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/authoring.md CHANGED
@@ -41,7 +41,8 @@ steps:
41
41
  properties: { plan: { type: string } }
42
42
  # maxAttempts: 2 # optional; overrides the step's maxAttempts (below)
43
43
  # maxSchemaFailures: 1 # just for this produce — see design.md §6
44
- body: | # the prompt; ${WORKFLOW} ${RUN} ${INDEX} are filled in
44
+ # bind: modifier # accepted value's `modifier` key writes through to run routing
45
+ body: | # the prompt; runtime placeholders are filled in when available
45
46
  Read the proposal and produce a `plan`.
46
47
  bodyFile: path/to.md # load body from a file, relative to this workflow's dir (must resolve inside it); mutually exclusive with body
47
48
 
@@ -62,6 +63,8 @@ steps:
62
63
  onInvalidate: escalate # consulted only when idempotent: false (see below)
63
64
  on: [inputsGreen] # optional; firing trigger (see below)
64
65
  idleAfter: 30m # required when 'idle' is in on:
66
+ onCancel: # optional cleanup declaration (see below)
67
+ consumes: [workspace] # plain consume subset needed after cancellation
65
68
  invalidates: [plan] # which input stems this step may invalidate
66
69
  cadence: "0s" # min spacing between runs (e.g. "30m")
67
70
  maxRunsPerDay: 1000
@@ -89,6 +92,92 @@ steps:
89
92
  anything: goes # untouched onto the order (Order.x); see design.md §27.3
90
93
  ```
91
94
 
95
+ ## x.discovery — advisory workflow discovery metadata
96
+
97
+ x.discovery is an Owenloop-owned convention inside the otherwise opaque
98
+ top-level x: map. It lets a person or catalog tool understand what a workflow
99
+ does, when to choose it, when a close-looking workflow is the wrong choice, and
100
+ how to seed/read its public interface:
101
+
102
+ ~~~yaml
103
+ x:
104
+ discovery:
105
+ description: >-
106
+ One non-empty paragraph explaining the workflow in colleague-facing language.
107
+ whenToUse:
108
+ - a non-empty trigger phrase
109
+ notFor:
110
+ - a non-empty anti-trigger phrase
111
+ interface:
112
+ inputs:
113
+ - name: proposal
114
+ summary: A non-empty description of the seed value.
115
+ schemaRef: "#/inputs/0/schema"
116
+ outputs:
117
+ - name: merge
118
+ summary: A non-empty description of the public result.
119
+ schemaRef: "#/steps/6/produces/0/schema"
120
+ ~~~
121
+
122
+ The bag itself is optional today, so existing definitions remain compatible.
123
+ Its absence is a lint warning, not a loading or execution failure. Once the bag
124
+ is present, all four top-level fields are required: catalog browsing
125
+ (description), positive routing (whenToUse), false-positive avoidance (notFor),
126
+ and usable seeding/result information (interface) answer separate questions. In
127
+ particular, an anti-trigger is not redundant with a trigger: it rules out the
128
+ nearby cases that would otherwise appear to match.
129
+
130
+ description must be a non-empty string. whenToUse and notFor must each be
131
+ non-empty arrays of non-empty strings. interface.inputs and interface.outputs
132
+ are required arrays, though either can be empty when the workflow genuinely has
133
+ no declared inputs or no public outputs. Each entry must have a non-empty name,
134
+ summary, and schemaRef. The entries cover every declared input and every public
135
+ outputs: name exactly once; no unknown or duplicate names are allowed. Their
136
+ named artifacts must carry schemas. schemaRef is a local JSON Pointer beginning
137
+ #/ to that existing machine schema, not a second copy of the schema.
138
+
139
+ owenloop lint reports missing or malformed discovery data as field-specific
140
+ warnings. These warnings do not fail lint, loading, packing, publishing, pushing,
141
+ or execution. Other x vocabularies remain opaque and unrestricted; only this
142
+ authoring-lint convention is recognized.
143
+
144
+ ## x.implements — advisory external interface claims
145
+
146
+ When present, x.implements must be a non-empty array of external interface
147
+ coordinates a definition claims to satisfy:
148
+
149
+ ~~~yaml
150
+ x:
151
+ implements:
152
+ - name: research-report
153
+ version: "1"
154
+ - name: auditable-report
155
+ version: "2026-08"
156
+ ~~~
157
+
158
+ Every entry contains exactly non-empty string name and version fields. More
159
+ than one claim is allowed, but an exact name/version coordinate may appear only
160
+ once. Version is intentionally an opaque string here: Owenloop does not impose
161
+ SemVer or catalog policy. Malformed claims are warning-only authoring lint, so
162
+ they neither stop lint nor turn loading or execution into a failure. Keeping
163
+ the field under x also means binaries at engine version 1 ignore it and continue
164
+ to load definitions written before or after the convention.
165
+
166
+ x.discovery.interface and x.implements answer different questions.
167
+ x.discovery.interface describes this definition's own inputs and public outputs
168
+ and owns the local schemaRef vocabulary. x.implements only names an external
169
+ catalog contract; it deliberately copies no schemas, artifact mappings, or
170
+ summaries and introduces no second pointer convention. Catalog lookup and
171
+ publish-time rejection are hub responsibilities, not owenloop lint.
172
+
173
+ Catalog or publish tooling that needs to compare a claimed interface with a
174
+ workflow can use the exported `checkInterfaceCompatibility` helper. It checks
175
+ inputs contravariantly and outputs covariantly using the supported structural
176
+ JSON Schema subset. When a schema combines root constraints with a top-level
177
+ `anyOf` or `oneOf`, those root constraints remain in force while branch coverage
178
+ is checked; union branches are not treated as standalone schemas. The checker
179
+ continues to fail closed for unsupported or unprovable schema constructs.
180
+
92
181
  ## `model:` — quality tiers, not vendor ids
93
182
 
94
183
  The engine never calls a model; `model:` is an opaque string that rides the
@@ -225,7 +314,9 @@ full contract.
225
314
  A command step's `consumes:` reach the command through its environment, not its
226
315
  working directory: `owenloop work exec` sets `OWENLOOP_CONSUMES` with the JSON
227
316
  inline, or `OWENLOOP_CONSUMES_FILE` with a path to it once that JSON exceeds
228
- 64 KiB. See [`docs/bundles.md` § Consumed inputs for command
317
+ 64 KiB. The worker also supplies rejection feedback and the order's current
318
+ modifier through `OWENLOOP_FEEDBACK`/`OWENLOOP_FEEDBACK_FILE` and
319
+ `OWENLOOP_MODIFIER`. See [`docs/bundles.md` § Consumed inputs for command
229
320
  steps](bundles.md#consumed-inputs-for-command-steps) for the reader snippet and
230
321
  the omitted-key rule.
231
322
 
@@ -306,6 +397,52 @@ check.
306
397
  `capabilities:` says *which* caller may claim it in the first place — a tick filter
307
398
  locally, a bound crew on a hub.
308
399
 
400
+ ### The trust boundary: publishing shares, installing scopes
401
+
402
+ `push` and `install` both put a def on your hub, and they treat its capabilities
403
+ differently on purpose.
404
+
405
+ `owenloop push` publishes defs **your org authored**. Their capabilities join the
406
+ org's **shared** vocabulary as written: two of your own defs that both author
407
+ `review` deliberately mean the same `review`, served by the same crews. That is
408
+ the whole value of a shared vocabulary.
409
+
410
+ `owenloop install <owner>/<repo>` publishes a def **someone else authored**. An
411
+ outside author writing `review` is not making your org's claim, so every
412
+ capability an installed def authors becomes `<def-name>.<capability>` —
413
+ `analyzer.review`, not `review` — unless you say otherwise, once, at install
414
+ time. Scoping is the default because the failure it prevents is silent: an
415
+ outside def entering the shared vocabulary starts drawing orders from the crews
416
+ already bound to that name.
417
+
418
+ Link deliberately, when you actually mean it. If your `reviewers` crew genuinely
419
+ should serve the installed def's `review`, answer the install prompt with
420
+ `code-review` (or whatever your org calls it), or pass
421
+ `--map review=code-review`. Then the org name it takes is the one your crews are
422
+ already bound to, and it draws from them by design rather than by collision.
423
+
424
+ **Never edit a def's content to get the mapping you want.** The mapping is
425
+ org-side data, recorded against `(def, authored-name)` on your hub; the def stays
426
+ byte-for-byte as its author wrote it, so upstream updates keep applying. Editing
427
+ `capabilities:` in a def you did not author forks it.
428
+
429
+ Four names, in the order the engine derives them:
430
+
431
+ | Vocabulary | Where it comes from |
432
+ | --- | --- |
433
+ | **authored** | what the def's YAML says, e.g. `review` |
434
+ | **mapped** | the org name a capability mapping gives it, e.g. `analyzer.review` |
435
+ | **composed** | the mapped name plus the run's modifier, e.g. `analyzer.review:deep` |
436
+ | **offered** | the composed name after any capability reroute rewrites it |
437
+
438
+ The two rewrite points key on different halves and fire at different times.
439
+ **Mappings key on the AUTHORED name and apply BEFORE composition** — they answer
440
+ "what does this def's `review` mean here". **Reroutes key on the COMPOSED string
441
+ and apply AFTER composition** — they answer "where should `analyzer.review:deep`
442
+ go right now". A reroute is therefore the operational lever (move traffic
443
+ today); a mapping is the identity decision (what this def's capability *is* in
444
+ your org).
445
+
309
446
  ## `produces:` vs `generates:`
310
447
 
311
448
  A stem under `produces:` is expected to be consumed downstream — owenloop's lint warns
@@ -314,6 +451,57 @@ if nothing consumes it. A stem under `generates:` is deliberately consumed by no
314
451
  are otherwise identical: schema-validated, fingerprinted, greenable, and visible in
315
452
  `status`/`show`.
316
453
 
454
+ ## `bind:` — write an accepted artifact into run state
455
+
456
+ A produce mapping may declare a `bind:` target. When that artifact is accepted,
457
+ the engine writes the selected value into the run instance in the same
458
+ acceptance transaction. The artifact's own version and event history remains the
459
+ record of the value and any later rejection; the bind adds the engine's sync
460
+ event.
461
+
462
+ The short form reads the accepted object's key named after the final segment of
463
+ the target. Here, the producer submits an object such as
464
+ `{ modifier: 'deep' }`; `bind: modifier` reads its `modifier` key.
465
+
466
+ ```yaml
467
+ modifiers: [express, standard, deep]
468
+ steps:
469
+ - name: choose_modifier
470
+ produces:
471
+ - name: modifier
472
+ bind: modifier
473
+ ```
474
+
475
+ The mapping form selects a dotted object path. It is equivalent to the short
476
+ form when `from` is omitted: `bind: { to: meta.customer }` reads the
477
+ accepted object's `customer` key.
478
+
479
+ ```yaml
480
+ - { name: customer, bind: { to: meta.customer } }
481
+ - name: decision
482
+ bind: { to: modifier, from: payload.value }
483
+ ```
484
+
485
+ The two supported target families are:
486
+
487
+ - `modifier` — the extracted value must be one member of the workflow's
488
+ declared `modifiers:` list. A name with whitespace cannot be in that list
489
+ because `modifiers:` refuses it at definition-parse time. A workflow may bind
490
+ `modifier` only once. A value outside the list is refused at submit time.
491
+ - `meta.<key>` — writes any JSON value into non-routing instance metadata.
492
+ Metadata never changes capability composition or routing.
493
+
494
+ `from` is always a dot-separated path through object keys; there is no
495
+ whole-value form. Arrays, escaping, and array indexes are not part of this
496
+ grammar. A missing path is a submit-time refusal.
497
+ Bindings are supported on singleton and map produces, not collection produces.
498
+ Only a green acceptance applies the bind: a producer submission that is waiting
499
+ for judges has not synchronized the run yet.
500
+
501
+ When a capability-bearing step can run before the modifier-bound artifact is
502
+ accepted, lint warns that the step is not downstream of the bound artifact.
503
+ Wire the dependency explicitly if that step must use the synchronized modifier.
504
+
317
505
  ## `judges:` — quality gates before green
318
506
 
319
507
  A `produces` entry can declare one or more **judges**: deterministic quality
@@ -426,11 +614,13 @@ produces:
426
614
  - **`atLeastOne`** — no refusal, no auto-skip; once any one member is green,
427
615
  the rest no longer count as outstanding for done-ness.
428
616
 
429
- A group's auto-skip re-arms exactly like a manual skip (same fingerprint
430
- mechanism) if the upstream inputs it depended on move. See
617
+ A manual/branch skip re-arms only after its upstream inputs move. An exclusive
618
+ group skip has an additional inverse: if the green winner is rejected or
619
+ retracted, a sibling whose latest skip reason is `exclusive` immediately
620
+ returns to `owed`; a structurally skipped sibling does not. See
431
621
  [`routing-groups.yaml`](../examples/workflows/routing-groups.yaml) for a
432
- runnable example, and [`docs/design.md` §26](design.md) for the full
433
- design (refusal timing, the judges interaction, and the model-checker parity
622
+ runnable example, and [`docs/design.md` §26](design.md) for the full design
623
+ (refusal timing, the judges interaction, and the model-checker parity
434
624
  guarantee).
435
625
 
436
626
  Eligibility (the automatic sweep) is pre-filtered the same way commit-time
@@ -504,7 +694,7 @@ steps:
504
694
  calls: delivery # bare local name; use <package>/<workflow> for a CAS target
505
695
  inputs: # child input → parent artifact (gate: sandbox green)
506
696
  proposal: proposal
507
- produces: [delivered] # one parent artifact; greens when delivery's output greens
697
+ produces: [delivered] # mirrors a green/value-defined output only after delivery is done
508
698
  - name: teardown
509
699
  consumes: [delivered]
510
700
  produces: [torn_down]
@@ -512,9 +702,12 @@ steps:
512
702
  body: Tear down and green `torn_down`.
513
703
  ```
514
704
 
515
- The engine spawns the child when the gate inputs are green, greens the parent's
516
- `calls:` output when the child's declared output greens (no Worker run), and re-provides
517
- inputs to the existing child if a gate input changes — it never spawns a duplicate.
705
+ The engine spawns the child when the gate inputs are green and keeps the parent's
706
+ `calls:` output owed until the child's declared output is green/value-defined **and**
707
+ `workflowDone(childDef, childArts)` says the whole child is done. Only then does it
708
+ mirror that value into the parent (no Worker run). A child with cleanup or a manually
709
+ supplied input still outstanding keeps the parent output owed. If a gate input changes,
710
+ the engine re-provides it to the existing child — it never spawns a duplicate.
518
711
 
519
712
  | | `include:` (Mode 1) | `calls:` (Mode 2) |
520
713
  |---|---|---|
@@ -572,6 +765,38 @@ carry an empty input fingerprint, so a commit can never satisfy it, and
572
765
  relative `idleAfter` window and survives a process restart.
573
766
  `engine.nextAlarm(workflow)` tells an external scheduler when to wake the instance.
574
767
 
768
+ ## `onCancel:` — cleanup that survives cancellation
769
+
770
+ `onCancel:` declares that a step is cleanup a control plane should dispatch when
771
+ it cancels a run. It is **not** an `on:` firing trigger: the standalone engine
772
+ has no run-cancellation state and never schedules it. A host that supports
773
+ cancellation reads this declaration separately.
774
+
775
+ The declaration names the inputs needed on the cancel path:
776
+
777
+ ```yaml
778
+ - name: deprovisioner
779
+ consumes: [merge, workspace] # normal path
780
+ onCancel:
781
+ consumes: [workspace] # cancel path
782
+ ```
783
+
784
+ The subset is explicit because cancellation can leave a normal input permanently
785
+ non-green. In this example, `merge` is terminal and will not green after a
786
+ cancel, so the control plane must not guess whether to wait for it or omit it.
787
+
788
+ `onCancel:` must be a mapping with a required `consumes:` list; an empty list
789
+ is allowed. Each listed name must be one of the step's own plain consumes, and a
790
+ name may appear only once. Map (`[$i]`) and reduce (`[*]`) consumes are not
791
+ allowed because a cancellation firing is keyless and runs once. The key is not
792
+ valid on a `calls:` step. An `allGreen` or `idle` evaluator may carry
793
+ `onCancel:`, but because evaluators cannot consume inputs, its list must be
794
+ empty.
795
+
796
+ `terminal: true` and `onCancel:` are deliberately compatible. Whether running
797
+ a destructive step during cleanup is sensible is the workflow author's decision,
798
+ not an engine policy.
799
+
575
800
  ## Consume / produce grammar
576
801
 
577
802
  | pattern | role | fires |
package/docs/bundles.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # `.wnlp` bundle format
2
2
 
3
- A `.wnlp` file packages one versioned package namespace, one or more named workflow definitions, and the regular files those definitions reference. The physical format is a gzip-compressed POSIX/PAX tar archive. Packing the same source bytes and canonical executable-bit choices produces identical archive bytes.
3
+ A `.wnlp` file packages one versioned package namespace, one or more named workflow definitions, and the regular files those definitions reference. The physical format is a gzip-compressed POSIX/PAX tar archive. Packing the same source bytes and canonical executable-bit choices produces an identical uncompressed canonical tar and therefore an identical bundle digest. The gzip wrapper's compressed payload depends on the zlib implementation linked by the running Node process and is not part of the bundle identity.
4
4
 
5
5
  The bundle APIs are independent of the local workflow store and the network:
6
6
 
@@ -135,7 +135,7 @@ For every regular file:
135
135
  - Every entry's data padding, including the padding after a `PaxHeader` data record, is zero-filled.
136
136
  - The archive ends with exactly two zero blocks and no bytes after the terminator.
137
137
 
138
- The gzip wrapper uses compression level 9 and has no optional filename, comment, or extra fields. Gzip mtime bytes are zero, and gzip header byte 9 (the OS byte) is explicitly forced to zero so Darwin and Linux produce the same bytes.
138
+ The gzip wrapper uses compression level 9 and has no optional filename, comment, or extra fields. Its magic, CM, FLG, MTIME, and OS ranges (bytes 0-1, 2, 3, 4-7, and 9) are fixed; mtime is zero and header byte 9 (the OS byte) is explicitly forced to zero. XFL (byte 8) comes from the linked zlib implementation and is intentionally not normalized. The compressed payload itself varies with the linked zlib implementation and is not the bundle identity; see the def digest above.
139
139
 
140
140
  The canonical tar contains regular-file entries only. Parent directories are implied by `/`-separated file paths and are never emitted as tar entries. The strict reader rejects archive symlink, hardlink, device, FIFO, socket, directory, and unknown entry types. The packer rejects source symlinks and non-regular filesystem nodes. Absolute paths, `.` segments, and `..` traversal are refused rather than normalized.
141
141
 
@@ -161,6 +161,25 @@ This check is separate from the read-only file modes applied during install. Ins
161
161
 
162
162
  An executable file installed by an older Owenloop release may already have lost its execute bit because older hardening mapped every regular file to `0444`. Reinstalling the exact original `.wnlp` is a supported atomic repair for that same-digest object. Owenloop first applies strict archive parsing, manifest and runtime admission, configured signature and policy verification, per-file integrity verification, and canonical digest verification to the supplied archive. Owenloop then reconstructs and completely verifies a clean staged object before replacing the broken destination through the normal journaled directory swap. The broken object's bytes are never reused. The prior object remains as the swap backup until the unchanged same-digest index state is durably committed; a failed repair restores the recoverable prior object and index state. A successful repair preserves the existing coordinate-to-digest mapping, and a later reinstall follows normal idempotent deduplication.
163
163
 
164
+ ## Authenticated recovery for worker store misses
165
+
166
+ When a modern command or agent worker cannot resolve an exact order digest from
167
+ either local workflow store, it performs one authenticated recovery attempt.
168
+ Using that worker's scoped bearer, it reads raw canonical bytes from
169
+ `GET /api/bundles/<digest>`, required publication evidence from
170
+ `GET /api/publications/<digest>`, and optional origin evidence from
171
+ `GET /api/origins/<digest>`, then installs only into the global store. The
172
+ original store lookup is retried once after a successful install; a store hit
173
+ does no hub I/O.
174
+
175
+ Recovery is fail-closed. The installer compares the ingested canonical digest
176
+ with the order digest before any object or index mutation, and the required
177
+ pre-commit verifier validates the supplied publication/origin evidence under
178
+ the normal policy before the journaled install can commit. Missing or malformed
179
+ publication evidence, redirects, non-404 origin errors, body caps, timeouts,
180
+ content mismatches, invalid signatures, or policy refusals leave the store
181
+ unchanged and the worker reports the ordinary instruction-resolution failure.
182
+
164
183
  ## Bundle assets during execution
165
184
 
166
185
  When a command or agent step resolves its definition from an installed bundle,
@@ -255,6 +274,30 @@ consume-side verification under its hard rule and refuses the whole order when
255
274
  the consumed evidence is absent, unverifiable, or invalid, so the environment
256
275
  block is built only for an order whose inputs already verified.
257
276
 
277
+ ### Rejection feedback and modifier context
278
+
279
+ When an order has owed paths with non-empty reason threads, `owenloop work exec`
280
+ also supplies the feedback as a JSON array through one of these variables:
281
+
282
+ | Variable | Set when | Value |
283
+ | --- | --- | --- |
284
+ | `OWENLOOP_FEEDBACK` | serialized feedback is at or under 65536 bytes | inline array of `{path, reasons}` objects |
285
+ | `OWENLOOP_FEEDBACK_FILE` | serialized feedback is strictly larger | absolute path to a private `0600` UTF-8 file containing that array |
286
+
287
+ Exactly one feedback variable is present when feedback exists; both are removed
288
+ when there is no feedback, so a nested command cannot inherit a stale thread.
289
+ The overflow file is removed after the command exits. Each `reasons` entry is
290
+ the normal artifact reason shape and may include `requested`, the machine-readable
291
+ replacement requested for a bound modifier artifact.
292
+
293
+ `OWENLOOP_MODIFIER` is set to the modifier stamped on this order, including an
294
+ escalation target when the order is an escalated re-offer. It is absent when the
295
+ run has no modifier. This is order metadata, not an instruction to mutate the
296
+ run; only an accepted artifact with a declared bind can do that.
297
+
298
+ An agent prompt can read the same value as `${MODIFIER}`. Unknown placeholders
299
+ remain unchanged; when an order has no modifier, `${MODIFIER}` remains literal.
300
+
258
301
  ## Working directory for command steps
259
302
 
260
303
  An order carries a `workdir` when its step declared `workdir:` or