pi-mega-compact 0.20.5 → 0.20.7

package/src/dedup-audit.test-helpers.ts

@@ -0,0 +1,49 @@
+/**
+ * dedup-audit.test-helpers.ts — shared harness for the dedup audit trail tests.
+ *
+ * Extracted so dedup-audit.test.ts and dedup-audit-gating.test.ts share one
+ * temp-dir lifecycle and one events.log reader instead of duplicating them, and
+ * so each test file stays under the 300-line src/ soft limit.
+ *
+ * Hermetic: every store gets its own temp state dir, so no test can observe
+ * another's audit lines. No network (PREVENT-PI-004).
+ */
+
+import { mkdtempSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadDedupConfig, type DedupConfigShape } from "./config/dedup.js";
+import { defaultEventsPath, type DedupAuditEvent } from "./monitoring.js";
+
+/** Root temp dir shared by both audit test files (each run gets a subdir). */
+export const baseTmp = mkdtempSync(join(tmpdir(), "mc-dedup-audit-"));
+
+/** The live config with per-test overrides applied. */
+export function cfg(over: Partial<DedupConfigShape> = {}): DedupConfigShape {
+	return { ...loadDedupConfig(), ...over };
+}
+
+let seq = 0;
+
+/** A never-before-used state dir under `baseTmp`. */
+export function freshDir(): string {
+	return join(baseTmp, `run-${seq++}-${Math.floor(performance.now() * 1000)}`);
+}
+
+/** Read every dedup_audit line from a store's default events.log. */
+export function auditLines(stateDir: string): DedupAuditEvent[] {
+	const path = defaultEventsPath(stateDir);
+	if (!existsSync(path)) return [];
+	return readFileSync(path, "utf-8")
+		.split("\n")
+		.filter((l) => l.trim())
+		.map((l) => JSON.parse(l) as DedupAuditEvent)
+		.filter((e) => e.type === "dedup_audit");
+}
+
+/** A path whose parent directory can never be created: it sits under a FILE. */
+export function unwritablePath(): string {
+	const blocker = join(baseTmp, `blocker-${seq++}`);
+	writeFileSync(blocker, "not a directory");
+	return join(blocker, "sub", "events.log");
+}

package/src/monitoring.ts

@@ -204,3 +204,13 @@ export function logRecallQuality(path: string, ev: RecallQualityEvent): void {
     /* best-effort — never break the extension */
   }
 }
+
+// ---------------------------------------------------------------------------
+// Dedup audit trail (external-audit item #2)
+// ---------------------------------------------------------------------------
+// The event shape and its append helper are DEFINED in vectorStore/dedup-audit.ts,
+// co-located with the only recorder that emits them (this file already carries
+// decision events + the metrics snapshot + FP alerting and must stay under its
+// 300-line soft limit). Re-exported here so callers that treat monitoring.ts as
+// the events.log barrel — including the dashboard SSE tail — keep one import.
+export { logDedupAudit, type DedupAuditEvent } from "./vectorStore/dedup-audit.js";

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",
+];

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

@@ -0,0 +1,119 @@
+/**
+ * vector-cortex/rollout/gate.ts — monotonic graduated-gate advance decision.
+ *
+ * A gate advances exactly ONE step only when ALL conjuncts hold:
+ *   (elapsedWallClock >= 72h)  — measured on the MONOTONIC clock, not wall time
+ *   AND (powered sample available)
+ *   AND (events >= 10000)
+ *   AND (sessions >= 200)
+ *
+ * Promotion is strictly monotonic by one gate step. The unique failure
+ * injection (TRIAD_RESILIENCE.md): a wall-clock jump while the monotonic clock
+ * is unchanged does NOT advance — because the 72h eligibility is the MONOTONIC
+ * delta, not wall time. We therefore take an injected clock seam with SEPARATE
+ * monotonic and wall readings and never call Date.now() directly for the safety
+ * decision (PREVENT decorum: the host injects a testable fake clock).
+ *
+ * Pure arithmetic over injected evidence + clock; no I/O, no network.
+ * PREVENT-011: no `any`.
+ */
+
+import {
+  ROLLOUT_GATES,
+  type GateIndex,
+  type LiveOutcomeV1,
+  type RolloutHardFault,
+} from "./types.js";
+
+/** The 72h monotonic residency requirement (milliseconds). */
+export const GATE_MIN_ELAPSED_MS = 72 * 60 * 60 * 1000;
+/** Powered-sample availability gate (minimum events for a one-sided CI read). */
+export const GATE_MIN_EVENTS = 10_000;
+/** Minimum distinct sessions before a gate may advance. */
+export const GATE_MIN_SESSIONS = 200;
+
+/**
+ * Injected clock seam. `now()` is MONOTONIC time (fake-clock testable; never
+ * wall time) — eligibility windows/cooldowns use it. `wallNow()` is wall time
+ * used ONLY for records (the `decidedAt` field), never for eligibility.
+ */
+export interface RolloutClock {
+  /** Monotonic milliseconds (e.g. process monotonic time, fake-clock testable). */
+  now(): number;
+  /** Wall-clock ISO-8601 string for records only. */
+  wallNow(): string;
+}
+
+/** Default clock: real monotonic (performance.now) + wall (ISO). */
+export function defaultClock(): RolloutClock {
+  return {
+    now: () => performance.now(),
+    wallNow: () => new Date().toISOString(),
+  };
+}
+
+/** Evidence observed in the current observation window. */
+export interface RolloutEvidence {
+  /** Monotonic start of the observation window (ms). */
+  readonly windowStartMs: number;
+  /** Whether a powered (statistically adequate) sample is available. */
+  readonly powered: boolean;
+  /** Total observed events in the window. */
+  readonly events: number;
+  /** Total distinct sessions observed in the window. */
+  readonly sessions: number;
+  /** Hard failures observed (any entry freezes promotion → select C). */
+  readonly hardFaults: readonly RolloutHardFault[];
+}
+
+/**
+ * Decide the next live outcome for a decision epoch. Returns the (possibly
+ * advanced) gate index + the full evidence snapshot. Promotion monotonic by one
+ * step; a hard fault freezes promotion (promotionBlocked=true) and is reported
+ * for C-selection by the live seam.
+ *
+ * @param currentGate the gate index BEFORE this decision (0..4).
+ * @param evidence the observed window evidence.
+ * @param clock the injected monotonic/wall clock seam.
+ */
+export function decideGate(
+  currentGate: GateIndex,
+  evidence: RolloutEvidence,
+  clock: RolloutClock,
+): LiveOutcomeV1 {
+  const elapsedMs = Math.max(0, clock.now() - evidence.windowStartMs);
+
+  const hardFault = evidence.hardFaults.length > 0;
+  const eligible =
+    !hardFault &&
+    currentGate < (ROLLOUT_GATES.length - 1) &&
+    elapsedMs >= GATE_MIN_ELAPSED_MS &&
+    evidence.powered &&
+    evidence.events >= GATE_MIN_EVENTS &&
+    evidence.sessions >= GATE_MIN_SESSIONS;
+
+  // Monotonic by ONE step only.
+  const nextGate: GateIndex = eligible
+    ? ((currentGate + 1) as GateIndex)
+    : currentGate;
+
+  return {
+    schema: "live-outcome-v1",
+    gateIndex: nextGate,
+    gatePct: ROLLOUT_GATES[nextGate]!,
+    elapsedMs,
+    powered: evidence.powered,
+    events: evidence.events,
+    sessions: evidence.sessions,
+    promotionBlocked: hardFault,
+    decidedAt: clock.wallNow(),
+  };
+}
+
+/**
+ * Whether a hard fault should SELECT triad C (pre-VC path). Any hard causal/
+ * tool/anchor/exact failure does. Exposed so the live seam can branch cleanly.
+ */
+export function selectsPreVcPath(fault: RolloutHardFault | undefined): boolean {
+  return fault !== undefined;
+}

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

@@ -0,0 +1,111 @@
+/**
+ * vector-cortex/rollout/types.ts — VC5C live graduated-rollout contracts.
+ *
+ * A session is deterministically hashed into one of 10,000 stable buckets
+ * (0..9999). The current rollout gate is one of 1% / 5% / 25% / 50% / 100%.
+ * A bucket is "in" the current gate iff `bucket < gatePct * 100`. Assignment is
+ * a PURE function of the session id: it NEVER changes across process restart
+ * (no Date.now / Math.random — see `assign.ts`).
+ *
+ * Pure types + registered conformance IDs: no storage, no console, no network
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+
+/** Total stable buckets. Reassignment on restart is impossible by construction. */
+export const ROLLOUT_BUCKETS = 10_000;
+
+/**
+ * The five graduated gates, in promotion order. Index = step. Promotion is
+ * strictly monotonic by ONE step (never skipping a gate).
+ */
+export const ROLLOUT_GATES: readonly number[] = [1, 5, 25, 50, 100];
+
+/** The current gate index (0 = 1%, 4 = 100%). */
+export type GateIndex = 0 | 1 | 2 | 3 | 4;
+
+/**
+ * A rollout assignment: the stable bucket + the gate it currently qualifies for.
+ * `bucket` is fixed for the life of the session; `gateIndex` is the highest gate
+ * whose bucket bound the session falls under AT the decision epoch.
+ */
+export interface RolloutAssignmentV1 {
+  readonly schema: "rollout-assignment-v1";
+  /** Session id the assignment was derived from. */
+  readonly sessionId: string;
+  /** Stable bucket in 0..9999 (deterministic, restart-invariant). */
+  readonly bucket: number;
+  /** Current highest gate the bucket qualifies for (0..4). */
+  readonly gateIndex: GateIndex;
+}
+
+/**
+ * The live outcome of a rollout decision epoch: the current gate, the evidence
+ * counts observed, and whether promotion to the next gate is BLOCKED (hard
+ * failure froze promotion).
+ */
+export interface LiveOutcomeV1 {
+  readonly schema: "live-outcome-v1";
+  /** Current gate index (0..4). */
+  readonly gateIndex: GateIndex;
+  /** Current gate percentage (ROLLOUT_GATES[gateIndex]). */
+  readonly gatePct: number;
+  /** Monotonic wall-elapsed milliseconds in the observation window. */
+  readonly elapsedMs: number;
+  /** Whether a powered (statistically adequate) sample is available. */
+  readonly powered: boolean;
+  /** Total observed events in the window. */
+  readonly events: number;
+  /** Total distinct sessions observed in the window. */
+  readonly sessions: number;
+  /** True when a hard causal/tool/anchor/exact failure froze promotion. */
+  readonly promotionBlocked: boolean;
+  /** ISO-8601 timestamp of the decision (records only; never drives eligibility). */
+  readonly decidedAt: string;
+}
+
+/**
+ * Failure class that, on a hard occurrence, selects triad C (pre-VC path) and
+ * freezes promotion. These are the only classes that can freeze the rollout.
+ */
+export type RolloutHardFailure =
+  | "causal"
+  | "tool"
+  | "anchor"
+  | "exact";
+
+/** A hard failure observation (drives the C selection + promotion freeze). */
+export interface RolloutHardFault {
+  readonly kind: RolloutHardFailure;
+  readonly detail: string;
+}
+
+/**
+ * The two conformance events VC5C emits to the monitoring/events path. Mirrors
+ * how prior sprints emit (resilience/emit.ts, render/emit.ts).
+ */
+export const ROLLOUT_EVENTS = [
+  "vector_cortex_rollout_assigned",
+  "vector_cortex_rollout_promotion_blocked",
+] as const;
+
+export type RolloutEvent = (typeof ROLLOUT_EVENTS)[number];
+
+/** Emitter signature (structural match to prior sprints' `RenderEmitter`). */
+export type RolloutEmitter = (event: string, fields: Record<string, unknown>) => void;
+
+/**
+ * Registered rollout conformance ID range (ROL-001..020). The acceptance
+ * aggregator reads these rows from the v2 manifest and asserts each returns its
+ * manifest `ok`/`code`.
+ */
+export const ROL_IDS: readonly string[] = Array.from(
+  { length: 20 },
+  (_v, i) => `ROL-${String(i + 1).padStart(3, "0")}`,
+);
+
+/** Named VC5C rollout conformance assertions (the sprint's headline rows). */
+export const ROL_NAMED_IDS = [
+  "ROL-BUCKET-001",
+  "ROL-POWER-002",
+  "ROL-SAFETY-003",
+] as const;