@marianmeres/workflow 1.0.0 → 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/README.md CHANGED
@@ -27,19 +27,19 @@ Required peer: a PostgreSQL connection (`pg.Pool`).
27
27
  A workflow is a **finite state machine with durable, long-lived instances**. Three concepts kept rigorously separate:
28
28
 
29
29
  - **Definition** — Static, versioned, JSON-serializable graph of states. Pure data; handler/matcher ids are strings.
30
- - **Instance** — One running occurrence of a definition. Lives as a row in `__workflow_instances`. Carries a *cursor* (current node) and a separate *execution_state* (lifecycle status).
30
+ - **Instance** — One running occurrence of a definition. Lives as a row in `__workflow_instances`. Carries a _cursor_ (current node) and a separate _execution_state_ (lifecycle status).
31
31
  - **Driver** — The advance engine. Stateless. Loads an instance, applies an outcome, dispatches the next step. Implemented as a steve job handler.
32
32
 
33
33
  Each FSM state declares its **node kind** via `meta`:
34
34
 
35
- | Kind | When the driver sees this state |
36
- |---|---|
37
- | `pure` | Fire `ENTER` to route via guards. Inline-expand. |
38
- | `effectful` | Enqueue an effect handler job. Wait for completion. |
35
+ | Kind | When the driver sees this state |
36
+ | ------------ | ------------------------------------------------------------------------------------------------- |
37
+ | `pure` | Fire `ENTER` to route via guards. Inline-expand. |
38
+ | `effectful` | Enqueue an effect handler job. Wait for completion. |
39
39
  | `suspending` | Park the instance (`waiting`). Wake on `wake_at` (`TIMEOUT`) or matched inbox signal (`MATCHED`). |
40
- | `terminal` | Mark instance `completed`. |
40
+ | `terminal` | Mark instance `completed`. |
41
41
 
42
- The user's handler returns `{ outcome, data }`. The driver calls `fsm.transition(outcome, data)`. The transition table picks the next state. There is no AI nondeterminism inside the FSM logic — return a label, look up the next node.
42
+ The user's handler returns `{ outcome, data }`. The driver calls `fsm.transition(outcome, data)`. The transition table picks the next state. `data` is the transition payload only; a handler that wants a value kept for later nodes returns it in `context` — a shallow patch merged before the transition. There is no AI nondeterminism inside the FSM logic — return a label, look up the next node.
43
43
 
44
44
  ## Example
45
45
 
@@ -50,81 +50,90 @@ import pg from "pg";
50
50
  import { Jobs } from "@marianmeres/steve";
51
51
  import { Cron } from "@marianmeres/cron";
52
52
  import {
53
- createMigrate,
54
- Workflow,
55
- WorkflowInboxCorrelator,
56
- WorkflowScheduler,
57
- type WorkflowDefinition,
53
+ createMigrate,
54
+ Workflow,
55
+ type WorkflowDefinition,
56
+ WorkflowInboxCorrelator,
57
+ WorkflowScheduler,
58
58
  } from "@marianmeres/workflow";
59
59
 
60
60
  // 1. Define the workflow (pure data — handler/matcher names are strings)
61
61
  const stockReplenishment: WorkflowDefinition = {
62
- id: "stock_replenishment",
63
- version: "1.0.0",
64
- fsm: {
65
- initial: "detect_low_stock",
66
- states: {
67
- detect_low_stock: {
68
- meta: { kind: "effectful", handler: "checkInventory" },
69
- on: { LOW: "send_order", OK: "_end_ok" },
70
- },
71
- send_order: {
72
- meta: { kind: "effectful", handler: "sendOrderEmail" },
73
- on: { SENT: "await_reply", FAILED: "_end_failed" },
74
- },
75
- await_reply: {
76
- meta: { kind: "suspending", matcher: "matchEmailReply", timeoutSec: 60 },
77
- on: { MATCHED: "classify_reply", TIMEOUT: "_end_timeout" },
78
- },
79
- classify_reply: {
80
- meta: { kind: "effectful", handler: "aiClassifyReply" },
81
- on: { CONFIRMED: "write_order", DENIED: "_end_denied", UNKNOWN: "_end_unknown" },
82
- },
83
- write_order: {
84
- meta: { kind: "effectful", handler: "persistOrder" },
85
- on: { OK: "_end_ok" },
86
- },
87
- _end_ok: { meta: { kind: "terminal" }, on: {} },
88
- _end_failed: { meta: { kind: "terminal" }, on: {} },
89
- _end_timeout: { meta: { kind: "terminal" }, on: {} },
90
- _end_denied: { meta: { kind: "terminal" }, on: {} },
91
- _end_unknown: { meta: { kind: "terminal" }, on: {} },
92
- },
93
- },
62
+ id: "stock_replenishment",
63
+ version: "1.0.0",
64
+ fsm: {
65
+ initial: "detect_low_stock",
66
+ states: {
67
+ detect_low_stock: {
68
+ meta: { kind: "effectful", handler: "checkInventory" },
69
+ on: { LOW: "send_order", OK: "_end_ok" },
70
+ },
71
+ send_order: {
72
+ meta: { kind: "effectful", handler: "sendOrderEmail" },
73
+ on: { SENT: "await_reply", FAILED: "_end_failed" },
74
+ },
75
+ await_reply: {
76
+ meta: { kind: "suspending", matcher: "matchEmailReply", timeoutSec: 60 },
77
+ on: { MATCHED: "classify_reply", TIMEOUT: "_end_timeout" },
78
+ },
79
+ classify_reply: {
80
+ meta: { kind: "effectful", handler: "aiClassifyReply" },
81
+ on: {
82
+ CONFIRMED: "write_order",
83
+ DENIED: "_end_denied",
84
+ UNKNOWN: "_end_unknown",
85
+ },
86
+ },
87
+ write_order: {
88
+ meta: { kind: "effectful", handler: "persistOrder" },
89
+ on: { OK: "_end_ok" },
90
+ },
91
+ _end_ok: { meta: { kind: "terminal" }, on: {} },
92
+ _end_failed: { meta: { kind: "terminal" }, on: {} },
93
+ _end_timeout: { meta: { kind: "terminal" }, on: {} },
94
+ _end_denied: { meta: { kind: "terminal" }, on: {} },
95
+ _end_unknown: { meta: { kind: "terminal" }, on: {} },
96
+ },
97
+ },
94
98
  };
95
99
 
96
100
  // 2. Connect + migrate
97
- const pool = new pg.Pool({ /* ... */ });
101
+ const pool = new pg.Pool({/* ... */});
98
102
  await createMigrate(pool).up("latest");
99
103
 
100
104
  // 3. Construct the runtime: steve.Jobs + cron.Cron are owned by *you*. The
101
105
  // workflow framework attaches its handlers to them and the consumer owns
102
106
  // the start/stop lifecycle. Share them with your app's other job/cron work
103
107
  // if you want — they coexist by type/name on the same underlying tables.
104
- const jobs = new Jobs({ db: pool });
108
+ //
109
+ // `autoCleanup` is not optional in practice: it runs steve's reaper, which
110
+ // is the only thing that notices a job whose worker died mid-run. Without
111
+ // it such a job sits in `running` forever and its instance never moves
112
+ // again. See "Persistence Guarantees" below.
113
+ const jobs = new Jobs({ db: pool, autoCleanup: true });
105
114
  const cron = new Cron({ db: pool });
106
115
 
107
116
  // 4. Construct the Workflow. It registers `workflow.advance` + one
108
117
  // `workflow.effect.<name>` handler per registered handler on the injected
109
118
  // Jobs (via `jobs.setHandler`).
110
119
  const wf = new Workflow({
111
- db: pool,
112
- jobs,
113
- projectId: "default",
114
- definitions: [stockReplenishment],
115
- handlers: {
116
- checkInventory: async (args) => ({ outcome: "LOW", data: { stock: 3 } }),
117
- sendOrderEmail: async (args) => ({ outcome: "SENT", data: { messageId: "..." } }),
118
- aiClassifyReply: async (args) => ({ outcome: "CONFIRMED", data: {} }),
119
- persistOrder: async (args) => ({ outcome: "OK", data: { orderId: "..." } }),
120
- },
121
- matchers: {
122
- matchEmailReply: ({ signal }) => signal.source === "email",
123
- },
120
+ db: pool,
121
+ jobs,
122
+ tenantId: "default",
123
+ definitions: [stockReplenishment],
124
+ handlers: {
125
+ checkInventory: async (args) => ({ outcome: "LOW", data: { stock: 3 } }),
126
+ sendOrderEmail: async (args) => ({ outcome: "SENT", data: { messageId: "..." } }),
127
+ aiClassifyReply: async (args) => ({ outcome: "CONFIRMED", data: {} }),
128
+ persistOrder: async (args) => ({ outcome: "OK", data: { orderId: "..." } }),
129
+ },
130
+ matchers: {
131
+ matchEmailReply: ({ signal }) => signal.source === "email",
132
+ },
124
133
  });
125
134
 
126
135
  // 5. Attach the scheduler + correlator ticks to the injected Cron.
127
- const scheduler = new WorkflowScheduler({ cron, workflow: wf });
136
+ const scheduler = new WorkflowScheduler({ cron, workflow: wf });
128
137
  const correlator = new WorkflowInboxCorrelator({ cron, workflow: wf });
129
138
  await scheduler.register();
130
139
  await correlator.register();
@@ -135,18 +144,18 @@ await cron.start(2);
135
144
 
136
145
  // 7. Create an instance
137
146
  const instance = await wf.create({
138
- definitionId: "stock_replenishment",
139
- definitionVersion: "1.0.0",
140
- correlationToken: crypto.randomUUID(),
147
+ definitionId: "stock_replenishment",
148
+ definitionVersion: "1.0.0",
149
+ correlationToken: crypto.randomUUID(),
141
150
  });
142
151
 
143
152
  // 8. When an external signal arrives, append it to the inbox. The
144
153
  // correlator's next tick matches it to the waiting instance and fires
145
154
  // `MATCHED` on the FSM.
146
155
  await wf.appendInbox({
147
- source: "email",
148
- correlationToken: instance.correlation_token!,
149
- payload: { subject: "Re: order", body: "yes please" },
156
+ source: "email",
157
+ correlationToken: instance.correlation_token!,
158
+ payload: { subject: "Re: order", body: "yes please" },
150
159
  });
151
160
 
152
161
  // 9. Graceful shutdown — stop what you started.
@@ -154,6 +163,10 @@ await cron.stop();
154
163
  await jobs.stop();
155
164
  ```
156
165
 
166
+ There is a clickable version of all of this in [`example/`](./example): the same wiring,
167
+ a graph you can watch an instance walk, and a button for each way it can go wrong. See
168
+ [The interactive example](#the-interactive-example).
169
+
157
170
  ## How It Works
158
171
 
159
172
  ```
@@ -173,18 +186,23 @@ await jobs.stop();
173
186
  PostgreSQL
174
187
  ```
175
188
 
176
- The framework owns no runtime processes. It registers job and cron handlers on the `Jobs` and `Cron` instances you pass in; you call `start()` / `stop()` on them. This lets the workflow's jobs/crons coexist with your application's own — they share `__job` / `__cron` tables and coexist by `type` / `name`. Sharing one runtime per process is cheaper than running parallel pollers.
189
+ The framework owns no runtime processes. It registers job and cron handlers on the `Jobs` and `Cron` instances you pass in; you call `start()` / `stop()` on them. This lets the workflow's jobs/crons coexist with your application's own — they share `__job` / `__cron` tables and coexist by `type` / `name`. Sharing one runtime per process is cheaper than running parallel pollers — and safer: a `Jobs` or `Cron` that polls these tables without the workflow handlers attached silently noops the work it claims (see [Failure Modes](#failure-modes)).
177
190
 
178
- A single steve job type — **`workflow.advance`** — encapsulates one step of the driver. Its payload is `{ project_id, instance_id, outcome?, outcome_data? }`. The handler:
191
+ A single steve job type — **`workflow.advance`** — encapsulates one step of the driver. Its payload is `{ tenant_id, instance_id, kind, expected_seq, outcome?, outcome_data?, inbox_id? }`. The handler:
179
192
 
180
193
  1. Locks the instance row inside a transaction.
181
- 2. If an `outcome` was supplied (wake from effect / signal / timer), applies it via `fsm.transition(outcome, data)`. If the FSM rejects, the instance is marked `failed`.
182
- 3. Loops on the current state's `meta.kind`, settling at the first terminal / effectful / suspending state and persisting the new cursor + execution_state in the same transaction.
183
- 4. For effectful nodes, enqueues a **`workflow.effect.<handlerName>`** steve job. On its success, the effect handler enqueues a fresh advance carrying the outcome. On terminal failure, the instance is marked `failed`.
194
+ 2. Drops the job if the instance is already terminal, if `expected_seq` no longer matches the row's `seq` (the fence — see below), or if the row is not in the state this `kind` of advance expects.
195
+ 3. If an `outcome` was supplied (wake from effect / signal / timer), applies it via `fsm.transition(outcome, data)`. If the FSM rejects, the instance is marked `failed`.
196
+ 4. Loops on the current state's `meta.kind`, settling at the first terminal / effectful / suspending state and persisting the new cursor + execution_state — and bumping `seq` — in the same transaction.
197
+ 5. For effectful nodes, enqueues a **`workflow.effect.<handlerName>`** steve job carrying that new `seq`. On its success, the effect handler enqueues a fresh advance carrying the outcome. On terminal failure, the instance is marked `failed`.
198
+
199
+ **The advance is the only writer of instance rows** (bar the job-failure hooks and the `cancel` / `retry` admin calls, which settle a row directly and bump `seq` with it). Everything else — the scheduler, the correlator — only _pokes_: it reads what looks due and enqueues an advance for it. A poke that is lost to a crash costs nothing, because whatever made the row look due is still true next tick; a poke that arrives twice costs nothing, because the second one is fenced out.
200
+
201
+ The **fence** is the `seq` column. Every settle-point write bumps it, and every advance/effect job carries the value it was issued against. A job whose value no longer matches belongs to a step the instance has already left — a duplicate, or a zombie from a worker that hung — and is dropped with a debug log rather than applied to a row that moved on.
184
202
 
185
- The **scheduler** runs as a registered cron job (default `* * * * *`). Each tick atomically flips `waiting` + `wake_at <= now()` rows to `pending`, clears `wake_at`, and enqueues a `workflow.advance` with `outcome: 'TIMEOUT'`.
203
+ The **scheduler** runs as a registered cron job (default `* * * * *`). Each tick is read-only: it selects `waiting` rows whose `wake_at` has passed and pokes one `TIMEOUT` advance per row (the advance re-checks due-ness under the lock and clears `wake_at`). A second scan pokes instances stuck in `pending` for longer than `stalePendingSec` — the residue of a crash between `create()`'s commit and steve's job insert, which happens on its own connection.
186
204
 
187
- The **correlator** runs as a registered cron job (default `* * * * *`). Each tick claims a batch of unprocessed `__workflow_inbox` rows, finds the waiting instance with the matching `correlation_token`, runs the user's `matcher` for the current state, and enqueues a `workflow.advance` with `outcome: 'MATCHED'` plus the signal payload.
205
+ The **correlator** runs as a registered cron job (default `* * * * *`). Each tick claims a batch of unprocessed `__workflow_inbox` rows, finds the live instance owning the `correlation_token`, runs the user's `matcher` for the current state, and pokes a `MATCHED` advance carrying the _inbox row id_. The advance re-reads that row under a lock and marks it processed in the same transaction as the transition, so a signal is never consumed without being delivered.
188
206
 
189
207
  ## Versioning Definitions
190
208
 
@@ -192,18 +210,43 @@ Each instance row stores `definition_version`. The framework looks up the defini
192
210
 
193
211
  ## Persistence Guarantees & Idempotency
194
212
 
195
- - The advance step is a single PG transaction: cursor / execution_state / wake_at / history are all written together with the effect-job insert.
196
- - Steve retries effect handlers per `effectMaxAttempts`. A worker crash mid-effect leaves the job in `running`; steve auto-cleanup reaps it after `~5min` and retries.
197
- - **Handlers must be idempotent.** A handler can run multiple times for the same instance if a worker crashes after the side effect but before steve records completion. Use upserts, idempotency keys, or check the existing state.
213
+ - **The instance write is one PG transaction.** Cursor, execution_state, wake_at, `seq` and history are written together, and a signal delivery marks its inbox row processed in that same transaction. The follow-up _job_ insert is not part of it: steve creates jobs on its own connection, so a job can exist for a transaction that ended up rolling back.
214
+ - **Job delivery is therefore at-least-once, and fenced.** A duplicate advance or effect job is recognized by `seq` and dropped. The fence is what makes the extra deliveries harmless, not their absence. `seq` arrives with schema 1.2.0 — run `createMigrate(pool).up("latest")` when upgrading.
215
+ - **Handlers must be idempotent.** The fence protects the _instance row_, not the outside world. A handler can still run twice — a worker that completed the side effect and then died before steve recorded the attempt gets retried. Use upserts, idempotency keys, or check the existing state.
216
+ - **Run `Jobs` with `autoCleanup: true`** (or call `jobs.cleanup()` periodically). Steve's reaper is the only thing that marks a job whose worker died as `expired`; without it that job stays `running` forever and its instance never moves again. With it, the framework re-queues the identical payload up to `redispatchLimit` times before giving up and failing the instance — the fence makes the re-queue a no-op if the dead worker's transaction did commit.
217
+ - **A `pending` instance is re-poked** after `stalePendingSec` (default 300s), which covers the crash window between `create()`'s commit and steve's job insert.
218
+
219
+ ## Signals: early, late, deferred
220
+
221
+ `appendInbox` never blocks on the instance being ready for the signal. What the correlator does with a row depends on what it finds behind the token:
222
+
223
+ | Situation | What happens |
224
+ | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
225
+ | Instance is `waiting` at a node that accepts `MATCHED`, matcher says yes | Advance poked; `signal_received` + the transition commit with the row's `processed_at` |
226
+ | Matcher says no | `signal_rejected` history; row marked processed |
227
+ | Matcher throws | Row deferred — re-examined next tick, with an error log |
228
+ | Instance is live but not `waiting` yet (still running the step that emits the token) | Row deferred |
229
+ | Instance is `waiting` at a node with no `MATCHED` edge (e.g. a timer-only delay) | Row deferred |
230
+ | No live instance owns the token, or the one that did has failed | Row marked processed with a warn log (plus `signal_rejected` history if a terminal instance exists) |
231
+
232
+ "Deferred" means the row stays unprocessed and is looked at again on the next tick — an early signal is early, not wrong. Only one signal per instance is poked per tick; the rest defer, because a second one would be fenced out anyway.
233
+
234
+ Two consequences worth knowing: a deferred row is retried indefinitely (a permanently-throwing matcher logs on every tick), and rows are claimed `ORDER BY received_at LIMIT tickBatchSize`, so a deferred backlog larger than the batch would shadow newer rows.
198
235
 
199
236
  ## Failure Modes
200
237
 
201
- | Failure | Behavior |
202
- |---|---|
203
- | Effect handler throws repeatedly | Instance marked `failed`; `effect_failed` history entry. |
204
- | FSM rejects the outcome label | Instance marked `failed`; `transition_rejected` history entry. |
205
- | Pure node with no guard matching | Instance marked `failed`; `transition_rejected` history entry. |
206
- | Definition missing on advance | Instance marked `failed`. Keep old versions registered until drained. |
238
+ | Failure | Behavior |
239
+ | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
240
+ | Effect handler throws repeatedly | Steve retries the job `effectMaxAttempts` times, then the instance is marked `failed`; `effect_failed` history entry. |
241
+ | Advance job throws repeatedly | Steve retries the job `advanceMaxAttempts` times (default 10, ~17min of backoff), then the instance is marked `failed` with the last attempt's error message. |
242
+ | Worker dies mid-job | Steve's reaper (needs `autoCleanup`) marks the job `expired` — steve never retries those. The framework re-queues the identical payload, up to `redispatchLimit` dispatches in total, then fails the instance. |
243
+ | Lost advance: the side effect happened but the follow-up advance was never enqueued | The effect job is retried (if the enqueue threw) or re-dispatched after expiry (if the process died). Either way the handler runs again — the instance never left that `seq`, so the fence lets it through — and the advance is enqueued. **This is why handlers must be idempotent.** |
244
+ | FSM rejects the outcome label | Instance marked `failed`; `transition_rejected` history entry. |
245
+ | Pure node with no guard matching | Instance marked `failed`; `transition_rejected` history entry. |
246
+ | Definition missing on advance | Instance marked `failed`. Keep old versions registered until drained. |
247
+ | A `failed` instance you want back | `wf.retry(id)` puts it back to `pending` at its current cursor and re-runs that node — no new instance, no replay of the effects it already did. `wf.retry(id, { force: true })` covers a `running` one whose worker died. Nothing is fixed by retrying alone: fix the cause first. |
248
+ | An instance that should not finish at all | `wf.cancel(id, reason?)` marks it `cancelled` (terminal) and drops its timer and its correlation token. Jobs already in flight for it are fenced out — a queued effect job skips its handler rather than firing the side effect. |
249
+ | A second `Jobs` or `Cron` in a process that never registered the workflow handlers | **Silent data loss.** Both libraries fall back to a noop for an unknown `type` / `name`: steve marks the job completed, cron marks the tick run and advances `next_run_at`. Share one runtime per process, or make sure every process that starts a `Jobs`/`Cron` on these tables also constructs the `Workflow` and calls `register()`. |
207
250
 
208
251
  ## Observability
209
252
 
@@ -216,7 +259,63 @@ const events = await getHistory(pool, instanceId);
216
259
 
217
260
  ## Multi-tenancy
218
261
 
219
- Pass `projectId` to `Workflow`, `WorkflowScheduler`, and `WorkflowInboxCorrelator`. All three tables (and Cron's internal tables) carry `project_id`. One process can scope workers to a tenant while another scopes to a different tenant; the `FOR UPDATE SKIP LOCKED` claiming keeps them disjoint.
262
+ Pass `tenantId` to `Workflow`, `WorkflowScheduler`, and `WorkflowInboxCorrelator`. All three tables (and Cron's internal tables) carry `tenant_id`, so instances, inbox rows, history, and the tick registrations are scoped: a `Workflow` only ever sees its own tenant's rows.
263
+
264
+ **The queues are not scoped, though.** Both steve and cron claim the next due row globally — no tenant filter, no type filter — and both fall back to a noop for work they have no handler for. So running one process per tenant against a shared database does _not_ isolate them: process A will claim process B's jobs and cron ticks, and silently noop the ones whose handler it does not have. That is safe only when every such process registers the _same_ definitions, handlers, and ticks (which makes the per-process scoping pointless anyway).
265
+
266
+ The supported shape today is one runtime per database, serving whichever tenants it has definitions for. Tenant scoping is for keeping data apart, not for partitioning workers.
267
+
268
+ ## Breaking changes in 2.0
269
+
270
+ - **`project_id` renamed to `tenant_id` throughout**, aligning with the
271
+ ecosystem's tenant-scoping convention (`@marianmeres/cron`,
272
+ `@marianmeres/steve`). This covers the DB column on all three tables, the
273
+ `tenant_id` field on `WorkflowInstanceRow` / `InboxRow` / `HistoryRow`, the
274
+ `tenantId` option on `Workflow` / `WorkflowScheduler` /
275
+ `WorkflowInboxCorrelator`, the `tenantId` key in `HandlerArgs` / `MatcherArgs`,
276
+ the `tenant_id` key in `AdvanceJobPayload` / `EffectJobPayload`, and the
277
+ `DEFAULT_TENANT_ID` export (was `DEFAULT_PROJECT_ID`).
278
+
279
+ Run `createMigrate(pool).up("latest")` once on upgrade. Schema version 1.1.0
280
+ renames the column in place on all three tables, preserving existing data. It
281
+ is idempotent, and `down("1.0.0")` reverses it.
282
+
283
+ Jobs enqueued by 1.0.x carry the old `project_id` key in their steve payload.
284
+ The driver reads either key, so anything already queued at upgrade time drains
285
+ normally. That fallback is a transitional shim and will be removed in a later
286
+ major.
287
+
288
+ - **Requires `@marianmeres/cron` 3.x**, which performed the same rename on its
289
+ own tables. If you are upgrading an existing database, run its migration once
290
+ too — the cron tick registrations otherwise fail against the legacy column:
291
+
292
+ ```typescript
293
+ import { Cron } from "@marianmeres/cron";
294
+ await Cron.migrate(pool);
295
+ ```
296
+
297
+ Fresh installs need no action. `@marianmeres/steve` 3.x self-heals its own
298
+ schema on init, so it needs nothing either.
299
+
300
+ ## The interactive example
301
+
302
+ A control panel for one workflow instance: create it, approve it, reject it, let its timer
303
+ run out, hand it a signal its matcher declines, break the effect that books it, cancel it,
304
+ retry it — and watch the graph, the history and the inbox as each of those lands.
305
+
306
+ ```sh
307
+ createdb example_workflow # or point EXAMPLE_PG_* at a database you already have
308
+ deno task example # → http://127.0.0.1:8000
309
+ ```
310
+
311
+ The highlighted node is the cursor; the badge on it is the execution state. The countdown
312
+ is `wake_at`. The tick panel switches the scheduler and correlator to manual, so you can
313
+ watch the poke model one press at a time — and since every field on the page was read back
314
+ out of PostgreSQL, stopping the server mid-wait and starting it again changes nothing.
315
+
316
+ See [`example/`](./example) — the workflow itself (definition, handlers, matcher) is
317
+ [`example/workflow.ts`](./example/workflow.ts), which is the shortest complete answer to
318
+ "what does userland actually write?".
220
319
 
221
320
  ## API
222
321
 
@@ -16,22 +16,35 @@ export interface WorkflowInboxCorrelatorOptions {
16
16
  timezone?: string | null;
17
17
  /** Maximum number of inbox rows claimed per tick. Default: 100. */
18
18
  tickBatchSize?: number;
19
- /** Custom name for the registered cron job. Default: `workflow.correlator.<projectId>`. */
19
+ /** Custom name for the registered cron job. Default: `workflow.correlator.<tenantId>`. */
20
20
  tickName?: string;
21
21
  }
22
22
  /**
23
- * Cron-driven correlator that matches `__workflow_inbox` rows to waiting
24
- * workflow instances. On each tick:
23
+ * Cron-driven correlator that matches `__workflow_inbox` rows to workflow
24
+ * instances. On each tick it claims a batch of unprocessed rows
25
+ * (`FOR UPDATE SKIP LOCKED`) and, per row, finds the live instance owning the
26
+ * correlation token:
25
27
  *
26
- * 1. Claim a batch of unprocessed inbox rows (`FOR UPDATE SKIP LOCKED`).
27
- * 2. For each row, find a waiting instance with the same correlation_token.
28
- * 3. Resolve the instance's current-state `meta.matcher` (if any), call it
29
- * against the signal. The matcher is the semantic filter — the token is
30
- * just the index lookup.
31
- * 4. On match: enqueue an advance with `outcome: 'MATCHED'` carrying the
32
- * signal payload, mark the inbox row processed, history entry.
33
- * 5. On no-match (or no waiting instance): mark inbox row processed with
34
- * `signal_rejected` history entry against the instance (if there was one).
28
+ * | Instance | Action |
29
+ * | ----------------------------------------------- | --------------------------------------------------- |
30
+ * | none / terminal | mark processed (+ `signal_rejected` if terminal) |
31
+ * | live but not `waiting` | defer |
32
+ * | `waiting` at a node that has no `MATCHED` edge | defer |
33
+ * | `waiting`, matcher says no | `signal_rejected`, mark processed |
34
+ * | `waiting`, matcher says yes | poke an advance; the advance does the rest |
35
+ *
36
+ * "Defer" means: leave the row unprocessed and look at it again next tick. A
37
+ * signal that arrives before its wait point — the instance is still running the
38
+ * step that emits the token, or sits at a timer-only node — is early, not
39
+ * wrong; consuming it would lose it, and delivering it to a node with no
40
+ * `MATCHED` edge would fail the instance.
41
+ *
42
+ * The correlator only pokes: it never writes the instance row. The advance
43
+ * transitions the instance, records `signal_received` and marks the inbox row
44
+ * processed in one transaction, so a crashed poke is simply re-poked next tick.
45
+ *
46
+ * Starvation note: rows are claimed `ORDER BY received_at LIMIT tickBatchSize`,
47
+ * so a backlog of deferred rows larger than the batch would shadow newer ones.
35
48
  *
36
49
  * Like {@link WorkflowScheduler}, the correlator does not own its `Cron`. The
37
50
  * caller constructs a `Cron`, passes it in, runs its lifecycle. Call
@@ -40,7 +53,7 @@ export interface WorkflowInboxCorrelatorOptions {
40
53
  export declare class WorkflowInboxCorrelator {
41
54
  #private;
42
55
  readonly cron: Cron;
43
- readonly projectId: string;
56
+ readonly tenantId: string;
44
57
  readonly tickExpression: string;
45
58
  readonly tickName: string;
46
59
  constructor(options: WorkflowInboxCorrelatorOptions);
@@ -51,6 +64,10 @@ export declare class WorkflowInboxCorrelator {
51
64
  register(): Promise<void>;
52
65
  /** Removes the tick from the injected `Cron`. */
53
66
  unregister(): Promise<void>;
54
- /** Runs one tick immediately. Exposed for testing and on-demand matches. */
67
+ /**
68
+ * Runs one tick immediately. Exposed for testing and on-demand matches.
69
+ * Returns the number of rows resolved — poked, rejected or marked processed.
70
+ * Deferred rows are not counted; they are still there next tick.
71
+ */
55
72
  tickOnce(): Promise<number>;
56
73
  }