pi-mega-compact 0.16.3 → 0.17.1

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

@@ -0,0 +1,54 @@
+/**
+ * dashboard-client/src/api/vector-cortex.ts — vector-cortex API client.
+ * PREVENT-PI-004: relative path only (loopback dashboard).
+ */
+
+import type {
+	VectorCortexEvaluationSummary,
+	VectorCortexHealthCard,
+	VectorCortexLedgerView,
+	VectorCortexResetResult,
+} from "../types/vector-cortex";
+
+export type {
+	VectorCortexEvaluationSummary,
+	VectorCortexHealthCard,
+	VectorCortexLedgerView,
+	VectorCortexResetResult,
+};
+
+export async function fetchVectorCortexEvaluation(): Promise<VectorCortexEvaluationSummary> {
+	const r = await fetch("/api/vector-cortex/evaluation");
+	if (!r.ok) throw new Error(`vector-cortex evaluation: ${r.status}`);
+	return r.json() as Promise<VectorCortexEvaluationSummary>;
+}
+
+export async function fetchVectorCortexHealth(): Promise<VectorCortexHealthCard> {
+	const r = await fetch("/api/vector-cortex/health");
+	if (!r.ok) throw new Error(`vector-cortex health: ${r.status}`);
+	return r.json() as Promise<VectorCortexHealthCard>;
+}
+
+/** Reader-only occurrence-ledger identity view (VC1B). */
+export async function fetchVectorCortexLedger(
+	session = "default",
+): Promise<VectorCortexLedgerView> {
+	const r = await fetch(
+		`/api/vector-cortex/ledger?session=${encodeURIComponent(session)}`,
+	);
+	if (!r.ok) throw new Error(`vector-cortex ledger: ${r.status}`);
+	return r.json() as Promise<VectorCortexLedgerView>;
+}
+
+/** Admin capability: reset a breaker's cooldown (never evidence). */
+export async function resetVectorCortexBreaker(
+	subsystem: string,
+): Promise<VectorCortexResetResult> {
+	const r = await fetch("/api/vector-cortex/breakers/reset", {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ subsystem }),
+	});
+	if (!r.ok) throw new Error(`vector-cortex reset: ${r.status}`);
+	return r.json() as Promise<VectorCortexResetResult>;
+}

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

@@ -0,0 +1,272 @@
+/**
+ * VectorCortexTab.tsx — vector-cortex dashboard tab.
+ * VC0A: reader-only aggregate latency histogram + per-mode sample counts from
+ * GET /api/vector-cortex/evaluation. VC0C (task 5): live safety envelope health
+ * card (breaker state, window/probe/backoff, durable spool frontier/lag) from
+ * GET /api/vector-cortex/health plus an admin "reset cooldown" action. Polls
+ * every 5s.
+ */
+
+import { useState, useEffect, useCallback } from "react";
+import {
+	fetchVectorCortexEvaluation,
+	fetchVectorCortexHealth,
+	fetchVectorCortexLedger,
+	resetVectorCortexBreaker,
+	type VectorCortexEvaluationSummary,
+	type VectorCortexHealthCard,
+	type VectorCortexLedgerView,
+} from "../api/vector-cortex";
+import { Card, CardContent, CardHeader, CardTitle } from "../components/ui/card";
+import { Badge } from "../components/ui/badge";
+
+function ModeChip({ mode, count }: { mode: string; count: number }): React.ReactElement {
+	return (
+		<div className="flex items-center justify-between border-b border-border/50 py-1 text-sm">
+			<span className="text-muted-foreground">Mode {mode}</span>
+			<span className="font-mono">{count}</span>
+		</div>
+	);
+}
+
+function Metric({ label, value }: { label: string; value: string }): React.ReactElement {
+	return (
+		<div>
+			<div className="text-xs text-muted-foreground">{label}</div>
+			<div className="font-mono text-sm">{value}</div>
+		</div>
+	);
+}
+
+export default function VectorCortexTab(): React.ReactElement {
+	const [data, setData] = useState<VectorCortexEvaluationSummary | null>(null);
+	const [err, setError] = useState<string | null>(null);
+	const [loading, setLoading] = useState(true);
+	const [health, setHealth] = useState<VectorCortexHealthCard | null>(null);
+	const [resetMsg, setResetMsg] = useState<string | null>(null);
+	const [ledger, setLedger] = useState<VectorCortexLedgerView | null>(null);
+
+	const poll = useCallback(() => {
+		fetchVectorCortexEvaluation()
+			.then(setData)
+			.catch((e: unknown) =>
+				setError(e instanceof Error ? e.message : String(e)),
+			)
+			.finally(() => setLoading(false));
+		fetchVectorCortexHealth().then(setHealth).catch(() => {
+			/* health card is best-effort (VC0C) */
+		});
+		fetchVectorCortexLedger().then(setLedger).catch(() => {
+			/* ledger card is best-effort (VC1B) */
+		});
+	}, []);
+
+	useEffect(() => {
+		poll();
+		const id = setInterval(poll, 5000);
+		return () => clearInterval(id);
+	}, [poll]);
+
+	const onReset = () => {
+		resetVectorCortexBreaker("provider")
+			.then((r) => {
+				setResetMsg(
+					`Breaker "${r.subsystem}" ${r.state}; evidence retained: ${r.failures} failures / ${r.attempts} attempts`,
+				);
+				return fetchVectorCortexHealth();
+			})
+			.then(setHealth)
+			.catch((e: unknown) =>
+				setResetMsg(e instanceof Error ? e.message : String(e)),
+			);
+	};
+
+	if (loading && !data)
+		return <div className="vc-loading">Loading vector-cortex evaluation…</div>;
+	if (err && !data)
+		return <div className="vc-error">Error: {err}</div>;
+	if (!data)
+		return <div className="vc-empty">No evaluation data available.</div>;
+
+	const max = Math.max(1, ...data.histogram.cells, data.histogram.overflow);
+	return (
+		<div className="flex flex-col gap-4">
+			<div className="flex items-center gap-2">
+				<h2 className="text-lg font-semibold">Vector Cortex Evaluation</h2>
+				{data.enabled ? (
+					<Badge variant="warning">OBSERVER PENDING (A)</Badge>
+				) : (
+					<Badge variant="danger">MODE C (OFF)</Badge>
+				)}
+			</div>
+
+			<div className="grid grid-cols-1 gap-4 md:grid-cols-3">
+				<Card>
+					<CardHeader>
+						<CardTitle>Samples</CardTitle>
+					</CardHeader>
+					<CardContent>
+						<div className="text-3xl font-bold">{data.samples}</div>
+						<div className="mt-2 flex flex-col">
+							<ModeChip mode="A" count={data.byMode.A} />
+							<ModeChip mode="B" count={data.byMode.B} />
+							<ModeChip mode="C" count={data.byMode.C} />
+						</div>
+					</CardContent>
+				</Card>
+
+				<Card className="md:col-span-2">
+					<CardHeader>
+						<CardTitle>Latency Histogram (ms, inclusive edges)</CardTitle>
+					</CardHeader>
+					<CardContent>
+						<div className="flex items-end gap-2" style={{ height: 160 }}>
+							{data.histogram.edges.map((edge, i) => {
+								const h = (data.histogram.cells[i] / max) * 140;
+								return (
+									<div key={edge} className="flex flex-1 flex-col items-center gap-1">
+										<span className="text-xs text-muted-foreground">
+											{data.histogram.cells[i]}
+										</span>
+										<div
+											className="w-full rounded-t"
+											style={{ height: Math.max(2, h), background: "#6366f1" }}
+										/>
+										<span className="text-[10px] text-muted-foreground">&le;{edge}</span>
+									</div>
+								);
+							})}
+							<div className="flex flex-1 flex-col items-center gap-1">
+								<span className="text-xs text-muted-foreground">
+									{data.histogram.overflow}
+								</span>
+								<div
+									className="w-full rounded-t"
+									style={{
+										height: Math.max(2, (data.histogram.overflow / max) * 140),
+										background: "#f87171",
+									}}
+								/>
+								<span className="text-[10px] text-muted-foreground">&gt;250</span>
+							</div>
+						</div>
+						<div className="mt-1 text-xs text-muted-foreground">
+							Total: {data.histogram.total} · Rejects: {data.rejects.length}
+						</div>
+					</CardContent>
+				</Card>
+			</div>
+
+			<Card>
+				<CardHeader>
+					<div className="flex items-center justify-between">
+						<CardTitle>Live Safety Envelope (VC0C)</CardTitle>
+						<div className="flex items-center gap-2">
+							{health?.stateSource === "ephemeral" && (
+								<Badge variant="outline">EPHEMERAL (non-live)</Badge>
+							)}
+							<button
+								onClick={onReset}
+								disabled={!health?.enabled}
+								className="rounded border border-border px-2 py-1 text-xs disabled:opacity-50"
+							>
+								Reset Cooldown
+							</button>
+						</div>
+					</div>
+				</CardHeader>
+				<CardContent>
+					{resetMsg && (
+						<div className="mb-2 text-xs text-muted-foreground">{resetMsg}</div>
+					)}
+					{!health ? (
+						<div className="vc-empty">Health unavailable (VC0C off).</div>
+					) : (
+						<div className="grid grid-cols-2 gap-4 md:grid-cols-4">
+							<Metric label="State" value={health.state} />
+							<Metric label="Mode" value={health.mode} />
+							<Metric label="Window" value={`${health.windowMs}ms`} />
+							<Metric label="Probes" value={String(health.probeCount)} />
+							<Metric label="Backoff" value={`${health.backoffDelayMs}ms`} />
+							<Metric
+								label="Failures"
+								value={`${health.failures}/${health.attempts}`}
+							/>
+							<Metric
+								label="Frontier"
+								value={
+									health.stateSource === "ephemeral"
+										? "non-live"
+										: health.frontierFrozen
+											? "FROZEN"
+											: "LIVE"
+								}
+							/>
+							<Metric label="Spool lag" value={String(health.spoolLag)} />
+						</div>
+					)}
+				</CardContent>
+			</Card>
+			<Card>
+				<CardHeader>
+					<div className="flex items-center justify-between">
+						<CardTitle>Occurrence Ledger (VC1B)</CardTitle>
+						{ledger?.enabled ? (
+							<Badge variant="success">ACTIVE</Badge>
+						) : (
+							<Badge variant="danger">OFF</Badge>
+						)}
+					</div>
+				</CardHeader>
+				<CardContent>
+					{!ledger?.enabled ? (
+						<div className="vc-empty">Ledger disabled (VC1B off).</div>
+					) : (
+						<>
+							<div className="mb-3 grid grid-cols-2 gap-4 md:grid-cols-3">
+								<Metric label="Session" value={ledger.session} />
+								<Metric label="High-water" value={ledger.highWater} />
+								<Metric label="Occurrences" value={String(ledger.count)} />
+							</div>
+							{ledger.occurrences.length === 0 ? (
+								<div className="vc-empty">No occurrences recorded.</div>
+							) : (
+								<div className="max-h-64 overflow-y-auto">
+									<table className="w-full text-left text-xs">
+										<thead>
+											<tr className="border-b border-border/50 text-muted-foreground">
+												<th className="py-1 pr-2">seq</th>
+												<th className="py-1 pr-2">eventId</th>
+												<th className="py-1 pr-2">kind</th>
+												<th className="py-1 pr-2">toolCall</th>
+												<th className="py-1">digest</th>
+											</tr>
+										</thead>
+										<tbody>
+											{ledger.occurrences.map((o) => (
+												<tr
+													key={`${o.seq}-${o.eventId}`}
+													className="border-b border-border/30"
+												>
+													<td className="py-1 pr-2 font-mono">{o.seq}</td>
+													<td className="py-1 pr-2 font-mono">{o.eventId}</td>
+													<td className="py-1 pr-2">{o.kind}</td>
+													<td className="py-1 pr-2 font-mono">
+														{o.toolCallId ?? "\u2014"}
+													</td>
+													<td className="max-w-[180px] truncate font-mono text-muted-foreground">
+														{o.digest}
+													</td>
+												</tr>
+											))}
+										</tbody>
+									</table>
+								</div>
+							)}
+						</>
+					)}
+				</CardContent>
+			</Card>
+		</div>
+	);
+}

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

@@ -12,6 +12,7 @@ import {
   BookOpen,
   Wrench,
   Network,
+  Activity,
 } from "lucide-react";
 
 export type TabId =
@@ -26,7 +27,8 @@ export type TabId =
   | "turns"
   | "maintenance"
   | "memory-map"
-  | "health";
+  | "health"
+  | "vector-cortex";
 
 export interface TabDef {
   id: TabId;
@@ -50,6 +52,7 @@ export const ADVANCED_TABS: TabDef[] = [
   { id: "wiki", label: "Wiki", icon: BookOpen },
   { id: "maintenance", label: "Maintenance", icon: Wrench },
   { id: "memory-map", label: "Memory Map", icon: Network },
+  { id: "vector-cortex", label: "Vector Cortex", icon: Activity },
 ];
 
 export const ADVANCED_TAB_IDS: ReadonlySet<TabId> = new Set(

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

@@ -0,0 +1,84 @@
+/**
+ * dashboard-client/src/types/vector-cortex.ts — vector-cortex client types.
+ * Mirrors the reader-only evaluation summary (VC0A). Contains only aggregates
+ * (histogram cells + counts), never payloads/prompts/ledger.
+ */
+
+export interface VectorCortexEvaluationSummary {
+  enabled: boolean;
+  mode: "A" | "B" | "C";
+  samples: number;
+  byMode: { A: number; B: number; C: number };
+  histogram: {
+    edges: number[];
+    cells: number[];
+    overflow: number;
+    total: number;
+  };
+  rejects: string[];
+  updatedAt: string;
+}
+
+/**
+ * Health card (VC0C, task 5): breaker state + durable spool frontier/lag.
+ * Aggregate only — never payloads/prompts/ledger.
+ */
+export interface VectorCortexHealthCard {
+  enabled: boolean;
+  mode: "A" | "B" | "C";
+  state:
+    | "CLOSED_A"
+    | "OPEN_B"
+    | "OPEN_C"
+    | "PROBE_B"
+    | "PROBE_A"
+    | "MANUAL_HALT";
+  subsystem: string;
+  sinceMs: number;
+  reason?: string;
+  windowMs: number;
+  probeCount: number;
+  backoffDelayMs: number;
+  frontierFrozen: boolean;
+  authorityOutage: boolean;
+  spoolLag: number;
+  attempts: number;
+  failures: number;
+  p95Ms: number;
+  failureRate: number;
+  updatedAt: string;
+  aggregate: string;
+  /** "ephemeral" = per-process/in-memory breaker (non-live until VC0D). */
+  stateSource: "ephemeral" | "live";
+}
+
+/** Admin reset result (VC0C, task 5). */
+export interface VectorCortexResetResult {
+  subsystem: string;
+  state: string;
+  cooldownCleared: boolean;
+  attempts: number;
+  failures: number;
+  probeCount: number;
+  manualReason?: string;
+  updatedAt: string;
+}
+
+/**
+ * Occurrence-ledger identity view (VC1B, GET /api/vector-cortex/ledger).
+ * Reader-only: seq/eventId/kind/digest + high-water, never source payloads.
+ */
+export interface VectorCortexLedgerView {
+  enabled: boolean;
+  session: string;
+  highWater: string;
+  count: number;
+  occurrences: Array<{
+    seq: string;
+    eventId: string;
+    kind: string;
+    digest: string;
+    toolCallId?: string;
+  }>;
+  updatedAt: string;
+}

package/extensions/dashboard-client/tsconfig.json

@@ -16,7 +16,7 @@
     "verbatimModuleSyntax": true,
     "noEmit": true,
     "allowImportingTsExtensions": true,
-    "types": [],
+    "types": ["node"],
     "baseUrl": ".",
     "paths": {
       "@/*": ["./src/*"],

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

@@ -0,0 +1,67 @@
+/**
+ * api-contracts/endpoints/registry-ext.ts — additive endpoint registry groups.
+ *
+ * Split out of registry.ts (delegate-shell) so the registry stays under the
+ * 500-line extension hard limit. Holds the newest endpoint groups (per-model
+ * thresholds, vector-cortex) that are appended to the ENDPOINTS registry via
+ * object spread. Types are identical to sibling entries (`EndpointDef`).
+ *
+ * Sprint A1 — PREVENT-PI-004: zero network code (type definitions only).
+ * PREVENT-011: no `any` type.
+ */
+import type { EndpointDef } from "../core.js";
+import type { RagMetricsResponse } from "../rag-metrics.js";
+import type { ModelThresholdsResponse } from "../model-thresholds.js";
+import type {
+  VectorCortexEvaluationSummary,
+  VectorCortexLedgerView,
+} from "../vector-cortex.js";
+
+/** Additive endpoint entries spread into the ENDPOINTS registry. */
+export const EXTRA_ENDPOINTS = {
+	// ─── Per-model compaction thresholds (S52 / v0.16.1) ───────────────
+
+	/** GET /api/model-thresholds — List known models + their thresholds. */
+	modelThresholds: {
+		method: "GET",
+		path: "/api/model-thresholds",
+		description:
+			"Every known model (from model_snapshots) with its per-model threshold override (or defaults).",
+	} as const satisfies EndpointDef<"GET", undefined, ModelThresholdsResponse>,
+
+	// ─── RAG Metrics (Sprint H2) ──────────────────────────────────────
+
+	/** GET /api/rag-metrics — HyDE + recall-quality telemetry aggregates. */
+	ragMetrics: {
+		method: "GET",
+		path: "/api/rag-metrics",
+		description:
+			"HyDE invocation + recall-quality telemetry: flags, totals, recent turns, and daily series.",
+	} as const satisfies EndpointDef<"GET", undefined, RagMetricsResponse>,
+
+	// ─── Vector Cortex (VC0A) ────────────────────────────────────────
+
+	/** GET /api/vector-cortex/evaluation — reader-only eval aggregate (VC0A). */
+	vectorCortexEvaluation: {
+		method: "GET",
+		path: "/api/vector-cortex/evaluation",
+		description:
+			"Reader-only vector-cortex evaluation summary: latency histogram + per-mode sample counts (never payloads).",
+	} as const satisfies EndpointDef<
+		"GET",
+		undefined,
+		VectorCortexEvaluationSummary
+	>,
+
+	/** GET /api/vector-cortex/ledger — reader-only occurrence ledger view (VC1B). */
+	vectorCortexLedger: {
+		method: "GET",
+		path: "/api/vector-cortex/ledger",
+		description:
+			"Reader-only occurrence-ledger identity view: seq/eventId/kind/digest + high-water (never source payloads).",
+	} as const satisfies EndpointDef<
+		"GET",
+		undefined,
+		VectorCortexLedgerView
+	>,
+} as const;

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

@@ -32,8 +32,7 @@ import type {
 	RagSettingsRequest,
 	RagSettingsResponsePost,
 } from "../rag-settings.js";
-import type { RagMetricsResponse } from "../rag-metrics.js";
-import type { ModelThresholdsResponse } from "../model-thresholds.js";
+import { EXTRA_ENDPOINTS } from "./registry-ext.js";
 import type {
 	TurnsResponse,
 	ConversationTurnsResponse,
@@ -491,23 +490,7 @@ export const ENDPOINTS = {
 		RagSettingsResponsePost
 	>,
 
-	// ─── RAG Metrics (Sprint H2) ──────────────────────────────────────
-
-	/** GET /api/rag-metrics — HyDE + recall-quality telemetry aggregates. */
-	ragMetrics: {
-		method: "GET",
-		path: "/api/rag-metrics",
-		description:
-			"HyDE invocation + recall-quality telemetry: flags, totals, recent turns, and daily series.",
-	} as const satisfies EndpointDef<"GET", undefined, RagMetricsResponse>,
-
-	// ─── Per-model compaction thresholds (S52 / v0.16.1) ───────────────
-
-	/** GET /api/model-thresholds — List known models + their thresholds. */
-	modelThresholds: {
-		method: "GET",
-		path: "/api/model-thresholds",
-		description:
-			"Every known model (from model_snapshots) with its per-model threshold override (or defaults).",
-	} as const satisfies EndpointDef<"GET", undefined, ModelThresholdsResponse>,
+	// ─── Additive groups (rag-metrics, thresholds, vector-cortex) live in
+	// ─── registry-ext.ts so this registry stays under the 500-line limit.
+	...EXTRA_ENDPOINTS,
 } as const;

package/extensions/dashboard-server/api-contracts/index.ts

@@ -242,6 +242,9 @@ export type {
 // Embedder health probe
 export type { EmbedderHealthResponse } from "./embedder-health.js";
 
+// VC0A — vector-cortex evaluation summary (reader-only)
+export type { VectorCortexEvaluationSummary } from "./vector-cortex.js";
+
 // S46/D3 — memory graph (visual memory map) + validation report
 export type {
 	MemoryMapResponse,