@adhd/backlog 1.0.2 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhd/backlog",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "bin": {
     "adhd-backlog": "index.js"
   },

package/query/query.d.ts

@@ -47,6 +47,18 @@ export interface IQueryStoreHandle {
      * open) so a long-lived process notices a store rewritten under it.
      */
     readonly assertVocabulary?: () => Promise<void>;
+    /**
+     * Fail-loud status/priority catalog invariant guard
+     * (`store/catalog-invariant-guard.ts`). When present, `queryIssuesWithMeta`
+     * awaits it alongside {@link IQueryStoreHandle.assertVocabulary} before
+     * dispatching any view: a catalog carrying an unflagged reserved terminal
+     * status, or two same-kind rows sharing a case fold, must fail loudly rather
+     * than serve a mis-classified read. OPTIONAL so a hand-built handle (tests,
+     * the ETL) is unaffected — `api.ts`'s `queryHandle` wires it for every real
+     * host, and it is deliberately re-run per query (not latched at open), like
+     * the vocabulary guard.
+     */
+    readonly assertCatalogInvariants?: () => Promise<void>;
 }
 /**
  * Whether a `query` verb's own input touches the semantic channel at all —

package/store/catalog-invariant-guard.d.ts

@@ -0,0 +1,62 @@
+import { StoreAdapter } from '@adhd/sox-store-adapter';
+
+/**
+ * One way the catalog can violate an invariant. Carried as structured data on
+ * {@link CatalogInvariantError} so a caller (a diagnostic, a test) can act on
+ * the offending rows without parsing the rendered message.
+ */
+export type CatalogInvariantViolation = {
+    kind: 'unflagged-terminal';
+    /** The row's own name, verbatim. */
+    name: string;
+    /** The row's uid — the handle a reader uses to inspect or repair it. */
+    uid: string;
+} | {
+    kind: 'case-fragment-duplicate';
+    /** The case-folded name the rows collide on. */
+    fold: string;
+    /** Every colliding spelling, in rowid order (≥ 2). */
+    names: readonly string[];
+    /** The colliding rows' uids, aligned index-for-index with {@link names}. */
+    uids: readonly string[];
+};
+/**
+ * Render a violation list into the self-explaining message the guard throws.
+ * Exported so a diagnostic can reuse the exact wording the error carries.
+ */
+export declare function renderCatalogInvariantViolations(violations: ReadonlyArray<CatalogInvariantViolation>): string;
+/**
+ * The status/priority catalog violates an invariant this build's read layer
+ * depends on. Carries the offending rows as structured fields so a caller can
+ * render them; the message itself names every row AND the repair.
+ */
+export declare class CatalogInvariantError extends Error {
+    readonly violations: ReadonlyArray<CatalogInvariantViolation>;
+    constructor(violations: ReadonlyArray<CatalogInvariantViolation>);
+}
+/**
+ * Read every live status/priority row and return the invariant violations.
+ * A pure read — it never writes, so it is safe against any store, including
+ * the live one.
+ *
+ * BOUNDED by the catalog: exactly one statement against
+ * `node WHERE kind IN ('status','priority') AND t_invalid IS NULL`, folding
+ * each name in JS. The row set is the catalog (a handful of rows), never the
+ * issue graph.
+ */
+export declare function inspectCatalogInvariants(adapter: StoreAdapter): Promise<CatalogInvariantViolation[]>;
+/**
+ * Assert the store's status/priority catalog satisfies both invariants.
+ *
+ * Passes (no throw) on an empty store, and on a catalog whose reserved
+ * terminal statuses are flagged and whose same-kind names are fold-unique.
+ * Throws {@link CatalogInvariantError}, naming every offending row and the
+ * repair that resolves it, otherwise.
+ *
+ * BOUNDED BY CONSTRUCTION: this runs on every write verb (`api.ts`'s
+ * `writeHandle`), every query (`api.ts`'s `queryHandle` → `query.ts`), and
+ * store open (`openGraphBacklogStore`), so it must not scan the store per
+ * call. It reads only the (small) status/priority catalog — see
+ * {@link inspectCatalogInvariants}.
+ */
+export declare function assertCatalogInvariants(adapter: StoreAdapter): Promise<void>;

package/write/catalog-merge.d.ts

@@ -0,0 +1,123 @@
+import { IWriteStoreHandle } from './tx.js';
+import { NodeRecord } from '@adhd/sox-graph-store';
+
+/** The two catalog kinds this repair collapses (D3's whole scope). */
+export type CatalogKind = 'status' | 'priority';
+/**
+ * A status fold group that CANNOT be safely collapsed: two or more LIVE rows
+ * share a fold, yet none carries the write path's lowercase spelling. Merging
+ * would have to pick a non-lowercase canonical (or rename one to a spelling no
+ * write emits), and the next ordinary `create` would exact-match miss and
+ * re-mint the fragment. Surfaced, never merged, never renamed.
+ */
+export interface IUnmergeableGroup {
+    kind: CatalogKind;
+    names: string[];
+}
+/**
+ * A planned merge: the fold groups to collapse, by uid. `groups` is EMPTY when
+ * the store has no live case-variant group — the idempotency signal.
+ *
+ * `unmergeable` carries the status groups deliberately LEFT ALONE (no
+ * write-spelling member). It is a diagnostic, never an action: the plan is
+ * incomplete-by-refusal for those groups, so a caller that treats a zero-group
+ * plan as "the store is clean" must also check this list.
+ */
+export interface IMergePlan {
+    groups: Array<{
+        canonicalUid: string;
+        fragmentUids: string[];
+    }>;
+    unmergeable: IUnmergeableGroup[];
+    at: string;
+}
+/**
+ * One merged-away fragment, with everything needed to restore it. The
+ * `fragmentMeta`/`canonicalMetaBefore` fields carry the full prior `meta`
+ * objects (not just the changed keys), so reverse is byte-exact on the keys
+ * this repair touches and never guesses.
+ *
+ * {@link canonicalMetaBefore} is the one field beyond the required shape —
+ * without it a reverse cannot distinguish "canonical had no rank, adopted the
+ * fragment's" from "canonical's own rank was this", and cannot remove exactly
+ * the aliases this repair appended. It is OPTIONAL so a hand-authored minimal
+ * journal still type-checks; a journal written by this module always includes
+ * it.
+ */
+export interface IMergeJournalEntry {
+    fragmentUid: string;
+    canonicalUid: string;
+    fragmentMeta: unknown;
+    repointedEdges: Array<{
+        srcRowid: number;
+        rel: string;
+        fragmentDstRowid: number;
+    }>;
+    /** The fragment's numeric `rank` at apply time, when it had one — the value the survivor did NOT adopt unless it had none of its own. */
+    retainedRank?: number;
+    /** Present only when a PRIORITY group had no upper-spelled member: the canonical row was renamed to uppercase, and this is how to undo it. A status canonical is never renamed. */
+    renamed?: {
+        uid: string;
+        from: string;
+        to: string;
+    };
+    /** The canonical row's full prior `meta`, for exact reversal of the appended aliases / adopted rank. */
+    canonicalMetaBefore?: unknown;
+}
+export interface IMergeJournal {
+    entries: IMergeJournalEntry[];
+    at: string;
+}
+/**
+ * Build the collapse plan from the LIVE catalog rows. Pure over node records —
+ * it never reads edges, so a fragment with more incoming edges than the
+ * canonical loses anyway (owner directive: spelling decides, not edge count).
+ *
+ * Grouping is by {@link catalogNameFold} alone. Within a fold group the
+ * canonical is the member already carrying the write path's spelling for that
+ * kind — lowercase for `status`, uppercase for `priority`.
+ *
+ * A `priority` group with no upper-spelled member falls back to its
+ * lowest-rowid member (deterministically renamed to uppercase at apply, as
+ * before). A `status` group with no lower-spelled member is NOT planned at all:
+ * any canonical would carry a spelling the write path never emits, so merging
+ * would regenerate the fragment on the next ordinary `create`. It is surfaced
+ * in `unmergeable` instead.
+ */
+export declare function planCaseFragmentMerge(liveStatuses: readonly NodeRecord[], livePriorities: readonly NodeRecord[]): IMergePlan;
+/**
+ * Apply the plan in ONE `executeWriteTransaction` (`BEGIN IMMEDIATE` + bounded
+ * busy-only retry, §4c) — every group in the plan commits together or not at
+ * all, so a refusal in a later group can never leave an earlier group half
+ * merged.
+ *
+ * For each group: re-point every incoming catalog edge onto the canonical,
+ * append the merged-away (and renamed-from) spellings to
+ * `canonical.meta.aliases`, adopt the canonical's rank (a fragment's only if
+ * the canonical lacks one), and invalidate each fragment with `t_invalid`.
+ *
+ * REFUSES (throws, rolling the whole apply back) any group whose fragment does
+ * not fold to the canonical's live name, or whose kind differs — the
+ * `closed`/`DONE` guard: two distinct tokens are never case-variants and can
+ * never be collapsed here. It also REFUSES a `status` group whose canonical is
+ * not already lowercase-spelled — merging INTO a spelling the write path never
+ * emits would let the next ordinary `create` re-mint the fragment.
+ *
+ * Only a `priority` group is ever renamed (to uppercase, when it had no
+ * uppercase member). A `status` `name` is NEVER rewritten.
+ *
+ * A planned fragment that is no longer LIVE (a concurrent writer invalidated
+ * it between plan and apply) is tolerated — it is skipped, exactly as D1's
+ * apply re-guards each row.
+ */
+export declare function applyCaseFragmentMerge(handle: IWriteStoreHandle, plan: IMergePlan): Promise<IMergeJournal>;
+/**
+ * Reverse an applied journal in ONE `executeWriteTransaction`: re-liven each
+ * fragment, restore its exact prior `meta`, re-point its original edges back
+ * off the canonical, restore the canonical's prior `meta` (dropping the
+ * appended aliases / adopted rank), and undo any rename.
+ *
+ * A fragment or canonical uid that no longer exists is skipped — the same
+ * tolerant posture D1's reverse takes for a concurrently-deleted row.
+ */
+export declare function reverseCaseFragmentMerge(handle: IWriteStoreHandle, journal: IMergeJournal): Promise<void>;

package/write/catalog-repair.d.ts

@@ -0,0 +1,74 @@
+import { RESERVED_TERMINAL_STATUS_NAMES } from './catalog.js';
+import { IWriteStoreHandle } from './tx.js';
+
+/**
+ * The reserved terminal vocabulary — SINGLE SOURCE, owned by
+ * `write/catalog.ts` (the mint path that seeds from it) and re-exported here
+ * so this module's consumers keep one import site. A drift test
+ * (`catalog-mint-terminal.spec.ts`) asserts this is the SAME object the mint
+ * path uses, i.e. that exactly ONE definition exists in the codebase.
+ */
+export { RESERVED_TERMINAL_STATUS_NAMES };
+/**
+ * Unicode fold used by BOTH duplicate detection and JS-side grouping — never
+ * `SQL lower()`/`NOCASE` (ASCII-only, so it folds `A`–`Z` and nothing else).
+ * `NFKC` first so compatibility forms collapse, then `toLowerCase()` (the JS
+ * Unicode-aware case fold, mirroring PostgreSQL `citext`'s documented Unicode
+ * behavior) so `RESOLVED`, `resolved` and `Resolved` group together.
+ */
+export declare function catalogNameFold(name: string): string;
+/**
+ * The set of LIVE `status` rowids the backfill should set `terminal:true` on,
+ * plus the plan timestamp. Rows already `terminal:true` are EXCLUDED here (the
+ * idempotency guarantee: a fully-repaired store plans nothing).
+ */
+export interface ITerminalBackfillPlan {
+    setTerminalRowids: number[];
+    at: string;
+}
+/**
+ * The apply journal — enough to restore EXACTLY the prior state. `hadTerminal`
+ * is the row's `meta.terminal === true` at apply time; because a row already
+ * `true` is never changed (and never journaled), every real entry's
+ * `hadTerminal` is `false`.
+ */
+export interface ITerminalBackfillJournal {
+    entries: Array<{
+        rowid: number;
+        uid: string;
+        hadTerminal: boolean;
+    }>;
+    at: string;
+}
+/**
+ * Build the backfill plan: every LIVE `status` row whose FOLDED name is a
+ * reserved terminal name and whose `terminal` flag is not already `true`.
+ *
+ * Reads are plain SELECTs against the bare adapter — this is a repair planner,
+ * not a write verb, and it holds no lock across the (separately transactional)
+ * apply. A row created or renamed between plan and apply is tolerantly skipped
+ * by {@link applyTerminalBackfill}, which re-guards each row inside its own
+ * transaction.
+ */
+export declare function planTerminalBackfill(handle: IWriteStoreHandle, at?: string): Promise<ITerminalBackfillPlan>;
+/**
+ * Apply the plan in ONE `executeWriteTransaction` (`BEGIN IMMEDIATE` +
+ * busy-only bounded retry, §4c): read each target status row, guarded-parse
+ * its `meta`, set `terminal:true`, guarded
+ * `UPDATE node SET meta = ? WHERE rowid = ? AND t_invalid IS NULL`. Only the
+ * `terminal` flag is touched — every other `meta` key is carried through
+ * verbatim.
+ *
+ * A rowid that is no longer a LIVE `status` row between plan and apply is
+ * skipped (nothing to repair, nothing journaled); a planned rowid that IS a
+ * live non-`status` row is a plan/DB mismatch and throws loudly (ADR-0002 D5
+ * step 4's error-loudly posture) rather than silently rewriting an unrelated
+ * node.
+ */
+export declare function applyTerminalBackfill(handle: IWriteStoreHandle, plan: ITerminalBackfillPlan): Promise<ITerminalBackfillJournal>;
+/**
+ * Reverse an applied journal in ONE `executeWriteTransaction`: restore
+ * `meta.terminal` to its recorded `hadTerminal` for each entry — and NOTHING
+ * else. A rowid that is no longer a LIVE `status` row is skipped.
+ */
+export declare function reverseTerminalBackfill(handle: IWriteStoreHandle, journal: ITerminalBackfillJournal): Promise<void>;

package/write/catalog.d.ts

@@ -56,12 +56,81 @@ export interface IMintOrResolveInput {
      */
     at?: string;
 }
+/**
+ * The reserved TERMINAL status vocabulary — the ONE in-code definition
+ * (SPEC.md §2: `status.terminal` drives closedness). Modelled directly on
+ * {@link EDGE_KIND_TABLE} further down this file: a frozen in-code table the
+ * mint layer seeds from, exactly as {@link resolveEdgeKindTx} seeds
+ * `edge_kind` from §3's fixed edge table.
+ *
+ * The flag, never the name, is the read-time source of truth —
+ * `query/card.ts`'s `isStatusTerminal` stays name-blind (ADR-0002 D1: an
+ * unfixed-source gap is repaired at the SOURCE, never papered over with a
+ * read-time name fallback, which would be a second, drifting source of
+ * truth). This table is that source fix: a name listed here that has no live
+ * `status` row is SEEDED `terminal:true` by {@link mintOrResolveStatusTx}, so
+ * minting `closed` (or any other reserved name) can no longer produce a row
+ * that reads as non-terminal — the drift `catalog-repair.ts` exists to clean
+ * up is not regenerated on the next mint.
+ *
+ * Membership is decided on the FOLDED name ({@link catalogNameFold}) — the
+ * same Unicode fold the duplicate guard and the case-fragment repair use, never
+ * SQL `lower()`/`NOCASE`, which fold only ASCII `A`–`Z`. The spellings below
+ * are the canonical catalog rows, but the PREDICATE folds, so `Closed`,
+ * `fixed`, `resolved` and `done` all count as reserved. This matters because a
+ * first-ever lowercase `fixed`/`resolved`/`done` has no uppercase row to
+ * collide against; under an exact-case predicate it would seed
+ * `terminal:false` — a closed status the read layer returns as open (backlog
+ * b4525bc3 / d7ec2c50). There is exactly ONE such table in the codebase
+ * (`catalog-repair.ts` re-exports this set rather than declaring its own).
+ */
+export declare const RESERVED_TERMINAL_STATUS_NAMES: ReadonlySet<string>;
+/** Whether `name` is one of {@link RESERVED_TERMINAL_STATUS_NAMES} under the case fold — so any spelling of the reserved terminal vocabulary (`closed`/`Closed`/`CLOSED`, `fixed`/`FIXED`) counts. */
+export declare function isReservedTerminalStatusName(name: string): boolean;
 /**
  * The flat-catalog find-then-create (§1, §4c, §6.1): `kind`/`status`/
  * `priority`/`agent` are mintable on an unresolved NAME; a uid-shaped `ref`
  * that does not resolve instead throws — minting NEVER applies to a uid.
+ *
+ * A NAME that case-folds to an EXISTING LIVE row of the same kind but is
+ * spelled differently (`IN_PROGRESS` when `in_progress` is live) is REFUSED
+ * with {@link CaseVariantNameError} — never fold-resolved onto the existing
+ * row, never minted as a twin. Identity is exact-case (`WHERE name = ?`), so a
+ * variant is neither the same row nor a genuinely new name; it is ambiguous,
+ * and the ambiguity is stopped here rather than allowed to grow a duplicate
+ * the catalog-invariant guard would then abort every read over.
  */
 export declare function mintOrResolveCatalogTx(tx: AdapterTransaction, input: IMintOrResolveInput): Promise<IResolvedCatalogRow>;
+/**
+ * Resolve-or-seed a `status` catalog row (§2, §6.1, §6.3.2, §6.3.4) — the
+ * ONE sanctioned status mint path, and the write-side counterpart of the
+ * read-side `query/card.ts`'s `isStatusTerminal`.
+ *
+ * Unlike the generic {@link mintOrResolveCatalogTx}, it SEEDS `terminal` from
+ * the frozen {@link RESERVED_TERMINAL_STATUS_NAMES} table on a miss — never
+ * from a call-site literal (`terminal:false` hardcoded at the call site was
+ * the drift's root cause) and never from a read-time name heuristic
+ * (`isStatusTerminal` stays name-blind, ADR-0002 D1). A name in the table
+ * seeds `terminal:true`; every other name seeds the pre-existing
+ * `terminal:false` default (§6.3.2: a novel or mistyped name must never
+ * silently close or exclude an item).
+ *
+ * Self-healing and idempotent, exactly like {@link resolveEdgeKindTx}: the
+ * exact `(kind,name)` lookup inside {@link mintOrResolveCatalogTx} finds the
+ * seeded row on every subsequent call, so reseeding never duplicates — the
+ * store converges to one live `status` row per name. A case-variant name
+ * (`Closed` vs a seeded `closed`) is REFUSED by {@link mintOrResolveCatalogTx}
+ * with {@link CaseVariantNameError} rather than folded onto the existing row or
+ * minted as a twin — the same exact-case stop every other flat catalog takes
+ * (see that function's doc comment).
+ *
+ * A uid-shaped `ref` that does not resolve still throws
+ * `CatalogNotFoundError` — minting never applies to a uid (§6.1).
+ */
+export declare function mintOrResolveStatusTx(tx: AdapterTransaction, input: {
+    ref: string;
+    at?: string;
+}): Promise<IResolvedCatalogRow>;
 /** `priority`'s mint rule (§6.3.2): "rank set to one past the current max rank (i.e. lowest urgency) — a novel priority can never silently outrank an existing one." */
 export declare function nextPriorityRankTx(tx: AdapterTransaction): Promise<number>;
 /**

package/write/create-issue.d.ts

@@ -25,7 +25,7 @@ export interface ICreateIssueInput {
     component?: string;
     /** catalog name or uid; default is the project's configured `policy.defaultKind`, falling back to the global `"issue"` row. An unresolved NAME mints; a uid-shaped ref that does not resolve throws (§6.1). */
     kind?: string;
-    /** catalog name or uid; default is `policy.defaultStatus`, falling back to the global `"open"` row (minted with `terminal:false` if it does not yet exist). An unresolved NAME mints with `terminal:false`; a uid-shaped ref that does not resolve throws (§6.1). */
+    /** catalog name or uid; default is `policy.defaultStatus`, falling back to the global `"open"` row. An unresolved NAME is minted via `mintOrResolveStatusTx`: a name in the frozen reserved terminal table (`RESERVED_TERMINAL_STATUS_NAMES`, `catalog.ts`) seeds `terminal:true`, every other name seeds `terminal:false` (a novel/typo name must never silently close an item, §6.3.2); a uid-shaped ref that does not resolve throws (§6.1). */
     status?: string;
     /** catalog name or uid; genuinely OPTIONAL — §6.3.2 states minting behavior for a GIVEN unresolved name but, unlike `kind`/`status`, states no fallback for the omitted case; omitted therefore writes no `has_priority` edge at all (a deliberate reading of §6.3.2's more precise per-field text over §4's summary prose — see this project's own README/CHANGELOG note on this slice for the citation). An unresolved NAME mints with `rank` = one past the current max (lowest urgency); a uid-shaped ref that does not resolve throws. */
     priority?: string;

package/write/errors.d.ts

@@ -18,7 +18,7 @@
  * All named classes here are `E_VALIDATION`- or `E_CONSTRAINT`-class
  * members of the same union (SPEC.md §4c, "Two failure-signaling shapes,
  * reconciled into one contract") — `IssueNotFoundError`, `InvalidArgumentError`,
- * `CatalogNotFoundError`, `ClaimHeldError`, `SingleValuedRelationConflictError`,
+ * `CatalogNotFoundError`, `CaseVariantNameError`, `ClaimHeldError`, `SingleValuedRelationConflictError`,
  * `NoteRequiredError`, `CitationRequiredError`, `CitationUnverifiableError` are
  * `E_VALIDATION` (never retryable — thrown before any driver call runs);
  * `StaleSupersedeError` is the one deliberate `E_CONSTRAINT` this spec's own
@@ -162,6 +162,42 @@ export declare class CatalogNotFoundError extends BacklogWriteError {
     readonly retryable = false;
     constructor(catalogKind: string, ref: string);
 }
+/**
+ * A flat-catalog write named a token that differs from an EXISTING LIVE row of
+ * the SAME kind only by letter case (`IN_PROGRESS` vs `in_progress`, `high` vs
+ * `HIGH`). Catalog identity is EXACT-case (`DATA_MODEL.md:70-78`; the
+ * `(kind, name)` resolve in `write/catalog.ts` is `WHERE name = ?`), so the
+ * write path REFUSES the variant rather than fold-resolving it onto the
+ * existing row or minting a twin. Accepting it would grow a second live row
+ * that case-folds to the first — the case-fragment defect the uniqueness guard
+ * (`store/catalog-invariant-guard.ts`) exists to catch, which is exactly how
+ * the store wedged (BUG: a mixed-case write minted a twin, then the guard
+ * refused every read).
+ *
+ * The message names BOTH spellings and tells the caller which one to use: the
+ * one already live. The ambiguity is stopped here, at the single write call
+ * site, instead of aborting every read.
+ *
+ * `E_VALIDATION`, never retryable — this is a before-any-mint decision, so
+ * retrying the identical payload fails identically.
+ */
+export declare class CaseVariantNameError extends BacklogWriteError {
+    /** The flat-catalog kind (`status`, `priority`, `kind`, `agent`). */
+    readonly catalogKind: string;
+    /** The name of the row ALREADY LIVE for this kind — the spelling to use. */
+    readonly canonicalName: string;
+    /** The differing name the caller supplied — the spelling that was refused. */
+    readonly offendingName: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(
+    /** The flat-catalog kind (`status`, `priority`, `kind`, `agent`). */
+    catalogKind: string, 
+    /** The name of the row ALREADY LIVE for this kind — the spelling to use. */
+    canonicalName: string, 
+    /** The differing name the caller supplied — the spelling that was refused. */
+    offendingName: string);
+}
 /** A caller-supplied argument is missing, blank, or fails a project-declared invariant. */
 export declare class InvalidArgumentError extends BacklogWriteError {
     readonly field: string;

package/write/transition.d.ts

@@ -6,7 +6,7 @@ export interface ITransitionInput {
     uid: string;
     /** The identity of the acting agent or person (§6.3's opening rule). REQUIRED. */
     by: string;
-    /** catalog name or uid. An unresolved NAME mints a new status row with `terminal:false` (exactly like `create`'s own `status` field, §6.3.2/§6.1); a uid-shaped ref that does not resolve throws `CatalogNotFoundError('status', ref)`. */
+    /** catalog name or uid. An unresolved NAME is minted via `mintOrResolveStatusTx` (exactly like `create`'s own `status` field, §6.3.2/§6.1): a name in the frozen reserved terminal table (`RESERVED_TERMINAL_STATUS_NAMES`, `catalog.ts`) seeds `terminal:true`, every other name seeds `terminal:false`; a uid-shaped ref that does not resolve throws `CatalogNotFoundError('status', ref)`. */
     toStatus: string;
     /** REQUIRED unless `project_policy.transition_requires_note` is `false` (default `true`) — optional in the type; enforced at runtime (`NoteRequiredError`), never at the TS level. */
     note?: string;
@@ -42,8 +42,9 @@ export interface ITransitionOutcome {
  * `update` — this file's own doc comment on `update.ts` explains why that
  * reuses this error class rather than a new one), `CatalogNotFoundError('status',
  * toStatus)` (uid-shaped `toStatus` only — an unresolved NAME instead
- * auto-mints with `terminal:false`, exactly as `create`'s own `status` field,
- * §6.1), a project-declared `requiredFields` entry (§2 — here, always just
+ * auto-mints via `mintOrResolveStatusTx`, seeding `terminal` from the frozen
+ * reserved table exactly as `create`'s own `status` field does (§6.1), a
+ * project-declared `requiredFields` entry (§2 — here, always just
  * `status`, see this file's own doc comment) left blank,
  * `NoteRequiredError` (policy-gated), `CitationRequiredError`
  * (policy-gated, terminal-only), `CitationUnverifiableError(target,