pi-mega-compact 0.18.1 → 0.19.1

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

@@ -12,10 +12,12 @@ import {
 	fetchVectorCortexEvaluation,
 	fetchVectorCortexHealth,
 	fetchVectorCortexLedger,
+	fetchVectorCortexTopology,
 	resetVectorCortexBreaker,
 	type VectorCortexEvaluationSummary,
 	type VectorCortexHealthCard,
 	type VectorCortexLedgerView,
+	type VectorCortexTopologyView,
 } from "../api/vector-cortex";
 import { Card, CardContent, CardHeader, CardTitle } from "../components/ui/card";
 import { Badge } from "../components/ui/badge";
@@ -45,6 +47,7 @@ export default function VectorCortexTab(): React.ReactElement {
 	const [health, setHealth] = useState<VectorCortexHealthCard | null>(null);
 	const [resetMsg, setResetMsg] = useState<string | null>(null);
 	const [ledger, setLedger] = useState<VectorCortexLedgerView | null>(null);
+	const [topology, setTopology] = useState<VectorCortexTopologyView | null>(null);
 
 	const poll = useCallback(() => {
 		fetchVectorCortexEvaluation()
@@ -59,6 +62,9 @@ export default function VectorCortexTab(): React.ReactElement {
 		fetchVectorCortexLedger().then(setLedger).catch(() => {
 			/* ledger card is best-effort (VC1B) */
 		});
+		fetchVectorCortexTopology().then(setTopology).catch(() => {
+			/* topology card is best-effort (VC3A) */
+		});
 	}, []);
 
 	useEffect(() => {
@@ -203,6 +209,36 @@ export default function VectorCortexTab(): React.ReactElement {
 								}
 							/>
 							<Metric label="Spool lag" value={String(health.spoolLag)} />
+								<Metric label="Encoder mode" value={health.encoderMode} />
+								<Metric label="Encoder asset" value={health.encoderAssetDigest ? health.encoderAssetDigest.slice(0, 12) : "none"} />
+						</div>
+					)}
+				</CardContent>
+			</Card>
+			<Card>
+				<CardHeader>
+					<div className="flex items-center justify-between">
+						<CardTitle>Derived Cortex Store (VC3A)</CardTitle>
+						{topology?.enabled ? (
+							<Badge variant="success">ACTIVE</Badge>
+						) : (
+							<Badge variant="danger">OFF</Badge>
+						)}
+					</div>
+				</CardHeader>
+				<CardContent>
+					{!topology?.enabled ? (
+						<div className="vc-empty">Cortex store disabled (VC3A off).</div>
+					) : (
+						<div className="grid grid-cols-2 gap-4 md:grid-cols-3">
+							<Metric label="Generation" value={topology.generationId ?? "—"} />
+							<Metric label="Ordinal" value={topology.ordinal ?? "—"} />
+							<Metric label="Records" value={String(topology.recordCount)} />
+							<Metric label="Frontier (HW)" value={topology.sourceHighWater} />
+							<Metric
+								label="Root digest"
+								value={topology.rootDigest ? topology.rootDigest.slice(0, 16) : "—"}
+							/>
 						</div>
 					)}
 				</CardContent>

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

@@ -50,6 +50,17 @@ export interface VectorCortexHealthCard {
   aggregate: string;
   /** "ephemeral" = per-process/in-memory breaker (non-live until VC0D). */
   stateSource: "ephemeral" | "live";
+  /**
+   * VC2C encoder asset digest — SHA-256 of the committed ModelManifestV1 bytes.
+   * null when no qualified encoder manifest is present on this host.
+   */
+  encoderAssetDigest: string | null;
+  /**
+   * VC2C encoder triad mode: "A" when the committed asset verifies as a
+   * qualified learned asset on this host/platform, else "B" (trigram) or "C"
+   * (lexical).
+   */
+  encoderMode: "A" | "B" | "C";
 }
 
 /** Admin reset result (VC0C, task 5). */
@@ -64,6 +75,21 @@ export interface VectorCortexResetResult {
   updatedAt: string;
 }
 
+/**
+ * Reader-only cortex topology view (VC3A, GET /api/vector-cortex/topology).
+ * Aggregate only — active generation identity, one root digest, derived frontier
+ * and record count. Never append/rebuild capability or raw record payloads.
+ */
+export interface VectorCortexTopologyView {
+  enabled: boolean;
+  generationId: string | null;
+  rootDigest: string | null;
+  sourceHighWater: string;
+  recordCount: number;
+  ordinal: string | null;
+  updatedAt: string;
+}
+
 /**
  * Occurrence-ledger identity view (VC1B, GET /api/vector-cortex/ledger).
  * Reader-only: seq/eventId/kind/digest + high-water, never source payloads.

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

@@ -90,6 +90,17 @@ export interface VectorCortexHealthCard {
    * only once the persistent breaker runtime + producer wiring land (VC0D).
    */
   readonly stateSource: "ephemeral" | "live";
+  /**
+   * VC2C encoder asset digest — SHA-256 of the committed ModelManifestV1 bytes.
+   * null when no qualified encoder manifest is present on this host.
+   */
+  readonly encoderAssetDigest: string | null;
+  /**
+   * VC2C encoder triad mode: "A" when the committed asset verifies as a
+   * qualified learned asset on this host/platform, else "B" (trigram) or "C"
+   * (lexical). Reader-only aggregate — the measured digest prefix, never bytes.
+   */
+  readonly encoderMode: "A" | "B" | "C";
 }
 
 /**
@@ -108,6 +119,29 @@ export interface VectorCortexResetResult {
   readonly updatedAt: string;
 }
 
+/**
+ * Reader-only cortex topology view for GET /api/vector-cortex/topology (VC3A).
+ * Built on the CortexReader capability surface ONLY — it exposes the flagged
+ * enabled state, active generation identity, one root digest, derived frontier
+ * and record count, and NEVER append/rebuild capability or raw record payloads.
+ */
+export interface VectorCortexTopologyView {
+  /** Whether the VC3A cortex-store flag is enabled in this process. */
+  readonly enabled: boolean;
+  /** Active generation id, or null when none rebuilt yet. */
+  readonly generationId: string | null;
+  /** Active generation root digest, or null. */
+  readonly rootDigest: string | null;
+  /** Derived frontier (active generation sourceHighWater, else "0"). */
+  readonly sourceHighWater: string;
+  /** Accepted derived record count. */
+  readonly recordCount: number;
+  /** Monotonic rebuild ordinal, or null. */
+  readonly ordinal: string | null;
+  /** 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

@@ -325,6 +325,18 @@ export const SETTINGS: ReadonlyArray<{
 				"VectorSetV1 five L2-normalized heads (384/128/128/64/32) with head-calibration draft + asset-free trigram B (512d) and lexical C fallbacks, plus the per-head emit seam. OFF = mode C, no per-head vectors emitted, byte-identical predecessor.",
 				true,
 			),
+			boolDirect(
+				"MEGACOMPACT_VC2C",
+				"VC2C Encoder Qualification + Calibration",
+				"QualifiedEncoderV1/CalibrationV1: calibration fit on the calibration split only (held-out labels prohibited) + atomic selection across MODEL_ASSET and per-head EVALUATION thresholds (any field failure demotes all of A). OFF = mode C, no qualification/calibration selection, byte-identical predecessor.",
+				true,
+			),
+			boolDirect(
+				"MEGACOMPACT_VC3A",
+				"VC3A Cortex Store",
+				"Capability-gated derived cortex store (CortexReader/Writer/Admin + CortexRecordV1): additive, keyed (sourceHighWater, algorithmVersion, id), immutable records, deterministic generation rebuild + one root digest. OFF = mode C, no cortex records written, byte-identical predecessor.",
+				true,
+			),
 		],
 	},
 	{

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

@@ -0,0 +1,59 @@
+/**
+ * dashboard-server/routes-vector-cortex-eval.ts — VC0A vector-cortex evaluation
+ * dashboard route.
+ *
+ * A single reader-only GET /api/vector-cortex/evaluation that aggregates redacted
+ * evaluation rows (persisted JSONL under the state dir) via the reader. No
+ * writable capability — no reset/mutation here.
+ *
+ * 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 type { RouteContext } from "./routes-core.js";
+import { VC0A_ENABLED } from "../../src/config.js";
+import { readEvalRows } from "../../src/vector-cortex/eval/persist.js";
+import { summarizeEvalRows } from "../../src/vector-cortex/eval/reader.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import type { VectorCortexEvaluationSummary } from "./api-contracts/vector-cortex.js";
+
+/** Reader-only aggregate GET /api/vector-cortex/evaluation. */
+export function handleVectorCortexEvaluation(
+  req: IncomingMessage,
+  res: ServerResponse,
+  ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  if (url !== "/api/vector-cortex/evaluation") return false;
+  if (req.method !== "GET") {
+    // Reader-only: no mutation endpoints exist on this path.
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC0A_ENABLED();
+  const rows = enabled ? readEvalRows(ctx.stateDir) : [];
+  const summary = summarizeEvalRows(rows);
+
+  const body: VectorCortexEvaluationSummary = {
+    enabled,
+    mode: enabled ? "A" : "C",
+    samples: summary.samples,
+    byMode: {
+      A: summary.byMode.A,
+      B: summary.byMode.B,
+      C: summary.byMode.C,
+    },
+    histogram: {
+      edges: [...summary.histogram.edges],
+      cells: [...summary.histogram.cells],
+      overflow: summary.histogram.overflow,
+      total: summary.histogram.total,
+    },
+    rejects: [], // VC0C wires live breaker/reject telemetry here
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

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

@@ -0,0 +1,273 @@
+/**
+ * dashboard-server/routes-vector-cortex-health.ts — VC0C vector-cortex breaker
+ * health + reset routes (plus the VC2C encoder-health facts they surface).
+ *
+ *   GET  /api/vector-cortex/health          — reader-only aggregate health card
+ *   POST /api/vector-cortex/breakers/reset  — explicit admin capability
+ *
+ * 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 { VC0C_ENABLED, VC2C_ENABLED } from "../../src/config.js";
+import { createVectorCortexSafety } from "../mega-runtime/vector-cortex-safety.js";
+import { readEncoderManifest, verifyEncoderAsset, detectPlatform } from "../../src/vector-cortex/encoder/asset.js";
+import { sendJson, readJsonBody } from "./routes-vector-cortex-shared.js";
+import type {
+  VectorCortexHealthCard,
+  VectorCortexResetResult,
+} from "./api-contracts/vector-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;
+}
+
+/**
+ * VC2C encoder health facts (task 5): the SHA-256 of the committed qualified
+ * manifest (asset digest) and the encoder triad mode. Reader-only aggregate
+ * (digest prefix, no bytes). Gated on MEGACOMPACT_VC2C: when the flag is OFF
+ * (rollback), the card reports mode C with an absent digest — consistent with
+ * the rest of the card, whose enabled/mode fields reflect active (flag-gated)
+ * state. When ON: "A" when the committed asset verifies on this host, "B" when
+ * present but not verified (demotion), "C" when absent.
+ *
+ * The verification hashes the full ONNX + tokenizer bytes, which is expensive
+ * on a periodically-polled endpoint as the shipped asset grows. The result is
+ * memoized against a cheap key (manifest bytes + file sizes/mtimes + platform);
+ * any on-disk mutation invalidates the key, so the cache never goes stale while
+ * avoiding the repeated large-file hashing. A failed digest read returns null
+ * (an absent digest), never a misleading zero-sentinel.
+ */
+type EncoderHealthFacts = { assetDigest: string | null; mode: "A" | "B" | "C" };
+
+interface HealthFactCache {
+  key: string;
+  facts: EncoderHealthFacts;
+}
+
+let healthCache: HealthFactCache | null = null;
+
+/** Stable cache key: manifest bytes + (size,mtime) of the asset files + platform. */
+function healthFactCacheKey(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 computeEncoderHealthFacts(dir: string): EncoderHealthFacts | null {
+  const manifest = readEncoderManifest(dir);
+  if (manifest === null) return { assetDigest: null, mode: "C" };
+  const manifestPath = join(dir, "manifest.json");
+  const key = healthFactCacheKey(dir, manifestPath);
+  if (key === null) return null;
+  if (healthCache !== null && healthCache.key === key) return healthCache.facts;
+  let digest: string;
+  try {
+    // guardrails-allow PREVENT-PI-004: local manifest filesystem read (loopback)
+    digest = createHash("sha256").update(readFileSync(manifestPath)).digest("hex");
+  } catch {
+    return { assetDigest: null, mode: "B" };
+  }
+  const verify = verifyEncoderAsset(dir, manifest, detectPlatform());
+  const facts: EncoderHealthFacts = { assetDigest: digest, mode: verify.ok ? "A" : "B" };
+  healthCache = { key, facts };
+  return facts;
+}
+
+function encoderHealthFacts(): EncoderHealthFacts {
+  if (!VC2C_ENABLED()) {
+    // Rollback: MEGACOMPACT_VC2C=0 selects C — report the inactive (flag-gated)
+    // mode with no asset digest rather than an on-disk-computed A/B.
+    return { assetDigest: null, mode: "C" };
+  }
+  const dir = encoderAssetDir();
+  if (dir === null) return { assetDigest: null, mode: "C" };
+  const facts = computeEncoderHealthFacts(dir);
+  if (facts === null) return { assetDigest: null, mode: "C" };
+  return facts;
+}
+
+/**
+ * Reader-only GET /api/vector-cortex/health (VC0C).
+ *
+ * Aggregate health card: breaker state (window/probe/backoff), durable spool
+ * frontier/authority/lag, and a worst-state aggregate. Constructs the safety
+ * adapter over the state dir — durable spool state (frontier-frozen, lag) is
+ * read from disk, so it reflects restart. Purely read: no mutation, never
+ * payloads/prompts/ledger.
+ */
+export function handleVectorCortexHealth(
+  req: IncomingMessage,
+  res: ServerResponse,
+  ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  if (url !== "/api/vector-cortex/health") return false;
+  if (req.method !== "GET") {
+    // Reader-only path: no mutation endpoint lives at /health.
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC0C_ENABLED();
+  const safety = enabled ? createVectorCortexSafety({ stateDir: ctx.stateDir }) : null;
+  const card = safety ? safety.health() : null;
+
+  const enc = encoderHealthFacts();
+
+  const fallback: VectorCortexHealthCard = {
+    enabled: false,
+    mode: "C",
+    state: "CLOSED_A",
+    subsystem: "provider",
+    sinceMs: 0,
+    windowMs: 0,
+    probeCount: 0,
+    backoffDelayMs: 0,
+    frontierFrozen: false,
+    authorityOutage: false,
+    spoolLag: 0,
+    attempts: 0,
+    failures: 0,
+    p95Ms: 0,
+    failureRate: 0,
+    updatedAt: new Date().toISOString(),
+    aggregate: "CLOSED_A",
+    stateSource: "ephemeral",
+    encoderAssetDigest: enc.assetDigest,
+    encoderMode: enc.mode,
+  };
+  if (!card) {
+    sendJson(res, 200, fallback);
+    return true;
+  }
+
+  const mode: "A" | "B" | "C" =
+    card.state === "CLOSED_A" ? "A" : card.state === "MANUAL_HALT" ? "C" : "B";
+  const aggregate =
+    card.state === "MANUAL_HALT"
+      ? "MANUAL_HALT"
+      : card.state === "OPEN_C"
+        ? "OPEN_C"
+        : card.state === "OPEN_B"
+          ? "OPEN_B"
+          : card.state === "PROBE_B" || card.state === "PROBE_A"
+            ? "PROBE"
+            : "CLOSED_A";
+
+  const body: VectorCortexHealthCard = {
+    enabled,
+    mode,
+    state: card.state,
+    subsystem: card.subsystem,
+    sinceMs: card.sinceMs,
+    reason: card.reason,
+    windowMs: card.windowMs,
+    probeCount: card.probeCount,
+    backoffDelayMs: card.backoffDelayMs,
+    frontierFrozen: card.frontierFrozen,
+    authorityOutage: card.authorityOutage,
+    spoolLag: card.spoolLag,
+    attempts: card.attempts,
+    failures: card.failures,
+    p95Ms: card.p95Ms,
+    failureRate: card.failureRate,
+    updatedAt: new Date().toISOString(),
+    aggregate,
+    stateSource: card.stateSource,
+    encoderAssetDigest: enc.assetDigest,
+    encoderMode: enc.mode,
+  };
+  sendJson(res, 200, body);
+  return true;
+}
+
+/**
+ * Admin POST /api/vector-cortex/breakers/reset (VC0C).
+ *
+ * Explicit admin capability (separate from the reader GET). Clears a breaker's
+ * cooldown — or unwires a MANUAL_HALT — but NEVER evidence (attempts/failures
+ * are retained, per TRIAD_RESILIENCE). The subsystem is actor-supplied via the
+ * JSON body `{ subsystem }`. Every reset is documented in the returned record
+ * (state, retained evidence, updatedAt) — an auditable mutation surface; the
+ * GET path can never mutate.
+ */
+export function handleVectorCortexBreakersReset(
+  req: IncomingMessage,
+  res: ServerResponse,
+  ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  if (url !== "/api/vector-cortex/breakers/reset") return false;
+  if (req.method !== "POST") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+  if (!VC0C_ENABLED()) {
+    sendJson(res, 409, { error: "vco_c_disabled" });
+    return true;
+  }
+
+  readJsonBody(req, (parsed) => {
+    if (!parsed.ok) {
+      sendJson(res, 400, { error: parsed.error });
+      return;
+    }
+    const subsystem = parsed.value.subsystem;
+    if (typeof subsystem !== "string" || subsystem.length === 0) {
+      sendJson(res, 400, { error: "subsystem_required" });
+      return;
+    }
+    try {
+      const safety = createVectorCortexSafety({ stateDir: ctx.stateDir });
+      const rec = safety.reset(subsystem);
+      const body: VectorCortexResetResult = {
+        subsystem: rec.subsystem,
+        state: rec.state,
+        cooldownCleared: true,
+        attempts: rec.attempts,
+        failures: rec.failures,
+        probeCount: rec.probeCount,
+        manualReason: rec.manualReason,
+        updatedAt: rec.updatedAt,
+      };
+      sendJson(res, 200, body);
+    } catch {
+      sendJson(res, 500, { error: "reset_failed" });
+    }
+  });
+  return true;
+}

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

@@ -0,0 +1,92 @@
+/**
+ * dashboard-server/routes-vector-cortex-ledger.ts — VC1B vector-cortex ledger
+ * dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/ledger built on the LedgerReader capability:
+ * opens the occurrence-v2 ledger for this repo's state dir and returns the
+ * session's occurrence IDENTITY rows (seq/eventId/kind/digest/toolCallId) plus
+ * high-water/count. NEVER ships sourceBytes or prompt text (reader-only
+ * no-ledger-text rule). Optional `?session=<id>` query selects the session.
+ *
+ * Guardrails: PREVENT-PI-004 (local filesystem read only), PREVENT-011 (no
+ * `any`), reader-only aggregate/identity only.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import { VC1B_ENABLED } from "../../src/config.js";
+import { createLedgerStore } from "../../src/vector-cortex/ledger/store.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import type { VectorCortexLedgerView } from "./api-contracts/vector-cortex.js";
+
+/**
+ * Reader-only GET /api/vector-cortex/ledger (VC1B).
+ */
+export function handleVectorCortexLedger(
+  req: IncomingMessage,
+  res: ServerResponse,
+  ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+  if (path !== "/api/vector-cortex/ledger") return false;
+  if (req.method !== "GET") {
+    // Reader-only path: no mutation endpoint lives at /ledger.
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  // Parse the optional session query parameter.
+  let session = "default";
+  const qs = url.split("?")[1];
+  if (qs !== undefined) {
+    for (const pair of qs.split("&")) {
+      const [k, v] = pair.split("=");
+      if (k === "session" && v !== undefined && v.length > 0) {
+        session = decodeURIComponent(v);
+      }
+    }
+  }
+
+  const enabled = VC1B_ENABLED();
+  let active = enabled;
+  let highWater = "0";
+  let count = 0;
+  let occurrences: VectorCortexLedgerView["occurrences"] = [];
+
+  if (enabled) {
+    try {
+      const store = createLedgerStore({ stateDir: ctx.stateDir });
+      try {
+        const reader = store.reader();
+        highWater = reader.highWater(session).toString();
+        const rows = reader.readSession(session);
+        count = rows.length;
+        // Identity only: never sourceBytes or prompt text (reader-only rule).
+        occurrences = rows.slice(-500).map((occ) => ({
+          seq: occ.seq.toString(),
+          eventId: occ.eventId,
+          kind: occ.kind,
+          digest: occ.digest,
+          ...(occ.toolCallId !== undefined ? { toolCallId: occ.toolCallId } : {}),
+        }));
+      } finally {
+        store.close();
+      }
+    } catch {
+      // Non-fatal: a missing/corrupt ledger DB degrades to `enabled:false`.
+      active = false;
+    }
+  }
+
+  const body: VectorCortexLedgerView = {
+    enabled: active,
+    session,
+    highWater,
+    count,
+    occurrences,
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

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

@@ -0,0 +1,53 @@
+/**
+ * dashboard-server/routes-vector-cortex-shared.ts — shared HTTP helpers for the
+ * per-feature vector-cortex route modules.
+ *
+ * Homes the small request/response helpers used across the VC0A/VC0C/VC1B/VC3A
+ * handler modules (`sendJson`, `readJsonBody`) so the feature modules stay small
+ * and within extension line limits.
+ *
+ * Guardrails: PREVENT-PI-004 (loopback dashboard response only), PREVENT-011 (no
+ * `any`), PREVENT-001 (JSON.parse guarded by an object/shape check).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+export function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+
+/**
+ * Parse a JSON request body with a size cap. `cb` receives either a validated
+ * plain object or an error reason. PREVENT-001: JSON.parse is guarded by a
+ * shape check (rejects null / arrays / non-objects).
+ */
+export function readJsonBody(
+  req: IncomingMessage,
+  cb: (
+    result: { ok: true; value: Record<string, unknown> } | { ok: false; error: string },
+  ) => void,
+): void {
+  let body = "";
+  let tooBig = false;
+  req.on("data", (chunk: Buffer) => {
+    if (body.length > 65536) {
+      tooBig = true;
+      return;
+    }
+    body += chunk.toString();
+  });
+  req.on("end", () => {
+    if (tooBig) return cb({ ok: false, error: "body_too_large" });
+    try {
+      const v = body ? JSON.parse(body) : {};
+      if (typeof v !== "object" || v === null || Array.isArray(v)) {
+        return cb({ ok: false, error: "invalid_object" });
+      }
+      cb({ ok: true, value: v as Record<string, unknown> });
+    } catch {
+      cb({ ok: false, error: "invalid_json" });
+    }
+  });
+}