Skip to content

Commit 3dfd1aa

Browse files
kasvithkasvith
committed
docs: revise arch.md and WORKPLAN.md to match codebase reality
- Fix orchestration section: remove "not yet implemented", add correct API - Fix sleep/wait API: sleep_for → sleep, sleep_until → schedule_at - Fix cron DSL: @Cron → @schedule, use Durable.Scheduler.DSL - Fix log capture module names and remove non-existent APIs - Fix queue adapter name and API, mark extra adapters as planned - Mark Message Bus and Graph Visualization as planned - Add pending_events and wait_groups to DB schema - Update config reference to supervision tree style - Update WORKPLAN stats: 42 modules, ~291 tests, ~11k LOC - Update test coverage table with actual per-file counts - Add guides/orchestration.md to mix.exs extras
1 parent 83bf0a7 commit 3dfd1aa

11 files changed

Lines changed: 988 additions & 709 deletions

File tree

‎README.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -453,6 +453,23 @@ end
453453

454454
# Fire-and-forget: start child and continue
455455
{:ok, child_id} = start_workflow(MyApp.EmailWorkflow, %{"to" => email}, ref: :welcome)
456+
457+
# call_workflow also works inside parallel blocks (executed inline)
458+
parallel do
459+
step :payment, fn data ->
460+
case call_workflow(MyApp.PaymentWorkflow, %{"amount" => data.total}, ref: :pay) do
461+
{:ok, result} -> {:ok, assign(data, :payment, result)}
462+
{:error, reason} -> {:error, reason}
463+
end
464+
end
465+
466+
step :shipping, fn data ->
467+
case call_workflow(MyApp.ShippingWorkflow, %{"id" => data.order_id}, ref: :ship) do
468+
{:ok, result} -> {:ok, assign(data, :shipping, result)}
469+
{:error, reason} -> {:error, reason}
470+
end
471+
end
472+
end
456473
```
457474

458475
### API

‎agents/WORKPLAN.md‎

Lines changed: 42 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Durable Workflow Engine - Work Plan
22

3-
**Last Updated:** 2026-02-27
3+
**Last Updated:** 2026-03-08
44
**Overall Progress:** ~75% Complete
55
**Reference:** See `arch.md` for technical architecture
66

@@ -10,10 +10,10 @@
1010

1111
| Metric | Value |
1212
|--------|-------|
13-
| Source Modules | 40 |
14-
| Passing Tests | ~268 |
13+
| Source Modules | 42 |
14+
| Passing Tests | ~291 |
1515
| Documentation Guides | 6 |
16-
| Lines of Code | ~8,500 |
16+
| Lines of Code | ~11,000 |
1717

1818
---
1919

@@ -25,7 +25,7 @@
2525
| 1 | Core MVP | Complete | 100% |
2626
| 2 | Observability | Partial | 40% |
2727
| 3 | Advanced Features | Mostly Complete | 90% |
28-
| 4 | Scalability | Not Started | 0% |
28+
| 4 | Scalability | Partial | ~5% |
2929
| 5 | Developer Experience | Partial | 35% |
3030

3131
---
@@ -88,7 +88,7 @@
8888

8989
## Phase 3: Advanced Features [90%]
9090

91-
### 3.1-3.3 Wait Primitives [COMPLETE - 46 tests]
91+
### 3.1-3.3 Wait Primitives [COMPLETE - 52 tests]
9292

9393
| Feature | Status |
9494
|---------|--------|
@@ -105,7 +105,7 @@
105105
| Timeout handling | Complete |
106106
| Context preservation | Complete |
107107

108-
### 3.4 Conditional Branching [COMPLETE - 10 tests]
108+
### 3.4 Conditional Branching [COMPLETE - 19 tests]
109109

110110
| Feature | Status |
111111
|---------|--------|
@@ -119,7 +119,7 @@
119119

120120
Intentionally skipped - use step-level retries or Elixir's `Enum` functions instead.
121121

122-
### 3.6 Parallel Execution [COMPLETE - 13 tests]
122+
### 3.6 Parallel Execution [COMPLETE - 20 tests]
123123

124124
| Feature | Status |
125125
|---------|--------|
@@ -143,7 +143,7 @@ through idiomatic Elixir.
143143

144144
Low priority - `branch` macro covers most cases.
145145

146-
### 3.9 Compensation/Saga [COMPLETE - 6 tests]
146+
### 3.9 Compensation/Saga [COMPLETE - 10 tests]
147147

148148
| Feature | Status |
149149
|---------|--------|
@@ -152,7 +152,7 @@ Low priority - `branch` macro covers most cases.
152152
| Reverse-order execution | Complete |
153153
| CompensationRunner | Complete |
154154

155-
### 3.10 Cron Scheduling [COMPLETE - 45 tests]
155+
### 3.10 Cron Scheduling [COMPLETE - 49 tests]
156156

157157
| Feature | Status |
158158
|---------|--------|
@@ -172,6 +172,7 @@ Low priority - `branch` macro covers most cases.
172172
|---------|--------|
173173
| `call_workflow/3` (synchronous) | Complete |
174174
| `start_workflow/3` (fire-and-forget) | Complete |
175+
| `call_workflow` in `parallel` blocks (inline execution) | Complete |
175176
| Idempotent resume | Complete |
176177
| Cascade cancellation | Complete |
177178
| Parent notification on child complete/fail | Complete |
@@ -189,11 +190,11 @@ See `guides/orchestration.md` for comprehensive documentation.
189190

190191
---
191192

192-
## Phase 4: Scalability [0%]
193+
## Phase 4: Scalability [~5%]
193194

194195
| Feature | Priority | Complexity |
195196
|---------|----------|------------|
196-
| Queue Adapter Behaviour | Complete | - |
197+
| Queue Adapter Behaviour | **Complete** | - |
197198
| Redis Queue Adapter | Medium | Medium |
198199
| RabbitMQ Queue Adapter | Low | Medium |
199200
| Message Bus Behaviour | Medium | Low |
@@ -217,7 +218,7 @@ Note: Multi-node scheduling already works via `FOR UPDATE SKIP LOCKED`.
217218
| Module docs (@moduledoc) | Complete |
218219
| Function docs (@doc) | Complete |
219220
| Typespecs (@spec) | Complete |
220-
| 7 Documentation Guides | Complete |
221+
| 6 Documentation Guides | Complete |
221222

222223
### Remaining
223224

@@ -267,28 +268,36 @@ Note: Multi-node scheduling already works via `FOR UPDATE SKIP LOCKED`.
267268

268269
| Test File | Tests | Area |
269270
|-----------|-------|------|
270-
| scheduler_test.exs | 45 | Cron scheduling |
271-
| wait_test.exs | 46 | Wait primitives |
272-
| decision_test.exs | 13 | Decision steps |
273-
| parallel_test.exs | 13 | Parallel execution |
271+
| wait_test.exs | 52 | Wait primitives |
272+
| scheduler_test.exs | 49 | Cron scheduling |
273+
| parallel_test.exs | 20 | Parallel execution |
274+
| branch_test.exs | 19 | Branch macro |
275+
| postgres_test.exs | 16 | Queue adapter |
276+
| decision_test.exs | 14 | Decision steps |
274277
| log_capture_test.exs | 13 | Log/IO capture |
275-
| integration_test.exs | 11 | End-to-end flows |
276-
| branch_test.exs | 10 | Branch macro |
277-
| durable_test.exs | 8 | Core API |
278-
| compensation_test.exs | 6 | Saga pattern |
279-
| Other | ~36 | Queue, handlers, etc. |
280278
| orchestration_test.exs | 12 | Workflow orchestration |
281-
| **Total** | **~268** | |
279+
| integration_test.exs | 11 | End-to-end flows |
280+
| validation_test.exs | 10 | Input validation |
281+
| context_test.exs | 10 | Context management |
282+
| compensation_test.exs | 10 | Saga pattern |
283+
| durable_test.exs | 10 | Core API |
284+
| handler_test.exs | 8 | Log handler |
285+
| io_server_test.exs | 7 | IO capture |
286+
| resume_edge_cases_test.exs | 5 | Resume edge cases |
287+
| log_capture/integration_test.exs | 5 | Log capture integration |
288+
| Other | ~20 | Misc |
289+
| **Total** | **~291** | |
282290

283291
---
284292

285293
## Known Limitations
286294

287295
1. Wait primitives not supported in parallel blocks
288-
2. No backward jumps in decision steps (forward-only by design)
289-
3. Context is single-level atomized (top-level keys only)
290-
4. No workflow versioning
291-
5. No foreach/loop DSL primitives (use Elixir's `Enum` functions)
296+
2. Child workflows with waits (`sleep`, `wait_for_event`) not supported in parallel blocks
297+
3. No backward jumps in decision steps (forward-only by design)
298+
4. Context is single-level atomized (top-level keys only)
299+
5. No workflow versioning
300+
6. No foreach/loop DSL primitives (use Elixir's `Enum` functions)
292301

293302
---
294303

@@ -298,20 +307,24 @@ Note: Multi-node scheduling already works via `FOR UPDATE SKIP LOCKED`.
298307
2. **Graph Visualization** - Understanding complex workflows
299308
3. **Testing Helpers** - `Durable.TestCase` for easier workflow testing
300309

301-
The existing ~268 tests provide good confidence in implemented features. Suitable for internal use; additional documentation needed before public release.
310+
The existing ~291 tests provide good confidence in implemented features. Suitable for internal use; additional documentation needed before public release.
302311

303312
---
304313

305314
## Changelog
306315

307316
### 2026-02-27
317+
- Added `call_workflow` support inside `parallel` blocks (inline synchronous execution)
318+
- Child workflows in parallel execute synchronously with process state save/restore
319+
- 3 new tests for parallel call_workflow (total: ~291)
320+
- Updated guides/orchestration.md, guides/parallel.md, and README.md
308321
- Added workflow orchestration: `call_workflow/3` (synchronous) and `start_workflow/3` (fire-and-forget)
309322
- Added `Durable.Orchestration` module with `use Durable.Orchestration` macro
310323
- Added cascade cancellation (cancelling parent cancels active children)
311324
- Added parent notification on child completion/failure
312325
- Added `Durable.list_children/2` API
313326
- Added `guides/orchestration.md` documentation
314-
- 12 new tests for orchestration (total: ~268)
327+
- 12 new tests for orchestration
315328

316329
### 2026-01-23
317330
- Removed `foreach` primitive (use `Enum.map` or `Task.async_stream` instead)

0 commit comments

Comments
 (0)