@noetic-tools/core 5.7.0 → 5.9.0

package/dist/interpreter/execute.js

@@ -1,6 +1,7 @@
 import { frameworkCast, NoeticErrorImpl } from '@noetic-tools/types';
 import { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils.js';
 import { ContextImpl } from '../runtime/context-impl.js';
+import { REPLAY_KEY_PREFIX } from '../runtime/durable/step-ledger.js';
 import { DetachedHandleImpl } from '../util/detached-handle.js';
 import { executeAcpAgent } from './execute-acp-agent.js';
 import { executeCallModel, executeInvokeTool, executeRunCode, executeSpawn, executeWithContext, } from './execute-action.js';
@@ -112,21 +113,47 @@ export async function executeNoAdapter(step, input, ctx) {
     }
 }
 /**
- * Resume path: when a previous run recorded this exact step at `ledgerPath`,
- * replay its output instead of re-running. Held as a helper (rather than inline
- * in `execute`) so the resume branch stays flat: it pops the frontier itself —
- * the caller returns before the normal `leaveStep` runs — and emits
- * `step_replayed`. Returns `{ hit: false }` when there is nothing to replay so
- * the caller dispatches the step normally.
+ * @internal
+ * The ledger key this dispatch records and replays under, or undefined when the
+ * step bypasses the ledger (spec 23a § Identity). A `durable: false` step and a
+ * `schedule` (which never completes) are neither replayed nor recorded; the opt-out
+ * covers this step only, so its children still resolve their own keys. A
+ * `replayKey` replaces the positional path with `key:<key>`. A throwing `replayKey`
+ * costs this dispatch its durability, not its run: the step executes unrecorded.
+ */
+export function resolveLedgerKey(step, input, ctx) {
+    const impl = asContextImpl(frameworkCast(ctx));
+    if (!impl?.ledger || step.id.length === 0) {
+        return undefined;
+    }
+    if (step.durable === false || step.kind === 'schedule') {
+        return undefined;
+    }
+    if (!step.replayKey) {
+        return impl.currentPath();
+    }
+    try {
+        return `${REPLAY_KEY_PREFIX}${step.replayKey(input, ctx)}`;
+    }
+    catch (error) {
+        console.warn(`execute: replayKey for step "${step.id}" threw; running it without replay or recording:`, error instanceof Error ? error.message : String(error));
+        return undefined;
+    }
+}
+/**
+ * Resume path: when a previous run recorded this exact step at `ledgerKey`,
+ * replay its output instead of re-running, and emit `step_replayed`. Returns
+ * `{ hit: false }` when there is nothing to replay so the caller dispatches the
+ * step normally.
  */
 function replayFromLedger(opts) {
-    const { ledger, ledgerPath, impl, step, broadcaster, agentName } = opts;
-    if (!ledger || ledgerPath === undefined || ledger.isEmpty) {
+    const { ledger, ledgerKey, step, broadcaster, agentName } = opts;
+    if (!ledger || ledgerKey === undefined || ledger.isEmpty) {
         return {
             hit: false,
         };
     }
-    const replayed = ledger.take(ledgerPath, {
+    const replayed = ledger.take(ledgerKey, {
         id: step.id,
         kind: step.kind,
     });
@@ -135,9 +162,6 @@ function replayFromLedger(opts) {
             hit: false,
         };
     }
-    if (impl && step.id.length > 0) {
-        impl.leaveStep(step.id);
-    }
     emitFrameworkEvent({
         broadcaster,
         agentName,
@@ -154,16 +178,16 @@ function replayFromLedger(opts) {
 }
 /**
  * Record a completed step's output so a resumed run replays it rather than
- * re-executing. A no-op without a ledger or ledger path. Only successes reach
+ * re-executing. A no-op without a ledger or ledger key. Only successes reach
  * here — a step that threw skips this call in `execute` and runs again on resume.
  */
 async function recordToLedger(opts) {
-    const { ledger, ledgerPath, step, output } = opts;
-    if (!ledger || ledgerPath === undefined) {
+    const { ledger, ledgerKey, step, output } = opts;
+    if (!ledger || ledgerKey === undefined) {
         return;
     }
     await ledger.record({
-        path: ledgerPath,
+        path: ledgerKey,
         stepId: step.id,
         kind: step.kind,
         output,
@@ -220,56 +244,57 @@ export async function execute(step, input, ctx) {
             data: startedData,
         });
     }
-    // Push onto the durable frontier so checkpoints can record exactly which
-    // step was in flight when the snapshot fired. Steps with empty ids are
-    // skipped — they are not reattachable by id and would pollute the stack.
+    /* Register the step as in flight, so a checkpoint records it in the frontier, and
+     * run it on its own lane: a view of the context that carries this dispatch's path.
+     * Steps this step dispatches hang under that path, so concurrent dispatches on one
+     * context cannot interleave each other's paths. Steps with empty ids stay on the
+     * caller's lane — they are not reattachable by id and add no path segment. */
     const impl = asContextImpl(baseCtx);
-    if (impl && step.id.length > 0) {
-        impl.enterStep({
-            stepId: step.id,
-            input,
-        });
-    }
+    const frame = {
+        stepId: step.id,
+        input,
+    };
+    const lane = impl && step.id.length > 0 ? impl.enterStep(frame) : null;
+    const stepCtx = lane ? frameworkCast(lane) : ctx;
     /* Resume: a previous run that completed this exact step replays its recorded
-     * output instead of re-running it. `ledgerPath`/`ledger` are captured before
-     * dispatch and reused by the record below, because `leaveStep` pops the path
-     * on the way out. */
-    const ledgerPath = impl && step.id.length > 0 ? impl.currentPath() : undefined;
+     * output instead of re-running it. `ledgerKey`/`ledger` are captured before
+     * dispatch and reused by the record below. */
+    const ledgerKey = resolveLedgerKey(step, input, stepCtx);
     const ledger = impl?.ledger;
     const replay = replayFromLedger({
         ledger,
-        ledgerPath,
-        impl,
+        ledgerKey,
         step,
         broadcaster,
         agentName,
     });
     if (replay.hit) {
+        lane?.leaveStep(frame);
         return replay.output;
     }
     let result;
     try {
         switch (step.kind) {
             case 'runCode':
-                result = await dispatchViaAdapter(step, input, ctx, () => executeRunCode(step, input, ctx));
+                result = await dispatchViaAdapter(step, input, stepCtx, () => executeRunCode(step, input, stepCtx));
                 break;
             case 'callModel':
-                result = await executeCallModel(step, input, ctx, baseCtx.layers);
+                result = await executeCallModel(step, input, stepCtx, baseCtx.layers);
                 break;
             case 'acp-agent':
-                result = await executeAcpAgent(step, input, ctx, baseCtx.layers);
+                result = await executeAcpAgent(step, input, stepCtx, baseCtx.layers);
                 break;
             case 'invokeTool':
-                result = await executeInvokeTool(step, input, ctx, baseCtx.harness);
+                result = await executeInvokeTool(step, input, stepCtx, baseCtx.harness);
                 break;
             case 'decide':
-                result = await executeDecide(step, input, ctx, baseCtx.layers);
+                result = await executeDecide(step, input, stepCtx, baseCtx.layers);
                 break;
             case 'conditional':
-                result = await executeConditional(step, input, ctx, (s, i, c) => execute(s, i, c));
+                result = await executeConditional(step, input, stepCtx, (s, i, c) => execute(s, i, c));
                 break;
             case 'inParallel':
-                result = await executeInParallel(step, input, ctx, (s, i, c) => execute(s, i, c), {
+                result = await executeInParallel(step, input, stepCtx, (s, i, c) => execute(s, i, c), {
                     // Fork paths are child executions: the layer store lets their
                     // `onSpawn`/`onReturn` boundary run (see `createForkLayerBridge`).
                     layerStore: harnessWithLayerStore(baseCtx).layerStateStore,
@@ -277,16 +302,16 @@ export async function execute(step, input, ctx) {
                 });
                 break;
             case 'spawn':
-                result = await dispatchViaAdapter(step, input, ctx, () => executeSpawn(step, input, ctx, (s, i, c) => execute(s, i, c), buildSpawnOpts(ctx)));
+                result = await dispatchViaAdapter(step, input, stepCtx, () => executeSpawn(step, input, stepCtx, (s, i, c) => execute(s, i, c), buildSpawnOpts(stepCtx)));
                 break;
             case 'withContext':
-                result = await executeWithContext(step, input, ctx, (s, i, c) => execute(s, i, c));
+                result = await executeWithContext(step, input, stepCtx, (s, i, c) => execute(s, i, c));
                 break;
             case 'loop':
-                result = await executeLoop(step, input, ctx, (s, i, c) => execute(s, i, c));
+                result = await executeLoop(step, input, stepCtx, (s, i, c) => execute(s, i, c));
                 break;
             case 'schedule':
-                result = await executeSchedule(step, input, ctx, (s, i, c) => execute(s, i, c));
+                result = await executeSchedule(step, input, stepCtx, (s, i, c) => execute(s, i, c));
                 break;
             default: {
                 const _exhaustive = step;
@@ -301,9 +326,7 @@ export async function execute(step, input, ctx) {
         }
     }
     finally {
-        if (impl && step.id.length > 0) {
-            impl.leaveStep(step.id);
-        }
+        lane?.leaveStep(frame);
     }
     // Emit step_completed framework event (respects step.emit option)
     const completedData = {
@@ -323,7 +346,7 @@ export async function execute(step, input, ctx) {
      * again. */
     await recordToLedger({
         ledger,
-        ledgerPath,
+        ledgerKey,
         step,
         output: result,
     });

package/dist/interpreter/model-error.d.ts

@@ -0,0 +1,9 @@
+import type { Context } from './action-types.js';
+/**
+ * Give an error from a model provider call the step's id and a Noetic kind.
+ *
+ * Noetic errors pass through untouched. A failure on an aborted context is
+ * `cancelled` (the abort is what broke the call), a 429 is `model_rate_limit`,
+ * and anything else is `step_failed` with the provider error as its cause.
+ */
+export declare function wrapModelError(e: unknown, stepId: string, ctx: Pick<Context, 'aborted' | 'abortReason'>): Error;

package/dist/interpreter/model-error.js

@@ -0,0 +1,32 @@
+import { isNoeticError, NoeticConfigError, NoeticErrorImpl } from '@noetic-tools/types';
+import { statusOf } from '../util/status-code.js';
+/**
+ * Give an error from a model provider call the step's id and a Noetic kind.
+ *
+ * Noetic errors pass through untouched. A failure on an aborted context is
+ * `cancelled` (the abort is what broke the call), a 429 is `model_rate_limit`,
+ * and anything else is `step_failed` with the provider error as its cause.
+ */
+export function wrapModelError(e, stepId, ctx) {
+    if (isNoeticError(e) || e instanceof NoeticConfigError) {
+        return e;
+    }
+    if (ctx.aborted) {
+        return new NoeticErrorImpl({
+            kind: 'cancelled',
+            reason: ctx.abortReason ?? 'context aborted',
+        });
+    }
+    if (statusOf(e) === 429) {
+        return new NoeticErrorImpl({
+            kind: 'model_rate_limit',
+            stepId,
+        });
+    }
+    return new NoeticErrorImpl({
+        kind: 'step_failed',
+        stepId,
+        cause: e instanceof Error ? e : new Error(String(e)),
+        retriesExhausted: false,
+    });
+}

package/dist/interpreter/step-walk.d.ts

@@ -0,0 +1,11 @@
+import type { Step } from '@noetic-tools/types';
+/**
+ * Whether `step` or any step nested in it satisfies `test`.
+ *
+ * Only statically declared children are visited: a `conditional` or
+ * `inParallel` built from functions exposes its children through
+ * `_optimizable` only when the builder could enumerate them.
+ */
+export declare function someStep(step: Step, test: (step: Step) => boolean): boolean;
+/** The steps nested directly inside `step`, as far as they are statically known. */
+export declare function stepChildren(step: Step): ReadonlyArray<Step>;

package/dist/interpreter/step-walk.js

@@ -0,0 +1,41 @@
+/**
+ * Whether `step` or any step nested in it satisfies `test`.
+ *
+ * Only statically declared children are visited: a `conditional` or
+ * `inParallel` built from functions exposes its children through
+ * `_optimizable` only when the builder could enumerate them.
+ */
+export function someStep(step, test) {
+    if (test(step)) {
+        return true;
+    }
+    return stepChildren(step).some((child) => someStep(child, test));
+}
+/** The steps nested directly inside `step`, as far as they are statically known. */
+export function stepChildren(step) {
+    switch (step.kind) {
+        case 'callModel':
+        case 'runCode':
+        case 'invokeTool':
+        case 'decide':
+        case 'acp-agent':
+            return [];
+        case 'conditional':
+        case 'inParallel':
+            return step._optimizable ?? [];
+        case 'withContext':
+        case 'spawn':
+            return [
+                step.child,
+            ];
+        case 'loop':
+            return step.steps;
+        case 'schedule':
+            return [
+                step.step,
+            ];
+        default:
+            step;
+            return [];
+    }
+}

package/dist/observability/genai-attributes.d.ts

@@ -1,59 +1,82 @@
 export declare const GenAI: {
-    readonly SYSTEM: 'gen_ai.system';
-    readonly REQUEST_MODEL: 'gen_ai.request.model';
-    readonly USAGE_INPUT_TOKENS: 'gen_ai.usage.input_tokens';
-    readonly USAGE_OUTPUT_TOKENS: 'gen_ai.usage.output_tokens';
+    readonly SYSTEM: "gen_ai.system";
+    readonly REQUEST_MODEL: "gen_ai.request.model";
+    readonly USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens";
+    readonly USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
     /** Prompt tokens served from the provider's cache. Absent if unreported. */
-    readonly USAGE_CACHED_INPUT_TOKENS: 'gen_ai.usage.cached_input_tokens';
+    readonly USAGE_CACHED_INPUT_TOKENS: "gen_ai.usage.cached_input_tokens";
     /** Prompt tokens written into the provider's cache. Absent if unreported. */
-    readonly USAGE_CACHE_WRITE_TOKENS: 'gen_ai.usage.cache_write_tokens';
-    readonly COST: 'gen_ai.cost';
+    readonly USAGE_CACHE_WRITE_TOKENS: "gen_ai.usage.cache_write_tokens";
+    readonly COST: "gen_ai.cost";
 };
 export declare const ToolAttr: {
-    readonly NAME: 'tool.name';
-    readonly NEEDS_APPROVAL: 'tool.needs_approval';
+    readonly NAME: "tool.name";
+    readonly NEEDS_APPROVAL: "tool.needs_approval";
 };
 export declare const NoeticAttr: {
     /** Full JSON-serialised `WorkflowDocument` (the DAG, lossless). */
-    readonly WORKFLOW_DOCUMENT: 'noetic.workflow.document';
+    readonly WORKFLOW_DOCUMENT: "noetic.workflow.document";
     /** Workflow document schema version. */
-    readonly WORKFLOW_VERSION: 'noetic.workflow.version';
+    readonly WORKFLOW_VERSION: "noetic.workflow.version";
     /** Count of declared nodes in the workflow tree. */
-    readonly WORKFLOW_NODE_COUNT: 'noetic.workflow.node_count';
+    readonly WORKFLOW_NODE_COUNT: "noetic.workflow.node_count";
     /** JSON array of `{ id, kind }` for every declared node (flattened graph). */
-    readonly WORKFLOW_NODES: 'noetic.workflow.nodes';
+    readonly WORKFLOW_NODES: "noetic.workflow.nodes";
     /** JSON array of `{ from, to }` parent→child edges between declared nodes. */
-    readonly WORKFLOW_EDGES: 'noetic.workflow.edges';
-    /** Id of the declared workflow node an `llm.call`/`tool.call` span belongs to. */
-    readonly NODE_ID: 'noetic.node.id';
+    readonly WORKFLOW_EDGES: "noetic.workflow.edges";
+    /**
+     * Id of the step a span belongs to: the declared workflow node of an
+     * `llm.call`/`tool.call`, the `decide` step of a `decide.call`, the `spawn`
+     * step of a `spawn` span, the path step of an `inParallel.path` span.
+     */
+    readonly NODE_ID: "noetic.node.id";
+    /** Id of the `inParallel` step an `inParallel.path` span belongs to. */
+    readonly PARALLEL_ID: "noetic.parallel.id";
+    /** Zero-based position of the path among its `inParallel` siblings. */
+    readonly PARALLEL_INDEX: "noetic.parallel.index";
+    /** `NoeticError` kind a `spawn`/`inParallel.path` span failed with. */
+    readonly ERROR_KIND: "noetic.error.kind";
     /**
      * Conversation/session this run belongs to (the run's `ctx.threadId`). Stamped
      * on the root `workflow.run` span so every turn of a multi-turn session shares
      * one id, letting a consumer group per-run traces back into their session.
      */
-    readonly SESSION_ID: 'noetic.session.id';
+    readonly SESSION_ID: "noetic.session.id";
     /** Resource the session is scoped to (the run's `ctx.resourceId`), when set. */
-    readonly RESOURCE_ID: 'noetic.resource.id';
+    readonly RESOURCE_ID: "noetic.resource.id";
     /** Id of the anchoring epoch the assembled view belongs to. */
-    readonly CONTEXT_EPOCH_ID: 'noetic.context.epoch.id';
+    readonly CONTEXT_EPOCH_ID: "noetic.context.epoch.id";
     /** Assemblies served by the current epoch, including this one. */
-    readonly CONTEXT_EPOCH_AGE: 'noetic.context.epoch.age';
+    readonly CONTEXT_EPOCH_AGE: "noetic.context.epoch.age";
     /** Why the epoch re-anchored on this assembly, when it did. */
-    readonly CONTEXT_REANCHOR_REASON: 'noetic.context.reanchor_reason';
+    readonly CONTEXT_REANCHOR_REASON: "noetic.context.reanchor_reason";
     /** Tokens in the anchor band (the cache-stable prefix). */
-    readonly CONTEXT_ANCHOR_TOKENS: 'noetic.context.anchor_tokens';
+    readonly CONTEXT_ANCHOR_TOKENS: "noetic.context.anchor_tokens";
     /** Tokens in the live band (rendered after history). */
-    readonly CONTEXT_LIVE_TOKENS: 'noetic.context.live_tokens';
+    readonly CONTEXT_LIVE_TOKENS: "noetic.context.live_tokens";
     /** Tokens spent superseding stale anchors. */
-    readonly CONTEXT_DELTA_TOKENS: 'noetic.context.delta_tokens';
+    readonly CONTEXT_DELTA_TOKENS: "noetic.context.delta_tokens";
     /** JSON array of `{ id, placement, served }` per contributing layer. */
-    readonly CONTEXT_LAYER_PLACEMENTS: 'noetic.context.layer_placements';
+    readonly CONTEXT_LAYER_PLACEMENTS: "noetic.context.layer_placements";
     /** JSON array of `{ id, rate, rebillTokens }` per contributing layer. */
-    readonly CONTEXT_LAYER_CHURN: 'noetic.context.layer_churn';
+    readonly CONTEXT_LAYER_CHURN: "noetic.context.layer_churn";
     /** `native` or `estimated` — where a decision's probabilities came from. */
-    readonly DECISION_SOURCE: 'noetic.decision.source';
+    readonly DECISION_SOURCE: "noetic.decision.source";
     /** Comma-separated ids of questions the model refused. */
-    readonly DECISION_REFUSED: 'noetic.decision.refused';
+    readonly DECISION_REFUSED: "noetic.decision.refused";
     /** Prefix for per-question attributes: `noetic.decision.<id>.value` etc. */
-    readonly DECISION_PREFIX: 'noetic.decision.';
+    readonly DECISION_PREFIX: "noetic.decision.";
+};
+export declare const NoeticEvent: {
+    /** One per loop iteration: `{ loop, iteration, stop, reason? }`. */
+    readonly LOOP_VERDICT: "loop.verdict";
+    /** A channel dropped data or is waiting with no timeout: `{ kind, channelName, message, capacity?, operation? }`. */
+    readonly CHANNEL_WARNING: "channel.warning";
+    /**
+     * A layer's `onReturn` hook failed, so a spawn or inParallel path returned
+     * its result unchanged. Added to the child's span: `{ stepId, layerId,
+     * message }`. Defined in `@noetic-tools/context`, whose `returnLayers`
+     * emits it and cannot import core.
+     */
+    readonly SPAWN_SUMMARY_FAILED: "spawn.summary_failed";
 };

package/dist/observability/genai-attributes.js

@@ -1,3 +1,4 @@
+import { SPAWN_SUMMARY_FAILED_EVENT } from '@noetic-tools/context';
 // GenAI Semantic Convention attributes
 export const GenAI = {
     SYSTEM: 'gen_ai.system',
@@ -27,8 +28,18 @@ export const NoeticAttr = {
     WORKFLOW_NODES: 'noetic.workflow.nodes',
     /** JSON array of `{ from, to }` parent→child edges between declared nodes. */
     WORKFLOW_EDGES: 'noetic.workflow.edges',
-    /** Id of the declared workflow node an `llm.call`/`tool.call` span belongs to. */
+    /**
+     * Id of the step a span belongs to: the declared workflow node of an
+     * `llm.call`/`tool.call`, the `decide` step of a `decide.call`, the `spawn`
+     * step of a `spawn` span, the path step of an `inParallel.path` span.
+     */
     NODE_ID: 'noetic.node.id',
+    /** Id of the `inParallel` step an `inParallel.path` span belongs to. */
+    PARALLEL_ID: 'noetic.parallel.id',
+    /** Zero-based position of the path among its `inParallel` siblings. */
+    PARALLEL_INDEX: 'noetic.parallel.index',
+    /** `NoeticError` kind a `spawn`/`inParallel.path` span failed with. */
+    ERROR_KIND: 'noetic.error.kind',
     /**
      * Conversation/session this run belongs to (the run's `ctx.threadId`). Stamped
      * on the root `workflow.run` span so every turn of a multi-turn session shares
@@ -60,3 +71,18 @@ export const NoeticAttr = {
     /** Prefix for per-question attributes: `noetic.decision.<id>.value` etc. */
     DECISION_PREFIX: 'noetic.decision.',
 };
+// Span event names. Steps that open no span of their own (e.g. `loop`) add
+// these to the enclosing `ctx.span`.
+export const NoeticEvent = {
+    /** One per loop iteration: `{ loop, iteration, stop, reason? }`. */
+    LOOP_VERDICT: 'loop.verdict',
+    /** A channel dropped data or is waiting with no timeout: `{ kind, channelName, message, capacity?, operation? }`. */
+    CHANNEL_WARNING: 'channel.warning',
+    /**
+     * A layer's `onReturn` hook failed, so a spawn or inParallel path returned
+     * its result unchanged. Added to the child's span: `{ stepId, layerId,
+     * message }`. Defined in `@noetic-tools/context`, whose `returnLayers`
+     * emits it and cannot import core.
+     */
+    SPAWN_SUMMARY_FAILED: SPAWN_SUMMARY_FAILED_EVENT,
+};

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;