owenloop 0.2.0 → 0.3.1

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/docs/design.md CHANGED
@@ -24,9 +24,53 @@ function rather than a feature bolted beside it.
24
24
  - **§2.2 Task / lease** — the claimable unit of work-in-flight. One per
25
25
  `(step, key)`; `key` is `""` for plain/reduce/collection firings and the
26
26
  element path for a map firing.
27
+
28
+ **Lease lifecycle.** Claiming a firing writes `claimedAt` on the task and opens
29
+ a run. A lease's liveness is judged on read (at `reap`/`tick`/claim time), never
30
+ on a timer:
31
+ - **Reap TTL (the anchor rule).** A lease is fresh while
32
+ `now - max(claimedAt, heartbeatAt) <= ttl`, where `ttl` is the effective reap
33
+ TTL (engine `reapTtlMs`, default 2h; per-step `reapTtl:` overrides). A run that
34
+ heartbeats within the TTL is **never** reaped by this rule, however long it
35
+ runs — heartbeats extend the lease indefinitely. A run that goes silent past
36
+ the TTL is stale, reaped back to `idle` (its `attempts` bumps), and re-claimable
37
+ by another worker; the old run's next `green`/`close` then fails the commit CAS
38
+ (§12.2) with a stale-lease error.
39
+ - **Opt-in max-lease cap.** There is **no default cap on total lease lifetime.**
40
+ An operator may set one — engine `maxLeaseMs` or per-step `maxLease:` (per-step
41
+ overrides the engine option) — as a runaway backstop: it bounds total lifetime
42
+ from the original `claimedAt` regardless of heartbeats, so past
43
+ `claimedAt + maxLease` even a still-beating lease is reaped. The cap re-anchors
44
+ to the new `claimedAt` on re-claim. **Tradeoff, stated plainly:** a cap can reap
45
+ a healthy, still-beating job, after which another worker claims the same order —
46
+ duplicate execution is the price of the backstop. Leave it unset unless you
47
+ specifically want that bound; heartbeat liveness is already the reap signal.
48
+ - **Reap reasons.** When a reap clears a lease it records why, so the two failure
49
+ modes are distinguishable: `heartbeat-lost` (the anchor rule lapsed — the job
50
+ went silent) vs. `max-lease-exceeded` (a configured cap expired a still-beating
51
+ lease). When both bounds lapse, `heartbeat-lost` wins (a dead job is not reported
52
+ as cap-killed). See the CLI `reap` command (docs/cli.md) — or the `ReapReason`
53
+ type in `engine.ts` — for the full reason set.
27
54
  - **§2.3 Run** — the audit/budget record created when a task is claimed; holds the
28
55
  claim's input **fingerprint** for the commit CAS.
29
56
 
57
+ ### §2.4 Persistence history
58
+
59
+ SQLite keeps `artifact` as the compact current-state projection used by the
60
+ scheduler. In addition, every newly produced positive version is captured once
61
+ in immutable `artifact_version` (payload, fingerprint, producer, initial
62
+ acceptance, and time), while `artifact_event` is an append-only, version-addressed
63
+ lifecycle stream. Re-persisting a semantically identical artifact state appends no
64
+ event: change-detection is structural (a canonical, key-order-independent
65
+ comparison of the artifact's semantic fields), so `artifact_event` stays a true
66
+ audit stream rather than growing on order-only or no-op rewrites.
67
+ `Store.getArtifactHistory(workflow, path)` is deliberately a
68
+ narrow, lazy read; normal artifact/status listing does not load it. Intentional
69
+ artifact or workflow deletion also removes its history, so active instances retain
70
+ history but cleanup leaves no orphan audit rows. Upgrading legacy databases can
71
+ backfill the existing reason entries, but cannot recover payloads overwritten
72
+ before this schema existed; durable payload history begins after migration.
73
+
30
74
  ## §3 The firing rule
31
75
 
32
76
  A step's eligibility depends on its consume mode:
@@ -127,13 +171,26 @@ Held artifacts (`isHeld`, §20) also surface as `stalled: true` in
127
171
  irreversible side effect and must not silently re-fire; a human must `retry` or
128
172
  fix the upstream cause.
129
173
 
174
+ A `reject()` (judgment verdict) requires the target to already be a *built*
175
+ version — `green` or `submitted` — and refuses otherwise (a thrown Error): an
176
+ `owed` artifact has no build to render a verdict on (rejecting it would burn a
177
+ `judgmentRejects` toward the cap above with zero build attempts, a silent
178
+ freeze), and a `retracted` collection member is terminal (§11.3) — no firing
179
+ shape can ever rebuild it, so flipping it back to a live `rejected` debt would
180
+ wedge the instance.
181
+
130
182
  Clearing a stall:
131
183
  - **`retry`** — reset *both* counters to 0 and re-owe the artifact (optionally
132
184
  with fresh guidance appended as a `retry` reason). The only path that resets
133
185
  the counters. Also clears the held condition: a `retry` appends a `'retry'`
134
186
  reason entry, so the last entry's `kind` is no longer `'invalidated-irreversible'`
135
- and `isHeld` returns false.
136
- - **`retract`** — drop the member (collection elements).
187
+ and `isHeld` returns false. Requires the same consume-edge authority as
188
+ `reject`/`retract` (§4.1), and refuses a `retracted` target — retract is
189
+ final, and a bare collection element has no producer firing that could ever
190
+ rebuild it.
191
+ - **`retract`** — drop the member (collection elements), terminally. Requires
192
+ the same consume-edge authority as `reject` (§4.1): only a step that
193
+ consumes the member's stem (or human/engine) may retract it.
137
194
 
138
195
  ## §7 The forward cascade (level-triggered)
139
196
 
@@ -155,7 +212,10 @@ order-independent — re-running `settle()` on a healthy graph yields no ops.
155
212
 
156
213
  - **§11.1 produce `src[]`** — the producer `emit`s an unknown number of bare
157
214
  elements (`src[0]`, `src[1]`, …), then `seal`s. The seal is itself an artifact
158
- (`sealOf = src`); the collection is "complete" when the seal is green.
215
+ (`sealOf = src`); the collection is "complete" when the seal is green. Once
216
+ the seal is green, a further `emit` on the same open lease is refused
217
+ (`sealed-rejected`) rather than silently growing a "complete" set; the lease
218
+ stays open so the run can still close.
159
219
  - **§11.2 map `src[$i]`** — fan-out: one firing per element, `${INDEX}` bound.
160
220
  - **§11.x reduce `src[*]`** — fan-in: see §3.
161
221
  - **§11.x reduce with suffix `src[*].child`** — fan-in one level deeper: the
@@ -501,10 +561,10 @@ Shape rules:
501
561
  When the engine spawns a child instance, it passes `producedBy: { parentWf, parentPath }` to `createInstance`, which persists it via the store. The coordinate serves three duties:
502
562
 
503
563
  1. **Re-attach on reap**: when a child run is reaped, the engine re-attaches via the stored link.
504
- 2. **Reverse lookup**: `store.findChildByParent(parentWf, parentPath)` — the never-duplicate guard.
564
+ 2. **Reverse lookup**: `store.findChildByParent(parentWf, parentPath)` — the re-attach lookup (returns the *oldest* matching child deterministically, `ORDER BY created_at, id`; the never-duplicate *guarantee* lives in the atomic spawn plus the unique index, §23.6.9).
505
565
  3. **Cascade-up anchor**: the engine reads `producedBy` to propagate the child's outcome to the parent.
506
566
 
507
- **Storage**: two nullable columns on the `workflow` table — `produced_by_wf TEXT` and `produced_by_path TEXT` (both null for a top-level instance). Two columns (not a JSON blob) because the reverse lookup `(parentWf, parentPath) → child` must be SQL-indexable. The index `workflow_produced_by ON workflow(produced_by_wf, produced_by_path)` makes the lookup O(1). Added by the additive migration in `store.migrate()` (schema version 3).
567
+ **Storage**: two nullable columns on the `workflow` table — `produced_by_wf TEXT` and `produced_by_path TEXT` (both null for a top-level instance). Two columns (not a JSON blob) because the reverse lookup `(parentWf, parentPath) → child` must be SQL-indexable. The index `workflow_produced_by ON workflow(produced_by_wf, produced_by_path)` makes the lookup O(1). Added by the additive migration in `store.migrate()` (schema version 3). A second, **partial UNIQUE** index `workflow_produced_by_unique` on the same two columns (schema version 8, `WHERE` both coords are `NOT NULL` so top-level instances with NULL coords never conflict) makes a duplicate child physically impossible; it is created only when no legacy duplicates already exist (see §23.6.9).
508
568
 
509
569
  ### §23.3 calls: steps are machine-handled
510
570
 
@@ -531,12 +591,12 @@ The engine ships `maintainCalls` in `engine.ts` — the engine-internal method t
531
591
  Called at the top of every parent `tick` (outside any transaction), after `provideInput` on the parent (so a newly-supplied human input is immediately re-provided to any mapped child), and as a cascade-up prompt after child progress. For each `calls:` step in the parent def:
532
592
 
533
593
  1. **Gate check**: `gateStems = Object.values(callsInputs)` (parent artifact names wired to child inputs). Gate is ready when every gate stem is green.
534
- 2. **Re-attach guard**: `findChildByParent(parentWf, callsPath)` — spawn only when no child exists (`undefined`). This prevents duplicate children across crashes and re-ticks.
535
- 3. **Spawn**: if gate is ready and no child, `createInstance(step.calls, { producedBy, provide: gateValues })`. The parent calls: artifact stays `owed`.
594
+ 2. **Re-attach guard**: `findChildByParent(parentWf, callsPath)` — spawn only when no child exists (`undefined`). This re-attaches (rather than re-spawns) across crashes and sequential re-ticks; it does NOT by itself stop *concurrent* ticks in separate processes, which can each read `undefined` here before either inserts — that race is closed by the atomic spawn (§23.6.9). A second guard sits alongside it (§23.6.7 F2): if no child exists AND the parent calls artifact is already `rejected` on a schema refusal, skip the spawn attempt entirely while the gate stems' fingerprint is unchanged from the one stamped at refusal time — a moved gate is the only thing worth retrying against.
595
+ 3. **Provision**: if gate is ready, `provisionCallsChild(parentWf, step, callsStem, gateStems)` — a single `BEGIN IMMEDIATE` (§23.6.9) that re-reads the parent snapshot inside the write lock, then finds-or-creates the child AND syncs every mapped `callsInputs` value from that same fresh snapshot. It absorbs both the old spawn and the old re-provide (step 5) into one atomic read-verify-write, so a child is never seeded or re-provided from a snapshot older than its committing tx. The pre-reads above (gate, `findChildByParent`, F2 fingerprint, depth) are OPTIMISTIC — they decide only *whether* to attempt; the helper re-verifies in-tx and aborts silently (returns `null`, nothing written) if the gate re-armed or an F2 debt landed since. Instance/`settled` events fire only when this call created the child; a `commit`/`provide` fires for each input it re-wrote. The parent calls: artifact stays `owed`. §23.6.7 (F2): a child input-schema refusal here (seed or re-provide) is caught narrowly at the call site (`SchemaRefusalError` only — a genuine bug still throws) and recorded as a debt on the parent calls artifact instead of crashing the tick.
536
596
  4. **Outcome read**: read the child's declared `outputs:` artifact (exactly one, validated at load time). If it is green, machine-green the parent's calls: artifact.
537
- 5. **Re-provide**: for each `callsInputs` mapping, if the parent's value differs (deep-equal) from what the child holds, `provideInput(child, inputName, newValue)`. The child re-runs internally.
538
- 6. **Machine-green**: set parent calls: artifact to `acceptance: 'green'`, `version + 1`, `value = child outcome value`, `fingerprint = computeFingerprint(parentArts, gateStems)`. Then `settle(parentWf)` so downstream (teardown) fires. Do NOT set `terminal` — the calls: artifact must be re-armable if gate inputs move.
539
- 7. **Re-arm on child working**: if the child's outcome is no longer green (e.g. re-provide re-armed it) but the parent calls: artifact is green, re-arm the parent calls: artifact to `owed`. This handles gate re-arm correctly even though `deliver` step has `consumes: []` (the pure cascade cannot detect fingerprint mismatch for calls: steps).
597
+ 5. **Re-provide**: folded into step 3's atomic provision — `provisionCallsChild` syncs every changed `callsInputs` mapping (deep-equal check) inside the same tx that finds-or-creates the child, so the re-provide can no longer race a concurrent parent advance across a separate `provideInput` cascade. The child re-runs internally on each changed input. §23.6.7 (F2): same narrow schema-refusal handling as spawn — a child-illegal re-provided value becomes a debt on the parent calls artifact, not a thrown cascade.
598
+ 6. **Machine-green**: set parent calls: artifact to `acceptance: 'green'`, `version + 1`, `value = child outcome value`, `fingerprint = computeFingerprint(parentArts, gateStems) plus the child-outcome version pin` (§23.6.8, F4) — but only when the child outcome's version has moved past whatever version is currently pinned on the parent artifact. Then `settle(parentWf)` so downstream (teardown) fires. Do NOT set `terminal` — the calls: artifact must be re-armable if gate inputs move.
599
+ 7. **Re-arm on child working**: if the child's outcome is no longer green (e.g. re-provide re-armed it) but the parent calls: artifact is green, re-arm the parent calls: artifact to `owed`. This handles gate re-arm correctly even though `deliver` step has `consumes: []` (the pure cascade cannot detect fingerprint mismatch for calls: steps). This re-arm is unconditional on the pin — the pin only gates re-greening, never gates reopening to `owed`.
540
600
 
541
601
  #### §23.6.2 Cascade-up prompt
542
602
 
@@ -552,11 +612,68 @@ A child that greens its declared outcome with a status-bearing value (e.g. `{sta
552
612
 
553
613
  #### §23.6.5 Gate fingerprint and re-arm
554
614
 
555
- The machine-green fingerprint covers only `gateStems` (the parent artifacts wired into the child via `callsInputs`). The child-outcome version is intentionally NOT included in the fingerprint — `fingerprintMatches` uses a key-count check that would fail if the child version key count differs from the gate stem count. The child-outcome re-green trigger is handled by `maintainCalls` value comparison (`deepEqual`), not by the pure cascade.
615
+ The machine-green fingerprint covers `gateStems` (the parent artifacts wired into the child via `callsInputs`) plus, as of F4 (§23.6.8), a reserved `__child_outcome_version__` key pinning the child outcome's version. The child-outcome re-green trigger itself is still handled by `maintainCalls` value comparison (`deepEqual`), not by the pure forward cascade (`fingerprintMatches`) — `eligibleFirings`/`settle`'s cascade never looks at a calls: artifact's fingerprint to decide re-arming, since a calls: step declares `consumes: []`.
556
616
 
557
617
  #### §23.6.6 Transaction composition
558
618
 
559
- `maintainCalls` runs OUTSIDE any open `store.tx()`. Each mutating action (spawn via `createInstance`, re-provide via `provideInput`, machine-green) opens its own `store.tx()`. No nested transactions — node:sqlite does not support nested `BEGIN IMMEDIATE`.
619
+ `maintainCalls` runs OUTSIDE any open `store.tx()`. Each mutating action (provision — spawn + re-provide — via `provisionCallsChild`, machine-green via `publishCallsGreen`, re-arm via `rearmCallsGreen`) opens its own `store.tx()`. No nested transactions — node:sqlite does not support nested `BEGIN IMMEDIATE`.
620
+
621
+ Each mutating action does its **read-verify-write in ONE `BEGIN IMMEDIATE`**, not just its write. `maintainCalls`'s pre-reads (the outcome/gate/pin reads before STEP 6, the reverse-lookup before spawn) are an OPTIMISTIC gate that decides only *whether* to attempt the action — never what to commit; every value the write depends on is re-read and re-verified inside the same transaction. Under WAL this closes the cross-connection interleave where a second connection advances the parent gate (to a newer version) or re-arms the child between the stale pre-read and the write: without it, a stale child value could be published under a fresh gate fingerprint, and the same tick would issue downstream work off that stale value. `publishCallsGreen` re-reads the parent artifact, child, child outcome and gate in-tx, verifies the child is still green, the gate still ready, the F4 pin not yet passed, and the child inputs still consistent with the gate the fingerprint will claim, then computes the fingerprint from that one snapshot and writes; any mismatch aborts (returns `false`, nothing written — no debt, no reasons, no events) and defers to the next tick. `rearmCallsGreen` is the mirror guard (re-arm only if the parent is still green AND the child outcome still not green in-tx). The `commit`/`settled` events fire only when the helper actually wrote, so an aborted pass is silent. Child provisioning follows the same single-`BEGIN IMMEDIATE` shape (§23.6.9): `provisionCallsChild` re-reads the parent snapshot in-tx, then finds-or-creates the child and syncs its inputs from that snapshot — the reverse-lookup read, the insert, and every input write are one atomic step, so a child is never created (spawn) or re-written (re-provide) from a snapshot older than its committing tx. This is the creation-side twin of the machine-green fix above.
622
+
623
+ #### §23.6.7 F2 — child input-schema refusal is a debt, not a thrown tick
624
+
625
+ A `calls:` step wires parent artifact values into the child's inputs (`callsInputs`), but the parent's own schema for that artifact (if any) can be looser than — or entirely absent from — the child's declared input schema. Before this fix, `createInstance`'s seed-provide validation and `provideInput`'s validation threw a bare `Error` on a schema mismatch; because `maintainCalls` runs at the top of every `tick()` with no catch, one such value made every subsequent `tick(parent)` throw — a permanent crash loop with no debt or stall visible in `status()`.
626
+
627
+ The fix: `createInstance`/`provideInput` now throw a dedicated `SchemaRefusalError` (carrying the offending input name and schema issues) instead of a bare `Error` on a schema mismatch. `maintainCalls`'s STEP 3 provision — `provisionCallsChild`, which now covers both spawn and re-provide — surfaces the refusal (from the child seed or an input sync, rolling the whole provision tx back) and the call site catches `SchemaRefusalError` narrowly — any other error still propagates, since that's a genuine bug, not an expected refusal. On catch, the parent calls artifact is recorded as a debt with the same shape `green()` uses for its own schema-reject branch: `acceptance: 'rejected'`, `schemaRejects + 1`, a `validation`-kind reasons entry naming the child input and the schema issues. The tick then proceeds instead of throwing.
628
+
629
+ While the parent calls artifact sits `rejected` on a schema refusal and the gate stems' fingerprint (stamped at refusal time) is unchanged, `maintainCalls` does not re-attempt the spawn (STEP 2's guard) nor re-green from a rejected state (STEP 6 short-circuits on `acceptance === 'rejected'`) — re-trying the same illegal value every tick would just refuse again. A human `retry` clears the counter and re-arms to `owed`; once the parent value is fixed (the gate's fingerprint moves), the next tick spawns/re-provides normally.
630
+
631
+ The human's own `provideInput` call on the PARENT's own input artifact is unaffected — that validation happens against the PARENT's own schema, inside `provideInput`'s own transaction, before the calls: cascade (which runs `provideInput` again, this time against the CHILD) is ever reached. A parent-illegal value is refused (as before); a parent-legal-but-child-illegal value commits at the parent and surfaces as a debt on the calls: artifact per this section.
632
+
633
+ #### §23.6.8 F4 — reject on a calls artifact propagates to the child; the mirror is version-pinned
634
+
635
+ Before this fix, a consumer's `reject()` (or a human `skip()`) on a `calls:`-produced artifact was silently reversed on the very next tick: `maintainCalls`'s STEP 6 re-greens whenever the child outcome is green and the parent isn't already green-with-the-same-value, with no awareness that a verdict had landed in between. A deterministic consumer reject would inflate `judgmentRejects` on the parent artifact forever without ever reaching the child that actually needs to change — a livelock.
636
+
637
+ **Reject propagation.** `reject(parentWf, callsPath, by, text)` detects a `calls:`-produced artifact (the producing step declares `calls:`) and forwards the verdict instead of running the normal producer-invalidation path:
638
+
639
+ - Resolve the child via `store.findChildByParent(parentWf, callsPath)`. If no child was ever spawned, refuse the reject (`cannot reject '<path>': no child instance has been spawned yet`) — consistent with the existing verb-guard rule that a verdict needs a built version.
640
+ - The CHILD's declared outcome artifact goes `acceptance: 'rejected'`, `judgmentRejects + 1`, with a reasons entry carrying the verdict text and `by: 'parent:<by>'` — the `parent:` prefix marks the entry as an engine-forwarded verdict, not a direct one, in the child's own audit thread. The forward is engine-internal: authority was already checked against the PARENT def (`assertAuthority` runs before the calls-detection branch); the child's own `assertAuthority` is never consulted for this call.
641
+ - The PARENT calls artifact is reopened to `owed` (never left `rejected`) with a `reopen`/`structural` reasons entry, and its fingerprint is stamped with the rejected child outcome's version (the pin — §below). "Owed, waiting on the child to rebuild" is the honest status, and it lets STEP 6's existing mirror logic pick the new value up unmodified once the child recovers.
642
+ - The child's own producer re-arms on the normal knock-back loop — the verdict text rides the child producer's `owes` thread on its next firing, exactly like any other rejected artifact. Driving that re-arm means firing the CHILD instance's own tick; a deep `tick(parentWf)` does this for you by descending into the child (see the sweeping note below), and `rejectCallsArtifact` also prompts `maintainCalls(parentWf)` so the parent's own `owed`/pin state is visible immediately. What re-arms the child's producer step is the child's own tick, not the parent mirror — the deep descent is simply how a single parent tick reaches it.
643
+ - If the child keeps failing, `judgmentRejects` accrues on the CHILD artifact and the child stalls at its own `maxAttempts` — the liveness bound lands on the instance actually doing the work, not on the parent's pass-through artifact.
644
+
645
+ **Version-pinned mirror.** A `calls:` step declares `consumes: []`, so the parent artifact's own fingerprint machinery never sees its real input — the child outcome, which lives in another instance entirely. The fix threads a synthetic key, `Engine.CHILD_OUTCOME_PIN_KEY` (`'__child_outcome_version__'`), through the parent calls artifact's `fingerprint` map alongside the gate stems, holding the child outcome version the parent artifact currently rests on:
646
+
647
+ - STEP 6 stamps this pin whenever it machine-greens (to the child outcome's version at that moment), and only machine-greens at all when the child outcome's version has moved **past** the currently-stamped pin (or no pin is stamped yet).
648
+ - The reject-propagation path above stamps the same pin (to the just-rejected child outcome's version) when it reopens the parent to `owed`.
649
+ - `skip()` stamps the same pin when skipping a `calls:`-produced artifact (detected the same way as `reject()`, by checking `producingStep.calls`) — since `skip`'s normal fingerprint (`requiredInputs`-driven) is `consumes: []`-empty here too.
650
+ - All three sites compute "what child-outcome version does this rest on" through one helper, `Engine.childOutcomePin(parentWf, callsPath)`, so the pin logic lives in exactly one place.
651
+
652
+ This gives the two orderings the settled design calls for:
653
+
654
+ - **Order A** — a human skips the green calls artifact having seen child result v3; the child stays at v3. The pin (v3) matches the child's current version, so `pastPin` is false and STEP 6 never re-greens: the skip survives arbitrary ticks. The machine never overrides a decision made on current evidence.
655
+ - **Order B** — the same skip is pinned to v3, but the gate later moves, the child is re-provided, and it rebuilds to v4. Now `childOutcomeArt.version (4) > pinnedVersion (3)`, so `pastPin` is true: STEP 6 re-arms and mirrors the v4 value. A stale, months-old skip cannot permanently gag a fresh child result.
656
+
657
+ The `M2B-REARM` branch (§23.6.1 step 7 — child un-greened while parent stays green) is unaffected by the pin: it only checks `isGreen(childOutcomeArt)`, so it still reopens the parent to `owed` regardless of what's pinned. The pin governs only the re-green transition (`owed`/`rejected` → `green`), never the green → `owed` reopen.
658
+
659
+ **Deep tick — descend into `calls:` children from the parent tick.** `tick(parentWf)` is **deep by default**: after the parent's own tx settles, it walks every live `calls:` child and ticks each one in its own tx, folding the children's orders, reaps, deferrals, and `dueAt` up into the parent's `TickResult`. One `tick(rootWf)` therefore drives the whole tree — the caller no longer has to discover children and tick them itself. This is what makes a propagated reject (§23.6.8 above) resolve on a plain parent sweep: the reject re-arms work in the CHILD instance, and the deep descent is what fires the child's own tick so its producer step actually gets an order.
660
+
661
+ - **Descent condition.** The parent descends into a child step only when all three hold: (1) the step's **gate is green** (same readiness `maintainCalls` uses to spawn/mirror — see `callsGateReady`), (2) a **child instance exists** (`findChildByParent`), and (3) the parent's `calls:` artifact for that step is specifically **`owed`** — an outstanding producer debt, not merely non-green. `owed` is the sole live debt: it covers the fresh spawn, the F4 propagated-reject reopen (§23.6.8), and a gate-move re-arm. A `skipped`/`rejected`/`retracted` mirror is a dead or refused branch and is **not** descended (issuing child work for it would resurrect a settled decision); a re-armed gate with a still-green mirror, or a step whose child was never spawned, is likewise skipped — descent chases only real, outstanding child work. `callsDescendTargets(parentWf, def)` computes this set.
662
+ - **Own-tx-per-frame.** Descent runs *outside* the parent's transaction (`store.tx` is non-re-entrant — `BEGIN IMMEDIATE` would deadlock on itself). Each child frame opens its own tx via its own `tickInternal` call. The descent condition above is an OPTIMISTIC pre-read (computed outside any tx); the child frame carries the `calls:` edge (`parentEdge`) and, inside its own claim tx, re-verifies the parent gate + child-input consistency — the same predicate `publishCallsGreen` uses — before issuing any order, so a concurrent parent advance that superseded the parent value between the pre-read and the claim issues nothing and skips the subtree. This is the descent-path twin of the in-tx read-verify-write invariant §23.6.6 establishes for the publish/provision paths. The recursion carries a `visited` set so a diamond (two parents reaching the same child) or an accidental cycle ticks each instance at most once.
663
+ - **Aggregation.** Child orders are concatenated onto the parent's; `reaped` sums; `dueAt` takes the minimum across the tree so the caller's next-wake is the earliest across all levels. Each folded `DeferredFiring` carries a `workflow` field naming the instance it belongs to — **absent means the ticked root, present means a descendant** — so a caller can still tell which instance a deferral came from. The single `now` is threaded through the whole descent, so a reap TTL that trips at the parent's clock trips consistently for children in the same sweep.
664
+ - **Opt-out.** `tick(parentWf, { deep: false })` (CLI `--shallow`) ticks only that one instance — no descent, orders all carry the root's `workflow`. Use it to drive a single instance deliberately (tests, targeted retries); the default deep tick is what production drivers want.
665
+
666
+ **Status child-summary.** `status(parentWf)` enriches each `calls:`-debt entry with a `child: ChildStatusSummary` (`{ workflow, def, done, stalled, debts }`) when a child has been spawned for that step. `stalled` is true when the child (or, recursively, a grandchild on an unpaid `calls:` path) has any stalled debt — a worker that hit `maxAttempts` with no green outcome. This lets a conductor see, from the parent alone, that a `calls:` debt is blocked on a stuck child without separately walking into the child's own `status`. Like `failedRuns`/`attempts`, the field is engine-populated cross-instance state; `model.ts`'s pure single-instance `workflowStatus` never sets it.
667
+
668
+ **Discovering children directly.** A driver can still enumerate children itself — `store.listChildrenByParent`/`findChildByParent` give the reverse index from a parent id — and a propagated reject remains visible via the CHILD's own `status(childWf).debts` (the rejected outcome artifact appears there with `acceptance: 'rejected'`). But with deep tick as the default, a driver that sweeps only roots already reaches all live descendants; explicit child enumeration is for inspection and for the `--shallow` single-instance path, not a requirement for liveness.
669
+
670
+ #### §23.6.9 REL-5 / C2 — atomic fresh-snapshot child provision (never two children, never a stale seed)
671
+
672
+ Before REL-5, spawn read `findChildByParent` outside any transaction and then called `createInstance`, which opened its own transaction — a check-then-insert split across two tx boundaries and backed only by a *non-unique* reverse index. Two driver ticks (even in separate processes) could each observe "no child" and each insert one, leaving duplicate children for the same parent coordinate. REL-5 made the check and the insert one atomic step. C2 then widened that same tx to also carry the parent-snapshot re-read and the input sync, closing the creation-side twin of the C1 publish race (§23.6.6): a child seeded, or an existing child re-provided, from a stale parent value while a concurrent tick advanced the gate.
673
+
674
+ - **`provisionCallsChild(parentWf, step, callsStem, gateStems, now)`** (REL-5's `spawnChildIfAbsent`, widened by C2) wraps a fresh parent-snapshot re-read, `findChildByParent`, the find-or-create insert, AND the sync of every mapped `callsInputs` value in a *single* `BEGIN IMMEDIATE`. The first tick to acquire the write lock inserts the child; any other serializes behind it, re-reads the committed row, and re-attaches. Because the parent snapshot is re-read inside the write lock, a child is never seeded (spawn) or re-written (re-provide) from a value older than its committing tx — the fresh in-tx read IS the guard, so "never regress a child input" needs no version comparison. It returns `{ childId, created, provided }`, or `null` on a silent in-tx abort (the gate re-armed, or an F2 debt landed, since the optimistic pre-read). The caller fires `instance`/`settled` only when `created` is true and a `commit`/`provide` for each name in `provided`, so a re-attach with no input change stays silent — matching the pre-REL-5/pre-C2 per-action semantics. A `SchemaRefusalError` (a seed or re-provided parent value illegal per the child's input schema) rolls the whole tx back with no orphan row and no partial input sync, preserving the §23.6.7 F2 contract.
675
+ - **Partial UNIQUE index `workflow_produced_by_unique`** (schema version 8, on `(produced_by_wf, produced_by_path)` where both are `NOT NULL`) is the physical backstop that makes a duplicate impossible for any future writer path; `provisionCallsChild` also catches the unique-constraint error and retries the whole tx once — the retry finds the winner in-tx and syncs its inputs — as a belt-and-suspenders defense (unreachable under node:sqlite's write-lock-serialized connections).
676
+ - **Legacy duplicates are tolerated, not deleted.** If a pre-v8 database already holds duplicate children from the old race, the unique index is *not* created (that would fail) and no data is removed — the migration skips index creation while any duplicate exists (a cheap aggregate re-checked on every open) and relies on the atomic spawn to prevent new ones. Once the operator removes the legacy duplicates, the next open creates the index. Meanwhile `findChildByParent` returns the *oldest* matching child (`ORDER BY created_at, id LIMIT 1`) so every reader converges on the same winner rather than an arbitrary row.
560
677
 
561
678
  ## §24 Artifact judges (`judges:`)
562
679
 
@@ -690,6 +807,13 @@ verbs with no new CLI surface:
690
807
  so a human clearing a judge-reject stall doesn't leave a stale partial
691
808
  ledger for the rebuild to inherit.
692
809
 
810
+ A human bypass's scope is deliberately narrow: it skips the judge ledger and
811
+ the lease/CAS machinery, but not the artifact's declared output schema — a
812
+ human `green` on a produce with a `schema:` is validated exactly like a
813
+ producer commit (§18), refused with a thrown Error (no version bump, no
814
+ schemaRejects bump — there is no retry loop to protect on this path) rather
815
+ than silently landing a value downstream consumers assume is schema-valid.
816
+
693
817
  ### §24.7 `CommitResult['outcome']` — three success outcomes, two failure
694
818
 
695
819
  `green()`'s result vocabulary grows by two, both **successes**:
@@ -887,21 +1011,39 @@ sibling's auto-skip.
887
1011
  Auto-skip is implemented purely inside `maintainDecisions` (model.ts) — the
888
1012
  same pure, level-triggered fixpoint function §11.8/§12.3 already uses for
889
1013
  reject/retract/skip/rearm/pin/arm. For every `exactlyOne`/`atMostOne` group
890
- with exactly one `green` member, every `owed`/`rejected` sibling gets a `skip`
891
- op with `rejectKind: 'exclusive'` (a new `RejectKind`, alongside `judgment` /
892
- `structural` / `validation` / `invalidated-irreversible` — a liveness-
893
- accounting category, distinct from the skip's `ReasonAction`, which stays
894
- `'skip'`). Because `Engine.settle()` runs this cascade to a full fixpoint
895
- synchronously at the end of every `green()` call, the auto-skip is already
896
- visible by the time the winning `green()` call returns — a caller never
897
- observes an intermediate state where the winner is green but the loser is
898
- still `owed`.
1014
+ with exactly one `green` member, every `owed`, `rejected`, **or `submitted`**
1015
+ sibling gets a `skip` op with `rejectKind: 'exclusive'` (a new `RejectKind`,
1016
+ alongside `judgment` / `structural` / `validation` / `invalidated-irreversible`
1017
+ — a liveness-accounting category, distinct from the skip's `ReasonAction`,
1018
+ which stays `'skip'`). Because `Engine.settle()` runs this cascade to a full
1019
+ fixpoint synchronously at the end of every `green()` call, the auto-skip is
1020
+ already visible by the time the winning `green()` call returns — a caller
1021
+ never observes an intermediate state where the winner is green but the loser
1022
+ is still `owed` or `submitted`.
1023
+
1024
+ A `submitted` sibling is an OUTSTANDING state (§15): left uncovered by this
1025
+ cascade, a judged group member that submits before its sibling wins can never
1026
+ be settled — its judge order is correctly suppressed by §26.5's eligibility
1027
+ pre-filter, but the artifact itself just sits `submitted` forever, wedging the
1028
+ instance out of `done: true` permanently. Covering `submitted` here closes
1029
+ that gap. Skipping a `submitted` sibling also **clears its `approvals`
1030
+ ledger** (mirrors the cascade-reject approvals-clear, §24 §4.3): a partial
1031
+ judge sign-off recorded before the skip must never leak onto a later
1032
+ resubmission if the winning sibling is later un-greened and the branch
1033
+ revives — `Engine.applyOp`'s `'skip'` branch and its pure in-memory twin,
1034
+ `applyOpInMemory`'s `'skip'` branch (the checker's own reimplementation, since
1035
+ `settleInMemory` calls `maintainDecisions` directly and inherits the cascade
1036
+ fix for free, but `applyOpInMemory` mirrors the engine's mutation 1:1 and
1037
+ needs the same approvals-clear applied independently), both clear `approvals`
1038
+ on the skipped artifact whenever its prior acceptance was `submitted`.
899
1039
 
900
1040
  Re-arming an auto-skipped sibling needs zero group-specific code: it goes
901
1041
  through the exact same generic skip-re-arm mechanism (fingerprint-keyed,
902
1042
  §7) that already re-arms a manually-skipped branch when its upstream inputs
903
1043
  move. `rejectKind: 'exclusive'` only changes how the artifact is
904
- *classified* for liveness accounting; it does not change how it re-arms.
1044
+ *classified* for liveness accounting; it does not change how it re-arms — and
1045
+ the cleared approvals ledger travels with it, so a re-armed (or freshly
1046
+ re-produced) sibling always starts its judge ledger from empty.
905
1047
 
906
1048
  ### §26.3 Grammar and validation
907
1049
 
@@ -946,16 +1088,19 @@ sibling in this stem's group already sit green?" Every WORKER-firing branch
946
1088
  output path that is currently group-blocked, so the automatic sweep (`tick`)
947
1089
  never dispatches an order — in particular, never spawns a judge order for a
948
1090
  `submitted` sibling — that `groupCasCheck` is guaranteed to refuse the moment
949
- it tries to land green. This closes a real gap: before this fix, a `submitted`
950
- group member (one gated by `judges:`) was never auto-skipped by §26.2's
951
- cascade (auto-skip only acts on `owed`/`rejected` siblings), so its judge kept
952
- firing every tick until a human intervened — a wasted subagent spawn on every
953
- tick, not a correctness bug (the judge's `green()` call was always correctly
954
- refused), but pure waste this fix eliminates (`test/groups.test.ts` scenario
955
- (f2)). `groupCasCheck` itself stays load-bearing for a judge order that was
956
- already claimed (in flight) before the winner landed — the pre-filter only
957
- stops a *new* order from being offered, so scenario (f) still exercises the
958
- commit-time refusal against that in-flight race.
1091
+ it tries to land green. Historically this pre-filter was the only defense for
1092
+ a `submitted` group loser: §26.2's cascade covered only `owed`/`rejected`
1093
+ siblings, so a `submitted` member just sat there — its judge order suppressed
1094
+ from firing again, but the artifact itself never settled, wedging the
1095
+ instance out of `done: true` forever (a liveness bug, not merely wasted
1096
+ spawns). §26.2 now also auto-skips a `submitted` loser in the same settle as
1097
+ the winner's commit, so this eligibility pre-filter and that cascade converge:
1098
+ a `submitted` sibling is skipped essentially as soon as it stops being newly
1099
+ eligible (`test/groups.test.ts` scenario (f3)). `groupCasCheck` itself stays
1100
+ load-bearing for a judge order that was already claimed (in flight) before the
1101
+ winner landed — the pre-filter and the cascade both only act going forward, so
1102
+ scenario (f) still exercises the commit-time refusal against that in-flight
1103
+ race.
959
1104
 
960
1105
  Suppression applies to the automatic sweep only. A human `retry` re-arms the
961
1106
  named artifact directly and does not itself run `eligibleFirings` — but the
@@ -1098,6 +1243,88 @@ prefixing untouched (there are no stems inside `x:` to rewrite — it's
1098
1243
  opaque); a child definition's own top-level `x:` stays on the child def and
1099
1244
  is not merged into the parent's.
1100
1245
 
1246
+ ### §27.4 `worker:`/`command:`/`spec:` — declaring the executor
1247
+
1248
+ `x:` (§27.3) is a namespaced escape hatch for arbitrary external vocabulary.
1249
+ `worker:` is a narrower, purpose-built field for one specific job: telling
1250
+ whatever dispatches orders *which kind* of executor a step's order is for. It
1251
+ follows the same opaque-passthrough contract as `model` — the engine never
1252
+ interprets it, only carries it — but unlike `model` (a free-form quality
1253
+ hint) and unlike `x:` (fully unvalidated contents), `worker:` gets two narrow,
1254
+ hard-coded shape rules, because the two most common worker types have a
1255
+ structural precondition the engine can cheaply catch at load time instead of
1256
+ letting it surface as a confusing runtime stall.
1257
+
1258
+ **The contract, four clauses:**
1259
+
1260
+ 1. **Default is `'agent'`, and that default is silent.** A step (or judge)
1261
+ that omits `worker:` entirely behaves exactly as it did before this
1262
+ feature existed — every def in this repo predating `worker:` is
1263
+ unaffected, byte for byte. The default is applied at validation and
1264
+ engine-order-building time, never written back into the parsed def.
1265
+ 2. **`worker: command` requires `command:`.** A step (or judge) whose
1266
+ effective worker is `'command'` and carries no `command:` is a load-time
1267
+ `DefError`: `` step '<name>' has worker 'command' but no command: ``. Any
1268
+ other worker string has no such requirement — `command:` is only ever
1269
+ validated when the worker is literally `'command'`.
1270
+ 3. **`worker: agent` (explicit) requires a non-empty `body:`.** This check is
1271
+ deliberately scoped to an *explicit* `worker: agent`, not the *defaulted*
1272
+ value — i.e. `validateDef` checks `l.worker === 'agent'`, never
1273
+ `(l.worker ?? 'agent') === 'agent'`. That distinction matters: plenty of
1274
+ existing fixtures and generator-only steps rely on `buildStep`'s
1275
+ empty-body default and never write `worker:` at all. Checking the
1276
+ defaulted value would retroactively break every one of them. Checking
1277
+ only the explicit form catches the actual mistake this rule exists for —
1278
+ someone opts into `worker: agent` on purpose and forgets the prompt —
1279
+ without touching a single pre-existing def.
1280
+ 4. **`command:` and `spec:` are otherwise opaque.** `command` is
1281
+ shape-checked as a string (`asString`); `spec` is shape-checked as a plain
1282
+ map (`asExtension` — the same helper `x:` uses, reused verbatim, no new
1283
+ helper). Neither's *contents* are read, parsed, or interpreted by the
1284
+ engine. `spec` exists for cases where `command` alone isn't enough
1285
+ configuration (a timeout, a working directory hint, environment
1286
+ overrides) without inventing a new field per knob — the same "shape, not
1287
+ contents" philosophy as `x:`, just scoped to one step instead of the
1288
+ whole def.
1289
+
1290
+ **The optional `workers:` allow-list.** A definition can declare `workers:
1291
+ [agent, command, …]` at the top level — a typo guard, nothing more. When
1292
+ present, `validateDef` rejects any step or judge whose *effective* worker
1293
+ (after the `?? 'agent'` default is applied) isn't in the list. This runs
1294
+ **after** the default, deliberately: a def that declares `workers: [command]`
1295
+ (excluding `'agent'` on purpose) still fails a step that omits `worker:`
1296
+ entirely, because that step's effective worker is `'agent'` and `'agent'`
1297
+ isn't in the list. This is the intended behavior — once a def opts into the
1298
+ allow-list, it's exhaustive, and a step relying on the silent default doesn't
1299
+ get a free pass around it. A def with no `workers:` key accepts any worker
1300
+ string; there is no engine-wide registry of valid worker types to check
1301
+ against.
1302
+
1303
+ **Pass-through.** `worker`, `command`, and `spec` all ride `buildOrder` onto
1304
+ the emitted `Order` untouched — `Order.worker`, `Order.command`, `Order.spec`
1305
+ — the same pass-through contract as `Order.model` and `Order.x`. A step that
1306
+ never sets them emits an order with all three fields absent, identical to
1307
+ before this feature existed.
1308
+
1309
+ **Judges get the same fields, for free.** §24's `synthesizeJudgeSteps` turns
1310
+ each `judges:` entry into an ordinary `StepDef` — so a judge entry accepting
1311
+ `worker:`/`command:`/`spec:` and having the exact same `validateDef` rules
1312
+ apply to it isn't a separate code path, it's the same rules running against
1313
+ an already-existing synthesized step. A judge can therefore be a
1314
+ deterministic check (a script's exit code) instead of an LLM verdict, without
1315
+ any new validation logic. Note the pre-existing, orthogonal judge
1316
+ requirement — every judge needs `body:` or `bodyFile:` regardless of
1317
+ `worker:` — still applies; a `worker: command` judge still declares a
1318
+ `body:`, it's simply unread by a non-agent dispatcher.
1319
+
1320
+ **Scope notes**, mirroring §27.3's: `worker`/`command`/`spec` are additive
1321
+ and inert — a definition that never sets any of the three is unchanged in
1322
+ behavior and in `hashDef` terms. They live on the same two authored,
1323
+ engine-fired shapes as `x:` (a normal step, and — new here — a judge entry),
1324
+ participate in §28 pinning the same way (snapshotted at `createInstance`,
1325
+ and a later edit is real `hashDef` drift), and pass through `expandIncludes`
1326
+ prefixing untouched (there are no stems inside them to rewrite).
1327
+
1101
1328
  ## §28 Instance-to-definition pinning
1102
1329
 
1103
1330
  Every prior section treats a workflow *definition* as the stable thing and a
package/docs/embedding.md CHANGED
@@ -25,10 +25,12 @@ const { engine, store } = createEngine({
25
25
 
26
26
  | option | meaning |
27
27
  |-------------|---------|
28
- | `db` | SQLite path. `':memory:'` for an ephemeral store (great in tests). Defaults to `.owenloop/state.db`; parent dirs are created for a file path. |
29
- | `defs` | In-memory definitions as a `Map<string, WorkflowDef>` or an array of `WorkflowDef` (de-duped by name). Takes precedence over `defsDir`. |
28
+ | `db` | SQLite path. `':memory:'` for an ephemeral store (great in tests). Defaults to `.owenloop/state.db`; parent dirs are created for a file path. When the **default** path is used, a symlinked `.owenloop` directory — and a symlinked `state.db` file (or its SQLite `-wal`/`-shm`/`-journal` sidecars) inside a real `.owenloop` — is refused (filesystem-isolation guard against a hostile checkout redirecting state writes); an explicit `db` path is the caller's responsibility and is created/opened as-is. |
29
+ | `defs` | In-memory definitions as a `Map<string, WorkflowDef>` or an array of `WorkflowDef` (de-duped by name). Takes precedence over `defsDir`. Validated as a whole before use — see [In-memory definitions](#in-memory-definitions). |
30
30
  | `defsDir` | Directory of `*.yaml` definitions, loaded via `loadDefs`. A missing dir yields no defs (lenient, like the CLI), not an error. |
31
31
  | `reapTtlMs` | Forwarded to the `Engine` — the stranded-lease reap TTL. |
32
+ | `maxLeaseMs` | Forwarded to the `Engine` — an opt-in hard cap on total lease lifetime (per-step `maxLease:` overrides). Unset (default): no cap; heartbeats extend a lease indefinitely. Set it only as a runaway backstop — it can reap a healthy, still-beating job. |
33
+ | `maxCallDepth` | Forwarded to the `Engine` — the hard cap on `calls:` composition depth (root instance = depth 0). Defaults to 64. Defense in depth against a `calls:` cycle; only relevant when you hand-wire a custom `DefResolver` that construction-time validation can't inspect. |
32
34
  | `onEvent` | A push-style observer registered at construction (equivalent to `engine.subscribe`). See [Events](#events). |
33
35
  | `onListenerError` | Where a throwing listener's error is routed (default: swallowed). |
34
36
 
@@ -50,6 +52,11 @@ const engine = new Engine(store, (name) => {
50
52
  });
51
53
  ```
52
54
 
55
+ `loadDefs` already validates what it reads from disk. If you build a def set by
56
+ hand and want the same whole-set checks the factory applies (cross-def `calls:`
57
+ validity and cycle detection, not just per-def `validateDef`), run it through
58
+ the exported `finalizeDefs(rawMap)` before wiring the resolver over it.
59
+
53
60
  ## The worker step
54
61
 
55
62
  The shape is the same as a CLI wiring — `tick` to pull orders, run them, then
@@ -73,11 +80,59 @@ for (const order of orders) {
73
80
  const status = engine.status(wf); // { done, debts, eligible, blocked, inFlight }
74
81
  ```
75
82
 
76
- Each `order` is self-contained: `prompt`, `consumes` (the captured green
77
- inputs), `owes` (the owed outputs + their accumulated reason threads), plus
78
- `inputs`/`outputs`/`model`. A consumer rejecting an upstream artifact is just
79
- `engine.reject(wf, path, by, text)`; the forward cascade and stall liveness
80
- behave exactly as they do under the CLI, because it's the same engine.
83
+ Each `order` is self-contained: `workflow` (the instance it belongs to — see
84
+ deep tick below), `prompt`, `consumes` (the captured green inputs), `owes` (the
85
+ owed outputs + their accumulated reason threads), plus
86
+ `inputs`/`outputs`/`model`/`worker`/`command`/`spec`. A consumer rejecting an
87
+ upstream artifact is just `engine.reject(wf, path, by, text)`; the forward
88
+ cascade and stall liveness behave exactly as they do under the CLI, because
89
+ it's the same engine.
90
+
91
+ `engine.tick(wf)` is **deep by default**: after ticking `wf` it descends into
92
+ every live `calls:` child (recursively), folding their orders, `reaped`, folded
93
+ `deferred` (each descendant's deferral tagged with its `workflow`; a root-frame
94
+ deferral stays unstamped), and the tree-minimum `dueAt`
95
+ into the one `TickResult`. So an order in the list may belong to a child, not
96
+ `wf` — commit (`green`/`emit`/`seal`/`reject`) and `close` against
97
+ `order.workflow`, not the id you passed to `tick`. Pass `engine.tick(wf, { deep:
98
+ false })` to tick just that one instance (every order then carries `wf`). The
99
+ childless example above never triggers descent, so `order.workflow === wf`
100
+ throughout; it matters once a step declares `calls:`.
101
+
102
+ **Migrating from shallow ticking.** Because a single deep `engine.tick(root)`
103
+ can advance *many* workflow instances in one call, an embedder moving off the
104
+ one-workflow-per-tick assumption must key any per-workflow logic —
105
+ checkpointing, batching, an external transaction, a progress counter — on
106
+ `order.workflow`, not on the id it passed to `tick`. Don't assume every order in
107
+ one `TickResult` belongs to the instance you ticked; each order carries its own
108
+ `order.workflow`, and a folded deferral is stamped with a descendant's
109
+ `workflow` (absent means the root you ticked). `engine.tick(wf, { deep: false })`
110
+ (CLI `--shallow`) stays the deliberate single-instance escape hatch when you
111
+ want exactly the old behavior.
112
+
113
+ `order.worker` is where dispatch-by-executor-type earns its keep in an
114
+ embedder: rather than every order going to the same LLM-driving `runYourWorker`,
115
+ branch on it before deciding how to run the order.
116
+
117
+ ```ts
118
+ for (const order of orders) {
119
+ const result =
120
+ order.worker === 'command'
121
+ ? await runCommand(order.command!, order.spec) // order.command is opaque — never shelled out by owenloop itself
122
+ : await runYourAgent(order); // default / worker: 'agent' / anything else you handle the same way
123
+
124
+ const commit = engine.green(wf, order.run, order.outputs[0], result);
125
+ engine.close(wf, order.run);
126
+ }
127
+ ```
128
+
129
+ `worker`/`command`/`spec` are all optional and opaque — the engine only
130
+ shape-checks them at load time (`command` a string, `spec` a plain map) and
131
+ never reads their contents itself. `order.worker` is `undefined` when the
132
+ step never set it (today's default, unaffected by this feature). See
133
+ [`docs/design.md` §27.4](design.md) for the full contract and
134
+ [`docs/authoring.md`](authoring.md#worker--declaring-the-executor) for how to
135
+ declare it on a step.
81
136
 
82
137
  A runnable version of this lives at [`examples/embed.ts`](../examples/embed.ts):
83
138
 
@@ -131,9 +186,17 @@ The event union (exported as `EngineEvent`):
131
186
  commits (and the cascade has already settled inside that tx), so a listener
132
187
  that calls `status`/`tick`/`green` observes fully-committed, settled state —
133
188
  there is no open transaction to corrupt. A state-changing verb fires its
134
- specific `commit`/`instance` event followed by a `settled`; `close` fires only
135
- `closed` (it releases a lease, it doesn't touch artifact state); `tick` fires
136
- nothing (it hands you orders directly).
189
+ specific `commit`/`instance` event followed by a `settled`. `close` fires only
190
+ its `closed` lifecycle event and `tick` fires nothing of its own — `close`
191
+ otherwise just releases a lease and `tick` just hands you orders — but either
192
+ can advance `calls:` composition as a side
193
+ effect, and that composition fires events: a deep `tick` that spawns a child
194
+ emits `instance` + `settled`, and one that machine-greens or re-arms a parent
195
+ `calls:` artifact from a child's outcome emits `commit` + `settled` on the
196
+ parent; a `close` whose run belongs to a `calls:` child prompts that same
197
+ parent maintenance, so it too can emit `commit`/`settled` on the parent. Only
198
+ for an instance with no `calls:` parent or children does `close` fire just
199
+ `closed` and `tick` fire nothing.
137
200
  - **Synchronous, registration order.** The engine is single-writer and
138
201
  synchronous; listeners fire in the order they subscribed, on the calling
139
202
  thread. This is an in-process observer, not an async/cross-process bus —
@@ -163,6 +226,14 @@ const research = parseDef(/* a WorkflowDef-shaped object or YAML you parsed */);
163
226
  const { engine } = createEngine({ db: ':memory:', defs: [research] });
164
227
  ```
165
228
 
229
+ An in-memory `defs` set is validated as a whole — exactly like the filesystem
230
+ `defsDir` loader — before the engine is returned: `calls:` targets must exist,
231
+ `callsInputs` keys must be valid, a called def must have exactly one child
232
+ output, each def passes `validateDef`, and the set is checked for `calls:`
233
+ cycles. An invalid set **throws `DefError`** instead of silently registering.
234
+ The returned `defs` is a validated *copy*, so mutating the `Map`/array you
235
+ passed after construction no longer changes resolution.
236
+
166
237
  ## Lifecycle & concurrency
167
238
 
168
239
  - **Long-lived.** Create the `engine`/`store` once per database and reuse them;
@@ -0,0 +1,56 @@
1
+ # Declarative executor dispatch — demonstrates `worker:`/`command:`/`spec:`
2
+ # (§27.4 of docs/design.md).
3
+ #
4
+ # The engine never executes anything; `worker:` just labels which kind of
5
+ # executor a step's order is for, so the same def can mix an LLM-driven step
6
+ # with a deterministic, non-LLM one. `planner` omits `worker:` entirely (the
7
+ # default, unaffected `'agent'` path — every existing def in this repo stays
8
+ # exactly like this). `tester` declares `worker: command` with a real
9
+ # `command:` — a runner dispatching this order runs the command instead of an
10
+ # agent, no judgment involved. `tester`'s `result` produce is gated by a
11
+ # command judge (`ci-gate`): judges can be deterministic too, not just
12
+ # LLM-based — this one runs a check script and approves/rejects on exit status.
13
+ #
14
+ # Drive it:
15
+ # wf=$(owenloop create command-worker --provide plan='{"text":"add a cache layer"}' | jq -r .workflow)
16
+ # owenloop tick $wf # -> order for `planner` (worker: agent, default)
17
+ # owenloop green $wf <run> reviewed_plan --value '{"approved":true}'
18
+ # owenloop tick $wf # -> order for `tester` (worker: command)
19
+ # owenloop green $wf <run> result --value '{"exitCode":0}'
20
+ # owenloop tick $wf # -> order for the `ci-gate` judge (worker: command)
21
+ # owenloop green $wf <judge-run> result --value '{}' # judge approves -> result goes green
22
+
23
+ name: command-worker
24
+ title: Command-dispatched worker step
25
+ description: Mixes an agent step with a deterministic command step and a command judge.
26
+
27
+ inputs:
28
+ - name: plan
29
+ seedOwed: true # required: supply with --provide or `owenloop provide`
30
+
31
+ steps:
32
+ - name: planner
33
+ consumes: [plan]
34
+ produces: [reviewed_plan]
35
+ # worker: omitted here on purpose — the default/common case, completely
36
+ # unaffected by this feature. This step dispatches to an agent exactly
37
+ # like every step in every other bundled example.
38
+ body: |
39
+ Workflow ${WORKFLOW}, run ${RUN}.
40
+ Read `plan` and sanity-check it. Green `reviewed_plan` with your call.
41
+
42
+ - name: tester
43
+ consumes: [reviewed_plan]
44
+ produces:
45
+ - name: result
46
+ judges:
47
+ - name: ci-gate
48
+ body: "unused by a command judge, but still a required field (§24)" # not read; a command judge acts on exit status, not a prompt
49
+ worker: command # deterministic — no judgment, just run the script
50
+ command: scripts/ci-gate.sh # exit 0 approves, non-zero rejects with its output
51
+ worker: command # deterministic — no judgment, just run the script
52
+ command: npm test # opaque to the engine; the dispatcher runs this
53
+ spec: # opaque config for the dispatcher; engine never reads it
54
+ timeout: 300
55
+ workdir: .
56
+ body: "" # not required for worker: command (no agent prompt)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.2.0",
3
+ "version": "0.3.1",
4
4
  "description": "Deterministic rails for agentic workflows. Declare steps and dependencies; the engine guarantees order, redoes what changes invalidate, and stops what keeps failing — instead of hoping the agent follows through.",
5
5
  "license": "Apache-2.0",
6
6
  "author": "typicalday",