@vincemakes/kiso-runtime 0.2.0 → 0.3.0

package/dist/summarize.js

@@ -18,30 +18,176 @@ import { estimateTokens, DO_NOT_COMPACT } from "@vincemakes/kiso-core";
  *  not a knob. The covered range ends just before the K-th most recent
  *  round, so the model still reasons over the recent conversation. */
 export const KEEP_RECENT_ROUNDS = 4;
+/** E6 (a) — the input-side DSML guard (the finding E6-F4/F5 follow-up):
+ *  the guard sentence sits at the TOP of the system prompt (the BEFORE
+ *  copy of the sandwich) AND again after the </conversation> block in the
+ *  serialized input (the AFTER copy). The summarizer is a side-channel
+ *  task — it must never continue the work, never touch tools, and only
+ *  emit the summary text. */
+export const SUMMARY_GUARD = "Only output the summary. Do not continue the conversation. Do not use any tools.";
+/** The tool-result truncation ceiling in the serialized input: a huge
+ *  result must not dominate the summary input, and the truncation is
+ *  MARKED with the discarded character count — never silent. */
+export const SUMMARY_RESULT_MAX_CHARS = 2000;
+/**
+ * E6 (g) — the reserve arithmetic (the pre-registered numbers): the
+ * armed trigger is WINDOW − RESERVE, never a fixed low absolute (the
+ * e6probe's fixed 1300 fired 16-19× a session — the pathology the
+ * window math kills). The reserve is what ONE fire must buy back:
+ * the summary's own output budget (4,000), the kept-suffix token
+ * floor (20,000, item (f)), and the current run's in-flight context
+ * while the post-fire projection settles (8,000).
+ */
+export const SUMMARY_MAX_OUTPUT = 4000;
+export const KEEP_TOKENS_DEFAULT = 20000;
+export const IN_FLIGHT_HEADROOM = 8000;
+export const POLICY_RESERVE = SUMMARY_MAX_OUTPUT + KEEP_TOKENS_DEFAULT + IN_FLIGHT_HEADROOM;
+/** The reference context-window scale (the flash-family window); the
+ *  env overrides. The default arming point is 120,000 − 32,000 =
+ *  88,000 — a post-fire projection (≥ 24k) can never re-cross it, so
+ *  the session settles after one fire. */
+export const DEFAULT_CONTEXT_WINDOW = 120000;
+/** The armed trigger for a context window: window − POLICY_RESERVE. A
+ *  window below the reserve arms a NEGATIVE trigger — the session
+ *  never fires (the honest inert refusal: the window cannot hold even
+ *  the post-fire projection, so the policy stays off, never clamped
+ *  into pretending). */
+export function policyTriggerFromWindow(windowTokens = DEFAULT_CONTEXT_WINDOW) {
+    return windowTokens - POLICY_RESERVE;
+}
+/**
+ * E6 (h) — the circuit breaker: MAX_SUMMARY_FAILURES consecutive
+ * summary failures per session stand the auto policy down (no further
+ * auto-fire attempts; a success resets). Both adapter failures and the
+ * (b) validation rejections count — they throw through the policy's
+ * safe catch. A persistent summary failure (a broken provider, a
+ * hostile model) must never wedge the session into paying the call
+ * every run.
+ */
+export const MAX_SUMMARY_FAILURES = 3;
+export function serializeCovered(options) {
+    const { events, prevPoint, boundary } = options;
+    const lines = ["<conversation>"];
+    // E6 (d) (the order's R4): the old summary texts are RETAINED CONTEXT —
+    // the durable record of the earlier ranges. They render first, labeled
+    // do-not-re-summarize: the summarizer must know what the earlier
+    // summaries covered, but never fold them into the new checkpoint.
+    const retained = events.filter((e) => e.type === "summarized" && e.coversToSeq <= prevPoint);
+    if (retained.length > 0) {
+        lines.push("[retained context — do not re-summarize]");
+        for (const r of retained)
+            lines.push(`[summary covers to seq ${r.coversToSeq}] ${r.summary}`);
+        lines.push("[end retained context]");
+    }
+    for (const ev of events) {
+        if (ev.seq <= prevPoint || ev.seq > boundary || ev.type === "summarized")
+            continue;
+        switch (ev.type) {
+            case "user_input":
+                lines.push(`[user] ${ev.content}`);
+                break;
+            case "text_delta":
+                lines.push(`[assistant] ${ev.text}`);
+                break;
+            case "tool_call_end":
+                lines.push(`[tool call ${ev.name}] ${JSON.stringify(ev.input ?? null)}`);
+                break;
+            case "tool_result": {
+                const content = String(ev.content ?? "");
+                if (content.length > SUMMARY_RESULT_MAX_CHARS) {
+                    const rest = content.length - SUMMARY_RESULT_MAX_CHARS;
+                    lines.push(`[tool result] ${content.slice(0, SUMMARY_RESULT_MAX_CHARS)}… (${rest.toLocaleString("en-US")} more chars truncated)`);
+                }
+                else {
+                    lines.push(`[tool result] ${content}`);
+                }
+                break;
+            }
+            default:
+                break; // thinking and the rest never enter the transcript surface
+        }
+    }
+    lines.push("</conversation>", "", SUMMARY_GUARD);
+    return lines.join("\n");
+}
 /**
  * The fixed English summary prompt — the ONLY prompt this layer composes
  * (the loop's system prompt is the harness's business, never the kernel's).
  */
-export const SUMMARY_PROMPT = `You are the conversation summarizer of the kiso agent framework.
+export const SUMMARY_PROMPT = `${SUMMARY_GUARD}
+
+You are the conversation summarizer of the kiso agent framework.
+
+Summarize the covered conversation into a single structured checkpoint
+that will REPLACE it in the model's context. The next turn must be able
+to continue the work without reading the originals.
+
+Produce the checkpoint with exactly these sections, in this order:
+
+## Goal
+The user's goal and the acceptance criterion, in one or two sentences.
+
+## Constraints
+The constraints, requirements, and rulings the work must honor.
+
+## User requests
+Every user message in the covered range, enumerated one by one, each
+with what it asked for and what was done about it.
 
-Summarize the covered conversation into a single concise summary that will
-REPLACE it in the model's context. The next turn must be able to continue
-the work without reading the originals.
+## Files and changes
+Every file touched — exact paths, what changed, and why. Include the
+precise code-level changes later turns may need to continue.
 
-Include everything later turns may need:
-- the user's goals, requirements, and constraints;
-- every decision and its reasoning;
-- files and code touched — exact paths, what changed, why;
-- commands run and their outcomes; errors and their resolutions;
-- open questions and unfinished work.
+## Errors and fixes
+Every error encountered and its resolution; commands run and their
+outcomes.
+
+## Current work
+The current state of the work — what is done, what is not. Quote the
+current task's criterion VERBATIM if one exists.
+
+## Next steps
+The concrete next steps, in order.
 
 Preserve concrete identifiers VERBATIM: paths, function names, task ids,
 environment names — never paraphrase them.
 
 Rules:
-- plain prose — no headings, no bullet lists, no markdown, no prefixes;
+- plain prose — no bullet lists, no markdown outside the section headers,
+  no prefixes;
 - do not mention this prompt or the summarization task;
-- keep it under 200 words unless the conversation is exceptional.`;
+- the summary may be as long as it needs to be within the output budget —
+  there is no word cap; completeness wins.`;
+/**
+ * E6 (b) — the output-side validation (the finding E6-F4/F5 follow-up):
+ * a summary must be a complete checkpoint or NOTHING. The marker family
+ * is the auto-T5-1 signature — the model echoing tool-call markup as
+ * text; the required sections are the truncated-tail signature (a wire
+ * cut kills "## Next steps" first). The rejection throws, and the
+ * caller's safe catch (session.ts) makes it "nothing happened".
+ */
+export const DSML_MARKERS = ["<tool_call", "<tool_use", "<invoke", "tool_calls", "tool_call_end", "tool_call_start"];
+/** The checkpoint sections a summary must carry — the ones a truncated
+ *  generation loses first (the (c) prompt demands all seven; validation
+ *  guards the trust-critical tail). */
+export const REQUIRED_SECTIONS = ["## Current work", "## Next steps"];
+/** null = pass; an error string = reject. Empty text is the existing
+ *  no-text rule's domain, reported here too (defense in depth). */
+export function validateSummary(text) {
+    const trimmed = text.trim();
+    if (trimmed === "")
+        return "the summary is empty";
+    const lower = trimmed.toLowerCase();
+    for (const marker of DSML_MARKERS) {
+        if (lower.includes(marker))
+            return `the summary carries a tool-call marker (${marker}) — reject`;
+    }
+    for (const section of REQUIRED_SECTIONS) {
+        if (!trimmed.includes(section))
+            return `the summary is missing the required section ${section} — a truncated or incomplete checkpoint`;
+    }
+    return null;
+}
 /**
  * The one-shot summary call. Collects the adapter's text deltas into the
  * summary; usage/stop pass through untouched. Throws when the model
@@ -50,21 +196,38 @@ Rules:
 export async function summarizeConversation(options) {
     const { adapter, model, messages } = options;
     let text = "";
+    let usage = null;
     for await (const ev of adapter.stream({
         model,
         messages,
         systemPrompt: SUMMARY_PROMPT,
         ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        ...(options.maxOutputTokens !== undefined ? { maxTokens: options.maxOutputTokens } : {}),
     })) {
         if (ev.type === "text_delta")
             text += ev.text;
+        // The LAST usage event is the call's (a turn reports usage once).
+        if (ev.type === "usage" && ev.known) {
+            usage = { inputTokens: ev.inputTokens, outputTokens: ev.outputTokens, cacheRead: ev.cacheRead, cacheWrite: ev.cacheWrite };
+        }
     }
     const trimmed = text.trim();
     if (trimmed === "") {
         throw new Error("the summary call produced no text");
     }
-    return trimmed;
+    // E6 (b): a non-checkpoint summary is an honest failure — throw, the
+    // caller reports it, nothing is persisted (the auto-T5-1 regression).
+    const invalid = validateSummary(trimmed);
+    if (invalid !== null) {
+        throw new Error(`the summary call produced an invalid summary: ${invalid}`);
+    }
+    return { text: trimmed, usage };
 }
+/** E6 — the crux-experiment drop arm: the covered turns are replaced by
+ *  this fixed placeholder with NO model call. Experiment-only (the
+ *  contextPolicy drop mode); the adopted shape — if the crux evidence
+ *  earns it — is a distinct `dropped` event family, not this text. */
+export const DROP_PLACEHOLDER = "[e6-crux: the covered turns were dropped without a summary; continue from the kept turns and this placeholder]";
 /**
  * The last summary point: the previous `summarized` event's coversToSeq,
  * or -1 (the trajectory's start) when none exists. The covered range of
@@ -78,6 +241,23 @@ export function lastSummaryPoint(events) {
     }
     return prev;
 }
+/** The chars/4 token proxy for a single EVENT (the same convention as
+ *  estimateTokens, event-shaped — the (f) keep-floor walk needs the kept
+ *  suffix's tokens without projecting it). */
+function estimateEventTokens(ev) {
+    switch (ev.type) {
+        case "user_input":
+            return Math.ceil(ev.content.length / 4);
+        case "text_delta":
+            return Math.ceil(ev.text.length / 4);
+        case "tool_call_end":
+            return Math.ceil(JSON.stringify(ev.input ?? null).length / 4) + 20;
+        case "tool_result":
+            return Math.ceil(String(ev.content ?? "").length / 4);
+        default:
+            return 0;
+    }
+}
 /**
  * The covered range's end: the seq of the event just before the
  * keepRounds-th most recent user_input AFTER the last summary point —
@@ -103,7 +283,7 @@ export function lastSummaryPoint(events) {
  * (the operative list is the LATEST echo — the old ⑥ semantics:
  * superseded echoes stay coverable).
  */
-export function summaryBoundarySeq(events, keepRounds = KEEP_RECENT_ROUNDS) {
+export function summaryBoundarySeq(events, keepRounds = KEEP_RECENT_ROUNDS, keepTokens) {
     const prevPoint = lastSummaryPoint(events);
     const uncoveredInputs = [];
     for (const ev of events) {
@@ -114,6 +294,36 @@ export function summaryBoundarySeq(events, keepRounds = KEEP_RECENT_ROUNDS) {
         return undefined;
     const firstUncovered = uncoveredInputs[0];
     let boundary = uncoveredInputs[uncoveredInputs.length - keepRounds] - 1;
+    // E6 (f): the keep budget is rounds AND tokens. A kept suffix smaller
+    // than keepTokens is a break the session cannot amortize (the E5-F1
+    // accounting) — walk the boundary back (keep more) until the kept
+    // events clear the floor. The walk picks the smallest kept suffix
+    // meeting it: per-event cumulative tokens, one pass. A floor the whole
+    // uncovered range cannot meet → nothing to compact (the policy is
+    // inert on small sessions — the token-shaped restraint).
+    if (keepTokens !== undefined && keepTokens > 0) {
+        const prefixTokens = [0];
+        let total = 0;
+        for (const ev of events) {
+            total += estimateEventTokens(ev);
+            prefixTokens.push(total);
+        }
+        const keptTokens = (b) => total - prefixTokens[b + 1];
+        let floorBoundary;
+        for (let i = uncoveredInputs.length - 1; i >= 0; i--) {
+            const b = uncoveredInputs[i] - 1;
+            if (keptTokens(b) >= keepTokens) {
+                floorBoundary = b;
+                break;
+            }
+        }
+        // b < firstUncovered covers no whole round (or the empty residue) —
+        // the honest nothing-to-compact.
+        if (floorBoundary === undefined || floorBoundary < firstUncovered)
+            return undefined;
+        if (floorBoundary < boundary)
+            boundary = floorBoundary;
+    }
     // The protected pullback applies ONCE on the base range (⑥); the
     // straddle pullback recomputes against the SHRINKING range below it.
     const protectedBoundary = latestProtectedBoundary(events, prevPoint, boundary);

package/dist/trace/guard.d.ts

@@ -22,6 +22,7 @@
  * the honest nullable quartet is a schema bump, deferred.
  */
 import type { Adapter, AdapterEvent, Event, StreamOptions } from "@vincemakes/kiso-core";
+import { type RentParts } from "./rent.js";
 export interface RequestTracerDeps {
     root: string;
     sessionId: string;
@@ -33,6 +34,11 @@ export interface RequestTracerDeps {
     adapterVersion?: string | null;
     /** The session log — the manifest's seqRange pointers derive from it. */
     log: readonly Event[];
+    /** E3 — the rent ledger's inputs: the base prompt as configured and
+     *  the per-extension appends in load order (the adapter's composed
+     *  systemPrompt is their RESULT — the parts are what the ledger
+     *  counts; the composed string itself is unchanged, I6). */
+    rentParts?: RentParts;
 }
 export declare class RequestTracer {
     #private;

package/dist/trace/guard.js

@@ -26,6 +26,7 @@ import { buildContextManifest, segmentHashes } from "./manifest.js";
 import { cacheableHashes } from "./analyze.js";
 import { hashContext, hashSystemPrompt, hashToolSpecs, stablePrefixFingerprint } from "./hash.js";
 import { PRICING_TABLE_V1, canonicalizeUsage } from "../usage/canonical.js";
+import { buildRentLedger } from "./rent.js";
 import { TRACE_SCHEMA_VERSION } from "./record.js";
 import { TraceWriter } from "./writer.js";
 export class RequestTracer {
@@ -34,6 +35,7 @@ export class RequestTracer {
     #provider;
     #runId;
     #adapterVersion;
+    #rentParts;
     #requestIndex = 0;
     #contextHashCounts = new Map();
     constructor(deps) {
@@ -42,6 +44,7 @@ export class RequestTracer {
         this.#provider = deps.provider;
         this.#runId = deps.runId;
         this.#adapterVersion = deps.adapterVersion ?? null;
+        this.#rentParts = deps.rentParts;
     }
     init() {
         this.#writer.init();
@@ -119,6 +122,18 @@ export class RequestTracer {
         this.#contextHashCounts.set(contextHash, retryAttempt + 1);
         const manifest = buildContextManifest({ log: this.#log, systemPrompt, tools, messages });
         const hashes = segmentHashes(systemPrompt, tools, messages);
+        // E3 — the static rent ledger, one line per surface; the envelope
+        // derives from the request the guard already has (R5), the base and
+        // the appends from the threaded parts (R3/R4 — observation only).
+        // exactOptionalPropertyTypes: an absent surface is an absent key —
+        // never an explicit undefined (R9).
+        const rentParts = this.#rentParts;
+        const rent = buildRentLedger({
+            model: options.model,
+            ...(rentParts?.base !== undefined ? { base: rentParts.base } : {}),
+            ...(rentParts?.appends !== undefined ? { appends: rentParts.appends } : {}),
+            ...(tools !== undefined ? { tools } : {}),
+        });
         return {
             schemaVersion: TRACE_SCHEMA_VERSION,
             kind: "request",
@@ -156,6 +171,7 @@ export class RequestTracer {
                 pricingTableId: PRICING_TABLE_V1.id,
                 pricingTableVersion: PRICING_TABLE_V1.version,
             },
+            rent,
             latencyMs: 0,
             ttftMs: 0,
             toolCalls: [],

package/dist/trace/record.d.ts

@@ -19,15 +19,24 @@
  * 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: 2 for 1.3.0 (the canonical block). Version 1 = the 1.2.0
- *  shape, kept for generation-compat reads (R1d-1). Algorithm and shape
- *  changes bump it (ADR-0051 §6 OUT-side versioning). */
-export declare const TRACE_SCHEMA_VERSION = 2;
-/** The versions a reader may meet in a ledger. v1 records are accepted
- *  (generation-compat, R1d-1) and read as defaults — no canonical block. */
+/** 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 declare 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 declare const TRACE_SCHEMA_VERSIONS: Readonly<Set<number>>;
 import type { CanonicalUsage } from "../usage/canonical.js";
+import { type RentLine } from "./rent.js";
 export type Freshness = "fresh" | "cache_read" | "cache_write";
 /** That is the complete set for 1.2.0. */
 export type Outcome = "ok" | "provider_error" | "aborted";
@@ -43,7 +52,7 @@ export interface TraceSegment {
 }
 /** That is the complete set for 1.2.0. */
 export interface TraceRecord {
-    schemaVersion: 2;
+    schemaVersion: 3;
     kind: "request";
     requestId: string;
     runId: string;
@@ -77,6 +86,11 @@ export interface TraceRecord {
      *  the validator pins the equality — and carries the cost from the
      *  versioned pricing table (every cost records its table version). */
     canonical: CanonicalUsage;
+    /** E3 — the static rent ledger: one line per surface (system:base,
+     *  system:ext:<name>, tool:<name>, envelope), counts never payloads —
+     *  see trace/rent.ts. v3 requires the block; a v1/v2 sidecar has none
+     *  and reads as the zero-rent ledger (R2-1). */
+    rent: RentLine[];
     latencyMs: number;
     ttftMs: number;
     toolCalls: string[];
@@ -91,21 +105,21 @@ export interface TraceRecord {
 }
 /** That is the complete set for 1.2.0. */
 export interface HeaderLine {
-    schemaVersion: 2;
+    schemaVersion: 3;
     kind: "header";
     sessionId: string;
     kisoVersion: string;
     createdAt: number;
 }
 export interface RunEndLine {
-    schemaVersion: 2;
+    schemaVersion: 3;
     kind: "run_end";
     runId: string;
     ts: number;
     lastRequestIndex: number;
 }
 export interface CrashLine {
-    schemaVersion: 2;
+    schemaVersion: 3;
     kind: "crash";
     ts: number;
     note: string;
@@ -122,7 +136,9 @@ export declare function hashSpecFor(version: number): HashSpec;
  *  canonical block and reads as defaults at every consumer. */
 export declare const TRACE_RECORD_FIELDS_V1: readonly ["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 declare const TRACE_RECORD_FIELDS: readonly ["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", "canonical"];
+export declare const TRACE_RECORD_FIELDS_V2: readonly ["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", "canonical"];
+/** The 0.2.1 field set (schemaVersion 3) = the v2 set + `rent`. */
+export declare const TRACE_RECORD_FIELDS: readonly ["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", "canonical", "rent"];
 export declare const TRACE_SEGMENT_FIELDS: readonly ["role", "seqRange", "estTokens", "freshness"];
 export declare function validateTraceSegment(v: unknown): v is TraceSegment;
 export declare function validateTraceRecord(v: unknown): v is TraceRecord;

package/dist/trace/record.js

@@ -19,18 +19,28 @@
  * 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: 2 for 1.3.0 (the canonical block). Version 1 = the 1.2.0
- *  shape, kept for generation-compat reads (R1d-1). Algorithm and shape
- *  changes bump it (ADR-0051 §6 OUT-side versioning). */
-export const TRACE_SCHEMA_VERSION = 2;
-/** The versions a reader may meet in a ledger. v1 records are accepted
- *  (generation-compat, R1d-1) and read as defaults — no canonical block. */
-export const TRACE_SCHEMA_VERSIONS = new Set([1, TRACE_SCHEMA_VERSION]);
+/** 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];
@@ -72,7 +82,9 @@ export const TRACE_RECORD_FIELDS_V1 = [
     "ts",
 ];
 /** The 1.3.0 field set (schemaVersion 2) = the v1 set + `canonical`. */
-export const TRACE_RECORD_FIELDS = [...TRACE_RECORD_FIELDS_V1, "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
@@ -119,12 +131,13 @@ export function validateTraceRecord(v) {
     if (!isRecord(v))
         return false;
     const version = v.schemaVersion;
-    // generation-compat (R1d-1): a v1 sidecar has no canonical block and
-    // reads as defaults — accepted, never a crash; the current version is
-    // fully checked (shape + the canonical block + its consistency).
-    if (version !== 1 && version !== TRACE_SCHEMA_VERSION)
+    // 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 : TRACE_RECORD_FIELDS;
+    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")
@@ -197,6 +210,13 @@ export function validateTraceRecord(v) {
                 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;

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;