@adhd/backlog 0.1.9 → 1.0.1

package/write/catalog.d.ts

@@ -0,0 +1,369 @@
+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;
+    /**
+     * External filesystem roots (absolute paths) this project may cite from, in
+     * ADDITION to its own `metadata.path` root (BUG c6d35272). A citation target
+     * is accepted iff its CANONICAL (symlink-resolved) path lies within the
+     * project root OR one of these roots (`citation-path.ts`'s
+     * `resolveCitationTarget`); a `..` traversal or a symlink that escapes stays
+     * rejected, and an arbitrary absolute path outside every root is never
+     * readable. Only the resulting `sha` is persisted — never file content.
+     *
+     * This layer defaults to the EMPTY array, and {@link resolveProjectPolicy}'s
+     * injected runtime default (`defaultCitationAllowedExternalRoots()`) is ALSO
+     * empty — there is NO machine-global default root (BUG 62059b57 follow-up:
+     * the store's `~/.adhd/backlog` data home is not citable). A project opts
+     * into the external carve-out by naming roots here; an empty array (the
+     * default, or an explicit `[]`) leaves it disabled. This is TYPED,
+     * per-project config — deliberately never an environment toggle.
+     */
+    readonly citationAllowedExternalRoots: readonly string[];
+    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/citation-path.d.ts

@@ -0,0 +1,133 @@
+/**
+ * citation-path.ts — the citation-path containment contract (BUG c6d35272).
+ *
+ * A citation's `sha` hashes EXTERNAL file content (§6.3.2/§8.5). By default a
+ * citation target must resolve INSIDE the owning project's own root
+ * (`project.metadata.path`): that keeps the read surface confined to the tree
+ * the project already owns, so a citation can never be used as a
+ * file-exists/readable oracle for an arbitrary absolute path elsewhere on the
+ * host. But some genuine evidence lives OUTSIDE that root — a machine-level
+ * tool (`~/.local/bin/gx`), a globally-installed package's `dist/**`, a
+ * `/tmp` scratch artifact, or any root the project explicitly allowlists via
+ * `citationAllowedExternalRoots`. Before this module the ONLY way to cite such
+ * evidence on a path-PRESENT project was to omit the citation entirely —
+ * which `create`
+ * still reported as SUCCESS, silently downgrading a labelled-unverified
+ * citation to an unlabelled absence (exactly what "No citation, no claim"
+ * forbids).
+ *
+ * The carve-out is a TYPED, per-project ALLOWLIST — `project_policy.
+ * citationAllowedExternalRoots` (see `catalog.ts`'s `IProjectPolicy`) — never
+ * an env toggle and never a blanket "any absolute path" escape. A citation is
+ * accepted iff its CANONICAL (symlink-resolved) target lies within the project
+ * root OR within one of the project's allowed external roots. Every allowed
+ * root is itself canonicalized before comparison, so:
+ *
+ * - a relative `../…` traversal cannot widen the surface (it resolves to an
+ *   absolute candidate that is then containment-checked);
+ * - a symlink INSIDE the root that points OUTSIDE it is rejected (the
+ *   canonical target is outside every root) — this is the same defect the
+ *   sibling item c6d90ddf names, closed here for free by canonicalizing;
+ * - a root that is itself reached through a symlink still matches, because
+ *   both the candidate and the root are canonicalized through the SAME
+ *   `realpath` pass.
+ *
+ * Nothing here reads file CONTENT — only paths are resolved and compared.
+ * Only the resulting sha is ever persisted (§8.5); the citation node stores
+ * `target`/`sha`, never the bytes.
+ */
+/**
+ * The default external roots a project may cite from, used when the project's
+ * own policy supplies no `citationAllowedExternalRoots`. This is the EMPTY
+ * array: the runtime grants NO machine-global default root.
+ *
+ * Why: the runtime's own data home, `~/.adhd/backlog`, is the STORE's home,
+ * not an evidence tree. It holds only the machine-global backlog database
+ * (`production/data/backlog-v2.db`) and its snapshots (`production/backup-*`,
+ * top-level `backup-*`/`backups/`), plus the `test/` store. Granting it as a
+ * default root let a citation's `sha` read/hash surface resolve straight INTO
+ * the shared backlog graph — the very graph the citation containment exists to
+ * keep out of citation reads. The earlier narrowing from `~/.adhd` down to
+ * `~/.adhd/backlog` (BUG 62059b57) stopped one directory too high (BUG
+ * 62059b57 follow-up).
+ *
+ * This does NOT gut the carve-out MECHANISM: a project that genuinely needs a
+ * specific external root (a machine tool, a globally-installed package's
+ * `dist/**`) names it explicitly in `project_policy.citationAllowedExternalRoots`,
+ * and that typed, per-project allowlist is unchanged. Only the unearned
+ * machine-global default is gone.
+ *
+ * Deliberately a FUNCTION, called LAZILY by {@link resolveProjectPolicy} on
+ * every policy resolve, never a module-level constant: the call surface stays
+ * stable if a legitimate machine-global root is ever re-introduced, and every
+ * caller keeps the lazy, per-resolve contract.
+ */
+export declare function defaultCitationAllowedExternalRoots(): string[];
+/**
+ * Render `root` for a human-facing error message: `~`-anchored when it lies
+ * under the current home directory, the bare absolute path otherwise. Keeps
+ * the `CitationUnverifiableError` message stable across machines (a literal
+ * `/Users/<name>/.adhd` would leak the operator's identity and differ per
+ * host, making the message hard to assert on).
+ */
+export declare function displayExternalRoot(root: string): string;
+/**
+ * Lexical containment: does `candidate` sit at or under `root`?
+ *
+ * Uses `path.relative` — NEVER a bare `startsWith(root)`, which a sibling
+ * directory sharing a name prefix would defeat (`/repo` vs `/repo-evil`:
+ * `'/repo-evil/x'.startsWith('/repo')` is `true`). Both arguments are expected
+ * to be ABSOLUTE and (ideally) canonical already; this function is purely
+ * lexical and performs no I/O.
+ */
+export declare function isPathWithin(root: string, candidate: string): boolean;
+/**
+ * The §4c "the file genuinely is not there" error taxonomy, in ONE place.
+ *
+ * `ENOENT` (a path segment does not exist) and `ENOTDIR` (a path segment that
+ * should be a directory is in fact a file, so the target cannot exist) both
+ * mean exactly "not there" — the ONLY case any caller may degrade to the
+ * `'unverified'` sentinel. Every other errno (`EACCES`, `EPERM`, `EMFILE`,
+ * `EISDIR`, `ELOOP`, …) is a REAL I/O failure and must never be masked as an
+ * absent file. Shared by {@link canonicalizePath} and both write verbs'
+ * `computeCitationSha` (BUG c6d35272 follow-up) so that taxonomy is
+ * single-source and cannot drift between its three call sites.
+ *
+ * NOT used by `tools/etl/citation.ts`: that frozen tool deliberately ALSO
+ * exempts `EISDIR` (its own documented, corpus-driven divergence), so folding
+ * it into this narrower ENOENT/ENOTDIR predicate would regress it.
+ */
+export declare function isMissingPathError(err: unknown): boolean;
+/**
+ * Resolve `p` to its real, symlink-free absolute path.
+ *
+ * `p` need not exist. On `ENOENT`/`ENOTDIR` the nearest EXISTING ancestor is
+ * canonicalized and the non-existent tail is re-joined onto it, so a citation
+ * naming a file that does not exist still yields a stable absolute candidate
+ * for the containment check — the "does it actually exist / is it readable?"
+ * verdict is deliberately left to the caller's `readFile` (which the write
+ * layer's error taxonomy degrades to the `'unverified'` sentinel on
+ * ENOENT/ENOTDIR, `WriteIOError` otherwise). Any OTHER error (EACCES, ELOOP,
+ * …) propagates untouched — a real I/O fault must never be masked as a
+ * missing file.
+ */
+export declare function canonicalizePath(p: string): Promise<string>;
+/** The outcome of {@link resolveCitationTarget}. */
+export interface IResolvedCitationTarget {
+    /** `true` iff the canonical candidate lies within the project root or one of `allowedRoots`. */
+    accepted: boolean;
+    /** The CANONICAL (symlink-resolved) absolute path — the exact path the caller should read. Returned even when `accepted` is `false`, for a caller that wants to report it. */
+    candidate: string;
+}
+/**
+ * Decide whether `file` (absolute, or relative to `projectRoot`) is a
+ * citable target: canonical containment against `projectRoot` ∪
+ * `allowedRoots`. See this module's header for the security model.
+ *
+ * `projectRoot` and every entry of `allowedRoots` are canonicalized through
+ * the SAME pass as the candidate, so a root reached via a symlink still
+ * matches its own contents (and a root that does not exist is canonicalized
+ * to its nearest existing ancestor + the literal tail, exactly like the
+ * candidate).
+ */
+export declare function resolveCitationTarget(projectRoot: string, file: string, allowedRoots: readonly string[]): Promise<IResolvedCitationTarget>;

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>;