@orkestrel/scaffold 0.0.114 → 0.0.116

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/dist/bin/main.js +137 -15
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/orchestration.md +5 -3
  4. package/dist/host/agents/platforms/windows.md +1 -0
  5. package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +4 -4
  7. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -1
  8. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +8 -2
  9. package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +1 -0
  10. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
  11. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
  12. package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
  13. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +9 -3
  14. package/dist/host/claude/agents/analyst.md +1 -1
  15. package/dist/host/claude/agents/astra.md +2 -2
  16. package/dist/host/claude/agents/builder.md +4 -4
  17. package/dist/host/claude/agents/opus.md +3 -3
  18. package/dist/host/claude/agents/orkestrel.md +5 -7
  19. package/dist/host/claude/agents/planner.md +8 -2
  20. package/dist/host/claude/rules/campaign.md +2 -1
  21. package/dist/host/claude/rules/documentation.md +1 -0
  22. package/dist/host/claude/rules/names.md +3 -1
  23. package/dist/host/claude/rules/tests.md +7 -4
  24. package/dist/host/claude/rules/writing.md +1 -0
  25. package/dist/host/claude/skills/enterprise-bootstrap/SKILL.md +1 -2
  26. package/dist/host/claude/skills/orkestrel-align/SKILL.md +1 -1
  27. package/dist/host/claude/skills/orkestrel-build/SKILL.md +1 -2
  28. package/dist/host/claude/skills/orkestrel-debrief/SKILL.md +1 -2
  29. package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
  30. package/dist/host/claude/skills/orkestrel-falsify/SKILL.md +1 -1
  31. package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
  32. package/dist/host/claude/skills/orkestrel-journey/SKILL.md +1 -1
  33. package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
  34. package/dist/host/claude/skills/orkestrel-polish/SKILL.md +1 -2
  35. package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -2
  36. package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
  37. package/dist/host/codex/agents/analyst.toml +8 -5
  38. package/dist/host/codex/agents/astra.toml +4 -5
  39. package/dist/host/codex/agents/builder.toml +5 -5
  40. package/dist/host/codex/agents/opus.toml +3 -4
  41. package/dist/host/codex/agents/orkestrel.toml +2 -1
  42. package/dist/host/codex/agents/planner.toml +8 -5
  43. package/dist/host/codex/agents/reviewer.toml +5 -4
  44. package/dist/host/guides/abort.md +17 -17
  45. package/dist/host/guides/agent.md +445 -445
  46. package/dist/host/guides/brief.md +143 -143
  47. package/dist/host/guides/browser.md +731 -731
  48. package/dist/host/guides/budget.md +39 -39
  49. package/dist/host/guides/capture.md +298 -298
  50. package/dist/host/guides/console.md +109 -109
  51. package/dist/host/guides/contract.md +335 -335
  52. package/dist/host/guides/csv.md +30 -30
  53. package/dist/host/guides/database.md +163 -163
  54. package/dist/host/guides/emitter.md +17 -17
  55. package/dist/host/guides/form.md +99 -99
  56. package/dist/host/guides/guide.md +361 -183
  57. package/dist/host/guides/html.md +49 -49
  58. package/dist/host/guides/indexeddb.md +40 -40
  59. package/dist/host/guides/interpret.md +139 -139
  60. package/dist/host/guides/lsp.md +114 -114
  61. package/dist/host/guides/markdown.md +68 -68
  62. package/dist/host/guides/mcp.md +3745 -3745
  63. package/dist/host/guides/middleware.md +170 -170
  64. package/dist/host/guides/msg.md +95 -95
  65. package/dist/host/guides/ndjson.md +8 -8
  66. package/dist/host/guides/ollama.md +56 -56
  67. package/dist/host/guides/pool.md +21 -21
  68. package/dist/host/guides/probe.md +82 -82
  69. package/dist/host/guides/process.md +99 -99
  70. package/dist/host/guides/program.md +98 -96
  71. package/dist/host/guides/qualifier.md +70 -70
  72. package/dist/host/guides/queue.md +37 -37
  73. package/dist/host/guides/rater.md +38 -38
  74. package/dist/host/guides/reason.md +308 -308
  75. package/dist/host/guides/relation.md +50 -50
  76. package/dist/host/guides/router.md +58 -58
  77. package/dist/host/guides/scaffold.md +554 -419
  78. package/dist/host/guides/sea.md +128 -128
  79. package/dist/host/guides/server.md +100 -100
  80. package/dist/host/guides/sqlite.md +28 -28
  81. package/dist/host/guides/sse.md +20 -20
  82. package/dist/host/guides/study.md +444 -444
  83. package/dist/host/guides/table.md +82 -82
  84. package/dist/host/guides/template.md +41 -41
  85. package/dist/host/guides/terminal.md +121 -121
  86. package/dist/host/guides/test.md +273 -273
  87. package/dist/host/guides/timeout.md +18 -18
  88. package/dist/host/guides/tool.md +27 -27
  89. package/dist/host/guides/toolbox.md +166 -166
  90. package/dist/host/guides/websocket.md +54 -54
  91. package/dist/host/guides/worker.md +24 -24
  92. package/dist/host/guides/workflow.md +187 -187
  93. package/dist/host/guides/workspace.md +55 -55
  94. package/dist/host/manifest.json +93 -93
  95. package/dist/host/tests/setupPolicy.ts +5 -3
  96. package/dist/src/core/index.cjs +89 -3
  97. package/dist/src/core/index.cjs.map +1 -1
  98. package/dist/src/core/index.d.cts +229 -144
  99. package/dist/src/core/index.d.ts +229 -144
  100. package/dist/src/core/index.js +87 -4
  101. package/dist/src/core/index.js.map +1 -1
  102. package/dist/src/server/index.cjs +292 -66
  103. package/dist/src/server/index.cjs.map +1 -1
  104. package/dist/src/server/index.d.cts +188 -6
  105. package/dist/src/server/index.d.ts +188 -6
  106. package/dist/src/server/index.js +287 -69
  107. package/dist/src/server/index.js.map +1 -1
  108. package/package.json +4 -3
@@ -70,19 +70,19 @@ Why this is safe: the definition is the single source of truth. `execute` builds
70
70
 
71
71
  ### Factories
72
72
 
73
- | API | Kind | Summary |
74
- | ----------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
75
- | `createWorkflowContract` | function | Compiles the workflow definition contract — the JSON Schema, guard, parser, and seeded generator for a `WorkflowDefinition`, all derived from one shape and kept in lockstep. |
76
- | `createWorkflow` | function | Builds the live W-b entity tree from a `WorkflowDefinition` — the whole `WorkflowInterface` → `PhaseInterface` → `TaskInterface` tree, each level wired with its lineage context, its emitter, and the cascade, and every node born `pending`. |
77
- | `createWorkflowTree` | function | Builds the live entity tree one definition and one owned options bag describe — the shared construction path behind every definition-driven mint. |
78
- | `createRestoredWorkflow` | function | Builds an equivalent live W-b entity tree from a `WorkflowSnapshot` — the inverse of `WorkflowInterface.snapshot`, restoring structure + each node's status + recorded results + positional order + the persisted `#override`. |
79
- | `createRecoveredWorkflow` | function | Builds an interrupted workflow back to life at its remaining retry budget, normalizing a leaf whose attempts are exhausted into a recovery failure. |
80
- | `createMemoryWorkflowStore` | function | Creates the in-memory durable `WorkflowStoreInterface` — a process-lifetime `MemoryWorkflowStore` persisting `WorkflowSnapshot`s by workflow id, the default backend behind the W-d persistence seam. It takes no options and expires nothing: a persisted run state lives until an explicit `delete`. |
81
- | `createDatabaseWorkflowStore` | function | Creates a `DatabaseWorkflowStore` over any `DriverInterface` — the durable, driver-pluggable backing for the W-d persistence seam, the opt-in twin of `createMemoryWorkflowStore`. It holds the snapshot as one opaque JSON column, and its `driver` defaults to memory, so it works before any durable driver is passed. |
82
- | `createWorkflowRunner` | function | Creates the thin orchestrator — a `WorkflowRunnerInterface` — that executes a live W-b workflow tree by composing the shipped substrate: phases sequential, tasks concurrent, each task dispatched through its own resolved handler under the workflow's `bail` policy. The engine is pure — it carries no behavior or provider registry, and its only option is the scheduler it paces phase boundaries with. |
83
- | `createWorkflowManager` | function | Creates a `WorkflowManagerInterface` — the store-backed registry of `WorkflowInterface`s, the additive manager tier mirroring the `@orkestrel/agent` line's `createConversationManager` / `createWorkspaceManager`. The returned registry makes hydrated named work runnable when `options.functions` is supplied, and leaves it inspectable when it is not. |
84
- | `createScheduler` | function | Creates the safe cross-environment cooperative-yield default — a `SchedulerInterface` built on `setTimeout` / `clearTimeout` alone, so it runs unchanged in both the browser and Node. |
85
- | `createRunner` | function | Creates a thin generic orchestrator that drives declared units — and any they `spawn` — through a bounded-concurrency queue, collecting their results in order and failing the run fast on the first genuine unit failure. |
73
+ | Name | Kind | Signature | Summary |
74
+ | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
75
+ | `createWorkflowContract` | function | `() => ContractInterface<WorkflowDefinition>` | Compiles the workflow definition contract — the JSON Schema, guard, parser, and seeded generator for a `WorkflowDefinition`, all derived from one shape and kept in lockstep. |
76
+ | `createWorkflow` | function | `(definition: WorkflowDefinition, options?: WorkflowOptions) => WorkflowInterface` | Builds the live W-b entity tree from a `WorkflowDefinition` — the whole `WorkflowInterface` → `PhaseInterface` → `TaskInterface` tree, each level wired with its lineage context, its emitter, and the cascade, and every node born `pending`. |
77
+ | `createWorkflowTree` | function | `(definition: WorkflowDefinition, captured: WorkflowOptions) => WorkflowInterface` | Builds the live entity tree one definition and one owned options bag describe — the shared construction path behind every definition-driven mint. |
78
+ | `createRestoredWorkflow` | function | `(snapshot: unknown, options?: WorkflowOptions) => WorkflowInterface` | Builds an equivalent live W-b entity tree from a `WorkflowSnapshot` — the inverse of `WorkflowInterface.snapshot`, restoring structure + each node's status + recorded results + positional order + the persisted `#override`. |
79
+ | `createRecoveredWorkflow` | function | `(snapshot: unknown, options?: WorkflowOptions) => WorkflowInterface` | Builds an interrupted workflow back to life at its remaining retry budget, normalizing a leaf whose attempts are exhausted into a recovery failure. |
80
+ | `createMemoryWorkflowStore` | function | `() => WorkflowStoreInterface` | Creates the in-memory durable `WorkflowStoreInterface` — a process-lifetime `MemoryWorkflowStore` persisting `WorkflowSnapshot`s by workflow id, the default backend behind the W-d persistence seam. It takes no options and expires nothing: a persisted run state lives until an explicit `delete`. |
81
+ | `createDatabaseWorkflowStore` | function | `(driver?: DriverInterface) => WorkflowStoreInterface` | Creates a `DatabaseWorkflowStore` over any `DriverInterface` — the durable, driver-pluggable backing for the W-d persistence seam, the opt-in twin of `createMemoryWorkflowStore`. It holds the snapshot as one opaque JSON column, and its `driver` defaults to memory, so it works before any durable driver is passed. |
82
+ | `createWorkflowRunner` | function | `(options?: WorkflowRunnerOptions) => WorkflowRunnerInterface` | Creates the thin orchestrator — a `WorkflowRunnerInterface` — that executes a live W-b workflow tree by composing the shipped substrate: phases sequential, tasks concurrent, each task dispatched through its own resolved handler under the workflow's `bail` policy. The engine is pure — it carries no behavior or provider registry, and its only option is the scheduler it paces phase boundaries with. |
83
+ | `createWorkflowManager` | function | `(options?: WorkflowManagerOptions) => WorkflowManagerInterface` | Creates a `WorkflowManagerInterface` — the store-backed registry of `WorkflowInterface`s, the additive manager tier mirroring the `@orkestrel/agent` line's `createConversationManager` / `createWorkspaceManager`. The returned registry makes hydrated named work runnable when `options.functions` is supplied, and leaves it inspectable when it is not. |
84
+ | `createScheduler` | function | `() => SchedulerInterface` | Creates the safe cross-environment cooperative-yield default — a `SchedulerInterface` built on `setTimeout` / `clearTimeout` alone, so it runs unchanged in both the browser and Node. |
85
+ | `createRunner` | function | `<TInput, TResult>(options: RunnerOptions<TInput, TResult>) => RunnerInterface<TInput, TResult>` | Creates a thin generic orchestrator that drives declared units — and any they `spawn` — through a bounded-concurrency queue, collecting their results in order and failing the run fast on the first genuine unit failure. |
86
86
 
87
87
  ### Copy a progress frame
88
88
 
@@ -101,12 +101,12 @@ A phase and a task are minted by their parent and reached as `PhaseInterface` an
101
101
 
102
102
  Every tier declares `description` as a required `string | undefined` member backed by a getter, so `'description' in entity` reports `true` whatever the definition declared and a reader takes absence from the value. The pure-JSON snapshot still omits the key when no prose was declared.
103
103
 
104
- | Class | Kind | Summary |
105
- | -------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
106
- | `Workflow` | class | Implements the live derived state machine (W-b) for a whole workflow — the observable root whose `LifecycleStatus` is computed from its phases under the `bail` policy and recomputed reactively as the cascade propagates up from a task transition. |
107
- | `PhaseManager` | class | Implements the lean child manager of a `Workflow`'s live phases — the phase vocabulary over one insertion-ordered `Collection`, the phase analogue of `TaskManager`. |
108
- | `TaskManager` | class | Implements the lean child manager of a `Phase`'s live tasks — the task vocabulary over one insertion-ordered `Collection`, so positional order is preserved across an interior `skip` / `remove`. |
109
- | `Collection` | class | Implements the insertion-ordered gated store both lean managers hold — entities keyed by `id`, positional order preserved across an interior `skip` or `remove`. |
104
+ | Name | Kind | Signature | Summary |
105
+ | -------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
106
+ | `Workflow` | class | `new (snapshot: WorkflowSnapshot, options?: WorkflowOptions) => WorkflowInterface` | Implements the live derived state machine (W-b) for a whole workflow — the observable root whose `LifecycleStatus` is computed from its phases under the `bail` policy and recomputed reactively as the cascade propagates up from a task transition. |
107
+ | `PhaseManager` | class | `new () => PhaseManagerInterface` | Implements the lean child manager of a `Workflow`'s live phases — the phase vocabulary over one insertion-ordered `Collection`, the phase analogue of `TaskManager`. |
108
+ | `TaskManager` | class | `new () => TaskManagerInterface` | Implements the lean child manager of a `Phase`'s live tasks — the task vocabulary over one insertion-ordered `Collection`, so positional order is preserved across an interior `skip` / `remove`. |
109
+ | `Collection` | class | `new <TEntry extends CollectionEntry<TPatch>, TPatch>(noun: string, patch: Guard<TPatch>) => CollectionInterface<TEntry, TPatch>` | Implements the insertion-ordered gated store both lean managers hold — entities keyed by `id`, positional order preserved across an interior `skip` or `remove`. |
110
110
 
111
111
  ### The positional collection
112
112
 
@@ -134,16 +134,16 @@ Beneath the engine sit the shipped primitives it composes — it re-implements n
134
134
 
135
135
  Both handles are minted per dispatch from values only the driving engine holds — the unit's abort, the attempt signal, the spawn callback — so the package keeps their classes internal and a handler receives one rather than building one.
136
136
 
137
- | Class | Kind | Summary |
138
- | --------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
139
- | `WorkflowRunner` | class | Implements the thin orchestrator that executes a live W-b workflow tree by composing the shipped substrate — phases sequential, tasks concurrent — dispatching each task through its own resolved handler under the `bail` policy. |
140
- | `WorkflowPersistence` | class | Coordinates advanced run-local snapshot persistence with one writer and one coalesced most recent obligation, normally composed through `execute({ store })` rather than built directly. |
141
- | `Runner` | class | Implements a thin generic orchestrator that drives declared units — and any they `spawn` — through a bounded-concurrency `createQueue`, collecting ordered results. |
142
- | `RunHolder` | class | Holds the active phase `RunnerInterface` for one `WorkflowRunnerInterface.execute` call, for the lifetime of that run. |
143
- | `HostSchedule` | class | Owns the cancellation and exact failure of one scheduled host operation. |
144
- | `WorkflowExecution` | class | Owns the bounds, durability, and live phase cursor of one workflow execution. |
145
- | `TaskAttempt` | class | Holds one handler outcome without moving its invocation or exception boundary. |
146
- | `PhaseExecution` | class | Owns task launch membership, attempt counts, and active claims for one phase execution. |
137
+ | Name | Kind | Signature | Summary |
138
+ | --------------------- | ----- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
139
+ | `WorkflowRunner` | class | `new (scheduler: SchedulerInterface) => WorkflowRunnerInterface` | Implements the thin orchestrator that executes a live W-b workflow tree by composing the shipped substrate — phases sequential, tasks concurrent — dispatching each task through its own resolved handler under the `bail` policy. |
140
+ | `WorkflowPersistence` | class | `new (workflow: WorkflowInterface, store: WorkflowStoreInterface) => WorkflowPersistenceInterface` | Coordinates advanced run-local snapshot persistence with one writer and one coalesced most recent obligation, normally composed through `execute({ store })` rather than built directly. |
141
+ | `Runner` | class | `new <TInput, TResult>(options: RunnerOptions<TInput, TResult>) => RunnerInterface<TInput, TResult>` | Implements a thin generic orchestrator that drives declared units — and any they `spawn` — through a bounded-concurrency `createQueue`, collecting ordered results. |
142
+ | `RunHolder` | class | `new () => RunHolderInterface` | Holds the active phase `RunnerInterface` for one `WorkflowRunnerInterface.execute` call, for the lifetime of that run. |
143
+ | `HostSchedule` | class | `new (start: HostScheduleFunction, signal?: AbortSignal) => HostScheduleInterface` | Owns the cancellation and exact failure of one scheduled host operation. |
144
+ | `WorkflowExecution` | class | `new () => WorkflowExecutionInterface` | Owns the bounds, durability, and live phase cursor of one workflow execution. |
145
+ | `TaskAttempt` | class | `new () => TaskAttemptInterface` | Holds one handler outcome without moving its invocation or exception boundary. |
146
+ | `PhaseExecution` | class | `new () => PhaseExecutionInterface` | Owns task launch membership, attempt counts, and active claims for one phase execution. |
147
147
 
148
148
  ### Scheduler (pacing)
149
149
 
@@ -159,9 +159,9 @@ await createHostSchedule((complete) => {
159
159
  }, controller.signal)
160
160
  ```
161
161
 
162
- | API | Kind | Summary |
163
- | ----------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
164
- | `Scheduler` | class | Implements the safe cross-environment cooperative-yield default — a `SchedulerInterface` built on `setTimeout` / `clearTimeout` alone, so it runs unchanged in both the browser and Node. |
162
+ | Name | Kind | Signature | Summary |
163
+ | ----------- | ----- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
164
+ | `Scheduler` | class | `new () => SchedulerInterface` | Implements the safe cross-environment cooperative-yield default — a `SchedulerInterface` built on `setTimeout` / `clearTimeout` alone, so it runs unchanged in both the browser and Node. |
165
165
 
166
166
  ### Environment backends
167
167
 
@@ -175,31 +175,31 @@ The **browser** backends ship in [`src/browser`](../src/browser), published thro
175
175
  - `FrameScheduler.yield()` resumes before the next paint through `requestAnimationFrame` (and `cancelAnimationFrame` on abort) — for work that must batch per render frame and naturally pause while the tab is hidden. `priority` is a no-op.
176
176
  - `IdleScheduler.yield()` resumes when the host is idle through `requestIdleCallback` (and `cancelIdleCallback` on abort), falling back to a `setTimeout(0)` macrotask where it is absent (Safari today) — for low-priority background work that must not contend with rendering or input. `priority` is a no-op.
177
177
 
178
- | API | Kind | Summary |
179
- | ------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
180
- | `NodeScheduler` | class | Implements the Node `SchedulerInterface` — the server-native cooperative-yield backend whose `yield` waits on `setImmediate` and whose abort rejects with the caller's own reason. A `priority` hint is accepted and does nothing, because Node has no priority primitive. |
181
- | `BrowserScheduler` | class | Implements the browser `SchedulerInterface` — the browser-native cooperative-yield backend built on the Prioritized Task Scheduling API (`scheduler.postTask`) at the mapped priority, falling back to a zero-delay macrotask where it is absent, and rejecting an aborted wait with the caller's own reason. |
182
- | `FrameScheduler` | class | Implements the frame-aligned `SchedulerInterface` — a browser cooperative-yield backend whose `yield` resumes before the next paint through `requestAnimationFrame`, rejecting an aborted wait with the caller's own reason. A `priority` hint is accepted and does nothing. |
183
- | `IdleScheduler` | class | Implements the idle-time `SchedulerInterface` — a browser cooperative-yield backend whose `yield` resumes when the host is idle through `requestIdleCallback`, falling back to a zero-delay macrotask where it is absent, and rejecting an aborted wait with the caller's own reason. A `priority` hint is accepted and does nothing. |
178
+ | Name | Kind | Signature | Summary |
179
+ | ------------------ | ----- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
180
+ | `NodeScheduler` | class | `new () => SchedulerInterface` | Implements the Node `SchedulerInterface` — the server-native cooperative-yield backend whose `yield` waits on `setImmediate` and whose abort rejects with the caller's own reason. A `priority` hint is accepted and does nothing, because Node has no priority primitive. |
181
+ | `BrowserScheduler` | class | `new () => SchedulerInterface` | Implements the browser `SchedulerInterface` — the browser-native cooperative-yield backend built on the Prioritized Task Scheduling API (`scheduler.postTask`) at the mapped priority, falling back to a zero-delay macrotask where it is absent, and rejecting an aborted wait with the caller's own reason. |
182
+ | `FrameScheduler` | class | `new () => SchedulerInterface` | Implements the frame-aligned `SchedulerInterface` — a browser cooperative-yield backend whose `yield` resumes before the next paint through `requestAnimationFrame`, rejecting an aborted wait with the caller's own reason. A `priority` hint is accepted and does nothing. |
183
+ | `IdleScheduler` | class | `new () => SchedulerInterface` | Implements the idle-time `SchedulerInterface` — a browser cooperative-yield backend whose `yield` resumes when the host is idle through `requestIdleCallback`, falling back to a zero-delay macrotask where it is absent, and rejecting an aborted wait with the caller's own reason. A `priority` hint is accepted and does nothing. |
184
184
 
185
- | API | Kind | Summary |
186
- | ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
187
- | `createNodeScheduler` | function | Creates the Node-native cooperative-yield `SchedulerInterface` — `yield()` is a `setImmediate` host-turn (the canonical Node "give the event loop a turn"), `delay(ms)` a real `setTimeout`. |
188
- | `createBrowserScheduler` | function | Creates the browser-native cooperative-yield `SchedulerInterface` — `yield()` uses the Prioritized Task Scheduling API (`scheduler.postTask`) at the requested priority when present, falling back to a `setTimeout(0)` macrotask; `delay(ms)` is a real `setTimeout`. |
189
- | `createFrameScheduler` | function | Creates the frame-aligned cooperative-yield `SchedulerInterface` — `yield()` resumes before the next paint through `requestAnimationFrame`; `delay(ms)` is a real `setTimeout`. |
190
- | `createIdleScheduler` | function | Creates the idle-time cooperative-yield `SchedulerInterface` — `yield()` resumes when the host is idle through `requestIdleCallback` when present, falling back to a `setTimeout(0)` macrotask; `delay(ms)` is a real `setTimeout`. |
185
+ | Name | Kind | Signature | Summary |
186
+ | ------------------------ | -------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
187
+ | `createNodeScheduler` | function | `() => SchedulerInterface` | Creates the Node-native cooperative-yield `SchedulerInterface` — `yield()` is a `setImmediate` host-turn (the canonical Node "give the event loop a turn"), `delay(ms)` a real `setTimeout`. |
188
+ | `createBrowserScheduler` | function | `() => SchedulerInterface` | Creates the browser-native cooperative-yield `SchedulerInterface` — `yield()` uses the Prioritized Task Scheduling API (`scheduler.postTask`) at the requested priority when present, falling back to a `setTimeout(0)` macrotask; `delay(ms)` is a real `setTimeout`. |
189
+ | `createFrameScheduler` | function | `() => SchedulerInterface` | Creates the frame-aligned cooperative-yield `SchedulerInterface` — `yield()` resumes before the next paint through `requestAnimationFrame`; `delay(ms)` is a real `setTimeout`. |
190
+ | `createIdleScheduler` | function | `() => SchedulerInterface` | Creates the idle-time cooperative-yield `SchedulerInterface` — `yield()` resumes when the host is idle through `requestIdleCallback` when present, falling back to a `setTimeout(0)` macrotask; `delay(ms)` is a real `setTimeout`. |
191
191
 
192
192
  The browser backends also publish supporting members through `@orkestrel/workflow/browser`: the `POST_TASK_PRIORITY` map `BrowserScheduler` reads to translate a portable `SchedulerPriority` into a `scheduler.postTask` priority level, and the `IdleInterface` shape of the feature-detected `requestIdleCallback` / `cancelIdleCallback` pair `IdleScheduler` narrows to (or resolves to `undefined`, falling back to a macrotask).
193
193
 
194
194
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
195
195
 
196
- | Type | Kind | Shape | Summary |
196
+ | Name | Kind | Signature | Summary |
197
197
  | --------------- | --------- | --------------------- | ---------------------------------------------------------------------------------------------------------- |
198
198
  | `IdleInterface` | interface | `{ request, cancel }` | Declares the narrowed `requestIdleCallback` / `cancelIdleCallback` pair feature-detected off `globalThis`. |
199
199
 
200
200
  A `Shape` cell holds the constant's declared type.
201
201
 
202
- | API | Kind | Shape | Summary |
202
+ | Name | Kind | Signature | Summary |
203
203
  | -------------------- | ----- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
204
204
  | `POST_TASK_PRIORITY` | const | `Readonly<Record<SchedulerPriority, string>>` | Maps each portable `SchedulerPriority` to the browser-native `postTask` priority — `user` to `'user-blocking'`, `normal` to `'user-visible'`, and `background` to `'background'`. |
205
205
 
@@ -209,25 +209,25 @@ Each backend is a standalone `implements SchedulerInterface`, so its public meth
209
209
 
210
210
  The durable persistence seam (W-d) — a dual-store convention (the `QueueStore` / `SessionStore` pattern). A `WorkflowStoreInterface` persists the pure-JSON `WorkflowSnapshot` keyed by workflow id through interchangeable backends: `MemoryWorkflowStore` (a plain `Map`, the zero-plumbing default, `createMemoryWorkflowStore`) and `DatabaseWorkflowStore` (the opt-in, driver-pluggable twin over a `databases` table, the snapshot stored as one opaque JSON column, `createDatabaseWorkflowStore`). Both live under `src/core/stores/`. The Database store's driver defaults to memory, so it also works in memory out of the box; you opt into the durable plumbing (JSON / SQLite / IndexedDB) by passing a driver — and it swaps in through the same interface, without touching the engine or the entity tree. Restore stays the shipped `createRestoredWorkflow`.
211
211
 
212
- | Class | Kind | Summary |
213
- | ----------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
214
- | `MemoryWorkflowStore` | class | Implements the in-memory `WorkflowStoreInterface` — a process-lifetime `Map` of `WorkflowSnapshot`s keyed by workflow id, the default store `createMemoryWorkflowStore` builds. It expires nothing: a persisted snapshot lives until an explicit `delete`. |
215
- | `DatabaseWorkflowStore` | class | Implements a `WorkflowStoreInterface` backed by one table of the `databases` layer — a workflow's durable run state is a row, so persistence reduces to keyed point-access (`get` / `set` / `delete`) over a `TableInterface`, the driver-pluggable twin of the plain-`Map` `MemoryWorkflowStore`. |
212
+ | Name | Kind | Signature | Summary |
213
+ | ----------------------- | ----- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
214
+ | `MemoryWorkflowStore` | class | `new () => WorkflowStoreInterface` | Implements the in-memory `WorkflowStoreInterface` — a process-lifetime `Map` of `WorkflowSnapshot`s keyed by workflow id, the default store `createMemoryWorkflowStore` builds. It expires nothing: a persisted snapshot lives until an explicit `delete`. |
215
+ | `DatabaseWorkflowStore` | class | `new (table: TableInterface<WorkflowSnapshotRow>) => WorkflowStoreInterface` | Implements a `WorkflowStoreInterface` backed by one table of the `databases` layer — a workflow's durable run state is a row, so persistence reduces to keyed point-access (`get` / `set` / `delete`) over a `TableInterface`, the driver-pluggable twin of the plain-`Map` `MemoryWorkflowStore`. |
216
216
 
217
217
  ### Registry
218
218
 
219
219
  The additive manager tier, following the `@orkestrel/agent` line's store standard: `WorkflowManager` (`createWorkflowManager`) is an insertion-ordered registry of live `WorkflowInterface`s keyed by `id`, mirroring `ConversationManager` / `WorkspaceManager` — with the same optional `store` seam (`open` hydrates on a registry miss, `save` persists) but no `active` / `switch` pointer (nothing in this domain renders "the current workflow"). The workflow-specific nuance: the manager also carries an optional `functions` registry threaded into every mint (`add`, through `createWorkflow`) and every hydrate (`open`, through `createRestoredWorkflow`). With functions, named work is runnable; without them, exact hydrated state remains inspectable and execution refuses unresolved names.
220
220
 
221
- | Class | Kind | Summary |
222
- | ----------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
223
- | `WorkflowManager` | class | Implements the store-backed registry of `WorkflowInterface`s keyed by `id`, in insertion order — the additive manager tier mirroring the `@orkestrel/agent` line's `ConversationManager` / `WorkspaceManager`. Event-free (a registry, like its twins); the observability lives on each `WorkflowInterface`. |
221
+ | Name | Kind | Signature | Summary |
222
+ | ----------------- | ----- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
223
+ | `WorkflowManager` | class | `new (options?: WorkflowManagerOptions) => WorkflowManagerInterface` | Implements the store-backed registry of `WorkflowInterface`s keyed by `id`, in insertion order — the additive manager tier mirroring the `@orkestrel/agent` line's `ConversationManager` / `WorkspaceManager`. Event-free (a registry, like its twins); the observability lives on each `WorkflowInterface`. |
224
224
 
225
225
  ### Errors
226
226
 
227
- | API | Kind | Summary |
228
- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
229
- | `WorkflowError` | class | Represents an error the workflow runtime raises for an operation it refuses — a `WorkflowErrorCode` (`TRANSITION`, `RESTORE`, `MUTATION`, `SCHEDULE`, or `INVARIANT`) beside an optional `context` naming the node or the parameter at fault. |
230
- | `isWorkflowError` | function | Narrows an unknown caught value to a `WorkflowError`. |
227
+ | Name | Kind | Signature | Summary |
228
+ | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
229
+ | `WorkflowError` | class | `new (code: WorkflowErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => WorkflowError` | Represents an error the workflow runtime raises for an operation it refuses — a `WorkflowErrorCode` (`TRANSITION`, `RESTORE`, `MUTATION`, `SCHEDULE`, or `INVARIANT`) beside an optional `context` naming the node or the parameter at fault. |
230
+ | `isWorkflowError` | function | `(value: unknown) => value is WorkflowError` | Narrows an unknown caught value to a `WorkflowError`. |
231
231
 
232
232
  Every error this package raises for a refused operation of its own is a `WorkflowError`, narrowable with `isWorkflowError`. These values are deliberately not translated and reach the caller unchanged: a value thrown by a consumer-supplied `WorkflowFunction`, a value thrown or rejected by a consumer-supplied `WorkflowStoreInterface`, a value thrown by the `start` closure a caller hands `createHostSchedule` or reported through its `failure` callback, and the `reason` an `AbortSignal` carries — a pending wait rejects with that reason verbatim, which is what makes cancellation identity-preserving. Each is a caller-owned value the package passes through on purpose, not a package fault it failed to wrap.
233
233
 
@@ -244,53 +244,53 @@ consumers import its `JSONRecord`, `cloneJSONValue`, and `cloneJSONRecord` from
244
244
  originating package. Workflow does not re-export them. Its domain cloners below add
245
245
  workflow-specific validation and translate ownership failures into `WorkflowError`.
246
246
 
247
- | API | Kind | Summary |
248
- | --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
249
- | `cloneWorkflowSnapshot` | function | Validates and owns a workflow snapshot before live construction. |
250
- | `isWorkflowSnapshot` | function | Guards the hostile boundary totally for a workflow snapshot. |
251
- | `isOwnedWorkflowSnapshot` | function | Validates a safe owned JSON graph as a coherent workflow snapshot. |
252
- | `isLifecycleStatus` | function | Checks whether an unknown value belongs to the workflow lifecycle vocabulary. |
253
- | `isTaskFailure` | function | Tests a normalized persisted task failure. |
254
- | `isTaskResult` | function | Tests a result's lineage against its containing snapshot nodes. |
255
- | `matchesDescription` | function | Compares two optional description values. |
256
- | `hasWorkflowHandlers` | function | Tests that every named task has a callable runtime handler before dispatch. |
257
- | `scanSnapshotContext` | function | Locates the nearest identifiable node for an inconsistent owned snapshot. |
258
- | `isTerminalStatus` | function | Tests whether a `LifecycleStatus` is terminal — `completed`, `failed`, `skipped`, or `stopped`, the states a node never transitions out of. |
259
- | `derivePhaseStatus` | function | Derives a phase's status from its tasks' statuses, the most severe terminal status winning (tasks are concurrent, so this is an order-insensitive reduction). |
260
- | `deriveWorkflowStatus` | function | Derives a workflow's status from its phases' `PhaseDerivation`s — each phase's status paired with the effective `bail` it ran under (`phase.bail ?? workflow.bail`) — so the failure outcome is aware of each phase's own policy, and `failed` is reachable only where that policy is `true` (phases are sequential, but the derivation is an order-insensitive reduction over the settled set). |
261
- | `deriveBoundary` | function | Derives the pending-suffix boundary of a positional list of `LifecycleStatus`es — the index of the first entry in the contiguous trailing run of `pending` entries, or the list's length where it has none. |
262
- | `canTransitionTask` | function | Tests whether the live W-b task state machine may move directly from one `LifecycleStatus` to another — the legal-transition guard. |
263
- | `resolveTaskSilence` | function | Resolves a task's runtime silence window against its workflow default, to a host-safe `1..MAX_TIMER_MS` window or to `undefined` where the task disables it. |
264
- | `cloneTaskActivity` | function | Validates and clones one complete task activity frame. |
265
- | `cloneTaskProgress` | function | Copies a supplied task progress frame after checking its own keys and prototype. |
266
- | `isTaskActivityInput` | function | Tests whether an unknown value is a valid whole-frame activity report. |
267
- | `isTaskActivity` | function | Tests whether an unknown value is valid persisted task activity. |
268
- | `captureWorkflowOptions` | function | Captures every top-level `WorkflowOptions` value exactly once into an owned plain bag. |
269
- | `createHostSchedule` | function | Schedules one cancellable host operation behind an owned settlement signal. |
270
- | `success` | function | Boxes a value as a `Success` — the graceful outcome half of a `Result`. |
271
- | `failure` | function | Boxes an error as a `Failure` — the graceful outcome half of a `Result`. |
272
- | `errorToMessage` | function | Normalizes an unknown thrown value to a non-empty persistence-safe message. |
273
- | `findFailure` | function | Finds the first `TaskResult` in a positional list whose boxed outcome is a `Failure` — the pure scan shared by a phase's and a workflow's derived-`failed` `fail`-event lookup. |
274
- | `buildWorkflowContext` | function | Builds a `WorkflowContext` — the identity every level inherits — from a node's `id` / `name` / optional `description`. |
275
- | `buildPhaseContext` | function | Builds a `PhaseContext` — a phase's own identity plus a back-reference to its workflow — from the parent `WorkflowContext` and the phase node's identity. |
276
- | `buildTaskContext` | function | Builds a `TaskContext` — a task's own identity plus a back-reference to its phase (and, transitively, its workflow) — from the parent `PhaseContext` and the task node's identity. |
277
- | `definitionToSnapshot` | function | Converts a `WorkflowDefinition` into an initial `WorkflowSnapshot` — every node `pending`, no results, empty metadata — so the live W-b tree has one construction path, snapshot-driven, for a fresh build and for a restore alike. |
278
- | `phaseDefinitionToSnapshot` | function | Converts one `PhaseDefinition` into an initial, all-`pending` `PhaseSnapshot` — the per-phase step of `definitionToSnapshot`. |
279
- | `taskDefinitionToSnapshot` | function | Converts one `TaskDefinition` into an initial, `pending` `TaskSnapshot` — the per-task leaf step of `definitionToSnapshot` (no result yet, empty metadata). |
280
- | `recoverWorkflowSnapshot` | function | Converts interrupted running work into a recoverable pending suffix or an exhausted recovery failure without replenishing attempts. |
281
- | `collectResults` | function | Flattens a nested list of per-phase `TaskResult` lists into one positional list — the workflow tier of the result tree, built from each phase's `results()`. |
282
- | `parkSignal` | function | Parks until `signal` aborts — a promise-parked wait, never a timer or busy-loop, that resolves on the abort event and never rejects. |
283
- | `insertEntry` | function | Inserts one `[key, value]` entry at a positional index into a readonly entries array — the pure splice-in step behind an insertion-ordered registry's `add`. |
284
- | `moveEntry` | function | Repositions the entry keyed `key` to a new positional index in a readonly entries array — the pure remove-then-reinsert step behind an insertion-ordered registry's `move`. |
285
- | `createHostDelay` | function | Schedules the shared host timer boundary every scheduler backend resumes from. |
286
- | `isWorkflowInterface` | function | Checks whether an unknown value is a live workflow entity rather than a definition. |
287
- | `isTaskClaimList` | function | Checks whether an unknown value is a valid list of task activity claims. |
288
- | `cloneTaskClaims` | function | Validates and owns one list of task activity claims. |
289
- | `isHalted` | function | Tests whether a driving run must stop giving a workflow — or one forced phase of it — more work. |
290
- | `isStoppable` | function | Tests whether forcing a workflow `stopped` would still record the cancellation. |
291
- | `isCompletable` | function | Tests whether a naturally-finished run may force its workflow `completed`. |
292
- | `matchesAbortedAttempt` | function | Tests whether a task attempt is aborted rather than merely timed out. |
293
- | `ownsAttempt` | function | Tests whether one attempt still owns the task it launched. |
247
+ | Name | Kind | Signature | Summary |
248
+ | --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
249
+ | `cloneWorkflowSnapshot` | function | `(input: unknown, id?: string) => WorkflowSnapshot` | Validates and owns a workflow snapshot before live construction. |
250
+ | `isWorkflowSnapshot` | function | `(value: unknown) => value is WorkflowSnapshot` | Guards the hostile boundary totally for a workflow snapshot. |
251
+ | `isOwnedWorkflowSnapshot` | function | `(value: unknown) => value is WorkflowSnapshot` | Validates a safe owned JSON graph as a coherent workflow snapshot. |
252
+ | `isLifecycleStatus` | function | `(value: unknown) => value is LifecycleStatus` | Checks whether an unknown value belongs to the workflow lifecycle vocabulary. |
253
+ | `isTaskFailure` | function | `(value: unknown) => value is TaskFailure` | Tests a normalized persisted task failure. |
254
+ | `isTaskResult` | function | `(value: unknown, workflow: unknown, phase: unknown, task: unknown) => value is TaskResult` | Tests a result's lineage against its containing snapshot nodes. |
255
+ | `matchesDescription` | function | `(left: unknown, right: unknown) => boolean` | Compares two optional description values. |
256
+ | `hasWorkflowHandlers` | function | `((workflow: WorkflowInterface) => boolean) & ((workflow: WorkflowSnapshot, functions: WorkflowRegistry \| undefined) => boolean)` | Tests that every named task has a callable runtime handler before dispatch. |
257
+ | `scanSnapshotContext` | function | `(value: unknown) => Readonly<Record<string, unknown>> \| undefined` | Locates the nearest identifiable node for an inconsistent owned snapshot. |
258
+ | `isTerminalStatus` | function | `(status: LifecycleStatus) => boolean` | Tests whether a `LifecycleStatus` is terminal — `completed`, `failed`, `skipped`, or `stopped`, the states a node never transitions out of. |
259
+ | `derivePhaseStatus` | function | `(tasks: readonly LifecycleStatus[]) => LifecycleStatus` | Derives a phase's status from its tasks' statuses, the most severe terminal status winning (tasks are concurrent, so this is an order-insensitive reduction). |
260
+ | `deriveWorkflowStatus` | function | `(phases: readonly PhaseDerivation[]) => LifecycleStatus` | Derives a workflow's status from its phases' `PhaseDerivation`s — each phase's status paired with the effective `bail` it ran under (`phase.bail ?? workflow.bail`) — so the failure outcome is aware of each phase's own policy, and `failed` is reachable only where that policy is `true` (phases are sequential, but the derivation is an order-insensitive reduction over the settled set). |
261
+ | `deriveBoundary` | function | `(statuses: readonly LifecycleStatus[]) => number` | Derives the pending-suffix boundary of a positional list of `LifecycleStatus`es — the index of the first entry in the contiguous trailing run of `pending` entries, or the list's length where it has none. |
262
+ | `canTransitionTask` | function | `(from: LifecycleStatus, to: LifecycleStatus) => boolean` | Tests whether the live W-b task state machine may move directly from one `LifecycleStatus` to another — the legal-transition guard. |
263
+ | `resolveTaskSilence` | function | `(value: number \| undefined, fallback: number \| undefined) => number \| undefined` | Resolves a task's runtime silence window against its workflow default, to a host-safe `1..MAX_TIMER_MS` window or to `undefined` where the task disables it. |
264
+ | `cloneTaskActivity` | function | `(input: unknown, updated?: number) => TaskActivity` | Validates and clones one complete task activity frame. |
265
+ | `cloneTaskProgress` | function | `(input: unknown) => unknown` | Copies a supplied task progress frame after checking its own keys and prototype. |
266
+ | `isTaskActivityInput` | function | `(value: unknown) => value is TaskActivityInput` | Tests whether an unknown value is a valid whole-frame activity report. |
267
+ | `isTaskActivity` | function | `(value: unknown) => value is TaskActivity` | Tests whether an unknown value is valid persisted task activity. |
268
+ | `captureWorkflowOptions` | function | `(options?: WorkflowOptions) => WorkflowOptions` | Captures every top-level `WorkflowOptions` value exactly once into an owned plain bag. |
269
+ | `createHostSchedule` | function | `(start: HostScheduleFunction, signal?: AbortSignal) => Promise<void>` | Schedules one cancellable host operation behind an owned settlement signal. |
270
+ | `success` | function | `<T>(value: T) => Success<T>` | Boxes a value as a `Success` — the graceful outcome half of a `Result`. |
271
+ | `failure` | function | `<E>(error: E) => Failure<E>` | Boxes an error as a `Failure` — the graceful outcome half of a `Result`. |
272
+ | `errorToMessage` | function | `(error: unknown) => string` | Normalizes an unknown thrown value to a non-empty persistence-safe message. |
273
+ | `findFailure` | function | `(results: readonly TaskResult[]) => TaskResult \| undefined` | Finds the first `TaskResult` in a positional list whose boxed outcome is a `Failure` — the pure scan shared by a phase's and a workflow's derived-`failed` `fail`-event lookup. |
274
+ | `buildWorkflowContext` | function | `(node: WorkflowContext) => WorkflowContext` | Builds a `WorkflowContext` — the identity every level inherits — from a node's `id` / `name` / optional `description`. |
275
+ | `buildPhaseContext` | function | `(workflow: WorkflowContext, node: WorkflowContext) => PhaseContext` | Builds a `PhaseContext` — a phase's own identity plus a back-reference to its workflow — from the parent `WorkflowContext` and the phase node's identity. |
276
+ | `buildTaskContext` | function | `(phase: PhaseContext, node: WorkflowContext) => TaskContext` | Builds a `TaskContext` — a task's own identity plus a back-reference to its phase (and, transitively, its workflow) — from the parent `PhaseContext` and the task node's identity. |
277
+ | `definitionToSnapshot` | function | `(definition: WorkflowDefinition, bail?: boolean) => WorkflowSnapshot` | Converts a `WorkflowDefinition` into an initial `WorkflowSnapshot` — every node `pending`, no results, empty metadata — so the live W-b tree has one construction path, snapshot-driven, for a fresh build and for a restore alike. |
278
+ | `phaseDefinitionToSnapshot` | function | `(phase: WorkflowDefinition['phases'][number], workflowBail: boolean) => PhaseSnapshot` | Converts one `PhaseDefinition` into an initial, all-`pending` `PhaseSnapshot` — the per-phase step of `definitionToSnapshot`. |
279
+ | `taskDefinitionToSnapshot` | function | `(task: WorkflowDefinition['phases'][number]['tasks'][number]) => TaskSnapshot` | Converts one `TaskDefinition` into an initial, `pending` `TaskSnapshot` — the per-task leaf step of `definitionToSnapshot` (no result yet, empty metadata). |
280
+ | `recoverWorkflowSnapshot` | function | `(snapshot: WorkflowSnapshot) => WorkflowSnapshot` | Converts interrupted running work into a recoverable pending suffix or an exhausted recovery failure without replenishing attempts. |
281
+ | `collectResults` | function | `(phases: ReadonlyArray<readonly TaskResult[]>) => readonly TaskResult[]` | Flattens a nested list of per-phase `TaskResult` lists into one positional list — the workflow tier of the result tree, built from each phase's `results()`. |
282
+ | `parkSignal` | function | `(signal: AbortSignal) => Promise<void>` | Parks until `signal` aborts — a promise-parked wait, never a timer or busy-loop, that resolves on the abort event and never rejects. |
283
+ | `insertEntry` | function | `<T>(entries: ReadonlyArray<readonly [string, T]>, index: number, key: string, value: T) => ReadonlyArray<readonly [string, T]>` | Inserts one `[key, value]` entry at a positional index into a readonly entries array — the pure splice-in step behind an insertion-ordered registry's `add`. |
284
+ | `moveEntry` | function | `<T>(entries: ReadonlyArray<readonly [string, T]>, key: string, index: number) => ReadonlyArray<readonly [string, T]>` | Repositions the entry keyed `key` to a new positional index in a readonly entries array — the pure remove-then-reinsert step behind an insertion-ordered registry's `move`. |
285
+ | `createHostDelay` | function | `(ms: number, signal?: AbortSignal) => Promise<void>` | Schedules the shared host timer boundary every scheduler backend resumes from. |
286
+ | `isWorkflowInterface` | function | `(value: unknown) => value is WorkflowInterface` | Checks whether an unknown value is a live workflow entity rather than a definition. |
287
+ | `isTaskClaimList` | function | `(value: unknown) => value is readonly TaskClaim[]` | Checks whether an unknown value is a valid list of task activity claims. |
288
+ | `cloneTaskClaims` | function | `(input: unknown, noun: string) => readonly unknown[]` | Validates and owns one list of task activity claims. |
289
+ | `isHalted` | function | `(workflow: WorkflowInterface, phase?: PhaseInterface) => boolean` | Tests whether a driving run must stop giving a workflow — or one forced phase of it — more work. |
290
+ | `isStoppable` | function | `(workflow: WorkflowInterface) => boolean` | Tests whether forcing a workflow `stopped` would still record the cancellation. |
291
+ | `isCompletable` | function | `(workflow: WorkflowInterface) => boolean` | Tests whether a naturally-finished run may force its workflow `completed`. |
292
+ | `matchesAbortedAttempt` | function | `(task: TaskInterface, controller: ControllerInterface<TaskInterface, void>, runSignal: AbortSignal) => boolean` | Tests whether a task attempt is aborted rather than merely timed out. |
293
+ | `ownsAttempt` | function | `(owners: ReadonlyMap<string, number>, task: TaskInterface, attempt: number) => boolean` | Tests whether one attempt still owns the task it launched. |
294
294
 
295
295
  Every exported `is*` guard is total over every traversed argument. In particular,
296
296
  `isTaskFailure`, `isTaskResult`, and `isOwnedWorkflowSnapshot` contain throwing
@@ -367,26 +367,26 @@ resolveTaskSilence(0, 30_000) // undefined: the task explicitly disables inherit
367
367
 
368
368
  A `Shape` cell holds the constant's declared type.
369
369
 
370
- | API | Kind | Shape | Summary |
371
- | ------------------ | ----- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
372
- | `taskShape` | const | `ObjectShape<{ id, name, description?, behavior?, retries?, timeout? }>` | Describes the shape of a `TaskDefinition` — identity plus an optional `behavior` behavior reference (a plain registry-key string, min length 1). `description` is optional prose. |
373
- | `phaseShape` | const | `ObjectShape<{ id, name, description?, tasks, concurrency?, bail? }>` | Describes the shape of a `PhaseDefinition` — identity, its ordered `taskShape` tasks, and an optional positive-integer `concurrency` throttle (max tasks in flight; omitted ⇒ unbounded). |
374
- | `workflowShape` | const | `ObjectShape<{ id, name, description?, phases, bail? }>` | Describes the shape of a `WorkflowDefinition` — the contract root: identity, its ordered `phaseShape` phases, and the optional `bail` boolean failure policy (the literal pair `true`/`false`, the runtime mirror of the boolean toggle; omitted ⇒ the graceful default). |
375
- | `taskUpdateShape` | const | `ObjectShape<{ name?, description? }>` | Describes the shape of a `TaskUpdate` — a partial edit to a `pending` task's `name` / `description`, both optional. |
376
- | `phaseUpdateShape` | const | `ObjectShape<{ name?, description?, concurrency?, bail? }>` | Describes the shape of a `PhaseUpdate` — a partial edit to a `pending` phase's `name` / `description` / `concurrency` / `bail`, all optional. |
370
+ | Name | Kind | Signature | Summary |
371
+ | ------------------ | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
372
+ | `taskShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>` | Describes the shape of a `TaskDefinition` — identity plus an optional `behavior` behavior reference (a plain registry-key string, min length 1). `description` is optional prose. |
373
+ | `phaseShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; tasks: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a `PhaseDefinition` — identity, its ordered `taskShape` tasks, and an optional positive-integer `concurrency` throttle (max tasks in flight; omitted ⇒ unbounded). |
374
+ | `workflowShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; phases: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; tasks: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a `WorkflowDefinition` — the contract root: identity, its ordered `phaseShape` phases, and the optional `bail` boolean failure policy (the literal pair `true`/`false`, the runtime mirror of the boolean toggle; omitted ⇒ the graceful default). |
375
+ | `taskUpdateShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>` | Describes the shape of a `TaskUpdate` — a partial edit to a `pending` task's `name` / `description`, both optional. |
376
+ | `phaseUpdateShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a `PhaseUpdate` — a partial edit to a `pending` phase's `name` / `description` / `concurrency` / `bail`, all optional. |
377
377
 
378
378
  ### Constants
379
379
 
380
380
  A `Shape` cell holds the constant's declared type.
381
381
 
382
- | Constant | Kind | Shape | Summary |
382
+ | Name | Kind | Signature | Summary |
383
383
  | --------------------------- | ----- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
384
- | `DEFAULT_BAIL` | const | `boolean` | Names the default `WorkflowDefinition.bail`, `false` — the graceful policy that records a leaf failure and finishes every phase. |
384
+ | `DEFAULT_BAIL` | const | `false` | Names the default `WorkflowDefinition.bail`, `false` — the graceful policy that records a leaf failure and finishes every phase. |
385
385
  | `LIFECYCLE_STATUSES` | const | `readonly LifecycleStatus[]` | Lists every `LifecycleStatus` value, frozen — the vocabulary every tier draws from, in the order `pending`, `running`, `completed`, `failed`, `skipped`, `stopped`. |
386
386
  | `TERMINAL_STATUSES` | const | `readonly LifecycleStatus[]` | Lists the terminal `LifecycleStatus` values, frozen — `completed`, `failed`, `skipped`, and `stopped`, each a state a node never transitions out of. |
387
387
  | `TASK_TRANSITIONS` | const | `Readonly<Record<LifecycleStatus, readonly LifecycleStatus[]>>` | Declares the legal `LifecycleStatus` transition graph of the live W-b task state machine — each current status mapped to the statuses it may move to directly, frozen. |
388
- | `DEFAULT_PHASE_CONCURRENCY` | const | `number` | Names the default per-phase task concurrency the `createWorkflowRunner` runner applies when a `PhaseDefinition` omits its `concurrency` throttle — `1024`, a cap that is effectively unbounded for any realistic phase. |
389
- | `MAX_TIMER_MS` | const | `number` | Names the largest delay representable by the host timer APIs without overflow or clamping, `2_147_483_647` milliseconds. |
388
+ | `DEFAULT_PHASE_CONCURRENCY` | const | `1024` | Names the default per-phase task concurrency the `createWorkflowRunner` runner applies when a `PhaseDefinition` omits its `concurrency` throttle — `1024`, a cap that is effectively unbounded for any realistic phase. |
389
+ | `MAX_TIMER_MS` | const | `2147483647` | Names the largest delay representable by the host timer APIs without overflow or clamping, `2_147_483_647` milliseconds. |
390
390
  | `PERSISTED_NODE_EVENTS` | const | `ReadonlyArray<keyof WorkflowEventMap & keyof PhaseEventMap>` | Lists the `WorkflowEventMap` / `PhaseEventMap` events that make a durable observer re-persist the live tree, frozen — `start`, `complete`, `fail`, `skip`, `stop`, `move`, and `update`. |
391
391
  | `PERSISTED_TASK_EVENTS` | const | `ReadonlyArray<keyof TaskEventMap>` | Lists the `TaskEventMap` events that make a durable observer re-persist the live tree, frozen — `start`, `complete`, `fail`, `skip`, `stop`, `report`, and `pulse`. |
392
392
 
@@ -394,78 +394,78 @@ A `Shape` cell holds the constant's declared type.
394
394
 
395
395
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
396
396
 
397
- | Type | Kind | Shape | Summary |
398
- | ------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
399
- | `TaskDefinition` | interface | `{ id, name, description?, behavior?, retries?, timeout? }` | Represents the serializable definition of one task — its identity, an optional reference to the behavior it runs, and its optional per-task `retries` and `timeout` overrides. |
400
- | `PhaseDefinition` | interface | `{ id, name, description?, tasks, concurrency?, bail? }` | Represents the serializable definition of one phase — its identity, its ordered tasks, an optional resource throttle, and an optional `bail` override of the workflow policy. |
401
- | `WorkflowDefinition` | interface | `{ id, name, description?, phases, bail? }` | Represents the serializable definition of a whole workflow — its identity, its ordered phases, and the `bail` failure policy. |
402
- | `WorkflowContext` | interface | `{ id, name, description? }` | Represents the ambient context of a workflow — the identity every level inherits. |
403
- | `PhaseContext` | interface | `{ id, name, description?, workflow }` | Represents the ambient context of a phase — its own identity plus a back-reference to the workflow it belongs to. |
404
- | `TaskContext` | interface | `{ id, name, description?, phase }` | Represents the ambient context of a task — its own identity plus a back-reference to the phase (and, transitively, the workflow) it belongs to. |
405
- | `WorkflowInput` | type | `Partial<WorkflowContext>` | Represents the minimal data to create a workflow context — a partial `WorkflowContext`. |
406
- | `PhaseInput` | type | `Partial<PhaseContext>` | Represents the minimal data to create a phase context — a partial `PhaseContext`. |
407
- | `TaskInput` | interface | `{ id?, name?, description?, phase?, metadata? }` | Represents the minimal data to create a task context — a partial `TaskContext` plus the open `metadata` bag the task stores and snapshots without interpreting it. |
408
- | `TaskProgress` | interface | `{ progress, total?, message? }` | Represents the aggregate progress most recently reported by a running task. |
409
- | `TaskClaim` | interface | `{ id, name, started }` | Represents one identified thing a running task claims active, with the moment the claim began — the shape `TaskOperation` and `TaskConstraint` share. |
410
- | `TaskOperation` | interface | `{ id, name, started }` | Represents one operation claimed active when a running task's complete frame was accepted. |
411
- | `TaskConstraint` | interface | `{ id, name, started }` | Represents one constraint claimed active when a running task's complete frame was accepted. |
412
- | `TaskActivityInput` | interface | `{ note?, progress?, operations?, constraints? }` | Represents one complete replacement of a running task's observable activity, an omitted collection meaning an empty one. |
413
- | `TaskActivity` | interface | `{ note?, progress?, operations, constraints, updated }` | Represents the bounded, JSON-serializable activity most recently accepted from a task reporter. |
414
- | `TaskUpdate` | interface | `{ name?, description? }` | Represents a declarative partial update to a `TaskInterface` — the fields a `pending` task's `TaskInterface.patch` (and the owning `TaskManagerInterface.update`) accept, runtime-validated through `taskUpdateShape`. |
415
- | `PhaseUpdate` | interface | `{ name?, description?, concurrency?, bail? }` | Represents a declarative partial update to a `PhaseInterface` — the fields a `pending` phase's `PhaseInterface.patch` (and the owning `PhaseManagerInterface.update`) accept, runtime-validated through `phaseUpdateShape`. |
416
- | `WorkflowErrorCode` | type | `'TRANSITION' \| 'RESTORE' \| 'MUTATION' \| 'SCHEDULE' \| 'INVARIANT'` | Names the machine-readable code of a `WorkflowError` — the fault the live W-b state machine raises. |
417
- | `LifecycleStatus` | type | `'pending' \| 'running' \| 'completed' \| 'failed' \| 'skipped' \| 'stopped'` | Names the shared lifecycle vocabulary every tier draws from — `pending` before it runs, `running` while in flight, then one of the terminal states `completed` / `failed` / `skipped` / `stopped`. |
418
- | `PhaseDerivation` | interface | `{ status, bail }` | Represents one phase's contribution to the workflow-status derivation — its `LifecycleStatus` paired with the effective `bail` policy it ran under (`phase.bail ?? workflow.bail`) — the input shape `deriveWorkflowStatus` reduces. |
419
- | `TaskFailureOrigin` | type | `'handler' \| 'timeout' \| 'recovery'` | Names where a task failure arose — the axis a persisted `TaskFailure` records. |
420
- | `TaskFailure` | interface | `{ origin, message }` | Represents a normalized JSON-safe task failure persisted without a stack or cause. |
421
- | `TaskResult` | interface | `{ task, phase, workflow, status, result?, timestamp }` | Represents the structured outcome of a task execution — its full lineage, its terminal status, the moment it settled, and its boxed produced outcome. |
422
- | `TaskSnapshot` | interface | `{ id, name, description?, status, result?, metadata, attempts, behavior?, retries?, timeout?, activity? }` | Represents a JSON-serializable snapshot of one task's state — the leaf of the snapshot tree the durable store (W-d) persists. |
423
- | `PhaseSnapshot` | interface | `{ id, name, description?, status, override?, bail, concurrency?, tasks }` | Represents a JSON-serializable snapshot of one phase's state — its identity, status, the forced override a whole-phase `skip` or `stop` left, the effective `bail` and `concurrency` it ran under, and its nested task snapshots. |
424
- | `WorkflowSnapshot` | interface | `{ id, name, description?, status, override?, bail, phases, created, updated }` | Represents a JSON-serializable snapshot of a whole workflow's state — its identity, status, its forced override (if any), the `bail` policy it ran under, its nested phase snapshots, and creation / update timestamps. |
425
- | `WorkflowStoreInterface` | interface | `{} plus get, set, delete` | Declares the durable persistence seam for a `WorkflowSnapshot` — the async `get` / `set` / `delete` primitives keyed by a workflow id, the snapshot analogue of the server package's `SessionStoreInterface` (and the `@orkestrel/queue` `QueueStoreInterface` driver-swap pattern). |
426
- | `WorkflowSnapshotRow` | interface | `{ id, snapshot }` | Represents one row of the table a `DatabaseWorkflowStore` persists — a workflow `id` plus its `WorkflowSnapshot` held as one opaque JSON column, read back as `unknown` and narrowed on `get`. |
427
- | `WorkflowEventMap` | type | `{ start, complete, fail, pause, resume, skip, stop, add, remove, move, update }` | Declares the push observation surface of the workflow entity (W-b) — the lifecycle moments a fire-and-forget observer subscribes to through `workflow.emitter.on`. |
428
- | `PhaseEventMap` | type | `{ start, complete, fail, pause, resume, skip, stop, add, remove, move, update }` | Declares the push observation surface of the phase entity (W-b) — analogous to `WorkflowEventMap`, scoped to one phase. |
429
- | `TaskEventMap` | type | `{ start, complete, fail, pause, resume, skip, stop, report, pulse, silence }` | Declares the push observation surface of the task entity (W-b) — the lifecycle moments of one task. |
430
- | `TaskOptions` | interface | `{ on?, error?, metadata?, silence? }` | Declares the runtime options for a `TaskInterface` — the construction bag the live leaf state machine (W-b) carries that the W-a `TaskDefinition` did not. |
431
- | `PhaseOptions` | interface | `{ on?, error?, tasks? }` | Declares the runtime options for a `PhaseInterface` — the construction bag the live derived phase state machine (W-b) carries. |
432
- | `WorkflowOptions` | interface | `{ on?, bail?, error?, phases?, functions?, silence? }` | Declares the runtime options for a `WorkflowInterface` — the construction bag the live derived workflow state machine (W-b) carries, the root `createWorkflow` accepts. |
433
- | `WorkflowInterface` | interface | `{ emitter, id, name, description, context, bail, status, phases, paused, destroyed, signal } plus phase, results, skip, stop, complete, pause, resume, destroy, wait, add, remove, move, update, snapshot` | Declares the live derived state machine (W-b) for a whole `WorkflowDefinition` — the observable root whose `LifecycleStatus` is derived from its phases under the `bail` policy and recomputed reactively as the cascade propagates up. |
434
- | `PhaseInterface` | interface | `{ emitter, id, name, description, context, workflow, status, bail, concurrency, paused, tasks } plus task, results, skip, stop, pause, resume, wait, add, remove, move, update, patch, snapshot` | Declares the live derived state machine (W-b) for one `PhaseDefinition` — an observable phase whose `LifecycleStatus` is derived from its tasks (never set directly) and recomputed reactively as a task transitions (the cascade). |
435
- | `TaskInterface` | interface | `{ emitter, id, name, description, context, phase, workflow, status, attempts, result, behavior, handler, retries, timeout, activity, silence, silent, paused, signal } plus start, complete, fail, skip, stop, report, pulse, pause, resume, wait, patch, snapshot` | Declares the live leaf state machine (W-b) for one `TaskDefinition` — an observable, guarded synchronous task whose explicit `LifecycleStatus` advances through the declared transitions. |
436
- | `TaskManagerInterface` | interface | `{ count } plus append, add, remove, move, update, task, tasks` | Declares the lean child manager of a `PhaseInterface`'s live tasks — positional accessors plus `count`, backed by an insertion-ordered store so order is preserved across an interior `skip` / `remove`. |
437
- | `PhaseManagerInterface` | interface | `{ count } plus append, add, remove, move, update, phase, phases` | Declares the lean child manager of a `WorkflowInterface`'s live phases — positional accessors plus `count`, the phase analogue of `TaskManagerInterface`. |
438
- | `CollectionEntry` | interface | `{ id, status } plus patch` | Declares what the `CollectionInterface` store requires of the entities it holds — a stable `id`, a gating `LifecycleStatus`, and a `patch` the store applies after validation. |
439
- | `CollectionInterface` | interface | `{ count } plus append, add, remove, move, update, entry, entries` | Declares an insertion-ordered store of `CollectionEntry` entities keyed by `id`, with the gated mutation quartet a lean manager delegates to. |
440
- | `WorkflowFunction` | type | `(controller: TaskControllerInterface) => Promise<JSONValue> \| JSONValue` | Declares the registered behavior a `function`-form `TaskDefinition` runs, resolved by name through the `WorkflowRegistry` registry — a function type the framework invokes. |
441
- | `WorkflowRegistry` | type | `Readonly<Record<string, WorkflowFunction>>` | Declares the `function`-task behavior registry — workflow function names mapped to their `WorkflowFunction` handlers. |
442
- | `TaskControllerInterface` | interface | `{ signal, aborted, input, task, attempt, paused } plus report, pulse, wait, results` | Declares the per-task handle a `WorkflowFunction` receives — the running task's cancellation, its input, its lineage, and read access up the tree to the results already settled. |
443
- | `AttemptOutcome` | type | `readonly [settled: true, value: JSONValue] \| readonly [settled: false, value: undefined, genuine?: boolean]` | Names how one task attempt left the race between its handler and its cancellation. |
444
- | `RunHolderInterface` | interface | `{ runner } plus hold` | Holds the phase `RunnerInterface` one `WorkflowRunnerInterface.execute` call is driving, for the lifetime of that run. |
445
- | `HostScheduleInterface` | interface | `{ promise }` | Exposes the settlement of one owned host operation. |
446
- | `HostScheduleFunction` | type | `(complete, failure) => cancel` | Arms one host operation and returns its cancellation closure. |
447
- | `WorkflowExecutionInterface` | interface | `{ cursor, persistence } plus start / advance / clear` | Owns the bounds, durability, and phase cursor of one workflow execution. |
448
- | `TaskAttemptInterface` | interface | `{ outcome } plus resolve` | Holds the captured outcome of one task handler invocation. |
449
- | `PhaseExecutionInterface` | interface | `{ launched, attempts, owners } plus add / restore / record / claim / revoke` | Owns task launch membership, attempt counts, and active claims for one phase execution. |
450
- | `WorkflowResult` | interface | `{ workflow, status, results, durable?, fault? }` | Represents the structured outcome of a `WorkflowRunnerInterface.execute` run — the settled live workflow, its final status, the flattened result tree, and the persistence outcome a supplied store produced. |
451
- | `WorkflowCheckpoint` | type | `'initial' \| 'attempt' \| 'settlement' \| 'final'` | Names a runner-owned durability boundary. |
452
- | `WorkflowFault` | interface | `{ checkpoint, message, task?, attempt? }` | Represents a normalized persistence failure surfaced as workflow result data. |
453
- | `WorkflowPersistenceInterface` | interface | `{ fault } plus checkpoint, finalize, detach` | Declares the advanced run-local durability coordinator normally composed by `WorkflowRunnerInterface.execute` when `store` is supplied. |
454
- | `WorkflowRunOptions` | type | `WorkflowOptions & { signal?, timeout?, budget?, store? }` | Declares the options for one `WorkflowRunnerInterface.execute` call — the live tree's construction options (`WorkflowOptions`) beside the per-run controls: the bounds (an external abort, a deadline, and a cost ceiling), each folded into every task's cancellation, and the optional durable `store`. |
455
- | `WorkflowRunnerOptions` | interface | `{ scheduler? }` | Declares the options for `createWorkflowRunner` — the optional pacing scheduler the runner paces phase boundaries with. |
456
- | `WorkflowRunnerInterface` | interface | `{} plus execute` | Declares a thin orchestrator that executes a live `WorkflowInterface` tree by composing the shipped substrate — phases sequential, tasks concurrent, each task dispatched through its own resolved handler under the `bail` policy. |
457
- | `WorkflowManagerOptions` | interface | `{ store?, functions? }` | Declares the options for `createWorkflowManager` — the optional durable `WorkflowStoreInterface` seam plus the `WorkflowRegistry` registry every workflow the manager mints or hydrates resolves its tasks' handlers against. |
458
- | `WorkflowManagerInterface` | interface | `{ count } plus workflow, workflows, add, open, save, remove, clear` | Declares a store-backed registry of `WorkflowInterface`s keyed by their `id`, in insertion order — the additive manager tier mirroring `ConversationManagerInterface` / `WorkspaceManagerInterface` from the `@orkestrel/agent` line, adapted for the workflow domain: `add` mints from a `WorkflowDefinition`, and the optional `store` seam's `open` threads the manager's `WorkflowRegistry` registry, so a hydrated workflow is immediately runnable rather than a restored state mirror. |
459
- | `SchedulerPriority` | type | `'user' \| 'normal' \| 'background'` | Names the relative urgency hint for cooperative scheduling. Honoured by environment backends; the cross-environment default treats all priorities uniformly. |
460
- | `SchedulerOptions` | interface | `{ priority?, signal? }` | Declares the options for a single cooperative yield/delay. |
461
- | `SchedulerInterface` | interface | `{} plus yield, delay` | Declares a cooperative host-yield primitive: a loop decides what to do; the scheduler decides when the host regains control. It is abort-aware — a pending yield or delay rejects with the signal's reason when aborted. |
462
- | `ControllerInterface` | interface | `{ id, input, signal, aborted } plus wait, spawn, abort` | Declares the per-unit handle a `RunnerHandler` receives — the running unit's identity, input, cancellation, and the controls to cooperate with the run. |
463
- | `RunnerHandler` | type | `(controller: ControllerInterface<TInput, TResult>) => Promise<TResult> \| TResult` | Runs one unit's work, given its `ControllerInterface`. |
464
- | `RunnerOptions` | interface | `{ on?, error?, handler, concurrency?, retries?, timeout?, entries? }` | Declares the options for `createRunner` — the `handler` every unit runs, the queue bounds `concurrency`, `retries`, and `timeout`, the per-entry `entries` resolver, and the emitter `on` hooks and `error` handler. |
465
- | `RunnerEntryOptions` | interface | `{ retries?, timeout? }` | Declares the per-entry reliability overrides for one unit — its extra attempts on failure and its per-attempt deadline, resolved from the unit's input through `RunnerOptions.entries`. |
466
- | `RunnerInterface` | interface | `{ emitter, active, stopped, paused } plus execute, spawn, abort, pause, resume, stop, destroy` | Declares a thin generic orchestrator that drives declared units — plus any they `spawn` — through a bounded-concurrency queue, collecting their results in order. |
467
- | `RunnerEventMap` | type | `{ start, unit, spawn, settle, fail, finish, abort }` | Declares the push observation surface of a `RunnerInterface` — the run lifecycle a fire-and-forget observer (logging, metrics, tracing) subscribes to, beside the eventual `execute` result. |
468
- | `RunnerUnit` | interface | `{ id, input }` | Represents one unit the `RunnerInterface` is tracking: the queue payload it was enqueued with — its `id` (a random UUID) keys it in the runner's ordered launch list and value map, and `input` is the unit's work payload handed to the handler's `Controller`. |
397
+ | Name | Kind | Signature | Summary |
398
+ | ------------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
399
+ | `TaskDefinition` | interface | `{ id, name, description?, behavior?, retries?, timeout? }` | Represents the serializable definition of one task — its identity, an optional reference to the behavior it runs, and its optional per-task `retries` and `timeout` overrides. |
400
+ | `PhaseDefinition` | interface | `{ id, name, description?, tasks, concurrency?, bail? }` | Represents the serializable definition of one phase — its identity, its ordered tasks, an optional resource throttle, and an optional `bail` override of the workflow policy. |
401
+ | `WorkflowDefinition` | interface | `{ id, name, description?, phases, bail? }` | Represents the serializable definition of a whole workflow — its identity, its ordered phases, and the `bail` failure policy. |
402
+ | `WorkflowContext` | interface | `{ id, name, description? }` | Represents the ambient context of a workflow — the identity every level inherits. |
403
+ | `PhaseContext` | interface | `{ workflow }` | Represents the ambient context of a phase — its own identity plus a back-reference to the workflow it belongs to. |
404
+ | `TaskContext` | interface | `{ phase }` | Represents the ambient context of a task — its own identity plus a back-reference to the phase (and, transitively, the workflow) it belongs to. |
405
+ | `WorkflowInput` | type | `Partial<WorkflowContext>` | Represents the minimal data to create a workflow context — a partial `WorkflowContext`. |
406
+ | `PhaseInput` | type | `Partial<PhaseContext>` | Represents the minimal data to create a phase context — a partial `PhaseContext`. |
407
+ | `TaskInput` | interface | `{ metadata? }` | Represents the minimal data to create a task context — a partial `TaskContext` plus the open `metadata` bag the task stores and snapshots without interpreting it. |
408
+ | `TaskProgress` | interface | `{ progress, total?, message? }` | Represents the aggregate progress most recently reported by a running task. |
409
+ | `TaskClaim` | interface | `{ id, name, started }` | Represents one identified thing a running task claims active, with the moment the claim began — the shape `TaskOperation` and `TaskConstraint` share. |
410
+ | `TaskOperation` | interface | `{}` | Represents one operation claimed active when a running task's complete frame was accepted. |
411
+ | `TaskConstraint` | interface | `{}` | Represents one constraint claimed active when a running task's complete frame was accepted. |
412
+ | `TaskActivityInput` | interface | `{ note?, progress?, operations?, constraints? }` | Represents one complete replacement of a running task's observable activity, an omitted collection meaning an empty one. |
413
+ | `TaskActivity` | interface | `{ note?, progress?, operations, constraints, updated }` | Represents the bounded, JSON-serializable activity most recently accepted from a task reporter. |
414
+ | `TaskUpdate` | interface | `{ name?, description? }` | Represents a declarative partial update to a `TaskInterface` — the fields a `pending` task's `TaskInterface.patch` (and the owning `TaskManagerInterface.update`) accept, runtime-validated through `taskUpdateShape`. |
415
+ | `PhaseUpdate` | interface | `{ name?, description?, concurrency?, bail? }` | Represents a declarative partial update to a `PhaseInterface` — the fields a `pending` phase's `PhaseInterface.patch` (and the owning `PhaseManagerInterface.update`) accept, runtime-validated through `phaseUpdateShape`. |
416
+ | `WorkflowErrorCode` | type | `'TRANSITION' \| 'RESTORE' \| 'MUTATION' \| 'SCHEDULE' \| 'INVARIANT'` | Names the machine-readable code of a `WorkflowError` — the fault the live W-b state machine raises. |
417
+ | `LifecycleStatus` | type | `'pending' \| 'running' \| 'completed' \| 'failed' \| 'skipped' \| 'stopped'` | Names the shared lifecycle vocabulary every tier draws from — `pending` before it runs, `running` while in flight, then one of the terminal states `completed` / `failed` / `skipped` / `stopped`. |
418
+ | `PhaseDerivation` | interface | `{ status, bail }` | Represents one phase's contribution to the workflow-status derivation — its `LifecycleStatus` paired with the effective `bail` policy it ran under (`phase.bail ?? workflow.bail`) — the input shape `deriveWorkflowStatus` reduces. |
419
+ | `TaskFailureOrigin` | type | `'handler' \| 'timeout' \| 'recovery'` | Names where a task failure arose — the axis a persisted `TaskFailure` records. |
420
+ | `TaskFailure` | interface | `{ origin, message }` | Represents a normalized JSON-safe task failure persisted without a stack or cause. |
421
+ | `TaskResult` | interface | `{ task, phase, workflow, status, result?, timestamp }` | Represents the structured outcome of a task execution — its full lineage, its terminal status, the moment it settled, and its boxed produced outcome. |
422
+ | `TaskSnapshot` | interface | `{ id, name, description?, status, result?, metadata, attempts, behavior?, retries?, timeout?, activity? }` | Represents a JSON-serializable snapshot of one task's state — the leaf of the snapshot tree the durable store (W-d) persists. |
423
+ | `PhaseSnapshot` | interface | `{ id, name, description?, status, override?, bail, concurrency?, tasks }` | Represents a JSON-serializable snapshot of one phase's state — its identity, status, the forced override a whole-phase `skip` or `stop` left, the effective `bail` and `concurrency` it ran under, and its nested task snapshots. |
424
+ | `WorkflowSnapshot` | interface | `{ id, name, description?, status, override?, bail, phases, created, updated }` | Represents a JSON-serializable snapshot of a whole workflow's state — its identity, status, its forced override (if any), the `bail` policy it ran under, its nested phase snapshots, and creation / update timestamps. |
425
+ | `WorkflowStoreInterface` | interface | `{ get(), set(), delete() }` | Declares the durable persistence seam for a `WorkflowSnapshot` — the async `get` / `set` / `delete` primitives keyed by a workflow id, the snapshot analogue of the server package's `SessionStoreInterface` (and the `@orkestrel/queue` `QueueStoreInterface` driver-swap pattern). |
426
+ | `WorkflowSnapshotRow` | interface | `{ id, snapshot }` | Represents one row of the table a `DatabaseWorkflowStore` persists — a workflow `id` plus its `WorkflowSnapshot` held as one opaque JSON column, read back as `unknown` and narrowed on `get`. |
427
+ | `WorkflowEventMap` | type | `{ readonly start: readonly [id: string]; readonly complete: readonly []; readonly fail: readonly [result: TaskResult]; readonly pause: readonly []; readonly resume: readonly []; readonly skip: readonly []; readonly stop: readonly []; readonly add: readonly [phase: PhaseInterface, index: number]; readonly remove: readonly [phase: PhaseInterface]; readonly move: readonly [phase: PhaseInterface, index: number]; readonly update: readonly [phase: PhaseInterface]; }` | Declares the push observation surface of the workflow entity (W-b) — the lifecycle moments a fire-and-forget observer subscribes to through `workflow.emitter.on`. |
428
+ | `PhaseEventMap` | type | `{ readonly start: readonly [id: string]; readonly complete: readonly []; readonly fail: readonly [result: TaskResult]; readonly pause: readonly []; readonly resume: readonly []; readonly skip: readonly []; readonly stop: readonly []; readonly add: readonly [task: TaskInterface, index: number]; readonly remove: readonly [task: TaskInterface]; readonly move: readonly [task: TaskInterface, index: number]; readonly update: readonly [task: TaskInterface]; }` | Declares the push observation surface of the phase entity (W-b) — analogous to `WorkflowEventMap`, scoped to one phase. |
429
+ | `TaskEventMap` | type | `{ readonly start: readonly [id: string]; readonly complete: readonly [result: TaskResult]; readonly fail: readonly [result: TaskResult]; readonly pause: readonly []; readonly resume: readonly []; readonly skip: readonly []; readonly stop: readonly []; readonly report: readonly [activity: TaskActivity]; readonly pulse: readonly [activity: TaskActivity]; readonly silence: readonly []; }` | Declares the push observation surface of the task entity (W-b) — the lifecycle moments of one task. |
430
+ | `TaskOptions` | interface | `{ on?, error?, metadata?, silence? }` | Declares the runtime options for a `TaskInterface` — the construction bag the live leaf state machine (W-b) carries that the W-a `TaskDefinition` did not. |
431
+ | `PhaseOptions` | interface | `{ on?, error?, tasks? }` | Declares the runtime options for a `PhaseInterface` — the construction bag the live derived phase state machine (W-b) carries. |
432
+ | `WorkflowOptions` | interface | `{ on?, bail?, error?, phases?, functions?, silence? }` | Declares the runtime options for a `WorkflowInterface` — the construction bag the live derived workflow state machine (W-b) carries, the root `createWorkflow` accepts. |
433
+ | `WorkflowInterface` | interface | `{ emitter, id, name, description, context, bail, status, phases, paused, destroyed, signal, phase(), results(), skip(), stop(), complete(), pause(), resume(), destroy(), wait(), add(), remove(), move(), update(), snapshot() }` | Declares the live derived state machine (W-b) for a whole `WorkflowDefinition` — the observable root whose `LifecycleStatus` is derived from its phases under the `bail` policy and recomputed reactively as the cascade propagates up. |
434
+ | `PhaseInterface` | interface | `{ emitter, id, name, description, context, workflow, status, bail, concurrency, paused, tasks, task(), results(), skip(), stop(), pause(), resume(), wait(), add(), remove(), move(), update(), patch(), snapshot() }` | Declares the live derived state machine (W-b) for one `PhaseDefinition` — an observable phase whose `LifecycleStatus` is derived from its tasks (never set directly) and recomputed reactively as a task transitions (the cascade). |
435
+ | `TaskInterface` | interface | `{ emitter, id, name, description, context, phase, workflow, status, attempts, result, behavior, handler, retries, timeout, activity, silence, silent, paused, signal, start(), complete(), fail(), skip(), stop(), report(), pulse(), pause(), resume(), wait(), patch(), snapshot() }` | Declares the live leaf state machine (W-b) for one `TaskDefinition` — an observable, guarded synchronous task whose explicit `LifecycleStatus` advances through the declared transitions. |
436
+ | `TaskManagerInterface` | interface | `{ count, append(), add(), remove(), move(), update(), task(), tasks() }` | Declares the lean child manager of a `PhaseInterface`'s live tasks — positional accessors plus `count`, backed by an insertion-ordered store so order is preserved across an interior `skip` / `remove`. |
437
+ | `PhaseManagerInterface` | interface | `{ count, append(), add(), remove(), move(), update(), phase(), phases() }` | Declares the lean child manager of a `WorkflowInterface`'s live phases — positional accessors plus `count`, the phase analogue of `TaskManagerInterface`. |
438
+ | `CollectionEntry` | interface | `{ id, status, patch() }` | Declares what the `CollectionInterface` store requires of the entities it holds — a stable `id`, a gating `LifecycleStatus`, and a `patch` the store applies after validation. |
439
+ | `CollectionInterface` | interface | `{ count, append(), add(), remove(), move(), update(), entry(), entries() }` | Declares an insertion-ordered store of `CollectionEntry` entities keyed by `id`, with the gated mutation quartet a lean manager delegates to. |
440
+ | `WorkflowFunction` | type | `(controller: TaskControllerInterface) => Promise<JSONValue> \| JSONValue` | Declares the registered behavior a `function`-form `TaskDefinition` runs, resolved by name through the `WorkflowRegistry` registry — a function type the framework invokes. |
441
+ | `WorkflowRegistry` | type | `Readonly<Record<string, WorkflowFunction>>` | Declares the `function`-task behavior registry — workflow function names mapped to their `WorkflowFunction` handlers. |
442
+ | `TaskControllerInterface` | interface | `{ signal, aborted, input, task, attempt, paused, report(), pulse(), wait(), results() }` | Declares the per-task handle a `WorkflowFunction` receives — the running task's cancellation, its input, its lineage, and read access up the tree to the results already settled. |
443
+ | `AttemptOutcome` | type | `readonly [settled: true, value: JSONValue] \| readonly [settled: false, value: undefined, genuine?: boolean]` | Names how one task attempt left the race between its handler and its cancellation. |
444
+ | `RunHolderInterface` | interface | `{ runner, hold() }` | Holds the phase `RunnerInterface` one `WorkflowRunnerInterface.execute` call is driving, for the lifetime of that run. |
445
+ | `HostScheduleInterface` | interface | `{ promise }` | Exposes the settlement of one owned host operation. |
446
+ | `HostScheduleFunction` | type | `(complete: () => void, failure: (error: unknown) => void) => () => void` | Arms one host operation and returns its cancellation closure. |
447
+ | `WorkflowExecutionInterface` | interface | `{ cursor, persistence, start(), advance(), clear() }` | Owns the bounds, durability, and phase cursor of one workflow execution. |
448
+ | `TaskAttemptInterface` | interface | `{ outcome, resolve() }` | Holds the captured outcome of one task handler invocation. |
449
+ | `PhaseExecutionInterface` | interface | `{ launched, attempts, owners, add(), restore(), record(), claim(), revoke() }` | Owns task launch membership, attempt counts, and active claims for one phase execution. |
450
+ | `WorkflowResult` | interface | `{ workflow, status, results, durable?, fault? }` | Represents the structured outcome of a `WorkflowRunnerInterface.execute` run — the settled live workflow, its final status, the flattened result tree, and the persistence outcome a supplied store produced. |
451
+ | `WorkflowCheckpoint` | type | `'initial' \| 'attempt' \| 'settlement' \| 'final'` | Names a runner-owned durability boundary. |
452
+ | `WorkflowFault` | interface | `{ checkpoint, message, task?, attempt? }` | Represents a normalized persistence failure surfaced as workflow result data. |
453
+ | `WorkflowPersistenceInterface` | interface | `{ fault, checkpoint(), finalize(), detach() }` | Declares the advanced run-local durability coordinator normally composed by `WorkflowRunnerInterface.execute` when `store` is supplied. |
454
+ | `WorkflowRunOptions` | type | `WorkflowOptions & { readonly signal?: AbortSignal; readonly timeout?: number; readonly budget?: BudgetInterface<TokenUsage>; readonly store?: WorkflowStoreInterface; }` | Declares the options for one `WorkflowRunnerInterface.execute` call — the live tree's construction options (`WorkflowOptions`) beside the per-run controls: the bounds (an external abort, a deadline, and a cost ceiling), each folded into every task's cancellation, and the optional durable `store`. |
455
+ | `WorkflowRunnerOptions` | interface | `{ scheduler? }` | Declares the options for `createWorkflowRunner` — the optional pacing scheduler the runner paces phase boundaries with. |
456
+ | `WorkflowRunnerInterface` | interface | `{ execute() }` | Declares a thin orchestrator that executes a live `WorkflowInterface` tree by composing the shipped substrate — phases sequential, tasks concurrent, each task dispatched through its own resolved handler under the `bail` policy. |
457
+ | `WorkflowManagerOptions` | interface | `{ store?, functions? }` | Declares the options for `createWorkflowManager` — the optional durable `WorkflowStoreInterface` seam plus the `WorkflowRegistry` registry every workflow the manager mints or hydrates resolves its tasks' handlers against. |
458
+ | `WorkflowManagerInterface` | interface | `{ count, workflow(), workflows(), add(), open(), save(), remove(), clear() }` | Declares a store-backed registry of `WorkflowInterface`s keyed by their `id`, in insertion order — the additive manager tier mirroring `ConversationManagerInterface` / `WorkspaceManagerInterface` from the `@orkestrel/agent` line, adapted for the workflow domain: `add` mints from a `WorkflowDefinition`, and the optional `store` seam's `open` threads the manager's `WorkflowRegistry` registry, so a hydrated workflow is immediately runnable rather than a restored state mirror. |
459
+ | `SchedulerPriority` | type | `'user' \| 'normal' \| 'background'` | Names the relative urgency hint for cooperative scheduling. Honoured by environment backends; the cross-environment default treats all priorities uniformly. |
460
+ | `SchedulerOptions` | interface | `{ priority?, signal? }` | Declares the options for a single cooperative yield/delay. |
461
+ | `SchedulerInterface` | interface | `{ yield(), delay() }` | Declares a cooperative host-yield primitive: a loop decides what to do; the scheduler decides when the host regains control. It is abort-aware — a pending yield or delay rejects with the signal's reason when aborted. |
462
+ | `ControllerInterface` | interface | `{ id, input, signal, aborted, wait(), spawn(), abort() }` | Declares the per-unit handle a `RunnerHandler` receives — the running unit's identity, input, cancellation, and the controls to cooperate with the run. |
463
+ | `RunnerHandler` | type | `(controller: ControllerInterface<TInput, TResult>) => Promise<TResult> \| TResult` | Runs one unit's work, given its `ControllerInterface`. |
464
+ | `RunnerOptions` | interface | `{ on?, error?, handler, concurrency?, retries?, timeout?, entries? }` | Declares the options for `createRunner` — the `handler` every unit runs, the queue bounds `concurrency`, `retries`, and `timeout`, the per-entry `entries` resolver, and the emitter `on` hooks and `error` handler. |
465
+ | `RunnerEntryOptions` | interface | `{ retries?, timeout? }` | Declares the per-entry reliability overrides for one unit — its extra attempts on failure and its per-attempt deadline, resolved from the unit's input through `RunnerOptions.entries`. |
466
+ | `RunnerInterface` | interface | `{ emitter, active, stopped, paused, execute(), spawn(), abort(), pause(), resume(), stop(), destroy() }` | Declares a thin generic orchestrator that drives declared units — plus any they `spawn` — through a bounded-concurrency queue, collecting their results in order. |
467
+ | `RunnerEventMap` | type | `{ readonly start: readonly []; readonly unit: readonly [id: string]; readonly spawn: readonly [id: string, parent: string \| undefined]; readonly settle: readonly [id: string]; readonly fail: readonly [id: string, error: unknown]; readonly finish: readonly [results: readonly TResult[]]; readonly abort: readonly [reason: unknown]; }` | Declares the push observation surface of a `RunnerInterface` — the run lifecycle a fire-and-forget observer (logging, metrics, tracing) subscribes to, beside the eventual `execute` result. |
468
+ | `RunnerUnit` | interface | `{ id, input }` | Represents one unit the `RunnerInterface` is tracking: the queue payload it was enqueued with — its `id` (a random UUID) keys it in the runner's ordered launch list and value map, and `input` is the unit's work payload handed to the handler's `Controller`. |
469
469
 
470
470
  ## Methods
471
471