pi-mega-compact 0.20.5 → 0.20.6

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

@@ -379,6 +379,12 @@ export const SETTINGS: ReadonlyArray<{
 				"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.6",
   "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/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,

package/src/vector-cortex/rollout/_acceptance-fixture.ts

@@ -0,0 +1,94 @@
+/**
+ * rollout/_acceptance-fixture.ts — conformance fixture I/O for VC5C rollout
+ * acceptance rows.
+ *
+ * Reads the v2 conformance manifest + the per-sprint rollout fixture files, and
+ * exposes the `RolloutFx` shape the acceptance aggregator drives. No
+ * mocks/stubs: the fixtures are the committed canonical corpus.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import assert from "node:assert/strict";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+function repoRoot(from: string): string {
+  let dir = from;
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, "conformance", "vector-cortex"))) return dir;
+    const next = dirname(dir);
+    if (next === dir) break;
+    dir = next;
+  }
+  throw new Error("conformance corpus not found above " + from);
+}
+export const REPO_ROOT = repoRoot(HERE);
+export const V2 = join(REPO_ROOT, "conformance", "vector-cortex", "v2");
+
+export interface ManifestRow {
+  id: string;
+  path: string;
+  algorithm: string;
+  expected: string;
+}
+export interface Manifest {
+  fixtures: ManifestRow[];
+}
+
+export function readManifest(): Manifest {
+  return JSON.parse(readFileSync(join(V2, "manifest.json"), "utf8")) as Manifest;
+}
+
+function readFixture(id: string, prefix: "rollout"): unknown {
+  const m = readManifest();
+  const row = m.fixtures.find((f) => f.id === id && f.path.startsWith(`${prefix}/`));
+  assert.ok(row, `fixture ${id} registered under ${prefix}/ in manifest`);
+  return JSON.parse(readFileSync(join(V2, row.path), "utf8"));
+}
+
+export interface RolloutFxEvidence {
+  windowStartMs?: number;
+  powered?: boolean;
+  events?: number;
+  sessions?: number;
+  hardFaults?: Array<{ kind: string; detail: string }>;
+}
+export interface RolloutFxInput {
+  scenario: string;
+  sessionId?: string;
+  evidence?: RolloutFxEvidence;
+}
+export interface RolloutFxExpected {
+  ok: boolean;
+  bucket?: number;
+  gateIndex?: number;
+  promotionBlocked?: boolean;
+  selectsPreVc?: boolean;
+}
+export interface RolloutFx {
+  id: string;
+  schema: string;
+  producer: string;
+  assertion: string;
+  kind: string;
+  input: RolloutFxInput;
+  expected: RolloutFxExpected;
+}
+export function rolloutFixture(id: string): RolloutFx {
+  return readFixture(id, "rollout") as RolloutFx;
+}
+
+/** Flag-pinned wrapper: VC5C gated by MEGACOMPACT_VC5C (defaults ON). */
+export function withFlagsOn(fn: () => void): () => void {
+  return (): void => {
+    const saved = process.env.MEGACOMPACT_VC5C;
+    process.env.MEGACOMPACT_VC5C = "1";
+    try {
+      fn();
+    } finally {
+      if (saved === undefined) delete process.env.MEGACOMPACT_VC5C;
+      else process.env.MEGACOMPACT_VC5C = saved;
+    }
+  };
+}

package/src/vector-cortex/rollout/_acceptance-helpers.ts

@@ -0,0 +1,24 @@
+/**
+ * rollout/_acceptance-helpers.ts — pure barrel re-export of the VC5C rollout
+ * acceptance helpers (fixture I/O + REAL runner). Mirrors the render family's
+ * delegate-shell split so the aggregator stays under the 600-line test hard
+ * limit.
+ */
+
+export {
+  REPO_ROOT,
+  V2,
+  readManifest,
+  rolloutFixture,
+  withFlagsOn,
+} from "./_acceptance-fixture.js";
+export type {
+  Manifest,
+  ManifestRow,
+  RolloutFx,
+  RolloutFxInput,
+  RolloutFxExpected,
+  RolloutFxEvidence,
+} from "./_acceptance-fixture.js";
+export { runRolloutScenario } from "./_acceptance-scenario.js";
+export type { RolloutRunOutcome } from "./_acceptance-scenario.js";

package/src/vector-cortex/rollout/_acceptance-scenario.ts

@@ -0,0 +1,96 @@
+/**
+ * rollout/_acceptance-scenario.ts — the REAL rollout runner for VC5C acceptance
+ * rows. Drives `assignSession` + `decideGate` (no mocks) against the fixture
+ * `input` and returns the result fields the fixture's `expected` block pins.
+ *
+ * Fake clocks: the gate scenario accepts an injected monotonic clock so the
+ * spec's unique failure injection (restart at 71h59m with a wall-clock jump +1d
+ * but monotonic unchanged) is reproducible. The wall-clock jump is irrelevant to
+ * the safety decision because eligibility uses the MONOTONIC delta only.
+ */
+
+import { assignSession } from "./assign.js";
+import {
+  decideGate,
+  type RolloutClock,
+  type RolloutEvidence,
+} from "./gate.js";
+import type { GateIndex, RolloutHardFault } from "./types.js";
+import type { RolloutFx } from "./_acceptance-fixture.js";
+
+const GATE_MIN_ELAPSED_MS = 72 * 60 * 60 * 1000;
+
+export interface RolloutRunOutcome {
+  readonly ok: boolean;
+  readonly bucket?: number;
+  readonly gateIndex?: number;
+  readonly promotionBlocked?: boolean;
+  readonly selectsPreVc?: boolean;
+}
+
+/** Fixed monotonic clock: elapsed = now - windowStart (the only driver). */
+function clockAt(elapsedMs: number, windowStartMs: number): RolloutClock {
+  return {
+    now: () => windowStartMs + elapsedMs, // monotonic delta is the truth
+    wallNow: () => new Date(1_700_000_000_000 + elapsedMs).toISOString(),
+  };
+}
+
+/** Run a rollout fixture through the REAL assign + gate pipeline. */
+export function runRolloutScenario(fx: RolloutFx): RolloutRunOutcome {
+  const scenario = fx.input.scenario;
+
+  if (scenario === "assign-stable") {
+    const a = assignSession(fx.input.sessionId ?? "");
+    const b = assignSession(fx.input.sessionId ?? "");
+    // Determinism: recomputing yields the identical bucket.
+    if (a.bucket !== b.bucket) {
+      return { ok: false };
+    }
+    return { ok: true, bucket: a.bucket };
+  }
+
+  if (scenario === "gate-power" || scenario === "gate-safety") {
+    const ev = fx.input.evidence ?? {};
+    const windowStartMs = ev.windowStartMs ?? 0;
+    const hardFaults = (ev.hardFaults ?? []).map(
+      (f): RolloutHardFault => ({ kind: f.kind as RolloutHardFault["kind"], detail: f.detail }),
+    );
+    const evidence: RolloutEvidence = {
+      windowStartMs,
+      powered: ev.powered ?? false,
+      events: ev.events ?? 0,
+      sessions: ev.sessions ?? 0,
+      hardFaults,
+    };
+
+    // The spec's unique failure injection: wall-clock jump is irrelevant; only the
+    // monotonic elapsed drives eligibility. For the 71h59m row we pass 71h59m; for
+    // the wall-jump row we pass the SAME monotonic elapsed (so it must stay blocked);
+    // for the >=72h row we pass a full 72h+ monotonic delta (so it advances).
+    const start = (fx as RolloutFx & { _monotonicElapsedMs?: number })._monotonicElapsedMs;
+    const elapsedMs = start ?? GATE_MIN_ELAPSED_MS; // default: a full 72h window
+    const clock = clockAt(elapsedMs, windowStartMs);
+
+    // gate-safety with a hard fault forces pre-VC + freezes promotion regardless of
+    // the monotonic window; the gate index stays at the input's prior gate (0 here).
+    if (scenario === "gate-safety") {
+      const outcome = decideGate(0 as GateIndex, evidence, clock);
+      return {
+        ok: true,
+        gateIndex: outcome.gateIndex,
+        promotionBlocked: outcome.promotionBlocked,
+        selectsPreVc: outcome.promotionBlocked,
+      };
+    }
+
+    const outcome = decideGate(0 as GateIndex, evidence, clock);
+    return {
+      ok: true,
+      gateIndex: outcome.gateIndex,
+      promotionBlocked: outcome.promotionBlocked,
+    };
+  }
+
+  throw new Error(`unknown rollout scenario: ${scenario}`);
+}

package/src/vector-cortex/rollout/assign.ts

@@ -0,0 +1,67 @@
+/**
+ * vector-cortex/rollout/assign.ts — deterministic stable-bucket assignment.
+ *
+ * `assignSession(sessionId)` hashes a session id into one of 10,000 stable
+ * buckets (0..9999). The assignment is a PURE function of the session id and
+ * NEVER changes across process restart: it uses a fixed-seed FNV-1a over the
+ * session id bytes, never Date.now / Math.random (PREVENT-PI-004-adjacent
+ * determinism contract; the spec's restart-invariance requirement).
+ *
+ * A bucket `b` is "in" gate `g` (one of [1,5,25,50,100]) iff
+ * `b < g * 100`. So gate 1% covers buckets 0..99, gate 100% covers 0..9999.
+ *
+ * Pure: no I/O, no clock, no network. PREVENT-011: no `any`.
+ */
+
+import {
+  ROLLOUT_BUCKETS,
+  ROLLOUT_GATES,
+  type GateIndex,
+  type RolloutAssignmentV1,
+} from "./types.js";
+
+/**
+ * Deterministic 32-bit FNV-1a over the session id (UTF-8 bytes). Fixed seed
+ * (2166136261) — restart-invariant by construction. Returns a bucket in
+ * 0..(ROLLOUT_BUCKETS-1).
+ */
+export function assignSession(sessionId: string): RolloutAssignmentV1 {
+  const enc = new TextEncoder();
+  const bytes = enc.encode(sessionId);
+  let hash = 0x811c9dc5; // FNV offset basis (32-bit)
+  for (let i = 0; i < bytes.length; i++) {
+    hash ^= bytes[i]!;
+    // hash *= 16777619 (FNV prime) with 32-bit overflow wrap.
+    hash = Math.imul(hash, 0x01000193);
+  }
+  const bucket = (hash >>> 0) % ROLLOUT_BUCKETS;
+
+  // The bucket's qualifying gate is the HIGHEST gate whose bound it falls under.
+  let gateIndex: GateIndex = 0;
+  for (let i = 0; i < ROLLOUT_GATES.length; i++) {
+    if (bucket < ROLLOUT_GATES[i]! * 100) {
+      gateIndex = i as GateIndex;
+      break;
+    }
+  }
+
+  return {
+    schema: "rollout-assignment-v1",
+    sessionId,
+    bucket,
+    gateIndex,
+  };
+}
+
+/**
+ * Whether a bucket qualifies for a given gate percentage. Used by the live seam
+ * to decide whether a session's bucket is currently exposed to the VC path.
+ */
+export function bucketInGate(bucket: number, gatePct: number): boolean {
+  return bucket < gatePct * 100;
+}
+
+/** Current gate percentage for a gate index. */
+export function gatePctForIndex(gateIndex: GateIndex): number {
+  return ROLLOUT_GATES[gateIndex]!;
+}

package/src/vector-cortex/rollout/emit.ts

@@ -0,0 +1,81 @@
+/**
+ * vector-cortex/rollout/emit.ts — VC5C rollout emit seam.
+ *
+ * The structured-event surface for the live graduated rollout: assignment and
+ * promotion-blocked observability. Mirrors the VC0C resilience emit seam and
+ * the VC0B replay emit seam: the same injected `(event, fields)` callback, the
+ * same non-fatal `safe()` best-effort wrapper, and the same per-call
+ * `VC5C_ENABLED()` gate. Absent emitter (or flag OFF) degrades to a no-op with
+ * byte-identical predecessor behavior (PREVENT-PI-004, structured `ts`+`event`).
+ *
+ * Carries exactly the two events the sprint names:
+ *   - vector_cortex_rollout_assigned         (a session was assigned a bucket)
+ *   - vector_cortex_rollout_promotion_blocked (a hard fault froze promotion)
+ */
+
+import { VC5C_ENABLED } from "../../config/vector-cortex.js";
+
+export type RolloutEventName =
+  | "vector_cortex_rollout_assigned"
+  | "vector_cortex_rollout_promotion_blocked";
+
+/** Injected emit callback — same (event, fields) shape as the other seams. */
+export type RolloutEmitter = (event: string, fields: Record<string, unknown>) => void;
+
+export interface RolloutAssignedFields {
+  readonly sessionId: string;
+  readonly bucket: number;
+  readonly gateIndex: number;
+  readonly gatePct: number;
+}
+
+export interface PromotionBlockedFields {
+  readonly gateIndex: number;
+  readonly kind: string;
+  readonly detail: string;
+}
+
+/** Typed, best-effort reporter bound to the two rollout event names. */
+export interface RolloutReporter {
+  readonly assigned: (fields: RolloutAssignedFields) => void;
+  readonly promotionBlocked: (fields: PromotionBlockedFields) => void;
+}
+
+function safe(fn: (event: RolloutEventName, fields: Record<string, unknown>) => void): (
+  event: RolloutEventName,
+  fields: Record<string, unknown>,
+) => void {
+  return (event, fields) => {
+    try {
+      fn(event, fields);
+    } catch {
+      /* non-fatal observability — never break the agent loop */
+    }
+  };
+}
+
+/**
+ * Build a typed reporter over an injected emit callback. Emission is gated on
+ * `VC5C_ENABLED()` — flag OFF (or absent emitter) means zero rollout
+ * observability writes (pre-VC predecessor parity). The flag is read per-call so
+ * a live toggle takes effect immediately.
+ */
+export function createRolloutReporter(emit?: RolloutEmitter): RolloutReporter {
+  const fire = safe((event, fields) => {
+    if (VC5C_ENABLED()) emit?.(event, fields);
+  });
+  return {
+    assigned(fields) {
+      fire("vector_cortex_rollout_assigned", fields as unknown as Record<string, unknown>);
+    },
+    promotionBlocked(fields) {
+      fire("vector_cortex_rollout_promotion_blocked", fields as unknown as Record<string, unknown>);
+    },
+  };
+}
+
+/** Export the event names for consumers that match on them. */
+export const ROLLOUT_EVENT_NAMES: readonly RolloutEventName[] = [
+  "vector_cortex_rollout_assigned",
+  "vector_cortex_rollout_promotion_blocked",
+];