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.
- package/CHANGELOG.md +69 -0
- package/README.md +81 -39
- package/bin/owenloop.mjs +16 -1
- package/dist/packages/work/src/agent/loop.d.ts +23 -8
- package/dist/packages/work/src/agent/loop.js +55 -6
- package/dist/packages/work/src/bundle/pull.d.ts +21 -0
- package/dist/packages/work/src/bundle/pull.js +118 -0
- package/dist/packages/work/src/consumed-verifier.js +6 -17
- package/dist/packages/work/src/exec/instructions.d.ts +4 -1
- package/dist/packages/work/src/exec/instructions.js +3 -0
- package/dist/packages/work/src/exec/loop.d.ts +2 -2
- package/dist/packages/work/src/exec/loop.js +273 -46
- package/dist/packages/work/src/exec/receipt.d.ts +7 -7
- package/dist/packages/work/src/exec/receipt.js +6 -6
- package/dist/packages/work/src/harness/claude.js +116 -0
- package/dist/packages/work/src/harness/codex.d.ts +8 -0
- package/dist/packages/work/src/harness/codex.js +27 -1
- package/dist/packages/work/src/harness/contract.d.ts +9 -0
- package/dist/packages/work/src/hub/client.d.ts +19 -4
- package/dist/packages/work/src/hub/client.js +7 -3
- package/dist/packages/work/src/hub/types.d.ts +84 -0
- package/dist/packages/work/src/main.js +1 -0
- package/dist/packages/work/src/roles/agent-run.js +57 -32
- package/dist/packages/work/src/roles/exec.js +27 -8
- package/dist/packages/work/src/roles/settings.js +2 -0
- package/dist/packages/work/src/roles/shift.js +14 -2
- package/dist/packages/work/src/roles/util.d.ts +1 -0
- package/dist/packages/work/src/roles/util.js +10 -0
- package/dist/packages/work/src/settings/hub-roster-cache.d.ts +68 -0
- package/dist/packages/work/src/settings/hub-roster-cache.js +370 -0
- package/dist/packages/work/src/settings/roster.d.ts +84 -0
- package/dist/packages/work/src/settings/roster.js +364 -5
- package/dist/packages/work/src/settings/serving.d.ts +17 -0
- package/dist/packages/work/src/settings/serving.js +79 -0
- package/dist/packages/work/src/settings/settings.d.ts +14 -1
- package/dist/packages/work/src/settings/settings.js +14 -0
- package/dist/packages/work/src/shift/loop.d.ts +108 -5
- package/dist/packages/work/src/shift/loop.js +416 -54
- package/dist/packages/work/src/shift/protocol.d.ts +7 -5
- package/dist/packages/work/src/shift/runtime.d.ts +18 -0
- package/dist/packages/work/src/shift/runtime.js +104 -5
- package/dist/packages/work/src/shift/server.js +2 -0
- package/dist/packages/work/src/shift/spawn.d.ts +17 -2
- package/dist/packages/work/src/shift/spawn.js +16 -13
- package/dist/packages/work/src/shift/state.d.ts +29 -2
- package/dist/packages/work/src/shift/state.js +45 -15
- package/dist/packages/work/src/submit-proof.d.ts +11 -8
- package/dist/packages/work/src/submit-proof.js +11 -8
- package/dist/packages/work/src/usage.d.ts +1 -1
- package/dist/packages/work/src/usage.js +7 -1
- package/dist/packages/work/src/util/modifier-init.d.ts +7 -0
- package/dist/packages/work/src/util/modifier-init.js +73 -0
- package/dist/src/bundle/tar.d.ts +9 -4
- package/dist/src/bundle/tar.js +9 -4
- package/dist/src/capabilities.d.ts +76 -6
- package/dist/src/capabilities.js +49 -6
- package/dist/src/capability-mapping-client.d.ts +29 -0
- package/dist/src/capability-mapping-client.js +160 -0
- package/dist/src/cli.d.ts +16 -3
- package/dist/src/cli.js +1925 -281
- package/dist/src/config-dir.d.ts +1 -1
- package/dist/src/config-dir.js +1 -1
- package/dist/src/crypto/index.d.ts +1 -1
- package/dist/src/crypto/index.js +1 -1
- package/dist/src/crypto/org-root.d.ts +30 -12
- package/dist/src/crypto/org-root.js +162 -14
- package/dist/src/crypto/records.d.ts +2 -0
- package/dist/src/crypto/records.js +2 -0
- package/dist/src/defs.d.ts +38 -2
- package/dist/src/defs.js +593 -86
- package/dist/src/engine.d.ts +103 -25
- package/dist/src/engine.js +331 -79
- package/dist/src/hub.d.ts +77 -0
- package/dist/src/hub.js +162 -0
- package/dist/src/implements.d.ts +56 -0
- package/dist/src/implements.js +790 -0
- package/dist/src/index.d.ts +11 -9
- package/dist/src/index.js +6 -5
- package/dist/src/mcp/serve.d.ts +22 -0
- package/dist/src/mcp/serve.js +330 -41
- package/dist/src/mcp/server.d.ts +10 -7
- package/dist/src/mcp/server.js +53 -8
- package/dist/src/model.d.ts +48 -10
- package/dist/src/model.js +252 -99
- package/dist/src/order-resolver.d.ts +1 -0
- package/dist/src/order-resolver.js +8 -1
- package/dist/src/schemas/index.d.ts +11 -0
- package/dist/src/schemas/order.v1.schema.json +7 -1
- package/dist/src/store/def-source.d.ts +19 -0
- package/dist/src/store/def-source.js +87 -17
- package/dist/src/store/gc-recovery.d.ts +46 -0
- package/dist/src/store/gc-recovery.js +258 -0
- package/dist/src/store/gc.d.ts +94 -0
- package/dist/src/store/gc.js +562 -0
- package/dist/src/store/index.d.ts +3 -1
- package/dist/src/store/index.js +2 -0
- package/dist/src/store/install.d.ts +34 -5
- package/dist/src/store/install.js +73 -11
- package/dist/src/store/pre-commit-verifier.js +42 -2
- package/dist/src/store/snapshot-guard.d.ts +18 -0
- package/dist/src/store/snapshot-guard.js +94 -0
- package/dist/src/store.d.ts +69 -4
- package/dist/src/store.js +254 -16
- package/dist/src/types.d.ts +101 -20
- package/dist/src/util.js +4 -1
- package/docs/authoring.md +235 -10
- package/docs/bundles.md +45 -2
- package/docs/cli.md +437 -55
- package/docs/crypto.md +32 -10
- package/docs/design.md +177 -47
- package/docs/evals/mcp-charter-baseline.json +428 -0
- package/docs/mcp-charter-eval.md +124 -0
- package/docs/routing.md +189 -34
- package/docs/shift-logs.md +38 -9
- package/docs/wire-contracts.md +78 -14
- package/examples/workflows/compile-dev-playbook.yaml +1 -1
- package/examples/workflows/delivery.yaml +31 -14
- package/examples/workflows/ship.yaml +38 -4
- package/package.json +2 -1
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
- package/plugins/claude-code/plugin/.mcp.json +1 -1
- package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
- package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
- package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
- package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
- package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
- package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
- package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
- 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/
|
|
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
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
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>/
|
|
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. `
|
|
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.
|
|
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, `
|
|
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).
|
|
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)
|
|
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)
|
|
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]`
|
|
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
|
|
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
|
|
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)
|
|
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
|
|
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
|
-
-
|
|
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
|
|
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),
|
|
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`,
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
|
|
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
|
-
|
|
1004
|
-
buckets, by recomputing eligibility
|
|
1005
|
-
(`eligibleFirings(def, arts,
|
|
1006
|
-
|
|
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)
|
|
1011
|
-
|
|
1012
|
-
|
|
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
|
|
1015
|
-
structural dead-end (e.g. a `group:`-blocked or
|
|
1016
|
-
owed input with no producer). This is folded
|
|
1017
|
-
makes `check` exit nonzero — but only when the
|
|
1018
|
-
(`!report.bounded`), since a tight
|
|
1019
|
-
can otherwise manufacture a spurious
|
|
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-
|
|
1176
|
-
|
|
1177
|
-
|
|
1178
|
-
|
|
1179
|
-
|
|
1180
|
-
|
|
1181
|
-
|
|
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
|
|
1245
|
-
|
|
1246
|
-
|
|
1247
|
-
|
|
1248
|
-
|
|
1249
|
-
|
|
1250
|
-
|
|
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.
|