@descryy/core 0.4.0 → 0.5.0

package/dist/recording/writer.d.ts

@@ -1,84 +1,20 @@
-/**
- * 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.
- */
+/** Records a run and its calls (`ai-tool-contract.md` §6 rule 5, §41.15). Ordering is
+ *  `recorded_runs.next_seq`, not `recorded_at` — a clock can tie, and §12's replay guarantee
+ *  needs a total order. `recordCall` never throws: failure returns `{recorded:false,error}`. */
 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.
- */
+/** Graph stamp, captured once per run. `null` (never omitted) where the graph wasn't consulted
+ *  — same as contract §3's `graph.resolutionFloor`: a missing field and a null field read
+ *  identically to a careless caller, and only one is honest. */
 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`.
-     */
+    /** §12: present and nullable, and null on every row this store will hold — settled, not pending.
+     *  descry-desktop never calls this tool-recording store; it tracks prompt_version per-attempt in
+     *  its own model_recording_attempts table (one run renders multiple prompts). Corrected by PF-1. */
     readonly promptVersion?: string | null;
     /** §12: present and nullable. No model layer exists yet, so always null today. */
     readonly modelId?: string | null;
@@ -105,7 +41,8 @@ export interface ToolCallRecord {
 }
 export interface RecordCallOptions {
     readonly now?: () => number;
-    /** The redaction seam — see this file's module header. */
+    /** Opt-in redaction, run before serialising (§6: redaction at the tool boundary). No caller in
+     *  this repo passes one yet — every row currently written is exactly what the tool call carried. */
     readonly redact?: (call: ToolCallRecord) => ToolCallRecord;
 }
 export type RecordCallResult = {

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

@@ -1 +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"}
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../src/recording/writer.ts"],"names":[],"mappings":"AAAA;;gGAEgG;AAGhG,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAE5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D;;gEAEgE;AAChE,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;;wGAEoG;IACpG,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;wGACoG;IACpG,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

@@ -1,46 +1,6 @@
-/**
- * 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.
- */
+/** Records a run and its calls (`ai-tool-contract.md` §6 rule 5, §41.15). Ordering is
+ *  `recorded_runs.next_seq`, not `recorded_at` — a clock can tie, and §12's replay guarantee
+ *  needs a total order. `recordCall` never throws: failure returns `{recorded:false,error}`. */
 import { randomUUID } from "node:crypto";
 import { canonicalJson } from "@descryy/ir";
 export function startRun(driver, stamp, options = {}) {

package/dist/recording/writer.js.map

@@ -1 +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"}
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../src/recording/writer.ts"],"names":[],"mappings":"AAAA;;gGAEgG;AAEhG,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,aAAa,EAAkB,MAAM,aAAa,CAAC;AA0B5D,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;AA2BD,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

@@ -1,59 +1,6 @@
 /**
- * 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.
+ * Fan-out attenuation (DEC-067). A hub (e.g. `DocumentType`, 165 dependents) drags unrelated consumers into a blast radius when merely *passed through* — so attenuation hits expansion out of a hub, never the edge itself: a changed hub still shows full impact (seed exemption, depth 0), a reached one is always damped.
+ * Derived at traversal time from adjacency already fetched — never stored, never part of identity (DEC-017). Table is provisional, measured at 8.5/22.0/28.5/41.0% of `USES_TYPE` edges on one repository; tune from real data like every §12 weight.
  */
 /** One band of the attenuation table. `upTo` is inclusive. */
 export interface FanOutBucket {
@@ -64,22 +11,13 @@ export interface FanOutBucket {
     /** 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.
- */
+/** DEC-067's provisional table. `1.0` for the first band matters — an ordinary
+ *  node must be unaffected 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.
- */
+/** Multiplier for expansion out of a node. `depth === 0` seed exemption checked
+ *  here, not at the call site, so it can't 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;

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

@@ -1 +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"}
+{"version":3,"file":"fanout.d.ts","sourceRoot":"","sources":["../../src/scoping/fanout.ts"],"names":[],"mappings":"AAAA;;;GAGG;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;uDACuD;AACvD,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;+DAC+D;AAC/D,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

@@ -1,67 +1,9 @@
 /**
- * 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.
+ * Fan-out attenuation (DEC-067). A hub (e.g. `DocumentType`, 165 dependents) drags unrelated consumers into a blast radius when merely *passed through* — so attenuation hits expansion out of a hub, never the edge itself: a changed hub still shows full impact (seed exemption, depth 0), a reached one is always damped.
+ * Derived at traversal time from adjacency already fetched — never stored, never part of identity (DEC-017). Table is provisional, measured at 8.5/22.0/28.5/41.0% of `USES_TYPE` edges on one repository; tune from real data like every §12 weight.
  */
+/** DEC-067's provisional table. `1.0` for the first band matters — an ordinary
+ *  node must be unaffected in a graph without hubs. */
 export const DEFAULT_FANOUT_BUCKETS = [
     { upTo: 5, multiplier: 1.0, label: "local" },
     { upTo: 20, multiplier: 0.8, label: "shared" },
@@ -77,12 +19,8 @@ export function bucketFor(fanOut, buckets = DEFAULT_FANOUT_BUCKETS) {
     // 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.
- */
+/** Multiplier for expansion out of a node. `depth === 0` seed exemption checked
+ *  here, not at the call site, so it can't be half-applied. */
 export function attenuationFor(fanOut, depth, buckets = DEFAULT_FANOUT_BUCKETS) {
     if (depth === 0)
         return 1;

package/dist/scoping/fanout.js.map

@@ -1 +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"}
+{"version":3,"file":"fanout.js","sourceRoot":"","sources":["../../src/scoping/fanout.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH;uDACuD;AACvD,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;+DAC+D;AAC/D,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/score.d.ts

@@ -1,83 +1,33 @@
-/**
- * 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.
- */
+/** §12.4 impact score: ParentScore × EdgeWeight × ChangeCouplingFactor ×
+ *  IncidentCorrelationFactor × EdgeConfidence. History factors default 1.0
+ *  (new file/no incidents isn't under-scored). Applied in two parts, not
+ *  per-hop: path decay uses EdgeWeight×EdgeConfidence only (<1, terminates);
+ *  history factors apply once to a node's final score (DEC-037, §12.3/§12.7). */
 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.
- */
+/** Per-node history factors, computed once and cached — looked up on the
+ *  node entered, not the edge, or a node reached two ways double-boosts. */
 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.
-     */
+    /** §12.4's `ChangeCouplingFactor` (`CHANGES_WITH`, §11.7). File-to-file
+     *  only — a `FUNCTION` has no co-change history. Stored in one canonical
+     *  direction (DEC-036), so both `outgoing`/`incoming` must be read. */
     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.
-     */
+    /** §12.4's `IncidentCorrelationFactor` (`INCIDENT_CORRELATED`, §11.6).
+     *  Saturating, not linear — an unbounded count would let one pathological
+     *  file dominate every blast radius. */
     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.
- */
+/** Per-hop decay: `EdgeWeight × EdgeConfidence` only — strictly <1, so path
+ *  score decreases monotonically and traversal terminates on any graph. */
 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.
- */
+/** A node's final score: best path decay, adjusted once by its own history.
+ *  Capped at `maxScore` (§12.7 tiers on absolute thresholds). */
 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.
- */
+/** Largest boost history can add. Pruning runs on the unboosted path score,
+ *  so the prune point must be lowered by this much or a boostable node is
+ *  discarded before its boost is computed. */
 export declare function maxBoost(config: ScopingConfig): number;
 //# sourceMappingURL=score.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"score.d.ts","sourceRoot":"","sources":["../../src/scoping/score.ts"],"names":[],"mappings":"AAAA;;;;iFAIiF;AAEjF,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;4EAC4E;AAC5E,qBAAa,cAAc;;gBAOb,QAAQ,EAAE,iBAAiB,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC;IAM1F;;2EAEuE;IACvE,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAwBnC;;4CAEwC;IACxC,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;CAUpC;AAED;2EAC2E;AAC3E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,CAEpE;AAED;iEACiE;AACjE,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,cAAc,GACtB,MAAM,CAGR;AAED;;8CAE8C;AAC9C,wBAAgB,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAEtD"}

package/dist/scoping/score.js

@@ -1,32 +1,10 @@
-/**
- * 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.
- */
-/**
- * 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.
- */
+/** §12.4 impact score: ParentScore × EdgeWeight × ChangeCouplingFactor ×
+ *  IncidentCorrelationFactor × EdgeConfidence. History factors default 1.0
+ *  (new file/no incidents isn't under-scored). Applied in two parts, not
+ *  per-hop: path decay uses EdgeWeight×EdgeConfidence only (<1, terminates);
+ *  history factors apply once to a node's final score (DEC-037, §12.3/§12.7). */
+/** Per-node history factors, computed once and cached — looked up on the
+ *  node entered, not the edge, or a node reached two ways double-boosts. */
 export class HistoryFactors {
     #provider;
     #config;
@@ -38,19 +16,9 @@ export class HistoryFactors {
         this.#config = config;
         this.#seeds = seeds;
     }
-    /**
-     * §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.
-     */
+    /** §12.4's `ChangeCouplingFactor` (`CHANGES_WITH`, §11.7). File-to-file
+     *  only — a `FUNCTION` has no co-change history. Stored in one canonical
+     *  direction (DEC-036), so both `outgoing`/`incoming` must be read. */
     couplingFor(nodeId) {
         const cached = this.#coupling.get(nodeId);
         if (cached !== undefined)
@@ -73,13 +41,9 @@ export class HistoryFactors {
         this.#coupling.set(nodeId, factor);
         return factor;
     }
-    /**
-     * §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.
-     */
+    /** §12.4's `IncidentCorrelationFactor` (`INCIDENT_CORRELATED`, §11.6).
+     *  Saturating, not linear — an unbounded count would let one pathological
+     *  file dominate every blast radius. */
     incidentFor(nodeId) {
         const cached = this.#incident.get(nodeId);
         if (cached !== undefined)
@@ -91,34 +55,20 @@ export class HistoryFactors {
         return factor;
     }
 }
-/**
- * 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.
- */
+/** Per-hop decay: `EdgeWeight × EdgeConfidence` only — strictly <1, so path
+ *  score decreases monotonically and traversal terminates on any graph. */
 export function hopDecay(edge, config) {
     return config.edgeWeights[edge.type] * edge.confidence;
 }
-/**
- * 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.
- */
+/** A node's final score: best path decay, adjusted once by its own history.
+ *  Capped at `maxScore` (§12.7 tiers on absolute thresholds). */
 export function finalScore(pathScore, nodeId, config, history) {
     const boosted = pathScore * history.couplingFor(nodeId) * history.incidentFor(nodeId);
     return Math.min(boosted, config.maxScore);
 }
-/**
- * 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.
- */
+/** Largest boost history can add. Pruning runs on the unboosted path score,
+ *  so the prune point must be lowered by this much or a boostable node is
+ *  discarded before its boost is computed. */
 export function maxBoost(config) {
     return config.maxCouplingFactor * config.maxIncidentFactor;
 }

package/dist/scoping/score.js.map

@@ -1 +1 @@
-{"version":3,"file":"score.js","sourceRoot":"","sources":["../../src/scoping/score.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"score.js","sourceRoot":"","sources":["../../src/scoping/score.ts"],"names":[],"mappings":"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"}