pi-mega-compact 0.20.4 → 0.20.6

package/extensions/dashboard-client/src/tabs/VectorCortexTab.tsx

@@ -15,6 +15,8 @@ import {
 	fetchVectorCortexQuery,
 	fetchVectorCortexReconstruct,
 	fetchVectorCortexPlans,
+	fetchVectorCortexRender,
+	fetchVectorCortexRollout,
 	fetchVectorCortexShards,
 	fetchVectorCortexTopology,
 	resetVectorCortexBreaker,
@@ -24,11 +26,17 @@ import {
 	type VectorCortexQueryView,
 	type VectorCortexReconstructView,
 	type VectorCortexPlansView,
+	type VectorCortexRenderView,
+	type VectorCortexRolloutView,
 	type VectorCortexShardsView,
 	type VectorCortexTopologyView,
 } from "../api/vector-cortex";
 import { Card, CardContent, CardHeader, CardTitle } from "../components/ui/card";
 import { Badge } from "../components/ui/badge";
+import { Metric } from "./VectorCortexMetric";
+import { VectorCortexRenderCard } from "./VectorCortexRenderCard";
+import { VectorCortexRolloutCard } from "./VectorCortexRolloutCard";
+import { VectorCortexPlansCard } from "./VectorCortexPlansCard";
 
 function ModeChip({ mode, count }: { mode: string; count: number }): React.ReactElement {
 	return (
@@ -39,15 +47,6 @@ function ModeChip({ mode, count }: { mode: string; count: number }): React.React
 	);
 }
 
-function Metric({ label, value }: { label: string; value: string }): React.ReactElement {
-	return (
-		<div>
-			<div className="text-xs text-muted-foreground">{label}</div>
-			<div className="font-mono text-sm">{value}</div>
-		</div>
-	);
-}
-
 export default function VectorCortexTab(): React.ReactElement {
 	const [data, setData] = useState<VectorCortexEvaluationSummary | null>(null);
 	const [err, setError] = useState<string | null>(null);
@@ -60,6 +59,8 @@ export default function VectorCortexTab(): React.ReactElement {
 	const [shards, setShards] = useState<VectorCortexShardsView | null>(null);
 	const [reconstruct, setReconstruct] = useState<VectorCortexReconstructView | null>(null);
 	const [plans, setPlans] = useState<VectorCortexPlansView | null>(null);
+	const [render, setRender] = useState<VectorCortexRenderView | null>(null);
+	const [rollout, setRollout] = useState<VectorCortexRolloutView | null>(null);
 
 	const poll = useCallback(() => {
 		fetchVectorCortexEvaluation()
@@ -89,6 +90,12 @@ export default function VectorCortexTab(): React.ReactElement {
 		fetchVectorCortexPlans().then(setPlans).catch(() => {
 			/* plan manifest card is best-effort (VC5A) */
 		});
+		fetchVectorCortexRender().then(setRender).catch(() => {
+			/* render conformance card is best-effort (VC5B) */
+		});
+		fetchVectorCortexRollout().then(setRollout).catch(() => {
+			/* rollout card is best-effort (VC5C) */
+		});
 	}, []);
 
 	useEffect(() => {
@@ -403,35 +410,9 @@ export default function VectorCortexTab(): React.ReactElement {
 					)}
 				</CardContent>
 			</Card>
-			<Card>
-				<CardHeader>
-					<div className="flex items-center justify-between">
-						<CardTitle>Plan Manifests (VC5A)</CardTitle>
-						{plans?.enabled ? (
-							<Badge variant="success">ACTIVE</Badge>
-						) : (
-							<Badge variant="danger">OFF</Badge>
-						)}
-					</div>
-				</CardHeader>
-				<CardContent>
-					{!plans?.enabled ? (
-						<div className="vc-empty">PromptDagV1 + budgeted planner disabled (VC5A off).</div>
-					) : (
-					<>
-						<div className="grid grid-cols-2 gap-4 md:grid-cols-4">
-							<Metric label="DAG fixtures" value={String(plans.dagCount)} />
-							<Metric label="Plan fixtures" value={String(plans.plannerCount)} />
-							<Metric label="Plans exposed" value={String(plans.plans.length)} />
-						</div>
-						<div className="mt-3 text-xs text-muted-foreground">
-							Reader-only plan manifests only — no session payloads or prompt text.
-							Per-run plan outputs are staged in-memory this sprint.
-						</div>
-					</>
-					)}
-				</CardContent>
-			</Card>
+			<VectorCortexPlansCard view={plans} />
+			<VectorCortexRenderCard view={render} />
+			<VectorCortexRolloutCard view={rollout} />
 			<Card>
 				<CardHeader>
 					<div className="flex items-center justify-between">

package/extensions/dashboard-client/src/types/vector-cortex.ts

@@ -182,3 +182,29 @@ export interface VectorCortexPlansView {
   plans: VectorCortexPlanManifest[];
   updatedAt: string;
 }
+
+/** Reader-only render + provider-profile view (VC5B). */
+export interface VectorCortexRenderView {
+  enabled: boolean;
+  renderCount: number;
+  providerCount: number;
+  knownProfiles: string[];
+  updatedAt: string;
+}
+
+/**
+ * Reader-only live graduated-rollout view (VC5C, GET /api/vector-cortex/rollout).
+ * Aggregate only — current gate, bucket count, sessions/events counts, promotion
+ * state. Never session payloads or bucket→session mappings.
+ */
+export interface VectorCortexRolloutView {
+  enabled: boolean;
+  gateIndex: number;
+  gatePct: number;
+  buckets: number;
+  bucketCount: number;
+  events: number;
+  sessions: number;
+  promotionBlocked: boolean;
+  updatedAt: string;
+}

package/extensions/dashboard-server/api-contracts/vector-cortex.ts

@@ -297,7 +297,58 @@ export interface VectorCortexPlansView {
 }
 
 /**
- * Reader-only occurrence-ledger view for GET /api/vector-cortex/ledger (VC1B).
+ * Reader-only render/profile view for GET /api/vector-cortex/render (VC5B).
+ * Reports the registered render (REN-001..) and provider-profile (PRO-001..)
+ * identifier counts + the known provider-profile keys. NEVER exposes rendered
+ * node bytes, prompt text, or the canonical outbound request (reader-only,
+ * SECURITY_PRIVACY: the exact ledger is not training data).
+ */
+export interface VectorCortexRenderView {
+  /** Whether the VC5B render + provider-profile flag is enabled. */
+  readonly enabled: boolean;
+  /** Count of registered render fixtures (REN-001..). */
+  readonly renderCount: number;
+  /** Count of registered provider-profile fixtures (PRO-001..). */
+  readonly providerCount: number;
+  /** Known base provider-profile keys (provider//model), reader-only. */
+  readonly knownProfiles: readonly string[];
+  /** ISO timestamp of the snapshot. */
+  readonly updatedAt: string;
+}
+
+/**
+ * Reader-only live graduated-rollout view for GET /api/vector-cortex/rollout
+ * (VC5C). Purely an enabled-flag + aggregate over the rollout state — current
+ * gate, bucket count, sessions/events counts, and promotion-blocked state.
+ * Reader-only: NEVER exposes session payloads, prompt text, or bucket→session
+ * mappings (reader-only, SECURITY_PRIVACY). The rollout evidence is in-memory in
+ * this sprint (no durable store), so when no epoch has been observed the
+ * aggregates are truthfully zero. Non-fatal: a missing state degrades to
+ * `enabled:false`.
+ */
+export interface VectorCortexRolloutView {
+  /** Whether the VC5C live graduated-rollout flag is enabled. */
+  readonly enabled: boolean;
+  /** Current gate index (0..4). */
+  readonly gateIndex: number;
+  /** Current gate percentage (ROLLOUT_GATES[gateIndex]). */
+  readonly gatePct: number;
+  /** Total stable buckets (10,000). */
+  readonly buckets: number;
+  /** Count of buckets currently exposed under the active gate. */
+  readonly bucketCount: number;
+  /** Total observed events in the window. */
+  readonly events: number;
+  /** Total distinct sessions observed in the window. */
+  readonly sessions: number;
+  /** True when a hard failure froze promotion. */
+  readonly promotionBlocked: boolean;
+  /** ISO timestamp of the snapshot. */
+  readonly updatedAt: string;
+}
+
+/**
+ * Reader-only occurrence-ledger identity view for GET /api/vector-cortex/ledger (VC1B).
  * Built on the LedgerReader capability surface. Exposes occurrence IDENTITY
  * (seq/eventId/kind/digest/toolCallId) and the per-session high-water/count —
  * NEVER sourceBytes or prompt text, honoring the reader-only no-ledger-text rule.

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

@@ -373,6 +373,18 @@ export const SETTINGS: ReadonlyArray<{
 				"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-render.ts

@@ -0,0 +1,49 @@
+/**
+ * dashboard-server/routes-vector-cortex-render.ts — VC5B render + provider-profile
+ * dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/render returning the registered render
+ * (REN-001..020) and provider-profile (PRO-001..015) identifier counts plus the
+ * known base provider-profile keys. NEVER exposes rendered node bytes, prompt
+ * text, or the canonical outbound request (reader-only, SECURITY_PRIVACY).
+ * Flag-gated on MEGACOMPACT_VC5B: `enabled:false` when off (byte-identical to
+ * the pre-VC5B predecessor).
+ *
+ * Guardrails: PREVENT-PI-004 (local in-process state only), PREVENT-011 (no
+ * `any`), reader-only aggregate (counts + profile keys only).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import { VC5B_ENABLED } from "../../src/config.js";
+import { REN_IDS } from "../../src/vector-cortex/render/types.js";
+import { PRO_IDS } from "../../src/vector-cortex/provider/types.js";
+import { KNOWN_PROVIDER_KEYS } from "../../src/vector-cortex/provider/registry.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import type { VectorCortexRenderView } from "./api-contracts/vector-cortex.js";
+
+/** Reader-only GET /api/vector-cortex/render (VC5B). */
+export function handleVectorCortexRender(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+  if (path !== "/api/vector-cortex/render") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC5B_ENABLED();
+  const body: VectorCortexRenderView = {
+    enabled,
+    renderCount: enabled ? REN_IDS.length : 0,
+    providerCount: enabled ? PRO_IDS.length : 0,
+    knownProfiles: enabled ? KNOWN_PROVIDER_KEYS : [],
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return 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

@@ -23,3 +23,5 @@ export { handleVectorCortexShards } from "./routes-vector-cortex-shards.js";
 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

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

package/extensions/dashboard-server/server.ts

@@ -67,6 +67,8 @@ import {
 	handleVectorCortexResidual,
 	handleVectorCortexReconstruct,
 	handleVectorCortexPlans,
+	handleVectorCortexRender,
+	handleVectorCortexRollout,
 	handleStatic,
 } from "./routes.js";
 
@@ -313,6 +315,8 @@ export async function launchDashboardServer(
 		if (handleVectorCortexResidual(req, res, ctx)) return;
 		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-context/vector-cortex.ts

@@ -0,0 +1,163 @@
+/**
+ * mega-context/vector-cortex.ts — VC5B delegation seam (the sprint's production
+ * ownership: `extensions/mega-context/vector-cortex.ts`).
+ *
+ * This is the ONLY extension-side surface VC5B owns. It delegates to the pi-
+ * agnostic `src/vector-cortex/render` + `src/vector-cortex/provider` logic and
+ * wires the two structured events the sprint emits:
+ *   - `vector_cortex_render_validated`  — a render passed validation and will be
+ *     prepended via the host `before_agent_start` systemPrompt seam.
+ *   - `vector_cortex_provider_bypassed` — an unknown provider/profile forced a
+ *     clean bypass (triad C, the predecessor prompt path).
+ *
+ * GUARDRAIL PREVENT-PI-003 (critical): the rendered compacted context is placed
+ * via the host `before_agent_start` systemPrompt PREPEND seam — it is NEVER
+ * emitted as a `role:"system"` conversation message. The renderer returns a
+ * `RenderManifestV1`, not a raw system-role payload; this seam composes the
+ * manifest's prepend into `event.systemPrompt`.
+ *
+ * The context handler (extensions/mega-events/context-handler.ts) is 228 lines
+ * (already a delegate shell) and under the extension hard limit, so NO split was
+ * required — VC5B delegates from here rather than modifying that handler.
+ *
+ * Pi runtime adapter: imports only pi runtime types + the VC5B logic. Flag-gated
+ * on `VC5B_ENABLED()`; flag OFF is byte-identical to the predecessor (VC5A state
+ * — the DAG/plan path), so this seam returns the host's unmodified systemPrompt.
+ */
+
+import type { ExtensionAPI, ExtensionContext, BeforeAgentStartEvent } from "@earendil-works/pi-coding-agent";
+
+import { VC5B_ENABLED } from "../../src/config/vector-cortex.js";
+import { resolveProviderProfile } from "../../src/vector-cortex/provider/registry.js";
+import { renderPrompt } from "../../src/vector-cortex/render/renderer.js";
+import { validateRender } from "../../src/vector-cortex/render/validator.js";
+import type { RenderInput, RenderManifestV1, CanonicalOutboundRequest } from "../../src/vector-cortex/render/types.js";
+import type { ProviderProfileBundle } from "../../src/vector-cortex/provider/types.js";
+
+/** An injected emit callback — the same (event, fields) shape as the src seams. */
+export type VectorCortexEmit = (event: string, fields: Record<string, unknown>) => void;
+
+/** The VC5B seam result handed back to the before_agent_start handler. */
+export interface VectorCortexRenderOutcome {
+  readonly validated: boolean;
+  readonly bypassed: boolean;
+  readonly manifest: RenderManifestV1 | null;
+  /** The text to prepend to the host systemPrompt (empty when not VC5B). */
+  readonly systemPromptPrepend: string;
+  readonly triad: "A" | "B" | "C";
+}
+
+/**
+ * Run the full VC5B render+validate pipeline. Returns a structured outcome the
+ * `before_agent_start` handler composes into the host systemPrompt. On a clean
+ * bypass (unknown profile) it emits `vector_cortex_provider_bypassed` and the
+ * host uses the predecessor prompt path (triad C). On a validated render it
+ * emits `vector_cortex_render_validated` (triad A).
+ *
+ * All emits are best-effort and non-fatal; the flag gates zero observability
+ * writes when OFF (byte-identical to predecessor).
+ */
+export function runVectorCortexRender(
+  input: RenderInput,
+  emit?: VectorCortexEmit,
+): VectorCortexRenderOutcome {
+  const fire = (event: string, fields: Record<string, unknown>): void => {
+    try {
+      if (VC5B_ENABLED()) emit?.(event, fields);
+    } catch {
+      /* non-fatal observability — never break the agent loop */
+    }
+  };
+
+  const rendered = renderPrompt(input);
+  if (!rendered.ok) {
+    // Clean bypass (unknown profile) or a hard order mismatch. Bypass emits the
+    // provider-bypassed event and defers to the predecessor prompt path.
+    fire("vector_cortex_provider_bypassed", {
+      code: rendered.code,
+      triad: rendered.triad,
+    });
+    return {
+      validated: false,
+      bypassed: true,
+      manifest: null,
+      systemPromptPrepend: "",
+      triad: rendered.triad,
+    };
+  }
+
+  // Validate the canonical request BEFORE invocation. The profile at validation
+  // time must match the manifest profile (the UNIQUE injection swaps it → C).
+  const sourceToolBytes = new Map<string, string>();
+  for (const t of rendered.request.tools) sourceToolBytes.set(t.id, t.bytes);
+  const pinnedToolLengths = new Map<string, number>();
+  for (const t of rendered.request.tools) {
+    pinnedToolLengths.set(t.id, Buffer.byteLength(t.bytes, "utf8"));
+  }
+  const check = validateRender(
+    rendered.manifest,
+    rendered.request,
+    input.profile,
+    sourceToolBytes,
+    pinnedToolLengths,
+  );
+
+  if (!check.ok) {
+    fire("vector_cortex_provider_bypassed", {
+      code: check.code,
+      triad: check.triad,
+    });
+    return {
+      validated: false,
+      bypassed: true,
+      manifest: rendered.manifest,
+      systemPromptPrepend: "",
+      triad: check.triad,
+    };
+  }
+
+  fire("vector_cortex_render_validated", {
+    profileId: rendered.manifest.profileId,
+    requestDigest: rendered.manifest.requestDigest,
+    nodeCount: rendered.manifest.nodeOrder.length,
+    triad: "A",
+  });
+  return {
+    validated: true,
+    bypassed: false,
+    manifest: rendered.manifest,
+    systemPromptPrepend: rendered.request.systemPromptPrepend,
+    triad: "A",
+  };
+}
+
+/**
+ * Register the VC5B `before_agent_start` prepend seam on the host. Flag OFF →
+ * byte-identical to the predecessor (returns the host's unmodified systemPrompt).
+ * The composed prepend is placed on the HOST systemPrompt, never as role:system.
+ */
+export function registerVectorCortexRender(
+  pi: ExtensionAPI,
+  _ctx: ExtensionContext,
+  emit?: VectorCortexEmit,
+): void {
+  pi.on("before_agent_start", (event: BeforeAgentStartEvent, ctx: ExtensionContext) => {
+    if (!VC5B_ENABLED()) return; // byte-identical predecessor behavior
+    // The host supplies the active (provider, model) so the seam can resolve the
+    // profile. Until the host passes a render input, the seam stays inert.
+    const pending = (ctx as unknown as { megaCompactVectorCortexRender?: RenderInput }).megaCompactVectorCortexRender;
+    if (pending === undefined) return;
+    const outcome = runVectorCortexRender(pending, emit);
+    if (!outcome.validated) return; // bypass / mismatch → predecessor path
+    return { systemPrompt: `${event.systemPrompt}\n\n${outcome.systemPromptPrepend}` };
+  });
+}
+
+/** Resolve a provider profile by (provider, model) for the host to pass in. */
+export function resolveProfile(provider: string, model: string): ProviderProfileBundle | null {
+  const res = resolveProviderProfile(provider, model);
+  return res.ok ? res.bundle : null;
+}
+
+/** Re-export the core types the host adapter consumes (contract-first). */
+export type { RenderInput, RenderManifestV1, CanonicalOutboundRequest };

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,
+  };
+}