Skip to content

Sync ako/mxcli: a consumed business event service survives a rewrite; events listed by kind and channel; four more build errors caught by check - #1892

Merged
ako merged 20 commits into
mendixlabs:mainfrom
ako:main
Nov 18, 2026

Conversation

@ako

@ako ako commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator

Syncs ako/mxcli:main into upstream: 8 commits since #1891 — a consumed business event service is no longer destroyed by a rewrite, business events are listed by kind and channel, and check refuses four more things the build does.

Business events: a consumer survives a rewrite

In Mendix 11 a consumed business event service is the same BusinessEvents$BusinessEventService document as a published one, told apart by Definition: null plus the producer's AsyncAPI contract in Document, with a handler microflow on each operation. create or modify built a published service unconditionally, so over a consumer it dropped the contract and the handlers and invented a Definition, while check --references passed and exec reported success. The contract is the only record of the channel id a subscriber binds to, and nothing in the model can put it back.

  • A rewrite that would destroy a consumer's contract is refused, naming its size and pointing at describe and drop.
  • A handler microflow the statement doesn't state is carried, so a partial statement no longer unbinds it; describe now prints microflow.
  • describe of a consumer prints a complete statement instead of a header with no body (which exec then failed to parse).

Business events: kind and channel

  • list business event services gains a Kind column (published or consumed).
  • list business events gains a Channel column and now lists what an app consumes; it only walked published definitions, so every subscription was missing. The broker derives the topic from the channel id (businessevents.<channel id>.<space>), the value two apps have to agree on.
  • show contract channels|messages from <publisher> works on a publisher, not only a consumer.

The Kafka event integration proposal gains measured findings (the module is started by StartupBusinessEvents from the after-startup microflow, and omitting it fails silently with mx check clean; the topic naming; export) and settles two design points: the contract-based body item is consume <Message> entity … microflow …, and export is a CLI command.

check: refuse what the build refuses

Each with a bug-test script:

  • a REST call that returns a list from an object-rooted mapping (CE0243);
  • an alter that leaves a published OData attribute published as the wrong type (CE5016);
  • a primitive where a list operation needs an object or a list (CE0023);
  • a mapping element whose association doesn't connect it to its parent (CE0295)

claude and others added 20 commits November 18, 2026 04:27
…c naming, export

Findings measured against the fixture project (ako/TestApp 619864b, Mendix
11.16.1) and Studio Pro's editors, folded into the Kafka event proposal:

- §1: the Business Events module is started by StartupBusinessEvents from the
  after-startup microflow; nothing calls ConsumeBusinessEvent. The omission
  fails silently and mx check is clean, so §5.1 gains a "module started" rule.
  This answers §9.5, now marked as such.
- §1: topic is businessevents.<channel id>.<space>, with the ChannelName
  constant as a one-topic dev shortcut.
- §5.2: `id` is UI-only. Studio Pro lists it per entity, but the model stores
  five properties for Order and three for Customer. Authoring it would break
  CLAUDE.md rule 4.
- §5.2: the topic is cdc.<AppName>.<ExposedName>.<Major>.<space>, so a major
  bump starts a new topic — and RENAME ENTITY reaches the same outcome via
  CE1585. Both now stated next to the version policy.
- §5.4: the consumer clobber is measured (#2381), with the publisher
  round-tripping to Unchanged as the control; and a publisher's channel id
  cannot be read, although it is the topic name.
- §5.5 (new, part E): export a published service's contract. Studio Pro exports
  all three published types; four of five OData artifacts are fetched from a
  running app, AsyncAPI and the GraphQL schema are rendered.
  ODataPublish$PublishedContract is in the metamodel but not populated.
- §5.1: `subscribe` now has two meanings; flagged for a decision.
- §8: tests for each of the above, each with its control.
- §9: a local Kafka broker retires item 5 and gives §8 a runtime check, but not
  items 1-4.

Docs only; no code changes.

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_011oK82qQLKUyoXXGmbmX68t
… export as CLI

Both decided by the maintainer in session:

- §5.1: the contract-based body item is `consume <Message> entity … microflow …`,
  not `subscribe`. `subscribe` already means "this app consumes a message of its
  own definition", and Studio Pro's publisher editor has both a Publish and a
  Subscribe table for exactly that, so reusing it would give two spellings that
  write the same ServiceOperation. `consume` matches the metamodel's own
  vocabulary (ConsumedBusinessEventService, ConsumedBusinessEvent, the CBE_
  entity prefix). Only the keyword changes: the stored Operation stays
  "subscribe", so no BSON changes.
  Lexing: a CONSUME token has to be added — the grammar has CONSUMED but not
  CONSUME — and longest-match keeps `consumed` on the existing token.
- §5.5: `export contract` is a CLI command, not an MDL statement.

Examples, the check-rule table and the B1 plan row updated to match.

Docs only; no code changes.

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_011oK82qQLKUyoXXGmbmX68t
docs(proposals): Kafka event integration — measured follow-ups to #2380
check: refuse a mapping element whose association does not connect it to its parent (CE0295)
… contract

In Mendix 11 a consumed business event service is the same
BusinessEvents$BusinessEventService document as a published one, told apart by
`Definition: null` plus the producer's AsyncAPI contract in `Document`, with a
handler microflow on each ServiceOperation.

createBusinessEventService builds a published service unconditionally: it never
sets svc.Document, and `svc.Definition = def` always runs. So `create or modify`
over a consumer dropped the contract (2696 chars -> "") and the handler, and
invented a Definition — while `check --references` passed and exec reported
"Modified business event service". The contract is the only record of the
channel id a subscriber binds to, and nothing in the model can put it back.

Guard, don't drop (ADR-0005): refuse the statement when the stored service has a
contract, naming the byte count and pointing at describe and drop. Carrying the
Document instead would produce a Document+Definition hybrid Studio Pro never
writes.

The handler loss was a separate mechanism. MDL has had `MICROFLOW qualifiedName`
on the businessEventMessageDef rule all along, so a statement omitting it is a
partial statement, not a request to unbind: the stored Microflow is now carried
when the statement is silent, the way carriedDocumentation does (#1018).

Read side, same issue:

- describe never printed `microflow`, so describe -> exec unbound the handler on
  a publisher-shaped service too.
- describe of a consumer emitted only the statement header — no property list,
  no body, no `;` — because the whole statement sits inside
  `if found.Definition != nil`, so exec of that output failed with
  "mismatched input '<EOF>' expecting '('". A consumer is now described as MDL
  comments: the subscriptions and the contract verbatim. It parses, and there is
  no statement to re-run into the bug. The early return is why the diff dedents
  the published branch.

Evidence: the four tests were written first and all failed with the reported
symptoms; _PublisherRewriteStillAllowed passed throughout, so the guard is not
refusing everything. 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" (ADR-0008 elision intact).

Closes #2381

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_011oK82qQLKUyoXXGmbmX68t
check: refuse a primitive where a list operation needs an object or a list (CE0023)
fix(businessevents): refuse a rewrite that would destroy a consumer's contract
Second slice of part A1 (#2384 §5.4). Both roles of
BusinessEvents$BusinessEventService were listed identically and the channel id
could not be read from a publisher at all, although it is the value the two apps
have to agree on: the broker derives the topic from it
(`businessevents.<channel id>.<space>`).

- `list business event services` gains a Kind column, published or consumed.
  Without it a consumer reads as a contradiction — 0 messages and 1 subscribe —
  because its messages live in the cached contract and never in a Definition.
  `mixed` and `empty` are named rather than guessed at: neither is a shape
  Studio Pro writes.

- `list business events` gains a Channel column, and now lists what an app
  CONSUMES. It only ever walked svc.Definition, so every subscription was
  silently absent: on the fixture project it reported 1 event where the two
  services handle 2. A consumer's rows take their channel and payload property
  count from the cached contract; a contract that is absent or unparseable
  leaves those blank rather than hiding the subscription.

- `show contract channels|messages from <publisher>` works. It refused with "no
  cached AsyncAPI contract … (it may be a publisher, not a consumer)" because it
  only read Document, while a publisher keeps its channels in Definition.
  contractFromDefinition projects what is stored — it is not the AsyncAPI
  renderer (#2384 part E): OperationID is left empty, because a publisher stores
  none and Studio Pro mints it at export time. A service with neither contract
  nor definition still refuses, naming which is missing.

On the fixture both sides now show the same channel id
f2477dc90f714d69bb12df0df1ee9cce, so the publisher/subscriber join is readable
from one command.

The business-events skill is corrected too: it claimed "there is no MDL property
to state a channel name, so two apps defining the same service get different
topics". The premise is right and the conclusion wrong — the producing app mints
the id and it reaches a consumer inside the exported contract, not by both apps
spelling the same string.

Controls: each of the three behaviours stubbed in turn, and the matching test
fails with the reported symptom (Kind blank, consumer's subscription missing,
publisher refused).

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_011oK82qQLKUyoXXGmbmX68t
check: refuse an alter that leaves a published OData attribute published as the wrong type (CE5016)
feat(businessevents): show the service kind and the channel id
check: refuse a REST call that returns a list from an object-rooted mapping (CE0243)
…tract

Part B of #2384, first slice. A consumed business event service — the same
BusinessEvents$BusinessEventService document as a published one, but storing the
producer's contract instead of a definition of its own — can now be written from
MDL:

    create or modify business event service BusinessEventsClient.OrdersEventClient
    ( ContractFile: 'contract.yaml' )     -- or Contract: $$<asyncapi yaml>$$
    {
      consume OrderPlaceEvent
        entity BusinessEventsClient.CBE_OrderPlaceEvent
        microflow BusinessEventsClient.HandleBE_OrderPlaceEvent;
    };

Run against the Studio Pro-authored consumer in ako/TestApp 619864b that reports
**Unchanged**: the statement reproduces the stored document byte for byte, so
ADR-0008 elision fires and nothing is written. That is the evidence the write
path emits Studio Pro's shape rather than merely something `check` accepts.
describe -> exec -> describe is a fixed point.

- Grammar: a CONSUME token distinct from the existing CONSUMED (longest match
  keeps `consumed` on the latter); a `consume <Message> entity … microflow …`
  body item alongside `message …`; DOLLAR_STRING accepted as an odata property
  value, gated per key by the strict-property schema rather than by the parser.
- AST/visitor: Contract, ContractFile, ContractSet, Consumes, and the R11
  exclusivity rules — the two shapes write different documents, so a mixed
  statement is refused by name rather than half-applied.
- Write: Document carries a value (canon completes the key on both roles, but
  only an explicit write carries the text); a consumer has no Definition, which
  is what tells the roles apart in storage; a shared write tail gives it the same
  folder and Created/Modified handling as a publisher.
- ContractFile is read at exec time and stored verbatim, so nothing later depends
  on the file. An empty or missing one is an error: mxbuild throws "business
  events service should have definitions" on a contractless consumer.
- describe emits the statement, with the contract inline. Two cases fall back to
  the comment form rather than emit something that cannot re-execute: no contract
  stored, and a contract containing `$$`, which ends the block early
  (`'$$' .*? '$$'` is non-greedy) with no escape available.

The #2381 guard changes with it, as the bug-patterns page says a guard must when
its construct becomes authorable: a contract-bearing statement is a restatement
and passes, while a published-shaped statement over a stored contract still
refuses. Both arms have a test — without the second, #2381 returns in silence.

One defect found by running the round trip rather than assuming it: describe
first printed `Contract: $$\n<contract>\n$$` for looks, and since
unquoteDollarString returns everything between the delimiters, the re-parsed
contract carried a leading newline the stored one did not. describe -> exec
reported Modified on an untouched service until the text was emitted byte-exact.

Controls: the consumer branch, ContractFile validation, the guard's lifecycle
change and R11 each stubbed in turn, with the matching tests failing on their own
symptoms.

Still open in part B: ContractFrom (needs the B2 renderer, shared with part E)
and the B4 check rules.

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_011oK82qQLKUyoXXGmbmX68t
feat(businessevents): author a consumed service from its AsyncAPI contract
@ako
ako merged commit d4f58a2 into mendixlabs:main Nov 18, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants