owenloop 0.5.8 → 0.5.10

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.
Files changed (131) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/README.md +81 -39
  3. package/bin/owenloop.mjs +16 -1
  4. package/dist/packages/work/src/agent/loop.d.ts +23 -8
  5. package/dist/packages/work/src/agent/loop.js +55 -6
  6. package/dist/packages/work/src/bundle/pull.d.ts +21 -0
  7. package/dist/packages/work/src/bundle/pull.js +118 -0
  8. package/dist/packages/work/src/consumed-verifier.js +6 -17
  9. package/dist/packages/work/src/exec/instructions.d.ts +4 -1
  10. package/dist/packages/work/src/exec/instructions.js +3 -0
  11. package/dist/packages/work/src/exec/loop.d.ts +2 -2
  12. package/dist/packages/work/src/exec/loop.js +273 -46
  13. package/dist/packages/work/src/exec/receipt.d.ts +7 -7
  14. package/dist/packages/work/src/exec/receipt.js +6 -6
  15. package/dist/packages/work/src/harness/claude.js +116 -0
  16. package/dist/packages/work/src/harness/codex.d.ts +8 -0
  17. package/dist/packages/work/src/harness/codex.js +27 -1
  18. package/dist/packages/work/src/harness/contract.d.ts +9 -0
  19. package/dist/packages/work/src/hub/client.d.ts +19 -4
  20. package/dist/packages/work/src/hub/client.js +7 -3
  21. package/dist/packages/work/src/hub/types.d.ts +84 -0
  22. package/dist/packages/work/src/main.js +1 -0
  23. package/dist/packages/work/src/roles/agent-run.js +57 -32
  24. package/dist/packages/work/src/roles/exec.js +27 -8
  25. package/dist/packages/work/src/roles/settings.js +2 -0
  26. package/dist/packages/work/src/roles/shift.js +14 -2
  27. package/dist/packages/work/src/roles/util.d.ts +1 -0
  28. package/dist/packages/work/src/roles/util.js +10 -0
  29. package/dist/packages/work/src/settings/hub-roster-cache.d.ts +68 -0
  30. package/dist/packages/work/src/settings/hub-roster-cache.js +370 -0
  31. package/dist/packages/work/src/settings/roster.d.ts +84 -0
  32. package/dist/packages/work/src/settings/roster.js +364 -5
  33. package/dist/packages/work/src/settings/serving.d.ts +17 -0
  34. package/dist/packages/work/src/settings/serving.js +79 -0
  35. package/dist/packages/work/src/settings/settings.d.ts +14 -1
  36. package/dist/packages/work/src/settings/settings.js +14 -0
  37. package/dist/packages/work/src/shift/loop.d.ts +108 -5
  38. package/dist/packages/work/src/shift/loop.js +416 -54
  39. package/dist/packages/work/src/shift/protocol.d.ts +7 -5
  40. package/dist/packages/work/src/shift/runtime.d.ts +18 -0
  41. package/dist/packages/work/src/shift/runtime.js +104 -5
  42. package/dist/packages/work/src/shift/server.js +2 -0
  43. package/dist/packages/work/src/shift/spawn.d.ts +17 -2
  44. package/dist/packages/work/src/shift/spawn.js +16 -13
  45. package/dist/packages/work/src/shift/state.d.ts +29 -2
  46. package/dist/packages/work/src/shift/state.js +45 -15
  47. package/dist/packages/work/src/submit-proof.d.ts +11 -8
  48. package/dist/packages/work/src/submit-proof.js +11 -8
  49. package/dist/packages/work/src/usage.d.ts +1 -1
  50. package/dist/packages/work/src/usage.js +7 -1
  51. package/dist/packages/work/src/util/modifier-init.d.ts +7 -0
  52. package/dist/packages/work/src/util/modifier-init.js +73 -0
  53. package/dist/src/bundle/tar.d.ts +9 -4
  54. package/dist/src/bundle/tar.js +9 -4
  55. package/dist/src/capabilities.d.ts +76 -6
  56. package/dist/src/capabilities.js +49 -6
  57. package/dist/src/capability-mapping-client.d.ts +29 -0
  58. package/dist/src/capability-mapping-client.js +160 -0
  59. package/dist/src/cli.d.ts +16 -3
  60. package/dist/src/cli.js +1925 -281
  61. package/dist/src/config-dir.d.ts +1 -1
  62. package/dist/src/config-dir.js +1 -1
  63. package/dist/src/crypto/index.d.ts +1 -1
  64. package/dist/src/crypto/index.js +1 -1
  65. package/dist/src/crypto/org-root.d.ts +30 -12
  66. package/dist/src/crypto/org-root.js +162 -14
  67. package/dist/src/crypto/records.d.ts +2 -0
  68. package/dist/src/crypto/records.js +2 -0
  69. package/dist/src/defs.d.ts +38 -2
  70. package/dist/src/defs.js +593 -86
  71. package/dist/src/engine.d.ts +103 -25
  72. package/dist/src/engine.js +331 -79
  73. package/dist/src/hub.d.ts +77 -0
  74. package/dist/src/hub.js +162 -0
  75. package/dist/src/implements.d.ts +56 -0
  76. package/dist/src/implements.js +790 -0
  77. package/dist/src/index.d.ts +11 -9
  78. package/dist/src/index.js +6 -5
  79. package/dist/src/mcp/serve.d.ts +22 -0
  80. package/dist/src/mcp/serve.js +330 -41
  81. package/dist/src/mcp/server.d.ts +10 -7
  82. package/dist/src/mcp/server.js +53 -8
  83. package/dist/src/model.d.ts +48 -10
  84. package/dist/src/model.js +252 -99
  85. package/dist/src/order-resolver.d.ts +1 -0
  86. package/dist/src/order-resolver.js +8 -1
  87. package/dist/src/schemas/index.d.ts +11 -0
  88. package/dist/src/schemas/order.v1.schema.json +7 -1
  89. package/dist/src/store/def-source.d.ts +19 -0
  90. package/dist/src/store/def-source.js +87 -17
  91. package/dist/src/store/gc-recovery.d.ts +46 -0
  92. package/dist/src/store/gc-recovery.js +258 -0
  93. package/dist/src/store/gc.d.ts +94 -0
  94. package/dist/src/store/gc.js +562 -0
  95. package/dist/src/store/index.d.ts +3 -1
  96. package/dist/src/store/index.js +2 -0
  97. package/dist/src/store/install.d.ts +34 -5
  98. package/dist/src/store/install.js +73 -11
  99. package/dist/src/store/pre-commit-verifier.js +42 -2
  100. package/dist/src/store/snapshot-guard.d.ts +18 -0
  101. package/dist/src/store/snapshot-guard.js +94 -0
  102. package/dist/src/store.d.ts +69 -4
  103. package/dist/src/store.js +254 -16
  104. package/dist/src/types.d.ts +101 -20
  105. package/dist/src/util.js +4 -1
  106. package/docs/authoring.md +235 -10
  107. package/docs/bundles.md +45 -2
  108. package/docs/cli.md +437 -55
  109. package/docs/crypto.md +32 -10
  110. package/docs/design.md +177 -47
  111. package/docs/evals/mcp-charter-baseline.json +428 -0
  112. package/docs/mcp-charter-eval.md +124 -0
  113. package/docs/routing.md +189 -34
  114. package/docs/shift-logs.md +38 -9
  115. package/docs/wire-contracts.md +78 -14
  116. package/examples/workflows/compile-dev-playbook.yaml +1 -1
  117. package/examples/workflows/delivery.yaml +31 -14
  118. package/examples/workflows/ship.yaml +38 -4
  119. package/package.json +2 -1
  120. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  121. package/plugins/claude-code/plugin/.mcp.json +1 -1
  122. package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
  123. package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
  124. package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
  125. package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
  126. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  127. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  128. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
  129. package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
  130. package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
  131. package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
package/docs/crypto.md CHANGED
@@ -70,7 +70,7 @@ child stderr is never interpolated into error text.
70
70
  | `machine` | the literal `"local"` |
71
71
  | `agent` | the agent identity id |
72
72
 
73
- `owenloop setup` step `[4/7] signing keys` ensures all three, in that order,
73
+ `owenloop setup` step `[4/8] signing keys` ensures all three, in that order,
74
74
  idempotently: a second run performs zero writes.
75
75
 
76
76
  **One backend is selected once and never error-fallback.** A fallback after a
@@ -174,13 +174,19 @@ consumer passes to `verifyConsumed` as `expectedVersion`. It is never inferred
174
174
  from process-local state.
175
175
 
176
176
  Retry-safety is a property of where the target is computed, not of the client.
177
- The engine computes it inside the claim transaction and persists it with the
178
- immutable order, so every read of that claim — a reconnect, a retried submit
179
- after a lost response, a restarted holder — yields the same number. Engine
180
- refusal paths that leave the run open (a schema reject) do not bump the
181
- artifact, so the target survives in-claim retries; a refinement is a new claim
182
- and receives a newly issued target. A stale target fails the consumer's version
183
- check, which is a refusal, never an admitted unverified value.
177
+ The engine issues it inside the claim transaction and persists it with the
178
+ order, so a reconnect, a retried submit after a lost response, or a restarted
179
+ holder re-reads the issued number instead of guessing one; a refinement is a new
180
+ claim and receives a newly issued target.
181
+
182
+ The target is not frozen for the life of the claim. A refusal that leaves the
183
+ run open without bumping the artifact (a schema reject) leaves it correct, but a
184
+ judgment or human reject follows a commit that already bumped the artifact and
185
+ leaves the same claim live to retry — so the engine re-stamps that claim's
186
+ target from the current committed version at the reject site. A client must
187
+ therefore re-read `owes[].version` off the order on every submit and never cache
188
+ it across a reject. A stale target fails the consumer's version check, which is
189
+ a refusal, never an admitted unverified value.
184
190
 
185
191
  A target is authoritative only when it is a positive integer: the smallest
186
192
  commit any producer can land is v1. An absent target, a `0`, or a non-integer
@@ -719,16 +725,32 @@ layout is:
719
725
  ```text
720
726
  <config>/org-root.pub # public anchor, 0644
721
727
  <config>/org-root # private anchor, 0600
722
- <config>/roster/<sha256hex(keyid)>.grant.dsse
728
+ <config>/grants/<sha256hex(keyid)>.grant.dsse
723
729
  <config>/revocations/<sha256hex(keyid)>.revocation.dsse
724
730
  ```
725
731
 
726
732
  The root key is stored outside `PrincipalKeyManager` because the root is not a
727
733
  hub-scoped principal key. The containing directory is `0700`; the private root
728
- is never returned by the library or placed in an envelope. `loadRoster` and
734
+ is never returned by the library or placed in an envelope. `loadGrants` and
729
735
  `loadRevocations` return raw envelope bytes to the pure validator and refuse
730
736
  symlinked or non-regular files.
731
737
 
738
+ If `<config>/grants` has zero `*.grant.dsse` entries while the pre-rename
739
+ `<config>/roster` is a readable, non-symlink directory of regular files that
740
+ holds grants, owenloop refuses rather than treating the machine as unenrolled.
741
+ It never reads or moves that legacy directory. When `<config>/grants` is
742
+ absent, the shell-quoted remediation is structurally
743
+ `mv <config>/roster <config>/grants`; this whole-directory rename preserves
744
+ every accepted grant filename, including dot-prefixed names. When a grants path
745
+ already exists, the printed remediation is instead
746
+ `rmdir <config>/grants && mv <config>/roster <config>/grants`. It moves only if
747
+ that path is an empty real directory; otherwise `rmdir` fails without moving
748
+ anything, and the operator must inspect `<config>/grants` by hand before
749
+ retrying. In either case, restart running owenloop shift daemons after a
750
+ successful migration. If the legacy source is a file or symlink, cannot be
751
+ inspected, or contains a non-regular entry, owenloop prints no migration
752
+ command: repair the named source path by hand before retrying the migration.
753
+
732
754
  ## Admin-signed policy floors
733
755
 
734
756
  A policy floor is an org-wide minimum for local enforcement. An org admin signs
package/docs/design.md CHANGED
@@ -579,11 +579,12 @@ When the engine spawns a child instance, it passes `producedBy: { parentWf, pare
579
579
 
580
580
  - **Excluded from `eligibleFirings`**: `model.ts` skips any step with `step.calls` set. No worker order is ever emitted for a `calls:` step.
581
581
  - **Owed artifact seeded normally**: `pendingOwed` seeds the calls: step's one declared `produces` stem as owed at instance start (same code path as normal singleton produces).
582
- - **Debt/done correctness**: an owed calls: artifact is a normal debt. The parent workflow is not done until the calls: output is green (same logic as any other owed artifact — no special casing needed).
582
+ - **Debt/done correctness**: an owed calls: artifact is a normal debt. It stays owed until the child's declared output is green with a value **and the whole child workflow is done** under the same rule as `workflowStatus().done` (including the satisfied-`atLeastOne` exception). Only then does the mirror green, so the parent cannot report done while the child still owes cleanup.
583
+ - **Model-checker abstraction**: the checker has no child-instance graph, so its one synthetic calls transition is the opaque completion of the whole child plus exposure of the declared output. It already models the terminal handoff rather than an early output event; the runtime join timing changes here require no new checker transition or cross-definition recursion.
583
584
 
584
585
  ### §23.4 Cross-def calls-cycle check
585
586
 
586
- At `loadDefs` time, after all defs are expanded and per-def validated, `detectCallsCycles(defs)` performs a DFS over the `calls:` edge graph and throws `DefError: calls cycle: a -> b -> a` if a cycle exists. The DFS follows the same scope-aware resolution as runtime spawning and keys each edge by the resolved definition, not by the bare text alone; two bundles may therefore each contain a workflow named `build` without being collapsed into one node.
587
+ At `loadDefs` time, after all defs are expanded and per-def validated, `finalizeDefs` runs the original bounded first-cycle DFS and throws `DefError: calls cycle: a -> b -> a` on its first witness. Authoring commands call `reportCallsCycles(defs)`, which preserves that first witness and adds deterministic per-member witnesses until every cyclic definition is attributed, without enumerating the potentially exponential set of all simple cycles. Each finding names exactly the members on its displayed path. Both paths follow the same scope-aware resolution as runtime spawning and key each edge by the resolved definition, not by the bare text alone; two bundles may therefore each contain a workflow named `build` without being collapsed into one node.
587
588
 
588
589
  This check is **separate** from the include-cycle guard in `expandIncludes` (§22.5) — they walk different edge kinds (`calls:` vs `include:`). An include cycle and a calls cycle can coexist independently and are reported with different messages (`calls cycle:` vs `include cycle:`).
589
590
 
@@ -606,32 +607,34 @@ Called at the top of every parent `tick` (outside any transaction), after `provi
606
607
 
607
608
  A mismatch rolls back the child creation and input sync, then records the parent `calls:` artifact as `rejected` with a structural reason naming the expected and resolved digests. The engine does not throw or run the mismatched child. The current gate fingerprint prevents the same refusal from being retried on every tick. An already-existing child is read through its own §28 snapshot and is not re-checked by this spawn-only guard.
608
609
 
609
- 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.
610
+ 4. **Outcome/join read**: read the child's declared `outputs:` artifact (exactly one, validated at load time) and compute whole-child done-ness from the same pinned child definition and artifact snapshot. Only a green, value-defined outcome from a done child may machine-green the parent's calls: artifact.
610
611
  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.
611
- 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.
612
- 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`.
612
+ 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 is done and 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 or whole-child completion no longer holds.
613
+ 7. **Re-arm on child working**: when the parent calls: artifact is green, re-arm it to `owed` if either the child's outcome is no longer green (e.g. re-provide re-armed it) **or the outcome remains green but the child is not done**. This handles gate re-arm and late cleanup correctly even though `deliver` declares `consumes: []` (the pure cascade cannot detect either cross-instance condition). The green-outcome/unfinished-child case records `called workflow is not done` and removes only the reserved child-output version pin, preserving every gate-version entry. Removing that one pin is what permits the unchanged declared output to be mirrored again after cleanup completes; ordinary non-green outcome re-arms retain the fingerprint, pin, and existing `gate input moved: child re-running` reason.
614
+
615
+ This widened re-arm is intentionally retroactive. On the next maintain pass, an existing store whose caller mirror is falsely green while its child is unfinished is reconciled back to `owed`; normal settling may invalidate downstream parent artifacts, and owed-only deep descent resumes the child's cleanup. This repairs persisted false completion without a schema or data migration. A child waiting for a manually supplied input remains an ordinary outstanding workflow; there is no timeout, bypass, warning, or load-time mapping rule.
613
616
 
614
617
  #### §23.6.2 Cascade-up prompt
615
618
 
616
- After a child `green` or `close`, `triggerParentIfChild(childWf)` reads the child's `producedBy` link and calls `maintainCalls(parentWf)`. This propagates the child's outcome to the parent immediately, instead of waiting for the next scheduled tick. Durability is free regardless: even without the prompt, the next parent tick calls `maintainCalls` and reads the persisted child outcome. The recursion guard (`_inMaintainCalls: Set<string>`) prevents `maintainCalls → provideInput → fireSettled → triggerParentIfChild → maintainCalls` infinite steps.
619
+ After a child `green` or `close`, `triggerParentIfChild(childWf)` reads the child's `producedBy` link and calls `maintainCalls(parentWf)` immediately instead of waiting for the next scheduled tick. This is a prompt to re-evaluate the join, not an unconditional outcome propagation: the parent mirror is published only when the declared child output is green and value-defined **and** `workflowDone(childDef, childArts)` is true for the whole child snapshot. If cleanup or a manually supplied input remains outstanding, the parent calls: artifact stays `owed`. Durability is free regardless: even without the prompt, the next parent tick calls `maintainCalls` and performs the same join check against persisted child state. The recursion guard (`_inMaintainCalls: Set<string>`) prevents `maintainCalls → provideInput → fireSettled → triggerParentIfChild → maintainCalls` infinite steps.
617
620
 
618
621
  #### §23.6.3 `outputs:` as embedding interface
619
622
 
620
- A workflow that can be called via `calls:` must declare exactly one `outputs:` stem (validated at `loadDefs` Phase 2). The called workflow's `outputs:[0]` is the artifact whose value is reflected up to the parent's calls: artifact when it greens. The `delivery` workflow declares `outputs: [merge]` — its merge artifact is the public outcome. A parent `calls: delivery` receives the merge value in its `delivered` artifact.
623
+ A workflow that can be called via `calls:` must declare exactly one `outputs:` stem (validated at `loadDefs` Phase 2). The called workflow's `outputs:[0]` selects the value to expose; greening that artifact is not by itself the completion signal. Its value is reflected to the parent's calls: artifact only when it is green and value-defined **and** `workflowDone(childDef, childArts)` says the whole child is done. The `delivery` workflow declares `outputs: [merge]` — its merge artifact is the public outcome. A parent `calls: delivery` eventually receives the merge value in its `delivered` artifact after all delivery work has completed.
621
624
 
622
625
  #### §23.6.4 Failure branch
623
626
 
624
- A child that greens its declared outcome with a status-bearing value (e.g. `{status: 'failed'}`) propagates that value up unchanged. The parent's calls: artifact greens with the failure status, and teardown (or other consumers) receives it through the normal green gate. Teardown runs on success AND failure — there is no special consume mode for failure.
627
+ A green, value-defined declared outcome may carry a status-bearing value (e.g. `{status: 'failed'}`), but it is mirrored only after `workflowDone(childDef, childArts)` says the whole child is done. At that point the value propagates unchanged: the parent's calls: artifact greens with the failure status, and teardown (or other consumers) receives it through the normal green gate. A green failure outcome with outstanding child cleanup or a manual input keeps the parent mirror `owed`. Once the child is done, teardown runs on success AND failure — there is no special consume mode for failure.
625
628
 
626
629
  #### §23.6.5 Gate fingerprint and re-arm
627
630
 
628
- 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: []`.
631
+ 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 cross-instance join/re-green trigger is handled by `maintainCalls`'s outcome-value, `workflowDone`, and version-pin checks, not by green-fingerprint invalidation in the pure forward cascade: a calls: step still declares `consumes: []`, and its live green fingerprint must not be compared with the gate-only dependency set. Maintenance does use `callsInputs` separately to find dead gate branches, structurally skip the calls output and its downstream branch, and revive an engine-authored cascade skip after the gate returns green with moved versions. Human or producer skips retain the child-outcome pin semantics in §23.6.8 and are not revived merely because the gate is green.
629
632
 
630
633
  #### §23.6.6 Transaction composition
631
634
 
632
635
  `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`.
633
636
 
634
- 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.
637
+ Each mutating action does its **read-verify-write in ONE `BEGIN IMMEDIATE`**, not just its write. `maintainCalls`'s pre-reads (the outcome/done/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), re-arms the child, or changes its completion state 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-resolves the pinned child definition, verifies its expected output stem, and re-reads the parent artifact, all child artifacts, declared outcome, and gate in-tx; it requires the outcome still green/value-defined, the whole child still done, the gate still ready, the F4 pin passed, and child inputs consistent with the gate before computing the fingerprint and writing from that one snapshot. Any mismatch aborts (returns `false`, nothing written — no debt, no reasons, no events) and defers to the next tick. `rearmCallsGreen` performs the mirror in-tx recheck: it re-resolves the pinned child definition, verifies the expected output stem, reads all child artifacts, and re-arms only if the parent is still green and the outcome is non-green or the child is unfinished. 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.
635
638
 
636
639
  #### §23.6.7 F2 — child input-schema refusal is a debt, not a thrown tick
637
640
 
@@ -651,7 +654,7 @@ Before this fix, a consumer's `reject()` (or a human `skip()`) on a `calls:`-pro
651
654
 
652
655
  - 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.
653
656
  - 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.
654
- - 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.
657
+ - 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 outcome rebuilds and the whole child is done.
655
658
  - 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.
656
659
  - 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.
657
660
 
@@ -660,22 +663,25 @@ Before this fix, a consumer's `reject()` (or a human `skip()`) on a `calls:`-pro
660
663
  - 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).
661
664
  - The reject-propagation path above stamps the same pin (to the just-rejected child outcome's version) when it reopens the parent to `owed`.
662
665
  - `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.
663
- - 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.
666
+ - The green-outcome/unfinished-child structural re-arm deletes this reserved pin only. The outcome version may remain unchanged while cleanup reruns, so retaining the pin would leave the mirror permanently owed after the child becomes done again. Gate-version entries remain intact, and non-green outcome, reject, and skip paths keep their existing pins.
667
+ - Publication stamps the outcome version from its authoritative in-transaction child snapshot; reject-propagation and skip use `Engine.childOutcomePin(parentWf, callsPath)` at verdict time. The structural re-arm operates on the already-stamped parent fingerprint and removes only that reserved key.
664
668
 
665
669
  This gives the two orderings the settled design calls for:
666
670
 
667
671
  - **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.
668
672
  - **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.
669
673
 
670
- 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.
674
+ The `M2B-REARM` branch (§23.6.1 step 7) never lets the pin block reopening. A non-green child outcome retains it; a green outcome on an unfinished child clears it so the same output version may republish once the child finishes. In both cases, the parent returns to the live `owed` debt that deep descent follows.
671
675
 
672
676
  **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.
673
677
 
674
- - **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.
678
+ - **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), a gate-move re-arm, and the whole-child unfinished 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; its owed-only rule does not change, because widened maintenance now restores unfinished joins to that live debt.
675
679
  - **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.
676
680
  - **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. Because the folded order list can contain child orders, a driver must commit and close each order against `order.workflow`, not the root id passed to `tick`. The `{ deep: false }` opt-out is the only case where every order is guaranteed to belong to the requested root.
677
681
  - **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.
678
682
 
683
+ **Tested depth and hard bound.** `calls: deep tick (2) three-level nesting — tick(root) drives the tree to done` covers three workflow instances driven to done from root ticks: the root at calls depth 0, a child at depth 1, and a grandchild at depth 2. `DEFAULT_MAX_CALL_DEPTH` is 64, and hosts may configure that bound with the `Engine` `maxCallDepth` option. The bound is defense in depth against a cycle that bypassed construction-time validation, not a normal tuning knob; there is no unlimited or arbitrary-depth guarantee. See also `calls: (REL-4) maxCallDepth stops a self-calling def cleanly — no overflow, bounded rows`.
684
+
679
685
  **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 Shift 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.
680
686
 
681
687
  **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.
@@ -812,6 +818,16 @@ opinion about the artifact's quality — it's a fact about worker
812
818
  availability, and the two must stay uncorrelated so a flaky judge worker
813
819
  cannot exhaust the producer's `maxAttempts` budget on its own.
814
820
 
821
+ ### §24.5.1 Released lease churn
822
+
823
+ A public `Engine.close(..., 'released')` returns a claimed lease without
824
+ counting a run for daily-budget or cadence purposes, but increments the task's
825
+ `attempts` status field. This makes repeated pickup-window lapses and explicit
826
+ holder/capacity handbacks visible in instance status. It remains lease-churn
827
+ telemetry: it does not affect `judgmentRejects`, which is the rework budget.
828
+ The private born-reject/CAS-stale release remains excluded because that firing
829
+ was invalidated before it became a holder lease attempt.
830
+
815
831
  ### §24.6 Human override
816
832
 
817
833
  Two human-facing bypass points, both reusing the existing `green`/`retry`
@@ -970,6 +986,13 @@ step's last owed submit is what closes it — so the reverse order made every
970
986
  reject from a single-owed-path step undeliverable. What follows the reject
971
987
  depends on the hub's own answer, in its `closed` field:
972
988
 
989
+ The payload reject's `text` starts with the script's reason. When the command
990
+ has a non-empty captured output tail, the worker appends a labeled
991
+ `--- command output (last N bytes) ---` section containing the last 4 KiB of
992
+ combined stdout-then-stderr output (lossy UTF-8, with trailing newlines
993
+ trimmed before counting bytes). An empty tail adds nothing, and the payload
994
+ marker line is retained. Judge rejects are not changed by this formatting.
995
+
973
996
  - `closed: true` — the rejected path was one of this firing's consumed inputs,
974
997
  so the hub closed the run `no_work`. The owed paths stay debts and the step
975
998
  re-fires against the rebuilt input. No receipt is submitted: an artifact
@@ -994,29 +1017,57 @@ instance.
994
1017
  ## §25 The model checker (`owenloop check`) — scope
995
1018
 
996
1019
  `owenloop check <def>` (see `cli.ts` usage) runs a bounded reachability
997
- search over `applyOutcome` transitions in `model.ts`, looking for stall
998
- states, true deadlocks, stuck artifacts, dead steps, and violations of any
999
- declared invariants. It is a static analysis of a workflow definition's
1000
- shape, not a simulation of a running instance.
1020
+ search over the `applyOutcome` transitions in `model.ts`, including the
1021
+ model-only authority transitions described below, looking for stall states,
1022
+ true deadlocks, stuck artifacts, dead steps, and violations of any declared
1023
+ invariants. It is a static analysis of a workflow definition's shape, not a
1024
+ simulation of a running instance.
1025
+
1026
+ **Collection-cap reporting.** The finite member-count cap used when expanding
1027
+ an `emit`/`seal` outcome defaults to 2 and can be set with `--max-collection`.
1028
+ The structured `CheckReport` records the effective value in
1029
+ `maxCollectionSize` and sets `collectionCapApplied` when the search expands at
1030
+ least one reachable collection fork. This metadata describes the explored
1031
+ search shape; it is not a `boundsHit` value and does not make `bounded` true.
1032
+ The CLI reports the same caveat in text mode and includes both fields in JSON.
1033
+
1034
+ **Collection-member retract transitions.** A bare collection member may be
1035
+ retracted by any authorized non-judge consumer, even when that member is
1036
+ rejected and therefore has no ordinary eligible map firing. The live scheduler
1037
+ (`eligibleFirings`) remains worker-only and keeps its green-input gate; the
1038
+ checker adds one synthetic successor transition for each authorized
1039
+ `(consumer, member)` pair so a runtime-valid retract is not reported as a
1040
+ deadlock. The synthetic transition offers only `retract`. It is not counted as
1041
+ an ordinary worker firing for dead-step accounting, and a synthesized judge's
1042
+ read-only context never grants member-retract authority. Applying it terminally
1043
+ retracts the member and lets the normal cascade retract its indexed map
1044
+ children, removing them from a reduce's surviving-member set.
1001
1045
 
1002
1046
  **Stall states vs true deadlocks.** A reachable, non-done state with zero
1003
- eligible firings is classified into exactly ONE of two mutually exclusive
1004
- buckets, by recomputing eligibility as if every freeze were lifted
1005
- (`eligibleFirings(def, arts, undefined, { ignoreFreeze: true })` — "unlimited
1006
- attempts," i.e. what a human `retry` grants):
1047
+ available transitions is classified into exactly ONE of two mutually exclusive
1048
+ buckets, by recomputing eligibility with every freeze lifted and with an
1049
+ eventual-time bag (`eligibleFirings(def, arts, EVENTUAL_TIME_FACTS,
1050
+ { ignoreFreeze: true })`). That represents unlimited attempts (what a human
1051
+ `retry` grants) and an elapsed idle threshold, but is used only for
1052
+ classification — it does not add time to the BFS canonical key or expand an
1053
+ idle successor.
1007
1054
  - **stall state** (`report.stallStates`) — the recompute yields >= 1 firing:
1008
1055
  the state's ONLY blocker is a frozen/stalled debt — `maxAttempts` reached
1009
1056
  (`isStalled`, §6), `maxSchemaFailures` reached (`isSchemaStalled`, §6/§18),
1010
- or held (`isHeld`, §20). Lifting the freeze re-arms a producer, so the
1011
- line COULD move. This is a by-design human-escalation brake — EXPECTED,
1012
- never a defect, and it never affects the exit code.
1057
+ or held (`isHeld`, §20) — or a future idle threshold. Lifting the freeze
1058
+ re-arms a producer, or elapsed time enables the idle step, so the line
1059
+ COULD move. This is a by-design human-escalation brake or expected future
1060
+ wait — never a defect, and it never affects the exit code. Because the
1061
+ reachability search remains timeless, this classification does not by
1062
+ itself prove that an idle-only path is `completable`.
1013
1063
  - **true deadlock** (`report.deadlocks`) — the recompute STILL yields zero
1014
- firings: no producer would re-arm even at unlimited attempts. A genuine
1015
- structural dead-end (e.g. a `group:`-blocked or ungreen-input state, or an
1016
- owed input with no producer). This is folded into `hasDefiniteDefect` and
1017
- makes `check` exit nonzero — but only when the search was exhaustive
1018
- (`!report.bounded`), since a tight `--max-collection`/`--max-states` cap
1019
- can otherwise manufacture a spurious no-moves state.
1064
+ firings: no producer would re-arm even after unlimited attempts or elapsed
1065
+ idle time. A genuine structural dead-end (e.g. a `group:`-blocked or
1066
+ ungreen-input state, or an owed input with no producer). This is folded
1067
+ into `hasDefiniteDefect` and makes `check` exit nonzero — but only when the
1068
+ search was exhaustive (`!report.bounded`), since a tight
1069
+ `--max-collection`/`--max-states` cap can otherwise manufacture a spurious
1070
+ no-moves state.
1020
1071
 
1021
1072
  The freeze-lift recompute ONLY lifts the `frozen()` guard — it does not
1022
1073
  bypass group-exclusivity (`groupBlockingWinner`), input-green gates, or
@@ -1172,13 +1223,21 @@ fix for free, but `applyOpInMemory` mirrors the engine's mutation 1:1 and
1172
1223
  needs the same approvals-clear applied independently), both clear `approvals`
1173
1224
  on the skipped artifact whenever its prior acceptance was `submitted`.
1174
1225
 
1175
- Re-arming an auto-skipped sibling needs zero group-specific code: it goes
1176
- through the exact same generic skip-re-arm mechanism (fingerprint-keyed,
1177
- §7) that already re-arms a manually-skipped branch when its upstream inputs
1178
- move. `rejectKind: 'exclusive'` only changes how the artifact is
1179
- *classified* for liveness accounting; it does not change how it re-arms — and
1180
- the cleared approvals ledger travels with it, so a re-armed (or freshly
1181
- re-produced) sibling always starts its judge ledger from empty.
1226
+ Re-arm has two deliberately separate paths. A manual or branch skip remains
1227
+ fingerprint-keyed (§7): its direct inputs must all be green and have moved.
1228
+ For an exclusive group, when no winner remains, a currently skipped sibling
1229
+ whose **latest** `ReasonEntry` with `action: 'skip'` has `kind: 'exclusive'`
1230
+ re-arms directly to `owed`. The latest entry matters: a later structural skip
1231
+ supersedes any historical exclusive skip. This inverse is group-specific
1232
+ because knocking down the winner changes none of the sibling producer's input
1233
+ versions, so the generic movement gate correctly cannot see it.
1234
+
1235
+ `Engine.applyOp` records the exclusive skip marker and re-arms without a
1236
+ version bump; its pure `applyOpInMemory` mirror records the same deterministic
1237
+ skip/reopen metadata. The model checker's canonical state key also includes a
1238
+ skipped artifact's latest skip kind, since exclusive and structural skips now
1239
+ have different outgoing transitions. The cleared approvals ledger travels with
1240
+ the re-arm, so a freshly resubmitted judged sibling starts from empty.
1182
1241
 
1183
1242
  ### §26.3 Grammar and validation
1184
1243
 
@@ -1241,13 +1300,13 @@ Suppression applies to the automatic sweep only. A human `retry` re-arms the
1241
1300
  named artifact directly and does not itself run `eligibleFirings` — but the
1242
1301
  artifact is still subject to `maintainDecisions`' own auto-skip cascade
1243
1302
  (§26.2), which runs synchronously inside `retry`'s `settle()` call and
1244
- re-skips it immediately if the winning sibling is still green. Either way — a
1245
- retried stem is suppressed again on the next tick exactly like a
1246
- machine-originated re-arm, unless the winning sibling has been knocked down
1247
- first (`reject`/`retract`), which makes the *producer* eligible to re-fire
1248
- again (`test/groups.test.ts` scenario (i)). This mirrors the existing
1249
- human-bypass symmetry at `green()` (§24.6): a human bypasses the run/lease/CAS
1250
- machinery, never the group-exclusivity contract itself.
1303
+ re-skips it immediately while the winning sibling is green. In contrast,
1304
+ rejecting or retracting that winner directly re-arms siblings whose current
1305
+ skip is exclusive; manual/branch-skipped artifacts still wait for input
1306
+ movement. The producer then becomes eligible to re-fire
1307
+ (`test/groups.test.ts` scenario (i)). This mirrors the existing human-bypass
1308
+ symmetry at `green()` (§24.6): a human bypasses the run/lease/CAS machinery,
1309
+ never the group-exclusivity contract itself.
1251
1310
 
1252
1311
  ## §27 Engine-version contract and unknown-key rejection
1253
1312
 
@@ -1365,6 +1424,11 @@ the dataflow fields, the runner reads `x:` — with no allowlist churn as the
1365
1424
  external tooling grows knobs, and no third-party schema leaking into the
1366
1425
  engine's own.
1367
1426
 
1427
+ The authoring linter additionally recognizes Owenloop's optional x.discovery
1428
+ convention. That narrow, warning-only convention helps catalog tooling describe
1429
+ a workflow's purpose and public interface; it does not change the parser's
1430
+ opaque-extension contract or make any x value execution-active.
1431
+
1368
1432
  Scope notes: `x:` is a key on the two *authored, engine-fired* shapes
1369
1433
  (`RAW_DEF_KEYS`, `RAW_STEP_KEYS`). It is **not** in the smaller
1370
1434
  `calls:`/`include:` directive shapes (same shape-routing rule as §27.2 —
@@ -1612,7 +1676,11 @@ dynamic feedback, so it stays); the acceptance lifecycle state it used to
1612
1676
  duplicate is read from the artifact row, which is where it lives anyway
1613
1677
  (§5, §24.1). The claim-time invariant is unchanged: the order is built and
1614
1678
  the run row is inserted in the same transaction, and the persisted
1615
- `RunData.order` is byte-identical to the packet `tick` handed out.
1679
+ `RunData.order` is byte-identical to the packet `tick` handed out. That is a
1680
+ claim-time invariant, not a lifetime one: the single post-claim write to a
1681
+ persisted order is `Store.restampOrderTarget`, which rewrites one
1682
+ `owes[].version` when a reject re-arms a still-open claim whose artifact the
1683
+ preceding commit already bumped.
1616
1684
 
1617
1685
  ### §29.1 `defDigest` — instruction-content identity
1618
1686
 
@@ -1682,7 +1750,7 @@ addressed by digest.
1682
1750
  record or throws the named refusal; `resolveOrder(order)` builds the
1683
1751
  `{defDigest, step, key}` ref from an order and additionally materializes the
1684
1752
  runtime placeholders in the resolved prompt — the same substitution
1685
- `${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MAX_ATTEMPTS}` that
1753
+ `${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MODIFIER}`/`${MAX_ATTEMPTS}` that
1686
1754
  `buildOrder` used to inline, moved whole to resolution time (unknown
1687
1755
  placeholders stay untouched; `MAX_ATTEMPTS` renders the `maxAttempts` metadata
1688
1756
  from the resolved instruction record). Substitution
@@ -1846,3 +1914,65 @@ path still requires a pre-commit verifier and remains fail-closed when that
1846
1914
  adapter is not provided. The ingestor and verifier are separate concerns:
1847
1915
  ingestion makes the bundle's verified object available, while the verifier
1848
1916
  decides whether the install may commit it.
1917
+
1918
+ ## §31 Cleanup on cancellation (`onCancel:`)
1919
+
1920
+ The engine's step grammar has a declarative cleanup marker:
1921
+
1922
+ ```yaml
1923
+ - name: deprovisioner
1924
+ consumes: [merge, workspace]
1925
+ onCancel:
1926
+ consumes: [workspace]
1927
+ ```
1928
+
1929
+ This is deliberately a new step key rather than another `on:` token.
1930
+
1931
+ | Existing key | What it means | Why it is not cleanup-on-cancel |
1932
+ |---|---|---|
1933
+ | `terminal: true` | A step's green is a destructive completion. | It says nothing about run lifecycle. |
1934
+ | `effect.onInvalidate` | Routes an already-green artifact after its inputs move. | Cancellation is not an input move. |
1935
+ | `on:` | Pure in-run firing vocabulary. | It has no lifecycle signal or per-trigger consume payload. |
1936
+ | `idleAfter:` | Duration sidecar for `on: [idle]`. | It is unrelated to cancellation. |
1937
+ | `x:` | Opaque extension map. | It cannot validate this declaration or catch typos. |
1938
+
1939
+ Finally, `on:` is evaluated by the clock-free, state-pure
1940
+ `eligibleFirings(ArtifactMap, TimeFacts)`; cancellation is neither artifact
1941
+ state nor a time fact, and `WorkflowData` has no instance status. It therefore
1942
+ cannot be a scheduler trigger in this package.
1943
+
1944
+ `onCancel:` is a mapping with exactly one required key, `consumes:`, a list of
1945
+ strings that may be empty. Every entry must be a unique stem from the owning
1946
+ step's own plain consumes. Map and reduce consumes have no key binding on a
1947
+ one-time cancellation firing and are refused. The key is refused on `calls:`
1948
+ steps by that grammar's smaller key allowlist. `allGreen` and `idle`
1949
+ evaluators may declare `onCancel:` only with an empty list because they cannot
1950
+ declare normal consumes. `terminal: true` together with `onCancel:` remains
1951
+ legal deliberately: the engine does not infer an author's cleanup policy.
1952
+
1953
+ `onCancel:` is inert in the standalone engine. It does not affect
1954
+ `eligibleFirings`, `modelCheck`, the forward cascade, or done-ness. A host
1955
+ with no cancellation concept loads a definition carrying it with no behavior
1956
+ change.
1957
+
1958
+ The control plane contract is:
1959
+
1960
+ > **`onCancel:` contract.** When the control plane cancels a run of instance `W`:
1961
+ >
1962
+ > 1. Resolve `W`'s def — `WorkflowData.defSnapshot` when pinned (§28), otherwise by name.
1963
+ > 2. Select the cleanup steps: `cancelCleanupSteps(def)` (exported from `owenloop`), i.e. every
1964
+ > step where `step.onCancel !== undefined`, in def order.
1965
+ > 3. For each such step `S`: if **every** stem in `S.onCancel.consumes` is green, dispatch an
1966
+ > order for `S` whose inputs are exactly those stems and their values. If any is not green,
1967
+ > `S` is not dispatchable — record that and do not block cancellation on it.
1968
+ > 4. `assertServableInstance` (`packages/hub-core/src/serving.ts`) must admit an order on a
1969
+ > `cancelled` instance **only** when that order is for a step selected in step 2. Every other
1970
+ > step stays refused, exactly as today.
1971
+ > 5. A step with no `onCancel:` is never dispatched after cancel — today's behaviour, unchanged.
1972
+ > 6. **Recommended, and the follow-on run's call to confirm:** hold the cancelled instance out of
1973
+ > its final closed state until each dispatched cleanup step's produces settle (green, or
1974
+ > exhausted per that step's `maxAttempts`). Closing immediately would reproduce the original
1975
+ > defect in a slower form — the order exists but nothing waits for it.
1976
+ > 7. `onCancel:` is inert in the standalone engine. `eligibleFirings`, `modelCheck`, the forward
1977
+ > cascade, and done-ness do not read it. A host with no cancellation concept loads and runs a
1978
+ > def carrying it with no behaviour change.