owenloop 0.5.9 → 0.5.11

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 (86) hide show
  1. package/CHANGELOG.md +51 -0
  2. package/README.md +77 -37
  3. package/bin/owenloop.mjs +16 -1
  4. package/dist/packages/work/src/agent/loop.js +7 -0
  5. package/dist/packages/work/src/bundle/pull.d.ts +21 -0
  6. package/dist/packages/work/src/bundle/pull.js +118 -0
  7. package/dist/packages/work/src/exec/instructions.d.ts +4 -1
  8. package/dist/packages/work/src/exec/instructions.js +3 -0
  9. package/dist/packages/work/src/exec/loop.d.ts +1 -1
  10. package/dist/packages/work/src/exec/loop.js +92 -14
  11. package/dist/packages/work/src/harness/claude.js +16 -0
  12. package/dist/packages/work/src/harness/codex.d.ts +8 -0
  13. package/dist/packages/work/src/harness/codex.js +27 -1
  14. package/dist/packages/work/src/harness/contract.d.ts +9 -0
  15. package/dist/packages/work/src/roles/agent-run.js +38 -10
  16. package/dist/packages/work/src/roles/exec.js +25 -8
  17. package/dist/packages/work/src/shift/loop.js +118 -4
  18. package/dist/packages/work/src/shift/runtime.d.ts +3 -0
  19. package/dist/packages/work/src/shift/runtime.js +10 -1
  20. package/dist/packages/work/src/submit-proof.d.ts +11 -8
  21. package/dist/packages/work/src/submit-proof.js +11 -8
  22. package/dist/src/capabilities.d.ts +70 -6
  23. package/dist/src/capabilities.js +49 -6
  24. package/dist/src/capability-mapping-client.d.ts +29 -0
  25. package/dist/src/capability-mapping-client.js +160 -0
  26. package/dist/src/cli.d.ts +2 -2
  27. package/dist/src/cli.js +1200 -166
  28. package/dist/src/defs.d.ts +41 -1
  29. package/dist/src/defs.js +461 -92
  30. package/dist/src/engine.d.ts +108 -22
  31. package/dist/src/engine.js +573 -85
  32. package/dist/src/factory.js +5 -3
  33. package/dist/src/hub.d.ts +77 -0
  34. package/dist/src/hub.js +162 -0
  35. package/dist/src/implements.d.ts +37 -0
  36. package/dist/src/implements.js +790 -0
  37. package/dist/src/index.d.ts +12 -10
  38. package/dist/src/index.js +7 -6
  39. package/dist/src/mcp/serve.js +254 -45
  40. package/dist/src/mcp/server.d.ts +10 -7
  41. package/dist/src/mcp/server.js +53 -8
  42. package/dist/src/model.d.ts +46 -10
  43. package/dist/src/model.js +224 -78
  44. package/dist/src/order-resolver.js +1 -0
  45. package/dist/src/store/def-source.d.ts +19 -0
  46. package/dist/src/store/def-source.js +87 -17
  47. package/dist/src/store/gc-recovery.d.ts +46 -0
  48. package/dist/src/store/gc-recovery.js +258 -0
  49. package/dist/src/store/gc.d.ts +94 -0
  50. package/dist/src/store/gc.js +563 -0
  51. package/dist/src/store/index.d.ts +3 -1
  52. package/dist/src/store/index.js +2 -0
  53. package/dist/src/store/install.d.ts +34 -5
  54. package/dist/src/store/install.js +73 -11
  55. package/dist/src/store/pre-commit-verifier.js +42 -2
  56. package/dist/src/store/snapshot-guard.d.ts +18 -0
  57. package/dist/src/store/snapshot-guard.js +94 -0
  58. package/dist/src/store.d.ts +66 -4
  59. package/dist/src/store.js +333 -12
  60. package/dist/src/types.d.ts +97 -17
  61. package/dist/src/types.js +4 -0
  62. package/dist/src/util.js +4 -1
  63. package/docs/authoring.md +214 -9
  64. package/docs/bundles.md +19 -0
  65. package/docs/cli.md +270 -30
  66. package/docs/crypto.md +13 -7
  67. package/docs/design.md +107 -46
  68. package/docs/evals/mcp-charter-baseline.json +428 -0
  69. package/docs/mcp-charter-eval.md +124 -0
  70. package/docs/shift-logs.md +18 -0
  71. package/docs/wire-contracts.md +28 -7
  72. package/examples/workflows/compile-dev-playbook.yaml +1 -1
  73. package/examples/workflows/ship.yaml +28 -2
  74. package/package.json +2 -1
  75. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  76. package/plugins/claude-code/plugin/.mcp.json +1 -1
  77. package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
  78. package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
  79. package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
  80. package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
  81. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  82. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  83. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
  84. package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
  85. package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
  86. package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
package/docs/authoring.md CHANGED
@@ -92,6 +92,92 @@ steps:
92
92
  anything: goes # untouched onto the order (Order.x); see design.md §27.3
93
93
  ```
94
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
+
95
181
  ## `model:` — quality tiers, not vendor ids
96
182
 
97
183
  The engine never calls a model; `model:` is an opaque string that rides the
@@ -311,6 +397,52 @@ check.
311
397
  `capabilities:` says *which* caller may claim it in the first place — a tick filter
312
398
  locally, a bound crew on a hub.
313
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
+
314
446
  ## `produces:` vs `generates:`
315
447
 
316
448
  A stem under `produces:` is expected to be consumed downstream — owenloop's lint warns
@@ -419,6 +551,16 @@ regardless of `executor:` — that requirement is orthogonal to this feature and
419
551
  applies even to a `executor: command` judge (the field just goes unread by a
420
552
  non-agent dispatcher).
421
553
 
554
+ Native judges declared here inherit the producing step's `capabilities:` when a
555
+ judge omits that key: the synthesized judge receives a copy. A non-empty
556
+ `capabilities:` list on the judge is authoritative and replaces — rather than
557
+ extends — the producer list; `capabilities: []` is invalid, so omit the key to
558
+ request inheritance. At offer time, the run modifier composes with every
559
+ capability in the resulting judge list just as it does for an ordinary step
560
+ (for example, `wise` under `deep` is offered as `wise:deep`). If neither the
561
+ producer nor judge supplies capabilities, the judge remains capability-silent,
562
+ and there is nothing to compose.
563
+
422
564
  Author `x:` on the producer step, not on individual judge entries. Every native
423
565
  judge synthesized from that producer inherits the producer's complete parsed
424
566
  `x:` map. Each judge receives an independent deep clone, so runner-side
@@ -482,11 +624,13 @@ produces:
482
624
  - **`atLeastOne`** — no refusal, no auto-skip; once any one member is green,
483
625
  the rest no longer count as outstanding for done-ness.
484
626
 
485
- A group's auto-skip re-arms exactly like a manual skip (same fingerprint
486
- mechanism) if the upstream inputs it depended on move. See
627
+ A manual/branch skip re-arms only after its upstream inputs move. An exclusive
628
+ group skip has an additional inverse: if the green winner is rejected or
629
+ retracted, a sibling whose latest skip reason is `exclusive` immediately
630
+ returns to `owed`; a structurally skipped sibling does not. See
487
631
  [`routing-groups.yaml`](../examples/workflows/routing-groups.yaml) for a
488
- runnable example, and [`docs/design.md` §26](design.md) for the full
489
- design (refusal timing, the judges interaction, and the model-checker parity
632
+ runnable example, and [`docs/design.md` §26](design.md) for the full design
633
+ (refusal timing, the judges interaction, and the model-checker parity
490
634
  guarantee).
491
635
 
492
636
  Eligibility (the automatic sweep) is pre-filtered the same way commit-time
@@ -508,7 +652,7 @@ from dead-end warnings, but unlike `terminal:` they stay re-armable.
508
652
  | `generates:` | step | yes | yes | internal sink, not the public interface |
509
653
  | `outputs:` | workflow | yes | yes | public interface / composition boundary |
510
654
 
511
- ## Composition — `include:` (compile-time) and `calls:` (runtime)
655
+ ## Composition — `include:` (compile-time) and runtime calls
512
656
 
513
657
  Two ways to build a workflow out of other workflows:
514
658
 
@@ -560,7 +704,7 @@ steps:
560
704
  calls: delivery # bare local name; use <package>/<workflow> for a CAS target
561
705
  inputs: # child input → parent artifact (gate: sandbox green)
562
706
  proposal: proposal
563
- produces: [delivered] # one parent artifact; greens when delivery's output greens
707
+ produces: [delivered] # mirrors a green/value-defined output only after delivery is done
564
708
  - name: teardown
565
709
  consumes: [delivered]
566
710
  produces: [torn_down]
@@ -568,9 +712,12 @@ steps:
568
712
  body: Tear down and green `torn_down`.
569
713
  ```
570
714
 
571
- The engine spawns the child when the gate inputs are green, greens the parent's
572
- `calls:` output when the child's declared output greens (no Worker run), and re-provides
573
- inputs to the existing child if a gate input changes — it never spawns a duplicate.
715
+ The engine spawns the child when the gate inputs are green and keeps the parent's
716
+ `calls:` output owed until the child's declared output is green/value-defined **and**
717
+ `workflowDone(childDef, childArts)` says the whole child is done. Only then does it
718
+ mirror that value into the parent (no Worker run). A child with cleanup or a manually
719
+ supplied input still outstanding keeps the parent output owed. If a gate input changes,
720
+ the engine re-provides it to the existing child — it never spawns a duplicate.
574
721
 
575
722
  | | `include:` (Mode 1) | `calls:` (Mode 2) |
576
723
  |---|---|---|
@@ -579,6 +726,64 @@ inputs to the existing child if a gate input changes — it never spawns a dupli
579
726
  | Use for | New combined workflows | Embedding an existing workflow as a black box |
580
727
  | Visibility | All child stems visible in the parent | Only the declared `produces:` artifact |
581
728
 
729
+ ### Calling a start-bound interface
730
+
731
+ `callsInterface:` is the interface-targeted form of a runtime call. The workflow
732
+ author names the exact interface version the step requires, while the host that starts
733
+ the instance selects the installed implementation. The engine validates that selection
734
+ before it writes the root instance and pins the complete binding set for the lifetime of
735
+ the run.
736
+
737
+ ```yaml
738
+ steps:
739
+ - name: report
740
+ callsInterface:
741
+ name: report
742
+ version: 1.0.0
743
+ inputs:
744
+ source: prepared_source
745
+ produces: [report]
746
+ ```
747
+
748
+ `callsInterface:` and `calls:` are mutually exclusive. Otherwise the call-step contract
749
+ is the same: exactly one `produces:` entry, child-input-to-parent-artifact `inputs:`
750
+ wiring, no `judges:` or `group:`, engine-managed spawning, and no Worker order for the
751
+ call step itself. Interface calls v1 also require the chosen implementation workflow to
752
+ declare exactly one public `outputs:` entry.
753
+
754
+ The host supplies one binding for every interface called directly by the workflow when
755
+ it invokes `Engine.createInstance`:
756
+
757
+ ```ts
758
+ engine.createInstance('parent', {
759
+ interfaceBindings: [{
760
+ interface: { name: 'report', version: '1.0.0' },
761
+ target: 'acme/report@2.3.1',
762
+ digest: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
763
+ signature: {
764
+ inputs: [{ name: 'source', schema: { type: 'object' } }],
765
+ outputs: [{ name: 'report', schema: { type: 'object' } }],
766
+ },
767
+ }],
768
+ });
769
+ ```
770
+
771
+ `target` must be an exact installed workflow coordinate and `digest` must be that
772
+ bundle's canonical lowercase SHA-256 digest. The target must carry a matching valid
773
+ `x.implements` claim, its declared input and output schemas must be structurally
774
+ compatible with the supplied signature, and every wired child input must exist in both
775
+ the signature and target. A missing, duplicate, malformed, stale, or incompatible
776
+ binding throws the named `InterfaceBindingRefusalError` before any workflow or artifact
777
+ row is inserted.
778
+
779
+ The root's normalized bindings are inherited unchanged by every child. At spawn time
780
+ the engine resolves the implementation by its exact digest again and transactionally
781
+ compares it with the persisted target and digest. A missing or repointed implementation
782
+ becomes visible structural debt on the parent call output; the engine does not fall
783
+ back, reselect, or rebind. Updates to installed implementations therefore affect only
784
+ new instances whose host selects them. Selection, ranking, and receipt authorship belong
785
+ to the host; the engine accepts, validates, persists, and enforces the resulting pin.
786
+
582
787
  ## `effect:` — re-running steps with side effects
583
788
 
584
789
  By default a step is **idempotent** — safe to re-run if its inputs move, which is what
package/docs/bundles.md CHANGED
@@ -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,