pi-mega-compact 0.20.5 → 0.20.7

package/src/vectorStore/class.ts

@@ -7,9 +7,8 @@
  * 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 type { Embedder } from "../embedder.js";
-import { cosineSimilarity, defaultEmbedder } from "../embedder.js";
+import { defaultEmbedder } from "../embedder.js";
 import {
 	loadDedupConfig,
 	type DedupConfigShape,
@@ -17,47 +16,28 @@ import {
 } from "../config/dedup.js";
 import { logDecision } from "../monitoring.js";
 import { repoKey } from "../store/repoKey.js";
-import type { StoredCheckpoint } from "../store.js";
-import { getStateDir, normalizeSessionId, compressSmart } from "../store.js";
-import { computeContentDigest } from "../dedup/digest.js";
+import { getStateDir } from "../store.js";
 import type { RaptorTree } from "../dedup/raptor/tree.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 { openBloom } from "../store/bloom.js";
 import { migrateJsonToSqlite } from "../store/migrate.js";
-import { computeRegionHash } from "./hash.js";
+import { addCheckpoint } from "./add.js";
 import type { AddInput, AddResult } from "./types.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.
 	readonly embedder: Embedder;
 	readonly stateDir: string;
-	private readonly l2Threshold: number;
+	/** L2 semantic firing point (cfg.L2_COSINE, or a direct test override). */
+	readonly l2Threshold: number;
 	/** Single source of truth for tier flags + thresholds (Sprint 14). */
 	readonly cfg: DedupConfigShape;
 	/** Optional monitoring target (Sprint 14). Undefined → no monitoring. */
-	private readonly eventsPath?: string;
+	readonly eventsPath?: string;
 	/**
 	 * Repo key for the async PGlite vector index (Slice 2). We use the stateDir
 	 * itself as the repo id — it is already unique per repo and available here
@@ -132,302 +112,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: AddInput): AddResult {
-		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: DedupTier | null = 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: StoredCheckpoint = {
-			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.
-	 */
-	private findL1Duplicate(
-		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__",
-			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/src/vectorStore/dedup-audit.ts

@@ -0,0 +1,199 @@
+/**
+ * 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";
+
+/**
+ * One dedup decision, as persisted to events.log.
+ *
+ * `ts` is an ISO-8601 string (not the epoch millis DedupDecisionEvent uses):
+ * the dashboard SSE tail only forwards lines carrying a `type` discriminator,
+ * and its consumers parse the timestamp as a date. Optional fields are omitted
+ * rather than nulled — a missing `similarity` means the tier computed no score,
+ * which is itself the honest signal (L0/L1 are hash/verify tiers).
+ */
+export interface DedupAuditEvent {
+	/** SSE discriminator — the dashboard streams only typed lines. */
+	type: "dedup_audit";
+	/** ISO-8601 decision timestamp. */
+	ts: string;
+	/** Normalized session the region belongs to. */
+	sessionId: string;
+	/** Which layer produced the decision ("new" = nothing collapsed). */
+	tier: "L0" | "L1" | "L2" | "new";
+	/** What the layer decided. */
+	status: "deduped" | "passed" | "stored";
+	/** Checkpoint the region collapsed onto, or the nearest one scored. */
+	matchedEntry?: string;
+	/** Checkpoint created, when the outcome was a new write. */
+	storedEntry?: string;
+	/** Cosine similarity — present only where a tier actually scored. */
+	similarity?: number;
+	/** Why the decision went the way it did (e.g. "contentHash", "mark_only"). */
+	dedupReason?: string;
+	/** Tokens the original region occupied before compaction. */
+	originalTokenEstimate?: number;
+	/** Tokens the stored summary occupies. */
+	tokenEstimate?: number;
+}
+
+/**
+ * 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: string, ev: DedupAuditEvent): void {
+	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 */
+	}
+}
+
+/** The slice of VectorStore the audit emitter reads. */
+export interface DedupAuditContext {
+	/** Per-repo state dir — resolves the events.log the dashboard tails. */
+	readonly stateDir: string;
+	/** Explicit events.log override (tests / the Sprint-14 monitoring opt-in). */
+	readonly eventsPath?: string;
+	/** Whether the audit trail is enabled (cfg.DEDUP_AUDIT). */
+	readonly auditEnabled: boolean;
+}
+
+/** The decision payload a call site supplies; ts/type are filled in here. */
+export type DedupAuditInput = Omit<DedupAuditEvent, "type" | "ts">;
+
+/**
+ * The per-add() facts every decision in one cascade shares: which session, and
+ * the token accounting already computed by the caller.
+ */
+export interface DedupAuditScope {
+	sessionId: string;
+	/** Tokens the original region occupied (VectorStore.add's `origTokens`). */
+	originalTokenEstimate?: number;
+	/** Tokens the stored summary occupies (AddInput.tokenEstimate). */
+	tokenEstimate?: number;
+}
+
+/**
+ * A decision recorder bound to one add() cascade.
+ *
+ * `deduped` / `passed` / `stored` are the three shapes the cascade actually
+ * produces; binding them here keeps VectorStore.add's call sites to one line
+ * each (delegate-shell pattern) and keeps the field-honesty rules — which tier
+ * may carry a similarity, matched vs. created id — in a single place.
+ */
+export interface DedupAuditRecorder {
+	/** A tier collapsed the region onto `matchedEntry`. */
+	deduped(
+		tier: "L0" | "L1" | "L2",
+		matchedEntry: string,
+		dedupReason: string,
+		similarity?: number,
+	): void;
+	/** A tier scored a candidate but did not collapse (threshold near-miss). */
+	passed(
+		tier: "L0" | "L1" | "L2",
+		matchedEntry: string,
+		similarity: number,
+	): void;
+	/** Final outcome: nothing collapsed, a new checkpoint was written. */
+	stored(storedEntry: string, dedupReason: string, tokenEstimate: number): void;
+}
+
+/** Build a recorder bound to one add() cascade. */
+export function dedupAuditRecorder(
+	ctx: DedupAuditContext,
+	scope: DedupAuditScope,
+): DedupAuditRecorder {
+	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: DedupAuditContext,
+	input: DedupAuditInput,
+): void {
+	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/src/vectorStore.ts

@@ -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,

package/extensions/dashboard-client/dist/assets/VectorCortexTab-BWi3u_gp.js

@@ -1,2 +0,0 @@
-import{j as e,B as a,r as c}from"./index-i9oaPE0a.js";import{C as d,a as i,b as x,c as h}from"./card-C-DxXv1-.js";async function L(){const s=await fetch("/api/vector-cortex/evaluation");if(!s.ok)throw new Error(`vector-cortex evaluation: ${s.status}`);return s.json()}async function w(){const s=await fetch("/api/vector-cortex/health");if(!s.ok)throw new Error(`vector-cortex health: ${s.status}`);return s.json()}async function H(){const s=await fetch("/api/vector-cortex/topology");if(!s.ok)throw new Error(`vector-cortex topology: ${s.status}`);return s.json()}async function q(){const s=await fetch("/api/vector-cortex/query");if(!s.ok)throw new Error(`vector-cortex query: ${s.status}`);return s.json()}async function G(){const s=await fetch("/api/vector-cortex/shards");if(!s.ok)throw new Error(`vector-cortex shards: ${s.status}`);return s.json()}async function Q(){const s=await fetch("/api/vector-cortex/reconstruct");if(!s.ok)throw new Error(`vector-cortex reconstruct: ${s.status}`);return s.json()}async function W(){const s=await fetch("/api/vector-cortex/plans");if(!s.ok)throw new Error(`vector-cortex plans: ${s.status}`);return s.json()}async function z(){const s=await fetch("/api/vector-cortex/render");if(!s.ok)throw new Error(`vector-cortex render: ${s.status}`);return s.json()}async function J(s="default"){const o=await fetch(`/api/vector-cortex/ledger?session=${encodeURIComponent(s)}`);if(!o.ok)throw new Error(`vector-cortex ledger: ${o.status}`);return o.json()}async function K(s){const o=await fetch("/api/vector-cortex/breakers/reset",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({subsystem:s})});if(!o.ok)throw new Error(`vector-cortex reset: ${o.status}`);return o.json()}function t({label:s,value:o}){return e.jsxs("div",{children:[e.jsx("div",{className:"text-xs text-muted-foreground",children:s}),e.jsx("div",{className:"font-mono text-sm",children:o})]})}function U({view:s}){return e.jsxs(d,{children:[e.jsx(i,{children:e.jsxs("div",{className:"flex items-center justify-between",children:[e.jsx(x,{children:"Validated Prompt Renderer (VC5B)"}),s?.enabled?e.jsx(a,{variant:"success",children:"ACTIVE"}):e.jsx(a,{variant:"danger",children:"OFF"})]})}),e.jsx(h,{children:s?.enabled?e.jsxs(e.Fragment,{children:[e.jsxs("div",{className:"grid grid-cols-2 gap-4 md:grid-cols-4",children:[e.jsx(t,{label:"Render fixtures",value:String(s.renderCount)}),e.jsx(t,{label:"Provider profiles",value:String(s.providerCount)}),e.jsx(t,{label:"Known profiles",value:String(s.knownProfiles.length)})]}),e.jsx("div",{className:"mt-3 text-xs text-muted-foreground",children:"Reader-only render conformance route — no prompt text or session payloads exposed."})]}):e.jsx("div",{className:"vc-empty",children:"Renderer disabled (VC5B off)."})})]})}function Z({view:s}){return e.jsxs(d,{children:[e.jsx(i,{children:e.jsxs("div",{className:"flex items-center justify-between",children:[e.jsx(x,{children:"Plan Manifests (VC5A)"}),s?.enabled?e.jsx(a,{variant:"success",children:"ACTIVE"}):e.jsx(a,{variant:"danger",children:"OFF"})]})}),e.jsx(h,{children:s?.enabled?e.jsxs(e.Fragment,{children:[e.jsxs("div",{className:"grid grid-cols-2 gap-4 md:grid-cols-4",children:[e.jsx(t,{label:"DAG fixtures",value:String(s.dagCount)}),e.jsx(t,{label:"Plan fixtures",value:String(s.plannerCount)}),e.jsx(t,{label:"Plans exposed",value:String(s.plans.length)})]}),e.jsx("div",{className:"mt-3 text-xs text-muted-foreground",children:"Reader-only plan manifests only — no session payloads or prompt text. Per-run plan outputs are staged in-memory this sprint."})]}):e.jsx("div",{className:"vc-empty",children:"PromptDagV1 + budgeted planner disabled (VC5A off)."})})]})}function p({mode:s,count:o}){return e.jsxs("div",{className:"flex items-center justify-between border-b border-border/50 py-1 text-sm",children:[e.jsxs("span",{className:"text-muted-foreground",children:["Mode ",s]}),e.jsx("span",{className:"font-mono",children:o})]})}function _(){const[s,o]=c.useState(null),[b,V]=c.useState(null),[E,F]=c.useState(!0),[n,y]=c.useState(null),[N,C]=c.useState(null),[m,R]=c.useState(null),[l,$]=c.useState(null),[v,k]=c.useState(null),[j,A]=c.useState(null),[u,T]=c.useState(null),[I,M]=c.useState(null),[B,D]=c.useState(null),f=c.useCallback(()=>{L().then(o).catch(r=>V(r instanceof Error?r.message:String(r))).finally(()=>F(!1)),w().then(y).catch(()=>{}),J().then(R).catch(()=>{}),H().then($).catch(()=>{}),q().then(k).catch(()=>{}),G().then(A).catch(()=>{}),Q().then(T).catch(()=>{}),W().then(M).catch(()=>{}),z().then(D).catch(()=>{})},[]);c.useEffect(()=>{f();const r=setInterval(f,5e3);return()=>clearInterval(r)},[f]);const O=()=>{K("provider").then(r=>(C(`Breaker "${r.subsystem}" ${r.state}; evidence retained: ${r.failures} failures / ${r.attempts} attempts`),w())).then(y).catch(r=>C(r instanceof Error?r.message:String(r)))};if(E&&!s)return e.jsx("div",{className:"vc-loading",children:"Loading vector-cortex evaluation…"});if(b&&!s)return e.jsxs("div",{className:"vc-error",children:["Error: ",b]});if(!s)return e.jsx("div",{className:"vc-empty",children:"No evaluation data available."});const S=Math.max(1,...s.histogram.cells,s.histogram.overflow);return e.jsxs("div",{className:"flex flex-col gap-4",children:[e.jsxs("div",{className:"flex items-center gap-2",children:[e.jsx("h2",{className:"text-lg font-semibold",children:"Vector Cortex Evaluation"}),s.enabled?e.jsx(a,{variant:"warning",children:"OBSERVER PENDING (A)"}):e.jsx(a,{variant:"danger",children:"MODE C (OFF)"})]}),e.jsxs("div",{className:"grid grid-cols-1 gap-4 md:grid-cols-3",children:[e.jsxs(d,{children:[e.jsx(i,{children:e.jsx(x,{children:"Samples"})}),e.jsxs(h,{children:[e.jsx("div",{className:"text-3xl font-bold",children:s.samples}),e.jsxs("div",{className:"mt-2 flex flex-col",children:[e.jsx(p,{mode:"A",count:s.byMode.A}),e.jsx(p,{mode:"B",count:s.byMode.B}),e.jsx(p,{mode:"C",count:s.byMode.C})]})]})]}),e.jsxs(d,{className:"md:col-span-2",children:[e.jsx(i,{children:e.jsx(x,{children:"Latency Histogram (ms, inclusive edges)"})}),e.jsxs(h,{children:[e.jsxs("div",{className:"flex items-end gap-2",style:{height:160},children:[s.histogram.edges.map((r,g)=>{const P=s.histogram.cells[g]/S*140;return e.jsxs("div",{className:"flex flex-1 flex-col items-center gap-1",children:[e.jsx("span",{className:"text-xs text-muted-foreground",children:s.histogram.cells[g]}),e.jsx("div",{className:"w-full rounded-t",style:{height:Math.max(2,P),background:"#6366f1"}}),e.jsxs("span",{className:"text-[10px] text-muted-foreground",children:["≤",r]})]},r)}),e.jsxs("div",{className:"flex flex-1 flex-col items-center gap-1",children:[e.jsx("span",{className:"text-xs text-muted-foreground",children:s.histogram.overflow}),e.jsx("div",{className:"w-full rounded-t",style:{height:Math.max(2,s.histogram.overflow/S*140),background:"#f87171"}}),e.jsx("span",{className:"text-[10px] text-muted-foreground",children:">250"})]})]}),e.jsxs("div",{className:"mt-1 text-xs text-muted-foreground",children:["Total: ",s.histogram.total," · Rejects: ",s.rejects.length]})]})]})]}),e.jsxs(d,{children:[e.jsx(i,{children:e.jsxs("div",{className:"flex items-center justify-between",children:[e.jsx(x,{children:"Live Safety Envelope (VC0C)"}),e.jsxs("div",{className:"flex items-center gap-2",children:[n?.stateSource==="ephemeral"&&e.jsx(a,{variant:"outline",children:"EPHEMERAL (non-live)"}),e.jsx("button",{onClick:O,disabled:!n?.enabled,className:"rounded border border-border px-2 py-1 text-xs disabled:opacity-50",children:"Reset Cooldown"})]})]})}),e.jsxs(h,{children:[N&&e.jsx("div",{className:"mb-2 text-xs text-muted-foreground",children:N}),n?e.jsxs("div",{className:"grid grid-cols-2 gap-4 md:grid-cols-4",children:[e.jsx(t,{label:"State",value:n.state}),e.jsx(t,{label:"Mode",value:n.mode}),e.jsx(t,{label:"Window",value:`${n.windowMs}ms`}),e.jsx(t,{label:"Probes",value:String(n.probeCount)}),e.jsx(t,{label:"Backoff",value:`${n.backoffDelayMs}ms`}),e.jsx(t,{label:"Failures",value:`${n.failures}/${n.attempts}`}),e.jsx(t,{label:"Frontier",value:n.stateSource==="ephemeral"?"non-live":n.frontierFrozen?"FROZEN":"LIVE"}),e.jsx(t,{label:"Spool lag",value:String(n.spoolLag)}),e.jsx(t,{label:"Encoder mode",value:n.encoderMode}),e.jsx(t,{label:"Encoder asset",value:n.encoderAssetDigest?n.encoderAssetDigest.slice(0,12):"none"})]}):e.jsx("div",{className:"vc-empty",children:"Health unavailable (VC0C off)."})]})]}),e.jsxs(d,{children:[e.jsx(i,{children:e.jsxs("div",{className:"flex items-center justify-between",children:[e.jsx(x,{children:"Derived Cortex Store (VC3A)"}),l?.enabled?e.jsx(a,{variant:"success",children:"ACTIVE"}):e.jsx(a,{variant:"danger",children:"OFF"})]})}),e.jsx(h,{children:l?.enabled?e.jsxs(e.Fragment,{children:[e.jsxs("div",{className:"grid grid-cols-2 gap-4 md:grid-cols-3",children:[e.jsx(t,{label:"Generation",value:l.generationId??"—"}),e.jsx(t,{label:"Ordinal",value:l.ordinal??"—"}),e.jsx(t,{label:"Records",value:String(l.recordCount)}),e.jsx(t,{label:"Frontier (HW)",value:l.sourceHighWater}),e.jsx(t,{label:"Root digest",value:l.rootDigest?l.rootDigest.slice(0,16):"—"}),l.nodes!==void 0&&e.jsxs(e.Fragment,{children:[e.jsx(t,{label:"Nodes",value:String(l.nodes?.length??0)}),e.jsx(t,{label:"Edges",value:String(l.edges?.length??0)}),e.jsx(t,{label:"Graph digest",value:l.generationDigest?l.generationDigest.slice(0,16):"—"})]})]}),l.nodes!==void 0&&(l.edges?.length??0)>0&&e.jsxs("div",{className:"mt-4 max-h-56 overflow-y-auto",children:[e.jsx("div",{className:"mb-1 text-xs font-medium text-muted-foreground",children:"Topology edges (VC3B)"}),e.jsxs("table",{className:"w-full text-left text-xs",children:[e.jsx("thead",{children:e.jsxs("tr",{className:"border-b border-border/50 text-muted-foreground",children:[e.jsx("th",{className:"py-1 pr-2",children:"source"}),e.jsx("th",{className:"py-1 pr-2",children:"target"}),e.jsx("th",{className:"py-1 pr-2",children:"head"}),e.jsx("th",{className:"py-1 pr-2",children:"dir"}),e.jsx("th",{className:"py-1",children:"score"})]})}),e.jsx("tbody",{children:l.edges?.map((r,g)=>e.jsxs("tr",{className:"border-b border-border/30",children:[e.jsx("td",{className:"py-1 pr-2 font-mono",children:r.source}),e.jsx("td",{className:"py-1 pr-2 font-mono",children:r.target}),e.jsx("td",{className:"py-1 pr-2 font-mono",children:r.head}),e.jsx("td",{className:"py-1 pr-2",children:r.direction}),e.jsx("td",{className:"py-1 font-mono",children:r.score})]},`${r.source}-${r.target}-${r.head}-${g}`))})]})]})]}):e.jsx("div",{className:"vc-empty",children:"Cortex store disabled (VC3A off)."})})]}),e.jsxs(d,{children:[e.jsx(i,{children:e.jsxs("div",{className:"flex items-center justify-between",children:[e.jsx(x,{children:"Topology Query Diagnostics (VC3C)"}),v?.enabled?e.jsx(a,{variant:"success",children:"ACTIVE"}):e.jsx(a,{variant:"danger",children:"OFF"})]})}),e.jsx(h,{children:v?.enabled?e.jsx("div",{className:"grid grid-cols-2 gap-4 md:grid-cols-3",children:e.jsx(t,{label:"Router version",value:String(v.routerVersion)})}):e.jsx("div",{className:"vc-empty",children:"Query diagnostics unavailable (VC3C off)."})})]}),e.jsxs(d,{children:[e.jsx(i,{children:e.jsxs("div",{className:"flex items-center justify-between",children:[e.jsx(x,{children:"Dual-Tier Shards (VC4A)"}),j?.enabled?e.jsx(a,{variant:"success",children:"ACTIVE"}):e.jsx(a,{variant:"danger",children:"OFF"})]})}),e.jsx(h,{children:j?.enabled?e.jsxs(e.Fragment,{children:[e.jsxs("div",{className:"grid grid-cols-2 gap-4 md:grid-cols-4",children:[e.jsx(t,{label:"Semantic shards",value:String(j.semanticCount)}),e.jsx(t,{label:"Exact shards",value:String(j.exactCount)}),e.jsx(t,{label:"Byte total",value:String(j.byteTotal)}),e.jsx(t,{label:"Protected bytes",value:String(j.protectedByteTotal)})]}),e.jsx("div",{className:"mt-3 text-xs text-muted-foreground",children:"Reader-only count/byte aggregate; staged in-memory this sprint."})]}):e.jsx("div",{className:"vc-empty",children:"Dual-tier shards disabled (VC4A off)."})})]}),e.jsxs(d,{children:[e.jsx(i,{children:e.jsxs("div",{className:"flex items-center justify-between",children:[e.jsx(x,{children:"Reconstruction Fidelity (VC4C)"}),u?.enabled?e.jsx(a,{variant:"success",children:"ACTIVE"}):e.jsx(a,{variant:"danger",children:"OFF"})]})}),e.jsx(h,{children:u?.enabled?e.jsxs(e.Fragment,{children:[e.jsxs("div",{className:"grid grid-cols-2 gap-4 md:grid-cols-4",children:[e.jsx(t,{label:"Closure attempts",value:String(u.closureAttempts)}),e.jsx(t,{label:"Closure rejections",value:String(u.closureRejections)}),e.jsx(t,{label:"Validated",value:String(u.validatedCount)}),e.jsx(t,{label:"Invalidated",value:String(u.invalidatedCount)}),e.jsx(t,{label:"Span total",value:String(u.spanTotal)}),e.jsx(t,{label:"Byte total",value:String(u.byteTotal)})]}),e.jsx("div",{className:"mt-3 text-xs text-muted-foreground",children:"Reader-only closure/validation aggregate; staged in-memory this sprint."})]}):e.jsx("div",{className:"vc-empty",children:"Reconstruction fidelity disabled (VC4C off)."})})]}),e.jsx(Z,{view:I}),e.jsx(U,{view:B}),e.jsxs(d,{children:[e.jsx(i,{children:e.jsxs("div",{className:"flex items-center justify-between",children:[e.jsx(x,{children:"Occurrence Ledger (VC1B)"}),m?.enabled?e.jsx(a,{variant:"success",children:"ACTIVE"}):e.jsx(a,{variant:"danger",children:"OFF"})]})}),e.jsx(h,{children:m?.enabled?e.jsxs(e.Fragment,{children:[e.jsxs("div",{className:"mb-3 grid grid-cols-2 gap-4 md:grid-cols-3",children:[e.jsx(t,{label:"Session",value:m.session}),e.jsx(t,{label:"High-water",value:m.highWater}),e.jsx(t,{label:"Occurrences",value:String(m.count)})]}),m.occurrences.length===0?e.jsx("div",{className:"vc-empty",children:"No occurrences recorded."}):e.jsx("div",{className:"max-h-64 overflow-y-auto",children:e.jsxs("table",{className:"w-full text-left text-xs",children:[e.jsx("thead",{children:e.jsxs("tr",{className:"border-b border-border/50 text-muted-foreground",children:[e.jsx("th",{className:"py-1 pr-2",children:"seq"}),e.jsx("th",{className:"py-1 pr-2",children:"eventId"}),e.jsx("th",{className:"py-1 pr-2",children:"kind"}),e.jsx("th",{className:"py-1 pr-2",children:"toolCall"}),e.jsx("th",{className:"py-1",children:"digest"})]})}),e.jsx("tbody",{children:m.occurrences.map(r=>e.jsxs("tr",{className:"border-b border-border/30",children:[e.jsx("td",{className:"py-1 pr-2 font-mono",children:r.seq}),e.jsx("td",{className:"py-1 pr-2 font-mono",children:r.eventId}),e.jsx("td",{className:"py-1 pr-2",children:r.kind}),e.jsx("td",{className:"py-1 pr-2 font-mono",children:r.toolCallId??"—"}),e.jsx("td",{className:"max-w-[180px] truncate font-mono text-muted-foreground",children:r.digest})]},`${r.seq}-${r.eventId}`))})]})})]}):e.jsx("div",{className:"vc-empty",children:"Ledger disabled (VC1B off)."})})]})]})}export{_ as default};
-//# sourceMappingURL=VectorCortexTab-BWi3u_gp.js.map