owenloop 0.4.1 → 0.5.1
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 +71 -0
- package/README.md +182 -53
- package/bin/owenloop.mjs +50 -2
- package/dist/packages/work/src/agent/brief.d.ts +176 -0
- package/dist/packages/work/src/agent/brief.js +197 -0
- package/dist/packages/work/src/agent/loop.d.ts +141 -0
- package/dist/packages/work/src/agent/loop.js +669 -0
- package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
- package/dist/packages/work/src/agent/model-policy.js +138 -0
- package/dist/packages/work/src/agent/workdir.d.ts +210 -0
- package/dist/packages/work/src/agent/workdir.js +319 -0
- package/dist/packages/work/src/bundle/cache.d.ts +92 -0
- package/dist/packages/work/src/bundle/cache.js +338 -0
- package/dist/packages/work/src/bundle/fetch.d.ts +87 -0
- package/dist/packages/work/src/bundle/fetch.js +345 -0
- package/dist/packages/work/src/bundle/types.d.ts +164 -0
- package/dist/packages/work/src/bundle/types.js +1 -0
- package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
- package/dist/packages/work/src/consumed-verifier.js +205 -0
- package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
- package/dist/packages/work/src/credentials/owenloop.js +28 -0
- package/dist/packages/work/src/credentials/reader.d.ts +36 -0
- package/dist/packages/work/src/credentials/reader.js +32 -0
- package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
- package/dist/packages/work/src/credentials/resolve.js +56 -0
- package/dist/packages/work/src/exec/instructions.d.ts +99 -0
- package/dist/packages/work/src/exec/instructions.js +323 -0
- package/dist/packages/work/src/exec/loop.d.ts +40 -0
- package/dist/packages/work/src/exec/loop.js +332 -0
- package/dist/packages/work/src/exec/payload.d.ts +29 -0
- package/dist/packages/work/src/exec/payload.js +54 -0
- package/dist/packages/work/src/exec/receipt.d.ts +41 -0
- package/dist/packages/work/src/exec/receipt.js +32 -0
- package/dist/packages/work/src/exec/runner.d.ts +71 -0
- package/dist/packages/work/src/exec/runner.js +256 -0
- package/dist/packages/work/src/harness/child-env.d.ts +100 -0
- package/dist/packages/work/src/harness/child-env.js +134 -0
- package/dist/packages/work/src/harness/claude.d.ts +140 -0
- package/dist/packages/work/src/harness/claude.js +837 -0
- package/dist/packages/work/src/harness/codex.d.ts +111 -0
- package/dist/packages/work/src/harness/codex.js +1024 -0
- package/dist/packages/work/src/harness/contract.d.ts +308 -0
- package/dist/packages/work/src/harness/contract.js +32 -0
- package/dist/packages/work/src/harness/fake.d.ts +59 -0
- package/dist/packages/work/src/harness/fake.js +91 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.js +351 -0
- package/dist/packages/work/src/harness/permissions.d.ts +75 -0
- package/dist/packages/work/src/harness/permissions.js +182 -0
- package/dist/packages/work/src/harness/registry.d.ts +47 -0
- package/dist/packages/work/src/harness/registry.js +45 -0
- package/dist/packages/work/src/harness/session-store.d.ts +181 -0
- package/dist/packages/work/src/harness/session-store.js +523 -0
- package/dist/packages/work/src/harness/types.d.ts +29 -0
- package/dist/packages/work/src/harness/types.js +14 -0
- package/dist/packages/work/src/harnesses.d.ts +38 -0
- package/dist/packages/work/src/harnesses.js +38 -0
- package/dist/packages/work/src/hold/loop.d.ts +36 -0
- package/dist/packages/work/src/hold/loop.js +23 -0
- package/dist/packages/work/src/hold/mcp.d.ts +75 -0
- package/dist/packages/work/src/hold/mcp.js +264 -0
- package/dist/packages/work/src/hub/client.d.ts +23 -0
- package/dist/packages/work/src/hub/client.js +91 -0
- package/dist/packages/work/src/hub/types.d.ts +326 -0
- package/dist/packages/work/src/hub/types.js +26 -0
- package/dist/packages/work/src/lease/loop.d.ts +94 -0
- package/dist/packages/work/src/lease/loop.js +277 -0
- package/dist/packages/work/src/main.d.ts +1 -0
- package/dist/packages/work/src/main.js +48 -0
- package/dist/packages/work/src/mcp/server.d.ts +125 -0
- package/dist/packages/work/src/mcp/server.js +320 -0
- package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
- package/dist/packages/work/src/owenloop-bin.js +18 -0
- package/dist/packages/work/src/roles/agent-run.d.ts +124 -0
- package/dist/packages/work/src/roles/agent-run.js +529 -0
- package/dist/packages/work/src/roles/exec.d.ts +48 -0
- package/dist/packages/work/src/roles/exec.js +228 -0
- package/dist/packages/work/src/roles/hold.d.ts +72 -0
- package/dist/packages/work/src/roles/hold.js +363 -0
- package/dist/packages/work/src/roles/join.d.ts +18 -0
- package/dist/packages/work/src/roles/join.js +204 -0
- package/dist/packages/work/src/roles/lint.d.ts +58 -0
- package/dist/packages/work/src/roles/lint.js +234 -0
- package/dist/packages/work/src/roles/prepare.d.ts +1 -0
- package/dist/packages/work/src/roles/prepare.js +249 -0
- package/dist/packages/work/src/roles/release.d.ts +48 -0
- package/dist/packages/work/src/roles/release.js +137 -0
- package/dist/packages/work/src/roles/sessions.d.ts +61 -0
- package/dist/packages/work/src/roles/sessions.js +180 -0
- package/dist/packages/work/src/roles/settings.d.ts +6 -0
- package/dist/packages/work/src/roles/settings.js +71 -0
- package/dist/packages/work/src/roles/shift.d.ts +13 -0
- package/dist/packages/work/src/roles/shift.js +250 -0
- package/dist/packages/work/src/roles/signals.d.ts +55 -0
- package/dist/packages/work/src/roles/signals.js +62 -0
- package/dist/packages/work/src/settings/provision.d.ts +21 -0
- package/dist/packages/work/src/settings/provision.js +47 -0
- package/dist/packages/work/src/settings/settings.d.ts +136 -0
- package/dist/packages/work/src/settings/settings.js +155 -0
- package/dist/packages/work/src/shift/client.d.ts +24 -0
- package/dist/packages/work/src/shift/client.js +124 -0
- package/dist/packages/work/src/shift/loop.d.ts +131 -0
- package/dist/packages/work/src/shift/loop.js +751 -0
- package/dist/packages/work/src/shift/protocol.d.ts +95 -0
- package/dist/packages/work/src/shift/protocol.js +24 -0
- package/dist/packages/work/src/shift/routing.d.ts +35 -0
- package/dist/packages/work/src/shift/routing.js +50 -0
- package/dist/packages/work/src/shift/runtime.d.ts +45 -0
- package/dist/packages/work/src/shift/runtime.js +337 -0
- package/dist/packages/work/src/shift/server.d.ts +23 -0
- package/dist/packages/work/src/shift/server.js +716 -0
- package/dist/packages/work/src/shift/spawn.d.ts +109 -0
- package/dist/packages/work/src/shift/spawn.js +158 -0
- package/dist/packages/work/src/shift/state.d.ts +79 -0
- package/dist/packages/work/src/shift/state.js +385 -0
- package/dist/packages/work/src/submit-proof.d.ts +36 -0
- package/dist/packages/work/src/submit-proof.js +93 -0
- package/dist/packages/work/src/usage.d.ts +6 -0
- package/dist/packages/work/src/usage.js +175 -0
- package/dist/src/add.d.ts +189 -0
- package/dist/src/add.js +300 -0
- package/dist/src/archive.d.ts +97 -0
- package/dist/src/archive.js +591 -0
- package/dist/src/bundle/index.d.ts +64 -0
- package/dist/src/bundle/index.js +508 -0
- package/dist/src/bundle/manifest.d.ts +50 -0
- package/dist/src/bundle/manifest.js +435 -0
- package/dist/src/bundle/runtime.d.ts +26 -0
- package/dist/src/bundle/runtime.js +64 -0
- package/dist/src/bundle/tar.d.ts +62 -0
- package/dist/src/bundle/tar.js +238 -0
- package/dist/src/bundle/types.d.ts +105 -0
- package/dist/src/bundle/types.js +21 -0
- package/dist/{cli.d.ts → src/cli.d.ts} +92 -7
- package/dist/src/cli.js +5968 -0
- package/dist/{credentials.d.ts → src/credentials.d.ts} +22 -15
- package/dist/{credentials.js → src/credentials.js} +35 -31
- package/dist/src/crypto/allowed-signers.d.ts +68 -0
- package/dist/src/crypto/allowed-signers.js +307 -0
- package/dist/src/crypto/canonical.d.ts +8 -0
- package/dist/src/crypto/canonical.js +92 -0
- package/dist/src/crypto/chain.d.ts +65 -0
- package/dist/src/crypto/chain.js +377 -0
- package/dist/src/crypto/dsse.d.ts +209 -0
- package/dist/src/crypto/dsse.js +282 -0
- package/dist/src/crypto/enrollment.d.ts +78 -0
- package/dist/src/crypto/enrollment.js +186 -0
- package/dist/src/crypto/index.d.ts +48 -0
- package/dist/src/crypto/index.js +44 -0
- package/dist/src/crypto/keys.d.ts +258 -0
- package/dist/src/crypto/keys.js +908 -0
- package/dist/src/crypto/org-root.d.ts +33 -0
- package/dist/src/crypto/org-root.js +78 -0
- package/dist/src/crypto/origin-rules.d.ts +56 -0
- package/dist/src/crypto/origin-rules.js +143 -0
- package/dist/src/crypto/policy-floor.d.ts +98 -0
- package/dist/src/crypto/policy-floor.js +353 -0
- package/dist/src/crypto/records.d.ts +316 -0
- package/dist/src/crypto/records.js +157 -0
- package/dist/src/crypto/scope.d.ts +49 -0
- package/dist/src/crypto/scope.js +83 -0
- package/dist/src/crypto/ssh.d.ts +171 -0
- package/dist/src/crypto/ssh.js +396 -0
- package/dist/src/crypto/submission.d.ts +33 -0
- package/dist/src/crypto/submission.js +47 -0
- package/dist/src/crypto/trust-roots.d.ts +29 -0
- package/dist/src/crypto/trust-roots.js +39 -0
- package/dist/src/crypto/verify-consumed.d.ts +67 -0
- package/dist/src/crypto/verify-consumed.js +259 -0
- package/dist/src/crypto/verify-origin.d.ts +50 -0
- package/dist/src/crypto/verify-origin.js +151 -0
- package/dist/src/crypto/verify-publication.d.ts +60 -0
- package/dist/src/crypto/verify-publication.js +150 -0
- package/dist/{defs.d.ts → src/defs.d.ts} +24 -1
- package/dist/{defs.js → src/defs.js} +181 -61
- package/dist/{engine.d.ts → src/engine.d.ts} +105 -9
- package/dist/{engine.js → src/engine.js} +251 -47
- package/dist/{factory.d.ts → src/factory.d.ts} +16 -0
- package/dist/{factory.js → src/factory.js} +16 -4
- package/dist/src/global-config.d.ts +59 -0
- package/dist/src/global-config.js +84 -0
- package/dist/{hub.d.ts → src/hub.d.ts} +280 -31
- package/dist/{hub.js → src/hub.js} +493 -52
- package/dist/src/index.d.ts +47 -0
- package/dist/src/index.js +41 -0
- package/dist/src/install.d.ts +538 -0
- package/dist/src/install.js +1981 -0
- package/dist/src/lock.d.ts +38 -0
- package/dist/src/lock.js +325 -0
- package/dist/src/mcp/serve.d.ts +109 -0
- package/dist/{mcp → src/mcp}/serve.js +335 -75
- package/dist/{mcp → src/mcp}/server.d.ts +6 -9
- package/dist/{mcp → src/mcp}/server.js +18 -10
- package/dist/{model.d.ts → src/model.d.ts} +15 -0
- package/dist/{model.js → src/model.js} +112 -2
- package/dist/src/order-resolver.d.ts +184 -0
- package/dist/src/order-resolver.js +252 -0
- package/dist/src/package-version.d.ts +10 -0
- package/dist/src/package-version.js +42 -0
- package/dist/{paths.d.ts → src/paths.d.ts} +14 -1
- package/dist/{paths.js → src/paths.js} +18 -0
- package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
- package/dist/src/schemas/index.d.ts +1416 -0
- package/dist/src/schemas/index.js +31 -0
- package/dist/src/schemas/order.v1.schema.json +106 -0
- package/dist/src/schemas/origin.v1.schema.json +68 -0
- package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
- package/dist/src/schemas/publication.v1.schema.json +31 -0
- package/dist/src/schemas/revocation.v1.schema.json +39 -0
- package/dist/src/schemas/submission.v1.schema.json +61 -0
- package/dist/src/store/def-source.d.ts +52 -0
- package/dist/src/store/def-source.js +335 -0
- package/dist/src/store/index-file.d.ts +69 -0
- package/dist/src/store/index-file.js +151 -0
- package/dist/src/store/index.d.ts +27 -0
- package/dist/src/store/index.js +22 -0
- package/dist/src/store/ingestor.d.ts +43 -0
- package/dist/src/store/ingestor.js +211 -0
- package/dist/src/store/install.d.ts +228 -0
- package/dist/src/store/install.js +555 -0
- package/dist/src/store/instruction-source.d.ts +49 -0
- package/dist/src/store/instruction-source.js +298 -0
- package/dist/src/store/origin-evidence.d.ts +21 -0
- package/dist/src/store/origin-evidence.js +66 -0
- package/dist/src/store/pre-commit-verifier.d.ts +68 -0
- package/dist/src/store/pre-commit-verifier.js +418 -0
- package/dist/src/store/resolve.d.ts +138 -0
- package/dist/src/store/resolve.js +363 -0
- package/dist/src/store/types.d.ts +288 -0
- package/dist/src/store/types.js +356 -0
- package/dist/{types.d.ts → src/types.d.ts} +58 -24
- package/dist/{untar.d.ts → src/untar.d.ts} +8 -23
- package/dist/src/untar.js +38 -0
- package/dist/{util.d.ts → src/util.d.ts} +3 -2
- package/dist/{util.js → src/util.js} +3 -2
- package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
- package/dist/{owenwork.js → src/work-settings.js} +27 -27
- package/docs/agent-runner.md +86 -0
- package/docs/authoring.md +150 -59
- package/docs/bundles.md +250 -0
- package/docs/cli.md +1758 -163
- package/docs/crypto.md +816 -0
- package/docs/design.md +374 -52
- package/docs/embedding.md +135 -27
- package/docs/wire-contracts.md +380 -0
- package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
- package/examples/workflows/compile-dev-playbook.yaml +338 -0
- package/examples/workflows/judges/gate-sharpness.md +39 -0
- package/examples/workflows/judges/security.md +34 -0
- package/package.json +22 -8
- package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
- package/plugins/claude-code/plugin/.mcp.json +14 -0
- package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
- package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
- package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
- package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
- package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
- package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
- package/plugins/codex/.agents/plugins/marketplace.json +21 -0
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
- package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
- package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
- package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
- package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
- package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
- package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
- package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
- package/dist/add.d.ts +0 -384
- package/dist/add.js +0 -834
- package/dist/cli.js +0 -3270
- package/dist/index.d.ts +0 -32
- package/dist/index.js +0 -23
- package/dist/lock.d.ts +0 -80
- package/dist/lock.js +0 -217
- package/dist/mcp/serve.d.ts +0 -84
- package/dist/untar.js +0 -164
- /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
- /package/dist/{schema.js → src/schema.js} +0 -0
- /package/dist/{store.d.ts → src/store.d.ts} +0 -0
- /package/dist/{store.js → src/store.js} +0 -0
- /package/dist/{types.js → src/types.js} +0 -0
package/docs/embedding.md
CHANGED
|
@@ -6,8 +6,9 @@ on an `Engine` and prints the results as JSON. Everything it does, a host
|
|
|
6
6
|
process can do **in-process** — and get the lifecycle back as typed objects
|
|
7
7
|
rather than JSON on stdout.
|
|
8
8
|
|
|
9
|
-
This document covers the in-process API: the one-call factory, the worker step
|
|
10
|
-
|
|
9
|
+
This document covers the in-process API: the one-call factory, the worker step
|
|
10
|
+
(the loop a Step Agent — or your own host code — runs), in-memory definitions,
|
|
11
|
+
lifecycle/concurrency, and **push-style events** so a host
|
|
11
12
|
can react the instant the graph advances instead of polling.
|
|
12
13
|
|
|
13
14
|
## The one-call factory
|
|
@@ -15,13 +16,15 @@ can react the instant the graph advances instead of polling.
|
|
|
15
16
|
```ts
|
|
16
17
|
import { createEngine } from 'owenloop';
|
|
17
18
|
|
|
18
|
-
const { engine, store } = createEngine({
|
|
19
|
+
const { engine, store, resolver } = createEngine({
|
|
19
20
|
db: '.owenloop/state.db', // SQLite path; ':memory:' for ephemeral. Default: .owenloop/state.db
|
|
20
21
|
defsDir: 'workflows', // load *.yaml defs from a directory
|
|
21
22
|
});
|
|
22
23
|
```
|
|
23
24
|
|
|
24
|
-
`createEngine(opts)` returns `{ engine, store, defs }`
|
|
25
|
+
`createEngine(opts)` returns `{ engine, store, defs, resolver }` — `resolver`
|
|
26
|
+
is the order's instruction resolver (see [The worker step](#the-worker-step)),
|
|
27
|
+
the same one the engine uses internally — and accepts:
|
|
25
28
|
|
|
26
29
|
| option | meaning |
|
|
27
30
|
|-------------|---------|
|
|
@@ -31,6 +34,7 @@ const { engine, store } = createEngine({
|
|
|
31
34
|
| `reapTtlMs` | Forwarded to the `Engine` — the stranded-lease reap TTL. |
|
|
32
35
|
| `maxLeaseMs` | Forwarded to the `Engine` — an opt-in hard cap on total lease lifetime (per-step `maxLease:` overrides). Unset (default): no cap; heartbeats extend a lease indefinitely. Set it only as a runaway backstop — it can reap a healthy, still-beating job. |
|
|
33
36
|
| `maxCallDepth` | Forwarded to the `Engine` — the hard cap on `calls:` composition depth (root instance = depth 0). Defaults to 64. Defense in depth against a `calls:` cycle; only relevant when you hand-wire a custom `DefResolver` that construction-time validation can't inspect. |
|
|
37
|
+
| `instructionSource` | The order-instruction source (`OrderInstructionSource`: `digestOf` + typed `lookup`). Each resolved record includes the exact static instruction bytes and the step's `maxAttempts` materialization metadata. Default: an adapter over the definitions this engine loads — the same reference-mode behavior the CLI gets. For a store-backed consumer, use `createStoreInstructionSource` and call its asynchronous `prime(defDigest)` before the synchronous resolver lookup; the source verifies and caches a local object before serving its bytes (see [Resolving instructions](#resolving-instructions)). The store source is a consumer-side resolver; the engine's default emitter remains the loaded-definition adapter. |
|
|
34
38
|
| `onEvent` | A push-style observer registered at construction (equivalent to `engine.subscribe`). See [Events](#events). |
|
|
35
39
|
| `onListenerError` | Where a throwing listener's error is routed (default: swallowed). |
|
|
36
40
|
|
|
@@ -41,15 +45,17 @@ Prefer to wire it yourself? The pieces are all exported — `createEngine` is ju
|
|
|
41
45
|
sugar over them:
|
|
42
46
|
|
|
43
47
|
```ts
|
|
44
|
-
import { Engine, openStore, loadDefs } from 'owenloop';
|
|
48
|
+
import { Engine, openStore, loadDefs, createDefInstructionSource } from 'owenloop';
|
|
45
49
|
|
|
46
50
|
const store = openStore('.owenloop/state.db');
|
|
47
51
|
const defs = loadDefs('workflows');
|
|
52
|
+
const instructionSource = createDefInstructionSource(defs.values());
|
|
48
53
|
const engine = new Engine(store, (name) => {
|
|
49
54
|
const d = defs.get(name);
|
|
50
55
|
if (!d) throw new Error(`unknown workflow definition '${name}'`);
|
|
51
56
|
return d;
|
|
52
|
-
});
|
|
57
|
+
}, { instructionSource });
|
|
58
|
+
const { resolver } = engine;
|
|
53
59
|
```
|
|
54
60
|
|
|
55
61
|
`loadDefs` already validates what it reads from disk. If you build a def set by
|
|
@@ -69,24 +75,88 @@ const wf = engine.createInstance('delivery', {
|
|
|
69
75
|
|
|
70
76
|
const { orders } = engine.tick(wf);
|
|
71
77
|
for (const order of orders) {
|
|
72
|
-
const
|
|
73
|
-
const
|
|
78
|
+
const instructions = resolver.resolveOrder(order); // { prompt?, command? }
|
|
79
|
+
const result = await runYourWorker(order, instructions); // ← your domain
|
|
80
|
+
const commit = engine.green(order.workflow, order.run, order.outputs[0], result);
|
|
74
81
|
if (commit.outcome !== 'green') {
|
|
75
82
|
// born-rejected (an input moved) or schema-rejected (§18) — inspect commit.reason
|
|
76
83
|
}
|
|
77
|
-
engine.close(
|
|
84
|
+
engine.close(order.workflow, order.run);
|
|
78
85
|
}
|
|
79
86
|
|
|
80
87
|
const status = engine.status(wf); // { done, debts, eligible, blocked, inFlight }
|
|
81
88
|
```
|
|
82
89
|
|
|
83
|
-
Each `order` is
|
|
84
|
-
deep tick below), `
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
+
Each `order` is a **reference packet**: `workflow` (the instance it belongs
|
|
91
|
+
to — see deep tick below), `defDigest` (identifies the definition snapshot to
|
|
92
|
+
resolve instructions from), `consumes` (the captured green inputs), `owes`
|
|
93
|
+
(the owed outputs + their accumulated reason threads), plus
|
|
94
|
+
`inputs`/`outputs`/`workdir`/`model`/`worker`/`spec`/`x`/`cause`. `workdir` may
|
|
95
|
+
be authored as a literal `workdir:` or resolved from a consumed artifact by a
|
|
96
|
+
step's `workdirFrom:`; the order field and wire shape are the same either way.
|
|
97
|
+
If the consumed value cannot resolve to a non-empty string, `engine.tick()`
|
|
98
|
+
returns a `workdir-unresolved` deferral and emits no order. It carries
|
|
99
|
+
no authored prompt or command text — those resolve through `resolver` by
|
|
100
|
+
digest (next section). A consumer rejecting an upstream artifact is just
|
|
101
|
+
`engine.reject(wf, path, by, text)`; the forward cascade and stall liveness
|
|
102
|
+
behave exactly as they do under the CLI, because it's the same engine.
|
|
103
|
+
|
|
104
|
+
### Resolving instructions
|
|
105
|
+
|
|
106
|
+
Orders are resolved before dispatch through the `(defDigest, step, key)`
|
|
107
|
+
boundary — `resolver.resolveOrder(order)` (or `resolver.resolve(ref)` for a
|
|
108
|
+
bare reference). The resolver is backed by an `OrderInstructionSource`, and
|
|
109
|
+
the same path serves every caller: the CLI, this embedded engine, and orders
|
|
110
|
+
relayed from a remote coordinator or transport all resolve through one
|
|
111
|
+
boundary, against whatever source the deployer trusts. The shipped default is
|
|
112
|
+
the loaded-definition adapter (seeded with the defs this engine runs).
|
|
113
|
+
|
|
114
|
+
A host that distributes definitions from the content-addressed store can use
|
|
115
|
+
`createStoreInstructionSource({ projectRoot, globalRoot, verifier })`. The store
|
|
116
|
+
source performs filesystem verification asynchronously, so the host must prime
|
|
117
|
+
the order's digest before the resolver's synchronous lookup:
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
import {
|
|
121
|
+
createBundleIngestor,
|
|
122
|
+
createStoreInstructionSource,
|
|
123
|
+
OrderResolver,
|
|
124
|
+
} from 'owenloop';
|
|
125
|
+
|
|
126
|
+
const source = createStoreInstructionSource({
|
|
127
|
+
projectRoot: 'workflows',
|
|
128
|
+
globalRoot: '/path/to/.owenloop/workflows',
|
|
129
|
+
verifier: createBundleIngestor(),
|
|
130
|
+
});
|
|
131
|
+
const resolver = new OrderResolver(source);
|
|
132
|
+
|
|
133
|
+
await source.prime(order.defDigest); // verify and cache the local object
|
|
134
|
+
const instructions = resolver.resolveOrder(order); // synchronous cache lookup
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
`prime` returns `resolved` or `unknown-digest`; an integrity failure is a
|
|
138
|
+
separate refusal. The source enumerates indexed bundle objects, verifies each
|
|
139
|
+
candidate on read, loads every workflow path listed by its `bundle.yaml`, and
|
|
140
|
+
matches each finalized definition's instruction projection digest to
|
|
141
|
+
`order.defDigest`. The order's digest is the
|
|
142
|
+
only instruction key supplied by the transport; the source never accepts
|
|
143
|
+
prompt or command text from the packet. `createEngine` keeps its default
|
|
144
|
+
loaded-definition emitter, because the store source's `digestOf` is deliberately
|
|
145
|
+
unable to emit a digest for an uninstalled definition.
|
|
146
|
+
|
|
147
|
+
Resolution returns `{ prompt?, command?, acceptance? }` — the exact authored
|
|
148
|
+
values, byte-for-byte (the loaded-definition adapter preserves an authored
|
|
149
|
+
empty body as `prompt: ''`; a source may omit prompt when no prompt exists), with
|
|
150
|
+
the runtime placeholders
|
|
151
|
+
(`${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MAX_ATTEMPTS}`)
|
|
152
|
+
materialized into the prompt. An unknown digest — the definition was never
|
|
153
|
+
delivered, or the bytes don't match what emitted the order — raises the named
|
|
154
|
+
refusal `UnknownDefDigestError` (it carries `defDigest`, and its message names
|
|
155
|
+
it). A known digest with an unknown `step` raises the distinct
|
|
156
|
+
`UnknownInstructionError` (it carries `defDigest`, `step`, and `key`). Treat
|
|
157
|
+
either refusal as refuse-the-job: there is no fallback to name-based
|
|
158
|
+
resolution and no degraded mode. See [`docs/design.md` §29](design.md) and
|
|
159
|
+
[§30](design.md) for the full contract.
|
|
90
160
|
|
|
91
161
|
`engine.tick(wf)` is **deep by default**: after ticking `wf` it descends into
|
|
92
162
|
every live `calls:` child (recursively), folding their orders, `reaped`, folded
|
|
@@ -110,28 +180,33 @@ one `TickResult` belongs to the instance you ticked; each order carries its own
|
|
|
110
180
|
(CLI `--shallow`) stays the deliberate single-instance escape hatch when you
|
|
111
181
|
want exactly the old behavior.
|
|
112
182
|
|
|
113
|
-
`order.worker` is where dispatch-by-
|
|
183
|
+
`order.worker` is where dispatch-by-worker-type earns its keep in an
|
|
114
184
|
embedder: rather than every order going to the same LLM-driving `runYourWorker`,
|
|
115
185
|
branch on it before deciding how to run the order.
|
|
116
186
|
|
|
117
187
|
```ts
|
|
118
188
|
for (const order of orders) {
|
|
189
|
+
const instructions = resolver.resolveOrder(order);
|
|
119
190
|
const result =
|
|
120
191
|
order.worker === 'command'
|
|
121
|
-
? await runCommand(
|
|
122
|
-
: await runYourAgent(order);
|
|
192
|
+
? await runCommand(instructions.command!, order.spec) // resolved command text is opaque to owenloop — never shelled out by the engine itself
|
|
193
|
+
: await runYourAgent(order, instructions.prompt); // default / worker: 'agent' / anything else you handle the same way
|
|
123
194
|
|
|
124
|
-
const commit = engine.green(
|
|
125
|
-
engine.close(
|
|
195
|
+
const commit = engine.green(order.workflow, order.run, order.outputs[0], result);
|
|
196
|
+
engine.close(order.workflow, order.run);
|
|
126
197
|
}
|
|
127
198
|
```
|
|
128
199
|
|
|
129
|
-
`worker`/`
|
|
130
|
-
shape-
|
|
131
|
-
never reads their contents itself.
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
200
|
+
`worker`/`spec` are optional and opaque on the order; the authored
|
|
201
|
+
`executor:`/`command:`/`spec:` are shape-checked at load time (`command` a
|
|
202
|
+
string, `spec` a plain map) and the engine never reads their contents itself.
|
|
203
|
+
`order.worker` maps verbatim from the authored step's `executor:` and is
|
|
204
|
+
`undefined` when the step never set it (today's default, unaffected by this
|
|
205
|
+
feature); the authored `command:` text is not on the order — it arrives via
|
|
206
|
+
`resolver.resolveOrder(order).command`. See
|
|
207
|
+
[`docs/design.md` §27.4](design.md) for the authored contract,
|
|
208
|
+
[§29](design.md) for the reference-mode order, and
|
|
209
|
+
[`docs/authoring.md`](authoring.md#executor--declaring-the-executor) for how to
|
|
135
210
|
declare it on a step.
|
|
136
211
|
|
|
137
212
|
A runnable version of this lives at [`examples/embed.ts`](../examples/embed.ts):
|
|
@@ -320,6 +395,39 @@ means "no credential", but an exception means "the configured command could not
|
|
|
320
395
|
produce one" — surface its message rather than treating it as an empty slot,
|
|
321
396
|
because falling back to a local store is exactly what the setting forbids.
|
|
322
397
|
|
|
398
|
+
The index also exports the **crypto surface** ([Signing and key
|
|
399
|
+
storage](crypto.md) is the full reference):
|
|
400
|
+
|
|
401
|
+
- `PrincipalKeyManager` — generate/store/materialize the three principals'
|
|
402
|
+
Ed25519 signing keys (`ensure`, `inspect`, `withSigningKey`; refs are
|
|
403
|
+
`{ origin, kind, id }`, helpers `assertKeyRef`, `canonicalKeyRef`,
|
|
404
|
+
`keyRefHash`, `keyidFromBlob`, `publicKeyDescriptor`). The internal record
|
|
405
|
+
reader is private to `PrincipalKeyManager`; consumers receive **paths and
|
|
406
|
+
public descriptors, never private-key strings**. `ensure`/`inspect` return
|
|
407
|
+
only the public-key descriptor, and `withSigningKey` hands your callback a
|
|
408
|
+
temporary usable key path that the manager removes after use (or the
|
|
409
|
+
canonical path of an explicitly reused key).
|
|
410
|
+
- `SshSigner` / `createSshSigner` (behind the format-neutral `Signer`
|
|
411
|
+
interface) — SSHSIG signing/verification through stock `ssh-keygen -Y`.
|
|
412
|
+
- `dsseSignEnvelope` / `dsseVerifyEnvelope` plus the record-class wrappers and
|
|
413
|
+
the six `PAYLOAD_TYPE_*` constants — DSSE envelopes with strict Base64 and
|
|
414
|
+
exact-byte payload return.
|
|
415
|
+
- `canonicalValueBytes` / `valueDigestHex` — deterministic JSON value bytes and
|
|
416
|
+
lowercase SHA-256 value digests for submission records. The canonicalizer
|
|
417
|
+
rejects values that JSON transport cannot represent faithfully.
|
|
418
|
+
- `buildSubmissionRecord` / `signSubmission` — build the frozen `submission.v1`
|
|
419
|
+
record and return its serialized DSSE proof for a submitted artifact.
|
|
420
|
+
- `parseAllowedSigners` — structural parsing of stock `allowed_signers` files
|
|
421
|
+
(never throws; malformed lines come back with line numbers).
|
|
422
|
+
- `DEFAULT_MACHINE_SCOPE` and `buildEnrollmentGrant` — construct an immutable
|
|
423
|
+
machine enrollment grant from a public key descriptor without reading private
|
|
424
|
+
key material or performing I/O.
|
|
425
|
+
- `verifyRosterEntry` — classify one relayed enrollment envelope locally as
|
|
426
|
+
`enrolled`, `unenrolled`, `unverifiable`, or `invalid`. Pass an
|
|
427
|
+
`EnrollmentChainValidator` through `VerifyRosterEntryOptions` when the host
|
|
428
|
+
can prove that the grantor chains to the organization root; without that
|
|
429
|
+
validator, verification deliberately remains `unverifiable`.
|
|
430
|
+
|
|
323
431
|
`SUPPORTED_ENGINE_VERSION` is the programmatic form of the design.md §27
|
|
324
432
|
engine-version contract — the highest `engine:` a def may declare and still load.
|
|
325
433
|
Tooling can preflight-check a def's `engine:` field against it before handing the
|
|
@@ -0,0 +1,380 @@
|
|
|
1
|
+
# Wire contracts
|
|
2
|
+
|
|
3
|
+
This document describes the versioned records that cross an owenloop trust
|
|
4
|
+
boundary. The checked-in TypeScript definitions in `src/crypto/records.ts` and
|
|
5
|
+
the JSON Schemas in `src/schemas/` describe the same fields. The test suite
|
|
6
|
+
checks both directions: a field added to one side without the other fails the
|
|
7
|
+
build.
|
|
8
|
+
|
|
9
|
+
This package defines shapes only. Signing, verification, enrollment, revocation
|
|
10
|
+
processing, scope attenuation, origin recording, and policy evaluation are
|
|
11
|
+
separate responsibilities.
|
|
12
|
+
|
|
13
|
+
## DSSE envelope
|
|
14
|
+
|
|
15
|
+
The records use a DSSEv1 envelope with this shape:
|
|
16
|
+
|
|
17
|
+
```json
|
|
18
|
+
{
|
|
19
|
+
"payloadType": "application/vnd.owenloop.submission.v1+json",
|
|
20
|
+
"payload": "<base64 payload bytes>",
|
|
21
|
+
"signatures": [{ "keyid": "<optional hint>", "sig": "<base64 signature>" }]
|
|
22
|
+
}
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
`payloadType` is part of the signed data. The type is bound to the record class,
|
|
26
|
+
so a valid signature for one class cannot be consumed as another class.
|
|
27
|
+
`payload` and `sig` are standard Base64 when produced. Verification accepts the
|
|
28
|
+
standard and URL-safe alphabets but rejects malformed encodings.
|
|
29
|
+
|
|
30
|
+
The DSSE pre-authentication encoding is:
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
DSSEv1 SP len(typeBytes) SP typeBytes SP len(payloadBytes) SP payloadBytes
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Both lengths are ASCII decimal **byte counts**. `typeBytes` is the UTF-8 byte
|
|
37
|
+
sequence for `payloadType`; the payload length is the exact number of payload
|
|
38
|
+
bytes. The length is not the number of characters in a string. This distinction
|
|
39
|
+
matters for non-ASCII payload types or payload data.
|
|
40
|
+
|
|
41
|
+
## Versioned payload types
|
|
42
|
+
|
|
43
|
+
The six bound records defined here use the existing media types:
|
|
44
|
+
|
|
45
|
+
| Record | Payload type |
|
|
46
|
+
| --- | --- |
|
|
47
|
+
| Enrollment grant | `application/vnd.owenloop.enrollment-grant.v1+json` |
|
|
48
|
+
| Revocation | `application/vnd.owenloop.revocation.v1+json` |
|
|
49
|
+
| Submission | `application/vnd.owenloop.submission.v1+json` |
|
|
50
|
+
| Policy floor | `application/vnd.owenloop.policy-floor.v1+json` |
|
|
51
|
+
| Origin | `application/vnd.owenloop.origin.v1+json` |
|
|
52
|
+
| Publication | `application/vnd.owenloop.publication.v1+json` |
|
|
53
|
+
|
|
54
|
+
Origin is a bound record class, not a label. Its source fields are signed
|
|
55
|
+
content in a separate DSSE envelope, and the hub or another relay cannot write,
|
|
56
|
+
derive, or default them.
|
|
57
|
+
|
|
58
|
+
A contract change that removes a field, makes an optional field required, or
|
|
59
|
+
narrows an accepted value is breaking. Such a change requires a new payload
|
|
60
|
+
type at `.v2`; do not edit the meaning of `.v1`. Adding an optional field whose
|
|
61
|
+
absence preserves the old meaning is compatible and may update `.v1`, but the
|
|
62
|
+
TypeScript type, field manifest, schema, fixtures, and documentation must move
|
|
63
|
+
together in one commit.
|
|
64
|
+
|
|
65
|
+
## Submission record
|
|
66
|
+
|
|
67
|
+
Payload type: `application/vnd.owenloop.submission.v1+json`.
|
|
68
|
+
|
|
69
|
+
| Field | Required | Meaning |
|
|
70
|
+
| --- | --- | --- |
|
|
71
|
+
| `run` | yes | Workflow run identifier. |
|
|
72
|
+
| `workflow` | yes | Workflow instance identifier. |
|
|
73
|
+
| `defDigest` | yes | Non-empty opaque reference to the instruction snapshot. The resolver seam does not require a fixed digest alphabet. |
|
|
74
|
+
| `step` | yes | Producing step name. |
|
|
75
|
+
| `key` | yes | Binding key, including the empty key used by non-map firings. |
|
|
76
|
+
| `index` | no | Map/index position when the firing has one. |
|
|
77
|
+
| `produced` | yes | One or more produced values. |
|
|
78
|
+
| `consumedFingerprint` | yes | Open artifact-path map to the non-negative input version consumed at claim time. |
|
|
79
|
+
| `producerKeyId` | yes | `SHA256:<unpadded-base64>` fingerprint of the producer key. |
|
|
80
|
+
| `timestamp` | yes | Epoch milliseconds. |
|
|
81
|
+
|
|
82
|
+
Each `produced` entry has `artifact`, non-negative integer `version`, and a
|
|
83
|
+
lowercase SHA-256 `valueDigest`.
|
|
84
|
+
|
|
85
|
+
A driver signs only when the driver can name the exact artifact version without
|
|
86
|
+
inferring mutable coordinator state. A judge approval can use the judged path's
|
|
87
|
+
claim-time `consumedFingerprint` entry because the approval attests that existing
|
|
88
|
+
version and does not allocate a new version. A producer submit requires an exact
|
|
89
|
+
target version issued by a retry-safe hub protocol. Immutable `owes[].version`
|
|
90
|
+
metadata is not sufficient: the metadata becomes stale after a refinement, a
|
|
91
|
+
committed submit whose response is lost, an unsigned commit, or a client process
|
|
92
|
+
restart. Without explicit producer-version authority, built-in clients submit
|
|
93
|
+
the producer value without a proof rather than sign a process-local guess.
|
|
94
|
+
|
|
95
|
+
A consuming driver verifies the envelope before trusting the value. The
|
|
96
|
+
verified signer key must equal `producerKeyId`; the signed `produced[]` entry
|
|
97
|
+
must cover the requested artifact path; and the signed `valueDigest` and
|
|
98
|
+
`version` must match the delivered value and the consumer's claim-time version
|
|
99
|
+
when supplied. The driver then validates the producer's local enrollment chain,
|
|
100
|
+
revocations, and any supplied demand's scope. These checks belong to the
|
|
101
|
+
consuming driver, not the hub or another transport relay.
|
|
102
|
+
|
|
103
|
+
The built-in production `exec`, `agent-run`, and `hold` roles currently supply
|
|
104
|
+
no pool, label, or namespace demand, and `OrderPacket` has no demand field from
|
|
105
|
+
which to derive one. Production consume gates therefore enforce chain
|
|
106
|
+
termination, per-link signatures, attenuation, and revocation, but the
|
|
107
|
+
demand-dependent `scopePermits` restriction is currently vacuous. A verifier
|
|
108
|
+
caller that supplies a demand receives the full scope check. This is a named
|
|
109
|
+
follow-up, not hub-side trust.
|
|
110
|
+
|
|
111
|
+
### Deployed hub compatibility
|
|
112
|
+
|
|
113
|
+
The schema above is the target wire contract, not evidence that every deployed
|
|
114
|
+
hub carries every optional field. As of 2026-08-10, the production hub drops
|
|
115
|
+
`consumedFingerprint`, `owes[].version`, `owes[].proof`, and `consumesProof` from
|
|
116
|
+
served orders. The production REST and MCP submit paths also do not carry a
|
|
117
|
+
client-supplied `proof` through hub-core. A current client therefore cannot claim
|
|
118
|
+
that a submit proof was accepted, persisted beside a committed artifact version,
|
|
119
|
+
or relayed to a downstream consumer.
|
|
120
|
+
|
|
121
|
+
Client transport types keep these fields optional so one client remains
|
|
122
|
+
compatible with both the deployed hub and a future version-aware hub. End-to-end
|
|
123
|
+
proof support requires service changes: preserve all four order fields, accept
|
|
124
|
+
and persist submit proofs, return proof-acceptance and committed-version data,
|
|
125
|
+
and provide retry idempotency (running the same submission again changes
|
|
126
|
+
nothing) that survives a lost response and client restart.
|
|
127
|
+
|
|
128
|
+
## Publication record
|
|
129
|
+
|
|
130
|
+
Payload type: `application/vnd.owenloop.publication.v1+json`.
|
|
131
|
+
|
|
132
|
+
A publication record binds one signed statement to one canonical workflow
|
|
133
|
+
bundle. The `digest` is the lowercase 64-hex SHA-256 digest of the exact
|
|
134
|
+
uncompressed canonical tar inside the `.wnlp` bundle. The record is serialized
|
|
135
|
+
with the package's canonical JSON rules before DSSE signing; the signature does
|
|
136
|
+
not cover a gzip wrapper hash or a compiled-definition hash.
|
|
137
|
+
|
|
138
|
+
| Field | Required | Meaning |
|
|
139
|
+
| --- | --- | --- |
|
|
140
|
+
| `digest` | yes | Canonical bundle digest: lowercase 64-hex SHA-256 over the uncompressed canonical tar. |
|
|
141
|
+
| `name` | yes | Package name from the bundle manifest. |
|
|
142
|
+
| `version` | yes | Package version from the bundle manifest. |
|
|
143
|
+
| `publisherKeyId` | yes | Publisher public-key fingerprint in `SHA256:<unpadded-base64>` form. |
|
|
144
|
+
| `timestamp` | yes | Unix epoch milliseconds when the author created the publication record. |
|
|
145
|
+
|
|
146
|
+
The v1 publication object is closed: unknown properties are rejected. The
|
|
147
|
+
publication payload type is bound to this record by the runtime DSSE allow-list,
|
|
148
|
+
field manifest, and JSON Schema together.
|
|
149
|
+
|
|
150
|
+
## Origin record
|
|
151
|
+
|
|
152
|
+
Payload type: `application/vnd.owenloop.origin.v1+json`.
|
|
153
|
+
|
|
154
|
+
An origin record is a signed provenance statement for one canonical workflow
|
|
155
|
+
bundle. Its `digest` is the lowercase 64-hex SHA-256 digest of the exact
|
|
156
|
+
uncompressed canonical tar inside the `.wnlp` bundle. The origin and publication
|
|
157
|
+
records use the same digest and are signed inside the same signing scope with the
|
|
158
|
+
same signer, but each record has its own DSSE envelope and sidecar.
|
|
159
|
+
|
|
160
|
+
| Field | Required | Meaning |
|
|
161
|
+
| --- | --- | --- |
|
|
162
|
+
| `digest` | yes | Canonical bundle digest: lowercase 64-hex SHA-256 over the uncompressed canonical tar. |
|
|
163
|
+
| `name` | yes | Package name from the bundle manifest. |
|
|
164
|
+
| `version` | yes | Package version from the bundle manifest. |
|
|
165
|
+
| `source` | yes | Signed provenance union; one of the `git`, `console`, or `agent` forms below. |
|
|
166
|
+
| `attesterKeyId` | yes | Untrusted candidate-selection hint for the signing key; verification cross-checks it against the verified signer. |
|
|
167
|
+
| `timestamp` | yes | Unix epoch milliseconds when the author created the origin record. |
|
|
168
|
+
|
|
169
|
+
`source` is a closed discriminated union:
|
|
170
|
+
|
|
171
|
+
- `{ "kind": "git", "repo": "...", "commit": "..." }` records the
|
|
172
|
+
explicitly supplied repository identifier and a 40- or 64-hex commit SHA.
|
|
173
|
+
- `{ "kind": "console", "user": "..." }` records the authoring user
|
|
174
|
+
identity from a client-side signing ceremony.
|
|
175
|
+
- `{ "kind": "agent", "agent": "...", "session": "..." }` records the
|
|
176
|
+
agent identity and session.
|
|
177
|
+
|
|
178
|
+
The source value is not derived by the hub. A caller supplies source data (for
|
|
179
|
+
example through `owenloop publish --source '<json>'`), and the signer signs the
|
|
180
|
+
resulting origin record. A remote coordinator stores or relays the signed record
|
|
181
|
+
but never authors, stamps, or completes the origin.
|
|
182
|
+
|
|
183
|
+
## Enrollment grant
|
|
184
|
+
|
|
185
|
+
Payload type: `application/vnd.owenloop.enrollment-grant.v1+json`.
|
|
186
|
+
|
|
187
|
+
| Field | Required | Meaning |
|
|
188
|
+
| --- | --- | --- |
|
|
189
|
+
| `newKey` | yes | Public descriptor for the key being granted: `keyid`, `keyType`, `openSshPublicKey`, and optional `comment`. |
|
|
190
|
+
| `principal` | yes | `{ kind, id }`, where `kind` is `human`, `machine`, or `agent`. |
|
|
191
|
+
| `scope` | yes | Complete claim, production, publication, and delegation scope. |
|
|
192
|
+
| `grantedBy` | yes | Grantor key fingerprint in `SHA256:<unpadded-base64>` form. |
|
|
193
|
+
| `validFrom` | yes | Epoch milliseconds at which the grant becomes valid. |
|
|
194
|
+
|
|
195
|
+
`scope.pools`, `scope.labels`, and `scope.namespaces` are each either an array
|
|
196
|
+
of strings or the literal `"*"`. The empty array means no values; `"*"` means
|
|
197
|
+
every value. Each axis is required so a reader never has to guess a default.
|
|
198
|
+
|
|
199
|
+
`scope.delegation` is a discriminated union:
|
|
200
|
+
|
|
201
|
+
```json
|
|
202
|
+
{ "allowed": false }
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
or:
|
|
206
|
+
|
|
207
|
+
```json
|
|
208
|
+
{ "allowed": true, "maxDepth": 2 }
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
`maxDepth` is a non-negative integer or `"unbounded"`. A non-delegating grant
|
|
212
|
+
has no `maxDepth` field.
|
|
213
|
+
|
|
214
|
+
The wire record does not identify an organization or mark an org root. Chain
|
|
215
|
+
validation receives the org-root public key as a local trust anchor; the root
|
|
216
|
+
has no grant record. See [Enrollment chains, attenuation, and revocation](crypto.md#enrollment-chains-attenuation-and-revocation)
|
|
217
|
+
for chain termination, per-link signature verification, and scope attenuation.
|
|
218
|
+
|
|
219
|
+
## Revocation
|
|
220
|
+
|
|
221
|
+
Payload type: `application/vnd.owenloop.revocation.v1+json`.
|
|
222
|
+
|
|
223
|
+
| Field | Required | Meaning |
|
|
224
|
+
| --- | --- | --- |
|
|
225
|
+
| `revokedKey` | yes | Key fingerprint being revoked. |
|
|
226
|
+
| `principal` | yes | `{ kind, id }` for the principal that owns the key. |
|
|
227
|
+
| `revokedBy` | yes | Signer key fingerprint. |
|
|
228
|
+
| `issuedAt` | yes | Epoch milliseconds when the record was issued. |
|
|
229
|
+
| `effectiveFrom` | yes | Epoch milliseconds at which the revocation cut applies. |
|
|
230
|
+
| `backdated` | yes | Explicit marker for a cut earlier than issuance. |
|
|
231
|
+
| `reason` | no | Human-readable explanation. |
|
|
232
|
+
|
|
233
|
+
A normal forward cut uses `effectiveFrom === issuedAt` and
|
|
234
|
+
`backdated: false`. Verification must cross-check the boolean against the two
|
|
235
|
+
timestamps. JSON Schema checks each field's individual shape, while the
|
|
236
|
+
cross-field consistency rule is verification-time logic. A backdated cut is
|
|
237
|
+
structurally visible so the verifier can apply the stronger signer rule without
|
|
238
|
+
inferring intent from clock arithmetic alone.
|
|
239
|
+
|
|
240
|
+
Revocation cuts apply forward. An artifact that was valid before the cut is not
|
|
241
|
+
retroactively changed solely because a later revocation record exists. The
|
|
242
|
+
validator also checks timestamp consistency, signer authority, and the
|
|
243
|
+
org-root-only rule for backdated cuts. See [Enrollment chains, attenuation, and revocation](crypto.md#enrollment-chains-attenuation-and-revocation)
|
|
244
|
+
for those verification rules.
|
|
245
|
+
|
|
246
|
+
## Policy floor
|
|
247
|
+
|
|
248
|
+
Payload type: `application/vnd.owenloop.policy-floor.v1+json`.
|
|
249
|
+
|
|
250
|
+
| Field | Required | Meaning |
|
|
251
|
+
| --- | --- | --- |
|
|
252
|
+
| `org` | yes | Organization identifier. |
|
|
253
|
+
| `issuedAt` | yes | Epoch milliseconds when the floor was issued. |
|
|
254
|
+
| `signedBy` | yes | Admin key fingerprint. |
|
|
255
|
+
| `floor` | yes | Normative minimum settings. |
|
|
256
|
+
| `preset` | no | Optional `L0`, `L1`, or `L2` label. |
|
|
257
|
+
|
|
258
|
+
`floor` always carries the four normative axes. `trustMode` is a frozen wire
|
|
259
|
+
value; this package carries the value but does not evaluate trust-mode behavior.
|
|
260
|
+
The exact accepted literals are pinned in
|
|
261
|
+
`src/schemas/policy-floor.v1.schema.json`. The other three axes use these
|
|
262
|
+
literals:
|
|
263
|
+
|
|
264
|
+
- `unsignedDefs`: `warn` or `refuse`;
|
|
265
|
+
- `unsignedArtifacts`: `warn` or `refuse`;
|
|
266
|
+
- `originRules`: `advisory` or `enforced`.
|
|
267
|
+
|
|
268
|
+
A floor is a minimum. A driver may require a stricter local policy, and a
|
|
269
|
+
relaying transport cannot use this record to weaken that local policy. The
|
|
270
|
+
transport relays the record; the transport is not the signer. `preset` is only
|
|
271
|
+
a label for a set of floor values, never a replacement for those values, so a
|
|
272
|
+
future preset can change without changing the required wire fields.
|
|
273
|
+
|
|
274
|
+
## Reference-mode Order
|
|
275
|
+
|
|
276
|
+
`Order` is the sixth launch contract. The existing `Order` interface in
|
|
277
|
+
`src/types.ts` is authoritative; this package adds a schema and a manifest but
|
|
278
|
+
does not declare a second `Order` interface.
|
|
279
|
+
|
|
280
|
+
Required fields are `run`, `workflow`, `step`, `key`, `defDigest`, `inputs`,
|
|
281
|
+
`outputs`, `consumes`, and `owes`.
|
|
282
|
+
|
|
283
|
+
Optional fields are `index`, `workdir`, `model`, `worker`, `judge`, `spec`, `x`,
|
|
284
|
+
`consumedFingerprint`, `consumesProof`, and `cause`. `workdir` may be authored
|
|
285
|
+
as a literal `workdir:` or resolved by the engine from a consumed artifact's
|
|
286
|
+
`workdirFrom:` value; the Order wire shape remains unchanged.
|
|
287
|
+
|
|
288
|
+
`defDigest` is a non-empty opaque reference. `inputs` and `outputs` are string
|
|
289
|
+
arrays. `consumes` is an open artifact-path map; `spec` and `x` are opaque
|
|
290
|
+
objects carried through without engine interpretation. `owes` contains the owed
|
|
291
|
+
path, an optional claim-time `version`, judgment/schema rejection counters,
|
|
292
|
+
reason entries, and an optional opaque `proof` string. `cause`, when present, is
|
|
293
|
+
`inputsGreen`, `allGreen`, or `idle`.
|
|
294
|
+
|
|
295
|
+
**Decision A — version cross-check without fingerprint recomputation.** The
|
|
296
|
+
`consumedFingerprint`, when present, is an open artifact-path map whose values
|
|
297
|
+
are the non-negative versions captured when the engine claimed the order. The
|
|
298
|
+
producer covers the map in its `submission.v1` signature. A driver enforces the
|
|
299
|
+
versions supplied in this map against signed `produced[].version`, but does not
|
|
300
|
+
recompute the producer's complete map from consumed values. A driver
|
|
301
|
+
distinguishes an absent map from a genuinely empty map: if the order has
|
|
302
|
+
consumed inputs but omits the map, the driver submits without a proof and emits
|
|
303
|
+
a warning; when independent authoritative output-version metadata is available,
|
|
304
|
+
an order with no consumed inputs may sign an explicitly empty `{}` map.
|
|
305
|
+
|
|
306
|
+
An explicit `{}` or partial map alongside a non-empty consumed set is still a
|
|
307
|
+
signed assertion of the map supplied on the wire. A consuming driver verifies
|
|
308
|
+
the supplied entries and enforces the versions that are present; the driver
|
|
309
|
+
does not recompute the producer's complete fingerprint map from values that
|
|
310
|
+
arrived in the same order. A hub that implements this target contract stores and relays the signed
|
|
311
|
+
content; the hub does not verify, repair, or authorize the assertion. The
|
|
312
|
+
current production hub does not yet implement that proof transport.
|
|
313
|
+
|
|
314
|
+
`consumesProof` is a JSON-serialized map from artifact path to serialized DSSE
|
|
315
|
+
envelope:
|
|
316
|
+
|
|
317
|
+
```json
|
|
318
|
+
{"input":"{\"payloadType\":\"application/vnd.owenloop.submission.v1+json\",\"payload\":\"...\",\"signatures\":[...] }"}
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
The map lets one order carry proofs from multiple producers without changing
|
|
322
|
+
the frozen string slot. In the target service protocol, the hub stores each
|
|
323
|
+
accepted submit proof beside the exact committed artifact version and omits
|
|
324
|
+
paths with no stored proof; `consumesProof` never contains null or empty-string
|
|
325
|
+
entries. The current production service does not provide that persistence or
|
|
326
|
+
projection. A consuming driver treats a missing entry as the `absent` verdict
|
|
327
|
+
and applies the configured artifact policy rather than stripping that artifact
|
|
328
|
+
from the order.
|
|
329
|
+
|
|
330
|
+
`owes[].proof`, when present, uses the same serialized DSSE envelope format. The
|
|
331
|
+
signed `submission.v1` record contains one `produced[]` entry for the owed path;
|
|
332
|
+
its `valueDigest` covers the complete `owes[].reasons` array at signing time.
|
|
333
|
+
A driver verifies the complete reason thread before any prompt renderer
|
|
334
|
+
truncates or summarizes the thread. The `submission.v1` record shape itself is
|
|
335
|
+
unchanged.
|
|
336
|
+
|
|
337
|
+
**Decision B — consumer-owned revocation anchor.** At consume time, the driver
|
|
338
|
+
samples its own clock once for the complete gate and evaluates revocations at
|
|
339
|
+
that instant. A producer-signed timestamp cannot move the `effectiveFrom <= at`
|
|
340
|
+
boundary; a timestamp ahead of the consumer clock is diagnostic only. A prior
|
|
341
|
+
successful consumption is not rewritten, but a later consumption can refuse the
|
|
342
|
+
same producer's artifact after a forward revocation cut.
|
|
343
|
+
|
|
344
|
+
## Trust posture
|
|
345
|
+
|
|
346
|
+
A hub or other remote coordinator is a transport, not an integrity authority.
|
|
347
|
+
A compromised transport may delay or stall progress, but a driver must verify
|
|
348
|
+
that executable instructions, shell commands, dynamic artifact values, and
|
|
349
|
+
trusted signer identities were not altered before acting on them. These wire
|
|
350
|
+
contracts carry the data needed for those checks; consume-side verification is
|
|
351
|
+
implemented at the consuming driver boundary and never delegated to the hub.
|
|
352
|
+
|
|
353
|
+
## Command payload and worker reject contracts
|
|
354
|
+
|
|
355
|
+
A command worker may emit one payload marker line on stdout:
|
|
356
|
+
|
|
357
|
+
```text
|
|
358
|
+
##owenloop:payload## {"...json..."}
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
The worker scans stdout lines and uses the last line whose marker starts at the
|
|
362
|
+
beginning of the line. A marker in the middle of a line is not a match. The JSON
|
|
363
|
+
text after the marker is capped at 64 KiB. A missing marker leaves `payload`
|
|
364
|
+
out of the `CommandReceipt`; malformed or over-cap JSON produces
|
|
365
|
+
`payloadError` and no `payload`, while leaving the command exit code unchanged.
|
|
366
|
+
When the hub supplies authoritative output-version metadata and the driver can
|
|
367
|
+
sign, the parsed payload is part of the receipt value covered by the DSSE
|
|
368
|
+
submission proof. Current producer command receipts are unsigned because the
|
|
369
|
+
deployed hub does not supply a retry-safe target version.
|
|
370
|
+
|
|
371
|
+
A worker rejects an artifact through the `reject` verb. The request is exactly:
|
|
372
|
+
|
|
373
|
+
```json
|
|
374
|
+
{"workflow":"<workflow>","run":"<run>","path":"<artifact stem>","text":"<reasons>"}
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
The request has no `by` field. The hub derives the rejecting step from the
|
|
378
|
+
claiming run. The response carries the common `text` field plus `ok` and an
|
|
379
|
+
optional `closed`; `closed: true` means the claiming run is already closed and
|
|
380
|
+
the holder must stop without releasing it again.
|