pi-mega-compact 0.20.6 → 0.20.7

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/extensions/dashboard-server/routes-rag-settings-helpers.ts

@@ -7,25 +7,10 @@
  *
  * PREVENT-011: no `any` type.
  */
+import type { SettingSpec, SettingGroup } from "./routes-rag-settings-types.js";
+import { VECTOR_CORTEX_SETTINGS } from "./routes-rag-settings-vector-cortex.js";
 
-
-/**
- * Base metadata for a single setting entry before its live `value` is resolved.
- * `category` and `value` are filled in at read time by the handler.
- */
-export interface SettingSpec {
-	key: string;
-	label: string;
-	description: string;
-	type: "boolean" | "number" | "string";
-	default: string | number | boolean;
-	/** True when this is a `_DISABLED`-convention opt-out flag. */
-	disabledConvention: boolean;
-	requiresLlm: boolean;
-	unit?: string;
-	min?: number;
-	max?: number;
-}
+export type { SettingSpec } from "./routes-rag-settings-types.js";
 
 // Shorthand builders to keep the inventory terse and unambiguous.
 const boolFlag = (
@@ -96,10 +81,7 @@ const str = (
 });
 
 /** Every adjustable setting, grouped by category. Read-only after module load. */
-export const SETTINGS: ReadonlyArray<{
-	name: string;
-	settings: SettingSpec[];
-}> = [
+export const SETTINGS: ReadonlyArray<SettingGroup> = [
 	{
 		name: "RAG Pipeline",
 		settings: [
@@ -233,6 +215,12 @@ export const SETTINGS: ReadonlyArray<{
 			boolDirect("MEGACOMPACT_MARK_ONLY_L1", "Mark Only L1", "L1 runs but does not collapse", false),
 			boolDirect("MEGACOMPACT_MARK_ONLY_L2", "Mark Only L2", "L2 runs but does not collapse", false),
 			boolDirect("MEGACOMPACT_MINILM", "MiniLM Embedder", "Use MiniLM instead of trigram", false),
+			boolDirect(
+				"MEGACOMPACT_DEDUP_AUDIT",
+				"Dedup Audit Trail",
+				"Append one events.log line per tier decision (which layer collapsed a region, onto what, at what similarity) to tune the thresholds below. Pure instrumentation — dedup behavior is identical either way.",
+				true,
+			),
 		],
 	},
 	{
@@ -274,119 +262,7 @@ export const SETTINGS: ReadonlyArray<{
 			num("MEGACOMPACT_EMBEDDING_CHARS_PER_TOKEN", "Embedding Chars per Token", "Estimated characters per token used for embedder chunking size", 4, 1, 32),
 		],
 	},
-	{
-		name: "Vector Cortex",
-		settings: [
-			boolDirect(
-				"MEGACOMPACT_VC0A",
-				"VC0A Baseline Observability",
-				"Structured evaluation observer (MetricEventV1 + latency histogram). OFF = mode C, byte-identical to predecessor.",
-				true,
-			),
-			boolDirect(
-				"MEGACOMPACT_VC0B",
-				"VC0B Replay Correctness",
-				"ReplayCutV2 effective-cut (min of boundary-safe/commit/capture high-water + pair retreat + anchor floor) and M3 effective-cut-v2 migration. OFF = legacy capped replay, byte-identical.",
-				true,
-			),
-			boolDirect(
-				"MEGACOMPACT_VC1A",
-				"VC1A Canonical Byte Events",
-				"EventV2 byte-authority ledger codec (original bytes + SHA-256, strict UTF-8, derived NFC) and canonical validator (EVT_DIGEST_MISMATCH / EVT_UTF8_TAG_INVALID / EVT_DUPLICATE_ID). OFF = mode C, transcript codec unchanged, byte-identical.",
-				true,
-			),
-			boolDirect(
-				"MEGACOMPACT_VC1B",
-				"VC1B Occurrence Ledger + Tool Identity",
-				"Neutral occurrence ledger (LedgerReader/Writer/Admin + CompatJournalV1): per-session monotonic seq, tool result references one earlier call, uniqueness by (eventId,digest) only, and the M2 copy-validate-switch downgrade journal. OFF = mode C, ledger unwritten, byte-identical.",
-				true,
-			),
-			boolDirect(
-				"MEGACOMPACT_VC0C",
-				"VC0C Live Safety Envelope",
-				"TriadResult/Breaker live circuit breaker (60s window, 20 attempts, 30s cooldown, 3 probes, 5min healthy residence) + durable spool before provider invocation; manual reset clears cooldown but never evidence. OFF = mode C, unchanged transcript, byte-identical.",
-				true,
-			),
-			boolDirect(
-				"MEGACOMPACT_VC1C",
-				"VC1C Cross-Language Conformance v2",
-				"FixtureManifestV2 canonical manifest validator + DowngradeReport deterministic downgrade export + MinHashV2 exact big-integer signatures and the M4 copy/validate/switch minhash-v2 migration (seed table frozen, cross-language byte-exact). OFF = mode C, v1 sync dedup scan unchanged, byte-identical.",
-				true,
-			),
-			boolDirect(
-				"MEGACOMPACT_VC2A",
-				"VC2A Offline Model Runtime",
-				"ModelManifestV1 digest-before-load ONNX runtime (opset17/batch1/max512) + asset-free trigram demotion. Asset path assets/vector-cortex/encoder-v1 is immutable/digest-pinned. OFF = mode C, byte-identical to predecessor.",
-				true,
-			),
-			boolDirect(
-				"MEGACOMPACT_VC2B",
-				"VC2B Multi-Head Encoder",
-				"VectorSetV1 five L2-normalized heads (384/128/128/64/32) with head-calibration draft + asset-free trigram B (512d) and lexical C fallbacks, plus the per-head emit seam. OFF = mode C, no per-head vectors emitted, byte-identical predecessor.",
-				true,
-			),
-			boolDirect(
-				"MEGACOMPACT_VC2C",
-				"VC2C Encoder Qualification + Calibration",
-				"QualifiedEncoderV1/CalibrationV1: calibration fit on the calibration split only (held-out labels prohibited) + atomic selection across MODEL_ASSET and per-head EVALUATION thresholds (any field failure demotes all of A). OFF = mode C, no qualification/calibration selection, byte-identical predecessor.",
-				true,
-			),
-			boolDirect(
-				"MEGACOMPACT_VC3A",
-				"VC3A Cortex Store",
-				"Capability-gated derived cortex store (CortexReader/Writer/Admin + CortexRecordV1): additive, keyed (sourceHighWater, algorithmVersion, id), immutable records, deterministic generation rebuild + one root digest. OFF = mode C, no cortex records written, byte-identical predecessor.",
-				true,
-			),
-			boolDirect(
-				"MEGACOMPACT_VC3B",
-				"VC3B Deterministic Topology",
-				"Deterministic cortical topology (TopologyV1/EdgeV1): per-(source,head) top-k=16/head calibrated-threshold edges, stable score-desc/then-target-ID sort, dependency directed + contradiction symmetric paired records, one stable generation digest. OFF = mode C, no topology graph built/emitted, predecessor-precise topology view, byte-identical predecessor.",
-				true,
-			),
-			boolDirect(
-				"MEGACOMPACT_VC3C",
-				"VC3C Topology Query + Router Invalidation",
-				"TopologyQueryV1/RouterKeyV2 structured keys (length-delimited, unsigned-byte order, no prefix ambiguity), exact (session,generation) invalidation, stale-generation rejection (TOP_GENERATION_STALE), and the M6 router-generation-v2 copy/validate/switch migration. OFF = mode C, no structured router key / generation invalidation, byte-identical predecessor.",
-				true,
-			),
-			boolDirect(
-				"MEGACOMPACT_VC4A",
-				"VC4A Dual-Tier Shards",
-				"SemanticShardV1/ExactShardV1/ShardManifestV1: partition a session ONLY at complete EventV2 boundaries; exact shards preserve every tool call/result pair, anchor and invalid UTF-8 event as original bytes (pairs never split across exact shards); manifest enforces disjoint sorted ranges + complete protected-span coverage. OFF = mode C, exact anchors/current transcript only, byte-identical predecessor.",
-				true,
-			),
-			boolDirect(
-				"MEGACOMPACT_VC4B",
-				"VC4B Residual Basis Parity",
-				"Residual codec: orthonormal DCT-II basis + int16 block quantization + block-scoped exact correction stream + (9,6) Reed-Solomon parity shards with SHA-256 corruption detection; admission gates on encodedSize <= 95% of exact-compressed size. OFF = mode C, no residual artifact produced, byte-identical predecessor.",
-				true,
-			),
-			boolDirect(
-				"MEGACOMPACT_VC4C",
-				"VC4C Reconstruction Fidelity",
-				"Conservative closure + source-order assembly + reconstruction validator: recursively closes dependencies and whole tool pairs to a fixed point, resolves contradictions by retaining the later exact source resolution, assembles spans solely by source range, and rejects missing anchors / split pairs / digest mismatch / unresolved contradiction. Mandatory token estimate is content-only and handed unchanged to VC5A. OFF = mode C, no closure/validator, byte-identical predecessor (VC4B).",
-				true,
-			),
-			boolDirect(
-				"MEGACOMPACT_VC5A",
-				"VC5A PromptDagV1 + Budgeted Planner",
-				"Single-session DAG (PromptDagV1) + budgeted 0/1 portfolio planner: builds a stable Kahn-ordered DAG, computes the mandatory dependency/tool/anchor closure before optional selection, returns MANDATORY_CLOSURE_OVER_BUDGET with evidence preserved on overflow, and runs a utility-per-token portfolio that never exceeds the remaining budget. Framing is owned here, not in VC4C. OFF = byte-identical predecessor (VC4C).",
-				true,
-			),
-			boolDirect(
-				"MEGACOMPACT_VC5B",
-				"VC5B Validated Renderer + Provider Profiles",
-				"Validated prompt renderer: replays VC5A's stable Kahn order verbatim, preserves exact tool bytes (PREVENT-PI-002), places compacted context via the host before_agent_start prepend seam — never role:system (PREVENT-PI-003) — and SHA-256 hashes the entire canonical outbound request before provider invocation. Unknown provider/model cleanly bypasses to the predecessor prompt path. OFF = byte-identical predecessor (VC5A).",
-				true,
-			),
-			boolDirect(
-				"MEGACOMPACT_VC5C",
-				"VC5C Live Graduated Rollout",
-				"Live graduated rollout: deterministically hashes each session into a stable 10,000-bucket cohort and advances the exposure gate (1/5/25/50/100%) only after a 72h monotonic residency, a powered sample, >=10,000 events, and >=200 sessions — advancing ONE gate at a time. A hard causal/tool/anchor/exact failure freezes promotion and selects the pre-VC path. OFF = byte-identical predecessor (VC5B).",
-				true,
-			),
-		],
-	},
+	VECTOR_CORTEX_SETTINGS,
 	{
 		name: "Cost API",
 		settings: [

package/extensions/dashboard-server/routes-rag-settings-types.ts

@@ -0,0 +1,34 @@
+/**
+ * dashboard-server/routes-rag-settings-types.ts — SETTINGS inventory contract.
+ *
+ * The shared shapes the settings inventory is built from. Extracted so the
+ * inventory can be split across sibling files (helpers.ts + the per-area groups)
+ * without either side importing the other's data — contract-first, per
+ * docs/ENGINEERING_PRACTICES.md.
+ *
+ * PREVENT-011: no `any` type.
+ */
+
+/**
+ * Base metadata for a single setting entry before its live `value` is resolved.
+ * `category` and `value` are filled in at read time by the handler.
+ */
+export interface SettingSpec {
+	key: string;
+	label: string;
+	description: string;
+	type: "boolean" | "number" | "string";
+	default: string | number | boolean;
+	/** True when this is a `_DISABLED`-convention opt-out flag. */
+	disabledConvention: boolean;
+	requiresLlm: boolean;
+	unit?: string;
+	min?: number;
+	max?: number;
+}
+
+/** One named category of settings as rendered by the Setup panel. */
+export interface SettingGroup {
+	name: string;
+	settings: SettingSpec[];
+}