owenloop 0.2.0 → 0.2.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/authoring.md CHANGED
@@ -70,6 +70,10 @@ steps:
70
70
  # to the engine, passed through on the order
71
71
  # (see below)
72
72
  workdir: … # opaque hint passed through on the order; omitted when unset
73
+ worker: agent # opaque executor label (default: agent); see below
74
+ command: … # required when worker: command; opaque, never shelled out
75
+ spec: # optional opaque config map, shape-checked like x: (a plain map)
76
+ anything: goes # contents never read by the engine; see below
73
77
  x: # optional; opaque extension map, passed through
74
78
  anything: goes # untouched onto the order (Order.x); see design.md §27.3
75
79
  ```
@@ -98,6 +102,59 @@ a literal model id. Pin an exact model when you need reproducibility — just
98
102
  know the def is now host-specific, on purpose. Omit `model:` entirely and the
99
103
  dispatcher uses its default.
100
104
 
105
+ ## `worker:` — declaring the executor
106
+
107
+ Every step in every def written before this feature dispatches to an LLM
108
+ agent — that's still the default, and omitting `worker:` entirely leaves a
109
+ def byte-for-byte unchanged. `worker:` lets a step opt into a *different*
110
+ kind of executor instead: a shell command, a webhook, a browser-automation
111
+ runner, anything a dispatcher on the other end of `tick` knows how to run.
112
+ The engine never executes anything itself — `worker:` is an opaque label
113
+ that rides the order (same pass-through contract as `model`) for whatever
114
+ drives your workers to switch on.
115
+
116
+ ```yaml
117
+ steps:
118
+ - name: tester
119
+ consumes: [reviewed_plan]
120
+ produces: [result]
121
+ worker: command # opaque to the engine; default is 'agent'
122
+ command: npm test # required when worker: command; never parsed or shelled out
123
+ spec: # optional opaque config for the dispatcher
124
+ timeout: 300
125
+ workdir: .
126
+ body: "" # not required for worker: command
127
+ ```
128
+
129
+ Two shape rules, both enforced at load time, everything else opaque:
130
+
131
+ - **`worker: command` requires `command:`.** A `command`-worker step with no
132
+ `command:` is a load-time `DefError` — the dispatcher would have nothing to
133
+ run.
134
+ - **`worker: agent` (explicit) requires a real `body:`.** Omitting `worker:`
135
+ still defaults to `'agent'` and still needs no body-shape check beyond
136
+ today's behavior — this rule only fires when a step *explicitly* writes
137
+ `worker: agent` and leaves `body:` empty, which is almost certainly a
138
+ mistake (an agent step with no prompt).
139
+
140
+ Any other `worker` value (`browser-automation`, `webhook`, your own label) is
141
+ fully opaque — no `body:`/`command:` requirement at all. A definition can
142
+ optionally declare `workers: [agent, command]` at the top level as a typo
143
+ guard; when present, `validateDef` rejects any step (or judge — see below)
144
+ whose effective worker (after the `agent` default) isn't in the list:
145
+
146
+ ```yaml
147
+ name: my-workflow
148
+ workers: [agent, command] # optional allow-list; absent = any worker string accepted
149
+ ```
150
+
151
+ `command:` and `spec:` are opaque the same way `x:` is: `command` is
152
+ shape-checked as a string, `spec` as a plain map, and neither is ever read or
153
+ interpreted by the engine beyond that. All three (`worker`, `command`,
154
+ `spec`) ride through `buildOrder` onto the emitted `Order` untouched, exactly
155
+ like `model` and `workdir`. See [`docs/design.md` §27.4](design.md) for the
156
+ full contract.
157
+
101
158
  ## `produces:` vs `generates:`
102
159
 
103
160
  A stem under `produces:` is expected to be consumed downstream — owenloop's lint warns
@@ -137,11 +194,24 @@ steps:
137
194
  model: strong # optional, per-judge model tier
138
195
  inputs: true # optional, default false — judge also
139
196
  # reads the producer's inputs (question)
197
+ - name: ci-gate
198
+ body: "unused by a command judge, but still a required field" # every
199
+ # judge needs body/bodyFile regardless of worker
200
+ worker: command # judges can be deterministic too — same
201
+ command: scripts/ci-gate.sh # worker:/command: contract as a normal step
140
202
  maxAttempts: 5 # producer's cap (default for every produce on this step)
141
203
  # — also bounds judge-reject → rebuild loops; `report`
142
204
  # above could set its own maxAttempts: to override it
143
205
  ```
144
206
 
207
+ A judge entry accepts the same `worker:`/`command:`/`spec:` fields as a
208
+ normal step (see [`worker:` above](#worker--declaring-the-executor)) — a
209
+ judge can be a deterministic check (a script's exit status) instead of an
210
+ LLM verdict. Note `body:`/`bodyFile:` is still required on every judge
211
+ regardless of `worker:` — that requirement is orthogonal to this feature and
212
+ applies even to a `worker: command` judge (the field just goes unread by a
213
+ non-agent dispatcher).
214
+
145
215
  Each judge is a real step under the hood — it fires its own worker order
146
216
  through the normal pipeline, with its own throttles (`cadence:`,
147
217
  `maxRunsPerDay:`) and retry/timeout behavior. When `researcher` commits
package/docs/design.md CHANGED
@@ -127,13 +127,26 @@ Held artifacts (`isHeld`, §20) also surface as `stalled: true` in
127
127
  irreversible side effect and must not silently re-fire; a human must `retry` or
128
128
  fix the upstream cause.
129
129
 
130
+ A `reject()` (judgment verdict) requires the target to already be a *built*
131
+ version — `green` or `submitted` — and refuses otherwise (a thrown Error): an
132
+ `owed` artifact has no build to render a verdict on (rejecting it would burn a
133
+ `judgmentRejects` toward the cap above with zero build attempts, a silent
134
+ freeze), and a `retracted` collection member is terminal (§11.3) — no firing
135
+ shape can ever rebuild it, so flipping it back to a live `rejected` debt would
136
+ wedge the instance.
137
+
130
138
  Clearing a stall:
131
139
  - **`retry`** — reset *both* counters to 0 and re-owe the artifact (optionally
132
140
  with fresh guidance appended as a `retry` reason). The only path that resets
133
141
  the counters. Also clears the held condition: a `retry` appends a `'retry'`
134
142
  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).
143
+ and `isHeld` returns false. Requires the same consume-edge authority as
144
+ `reject`/`retract` (§4.1), and refuses a `retracted` target — retract is
145
+ final, and a bare collection element has no producer firing that could ever
146
+ rebuild it.
147
+ - **`retract`** — drop the member (collection elements), terminally. Requires
148
+ the same consume-edge authority as `reject` (§4.1): only a step that
149
+ consumes the member's stem (or human/engine) may retract it.
137
150
 
138
151
  ## §7 The forward cascade (level-triggered)
139
152
 
@@ -155,7 +168,10 @@ order-independent — re-running `settle()` on a healthy graph yields no ops.
155
168
 
156
169
  - **§11.1 produce `src[]`** — the producer `emit`s an unknown number of bare
157
170
  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.
171
+ (`sealOf = src`); the collection is "complete" when the seal is green. Once
172
+ the seal is green, a further `emit` on the same open lease is refused
173
+ (`sealed-rejected`) rather than silently growing a "complete" set; the lease
174
+ stays open so the run can still close.
159
175
  - **§11.2 map `src[$i]`** — fan-out: one firing per element, `${INDEX}` bound.
160
176
  - **§11.x reduce `src[*]`** — fan-in: see §3.
161
177
  - **§11.x reduce with suffix `src[*].child`** — fan-in one level deeper: the
@@ -531,12 +547,12 @@ The engine ships `maintainCalls` in `engine.ts` — the engine-internal method t
531
547
  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
548
 
533
549
  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`.
550
+ 2. **Re-attach guard**: `findChildByParent(parentWf, callsPath)` — spawn only when no child exists (`undefined`). This prevents duplicate children across crashes and re-ticks. 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.
551
+ 3. **Spawn**: if gate is ready and no child, `createInstance(step.calls, { producedBy, provide: gateValues })`. The parent calls: artifact stays `owed`. §23.6.7 (F2): a child input-schema refusal here is caught narrowly (`SchemaRefusalError` only — a genuine bug still throws) and recorded as a debt on the parent calls artifact instead of crashing the tick.
536
552
  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).
553
+ 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. §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.
554
+ 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.
555
+ 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
556
 
541
557
  #### §23.6.2 Cascade-up prompt
542
558
 
@@ -552,12 +568,50 @@ A child that greens its declared outcome with a status-bearing value (e.g. `{sta
552
568
 
553
569
  #### §23.6.5 Gate fingerprint and re-arm
554
570
 
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.
571
+ 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
572
 
557
573
  #### §23.6.6 Transaction composition
558
574
 
559
575
  `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`.
560
576
 
577
+ #### §23.6.7 F2 — child input-schema refusal is a debt, not a thrown tick
578
+
579
+ 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()`.
580
+
581
+ 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 (spawn) and STEP 5 (re-provide) each catch `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.
582
+
583
+ 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.
584
+
585
+ 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.
586
+
587
+ #### §23.6.8 F4 — reject on a calls artifact propagates to the child; the mirror is version-pinned
588
+
589
+ 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.
590
+
591
+ **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:
592
+
593
+ - 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.
594
+ - 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.
595
+ - 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.
596
+ - 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 requires ticking the CHILD instance (see the sweeping note below); `rejectCallsArtifact` also prompts `maintainCalls(parentWf)` so the parent's own `owed`/pin state is visible immediately, but it does not — and cannot, from the parent side alone — cause the child's producer step to fire.
597
+ - 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.
598
+
599
+ **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:
600
+
601
+ - 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).
602
+ - The reject-propagation path above stamps the same pin (to the just-rejected child outcome's version) when it reopens the parent to `owed`.
603
+ - `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.
604
+ - 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.
605
+
606
+ This gives the two orderings the settled design calls for:
607
+
608
+ - **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.
609
+ - **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.
610
+
611
+ 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.
612
+
613
+ **Sweeping note.** A propagated reject re-arms work in the CHILD instance, not the parent — `tick(parentWf)` re-runs `maintainCalls` (the mirror), but the child's own re-firing needs `tick(childWf)`. A driver/conductor that only ticks parents (never sweeping children) will see the parent sit `owed` indefinitely with no order ever appearing, because the actual work order is a child-instance concern. Drivers are expected to sweep every live instance (parent and child alike) — `store.listChildrenByParent`/`findChildByParent` give the reverse index needed to discover children from a parent id. The propagated reject is visible for such a sweep via the CHILD's own `status(childWf).debts` (the rejected outcome artifact appears there with `acceptance: 'rejected'`), independent of whether the sweep follows `producedBy` links or just iterates every known workflow id.
614
+
561
615
  ## §24 Artifact judges (`judges:`)
562
616
 
563
617
  A `produces` entry can declare one or more **judges**: deterministic
@@ -690,6 +744,13 @@ verbs with no new CLI surface:
690
744
  so a human clearing a judge-reject stall doesn't leave a stale partial
691
745
  ledger for the rebuild to inherit.
692
746
 
747
+ A human bypass's scope is deliberately narrow: it skips the judge ledger and
748
+ the lease/CAS machinery, but not the artifact's declared output schema — a
749
+ human `green` on a produce with a `schema:` is validated exactly like a
750
+ producer commit (§18), refused with a thrown Error (no version bump, no
751
+ schemaRejects bump — there is no retry loop to protect on this path) rather
752
+ than silently landing a value downstream consumers assume is schema-valid.
753
+
693
754
  ### §24.7 `CommitResult['outcome']` — three success outcomes, two failure
694
755
 
695
756
  `green()`'s result vocabulary grows by two, both **successes**:
@@ -887,21 +948,39 @@ sibling's auto-skip.
887
948
  Auto-skip is implemented purely inside `maintainDecisions` (model.ts) — the
888
949
  same pure, level-triggered fixpoint function §11.8/§12.3 already uses for
889
950
  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`.
951
+ with exactly one `green` member, every `owed`, `rejected`, **or `submitted`**
952
+ sibling gets a `skip` op with `rejectKind: 'exclusive'` (a new `RejectKind`,
953
+ alongside `judgment` / `structural` / `validation` / `invalidated-irreversible`
954
+ — a liveness-accounting category, distinct from the skip's `ReasonAction`,
955
+ which stays `'skip'`). Because `Engine.settle()` runs this cascade to a full
956
+ fixpoint synchronously at the end of every `green()` call, the auto-skip is
957
+ already visible by the time the winning `green()` call returns — a caller
958
+ never observes an intermediate state where the winner is green but the loser
959
+ is still `owed` or `submitted`.
960
+
961
+ A `submitted` sibling is an OUTSTANDING state (§15): left uncovered by this
962
+ cascade, a judged group member that submits before its sibling wins can never
963
+ be settled — its judge order is correctly suppressed by §26.5's eligibility
964
+ pre-filter, but the artifact itself just sits `submitted` forever, wedging the
965
+ instance out of `done: true` permanently. Covering `submitted` here closes
966
+ that gap. Skipping a `submitted` sibling also **clears its `approvals`
967
+ ledger** (mirrors the cascade-reject approvals-clear, §24 §4.3): a partial
968
+ judge sign-off recorded before the skip must never leak onto a later
969
+ resubmission if the winning sibling is later un-greened and the branch
970
+ revives — `Engine.applyOp`'s `'skip'` branch and its pure in-memory twin,
971
+ `applyOpInMemory`'s `'skip'` branch (the checker's own reimplementation, since
972
+ `settleInMemory` calls `maintainDecisions` directly and inherits the cascade
973
+ fix for free, but `applyOpInMemory` mirrors the engine's mutation 1:1 and
974
+ needs the same approvals-clear applied independently), both clear `approvals`
975
+ on the skipped artifact whenever its prior acceptance was `submitted`.
899
976
 
900
977
  Re-arming an auto-skipped sibling needs zero group-specific code: it goes
901
978
  through the exact same generic skip-re-arm mechanism (fingerprint-keyed,
902
979
  §7) that already re-arms a manually-skipped branch when its upstream inputs
903
980
  move. `rejectKind: 'exclusive'` only changes how the artifact is
904
- *classified* for liveness accounting; it does not change how it re-arms.
981
+ *classified* for liveness accounting; it does not change how it re-arms — and
982
+ the cleared approvals ledger travels with it, so a re-armed (or freshly
983
+ re-produced) sibling always starts its judge ledger from empty.
905
984
 
906
985
  ### §26.3 Grammar and validation
907
986
 
@@ -946,16 +1025,19 @@ sibling in this stem's group already sit green?" Every WORKER-firing branch
946
1025
  output path that is currently group-blocked, so the automatic sweep (`tick`)
947
1026
  never dispatches an order — in particular, never spawns a judge order for a
948
1027
  `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.
1028
+ it tries to land green. Historically this pre-filter was the only defense for
1029
+ a `submitted` group loser: §26.2's cascade covered only `owed`/`rejected`
1030
+ siblings, so a `submitted` member just sat there — its judge order suppressed
1031
+ from firing again, but the artifact itself never settled, wedging the
1032
+ instance out of `done: true` forever (a liveness bug, not merely wasted
1033
+ spawns). §26.2 now also auto-skips a `submitted` loser in the same settle as
1034
+ the winner's commit, so this eligibility pre-filter and that cascade converge:
1035
+ a `submitted` sibling is skipped essentially as soon as it stops being newly
1036
+ eligible (`test/groups.test.ts` scenario (f3)). `groupCasCheck` itself stays
1037
+ load-bearing for a judge order that was already claimed (in flight) before the
1038
+ winner landed — the pre-filter and the cascade both only act going forward, so
1039
+ scenario (f) still exercises the commit-time refusal against that in-flight
1040
+ race.
959
1041
 
960
1042
  Suppression applies to the automatic sweep only. A human `retry` re-arms the
961
1043
  named artifact directly and does not itself run `eligibleFirings` — but the
@@ -1098,6 +1180,88 @@ prefixing untouched (there are no stems inside `x:` to rewrite — it's
1098
1180
  opaque); a child definition's own top-level `x:` stays on the child def and
1099
1181
  is not merged into the parent's.
1100
1182
 
1183
+ ### §27.4 `worker:`/`command:`/`spec:` — declaring the executor
1184
+
1185
+ `x:` (§27.3) is a namespaced escape hatch for arbitrary external vocabulary.
1186
+ `worker:` is a narrower, purpose-built field for one specific job: telling
1187
+ whatever dispatches orders *which kind* of executor a step's order is for. It
1188
+ follows the same opaque-passthrough contract as `model` — the engine never
1189
+ interprets it, only carries it — but unlike `model` (a free-form quality
1190
+ hint) and unlike `x:` (fully unvalidated contents), `worker:` gets two narrow,
1191
+ hard-coded shape rules, because the two most common worker types have a
1192
+ structural precondition the engine can cheaply catch at load time instead of
1193
+ letting it surface as a confusing runtime stall.
1194
+
1195
+ **The contract, four clauses:**
1196
+
1197
+ 1. **Default is `'agent'`, and that default is silent.** A step (or judge)
1198
+ that omits `worker:` entirely behaves exactly as it did before this
1199
+ feature existed — every def in this repo predating `worker:` is
1200
+ unaffected, byte for byte. The default is applied at validation and
1201
+ engine-order-building time, never written back into the parsed def.
1202
+ 2. **`worker: command` requires `command:`.** A step (or judge) whose
1203
+ effective worker is `'command'` and carries no `command:` is a load-time
1204
+ `DefError`: `` step '<name>' has worker 'command' but no command: ``. Any
1205
+ other worker string has no such requirement — `command:` is only ever
1206
+ validated when the worker is literally `'command'`.
1207
+ 3. **`worker: agent` (explicit) requires a non-empty `body:`.** This check is
1208
+ deliberately scoped to an *explicit* `worker: agent`, not the *defaulted*
1209
+ value — i.e. `validateDef` checks `l.worker === 'agent'`, never
1210
+ `(l.worker ?? 'agent') === 'agent'`. That distinction matters: plenty of
1211
+ existing fixtures and generator-only steps rely on `buildStep`'s
1212
+ empty-body default and never write `worker:` at all. Checking the
1213
+ defaulted value would retroactively break every one of them. Checking
1214
+ only the explicit form catches the actual mistake this rule exists for —
1215
+ someone opts into `worker: agent` on purpose and forgets the prompt —
1216
+ without touching a single pre-existing def.
1217
+ 4. **`command:` and `spec:` are otherwise opaque.** `command` is
1218
+ shape-checked as a string (`asString`); `spec` is shape-checked as a plain
1219
+ map (`asExtension` — the same helper `x:` uses, reused verbatim, no new
1220
+ helper). Neither's *contents* are read, parsed, or interpreted by the
1221
+ engine. `spec` exists for cases where `command` alone isn't enough
1222
+ configuration (a timeout, a working directory hint, environment
1223
+ overrides) without inventing a new field per knob — the same "shape, not
1224
+ contents" philosophy as `x:`, just scoped to one step instead of the
1225
+ whole def.
1226
+
1227
+ **The optional `workers:` allow-list.** A definition can declare `workers:
1228
+ [agent, command, …]` at the top level — a typo guard, nothing more. When
1229
+ present, `validateDef` rejects any step or judge whose *effective* worker
1230
+ (after the `?? 'agent'` default is applied) isn't in the list. This runs
1231
+ **after** the default, deliberately: a def that declares `workers: [command]`
1232
+ (excluding `'agent'` on purpose) still fails a step that omits `worker:`
1233
+ entirely, because that step's effective worker is `'agent'` and `'agent'`
1234
+ isn't in the list. This is the intended behavior — once a def opts into the
1235
+ allow-list, it's exhaustive, and a step relying on the silent default doesn't
1236
+ get a free pass around it. A def with no `workers:` key accepts any worker
1237
+ string; there is no engine-wide registry of valid worker types to check
1238
+ against.
1239
+
1240
+ **Pass-through.** `worker`, `command`, and `spec` all ride `buildOrder` onto
1241
+ the emitted `Order` untouched — `Order.worker`, `Order.command`, `Order.spec`
1242
+ — the same pass-through contract as `Order.model` and `Order.x`. A step that
1243
+ never sets them emits an order with all three fields absent, identical to
1244
+ before this feature existed.
1245
+
1246
+ **Judges get the same fields, for free.** §24's `synthesizeJudgeSteps` turns
1247
+ each `judges:` entry into an ordinary `StepDef` — so a judge entry accepting
1248
+ `worker:`/`command:`/`spec:` and having the exact same `validateDef` rules
1249
+ apply to it isn't a separate code path, it's the same rules running against
1250
+ an already-existing synthesized step. A judge can therefore be a
1251
+ deterministic check (a script's exit code) instead of an LLM verdict, without
1252
+ any new validation logic. Note the pre-existing, orthogonal judge
1253
+ requirement — every judge needs `body:` or `bodyFile:` regardless of
1254
+ `worker:` — still applies; a `worker: command` judge still declares a
1255
+ `body:`, it's simply unread by a non-agent dispatcher.
1256
+
1257
+ **Scope notes**, mirroring §27.3's: `worker`/`command`/`spec` are additive
1258
+ and inert — a definition that never sets any of the three is unchanged in
1259
+ behavior and in `hashDef` terms. They live on the same two authored,
1260
+ engine-fired shapes as `x:` (a normal step, and — new here — a judge entry),
1261
+ participate in §28 pinning the same way (snapshotted at `createInstance`,
1262
+ and a later edit is real `hashDef` drift), and pass through `expandIncludes`
1263
+ prefixing untouched (there are no stems inside them to rewrite).
1264
+
1101
1265
  ## §28 Instance-to-definition pinning
1102
1266
 
1103
1267
  Every prior section treats a workflow *definition* as the stable thing and a
package/docs/embedding.md CHANGED
@@ -75,9 +75,34 @@ const status = engine.status(wf); // { done, debts, eligible, blocked, inFligh
75
75
 
76
76
  Each `order` is self-contained: `prompt`, `consumes` (the captured green
77
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.
78
+ `inputs`/`outputs`/`model`/`worker`/`command`/`spec`. A consumer rejecting an
79
+ upstream artifact is just `engine.reject(wf, path, by, text)`; the forward
80
+ cascade and stall liveness behave exactly as they do under the CLI, because
81
+ it's the same engine.
82
+
83
+ `order.worker` is where dispatch-by-executor-type earns its keep in an
84
+ embedder: rather than every order going to the same LLM-driving `runYourWorker`,
85
+ branch on it before deciding how to run the order.
86
+
87
+ ```ts
88
+ for (const order of orders) {
89
+ const result =
90
+ order.worker === 'command'
91
+ ? await runCommand(order.command!, order.spec) // order.command is opaque — never shelled out by owenloop itself
92
+ : await runYourAgent(order); // default / worker: 'agent' / anything else you handle the same way
93
+
94
+ const commit = engine.green(wf, order.run, order.outputs[0], result);
95
+ engine.close(wf, order.run);
96
+ }
97
+ ```
98
+
99
+ `worker`/`command`/`spec` are all optional and opaque — the engine only
100
+ shape-checks them at load time (`command` a string, `spec` a plain map) and
101
+ never reads their contents itself. `order.worker` is `undefined` when the
102
+ step never set it (today's default, unaffected by this feature). See
103
+ [`docs/design.md` §27.4](design.md) for the full contract and
104
+ [`docs/authoring.md`](authoring.md#worker--declaring-the-executor) for how to
105
+ declare it on a step.
81
106
 
82
107
  A runnable version of this lives at [`examples/embed.ts`](../examples/embed.ts):
83
108
 
@@ -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.2.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",