pi-mega-compact 0.20.26 → 0.20.28

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

@@ -0,0 +1,64 @@
+/**
+ * useSetupCortexPoll — polls the VC9A setup-cortex status endpoint (a sibling
+ * of useVectorCortexPoll, URL + payload differ only). Each fetch is
+ * best-effort: a failure sets the error slice and leaves data as-is. The
+ * Cortex sub-tab uses the returned payload to render the encoder card + the
+ * status badge, and SetupTab uses it to filter the sub-tab when the status
+ * reports the off/disabled shape.
+ */
+import { useState, useEffect, useCallback } from "react";
+import { fetchSetupCortexStatus } from "../api/setup-cortex";
+import type { SetupCortexStatusResponse } from "../types/setup-cortex";
+
+export interface SetupCortexPollState {
+	loading: boolean;
+	error: string | null;
+	data: SetupCortexStatusResponse | null;
+}
+
+/**
+ * Whether the Cortex sub-tab should be listed in SUB_TABS.
+ *
+ * The sub-tab is hidden (filtered from SUB_TABS) when the VC9A status payload
+ * reports the off/disabled shape — either the flag is off (`enabled:false`) or
+ * the derived status is "off" — exactly the VC0E honest-status gating the
+ * sibling VC cards use. While the payload is still loading/absent we default to
+ * visible so a transient poll isn't mistaken for the off state.
+ */
+export function isCortexSubTabVisible(
+	data: SetupCortexStatusResponse | null,
+): boolean {
+	if (data === null) return true;
+	return data.enabled && data.status !== "off";
+}
+
+export function useSetupCortexPoll(): [SetupCortexPollState, () => void] {
+	const [state, setState] = useState<SetupCortexPollState>({
+		loading: true,
+		error: null,
+		data: null,
+	});
+
+	const poll = useCallback(() => {
+		setState((prev) => ({ ...prev, loading: true }));
+		fetchSetupCortexStatus()
+			.then((data) =>
+				setState((prev) => ({ ...prev, data, loading: false, error: null })),
+			)
+			.catch((e: unknown) =>
+				setState((prev) => ({
+					...prev,
+					loading: false,
+					error: e instanceof Error ? e.message : String(e),
+				})),
+			);
+	}, []);
+
+	useEffect(() => {
+		poll();
+		const id = setInterval(poll, 5000);
+		return () => clearInterval(id);
+	}, [poll]);
+
+	return [state, poll];
+}

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

@@ -0,0 +1,118 @@
+/**
+ * dashboard-client/src/types/setup-cortex.ts — Setup Cortex client types.
+ *
+ * Client-side mirrors of the server contract (extensions/dashboard-server/
+ * api-contracts/setup-cortex.ts), kept in lockstep so the SetupTab Cortex
+ * sub-tab is fully typed end-to-end. The client bundle does not import the
+ * server tree, so these are redeclared here (PREVENT-011: no `any`; every type
+ * explicit). Aggregate values only — never payload bytes/prompts/ledger
+ * (EVAL-REDACT-002).
+ */
+
+/** The deriveVcStatus status projected by the VC9A reader endpoint. */
+export type VcStatus = "live" | "awaiting_data" | "deferred" | "structural" | "off";
+
+/** One open hard-gate blocker row surfaced on the blockers card. */
+export interface BlockerV1 {
+  /** Stable machine id keying the row (HG-1, HG-3, ...). */
+  readonly id: string;
+  /** Human title shown on the blockers card. */
+  readonly title: string;
+  /** Severity: blocker | high | medium. */
+  readonly severity: "blocker" | "high" | "medium";
+  /** Lifecycle state — always "open" (hard gates not closed in-workstream). */
+  readonly status: "open";
+  /** Optional candidate resolution surfaced for the user / controller. */
+  readonly resolution?: string;
+}
+
+/** Encoder qualification verdict projected for the reader. */
+export type SetupCortexQualificationVerdict = "qualified" | "demoted" | "unavailable";
+
+/** Reader-only view of the encoder health facts (digest prefix, no bytes). */
+export interface SetupCortexEncoderHealth {
+  /** First 12 hex chars of the committed asset-manifest digest, or null. */
+  readonly assetDigestPrefix: string | null;
+  /** Effective encoder triad mode (A verified / B demoted / C absent). */
+  readonly mode: "A" | "B" | "C";
+}
+
+/** Response for GET /api/setup-cortex-status. */
+export interface SetupCortexStatusResponse {
+  /** Whether the VC9A setup-cortex read path is active (its flag). */
+  readonly enabled: boolean;
+  /** The gating flag name ("MEGACOMPACT_VC9A"). */
+  readonly flag: string;
+  /** Effective encoder triad mode (A verified / B demoted / C absent / off). */
+  readonly mode: "A" | "B" | "C";
+  /** First 12 hex chars of the asset-manifest digest, or null. */
+  readonly assetDigestPrefix: string | null;
+  /** Qualification projection: verdict + any threshold failures surfaced. */
+  readonly qualification: {
+    readonly verdict: SetupCortexQualificationVerdict;
+    readonly thresholdFailures: string[];
+  };
+  /** The open hard-gate blockers (never closed here). */
+  readonly blockers: BlockerV1[];
+  /** Encoder health facts (digest prefix + mode). */
+  readonly encoderHealth: SetupCortexEncoderHealth;
+  /** ISO 8601 read timestamp. */
+  readonly updatedAt: string;
+  /** Shared status derivation (deriveVcStatus). */
+  readonly status: VcStatus;
+}
+
+/** The set of developer actions the Setup Cortex action drivers can run. */
+export type SetupCortexActionKind = "fetch-model" | "bench" | "verify-asset";
+
+/** Request body for POST /api/setup-cortex-action. confirm:true required. */
+export interface SetupCortexActionRequest {
+  readonly action: SetupCortexActionKind;
+  readonly confirm: boolean;
+}
+
+/** Outcome of running one Setup Cortex action. */
+export interface SetupCortexActionResult {
+  readonly action: SetupCortexActionKind;
+  readonly ok: boolean;
+  readonly exitCode: number | null;
+  readonly logPath: string;
+  readonly logName: string;
+  readonly spawned: boolean;
+}
+
+/** Error body used when a hard gate blocks the requested action. */
+export interface SetupCortexActionBlocked {
+  readonly error: "action_blocked_by_open_item";
+  /** The open hard-gate ids (HG-1/HG-3) that gate this action. */
+  readonly blockers: string[];
+}
+
+/** Error body used when confirm:true was not supplied. */
+export interface SetupCortexActionConfirmRequired {
+  readonly error: "confirmation_required";
+}
+
+/** Error body used when the setup-cortex action path is disabled (flag off). */
+export interface SetupCortexActionDisabled {
+  readonly error: "disabled";
+}
+
+/** Union of every non-2xx action error body the route can return. */
+export type SetupCortexActionErrorBody =
+  | SetupCortexActionBlocked
+  | SetupCortexActionConfirmRequired
+  | SetupCortexActionDisabled;
+
+/** Request query for GET /api/setup-cortex-action-log. */
+export interface SetupCortexActionLogQuery {
+  readonly name: string;
+}
+
+/** Response body for GET /api/setup-cortex-action-log (bounded, redacted). */
+export interface SetupCortexActionLogResponse {
+  readonly name: string;
+  readonly tail: string;
+  /** True when the full file fit in the tail (false = truncated to 8 KiB). */
+  readonly complete: boolean;
+}

package/extensions/dashboard-server/api-contracts/endpoints/registry-ext.ts

@@ -16,6 +16,14 @@ import type {
   VectorCortexEvaluationSummary,
   VectorCortexLedgerView,
 } from "../vector-cortex.js";
+import type {
+  SetupCortexStatusResponse,
+  SetupCortexActionRequest,
+  SetupCortexActionResult,
+  SetupCortexActionBlocked,
+  SetupCortexActionLogQuery,
+  SetupCortexActionLogResponse,
+} from "../setup-cortex.js";
 
 /** Additive endpoint entries spread into the ENDPOINTS registry. */
 export const EXTRA_ENDPOINTS = {
@@ -64,4 +72,40 @@ export const EXTRA_ENDPOINTS = {
 		undefined,
 		VectorCortexLedgerView
 	>,
+
+	// ─── VC9A Setup Cortex (dashboard Setup tab cortex status) ─────────
+
+	/** GET /api/setup-cortex-status — reader-only vector-cortex encoder gate. */
+	setupCortexStatus: {
+		method: "GET",
+		path: "/api/setup-cortex-status",
+		description:
+			"Reader-only vector-cortex encoder gate: mode A/B/C, qualification verdict, blockers, encoder health — for the dashboard Setup tab. Never closes the ML gate.",
+	} as const satisfies EndpointDef<"GET", undefined, SetupCortexStatusResponse>,
+
+	// ─── VC9B Setup Cortex actions (dashboard Setup tab action drivers) ─────
+
+	/** POST /api/setup-cortex-action — confirmation-gated fetch/bench/verify. */
+	setupCortexAction: {
+		method: "POST",
+		path: "/api/setup-cortex-action",
+		description:
+			"Confirmation-gated driver: fetch-model / bench / verify-asset. Executes only the committed local scripts (scripts/vc2-model-prep/*) or re-reads the committed encoder assets; an OPEN hard-gate item returns action_blocked_by_open_item and does NOT spawn. Never payload bytes; confirm:true required.",
+	} as const satisfies EndpointDef<
+		"POST",
+		SetupCortexActionRequest,
+		SetupCortexActionResult | SetupCortexActionBlocked
+	>,
+
+	/** GET /api/setup-cortex-action-log — bounded, redacted action log tail. */
+	setupCortexActionLog: {
+		method: "GET",
+		path: "/api/setup-cortex-action-log",
+		description:
+			"Bounded (8 KiB) redacted tail of a VC9B action log under <stateDir>/logs/vc9b/; the name must be a validated basename (path traversal rejected).",
+	} as const satisfies EndpointDef<
+		"GET",
+		SetupCortexActionLogQuery,
+		SetupCortexActionLogResponse
+	>,
 } as const;

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

@@ -0,0 +1,123 @@
+/**
+ * api-contracts/setup-cortex.ts — Setup Cortex status + action API types (VC9A/VC9B).
+ *
+ * Types for GET /api/setup-cortex-status (reader-only aggregate that surfaces
+ * the vector-cortex encoder gate WITHOUT closing the ML gate) and the VC9B
+ * action drivers POST /api/setup-cortex-action + GET /api/setup-cortex-action-log
+ * (confirmation-gated, hard-gate-aware fetches/bench/verify). Reader/actor-only:
+ * never payload bytes/prompts/ledger (EVAL-REDACT-002).
+ *
+ * PREVENT-PI-004: type definitions only, no network code.
+ * PREVENT-011: no `any` type — all types are explicit.
+ */
+
+import type { VcStatus } from "../vc-status.js";
+
+/** One blocker row surfaced on the dashboard Setup Cortex blockers card. */
+export interface BlockerV1 {
+  /** Stable machine id (HG-1, HG-3, ...) keying the row. */
+  readonly id: string;
+  /** Human title shown on the blockers card. */
+  readonly title: string;
+  /** Severity: blocker | high | medium. */
+  readonly severity: "blocker" | "high" | "medium";
+  /** Lifecycle state — always "open" (hard gates not closed in-workstream). */
+  readonly status: "open";
+  /** Optional candidate resolution surfaced for the user / controller. */
+  readonly resolution?: string;
+}
+
+/** The encoder qualification verdict projected for the reader (no calibration run). */
+export type SetupCortexQualificationVerdict = "qualified" | "demoted" | "unavailable";
+
+/** Reader-only view of the encoder health facts (digest prefix, no bytes). */
+export interface SetupCortexEncoderHealth {
+  /** First 12 hex chars of the committed asset-manifest digest, or null. */
+  readonly assetDigestPrefix: string | null;
+  /** Effective encoder triad mode (A verified / B demoted / C absent). */
+  readonly mode: "A" | "B" | "C";
+}
+
+/**
+ * Response for GET /api/setup-cortex-status.
+ */
+export interface SetupCortexStatusResponse {
+  /** Whether the VC9A setup-cortex read path is active (its flag). */
+  readonly enabled: boolean;
+  /** The gating flag name ("MEGACOMPACT_VC9A"). */
+  readonly flag: string;
+  /** Effective encoder triad mode (A verified / B demoted / C absent / off). */
+  readonly mode: "A" | "B" | "C";
+  /** First 12 hex chars of the asset-manifest digest, or null. */
+  readonly assetDigestPrefix: string | null;
+  /** Qualification projection: verdict + any threshold failures surfaced. */
+  readonly qualification: {
+    readonly verdict: SetupCortexQualificationVerdict;
+    readonly thresholdFailures: string[];
+  };
+  /** The open hard-gate blockers (vc2-model-prep §6, never closed here). */
+  readonly blockers: BlockerV1[];
+  /** Encoder health facts (digest prefix + mode). */
+  readonly encoderHealth: SetupCortexEncoderHealth;
+  /** ISO 8601 read timestamp. */
+  readonly updatedAt: string;
+  /** Shared status derivation (deriveVcStatus). */
+  readonly status: VcStatus;
+}
+
+// ─── VC9B action drivers ────────────────────────────────────────────────────
+
+/** The set of developer actions the Setup Cortex action drivers can run. */
+export type SetupCortexActionKind = "fetch-model" | "bench" | "verify-asset";
+
+/**
+ * Request body for POST /api/setup-cortex-action. `confirm:true` is the
+ * server-side hard requirement (mirrors the client ActionDef confirm pattern);
+ * anything else is rejected with confirmation_required.
+ */
+export interface SetupCortexActionRequest {
+  /** Which action to run. */
+  readonly action: SetupCortexActionKind;
+  /** Required explicit confirmation. Absent/false → 400 confirmation_required. */
+  readonly confirm: boolean;
+}
+
+/** Outcome of running one Setup Cortex action. */
+export interface SetupCortexActionResult {
+  readonly action: SetupCortexActionKind;
+  /** True when the subprocess (or asset re-verification) ran to completion. */
+  readonly ok: boolean;
+  /** Exit code of the spawned script, or null for verify-asset / no-spawn. */
+  readonly exitCode: number | null;
+  /** Absolute path of the captured log file under <stateDir>/logs/vc9b/. */
+  readonly logPath: string;
+  /** Relative basename of the log file (the value to pass to the log-tail route). */
+  readonly logName: string;
+  /** True when the subprocess was spawned (verify-asset re-runs asset seams only). */
+  readonly spawned: boolean;
+}
+
+/**
+ * Error body used when a hard gate blocks the requested action: the action is
+ * NOT spawned, and the blocking open hard-gate ids (HG-1/HG-3) are surfaced.
+ */
+export interface SetupCortexActionBlocked {
+  readonly error: "action_blocked_by_open_item";
+  /** The open hard-gate ids (HG-1/HG-3) that gate this action. */
+  readonly blockers: string[];
+}
+
+/** Request query for GET /api/setup-cortex-action-log. */
+export interface SetupCortexActionLogQuery {
+  /** Basename of a log file inside <stateDir>/logs/vc9b/ (traversal rejected). */
+  readonly name: string;
+}
+
+/** Response body for GET /api/setup-cortex-action-log (bounded, redacted). */
+export interface SetupCortexActionLogResponse {
+  readonly name: string;
+  /** Tail of the action log, capped at 8 KiB and redacted. */
+  readonly tail: string;
+  /** True when the full file fit in the tail (false = truncated to 8 KiB). */
+  readonly complete: boolean;
+}

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

@@ -56,6 +56,9 @@ import {
 	handleVectorCortexRollout,
 	handleVectorCortexClosureProof,
 	handleVectorCortexRestore,
+	handleSetupCortexStatus,
+	handleSetupCortexAction,
+	handleSetupCortexActionLog,
 } from "./routes.js";
 // VC6C repair lives in its own module (routes-vector-cortex-repair.ts) so the
 // heal route file stays well under the 400-line extension soft limit.
@@ -146,5 +149,8 @@ export function dispatchRoutes(
 	if (handleVectorCortexOutcomes(req, res, ctx)) return true;
 	if (handleVectorCortexPolicy(req, res, ctx)) return true;
 	if (handleVectorCortexPlatform(req, res, ctx)) return true;
+	if (handleSetupCortexStatus(req, res, ctx)) return true;
+	if (handleSetupCortexAction(req, res, ctx)) return true;
+	if (handleSetupCortexActionLog(req, res, ctx)) return true;
 	return false;
 }

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

@@ -192,5 +192,23 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"Canary selection and external Rust parity. The selector admits a qualified external Rust artifact only when ABI version, URL metadata, commit, Cargo.lock digest, and platform all match evidence; a Cargo.lock digest mismatch rejects the artifact (RUST_CARGO_DIGEST_MISMATCH). The cross-conformance runner exchanges length-framed neutral records over a local stdin/stdout channel — a subprocess, never a URL (PREVENT-PI-004). A parity mismatch selects TS mode B. A qualified external artifact is mode A, TS reference is mode B, legacy path is mode C. OFF = byte-identical predecessor (VC8B); the selector and cross-conformance arithmetic still run, only the reporter + dashboard seam is suppressed.",
 			true,
 		),
+		boolDirect(
+			"MEGACOMPACT_VC9A",
+			"VC9A Setup Cortex Status",
+			"Reader-only Setup Cortex status read path (GET /api/setup-cortex-status): surfaces the vector-cortex encoder gate — mode A/B/C, qualification verdict, open blockers, encoder health — to the dashboard Setup tab without closing the ML gate. OFF = byte-identical predecessor (VC8C-era): returns enabled:false / mode:C / status:off.",
+			true,
+		),
+		boolDirect(
+			"MEGACOMPACT_VC9B",
+			"VC9B Setup Cortex Actions",
+			"Setup Cortex action drivers (POST /api/setup-cortex-action + GET /api/setup-cortex-action-log): confirmation-gated wrappers that fetch-model / bench / verify-asset by spawning only the committed local scripts (scripts/vc2-model-prep/fetch-model.sh, bench-onnx.mjs) or re-reading the committed encoder assets — never payload bytes, no network. Actions gated by an OPEN hard-gate item (HG-1/HG-3) return action_blocked_by_open_item and do NOT spawn. OFF = byte-identical predecessor (VC9A-era): the action POST returns a disabled/404 shape and flag-off bytes are unchanged.",
+			true,
+		),
+		boolDirect(
+			"MEGACOMPACT_VC9C",
+			"VC9C SetupTab Cortex Sub-tab",
+			"SetupTab Cortex sub-tab (client UI): a Cortex sub-tab inside SetupTab that consumes the VC9A status endpoint (GET /api/setup-cortex-status) + the VC9B action endpoints. It surfaces the encoder mode A/B/C, asset digest prefix, qualification verdict + threshold failures, the open hard-gate blockers, and the confirmation-gated fetch/bench/verify actions. OFF = byte-identical predecessor (VC9B-era): the Cortex sub-tab is filtered from SUB_TABS and the Setup tab renders exactly as before.",
+			true,
+		),
 	],
 };

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

@@ -0,0 +1,133 @@
+/**
+ * dashboard-server/routes-setup-cortex-actions.ts — VC9B Setup Cortex action routes.
+ *
+ *   POST /api/setup-cortex-action            — confirmation-gated driver
+ *   GET  /api/setup-cortex-action-log        — bounded, redacted log tail
+ *
+ * Reader/actor-only: NEVER exposes payload bytes, prompts, or ledger. Actions
+ * only spawn the committed local vc2-model-prep scripts or re-read the committed
+ * encoder assets (verify-asset) — no network (PREVENT-PI-004). A hard gate
+ * (HG-1/HG-3) blocking the requested action yields 423 action_blocked_by_open_item
+ * with the blocker ids and NO subprocess is spawned. Missing confirm:true yields
+ * 400 confirmation_required. Flag-off (MEGACOMPACT_VC9B=0) is byte-identical to
+ * the VC9A-era predecessor: the routes are absent, so they return the 404
+ * disabled shape and no action runs.
+ *
+ * Guardrails: PREVENT-011 (no `any`), PREVENT-001 (guarded JSON.parse via
+ * readJsonBody), no string literals for scripts/blockers (delegated to
+ * setup-cortex-actions.ts + setup-cortex-blockers.ts).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import { sendJson, readJsonBody } from "./routes-vector-cortex-shared.js";
+import { VC9B_ENABLED } from "../../src/config.js";
+import { setupCortexActionBlockers } from "./setup-cortex-blockers.js";
+import {
+  runSetupCortexAction,
+  readActionLogTail,
+} from "./setup-cortex-actions.js";
+import type { SetupCortexActionKind } from "./api-contracts/setup-cortex.js";
+
+const ACTION_KINDS = new Set<SetupCortexActionKind>([
+  "fetch-model",
+  "bench",
+  "verify-asset",
+]);
+
+function isActionKind(v: unknown): v is SetupCortexActionKind {
+  return typeof v === "string" && ACTION_KINDS.has(v as SetupCortexActionKind);
+}
+
+/** Flag-off response, byte-identical regardless of request (VC9B absent). */
+function sendDisabled(res: ServerResponse): void {
+  sendJson(res, 404, { error: "disabled" });
+}
+
+/**
+ * POST /api/setup-cortex-action (VC9B). Returns true when it claims the request.
+ */
+export function handleSetupCortexAction(
+  req: IncomingMessage,
+  res: ServerResponse,
+  ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  if (url !== "/api/setup-cortex-action") return false;
+  if (req.method !== "POST") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+  if (!VC9B_ENABLED()) {
+    sendDisabled(res);
+    return true;
+  }
+  readJsonBody(req, (parsed) => {
+    if (!parsed.ok) {
+      sendJson(res, 400, { error: "invalid_body" });
+      return;
+    }
+    const value = parsed.value;
+    const action = value.action;
+    if (!isActionKind(action)) {
+      sendJson(res, 400, { error: "invalid_action" });
+      return;
+    }
+    if (value.confirm !== true) {
+      sendJson(res, 400, { error: "confirmation_required" });
+      return;
+    }
+    // Hard-gate check: when an OPEN hard-gate item gates this action, do NOT
+    // spawn — surface the blocker ids so the client highlights the matching rows.
+    const blockers = setupCortexActionBlockers(action);
+    if (blockers.length > 0) {
+      sendJson(res, 423, {
+        error: "action_blocked_by_open_item",
+        blockers: [...blockers],
+      });
+      return;
+    }
+    const result = runSetupCortexAction(action, ctx.stateDir);
+    sendJson(res, result.ok ? 200 : 500, result);
+  });
+  return true;
+}
+
+/**
+ * GET /api/setup-cortex-action-log?name=<basename> (VC9B). Returns true when it
+ * claims the request. Bounded tail (8 KiB max) + redacted (digest prefixes +
+ * codes); the name must validate to a basename inside the vc9b log dir.
+ */
+export function handleSetupCortexActionLog(
+  req: IncomingMessage,
+  res: ServerResponse,
+  ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  if (url.split("?")[0] !== "/api/setup-cortex-action-log") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+  if (!VC9B_ENABLED()) {
+    sendDisabled(res);
+    return true;
+  }
+  let name: string | null = null;
+  try {
+    name = new URL(url, "http://localhost").searchParams.get("name");
+  } catch {
+    name = null;
+  }
+  if (!name) {
+    sendJson(res, 400, { error: "invalid_log_name" });
+    return true;
+  }
+  const tail = readActionLogTail(ctx.stateDir, name);
+  if (tail === null) {
+    sendJson(res, 404, { error: "log_not_found" });
+    return true;
+  }
+  sendJson(res, 200, tail);
+  return true;
+}