pi-mega-compact 0.20.26 → 0.20.27

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

@@ -0,0 +1,167 @@
+/**
+ * dashboard-server/routes-setup-cortex.ts — VC9A Setup Cortex status route.
+ *
+ *   GET /api/setup-cortex-status — reader-only aggregate surfacing the
+ *        vector-cortex encoder gate (mode A/B/C, qualification verdict,
+ *        blockers, encoder health) for the dashboard Setup tab. Does NOT close
+ *        the ML gate: the hard-gate blockers are read-only and stay open.
+ *
+ * Reuses readEncoderManifest / verifyEncoderAsset / detectPlatform
+ * (src/vector-cortex/encoder/asset.ts) and deriveVcStatus (vc-status.ts),
+ * plus the memoized encoder-facts pattern from routes-vector-cortex-health.ts
+ * (manifest bytes + file size/mtime + platform cache key) so the expensive
+ * full-asset hashing is skipped on repeat polls.
+ *
+ * The blocker rows carry NO string literals here — they come from the static
+ * manifest module setup-cortex-blockers.ts (single canonical source).
+ *
+ * Guardrails: PREVENT-PI-004 (local filesystem read only), PREVENT-011 (no
+ * `any`), reader-only aggregate (never payloads/prompts/ledger — EVAL-REDACT-002).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { RouteContext } from "./routes-core.js";
+import { VC9A_ENABLED } from "../../src/config.js";
+import { readEncoderManifest, verifyEncoderAsset, detectPlatform } from "../../src/vector-cortex/encoder/asset.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import { deriveVcStatus } from "./vc-status.js";
+import { SETUP_CORTEX_BLOCKERS } from "./setup-cortex-blockers.js";
+import type {
+  SetupCortexStatusResponse,
+  BlockerV1,
+} from "./api-contracts/setup-cortex.js";
+
+/** Resolve the committed encoder-v1 asset dir by walking up to the repo root. */
+function encoderAssetDir(): string | null {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  const rel = join("assets", "vector-cortex", "encoder-v1");
+  for (let i = 0; i < 8; i++) {
+    const candidate = join(dir, rel);
+    try {
+      // guardrails-allow PREVENT-PI-004: local asset filesystem read (loopback)
+      readFileSync(join(candidate, "manifest.json"));
+      return candidate;
+    } catch {
+      /* keep walking */
+    }
+    const next = dirname(dir);
+    if (next === dir) break;
+    dir = next;
+  }
+  return null;
+}
+
+/** Reader-only encoder health facts: mode + asset digest (+ vertex/verdict). */
+interface SetupCortexFacts {
+  mode: "A" | "B" | "C";
+  assetDigestPrefix: string | null;
+  verdict: "qualified" | "demoted" | "unavailable";
+  thresholdFailures: string[];
+}
+
+interface SetupCortexFactCache {
+  key: string;
+  facts: SetupCortexFacts;
+}
+
+let factCache: SetupCortexFactCache | null = null;
+
+/** Stable cache key: manifest bytes + (size,mtime) of the asset files + platform. */
+function factCacheKey(dir: string, manifestPath: string): string | null {
+  const platform = detectPlatform();
+  if (!platform) return null;
+  const parts: string[] = [platform];
+  try {
+    for (const p of [manifestPath, join(dir, "model.onnx"), join(dir, "tokenizer.json")]) {
+      const s = statSync(p);
+      parts.push(`${s.size}:${s.mtimeMs}`);
+    }
+    // guardrails-allow PREVENT-PI-004: local manifest filesystem read (loopback)
+    parts.push(createHash("sha256").update(readFileSync(manifestPath)).digest("hex"));
+  } catch {
+    return null;
+  }
+  return parts.join("|");
+}
+
+function computeSetupCortexFacts(dir: string): SetupCortexFacts | null {
+  const manifest = readEncoderManifest(dir);
+  if (manifest === null) {
+    return { mode: "C", assetDigestPrefix: null, verdict: "unavailable", thresholdFailures: [] };
+  }
+  const manifestPath = join(dir, "manifest.json");
+  const key = factCacheKey(dir, manifestPath);
+  if (key === null) return null;
+  if (factCache !== null && factCache.key === key) return factCache.facts;
+  let digest: string;
+  try {
+    // guardrails-allow PREVENT-PI-004: local manifest filesystem read (loopback)
+    digest = createHash("sha256").update(readFileSync(manifestPath)).digest("hex");
+  } catch {
+    const facts: SetupCortexFacts = { mode: "B", assetDigestPrefix: null, verdict: "demoted", thresholdFailures: ["ENC_ASSET_UNREADABLE"] };
+    factCache = { key, facts };
+    return facts;
+  }
+  const verify = verifyEncoderAsset(dir, manifest, detectPlatform());
+  const prefix = digest.slice(0, 12);
+  const facts: SetupCortexFacts = verify.ok
+    ? { mode: "A", assetDigestPrefix: prefix, verdict: "qualified", thresholdFailures: [] }
+    : { mode: "B", assetDigestPrefix: prefix, verdict: "demoted", thresholdFailures: [verify.code] };
+  factCache = { key, facts };
+  return facts;
+}
+
+function setupCortexFacts(): SetupCortexFacts {
+  const dir = encoderAssetDir();
+  if (dir === null) {
+    return { mode: "C", assetDigestPrefix: null, verdict: "unavailable", thresholdFailures: [] };
+  }
+  const facts = computeSetupCortexFacts(dir);
+  return facts ?? { mode: "C", assetDigestPrefix: null, verdict: "unavailable", thresholdFailures: [] };
+}
+
+/**
+ * Reader-only GET /api/setup-cortex-status (VC9A).
+ *
+ * Purely read: no mutation, never payloads/prompts/ledger. Flag-off returns the
+ * byte-identical VC8C-era shape `{enabled:false, mode:"C", status:"off"}` with
+ * the encoder-health mode C and no qualification/blocker detail leaked.
+ */
+export function handleSetupCortexStatus(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  if (url !== "/api/setup-cortex-status") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC9A_ENABLED();
+  const facts = enabled ? setupCortexFacts() : null;
+  const blocks: BlockerV1[] = enabled ? [...SETUP_CORTEX_BLOCKERS] : [];
+
+  const body: SetupCortexStatusResponse = {
+    enabled,
+    flag: "MEGACOMPACT_VC9A",
+    mode: facts ? facts.mode : "C",
+    assetDigestPrefix: facts ? facts.assetDigestPrefix : null,
+    qualification: facts
+      ? { verdict: facts.verdict, thresholdFailures: facts.thresholdFailures }
+      : { verdict: "unavailable", thresholdFailures: [] },
+    blockers: blocks,
+    encoderHealth: facts
+      ? { assetDigestPrefix: facts.assetDigestPrefix, mode: facts.mode }
+      : { assetDigestPrefix: null, mode: "C" },
+    updatedAt: new Date().toISOString(),
+    status: deriveVcStatus({ enabled, hasData: !!facts && facts.verdict !== "unavailable", structuralOnly: true }),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

package/extensions/dashboard-server/routes.ts

@@ -56,3 +56,4 @@ export {
 	handleVectorCortexClosureProof,
 	handleVectorCortexRestore,
 } from "./routes-vector-cortex.js";
+export { handleSetupCortexStatus } from "./routes-setup-cortex.js";

package/extensions/dashboard-server/setup-cortex-blockers.ts

@@ -0,0 +1,73 @@
+/**
+ * dashboard-server/setup-cortex-blockers.ts — canonical blocker manifest for the
+ * dashboard Setup Cortex status read path (VC9A).
+ *
+ * The hard-gate items enumerated in docs/vector-cortex/vc2-model-prep.md §6
+ * (per the 2026-08-05 research update: the opset-14→17 re-export blocker is
+ * REMOVED because onnx-community exports are now opset 21). This module is the
+ * SINGLE canonical source of those blockers — the route file
+ * (routes-setup-cortex.ts) carries NO string literals for them; it reads this
+ * static manifest so the UI rows and the spec stay in one place.
+ *
+ * Reader-only, static: zero network, no writes (PREVENT-PI-004), no `any`
+ * (PREVENT-011).
+ */
+
+/** The open hard-gate items VC9A surfaces (nothing is closed in-workstream). */
+export interface SetupCortexBlockerV1 {
+  /** Stable machine id (e.g. HG-1) the client can key rows on. */
+  readonly id: string;
+  /** Human title shown on the blockers card. */
+  readonly title: string;
+  /** Severity: blocker | high | medium. */
+  readonly severity: "blocker" | "high" | "medium";
+  /** Lifecycle state — all OPEN (hard gates are never silently closed). */
+  readonly status: "open";
+  /** Optional candidate resolution surfaced for the controller / user. */
+  readonly resolution?: string;
+}
+
+/**
+ * The four blockers VC9A reports. Enumerates the vc2-model-prep §6 items that
+ * remain per the 2026-08-05 research. The opset re-export blocker (formerly
+ * §6 #2) is NOT listed: onnx-community exports are opset 21, so it is removed.
+ */
+export const SETUP_CORTEX_BLOCKERS: readonly SetupCortexBlockerV1[] = [
+  {
+    id: "HG-1",
+    title: "Five projection heads do not exist",
+    severity: "blocker",
+    status: "open",
+    resolution:
+      "Supervision transfer onto a frozen bge-small-en-v1.5 trunk (contradiction distilled from cross-encoder/nli-deberta-v3-small; dependency NLI-assisted; cache-stability deterministic; payload-routing small MLP) — VC2B training + export.",
+  },
+  {
+    id: "HG-3",
+    title: "onnxruntime-node install exceeds the 80 MiB asset budget",
+    severity: "blocker",
+    status: "open",
+    resolution:
+      "onnxruntime-node bundles ~258 MiB across all platforms. Candidate: transformers.js v4.2.0 (9.5 MiB shell, pure-Node via onnxruntime-web WASM) measured against budget + p95 gate before committing.",
+  },
+  {
+    id: "HG-4",
+    title: "No darwin-x64 binary in onnxruntime-node",
+    severity: "high",
+    status: "open",
+    resolution:
+      "Intel-Mac mode-A users demote to the WASM path (if HG-3 resolves that way) or mode B.",
+  },
+  {
+    id: "HG-5",
+    title: "RSS margin at 512 tokens is ~0.5%",
+    severity: "medium",
+    status: "open",
+    resolution:
+      "149.2 MiB vs 150 MiB cap with run-to-run variance 119-149 MiB; considers capping mode A at 384 tokens or using the marginal-footprint accounting runtime.ts already implements.",
+  },
+];
+
+/** Look up one blocker by id; undefined when unknown (defensive). */
+export function setupCortexBlocker(id: string): SetupCortexBlockerV1 | undefined {
+  return SETUP_CORTEX_BLOCKERS.find((b) => b.id === id);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.26",
+  "version": "0.20.27",
   "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-vc9a.ts

@@ -0,0 +1,31 @@
+/**
+ * config/vector-cortex-vc9a.ts — VC9A setup-cortex status-read-path sprint flag.
+ *
+ * Extracted from vector-cortex.ts so that file stays under the 300-line soft
+ * limit (soft-as-hard gate), exactly as vector-cortex-vc8c.ts,
+ * vector-cortex-breakers.ts and vector-cortex-early.ts were. This is the
+ * SETUP-DASHBOARD reader flag (the dashboard Setup tab cortex status endpoint).
+ * vector-cortex.ts re-exports it below and root src/config.ts re-exports it, so
+ * no consumer import path changes.
+ *
+ * The split is purely mechanical: VC9A_ENABLED is byte-identical in name,
+ * semantics, and default to the definition it replaces, and vector-cortex.ts
+ * re-exports it so every existing `from "./config/vector-cortex.js"` import
+ * keeps resolving unchanged.
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { sprintFlag } from "./vector-cortex-flag.js";
+
+/**
+ * VC9A — Setup Cortex status read path (GET /api/setup-cortex-status).
+ * Default ON. `MEGACOMPACT_VC9A=0` disables and is byte-identical to the
+ * predecessor (VC8C-era shape): the endpoint returns `{enabled:false,
+ * mode:"C", status:"off"}` and surfaces no qualification/blocker/health detail —
+ * a pure reader-only projection, never a mutation. This flag MUST also be a
+ * dashboard SETTINGS toggle (visible in config UI, never in EXCLUDED_SETTINGS),
+ * mirroring VC4A..VC8C. The dashboard reader itself performs only local
+ * filesystem reads (no network, PREVENT-PI-004).
+ */
+export const VC9A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC9A");

package/src/config/vector-cortex.ts

@@ -275,6 +275,11 @@ export const VC8B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC8B");
 // import keeps resolving unchanged.
 export { VC8C_ENABLED } from "./vector-cortex-vc8c.js";
 
+// VC9A (setup-cortex status read path) extracted to vector-cortex-vc9a.ts to
+// keep this file under the 300-line soft limit. Re-exported here so every
+// existing `from "./config/vector-cortex.js"` import keeps resolving unchanged.
+export { VC9A_ENABLED } from "./vector-cortex-vc9a.js";
+
 // 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

@@ -178,6 +178,7 @@ export {
   VC8A_ENABLED,
   VC8B_ENABLED,
   VC8C_ENABLED,
+  VC9A_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,