pi-mega-compact 0.20.17 → 0.20.19

package/dist/src/vector-cortex/migrations/pressure-v2-ops.js

@@ -0,0 +1,166 @@
+/**
+ * pressure-v2-ops.ts — M7 migration operational logic (copy/validate/switch).
+ *
+ * Extracted from pressure-v2.ts to keep the parent file under the 300-line
+ * soft limit (soft-as-hard gate). Pure logic over an injected M7Host;
+ * deterministic + testable; no console. PREVENT-002/011/PI-004 honored.
+ *
+ * WHY THE LABEL CHECK RE-READS THE HOST AT SWITCH TIME. The sprint's failure
+ * injection is explicit: kill the process after the copy phase, insert an
+ * unknown legacy pressure row, then resume — and the resumed run must return
+ * M7_PRESSURE_UNKNOWN and KEEP THE OLD POINTER. If the switch trusted the
+ * verdict of an earlier verify call, the injected row would be invisible and
+ * the pointer would flip over a store that still holds an uncanonical label.
+ * So `m7Switch` re-reads `v1Rows`/`existingV2`/`activeVersion` and re-validates
+ * against that live state. Validation is a precondition; the switch is the only
+ * place that proves the hazard is absent *right now*.
+ */
+import { createHash } from "node:crypto";
+import { isPressureLevel } from "../controller/policy.js";
+import { M7_FAIL, PRESSURE_LEGACY_VERSION } from "./pressure-v2-types.js";
+/** Length-prefixed framing so the folded fields cannot alias. */
+function field(value) {
+    return `${Buffer.byteLength(value, "utf8")}:${value}`;
+}
+/** Row identity is (session, effectiveSeq) — one pressure per sequence point. */
+const identity = (sessionId, effectiveSeq) => `${sessionId}::${effectiveSeq}`;
+/** The authoritative v2 digest: SHA-256 over the length-prefixed fields. */
+export function derivePressureDigest(sessionId, level, effectiveSeq, ts) {
+    return createHash("sha256")
+        .update(field("pressure-v2") +
+        field(sessionId) +
+        field(level) +
+        field(String(effectiveSeq)) +
+        field(ts), "utf8")
+        .digest("hex");
+}
+/**
+ * Map ONE legacy row to its v2 form. ONLY the canonical five labels map;
+ * anything else throws `{ code: M7_PRESSURE_UNKNOWN }`. There is deliberately
+ * no fallback branch — a coerced label is a silently misclassified workload.
+ */
+export function mapPressureRow(v1) {
+    if (!isPressureLevel(v1.label)) {
+        throw { code: M7_FAIL.PRESSURE_UNKNOWN };
+    }
+    return {
+        sessionId: v1.sessionId,
+        level: v1.label,
+        effectiveSeq: v1.effectiveSeq,
+        ts: v1.ts,
+        digest: derivePressureDigest(v1.sessionId, v1.label, v1.effectiveSeq, v1.ts),
+    };
+}
+/** True when every legacy row carries a canonical label. */
+export function allLabelsCanonical(host) {
+    return host.v1Rows().every((r) => isPressureLevel(r.label));
+}
+/**
+ * COPY: resumable per (session, effectiveSeq). An interrupted run resumes
+ * without duplicate rows. An uncanonical label aborts the copy with
+ * M7_PRESSURE_UNKNOWN before anything is written.
+ */
+export function m7Copy(host) {
+    const existing = new Map(host.existingV2().map((r) => [identity(r.sessionId, r.effectiveSeq), r]));
+    const wanted = [];
+    for (const v1 of host.v1Rows()) {
+        // Throws M7_PRESSURE_UNKNOWN for a non-canonical label.
+        const fresh = mapPressureRow(v1);
+        const stored = existing.get(identity(v1.sessionId, v1.effectiveSeq));
+        if (stored !== undefined && stored.digest === fresh.digest)
+            continue;
+        wanted.push(fresh);
+    }
+    if (wanted.length > 0)
+        host.putV2(wanted);
+    return { written: wanted, all: [...host.existingV2()] };
+}
+function dedupe(codes) {
+    const out = [];
+    for (const c of codes)
+        if (!out.includes(c))
+            out.push(c);
+    return out;
+}
+/**
+ * VALIDATE: compare counts and digests between v1 and v2, and re-check every
+ * legacy label. Returns codes rather than throwing so a caller sees every
+ * problem at once.
+ */
+export function m7Verify(host) {
+    const codes = [];
+    const v1Rows = host.v1Rows();
+    const stored = host.existingV2();
+    // Label check first: an uncanonical legacy label invalidates the whole run.
+    for (const v1 of v1Rows) {
+        if (!isPressureLevel(v1.label))
+            codes.push(M7_FAIL.PRESSURE_UNKNOWN);
+    }
+    const counts = new Map();
+    for (const r of stored) {
+        const id = identity(r.sessionId, r.effectiveSeq);
+        counts.set(id, (counts.get(id) ?? 0) + 1);
+    }
+    const expected = new Set();
+    for (const v1 of v1Rows) {
+        if (!isPressureLevel(v1.label))
+            continue;
+        const id = identity(v1.sessionId, v1.effectiveSeq);
+        expected.add(id);
+        const n = counts.get(id) ?? 0;
+        if (n === 0)
+            codes.push(M7_FAIL.COPY_PARTIAL);
+        if (n > 1)
+            codes.push(M7_FAIL.COUNT_MISMATCH);
+    }
+    // Every stored row must re-derive its own digest and correspond to a v1 row.
+    for (const r of stored) {
+        const fresh = derivePressureDigest(r.sessionId, r.level, r.effectiveSeq, r.ts);
+        if (r.digest !== fresh)
+            codes.push(M7_FAIL.DIGEST_MISMATCH);
+        if (!expected.has(identity(r.sessionId, r.effectiveSeq))) {
+            codes.push(M7_FAIL.COUNT_MISMATCH);
+        }
+    }
+    return { ok: codes.length === 0, codes: dedupe(codes) };
+}
+/**
+ * SWITCH: atomically flip the active pointer to v2 — but ONLY after
+ * re-validating against freshly-read host state (see the module note on the
+ * post-copy failure injection). The pointer is left untouched on any failure.
+ */
+export function m7Switch(host) {
+    if (host.activeVersion() !== PRESSURE_LEGACY_VERSION) {
+        return { ok: false, codes: [M7_FAIL.NOT_ON_LEGACY] };
+    }
+    // Re-read the live rows: an unknown label injected after the copy is caught
+    // here, and the old pointer survives.
+    if (!allLabelsCanonical(host)) {
+        return { ok: false, codes: [M7_FAIL.PRESSURE_UNKNOWN] };
+    }
+    const verify = m7Verify(host);
+    if (!verify.ok)
+        return verify;
+    host.switchToV2();
+    return { ok: true, codes: [] };
+}
+/**
+ * Full M7 migration: copy, then validate + switch. An uncanonical label thrown
+ * during the copy is converted to a result code so the caller sees the same
+ * shape as a validation failure, and the pointer is left on legacy.
+ */
+export function migratePressureV2(host) {
+    try {
+        m7Copy(host);
+    }
+    catch (err) {
+        const code = typeof err === "object" && err !== null && "code" in err
+            ? err.code
+            : undefined;
+        if (code === M7_FAIL.PRESSURE_UNKNOWN) {
+            return { ok: false, codes: [M7_FAIL.PRESSURE_UNKNOWN] };
+        }
+        throw err;
+    }
+    return m7Switch(host);
+}

package/dist/src/vector-cortex/migrations/pressure-v2-types.js

@@ -0,0 +1,32 @@
+/**
+ * pressure-v2-types.ts — M7 pressure-v2 migration types.
+ *
+ * Extracted from pressure-v2.ts to keep the parent file under the 300-line
+ * soft limit (soft-as-hard gate). Pure type + constant definitions; no logic.
+ * PREVENT-002/011/PI-004 honored.
+ */
+/** The active-version value the v2 pointer is switched to. */
+export const PRESSURE_V2_VERSION = 2;
+/** The legacy (predecessor) active version. */
+export const PRESSURE_LEGACY_VERSION = 1;
+/** M7 failure codes. */
+export const M7_FAIL = {
+    /** A legacy row carries a label outside the canonical five levels. */
+    PRESSURE_UNKNOWN: "M7_PRESSURE_UNKNOWN",
+    /** Copied row count does not match the legacy row count. */
+    COUNT_MISMATCH: "M7_COUNT_MISMATCH",
+    /** A v2 row digest does not re-derive from its own declared fields. */
+    DIGEST_MISMATCH: "M7_DIGEST_MISMATCH",
+    /** A legacy row has no corresponding v2 row (interrupted copy). */
+    COPY_PARTIAL: "M7_COPY_PARTIAL",
+    /** The active pointer is not on v1; switching would regress or no-op. */
+    NOT_ON_LEGACY: "M7_NOT_ON_LEGACY",
+};
+/**
+ * Registered M7 conformance IDs (M7-001..015). The acceptance test reads these
+ * rows from the v2 `adaptive-policy/` domain and asserts each returns its
+ * manifest bytes or exactly its listed failure code. Mirrors M5_IDS / M6_IDS.
+ */
+export const M7_IDS = Array.from({ length: 15 }, (_v, i) => `M7-${String(i + 1).padStart(3, "0")}`);
+/** Named M7 rows surfaced by the conformance corpus. */
+export const M7_NAMED_IDS = ["M7-PRESSURE-003"];

package/dist/src/vector-cortex/migrations/pressure-v2.js

@@ -0,0 +1,36 @@
+/**
+ * vector-cortex/migrations/pressure-v2.ts — M7 pressure-v2 migration
+ * (COPY + VALIDATE + SWITCH).
+ *
+ * Delegate-shell: types + constants live in pressure-v2-types.ts and the
+ * operational logic (copy/verify/switch/label mapping) lives in
+ * pressure-v2-ops.ts. This file re-exports the public surface so callers import
+ * from a single module. Split to keep under the 300-line soft limit
+ * (soft-as-hard gate).
+ *
+ * M7 canonicalizes the context-pressure label. The predecessor stored whatever
+ * label a producer happened to write; v2 admits EXACTLY five — `low`, `medium`,
+ * `high`, `ultra`, `mega` — and rejects everything else as
+ * `M7_PRESSURE_UNKNOWN`. The rejection is the feature: coercing an unrecognized
+ * legacy label onto the nearest level would silently reclassify a workload, and
+ * the direction of that error is unknowable from the label alone.
+ *
+ * Like M4/M5/M6 it follows the copy/validate/switch contract:
+ *
+ *   - copy:     resumable per (session, effectiveSeq) — an interrupted run
+ *               resumes without duplicate rows or active-pointer drift.
+ *   - validate: every v1 row has exactly one v2 row, every v2 digest re-derives
+ *               from its own declared fields, and every legacy label is
+ *               canonical.
+ *   - switch:   ATOMICALLY flip the active pointer via `host.switchToV2()`, but
+ *               only after RE-READING host state and re-validating. The sprint's
+ *               failure injection kills the process after the copy and then
+ *               inserts an unknown legacy pressure; the resumed run must return
+ *               `M7_PRESSURE_UNKNOWN` and KEEP THE OLD POINTER. A migration that
+ *               trusts a stale verification is a migration that corrupts on
+ *               restart.
+ *
+ * PREVENT-002/011/PI-004 honored.
+ */
+export { PRESSURE_V2_VERSION, PRESSURE_LEGACY_VERSION, M7_FAIL, M7_IDS, M7_NAMED_IDS, } from "./pressure-v2-types.js";
+export { derivePressureDigest, mapPressureRow, allLabelsCanonical, m7Copy, m7Verify, m7Switch, migratePressureV2, } from "./pressure-v2-ops.js";

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