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/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
|
-
|
|
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.
|
|
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
|
|
430
|
-
|
|
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
|
-
|
|
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] #
|
|
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
|
|
516
|
-
`calls:` output
|
|
517
|
-
|
|
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
|
|
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.
|
|
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
|