feat(intent): a retired target returns its source, so an event-driven reissue can fire

[delchev]

What does this PR do?

#6850 made the event-driven create-from's at-most-once guard state-aware: a target retired into a cancelled/void stage is stepped over, so the source's one-shot slot is freed. For the sourceStatus: combination it half-delivered — the door is unlocked and nobody can knock.

The completion hook moves the source off the status its own trigger qualifies on. That is deliberate: it is how the guard-claimed source stops matching. But the usual lifecycle graph declares no edge back, so after voiding the target:

• the guard correctly steps over the retired document — the slot is FREE;
• the source sits at its post-generation status and re-emits no qualifying -transitioned;
• only a shared button: true can reissue. An event-only rule (button: false, the shape intent: event-driven generates - create a document from a source document on an entity event, not only a button #6711 introduced the axis for) has no reissue path at all.

This takes the second direction the issue weighed — a declared reopen — because it is explicit in the model, uses only existing vocabulary, and makes the reissue the ordinary path rather than a second creation route:

generates:
  - name: invoice-from-proforma
    from: Proforma
    to: Invoice
    event: { onTransition: Proforma, when: "Status == APPROVED" }
    map: { Proforma: id }
    sourceStatus: INVOICED           # forward: the proforma is done once the invoice exists
    sourceStatusOnRetire: APPROVED   # back: voiding the invoice returns it - and the trigger re-fires

Retiring the invoice returns the proforma to APPROVED. That is a real lifecycle move of the proforma, announced on its own -transitioned channel, so the trigger re-fires, the guard steps over the retired invoice, and the replacement is minted by machinery that already existed. The retired document is kept, never edited or re-pointed.

Emission

GlueIntentGenerator.putSupersededTarget pre-renders hasReopen / reopenStatusValue / reopenRetiredCondition from the same retiring-stage: resolution the guard uses — the guard asks whether the target that exists is retired, the reopen asks whether the transition it just saw is what retired it, and one resolution is what stops them drifting. GenerateReopen.java.template (collection generateReopens, the same filtered descriptors and the same bindGenerate as generates/generateEvents) renders a MessageHandler on the target's -transitioned topic that flips the source with

sourceRepository.updateProperties(target.Proforma, java.util.Map.of("Status", 2),
        "<project>-Proforma-Proforma-transitioned");

— the notice riding the write into the outbox exactly as transitions: does, so the flip and its announcement commit together and <X>GenerateOnEvent cannot miss the moment that frees it.

Idempotence is by state, with no marker column

Two conditions carry it:

• the source must still stand at this rule's sourceStatus, so a source that has moved on down its own lifecycle is never overruled; and
• no target of that source may still count.

The second is the half that closes redelivery, and it is worth spelling out because the first alone looks sufficient and is not. A retirement is delivered at-least-once, so a void can arrive again after the reissue — and by then the source is standing at sourceStatus once more, because the reissue put it there. Without the free-slot scan the reopen would return a source that already has a live target against it, and create() would then return at its own guard, so nothing would ever put the status back. With it, the reopen runs exactly when a creation would be allowed through.

Refused where it could never fire

validateGeneratesReopen rejects, at parse: no sourceStatus (nothing to invert), the same status (a write that changes nothing announces nothing), mode: append (no guard, so no slot), no event: (the emission is gated on event-driven, so a button-only reopen would be authored and silently dropped — and there the button is the reissue), a cross-model target (its stages are classified in the owner model, the same limit scope: has), a target with no lifecycle, an unclassified nomenclature.

And validateStatusWritesAgainstLifecycle pins the source's graph to the one edge sourceStatus → reopen, rather than to reachability: that is exactly where the source stands when the retirement arrives, so a missing edge is an authoring error instead of a runtime ValidationException.

Two decisions worth recording

• The directions not taken. Having the target's retirement re-deliver the source's qualifying event fabricates a transition nobody made — and since the source stands at the post-generation status it would not even match the trigger's guard without bypassing it — while re-firing every other consumer of that channel. Documenting-and-warning is honest but leaves the automation inexpressible.
• sourceStatus and sourceStatusOnRetire both join the sites StatusSymbolResolver rewrites, so both take a seeded NAME or an id. sourceStatus was id-only; leaving the pair asymmetric while documenting the inverse with names would have been a wart of its own. Numeric values pass through untouched.
• Not added to IntentEmissionCoverageIT's voucher-from-slip on purpose: that fixture's The event-driven create-from guard is existence-only - a voided target blocks its replacement forever #6814 test reissues by POSTing the endpoint, and an automatic reissue racing that POST could mint a third voucher and turn a green test flaky. The end-to-end coverage lives in IntentEngineIT instead.

Verification

• engine-intent 806/806 — ten new parser cases (every rejection parses silently without the validator, which is the reported defect) and two new glue cases (the emitted inverse, and byte-identical output without the key).
• IntentEngineIT 58/58, IntentEmissionCoverageIT 1/1, ModelGenerationIT 1/1 — the last two matter most, since the change touches the shared putSupersededTarget and bindGenerate paths every create-from renders through.
• mvn formatter:validate clean; mvn -P release javadoc clean on both changed modules.
• The local PR-gate smoke run deadlocked rather than failed, in DatabasePerspectiveIT's @DirtiesContext teardown: main and FileSystemWatcher in a two-thread lock cycle over PollingWatchService's key/HashMap pair. That is The registry watcher's shutdown deadlock is back (#6437 fixed the wrong half) - every @DirtiesContext IT class wedges on macOS #6856, macOS-only (CI uses inotify), unrelated to this change — the six UI classes that ran before it all passed. CI is the authority for that slice.

What issues does this PR fix or reference?

• Closes intent: with sourceStatus:, a voided target frees the one-shot slot but nothing can re-fire the event-driven create-from #6868
• Follow-up to fix(intent): a voided target no longer blocks its replacement (#6814) #6850 (The event-driven create-from guard is existence-only - a voided target blocks its replacement forever #6814); composes with fix(intent): two event-driven rules can no longer share one at-most-once guard #6859's guard-ownership rule (one rule owns the slot either way)

Release Notes

An event-driven create-from that flips its source's status once the target exists could not be reissued automatically: voiding the target freed the source's slot, but the source could never re-qualify, so nothing fired into it and only a button could raise the replacement. A create-from may now declare sourceStatusOnRetire: — the status its source returns to when the target is retired — so void-and-reissue completes by itself.

Documentation

intent-assistant-guide.md, components/engine/engine-intent/README.md and components/engine/engine-intent/CLAUDE.md are updated in this PR (the DSL reference lives in-tree). Doc sites: dirigible-io/dirigible-io.github.io#211 and, vendor-neutral, IntentFile/intent-specification#48 (proposal 0025) + IntentFile/intentfile.github.io#38.

[delchev]

One coverage gap worth stating rather than leaving implicit.

GenerateReopen.java.template is the one event template with no fixture that compiles its output. The others get that for free from IntentEmissionCoverageIT, which publishes its project so the client-Java compiler runs over every generated file; I deliberately kept the reopen out of that fixture, because its #6814 block reissues by POSTing the create-from endpoint and an automatic reissue racing that POST could mint a third voucher and turn a green test flaky.

So I verified the rendered listener by hand instead: dumped the generated source from the IntentEngineIT run and ran javac over it. All 28 diagnostics are resolution-only — package gen… does not exist, cannot find symbol, and the knock-on does not override or implement a method from a supertype — and none syntactic, i.e. javac parsed the whole file. That establishes the template renders parseable Java, which nothing in the suite did before; it does not establish that it type-checks against the real SDK.

The residual risk is low, since every symbol the listener uses appears in the same position in an already-compiled sibling template (Criteria.create().eq, findById, updateProperties(id, Map, topic), MessageHandler / ListenerKind). But the honest fix is a fixture that compiles it, and it needs a source/target pair not entangled with the #6814 flow — a small addition to the emission fixture rather than a change to voucher-from-slip. Happy to add that here if you would rather not merge without it; otherwise I will file it as a follow-up.

Separately, for the record: the local PR-gate smoke run deadlocked rather than failed, in DatabasePerspectiveIT's @DirtiesContext teardown — main blocked in PollingWatchService$PollingWatchKey.disable holding the service's HashMap, FileSystemWatcher holding the key and waiting for that map. A genuine two-thread cycle, i.e. #6856, macOS-only (CI uses inotify). The six UI classes that ran before it passed, and this PR's own coverage (IntentEngineIT 58/58, IntentEmissionCoverageIT, ModelGenerationIT, engine-intent 806/806) was run separately and is green.