owenloop 0.5.0 → 0.5.2

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 (229) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/README.md +144 -35
  3. package/bin/owenloop.mjs +49 -1
  4. package/dist/packages/work/src/agent/brief.d.ts +29 -4
  5. package/dist/packages/work/src/agent/brief.js +49 -4
  6. package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
  7. package/dist/packages/work/src/agent/capability-model.js +148 -0
  8. package/dist/packages/work/src/agent/loop.d.ts +56 -7
  9. package/dist/packages/work/src/agent/loop.js +166 -9
  10. package/dist/packages/work/src/bundle/cache.d.ts +7 -5
  11. package/dist/packages/work/src/bundle/cache.js +20 -6
  12. package/dist/packages/work/src/bundle/fetch.d.ts +7 -5
  13. package/dist/packages/work/src/bundle/fetch.js +27 -7
  14. package/dist/packages/work/src/bundle/types.d.ts +8 -4
  15. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  16. package/dist/packages/work/src/consumed-verifier.js +205 -0
  17. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  18. package/dist/packages/work/src/exec/instructions.js +323 -0
  19. package/dist/packages/work/src/exec/loop.d.ts +29 -1
  20. package/dist/packages/work/src/exec/loop.js +313 -35
  21. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  22. package/dist/packages/work/src/exec/payload.js +54 -0
  23. package/dist/packages/work/src/exec/receipt.d.ts +9 -6
  24. package/dist/packages/work/src/exec/receipt.js +12 -1
  25. package/dist/packages/work/src/exec/runner.d.ts +7 -1
  26. package/dist/packages/work/src/exec/runner.js +84 -3
  27. package/dist/packages/work/src/harness/child-env.js +7 -0
  28. package/dist/packages/work/src/harness/claude.d.ts +20 -8
  29. package/dist/packages/work/src/harness/claude.js +260 -58
  30. package/dist/packages/work/src/harness/codex.d.ts +5 -4
  31. package/dist/packages/work/src/harness/codex.js +169 -41
  32. package/dist/packages/work/src/harness/contract.d.ts +36 -11
  33. package/dist/packages/work/src/harness/fake.js +1 -0
  34. package/dist/packages/work/src/harness/jsonrpc-stdio.js +7 -0
  35. package/dist/packages/work/src/harness/permissions.d.ts +16 -3
  36. package/dist/packages/work/src/harness/permissions.js +102 -13
  37. package/dist/packages/work/src/harness/session-store.d.ts +30 -10
  38. package/dist/packages/work/src/harness/session-store.js +317 -89
  39. package/dist/packages/work/src/hold/mcp.d.ts +25 -5
  40. package/dist/packages/work/src/hold/mcp.js +134 -12
  41. package/dist/packages/work/src/hub/client.d.ts +8 -1
  42. package/dist/packages/work/src/hub/client.js +15 -1
  43. package/dist/packages/work/src/hub/types.d.ts +137 -33
  44. package/dist/packages/work/src/hub/types.js +8 -10
  45. package/dist/packages/work/src/mcp/server.js +1 -1
  46. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  47. package/dist/packages/work/src/owenloop-bin.js +18 -0
  48. package/dist/packages/work/src/roles/agent-run.d.ts +12 -6
  49. package/dist/packages/work/src/roles/agent-run.js +115 -34
  50. package/dist/packages/work/src/roles/exec.d.ts +8 -0
  51. package/dist/packages/work/src/roles/exec.js +27 -2
  52. package/dist/packages/work/src/roles/hold.d.ts +6 -0
  53. package/dist/packages/work/src/roles/hold.js +83 -13
  54. package/dist/packages/work/src/roles/lint.d.ts +3 -4
  55. package/dist/packages/work/src/roles/lint.js +41 -7
  56. package/dist/packages/work/src/roles/settings.js +19 -2
  57. package/dist/packages/work/src/roles/shift.d.ts +1 -0
  58. package/dist/packages/work/src/roles/shift.js +36 -2
  59. package/dist/packages/work/src/settings/settings.d.ts +70 -1
  60. package/dist/packages/work/src/settings/settings.js +90 -4
  61. package/dist/packages/work/src/shift/logretention.d.ts +253 -0
  62. package/dist/packages/work/src/shift/logretention.js +407 -0
  63. package/dist/packages/work/src/shift/logsink.d.ts +14 -0
  64. package/dist/packages/work/src/shift/logsink.js +98 -0
  65. package/dist/packages/work/src/shift/loop.d.ts +32 -4
  66. package/dist/packages/work/src/shift/loop.js +687 -166
  67. package/dist/packages/work/src/shift/protocol.d.ts +128 -1
  68. package/dist/packages/work/src/shift/protocol.js +14 -0
  69. package/dist/packages/work/src/shift/runtime.d.ts +16 -0
  70. package/dist/packages/work/src/shift/runtime.js +291 -5
  71. package/dist/packages/work/src/shift/server.d.ts +13 -0
  72. package/dist/packages/work/src/shift/server.js +61 -36
  73. package/dist/packages/work/src/shift/spawn.d.ts +115 -19
  74. package/dist/packages/work/src/shift/spawn.js +234 -30
  75. package/dist/packages/work/src/shift/state.d.ts +76 -49
  76. package/dist/packages/work/src/shift/state.js +350 -103
  77. package/dist/packages/work/src/shift/truncate.d.ts +35 -0
  78. package/dist/packages/work/src/shift/truncate.js +73 -0
  79. package/dist/packages/work/src/submit-proof.d.ts +61 -0
  80. package/dist/packages/work/src/submit-proof.js +119 -0
  81. package/dist/packages/work/src/submit-value.d.ts +48 -0
  82. package/dist/packages/work/src/submit-value.js +118 -0
  83. package/dist/packages/work/src/usage.d.ts +1 -1
  84. package/dist/packages/work/src/usage.js +11 -0
  85. package/dist/src/add.d.ts +64 -259
  86. package/dist/src/add.js +81 -615
  87. package/dist/src/archive.d.ts +97 -0
  88. package/dist/src/archive.js +591 -0
  89. package/dist/src/bundle/index.d.ts +64 -0
  90. package/dist/src/bundle/index.js +508 -0
  91. package/dist/src/bundle/manifest.d.ts +50 -0
  92. package/dist/src/bundle/manifest.js +435 -0
  93. package/dist/src/bundle/runtime.d.ts +26 -0
  94. package/dist/src/bundle/runtime.js +64 -0
  95. package/dist/src/bundle/tar.d.ts +62 -0
  96. package/dist/src/bundle/tar.js +238 -0
  97. package/dist/src/bundle/types.d.ts +105 -0
  98. package/dist/src/bundle/types.js +21 -0
  99. package/dist/src/capabilities.d.ts +93 -0
  100. package/dist/src/capabilities.js +101 -0
  101. package/dist/src/cli.d.ts +90 -20
  102. package/dist/src/cli.js +2421 -374
  103. package/dist/src/credentials.d.ts +4 -3
  104. package/dist/src/credentials.js +21 -19
  105. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  106. package/dist/src/crypto/allowed-signers.js +307 -0
  107. package/dist/src/crypto/canonical.d.ts +8 -0
  108. package/dist/src/crypto/canonical.js +92 -0
  109. package/dist/src/crypto/chain.d.ts +65 -0
  110. package/dist/src/crypto/chain.js +377 -0
  111. package/dist/src/crypto/dsse.d.ts +209 -0
  112. package/dist/src/crypto/dsse.js +282 -0
  113. package/dist/src/crypto/enrollment.d.ts +78 -0
  114. package/dist/src/crypto/enrollment.js +186 -0
  115. package/dist/src/crypto/index.d.ts +48 -0
  116. package/dist/src/crypto/index.js +44 -0
  117. package/dist/src/crypto/keys.d.ts +258 -0
  118. package/dist/src/crypto/keys.js +908 -0
  119. package/dist/src/crypto/org-root.d.ts +33 -0
  120. package/dist/src/crypto/org-root.js +78 -0
  121. package/dist/src/crypto/origin-rules.d.ts +56 -0
  122. package/dist/src/crypto/origin-rules.js +143 -0
  123. package/dist/src/crypto/policy-floor.d.ts +98 -0
  124. package/dist/src/crypto/policy-floor.js +353 -0
  125. package/dist/src/crypto/records.d.ts +319 -0
  126. package/dist/src/crypto/records.js +168 -0
  127. package/dist/src/crypto/scope.d.ts +49 -0
  128. package/dist/src/crypto/scope.js +83 -0
  129. package/dist/src/crypto/ssh.d.ts +171 -0
  130. package/dist/src/crypto/ssh.js +396 -0
  131. package/dist/src/crypto/submission.d.ts +33 -0
  132. package/dist/src/crypto/submission.js +47 -0
  133. package/dist/src/crypto/trust-roots.d.ts +29 -0
  134. package/dist/src/crypto/trust-roots.js +39 -0
  135. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  136. package/dist/src/crypto/verify-consumed.js +259 -0
  137. package/dist/src/crypto/verify-origin.d.ts +50 -0
  138. package/dist/src/crypto/verify-origin.js +151 -0
  139. package/dist/src/crypto/verify-publication.d.ts +60 -0
  140. package/dist/src/crypto/verify-publication.js +150 -0
  141. package/dist/src/defs.d.ts +24 -1
  142. package/dist/src/defs.js +335 -27
  143. package/dist/src/engine.d.ts +211 -6
  144. package/dist/src/engine.js +459 -59
  145. package/dist/src/factory.d.ts +16 -0
  146. package/dist/src/factory.js +16 -4
  147. package/dist/src/global-config.d.ts +59 -0
  148. package/dist/src/global-config.js +84 -0
  149. package/dist/src/hub.d.ts +102 -32
  150. package/dist/src/hub.js +147 -58
  151. package/dist/src/index.d.ts +19 -2
  152. package/dist/src/index.js +23 -2
  153. package/dist/src/install.d.ts +538 -0
  154. package/dist/src/install.js +1981 -0
  155. package/dist/src/lock.d.ts +15 -57
  156. package/dist/src/lock.js +251 -143
  157. package/dist/src/mcp/serve.d.ts +46 -22
  158. package/dist/src/mcp/serve.js +174 -44
  159. package/dist/src/mcp/server.js +12 -1
  160. package/dist/src/model.d.ts +51 -0
  161. package/dist/src/model.js +157 -1
  162. package/dist/src/order-resolver.d.ts +184 -0
  163. package/dist/src/order-resolver.js +252 -0
  164. package/dist/src/package-version.d.ts +10 -0
  165. package/dist/src/package-version.js +42 -0
  166. package/dist/src/paths.d.ts +14 -1
  167. package/dist/src/paths.js +18 -0
  168. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  169. package/dist/src/schemas/index.d.ts +1433 -0
  170. package/dist/src/schemas/index.js +31 -0
  171. package/dist/src/schemas/order.v1.schema.json +120 -0
  172. package/dist/src/schemas/origin.v1.schema.json +68 -0
  173. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  174. package/dist/src/schemas/publication.v1.schema.json +31 -0
  175. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  176. package/dist/src/schemas/submission.v1.schema.json +61 -0
  177. package/dist/src/store/def-source.d.ts +52 -0
  178. package/dist/src/store/def-source.js +335 -0
  179. package/dist/src/store/index-file.d.ts +69 -0
  180. package/dist/src/store/index-file.js +151 -0
  181. package/dist/src/store/index.d.ts +27 -0
  182. package/dist/src/store/index.js +22 -0
  183. package/dist/src/store/ingestor.d.ts +43 -0
  184. package/dist/src/store/ingestor.js +211 -0
  185. package/dist/src/store/install.d.ts +228 -0
  186. package/dist/src/store/install.js +555 -0
  187. package/dist/src/store/instruction-source.d.ts +49 -0
  188. package/dist/src/store/instruction-source.js +298 -0
  189. package/dist/src/store/origin-evidence.d.ts +21 -0
  190. package/dist/src/store/origin-evidence.js +66 -0
  191. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  192. package/dist/src/store/pre-commit-verifier.js +418 -0
  193. package/dist/src/store/resolve.d.ts +138 -0
  194. package/dist/src/store/resolve.js +363 -0
  195. package/dist/src/store/types.d.ts +288 -0
  196. package/dist/src/store/types.js +356 -0
  197. package/dist/src/store.d.ts +33 -1
  198. package/dist/src/store.js +57 -4
  199. package/dist/src/types.d.ts +146 -12
  200. package/dist/src/untar.d.ts +8 -23
  201. package/dist/src/untar.js +10 -136
  202. package/docs/agent-runner.md +86 -0
  203. package/docs/authoring.md +64 -6
  204. package/docs/bundles.md +350 -0
  205. package/docs/cli.md +1298 -106
  206. package/docs/crypto.md +832 -0
  207. package/docs/design.md +342 -20
  208. package/docs/embedding.md +132 -25
  209. package/docs/shift-logs.md +642 -0
  210. package/docs/wire-contracts.md +395 -0
  211. package/package.json +6 -1
  212. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  213. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  214. package/plugins/claude-code/plugin/.mcp.json +14 -0
  215. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  216. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  217. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  218. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  219. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  220. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  221. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  222. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  223. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  224. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  225. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  226. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  227. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  228. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  229. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
package/docs/embedding.md CHANGED
@@ -16,13 +16,15 @@ can react the instant the graph advances instead of polling.
16
16
  ```ts
17
17
  import { createEngine } from 'owenloop';
18
18
 
19
- const { engine, store } = createEngine({
19
+ const { engine, store, resolver } = createEngine({
20
20
  db: '.owenloop/state.db', // SQLite path; ':memory:' for ephemeral. Default: .owenloop/state.db
21
21
  defsDir: 'workflows', // load *.yaml defs from a directory
22
22
  });
23
23
  ```
24
24
 
25
- `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:
26
28
 
27
29
  | option | meaning |
28
30
  |-------------|---------|
@@ -32,6 +34,7 @@ const { engine, store } = createEngine({
32
34
  | `reapTtlMs` | Forwarded to the `Engine` — the stranded-lease reap TTL. |
33
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. |
34
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. |
35
38
  | `onEvent` | A push-style observer registered at construction (equivalent to `engine.subscribe`). See [Events](#events). |
36
39
  | `onListenerError` | Where a throwing listener's error is routed (default: swallowed). |
37
40
 
@@ -42,15 +45,17 @@ Prefer to wire it yourself? The pieces are all exported — `createEngine` is ju
42
45
  sugar over them:
43
46
 
44
47
  ```ts
45
- import { Engine, openStore, loadDefs } from 'owenloop';
48
+ import { Engine, openStore, loadDefs, createDefInstructionSource } from 'owenloop';
46
49
 
47
50
  const store = openStore('.owenloop/state.db');
48
51
  const defs = loadDefs('workflows');
52
+ const instructionSource = createDefInstructionSource(defs.values());
49
53
  const engine = new Engine(store, (name) => {
50
54
  const d = defs.get(name);
51
55
  if (!d) throw new Error(`unknown workflow definition '${name}'`);
52
56
  return d;
53
- });
57
+ }, { instructionSource });
58
+ const { resolver } = engine;
54
59
  ```
55
60
 
56
61
  `loadDefs` already validates what it reads from disk. If you build a def set by
@@ -70,24 +75,88 @@ const wf = engine.createInstance('delivery', {
70
75
 
71
76
  const { orders } = engine.tick(wf);
72
77
  for (const order of orders) {
73
- const result = await runYourWorker(order); // ← your domain
74
- 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);
75
81
  if (commit.outcome !== 'green') {
76
82
  // born-rejected (an input moved) or schema-rejected (§18) — inspect commit.reason
77
83
  }
78
- engine.close(wf, order.run);
84
+ engine.close(order.workflow, order.run);
79
85
  }
80
86
 
81
87
  const status = engine.status(wf); // { done, debts, eligible, blocked, inFlight }
82
88
  ```
83
89
 
84
- Each `order` is self-contained: `workflow` (the instance it belongs to — see
85
- deep tick below), `prompt`, `consumes` (the captured green inputs), `owes` (the
86
- owed outputs + their accumulated reason threads), plus
87
- `inputs`/`outputs`/`model`/`executor`/`command`/`spec`. A consumer rejecting an
88
- upstream artifact is just `engine.reject(wf, path, by, text)`; the forward
89
- cascade and stall liveness behave exactly as they do under the CLI, because
90
- 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.
91
160
 
92
161
  `engine.tick(wf)` is **deep by default**: after ticking `wf` it descends into
93
162
  every live `calls:` child (recursively), folding their orders, `reaped`, folded
@@ -111,27 +180,32 @@ one `TickResult` belongs to the instance you ticked; each order carries its own
111
180
  (CLI `--shallow`) stays the deliberate single-instance escape hatch when you
112
181
  want exactly the old behavior.
113
182
 
114
- `order.executor` 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
115
184
  embedder: rather than every order going to the same LLM-driving `runYourWorker`,
116
185
  branch on it before deciding how to run the order.
117
186
 
118
187
  ```ts
119
188
  for (const order of orders) {
189
+ const instructions = resolver.resolveOrder(order);
120
190
  const result =
121
- order.executor === 'command'
122
- ? await runCommand(order.command!, order.spec) // order.command is opaque — never shelled out by owenloop itself
123
- : await runYourAgent(order); // default / executor: 'agent' / anything else you handle the same way
191
+ order.worker === 'command'
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
124
194
 
125
- const commit = engine.green(wf, order.run, order.outputs[0], result);
126
- 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);
127
197
  }
128
198
  ```
129
199
 
130
- `executor`/`command`/`spec` are all optional and opaque — the engine only
131
- shape-checks them at load time (`command` a string, `spec` a plain map) and
132
- never reads their contents itself. `order.executor` is `undefined` when the
133
- step never set it (today's default, unaffected by this feature). See
134
- [`docs/design.md` §27.4](design.md) for the full contract and
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
135
209
  [`docs/authoring.md`](authoring.md#executor--declaring-the-executor) for how to
136
210
  declare it on a step.
137
211
 
@@ -321,6 +395,39 @@ means "no credential", but an exception means "the configured command could not
321
395
  produce one" — surface its message rather than treating it as an empty slot,
322
396
  because falling back to a local store is exactly what the setting forbids.
323
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
+
324
431
  `SUPPORTED_ENGINE_VERSION` is the programmatic form of the design.md §27
325
432
  engine-version contract — the highest `engine:` a def may declare and still load.
326
433
  Tooling can preflight-check a def's `engine:` field against it before handing the