@vincemakes/kiso-runtime 0.1.38 → 0.2.1

package/dist/trace/record.js

@@ -0,0 +1,257 @@
+/**
+ * E1 (1.2.0) — the Request Trace record schema (proposal §1.1 as adopted
+ * by the R1 ruling: "adopt as-is, keep ts, per-round additive"). This is
+ * the 1.2.0 field-set lock: every field below is spec'd, and the
+ * closed-field-set gate (ruling R1a) pins the shape bidirectionally —
+ * `TRACE_RECORD_FIELDS`/`TRACE_SEGMENT_FIELDS` must stay in exact
+ * agreement with the interfaces, or trace-schema.test.ts goes red.
+ *
+ * R1a: `schemaVersion` pins BOTH the record shape AND the hash /
+ * fingerprint algorithms (`HASH_SPEC_BY_VERSION`). A version bump must
+ * pin a spec for the new version before any writer can use it
+ * (`hashSpecFor` throws otherwise).
+ *
+ * The ledger is OUT-side (ADR-0051 §6): versionable, never part of the
+ * correctness ABI. These types are runtime-internal.
+ *
+ * E2 (1.3.0) — schemaVersion 2: the record gains the `canonical` block
+ * (E2 proposal §1.5 Case A — the nested block, ruled 2026-08-13; raw
+ * quartet stays as provider observation above it). The validators accept
+ * BOTH generations (R1d-1): a v1 sidecar has no canonical block and reads
+ * as defaults at every consumer — never a crash.
+ *
+ * E3 (0.2.1) — schemaVersion 3: the record gains the `rent` block — the
+ * static rent ledger, one line per surface (trace/rent.ts). The v3
+ * writers record it; v1/v2 sidecars keep reading as defaults (R1d-1,
+ * R2-1): no rent block = no rent lines = the zero-rent reading, never a
+ * crash.
+ */
+/** schemaVersion: 3 for 0.2.1 (the rent block). Version 1 = the 1.2.0
+ *  shape, version 2 = the 1.3.0 shape; both kept for generation-compat
+ *  reads (R1d-1, R2-1). Algorithm and shape changes bump it (ADR-0051 §6
+ *  OUT-side versioning). */
+export const TRACE_SCHEMA_VERSION = 3;
+/** The versions a reader may meet in a ledger. v1 and v2 records are
+ *  accepted (generation-compat) and read as defaults — no canonical
+ *  block (v1), no rent block (v1, v2). */
+export const TRACE_SCHEMA_VERSIONS = new Set([1, 2, TRACE_SCHEMA_VERSION]);
+import { PRICING_TABLE_V1, priceFor, pricingTableFor, validateCanonicalUsage } from "../usage/canonical.js";
+import { validateRentLine } from "./rent.js";
+export const HASH_SPEC_BY_VERSION = {
+    1: { algorithm: "sha-256", output: "full-hex" },
+    2: { algorithm: "sha-256", output: "full-hex" }, // E2 — the algorithms do not change
+    3: { algorithm: "sha-256", output: "full-hex" }, // E3 — same algorithms, re-pinned (the E2 ritual)
+};
+export function hashSpecFor(version) {
+    const spec = HASH_SPEC_BY_VERSION[version];
+    if (spec === undefined)
+        throw new Error(`no hash spec pinned for trace schemaVersion ${version}`);
+    return spec;
+}
+// ── The closed-field-set gate (R1a) ───────────────────────────────────────
+// Trace-schema.test.ts asserts Object.keys of a fully populated record is
+// EXACTLY this set (both directions).
+/** The 1.2.0 field set (schemaVersion 1) — kept verbatim for
+ *  generation-compat reads of old sidecars (R1d-1): a v1 record has no
+ *  canonical block and reads as defaults at every consumer. */
+export const TRACE_RECORD_FIELDS_V1 = [
+    "schemaVersion",
+    "kind",
+    "requestId",
+    "runId",
+    "requestIndex",
+    "retryAttempt",
+    "provider",
+    "model",
+    "adapterVersion",
+    "systemPromptHash",
+    "toolSchemaHash",
+    "contextHash",
+    "contextManifest",
+    "segmentHashes",
+    "stablePrefixFingerprint",
+    "freshInput",
+    "cacheRead",
+    "cacheWrite",
+    "output",
+    "latencyMs",
+    "ttftMs",
+    "toolCalls",
+    "outcome",
+    "lineageLink",
+    "ts",
+];
+/** The 1.3.0 field set (schemaVersion 2) = the v1 set + `canonical`. */
+export const TRACE_RECORD_FIELDS_V2 = [...TRACE_RECORD_FIELDS_V1, "canonical"];
+/** The 0.2.1 field set (schemaVersion 3) = the v2 set + `rent`. */
+export const TRACE_RECORD_FIELDS = [...TRACE_RECORD_FIELDS_V2, "rent"];
+export const TRACE_SEGMENT_FIELDS = ["role", "seqRange", "estTokens", "freshness"];
+// ── Validators ────────────────────────────────────────────────────────────
+// Strict by design: extra keys are rejected (the closed set), so a
+// misspelled field can never silently enter the ledger.
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const keysOf = (v) => (isRecord(v) ? Object.keys(v) : []);
+const isNonNegInt = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
+const isNumber = (v) => typeof v === "number" && Number.isFinite(v);
+const isHex64 = (v) => typeof v === "string" && /^[0-9a-f]{64}$/.test(v);
+/** The closed set, both directions: no key outside the spec, and every
+ *  spec'd key present except the explicit optional ones. */
+const hasClosedKeys = (v, spec, optional = []) => {
+    const keys = keysOf(v);
+    if (keys.some((k) => !spec.includes(k)))
+        return false;
+    const optionalSet = new Set(optional);
+    return spec.every((k) => optionalSet.has(k) || keys.includes(k));
+};
+const VALID_SEGMENT_ROLES = new Set(["system", "tools", "turn", "current_turn"]);
+const VALID_FRESHNESS = new Set(["fresh", "cache_read", "cache_write"]);
+const VALID_OUTCOMES = new Set(["ok", "provider_error", "aborted"]);
+function isValidSeqRange(v) {
+    if (v === null)
+        return true;
+    if (!Array.isArray(v) || v.length !== 2)
+        return false;
+    const [a, b] = v;
+    return isNonNegInt(a) && isNonNegInt(b) && a <= b;
+}
+export function validateTraceSegment(v) {
+    if (!isRecord(v) || !hasClosedKeys(v, TRACE_SEGMENT_FIELDS))
+        return false;
+    if (typeof v.role !== "string" || !VALID_SEGMENT_ROLES.has(v.role))
+        return false;
+    if (!isValidSeqRange(v.seqRange))
+        return false;
+    if (!isNonNegInt(v.estTokens))
+        return false;
+    if (!VALID_FRESHNESS.has(v.freshness))
+        return false;
+    return true;
+}
+export function validateTraceRecord(v) {
+    if (!isRecord(v))
+        return false;
+    const version = v.schemaVersion;
+    // generation-compat (R1d-1, R2-1): a v1 sidecar has no canonical
+    // block, a v2 sidecar has no rent block — both read as defaults,
+    // accepted, never a crash; the current version is fully checked
+    // (shape + the canonical block + the rent ledger).
+    if (version !== 1 && version !== 2 && version !== TRACE_SCHEMA_VERSION)
+        return false;
+    const fields = version === 1 ? TRACE_RECORD_FIELDS_V1 : version === 2 ? TRACE_RECORD_FIELDS_V2 : TRACE_RECORD_FIELDS;
+    if (!hasClosedKeys(v, fields, ["lineageLink"]))
+        return false;
+    if (v.kind !== "request")
+        return false;
+    if (typeof v.requestId !== "string" || typeof v.runId !== "string")
+        return false;
+    if (!isNonNegInt(v.requestIndex) || !isNonNegInt(v.retryAttempt))
+        return false;
+    if (typeof v.provider !== "string" || typeof v.model !== "string")
+        return false;
+    if (v.adapterVersion !== null && typeof v.adapterVersion !== "string")
+        return false;
+    if (!isHex64(v.systemPromptHash) || !isHex64(v.toolSchemaHash) || !isHex64(v.contextHash))
+        return false;
+    if (!isHex64(v.stablePrefixFingerprint))
+        return false;
+    if (!Array.isArray(v.contextManifest) || !v.contextManifest.every(validateTraceSegment))
+        return false;
+    // segmentHashes must mirror the manifest 1:1 — a misaligned list
+    // would silently corrupt the break derivation (R4b)
+    if (!Array.isArray(v.segmentHashes) ||
+        v.segmentHashes.length !== v.contextManifest.length ||
+        !v.segmentHashes.every(isHex64))
+        return false;
+    if (!isNumber(v.freshInput) || !isNumber(v.cacheRead))
+        return false;
+    if (v.cacheWrite !== null && !isNumber(v.cacheWrite))
+        return false;
+    if (!isNumber(v.output) || !isNumber(v.latencyMs))
+        return false;
+    if (!isNumber(v.ttftMs))
+        return false; // 0 = unknown, never null (locked set)
+    if (!Array.isArray(v.toolCalls) || !v.toolCalls.every((t) => typeof t === "string"))
+        return false;
+    if (typeof v.outcome !== "string" || !VALID_OUTCOMES.has(v.outcome))
+        return false;
+    if (v.lineageLink !== undefined) {
+        const l = v.lineageLink;
+        if (!isRecord(l))
+            return false;
+        if (typeof l.parentSessionId !== "string" || typeof l.parentRunId !== "string")
+            return false;
+        if (!isNonNegInt(l.parentInvocationSeq))
+            return false;
+        if (typeof l.role !== "string")
+            return false;
+    }
+    if (version !== 1) {
+        // the canonical block: the schema's invariants machine-checked
+        if (!validateCanonicalUsage(v.canonical))
+            return false;
+        const c = v.canonical;
+        // the block formalizes the raw quartet — a divergence means the
+        // derivation drifted (a future bug, caught at the ledger)
+        if (c.input !== v.freshInput || c.cacheRead !== v.cacheRead || c.output !== v.output || c.cacheWrite !== v.cacheWrite)
+            return false;
+        // cost consistency: recomputed from the components × the version's
+        // pinned table, at the record's own route (the route context lives
+        // in the record; the standalone schema cannot check this). A null
+        // costUsd is the R5b-④c absent stamp (the table has no rate for
+        // this route) — nothing to recompute against, accepted. The
+        // cross-check runs only for builtin-id records: a foreign table's
+        // consistency is the billing layer's accounting, not the ledger's.
+        if (c.costUsd !== null && c.pricingTableId === PRICING_TABLE_V1.id) {
+            const expected = priceFor(v.provider, { input: c.input, output: c.output, cacheRead: c.cacheRead, cacheWrite: c.cacheWrite }, pricingTableFor(c.pricingTableVersion));
+            // non-null for the builtin table by construction (both real
+            // routes + the mirror fallback) — a null here is a code bug,
+            // and an epsilon check has nothing to compare
+            if (expected !== null && Math.abs(c.costUsd - expected) > 1e-6)
+                return false;
+        }
+    }
+    if (version === TRACE_SCHEMA_VERSION) {
+        // the rent block: every line validates (closed fields, non-empty
+        // surface, non-negative integer chars, the estTokens == ceil(chars/4)
+        // cross-check — R6). v1/v2 sidecars have no block (R2-1).
+        if (!Array.isArray(v.rent) || !v.rent.every(validateRentLine))
+            return false;
+    }
+    if (!isNumber(v.ts))
+        return false;
+    return true;
+}
+export function validateTraceLine(v) {
+    if (!isRecord(v))
+        return false;
+    // both ledger generations are readable (R1d-1); the per-kind shapes are
+    // identical across 1 → 2 — only the request line's field set differs
+    // (v1 lacks the canonical block), handled by validateTraceRecord's
+    // version dispatch
+    if (!TRACE_SCHEMA_VERSIONS.has(v.schemaVersion))
+        return false;
+    switch (v.kind) {
+        case "header":
+            return (hasClosedKeys(v, ["schemaVersion", "kind", "sessionId", "kisoVersion", "createdAt"]) &&
+                typeof v.sessionId === "string" &&
+                typeof v.kisoVersion === "string" &&
+                isNumber(v.createdAt));
+        case "request":
+            return validateTraceRecord(v);
+        case "run_end":
+            return (hasClosedKeys(v, ["schemaVersion", "kind", "runId", "ts", "lastRequestIndex"]) &&
+                typeof v.runId === "string" &&
+                isNumber(v.ts) &&
+                // -1 = the run made no adapter calls (an empty run still
+                // settles cleanly); anything below that is not a request index
+                typeof v.lastRequestIndex === "number" &&
+                Number.isInteger(v.lastRequestIndex) &&
+                v.lastRequestIndex >= -1);
+        case "crash":
+            return (hasClosedKeys(v, ["schemaVersion", "kind", "ts", "note"]) &&
+                isNumber(v.ts) &&
+                typeof v.note === "string");
+        default:
+            return false;
+    }
+}

package/dist/trace/rent.d.ts

@@ -0,0 +1,81 @@
+/**
+ * E3 (0.2.1) — the rent ledger: every request's static model-side rent,
+ * one line per surface.
+ *
+ * The static rent is the surface the model pays REGARDLESS of the turn's
+ * content: the base system prompt, each extension's append, every tool's
+ * serialized spec, and the per-request envelope. One line per surface,
+ * four classes, measured in chars + the rounds' est-token convention
+ * (chars/4, ceil — the E1 script's formula, the work order's own words,
+ * R6):
+ *
+ *   - system:base       the session's own prompt as the CLI handed it
+ *                       (built-in constant + project instructions — the
+ *                       runtime cannot split those, R3). The runtime's
+ *                       generated tool table is machinery BETWEEN base and
+ *                       appends; it stays out of the ledger (counts live
+ *                       in tool:<name> lines and the base's own line).
+ *   - system:ext:<name> one line per extension with a non-empty
+ *                       systemPrompt.append, measured on the append
+ *                       string, in load order.
+ *   - tool:<name>       one line per tool, measured on the exact
+ *                       serialized ToolSpec projection the adapters
+ *                       receive ({name, description, inputSchema} — the
+ *                       registry.toSpecs() shape, protocol/messages.ts).
+ *   - envelope          the per-request fixed overhead OUTSIDE the
+ *                       conversation payloads: the R5 skeleton
+ *                       JSON.stringify({model, messages: [], tools: []})
+ *                       — a function of the model string only, never of
+ *                       the payloads (the skeleton is the definition).
+ *
+ * R9: an absent surface is an absent line — an unconfigured mcp, a
+ * session with no project instructions: no line. The absence IS the
+ * ledger statement (the 0.1.45 diet-A precedent: not paid = no rent).
+ *
+ * Determinism (the reviewer-facing property): every line is derivable
+ * from components the reviewer can recompute — the exported prompt
+ * constant, the appends, the ToolSpec array, the request skeleton. The
+ * ledger stores COUNTS, never payloads (the seqRange thin-pointer
+ * discipline applied to rent).
+ *
+ * buildRentLedger is the SINGLE source: the R7 star gate drives a real
+ * session with the script's predicted composition and asserts the
+ * recorded ledger equals the prediction line for line.
+ */
+import type { ToolSpec } from "@vincemakes/kiso-core";
+export interface RentLine {
+    /** "system:base" | "system:ext:<name>" | "tool:<name>" | "envelope" */
+    surface: string;
+    /** length of the serialized surface, measured, never a copy */
+    chars: number;
+    /** Math.ceil(chars / 4) — the E1 script convention, pinned (R6) */
+    estTokens: number;
+}
+/** The closed line set (the same gate discipline as the record fields). */
+export declare const RENT_LINE_FIELDS: readonly ["surface", "chars", "estTokens"];
+/** What the runtime knows about the static surface beyond what the
+ *  adapter call itself carries: the base prompt as configured, and the
+ *  per-extension appends in load order (the adapter's composed
+ *  systemPrompt is the result — the parts are the ledger's inputs). */
+export interface RentParts {
+    base?: string;
+    appends?: readonly {
+        name: string;
+        text: string;
+    }[];
+}
+export interface RentInput extends RentParts {
+    model: string;
+    tools?: readonly ToolSpec[];
+}
+/** The one ledger: system:base, then system:ext:* (load order), then
+ *  tool:* (the array's order — the registry's toSpecs() order), then the
+ *  envelope. Absent surfaces contribute no lines (R9). */
+export declare function buildRentLedger(input: RentInput): RentLine[];
+/** The line validator — the same strict discipline as the record's other
+ *  closed sets: no key outside the spec, every spec'd key present,
+ *  non-empty surface (R9: a line exists only for a surface that exists),
+ *  non-negative integer chars, and the estTokens cross-check (R6). The
+ *  schema pins the LINE, not the multiset — duplicate surfaces are the
+ *  writer's business, never a schema crash. */
+export declare function validateRentLine(v: unknown): v is RentLine;

package/dist/trace/rent.js

@@ -0,0 +1,96 @@
+/**
+ * E3 (0.2.1) — the rent ledger: every request's static model-side rent,
+ * one line per surface.
+ *
+ * The static rent is the surface the model pays REGARDLESS of the turn's
+ * content: the base system prompt, each extension's append, every tool's
+ * serialized spec, and the per-request envelope. One line per surface,
+ * four classes, measured in chars + the rounds' est-token convention
+ * (chars/4, ceil — the E1 script's formula, the work order's own words,
+ * R6):
+ *
+ *   - system:base       the session's own prompt as the CLI handed it
+ *                       (built-in constant + project instructions — the
+ *                       runtime cannot split those, R3). The runtime's
+ *                       generated tool table is machinery BETWEEN base and
+ *                       appends; it stays out of the ledger (counts live
+ *                       in tool:<name> lines and the base's own line).
+ *   - system:ext:<name> one line per extension with a non-empty
+ *                       systemPrompt.append, measured on the append
+ *                       string, in load order.
+ *   - tool:<name>       one line per tool, measured on the exact
+ *                       serialized ToolSpec projection the adapters
+ *                       receive ({name, description, inputSchema} — the
+ *                       registry.toSpecs() shape, protocol/messages.ts).
+ *   - envelope          the per-request fixed overhead OUTSIDE the
+ *                       conversation payloads: the R5 skeleton
+ *                       JSON.stringify({model, messages: [], tools: []})
+ *                       — a function of the model string only, never of
+ *                       the payloads (the skeleton is the definition).
+ *
+ * R9: an absent surface is an absent line — an unconfigured mcp, a
+ * session with no project instructions: no line. The absence IS the
+ * ledger statement (the 0.1.45 diet-A precedent: not paid = no rent).
+ *
+ * Determinism (the reviewer-facing property): every line is derivable
+ * from components the reviewer can recompute — the exported prompt
+ * constant, the appends, the ToolSpec array, the request skeleton. The
+ * ledger stores COUNTS, never payloads (the seqRange thin-pointer
+ * discipline applied to rent).
+ *
+ * buildRentLedger is the SINGLE source: the R7 star gate drives a real
+ * session with the script's predicted composition and asserts the
+ * recorded ledger equals the prediction line for line.
+ */
+/** The closed line set (the same gate discipline as the record fields). */
+export const RENT_LINE_FIELDS = ["surface", "chars", "estTokens"];
+const line = (surface, text) => ({
+    surface,
+    chars: text.length,
+    estTokens: Math.ceil(text.length / 4),
+});
+/** The one ledger: system:base, then system:ext:* (load order), then
+ *  tool:* (the array's order — the registry's toSpecs() order), then the
+ *  envelope. Absent surfaces contribute no lines (R9). */
+export function buildRentLedger(input) {
+    const lines = [];
+    if (input.base !== undefined)
+        lines.push(line("system:base", input.base));
+    for (const append of input.appends ?? [])
+        lines.push(line(`system:ext:${append.name}`, append.text));
+    for (const tool of input.tools ?? []) {
+        lines.push(line(`tool:${tool.name}`, JSON.stringify({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema })));
+    }
+    // R5: the envelope is the request skeleton — a model-string function,
+    // never the payloads; the empty arrays are literal (the definition).
+    lines.push(line("envelope", JSON.stringify({ model: input.model, messages: [], tools: [] })));
+    return lines;
+}
+/** The line validator — the same strict discipline as the record's other
+ *  closed sets: no key outside the spec, every spec'd key present,
+ *  non-empty surface (R9: a line exists only for a surface that exists),
+ *  non-negative integer chars, and the estTokens cross-check (R6). The
+ *  schema pins the LINE, not the multiset — duplicate surfaces are the
+ *  writer's business, never a schema crash. */
+export function validateRentLine(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return false;
+    const o = v;
+    const keys = Object.keys(o);
+    const fields = RENT_LINE_FIELDS;
+    if (keys.some((k) => !fields.includes(k)))
+        return false;
+    if (!fields.every((k) => k in o))
+        return false;
+    if (typeof o.surface !== "string" || o.surface.length === 0)
+        return false;
+    const chars = o.chars;
+    const estTokens = o.estTokens;
+    if (typeof chars !== "number" || !Number.isInteger(chars) || chars < 0)
+        return false;
+    if (typeof estTokens !== "number" || !Number.isInteger(estTokens) || estTokens < 0)
+        return false;
+    if (estTokens !== Math.ceil(chars / 4))
+        return false;
+    return true;
+}

package/dist/trace/writer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * E1 (1.2.0) — slice 2, the trace writer (proposal §1.2 + §6).
+ *
+ * The ledger is OUT-side (ADR-0051 §6): a versionable observation
+ * artifact, never part of the correctness ABI. The soft-fail law
+ * (work-order): trace loss costs ONE stderr line, then the session runs
+ * on — the writer degrades to a no-op on its first I/O failure and
+ * never throws into the caller.
+ *
+ * Async discipline (work-order §9): request lines are ENQUEUED (a sync
+ * push, sub-microsecond) and flushed on setImmediate — the model hot
+ * path never blocks on the ledger. The run_end line is flushed
+ * SYNCHRONOUSLY from the run's finally block: clean-settle marking is
+ * where the ledger's story (every hole reconciles as a crash, never as
+ * a writer bug) needs the write to have happened before the run ends.
+ */
+import { type TraceLine } from "./record.js";
+/** The runtime's own version, read from the package.json next to the
+ *  build; null on failure (soft-fail — the header still ships). */
+export declare function runtimeVersion(): string | null;
+export interface TraceWriterDeps {
+    /** The sessions dir (store.root). The ledger lives in <root>/traces/ —
+     *  NOT flat in root: a flat `<sid>.trace.jsonl` would be enumerated as
+     *  a phantom session by SessionStore.list() and corrupt the bench
+     *  sessions glob (proposal §3.2; the R3a gate pins it). */
+    root: string;
+    sessionId: string;
+}
+export declare class TraceWriter {
+    #private;
+    constructor(deps: TraceWriterDeps);
+    /** One-time setup: mkdir the ledger dir, mark a previous run that left
+     *  no run_end (crash), write the header — the header once per ledger
+     *  file (session-level, §1.2), so a resume appends markers, never a
+     *  second header. Never throws. */
+    init(): void;
+    /** Enqueue a line for the next flush — the hot path's only cost.
+     *  Never throws; after a degradation the line is dropped. */
+    enqueue(line: TraceLine): void;
+    /** Clean-settle marking: the run_end line lands NOW (synchronous),
+     *  together with any still-pending request lines. */
+    finishRun(runId: string, lastRequestIndex: number): void;
+}

package/dist/trace/writer.js

@@ -0,0 +1,154 @@
+/**
+ * E1 (1.2.0) — slice 2, the trace writer (proposal §1.2 + §6).
+ *
+ * The ledger is OUT-side (ADR-0051 §6): a versionable observation
+ * artifact, never part of the correctness ABI. The soft-fail law
+ * (work-order): trace loss costs ONE stderr line, then the session runs
+ * on — the writer degrades to a no-op on its first I/O failure and
+ * never throws into the caller.
+ *
+ * Async discipline (work-order §9): request lines are ENQUEUED (a sync
+ * push, sub-microsecond) and flushed on setImmediate — the model hot
+ * path never blocks on the ledger. The run_end line is flushed
+ * SYNCHRONOUSLY from the run's finally block: clean-settle marking is
+ * where the ledger's story (every hole reconciles as a crash, never as
+ * a writer bug) needs the write to have happened before the run ends.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { TRACE_SCHEMA_VERSION } from "./record.js";
+let cachedRuntimeVersion;
+/** The runtime's own version, read from the package.json next to the
+ *  build; null on failure (soft-fail — the header still ships). */
+export function runtimeVersion() {
+    if (cachedRuntimeVersion === undefined) {
+        cachedRuntimeVersion = (() => {
+            try {
+                const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json"), "utf8"));
+                return pkg.version ?? null;
+            }
+            catch {
+                return null;
+            }
+        })();
+    }
+    return cachedRuntimeVersion;
+}
+export class TraceWriter {
+    #root;
+    #sessionId;
+    #path;
+    #pending = [];
+    #flushScheduled = false;
+    #degraded = false;
+    constructor(deps) {
+        this.#root = deps.root;
+        this.#sessionId = deps.sessionId;
+        this.#path = join(deps.root, "traces", `${deps.sessionId}.jsonl`);
+    }
+    /** One-time setup: mkdir the ledger dir, mark a previous run that left
+     *  no run_end (crash), write the header — the header once per ledger
+     *  file (session-level, §1.2), so a resume appends markers, never a
+     *  second header. Never throws. */
+    init() {
+        if (this.#degraded)
+            return;
+        try {
+            mkdirSync(join(this.#root, "traces"), { recursive: true });
+            const fresh = !existsSync(this.#path);
+            if (this.#crashDetect()) {
+                this.#writeSync([
+                    { schemaVersion: TRACE_SCHEMA_VERSION, kind: "crash", ts: Date.now(), note: "previous run left no run_end" },
+                ]);
+            }
+            if (fresh) {
+                this.#writeSync([
+                    {
+                        schemaVersion: TRACE_SCHEMA_VERSION,
+                        kind: "header",
+                        sessionId: this.#sessionId,
+                        kisoVersion: runtimeVersion() ?? "?",
+                        createdAt: Date.now(),
+                    },
+                ]);
+            }
+        }
+        catch (err) {
+            this.#degrade(err);
+        }
+    }
+    /** Enqueue a line for the next flush — the hot path's only cost.
+     *  Never throws; after a degradation the line is dropped. */
+    enqueue(line) {
+        if (this.#degraded)
+            return;
+        this.#pending.push(line);
+        if (!this.#flushScheduled) {
+            this.#flushScheduled = true;
+            setImmediate(() => {
+                this.#flushScheduled = false;
+                this.#flushSync();
+            });
+        }
+    }
+    /** Clean-settle marking: the run_end line lands NOW (synchronous),
+     *  together with any still-pending request lines. */
+    finishRun(runId, lastRequestIndex) {
+        this.enqueue({
+            schemaVersion: TRACE_SCHEMA_VERSION,
+            kind: "run_end",
+            runId,
+            ts: Date.now(),
+            lastRequestIndex,
+        });
+        this.#flushSync();
+    }
+    /** True when the ledger already exists and its LAST line is neither
+     *  run_end nor crash — an un-terminated run (killed mid-run), to be
+     *  marked. A crash-marked ledger is not re-marked. */
+    #crashDetect() {
+        if (!existsSync(this.#path))
+            return false;
+        let last;
+        try {
+            for (const line of readFileSync(this.#path, "utf8").split("\n")) {
+                if (line.trim() === "")
+                    continue;
+                last = JSON.parse(line);
+            }
+        }
+        catch {
+            return false; // unreadable ledger — do not compound the failure
+        }
+        if (last === undefined)
+            return false;
+        return last.kind !== "run_end" && last.kind !== "crash";
+    }
+    #writeSync(lines) {
+        if (lines.length === 0)
+            return;
+        try {
+            appendFileSync(this.#path, `${lines.map((l) => JSON.stringify(l)).join("\n")}\n`);
+        }
+        catch (err) {
+            this.#degrade(err);
+        }
+    }
+    #flushSync() {
+        if (this.#pending.length === 0)
+            return;
+        const lines = this.#pending;
+        this.#pending = [];
+        this.#writeSync(lines);
+    }
+    /** The soft-fail law: one stderr line, then the ledger is dropped and
+     *  the session runs on. Idempotent. */
+    #degrade(err) {
+        if (this.#degraded)
+            return;
+        this.#degraded = true;
+        this.#pending = [];
+        console.error(`[kiso] trace writer degraded (${err instanceof Error ? err.message : String(err)}); request traces dropped`);
+    }
+}