@descryy/core 0.1.0

package/dist/recording/schema.js

@@ -0,0 +1,104 @@
+/**
+ * The call-recording schema — `ai-tool-contract.md` §6, rule 5: "every call is
+ * recorded" (§41.15), the basis of replay (`ai-layer-plan.md` §9 layer 6,
+ * §12's reproducibility requirement).
+ *
+ * A separate store from `../store` on purpose, not an extra table bolted onto
+ * the graph schema:
+ *
+ * 1. **The two version numbers move for unrelated reasons.** `IR_SCHEMA_VERSION`
+ *    bumps when the graph's own shape changes; this schema bumps when the
+ *    recording format changes. Coupling them would force a recording-format
+ *    change to carry a graph rebuild, and vice versa.
+ * 2. **Nothing here is "derived."** DEC-017's derived/earned split exists
+ *    because derived rows can be regenerated from source. A recorded call is a
+ *    fact about one already-finished execution — there is no source to
+ *    regenerate it from, ever. Every table below is earned in DEC-017's sense,
+ *    and the version check refuses on mismatch rather than offering a
+ *    `dropDerived()`-equivalent: there is nothing safe to drop.
+ * 3. Same reasoning DEC-018 gives for the graph store applies here unchanged:
+ *    `node:sqlite` behind the existing `SqlDriver` interface, not a second
+ *    persistence technology. This module imports the driver, it does not
+ *    reinvent one.
+ *
+ * ## Unredacted material — read before wiring this to a live tool boundary
+ *
+ * Contract §6: redaction happens *at the tool boundary, before the model
+ * call*. **This store holds whatever `arguments` and `result` it is given,
+ * verbatim, unless a redactor was supplied.** `recordCall`'s `redact` option
+ * (`writer.ts`) is the seam; `redact.ts`'s `createRecordingRedactor` is a
+ * real, tested implementation of it, given the caller's own configured
+ * secret values. No live call site in this repo constructs and passes one
+ * today — recording is not yet wired into the MCP server's or
+ * `descry-runtime`'s actual tool dispatch — so every row written by this
+ * repo's current callers is still unredacted. Treat a database file under
+ * this schema as containing the same sensitive material the tool calls
+ * themselves carried, until whoever wires the live call path passes a
+ * redactor built from real secret values.
+ */
+export const RECORDING_SCHEMA_VERSION = 1;
+export const SCHEMA_SQL = `
+-- ---------------------------------------------------------------------------
+-- recording_meta — same role as the graph store's graph_meta: identity of the
+-- store itself, checked before anything else is trusted.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS recording_meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+) STRICT;
+
+-- ---------------------------------------------------------------------------
+-- recorded_runs — one row per AI-layer run. The graph stamp (commit_sha,
+-- built_at, ir_schema_version) is captured ONCE here, per §12: replay needs to
+-- know what graph the run saw, not re-derive it from the first call.
+--
+-- prompt_version and model_id are present and nullable, never a column that
+-- does not exist: §3's rule that "a missing field and a null field read
+-- identically to a careless caller, and only one of them is honest" applies
+-- to a database column exactly as it applies to the wire envelope. No model
+-- calls exist yet in this repo, so both are null on every row written today —
+-- that is a true statement about the current build, not a gap in the schema.
+--
+-- next_seq is the ordering counter writer.ts increments atomically with
+-- every insert into recorded_calls, so "what order did these calls happen in"
+-- is answerable without trusting wall-clock timestamps, which two calls in the
+-- same millisecond cannot distinguish.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS recorded_runs (
+  id                TEXT    PRIMARY KEY,
+  started_at        INTEGER NOT NULL,
+  commit_sha        TEXT,
+  built_at          TEXT,
+  ir_schema_version INTEGER,
+  prompt_version    TEXT,
+  model_id          TEXT,
+  next_seq          INTEGER NOT NULL DEFAULT 0
+) STRICT;
+
+-- ---------------------------------------------------------------------------
+-- recorded_calls — one row per tool call. (run_id, seq) is the primary key
+-- rather than an autoincrement id: ordering within a run is the whole point of
+-- seq, and a composite key makes "give me run X in order" a primary-key range
+-- scan instead of a sort.
+--
+-- arguments and result are stored as canonicalJson of exactly what the
+-- caller passed — the full envelope, not a summary. Dropping a field here
+-- (say, disclosures, or the resolution level buried in graph) would make
+-- this store unable to reproduce whatever the finding drew from that field,
+-- which is the one failure mode replay exists to rule out.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS recorded_calls (
+  run_id       TEXT    NOT NULL REFERENCES recorded_runs(id) ON DELETE CASCADE,
+  seq          INTEGER NOT NULL,
+  tool         TEXT    NOT NULL,
+  tool_version TEXT    NOT NULL,
+  class        TEXT    NOT NULL,
+  arguments    TEXT    NOT NULL,
+  result       TEXT    NOT NULL,
+  duration_ms  INTEGER NOT NULL,
+  cost         REAL,
+  recorded_at  INTEGER NOT NULL,
+  PRIMARY KEY (run_id, seq)
+) STRICT;
+`;
+//# sourceMappingURL=schema.js.map

package/dist/recording/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/recording/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAE1C,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+DzB,CAAC"}

package/dist/recording/writer.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Recording a run and its calls — `ai-tool-contract.md` §6, rule 5 (§41.15).
+ *
+ * ## Ordering is a counter, not a clock
+ *
+ * Two calls can land in the same millisecond, so `recorded_at` cannot be the
+ * ordering key. `recorded_runs.next_seq` is incremented atomically with every
+ * insert into `recorded_calls`, in the same transaction, so "what order did
+ * these happen in" is answerable from the primary key alone — the property
+ * §12's replay requirement depends on ("same inputs + same recorded responses
+ * = the same finding, byte for byte" only holds if a replayer can tell what
+ * order to feed them back in).
+ *
+ * ## `recordCall` cannot change the tool's own return
+ *
+ * A caller is expected to call the real tool, get its result, and *then* call
+ * `recordCall` — recording is telemetry about a call that has already
+ * happened, never a gate on it. So `recordCall` never throws: every failure
+ * inside it — no such run, a driver error, `arguments`/`result` containing
+ * something `canonicalJson` refuses (a `bigint`, a top-level `undefined`) — is
+ * caught here and reported back as `{ recorded: false, error }`. A caller that
+ * ignores the return value still gets its tool result untouched. This is
+ * `CLAUDE.md`'s honest-degradation rule applied to the recorder itself: a
+ * failed recording is disclosed in the return value, never silent, and never
+ * fatal to the call it was recording.
+ *
+ * ## Redaction is a documented seam
+ *
+ * Contract §6 puts redaction at the tool boundary, before the model call.
+ * `RecordCallOptions.redact`, when supplied, runs on the call *before* it is
+ * serialised, so nothing unredacted ever reaches `canonicalJson` once a
+ * redactor is passed in. `./redact.ts`'s `createRecordingRedactor` is a real
+ * implementation of that seam, ported from the model-client redaction seam in
+ * descry-desktop — see its module header. It is still opt-in rather than
+ * automatic here: this module has no way to know a deployment's actual
+ * secret values on its own, only the caller does, so a caller must construct
+ * the redactor and pass it. **No caller in this repo does that yet** — the
+ * MCP server's tool dispatch and `descry-runtime`'s do not call `recordCall`
+ * at all today (that wiring is separate, P3-boundary work) — so every row
+ * this module writes today is still exactly what the tool call carried. See
+ * `schema.ts`'s module header before treating a recording database file as
+ * safe to hand around.
+ */
+import { type ToolClass } from "@descryy/ir";
+import type { SqlDriver } from "../store/driver/driver.ts";
+/**
+ * The graph stamp, captured once per run. `null` where the graph was not
+ * consulted — never omitted, for the same reason the wire envelope's
+ * `graph.resolutionFloor` is never absent (contract §3): a missing field and a
+ * null field read identically to a careless caller, and only one of them is
+ * honest about what this run actually saw.
+ */
+export interface RunStamp {
+    readonly commitSha: string | null;
+    readonly builtAt: string | null;
+    readonly irSchemaVersion: number | null;
+}
+export interface StartRunOptions {
+    /**
+     * §12: present and nullable, **and null on every row this store will ever
+     * hold.** That is a settled fact now, not a pending wiring job.
+     *
+     * This comment used to say a caller in `descry-desktop/packages/pipeline`
+     * would eventually pass a value here. It will not, and the reason is
+     * structural rather than a matter of scheduling: this is the **tool-call**
+     * recording store, and `descry-desktop` never calls into it — measured, a
+     * grep for `startRun(`, `recordCall(` and `readRun(` across every `src`
+     * directory in that repository returns no reference to this module. It
+     * records model calls in its own `model_recording_attempts` table
+     * (`packages/session/src/model-recording/`), which carries its own
+     * `prompt_version` column, **per attempt** — because one run of that
+     * pipeline renders eight distinct prompts, and one column once per run
+     * cannot carry eight values without inventing a summary of seven of them.
+     *
+     * The column stays. A store that records tool calls has an honest place to
+     * name the prompt a run was issued under, if this repository ever grows a
+     * caller that knows one. What it does not have is a caller today, and
+     * saying "until that wiring lands" implied one was on its way.
+     *
+     * Corrected by PF-1 of `documents/plans/prompt-fingerprinting.md`.
+     */
+    readonly promptVersion?: string | null;
+    /** §12: present and nullable. No model layer exists yet, so always null today. */
+    readonly modelId?: string | null;
+    /** Injectable so determinism proofs are not at the mercy of the wall clock. */
+    readonly now?: () => number;
+    /** Injectable so determinism proofs are not at the mercy of `randomUUID`. */
+    readonly id?: () => string;
+}
+export declare function startRun(driver: SqlDriver, stamp: RunStamp, options?: StartRunOptions): {
+    runId: string;
+};
+/** One tool call, as the contract envelope defines it (§2, §6) — never a summary. */
+export interface ToolCallRecord {
+    readonly tool: string;
+    readonly toolVersion: string;
+    readonly class: ToolClass;
+    /** The full arguments passed to the call. */
+    readonly arguments: unknown;
+    /** The full result envelope returned — every field, including `disclosures`. */
+    readonly result: unknown;
+    readonly durationMs: number;
+    /** No model calls exist yet in this repo — always `null` today. Never invented as 0. */
+    readonly cost: number | null;
+}
+export interface RecordCallOptions {
+    readonly now?: () => number;
+    /** The redaction seam — see this file's module header. */
+    readonly redact?: (call: ToolCallRecord) => ToolCallRecord;
+}
+export type RecordCallResult = {
+    readonly recorded: true;
+    readonly seq: number;
+} | {
+    readonly recorded: false;
+    readonly error: unknown;
+};
+/** Record one call. Never throws — see this file's module header. */
+export declare function recordCall(driver: SqlDriver, runId: string, call: ToolCallRecord, options?: RecordCallOptions): RecordCallResult;
+//# sourceMappingURL=writer.d.ts.map

package/dist/recording/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../src/recording/writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAGH,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAE5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,+EAA+E;IAC/E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,GAAE,eAAoB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAsB7G;AAED,qFAAqF;AACrF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,cAAc,CAAC;CAC5D;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1D,qEAAqE;AACrE,wBAAgB,UAAU,CACxB,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,cAAc,EACpB,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CAsClB"}

package/dist/recording/writer.js

@@ -0,0 +1,81 @@
+/**
+ * Recording a run and its calls — `ai-tool-contract.md` §6, rule 5 (§41.15).
+ *
+ * ## Ordering is a counter, not a clock
+ *
+ * Two calls can land in the same millisecond, so `recorded_at` cannot be the
+ * ordering key. `recorded_runs.next_seq` is incremented atomically with every
+ * insert into `recorded_calls`, in the same transaction, so "what order did
+ * these happen in" is answerable from the primary key alone — the property
+ * §12's replay requirement depends on ("same inputs + same recorded responses
+ * = the same finding, byte for byte" only holds if a replayer can tell what
+ * order to feed them back in).
+ *
+ * ## `recordCall` cannot change the tool's own return
+ *
+ * A caller is expected to call the real tool, get its result, and *then* call
+ * `recordCall` — recording is telemetry about a call that has already
+ * happened, never a gate on it. So `recordCall` never throws: every failure
+ * inside it — no such run, a driver error, `arguments`/`result` containing
+ * something `canonicalJson` refuses (a `bigint`, a top-level `undefined`) — is
+ * caught here and reported back as `{ recorded: false, error }`. A caller that
+ * ignores the return value still gets its tool result untouched. This is
+ * `CLAUDE.md`'s honest-degradation rule applied to the recorder itself: a
+ * failed recording is disclosed in the return value, never silent, and never
+ * fatal to the call it was recording.
+ *
+ * ## Redaction is a documented seam
+ *
+ * Contract §6 puts redaction at the tool boundary, before the model call.
+ * `RecordCallOptions.redact`, when supplied, runs on the call *before* it is
+ * serialised, so nothing unredacted ever reaches `canonicalJson` once a
+ * redactor is passed in. `./redact.ts`'s `createRecordingRedactor` is a real
+ * implementation of that seam, ported from the model-client redaction seam in
+ * descry-desktop — see its module header. It is still opt-in rather than
+ * automatic here: this module has no way to know a deployment's actual
+ * secret values on its own, only the caller does, so a caller must construct
+ * the redactor and pass it. **No caller in this repo does that yet** — the
+ * MCP server's tool dispatch and `descry-runtime`'s do not call `recordCall`
+ * at all today (that wiring is separate, P3-boundary work) — so every row
+ * this module writes today is still exactly what the tool call carried. See
+ * `schema.ts`'s module header before treating a recording database file as
+ * safe to hand around.
+ */
+import { randomUUID } from "node:crypto";
+import { canonicalJson } from "@descryy/ir";
+export function startRun(driver, stamp, options = {}) {
+    const now = options.now ?? Date.now;
+    const mintId = options.id ?? (() => `run1:${randomUUID()}`);
+    const runId = mintId();
+    driver
+        .prepare(`INSERT INTO recorded_runs
+         (id, started_at, commit_sha, built_at, ir_schema_version, prompt_version, model_id, next_seq)
+       VALUES (?, ?, ?, ?, ?, ?, ?, 0)`)
+        .run(runId, now(), stamp.commitSha, stamp.builtAt, stamp.irSchemaVersion, options.promptVersion ?? null, options.modelId ?? null);
+    return { runId };
+}
+/** Record one call. Never throws — see this file's module header. */
+export function recordCall(driver, runId, call, options = {}) {
+    try {
+        const now = options.now ?? Date.now;
+        return driver.transaction(() => {
+            const run = driver.prepare("SELECT next_seq FROM recorded_runs WHERE id = ?").get(runId);
+            if (run === undefined) {
+                throw new Error(`recordCall: no such run "${runId}" — startRun must be called first`);
+            }
+            const seq = run.next_seq;
+            const effective = options.redact ? options.redact(call) : call;
+            driver
+                .prepare(`INSERT INTO recorded_calls
+             (run_id, seq, tool, tool_version, class, arguments, result, duration_ms, cost, recorded_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(runId, seq, effective.tool, effective.toolVersion, effective.class, canonicalJson(effective.arguments), canonicalJson(effective.result), effective.durationMs, effective.cost, now());
+            driver.prepare("UPDATE recorded_runs SET next_seq = ? WHERE id = ?").run(seq + 1, runId);
+            return { recorded: true, seq };
+        });
+    }
+    catch (error) {
+        return { recorded: false, error };
+    }
+}
+//# sourceMappingURL=writer.js.map

package/dist/recording/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../src/recording/writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,aAAa,EAAkB,MAAM,aAAa,CAAC;AAkD5D,MAAM,UAAU,QAAQ,CAAC,MAAiB,EAAE,KAAe,EAAE,UAA2B,EAAE;IACxF,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACpC,MAAM,MAAM,GAAG,OAAO,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,UAAU,EAAE,EAAE,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC;IAEvB,MAAM;SACH,OAAO,CACN;;uCAEiC,CAClC;SACA,GAAG,CACF,KAAK,EACL,GAAG,EAAE,EACL,KAAK,CAAC,SAAS,EACf,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,eAAe,EACrB,OAAO,CAAC,aAAa,IAAI,IAAI,EAC7B,OAAO,CAAC,OAAO,IAAI,IAAI,CACxB,CAAC;IAEJ,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC;AA0BD,qEAAqE;AACrE,MAAM,UAAU,UAAU,CACxB,MAAiB,EACjB,KAAa,EACb,IAAoB,EACpB,UAA6B,EAAE;IAE/B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;QAEpC,OAAO,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE;YAC7B,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAuB,iDAAiD,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAC/G,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBACtB,MAAM,IAAI,KAAK,CAAC,4BAA4B,KAAK,mCAAmC,CAAC,CAAC;YACxF,CAAC;YACD,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC;YACzB,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAE/D,MAAM;iBACH,OAAO,CACN;;iDAEuC,CACxC;iBACA,GAAG,CACF,KAAK,EACL,GAAG,EACH,SAAS,CAAC,IAAI,EACd,SAAS,CAAC,WAAW,EACrB,SAAS,CAAC,KAAK,EACf,aAAa,CAAC,SAAS,CAAC,SAAS,CAAC,EAClC,aAAa,CAAC,SAAS,CAAC,MAAM,CAAC,EAC/B,SAAS,CAAC,UAAU,EACpB,SAAS,CAAC,IAAI,EACd,GAAG,EAAE,CACN,CAAC;YAEJ,MAAM,CAAC,OAAO,CAAC,oDAAoD,CAAC,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;YAEzF,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAW,CAAC;QAC1C,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACpC,CAAC;AACH,CAAC"}

package/dist/scoping/fanout.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Fan-out attenuation — DEC-067.
+ *
+ * ## The problem this solves, and the one it must not create
+ *
+ * A handful of declarations are depended on by everything: on one measured
+ * repository `Stage` has 186 dependents and `DocumentType` 165. Those
+ * dependencies are **real**, and the graph represents them at full weight. The
+ * damage is not in the edge, it is in what traversal does when it *passes
+ * through* such a node — one function's reference to an enum drags 164
+ * unrelated consumers into a blast radius they have nothing to do with.
+ *
+ * So the attenuation attaches to **expansion out of a hub**, never to the edge.
+ * Weighting the edge would penalise both directions, and only one of them is
+ * wrong:
+ *
+ * - **change `DocumentType`** — all 165 dependents genuinely break. Damping that
+ *   makes Descry *understate* real impact, which is the opposite of the failure
+ *   being fixed.
+ * - **change a function that references `DocumentType`** — the other 164
+ *   consumers are unaffected, and pulling them in is noise.
+ *
+ * **The seed exemption is what separates those two cases**, and without it this
+ * module contradicts its own reason for existing. Seeds enter traversal at depth
+ * 0; attenuation applies only from depth 1 onward. A hub that was *changed* is
+ * never attenuated; a hub that was *reached* always is.
+ *
+ * ## Fan-out is not stored anywhere
+ *
+ * It is derived at traversal time from the adjacency already fetched, and is
+ * never written to a node, never part of identity, never hashed, never in a
+ * qualified symbol path, and never persisted (DEC-017's derived/earned split
+ * puts it firmly on the derived side — in fact it is not even that, it is not
+ * stored at all).
+ *
+ * ## Why the candidate count and not a separate in-degree query
+ *
+ * Traversal has already enumerated exactly the edges it would follow out of the
+ * current node. That count **is** the operational fan-out — the number of ways
+ * this node can explode — and it needs no second query, no index and no
+ * post-build pass. Defining fan-out as "edges expansion would follow" rather
+ * than as abstract in-degree also makes it the quantity that actually causes the
+ * dilution, rather than a proxy for it.
+ *
+ * One consequence has to be stated: `perNodeLimit` caps that enumeration, so a
+ * limit at or below the top boundary would understate a hub's fan-out and
+ * under-attenuate it. `validateScopingConfig` refuses that combination rather
+ * than silently mis-bucketing.
+ *
+ * ## Calibration
+ *
+ * Every number here is **provisional** (DEC-067). They are starting values from
+ * a single repository, chosen so that all four buckets are occupied — measured
+ * at 8.5% / 22.0% / 28.5% / 41.0% of `USES_TYPE` edges — which is the minimum
+ * property that makes the table worth having. They are to be tuned from real
+ * traversal data, like every other weight in §12.
+ */
+/** One band of the attenuation table. `upTo` is inclusive. */
+export interface FanOutBucket {
+    /** Largest fan-out in this band. The final bucket uses `Infinity`. */
+    readonly upTo: number;
+    /** Multiplier applied to expansion out of a node in this band. */
+    readonly multiplier: number;
+    /** Human label, for explaining a score rather than for logic. */
+    readonly label: string;
+}
+/**
+ * DEC-067's provisional table.
+ *
+ * `1.0` for the first band matters: an ordinary node must be completely
+ * unaffected, so that introducing this feature cannot move any score in a graph
+ * without hubs.
+ */
+export declare const DEFAULT_FANOUT_BUCKETS: readonly FanOutBucket[];
+/** The bucket a fan-out falls in. Never undefined — the last bucket is open. */
+export declare function bucketFor(fanOut: number, buckets?: readonly FanOutBucket[]): FanOutBucket;
+/**
+ * The multiplier for expansion out of a node.
+ *
+ * `depth === 0` is the seed exemption and is checked here rather than at the
+ * call site, so the rule lives in one place and cannot be half-applied.
+ */
+export declare function attenuationFor(fanOut: number, depth: number, buckets?: readonly FanOutBucket[]): number;
+/** The largest multiplier any bucket can apply — what termination must clear. */
+export declare function maxAttenuation(buckets: readonly FanOutBucket[]): number;
+//# sourceMappingURL=fanout.d.ts.map

package/dist/scoping/fanout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fanout.d.ts","sourceRoot":"","sources":["../../src/scoping/fanout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,YAAY,EAKzD,CAAC;AAEF,gFAAgF;AAChF,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,SAAS,YAAY,EAA2B,GACxD,YAAY,CAMd;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,SAAS,YAAY,EAA2B,GACxD,MAAM,CAGR;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAEvE"}

package/dist/scoping/fanout.js

@@ -0,0 +1,95 @@
+/**
+ * Fan-out attenuation — DEC-067.
+ *
+ * ## The problem this solves, and the one it must not create
+ *
+ * A handful of declarations are depended on by everything: on one measured
+ * repository `Stage` has 186 dependents and `DocumentType` 165. Those
+ * dependencies are **real**, and the graph represents them at full weight. The
+ * damage is not in the edge, it is in what traversal does when it *passes
+ * through* such a node — one function's reference to an enum drags 164
+ * unrelated consumers into a blast radius they have nothing to do with.
+ *
+ * So the attenuation attaches to **expansion out of a hub**, never to the edge.
+ * Weighting the edge would penalise both directions, and only one of them is
+ * wrong:
+ *
+ * - **change `DocumentType`** — all 165 dependents genuinely break. Damping that
+ *   makes Descry *understate* real impact, which is the opposite of the failure
+ *   being fixed.
+ * - **change a function that references `DocumentType`** — the other 164
+ *   consumers are unaffected, and pulling them in is noise.
+ *
+ * **The seed exemption is what separates those two cases**, and without it this
+ * module contradicts its own reason for existing. Seeds enter traversal at depth
+ * 0; attenuation applies only from depth 1 onward. A hub that was *changed* is
+ * never attenuated; a hub that was *reached* always is.
+ *
+ * ## Fan-out is not stored anywhere
+ *
+ * It is derived at traversal time from the adjacency already fetched, and is
+ * never written to a node, never part of identity, never hashed, never in a
+ * qualified symbol path, and never persisted (DEC-017's derived/earned split
+ * puts it firmly on the derived side — in fact it is not even that, it is not
+ * stored at all).
+ *
+ * ## Why the candidate count and not a separate in-degree query
+ *
+ * Traversal has already enumerated exactly the edges it would follow out of the
+ * current node. That count **is** the operational fan-out — the number of ways
+ * this node can explode — and it needs no second query, no index and no
+ * post-build pass. Defining fan-out as "edges expansion would follow" rather
+ * than as abstract in-degree also makes it the quantity that actually causes the
+ * dilution, rather than a proxy for it.
+ *
+ * One consequence has to be stated: `perNodeLimit` caps that enumeration, so a
+ * limit at or below the top boundary would understate a hub's fan-out and
+ * under-attenuate it. `validateScopingConfig` refuses that combination rather
+ * than silently mis-bucketing.
+ *
+ * ## Calibration
+ *
+ * Every number here is **provisional** (DEC-067). They are starting values from
+ * a single repository, chosen so that all four buckets are occupied — measured
+ * at 8.5% / 22.0% / 28.5% / 41.0% of `USES_TYPE` edges — which is the minimum
+ * property that makes the table worth having. They are to be tuned from real
+ * traversal data, like every other weight in §12.
+ */
+/**
+ * DEC-067's provisional table.
+ *
+ * `1.0` for the first band matters: an ordinary node must be completely
+ * unaffected, so that introducing this feature cannot move any score in a graph
+ * without hubs.
+ */
+export const DEFAULT_FANOUT_BUCKETS = [
+    { upTo: 5, multiplier: 1.0, label: "local" },
+    { upTo: 20, multiplier: 0.8, label: "shared" },
+    { upTo: 50, multiplier: 0.5, label: "high fan-out" },
+    { upTo: Number.POSITIVE_INFINITY, multiplier: 0.25, label: "hub" },
+];
+/** The bucket a fan-out falls in. Never undefined — the last bucket is open. */
+export function bucketFor(fanOut, buckets = DEFAULT_FANOUT_BUCKETS) {
+    for (const bucket of buckets) {
+        if (fanOut <= bucket.upTo)
+            return bucket;
+    }
+    // Unreachable when the table is validated, since the last `upTo` is Infinity.
+    return buckets[buckets.length - 1];
+}
+/**
+ * The multiplier for expansion out of a node.
+ *
+ * `depth === 0` is the seed exemption and is checked here rather than at the
+ * call site, so the rule lives in one place and cannot be half-applied.
+ */
+export function attenuationFor(fanOut, depth, buckets = DEFAULT_FANOUT_BUCKETS) {
+    if (depth === 0)
+        return 1;
+    return bucketFor(fanOut, buckets).multiplier;
+}
+/** The largest multiplier any bucket can apply — what termination must clear. */
+export function maxAttenuation(buckets) {
+    return buckets.reduce((largest, bucket) => Math.max(largest, bucket.multiplier), 0);
+}
+//# sourceMappingURL=fanout.js.map

package/dist/scoping/fanout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fanout.js","sourceRoot":"","sources":["../../src/scoping/fanout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAYH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAA4B;IAC7D,EAAE,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE;IAC5C,EAAE,IAAI,EAAE,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE;IAC9C,EAAE,IAAI,EAAE,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,cAAc,EAAE;IACpD,EAAE,IAAI,EAAE,MAAM,CAAC,iBAAiB,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE;CACnE,CAAC;AAEF,gFAAgF;AAChF,MAAM,UAAU,SAAS,CACvB,MAAc,EACd,UAAmC,sBAAsB;IAEzD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,IAAI,MAAM,CAAC,IAAI;YAAE,OAAO,MAAM,CAAC;IAC3C,CAAC;IACD,8EAA8E;IAC9E,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAc,EACd,KAAa,EACb,UAAmC,sBAAsB;IAEzD,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAC1B,OAAO,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,UAAU,CAAC;AAC/C,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,cAAc,CAAC,OAAgC;IAC7D,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;AACtF,CAAC"}

package/dist/scoping/index.d.ts

@@ -0,0 +1,10 @@
+export { DEFAULT_EDGE_WEIGHTS, DEFAULT_SCOPING_CONFIG, validateScopingConfig, ScopingConfigError, } from "./weights.ts";
+export type { ScopingConfig } from "./weights.ts";
+export { attenuationFor, bucketFor, maxAttenuation, DEFAULT_FANOUT_BUCKETS, } from "./fanout.ts";
+export type { FanOutBucket } from "./fanout.ts";
+export { HistoryFactors, hopDecay, finalScore, maxBoost } from "./score.ts";
+export { NODE_BUDGETS, TIER_THRESHOLDS, tierFor } from "./tiers.ts";
+export type { ScopeTier, Trigger } from "./tiers.ts";
+export { scopeChange } from "./traverse.ts";
+export type { Scope, ScopedNode, ScopeOptions } from "./traverse.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/scoping/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scoping/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EACL,cAAc,EACd,SAAS,EACT,cAAc,EACd,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACpE,YAAY,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/scoping/index.js

@@ -0,0 +1,6 @@
+export { DEFAULT_EDGE_WEIGHTS, DEFAULT_SCOPING_CONFIG, validateScopingConfig, ScopingConfigError, } from "./weights.js";
+export { attenuationFor, bucketFor, maxAttenuation, DEFAULT_FANOUT_BUCKETS, } from "./fanout.js";
+export { HistoryFactors, hopDecay, finalScore, maxBoost } from "./score.js";
+export { NODE_BUDGETS, TIER_THRESHOLDS, tierFor } from "./tiers.js";
+export { scopeChange } from "./traverse.js";
+//# sourceMappingURL=index.js.map

package/dist/scoping/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scoping/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,cAAc,EACd,SAAS,EACT,cAAc,EACd,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAGpE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/scoping/score.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The impact score — §12.4.
+ *
+ *     NewScore = ParentScore × EdgeWeight × ChangeCouplingFactor
+ *                            × IncidentCorrelationFactor × EdgeConfidence
+ *
+ * Both history factors **default to 1.0** so a brand-new file, or a repo with no
+ * logged incidents, is not unfairly under-scored. `EdgeConfidence` defaults to
+ * the edge's own value, which is 1.0 for a well-resolved adapter — so in a clean
+ * R3 repository the last three terms vanish and the formula is just weight
+ * decay. They do their work in a degraded one, which is the point.
+ *
+ * **The formula is applied in two parts, not as one product per hop.** Path
+ * decay uses only `EdgeWeight × EdgeConfidence`, which is strictly below 1 and
+ * therefore always terminates; the two history factors are applied once to a
+ * node's final score. See the long note in `weights.ts` for why the literal
+ * per-hop form cannot hold alongside §12.3 and §12.7, and DEC-037 for the
+ * decision. The short version: compounding a node's incident history at every
+ * hop of a path that merely passes through it counts the same evidence
+ * repeatedly.
+ */
+import type { IREdge } from "@descryy/ir";
+import type { AdjacencyProvider } from "../query/provider.ts";
+import type { ScopingConfig } from "./weights.ts";
+/**
+ * Per-node history factors, computed once and cached.
+ *
+ * Both are looked up on the node being *entered*, not on the edge: "this file
+ * has been involved in incidents" and "this file moves with the change" are
+ * properties of the destination, and computing them per edge would multiply the
+ * same boost in twice for a node reached two ways.
+ */
+export declare class HistoryFactors {
+    #private;
+    constructor(provider: AdjacencyProvider, config: ScopingConfig, seeds: ReadonlySet<string>);
+    /**
+     * §12.4's `ChangeCouplingFactor`, from `CHANGES_WITH` edges (§11.7).
+     *
+     * Boosts a node that historically moves with something in the diff. Two things
+     * make this narrower than it first appears, and both are honest limits rather
+     * than bugs:
+     *
+     * - `CHANGES_WITH` is **file-to-file**, so this only fires for `FILE` nodes.
+     *   A `FUNCTION` never has co-change history of its own.
+     * - The edge is stored in one canonical direction (DEC-036), so both
+     *   directions must be read. This is the one edge type where `outgoing` alone
+     *   is wrong.
+     */
+    couplingFor(nodeId: string): number;
+    /**
+     * §12.4's `IncidentCorrelationFactor`, from `INCIDENT_CORRELATED` edges (§11.6).
+     *
+     * Saturating rather than linear: the third incident on a file says much less
+     * than the first, and an unbounded count would let one pathological file
+     * dominate every blast radius it appears in.
+     */
+    incidentFor(nodeId: string): number;
+}
+/**
+ * The per-hop decay: `EdgeWeight × EdgeConfidence`, and nothing else.
+ *
+ * Strictly below 1 for any valid configuration, so the path score decreases
+ * monotonically and traversal terminates on any graph, cyclic or not. That is
+ * the whole termination argument, and it does not depend on what the history
+ * factors happen to be — which is what makes it a guarantee rather than a hope.
+ */
+export declare function hopDecay(edge: IREdge, config: ScopingConfig): number;
+/**
+ * A node's final score: its best path decay, adjusted once by its own history.
+ *
+ * Capped at `maxScore` because §12.7 tiers on absolute thresholds — a boosted
+ * score above 1.0 would put a two-hop node above the diff itself.
+ */
+export declare function finalScore(pathScore: number, nodeId: string, config: ScopingConfig, history: HistoryFactors): number;
+/**
+ * The largest amount any node's score can be raised by history.
+ *
+ * Pruning happens on the *unboosted* path score, so the prune point must be
+ * lowered by this much — otherwise a node that would clear the threshold once
+ * boosted is discarded before its boost is ever computed.
+ */
+export declare function maxBoost(config: ScopingConfig): number;
+//# sourceMappingURL=score.d.ts.map

package/dist/scoping/score.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score.d.ts","sourceRoot":"","sources":["../../src/scoping/score.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAY,MAAM,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;;;GAOG;AACH,qBAAa,cAAc;;gBAOb,QAAQ,EAAE,iBAAiB,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC;IAM1F;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAwBnC;;;;;;OAMG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;CAUpC;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,cAAc,GACtB,MAAM,CAGR;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAEtD"}