Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
3c5e864
docs(proposals): measured additions — startup rule, implicit id, topi…
claude Nov 18, 2026
d7bdfdc
docs(proposals): settle the two open design points — consume keyword,…
claude Nov 18, 2026
0a2ce06
check: refuse a mapping element whose association does not connect it…
claude Nov 18, 2026
be3df26
Merge pull request #2384 from ako/claude/busy-sagan-a0u4w0
ako Nov 18, 2026
9814647
Merge pull request #2385 from ako/fix/ce0295-from-catalog
ako Nov 18, 2026
fbc72e6
fix(businessevents): refuse a rewrite that would destroy a consumer's…
claude Nov 18, 2026
c6a0572
check: refuse a primitive where a list operation needs an object or a…
claude Nov 18, 2026
73cecec
check: refuse an alter that leaves a published OData attribute publis…
claude Nov 18, 2026
0f5cafa
Merge pull request #2386 from ako/fix/ce0023-from-catalog
ako Nov 18, 2026
c4666c2
Merge pull request #2387 from ako/claude/busy-sagan-a0u4w0
ako Nov 18, 2026
5d7041a
feat(businessevents): show the service kind and the channel id
claude Nov 18, 2026
b58ab7e
Merge origin/main into fix/ce5016-from-catalog
claude Nov 18, 2026
7ff725f
Merge pull request #2388 from ako/fix/ce5016-from-catalog
ako Nov 18, 2026
eb9085b
Merge pull request #2389 from ako/claude/busy-sagan-a0u4w0
ako Nov 18, 2026
47081e5
check: refuse a REST call that returns a list from an object-rooted m…
claude Nov 18, 2026
397e088
Merge remote-tracking branch 'origin/main' into fix/ce0243-from-catalog
claude Nov 18, 2026
8b37e3d
Merge pull request #2390 from ako/fix/ce0243-from-catalog
ako Nov 18, 2026
4dca15f
Merge branch 'mendixlabs:main' into main
ako Nov 18, 2026
2e4bf5a
feat(businessevents): author a consumed service from its AsyncAPI con…
claude Nov 18, 2026
43b997f
Merge pull request #2391 from ako/claude/busy-sagan-a0u4w0
ako Nov 18, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"area":"mdl/executor","date":"2026-11-18","symptom":"`create or modify business event service` over a CONSUMED service (Mendix 11: same BusinessEvents$BusinessEventService document, told apart by `Definition: null` + the producer's AsyncAPI contract in `Document`) dropped `Document` (2696 chars -> \"\") and `OperationImplementations[].Microflow`, and invented a Definition. `check --references` passed and exec reported `Modified business event service`. Separately, `describe` of such a service printed only the bare header `create or modify business event service M.X` — no property list, no body, no `;` — because the whole statement sits inside `if found.Definition != nil`, so exec of describe output failed with `mismatched input '<EOF>' expecting '('`.","cause":"createBusinessEventService builds a published service unconditionally: svc.Document is never set (businessEventServiceToGen does not write it either) and `svc.Definition = def` always runs, so a consumer is rewritten into a publisher shape. The handler loss is a different mechanism — MDL has had `MICROFLOW qualifiedName` on the businessEventMessageDef rule all along, so a statement omitting it is a partial statement whose unstated value the rebuild wrote as \"\"; businessEventIdentityCarry carried the operation $ID but nothing else off the stored op.","file":"mdl/executor/cmd_businessevents.go (guard in createBusinessEventService; operationID -> operationFor; describeConsumedBusinessEventService; microflow in describeBusinessEventService)","fix":"Guard-don't-drop (ADR-0005): refuse the statement when the stored service has a non-empty Document, naming the byte count and pointing at describe and drop. Carry the stored Microflow when the statement is silent, the way carriedDocumentation does (#1018). describe emits `microflow X` for an operation that has one, and describes a consumer as MDL comments — subscriptions plus the contract verbatim — which parses and holds no statement to re-run.","test":"mdl/executor/cmd_businessevents_consumer_test.go: _RefusesClobberingStoredContract, _PublisherRewriteStillAllowed (control), _CarriesStoredHandlerMicroflow (+ authored-wins control), _ConsumerDescribesAsParseableComments (both describe languages; asserts NO create statement is emitted), _EmitsHandlerMicroflow. Pre-fix run: all four positives failed with the reported symptoms, the publisher control passed. End-to-end on ako/TestApp 619864b: the refused exec left the unit byte-identical to pristine (Document 2696, Microflow intact) and the publisher still round-trips to `Unchanged`.","insight":"Two documents sharing one $Type is the trap: every `found.Definition != nil` and every unconditional `svc.Definition = def` is a place where one role's code silently handles the other. Grep for the discriminator, not for the document type. The handler microflow looked like a missing MDL spelling and was not — check the grammar before designing a feature, because `MICROFLOW qualifiedName` was already on the rule and the real defect was a one-line carry. A describe that emits a statement its own executor would refuse is worse than one that emits none: comments parse, carry everything, and cannot be re-run into the bug. Do not reach for a Document carry instead of the guard — carrying it would produce a Document+Definition hybrid Studio Pro never writes.","refs":["ako/mxcli#2381","ako/mxcli#2384","docs-wiki/bug-patterns/rewrite-drops-unauthored-state.md","docs-wiki/bug-patterns/describe-round-trip-gaps.md"]}
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"area": "mdl/executor", "date": "2026-11-18", "refs": ["ako/mxcli#1258"], "ce": ["CE0023"], "symptom": "`$R = UNION $L WITH $S` (and INTERSECT, SUBTRACT, EQUALS, `CONTAINS $S IN $L`) with a primitive variable as the operand that is not the list passed `check` and `exec`, and the build reported CE0023 \"Selected variable 'S' must be of type Object or List.\" The same shape with an Object or List operand built clean.", "file": "mdl/executor/validate_list_operand_kinds.go checkListOperandKinds (MDL101), called from validate_microflow.go and validate_nanoflow.go after the primitive kinds are seeded. Tests: validate_list_operand_kinds_test.go; fixtures mdl-examples/bug-tests/list-operand-primitive(.fail).mdl", "cause": "The only CE0023 findings were the `contains` String overload (ledger #53), which the builder rewrites into a Change Variable; nothing judged the operand type of a list operation that really is one. The validators already had the kind of every parameter and declare (varKinds) and used it for MDL063 and the numeric-assignment rules, but not here.", "insight": "**When a code is in the field-hit list only because of an overload workaround, measure the general shape the workaround stands next to: the operand-type matrix was cheaper than guessing the boundary.** One project, one flow per case, `mx check -j` read per document (the `locations[].document-name` field, not the error object): 42 first-and-second-operand cases, then 25 more over Boolean, Decimal, DateTime, Long and enumeration. Result: for UNION, INTERSECT, SUBTRACT, EQUALS and CONTAINS the second operand being any primitive is CE0023 (7 types x 5 operations = 35 of 35, nanoflows the same), an Object or List there is clean (`union $L with $O` builds), a wrong FIRST operand is CE0097 and COUNT/SUM over a non-list is CE0013 (both left for their own rules; `range $S limit 2` was clean). Staging did not interfere because every flow was its own document. Visitor mapping to remember: `SUBTRACT $A FROM $B` and `CONTAINS $A IN $B` store the LIST in InputVariable and the other operand in SecondVariable. An enumeration parameter `LO.Color` is indistinguishable from an object at parse time, so it is silent (5 of 63 measured cases, listed in the PR); a declared `enum` variable is judged. Sweep: 1,317 repo .mdl files, 0 MDL101 hits. Control: stubbing the check fails 60 sub-tests; the String `contains` function still passes."}
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"area": "mdl/executor", "date": "2026-11-18", "refs": ["ako/mxcli#1258"], "ce": ["CE0295"], "symptom": "An import or export mapping element `Assoc/Entity` whose association did not connect the entity above it to its own entity passed `check` and `exec` and was written; `mx check` then reported CE0295 \"Association '...' is not allowed\". Neither-end, parent-only and element-only associations were all rejected; the matching pair, and an end that is a generalization of the parent, the element's entity or both, built clean.", "file": "mdl/executor/validate_mapping_associations.go ValidateMappingAssociations (MDL100), called from validate_program.go with the lazy project opener. Tests: validate_mapping_associations_test.go; fixtures mdl-examples/bug-tests/mapping-association-not-allowed(.fail).mdl", "cause": "The export and import mapping builders resolve nothing about an element's association beyond qualifying its name; the message-definition path already refuses an association that connects neither direction (resolveAssociationCardinality), but the mapping builders never got that check. The four existing CE0295 findings were all the same mxcli-written array-container bug, so the rule for hand-written mappings was never recorded.", "insight": "**When the field-hit ranking shows a code only in findings about mxcli's own writer, the user-script form of the same error is probably unrefused: measure the hand-written shapes before assuming the writer fix covered it.** Measured on MxBuild 11.16.1 in separate project copies (export and import, one defect per copy plus a control): neither end, parent-only and element-only are CE0295; the plain pair is clean; specialization of the parent, the element or both is clean. My first control was wrong - an object element over a plain many-to-one Reference is also CE0295 (the association must reach at most one object; the repo's own example uses owner both) - which is a separate cardinality rule left uncovered, and the reason to run a control before trusting it. The resolver reuses associationCatalogFor and findEntityByQN, keeps the spelling the names were written in for project lookups (lower-casing them made the chain read as unreadable and the rule silent), and refuses only when both generalization chains were read to their roots. Sweep: 1,314 repo .mdl files, 0 MDL100 hits (weak without a project; the measurement is the evidence). Control: stubbing the function fails the script, group, project and parent-specialization tests."}
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"area": "mdl/executor", "date": "2026-11-18", "refs": ["ako/mxcli#1258"], "ce": ["CE5016"], "symptom": "`alter entity M.E modify attribute A: <other EDM type>` on an attribute a published OData service exposes passed `check` and `exec`; `mx check` then reported one CE5016 \"Attribute 'A' has type …, but is published as …\" per attribute. Measured: String to Integer, Decimal to Integer, Boolean to String, DateTime to String, String to Decimal. String(50) to String(80) was clean.", "file": "mdl/executor/validate_published_attribute_types.go ValidatePublishedAttributeTypes (MDL102), called from validate_program.go with the lazy project opener. Tests: validate_published_attribute_types_test.go; fixtures mdl-examples/bug-tests/published-attribute-type-change(.fail).mdl", "cause": "The publisher derives each attribute's EdmType once, when the service is written (mendixAttrTypeToEdm, adjudicated on 11.12.1), and nothing revisits it when the attribute's type later changes. The six earlier CE5016 findings were all that derivation being wrong; this is the derivation going stale.", "insight": "**When a derived value is stored beside its source, the gap is the edit that changes the source later, and the order of statements in a script decides whether it is a defect.** Measured on MxBuild 11.16.1 in copies of one project that started at 0 errors: `alter` then `create or modify published odata service` is 0 errors (the re-publish re-derives every type); the same two statements the other way round is CE5016. So the rule follows the script in order and clears when a later statement re-publishes, alters or drops the service, and stays silent when it cannot prove staleness. The first version passed its own tests and still missed the re-publish-then-alter case over a PROJECT entity, because the script never declared the attribute so its type was unknown and the entry was dropped: the end-to-end run against the measured scripts found it (9 scripts, all agree after the project-type fallback), the unit tests did not. Enum parameters, `rename attribute` and `drop attribute` (a different CE) are not covered. Sweep: 1,317 repo .mdl files, 0 MDL102 hits. Control: stubbing the check fails the script and project tests; stubbing only the project-type fallback fails the re-publish-then-alter test."}
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"area": "mdl/executor", "date": "2026-11-18", "refs": ["ako/mxcli#1258"], "ce": ["CE0243"], "symptom": "`$R = call rest service get $Url (…) returns mapping M.IMM as list of M.E` over an import mapping whose root is one object passed `check` and `exec`; `mx check` reported CE0243 \"The mapping used to return a value of type 'List of M.E', but now returns a value of type 'M.E'\". The other five combinations built clean.", "file": "mdl/executor/validate_rest_mapping_result.go ValidateRestMappingResult (MDL103), called from validate_program.go next to ValidateImportMappingRange; shape from newMappingShapeResolver. Tests: validate_rest_mapping_result_test.go; fixtures mdl-examples/bug-tests/rest-mapping-list-of-object-root(.fail).mdl", "cause": "The REST call is the one place the author states the result's cardinality themselves (`import from mapping` infers it from the mapping), so it is the one place it can disagree with the mapping's root. The four earlier CE0243 findings were all the builder INFERRING that cardinality wrongly, so the hand-written disagreement was never recorded.", "insight": "**When the field-hit records for a code are all the writer's own inference going wrong, look for the one construct where the author states the value instead of the tool inferring it: that is where a script can disagree.** Measured on MxBuild 11.16.1, one microflow per case over 3 mapping roots x 2 declared results: object-rooted `as E` clean, object-rooted `as list of E` CE0243, array-rooted either clean, a root below an array either clean. Binding ONE object out of a list is a real Studio Pro pattern (PrivateCloudData.REST_GetEnvironmentByUUID), so `as E` is never judged. The shape resolver and its conservative unknowns (root path, XML, message definition, no project) already existed for MDL-MAP04, so this rule is a second consumer, not a second resolver. A first end-to-end run against a project that already held my own flows reported a reference error on every case; a project holding only the mappings gave the clean comparison, so build the comparison project from the dependencies only. Sweep: 1,322 repo .mdl files, 0 MDL103 hits. Control: stubbing the rule fails the 4 sub-tests that expect a violation; the 6-flow comparison agrees with mx check on all six."}
67 changes: 56 additions & 11 deletions .claude/skills/mendix/business-events/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,12 @@ description: "Define event-driven APIs over Kafka with Mendix business event ser
| lines | section |
|---|---|
| 24-31 | When to Use This Skill |
| 32-101 | Commands |
| 102-117 | Message Definition Syntax |
| 118-125 | Service Properties |
| 126-132 | Operations |
| 133-179 | Publishing Events from Microflows |
| 180-192 | Checklist |
| 32-146 | Commands |
| 147-162 | Message Definition Syntax |
| 163-170 | Service Properties |
| 171-177 | Operations |
| 178-224 | Publishing Events from Microflows |
| 225-237 | Checklist |

<!-- /skill-index -->
# Business Events
Expand Down Expand Up @@ -49,10 +49,49 @@ list business events;
-- Filter messages by module
list business events in MyModule;

-- Full MDL description (round-trippable)
-- Full MDL description (round-trippable for a PUBLISHED service)
describe business event service Module.ServiceName;
```

`list business event services` has a **Kind** column: `published` (a definition of its
own) or `consumed` (no definition, the producer's AsyncAPI contract cached instead). A
consumed service shows 0 messages because its messages live in the contract, not in a
definition — the kind is what makes that legible. `list business events` lists both
roles' events with the **Channel** the broker derives the topic from.

### Author a Consumed Service

A **consumed** service stores the producing app's AsyncAPI contract instead of a
definition of its own, and binds events from it:

```sql
mdl 1;
create or modify business event service Module.OrdersEventClient
(
ContractFile: 'contracts/OrdersEventService.yaml' -- or Contract: $$<yaml>$$
)
{
consume OrderPlaceEvent
entity Module.CBE_OrderPlaceEvent
microflow Module.HandleBE_OrderPlaceEvent;
};
```

- Exactly one of `Contract:` / `ContractFile:`, and neither may be mixed with
`ServiceName`, `EventNamePrefix` or `message` — those are the published shape.
- `ContractFile` is read when the script runs and stored **verbatim**, so nothing later
depends on the file. `describe` prints the `Contract:` form, which re-executes anywhere.
- It is `consume`, not `subscribe`: `message X (…) subscribe` already means "this app
consumes X of its *own* definition". The stored `Operation` is `"subscribe"` either
way; only the keyword differs.
- The consumed entity (`CBE_…`, extending `BusinessEvents.ConsumedBusinessEvent`) and the
handler microflow are ordinary MDL, declared before the service.
- A service whose contract contains `$$` cannot be described inline — `$$…$$` has no
escape — so `describe` falls back to comments and tells you to use `ContractFile`.

A published-shaped statement over a stored contract is still refused rather than allowed
to destroy it (ako/mxcli#2381).

### Create a Business Event Service

```sql
Expand All @@ -74,10 +113,16 @@ create business event service Module.CustomerEventsApi

Preserves the existing UUID so other documents that reference this service remain valid.
`OR REPLACE` is accepted as a synonym. Each message keeps its stored channel — the
channel name is the Kafka topic subscribers listen on — matched by message name, so a
re-run of an unchanged script reports `Unchanged`; only a new message gets a new
(random) channel name. Renaming a message is a new channel. There is no MDL property to
state a channel name, so two apps defining "the same" service get different topics.
channel name is what the broker derives the Kafka topic from
(`businessevents.<channel id>.<space>`) — matched by message name, so a re-run of an
unchanged script reports `Unchanged`; only a new message gets a new (random) channel
name. Renaming a message is a new channel.

There is no MDL property to state a channel name, and that is correct: the producing app
mints the id, and it reaches a consumer **inside the exported AsyncAPI contract**, not by
both apps spelling the same string. Read it with `list business events` (Channel column)
or `show contract channels from Module.Service`, which works on a publisher as well as a
consumer.

```sql
mdl 1;
Expand Down
27 changes: 16 additions & 11 deletions .claude/skills/mendix/json-structures-and-mappings/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,17 +13,17 @@ description: "Create and manage JSON structures, import mappings and export mapp
| 33-110 | Key Concepts |
| 111-122 | Export Mappings |
| 123-187 | JSON Structures |
| 188-229 | Message Definitions |
| 230-393 | Import Mappings |
| 394-491 | Export Mappings |
| 492-509 | Starting a Mapping Below the Payload Root |
| 510-593 | Microflow Actions |
| 594-606 | Browse |
| 607-654 | Export Workflow: PE → NPE → JSON |
| 655-661 | Realistic Example: Countries REST API |
| 662-685 | Placing Documents in Folders |
| 686-701 | Documentation |
| 702-716 | Common Mistakes |
| 188-234 | Message Definitions |
| 235-398 | Import Mappings |
| 399-496 | Export Mappings |
| 497-514 | Starting a Mapping Below the Payload Root |
| 515-598 | Microflow Actions |
| 599-611 | Browse |
| 612-659 | Export Workflow: PE → NPE → JSON |
| 660-666 | Realistic Example: Countries REST API |
| 667-690 | Placing Documents in Folders |
| 691-706 | Documentation |
| 707-721 | Common Mistakes |

<!-- /skill-index -->
# JSON Structures, Import Mappings & Export Mappings
Expand Down Expand Up @@ -206,6 +206,11 @@ target entity** — the stored cardinality follows the direction of traversal an
the association's type, so a `Reference` gives a single object one way and a list
the other, while a `ReferenceSet` is a list both ways.

The association must also connect the entity the element sits under to the element's
own entity (either direction; a generalization of either is fine). Any other one is
CE0295 "Association '...' is not allowed"; `check` refuses it as MDL100, in import and
export mappings alike.

**Mendix 11.15 removed collections.** Each definition is its own document, and
a mapping names it in two parts. The collection form is refused on 11.15, and
the document form below 11.15:
Expand Down
Loading
Loading