@adhd/backlog 1.0.5 → 1.0.6

package/ir-artifact.d.ts

@@ -61,9 +61,13 @@ export declare function bakedIrArtifactPath(distDir: string): string;
 export declare function readBakedIrArtifact(distDir: string): Operation[] | undefined;
 /**
  * Writes the baked IR artifact to `outFile`, recording the provenance the
- * reader re-validates against: the source `.d.ts` path (audit), its sha256 and
- * byte length, plus a sha256 per EVERY `*.d.ts` under the artifact's `dist/`
- * (`artifactSource.deps`). Uses the plugin's shared `atomicWriteJson`, so the
+ * reader re-validates against: the source `.d.ts`'s DIST-RELATIVE path
+ * (`api.d.ts`; audit, machine-independent), its sha256 and byte length, plus a
+ * sha256 per EVERY `*.d.ts` under the artifact's `dist/`
+ * (`artifactSource.deps`). Emits NO timestamp and NO absolute path, so two
+ * builds of identical source produce byte-identical artifacts — reproducible
+ * output that `version`'s no-bump fast path depends on (`normalizedHash` over
+ * `dist/`). Uses the plugin's shared `atomicWriteJson`, so the
  * artifact is published atomically and durably exactly like a runtime-cache
  * entry — a build killed mid-write can never leave a half-written artifact
  * behind.

package/lifecycle.d.ts

@@ -0,0 +1,49 @@
+/**
+ * lifecycle.ts — the `starting / live / ready` trichotomy (D-A, Segment B).
+ *
+ * Exactly the three states DESIGN §2 D1 names. Failure/stop are transitions,
+ * never states:
+ *
+ *   - `starting`: env resolved, store opening, the mount being composed (the
+ *     ~14 s cold-start window), transports not yet accepting.
+ *   - `live`: the transport accepts connections (stdio connected / socket bound).
+ *   - `ready`: the serving-path probe (`readiness.ts`) has passed.
+ *
+ * A LIVENESS failure means RESTART; a READINESS failure is REPORT ONLY, state
+ * unchanged, NO restart. {@link IServiceLifecycle.fail} records a failure
+ * WITHOUT changing the state and returns the action the supervisor must take.
+ */
+export type IServiceState = 'starting' | 'live' | 'ready';
+export interface IServiceFailure {
+    kind: 'liveness' | 'readiness';
+    code: string;
+    message: string;
+    subject?: string;
+}
+export interface IServiceReport {
+    state: IServiceState;
+    /** ISO timestamp the current state was entered. */
+    since: string;
+    /** Present on a failure. A liveness failure means RESTART; a readiness
+     *  failure means REPORT ONLY, no restart. */
+    failure?: IServiceFailure;
+    lastTickAt?: string;
+    degraded: boolean;
+}
+export interface IServiceLifecycle {
+    state(): IServiceState;
+    report(): IServiceReport;
+    /** starting → live (transport accepting). */
+    markLive(): void;
+    /** live → ready (the serving-path probe passed). Idempotent. */
+    markReady(): void;
+    /** Record a failure WITHOUT changing the state; returns the supervisor action. */
+    fail(f: IServiceFailure): {
+        action: 'restart' | 'report';
+    };
+    whenReady(): Promise<void>;
+}
+export interface ILifecycleDeps {
+    now?: () => number;
+}
+export declare function createLifecycle(deps?: ILifecycleDeps): IServiceLifecycle;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhd/backlog",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "bin": {
     "adhd-backlog": "index.js"
   },
@@ -10,17 +10,17 @@
     "@adhd/apigen-engine-naming": "^0.2.5",
     "@adhd/apigen-plugin-api-fastify": "^0.2.6",
     "@adhd/apigen-plugin-batch": "^0.2.5",
-    "@adhd/apigen-plugin-cli-output": "^0.2.6",
+    "@adhd/apigen-plugin-cli-output": "^0.2.7",
     "@adhd/apigen-plugin-ir-cache": "^0.1.3",
     "@adhd/apigen-plugin-mcp": "^0.3.1",
     "@adhd/apigen-plugin-openapi": "^0.2.5",
     "@adhd/environment": "^0.1.8",
     "@adhd/environment-base-spec": "^0.1.3",
     "@adhd/environment-builder": "^0.1.7",
-    "@adhd/sox-graph-store": "^0.11.1",
-    "@adhd/sox-hybrid-search": "^0.5.0",
+    "@adhd/sox-graph-store": "^0.12.0",
+    "@adhd/sox-hybrid-search": "^0.6.0",
     "@adhd/sox-semantic": "^0.1.8",
-    "@adhd/sox-store-adapter": "^0.10.0",
+    "@adhd/sox-store-adapter": "^0.11.0",
     "@adhd/sox-telemetry": "^0.3.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "ajv": "^8.20.0",

package/query/canonical.d.ts

@@ -0,0 +1,16 @@
+import { AdapterTransaction } from '@adhd/sox-store-adapter';
+import { GraphBackend } from '@adhd/sox-graph-store';
+
+/**
+ * Resolve `uid` to the canonical head of its reserved `duplicate_of` chain.
+ * Read-only; returns the input uid when it resolves to nothing or is unlinked.
+ * Never throws on a linked uid.
+ */
+export declare function resolveCanonicalIssue(graph: GraphBackend, uid: string): Promise<string>;
+/**
+ * Tx-scoped {@link resolveCanonicalIssue} for the reserved same-judgement
+ * write path: the same chain walk (duplicate_of → one-hop redirect →
+ * `SUPERSEDES` head), hand-composed against the transaction handle rather than
+ * a bare `GraphBackend` (ADR-0002 — one concept, one algorithm).
+ */
+export declare function resolveIssueCanonicalTx(tx: AdapterTransaction, uid: string): Promise<string>;

package/query/card.d.ts

@@ -1,4 +1,5 @@
-import { IIssueAuditEntry, IIssueCard, IIssueField, IIssueRef } from './types.js';
+import { IVerdictRung } from './verdict.js';
+import { IIssueAuditEntry, IIssueCard, IIssueField, IIssueRef, IObligationView, ISimilarLinks, IScoreKind } from './types.js';
 import { EdgeRecord, GraphBackend, NodeRecord } from '@adhd/sox-graph-store';
 
 /** SPEC.md §6.5's `assertKnownFields` — unknown name → `BacklogValidationError` naming it, never a silent drop. */
@@ -14,18 +15,129 @@ export declare function resolveAuditTrail(graph: GraphBackend, issueId: number,
  * actually blocking it right now," never the full historical blocker set.
  */
 export declare function resolveBlockers(graph: GraphBackend, issueId: number): Promise<IIssueRef[]>;
-/** `related` — both directions of `relates_to` (an `n:m` symmetric-in-practice rel, §3), deduplicated. */
+/**
+ * `related` — every live relation type that touches this issue, deduplicated
+ * by node and tagged with the relation that produced it (C2 — structural
+ * legibility; SPEC.md §5/§6.5, DESIGN §5 AC2):
+ *
+ * - `relates_to` (both directions — an `n:m` symmetric-in-practice rel, §3),
+ *   tagged `relates_to`;
+ * - `part_of` (both directions: the parent when this item is the child, the
+ *   children when it is the parent), tagged `part_of`;
+ * - `blocks` outbound (this item blocks the target), tagged `blocks`; and
+ *   `blocks` incoming (the source blocks this item), tagged `blocked_by`.
+ *
+ * `blockers` (the non-terminal INCOMING subset) is deliberately NOT removed —
+ * it stays as the "what's actually blocking me right now" view; `related` is
+ * the structural superset. Widening this result is additive ROWS, never a
+ * signature change: a consumer reading `uid`/`title`/`status` is unaffected.
+ * Dedup is by node id, first-seen wins, in the deterministic order above.
+ */
 export declare function resolveRelated(graph: GraphBackend, issueId: number, outgoing?: EdgeRecord[]): Promise<IIssueRef[]>;
+/**
+ * C9 — the reviewed `similar_to` links touching one issue, BOTH directions
+ * (`n:m`). Outgoing edges (`similar_to` from this issue) become `similarTo`;
+ * incoming edges (into it) become `similarFrom`. Each neighbour is projected to
+ * the compact `ISimilarRef` shape (uid/title/status + owning project/repo).
+ *
+ * ADVISORY relation only — the reserved `duplicate_of` same-judgement relation
+ * is deliberately never read here.
+ */
+export declare function resolveSimilar(graph: GraphBackend, issueId: number, outgoing?: EdgeRecord[]): Promise<ISimilarLinks>;
+/**
+ * Outbound `blocks` (C2) — the issues THIS one blocks, live targets only.
+ * Mirrors {@link resolveBlockers}'s shape but for the other direction: that
+ * function returns the non-terminal INCOMING blockers ("what stops me"),
+ * this one returns everything this item unblocks ("what I am stopping").
+ */
+export declare function resolveBlocksOut(graph: GraphBackend, issueId: number, outgoing?: EdgeRecord[]): Promise<IIssueRef[]>;
+/**
+ * Transitive outbound dependent count (C2, AC3): how many nodes reach
+ * `issueId` via `blocks` (inclusive of direct dependents — the nodes this one
+ * blocks, directly or through a chain). A cycle-safe BFS over the outgoing
+ * `blocks` edges: a `visited` set counts each node once and terminates a cycle
+ * (the reachability set is finite even when the edge set is cyclic).
+ *
+ * `scope`, when given, restricts the walk to node ids in the set — a list page
+ * passes its own candidate id set so an N-item page costs N bounded walks, not
+ * N whole-graph walks. On a single `get`, `scope` is omitted and the walk is
+ * unbounded but still cycle-safe.
+ */
+export declare function resolveDependents(graph: GraphBackend, issueId: number, scope?: ReadonlySet<number>): Promise<number>;
+/**
+ * The single `part_of` parent of this item, or `null` (C2, AC3). `part_of` is
+ * declared `n:1` (one parent per item, DATA_MODEL.md §3 / `EDGE_KIND_TABLE`),
+ * so at most one live outgoing `part_of` edge can exist; the multiplicity gate
+ * (`checkMultiplicityTx`) enforces that at write time.
+ */
+export declare function resolvePartOf(graph: GraphBackend, issueId: number, outgoing?: EdgeRecord[]): Promise<IIssueRef | null>;
+/**
+ * `obligations` (C4) — the declared, typed requirements on this issue, read
+ * from its live `has_obligation` targets. PURE PROJECTION: each node's stored
+ * `metadata` maps straight onto an {@link IObligationView}; the predicate is
+ * NEVER evaluated here (evaluation belongs to the C5 gate at transition time
+ * and the C6 verdict on read). One batched `getNodesByIds`; the returned order
+ * follows the edge order, and an edge whose target no longer resolves (a
+ * concurrently-invalidated row) is simply skipped rather than yielding a
+ * partial view.
+ */
+export declare function resolveObligations(graph: GraphBackend, issueId: number, outgoing?: EdgeRecord[]): Promise<IObligationView[]>;
 export interface IAssembleIssueCardOptions {
     /** Score from a `searchRanked`/`searchNodes` response — populates `_score` when requested (§5a). */
     score?: number;
+    /** Provenance of `score` — populates `_score_kind` alongside `_score` (DESIGN §2 Invariant 5). */
+    scoreKind?: IScoreKind;
+    /**
+     * Bounds the sub-collection pseudo fields (`auditTrail`/`citations`/
+     * `related`/`blockers`) — `lastN` takes the LAST N rows, `after` is an
+     * opaque cursor naming a uid to resume strictly after. Applied HERE (at the
+     * card-assembly call site), never inside `resolveAuditTrail` itself: the
+     * `openCurve` view (`views/stats.ts`) calls an independent batched audit
+     * reader that needs the FULL trail and must not be bounded.
+     */
+    bounds?: {
+        lastN?: number;
+        after?: string;
+    };
     /** Pre-fetched outgoing edges (`getEdges({src: issue.id})`) — pass when the caller already has them (e.g. a batch `query` page) to avoid a redundant round trip. */
     outgoingEdges?: EdgeRecord[];
+    /**
+     * The candidate id set a `dependents` walk is bounded to (C2). A list page
+     * passes its own page id set so an N-item page costs N bounded walks; a
+     * single `get` omits it, leaving the walk unbounded (but cycle-safe). Only
+     * consulted when `fields` requests `dependents`.
+     */
+    scope?: ReadonlySet<number>;
+    /**
+     * C6 — the highest verdict ladder rung this card may derive. Default 2 (the
+     * list bound); a single-item `get` raises it to 3+ via `deriveThrough`.
+     * Only consulted when `fields` requests `verdict`.
+     */
+    verdictRung?: IVerdictRung;
+    /** C6 test instrumentation — threaded to `deriveVerdict`'s `onRung`. */
+    onVerdictRung?: (rung: number) => void;
+    /**
+     * C10 — a token the caller holds; when supplied AND the `spec` field was
+     * requested, `card.spec.freshness` reports whether that token is still
+     * current for this item's spec revision.
+     */
+    specToken?: string;
 }
 /**
  * Project `issue` onto the requested `fields` (default: the five-field terse
  * card, SPEC.md §6.5). `uid` is always populated regardless of `fields`.
  */
 export declare function assembleIssueCard(graph: GraphBackend, issue: NodeRecord, fields: readonly IIssueField[], opts?: IAssembleIssueCardOptions): Promise<IIssueCard>;
-/** Batch-assemble cards for a page of issue nodes, sharing one `getNodesByIds`-batched catalog/placement resolution pass where possible. Falls back to per-issue assembly (still batches internally) — a cross-issue batch would require a different, `getEdges`-list API this file's dependency (`GraphBackend`) does not expose. */
-export declare function assembleIssueCards(graph: GraphBackend, issues: NodeRecord[], fields: readonly IIssueField[], scoreByUid?: ReadonlyMap<string, number>): Promise<IIssueCard[]>;
+/** Batch-assemble cards for a page of issue nodes, sharing one `getNodesByIds`-batched catalog/placement resolution pass where possible. Falls back to per-issue assembly (still batches internally) — a cross-issue batch would require a different, `getEdges`-list API this file's dependency (`GraphBackend`) does not expose.
+ *
+ * The page's own node ids are handed to each card as the `dependents` walk's
+ * `scope` (C2): a list read bounds each transitive-dependent count to the page
+ * it is rendering, so an N-item page costs N bounded walks rather than N walks
+ * over the whole `blocks` graph. A single `get` (which calls
+ * {@link assembleIssueCard} directly, not this function) leaves the walk
+ * unbounded but cycle-safe. `scope` is inert unless `fields` requests
+ * `dependents`. */
+export declare function assembleIssueCards(graph: GraphBackend, issues: NodeRecord[], fields: readonly IIssueField[], scoreByUid?: ReadonlyMap<string, number>, scoreKindByUid?: ReadonlyMap<string, IScoreKind>, verdictOpts?: {
+    rung?: IVerdictRung;
+    onRung?: (rung: number) => void;
+}): Promise<IIssueCard[]>;

package/query/get.d.ts

@@ -5,7 +5,14 @@ import { GraphBackend } from '@adhd/sox-graph-store';
  * Fetch one issue by `uid`, projected to the requested `fields` (default:
  * the same five-field card `query` defaults to, SPEC.md §6.3.1/§6.5/AC-13).
  *
+ * `lastN`/`after` bound the sub-collection pseudo fields (`auditTrail`/
+ * `citations`/`related`/`blockers`) — `lastN` keeps the LAST N rows in each
+ * resolver's own order (the audit trail's oldest-first order is sliced to its
+ * newest tail), `after` resumes strictly after a uid. Both are opt-in; absent
+ * means the unbounded behavior every existing caller already had.
+ *
  * Errors: `IssueNotFoundError(uid)` (no live node carries `uid`),
- * `BacklogValidationError('fields', ...)` (an unknown field name).
+ * `BacklogValidationError('fields'|'lastN', ...)` (an unknown field name, or
+ * a non-positive/non-integer `lastN`).
  */
 export declare function getIssue(graph: GraphBackend, input: IIssueGetByUidInput): Promise<IIssueCard>;

package/query/index.d.ts

@@ -63,5 +63,6 @@ export * from './get.js';
 export * from './query.js';
 export * from './views/registry.js';
 export * from './views/stats.js';
+export * from './views/report.js';
 export * from './views/semantic.js';
 export * from './markdown.js';

package/query/query.d.ts

@@ -62,6 +62,13 @@ export interface IQueryStoreHandle {
      * same way, so neither ordinary path is gated.)
      */
     readonly assertCatalogInvariants?: () => Promise<void>;
+    /**
+     * C6 test instrumentation — invoked with each verdict ladder rung the list
+     * path actually evaluates. Never consulted by production callers; wired only
+     * so the N-item list bound (AC6) can be MEASURED, not asserted. The list path
+     * must never evaluate beyond rungs 1–2.
+     */
+    readonly onVerdictRung?: (rung: number) => void;
 }
 /**
  * Whether a `query` verb's own input touches the semantic channel at all —
@@ -109,19 +116,19 @@ export declare function resolveTextInput(handle: IQueryStoreHandle, input: IIssu
 export interface IQueryIssuesOutcome {
     result: IIssueQueryResult;
     /**
-     * Present only for `view:'list'` — the only view whose result is a
-     * filtered/paginated row set with an honestly countable pre-limit total
-     * (`envelope.ts`'s {@link IQueryEnvelopeMeta}). `view:'ready'` computes
-     * readiness in-memory and stops enumerating once `limit` candidates are
-     * found (`queryReady`'s own doc comment: removing that early exit to count
-     * a true pre-limit total would reintroduce the O(candidates) cost its
-     * grouped-relation-fetch design exists to avoid), `view:'stale'` applies no
-     * limit at all so every row it returns already IS the total, and
-     * `view:'similar'`/`'graph'`/`'order'`/`'overlap'` are a ranking, a graph
-     * projection, a topological order, and an axis grouping respectively — none
-     * of them a filtered row set with a "how many matched" count. Adding a
-     * `meta` to any of those would mean inventing a number this module cannot
-     * stand behind.
+     * Present for the four ITEM-LIST views (`list`/`ready`/`stale`/`similar`) —
+     * the only views whose result is a filtered row set with an honestly
+     * reportable completeness flag (`envelope.ts`'s {@link IQueryEnvelopeMeta}).
+     *
+     * `list` reports an exact pre-limit `total`; the other three derive `has_more`
+     * by fetching one row beyond the page and, when more exist, report `total`
+     * with `total_relation:'gte'` — an honest lower bound, never a fabricated
+     * exact number (DESIGN §2 Invariant 5, §7 condition 2). `graph`/`order`/
+     * `overlap` deliberately carry NO `meta`: they are a graph, a topological
+     * order, and an axis grouping — none a filtered row set with a "how many
+     * matched" count. Adding a `meta` to any of those would mean inventing a
+     * number this module cannot stand behind (see `meta-wire.e2e.ts`, whose
+     * `view:'graph'`-has-no-`meta` assertion is load-bearing).
      */
     meta?: IQueryEnvelopeMeta;
 }

package/query/redirect.d.ts

@@ -0,0 +1,30 @@
+import { GraphBackend, NodeRecord } from '@adhd/sox-graph-store';
+
+/**
+ * The stored shape of a soft-retired row's redirect. `toUid` is the canonical
+ * live node the retired row points at; `reason` is the free-text explanation
+ * recorded on the retired node's audit trail (and, when set, its
+ * `meta.retiredReason`). Kept as a named contract so the merge writer and any
+ * future reader share one shape rather than re-deriving it from `meta`.
+ */
+export interface IRedirect {
+    /** The canonical uid this retired row points at. */
+    toUid: string;
+    /** Why the row was retired — recorded on the retired node's audit + meta. */
+    reason: string;
+}
+/**
+ * If `record` is a soft-retired row carrying `meta.redirectTo`, return the
+ * canonical live node it points at (one hop only; a redirect→redirect chain
+ * longer than one hop throws). Otherwise `null`.
+ *
+ * `record` may itself be invalidated (`t_invalid` set) — that is the normal
+ * case, since retiring a row is what gives it a redirect. The TARGET, by
+ * contrast, must be a live node: a redirect into a tombstone is a broken
+ * invariant, not an unresolved name, so it throws rather than degrading to
+ * `null` (which a caller would misread as "this token leads nowhere").
+ *
+ * @throws InvalidArgumentError when the redirect target is missing/retired, or
+ *   when the target is itself a redirect (a chain longer than one hop).
+ */
+export declare function followRedirect(graph: GraphBackend, record: NodeRecord): Promise<NodeRecord | null>;

package/query/resolve.d.ts

@@ -44,6 +44,54 @@ export declare function tryResolveUidPrefix(graph: GraphBackend, ref: string, op
  * {@link StaleSupersedeError} pointing at the chain head.
  */
 export declare function resolveIssueByUid(graph: GraphBackend, uid: string): Promise<NodeRecord>;
+/**
+ * Resolve a token to the LOGICAL node it names TODAY: follow a one-hop merge
+ * redirect (C1's soft-retired project/component rows), then walk the
+ * `SUPERSEDES` chain to its head. NEVER throws on a superseded uid — that is
+ * the whole point of the split from {@link resolveIssueByUid}, which throws
+ * `StaleSupersedeError` because its callers (`get`, `card` blockers, `stats`)
+ * want to be told a reference is stale, not silently forwarded.
+ *
+ * This is the non-throwing resolver C3's attestation `subject.id` uses: an
+ * attestation written against a uid that a later body-edit superseded must
+ * still name the SAME logical item, and a caller holding a stale citation
+ * wants today's issue, not the next-oldest corpse.
+ *
+ * Delegates the chain walk to {@link currentUidOf} rather than re-implementing
+ * it (ADR-0002 — one concept, one implementation). Returns the head
+ * `NodeRecord`; when the chain dead-ends with no live successor it returns the
+ * node it started from, which is the most useful answer available.
+ */
+export declare function resolveLogicalIssue(graph: GraphBackend, ref: string): Promise<NodeRecord>;
+/**
+ * Normalise any issue uid (possibly superseded) to its SUPERSEDES-chain HEAD
+ * uid. Returns the input unchanged for an already-live uid.
+ *
+ * ONE concept, ONE implementation: this delegates to {@link resolveLogicalIssue}
+ * (which returns the head `NodeRecord`) — it is NOT a second chain walk
+ * (ADR-0002). Used by C3's attestation read path so an attestation filed
+ * against a uid a later body edit superseded still names the SAME logical item.
+ */
+export declare function resolveLogicalIssueId(graph: GraphBackend, uid: string): Promise<string>;
+/**
+ * Walk the `SUPERSEDES` chain forward from a superseded node to the uid the
+ * issue lives under NOW.
+ *
+ * `update`'s body path mints a new node and writes `SUPERSEDES` new→old, so
+ * the successor of a node is the `src` of the edge whose `dst` is that node —
+ * the reverse of the direction the edge reads. Repeated edits build a chain,
+ * and a uid cited before several edits is several hops back, so this follows
+ * the chain to its head rather than stopping at the first hop: a caller
+ * holding a stale citation wants today's issue, not the next-oldest corpse.
+ *
+ * Defensive, because this runs on an error path that must not itself throw:
+ * a cycle (impossible by construction, since each edit mints a fresh node,
+ * but not enforced by a constraint) is bounded by `seen`; a missing or
+ * invalidated successor ends the walk and yields the last good uid, and a
+ * chain that dead-ends immediately yields `undefined` — which
+ * {@link StaleSupersedeError} documents as "not known here".
+ */
+export declare function currentUidOf(graph: GraphBackend, superseded: NodeRecord): Promise<string | undefined>;
 /**
  * Resolve `ref` (uid or name, disambiguated by shape — SPEC.md §6.1) against
  * `expectedKind`, on the READ path: an unresolved NAME is never an error here

package/query/similar-clusters.d.ts

@@ -0,0 +1,8 @@
+import { IIssueQueryInput, ISimilarViewClusterBlock } from './types.js';
+import { ISimilarityScanHandle } from '../write/similarity-scan.js';
+
+/**
+ * Build the additive `view:'similar'` cluster block, or `undefined` when the
+ * query is not scope-filtered. Never writes.
+ */
+export declare function buildSimilarClusterBlock(handle: ISimilarityScanHandle, input: IIssueQueryInput): Promise<ISimilarViewClusterBlock | undefined>;

package/query/similarity-signals.d.ts

@@ -0,0 +1,47 @@
+/**
+ * similarity-signals.ts — the PURE multi-signal comparator the C9
+ * cross-project similarity guard is built on (C9 spec, `similarity-signals.ts`
+ * row). No store access, no I/O: two independent signals over plain values, so
+ * the guard is unit-testable in isolation and the scan (`write/similarity-scan.ts`)
+ * stays a thin composition of this plus the raw vector channel.
+ *
+ * Why a SECOND signal at all (AC7): cosine alone is never sufficient
+ * cross-project. Two boilerplate filings from unrelated repos can sit at high
+ * cosine while sharing no real intent — the title-token Jaccard and the
+ * structural (citation / component-path) overlap are the independent evidence
+ * that keeps such a pair advisory-invisible.
+ */
+/** The plain, store-free view of one item a signal comparison needs. */
+export interface ISignalItem {
+    title: string;
+    body?: string;
+    /**
+     * Tokens drawn from the item's citations — `file`/`symbol`/`errorText`/
+     * `blastRadius`. Callers pass whatever citation strings they have; this
+     * module tokenizes them.
+     */
+    citationTokens?: readonly string[];
+    /** The owning component's `meta.path` (repo-relative), when known. */
+    componentPath?: string;
+}
+/**
+ * Lowercase, split on every non-alphanumeric run, and drop stop words — the
+ * token stream {@link titleTokenOverlap} and {@link sharedStructuralSignal}
+ * both compare over, so the two signals can never disagree on what a "token"
+ * is.
+ */
+export declare function normalizeTokens(text: string): string[];
+/**
+ * Jaccard overlap of two title token SETS: `|A∩B| / |A∪B|`, in `[0,1]`.
+ * Two empty (or all-stop-word) titles have no overlap to speak of and score
+ * `0`, never `1` — "nothing in common" must not read as "identical".
+ */
+export declare function titleTokenOverlap(a: string, b: string): number;
+/**
+ * The second independent signal for a cross-project candidate: does the pair
+ * share a citation token (`file`/`symbol`/`errorText`/`blastRadius`) OR do
+ * their component paths nest (one is a path-prefix of the other — e.g.
+ * `packages/agent` and `packages/agent/agent-engine-compiler`)? Either is
+ * structural evidence of a real shared locus, independent of the cosine.
+ */
+export declare function sharedStructuralSignal(a: ISignalItem, b: ISignalItem): boolean;

package/query/spec-staleness.d.ts

@@ -0,0 +1,21 @@
+import { GraphBackend } from '@adhd/sox-graph-store';
+
+export type SpecFreshness = 'fresh' | 'stale' | 'unknown';
+export interface ISpecCheckInput {
+    uid: string;
+    token?: string;
+}
+export interface ISpecCheckOutcome {
+    current_revision: string;
+    /** `'sha256:<hex>'` — always this encoding. */
+    current_token: string;
+    state: SpecFreshness;
+    method: 'token' | 'content_hash' | 'ancestry' | 'none';
+    reason?: string;
+}
+/**
+ * Compare the caller's `token` against the ticket's current revision token and
+ * report the freshness ladder's verdict. See the module header for the rules.
+ * `uid` is the ticket (any uid on its `SUPERSEDES` chain is resolved forward).
+ */
+export declare function checkSpecStaleness(graph: GraphBackend, input: ISpecCheckInput): Promise<ISpecCheckOutcome>;