pi-mega-compact 0.20.17 → 0.20.18

package/dist/src/vector-cortex/controller/policy.js

@@ -0,0 +1,158 @@
+/**
+ * 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 { POLICY_ACTIONS, POLICY_DECISION_SCHEMA_V1, POL_ACTION_FORBIDDEN, POL_BUDGET_OUT_OF_BOUNDS, POL_PRESSURE_UNKNOWN, PRESSURE_LEVELS, } from "./types.js";
+/** Construct a policy failure. */
+function fail(code) {
+    return { code };
+}
+/** Type guard: is this a canonical pressure level? */
+export function isPressureLevel(label) {
+    return PRESSURE_LEVELS.includes(label);
+}
+/** Type guard: is this an allowed policy action? */
+export function isPolicyAction(action) {
+    return POLICY_ACTIONS.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) {
+    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) {
+    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) {
+    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, minBudget, maxBudget) {
+    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 = {
+    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 = {
+    low: "admit",
+    medium: "admit",
+    high: "dampen",
+    ultra: "defer",
+    mega: "reject",
+};
+/** Select the reason code that explains the decision. */
+function reasonFor(pressure, requested, clamped, bounds) {
+    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) {
+    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, bounds) {
+    return (isPolicyAction(decision.action) &&
+        Number.isFinite(decision.budget) &&
+        decision.budget >= bounds.minBudget &&
+        decision.budget <= bounds.maxBudget);
+}

package/dist/src/vector-cortex/controller/shadow.js

@@ -0,0 +1,117 @@
+/**
+ * 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 { evaluatePolicy } from "./policy.js";
+/** SHA-256 of the canonical prompt bytes, lowercase hex (VC5B convention). */
+export function promptDigestOf(promptBytes) {
+    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) {
+    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) {
+    if (typeof err === "object" && err !== null && "code" in err) {
+        const code = err.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, promptBytes) {
+    // 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 = [];
+    const rejections = [];
+    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) {
+    return result.metrics.liveMutations === 0;
+}

package/dist/src/vector-cortex/controller/types.js

@@ -0,0 +1,85 @@
+/**
+ * controller/types.ts — VC8B policy decision + pressure type definitions.
+ *
+ * PolicyDecisionV1 is the FINITE, BOUNDED output of the policy engine: one of a
+ * closed action set, a token budget clamped into a configured window, and a
+ * machine code reason. There is deliberately no free-text field and no open
+ * action string — an adaptive policy whose action space can grow at runtime
+ * cannot be reviewed, and a budget with no ceiling is a cost incident waiting
+ * to happen.
+ *
+ * PressureV2 canonicalizes the context-pressure label to EXACTLY five levels
+ * (low/medium/high/ultra/mega). Anything else is rejected rather than coerced:
+ * silently mapping an unrecognized legacy label onto a neighbouring level is
+ * how a "high" workload quietly starts being treated as "low".
+ *
+ * Conformance IDs POL-001..025 and M7-001..015 are registered here as the
+ * single source of truth for the sprint's conformance rows.
+ *
+ * PREVENT-PI-004: type definitions only, no network code.
+ * PREVENT-011: no `any` type.
+ */
+/** Schema version for PolicyDecisionV1. */
+export const POLICY_DECISION_SCHEMA_V1 = "policy-decision-v1";
+/** Schema version for PressureV2. */
+export const PRESSURE_SCHEMA_V2 = "pressure-v2";
+/** Failure code when a pressure label is outside the canonical five levels. */
+export const POL_PRESSURE_UNKNOWN = "POL_PRESSURE_UNKNOWN";
+/** Failure code when a requested action is outside the allowed finite set. */
+export const POL_ACTION_FORBIDDEN = "POL_ACTION_FORBIDDEN";
+/** Failure code when a budget bound pair is itself invalid (min > max, NaN). */
+export const POL_BUDGET_OUT_OF_BOUNDS = "POL_BUDGET_OUT_OF_BOUNDS";
+/** Failure code when the M7 migration meets a non-canonical pressure label. */
+export const M7_PRESSURE_UNKNOWN = "M7_PRESSURE_UNKNOWN";
+/** Failure code when M7 copied rows do not match the legacy row count. */
+export const M7_COUNT_MISMATCH = "M7_COUNT_MISMATCH";
+/** Failure code when an M7 row digest does not re-derive from its own fields. */
+export const M7_DIGEST_MISMATCH = "M7_DIGEST_MISMATCH";
+/** Failure code when the active pressure pointer is not on the legacy version. */
+export const M7_NOT_ON_LEGACY = "M7_NOT_ON_LEGACY";
+/**
+ * The canonical five pressure levels. Ordered low -> mega; the order is
+ * meaningful (policy escalates monotonically with pressure) so it is exported
+ * as an array, not just a union.
+ */
+export const PRESSURE_LEVELS = [
+    "low",
+    "medium",
+    "high",
+    "ultra",
+    "mega",
+];
+/**
+ * The FINITE allowed policy action set. A decision may carry no other action.
+ * `admit`    — proceed at the requested budget.
+ * `dampen`   — proceed at a reduced budget (pressure is elevated).
+ * `defer`    — postpone the work to a later turn.
+ * `escalate` — raise the budget within bounds (headroom is available).
+ * `reject`   — refuse the work outright.
+ */
+export const POLICY_ACTIONS = [
+    "admit",
+    "dampen",
+    "defer",
+    "escalate",
+    "reject",
+];
+/** Machine reason codes — never free-text. */
+export const POLICY_REASONS = [
+    "within_bounds",
+    "budget_clamped_low",
+    "budget_clamped_high",
+    "pressure_elevated",
+    "pressure_critical",
+    "headroom_available",
+];
+/** Conformance IDs POL-001..POL-025 for the 25 numbered policy rows. */
+export const POLICY_CONFORMANCE_IDS = Array.from({ length: 25 }, (_v, i) => `POL-${String(i + 1).padStart(3, "0")}`);
+/** Conformance IDs M7-001..M7-015 for the 15 numbered migration rows. */
+export const M7_CONFORMANCE_IDS = Array.from({ length: 15 }, (_v, i) => `M7-${String(i + 1).padStart(3, "0")}`);
+/** Named conformance fixtures for the sprint's headline assertions. */
+export const POLICY_NAMED_FIXTURES = [
+    "POL-CLAMP-001",
+    "POL-SHADOW-002",
+    "M7-PRESSURE-003",
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.17",
+  "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/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;
+}

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

@@ -0,0 +1,195 @@
+/**
+ * controller/types.ts — VC8B policy decision + pressure type definitions.
+ *
+ * PolicyDecisionV1 is the FINITE, BOUNDED output of the policy engine: one of a
+ * closed action set, a token budget clamped into a configured window, and a
+ * machine code reason. There is deliberately no free-text field and no open
+ * action string — an adaptive policy whose action space can grow at runtime
+ * cannot be reviewed, and a budget with no ceiling is a cost incident waiting
+ * to happen.
+ *
+ * PressureV2 canonicalizes the context-pressure label to EXACTLY five levels
+ * (low/medium/high/ultra/mega). Anything else is rejected rather than coerced:
+ * silently mapping an unrecognized legacy label onto a neighbouring level is
+ * how a "high" workload quietly starts being treated as "low".
+ *
+ * Conformance IDs POL-001..025 and M7-001..015 are registered here as the
+ * single source of truth for the sprint's conformance rows.
+ *
+ * PREVENT-PI-004: type definitions only, no network code.
+ * PREVENT-011: no `any` type.
+ */
+
+/** Schema version for PolicyDecisionV1. */
+export const POLICY_DECISION_SCHEMA_V1 = "policy-decision-v1";
+
+/** Schema version for PressureV2. */
+export const PRESSURE_SCHEMA_V2 = "pressure-v2";
+
+/** Failure code when a pressure label is outside the canonical five levels. */
+export const POL_PRESSURE_UNKNOWN = "POL_PRESSURE_UNKNOWN";
+
+/** Failure code when a requested action is outside the allowed finite set. */
+export const POL_ACTION_FORBIDDEN = "POL_ACTION_FORBIDDEN";
+
+/** Failure code when a budget bound pair is itself invalid (min > max, NaN). */
+export const POL_BUDGET_OUT_OF_BOUNDS = "POL_BUDGET_OUT_OF_BOUNDS";
+
+/** Failure code when the M7 migration meets a non-canonical pressure label. */
+export const M7_PRESSURE_UNKNOWN = "M7_PRESSURE_UNKNOWN";
+
+/** Failure code when M7 copied rows do not match the legacy row count. */
+export const M7_COUNT_MISMATCH = "M7_COUNT_MISMATCH";
+
+/** Failure code when an M7 row digest does not re-derive from its own fields. */
+export const M7_DIGEST_MISMATCH = "M7_DIGEST_MISMATCH";
+
+/** Failure code when the active pressure pointer is not on the legacy version. */
+export const M7_NOT_ON_LEGACY = "M7_NOT_ON_LEGACY";
+
+/**
+ * The canonical five pressure levels. Ordered low -> mega; the order is
+ * meaningful (policy escalates monotonically with pressure) so it is exported
+ * as an array, not just a union.
+ */
+export const PRESSURE_LEVELS = [
+  "low",
+  "medium",
+  "high",
+  "ultra",
+  "mega",
+] as const;
+
+/** A canonical context-pressure level. */
+export type PressureLevel = (typeof PRESSURE_LEVELS)[number];
+
+/**
+ * The FINITE allowed policy action set. A decision may carry no other action.
+ * `admit`    — proceed at the requested budget.
+ * `dampen`   — proceed at a reduced budget (pressure is elevated).
+ * `defer`    — postpone the work to a later turn.
+ * `escalate` — raise the budget within bounds (headroom is available).
+ * `reject`   — refuse the work outright.
+ */
+export const POLICY_ACTIONS = [
+  "admit",
+  "dampen",
+  "defer",
+  "escalate",
+  "reject",
+] as const;
+
+/** An allowed policy action. */
+export type PolicyAction = (typeof POLICY_ACTIONS)[number];
+
+/** Machine reason codes — never free-text. */
+export const POLICY_REASONS = [
+  "within_bounds",
+  "budget_clamped_low",
+  "budget_clamped_high",
+  "pressure_elevated",
+  "pressure_critical",
+  "headroom_available",
+] as const;
+
+/** A machine reason code explaining a decision. */
+export type PolicyReason = (typeof POLICY_REASONS)[number];
+
+/** The configured token-budget window a decision is clamped into. */
+export interface PolicyBounds {
+  readonly minBudget: number;
+  readonly maxBudget: number;
+}
+
+/**
+ * PolicyDecisionV1 — one bounded policy decision.
+ * `budget` is ALWAYS within the bounds that produced it; `action` is always a
+ * member of POLICY_ACTIONS.
+ */
+export interface PolicyDecisionV1 {
+  readonly schema: typeof POLICY_DECISION_SCHEMA_V1;
+  readonly decisionId: string;
+  readonly sessionId: string;
+  readonly action: PolicyAction;
+  readonly budget: number;
+  readonly pressure: PressureLevel;
+  readonly reason: PolicyReason;
+  readonly ts: string;
+}
+
+/** The input a policy evaluation consumes. */
+export interface PolicyInput {
+  readonly decisionId: string;
+  readonly sessionId: string;
+  /** The pressure label as received — validated, never coerced. */
+  readonly pressure: string;
+  /** The requested budget before clamping; any finite number. */
+  readonly requestedBudget: number;
+  readonly bounds: PolicyBounds;
+  readonly ts: string;
+}
+
+/**
+ * PressureV2 — a canonical pressure observation for a session at an effective
+ * sequence point.
+ */
+export interface PressureV2 {
+  readonly schema: typeof PRESSURE_SCHEMA_V2;
+  readonly level: PressureLevel;
+  readonly sessionId: string;
+  readonly effectiveSeq: number;
+  readonly ts: string;
+}
+
+/** Shadow metrics — counts only, never prompt bytes or free-text. */
+export interface ShadowMetrics {
+  /** Decisions evaluated in this shadow run. */
+  readonly evaluated: number;
+  /** Decisions whose budget was clamped at either bound. */
+  readonly clamped: number;
+  /** Inputs rejected (unknown pressure / bad bounds). */
+  readonly rejected: number;
+  /**
+   * Live mutations performed by the shadow engine. Structurally ALWAYS 0 —
+   * the shadow has no writer capability — and asserted as 0 by the sprint's
+   * acceptance contract.
+   */
+  readonly liveMutations: number;
+}
+
+/** The result of a shadow evaluation: decisions + metrics ONLY. */
+export interface ShadowResult {
+  readonly decisions: ReadonlyArray<PolicyDecisionV1>;
+  readonly rejections: ReadonlyArray<ShadowRejection>;
+  readonly metrics: ShadowMetrics;
+  /**
+   * The digest of the canonical prompt as observed on entry. The shadow engine
+   * re-computes this on exit and the two MUST be equal (POL-SHADOW-002).
+   */
+  readonly promptDigest: string;
+}
+
+/** A rejected shadow input, reduced to its code. */
+export interface ShadowRejection {
+  readonly decisionId: string;
+  readonly code: string;
+}
+
+/** Conformance IDs POL-001..POL-025 for the 25 numbered policy rows. */
+export const POLICY_CONFORMANCE_IDS: readonly string[] = Array.from(
+  { length: 25 },
+  (_v, i) => `POL-${String(i + 1).padStart(3, "0")}`,
+);
+
+/** Conformance IDs M7-001..M7-015 for the 15 numbered migration rows. */
+export const M7_CONFORMANCE_IDS: readonly string[] = Array.from(
+  { length: 15 },
+  (_v, i) => `M7-${String(i + 1).padStart(3, "0")}`,
+);
+
+/** Named conformance fixtures for the sprint's headline assertions. */
+export const POLICY_NAMED_FIXTURES = [
+  "POL-CLAMP-001",
+  "POL-SHADOW-002",
+  "M7-PRESSURE-003",
+] as const;