@adhd/backlog 1.0.4 → 1.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhd/backlog",
-  "version": "1.0.4",
+  "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;

package/write/errors.d.ts

@@ -162,6 +162,35 @@ 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
@@ -208,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;