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
@@ -81,6 +81,16 @@ export declare function lintDef(def: WorkflowDef): {
81
81
  errors: string[];
82
82
  warnings: string[];
83
83
  };
84
+ /** Stable private-map key for one installed coordinate at one verified digest. */
85
+ export declare function digestScopedCallsTargetKey(digest: string, target: string): string;
86
+ /**
87
+ * The def a `calls:` edge names, honoring CAS bundle scope — the value form of
88
+ * {@link resolveCallsTargetKey}. This is the ONE resolution rule shared by
89
+ * load-time validation (`finalizeDefs`), cycle detection, and the engine's
90
+ * spawn path, so a def that validates at load time is the same def the engine
91
+ * spawns at runtime.
92
+ */
93
+ export declare function resolveCallsTarget(defs: Map<string, WorkflowDef>, target: string, from: WorkflowDef): WorkflowDef | undefined;
84
94
  /** Load and validate a single workflow definition from a YAML file. */
85
95
  export declare function loadDefFile(file: string): WorkflowDef;
86
96
  /**
@@ -125,7 +135,20 @@ export declare function loadDefsUnfinalized(dir: string): Map<string, WorkflowDe
125
135
  * for a def without `_includes` (the normal in-memory case), so passing a plain
126
136
  * def map through is cheap and only adds the cross-def + cycle checks.
127
137
  */
128
- export declare function finalizeDefs(raw: Map<string, WorkflowDef>): Map<string, WorkflowDef>;
138
+ export interface FinalizeDefsOptions {
139
+ /**
140
+ * Explicit versioned targets whose definitions live in another installed
141
+ * bundle. Install-time validation may defer those edges; executable discovery
142
+ * later validates them against the complete store map before any run starts.
143
+ */
144
+ allowUnresolvedVersionedCalls?: ReadonlySet<string>;
145
+ /**
146
+ * Permit unresolved `calls:` edges in an explicitly partial, read-only map.
147
+ * Never use this option to construct an executable resolver.
148
+ */
149
+ allowUnresolvedCalls?: boolean;
150
+ }
151
+ export declare function finalizeDefs(raw: Map<string, WorkflowDef>, options?: FinalizeDefsOptions): Map<string, WorkflowDef>;
129
152
  /** One file that `loadDefsRaw` could not turn into a def (malformed YAML, bad shape, duplicate name). */
130
153
  export interface DefLoadFailure {
131
154
  file: string;
@@ -23,7 +23,7 @@ import { createHash } from 'node:crypto';
23
23
  import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
24
24
  import { basename, dirname, isAbsolute, join, sep } from 'node:path';
25
25
  import { parse as parseYaml } from 'yaml';
26
- import { parseConsume, parseProduce } from "./paths.js";
26
+ import { parseConsume, parseProduce, parseWorkdirFrom } from "./paths.js";
27
27
  import { parseDurationMs, parseDurationSecs } from "./util.js";
28
28
  import { assertValidSchema } from "./schema.js";
29
29
  /** Hand-maintained key allowlist for RawInput — kept next to the interface so
@@ -35,13 +35,13 @@ const RAW_PRODUCE_KEYS = ['name', 'schema', 'judges', 'maxAttempts', 'maxSchemaF
35
35
  * fields, so it gets its own allowlist rather than folding into
36
36
  * RAW_PRODUCE_KEYS (§27 unknown-key rejection). */
37
37
  const RAW_GROUP_KEYS = ['group', 'mode', 'of'];
38
- const RAW_JUDGE_KEYS = ['name', 'body', 'bodyFile', 'model', 'inputs', 'cadence', 'maxRunsPerDay', 'worker', 'command', 'spec'];
38
+ const RAW_JUDGE_KEYS = ['name', 'body', 'bodyFile', 'model', 'inputs', 'cadence', 'maxRunsPerDay', 'executor', 'command', 'spec'];
39
39
  /** Keys valid on a normal (non-calls:, non-include:) step entry. */
40
40
  const RAW_STEP_KEYS = [
41
41
  'name', 'consumes', 'produces', 'generates', 'invalidates', 'cadence',
42
42
  'maxRunsPerDay', 'parallel', 'maxAttempts', 'maxSchemaFailures', 'model',
43
- 'workdir', 'terminal', 'effect', 'on', 'idleAfter', 'body', 'bodyFile',
44
- 'calls', 'reapTtl', 'labels', 'maxLease', 'x', 'worker', 'command', 'spec',
43
+ 'workdir', 'workdirFrom', 'terminal', 'effect', 'on', 'idleAfter', 'body', 'bodyFile',
44
+ 'calls', 'reapTtl', 'capabilities', 'maxLease', 'x', 'executor', 'command', 'spec',
45
45
  ];
46
46
  /** Keys valid on a calls: step entry — a DIFFERENT (smaller) shape than RawStep;
47
47
  * the `calls:` key is what routes an entry here instead of RAW_STEP_KEYS. */
@@ -49,7 +49,7 @@ const RAW_CALLS_KEYS = ['name', 'calls', 'inputs', 'produces'];
49
49
  /** Keys valid on an include: directive entry — the `include:` key is the
50
50
  * discriminator that routes an entry here instead of RAW_STEP_KEYS/RAW_CALLS_KEYS. */
51
51
  const RAW_INCLUDE_KEYS = ['include', 'as', 'inputs'];
52
- const RAW_DEF_KEYS = ['name', 'title', 'description', 'inputs', 'steps', 'outputs', 'invariants', 'engine', 'x', 'workers'];
52
+ const RAW_DEF_KEYS = ['name', 'title', 'description', 'inputs', 'steps', 'outputs', 'invariants', 'engine', 'x', 'executors'];
53
53
  // ---- defaults ----------------------------------------------------------------
54
54
  const DEFAULTS = {
55
55
  cadence: '0s',
@@ -263,8 +263,8 @@ function parseJudges(v, ctx, baseDir) {
263
263
  if (raw.maxRunsPerDay !== undefined) {
264
264
  judge.maxRunsPerDay = asNumber(raw.maxRunsPerDay, DEFAULTS.maxRunsPerDay, `judge '${name}'.maxRunsPerDay`);
265
265
  }
266
- if (raw.worker !== undefined)
267
- judge.worker = asString(raw.worker, `judge '${name}'.worker`);
266
+ if (raw.executor !== undefined)
267
+ judge.executor = asString(raw.executor, `judge '${name}'.executor`);
268
268
  if (raw.command !== undefined)
269
269
  judge.command = asString(raw.command, `judge '${name}'.command`);
270
270
  if (raw.spec !== undefined)
@@ -574,8 +574,8 @@ export function buildDef(raw, source, baseDir) {
574
574
  }
575
575
  if (r.x !== undefined)
576
576
  def.x = asExtension(r.x, `workflow '${name}'.x`);
577
- if (r.workers !== undefined)
578
- def.workers = asStringArray(r.workers, `workflow '${name}'.workers`);
577
+ if (r.executors !== undefined)
578
+ def.executors = asStringArray(r.executors, `workflow '${name}'.executors`);
579
579
  return def;
580
580
  }
581
581
  // ---- Mode 1 expand helpers (M1-EXPAND) ----------------------------------------
@@ -626,6 +626,14 @@ function prefixStep(step, prefix) {
626
626
  // judges: marker names a local stem (unlike calls:, which names an external
627
627
  // workflow) — it must be prefixed to keep pointing at the (now-prefixed) produce.
628
628
  const newJudges = step.judges !== undefined ? prefixStem(step.judges) : undefined;
629
+ // workdirFrom names a local consumed stem followed by a dotted value path.
630
+ // Prefix only the stem; the value path is a field path inside the consumed value.
631
+ let newWorkdirFrom = step.workdirFrom;
632
+ if (step.workdirFrom !== undefined) {
633
+ const parsed = parseWorkdirFrom(step.workdirFrom, step.consumes);
634
+ if (parsed)
635
+ newWorkdirFrom = `${prefixStem(parsed.stem)}.${parsed.path}`;
636
+ }
629
637
  const result = {
630
638
  ...step,
631
639
  name: prefixStem(step.name),
@@ -633,12 +641,19 @@ function prefixStep(step, prefix) {
633
641
  produces: newProduces,
634
642
  invalidates: newInvalidates,
635
643
  };
644
+ // Each include alias is an independent materialization. Clone the opaque
645
+ // extension carrier so nested values cannot leak mutations across aliases or
646
+ // back into the resolved child definition. Preserve true absence.
647
+ if (step.x !== undefined)
648
+ result.x = structuredClone(step.x);
636
649
  if (newGenerates !== undefined)
637
650
  result.generates = newGenerates;
638
651
  if (newEffect !== undefined)
639
652
  result.effect = newEffect;
640
653
  if (newJudges !== undefined)
641
654
  result.judges = newJudges;
655
+ if (newWorkdirFrom !== undefined)
656
+ result.workdirFrom = newWorkdirFrom;
642
657
  return result;
643
658
  }
644
659
  /**
@@ -757,7 +772,7 @@ export function parseDef(raw, source, baseDir) {
757
772
  * an ordinary step, because judge orders flow through the normal
758
773
  * eligibleFirings → applySchedule → claim → buildOrder pipeline (§7.1).
759
774
  */
760
- function synthesizeJudgeSteps(producerStepName, pat, producerConsumeStems) {
775
+ function synthesizeJudgeSteps(producerStepName, pat, producerConsumeStems, producerX) {
761
776
  if (!pat.judges || pat.judges.length === 0)
762
777
  return [];
763
778
  return pat.judges.map((j) => {
@@ -778,10 +793,15 @@ function synthesizeJudgeSteps(producerStepName, pat, producerConsumeStems) {
778
793
  maxSchemaFailures: DEFAULTS.maxSchemaFailures,
779
794
  body: j.body,
780
795
  };
796
+ // Every native judge executes under the producer's complete opaque extension
797
+ // carrier. Clone per judge so neither producer nor sibling mutations can
798
+ // alter another synthesized step. Absence stays absence: no empty x bag.
799
+ if (producerX !== undefined)
800
+ step.x = structuredClone(producerX);
781
801
  if (j.model !== undefined)
782
802
  step.model = j.model;
783
- if (j.worker !== undefined)
784
- step.worker = j.worker;
803
+ if (j.executor !== undefined)
804
+ step.executor = j.executor;
785
805
  if (j.command !== undefined)
786
806
  step.command = j.command;
787
807
  if (j.spec !== undefined)
@@ -877,10 +897,12 @@ function buildStep(rl, i, baseDir) {
877
897
  };
878
898
  if (rl.workdir !== undefined)
879
899
  step.workdir = asString(rl.workdir, `step '${name}'.workdir`);
900
+ if (rl.workdirFrom !== undefined)
901
+ step.workdirFrom = asString(rl.workdirFrom, `step '${name}'.workdirFrom`);
880
902
  if (rl.model !== undefined)
881
903
  step.model = asString(rl.model, `step '${name}'.model`);
882
- if (rl.worker !== undefined)
883
- step.worker = asString(rl.worker, `step '${name}'.worker`);
904
+ if (rl.executor !== undefined)
905
+ step.executor = asString(rl.executor, `step '${name}'.executor`);
884
906
  if (rl.command !== undefined)
885
907
  step.command = asString(rl.command, `step '${name}'.command`);
886
908
  if (rl.spec !== undefined)
@@ -929,12 +951,12 @@ function buildStep(rl, i, baseDir) {
929
951
  const reapTtlStr = asString(rl.reapTtl, `step '${name}'.reapTtl`);
930
952
  step.reapTtlMs = parseDurationMs(reapTtlStr);
931
953
  }
932
- // A2: opaque routing labels. Empty list normalizes to absent (claimable by
954
+ // A2: opaque routing capabilities. Empty list normalizes to absent (claimable by
933
955
  // any caller), mirroring the groups.length > 0 pattern below.
934
- if (rl.labels !== undefined) {
935
- const ls = asStringArray(rl.labels, `step '${name}'.labels`);
956
+ if (rl.capabilities !== undefined) {
957
+ const ls = asStringArray(rl.capabilities, `step '${name}'.capabilities`);
936
958
  if (ls.length > 0)
937
- step.labels = ls;
959
+ step.capabilities = ls;
938
960
  }
939
961
  // A3: per-step max total lease lifetime (duration string, same as reapTtl).
940
962
  if (rl.maxLease !== undefined) {
@@ -948,7 +970,7 @@ function buildStep(rl, i, baseDir) {
948
970
  }
949
971
  }
950
972
  const producerConsumeStems = consumes.map((c) => c.stem);
951
- const judgeSteps = producesPatterns.flatMap((p) => synthesizeJudgeSteps(name, p, producerConsumeStems));
973
+ const judgeSteps = producesPatterns.flatMap((p) => synthesizeJudgeSteps(name, p, producerConsumeStems, step.x));
952
974
  return [step, ...judgeSteps];
953
975
  }
954
976
  // ---- validation --------------------------------------------------------------
@@ -971,6 +993,41 @@ export function validateDef(def) {
971
993
  for (const dup of [...inputNames].filter((n) => stepNames.has(n))) {
972
994
  errors.push(`'${dup}' is both an input and a step name`);
973
995
  }
996
+ for (const l of def.steps) {
997
+ if (l.workdir === undefined && l.workdirFrom === undefined)
998
+ continue;
999
+ if (l.workdir !== undefined && l.workdirFrom !== undefined) {
1000
+ errors.push(`step '${l.name}': workdir and workdirFrom are mutually exclusive; use one`);
1001
+ continue;
1002
+ }
1003
+ if (l.workdirFrom === undefined)
1004
+ continue;
1005
+ const raw = l.workdirFrom.trim();
1006
+ const bareConsume = l.consumes.find((c) => c.stem === raw);
1007
+ if (bareConsume) {
1008
+ errors.push(`step '${l.name}': workdirFrom must use '<consumedStem>.<dotted.path>' with a non-empty value path`);
1009
+ continue;
1010
+ }
1011
+ const firstDot = raw.indexOf('.');
1012
+ const valuePath = firstDot >= 0 ? raw.slice(firstDot + 1) : '';
1013
+ if (firstDot <= 0 || valuePath.length === 0) {
1014
+ errors.push(`step '${l.name}': workdirFrom must use '<consumedStem>.<dotted.path>' with a non-empty value path`);
1015
+ continue;
1016
+ }
1017
+ // Security boundary: a workdirFrom value becomes a filesystem path. The
1018
+ // source stem must be a plain consumed artifact so its value has passed the
1019
+ // engine's consume-side verification gate before a worker can cd into it.
1020
+ const parsed = parseWorkdirFrom(raw, l.consumes);
1021
+ if (!parsed) {
1022
+ const stem = raw.slice(0, firstDot);
1023
+ errors.push(`step '${l.name}': workdirFrom stem '${stem}' is not in consumes; ` +
1024
+ 'a step may only take its workdir from an artifact it consumes');
1025
+ }
1026
+ else if (parsed.mode !== 'plain') {
1027
+ errors.push(`step '${l.name}': workdirFrom stem '${parsed.stem}' uses a ${parsed.mode} consume; ` +
1028
+ 'workdirFrom requires a plain consume');
1029
+ }
1030
+ }
974
1031
  // one writer per artifact: map produced singleton/collection stems to producers
975
1032
  const producerOf = new Map(); // stem -> step name
976
1033
  const collectionStems = new Set();
@@ -1098,40 +1155,40 @@ export function validateDef(def) {
1098
1155
  }
1099
1156
  }
1100
1157
  }
1101
- // W1-VALIDATE: worker:/command: shape rules (declarative executor dispatch).
1102
- // Only two hard requirements; any other worker value is fully opaque.
1158
+ // W1-VALIDATE: executor:/command: shape rules (declarative executor dispatch).
1159
+ // Only two hard requirements; any other executor value is fully opaque.
1103
1160
  for (const l of def.steps) {
1104
- const worker = l.worker ?? 'agent';
1105
- // Deliberately `l.worker === 'agent'` (explicit opt-in), NOT
1106
- // `(l.worker ?? 'agent') === 'agent'` — that stricter form would also
1161
+ const executor = l.executor ?? 'agent';
1162
+ // Deliberately `l.executor === 'agent'` (explicit opt-in), NOT
1163
+ // `(l.executor ?? 'agent') === 'agent'` — that stricter form would also
1107
1164
  // catch every default-agent step that already gets away with an empty
1108
1165
  // body today (e.g. calls:-adjacent or generator-only fixtures), breaking
1109
- // existing defs that never write `worker:` at all. Scoping the check to
1110
- // an EXPLICIT `worker: agent` keeps every pre-existing def byte-for-byte
1111
- // unaffected while still catching "someone opted into the agent worker
1166
+ // existing defs that never write `executor:` at all. Scoping the check to
1167
+ // an EXPLICIT `executor: agent` keeps every pre-existing def byte-for-byte
1168
+ // unaffected while still catching "someone opted into the agent executor
1112
1169
  // type and forgot a body".
1113
- if (l.worker === 'agent' && l.body.trim() === '') {
1114
- errors.push(`step '${l.name}' has worker 'agent' but no body: (an agent step needs a prompt)`);
1170
+ if (l.executor === 'agent' && l.body.trim() === '') {
1171
+ errors.push(`step '${l.name}' has executor 'agent' but no body: (an agent step needs a prompt)`);
1115
1172
  }
1116
- else if (worker === 'command') {
1173
+ else if (executor === 'command') {
1117
1174
  if (l.command === undefined) {
1118
- errors.push(`step '${l.name}' has worker 'command' but no command:`);
1175
+ errors.push(`step '${l.name}' has executor 'command' but no command:`);
1119
1176
  }
1120
1177
  }
1121
- // any other worker value: opaque, no body/command requirement
1178
+ // any other executor value: opaque, no body/command requirement
1122
1179
  }
1123
- // W1-VALIDATE: workers: def-level allow-list typo guard. Applied AFTER the
1124
- // per-step `worker` default (?? 'agent') — a def declaring `workers:
1180
+ // W1-VALIDATE: executors: def-level allow-list typo guard. Applied AFTER the
1181
+ // per-step `executor` default (?? 'agent') — a def declaring `executors:
1125
1182
  // [command]` (deliberately excluding 'agent') still fails a step that omits
1126
- // `worker:` entirely, since its effective worker is 'agent'. This is
1183
+ // `executor:` entirely, since its effective executor is 'agent'. This is
1127
1184
  // intended (the list is exhaustive once declared), documented in
1128
1185
  // docs/authoring.md.
1129
- if (def.workers && def.workers.length > 0) {
1130
- const allowed = new Set(def.workers);
1186
+ if (def.executors && def.executors.length > 0) {
1187
+ const allowed = new Set(def.executors);
1131
1188
  for (const l of def.steps) {
1132
- const worker = l.worker ?? 'agent';
1133
- if (!allowed.has(worker)) {
1134
- errors.push(`step '${l.name}' has worker '${worker}' but workflow '${def.name}'.workers does not list it`);
1189
+ const executor = l.executor ?? 'agent';
1190
+ if (!allowed.has(executor)) {
1191
+ errors.push(`step '${l.name}' has executor '${executor}' but workflow '${def.name}'.executors does not list it`);
1135
1192
  }
1136
1193
  }
1137
1194
  }
@@ -1436,6 +1493,71 @@ export function lintDef(def) {
1436
1493
  : [];
1437
1494
  return { errors, warnings };
1438
1495
  }
1496
+ // ---- WS-6: scope-aware calls: target resolution -------------------------------
1497
+ /** Stable private-map key for one installed coordinate at one verified digest. */
1498
+ export function digestScopedCallsTargetKey(digest, target) {
1499
+ return `${digest}/${target}`;
1500
+ }
1501
+ /**
1502
+ * Resolve one `calls:` edge to the def map KEY that edge names, honoring CAS
1503
+ * bundle scope. Returns `undefined` when nothing matches (the caller reports the
1504
+ * `does not exist` error, or skips, as it always has).
1505
+ *
1506
+ * THREE CASES, checked in this order:
1507
+ *
1508
+ * 1. `target` contains `/` — an explicitly QUALIFIED reference. When the
1509
+ * calling definition carries a lock digest for that exact target, prefer the
1510
+ * digest-scoped coordinate alias registered by the CAS loader. That preserves
1511
+ * an already-running parent's selection when a project coordinate later
1512
+ * shadows the global coordinate it originally pinned. Without a reachable
1513
+ * pinned alias, use the direct coordinate/package key so new lookups retain
1514
+ * project-over-global precedence and the engine can surface a pin mismatch.
1515
+ * Never fall back to a bare lookup: an author who wrote a qualified name
1516
+ * asked for one specific definition.
1517
+ *
1518
+ * 2. `from` carries a `bundleDigest` (it was loaded out of a CAS bundle) and
1519
+ * `target` is bare — resolve SIBLING-FIRST: search the map for a def whose
1520
+ * `bundleDigest` equals `from.bundleDigest` and whose own name equals
1521
+ * `target`. This is what makes `calls: build` inside bundle A bind to
1522
+ * bundle A's `build` and never to bundle B's.
1523
+ *
1524
+ * 3. Otherwise — today's plain flat-map lookup, byte-for-byte unchanged. Every
1525
+ * def loaded off the filesystem or handed to `createEngine({ defs })` has
1526
+ * no `bundleDigest`, so it takes this path exactly as before.
1527
+ *
1528
+ * A bare `calls:` from a CAS def that names NO sibling falls through case 2 into
1529
+ * case 3, so an out-of-bundle name still resolves if the flat map holds it and
1530
+ * still produces the existing `does not exist` error if it does not.
1531
+ */
1532
+ function resolveCallsTargetKey(defs, target, from) {
1533
+ if (target.includes('/')) {
1534
+ const pinnedDigest = from.bundleLock?.[target];
1535
+ if (pinnedDigest !== undefined) {
1536
+ const pinnedKey = digestScopedCallsTargetKey(pinnedDigest, target);
1537
+ if (defs.has(pinnedKey))
1538
+ return pinnedKey;
1539
+ }
1540
+ return defs.has(target) ? target : undefined;
1541
+ }
1542
+ if (from.bundleDigest !== undefined) {
1543
+ for (const [key, candidate] of defs) {
1544
+ if (candidate.bundleDigest === from.bundleDigest && candidate.name === target)
1545
+ return key;
1546
+ }
1547
+ }
1548
+ return defs.has(target) ? target : undefined;
1549
+ }
1550
+ /**
1551
+ * The def a `calls:` edge names, honoring CAS bundle scope — the value form of
1552
+ * {@link resolveCallsTargetKey}. This is the ONE resolution rule shared by
1553
+ * load-time validation (`finalizeDefs`), cycle detection, and the engine's
1554
+ * spawn path, so a def that validates at load time is the same def the engine
1555
+ * spawns at runtime.
1556
+ */
1557
+ export function resolveCallsTarget(defs, target, from) {
1558
+ const key = resolveCallsTargetKey(defs, target, from);
1559
+ return key === undefined ? undefined : defs.get(key);
1560
+ }
1439
1561
  // ---- M2-CYCLE: cross-def calls-cycle detection --------------------------------
1440
1562
  /**
1441
1563
  * Walk the calls: edges in a flat def map and throw a DefError if any cycle exists.
@@ -1448,14 +1570,21 @@ function detectCallsCycles(defs) {
1448
1570
  const WHITE = 0, GREY = 1, BLACK = 2;
1449
1571
  const color = new Map([...defs.keys()].map((k) => [k, WHITE]));
1450
1572
  const stack = [];
1573
+ // WS-6: the walk must key on RESOLVED identity, not on the bare `calls:` text.
1574
+ // Two installed bundles may each export a workflow named `build`; keying the
1575
+ // walk by that bare text would fuse them into one node and report a cycle that
1576
+ // does not exist. `resolveCallsTarget` maps (edge text, calling def) to the
1577
+ // exact map key the engine will spawn, so each bundle's `build` stays its own
1578
+ // node under its own qualified key.
1451
1579
  const visit = (name) => {
1452
1580
  color.set(name, GREY);
1453
1581
  stack.push(name);
1454
1582
  const def = defs.get(name);
1455
1583
  // Unique calls: edges from this def (multiple steps might call the same child)
1456
1584
  const callsEdges = new Set((def?.steps ?? []).filter((l) => l.calls).map((l) => l.calls));
1457
- for (const child of callsEdges) {
1458
- if (!defs.has(child))
1585
+ for (const edge of callsEdges) {
1586
+ const child = def === undefined ? undefined : resolveCallsTargetKey(defs, edge, def);
1587
+ if (child === undefined)
1459
1588
  continue; // missing-def error is reported separately in loadDefs
1460
1589
  const c = color.get(child) ?? WHITE;
1461
1590
  if (c === GREY) {
@@ -1550,35 +1679,26 @@ export function loadDefsUnfinalized(dir) {
1550
1679
  }
1551
1680
  return raw;
1552
1681
  }
1553
- /**
1554
- * Phase 2/3 of def loading, factored out so it is the ONE validator every
1555
- * public construction path shares — the filesystem `loadDefs` above AND the
1556
- * in-memory `createEngine({ defs })` factory path (REL-4). Given a raw def map
1557
- * (each def possibly still carrying `_includes`), it: expands each def's
1558
- * includes; runs the cross-def `calls:` checks (target existence, `callsInputs`
1559
- * key validity, exactly-one child output); runs `validateDef` per expanded def;
1560
- * and finally `detectCallsCycles` over the whole expanded map. Returns the
1561
- * expanded, validated map. Throws `DefError` on the first problem — the same
1562
- * messages, in the same order, the filesystem loader has always produced (this
1563
- * is a pure extraction of what used to live inline in `loadDefs`).
1564
- *
1565
- * A host wiring an `Engine` by hand with its own set can call this to get the
1566
- * same validation the factory and the loader apply. `expandIncludes` is a no-op
1567
- * for a def without `_includes` (the normal in-memory case), so passing a plain
1568
- * def map through is cheap and only adds the cross-def + cycle checks.
1569
- */
1570
- export function finalizeDefs(raw) {
1682
+ export function finalizeDefs(raw, options = {}) {
1571
1683
  const out = new Map();
1572
1684
  const resolver = (name) => raw.get(name);
1573
1685
  for (const [name, def] of raw) {
1574
1686
  const expanded = expandIncludes(def, resolver);
1575
1687
  // M2-VALIDATE cross-def: target-def existence + child input-key validity.
1576
1688
  // These cannot live in validateDef (pure per-def, no resolver) — same split as expandIncludes.
1689
+ //
1690
+ // WS-6: `calls:` targets resolve through `resolveCallsTarget` (scope-aware),
1691
+ // NOT through the plain `resolver` used for `include:` expansion above.
1692
+ // `include:` is a DIFFERENT edge kind and is deliberately left on the flat
1693
+ // lookup — this workstream is `calls:`-only.
1577
1694
  for (const l of expanded.steps) {
1578
1695
  if (!l.calls)
1579
1696
  continue;
1580
- const childDef = resolver(l.calls);
1697
+ const childDef = resolveCallsTarget(raw, l.calls, expanded);
1581
1698
  if (!childDef) {
1699
+ if (options.allowUnresolvedCalls === true
1700
+ || options.allowUnresolvedVersionedCalls?.has(l.calls) === true)
1701
+ continue;
1582
1702
  throw new DefError(`calls names workflow '${l.calls}' which does not exist`);
1583
1703
  }
1584
1704
  const childInputNames = new Set(childDef.inputs.map((i) => i.name));
@@ -13,6 +13,8 @@ import type { WorkflowStatus } from './model.ts';
13
13
  import type { SchemaIssue } from './schema.ts';
14
14
  import type { Store } from './store.ts';
15
15
  import type { Author, Fingerprint, Order, WorkflowDef } from './types.ts';
16
+ import { OrderResolver } from './order-resolver.ts';
17
+ import type { OrderInstructionSource, ResolvedInstructions } from './order-resolver.ts';
16
18
  export type { Order } from './types.ts';
17
19
  /**
18
20
  * F2: a typed refusal for a produced-value/input-value schema mismatch, thrown
@@ -38,6 +40,24 @@ export declare class SchemaRefusalError extends Error {
38
40
  gateFingerprint?: Fingerprint;
39
41
  constructor(inputName: string, issues: SchemaIssue[]);
40
42
  }
43
+ /**
44
+ * WS-6: a `calls:` step resolved to a child definition that is NOT the one the
45
+ * parent's own bundle pinned. Thrown from inside `provisionCallsChild`'s
46
+ * transaction, so the whole provisioning tx rolls back — no child row, no
47
+ * partial input sync — and `maintainCalls` converts it into a visible debt on
48
+ * the parent's `calls:` artifact (see `recordCallsDigestReject`). The failure
49
+ * mode this prevents is silent: without it, a newer install of the same package
50
+ * would let a running parent spawn a DIFFERENT workflow body than the one it was
51
+ * pinned against, and nothing would say so.
52
+ */
53
+ export declare class CallsPinError extends Error {
54
+ readonly name = "CallsPinError";
55
+ /** The `calls:` target text exactly as the parent def wrote it. */
56
+ readonly target: string;
57
+ /** Human-readable statement of which pin was violated and how. */
58
+ readonly detail: string;
59
+ constructor(target: string, detail: string);
60
+ }
41
61
  /**
42
62
  * §tick-deferred: an eligible firing the tick did NOT promote to an order, tagged
43
63
  * with why. `'in-flight'` — the step's task is already claimed by an open run;
@@ -45,11 +65,13 @@ export declare class SchemaRefusalError extends Error {
45
65
  * step's daily run allowance is exhausted (binding over parallel); `'parallel-cap'`
46
66
  * — the step's concurrency cap is the binding constraint. Always emitted by
47
67
  * `applySchedule` or `tick`; never alters which firings are selected or claimed.
48
- * `'label-mismatch'` (A2) — the tick caller passed a label filter that does not
49
- * intersect the step's declared labels, so a peer orchestrator serving other
50
- * labels leaves it for the matching caller.
68
+ * `'capability-mismatch'` (A2) — the tick caller passed a capability filter that does not
69
+ * intersect the step's declared capabilities, so a peer orchestrator serving other
70
+ * capabilities leaves it for the matching caller; `'workdir-unresolved'` — a
71
+ * workdirFrom path in a consumed artifact was missing, non-object, or not a
72
+ * non-empty string, so no order or run was emitted.
51
73
  */
52
- export type DeferredReason = 'in-flight' | 'cadence' | 'daily-budget' | 'parallel-cap' | 'label-mismatch';
74
+ export type DeferredReason = 'in-flight' | 'cadence' | 'daily-budget' | 'parallel-cap' | 'capability-mismatch' | 'workdir-unresolved';
53
75
  export interface DeferredFiring {
54
76
  step: string;
55
77
  key: string;
@@ -57,6 +79,8 @@ export interface DeferredFiring {
57
79
  inputs: string[];
58
80
  outputs: string[];
59
81
  reason: DeferredReason;
82
+ /** Readable detail for deferrals whose reason alone is not actionable. */
83
+ detail?: string;
60
84
  /**
61
85
  * §23.6.8 deep tick: which instance this deferred firing belongs to.
62
86
  * Convention — **absent = the ticked ROOT instance; present = the named
@@ -134,7 +158,19 @@ export interface CreateOpts {
134
158
  parentPath: string;
135
159
  };
136
160
  }
137
- export type DefResolver = (defName: string) => WorkflowDef;
161
+ /**
162
+ * Map a definition name to its `WorkflowDef`, or throw if there is none.
163
+ *
164
+ * WS-6 widened this with an OPTIONAL second parameter. `from` is the def that
165
+ * NAMED `defName` — supplied only by the `calls:` spawn path, where the naming
166
+ * def's own CAS bundle scope decides which `defName` a bare reference means (a
167
+ * bare `calls: build` inside bundle A must reach bundle A's `build`, never an
168
+ * unrelated `build` from bundle B). Because the parameter is optional, every
169
+ * existing single-argument resolver — including a host's hand-written one —
170
+ * keeps today's exact behavior with no change: a resolver that ignores `from`
171
+ * simply performs the flat lookup it always did.
172
+ */
173
+ export type DefResolver = (defName: string, from?: WorkflowDef) => WorkflowDef;
138
174
  /**
139
175
  * A push notification of a committed engine change, delivered to observers
140
176
  * registered via {@link Engine.subscribe}. Lets an in-process host react the
@@ -198,6 +234,15 @@ export interface ReapDetail {
198
234
  export declare class Engine {
199
235
  readonly store: Store;
200
236
  private readonly resolveDef;
237
+ /**
238
+ * The reference-mode instruction boundary (WP-B1): where an order's
239
+ * `defDigest` turns back into exact authored instructions. Injected when a
240
+ * host supplies a WP-A3-compatible source; otherwise a loaded-definition
241
+ * adapter that still emits and resolves reference orders (not a
242
+ * compatibility mode). Public read-only facade: {@link Engine.resolver}.
243
+ */
244
+ private readonly instructionSource;
245
+ readonly resolver: OrderResolver;
201
246
  private readonly reapTtlMs;
202
247
  private readonly maxLeaseMs;
203
248
  private readonly maxCallDepth;
@@ -221,6 +266,14 @@ export declare class Engine {
221
266
  onEvent?: EngineListener;
222
267
  /** Where a throwing listener's error goes (default: swallowed). */
223
268
  onListenerError?: (err: unknown, event: EngineEvent) => void;
269
+ /**
270
+ * WP-A3-compatible digest/instruction source (WP-B1 seam). When
271
+ * supplied, `buildOrder` takes definition digests from it and
272
+ * resolution reads its verified records; when absent, the engine
273
+ * builds a loaded-definition adapter (same reference-mode behavior,
274
+ * no legacy fallback).
275
+ */
276
+ instructionSource?: OrderInstructionSource;
224
277
  });
225
278
  /**
226
279
  * Register a synchronous observer of engine changes; returns an idempotent
@@ -367,6 +420,28 @@ export declare class Engine {
367
420
  * depth refusal anyway (identical outcome, no lost valid update to strand).
368
421
  */
369
422
  private recordCallsDepthReject;
423
+ /**
424
+ * WS-6: record a `calls:` PIN violation as a debt on the PARENT calls
425
+ * artifact. Same clean-stop mechanism as `recordCallsDepthReject` — mark the
426
+ * artifact `rejected` and stamp the current gate fingerprint so the STEP-2 F2
427
+ * guard skips re-attempts instead of crash-looping the same refusal every
428
+ * tick — with a different, actionable message.
429
+ *
430
+ * Kept as its OWN recorder rather than folded into `recordCallsDepthReject`:
431
+ * the two refusals differ in what they mean (a depth trip says the definition
432
+ * set has a cycle that bypassed load-time validation; a pin violation says the
433
+ * installed store no longer holds the version this parent was pinned against)
434
+ * and therefore in what an operator should do next. Merging them into one
435
+ * parameterized recorder would blur exactly the distinction the message exists
436
+ * to carry.
437
+ *
438
+ * Like the depth recorder, this one needs NO carry-and-compare gate guard: a
439
+ * pin violation is decided from immutable provenance (the parent's §28 pinned
440
+ * snapshot and the resolved child's bundle digest), not from the gate
441
+ * snapshot, so a refusal decided at time T stays valid at recording time no
442
+ * matter what moved concurrently.
443
+ */
444
+ private recordCallsDigestReject;
370
445
  /**
371
446
  * M2B: Maintain all `calls:` steps for a parent workflow.
372
447
  * Called at the top of tick (outside any tx) and as cascade-up prompt.
@@ -428,7 +503,7 @@ export declare class Engine {
428
503
  tick(workflow: string, opts?: {
429
504
  now?: number;
430
505
  deep?: boolean;
431
- labels?: string[];
506
+ capabilities?: string[];
432
507
  }): TickResult;
433
508
  /**
434
509
  * The recursive tick worker. Runs this instance's own maintain → reap →
@@ -501,9 +576,9 @@ export declare class Engine {
501
576
  private callsDescendTargets;
502
577
  /**
503
578
  * Per-step cadence + daily budget + parallel cap over the eligible firings.
504
- * A2: `labels` is the tick caller's optional claim filter — when non-empty, a
505
- * step whose own `labels` are also non-empty is only schedulable when the two
506
- * intersect; a disjoint step's firings are deferred as `'label-mismatch'`.
579
+ * A2: `capabilities` is the tick caller's optional claim filter — when non-empty, a
580
+ * step whose own `capabilities` are also non-empty is only schedulable when the two
581
+ * intersect; a disjoint step's firings are deferred as `'capability-mismatch'`.
507
582
  * Filtering here (before cadence/budget) means a mismatched firing never
508
583
  * consumes the caller's slots and never perturbs cadence math.
509
584
  */
@@ -544,7 +619,28 @@ export declare class Engine {
544
619
  private isClaimFresh;
545
620
  /** Claim a firing's lease via CAS, snapshot the fingerprint, open a run. */
546
621
  private claim;
622
+ /**
623
+ * Build the reference-mode order for a firing (WP-B1). Carries the pinned
624
+ * snapshot's `defDigest` plus routing/reference fields, dynamic `consumes`
625
+ * values, and dynamic `owes` feedback — but NEVER authored prompt or
626
+ * command text, and no `owes[].acceptance` (the lifecycle state is dynamic
627
+ * engine state, not instructions). The digest comes from the instruction
628
+ * source's identity for the exact `def` passed in — the pinned snapshot
629
+ * from `defFor(workflow)`, never a fresh name lookup — and that same
630
+ * snapshot is registered under the digest (a side effect of `digestOf`),
631
+ * so the order stays resolvable after the live definition map changes.
632
+ */
547
633
  private buildOrder;
634
+ /**
635
+ * Resolve an order's static instructions through the SAME `(defDigest,
636
+ * step, key)` boundary {@link Engine.resolver} uses: exact authored prompt
637
+ * and command bytes (plus source-owned acceptance when the source carries
638
+ * it), with the runtime placeholders materialized in the prompt. Purely a
639
+ * read — never mutates the stored/emitted order, and never re-embeds text
640
+ * on it. Throws `UnknownDefDigestError` when no verified record exists for
641
+ * the order's digest — before any caller can execute a prompt or command.
642
+ */
643
+ resolveOrder(order: Order): ResolvedInstructions;
548
644
  /**
549
645
  * Commit a singleton/map output green — or born-reject it if an input moved.
550
646
  *