pi-mega-compact 0.20.32 → 0.20.34

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

@@ -54,9 +54,6 @@ import type {
 	SettingsUpdateRequest,
 	SettingsResponsePost,
 	RagMetricsResponse,
-	ModelThresholdsResponse,
-	ModelThresholdPutRequest,
-	ModelThresholdPutResponse,
 	WikiIndexResponse,
 	WikiPageResponse,
 	CurationResult,
@@ -67,74 +64,17 @@ import type {
 	TopicEvolutionResponse,
 } from "@contracts";
 
-/** Error thrown when a dashboard API response is not 2xx. */
-export class ApiError extends Error {
-	readonly status: number;
-	constructor(status: number, message: string) {
-		super(`dashboard API ${status}: ${message}`);
-		this.name = "ApiError";
-		this.status = status;
-	}
-}
-
-/** Internal: typed GET that throws ApiError on non-2xx. */
-async function getJson<T>(path: string): Promise<T> {
-	// guardrails-allow PREVENT-PI-004: relative-path fetch to same-origin dashboard server (loopback-only, static bundle served by the same Node HTTP server).
-	const res = await fetch(path);
-	if (!res.ok) {
-		throw new ApiError(
-			res.status,
-			await res.text().catch(() => res.statusText),
-		);
-	}
-	return res.json() as Promise<T>;
-}
-
-/** Internal: typed PUT that throws ApiError on non-2xx. */
-async function putJson<T>(path: string, body: unknown): Promise<T> {
-	// guardrails-allow PREVENT-PI-004: relative-path fetch to same-origin dashboard server (loopback-only).
-	const res = await fetch(path, {
-		method: "PUT",
-		headers: { "Content-Type": "application/json" },
-		body: JSON.stringify(body),
-	});
-	if (!res.ok) {
-		throw new ApiError(
-			res.status,
-			await res.text().catch(() => res.statusText),
-		);
-	}
-	return res.json() as Promise<T>;
-}
-
-/** Internal: typed POST that throws ApiError on non-2xx. */
-async function postJson<T>(path: string, body: unknown): Promise<T> {
-	// guardrails-allow PREVENT-PI-004: relative-path fetch to same-origin dashboard server (loopback-only, static bundle served by the same Node HTTP server).
-	const res = await fetch(path, {
-		method: "POST",
-		headers: { "Content-Type": "application/json" },
-		body: JSON.stringify(body),
-	});
-	if (!res.ok) {
-		throw new ApiError(
-			res.status,
-			await res.text().catch(() => res.statusText),
-		);
-	}
-	return res.json() as Promise<T>;
-}
-
-/** Build a query string from a record, skipping undefined/null values. */
-function query(
-	params: Record<string, string | number | undefined | null>,
-): string {
-	const sp = new URLSearchParams();
-	for (const [k, v] of Object.entries(params)) {
-		if (v !== undefined && v !== null) sp.set(k, String(v));
-	}
-	const qs = sp.toString();
-	return qs ? `?${qs}` : "";
-}
+// Shared HTTP helpers (ApiError/getJson/putJson/postJson/query) live in
+// client-http.ts (delegate-shell split keeps client.ts under 400 lines).
+import { getJson, putJson, postJson, query } from "./client-http.js";
+// Newer endpoint groups (model thresholds, PC-C prefix-stability) live in
+// client-extra.ts; re-exported here so downstream imports are unchanged.
+export {
+	fetchModelThresholds,
+	putModelThreshold,
+	deleteModelThreshold,
+	fetchPrefixStability,
+} from "./client-extra.js";
 
 // ─── Endpoint wrappers ──────────────────────────────────────────────────────
 
@@ -456,32 +396,3 @@ export function fetchTopicTimeline(
 export function fetchTopicEvolution(): Promise<TopicEvolutionResponse> {
 	return getJson<TopicEvolutionResponse>(ENDPOINTS.topicEvolution.path);
 }
-
-// ─── Per-model compaction thresholds (S52 / v0.16.1) ────────────────────
-
-/** GET /api/model-thresholds — list known models with their thresholds. */
-export function fetchModelThresholds(): Promise<ModelThresholdsResponse> {
-	return getJson<ModelThresholdsResponse>(ENDPOINTS.modelThresholds.path);
-}
-
-/** PUT /api/model-thresholds — upsert a per-model override. */
-export function putModelThreshold(
-	body: ModelThresholdPutRequest,
-): Promise<ModelThresholdPutResponse> {
-	return putJson<ModelThresholdPutResponse>(
-		ENDPOINTS.modelThresholds.path,
-		body,
-	);
-}
-
-/** DELETE /api/model-thresholds/:modelId — delete an override (revert). */
-export async function deleteModelThreshold(
-	modelId: string,
-): Promise<{ deleted: boolean }> {
-	const res = await fetch(
-		`${ENDPOINTS.modelThresholds.path}/${encodeURIComponent(modelId)}`,
-		{ method: "DELETE" },
-	);
-	if (!res.ok) throw new Error(`deleteModelThreshold ${res.status}`);
-	return res.json() as Promise<{ deleted: boolean }>;
-}

package/extensions/dashboard-client/src/components/PrefixStabilityCard.tsx

@@ -0,0 +1,98 @@
+/**
+ * dashboard-client/src/components/PrefixStabilityCard.tsx -- Prompt-cache per-turn
+ * stable-prefix ratio trend (PC-C).
+ *
+ * Renders a sparkline of the per-turn stable-prefix ratio (stablePrefix /
+ * totalMessages) read from /api/prefix-stability, with the average ratio and a
+ * three-point trend badge ("improving" | "stable" | "degrading"). Each bar is one
+ * turn. Uses the same .ov-sparkline / .ov-bar-* CSS classes as CacheHitRateTrendCard.
+ * No external charting dependencies.
+ */
+
+import type React from "react";
+import type { PrefixStabilityResponse } from "@contracts";
+import { Card, CardContent, CardHeader, CardTitle } from "../components/ui/card";
+
+export interface PrefixStabilityCardProps {
+	data: PrefixStabilityResponse;
+}
+
+function fmtRatio(n: number): string {
+	return `${(n * 100).toFixed(1)}%`;
+}
+
+/** Map a ratio (0–1) to a CSS color class (mirrors pctColorClass thresholds). */
+function ratioColorClass(ratio: number): string {
+	const pct = ratio * 100;
+	if (pct >= 80) return "ov-bar-green";
+	if (pct >= 60) return "ov-bar-teal";
+	if (pct >= 40) return "ov-bar-yellow";
+	if (pct >= 20) return "ov-bar-orange";
+	return "ov-bar-red";
+}
+
+const TREND_LABEL: Record<PrefixStabilityResponse["trend"], string> = {
+	improving: "Improving",
+	stable: "Stable",
+	degrading: "Degrading",
+};
+
+export const PrefixStabilityCard: React.FC<PrefixStabilityCardProps> = ({
+	data,
+}) => {
+	const { turns, avgRatio, trend } = data;
+
+	return (
+		<Card className="electric-hover">
+			<CardHeader>
+				<CardTitle>Per-Turn Stable Prefix</CardTitle>
+			</CardHeader>
+			<CardContent>
+				<div className="mb-3 flex gap-4 text-sm text-muted-foreground">
+					<div>
+						Avg:{" "}
+						<strong className="text-foreground">{fmtRatio(avgRatio)}</strong>
+					</div>
+					<div>
+						Trend:{" "}
+						<strong className="text-foreground">{TREND_LABEL[trend]}</strong>
+					</div>
+					<div>
+						Turns: <strong className="text-foreground">{turns.length}</strong>
+					</div>
+				</div>
+
+				{turns.length > 0 ? (
+					<>
+						<div
+							className="ov-sparkline"
+							role="img"
+							aria-label={`Per-turn stable-prefix ratio trend: ${turns.length} turns, average ${fmtRatio(avgRatio)}, trend ${TREND_LABEL[trend]}`}
+						>
+							{turns.map((t, i) => {
+								const barH = Math.max(2, Math.round(t.ratio * 60));
+								const colorClass = ratioColorClass(t.ratio);
+								const isLatest = i === turns.length - 1;
+								return (
+									<div
+										key={i}
+										className={`ov-sparkline-bar ${colorClass}${isLatest ? " ov-bar-latest" : ""}`}
+										style={{ height: `${barH}px` }}
+										title={`Turn ${t.turnIndex}: ${fmtRatio(t.ratio)} (${t.stablePrefix}/${t.totalMessages} msg) @ ${new Date(t.timestamp).toLocaleTimeString()}`}
+									/>
+								);
+							})}
+						</div>
+						<div className="mt-1 text-xs text-muted-foreground">
+							Shared prompt-cache prefix ratio per turn — higher is better.
+						</div>
+					</>
+				) : (
+					<div className="text-sm text-muted-foreground">
+						No stable-prefix samples yet
+					</div>
+				)}
+			</CardContent>
+		</Card>
+	);
+};

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

@@ -17,12 +17,14 @@ import type {
 	ProviderCacheResponse,
 	CacheStripesResponse,
 	PerfResponse,
+	PrefixStabilityResponse,
 } from "@contracts";
 import { useApi } from "../hooks/useApi";
 import {
 	fetchSnapshot,
 	fetchProviderCache,
 	fetchCacheStripes,
+	fetchPrefixStability,
 	fetchPerf,
 } from "../api/client";
 import { CacheHitsCard } from "../components/CacheHitsCard";
@@ -30,6 +32,7 @@ import { TimeSavedCard } from "../components/TimeSavedCard";
 import { ProviderCacheCard } from "../components/ProviderCacheCard";
 import { StripeDistributionCard } from "../components/StripeDistributionCard";
 import { CacheHitRateTrendCard } from "../components/CacheHitRateTrendCard";
+import { PrefixStabilityCard } from "../components/PrefixStabilityCard";
 import { Button } from "../components/ui/button";
 import { Card, CardContent, CardHeader, CardTitle } from "../components/ui/card";
 
@@ -65,6 +68,15 @@ export default function CacheTab(): React.ReactElement {
 		{ pollInterval: 15000 },
 	);
 
+	/* --- Per-turn stable-prefix ratio trend (PC-C, 15s poll) --- */
+	const {
+		data: prefixStability,
+		loading: psLoading,
+	} = useApi<PrefixStabilityResponse>(
+		useCallback(() => fetchPrefixStability(50), []),
+		{ pollInterval: 15000 },
+	);
+
 	/* --- Dedup cache snapshot (5s poll) --- */
 	const {
 		data: snapshot,
@@ -164,6 +176,21 @@ export default function CacheTab(): React.ReactElement {
 				<CacheHitRateTrendCard perf={perf} />
 			) : null}
 
+			{/* ==============================================================
+			    Section 3b -- Per-Turn Stable Prefix (PC-C)
+			    Omitted when flag-off: the endpoint 404s, so psError is set and
+			    this section stays empty. No sample/time-series data, only
+			    per-turn prefix ratios read from the local events log.
+			    ============================================================== */}
+			{prefixStability && !psLoading ? (
+				<div>
+					<h2 className="font-heading text-lg font-semibold">
+						Per-Turn Stable Prefix
+					</h2>
+					<PrefixStabilityCard data={prefixStability} />
+				</div>
+			) : null}
+
 			{/* ==============================================================
 			    Section 4 -- Mega-Compact Dedup Cache
 			    ============================================================== */}

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

@@ -24,6 +24,7 @@ import type {
   SetupCortexActionLogQuery,
   SetupCortexActionLogResponse,
 } from "../setup-cortex.js";
+import type { PrefixStabilityResponse } from "../prefix-stability.js";
 
 /** Additive endpoint entries spread into the ENDPOINTS registry. */
 export const EXTRA_ENDPOINTS = {
@@ -108,4 +109,18 @@ export const EXTRA_ENDPOINTS = {
 		SetupCortexActionLogQuery,
 		SetupCortexActionLogResponse
 	>,
+
+	// ─── PC-C Prompt-cache prefix stability (dashboard Cache tab) ───────
+
+	/** GET /api/prefix-stability — per-turn stable-prefix ratio trend (PC-C). */
+	prefixStability: {
+		method: "GET",
+		path: "/api/prefix-stability",
+		description:
+			"Per-turn prompt-cache stable-prefix ratio trend (GET /api/prefix-stability?limit=N) read from prefix_stability rows in the local events log. Flag-off (MEGACOMPACT_PC_C=0) returns 404.",
+	} as const satisfies EndpointDef<
+		"GET",
+		undefined,
+		PrefixStabilityResponse
+	>,
 } as const;

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

@@ -269,6 +269,12 @@ export type {
 	CacheStripesResponse,
 } from "./cache-stripes.js";
 
+// PC-C — prompt-cache prefix-stability per-turn trend
+export type {
+	PrefixStabilitySample,
+	PrefixStabilityResponse,
+} from "./prefix-stability.js";
+
 // RAG Settings — comprehensive adjustable settings (B6)
 export type {
 	SettingState,

package/extensions/dashboard-server/api-contracts/prefix-stability.ts

@@ -0,0 +1,40 @@
+/**
+ * api-contracts/prefix-stability.ts — Prompt-cache prefix-stability API contract (PC-C).
+ *
+ * Response shape for GET /api/prefix-stability?limit=50: per-turn stable-prefix
+ * ratio trend surfaced from the local monitoring events log (prefix_stability rows
+ * appended by tailResult.ts). Loopback-only data; zero network (PREVENT-PI-004).
+ */
+
+/** A single per-turn prefix-stability sample. */
+export interface PrefixStabilitySample {
+	/** Monotonic turn index (order of emission, 0-based). */
+	readonly turnIndex: number;
+	/** Number of messages sharing the stable prefix (cache-able head). */
+	readonly stablePrefix: number;
+	/** Total messages in the assembled prompt for that turn. */
+	readonly totalMessages: number;
+	/** stablePrefix / totalMessages (0.0–1.0); 0 when totalMessages is 0. */
+	readonly ratio: number;
+	/** Ollama-style striping mode at emit time: "v3" (cache-striping) | "v2" | "off". */
+	readonly striping: string;
+	/** ISO-8601 timestamp of the event (from the events log row). */
+	readonly timestamp: string;
+}
+
+/** Three-point trend classification across the returned window. */
+export type PrefixStabilityTrend = "improving" | "stable" | "degrading";
+
+/** Response body for GET /api/prefix-stability. */
+export interface PrefixStabilityResponse {
+	/** Per-turn samples in chronological order (oldest first), at most `limit`. */
+	readonly turns: PrefixStabilitySample[];
+	/** Mean ratio across returned samples (0.0–1.0); 0 when empty. */
+	readonly avgRatio: number;
+	/** Trend classification of the tail of the window vs its head. */
+	readonly trend: PrefixStabilityTrend;
+	/** Number of samples returned. */
+	readonly count: number;
+	/** Epoch-millis timestamp the endpoint last scanned the events log. */
+	readonly lastScanAt: number;
+}

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

@@ -28,6 +28,7 @@ import {
 	handleProviderCache,
 	handleMemoryStatus,
 	handleCacheStripes,
+	handlePrefixStability,
 	handleSetupStatus,
 	handleSetupDetect,
 	handleSetupConfigure,
@@ -114,6 +115,7 @@ export function dispatchRoutes(
 	if (handleProviderCache(req, res, ctx)) return true;
 	if (handleMemoryStatus(req, res, ctx)) return true;
 	if (handleCacheStripes(req, res, ctx)) return true;
+	if (handlePrefixStability(req, res, ctx)) return true;
 	if (handleSetupStatus(req, res, ctx)) return true;
 	if (handleSetupDetect(req, res, ctx)) return true;
 	if (handleSetupConfigure(req, res, ctx)) return true;

package/extensions/dashboard-server/routes-prefix-stability.ts

@@ -0,0 +1,142 @@
+/**
+ * dashboard-server/routes-prefix-stability.ts — Prompt-cache prefix-stability route (PC-C).
+ *
+ * GET /api/prefix-stability?limit=50 — reads recent prefix_stability rows from the
+ * local monitoring events log (ctx.eventsPath) and returns the per-turn stable-prefix
+ * ratio trend. Flag-off (MEGACOMPACT_PC_C=0) → 404, byte-identical to PC-B predecessor.
+ *
+ * Guardrails: PREVENT-PI-004 (loopback-only local dashboard), PREVENT-001 (null-safe
+ * JSON.parse), PREVENT-011 (no `any`). Zero network reads.
+ */
+
+import { readFileSync } from "node:fs";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { PrefixStabilityResponse } from "./api-contracts/prefix-stability.js";
+import type { RouteContext } from "./routes-core.js";
+
+/** Parse one events.log line into a generic JSON object, null-safe (PREVENT-001). */
+function parseEventLine(line: string): Record<string, unknown> | null {
+	try {
+		const parsed: unknown = JSON.parse(line);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+			return parsed as Record<string, unknown>;
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+/** Read the tail of events.log and return only prefix_stability rows, newest last. */
+function readPrefixStabilityEvents(
+	eventsPath: string,
+	limit: number,
+): Array<{ ts: number; stablePrefix: number; totalMessages: number; separation: string; striping: string }> {
+	const samples: Array<{
+		ts: number;
+		stablePrefix: number;
+		totalMessages: number;
+		separation: string;
+		striping: string;
+	}> = [];
+	let raw = "";
+	try {
+		raw = readFileSync(eventsPath, "utf-8"); // guardrails-allow PREVENT-PI-004: local events.log read (loopback dashboard)
+	} catch {
+		return samples;
+	}
+	for (const line of raw.split("\n")) {
+		if (!line.includes('"prefix_stability"')) continue;
+		const obj = parseEventLine(line);
+		if (!obj) continue;
+		// Only rows we appended (event === "prefix_stability").
+		if (obj.event !== "prefix_stability") continue;
+		const ts = typeof obj.ts === "number" ? obj.ts : 0;
+		const stablePrefix = typeof obj.stablePrefix === "number" ? obj.stablePrefix : 0;
+		const totalMessages = typeof obj.totalMessages === "number" ? obj.totalMessages : 0;
+		const striping = typeof obj.striping === "string" ? obj.striping : "off";
+		const separation = typeof obj.separation === "string" ? obj.separation : "off";
+		samples.push({ ts, stablePrefix, totalMessages, separation, striping });
+	}
+	return samples.slice(-limit);
+}
+
+/** Classify the three-point trend across the returned window (head-mean vs tail-mean). */
+function classifyTrend(ratios: number[]): PrefixStabilityResponse["trend"] {
+	if (ratios.length < 3) return "stable";
+	const third = Math.max(1, Math.floor(ratios.length / 3));
+	const head = ratios.slice(0, third).reduce((a, b) => a + b, 0) / third;
+	const tail = ratios.slice(-third).reduce((a, b) => a + b, 0) / third;
+	const delta = tail - head;
+	if (delta > 0.05) return "improving";
+	if (delta < -0.05) return "degrading";
+	return "stable";
+}
+
+/** Positive sprint-flag check (matches sprintFlag: `=0`/`=false`/`_DISABLED=true` → OFF). */
+function prefixStabilityEnabled(): boolean {
+	const v = process.env.MEGACOMPACT_PC_C;
+	if (v === "0" || v === "false") return false;
+	const disabled = process.env.MEGACOMPACT_PC_C_DISABLED;
+	if (disabled === "true" || disabled === "1") return false;
+	return true;
+}
+
+export function handlePrefixStability(
+	req: IncomingMessage,
+	res: ServerResponse,
+	ctx: RouteContext,
+): boolean {
+	if (!req.url?.startsWith("/api/prefix-stability")) return false;
+	if (!prefixStabilityEnabled()) {
+		// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+		res.writeHead(404, { "Content-Type": "application/json" });
+		res.end(JSON.stringify({ error: "not_found" }));
+		return true;
+	}
+	if (req.method !== "GET") {
+		// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+		res.writeHead(405, { "Content-Type": "application/json" });
+		res.end(JSON.stringify({ error: "method_not_allowed" }));
+		return true;
+	}
+	let limit = 50;
+	if (req.url.includes("?")) {
+		const params = new URLSearchParams(req.url.slice(req.url.indexOf("?")));
+		const l = params.get("limit");
+		if (l != null) {
+			const n = parseInt(l, 10);
+			if (Number.isFinite(n) && n > 0) limit = Math.min(n, 500);
+		}
+	}
+	try {
+		const events = readPrefixStabilityEvents(ctx.eventsPath, limit);
+		const turns = events.map((e, i) => ({
+			turnIndex: i,
+			stablePrefix: e.stablePrefix,
+			totalMessages: e.totalMessages,
+			ratio: e.totalMessages > 0 ? e.stablePrefix / e.totalMessages : 0,
+			striping: e.striping,
+			timestamp: new Date(e.ts).toISOString(),
+		}));
+		const avgRatio = turns.length
+			? turns.reduce((a, t) => a + t.ratio, 0) / turns.length
+			: 0;
+		const body: PrefixStabilityResponse = {
+			turns,
+			avgRatio: Math.round(avgRatio * 1000) / 1000,
+			trend: classifyTrend(turns.map((t) => t.ratio)),
+			count: turns.length,
+			lastScanAt: Date.now(),
+		};
+		// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+		res.writeHead(200, { "Content-Type": "application/json" });
+		res.end(JSON.stringify(body));
+	} catch (e) {
+		// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+		res.writeHead(500, { "Content-Type": "application/json" });
+		res.end(JSON.stringify({ error: "prefix_stability_unavailable", detail: String(e) }));
+	}
+	return true;
+}

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

@@ -216,5 +216,11 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"Embedder-detect consolidation + VC9 workstream roll-up: memoizes /api/setup-detect against the mutable input (resolved binary path + mtime) so consecutive requests reuse the result without re-spawning, and unifies the embedder + cortex sub-tabs' 5s poll contract. OFF = byte-identical predecessor (VC9C-era): detect spawns fresh per request and the embedder poll keeps its previous cadence.",
 			true,
 		),
+		boolDirect(
+			"MEGACOMPACT_PC_C",
+			"PC-C Dashboard Cache Visibility",
+			"Dashboard per-turn prompt-cache visibility: surfaces the per-turn stable-prefix ratio trend (GET /api/prefix-stability) in the CacheTab PrefixStabilityCard. Reads aggregate ratios/counts from the local monitoring events log only — no payload bytes. OFF = byte-identical predecessor (PC-B-era): /api/prefix-stability returns 404 and the CacheTab omits the PrefixStabilityCard.",
+			true,
+		),
 	],
 };

package/extensions/dashboard-server/routes.ts

@@ -30,6 +30,7 @@ export {
 export { handleMemoryMap } from "./routes-memory-map.js";
 export { handleRaptorTree, handleRaptorBuildHistory } from "./routes-raptor.js";
 export { handleCacheStripes } from "./routes-cache.js";
+export { handlePrefixStability } from "./routes-prefix-stability.js";
 export {
 	handleContextHealth,
 	handleCachePoison,

package/extensions/mega-events/context-handler/tailResult.ts

@@ -87,7 +87,11 @@ export function buildTailResult(
 						}
 					}
 					lastTurnPrefix.set(runtime, { sessionId, turn, fingerprints });
-					runtime.logger.info("prefix_stability", {
+					// PC-C: write to the always-on monitoring events log (appendEvent),
+					// not the debug-gated runtime logger (mega-compact.log), so the
+					// dashboard /api/prefix-stability endpoint can read this per-turn
+					// stable-prefix ratio from ctx.eventsPath. Same field shape.
+					runtime.appendEvent("prefix_stability", {
 						stablePrefix,
 						totalMessages: result.length,
 						separation: config.messageSeparation ? "v2" : "off",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.32",
+  "version": "0.20.34",
   "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-pcc.ts

@@ -0,0 +1,32 @@
+/**
+ * config/vector-cortex-pcc.ts — PC-C dashboard prompt-cache visibility flag.
+ *
+ * Extracted from vector-cortex.ts so that file stays under the 300-line soft
+ * limit (soft-as-hard gate), exactly as the vector-cortex-vc9{a,b,c,d}.ts
+ * siblings were. This is the PC-C dashboard per-turn prefix-stability flag.
+ * 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: PCC_ENABLED is byte-identical in name,
+ * semantics, and default to the sprint-flag convention it follows, 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";
+
+/**
+ * PC-C — dashboard per-turn prefix-stability visibility. Default ON.
+ * `MEGACOMPACT_PC_C=0` disables and is byte-identical to the predecessor
+ * (PC-B-era): /api/prefix-stability returns 404/disabled and the CacheTab
+ * renders exactly as before (stripe distribution + hit-rate trend only). When
+ * ON, the endpoint surfaces the per-turn stable-prefix ratio trend from the
+ * `prefix_stability` events in the monitoring log. The response contains
+ * aggregate ratios/counts only, never message content (EVAL-REDACT-002), and
+ * reads only the local events log (PREVENT-PI-004). This flag MUST also be a
+ * dashboard SETTINGS toggle (visible in config UI, never in EXCLUDED_SETTINGS),
+ * mirroring the other PC/VC flags.
+ */
+export const PCC_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_PC_C");

package/src/config/vector-cortex.ts

@@ -280,9 +280,9 @@ export { VC9A_ENABLED } from "./vector-cortex-vc9a.js";
 export { VC9B_ENABLED } from "./vector-cortex-vc9b.js";
 export { VC9C_ENABLED } from "./vector-cortex-vc9c.js";
 export { VC9D_ENABLED } from "./vector-cortex-vc9d.js";
+export { PCC_ENABLED } from "./vector-cortex-pcc.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.
+// Breaker constants (TRIAD_RESILIENCE.md §breaker) extracted to vector-cortex-breakers.ts.
 export {
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,

package/src/config.ts

@@ -182,6 +182,7 @@ export {
   VC9B_ENABLED,
   VC9C_ENABLED,
   VC9D_ENABLED,
+  PCC_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

package/extensions/dashboard-client/dist/assets/CacheTab-C3KWDFDm.js

@@ -1,2 +0,0 @@
-import{j as e,r as h,u as j,A as L,D as $,z as H,l as M}from"./index-eoCm0uxj.js";import{C as I,T as k}from"./TimeSavedCard-CYltysD3.js";import{b as m,c as u,d as w,e as W,f as d}from"./format-COjDIVGj.js";import{l as D}from"./pricing-DkYp8-vi.js";import{C as g,a as f,b as C,c as S}from"./card-Ce58rSXG.js";import{B as _}from"./button-B_4j_PVR.js";function R(a){return a>=80?"ov-stat-value-green":a>=50?"ov-stat-value-yellow":"ov-stat-value-red"}function F(a){return a==null?"":a>=0?"ov-stat-value-green":"ov-stat-value-red"}function r({label:a,value:s,className:t,title:l}){return e.jsxs("div",{className:"flex items-baseline justify-between border-b border-border py-1 text-sm",children:[e.jsx("span",{className:"text-xs text-muted-foreground",title:l,children:a}),e.jsx("span",{className:`font-semibold${t?` ${t}`:""}`,children:s})]})}function O(a){return e.jsxs(g,{className:"electric-hover",children:[e.jsx(f,{children:e.jsx(C,{children:"Provider Prompt Cache"})}),e.jsxs(S,{children:[e.jsx(r,{label:"Cache Hit Rate",value:`${a.hitPct.toFixed(1)}%`,className:R(a.hitPct)}),e.jsx(r,{label:"Turns Recorded",value:String(a.turnCount)}),e.jsx(r,{label:"Cache Read Tokens",value:m(a.totalCacheRead)}),e.jsx(r,{label:"Cache Write Tokens",value:m(a.totalCacheWrite)}),e.jsx(r,{label:"Input Tokens",value:m(a.totalInput)}),e.jsx(r,{label:"$ Saved (reads)",value:u(a.cacheReadSaved)}),e.jsx(r,{label:"Write Investment",value:u(a.cacheWriteCost)}),e.jsx(r,{label:"Net Saved",value:u(a.netSaved),className:F(a.netSaved)}),e.jsx(r,{label:"Model",value:a.modelLabel??"—"}),e.jsx(r,{label:"Tracked Since",value:w(a.firstTurnAt)}),e.jsx(r,{label:"Last Updated",value:W(a.latestTurnAt)}),a.byModel.length>0&&e.jsxs(e.Fragment,{children:[e.jsx("div",{className:"mt-2 text-xs font-semibold text-muted-foreground",children:"Per Model"}),a.byModel.map(s=>{const t=D(s.model),l=t!=null?s.totalCacheRead/1e6*t:null,n=t!=null?s.totalCacheWrite/1e6*t:null;return e.jsxs("div",{className:"mt-2",children:[e.jsx(r,{label:"Model",value:s.model}),e.jsx(r,{label:"Hit Rate",value:`${s.hitPct.toFixed(1)}%`,className:R(s.hitPct)}),e.jsx(r,{label:"Cache Read",value:m(s.totalCacheRead)}),e.jsx(r,{label:"Cache Write",value:m(s.totalCacheWrite)}),e.jsx(r,{label:"Samples",value:String(s.sampleCount)}),e.jsx(r,{label:"$ Saved (reads)",value:l!=null?u(l):"—"}),e.jsx(r,{label:"Write Investment",value:n!=null?u(n):"—"})]},s.model)})]})]})]})}const G=["ov-bar-green","ov-bar-blue","ov-bar-teal","ov-bar-yellow","ov-bar-gray"],B=["Permanent","Epoch","Topic","Thread","Volatile"],z={good:"ov-text-green",fair:"ov-text-yellow",degraded:"ov-text-orange",poor:"ov-text-red"};function K({data:a}){const s=Math.max(...a.buckets.map(l=>l.count),1),t=z[a.health.label]??"ov-text-gray";return e.jsxs("div",{className:"ov-card",children:[e.jsx("h3",{className:"ov-card-title",children:"Cache Stripe Distribution"}),e.jsxs("div",{className:"ov-stripe-health-summary",children:[e.jsx("span",{className:`ov-stripe-health-badge ${t}`,children:a.health.label}),e.jsx("span",{className:"ov-stripe-health-score",children:d(a.health.score)}),e.jsxs("span",{className:"ov-stripe-churn",children:["Churn: ",d(a.health.churnRate)]}),e.jsxs("span",{className:"ov-stripe-total",children:[a.totalChunks," total chunks"]})]}),e.jsx("div",{className:"ov-stripe-bars",children:a.buckets.map(l=>{const n=s>0?Math.max(0,Math.min(100,l.count/s*100)):0,o=G[l.stripe]??"ov-bar-gray",c=l.label||(B[l.stripe]??`Stripe ${l.stripe}`);return e.jsxs("div",{className:"ov-stripe-row",children:[e.jsx("span",{className:"ov-stripe-label",title:c,children:c}),e.jsx("div",{className:"ov-bar-track",children:e.jsx("div",{className:`ov-bar-fill ${o}`,style:{width:`${n}%`}})}),e.jsx("span",{className:"ov-stripe-count",children:l.count}),e.jsx("span",{className:"ov-stripe-stability",title:`min ${d(l.minStability)} / max ${d(l.maxStability)}`,children:d(l.avgStability)})]},l.stripe)})}),e.jsxs("div",{className:"ov-stripe-footer",children:["Epoch: ",a.epochId??"—","· Dominant tier: ",d(a.health.dominantTier)]})]})}function x(a){return`${a.toFixed(1)}%`}function U(a){return a>=80?"ov-bar-green":a>=60?"ov-bar-teal":a>=40?"ov-bar-yellow":a>=20?"ov-bar-orange":"ov-bar-red"}const V=({perf:a})=>{const{cache_hit_pct:s}=a,t=s.samples&&s.samples.length>0?s.samples:[];return e.jsxs(g,{className:"electric-hover",children:[e.jsx(f,{children:e.jsx(C,{children:"Cache Hit-Rate Trend"})}),e.jsxs(S,{children:[e.jsxs("div",{className:"mb-3 flex gap-4 text-sm text-muted-foreground",children:[e.jsxs("div",{children:["Avg: ",e.jsx("strong",{className:"text-foreground",children:x(s.avg)})]}),e.jsxs("div",{children:["Latest: ",e.jsx("strong",{className:"text-foreground",children:x(s.latest)})]}),e.jsxs("div",{children:["Samples: ",e.jsx("strong",{className:"text-foreground",children:s.n})]})]}),t.length>0?e.jsxs(e.Fragment,{children:[e.jsx("div",{className:"ov-sparkline",role:"img","aria-label":`Cache hit rate trend: ${s.n} samples, average ${x(s.avg)}, latest ${x(s.latest)}`,children:t.map((l,n)=>{const o=Math.max(2,Math.round(l.pct*.6)),c=U(l.pct),v=n===t.length-1;return e.jsx("div",{className:`ov-sparkline-bar ${c}${v?" ov-bar-latest":""}`,style:{height:`${o}px`},title:`${x(l.pct)} at ${new Date(l.ts).toLocaleTimeString()}`},n)})}),e.jsxs("div",{className:"mt-1 text-xs text-muted-foreground",children:[t.length," sample",t.length!==1?"s":""," over"," ",t.length>1?`${Math.round((t[t.length-1].ts-t[0].ts)/1e3)}s`:"latest turn"]})]}):e.jsx("div",{className:"text-sm text-muted-foreground",children:"No cache-hit samples yet"})]})]})};function ee(){const[a,s]=h.useState(!1),{data:t,loading:l,error:n}=j(h.useCallback(()=>L(),[]),{pollInterval:5e3}),{data:o,loading:c,error:v}=j(h.useCallback(()=>$(),[]),{pollInterval:15e3}),{data:N,loading:A,error:T}=j(h.useCallback(()=>H({minutes:30}),[]),{pollInterval:15e3}),{data:i,loading:E,error:y}=j(h.useCallback(()=>M(),[]),{pollInterval:5e3});return e.jsxs("div",{className:"flex flex-col gap-4",children:[e.jsxs("div",{children:[e.jsx(_,{type:"button",variant:"outline",onClick:()=>s(!a),children:a?"Hide Guidance":"Show Cache-Friendly Prompt Ordering Guidance"}),a&&e.jsxs(g,{className:"mt-3",children:[e.jsx(f,{children:e.jsx(C,{children:"Cache-Friendly Prompt Ordering"})}),e.jsxs(S,{children:[e.jsxs("ul",{className:"list-disc space-y-1 pl-5",children:[e.jsx("li",{children:"Keep system prompts and stable context at the top of your conversation — the provider caches the leading prefix."}),e.jsxs("li",{children:["Tool results and volatile content are automatically moved to the tail by message separation (",e.jsx("code",{children:"MEGACOMPACT_MESSAGE_SEPARATION"}),") so they don't invalidate the cache prefix."]}),e.jsxs("li",{children:["Cache striping (",e.jsx("code",{children:"MEGACOMPACT_CACHE_STRIPING"}),") further orders stable context by a stability score so the most durable chunks lead."]}),e.jsx("li",{children:"Avoid inserting new instructions mid-conversation — prepend them instead."})]}),i&&e.jsxs("div",{className:"mt-2 text-sm",children:[e.jsx("strong",{children:"Status:"})," ",i.config.auto?"Auto-compaction Enabled":"Auto-compaction Disabled"," |"," ","fast-gate ",i.config.fastGatePct,"% / threshold"," ",i.config.thresholdTokens.toLocaleString()," tokens"]})]})]})]}),e.jsx("h2",{className:"font-heading text-lg font-semibold",children:"Provider Prompt Cache"}),l?e.jsx("p",{className:"tab-stub",children:"Loading..."}):n?e.jsxs("p",{className:"tab-stub",children:["Provider cache unavailable: ",n.message]}):t?e.jsx(O,{hitPct:t.cache.avgHitPct,turnCount:t.cache.turnCount,totalCacheRead:t.cache.totalCacheRead,totalCacheWrite:t.cache.totalCacheWrite,totalInput:t.cache.totalInput,cacheReadSaved:t.savings?.cacheReadSaved??null,cacheWriteCost:t.savings?.cacheWriteCost??null,netSaved:t.savings?.netSaved??null,modelLabel:t.savings?.model??null,firstTurnAt:t.cache.firstTurnAt,latestTurnAt:t.cache.latestTurnAt,byModel:t.cache.byModel??[]}):null,e.jsx("h2",{className:"font-heading text-lg font-semibold",children:"Cache Stripe Distribution"}),c?e.jsx("p",{className:"tab-stub",children:"Loading..."}):v?e.jsxs("p",{className:"tab-stub",children:["Cache stripe data unavailable: ",v.message]}):o?e.jsx(K,{data:o}):null,e.jsx("h2",{className:"font-heading text-lg font-semibold",children:"Cache Hit-Rate Trend"}),A?e.jsx("p",{className:"tab-stub",children:"Loading..."}):T?e.jsxs("p",{className:"tab-stub",children:["Hit-rate trend unavailable: ",T.message]}):N?e.jsx(V,{perf:N}):null,e.jsx("h2",{className:"font-heading text-lg font-semibold",children:"Mega-Compact Dedup Cache"}),E?e.jsx("p",{className:"tab-stub",children:"Loading..."}):y?e.jsxs("p",{className:"tab-stub",children:["Snapshot unavailable: ",y.message]}):i&&(()=>{const{cacheHits:p,compacts:P,timeSaved:b}=i;return e.jsxs("div",{className:"grid grid-cols-1 gap-4 md:grid-cols-2 xl:grid-cols-3",children:[e.jsx(I,{cacheHitsSession:p.session,cacheHitsTotal:p.total,tokensSavedSession:p.sessionTokensSaved,tokensSavedTotal:p.totalTokensSaved,compactionsSession:P.session,compactionsTotal:P.total}),e.jsx(k,{compactSessionSec:b.compact.sessionSec,compactTotalSec:b.compact.totalSec,cacheHitSessionSec:b.cacheHit.sessionSec,cacheHitTotalSec:b.cacheHit.totalSec})]})})()]})}export{ee as default};
-//# sourceMappingURL=CacheTab-C3KWDFDm.js.map