@marianmeres/workflow 1.0.1 → 2.1.0

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.
package/API.md CHANGED
@@ -16,6 +16,7 @@ Full public API for [`@marianmeres/workflow`](./README.md).
16
16
  - [effectJobType](#effectjobtypename)
17
17
  - [Types](#types)
18
18
  - [WorkflowDefinition](#workflowdefinition)
19
+ - [WorkflowFSMConfig](#workflowfsmconfig--workflowstateconfig)
19
20
  - [NodeMeta](#nodemeta)
20
21
  - [Handler](#handler--handlerargs--handlerresult)
21
22
  - [Matcher](#matcher--matcherargs)
@@ -46,28 +47,37 @@ new Workflow(options: WorkflowOptions)
46
47
 
47
48
  **`WorkflowOptions`:**
48
49
 
49
- | Field | Type | Default | Description |
50
- |---|---|---|---|
51
- | `db` | `pg.Pool` | required | PostgreSQL pool. Used for direct SQL (persistence helpers, transactions). |
52
- | `jobs` | `Jobs` | required | Externally-owned `steve.Jobs` instance. Workflow registers its handlers on it via `setHandler`. The consumer runs `jobs.start()` / `jobs.stop()`. |
53
- | `projectId` | `string` | `"_default"` | Multi-tenant scope. |
54
- | `definitions` | `WorkflowDefinition[]` | required | Definitions to register. Validated on construction. |
55
- | `handlers` | `Record<string, Handler>` | required | Effect handlers keyed by name. |
56
- | `matchers` | `Record<string, Matcher>` | `{}` | Signal matchers keyed by name. |
57
- | `effectMaxAttempts` | `number` | `3` | Max retries for effect handlers (steve `max_attempts`). |
58
- | `effectMaxAttemptDurationMs` | `number` | `0` | Per-attempt timeout in ms (`0` = none). |
50
+ | Field | Type | Default | Description |
51
+ | ---------------------------- | ------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
52
+ | `db` | `pg.Pool` | required | PostgreSQL pool. Used for direct SQL (persistence helpers, transactions). |
53
+ | `jobs` | `Jobs` | required | Externally-owned `steve.Jobs` instance. Workflow registers its handlers on it via `setHandler`. The consumer runs `jobs.start()` / `jobs.stop()`. |
54
+ | `tenantId` | `string` | `"_default"` | Multi-tenant scope. |
55
+ | `definitions` | `WorkflowDefinition[]` | required | Definitions to register. Validated on construction. |
56
+ | `handlers` | `Record<string, Handler>` | required | Effect handlers keyed by name. |
57
+ | `matchers` | `Record<string, Matcher>` | `{}` | Signal matchers keyed by name. |
58
+ | `effectMaxAttempts` | `number` | `3` | Max retries for effect handlers (steve `max_attempts`). |
59
+ | `effectMaxAttemptDurationMs` | `number` | `0` | Per-attempt timeout in ms (`0` = none). |
60
+ | `advanceMaxAttempts` | `number` | `10` | Max retries for `workflow.advance` jobs (steve `max_attempts`). Steve's exponential backoff over 10 attempts spans ~17 minutes of database-outage tolerance. |
61
+ | `redispatchLimit` | `number` | `3` | How many times one job payload may be dispatched, counting the original, before an expiry fails the instance. |
59
62
 
60
63
  Throws on construction if any definition references a handler/matcher not present in the maps, or if any other structural problem is found (unknown transition target, missing terminal state, etc.). See [`validateDefinition`](#validatedefinitiondef-available).
61
64
 
62
- The constructor also subscribes (`jobs.onDone`) to terminal failures of each `workflow.effect.<name>` type and marks the corresponding workflow instance `failed` on `failed` / `expired`.
65
+ **One `Workflow` per `Jobs`.** Steve's `setHandler` is last-writer-wins, so a second `Workflow` on the same `Jobs` would take over `workflow.advance` and fail the first one's instances with "Unknown workflow definition". Constructing it throws instead; call [`detach()`](#detach-void) on the incumbent first, or give the second one its own `Jobs`.
66
+
67
+ The constructor also subscribes (`jobs.onDone`) to the terminal outcomes of `workflow.advance` and of each `workflow.effect.<name>` type:
68
+
69
+ - **`failed`** (steve exhausted the attempts) — the instance is marked `failed`, with `effect_failed` history for an effect job and `failed` history carrying the last attempt's error message for an advance.
70
+ - **`expired`** (the worker died mid-run; steve never retries those) — the identical payload is re-queued, up to `redispatchLimit` dispatches in total, and only then is the instance failed. A re-dispatch whose original did commit before the crash is fenced out by `seq`, so it costs nothing.
71
+
72
+ Note that jobs only ever reach `expired` if something reaps them: run the `Jobs` instance with `autoCleanup` or call `jobs.cleanup()` periodically. Without it a crashed worker leaves the instance `running` indefinitely.
63
73
 
64
74
  #### Properties
65
75
 
66
- | Name | Type | Description |
67
- |---|---|---|
68
- | `db` | `pg.Pool` | The provided pool. |
69
- | `jobs` | `Jobs` | The injected `Jobs` instance. |
70
- | `projectId` | `string` | Scope. |
76
+ | Name | Type | Description |
77
+ | ---------- | ------------------ | -------------------------------------------------- |
78
+ | `db` | `pg.Pool` | The provided pool. |
79
+ | `jobs` | `Jobs` | The injected `Jobs` instance. |
80
+ | `tenantId` | `string` | Scope. |
71
81
  | `registry` | `WorkflowRegistry` | Read-only access to definitions/handlers/matchers. |
72
82
 
73
83
  #### Methods
@@ -78,26 +88,46 @@ The constructor also subscribes (`jobs.onDone`) to terminal failures of each `wo
78
88
 
79
89
  Creates a new workflow instance, appends a `created` history entry, and enqueues the first `workflow.advance` job.
80
90
 
81
- | Field | Type | Description |
82
- |---|---|---|
83
- | `definitionId` | `string` | Must be registered. |
84
- | `definitionVersion` | `string` | Must be registered. |
85
- | `context` | `WorkflowContext` (optional) | Initial context. Default: `{}`. |
86
- | `correlationToken` | `string \| null` (optional) | Set up-front for signal-suspending nodes that need to be matchable before the workflow reaches them (e.g. outbound emails using UUID subaddressing). |
91
+ | Field | Type | Description |
92
+ | ------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
93
+ | `definitionId` | `string` | Must be registered. |
94
+ | `definitionVersion` | `string` | Must be registered. |
95
+ | `context` | `WorkflowContext` (optional) | Shallow-merged over the definition's `fsm.context` defaults (top-level keys replace). Default: the defaults alone, or `{}` if the definition declares none. |
96
+ | `correlationToken` | `string \| null` (optional) | Set up-front for signal-suspending nodes that need to be matchable before the workflow reaches them (e.g. outbound emails using UUID subaddressing). A handler can set or clear it later — see [`HandlerResult`](#handler--handlerargs--handlerresult). |
87
97
 
88
98
  ##### `find(id: string): Promise<WorkflowInstanceRow | null>`
89
99
 
90
- Looks up an instance by id, scoped to this Workflow's `projectId`. Returns `null` if not found or scoped to a different project.
100
+ Looks up an instance by id, scoped to this Workflow's `tenantId`. Returns `null` if not found or scoped to a different tenant.
101
+
102
+ ##### `cancel(id: string, reason?: string): Promise<boolean>`
103
+
104
+ Operator escape hatch: aborts a live instance. The row goes `cancelled` (terminal), loses its `wake_at` and its correlation token, and gets a `cancelled` history row carrying `reason`. The `seq` bump makes every job already in flight for it stale — a queued effect job resolves as `{ skipped: "stale" }` without calling its handler, and a late completion is dropped.
105
+
106
+ Returns `false` when the instance does not exist, belongs to another tenant, or is already terminal.
107
+
108
+ ##### `retry(id: string, opts?: { force?: boolean }): Promise<boolean>`
109
+
110
+ Operator escape hatch: resumes a `failed` instance from its current cursor instead of starting a new one and replaying every side effect from the top. The row goes back to `pending`, gets a `retried` history row carrying `from_state`, and a fresh `start` advance re-runs whatever the cursor node calls for — typically re-dispatching its effect.
111
+
112
+ `force: true` also allows a `running` instance, i.e. the operator asserting that its effect job is dead (a worker crashed and nothing reaps the job — see `autoCleanup`). Safe by construction: the `seq` bump makes the zombie stale, so a late completion is dropped.
113
+
114
+ Returns `false` when the instance does not exist, belongs to another tenant, or is in a state this does not cover. Retrying alone fixes nothing: an instance failed by a rejected transition or a deterministically throwing handler fails again unless the code changed.
91
115
 
92
116
  ##### `appendInbox(input): Promise<InboxRow>`
93
117
 
94
- Appends an external signal to `__workflow_inbox`. The correlator's next tick matches it to a waiting instance, runs the matcher, and (on match) enqueues an advance with `outcome: 'MATCHED'` and `outcome_data: payload`.
118
+ Appends an external signal to `__workflow_inbox`. The correlator's next tick matches it to a waiting instance, runs the matcher, and (on match) pokes an advance which delivers `MATCHED` with the row's payload and marks the row processed in one transaction. A signal that arrives before its wait point is deferred, not dropped — see [Per-tick behavior](#per-tick-behavior-1).
119
+
120
+ | Field | Type | Description |
121
+ | ------------------ | ------------------------- | -------------------------------------------------------------- |
122
+ | `source` | `string` | Free-form classifier, e.g. `"email"`, `"webhook"`. |
123
+ | `correlationToken` | `string` | Index key into waiting instances. |
124
+ | `payload` | `Record<string, unknown>` | Signal data, surfaced to the matcher and forwarded to the FSM. |
95
125
 
96
- | Field | Type | Description |
97
- |---|---|---|
98
- | `source` | `string` | Free-form classifier, e.g. `"email"`, `"webhook"`. |
99
- | `correlationToken` | `string` | Index key into waiting instances. |
100
- | `payload` | `Record<string, unknown>` | Signal data, surfaced to the matcher and forwarded to the FSM. |
126
+ ##### `detach(): void`
127
+
128
+ Removes everything the constructor registered on the `Jobs` instance — the `workflow.advance` and `workflow.effect.<name>` handlers plus the `onDone` subscriptions — and releases the one-Workflow-per-`Jobs` claim, so a replacement can be constructed on the same queue (tests, hot reload).
129
+
130
+ It does not stop the queue and does not touch running instances: jobs already enqueued stay in the table and fall back to steve's noop handler until something re-attaches. A no-op when this instance is not the attached one (already detached, or superseded).
101
131
 
102
132
  ##### `enqueueAdvance` / `enqueueEffect`
103
133
 
@@ -107,7 +137,7 @@ Internal `JobEnqueuer` interface methods used by the driver. Public so the sched
107
137
 
108
138
  ### `WorkflowScheduler`
109
139
 
110
- Cron-driven scheduler that wakes time-suspended instances. Attaches its tick to an **externally-owned** `@marianmeres/cron` `Cron` instance when `register()` is called. Each tick claims due rows and enqueues advance jobs with `outcome: 'TIMEOUT'`.
140
+ Cron-driven scheduler that wakes time-suspended instances. Attaches its tick to an **externally-owned** `@marianmeres/cron` `Cron` instance when `register()` is called. Each tick is read-only: it selects due rows and pokes one fenced `TIMEOUT` advance per row, which does the actual write.
111
141
 
112
142
  ```typescript
113
143
  import { WorkflowScheduler } from "@marianmeres/workflow";
@@ -122,24 +152,41 @@ new WorkflowScheduler(options: WorkflowSchedulerOptions)
122
152
 
123
153
  **`WorkflowSchedulerOptions`:**
124
154
 
125
- | Field | Type | Default | Description |
126
- |---|---|---|---|
127
- | `cron` | `Cron` | required | Externally-owned `Cron` instance. Scheduler registers its tick on this via `cron.register`. The consumer runs `cron.start()` / `cron.stop()`. |
128
- | `workflow` | `Workflow` | required | The Workflow whose instances this scheduler wakes. `projectId` and `db` are derived from it. |
129
- | `tickExpression` | `string` | `"* * * * *"` | 5-field cron expression. |
130
- | `timezone` | `string \| null` | host local | IANA timezone for the cron expression. |
131
- | `tickBatchSize` | `number` | `100` | Max rows claimed per tick. |
132
- | `tickName` | `string` | `workflow.scheduler.<projectId>` | Cron job name. |
155
+ | Field | Type | Default | Description |
156
+ | ----------------- | ---------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
157
+ | `cron` | `Cron` | required | Externally-owned `Cron` instance. Scheduler registers its tick on this via `cron.register`. The consumer runs `cron.start()` / `cron.stop()`. |
158
+ | `workflow` | `Workflow` | required | The Workflow whose instances this scheduler wakes. `tenantId` and `db` are derived from it. |
159
+ | `tickExpression` | `string` | `"* * * * *"` | 5-field cron expression. |
160
+ | `timezone` | `string \| null` | host local | IANA timezone for the cron expression. |
161
+ | `tickBatchSize` | `number` | `100` | Max rows poked per tick, **per scan**. |
162
+ | `tickName` | `string` | `workflow.scheduler.<tenantId>` | Cron job name. |
163
+ | `stalePendingSec` | `number` | `300` | Age at which a `pending` instance is assumed stranded and re-poked with a fresh `start` advance. Covers the crash window between `create()`'s commit and steve's job insert (separate connection). `0` disables the scan. |
133
164
 
134
165
  #### Methods
135
166
 
136
167
  > **No `start()` or `stop()`.** The consumer manages the `Cron` lifecycle.
137
168
 
138
- | Method | Description |
139
- |---|---|
140
- | `register(): Promise<void>` | Registers the tick on the injected `Cron`. Call once after construction. Idempotent (re-registering preserves `next_run_at`). |
141
- | `unregister(): Promise<void>` | Removes the tick from the injected `Cron`. |
142
- | `tickOnce(): Promise<number>` | Runs one tick immediately. Returns rows woken. Exposed for tests and on-demand wakes. |
169
+ | Method | Description |
170
+ | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
171
+ | `register(): Promise<void>` | Registers the tick on the injected `Cron`. Call once after construction. Idempotent (re-registering preserves `next_run_at`). |
172
+ | `unregister(): Promise<void>` | Removes the tick from the injected `Cron`. |
173
+ | `tickOnce(): Promise<SchedulerTickResult>` | Runs one tick immediately. Exposed for tests and on-demand wakes. |
174
+
175
+ ```typescript
176
+ interface SchedulerTickResult {
177
+ woken: number; // due `waiting` rows poked with a `timeout` advance
178
+ repoked: number; // stranded `pending` rows poked with a `start` advance
179
+ }
180
+ ```
181
+
182
+ #### Per-tick behavior
183
+
184
+ Each tick is **read-only** against `__workflow_instances` and runs two scans:
185
+
186
+ 1. `waiting` rows with `wake_at <= now()` → one `workflow.advance` poke each, `{ kind: 'timeout', outcome: 'TIMEOUT', expected_seq: row.seq }`.
187
+ 2. If `stalePendingSec > 0`: `pending` rows older than that → `{ kind: 'start', expected_seq: row.seq }`.
188
+
189
+ The advance re-checks the precondition under the row lock (including that the timer really is due) and is what writes. So the counts are _pokes issued_, not instances moved, and a row poked but not yet advanced is simply poked again next tick — the fence turns the duplicate into a no-op. Nothing is stranded by a crash mid-tick.
143
190
 
144
191
  ---
145
192
 
@@ -158,27 +205,39 @@ import { Cron } from "@marianmeres/cron";
158
205
  new WorkflowInboxCorrelator(options: WorkflowInboxCorrelatorOptions)
159
206
  ```
160
207
 
161
- **`WorkflowInboxCorrelatorOptions`** has the same shape as `WorkflowSchedulerOptions` (cron / workflow / tickExpression / timezone / tickBatchSize / tickName), with `tickName` defaulting to `workflow.correlator.<projectId>`.
208
+ **`WorkflowInboxCorrelatorOptions`** takes the same fields as `WorkflowSchedulerOptions` minus `stalePendingSec` (cron / workflow / tickExpression / timezone / tickBatchSize / tickName), with `tickName` defaulting to `workflow.correlator.<tenantId>`.
162
209
 
163
210
  #### Methods
164
211
 
165
212
  > **No `start()` or `stop()`.** The consumer manages the `Cron` lifecycle.
166
213
 
167
- | Method | Description |
168
- |---|---|
169
- | `register(): Promise<void>` | Registers the tick on the injected `Cron`. Call once after construction. |
170
- | `unregister(): Promise<void>` | Removes the tick from the injected `Cron`. |
171
- | `tickOnce(): Promise<number>` | Runs one tick immediately. Returns signals processed. Exposed for tests and on-demand correlation. |
214
+ | Method | Description |
215
+ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
216
+ | `register(): Promise<void>` | Registers the tick on the injected `Cron`. Call once after construction. |
217
+ | `unregister(): Promise<void>` | Removes the tick from the injected `Cron`. |
218
+ | `tickOnce(): Promise<number>` | Runs one tick immediately. Returns rows **resolved** — poked, rejected, or marked processed. Deferred rows are not counted; they are still there next tick. |
172
219
 
173
220
  #### Per-tick behavior
174
221
 
175
- For each unprocessed inbox row (claimed via `FOR UPDATE SKIP LOCKED`):
222
+ Rows are claimed `ORDER BY received_at LIMIT tickBatchSize` with `FOR UPDATE SKIP LOCKED`. For each row, the correlator looks up the **live** (non-terminal) instance owning `correlation_token`:
176
223
 
177
- 1. Find a `waiting` instance with the same `correlation_token`. None → mark processed, done.
178
- 2. Resolve `meta.matcher` on the instance's current state. Missing matcher (string id) → unregistered matcher → `signal_rejected` history, mark processed.
179
- 3. Run the matcher with `{ instanceId, projectId, context, signal }`.
180
- 4. Matcher returns `false` → `signal_rejected` history, mark processed.
181
- 5. Matcher returns `true` → `signal_received` history, flip instance to `pending`, mark processed, enqueue advance with `outcome: 'MATCHED'` and `outcome_data: signal.payload`.
224
+ | Instance | Action |
225
+ | --------------------------------------------------- | ------------------------------------------------------------------------------------------ |
226
+ | none, or terminal | mark processed + warn log (plus `signal_rejected` history if a terminal instance is found) |
227
+ | live but not `waiting` | **defer** |
228
+ | `waiting` at a node with no `MATCHED` (or `*`) edge | **defer** |
229
+ | already poked earlier in this tick | **defer** |
230
+ | `waiting`, matcher throws | **defer** (error log) |
231
+ | `waiting`, matcher returns `false` | `signal_rejected` history, mark processed |
232
+ | `waiting`, matcher returns `true` (or no matcher) | poke an advance: `{ kind: 'signal', expected_seq, inbox_id }` |
233
+
234
+ **Defer** = leave the row unprocessed and look at it again next tick. An early signal — the instance is still running the step that emits the token, or sits at a timer-only node — is early, not wrong: consuming it would lose it, and delivering it to a node with no `MATCHED` edge would fail the instance.
235
+
236
+ The correlator **never writes the instance row** and never marks a delivered row processed. The advance does both: it locks the inbox row, reads `outcome_data` off it, transitions, appends `signal_received`, and marks it processed in one transaction. A crashed poke is simply re-poked next tick.
237
+
238
+ Pokes are enqueued _after_ the claiming transaction commits — the advance would otherwise block on the inbox lock this tick still holds.
239
+
240
+ Two known costs: a deterministically-throwing matcher retries and logs every tick, and a deferred backlog larger than `tickBatchSize` shadows newer rows.
182
241
 
183
242
  ---
184
243
 
@@ -204,15 +263,15 @@ Validates every definition against the registered handler/matcher names. Throws
204
263
 
205
264
  #### Methods
206
265
 
207
- | Method | Returns | Description |
208
- |---|---|---|
209
- | `getDefinition(id, version)` | `WorkflowDefinition \| undefined` | Lookup. |
210
- | `requireDefinition(id, version)` | `WorkflowDefinition` | Throws if missing. |
211
- | `getHandler(name)` | `Handler \| undefined` | Lookup. |
212
- | `requireHandler(name)` | `Handler` | Throws if missing. |
213
- | `getMatcher(name)` | `Matcher \| undefined` | Lookup. |
214
- | `requireMatcher(name)` | `Matcher` | Throws if missing. |
215
- | `handlerNames()` | `string[]` | All registered handler names. |
266
+ | Method | Returns | Description |
267
+ | -------------------------------- | --------------------------------- | ----------------------------- |
268
+ | `getDefinition(id, version)` | `WorkflowDefinition \| undefined` | Lookup. |
269
+ | `requireDefinition(id, version)` | `WorkflowDefinition` | Throws if missing. |
270
+ | `getHandler(name)` | `Handler \| undefined` | Lookup. |
271
+ | `requireHandler(name)` | `Handler` | Throws if missing. |
272
+ | `getMatcher(name)` | `Matcher \| undefined` | Lookup. |
273
+ | `requireMatcher(name)` | `Matcher` | Throws if missing. |
274
+ | `handlerNames()` | `string[]` | All registered handler names. |
216
275
 
217
276
  ---
218
277
 
@@ -227,6 +286,7 @@ import { createMigrate } from "@marianmeres/workflow";
227
286
  ```
228
287
 
229
288
  **Parameters:**
289
+
230
290
  - `pool` (`pg.Pool`) — required
231
291
  - `options.logger` (`(...args: unknown[]) => void`, optional) — passed through to `Migrate`
232
292
 
@@ -239,7 +299,7 @@ const migrate = createMigrate(pool);
239
299
  await migrate.up("latest");
240
300
  ```
241
301
 
242
- Active version is stored in `__workflow_migrations`. The migration creates `__workflow_instances`, `__workflow_inbox`, `__workflow_history` and their indexes.
302
+ Active version is stored in `__workflow_migrations`. `1.0.0` creates `__workflow_instances`, `__workflow_inbox`, `__workflow_history` and their indexes; `1.1.0` renames `project_id` → `tenant_id`; `1.2.0` adds the `seq` fencing column and the partial index behind the scheduler's stale-`pending` scan. Upgrading an existing 2.0.x database needs `up("latest")` once — until then instances have `seq = 0` and every write bumps it from there.
243
303
 
244
304
  ---
245
305
 
@@ -248,6 +308,7 @@ Active version is stored in `__workflow_migrations`. The migration creates `__wo
248
308
  Standalone validator. Throws on the first structural problem.
249
309
 
250
310
  **Parameters:**
311
+
251
312
  - `def` (`WorkflowDefinition`)
252
313
  - `available.handlers` (`ReadonlySet<string>`)
253
314
  - `available.matchers` (`ReadonlySet<string>`)
@@ -261,6 +322,11 @@ Checks performed:
261
322
  - Every `suspending` state's matcher (if present) is in `available.matchers`.
262
323
  - Every transition target resolves to a defined state.
263
324
  - At least one `terminal` state exists.
325
+ - Every node has an edge for the events it is guaranteed to receive — each of these would otherwise be rejected by the FSM at runtime, failing the instance after any side effect at that node had already run:
326
+ - `pure` → an `ENTER` (or `*`) transition.
327
+ - `effectful` → at least one transition, or every handler outcome is rejected.
328
+ - `suspending` → a `MATCHED` (or `*`) transition when `meta.matcher` is set; a `TIMEOUT` (or `*`) one when `meta.timeoutSec` is set; and at least one of the two, or the node can never wake. `timeoutSec`, when present, must be a finite number greater than `0`.
329
+ - `terminal` → no transitions at all.
264
330
 
265
331
  ---
266
332
 
@@ -285,6 +351,7 @@ Builds the steve job-type string for an effect handler.
285
351
  Reads the append-only history rows for an instance in chronological order. Useful for `/admin/workflows`-style observability views.
286
352
 
287
353
  **Parameters:**
354
+
288
355
  - `exec` (`pg.Pool | pg.PoolClient | pg.Client`)
289
356
  - `instanceId` (`string`)
290
357
  - `limit` (`number`, optional) — Default: `200`
@@ -297,7 +364,7 @@ Reads the append-only history rows for an instance in chronological order. Usefu
297
364
  import { getHistory } from "@marianmeres/workflow";
298
365
  const events = await getHistory(pool, instance.id);
299
366
  for (const e of events) {
300
- console.log(e.at.toISOString(), e.event_type, e.from_node, "→", e.to_node);
367
+ console.log(e.at.toISOString(), e.event_type, e.from_node, "→", e.to_node);
301
368
  }
302
369
  ```
303
370
 
@@ -308,35 +375,54 @@ for (const e of events) {
308
375
  ### `WorkflowDefinition`
309
376
 
310
377
  ```typescript
311
- type WorkflowDefinition<TState extends string = string, TEvent extends string = string> = {
312
- id: string;
313
- version: string;
314
- fsm: FSMConfig<TState, TEvent, WorkflowContext>;
315
- };
378
+ type WorkflowDefinition<TState extends string = string, TEvent extends string = string> =
379
+ {
380
+ id: string;
381
+ version: string;
382
+ fsm: WorkflowFSMConfig<TState, TEvent>;
383
+ };
316
384
  ```
317
385
 
318
386
  The `fsm` field is a [`@marianmeres/fsm`](https://jsr.io/@marianmeres/fsm) config. Each state config carries `meta: NodeMeta` — the FSM passes it through, the workflow driver dispatches on it.
319
387
 
320
388
  ---
321
389
 
390
+ ### `WorkflowFSMConfig` / `WorkflowStateConfig`
391
+
392
+ ```typescript
393
+ type WorkflowStateConfig<TState extends string = string, TEvent extends string = string> =
394
+ & FSMStatesConfigValue<TState, TEvent, WorkflowContext>
395
+ & { meta: NodeMeta };
396
+
397
+ type WorkflowFSMConfig<TState extends string = string, TEvent extends string = string> =
398
+ & Omit<FSMConfig<TState, TEvent, WorkflowContext>, "states">
399
+ & { states: Record<TState, WorkflowStateConfig<TState, TEvent>> };
400
+ ```
401
+
402
+ fsm's own per-state `meta` is `unknown`, so `{ kind: "efectful" }` would type-check and only blow up in `validateDefinition`. These two narrow it to [`NodeMeta`](#nodemeta) and make it required — you get autocomplete on `kind`, `handler`, `matcher` and `timeoutSec` while authoring.
403
+
404
+ Narrowing only: a `WorkflowFSMConfig` is still a valid `FSMConfig`, so anything that accepts one accepts a definition's `fsm`. The only definitions that stop compiling are those `validateDefinition` already rejected.
405
+
406
+ ---
407
+
322
408
  ### `NodeMeta`
323
409
 
324
410
  ```typescript
325
411
  type NodeMeta =
326
- | { kind: "pure" }
327
- | { kind: "effectful"; handler: string }
328
- | { kind: "suspending"; matcher?: string; timeoutSec?: number }
329
- | { kind: "terminal" };
412
+ | { kind: "pure" }
413
+ | { kind: "effectful"; handler: string }
414
+ | { kind: "suspending"; matcher?: string; timeoutSec?: number }
415
+ | { kind: "terminal" };
330
416
  ```
331
417
 
332
418
  Discriminated union of node kinds. The driver dispatches on `kind`:
333
419
 
334
- | Kind | Driver behavior |
335
- |---|---|
336
- | `pure` | Auto-fires `ENTER`. User wires guarded transitions. Inline-expands. |
337
- | `effectful` | Enqueues a steve job for `handler`. Waits for completion. |
420
+ | Kind | Driver behavior |
421
+ | ------------ | --------------------------------------------------------------------------------------- |
422
+ | `pure` | Auto-fires `ENTER`. User wires guarded transitions. Inline-expands. |
423
+ | `effectful` | Enqueues a steve job for `handler`. Waits for completion. |
338
424
  | `suspending` | Parks the instance. Wakes on `wake_at` (`TIMEOUT`) or matched inbox signal (`MATCHED`). |
339
- | `terminal` | Marks instance `completed`. |
425
+ | `terminal` | Marks instance `completed`. |
340
426
 
341
427
  ---
342
428
 
@@ -346,15 +432,17 @@ Discriminated union of node kinds. The driver dispatches on `kind`:
346
432
  type Handler = (args: HandlerArgs) => Promise<HandlerResult> | HandlerResult;
347
433
 
348
434
  interface HandlerArgs {
349
- instanceId: string;
350
- projectId: string;
351
- context: WorkflowContext;
352
- signal?: AbortSignal;
435
+ instanceId: string;
436
+ tenantId: string;
437
+ context: WorkflowContext;
438
+ signal?: AbortSignal;
353
439
  }
354
440
 
355
441
  interface HandlerResult {
356
- outcome: string;
357
- data?: Record<string, unknown>;
442
+ outcome: string;
443
+ data?: Record<string, unknown>;
444
+ correlationToken?: string | null;
445
+ context?: Partial<WorkflowContext>;
358
446
  }
359
447
  ```
360
448
 
@@ -362,6 +450,10 @@ Handlers are async functions referenced by string name from `effectful` node met
362
450
 
363
451
  The returned `outcome` is the FSM event name that drives the next transition. `data` is forwarded as the transition payload (available in guards/actions if the user wires them).
364
452
 
453
+ `context` is a shallow patch (top-level keys replace) merged into the instance context _before_ the outcome transition is applied, so guards and actions on the outcome edge already see it and it is persisted at the next settle point. `data` is never merged automatically — a handler that wants a value kept for later nodes returns it in `context`, instead of an fsm `action` that copies it out of the payload.
454
+
455
+ `correlationToken` sets the instance's token, written at the settle point this outcome leads to — so a wait point can key on something that only exists once the effect has run (an SMTP `Message-ID`, a payment-provider session id) and is signallable the moment it becomes `waiting`. `null` clears the token; omitting the field leaves whatever `create({ correlationToken })` set. The value is recorded in the `transition` history row's data.
456
+
365
457
  **Idempotency:** handlers can run multiple times in failure scenarios. Design them accordingly.
366
458
 
367
459
  ---
@@ -372,14 +464,14 @@ The returned `outcome` is the FSM event name that drives the next transition. `d
372
464
  type Matcher = (args: MatcherArgs) => boolean | Promise<boolean>;
373
465
 
374
466
  interface MatcherArgs {
375
- instanceId: string;
376
- projectId: string;
377
- context: WorkflowContext;
378
- signal: InboxRow;
467
+ instanceId: string;
468
+ tenantId: string;
469
+ context: WorkflowContext;
470
+ signal: InboxRow;
379
471
  }
380
472
  ```
381
473
 
382
- Matchers are predicate functions referenced from `suspending` node metas. The correlation token alone is just an index lookup — the matcher is the *semantic* gate.
474
+ Matchers are predicate functions referenced from `suspending` node metas. The correlation token alone is just an index lookup — the matcher is the _semantic_ gate.
383
475
 
384
476
  ---
385
477
 
@@ -387,36 +479,39 @@ Matchers are predicate functions referenced from `suspending` node metas. The co
387
479
 
388
480
  ```typescript
389
481
  interface WorkflowInstanceRow {
390
- id: string;
391
- project_id: string;
392
- definition_id: string;
393
- definition_version: string;
394
- cursor: string; // current FSM state
395
- previous_cursor: string | null; // feeds FSM.fromSnapshot's snapshot.previous
396
- context: WorkflowContext;
397
- execution_state: ExecutionState;
398
- wake_at: Date | null;
399
- correlation_token: string | null;
400
- created_at: Date;
401
- updated_at: Date;
482
+ id: string;
483
+ tenant_id: string;
484
+ definition_id: string;
485
+ definition_version: string;
486
+ cursor: string; // current FSM state
487
+ previous_cursor: string | null; // feeds FSM.fromSnapshot's snapshot.previous
488
+ context: WorkflowContext;
489
+ execution_state: ExecutionState;
490
+ wake_at: Date | null;
491
+ correlation_token: string | null;
492
+ seq: number; // fencing token
493
+ created_at: Date;
494
+ updated_at: Date;
402
495
  }
403
496
  ```
404
497
 
405
498
  Schema-aligned. `cursor` and `execution_state` are deliberately separate columns — see [Two Orthogonal States](./AGENTS.md#two-orthogonal-states).
406
499
 
500
+ `seq` is the fencing token (schema 1.2.0). Every settle-point write bumps it; jobs carry the value they were issued against, so a duplicate or zombie job is recognized and dropped instead of being applied to a row that has moved on.
501
+
407
502
  ---
408
503
 
409
504
  ### `InboxRow`
410
505
 
411
506
  ```typescript
412
507
  interface InboxRow {
413
- id: string;
414
- project_id: string;
415
- received_at: Date;
416
- source: string;
417
- correlation_token: string;
418
- payload: Record<string, unknown>;
419
- processed_at: Date | null;
508
+ id: string;
509
+ tenant_id: string;
510
+ received_at: Date;
511
+ source: string;
512
+ correlation_token: string;
513
+ payload: Record<string, unknown>;
514
+ processed_at: Date | null;
420
515
  }
421
516
  ```
422
517
 
@@ -426,14 +521,14 @@ interface InboxRow {
426
521
 
427
522
  ```typescript
428
523
  interface HistoryRow {
429
- id: number;
430
- project_id: string;
431
- instance_id: string;
432
- at: Date;
433
- event_type: HistoryEventType;
434
- from_node: string | null;
435
- to_node: string | null;
436
- data: Record<string, unknown>;
524
+ id: number;
525
+ tenant_id: string;
526
+ instance_id: string;
527
+ at: Date;
528
+ event_type: HistoryEventType;
529
+ from_node: string | null;
530
+ to_node: string | null;
531
+ data: Record<string, unknown>;
437
532
  }
438
533
  ```
439
534
 
@@ -444,33 +539,57 @@ interface HistoryRow {
444
539
  ### `AdvanceJobPayload` / `EffectJobPayload`
445
540
 
446
541
  ```typescript
542
+ type AdvanceKind = "start" | "effect" | "timeout" | "signal";
543
+
447
544
  interface AdvanceJobPayload {
448
- project_id: string;
449
- instance_id: string;
450
- outcome?: string;
451
- outcome_data?: Record<string, unknown>;
452
- timeout?: boolean;
545
+ tenant_id: string;
546
+ instance_id: string;
547
+ kind?: AdvanceKind;
548
+ expected_seq?: number;
549
+ outcome?: string;
550
+ outcome_data?: Record<string, unknown>;
551
+ inbox_id?: string;
552
+ handler?: string;
553
+ correlation_token?: string | null;
554
+ redispatch?: number;
453
555
  }
454
556
 
455
557
  interface EffectJobPayload {
456
- project_id: string;
457
- instance_id: string;
458
- handler: string;
558
+ tenant_id: string;
559
+ instance_id: string;
560
+ handler: string;
561
+ seq?: number;
562
+ cursor?: string;
563
+ redispatch?: number;
459
564
  }
460
565
  ```
461
566
 
462
- Steve job payloads. You don't normally construct these directly — `Workflow.create` and the scheduler/correlator do it for you.
567
+ Steve job payloads. You don't normally construct these directly — `Workflow.create`, the driver and the scheduler/correlator do it for you.
568
+
569
+ | Field | Meaning |
570
+ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
571
+ | `kind` | What produced this advance. Selects the precondition the driver checks under the row lock: `start` → `pending`, `effect` → `running`, `signal` → `waiting`, `timeout` → `waiting` **and** a `wake_at` in the past. |
572
+ | `expected_seq` / `seq` | The fence: the instance `seq` the job was issued against. The driver drops the job if the locked row has moved past it. On an effect job a row that is _behind_ the fence means the dispatching transaction has not committed yet — the job throws so steve retries. |
573
+ | `inbox_id` | `kind: "signal"` only. The advance reads the outcome data off that row and marks it processed in the same transaction as the transition. |
574
+ | `handler` | `kind: "effect"` only; used for the `effect_completed` history entry. |
575
+ | `correlation_token` | `kind: "effect"` only. The token the handler returned; written at this advance's settle point. `null` clears it, absent leaves the row's own value alone. |
576
+ | `cursor` | Node that dispatched the effect. Diagnostics only. |
577
+ | `redispatch` | How many times this payload has been re-queued after its job expired. Bounded by `redispatchLimit`; absent on a first dispatch. |
578
+
579
+ **Absent `kind` / `expected_seq` / `seq` means unfenced** — a job enqueued by 2.0.x and still queued at upgrade time. The driver infers the kind from the payload shape and skips both the fence and the preconditions rather than swallowing the job. A transitional shim; it will be removed together with the `project_id` fallback in a later major.
463
580
 
464
581
  ---
465
582
 
466
583
  ### Other re-exported types
467
584
 
468
- | Type | Description |
469
- |---|---|
470
- | `WorkflowContext` | `Record<string, unknown>` — accumulated payload carried in `__workflow_instances.context` |
471
- | `WorkflowSnapshot` | `FSMSnapshot<string, WorkflowContext>` — passthrough re-export for convenience |
472
- | `ExecutionState` | Union of execution-state strings |
473
- | `HistoryEventType` | Union of history-event-type strings |
585
+ | Type | Description |
586
+ | --------------------- | --------------------------------------------------------------------------------------------------------- |
587
+ | `WorkflowContext` | `Record<string, unknown>` — accumulated payload carried in `__workflow_instances.context` |
588
+ | `WorkflowSnapshot` | `FSMSnapshot<string, WorkflowContext>` — passthrough re-export for convenience |
589
+ | `ExecutionState` | Union of execution-state strings |
590
+ | `HistoryEventType` | Union of history-event-type strings |
591
+ | `AdvanceKind` | `"start" \| "effect" \| "timeout" \| "signal"` — see [job payloads](#advancejobpayload--effectjobpayload) |
592
+ | `SchedulerTickResult` | `{ woken, repoked }` — what one `WorkflowScheduler` tick poked |
474
593
 
475
594
  ---
476
595
 
@@ -480,12 +599,12 @@ Steve job payloads. You don't normally construct these directly — `Workflow.cr
480
599
 
481
600
  ```typescript
482
601
  const EXECUTION_STATE = {
483
- PENDING: "pending",
484
- RUNNING: "running",
485
- WAITING: "waiting",
486
- COMPLETED: "completed",
487
- FAILED: "failed",
488
- CANCELLED: "cancelled",
602
+ PENDING: "pending",
603
+ RUNNING: "running",
604
+ WAITING: "waiting",
605
+ COMPLETED: "completed",
606
+ FAILED: "failed",
607
+ CANCELLED: "cancelled",
489
608
  } as const;
490
609
  ```
491
610
 
@@ -493,29 +612,30 @@ const EXECUTION_STATE = {
493
612
 
494
613
  ```typescript
495
614
  const HISTORY_EVENT = {
496
- CREATED: "created",
497
- TRANSITION: "transition",
498
- EFFECT_DISPATCHED: "effect_dispatched",
499
- EFFECT_COMPLETED: "effect_completed",
500
- EFFECT_FAILED: "effect_failed",
501
- SIGNAL_RECEIVED: "signal_received",
502
- SIGNAL_REJECTED: "signal_rejected",
503
- TIMEOUT: "timeout",
504
- TRANSITION_REJECTED: "transition_rejected",
505
- COMPLETED: "completed",
506
- FAILED: "failed",
507
- CANCELLED: "cancelled",
615
+ CREATED: "created",
616
+ TRANSITION: "transition",
617
+ EFFECT_DISPATCHED: "effect_dispatched",
618
+ EFFECT_COMPLETED: "effect_completed",
619
+ EFFECT_FAILED: "effect_failed",
620
+ SIGNAL_RECEIVED: "signal_received",
621
+ SIGNAL_REJECTED: "signal_rejected",
622
+ TIMEOUT: "timeout",
623
+ TRANSITION_REJECTED: "transition_rejected",
624
+ COMPLETED: "completed",
625
+ FAILED: "failed",
626
+ CANCELLED: "cancelled",
627
+ RETRIED: "retried",
508
628
  } as const;
509
629
  ```
510
630
 
511
631
  ### Misc
512
632
 
513
- | Name | Value | Notes |
514
- |---|---|---|
515
- | `DEFAULT_PROJECT_ID` | `"_default"` | Used when `projectId` not supplied. Matches `@marianmeres/cron`'s default. |
516
- | `JOB_TYPE_ADVANCE` | `"workflow.advance"` | Steve job type for one driver step. |
517
- | `JOB_TYPE_EFFECT_PREFIX` | `"workflow.effect."` | Full type: `workflow.effect.<handlerName>`. |
518
- | `PURE_ENTER_EVENT` | `"ENTER"` | Synthetic event fired by the driver into pure nodes. Wire guarded transitions on this event. |
633
+ | Name | Value | Notes |
634
+ | ------------------------ | -------------------- | -------------------------------------------------------------------------------------------- |
635
+ | `DEFAULT_TENANT_ID` | `"_default"` | Used when `tenantId` not supplied. Matches `@marianmeres/cron`'s default. |
636
+ | `JOB_TYPE_ADVANCE` | `"workflow.advance"` | Steve job type for one driver step. |
637
+ | `JOB_TYPE_EFFECT_PREFIX` | `"workflow.effect."` | Full type: `workflow.effect.<handlerName>`. |
638
+ | `PURE_ENTER_EVENT` | `"ENTER"` | Synthetic event fired by the driver into pure nodes. Wire guarded transitions on this event. |
519
639
 
520
640
  ---
521
641