pi-mega-compact 0.20.1 → 0.20.3

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

@@ -230,6 +230,72 @@ export interface VectorCortexResidualView {
   readonly updatedAt: string;
 }
 
+/**
+ * Reader-only reconstruction-fidelity aggregate for GET /api/vector-cortex/reconstruct
+ * (VC4C). Purely an enabled-flag + COUNT/BYTE aggregate — closure attempts,
+ * rejections, validated/invalidated counts, span total, and byte total.
+ * Reader-only: NEVER exposes reconstructed spans, exact bytes, or prompt text.
+ * The reconstruction validator is pure in-memory logic in this sprint (no
+ * durable metrics store), so when no closure has been staged the aggregates are
+ * truthfully zero. Non-fatal: a missing state dir degrades to `enabled:false`.
+ */
+export interface VectorCortexReconstructView {
+  /** Whether the VC4C reconstruction fidelity flag is enabled in this process. */
+  readonly enabled: boolean;
+  /** Number of closure attempts observed by the process emitter. */
+  readonly closureAttempts: number;
+  /** Number of closures rejected (events vector_cortex_closure_rejected). */
+  readonly closureRejections: number;
+  /** Number of reconstructions validated (events vector_cortex_reconstruction_validated). */
+  readonly validatedCount: number;
+  /** Number of reconstructions invalidated (failed validation). */
+  readonly invalidatedCount: number;
+  /** Total reconstructed spans across validated reconstructions. */
+  readonly spanTotal: number;
+  /** Total reconstructed bytes across validated reconstructions. */
+  readonly byteTotal: number;
+  /** ISO timestamp of the snapshot. */
+  readonly updatedAt: string;
+}
+
+/**
+ * Reader-only plan manifest view for GET /api/vector-cortex/plans (VC5A).
+ *
+ * Exposes ONLY plan manifests — the VC5A PromptDagV1 + budgeted-planner output:
+ * registered DAG/plan identifiers, the mandatory-closure status, selected-node
+ * manifests, and the mandatory-overflow signal. NEVER exposes session payloads,
+ * prompt text, byte spans, or source bytes (reader-only, SECURITY_PRIVACY).
+ *
+ * Flag-gated on MEGACOMPACT_VC5A: `enabled:false` when off (byte-identical to the
+ * pre-VC5A predecessor). Non-fatal: a missing manifest store degrades to
+ * `enabled:false` with empty arrays.
+ */
+export interface VectorCortexPlanManifest {
+  /** Stable plan id (e.g. "PLN-009"). */
+  readonly id: string;
+  /** Whether the mandatory dependency/tool/anchor closure fit within budget. */
+  readonly mandatoryInBudget: boolean;
+  /** Selected optional node ids under the budgeted portfolio (sorted by id bytes). */
+  readonly selectedNodeIds: readonly string[];
+  /** Total planned token estimate (mandatory framed + selected framed). */
+  readonly tokenTotal: number;
+  /** true when the mandatory closure exceeded budget (demoted to mode C). */
+  readonly demotedToC: boolean;
+}
+
+export interface VectorCortexPlansView {
+  /** Whether the VC5A PromptDagV1 + budgeted-planner flag is enabled. */
+  readonly enabled: boolean;
+  /** Count of registered PromptDagV1 fixtures (DAG-001..). */
+  readonly dagCount: number;
+  /** Count of registered plan fixtures (PLN-001..). */
+  readonly plannerCount: number;
+  /** Plan manifests (reader-only, no payloads). */
+  readonly plans: readonly VectorCortexPlanManifest[];
+  /** ISO timestamp of the snapshot. */
+  readonly updatedAt: string;
+}
+
 /**
  * Reader-only occurrence-ledger view for GET /api/vector-cortex/ledger (VC1B).
  * Built on the LedgerReader capability surface. Exposes occurrence IDENTITY

package/extensions/dashboard-server/routes-rag-settings-helpers.ts

@@ -361,6 +361,18 @@ export const SETTINGS: ReadonlyArray<{
 				"Residual codec: orthonormal DCT-II basis + int16 block quantization + block-scoped exact correction stream + (9,6) Reed-Solomon parity shards with SHA-256 corruption detection; admission gates on encodedSize <= 95% of exact-compressed size. OFF = mode C, no residual artifact produced, byte-identical predecessor.",
 				true,
 			),
+			boolDirect(
+				"MEGACOMPACT_VC4C",
+				"VC4C Reconstruction Fidelity",
+				"Conservative closure + source-order assembly + reconstruction validator: recursively closes dependencies and whole tool pairs to a fixed point, resolves contradictions by retaining the later exact source resolution, assembles spans solely by source range, and rejects missing anchors / split pairs / digest mismatch / unresolved contradiction. Mandatory token estimate is content-only and handed unchanged to VC5A. OFF = mode C, no closure/validator, byte-identical predecessor (VC4B).",
+				true,
+			),
+			boolDirect(
+				"MEGACOMPACT_VC5A",
+				"VC5A PromptDagV1 + Budgeted Planner",
+				"Single-session DAG (PromptDagV1) + budgeted 0/1 portfolio planner: builds a stable Kahn-ordered DAG, computes the mandatory dependency/tool/anchor closure before optional selection, returns MANDATORY_CLOSURE_OVER_BUDGET with evidence preserved on overflow, and runs a utility-per-token portfolio that never exceeds the remaining budget. Framing is owned here, not in VC4C. OFF = byte-identical predecessor (VC4C).",
+				true,
+			),
 		],
 	},
 	{

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

@@ -0,0 +1,58 @@
+/**
+ * dashboard-server/routes-vector-cortex-plans.ts — VC5A PromptDagV1 + budgeted
+ * planner dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/plans returning ONLY plan manifests — the
+ * registered PromptDagV1 (DAG-001..030) and budgeted-planner (PLN-001..020)
+ * identifier counts, plus a reader-only plans array. NEVER exposes session
+ * payloads, prompt text, byte spans, or source bytes (reader-only,
+ * SECURITY_PRIVACY). Flag-gated on MEGACOMPACT_VC5A: `enabled:false` when off
+ * (byte-identical to the pre-VC5A predecessor).
+ *
+ * The VC5A planner is PURE IN-MEMORY logic in this sprint (it has no durable plan
+ * store yet), so the per-run plan outputs are not persisted. The route reports
+ * the registered manifest layout truthfully: `enabled` reflects the flag, the
+ * dag/planner counts come from the registered conformance ID range, and `plans`
+ * is empty until a future sprint persists selected plans. Non-fatal: an internal
+ * error degrades to `enabled:false` with empty arrays.
+ *
+ * Guardrails: PREVENT-PI-004 (local filesystem / in-process state only),
+ * PREVENT-011 (no `any`), reader-only aggregate (counts + manifests only).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import { VC5A_ENABLED } from "../../src/config.js";
+import { DAG_IDS } from "../../src/vector-cortex/prompt-dag/types.js";
+import { PLN_IDS } from "../../src/vector-cortex/planner/types.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import type { VectorCortexPlansView } from "./api-contracts/vector-cortex.js";
+
+/**
+ * Reader-only GET /api/vector-cortex/plans (VC5A).
+ */
+export function handleVectorCortexPlans(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+  if (path !== "/api/vector-cortex/plans") return false;
+  if (req.method !== "GET") {
+    // Reader-only path: cannot be "off" without a GET; it is genuinely read-only.
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC5A_ENABLED();
+  const body: VectorCortexPlansView = {
+    enabled,
+    dagCount: enabled ? DAG_IDS.length : 0,
+    plannerCount: enabled ? PLN_IDS.length : 0,
+    plans: [],
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Dashboard handler: GET /api/vector-cortex/reconstruct (VC4C).
+ *
+ * Reader-only reconstruction-fidelity aggregate. Mirrors the VC4B residual
+ * handler: path guard + 405 on non-GET, gated on the sprint flag, returns a
+ * zero-valued view when disabled (byte-identical predecessor contract). Never
+ * returns reconstructed spans, exact bytes, or prompt text.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import { VC4C_ENABLED } from "../../src/config.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import type { VectorCortexReconstructView } from "./api-contracts/vector-cortex.js";
+
+export function handleVectorCortexReconstruct(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+  if (path !== "/api/vector-cortex/reconstruct") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+  const enabled = VC4C_ENABLED();
+  const body: VectorCortexReconstructView = {
+    enabled,
+    closureAttempts: 0,
+    closureRejections: 0,
+    validatedCount: 0,
+    invalidatedCount: 0,
+    spanTotal: 0,
+    byteTotal: 0,
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

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

@@ -21,3 +21,5 @@ export { handleVectorCortexTopology } from "./routes-vector-cortex-topology.js";
 export { handleVectorCortexQuery } from "./routes-vector-cortex-query.js";
 export { handleVectorCortexShards } from "./routes-vector-cortex-shards.js";
 export { handleVectorCortexResidual } from "./routes-vector-cortex-residual.js";
+export { handleVectorCortexReconstruct } from "./routes-vector-cortex-reconstruct.js";
+export { handleVectorCortexPlans } from "./routes-vector-cortex-plans.js";

package/extensions/dashboard-server/routes.ts

@@ -49,4 +49,6 @@ export {
 	handleVectorCortexQuery,
 	handleVectorCortexShards,
 	handleVectorCortexResidual,
+	handleVectorCortexReconstruct,
+	handleVectorCortexPlans,
 } from "./routes-vector-cortex.js";

package/extensions/dashboard-server/server.ts

@@ -65,6 +65,8 @@ import {
 	handleVectorCortexQuery,
 	handleVectorCortexShards,
 	handleVectorCortexResidual,
+	handleVectorCortexReconstruct,
+	handleVectorCortexPlans,
 	handleStatic,
 } from "./routes.js";
 
@@ -308,6 +310,8 @@ export async function launchDashboardServer(
 		if (handleVectorCortexQuery(req, res, ctx)) return;
 		if (handleVectorCortexShards(req, res, ctx)) return;
 		if (handleVectorCortexResidual(req, res, ctx)) return;
+		if (handleVectorCortexReconstruct(req, res, ctx)) return;
+		if (handleVectorCortexPlans(req, res, ctx)) return;
 		handleStatic(req, res, ctx);
 	});
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.1",
+  "version": "0.20.3",
   "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

@@ -160,6 +160,34 @@ export const VC4A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC4A");
  */
 export const VC4B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC4B");
 
+/**
+ * VC4C — reconstruction fidelity (closure + assemble + validate). Default ON.
+ * `MEGACOMPACT_VC4C=0` disables and is byte-identical to the predecessor
+ * (VC4B): no conservative closure is computed, the reconstruction validator's
+ * `vector_cortex_reconstruction_validated` / `vector_cortex_closure_rejected`
+ * events are never emitted, and the assembled reconstruction is never produced
+ * (the prompt continues to be built by the legacy VC4B exact/residual path and
+ * the VC4A shard goldens are unchanged). The closure/assemble/validate
+ * functions are PURE — flag OFF gates the reporter seam, never the arithmetic.
+ * This flag MUST also be a dashboard SETTINGS toggle (visible in config UI,
+ * never in EXCLUDED_SETTINGS), mirroring VC4A/VC4B.
+ */
+export const VC4C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC4C");
+
+/**
+ * VC5A — PromptDagV1 + budgeted portfolio planner. Default ON.
+ * `MEGACOMPACT_VC5A=0` disables and is byte-identical to the predecessor
+ * (VC4C): no prompt DAG is built or validated, no budgeted plan is selected,
+ * the `vector_cortex_plan_selected` / `vector_cortex_plan_mandatory_overflow`
+ * events are never emitted, and the prompt continues to be built by the
+ * predecessor VC4C closure/reconstruction path (its goldens are unchanged).
+ * The builder/validator/portfolio functions are PURE — flag OFF gates the
+ * reporter + dashboard seam, never the arithmetic. This flag MUST also be a
+ * dashboard SETTINGS toggle (visible in config UI, never in EXCLUDED_SETTINGS),
+ * mirroring VC4A/VC4B/VC4C.
+ */
+export const VC5A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC5A");
+
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/src/config.ts

@@ -165,6 +165,8 @@ export {
   VC3C_ENABLED,
   VC4A_ENABLED,
   VC4B_ENABLED,
+  VC4C_ENABLED,
+  VC5A_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

package/src/vector-cortex/planner/manifest.ts

@@ -0,0 +1,83 @@
+/**
+ * vector-cortex/planner/manifest.ts — plan manifest identity + pre-provider
+ * revalidation (VC5A).
+ *
+ * Split from `portfolio.ts` (which owns SELECTION) so each file keeps one
+ * concern and stays under the 300-line soft limit: this module owns the plan's
+ * IDENTITY and the last gate before a provider call.
+ *
+ * The manifest digest deliberately covers PER-NODE TOKEN COUNTS, which the DAG
+ * digest does not: token counts are a planner input rather than DAG structure.
+ * That is exactly what makes the sprint's unique failure injection detectable —
+ * mutating a node's token count after planning but before validation changes the
+ * recomputed manifest digest, so `validatePlanManifest` returns
+ * `PLN_MANIFEST_DIGEST_MISMATCH` and the plan never reaches the provider.
+ *
+ * Pure/deterministic: no storage, no console, no network (PREVENT-PI-004).
+ */
+
+import { createHash } from "node:crypto";
+
+import type { PlanCandidate, PlanV1 } from "./types.js";
+
+/**
+ * Deterministic digest over a plan AND the token counts/utilities it was
+ * selected with. Hashing walks `selectedNodeIds` in its stored (sorted) order,
+ * so the digest is a pure function of the plan and the candidate facts.
+ *
+ * A node missing from `candidates` hashes as `-1`, so dropping a candidate is
+ * itself a detectable mutation rather than a silently-skipped field.
+ */
+export function planManifestDigest(
+  plan: PlanV1,
+  candidates: readonly PlanCandidate[],
+): string {
+  const h = createHash("sha256");
+  h.update(plan.schema);
+  h.update(" ");
+  h.update(plan.dagDigest);
+  h.update(" ");
+  h.update(String(plan.tokenBudget));
+  h.update(" ");
+  h.update(String(plan.tokenTotal));
+  h.update(" ");
+  h.update(String(plan.dependencyHighWater));
+  const byId = new Map(candidates.map((c) => [c.nodeId, c]));
+  for (const id of plan.selectedNodeIds) {
+    const c = byId.get(id);
+    h.update("");
+    h.update(id);
+    h.update(" ");
+    // Token count is part of the identity — a post-plan mutation breaks it.
+    h.update(String(c?.tokenEstimate ?? -1));
+    h.update(" ");
+    h.update(String(c?.utility ?? -1));
+  }
+  return h.digest("hex");
+}
+
+/** The verdict of the pre-provider manifest revalidation. */
+export type PlanManifestValidation =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly code: "PLN_MANIFEST_DIGEST_MISMATCH" };
+
+/**
+ * Re-validate a plan against the candidates AS THEY STAND NOW, immediately
+ * before a provider call. Returns `PLN_MANIFEST_DIGEST_MISMATCH` when the
+ * recomputed manifest digest disagrees with the digest pinned at planning time.
+ *
+ * This is the sprint's unique failure injection: a node token count mutated
+ * after planning but before validation is caught here, BEFORE the provider is
+ * invoked, rather than producing a prompt whose real cost differs from the
+ * admitted budget.
+ */
+export function validatePlanManifest(
+  plan: PlanV1,
+  candidates: readonly PlanCandidate[],
+  pinnedDigest: string,
+): PlanManifestValidation {
+  if (planManifestDigest(plan, candidates) !== pinnedDigest) {
+    return { ok: false, code: "PLN_MANIFEST_DIGEST_MISMATCH" };
+  }
+  return { ok: true };
+}

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

@@ -0,0 +1,190 @@
+/**
+ * vector-cortex/planner/types.ts — `PlanV1` + the budget admission contract
+ * (VC5A, task 1).
+ *
+ * VC5A EXCLUSIVELY OWNS FRAMING + BUDGET ADMISSION (CONTRACTS §plan and
+ * closure). VC4C hands over `ClosureResult.mandatoryTokenEstimate`, a
+ * CONTENT-ONLY count with no prompt framing, no role tags and no separators, and
+ * VC4C never truncates a mandatory node nor reasons about a budget. This module
+ * adds the framing cost on top of that content estimate and decides admission:
+ *
+ *   framed(node)   = tokenEstimate + framingPerNode
+ *   mandatoryCost  = mandatoryTokenEstimate + framingPerNode * |mandatory|
+ *                    + framingOverhead
+ *
+ * If `mandatoryCost > tokenBudget` the planner returns
+ * `MANDATORY_CLOSURE_OVER_BUDGET` and the adapter demotes to C. Crucially it
+ * does so WITHOUT DROPPING EVIDENCE: the mandatory set is returned intact on the
+ * failure so the caller can report exactly what did not fit (the sprint bar:
+ * "over-budget mandatory closure never drops evidence and always demotes").
+ *
+ * The framing constants are CONFIGURABLE, never invented magic numbers: a caller
+ * supplies the profile it is actually rendering with, and the defaults below are
+ * documented as a conservative baseline rather than a measured provider fact.
+ *
+ * Pure types + registered conformance IDs: no storage, no console, no network
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+
+/**
+ * The prompt framing cost model. These are the ONLY places framing enters the
+ * budget, keeping the VC4C content-only estimate cleanly separable.
+ *
+ * `perNode` is the per-node envelope (role tag + separator) a renderer adds
+ * around one node's content. `overhead` is the whole-prompt fixed cost (system
+ * preamble scaffolding, closing delimiters) charged once.
+ *
+ * Both DEFAULT to a conservative baseline and are overridable per call, so a
+ * provider profile with a measured framing cost (VC5B) supplies its own numbers
+ * rather than inheriting a guess.
+ */
+export interface FramingProfile {
+  /** Tokens added around each selected node (role tag + separator). */
+  readonly perNode: number;
+  /** Fixed whole-prompt framing tokens charged once. */
+  readonly overhead: number;
+}
+
+/**
+ * Conservative default framing baseline. Documented as a BASELINE, not a
+ * measured provider constant: a real provider profile (VC5B) overrides it. Kept
+ * small and explicit so a default-driven plan is never silently over-optimistic.
+ */
+export const DEFAULT_FRAMING: FramingProfile = { perNode: 4, overhead: 8 };
+
+/**
+ * One candidate offered to the 0/1 portfolio. `mandatory` candidates are the
+ * closed set from VC4C and are admitted before any optional selection; optional
+ * candidates compete for the REMAINING budget.
+ *
+ * `sourceSeq` is the source ordering fact used as the FIRST tie-break after
+ * utility-per-token, so two equally efficient candidates resolve by source
+ * position (earlier wins) and then by ID bytes — a total, deterministic order.
+ */
+export interface PlanCandidate {
+  readonly nodeId: string;
+  /** CONTENT-ONLY token estimate (framing is added by the planner). */
+  readonly tokenEstimate: number;
+  /** Selection value; higher is better. Ratio is `utility / framedTokens`. */
+  readonly utility: number;
+  /** Source sequence position, the first tie-break after the ratio. */
+  readonly sourceSeq: bigint;
+  /** True when the candidate is part of the mandatory closure. */
+  readonly mandatory: boolean;
+}
+
+/** Why a candidate was left out of the plan (recorded, never silent). */
+export interface PlanOmission {
+  readonly nodeId: string;
+  readonly reason: "over-budget" | "incompatible" | "zero-utility";
+}
+
+/** Planner failure codes (registered PLN codes). */
+export type PlanFailureCode =
+  /**
+   * The mandatory closure alone (with framing) exceeds `tokenBudget`. Evidence
+   * is NOT dropped — the mandatory set is returned intact and the adapter
+   * demotes to C.
+   */
+  | "MANDATORY_CLOSURE_OVER_BUDGET"
+  /** A candidate names a node absent from the DAG. */
+  | "PLN_UNKNOWN_NODE"
+  /** Two selected nodes declare mutual incompatibility. */
+  | "PLN_INCOMPATIBLE_SELECTION"
+  /** The DAG digest recorded in the plan no longer matches the DAG. */
+  | "PLN_MANIFEST_DIGEST_MISMATCH"
+  /** The budget itself is invalid (negative or non-finite). */
+  | "PLN_INVALID_BUDGET";
+
+/**
+ * The accepted plan (CONTRACTS §plan and closure). `selectedNodeIds` is sorted
+ * for a stable manifest; `tokenTotal` is the FRAMED total and is guaranteed
+ * `<= tokenBudget` for every accepted plan.
+ */
+export interface PlanV1 {
+  readonly schema: "plan-v1";
+  /** Digest of the DAG this plan was selected over (binds plan to structure). */
+  readonly dagDigest: string;
+  /** The selected node IDs, sorted by ID bytes. */
+  readonly selectedNodeIds: readonly string[];
+  /** The budget this plan was admitted against. */
+  readonly tokenBudget: number;
+  /** Framed token total of the selection; always `<= tokenBudget`. */
+  readonly tokenTotal: number;
+  /** Summed utility of the selection. */
+  readonly utilityTotal: number;
+  /** The durable authority high-water the plan's evidence depends on. */
+  readonly dependencyHighWater: bigint;
+  /** Candidates deliberately left out, with the reason. */
+  readonly omissions: readonly PlanOmission[];
+}
+
+/**
+ * The planner verdict. On failure the mandatory set is preserved so an
+ * over-budget closure can be reported WITHOUT dropping evidence.
+ */
+export type PlanResult =
+  | { readonly ok: true; readonly plan: PlanV1 }
+  | {
+      readonly ok: false;
+      readonly code: PlanFailureCode;
+      /** The intact mandatory node IDs (never dropped on failure). */
+      readonly mandatory: readonly string[];
+      /** The framed cost of the mandatory set that could not be admitted. */
+      readonly mandatoryCost: number;
+      /** The budget the mandatory cost was measured against. */
+      readonly tokenBudget: number;
+    };
+
+/**
+ * The triad mode VC5A selects (TRIAD_RESILIENCE). A/B/C are INDEPENDENT
+ * algorithms:
+ *
+ *   A = the 0/1 portfolio optimizer (ratio-ordered admission);
+ *   B = a stable greedy closed planner, forced by an A exception — it shares no
+ *       ratio ordering with A and admits strictly in source order;
+ *   C = the predecessor prompt, forced by mandatory overflow; it states its loss
+ *       of old semantic context (continuity, NOT completeness).
+ */
+export type PlanMode = "A" | "B" | "C";
+
+/** The two structured events the VC5A reporter emits. */
+export type PlanEventName =
+  | "vector_cortex_plan_selected"
+  | "vector_cortex_plan_mandatory_overflow";
+
+/** Injected emit callback — same (event, fields) shape as the other VC seams. */
+export type PlanEmitter = (
+  event: PlanEventName,
+  fields: Record<string, unknown>,
+) => void;
+
+/** Typed, best-effort reporter bound to the two plan event names. */
+export interface PlanReporter {
+  readonly planSelected: (fields: Record<string, unknown>) => void;
+  readonly planMandatoryOverflow: (fields: Record<string, unknown>) => void;
+}
+
+/**
+ * Aggregate-only plan metrics for the dashboard (counts/tokens only, never
+ * prompt text or node payloads).
+ */
+export interface PlanMetricsV1 {
+  readonly plansSelected: number;
+  readonly mandatoryOverflows: number;
+  readonly nodesSelected: number;
+  readonly tokenTotal: number;
+}
+
+/**
+ * Registered PLN conformance ID range (PLN-001..020). The acceptance aggregator
+ * reads these rows from the v2 manifest and asserts each returns its manifest
+ * `ok`/`code`.
+ */
+export const PLN_IDS: readonly string[] = Array.from(
+  { length: 20 },
+  (_v, i) => `PLN-${String(i + 1).padStart(3, "0")}`,
+);
+
+/** Named VC5A planner conformance assertions (the sprint's headline rows). */
+export const PLAN_NAMED_IDS = ["PLN-MANDATORY-002", "PLN-TIE-003"] as const;