@adhd/backlog 0.1.9 → 1.0.0

package/write/tx.d.ts

@@ -0,0 +1,344 @@
+import { BacklogWriteError } from './errors.js';
+import { TypePolicy } from '@adhd/sox-graph-store';
+import { AdapterTransaction, StoreAdapter } from '@adhd/sox-store-adapter';
+
+/**
+ * The on-write embedding substrate (§4b, FEAT-021) — the narrow slice of
+ * `semanticBackend`/`SemanticBackend` (`store/semantic-search.ts`,
+ * reference-only) this write layer actually needs. Deliberately NOT the
+ * spec's own `createEmbeddingObserver(semanticBackend)` shape: that observer
+ * is constructed from a `GraphWriteObserver` and registered with
+ * `createGraphBackend`'s `observers` option, so it only ever fires from
+ * INSIDE the library's own `writeNode`/`writeNodeInTx` (`GraphWriteObserver.
+ * onNodeWritten`, verified against the published `@adhd/sox-graph-store`
+ * dist) — a hook this file's entire premise is that the write layer
+ * structurally never reaches, because every write here goes through the
+ * hand-composed, tx-scoped primitives below instead of the library's own
+ * autocommitting methods (this file's own opening doc comment). So §4b's
+ * "AFTER the write layer's `immediate` transaction has committed" contract is
+ * satisfied here by explicit, write-verb-owned invocation (see
+ * `embedding-observer.ts`'s `scheduleIssueEmbedding`) rather than an
+ * observer callback — the write verb itself IS the thing that knows the
+ * subject transaction just committed, so it is the thing that calls this
+ * interface's methods, once, right after `executeWriteTransaction` resolves.
+ *
+ * `embedDocument`/`upsertVector`/`deleteVector` only — no query-side method
+ * (`knn`/`embedQuery`/`iterVectors`) belongs here: those are `query/**`'s
+ * concern (`IQueryStoreHandle.search`, `query/views/semantic.ts`), out of
+ * this slice's scope to touch.
+ */
+export interface IEmbeddingBackend {
+    /** The embedding model identifier stamped alongside every vector this backend writes/deletes — passed straight through to `upsertVector`/`deleteVector`'s own `modelId` so a caller wiring multiple models never mixes spaces. */
+    readonly modelId: string;
+    /** Embeds `content` (the issue's `${title}\n${body}` text — see `embedding-observer.ts`'s own doc comment on why this MUST be composed identically to `create-issue.ts`'s `scanForDuplicates`). Rejects on a provider failure — never swallowed here; the caller (`scheduleIssueEmbedding`) is what degrades a rejection to a logged `embedding_failed` audit row (§4b). */
+    embedDocument(content: string): Promise<Float32Array>;
+    /** Upserts `vector` for graph node `nodeRowid` (the SAME numeric value `writeNodeTx`/`writeAudit` already track as `.rowid` — never `uid`, per `@adhd/sox-vector-store`'s own `id`-is-rowid convention, confirmed against `query/views/semantic.spec.ts`'s `indexIssue` helper). */
+    upsertVector(nodeRowid: number, vector: Float32Array): Promise<void>;
+    /** Deletes any vector stored for `nodeRowid` under `this.modelId`. A no-op (never throws) when no vector was ever stored for that rowid — mirrors `AsyncVectorBackend.delete`'s own idempotent contract (`@adhd/sox-vector-store`). */
+    deleteVector(nodeRowid: number): Promise<void>;
+}
+/**
+ * The dependencies a write verb needs to open its own `immediate` transaction
+ * and validate the edges it writes. Constructed once at store-open time (out
+ * of scope for this slice — see the store-bootstrap file that wires
+ * `createGraphBackend`'s own `typePolicy` option, DATA_MODEL.md §0 point 5)
+ * and threaded through every write verb.
+ */
+export interface IWriteStoreHandle {
+    /** The `StoreAdapter` the backlog store exposes — never `GraphBackend.transaction`, which cannot request `immediate` mode (§4c). */
+    readonly adapter: StoreAdapter;
+    /**
+     * The SAME injected `TypePolicy` instance the store's `GraphBackend` was
+     * constructed with (or `DEFAULT_TYPE_POLICY` — though the spec requires an
+     * open-schema policy be injected, DATA_MODEL.md §0 point 5). `writeEdgeTx`
+     * calls this directly, in-process, never through `writeEdge` (§2).
+     */
+    readonly typePolicy: TypePolicy;
+    /**
+     * §4b's on-write embedding substrate — OPTIONAL, mirroring
+     * `IDuplicateScanHandle.search`'s own "never silently go dark, but also
+     * never hard-fail when unwired" posture (`create-issue.ts`). Absent →
+     * `scheduleIssueEmbedding` (`embedding-observer.ts`) is a true no-op: no
+     * embed attempt, no `embedding_*` audit row, nothing logged — filing/
+     * updating an issue must never depend on RAG being configured in a given
+     * environment. Present → every genuine create and every body-changing
+     * update schedules a post-commit embed/audit round-trip (see
+     * `embedding-observer.ts`'s own doc comment for the exact verb-by-verb
+     * wiring and the touch-vs-supersede scope decision).
+     */
+    readonly embedding?: IEmbeddingBackend;
+}
+/** A node row as read back inside a transaction, mapped onto the fields the write layer needs. */
+export interface ITxNodeRow {
+    rowid: number;
+    uid: string;
+    kind: string;
+    name: string | null;
+    content: string;
+    metadata: Record<string, unknown> | undefined;
+    tInvalid: string | null;
+    isSuperseded: boolean;
+}
+/** Current UTC timestamp in the same ISO-8601 shape `@adhd/sox-graph-store` stamps every row with. */
+export declare function nowISO(): string;
+/** `sha256` hex digest of arbitrary string/Buffer content — used for citation and audit content-addressing (§4a/§8.5), never for the library's own dedupe hash (that stays trim+lowercase, see {@link writeNodeTx}). */
+export declare function sha256Hex(input: string | Buffer): string;
+/**
+ * Deterministic JSON serialization with keys sorted at every level — the
+ * "canonical JSON serialization... with stable (sorted) key order" DATA_MODEL.md
+ * §10 point 2 defines for `transition.sha` and states is "the same convention
+ * SPEC.md §4a already states for the audit `sha`, applied identically."
+ * `undefined` values are omitted (never serialized as `null` silently — a
+ * caller that means "explicitly null" must pass `null`, not omit the key).
+ */
+export declare function canonicalJSONStringify(value: Record<string, unknown>): string;
+/**
+ * uid → node, inside a tx. Mirrors `getNodeByUid`'s own SELECT
+ * (`SELECT * FROM node WHERE uid = ?`, `@adhd/sox-graph-store` dist/index.js:1573-1576)
+ * 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>;
+/**
+ * Resolves `uid` to the CURRENT, live `issue` row, or throws.
+ *
+ * Every issue verb needs exactly this, and the check is in two parts that are
+ * easy to half-implement:
+ *
+ *  - `tInvalid !== null` — the issue was soft-deleted (`delete.ts`).
+ *  - `isSuperseded` — the issue's body was edited, so `update.ts` minted a
+ *    NEW node with a new uid and flipped this row's `is_superseded` flag.
+ *    **The supersede CAS sets `is_superseded` ONLY; it never touches
+ *    `t_invalid`** (update.ts's `UPDATE node SET is_superseded = 1 WHERE
+ *    rowid = ? AND is_superseded = 0`). So a superseded row is still
+ *    `t_invalid IS NULL`, and a `tInvalid`-only guard lets a stale uid
+ *    straight through.
+ *
+ * That second half was missing from `claim`, `relate`, `move` and `delete`
+ * while `update` and `transition` each had their own hand-written copy of it.
+ * The consequences were silent, not loud — this repo is parallel-process
+ * enabled, so a caller holding a uid from before a concurrent body edit is a
+ * real scenario, and it could `claim` a superseded node (two agents each
+ * believing they hold the lease on the same issue), `relate` an edge onto it
+ * (permanently invisible against the issue's real uid, since `card.ts` never
+ * walks SUPERSEDES chains), or `delete` it and be told `invalidated: true`
+ * while the live issue was untouched.
+ *
+ * It exists as ONE function, rather than as a documented convention, because
+ * the convention is exactly what failed: six verbs hand-duplicated the fetch
+ * and four dropped half the guard. A new verb that calls this cannot
+ * reproduce the gap; a new verb that hand-rolls `getNodeByUidTx` can, so
+ * prefer this everywhere an issue uid arrives from a caller.
+ *
+ * @throws IssueNotFoundError when no row carries `uid`, it is not an `issue`,
+ *   or it has been soft-deleted.
+ * @throws StaleSupersedeError when `uid` names a superseded node — the uid was
+ *   valid once and names a real row, so this is deliberately NOT reported as
+ *   "not found": the caller's reference is stale, not wrong.
+ */
+export declare function resolveLiveIssueTx(tx: AdapterTransaction, uid: string): Promise<ITxNodeRow>;
+/** 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. */
+    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;
+    /** The content column. Defaults to `name` when omitted (mirrors `findOrCreateNode`'s own `opts?.content ?? name` convention, `@adhd/sox-graph-store` dist/index.js:1446). */
+    content?: string;
+    metadata?: Record<string, unknown>;
+    /**
+     * The ISO-8601 timestamp stamped onto this row's `t_occurred`/`t_created`/
+     * `t_valid` columns. Optional; defaults to a fresh {@link nowISO}() call
+     * when omitted, so an existing single-row call site compiles and behaves
+     * unchanged.
+     *
+     * A caller composing ONE logical write out of several rows (e.g.
+     * `createIssue`'s issue node + N citation nodes + the `writeAudit` audit
+     * node, all inside the SAME `executeWriteTransaction` callback) MUST
+     * capture a single `const now = nowISO()` up front and pass it as `at` to
+     * EVERY {@link writeNodeTx} (and {@link writeEdgeTx}) call in that closure.
+     * Without this, each call computes its own fresh, microseconds-later
+     * `nowISO()`, so the issue node's persisted `t_created`, the citations'
+     * `t_created`, and the audit row's recorded `at` all drift apart within
+     * what is supposed to be one atomic, single-instant write — breaking the
+     * guarantee (§4a) that the audit's `at` describes exactly when the subject
+     * it records was created.
+     */
+    at?: string;
+    /**
+     * NOT a real input — {@link writeNodeTx} unconditionally never dedupes (see
+     * its own doc comment below) and never reads a dedupe flag off `input` at
+     * all. Declared here ONLY as `never` so that a future call site which
+     * writes `{ ..., skipDedupe: true }` (or `false`) — believing, from having
+     * read the library's own `writeNodeInTx` signature, that this is a real
+     * per-call toggle — fails to COMPILE (excess-property check on an object
+     * literal) instead of silently having the property ignored. SPEC.md §1/§4
+     * state "All entity writes pass `skipDedupe: true`" with NO kind-scoped
+     * exception anywhere in the spec — every kind this write layer ever
+     * composes (`project`/`component`/`location`/`issue`/`kind`/`edge_kind`/
+     * `status`/`priority`/`agent`/`note`/`citation`/`transition`/`audit`,
+     * SPEC.md §3) skips dedupe unconditionally, so there is no legitimate
+     * call-site variance to gate: the safest surface for "always true" is a
+     * surface that cannot express anything else.
+     */
+    skipDedupe?: never;
+}
+/**
+ * Hand-composed node INSERT, issued against `tx`. Mirrors `writeNodeInTx`'s
+ * own INSERT column list and defaults EXACTLY (`@adhd/sox-graph-store`
+ * dist/index.js:1410-1421) with `skipDedupe: true` UNCONDITIONALLY in every
+ * normal run — the spec §1 requires this on every entity write ("two
+ * identical-body issues are two rows, never one collapsed row") — so this
+ * function skips the content-hash SELECT `writeNodeInTx` runs when
+ * `skipDedupe` is falsy, and always inserts a fresh row. `uid` is
+ * `crypto.randomUUID()` — the SAME generator the library uses
+ * (`generateUid()`, dist/index.js:646-648) — so a write-layer-written row is
+ * byte-for-byte indistinguishable in shape from one the library itself would
+ * have written, just composed by hand to stay inside the caller's own
+ * transaction.
+ *
+ * **`skipDedupe` is uncontrollable from any call site, by construction, not
+ * by per-call convention.** {@link IWriteNodeTxInput} has no way to ask this
+ * function to dedupe (its `skipDedupe` field is typed `never` specifically
+ * so no call site can even compile one in). This is deliberate: seven more
+ * write verbs (`update`/`transition`/`claim`/`relate`/`move`/`delete`/
+ * `supersede`) are built on top of this file by separate agents, and
+ * SPEC.md §1/§4 ("All entity writes pass `skipDedupe: true`") name NO kind
+ * that is exempt — the catalog kinds (`kind`/`status`/`priority`/`agent`/
+ * `edge_kind`), the resolved-only kinds (`project`/`component`), and every
+ * subject kind (`issue`/`note`/`citation`/`transition`/`audit`/`location`)
+ * all go through this SAME unconditional INSERT. A future call site cannot
+ * "forget" to pass `skipDedupe: true` because there is no longer any code
+ * path — in this function OR in its input type — where forgetting it would
+ * change behavior. The ONLY door back to the library's own dedupe behavior
+ * is {@link resolveDedupeMode}'s env switch, checked below — negative-control
+ * test use only, never a per-call toggle.
+ */
+export declare function writeNodeTx(tx: AdapterTransaction, input: IWriteNodeTxInput): Promise<{
+    rowid: number;
+    uid: string;
+}>;
+/**
+ * The declared `(rel, source_kind, target_kind, multiplicity)` table the spec
+ * §3 fixes once — the same "typed rels, each name unique with ONE
+ * (source_kind → target_kind)" table, `audits` carrying the one declared
+ * `source_kind: '*'` sentinel (§2). This is DATA the write layer already
+ * knows at compile time; catalog.ts's `resolveEdgeKindTx` reconciles it with
+ * the `edge_kind` catalog ROW (seeded once, never caller-mintable, §1) rather
+ * than re-deriving it from this table on every call.
+ */
+export type EdgeMultiplicity = 'n:1' | '1:n' | 'n:m';
+export interface IEdgeKindRule {
+    rel: string;
+    /** `'*'` is the one declared sentinel (`audits`, §2) — skip the source-kind match for this rule only. */
+    sourceKind: string;
+    targetKind: string;
+    multiplicity: EdgeMultiplicity;
+}
+export interface IWriteEdgeTxInput {
+    srcRowid: number;
+    srcUid: string;
+    srcKind: string;
+    dstRowid: number;
+    dstUid: string;
+    dstKind: string;
+    rel: string;
+    metadata?: Record<string, unknown>;
+    weight?: number;
+    /** The resolved `edge_kind` rule this rel must satisfy (catalog.ts's `resolveEdgeKindTx`). */
+    rule: IEdgeKindRule;
+    typePolicy: TypePolicy;
+    /**
+     * The ISO-8601 timestamp stamped onto this edge's `t_created`/`t_valid`
+     * columns. Optional; defaults to a fresh {@link nowISO}() call when
+     * omitted. Same one-logical-write-one-timestamp rule as
+     * {@link IWriteNodeTxInput.at} — a caller writing several edges (or an
+     * edge alongside node writes) inside one `executeWriteTransaction`
+     * callback should pass the SAME captured `now` to every one of them.
+     */
+    at?: string;
+}
+/**
+ * Edge write, inside a tx (upsert, re-livening included). Mirrors
+ * `writeEdgeInternal`'s own INSERT EXACTLY (`@adhd/sox-graph-store`
+ * dist/index.js:1894-1898) — same `ON CONFLICT(src, dst, rel) DO UPDATE`,
+ * same `t_invalid = NULL` re-livening — issued against `tx` instead of the
+ * bare adapter, never a `writeEdge` call itself (§4c).
+ *
+ * Endpoint-kind validation (§2: resolve `edge_kind`, check `source_kind`/
+ * `target_kind`, THEN call the injected `TypePolicy` directly in-process,
+ * never through `writeEdge`) and multiplicity enforcement both run BEFORE the
+ * INSERT, against the SAME `tx` handle.
+ */
+export declare function writeEdgeTx(tx: AdapterTransaction, input: IWriteEdgeTxInput): Promise<void>;
+/**
+ * Internal — a resolved `edge_kind` rule's declared endpoint kind does not
+ * match the actual endpoint being written. This is a write-layer composition
+ * defect (the caller passed the wrong node as an endpoint), never a
+ * caller-facing input-validation case with its own named class in the spec's
+ * taxonomy — every write-layer call site passes endpoint kinds it just resolved or
+ * wrote itself in the SAME transaction, so this should be unreachable in
+ * practice; it exists to fail loudly rather than silently write a
+ * mismatched edge if that invariant is ever broken by a future verb.
+ */
+export declare class BacklogEdgeKindMismatchError extends BacklogWriteError {
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(rel: string, side: 'source' | 'target', expectedKind: string, actualKind: string);
+}
+export interface IInvalidateEdgeTxInput {
+    srcRowid: number;
+    dstRowid: number;
+    rel: string;
+    reason?: string;
+    /**
+     * The ISO-8601 timestamp stamped onto `t_invalid`/`meta.invalidatedAt`.
+     * Optional; defaults to a fresh {@link nowISO}() call when omitted. Same
+     * one-logical-write-one-timestamp rule as {@link IWriteNodeTxInput.at}.
+     */
+    at?: string;
+}
+/**
+ * Edge invalidate, inside a tx. Mirrors `invalidateEdge` EXACTLY
+ * (`@adhd/sox-graph-store` dist/index.js:1846-1855) — same idempotent
+ * "already invalidated or absent → no-op" behavior — issued against `tx`
+ * instead of the bare adapter.
+ */
+export declare function invalidateEdgeTx(tx: AdapterTransaction, input: IInvalidateEdgeTxInput): Promise<void>;
+/**
+ * The one transaction wrapper every write verb calls — `store.adapter.transaction(fn,
+ * {mode: resolveTransactionMode()})`, which is `'immediate'` (§4c: `BEGIN
+ * IMMEDIATE`, the RESERVED-lock-at-BEGIN "compare-and-swap primitive" every
+ * check-then-act verb in §4's table depends on) in every normal run and only
+ * ever `'deferred'` when a test has explicitly set
+ * `ADHD_BACKLOG_UNSAFE_TX_MODE=deferred` to prove a negative control (see
+ * {@link resolveTransactionMode}'s own doc comment) — with the §4c retry
+ * contract layered on top:
+ *
+ * - A {@link BacklogWriteError} thrown from `fn` (an app-level validation
+ *   failure, or the `supersede` CAS's {@link StaleSupersedeError}) is
+ *   ALREADY a decided, terminal, transport-facing error — rethrown
+ *   immediately, untouched, never reclassified or retried.
+ * - A raw driver-level error is classified via {@link classifyDriverError}.
+ *   `E_CONTENTION` retries up to 3 total attempts (linear backoff 250ms then
+ *   500ms) before surfacing {@link WriteContentionError}. `E_IO`
+ *   (`isDatabaseError(err)` true — a recognized-but-otherwise-unclassified
+ *   database/driver error) surfaces {@link WriteIOError} on the FIRST
+ *   occurrence, never retried — §4c's uniform reason across every write
+ *   class: `writeAudit` (§4a) rides inside literally every write-layer
+ *   transaction as an unguarded, keyless-content INSERT, so a retry whose
+ *   earlier attempt actually committed would silently double the audit
+ *   trail even where the SUBJECT write is safe to retry on its own merits.
+ *   An `E_IO` classification whose `err` is NOT database-shaped at all
+ *   (`isDatabaseError(err)` false — a genuine app-level bug, never a driver
+ *   fault) is rethrown UNTOUCHED instead — never wrapped in
+ *   {@link WriteIOError}, which always asserts `retryable: true`.
+ * - An `E_CONSTRAINT` this function did not already expect as
+ *   {@link StaleSupersedeError} (i.e. a raw, unclassified constraint
+ *   violation — structurally unreachable under the hand-composed
+ *   find-then-create + `immediate`-mode discipline every verb follows, §1)
+ *   is rethrown UNTOUCHED — never swallowed, never coerced into a
+ *   not-actually-specified wrapper class.
+ */
+export declare function executeWriteTransaction<T>(handle: IWriteStoreHandle, fn: (tx: AdapterTransaction) => Promise<T>): Promise<T>;

package/write/update.d.ts

@@ -0,0 +1,81 @@
+import { IWriteStoreHandle } from './tx.js';
+
+export interface IUpdateIssueInput {
+    /** The `issue` uid to update (§6.3, an "Issue verb"). */
+    uid: string;
+    /** The acting identity — an agent or a person (§6.3's opening rule). REQUIRED. */
+    by: string;
+    /** → `touch` (metadata/name only). */
+    title?: string;
+    /** → `supersede` (§3/§4: "body change → supersede... never touch a body"). Mints a fresh `uid` — see {@link IUpdateIssueOutcome.uid}. */
+    body?: string;
+    /** catalog name or uid; → `touch` + `has_kind` edge rewrite (hand-composed invalidate-old + upsert-new, same tx, §4c). An unresolved NAME mints; a uid-shaped ref that does not resolve throws `CatalogNotFoundError('kind', ref)` (§6.1 — minting never applies to a uid). */
+    kind?: string;
+    /** catalog name or uid; → `touch` + `has_priority` edge rewrite. An unresolved NAME mints (rank = one past the current max); a uid-shaped ref that does not resolve throws `CatalogNotFoundError('priority', ref)`. */
+    priority?: string;
+    /** Plain metadata scalar (§6.2) — no edge. */
+    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;
+    /**
+     * §4b/§6.2 — waits for the fire-and-forget on-write embedding round-trip
+     * before `update` returns, when `true` and `handle.embedding` is
+     * configured. Only meaningful on a BODY-changing call (the `supersede`
+     * path) — a pure touch (title/kind/priority/assignee/author only) never
+     * schedules a re-embed at all, so `awaitEmbed:true` on a touch-only patch
+     * is a harmless no-op (see `embedding-observer.ts`'s own doc comment for
+     * why touch is deliberately excluded). On a body change, TWO round-trips
+     * are scheduled (delete the old node's vector, upsert the new node's) —
+     * `awaitEmbed:true` awaits BOTH before returning.
+     */
+    awaitEmbed?: boolean;
+}
+export type IUpdateIssueChangedField = 'title' | 'body' | 'kind' | 'priority' | 'assignee' | 'author';
+export interface IUpdateIssueOutcome {
+    /**
+     * The resulting CURRENT issue's uid — the SAME `input.uid` when `body` was
+     * not given (a pure touch/edge-rewrite on the existing node), or the FRESH
+     * uid the supersede minted when it was (§6.3.2's `create+supersedes`
+     * composition reads exactly this field as "the NEW node the supersede
+     * primitive minted" — `IUpdateIssueOutcome` carries no separate
+     * `supersededUid`, so `input.uid` is that composition's own record of what
+     * was superseded).
+     */
+    uid: string;
+    /**
+     * Every key present in the input with a defined value, and ONLY those keys
+     * (`assertNoSilentlyDiscardedPatchKeys`, carried forward per §6.3.3 as a
+     * general correctness rule, not machinery scoped to any particular patch
+     * shape). Empty is unreachable here — a zero-field patch throws
+     * `InvalidArgumentError` before this outcome is ever constructed.
+     */
+    changed: IUpdateIssueChangedField[];
+}
+/**
+ * Update an issue (§4, §6.3.3). One `immediate` transaction.
+ *
+ * Errors: `InvalidArgumentError` (`uid`/`by` missing/blank; blank `title`/
+ * `body` when given; no fields at all in the patch — a zero-field call is a
+ * client error, not a silent no-op success, since the caller almost
+ * certainly meant a different verb), `BacklogValidationError('status', ...)`
+ * (an untyped caller sent a `status` field — §8 AC-14, this is the ONE
+ * runtime rejection this whole file exists to guarantee, and it names
+ * `transition` in its message), `IssueNotFoundError` (no live `issue` node
+ * carries `uid`, including an already-superseded one — this file's own doc
+ * comment on why that is a deliberate divergence, reusing
+ * `StaleSupersedeError` rather than `IssueNotFoundError` for that specific
+ * case since the identity itself still exists, just not at THIS uid
+ * anymore), `CatalogNotFoundError('kind'|'priority'|'agent', ref)`
+ * (uid-shaped ref only — an unresolved NAME instead auto-mints, §6.1),
+ * `InvalidArgumentError('kind', ...)` (§2 `project_kind` — a resolved
+ * `kind` name outside this project's non-empty `allowedKinds` set) / a
+ * project-declared `requiredFields` entry left blank by this call (§2 —
+ * see this file's own doc comment on the composition gap this resolves),
+ * `StaleSupersedeError(uid)` (body-change path only — the supersede CAS
+ * lost a race to a concurrent edit of the same `uid`, OR `uid` was already
+ * superseded before this call ever started; the patch was not applied,
+ * re-`get` and retry, never a silent partial apply),
+ * `WriteContentionError`/`WriteIOError` (§4c — an exhausted driver-level
+ * retry on the underlying `immediate` transaction).
+ */
+export declare function update(handle: IWriteStoreHandle, input: IUpdateIssueInput): Promise<IUpdateIssueOutcome>;

package/client.d.ts

@@ -1,174 +0,0 @@
-import { GraphBacklogStore } from './store/graph-backlog-store.js';
-import { BacklogConfig } from './env.js';
-import { ArchiveOpts, ArchiveResult, AuditTrailResult, BacklogFilter, BacklogItem, BacklogStats, BacklogStatus, ClaimOpts, ClaimResult, Citation, CreateItemInput, CreateItemResult, DependencyGraph, ImportMarkdownInput, ImportResult, MigrationPhase, MigrationStatusResult, Priority, ReleaseResult, RepoMigrationResult, SetMigrationPhaseResult, StatsScope, TopoOrderResult, TransitionOpts, UpdateItemInput } from './model.js';
-import { Environment } from '@adhd/environment';
-
-/** The one type apigen special-cases via the `ctx-name-only` invariant. */
-export interface BacklogCtx {
-    store: GraphBacklogStore;
-    env: Environment<BacklogConfig>;
-    /**
-     * Test-isolation escape hatch ONLY — mirrors `BuildBacklogEnvOptions.adhdRoot`
-     * (the same value passed to `buildBacklogEnv({ adhdRoot })` when constructing
-     * `env`). NEVER set this in production code (`server.ts`/`cli.ts` never do).
-     * `setMigrationPhase` threads it through to `writeMigrationPhase` so a
-     * temp-rooted test `ctx` can never write to the real machine-global
-     * `~/.adhd` — omitting this on a real ctx write is exactly the bug
-     * `migration-admin.spec.ts`'s negative control caught (a test run wrote
-     * `phase-4` to the real `~/.adhd/backlog/production/config.yaml` before
-     * this field existed; reverted, see CHANGELOG).
-     */
-    adhdRoot?: string;
-}
-/**
- * Dedupe-scans (FTS + symbol/path/errorText metadata match) before writing.
- * Allocates humanId as family + next number within (repo, family) unless
- * idOverride is given.
- */
-export declare function createItem(ctx: BacklogCtx, input: CreateItemInput): Promise<CreateItemResult>;
-/**
- * repo is required — humanId alone is not globally unique. A genuine miss
- * (humanId doesn't exist under ANY repo) still returns `null` — unchanged,
- * every existing caller relying on nullable-not-throwing keeps working.
- *
- * BUG-BACKLOG-REPO-LOOKUP-UX-001: previously a repo/humanId MISMATCH (the
- * item is live, just filed under a different `repo` string) was
- * indistinguishable from a genuine miss — both silently returned `null`,
- * which is worse than `appendNote`'s bare-but-at-least-thrown
- * `BacklogItemNotFoundError` (and, before this fix, could surface through
- * apigen's MCP layer as the unrelated broken int64/null encoding,
- * BUG-APIGEN-LOGICAL-NULL-OBJECT-RESULT-INT64-001 — out of scope here, but
- * this fix removes the only path that made this lookup look like that bug).
- * Now: a real cross-repo match THROWS the same informative
- * `BacklogItemNotFoundError` (with `foundInRepos` naming the actual repo) the
- * mutating lookups already throw, instead of masquerading as "not found".
- */
-export declare function getItem(ctx: BacklogCtx, repo: string, humanId: string): Promise<BacklogItem | null>;
-export declare function updateItem(ctx: BacklogCtx, repo: string, humanId: string, patch: UpdateItemInput): Promise<BacklogItem>;
-export declare function listItems(ctx: BacklogCtx, filter?: BacklogFilter): Promise<BacklogItem[]>;
-/** Invalidates the node (bi-temporal — never a hard delete). */
-export declare function softDeleteItem(ctx: BacklogCtx, repo: string, humanId: string, reason: string): Promise<void>;
-export declare function stats(ctx: BacklogCtx, scope?: StatsScope): Promise<BacklogStats>;
-/** Open + prioritized, most-severe first. */
-export declare function spotlight(ctx: BacklogCtx, scope?: StatsScope, limit?: number): Promise<BacklogItem[]>;
-/** Open items whose every DEPENDS_ON target is a terminal status AND which are not currently claimed. */
-export declare function readyItems(ctx: BacklogCtx, scope?: StatsScope): Promise<BacklogItem[]>;
-/** The DEPENDS_ON set of `humanId` that is NOT yet terminal. */
-export declare function blockers(ctx: BacklogCtx, repo: string, humanId: string): Promise<BacklogItem[]>;
-export declare function dependencyGraph(ctx: BacklogCtx, scope?: StatsScope): Promise<DependencyGraph>;
-export declare function topoOrder(ctx: BacklogCtx, scope?: StatsScope): Promise<TopoOrderResult>;
-/** Items whose claim lease is older than maxAgeMin with no renewal — candidates for --force reclaim. */
-export declare function staleClaims(ctx: BacklogCtx, maxAgeMin: number, scope?: StatsScope): Promise<BacklogItem[]>;
-export declare function claimItem(ctx: BacklogCtx, repo: string, humanId: string, by: string, opts?: ClaimOpts): Promise<ClaimResult>;
-/** Same-claimant renewal — always succeeds (bumps claimedAt), no contention check. */
-export declare function renewClaim(ctx: BacklogCtx, repo: string, humanId: string, by: string): Promise<ClaimResult>;
-export declare function releaseClaim(ctx: BacklogCtx, repo: string, humanId: string, by: string, opts?: {
-    force?: boolean;
-}): Promise<ReleaseResult>;
-/** Durable ownership (planner decision) — distinct from the ephemeral claim lease. */
-export declare function assignItem(ctx: BacklogCtx, repo: string, humanId: string, to: string, by: string): Promise<BacklogItem>;
-/** transitionStatus(id, 'IN_PROGRESS', ...) + an implicit claimItem(id, by) — a no-op claim-wise if already held by `by`. */
-export declare function startWork(ctx: BacklogCtx, repo: string, humanId: string, by: string): Promise<BacklogItem>;
-export declare function transitionStatus(ctx: BacklogCtx, repo: string, humanId: string, status: BacklogStatus, opts: TransitionOpts): Promise<BacklogItem>;
-export declare function addCitation(ctx: BacklogCtx, repo: string, humanId: string, citation: Citation): Promise<BacklogItem>;
-export declare function appendNote(ctx: BacklogCtx, repo: string, humanId: string, by: string, text: string): Promise<BacklogItem>;
-/** Sugar for transitionStatus into any terminal status. */
-export declare function resolveItem(ctx: BacklogCtx, repo: string, humanId: string, status: BacklogStatus, opts: TransitionOpts): Promise<BacklogItem>;
-/**
- * Renders terminal items to CHANGELOG.md-formatted markdown and marks them
- * archived (metadata.archivedAt set) so renderToMarkdown's default view
- * excludes them — the graph node itself is NEVER deleted.
- */
-export declare function archiveResolved(ctx: BacklogCtx, scope: StatsScope, opts?: ArchiveOpts): Promise<ArchiveResult>;
-export declare function addDependency(ctx: BacklogCtx, repo: string, humanId: string, dependsOnHumanId: string): Promise<void>;
-export declare function removeDependency(ctx: BacklogCtx, repo: string, humanId: string, dependsOnHumanId: string): Promise<void>;
-export declare function linkRelated(ctx: BacklogCtx, repo: string, humanIdA: string, humanIdB: string): Promise<void>;
-/** Mints a new item, links new SUPERSEDES old, invalidates old with reason. */
-export declare function supersedeItem(ctx: BacklogCtx, repo: string, oldHumanId: string, newInput: CreateItemInput, reason: string): Promise<BacklogItem>;
-/** Creates N children linked child PART_OF parent. Parent is left open. */
-export declare function splitItem(ctx: BacklogCtx, repo: string, parentHumanId: string, children: CreateItemInput[]): Promise<BacklogItem[]>;
-/** SAME_AS(drop -> keep), invalidates drop with an auto-generated reason. */
-export declare function mergeItems(ctx: BacklogCtx, repo: string, keepHumanId: string, dropHumanId: string, reason: string): Promise<BacklogItem>;
-export declare function setPriority(ctx: BacklogCtx, repo: string, humanId: string, priority: Priority): Promise<BacklogItem>;
-/** MEMBER_OF edge to a plan node (auto-created if the plan slug hasn't been seen before). */
-export declare function attachToPlan(ctx: BacklogCtx, repo: string, humanId: string, planSlug: string): Promise<void>;
-/**
- * BUG-BACKLOG-REPO-SPLIT-001 / DEBT-BACKLOG-REPO-MOVE-001 — the dedicated
- * primitive to move every live item out of `fromRepo` into `toRepo` (a
- * repo-key correction, e.g. a legacy `"adhd"` string onto the canonical
- * `"PseudoSky/adhd"`). `dryRun` defaults to `true`: a caller must pass
- * `dryRun:false` explicitly to write anything — the default call is always
- * safe to make speculatively and returns the full plan (including which
- * items would be renamed, and to what) with zero mutation.
- *
- * Collisions (a humanId already live in `toRepo`) are never silently
- * dropped, overwritten, or left ambiguous — each is deterministically
- * renamed to the next free number in its own family within `toRepo`
- * (`store/repo-migration.ts`'s `planRepoMigration`), and an audit note
- * recording the original `(fromRepo, humanId)` is attached to the moved
- * item so the rename is traceable. Cross-item links (DEPENDS_ON,
- * RELATES_TO, PART_OF, SUPERSEDES, SAME_AS, MEMBER_OF, ASSIGNED_TO) are
- * preserved automatically — a move never changes a node's id, only its
- * `namespace`/`repo`/`humanId`/`name`/`content`.
- *
- * Every planned item gets exactly one reported outcome
- * (`results[i].ok`/`error`) when `dryRun:false` — a per-item failure never
- * aborts the rest of the batch and never goes unreported.
- */
-export declare function migrateRepo(ctx: BacklogCtx, fromRepo: string, toRepo: string, by: string, dryRun?: boolean): Promise<RepoMigrationResult>;
-export declare function importFromMarkdown(ctx: BacklogCtx, input: ImportMarkdownInput): Promise<ImportResult>;
-/**
- * Excludes archived items (SPEC.md §5.4 archiveResolved) — see markdown.ts's
- * renderItemsToMarkdown doc comment. Archival exclusion goes through
- * `BacklogFilter.excludeArchived` (query.ts's `applyExcludeArchivedFilter`)
- * rather than a private scan here, so a caller comparing this output
- * against `listItems`/`queryItemNodes` for the SAME filter (e.g.
- * `render-projections.mjs`'s round-trip verify) can reproduce this exact
- * item set by passing `{ ...filter, excludeArchived: true }` themselves —
- * see BUG-BACKLOG-RENDER-VERIFY-ARCHIVED-MISMATCH-001.
- */
-export declare function renderToMarkdown(ctx: BacklogCtx, filter?: BacklogFilter): Promise<string>;
-export declare function exportJson(ctx: BacklogCtx, filter?: BacklogFilter): Promise<BacklogItem[]>;
-/** Bi-temporal history + supersession chain. */
-export declare function auditTrail(ctx: BacklogCtx, repo: string, humanId: string): Promise<AuditTrailResult>;
-/**
- * MIGRATION.md §4.4 — a QUERIED signal, never hardcoded prose: reports the
- * live `migration.phase` config value (`env.ts`, env-overridable via
- * `ADHD_BACKLOG_MIGRATION_PHASE`) plus a human-readable meaning, so an agent
- * (or the `backlog-usage` skill) always asks the tool which of BACKLOG.md or
- * the tool is authoritative right now, instead of trusting a stale doc
- * sentence. NOT yet per-repo-keyed (MIGRATION.md §9 open decision 6) — one
- * global value for the whole machine.
- */
-export declare function migrationStatus(ctx: BacklogCtx): Promise<MigrationStatusResult>;
-/**
- * MIGRATION.md §4.4's "admin CLI call" half: writes `migration.phase`
- * THROUGH to the GLOBAL layer's `config.yaml` (`migration-admin.ts`) so the
- * new value is a durable, cross-process, cross-repo signal — not merely an
- * env var scoped to whoever's shell happened to export it. Whoever executes
- * a phase's Definition of Done calls this exactly once, after verifying the
- * DoD, never speculatively.
- */
-export declare function setMigrationPhase(ctx: BacklogCtx, phase: MigrationPhase): Promise<SetMigrationPhaseResult>;
-export interface BacklogVersionInfo {
-    /** This package's real `package.json` name, e.g. `"@adhd/backlog"`. */
-    name: string;
-    /** This package's real `package.json` version — never hardcoded. */
-    version: string;
-}
-/**
- * Reports this running package's own real `name`/`version`, read fresh from
- * `package.json` on every call (never a compiled-in constant, so a
- * republished build can never drift from what this reports). `ctx` is
- * unused — kept for signature consistency with every other `client.ts`
- * export (the `ctx-name-only` invariant every extraction/mount/CLI-dispatch
- * path in this package assumes, per this file's own top-of-file doc
- * comment) rather than special-casing a bare, ctx-less export whose
- * extraction/dispatch behavior has not been verified.
- *
- * The reading itself lives in `version-info.ts`'s `readBacklogVersionInfo()`
- * (store-free) so `cli.ts` can short-circuit `backlog version` without
- * opening the store (DEBT-BACKLOG-CLI-EAGER-STORE-OPEN-001) — this function
- * and that short-circuit share the exact same reading path.
- */
-export declare function version(ctx: BacklogCtx): Promise<BacklogVersionInfo>;