pi-mega-compact 0.20.2 → 0.20.4

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.ts

@@ -22,3 +22,4 @@ 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

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

package/extensions/dashboard-server/server.ts

@@ -66,6 +66,7 @@ import {
 	handleVectorCortexShards,
 	handleVectorCortexResidual,
 	handleVectorCortexReconstruct,
+	handleVectorCortexPlans,
 	handleStatic,
 } from "./routes.js";
 
@@ -235,15 +236,16 @@ export async function launchDashboardServer(
 		detectCrossRepoDrift,
 	});
 
-	// Bind host resolution: explicit MEGACOMPACT_DASHBOARD_HOST override wins;
-	// otherwise auto-bind to the Tailscale interface (tailnet access); fall back
-	// to loopback when Tailscale is absent. 0.0.0.0 means "all interfaces" and
-	// opts into permissive CORS below.
-	const host =
-		process.env.MEGACOMPACT_DASHBOARD_HOST ??
-		detectTailscaleIP() ??
-		"127.0.0.1";
+	// Bind host resolution. Default: ALL interfaces (0.0.0.0) so the dashboard
+	// is reachable on loopback (localhost — the launcher's health check + the
+	// local browser), the tailnet (Tailscale), and any LAN interface. The
+	// network-denial gate was removed (the user opted into open access);
+	// MEGACOMPACT_DASHBOARD_HOST overrides for anyone who wants to restrict to
+	// a single interface. The tailnet IP is still detected so we can surface it
+	// as the remote access address. 0.0.0.0 opts into permissive CORS below.
+	const host = process.env.MEGACOMPACT_DASHBOARD_HOST ?? "0.0.0.0";
 	const allInterfaces = host === "0.0.0.0";
+	const tailscaleIP = allInterfaces ? detectTailscaleIP() : null;
 
 	// guardrails-allow PREVENT-PI-004: optional, user-triggered /dashboard server (tailnet-local via Tailscale mesh or loopback); no remote outbound calls.
 	const server = createServer((req: IncomingMessage, res: ServerResponse) => {
@@ -310,6 +312,7 @@ export async function launchDashboardServer(
 		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);
 	});
 
@@ -334,27 +337,33 @@ export async function launchDashboardServer(
 			});
 
 			server.listen(port, host, () => {
-				// When bound to the loopback, keep the legacy localhost URL so the
-				// user's browser (which resolves localhost → ::1 or 127.0.0.1) works.
-				// When bound to a tailnet/tailscale IP, surface that address instead.
+				// Surface localhost for local reach (the launcher health-checks
+				// localhost + the local browser uses it), and — when bound to all
+				// interfaces with a tailnet present — also surface the tailnet
+				// address for remote devices on the mesh.
+				const localUrl = `http://localhost:${port}`; // guardrails-allow PREVENT-PI-004: dashboard URL (loopback/all-interfaces, user-opted open access)
+				const tailnetUrl =
+					allInterfaces && tailscaleIP ? `http://${tailscaleIP}:${port}` : null; // guardrails-allow PREVENT-PI-004: dashboard URL (tailnet, user-opted open access)
 				const url =
 					host === "127.0.0.1"
-						? `http://localhost:${port}`
-						: `http://${host}:${port}`; // guardrails-allow PREVENT-PI-004: dashboard URL (tailnet-local via Tailscale mesh or loopback)
-				log("server running", { url, host });
+						? localUrl
+						: tailnetUrl ?? `http://${host}:${port}`;
+				log("server running", { url, host, tailnetUrl });
 				// eslint-disable-next-line no-console
-				console.log(`[mega-compact] dashboard server running: ${url}`);
+				console.log(
+					`[mega-compact] dashboard server running: ${url}` +
+						(tailnetUrl ? ` (also ${localUrl})` : ""),
+				);
 
-				// v0.8.2: also bind the IPv6 loopback (::1) when bound to the IPv4
-				// loopback. On many systems `localhost` resolves to ::1 first (see
-				// /etc/hosts), so an IPv4-only bind makes the browser hit ::1:port and
-				// get connection refused. PREVENT-PI-004 (loopback-only) means BOTH
-				// 127.0.0.1 and ::1. When bound to a tailscale/0.0.0.0 host, we do NOT
-				// bind ::1 — the tailnet address is what the user reaches. Non-fatal:
+				// v0.8.2: also bind the IPv6 loopback (::1) when localhost must work.
+				// On many systems `localhost` resolves to ::1 first (see /etc/hosts),
+				// so an IPv4-only bind makes the browser hit ::1:port and get refused.
+				// Bind ::1 for the explicit loopback bind AND the all-interfaces bind
+				// (a browser resolving localhost → ::1 must still connect). Non-fatal:
 				// IPv4-only hosts or a ::1 already in use just skip the mirror.
 				let v6: ReturnType<typeof createServer> | undefined;
 				const v4Handler = server.listeners("request")[0];
-				if (host === "127.0.0.1" && v4Handler) {
+				if ((host === "127.0.0.1" || allInterfaces) && v4Handler) {
 					v6 = createServer((r, s) =>
 						(v4Handler as (a: IncomingMessage, b: ServerResponse) => void).call(
 							server,

package/package.json

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

@@ -174,6 +174,20 @@ export const VC4B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_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

@@ -166,6 +166,7 @@ export {
   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;