@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/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
|
@@ -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.
|