@adhd/backlog 1.0.4 → 1.0.6

package/write/obligation.d.ts

@@ -0,0 +1,133 @@
+import { IWriteStoreHandle } from './tx.js';
+
+/** `block` refuses the transition; `warn` records the shortfall but allows it (the C5 gate reads this). */
+export type IObligationSeverity = 'block' | 'warn';
+/** Which side of an edge the subject sits on: `in` = subject is `dst`, `out` = subject is `src`. */
+export type IRelationDirection = 'in' | 'out';
+/**
+ * The CLOSED predicate core (DESIGN §2 Primitive 3). No CEL, no dynamic leaf,
+ * no timeout — the grammar is exactly these six productions. Validated
+ * recursively by {@link assertValidPredicate}.
+ *
+ * - `evidence{kind,min?}` → distinct verified attestations of `kind` ≥ `min ?? 1`.
+ * - `blockers_terminal()` → every incoming live `blocks` source is terminal.
+ * - `relation{type,direction}` → a live edge of `type` touches the subject.
+ * - `all_of` / `any_of` / `not` → boolean composition. Empty `all_of` ⇒ `true`,
+ *   empty `any_of` ⇒ `false` (documented, asserted).
+ */
+export type IPredicate = {
+    op: 'evidence';
+    kind: string;
+    min?: number;
+} | {
+    op: 'blockers_terminal';
+} | {
+    op: 'relation';
+    type: string;
+    direction: IRelationDirection;
+} | {
+    op: 'all_of';
+    of: IPredicate[];
+} | {
+    op: 'any_of';
+    of: IPredicate[];
+} | {
+    op: 'not';
+    of: IPredicate;
+};
+export interface IObligationAppliesTo {
+    /** Absent ⇒ applies to any from-status. */
+    from?: string;
+    /**
+     * REQUIRED. Scopes a TRANSITION into that status: a concrete status name, or
+     * `'*'` for "any terminal transition". Evaluated by the C5 gate at the
+     * transition, and surfaced by the C6 verdict as a *prediction* of that gate.
+     */
+    to: string;
+}
+export interface IObligationOverride {
+    /** Non-empty actor identities permitted to override this obligation — an override always requires a recorded reason at the C5 layer. */
+    actors: string[];
+}
+export interface IObligateInput {
+    uid: string;
+    applies_to: IObligationAppliesTo;
+    requirement: IPredicate;
+    on_fail: IObligationSeverity;
+    override?: IObligationOverride;
+    by: string;
+}
+export interface IObligateOutcome {
+    uid: string;
+    obligationUid: string;
+}
+export interface IUnobligateInput {
+    obligationUid: string;
+    by: string;
+}
+export interface IUnobligateOutcome {
+    obligationUid: string;
+    invalidated: true;
+}
+/**
+ * The three leaf questions the grammar can ask. Implemented by each caller's
+ * own resolver — C5's tx-backed `evaluateTransitionGateTx` and C6's verdict
+ * resolver — because the leaf lookups are the ONLY part that touches storage;
+ * the composition is {@link evaluatePredicate}'s job alone.
+ */
+export interface IPredicateResolver {
+    /** Distinct attestations of `claim.kind === kind` whose `check.state === 'verified'`. */
+    countVerifiedAttestations(kind: string): Promise<number>;
+    /** `true` iff every incoming live `blocks` edge's source issue is terminal; a missing status is non-terminal (fail-closed). */
+    blockersAllTerminal(): Promise<boolean>;
+    /** `true` iff a live edge of `type` exists with the subject as `dst` (`in`) or `src` (`out`). */
+    relationExists(type: string, direction: IRelationDirection): Promise<boolean>;
+}
+/**
+ * Recursive validator over the closed core — throws {@link InvalidPredicateError}
+ * on an unknown `op`, a missing/ill-typed leaf, an unexpected extra key, a
+ * non-array `all_of`/`any_of` `of`, or `evidence.min < 1`. Runs BEFORE any
+ * transaction opens.
+ */
+export declare function assertValidPredicate(pred: unknown): asserts pred is IPredicate;
+/**
+ * Pure evaluator — the ONE implementation of the grammar's semantics, shared
+ * by the C5 write gate (tx-backed resolver) and the C6 verdict (graph-backed
+ * resolver). NOT re-implemented per caller (adhd ADR-0002).
+ *
+ * **Documented short-circuits:** an empty `all_of` is `true`, an empty `any_of`
+ * is `false`, and `not` of an empty `any_of` is therefore `true`.
+ *
+ * **Fail-closed:** a resolver rejection propagates — it is never coerced to
+ * `true`. A gate that cannot determine a leaf must refuse, not pass.
+ */
+export declare function evaluatePredicate(pred: IPredicate, resolver: IPredicateResolver): Promise<boolean>;
+/**
+ * Declare an obligation on a live issue. One `immediate` transaction: resolve
+ * the issue (`resolveLiveIssueTx`), write the `obligation` node, resolve
+ * `has_obligation`, write the edge, and audit `'obligated'`. The subject issue
+ * is NEVER mutated — no column, no `meta` touch, no stored status.
+ *
+ * Validation (`assertValidPredicate`, `applies_to.to` required, `on_fail` ∈
+ * `{block,warn}`, override shape) runs BEFORE `executeWriteTransaction`, so a
+ * malformed predicate never holds the write lock.
+ *
+ * Errors: `InvalidArgumentError` (blank `uid`/`by`, omitted/blank
+ * `applies_to.to`, bad `on_fail`, malformed override),
+ * `InvalidPredicateError` (the closed-core grammar), `IssueNotFoundError`,
+ * `StaleSupersedeError`, `WriteContentionError`/`WriteIOError` (§4c).
+ */
+export declare function obligate(handle: IWriteStoreHandle, input: IObligateInput): Promise<IObligateOutcome>;
+/**
+ * Retire an obligation. One `immediate` transaction: resolve `obligationUid` to
+ * a live `obligation` node (else {@link ObligationNotFoundError}),
+ * soft-invalidate it (`UPDATE node SET t_invalid = ?, meta = <merged
+ * invalidatedAt/invalidatedReason> WHERE rowid = ?` — the `delete.ts` /
+ * `rmLocation` bi-temporal shape), invalidate the owning `has_obligation` edge,
+ * and audit `'unobligated'`. Never a hard delete — the row and its trail stay
+ * readable; it simply stops appearing on the card.
+ *
+ * Errors: `InvalidArgumentError` (blank `obligationUid`/`by`),
+ * `ObligationNotFoundError`, `WriteContentionError`/`WriteIOError` (§4c).
+ */
+export declare function unobligate(handle: IWriteStoreHandle, input: IUnobligateInput): Promise<IUnobligateOutcome>;

package/write/relate.d.ts

@@ -1,7 +1,7 @@
 import { IWriteStoreHandle } from './tx.js';
 
 /** The closed `rel` union `relate` accepts (§3/§6.3.6) — issue → issue in every case. */
-export type RelateRel = 'relates_to' | 'supersedes' | 'blocks' | 'duplicate_of' | 'part_of';
+export type RelateRel = 'relates_to' | 'supersedes' | 'blocks' | 'duplicate_of' | 'part_of' | 'similar_to';
 export interface IRelateInput {
     /** The relation's SOURCE `issue` uid (§1: uid is the only identifier — never a name, never repo-scoped). */
     sourceUid: string;

package/write/revision.d.ts

@@ -0,0 +1,27 @@
+/**
+ * revision.ts — the issue content-revision counter (DESIGN §2 Primitive 1/4).
+ *
+ * One revision counter, one name: `subject.revision` (Primitive 2) and
+ * `source_revision` (Primitive 4) are the SAME quantity — a monotonic counter
+ * on the issue's own `meta.revision`, bumped on every mutating write. A check
+ * or a verdict is stale relative to this one counter, so it must be read
+ * through one function rather than each consumer re-deriving it.
+ *
+ * This module is pure (no store, no I/O): it reads only the `meta` blob a
+ * caller already has in hand. `C6`'s verdict layer owns the bump sites
+ * (`create-issue` seeds `revision: 0`; `update`/`transition`/`claim`/`relate`/
+ * `move` set `nextRevision(priorMeta)`); `attest`/`recheck` deliberately do
+ * NOT bump, because they never touch the subject.
+ *
+ * A never-mutated issue (no `meta.revision` at all, e.g. every issue created
+ * before the counter existed) reads as `0`, so the pre-counter corpus is
+ * consistent without a backfill.
+ */
+/**
+ * The monotonic revision of an issue's content — `0` for a never-mutated
+ * issue. A non-finite or non-numeric stored value (a malformed `meta` blob)
+ * degrades to `0` rather than propagating `NaN` into a comparison.
+ */
+export declare function readRevision(meta: Record<string, unknown> | undefined): number;
+/** `readRevision(meta) + 1` — the revision a mutating write stamps onto its node. */
+export declare function nextRevision(meta: Record<string, unknown> | undefined): number;

package/write/similarity-scan.d.ts

@@ -0,0 +1,84 @@
+import { StoreSearchBackend } from '@adhd/sox-hybrid-search';
+import { GraphBackend } from '@adhd/sox-graph-store';
+
+/** The search/graph substrate the scan needs — structurally compatible with the create gate's `IDuplicateScanHandle`. */
+export interface ISimilarityScanHandle {
+    readonly graph?: GraphBackend;
+    readonly search?: {
+        readonly backend: StoreSearchBackend;
+        embedQuery?(text: string): Promise<Float32Array>;
+    };
+}
+/** Why the scan could not produce a calibrated comparison — never a generic "unavailable". */
+export type SimilarityScanDegradedReason = 'no-search-backend' | 'no-embed-query' | 'no-vector-scores';
+/** One advisory similarity candidate, with the provenance a reviewer needs to judge it across projects. */
+export interface ISimilarCandidate {
+    uid: string;
+    title: string;
+    /** Cosine similarity in `[0,1]`, straight off the vector channel. */
+    score: number;
+    scope: 'same-project' | 'cross-project';
+    provenance?: {
+        projectUid: string;
+        projectName: string;
+        componentUid?: string;
+        repoUrl?: string;
+    };
+    /** Which independent signals fired, e.g. `['cosine','title-tokens']`. */
+    signals?: string[];
+}
+export interface ISimilarityScanInput {
+    title: string;
+    body: string;
+    scope: 'same-project' | 'multi-project' | 'store-wide';
+    /** Required for `same-project`/`multi-project`: the filing project. */
+    projectUid?: string;
+    sameProjectThreshold: number;
+    crossProjectThreshold: number;
+    margin: number;
+    tokenOverlapMin: number;
+    limit?: number;
+    /**
+     * The filing item's own citation tokens / component path — the "A" side of
+     * the structural signal. Optional: absent means the structural signal can
+     * only ever fire on the candidate's side, which is the correct default for a
+     * caller with no new-item context (the view cluster scan).
+     */
+    citationTokens?: readonly string[];
+    componentPath?: string;
+    /** Ids the scan must EXCLUDE (the declared `dedupeExcludeUid` parent + its `part_of` ancestor chain). */
+    excludeIds?: ReadonlySet<number>;
+}
+/** The richer outcome {@link scanSimilarCandidatesWithMeta} returns; {@link scanSimilarCandidates} is its candidates-only projection. */
+export interface ISimilarityScanOutcome {
+    candidates: ISimilarCandidate[];
+    degraded: boolean;
+    degradedReason?: SimilarityScanDegradedReason;
+}
+/**
+ * Citation-derived structural tokens + owning component path for one issue.
+ *
+ * Exported so BOTH scan callers can supply the A-side of the AC7 structural
+ * signal from a real stored item: the `view:'similar'` cluster block derives
+ * its seed's context with this directly (the seed is already written), while
+ * the create-time gate derives the not-yet-written filing item's context from
+ * its input in `write/create-issue.ts`.
+ */
+export declare function structuralContextFor(graph: GraphBackend, issueId: number): Promise<{
+    citationTokens: string[];
+    componentPath?: string;
+}>;
+/**
+ * The scan, with its degraded-mode metadata. Returns `{candidates:[], degraded:false}`
+ * when the scope is a COMPLETE scan of nothing (the scope resolves to an empty
+ * candidate set, or every candidate was excluded); returns a degraded outcome
+ * when there ARE rows to compare against but the calibrated (vector) channel
+ * could not answer — the distinction the create gate's `abort` fails closed on.
+ */
+export declare function scanSimilarCandidatesWithMeta(handle: ISimilarityScanHandle, input: ISimilarityScanInput): Promise<ISimilarityScanOutcome>;
+/**
+ * The candidates-only projection of {@link scanSimilarCandidatesWithMeta}
+ * (the C9 spec's stated signature): best-first, advisory, never writes, and
+ * `[]` when the embedding substrate is absent.
+ */
+export declare function scanSimilarCandidates(handle: ISimilarityScanHandle, input: ISimilarityScanInput): Promise<ISimilarCandidate[]>;

package/write/spec-revision.d.ts

@@ -0,0 +1,131 @@
+import { IWriteStoreHandle } from './tx.js';
+import { GraphBackend, NodeRecord } from '@adhd/sox-graph-store';
+
+/** The long-form file export an anchor points at: `locator + digest` (Primitive 2) — referenced, never embedded. */
+export interface ISpecAnchor {
+    locator: string;
+    digest: string;
+}
+/**
+ * Immutable revision object metadata (node `kind: 'SPEC'`). The node's
+ * `content` column holds the FRAGMENT appended at this revision (the delta; the
+ * base revision's fragment IS the base document). No revision stores a full
+ * snapshot — the document is the fold over the chain's `content` values and
+ * `revision_token` is the hash of that fold.
+ */
+export interface ISpecRevisionMeta {
+    /** The ticket's logical id (the head resolved at append time) — see the module header. */
+    spec_of: string;
+    /** 1,2,3… monotonic within the spec. */
+    revision_seq: number;
+    /** `'sha256:<hex>'` of the FOLDED document at this revision. */
+    revision_token: string;
+    /** Predecessor revision uid (`null` for the base revision). */
+    prev_revision: string | null;
+    /** The long-form file export (Primitive 2). */
+    anchor: ISpecAnchor;
+    appended_by: string;
+    appended_at: string;
+}
+export interface ISpecAppendInput {
+    /** The ticket's logical id — any uid on its `SUPERSEDES` chain is resolved forward. */
+    uid: string;
+    /** The delta appended at this revision (becomes the node's `content`). */
+    fragment: string;
+    /** The file export for this revision. */
+    anchor?: ISpecAnchor;
+    /** REQUIRED CAS token — the revision uid the caller read (`''` when the ticket had no spec yet). */
+    base_revision: string;
+    by: string;
+}
+export interface ISpecAppendOutcome {
+    /** UNCHANGED — cross-checked by AC1. */
+    uid: string;
+    /** The NEW revision uid. */
+    spec_revision: string;
+    /** `'sha256:<hex>'`. */
+    spec_revision_token: string;
+    revision_seq: number;
+}
+/** Current revision + its token for a work item. */
+export interface ISpecPointer {
+    revision_uid: string;
+    revision_token: string;
+    revision_seq: number;
+}
+/**
+ * The store surface {@link appendSpecRevision} needs. Beyond the ordinary write
+ * handle it requires the store's `GraphBackend`, because revision DISCOVERY must
+ * run the SAME live-kind traversal the read path (`deriveSpecHead`) and the
+ * reconciliation (`spec-revision.reconcile.ts`) use — and that traversal
+ * (`query/resolve.ts`'s `resolveEdgeScopedCandidates`) is a `GraphBackend` read
+ * that must run BEFORE the `BEGIN IMMEDIATE` transaction opens (a `GraphBackend`
+ * call never runs inside it — see `resolveLogicalHeadTx`). `GraphBacklogStore`
+ * and the test `TestIssueStore` both satisfy this shape.
+ */
+export type ISpecAppendStore = IWriteStoreHandle & {
+    readonly graph: GraphBackend;
+};
+/**
+ * Rowids of live items whose DECLARED catalog kind is `SPEC` — an
+ * `issue`-shaped node carrying a live `has_kind` edge to the `kind:'SPEC'`
+ * catalog row. This is the SHIPPED production shape: the reconciled corpus is
+ * `issue` nodes whose DECLARED kind is `SPEC`, and reconciliation stamps them
+ * `spec_of`/`revision_seq` WITHOUT changing the raw `node.kind` column. Any
+ * discovery keyed on the raw column alone is therefore blind to them.
+ *
+ * Uses the SAME live-kind traversal the read path's `filter.kind`
+ * (`query/views/semantic.ts`) and `spec-revision.reconcile.ts` use —
+ * `query/resolve.ts`'s {@link resolveEdgeScopedCandidates} on
+ * `has_kind`→`SPEC` — so read, write, and reconcile can never disagree on what
+ * "a live `kind:'SPEC'` item" is. Returns `undefined` when `SPEC` resolves to
+ * no live catalog row (nothing is declared SPEC).
+ */
+export declare function declaredSpecRowids(graph: GraphBackend): Promise<ReadonlySet<number> | undefined>;
+/**
+ * Every live SPEC document — the UNION of two representations the store has
+ * held, both of which are specs:
+ *
+ *  (a) a node whose RAW `kind` column is `SPEC` — the immutable revision object
+ *      {@link appendSpecRevision} mints (and the shape the unit fixtures
+ *      build); and
+ *  (b) an `issue` node whose DECLARED catalog kind is `SPEC` — the reconciled
+ *      production corpus (see {@link declaredSpecRowids}).
+ *
+ * This is the ONE discovery the read path ({@link deriveSpecHead}), the write
+ * path (`findChainHeadTx` via {@link declaredSpecRowids}), and the
+ * reconciliation all share, so they cannot drift on which items are specs. The
+ * union is load-bearing: a raw-kind-only reader missed shape (b) entirely.
+ */
+export declare function discoverLiveSpecNodes(graph: GraphBackend): Promise<NodeRecord[]>;
+/**
+ * Append a revision. One `BEGIN IMMEDIATE` transaction (ADR-0001 + ADR-0012 —
+ * no temp-file/rename/flock; atomicity is the store's job):
+ *
+ *  1. resolve `uid` → logical head (input may be any `SUPERSEDES`-chain uid — AC9);
+ *  2. read the current revision; if it is not `base_revision` →
+ *     {@link SpecRevisionConflictError} (stale base — no write; AC6);
+ *  3. write a NEW `kind:'SPEC'` node holding the fragment (AC1/AC8);
+ *  4. advance the ticket's `meta.spec_revision` IN PLACE via the CAS helper,
+ *     bumping `meta.revision` — the uid is preserved (AC1);
+ *  5. `writeAudit(action:'spec-appended')`.
+ *
+ * NEVER update or delete a revision node (AC1/AC8).
+ */
+export declare function appendSpecRevision(handle: ISpecAppendStore, input: ISpecAppendInput): Promise<ISpecAppendOutcome>;
+/**
+ * The derived chain head for a ticket — a live `SPEC` node whose
+ * `meta.spec_of` is in the ticket's `SUPERSEDES`-chain uid set with the max
+ * `meta.revision_seq` (read-path analogue of {@link findChainHeadTx}, backed by
+ * the same reconciliation-created functional index). `undefined` when the ticket has
+ * no live revision.
+ */
+export declare function deriveSpecHead(graph: GraphBackend, uid: string): Promise<ISpecPointer | undefined>;
+/** The pointer ON THE RECORD only (`meta.spec_revision`) — never the derived head. Used by the staleness cross-check. */
+export declare function readPointerRecord(graph: GraphBackend, uid: string): Promise<ISpecPointer | undefined>;
+/**
+ * Current revision + its token for a work item (`undefined` if it has no spec).
+ * Prefers the on-record pointer; falls back to the derived chain head so a
+ * ticket whose pointer was not (yet) written — pre-reconciliation data — still reads.
+ */
+export declare function readSpecPointer(graph: GraphBackend, uid: string): Promise<ISpecPointer | undefined>;

package/write/spec-revision.reconcile.d.ts

@@ -0,0 +1,48 @@
+import { IWriteStoreHandle } from './tx.js';
+import { GraphBackend } from '@adhd/sox-graph-store';
+
+/** The store surface the reconciliation needs — satisfied by `GraphBacklogStore` and the test store alike. */
+export type ISpecReconcileStore = IWriteStoreHandle & {
+    readonly graph: GraphBackend;
+};
+export interface ISpecReconcileStamp {
+    revisionUid: string;
+    /** The logical id stamped onto `meta.spec_of` (the ticket's head). */
+    specOf: string;
+    revisionSeq: number;
+    prevRevision: string | null;
+    revisionToken: string;
+    /** `false` when the node already carries exactly this stamp (skip the write). */
+    needsStamp: boolean;
+}
+export interface ISpecReconcileHead {
+    ticketUid: string;
+    revisionUid: string;
+    revisionToken: string;
+    revisionSeq: number;
+    /** `false` when the ticket's pointer already names this head with this token. */
+    needsPointer: boolean;
+}
+export interface ISpecReconcileReport {
+    /** How many live `SPEC` nodes were discovered. */
+    scanned: number;
+    stamps: ISpecReconcileStamp[];
+    heads: ISpecReconcileHead[];
+    /** `SPEC` nodes already stamped (idempotent no-op). */
+    alreadyStamped: number;
+    /** `SPEC` nodes with no live `part_of` parent — left untouched, reported. */
+    orphaned: string[];
+    /** Whether the lookup index exists after this call. */
+    indexCreated: boolean;
+}
+/**
+ * Compute the reconciliation plan WITHOUT writing (the dry-run). Discovery is
+ * `query`-driven; nothing is mutated.
+ */
+export declare function planSpecRevisionReconcile(store: ISpecReconcileStore): Promise<ISpecReconcileReport>;
+/**
+ * Apply the reconciliation. Idempotent: an already-stamped `SPEC` and an
+ * already-pointed ticket are both skipped, so a second run is a no-op. One
+ * `BEGIN IMMEDIATE` transaction (ADR-0001) — never a hard delete.
+ */
+export declare function applySpecRevisionReconcile(store: ISpecReconcileStore): Promise<ISpecReconcileReport>;

package/write/transition.d.ts

@@ -1,5 +1,5 @@
 import { IWriteStoreHandle } from './tx.js';
-import { ICitationInput } from './create-issue.js';
+import { ICitation } from '../citation.js';
 
 export interface ITransitionInput {
     /** The `issue` uid to transition (§6.3, an "Issue verb"). */
@@ -11,7 +11,7 @@ export interface ITransitionInput {
     /** 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;
     /** REQUIRED (≥1) when `project_policy.citation_required` is `true` AND `toStatus` resolves to a terminal status. Written as `citation` nodes + `has_citation` edges exactly like `create`'s own citations. */
-    citations?: ICitationInput[];
+    citations?: ICitation[];
     /**
      * The item-level disclosure-contract git context — the SAME plain metadata
      * scalar `create`'s own `gitContext` field writes (repo `AGENTS.md`'s "Cite
@@ -22,6 +22,17 @@ export interface ITransitionInput {
      * per-citation `ref` — it rides the issue, never a `citation` node.
      */
     gitContext?: string;
+    /**
+     * A recorded override of a refusing obligation (C5, DESIGN §2 Primitive 3).
+     * Honoured ONLY when the caller is in the refusing obligation's
+     * `override.actors`; a reason is ALWAYS required (never a configurable
+     * boolean) and is recorded on the audit row. A claimed override by a
+     * non-listed actor, or one with a blank reason, throws
+     * `OverrideNotPermittedError`.
+     */
+    override?: {
+        reason: string;
+    };
 }
 export interface ITransitionOutcome {
     uid: string;

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.
  *
@@ -140,7 +162,7 @@ export declare function resolveLiveIssueTx(tx: AdapterTransaction, uid: string):
 /** rowid → node, inside a tx (used to resolve an edge endpoint's kind without a redundant round trip when the caller doesn't already know it). */
 export declare function getNodeByRowidTx(tx: AdapterTransaction, rowid: number): Promise<ITxNodeRow | null>;
 export interface IWriteNodeTxInput {
-    /** The entity-type discriminator — `project`/`component`/`location`/`issue`/`kind`/`edge_kind`/`status`/`priority`/`agent`/`note`/`citation`/`transition`/`audit` (§3). NEVER validated against a closed vocabulary here — the schema is open by design (§0 anti-antipattern 3); the write layer is the only composer of these literals. */
+    /** The entity-type discriminator — `project`/`component`/`location`/`issue`/`kind`/`edge_kind`/`status`/`priority`/`agent`/`note`/`citation`/`transition`/`audit`/`attestation`/`obligation`/`SPEC` (§3; the SPEC revision kind is added by C10, DESIGN §12). NEVER validated against a closed vocabulary here — the schema is open by design (§0 anti-antipattern 3); the write layer is the only composer of these literals. */
     kind: string;
     /** The business name (`issue.title`, a catalog row's name, …). Omit for a node with no name (none currently exist in §3's table, but the column is nullable). */
     name?: string;
@@ -306,6 +328,26 @@ export interface IInvalidateEdgeTxInput {
  * instead of the bare adapter.
  */
 export declare function invalidateEdgeTx(tx: AdapterTransaction, input: IInvalidateEdgeTxInput): Promise<void>;
+/**
+ * Update a LIVE node's `meta` IN PLACE inside `tx`, CAS-guarded on the node's
+ * own `meta.revision` counter (SR-2 monotonic revision + SR-6 per-node CAS,
+ * per DESIGN §2 Primitive 1's "node's monotonic `revision`, bumped on every
+ * mutating write"). Preserves `uid` — this is the ONLY write path that mutates
+ * a node without superseding it, and it exists solely for the C10 spec pointer
+ * (`meta.spec_revision`) and the SR-2 counter it bumps. No other verb may adopt
+ * it without a new decision.
+ *
+ * `patch`'s keys are shallow-merged over the node's existing meta; the merged
+ * blob's `revision` is set to `expectedRevision + 1`. Returns the new revision
+ * number on success, or `null` when the node is missing OR the stored revision
+ * no longer equals `expectedRevision` (a concurrent writer won the CAS — the
+ * caller must surface a stale-base error, and because this runs inside the
+ * caller's own `BEGIN IMMEDIATE` transaction, a thrown error rolls the whole
+ * transaction back). A node with no `meta.revision` at all reads as revision
+ * `0` (matching `revision.ts`'s `readRevision`), so a pre-counter row is
+ * CAS-addressable without a backfill.
+ */
+export declare function updateNodeMetaTx(tx: AdapterTransaction, uid: string, patch: Record<string, unknown>, expectedRevision: number): Promise<number | null>;
 /**
  * The one transaction wrapper every write verb calls — `store.adapter.transaction(fn,
  * {mode: resolveTransactionMode()})`, which is `'immediate'` (§4c: `BEGIN

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;

package/write/update.d.ts

@@ -1,4 +1,5 @@
 import { IWriteStoreHandle } from './tx.js';
+import { ICitation } from '../citation.js';
 
 export interface IUpdateIssueInput {
     /** The `issue` uid to update (§6.3, an "Issue verb"). */
@@ -17,6 +18,27 @@ export interface IUpdateIssueInput {
     assignee?: string;
     /** catalog agent name/uid; → `touch` + `authored_by` edge rewrite. An unresolved NAME mints; a uid-shaped ref that does not resolve throws `CatalogNotFoundError('agent', ref)`. */
     author?: string;
+    /**
+     * The DESIRED set of citations this issue should carry after this call — a
+     * DIFF-EMITTER, never a body rewrite (the architecture verdict): the live
+     * citation set is read inside the SAME `immediate` transaction, citations
+     * present live but absent from `citations` are removed (bi-temporally), and
+     * citations in `citations` but not live are added. Identity for the diff is
+     * `(file, lines, revision)` (§ `citationKey`), never `sha`/`context`.
+     *
+     * Routing a citation change through `body`/`supersede` is FORBIDDEN: that
+     * would mint a new issue uid and violate §1's "uid is the only identity".
+     * When `body` IS also given, the supersede mints the new node first, its
+     * live citations are carried forward, and THIS diff is applied against the
+     * carried-forward set on the new node — still inside the one transaction.
+     *
+     * Each citation's `sha` is computed (and policy-gated, exactly as `create`/
+     * `transition` do) before the transaction opens, so the write lock is never
+     * held across a filesystem/git read. `citations: []` clears every live
+     * citation. Omitted entirely ⇒ citations are untouched (and carried forward
+     * verbatim on a body edit).
+     */
+    citations?: ICitation[];
     /**
      * §4b/§6.2 — waits for the fire-and-forget on-write embedding round-trip
      * before `update` returns, when `true` and `handle.embedding` is
@@ -30,7 +52,7 @@ export interface IUpdateIssueInput {
      */
     awaitEmbed?: boolean;
 }
-export type IUpdateIssueChangedField = 'title' | 'body' | 'kind' | 'priority' | 'assignee' | 'author';
+export type IUpdateIssueChangedField = 'title' | 'body' | 'kind' | 'priority' | 'assignee' | 'author' | 'citations';
 export interface IUpdateIssueOutcome {
     /**
      * The resulting CURRENT issue's uid — the SAME `input.uid` when `body` was