pi-mega-compact 0.20.5 → 0.20.7

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,113 +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,
-			),
-		],
-	},
+	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[];
+}

package/extensions/dashboard-server/routes-rag-settings-vector-cortex.ts

@@ -0,0 +1,142 @@
+/**
+ * dashboard-server/routes-rag-settings-vector-cortex.ts — Vector Cortex SETTINGS.
+ *
+ * The VC0A..VC5C chain flag inventory, split out of routes-rag-settings-helpers.ts
+ * to keep that file under the 400-line extensions/ soft limit. Every VC flag is a
+ * user-visible dashboard toggle (never in EXCLUDED_SETTINGS) per the chain spec,
+ * and each carries the long description the Setup panel renders as help text.
+ *
+ * PREVENT-011: no `any` type.
+ */
+
+import type { SettingSpec, SettingGroup } from "./routes-rag-settings-types.js";
+
+const boolDirect = (
+	key: string,
+	label: string,
+	description: string,
+	def: boolean,
+): SettingSpec => ({
+	key,
+	label,
+	description,
+	type: "boolean",
+	default: def,
+	disabledConvention: false,
+	requiresLlm: false,
+});
+
+/** The Vector Cortex chain flags, as one SETTINGS category. */
+export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
+	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,
+		),
+	],
+};

package/extensions/dashboard-server/routes-vector-cortex-rollout.ts

@@ -0,0 +1,52 @@
+/**
+ * dashboard-server/routes-vector-cortex-rollout.ts — VC5C live graduated-rollout
+ * dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/rollout returning the rollout aggregate:
+ * current gate, bucket count, sessions/events counts, and promotion-blocked
+ * state. NEVER exposes session payloads, prompt text, or bucket→session mappings
+ * (reader-only, SECURITY_PRIVACY). Flag-gated on MEGACOMPACT_VC5C: `enabled:false`
+ * when off (byte-identical to the pre-VC5C predecessor).
+ *
+ * Guardrails: PREVENT-PI-004 (local in-process state only), PREVENT-011 (no
+ * `any`), reader-only aggregate (counts + gate state only).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import { VC5C_ENABLED } from "../../src/config.js";
+import { ROLLOUT_GATES, ROLLOUT_BUCKETS } from "../../src/vector-cortex/rollout/types.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import type { VectorCortexRolloutView } from "./api-contracts/vector-cortex.js";
+
+/** Reader-only GET /api/vector-cortex/rollout (VC5C). */
+export function handleVectorCortexRollout(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+  if (path !== "/api/vector-cortex/rollout") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC5C_ENABLED();
+  const gateIndex = 0; // Ephemeral rollout state: no durable gate in this sprint.
+  const gatePct = ROLLOUT_GATES[gateIndex]!;
+  const body: VectorCortexRolloutView = {
+    enabled,
+    gateIndex: enabled ? gateIndex : 0,
+    gatePct: enabled ? gatePct : 0,
+    buckets: ROLLOUT_BUCKETS,
+    bucketCount: enabled ? gatePct * 100 : 0,
+    events: 0,
+    sessions: 0,
+    promotionBlocked: false,
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

package/extensions/dashboard-server/routes-vector-cortex.ts

@@ -24,3 +24,4 @@ export { handleVectorCortexResidual } from "./routes-vector-cortex-residual.js";
 export { handleVectorCortexReconstruct } from "./routes-vector-cortex-reconstruct.js";
 export { handleVectorCortexPlans } from "./routes-vector-cortex-plans.js";
 export { handleVectorCortexRender } from "./routes-vector-cortex-render.js";
+export { handleVectorCortexRollout } from "./routes-vector-cortex-rollout.js";

package/extensions/dashboard-server/routes.ts

@@ -52,4 +52,5 @@ export {
 	handleVectorCortexReconstruct,
 	handleVectorCortexPlans,
 	handleVectorCortexRender,
+	handleVectorCortexRollout,
 } from "./routes-vector-cortex.js";

package/extensions/dashboard-server/server.ts

@@ -68,6 +68,7 @@ import {
 	handleVectorCortexReconstruct,
 	handleVectorCortexPlans,
 	handleVectorCortexRender,
+	handleVectorCortexRollout,
 	handleStatic,
 } from "./routes.js";
 
@@ -315,6 +316,7 @@ export async function launchDashboardServer(
 		if (handleVectorCortexReconstruct(req, res, ctx)) return;
 		if (handleVectorCortexPlans(req, res, ctx)) return;
 		if (handleVectorCortexRender(req, res, ctx)) return;
+	if (handleVectorCortexRollout(req, res, ctx)) return;
 		handleStatic(req, res, ctx);
 	});
 

package/extensions/mega-runtime/vector-cortex-live.ts

@@ -0,0 +1,165 @@
+/**
+ * vector-cortex-live.ts — VC5C live graduated-rollout integration seam.
+ *
+ * This adapter composes the rollout assign + gate + emit seams into the host
+ * provider-invocation path. It runs BEFORE provider invocation and decides, for
+ * the current session, which live path is active:
+ *
+ *   - on a hard causal/tool/anchor/exact failure → select mode C (pre-VC prompt
+ *     path) and FREEZE promotion (promotionBlocked=true) for the remainder of the
+ *     cooldown/spool/restart/clock period satisfying TRIAD_RESILIENCE;
+ *   - otherwise → the active gate decides whether the VC path is exposed to this
+ *     session's bucket.
+ *
+ * PREVENT-PI-003: the rollout NEVER emits a `role:"system"` message. The VC
+ * prompt context is composed into the host `before_agent_start` systemPrompt
+ * prepend seam only. PREVENT-PI-004: zero network calls (local in-process state
+ * + injected clock only). PREVENT-011: no `any`. Non-fatal: any rollout noise
+ * degrades to mode C (pre-VC continuity), never breaking the agent loop.
+ *
+ * LIVENESS HONESTY (mirrors VC0C-Q01/Q06): the rollout decision state here is
+ * PER-PROCESS / IN-MEMORY and EPHEMERAL — there is NO persistent rollout runtime
+ * and NO live producer wiring. The gate decision is recomputed from injected
+ * evidence each epoch. The assigned/blocked events are emitted for observability
+ * only.
+ */
+
+import { assignSession, bucketInGate, gatePctForIndex } from "../../src/vector-cortex/rollout/assign.js";
+import {
+  decideGate,
+  selectsPreVcPath,
+  type RolloutClock,
+  type RolloutEvidence,
+} from "../../src/vector-cortex/rollout/gate.js";
+import { createRolloutReporter, type RolloutReporter } from "../../src/vector-cortex/rollout/emit.js";
+import type { GateIndex, RolloutHardFault } from "../../src/vector-cortex/rollout/types.js";
+import { VC5C_ENABLED } from "../../src/config/vector-cortex.js";
+
+/** Host context the live seam needs. */
+export interface VectorCortexLiveContext {
+  /** Monotonic clock for windows/cooldowns + gate eligibility (fake-clock testable). */
+  readonly clock?: RolloutClock;
+  /** Current gate index BEFORE this epoch (0..4). */
+  readonly currentGate?: GateIndex;
+  /** Injected rollout evidence for the current window. */
+  readonly evidence?: RolloutEvidence;
+  /** Hard faults observed this epoch (any entry forces C + freezes promotion). */
+  readonly hardFaults?: readonly RolloutHardFault[];
+  /** Optional emit callback for observability events. */
+  readonly emit?: (event: string, fields: Record<string, unknown>) => void;
+}
+
+/** The decision the live seam returns for one session epoch. */
+export interface VectorCortexLiveDecision {
+  /** Whether the VC path is exposed to this session (true under current gate). */
+  readonly vcActive: boolean;
+  /** True when a hard failure forced mode C (pre-VC continuity). */
+  readonly forcedPreVc: boolean;
+  /**
+   * The selected triad mode for this epoch. The VC5C rollout seam only ever
+   * selects "A" (VC path exposed at the active gate) or "C" (pre-VC fallback:
+   * flag off, no evidence/clock, or a hard causal/tool/anchor/exact fault that
+   * freezes promotion). The deterministic-greedy triad "B" mode is NOT produced
+   * here — this seam is a pure gating/eligibility layer with no live renderer
+   * driver; a real mode-B greedy-render fallback belongs to the layer that
+   * actually runs renderers (a future sprint), not to this observability seam.
+   * Declaring "B" in this union while never producing it would be an overclaim.
+   */
+  readonly mode: "A" | "C";
+  /** The session's stable bucket (0..9999). */
+  readonly bucket: number;
+  /** The effective gate index after this epoch. */
+  readonly gateIndex: GateIndex;
+  /** True when promotion is frozen by a hard fault. */
+  readonly promotionBlocked: boolean;
+  /** The systemPrompt prepend the host `before_agent_start` seam should use. */
+  readonly systemPromptPrepend: string;
+}
+
+const NO_PREPEND = "";
+
+/**
+ * Decide the live path for a session epoch. Pure over injected context; no
+ * I/O, no network. Flag OFF (or absent evidence/clock) degrades to mode C with
+ * the VC path inactive (pre-VC predecessor parity).
+ */
+export function decideLivePath(
+  sessionId: string,
+  ctx: VectorCortexLiveContext,
+): VectorCortexLiveDecision {
+  const reporter: RolloutReporter = createRolloutReporter(ctx.emit);
+  const assignment = assignSession(sessionId);
+
+  if (!VC5C_ENABLED()) {
+    // Pre-VC predecessor: no rollout, no VC path. Never emit role:system.
+    return {
+      vcActive: false,
+      forcedPreVc: false,
+      mode: "C",
+      bucket: assignment.bucket,
+      gateIndex: 0,
+      promotionBlocked: false,
+      systemPromptPrepend: NO_PREPEND,
+    };
+  }
+
+  reporter.assigned({
+    sessionId,
+    bucket: assignment.bucket,
+    gateIndex: assignment.gateIndex,
+    gatePct: gatePctForIndex(assignment.gateIndex),
+  });
+
+  const hardFaults = ctx.hardFaults ?? [];
+  const hardFault = hardFaults.length > 0 ? hardFaults[0]! : undefined;
+  const forcedPreVc = selectsPreVcPath(hardFault);
+
+  if (forcedPreVc && hardFault) {
+    reporter.promotionBlocked({
+      gateIndex: ctx.currentGate ?? assignment.gateIndex,
+      kind: hardFault.kind,
+      detail: hardFault.detail,
+    });
+    // Hard failure → select C (pre-VC path) and freeze promotion.
+    return {
+      vcActive: false,
+      forcedPreVc: true,
+      mode: "C",
+      bucket: assignment.bucket,
+      gateIndex: ctx.currentGate ?? assignment.gateIndex,
+      promotionBlocked: true,
+      systemPromptPrepend: NO_PREPEND,
+    };
+  }
+
+  const clock = ctx.clock;
+  const evidence = ctx.evidence;
+  if (clock === undefined || evidence === undefined) {
+    // No live evidence/clock → pre-VC parity (no promotion, no VC exposure).
+    return {
+      vcActive: false,
+      forcedPreVc: false,
+      mode: "C",
+      bucket: assignment.bucket,
+      gateIndex: assignment.gateIndex,
+      promotionBlocked: false,
+      systemPromptPrepend: NO_PREPEND,
+    };
+  }
+
+  const outcome = decideGate(ctx.currentGate ?? assignment.gateIndex, evidence, clock);
+  const vcActive = bucketInGate(assignment.bucket, outcome.gatePct);
+
+  // PREVENT-PI-003: VC prompt context is composed into the host prepend seam,
+  // never as a role:system message. Empty prepend here (the actual prompt text
+  // is owned by the renderer seam); this seam only signals eligibility.
+  return {
+    vcActive,
+    forcedPreVc: false,
+    mode: vcActive ? "A" : "C",
+    bucket: assignment.bucket,
+    gateIndex: outcome.gateIndex,
+    promotionBlocked: outcome.promotionBlocked,
+    systemPromptPrepend: NO_PREPEND,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.5",
+  "version": "0.20.7",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/config/dedup.ts

@@ -75,6 +75,14 @@ export interface DedupConfigShape {
    *  topical structure before detailed checkpoint hits. */
   RAPTOR_INJECT_SUMMARIES: boolean;
   // Monitoring / alerting.
+  /**
+   * Durable dedup audit trail (external-audit item #2). ON appends one
+   * structured JSON line per tier DECISION to events.log so an operator can see
+   * which layer collapsed a region, onto what, and at what similarity — the
+   * inputs needed to tune the thresholds above. OFF writes nothing at all;
+   * dedup behavior is identical either way (pure instrumentation).
+   */
+  DEDUP_AUDIT: boolean;
   FP_RATE_L0: number; // FP alert threshold for exact tier
   FP_RATE_L1L2: number; // FP alert threshold for fuzzy tiers
   ALERT_WINDOW_MS: number;
@@ -115,6 +123,7 @@ export function loadDedupConfig(): DedupConfigShape {
     RAPTOR_MAX_LEAF_EXPANSION: envNum("MEGACOMPACT_RAPTOR_MAX_LEAF_EXP", 10),
     RAPTOR_FRESHNESS_HOURS: envNum("MEGACOMPACT_RAPTOR_FRESHNESS_HOURS", 4),
     RAPTOR_INJECT_SUMMARIES: envBool("MEGACOMPACT_RAPTOR_INJECT_SUMMARIES", true),
+    DEDUP_AUDIT: envBool("MEGACOMPACT_DEDUP_AUDIT", true),
     FP_RATE_L0: envNum("MEGACOMPACT_FP_RATE_L0", 0.01),
     FP_RATE_L1L2: envNum("MEGACOMPACT_FP_RATE_L1L2", 0.05),
     ALERT_WINDOW_MS: envNum("MEGACOMPACT_ALERT_WINDOW_MS", 600_000),

package/src/config/vector-cortex.ts

@@ -201,6 +201,19 @@ export const VC5A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC5A");
  */
 export const VC5B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC5B");
 
+/**
+ * VC5C — live graduated rollout. Default ON. `MEGACOMPACT_VC5C=0` disables and
+ * is byte-identical to the predecessor (VC5B): no session is assigned a stable
+ * 10k bucket, no gate-advance decision runs, the `vector_cortex_rollout_assigned`
+ * / `vector_cortex_rollout_promotion_blocked` events are never emitted, and the
+ * prompt continues to be built by the predecessor VC5B renderer path (its goldens
+ * are unchanged). The assign/gate/emit functions are PURE — flag OFF gates the
+ * reporter + dashboard seam, never the arithmetic. This flag MUST also be a
+ * dashboard SETTINGS toggle (visible in config UI, never in EXCLUDED_SETTINGS),
+ * mirroring VC4A/VC4B/VC4C/VC5A/VC5B.
+ */
+export const VC5C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC5C");
+
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/src/config.ts

@@ -168,6 +168,7 @@ export {
   VC4C_ENABLED,
   VC5A_ENABLED,
   VC5B_ENABLED,
+  VC5C_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,