@noetic-tools/core 5.6.0 → 5.8.0

package/dist/runtime/channel-store.d.ts

@@ -1,4 +1,36 @@
 import type { Channel, ChannelHandle, ExternalChannel } from '@noetic-tools/types';
+import type { ChannelSnapshot } from '../types/checkpoint.js';
+/**
+ * A channel condition worth surfacing but not worth failing on. `AgentHarness`
+ * records these as `channel.warning` span events (spec 10); a bare store
+ * prints them with `console.warn`.
+ */
+export type ChannelWarning = {
+    /** An external sender hit a full queue and the oldest item was dropped. */
+    kind: 'overflow_drop';
+    channelName: string;
+    capacity: number;
+    message: string;
+} | {
+    /** An external subscriber's private buffer filled and its oldest value was dropped. */
+    kind: 'subscriber_drop';
+    channelName: string;
+    capacity: number;
+    message: string;
+} | {
+    /** A `recv` or parked `send` is waiting with `timeout: 0`, so nothing will time it out. */
+    kind: 'unbounded_wait';
+    channelName: string;
+    operation: 'recv' | 'send';
+    message: string;
+};
+/** Options accepted by the `ChannelStore` constructor. */
+export interface ChannelStoreOpts {
+    /** Receives every channel warning. Defaults to `warnToConsole`. */
+    onWarning?: (warning: ChannelWarning) => void;
+}
+/** Print a channel warning with the `[noetic]` prefix. */
+export declare function warnToConsole(warning: ChannelWarning): void;
 /** Options accepted by internal (back-pressured) `send`. */
 export interface ChannelSendOpts {
     /**
@@ -21,7 +53,34 @@ export declare class ChannelStore {
      */
     private handleObserved;
     private subscribersByExecution;
+    /**
+     * Channel name → ids of the root executions that used it, which decides
+     * the channels an execution's checkpoint carries. Ids stay after their
+     * execution closes: a host may checkpoint a finished run, and channel
+     * state itself lives for the harness lifetime (spec 06, Lifecycle).
+     */
+    private users;
+    private readonly warn;
+    constructor(opts?: ChannelStoreOpts);
     private getOrCreate;
+    /**
+     * Record that `executionId` (a root execution) uses `channel`, so the
+     * channel rides along in its checkpoints.
+     */
+    claim<T>(channel: Channel<T>, executionId: string): void;
+    private addUser;
+    /**
+     * Stored state (values, queued items) of every channel `executionId` used.
+     * Parked receivers, parked senders, and subscribers are live promises and
+     * stay out; topic channels store nothing and are skipped.
+     */
+    snapshot(executionId: string): ChannelSnapshot[];
+    /**
+     * Refill channel state from a checkpoint and mark `executionId` as a user.
+     * A channel that already has live state keeps it — live state is never
+     * older than a snapshot.
+     */
+    restore(executionId: string, snapshots: readonly ChannelSnapshot[]): void;
     /**
      * Subscribe to wake notifications on a channel without consuming any value.
      * Fired once on the next `send()` for any mode, then auto-removed. Returns
@@ -42,8 +101,12 @@ export declare class ChannelStore {
      * - **topic**: deliver to current subscribers, resolve immediately.
      *
      * External callers use `ChannelHandle.send` (sync, drop-oldest) instead.
+     * `opts.timeout: 0` parks with no timeout and warns `unbounded_wait`.
+     *
+     * @throws `NoeticConfigError` with code `INVALID_CHANNEL_TIMEOUT` (as a
+     * rejection) when `opts.timeout` is negative.
      */
-    send<T>(channel: Channel<T>, value: T, opts?: ChannelSendOpts): Promise<void>;
+    send<T>(channel: Channel<T>, value: NoInfer<T>, opts?: ChannelSendOpts): Promise<void>;
     /** Park an internal sender on a full queue until a slot frees (FIFO). */
     private parkSender;
     /**
@@ -53,6 +116,15 @@ export declare class ChannelStore {
     private promotePendingSender;
     /** Fire-and-reset the one-shot wake subscribers for a channel state. */
     private fireWakes;
+    /**
+     * Receive by mode: value returns the current value, queue dequeues the
+     * head, topic waits for the next send. A receiver that has to wait gets
+     * `channel_timeout` after `timeout` ms; `0` waits with no timeout in every
+     * mode and warns `unbounded_wait`.
+     *
+     * @throws `NoeticConfigError` with code `INVALID_CHANNEL_TIMEOUT` (as a
+     * rejection) when `timeout` is negative.
+     */
     recv<T>(channel: Channel<T>, timeout?: number, signal?: AbortSignal): Promise<T>;
     tryRecv<T>(channel: Channel<T>): T | null;
     private waitWithTimeout;

package/dist/runtime/channel-store.js

@@ -1,7 +1,20 @@
-import { frameworkCast, NoeticErrorImpl } from '@noetic-tools/types';
-const MAX_TOPIC_TIMEOUT = 300_000; // 5 minutes
+import { frameworkCast, NoeticConfigError, NoeticErrorImpl } from '@noetic-tools/types';
 const DEFAULT_SEND_TIMEOUT = 30_000;
 const RESOLVED = Promise.resolve();
+/**
+ * Reject a negative (or NaN) channel timeout. `0` is legal and disables the
+ * timeout; anything below it is a caller bug, not a shorter wait.
+ */
+function invalidTimeout(channelName, timeout) {
+    if (timeout >= 0) {
+        return null;
+    }
+    return new NoeticConfigError({
+        code: 'INVALID_CHANNEL_TIMEOUT',
+        message: `Channel '${channelName}': timeout must be a non-negative number of milliseconds, got ${timeout}.`,
+        hint: 'Pass a positive timeout in milliseconds, or 0 to wait with no timeout.',
+    });
+}
 /** Build the `cancelled` error a blocked channel operation rejects with on abort. */
 function cancelledError(signal) {
     return new NoeticErrorImpl({
@@ -9,6 +22,10 @@ function cancelledError(signal) {
         reason: typeof signal.reason === 'string' ? signal.reason : undefined,
     });
 }
+/** Print a channel warning with the `[noetic]` prefix. */
+export function warnToConsole(warning) {
+    console.warn(`[noetic] ${warning.message}`);
+}
 export class ChannelStore {
     channels = new Map();
     closedExecutions = new Set();
@@ -21,25 +38,87 @@ export class ChannelStore {
      */
     handleObserved = new Set();
     subscribersByExecution = new Map();
+    /**
+     * Channel name → ids of the root executions that used it, which decides
+     * the channels an execution's checkpoint carries. Ids stay after their
+     * execution closes: a host may checkpoint a finished run, and channel
+     * state itself lives for the harness lifetime (spec 06, Lifecycle).
+     */
+    users = new Map();
+    warn;
+    constructor(opts = {}) {
+        this.warn = opts.onWarning ?? warnToConsole;
+    }
     getOrCreate(channel) {
-        let state = frameworkCast(this.channels.get(channel.name));
-        if (!state) {
-            state = {
-                mode: channel.mode,
-                hasValue: false,
-                valueWaiters: [],
-                queue: [],
-                capacity: channel.capacity ?? 1_000,
-                queueWaiters: [],
-                pendingSenders: [],
-                topicSubscribers: new Set(),
-                wakeSubscribers: new Set(),
-                externalSubscribers: new Set(),
-            };
-            this.channels.set(channel.name, frameworkCast(state));
+        const existing = frameworkCast(this.channels.get(channel.name));
+        if (existing) {
+            return existing;
         }
+        const state = emptyState(channel.mode, channel.capacity ?? 1_000);
+        this.channels.set(channel.name, frameworkCast(state));
         return state;
     }
+    /**
+     * Record that `executionId` (a root execution) uses `channel`, so the
+     * channel rides along in its checkpoints.
+     */
+    claim(channel, executionId) {
+        this.addUser(channel.name, executionId);
+    }
+    addUser(channelName, executionId) {
+        let ids = this.users.get(channelName);
+        if (!ids) {
+            ids = new Set();
+            this.users.set(channelName, ids);
+        }
+        ids.add(executionId);
+    }
+    /**
+     * Stored state (values, queued items) of every channel `executionId` used.
+     * Parked receivers, parked senders, and subscribers are live promises and
+     * stay out; topic channels store nothing and are skipped.
+     */
+    snapshot(executionId) {
+        const out = [];
+        for (const [name, ids] of this.users) {
+            const state = this.channels.get(name);
+            if (!state || !ids.has(executionId)) {
+                continue;
+            }
+            if (state.mode === 'value') {
+                out.push({
+                    name,
+                    mode: 'value',
+                    value: state.currentValue,
+                    hasValue: state.hasValue,
+                });
+            }
+            if (state.mode === 'queue') {
+                out.push({
+                    name,
+                    mode: 'queue',
+                    capacity: state.capacity,
+                    queue: [
+                        ...state.queue,
+                    ],
+                });
+            }
+        }
+        return out;
+    }
+    /**
+     * Refill channel state from a checkpoint and mark `executionId` as a user.
+     * A channel that already has live state keeps it — live state is never
+     * older than a snapshot.
+     */
+    restore(executionId, snapshots) {
+        for (const snap of snapshots) {
+            if (!this.channels.has(snap.name)) {
+                this.channels.set(snap.name, restoredState(snap));
+            }
+            this.addUser(snap.name, executionId);
+        }
+    }
     /**
      * Subscribe to wake notifications on a channel without consuming any value.
      * Fired once on the next `send()` for any mode, then auto-removed. Returns
@@ -70,8 +149,16 @@ export class ChannelStore {
      * - **topic**: deliver to current subscribers, resolve immediately.
      *
      * External callers use `ChannelHandle.send` (sync, drop-oldest) instead.
+     * `opts.timeout: 0` parks with no timeout and warns `unbounded_wait`.
+     *
+     * @throws `NoeticConfigError` with code `INVALID_CHANNEL_TIMEOUT` (as a
+     * rejection) when `opts.timeout` is negative.
      */
     send(channel, value, opts) {
+        const invalid = invalidTimeout(channel.name, opts?.timeout ?? DEFAULT_SEND_TIMEOUT);
+        if (invalid) {
+            return Promise.reject(invalid);
+        }
         const state = this.getOrCreate(channel);
         let result = RESOLVED;
         switch (state.mode) {
@@ -106,8 +193,8 @@ export class ChannelStore {
                 }
                 break;
             case 'topic':
-                for (const sub of state.topicSubscribers) {
-                    sub(value);
+                for (const waiter of state.topicWaiters.splice(0)) {
+                    waiter.resolve(value);
                 }
                 for (const sub of state.externalSubscribers) {
                     sub.push(value);
@@ -153,7 +240,15 @@ export class ChannelStore {
                 state.pendingSenders.splice(idx, 1);
                 return true;
             };
-            if (timeout > 0) {
+            if (timeout === 0) {
+                this.warn({
+                    kind: 'unbounded_wait',
+                    channelName,
+                    operation: 'send',
+                    message: `Channel '${channelName}': send parked on a full queue with timeout 0 — it waits until a consumer frees a slot or the context aborts.`,
+                });
+            }
+            else {
                 timer = setTimeout(() => {
                     if (removeEntry()) {
                         entry.reject(new NoeticErrorImpl({
@@ -208,7 +303,20 @@ export class ChannelStore {
             wake();
         }
     }
+    /**
+     * Receive by mode: value returns the current value, queue dequeues the
+     * head, topic waits for the next send. A receiver that has to wait gets
+     * `channel_timeout` after `timeout` ms; `0` waits with no timeout in every
+     * mode and warns `unbounded_wait`.
+     *
+     * @throws `NoeticConfigError` with code `INVALID_CHANNEL_TIMEOUT` (as a
+     * rejection) when `timeout` is negative.
+     */
     async recv(channel, timeout = 30_000, signal) {
+        const invalid = invalidTimeout(channel.name, timeout);
+        if (invalid) {
+            throw invalid;
+        }
         // An already-aborted context must reject promptly rather than park a
         // waiter that nothing will ever wake (spec 09, Cancellation item 2).
         if (signal?.aborted) {
@@ -235,46 +343,8 @@ export class ChannelStore {
                 }
                 return this.waitWithTimeout(state.queueWaiters, channel.name, timeout, signal);
             }
-            case 'topic': {
-                // Clamp timeout to prevent indefinite subscriber leaks
-                let effectiveTimeout = timeout;
-                if (effectiveTimeout <= 0) {
-                    console.warn(`[noetic] Channel '${channel.name}': topic recv with non-positive timeout, clamping to ${MAX_TOPIC_TIMEOUT}ms`);
-                    effectiveTimeout = MAX_TOPIC_TIMEOUT;
-                }
-                return new Promise((resolve, reject) => {
-                    let removeAbortListener = null;
-                    const timer = setTimeout(() => {
-                        state.topicSubscribers.delete(handler);
-                        removeAbortListener?.();
-                        reject(new NoeticErrorImpl({
-                            kind: 'channel_timeout',
-                            channelName: channel.name,
-                            timeout: effectiveTimeout,
-                        }));
-                    }, effectiveTimeout);
-                    const handler = (value) => {
-                        clearTimeout(timer);
-                        state.topicSubscribers.delete(handler);
-                        removeAbortListener?.();
-                        resolve(value);
-                    };
-                    state.topicSubscribers.add(handler);
-                    if (signal) {
-                        const onAbort = () => {
-                            clearTimeout(timer);
-                            state.topicSubscribers.delete(handler);
-                            reject(cancelledError(signal));
-                        };
-                        signal.addEventListener('abort', onAbort, {
-                            once: true,
-                        });
-                        removeAbortListener = () => {
-                            signal.removeEventListener('abort', onAbort);
-                        };
-                    }
-                });
-            }
+            case 'topic':
+                return this.waitWithTimeout(state.topicWaiters, channel.name, timeout, signal);
         }
     }
     tryRecv(channel) {
@@ -325,7 +395,15 @@ export class ChannelStore {
                 waiters.splice(idx, 1);
                 return true;
             };
-            if (timeout > 0) {
+            if (timeout === 0) {
+                this.warn({
+                    kind: 'unbounded_wait',
+                    channelName,
+                    operation: 'recv',
+                    message: `Channel '${channelName}': recv waiting with timeout 0 — it waits until a value arrives or the context aborts.`,
+                });
+            }
+            else {
                 timer = setTimeout(() => {
                     if (removeEntry()) {
                         wrappedReject(new NoeticErrorImpl({
@@ -362,7 +440,12 @@ export class ChannelStore {
             state.queueWaiters.length === 0 &&
             state.queue.length >= state.capacity;
         if (isFullQueue) {
-            console.warn(`[noetic] Channel '${channel.name}': queue at capacity (${state.capacity}), dropping oldest message (external sender).`);
+            this.warn({
+                kind: 'overflow_drop',
+                channelName: channel.name,
+                capacity: state.capacity,
+                message: `Channel '${channel.name}': queue at capacity (${state.capacity}), dropping oldest message (external sender).`,
+            });
             state.queue.shift();
             state.queue.push(value);
             this.fireWakes(state);
@@ -391,10 +474,12 @@ export class ChannelStore {
         if (this.closedExecutions.has(executionId)) {
             return CLOSED_ITERABLE;
         }
+        this.claim(channel, executionId);
         const state = this.getOrCreate(channel);
         const subscriber = new ExternalSubscriber({
             channelName: channel.name,
             conflate: state.mode === 'value',
+            warn: this.warn,
             takeShared: state.mode === 'queue'
                 ? () => {
                     const head = this.dequeueHead(state);
@@ -462,6 +547,7 @@ export class ChannelStore {
     }
     getHandle(channel, executionId) {
         this.handleObserved.add(executionId);
+        this.claim(channel, executionId);
         const store = this;
         return {
             get closed() {
@@ -506,6 +592,31 @@ export class ChannelStore {
         this.closedExecutions.delete(executionId);
     }
 }
+function emptyState(mode, capacity) {
+    return {
+        mode,
+        hasValue: false,
+        valueWaiters: [],
+        queue: [],
+        capacity,
+        queueWaiters: [],
+        pendingSenders: [],
+        topicWaiters: [],
+        wakeSubscribers: new Set(),
+        externalSubscribers: new Set(),
+    };
+}
+function restoredState(snap) {
+    if (snap.mode === 'value') {
+        const state = emptyState('value', 1_000);
+        state.currentValue = snap.value;
+        state.hasValue = snap.hasValue;
+        return state;
+    }
+    const state = emptyState('queue', snap.capacity);
+    state.queue.push(...snap.queue);
+    return state;
+}
 const MAX_EXTERNAL_BUFFER = 1_000;
 const CLOSED_ITERABLE = {
     [Symbol.asyncIterator]() {
@@ -559,7 +670,12 @@ class ExternalSubscriber {
             return;
         }
         if (this.buffer.length >= MAX_EXTERNAL_BUFFER) {
-            console.warn(`[noetic] Channel '${this.opts.channelName}': external subscriber buffer at capacity (${MAX_EXTERNAL_BUFFER}), dropping oldest value.`);
+            this.opts.warn({
+                kind: 'subscriber_drop',
+                channelName: this.opts.channelName,
+                capacity: MAX_EXTERNAL_BUFFER,
+                message: `Channel '${this.opts.channelName}': external subscriber buffer at capacity (${MAX_EXTERNAL_BUFFER}), dropping oldest value.`,
+            });
             this.buffer.shift();
         }
         this.buffer.push(value);

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

@@ -1,5 +1,11 @@
 import type { AgentHarnessContract, Channel, ChannelStore, Context, ContextData, ContextLayer, CwdState, EventBroadcaster, FrontierFrame, FsAdapter, Item, ItemLog, ItemSchemaRegistry, LastLayerUsage, Span, StepMeta, TokenUsage, Tool } from './context-deps.js';
 import type { StepLedger } from './durable/step-ledger.js';
+/**
+ * @internal
+ * Id of the root execution `ctx` runs under — the id `run()` opens and
+ * closes channel scopes with (spec 06).
+ */
+export declare function rootIdOf(ctx: Context): string;
 /**
  * @internal
  * The cancellation tree rooted at `ctx`, in pre-order (a parent before its
@@ -14,6 +20,7 @@ export declare class ContextImpl implements Context<ContextData> {
     cost: number;
     state: unknown;
     readonly parent: Context<ContextData> | null;
+    readonly usageParent: Context<ContextData> | null;
     readonly depth: number;
     readonly span: Span;
     readonly threadId: string;
@@ -98,6 +105,8 @@ export declare class ContextImpl implements Context<ContextData> {
     constructor(opts: {
         harness: AgentHarnessContract;
         parent?: Context;
+        /** Charge this context's usage to `parent` as it is spent. Default `true`. */
+        rollUpUsage?: boolean;
         items?: Item[];
         state?: unknown;
         threadId?: string;
@@ -153,7 +162,7 @@ export declare class ContextImpl implements Context<ContextData> {
     recv<T>(ch: Channel<T>, opts?: {
         timeout?: number;
     }): Promise<T>;
-    send<T>(ch: Channel<T>, value: T): Promise<void>;
+    send<T>(ch: Channel<T>, value: NoInfer<T>): Promise<void>;
     tryRecv<T>(ch: Channel<T>): T | null;
     checkpoint(): Promise<void>;
     complete<T>(value: T): void;

package/dist/runtime/context-impl.js

@@ -9,6 +9,18 @@ class NoopSpan {
     addEvent(_name, _attributes) { }
     end() { }
 }
+/**
+ * @internal
+ * Id of the root execution `ctx` runs under — the id `run()` opens and
+ * closes channel scopes with (spec 06).
+ */
+export function rootIdOf(ctx) {
+    let node = ctx;
+    while (node.parent) {
+        node = node.parent;
+    }
+    return node.id;
+}
 /**
  * @internal
  * The cancellation tree rooted at `ctx`, in pre-order (a parent before its
@@ -38,6 +50,7 @@ export class ContextImpl {
     cost = 0;
     state;
     parent;
+    usageParent;
     depth;
     span;
     threadId;
@@ -125,6 +138,7 @@ export class ContextImpl {
         this.harness = opts.harness;
         this.state = opts.state ?? {};
         this.parent = opts.parent ?? null;
+        this.usageParent = opts.rollUpUsage === false ? null : this.parent;
         this.depth = this.parent ? this.parent.depth + 1 : 0;
         this.span = opts.span ?? new NoopSpan();
         this.threadId = opts.threadId ?? crypto.randomUUID();
@@ -213,6 +227,7 @@ export class ContextImpl {
         if (!this.channelStore) {
             return Promise.reject(new Error('No channel store configured'));
         }
+        this.channelStore.claim(ch, rootIdOf(this));
         return this.channelStore.recv(ch, opts?.timeout, this._abortController.signal);
     }
     send(ch, value) {
@@ -222,6 +237,7 @@ export class ContextImpl {
         // Internal sender: back-pressured on full queue channels (default 30s →
         // channel_timeout); aborting this context rejects a parked send with
         // 'cancelled' via the shared abort signal.
+        this.channelStore.claim(ch, rootIdOf(this));
         return this.channelStore.send(ch, value, {
             signal: this._abortController.signal,
         });
@@ -230,6 +246,7 @@ export class ContextImpl {
         if (!this.channelStore) {
             throw new Error('No channel store configured');
         }
+        this.channelStore.claim(ch, rootIdOf(this));
         return this.channelStore.tryRecv(ch);
     }
     async checkpoint() {

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

@@ -1,5 +1,6 @@
 import type { LayerStateStore } from '@noetic-tools/context';
 import type { Context, Item, ItemSchemaRegistry, RestoreContextOptions } from '@noetic-tools/types';
+import type { ChannelStore } from '../channel-store.js';
 import type { EventBroadcaster } from '../event-broadcaster.js';
 import type { CheckpointStore } from './checkpoint-store.js';
 import type { StepLedgerRetention, StepLedgerStore } from './step-ledger.js';
@@ -28,6 +29,7 @@ export interface CheckpointHarnessHandle {
     readonly stepLedgerStore?: StepLedgerStore;
     readonly stepLedgerRetention?: StepLedgerRetention;
     readonly layerStateStore: LayerStateStore;
+    readonly channelStore: Pick<ChannelStore, 'snapshot' | 'restore'>;
     readonly itemSchemas: ItemSchemaRegistry;
     createContext(opts?: RestoreCheckpointOptions & {
         items?: Item[];
@@ -51,7 +53,9 @@ export declare function captureCheckpoint(h: CheckpointHarnessHandle, ctx: Conte
  * `null` if no snapshot is recorded for `executionId`. Layer state is
  * replayed into `layerStateStore` keyed by the original executionId so
  * the restored context observes the pre-crash state through
- * `readLayerState` and the context projectors.
+ * `readLayerState` and the context projectors. Channel values and queued
+ * items are refilled into the channel store, for channels with no live
+ * state.
  *
  * `opts` carries the host's own context wiring (broadcaster, parent, state,
  * layer overrides) into the rebuilt context. A snapshot cannot round-trip live

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

@@ -1,5 +1,5 @@
 import { CheckpointSchemaVersion } from '../../types/checkpoint.js';
-import { ContextImpl } from '../context-impl.js';
+import { ContextImpl, rootIdOf } from '../context-impl.js';
 import { StepLedger } from './step-ledger.js';
 //#endregion
 //#region captureCheckpoint
@@ -47,6 +47,9 @@ export async function captureCheckpoint(h, ctx) {
                 ...ctx.itemLog.items,
             ],
         },
+        // Channel state belongs to the root execution, so a child checkpoint
+        // carries the channels its root used.
+        channels: h.channelStore.snapshot(rootIdOf(ctx)),
         capturedAt: new Date().toISOString(),
     };
     try {
@@ -63,7 +66,9 @@ export async function captureCheckpoint(h, ctx) {
  * `null` if no snapshot is recorded for `executionId`. Layer state is
  * replayed into `layerStateStore` keyed by the original executionId so
  * the restored context observes the pre-crash state through
- * `readLayerState` and the context projectors.
+ * `readLayerState` and the context projectors. Channel values and queued
+ * items are refilled into the channel store, for channels with no live
+ * state.
  *
  * `opts` carries the host's own context wiring (broadcaster, parent, state,
  * layer overrides) into the rebuilt context. A snapshot cannot round-trip live
@@ -91,6 +96,7 @@ export async function restoreFromCheckpoint(h, executionId, opts) {
     for (const [layerId, state] of Object.entries(snapshot.layers)) {
         h.layerStateStore.set(executionId, layerId, state);
     }
+    h.channelStore.restore(executionId, snapshot.channels ?? []);
     const items = h.itemSchemas.parseMany(snapshot.itemLog.items);
     const cwdInit = snapshot.cwd?.current ?? undefined;
     /* Caller wiring first, snapshot second: a host may legitimately swap the context

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

@@ -11,6 +11,12 @@
  * into the single `execution:<id>:snapshot` key would rewrite a growing blob on every
  * step — O(n²) bytes over a run.
  *
+ * An entry's key is one of two forms (spec 23a § Identity). By default it is the step's
+ * execution path (`ContextImpl.currentPath()`): positional, so a resumed run lines up
+ * recorded outputs with steps by where they ran. A step with a `replayKey` is keyed
+ * `key:<replayKey>` instead: content-addressed, so it finds its output wherever it
+ * runs. A `durable: false` step has no key and is never recorded.
+ *
  * Sharding bounds the cost of one append but not the total, so retention is bounded on
  * two axes (`StepLedgerRetention`): an oversized entry is dropped rather than written,
  * and past `maxEntries` the oldest entry is evicted. Both degradations are safe by
@@ -19,7 +25,9 @@
  */
 import type { StorageAdapter } from '@noetic-tools/context';
 import { z } from 'zod';
-/** @public One completed step, keyed by its execution path. */
+/** Marks a ledger key as a step's `replayKey` rather than its execution path. */
+export declare const REPLAY_KEY_PREFIX = "key:";
+/** @public One completed step, keyed by its execution path or its `key:` replay key. */
 export declare const StepLedgerEntrySchema: z.ZodObject<{
     path: z.ZodString;
     stepId: z.ZodString;
@@ -153,9 +161,11 @@ export declare class StepLedger {
     get stats(): StepLedgerStats;
     /**
      * 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.
+     * A divergence (different step id or kind at this key) returns undefined so the step
+     * runs fresh. At a positional path it also discards every entry recorded beneath it —
+     * the subtree's recorded outputs belong to a branch that no longer exists. A `key:`
+     * entry discards only itself: its children are keyed by their own paths or keys, not
+     * nested under it.
      */
     take(path: string, step: {
         id: string;