@adhd/backlog 0.1.8 → 1.0.0

package/write/catalog.d.ts

@@ -0,0 +1,351 @@
+import { IComponentSummary, ILocationSummary, ILocationType, IProjectSummary } from '../query/types.js';
+import { IEdgeKindRule, IWriteStoreHandle } from './tx.js';
+import { AdapterTransaction } from '@adhd/sox-store-adapter';
+
+/** Whether `ref` should be treated as a `uid` (exact resolve-or-throw) rather than a business `name` (find, and for the flat catalogs, find-then-mint). */
+export declare function isUidShaped(ref: string): boolean;
+export interface IResolvedCatalogRow {
+    rowid: number;
+    uid: string;
+    name: string;
+}
+export interface IResolvedProjectRow extends IResolvedCatalogRow {
+    metadata: Record<string, unknown> | undefined;
+}
+/**
+ * `project` (§1, §6.1): resolved-ONLY, `uid` or `name`, NEVER minted by an
+ * issue verb — minting a project is the explicit `upsertProject` registry
+ * verb's job alone (§3a), out of scope for this slice.
+ */
+export declare function resolveProjectTx(tx: AdapterTransaction, ref: string): Promise<IResolvedProjectRow>;
+/**
+ * `component`, scoped within `project` (§6.1, §6.3.2): resolved-ONLY, `uid`
+ * or `name` — an unresolved name throws `CatalogNotFoundError('component', name)`
+ * rather than silently forking a new component under the given project.
+ */
+export declare function resolveComponentTx(tx: AdapterTransaction, input: {
+    projectUid: string;
+    ref: string;
+}): Promise<IResolvedCatalogRow>;
+/**
+ * `project`'s reserved default component, `(root)` (§3, §6.1, §6.3.2,
+ * §8 AC-23): what `createIssue` resolves to when `component` is omitted.
+ * A row `upsertProject` already guarantees is live for every project — NEVER
+ * minted here, in either case (§1). Resolved via `owns_project` (the SAME
+ * traversal §3a's registry uses), not a bare name lookup, so a `(root)` row
+ * belonging to a DIFFERENT project can never be mismatched onto this one.
+ */
+export declare function resolveDefaultComponentTx(tx: AdapterTransaction, input: {
+    projectRowid: number;
+}): Promise<IResolvedCatalogRow>;
+export type FlatCatalogKind = 'kind' | 'status' | 'priority' | 'agent';
+export interface IMintOrResolveInput {
+    catalogKind: FlatCatalogKind;
+    ref: string;
+    /** Metadata to seed onto a MINTED row only — never read or applied when `ref` resolves to an existing row. Evaluated lazily (only on an actual mint) since e.g. `priority`'s rank needs a fresh in-tx MAX query (§6.3.2). */
+    mintMetadata?: (tx: AdapterTransaction) => Promise<Record<string, unknown>>;
+    /**
+     * The caller's single logical-write timestamp, forwarded to `writeNodeTx` so a
+     * minted catalog row carries the SAME `t_created`/`t_valid` as the issue that
+     * caused the mint. Omitted, `writeNodeTx` stamps its own `nowISO()`, which is
+     * what produced per-row drift within one `createIssue`.
+     *
+     * Deliberately NOT threaded into `resolveEdgeKindTx`'s `edge_kind` rows: those
+     * are schema-infrastructure rows describing the relation table itself, not part
+     * of any one issue's logical write, so they keep their own clock.
+     */
+    at?: string;
+}
+/**
+ * The flat-catalog find-then-create (§1, §4c, §6.1): `kind`/`status`/
+ * `priority`/`agent` are mintable on an unresolved NAME; a uid-shaped `ref`
+ * that does not resolve instead throws — minting NEVER applies to a uid.
+ */
+export declare function mintOrResolveCatalogTx(tx: AdapterTransaction, input: IMintOrResolveInput): Promise<IResolvedCatalogRow>;
+/** `priority`'s mint rule (§6.3.2): "rank set to one past the current max rank (i.e. lowest urgency) — a novel priority can never silently outrank an existing one." */
+export declare function nextPriorityRankTx(tx: AdapterTransaction): Promise<number>;
+/**
+ * §3's fixed edge table — the ONE declared shape for every `rel` (§2's
+ * closing statement: "the SAME check for every row, never two different
+ * checks"). `audits`' `source_kind: '*'` is the one declared sentinel (§2).
+ */
+export declare const EDGE_KIND_TABLE: readonly IEdgeKindRule[];
+/**
+ * Resolve the `edge_kind` catalog row for `rel`, inside `tx` — the SAME
+ * `tx.executeGet` lookup §1 describes for the VALIDATION half of every edge
+ * write. `edge_kind` is NEVER caller-mintable (§1, §6.1): every row is
+ * "seeded once from §3's fixed edge table," normally by a dedicated
+ * bootstrap/seed step (§8.6 step 2 is the ETL's own version of this same
+ * seeding).
+ *
+ * **Documented deviation for this slice.** This task ships the write-layer
+ * core only (`errors.ts`/`tx.ts`/`catalog.ts`/`audit.ts`/`create-issue.ts`) —
+ * no dedicated seed/bootstrap script exists yet to have run before
+ * `createIssue` is first called. Rather than make `createIssue` depend on an
+ * out-of-scope script, this function self-heals: on a miss, it seeds the
+ * row from {@link EDGE_KIND_TABLE} — the IDENTICAL fixed §3 shape a real seed
+ * script would write, never a caller-supplied one — inside the SAME `tx` the
+ * calling verb already opened. This satisfies "seeded once" (idempotent:
+ * the `tx.executeGet` above finds it on every subsequent call) without
+ * requiring a separate bootstrap step to exist first. A future seed script
+ * making this self-heal path dead code is expected and fine — the row shape
+ * it would find already-present is identical either way.
+ *
+ * **A malformed row (should never happen — only this module ever writes
+ * one) is guarded, never crashed on, and never left to accumulate.** `meta`
+ * is read via {@link parseMetaObject} — a non-JSON `meta` value degrades to
+ * `{}` instead of throwing a raw `SyntaxError` out of the transaction
+ * callback (Finding 1: unguarded, that would misclassify as a retryable
+ * `E_IO` at `executeWriteTransaction`'s boundary and retry forever against a
+ * deterministic parse failure). Either that degraded `{}`, or a
+ * successfully-parsed object missing one of the three expected keys, takes
+ * the SAME "malformed" branch below: the row is invalidated and a correct
+ * replacement is minted from {@link EDGE_KIND_TABLE} in the SAME `tx`, so the
+ * next call's SELECT (now a deterministic `ORDER BY rowid` — the prior
+ * ordering-free `LIMIT 1` made which duplicate got read unspecified, Finding
+ * 2) can never re-find the malformed row and re-mint yet another duplicate.
+ * The store converges to exactly one live `edge_kind` row per `rel` after
+ * this call, rather than growing an unbounded set of malformed duplicates.
+ */
+export declare function resolveEdgeKindTx(tx: AdapterTransaction, rel: string): Promise<IEdgeKindRule>;
+/**
+ * Per-project policy (§2): DATA, realized as `project.meta.metadata.policy`
+ * — §2's table has no dedicated node/edge of its own (it is 1:1 with
+ * `project`, never many-to-many), so it lives inside the SAME metadata blob
+ * `project`'s other declared fields (`repoUrl`, `monorepo`, …, §3a) already
+ * occupy. Every field defaults exactly as §2 states when the project carries
+ * no `policy` object at all (a project seeded before policy existed, or
+ * minimally).
+ */
+export interface IProjectPolicy {
+    readonly transitionRequiresNote: boolean;
+    readonly citationRequired: boolean;
+    readonly citationRequiresSha: boolean;
+    readonly defaultStatus?: string;
+    readonly defaultKind?: string;
+    readonly dedupeScanEnabled: boolean;
+    readonly dedupeThreshold: number;
+    readonly claimStaleAfterMin: number;
+    /** `project_status` — empty means "no restriction" (§2). */
+    readonly allowedStatuses: readonly string[];
+    /** `project_kind` — empty means "no restriction" (§2). */
+    readonly allowedKinds: readonly string[];
+    /** `project_field_requirement` — field names required on every mutating write for this project (§2). */
+    readonly requiredFields: readonly string[];
+}
+export declare function resolveProjectPolicy(project: IResolvedProjectRow): IProjectPolicy;
+/**
+ * Whether a resolved project has a known filesystem `path` (§8.4/§8.5) — the
+ * precondition for citation content-addressing to be POSSIBLE at all. When it
+ * does not, `computeCitationSha` can only ever return the `"unverified"`
+ * sentinel (`create-issue.ts`/`transition.ts` both short-circuit on a
+ * non-string/empty `metadata.path`), so `project_policy.citationRequiresSha`
+ * has nothing to gate: the gate applies only where verification is possible.
+ * A path-less project therefore records `sha:"unverified"` verbatim, matching
+ * the ETL's own precedent (`tools/etl/citation.ts`). Kept beside
+ * {@link resolveProjectPolicy} — it reads the same resolved project row. The
+ * PREDICATE itself is shared by BOTH write paths so the `create`/`transition`
+ * gates never drift on WHICH projects are verifiable; the surrounding
+ * `computeCitationSha` hashing body is NOT shared — it stays a per-file copy
+ * in each verb (this package's established per-file-duplication convention —
+ * see `transition.ts`'s own doc comment on its copy).
+ *
+ * A TYPE PREDICATE, not a bare `boolean`: both `computeCitationSha` call sites
+ * (and the waiver log beside each gate) need the narrowed `metadata.path` as a
+ * `string` immediately after the guard, and a predicate is the one form that
+ * gives them that without a non-null assertion or a re-read of the same field.
+ */
+export declare function projectHasKnownPath(project: IResolvedProjectRow): project is IResolvedProjectRow & {
+    metadata: Record<string, unknown> & {
+        path: string;
+    };
+};
+export interface IUpsertProjectInput {
+    /** The business key `project` is upserted by (§3a, §4). */
+    name: string;
+    path?: string;
+    repoUrl?: string;
+    monorepo?: boolean;
+    description?: string;
+    /** The acting agent's or person's identity (§6.3's opening rule). REQUIRED. */
+    by: string;
+}
+export interface IUpsertProjectOutcome {
+    uid: string;
+    /** `false` when an existing LIVE `project` row with this `name` was found and updated in place; `true` only on a genuine first mint. */
+    created: boolean;
+    project: IProjectSummary;
+}
+/**
+ * Create-or-update a `project` by `name` (§3a, §4). One `immediate`
+ * transaction: find the LIVE `project` row by `name` — on a HIT, merge the
+ * supplied fields into the EXISTING `meta` blob (never a wholesale replace;
+ * an existing `meta.policy` — §2's per-project policy, read back by
+ * {@link resolveProjectPolicy} — survives every subsequent `upsertProject`
+ * untouched) and audit `'updated'`; on a MISS, mint the `project` row AND,
+ * "on first creation ONLY," the reserved default `component` row named
+ * `(root)` plus its `owns_project` edge, in the SAME transaction (§4) — audit
+ * `'created'`. A repeat `upsertProject` against an existing project finds
+ * `(root)` already live (via the existing-project branch, which never touches
+ * it) and writes nothing further for it: idempotent, never a second row.
+ *
+ * Race-safety (§4c): the find-then-create SELECT and the INSERT/UPDATE both
+ * run inside the SAME `BEGIN IMMEDIATE` transaction two concurrent processes
+ * cannot both hold at once — one commits, the other's driver-level conflict
+ * surfaces as `E_CONTENTION` and is retried by {@link executeWriteTransaction}
+ * (250ms/500ms backoff, 3 attempts, §4c), never a racing check-then-insert.
+ *
+ * Errors: `InvalidArgumentError` (`name`/`by` missing or blank),
+ * `WriteContentionError`/`WriteIOError` (§4c, an exhausted or unclassified
+ * driver-level failure on the underlying `immediate` transaction).
+ */
+export declare function upsertProject(handle: IWriteStoreHandle, input: IUpsertProjectInput): Promise<IUpsertProjectOutcome>;
+/**
+ * Transaction-PARTICIPANT core of {@link upsertProject} — the exact body
+ * that used to run inside its `executeWriteTransaction` callback, extracted
+ * so a caller that already owns an open `immediate` transaction (the ETL's
+ * `tools/etl/import-item.ts` bundles an entire source item's writes into ONE
+ * transaction, SPEC.md §7a) can participate in it instead of nesting a
+ * second `executeWriteTransaction` call — nesting would either deadlock or
+ * silently open two separate transactions where one atomic one was intended.
+ * `upsertProject` itself is now a thin wrapper: open the transaction, hand it
+ * to this function. Same validation contract as `upsertProject` — callers of
+ * THIS function are responsible for having already run `assertNonBlank`/
+ * `assertNotBareRoleLiteral` on `input.name`/`input.by` (this function does
+ * not re-validate, matching every other `*Tx` helper in this module).
+ */
+export declare function upsertProjectTx(tx: AdapterTransaction, handle: Pick<IWriteStoreHandle, 'typePolicy'>, input: IUpsertProjectInput): Promise<IUpsertProjectOutcome>;
+export interface IUpsertComponentInput {
+    /** `project` reference — `uid` or `name` (§6.1's disambiguation-by-shape rule), resolved-ONLY, never minted. */
+    project: string;
+    /** The business key `component` is upserted by, scoped to `project` (§3a, §4: "upsert by `(project, name)`"). */
+    name: string;
+    path?: string;
+    description?: string;
+    /** The acting agent's or person's identity (§6.3's opening rule). REQUIRED. */
+    by: string;
+}
+export interface IUpsertComponentOutcome {
+    uid: string;
+    /** `false` when an existing LIVE `component` row with this `(project, name)` was found and updated in place. */
+    created: boolean;
+    component: IComponentSummary;
+}
+/**
+ * Create-or-update a `component` by `(project, name)` (§3a, §4). `project`
+ * is resolved-ONLY ({@link resolveProjectTx}) — an unresolved `project`
+ * throws `CatalogNotFoundError` before any component-side work runs. One
+ * `immediate` transaction thereafter: find the LIVE `component` row scoped to
+ * the resolved project's `uid` — on a HIT, merge the supplied fields into the
+ * EXISTING `meta` (never a wholesale replace, same rule as
+ * {@link upsertProject}) and audit `'updated'`; on a MISS, mint the row.
+ * Either way, the `owns_project` edge (project → component, §3a's registry
+ * edge set) is written with the SAME `ON CONFLICT` upsert `writeEdgeTx`
+ * itself already performs — a no-op re-livening when the edge already exists,
+ * so a component whose edge somehow drifted from its `meta.projectUid` (it
+ * never should, both are written in the SAME transaction on creation) is
+ * self-healed rather than left stale.
+ *
+ * Errors: `InvalidArgumentError` (`project`/`name`/`by` missing or blank),
+ * `CatalogNotFoundError` (`project` does not resolve),
+ * `WriteContentionError`/`WriteIOError` (§4c).
+ */
+export declare function upsertComponent(handle: IWriteStoreHandle, input: IUpsertComponentInput): Promise<IUpsertComponentOutcome>;
+/**
+ * Transaction-PARTICIPANT core of {@link upsertComponent} — same extraction
+ * rationale as {@link upsertProjectTx}: lets a caller that already owns an
+ * open `immediate` transaction (the ETL) participate instead of nesting a
+ * second `executeWriteTransaction`. `upsertComponent` itself is now a thin
+ * wrapper: validate, open the transaction, hand it to this function. Callers
+ * of THIS function are responsible for having already run the same
+ * `assertNonBlank`/`assertNotBareRoleLiteral` validation `upsertComponent`
+ * runs before opening its transaction.
+ */
+export declare function upsertComponentTx(tx: AdapterTransaction, handle: Pick<IWriteStoreHandle, 'typePolicy'>, input: IUpsertComponentInput): Promise<IUpsertComponentOutcome>;
+export interface IUpsertLocationInput {
+    /**
+     * `component` reference — `uid` or `name` (§6.1's disambiguation-by-shape
+     * rule). A bare NAME is ambiguous on its own (component names are unique
+     * only WITHIN a project, §6.3.2), so a name reference REQUIRES `project`
+     * to scope it; a `uid` reference never needs `project` (a documented
+     * judgment call — SPEC.md §3a states the call convention
+     * `upsertLocation({component, locType, value})` without a `project` field,
+     * but never states how a bare component name resolves; this reading stays
+     * consistent with every OTHER verb's own `project`-scoped component
+     * resolution — §6.1, §6.3.2 — rather than inventing a global name-uniqueness
+     * scan `resolveComponentTx` itself does not perform).
+     */
+    component: string;
+    project?: string;
+    locType: ILocationType;
+    value: string;
+    /** The acting agent's or person's identity (§6.3's opening rule). REQUIRED. */
+    by: string;
+}
+export interface IUpsertLocationOutcome {
+    uid: string;
+    /** `false` when a LIVE `location` row with this exact `(component, locType, value)` already existed — a genuine no-op: identity IS the row's entire content, so nothing is written or audited (§4a's "never disguised as a real write" rule, `move.ts`'s stated-no-op pattern). */
+    created: boolean;
+    location: ILocationSummary;
+}
+/**
+ * Create-or-find a `location` by `(component, locType, value)` (§3a, §4).
+ * `component` is resolved-ONLY — by `uid` directly, or by `name` scoped to
+ * `project` (see {@link IUpsertLocationInput.component}'s doc comment for the
+ * resolved ambiguity). One `immediate` transaction: find a LIVE `location`
+ * row with the exact triple — a HIT is a genuine no-op (the triple IS the
+ * row's whole identity; there is no fourth field left to merge, unlike
+ * `project`/`component`), so NOTHING is written or audited and `created:
+ * false` is returned; a MISS mints the row plus its `has_location` edge
+ * (component → location, §3a's registry edge set) and audits `'created'`.
+ *
+ * An invalidated (`rmLocation`-ed) row is never resurrected or matched here —
+ * the SELECT is `t_invalid IS NULL`-scoped like every other resolution in
+ * this module, so re-`upsertLocation`-ing the identical triple after an
+ * `rmLocation` mints a genuinely NEW row with a NEW `uid`, leaving the
+ * invalidated row's own audit trail untouched (the same bi-temporal
+ * non-resurrection rule `delete.ts` documents for `issue`).
+ *
+ * Errors: `InvalidArgumentError` (`component`/`value`/`by` missing or blank,
+ * `locType` not one of `path`/`url`/`tool`, or a bare `component` NAME given
+ * without `project`), `CatalogNotFoundError` (`project`/`component` does not
+ * resolve), `WriteContentionError`/`WriteIOError` (§4c).
+ */
+export declare function upsertLocation(handle: IWriteStoreHandle, input: IUpsertLocationInput): Promise<IUpsertLocationOutcome>;
+export interface IRmLocationInput {
+    uid: string;
+    /** The acting agent's or person's identity (§6.3's opening rule). REQUIRED. */
+    by: string;
+    /** Optional explanation recorded on the invalidation's audit row and merged into the location's own `meta` (mirrors `delete.ts`'s `reason`, which SPEC.md §6.3.7 requires for `issue` — kept optional here since §3a/§4 state no such requirement for `location`). */
+    reason?: string;
+}
+export interface IRmLocationOutcome {
+    uid: string;
+    invalidated: true;
+}
+/**
+ * Soft-invalidate a LIVE `location` by `uid` (§3a, §4: "invalidate"; §4c's
+ * table: "invalidate-by-uid after confirming the row is live, for uniformity
+ * with every other verb above"). One `immediate` transaction: resolve `uid`
+ * → LIVE `location` node (`resolveByUidTx`, never a bare `getNodeByUid`, §4c)
+ * → hand-composed guarded `UPDATE node SET t_invalid = ?, meta = ? WHERE
+ * rowid = ?` (merging `invalidatedReason`/`invalidatedAt` into the EXISTING
+ * `meta`, never a wholesale replace — the SAME shape `delete.ts` uses for
+ * `issue`) → invalidate the owning `has_location` edge
+ * ({@link invalidateEdgeTx}, resolved via the location's own
+ * `meta.componentUid`) → `writeAudit` (action `'deleted'`, matching
+ * `delete.ts`'s own vocabulary), all against the SAME `tx`.
+ *
+ * No `issue` node ever references a `location` directly — per §3a's fixed
+ * edge table ({@link EDGE_KIND_TABLE}), `has_location` (component → location)
+ * is the ONLY rel touching `location` at all — so the sole referencing edge
+ * this invalidates is the owning component's own `has_location` edge; no
+ * issue-side fallout exists to reconcile.
+ *
+ * Errors: `InvalidArgumentError` (`uid`/`by` missing or blank),
+ * `CatalogNotFoundError` (no LIVE `location` node carries `uid` — including
+ * an ALREADY-`rmLocation`-ed `uid`, the same non-resurrection rule
+ * {@link IUpsertLocationOutcome}'s doc comment describes),
+ * `WriteContentionError`/`WriteIOError` (§4c).
+ */
+export declare function rmLocation(handle: IWriteStoreHandle, input: IRmLocationInput): Promise<IRmLocationOutcome>;

package/write/claim-lease.d.ts

@@ -0,0 +1,21 @@
+/**
+ * claim-lease.ts — the ephemeral claim lease's read-side logic, shared by
+ * every write verb that needs to know whether a live claim currently blocks
+ * it. `claim.ts` (§6.3.5) is the only verb that MUTATES `claimedBy`/
+ * `claimedAt`; this module only ever reads and interprets that pair, so
+ * `transition.ts` (§6.3.5's own "a live claim by someone else blocks a
+ * status change" rule) can enforce the SAME staleness semantics without
+ * duplicating the age-math or silently drifting from it over time.
+ */
+/** Pulls the raw `claimedBy`/`claimedAt` pair off an issue's metadata, typed and undefined-safe. */
+export declare function extractClaimMeta(metadata: Record<string, unknown> | undefined): {
+    claimedBy: string | undefined;
+    claimedAt: string | undefined;
+};
+/**
+ * A missing `claimedAt` (should not happen alongside a real `claimedBy`, but
+ * never trusted) is treated as infinitely old — the same fail-open choice
+ * `claim.ts`'s own reclaim branch already makes.
+ */
+export declare function claimAgeMinutes(claimedAt: string | undefined, now: string): number;
+export declare function isClaimStale(claimedAt: string | undefined, now: string, staleAfterMin: number): boolean;

package/write/claim.d.ts

@@ -0,0 +1,80 @@
+import { IWriteStoreHandle } from './tx.js';
+
+export interface IClaimInput {
+    /** The `issue` uid to claim/release/renew (§6.3, an "Issue verb"). */
+    uid: string;
+    /** The claimant — the acting agent or person. REQUIRED on every action (§6.3's opening rule). */
+    by: string;
+    action: 'claim' | 'release' | 'renew';
+    /** Human-confirmed override of a NON-stale claim (§6.2). Only consulted on `action:'claim'` when the current claimant differs and the lease is not yet stale. */
+    force?: boolean;
+}
+export interface IClaimOutcome {
+    uid: string;
+    status: 'claimed' | 'held' | 'reclaimed-stale' | 'renewed' | 'released' | 'release-noop';
+    claimedBy?: string;
+    claimedAt?: string;
+    heldBy?: string;
+    heldSince?: string;
+    previousClaimant?: string;
+    wasClaimedBy?: string;
+}
+/**
+ * `claim` / `release` / `renew` an issue's lease (§6.3.5). One `immediate`
+ * transaction; the CAS decision and the metadata touch both run against the
+ * SAME `tx` the transaction opened, so two concurrent callers against the
+ * SAME `uid` serialize through the transaction's RESERVED lock — the loser's
+ * own re-fetch (inside its own attempt, after the winner commits) sees the
+ * winner's already-written `claimedBy`/`claimedAt`, never a stale
+ * pre-transaction read.
+ *
+ * Rule table (SPEC.md §6.3.5, restated here for the metadata-only shape the
+ * lease now lives in):
+ *
+ * | action    | current `claimedBy`                                  | outcome |
+ * |-----------|-------------------------------------------------------|---------|
+ * | `claim`   | unset                                                   | write `{claimedBy, claimedAt}`; `status:'claimed'` |
+ * | `claim`   | `== by`                                                 | no-op write of `claimedAt`; `status:'held'` |
+ * | `claim`   | `!= by`, age < `claim_stale_after_min`, `!force`        | throws `ClaimHeldError` |
+ * | `claim`   | `!= by`, age ≥ threshold, OR `force:true`               | write `{claimedBy, claimedAt}`; `status:'reclaimed-stale'`, `previousClaimant` |
+ * | `release` | `== by`                                                 | clear both fields; `status:'released'` |
+ * | `release` | `!= by` or unset                                        | no write; `status:'release-noop'`, `wasClaimedBy` |
+ * | `renew`   | `== by`                                                 | bump `claimedAt`; `status:'renewed'` |
+ * | `renew`   | `!= by` or unset                                        | throws `ClaimHeldError` |
+ *
+ * **Audit.** Every branch that performs a real write emits exactly one
+ * `audit` node via {@link writeAudit}, inside the SAME transaction (§4a "no
+ * bare mutation"). `writeAudit`'s own doc comment enumerates the audit
+ * `action` vocabulary as `'claimed'`/`'released'`/`'renewed'`/
+ * `'reclaimed-stale'` — four values, not five — so the `claim`-when-`== by`
+ * ("held", an idempotent re-affirmation of an already-owned claim) branch
+ * reuses `action:'claimed'`; its `IClaimOutcome.status` is still the distinct
+ * `'held'` value the rule table names, carried in the OUTCOME, not the audit
+ * action string. The two branches the rule table marks "no write"
+ * (`release-noop`) perform no touch and emit no audit — nothing changed, so
+ * §4a's "every STATE CHANGE writes an audit node" does not apply. This
+ * reading resolves a genuine tension in SPEC.md §6.3.5 (see this package's
+ * write-verb report for the full citation) between "every branch writes an
+ * audit node" and the rule table's own "no write" / four-action vocabulary;
+ * it is the only reading consistent with `writeAudit`'s own doc comment.
+ *
+ * **`renew` against an unclaimed issue.** The rule table assigns this to the
+ * SAME `ClaimHeldError` outcome as "held by someone else" — but there is no
+ * real holder to report. SPEC.md does not resolve this case explicitly; this
+ * implementation reports `ClaimHeldError('', '')` (empty-string sentinels,
+ * never a fabricated agent name or timestamp) so the thrown error's shape is
+ * still exactly `ClaimHeldError` per the rule table, without inventing data
+ * the graph does not have.
+ *
+ * Errors: `InvalidArgumentError` (`uid`/`by` missing/blank, or `action`
+ * outside the closed `'claim'|'release'|'renew'` 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), `IssueNotFoundError` (no live `issue` node
+ * carries `uid`), `ClaimHeldError` (per the rule table above),
+ * `IssueTerminalError` (`action:'claim'` only — the issue's current status
+ * is `terminal`; `release`/`renew` are exempt, since cleanup on an issue
+ * that got closed out from under the claimant must still succeed),
+ * `WriteContentionError`/`WriteIOError` (§4c — an exhausted driver-level
+ * retry on the underlying `immediate` transaction).
+ */
+export declare function claim(handle: IWriteStoreHandle, input: IClaimInput): Promise<IClaimOutcome>;