pi-mega-compact 0.20.18 → 0.20.20

package/dist/vector-cortex/cache/_diagnostics-fixture.js

@@ -1,14 +1,33 @@
 /**
- * cache/_diagnostics-fixture.ts — VC7C acceptance-test fixture helpers.
+ * cache/_diagnostics-fixture.ts — VC7C conformance fixture I/O + host builders.
  *
- * Reads conformance fixtures from the v2 `cache-diagnostics/` domain and provides
- * a flag-toggling wrapper for VC7C parity tests. Mirrors `_economics-fixture.ts`.
+ * Reads conformance fixtures from the v2 `cache-diagnostics/` domain, decodes
+ * them into the REAL production types (`MissObservation`, `M5Host`) and feeds
+ * them verbatim into `classifyMiss` / `migrateRequestHashV2`. Fixtures store
+ * bigints as JSON numbers — converted here (lossy conversion would break
+ * digests and the acceptance rows would fail loudly).
+ *
+ * No mocks, no stubs, no parallel "test shape": the decoded objects ARE
+ * `MissObservation` / `M5Host` and drive the production functions directly.
+ * Mirrors `_economics-fixture.ts`.
  */
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 const here = dirname(fileURLToPath(import.meta.url));
-const V2 = join(here, "..", "..", "..", "conformance", "vector-cortex", "v2");
+function repoRoot(from) {
+    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);
+}
+const V2 = join(repoRoot(here), "conformance", "vector-cortex", "v2");
 const DIR = join(V2, "cache-diagnostics");
 /** Read + parse one conformance fixture by ID. */
 export function diagnosticsFixture(id) {
@@ -29,3 +48,58 @@ export function withVc7cFlag(value, fn) {
             process.env.MEGACOMPACT_VC7C = prior;
     }
 }
+/** Read a cache-diagnostic fixture as a typed CacheFx. */
+export function cacheFx(id) {
+    return diagnosticsFixture(id);
+}
+/** Decode the fixture's JSON observe into the production MissObservation. */
+export function toObservation(fx) {
+    const o = fx.input.observe;
+    return {
+        requestProfileId: o.requestProfileId,
+        requestProfileVersion: o.requestProfileVersion,
+        cachedProfileId: o.cachedProfileId,
+        cachedProfileVersion: o.cachedProfileVersion,
+        requestCoveredDigest: o.requestCoveredDigest,
+        cachedCoveredDigest: o.cachedCoveredDigest,
+        requestedRangeCount: o.requestedRangeCount,
+        cachedRangeCount: o.cachedRangeCount,
+        requestDigest: o.requestDigest,
+        cachedRequestDigest: o.cachedRequestDigest,
+        requestDependencyHighWater: BigInt(o.requestDependencyHighWater),
+        cachedDependencyHighWater: o.cachedDependencyHighWater === null
+            ? null
+            : BigInt(o.cachedDependencyHighWater),
+        generationInvalidated: o.generationInvalidated,
+    };
+}
+/** Read an M5 fixture as a typed M5Fx. */
+export function m5Fx(id) {
+    return diagnosticsFixture(id);
+}
+/** Build an in-memory M5Host from the fixture input. */
+export function toM5Host(fx) {
+    const v1Rows = fx.input.v1Rows.map((r) => ({
+        profileId: r.profileId,
+        requestDigest: r.requestDigest,
+        hash: r.hash,
+    }));
+    const v2Rows = [];
+    let activeVersion = fx.input.activeVersion;
+    const host = {
+        v1Rows: () => v1Rows,
+        economicsVersionOf: (p) => fx.input.econVersionOf[p] ?? "econ-1",
+        sessionOf: (p) => fx.input.sessionOf[p] ?? "s1",
+        liveGenerationOf: (s) => BigInt(fx.input.liveGenerationOf[s] ?? 0),
+        existingV2: () => v2Rows,
+        putV2: (rows) => v2Rows.push(...rows),
+        activeVersion: () => activeVersion,
+        switchToV2: () => {
+            activeVersion = 2;
+        },
+        get activeVersionAfter() {
+            return activeVersion;
+        },
+    };
+    return host;
+}

package/dist/vector-cortex/cache/diagnostics.js

@@ -34,21 +34,30 @@ function advanceDelta(request, cached) {
 }
 /** Collect the payload-free evidence from one observation. */
 export function collectEvidence(o) {
+    // Absence is computed first: "absence is not a mismatch" means a cold key
+    // (null cached fields) classifies `unknown`, never `profile`/`range`/etc.
+    // The cachedRangeCount on a cold key is 0 by convention (not a real count),
+    // so it must not trigger a range mismatch even though isPresent(0) is true.
+    const absent = !isPresent(o.cachedProfileId) &&
+        !isPresent(o.cachedCoveredDigest) &&
+        !isPresent(o.cachedRequestDigest) &&
+        !isPresent(o.cachedDependencyHighWater);
     const profileMismatch = isPresent(o.cachedProfileId) &&
         isPresent(o.cachedProfileVersion) &&
         (o.cachedProfileId !== o.requestProfileId ||
             o.cachedProfileVersion !== o.requestProfileVersion);
-    const rangeMismatch = (isPresent(o.cachedCoveredDigest) &&
-        o.cachedCoveredDigest !== o.requestCoveredDigest) ||
-        (isPresent(o.cachedRangeCount) &&
-            o.cachedRangeCount !== o.requestedRangeCount);
+    // Guard with !absent: a cold key's cachedRangeCount is 0 by convention (not
+    // a real count), so it must not fire a range mismatch even though
+    // isPresent(0) is true. The covered-digest arm is already null-safe but
+    // the rangeCount arm is not — !absent covers both uniformly.
+    const rangeMismatch = !absent &&
+        ((isPresent(o.cachedCoveredDigest) &&
+            o.cachedCoveredDigest !== o.requestCoveredDigest) ||
+            (isPresent(o.cachedRangeCount) &&
+                o.cachedRangeCount !== o.requestedRangeCount));
     const dep = advanceDelta(o.requestDependencyHighWater, o.cachedDependencyHighWater);
     const requestMismatch = isPresent(o.cachedRequestDigest) &&
         o.cachedRequestDigest !== o.requestDigest;
-    const absent = !isPresent(o.cachedProfileId) &&
-        !isPresent(o.cachedCoveredDigest) &&
-        !isPresent(o.cachedRequestDigest) &&
-        !isPresent(o.cachedDependencyHighWater);
     return {
         profileMismatch,
         rangeMismatch,

package/dist/vector-cortex/controller/_adaptive-fixture.js

@@ -0,0 +1,126 @@
+/**
+ * controller/_adaptive-fixture.ts — VC8B conformance fixture I/O + host builders.
+ *
+ * Reads conformance fixtures from the v2 `adaptive-policy/` domain, decodes
+ * them into the REAL production types (`PolicyInput`, `M7Host`) and feeds
+ * them verbatim into `evaluatePolicy` / `evaluateShadow` / `migratePressureV2`.
+ *
+ * No mocks, no stubs, no parallel "test shape": the decoded objects ARE the
+ * production types and drive the production functions directly.
+ * Mirrors `_diagnostics-fixture.ts` (VC7C) and `_economics-fixture.ts` (VC7B).
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const here = dirname(fileURLToPath(import.meta.url));
+function repoRoot(from) {
+    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);
+}
+const V2 = join(repoRoot(here), "conformance", "vector-cortex", "v2");
+const DIR = join(V2, "adaptive-policy");
+/** Read + parse one conformance fixture by ID from adaptive-policy/. */
+export function adaptiveFixture(id) {
+    const raw = readFileSync(join(DIR, `${id}.json`), "utf8");
+    return JSON.parse(raw);
+}
+/** Run `fn` with MEGACOMPACT_VC8B set to `value`, restoring the prior value after. */
+export function withVc8bFlag(value, fn) {
+    const prior = process.env.MEGACOMPACT_VC8B;
+    process.env.MEGACOMPACT_VC8B = value;
+    try {
+        return fn();
+    }
+    finally {
+        if (prior === undefined)
+            delete process.env.MEGACOMPACT_VC8B;
+        else
+            process.env.MEGACOMPACT_VC8B = prior;
+    }
+}
+/** Read a policy-decision fixture as a typed PolFx. */
+export function polFx(id) {
+    return adaptiveFixture(id);
+}
+/** Decode the fixture's JSON input into the production PolicyInput. */
+export function toPolicyInput(fx) {
+    return {
+        decisionId: fx.input.decisionId,
+        sessionId: fx.input.sessionId,
+        pressure: fx.input.pressure,
+        requestedBudget: fx.input.requestedBudget,
+        bounds: {
+            minBudget: fx.input.bounds.minBudget,
+            maxBudget: fx.input.bounds.maxBudget,
+        },
+        ts: fx.input.ts,
+    };
+}
+/** Read a policy-shadow fixture as a typed ShadowFx. */
+export function shadowFx(id) {
+    return adaptiveFixture(id);
+}
+/** Decode shadow input rows into production PolicyInput[]. */
+export function toShadowInputs(fx) {
+    return fx.input.inputs.map((i) => ({
+        decisionId: i.decisionId,
+        sessionId: i.sessionId,
+        pressure: i.pressure,
+        requestedBudget: i.requestedBudget,
+        bounds: {
+            minBudget: i.bounds.minBudget,
+            maxBudget: i.bounds.maxBudget,
+        },
+        ts: i.ts,
+    }));
+}
+/** Read an M7 fixture as a typed M7Fx. */
+export function m7Fx(id) {
+    return adaptiveFixture(id);
+}
+/** Build an in-memory M7Host from the fixture input. */
+export function toM7Host(fx) {
+    const v1Rows = fx.input.v1Rows.map((r) => ({
+        sessionId: r.sessionId,
+        label: r.label,
+        effectiveSeq: r.effectiveSeq,
+        ts: r.ts,
+    }));
+    // For inject-after-copy, the injected row carries a non-canonical label.
+    // migratePressureV2 calls m7Copy first, which throws M7_PRESSURE_UNKNOWN for
+    // the bad label — the result is the same: ok:false, pointer on v1.
+    if (fx.input.injectedRow) {
+        v1Rows.push({
+            sessionId: fx.input.injectedRow.sessionId,
+            label: fx.input.injectedRow.label,
+            effectiveSeq: fx.input.injectedRow.effectiveSeq,
+            ts: fx.input.injectedRow.ts,
+        });
+    }
+    const v2Rows = [];
+    let activeVersion = fx.input.activeVersion ?? 1;
+    const host = {
+        v1Rows: () => v1Rows,
+        existingV2: () => v2Rows,
+        putV2: (rows) => v2Rows.push(...rows),
+        activeVersion: () => activeVersion,
+        switchToV2: () => {
+            activeVersion = 2;
+        },
+        get activeVersionAfter() {
+            return activeVersion;
+        },
+        get v2RowCount() {
+            return v2Rows.length;
+        },
+    };
+    return host;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * controller/policy-emit.ts — VC8B reporter seam (FLAG-GATED).
+ *
+ * Mirrors the VC8A outcomes-emit pattern: a thin `safe()` wrapper around an
+ * optional injected `emit`, and the two event names the sprint spec requires:
+ *   - `vector_cortex_shadow_decision_recorded` — a shadow decision was produced.
+ *   - `vector_cortex_policy_action_rejected`   — an input was refused by policy.
+ *
+ * FLAG SEMANTICS. The policy/shadow/M7 arithmetic STILL RUNS regardless of
+ * `MEGACOMPACT_VC8B`. The flag gates ONLY this reporting + dashboard seam:
+ * flag-off is byte-identical to the predecessor (VC8A).
+ *
+ * PAYLOAD DISCIPLINE. These events carry only ids, the finite action, the
+ * numeric budget, and machine codes — never prompt bytes, response text, or
+ * free-text.
+ *
+ * PREVENT-PI-004: no network. PREVENT-011: no `any` type.
+ */
+import { VC8B_ENABLED } from "../../config/vector-cortex.js";
+/** Run `fn` only when an emit exists; a reporting failure is never fatal. */
+function safe(emit, fn) {
+    if (emit === undefined)
+        return;
+    try {
+        fn(emit);
+    }
+    catch {
+        // Non-fatal: a reporting failure must never break the agent loop.
+    }
+}
+/** Report a shadow decision that was recorded. Gated by the flag. */
+export function reportShadowDecisionRecorded(emit, decision) {
+    if (!VC8B_ENABLED())
+        return;
+    safe(emit, (e) => e("vector_cortex_shadow_decision_recorded", {
+        ts: undefined,
+        event: "vector_cortex_shadow_decision_recorded",
+        decisionId: decision.decisionId,
+        sessionId: decision.sessionId,
+        action: decision.action,
+        budget: decision.budget,
+        pressure: decision.pressure,
+        reason: decision.reason,
+    }));
+}
+/** Report a policy action rejected by validation. Gated by the flag. */
+export function reportPolicyActionRejected(emit, rejection) {
+    if (!VC8B_ENABLED())
+        return;
+    safe(emit, (e) => e("vector_cortex_policy_action_rejected", {
+        ts: undefined,
+        event: "vector_cortex_policy_action_rejected",
+        decisionId: rejection.decisionId,
+        code: rejection.code,
+    }));
+}

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