audit-tools 0.28.0

package/dist/remediate/contractPipeline/semanticProjection.js

@@ -0,0 +1,102 @@
+/**
+ * Semantic projection for contract-pipeline staleness (B3).
+ *
+ * The staleness DAG used to key every dependency on the upstream's RAW payload
+ * content hash, so any byte change to an upstream — a reworded rationale, a
+ * regenerated `created_at` stamp, a reordered list — re-staled the entire
+ * downstream chain and forced a full (often LLM-driven) re-authoring of
+ * artifacts whose load-bearing inputs had not actually changed. That is the
+ * exact friction B3 names: "an edit to finalized_module_contracts re-stales
+ * obligation_ledger → test_validator_plan → contract_assessment even when the
+ * obligation set is unchanged."
+ *
+ * The fix is to make staleness content/semantics-aware: a dependency is recorded
+ * and compared by the hash of its *semantic projection* — only the structure a
+ * downstream actually consumes — not its raw bytes. A cosmetic upstream edit
+ * projects to the same value, so downstreams stay fresh; a real change to the
+ * load-bearing structure (a new module invariant, a changed interface) projects
+ * differently and correctly re-stales.
+ *
+ * This mirrors audit-code's `normalizeForMetadataHash`
+ * (`orchestrator/artifactFreshness.ts`): strip non-semantic provenance fields
+ * universally, then apply a per-artifact structural projection. The two
+ * orchestrators stay in conceptual parity (semantic-projection staleness) while
+ * each owns the projection table for its own artifact set.
+ */
+import { isRecord, stableStringifyProjection } from "audit-tools/shared";
+export { stableStringifyProjection };
+/**
+ * Non-semantic top-level fields stripped from EVERY artifact before projecting.
+ * These are provenance (wall-clock stamps), never meaning: re-deriving the
+ * obligation ledger or re-emitting any artifact mints a fresh `created_at`, and
+ * without stripping it the artifact's hash churns on every rebuild and
+ * perpetually re-stales its downstreams — a finalization-oscillation hazard.
+ */
+const UNIVERSAL_NON_SEMANTIC_FIELDS = ["created_at", "generated_at"];
+/**
+ * The finalized-module-contract fields that are load-bearing for ALL of its
+ * downstreams. These are exactly the fields `deriveObligationLedger` consumes
+ * (`contractPipeline/derive.ts`): the obligation set, the test plan, the
+ * conceptual critique, and the contract assessment all reason about the module
+ * boundaries, interfaces, invariants, and failure modes — never the surrounding
+ * rationale/narrative/seam prose. Projecting to these fields means a pure-prose
+ * edit to the finalized contracts leaves the whole obligation-bearing chain
+ * fresh, while a changed interface or a new invariant correctly re-stales it.
+ */
+const DERIVABLE_MODULE_CONTRACT_FIELDS = [
+    "name",
+    "inputs",
+    "outputs",
+    "invariants",
+    "failure_modes",
+    "validation_boundary",
+];
+function stripFields(record, fields) {
+    const drop = new Set(fields);
+    return Object.fromEntries(Object.entries(record).filter(([key]) => !drop.has(key)));
+}
+function projectModuleContract(value) {
+    const record = isRecord(value) ? value : {};
+    const out = {};
+    for (const field of DERIVABLE_MODULE_CONTRACT_FIELDS) {
+        out[field] = record[field];
+    }
+    return out;
+}
+/**
+ * Project a contract-pipeline artifact payload to only its load-bearing
+ * structure for downstream-staleness purposes. The universal provenance strip
+ * applies to every artifact; `finalized_module_contracts` additionally projects
+ * its `module_contracts` to the derivable fields. Artifacts with no special case
+ * fall back to the provenance-stripped payload (conservative: behaves like the
+ * raw payload minus stamps).
+ *
+ * Non-object payloads pass through unchanged.
+ */
+export function semanticProjection(name, payload) {
+    if (!isRecord(payload))
+        return payload;
+    const stripped = stripFields(payload, UNIVERSAL_NON_SEMANTIC_FIELDS);
+    if (name === "finalized_module_contracts") {
+        // Keep every top-level field (contract_version, goal_id, …) but narrow each
+        // module entry to its derivable fields, so a reworded per-module rationale /
+        // seam-prose edit projects identically while a changed interface / new
+        // invariant does not. Narrowing entries (not the whole artifact) keeps the
+        // projection conservative: any top-level field a downstream might read still
+        // participates in staleness.
+        if (!Array.isArray(stripped.module_contracts))
+            return stripped;
+        return {
+            ...stripped,
+            module_contracts: stripped.module_contracts.map(projectModuleContract),
+        };
+    }
+    return stripped;
+}
+/**
+ * The order-independent stable serialization used to hash a projection is the
+ * shared `stableStringifyProjection` (re-exported above) — single-sourced in
+ * `audit-tools/shared` so audit-code and remediate-code hash projections
+ * identically.
+ */
+//# sourceMappingURL=semanticProjection.js.map

package/dist/remediate/contractPipeline/semanticProjection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticProjection.js","sourceRoot":"","sources":["../../../src/remediate/contractPipeline/semanticProjection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,QAAQ,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAGzE,OAAO,EAAE,yBAAyB,EAAE,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,6BAA6B,GAAsB,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC;AAExF;;;;;;;;;GASG;AACH,MAAM,gCAAgC,GAAsB;IAC1D,MAAM;IACN,QAAQ;IACR,SAAS;IACT,YAAY;IACZ,eAAe;IACf,qBAAqB;CACtB,CAAC;AAEF,SAAS,WAAW,CAClB,MAA+B,EAC/B,MAAyB;IAEzB,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CACzD,CAAC;AACJ,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAc;IAC3C,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5C,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,KAAK,IAAI,gCAAgC,EAAE,CAAC;QACrD,GAAG,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAkC,EAClC,OAAgB;IAEhB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IACvC,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,EAAE,6BAA6B,CAAC,CAAC;IAErE,IAAI,IAAI,KAAK,4BAA4B,EAAE,CAAC;QAC1C,4EAA4E;QAC5E,6EAA6E;QAC7E,uEAAuE;QACvE,2EAA2E;QAC3E,6EAA6E;QAC7E,6BAA6B;QAC7B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;YAAE,OAAO,QAAQ,CAAC;QAC/D,OAAO;YACL,GAAG,QAAQ;YACX,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GAAG,CAAC,qBAAqB,CAAC;SACvE,CAAC;IACJ,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG"}

package/dist/remediate/coverage/findingLedger.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Per-finding / per-node coverage ledger (N-coverage-ledger).
+ *
+ * Source_type-aware denominator (INV-CL-05):
+ *   - structured_audit → finding-enumeration denominator (every finding id
+ *     from finding-enumeration.json must reach a terminal disposition)
+ *   - document / non-enumerable → DAG-node denominator (every promoted
+ *     implementation-DAG node must reach a terminal disposition)
+ *
+ * A 0/0 ledger is INCOMPLETE (fail-closed) — zero denominator never counts as
+ * vacuously complete (INV-CL-05).
+ *
+ * Terminal dispositions: resolved, resolved_no_change, ignored,
+ *   deemed_inappropriate, force_closed_unresolved.
+ *
+ * Non-terminal item statuses (blocked, pending, tested, refactored, verified,
+ *   tested_successfully) map to force_closed_unresolved so that the ledger is
+ *   always fully populated after build.
+ *
+ * Identity (drift-plan R2): the ledger keys every entry off a finding/node id
+ * that is already the output of the single finding-identity authority —
+ * structured_audit denominator ids come from `assignStableFindingIds`
+ * (`<LENS>-<sha256(findingIdentitySignature)>`) and DAG-node denominator ids
+ * come from `ensureNodeId`. The ledger therefore performs no identity rule of
+ * its own; two findings the shared authority deems the same already collapse to
+ * one denominator id upstream (cross-lens dedup), so the ledger never
+ * double-counts one identity. The duplicate guard below catches the inverse —
+ * one identity id claimed by two entries (a merge/build defect).
+ */
+import type { PerFindingCoverageLedger, PerFindingDenominatorKind, RemediationItemState } from "../state/types.js";
+/**
+ * Parameters for building the per-finding ledger.
+ *
+ * For `structured_audit` sources pass `enumeratedIds` — the complete list of
+ * finding ids from `finding-enumeration.json`.  For document / non-enumerable
+ * sources pass `promotedNodeIds` — the ids of all promoted implementation-DAG
+ * nodes.
+ *
+ * `items` is the `RemediationState.items` record: finding_id → state.
+ */
+export interface BuildPerFindingLedgerParams {
+    /** "finding_enumeration" for structured_audit; "dag_node" for document sources. */
+    denominatorKind: PerFindingDenominatorKind;
+    /**
+     * The authoritative denominator set.
+     *
+     * - structured_audit: every id from finding-enumeration.json (all findings).
+     * - document: every promoted implementation-DAG node id.
+     */
+    denominatorIds: readonly string[];
+    /** The current `RemediationState.items` (may be undefined when state is pre-plan). */
+    items: Record<string, RemediationItemState> | undefined;
+}
+/**
+ * Build a `PerFindingCoverageLedger` from the authoritative denominator set
+ * and the current item state.
+ *
+ * Every id in `denominatorIds` produces exactly one entry.  Ids present in
+ * `items` are mapped via `statusToDisposition`; ids absent from `items`
+ * (never reached the implement phase) produce `force_closed_unresolved`.
+ */
+export declare function buildPerFindingLedger(params: BuildPerFindingLedgerParams): PerFindingCoverageLedger;
+/** Result returned by `assertLedgerComplete`. */
+export interface LedgerCompletenessResult {
+    /** True only when every denominator id has a terminal disposition AND denominator > 0. */
+    complete: boolean;
+    /**
+     * Ids that appear in the denominator but have no terminal disposition
+     * (i.e. missing from entries or mapped to a non-terminal disposition).
+     *
+     * In the current implementation all non-terminal statuses map to
+     * `force_closed_unresolved` (which IS terminal), so `missing` contains ids
+     * that are absent from `entries` altogether — which cannot happen after
+     * `buildPerFindingLedger` runs.  This field is retained for callers that
+     * construct ledgers manually or via partial merges.
+     */
+    missing: string[];
+    /**
+     * Ids that appear more than once in `entries`.  Duplicate entries indicate
+     * a merge/build defect (two workers claimed the same finding).
+     */
+    duplicated: string[];
+    /** How the denominator was derived (pass-through from the ledger). */
+    denominator_kind: PerFindingDenominatorKind;
+}
+/**
+ * Assert that a `PerFindingCoverageLedger` is complete.
+ *
+ * Completeness rules (INV-CL-05):
+ * 1. `denominator` must be > 0. A 0/0 ledger is INCOMPLETE (fail-closed).
+ * 2. Every entry must have a terminal disposition.
+ * 3. No id may appear more than once in `entries` (no duplicates).
+ * 4. The number of terminal entries must equal `denominator`.
+ *
+ * Returns `{complete: true, missing: [], duplicated: [], denominator_kind}`
+ * when all rules are satisfied; otherwise `{complete: false, missing, duplicated, ...}`.
+ */
+export declare function assertLedgerComplete(ledger: PerFindingCoverageLedger): LedgerCompletenessResult;
+//# sourceMappingURL=findingLedger.d.ts.map

package/dist/remediate/coverage/findingLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findingLedger.d.ts","sourceRoot":"","sources":["../../../src/remediate/coverage/findingLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EACV,wBAAwB,EACxB,yBAAyB,EAGzB,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAuB3B;;;;;;;;;GASG;AACH,MAAM,WAAW,2BAA2B;IAC1C,mFAAmF;IACnF,eAAe,EAAE,yBAAyB,CAAC;IAC3C;;;;;OAKG;IACH,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,GAAG,SAAS,CAAC;CACzD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,2BAA2B,GAClC,wBAAwB,CAmB1B;AAID,iDAAiD;AACjD,MAAM,WAAW,wBAAwB;IACvC,0FAA0F;IAC1F,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;;;;OASG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,sEAAsE;IACtE,gBAAgB,EAAE,yBAAyB,CAAC;CAC7C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,wBAAwB,GAC/B,wBAAwB,CAoC1B"}

package/dist/remediate/coverage/findingLedger.js

@@ -0,0 +1,110 @@
+/**
+ * Per-finding / per-node coverage ledger (N-coverage-ledger).
+ *
+ * Source_type-aware denominator (INV-CL-05):
+ *   - structured_audit → finding-enumeration denominator (every finding id
+ *     from finding-enumeration.json must reach a terminal disposition)
+ *   - document / non-enumerable → DAG-node denominator (every promoted
+ *     implementation-DAG node must reach a terminal disposition)
+ *
+ * A 0/0 ledger is INCOMPLETE (fail-closed) — zero denominator never counts as
+ * vacuously complete (INV-CL-05).
+ *
+ * Terminal dispositions: resolved, resolved_no_change, ignored,
+ *   deemed_inappropriate, force_closed_unresolved.
+ *
+ * Non-terminal item statuses (blocked, pending, tested, refactored, verified,
+ *   tested_successfully) map to force_closed_unresolved so that the ledger is
+ *   always fully populated after build.
+ *
+ * Identity (drift-plan R2): the ledger keys every entry off a finding/node id
+ * that is already the output of the single finding-identity authority —
+ * structured_audit denominator ids come from `assignStableFindingIds`
+ * (`<LENS>-<sha256(findingIdentitySignature)>`) and DAG-node denominator ids
+ * come from `ensureNodeId`. The ledger therefore performs no identity rule of
+ * its own; two findings the shared authority deems the same already collapse to
+ * one denominator id upstream (cross-lens dedup), so the ledger never
+ * double-counts one identity. The duplicate guard below catches the inverse —
+ * one identity id claimed by two entries (a merge/build defect).
+ */
+import { statusToDisposition } from "../state/itemStatus.js";
+// ── Disposition terminality ─────────────────────────────────────────────────
+// The status→disposition map is single-sourced in state/itemStatus.ts; this
+// module owns only PerFindingDisposition terminality (which dispositions count
+// toward coverage).
+/** Whether a PerFindingDisposition is terminal (contributes to coverage). */
+const TERMINAL_DISPOSITIONS = new Set([
+    "resolved",
+    "resolved_no_change",
+    "ignored",
+    "deemed_inappropriate",
+    "force_closed_unresolved",
+]);
+function dispositionIsTerminal(d) {
+    return TERMINAL_DISPOSITIONS.has(d);
+}
+/**
+ * Build a `PerFindingCoverageLedger` from the authoritative denominator set
+ * and the current item state.
+ *
+ * Every id in `denominatorIds` produces exactly one entry.  Ids present in
+ * `items` are mapped via `statusToDisposition`; ids absent from `items`
+ * (never reached the implement phase) produce `force_closed_unresolved`.
+ */
+export function buildPerFindingLedger(params) {
+    const { denominatorKind, denominatorIds, items } = params;
+    const entries = denominatorIds.map((id) => {
+        const stateItem = items?.[id];
+        const disposition = stateItem
+            ? statusToDisposition(stateItem.status)
+            : "force_closed_unresolved";
+        return { id, disposition };
+    });
+    const covered = entries.filter((e) => dispositionIsTerminal(e.disposition)).length;
+    return {
+        denominator_kind: denominatorKind,
+        denominator: denominatorIds.length,
+        covered,
+        entries,
+    };
+}
+/**
+ * Assert that a `PerFindingCoverageLedger` is complete.
+ *
+ * Completeness rules (INV-CL-05):
+ * 1. `denominator` must be > 0. A 0/0 ledger is INCOMPLETE (fail-closed).
+ * 2. Every entry must have a terminal disposition.
+ * 3. No id may appear more than once in `entries` (no duplicates).
+ * 4. The number of terminal entries must equal `denominator`.
+ *
+ * Returns `{complete: true, missing: [], duplicated: [], denominator_kind}`
+ * when all rules are satisfied; otherwise `{complete: false, missing, duplicated, ...}`.
+ */
+export function assertLedgerComplete(ledger) {
+    const { denominator, entries, denominator_kind } = ledger;
+    // Rule 1: fail-closed on zero denominator.
+    if (denominator === 0) {
+        return { complete: false, missing: [], duplicated: [], denominator_kind };
+    }
+    // Detect duplicates
+    const seen = new Map();
+    for (const entry of entries) {
+        seen.set(entry.id, (seen.get(entry.id) ?? 0) + 1);
+    }
+    const duplicated = [...seen.entries()]
+        .filter(([, count]) => count > 1)
+        .map(([id]) => id);
+    // Ids with non-terminal disposition
+    const nonTerminal = entries
+        .filter((e) => !dispositionIsTerminal(e.disposition))
+        .map((e) => e.id);
+    // Ids missing from entries entirely (if someone built a partial ledger)
+    // We detect this by checking covered vs denominator via the entries array.
+    const terminalCount = entries.filter((e) => dispositionIsTerminal(e.disposition)).length;
+    const missing = nonTerminal; // non-terminal entries = still missing a real closure
+    const complete = duplicated.length === 0 &&
+        missing.length === 0 &&
+        terminalCount === denominator;
+    return { complete, missing, duplicated, denominator_kind };
+}
+//# sourceMappingURL=findingLedger.js.map

package/dist/remediate/coverage/findingLedger.js.map

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

package/dist/remediate/dedup/crossLensDedup.d.ts

@@ -0,0 +1,9 @@
+import type { Finding, RemediationBlock } from "../state/types.js";
+export declare function wordJaccard(a: string, b: string): number;
+export interface CrossLensDedupResult {
+    findings: Finding[];
+    mergeMap: Map<string, string>;
+}
+export declare function deduplicateCrossLensFindings(findings: Finding[]): CrossLensDedupResult;
+export declare function fixupBlocksAfterDedup(blocks: RemediationBlock[], mergeMap: Map<string, string>): RemediationBlock[];
+//# sourceMappingURL=crossLensDedup.d.ts.map

package/dist/remediate/dedup/crossLensDedup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crossLensDedup.d.ts","sourceRoot":"","sources":["../../../src/remediate/dedup/crossLensDedup.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAYnE,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CASxD;AAkCD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,OAAO,EAAE,GAClB,oBAAoB,CA2ItB;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,gBAAgB,EAAE,EAC1B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,gBAAgB,EAAE,CAMpB"}

package/dist/remediate/dedup/crossLensDedup.js

@@ -0,0 +1,191 @@
+import { severityRank, confidenceRank, findingIdentityKey, } from "audit-tools/shared";
+function wordSet(text) {
+    return new Set(text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, " ")
+        .split(/\s+/)
+        .filter(Boolean));
+}
+export function wordJaccard(a, b) {
+    const sa = wordSet(a);
+    const sb = wordSet(b);
+    let intersection = 0;
+    for (const w of sa) {
+        if (sb.has(w))
+            intersection++;
+    }
+    const union = sa.size + sb.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+function filePathOverlap(a, b) {
+    const setA = new Set(a.affected_files.map((f) => f.path));
+    const setB = new Set(b.affected_files.map((f) => f.path));
+    let intersection = 0;
+    for (const path of setA) {
+        if (setB.has(path))
+            intersection++;
+    }
+    const union = setA.size + setB.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+function primaryPath(finding) {
+    return finding.affected_files[0]?.path ?? "";
+}
+/**
+ * The shared finding-identity signature of a finding, but only when it is
+ * *discriminating* enough to stand on its own as an exact-match key for
+ * cross-lens dedup. A structural-anchor signature with an empty scope
+ * (`anchor|<path>|`) means nothing more than "same file" — too coarse to
+ * collapse two findings by itself, so the fuzzy title/overlap layer must refine
+ * it. We return `null` in that case so it never short-circuits the heuristic.
+ * Anchored-with-scope and normalized-title signatures are discriminating and are
+ * returned verbatim; the rule/category tier embeds the lens, so two cross-lens
+ * findings never share it (they fall through to the fuzzy layer by design).
+ */
+function discriminatingIdentityKey(finding) {
+    const key = findingIdentityKey(finding);
+    if (key.startsWith("anchor|") && key.endsWith("|"))
+        return null;
+    return key;
+}
+export function deduplicateCrossLensFindings(findings) {
+    const groups = new Map();
+    for (const finding of findings) {
+        const key = primaryPath(finding);
+        const group = groups.get(key);
+        if (group) {
+            group.push(finding);
+        }
+        else {
+            groups.set(key, [finding]);
+        }
+    }
+    const removed = new Set();
+    const mergeMap = new Map();
+    /**
+     * Maps each source finding that participates as a survivor to its cloned
+     * merged copy. INV-remediate-state-05: survivors are cloned so the caller's
+     * original Finding objects are never mutated in place.
+     */
+    const cloneOf = new Map();
+    for (const group of groups.values()) {
+        if (group.length < 2)
+            continue;
+        for (let i = 0; i < group.length; i++) {
+            if (removed.has(group[i]))
+                continue;
+            for (let j = i + 1; j < group.length; j++) {
+                if (removed.has(group[j]))
+                    continue;
+                const a = group[i];
+                const b = group[j];
+                if (a.lens.toLowerCase() === b.lens.toLowerCase())
+                    continue;
+                // Category is a hard merge-key discriminator, applied ahead of BOTH the
+                // exact-match and fuzzy layers: two findings that share a file/lens-pair
+                // but were classified under different categories describe structurally
+                // different problems and must NEVER be collapsed — e.g. ARC-86b18f1b
+                // (inferred_contract_gap) vs ARC-86b18f1b-2 (invariant_counterexample)
+                // stay distinct (OBL-C003-DEDUP / OBL-INV-RPS-07). Category is
+                // orthogonal to the structural-anchor identity signature (which ignores
+                // it), so it remains an independent hard gate. A true duplicate keeps the
+                // same category and still collapses below.
+                if (a.category.toLowerCase() !== b.category.toLowerCase())
+                    continue;
+                // Exact-match layer (drift-plan R2): within a matching category, the
+                // shared finding-identity signature is the one authority for "is this the
+                // same finding?". When two cross-lens findings share a DISCRIMINATING
+                // signature they ARE the same defect — collapse even if their titles
+                // diverged enough to slip under the Jaccard floor (the signature is
+                // lens-independent at the structural-anchor-with-scope and
+                // normalized-title tiers). Otherwise fall back to the fuzzy heuristic: a
+                // moderate title overlap plus a real file overlap.
+                const keyA = discriminatingIdentityKey(a);
+                const keyB = discriminatingIdentityKey(b);
+                const exactIdentityMatch = keyA !== null && keyA === keyB;
+                if (!exactIdentityMatch) {
+                    const titleSim = wordJaccard(a.title, b.title);
+                    if (titleSim < 0.4)
+                        continue;
+                    if (filePathOverlap(a, b) < 0.5)
+                        continue;
+                }
+                const aSev = severityRank(a.severity);
+                const bSev = severityRank(b.severity);
+                const aConf = confidenceRank(a.confidence);
+                const bConf = confidenceRank(b.confidence);
+                const keepA = aSev > bSev || (aSev === bSev && aConf >= bConf);
+                // originalSurvivor is one of the source Finding objects (a or b).
+                // absorbed is the other source Finding.
+                const originalSurvivor = keepA ? a : b;
+                const absorbed = keepA ? b : a;
+                // Re-use the existing clone if this survivor has already been cloned by
+                // a prior pair in this group; otherwise create a new clone.
+                let survivor = cloneOf.get(originalSurvivor);
+                if (!survivor) {
+                    survivor = {
+                        ...originalSurvivor,
+                        affected_files: [...originalSurvivor.affected_files],
+                        evidence: originalSurvivor.evidence ? [...originalSurvivor.evidence] : [],
+                    };
+                    cloneOf.set(originalSurvivor, survivor);
+                    // Update the group slot so future pair iterations in the same group
+                    // refer to the clone rather than the unmodified source object.
+                    const survivorGroupIdx = keepA ? i : j;
+                    group[survivorGroupIdx] = survivor;
+                }
+                const existingPaths = new Set(survivor.affected_files.map((f) => `${f.path}:${f.line_start ?? ""}:${f.line_end ?? ""}:${f.symbol ?? ""}`));
+                for (const file of absorbed.affected_files) {
+                    const fKey = `${file.path}:${file.line_start ?? ""}:${file.line_end ?? ""}:${file.symbol ?? ""}`;
+                    if (!existingPaths.has(fKey)) {
+                        survivor.affected_files.push(file);
+                        existingPaths.add(fKey);
+                    }
+                }
+                survivor.evidence = [
+                    ...new Set([
+                        ...(survivor.evidence ?? []),
+                        ...(absorbed.evidence ?? []),
+                    ]),
+                ];
+                survivor.systemic = Boolean(survivor.systemic || absorbed.systemic);
+                if (absorbed.summary.length > survivor.summary.length) {
+                    survivor.summary = absorbed.summary;
+                }
+                removed.add(absorbed);
+                mergeMap.set(absorbed.id, survivor.id);
+                process.stderr.write(JSON.stringify({
+                    level: "info",
+                    event: "cross_lens_dedup_merge",
+                    absorbed_id: absorbed.id,
+                    absorbed_lens: absorbed.lens,
+                    survivor_id: survivor.id,
+                    survivor_lens: survivor.lens,
+                    ts: new Date().toISOString(),
+                }) + "\n");
+                // If the `i`-slot finding was just absorbed (!keepA), stop the inner
+                // loop — there is no point comparing an absorbed finding with more
+                // candidates. The outer loop's guard (removed.has(group[i])) handles
+                // advancing `i` past it on the next outer iteration.
+                if (!keepA)
+                    break;
+            }
+        }
+    }
+    // Return clones for survivors, original objects for untouched findings.
+    return {
+        findings: findings
+            .filter((f) => !removed.has(f))
+            .map((f) => cloneOf.get(f) ?? f),
+        mergeMap,
+    };
+}
+export function fixupBlocksAfterDedup(blocks, mergeMap) {
+    if (mergeMap.size === 0)
+        return blocks;
+    return blocks.map((block) => ({
+        ...block,
+        items: [...new Set(block.items.map((id) => mergeMap.get(id) ?? id))],
+    }));
+}
+//# sourceMappingURL=crossLensDedup.js.map

package/dist/remediate/dedup/crossLensDedup.js.map

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

package/dist/remediate/dispatch/amendmentClaim.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Amendment claim routing for the ownership-gated affected_files protocol.
+ *
+ * When a worker discovers a necessary edit outside its declared contract scope,
+ * it submits the candidate paths to `routeAmendmentRequest`. Unowned paths are
+ * granted unilaterally; owned or contended paths are routed back through the
+ * seam detect+resolve protocol.
+ */
+import type { OwnershipRegistry } from "./ownershipRegistry.js";
+/** Discriminated union for the outcome of a single amendment claim attempt. */
+export type AmendmentClaimResult = {
+    outcome: "granted";
+    path: string;
+} | {
+    outcome: "owned";
+    path: string;
+    owner_node_id: string;
+} | {
+    outcome: "contended";
+    path: string;
+    sibling_node_id: string;
+};
+/**
+ * Route a worker's requested amendment paths into granted vs seam-routed.
+ *
+ * - Granted paths: unowned and uncontended — added to the node's scope for
+ *   targeted verification before committing to main.
+ * - Seam-routed paths: owned by another node's contract scope or contended by
+ *   a live parallel sibling — must be resolved via the seam detect+resolve
+ *   protocol (re-scope contracts or serialize the nodes) before merging.
+ *
+ * Each path appears in exactly one of the two output lists.
+ */
+export declare function routeAmendmentRequest(registry: OwnershipRegistry, nodeId: string, candidatePaths: string[]): {
+    granted: string[];
+    seam_routed: Array<{
+        path: string;
+        reason: AmendmentClaimResult;
+    }>;
+};
+//# sourceMappingURL=amendmentClaim.d.ts.map

package/dist/remediate/dispatch/amendmentClaim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amendmentClaim.d.ts","sourceRoot":"","sources":["../../../src/remediate/dispatch/amendmentClaim.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,+EAA+E;AAC/E,MAAM,MAAM,oBAAoB,GAC5B;IAAE,OAAO,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EAAE,GACvB;IACD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,oBAAoB,CAAA;KAAE,CAAC,CAAC;CACpE,CAgDA"}

package/dist/remediate/dispatch/amendmentClaim.js

@@ -0,0 +1,60 @@
+/**
+ * Amendment claim routing for the ownership-gated affected_files protocol.
+ *
+ * When a worker discovers a necessary edit outside its declared contract scope,
+ * it submits the candidate paths to `routeAmendmentRequest`. Unowned paths are
+ * granted unilaterally; owned or contended paths are routed back through the
+ * seam detect+resolve protocol.
+ */
+/**
+ * Route a worker's requested amendment paths into granted vs seam-routed.
+ *
+ * - Granted paths: unowned and uncontended — added to the node's scope for
+ *   targeted verification before committing to main.
+ * - Seam-routed paths: owned by another node's contract scope or contended by
+ *   a live parallel sibling — must be resolved via the seam detect+resolve
+ *   protocol (re-scope contracts or serialize the nodes) before merging.
+ *
+ * Each path appears in exactly one of the two output lists.
+ */
+export function routeAmendmentRequest(registry, nodeId, candidatePaths) {
+    const granted = [];
+    const seam_routed = [];
+    for (const path of candidatePaths) {
+        const outcome = registry.claimAmendment(nodeId, path);
+        if (outcome === "granted") {
+            granted.push(path);
+            continue;
+        }
+        if (outcome === "owned") {
+            const owner_node_id = registry.contractOwner(path) ?? "unknown";
+            const entry = { outcome: "owned", path, owner_node_id };
+            seam_routed.push({ path, reason: entry });
+            process.stderr.write(JSON.stringify({
+                level: "warn",
+                event: "amendment_seam_routed",
+                node_id: nodeId,
+                path,
+                outcome: "owned",
+                owner_node_id,
+                ts: new Date().toISOString(),
+            }) + "\n");
+            continue;
+        }
+        // contended
+        const sibling_node_id = registry.amendmentClaimant(path) ?? "unknown";
+        const entry = { outcome: "contended", path, sibling_node_id };
+        seam_routed.push({ path, reason: entry });
+        process.stderr.write(JSON.stringify({
+            level: "warn",
+            event: "amendment_seam_routed",
+            node_id: nodeId,
+            path,
+            outcome: "contended",
+            sibling_node_id,
+            ts: new Date().toISOString(),
+        }) + "\n");
+    }
+    return { granted, seam_routed };
+}
+//# sourceMappingURL=amendmentClaim.js.map