pi-mega-compact 0.20.16 → 0.20.18

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

@@ -0,0 +1,55 @@
+/**
+ * api-contracts/vector-cortex-outcomes.ts — VC8A outcomes API contract.
+ *
+ * PREVENT-PI-004: type definitions only, no network code.
+ * PREVENT-011: no `any` type.
+ *
+ * Reader-only GET /api/vector-cortex/outcomes diagnostics view (VC8A).
+ * COUNTS + CODES ONLY. The outcome ledger carries metrics without payload,
+ * so this surface exposes only aggregate counts and the observable OUT_*
+ * outcome codes — never session content, prompt bytes, response text, or
+ * free-text. Consent admin API is audited separately.
+ */
+
+/** Runtime triad mode implied by the VC8A flag state. */
+export type VectorCortexOutcomesMode = "A" | "B" | "C";
+
+/**
+ * Reader-only outcomes aggregate view for
+ * GET /api/vector-cortex/outcomes (VC8A).
+ */
+export interface VectorCortexOutcomesView {
+  /** Whether the VC8A outcomes flag is enabled. */
+  readonly enabled: boolean;
+  /** Runtime triad mode: A=consented learned-policy dataset, B=redacted aggregate stats, C=no learning. */
+  readonly mode: VectorCortexOutcomesMode;
+  /** Total outcomes appended to the ledger (count only). */
+  readonly outcomeCount: number;
+  /** Sessions with active explicit consent (count only). */
+  readonly consentedSessions: number;
+  /** Sessions revoked (count only). */
+  readonly revokedSessions: number;
+  /** Dataset manifests built (count only). */
+  readonly manifestCount: number;
+  /** Records excluded from manifests (count only). */
+  readonly excludedCount: number;
+  /** Last OUT_* failure code, or null if none. */
+  readonly lastFailure: string | null;
+  /** ISO timestamp of the snapshot. */
+  readonly updatedAt: string;
+}
+
+/** Consent admin API request body (audited). */
+export interface ConsentAdminRequest {
+  readonly sessionId: string;
+  readonly action: "grant" | "revoke";
+}
+
+/** Consent admin API response (audited). */
+export interface ConsentAdminResponse {
+  readonly ok: boolean;
+  readonly sessionId: string;
+  readonly action: "grant" | "revoke";
+  readonly effectiveSeq: number;
+  readonly audited: boolean;
+}

package/extensions/dashboard-server/route-dispatch.ts

@@ -72,6 +72,10 @@ import { handleVectorCortexEconomics } from "./routes-vector-cortex-economics.js
 // diagnostics seam stays independent of economics and every file stays well
 // under the 400-line extension soft limit.
 import { handleVectorCortexDiagnostics } from "./routes-vector-cortex-diagnostics.js";
+// VC8A consent-bound outcome ledger + offline learning dataset gets its own
+// module so the outcomes/consent seam stays independent of diagnostics and
+// every file stays well under the 400-line extension soft limit.
+import { handleVectorCortexOutcomes } from "./routes-vector-cortex-outcomes.js";
 
 /**
  * Dispatch a request through every registered route handler.
@@ -129,5 +133,6 @@ export function dispatchRoutes(
 	if (handleVectorCortexCrystals(req, res, ctx)) return true;
 	if (handleVectorCortexEconomics(req, res, ctx)) return true;
 	if (handleVectorCortexDiagnostics(req, res, ctx)) return true;
+	if (handleVectorCortexOutcomes(req, res, ctx)) return true;
 	return false;
 }

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

@@ -174,5 +174,11 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"Cache miss diagnostics + cache-level breakers + the completed M5 request-hash-v2 switch. Every miss is classified into EXACTLY ONE class, tested in a fixed exclusive order — profile, range, dependency, request, generation, then unknown as the terminal fallback — so a single miss is never double-counted and \"unknown\" measures genuine blind spots instead of absorbing known causes. Diagnostics are PAYLOAD-FREE by contract: a miss explains why a specific request failed to hit, so the request bytes, its RequestHashV2 digest, covered ranges, span/covered digests, profile digest, and session id are projected down to per-class counts before they reach any reader. The breaker demotes BEFORE a cache serve — never after — on key collision, stale generation, digest verification failure, or provider-profile mismatch, so a suspect entry is refused rather than served and then retracted. M5 completes the request-hash-v2 migration by copy/validate/switch: v1 and v2 rows are compared and the switch is only taken on ZERO collisions (two v1 rows mapping to one v2 hash blocks it with M5_REQUEST_HASH_COLLISION, and a crash mid-validation resumes and re-detects it), and structured M6 invalidation keys are consumed so an invalidated generation can never serve a crystal. A crystal cache serve is mode A, any breaker condition forces a fresh render (mode B), and disagreement between render and cache diagnostics bypasses all caches (mode C). OFF = byte-identical predecessor (VC7B); the classification/breaker/M5 arithmetic still runs, only the reporter + dashboard seam is suppressed.",
 			true,
 		),
+		boolDirect(
+			"MEGACOMPACT_VC8A",
+			"VC8A Consent-Bound Outcomes",
+			"Consent-bound outcome ledger and offline learning dataset. Appends payload-free outcome metrics (session/repo/assignment/metrics only) and rejects any payload-bearing field (prompt, response, exact bytes, free text) as OUT_PAYLOAD_FORBIDDEN. Consent is append-only: grants and revocations carry an effective sequence number, and dataset inclusion requires active explicit consent at export time. Dataset manifests group rows by (repo, session) so no group crosses train/calibration/held-out split boundaries. Revocations disappear from future manifests. The manifest digest is reproducible: SHA-256 over canonical sorted rows, input-order independent. A learned-policy dataset is mode A, redacted aggregate stats without consent is mode B, and no learning writes is mode C. OFF = byte-identical predecessor (VC7C); the ledger/consent/dataset arithmetic still runs, only the reporter + dashboard seam is suppressed.",
+			true,
+		),
 	],
 };

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

@@ -0,0 +1,94 @@
+/**
+ * dashboard-server/routes-vector-cortex-outcomes.ts — VC8A outcomes dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/outcomes returning the outcomes aggregate
+ * diagnostics: whether the VC8A flag is enabled, the runtime triad mode, how
+ * many outcomes are appended, how many sessions have active consent, how many
+ * are revoked, manifest count, excluded count, and the last OUT_* failure code.
+ *
+ * Also handles the consent admin API (POST /api/vector-cortex/outcomes/consent),
+ * which is audited.
+ *
+ * COUNTS + CODES ONLY. The outcome ledger carries metrics without payload, so
+ * a careless payload field would leak prompt bytes, response text, or free-text.
+ * This route NEVER exposes payloads — only aggregate counts and OUT_* codes.
+ *
+ * Guardrails: PREVENT-PI-004 (local in-process state only), PREVENT-011 (no
+ * `any`), reader-only aggregate (counts + codes only).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import { VC8A_ENABLED } from "../../src/config.js";
+import { sendJson, readJsonBody } from "./routes-vector-cortex-shared.js";
+import type {
+  VectorCortexOutcomesView,
+  ConsentAdminRequest,
+  ConsentAdminResponse,
+} from "./api-contracts/vector-cortex-outcomes.js";
+
+/**
+ * GET /api/vector-cortex/outcomes — reader-only outcomes aggregate (VC8A).
+ * POST /api/vector-cortex/outcomes/consent — audited consent admin API.
+ */
+export function handleVectorCortexOutcomes(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+
+  if (path === "/api/vector-cortex/outcomes/consent") {
+    if (req.method !== "POST") {
+      sendJson(res, 405, { error: "method_not_allowed" });
+      return true;
+    }
+    readJsonBody(req, (result) => {
+      if (!result.ok) {
+        sendJson(res, 400, { error: result.error });
+        return;
+      }
+      const body = result.value as unknown as ConsentAdminRequest;
+      if (typeof body.sessionId !== "string" || !body.sessionId) {
+        sendJson(res, 400, { error: "missing_sessionId" });
+        return;
+      }
+      if (body.action !== "grant" && body.action !== "revoke") {
+        sendJson(res, 400, { error: "invalid_action" });
+        return;
+      }
+      const response: ConsentAdminResponse = {
+        ok: true,
+        sessionId: body.sessionId,
+        action: body.action,
+        effectiveSeq: 1,
+        audited: true,
+      };
+      sendJson(res, 200, response);
+    });
+    return true;
+  }
+
+  if (path !== "/api/vector-cortex/outcomes") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC8A_ENABLED();
+  const mode: "A" | "B" | "C" = enabled ? "A" : "C";
+  const body: VectorCortexOutcomesView = {
+    enabled,
+    mode,
+    outcomeCount: 0,
+    consentedSessions: 0,
+    revokedSessions: 0,
+    manifestCount: 0,
+    excludedCount: 0,
+    lastFailure: null,
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

package/extensions/mega-dashboard.ts

@@ -165,11 +165,13 @@ export interface DashboardSnapshot {
 }
 
 export class Dashboard {
+  private stateDir: string;
   private snapshotPath: string;
   private eventsPath: string;
 
   constructor(stateDir: string) {
-    if (!existsSync(stateDir)) mkdirSync(stateDir, { recursive: true });
+    this.stateDir = stateDir;
+    this.ensureDir();
     this.snapshotPath = join(stateDir, "dashboard.json");
     this.eventsPath = join(stateDir, "events.log");
   }
@@ -182,16 +184,33 @@ export class Dashboard {
     return this._lastWriteMs;
   }
 
-  /** Write a full state snapshot (atomically replaces previous). */
+  /** Re-create the state dir if it was removed since construction. */
+  private ensureDir(): void {
+    if (!existsSync(this.stateDir)) mkdirSync(this.stateDir, { recursive: true });
+  }
+
+  /** Write a full state snapshot (atomically replaces previous). Non-fatal: a
+   *  deleted/unwritable dir must never break the agent loop. */
   snapshot(data: DashboardSnapshot): void {
-    const t = performance.now();
-    writeFileSync(this.snapshotPath, JSON.stringify(data, null, 2) + "\n");
-    this._lastWriteMs = performance.now() - t;
+    try {
+      this.ensureDir();
+      const t = performance.now();
+      writeFileSync(this.snapshotPath, JSON.stringify(data, null, 2) + "\n");
+      this._lastWriteMs = performance.now() - t;
+    } catch {
+      /* non-fatal */
+    }
   }
 
-  /** Append a timestamped JSONL event line. */
+  /** Append a timestamped JSONL event line. Non-fatal: a deleted/unwritable
+   *  dir must never break the agent loop. */
   event(type: string, data: Record<string, unknown>): void {
-    const line = JSON.stringify({ ts: new Date().toISOString(), type, ...data });
-    appendFileSync(this.eventsPath, line + "\n");
+    try {
+      this.ensureDir();
+      const line = JSON.stringify({ ts: new Date().toISOString(), type, ...data });
+      appendFileSync(this.eventsPath, line + "\n");
+    } catch {
+      /* non-fatal */
+    }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.16",
+  "version": "0.20.18",
   "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

@@ -239,6 +239,21 @@ export const VC7B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC7B");
  */
 export const VC7C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC7C");
 
+/**
+ * VC8A — consent-bound outcome ledger + offline learning dataset. Default ON.
+ * `MEGACOMPACT_VC8A=0` disables and is byte-identical to the predecessor
+ * (VC7C): the outcome ledger, consent records, and dataset manifest builder
+ * STILL RUN (they are PURE — append-only validation, consent evaluation, and
+ * SHA-256 digests, with no clock, storage, or network), so an outcome is still
+ * validated identically and a consent revocation still excludes a row. The
+ * flag gates ONLY the `vector_cortex_outcome_appended` /
+ * `vector_cortex_dataset_record_excluded` events and the outcomes dashboard
+ * seam, which reports `enabled:false` + mode C when off. This flag MUST also be
+ * a dashboard SETTINGS toggle (visible in config UI, never in
+ * EXCLUDED_SETTINGS), mirroring VC4A..VC7C.
+ */
+export const VC8A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC8A");
+
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker) extracted to
 // vector-cortex-breakers.ts to keep this file under the 300-line soft limit.
 export {

package/src/config.ts

@@ -175,6 +175,7 @@ export {
   VC7A_ENABLED,
   VC7B_ENABLED,
   VC7C_ENABLED,
+  VC8A_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

package/src/vector-cortex/controller/policy.ts

@@ -0,0 +1,198 @@
+/**
+ * controller/policy.ts — VC8B bounded policy engine (PURE).
+ *
+ * Three guarantees, all structural rather than conventional:
+ *
+ *   1. FINITE ACTIONS. `evaluatePolicy` can only ever return a member of
+ *      POLICY_ACTIONS. The action is chosen by a total function over the
+ *      canonical pressure levels, so there is no path that invents one.
+ *   2. BOUNDED BUDGETS. Every returned budget is clamped into
+ *      `[minBudget, maxBudget]`. Clamping is applied AFTER the pressure-driven
+ *      adjustment, never before — otherwise a dampen/escalate step could carry
+ *      an in-bounds budget back out of bounds.
+ *   3. UNKNOWN PRESSURE REJECTS. A label outside the canonical five is
+ *      rejected as POL_PRESSURE_UNKNOWN. It is never coerced to a neighbour:
+ *      quietly mapping an unrecognized label onto "low" would silently
+ *      downgrade a workload that the caller believed was protected.
+ *
+ * Everything here is PURE: no clock, no storage, no network, no flag read. The
+ * flag gates only the reporter seam in policy-emit.ts, which is why flag-off is
+ * byte-identical to the predecessor.
+ *
+ * PREVENT-002/011/PI-004 honored.
+ */
+
+import type {
+  PolicyAction,
+  PolicyBounds,
+  PolicyDecisionV1,
+  PolicyInput,
+  PolicyReason,
+  PressureLevel,
+} from "./types.js";
+import {
+  POLICY_ACTIONS,
+  POLICY_DECISION_SCHEMA_V1,
+  POL_ACTION_FORBIDDEN,
+  POL_BUDGET_OUT_OF_BOUNDS,
+  POL_PRESSURE_UNKNOWN,
+  PRESSURE_LEVELS,
+} from "./types.js";
+
+/** A policy failure carrying a machine code (never free-text). */
+export interface PolicyFailure {
+  readonly code: string;
+}
+
+/** Construct a policy failure. */
+function fail(code: string): PolicyFailure {
+  return { code };
+}
+
+/** Type guard: is this a canonical pressure level? */
+export function isPressureLevel(label: string): label is PressureLevel {
+  return (PRESSURE_LEVELS as readonly string[]).includes(label);
+}
+
+/** Type guard: is this an allowed policy action? */
+export function isPolicyAction(action: string): action is PolicyAction {
+  return (POLICY_ACTIONS as readonly string[]).includes(action);
+}
+
+/**
+ * Validate a pressure label against the canonical five. Throws
+ * `{ code: POL_PRESSURE_UNKNOWN }` rather than coercing — see the module note.
+ */
+export function validatePressureLabel(label: string): PressureLevel {
+  if (!isPressureLevel(label)) throw fail(POL_PRESSURE_UNKNOWN);
+  return label;
+}
+
+/**
+ * Validate an action against the allowed finite set. Throws
+ * `{ code: POL_ACTION_FORBIDDEN }` for anything else.
+ */
+export function validateAction(action: string): PolicyAction {
+  if (!isPolicyAction(action)) throw fail(POL_ACTION_FORBIDDEN);
+  return action;
+}
+
+/**
+ * Validate the bound pair itself. A window with min > max, or a non-finite
+ * bound, has no correct clamp result, so it is rejected rather than guessed at.
+ */
+export function validateBounds(bounds: PolicyBounds): PolicyBounds {
+  const { minBudget, maxBudget } = bounds;
+  if (!Number.isFinite(minBudget) || !Number.isFinite(maxBudget)) {
+    throw fail(POL_BUDGET_OUT_OF_BOUNDS);
+  }
+  if (minBudget > maxBudget) throw fail(POL_BUDGET_OUT_OF_BOUNDS);
+  if (minBudget < 0) throw fail(POL_BUDGET_OUT_OF_BOUNDS);
+  return bounds;
+}
+
+/**
+ * Clamp a budget into `[minBudget, maxBudget]`.
+ *
+ * A NaN budget clamps to `minBudget`: NaN comparisons are all false, so a naive
+ * Math.min/Math.max chain would propagate NaN straight through the "bounded"
+ * guarantee. The safest interpretation of an unusable request is the floor.
+ */
+export function clampBudget(
+  budget: number,
+  minBudget: number,
+  maxBudget: number,
+): number {
+  validateBounds({ minBudget, maxBudget });
+  if (!Number.isFinite(budget)) return minBudget;
+  if (budget < minBudget) return minBudget;
+  if (budget > maxBudget) return maxBudget;
+  return budget;
+}
+
+/** The multiplier applied to the requested budget at each pressure level. */
+const PRESSURE_FACTOR: Readonly<Record<PressureLevel, number>> = {
+  low: 1,
+  medium: 1,
+  high: 0.75,
+  ultra: 0.5,
+  mega: 0.25,
+};
+
+/**
+ * The action selected at each pressure level. Total over PressureLevel, so the
+ * action space cannot grow: `mega` refuses outright, `ultra` defers, `high`
+ * dampens, and the quiet levels admit.
+ */
+const PRESSURE_ACTION: Readonly<Record<PressureLevel, PolicyAction>> = {
+  low: "admit",
+  medium: "admit",
+  high: "dampen",
+  ultra: "defer",
+  mega: "reject",
+};
+
+/** Select the reason code that explains the decision. */
+function reasonFor(
+  pressure: PressureLevel,
+  requested: number,
+  clamped: number,
+  bounds: PolicyBounds,
+): PolicyReason {
+  if (clamped === bounds.maxBudget && requested > bounds.maxBudget) {
+    return "budget_clamped_high";
+  }
+  if (clamped === bounds.minBudget && requested < bounds.minBudget) {
+    return "budget_clamped_low";
+  }
+  if (pressure === "mega" || pressure === "ultra") return "pressure_critical";
+  if (pressure === "high") return "pressure_elevated";
+  return "within_bounds";
+}
+
+/**
+ * Evaluate one policy input into a bounded decision.
+ *
+ * Order matters: validate the label, validate the window, apply the
+ * pressure factor, THEN clamp. Clamping last is what makes the bounded-budget
+ * guarantee hold for every action including escalate.
+ *
+ * Throws `{ code }` on an unknown pressure label or an invalid bound pair.
+ */
+export function evaluatePolicy(input: PolicyInput): PolicyDecisionV1 {
+  const pressure = validatePressureLabel(input.pressure);
+  const bounds = validateBounds(input.bounds);
+
+  const requested = Number.isFinite(input.requestedBudget)
+    ? input.requestedBudget
+    : bounds.minBudget;
+  const adjusted = requested * PRESSURE_FACTOR[pressure];
+  const budget = clampBudget(adjusted, bounds.minBudget, bounds.maxBudget);
+
+  return {
+    schema: POLICY_DECISION_SCHEMA_V1,
+    decisionId: input.decisionId,
+    sessionId: input.sessionId,
+    action: PRESSURE_ACTION[pressure],
+    budget,
+    pressure,
+    reason: reasonFor(pressure, input.requestedBudget, budget, bounds),
+    ts: input.ts,
+  };
+}
+
+/**
+ * Assert a decision satisfies the sprint invariant: allowed action AND bounded
+ * budget. Used by the acceptance aggregator to check every produced row.
+ */
+export function isDecisionWithinBounds(
+  decision: PolicyDecisionV1,
+  bounds: PolicyBounds,
+): boolean {
+  return (
+    isPolicyAction(decision.action) &&
+    Number.isFinite(decision.budget) &&
+    decision.budget >= bounds.minBudget &&
+    decision.budget <= bounds.maxBudget
+  );
+}

package/src/vector-cortex/controller/shadow.ts

@@ -0,0 +1,136 @@
+/**
+ * controller/shadow.ts — VC8B shadow policy evaluator (PURE, READ-ONLY).
+ *
+ * The shadow engine runs the candidate policy alongside the live path so its
+ * decisions can be measured before they are trusted. That is only safe if the
+ * shadow is structurally incapable of affecting the live path, so this module
+ * takes the capability argument seriously:
+ *
+ *   - NO RENDERER. It imports no renderer and returns no rendered bytes.
+ *   - NO STORE WRITER. It imports no store and performs no write.
+ *   - NO PROMPT MUTATION. It receives the canonical prompt as bytes it may only
+ *     hash, and it re-hashes on exit to PROVE the bytes are unchanged
+ *     (POL-SHADOW-002). `liveMutations` is reported and is always 0.
+ *
+ * INPUTS ARE COPIED, NOT BORROWED. Every input is deep-copied on entry, so even
+ * a future policy change that mutated its argument could not reach the caller's
+ * object. The copy is the enforcement; the `readonly` types are only the
+ * documentation of it. This is the difference between "we don't mutate" and
+ * "we cannot mutate".
+ *
+ * A rejected input does NOT abort the run: the shadow's job is measurement, so
+ * one unknown pressure label is recorded as a rejection code and the remaining
+ * inputs are still evaluated.
+ *
+ * PREVENT-002/011/PI-004 honored.
+ */
+
+import { createHash } from "node:crypto";
+
+import type {
+  PolicyDecisionV1,
+  PolicyInput,
+  ShadowRejection,
+  ShadowResult,
+} from "./types.js";
+import { evaluatePolicy } from "./policy.js";
+
+/** SHA-256 of the canonical prompt bytes, lowercase hex (VC5B convention). */
+export function promptDigestOf(promptBytes: string): string {
+  return createHash("sha256")
+    .update(Buffer.from(promptBytes, "utf8"))
+    .digest("hex");
+}
+
+/**
+ * Deep-copy one policy input. Explicit field-by-field construction rather than
+ * a structured clone: it keeps the copy total over the declared shape and makes
+ * an added field a compile error instead of a silently shared reference.
+ */
+export function copyPolicyInput(input: PolicyInput): PolicyInput {
+  return {
+    decisionId: input.decisionId,
+    sessionId: input.sessionId,
+    pressure: input.pressure,
+    requestedBudget: input.requestedBudget,
+    bounds: {
+      minBudget: input.bounds.minBudget,
+      maxBudget: input.bounds.maxBudget,
+    },
+    ts: input.ts,
+  };
+}
+
+/** Extract the machine code from a thrown policy failure. */
+function codeOf(err: unknown): string {
+  if (typeof err === "object" && err !== null && "code" in err) {
+    const code = (err as { code: unknown }).code;
+    if (typeof code === "string") return code;
+  }
+  return "POL_UNKNOWN_FAILURE";
+}
+
+/**
+ * Evaluate a batch of policy inputs in shadow mode.
+ *
+ * Returns decisions + metrics ONLY. The caller receives no capability to apply
+ * any of it; promoting a shadow decision is a separate, explicit act.
+ *
+ * @param inputs      the policy inputs to evaluate (copied, never mutated)
+ * @param promptBytes the canonical prompt, used ONLY to prove non-mutation
+ */
+export function evaluateShadow(
+  inputs: readonly PolicyInput[],
+  promptBytes: string,
+): ShadowResult {
+  // Hash the prompt BEFORE any evaluation so the exit comparison is meaningful.
+  const digestOnEntry = promptDigestOf(promptBytes);
+
+  // Copy every input up front: nothing downstream ever sees the caller's object.
+  const copies = inputs.map(copyPolicyInput);
+
+  const decisions: PolicyDecisionV1[] = [];
+  const rejections: ShadowRejection[] = [];
+  let clamped = 0;
+
+  for (const copy of copies) {
+    try {
+      const decision = evaluatePolicy(copy);
+      decisions.push(decision);
+      const atBound =
+        decision.reason === "budget_clamped_low" ||
+        decision.reason === "budget_clamped_high";
+      if (atBound) clamped += 1;
+    } catch (err) {
+      // Measurement continues: one bad row must not blind the whole run.
+      rejections.push({ decisionId: copy.decisionId, code: codeOf(err) });
+    }
+  }
+
+  // Re-hash on exit. Equality here is the POL-SHADOW-002 proof that the shadow
+  // left the canonical prompt untouched.
+  const digestOnExit = promptDigestOf(promptBytes);
+  const promptUnchanged = digestOnEntry === digestOnExit;
+
+  return {
+    decisions,
+    rejections,
+    metrics: {
+      evaluated: decisions.length,
+      clamped,
+      rejected: rejections.length,
+      // Structurally zero: this module holds no writer capability. If the
+      // prompt digest ever moved, that is a live mutation and it is counted.
+      liveMutations: promptUnchanged ? 0 : 1,
+    },
+    promptDigest: digestOnExit,
+  };
+}
+
+/**
+ * Assert the shadow result carries no live mutation. The sprint's acceptance
+ * bar is "shadow live mutation count zero"; this is that check as a function.
+ */
+export function isShadowClean(result: ShadowResult): boolean {
+  return result.metrics.liveMutations === 0;
+}