From db86285444aab921663eb1dfce5c84c554204c94 Mon Sep 17 00:00:00 2001
From: Adam Malczewski <github@tradam.dev>
Date: Thu, 11 Jun 2026 16:06:48 +0900
Subject: feat(cache-warming,surfaces,metrics,markdown): conversation-scoped
 surfaces, cache warming + retention, markdown

Consumes the backend cache-warming + cache-rate handoffs end-to-end and adds supporting infra:

- protocol/transport: conversation-scoped surfaces (conversationId on subscribe/invoke/surface + staleness routing); store auto-subscribes the catalog with the focused conversation and re-scopes on switch.
- surface-host: generic Number field renderer + custom rendererId dispatch (graceful skip on unknown).
- cache-warming feature: enabled toggle, min+sec interval, AUTHORITATIVE countdown from the surface's cache-warming-timer nextWarmAt, manual Warm now (POST /chat/warm), lastWarmAt-keyed history, cache-retention stat, expectedCacheRate headline.
- metrics: cross-turn expected-cache (retention) derivation + bubble badge; cache-rate fix needs no code change (inputTokens now total).
- markdown feature: marked + marked-highlight + highlight.js + dompurify, rendered in ChatView.
- fixes (gemini review): {#key activeConversationId} remount of CacheWarmingView to stop history/feedback leaking across tabs; guard NaN interval inputs from committing 0.
- docs/contracts: regenerated transport/ui-contract mirrors; backend-handoff updated (CR-3 resolved).

Verified: svelte-check 0 errors, biome clean, 494 tests pass, vite build OK.
---
 src/core/metrics/format.test.ts | 59 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

(limited to 'src/core/metrics/format.test.ts')

diff --git a/src/core/metrics/format.test.ts b/src/core/metrics/format.test.ts
index 77c5204..3eec93d 100644
--- a/src/core/metrics/format.test.ts
+++ b/src/core/metrics/format.test.ts
@@ -2,8 +2,10 @@ import type { StepId, StepMetrics, TurnMetrics } from "@dispatch/wire";
 import { describe, expect, it } from "vitest";
 import {
 	computeCachePct,
+	computeExpectedCachePct,
 	computeTps,
 	viewCacheRate,
+	viewExpectedCache,
 	viewStepMetrics,
 	viewTurnMetrics,
 } from "./format";
@@ -249,3 +251,60 @@ describe("viewCacheRate", () => {
 		expect(miss.isHit).toBe(false);
 	});
 });
+
+describe("computeExpectedCachePct", () => {
+	it("null when there is no prior turn (first turn has no baseline)", () => {
+		expect(computeExpectedCachePct({ inputTokens: 100, outputTokens: 0 }, null)).toBeNull();
+	});
+
+	it("null when the prior turn cached nothing (denominator 0)", () => {
+		const prev = { inputTokens: 100, outputTokens: 0 };
+		const current = { inputTokens: 200, outputTokens: 0, cacheReadTokens: 50 };
+		expect(computeExpectedCachePct(current, prev)).toBeNull();
+	});
+
+	it("100% when the whole prior cached prefix was read back (backend worked example)", () => {
+		// turn 1: cacheRead 0, cacheWrite 5146 → prefix 5146; turn 2 reads 5146 back.
+		const prev = { inputTokens: 5149, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 5146 };
+		const current = {
+			inputTokens: 8462,
+			outputTokens: 0,
+			cacheReadTokens: 5146,
+			cacheWriteTokens: 3313,
+		};
+		expect(computeExpectedCachePct(current, prev)).toBe(100);
+	});
+
+	it("drops below 100% when the cache busted (read < prior prefix)", () => {
+		const prev = {
+			inputTokens: 1000,
+			outputTokens: 0,
+			cacheReadTokens: 100,
+			cacheWriteTokens: 900,
+		};
+		const current = { inputTokens: 1000, outputTokens: 0, cacheReadTokens: 500 };
+		// 500 / (100 + 900) = 50%
+		expect(computeExpectedCachePct(current, prev)).toBe(50);
+	});
+
+	it("clamps to 100 if read somehow exceeds the prior prefix", () => {
+		const prev = { inputTokens: 100, outputTokens: 0, cacheWriteTokens: 100 };
+		const current = { inputTokens: 100, outputTokens: 0, cacheReadTokens: 250 };
+		expect(computeExpectedCachePct(current, prev)).toBe(100);
+	});
+});
+
+describe("viewExpectedCache", () => {
+	it("null view when it cannot be derived (no prior turn)", () => {
+		expect(viewExpectedCache({ inputTokens: 100, outputTokens: 0 }, null)).toBeNull();
+	});
+
+	it("success level + hit flag for full retention", () => {
+		const prev = { inputTokens: 5149, outputTokens: 0, cacheWriteTokens: 5146 };
+		const current = { inputTokens: 8462, outputTokens: 0, cacheReadTokens: 5146 };
+		const v = viewExpectedCache(current, prev);
+		expect(v?.pct).toBe(100);
+		expect(v?.level).toBe("success");
+		expect(v?.isHit).toBe(true);
+	});
+});
-- 
cgit v1.2.3