Skip to content

docs(intent): lifecycle stages, report scope, and statuses by name - #169

Merged
delchev merged 1 commit into
masterfrom
docs/intent-lifecycle-stages-scope
Aug 10, 2026
Merged

docs(intent): lifecycle stages, report scope, and statuses by name#169
delchev merged 1 commit into
masterfrom
docs/intent-lifecycle-stages-scope

Conversation

@delchev

@delchev delchev commented Aug 10, 2026

Copy link
Copy Markdown
Contributor

Documents the intent DSL additions from eclipse-dirigible/dirigible#6647 (issue eclipse-dirigible/dirigible#6645). The vendor-neutral specification wording is proposed separately as IntentFile/intent-specification#6.

The problem being documented: an aggregation over an entity that carries a function: EntityStatus counted drafts nobody had issued, cancelled documents and voided ones, unless the author remembered a status predicate in filter: — and nothing in the DSL, the generator or the editor said the report was incomplete without one. The report generated, the SQL was valid, the tile rendered a number, and the number was wrong.

/help/intent/dsl-reference

  • seeds → stage — the draft | live | cancelled | void vocabulary as a table, that it is metadata and never becomes a column (the CSV and imported table are unchanged), and the id / vocabulary / stage-property-collision rules.
  • seeds → Statuses by name, not by id — every site that accepts a seeded name, and why names are the better default: an id is positional, so inserting a status mid-nomenclature silently retargets every guard authored against the old numbering. The red-storno-vs-Void ledger case is named concretely, because "prefer names" is unconvincing without it.
  • reports → scope — the three shapes, the exact three conditions under which an unscoped aggregate defaults to live (and why a status dimension or an authored status filter stands it down), and a warning callout for the case that matters most: when the nomenclature is unclassified, the Generate warning is the omission's only signal — visible in the Intent Editor's notes strip, the Builder shell's publish panel, and the warnings field of POST /services/ide/intent/generate.
  • The transitions snippet now shows symbolic statuses; the cross-model boundary is listed under Planned.

npm run docs:build is clean and the three new anchors resolve (#stage-what-a-status-means-to-the-lifecycle, #statuses-by-name-not-by-id, #scope-which-lifecycle-rows-an-aggregate-counts), as do the cross-references between them.

An aggregate over an entity with a lifecycle counted drafts, cancellations and
voided documents unless the author remembered a magic-number status predicate,
and nothing said so. Document the three constructs that close it:

- seeds: `stage: draft|live|cancelled|void` classifies a status nomenclature -
  metadata, never a column - plus the id/vocabulary/collision rules.
- seeds: statuses may be referenced by their seeded NAME everywhere the intent
  names one, with the positional-id argument that makes names the better default.
- reports: `scope: all | <stage>`, the three conditions under which an unscoped
  aggregate defaults to live, and the Generate warning that fires when the
  nomenclature is unclassified (the omission's only signal).

Also: the transitions snippet now shows symbolic statuses, and the cross-model
boundary is listed under Planned.
@delchev
delchev merged commit 65a2d48 into master Aug 10, 2026
@delchev
delchev deleted the docs/intent-lifecycle-stages-scope branch August 10, 2026 09:31
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.

1 participant