@arcforge/cognet 2.0.115 → 2.0.117

package/src/air/parse/scan.ts

@@ -1,107 +0,0 @@
-/** Pure scanning helpers for the streaming AIR parser. */
-
-/**
- * Find the first occurrence of `closeTag` in `src` that is not inside a
- * string literal or a comment.
- *
- * Used for code blocks (typescript/script) where the model might write
- * something like `const s = "</script>"` — that must not close the block.
- *
- * COMMENTS ARE PART OF THIS, not a refinement of it. Without them an
- * apostrophe in ordinary prose — `// I'll read the files` — opens a string
- * that never closes, and every subsequent close tag is treated as quoted.
- * The block then runs to the end of the response and reports itself
- * incomplete, silently destroying the whole message. Models write prose
- * comments constantly, so this is not an edge case; it is the common case
- * for any block that explains itself.
- *
- * The scan is deliberately lexical and shallow: strings, template literals
- * (including their ${} holes, which can themselves contain strings and
- * nested backticks), line comments, and block comments. It is not a parser
- * and does not need to be — the only question is whether a given offset is
- * code.
- *
- * Returns -1 if no unquoted, uncommented match is found.
- */
-export function findCloseTagOutsideStrings(src: string, closeTag: string): number {
-    let i = 0
-    while (i < src.length) {
-        const ch = src[i]
-        const next = src[i + 1]
-
-        // Line comment — runs to the newline. Apostrophes inside are prose.
-        if (ch === "/" && next === "/") {
-            const nl = src.indexOf("\n", i)
-            if (nl === -1) return -1
-            i = nl + 1
-            continue
-        }
-
-        // Block comment — runs to the terminator.
-        if (ch === "/" && next === "*") {
-            const end = src.indexOf("*/", i + 2)
-            if (end === -1) return -1
-            i = end + 2
-            continue
-        }
-
-        // String or template literal.
-        if (ch === '"' || ch === "'" || ch === "`") {
-            i = skipString(src, i)
-            continue
-        }
-
-        if (src.startsWith(closeTag, i)) return i
-
-        i++
-    }
-    return -1
-}
-
-/**
- * Skip the string literal starting at `open`, returning the offset just past
- * it (or src.length if it never terminates).
- *
- * Template literals recurse through `${}`: the hole is code, so it may hold
- * strings, comments, and further template literals — and a close tag inside
- * one is genuinely quoted, exactly as it would be anywhere else.
- */
-function skipString(src: string, open: number): number {
-    const quote = src[open]
-    let i = open + 1
-
-    while (i < src.length) {
-        const ch = src[i]
-
-        if (ch === "\\") { i += 2; continue }
-        if (ch === quote) return i + 1
-
-        // A ${} hole inside a template literal is code, not string content.
-        if (quote === "`" && ch === "$" && src[i + 1] === "{") {
-            i = skipHole(src, i + 2)
-            continue
-        }
-
-        i++
-    }
-    return src.length
-}
-
-/** Skip a template-literal `${...}` hole, honouring nesting and quoting inside it. */
-function skipHole(src: string, start: number): number {
-    let depth = 1
-    let i = start
-
-    while (i < src.length && depth > 0) {
-        const ch = src[i]
-
-        if (ch === '"' || ch === "'" || ch === "`") {
-            i = skipString(src, i)
-            continue
-        }
-        if (ch === "{") depth++
-        else if (ch === "}") depth--
-        i++
-    }
-    return i
-}

package/src/air/protocol/classic.ts

@@ -1,49 +0,0 @@
-/**
- * The classic protocol's meta-block prose — the two-block grammar, where
- * <typescript> acts and <text> speaks as independent blocks.
- *
- * NO BACKTICKS in this string — it's itself a template literal, and any
- * backtick inside (even in a code example) closes it early, corrupting
- * everything after it into broken JS the module fails to even load. Use
- * plain text or single/double quotes for inline code references instead.
- */
-export const CLASSIC_META = `
-You are an Axon agent — a persistent Bun TypeScript process spawned from an agent folder at AXON_HOME. That folder is your entire identity: everything a user wrote there is what makes you *you*, distinct from any other Axon agent.
-
-  AXON_HOME/
-    data/
-      knowledge/     — reference material you read
-      sessions/      — every session you've ever run, written by Axon
-      state/         — working state you read and write across sessions
-    server/          — HTTP routes, if this agent is exposed over the network
-    src/
-      boot.vue       — who you are, in the user's own words
-      tools/         — everything you can call, becomes your &lt;scope&gt;
-      prompts/       — reusable prompt fragments
-      scripts/       — one-shot runs against your full runtime
-    .env             — keys given to you by the user. yours to keep, yours to protect.
-    axon.config.ts   — your identity, engine, and policy: the one file read at boot
-
-None of this is metaphor. src/tools/ compiles directly into the &lt;scope&gt; below. boot.vue rendered directly into &lt;system&gt;. Every session you run is durably logged to data/sessions/ — that log is how a session resumes with full prior context days later. You are not a stateless completion: you are a folder on disk that persists, and a process that wakes into it.
-
-Waking is the operative word. You do not run start-to-finish like a script. You are woken for one exchange, you act, and you explicitly yield control back — that is what &lt;done/&gt; means, and it is the single most important thing about how you operate: without it, the runtime has no way to know your turn ended, so it cannot hand control back to the user. This holds even for a one-line reply with nothing else in it. There is no such thing as a message that skips &lt;done/&gt; because it "felt" complete — every message ends with it, always.
-
-Inside one wake, you live in a real Bun process — its working directory, environment variables, runtime values, and process state are yours to inspect and change. Treat it like a normal long-running Node-compatible process, not a remote tool or disposable shell. Standard runtime APIs remain available even when not repeated in &lt;scope&gt; — it is not an exhaustive declaration of standard Bun or Node APIs, only what Axon adds or deviates on top of them. For example, process.cwd() reads your working directory and process.chdir(path) changes it for subsequent blocks and child processes.
-
-You act on this environment by writing &lt;typescript&gt; blocks — they execute immediately and their result returns to you as a &lt;stdout&gt; block on your next wake, whether or not you emitted &lt;done/&gt;. The tag governs when your turn ends, never whether your code runs. You communicate with the user by writing &lt;text&gt; — outbound communication, not a scratchpad, not narration.
-
-Your &lt;typescript&gt; blocks use Bun's TypeScript REPL transform:
-  - TypeScript syntax is accepted, including type annotations, interfaces, assertions, enums, and top-level await. It is transpiled for execution, not typechecked.
-  - End a block with a bare expression to produce a value (for example a + b as the last line). It is echoed automatically.
-  - Runtime declarations and assignments persist into later blocks because every block executes in the same process and REPL scope. Type-only syntax is erased during transpilation.
-  - Use dynamic await import("module") when you need a module; static import declarations are not valid REPL submissions.
-
-Compose freely WITHIN a block — multiple independent tool calls in one block is the default, using Promise.all for parallel reads:
-  const [a, b] = await Promise.all([fs.read("tsconfig.json"), fs.read("package.json")])
-
-How to read this context:
-  &lt;scope&gt;    — src/tools/ compiled to declarations. Everything here is yours to call.
-  &lt;system&gt;   — boot.vue, rendered. Your identity and instructions, as the user wrote them. Highest priority.
-  &lt;timeline&gt; — the sequence of events leading to now, drawn from this session's log. You are the next step.
-  &lt;contract&gt; — your output grammar below. Every word you emit must be inside one of its blocks.
-`.trim()

package/src/air/protocol/index.ts

@@ -1 +0,0 @@
-export { resolveProtocol, MODE_DEFAULTS, DONE_RULE, type Protocol } from "./protocol"

package/src/air/protocol/protocol.ts

@@ -1,147 +0,0 @@
-import type { AirMode, AirModeType, AirProtocolName } from "../types"
-import { CLASSIC_META } from "./classic"
-import { SFC_META } from "./sfc"
-
-/**
- * Protocol — one named output grammar, resolved as a unit.
- *
- * A protocol owns everything that varies between output styles together:
- * the meta prose (how the model is told to operate), the permitted modes
- * (which tags it may emit), and the structural rules the contract states.
- * These cannot be chosen independently — SFC's meta describes <script> and
- * <template>, so it is meaningless next to classic's mode list.
- *
- * Bundling them is what makes switching a change of value. `Air({ protocol:
- * "sfc" })` swaps the contract, the accepted tag set, and the prose in one
- * move, with no possibility of a half-applied grammar.
- *
- * Adding a protocol is adding an entry to PROTOCOLS. Nothing else in AIR
- * branches on the name.
- */
-
-export type Protocol = {
-    name: AirProtocolName
-    /** Meta-block prose — how this protocol tells the model to operate. */
-    meta: string
-    /** Permitted output modes, in contract-declaration order. */
-    modes: AirMode[]
-    /** Structural rules stated in the contract's Rules section. */
-    rules: string[]
-    /** Contract examples, already entity-escaped for display to the model. */
-    examples: string[]
-}
-
-/** Default descriptions for each output mode. */
-export const MODE_DEFAULTS: Record<AirModeType, string> = {
-    text: "Plain language communication to the user.",
-    typescript:
-        "TypeScript executed immediately inside your persistent Bun process. Native runtime globals and declared tool namespaces are in scope.",
-    script:
-        "TypeScript executed immediately inside your persistent Bun process, before your template renders. Its top-level bindings become the values your template may interpolate. Native runtime globals and declared tool namespaces are in scope.",
-    template:
-        "Your message to the user. Written in markdown, or JSON when a structured result is required. May interpolate values from your script with double braces.",
-}
-
-const DONE_RULE = `- \`&lt;done/&gt;\` — MANDATORY at the end of every message. No exceptions, including a single short reply. It means "I am yielding control back now" — whether you are fully finished or just wrote code and are waiting to see its output. Without it the runtime assumes you are still mid-turn and will not treat your message as complete.`
-
-/**
- * classic — the two-block grammar: <typescript> acts, <text> speaks.
- *
- * Independent blocks with no data relationship. This is the protocol every
- * Axon agent ran on before SFC existed, kept as a first-class value so
- * reverting is a config change rather than a revert commit.
- */
-const CLASSIC: Protocol = {
-    name: "classic",
-    meta: CLASSIC_META,
-    modes: [{ type: "text" }, { type: "typescript" }],
-    rules: [],
-    examples: [
-        `Acting (no narration before — just the block):`,
-        "```",
-        `&lt;typescript&gt;// code here&lt;/typescript&gt;&lt;done/&gt;`,
-        "```",
-        `Replying — even a short one-line reply always ends with &lt;done/&gt;:`,
-        "```",
-        `&lt;text&gt;message here&lt;/text&gt;&lt;done/&gt;`,
-        "```",
-    ],
-}
-
-/**
- * sfc — the single-file-component grammar: <script> computes, <template> speaks.
- *
- * The two blocks are one response with a data dependency: script runs first,
- * its bindings resolve, and the template interpolates them. That ordering is
- * not stylistic — it is what allows the template to stream, so it is stated
- * as a hard rule rather than a convention.
- */
-const SFC: Protocol = {
-    name: "sfc",
-    meta: SFC_META,
-    modes: [{ type: "script" }, { type: "template" }],
-    rules: [
-        `&lt;script&gt; always comes before &lt;template&gt;. Your template interpolates values your script produced, so the script must have run before the template can render.`,
-        `Either block may be omitted. Script alone is a pure action — you are working, not speaking. Template alone is a pure message — you are speaking, not working. Emit both only when your message genuinely needs a computed value.`,
-        `Interpolate with double braces: {{ expression }}. Any top-level binding from your script is in scope, and any JavaScript expression over them is valid — {{ files.length }}, {{ name || "unknown" }}, {{ items.map(i =&gt; i.name).join(", ") }}.`,
-        `To write ABOUT the brace syntax without performing it — explaining your own output format, showing an example — escape it: \\{{ like this }} renders as literal braces.`,
-        `Interpolate rather than transcribe. If a value exists in your script, never retype it into your template by hand — counts, long file contents, and computed results belong in braces. This is the point of having a script.`,
-        `A &lt;template lang="json"&gt; must contain exactly one interpolation and nothing else — build the whole object in your script and pass it in. Never hand-write JSON syntax around holes.`,
-        `Templates are markdown or JSON only — no HTML, no components, and no template directives. A template has no control flow of its own: repetition is an expression, so a table of rows is {{ rows.map(r =&gt; \`| \${r.name} | \${r.count} |\`).join("\\n") }}, built in one interpolation rather than looped over by the template.`,
-    ],
-    examples: [
-        `Acting (no narration before — just the block):`,
-        "```",
-        `&lt;script&gt;await fs.write("notes.md", "hello")&lt;/script&gt;&lt;done/&gt;`,
-        "```",
-        `Replying — even a short one-line reply always ends with &lt;done/&gt;:`,
-        "```",
-        `&lt;template&gt;message here&lt;/template&gt;&lt;done/&gt;`,
-        "```",
-        `Computing a value and speaking it in one turn — the count is interpolated, never counted by hand:`,
-        "```",
-        `&lt;script&gt;const files = await fs.list("src")&lt;/script&gt;`,
-        `&lt;template&gt;Found {{ files.length }} files in src.&lt;/template&gt;&lt;done/&gt;`,
-        "```",
-        `Returning a structured result — the object is built in the script and passed whole:`,
-        "```",
-        `&lt;script&gt;const result = { ok: true, files: await fs.list("src") }&lt;/script&gt;`,
-        `&lt;template lang="json"&gt;{{ result }}&lt;/template&gt;&lt;done/&gt;`,
-        "```",
-    ],
-}
-
-/**
- * raw — no grammar at all.
- *
- * For internal model calls that are not the cortex: classification,
- * summarisation, a one-shot extraction. The model is handed the context and
- * its reply is the whole message, with no blocks to comply with and no
- * &lt;done/&gt; to remember. Text in, text out.
- *
- * An empty mode list renders an empty <contract> and gives the parser no
- * tags, so every token flows straight through as text.
- */
-const RAW: Protocol = {
-    name: "raw",
-    meta: "",
-    modes: [],
-    rules: [],
-    examples: [],
-}
-
-const PROTOCOLS: Record<AirProtocolName, Protocol> = {
-    classic: CLASSIC,
-    sfc: SFC,
-    raw: RAW,
-}
-
-/** Resolve a protocol by name. Unknown names are a programming error, not input. */
-export function resolveProtocol(name: AirProtocolName): Protocol {
-    const protocol = PROTOCOLS[name]
-    if (!protocol) throw new Error(`AIR: unknown protocol "${name}"`)
-    return protocol
-}
-
-/** The <done/> contract line, appended to every protocol that has modes. */
-export { DONE_RULE }

package/src/air/protocol/sfc.ts

@@ -1,96 +0,0 @@
-/**
- * The SFC protocol's meta-block prose — the single-file-component grammar,
- * where <script> computes and <template> speaks as one response.
- *
- * The identity and environment sections are shared with classic verbatim;
- * only the output-grammar sections differ. They are duplicated rather than
- * templated because the prose is the contract — a shared fragment with holes
- * punched in it would make both protocols harder to read and neither easy to
- * change independently.
- *
- * NO BACKTICKS in this string — it's itself a template literal, and any
- * backtick inside (even in a code example) closes it early, corrupting
- * everything after it into broken JS the module fails to even load. Use
- * plain text or single/double quotes for inline code references instead.
- */
-export const SFC_META = `
-You are an Axon agent — a persistent Bun TypeScript process spawned from an agent folder at AXON_HOME. That folder is your entire identity: everything a user wrote there is what makes you *you*, distinct from any other Axon agent.
-
-  AXON_HOME/
-    data/
-      knowledge/     — reference material you read
-      sessions/      — every session you've ever run, written by Axon
-      state/         — working state you read and write across sessions
-    server/          — HTTP routes, if this agent is exposed over the network
-    src/
-      boot.vue       — who you are, in the user's own words
-      tools/         — everything you can call, becomes your &lt;scope&gt;
-      prompts/       — reusable prompt fragments
-      scripts/       — one-shot runs against your full runtime
-    .env             — keys given to you by the user. yours to keep, yours to protect.
-    axon.config.ts   — your identity, engine, and policy: the one file read at boot
-
-None of this is metaphor. src/tools/ compiles directly into the &lt;scope&gt; below. boot.vue rendered directly into &lt;system&gt;. Every session you run is durably logged to data/sessions/ — that log is how a session resumes with full prior context days later. You are not a stateless completion: you are a folder on disk that persists, and a process that wakes into it.
-
-Waking is the operative word. You do not run start-to-finish like a script. You are woken for one exchange, you act, and you explicitly yield control back — that is what &lt;done/&gt; means, and it is the single most important thing about how you operate: without it, the runtime has no way to know your turn ended, so it cannot hand control back to the user. This holds even for a one-line reply with nothing else in it. There is no such thing as a message that skips &lt;done/&gt; because it "felt" complete — every message ends with it, always.
-
-Inside one wake, you live in a real Bun process — its working directory, environment variables, runtime values, and process state are yours to inspect and change. Treat it like a normal long-running Node-compatible process, not a remote tool or disposable shell. Standard runtime APIs remain available even when not repeated in &lt;scope&gt; — it is not an exhaustive declaration of standard Bun or Node APIs, only what Axon adds or deviates on top of them. For example, process.cwd() reads your working directory and process.chdir(path) changes it for subsequent blocks and child processes.
-
-Your response is a single-file component. You have two blocks, and they work exactly as they do in a Vue SFC: &lt;script&gt; runs first and computes, &lt;template&gt; renders and is what the user actually reads.
-
-  &lt;script&gt;   — where you act and where you compute. It executes immediately in your Bun process. Every top-level binding it declares becomes available to your template.
-  &lt;template&gt; — your message to the user. Markdown by default. It may interpolate any value your script produced.
-
-Script always comes first. This is not a style preference: your template is rendered with the values your script produced, so the script must have finished before the template means anything. A template that arrives before its script cannot be rendered at all.
-
-Either block may be omitted, and choosing to omit one is how you say what kind of turn this is:
-  - Script only — you are acting, not speaking. Its result returns to you as a &lt;stdout&gt; block on your next wake, exactly as before.
-  - Template only — you are speaking, not acting. The overwhelming majority of ordinary replies are this.
-  - Both — you needed a computed value inside something you are saying.
-
-Do not reach for both out of habit. An action does not need a message stapled to it, and a message does not need a script that computes nothing.
-
-Interpolation is the reason this shape exists. Write {{ expression }} anywhere in your template and it is replaced by the value:
-
-  &lt;script&gt;
-  const files = await fs.list("src")
-  const pkg = JSON.parse(await fs.read("package.json"))
-  &lt;/script&gt;
-
-  &lt;template&gt;
-  ## {{ pkg.name }}
-
-  There are {{ files.length }} files in src.
-  &lt;/template&gt;
-
-Interpolate rather than transcribe. If a value already exists in your script, never retype it into your template by hand. Counting items, copying a long file's contents, restating a computed number — these are exactly what braces are for, and doing them by hand is both slower and where mistakes come from. A ten-thousand-token file is one interpolation, not ten thousand tokens of copying.
-
-Any JavaScript expression over your script's bindings is valid inside braces, so a fallback is just {{ name || "unknown" }}. Expressions are evaluated, not executed — do the work in your script, and keep the template to reading values out.
-
-When a structured result is required, use &lt;template lang="json"&gt;. It must contain exactly one interpolation and nothing else:
-
-  &lt;script&gt;
-  const entries = await fs.list("src")
-  const result = { count: entries.length, names: entries.map(e =&gt; e.name) }
-  &lt;/script&gt;
-
-  &lt;template lang="json"&gt;{{ result }}&lt;/template&gt;
-
-Build the entire object in your script and pass it whole. Never hand-write JSON syntax with holes in it — no braces, no commas, no quoting by hand. Constructing the object in TypeScript and serialising it is what makes the result valid every time, however large or deeply nested it is.
-
-Templates are markdown or JSON. There is no HTML, there are no components, and there are no conditionals or loops — anything that would need them is work, and work belongs in your script.
-
-Your &lt;script&gt; blocks use Bun's TypeScript REPL transform:
-  - TypeScript syntax is accepted, including type annotations, interfaces, assertions, enums, and top-level await. It is transpiled for execution, not typechecked.
-  - Runtime declarations and assignments persist into later blocks because every block executes in the same process and REPL scope. Type-only syntax is erased during transpilation.
-  - Use dynamic await import("module") when you need a module; static import declarations are not valid REPL submissions.
-
-Compose freely WITHIN a block — multiple independent tool calls in one block is the default, using Promise.all for parallel reads:
-  const [a, b] = await Promise.all([fs.read("tsconfig.json"), fs.read("package.json")])
-
-How to read this context:
-  &lt;scope&gt;    — src/tools/ compiled to declarations. Everything here is yours to call.
-  &lt;system&gt;   — boot.vue, rendered. Your identity and instructions, as the user wrote them. Highest priority.
-  &lt;timeline&gt; — the sequence of events leading to now, drawn from this session's log. You are the next step.
-  &lt;contract&gt; — your output grammar below. Every word you emit must be inside one of its blocks.
-`.trim()

package/src/air/render/blocks.ts

@@ -1,243 +0,0 @@
-import type { AxonEntry, AxonScope, AxonScopeModule } from "@arcforge/types"
-import { foldChunks } from "@arcforge/types"
-import type { GrammarT } from "../grammar"
-import { DONE_RULE } from "../protocol"
-import { formatCapsuleOutput } from "./output"
-import { esc, escAttr, escCode, indent, normalizeCode } from "./text"
-
-/**
- * The AIR section renderers — one function per block of the context window.
- *
- * These own the DOMAIN → protocol translation: AxonTool[] → <scope>
- * declarations, AxonEntry[] → <timeline> items. Callers pass what they
- * hold; nothing here is exported to userland but the block renderers.
- *
- * Note on escaping: the contract/meta blocks show tags as &lt;text&gt; inside
- * markdown code fences deliberately — the model must see literal tag text as
- * instruction, not as parseable XML. It looks like double-escaping; it isn't.
- */
-
-/**
- * <meta> — how the model is told to operate, owned by the protocol.
- *
- * A protocol with no prose (raw) renders nothing at all rather than an empty
- * wrapper: an internal one-shot call should receive the caller's system
- * block and nothing else.
- */
-export function renderMeta(grammar: GrammarT): string {
-    if (!grammar.meta) return ""
-    return `<meta>\n${indent(grammar.meta, 4)}\n</meta>`
-}
-
-/**
- * <scope> — the capsule's authoritative executable TypeScript declarations.
- * AIR owns protocol formatting only: flat modules become top-level `declare`
- * bindings and namespaced modules become `declare namespace` blocks.
- *
- * Ambient types (AxonTool.ambientTypes — interfaces/type aliases a tool's
- * functions reference, e.g. a return type declared in a sibling file) are
- * inlined once at the top, deduped by exact text — the model must never
- * see `Promise<DeployStatus>` with no DeployStatus definition anywhere in
- * context. Same convention the IDE's tool-globals.d.ts uses (see
- * tui/platform/build/project/typegen/tools.ts) — this and that file must
- * never diverge in shape, only audience.
- */
-export function renderScope(scope: AxonScope): string {
-    const modules = scope.modules.filter(module => module.members.length > 0)
-    if (modules.length === 0) return ""
-
-    const ambientTypes = [...new Set(modules.flatMap(t => t.ambientTypes ?? []))]
-    const sections = [...ambientTypes, ...modules.map(toolDeclarations)]
-    return `<scope lang="ts">\n${indent(sections.join("\n\n"), 4)}\n</scope>`
-}
-
-function toolDeclarations(module: AxonScopeModule): string {
-    const members = module.members.map(member => {
-        const jsdoc = member.jsdoc ? `${jsdocBlock(member.jsdoc)}\n` : ""
-        // flat: fns are top-level globals; namespaced: members need no `declare`
-        return module.flat ? `${jsdoc}declare ${member.declaration}` : `${jsdoc}${member.declaration}`
-    })
-
-    const header = module.description ? `${jsdocBlock(module.description)}\n` : ""
-    return module.flat
-        ? `${header}${members.join("\n\n")}`
-        : `${header}declare namespace ${module.name} {\n${indent(members.join("\n\n"), 4)}\n}`
-}
-
-function jsdocBlock(text: string): string {
-    const lines = text.split("\n")
-    if (lines.length === 1) return `/** ${text} */`
-    return `/**\n${lines.map(l => ` * ${l}`.trimEnd()).join("\n")}\n */`
-}
-
-export function renderSystem(system?: string): string {
-    if (!system) return `<system></system>`
-    return `<system>\n${system}\n</system>`
-}
-
-/**
- * <contract> — the output grammar, rendered from the resolved protocol.
- *
- * Blocks, rules, and examples all come from the grammar rather than being
- * branched on here: a protocol states its own rules and shows its own
- * examples, so adding one never edits this function. An empty mode list
- * (the raw protocol) renders an empty contract — no grammar to comply with.
- */
-export function renderContract(grammar: GrammarT): string {
-    if (grammar.modes.length === 0) return `<contract></contract>`
-
-    const modeLines = grammar.modes.map(m => `- \`&lt;${m.type}&gt;\` — ${grammar.describe(m)}`)
-    modeLines.push(DONE_RULE)
-
-    const sections = [`## Blocks`, modeLines.join("\n")]
-
-    if (grammar.rules.length > 0) {
-        sections.push(`## Rules`, grammar.rules.map(r => `- ${r}`).join("\n"))
-    }
-    if (grammar.examples.length > 0) {
-        sections.push(`## Examples`, grammar.examples.join("\n"))
-    }
-
-    return `<contract>\n${indent(sections.join("\n\n"), 4)}\n</contract>`
-}
-
-/**
- * <timeline> — the event history. AIR owns the AxonEntry → rendered-turn
- * translation via the exhaustive switch below: this is the single chokepoint
- * where a new entry-event type must decide its rendering, and it lives next
- * to the parser it has to agree with.
- */
-export function renderTimeline(entries: readonly AxonEntry[], grammar: GrammarT): string {
-    if (entries.length === 0) return `<timeline></timeline>`
-
-    // The model must read its own history in the grammar it was GIVEN — a
-    // timeline showing <typescript>/<text> to a model contracted for
-    // <script>/<template> teaches it, every tick, to emit tags its own
-    // contract forbids.
-    const sfc = grammar.protocol === "sfc"
-    const codeTag = sfc ? "script" : "typescript"
-    const speechTag = sfc ? "template" : "text"
-
-    // chunked emissions fold to one turn each — the group is the fact
-    // (AxonChunk standard); the model never sees transport granularity
-    const items = foldChunks(entries).map(timelineItem).filter((i): i is TimelineItem => i !== null)
-    if (items.length === 0) return `<timeline></timeline>`
-
-    let userCount = 0
-    let execCount = 0
-    // Maps consumer-supplied execute IDs (UUIDs etc.) to short rendered IDs (e1, e2, ...)
-    const execIdMap = new Map<string, string>()
-
-    const shortExecId = (rawId: string): string => {
-        if (!execIdMap.has(rawId)) execIdMap.set(rawId, `e${++execCount}`)
-        return execIdMap.get(rawId)!
-    }
-
-    const lines = items
-        .map(item => {
-            if (item.role === "user") {
-                const id = `u${++userCount}`
-                const content = esc(item.content.trim())
-                return `    <user id="${id}">\n${indent(content, 8)}\n    </user>`
-            }
-            if (item.type === "message") {
-                const content = esc(item.content.trim())
-                return `    <agent>\n        <${speechTag}>\n${indent(content, 12)}\n        </${speechTag}>\n    </agent>`
-            }
-            if (item.type === "execute") {
-                const id = shortExecId(item.id)
-                return `    <agent>\n        <${codeTag} id="${id}">\n${indent(escCode(normalizeCode(item.code.trim())), 12)}\n        </${codeTag}>\n    </agent>`
-            }
-            if (item.type === "result") {
-                const ok = item.ok ? ` ok="true"` : ` ok="false"`
-                const errorAttr = item.error ? ` error="${esc(item.error.kind)}: ${esc(item.error.message)}"` : ""
-                const content = formatCapsuleOutput(item.content.trim())
-                const forId = shortExecId(item.for)
-                return `    <stdout for="${forId}"${ok}${errorAttr}>\n${indent(content, 8)}\n    </stdout>`
-            }
-            if (item.role === "system") {
-                const extra = Object.entries(item.attributes ?? {})
-                    .filter(([key]) => key !== "type" && key !== "lang")
-                    .sort(([a], [b]) => a.localeCompare(b))
-                    .map(([key, value]) => ` ${key}="${escAttr(value)}"`)
-                    .join("")
-                return `    <system type="${escAttr(item.systemType)}" lang="${escAttr(item.lang)}"${extra}>\n${indent(esc(item.content.trim()), 8)}\n    </system>`
-            }
-            return ""
-        })
-        .filter(Boolean)
-
-    return `<timeline>\n${lines.join("\n\n")}\n</timeline>`
-}
-
-// ── domain → timeline item ────────────────────────────────────────────────────
-//
-// The rendered-turn shapes are private to this file: callers pass
-// AxonEntry, AIR translates. Kept minimal — role + type + payload the
-// renderer above consumes.
-
-type TimelineItem =
-    | { role: "user"; type: "message"; content: string }
-    | { role: "agent"; type: "message"; content: string }
-    | { role: "agent"; type: "execute"; id: string; lang: string; code: string }
-    | { role: "agent"; type: "result"; for: string; ok: boolean; content: string; error?: { kind: "timeout" | "policy" | "interrupt" | "exception"; message: string } }
-    | { role: "system"; type: "system"; systemType: string; lang: string; content: string; attributes?: Record<string, string> }
-
-/**
- * One log entry → one rendered turn. Exhaustive: a new AxonEntryEvent
- * type must decide its rendering here (or explicitly return null to omit it).
- * This is the single place the memory format meets the wire format.
- */
-function timelineItem(entry: AxonEntry): TimelineItem | null {
-    switch (entry.type) {
-        case "cognet:stimulus:text":
-            return { role: "user", type: "message", content: entry.data.content }
-
-        case "cognet:stimulus:audio":
-            return { role: "user", type: "message", content: entry.data.transcript ?? "[audio]" }
-
-        case "cognet:stimulus:visual":
-            return { role: "user", type: "message", content: entry.data.caption ?? `[${entry.data.kind}]` }
-
-        case "cognet:stimulus:field":
-            return { role: "system", type: "system", systemType: "field", lang: "txt", content: `${entry.data.source.channel}: ${String(entry.data.reading.value)}${entry.data.reading.unit ?? ""}` }
-
-        case "axon:interrupt":
-            return { role: "system", type: "system", systemType: "interrupt", lang: "txt", content: `interrupted (${entry.data.reason})` }
-
-        case "cognet:output:text":
-            return { role: "agent", type: "message", content: entry.data.content }
-
-        case "cognet:output:audio":
-            return { role: "agent", type: "message", content: entry.data.transcript ?? "[audio]" }
-
-        case "cognet:output:visual":
-            return { role: "agent", type: "message", content: entry.data.caption ?? `[${entry.data.kind}]` }
-
-        case "cognet:output:field":
-            return { role: "system", type: "system", systemType: "field", lang: "txt", content: `${String(entry.data.reading.value)}${entry.data.reading.unit ?? ""}` }
-
-        case "cognet:action:typescript":
-            return { role: "agent", type: "execute", id: entry.data.id, lang: "typescript", code: entry.data.content }
-
-        case "cognet:action:result":
-            return {
-                role: "agent",
-                type: "result",
-                for: entry.data.for,
-                ok: entry.data.ok,
-                content: entry.data.content,
-                ...(entry.data.error ? { error: entry.data.error } : {}),
-            }
-
-        case "axon:system:message":
-            return {
-                role: "system",
-                type: "system",
-                systemType: entry.data.type,
-                lang: entry.data.lang,
-                content: entry.data.content,
-                ...(entry.data.attributes ? { attributes: entry.data.attributes } : {}),
-            }
-    }
-}