@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/AGENTS.md +207 -94
- package/API.md +277 -157
- package/README.md +182 -83
- package/dist/correlator.d.ts +31 -14
- package/dist/correlator.js +130 -73
- package/dist/definition.d.ts +5 -1
- package/dist/definition.js +54 -1
- package/dist/driver.d.ts +28 -23
- package/dist/driver.js +223 -59
- package/dist/migrations/1_1_0.d.ts +11 -0
- package/dist/migrations/1_1_0.js +61 -0
- package/dist/migrations/1_2_0.d.ts +16 -0
- package/dist/migrations/1_2_0.js +44 -0
- package/dist/migrations/index.js +5 -1
- package/dist/mod.d.ts +8 -5
- package/dist/mod.js +7 -4
- package/dist/persistence/history.d.ts +1 -1
- package/dist/persistence/history.js +3 -3
- package/dist/persistence/inbox.d.ts +9 -3
- package/dist/persistence/inbox.js +16 -7
- package/dist/persistence/instances.d.ts +46 -13
- package/dist/persistence/instances.js +78 -33
- package/dist/scheduler.d.ts +33 -9
- package/dist/scheduler.js +45 -21
- package/dist/types.d.ts +126 -13
- package/dist/types.js +28 -2
- package/dist/workflow.d.ts +76 -4
- package/dist/workflow.js +237 -35
- package/docs/_archive/analysis/00-overview-and-roadmap.md +233 -0
- package/docs/_archive/analysis/01-durability.md +404 -0
- package/docs/_archive/analysis/02-correlation.md +228 -0
- package/docs/_archive/analysis/03-definition-and-api.md +248 -0
- package/docs/_archive/analysis/04-docs-tests-ops.md +191 -0
- package/docs/_archive/analysis/PROGRESS.md +172 -0
- package/docs/_archive/analysis/README.md +38 -0
- package/package.json +8 -7
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
|
|
50
|
-
|
|
51
|
-
| `db`
|
|
52
|
-
| `jobs`
|
|
53
|
-
| `
|
|
54
|
-
| `definitions`
|
|
55
|
-
| `handlers`
|
|
56
|
-
| `matchers`
|
|
57
|
-
| `effectMaxAttempts`
|
|
58
|
-
| `effectMaxAttemptDurationMs` | `number`
|
|
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
|
-
|
|
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
|
|
67
|
-
|
|
68
|
-
| `db`
|
|
69
|
-
| `jobs`
|
|
70
|
-
| `
|
|
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
|
|
82
|
-
|
|
83
|
-
| `definitionId`
|
|
84
|
-
| `definitionVersion` | `string`
|
|
85
|
-
| `context`
|
|
86
|
-
| `correlationToken`
|
|
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 `
|
|
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)
|
|
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
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
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
|
|
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
|
|
126
|
-
|
|
127
|
-
| `cron`
|
|
128
|
-
| `workflow`
|
|
129
|
-
| `tickExpression`
|
|
130
|
-
| `timezone`
|
|
131
|
-
| `tickBatchSize`
|
|
132
|
-
| `tickName`
|
|
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
|
|
139
|
-
|
|
140
|
-
| `register(): Promise<void>`
|
|
141
|
-
| `unregister(): Promise<void>`
|
|
142
|
-
| `tickOnce(): Promise<
|
|
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`**
|
|
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
|
|
168
|
-
|
|
169
|
-
| `register(): Promise<void>`
|
|
170
|
-
| `unregister(): Promise<void>` | Removes the tick from the injected `Cron`.
|
|
171
|
-
| `tickOnce(): Promise<number>` | Runs one tick immediately. Returns
|
|
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
|
-
|
|
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
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
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
|
|
208
|
-
|
|
209
|
-
| `getDefinition(id, version)`
|
|
210
|
-
| `requireDefinition(id, version)` | `WorkflowDefinition`
|
|
211
|
-
| `getHandler(name)`
|
|
212
|
-
| `requireHandler(name)`
|
|
213
|
-
| `getMatcher(name)`
|
|
214
|
-
| `requireMatcher(name)`
|
|
215
|
-
| `handlerNames()`
|
|
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`.
|
|
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
|
-
|
|
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
|
-
|
|
313
|
-
|
|
314
|
-
|
|
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
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
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
|
|
335
|
-
|
|
336
|
-
| `pure`
|
|
337
|
-
| `effectful`
|
|
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`
|
|
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
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
435
|
+
instanceId: string;
|
|
436
|
+
tenantId: string;
|
|
437
|
+
context: WorkflowContext;
|
|
438
|
+
signal?: AbortSignal;
|
|
353
439
|
}
|
|
354
440
|
|
|
355
441
|
interface HandlerResult {
|
|
356
|
-
|
|
357
|
-
|
|
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
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
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
|
|
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
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
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
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
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
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
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
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
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
|
-
|
|
457
|
-
|
|
458
|
-
|
|
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
|
|
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
|
|
469
|
-
|
|
470
|
-
| `WorkflowContext`
|
|
471
|
-
| `WorkflowSnapshot`
|
|
472
|
-
| `ExecutionState`
|
|
473
|
-
| `HistoryEventType`
|
|
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
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
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
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
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
|
|
514
|
-
|
|
515
|
-
| `
|
|
516
|
-
| `JOB_TYPE_ADVANCE`
|
|
517
|
-
| `JOB_TYPE_EFFECT_PREFIX` | `"workflow.effect."` | Full type: `workflow.effect.<handlerName>`.
|
|
518
|
-
| `PURE_ENTER_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
|
|