@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.
@@ -0,0 +1,248 @@
1
+ <!--
2
+ GENERATED ANALYSIS — @marianmeres/workflow (definitions, registry, public API)
3
+ Produced 2026-08-26 by an inline single-agent review: full read of src/, tests/, docs, and the
4
+ resolved sources of @marianmeres/fsm 3.1.0, steve 3.0.0, cron 3.2.0 → self-verification pass
5
+ re-opening every cited line. Claims verified against the codebase at commit 02a7635.
6
+ Planning artifact; no code was changed.
7
+ -->
8
+
9
+ # Definitions, Registry & Public API
10
+
11
+ > This is the part of the package that is genuinely well done and needs no rethinking:
12
+ > pure-data definitions with string handler references, construction-time validation
13
+ > (`definition.ts:16–139`), pin-and-freeze versioning keyed by `id@version`, `meta`
14
+ > passthrough via fsm 3.1's `getCurrentMeta` (`fsm.ts:847–858`), and a correct resume via
15
+ > `fromSnapshot` that skips `onEnter` (`fsm.ts:1005–1048`). No findings against the design.
16
+
17
+ > The single most important takeaway: the gaps are edges a first real workflow will hit
18
+ > within a day. The validator accepts definitions that are _guaranteed_ to fail at runtime
19
+ > (a `pure` node with no `ENTER` edge, a `timeoutSec` with no `TIMEOUT` edge). `create()`
20
+ > ignores the definition's own `context` defaults. Two `Workflow`s on one `Jobs` overwrite
21
+ > each other's `workflow.advance` handler without a word. And `meta` is `unknown` while you
22
+ > type it.
23
+
24
+ > Headline recommendation: four small additive changes (validator rules, context seeding, a
25
+ > double-attach guard, typed `meta`) and two decisions for the owner — whether one runtime
26
+ > should serve many tenants in one process, and whether handlers may patch context without
27
+ > an fsm `action` per edge.
28
+
29
+ ## Summary of recommendations
30
+
31
+ | # | Recommendation | Value | Effort | Risk |
32
+ | - | ------------------------------------------------------------------------------- | ----- | ------ | -------------------------- |
33
+ | 1 | Validator: reject definitions that must fail at runtime | med | S | low |
34
+ | 2 | `create()` seeds context from `def.fsm.context` | med | S | low |
35
+ | 3 | Guard against two `Workflow`s on one `Jobs`; (decision) tenant-per-call runtime | med | S (+M) | low (+med for the runtime) |
36
+ | 4 | Opt-in `HandlerResult.context` patch (decision) | med | S | low |
37
+ | 5 | Typed `meta` in `WorkflowDefinition` | low | S | low — trivially cheap |
38
+
39
+ ## Findings & recommendations (detailed)
40
+
41
+ ### 1. The validator misses guaranteed runtime failures
42
+
43
+ - **Problem / observation.** `validateDefinition` checks handler/matcher names and that
44
+ every transition _target_ exists, but never that the _events_ a node will receive have
45
+ an edge. `case "pure": break;` (`definition.ts:62–63`); suspending checks the matcher
46
+ name only (`:80–97`); the transition loop validates targets (`:108–130`). Each of these
47
+ fails deterministically at runtime, after side effects may already have run:
48
+
49
+ | Definition | Runtime |
50
+ | ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
51
+ | `pure` node without `on.ENTER` (or `*`) | `transition_rejected` + `failed` on entry (`driver.ts:258–273`) |
52
+ | `suspending` with `timeoutSec`, no `TIMEOUT` | scheduler fires `TIMEOUT` → rejected → `failed` (`driver.ts:151–165`) |
53
+ | `suspending` with `matcher`, no `MATCHED` | today: `failed` on the first signal; after 02 #1: deferred forever — silent instead |
54
+ | `suspending` with neither `timeoutSec` nor a `MATCHED` edge | can never wake — sleeps forever |
55
+ | `effectful` with `on: {}` | every outcome rejected → `failed` |
56
+
57
+ - **Evidence.** `definition.ts:60–63`:
58
+ ```ts
59
+ const kind = (meta as { kind?: string }).kind;
60
+ switch (kind) {
61
+ case "pure":
62
+ break;
63
+ ```
64
+
65
+ - **Proposed change.** Add, in the existing message style (`"${def.id}@${def.version}":
66
+ state "${stateName}" …`):
67
+ - `pure` → `on.ENTER` or `on["*"]` must exist.
68
+ - `effectful` → `on` must have at least one event.
69
+ - `suspending` → `timeoutSec` present ⇒ `TIMEOUT` or `*`; `matcher` present ⇒ `MATCHED`
70
+ or `*`; at least one of (`timeoutSec`, a `MATCHED`/`*` edge) must exist;
71
+ `timeoutSec`, when present, must be a finite number `> 0`.
72
+ - `terminal` → `on` must be empty (a terminal with edges is a contradiction; the fixtures
73
+ already write `on: {}`).
74
+
75
+ - **Done when** — `tests/validator.test.ts` (new) has one failing definition per rule above
76
+ and asserts the thrown message; the existing fixtures still validate.
77
+
78
+ - **Affected files.** `src/definition.ts`, `tests/validator.test.ts` (new), `API.md`
79
+ (`validateDefinition` → "Checks performed").
80
+
81
+ - **Effort / Value / Risk.** S / med / low. Can only reject definitions that would have
82
+ failed at runtime.
83
+
84
+ ### 2. `create()` ignores the definition's `context` defaults
85
+
86
+ - **Problem / observation.** `create()` seeds `context: input.context ?? {}`
87
+ (`workflow.ts:192`). fsm supports `context?: TContext | (() => TContext)` (`fsm.ts:69`)
88
+ and builds it in `#initContext` (`:354–362`) — but the driver only ever constructs
89
+ machines via `fromSnapshot`, which takes the snapshot's context verbatim (`fsm.ts:1039`).
90
+ `def.fsm.context` is never read anywhere in `src/`. A definition declaring
91
+ `context: () => ({ attempts: 0 })` starts with `{}`, and a guard reading
92
+ `ctx.attempts < 3` compares `undefined`.
93
+
94
+ - **Evidence.** `workflow.ts:187–194`:
95
+ ```ts
96
+ const row = await createInstance(this.db, {
97
+ ...
98
+ cursor: def.fsm.initial,
99
+ context: input.context ?? {},
100
+ ```
101
+
102
+ - **Proposed change.** In `create()`:
103
+ ```ts
104
+ const base = typeof def.fsm.context === "function"
105
+ ? def.fsm.context()
106
+ : structuredClone(def.fsm.context ?? {});
107
+ const context = { ...base, ...(input.context ?? {}) }; // shallow; document it
108
+ ```
109
+
110
+ - **Done when** — test: a definition with `context: () => ({ n: 1, s: "x" })` and
111
+ `create({ context: { s: "y" } })` → `row.context` deep-equals `{ n: 1, s: "y" }`; a
112
+ definition without `context` behaves as before.
113
+
114
+ - **Affected files.** `src/workflow.ts`, `tests/` (a case in the driver test file from
115
+ 04 #3 or its own), `API.md` (`create` table: `context` "merged over the definition's
116
+ defaults").
117
+
118
+ - **Effort / Value / Risk.** S / med / low. Behavior changes only for definitions that
119
+ declare `context` — which are silently ignored today.
120
+
121
+ ### 3. Two `Workflow`s on one `Jobs` overwrite each other; one tenant per runtime
122
+
123
+ - **Problem / observation.** The constructor does `jobs.setHandler(JOB_TYPE_ADVANCE, …)`
124
+ (`workflow.ts:99–110`); steve's `setHandler` assigns into a map — last writer wins
125
+ (`jobs.ts:625–632`) — while `onDone` subscriptions accumulate (`jobs.ts:1045–1051`). A
126
+ second `Workflow` on the same `Jobs` (another tenant, or another set of definitions)
127
+ routes _every_ `workflow.advance` job through the second registry; the first's instances
128
+ fail one by one with `Unknown definition …` (`driver.ts:122–132`). Nothing warns.
129
+ `README.md:219` steers toward one process per tenant, but the in-process case is the
130
+ natural shape for a small multi-tenant app — and this package's ecosystem is built
131
+ around `tenant_id` everywhere.
132
+
133
+ - **Evidence.** `jobs.ts:625–632`:
134
+ ```ts
135
+ setHandler(type, handler) {
136
+ if (typeof handler === "function") this.#jobHandlers[type] = handler;
137
+ ```
138
+
139
+ - **Proposed change.**
140
+ **(a) Guard (small, do it):** a module-level `WeakMap<Jobs, Workflow>`; the constructor
141
+ throws `Workflow: a Workflow is already attached to this Jobs instance` on a second
142
+ attach. Add `detach()` — `setHandler(type, null)` for `workflow.advance` and every effect
143
+ type, unsubscribe the `onDone` listeners (steve returns unsubscribers), clear the map
144
+ entry — so tests and hot-reload setups can re-attach.
145
+ **(b) Tenant-per-call runtime (decision):** make the tenant a per-call concern so one
146
+ `Workflow` serves many tenants — `create({ tenantId? })`, `appendInbox({ tenantId? })`,
147
+ `find(id, { tenantId? })`, `cancel`/`retry` likewise, defaulting to the constructor's
148
+ `tenantId`; `WorkflowScheduler`/`WorkflowInboxCorrelator` gain
149
+ `tenantId?: string | "*"` (`"*"` = all tenants; tick name `workflow.scheduler`). The job
150
+ payloads already carry `tenant_id`, the driver is tenant-agnostic, the registry is
151
+ shared, the tables are tenant-keyed. Purely additive.
152
+
153
+ - **Done when** — (a) test: a second `new Workflow({ jobs, … })` throws; after
154
+ `wf.detach()` it succeeds. (b) test: one `Workflow`, `create({ tenantId: "a" })` and
155
+ `create({ tenantId: "b" })`, a scheduler with `tenantId: "*"` wakes both; `find` with
156
+ the wrong tenant returns `null`.
157
+
158
+ - **Affected files.** (a) `src/workflow.ts`, `API.md`. (b) additionally
159
+ `src/scheduler.ts`, `src/correlator.ts`, `src/persistence/instances.ts`,
160
+ `src/persistence/inbox.ts`, `README.md` (Multi-tenancy).
161
+
162
+ - **Effort / Value / Risk.** (a) S / med / low. (b) M / med / med — an API-surface
163
+ decision; only worth it if same-process multi-tenant is a target deployment.
164
+
165
+ ### 4. Threading handler data into context requires an fsm `action` per edge (decision)
166
+
167
+ - **Problem / observation.** The driver deliberately does not merge `data` into context
168
+ (`driver.ts:166–170`: "We don't auto-merge to keep state shape under the user's
169
+ control"). The consequence is visible in the package's own fixture: every effectful edge
170
+ in `tests/fixtures/weekly-digest.ts` carries an `action` whose only job is to copy
171
+ `payload.content` / `payload.summary` into `ctx` (`:35–41`, `:48–54`; the file's header
172
+ comment at `:9–12` explains the workaround). Those functions are the only non-data parts
173
+ of an otherwise JSON-safe definition, and every real workflow will replicate them.
174
+
175
+ - **Evidence.** `tests/fixtures/weekly-digest.ts:35–41`:
176
+ ```ts
177
+ FETCHED: {
178
+ target: "summarize",
179
+ action: (ctx: DigestContext, payload) => {
180
+ const p = payload as { content?: string } | undefined;
181
+ ctx.content = p?.content;
182
+ },
183
+ },
184
+ ```
185
+
186
+ - **Proposed change.** Opt-in, explicit per handler — keeps the shape under the author's
187
+ control without the boilerplate: `HandlerResult.context?: Partial<WorkflowContext>`,
188
+ shallow-merged into the instance context in `runAdvance` _before_ `fsm.transition(outcome)`,
189
+ so guards on the outcome edge see it. `data` is unchanged (still the fsm payload).
190
+
191
+ - **Done when** — a weekly-digest fixture variant with no `action`s reaches `_end_ok` with
192
+ the same final context; a guard on the outcome edge observes a merged key.
193
+
194
+ - **Affected files.** `src/types.ts`, `src/driver.ts`, `README.md` / `API.md` /
195
+ `AGENTS.md` (convention #1 wording).
196
+
197
+ - **Effort / Value / Risk.** S / med / low. **Decision needed:** the current stance is a
198
+ considered choice, not an oversight; this changes it.
199
+
200
+ ### 5. `meta` is `unknown` while authoring a definition
201
+
202
+ - **Problem / observation.** `WorkflowDefinition.fsm` is
203
+ `FSMConfig<TState, TEvent, WorkflowContext>` (`types.ts:45`), whose per-state `meta` is
204
+ `unknown` (`fsm.ts:33`). `{ kind: "efectful", handler: "x" }` type-checks; it is caught at
205
+ construction by `definition.ts:101–105`, so this is editor feedback and autocomplete,
206
+ not safety.
207
+
208
+ - **Proposed change.**
209
+ ```ts
210
+ export type WorkflowStateConfig<TState extends string, TEvent extends string> =
211
+ & FSMStatesConfigValue<TState, TEvent, WorkflowContext>
212
+ & { meta: NodeMeta };
213
+ export type WorkflowFSMConfig<
214
+ TState extends string = string,
215
+ TEvent extends string = string,
216
+ > =
217
+ & Omit<FSMConfig<TState, TEvent, WorkflowContext>, "states">
218
+ & { states: Record<TState, WorkflowStateConfig<TState, TEvent>> };
219
+ export interface WorkflowDefinition<
220
+ TState extends string = string,
221
+ TEvent extends string = string,
222
+ > {
223
+ id: string;
224
+ version: string;
225
+ fsm: WorkflowFSMConfig<TState, TEvent>;
226
+ }
227
+ ```
228
+ `WorkflowFSMConfig` narrows `meta` from `unknown`, so it stays assignable to `FSMConfig`
229
+ and `FSM.fromSnapshot(def.fsm, …)` keeps type-checking. `definition.ts` and
230
+ `correlator.ts:139–142` can drop their `as NodeMeta` casts.
231
+
232
+ - **Done when** — a fixture line with a misspelled `kind` under `// @ts-expect-error`
233
+ passes `deno check`; the existing fixtures compile unchanged.
234
+
235
+ - **Affected files.** `src/types.ts`, `src/definition.ts`, `src/correlator.ts`, `API.md`.
236
+
237
+ - **Effort / Value / Risk.** S / low / low. A consumer definition with a state that has no
238
+ `meta` stops compiling — it already failed validation.
239
+
240
+ ## Open questions / decisions needed
241
+
242
+ Resolved 2026-08-26 (see `PROGRESS.md` → Decisions log):
243
+
244
+ - **#3 (b):** guard only (T10). The tenant-per-call runtime (T11) is deferred; revisit when
245
+ a real need to serve several tenants from one `Workflow`/`Jobs` in one process appears.
246
+ - **#4:** add the opt-in `HandlerResult.context` patch (T17 approved) — shallow merge before
247
+ the outcome transition; `data` stays the fsm payload; no automatic merge of `data`.
248
+ - **#1:** a `terminal` state with a non-empty `on` throws at validation.
@@ -0,0 +1,191 @@
1
+ <!--
2
+ GENERATED ANALYSIS — @marianmeres/workflow (docs accuracy, tests, ops hygiene)
3
+ Produced 2026-08-26 by an inline single-agent review: full read of src/, tests/, docs, and the
4
+ resolved sources of @marianmeres/fsm 3.1.0, steve 3.0.0, cron 3.2.0 → self-verification pass
5
+ re-opening every cited line. Claims verified against the codebase at commit 02a7635.
6
+ Planning artifact; no code was changed.
7
+ -->
8
+
9
+ # Docs Accuracy, Test Coverage & Repo Hygiene
10
+
11
+ > The documentation is unusually complete for a v2 package — `AGENTS.md`'s conventions,
12
+ > failure-mode table and glossary are exactly what a consumer (or an agent) needs. Three
13
+ > sentences in it, though, promise durability the code does not deliver, and they are
14
+ > precisely the sentences a consumer reads before deciding _not_ to add their own safety
15
+ > nets. Tests cover the happy, timeout and handler-failure paths and the schema migration,
16
+ > but not the driver's pure-node loop, any rejection path, or any duplicate-delivery path.
17
+ > `deno lint` and `deno fmt --check` are red. One migration guard is schema-blind.
18
+
19
+ > The single most important takeaway: fix the three over-claims _together with_ the
20
+ > behavior changes in `01-durability.md` — the docs should describe what the driver
21
+ > actually guarantees after the sprint, and `autoCleanup`, which today is never mentioned,
22
+ > is the switch that makes crash recovery exist at all.
23
+
24
+ > Headline recommendation: one docs pass at the end of the first sprint (README, AGENTS,
25
+ > API); a `tests/driver.test.ts` for the untested driver branches; the one-line
26
+ > `table_schema` fix in migration 1.1.0; and a `deno task check` that makes lint/fmt part
27
+ > of the routine.
28
+
29
+ ## Summary of recommendations
30
+
31
+ | # | Recommendation | Value | Effort | Risk |
32
+ | - | --------------------------------------------------------------------------------------------------- | ----- | ------ | ---- |
33
+ | 1 | Correct the three durability over-claims; document `autoCleanup`; document the noop-handler hazards | high | S | low |
34
+ | 2 | Migration 1.1.0 column guard ignores `table_schema` | med | S | low |
35
+ | 3 | Driver test coverage: pure routing, hop guard, rejection paths, matcher rejection | med | M | low |
36
+ | 4 | `deno fmt` / `deno lint` clean, plus a `check` task | low | S | low |
37
+
38
+ ## Findings & recommendations (detailed)
39
+
40
+ ### 1. Three durability claims are wrong, and the switch that enables recovery is undocumented
41
+
42
+ - **Problem / observation.**
43
+ - `README.md:195` — "The advance step is a single PG transaction: cursor /
44
+ execution_state / wake_at / history are all written together with the effect-job
45
+ insert." The effect-job insert goes through `jobs.create` on steve's own connection
46
+ (`workflow.ts:159–168` ignores its `_client` argument; `_create.ts:21,43`), outside the
47
+ advance transaction. Enqueue precedes commit (`driver.ts:220–224`), so the practical
48
+ consequence is bounded — a job can exist for a transaction that rolled back — but the
49
+ sentence is false as written, and the fix in 01 #1 makes the true story simple to
50
+ state ("at-least-once, fenced").
51
+ - `README.md:196` — "steve auto-cleanup reaps it after ~5min and retries" — and
52
+ `AGENTS.md:231` — "Steve retries per `max_attempts`". Steve's reaper marks jobs
53
+ `expired`, terminal, no retry (`_mark-expired.ts:6–8`); the workflow then marks the
54
+ instance `failed` (`workflow.ts:133–143`). And the reaper only runs with
55
+ `autoCleanup: true` (`jobs.ts:451–454`): `grep -rn autoCleanup README.md AGENTS.md
56
+ API.md` → nothing. The README example constructs `new Jobs({ db: pool })`
57
+ (`README.md:104`) — a reader who copies it gets a system where a worker crash strands
58
+ the instance in `running` forever.
59
+ - `AGENTS.md:232` — "Lost advance after effect … handler runs again; advance enqueued.
60
+ Handlers must be idempotent." Incomplete: with the current driver the _second_ advance
61
+ is rejected by the FSM and fails the instance (01 #1 (b)).
62
+ - Missing: the cron-side noop hazard. A `Cron` started in a process that never called
63
+ `scheduler.register()` still claims the persisted `workflow.scheduler.<tenant>` row,
64
+ runs a noop with a warning (`cron.ts:472`, `:487–492`) and advances `next_run_at`.
65
+ `AGENTS.md:192` covers the equivalent steve hazard; the README mentions neither.
66
+
67
+ - **Evidence.** `README.md:193–197`:
68
+ ```
69
+ - The advance step is a single PG transaction: cursor / execution_state / wake_at / history are all written together with the effect-job insert.
70
+ - 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.
71
+ ```
72
+
73
+ - **Proposed change.** After T01–T04 land, rewrite: README "Persistence Guarantees &
74
+ Idempotency" and "Failure Modes"; AGENTS "Failure Modes & Recovery" and "Runtime
75
+ Ownership"; API `AdvanceJobPayload` / `EffectJobPayload`, the new options
76
+ (`advanceMaxAttempts`, `redispatchLimit`, `stalePendingSec`), `cancel`/`retry` when they
77
+ land, and the correlator's "Per-tick behavior" (`API.md:173–181`) for the deferral
78
+ semantics of 02 #1. Add `autoCleanup: true` to the README example with one sentence on
79
+ why. Add a short "Signals: early, late, deferred" section. Follow the
80
+ `HUMAN_DOCUMENTATION_GUIDE.md` / `AGENT_DOCUMENTATION_GUIDE.md` conventions from
81
+ mm-local-docs.
82
+
83
+ - **Done when** — `grep -n "written together with the effect-job insert\|reaps it after
84
+ ~5min and retries\|Steve retries per" README.md AGENTS.md` returns nothing;
85
+ `grep -c autoCleanup README.md AGENTS.md` ≥ 1 in each; `API.md` documents
86
+ `expected_seq`, `kind`, `seq` and every new option shipped in the sprint.
87
+
88
+ - **Affected files.** `README.md`, `AGENTS.md`, `API.md`, `src/mod.ts` (module doc
89
+ example).
90
+
91
+ - **Effort / Value / Risk.** S / high / low. Sequenced last in the sprint so it describes
92
+ shipped behavior, not intent.
93
+
94
+ ### 2. Migration 1.1.0's column guard is schema-blind
95
+
96
+ - **Problem / observation.** `renameColumn()` guards the `RENAME COLUMN` on
97
+ `information_schema.columns WHERE table_name = '…' AND column_name = '…'`
98
+ (`1_1_0.ts:16–18`) with no `table_schema` predicate. In a database with several schemas
99
+ holding the same tables — per-tenant or per-app schemas selected via `search_path`, a
100
+ common Postgres layout — a `project_id` found in _another_ schema's `__workflow_instances`,
101
+ or a `tenant_id` already present there, flips the guard: the rename is skipped in the
102
+ current schema (every query then fails on `tenant_id`), or attempted where it already
103
+ happened. The test suite runs in one schema and cannot observe it.
104
+
105
+ - **Evidence.** `src/migrations/1_1_0.ts:16–18`:
106
+ ```ts
107
+ const col = (c: string) =>
108
+ `EXISTS (SELECT 1 FROM information_schema.columns
109
+ WHERE table_name = '${table}' AND column_name = '${c}')`;
110
+ ```
111
+
112
+ - **Proposed change.** `AND table_schema = current_schema()` in the `EXISTS` (or
113
+ `= ANY(current_schemas(false))`). The rest of the DDL is unqualified and follows
114
+ `search_path` consistently — that is the right behavior; only the guard is
115
+ inconsistent with it. Apply the same discipline to the `1.2.0` migration from 01 #1.
116
+
117
+ - **Done when** — `renameColumn()`'s SQL contains `table_schema = current_schema()`;
118
+ `tests/migrations.test.ts` passes; optionally a test creates
119
+ `other.__workflow_instances (tenant_id text)` first and asserts the rename in `public`
120
+ still happens.
121
+
122
+ - **Affected files.** `src/migrations/1_1_0.ts`.
123
+
124
+ - **Effort / Value / Risk.** S / med / low.
125
+
126
+ ### 3. Driver test coverage gaps
127
+
128
+ - **Problem / observation.** Both fixtures define only `effectful`, `suspending` and
129
+ `terminal` nodes (`tests/fixtures/stock-replenishment.ts:26–55`,
130
+ `tests/fixtures/weekly-digest.ts:32–69`). Untested: the `pure` branch
131
+ (`driver.ts:256–284`), `MAX_PURE_HOPS` (`:79`, `:296–300`), `transition_rejected`
132
+ (`:151–165`), the unknown-definition path (`:122–132`), and the correlator's
133
+ `signal_rejected` path (`correlator.ts:175–185`). The suite is PG-only
134
+ (`ignore: !pgConfigured()`), which is right for a driver that is SQL-bound — but each
135
+ behavior change in the first sprint must land with its test, and the branches above have
136
+ none to extend. Also, `waitUntil` is copy-pasted three times
137
+ (`tests/stock_replenishment.test.ts:22–33`, `tests/weekly_digest.test.ts:32–43`,
138
+ `tests/migrations.test.ts:22–33`).
139
+
140
+ - **Proposed change.** `tests/driver.test.ts` with a small dedicated fixture:
141
+ (a) `pure` routing on `ENTER` with two guards (left/right by a context flag);
142
+ (b) `pure → pure → effectful` in one advance (history shows both `transition` rows and one
143
+ `effect_dispatched`);
144
+ (c) a `pure` self-cycle hits `MAX_PURE_HOPS` → `failed` with the "exceeded" reason;
145
+ (d) a handler returning an outcome the node does not accept → `transition_rejected` +
146
+ `failed`;
147
+ (e) an instance whose `definition_version` is not registered → `failed`;
148
+ (f) matcher returns `false` → `signal_rejected`, inbox row processed, instance still
149
+ `waiting`.
150
+ Move `waitUntil` to `tests/_util.ts`.
151
+
152
+ - **Done when** — `deno task test` runs the six cases green; `grep -c "async function
153
+ waitUntil" tests/*.test.ts` is `0`.
154
+
155
+ - **Affected files.** `tests/driver.test.ts` (new), `tests/fixtures/` (new fixture),
156
+ `tests/_util.ts` (new), the three existing test files.
157
+
158
+ - **Effort / Value / Risk.** M / med / low.
159
+
160
+ ### 4. Lint and format are red; there is no aggregate check task
161
+
162
+ - **Problem / observation.** `deno lint` → 5 × `require-await`
163
+ (`tests/fixtures/stock-replenishment.ts:70,76,82,85`,
164
+ `tests/stock_replenishment.test.ts:224`). `deno fmt --check` → 12 files: `src/correlator.ts`,
165
+ `src/driver.ts`, `src/mod.ts`, `src/persistence/history.ts`, `src/workflow.ts`, three
166
+ test files, and `README.md` / `API.md` / `AGENTS.md` / `deno.json`. The markdown diffs
167
+ are table re-alignment under the repo's own `fmt` config (`deno.json:29–34`); the
168
+ TypeScript diffs are import/wrapping trivia. Nothing here is a bug — but a red baseline
169
+ means a driver (`sprint/SPEC.md` §2) cannot use these as `Verify:` commands, and nobody
170
+ notices new drift.
171
+
172
+ - **Proposed change.** Drop the `async` keywords on the sync fixtures (`Handler` allows a
173
+ plain `HandlerResult`, `types.ts:68`); `deno fmt`; add
174
+ `"check": "deno fmt --check && deno lint && deno check src/mod.ts tests/*.ts"` to
175
+ `deno.json` tasks.
176
+
177
+ - **Done when** — `deno task check` exits `0`.
178
+
179
+ - **Affected files.** `deno.json`, the 12 listed files.
180
+
181
+ - **Effort / Value / Risk.** S / low / low. Kept only because it is trivially cheap.
182
+
183
+ ## Open questions / decisions needed
184
+
185
+ Resolved 2026-08-26 (see `PROGRESS.md` → Decisions log): **#4** — let `deno fmt` reflow
186
+ the markdown tables (`README.md`, `API.md`, `AGENTS.md`); no `fmt.exclude` for them (T15
187
+ approved). Amended when the backlog was promoted: `fmt.exclude` gains
188
+ `docs/analysis/PROGRESS.md` alone, because the sprint driver's own bookkeeping commit
189
+ rewrites a `Commit` cell without re-padding the table and would otherwise leave
190
+ `deno fmt --check` — now a `Verify:` command — red through no task's fault.
191
+ **#1** has no open question, but it must wait for T01–T04 so it documents shipped behavior.
@@ -0,0 +1,172 @@
1
+ # Implementation Progress — workflow analysis roadmap
2
+
3
+ <!-- tracker: v1 -->
4
+
5
+ Living tracker for acting on [`00-overview-and-roadmap.md`](./00-overview-and-roadmap.md).
6
+ A fresh conversation should read this file first, then the relevant `NN-*.md` section.
7
+
8
+ **Status legend:** ⬜ ready · 🚧 in progress · ⏸️ blocked/awaiting decision · 🔒 human-only · ✅ done · ⏭️ deferred
9
+
10
+ > Convention: one branch per sprint, one commit per task. Each task resolves its source doc's
11
+ > "Open questions" first (record in the Decisions log), then implement → verify → tick here.
12
+ > The tasks in the first sprint change durability semantics — every one lands with its test
13
+ > (the source section's **Done when** names it).
14
+
15
+ ## First sprint (durability + signal delivery, before first production use)
16
+
17
+ Branch: `analysis/first-sprint`
18
+ Options: --max-tasks 20 --budget 40 --model claude-opus-5 --effort xhigh
19
+ Verify: deno task test
20
+ Verify: deno check src/mod.ts tests/*.ts
21
+
22
+ | Status | ID | Deps | Task | Source | Commit |
23
+ | ------ | --- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------ |
24
+ | ✅ | T01 | — | Fencing token: migration 1.2.0 `seq`; `kind` + `expected_seq` on advances, `seq` on effects; fenced advance/effect/fail; `create()` in tx | [01](./01-durability.md) #1 | c7e5b22 |
25
+ | ✅ | T02 | T01 | Correlator: defer early signals, deliver only to `MATCHED`-accepting waits, processed-in-advance, per-tick dedupe, matcher-throw retry | [02](./02-correlation.md) #1, #2 | 27c0f60 |
26
+ | ✅ | T03 | T01 T02 | Scheduler: read-only TIMEOUT pokes + stale-pending re-poke; delete `claimDueWakeUps`; pending partial index | [01](./01-durability.md) #2 | 53a3323 |
27
+ | ✅ | T04 | T01 | Observe `workflow.advance` failures; bounded re-dispatch of `expired` advance/effect jobs; `advanceMaxAttempts`, `redispatchLimit` | [01](./01-durability.md) #3 | 6de8396 |
28
+ | ✅ | T05 | T01 T02 T03 T04 | Docs pass: correct durability claims, document `autoCleanup`, fence/poke model, signal semantics, noop-handler hazards | [04](./04-docs-tests-ops.md) #1 | a7f96c4 |
29
+
30
+ `Verify:` deliberately omitted `deno lint` / `deno fmt --check` — both were red at the
31
+ baseline (T15). The second sprint adds them, with T15 as its first row.
32
+
33
+ Before starting the driver: commit `docs/analysis/` on `master` (the driver refuses a
34
+ dirty tree and only switches to the sprint branch from a default branch), then run
35
+ `sprint docs/analysis` from the repository root. `deno task test` needs the `TEST_PG_*`
36
+ env from `.env`.
37
+
38
+ ## Second sprint (hardening, API surface, release)
39
+
40
+ Branch: `analysis/first-sprint`
41
+ Options: --max-tasks 12 --budget 90 --task-budget 12 --max-turns 120 --run-deadline 21600 --model claude-opus-5 --effort xhigh
42
+ Verify: deno lint
43
+ Verify: deno fmt --check
44
+
45
+ | Status | ID | Deps | Task | Source | Commit |
46
+ | ------ | --- | --------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------- | ------ |
47
+ | ✅ | T15 | — | `deno fmt` + `deno lint` clean; `deno task check`; `fmt.exclude` for this tracker | [04](./04-docs-tests-ops.md) #4 | 25df0af |
48
+ | ✅ | T13 | — | `tests/driver.test.ts`: pure routing, hop guard, rejections, unknown definition; `tests/_util.ts` | [04](./04-docs-tests-ops.md) #3 | fb296f5 |
49
+ | ✅ | T12 | — | Migration 1.1.0 guard: `table_schema = current_schema()` | [04](./04-docs-tests-ops.md) #2 | 18362df |
50
+ | ✅ | T06 | — | Validator: reject definitions that must fail at runtime (ENTER/TIMEOUT/MATCHED/empty `on`) | [03](./03-definition-and-api.md) #1 | 4a3fc30 |
51
+ | ✅ | T09 | — | `create()` seeds context from `def.fsm.context`, input overlays | [03](./03-definition-and-api.md) #2 | 402d4e7 |
52
+ | ✅ | T10 | — | Guard: one `Workflow` per `Jobs` (WeakMap + throw) and `detach()` | [03](./03-definition-and-api.md) #3 | 29a5bb1 |
53
+ | ✅ | T08 | T01 | `HandlerResult.correlationToken` applied at the settle-point write | [02](./02-correlation.md) #3 | 1a947a8 |
54
+ | ✅ | T17 | T08 | Opt-in `HandlerResult.context` shallow patch before the outcome transition | [03](./03-definition-and-api.md) #4 | efce4a7 |
55
+ | ✅ | T07 | T01 | `cancel(id, reason?)` / `retry(id, { force? })` on `Workflow`; `RETRIED` history event | [01](./01-durability.md) #4 | 3bafa6b |
56
+ | ✅ | T14 | — | Typed `meta`: `WorkflowStateConfig` / `WorkflowFSMConfig`; drop the `as NodeMeta` casts | [03](./03-definition-and-api.md) #5 | 10031bd |
57
+ | 🔒 | T16 | T06 T07 T08 T09 T10 T12 T13 T14 T15 T17 | Release 2.1.0 to JSR + npm (`deno task rpm`); smoke-run the npm build under Node first | [04](./04-docs-tests-ops.md) #1 | — |
58
+
59
+ The whole backlog, promoted in **run order rather than rank order**: T15 first because it makes
60
+ the two new `Verify:` commands green, T13 second because every later test file wants
61
+ `tests/_util.ts` and a driver fixture, T14 last because it retypes what the fixtures written
62
+ before it compile against. The rest keep their relative rank.
63
+
64
+ `Verify:` accumulates, so the two lines above join the first sprint's `deno task test` and
65
+ `deno check` — **four commands after every task**, T15 included (which is why it runs first).
66
+
67
+ T16 sits in the sprint table rather than the backlog on purpose: a run that finishes every
68
+ runnable row then exits `2` — "nothing the driver can run, 1 🔒 — yours to do" — instead of `0`,
69
+ so "sprint complete" and "the release is waiting on you" do not look the same
70
+ (`sprint/SPEC.md` §3.3). Flip it to ✅ after publishing and the next run exits `0`.
71
+
72
+ Run it with `sprint docs/analysis` from the repository root. The declared branch is already
73
+ checked out, so the driver switches nothing. `deno task test` needs the `TEST_PG_*` env from
74
+ `.env`.
75
+
76
+ ## Backlog (ranked, post-sprint)
77
+
78
+ | Status | ID | Rank | Deps | Task | Source |
79
+ | ------ | --- | ---- | ---- | --------------------------------------------------------------------------------------------- | ----------------------------------- |
80
+ | ⏭️ | T11 | 13 | T10 | Tenant-per-call runtime: `tenantId` on `create`/`appendInbox`/`find`, `"*"` ticks | [03](./03-definition-and-api.md) #3 |
81
+
82
+ T11 is the only row left here — deferred by decision, guard only (T10) for now; the revisit
83
+ trigger is in the Decisions log. Everything else was promoted into the second sprint above.
84
+
85
+ ## Decisions log
86
+
87
+ - **2026-08-26** — Backlog promoted into a second sprint (owner interview):
88
+ - **Scope:** all ten ⬜ backlog rows into one section, on the same branch
89
+ `analysis/first-sprint` — no merge to `master` in between. T16 moves into the sprint
90
+ table as 🔒 so a completed run exits `2` ("the release is yours"), not `0`. T11 stays
91
+ the only backlog row.
92
+ - **Run order is not rank order.** T15 first (it makes the two new `Verify:` commands
93
+ green), T13 second (`tests/_util.ts` and a driver fixture for every later test), T14
94
+ last (it retypes what earlier fixtures compile against). The rest keep their rank.
95
+ - **`Verify:` gains `deno lint` and `deno fmt --check`** — approved now that T15 leads.
96
+ They accumulate onto the first sprint's two commands: four run after every task.
97
+ - **T15 additionally excludes `docs/analysis/PROGRESS.md` from `deno fmt`.** —
98
+ _Rationale:_ `setCommitCell` writes a 7-character hash into a `Commit` cell sized for
99
+ `—` without re-padding the header, so the driver's own end-of-run bookkeeping commit
100
+ leaves this file failing `deno fmt --check` — it does today, at `253032b`. Without the
101
+ exclusion the first task of any _later_ run fails a verification that has nothing to do
102
+ with it. This does **not** reverse the "no `fmt.exclude`" decision for
103
+ `README`/`API`/`AGENTS`; those are still reflowed.
104
+ - **T14 ships as specced, under 2.1.0.** `meta` stays required on `WorkflowStateConfig`.
105
+ Only a definition that already threw in `validateDefinition` loses compilation, so no
106
+ working consumer breaks and a minor bump is honest.
107
+ - **T12 covers 1.1.0 only.** The 1.2.0 migration T01 shipped uses
108
+ `ADD COLUMN IF NOT EXISTS` / `CREATE INDEX IF NOT EXISTS` and reads no
109
+ `information_schema`, so it has no schema-blind guard to fix.
110
+ - **T13 case (f) is already covered.** `tests/correlator.test.ts` (T02) asserts the
111
+ `signal_rejected` path. T13 is cases (a)–(e) plus moving `waitUntil` — now duplicated in
112
+ **five** test files, not the three the source doc counted — into `tests/_util.ts`.
113
+ - **Ceilings raised from sprint 1's measurements:** the five tasks cost $3.66–$5.85
114
+ (mean $4.71, $23.43 total) and ran 8–13 min each, and T05 used 75 of its 80 turns. Hence
115
+ `--budget 90 --task-budget 12 --max-turns 120 --run-deadline 21600`: ten tasks ≈ $47 and
116
+ ≈ 2 h, with the turn cap no longer one refusal away and the whole-run deadline able to
117
+ fit the tail.
118
+
119
+ - **2026-08-26** — Owner interview: every open question closed; the sprint is cleared for
120
+ unattended EXECUTE via the sprint driver.
121
+ - **T11 tenant-per-call runtime → ⏭️ deferred.** Guard only (T10) for now. —
122
+ _Rationale:_ same-process multi-tenant is not a current deployment, and T11 is purely
123
+ additive later. _Revisit trigger:_ a real need to serve several `tenant_id`s from one
124
+ `Workflow`/`Jobs` in one process.
125
+ - **T17 opt-in `HandlerResult.context` patch → ⬜ approved.** Shallow-merged into the
126
+ instance context before the outcome transition; `data` stays the fsm payload; no
127
+ automatic merge of `data`. — _Rationale:_ removes the per-edge `action` boilerplate
128
+ while keeping the persisted shape an explicit per-handler choice.
129
+ - **T04 `expired` policy: bounded re-dispatch** of the identical payload, for advance and
130
+ effect jobs alike, `redispatchLimit = 3`, then fail the instance. — _Rationale:_ the
131
+ fence makes a zombie's late completion a no-op and handlers are already required to be
132
+ idempotent, so re-dispatch turns a crash into recovery.
133
+ - **T15 → ⬜ approved: let `deno fmt` reflow the markdown** (README, API, AGENTS); no
134
+ `fmt.exclude`.
135
+ - **Defaults accepted:** fence column `seq` (`integer NOT NULL DEFAULT 0`);
136
+ `advanceMaxAttempts = 10`; `redispatchLimit = 3`; `stalePendingSec = 300` with the
137
+ re-poke on by default (`0` disables). All but the column name are runtime options.
138
+ - **Inbox rows whose token no live instance owns** (unknown token, or the instance is
139
+ terminal) **are marked processed on the first tick** with a warn log — plus a
140
+ `signal_rejected` history row when a terminal instance exists. No grace period. —
141
+ _Rationale:_ a token no live instance owns is an upstream bug, not something to wait on.
142
+ - **Validator (T06): a `terminal` state with a non-empty `on` throws.**
143
+ - **Execution: unattended via the sprint driver.** One commit per task on
144
+ `analysis/first-sprint`, pre-authorized; the driver records the hashes. The owner
145
+ commits `docs/analysis/` first and runs `sprint docs/analysis` from the repo root.
146
+ - **2026-08-26** — Plan-author defaults confirmed as written in the interview above:
147
+ an advance payload without `expected_seq` is treated as unfenced (2.0.x jobs still queued
148
+ at upgrade) — a transitional shim removed together with `payloadTenantId` (_Rationale:_
149
+ additive migration, zero downtime, same policy as the 1.1.0 rename); ticks are read-only
150
+ pokes and the advance is the only writer of instance rows, stale pokes debug-logged and
151
+ never written to history (_Rationale:_ every crash window becomes "next tick pokes
152
+ again"; history stays an event log); T03 is sequenced after T02 (_Rationale:_ the
153
+ stale-`pending` re-poke is only safe once `create()` is the sole producer of `pending`);
154
+ early signals — instance live but not `waiting`, or node without a `MATCHED` edge — stay
155
+ unprocessed and are retried each tick, and a throwing matcher leaves its row for the next
156
+ tick (_Rationale:_ losing a signal is worse than re-examining a row); `failed` advance
157
+ jobs fail the instance with the last attempt's error message; `Verify:` excludes lint/fmt
158
+ until T15 lands (_Rationale:_ a red baseline would refuse the sprint, `sprint/SPEC.md`
159
+ §3.2).
160
+
161
+ ## How to resume (for a fresh conversation)
162
+
163
+ 1. Read this file + `00-overview-and-roadmap.md`.
164
+ 2. Pick the first ⬜ task whose `Deps` are all ✅ (or the `T##` you were given); open its
165
+ source doc section for the detail and its **Done when** criterion. Check the finding
166
+ still holds against the current code — the plan was verified at `02a7635`.
167
+ 3. Every "Open questions" item is already resolved in the Decisions log — do not re-ask. If
168
+ the task's premise no longer holds against the current code, return `blocked` rather
169
+ than building something plausible in its place.
170
+ 4. Implement (with the test the **Done when** names) → run the `Verify:` commands → flip
171
+ the row to ✅ here → one commit per task on the sprint branch (pre-authorized; leave the
172
+ `Commit` cell as `—`, the driver fills it in).
@@ -0,0 +1,38 @@
1
+ # Analysis & Roadmap — `@marianmeres/workflow`
2
+
3
+ This directory holds a **code-verified** review of the package produced on **2026-08-26**
4
+ (codebase at commit `02a7635`, before any production use). It is a **planning artifact** —
5
+ no source code was changed. Every technical claim cites `file:line` in this repo or in the
6
+ resolved sources of `@marianmeres/fsm` 3.1.0, `@marianmeres/steve` 3.0.0 and
7
+ `@marianmeres/cron` 3.2.0, and was re-checked against the code before shipping;
8
+ suggestions that duplicated existing behavior or were low-value for a solo maintainer were
9
+ cut.
10
+
11
+ **Start here:** [`00-overview-and-roadmap.md`](./00-overview-and-roadmap.md) — the
12
+ verdict, the ranked master table, the recommended first sprint, and the sequencing graph.
13
+ Then [`PROGRESS.md`](./PROGRESS.md) to act on it.
14
+
15
+ ## Documents
16
+
17
+ | # | Doc | Scope | Headline finding |
18
+ | -- | ---------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
19
+ | 00 | [overview-and-roadmap](./00-overview-and-roadmap.md) | Synthesis + ranked roadmap | Architecture is right; the driver assumes exactly-once delivery from an at-least-once queue — add a fence |
20
+ | 01 | [durability](./01-durability.md) | Driver ↔ steve contract, crash windows | No fencing token: stale/duplicate jobs fail healthy instances; claim-then-enqueue strands rows; `expired` ≠ retry |
21
+ | 02 | [correlation](./02-correlation.md) | Inbox → instance signal delivery | Early signals are dropped; a signal at a timer-only wait fails the instance; token is create-time only |
22
+ | 03 | [definition-and-api](./03-definition-and-api.md) | Validator, registry, public API, DX | Validator admits definitions that must fail; `create()` ignores `context` defaults; two `Workflow`s on one `Jobs` collide |
23
+ | 04 | [docs-tests-ops](./04-docs-tests-ops.md) | Docs accuracy, test coverage, repo hygiene | Three durability claims are false and `autoCleanup` is undocumented; pure nodes and rejections are untested |
24
+
25
+ ## How it was produced
26
+
27
+ A single-agent inline review: complete read of `src/`, `tests/`, `README.md`, `API.md`,
28
+ `AGENTS.md` and the working notes in `tmp/`, plus the relevant dependency sources
29
+ (`fsm.ts`, steve's `jobs.ts` and `job/*`, cron's `cron.ts` and `cron/*`), followed by a
30
+ verification pass that re-opened every cited line and ran the baseline (`deno task test`:
31
+ 10 passed; `deno check`: clean; `deno lint`: 5 problems; `deno fmt --check`: 12 files).
32
+ Editorial notes such as "_Cut from the draft:_" inside the docs record what the
33
+ verification pass removed and why.
34
+
35
+ > Every open question was closed in an owner interview on 2026-08-26. The calls and their
36
+ > rationale are in the `PROGRESS.md` decisions log; each doc's **"Open questions /
37
+ > decisions needed"** section records its own resolutions. The first sprint is cleared for
38
+ > unattended EXECUTE via the sprint driver.