feat(intent): a create-from may be triggered by a source event, not only a button (#6711)

[delchev]

Closes #6711.

The gap

generates: (create-from) was strictly a user action — a button on the source view. "When the source reaches this state, mint the follow-up document" had no expression. The motivating case: a fine arrives through an inbound: webhook, and once its responsible person is identified (a status transition), a declaration document must be created from the fine and that person. Everything that could express it was wrong in a specific way:

• a generates button plus a process wait step — the automation degrades to a person remembering to click, and an unclicked record parks its process instance forever;
• posts — event-driven and idempotent, but it emits flat mapped rows and cannot mint a header-and-items document (the rows need the id of the header it would have to create first);
• a hand-written delegate in custom/.

What this adds

generates:
  - name: declaration-from-fine
    from: Fine
    to: Declaration
    event: { onTransition: Fine, when: "Status == IDENTIFIED" }   # or { onCreate: Fine }
    map:
      Fine: id                       # REQUIRED with an event — the back-reference, i.e. the guard
      Vehicle: Vehicle
    defaults: { declaredAt: now }
    items:                           # a whole document — header AND items
      - { name: "Fine {number}", amount: Amount }

onTransition binds the source's -transitioned topic with a mandatory status guard (named or numbered); onCreate binds its create topic for a source with no lifecycle, guard optional — postings' event axis, applied to a whole document.

The event says WHEN, never what. The entity it names must be the one from: declares, and model: is rejected because fromUses: owns that. Both are parser-checked: two ways to name one source can only drift apart.

At-most-once is derived, not declared twice. The map entry copying the source's key is the target's back-reference, so the glue derives the guard from it — and a declaration without one fails loudly (at parse locally, with the fix in the message; at generation for a cross-model source, where the owner's key field first resolves). Without it an event redelivery mints a duplicate document. A create-from with no event keeps no guard at all: producing several targets from one source by clicking twice is a legitimate manual act, and that behaviour is unchanged.

One creation path for both triggers. Generate.java.template's body became a create(Integer sourceId) method that carries the guard, and the new GenerateOnEvent.java.template renders a MessageHandler which re-reads the source (the payload is as-of the event and lacks anything a later step wrote), applies the status guard, and calls that method. It carries no mapping of its own — that is what keeps a button and an event from diverging. The listener is its own glue collection (generateEvents, the filtered generates list — one file per entry is the collection contract, and an event-less create-from must contribute no listener) sharing one binder with generates.

button: is true by default without an event and false with one (declaring an event is how an author says nobody has to click); button: true keeps both, and button: false with no event is rejected — the action would have no trigger at all. With no button the generated class gets no @Controller/@Post, no custom-action descriptor and no i18n label: no endpoint nothing links to.

Backward compatibility. The template gates the controller half on the negative (#if(!$eventOnly)), so regenerating code from a .glue written before this key existed still renders the endpoint it always did.

Verification

• GeneratesIntentTest — the six validation rules (wrong source entity, repeated model, unguarded onTransition, missing back-reference, button: false with no event, and the happy shape dropping its button).
• GlueGeneratesTest — trigger kind, guard property/value from a named status, the derived back-reference, and the loud cross-model failure.
• ModelGenerationIT — its glue fixture gained an event-driven entry plus the generateEvents collection, so the new listener is rendered and checked for surviving ${…} references (the failure mode fix(generation): the glue templates get every reference they render #6723 paid for; the fixture's other two entries deliberately keep the old key set).
• IntentEmissionCoverageIT — both layers. Emission: the listener binds -Slip-transitioned, guards on the status the seeded name resolved to, delegates to new VoucherFromSlipGenerate().create(, and carries no mapping; the create-from keeps its endpoint (button: true) and gained the back-reference guard. Runtime: nobody calls the create-from — a slip is posted through its transition and the voucher has to appear by itself, with its computed line (so the whole create-from ran, not an empty header) — and a click afterwards returns that same voucher.
• IntentEngineIT 46/46 (two assertions updated for the renamed create(sourceId) parameter), engine-intent + ide-template unit tests 439/439, formatter:validate and the release-profile javadoc clean.

Documentation

• Specification: spec: event-driven creation - a create-from may run on a source event IntentFile/intent-specification#14 (left open for the maintainer) — removes the Planned entry that named this gap.
• intentfile.org: docs: event-driven creation - a create-from may run on a source event IntentFile/intentfile.github.io#14 (left open).
• dirigible.io: docs(intent): event-driven create-from - mint the document on a source event dirigible-io/dirigible-io.github.io#174.
• In-repo: the assistant guide (the contract the editor's AI is prompted against), the engine-intent guide and the root CLAUDE.md.

🤖 Generated with Claude Code