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
@@ -9,11 +9,12 @@
9
9
  * (snapshotted on the run) against current input versions; a moved input
10
10
  * born-rejects the output instead of greening it.
11
11
  */
12
- import { elementPath, parseElement, sealPath, } from "./paths.js";
12
+ import { elementPath, parseElement, parseWorkdirFrom, sealPath, } from "./paths.js";
13
13
  import { collectionStem, computeFingerprint, eligibleFirings, fingerprintMatches, groupBlockingWinner, isGreen, judgeNameOf, maintainDecisions, pendingOwed, plainConsumes, requiredInputs, workflowStatus, } from "./model.js";
14
14
  import { summarizeIssues, validateValue } from "./schema.js";
15
15
  import { hashDef } from "./defs.js";
16
16
  import { localMidnightMs, nowMs, randId } from "./util.js";
17
+ import { createDefInstructionSource, OrderResolver } from "./order-resolver.js";
17
18
  const DEFAULT_REAP_TTL_MS = 2 * 60 * 60 * 1000; // 2h
18
19
  /**
19
20
  * REL-4: hard cap on `calls:` composition depth (root instance = depth 0), a
@@ -53,9 +54,87 @@ export class SchemaRefusalError extends Error {
53
54
  this.issues = issues;
54
55
  }
55
56
  }
57
+ /**
58
+ * WS-6: a `calls:` step resolved to a child definition that is NOT the one the
59
+ * parent's own bundle pinned. Thrown from inside `provisionCallsChild`'s
60
+ * transaction, so the whole provisioning tx rolls back — no child row, no
61
+ * partial input sync — and `maintainCalls` converts it into a visible debt on
62
+ * the parent's `calls:` artifact (see `recordCallsDigestReject`). The failure
63
+ * mode this prevents is silent: without it, a newer install of the same package
64
+ * would let a running parent spawn a DIFFERENT workflow body than the one it was
65
+ * pinned against, and nothing would say so.
66
+ */
67
+ export class CallsPinError extends Error {
68
+ name = 'CallsPinError';
69
+ /** The `calls:` target text exactly as the parent def wrote it. */
70
+ target;
71
+ /** Human-readable statement of which pin was violated and how. */
72
+ detail;
73
+ constructor(target, detail) {
74
+ super(`calls target '${target}' failed its pin check: ${detail}`);
75
+ this.target = target;
76
+ this.detail = detail;
77
+ }
78
+ }
79
+ /**
80
+ * WS-6: check that `childDef` is the definition the parent's own bundle pinned
81
+ * for the `calls:` target `target`. Returns `undefined` when the edge is fine,
82
+ * or a human-readable violation string.
83
+ *
84
+ * THREE CASES, and the FIRST two are the whole point of the check:
85
+ *
86
+ * 1. `target` is BARE and `parentDef` came from a CAS bundle
87
+ * (`parentDef.bundleDigest` is set). The pin is BUNDLE-digest equality: the
88
+ * v2 bundle format carries no per-workflow digest, and `assertLockCoverage`
89
+ * deliberately skips non-versioned refs, so a sibling's pin IS its
90
+ * containing bundle's own digest. `childDef.bundleDigest` must equal
91
+ * `parentDef.bundleDigest`.
92
+ *
93
+ * 2. `target` is an explicit `namespace/name@version` reference AND the parent
94
+ * bundle's manifest `lock` names it. The lock value is a canonical BUNDLE
95
+ * digest (`bundle.yaml.lock` validates lowercase 64-hex; `assertLockCoverage`
96
+ * requires an entry for every versioned target), so it is compared against
97
+ * `childDef.bundleDigest` — NOT against `defInstructionDigest`, which
98
+ * projects one definition and is a different digest kind entirely.
99
+ *
100
+ * 3. Everything else — a parent with no CAS provenance, or a versioned target
101
+ * with no lock entry reachable — is UNPINNED and passes. This is what keeps
102
+ * every filesystem def, every `owenloop add` def, and every legacy unpinned
103
+ * instance behaving exactly as before: no provenance, no check.
104
+ */
105
+ function callsPinViolation(parentDef, childDef, target) {
106
+ if (target.includes('/')) {
107
+ const pinned = parentDef.bundleLock?.[target];
108
+ if (pinned === undefined)
109
+ return undefined; // no lock entry reachable — unpinned
110
+ if (childDef.bundleDigest === undefined) {
111
+ return `parent bundle pins it to ${pinned} but the resolved definition carries no bundle provenance`;
112
+ }
113
+ if (childDef.bundleDigest !== pinned) {
114
+ return `parent bundle pins it to ${pinned} but the resolved definition comes from ${childDef.bundleDigest}`;
115
+ }
116
+ return undefined;
117
+ }
118
+ if (parentDef.bundleDigest === undefined)
119
+ return undefined; // parent not CAS-installed — unpinned
120
+ if (childDef.bundleDigest !== parentDef.bundleDigest) {
121
+ const found = childDef.bundleDigest ?? 'no bundle (a project-local or add-installed definition)';
122
+ return `a bare calls: target must be a sibling in the parent's own bundle ${parentDef.bundleDigest}, but it resolved to ${found}`;
123
+ }
124
+ return undefined;
125
+ }
56
126
  export class Engine {
57
127
  store;
58
128
  resolveDef;
129
+ /**
130
+ * The reference-mode instruction boundary (WP-B1): where an order's
131
+ * `defDigest` turns back into exact authored instructions. Injected when a
132
+ * host supplies a WP-A3-compatible source; otherwise a loaded-definition
133
+ * adapter that still emits and resolves reference orders (not a
134
+ * compatibility mode). Public read-only facade: {@link Engine.resolver}.
135
+ */
136
+ instructionSource;
137
+ resolver;
59
138
  reapTtlMs;
60
139
  maxLeaseMs;
61
140
  maxCallDepth;
@@ -66,6 +145,8 @@ export class Engine {
66
145
  constructor(store, resolveDef, opts = {}) {
67
146
  this.store = store;
68
147
  this.resolveDef = resolveDef;
148
+ this.instructionSource = opts.instructionSource ?? createDefInstructionSource();
149
+ this.resolver = new OrderResolver(this.instructionSource);
69
150
  this.reapTtlMs = opts.reapTtlMs ?? DEFAULT_REAP_TTL_MS;
70
151
  this.maxLeaseMs = opts.maxLeaseMs;
71
152
  this.maxCallDepth = opts.maxCallDepth ?? DEFAULT_MAX_CALL_DEPTH;
@@ -173,7 +254,7 @@ export class Engine {
173
254
  * orphan child row, no partial input sync — preserving the F2 contract; the
174
255
  * caller records it as a debt on the parent calls artifact.
175
256
  */
176
- provisionCallsChild(parentWf, step, callsStem, gateStems, now) {
257
+ provisionCallsChild(parentWf, parentDef, step, callsStem, gateStems, now) {
177
258
  // B2: the gate fingerprint of the exact in-tx snapshot the seed/re-provide
178
259
  // validation ran against. Captured fresh inside `run()` so a retry re-reads
179
260
  // it; carried out on a `SchemaRefusalError` so `recordCallsSchemaReject` can
@@ -210,7 +291,17 @@ export class Engine {
210
291
  let childDef;
211
292
  if (!child) {
212
293
  const childId = randId('wf');
213
- childDef = this.resolveDef(step.calls);
294
+ // WS-6: resolve IN THE PARENT'S SCOPE. `parentDef` is the parent's own
295
+ // §28 pin (defFor prefers `defSnapshot` over the live resolver), so a
296
+ // bare `calls:` from a def installed out of a CAS bundle binds to that
297
+ // same bundle's workflow — the version the parent was pinned against —
298
+ // and not to whatever a later install happened to name the same thing.
299
+ childDef = this.resolveDef(step.calls, parentDef);
300
+ // WS-6: and the resolved child must still be the PINNED one. See
301
+ // `callsPinViolation`.
302
+ const violation = callsPinViolation(parentDef, childDef, step.calls);
303
+ if (violation !== undefined)
304
+ throw new CallsPinError(step.calls, violation);
214
305
  const seedProvide = {};
215
306
  for (const [childInputName, parentArtifactName] of Object.entries(step.callsInputs ?? {})) {
216
307
  const parentArt = parentArts.get(parentArtifactName);
@@ -486,6 +577,49 @@ export class Engine {
486
577
  this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'reject' });
487
578
  this.fireSettled(parentWf);
488
579
  }
580
+ /**
581
+ * WS-6: record a `calls:` PIN violation as a debt on the PARENT calls
582
+ * artifact. Same clean-stop mechanism as `recordCallsDepthReject` — mark the
583
+ * artifact `rejected` and stamp the current gate fingerprint so the STEP-2 F2
584
+ * guard skips re-attempts instead of crash-looping the same refusal every
585
+ * tick — with a different, actionable message.
586
+ *
587
+ * Kept as its OWN recorder rather than folded into `recordCallsDepthReject`:
588
+ * the two refusals differ in what they mean (a depth trip says the definition
589
+ * set has a cycle that bypassed load-time validation; a pin violation says the
590
+ * installed store no longer holds the version this parent was pinned against)
591
+ * and therefore in what an operator should do next. Merging them into one
592
+ * parameterized recorder would blur exactly the distinction the message exists
593
+ * to carry.
594
+ *
595
+ * Like the depth recorder, this one needs NO carry-and-compare gate guard: a
596
+ * pin violation is decided from immutable provenance (the parent's §28 pinned
597
+ * snapshot and the resolved child's bundle digest), not from the gate
598
+ * snapshot, so a refusal decided at time T stays valid at recording time no
599
+ * matter what moved concurrently.
600
+ */
601
+ recordCallsDigestReject(parentWf, def, callsStem, gateStems, err, now) {
602
+ const text = `calls target '${err.target}' failed its pin check: ${err.detail}; `
603
+ + `the parent is pinned to the definition it was created against (§28), so this spawn was refused rather than `
604
+ + `run a different workflow body than the one that was pinned — reinstall the pinned bundle, or start a new `
605
+ + `parent instance against the current one`;
606
+ this.store.tx(() => {
607
+ const art = this.store.getArtifact(parentWf, callsStem);
608
+ if (!art)
609
+ return; // not yet materialized by pendingOwed — nothing to stamp
610
+ const gateArts = this.artMap(parentWf);
611
+ const fp = computeFingerprint(gateArts, gateStems);
612
+ this.store.putArtifact({
613
+ ...art,
614
+ acceptance: 'rejected',
615
+ fingerprint: fp,
616
+ reasons: [...art.reasons, reason('reject', 'structural', 'engine', text, art.version)],
617
+ });
618
+ this.settle(parentWf, def, now);
619
+ });
620
+ this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'reject' });
621
+ this.fireSettled(parentWf);
622
+ }
489
623
  /**
490
624
  * M2B: Maintain all `calls:` steps for a parent workflow.
491
625
  * Called at the top of tick (outside any tx) and as cascade-up prompt.
@@ -551,7 +685,7 @@ export class Engine {
551
685
  // schema-reject branch) instead of crash-looping every subsequent tick.
552
686
  let provision;
553
687
  try {
554
- provision = this.provisionCallsChild(parentWf, step, callsStem, gateStems, now);
688
+ provision = this.provisionCallsChild(parentWf, def, step, callsStem, gateStems, now);
555
689
  }
556
690
  catch (err) {
557
691
  if (err instanceof SchemaRefusalError) {
@@ -565,6 +699,15 @@ export class Engine {
565
699
  }
566
700
  continue;
567
701
  }
702
+ // WS-6: a pin violation is not a bug either — it means the installed
703
+ // store no longer holds the bundle this parent was pinned against. It
704
+ // becomes a visible debt on the PARENT calls artifact (never a silent
705
+ // divergent run, and never an uncaught throw that would take the whole
706
+ // tick down), and the STEP-2 F2 guard then stops the re-attempt loop.
707
+ if (err instanceof CallsPinError) {
708
+ this.recordCallsDigestReject(parentWf, def, callsStem, gateStems, err, now);
709
+ continue;
710
+ }
568
711
  throw err;
569
712
  }
570
713
  if (!provision)
@@ -806,7 +949,7 @@ export class Engine {
806
949
  * only this instance's own orders. See `TickResult` for the fold semantics.
807
950
  */
808
951
  tick(workflow, opts = {}) {
809
- return this.tickInternal(workflow, opts.now ?? nowMs(), opts.deep ?? true, opts.labels ?? [], new Set(), 0);
952
+ return this.tickInternal(workflow, opts.now ?? nowMs(), opts.deep ?? true, opts.capabilities ?? [], new Set(), 0);
810
953
  }
811
954
  /**
812
955
  * The recursive tick worker. Runs this instance's own maintain → reap →
@@ -847,7 +990,7 @@ export class Engine {
847
990
  * edge it hangs from. The guard is silent (no debt/reasons/events), mirroring
848
991
  * the abort discipline of `publishCallsGreen`/`provisionCallsChild`.
849
992
  */
850
- tickInternal(workflow, now, deep, labels, visited, depth, parentEdge) {
993
+ tickInternal(workflow, now, deep, capabilities, visited, depth, parentEdge) {
851
994
  if (depth > this.maxCallDepth) {
852
995
  throw new Error(`calls depth limit exceeded (maxCallDepth=${this.maxCallDepth}) ticking '${workflow}': `
853
996
  + `a calls: composition is deeper than the bound, which usually means a calls: cycle `
@@ -893,13 +1036,7 @@ export class Engine {
893
1036
  // Compute time facts for idle eligibility (clock-read boundary).
894
1037
  const timeFacts = this.computeTimeFacts(def, workflow, arts, now);
895
1038
  const firings = eligibleFirings(def, arts, timeFacts);
896
- const { selected, deferred } = this.applySchedule(workflow, def, firings, now, labels);
897
- // Clear alarm_at for any idle firing that was selected (consume the alarm).
898
- for (const f of selected) {
899
- if (f.cause === 'idle') {
900
- this.store.clearAlarm(workflow, f.step);
901
- }
902
- }
1039
+ const { selected, deferred } = this.applySchedule(workflow, def, firings, now, capabilities);
903
1040
  const orders = [];
904
1041
  const allDeferred = [...deferred];
905
1042
  for (const f of selected) {
@@ -910,7 +1047,14 @@ export class Engine {
910
1047
  d.index = f.index;
911
1048
  allDeferred.push(d);
912
1049
  }
1050
+ else if (claimed && typeof claimed === 'object' && 'deferred' in claimed) {
1051
+ allDeferred.push(claimed.deferred);
1052
+ }
913
1053
  else if (claimed) {
1054
+ // Consume an idle alarm only after the order and run are claimed. A
1055
+ // workdir-unresolved firing must retain its alarm so the next tick can retry.
1056
+ if (f.cause === 'idle')
1057
+ this.store.clearAlarm(workflow, f.step);
914
1058
  orders.push(claimed);
915
1059
  }
916
1060
  }
@@ -927,7 +1071,7 @@ export class Engine {
927
1071
  // subtree — do not tick grandchildren off a frame that issued nothing.
928
1072
  if (deep && !staleEdge) {
929
1073
  for (const { step, child } of this.callsDescendTargets(workflow, def)) {
930
- const cr = this.tickInternal(child.id, now, deep, labels, visited, depth + 1, {
1074
+ const cr = this.tickInternal(child.id, now, deep, capabilities, visited, depth + 1, {
931
1075
  parentWf: workflow,
932
1076
  step,
933
1077
  callsStem: step.produces[0].stem,
@@ -1001,13 +1145,13 @@ export class Engine {
1001
1145
  }
1002
1146
  /**
1003
1147
  * Per-step cadence + daily budget + parallel cap over the eligible firings.
1004
- * A2: `labels` is the tick caller's optional claim filter — when non-empty, a
1005
- * step whose own `labels` are also non-empty is only schedulable when the two
1006
- * intersect; a disjoint step's firings are deferred as `'label-mismatch'`.
1148
+ * A2: `capabilities` is the tick caller's optional claim filter — when non-empty, a
1149
+ * step whose own `capabilities` are also non-empty is only schedulable when the two
1150
+ * intersect; a disjoint step's firings are deferred as `'capability-mismatch'`.
1007
1151
  * Filtering here (before cadence/budget) means a mismatched firing never
1008
1152
  * consumes the caller's slots and never perturbs cadence math.
1009
1153
  */
1010
- applySchedule(workflow, def, firings, now, labels) {
1154
+ applySchedule(workflow, def, firings, now, capabilities) {
1011
1155
  const midnight = localMidnightMs(now);
1012
1156
  const selected = [];
1013
1157
  const deferred = [];
@@ -1021,13 +1165,13 @@ export class Engine {
1021
1165
  const stepFirings = firings.filter((f) => f.step === step.name);
1022
1166
  if (stepFirings.length === 0)
1023
1167
  continue;
1024
- // A2: caller label filter vs. step labels. Both non-empty and disjoint →
1168
+ // A2: caller capability filter vs. step capabilities. Both non-empty and disjoint →
1025
1169
  // this caller must not claim the step; defer every firing and skip it
1026
1170
  // before it touches cadence/budget/slot math.
1027
- if (labels.length > 0 && step.labels && step.labels.length > 0 &&
1028
- !step.labels.some((l) => labels.includes(l))) {
1171
+ if (capabilities.length > 0 && step.capabilities && step.capabilities.length > 0 &&
1172
+ !step.capabilities.some((l) => capabilities.includes(l))) {
1029
1173
  for (const f of stepFirings)
1030
- defer(f, 'label-mismatch');
1174
+ defer(f, 'capability-mismatch');
1031
1175
  continue;
1032
1176
  }
1033
1177
  const latest = this.store.latestRun(workflow, step.name);
@@ -1126,7 +1270,9 @@ export class Engine {
1126
1270
  // CONFLICT DO UPDATE, no history table), so the issued order is unrecoverable
1127
1271
  // later unless captured here; this persisted packet is the replay/eval/paper
1128
1272
  // trail record (buildOrder is deterministic modulo run id).
1129
- const order = this.buildOrder(def, workflow, runId, f, arts);
1273
+ const order = this.buildOrder(def, workflow, runId, f, arts, fp);
1274
+ if (typeof order === 'object' && 'deferred' in order)
1275
+ return order;
1130
1276
  // Stamp the run with the tick's clock so cadence/budget compare on one clock.
1131
1277
  this.store.insertRun(runId, { workflow, step: f.step, key: f.key, fingerprint: fp, order, ...(f.cause ? { cause: f.cause } : {}) }, now);
1132
1278
  this.store.putTask({
@@ -1140,7 +1286,18 @@ export class Engine {
1140
1286
  });
1141
1287
  return order;
1142
1288
  }
1143
- buildOrder(def, workflow, runId, f, arts) {
1289
+ /**
1290
+ * Build the reference-mode order for a firing (WP-B1). Carries the pinned
1291
+ * snapshot's `defDigest` plus routing/reference fields, dynamic `consumes`
1292
+ * values, and dynamic `owes` feedback — but NEVER authored prompt or
1293
+ * command text, and no `owes[].acceptance` (the lifecycle state is dynamic
1294
+ * engine state, not instructions). The digest comes from the instruction
1295
+ * source's identity for the exact `def` passed in — the pinned snapshot
1296
+ * from `defFor(workflow)`, never a fresh name lookup — and that same
1297
+ * snapshot is registered under the digest (a side effect of `digestOf`),
1298
+ * so the order stays resolvable after the live definition map changes.
1299
+ */
1300
+ buildOrder(def, workflow, runId, f, arts, consumedFingerprint) {
1144
1301
  const step = this.step(def, f.step);
1145
1302
  const consumes = {};
1146
1303
  for (const p of f.inputs) {
@@ -1148,11 +1305,61 @@ export class Engine {
1148
1305
  if (a?.value !== undefined)
1149
1306
  consumes[p] = a.value;
1150
1307
  }
1308
+ const unresolved = (detail) => {
1309
+ const deferred = {
1310
+ step: f.step,
1311
+ key: f.key,
1312
+ inputs: f.inputs,
1313
+ outputs: f.outputs,
1314
+ reason: 'workdir-unresolved',
1315
+ detail,
1316
+ };
1317
+ if (f.index !== undefined)
1318
+ deferred.index = f.index;
1319
+ return { deferred };
1320
+ };
1321
+ let resolvedWorkdir;
1322
+ if (step.workdirFrom !== undefined) {
1323
+ const parsed = parseWorkdirFrom(step.workdirFrom, step.consumes);
1324
+ if (!parsed) {
1325
+ return unresolved(`workdirFrom '${step.workdirFrom}': expected a consumed stem followed by a non-empty dotted value path`);
1326
+ }
1327
+ if (parsed.mode !== 'plain') {
1328
+ return unresolved(`workdirFrom '${step.workdirFrom}': source stem '${parsed.stem}' is not a plain consume`);
1329
+ }
1330
+ let value = consumes[parsed.stem];
1331
+ const segments = parsed.path.split('.');
1332
+ for (let i = 0; i < segments.length; i++) {
1333
+ const segment = segments[i];
1334
+ const pathAt = segments.slice(0, i + 1).join('.');
1335
+ if (value === undefined) {
1336
+ return unresolved(`workdirFrom '${step.workdirFrom}': value at '${pathAt}' is undefined`);
1337
+ }
1338
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) {
1339
+ return unresolved(`workdirFrom '${step.workdirFrom}': value at '${pathAt}' is not an object`);
1340
+ }
1341
+ if (!Object.prototype.hasOwnProperty.call(value, segment)) {
1342
+ return unresolved(`workdirFrom '${step.workdirFrom}': value at '${pathAt}' is undefined`);
1343
+ }
1344
+ value = value[segment];
1345
+ }
1346
+ if (typeof value !== 'string' || value.trim().length === 0) {
1347
+ return unresolved(`workdirFrom '${step.workdirFrom}': value at '${parsed.path}' must be a non-empty string`);
1348
+ }
1349
+ resolvedWorkdir = value;
1350
+ }
1351
+ else if (step.workdir !== undefined) {
1352
+ resolvedWorkdir = step.workdir;
1353
+ }
1354
+ // Digest registration is part of emitting an order. Keep it after dynamic
1355
+ // workdir resolution so an unresolved firing does not register an order
1356
+ // identity or reach the run insert below.
1357
+ const defDigest = this.instructionSource.digestOf(def);
1151
1358
  const owes = f.outputs.map((p) => {
1152
1359
  const a = arts.get(p);
1153
1360
  return {
1154
1361
  path: p,
1155
- acceptance: a?.acceptance ?? 'owed',
1362
+ version: a?.version ?? 0,
1156
1363
  judgmentRejects: a?.judgmentRejects ?? 0,
1157
1364
  schemaRejects: a?.schemaRejects ?? 0,
1158
1365
  reasons: a?.reasons ?? [],
@@ -1163,34 +1370,22 @@ export class Engine {
1163
1370
  workflow,
1164
1371
  step: f.step,
1165
1372
  key: f.key,
1373
+ defDigest,
1166
1374
  inputs: f.inputs,
1167
1375
  outputs: f.outputs,
1168
- prompt: substitute(step.body, {
1169
- WORKFLOW: workflow,
1170
- RUN: runId,
1171
- STEP: f.step,
1172
- KEY: f.key,
1173
- INDEX: f.index === undefined ? '' : String(f.index),
1174
- // Intentionally step-generic: a single firing can discharge multiple
1175
- // outputs (f.outputs) at once, so there is no single produce to
1176
- // resolve a per-produce maxAttempts override against here. This
1177
- // always reflects the step default even when individual produces
1178
- // override it (see model.ts effectiveMaxAttempts()).
1179
- MAX_ATTEMPTS: String(step.maxAttempts),
1180
- }),
1376
+ ...(resolvedWorkdir !== undefined ? { workdir: resolvedWorkdir } : {}),
1181
1377
  consumes,
1378
+ consumedFingerprint: { ...consumedFingerprint },
1182
1379
  owes,
1183
1380
  };
1184
1381
  if (f.index !== undefined)
1185
1382
  order.index = f.index;
1186
- if (step.workdir !== undefined)
1187
- order.workdir = step.workdir;
1188
1383
  if (step.model !== undefined)
1189
1384
  order.model = step.model;
1190
- if (step.worker !== undefined)
1191
- order.worker = step.worker;
1192
- if (step.command !== undefined)
1193
- order.command = step.command;
1385
+ if (step.executor !== undefined)
1386
+ order.worker = step.executor;
1387
+ if (step.judges !== undefined)
1388
+ order.judge = step.judges;
1194
1389
  if (step.spec !== undefined)
1195
1390
  order.spec = step.spec;
1196
1391
  if (step.x !== undefined)
@@ -1199,6 +1394,18 @@ export class Engine {
1199
1394
  order.cause = f.cause;
1200
1395
  return order;
1201
1396
  }
1397
+ /**
1398
+ * Resolve an order's static instructions through the SAME `(defDigest,
1399
+ * step, key)` boundary {@link Engine.resolver} uses: exact authored prompt
1400
+ * and command bytes (plus source-owned acceptance when the source carries
1401
+ * it), with the runtime placeholders materialized in the prompt. Purely a
1402
+ * read — never mutates the stored/emitted order, and never re-embeds text
1403
+ * on it. Throws `UnknownDefDigestError` when no verified record exists for
1404
+ * the order's digest — before any caller can execute a prompt or command.
1405
+ */
1406
+ resolveOrder(order) {
1407
+ return this.resolver.resolveOrder(order);
1408
+ }
1202
1409
  // ---- producer commits ------------------------------------------------------
1203
1410
  /**
1204
1411
  * Commit a singleton/map output green — or born-reject it if an input moved.
@@ -2526,9 +2733,6 @@ function nextIndex(arts, stem) {
2526
2733
  }
2527
2734
  return max + 1;
2528
2735
  }
2529
- function substitute(body, vars) {
2530
- return body.replace(/\$\{(\w+)\}/g, (m, k) => (k in vars ? vars[k] ?? '' : m));
2531
- }
2532
2736
  /** M2B: structural deep-equal, order-insensitive on object keys (artifact values are always JSON-shaped). */
2533
2737
  function deepEqual(a, b) {
2534
2738
  if (a === b)
@@ -21,6 +21,8 @@
21
21
  import { Engine } from './engine.ts';
22
22
  import type { EngineEvent, EngineListener } from './engine.ts';
23
23
  import type { Store } from './store.ts';
24
+ import { OrderResolver } from './order-resolver.ts';
25
+ import type { OrderInstructionSource } from './order-resolver.ts';
24
26
  import type { WorkflowDef } from './types.ts';
25
27
  export interface CreateEngineOpts {
26
28
  /**
@@ -63,12 +65,26 @@ export interface CreateEngineOpts {
63
65
  onEvent?: EngineListener;
64
66
  /** Where a throwing `onEvent`/subscriber's error goes (default: swallowed). */
65
67
  onListenerError?: (err: unknown, event: EngineEvent) => void;
68
+ /**
69
+ * WP-A3-compatible digest/instruction source (the WP-B1 seam). When
70
+ * supplied, emitted orders take their `defDigest` from this source and
71
+ * resolution reads its verified records; when absent, `createEngine`
72
+ * builds one loaded-definition resolver from the finalized def set —
73
+ * same reference-mode behavior, no legacy branch.
74
+ */
75
+ instructionSource?: OrderInstructionSource;
66
76
  }
67
77
  export interface CreatedEngine {
68
78
  engine: Engine;
69
79
  store: Store;
70
80
  /** The resolved definition set, so a host can introspect what was registered. */
71
81
  defs: Map<string, WorkflowDef>;
82
+ /**
83
+ * The reference-order resolver (WP-B1) — the one resolution path for
84
+ * emitted orders. Identical to `engine.resolver`; returned here so an
85
+ * embedder can resolve without holding the engine object.
86
+ */
87
+ resolver: OrderResolver;
72
88
  }
73
89
  /**
74
90
  * Open a store, resolve definitions, and return a wired `Engine` ready to
@@ -23,7 +23,8 @@ import { dirname, join } from 'node:path';
23
23
  import { Engine } from "./engine.js";
24
24
  import { openStore } from "./store.js";
25
25
  import { dbPathRefusingSymlink, mkdirRefusingSymlink } from "./util.js";
26
- import { finalizeDefs, loadDefs } from "./defs.js";
26
+ import { finalizeDefs, loadDefs, resolveCallsTarget } from "./defs.js";
27
+ import { createDefInstructionSource, OrderResolver } from "./order-resolver.js";
27
28
  /**
28
29
  * Open a store, resolve definitions, and return a wired `Engine` ready to
29
30
  * `createInstance` / `tick` / `green` / … . See `docs/embedding.md`.
@@ -74,12 +75,22 @@ export function createEngine(opts = {}) {
74
75
  mkdirSync(dirname(db), { recursive: true });
75
76
  }
76
77
  const store = openStore(db);
77
- const resolveDef = (name) => {
78
- const d = defs.get(name);
78
+ // WS-6: scope-aware, matching the CLI resolver. An embedder's in-memory def
79
+ // set carries no CAS provenance, so `resolveCallsTarget` takes its plain
80
+ // flat-map branch and behavior here is unchanged; the branch exists so an
81
+ // embedder that DOES hand in store-loaded defs gets the same sibling-first
82
+ // rule `finalizeDefs` already validated the set against.
83
+ const resolveDef = (name, from) => {
84
+ const d = from === undefined ? defs.get(name) : resolveCallsTarget(defs, name, from);
79
85
  if (!d)
80
86
  throw new Error(`unknown workflow definition '${name}'`);
81
87
  return d;
82
88
  };
89
+ // WP-B1: one resolver for reference orders, shared by the engine (emission)
90
+ // and returned to the embedder (resolution). Seeded with the finalized def
91
+ // set so their digests are registered up front; `buildOrder` re-registers
92
+ // each exact pinned snapshot it emits against.
93
+ const instructionSource = opts.instructionSource ?? createDefInstructionSource(defs.values());
83
94
  const engineOpts = {};
84
95
  if (opts.reapTtlMs !== undefined)
85
96
  engineOpts.reapTtlMs = opts.reapTtlMs;
@@ -91,6 +102,7 @@ export function createEngine(opts = {}) {
91
102
  engineOpts.onEvent = opts.onEvent;
92
103
  if (opts.onListenerError !== undefined)
93
104
  engineOpts.onListenerError = opts.onListenerError;
105
+ engineOpts.instructionSource = instructionSource;
94
106
  const engine = new Engine(store, resolveDef, engineOpts);
95
- return { engine, store, defs };
107
+ return { engine, store, defs, resolver: engine.resolver };
96
108
  }
@@ -0,0 +1,59 @@
1
+ /**
2
+ * `~/.owenloop/config.json` — the CONTROL plane's non-secret configuration file.
3
+ *
4
+ * Sole writer: `owenloop login` (`dispatchLogin` in `src/cli.ts`), which records
5
+ * the hub origin it just authenticated against here, best-effort, after the
6
+ * credential itself has already been stored. Sole reader: `owenloop mcp`'s
7
+ * origin ladder (`resolveMcpOrigin` in `src/mcp/serve.ts`), which needs to know
8
+ * which hub the operator is using WITHOUT enumerating the credential store —
9
+ * the store's `keychain` and `external` backends cannot be listed at all (see
10
+ * `listStoredHubOrigins` in `src/hub.ts`), so a value that lived only inside
11
+ * the credential vault would be unreadable to the server on the majority of
12
+ * real installs (macOS defaults to the keychain backend).
13
+ *
14
+ * This is deliberately a SEPARATE file from `src/work-settings.ts`'s
15
+ * `~/.config/owenloop/settings.json` (or `$XDG_CONFIG_HOME/owenloop/settings.json`
16
+ * when set). That file belongs to the EXECUTION plane: `owenloop setup` is its
17
+ * sole writer, and `owenloop work` role resolution and pre-commit verification
18
+ * are its readers. This file belongs to the CONTROL plane: `owenloop login`
19
+ * writes it, `owenloop mcp` reads it. Nothing reconciles the two if they
20
+ * disagree — e.g. after `owenloop login --hub A` followed by
21
+ * `owenloop setup --hub B` — and that is an accepted cost, not an oversight:
22
+ * the two files answer different questions ("what hub does an agent shift run
23
+ * against" vs. "what hub does the human's MCP session talk to") for two
24
+ * independently-evolving call paths, and forcing one file to answer both would
25
+ * couple them for no benefit. This file is also HOME-rooted, not XDG-aware,
26
+ * unlike `settings.json`: `owenloop mcp` is a human-facing control-plane
27
+ * process, and there is no separate "XDG vs. HOME" precedence to resolve here
28
+ * — the caller supplies `home` directly (see `globalConfigPath`), mirroring
29
+ * how `src/cli.ts`'s `workflowHome` resolves the same value.
30
+ *
31
+ * Never holds a secret: `hub` is an origin URL, nothing else. A read failure
32
+ * of any kind (file absent, invalid JSON, wrong shape, blank `hub`, or a
33
+ * `hub` value that does not normalize to a valid http(s) origin) is reported
34
+ * as `null`, never thrown — this file is one rung of a fallback ladder
35
+ * (`resolveMcpOrigin`), and a corrupt or half-written config must not be able
36
+ * to crash `owenloop mcp` at startup; the ladder simply falls through to the
37
+ * next rung instead.
38
+ */
39
+ /** The shape of `~/.owenloop/config.json`. `version` is reserved for a future migration. */
40
+ export interface GlobalConfig {
41
+ version: 1;
42
+ hub: string;
43
+ }
44
+ /** `<home>/.owenloop/config.json` — `home` is the caller-resolved `HOME`/`USERPROFILE` value. */
45
+ export declare function globalConfigPath(home: string): string;
46
+ /**
47
+ * Read and validate `path`. Returns `null` — never throws — when the file is
48
+ * absent, is not valid JSON, is not a JSON object, its `hub` field is
49
+ * missing, non-string, or blank, or `hub` does not normalize to a valid
50
+ * http(s) origin (`normalizeOrigin`, `src/hub.ts` — e.g. `"not a url"` or a
51
+ * bare hostname with no scheme). Callers treat `null` as "this rung has
52
+ * nothing to offer" and fall through to the next one. The `hub` on a non-null
53
+ * return is always normalized (scheme required, trailing slash/path
54
+ * stripped) — the same guarantee every other rung of `resolveMcpOrigin`
55
+ * provides, so callers never need to re-normalize what this returns.
56
+ */
57
+ export declare function readGlobalConfig(path: string): GlobalConfig | null;
58
+ /** Write `config` to `path`, creating its parent directory if needed. Atomic (see `writeFileAtomic`). */
59
+ export declare function writeGlobalConfig(path: string, config: GlobalConfig): void;