@adhd/backlog 1.0.3 → 1.0.5

package/package.json

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

package/query/query.d.ts

@@ -48,15 +48,18 @@ export interface IQueryStoreHandle {
      */
     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.
+     * Status/priority catalog invariant check (`store/catalog-invariant-guard.ts`),
+     * exposed OPT-IN — deliberately NOT consulted by `queryIssuesWithMeta`, and
+     * therefore NEVER on the ordinary read path. A drifted catalog (an unflagged
+     * reserved terminal status, or two same-kind rows sharing a case fold) is a
+     * bounded data problem: the read path serves the store regardless, and the
+     * drift is surfaced as a NAMED, non-zero check by the `store-check` CLI verb.
+     * `api.ts`'s `queryHandle` still wires it for every real host, so a caller
+     * that WANTS to assert explicitly can call `handle.assertCatalogInvariants?.()`
+     * — but no read ever does so implicitly. (Earlier this was awaited inside
+     * `queryIssuesWithMeta`; that abort turned one drifted row into a total read
+     * outage and was removed. The write path's per-verb abort was removed the
+     * same way, so neither ordinary path is gated.)
      */
     readonly assertCatalogInvariants?: () => Promise<void>;
 }

package/query/resolve.d.ts

@@ -9,12 +9,39 @@ export interface IResolvedRef {
     name: string;
     record: NodeRecord;
 }
+/**
+ * Resolve `ref` to exactly one LIVE node, by exact uid or by a UNIQUE uid
+ * prefix. Exact match is the fast path and always wins.
+ *
+ * Errors: `AmbiguousReferenceError` when a prefix matches ≥2 live nodes (the
+ * candidates are carried on the error and named in its message);
+ * `IssueNotFoundError` (kind `issue`) / `CatalogNotFoundError` (any other
+ * kind) when an exact uid or prefix matches nothing; `InvalidArgumentError`
+ * when `ref` is a uid attempt shorter than the minimum prefix length.
+ */
+export declare function resolveUidPrefix(graph: GraphBackend, ref: string, opts?: {
+    expectedKind?: string;
+}): Promise<NodeRecord>;
+/**
+ * Like {@link resolveUidPrefix}, but `null` instead of a not-found error when
+ * nothing matches — for callers that treat a uid miss as "fall through to a
+ * name lookup." An AMBIGUOUS prefix still throws (never silently picks one),
+ * and a too-short uid attempt returns `null` so a genuine short business name
+ * is not swallowed.
+ */
+export declare function tryResolveUidPrefix(graph: GraphBackend, ref: string, opts?: {
+    expectedKind?: string;
+}): Promise<NodeRecord | null>;
 /**
  * Resolve `uid` → the live `issue` node, or throw {@link IssueNotFoundError}
  * (SPEC.md §6.1: "a `uid` with no matching live node throws
  * `IssueNotFoundError(uid)`"). This is the READ-PATH counterpart of
  * `write/tx.ts`'s `getNodeByUidTx` — safe to call standalone because it is
  * not composing a check-then-act write around the result.
+ *
+ * Accepts an exact uid or a UNIQUE uid prefix (see {@link resolveUidPrefix});
+ * a superseded node — whether reached by exact uid or prefix — throws the same
+ * {@link StaleSupersedeError} pointing at the chain head.
  */
 export declare function resolveIssueByUid(graph: GraphBackend, uid: string): Promise<NodeRecord>;
 /**

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

@@ -53,10 +53,16 @@ export declare function inspectCatalogInvariants(adapter: StoreAdapter): Promise
  * 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
+ * WHERE IT RUNS: the `store-check` CLI verb — a NAMED, non-zero check an
+ * operator runs deliberately — plus any caller that asserts deliberately via
+ * `IQueryStoreHandle.assertCatalogInvariants`. It is deliberately NOT run on
+ * the ordinary read path (`queryIssuesWithMeta`), on the write path (`api.ts`'s
+ * `writeHandle`), or at store open (`openGraphBacklogStore`): a violation must
+ * be detected loudly and REPORTED, never allowed to turn every read — or every
+ * unrelated write — into an outage.
+ *
+ * BOUNDED BY CONSTRUCTION: it must not scan the issue graph per call. It reads
+ * only the (small) status/priority catalog — see
  * {@link inspectCatalogInvariants}.
  */
 export declare function assertCatalogInvariants(adapter: StoreAdapter): Promise<void>;

package/write/catalog.d.ts

@@ -1,9 +1,16 @@
 import { IComponentSummary, ILocationSummary, ILocationType, IProjectSummary } from '../query/types.js';
 import { IEdgeKindRule, IWriteStoreHandle } from './tx.js';
+import { isUidShaped } from './uid-prefix.js';
 import { AdapterTransaction } from '@adhd/sox-store-adapter';
 
-/** Whether `ref` should be treated as a `uid` (exact resolve-or-throw) rather than a business `name` (find, and for the flat catalogs, find-then-mint). */
-export declare function isUidShaped(ref: string): boolean;
+/**
+ * Disambiguation by SHAPE, not a second field (§6.1): a 36-character
+ * version-4-UUID-formatted string is a `uid`; anything else is a `name`. The
+ * single definition lives in `write/uid-prefix.ts` (which also owns prefix
+ * classification); re-exported here so every existing `isUidShaped` importer
+ * keeps its path unchanged.
+ */
+export { isUidShaped };
 export interface IResolvedCatalogRow {
     rowid: number;
     uid: string;
@@ -73,21 +80,32 @@ export interface IMintOrResolveInput {
  * 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).
+ * 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 EXACTLY one of {@link RESERVED_TERMINAL_STATUS_NAMES} — case-sensitive, the same predicate the `(kind,name)` resolve uses. */
+/** 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>;
 /**
@@ -108,9 +126,10 @@ export declare function mintOrResolveCatalogTx(tx: AdapterTransaction, input: IM
  * 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).
+ * (`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).

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,71 @@ export declare class CatalogNotFoundError extends BacklogWriteError {
     readonly retryable = false;
     constructor(catalogKind: string, ref: string);
 }
+/**
+ * A uid reference matched MORE THAN ONE live node by prefix. Carries the
+ * candidate set (`uid` + `kind` + `name`) as structured data so a caller can
+ * disambiguate and re-run, and renders every candidate into the message.
+ *
+ * The resolver NEVER auto-selects among the candidates — silently returning
+ * the wrong item is strictly worse than refusing. Distinct from
+ * `IssueNotFoundError` (an exact uid that is genuinely absent) so a caller can
+ * branch structurally: an ambiguous reference is actionable (re-run with a
+ * longer prefix or the full uid), a missing one is not.
+ *
+ * `E_VALIDATION`, never retryable — retrying the identical short reference
+ * resolves to the identical candidate set.
+ */
+export declare class AmbiguousReferenceError extends BacklogWriteError {
+    readonly ref: string;
+    readonly candidates: ReadonlyArray<{
+        uid: string;
+        kind: string;
+        name: string;
+    }>;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(ref: string, candidates: ReadonlyArray<{
+        uid: string;
+        kind: string;
+        name: 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;
@@ -172,9 +237,16 @@ export declare class InvalidArgumentError extends BacklogWriteError {
 /** No live `issue` node carries the given `uid` (SPEC.md §6.1). */
 export declare class IssueNotFoundError extends BacklogWriteError {
     readonly uid: string;
+    readonly asPrefix: boolean;
     readonly code: "E_VALIDATION";
     readonly retryable = false;
-    constructor(uid: string);
+    /**
+     * @param uid The uid (or uid prefix) the caller passed in.
+     * @param asPrefix Set by the prefix resolver when `uid` was a short prefix
+     *   rather than a full uid, so the message says "no item matches" instead of
+     *   implying the caller passed a complete uid that is simply absent.
+     */
+    constructor(uid: string, asPrefix?: boolean);
 }
 /**
  * `claim` (§6.3.5): the lease is held by someone else, not yet stale, and the

package/write/tx.d.ts

@@ -1,3 +1,4 @@
+import { INodeReadExecutor } from './uid-prefix.js';
 import { BacklogWriteError } from './errors.js';
 import { TypePolicy } from '@adhd/sox-graph-store';
 import { AdapterTransaction, StoreAdapter } from '@adhd/sox-store-adapter';
@@ -98,7 +99,28 @@ export declare function canonicalJSONStringify(value: Record<string, unknown>):
  * issued against `tx` instead of the bare adapter — never a `getNodeByUid`
  * call itself, which always runs against `this.adapter` (§4c).
  */
-export declare function getNodeByUidTx(tx: AdapterTransaction, uid: string): Promise<ITxNodeRow | null>;
+export declare function getNodeByUidTx(tx: INodeReadExecutor, uid: string): Promise<ITxNodeRow | null>;
+/**
+ * uid reference → LIVE `issue`/catalog node row, inside a tx, accepting a
+ * UNIQUE uid PREFIX as well as an exact uid. This is the single write-side
+ * funnel every issue verb ({@link resolveLiveIssueTx}) and catalog
+ * uid-resolution (`catalog.ts`'s `resolveByUidTx`, hence `rm-location`) goes
+ * through, so the prefix contract is defined once rather than per verb.
+ *
+ * Exact match is the fast path and keeps winning: a full uid is looked up
+ * directly, and only when that misses is a prefix scan attempted. A prefix
+ * below `MIN_UID_PREFIX_LENGTH` throws an "too short" argument error; a prefix
+ * that matches zero rows throws the kind-appropriate not-found; a prefix that
+ * matches two or more throws {@link AmbiguousReferenceError} naming every
+ * candidate — never an arbitrary pick.
+ *
+ * @throws IssueNotFoundError (kind `issue`) / CatalogNotFoundError (any other
+ *   kind) when nothing live matches.
+ * @throws AmbiguousReferenceError when a prefix matches more than one live row.
+ */
+export declare function resolveUidPrefixTx(exec: INodeReadExecutor, ref: string, opts?: {
+    expectedKind?: string;
+}): Promise<ITxNodeRow>;
 /**
  * Resolves `uid` to the CURRENT, live `issue` row, or throws.
  *

package/write/uid-prefix.d.ts

@@ -0,0 +1,78 @@
+import { InvalidArgumentError } from './errors.js';
+
+/** Whether `ref` is an exact, full uid (resolve-or-throw), never a business `name` and never a prefix. */
+export declare function isUidShaped(ref: string): boolean;
+/**
+ * The shortest uid prefix this resolver will accept. Eight hex characters —
+ * the first UUID block, the human-copyable unit, and 32 bits of address space;
+ * see this file's header for the full justification.
+ */
+export declare const MIN_UID_PREFIX_LENGTH = 8;
+/**
+ * Whether `ref` is a proper prefix (length `>=` {@link MIN_UID_PREFIX_LENGTH},
+ * `< 36`) of some canonical uid string — hex characters with hyphens only at
+ * the canonical boundary positions.
+ */
+export declare function isUidPrefixShaped(ref: string): boolean;
+/** How a caller-supplied reference reads: an exact uid, a uid prefix, a too-short uid attempt, or not uid-shaped at all. */
+export type UidRefKind = 'exact' | 'prefix' | 'too-short' | 'not-uid';
+/**
+ * Classify `ref` for uid resolution. `too-short` is a uid ATTEMPT (hex/hyphen
+ * only) below {@link MIN_UID_PREFIX_LENGTH} — a strict uid context rejects it
+ * as too short, while a uid-or-name context falls back to a name lookup, so a
+ * genuine 6-character value that is itself a valid name is never swallowed.
+ */
+export declare function classifyUidRef(ref: string): UidRefKind;
+/** One live node matching a uid PREFIX, projected to the fields the ambiguity decision and its error need. */
+export interface IUidCandidate {
+    uid: string;
+    kind: string;
+    name: string | null;
+    isSuperseded: boolean;
+}
+/**
+ * The minimal executor a prefix candidate read needs. Structural, so it is
+ * satisfied by `AdapterTransaction`, graph-store's `GraphTransaction`, and a
+ * bare `StoreAdapter` alike — nothing here depends on which one it is.
+ */
+export interface IUidPrefixQueryExecutor {
+    executeAll<T = Record<string, unknown>>(sql: string, args?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+}
+/**
+ * The executor a uid resolution needs: the prefix candidate read plus the
+ * exact single-row read. Structural, so `AdapterTransaction`,
+ * graph-store's `GraphTransaction`, and a bare `StoreAdapter` all satisfy it.
+ */
+export interface INodeReadExecutor extends IUidPrefixQueryExecutor {
+    executeGet<T = Record<string, unknown>>(sql: string, args?: unknown[]): Promise<T | null>;
+}
+/**
+ * Every LIVE node whose uid starts with `prefix`.
+ *
+ * The range predicate `uid >= ? AND uid < ?` is an indexed prefix scan (the
+ * store keeps a unique index on `uid`) and, unlike a `LIKE` pattern, is
+ * case-exact against the lowercase uids the store mints — so the input is
+ * lower-cased once here and the caller never has to reason about collation.
+ * Soft-deleted rows are excluded in SQL (`t_invalid IS NULL`); a superseded
+ * row is returned (its `is_superseded` flag carried) so a caller that resolves
+ * to it can raise the same stale-reference error the exact path does.
+ */
+export declare function queryLiveUidPrefixCandidates(exec: IUidPrefixQueryExecutor, prefix: string): Promise<IUidCandidate[]>;
+/**
+ * The ambiguity decision, shared by both paths. Returns the sole candidate, or
+ * `null` when there are none (the caller owns the not-found error, which
+ * differs by kind). Two or more candidates throw {@link AmbiguousReferenceError}
+ * — the resolver never auto-selects.
+ */
+export declare function selectUniqueUidCandidate(ref: string, candidates: readonly IUidCandidate[]): IUidCandidate | null;
+/**
+ * The not-found error for a uid reference, keyed by the kind the caller asked
+ * for. `asPrefix` selects the prefix-specific wording ("no item matches")
+ * versus the exact-uid wording, so a caller can tell "this short reference
+ * matched nothing" from "this full uid is not here."
+ */
+export declare function missingUidError(expectedKind: string | undefined, ref: string, asPrefix: boolean): Error;
+/** The too-short refusal — a uid attempt below {@link MIN_UID_PREFIX_LENGTH}. */
+export declare function tooShortUidError(ref: string): InvalidArgumentError;