fix(intent): a voided target no longer blocks its replacement (#6814)

[delchev]

Closes #6814.

The problem

The event-driven create-from's at-most-once guard queries row existence only — findAll(eq(backRef, sourceId)), no state — and a voided target answers yes forever: it keeps existing and keeps back-referencing the source. The source's one-shot slot is spent at the first creation and nothing that later happens to the target releases it:

1. An event mints Invoice INV-001 from Timesheet 12.
2. INV-001 is wrong; the transitions: Void moves it to VOIDED. It still exists, still references Timesheet 12.
3. The source re-qualifies (or the shared button is clicked): the guard finds VOIDED INV-001 and returns it. The UI toasts the voided document; no replacement is ever created.

"Void and reissue" — a document retired while keeping its number, a fresh one raised — was inexpressible for an event-driven create-from, and the failure was silent (a 200 carrying the retired document).

The fix — reuse the classification, add no key

What a status MEANS is already declared once, where the nomenclature is seeded: the stage: classification a report's scope: resolves through (#6645). The guard now reads it.

seeds:
  - name: declaration-states
    entity: DeclarationState
    rows:
      - { id: 1, name: DRAFT,     stage: draft }
      - { id: 2, name: FILED,     stage: live }
      - { id: 3, name: CANCELLED, stage: cancelled }   # a target in either of these
      - { id: 4, name: VOIDED,    stage: void }        # no longer blocks its source

• A target classified cancelled or void is retired: the guard steps over it, so the next qualifying event — or a click — mints a replacement. The retired document is kept, never edited or re-pointed; both stay on the audit trail.
• A draft or live target still blocks, so redelivery idempotence is untouched: a redelivered event finds the document it created.

The alternative — a supersedeWhen: key on the rule — was rejected: two vocabularies for "this row no longer counts" could only drift, and an author who has already classified their statuses should not repeat it per rule. mode: append (#6800) is not this fix and could be misread as one — it is the absence of a guard, so it would also mint a document on every later qualifying event.

Emission

GlueIntentGenerator.putSupersededTarget pre-renders hasRetiredStatus / retiredStatusProperty / retiredStatusCondition (the template stays shape-only); Generate.java.template turns

if (!existing.isEmpty()) { return existing.get(0); }

into

for (VoucherEntity candidate : existing) {
    if (candidate.Status == null || !(candidate.Status == 3)) {
        return candidate;
    }
}

Gated on the boolean, so a .glue written before this key existed keeps the existence-only guard it always had, and a model that adopts no stage: regenerates byte-identical output.

What is deliberately left alone

• No lifecycle on the target → existence-only guard, silently: nothing can retire that document.
• A lifecycle nobody classified → existence-only guard plus a generation warning. That is the silent combination the issue is about — the guard reads as state-aware and is not — so Generate names the create-from, the nomenclature and the key to classify it with.
• A cross-model target is seeded in its owner model, so no classification is resolvable at the consumer; same limit scope: has.
• posts: keeps its own guard: a register row has no lifecycle of its own, and a bad post is unwound by postings:' reverses:/storno: compensation.

Tests

• GlueGeneratesTest — the classified case (both retiring stages, in seed order, and not the draft/live ones), the unclassified case (existence-only + the warning naming the create-from, the nomenclature and stage:), and the no-lifecycle case (neither retires nor warns).
• IntentEmissionCoverageIT — classifies its shared EntryStatus nomenclature and asserts both layers: the emitted guard steps over a cancelled candidate, and at runtime the voucher the slip's transition minted is voided through a new VoidVoucher transition, after which generating from the same slip mints a second voucher while the voided one is kept.
• Green locally: IntentEmissionCoverageIT, IntentEngineIT (50), ModelGenerationIT, the whole engine-intent unit suite (694), formatter:validate, javadoc under -P release.

Docs: dirigible.io PR and the intentfile specification proposal + site PR are open alongside.

🤖 Generated with Claude Code