pi-mega-compact 0.20.6 → 0.20.8

package/dist/src/vectorStore/class.js

@@ -1,34 +1,21 @@
-/**
- * class.ts — VectorStore implementation (extracted from vectorStore.ts).
- *
- * One store, three consumers (per PLAN.md): auto-inline on resume, on-demand
- * /recall-context, and the dedup sentinel. All share `add / search / dedupe`.
- *
- * Backed by the gzipped on-disk checkpoint files (store.ts). Similarity is a
- * linear cosine scan — checkpoint counts are small, so no ANN index is needed.
- */
-import { createHash } from "node:crypto";
-import { cosineSimilarity, defaultEmbedder } from "../embedder.js";
+import { defaultEmbedder } from "../embedder.js";
 import { loadDedupConfig, } from "../config/dedup.js";
 import { logDecision } from "../monitoring.js";
 import { repoKey } from "../store/repoKey.js";
-import { getStateDir, normalizeSessionId, compressSmart } from "../store.js";
-import { computeContentDigest } from "../dedup/digest.js";
-import { minhashSignature, SIGNATURE_VERSION, NUM_HASHES, } from "../dedup/l1-minhash.js";
-import { lshBands } from "../dedup/l1-lsh.js";
-import { isNearDuplicate } from "../dedup/l1-verify.js";
-import { openBloom, saveBloom } from "../store/bloom.js";
-import { listCheckpoints, nextCheckpointId, upsertCheckpoint, loadSessionState, saveSessionState, upsertMinhashSignature, insertLshBuckets, lshCandidateChunks, addTokensSaved, bumpDedupStats, } from "../store/sqlite.js";
+import { getStateDir } from "../store.js";
+import { openBloom } from "../store/bloom.js";
 import { migrateJsonToSqlite } from "../store/migrate.js";
-import { computeRegionHash } from "./hash.js";
+import { addCheckpoint } from "./add.js";
 export class VectorStore {
     // These fields are `readonly` (set once in the constructor) but NOT private:
-    // the read/search/dedup helpers split into vector-read.ts, vector-search.ts,
-    // and vector-dedup.ts access them directly. Marking them private would force
-    // ugly `as unknown as` casts in those modules; keeping them package-public
-    // makes VectorStore a thin barrel whose helpers live in sibling files.
+    // the add/read/search/dedup helpers split into add.ts, vector-read.ts,
+    // vector-search.ts, and vector-dedup.ts access them directly. Marking them
+    // private would force ugly `as unknown as` casts in those modules; keeping
+    // them package-public makes VectorStore a thin barrel whose helpers live in
+    // sibling files.
     embedder;
     stateDir;
+    /** L2 semantic firing point (cfg.L2_COSINE, or a direct test override). */
     l2Threshold;
     /** Single source of truth for tier flags + thresholds (Sprint 14). */
     cfg;
@@ -82,275 +69,12 @@ export class VectorStore {
         });
     }
     /**
-     * Add a checkpoint. Dedup cascade:
-     *   1. regionHash exact match (legacy, backward-compat)
-     *   2. summaryHash exact match (new: catches same-topic incremental compactions)
-     *   3. content similarity ≥ dedupSim (catches near-identical summaries)
-     *   4. If none match → create new checkpoint
+     * Add a checkpoint, deduping it against the session's existing checkpoints.
+     *
+     * The cascade itself lives in ./add.ts (sibling-helper pattern) so this class
+     * stays a thin shell over the fields its helpers read.
      */
     add(input) {
-        const t0 = Date.now();
-        const sessionId = normalizeSessionId(input.sessionId);
-        const regionHash = computeRegionHash(input.regionText);
-        const all = listCheckpoints(sessionId, this.stateDir);
-        // Honest "tokens saved" base for this region. For a deduped add the whole
-        // original region is discarded (nothing new stored); for a new checkpoint
-        // we persist (orig − stored). Falls back to stored when orig is unknown.
-        const origTokens = input.originalTokenEstimate ?? input.tokenEstimate ?? 0;
-        const cfg = this.cfg;
-        // Live per-tier progress hook (Phase 1). Sync + optional; fired at each tier
-        // so the UI can paint "L0 ✓ → L1 ✓ → L2 0.91 → stored" during a compaction.
-        const onTier = input.onTier;
-        // Tracks whether a tier matched while in MARK_ONLY (record-but-don't-collapse),
-        // and which tier.
-        let markOnly = null;
-        // 0. L0 content-hash dedup (Sprint 9) — catches identical content arriving
-        //    under different regionText. Normalization handles case/whitespace/ANSI so
-        //    variants collapse to one row. Dual-hash guards a single-hash collision.
-        //    Sprint 10: bloom is the accelerator — a miss means "definitely new" and
-        //    skips the scan; a hit is only a candidate, confirmed against `all` below.
-        //    Gated by L0_ENABLED (Sprint 14). MARK_ONLY_L0 records the decision but
-        //    does not collapse — the new region is still stored.
-        onTier?.({ tier: "L0", status: "scanning" });
-        const digest = computeContentDigest(input.regionText);
-        const bloom = openBloom(this.stateDir);
-        if (cfg.L0_ENABLED && bloom.maybeHas(digest.contentHash)) {
-            const contentMatch = all.find((cp) => cp.contentHash === digest.contentHash &&
-                cp.contentHash2 === digest.contentHash2);
-            if (contentMatch) {
-                if (cfg.MARK_ONLY_L0) {
-                    markOnly = "L0"; // Record-but-don't-collapse: fall through.
-                }
-                else {
-                    contentMatch.timestamp = input.timestamp;
-                    upsertCheckpoint(contentMatch, this.stateDir);
-                    bumpDedupStats(true, this.stateDir);
-                    // Deduped: whole original region discarded, nothing new stored.
-                    addTokensSaved(origTokens, this.stateDir);
-                    const r = {
-                        checkpoint: contentMatch,
-                        deduped: true,
-                        reason: "contentHash",
-                    };
-                    this.record("L0", "deduped", "contentHash", Date.now() - t0, 1, contentMatch.checkpointId);
-                    onTier?.({ tier: "L0", status: "deduped", detail: "contentHash" });
-                    return r;
-                }
-            }
-        }
-        // 1. Legacy regionHash dedup (backward-compat) — part of L0 tier gating.
-        if (cfg.L0_ENABLED) {
-            const regionMatch = all.find((cp) => cp.regionHash === regionHash);
-            if (regionMatch) {
-                if (cfg.MARK_ONLY_L0) {
-                    markOnly = "L0"; // fall through
-                }
-                else {
-                    bumpDedupStats(true, this.stateDir);
-                    // Deduped: whole original region discarded, nothing new stored.
-                    addTokensSaved(origTokens, this.stateDir);
-                    const r = {
-                        checkpoint: regionMatch,
-                        deduped: true,
-                        reason: "regionHash",
-                    };
-                    this.record("L0", "deduped", "regionHash", Date.now() - t0, 1, regionMatch.checkpointId);
-                    onTier?.({ tier: "L0", status: "deduped", detail: "regionHash" });
-                    return r;
-                }
-            }
-        }
-        // 2. SummaryHash dedup — catches same-topic incremental compactions.
-        //    Full 64-hex SHA-256 (was 16-hex in Sprint 8 — collision-prone).
-        const summaryHash = input.topicSummary
-            ? createHash("sha256").update(input.topicSummary).digest("hex")
-            : undefined;
-        if (summaryHash && cfg.L0_ENABLED) {
-            const summaryMatch = all.find((cp) => cp.summaryHash === summaryHash);
-            if (summaryMatch) {
-                if (cfg.MARK_ONLY_L0) {
-                    markOnly = "L0"; // fall through
-                }
-                else {
-                    summaryMatch.timestamp = input.timestamp;
-                    upsertCheckpoint(summaryMatch, this.stateDir);
-                    bumpDedupStats(true, this.stateDir);
-                    // Deduped: whole original region discarded, nothing new stored.
-                    addTokensSaved(origTokens, this.stateDir);
-                    const r = {
-                        checkpoint: summaryMatch,
-                        deduped: true,
-                        reason: "summaryHash",
-                    };
-                    this.record("L0", "deduped", "summaryHash", Date.now() - t0, 1, summaryMatch.checkpointId);
-                    onTier?.({ tier: "L0", status: "deduped", detail: "summaryHash" });
-                    return r;
-                }
-            }
-        }
-        // L0 did not collapse this region.
-        onTier?.({ tier: "L0", status: "passed" });
-        // 2b. L1 MinHash/LSH near-duplicate dedup (Sprint 11) — catches one-word
-        //     edits / rewordings that L0's exact hash misses. Cheap LSH bucket
-        //     retrieval → trigram verification (pg_trgm-equivalent) as the final gate.
-        //     Gated by L1_ENABLED (Sprint 14); MARK_ONLY_L1 records but doesn't collapse.
-        onTier?.({ tier: "L1", status: "scanning" });
-        if (cfg.L1_ENABLED) {
-            const l1 = this.findL1Duplicate(sessionId, input.regionText, all);
-            if (l1 && !cfg.MARK_ONLY_L1) {
-                l1.timestamp = input.timestamp;
-                upsertCheckpoint(l1, this.stateDir);
-                bumpDedupStats(true, this.stateDir);
-                const r = { checkpoint: l1, deduped: true, reason: "l1MinHash" };
-                this.record("L1", "deduped", "l1MinHash", Date.now() - t0, 1, l1.checkpointId);
-                onTier?.({ tier: "L1", status: "deduped", detail: "l1MinHash" });
-                return r;
-            }
-            if (l1 && cfg.MARK_ONLY_L1)
-                markOnly = "L1";
-        }
-        onTier?.({ tier: "L1", status: "passed" });
-        // 3. L2 semantic dedup — catches near-identical / semantically-similar regions
-        //    via cosine over the embedding. topicSummary is used for summaryHash dedup
-        //    (tier 2); the vector index is keyed on the original region for backward-
-        //    compat search semantics. Threshold from cfg (L2_COSINE trigram honest
-        //    firing point). QA #13 timeout guard: if the O(n) scan exceeds the budget,
-        //    degrade to "store without dedup this pass" so we never lose a checkpoint.
-        //    Gated by L2_ENABLED (Sprint 14); MARK_ONLY_L2 records but doesn't collapse.
-        const SIMILARITY_BUDGET_MS = cfg.SIMILARITY_BUDGET_MS;
-        const simThreshold = this.l2Threshold; // from cfg.L2_COSINE (default 0.85 trigram)
-        const embedding = this.embedder.embed(input.regionText);
-        onTier?.({ tier: "L2", status: "scanning" });
-        if (cfg.L2_ENABLED && all.length > 0) {
-            const start = Date.now();
-            let timedOut = false;
-            const nearest = all.reduce((best, cp) => {
-                if (!timedOut && Date.now() - start > SIMILARITY_BUDGET_MS)
-                    timedOut = true;
-                if (timedOut)
-                    return best;
-                const sim = cosineSimilarity(embedding, cp.embedding);
-                return sim > best.sim ? { checkpoint: cp, sim } : best;
-            }, { checkpoint: all[0], sim: -1 });
-            if (!timedOut && nearest.sim >= simThreshold) {
-                if (!cfg.MARK_ONLY_L2) {
-                    // Near-identical — update timestamp on existing checkpoint
-                    nearest.checkpoint.timestamp = input.timestamp;
-                    upsertCheckpoint(nearest.checkpoint, this.stateDir);
-                    bumpDedupStats(true, this.stateDir);
-                    // Deduped: whole original region discarded, nothing new stored.
-                    addTokensSaved(origTokens, this.stateDir);
-                    const r = {
-                        checkpoint: nearest.checkpoint,
-                        deduped: true,
-                        reason: "contentSimilarity",
-                    };
-                    this.record("L2", "deduped", "contentSimilarity", Date.now() - t0, nearest.sim, nearest.checkpoint.checkpointId);
-                    onTier?.({
-                        tier: "L2",
-                        status: "deduped",
-                        detail: nearest.sim.toFixed(2),
-                    });
-                    return r;
-                }
-                markOnly = "L2";
-            }
-            onTier?.({
-                tier: "L2",
-                status: "passed",
-                detail: `best ${nearest.sim.toFixed(2)}`,
-            });
-        }
-        // 4. Genuinely new — create checkpoint
-        const checkpointId = nextCheckpointId(sessionId, this.stateDir);
-        const checkpoint = {
-            checkpointId,
-            sessionId,
-            repoId: this.repoId,
-            summary: input.summary,
-            topicSummary: input.topicSummary,
-            summaryHash,
-            keyDecisions: input.keyDecisions ?? [],
-            nextSteps: input.nextSteps ?? [],
-            filesModified: input.filesModified ?? [],
-            tokenEstimate: input.tokenEstimate ?? 0,
-            originalTokenEstimate: input.originalTokenEstimate,
-            regionHash,
-            contentHash: digest.contentHash,
-            contentHash2: digest.contentHash2,
-            contentHashVersion: digest.contentHashVersion,
-            normalizedText: digest.normalizedText,
-            compressedOriginal: compressSmart(Buffer.from(input.regionText, "utf-8"), input.compressionPressure),
-            embedding,
-            timestamp: input.timestamp,
-        };
-        // Persistence is SQLite (store/sqlite.ts). upsertCheckpoint keeps the
-        // idempotent-by-id semantics the old JSON append implied.
-        upsertCheckpoint(checkpoint, this.stateDir);
-        // Cumulative "tokens saved" counter (per-repo SQLite meta). For a NEW
-        // checkpoint the saved amount is (original − stored); for a deduped add the
-        // whole original region is discarded (handled in the deduped return paths
-        // below). Survives sessions and travels with the repo.
-        const stored = input.tokenEstimate ?? 0;
-        addTokensSaved(Math.max(0, origTokens - stored), this.stateDir);
-        // L1: persist this checkpoint's MinHash signature + LSH buckets so future
-        // near-duplicate inserts can find it. Deterministic given the seed.
-        const sig = minhashSignature(input.regionText);
-        upsertMinhashSignature(checkpointId, sessionId, SIGNATURE_VERSION, sig, this.stateDir);
-        insertLshBuckets(checkpointId, sessionId, SIGNATURE_VERSION, lshBands(sig, sessionId, SIGNATURE_VERSION), this.stateDir);
-        // Bloom accelerator: record the new content_hash so a future add() can short-
-        // circuit the scan on a hit (still confirmed by the SELECT-based `all` above).
-        bloom.add(digest.contentHash);
-        saveBloom(this.stateDir);
-        // Track the region hash in session state for fast sentinel checks.
-        const state = loadSessionState(sessionId, this.stateDir);
-        if (!state.storedRegionHashes.includes(regionHash)) {
-            state.storedRegionHashes.push(regionHash);
-            saveSessionState(sessionId, state, this.stateDir);
-        }
-        // A new checkpoint. If a tier matched while MARK_ONLY, record that (the
-        // decision fired but we intentionally did not collapse).
-        if (markOnly) {
-            this.record(markOnly, "mark_only", "mark_only", Date.now() - t0);
-        }
-        else {
-            this.record("L0", "new", undefined, Date.now() - t0);
-        }
-        // Cumulative store-wide dedup accounting (attempt, not collapsed).
-        bumpDedupStats(false, this.stateDir);
-        onTier?.({ tier: "new", status: "stored" });
-        return { checkpoint, deduped: false };
-    }
-    /**
-     * L1 near-duplicate lookup: MinHash → LSH candidate retrieval → trigram verify.
-     * Returns the matching checkpoint or undefined. Bounded by a 100-candidate cap
-     * and a 20ms verify budget (QA #7/#15) so it never hangs a large session.
-     */
-    findL1Duplicate(sessionId, regionText, all) {
-        if (all.length === 0)
-            return undefined;
-        const sig = minhashSignature(regionText);
-        if (sig.length !== NUM_HASHES)
-            return undefined;
-        const bands = lshBands(sig, sessionId, SIGNATURE_VERSION);
-        // Cheap candidate retrieval (single query, capped). Exclude nothing yet —
-        // the new checkpoint has no id, so pass a sentinel that never matches.
-        const candidateIds = lshCandidateChunks(bands, sessionId, "__new__", this.stateDir, 100);
-        if (candidateIds.length === 0)
-            return undefined;
-        const byId = new Map(all.map((cp) => [cp.checkpointId, cp]));
-        const VERIFY_BUDGET_MS = 20;
-        const start = Date.now();
-        for (const id of candidateIds) {
-            if (Date.now() - start > VERIFY_BUDGET_MS)
-                break; // QA #15: abort → "not dup"
-            const cand = byId.get(id);
-            if (!cand)
-                continue;
-            const candText = cand.normalizedText ?? cand.summary ?? "";
-            if (isNearDuplicate(regionText, candText))
-                return cand;
-        }
-        return undefined;
+        return addCheckpoint(this, input);
     }
 }

package/dist/src/vectorStore/dedup-audit.js

@@ -0,0 +1,104 @@
+/**
+ * dedup-audit.ts — durable audit trail for dedup tier decisions
+ * (external-audit item #2).
+ *
+ * Before this module a tier decision existed only as the in-process `onTier`
+ * callback that paints the live UI; nothing survived the process, so an
+ * operator could not answer "which layer collapsed this region, onto what, at
+ * what similarity?" — the inputs needed to tune the thresholds in
+ * config/dedup.ts. Here each decision is appended to the repo's events.log as
+ * one structured JSON line (see `DedupAuditEvent` below).
+ *
+ * The event type and its append helper live HERE rather than in monitoring.ts:
+ * monitoring.ts already owns three concerns (decision events, the dashboard.json
+ * metrics snapshot, FP alerting) and sits close to its 300-line soft limit, so
+ * co-locating the shape with the only recorder that produces it keeps both files
+ * under the headroom gate. monitoring.ts re-exports both for callers (and the
+ * dashboard SSE tail) that treat it as the events.log barrel.
+ *
+ * Design constraints:
+ *  - PURE INSTRUMENTATION. Nothing in this file may influence a dedup outcome.
+ *  - Best-effort/non-fatal: `logDedupAudit` swallows IO errors, and the emitter
+ *    itself is wrapped so a malformed field can never break add().
+ *  - Honest fields only: a value is emitted only where the caller actually
+ *    computed it. L0/L1 are hash/verify tiers and pass no `similarity`.
+ *  - Signal, not chatter: callers emit on DECISIONS (a match, a scored
+ *    candidate, the final outcome), never on every "scanning" transition.
+ *  - Flag-gated by cfg.DEDUP_AUDIT (default ON; OFF writes nothing at all).
+ *
+ * PREVENT-PI-004: local filesystem append only, no network.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { defaultEventsPath } from "../monitoring.js";
+/**
+ * Append one audit event to events.log (best-effort, never throws).
+ *
+ * Same append-one-JSON-line contract as monitoring.ts's logDecision — an
+ * unwritable path is swallowed so instrumentation can never break add().
+ */
+export function logDedupAudit(path, ev) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, `${JSON.stringify(ev)}\n`, "utf-8");
+    }
+    catch {
+        /* best-effort — never break the extension on a log failure */
+    }
+}
+/** Build a recorder bound to one add() cascade. */
+export function dedupAuditRecorder(ctx, scope) {
+    const base = {
+        sessionId: scope.sessionId,
+        originalTokenEstimate: scope.originalTokenEstimate,
+        tokenEstimate: scope.tokenEstimate,
+    };
+    return {
+        deduped: (tier, matchedEntry, dedupReason, similarity) => emitDedupAudit(ctx, {
+            ...base,
+            tier,
+            status: "deduped",
+            matchedEntry,
+            dedupReason,
+            ...(similarity === undefined ? {} : { similarity }),
+        }),
+        passed: (tier, matchedEntry, similarity) => emitDedupAudit(ctx, {
+            ...base,
+            tier,
+            status: "passed",
+            matchedEntry,
+            similarity,
+        }),
+        stored: (storedEntry, dedupReason, tokenEstimate) => emitDedupAudit(ctx, {
+            ...base,
+            tier: "new",
+            status: "stored",
+            storedEntry,
+            dedupReason,
+            tokenEstimate,
+        }),
+    };
+}
+/**
+ * Append one dedup decision to events.log.
+ *
+ * Resolves the target path from the explicit `eventsPath` when a caller opted
+ * in (Sprint 14 monitoring / tests), otherwise from the store's own per-repo
+ * state dir — production never passes `eventsPath`, so defaulting is what makes
+ * the audit trail actually exist on a real device.
+ */
+export function emitDedupAudit(ctx, input) {
+    if (!ctx.auditEnabled)
+        return;
+    try {
+        const path = ctx.eventsPath ?? defaultEventsPath(ctx.stateDir);
+        logDedupAudit(path, {
+            type: "dedup_audit",
+            ts: new Date().toISOString(),
+            ...input,
+        });
+    }
+    catch {
+        /* instrumentation must never break the add() path */
+    }
+}

package/dist/src/vectorStore.js

@@ -8,6 +8,7 @@
  * "./vectorStore.js" are unchanged.
  */
 export { VectorStore } from "./vectorStore/class.js";
+export { addCheckpoint } from "./vectorStore/add.js";
 export { computeRegionHash } from "./vectorStore/hash.js";
 export { L2_ENABLED, } from "./vectorStore/types.js";
 // Re-exports (back-compat): existing call sites keep importing from "./vectorStore.js"

package/dist/vector-cortex/heal/_acceptance-fixture.js

@@ -0,0 +1,56 @@
+/**
+ * heal/_acceptance-fixture.ts — conformance fixture I/O for VC6A closure
+ * optimization acceptance rows.
+ *
+ * Reads the v2 conformance manifest + the per-sprint closure-optimization
+ * fixture files, and exposes the `HealFx` shape the acceptance aggregator
+ * drives. No mocks/stubs: the fixtures are the committed canonical corpus, fed
+ * verbatim into `closeSelection` → `optimizeClosure` → `verifyProof`.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import assert from "node:assert/strict";
+const HERE = dirname(fileURLToPath(import.meta.url));
+function repoRoot(from) {
+    let dir = from;
+    for (let i = 0; i < 8; i++) {
+        if (existsSync(join(dir, "conformance", "vector-cortex")))
+            return dir;
+        const next = dirname(dir);
+        if (next === dir)
+            break;
+        dir = next;
+    }
+    throw new Error("conformance corpus not found above " + from);
+}
+export const REPO_ROOT = repoRoot(HERE);
+export const V2 = join(REPO_ROOT, "conformance", "vector-cortex", "v2");
+export function readManifest() {
+    return JSON.parse(readFileSync(join(V2, "manifest.json"), "utf8"));
+}
+function readFixture(id, prefix) {
+    const m = readManifest();
+    const row = m.fixtures.find((f) => f.id === id && f.path.startsWith(`${prefix}/`));
+    assert.ok(row, `fixture ${id} registered under ${prefix}/ in manifest`);
+    return JSON.parse(readFileSync(join(V2, row.path), "utf8"));
+}
+export function healFixture(id) {
+    return readFixture(id, "closure-optimization");
+}
+/** Flag-pinned wrapper: VC6A gated by MEGACOMPACT_VC6A (defaults ON). */
+export function withFlagsOn(fn) {
+    return () => {
+        const saved = process.env.MEGACOMPACT_VC6A;
+        process.env.MEGACOMPACT_VC6A = "1";
+        try {
+            fn();
+        }
+        finally {
+            if (saved === undefined)
+                delete process.env.MEGACOMPACT_VC6A;
+            else
+                process.env.MEGACOMPACT_VC6A = saved;
+        }
+    };
+}

package/dist/vector-cortex/heal/closure-metrics.js

@@ -0,0 +1,66 @@
+/**
+ * vector-cortex/heal/closure-metrics.ts — VC6A closure proof metrics + handoff.
+ *
+ * Pure read-only derivations over a `ClosureProofV2`: traversal savings (the
+ * sprint's >=20% median acceptance bar) and the `RestoreHintV1` list VC6B
+ * consumes. Extracted from `closure-opt.ts` (delegate-shell) to keep the core
+ * reduction algorithm under the 300-line soft limit.
+ *
+ * PURE / DETERMINISTIC / LOCAL: no storage, no clock, no network (PREVENT-PI-004
+ * / PREVENT-011). Identity only — never source bytes or prompt text
+ * (SECURITY_PRIVACY).
+ */
+/** Bytewise id comparator — matches `closure-opt.ts` / `reconstruct/closure.ts`. */
+function byBytes(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Anchor id set from a graph (matches `closure-opt.ts`). */
+function anchorIds(graph) {
+    return new Set(graph.nodes.filter((n) => n.anchor === true).map((n) => n.id));
+}
+/**
+ * Traversal savings as a fraction in [0,1]: how much of the conservative edge
+ * walk the optimized plan avoids. A plan with nothing to remove scores 0 (not a
+ * failure — a chain graph is already minimal). The sprint's acceptance bar is a
+ * >=20% MEDIAN over the corpus, never a per-graph floor.
+ */
+export function traversalSavings(proof) {
+    if (proof.conservativeTraversals === 0)
+        return 0;
+    const saved = proof.conservativeTraversals - proof.optimizedTraversals;
+    return saved / proof.conservativeTraversals;
+}
+/**
+ * Derive the `RestoreHintV1` list VC6B consumes (the sprint's declared handoff:
+ * "VC6B receives missing-source hints and proof").
+ *
+ * One hint per selected node that a RETAINED edge reaches, naming the cheapest
+ * (bytewise-first) retained prerequisite and whether the node is protected.
+ * Identity only — never source bytes or prompt text (SECURITY_PRIVACY).
+ */
+export function restoreHints(proof, graph) {
+    const anchors = anchorIds(graph);
+    const best = new Map();
+    for (const row of proof.rows) {
+        if (row.decision !== "retained")
+            continue;
+        const reason = row.reason;
+        const existing = best.get(row.to);
+        if (existing === undefined || byBytes(row.from, existing.from) < 0) {
+            best.set(row.to, { from: row.from, reason });
+        }
+    }
+    const hints = [];
+    for (const nodeId of [...proof.selected].sort(byBytes)) {
+        const hit = best.get(nodeId);
+        const isToolPair = proof.retainedEdges.some((e) => e.kind === "tool-pair" && (e.from === nodeId || e.to === nodeId));
+        hints.push({
+            schema: "restore-hint-v1",
+            nodeId,
+            viaEdgeFrom: hit?.from,
+            protectedNode: anchors.has(nodeId) || isToolPair,
+            reason: hit?.reason ?? (anchors.has(nodeId) ? "anchor" : "no-alternate-path"),
+        });
+    }
+    return hints;
+}