pi-mega-compact 0.20.6 → 0.20.8

package/src/vector-cortex/heal/proof.ts

@@ -0,0 +1,234 @@
+/**
+ * vector-cortex/heal/proof.ts — VC6A proof verifier (task 4).
+ *
+ * The optimizer (`closure-opt.ts`) is PURE and cheap, but a proof is cheap to
+ * LIE about: a buggy or tampered producer could ship a proof that removes an
+ * edge the conservative closure actually needs. The verifier does not trust the
+ * proof — it REPLAYS it against the conservative oracle from scratch.
+ *
+ * REPLAY. From the conservative `ClosureResult` we rebuild the requirement
+ * adjacency (`to ⇒ from` for `depends`, both directions for `tool-pair`) over
+ * the in-selection edges — exactly the relation `closure-opt` reduced over.
+ * For every row the proof claims to REMOVE, the verifier independently confirms
+ * the same alternate path exists. For every row it claims to RETAIN, it confirms
+ * the protection reason holds (or that no alternate path exists). Any row that
+ * fails its own predicate is a witness violation.
+ *
+ * SELECTED-SET DIVERGENCE (the cardinal sin). The proof must contain the SAME
+ * selected set as the conservative oracle, byte for byte. Closure optimization
+ * is allowed to make the plan cheaper, never smaller — so if the proof's
+ * `selected` differs from the oracle's, that is `HEAL_PROOF_SET_MISMATCH` and the
+ * repaired triad must fall back to mode B (the conservative closure) and
+ * ultimately C (VC5C's legacy prompt) if even that fails.
+ *
+ * PURE / DETERMINISTIC / LOCAL, like everything in `heal/`: no storage, no
+ * console, no clock, no network (PREVENT-PI-004 / PREVENT-011). The verifier
+ * reads only types and the two ClosureEdge/ClosureGraph/ClosureResult shapes.
+ */
+
+import type { ClosureGraph, ClosureResult } from "../reconstruct/types.js";
+import type {
+  ClosureProofRow,
+  ClosureProofV2,
+  HealFailureCode,
+  HealMode,
+  HealTriadOutcome,
+  ProofVerification,
+} from "./types.js";
+
+/** Bytewise id comparator — matches `closure-opt.ts` / `reconstruct/closure.ts`. */
+function byBytes(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** Requirement adjacency over an edge list, identical to `closure-opt`. */
+function requirementAdjacency(edges: readonly ClosureProofRow[]): Map<string, string[]> {
+  const adj = new Map<string, string[]>();
+  const add = (key: string, value: string): void => {
+    const list = adj.get(key);
+    if (list === undefined) adj.set(key, [value]);
+    else list.push(value);
+  };
+  for (const row of edges) {
+    if (row.kind === "contradicts") continue; // not a traversal edge
+    if (row.kind === "depends") add(row.to, row.from);
+    else if (row.kind === "tool-pair") {
+      add(row.to, row.from);
+      add(row.from, row.to);
+    }
+  }
+  for (const list of adj.values()) list.sort(byBytes);
+  return adj;
+}
+
+/** Does a detour `start ⇒ via ⇒ ... ⇒ target` exist, excluding the direct hop? */
+function alternatePathVia(
+  adj: ReadonlyMap<string, string[]>,
+  start: string,
+  target: string,
+): string | null {
+  for (const hop of (adj.get(start) ?? []).filter((n) => n !== target)) {
+    const seen = new Set<string>([start]);
+    const worklist: string[] = [hop];
+    while (worklist.length > 0) {
+      worklist.sort(byBytes);
+      const current = worklist.shift();
+      if (current === undefined) break;
+      if (current === target) return hop;
+      if (seen.has(current)) continue;
+      seen.add(current);
+      for (const next of adj.get(current) ?? []) {
+        if (!seen.has(next)) worklist.push(next);
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Verify a `ClosureProofV2` produced for an already-closed graph.
+ *
+ * Returns `{ ok: true, selected }` when the replay confirms the optimized plan is
+ * provably equivalent to the conservative closure — mode A may be used. On any
+ * divergence it returns `{ ok: false, codes }` listing every failure code; the
+ * caller routes to mode B (conservative) and, if that also fails, mode C (legacy,
+ * with `semanticLossStated`). The verifier is idempotent — replaying the same
+ * proof twice yields the same verdict, which `vc6a-acceptance.test.ts` asserts.
+ */
+export function verifyProof(
+  proof: ClosureProofV2,
+  conservative: ClosureResult,
+  graph?: ClosureGraph,
+): ProofVerification {
+  const codes: HealFailureCode[] = [];
+  const inSelection = new Set(conservative.selected);
+  const anchors = new Set(
+    (graph?.nodes ?? []).filter((n) => n.anchor === true).map((n) => n.id),
+  );
+
+  // 1. Selected-set divergence is the hard gate (task 4: HEAL_PROOF_SET_MISMATCH).
+  const oracleSelected = [...conservative.selected].sort(byBytes);
+  const proofSelected = [...proof.selected].sort(byBytes);
+  const selectedMatch =
+    oracleSelected.length === proofSelected.length &&
+    oracleSelected.every((id, i) => id === proofSelected[i]);
+  if (!selectedMatch) codes.push("HEAL_PROOF_SET_MISMATCH");
+
+  // 2. Re-check each row against its own predicate. For a removal, the witness
+  //    is validated against the OTHER rows (the reduced graph), so a removal
+  //    never justifies another's witness — this catches both a missing-witness
+  //    removal (HEAL-PROOF-003) and a protected edge that was removed
+  //    (HEAL_PROOF_PROTECTED_REMOVED).
+
+  for (const row of proof.rows) {
+    // Out-of-scope rows (touch an unselected node) should never have been
+    // emitted; treat as a witness violation so a malformed proof fails loudly.
+    if (!inSelection.has(row.from) || !inSelection.has(row.to)) {
+      codes.push("HEAL_PROOF_WITNESS_INVALID");
+      continue;
+    }
+    if (row.decision === "removed") {
+      // A removal MUST carry a witness and the witness MUST still validate
+      // against the OTHER rows (the reduced graph) — never the row itself, so a
+      // removal never justifies another's witness (matches the optimizer's
+      // exclusion rule).
+      if (row.via === undefined) {
+        codes.push("HEAL_PROOF_WITNESS_INVALID");
+        continue;
+      }
+      const others = proof.rows.filter((r) => r !== row);
+      const witness = alternatePathVia(requirementAdjacency(others), row.to, row.from);
+      if (witness === null) {
+        codes.push("HEAL_PROOF_WITNESS_INVALID");
+        continue;
+      }
+      if (anchors.has(row.from) || anchors.has(row.to)) {
+        // Topology says removable, but an anchor edge is NEVER removable.
+        codes.push("HEAL_PROOF_PROTECTED_REMOVED");
+        continue;
+      }
+      if (row.kind === "tool-pair" || row.kind === "contradicts") {
+        // Both are protected regardless of topology.
+        codes.push("HEAL_PROOF_PROTECTED_REMOVED");
+      }
+    } else {
+      // A retained plain depends edge that claims `no-alternate-path` but
+      // actually HAS one (through the other rows) is an internal inconsistency:
+      // the optimizer kept a removable edge without removing it. The proof is
+      // internally contradictory, so it fails replay.
+      if (row.kind === "depends" && row.reason === "no-alternate-path") {
+        const others = proof.rows.filter((r) => r !== row);
+        const hasPath = alternatePathVia(requirementAdjacency(others), row.to, row.from);
+        if (hasPath !== null) codes.push("HEAL_PROOF_WITNESS_INVALID");
+      }
+    }
+  }
+
+  // 3. Completeness: every in-selection edge the optimizer considered must appear
+  //    in the proof. A dropped row (the unique-injection test drops one) surfaces
+  //    as HEAL_PROOF_INCOMPLETE even if the remaining rows replay fine — the proof
+  //    must account for EVERY considered edge. `conservativeTraversals` is the
+  //    optimizer's own record of how many edges it fed through, so `rows.length`
+  //    must equal it exactly.
+  if (proof.rows.length < proof.conservativeTraversals) {
+    codes.push("HEAL_PROOF_INCOMPLETE");
+  }
+
+  if (codes.length === 0) {
+    return { ok: true, selected: proofSelected };
+  }
+  return { ok: false, codes: [...new Set(codes)] };
+}
+
+/**
+ * Drive the A/B/C resilient triad for one closure (task 5 wiring; VC6A exposes
+ * the decision; the actual selection/budget work is VC4C/VC5A respectively).
+ *
+ *  - A: the optimized proof verified cleanly → ship the optimized plan.
+ *  - B: proof rejected → fall back to the conservative VC4C closure (no opt).
+ *  - C: B also failed (should not happen for a sound conservative closure) →
+ *       state the legacy prompt path with `semanticLossStated`.
+ *
+ * This is PURE: it returns the verdict and which mode to use; it does not emit,
+ * store, or touch the network. The emit seam (`emit.ts`) consumes the outcome.
+ */
+export function selectHealMode(
+  proof: ClosureProofV2,
+  conservative: ClosureResult,
+  graph?: ClosureGraph,
+): HealTriadOutcome {
+  const verification = verifyProof(proof, conservative, graph);
+  if (verification.ok) {
+    return {
+      mode: "A" as HealMode,
+      proof,
+      selected: [...proof.selected],
+      codes: [],
+      semanticLossStated: false,
+    };
+  }
+  // Mode B: conservative closure is sound by construction (it is the oracle the
+  // proof was measured against). Use it directly.
+  return {
+    mode: "B" as HealMode,
+    proof: null,
+    selected: [...conservative.selected],
+    codes: verification.codes,
+    semanticLossStated: false,
+  };
+}
+
+/**
+ * Convenience for the rare B-failure path: if even the conservative oracle's
+ * selection cannot be honored, state the legacy prompt and MARK semantic loss.
+ * Mode C is the last resort and the only place semantic loss is ever admitted.
+ */
+export function legacyFallback(conservative: ClosureResult, reason: HealFailureCode): HealTriadOutcome {
+  return {
+    mode: "C" as HealMode,
+    proof: null,
+    selected: [...conservative.selected],
+    codes: [reason, "HEAL_CLOSURE_REJECTED"],
+    semanticLossStated: true,
+  };
+}

package/src/vector-cortex/heal/types.ts

@@ -0,0 +1,226 @@
+/**
+ * vector-cortex/heal/types.ts — VC6A closure-optimization contract.
+ *
+ * Owns `ClosureProofV2` and `RestoreHintV1`.
+ *
+ * VC4C already performs the MANDATORY conservative closure (CONTRACTS §plan and
+ * closure): it recursively adds every `depends`/tool-pair predecessor to a fixed
+ * point, resolves contradictions, and preserves the anchor floor. VC6A does NOT
+ * re-close and does NOT change WHICH NODES ARE SELECTED — "VC6 only optimizes
+ * restoration/self-healing". It optimizes the PROOF EDGES of that already-closed
+ * graph by transitive reduction: an edge `a -> c` whose requirement is already
+ * carried by a path `a -> b -> c` is redundant and can be dropped from the
+ * traversal plan without changing the closed set.
+ *
+ * The optimization is therefore a claim, and a claim needs a receipt:
+ * `ClosureProofV2` records EVERY considered edge — retained or removed — with
+ * the reason. `proof.ts` replays those rows against the conservative VC4C oracle
+ * and rejects the optimization if the selected set diverges
+ * (`HEAL_PROOF_SET_MISMATCH`) or if a considered edge has no proof row
+ * (`HEAL_PROOF_INCOMPLETE`).
+ *
+ * PROTECTED EDGES ARE NEVER REMOVED. A tool-pair edge (PREVENT-PI-002), an edge
+ * touching an anchor node (PREVENT-PI-001's anchor floor), a
+ * contradiction-resolution edge, and a SOLE dependency edge (the only edge that
+ * pulls its prerequisite in) are all retained unconditionally, even when an
+ * alternate path exists. Only a redundant `depends` edge may go.
+ *
+ * Pure types + registered conformance IDs: no storage, no console, no network
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import type { ClosureEdge, ClosureEdgeKind } from "../reconstruct/types.js";
+
+/**
+ * Why an edge survived the reduction. Ordered from strongest guarantee to
+ * weakest:
+ *
+ *   - `tool-pair`      — a tool call/result pair is atomic and never split
+ *                        (PREVENT-PI-002), so its edge is structural, not
+ *                        merely a traversal hint;
+ *   - `anchor`         — an endpoint is in the preserved anchor floor
+ *                        (PREVENT-PI-001), so the edge documents a floor
+ *                        obligation and is never elided;
+ *   - `contradiction`  — a `contradicts` edge participates in resolution; the
+ *                        resolver reads it directly, so removing it would
+ *                        change the resolved set, not just the traversal;
+ *   - `sole-dependency`— the ONLY edge requiring this prerequisite; removing it
+ *                        would drop the prerequisite from the closure;
+ *   - `no-alternate-path` — a plain `depends` edge with no `a -> ... -> c`
+ *                        detour, so it still carries its own requirement.
+ */
+export type RetainReason =
+  | "tool-pair"
+  | "anchor"
+  | "contradiction"
+  | "sole-dependency"
+  | "no-alternate-path";
+
+/**
+ * Why an edge was removed. Exactly one reason exists today — a redundant
+ * `depends` edge shadowed by a longer path — and it is spelled out rather than
+ * implied so a proof row can never be "removed, reason unstated"
+ * (HEAL-PROOF-003).
+ */
+export type RemoveReason = "transitively-implied";
+
+/**
+ * One proof row: an edge the optimizer CONSIDERED, and what it decided.
+ *
+ * Every considered edge produces exactly one row — including retained ones. A
+ * proof that lists only removals cannot be replayed against the oracle, because
+ * the verifier could not distinguish "retained deliberately" from "never
+ * examined" (the `HEAL_PROOF_INCOMPLETE` injection).
+ *
+ * `via` names the intermediate vertex of the witnessing path `from -> via -> to`
+ * for a removal. It is REQUIRED on a removal row (the witness IS the reason) and
+ * absent on a retention row.
+ */
+export interface ClosureProofRow {
+  readonly from: string;
+  readonly to: string;
+  readonly kind: ClosureEdgeKind;
+  readonly decision: "retained" | "removed";
+  /** The stated reason. A removal without a reason fails verification. */
+  readonly reason: RetainReason | RemoveReason;
+  /** Witness vertex of the implying path (removals only). */
+  readonly via?: string;
+}
+
+/**
+ * The optimization receipt (`ClosureProofV2`).
+ *
+ * `selected` is copied UNCHANGED from the conservative VC4C closure — the
+ * optimizer never edits it, and the verifier re-derives it independently to
+ * prove that. `retainedEdges`/`removedEdges` are the optimized traversal plan;
+ * `rows` is the full considered-edge ledger, sorted deterministically.
+ *
+ * `conservativeTraversals` / `optimizedTraversals` are the edge-walk counts of
+ * the conservative and reduced plans; the sprint's acceptance bar is a >=20%
+ * median reduction across the fixture corpus, measured from these two numbers.
+ */
+export interface ClosureProofV2 {
+  readonly schema: "closure-proof-v2";
+  readonly sessionId: string;
+  /** The closed selection, byte-identical to the conservative VC4C result. */
+  readonly selected: readonly string[];
+  /** Edges kept in the optimized traversal plan (sorted). */
+  readonly retainedEdges: readonly ClosureEdge[];
+  /** Edges dropped as transitively implied (sorted). */
+  readonly removedEdges: readonly ClosureEdge[];
+  /** One row per CONSIDERED edge — retained and removed alike (sorted). */
+  readonly rows: readonly ClosureProofRow[];
+  /** Edge walks the conservative plan performs. */
+  readonly conservativeTraversals: number;
+  /** Edge walks the optimized plan performs. */
+  readonly optimizedTraversals: number;
+}
+
+/**
+ * `RestoreHintV1` — the reader-only hint VC6B consumes to fetch missing sources.
+ *
+ * A hint names a node the optimized plan still needs and the CHEAPEST retained
+ * edge that reaches it (`viaEdgeFrom`), so the restorer can walk one edge rather
+ * than re-deriving the closure. `protectedNode` marks a node whose edge set was
+ * retained for a hard-safety reason (tool pair / anchor), telling VC6B to treat
+ * it as non-negotiable.
+ *
+ * Reader-only by contract: node IDENTITY plus the traversal hint, NEVER source
+ * bytes or prompt text (SECURITY_PRIVACY — the exact ledger is not training
+ * data and is never rendered through a diagnostic surface).
+ */
+export interface RestoreHintV1 {
+  readonly schema: "restore-hint-v1";
+  readonly nodeId: string;
+  /** The retained edge's prerequisite endpoint, if the node has one. */
+  readonly viaEdgeFrom?: string;
+  /** True when the node is anchor-floor or tool-pair protected. */
+  readonly protectedNode: boolean;
+  /** Deterministic reason label mirroring the retention reason. */
+  readonly reason: RetainReason;
+}
+
+/** VC6A failure codes (registered HEAL codes). */
+export type HealFailureCode =
+  /** The replayed selected set diverges from the conservative oracle. */
+  | "HEAL_PROOF_SET_MISMATCH"
+  /** A considered edge has no proof row (or a removal states no reason). */
+  | "HEAL_PROOF_INCOMPLETE"
+  /** A proof row removes an edge that is protected and must be retained. */
+  | "HEAL_PROOF_PROTECTED_REMOVED"
+  /** A removal row's witness path `from -> via -> to` does not exist. */
+  | "HEAL_PROOF_WITNESS_INVALID"
+  /** The underlying conservative closure itself failed — nothing to optimize. */
+  | "HEAL_CLOSURE_REJECTED";
+
+/**
+ * Verifier verdict. `ok:true` means the optimized plan is provably equivalent to
+ * the conservative closure and mode A may be used. `ok:false` routes to mode B
+ * (the conservative VC4C closure, unoptimized) — never to a partially reduced
+ * plan.
+ */
+export type ProofVerification =
+  | { readonly ok: true; readonly selected: readonly string[] }
+  | { readonly ok: false; readonly codes: readonly HealFailureCode[] };
+
+/**
+ * The triad mode VC6A selects (TRIAD_RESILIENCE).
+ *
+ *   A = the optimized closure whose proof verified;
+ *   B = the VC4C conservative closure, forced by proof rejection — an
+ *       INDEPENDENT algorithm (fixed-point worklist, no reduction) reached by a
+ *       different code path in `reconstruct/closure.ts`;
+ *   C = the legacy prompt, forced when BOTH closure paths fail (an unresolved
+ *       contradiction or a structurally invalid graph), stating its loss of old
+ *       semantic context.
+ */
+export type HealMode = "A" | "B" | "C";
+
+/** The outcome of the VC6A triad selection. */
+export interface HealTriadOutcome {
+  readonly mode: HealMode;
+  /** The verified optimized proof (mode A only). */
+  readonly proof: ClosureProofV2 | null;
+  /** The selected node set actually used (empty only in mode C). */
+  readonly selected: readonly string[];
+  readonly codes: readonly HealFailureCode[];
+  /** Set only in mode C (TRIAD_RESILIENCE — "C states its semantic loss"). */
+  readonly semanticLossStated: boolean;
+}
+
+/** The two structured events the VC6A reporter emits. */
+export type HealEventName =
+  | "vector_cortex_closure_optimized"
+  | "vector_cortex_closure_proof_rejected";
+
+/**
+ * Aggregate-only closure-proof metrics for the dashboard (counts only, never
+ * node ids, edges, or source payloads).
+ */
+export interface HealMetricsV1 {
+  readonly optimizations: number;
+  readonly proofRejections: number;
+  readonly retainedEdgeTotal: number;
+  readonly removedEdgeTotal: number;
+  readonly conservativeTraversalTotal: number;
+  readonly optimizedTraversalTotal: number;
+}
+
+/**
+ * Registered HEAL conformance ID range (HEAL-001..015). The acceptance test
+ * reads these rows from the v2 manifest and asserts each returns its manifest
+ * `ok`/`code`.
+ */
+export const HEAL_IDS: readonly string[] = Array.from(
+  { length: 15 },
+  (_v, i) => `HEAL-${String(i + 1).padStart(3, "0")}`,
+);
+
+/** Named VC6A conformance assertions (the sprint's headline rows). */
+export const HEAL_NAMED_IDS = [
+  "HEAL-REDUCE-001",
+  "HEAL-PROTECT-002",
+  "HEAL-PROOF-003",
+] as const;
+
+export type { ClosureEdge, ClosureEdgeKind };

package/src/vectorStore/add-l0.ts

@@ -0,0 +1,152 @@
+/**
+ * add-l0.ts — the L0 exact-match tier of the dedup cascade.
+ *
+ * L0 is three exact-hash probes sharing one enable flag and one MARK_ONLY flag:
+ *   1. contentHash — normalized dual-hash, bloom-accelerated (Sprint 9/10)
+ *   2. regionHash  — the legacy pre-normalization hash (backward-compat)
+ *   3. summaryHash — same-topic incremental compactions
+ *
+ * Split out of add.ts so both files stay under the 300-line src/ soft limit.
+ * The tier is a pure decision: it either produces a collapse (returning the
+ * matched result) or reports the fall-through, and it never writes a new
+ * checkpoint — that stays in add.ts.
+ *
+ * All three probes are hash comparisons, so none of them computes a similarity
+ * score and none is invented for the audit trail.
+ */
+import { createHash } from "node:crypto";
+import type { StoredCheckpoint } from "../store.js";
+import type { ContentDigest } from "../dedup/digest.js";
+import { upsertCheckpoint, addTokensSaved, bumpDedupStats } from "../store/sqlite.js";
+import type { BloomFilter } from "../store/bloom.js";
+import type { DedupAuditRecorder } from "./dedup-audit.js";
+import type { AddInput, AddResult } from "./types.js";
+import type { VectorStore } from "./class.js";
+
+/** Everything the L0 tier needs from the enclosing add() cascade. */
+export interface L0Context {
+	store: VectorStore;
+	input: AddInput;
+	/** Checkpoints already stored for this session. */
+	all: StoredCheckpoint[];
+	/** Normalized content digest of the incoming region. */
+	digest: ContentDigest;
+	/** Legacy region hash of the incoming region. */
+	regionHash: string;
+	/** SHA-256 of the topic summary, when one was supplied. */
+	summaryHash?: string;
+	/** Tokens the original region occupied (the dedup "saved" base). */
+	origTokens: number;
+	/** Warm bloom accelerator for the content-hash probe. */
+	bloom: BloomFilter;
+	/** Cascade start time, for the monitoring latency figure. */
+	t0: number;
+	audit: DedupAuditRecorder;
+}
+
+/**
+ * Outcome of the L0 tier.
+ *
+ * `result` set → the tier collapsed the region and add() returns immediately.
+ * `markOnly` set → a probe matched but MARK_ONLY policy said store anyway, so
+ * the cascade continues and records the mark at the end.
+ */
+export interface L0Outcome {
+	result?: AddResult;
+	markOnly: "L0" | null;
+}
+
+/** Run the L0 exact-match tier. */
+export function runL0Tier(ctx: L0Context): L0Outcome {
+	const { store, input, all, digest, regionHash, origTokens, bloom, t0, audit } = ctx;
+	const cfg = store.cfg;
+	const onTier = input.onTier;
+	let markOnly: "L0" | null = null;
+
+	// 0. 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` here.
+	//    MARK_ONLY_L0 records the decision but does not collapse.
+	onTier?.({ tier: "L0", status: "scanning" });
+	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, store.stateDir);
+				bumpDedupStats(true, store.stateDir);
+				// Deduped: whole original region discarded, nothing new stored.
+				addTokensSaved(origTokens, store.stateDir);
+				store.record("L0", "deduped", "contentHash", Date.now() - t0, 1, contentMatch.checkpointId);
+				audit.deduped("L0", contentMatch.checkpointId, "contentHash");
+				onTier?.({ tier: "L0", status: "deduped", detail: "contentHash" });
+				return {
+					result: { checkpoint: contentMatch, deduped: true, reason: "contentHash" },
+					markOnly,
+				};
+			}
+		}
+	}
+
+	// 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, store.stateDir);
+				// Deduped: whole original region discarded, nothing new stored.
+				addTokensSaved(origTokens, store.stateDir);
+				store.record("L0", "deduped", "regionHash", Date.now() - t0, 1, regionMatch.checkpointId);
+				audit.deduped("L0", regionMatch.checkpointId, "regionHash");
+				onTier?.({ tier: "L0", status: "deduped", detail: "regionHash" });
+				return {
+					result: { checkpoint: regionMatch, deduped: true, reason: "regionHash" },
+					markOnly,
+				};
+			}
+		}
+	}
+
+	// 2. SummaryHash dedup — catches same-topic incremental compactions.
+	if (ctx.summaryHash && cfg.L0_ENABLED) {
+		const summaryMatch = all.find((cp) => cp.summaryHash === ctx.summaryHash);
+		if (summaryMatch) {
+			if (cfg.MARK_ONLY_L0) {
+				markOnly = "L0"; // fall through
+			} else {
+				summaryMatch.timestamp = input.timestamp;
+				upsertCheckpoint(summaryMatch, store.stateDir);
+				bumpDedupStats(true, store.stateDir);
+				// Deduped: whole original region discarded, nothing new stored.
+				addTokensSaved(origTokens, store.stateDir);
+				store.record("L0", "deduped", "summaryHash", Date.now() - t0, 1, summaryMatch.checkpointId);
+				audit.deduped("L0", summaryMatch.checkpointId, "summaryHash");
+				onTier?.({ tier: "L0", status: "deduped", detail: "summaryHash" });
+				return {
+					result: { checkpoint: summaryMatch, deduped: true, reason: "summaryHash" },
+					markOnly,
+				};
+			}
+		}
+	}
+	// L0 did not collapse this region.
+	onTier?.({ tier: "L0", status: "passed" });
+	return { markOnly };
+}
+
+/** SHA-256 of the topic summary (full 64-hex; 16-hex was collision-prone). */
+export function computeSummaryHash(topicSummary?: string): string | undefined {
+	return topicSummary
+		? createHash("sha256").update(topicSummary).digest("hex")
+		: undefined;
+}

package/src/vectorStore/add-l1.ts

@@ -0,0 +1,57 @@
+/**
+ * add-l1.ts — the L1 MinHash/LSH near-duplicate lookup.
+ *
+ * Split out of add.ts to keep both files under the 300-line src/ soft limit.
+ * L1 catches the one-word edits and rewordings L0's exact hashes miss: a cheap
+ * LSH bucket retrieval narrows the field, then a trigram verification
+ * (pg_trgm-equivalent) is the final gate. The verify is boolean, so the tier
+ * produces no similarity score.
+ */
+import type { StoredCheckpoint } from "../store.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 { lshCandidateChunks } from "../store/sqlite.js";
+import type { VectorStore } from "./class.js";
+
+export /**
+ * 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.
+ */
+function findL1Duplicate(
+	store: VectorStore,
+	sessionId: string,
+	regionText: string,
+	all: StoredCheckpoint[],
+): StoredCheckpoint | undefined {
+	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__",
+		store.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;
+}