pi-mega-compact 0.20.16 → 0.20.18

package/dist/config/vector-cortex.js

@@ -211,6 +211,20 @@ export const VC7B_ENABLED = () => sprintFlag("MEGACOMPACT_VC7B");
  * EXCLUDED_SETTINGS), mirroring VC4A..VC7B.
  */
 export const VC7C_ENABLED = () => 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 = () => 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 { BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./vector-cortex-breakers.js";

package/dist/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, VC8A_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

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

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+export {};

package/dist/extensions/dashboard-server/route-dispatch.js

@@ -24,6 +24,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.
  * Returns true if a handler claimed the request (ended the response).
@@ -123,5 +127,7 @@ export function dispatchRoutes(req, res, ctx) {
         return true;
     if (handleVectorCortexDiagnostics(req, res, ctx))
         return true;
+    if (handleVectorCortexOutcomes(req, res, ctx))
+        return true;
     return false;
 }

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

@@ -45,5 +45,6 @@ export const VECTOR_CORTEX_SETTINGS = {
         boolDirect("MEGACOMPACT_VC7A", "VC7A Frozen Range Crystals", "Frozen range crystals: caches a rendered prompt under an IMMUTABLE key built from the source ranges it covers, the digest of those covered bytes, the validated durable dependency high-water, and the renderer + provider profile — and deliberately NOT the global ledger frontier, so an unrelated append leaves the key unchanged instead of invalidating every crystal on every turn. Any covered-byte, dependency, renderer, or profile change invalidates 100%. Ranges are sorted by source start and overlapping ranges are rejected (CRY_RANGE_OVERLAP) rather than merged. The store is content-addressed and write-once: identical bytes re-written are idempotent, but a same-key/different-bytes write returns CRY_KEY_COLLISION and never overwrites, surfacing renderer non-determinism instead of hiding it. A store hit is mode A, a miss/collision forces a fresh deterministic render (mode B), and an unavailable store bypasses the cache entirely (mode C). OFF = byte-identical predecessor (VC6C); the crystal/store arithmetic still runs, only the reporter + dashboard seam is suppressed.", true),
         boolDirect("MEGACOMPACT_VC7B", "VC7B Provider Cache Economics", "Provider cache economics: extends the VC5B provider registry with cache economics (read/write price, TTL, minimum prefix, and a mandatory exclusion fixture id). Answers whether reusing a frozen crystal is actually worth it — a cache WRITE typically costs more than an uncached token, so a cache only pays off once a written prefix is re-read enough times before TTL expiry. Net savings are reported (never clamped at zero, so a losing cache stays visible) and every exclusion MUST name a proving conformance fixture or it is rejected (ECON_EXCLUSION_UNPROVEN). A compiled crystal boundary still reuses the VC7A key unchanged, and a randomized session-level experiment assigns arms by a stable hash so a lost assignment journal re-derives the same arm. OFF = byte-identical predecessor (VC7A); the economics/compiler/experiment arithmetic still runs, only the reporter + dashboard seam is suppressed.", true),
         boolDirect("MEGACOMPACT_VC7C", "VC7C Cache Diagnostics & Breakers", "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/dist/extensions/dashboard-server/routes-vector-cortex-outcomes.js

@@ -0,0 +1,79 @@
+/**
+ * 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 { VC8A_ENABLED } from "../../src/config.js";
+import { sendJson, readJsonBody } from "./routes-vector-cortex-shared.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, res, _ctx) {
+    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;
+            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 = {
+                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 = enabled ? "A" : "C";
+    const body = {
+        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/dist/extensions/mega-dashboard.js

@@ -15,11 +15,12 @@
 import { join } from "node:path";
 import { existsSync, mkdirSync, writeFileSync, appendFileSync } from "node:fs";
 export class Dashboard {
+    stateDir;
     snapshotPath;
     eventsPath;
     constructor(stateDir) {
-        if (!existsSync(stateDir))
-            mkdirSync(stateDir, { recursive: true });
+        this.stateDir = stateDir;
+        this.ensureDir();
         this.snapshotPath = join(stateDir, "dashboard.json");
         this.eventsPath = join(stateDir, "events.log");
     }
@@ -30,15 +31,34 @@ export class Dashboard {
     get lastWriteMs() {
         return this._lastWriteMs;
     }
-    /** Write a full state snapshot (atomically replaces previous). */
+    /** Re-create the state dir if it was removed since construction. */
+    ensureDir() {
+        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) {
-        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, data) {
-        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/dist/src/config/vector-cortex.js

@@ -211,6 +211,20 @@ export const VC7B_ENABLED = () => sprintFlag("MEGACOMPACT_VC7B");
  * EXCLUDED_SETTINGS), mirroring VC4A..VC7B.
  */
 export const VC7C_ENABLED = () => 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 = () => 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 { BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./vector-cortex-breakers.js";

package/dist/src/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, VC8A_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

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