@adhd/backlog 1.0.4 → 1.0.6

package/store/catalog-invariant-guard.d.ts

@@ -26,7 +26,7 @@ export type CatalogInvariantViolation = {
  */
 export declare function renderCatalogInvariantViolations(violations: ReadonlyArray<CatalogInvariantViolation>): string;
 /**
- * The status/priority catalog violates an invariant this build's read layer
+ * The status/priority/kind catalog violates an invariant this build's read layer
  * depends on. Carries the offending rows as structured fields so a caller can
  * render them; the message itself names every row AND the repair.
  */
@@ -35,7 +35,7 @@ export declare class CatalogInvariantError extends Error {
     constructor(violations: ReadonlyArray<CatalogInvariantViolation>);
 }
 /**
- * Read every live status/priority row and return the invariant violations.
+ * Read every live status/priority/kind row and return the invariant violations.
  * A pure read — it never writes, so it is safe against any store, including
  * the live one.
  *
@@ -46,17 +46,23 @@ export declare class CatalogInvariantError extends Error {
  */
 export declare function inspectCatalogInvariants(adapter: StoreAdapter): Promise<CatalogInvariantViolation[]>;
 /**
- * Assert the store's status/priority catalog satisfies both invariants.
+ * Assert the store's status/priority/kind catalog satisfies both invariants.
  *
  * Passes (no throw) on an empty store, and on a catalog whose reserved
  * terminal statuses are flagged and whose same-kind names are fold-unique.
  * Throws {@link CatalogInvariantError}, naming every offending row and the
  * repair that resolves it, otherwise.
  *
- * BOUNDED BY CONSTRUCTION: this runs on every write verb (`api.ts`'s
- * `writeHandle`), every query (`api.ts`'s `queryHandle` → `query.ts`), and
- * store open (`openGraphBacklogStore`), so it must not scan the store per
- * call. It reads only the (small) status/priority catalog — see
+ * WHERE IT RUNS: the `store-check` CLI verb — a NAMED, non-zero check an
+ * operator runs deliberately — plus any caller that asserts deliberately via
+ * `IQueryStoreHandle.assertCatalogInvariants`. It is deliberately NOT run on
+ * the ordinary read path (`queryIssuesWithMeta`), on the write path (`api.ts`'s
+ * `writeHandle`), or at store open (`openGraphBacklogStore`): a violation must
+ * be detected loudly and REPORTED, never allowed to turn every read — or every
+ * unrelated write — into an outage.
+ *
+ * BOUNDED BY CONSTRUCTION: it must not scan the issue graph per call. It reads
+ * only the (small) status/priority/kind catalog — see
  * {@link inspectCatalogInvariants}.
  */
 export declare function assertCatalogInvariants(adapter: StoreAdapter): Promise<void>;

package/vocabulary.d.ts

@@ -0,0 +1,48 @@
+/**
+ * vocabulary.ts — the ONE pinned list of the data verbs this package mounts
+ * (SPEC.md §6.7), plus nothing else.
+ *
+ * ## Why this is its own leaf module
+ *
+ * `BACKLOG_VERBS` is read by two callers that must never drift apart:
+ *
+ *  - `server.ts` — the mount-time carve-out check and the four-transport
+ *    surface projection; and
+ *  - `query/views/catalog.ts` — the generated `verb` catalog, which must
+ *    enumerate the SAME advertised surface a consumer reads.
+ *
+ * If `catalog.ts` imported `server.ts` for the list, the whole query layer
+ * would transitively load the server's fastify/MCP plugin graph (a runtime
+ * cycle `server → api → query → catalog → server`), which is both a startup
+ * cost and a needless coupling. Declaring the constant in a module with zero
+ * imports keeps `catalog.ts` on the leaf and lets `server.ts` re-export the
+ * identical binding, so there is still exactly ONE list.
+ *
+ * The comment body below is reproduced verbatim from `server.ts` (its former
+ * home) so the "why this list is pinned" rationale stays attached to the
+ * value rather than the file it happens to live in.
+ */
+/**
+ * SPEC.md §6.7 — the data verbs the whole surface consolidates onto:
+ * the nine issue verbs plus `lookup`, §3a's registry CRUD verbs, and the
+ * three §5 stats/rollup reads (`priority-matrix`/`part-of-rollup`/
+ * `open-curve`), mounted as `backlog_<verb>`. Pinned here, next to the
+ * carve-out it is the complement of, because it is the ONE list four separate
+ * surfaces are checked against: the three apigen mounts derive their names
+ * from the operation descriptors via `describeMountedSurface`, and `cli.ts`'s
+ * argv parser — which is deliberately NOT an apigen mount, because apigen's
+ * `parseArgs` cannot express the §2.1b positional form, projects `string[]`
+ * as a JSON-valued flag where §7.3 wants comma-separated, and only sets
+ * `process.exitCode` on a thrown `ApiError` (so an `ok:false` envelope would
+ * exit 0, contradicting `BACKLOG_EXIT_CODE`) — has to be checked against this
+ * list rather than derived from the mount.
+ *
+ * That asymmetry is exactly how a split brain starts, and this repo already
+ * has one open as BUG-BACKLOG-MCP-CLI-SPLIT-BRAIN-001. `server.verbs.spec.ts`
+ * asserts BOTH sides against this constant so a verb added to one surface and
+ * forgotten on the other fails a test instead of shipping.
+ *
+ * Order is the SPEC.md §4/§6 declaration order, not alphabetical; compare as
+ * sets.
+ */
+export declare const BACKLOG_VERBS: readonly string[];

package/write/anchor-check.d.ts

@@ -0,0 +1,139 @@
+/**
+ * anchor-check.ts — the cheap-first mechanical anchor ladder (C3, DESIGN §2
+ * Primitive 2).
+ *
+ * An attestation's `anchor` is a `locator + digest`. This module parses the
+ * closed locator grammar and resolves a `path:` anchor against the subject
+ * project's git work tree, in the cheapest useful order:
+ *
+ *   1. `existsAtHead`      — `git cat-file -e HEAD:<relpath>` (exit 0 =
+ *      present). No file read, no network, no agent.
+ *   2. `changedSinceFiling`— `git log --since=<t> -- <relpath>` non-empty.
+ *   3. full re-resolve     — ONLY when `opts.full` is set (`recheck`, and the
+ *      verdict's own rung 5): hash the HEAD blob and compare to the anchor's
+ *      `digest`.
+ *
+ * Every outcome carries the rung that produced it (`method`), so `verified` /
+ * `stale` / `unknown` / `unverified` are EXPLICIT states with a `reason` —
+ * never an absent field, never a silent success.
+ *
+ * The whole module is pure with respect to the store (no writes); it shells to
+ * the local `git` CLI the repo already uses. A missing `git`, a non-repo root,
+ * or an unresolvable path degrades to `unknown`, never a thrown exception —
+ * `unknown` is a first-class value here (Wikidata deprecate-with-reason, C2PA
+ * claim-vs-assertion). `refuted` is deliberately absent: a mechanical anchor
+ * proves present/matching/stale/absent only, never "the claim is contradicted".
+ */
+/** The closed set of mechanical-check states. `refuted` is deliberately absent (see module header). */
+export type AttestationCheckState = 'unverified' | 'verified' | 'stale' | 'unknown';
+/**
+ * One rung-result of the anchor ladder. `method` names which rung actually ran
+ * (`'exists_at_head'` | `'changed_since'` | `'full_resolve'` | `'none'`), so a
+ * cheap pre-filter can be proven cheap (AC7) and a full re-resolve is visible.
+ */
+export interface IAttestCheck {
+    state: AttestationCheckState;
+    method: string;
+    checked_at: string;
+    checked_by: string;
+    reason?: string;
+}
+/**
+ * An anchor is `locator + digest`. The locator grammar is closed:
+ * `path:<file>[:<line>]` | `url:<url>` | `query:<cql>` | `registry:<ref>` |
+ * `commit:<sha>` (C5: ancestry of the default branch).
+ * A bare hand-maintained `path:line` is INSUFFICIENT without a `digest` — the
+ * digest is the whole point of content-addressing the claim.
+ */
+export interface IAttestationAnchor {
+    locator: string;
+    digest: string;
+}
+/** The parsed form of a locator (one arm per grammar production). */
+export type IParsedAnchor = {
+    scheme: 'path';
+    target: string;
+    line?: number;
+} | {
+    scheme: 'url';
+    target: string;
+} | {
+    scheme: 'query';
+    target: string;
+} | {
+    scheme: 'registry';
+    target: string;
+} | {
+    scheme: 'commit';
+    target: string;
+} | {
+    scheme: 'revision';
+    target: string;
+};
+/**
+ * The closed set of locator SCHEMES the grammar names (C3 added
+ * `path|url|query|registry`; C5 adds `commit:<sha>`; C10 adds `revision:<uid>`).
+ * Kept as an exported alias so a consumer (the C5 gate) can branch on the
+ * scheme without re-listing it.
+ */
+export type AnchorLocatorKind = 'path' | 'url' | 'query' | 'registry' | 'commit' | 'revision';
+/** Options for {@link checkAnchor}. */
+export interface ICheckAnchorOptions {
+    /** The subject project's root (git work tree) — absent means `unknown`. */
+    root?: string;
+    /** ISO filing time for the changed-since rung. Absent skips rung 2. */
+    sinceISO?: string;
+    /** Run the full re-resolve (rung 3: hash HEAD content and compare to `digest`). */
+    full?: boolean;
+    now: string;
+    by: string;
+}
+/**
+ * Parse `locator` against the closed grammar, throwing
+ * {@link AnchorLocatorInvalidError} for anything outside it (a blank locator,
+ * an unknown scheme, an empty body). `path:` accepts an optional trailing
+ * `:<digits>` line number; every other scheme carries its body verbatim.
+ */
+export declare function parseAnchor(locator: string): IParsedAnchor;
+/** Whether `root` is (inside) a git work tree — the precondition for rungs 1–3. */
+export declare function isGitWorkTree(root: string): boolean;
+/**
+ * Rung 1 — is `relpath` present at `HEAD`? Exit 0 = present; any other exit
+ * (missing object, not a repo) = not present. Cheap: no content is read.
+ */
+export declare function existsAtHead(root: string, relpath: string): boolean;
+/**
+ * Rung 2 — did any commit touch `relpath` at/after `sinceISO`? `git log
+ * --since` compares against committer date, so this is a genuine "has the
+ * tracked file moved since we filed" probe with no content read.
+ */
+export declare function changedSinceFiling(root: string, relpath: string, sinceISO: string): boolean;
+/** The mechanical check a `commit:` anchor names — the one string every refusal carries as `performed_check`. */
+export declare const DEFAULT_BRANCH_ANCESTOR_CHECK: "default_branch_ancestor";
+/** The result of the default-branch check: whether `sha` is an ancestor of the resolved default branch, and the named check that produced it. */
+export interface IDefaultBranchCheck {
+    onDefaultBranch: boolean;
+    performed: string;
+}
+/**
+ * Is `<sha>` an ancestor of the repo's default branch? Shells
+ * `git merge-base --is-ancestor <sha> <default>`, exactly as C3's anchor ladder
+ * shells `git cat-file`/`git log`. Returns `{onDefaultBranch:false,
+ * performed:'default_branch_ancestor'}` when the repo or the branch cannot be
+ * resolved (fail-closed, never a silent pass) — the `performed` field is
+ * present in every outcome so the caller can name the mechanical check.
+ */
+export declare function isShaOnDefaultBranch(repoRoot: string, sha: string, defaultBranch?: string): Promise<IDefaultBranchCheck>;
+/**
+ * Run the cheap-first ladder against `anchor` and return the rung-result.
+ *
+ * A non-`path` locator (`url:`/`query:`/`registry:`) has no mechanical checker
+ * wired, so it is explicitly `unverified` — never an absent field. A `path:`
+ * anchor with no resolvable root, or a root that is not a git work tree, is
+ * `unknown` (a genuine "could not determine", distinct from "gone").
+ *
+ * Throws {@link AnchorLocatorInvalidError} (a caller-input mistake) when the
+ * locator is outside the closed grammar; every other failure is a reported
+ * state, not a throw.
+ */
+export declare function checkAnchor(anchor: IAttestationAnchor, opts: ICheckAnchorOptions): IAttestCheck;

package/write/attestation.d.ts

@@ -0,0 +1,64 @@
+import { IWriteStoreHandle } from './tx.js';
+import { AttestationCheckState, IAttestCheck, IAttestationAnchor } from './anchor-check.js';
+
+export type { AttestationCheckState, IAttestCheck, IAttestationAnchor };
+/**
+ * An issue revision reference: the numeric monotonic counter, or — for C10's
+ * `SPEC`-node annotations — an opaque `sha256:<hex>` token. Additive only: an
+ * `issue` subject with a numeric revision is byte-for-byte unchanged.
+ */
+export type AttestRevisionRef = number | string;
+/** The claim an attestation asserts. `kind` is open vocabulary (e.g. `'published-artifact'`, `'live-system'`); `body` is free text. */
+export interface IAttestClaim {
+    kind: string;
+    body?: string;
+}
+export interface IAttestInput {
+    /** The LOGICAL subject: chain-head `uid` + the content `revision` observed. */
+    subject: {
+        id: string;
+        revision: AttestRevisionRef;
+    };
+    claim: IAttestClaim;
+    anchor: IAttestationAnchor;
+    by: string;
+}
+export interface IAttestOutcome {
+    attestationUid: string;
+    subject: {
+        id: string;
+        revision: AttestRevisionRef;
+    };
+    check: IAttestCheck;
+}
+export interface IRecheckInput {
+    attestationUid: string;
+    by: string;
+}
+export interface IRecheckOutcome {
+    attestationUid: string;
+    checks: IAttestCheck[];
+}
+/**
+ * Create an attestation — a new `attestation` node + `attests` edge against
+ * the LIVE subject issue, plus one `audit` row. The subject node is NEVER
+ * mutated (no `UPDATE node … WHERE rowid = subject`).
+ *
+ * Errors: `InvalidArgumentError` (blank `subject.id`/`claim.kind`/`by`, an
+ * absent `subject.revision`), `AnchorLocatorInvalidError` (a locator outside
+ * the closed grammar, or a blank `anchor.digest`),
+ * `StaleSupersedeError`/`IssueNotFoundError` (the subject uid is superseded or
+ * unknown), `WriteContentionError`/`WriteIOError` (an exhausted driver-level
+ * retry on the underlying `immediate` transaction).
+ */
+export declare function attest(handle: IWriteStoreHandle, input: IAttestInput): Promise<IAttestOutcome>;
+/**
+ * Re-run the anchor ladder against an existing attestation and APPEND the new
+ * check to `checks[]` (earlier entries copied forward verbatim — never a
+ * truncated history). Replaces the echoed `check` with the newest entry and
+ * writes one `audit` row on the attestation node.
+ *
+ * Errors: `InvalidArgumentError` (blank `by`), `AttestationNotFoundError` (no
+ * live `attestation` node carries the uid).
+ */
+export declare function recheck(handle: IWriteStoreHandle, input: IRecheckInput): Promise<IRecheckOutcome>;

package/write/catalog-merge.d.ts

@@ -1,8 +1,8 @@
 import { IWriteStoreHandle } from './tx.js';
 import { NodeRecord } from '@adhd/sox-graph-store';
 
-/** The two catalog kinds this repair collapses (D3's whole scope). */
-export type CatalogKind = 'status' | 'priority';
+/** The catalog kinds this repair collapses (D3's scope, widened to `kind` by C8). */
+export type CatalogKind = 'status' | 'priority' | 'kind';
 /**
  * A status fold group that CANNOT be safely collapsed: two or more LIVE rows
  * share a fold, yet none carries the write path's lowercase spelling. Merging
@@ -75,16 +75,23 @@ export interface IMergeJournal {
  *
  * Grouping is by {@link catalogNameFold} alone. Within a fold group the
  * canonical is the member already carrying the write path's spelling for that
- * kind — lowercase for `status`, uppercase for `priority`.
+ * kind — lowercase for `status`, uppercase for `priority`, lowercase for the
+ * OPEN `kind` vocabulary (its canonical rule).
  *
  * A `priority` group with no upper-spelled member falls back to its
  * lowest-rowid member (deterministically renamed to uppercase at apply, as
- * before). A `status` group with no lower-spelled member is NOT planned at all:
- * any canonical would carry a spelling the write path never emits, so merging
- * would regenerate the fragment on the next ordinary `create`. It is surfaced
- * in `unmergeable` instead.
+ * before). A `status` OR `kind` group with no lower-spelled member is NOT
+ * planned at all: any canonical would carry a spelling the write path / fold
+ * lookup would not re-find, so merging would regenerate the fragment on the
+ * next ordinary `create`. It is surfaced in `unmergeable` instead.
+ *
+ * `liveKinds` is OPTIONAL and ADDITIVE (C8): existing two-argument callers
+ * keep their exact behavior, and a caller that wants the `kind` repair passes
+ * the live `kind` rows. (A kind cannot be planned without its rows entering
+ * somewhere; the spec's "unchanged signature" is honoured as "unchanged for
+ * every existing caller".)
  */
-export declare function planCaseFragmentMerge(liveStatuses: readonly NodeRecord[], livePriorities: readonly NodeRecord[]): IMergePlan;
+export declare function planCaseFragmentMerge(liveStatuses: readonly NodeRecord[], livePriorities: readonly NodeRecord[], liveKinds?: readonly NodeRecord[]): IMergePlan;
 /**
  * Apply the plan in ONE `executeWriteTransaction` (`BEGIN IMMEDIATE` + bounded
  * busy-only retry, §4c) — every group in the plan commits together or not at

package/write/catalog.d.ts

@@ -1,9 +1,16 @@
 import { IComponentSummary, ILocationSummary, ILocationType, IProjectSummary } from '../query/types.js';
 import { IEdgeKindRule, IWriteStoreHandle } from './tx.js';
+import { isUidShaped } from './uid-prefix.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;
+/**
+ * Disambiguation by SHAPE, not a second field (§6.1): a 36-character
+ * version-4-UUID-formatted string is a `uid`; anything else is a `name`. The
+ * single definition lives in `write/uid-prefix.ts` (which also owns prefix
+ * classification); re-exported here so every existing `isUidShaped` importer
+ * keeps its path unchanged.
+ */
+export { isUidShaped };
 export interface IResolvedCatalogRow {
     rowid: number;
     uid: string;
@@ -55,6 +62,16 @@ export interface IMintOrResolveInput {
      * of any one issue's logical write, so they keep their own clock.
      */
     at?: string;
+    /**
+     * A DEPRECATED catalog name
+     * (`meta.lifecycle === 'deprecated'`, or a `kind` in the frozen
+     * {@link DEPRECATED_KIND_NAMES} set) is REFUSED on mint/resolve unless this
+     * is `true` — a typed caller decision, never an env var. Refusal throws
+     * `InvalidArgumentError('kind', …)` naming `meta.replacedBy` (or the in-code
+     * {@link DEPRECATED_KIND_REPLACEMENTS} fallback), so the caller is told the
+     * term to use instead. Only `kind` currently has a deprecated vocabulary.
+     */
+    allowDeprecated?: boolean;
 }
 /**
  * The reserved TERMINAL status vocabulary — the ONE in-code definition
@@ -87,6 +104,29 @@ export interface IMintOrResolveInput {
 export declare const RESERVED_TERMINAL_STATUS_NAMES: ReadonlySet<string>;
 /** Whether `name` is one of {@link RESERVED_TERMINAL_STATUS_NAMES} under the case fold — so any spelling of the reserved terminal vocabulary (`closed`/`Closed`/`CLOSED`, `fixed`/`FIXED`) counts. */
 export declare function isReservedTerminalStatusName(name: string): boolean;
+/**
+ * The RETIRED `kind` vocabulary — the borrowed terms the C8 spec retires with
+ * a replacement, modelled on {@link RESERVED_TERMINAL_STATUS_NAMES}: a frozen
+ * in-code set, so a retired term is refused on mint even before (or without) a
+ * row-level `meta.lifecycle:'deprecated'` data change. Membership is decided on
+ * the FOLDED name ({@link catalogNameFold}), so `EPIC`/`epic` are one term.
+ *
+ * `EPIC` is the one entry: it is a borrowed Jira primitive re-expressed by the
+ * existing `FEAT` kind (DESIGN §2 Invariant 6 / §6 "re-express in place, never
+ * re-key"). The replacement lives in {@link DEPRECATED_KIND_REPLACEMENTS}.
+ */
+export declare const DEPRECATED_KIND_NAMES: ReadonlySet<string>;
+/**
+ * The term to use instead of each {@link DEPRECATED_KIND_NAMES} entry. Kept
+ * separate from the name set so a row's live `meta.replacedBy` (a reviewed
+ * repair's own decision) is preferred when present, with this map as the
+ * in-code fallback the error and the generated catalog both name.
+ */
+export declare const DEPRECATED_KIND_REPLACEMENTS: ReadonlyMap<string, string>;
+/** Whether `name` is a RETIRED `kind` term under the case fold — `EPIC`/`epic` both count. */
+export declare function isDeprecatedKindName(name: string): boolean;
+/** The in-code replacement for a deprecated `kind` name, or `undefined` when it is not one. */
+export declare function deprecatedKindReplacement(name: string): string | undefined;
 /**
  * The flat-catalog find-then-create (§1, §4c, §6.1): `kind`/`status`/
  * `priority`/`agent` are mintable on an unresolved NAME; a uid-shaped `ref`
@@ -219,7 +259,30 @@ export interface IProjectPolicy {
     readonly allowedKinds: readonly string[];
     /** `project_field_requirement` — field names required on every mutating write for this project (§2). */
     readonly requiredFields: readonly string[];
+    /**
+     * C9 — how wide the CREATE-TIME advisory similarity scan looks. `'same-project'`
+     * (the default) is byte-for-byte today's behaviour (AC1); `'multi-project'`
+     * adds sibling projects reachable via a shared `repoUrl`/`component.meta.path`;
+     * `'store-wide'` drops the id restriction entirely. This NEVER widens the
+     * WRITE path — the scan is advisory and writes nothing (AC3) — it only widens
+     * which existing items may be surfaced as similar candidates.
+     */
+    readonly similarityScope: ISimilarityScope;
+    /**
+     * C9 — cosine threshold for CROSS-project candidates. Deliberately a DISTINCT
+     * value from `dedupeThreshold` (which stays calibrated for same-project
+     * byte-identical refiles): sharing one number either re-suppresses legitimate
+     * cross-repo filings or admits boilerplate (AC7/AC8). Enforced distinct by
+     * test, not by a runtime assertion.
+     */
+    readonly similarityCrossProjectThreshold: number;
+    /** C9 — minimum top-vs-next cosine gap for a cross-project candidate (margin guard). A candidate that is not meaningfully more similar than the runner-up is ambiguous and is not surfaced. */
+    readonly similarityCrossProjectMargin: number;
+    /** C9 — minimum title-token Jaccard overlap required as the second independent signal for a cross-project candidate (AC7). Cosine alone is never sufficient cross-project. */
+    readonly similarityCrossProjectTokenOverlap: number;
 }
+/** C9 — the typed scan breadth for the create-time advisory similarity scan. */
+export type ISimilarityScope = 'same-project' | 'multi-project' | 'store-wide';
 export declare function resolveProjectPolicy(project: IResolvedProjectRow): IProjectPolicy;
 /**
  * Whether a resolved project has a known filesystem `path` (§8.4/§8.5) — the
@@ -349,6 +412,13 @@ export declare function upsertComponent(handle: IWriteStoreHandle, input: IUpser
  * runs before opening its transaction.
  */
 export declare function upsertComponentTx(tx: AdapterTransaction, handle: Pick<IWriteStoreHandle, 'typePolicy'>, input: IUpsertComponentInput): Promise<IUpsertComponentOutcome>;
+/**
+ * The closed `location_type` vocabulary (§3, §3a). The ONE in-code definition:
+ * `upsertLocation` validates against it, and `query/views/catalog.ts`'s
+ * generated `location_type` catalog projects from it. Exported (rather than a
+ * private const) so the catalog cannot become a second, hand-maintained copy.
+ */
+export declare const VALID_LOCATION_TYPES: readonly ILocationType[];
 export interface IUpsertLocationInput {
     /**
      * `component` reference — `uid` or `name` (§6.1's disambiguation-by-shape

package/write/citation-path.d.ts

@@ -131,3 +131,34 @@ export interface IResolvedCitationTarget {
  * candidate).
  */
 export declare function resolveCitationTarget(projectRoot: string, file: string, allowedRoots: readonly string[]): Promise<IResolvedCitationTarget>;
+/**
+ * The TOOL's OWN installed evidence roots — where this package installs its
+ * skill (`install-skill.ts`'s host table: `.claude/skills/backlog`,
+ * `$CODEX_HOME/skills/backlog`, `~/.config/opencode/skills/backlog`).
+ *
+ * These are citable by DEFAULT, and deliberately NARROWER than the
+ * machine-global `~/.adhd/backlog` store home this module's header rejects:
+ * they grant only the tool's own installed docs (a stable, versioned,
+ * human-authored evidence tree), never the store. Typed and always-on, so a
+ * project does not have to allowlist the tool it is using in order to cite
+ * the tool's own documentation.
+ *
+ * `home` is injectable for tests; it defaults to the real home directory.
+ */
+export declare function toolOwnedCitationRoots(home?: string): string[];
+/** The minimal read-only executor {@link resolveSiblingProjectRootsTx} needs — satisfied structurally by `AdapterTransaction` and the bare `StoreAdapter`. */
+export interface ISiblingRootExecutor {
+    executeAll<T = Record<string, unknown>>(sql: string, args?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+}
+/**
+ * The `metadata.path` of every LIVE `project` row EXCEPT `excludeProjectUid`.
+ *
+ * A citation into a *sibling registered project* must be probed against that
+ * project's OWN root, not the citing item's — otherwise a legitimate
+ * cross-repo citation falsely resolves to `unverified` and the write is
+ * refused (AC4). Path-less sibling projects contribute nothing (there is no
+ * root to check against).
+ */
+export declare function resolveSiblingProjectRootsTx(exec: ISiblingRootExecutor, excludeProjectUid: string): Promise<string[]>;

package/write/citation.d.ts

@@ -0,0 +1,157 @@
+import { IWriteStoreHandle } from './tx.js';
+import { IProjectPolicy, IResolvedProjectRow } from './catalog.js';
+import { ICitation, ICitationRecord } from '../citation.js';
+import { AdapterTransaction } from '@adhd/sox-store-adapter';
+
+/**
+ * §8.5's two-branch citation-sha rule, in ONE place (the generalization of the
+ * copy `create-issue.ts`/`transition.ts` each used to carry).
+ *
+ * Branch 1: a PATH-LESS project cannot content-address anything, so every
+ * citation degrades to the `'unverified'` sentinel up front.
+ *
+ * Branch 2a (revision-pinned): when `revision` is given, the target is resolved
+ * against the git revision (`git show <revision>:<relpath>`) rather than the
+ * working tree — so a file that exists only on an unmerged branch is citable.
+ * The read is confined to the project's own git object database (git refuses a
+ * `..` path), so no filesystem containment check is needed for it.
+ *
+ * Branch 2b (working tree): the target must resolve (canonically) within the
+ * project root OR within one of `allowedExternalRoots` —
+ * `citation-path.ts`'s {@link resolveCitationTarget}. The only filesystem read
+ * happens after acceptance.
+ *
+ * §4c's error taxonomy is preserved exactly: ENOENT/ENOTDIR → `'unverified'`
+ * (the file genuinely is not there); EISDIR → `CitationTargetIsDirectoryError`;
+ * any other errno → `WriteIOError` (`citationReadError`).
+ */
+export declare function computeCitationSha(project: IResolvedProjectRow, file: string, revision: string | undefined, allowedExternalRoots: readonly string[], siblingRoots?: readonly string[]): Promise<string>;
+/**
+ * Compute the sha for every citation in `citations`, in caller order — NO
+ * policy gate (see {@link assertCitationShasVerifiable}). This is the
+ * filesystem/git half of the citation-sha pre-resolve, callable on its own by a
+ * caller (`update`'s diff-emitter) that must defer the gate until it knows
+ * which citations are actually being ADDED.
+ */
+export declare function computeCitationShas(project: IResolvedProjectRow, citations: readonly ICitation[], allowedExternalRoots: readonly string[], siblingRoots?: readonly string[]): Promise<string[]>;
+/**
+ * Enforce `project_policy.citationRequiresSha` over an already-computed sha
+ * list, paired index-for-index with `citations`. Only where verification is
+ * POSSIBLE (the project has a known `path`) is a `"unverified"` sha a hard
+ * `CitationUnverifiableError` naming the allowed roots; a path-less project
+ * records `sha:"unverified"` verbatim, with the deliberate waiver logged (DEBT
+ * a934e089) rather than silently applied. `verb` names the caller in that log.
+ *
+ * Split from {@link computeCitationShas} so `update`'s diff-emitter can compute
+ * shas for its whole desired set but gate ONLY the citations it actually adds —
+ * so an issue holding a citation whose file has since vanished can still be
+ * updated (that already-live citation is neither re-added nor re-gated; only a
+ * genuinely new, unverifiable citation is refused).
+ */
+export declare function assertCitationShasVerifiable(project: IResolvedProjectRow, policy: IProjectPolicy, citations: readonly ICitation[], shas: readonly string[], verb: string): void;
+/**
+ * Compute AND policy-gate the sha for every citation in `citations`, in caller
+ * order — the ONE implementation `createIssue`/`transition`'s pre-transaction
+ * citation loop and `addCitation`'s single-citation resolve share. Composes
+ * {@link computeCitationShas} + {@link assertCitationShasVerifiable}.
+ */
+export declare function resolveCitationShas(project: IResolvedProjectRow, policy: IProjectPolicy, citations: readonly ICitation[], siblingRoots: readonly string[], verb: string): Promise<string[]>;
+/** Mint ONE `citation` node + its `has_citation` edge against the issue, inside the caller's open `tx`. NEVER writes an audit row — the calling verb owns the ONE audit its §4a contract requires. */
+export declare function appendCitationTx(tx: AdapterTransaction, handle: IWriteStoreHandle, params: {
+    issueRowid: number;
+    issueUid: string;
+    citation: ICitation;
+    sha: string;
+    at: string;
+}): Promise<{
+    rowid: number;
+    uid: string;
+}>;
+/** A live citation attached to an issue — just the identity + diff key the diff-emitter needs. */
+export interface ILiveCitationRow {
+    rowid: number;
+    uid: string;
+    /** {@link citationKey}-shaped (`file` + `lines`), read off the persisted `target`/`line`. */
+    key: string;
+}
+/**
+ * The LIVE citations currently attached to `issueRowid`, in edge order — the
+ * "live set" `update`'s diff-emitter compares a desired set against. A live
+ * `has_citation` edge whose target node is missing or invalidated is skipped
+ * defensively (the invariant is that the two are invalidated together, so this
+ * should never fire).
+ */
+export declare function readLiveCitationsTx(tx: AdapterTransaction, issueRowid: number): Promise<ILiveCitationRow[]>;
+/**
+ * Bi-temporally invalidate ONE citation: its node (`t_invalid` + a merged
+ * `meta.invalidatedReason`/`invalidatedAt`, never a wholesale replace — the
+ * `rmLocation`/`delete` shape) AND its owning `has_citation` edge. Hand-
+ * composed against `tx`.
+ *
+ * Never writes an audit row — the calling verb owns it (so `update` emits its
+ * single `'updated'` audit for a whole diff rather than one per citation).
+ */
+export declare function removeCitationTx(tx: AdapterTransaction, params: {
+    citationRowid: number;
+    citationUid: string;
+    at: string;
+    reason?: string;
+}): Promise<void>;
+export interface IAddCitationInput {
+    /** The `issue` uid the citation is attached to. */
+    uid: string;
+    /** The citation to add — the SAME {@link ICitation} contract `create`/`transition` accept, including the optional `revision`. */
+    citation: ICitation;
+    /** The acting identity (§6.3's opening rule). REQUIRED. */
+    by: string;
+}
+export interface IAddCitationOutcome {
+    /** The minted `citation` node's own uid — the identity `removeCitation` addresses. */
+    uid: string;
+    /** The issue the citation was attached to (unchanged). */
+    issueUid: string;
+    /** The minted citation, projected (the read shape). */
+    citation: ICitationRecord;
+}
+/**
+ * Add ONE citation to an existing issue (§6.3, §4). One `immediate`
+ * transaction: resolve `uid` → live `issue` → mint the `citation` node + its
+ * `has_citation` edge → `writeAudit`, all against the SAME `tx` (never the
+ * bare-adapter `writeNode`/`writeEdge`, §4c). The cited file's sha is computed
+ * BEFORE the transaction opens, exactly as `create`/`transition` do, so the
+ * write lock is never held across a filesystem/git read.
+ *
+ * Errors: `InvalidArgumentError` (blank `uid`/`by`/`citation.file`),
+ * `IssueNotFoundError` (no live `issue` carries `uid`), `StaleSupersedeError`
+ * (`uid` names a superseded issue), `CitationUnverifiableError` (the target did
+ * not resolve to a real sha and the owning project requires one — including a
+ * `revision` that does not resolve), `WriteContentionError`/`WriteIOError`
+ * (§4c).
+ */
+export declare function addCitation(handle: IWriteStoreHandle, input: IAddCitationInput): Promise<IAddCitationOutcome>;
+export interface IRemoveCitationInput {
+    /** The `citation` uid to soft-remove — the citation's OWN uid, never a `(target,line)` re-specification. */
+    uid: string;
+    /** The acting identity (§6.3's opening rule). REQUIRED. */
+    by: string;
+    /** Optional explanation recorded on the invalidation and the audit row (mirrors `rmLocation`'s `reason`). */
+    reason?: string;
+}
+export interface IRemoveCitationOutcome {
+    uid: string;
+    invalidated: true;
+}
+/**
+ * Soft-remove ONE citation by its own `uid` (§6.3, §4). One `immediate`
+ * transaction: resolve `uid` → LIVE `citation` node (`resolveCitationNodeTx`,
+ * never a bare `getNodeByUid`) → bi-temporally invalidate the node AND its
+ * `has_citation` edge ({@link removeCitationTx}) → `writeAudit`, all against the
+ * SAME `tx`. The citation's ISSUE is untouched: its uid is preserved and no
+ * node is superseded.
+ *
+ * Errors: `InvalidArgumentError` (blank `uid`/`by`), `CitationNotFoundError`
+ * (no LIVE `citation` node carries `uid` — including an already-removed uid, or
+ * a uid that names a node of a different kind, the "foreign citation" refusal),
+ * `WriteContentionError`/`WriteIOError` (§4c).
+ */
+export declare function removeCitation(handle: IWriteStoreHandle, input: IRemoveCitationInput): Promise<IRemoveCitationOutcome>;