@vincemakes/kiso-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kiso contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @vincemakes/kiso-core
+
+The 2,000-line kernel at the bottom of the kiso framework: the event
+protocol (sum type with seq), the ReAct loop, hooks, modes, permissions,
+microcompact, delivery truth, the lossless event-log projection, and the
+execution ledger keyed by executionId.
+
+See the repository README for the framework overview and the ADRs for
+every decision.

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared API-error → StructuredError mapping for both adapters.
+ *
+ * Classification by status code, never by regex over message text
+ * (ADR-0005). 529 is the Cloudflare overload code most OpenAI-compat
+ * providers proxy raw.
+ */
+import type { StructuredError } from "./protocol/events.js";
+export declare function mapApiError(status: number | undefined, message: string): StructuredError;

package/dist/errors.js

@@ -0,0 +1,29 @@
+/**
+ * Shared API-error → StructuredError mapping for both adapters.
+ *
+ * Classification by status code, never by regex over message text
+ * (ADR-0005). 529 is the Cloudflare overload code most OpenAI-compat
+ * providers proxy raw.
+ */
+export function mapApiError(status, message) {
+    const withStatus = (e) => status !== undefined ? { ...e, status } : e;
+    switch (status) {
+        case 401:
+        case 403:
+            return withStatus({ code: "invalid_request", retryable: false, message });
+        case 408:
+        case 409:
+        case 429:
+            return withStatus({ code: "rate_limit", retryable: true, message });
+        case 529:
+            return withStatus({ code: "overloaded", retryable: true, message });
+        case 400:
+            return withStatus({ code: "invalid_request", retryable: false, message });
+        default:
+            if (status !== undefined && status >= 500 && status < 600) {
+                // D4: every 500-599 is api_5xx and retryable.
+                return withStatus({ code: "api_5xx", retryable: true, message });
+            }
+            return withStatus({ code: "unknown", retryable: false, message });
+    }
+}

package/dist/governance/delivery.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Delivery truth — "done" means the ledger says so, not the model (uooki
+ * done_guard, 30 incidents distilled).
+ *
+ * The kernel's terminal is honest but shallow: `completed` means "the loop
+ * ended on its own terms". Whether the turn DELIVERED what was asked is a
+ * harness-side verdict over the trajectory — this module computes it from
+ * the same events the loop yielded, so the verdict is replayable and the
+ * model's narration never participates in its own grading.
+ *
+ * Producers are declared on tools (`delivers`, tools/tool.ts); the verdict
+ * counts producer calls that completed (non-error results), against a
+ * delivery claim in the text. The canonical lie — "已生成文档" with zero
+ * producer calls and a clean completed terminal — fails here.
+ *
+ * In M3.5 the emission side (artifact URLs extracted from results) joins;
+ * today a completed producer IS the emission.
+ */
+import type { Event } from "../protocol/events.js";
+export interface DeliveryConfig {
+    /** Whether this turn was required to deliver at all. */
+    readonly required: boolean;
+    /** Tool names that produce a deliverable. */
+    readonly producers: ReadonlySet<string>;
+}
+export interface DeliveryVerdict {
+    readonly passed: boolean;
+    /** Producer calls the model actually made. */
+    readonly producerCalls: readonly string[];
+    /** Producer calls that completed (non-error result). */
+    readonly completedProducers: readonly string[];
+    /** The text claimed delivery (a claim is a lie only when unbacked). */
+    readonly claimedInText: boolean;
+}
+export declare function analyzeDelivery(events: readonly Event[], config: DeliveryConfig): DeliveryVerdict;

package/dist/governance/delivery.js

@@ -0,0 +1,47 @@
+/**
+ * Delivery truth — "done" means the ledger says so, not the model (uooki
+ * done_guard, 30 incidents distilled).
+ *
+ * The kernel's terminal is honest but shallow: `completed` means "the loop
+ * ended on its own terms". Whether the turn DELIVERED what was asked is a
+ * harness-side verdict over the trajectory — this module computes it from
+ * the same events the loop yielded, so the verdict is replayable and the
+ * model's narration never participates in its own grading.
+ *
+ * Producers are declared on tools (`delivers`, tools/tool.ts); the verdict
+ * counts producer calls that completed (non-error results), against a
+ * delivery claim in the text. The canonical lie — "已生成文档" with zero
+ * producer calls and a clean completed terminal — fails here.
+ *
+ * In M3.5 the emission side (artifact URLs extracted from results) joins;
+ * today a completed producer IS the emission.
+ */
+const CLAIM_PATTERN = /交付|已生成|已创建|已完成|completed|delivered|done/i;
+export function analyzeDelivery(events, config) {
+    const producerCalls = [];
+    const completedProducers = [];
+    let claimedInText = false;
+    for (const ev of events) {
+        switch (ev.type) {
+            case "text_delta":
+                if (CLAIM_PATTERN.test(ev.text))
+                    claimedInText = true;
+                break;
+            case "tool_call_end":
+                if (config.producers.has(ev.name))
+                    producerCalls.push(ev.callId);
+                break;
+            case "tool_result":
+                if (producerCalls.includes(ev.callId) && !ev.isError) {
+                    completedProducers.push(ev.callId);
+                }
+                break;
+        }
+    }
+    return {
+        passed: !config.required || completedProducers.length > 0,
+        producerCalls,
+        completedProducers,
+        claimedInText,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./protocol/index.js";
+export * from "./tools/tool.js";
+export * from "./tools/registry.js";
+export * from "./errors.js";
+export * from "./kernel/event-log.js";
+export * from "./kernel/hooks.js";
+export * from "./kernel/mode.js";
+export * from "./kernel/permission.js";
+export * from "./kernel/loop.js";
+export * from "./kernel/compaction.js";
+export * from "./kernel/project.js";
+export * from "./kernel/ledger.js";
+export * from "./governance/delivery.js";

package/dist/index.js

@@ -0,0 +1,13 @@
+export * from "./protocol/index.js";
+export * from "./tools/tool.js";
+export * from "./tools/registry.js";
+export * from "./errors.js";
+export * from "./kernel/event-log.js";
+export * from "./kernel/hooks.js";
+export * from "./kernel/mode.js";
+export * from "./kernel/permission.js";
+export * from "./kernel/loop.js";
+export * from "./kernel/compaction.js";
+export * from "./kernel/project.js";
+export * from "./kernel/ledger.js";
+export * from "./governance/delivery.js";

package/dist/kernel/compaction.d.ts

@@ -0,0 +1,60 @@
+/**
+ * L2 — compaction primitives.
+ *
+ * The kernel's compaction policy is identity preservation, not summary
+ * (mauri ADR-0007): keep the message SHELL (id, role, position), replace the
+ * content with a marker, zero LLM calls. A summary is a NEW message; it never
+ * rewrites an old one. Messages are immutable (ADR-0002) — "clearing" is
+ * append, not mutation.
+ *
+ * The idempotence predicate is the first thing here because it is the FIRST
+ * kernel function demanded by a fixture: the compaction-regrowth incident
+ * (uooki 2026, video pipeline) was an O(N²) growth where repeated compaction
+ * re-archived messages already marked cleared, overwriting their original
+ * content. One line fixed it: a marked message is never archived again.
+ */
+import type { AssistantBlock, Message } from "../protocol/messages.js";
+/** Marker prefix for cleared tool results. Must be unambiguous and stable. */
+export declare const CLEARED_MARKER_PREFIX = "[content cleared \u2014 reference by revision]";
+export declare function isClearedMarker(content: string): boolean;
+/** Idempotence gate: a message whose content is already the clear marker is
+ *  never compacted again, never re-archived, never overwritten. */
+export declare function shouldClearContent(content: string): boolean;
+/**
+ * Rough token estimate (chars/4 + structural overhead). Calibration-free on
+ * purpose: compaction only needs a stable MONOTONE proxy, not an exact
+ * count — the threshold absorbs the error (mauri ADR-0007).
+ */
+export declare function estimateTokens(messages: readonly Message[]): number;
+/**
+ * Microcompact — zero-LLM context relief (ported shape from oohki runner,
+ * adapted to kiso's Message union; identity preservation, ADR-0007):
+ *
+ * 1. Find the boundary: the KEEP_RECENT_TURNS-th user message from the end.
+ *    Recent turns stay fully intact — the model must reason about them.
+ * 2. Tool results BEFORE the boundary have their content replaced by a stub
+ *    that keeps the name + char count (an information anchor, not a hole).
+ * 3. Idempotent: already-cleared content is never touched again (the
+ *    compaction-regrowth incident's one-line fix, as a first-class rule).
+ * 4. Returns a NEW array; messages are immutable (ADR-0002).
+ */
+export declare const KEEP_RECENT_TURNS = 5;
+export interface MicrocompactResult {
+    readonly messages: readonly Message[];
+    /** How much content (chars) was cleared this pass. */
+    readonly clearedChars: number;
+    /**
+     * ONLY the tool results cleared THIS pass — the delta, never the
+     * cumulative marker set (五: a replayable trajectory must not record the
+     * same replacement on every turn). `eventSeq` is the cleared result's
+     * stable identity (the tool_result event's seq, attached by the
+     * projection); it is undefined for hand-built messages outside the loop.
+     */
+    readonly cleared: readonly {
+        readonly eventSeq?: number;
+        readonly callId: string;
+        readonly content: string;
+    }[];
+}
+export declare function microcompact(messages: readonly Message[]): MicrocompactResult;
+export type { AssistantBlock };

package/dist/kernel/compaction.js

@@ -0,0 +1,117 @@
+/**
+ * L2 — compaction primitives.
+ *
+ * The kernel's compaction policy is identity preservation, not summary
+ * (mauri ADR-0007): keep the message SHELL (id, role, position), replace the
+ * content with a marker, zero LLM calls. A summary is a NEW message; it never
+ * rewrites an old one. Messages are immutable (ADR-0002) — "clearing" is
+ * append, not mutation.
+ *
+ * The idempotence predicate is the first thing here because it is the FIRST
+ * kernel function demanded by a fixture: the compaction-regrowth incident
+ * (uooki 2026, video pipeline) was an O(N²) growth where repeated compaction
+ * re-archived messages already marked cleared, overwriting their original
+ * content. One line fixed it: a marked message is never archived again.
+ */
+/** Marker prefix for cleared tool results. Must be unambiguous and stable. */
+export const CLEARED_MARKER_PREFIX = "[content cleared — reference by revision]";
+export function isClearedMarker(content) {
+    return content.startsWith(CLEARED_MARKER_PREFIX);
+}
+/** Idempotence gate: a message whose content is already the clear marker is
+ *  never compacted again, never re-archived, never overwritten. */
+export function shouldClearContent(content) {
+    return !isClearedMarker(content);
+}
+/**
+ * Rough token estimate (chars/4 + structural overhead). Calibration-free on
+ * purpose: compaction only needs a stable MONOTONE proxy, not an exact
+ * count — the threshold absorbs the error (mauri ADR-0007).
+ */
+export function estimateTokens(messages) {
+    let total = 0;
+    for (const msg of messages) {
+        if (msg.role === "user") {
+            total += Math.ceil(msg.content.length / 4);
+        }
+        else if (msg.role === "assistant") {
+            for (const block of msg.blocks) {
+                total +=
+                    block.type === "text"
+                        ? Math.ceil(block.text.length / 4)
+                        : Math.ceil(JSON.stringify(block.input).length / 4) + 20;
+            }
+        }
+        else {
+            total += Math.ceil(msg.content.length / 4) + 10;
+        }
+    }
+    return total;
+}
+/**
+ * Microcompact — zero-LLM context relief (ported shape from oohki runner,
+ * adapted to kiso's Message union; identity preservation, ADR-0007):
+ *
+ * 1. Find the boundary: the KEEP_RECENT_TURNS-th user message from the end.
+ *    Recent turns stay fully intact — the model must reason about them.
+ * 2. Tool results BEFORE the boundary have their content replaced by a stub
+ *    that keeps the name + char count (an information anchor, not a hole).
+ * 3. Idempotent: already-cleared content is never touched again (the
+ *    compaction-regrowth incident's one-line fix, as a first-class rule).
+ * 4. Returns a NEW array; messages are immutable (ADR-0002).
+ */
+export const KEEP_RECENT_TURNS = 5;
+export function microcompact(messages) {
+    const userIndices = [];
+    for (let i = 0; i < messages.length; i++) {
+        if (messages[i]?.role === "user")
+            userIndices.push(i);
+    }
+    if (userIndices.length <= KEEP_RECENT_TURNS) {
+        return { messages, clearedChars: 0, cleared: [] };
+    }
+    const recentBoundary = userIndices[userIndices.length - KEEP_RECENT_TURNS];
+    const nameByCallId = buildToolNameMap(messages);
+    let clearedChars = 0;
+    const cleared = [];
+    let changed = false;
+    const result = messages.map((msg, i) => {
+        if (i >= recentBoundary || msg.role !== "tool")
+            return msg;
+        if (typeof msg.content !== "string")
+            return msg; // binary content is untouched
+        if (!shouldClearContent(msg.content))
+            return msg; // idempotence gate
+        const toolName = nameByCallId.get(msg.callId) ?? "unknown";
+        const eventSeq = msg.eventSeq;
+        clearedChars += msg.content.length;
+        cleared.push({
+            ...(eventSeq !== undefined ? { eventSeq } : {}),
+            callId: msg.callId,
+            content: `${CLEARED_MARKER_PREFIX} ${toolName} returned ${msg.content.length.toLocaleString()} chars — compacted`,
+        });
+        changed = true;
+        return {
+            ...msg,
+            content: `${CLEARED_MARKER_PREFIX} ${toolName} returned ${msg.content.length.toLocaleString()} chars — compacted`,
+        };
+    });
+    return {
+        messages: changed ? result : messages,
+        clearedChars,
+        cleared,
+    };
+}
+/** callId → tool name, from assistant tool_use blocks (for the stub). */
+function buildToolNameMap(messages) {
+    const map = new Map();
+    for (const msg of messages) {
+        if (msg.role !== "assistant")
+            continue;
+        for (const block of msg.blocks) {
+            if (block.type === "tool_use")
+                map.set(block.callId, block.name);
+        }
+    }
+    return map;
+}

package/dist/kernel/event-log.d.ts

@@ -0,0 +1,44 @@
+/**
+ * L2 — the EventLog: the kernel's single truth (ADR-0002).
+ *
+ * Every event the loop yields passes through here. `seq` is assigned HERE,
+ * and only here: an adapter's seq is a "stream-local ordering hint" that this
+ * log re-asserts, because the loop interleaves adapter events with its own
+ * (tool_result, terminal). One allocator, monotonic by construction — there
+ * is no second copy of history to desync, and a trajectory is the replay of
+ * seq 0..N.
+ */
+import type { Event } from "../protocol/events.js";
+/**
+ * An event without its seq — what producers emit.
+ *
+ * Distribution note: conditional types only distribute over a BARE type
+ * parameter — `Event extends unknown ? Omit<Event, "seq"> : never` does NOT
+ * distribute (Event is a concrete alias, not a parameter) and collapses the
+ * union to its common keys. Wrapping the union in a generic parameter is
+ * what keeps each variant's own fields (callId, outcome, text, ...).
+ */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export type EventInput = DistributiveOmit<Event, "seq">;
+export declare class EventLog {
+    #private;
+    /**
+     * A log may be seeded with an existing trajectory (a session rebuilt
+     * from disk, Phase C). The seed is STRICTLY validated: seq must be
+     * exactly 0..N. A gap or duplicate means the trajectory is damaged —
+     * the array length must never mask it (Area 1). Numbering continues
+     * after the seed; `seq` remains the single allocator from here on.
+     */
+    constructor(initial?: readonly Event[]);
+    /**
+     * Append an event; assigns the authoritative seq and returns it.
+     * `seq` is assigned HERE and only here — a producer's seq is a
+     * stream-local hint, never trusted (ADR-0002).
+     */
+    append(ev: EventInput): Event;
+    get all(): readonly Event[];
+    /** Incremental view for consumers that already saw `seq` and before. */
+    since(seq: number): readonly Event[];
+    get lastSeq(): number;
+}
+export {};

package/dist/kernel/event-log.js

@@ -0,0 +1,51 @@
+/**
+ * L2 — the EventLog: the kernel's single truth (ADR-0002).
+ *
+ * Every event the loop yields passes through here. `seq` is assigned HERE,
+ * and only here: an adapter's seq is a "stream-local ordering hint" that this
+ * log re-asserts, because the loop interleaves adapter events with its own
+ * (tool_result, terminal). One allocator, monotonic by construction — there
+ * is no second copy of history to desync, and a trajectory is the replay of
+ * seq 0..N.
+ */
+export class EventLog {
+    #events;
+    #next;
+    /**
+     * A log may be seeded with an existing trajectory (a session rebuilt
+     * from disk, Phase C). The seed is STRICTLY validated: seq must be
+     * exactly 0..N. A gap or duplicate means the trajectory is damaged —
+     * the array length must never mask it (Area 1). Numbering continues
+     * after the seed; `seq` remains the single allocator from here on.
+     */
+    constructor(initial = []) {
+        for (let i = 0; i < initial.length; i++) {
+            const seq = initial[i].seq;
+            if (seq !== i) {
+                throw new Error(`EventLog: seq discontinuity — expected ${i}, got ${seq}`);
+            }
+        }
+        this.#events = [...initial];
+        this.#next = initial.length;
+    }
+    /**
+     * Append an event; assigns the authoritative seq and returns it.
+     * `seq` is assigned HERE and only here — a producer's seq is a
+     * stream-local hint, never trusted (ADR-0002).
+     */
+    append(ev) {
+        const full = { ...ev, seq: this.#next++ };
+        this.#events.push(full);
+        return full;
+    }
+    get all() {
+        return this.#events;
+    }
+    /** Incremental view for consumers that already saw `seq` and before. */
+    since(seq) {
+        return this.#events.filter((e) => e.seq >= seq);
+    }
+    get lastSeq() {
+        return this.#next - 1;
+    }
+}

package/dist/kernel/hooks.d.ts

@@ -0,0 +1,52 @@
+/**
+ * L2 — the hook vocabulary: 3 phases + lifecycle (mauri ADR-0006).
+ *
+ * ReAct's loop has exactly three model↔world interfaces — assemble (feed the
+ * model), model (the model speaks), execute (the model makes the world work)
+ * — plus lifecycle points around them. Every hook is either a transform
+ * (returns a replacement) or an observer (void); the kernel never invents
+ * phases beyond these nine.
+ *
+ * Payload types are SHARED between fire-site and read-site: a hook author
+ * cannot drift a key name, because the keys do not exist — the payload is a
+ * typed object (the mauri payload-contract discipline, ADR-0017, as a
+ * compile-time fact instead of a written rule).
+ */
+import type { Event } from "../protocol/events.js";
+import type { Message, UserMessage } from "../protocol/messages.js";
+import type { ToolResult } from "../tools/tool.js";
+import type { PermissionDecision } from "./permission.js";
+export interface HookContext {
+    readonly sessionId?: string;
+}
+export interface PreLlmPayload {
+    readonly model: string;
+    readonly turns: number;
+}
+export interface ToolCallPayload {
+    readonly callId: string;
+    readonly name: string;
+    readonly input: Readonly<Record<string, unknown>>;
+}
+export interface HookHost {
+    /** Assemble: rewrite or veto the incoming user message. null = drop. */
+    onUserMessage?(msg: UserMessage, ctx: HookContext): Promise<UserMessage | null>;
+    /** Assemble: last word before the model is called. */
+    onPreLlm?(payload: PreLlmPayload, ctx: HookContext): Promise<void>;
+    /** Model: observer over every event as it flows. Never throws outward. */
+    onEvent?(event: Event, ctx: HookContext): Promise<void>;
+    /** Execute: permission negotiation before a tool runs. */
+    onPreTool?(call: ToolCallPayload, ctx: HookContext): Promise<PermissionDecision>;
+    /** Execute: rewrite the result a tool returns. */
+    onPostTool?(call: ToolCallPayload, result: ToolResult, ctx: HookContext): Promise<ToolResult>;
+    /** Lifecycle: compaction is about to replace history. */
+    onPreCompact?(messages: readonly Message[], ctx: HookContext): Promise<void>;
+    /** Lifecycle: compaction finished. */
+    onPostCompact?(messages: readonly Message[], ctx: HookContext): Promise<void>;
+    /** Lifecycle: the loop paused (human decision pending). */
+    onPause?(reason: string, ctx: HookContext): Promise<void>;
+    /** Lifecycle: the loop is about to stop. */
+    onStop?(reason: string, ctx: HookContext): Promise<void>;
+}
+/** Every hook optional; unset = pass-through. The kernel runs with this. */
+export declare const NoOpHooks: HookHost;

package/dist/kernel/hooks.js

@@ -0,0 +1,16 @@
+/**
+ * L2 — the hook vocabulary: 3 phases + lifecycle (mauri ADR-0006).
+ *
+ * ReAct's loop has exactly three model↔world interfaces — assemble (feed the
+ * model), model (the model speaks), execute (the model makes the world work)
+ * — plus lifecycle points around them. Every hook is either a transform
+ * (returns a replacement) or an observer (void); the kernel never invents
+ * phases beyond these nine.
+ *
+ * Payload types are SHARED between fire-site and read-site: a hook author
+ * cannot drift a key name, because the keys do not exist — the payload is a
+ * typed object (the mauri payload-contract discipline, ADR-0017, as a
+ * compile-time fact instead of a written rule).
+ */
+/** Every hook optional; unset = pass-through. The kernel runs with this. */
+export const NoOpHooks = {};

package/dist/kernel/ledger.d.ts

@@ -0,0 +1,43 @@
+/**
+ * L2 — the execution ledger: exactly-once side effects from the event log.
+ *
+ * Every tool execution writes `tool_execution_started` before the handler
+ * and `tool_execution_succeeded` / `tool_execution_failed` after
+ * (kernel/loop.ts). From those events alone — no second store — this module
+ * answers the recovery questions:
+ *
+ *   1. What is the durable status of execution X? (`executionLedger`)
+ *   2. What is the latest execution of call Y? (`executionForCallId`)
+ *
+ * IDENTITY (Area 3): the ledger is keyed by `executionId` — a persistent,
+ * framework-generated id unique per log (one per started event). The
+ * provider's `callId` is correlation only and may repeat; two logical calls
+ * with identical (name, input) are two executions.
+ *
+ * Status derivation:
+ *   started, no terminal event yet   → "uncertain"   (interrupted: human)
+ *   succeeded                        → "succeeded"   (confirmed, never re-run)
+ *   failed, safeToRetry (idempotent) → "failed"      (clean failure)
+ *   failed, not safeToRetry          → "uncertain"   (side effects possible)
+ *   resolved "rerun"                 → "rerun"       (human cleared it)
+ *   resolved "abandoned"             → "abandoned"   (human killed it)
+ */
+import type { Event } from "../protocol/events.js";
+export type ExecutionStatus = "uncertain" | "succeeded" | "failed" | "rerun" | "abandoned";
+export interface ExecutionRecord {
+    readonly executionId: string;
+    readonly callId: string;
+    readonly name: string;
+    readonly input: Readonly<Record<string, unknown>>;
+    readonly status: ExecutionStatus;
+    /** Present when `status` is "succeeded" — the durable result to replay. */
+    readonly result?: {
+        readonly content: string;
+        readonly isError: false;
+    };
+    readonly error?: string;
+}
+/** executionId → durable status, rebuilt purely from events (ADR-0002). */
+export declare function executionLedger(events: readonly Event[]): Map<string, ExecutionRecord>;
+/** The LATEST execution record for a provider call id (correlation only). */
+export declare function executionForCallId(events: readonly Event[], callId: string): ExecutionRecord | undefined;

package/dist/kernel/ledger.js

@@ -0,0 +1,88 @@
+/**
+ * L2 — the execution ledger: exactly-once side effects from the event log.
+ *
+ * Every tool execution writes `tool_execution_started` before the handler
+ * and `tool_execution_succeeded` / `tool_execution_failed` after
+ * (kernel/loop.ts). From those events alone — no second store — this module
+ * answers the recovery questions:
+ *
+ *   1. What is the durable status of execution X? (`executionLedger`)
+ *   2. What is the latest execution of call Y? (`executionForCallId`)
+ *
+ * IDENTITY (Area 3): the ledger is keyed by `executionId` — a persistent,
+ * framework-generated id unique per log (one per started event). The
+ * provider's `callId` is correlation only and may repeat; two logical calls
+ * with identical (name, input) are two executions.
+ *
+ * Status derivation:
+ *   started, no terminal event yet   → "uncertain"   (interrupted: human)
+ *   succeeded                        → "succeeded"   (confirmed, never re-run)
+ *   failed, safeToRetry (idempotent) → "failed"      (clean failure)
+ *   failed, not safeToRetry          → "uncertain"   (side effects possible)
+ *   resolved "rerun"                 → "rerun"       (human cleared it)
+ *   resolved "abandoned"             → "abandoned"   (human killed it)
+ */
+/** executionId → durable status, rebuilt purely from events (ADR-0002). */
+export function executionLedger(events) {
+    const ledger = new Map();
+    for (const ev of events) {
+        switch (ev.type) {
+            case "tool_execution_started":
+                ledger.set(ev.executionId, {
+                    executionId: ev.executionId,
+                    callId: ev.callId,
+                    name: ev.name,
+                    input: ev.input,
+                    status: "uncertain",
+                });
+                break;
+            case "tool_execution_succeeded": {
+                const prior = ledger.get(ev.executionId);
+                if (prior) {
+                    ledger.set(ev.executionId, { ...prior, status: "succeeded", result: ev.result });
+                }
+                break;
+            }
+            case "tool_execution_failed": {
+                const prior = ledger.get(ev.executionId);
+                if (prior) {
+                    ledger.set(ev.executionId, {
+                        ...prior,
+                        // Area 3: only a tool that proved safe-to-retry gets a
+                        // clean "failed"; everything else may have produced a
+                        // side effect and is uncertain until a human decides.
+                        status: ev.safeToRetry ? "failed" : "uncertain",
+                        ...(ev.error !== undefined ? { error: ev.error } : {}),
+                    });
+                }
+                break;
+            }
+            case "tool_execution_resolved": {
+                const prior = ledger.get(ev.executionId);
+                if (prior) {
+                    ledger.set(ev.executionId, {
+                        ...prior,
+                        status: ev.resolution === "rerun" ? "rerun" : "abandoned",
+                    });
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return ledger;
+}
+/** The LATEST execution record for a provider call id (correlation only). */
+export function executionForCallId(events, callId) {
+    const ledger = executionLedger(events);
+    let found;
+    for (const ev of events) {
+        if (ev.type !== "tool_execution_started")
+            continue;
+        if (ev.callId !== callId)
+            continue;
+        found = ledger.get(ev.executionId);
+    }
+    return found;
+}