@noetic-tools/core 2.3.0 → 2.5.0

package/dist/builders/tool-builder.d.ts

@@ -1,4 +1,4 @@
-import type { FunctionCallItem, FunctionCallOutputItem, Item, ItemSchemaExtensions, Tool, ToolExecutionContext, ToolMemoryDeclaration, ToolResultExtensionItem } from '@noetic-tools/types';
+import type { FunctionCallItem, FunctionCallOutputItem, Item, ItemSchemaExtensions, Tool, ToolExecutionContext, ToolMemoryDeclaration, ToolResultExtensionItem, ToolUiDeclaration } from '@noetic-tools/types';
 import type { ZodTypeAny, z } from 'zod';
 interface ToolConfig<I extends ZodTypeAny, O extends ZodTypeAny> {
     name: string;
@@ -18,6 +18,8 @@ interface ToolConfig<I extends ZodTypeAny, O extends ZodTypeAny> {
     needsApproval?: boolean;
     /** Optional memory declaration — the runtime generates a MemoryLayer from this via toolMemoryLayer(). */
     memory?: ToolMemoryDeclaration;
+    /** Optional UI declaration — the runtime emits the rendered fragments at call/progress/result points. */
+    ui?: ToolUiDeclaration<I, O>;
 }
 interface GeneratorToolConfig<I extends ZodTypeAny, E extends ZodTypeAny, O extends ZodTypeAny> {
     name: string;
@@ -38,6 +40,8 @@ interface GeneratorToolConfig<I extends ZodTypeAny, E extends ZodTypeAny, O exte
     needsApproval?: boolean;
     /** Optional memory declaration — the runtime generates a MemoryLayer from this via toolMemoryLayer(). */
     memory?: ToolMemoryDeclaration;
+    /** Optional UI declaration — the runtime emits the rendered fragments at call/progress/result points. */
+    ui?: ToolUiDeclaration<I, O, z.infer<E>>;
 }
 /**
  * Creates a typed Tool with Zod schema inference for input and output.

package/dist/builders/tool-builder.js

@@ -36,6 +36,7 @@ export function tool(config) {
         execute: config.execute,
         needsApproval: config.needsApproval,
         memory: config.memory,
+        ui: config.ui,
     };
 }
 /**
@@ -56,6 +57,7 @@ export function toolWithGenerator(config) {
         execute: config.execute,
         needsApproval: config.needsApproval,
         memory: config.memory,
+        ui: config.ui,
     };
 }
 //#endregion

package/dist/harness/agent-harness.d.ts

@@ -1,7 +1,7 @@
 import { ItemSchemaRegistry } from '@noetic-tools/types';
 import type { DetachedSpawnOverrides } from './deps/interpreter.js';
 import type { LayerStateStore, RecallCache } from './deps/memory.js';
-import type { CheckpointStore, EventBroadcaster } from './deps/runtime.js';
+import type { CheckpointStore, EventBroadcaster, StepLedgerStore } from './deps/runtime.js';
 import type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, ContextMemory, CwdState, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaExtensions, LLMResponse, LlmProviderConfig, MemoryLayer, ProjectionPolicy, RecallLayerOutput, SessionScope, ShellAdapter, Span, SteeringDecision, Step, StorageAdapter, StreamEvent, StreamingItem, SubHarnessSession, SubprocessAdapter, Tool, TraceExporter, ZodType } from './deps/types.js';
 export { createStreamIdleWatchdog } from './model-call.js';
 interface AgentHarnessOpts<TParams extends Record<string, unknown> = Record<string, unknown>> {
@@ -105,6 +105,12 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
      * @internal
      */
     readonly checkpointStore?: CheckpointStore;
+    /**
+     * Append-only step ledger backing resume. Present exactly when durability is on
+     * (a `CheckpointStore` is configured), so a zero-config harness records nothing.
+     * @internal
+     */
+    readonly stepLedgerStore?: StepLedgerStore;
     private readonly initialStep?;
     /** Harness-wide tool pool merged into every context's `unifiedTools`. */
     private readonly harnessTools;

package/dist/harness/agent-harness.js

@@ -4,7 +4,7 @@ import { NoopExporter } from '../observability/trace-exporter.js';
 import { createInMemoryFsAdapter, createInMemoryShellAdapter, createInMemorySubprocessAdapter, OpenRouter, } from './deps/adapters.js';
 import { collectAllTools, deduplicateTools, dispatchStepThroughAdapter, execute, } from './deps/interpreter.js';
 import { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, contextToExecCtx, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from './deps/memory.js';
-import { buildItemStream, ChannelStore, ContextImpl, captureCheckpoint, createInMemoryStorage, filterReasoningStream, filterTextStream, restoreFromCheckpoint, SessionRunner, snapshotCwdState, } from './deps/runtime.js';
+import { buildItemStream, ChannelStore, ContextImpl, captureCheckpoint, createInMemoryStorage, createStepLedgerStore, filterReasoningStream, filterTextStream, restoreFromCheckpoint, SessionRunner, StepLedger, snapshotCwdState, } from './deps/runtime.js';
 import { SteeringAction } from './deps/types.js';
 import { AgentHarnessModelCaller } from './model-call.js';
 export { createStreamIdleWatchdog } from './model-call.js';
@@ -124,6 +124,12 @@ export class AgentHarness {
      * @internal
      */
     checkpointStore;
+    /**
+     * Append-only step ledger backing resume. Present exactly when durability is on
+     * (a `CheckpointStore` is configured), so a zero-config harness records nothing.
+     * @internal
+     */
+    stepLedgerStore;
     initialStep;
     /** Harness-wide tool pool merged into every context's `unifiedTools`. */
     harnessTools;
@@ -181,6 +187,11 @@ export class AgentHarness {
         this.shell = opts.shell ?? createInMemoryShellAdapter();
         this.subprocess = opts.subprocess ?? createInMemorySubprocessAdapter();
         this.checkpointStore = opts.checkpointStore;
+        this.stepLedgerStore = opts.checkpointStore
+            ? createStepLedgerStore({
+                storage: this.config.storage ?? createInMemoryStorage(),
+            })
+            : undefined;
         this.initialStep = opts.initialStep;
         this.harnessTools = opts.tools ?? [];
         this._memory = opts.memory;
@@ -433,6 +444,10 @@ export class AgentHarness {
         await this.initLayers(layers, ctx, storage);
     }
     detachedSpawn(s, input, parentCtx, overrides) {
+        /* NOT a checkpoint boundary, despite spec 23 listing one here: a DetachedHandle's
+         * settle is only observable via `await()`, and calling it internally would consume
+         * the result the caller is holding. The handle manifest is the adapter's own
+         * durability surface (`listLive`/`reattach`), so nothing is lost. */
         return dispatchStepThroughAdapter(this, s, input, parentCtx, overrides);
     }
     createContext(opts) {
@@ -442,13 +457,27 @@ export class AgentHarness {
             base: this.itemSchemas,
             layers: effectiveMemory,
         });
+        /* The execution id is chosen here rather than inside ContextImpl so the ledger
+         * can be keyed to it — the ledger's storage keys and `ctx.id` must agree for a
+         * later `restore()` to find what this run recorded. */
+        const executionId = crypto.randomUUID();
         return new ContextImpl({
             ...rest,
+            id: executionId,
             harness: this,
             channelStore: this.channelStore,
             layers: effectiveMemory,
             itemSchemas,
             cwdState: resolveContextCwdState(this.rootCwdState, opts?.parent, cwdInit),
+            // Without this `ctx.checkpoint()` is inert, and the boundaries below never
+            // persist anything (a no-op when no CheckpointStore is configured).
+            checkpointFn: (c) => this.checkpoint(c),
+            ledger: this.stepLedgerStore
+                ? new StepLedger({
+                    executionId,
+                    store: this.stepLedgerStore,
+                })
+                : undefined,
         });
     }
     send(channel, value, ctx) {
@@ -704,13 +733,16 @@ export class AgentHarness {
                 rerenderRequests: [],
             };
         }
-        return runAppendPipeline({
+        const piped = await runAppendPipeline({
             layers,
             items,
             ctx: this.toExecCtx(ctx),
             log: ctx.itemLog,
             store: this.layerStateStore,
         });
+        // Layer state can mutate as items land, so the snapshot must follow the fold.
+        await this.checkpoint(ctx);
+        return piped;
     }
     async executeRerender(requests, layers, ctx, budgets, query) {
         return executeRerender({

package/dist/harness/deps/runtime.d.ts

@@ -3,6 +3,8 @@ export { ContextImpl } from '../../runtime/context-impl.js';
 export { snapshotCwdState } from '../../runtime/cwd-helpers.js';
 export type { CheckpointStore } from '../../runtime/durable/index.js';
 export { captureCheckpoint, restoreFromCheckpoint, } from '../../runtime/durable/harness-checkpoints.js';
+export type { StepLedgerEntry, StepLedgerStore } from '../../runtime/durable/step-ledger.js';
+export { createStepLedgerStore, StepLedger } from '../../runtime/durable/step-ledger.js';
 export type { EventBroadcaster } from '../../runtime/event-broadcaster.js';
 export { createInMemoryStorage } from '../../runtime/in-memory-storage.js';
 export type { QueuedMessage } from '../../runtime/message-queue.js';

package/dist/harness/deps/runtime.js

@@ -2,6 +2,7 @@ export { ChannelStore } from '../../runtime/channel-store.js';
 export { ContextImpl } from '../../runtime/context-impl.js';
 export { snapshotCwdState } from '../../runtime/cwd-helpers.js';
 export { captureCheckpoint, restoreFromCheckpoint, } from '../../runtime/durable/harness-checkpoints.js';
+export { createStepLedgerStore, StepLedger } from '../../runtime/durable/step-ledger.js';
 export { createInMemoryStorage } from '../../runtime/in-memory-storage.js';
 export { SessionRunner } from '../../runtime/session-runner.js';
 export { buildItemStream, filterReasoningStream, filterTextStream, } from '../../runtime/session-streams.js';

package/dist/interpreter/execute-action.js

@@ -591,6 +591,10 @@ export async function executeSpawn(step, input, ctx, executeStep, opts) {
         unifiedTools: childUnifiedTools.length > 0 ? childUnifiedTools : undefined,
         cwdState: snapshotCwdState(baseCtx),
         id: childId,
+        // The spawn's own path prefixes the child's, so a resumed run lines its steps up
+        // with the ones recorded inside the same spawn rather than at the root.
+        pathPrefix: baseCtx instanceof ContextImpl ? baseCtx.currentPath() : '',
+        ledger: baseCtx instanceof ContextImpl ? baseCtx.ledger : undefined,
     });
     try {
         // Execute the child step

package/dist/interpreter/execute-control.js

@@ -23,11 +23,18 @@ function createChildContexts(ctx, count, stepId) {
     const threadId = isContextImpl(ctx) ? ctx.threadId : crypto.randomUUID();
     const resourceId = isContextImpl(ctx) ? ctx.resourceId : undefined;
     const channelStore = getContextChannelStore(ctx);
+    const parentPath = isContextImpl(ctx) ? ctx.currentPath() : '';
+    const parentLedger = isContextImpl(ctx) ? ctx.ledger : undefined;
     return Array.from({
         length: count,
-    }, () => new ContextImpl({
+    }, (_unused, index) => new ContextImpl({
         harness: ctx.harness,
         parent: ctx,
+        /* Ledger paths must stay unique across sibling paths: a child ContextImpl
+         * starts with an empty frontier, so without a prefix every path would
+         * restart at the root and collide with its siblings. */
+        pathPrefix: `${parentPath}[${index}]`,
+        ledger: parentLedger,
         items: [
             ...ctx.itemLog.items,
         ],

package/dist/interpreter/execute.js

@@ -172,6 +172,32 @@ export async function execute(step, input, ctx) {
             input,
         });
     }
+    /* Resume: a previous run that completed this exact step replays its recorded
+     * output instead of re-running it. Captured before dispatch and held for the
+     * record below, because `leaveStep` pops the path on the way out. */
+    const ledgerPath = impl && step.id.length > 0 ? impl.currentPath() : undefined;
+    const ledger = impl?.ledger;
+    if (ledger && ledgerPath !== undefined && !ledger.isEmpty) {
+        const replayed = ledger.take(ledgerPath, {
+            id: step.id,
+            kind: step.kind,
+        });
+        if (replayed) {
+            if (impl && step.id.length > 0) {
+                impl.leaveStep(step.id);
+            }
+            emitFrameworkEvent({
+                broadcaster,
+                agentName,
+                eventType: 'step_replayed',
+                data: {
+                    stepId: step.id,
+                    kind: step.kind,
+                },
+            });
+            return frameworkCast(replayed.output);
+        }
+    }
     let result;
     try {
         switch (step.kind) {
@@ -243,5 +269,22 @@ export async function execute(step, input, ctx) {
             data: completedData,
         });
     }
+    /* Record the completed step so a resumed run replays this output rather than
+     * re-running the step. Only successes are recorded: a step that threw must run
+     * again. */
+    if (ledger && ledgerPath !== undefined) {
+        await ledger.record({
+            path: ledgerPath,
+            stepId: step.id,
+            kind: step.kind,
+            output: result,
+            completedAt: new Date().toISOString(),
+        });
+    }
+    /* Durability boundary (spec 23): snapshot after each completed step, so a crash
+     * lands on a checkpoint that includes the item-log and layer-state mutations this
+     * step produced. A no-op unless the harness has a CheckpointStore, and a failing
+     * save is logged rather than thrown — durability must never fail a good step. */
+    await baseCtx.checkpoint();
     return result;
 }

package/dist/runtime/context-impl.d.ts

@@ -1,4 +1,5 @@
 import type { AgentHarnessContract, Channel, ChannelStore, Context, ContextMemory, CwdState, EventBroadcaster, FrontierFrame, FsAdapter, Item, ItemLog, ItemSchemaRegistry, LastLayerUsage, MemoryLayer, Span, StepMeta, TokenUsage, Tool } from './context-deps.js';
+import type { StepLedger } from './durable/step-ledger.js';
 export declare class ContextImpl implements Context<ContextMemory> {
     readonly id: string;
     stepCount: number;
@@ -53,6 +54,31 @@ export declare class ContextImpl implements Context<ContextMemory> {
      * @internal
      */
     private readonly _frontier;
+    /**
+     * Path segment for each in-flight frame, parallel to `_frontier`. Kept separate so
+     * `serialiseFrontier()` keeps emitting the published `FrontierFrame` shape.
+     * @internal
+     */
+    private readonly _segments;
+    /**
+     * Path this context's steps hang under. Empty on a root context; a fork/spawn child
+     * inherits its parent's current path plus a discriminator, so a path key stays unique
+     * across the whole step tree rather than restarting per child context.
+     * @internal
+     */
+    private readonly _pathPrefix;
+    /**
+     * Dispatch counts per `<parent path>/<step id>`, so a loop body re-entered on each
+     * iteration gets `#0`, `#1`, … instead of colliding on one key.
+     * @internal
+     */
+    private readonly _occurrences;
+    /**
+     * Completion ledger for the execution this context belongs to. Shared by reference
+     * with fork/spawn children — one execution, one ledger.
+     * @internal
+     */
+    readonly ledger?: StepLedger;
     constructor(opts: {
         harness: AgentHarnessContract;
         parent?: Context;
@@ -62,7 +88,11 @@ export declare class ContextImpl implements Context<ContextMemory> {
         resourceId?: string;
         span?: Span;
         channelStore?: ChannelStore;
-        checkpointFn?: () => Promise<void>;
+        checkpointFn?: (ctx: Context) => Promise<void>;
+        /** Path this context's steps hang under (fork/spawn children inherit one). */
+        pathPrefix?: string;
+        /** The execution's completion ledger, shared with children by reference. */
+        ledger?: StepLedger;
         layers?: MemoryLayer[];
         unifiedTools?: ReadonlyArray<Tool>;
         itemSchemas?: ItemSchemaRegistry;
@@ -108,6 +138,14 @@ export declare class ContextImpl implements Context<ContextMemory> {
      * stack of steps currently in-flight on this context.
      */
     enterStep(frame: FrontierFrame): void;
+    /**
+     * @internal
+     * The execution path of the step currently on top of the frontier — the ledger key
+     * identifying this exact dispatch. Stable across a replay given the same control
+     * flow, which is what lets a resumed run line recorded outputs up with the steps
+     * that produced them.
+     */
+    currentPath(): string;
     /**
      * @internal
      * Pop the top frame. Called when a step resolves (success or failure)

package/dist/runtime/context-impl.js

@@ -67,6 +67,31 @@ export class ContextImpl {
      * @internal
      */
     _frontier = [];
+    /**
+     * Path segment for each in-flight frame, parallel to `_frontier`. Kept separate so
+     * `serialiseFrontier()` keeps emitting the published `FrontierFrame` shape.
+     * @internal
+     */
+    _segments = [];
+    /**
+     * Path this context's steps hang under. Empty on a root context; a fork/spawn child
+     * inherits its parent's current path plus a discriminator, so a path key stays unique
+     * across the whole step tree rather than restarting per child context.
+     * @internal
+     */
+    _pathPrefix;
+    /**
+     * Dispatch counts per `<parent path>/<step id>`, so a loop body re-entered on each
+     * iteration gets `#0`, `#1`, … instead of colliding on one key.
+     * @internal
+     */
+    _occurrences = new Map();
+    /**
+     * Completion ledger for the execution this context belongs to. Shared by reference
+     * with fork/spawn children — one execution, one ledger.
+     * @internal
+     */
+    ledger;
     constructor(opts) {
         this.id = opts.id ?? crypto.randomUUID();
         this._createdAt = Date.now();
@@ -79,6 +104,8 @@ export class ContextImpl {
         this.resourceId = opts.resourceId;
         this.channelStore = opts.channelStore;
         this._checkpointFn = opts.checkpointFn;
+        this._pathPrefix = opts.pathPrefix ?? '';
+        this.ledger = opts.ledger;
         this.layers = opts.layers;
         this.unifiedTools = opts.unifiedTools;
         this.itemSchemas = opts.itemSchemas ?? defaultItemSchemaRegistry;
@@ -140,7 +167,7 @@ export class ContextImpl {
     }
     async checkpoint() {
         if (this._checkpointFn) {
-            await this._checkpointFn();
+            await this._checkpointFn(this);
         }
     }
     complete(value) {
@@ -180,8 +207,23 @@ export class ContextImpl {
      * stack of steps currently in-flight on this context.
      */
     enterStep(frame) {
+        const parent = this.currentPath();
+        const key = `${parent}/${frame.stepId}`;
+        const occurrence = this._occurrences.get(key) ?? 0;
+        this._occurrences.set(key, occurrence + 1);
+        this._segments.push(`/${frame.stepId}#${occurrence}`);
         this._frontier.push(frame);
     }
+    /**
+     * @internal
+     * The execution path of the step currently on top of the frontier — the ledger key
+     * identifying this exact dispatch. Stable across a replay given the same control
+     * flow, which is what lets a resumed run line recorded outputs up with the steps
+     * that produced them.
+     */
+    currentPath() {
+        return this._pathPrefix + this._segments.join('');
+    }
     /**
      * @internal
      * Pop the top frame. Called when a step resolves (success or failure)
@@ -198,6 +240,7 @@ export class ContextImpl {
             console.warn(`ContextImpl.leaveStep: expected "${expectedStepId}" on top of frontier but saw "${top.stepId}".`);
         }
         this._frontier.pop();
+        this._segments.pop();
     }
     /**
      * @internal

package/dist/runtime/durable/harness-checkpoints.d.ts

@@ -1,6 +1,7 @@
 import type { LayerStateStore, MemoryLayer } from '@noetic-tools/memory';
 import type { Context, Item, ItemSchemaRegistry } from '@noetic-tools/types';
 import type { CheckpointStore } from './checkpoint-store.js';
+import type { StepLedgerStore } from './step-ledger.js';
 /**
  * Minimum harness surface `captureCheckpoint` / `restoreFromCheckpoint`
  * require. `AgentHarness` already satisfies this shape via its
@@ -11,6 +12,7 @@ import type { CheckpointStore } from './checkpoint-store.js';
  */
 export interface CheckpointHarnessHandle {
     readonly checkpointStore?: CheckpointStore;
+    readonly stepLedgerStore?: StepLedgerStore;
     readonly layerStateStore: LayerStateStore;
     readonly itemSchemas: ItemSchemaRegistry;
     readonly _memory?: MemoryLayer[];

package/dist/runtime/durable/harness-checkpoints.js

@@ -1,5 +1,6 @@
 import { CheckpointSchemaVersion } from '../../types/checkpoint.js';
 import { ContextImpl } from '../context-impl.js';
+import { StepLedger } from './step-ledger.js';
 //#endregion
 //#region captureCheckpoint
 /**
@@ -98,6 +99,24 @@ export async function restoreFromCheckpoint(h, executionId) {
             writable: false,
             enumerable: true,
         });
+        /* Attach the recovered completion ledger. `createContext` already built a fresh
+         * one keyed to a throwaway id; the restored context needs the entries recorded
+         * under THIS execution, or `execute()` would replay nothing and re-run the whole
+         * tree. Assigned the same way `id` is, to keep `createContext`'s public options
+         * free of resume-only fields. */
+        if (h.stepLedgerStore) {
+            const recovered = await h.stepLedgerStore.load(executionId);
+            Object.defineProperty(ctx, 'ledger', {
+                value: new StepLedger({
+                    executionId,
+                    store: h.stepLedgerStore,
+                    recovered,
+                }),
+                configurable: false,
+                writable: false,
+                enumerable: true,
+            });
+        }
     }
     return ctx;
 }

package/dist/runtime/durable/step-ledger.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The step completion ledger: what a resumed execution replays instead of re-running.
+ *
+ * The frontier records which steps were IN FLIGHT at snapshot time; it says nothing
+ * about which ones finished, and a finished step leaves no trace once `leaveStep` pops
+ * it. Resume therefore needs a separate record — and it must carry each step's OUTPUT,
+ * not merely a "done" flag: steps consume the previous step's value, and an `llm` step
+ * re-run to catch up produces a different one than the rest of the run already saw.
+ *
+ * Entries are stored one key per step so appends are O(1). Folding the whole ledger
+ * into the single `execution:<id>:snapshot` key would rewrite a growing blob on every
+ * step — O(n²) bytes over a run.
+ */
+import type { StorageAdapter } from '@noetic-tools/memory';
+import { z } from 'zod';
+/** @public One completed step, keyed by its execution path. */
+export declare const StepLedgerEntrySchema: z.ZodObject<{
+    path: z.ZodString;
+    stepId: z.ZodString;
+    kind: z.ZodString;
+    output: z.ZodUnknown;
+    completedAt: z.ZodString;
+}, z.core.$strip>;
+/** @public A completed step recorded for replay. */
+export type StepLedgerEntry = z.infer<typeof StepLedgerEntrySchema>;
+/** Storage key prefix owning every ledger entry for one execution. */
+export declare function stepLedgerPrefix(executionId: string): string;
+/**
+ * @public
+ * Durable append-only ledger for one harness's executions. Backed by the same
+ * `StorageAdapter` as the checkpoint store; it reserves the `:ledger:` suffix that
+ * `CheckpointKeys` already sets aside.
+ */
+export interface StepLedgerStore {
+    /** Record a completed step. Sequence numbers order entries within an execution. */
+    append: (executionId: string, seq: number, entry: StepLedgerEntry) => Promise<void>;
+    /** Every recorded entry for an execution, keyed by path. Corrupt rows are skipped. */
+    load: (executionId: string) => Promise<Map<string, StepLedgerEntry>>;
+    /** Drop an execution's ledger (paired with `CheckpointStore.clear`). */
+    clear: (executionId: string) => Promise<void>;
+}
+export declare function createStepLedgerStore(opts: {
+    storage: StorageAdapter;
+}): StepLedgerStore;
+/**
+ * @public
+ * The in-memory ledger a single execution carries: entries recovered from a previous
+ * run (available for replay) plus the sequence counter for newly recorded ones.
+ *
+ * Shared by reference across fork/spawn children so one execution has one ledger —
+ * path keys are globally unique across the step tree, so a flat map is correct.
+ */
+export declare class StepLedger {
+    /** Recovered entries, by path. Consumed as replay proceeds. */
+    private readonly replayable;
+    private seq;
+    private readonly store?;
+    private readonly executionId;
+    constructor(opts: {
+        executionId: string;
+        store?: StepLedgerStore;
+        recovered?: Map<string, StepLedgerEntry>;
+    });
+    /** True when this execution has nothing recovered to replay (the common, fresh case). */
+    get isEmpty(): boolean;
+    /**
+     * The recorded output for `path`, when a previous run completed the same step there.
+     * A divergence (different step id or kind at this path) discards the entry and every
+     * entry recorded beneath it, then returns undefined so the step runs fresh — the
+     * subtree's recorded outputs belong to a branch that no longer exists.
+     */
+    take(path: string, step: {
+        id: string;
+        kind: string;
+    }): StepLedgerEntry | undefined;
+    /** Drop `path` and everything recorded below it. */
+    private discardSubtree;
+    /** Record a completed step. Best-effort: a failed write costs resumability, not the run. */
+    record(entry: StepLedgerEntry): Promise<void>;
+}

package/dist/runtime/durable/step-ledger.js

@@ -0,0 +1,131 @@
+/**
+ * The step completion ledger: what a resumed execution replays instead of re-running.
+ *
+ * The frontier records which steps were IN FLIGHT at snapshot time; it says nothing
+ * about which ones finished, and a finished step leaves no trace once `leaveStep` pops
+ * it. Resume therefore needs a separate record — and it must carry each step's OUTPUT,
+ * not merely a "done" flag: steps consume the previous step's value, and an `llm` step
+ * re-run to catch up produces a different one than the rest of the run already saw.
+ *
+ * Entries are stored one key per step so appends are O(1). Folding the whole ledger
+ * into the single `execution:<id>:snapshot` key would rewrite a growing blob on every
+ * step — O(n²) bytes over a run.
+ */
+import { z } from 'zod';
+/** @public One completed step, keyed by its execution path. */
+export const StepLedgerEntrySchema = z.object({
+    /** Execution path key — see `ContextImpl.currentPath()`. Unique per dispatch. */
+    path: z.string().min(1),
+    stepId: z.string(),
+    kind: z.string(),
+    /** Replayed verbatim in place of re-running the step. */
+    output: z.unknown(),
+    completedAt: z.string(),
+});
+/** Storage key prefix owning every ledger entry for one execution. */
+export function stepLedgerPrefix(executionId) {
+    return `execution:${executionId}:ledger:`;
+}
+/** Zero-pad so lexicographic key order matches dispatch order under `list()`. */
+function seqKey(executionId, seq) {
+    return `${stepLedgerPrefix(executionId)}${String(seq).padStart(8, '0')}`;
+}
+export function createStepLedgerStore(opts) {
+    const { storage } = opts;
+    return {
+        append: async (executionId, seq, entry) => {
+            await storage.set(seqKey(executionId, seq), entry);
+        },
+        load: async (executionId) => {
+            const keys = await storage.list(stepLedgerPrefix(executionId));
+            const byPath = new Map();
+            for (const key of keys) {
+                const raw = await storage.get(key);
+                if (raw === null || raw === undefined) {
+                    continue;
+                }
+                const parsed = StepLedgerEntrySchema.safeParse(raw);
+                if (!parsed.success) {
+                    /* A row we cannot read is a step we cannot replay — it simply re-runs.
+                     * Dropping it is safe; failing the resume over it would not be. */
+                    console.warn(`StepLedger: discarding unreadable entry "${key}": ${parsed.error.message}`);
+                    continue;
+                }
+                byPath.set(parsed.data.path, parsed.data);
+            }
+            return byPath;
+        },
+        clear: async (executionId) => {
+            const keys = await storage.list(stepLedgerPrefix(executionId));
+            for (const key of keys) {
+                await storage.delete(key);
+            }
+        },
+    };
+}
+/**
+ * @public
+ * The in-memory ledger a single execution carries: entries recovered from a previous
+ * run (available for replay) plus the sequence counter for newly recorded ones.
+ *
+ * Shared by reference across fork/spawn children so one execution has one ledger —
+ * path keys are globally unique across the step tree, so a flat map is correct.
+ */
+export class StepLedger {
+    /** Recovered entries, by path. Consumed as replay proceeds. */
+    replayable;
+    seq;
+    store;
+    executionId;
+    constructor(opts) {
+        this.executionId = opts.executionId;
+        this.store = opts.store;
+        this.replayable = opts.recovered ?? new Map();
+        this.seq = this.replayable.size;
+    }
+    /** True when this execution has nothing recovered to replay (the common, fresh case). */
+    get isEmpty() {
+        return this.replayable.size === 0;
+    }
+    /**
+     * The recorded output for `path`, when a previous run completed the same step there.
+     * A divergence (different step id or kind at this path) discards the entry and every
+     * entry recorded beneath it, then returns undefined so the step runs fresh — the
+     * subtree's recorded outputs belong to a branch that no longer exists.
+     */
+    take(path, step) {
+        const entry = this.replayable.get(path);
+        if (!entry) {
+            return undefined;
+        }
+        if (entry.stepId !== step.id || entry.kind !== step.kind) {
+            this.discardSubtree(path);
+            return undefined;
+        }
+        return entry;
+    }
+    /** Drop `path` and everything recorded below it. */
+    discardSubtree(path) {
+        for (const key of [
+            ...this.replayable.keys(),
+        ]) {
+            if (key === path || key.startsWith(`${path}/`)) {
+                this.replayable.delete(key);
+            }
+        }
+    }
+    /** Record a completed step. Best-effort: a failed write costs resumability, not the run. */
+    async record(entry) {
+        if (!this.store) {
+            return;
+        }
+        const seq = this.seq;
+        this.seq += 1;
+        try {
+            await this.store.append(this.executionId, seq, entry);
+        }
+        catch (error) {
+            console.warn(`StepLedger: failed to record "${entry.path}":`, error instanceof Error ? error.message : String(error));
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/core",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "type": "module",
   "description": "Step primitives, interpreter, runtime, and memory layer contract for Noetic agents.",
   "license": "Apache-2.0",