owenloop 0.5.0 → 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 (211) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +137 -35
  3. package/bin/owenloop.mjs +49 -1
  4. package/dist/packages/work/src/agent/brief.d.ts +8 -4
  5. package/dist/packages/work/src/agent/brief.js +7 -3
  6. package/dist/packages/work/src/agent/loop.d.ts +13 -7
  7. package/dist/packages/work/src/agent/loop.js +136 -9
  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/bundle/cache.d.ts +7 -5
  11. package/dist/packages/work/src/bundle/cache.js +20 -6
  12. package/dist/packages/work/src/bundle/fetch.d.ts +7 -5
  13. package/dist/packages/work/src/bundle/fetch.js +27 -7
  14. package/dist/packages/work/src/bundle/types.d.ts +8 -4
  15. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  16. package/dist/packages/work/src/consumed-verifier.js +205 -0
  17. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  18. package/dist/packages/work/src/exec/instructions.js +323 -0
  19. package/dist/packages/work/src/exec/loop.d.ts +12 -1
  20. package/dist/packages/work/src/exec/loop.js +137 -20
  21. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  22. package/dist/packages/work/src/exec/payload.js +54 -0
  23. package/dist/packages/work/src/exec/receipt.d.ts +9 -6
  24. package/dist/packages/work/src/exec/receipt.js +12 -1
  25. package/dist/packages/work/src/exec/runner.d.ts +7 -1
  26. package/dist/packages/work/src/exec/runner.js +74 -3
  27. package/dist/packages/work/src/harness/child-env.js +7 -0
  28. package/dist/packages/work/src/harness/claude.d.ts +20 -8
  29. package/dist/packages/work/src/harness/claude.js +260 -58
  30. package/dist/packages/work/src/harness/codex.d.ts +5 -4
  31. package/dist/packages/work/src/harness/codex.js +169 -41
  32. package/dist/packages/work/src/harness/contract.d.ts +36 -11
  33. package/dist/packages/work/src/harness/fake.js +1 -0
  34. package/dist/packages/work/src/harness/jsonrpc-stdio.js +7 -0
  35. package/dist/packages/work/src/harness/permissions.d.ts +16 -3
  36. package/dist/packages/work/src/harness/permissions.js +102 -13
  37. package/dist/packages/work/src/harness/session-store.d.ts +27 -9
  38. package/dist/packages/work/src/harness/session-store.js +271 -67
  39. package/dist/packages/work/src/hold/mcp.d.ts +25 -5
  40. package/dist/packages/work/src/hold/mcp.js +126 -11
  41. package/dist/packages/work/src/hub/client.d.ts +2 -1
  42. package/dist/packages/work/src/hub/client.js +14 -1
  43. package/dist/packages/work/src/hub/types.d.ts +69 -33
  44. package/dist/packages/work/src/hub/types.js +8 -10
  45. package/dist/packages/work/src/mcp/server.js +1 -1
  46. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  47. package/dist/packages/work/src/owenloop-bin.js +18 -0
  48. package/dist/packages/work/src/roles/agent-run.d.ts +12 -6
  49. package/dist/packages/work/src/roles/agent-run.js +116 -34
  50. package/dist/packages/work/src/roles/exec.d.ts +8 -0
  51. package/dist/packages/work/src/roles/exec.js +27 -2
  52. package/dist/packages/work/src/roles/hold.d.ts +4 -0
  53. package/dist/packages/work/src/roles/hold.js +44 -5
  54. package/dist/packages/work/src/roles/lint.d.ts +3 -4
  55. package/dist/packages/work/src/roles/lint.js +41 -7
  56. package/dist/packages/work/src/roles/settings.js +5 -0
  57. package/dist/packages/work/src/roles/shift.d.ts +1 -0
  58. package/dist/packages/work/src/roles/shift.js +23 -1
  59. package/dist/packages/work/src/settings/settings.d.ts +17 -1
  60. package/dist/packages/work/src/settings/settings.js +39 -0
  61. package/dist/packages/work/src/shift/loop.d.ts +14 -3
  62. package/dist/packages/work/src/shift/loop.js +447 -164
  63. package/dist/packages/work/src/shift/protocol.d.ts +4 -0
  64. package/dist/packages/work/src/shift/runtime.d.ts +2 -0
  65. package/dist/packages/work/src/shift/runtime.js +66 -3
  66. package/dist/packages/work/src/shift/spawn.d.ts +41 -18
  67. package/dist/packages/work/src/shift/spawn.js +89 -31
  68. package/dist/packages/work/src/shift/state.d.ts +53 -51
  69. package/dist/packages/work/src/shift/state.js +325 -102
  70. package/dist/packages/work/src/submit-proof.d.ts +36 -0
  71. package/dist/packages/work/src/submit-proof.js +93 -0
  72. package/dist/src/add.d.ts +64 -259
  73. package/dist/src/add.js +81 -615
  74. package/dist/src/archive.d.ts +97 -0
  75. package/dist/src/archive.js +591 -0
  76. package/dist/src/bundle/index.d.ts +64 -0
  77. package/dist/src/bundle/index.js +508 -0
  78. package/dist/src/bundle/manifest.d.ts +50 -0
  79. package/dist/src/bundle/manifest.js +435 -0
  80. package/dist/src/bundle/runtime.d.ts +26 -0
  81. package/dist/src/bundle/runtime.js +64 -0
  82. package/dist/src/bundle/tar.d.ts +62 -0
  83. package/dist/src/bundle/tar.js +238 -0
  84. package/dist/src/bundle/types.d.ts +105 -0
  85. package/dist/src/bundle/types.js +21 -0
  86. package/dist/src/cli.d.ts +90 -20
  87. package/dist/src/cli.js +2407 -365
  88. package/dist/src/credentials.d.ts +4 -3
  89. package/dist/src/credentials.js +21 -19
  90. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  91. package/dist/src/crypto/allowed-signers.js +307 -0
  92. package/dist/src/crypto/canonical.d.ts +8 -0
  93. package/dist/src/crypto/canonical.js +92 -0
  94. package/dist/src/crypto/chain.d.ts +65 -0
  95. package/dist/src/crypto/chain.js +377 -0
  96. package/dist/src/crypto/dsse.d.ts +209 -0
  97. package/dist/src/crypto/dsse.js +282 -0
  98. package/dist/src/crypto/enrollment.d.ts +78 -0
  99. package/dist/src/crypto/enrollment.js +186 -0
  100. package/dist/src/crypto/index.d.ts +48 -0
  101. package/dist/src/crypto/index.js +44 -0
  102. package/dist/src/crypto/keys.d.ts +258 -0
  103. package/dist/src/crypto/keys.js +908 -0
  104. package/dist/src/crypto/org-root.d.ts +33 -0
  105. package/dist/src/crypto/org-root.js +78 -0
  106. package/dist/src/crypto/origin-rules.d.ts +56 -0
  107. package/dist/src/crypto/origin-rules.js +143 -0
  108. package/dist/src/crypto/policy-floor.d.ts +98 -0
  109. package/dist/src/crypto/policy-floor.js +353 -0
  110. package/dist/src/crypto/records.d.ts +316 -0
  111. package/dist/src/crypto/records.js +157 -0
  112. package/dist/src/crypto/scope.d.ts +49 -0
  113. package/dist/src/crypto/scope.js +83 -0
  114. package/dist/src/crypto/ssh.d.ts +171 -0
  115. package/dist/src/crypto/ssh.js +396 -0
  116. package/dist/src/crypto/submission.d.ts +33 -0
  117. package/dist/src/crypto/submission.js +47 -0
  118. package/dist/src/crypto/trust-roots.d.ts +29 -0
  119. package/dist/src/crypto/trust-roots.js +39 -0
  120. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  121. package/dist/src/crypto/verify-consumed.js +259 -0
  122. package/dist/src/crypto/verify-origin.d.ts +50 -0
  123. package/dist/src/crypto/verify-origin.js +151 -0
  124. package/dist/src/crypto/verify-publication.d.ts +60 -0
  125. package/dist/src/crypto/verify-publication.js +150 -0
  126. package/dist/src/defs.d.ts +24 -1
  127. package/dist/src/defs.js +145 -25
  128. package/dist/src/engine.d.ts +99 -3
  129. package/dist/src/engine.js +238 -34
  130. package/dist/src/factory.d.ts +16 -0
  131. package/dist/src/factory.js +16 -4
  132. package/dist/src/global-config.d.ts +59 -0
  133. package/dist/src/global-config.js +84 -0
  134. package/dist/src/hub.d.ts +75 -21
  135. package/dist/src/hub.js +123 -40
  136. package/dist/src/index.d.ts +17 -2
  137. package/dist/src/index.js +20 -2
  138. package/dist/src/install.d.ts +538 -0
  139. package/dist/src/install.js +1981 -0
  140. package/dist/src/lock.d.ts +15 -57
  141. package/dist/src/lock.js +251 -143
  142. package/dist/src/mcp/serve.d.ts +46 -22
  143. package/dist/src/mcp/serve.js +167 -44
  144. package/dist/src/mcp/server.js +12 -1
  145. package/dist/src/model.d.ts +15 -0
  146. package/dist/src/model.js +111 -1
  147. package/dist/src/order-resolver.d.ts +184 -0
  148. package/dist/src/order-resolver.js +252 -0
  149. package/dist/src/package-version.d.ts +10 -0
  150. package/dist/src/package-version.js +42 -0
  151. package/dist/src/paths.d.ts +14 -1
  152. package/dist/src/paths.js +18 -0
  153. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  154. package/dist/src/schemas/index.d.ts +1416 -0
  155. package/dist/src/schemas/index.js +31 -0
  156. package/dist/src/schemas/order.v1.schema.json +106 -0
  157. package/dist/src/schemas/origin.v1.schema.json +68 -0
  158. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  159. package/dist/src/schemas/publication.v1.schema.json +31 -0
  160. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  161. package/dist/src/schemas/submission.v1.schema.json +61 -0
  162. package/dist/src/store/def-source.d.ts +52 -0
  163. package/dist/src/store/def-source.js +335 -0
  164. package/dist/src/store/index-file.d.ts +69 -0
  165. package/dist/src/store/index-file.js +151 -0
  166. package/dist/src/store/index.d.ts +27 -0
  167. package/dist/src/store/index.js +22 -0
  168. package/dist/src/store/ingestor.d.ts +43 -0
  169. package/dist/src/store/ingestor.js +211 -0
  170. package/dist/src/store/install.d.ts +228 -0
  171. package/dist/src/store/install.js +555 -0
  172. package/dist/src/store/instruction-source.d.ts +49 -0
  173. package/dist/src/store/instruction-source.js +298 -0
  174. package/dist/src/store/origin-evidence.d.ts +21 -0
  175. package/dist/src/store/origin-evidence.js +66 -0
  176. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  177. package/dist/src/store/pre-commit-verifier.js +418 -0
  178. package/dist/src/store/resolve.d.ts +138 -0
  179. package/dist/src/store/resolve.js +363 -0
  180. package/dist/src/store/types.d.ts +288 -0
  181. package/dist/src/store/types.js +356 -0
  182. package/dist/src/types.d.ts +45 -11
  183. package/dist/src/untar.d.ts +8 -23
  184. package/dist/src/untar.js +10 -136
  185. package/docs/agent-runner.md +86 -0
  186. package/docs/authoring.md +57 -6
  187. package/docs/bundles.md +250 -0
  188. package/docs/cli.md +1171 -97
  189. package/docs/crypto.md +816 -0
  190. package/docs/design.md +342 -20
  191. package/docs/embedding.md +132 -25
  192. package/docs/wire-contracts.md +380 -0
  193. package/package.json +6 -1
  194. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  195. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  196. package/plugins/claude-code/plugin/.mcp.json +14 -0
  197. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  198. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  199. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  200. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  201. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  202. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  203. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  204. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  205. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  206. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  207. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  208. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  209. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  210. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  211. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -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;
package/dist/src/defs.js CHANGED
@@ -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
@@ -40,7 +40,7 @@ const RAW_JUDGE_KEYS = ['name', 'body', 'bodyFile', 'model', 'inputs', 'cadence'
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',
43
+ 'workdir', 'workdirFrom', 'terminal', 'effect', 'on', 'idleAfter', 'body', 'bodyFile',
44
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;
@@ -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,6 +793,11 @@ 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
803
  if (j.executor !== undefined)
@@ -877,6 +897,8 @@ 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
904
  if (rl.executor !== 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();
@@ -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;
@@ -47,9 +67,11 @@ export declare class SchemaRefusalError extends Error {
47
67
  * `applySchedule` or `tick`; never alters which firings are selected or claimed.
48
68
  * `'capability-mismatch'` (A2) — the tick caller passed a capability filter that does not
49
69
  * intersect the step's declared capabilities, so a peer orchestrator serving other
50
- * capabilities leaves it for the matching caller.
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' | 'capability-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.
@@ -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
  *