@adhd/backlog 1.0.1 → 1.0.3

package/package.json

@@ -1,22 +1,22 @@
 {
   "name": "@adhd/backlog",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "bin": {
     "adhd-backlog": "index.js"
   },
   "dependencies": {
-    "@adhd/apigen-base-logical": "^0.1.3",
-    "@adhd/apigen-core-client": "^0.3.2",
-    "@adhd/apigen-engine-naming": "^0.2.4",
-    "@adhd/apigen-plugin-api-fastify": "^0.2.5",
-    "@adhd/apigen-plugin-batch": "^0.2.4",
-    "@adhd/apigen-plugin-cli-output": "^0.2.5",
-    "@adhd/apigen-plugin-ir-cache": "^0.1.2",
-    "@adhd/apigen-plugin-mcp": "^0.3.0",
-    "@adhd/apigen-plugin-openapi": "^0.2.4",
-    "@adhd/environment": "^0.1.7",
-    "@adhd/environment-base-spec": "^0.1.2",
-    "@adhd/environment-builder": "^0.1.6",
+    "@adhd/apigen-base-logical": "^0.1.4",
+    "@adhd/apigen-core-client": "^0.3.3",
+    "@adhd/apigen-engine-naming": "^0.2.5",
+    "@adhd/apigen-plugin-api-fastify": "^0.2.6",
+    "@adhd/apigen-plugin-batch": "^0.2.5",
+    "@adhd/apigen-plugin-cli-output": "^0.2.6",
+    "@adhd/apigen-plugin-ir-cache": "^0.1.3",
+    "@adhd/apigen-plugin-mcp": "^0.3.1",
+    "@adhd/apigen-plugin-openapi": "^0.2.5",
+    "@adhd/environment": "^0.1.8",
+    "@adhd/environment-base-spec": "^0.1.3",
+    "@adhd/environment-builder": "^0.1.7",
     "@adhd/sox-graph-store": "^0.11.1",
     "@adhd/sox-hybrid-search": "^0.5.0",
     "@adhd/sox-semantic": "^0.1.8",

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,69 @@ 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 EXACT and case-sensitive — the same predicate the `(kind,name)`
+ * lookup uses (`WHERE name = ?`). A case-variant (`Closed`) is deliberately
+ * NOT a member: it is an exact miss, self-heals into its own row (never a
+ * throw), and is left to the separately-owned case-fragment repair, which
+ * folds names. Spelling the canonical rows here is what pins them; 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 EXACTLY one of {@link RESERVED_TERMINAL_STATUS_NAMES} — case-sensitive, the same predicate the `(kind,name)` resolve uses. */
+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.
  */
 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 an exact miss, so it self-heals into its
+ * own row rather than throwing — the pre-existing resolution property, not a
+ * terminality decision (the case-fragment repair folds those separately).
+ *
+ * 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/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,