pi-mega-compact 0.20.17 → 0.20.19

package/extensions/dashboard-client/src/tabs/VectorCortexPolicyCard.tsx

@@ -0,0 +1,43 @@
+import type React from "react";
+import type { VectorCortexPolicyView } from "../api/vector-cortex";
+import { Card, CardContent, CardHeader, CardTitle } from "../components/ui/card";
+import { Badge } from "../components/ui/badge";
+import { Metric } from "./VectorCortexMetric";
+
+export function VectorCortexPolicyCard({ view }: { view: VectorCortexPolicyView | null }): React.ReactElement {
+	return (
+		<Card>
+			<CardHeader>
+				<div className="flex items-center justify-between">
+					<CardTitle>Shadow Adaptive Policy (VC8B)</CardTitle>
+					{view?.enabled ? (
+						<Badge variant="success">ACTIVE</Badge>
+					) : (
+						<Badge variant="danger">OFF</Badge>
+					)}
+				</div>
+			</CardHeader>
+			<CardContent>
+				{!view?.enabled ? (
+					<div className="vc-empty">Shadow adaptive policy disabled (VC8B off) — no shadow decisions are reported, so the live path uses the predecessor thresholds (mode C). The policy, shadow, and M7 migration arithmetic still run; only this reporting seam is suppressed.</div>
+				) : (
+					<>
+						<div className="grid grid-cols-2 gap-4 md:grid-cols-4">
+							<Metric label="Mode" value={view.mode} />
+							<Metric label="Shadow decisions" value={String(view.shadowDecisions)} />
+							<Metric label="Clamped" value={String(view.clampedDecisions)} />
+							<Metric label="Rejected inputs" value={String(view.rejectedInputs)} />
+							<Metric label="Live mutations" value={String(view.liveMutations)} />
+							<Metric label="Pressure version" value={String(view.pressureVersion)} />
+							<Metric label="Last failure" value={view.lastFailure ?? "none"} />
+							<Metric label="Updated" value={view.updatedAt} />
+						</div>
+						<div className="mt-3 text-xs text-muted-foreground">
+							Reader-only shadow adaptive policy — aggregate counts and POL_/M7_ codes only. Policy actions are from a finite set chosen deterministically by the canonical pressure level; budgets are clamped into a configured window after the pressure factor. Unknown pressure labels are rejected as POL_PRESSURE_UNKNOWN, never coerced. The shadow engine is structurally incapable of affecting the live path — inputs are deep-copied and the prompt digest is pinned before and after — so liveMutations is always zero. M7 migrates legacy pressure labels to the v2 canonical five by copy/validate/switch; an unknown label blocks the switch (M7_PRESSURE_UNKNOWN). No prompt bytes, session content, or free-text ever reaches the client.
+						</div>
+					</>
+				)}
+			</CardContent>
+		</Card>
+	);
+}

package/extensions/dashboard-client/src/tabs/VectorCortexTab.tsx

@@ -26,6 +26,7 @@ import { VectorCortexCrystalsCard } from "./VectorCortexCrystalsCard";
 import { VectorCortexEconomicsCard } from "./VectorCortexEconomicsCard";
 import { VectorCortexDiagnosticsCard } from "./VectorCortexDiagnosticsCard";
 import { VectorCortexOutcomesCard } from "./VectorCortexOutcomesCard";
+import { VectorCortexPolicyCard } from "./VectorCortexPolicyCard";
 import {
 	VectorCortexShardsCard,
 	VectorCortexReconstructCard,
@@ -204,6 +205,7 @@ export default function VectorCortexTab(): React.ReactElement {
 			<VectorCortexEconomicsCard view={poll.economics} />
 			<VectorCortexDiagnosticsCard view={poll.diagnostics} />
 			<VectorCortexOutcomesCard view={poll.outcomes} />
+			<VectorCortexPolicyCard view={poll.policy} />
 			<VectorCortexLedgerCard ledger={poll.ledger} />
 		</div>
 	);

package/extensions/dashboard-client/src/tabs/useVectorCortexPoll.ts

@@ -20,6 +20,7 @@ import {
 	fetchVectorCortexEconomics,
 	fetchVectorCortexDiagnostics,
 	fetchVectorCortexOutcomes,
+	fetchVectorCortexPolicy,
 	fetchVectorCortexShards,
 	fetchVectorCortexTopology,
 	type VectorCortexEvaluationSummary,
@@ -37,6 +38,7 @@ import {
 	type VectorCortexEconomicsView,
 	type VectorCortexDiagnosticsView,
 	type VectorCortexOutcomesView,
+	type VectorCortexPolicyView,
 	type VectorCortexShardsView,
 	type VectorCortexTopologyView,
 } from "../api/vector-cortex";
@@ -61,6 +63,7 @@ export interface VectorCortexPollState {
 	economics: VectorCortexEconomicsView | null;
 	diagnostics: VectorCortexDiagnosticsView | null;
 	outcomes: VectorCortexOutcomesView | null;
+	policy: VectorCortexPolicyView | null;
 }
 
 export function useVectorCortexPoll(): [
@@ -87,6 +90,7 @@ export function useVectorCortexPoll(): [
 		economics: null,
 		diagnostics: null,
 		outcomes: null,
+		policy: null,
 	});
 
 	const poll = useCallback(() => {
@@ -116,6 +120,7 @@ export function useVectorCortexPoll(): [
 		fetchVectorCortexEconomics().then((economics) => setState((p) => ({ ...p, economics }))).catch(() => {});
 		fetchVectorCortexDiagnostics().then((diagnostics) => setState((p) => ({ ...p, diagnostics }))).catch(() => {});
 		fetchVectorCortexOutcomes().then((outcomes) => setState((p) => ({ ...p, outcomes }))).catch(() => {});
+		fetchVectorCortexPolicy().then((policy) => setState((p) => ({ ...p, policy }))).catch(() => {});
 	}, []);
 
 	useEffect(() => {

package/extensions/dashboard-client/src/types/vector-cortex-vc8.ts

@@ -23,3 +23,20 @@ export interface VectorCortexOutcomesView {
   lastFailure: string | null;
   updatedAt: string;
 }
+
+/**
+ * Reader-only shadow adaptive policy aggregate view (VC8B). Counts + POL_ and M7_
+ * codes only — the policy engine carries no payload, so no prompt bytes,
+ * session content, or free-text ever reaches the client.
+ */
+export interface VectorCortexPolicyView {
+  enabled: boolean;
+  mode: "A" | "B" | "C";
+  shadowDecisions: number;
+  clampedDecisions: number;
+  rejectedInputs: number;
+  liveMutations: number;
+  pressureVersion: number;
+  lastFailure: string | null;
+  updatedAt: string;
+}

package/extensions/dashboard-client/src/types/vector-cortex.ts

@@ -262,4 +262,4 @@ export type {
   VectorCortexDiagnosticsView,
 } from "./vector-cortex-vc7.js";
 
-export type { VectorCortexOutcomesView } from "./vector-cortex-vc8.js";
+export type { VectorCortexOutcomesView, VectorCortexPolicyView } from "./vector-cortex-vc8.js";

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

@@ -0,0 +1,36 @@
+/**
+ * api-contracts/vector-cortex-policy.ts — VC8B shadow adaptive policy API contract.
+ *
+ * PREVENT-PI-004: type definitions only, no network code.
+ * PREVENT-011: no `any` type.
+ *
+ * Reader-only GET /api/vector-cortex/policy diagnostics view (VC8B).
+ * COUNTS + CODES ONLY. The policy engine carries no payload — this surface
+ * exposes only aggregate decision counts and machine codes, never session
+ * content, prompt bytes, or free-text.
+ */
+
+/** Runtime triad mode implied by the VC8B flag state. */
+export type VectorCortexPolicyMode = "A" | "B" | "C";
+
+/** Reader-only policy + shadow aggregate view for GET /api/vector-cortex/policy. */
+export interface VectorCortexPolicyView {
+  /** Whether the VC8B policy flag is enabled. */
+  readonly enabled: boolean;
+  /** Runtime triad mode: A=shadow candidate, B=static calibrated, C=fixed legacy. */
+  readonly mode: VectorCortexPolicyMode;
+  /** Total shadow decisions evaluated (count only). */
+  readonly shadowDecisions: number;
+  /** Decisions whose budget was clamped at a bound (count only). */
+  readonly clampedDecisions: number;
+  /** Shadow rejections (unknown pressure / bad bounds) (count only). */
+  readonly rejectedInputs: number;
+  /** Live mutations detected (structurally always 0). */
+  readonly liveMutations: number;
+  /** M7 migration state: active pressure version (1 or 2). */
+  readonly pressureVersion: number;
+  /** Last POL_ or M7_ failure code, or null if none. */
+  readonly lastFailure: string | null;
+  /** ISO timestamp of the snapshot. */
+  readonly updatedAt: string;
+}

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

@@ -77,6 +77,11 @@ import { handleVectorCortexDiagnostics } from "./routes-vector-cortex-diagnostic
 // every file stays well under the 400-line extension soft limit.
 import { handleVectorCortexOutcomes } from "./routes-vector-cortex-outcomes.js";
 
+// VC8B shadow adaptive policy + M7 pressure-v2 gets its own module so the
+// policy/shadow seam stays independent and every file stays well under the
+// 400-line extension soft limit.
+import { handleVectorCortexPolicy } from "./routes-vector-cortex-policy.js";
+
 /**
  * Dispatch a request through every registered route handler.
  * Returns true if a handler claimed the request (ended the response).
@@ -134,5 +139,6 @@ export function dispatchRoutes(
 	if (handleVectorCortexEconomics(req, res, ctx)) return true;
 	if (handleVectorCortexDiagnostics(req, res, ctx)) return true;
 	if (handleVectorCortexOutcomes(req, res, ctx)) return true;
+	if (handleVectorCortexPolicy(req, res, ctx)) return true;
 	return false;
 }

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

@@ -180,5 +180,11 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"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,
 		),
+		boolDirect(
+			"MEGACOMPACT_VC8B",
+			"VC8B Shadow Adaptive Policy",
+			"Bounded shadow adaptive policy + M7 pressure-v2 migration. Policy actions are from a finite set (admit/dampen/defer/escalate/reject) chosen deterministically by the canonical pressure level; token budgets are clamped into a configured window after the pressure factor. Unknown pressure labels are rejected as POL_PRESSURE_UNKNOWN, never coerced to a neighbour. The shadow engine is structurally incapable of affecting the live path: inputs are deep-copied, the canonical prompt digest is pinned before and after to prove non-mutation, and liveMutations is always zero. M7 migrates legacy pressure labels to the v2 canonical five by copy/validate/switch; an unknown label blocks the switch and keeps the legacy pointer (M7_PRESSURE_UNKNOWN). A shadow decision is mode A, static calibrated policy is mode B (forced by invalid A), and fixed legacy thresholds is mode C (forced by M7 or B failure). OFF = byte-identical predecessor (VC8A); the policy/shadow/migration arithmetic still runs, only the reporter + dashboard seam is suppressed.",
+			true,
+		),
 	],
 };

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

@@ -0,0 +1,55 @@
+/**
+ * dashboard-server/routes-vector-cortex-policy.ts — VC8B policy dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/policy returning the shadow adaptive
+ * policy aggregate diagnostics: whether the VC8B flag is enabled, the runtime
+ * triad mode, how many shadow decisions were evaluated, how many were clamped
+ * at a bound, how many were rejected (unknown pressure / bad bounds), the
+ * live-mutation count (structurally always 0), the active pressure version,
+ * and the last POL_ or M7_ failure code.
+ *
+ * COUNTS + CODES ONLY. The policy engine carries no payload, so this route
+ * NEVER exposes prompt bytes, session content, or free-text — only aggregate
+ * counts and machine codes.
+ *
+ * Guardrails: PREVENT-PI-004 (local in-process state only), PREVENT-011 (no
+ * `any`), reader-only aggregate (counts + codes only).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import { VC8B_ENABLED } from "../../src/config.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import type { VectorCortexPolicyView } from "./api-contracts/vector-cortex-policy.js";
+
+/** GET /api/vector-cortex/policy — reader-only policy + shadow aggregate (VC8B). */
+export function handleVectorCortexPolicy(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+
+  if (path !== "/api/vector-cortex/policy") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC8B_ENABLED();
+  const mode: VectorCortexPolicyView["mode"] = enabled ? "A" : "C";
+  const body: VectorCortexPolicyView = {
+    enabled,
+    mode,
+    shadowDecisions: 0,
+    clampedDecisions: 0,
+    rejectedInputs: 0,
+    liveMutations: 0,
+    pressureVersion: 1,
+    lastFailure: null,
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.17",
+  "version": "0.20.19",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/config/vector-cortex.ts

@@ -254,6 +254,21 @@ export const VC7C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC7C");
  */
 export const VC8A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC8A");
 
+/**
+ * VC8B — bounded shadow adaptive policy + M7 pressure-v2. Default ON.
+ * `MEGACOMPACT_VC8B=0` disables and is byte-identical to the predecessor
+ * (VC8A): the policy engine, shadow evaluator, and M7 migration STILL RUN
+ * (they are PURE — action validation, budget clamping, pressure canonicalization
+ * and copy/validate/switch, with no clock, storage, or network), so a budget is
+ * still clamped identically and an unknown pressure label is still rejected. The
+ * flag gates ONLY the `vector_cortex_shadow_decision_recorded` /
+ * `vector_cortex_policy_action_rejected` events and the policy 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..VC8A.
+ */
+export const VC8B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC8B");
+
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker) extracted to
 // vector-cortex-breakers.ts to keep this file under the 300-line soft limit.
 export {

package/src/config.ts

@@ -176,6 +176,7 @@ export {
   VC7B_ENABLED,
   VC7C_ENABLED,
   VC8A_ENABLED,
+  VC8B_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

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

@@ -0,0 +1,82 @@
+/**
+ * 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";
+import type { PolicyAction, PolicyReason, PressureLevel } from "./types.js";
+
+/** The two structured events the VC8B reporter emits. */
+export type PolicyEventName =
+  | "vector_cortex_shadow_decision_recorded"
+  | "vector_cortex_policy_action_rejected";
+
+/** Optional emit fn injected by the runtime; tests pass `undefined`. */
+export type PolicyEmit = (name: string, payload: unknown) => void;
+
+/** Run `fn` only when an emit exists; a reporting failure is never fatal. */
+function safe(emit: PolicyEmit | undefined, fn: (emit: PolicyEmit) => void): void {
+  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: PolicyEmit | undefined,
+  decision: {
+    readonly decisionId: string;
+    readonly sessionId: string;
+    readonly action: PolicyAction;
+    readonly budget: number;
+    readonly pressure: PressureLevel;
+    readonly reason: PolicyReason;
+  },
+): void {
+  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: PolicyEmit | undefined,
+  rejection: { readonly decisionId: string; readonly code: string },
+): void {
+  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/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
+  );
+}