@orkestrel/workflow 0.0.8 → 0.0.10

package/dist/src/core/index.d.cts

@@ -92,6 +92,27 @@ export declare function buildWorkflowContext(node: WorkflowContext): WorkflowCon
  */
 export declare function canTransitionTask(from: TaskStatus, to: TaskStatus): boolean;
 
+/**
+ * Capture every top-level {@link WorkflowOptions} value exactly once into an owned plain bag.
+ *
+ * @remarks
+ * Direct property reads preserve inherited and non-enumerable option values while preventing
+ * accessor-backed caller bags from shifting policy, handlers, hooks, or nested options between
+ * construction stages. Nested bags and the functions registry retain their original identities so
+ * entity constructors can snapshot keyed child options and live additions can resolve against the
+ * same registry.
+ *
+ * @param options - The caller-owned workflow construction options
+ * @returns An owned top-level options bag containing the captured values
+ *
+ * @example
+ * ```ts
+ * const captured = captureWorkflowOptions(options)
+ * const workflow = createWorkflow(definition, captured)
+ * ```
+ */
+export declare function captureWorkflowOptions(options?: WorkflowOptions): WorkflowOptions;
+
 /**
  * Validate and clone one complete task activity frame.
  *
@@ -113,9 +134,11 @@ export declare function cloneTaskActivity(input: unknown, updated?: number): Tas
  * Validate and own a workflow snapshot before live construction.
  *
  * @param input - The hostile snapshot boundary
+ * @param id - The optional storage key the owned snapshot must match
  * @returns A deeply owned frozen snapshot
+ * @throws {WorkflowError} With `RESTORE` when the snapshot is invalid or does not match `id`
  */
-export declare function cloneWorkflowSnapshot(input: unknown): WorkflowSnapshot;
+export declare function cloneWorkflowSnapshot(input: unknown, id?: string): WorkflowSnapshot;
 
 /**
  * Flatten a nested list of per-phase {@link TaskResult} lists into one positional list
@@ -242,7 +265,7 @@ export declare interface ControllerInterface<TInput, TResult> {
  * @remarks
  * Builds a one-table database (`snapshots`, keyed by `id`) over the supplied driver, the snapshot
  * held as ONE OPAQUE JSON COLUMN — the column map is `{ id; snapshot }` where `snapshot` is a
- * `rawShape` (a JSON blob), exactly as {@link createDatabaseQueueStore} stores its `input`. The
+ * `rawShape` (a JSON blob), exactly as `createDatabaseQueueStore` stores its `input`. The
  * snapshot is already a COMPLETE, self-contained, pure-JSON payload, so storing it whole is lossless
  * AND keeps the row type FLAT — a structured multi-column snapshot table would force the contract to
  * `Infer` the deeply-nested snapshot shape (workflow → phases → tasks → results) and trip TS2589;
@@ -258,7 +281,8 @@ export declare interface ControllerInterface<TInput, TResult> {
  *
  * @example
  * ```ts
- * import { createDatabaseWorkflowStore, createMemoryDriver, createWorkflow, restoreWorkflow } from '@src/core'
+ * import { createMemoryDriver } from '@orkestrel/database'
+ * import { createDatabaseWorkflowStore, createWorkflow, restoreWorkflow } from '@orkestrel/workflow'
  *
  * const store = createDatabaseWorkflowStore(createMemoryDriver()) // a durable driver swaps in here
  * const workflow = createWorkflow(definition)
@@ -285,7 +309,7 @@ export declare function createDeferred<T>(): DeferredInterface<T>;
  *
  * @remarks
  * The snapshot analogue of the server package's `createMemorySessionStore`
- * (and the {@link createMemoryQueueStore} family), but LEANER — there is no idle-TTL, so no
+ * (and the `createMemoryQueueStore` family), but LEANER — there is no idle-TTL, so no
  * options bag (AGENTS §21 minimal): a persisted run-state lives until an explicit `delete`. This is
  * the zero-plumbing DEFAULT (a plain `Map`); its driver-pluggable twin is
  * {@link createDatabaseWorkflowStore} (the snapshot as one opaque JSON column over a `databases`
@@ -297,7 +321,7 @@ export declare function createDeferred<T>(): DeferredInterface<T>;
  *
  * @example
  * ```ts
- * import { createMemoryWorkflowStore, createWorkflow, restoreWorkflow } from '@src/core'
+ * import { createMemoryWorkflowStore, createWorkflow, restoreWorkflow } from '@orkestrel/workflow'
  *
  * const store = createMemoryWorkflowStore()
  * const workflow = createWorkflow(definition)
@@ -337,7 +361,7 @@ export declare function createMemoryWorkflowStore(): WorkflowStoreInterface;
  *
  * @example
  * ```ts
- * import { createRunner } from '@src/core'
+ * import { createRunner } from '@orkestrel/workflow'
  *
  * // A handler that fans out one sibling per declared unit, then returns its own value.
  * const runner = createRunner<number, number>({
@@ -363,7 +387,8 @@ export declare function createRunner<TInput, TResult>(options: RunnerOptions<TIn
  * `yield()` gives the host a turn via a zero-delay macrotask (so pending I/O,
  * timers, and rendering actually run — a microtask would not); `delay(ms)` resumes
  * after at least `ms`. Pass `options.signal` to make a pending yield/delay reject
- * with the signal's `reason` on abort (with full timer/listener cleanup).
+ * with the signal's exact `reason`; the shared owned-signal lifecycle clears the timer
+ * without invoking caller-owned listener methods.
  * `options.priority` is accepted for contract compliance but treated uniformly by
  * this default — environment backends honour it.
  *
@@ -371,7 +396,8 @@ export declare function createRunner<TInput, TResult>(options: RunnerOptions<TIn
  *
  * @example
  * ```ts
- * import { createAbort, createScheduler } from '@src/core'
+ * import { createAbort } from '@orkestrel/abort'
+ * import { createScheduler } from '@orkestrel/workflow'
  *
  * const abort = createAbort()
  * const scheduler = createScheduler()
@@ -385,7 +411,7 @@ export declare function createRunner<TInput, TResult>(options: RunnerOptions<TIn
  *
  * @example
  * ```ts
- * import { createScheduler } from '@src/core'
+ * import { createScheduler } from '@orkestrel/workflow'
  *
  * // A backoff: wait a growing interval between retries.
  * const scheduler = createScheduler()
@@ -424,7 +450,7 @@ export declare function createScheduler(): SchedulerInterface;
  *
  * @example
  * ```ts
- * import { createWorkflow } from '@src/core'
+ * import { createWorkflow } from '@orkestrel/workflow'
  *
  * const workflow = createWorkflow(definition, { on: { complete: () => done() } })
  * const phase = workflow.phase('phase-build')
@@ -452,7 +478,7 @@ export declare function createWorkflow(definition: WorkflowDefinition, options?:
  *
  * @example
  * ```ts
- * import { createWorkflowContract } from '@src/core'
+ * import { createWorkflowContract } from '@orkestrel/workflow'
  *
  * const contract = createWorkflowContract()
  * const definition = contract.generate()       // a valid WorkflowDefinition
@@ -482,7 +508,7 @@ export declare function createWorkflowContract(): ContractInterface<WorkflowDefi
  *
  * @example
  * ```ts
- * import { createMemoryWorkflowStore, createWorkflowManager } from '@src/core'
+ * import { createMemoryWorkflowStore, createWorkflowManager } from '@orkestrel/workflow'
  *
  * const manager = createWorkflowManager({
  * 	store: createMemoryWorkflowStore(),
@@ -527,7 +553,7 @@ export declare function createWorkflowManager(options?: WorkflowManagerOptions):
  *
  * @example
  * ```ts
- * import { createWorkflowRunner } from '@src/core'
+ * import { createWorkflowRunner } from '@orkestrel/workflow'
  *
  * const runner = createWorkflowRunner()
  * const definition = { id: 'w', name: 'W', phases: [{ id: 'p', name: 'P', tasks: [
@@ -569,7 +595,8 @@ export declare function createWorkflowRunner(options?: WorkflowRunnerOptions): W
  *   the row `{ id: snapshot.id, snapshot }`.
  * - **`get(id)` resolves the stored snapshot for an id**, narrowing the opaque JSON column back to
  *   a {@link WorkflowSnapshot} ({@link import('../helpers.js').isWorkflowSnapshot} — the AGENTS §14
- *   boundary narrow for an untrusted storage read), or `undefined` if none is stored.
+ *   boundary narrow for an untrusted storage read), or `undefined` if none is stored. A present
+ *   snapshot whose own id differs from the requested key rejects with normalized `RESTORE` evidence.
  * - **`delete(id)` drops a snapshot by id**; an absent id is a no-op (no throw).
  *
  * UNLIKE the server package's `SessionStoreInterface` there is NO
@@ -580,7 +607,8 @@ export declare function createWorkflowRunner(options?: WorkflowRunnerOptions): W
  *
  * @example
  * ```ts
- * import { createDatabaseWorkflowStore, createMemoryDriver, createWorkflow, restoreWorkflow } from '@src/core'
+ * import { createMemoryDriver } from '@orkestrel/database'
+ * import { createDatabaseWorkflowStore, createWorkflow, restoreWorkflow } from '@orkestrel/workflow'
  *
  * const store = createDatabaseWorkflowStore(createMemoryDriver()) // a durable driver swaps in here
  * const workflow = createWorkflow(definition)
@@ -599,7 +627,7 @@ export declare class DatabaseWorkflowStore implements WorkflowStoreInterface {
      *   {@link WorkflowSnapshotRow} `{ id; snapshot }` shape (the snapshot one opaque JSON column)
      */
     constructor(table: TableInterface<WorkflowSnapshotRow>);
-    /** Resolve the persisted snapshot for `id`, narrowing the opaque JSON column back to a `WorkflowSnapshot`. */
+    /** Resolve and key-check the snapshot for `id`, narrowing the opaque column to `WorkflowSnapshot`. */
     get(id: string): Promise<WorkflowSnapshot | undefined>;
     /** Insert or replace under the snapshot's OWN `id` (no separate id param) — the row is `{ id, snapshot }`. */
     set(snapshot: WorkflowSnapshot): Promise<void>;
@@ -799,8 +827,19 @@ export declare function failure<E>(error: E): Failure<E>;
  */
 export declare function findFailure(results: readonly TaskResult[]): TaskResult | undefined;
 
-/** Test that every present behavior reference resolves before dispatch. */
-export declare function hasWorkflowHandlers(snapshot: WorkflowSnapshot, functions: WorkflowFunctions | undefined): boolean;
+/**
+ * Test that every named task has a callable runtime handler before dispatch.
+ *
+ * @remarks
+ * A snapshot lookup reads each unique `run` binding at most once from `functions`. A live workflow
+ * validates its tasks' already-resolved handlers without consulting the retained registry again.
+ *
+ * @param workflow - The persisted snapshot or constructed live workflow to validate
+ * @returns Whether every named task resolves to a callable handler
+ */
+export declare function hasWorkflowHandlers(workflow: WorkflowInterface): boolean;
+
+export declare function hasWorkflowHandlers(workflow: WorkflowSnapshot, functions: WorkflowFunctions | undefined): boolean;
 
 /**
  * Insert one `[key, value]` entry at a positional index into a readonly entries array —
@@ -945,7 +984,7 @@ export declare const MAX_TIMER_MS = 2147483647;
  *
  * @example
  * ```ts
- * import { createMemoryWorkflowStore, createWorkflow, restoreWorkflow } from '@src/core'
+ * import { createMemoryWorkflowStore, createWorkflow, restoreWorkflow } from '@orkestrel/workflow'
  *
  * const store = createMemoryWorkflowStore()
  * const workflow = createWorkflow(definition)
@@ -1017,9 +1056,9 @@ export declare function parkSignal(signal: AbortSignal): Promise<void>;
  *
  * @remarks
  * - **Derived status.** `status` is `#override` when one is in force, else
- *   {@link derivePhaseStatus} over the live tasks' statuses. {@link #recompute} (passed to
+ *   {@link derivePhaseStatus} over the live tasks' statuses. `#recompute` (passed to
  *   each child {@link Task}) re-derives on every child transition; a CHANGE emits the matching
- *   event AND escalates to the workflow ({@link #escalate}, the upward step of the cascade).
+ *   event AND escalates to the workflow (`#escalate`, the upward step of the cascade).
  * - **Override (AGENTS §10).** `skip` / `stop` FORCE the phase's status (e.g. skipping a whole
  *   phase), overriding the derived value; the override is PERSISTED in the snapshot's own
  *   `override` field and restored DIRECTLY (no divergence guess), so a forced phase round-trips.
@@ -1050,10 +1089,12 @@ export declare function parkSignal(signal: AbortSignal): Promise<void>;
  *   construction path {@link #append} uses at build time, so a live mint and a restored/built
  *   task are wired IDENTICALLY. At construction, the workflow-level
  *   {@link import('../types.js').WorkflowFunctions} registry (threaded from
- *   {@link import('../types.js').WorkflowOptions.functions}) resolves each task's `run` name into
- *   its runtime {@link import('../types.js').TaskInterface.handler} ONCE; a `run` that is omitted
- *   or unregistered resolves to no handler; only an omitted `run` is a no-op, while an
- *   unresolved present name makes the containing tree non-drivable.
+ *   {@link import('../types.js').WorkflowOptions.functions}) resolves every unique initial `run`
+ *   name ONCE before any task is built; siblings sharing a name receive the exact same captured
+ *   runtime {@link import('../types.js').TaskInterface.handler}. A later live {@link add} reads
+ *   that name once from the retained registry at its own mint moment. An omitted or unregistered
+ *   `run` resolves to no handler; only omission is a no-op, while an unresolved present name makes
+ *   the containing tree non-drivable.
  * - **Runtime lifecycle (AGENTS §10).** `pause` / `resume` / `wait` mirror the workflow's own
  *   quartet, scoped to this phase — a driving
  *   {@link import('../types.js').WorkflowRunnerInterface.execute} gates a task's own
@@ -1649,6 +1690,11 @@ export declare const phaseUpdateShape: ObjectShape<{
 /**
  * Rebuild an interrupted workflow at its remaining retry budget.
  *
+ * @remarks
+ * Each phase captures every unique initial `run` binding once before constructing tasks. Recovery
+ * validates those live tasks' captured callable handlers without rereading the registry, while the
+ * retained registry identity remains available to resolve future live additions at their mint time.
+ *
  * @param snapshot - The hostile persisted snapshot
  * @param options - Runtime handlers and entity options
  * @returns A recoverable live workflow
@@ -1699,7 +1745,7 @@ export declare function resolveTaskSilence(value: number | undefined, fallback:
  *
  * @example
  * ```ts
- * import { restoreWorkflow } from '@src/core'
+ * import { restoreWorkflow } from '@orkestrel/workflow'
  *
  * const restored = restoreWorkflow(workflow.snapshot()) // bail comes from the snapshot
  * restored.status === workflow.status // true
@@ -1794,7 +1840,7 @@ export declare class Runner<TInput, TResult> implements RunnerInterface<TInput,
      */
     spawn(input: TInput): Promise<TResult> | undefined;
     execute(inputs: readonly TInput[]): Promise<readonly TResult[]>;
-    abort(reason?: unknown): void;
+    abort(reason?: unknown): Promise<void>;
     /**
      * Suspend dispatch (AGENTS §10 — resumable): delegates to the backing queue's own
      * `pause`, which holds the NEXT dispatch while any in-flight unit finishes.
@@ -1824,8 +1870,8 @@ export declare class Runner<TInput, TResult> implements RunnerInterface<TInput,
      * gate, no recorded failure, no fail-fast trip) rather than a genuine failure — a
      * dispatched unit's rejection while stopping is still a real failure. Idempotent.
      */
-    stop(): void;
-    destroy(): void;
+    stop(): Promise<void>;
+    destroy(): Promise<void>;
 }
 
 /**
@@ -1957,8 +2003,9 @@ export declare interface RunnerInterface<TInput, TResult> {
      * `execute` reject.
      *
      * @param reason - An optional cancellation reason propagated to every unit's signal
+     * @returns The stable cleanup barrier
      */
-    abort(reason?: unknown): void;
+    abort(reason?: unknown): Promise<void>;
     /**
      * Suspend dispatch (AGENTS §10 — resumable): the backing queue holds the NEXT dispatch
      * while any in-flight unit finishes; idempotent.
@@ -1995,10 +2042,15 @@ export declare interface RunnerInterface<TInput, TResult> {
      * runner.stop() // the in-flight unit finishes; the rest are gracefully dropped
      * await results // resolves with whatever settled — never rejects
      * ```
+     * @returns The stable graceful-cleanup barrier
      */
-    stop(): void;
-    /** Tear the runner down — `abort` plus stop the backing queue; idempotent. */
-    destroy(): void;
+    stop(): Promise<void>;
+    /**
+     * Tear the runner down, awaiting backing-queue cleanup before destroying the emitter last.
+     *
+     * @returns The stable teardown barrier
+     */
+    destroy(): Promise<void>;
 }
 
 /**
@@ -2008,11 +2060,11 @@ export declare interface RunnerInterface<TInput, TResult> {
  * - `handler` — runs each unit's work against its {@link ControllerInterface};
  *   rejecting fails the unit (and, after retries are exhausted, fails the run).
  * - `concurrency` — the maximum units in flight at once; defaults to `1` (ordered,
- *   one-at-a-time). Floored at `1`.
+ *   one-at-a-time) and must be a positive safe integer.
  * - `retries` — the default extra attempts per unit on failure (or a per-attempt
- *   timeout); defaults to `0`.
- * - `timeout` — the per-attempt deadline in milliseconds; defaults to none (a
- *   non-positive value means no deadline).
+ *   timeout); defaults to `0` and must be a nonnegative safe integer.
+ * - `timeout` — the per-attempt deadline in milliseconds; defaults to `0`, must be
+ *   an integer in `0..2_147_483_647`, and `0` disables the deadline.
  * - `entries` — per-entry `retries` / `timeout` overrides, resolved from each
  *   input; falls back to the runner-level `retries` / `timeout` defaults.
  * - `on` — the reserved {@link EmitterHooks} key (§8): initial listeners for the runner's
@@ -2048,6 +2100,25 @@ export declare interface RunnerUnit<TInput> {
     readonly input: TInput;
 }
 
+/**
+ * Schedule one cancellable host operation behind an owned settlement signal.
+ *
+ * @remarks
+ * The completion and failure paths each own an {@link AbortController}; their native composite is
+ * linked to the optional caller signal before `start` can arm host work. Scheduler backends attach
+ * only to that safe composite, so caller mutation of `addEventListener` or `removeEventListener`
+ * cannot strand the operation. The first completion resolves, the first host failure rejects with
+ * its exact value, and caller abort rejects with its exact linked reason. Caller abort and host
+ * failure cancel an armed handle; synchronous settlement also cancels the handle immediately after
+ * `start` returns it. Cancellation is secondary cleanup: if its closure throws, the already-winning
+ * completion, exact host failure, or exact caller reason still settles without escape or replacement.
+ *
+ * @param start - Arm host work and return its cancellation closure
+ * @param signal - Optional caller cancellation signal
+ * @returns A promise settled exactly once by completion, host failure, or caller abort
+ */
+export declare function scheduleHost(start: (complete: () => void, failure: (error: unknown) => void) => () => void, signal?: AbortSignal): Promise<void>;
+
 /**
  * The safe cross-environment cooperative-yield default — a {@link SchedulerInterface}
  * built on `setTimeout` / `clearTimeout` alone, so it runs unchanged in both the
@@ -2064,11 +2135,10 @@ export declare interface RunnerUnit<TInput> {
  *   regains control, so it would not actually let pending I/O, timers, or
  *   rendering run — it only defers within the current task. A zero-delay timer is
  *   the correct cross-environment "give the host a turn".
- * - **Abort-aware.** A pending `yield` / `delay` rejects with `signal.reason` when
- *   the signal aborts (the standard `AbortSignal` convention). An already-aborted
- *   signal rejects immediately without arming a timer. Either settle path clears
- *   the timer and removes the abort listener — no leaked timer, no leaked
- *   listener, and no double-settle.
+ * - **Abort-aware.** A pending `yield` / `delay` rejects with `signal.reason` exactly.
+ *   {@link scheduleHost} links an owned settlement composite to the caller before arming
+ *   the timer, so pre-abort schedules nothing, caller signal method mutation is harmless,
+ *   cancellation clears the handle, and native first-settlement wins exactly once.
  * - **Priority is accepted but uniform.** `options.priority` is part of the
  *   contract, but a `setTimeout`-based default cannot act on urgency, so it treats
  *   every priority the same. Environment backends honour it.
@@ -2956,11 +3026,11 @@ export declare type UnitOutcome<TResult> = {
  * - **Construction.** Built from a {@link WorkflowSnapshot} (the unified input —
  *   {@link import('./factories.js').createWorkflow} seeds an initial snapshot from a
  *   {@link import('./types.js').WorkflowDefinition}, {@link import('./factories.js').restoreWorkflow}
- *   passes a persisted one). Each child {@link Phase} is wired to escalate to {@link #recompute}.
+ *   passes a persisted one). Each child {@link Phase} is wired to escalate to `#recompute`.
  * - **Derived status.** `status` is `#override` when forced, else
  *   {@link deriveWorkflowStatus} over the live phases' statuses feeding `bail`. `failed` is
  *   reachable ONLY under `bail: true` (a single failed task halts the workflow); under
- *   `bail: false` a failed phase folds into `completed`. {@link #recompute} diffs on each phase
+ *   `bail: false` a failed phase folds into `completed`. `#recompute` diffs on each phase
  *   change; a CHANGE emits.
  * - **Override (AGENTS §10).** `skip` / `stop` FORCE the status; an executed task-free pending tree
  *   may also be force-completed vacuously. The override is PERSISTED in the snapshot's own
@@ -3414,12 +3484,11 @@ export declare interface WorkflowInterface {
  *   `functions` registry in) and stores it under `definition.id` — an already-present id
  *   OVERWRITES (last write wins). `count` is the map size, `workflow(id)` looks one up,
  *   `workflows()` lists them in insertion order.
- * - **Durable open / save.** `open(id)` returns an already-registered workflow directly; on a
- *   registry MISS with a `store` set it rehydrates through {@link restoreWorkflow} (flowing the
- *   manager's `functions` registry in so the rehydrated tree is RUNNABLE), registers it, and
- *   returns it — lenient (`undefined`) with no store or a store miss. `save(id)` persists a
- *   registered workflow's `snapshot()` to the `store` — lenient (`false`) with no store or an
- *   unknown id.
+ * - **Durable open / save.** `open(id)` returns an already-registered workflow directly; same-id
+ *   misses share one hydration. A concurrent `add` wins, while `remove` / `clear` invalidate
+ *   earlier reads; wrong-key payloads reject with `RESTORE`. `save(id)` captures a registered
+ *   workflow's snapshot at invocation and serializes same-id writes without coupling other ids.
+ *   Both remain lenient without a store or registered id.
  * - **Removal.** `remove` drops one by id, or a batch (§9.2, array overload FIRST) — `true` when
  *   any was removed. `clear` empties the registry.
  * - **No active pointer.** Unlike its `ConversationManager` / `WorkspaceManager` twins, there is
@@ -3469,10 +3538,17 @@ export declare class WorkflowManager implements WorkflowManagerInterface {
  *   `workflows()` lists them in insertion order.
  * - **Durable open / save (the optional `store` seam).** When a {@link WorkflowStoreInterface}
  *   is supplied (the `store` option), `open(id)` resolves an already-registered workflow
- *   directly (no store hit); on a registry MISS it HYDRATES one from `store.get(id)` through
+ *   directly (no store hit); same-id registry misses share one in-flight hydration. On a MISS
+ *   it HYDRATES one from `store.get(id)` through
  *   {@link import('./factories.js').restoreWorkflow} — flowing this manager's `functions`
- *   registry in so the rehydrated tree is RUNNABLE — registers it, and returns it. `save(id)`
- *   PERSISTS a registered workflow's {@link WorkflowInterface.snapshot} to the store. Both are
+ *   registry in so the rehydrated tree is RUNNABLE — registers it, and returns it. Registry
+ *   mutation wins over an earlier pending hydration: `add` supplies the live result, while
+ *   `remove` (even for an absent id) and `clear` invalidate the earlier read. Missed and failed
+ *   reads leave no stale in-flight entry, and a payload whose own id differs from the requested
+ *   key rejects with `RESTORE` instead of registering under either id. `save(id)` captures a
+ *   registered workflow's {@link WorkflowInterface.snapshot} at invocation, then PERSISTS it.
+ *   Same-id writes run serially in invocation order; different ids remain independent, and an
+ *   earlier rejection reaches its caller without preventing a later queued write. Both are
  *   LENIENT without a store — `open` resolves only registered ids, `save` is a no-op
  *   (`false`) — never a throw. The EXACT analogue of
  *   `ConversationManagerInterface.open` / `.save` and `WorkspaceManagerInterface.open` /
@@ -3486,7 +3562,7 @@ export declare class WorkflowManager implements WorkflowManagerInterface {
  *
  * @example
  * ```ts
- * import { createWorkflowManager } from '@src/core'
+ * import { createWorkflowManager } from '@orkestrel/workflow'
  *
  * const manager = createWorkflowManager({
  * 	functions: { compile: async (controller) => `built ${controller.task.id}` },
@@ -3520,11 +3596,17 @@ export declare interface WorkflowManagerInterface {
      *
      * @remarks
      * - If `id` is ALREADY registered, it is returned directly — no store hit.
-     * - Else if a `store` is set, `store.get(id)` is awaited; on a HIT the snapshot is
+     * - Same-id registry misses share one in-flight `store.get(id)` and resolve to the same live
+     *   object. On a HIT the snapshot is
      *   rehydrated into a fresh {@link WorkflowInterface} via
      *   {@link import('./factories.js').restoreWorkflow}, flowing this manager's `functions`
      *   registry in (so the rehydrated tree carries real resolved `handler`s and can RESUME
-     *   real work), registers it, and returns it.
+     *   real work), registers it, and returns it. A payload whose own id differs from `id` rejects
+     *   with a normalized `RESTORE` error carrying the requested and payload ids.
+     * - Registry mutation after the store read starts has precedence: `add(definition)` for the
+     *   same id wins and becomes every pending caller's result; `remove(id)` invalidates that read
+     *   even when the id was absent; `clear()` invalidates every earlier read. A miss or rejection
+     *   clears the in-flight entry so a later call retries.
      * - Else (no store, or a store MISS) ⇒ `undefined` (lenient — no throw).
      *
      * @param id - The workflow id to open
@@ -3536,9 +3618,10 @@ export declare interface WorkflowManagerInterface {
      * {@link WorkflowStoreInterface} (`store`).
      *
      * @remarks
-     * Lenient: when a `store` is set AND `id` is registered, `store.set(workflow.snapshot())`
-     * is awaited and `true` is returned; otherwise (no store, OR an unknown id) it is a NO-OP
-     * returning `false` — never a throw.
+     * When a `store` is set AND `id` is registered, the snapshot is captured synchronously at
+     * invocation. Same-id `store.set` calls are serialized in invocation order; different ids are
+     * independent. A rejected write reaches that caller unchanged but does not poison a later
+     * queued write. Otherwise (no store, OR an unknown id) it is a NO-OP returning `false`.
      *
      * @param id - The id of the registered workflow to persist
      * @returns `true` when the snapshot was persisted; `false` when no store / unknown id
@@ -3716,8 +3799,9 @@ export declare interface WorkflowResult {
  * - **Composes, never re-implements.** Per-phase bounded concurrency is one
  *   {@link createRunner} per phase (the substrate {@link RunnerInterface} over the workers
  *   `Queue`); `bail` maps onto that Runner's fail-fast vs settle-all; the run-level abort /
- *   timeout / budget / entity `signal` fold through {@link createAbort} / {@link createTimeout} +
- *   `AbortSignal.any` (exactly as the agent runtime folds its bounds); pacing is the shipped
+ *   timeout / budget / entity `signal` fold through the `@orkestrel/abort` signal contract,
+ *   {@link createTimeout}, and `AbortSignal.any` (exactly as the agent runtime folds its bounds);
+ *   pacing is the shipped
  *   {@link SchedulerInterface}. The runner writes ZERO concurrency / retry / abort logic of
  *   its own — it only sequences phases, dispatches a task's own handler, and drives the live
  *   entity. The workflow layer owns per-task deadlines because timeout settlement must
@@ -4115,8 +4199,8 @@ export declare type WorkflowStatus = LifecycleStatus;
 /**
  * The durable persistence seam for a {@link WorkflowSnapshot} — three async primitives
  * (`get` / `set` / `delete`) keyed by a workflow id, the snapshot analogue of
- * the server package's `SessionStoreInterface` (and the
- * {@link QueueStoreInterface} driver-swap pattern).
+ * the server package's `SessionStoreInterface` (and the `@orkestrel/queue`
+ * `QueueStoreInterface` driver-swap pattern).
  *
  * @remarks
  * The store persists the W-a {@link WorkflowSnapshot} — the COMPLETE, self-contained,
@@ -4129,7 +4213,7 @@ export declare type WorkflowStatus = LifecycleStatus;
  *
  * Every primitive is async (a `Promise`), so a durable backend (a database round-trip) fits the
  * same shape as the memory one. The snapshot carries its OWN id, so `set` takes no separate id
- * param (mirroring {@link QueueStoreInterface.save} / the server package's
+ * param (mirroring `QueueStoreInterface.save` from `@orkestrel/queue` / the server package's
  * `SessionStoreInterface.set`, which key off the value's own
  * `id`). UNLIKE a session store there is NO idle-TTL / eviction — a persisted workflow run-state
  * lives until an explicit `delete`, never silently expiring (it is durable orchestration state,
@@ -4139,6 +4223,8 @@ export declare type WorkflowStatus = LifecycleStatus;
 export declare interface WorkflowStoreInterface {
     /**
      * Resolve the persisted snapshot for `id`, or `undefined` if none is stored.
+     * A present payload whose own `id` differs from the requested storage key is corrupt and
+     * rejects with a normalized `RESTORE` error carrying both ids.
      *
      * @param id - The workflow id to resolve (a {@link WorkflowSnapshot.id})
      * @returns The persisted snapshot, or `undefined` if absent
@@ -4146,7 +4232,7 @@ export declare interface WorkflowStoreInterface {
     get(id: string): Promise<WorkflowSnapshot | undefined>;
     /**
      * Insert or replace a snapshot under its own `snapshot.id` (no separate id param —
-     * mirroring {@link QueueStoreInterface.save}).
+     * mirroring `QueueStoreInterface.save` from `@orkestrel/queue`).
      *
      * @param snapshot - The snapshot to store (keyed by its `id`)
      */