@noetic-tools/core 5.7.0 → 5.8.0

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
@@ -156,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
@@ -215,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) {
@@ -224,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,
         });
@@ -232,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;

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

@@ -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
@@ -21,9 +27,14 @@ import { storageGetMany } from '@noetic-tools/context';
 import { NoeticConfigError } from '@noetic-tools/types';
 import { z } from 'zod';
 //#region Entry
-/** @public One completed step, keyed by its execution path. */
+/** Marks a ledger key as a step's `replayKey` rather than its execution path. */
+export const REPLAY_KEY_PREFIX = 'key:';
+/** @public One completed step, keyed by its execution path or its `key:` replay key. */
 export const StepLedgerEntrySchema = z.object({
-    /** Execution path key — see `ContextImpl.currentPath()`. Unique per dispatch. */
+    /**
+     * Ledger key: the execution path (`ContextImpl.currentPath()`, unique per dispatch)
+     * or `key:<replayKey>` for a step that sets `replayKey`.
+     */
     path: z.string().min(1),
     stepId: z.string(),
     kind: z.string(),
@@ -197,9 +208,11 @@ export class StepLedger {
     }
     /**
      * 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, step) {
         const entry = this.replayable.get(path);
@@ -207,6 +220,10 @@ export class StepLedger {
             return undefined;
         }
         if (entry.stepId !== step.id || entry.kind !== step.kind) {
+            if (path.startsWith(REPLAY_KEY_PREFIX)) {
+                this.replayable.delete(path);
+                return undefined;
+            }
             this.discardSubtree(path);
             return undefined;
         }

package/dist/types/checkpoint.d.ts

@@ -72,6 +72,26 @@ export declare const ItemLogSnapshotSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** @public Item log portion of a snapshot. */
 export type ItemLogSnapshot = z.infer<typeof ItemLogSnapshotSchema>;
+/**
+ * @public
+ * Channel state an execution used, captured so a restored execution sees the
+ * same values and queued items. Only stored data is kept — parked receivers,
+ * parked senders, and subscribers are live promises that cannot round-trip.
+ * Topic channels hold no stored data, so they never appear.
+ */
+export declare const ChannelSnapshotSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    name: z.ZodString;
+    mode: z.ZodLiteral<"value">;
+    value: z.ZodOptional<z.ZodUnknown>;
+    hasValue: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodString;
+    mode: z.ZodLiteral<"queue">;
+    capacity: z.ZodNumber;
+    queue: z.ZodArray<z.ZodUnknown>;
+}, z.core.$strip>], "mode">;
+/** @public One channel's stored state inside a checkpoint snapshot. */
+export type ChannelSnapshot = z.infer<typeof ChannelSnapshotSchema>;
 /**
  * @public
  * Top-level checkpoint payload persisted through a `CheckpointStore`. Carries
@@ -101,6 +121,17 @@ export declare const CheckpointSnapshotSchema: z.ZodObject<{
     itemLog: z.ZodObject<{
         items: z.ZodArray<z.ZodUnknown>;
     }, z.core.$strip>;
+    channels: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        name: z.ZodString;
+        mode: z.ZodLiteral<"value">;
+        value: z.ZodOptional<z.ZodUnknown>;
+        hasValue: z.ZodBoolean;
+    }, z.core.$strip>, z.ZodObject<{
+        name: z.ZodString;
+        mode: z.ZodLiteral<"queue">;
+        capacity: z.ZodNumber;
+        queue: z.ZodArray<z.ZodUnknown>;
+    }, z.core.$strip>], "mode">>>;
     capturedAt: z.ZodString;
 }, z.core.$strip>;
 /** @public Snapshot of an execution suitable for `CheckpointStore.save()`. */

package/dist/types/checkpoint.js

@@ -68,6 +68,29 @@ export const PendingAskUserSnapshotSchema = z.object({
 export const ItemLogSnapshotSchema = z.object({
     items: z.array(z.unknown()),
 });
+/**
+ * @public
+ * Channel state an execution used, captured so a restored execution sees the
+ * same values and queued items. Only stored data is kept — parked receivers,
+ * parked senders, and subscribers are live promises that cannot round-trip.
+ * Topic channels hold no stored data, so they never appear.
+ */
+export const ChannelSnapshotSchema = z.discriminatedUnion('mode', [
+    z.object({
+        name: z.string(),
+        mode: z.literal('value'),
+        /** The last value written. Absent when the channel was never written. */
+        value: z.unknown().optional(),
+        hasValue: z.boolean(),
+    }),
+    z.object({
+        name: z.string(),
+        mode: z.literal('queue'),
+        capacity: z.number(),
+        /** Queued items, oldest first. */
+        queue: z.array(z.unknown()),
+    }),
+]);
 /**
  * @public
  * Top-level checkpoint payload persisted through a `CheckpointStore`. Carries
@@ -84,6 +107,12 @@ export const CheckpointSnapshotSchema = z.object({
     cwd: CwdSnapshotSchema.nullable(),
     askUser: z.array(PendingAskUserSnapshotSchema),
     itemLog: ItemLogSnapshotSchema,
+    /**
+     * Stored state of every channel the execution used. Optional so snapshots
+     * written before channels were captured still load (they restore with no
+     * channel state).
+     */
+    channels: z.array(ChannelSnapshotSchema).optional(),
     /** ISO-8601 timestamp of when the snapshot was taken. */
     capturedAt: z.string(),
 });

package/dist/until/combinators.d.ts

@@ -2,6 +2,11 @@ import type { Until } from '@noetic-tools/types';
 /**
  * Combines predicates with OR semantics; stops the loop when any predicate says stop.
  *
+ * Predicates run in order and the first stop verdict short-circuits, so it is
+ * returned as is. When none stops, the combined verdict carries every
+ * predicate's `reason` (joined with `'; '`) and `feedback` (joined with `'\n'`),
+ * so a failing `until.verified()` still hands its feedback to `prepareNext`.
+ *
  * @public
  * @param predicates - Until predicates to evaluate.
  * @returns A combined `Until` that short-circuits on the first stop verdict.
@@ -10,6 +15,11 @@ export declare function any(...predicates: Until[]): Until;
 /**
  * Combines predicates with AND semantics; stops the loop only when all predicates say stop.
  *
+ * Predicates run in order and the first continue verdict short-circuits, so it
+ * is returned as is. When all stop, the combined verdict carries every
+ * predicate's `reason` (joined with `'; '`, default `'All predicates
+ * satisfied'`) and `feedback` (joined with `'\n'`).
+ *
  * @public
  * @param predicates - Until predicates to evaluate.
  * @returns A combined `Until` that requires all predicates to be satisfied.