@noetic-tools/core 5.8.0 → 5.9.0

package/dist/runtime/context-impl.js

@@ -99,30 +99,24 @@ export class ContextImpl {
     _children = new Set();
     _contextData;
     /**
-     * Stack of steps currently in flight on this context, most-recent last.
-     * Pushed by `enterStep` at the top of `execute()` and popped by
-     * `leaveStep` when the step resolves (success or failure). The harness'
-     * checkpoint writer serialises this stack as the execution frontier so
-     * a restart can identify which step the context was paused inside.
+     * Steps in flight on this context, in dispatch order. `enterStep` adds a frame and
+     * `leaveStep` removes that same frame, so concurrent dispatches can settle in any
+     * order without disturbing each other. The checkpoint writer serialises this set as
+     * the execution frontier.
      * @internal
      */
-    _frontier = [];
+    _inFlight = new Set();
     /**
-     * Path segment for each in-flight frame, parallel to `_frontier`. Kept separate so
-     * `serialiseFrontier()` keeps emitting the published `FrontierFrame` shape.
+     * Execution path of the step whose lane this is. On the context itself it is the
+     * prefix its steps hang under: empty on a root context, the parent's path plus a
+     * discriminator on an inParallel/spawn child, so a path stays unique across the whole
+     * step tree. A lane (see `enterStep`) reads its own step's path here instead.
      * @internal
      */
-    _segments = [];
-    /**
-     * Path this context's steps hang under. Empty on a root context; an inParallel/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;
+    _path;
     /**
      * 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.
+     * iteration gets `#0`, `#1`, … instead of colliding on one key. Shared by every lane.
      * @internal
      */
     _occurrences = new Map();
@@ -145,7 +139,7 @@ export class ContextImpl {
         this.resourceId = opts.resourceId;
         this.channelStore = opts.channelStore;
         this._checkpointFn = opts.checkpointFn;
-        this._pathPrefix = opts.pathPrefix ?? '';
+        this._path = opts.pathPrefix ?? '';
         this.ledger = opts.ledger;
         this.layers = opts.layers;
         this.unifiedTools = opts.unifiedTools;
@@ -300,45 +294,35 @@ export class ContextImpl {
     }
     /**
      * @internal
-     * Push a frame onto the execution frontier. Called by `execute()` at the
-     * top of every step dispatch so that the frontier reflects exactly the
-     * stack of steps currently in-flight on this context.
+     * Register `frame` as in flight and return the lane its step runs on: a view of
+     * this context that shares everything except its execution path. `execute()` hands
+     * the lane to the step, so steps the step dispatches hang under its path no matter
+     * how other dispatches on this context interleave. The occurrence ordinal is taken
+     * here, at dispatch, never at settle.
      */
     enterStep(frame) {
-        const parent = this.currentPath();
-        const key = `${parent}/${frame.stepId}`;
+        const key = `${this._path}/${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);
+        this._inFlight.add(frame);
+        return laneOf(this, `${key}#${occurrence}`);
     }
     /**
      * @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.
+     * The execution path of the step this lane belongs to — 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('');
+        return this._path;
     }
     /**
      * @internal
-     * Pop the top frame. Called when a step resolves (success or failure)
-     * so that the frontier unwinds cleanly. The value of `expectedStepId`
-     * is used as a consistency check — if it does not match the top frame
-     * the pop is still performed, but a best-effort warning is surfaced to
-     * stderr rather than swallowed silently.
+     * Drop `frame` from the in-flight set. Called when its step resolves, success or
+     * failure.
      */
-    leaveStep(expectedStepId) {
-        const top = this._frontier[this._frontier.length - 1];
-        if (top && top.stepId !== expectedStepId) {
-            // A mismatch indicates bookkeeping drift. We unwind best-effort and
-            // let the caller observe via `serialiseFrontier()` if needed.
-            console.warn(`ContextImpl.leaveStep: expected "${expectedStepId}" on top of frontier but saw "${top.stepId}".`);
-        }
-        this._frontier.pop();
-        this._segments.pop();
+    leaveStep(frame) {
+        this._inFlight.delete(frame);
     }
     /**
      * @internal
@@ -346,10 +330,46 @@ export class ContextImpl {
      * checkpoint writer — see `AgentHarness.checkpoint`.
      */
     serialiseFrontier() {
-        return this._frontier.map((frame) => ({
+        return [
+            ...this._inFlight,
+        ].map((frame) => ({
             stepId: frame.stepId,
             input: frame.input,
             state: frame.state,
         }));
     }
 }
+//#region Lanes
+/** The context each lane views, so `laneOf` never stacks a proxy on a proxy. */
+const laneTargets = new WeakMap();
+/**
+ * A view of `ctx` that reads `path` as its execution path and forwards every other
+ * read and write to the context itself, so state, usage, abort, and the in-flight set
+ * stay shared. A Proxy rather than a subclass: steps assign `ctx.state` and friends
+ * directly, and a copy would keep those writes to itself.
+ */
+function laneOf(ctx, path) {
+    const target = laneTargets.get(ctx) ?? ctx;
+    const lane = new Proxy(target, {
+        get(base, prop, receiver) {
+            if (prop === '_path') {
+                return path;
+            }
+            return Reflect.get(base, prop, receiver);
+        },
+        set(base, prop, value) {
+            return Reflect.set(base, prop, value);
+        },
+    });
+    laneTargets.set(lane, target);
+    return lane;
+}
+/**
+ * @internal
+ * The context a lane views, or `ctx` itself when it is not a lane. For per-execution
+ * caches keyed by context identity, which every lane of one context must share.
+ */
+export function laneBase(ctx) {
+    return ctx instanceof ContextImpl ? (laneTargets.get(ctx) ?? ctx) : ctx;
+}
+//#endregion

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

@@ -49,29 +49,42 @@ export interface CheckpointHarnessHandle {
  */
 export declare function captureCheckpoint(h: CheckpointHarnessHandle, ctx: Context): Promise<void>;
 /**
- * Rebuild a `Context` from a previously-persisted snapshot. Returns
- * `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. Channel values and queued
- * items are refilled into the channel store, for channels with no live
- * state.
+ * What `restoreFromCheckpoint` rebuilt. `fromSnapshot` is false for a ledger-only
+ * restore, whose layer state was never recovered — the harness must then let layer
+ * `init` hydrate normally instead of keeping restored state.
  *
- * `opts` carries the host's own context wiring (broadcaster, parent, state,
- * layer overrides) into the rebuilt context. A snapshot cannot round-trip live
- * objects, so a host that decorated the original context has to hand the same
- * decoration back here — otherwise the resumed run gets a bare context and
- * whatever depended on that wiring stops working silently. Snapshot-owned
- * fields always win: identity, item log, and cwd come from the persisted
- * record, never from `opts`.
+ * @internal
+ */
+export interface RestoredExecution {
+    ctx: Context;
+    fromSnapshot: boolean;
+}
+/**
+ * Rebuild a `Context` for `executionId` from what a previous run recorded: the
+ * checkpoint snapshot and the step-completion ledger. Either is enough. Returns
+ * `null` only when neither exists, so the caller starts a fresh execution.
+ *
+ * - With a snapshot, the item log, layer state, channel state, cwd, and thread/resource
+ *   ids come from it. Layer state is replayed into `layerStateStore` under the original
+ *   id; channel values and queued items refill the channel store for channels with no
+ *   live state.
+ * - Without one, the context starts like `createContext(opts)` would — empty item
+ *   log, no layer or channel state, the harness's root cwd, fresh thread id — and only
+ *   its identity and ledger are recovered. Recorded steps replay; the rest run fresh.
+ *
+ * `opts` carries the host's own context wiring (broadcaster, parent, state, layer
+ * overrides). A snapshot cannot round-trip live objects, so a host that decorated
+ * the original context has to hand the same decoration back here. Snapshot-owned
+ * fields always win: identity, item log, and cwd come from the persisted record,
+ * never from `opts`.
  *
- * Preserves the original executionId on the returned context via
- * `Object.defineProperty` — adapter correlation across crash/restart
- * requires a stable id.
+ * A snapshot whose schema version is unknown throws
+ * `NoeticConfigError(CHECKPOINT_SCHEMA_MISMATCH)` from the store; the ledger is not
+ * used as a fallback, because resuming onto it would drop state the snapshot held.
  *
  * @internal
  */
-export declare function restoreFromCheckpoint(h: CheckpointHarnessHandle, executionId: string, opts?: RestoreCheckpointOptions): Promise<Context | null>;
+export declare function restoreFromCheckpoint(h: CheckpointHarnessHandle, executionId: string, opts?: RestoreCheckpointOptions): Promise<RestoredExecution | null>;
 /**
  * Discard every recovery record for one execution: the snapshot and the completion
  * ledger. Clearing the snapshot alone would strand the ledger's shards under

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

@@ -59,28 +59,28 @@ export async function captureCheckpoint(h, ctx) {
         console.warn(`AgentHarness.checkpoint: failed to persist snapshot for execution "${ctx.id}":`, err);
     }
 }
-//#endregion
-//#region restoreFromCheckpoint
 /**
- * Rebuild a `Context` from a previously-persisted snapshot. Returns
- * `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. Channel values and queued
- * items are refilled into the channel store, for channels with no live
- * state.
+ * Rebuild a `Context` for `executionId` from what a previous run recorded: the
+ * checkpoint snapshot and the step-completion ledger. Either is enough. Returns
+ * `null` only when neither exists, so the caller starts a fresh execution.
+ *
+ * - With a snapshot, the item log, layer state, channel state, cwd, and thread/resource
+ *   ids come from it. Layer state is replayed into `layerStateStore` under the original
+ *   id; channel values and queued items refill the channel store for channels with no
+ *   live state.
+ * - Without one, the context starts like `createContext(opts)` would — empty item
+ *   log, no layer or channel state, the harness's root cwd, fresh thread id — and only
+ *   its identity and ledger are recovered. Recorded steps replay; the rest run fresh.
  *
- * `opts` carries the host's own context wiring (broadcaster, parent, state,
- * layer overrides) into the rebuilt context. A snapshot cannot round-trip live
- * objects, so a host that decorated the original context has to hand the same
- * decoration back here — otherwise the resumed run gets a bare context and
- * whatever depended on that wiring stops working silently. Snapshot-owned
- * fields always win: identity, item log, and cwd come from the persisted
- * record, never from `opts`.
+ * `opts` carries the host's own context wiring (broadcaster, parent, state, layer
+ * overrides). A snapshot cannot round-trip live objects, so a host that decorated
+ * the original context has to hand the same decoration back here. Snapshot-owned
+ * fields always win: identity, item log, and cwd come from the persisted record,
+ * never from `opts`.
  *
- * Preserves the original executionId on the returned context via
- * `Object.defineProperty` — adapter correlation across crash/restart
- * requires a stable id.
+ * A snapshot whose schema version is unknown throws
+ * `NoeticConfigError(CHECKPOINT_SCHEMA_MISMATCH)` from the store; the ledger is not
+ * used as a fallback, because resuming onto it would drop state the snapshot held.
  *
  * @internal
  */
@@ -90,53 +90,69 @@ export async function restoreFromCheckpoint(h, executionId, opts) {
         return null;
     }
     const snapshot = await store.load(executionId);
-    if (!snapshot) {
+    const recovered = await h.stepLedgerStore?.load(executionId);
+    if (!snapshot && (!recovered || recovered.entries.size === 0)) {
         return null;
     }
+    const ctx = snapshot ? contextFromSnapshot(h, snapshot, opts) : h.createContext(opts);
+    if (ctx instanceof ContextImpl) {
+        adoptExecution({
+            h,
+            ctx,
+            executionId,
+            recovered,
+        });
+    }
+    return {
+        ctx,
+        fromSnapshot: snapshot !== null,
+    };
+}
+/** Replay a snapshot's layer and channel state and build the context its item log and cwd describe. */
+function contextFromSnapshot(h, snapshot, opts) {
     for (const [layerId, state] of Object.entries(snapshot.layers)) {
-        h.layerStateStore.set(executionId, layerId, state);
+        h.layerStateStore.set(snapshot.executionId, layerId, state);
     }
-    h.channelStore.restore(executionId, snapshot.channels ?? []);
-    const items = h.itemSchemas.parseMany(snapshot.itemLog.items);
-    const cwdInit = snapshot.cwd?.current ?? undefined;
+    h.channelStore.restore(snapshot.executionId, snapshot.channels ?? []);
     /* Caller wiring first, snapshot second: a host may legitimately swap the context
      * layers or hang the restored execution under a new parent, but it must never be
      * able to override the identity/history the snapshot is the record of. */
-    const ctx = h.createContext({
+    return h.createContext({
         ...opts,
-        items,
+        items: h.itemSchemas.parseMany(snapshot.itemLog.items),
         threadId: snapshot.threadId,
         resourceId: snapshot.resourceId,
-        cwdInit,
+        cwdInit: snapshot.cwd?.current ?? undefined,
     });
-    if (ctx instanceof ContextImpl) {
-        Object.defineProperty(ctx, 'id', {
-            value: executionId,
-            configurable: false,
-            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,
-                    retention: h.stepLedgerRetention,
-                }),
-                configurable: false,
-                writable: false,
-                enumerable: true,
-            });
-        }
+}
+/**
+ * Give `ctx` the original execution id and the ledger recorded under it.
+ * `createContext` already built a fresh ledger keyed to a throwaway id; without the
+ * recovered one `execute()` would replay nothing and re-run the whole tree. Both are
+ * assigned with `defineProperty` to keep `createContext`'s public options free of
+ * resume-only fields — adapter correlation across a restart needs the stable id.
+ */
+function adoptExecution({ h, ctx, executionId, recovered, }) {
+    Object.defineProperty(ctx, 'id', {
+        value: executionId,
+        configurable: false,
+        writable: false,
+        enumerable: true,
+    });
+    if (!h.stepLedgerStore || !recovered) {
+        return;
     }
-    return ctx;
+    Object.defineProperty(ctx, 'ledger', {
+        value: new StepLedger({
+            executionId,
+            store: h.stepLedgerStore,
+            recovered,
+            retention: h.stepLedgerRetention,
+        }),
+        configurable: false,
+        writable: false,
+        enumerable: true,
+    });
 }
 //#endregion
 //#region clearCheckpoint

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

@@ -2,7 +2,7 @@
  * 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
+ * about which ones finished, and a finished step leaves no trace once `leaveStep` drops
  * 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 a `callModel` step
  * re-run to catch up produces a different one than the rest of the run already saw.

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

@@ -2,7 +2,7 @@
  * 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
+ * about which ones finished, and a finished step leaves no trace once `leaveStep` drops
  * 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 a `callModel` step
  * re-run to catch up produces a different one than the rest of the run already saw.

package/dist/schemas/workflow.d.ts

@@ -3,5 +3,5 @@
  * consumers can validate workflow documents without importing core.
  * This barrel keeps core's public and intra-core import paths unchanged.
  */
-export type { AcpAgentWorkflowNode, CallModelWorkflowNode, ConditionalRoute, ConditionalWorkflowNode, DecideWorkflowNode, InParallelWorkflowNode, InvokeToolWorkflowNode, LoopWorkflowNode, OutputCodecRef, RouteSwitchWorkflowNode, RunCodeWorkflowNode, ScheduleWorkflowNode, SequenceWorkflowNode, SpawnWorkflowNode, SubflowWorkflowNode, UntilPredicate, WithContextWorkflowNode, WorkflowDocument, WorkflowGraph, WorkflowNode, } from '@noetic-tools/types';
+export type { AcpAgentWorkflowNode, CallModelWorkflowNode, ConditionalRoute, ConditionalWorkflowNode, DecideWorkflowNode, InParallelWorkflowNode, InvokeToolWorkflowNode, LoopWorkflowNode, OutputCodecRef, RouteSwitchWorkflowNode, RunCodeWorkflowNode, ScheduleWorkflowNode, SequenceWorkflowNode, SpawnWorkflowNode, SubflowWorkflowNode, UntilPredicate, WithContextWorkflowNode, WorkflowDocument, WorkflowGraph, WorkflowNode, WorkflowReplayKey, } from '@noetic-tools/types';
 export { MergeStrategy, MergeStrategySchema, UntilPredicateSchema, validateWorkflow, WorkflowDocumentSchema, WorkflowNodeSchema, walkWorkflow, workflowDepth, workflowGraph, } from '@noetic-tools/types';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/core",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "type": "module",
   "description": "Step primitives, interpreter, runtime, and context layer contract for Noetic agents.",
   "license": "Apache-2.0",
@@ -68,8 +68,8 @@
     }
   },
   "dependencies": {
-    "@noetic-tools/context": "^1.5.0",
-    "@noetic-tools/types": "^3.6.0",
+    "@noetic-tools/context": "^1.6.0",
+    "@noetic-tools/types": "^3.7.0",
     "@openrouter/agent": "^0.11.0",
     "@openrouter/sdk": "1.4.25",
     "zod": "^4.0.0"