@adhd/backlog 0.1.8 → 1.0.0

package/write/errors.d.ts

@@ -0,0 +1,303 @@
+/**
+ * errors.ts — the write layer error taxonomy (SPEC.md §4c).
+ *
+ * Every write-layer write ultimately fails in exactly one of two ways, never a raw
+ * driver exception and never a bare string:
+ *
+ * 1. A **named, typed, transport-facing class** thrown before any driver call
+ *    ever runs (an app-level validation failure — a missing `by`, an
+ *    unresolved catalog reference, a CAS conflict this spec itself detects),
+ *    or thrown by {@link executeWriteTransaction} (tx.ts) after it has
+ *    decided a driver-level failure is terminal.
+ * 2. The internal {@link IWriteError} envelope — `tx.ts`'s OWN pattern-matched
+ *    shape for a caught driver-level failure, used only to decide
+ *    retry-vs-rethrow. A caller of the write layer (createIssue, and every
+ *    other §6.3 verb) never sees this shape directly; they only ever catch
+ *    one of the named classes below.
+ *
+ * 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`,
+ * `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
+ * `supersede` CAS raises (§4c, "updateIssue's body path"). `WriteContentionError`
+ * / `WriteIOError` are the two driver-level classes tx.ts's retry loop
+ * produces on exhaustion (`E_CONTENTION` / `E_IO`).
+ */
+/** The closed code union every {@link IWriteError} carries (SPEC.md §4c). */
+export type WriteErrorCode = 'E_CONTENTION' | 'E_CONSTRAINT' | 'E_VALIDATION' | 'E_IO';
+/**
+ * The write layer's internal envelope for a caught driver-level failure
+ * (SPEC.md §4c). This is NEVER the shape a caller of `createIssue` (or any
+ * other write-layer verb) receives directly — it is what `tx.ts`'s retry loop pattern-
+ * matches on internally before re-throwing one of the named classes below.
+ * `retryable` is the ONLY field a caller should ever branch on, and only on
+ * the named classes that carry it forward — never a message-text match.
+ */
+export interface IWriteError {
+    code: WriteErrorCode;
+    retryable: boolean;
+    retry_after_ms?: number;
+    message: string;
+    /** The original driver-native error — never swallowed. */
+    cause: unknown;
+}
+/**
+ * Common base for every transport-facing error the write layer throws.
+ * `tx.ts`'s retry loop uses `instanceof BacklogWriteError` to recognize an
+ * already-decided, terminal failure (thrown from inside a verb's own
+ * transaction callback) and rethrow it untouched — never reclassify or retry
+ * a failure this layer has already named.
+ */
+export declare abstract class BacklogWriteError extends Error implements IWriteError {
+    abstract readonly code: WriteErrorCode;
+    abstract readonly retryable: boolean;
+    readonly retry_after_ms?: number;
+    readonly cause: unknown;
+    protected constructor(message: string, cause?: unknown, retryAfterMs?: number);
+}
+/**
+ * `E_CONTENTION`, exhausted. Thrown by {@link executeWriteTransaction}
+ * (tx.ts) after 3 total attempts (1 initial + 2 retries, 250ms/500ms linear
+ * backoff — SPEC.md §4c "Retry semantics") all failed on lock/commit
+ * contention (`isBusyError`/`isConcurrentConflict`). `retryable` stays `true`
+ * even on exhaustion (ADR-0012 §4's own contract) — the caller, not the write
+ * layer, owns any retry beyond this bound.
+ */
+export declare class WriteContentionError extends BacklogWriteError {
+    readonly code: "E_CONTENTION";
+    readonly retryable = true;
+    constructor(retryAfterMs: number, cause: unknown);
+}
+/**
+ * `E_IO`, the first (and, by design, only) occurrence — SPEC.md §4c never
+ * auto-retries `E_IO` on any write-layer verb, because `writeAudit` (§4a)
+ * rides inside literally every write transaction as an unguarded, keyless
+ * INSERT. `retryable` stays `true` (ADR-0012 §4) — the caller, who alone has
+ * the business context to check whether the write actually landed (e.g. a
+ * `query` before resubmitting), owns the decision to retry.
+ *
+ * Constructed by {@link executeWriteTransaction} (tx.ts) ONLY for
+ * {@link classifyDriverError}'s recognized-but-unclassified-database-error
+ * branch (`isDatabaseError(err)` true). A genuinely unrecognized,
+ * non-database-shaped failure (`isDatabaseError(err)` false — a deterministic
+ * bug in this module's own code) is never wrapped in this class — it would
+ * assert `retryable: true` on a failure that can never succeed on retry — and
+ * is instead rethrown untouched by the caller.
+ */
+export declare class WriteIOError extends BacklogWriteError {
+    readonly code: "E_IO";
+    readonly retryable = true;
+    constructor(cause: unknown);
+}
+/**
+ * The one deliberate `E_CONSTRAINT` this spec's own CAS raises (SPEC.md
+ * §4c, "updateIssue's body path: supersede needs a CAS the library doesn't
+ * give it") — the `UPDATE node SET is_superseded = 1 WHERE rowid = ? AND
+ * is_superseded = 0` guard affected zero rows, meaning a concurrent writer
+ * already superseded the same target first. Never retryable — retrying a
+ * terminal CAS loss cannot change its outcome.
+ */
+export declare class StaleSupersedeError extends BacklogWriteError {
+    readonly uid: string;
+    readonly successorUid?: string | undefined;
+    readonly code: "E_CONSTRAINT";
+    readonly retryable = false;
+    /**
+     * @param uid The stale uid the caller passed in.
+     * @param successorUid The uid this issue lives under NOW, when it is known —
+     *   the head of the `SUPERSEDES` chain starting at `uid`. Supplied by the
+     *   READ path (`resolveIssueByUid`), which can walk the chain against
+     *   committed state. The WRITE-path CAS deliberately omits it: it loses the
+     *   race *inside* its own transaction, so any successor it read would be a
+     *   uid another in-flight writer may still supersede before this caller
+     *   acts on it. Absent means "not known here", never "none exists".
+     */
+    constructor(uid: string, successorUid?: string | undefined);
+}
+/**
+ * A `project`/`component`/`kind`/`status`/`priority`/`agent`/`edge_kind`
+ * reference did not resolve. Thrown for a UUID-shaped `ref` that has no live
+ * row (uids are never auto-vivified, SPEC.md §6.1), and for `project`/
+ * `component` NAMEs, which `createIssue` never mints (§1, §6.1 — component
+ * and project are resolved-only by every issue verb).
+ */
+export declare class CatalogNotFoundError extends BacklogWriteError {
+    readonly catalogKind: string;
+    readonly ref: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(catalogKind: string, ref: string);
+}
+/** A caller-supplied argument is missing, blank, or fails a project-declared invariant. */
+export declare class InvalidArgumentError extends BacklogWriteError {
+    readonly field: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(field: string, detail?: string);
+}
+/** No live `issue` node carries the given `uid` (SPEC.md §6.1). */
+export declare class IssueNotFoundError extends BacklogWriteError {
+    readonly uid: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(uid: string);
+}
+/**
+ * `claim` (§6.3.5): the lease is held by someone else, not yet stale, and the
+ * caller did not pass `force:true`.
+ */
+export declare class ClaimHeldError extends BacklogWriteError {
+    readonly heldBy: string;
+    readonly heldSince: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(heldBy: string, heldSince: string);
+}
+/**
+ * `claim` (§6.3.5): the target issue's current status is `terminal` — there
+ * is nothing left to lease on an already-closed issue. Re-open via
+ * `transition` to a non-terminal status instead (SPEC.md's own `closedAt`
+ * clearing rule, §6.3.4) — claiming a terminal issue is not a documented or
+ * intended step in that flow.
+ */
+export declare class IssueTerminalError extends BacklogWriteError {
+    readonly uid: string;
+    readonly status: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(uid: string, status: string);
+}
+/**
+ * `relate` (§6.3.6): a single-valued rel already has a value on the CAPPED
+ * side, and it is not the one being added. This is the SAME
+ * `edge_kind.multiplicity` gate every edge write runs (§2, `checkMultiplicityTx`
+ * in tx.ts) — `relate`'s `n:1` rels (`supersedes`, `duplicate_of`, `part_of`)
+ * are its most visible caller, but the gate is generic over BOTH capped
+ * multiplicities `edge_kind` declares (§2):
+ *
+ * - `n:1` — the SOURCE's out-degree is capped at one (`side: 'source'`): the
+ *   source already points at a different target.
+ * - `1:n` — the TARGET's in-degree is capped at one (`side: 'target'`): the
+ *   target is already pointed at by a different source.
+ *
+ * Deliberately a single named-options constructor, not positional
+ * `(a, b, c)` args — `checkMultiplicityTx`'s two branches resolve the capped
+ * uid and the conflicting uid via DIFFERENT SQL joins (one via `e.dst`, one
+ * via `e.src`), and two same-shaped `string` positional args are trivially
+ * swappable by a future edit without a type error to catch it (exactly what
+ * happened to the 1:n branch before this fix — the message string still read
+ * as plausible English with the values swapped, which is how it went
+ * unnoticed). Named fields make the mistake a call site can no longer make
+ * silently.
+ */
+export declare class SingleValuedRelationConflictError extends BacklogWriteError {
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    /** Which side of `rel` this multiplicity rule caps at one value. */
+    readonly side: 'source' | 'target';
+    /** The uid of the node whose `side` is capped (already at its one allowed value). */
+    readonly cappedUid: string;
+    readonly rel: string;
+    /** The uid of the pre-existing OTHER endpoint already occupying the capped side's one slot. */
+    readonly conflictingUid: string;
+    constructor(input: {
+        side: 'source' | 'target';
+        cappedUid: string;
+        rel: string;
+        conflictingUid: string;
+    });
+}
+/**
+ * A citation's `sha` resolved to the `"unverified"` sentinel (§8.5's
+ * two-branch rule) and `project_policy.citation_requires_sha` (default
+ * `true`) rejects that. The gate applies only where verification is POSSIBLE:
+ * the owning project has a non-empty filesystem `path` and the cited file is
+ * missing (or escapes the project root). A PATH-LESS project cannot hash its
+ * citations at all, so the gate is waived and `sha:"unverified"` is persisted
+ * verbatim — `CitationUnverifiableError` is never thrown for it.
+ */
+export declare class CitationUnverifiableError extends BacklogWriteError {
+    readonly target: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(target: string);
+}
+/** `transition` (§6.3.4): `project_policy.transition_requires_note` (default `true`) and no `note` was given. */
+export declare class NoteRequiredError extends BacklogWriteError {
+    readonly uid: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(uid: string);
+}
+/** `transition` (§6.3.4): `project_policy.citation_required` (default `false`) is set, the target status is terminal, and no citation was given. */
+export declare class CitationRequiredError extends BacklogWriteError {
+    readonly uid: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(uid: string);
+}
+/**
+ * The read layer's own validation class (SPEC.md §6.5) — an unknown `fields`
+ * entry (`assertKnownFields`) or an out-of-range/non-integral `limit`
+ * (`assertQueryLimit`, "a cap that isn't an error is indistinguishable from a
+ * complete result"). Declared here, not in `src/query/`, per this file's own
+ * "do not invent parallel ones" rule: it is the SAME `E_VALIDATION`-class
+ * member of the write layer's error union (§4c), just raised by the read
+ * surface — a `query`/`get` caller catches it identically to any other named
+ * class in this module. `field` names the offending input key
+ * (`'fields'`/`'limit'`); `detail` carries the specific reason (which unknown
+ * name, or which bound was violated).
+ */
+export declare class BacklogValidationError extends BacklogWriteError {
+    readonly field: string;
+    readonly code: "E_VALIDATION";
+    readonly retryable = false;
+    constructor(field: string, detail?: string);
+}
+/**
+ * Classify a caught, RAW driver-level error (never one of our own
+ * {@link BacklogWriteError} subclasses — those are already decided and must
+ * never reach this function) into the internal {@link IWriteError} envelope,
+ * using `@adhd/sox-store-adapter`'s portable, driver-shaped detection
+ * predicates (SPEC.md §4c) — never a raw `err.code`/message match of our
+ * own, since Turso's `err.code` carries no discriminating information
+ * (ADR-0012 §3).
+ *
+ * `isDatabaseError` (`@adhd/sox-store-adapter`'s "is this err shaped like a
+ * recognized database error AT ALL" predicate) is what actually distinguishes
+ * the two `E_IO` sub-cases the SPEC.md §4c table collapses into one row
+ * ("Unclassified driver/connection failure | `E_IO` | `isDatabaseError`
+ * catch-all | `true`"):
+ *
+ * - A RECOGNIZED-but-otherwise-unclassified database error (`isDatabaseError`
+ *   true — e.g. a driver/connection fault that isn't busy/contention/unique/FK)
+ *   is the case that table row actually describes: `E_IO`, `retryable: true`,
+ *   surfaced once by {@link executeWriteTransaction} (tx.ts) as
+ *   {@link WriteIOError} and never auto-retried (§4c "Retry semantics" — the
+ *   audit-atomicity hazard applies uniformly).
+ * - A GENUINELY UNRECOGNIZED failure — `isDatabaseError` false, meaning it
+ *   never even reached the driver (a `TypeError`/`SyntaxError`/other
+ *   deterministic bug in this module's own code, e.g. a `JSON.parse` thrown
+ *   from inside a verb's transaction callback) — is NOT a database fault at
+ *   all and must never be reported `retryable: true`: a caller honouring
+ *   `retryable` would retry a failure that can never succeed. This still
+ *   returns `code: 'E_IO'` (the closed `WriteErrorCode` union, SPEC.md §4c,
+ *   has no fifth bucket for "not a driver error at all" and this failure did
+ *   reach the transaction boundary same as the recognized case) but with
+ *   `retryable: false` — the discriminator {@link executeWriteTransaction}
+ *   uses to skip {@link WriteIOError} (which hardcodes `retryable: true`,
+ *   ADR-0012 §4) for this branch and instead rethrow the original error
+ *   UNTOUCHED, exactly like the unclassified-`E_CONSTRAINT` catch-all below
+ *   it: a raw `TypeError`/`SyntaxError` is *more* diagnostic than a generic
+ *   `WriteIOError`, not less.
+ */
+export declare function classifyDriverError(err: unknown): IWriteError;
+/**
+ * Rejects the specific bare-role literals SPEC.md calls out by name, on top
+ * of whatever blank/missing check the call site already runs. Call this
+ * immediately after `assertNonBlank('by', input.by)` at every mutating verb.
+ */
+export declare function assertNotBareRoleLiteral(field: string, value: string): void;

package/write/issue-status.d.ts

@@ -0,0 +1,10 @@
+import { ITxNodeRow } from './tx.js';
+import { AdapterTransaction } from '@adhd/sox-store-adapter';
+
+/**
+ * `caller` is embedded in the invariant-violation error messages so a thrown
+ * `Error` still reads as coming from the verb that actually called this,
+ * matching the per-file error-message convention both callers already used
+ * before this was extracted.
+ */
+export declare function resolveIssueStatusTx(tx: AdapterTransaction, issueRowid: number, caller: string): Promise<ITxNodeRow>;

package/write/move.d.ts

@@ -0,0 +1,70 @@
+import { IWriteStoreHandle } from './tx.js';
+
+export interface IMoveIssueInput {
+    /** The `issue` uid to move (§6.3, an "Issue verb"). */
+    uid: string;
+    /**
+     * uid or name of the destination project, resolved per §6.1 —
+     * RESOLVE-ONLY, exactly like `createIssue`'s own `project` field: never
+     * minted by this verb. Omitted (undefined) is a distinct third case, never
+     * an error: it resolves to the issue's OWN CURRENT project (a
+     * component-only move — see this file's own doc comment).
+     */
+    toProject?: string;
+    /**
+     * uid or name of the destination component, scoped within the RESOLVED
+     * destination project (whichever project that is), resolved per §6.1 —
+     * RESOLVE-ONLY, never minted (see §6.1's project-vs-component asymmetry:
+     * use `upsertComponent` first if the component does not yet exist).
+     * Omitted (undefined) resolves instead to the destination project's
+     * reserved default component `(root)`, already guaranteed live by
+     * `upsertProject` (§3/§8 AC-23) — never minted here either.
+     */
+    toComponent?: string;
+    /** The acting agent or person performing the move (§6.3's opening rule). REQUIRED. */
+    by: string;
+}
+export interface IMoveIssueOutcome {
+    uid: string;
+    /** `true` when the resolved destination component is the SAME live component the issue already occupied — an idempotent call, stated rather than disguised (see this file's own doc comment). No edge was invalidated or written, and no audit row was produced. */
+    noop: boolean;
+    fromProject: string;
+    toProject: string;
+    fromComponent: string;
+    toComponent: string;
+}
+/**
+ * Reparent an issue onto a (possibly different) project's (possibly
+ * different) component (§6.3.6, §8 AC-17). One `immediate` transaction:
+ * resolve `uid` → live `issue` node (tx-scoped, §4c) → walk its CURRENT
+ * `owns_component`/`owns_project` edges → resolve the DESTINATION project
+ * (given, or the current one) → resolve the DESTINATION component within
+ * that project (given, or that project's reserved `(root)`, §8 AC-23) → if
+ * the destination component is the SAME live component the issue already
+ * occupies, return a no-op outcome (nothing invalidated, nothing written, no
+ * audit — see this file's own doc comment); otherwise hand-composed
+ * `invalidateEdgeTx` (the OLD `owns_component` edge) THEN hand-composed
+ * `writeEdgeTx` (the NEW one) THEN `writeAudit` — all against the SAME `tx`,
+ * so the invalidate and the write either both land or neither does (never a
+ * write-then-write that can half-apply). The invalidate runs strictly BEFORE
+ * the write so `writeEdgeTx`'s own `1:n`-multiplicity check (the target
+ * issue's in-degree capped at one, tx.ts's `checkMultiplicityTx`) sees the
+ * old edge already retired and never raises a false
+ * `SingleValuedRelationConflictError` against the issue's own prior
+ * placement.
+ *
+ * Errors: `InvalidArgumentError` (`uid`/`by` missing/blank),
+ * `IssueNotFoundError` (no live `issue` node carries `uid`),
+ * `CatalogNotFoundError('project', toProject)` (a given `toProject` did not
+ * resolve — resolve-only, never minted, exactly like `createIssue`'s own
+ * `project` field), `CatalogNotFoundError('component', toComponent)` (a given
+ * `toComponent` did not resolve WITHIN the resolved destination project —
+ * resolve-only, never minted; a uid belonging to a DIFFERENT project is
+ * treated identically to an unresolved ref, per `resolveComponentTx`'s own
+ * contract), `SingleValuedRelationConflictError` (defensive — the generic
+ * `1:n` multiplicity guard `writeEdgeTx` runs for every edge write; expected
+ * unreachable here given the invalidate-before-write ordering above),
+ * `WriteContentionError`/`WriteIOError` (§4c — an exhausted driver-level
+ * retry on the underlying `immediate` transaction).
+ */
+export declare function move(handle: IWriteStoreHandle, input: IMoveIssueInput): Promise<IMoveIssueOutcome>;

package/write/relate.d.ts

@@ -0,0 +1,52 @@
+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 interface IRelateInput {
+    /** The relation's SOURCE `issue` uid (§1: uid is the only identifier — never a name, never repo-scoped). */
+    sourceUid: string;
+    /** The relation's TARGET `issue` uid — may belong to ANY project, including a different one than `sourceUid` (see this file's own doc comment on the resolved cross-project gap). */
+    targetUid: string;
+    rel: RelateRel;
+    action: 'add' | 'remove';
+    /** The acting agent or person performing the change (§6.3's opening rule). REQUIRED. */
+    by: string;
+}
+export interface IRelateOutcome {
+    sourceUid: string;
+    targetUid: string;
+    rel: string;
+    action: 'add' | 'remove';
+    /** `true` when `add` found an already-live matching edge, or `remove` found none — an idempotent call, stated rather than disguised (§6.3.6). No edge was invalidated or written, and no audit row was produced. */
+    noop: boolean;
+}
+/**
+ * Add or remove a typed `issue ↔ issue` relation (§6.3.6). One `immediate`
+ * transaction: resolve `sourceUid`/`targetUid` → live `issue` nodes (tx-scoped,
+ * §4c) → resolve `rel`'s `edge_kind` rule (`resolveEdgeKindTx`, catalog.ts) →
+ * check whether a LIVE `(sourceUid, targetUid, rel)` edge already exists →
+ * branch:
+ *
+ * - `add`, edge already live → `noop:true`, nothing written.
+ * - `add`, edge not live (absent, or previously `remove`d) → `writeEdgeTx`
+ *   (tx.ts) — inserts fresh or re-livens; throws
+ *   `SingleValuedRelationConflictError` if `rel` is single-valued (`n:1`:
+ *   `supersedes`/`duplicate_of`/`part_of`) and `sourceUid` already has a
+ *   LIVE `rel` edge to a DIFFERENT target (`checkMultiplicityTx`, tx.ts —
+ *   this file adds no separate check) — then `writeAudit`, `noop:false`.
+ * - `remove`, edge not live → `noop:true`, nothing written.
+ * - `remove`, edge live → `invalidateEdgeTx` (tx.ts) then `writeAudit`,
+ *   `noop:false`.
+ *
+ * Errors: `InvalidArgumentError` (`sourceUid`/`targetUid`/`by` missing or
+ * blank; `rel` outside the closed 5-value set — the TS type restricts this
+ * at compile time but a transport boundary, e.g. CLI/MCP JSON input, can
+ * still send an arbitrary string; `action` outside `'add'|'remove'`, same
+ * reason; `sourceUid === targetUid` — a self-relation is always a client
+ * error, never silently written, §6.3.6), `IssueNotFoundError` (either
+ * endpoint is not a live `issue` node), `SingleValuedRelationConflictError`
+ * (per the `add` branch above), `WriteContentionError`/`WriteIOError` (§4c —
+ * an exhausted driver-level retry on the underlying `immediate`
+ * transaction).
+ */
+export declare function relate(handle: IWriteStoreHandle, input: IRelateInput): Promise<IRelateOutcome>;

package/write/transition.d.ts

@@ -0,0 +1,60 @@
+import { IWriteStoreHandle } from './tx.js';
+import { ICitationInput } from './create-issue.js';
+
+export interface ITransitionInput {
+    /** The `issue` uid to transition (§6.3, an "Issue verb"). */
+    uid: string;
+    /** The identity of the acting agent or person (§6.3's opening rule). REQUIRED. */
+    by: string;
+    /** catalog name or uid. An unresolved NAME mints a new status row with `terminal:false` (exactly like `create`'s own `status` field, §6.3.2/§6.1); a uid-shaped ref that does not resolve throws `CatalogNotFoundError('status', ref)`. */
+    toStatus: string;
+    /** REQUIRED unless `project_policy.transition_requires_note` is `false` (default `true`) — optional in the type; enforced at runtime (`NoteRequiredError`), never at the TS level. */
+    note?: string;
+    /** 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[];
+    /**
+     * The item-level disclosure-contract git context — the SAME plain metadata
+     * scalar `create`'s own `gitContext` field writes (repo `AGENTS.md`'s "Cite
+     * what you read": the FIRST element of a `Citations:` block is `<active git
+     * context>`). When supplied, it UPDATES the item's stored value on the
+     * metadata touch this verb already performs; when omitted, the item's
+     * existing value (if any) is left untouched. ITEM-level, deliberately not a
+     * per-citation `ref` — it rides the issue, never a `citation` node.
+     */
+    gitContext?: string;
+}
+export interface ITransitionOutcome {
+    uid: string;
+    fromStatus: string;
+    toStatus: string;
+    /** Present iff `toStatus.terminal` — see this file's own doc comment on `closedAt`. */
+    closedAt?: string;
+    /** The minted `transition` node's own uid, for audit-trail addressing. */
+    transitionUid: string;
+}
+/**
+ * Transition an issue's status (§4a, §6.3.4). One `immediate` transaction.
+ *
+ * Errors: `InvalidArgumentError` (`uid`/`by`/`toStatus` missing/blank, blank
+ * `citations[i].file`, or a resolved `toStatus` outside this project's
+ * `allowedStatuses` set), `IssueNotFoundError` (no live `issue` node carries
+ * `uid`), `StaleSupersedeError(uid)` (`uid` was already superseded by a prior
+ * `update` — this file's own doc comment on `update.ts` explains why that
+ * reuses this error class rather than a new one), `CatalogNotFoundError('status',
+ * toStatus)` (uid-shaped `toStatus` only — an unresolved NAME instead
+ * auto-mints with `terminal:false`, exactly as `create`'s own `status` field,
+ * §6.1), a project-declared `requiredFields` entry (§2 — here, always just
+ * `status`, see this file's own doc comment) left blank,
+ * `NoteRequiredError` (policy-gated), `CitationRequiredError`
+ * (policy-gated, terminal-only), `CitationUnverifiableError(target)`
+ * (policy-gated via `project_policy.citation_requires_sha` — a given
+ * citation's `sha` resolved to the `"unverified"` sentinel and the project
+ * requires a real hash; the gate applies only when the project has a known
+ * `path`, so a path-less project records `sha:"unverified"` verbatim),
+ * `ClaimHeldError(heldBy, heldSince)` (§6.3.5 — a
+ * live, non-stale claim held by someone other than `input.by` blocks the
+ * status change; see claim-lease.ts), `WriteContentionError`/`WriteIOError`
+ * (§4c — an exhausted driver-level retry on the underlying `immediate`
+ * transaction).
+ */
+export declare function transition(handle: IWriteStoreHandle, input: ITransitionInput): Promise<ITransitionOutcome>;