dsh-context 0.22.0 → 0.22.2

package/lib/index.js

@@ -1,697 +1,807 @@
-// src/host/config.ts
 import { z } from "zod";
-var DEFAULT_BOUNDS = {
-  maxRequestSteps: 1500,
-  maxKeptTurns: 300,
-  maxEvents: 400,
-  maxNodes: 2e3,
-  maxArchiveNodes: 400
+import { deriveEventMessage } from "@deepseek-ai/dsh-session";
+//#region src/host/config.ts
+/**
+* dsh-context host configuration — the `config:` block of the `dsh-context`
+* loader row in cordis.yml.
+*
+* Cordis validates the entry config against this exported `Config` schema
+* (any Standard Schema v1 validator — zod is ours) before `apply` runs, fills
+* per-field defaults, and fails the load loudly on invalid or unknown keys
+* (`.strict()`). The official plugin-config principle this answers: "anything
+* that two deployments may want to set differently is a configuration field".
+*
+* The persisted projection state shape is independent of these bounds — they
+* only tune the fold's retention / presentation slice, so changing them never
+* requires a projection `stateVersion` bump.
+*/
+/** Defaults — the exact bounds the fold used before they became configurable. */
+const DEFAULT_BOUNDS = {
+	maxRequestSteps: 1500,
+	maxKeptTurns: 300,
+	maxEvents: 400,
+	maxNodes: 2e3,
+	maxArchiveNodes: 400
 };
-var Config = z.preprocess(
-  (v) => v ?? {},
-  z.object({
-    maxRequestSteps: z.number().int().min(1).default(DEFAULT_BOUNDS.maxRequestSteps),
-    maxKeptTurns: z.number().int().min(1).default(DEFAULT_BOUNDS.maxKeptTurns),
-    maxEvents: z.number().int().min(1).default(DEFAULT_BOUNDS.maxEvents),
-    maxNodes: z.number().int().min(1).default(DEFAULT_BOUNDS.maxNodes),
-    maxArchiveNodes: z.number().int().min(1).default(DEFAULT_BOUNDS.maxArchiveNodes)
-  }).strict()
-);
+/**
+* The cordis `Config` validator: strict on keys, defaults on the schema fields.
+* Tolerates `undefined` (a patch row without a `config:` block — defaults win).
+*/
+const Config = z.preprocess((v) => v ?? {}, z.object({
+	maxRequestSteps: z.number().int().min(1).default(DEFAULT_BOUNDS.maxRequestSteps),
+	maxKeptTurns: z.number().int().min(1).default(DEFAULT_BOUNDS.maxKeptTurns),
+	maxEvents: z.number().int().min(1).default(DEFAULT_BOUNDS.maxEvents),
+	maxNodes: z.number().int().min(1).default(DEFAULT_BOUNDS.maxNodes),
+	maxArchiveNodes: z.number().int().min(1).default(DEFAULT_BOUNDS.maxArchiveNodes)
+}).strict());
+/** Validate (and default) the entry config into concrete fold bounds. */
 function resolveBounds(config) {
-  return Config.parse(config ?? {});
+	return Config.parse(config ?? {});
 }
-
-// src/host/headers.ts
-import { z as z2 } from "zod";
-
-// src/host/pricing.ts
-var CHARS_PER_TOKEN = 4;
-var BLOCK_OVERHEAD = 4;
-var ROLE_OVERHEAD = 4;
+//#endregion
+//#region src/host/pricing.ts
+/**
+* Token pricing — the same fixed-density heuristic as the harness's own
+* token-meter (`dsh-token-meter/estimate.ts`): ~4 chars ≈ 1 token, +4 per
+* content block, +4 role framing. Pure functions over message payloads.
+*/
+const CHARS_PER_TOKEN = 4;
+const BLOCK_OVERHEAD = 4;
+const ROLE_OVERHEAD = 4;
+/** Whole-array tool-schema price (the header's tools total). */
 function estimateToolsTotal(tools) {
-  return tools.length > 0 ? Math.ceil(JSON.stringify(tools).length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD : 0;
+	return tools.length > 0 ? Math.ceil(JSON.stringify(tools).length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD : 0;
 }
 function estimateBlocks(blocks) {
-  let tokens = 0;
-  if (!Array.isArray(blocks)) return 0;
-  for (const block of blocks) {
-    if (block === null || typeof block !== "object") continue;
-    switch (block.type) {
-      case "text":
-      case "reasoning":
-        tokens += Math.ceil(String(block.text || "").length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD;
-        break;
-      case "tool-call":
-        tokens += Math.ceil(String(block.name || "").length / CHARS_PER_TOKEN) + Math.ceil(String(block.arguments || "").length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD;
-        break;
-      case "tool-result":
-        tokens += estimateBlocks(block.content) + BLOCK_OVERHEAD;
-        break;
-      default:
-        tokens += BLOCK_OVERHEAD + Math.ceil(JSON.stringify(block).length / CHARS_PER_TOKEN);
-    }
-  }
-  return tokens;
+	let tokens = 0;
+	if (!Array.isArray(blocks)) return 0;
+	for (const block of blocks) switch (block.type) {
+		case "text":
+		case "reasoning":
+			tokens += Math.ceil((block.text || "").length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD;
+			break;
+		case "tool-call":
+			tokens += Math.ceil((block.name || "").length / CHARS_PER_TOKEN) + Math.ceil((block.arguments || "").length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD;
+			break;
+		case "tool-result":
+			tokens += estimateBlocks(block.content) + BLOCK_OVERHEAD;
+			break;
+		default: tokens += BLOCK_OVERHEAD + Math.ceil(JSON.stringify(block).length / CHARS_PER_TOKEN);
+	}
+	return tokens;
 }
+/**
+* Price one surface message exactly like dsh's token-meter estimate:
+* an empty-content assistant/message projects to NO message (it only hosts
+* usage), so it prices 0; every other message pays content + role framing.
+*/
 function estimateMessage(message, emptyIsZero = false) {
-  if (emptyIsZero && (message === null || message === void 0 || !Array.isArray(message.content) || message.content.length === 0)) {
-    return 0;
-  }
-  return estimateBlocks(message?.content) + ROLE_OVERHEAD;
+	if (emptyIsZero && (message === null || message === void 0 || !Array.isArray(message.content) || message.content.length === 0)) return 0;
+	return estimateBlocks(message?.content) + ROLE_OVERHEAD;
 }
 function estimateSystem(text) {
-  if (typeof text !== "string" || text.length === 0) return 0;
-  return Math.ceil(text.length / CHARS_PER_TOKEN) + ROLE_OVERHEAD;
+	if (typeof text !== "string" || text.length === 0) return 0;
+	return Math.ceil(text.length / CHARS_PER_TOKEN) + ROLE_OVERHEAD;
 }
+/** Per-tool price for the top-tools display (the total uses dsh's whole-array price). */
 function estimateToolSchema(tool) {
-  return Math.ceil(JSON.stringify(tool).length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD;
+	return Math.ceil(JSON.stringify(tool).length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD;
 }
 function firstText(blocks) {
-  if (!Array.isArray(blocks)) return "";
-  for (const b of blocks) {
-    if (b && b.type === "text" && typeof b.text === "string" && b.text.trim() !== "") {
-      return b.text.replace(/\s+/g, " ").trim().slice(0, 80);
-    }
-  }
-  return "";
+	if (!Array.isArray(blocks)) return "";
+	for (const b of blocks) if (b.type === "text" && typeof b.text === "string" && b.text.trim() !== "") return b.text.replace(/\s+/g, " ").trim().slice(0, 80);
+	return "";
 }
 function toolCallNames(blocks) {
-  const names = [];
-  if (!Array.isArray(blocks)) return names;
-  for (const b of blocks) {
-    if (b && b.type === "tool-call" && typeof b.name === "string") names.push(b.name);
-  }
-  return names;
+	const names = [];
+	if (!Array.isArray(blocks)) return names;
+	for (const b of blocks) if (b.type === "tool-call" && typeof b.name === "string") names.push(b.name);
+	return names;
 }
 function isInjection(source) {
-  return source !== null && typeof source === "object" && (source.kind === "plugin" || source.kind === "skill-invocation" || typeof source.form === "string");
+	return source !== null && source !== void 0 && (source.kind === "plugin" || source.kind === "skill-invocation" || typeof source.form === "string");
 }
-
-// src/host/headers.ts
-var HEADERS_MAX = 50;
-var headerToolSchema = z2.object({
-  name: z2.string(),
-  tokens: z2.number().int().nonnegative(),
-  description: z2.string().optional(),
-  schema: z2.unknown().optional()
-}).strict();
-var contextHeadersSchema = z2.object({
-  headers: z2.array(z2.object({
-    seq: z2.number(),
-    time: z2.number(),
-    system: z2.string().optional(),
-    tools: z2.array(headerToolSchema)
-  }).strict())
+//#endregion
+//#region src/host/headers.ts
+/**
+* The `contextHeaders` session projection unit — the request-header CONTENT
+* epochs behind the timeline's envelope figures.
+*
+* The hot `contextTimeline` unit carries only token prices of the system
+* prompt and tool schemas; this companion unit keeps the CONTENT (full
+* system prompt text, full tool JSON schemas) so the Context browser card
+* can show what a picked step's request was actually assembled from. It is
+* a separate unit on purpose: the agent loop logs `request/header` only
+* when the header changes, so this state (and its pushes to the browser)
+* moves rarely — carrying full content costs nothing on the per-event hot
+* path.
+*
+* Same projection contract as the timeline unit: pure init/apply/view,
+* `Object.is` reference stability for uninteresting events, plain-JSON
+* bounded state (epoch list capped — see HEADERS_MAX).
+*/
+/** Retention cap on header epochs (changes are rare; 50 is generous). */
+const HEADERS_MAX = 50;
+const headerToolSchema = z.object({
+	name: z.string(),
+	tokens: z.number().int().nonnegative(),
+	description: z.string().optional(),
+	schema: z.unknown().optional()
 }).strict();
-var contextHeadersStateSchema = contextHeadersSchema;
+const contextHeadersSchema = z.object({ headers: z.array(z.object({
+	seq: z.number(),
+	time: z.number(),
+	system: z.string().optional(),
+	tools: z.array(headerToolSchema)
+}).strict()) }).strict();
+/**
+* The persisted state and the wire view are the same shape here (the view
+* only shallow-copies each record), so one schema validates both under the
+* dsh 0.1.1-rc.1+ `stateSchema`/`wire` contract.
+*/
+const contextHeadersStateSchema = contextHeadersSchema;
+/** Fold one `request/header` payload into an epoch record (display-priced). */
 function recordOf(event) {
-  if (event.type !== "request/header") return null;
-  const header = event.data.header;
-  if (header === null || typeof header !== "object") return null;
-  const tools = Array.isArray(header.tools) ? header.tools : [];
-  const record = {
-    seq: event.seq,
-    time: event.time,
-    tools: tools.map((t) => {
-      const tool = t;
-      const entry = {
-        name: typeof tool.name === "string" ? tool.name : "?",
-        tokens: estimateToolSchema(t),
-        schema: t
-      };
-      if (typeof tool.description === "string" && tool.description !== "") {
-        entry.description = tool.description;
-      }
-      return entry;
-    })
-  };
-  if (typeof header.system === "string" && header.system.length > 0) {
-    record.system = header.system;
-  }
-  return record;
+	if (event.type !== "request/header") return null;
+	const rawHeader = event.data.header;
+	if (rawHeader === null || rawHeader === void 0 || typeof rawHeader !== "object") return null;
+	const header = rawHeader;
+	const tools = Array.isArray(header.tools) ? header.tools : [];
+	const record = {
+		seq: event.seq,
+		time: event.time,
+		tools: tools.map((t) => {
+			const tool = t;
+			const entry = {
+				name: typeof tool.name === "string" ? tool.name : "?",
+				tokens: estimateToolSchema(t),
+				schema: t
+			};
+			if (typeof tool.description === "string" && tool.description !== "") entry.description = tool.description;
+			return entry;
+		})
+	};
+	if (typeof header.system === "string" && header.system.length > 0) record.system = header.system;
+	return record;
 }
+/**
+* The context-headers projection unit. Registered alongside the timeline
+* unit (host/index.ts); clients read it through `useProjection('contextHeaders')`
+* and degrade to tokens-only header sections when the key is absent.
+*
+* Dual-contract definition (see compat.ts): `schema`/`view` for
+* dsh <= 0.1.0-rc.8, `stateSchema`/`wire` for dsh >= 0.1.1-rc.1. Without
+* `wire`, the 0.1.1-rc.1+ registry treats the unit as host-only and the
+* Context browser's system/tools sections would degrade.
+*/
 function createContextHeadersDefinition() {
-  const view = (state) => ({
-    headers: state.headers.map((h) => ({ ...h, tools: h.tools.map((t) => ({ ...t })) }))
-  });
-  const definition = {
-    key: "contextHeaders",
-    // dsh <= 0.1.0-rc.8 contract: one schema validates the wire payload, `view` is top-level.
-    schema: contextHeadersSchema,
-    view,
-    // dsh >= 0.1.1-rc.1 contract: `stateSchema` validates persisted state, the client view lives in `wire`.
-    stateSchema: contextHeadersStateSchema,
-    wire: { viewSchema: contextHeadersSchema, view },
-    init: () => ({ headers: [] }),
-    apply: (state, event) => {
-      const record = recordOf(event);
-      if (record === null) return state;
-      const last = state.headers[state.headers.length - 1];
-      if (last !== void 0 && last.seq === record.seq) return state;
-      const headers = [...state.headers, record];
-      return { headers: headers.length > HEADERS_MAX ? headers.slice(-HEADERS_MAX) : headers };
-    },
-    stateVersion: 1
-  };
-  return definition;
+	const view = (state) => ({ headers: state.headers.map((h) => ({
+		...h,
+		tools: h.tools.map((t) => ({ ...t }))
+	})) });
+	return {
+		key: "contextHeaders",
+		schema: contextHeadersSchema,
+		view,
+		stateSchema: contextHeadersStateSchema,
+		wire: {
+			viewSchema: contextHeadersSchema,
+			view
+		},
+		init: () => ({ headers: [] }),
+		apply: (state, event) => {
+			const record = recordOf(event);
+			if (record === null) return state;
+			const last = state.headers.at(-1);
+			if (last !== void 0 && last.seq === record.seq) return state;
+			const headers = [...state.headers, record];
+			return { headers: headers.length > HEADERS_MAX ? headers.slice(-50) : headers };
+		},
+		stateVersion: 1
+	};
 }
-
-// src/host/timeline.ts
-import { z as z3 } from "zod";
-
-// src/host/fold.ts
-import { deriveEventMessage } from "@deepseek-ai/dsh-session";
+//#endregion
+//#region src/host/fold.ts
+/** Keep only the trailing `maxTurns` turn-runs of a request timeline. */
 function trimToLastTurns(requests, maxTurns) {
-  let runs = 0;
-  let start = requests.length;
-  let prevTurn;
-  for (let i = requests.length - 1; i >= 0; i--) {
-    const turn = requests[i].turn;
-    if (turn !== prevTurn) {
-      if (runs >= maxTurns) break;
-      runs++;
-      prevTurn = turn;
-    }
-    start = i;
-  }
-  return requests.slice(start);
+	let runs = 0;
+	let start = requests.length;
+	let prevTurn;
+	for (let i = requests.length - 1; i >= 0; i--) {
+		const turn = requests[i].turn;
+		if (turn !== prevTurn) {
+			if (runs >= maxTurns) break;
+			runs++;
+			prevTurn = turn;
+		}
+		start = i;
+	}
+	return requests.slice(start);
 }
+/** Distinct turn runs in a request timeline (consecutive equal-turn runs). */
 function countTurnRuns(requests) {
-  let runs = 0;
-  let prevTurn;
-  for (const r of requests) {
-    if (r.turn !== prevTurn) {
-      runs++;
-      prevTurn = r.turn;
-    }
-  }
-  return runs;
+	let runs = 0;
+	let prevTurn;
+	for (const r of requests) if (r.turn !== prevTurn) {
+		runs++;
+		prevTurn = r.turn;
+	}
+	return runs;
 }
+/** Retain the newest tail of the two unbounded lists (bounded persisted state). */
 function trimState(st, bounds) {
-  if (countTurnRuns(st.requests) > bounds.maxKeptTurns) {
-    st.requests = trimToLastTurns(st.requests, bounds.maxKeptTurns);
-  }
-  if (st.requests.length > bounds.maxRequestSteps) {
-    st.requests = st.requests.slice(-bounds.maxRequestSteps);
-  }
-  if (st.events.length > bounds.maxEvents) st.events = st.events.slice(-bounds.maxEvents);
-  if (st.archived.length > 0) {
-    let drop = 0;
-    const oldestReq = st.requests.length > 0 ? st.requests[0].seq : void 0;
-    if (oldestReq !== void 0) {
-      while (drop < st.archived.length && (st.archived[drop].gone ?? Infinity) <= oldestReq) drop++;
-    }
-    if (st.archived.length - drop > bounds.maxArchiveNodes) {
-      drop = st.archived.length - bounds.maxArchiveNodes;
-    }
-    if (drop > 0) {
-      const floor = st.archived[drop - 1].gone;
-      if (floor !== void 0) st.archiveFloor = Math.max(st.archiveFloor ?? 0, floor);
-      st.archived = st.archived.slice(drop);
-    }
-  }
+	if (countTurnRuns(st.requests) > bounds.maxKeptTurns) st.requests = trimToLastTurns(st.requests, bounds.maxKeptTurns);
+	if (st.requests.length > bounds.maxRequestSteps) st.requests = st.requests.slice(-bounds.maxRequestSteps);
+	if (st.events.length > bounds.maxEvents) st.events = st.events.slice(-bounds.maxEvents);
+	if (st.archived.length > 0) {
+		let drop = 0;
+		const oldestReq = st.requests.length > 0 ? st.requests[0].seq : void 0;
+		if (oldestReq !== void 0) while (drop < st.archived.length && (st.archived[drop].gone ?? Infinity) <= oldestReq) drop++;
+		if (st.archived.length - drop > bounds.maxArchiveNodes) drop = st.archived.length - bounds.maxArchiveNodes;
+		if (drop > 0) {
+			const floor = st.archived[drop - 1].gone;
+			if (floor !== void 0) st.archiveFloor = Math.max(st.archiveFloor ?? 0, floor);
+			st.archived = st.archived.slice(drop);
+		}
+	}
 }
 function createTimelineState() {
-  return {
-    surface: [],
-    sums: { user: 0, inject: 0, assistant: 0, tool: 0 },
-    systemTokens: 0,
-    toolsTokens: 0,
-    toolList: [],
-    requests: [],
-    events: [],
-    archived: [],
-    callNames: {}
-  };
+	return {
+		surface: [],
+		sums: {
+			user: 0,
+			inject: 0,
+			assistant: 0,
+			tool: 0
+		},
+		systemTokens: 0,
+		toolsTokens: 0,
+		toolList: [],
+		requests: [],
+		events: [],
+		archived: [],
+		callNames: {}
+	};
 }
 function categoryOf(type, message) {
-  if (type === "assistant/message") return "assistant";
-  if (type === "tool/result") return "tool";
-  if (isInjection(message?.source)) return "inject";
-  return "user";
+	if (type === "assistant/message") return "assistant";
+	if (type === "tool/result") return "tool";
+	if (isInjection(message?.source)) return "inject";
+	return "user";
 }
+/**
+* Archive removed surface nodes as stamped COPIES — the objects leaving
+* `st.surface` are shared with the persisted previous state, so `gone` must
+* never be written onto them directly.
+*/
 function archiveRemoved(st, removed, goneSeq) {
-  for (const n of removed) st.archived.push({ ...n, gone: goneSeq });
+	for (const n of removed) st.archived.push({
+		...n,
+		gone: goneSeq
+	});
 }
 function applySurface(st, ev, type, data, message) {
-  const cat = categoryOf(type, message ?? void 0);
-  const node = {
-    seq: ev.seq,
-    time: ev.time,
-    cat,
-    // Empty assistant messages project to no model message (usage-only), so
-    // they price 0 — `deriveEventMessage` returns null for that case, and
-    // `estimateMessage(null, true)` short-circuits before ROLE_OVERHEAD.
-    tokens: estimateMessage(message, type === "assistant/message")
-  };
-  const source = message?.source;
-  const form = source?.form;
-  if (typeof form === "string") node.form = form;
-  if (type === "assistant/message") {
-    const text = firstText(message?.content);
-    if (text !== "") node.text = text;
-    else {
-      const names = toolCallNames(message?.content);
-      if (names.length > 0) node.calls = names.slice(0, 3);
-    }
-  } else if (type === "tool/result") {
-    const srcId = source?.callId;
-    const srcName = typeof srcId === "string" ? st.callNames[srcId] : void 0;
-    const block = message?.content?.[0];
-    const blockId = block?.toolCallId;
-    if (srcName) node.tool = srcName;
-    else if (typeof blockId === "string") node.tool = st.callNames[blockId];
-    if (data?.error) node.err = true;
-  } else if (source?.kind === "skill-invocation") {
-    node.skill = typeof source.name === "string" ? source.name : "?";
-  } else if (source?.kind === "plugin") {
-    if (source.form === "notice" && typeof source.summary === "string") node.text = source.summary;
-    else if (source.form === "snapshot" && Array.isArray(source.sections)) {
-      node.text = source.sections.map((s) => s?.name).filter(Boolean).join(", ").slice(0, 80);
-    } else {
-      const ptext = firstText(message?.content);
-      if (ptext !== "") node.text = ptext;
-    }
-  } else {
-    const utext = firstText(message?.content);
-    if (utext !== "") node.text = utext;
-  }
-  const shadowedSeqs = st.pendingShadowedSeqs;
-  delete st.pendingShadowedSeqs;
-  const op = ev.surfaceOp;
-  if (op !== null && typeof op === "object" && op.op === "replace") {
-    if (Array.isArray(shadowedSeqs) && shadowedSeqs.length > 0) {
-      const shadowed = new Set(shadowedSeqs);
-      const kept = [];
-      const removed = [];
-      for (const n of st.surface) {
-        if (shadowed.has(n.seq)) {
-          st.sums[n.cat] -= n.tokens;
-          removed.push(n);
-        } else kept.push(n);
-      }
-      archiveRemoved(st, removed, ev.seq);
-      st.surface = kept;
-      st.sums[cat] += node.tokens;
-      st.surface.push(node);
-      return node;
-    }
-    let si = -1;
-    let ei = -1;
-    for (let i = 0; i < st.surface.length; i++) {
-      if (si < 0 && st.surface[i].seq === op.start) si = i;
-      if (st.surface[i].seq === op.end) {
-        ei = i;
-        break;
-      }
-    }
-    if (si >= 0 && ei >= si) {
-      const removed = st.surface.splice(si, ei - si + 1, node);
-      archiveRemoved(st, removed, ev.seq);
-      for (const r of removed) st.sums[r.cat] -= r.tokens;
-      st.sums[cat] += node.tokens;
-      return node;
-    }
-  }
-  st.surface.push(node);
-  st.sums[cat] += node.tokens;
-  return node;
+	const cat = categoryOf(type, message ?? void 0);
+	const node = {
+		seq: ev.seq,
+		time: ev.time,
+		cat,
+		tokens: estimateMessage(message, type === "assistant/message")
+	};
+	const source = message?.source;
+	const form = source?.form;
+	if (typeof form === "string") node.form = form;
+	if (type === "assistant/message") {
+		const text = firstText(message?.content);
+		if (text !== "") node.text = text;
+		else {
+			const names = toolCallNames(message?.content);
+			if (names.length > 0) node.calls = names.slice(0, 3);
+		}
+	} else if (type === "tool/result") {
+		const srcId = source?.callId;
+		const srcName = typeof srcId === "string" ? st.callNames[srcId] : void 0;
+		const blockId = (message?.content?.[0])?.toolCallId;
+		if (srcName) node.tool = srcName;
+		else if (typeof blockId === "string") node.tool = st.callNames[blockId];
+		if (data?.error) node.err = true;
+	} else if (source?.kind === "skill-invocation") node.skill = typeof source.name === "string" ? source.name : "?";
+	else if (source?.kind === "plugin") {
+		if (source.form === "notice" && typeof source.summary === "string") node.text = source.summary;
+		else if (source.form === "snapshot" && Array.isArray(source.sections)) node.text = source.sections.map((s) => s?.name).filter(Boolean).join(", ").slice(0, 80);
+		else {
+			const ptext = firstText(message?.content);
+			if (ptext !== "") node.text = ptext;
+		}
+	} else {
+		const utext = firstText(message?.content);
+		if (utext !== "") node.text = utext;
+	}
+	const shadowedSeqs = st.pendingShadowedSeqs;
+	delete st.pendingShadowedSeqs;
+	const op = ev.surfaceOp;
+	if (op !== null && typeof op === "object" && op.op === "replace") {
+		if (Array.isArray(shadowedSeqs) && shadowedSeqs.length > 0) {
+			const shadowed = new Set(shadowedSeqs);
+			const kept = [];
+			const removed = [];
+			for (const n of st.surface) if (shadowed.has(n.seq)) {
+				st.sums[n.cat] -= n.tokens;
+				removed.push(n);
+			} else kept.push(n);
+			archiveRemoved(st, removed, ev.seq);
+			st.surface = kept;
+			st.sums[cat] += node.tokens;
+			st.surface.push(node);
+			return node;
+		}
+		let si = -1;
+		let ei = -1;
+		for (let i = 0; i < st.surface.length; i++) {
+			if (si < 0 && st.surface[i].seq === op.start) si = i;
+			if (st.surface[i].seq === op.end) {
+				ei = i;
+				break;
+			}
+		}
+		if (si >= 0 && ei >= si) {
+			const removed = st.surface.splice(si, ei - si + 1, node);
+			archiveRemoved(st, removed, ev.seq);
+			for (const r of removed) st.sums[r.cat] -= r.tokens;
+			st.sums[cat] += node.tokens;
+			return node;
+		}
+	}
+	st.surface.push(node);
+	st.sums[cat] += node.tokens;
+	return node;
 }
+/**
+* The DeepSeek V4 model family a model name prices as — matched on the NAME
+* alone (provider-agnostic: official API, proxies, OpenRouter spellings like
+* `deepseek/deepseek-v4-flash` all land here). Null for any other model:
+* non-V4 usage is simply not priced.
+*/
 function costFamilyOf(model) {
-  if (model === void 0) return null;
-  const m = model.toLowerCase();
-  if (!m.includes("v4")) return null;
-  if (m.includes("flash")) return "flash";
-  if (m.includes("pro")) return "pro";
-  return null;
+	if (model === void 0) return null;
+	const m = model.toLowerCase();
+	if (!m.includes("v4")) return null;
+	if (m.includes("flash")) return "flash";
+	if (m.includes("pro")) return "pro";
+	return null;
 }
+/** DeepSeek's UTC peak windows: 01:00-04:00 and 06:00-10:00 (off-peak is half price). */
 function isPeakUtc(time) {
-  const h = new Date(time).getUTCHours();
-  return h >= 1 && h < 4 || h >= 6 && h < 10;
+	const h = new Date(time).getUTCHours();
+	return h >= 1 && h < 4 || h >= 6 && h < 10;
 }
+/**
+* Fold one billed request into the session-cost totals, cloning along the
+* mutated path only (the untouched branch stays shared with the persisted
+* previous state — the apply contract never mutates it in place).
+*/
 function accumulateCost(st, time, usage) {
-  const family = costFamilyOf(st.model);
-  if (family === null) return;
-  const prev = st.cost ?? {};
-  const fam = prev[family] ?? {};
-  const period = isPeakUtc(time) ? "peak" : "off";
-  const b = fam[period] ?? { uncached: 0, cacheRead: 0, cacheWrite: 0, output: 0 };
-  const nextFam = { ...fam };
-  nextFam[period] = {
-    uncached: b.uncached + (usage.inputTokens ?? 0),
-    cacheRead: b.cacheRead + (usage.cacheReadTokens ?? 0),
-    cacheWrite: b.cacheWrite + (usage.cacheWriteTokens ?? 0),
-    output: b.output + (usage.outputTokens ?? 0)
-  };
-  const next = { ...prev };
-  next[family] = nextFam;
-  st.cost = next;
+	const family = costFamilyOf(st.model);
+	if (family === null) return;
+	const prev = st.cost ?? {};
+	const fam = prev[family] ?? {};
+	const period = isPeakUtc(time) ? "peak" : "off";
+	const b = fam[period] ?? {
+		uncached: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		output: 0
+	};
+	const nextFam = { ...fam };
+	nextFam[period] = {
+		uncached: b.uncached + (usage.inputTokens ?? 0),
+		cacheRead: b.cacheRead + (usage.cacheReadTokens ?? 0),
+		cacheWrite: b.cacheWrite + (usage.cacheWriteTokens ?? 0),
+		output: b.output + (usage.outputTokens ?? 0)
+	};
+	const next = { ...prev };
+	next[family] = nextFam;
+	st.cost = next;
 }
+/**
+* Advance the fold over ONE committed session event under the projection
+* contract. Uninteresting events return the same reference (`Object.is` gates
+* the change feed); any change returns a new reference over a lazy shallow
+* clone, so the persisted state is never mutated in place by the caller.
+* `bounds` come from the plugin config (config.ts) — retention only, they
+* never change the state shape.
+*/
 function applyTimeline(state, event, bounds) {
-  let st;
-  const ensure = () => st ??= {
-    ...state,
-    surface: [...state.surface],
-    sums: { ...state.sums },
-    toolList: [...state.toolList],
-    requests: [...state.requests],
-    events: [...state.events],
-    archived: [...state.archived],
-    callNames: { ...state.callNames }
-  };
-  const data = event.data;
-  switch (event.type) {
-    case "request/header": {
-      const header = data?.header ?? {};
-      const tools = Array.isArray(header.tools) ? header.tools : [];
-      const s = ensure();
-      s.toolList = tools.map((t) => ({
-        name: typeof t.name === "string" ? t.name : "?",
-        tokens: estimateToolSchema(t)
-      }));
-      s.toolsTokens = estimateToolsTotal(tools);
-      s.systemTokens = estimateSystem(header.system);
-      if (header.config && typeof header.config.model === "string") s.model = header.config.model;
-      if (header.config && typeof header.config.provider === "string") s.provider = header.config.provider;
-      if (data?.reason === "change" && s.model && s.lastModel && s.model !== s.lastModel) {
-        s.events.push({ seq: event.seq, time: event.time, kind: "model", from: s.lastModel, to: s.model });
-      }
-      if (s.model) s.lastModel = s.model;
-      break;
-    }
-    case "request/context": {
-      const s = ensure();
-      if (data && typeof data.contextWindow === "number") s.contextWindow = data.contextWindow;
-      if (data && typeof data.model === "string") s.model = data.model;
-      if (data && typeof data.provider === "string") s.provider = data.provider;
-      break;
-    }
-    case "tool/call": {
-      if (data && data.callId !== void 0 && typeof data.name === "string") {
-        const s = ensure();
-        s.callNames[String(data.callId)] = data.name;
-      }
-      break;
-    }
-    case "user/message": {
-      const msg = deriveEventMessage(event);
-      const s = ensure();
-      const node = applySurface(s, event, event.type, data, msg);
-      const source = msg?.source;
-      if (isInjection(source)) {
-        const rec = {
-          seq: event.seq,
-          time: event.time,
-          kind: "inject",
-          form: source.form || "context",
-          tokens: node.tokens
-        };
-        if (source.kind === "skill-invocation") {
-          rec.sub = "skill";
-          rec.name = typeof source.name === "string" ? source.name : "?";
-        } else if (typeof source.plugin === "string" && source.plugin !== "") {
-          rec.name = source.plugin;
-        }
-        s.events.push(rec);
-      }
-      break;
-    }
-    case "tool/result": {
-      const toolMsg = deriveEventMessage(event);
-      const s = ensure();
-      applySurface(s, event, event.type, data, toolMsg);
-      break;
-    }
-    case "assistant/message": {
-      const usage = data?.usage;
-      const s = ensure();
-      const total = s.systemTokens + s.toolsTokens + s.sums.user + s.sums.inject + s.sums.assistant + s.sums.tool;
-      const record = {
-        time: event.time,
-        seq: event.seq,
-        system: s.systemTokens,
-        tools: s.toolsTokens,
-        user: s.sums.user,
-        inject: s.sums.inject,
-        assistant: s.sums.assistant,
-        tool: s.sums.tool,
-        total
-      };
-      if (data && typeof data.turn === "number") record.turn = data.turn;
-      if (data && typeof data.step === "number") record.step = data.step;
-      if (usage && typeof usage.inputTokens === "number") {
-        record.prompt = usage.inputTokens + (usage.cacheReadTokens || 0) + (usage.cacheWriteTokens || 0);
-        if (typeof usage.outputTokens === "number") record.output = usage.outputTokens;
-        accumulateCost(s, event.time, usage);
-      }
-      s.requests.push(record);
-      const asstMsg = deriveEventMessage(event);
-      applySurface(s, event, event.type, data, asstMsg);
-      break;
-    }
-    case "compaction/summary":
-    case "compaction/prune": {
-      const s = ensure();
-      if (data && Array.isArray(data.shadowedSeqs)) {
-        s.pendingShadowedSeqs = data.shadowedSeqs.filter((x) => typeof x === "number");
-      }
-      s.events.push({
-        seq: event.seq,
-        time: event.time,
-        kind: event.type === "compaction/summary" ? "compaction" : "prune",
-        tokens: data && typeof data.shadowedTokenCount === "number" ? data.shadowedTokenCount : 0,
-        ...event.type === "compaction/summary" && data && Array.isArray(data.shadowedSeqs) ? { count: data.shadowedSeqs.length } : {}
-      });
-      break;
-    }
-    default:
-      return state;
-  }
-  if (st !== void 0) {
-    trimState(st, bounds);
-    return st;
-  }
-  return state;
+	let st;
+	const ensure = () => st ??= {
+		...state,
+		surface: [...state.surface],
+		sums: { ...state.sums },
+		toolList: [...state.toolList],
+		requests: [...state.requests],
+		events: [...state.events],
+		archived: [...state.archived],
+		callNames: { ...state.callNames }
+	};
+	const data = event.data;
+	switch (event.type) {
+		case "request/header": {
+			const header = data?.header ?? {};
+			const tools = Array.isArray(header.tools) ? header.tools : [];
+			const s = ensure();
+			s.toolList = tools.map((t) => ({
+				name: typeof t.name === "string" ? t.name : "?",
+				tokens: estimateToolSchema(t)
+			}));
+			s.toolsTokens = estimateToolsTotal(tools);
+			s.systemTokens = estimateSystem(header.system);
+			if (header.config && typeof header.config.model === "string") s.model = header.config.model;
+			if (header.config && typeof header.config.provider === "string") s.provider = header.config.provider;
+			if (data?.reason === "change" && s.model && s.lastModel && s.model !== s.lastModel) s.events.push({
+				seq: event.seq,
+				time: event.time,
+				kind: "model",
+				from: s.lastModel,
+				to: s.model
+			});
+			if (s.model) s.lastModel = s.model;
+			break;
+		}
+		case "request/context": {
+			const s = ensure();
+			if (data && typeof data.contextWindow === "number") s.contextWindow = data.contextWindow;
+			if (data && typeof data.model === "string") s.model = data.model;
+			if (data && typeof data.provider === "string") s.provider = data.provider;
+			break;
+		}
+		case "tool/call":
+			if (data && typeof data.callId === "string" && typeof data.name === "string") {
+				const s = ensure();
+				s.callNames[data.callId] = data.name;
+			}
+			break;
+		case "user/message": {
+			const msg = deriveEventMessage(event);
+			const s = ensure();
+			const node = applySurface(s, event, event.type, data, msg);
+			const source = msg?.source;
+			if (isInjection(source)) {
+				const rec = {
+					seq: event.seq,
+					time: event.time,
+					kind: "inject",
+					form: source.form || "context",
+					tokens: node.tokens
+				};
+				if (source.kind === "skill-invocation") {
+					rec.sub = "skill";
+					rec.name = typeof source.name === "string" ? source.name : "?";
+				} else if (typeof source.plugin === "string" && source.plugin !== "") rec.name = source.plugin;
+				s.events.push(rec);
+			}
+			break;
+		}
+		case "tool/result": {
+			const toolMsg = deriveEventMessage(event);
+			applySurface(ensure(), event, event.type, data, toolMsg);
+			break;
+		}
+		case "assistant/message": {
+			const usage = data?.usage;
+			const s = ensure();
+			const total = s.systemTokens + s.toolsTokens + s.sums.user + s.sums.inject + s.sums.assistant + s.sums.tool;
+			const record = {
+				time: event.time,
+				seq: event.seq,
+				system: s.systemTokens,
+				tools: s.toolsTokens,
+				user: s.sums.user,
+				inject: s.sums.inject,
+				assistant: s.sums.assistant,
+				tool: s.sums.tool,
+				total
+			};
+			if (data && typeof data.turn === "number") record.turn = data.turn;
+			if (data && typeof data.step === "number") record.step = data.step;
+			if (usage && typeof usage.inputTokens === "number") {
+				record.prompt = usage.inputTokens + (usage.cacheReadTokens || 0) + (usage.cacheWriteTokens || 0);
+				if (typeof usage.outputTokens === "number") record.output = usage.outputTokens;
+				accumulateCost(s, event.time, usage);
+			}
+			s.requests.push(record);
+			const asstMsg = deriveEventMessage(event);
+			applySurface(s, event, event.type, data, asstMsg);
+			break;
+		}
+		case "compaction/summary":
+		case "compaction/prune": {
+			const s = ensure();
+			if (data && Array.isArray(data.shadowedSeqs)) s.pendingShadowedSeqs = data.shadowedSeqs.filter((x) => typeof x === "number");
+			s.events.push({
+				seq: event.seq,
+				time: event.time,
+				kind: event.type === "compaction/summary" ? "compaction" : "prune",
+				tokens: data && typeof data.shadowedTokenCount === "number" ? data.shadowedTokenCount : 0,
+				...event.type === "compaction/summary" && data && Array.isArray(data.shadowedSeqs) ? { count: data.shadowedSeqs.length } : {}
+			});
+			break;
+		}
+		default: return state;
+	}
+	if (st !== void 0) {
+		trimState(st, bounds);
+		return st;
+	}
+	return state;
 }
+/**
+* Build the wire snapshot served to the browser — the projection's `view()`.
+* Bounds the surface nodes (newest carry the signal), and attributes each
+* event to the request around it by stamping COPIES (the persisted state
+* objects are never mutated).
+*/
 function buildTimelineView(state, bounds) {
-  const surfaceTotal = state.sums.user + state.sums.inject + state.sums.assistant + state.sums.tool;
-  const result = {
-    ok: true,
-    model: state.model,
-    provider: state.provider,
-    contextWindow: state.contextWindow,
-    current: {
-      system: state.systemTokens,
-      tools: state.toolsTokens,
-      user: state.sums.user,
-      inject: state.sums.inject,
-      assistant: state.sums.assistant,
-      tool: state.sums.tool,
-      total: surfaceTotal + state.systemTokens + state.toolsTokens
-    },
-    toolList: state.toolList,
-    requests: state.requests.map((r) => ({ ...r })),
-    events: state.events.map((e) => ({ ...e })),
-    nodes: [],
-    droppedNodes: 0,
-    archive: state.archived.map((n) => ({ ...n }))
-  };
-  if (state.cost !== void 0) {
-    const copyFam = (f) => {
-      if (f === void 0) return void 0;
-      const out = {};
-      if (f.peak !== void 0) out.peak = { ...f.peak };
-      if (f.off !== void 0) out.off = { ...f.off };
-      return out;
-    };
-    const cost = {};
-    const flash = copyFam(state.cost.flash);
-    if (flash !== void 0) cost.flash = flash;
-    const pro = copyFam(state.cost.pro);
-    if (pro !== void 0) cost.pro = pro;
-    result.cost = cost;
-  }
-  const overflowCount = Math.max(0, state.surface.length - bounds.maxNodes);
-  const overflow = state.surface.slice(0, overflowCount);
-  const tail = state.surface.slice(overflowCount);
-  const pinned = overflow.filter((n) => n.cat === "inject");
-  result.nodes = pinned.length > 0 ? [...pinned, ...tail] : tail;
-  result.droppedNodes = overflowCount - pinned.length;
-  if (result.droppedNodes > 0) {
-    let floor = 0;
-    for (const n of overflow) if (n.cat !== "inject") floor = Math.max(floor, n.seq);
-    result.surfaceFloor = floor;
-  }
-  if (state.archiveFloor !== void 0) result.archiveFloor = state.archiveFloor;
-  const requests = result.requests;
-  const events = result.events;
-  let ri = 0;
-  for (const ev of events) {
-    while (ri < requests.length && requests[ri].seq <= ev.seq) ri++;
-    const next = requests[ri];
-    const prev = ri > 0 ? requests[ri - 1] : void 0;
-    if (next !== void 0 && typeof next.turn === "number" && typeof next.step === "number") {
-      ev.turn = next.turn;
-      ev.step = next.step;
-    }
-    if (prev !== void 0 && typeof prev.turn === "number" && typeof prev.step === "number") {
-      ev.fromTurn = prev.turn;
-      ev.fromStep = prev.step;
-    }
-  }
-  return result;
+	const surfaceTotal = state.sums.user + state.sums.inject + state.sums.assistant + state.sums.tool;
+	const result = {
+		ok: true,
+		model: state.model,
+		provider: state.provider,
+		contextWindow: state.contextWindow,
+		current: {
+			system: state.systemTokens,
+			tools: state.toolsTokens,
+			user: state.sums.user,
+			inject: state.sums.inject,
+			assistant: state.sums.assistant,
+			tool: state.sums.tool,
+			total: surfaceTotal + state.systemTokens + state.toolsTokens
+		},
+		toolList: state.toolList,
+		requests: state.requests.map((r) => ({ ...r })),
+		events: state.events.map((e) => ({ ...e })),
+		nodes: [],
+		droppedNodes: 0,
+		archive: state.archived.map((n) => ({ ...n }))
+	};
+	if (state.cost !== void 0) {
+		const copyFam = (f) => {
+			if (f === void 0) return void 0;
+			const out = {};
+			if (f.peak !== void 0) out.peak = { ...f.peak };
+			if (f.off !== void 0) out.off = { ...f.off };
+			return out;
+		};
+		const cost = {};
+		const flash = copyFam(state.cost.flash);
+		if (flash !== void 0) cost.flash = flash;
+		const pro = copyFam(state.cost.pro);
+		if (pro !== void 0) cost.pro = pro;
+		result.cost = cost;
+	}
+	const overflowCount = Math.max(0, state.surface.length - bounds.maxNodes);
+	const overflow = state.surface.slice(0, overflowCount);
+	const tail = state.surface.slice(overflowCount);
+	const pinned = overflow.filter((n) => n.cat === "inject");
+	result.nodes = pinned.length > 0 ? [...pinned, ...tail] : tail;
+	result.droppedNodes = overflowCount - pinned.length;
+	if (result.droppedNodes > 0) {
+		let floor = 0;
+		for (const n of overflow) if (n.cat !== "inject") floor = Math.max(floor, n.seq);
+		result.surfaceFloor = floor;
+	}
+	if (state.archiveFloor !== void 0) result.archiveFloor = state.archiveFloor;
+	const requests = result.requests;
+	const events = result.events;
+	let ri = 0;
+	for (const ev of events) {
+		while (ri < requests.length && requests[ri].seq <= ev.seq) ri++;
+		const next = requests.at(ri);
+		const prev = ri > 0 ? requests.at(ri - 1) : void 0;
+		if (next !== void 0 && typeof next.turn === "number" && typeof next.step === "number") {
+			ev.turn = next.turn;
+			ev.step = next.step;
+		}
+		if (prev !== void 0 && typeof prev.turn === "number" && typeof prev.step === "number") {
+			ev.fromTurn = prev.turn;
+			ev.fromStep = prev.step;
+		}
+	}
+	return result;
 }
-
-// src/host/timeline.ts
-var surfaceNodeSchema = z3.object({
-  seq: z3.number().int().nonnegative(),
-  time: z3.number().optional(),
-  cat: z3.enum(["user", "inject", "assistant", "tool"]),
-  tokens: z3.number().int().nonnegative(),
-  gone: z3.number().int().nonnegative().optional(),
-  form: z3.string().optional(),
-  text: z3.string().optional(),
-  tool: z3.string().optional(),
-  err: z3.boolean().optional(),
-  skill: z3.string().optional(),
-  calls: z3.array(z3.string()).optional()
+//#endregion
+//#region src/host/timeline.ts
+/**
+* The `contextTimeline` session projection unit — the plugin's data plane.
+*
+* This is the whole Host half after the v0.9 data-path migration: instead of
+* serving snapshots over a custom `/dsh-context` RPC channel, the plugin
+* registers one pure projection unit on the harness's
+* `ctx.sessionProjections` registry. The framework then:
+*   - drives the fold per committed `session/event` (eager, incremental),
+*   - persists the unit state through `ctx.sessionProjectionCache`
+*     (checkpointed rows, cold-read ladder, resume-safe),
+*   - delivers finished values to the browser as a `session/projection` push
+*     frame plus a tail-page baseline, where the Client reads them through
+*     the framework-standard `useProjection('contextTimeline')` seat.
+*
+* The unit is pure mathematics (init/apply/view) — it holds no subscriptions
+* and never touches the client. The wire value is the same Snapshot the UI
+* has always rendered (shared/types.ts), so the Client renders unchanged.
+*/
+/** Validate the wire payload before it leaves the host (strict: no drift). */
+const surfaceNodeSchema = z.object({
+	seq: z.number().int().nonnegative(),
+	time: z.number().optional(),
+	cat: z.enum([
+		"user",
+		"inject",
+		"assistant",
+		"tool"
+	]),
+	tokens: z.number().int().nonnegative(),
+	gone: z.number().int().nonnegative().optional(),
+	form: z.string().optional(),
+	text: z.string().optional(),
+	tool: z.string().optional(),
+	err: z.boolean().optional(),
+	skill: z.string().optional(),
+	calls: z.array(z.string()).optional()
 }).strict();
-var requestRecordSchema = z3.object({
-  turn: z3.number().optional(),
-  step: z3.number().optional(),
-  time: z3.number(),
-  seq: z3.number(),
-  system: z3.number().int().nonnegative(),
-  tools: z3.number().int().nonnegative(),
-  user: z3.number().int().nonnegative(),
-  inject: z3.number().int().nonnegative(),
-  assistant: z3.number().int().nonnegative(),
-  tool: z3.number().int().nonnegative(),
-  total: z3.number().int().nonnegative(),
-  prompt: z3.number().int().nonnegative().optional(),
-  output: z3.number().int().nonnegative().optional(),
-  stepCount: z3.number().int().positive().optional()
+const requestRecordSchema = z.object({
+	turn: z.number().optional(),
+	step: z.number().optional(),
+	time: z.number(),
+	seq: z.number(),
+	system: z.number().int().nonnegative(),
+	tools: z.number().int().nonnegative(),
+	user: z.number().int().nonnegative(),
+	inject: z.number().int().nonnegative(),
+	assistant: z.number().int().nonnegative(),
+	tool: z.number().int().nonnegative(),
+	total: z.number().int().nonnegative(),
+	prompt: z.number().int().nonnegative().optional(),
+	output: z.number().int().nonnegative().optional(),
+	stepCount: z.number().int().positive().optional()
 }).strict();
-var contextEventSchema = z3.object({
-  seq: z3.number(),
-  time: z3.number(),
-  kind: z3.enum(["compaction", "prune", "inject", "model"]),
-  form: z3.string().optional(),
-  tokens: z3.number().optional(),
-  count: z3.number().optional(),
-  sub: z3.string().optional(),
-  name: z3.string().optional(),
-  from: z3.string().optional(),
-  to: z3.string().optional(),
-  fromTurn: z3.number().optional(),
-  fromStep: z3.number().optional(),
-  turn: z3.number().optional(),
-  step: z3.number().optional()
+const contextEventSchema = z.object({
+	seq: z.number(),
+	time: z.number(),
+	kind: z.enum([
+		"compaction",
+		"prune",
+		"inject",
+		"model"
+	]),
+	form: z.string().optional(),
+	tokens: z.number().optional(),
+	count: z.number().optional(),
+	sub: z.string().optional(),
+	name: z.string().optional(),
+	from: z.string().optional(),
+	to: z.string().optional(),
+	fromTurn: z.number().optional(),
+	fromStep: z.number().optional(),
+	turn: z.number().optional(),
+	step: z.number().optional()
 }).strict();
-var currentSchema = z3.object({
-  system: z3.number().int().nonnegative(),
-  tools: z3.number().int().nonnegative(),
-  user: z3.number().int().nonnegative(),
-  inject: z3.number().int().nonnegative(),
-  assistant: z3.number().int().nonnegative(),
-  tool: z3.number().int().nonnegative(),
-  total: z3.number().int().nonnegative()
+const currentSchema = z.object({
+	system: z.number().int().nonnegative(),
+	tools: z.number().int().nonnegative(),
+	user: z.number().int().nonnegative(),
+	inject: z.number().int().nonnegative(),
+	assistant: z.number().int().nonnegative(),
+	tool: z.number().int().nonnegative(),
+	total: z.number().int().nonnegative()
 }).strict();
-var costBucketsSchema = z3.object({
-  uncached: z3.number().int().nonnegative(),
-  cacheRead: z3.number().int().nonnegative(),
-  cacheWrite: z3.number().int().nonnegative(),
-  output: z3.number().int().nonnegative()
+const costBucketsSchema = z.object({
+	uncached: z.number().int().nonnegative(),
+	cacheRead: z.number().int().nonnegative(),
+	cacheWrite: z.number().int().nonnegative(),
+	output: z.number().int().nonnegative()
 }).strict();
-var costFamilySchema = z3.object({
-  peak: costBucketsSchema.optional(),
-  off: costBucketsSchema.optional()
+const costFamilySchema = z.object({
+	peak: costBucketsSchema.optional(),
+	off: costBucketsSchema.optional()
 }).strict();
-var contextTimelineSchema = z3.object({
-  ok: z3.literal(true),
-  model: z3.string().optional(),
-  provider: z3.string().optional(),
-  contextWindow: z3.number().optional(),
-  current: currentSchema,
-  toolList: z3.array(z3.object({ name: z3.string(), tokens: z3.number().int().nonnegative() }).strict()),
-  requests: z3.array(requestRecordSchema),
-  events: z3.array(contextEventSchema),
-  cost: z3.object({ flash: costFamilySchema.optional(), pro: costFamilySchema.optional() }).strict().optional(),
-  nodes: z3.array(surfaceNodeSchema),
-  droppedNodes: z3.number().int().nonnegative(),
-  archive: z3.array(surfaceNodeSchema),
-  surfaceFloor: z3.number().int().nonnegative().optional(),
-  archiveFloor: z3.number().int().nonnegative().optional()
+const contextTimelineSchema = z.object({
+	ok: z.literal(true),
+	model: z.string().optional(),
+	provider: z.string().optional(),
+	contextWindow: z.number().optional(),
+	current: currentSchema,
+	toolList: z.array(z.object({
+		name: z.string(),
+		tokens: z.number().int().nonnegative()
+	}).strict()),
+	requests: z.array(requestRecordSchema),
+	events: z.array(contextEventSchema),
+	cost: z.object({
+		flash: costFamilySchema.optional(),
+		pro: costFamilySchema.optional()
+	}).strict().optional(),
+	nodes: z.array(surfaceNodeSchema),
+	droppedNodes: z.number().int().nonnegative(),
+	archive: z.array(surfaceNodeSchema),
+	surfaceFloor: z.number().int().nonnegative().optional(),
+	archiveFloor: z.number().int().nonnegative().optional()
 }).strict();
-var timelineStateSchema = z3.object({
-  surface: z3.array(surfaceNodeSchema),
-  sums: z3.object({
-    user: z3.number().int().nonnegative(),
-    inject: z3.number().int().nonnegative(),
-    assistant: z3.number().int().nonnegative(),
-    tool: z3.number().int().nonnegative()
-  }).strict(),
-  systemTokens: z3.number().int().nonnegative(),
-  toolsTokens: z3.number().int().nonnegative(),
-  toolList: z3.array(z3.object({ name: z3.string(), tokens: z3.number().int().nonnegative() }).strict()),
-  model: z3.string().optional(),
-  provider: z3.string().optional(),
-  lastModel: z3.string().optional(),
-  contextWindow: z3.number().optional(),
-  requests: z3.array(requestRecordSchema),
-  events: z3.array(contextEventSchema),
-  archived: z3.array(surfaceNodeSchema),
-  cost: z3.object({ flash: costFamilySchema.optional(), pro: costFamilySchema.optional() }).strict().optional(),
-  archiveFloor: z3.number().optional(),
-  callNames: z3.record(z3.string(), z3.string()),
-  pendingShadowedSeqs: z3.array(z3.number()).optional()
+/**
+* The persisted fold-state schema (the dsh 0.1.1-rc.1+ `stateSchema`
+* contract). Validates the plain-JSON `TimelineState` before a checkpoint
+* row seeds a fold — the same shape guarantee the projection cache's
+* plain-JSON precondition already enforces at write time.
+*/
+const timelineStateSchema = z.object({
+	surface: z.array(surfaceNodeSchema),
+	sums: z.object({
+		user: z.number().int().nonnegative(),
+		inject: z.number().int().nonnegative(),
+		assistant: z.number().int().nonnegative(),
+		tool: z.number().int().nonnegative()
+	}).strict(),
+	systemTokens: z.number().int().nonnegative(),
+	toolsTokens: z.number().int().nonnegative(),
+	toolList: z.array(z.object({
+		name: z.string(),
+		tokens: z.number().int().nonnegative()
+	}).strict()),
+	model: z.string().optional(),
+	provider: z.string().optional(),
+	lastModel: z.string().optional(),
+	contextWindow: z.number().optional(),
+	requests: z.array(requestRecordSchema),
+	events: z.array(contextEventSchema),
+	archived: z.array(surfaceNodeSchema),
+	cost: z.object({
+		flash: costFamilySchema.optional(),
+		pro: costFamilySchema.optional()
+	}).strict().optional(),
+	archiveFloor: z.number().optional(),
+	callNames: z.record(z.string(), z.string()),
+	pendingShadowedSeqs: z.array(z.number()).optional()
 });
+/**
+* The context-timeline projection unit, created per plugin instance with its
+* config-resolved retention bounds (config.ts), and registered on
+* `ctx.sessionProjections`. Registry lifecycle notes (mirrored from the
+* harness contract): registration is an effect on the caller's fiber — an
+* unloaded Host half removes the key, and clients read it as capability
+* absence. `stateVersion` must be bumped whenever the persisted state shape
+* or fold semantics change (invalidation of cached rows); config-only
+* changes never require it (bounds tune retention, not state shape).
+*
+* The definition carries BOTH session-projection contracts (see compat.ts):
+* `schema`/`view` for dsh <= 0.1.0-rc.8, `stateSchema`/`wire` for
+* dsh >= 0.1.1-rc.1 — each registry reads its own fields off the same unit.
+* Without the `wire` block the 0.1.1-rc.1+ registry treats the unit as
+* host-only and never delivers `contextTimeline` to the browser (the Context
+* tab would stay on its loading screen forever).
+*/
 function createContextTimelineDefinition(config) {
-  const bounds = resolveBounds(config);
-  const view = (state) => buildTimelineView(state, bounds);
-  const definition = {
-    key: "contextTimeline",
-    // dsh <= 0.1.0-rc.8 contract: one schema validates the wire payload, `view` is top-level.
-    schema: contextTimelineSchema,
-    view,
-    // dsh >= 0.1.1-rc.1 contract: `stateSchema` validates persisted state, the client view lives in `wire`.
-    stateSchema: timelineStateSchema,
-    wire: { viewSchema: contextTimelineSchema, view },
-    init: () => createTimelineState(),
-    apply: (state, event) => applyTimeline(state, event, bounds),
-    // 2 since 0.11: the occupancy mirror (pressureTokens/sampledSurfaceTokens/
-    // occupancyWindow) left the persisted state — the client now reads the
-    // official token-meter `contextPressure` projection instead. Old cached
-    // rows are discarded and refolded.
-    // 3 since 0.12: the removed-node archive (`archived` + `archiveFloor`)
-    // joined the persisted state for the Context browser's per-step
-    // reconstruction — cached rows predate the shape and are refolded.
-    // 4 since 0.18: the persisted state no longer carries `undefined`-valued
-    // properties (model/provider/lastModel/contextWindow are absent until
-    // known; pendingShadowedSeqs is deleted when consumed). The previous
-    // shape violated the plain-JSON persisted-state precondition and failed
-    // EVERY session-projection-cache write (TypeError: projection checkpoint
-    // is not losslessly JSON-serializable) — which also starved the `title`
-    // projection row and broke the session list after a restart. The bump
-    // discards old cached rows and refolds them clean.
-    // 5: the session-cost totals (`cost` — per-family/per-period billed
-    // tokens) joined the persisted state; cached rows predate the shape and
-    // are refolded.
-    stateVersion: 5
-  };
-  return definition;
+	const bounds = resolveBounds(config);
+	const view = (state) => buildTimelineView(state, bounds);
+	return {
+		key: "contextTimeline",
+		schema: contextTimelineSchema,
+		view,
+		stateSchema: timelineStateSchema,
+		wire: {
+			viewSchema: contextTimelineSchema,
+			view
+		},
+		init: () => createTimelineState(),
+		apply: (state, event) => applyTimeline(state, event, bounds),
+		stateVersion: 5
+	};
 }
-
-// src/host/index.ts
-var name = "dsh-context";
-var inject = ["sessionProjections"];
+//#endregion
+//#region src/host/index.ts
+const name = "dsh-context";
+/** Required services: the session-projection registry that drives the unit. */
+const inject = ["sessionProjections"];
 function apply(ctx, config) {
-  ctx.sessionProjections.register(createContextTimelineDefinition(config));
-  ctx.sessionProjections.register(createContextHeadersDefinition());
+	ctx.sessionProjections.register(createContextTimelineDefinition(config));
+	ctx.sessionProjections.register(createContextHeadersDefinition());
 }
-export {
-  Config,
-  apply,
-  inject,
-  name
-};
+//#endregion
+export { Config, apply, inject, name };