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.
Files changed (282) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/README.md +182 -53
  3. package/bin/owenloop.mjs +50 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +176 -0
  5. package/dist/packages/work/src/agent/brief.js +197 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +141 -0
  7. package/dist/packages/work/src/agent/loop.js +669 -0
  8. package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
  9. package/dist/packages/work/src/agent/model-policy.js +138 -0
  10. package/dist/packages/work/src/agent/workdir.d.ts +210 -0
  11. package/dist/packages/work/src/agent/workdir.js +319 -0
  12. package/dist/packages/work/src/bundle/cache.d.ts +92 -0
  13. package/dist/packages/work/src/bundle/cache.js +338 -0
  14. package/dist/packages/work/src/bundle/fetch.d.ts +87 -0
  15. package/dist/packages/work/src/bundle/fetch.js +345 -0
  16. package/dist/packages/work/src/bundle/types.d.ts +164 -0
  17. package/dist/packages/work/src/bundle/types.js +1 -0
  18. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  19. package/dist/packages/work/src/consumed-verifier.js +205 -0
  20. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  21. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  22. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  23. package/dist/packages/work/src/credentials/reader.js +32 -0
  24. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  25. package/dist/packages/work/src/credentials/resolve.js +56 -0
  26. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  27. package/dist/packages/work/src/exec/instructions.js +323 -0
  28. package/dist/packages/work/src/exec/loop.d.ts +40 -0
  29. package/dist/packages/work/src/exec/loop.js +332 -0
  30. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  31. package/dist/packages/work/src/exec/payload.js +54 -0
  32. package/dist/packages/work/src/exec/receipt.d.ts +41 -0
  33. package/dist/packages/work/src/exec/receipt.js +32 -0
  34. package/dist/packages/work/src/exec/runner.d.ts +71 -0
  35. package/dist/packages/work/src/exec/runner.js +256 -0
  36. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  37. package/dist/packages/work/src/harness/child-env.js +134 -0
  38. package/dist/packages/work/src/harness/claude.d.ts +140 -0
  39. package/dist/packages/work/src/harness/claude.js +837 -0
  40. package/dist/packages/work/src/harness/codex.d.ts +111 -0
  41. package/dist/packages/work/src/harness/codex.js +1024 -0
  42. package/dist/packages/work/src/harness/contract.d.ts +308 -0
  43. package/dist/packages/work/src/harness/contract.js +32 -0
  44. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  45. package/dist/packages/work/src/harness/fake.js +91 -0
  46. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  47. package/dist/packages/work/src/harness/jsonrpc-stdio.js +351 -0
  48. package/dist/packages/work/src/harness/permissions.d.ts +75 -0
  49. package/dist/packages/work/src/harness/permissions.js +182 -0
  50. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  51. package/dist/packages/work/src/harness/registry.js +45 -0
  52. package/dist/packages/work/src/harness/session-store.d.ts +181 -0
  53. package/dist/packages/work/src/harness/session-store.js +523 -0
  54. package/dist/packages/work/src/harness/types.d.ts +29 -0
  55. package/dist/packages/work/src/harness/types.js +14 -0
  56. package/dist/packages/work/src/harnesses.d.ts +38 -0
  57. package/dist/packages/work/src/harnesses.js +38 -0
  58. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  59. package/dist/packages/work/src/hold/loop.js +23 -0
  60. package/dist/packages/work/src/hold/mcp.d.ts +75 -0
  61. package/dist/packages/work/src/hold/mcp.js +264 -0
  62. package/dist/packages/work/src/hub/client.d.ts +23 -0
  63. package/dist/packages/work/src/hub/client.js +91 -0
  64. package/dist/packages/work/src/hub/types.d.ts +326 -0
  65. package/dist/packages/work/src/hub/types.js +26 -0
  66. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  67. package/dist/packages/work/src/lease/loop.js +277 -0
  68. package/dist/packages/work/src/main.d.ts +1 -0
  69. package/dist/packages/work/src/main.js +48 -0
  70. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  71. package/dist/packages/work/src/mcp/server.js +320 -0
  72. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  73. package/dist/packages/work/src/owenloop-bin.js +18 -0
  74. package/dist/packages/work/src/roles/agent-run.d.ts +124 -0
  75. package/dist/packages/work/src/roles/agent-run.js +529 -0
  76. package/dist/packages/work/src/roles/exec.d.ts +48 -0
  77. package/dist/packages/work/src/roles/exec.js +228 -0
  78. package/dist/packages/work/src/roles/hold.d.ts +72 -0
  79. package/dist/packages/work/src/roles/hold.js +363 -0
  80. package/dist/packages/work/src/roles/join.d.ts +18 -0
  81. package/dist/packages/work/src/roles/join.js +204 -0
  82. package/dist/packages/work/src/roles/lint.d.ts +58 -0
  83. package/dist/packages/work/src/roles/lint.js +234 -0
  84. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  85. package/dist/packages/work/src/roles/prepare.js +249 -0
  86. package/dist/packages/work/src/roles/release.d.ts +48 -0
  87. package/dist/packages/work/src/roles/release.js +137 -0
  88. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  89. package/dist/packages/work/src/roles/sessions.js +180 -0
  90. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  91. package/dist/packages/work/src/roles/settings.js +71 -0
  92. package/dist/packages/work/src/roles/shift.d.ts +13 -0
  93. package/dist/packages/work/src/roles/shift.js +250 -0
  94. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  95. package/dist/packages/work/src/roles/signals.js +62 -0
  96. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  97. package/dist/packages/work/src/settings/provision.js +47 -0
  98. package/dist/packages/work/src/settings/settings.d.ts +136 -0
  99. package/dist/packages/work/src/settings/settings.js +155 -0
  100. package/dist/packages/work/src/shift/client.d.ts +24 -0
  101. package/dist/packages/work/src/shift/client.js +124 -0
  102. package/dist/packages/work/src/shift/loop.d.ts +131 -0
  103. package/dist/packages/work/src/shift/loop.js +751 -0
  104. package/dist/packages/work/src/shift/protocol.d.ts +95 -0
  105. package/dist/packages/work/src/shift/protocol.js +24 -0
  106. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  107. package/dist/packages/work/src/shift/routing.js +50 -0
  108. package/dist/packages/work/src/shift/runtime.d.ts +45 -0
  109. package/dist/packages/work/src/shift/runtime.js +337 -0
  110. package/dist/packages/work/src/shift/server.d.ts +23 -0
  111. package/dist/packages/work/src/shift/server.js +716 -0
  112. package/dist/packages/work/src/shift/spawn.d.ts +109 -0
  113. package/dist/packages/work/src/shift/spawn.js +158 -0
  114. package/dist/packages/work/src/shift/state.d.ts +79 -0
  115. package/dist/packages/work/src/shift/state.js +385 -0
  116. package/dist/packages/work/src/submit-proof.d.ts +36 -0
  117. package/dist/packages/work/src/submit-proof.js +93 -0
  118. package/dist/packages/work/src/usage.d.ts +6 -0
  119. package/dist/packages/work/src/usage.js +175 -0
  120. package/dist/src/add.d.ts +189 -0
  121. package/dist/src/add.js +300 -0
  122. package/dist/src/archive.d.ts +97 -0
  123. package/dist/src/archive.js +591 -0
  124. package/dist/src/bundle/index.d.ts +64 -0
  125. package/dist/src/bundle/index.js +508 -0
  126. package/dist/src/bundle/manifest.d.ts +50 -0
  127. package/dist/src/bundle/manifest.js +435 -0
  128. package/dist/src/bundle/runtime.d.ts +26 -0
  129. package/dist/src/bundle/runtime.js +64 -0
  130. package/dist/src/bundle/tar.d.ts +62 -0
  131. package/dist/src/bundle/tar.js +238 -0
  132. package/dist/src/bundle/types.d.ts +105 -0
  133. package/dist/src/bundle/types.js +21 -0
  134. package/dist/{cli.d.ts → src/cli.d.ts} +92 -7
  135. package/dist/src/cli.js +5968 -0
  136. package/dist/{credentials.d.ts → src/credentials.d.ts} +22 -15
  137. package/dist/{credentials.js → src/credentials.js} +35 -31
  138. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  139. package/dist/src/crypto/allowed-signers.js +307 -0
  140. package/dist/src/crypto/canonical.d.ts +8 -0
  141. package/dist/src/crypto/canonical.js +92 -0
  142. package/dist/src/crypto/chain.d.ts +65 -0
  143. package/dist/src/crypto/chain.js +377 -0
  144. package/dist/src/crypto/dsse.d.ts +209 -0
  145. package/dist/src/crypto/dsse.js +282 -0
  146. package/dist/src/crypto/enrollment.d.ts +78 -0
  147. package/dist/src/crypto/enrollment.js +186 -0
  148. package/dist/src/crypto/index.d.ts +48 -0
  149. package/dist/src/crypto/index.js +44 -0
  150. package/dist/src/crypto/keys.d.ts +258 -0
  151. package/dist/src/crypto/keys.js +908 -0
  152. package/dist/src/crypto/org-root.d.ts +33 -0
  153. package/dist/src/crypto/org-root.js +78 -0
  154. package/dist/src/crypto/origin-rules.d.ts +56 -0
  155. package/dist/src/crypto/origin-rules.js +143 -0
  156. package/dist/src/crypto/policy-floor.d.ts +98 -0
  157. package/dist/src/crypto/policy-floor.js +353 -0
  158. package/dist/src/crypto/records.d.ts +316 -0
  159. package/dist/src/crypto/records.js +157 -0
  160. package/dist/src/crypto/scope.d.ts +49 -0
  161. package/dist/src/crypto/scope.js +83 -0
  162. package/dist/src/crypto/ssh.d.ts +171 -0
  163. package/dist/src/crypto/ssh.js +396 -0
  164. package/dist/src/crypto/submission.d.ts +33 -0
  165. package/dist/src/crypto/submission.js +47 -0
  166. package/dist/src/crypto/trust-roots.d.ts +29 -0
  167. package/dist/src/crypto/trust-roots.js +39 -0
  168. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  169. package/dist/src/crypto/verify-consumed.js +259 -0
  170. package/dist/src/crypto/verify-origin.d.ts +50 -0
  171. package/dist/src/crypto/verify-origin.js +151 -0
  172. package/dist/src/crypto/verify-publication.d.ts +60 -0
  173. package/dist/src/crypto/verify-publication.js +150 -0
  174. package/dist/{defs.d.ts → src/defs.d.ts} +24 -1
  175. package/dist/{defs.js → src/defs.js} +181 -61
  176. package/dist/{engine.d.ts → src/engine.d.ts} +105 -9
  177. package/dist/{engine.js → src/engine.js} +251 -47
  178. package/dist/{factory.d.ts → src/factory.d.ts} +16 -0
  179. package/dist/{factory.js → src/factory.js} +16 -4
  180. package/dist/src/global-config.d.ts +59 -0
  181. package/dist/src/global-config.js +84 -0
  182. package/dist/{hub.d.ts → src/hub.d.ts} +280 -31
  183. package/dist/{hub.js → src/hub.js} +493 -52
  184. package/dist/src/index.d.ts +47 -0
  185. package/dist/src/index.js +41 -0
  186. package/dist/src/install.d.ts +538 -0
  187. package/dist/src/install.js +1981 -0
  188. package/dist/src/lock.d.ts +38 -0
  189. package/dist/src/lock.js +325 -0
  190. package/dist/src/mcp/serve.d.ts +109 -0
  191. package/dist/{mcp → src/mcp}/serve.js +335 -75
  192. package/dist/{mcp → src/mcp}/server.d.ts +6 -9
  193. package/dist/{mcp → src/mcp}/server.js +18 -10
  194. package/dist/{model.d.ts → src/model.d.ts} +15 -0
  195. package/dist/{model.js → src/model.js} +112 -2
  196. package/dist/src/order-resolver.d.ts +184 -0
  197. package/dist/src/order-resolver.js +252 -0
  198. package/dist/src/package-version.d.ts +10 -0
  199. package/dist/src/package-version.js +42 -0
  200. package/dist/{paths.d.ts → src/paths.d.ts} +14 -1
  201. package/dist/{paths.js → src/paths.js} +18 -0
  202. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  203. package/dist/src/schemas/index.d.ts +1416 -0
  204. package/dist/src/schemas/index.js +31 -0
  205. package/dist/src/schemas/order.v1.schema.json +106 -0
  206. package/dist/src/schemas/origin.v1.schema.json +68 -0
  207. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  208. package/dist/src/schemas/publication.v1.schema.json +31 -0
  209. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  210. package/dist/src/schemas/submission.v1.schema.json +61 -0
  211. package/dist/src/store/def-source.d.ts +52 -0
  212. package/dist/src/store/def-source.js +335 -0
  213. package/dist/src/store/index-file.d.ts +69 -0
  214. package/dist/src/store/index-file.js +151 -0
  215. package/dist/src/store/index.d.ts +27 -0
  216. package/dist/src/store/index.js +22 -0
  217. package/dist/src/store/ingestor.d.ts +43 -0
  218. package/dist/src/store/ingestor.js +211 -0
  219. package/dist/src/store/install.d.ts +228 -0
  220. package/dist/src/store/install.js +555 -0
  221. package/dist/src/store/instruction-source.d.ts +49 -0
  222. package/dist/src/store/instruction-source.js +298 -0
  223. package/dist/src/store/origin-evidence.d.ts +21 -0
  224. package/dist/src/store/origin-evidence.js +66 -0
  225. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  226. package/dist/src/store/pre-commit-verifier.js +418 -0
  227. package/dist/src/store/resolve.d.ts +138 -0
  228. package/dist/src/store/resolve.js +363 -0
  229. package/dist/src/store/types.d.ts +288 -0
  230. package/dist/src/store/types.js +356 -0
  231. package/dist/{types.d.ts → src/types.d.ts} +58 -24
  232. package/dist/{untar.d.ts → src/untar.d.ts} +8 -23
  233. package/dist/src/untar.js +38 -0
  234. package/dist/{util.d.ts → src/util.d.ts} +3 -2
  235. package/dist/{util.js → src/util.js} +3 -2
  236. package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
  237. package/dist/{owenwork.js → src/work-settings.js} +27 -27
  238. package/docs/agent-runner.md +86 -0
  239. package/docs/authoring.md +150 -59
  240. package/docs/bundles.md +250 -0
  241. package/docs/cli.md +1758 -163
  242. package/docs/crypto.md +816 -0
  243. package/docs/design.md +374 -52
  244. package/docs/embedding.md +135 -27
  245. package/docs/wire-contracts.md +380 -0
  246. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  247. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  248. package/examples/workflows/judges/gate-sharpness.md +39 -0
  249. package/examples/workflows/judges/security.md +34 -0
  250. package/package.json +22 -8
  251. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  252. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  253. package/plugins/claude-code/plugin/.mcp.json +14 -0
  254. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  255. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  256. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  257. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  258. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  259. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  260. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  261. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  262. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  263. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  264. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  265. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  266. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  267. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  268. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
  269. package/dist/add.d.ts +0 -384
  270. package/dist/add.js +0 -834
  271. package/dist/cli.js +0 -3270
  272. package/dist/index.d.ts +0 -32
  273. package/dist/index.js +0 -23
  274. package/dist/lock.d.ts +0 -80
  275. package/dist/lock.js +0 -217
  276. package/dist/mcp/serve.d.ts +0 -84
  277. package/dist/untar.js +0 -164
  278. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  279. /package/dist/{schema.js → src/schema.js} +0 -0
  280. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  281. /package/dist/{store.js → src/store.js} +0 -0
  282. /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
- in-memory definitions, lifecycle/concurrency, and **push-style events** so a host
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 }` and accepts:
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 result = await runYourWorker(order); // ← your domain
73
- const commit = engine.green(wf, order.run, order.outputs[0], result);
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(wf, order.run);
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 self-contained: `workflow` (the instance it belongs to — see
84
- deep tick below), `prompt`, `consumes` (the captured green inputs), `owes` (the
85
- owed outputs + their accumulated reason threads), plus
86
- `inputs`/`outputs`/`model`/`worker`/`command`/`spec`. A consumer rejecting an
87
- upstream artifact is just `engine.reject(wf, path, by, text)`; the forward
88
- cascade and stall liveness behave exactly as they do under the CLI, because
89
- it's the same engine.
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-executor-type earns its keep in an
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(order.command!, order.spec) // order.command is opaque — never shelled out by owenloop itself
122
- : await runYourAgent(order); // default / worker: 'agent' / anything else you handle the same way
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(wf, order.run, order.outputs[0], result);
125
- engine.close(wf, order.run);
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`/`command`/`spec` are all optional and opaque — the engine only
130
- shape-checks them at load time (`command` a string, `spec` a plain map) and
131
- never reads their contents itself. `order.worker` is `undefined` when the
132
- step never set it (today's default, unaffected by this feature). See
133
- [`docs/design.md` §27.4](design.md) for the full contract and
134
- [`docs/authoring.md`](authoring.md#worker--declaring-the-executor) for how to
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.