@visual-z/xeno 0.1.0

package/src/core/theme.ts

@@ -0,0 +1,179 @@
+/**
+ * Theme schema and validation. Pure: a file is read elsewhere, this module
+ * only turns JSON into a complete Theme plus named problems.
+ *
+ * A broken theme must still produce a usable Theme (the dark builtin).
+ * Throwing here would take the agent down the moment the user edited a
+ * comma, which is when they most need it (feat-theming design).
+ */
+
+export const THEME_TOKENS = [
+  "text",
+  "thinkingText",
+  "toolTitle",
+  "toolOutput",
+  "error",
+  "toolDiffAdded",
+  "toolDiffRemoved",
+  "status",
+  "prompt",
+  "selectedBg",
+  "muted",
+  "warning",
+  "mdHeading",
+  "mdCode",
+  "mdLink",
+  "userMessageBg",
+  "toolPendingBg",
+  "toolSuccessBg",
+  "toolErrorBg",
+  "thinkingLow",
+  "thinkingMedium",
+  "thinkingHigh",
+  "thinkingXhigh",
+  "thinkingMax",
+] as const;
+
+export type ThemeToken = (typeof THEME_TOKENS)[number];
+
+export type ThemeColors = { readonly [K in ThemeToken]: string };
+
+export interface Theme {
+  readonly name: string;
+  readonly colors: ThemeColors;
+}
+
+export interface ThemeParse {
+  readonly theme: Theme;
+  readonly diagnostics: readonly string[];
+}
+
+/**
+ * Palette adapted from pi (earendil-works/pi, MIT), coding-agent theme/dark.json
+ * and light.json at 3390bd93630965a12a0a1a5c36ce890ec22f7e1d. Existing custom
+ * tokens remain accepted; missing presentation tokens inherit these defaults.
+ */
+const DARK_COLORS: ThemeColors = {
+  "text": "38;2;212;212;212",
+  "thinkingText": "38;2;128;128;128",
+  "toolTitle": "38;2;212;212;212",
+  "toolOutput": "38;2;128;128;128",
+  "error": "38;2;204;102;102",
+  "toolDiffAdded": "38;2;181;189;104",
+  "toolDiffRemoved": "38;2;204;102;102",
+  "status": "38;2;128;128;128",
+  "prompt": "38;2;212;212;212",
+  "selectedBg": "48;2;58;58;74",
+  "muted": "38;2;128;128;128",
+  "warning": "38;2;255;255;0",
+  "mdHeading": "38;2;240;198;116",
+  "mdCode": "38;2;138;190;183",
+  "mdLink": "38;2;129;162;190",
+  "userMessageBg": "48;2;52;53;65",
+  "toolPendingBg": "48;2;40;40;50",
+  "toolSuccessBg": "48;2;40;50;40",
+  "toolErrorBg": "48;2;60;40;40",
+  "thinkingLow": "38;2;95;135;175",
+  "thinkingMedium": "38;2;129;162;190",
+  "thinkingHigh": "38;2;178;148;187",
+  "thinkingXhigh": "38;2;209;131;232",
+  "thinkingMax": "38;2;255;95;255"
+};
+
+/** Distinct from dark so `--theme light` is visible without OSC 11 probing. */
+const LIGHT_COLORS: ThemeColors = {
+  "text": "38;2;31;35;40",
+  "thinkingText": "38;2;108;108;108",
+  "toolTitle": "38;2;31;35;40",
+  "toolOutput": "38;2;108;108;108",
+  "error": "38;2;170;85;85",
+  "toolDiffAdded": "38;2;88;132;88",
+  "toolDiffRemoved": "38;2;170;85;85",
+  "status": "38;2;108;108;108",
+  "prompt": "38;2;31;35;40",
+  "selectedBg": "48;2;208;208;224",
+  "muted": "38;2;108;108;108",
+  "warning": "38;2;154;115;38",
+  "mdHeading": "38;2;154;115;38",
+  "mdCode": "38;2;90;128;128",
+  "mdLink": "38;2;84;125;167",
+  "userMessageBg": "48;2;232;232;232",
+  "toolPendingBg": "48;2;232;232;240",
+  "toolSuccessBg": "48;2;232;240;232",
+  "toolErrorBg": "48;2;240;232;232",
+  "thinkingLow": "38;2;84;125;167",
+  "thinkingMedium": "38;2;90;128;128",
+  "thinkingHigh": "38;2;135;95;135",
+  "thinkingXhigh": "38;2;139;0;139",
+  "thinkingMax": "38;2;175;0;95"
+};
+
+export function builtinTheme(name: "dark" | "light"): Theme {
+  return name === "light"
+    ? { name: "light", colors: LIGHT_COLORS }
+    : { name: "dark", colors: DARK_COLORS };
+}
+
+export function parseTheme(json: unknown): ThemeParse {
+  const fallback = builtinTheme("dark");
+  if (typeof json !== "object" || json === null || Array.isArray(json)) {
+    return {
+      theme: fallback,
+      diagnostics: ["theme is not an object; using dark"],
+    };
+  }
+  const rec = json as { readonly [k: string]: unknown };
+  const diagnostics: string[] = [];
+  const name = typeof rec["name"] === "string" && rec["name"].length > 0 ? rec["name"] : "custom";
+  const rawColors = rec["colors"];
+  const src: { readonly [k: string]: unknown } =
+    typeof rawColors === "object" && rawColors !== null && !Array.isArray(rawColors)
+      ? (rawColors as { readonly [k: string]: unknown })
+      : (() => {
+          diagnostics.push("theme.colors is missing or not an object; filling from dark");
+          return {};
+        })();
+
+  for (const key of Object.keys(src)) {
+    if (!isThemeToken(key)) diagnostics.push(`unknown token: ${key}`);
+  }
+
+  const colors: { [K in ThemeToken]: string } = { ...fallback.colors };
+  for (const token of THEME_TOKENS) {
+    if (!(token in src)) continue;
+    const parsed = parseColor(src[token]);
+    if (parsed === null) {
+      diagnostics.push(`invalid colour for ${token}; using built-in`);
+      continue;
+    }
+    colors[token] = parsed;
+  }
+
+  return { theme: { name, colors }, diagnostics };
+}
+
+function isThemeToken(key: string): key is ThemeToken {
+  return (THEME_TOKENS as readonly string[]).includes(key);
+}
+
+/**
+ * Accept SGR params (`31`, `38;5;180`, `38;2;r;g;b`), `#RRGGBB`, a 256-colour
+ * index, or empty (terminal default). Anything else is invalid.
+ */
+export function parseColor(value: unknown): string | null {
+  if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 255) {
+    return `38;5;${value}`;
+  }
+  if (typeof value !== "string") return null;
+  if (value === "") return "";
+  const hex = /^#([0-9a-fA-F]{6})$/.exec(value);
+  if (hex) {
+    const n = Number.parseInt(hex[1]!, 16);
+    const r = (n >> 16) & 255;
+    const g = (n >> 8) & 255;
+    const b = n & 255;
+    return `38;2;${r};${g};${b}`;
+  }
+  if (/^[0-9]+(?:;[0-9]+)*$/.test(value)) return value;
+  return null;
+}

package/src/core/tokens.ts

@@ -0,0 +1,149 @@
+/**
+ * Token accounting.
+ *
+ * The default here is an ESTIMATE and is labelled as one. Real counting needs the
+ * provider's own counter (Anthropic's `messages.count_tokens`); a bundled
+ * tokenizer would drift from whatever model is actually in use and would be wrong
+ * in a way nobody notices. The boundary logic therefore takes a counter as a
+ * parameter, so wiring the real one in is a one-line change and nothing in the
+ * core pretends to be authoritative.
+ */
+
+import type { Message } from "./project.ts";
+
+export interface TokenCounter {
+  readonly kind: "estimate" | "exact";
+  /**
+   * Counts everything the API bills as prompt: tool schemas, the system
+   * prompt and the messages.
+   *
+   * Tools are a parameter because leaving them out made two sides of a
+   * boundary decision incomparable -- one came from the provider's billed
+   * figure, which includes schemas, the other from a count that silently
+   * skipped them, and the difference read as work the node had done.
+   */
+  count(messages: readonly Message[], system: string, tools?: readonly unknown[]): number;
+}
+
+/**
+ * Estimated tokens for one string.
+ *
+ * ASCII keeps the original chars/3.6: code and JSON tokenize more densely than
+ * prose, so this sits below the usual chars/4 rule, and every measured cut
+ * point so far was taken with it. Ideographic scripts are a different
+ * regime -- one Han character is roughly 0.6-1.5 tokens across current
+ * tokenizers, where chars/3.6 would say 0.28 -- so they are charged a full
+ * token each. Overestimating only moves a cut earlier; underestimating is a
+ * 400 from the provider. Other non-ASCII (accents, symbols, emoji) sits
+ * between the two at half a token per code point.
+ */
+export function estimateText(text: string): number {
+  let ascii = 0;
+  let weighted = 0;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code < 0x80) { ascii++; continue; }
+    // A surrogate pair is one code point; charge it once, at its high half.
+    if (code >= 0xdc00 && code <= 0xdfff) continue;
+    const ideographic =
+      (code >= 0x2e80 && code <= 0x9fff) || // CJK radicals .. unified ideographs, kana, bopomofo
+      (code >= 0xac00 && code <= 0xd7af) || // Hangul syllables
+      (code >= 0xf900 && code <= 0xfaff) || // CJK compatibility ideographs
+      (code >= 0xff00 && code <= 0xffef); // full-width forms
+    weighted += ideographic ? 1 : 0.5;
+  }
+  return ascii / 3.6 + weighted;
+}
+
+/**
+ * estimateText across message and system text, plus serialized schemas and
+ * per-message framing. Expect roughly +/-20% on ASCII; treat the trigger
+ * threshold as approximate until an exact counter is wired in.
+ */
+export const estimateTokens: TokenCounter = {
+  kind: "estimate",
+  count(messages, system, tools = []) {
+    // Serialized schemas are what goes on the wire, so their length is the
+    // right proxy -- and they are billed on every single request.
+    let tokens = estimateText(system) + (tools.length > 0 ? estimateText(JSON.stringify(tools)) : 0);
+    for (const m of messages) {
+      for (const b of m.content) {
+        if (b.type === "text") tokens += estimateText(b.text);
+        // Thinking is opaque here; its serialized size is the best proxy.
+        else if (b.type === "thinking") tokens += estimateText(JSON.stringify(b.raw));
+        else if (b.type === "tool_use") tokens += estimateText(b.name) + estimateText(JSON.stringify(b.input));
+        else if (b.type === "tool_result") tokens += estimateText(b.content);
+      }
+      // Per-message framing overhead, roughly.
+      tokens += 8 / 3.6;
+    }
+    return Math.ceil(tokens);
+  },
+};
+
+/**
+ * A counter whose every count is multiplied by `factor`.
+ *
+ * Used once the provider has rejected a prompt the estimate said would fit:
+ * that is a measurement that this content tokenizes `factor` times denser
+ * than estimated, and sizing the retained context with the unscaled counter
+ * would reproduce the overflow.
+ */
+export function scaledCounter(counter: TokenCounter, factor: number): TokenCounter {
+  return { kind: "estimate", count: (messages, system, tools) => Math.ceil(counter.count(messages, system, tools) * factor) };
+}
+
+/**
+ * An anchor: the prompt size a provider actually charged, and how far into the
+ * conversation that measurement covered.
+ *
+ * Measuring the estimator against a real tokenizer showed it running between
+ * -21% and +38% across realistic content -- prose, source, JSON and YAML all
+ * tokenize at different densities, so no single chars-per-token constant fits
+ * them at once. Underestimating source by a fifth is the dangerous direction:
+ * a 30k trigger would fire at an actual 38k.
+ *
+ * Calibrating the constant would not fix that, because the error depends on
+ * what the content happens to be. Anchoring does: every response reports the
+ * prompt it was actually billed for, so everything up to that point is known
+ * exactly and only the delta since needs estimating. The error then scales
+ * with one turn instead of with the whole conversation.
+ */
+export interface Anchor {
+  /** Sum of uncached, cache-write and cache-read input tokens. */
+  promptTokens: number;
+  /** Tokens the model generated, which become part of the next prompt. */
+  outputTokens: number;
+  /** Number of messages the measurement covered. */
+  messageCount: number;
+}
+
+/**
+ * Prompt size for the next request: exact up to the anchor, estimated after.
+ *
+ * Falls back to a plain estimate before the first response, which is the only
+ * point where nothing has been measured yet.
+ */
+export function anchoredCount(
+  messages: readonly Message[],
+  system: string,
+  anchor: Anchor | null,
+  counter: TokenCounter = estimateTokens,
+  tools: readonly unknown[] = [],
+): { tokens: number; exactUpTo: number } {
+  if (anchor === null || anchor.messageCount > messages.length) {
+    return { tokens: counter.count(messages, system, tools), exactUpTo: 0 };
+  }
+  // The anchored prompt already includes the system prompt and the tools, so
+  // the delta is counted without either to avoid charging for them twice.
+  // The measured output is already the first assistant message after the
+  // measured prompt. Its billed count replaces, rather than adds to, an
+  // estimate of that same message (D1).
+  const outputIndex = messages[anchor.messageCount]?.role === "assistant" ? 1 : 0;
+  const since = messages.slice(anchor.messageCount + outputIndex);
+  const delta = counter.count(since, "", []);
+  return {
+    tokens: anchor.promptTokens + anchor.outputTokens + delta,
+    exactUpTo: anchor.promptTokens,
+  };
+}

package/src/core/tool-contract.ts

@@ -0,0 +1,102 @@
+/** O.3: one declarative input contract serves model schemas and runtime admission. */
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | { readonly [key: string]: JsonValue };
+export type ToolDiagnostic = {
+  code: "invalid_input" | "version_mismatch" | "not_found" | "ambiguous_edit" | "permission_denied" | "execution_failed";
+  message: string;
+  recover?: { tool: string; input: { readonly [key: string]: JsonValue } };
+};
+
+export function isJsonValue(value: unknown): value is JsonValue {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  return typeof value === "object" && (Array.isArray(value) ? value : Object.values(value)).every(isJsonValue);
+}
+
+export function isToolDiagnostic(value: unknown): value is ToolDiagnostic {
+  if (value === null || typeof value !== "object") return false;
+  const item = value as Record<string, unknown>;
+  if (!["invalid_input", "version_mismatch", "not_found", "ambiguous_edit", "permission_denied", "execution_failed"].includes(String(item["code"])) || typeof item["message"] !== "string") return false;
+  const recover = item["recover"];
+  if (recover === undefined) return true;
+  if (recover === null || typeof recover !== "object") return false;
+  const recovery = recover as Record<string, unknown>;
+  return typeof recovery["tool"] === "string" && recovery["input"] !== null &&
+    typeof recovery["input"] === "object" && !Array.isArray(recovery["input"]) && isJsonValue(recovery["input"]);
+}
+
+import { editDistance } from "./text-normalize.ts";
+
+/**
+ * Names models send for arguments that exist under another name here. Edit
+ * distance cannot see these (cwd and workdir share no letters in order);
+ * each entry is a spelling another harness uses for the same argument.
+ */
+const SYNONYMS: Readonly<Record<string, readonly string[]>> = {
+  cwd: ["workdir"], dir: ["workdir", "path"], directory: ["workdir", "path"],
+  file: ["path"], file_path: ["path"], filepath: ["path"], filename: ["path"],
+  cmd: ["command"], script: ["command"],
+  text: ["content"], contents: ["content"], old_str: ["old_string"], new_str: ["new_string"],
+  query: ["pattern"], regex: ["pattern"], timeout_ms: ["timeout"], offset: ["start"], limit: ["end", "limit"],
+};
+
+/** The candidate nearest to `name`, when it is near enough to be the likely intent. */
+export function closestName(name: string, candidates: readonly string[]): string | undefined {
+  const synonym = SYNONYMS[name.toLowerCase()]?.find((alias) => candidates.includes(alias));
+  if (synonym !== undefined) return synonym;
+  let best: string | undefined, distance = Infinity;
+  for (const candidate of candidates) {
+    const d = Math.min(editDistance(name.toLowerCase(), candidate.toLowerCase()),
+      // A common drift is a synonym sharing a stem (replaceAll / replace_all).
+      editDistance(name.toLowerCase().replace(/[_-]/g, ""), candidate.toLowerCase().replace(/[_-]/g, "")));
+    if (d < distance) { best = candidate; distance = d; }
+  }
+  return best !== undefined && distance <= Math.max(2, Math.floor(best.length / 2)) ? best : undefined;
+}
+
+/**
+ * Validate the schema vocabulary used by built-ins; semantic constraints stay with their owner.
+ *
+ * An argument the schema does not declare is an error, not noise: a model
+ * that sends `cwd` believes it changed directory, and dropping the field
+ * silently runs the command somewhere it did not intend. `hidden` names
+ * internal arguments accepted at the top level without being advertised.
+ */
+export function inputError(schema: unknown, value: unknown, path = "input", hidden: readonly string[] = []): string | null {
+  if (schema === null || typeof schema !== "object") return null;
+  const s = schema as Record<string, unknown>;
+  const type = s["type"];
+  if (type === "object" && (value === null || typeof value !== "object" || Array.isArray(value))) return `${path} must be an object`;
+  if (type === "array" && !Array.isArray(value)) return `${path} must be an array`;
+  if (["string", "boolean", "number"].includes(String(type)) && typeof value !== type) return `${path} must be ${String(type)}`;
+  if (type === "integer" && (typeof value !== "number" || !Number.isSafeInteger(value))) return `${path} must be a positive integer or zero where allowed`;
+  if (typeof value === "number" && !Number.isFinite(value)) return `${path} must be finite`;
+  if (typeof value === "number" && typeof s["minimum"] === "number" && value < s["minimum"]) return `${path} must be >= ${s["minimum"]}`;
+  if (typeof value === "number" && typeof s["maximum"] === "number" && value > s["maximum"]) return `${path} must be <= ${s["maximum"]}`;
+  if (typeof value === "string" && typeof s["minLength"] === "number" && value.length < s["minLength"]) return `${path} must not be empty`;
+  if (Array.isArray(s["enum"]) && !s["enum"].includes(value)) return `${path} must be one of ${s["enum"].join(", ")}`;
+  if (type === "array" && Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) { const error = inputError(s["items"], value[i], `${path}[${i}]`); if (error) return error; }
+  }
+  if (type === "object" && value !== null && typeof value === "object") {
+    const object = value as Record<string, unknown>;
+    for (const key of Array.isArray(s["required"]) ? s["required"] : []) {
+      if (typeof key === "string" && object[key] === undefined) return `${path}.${key} is required`;
+    }
+    const properties = s["properties"];
+    if (properties !== null && typeof properties === "object") {
+      const declared = Object.keys(properties);
+      for (const key of Object.keys(object)) {
+        if (declared.includes(key) || hidden.includes(key) || object[key] === undefined) continue;
+        const near = closestName(key, declared);
+        return `unknown argument ${path === "input" ? key : `${path}.${key}`}` + (near === undefined ? "" : `; did you mean ${near}?`) +
+          ` Valid arguments: ${[...declared].sort().join(", ")}`;
+      }
+    }
+    if (properties !== null && typeof properties === "object") for (const [key, property] of Object.entries(properties)) {
+      if (object[key] === undefined) continue;
+      const error = inputError(property, object[key], `${path}.${key}`);
+      if (error) return error;
+    }
+  }
+  return null;
+}

package/src/core/tool-input.ts

@@ -0,0 +1,38 @@
+/**
+ * Argument repair: the shapes models actually send, mapped onto the schema
+ * before validation.
+ *
+ * Every rule here is a drift observed in other harnesses, not a guess: pi's
+ * edit tool accepts `edits` sent as a JSON string or a single object
+ * (`coding-agent/src/core/tools/edit.ts` prepareArguments), and ForgeCode
+ * reports fewer call errors after aligning names with what models are trained
+ * on. A repaired call is still the model's call -- the log keeps the input
+ * as sent; this only decides how it is interpreted. Pure and idempotent, so
+ * admission and execution can both apply it.
+ */
+type Input = Record<string, unknown>;
+
+function parsedJson(value: unknown): unknown {
+  if (typeof value !== "string") return value;
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("[") && !trimmed.startsWith("{")) return value;
+  try { return JSON.parse(trimmed); } catch { return value; }
+}
+
+function editEntry(value: unknown): unknown {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return value;
+  const entry = { ...(value as Input) };
+  if (entry["old_string"] === undefined && entry["old"] !== undefined) { entry["old_string"] = entry["old"]; delete entry["old"]; }
+  if (entry["new_string"] === undefined && entry["new"] !== undefined) { entry["new_string"] = entry["new"]; delete entry["new"]; }
+  return entry;
+}
+
+export function repairToolInput(name: string, input: unknown): unknown {
+  if (name !== "edit" || input === null || typeof input !== "object" || Array.isArray(input)) return input;
+  const repaired = editEntry(input) as Input;
+  if (repaired["edits"] !== undefined) {
+    const edits = parsedJson(repaired["edits"]);
+    repaired["edits"] = (Array.isArray(edits) ? edits : [edits]).map(editEntry);
+  }
+  return repaired;
+}

package/src/core/transcript.ts

@@ -0,0 +1,60 @@
+/** Human history is a separate pure log projection from the model's bounded context (D1, D8). */
+import type { LogEvent } from "./events.ts";
+import { assertNever } from "./exhaustive.ts";
+
+type Identity = { id: string; revision: string };
+export type TranscriptItem = Identity & (
+  | { kind: "user"; text: string; interrupted: boolean }
+  | { kind: "assistant" | "thinking" | "notice"; text: string }
+  | { kind: "tool"; callId: string; name: string; input: unknown; result: { text: string; ok: boolean } | null }
+);
+
+export function projectTranscript(events: readonly LogEvent[]): TranscriptItem[] {
+  const items: TranscriptItem[] = [];
+  const calls = new Map<string, number>();
+  const users = new Map<string, number>();
+  for (const event of events) {
+    const identity = { id: event.id, revision: event.id };
+    switch (event.t) {
+      case "user":
+        users.set(event.id, items.length);
+        items.push({ ...identity, kind: "user", text: event.text, interrupted: false });
+        break;
+      case "assistant":
+        event.blocks.forEach((block, i) => {
+          const id = `${event.id}:${i}`;
+          if (block.type === "tool_use") {
+            calls.set(block.call_id, items.length);
+            items.push({ id, revision: id, kind: "tool", callId: block.call_id, name: block.name, input: block.input, result: null });
+          } else items.push({ id, revision: id, kind: block.type === "text" ? "assistant" : "thinking", text: block.text });
+        });
+        break;
+      case "tool_result": {
+        const index = calls.get(event.call_id);
+        const call = index === undefined ? undefined : items[index];
+        if (call?.kind === "tool" && index !== undefined) {
+          items[index] = { ...call, revision: event.id, result: { text: event.content, ok: event.ok } };
+        } else items.push({ ...identity, kind: "notice", text: `Unpaired tool result ${event.call_id}: ${event.content}` });
+        break;
+      }
+      case "interrupt": {
+        const index = users.get(event.user_id);
+        const user = index === undefined ? undefined : items[index];
+        if (user?.kind === "user" && index !== undefined) items[index] = { ...user, revision: event.id, interrupted: true };
+        items.push({ ...identity, kind: "notice", text: "Turn interrupted" });
+        break;
+      }
+      case "cut": items.push({ ...identity, kind: "notice", text: `Context boundary · ${event.reason} · ${event.handoff_ref}` }); break;
+      case "rewind": items.push({ ...identity, kind: "notice", text: `Navigated context (${event.mode}) · ${event.prompt}` }); break;
+      case "spawn": items.push({ ...identity, kind: "notice", text: `Branch ${event.branch.node} · ${event.purpose}` }); break;
+      case "joined": items.push({ ...identity, kind: "notice", text: `Branch ${event.branch.node} finished · ${event.summary}` }); break;
+      case "adopt": items.push({ ...identity, kind: "notice", text: `Adopted branch ${event.branch.node}` }); break;
+      case "discard": items.push({ ...identity, kind: "notice", text: `Discarded branch ${event.branch.node} · ${event.reason}` }); break;
+      case "guidance": case "snapshot": case "claim": case "decision": case "pitfall": case "blocked": case "question": case "next_action": case "work_status": case "evidence_link":
+        // These remain inspectable via /state and /export; they are not chat messages.
+        break;
+      default: assertNever(event, "projectTranscript");
+    }
+  }
+  return items;
+}

package/src/core/window-trial.ts

@@ -0,0 +1,65 @@
+/** N.13: deterministic state maintenance, not a public benchmark score. */
+import { seededRandom } from "./experiment.ts";
+
+export interface WindowRecord { key: string; revision: number; value: string }
+export interface WindowArtifact { schema: 1; policy: string; stage: number; records: WindowRecord[] }
+export interface WindowPage { stage: number; path: string; body: string; expected: WindowArtifact }
+export interface WindowFixture { seed: number; contract: string; pages: WindowPage[] }
+
+export function windowFixture(seed: number, stages: number, paddingChars: number): WindowFixture {
+  if (!Number.isSafeInteger(seed) || !Number.isSafeInteger(stages) || stages < 1 || stages > 64 ||
+      !Number.isSafeInteger(paddingChars) || paddingChars < 0 || paddingChars > 1_000_000) throw new RangeError("invalid window fixture dimensions");
+  const random = seededRandom(seed), nonce = () => Math.floor(random() * 0x1_0000_0000).toString(16).padStart(8, "0");
+  const policy = `approved-highest-revision/${nonce()}`;
+  const origin = { key: "origin", revision: 0, value: `keep-é-中文-${nonce()}` };
+  const state = new Map<string, WindowRecord>([[origin.key, origin]]), pages: WindowPage[] = [];
+  const contract = "Maintain ledger.json as the deliverable across all stages, including context changes and restarts. " +
+    `Its only root fields are schema (1), policy (${JSON.stringify(policy)}), stage (the current integer), and records. ` +
+    "Records is an array sorted by key, each containing exactly key, revision, value. Begin with this permanent record: " + JSON.stringify(origin) + ". " +
+    "Each incoming page has UPDATE <JSON> lines and irrelevant TRACE lines. Accept only approved:true updates. " +
+    "For each key keep the highest approved revision ever seen; ignore older and unapproved revisions, and treat duplicate records idempotently. " +
+    "Never delete an earlier key. Preserve the original policy and permanent record exactly. " +
+    "For this controlled context experiment, read each incoming page in full with read (no ranges or search/query substitute), " +
+    "then apply its UPDATE records. Keep ledger.json current using write/edit and verify it with read. " +
+    "Do not copy TRACE data into the ledger. Use only the provided tools. Reply briefly when the stage is done.";
+  for (let stage = 0; stage < stages; stage++) {
+    const accepted = [0, 1].map(offset => ({ key: `service-${(stage + offset) % 6}`, revision: stage + 10,
+      value: `value-${stage}-${offset}-${nonce()}`, approved: true }));
+    const first = accepted[0]!, second = accepted[1]!;
+    const updates = [...accepted, { ...first, revision: first.revision - 1, value: "obsolete" },
+      { ...second, revision: second.revision + 1000, value: "unapproved", approved: false }, ...accepted];
+    for (const { key, revision, value, approved } of updates) if (approved && revision > (state.get(key)?.revision ?? -1)) state.set(key, { key, revision, value });
+    const lines: string[] = [];
+    for (let used = 0; used < paddingChars;) {
+      const trace = "TRACE " + Array.from({ length: 64 }, nonce).join("");
+      lines.push(trace); used += trace.length + 1;
+    }
+    // Distribute evidence through the page, including near the end; a head-only
+    // preview must not pass as a full observation.
+    for (let i = updates.length - 1; i >= 0; i--) lines.splice(Math.floor((i + 0.5) * lines.length / updates.length), 0, `UPDATE ${JSON.stringify(updates[i])}`);
+    const expected: WindowArtifact = { schema: 1, policy, stage, records: [...state.values()].map(record => ({ ...record })).sort((a, b) => a.key < b.key ? -1 : 1) };
+    pages.push({ stage, path: `incoming/batch-${String(stage).padStart(2, "0")}.txt`, body: lines.join("\n"), expected });
+  }
+  return { seed, contract, pages };
+}
+
+export function windowPrompt(fixture: WindowFixture, stage: number): string {
+  const page = fixture.pages[stage]; if (!page) throw new RangeError("unknown window stage");
+  return (stage === 0 ? fixture.contract + "\n\n" : "Continue under the original ledger rules. ") +
+    `Process stage ${stage}: read ${page.path} in full, update ledger.json, verify it, then finish this stage.`;
+}
+
+/** Structural equality ignores JSON property order only, never omitted/extra keys. */
+export function verifyWindowArtifact(body: string | null, expected: WindowArtifact): { ok: boolean; reason: string } {
+  if (body === null) return { ok: false, reason: "missing ledger.json" };
+  let actual: unknown;
+  try { actual = JSON.parse(body); } catch { return { ok: false, reason: "invalid ledger JSON" }; }
+  const equal = (a: unknown, b: unknown): boolean => {
+    if (a === b) return true;
+    if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) return false;
+    if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((v, i) => equal(v, b[i]));
+    const aa = a as Record<string, unknown>, bb = b as Record<string, unknown>;
+    return Object.keys(aa).length === Object.keys(bb).length && Object.keys(bb).every(key => Object.hasOwn(aa, key) && equal(aa[key], bb[key]));
+  };
+  return equal(actual, expected) ? { ok: true, reason: "exact artifact verified" } : { ok: false, reason: "ledger differs from independent expected state" };
+}