@adhd/backlog 1.0.5 → 1.0.6

package/write/relate.d.ts

@@ -1,7 +1,7 @@
 import { IWriteStoreHandle } from './tx.js';
 
 /** The closed `rel` union `relate` accepts (§3/§6.3.6) — issue → issue in every case. */
-export type RelateRel = 'relates_to' | 'supersedes' | 'blocks' | 'duplicate_of' | 'part_of';
+export type RelateRel = 'relates_to' | 'supersedes' | 'blocks' | 'duplicate_of' | 'part_of' | 'similar_to';
 export interface IRelateInput {
     /** The relation's SOURCE `issue` uid (§1: uid is the only identifier — never a name, never repo-scoped). */
     sourceUid: string;

package/write/revision.d.ts

@@ -0,0 +1,27 @@
+/**
+ * revision.ts — the issue content-revision counter (DESIGN §2 Primitive 1/4).
+ *
+ * One revision counter, one name: `subject.revision` (Primitive 2) and
+ * `source_revision` (Primitive 4) are the SAME quantity — a monotonic counter
+ * on the issue's own `meta.revision`, bumped on every mutating write. A check
+ * or a verdict is stale relative to this one counter, so it must be read
+ * through one function rather than each consumer re-deriving it.
+ *
+ * This module is pure (no store, no I/O): it reads only the `meta` blob a
+ * caller already has in hand. `C6`'s verdict layer owns the bump sites
+ * (`create-issue` seeds `revision: 0`; `update`/`transition`/`claim`/`relate`/
+ * `move` set `nextRevision(priorMeta)`); `attest`/`recheck` deliberately do
+ * NOT bump, because they never touch the subject.
+ *
+ * A never-mutated issue (no `meta.revision` at all, e.g. every issue created
+ * before the counter existed) reads as `0`, so the pre-counter corpus is
+ * consistent without a backfill.
+ */
+/**
+ * The monotonic revision of an issue's content — `0` for a never-mutated
+ * issue. A non-finite or non-numeric stored value (a malformed `meta` blob)
+ * degrades to `0` rather than propagating `NaN` into a comparison.
+ */
+export declare function readRevision(meta: Record<string, unknown> | undefined): number;
+/** `readRevision(meta) + 1` — the revision a mutating write stamps onto its node. */
+export declare function nextRevision(meta: Record<string, unknown> | undefined): number;

package/write/similarity-scan.d.ts

@@ -0,0 +1,84 @@
+import { StoreSearchBackend } from '@adhd/sox-hybrid-search';
+import { GraphBackend } from '@adhd/sox-graph-store';
+
+/** The search/graph substrate the scan needs — structurally compatible with the create gate's `IDuplicateScanHandle`. */
+export interface ISimilarityScanHandle {
+    readonly graph?: GraphBackend;
+    readonly search?: {
+        readonly backend: StoreSearchBackend;
+        embedQuery?(text: string): Promise<Float32Array>;
+    };
+}
+/** Why the scan could not produce a calibrated comparison — never a generic "unavailable". */
+export type SimilarityScanDegradedReason = 'no-search-backend' | 'no-embed-query' | 'no-vector-scores';
+/** One advisory similarity candidate, with the provenance a reviewer needs to judge it across projects. */
+export interface ISimilarCandidate {
+    uid: string;
+    title: string;
+    /** Cosine similarity in `[0,1]`, straight off the vector channel. */
+    score: number;
+    scope: 'same-project' | 'cross-project';
+    provenance?: {
+        projectUid: string;
+        projectName: string;
+        componentUid?: string;
+        repoUrl?: string;
+    };
+    /** Which independent signals fired, e.g. `['cosine','title-tokens']`. */
+    signals?: string[];
+}
+export interface ISimilarityScanInput {
+    title: string;
+    body: string;
+    scope: 'same-project' | 'multi-project' | 'store-wide';
+    /** Required for `same-project`/`multi-project`: the filing project. */
+    projectUid?: string;
+    sameProjectThreshold: number;
+    crossProjectThreshold: number;
+    margin: number;
+    tokenOverlapMin: number;
+    limit?: number;
+    /**
+     * The filing item's own citation tokens / component path — the "A" side of
+     * the structural signal. Optional: absent means the structural signal can
+     * only ever fire on the candidate's side, which is the correct default for a
+     * caller with no new-item context (the view cluster scan).
+     */
+    citationTokens?: readonly string[];
+    componentPath?: string;
+    /** Ids the scan must EXCLUDE (the declared `dedupeExcludeUid` parent + its `part_of` ancestor chain). */
+    excludeIds?: ReadonlySet<number>;
+}
+/** The richer outcome {@link scanSimilarCandidatesWithMeta} returns; {@link scanSimilarCandidates} is its candidates-only projection. */
+export interface ISimilarityScanOutcome {
+    candidates: ISimilarCandidate[];
+    degraded: boolean;
+    degradedReason?: SimilarityScanDegradedReason;
+}
+/**
+ * Citation-derived structural tokens + owning component path for one issue.
+ *
+ * Exported so BOTH scan callers can supply the A-side of the AC7 structural
+ * signal from a real stored item: the `view:'similar'` cluster block derives
+ * its seed's context with this directly (the seed is already written), while
+ * the create-time gate derives the not-yet-written filing item's context from
+ * its input in `write/create-issue.ts`.
+ */
+export declare function structuralContextFor(graph: GraphBackend, issueId: number): Promise<{
+    citationTokens: string[];
+    componentPath?: string;
+}>;
+/**
+ * The scan, with its degraded-mode metadata. Returns `{candidates:[], degraded:false}`
+ * when the scope is a COMPLETE scan of nothing (the scope resolves to an empty
+ * candidate set, or every candidate was excluded); returns a degraded outcome
+ * when there ARE rows to compare against but the calibrated (vector) channel
+ * could not answer — the distinction the create gate's `abort` fails closed on.
+ */
+export declare function scanSimilarCandidatesWithMeta(handle: ISimilarityScanHandle, input: ISimilarityScanInput): Promise<ISimilarityScanOutcome>;
+/**
+ * The candidates-only projection of {@link scanSimilarCandidatesWithMeta}
+ * (the C9 spec's stated signature): best-first, advisory, never writes, and
+ * `[]` when the embedding substrate is absent.
+ */
+export declare function scanSimilarCandidates(handle: ISimilarityScanHandle, input: ISimilarityScanInput): Promise<ISimilarCandidate[]>;

package/write/spec-revision.d.ts

@@ -0,0 +1,131 @@
+import { IWriteStoreHandle } from './tx.js';
+import { GraphBackend, NodeRecord } from '@adhd/sox-graph-store';
+
+/** The long-form file export an anchor points at: `locator + digest` (Primitive 2) — referenced, never embedded. */
+export interface ISpecAnchor {
+    locator: string;
+    digest: string;
+}
+/**
+ * Immutable revision object metadata (node `kind: 'SPEC'`). The node's
+ * `content` column holds the FRAGMENT appended at this revision (the delta; the
+ * base revision's fragment IS the base document). No revision stores a full
+ * snapshot — the document is the fold over the chain's `content` values and
+ * `revision_token` is the hash of that fold.
+ */
+export interface ISpecRevisionMeta {
+    /** The ticket's logical id (the head resolved at append time) — see the module header. */
+    spec_of: string;
+    /** 1,2,3… monotonic within the spec. */
+    revision_seq: number;
+    /** `'sha256:<hex>'` of the FOLDED document at this revision. */
+    revision_token: string;
+    /** Predecessor revision uid (`null` for the base revision). */
+    prev_revision: string | null;
+    /** The long-form file export (Primitive 2). */
+    anchor: ISpecAnchor;
+    appended_by: string;
+    appended_at: string;
+}
+export interface ISpecAppendInput {
+    /** The ticket's logical id — any uid on its `SUPERSEDES` chain is resolved forward. */
+    uid: string;
+    /** The delta appended at this revision (becomes the node's `content`). */
+    fragment: string;
+    /** The file export for this revision. */
+    anchor?: ISpecAnchor;
+    /** REQUIRED CAS token — the revision uid the caller read (`''` when the ticket had no spec yet). */
+    base_revision: string;
+    by: string;
+}
+export interface ISpecAppendOutcome {
+    /** UNCHANGED — cross-checked by AC1. */
+    uid: string;
+    /** The NEW revision uid. */
+    spec_revision: string;
+    /** `'sha256:<hex>'`. */
+    spec_revision_token: string;
+    revision_seq: number;
+}
+/** Current revision + its token for a work item. */
+export interface ISpecPointer {
+    revision_uid: string;
+    revision_token: string;
+    revision_seq: number;
+}
+/**
+ * The store surface {@link appendSpecRevision} needs. Beyond the ordinary write
+ * handle it requires the store's `GraphBackend`, because revision DISCOVERY must
+ * run the SAME live-kind traversal the read path (`deriveSpecHead`) and the
+ * reconciliation (`spec-revision.reconcile.ts`) use — and that traversal
+ * (`query/resolve.ts`'s `resolveEdgeScopedCandidates`) is a `GraphBackend` read
+ * that must run BEFORE the `BEGIN IMMEDIATE` transaction opens (a `GraphBackend`
+ * call never runs inside it — see `resolveLogicalHeadTx`). `GraphBacklogStore`
+ * and the test `TestIssueStore` both satisfy this shape.
+ */
+export type ISpecAppendStore = IWriteStoreHandle & {
+    readonly graph: GraphBackend;
+};
+/**
+ * Rowids of live items whose DECLARED catalog kind is `SPEC` — an
+ * `issue`-shaped node carrying a live `has_kind` edge to the `kind:'SPEC'`
+ * catalog row. This is the SHIPPED production shape: the reconciled corpus is
+ * `issue` nodes whose DECLARED kind is `SPEC`, and reconciliation stamps them
+ * `spec_of`/`revision_seq` WITHOUT changing the raw `node.kind` column. Any
+ * discovery keyed on the raw column alone is therefore blind to them.
+ *
+ * Uses the SAME live-kind traversal the read path's `filter.kind`
+ * (`query/views/semantic.ts`) and `spec-revision.reconcile.ts` use —
+ * `query/resolve.ts`'s {@link resolveEdgeScopedCandidates} on
+ * `has_kind`→`SPEC` — so read, write, and reconcile can never disagree on what
+ * "a live `kind:'SPEC'` item" is. Returns `undefined` when `SPEC` resolves to
+ * no live catalog row (nothing is declared SPEC).
+ */
+export declare function declaredSpecRowids(graph: GraphBackend): Promise<ReadonlySet<number> | undefined>;
+/**
+ * Every live SPEC document — the UNION of two representations the store has
+ * held, both of which are specs:
+ *
+ *  (a) a node whose RAW `kind` column is `SPEC` — the immutable revision object
+ *      {@link appendSpecRevision} mints (and the shape the unit fixtures
+ *      build); and
+ *  (b) an `issue` node whose DECLARED catalog kind is `SPEC` — the reconciled
+ *      production corpus (see {@link declaredSpecRowids}).
+ *
+ * This is the ONE discovery the read path ({@link deriveSpecHead}), the write
+ * path (`findChainHeadTx` via {@link declaredSpecRowids}), and the
+ * reconciliation all share, so they cannot drift on which items are specs. The
+ * union is load-bearing: a raw-kind-only reader missed shape (b) entirely.
+ */
+export declare function discoverLiveSpecNodes(graph: GraphBackend): Promise<NodeRecord[]>;
+/**
+ * Append a revision. One `BEGIN IMMEDIATE` transaction (ADR-0001 + ADR-0012 —
+ * no temp-file/rename/flock; atomicity is the store's job):
+ *
+ *  1. resolve `uid` → logical head (input may be any `SUPERSEDES`-chain uid — AC9);
+ *  2. read the current revision; if it is not `base_revision` →
+ *     {@link SpecRevisionConflictError} (stale base — no write; AC6);
+ *  3. write a NEW `kind:'SPEC'` node holding the fragment (AC1/AC8);
+ *  4. advance the ticket's `meta.spec_revision` IN PLACE via the CAS helper,
+ *     bumping `meta.revision` — the uid is preserved (AC1);
+ *  5. `writeAudit(action:'spec-appended')`.
+ *
+ * NEVER update or delete a revision node (AC1/AC8).
+ */
+export declare function appendSpecRevision(handle: ISpecAppendStore, input: ISpecAppendInput): Promise<ISpecAppendOutcome>;
+/**
+ * The derived chain head for a ticket — a live `SPEC` node whose
+ * `meta.spec_of` is in the ticket's `SUPERSEDES`-chain uid set with the max
+ * `meta.revision_seq` (read-path analogue of {@link findChainHeadTx}, backed by
+ * the same reconciliation-created functional index). `undefined` when the ticket has
+ * no live revision.
+ */
+export declare function deriveSpecHead(graph: GraphBackend, uid: string): Promise<ISpecPointer | undefined>;
+/** The pointer ON THE RECORD only (`meta.spec_revision`) — never the derived head. Used by the staleness cross-check. */
+export declare function readPointerRecord(graph: GraphBackend, uid: string): Promise<ISpecPointer | undefined>;
+/**
+ * Current revision + its token for a work item (`undefined` if it has no spec).
+ * Prefers the on-record pointer; falls back to the derived chain head so a
+ * ticket whose pointer was not (yet) written — pre-reconciliation data — still reads.
+ */
+export declare function readSpecPointer(graph: GraphBackend, uid: string): Promise<ISpecPointer | undefined>;

package/write/spec-revision.reconcile.d.ts

@@ -0,0 +1,48 @@
+import { IWriteStoreHandle } from './tx.js';
+import { GraphBackend } from '@adhd/sox-graph-store';
+
+/** The store surface the reconciliation needs — satisfied by `GraphBacklogStore` and the test store alike. */
+export type ISpecReconcileStore = IWriteStoreHandle & {
+    readonly graph: GraphBackend;
+};
+export interface ISpecReconcileStamp {
+    revisionUid: string;
+    /** The logical id stamped onto `meta.spec_of` (the ticket's head). */
+    specOf: string;
+    revisionSeq: number;
+    prevRevision: string | null;
+    revisionToken: string;
+    /** `false` when the node already carries exactly this stamp (skip the write). */
+    needsStamp: boolean;
+}
+export interface ISpecReconcileHead {
+    ticketUid: string;
+    revisionUid: string;
+    revisionToken: string;
+    revisionSeq: number;
+    /** `false` when the ticket's pointer already names this head with this token. */
+    needsPointer: boolean;
+}
+export interface ISpecReconcileReport {
+    /** How many live `SPEC` nodes were discovered. */
+    scanned: number;
+    stamps: ISpecReconcileStamp[];
+    heads: ISpecReconcileHead[];
+    /** `SPEC` nodes already stamped (idempotent no-op). */
+    alreadyStamped: number;
+    /** `SPEC` nodes with no live `part_of` parent — left untouched, reported. */
+    orphaned: string[];
+    /** Whether the lookup index exists after this call. */
+    indexCreated: boolean;
+}
+/**
+ * Compute the reconciliation plan WITHOUT writing (the dry-run). Discovery is
+ * `query`-driven; nothing is mutated.
+ */
+export declare function planSpecRevisionReconcile(store: ISpecReconcileStore): Promise<ISpecReconcileReport>;
+/**
+ * Apply the reconciliation. Idempotent: an already-stamped `SPEC` and an
+ * already-pointed ticket are both skipped, so a second run is a no-op. One
+ * `BEGIN IMMEDIATE` transaction (ADR-0001) — never a hard delete.
+ */
+export declare function applySpecRevisionReconcile(store: ISpecReconcileStore): Promise<ISpecReconcileReport>;

package/write/transition.d.ts

@@ -1,5 +1,5 @@
 import { IWriteStoreHandle } from './tx.js';
-import { ICitationInput } from './create-issue.js';
+import { ICitation } from '../citation.js';
 
 export interface ITransitionInput {
     /** The `issue` uid to transition (§6.3, an "Issue verb"). */
@@ -11,7 +11,7 @@ export interface ITransitionInput {
     /** REQUIRED unless `project_policy.transition_requires_note` is `false` (default `true`) — optional in the type; enforced at runtime (`NoteRequiredError`), never at the TS level. */
     note?: string;
     /** REQUIRED (≥1) when `project_policy.citation_required` is `true` AND `toStatus` resolves to a terminal status. Written as `citation` nodes + `has_citation` edges exactly like `create`'s own citations. */
-    citations?: ICitationInput[];
+    citations?: ICitation[];
     /**
      * The item-level disclosure-contract git context — the SAME plain metadata
      * scalar `create`'s own `gitContext` field writes (repo `AGENTS.md`'s "Cite
@@ -22,6 +22,17 @@ export interface ITransitionInput {
      * per-citation `ref` — it rides the issue, never a `citation` node.
      */
     gitContext?: string;
+    /**
+     * A recorded override of a refusing obligation (C5, DESIGN §2 Primitive 3).
+     * Honoured ONLY when the caller is in the refusing obligation's
+     * `override.actors`; a reason is ALWAYS required (never a configurable
+     * boolean) and is recorded on the audit row. A claimed override by a
+     * non-listed actor, or one with a blank reason, throws
+     * `OverrideNotPermittedError`.
+     */
+    override?: {
+        reason: string;
+    };
 }
 export interface ITransitionOutcome {
     uid: string;

package/write/tx.d.ts

@@ -162,7 +162,7 @@ export declare function resolveLiveIssueTx(tx: AdapterTransaction, uid: string):
 /** rowid → node, inside a tx (used to resolve an edge endpoint's kind without a redundant round trip when the caller doesn't already know it). */
 export declare function getNodeByRowidTx(tx: AdapterTransaction, rowid: number): Promise<ITxNodeRow | null>;
 export interface IWriteNodeTxInput {
-    /** The entity-type discriminator — `project`/`component`/`location`/`issue`/`kind`/`edge_kind`/`status`/`priority`/`agent`/`note`/`citation`/`transition`/`audit` (§3). NEVER validated against a closed vocabulary here — the schema is open by design (§0 anti-antipattern 3); the write layer is the only composer of these literals. */
+    /** The entity-type discriminator — `project`/`component`/`location`/`issue`/`kind`/`edge_kind`/`status`/`priority`/`agent`/`note`/`citation`/`transition`/`audit`/`attestation`/`obligation`/`SPEC` (§3; the SPEC revision kind is added by C10, DESIGN §12). NEVER validated against a closed vocabulary here — the schema is open by design (§0 anti-antipattern 3); the write layer is the only composer of these literals. */
     kind: string;
     /** The business name (`issue.title`, a catalog row's name, …). Omit for a node with no name (none currently exist in §3's table, but the column is nullable). */
     name?: string;
@@ -328,6 +328,26 @@ export interface IInvalidateEdgeTxInput {
  * instead of the bare adapter.
  */
 export declare function invalidateEdgeTx(tx: AdapterTransaction, input: IInvalidateEdgeTxInput): Promise<void>;
+/**
+ * Update a LIVE node's `meta` IN PLACE inside `tx`, CAS-guarded on the node's
+ * own `meta.revision` counter (SR-2 monotonic revision + SR-6 per-node CAS,
+ * per DESIGN §2 Primitive 1's "node's monotonic `revision`, bumped on every
+ * mutating write"). Preserves `uid` — this is the ONLY write path that mutates
+ * a node without superseding it, and it exists solely for the C10 spec pointer
+ * (`meta.spec_revision`) and the SR-2 counter it bumps. No other verb may adopt
+ * it without a new decision.
+ *
+ * `patch`'s keys are shallow-merged over the node's existing meta; the merged
+ * blob's `revision` is set to `expectedRevision + 1`. Returns the new revision
+ * number on success, or `null` when the node is missing OR the stored revision
+ * no longer equals `expectedRevision` (a concurrent writer won the CAS — the
+ * caller must surface a stale-base error, and because this runs inside the
+ * caller's own `BEGIN IMMEDIATE` transaction, a thrown error rolls the whole
+ * transaction back). A node with no `meta.revision` at all reads as revision
+ * `0` (matching `revision.ts`'s `readRevision`), so a pre-counter row is
+ * CAS-addressable without a backfill.
+ */
+export declare function updateNodeMetaTx(tx: AdapterTransaction, uid: string, patch: Record<string, unknown>, expectedRevision: number): Promise<number | null>;
 /**
  * The one transaction wrapper every write verb calls — `store.adapter.transaction(fn,
  * {mode: resolveTransactionMode()})`, which is `'immediate'` (§4c: `BEGIN

package/write/update.d.ts

@@ -1,4 +1,5 @@
 import { IWriteStoreHandle } from './tx.js';
+import { ICitation } from '../citation.js';
 
 export interface IUpdateIssueInput {
     /** The `issue` uid to update (§6.3, an "Issue verb"). */
@@ -17,6 +18,27 @@ export interface IUpdateIssueInput {
     assignee?: string;
     /** catalog agent name/uid; → `touch` + `authored_by` edge rewrite. An unresolved NAME mints; a uid-shaped ref that does not resolve throws `CatalogNotFoundError('agent', ref)`. */
     author?: string;
+    /**
+     * The DESIRED set of citations this issue should carry after this call — a
+     * DIFF-EMITTER, never a body rewrite (the architecture verdict): the live
+     * citation set is read inside the SAME `immediate` transaction, citations
+     * present live but absent from `citations` are removed (bi-temporally), and
+     * citations in `citations` but not live are added. Identity for the diff is
+     * `(file, lines, revision)` (§ `citationKey`), never `sha`/`context`.
+     *
+     * Routing a citation change through `body`/`supersede` is FORBIDDEN: that
+     * would mint a new issue uid and violate §1's "uid is the only identity".
+     * When `body` IS also given, the supersede mints the new node first, its
+     * live citations are carried forward, and THIS diff is applied against the
+     * carried-forward set on the new node — still inside the one transaction.
+     *
+     * Each citation's `sha` is computed (and policy-gated, exactly as `create`/
+     * `transition` do) before the transaction opens, so the write lock is never
+     * held across a filesystem/git read. `citations: []` clears every live
+     * citation. Omitted entirely ⇒ citations are untouched (and carried forward
+     * verbatim on a body edit).
+     */
+    citations?: ICitation[];
     /**
      * §4b/§6.2 — waits for the fire-and-forget on-write embedding round-trip
      * before `update` returns, when `true` and `handle.embedding` is
@@ -30,7 +52,7 @@ export interface IUpdateIssueInput {
      */
     awaitEmbed?: boolean;
 }
-export type IUpdateIssueChangedField = 'title' | 'body' | 'kind' | 'priority' | 'assignee' | 'author';
+export type IUpdateIssueChangedField = 'title' | 'body' | 'kind' | 'priority' | 'assignee' | 'author' | 'citations';
 export interface IUpdateIssueOutcome {
     /**
      * The resulting CURRENT issue's uid — the SAME `input.uid` when `body` was