owenloop 0.5.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (229) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/README.md +144 -35
  3. package/bin/owenloop.mjs +49 -1
  4. package/dist/packages/work/src/agent/brief.d.ts +29 -4
  5. package/dist/packages/work/src/agent/brief.js +49 -4
  6. package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
  7. package/dist/packages/work/src/agent/capability-model.js +148 -0
  8. package/dist/packages/work/src/agent/loop.d.ts +56 -7
  9. package/dist/packages/work/src/agent/loop.js +166 -9
  10. package/dist/packages/work/src/bundle/cache.d.ts +7 -5
  11. package/dist/packages/work/src/bundle/cache.js +20 -6
  12. package/dist/packages/work/src/bundle/fetch.d.ts +7 -5
  13. package/dist/packages/work/src/bundle/fetch.js +27 -7
  14. package/dist/packages/work/src/bundle/types.d.ts +8 -4
  15. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  16. package/dist/packages/work/src/consumed-verifier.js +205 -0
  17. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  18. package/dist/packages/work/src/exec/instructions.js +323 -0
  19. package/dist/packages/work/src/exec/loop.d.ts +29 -1
  20. package/dist/packages/work/src/exec/loop.js +313 -35
  21. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  22. package/dist/packages/work/src/exec/payload.js +54 -0
  23. package/dist/packages/work/src/exec/receipt.d.ts +9 -6
  24. package/dist/packages/work/src/exec/receipt.js +12 -1
  25. package/dist/packages/work/src/exec/runner.d.ts +7 -1
  26. package/dist/packages/work/src/exec/runner.js +84 -3
  27. package/dist/packages/work/src/harness/child-env.js +7 -0
  28. package/dist/packages/work/src/harness/claude.d.ts +20 -8
  29. package/dist/packages/work/src/harness/claude.js +260 -58
  30. package/dist/packages/work/src/harness/codex.d.ts +5 -4
  31. package/dist/packages/work/src/harness/codex.js +169 -41
  32. package/dist/packages/work/src/harness/contract.d.ts +36 -11
  33. package/dist/packages/work/src/harness/fake.js +1 -0
  34. package/dist/packages/work/src/harness/jsonrpc-stdio.js +7 -0
  35. package/dist/packages/work/src/harness/permissions.d.ts +16 -3
  36. package/dist/packages/work/src/harness/permissions.js +102 -13
  37. package/dist/packages/work/src/harness/session-store.d.ts +30 -10
  38. package/dist/packages/work/src/harness/session-store.js +317 -89
  39. package/dist/packages/work/src/hold/mcp.d.ts +25 -5
  40. package/dist/packages/work/src/hold/mcp.js +134 -12
  41. package/dist/packages/work/src/hub/client.d.ts +8 -1
  42. package/dist/packages/work/src/hub/client.js +15 -1
  43. package/dist/packages/work/src/hub/types.d.ts +137 -33
  44. package/dist/packages/work/src/hub/types.js +8 -10
  45. package/dist/packages/work/src/mcp/server.js +1 -1
  46. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  47. package/dist/packages/work/src/owenloop-bin.js +18 -0
  48. package/dist/packages/work/src/roles/agent-run.d.ts +12 -6
  49. package/dist/packages/work/src/roles/agent-run.js +115 -34
  50. package/dist/packages/work/src/roles/exec.d.ts +8 -0
  51. package/dist/packages/work/src/roles/exec.js +27 -2
  52. package/dist/packages/work/src/roles/hold.d.ts +6 -0
  53. package/dist/packages/work/src/roles/hold.js +83 -13
  54. package/dist/packages/work/src/roles/lint.d.ts +3 -4
  55. package/dist/packages/work/src/roles/lint.js +41 -7
  56. package/dist/packages/work/src/roles/settings.js +19 -2
  57. package/dist/packages/work/src/roles/shift.d.ts +1 -0
  58. package/dist/packages/work/src/roles/shift.js +36 -2
  59. package/dist/packages/work/src/settings/settings.d.ts +70 -1
  60. package/dist/packages/work/src/settings/settings.js +90 -4
  61. package/dist/packages/work/src/shift/logretention.d.ts +253 -0
  62. package/dist/packages/work/src/shift/logretention.js +407 -0
  63. package/dist/packages/work/src/shift/logsink.d.ts +14 -0
  64. package/dist/packages/work/src/shift/logsink.js +98 -0
  65. package/dist/packages/work/src/shift/loop.d.ts +32 -4
  66. package/dist/packages/work/src/shift/loop.js +687 -166
  67. package/dist/packages/work/src/shift/protocol.d.ts +128 -1
  68. package/dist/packages/work/src/shift/protocol.js +14 -0
  69. package/dist/packages/work/src/shift/runtime.d.ts +16 -0
  70. package/dist/packages/work/src/shift/runtime.js +291 -5
  71. package/dist/packages/work/src/shift/server.d.ts +13 -0
  72. package/dist/packages/work/src/shift/server.js +61 -36
  73. package/dist/packages/work/src/shift/spawn.d.ts +115 -19
  74. package/dist/packages/work/src/shift/spawn.js +234 -30
  75. package/dist/packages/work/src/shift/state.d.ts +76 -49
  76. package/dist/packages/work/src/shift/state.js +350 -103
  77. package/dist/packages/work/src/shift/truncate.d.ts +35 -0
  78. package/dist/packages/work/src/shift/truncate.js +73 -0
  79. package/dist/packages/work/src/submit-proof.d.ts +61 -0
  80. package/dist/packages/work/src/submit-proof.js +119 -0
  81. package/dist/packages/work/src/submit-value.d.ts +48 -0
  82. package/dist/packages/work/src/submit-value.js +118 -0
  83. package/dist/packages/work/src/usage.d.ts +1 -1
  84. package/dist/packages/work/src/usage.js +11 -0
  85. package/dist/src/add.d.ts +64 -259
  86. package/dist/src/add.js +81 -615
  87. package/dist/src/archive.d.ts +97 -0
  88. package/dist/src/archive.js +591 -0
  89. package/dist/src/bundle/index.d.ts +64 -0
  90. package/dist/src/bundle/index.js +508 -0
  91. package/dist/src/bundle/manifest.d.ts +50 -0
  92. package/dist/src/bundle/manifest.js +435 -0
  93. package/dist/src/bundle/runtime.d.ts +26 -0
  94. package/dist/src/bundle/runtime.js +64 -0
  95. package/dist/src/bundle/tar.d.ts +62 -0
  96. package/dist/src/bundle/tar.js +238 -0
  97. package/dist/src/bundle/types.d.ts +105 -0
  98. package/dist/src/bundle/types.js +21 -0
  99. package/dist/src/capabilities.d.ts +93 -0
  100. package/dist/src/capabilities.js +101 -0
  101. package/dist/src/cli.d.ts +90 -20
  102. package/dist/src/cli.js +2421 -374
  103. package/dist/src/credentials.d.ts +4 -3
  104. package/dist/src/credentials.js +21 -19
  105. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  106. package/dist/src/crypto/allowed-signers.js +307 -0
  107. package/dist/src/crypto/canonical.d.ts +8 -0
  108. package/dist/src/crypto/canonical.js +92 -0
  109. package/dist/src/crypto/chain.d.ts +65 -0
  110. package/dist/src/crypto/chain.js +377 -0
  111. package/dist/src/crypto/dsse.d.ts +209 -0
  112. package/dist/src/crypto/dsse.js +282 -0
  113. package/dist/src/crypto/enrollment.d.ts +78 -0
  114. package/dist/src/crypto/enrollment.js +186 -0
  115. package/dist/src/crypto/index.d.ts +48 -0
  116. package/dist/src/crypto/index.js +44 -0
  117. package/dist/src/crypto/keys.d.ts +258 -0
  118. package/dist/src/crypto/keys.js +908 -0
  119. package/dist/src/crypto/org-root.d.ts +33 -0
  120. package/dist/src/crypto/org-root.js +78 -0
  121. package/dist/src/crypto/origin-rules.d.ts +56 -0
  122. package/dist/src/crypto/origin-rules.js +143 -0
  123. package/dist/src/crypto/policy-floor.d.ts +98 -0
  124. package/dist/src/crypto/policy-floor.js +353 -0
  125. package/dist/src/crypto/records.d.ts +319 -0
  126. package/dist/src/crypto/records.js +168 -0
  127. package/dist/src/crypto/scope.d.ts +49 -0
  128. package/dist/src/crypto/scope.js +83 -0
  129. package/dist/src/crypto/ssh.d.ts +171 -0
  130. package/dist/src/crypto/ssh.js +396 -0
  131. package/dist/src/crypto/submission.d.ts +33 -0
  132. package/dist/src/crypto/submission.js +47 -0
  133. package/dist/src/crypto/trust-roots.d.ts +29 -0
  134. package/dist/src/crypto/trust-roots.js +39 -0
  135. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  136. package/dist/src/crypto/verify-consumed.js +259 -0
  137. package/dist/src/crypto/verify-origin.d.ts +50 -0
  138. package/dist/src/crypto/verify-origin.js +151 -0
  139. package/dist/src/crypto/verify-publication.d.ts +60 -0
  140. package/dist/src/crypto/verify-publication.js +150 -0
  141. package/dist/src/defs.d.ts +24 -1
  142. package/dist/src/defs.js +335 -27
  143. package/dist/src/engine.d.ts +211 -6
  144. package/dist/src/engine.js +459 -59
  145. package/dist/src/factory.d.ts +16 -0
  146. package/dist/src/factory.js +16 -4
  147. package/dist/src/global-config.d.ts +59 -0
  148. package/dist/src/global-config.js +84 -0
  149. package/dist/src/hub.d.ts +102 -32
  150. package/dist/src/hub.js +147 -58
  151. package/dist/src/index.d.ts +19 -2
  152. package/dist/src/index.js +23 -2
  153. package/dist/src/install.d.ts +538 -0
  154. package/dist/src/install.js +1981 -0
  155. package/dist/src/lock.d.ts +15 -57
  156. package/dist/src/lock.js +251 -143
  157. package/dist/src/mcp/serve.d.ts +46 -22
  158. package/dist/src/mcp/serve.js +174 -44
  159. package/dist/src/mcp/server.js +12 -1
  160. package/dist/src/model.d.ts +51 -0
  161. package/dist/src/model.js +157 -1
  162. package/dist/src/order-resolver.d.ts +184 -0
  163. package/dist/src/order-resolver.js +252 -0
  164. package/dist/src/package-version.d.ts +10 -0
  165. package/dist/src/package-version.js +42 -0
  166. package/dist/src/paths.d.ts +14 -1
  167. package/dist/src/paths.js +18 -0
  168. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  169. package/dist/src/schemas/index.d.ts +1433 -0
  170. package/dist/src/schemas/index.js +31 -0
  171. package/dist/src/schemas/order.v1.schema.json +120 -0
  172. package/dist/src/schemas/origin.v1.schema.json +68 -0
  173. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  174. package/dist/src/schemas/publication.v1.schema.json +31 -0
  175. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  176. package/dist/src/schemas/submission.v1.schema.json +61 -0
  177. package/dist/src/store/def-source.d.ts +52 -0
  178. package/dist/src/store/def-source.js +335 -0
  179. package/dist/src/store/index-file.d.ts +69 -0
  180. package/dist/src/store/index-file.js +151 -0
  181. package/dist/src/store/index.d.ts +27 -0
  182. package/dist/src/store/index.js +22 -0
  183. package/dist/src/store/ingestor.d.ts +43 -0
  184. package/dist/src/store/ingestor.js +211 -0
  185. package/dist/src/store/install.d.ts +228 -0
  186. package/dist/src/store/install.js +555 -0
  187. package/dist/src/store/instruction-source.d.ts +49 -0
  188. package/dist/src/store/instruction-source.js +298 -0
  189. package/dist/src/store/origin-evidence.d.ts +21 -0
  190. package/dist/src/store/origin-evidence.js +66 -0
  191. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  192. package/dist/src/store/pre-commit-verifier.js +418 -0
  193. package/dist/src/store/resolve.d.ts +138 -0
  194. package/dist/src/store/resolve.js +363 -0
  195. package/dist/src/store/types.d.ts +288 -0
  196. package/dist/src/store/types.js +356 -0
  197. package/dist/src/store.d.ts +33 -1
  198. package/dist/src/store.js +57 -4
  199. package/dist/src/types.d.ts +146 -12
  200. package/dist/src/untar.d.ts +8 -23
  201. package/dist/src/untar.js +10 -136
  202. package/docs/agent-runner.md +86 -0
  203. package/docs/authoring.md +64 -6
  204. package/docs/bundles.md +350 -0
  205. package/docs/cli.md +1298 -106
  206. package/docs/crypto.md +832 -0
  207. package/docs/design.md +342 -20
  208. package/docs/embedding.md +132 -25
  209. package/docs/shift-logs.md +642 -0
  210. package/docs/wire-contracts.md +395 -0
  211. package/package.json +6 -1
  212. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  213. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  214. package/plugins/claude-code/plugin/.mcp.json +14 -0
  215. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  216. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  217. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  218. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  219. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  220. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  221. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  222. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  223. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  224. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  225. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  226. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  227. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  228. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  229. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
@@ -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,9 +23,12 @@ 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
+ // The separator lives with composition/matching (capabilities.ts); the parser
30
+ // only enforces that an AUTHORED name never contains it.
31
+ import { MODIFIER_SEPARATOR } from "./capabilities.js";
29
32
  /** Hand-maintained key allowlist for RawInput — kept next to the interface so
30
33
  * the two can't silently drift (§27 unknown-key rejection). */
31
34
  const RAW_INPUT_KEYS = ['name', 'producer', 'seedOwed', 'schema'];
@@ -35,13 +38,14 @@ const RAW_PRODUCE_KEYS = ['name', 'schema', 'judges', 'maxAttempts', 'maxSchemaF
35
38
  * fields, so it gets its own allowlist rather than folding into
36
39
  * RAW_PRODUCE_KEYS (§27 unknown-key rejection). */
37
40
  const RAW_GROUP_KEYS = ['group', 'mode', 'of'];
38
- const RAW_JUDGE_KEYS = ['name', 'body', 'bodyFile', 'model', 'inputs', 'cadence', 'maxRunsPerDay', 'executor', 'command', 'spec'];
41
+ const RAW_JUDGE_KEYS = ['name', 'body', 'bodyFile', 'model', 'inputs', 'cadence', 'maxRunsPerDay', 'executor', 'command', 'spec', 'capabilities'];
39
42
  /** Keys valid on a normal (non-calls:, non-include:) step entry. */
40
43
  const RAW_STEP_KEYS = [
41
44
  'name', 'consumes', 'produces', 'generates', 'invalidates', 'cadence',
42
45
  'maxRunsPerDay', 'parallel', 'maxAttempts', 'maxSchemaFailures', 'model',
43
- 'workdir', 'terminal', 'effect', 'on', 'idleAfter', 'body', 'bodyFile',
46
+ 'workdir', 'workdirFrom', 'terminal', 'effect', 'on', 'idleAfter', 'body', 'bodyFile',
44
47
  'calls', 'reapTtl', 'capabilities', 'maxLease', 'x', 'executor', 'command', 'spec',
48
+ 'escalation',
45
49
  ];
46
50
  /** Keys valid on a calls: step entry — a DIFFERENT (smaller) shape than RawStep;
47
51
  * the `calls:` key is what routes an entry here instead of RAW_STEP_KEYS. */
@@ -49,7 +53,7 @@ const RAW_CALLS_KEYS = ['name', 'calls', 'inputs', 'produces'];
49
53
  /** Keys valid on an include: directive entry — the `include:` key is the
50
54
  * discriminator that routes an entry here instead of RAW_STEP_KEYS/RAW_CALLS_KEYS. */
51
55
  const RAW_INCLUDE_KEYS = ['include', 'as', 'inputs'];
52
- const RAW_DEF_KEYS = ['name', 'title', 'description', 'inputs', 'steps', 'outputs', 'invariants', 'engine', 'x', 'executors'];
56
+ const RAW_DEF_KEYS = ['name', 'title', 'description', 'inputs', 'steps', 'outputs', 'invariants', 'engine', 'x', 'executors', 'modifiers'];
53
57
  // ---- defaults ----------------------------------------------------------------
54
58
  const DEFAULTS = {
55
59
  cadence: '0s',
@@ -84,6 +88,75 @@ function asStringArray(v, ctx) {
84
88
  }
85
89
  return v;
86
90
  }
91
+ /**
92
+ * A routing capability as an author may write it: no separator, no surrounding
93
+ * whitespace, non-empty.
94
+ *
95
+ * Deliberately NOT a full charset rule. Capability names are opaque routing
96
+ * labels shared with a hub whose own validation is length + non-empty + no
97
+ * `personal:` prefix; imposing a charset here would reject names that already
98
+ * bind successfully today. The one new restriction is the reserved separator.
99
+ */
100
+ function assertAuthoredCapability(value, ctx) {
101
+ if (value.trim().length === 0) {
102
+ throw new DefError(`${ctx}: capability names must not be empty or whitespace`);
103
+ }
104
+ if (value.includes(MODIFIER_SEPARATOR)) {
105
+ throw new DefError(`${ctx}: capability '${value}' must not contain '${MODIFIER_SEPARATOR}' — ` +
106
+ 'the suffix position is reserved for the modifier the engine composes at offer time ' +
107
+ "(a run carrying 'deep' turns the authored capability 'wise' into 'wise:deep')");
108
+ }
109
+ }
110
+ /**
111
+ * Parse the def-level `modifiers:` block into a validated, order-insensitive
112
+ * set of plain names.
113
+ *
114
+ * Order is NOT preserved as meaning: the list is a vocabulary, and nothing in
115
+ * the engine compares two modifiers or treats one as higher than another. The
116
+ * array shape is only YAML's way of writing a set.
117
+ */
118
+ function parseModifiers(v, ctx) {
119
+ const values = asStringArray(v, ctx);
120
+ if (values.length === 0) {
121
+ throw new DefError(`${ctx} must list at least one modifier, or be omitted entirely`);
122
+ }
123
+ const seen = new Set();
124
+ for (const value of values) {
125
+ if (value.trim().length === 0) {
126
+ throw new DefError(`${ctx}: modifier names must not be empty or whitespace`);
127
+ }
128
+ if (value.includes(MODIFIER_SEPARATOR)) {
129
+ throw new DefError(`${ctx}: modifier '${value}' must not contain '${MODIFIER_SEPARATOR}' — ` +
130
+ 'it is the separator the engine composes with');
131
+ }
132
+ if (seen.has(value))
133
+ throw new DefError(`${ctx}: duplicate modifier '${value}'`);
134
+ seen.add(value);
135
+ }
136
+ return values;
137
+ }
138
+ /** Parse a step's `escalation:` block. Cross-checks against the def's declared
139
+ * modifier set and the step's effective maxAttempts happen in `validateDef`,
140
+ * which is the first place that sees the whole def. */
141
+ function parseEscalation(v, ctx) {
142
+ if (typeof v !== 'object' || v === null || Array.isArray(v)) {
143
+ throw new DefError(`${ctx} must be a mapping of { after, modifier }`);
144
+ }
145
+ const raw = v;
146
+ assertNoUnknownKeys(raw, ['after', 'modifier'], ctx);
147
+ if (raw['after'] === undefined)
148
+ throw new DefError(`${ctx} must set 'after'`);
149
+ if (raw['modifier'] === undefined)
150
+ throw new DefError(`${ctx} must set 'modifier'`);
151
+ const after = asNumber(raw['after'], 0, `${ctx}.after`);
152
+ if (!Number.isInteger(after) || after < 1) {
153
+ throw new DefError(`${ctx}.after must be a positive integer (rejection count that triggers the escalated re-offer)`);
154
+ }
155
+ const modifier = asString(raw['modifier'], `${ctx}.modifier`);
156
+ if (modifier.trim().length === 0)
157
+ throw new DefError(`${ctx}.modifier must not be empty`);
158
+ return { after, modifier };
159
+ }
87
160
  function asNumber(v, fallback, ctx) {
88
161
  if (v === undefined)
89
162
  return fallback;
@@ -269,6 +342,15 @@ function parseJudges(v, ctx, baseDir) {
269
342
  judge.command = asString(raw.command, `judge '${name}'.command`);
270
343
  if (raw.spec !== undefined)
271
344
  judge.spec = asExtension(raw.spec, `judge '${name}'.spec`);
345
+ if (raw.capabilities !== undefined) {
346
+ const caps = asStringArray(raw.capabilities, `judge '${name}'.capabilities`);
347
+ if (caps.length === 0) {
348
+ throw new DefError(`judge '${name}'.capabilities must not be empty — omit the key to inherit the producing step's capabilities`);
349
+ }
350
+ for (const cap of caps)
351
+ assertAuthoredCapability(cap, `judge '${name}'.capabilities`);
352
+ judge.capabilities = caps;
353
+ }
272
354
  return judge;
273
355
  });
274
356
  }
@@ -576,6 +658,8 @@ export function buildDef(raw, source, baseDir) {
576
658
  def.x = asExtension(r.x, `workflow '${name}'.x`);
577
659
  if (r.executors !== undefined)
578
660
  def.executors = asStringArray(r.executors, `workflow '${name}'.executors`);
661
+ if (r.modifiers !== undefined)
662
+ def.modifiers = parseModifiers(r.modifiers, `workflow '${name}'.modifiers`);
579
663
  return def;
580
664
  }
581
665
  // ---- Mode 1 expand helpers (M1-EXPAND) ----------------------------------------
@@ -626,6 +710,14 @@ function prefixStep(step, prefix) {
626
710
  // judges: marker names a local stem (unlike calls:, which names an external
627
711
  // workflow) — it must be prefixed to keep pointing at the (now-prefixed) produce.
628
712
  const newJudges = step.judges !== undefined ? prefixStem(step.judges) : undefined;
713
+ // workdirFrom names a local consumed stem followed by a dotted value path.
714
+ // Prefix only the stem; the value path is a field path inside the consumed value.
715
+ let newWorkdirFrom = step.workdirFrom;
716
+ if (step.workdirFrom !== undefined) {
717
+ const parsed = parseWorkdirFrom(step.workdirFrom, step.consumes);
718
+ if (parsed)
719
+ newWorkdirFrom = `${prefixStem(parsed.stem)}.${parsed.path}`;
720
+ }
629
721
  const result = {
630
722
  ...step,
631
723
  name: prefixStem(step.name),
@@ -633,12 +725,19 @@ function prefixStep(step, prefix) {
633
725
  produces: newProduces,
634
726
  invalidates: newInvalidates,
635
727
  };
728
+ // Each include alias is an independent materialization. Clone the opaque
729
+ // extension carrier so nested values cannot leak mutations across aliases or
730
+ // back into the resolved child definition. Preserve true absence.
731
+ if (step.x !== undefined)
732
+ result.x = structuredClone(step.x);
636
733
  if (newGenerates !== undefined)
637
734
  result.generates = newGenerates;
638
735
  if (newEffect !== undefined)
639
736
  result.effect = newEffect;
640
737
  if (newJudges !== undefined)
641
738
  result.judges = newJudges;
739
+ if (newWorkdirFrom !== undefined)
740
+ result.workdirFrom = newWorkdirFrom;
642
741
  return result;
643
742
  }
644
743
  /**
@@ -757,7 +856,7 @@ export function parseDef(raw, source, baseDir) {
757
856
  * an ordinary step, because judge orders flow through the normal
758
857
  * eligibleFirings → applySchedule → claim → buildOrder pipeline (§7.1).
759
858
  */
760
- function synthesizeJudgeSteps(producerStepName, pat, producerConsumeStems) {
859
+ function synthesizeJudgeSteps(producerStepName, pat, producerConsumeStems, producerX, producerCapabilities) {
761
860
  if (!pat.judges || pat.judges.length === 0)
762
861
  return [];
763
862
  return pat.judges.map((j) => {
@@ -778,6 +877,22 @@ function synthesizeJudgeSteps(producerStepName, pat, producerConsumeStems) {
778
877
  maxSchemaFailures: DEFAULTS.maxSchemaFailures,
779
878
  body: j.body,
780
879
  };
880
+ // Every native judge executes under the producer's complete opaque extension
881
+ // carrier. Clone per judge so neither producer nor sibling mutations can
882
+ // alter another synthesized step. Absence stays absence: no empty x bag.
883
+ if (producerX !== undefined)
884
+ step.x = structuredClone(producerX);
885
+ // Routing: an explicit judge `capabilities:` wins; otherwise the judge
886
+ // INHERITS the producer's. Without inheritance every synthesized judge
887
+ // would be capability-silent, and a capability-silent step bypasses the
888
+ // claim filter entirely — any polling crew could claim the judge that
889
+ // gates work routed deliberately to one crew. Copied, not shared, so a
890
+ // later mutation of either step cannot reach the other (same contract as
891
+ // the `x` clone above).
892
+ if (j.capabilities !== undefined)
893
+ step.capabilities = [...j.capabilities];
894
+ else if (producerCapabilities !== undefined)
895
+ step.capabilities = [...producerCapabilities];
781
896
  if (j.model !== undefined)
782
897
  step.model = j.model;
783
898
  if (j.executor !== undefined)
@@ -877,6 +992,8 @@ function buildStep(rl, i, baseDir) {
877
992
  };
878
993
  if (rl.workdir !== undefined)
879
994
  step.workdir = asString(rl.workdir, `step '${name}'.workdir`);
995
+ if (rl.workdirFrom !== undefined)
996
+ step.workdirFrom = asString(rl.workdirFrom, `step '${name}'.workdirFrom`);
880
997
  if (rl.model !== undefined)
881
998
  step.model = asString(rl.model, `step '${name}'.model`);
882
999
  if (rl.executor !== undefined)
@@ -933,9 +1050,14 @@ function buildStep(rl, i, baseDir) {
933
1050
  // any caller), mirroring the groups.length > 0 pattern below.
934
1051
  if (rl.capabilities !== undefined) {
935
1052
  const ls = asStringArray(rl.capabilities, `step '${name}'.capabilities`);
1053
+ for (const cap of ls)
1054
+ assertAuthoredCapability(cap, `step '${name}'.capabilities`);
936
1055
  if (ls.length > 0)
937
1056
  step.capabilities = ls;
938
1057
  }
1058
+ if (rl.escalation !== undefined) {
1059
+ step.escalation = parseEscalation(rl.escalation, `step '${name}'.escalation`);
1060
+ }
939
1061
  // A3: per-step max total lease lifetime (duration string, same as reapTtl).
940
1062
  if (rl.maxLease !== undefined) {
941
1063
  step.maxLeaseMs = parseDurationMs(asString(rl.maxLease, `step '${name}'.maxLease`));
@@ -948,7 +1070,7 @@ function buildStep(rl, i, baseDir) {
948
1070
  }
949
1071
  }
950
1072
  const producerConsumeStems = consumes.map((c) => c.stem);
951
- const judgeSteps = producesPatterns.flatMap((p) => synthesizeJudgeSteps(name, p, producerConsumeStems));
1073
+ const judgeSteps = producesPatterns.flatMap((p) => synthesizeJudgeSteps(name, p, producerConsumeStems, step.x, step.capabilities));
952
1074
  return [step, ...judgeSteps];
953
1075
  }
954
1076
  // ---- validation --------------------------------------------------------------
@@ -971,6 +1093,41 @@ export function validateDef(def) {
971
1093
  for (const dup of [...inputNames].filter((n) => stepNames.has(n))) {
972
1094
  errors.push(`'${dup}' is both an input and a step name`);
973
1095
  }
1096
+ for (const l of def.steps) {
1097
+ if (l.workdir === undefined && l.workdirFrom === undefined)
1098
+ continue;
1099
+ if (l.workdir !== undefined && l.workdirFrom !== undefined) {
1100
+ errors.push(`step '${l.name}': workdir and workdirFrom are mutually exclusive; use one`);
1101
+ continue;
1102
+ }
1103
+ if (l.workdirFrom === undefined)
1104
+ continue;
1105
+ const raw = l.workdirFrom.trim();
1106
+ const bareConsume = l.consumes.find((c) => c.stem === raw);
1107
+ if (bareConsume) {
1108
+ errors.push(`step '${l.name}': workdirFrom must use '<consumedStem>.<dotted.path>' with a non-empty value path`);
1109
+ continue;
1110
+ }
1111
+ const firstDot = raw.indexOf('.');
1112
+ const valuePath = firstDot >= 0 ? raw.slice(firstDot + 1) : '';
1113
+ if (firstDot <= 0 || valuePath.length === 0) {
1114
+ errors.push(`step '${l.name}': workdirFrom must use '<consumedStem>.<dotted.path>' with a non-empty value path`);
1115
+ continue;
1116
+ }
1117
+ // Security boundary: a workdirFrom value becomes a filesystem path. The
1118
+ // source stem must be a plain consumed artifact so its value has passed the
1119
+ // engine's consume-side verification gate before a worker can cd into it.
1120
+ const parsed = parseWorkdirFrom(raw, l.consumes);
1121
+ if (!parsed) {
1122
+ const stem = raw.slice(0, firstDot);
1123
+ errors.push(`step '${l.name}': workdirFrom stem '${stem}' is not in consumes; ` +
1124
+ 'a step may only take its workdir from an artifact it consumes');
1125
+ }
1126
+ else if (parsed.mode !== 'plain') {
1127
+ errors.push(`step '${l.name}': workdirFrom stem '${parsed.stem}' uses a ${parsed.mode} consume; ` +
1128
+ 'workdirFrom requires a plain consume');
1129
+ }
1130
+ }
974
1131
  // one writer per artifact: map produced singleton/collection stems to producers
975
1132
  const producerOf = new Map(); // stem -> step name
976
1133
  const collectionStems = new Set();
@@ -1246,6 +1403,94 @@ export function validateDef(def) {
1246
1403
  }
1247
1404
  }
1248
1405
  }
1406
+ // ---- routing modifiers and escalation ------------------------------------
1407
+ //
1408
+ // Three separate rules, each with its own precondition. They are grouped
1409
+ // because they all read `def.modifiers`, not because they are one check.
1410
+ //
1411
+ // R1 escalation.modifier must be a member of the def's declared set, and
1412
+ // a step may not carry `escalation:` at all in a def that declares no
1413
+ // `modifiers:` — there is no target vocabulary for it to draw from.
1414
+ // R2 escalation.after must be strictly less than the effective maxAttempts
1415
+ // of EVERY produce on the step. At judgmentRejects >= maxAttempts the
1416
+ // engine freezes the artifact (`model.ts` isStalled), so a rule
1417
+ // authored at or past that threshold re-offers a step that can never
1418
+ // run again. Taking the MINIMUM across produces is the conservative
1419
+ // reading: the step is dead as soon as its shortest-fused produce
1420
+ // freezes, whatever the others allow.
1421
+ // R3 in a def that declares `modifiers:`, every command step must author
1422
+ // `capabilities`. A capability-silent step bypasses the claim filter
1423
+ // (`engine.ts` A2) entirely, so any polling crew could claim it —
1424
+ // and, under composition, it would never receive a modifier suffix
1425
+ // either, silently opting out of the routing the def just declared.
1426
+ //
1427
+ // SCOPED DELIBERATELY to modifier-declaring defs. The plan document
1428
+ // states this rule unconditionally, but every def that predates
1429
+ // modifiers (examples/workflows/command-executor.yaml among them) has
1430
+ // capability-silent command steps, and the same document promises
1431
+ // "defs without `modifiers:` run exactly as today". Opting into the
1432
+ // new routing vocabulary is what turns the stricter rule on.
1433
+ const declaredModifiers = new Set(def.modifiers ?? []);
1434
+ for (const l of def.steps) {
1435
+ if (l.escalation === undefined)
1436
+ continue;
1437
+ if (declaredModifiers.size === 0) {
1438
+ errors.push(`step '${l.name}': escalation is set but workflow '${def.name}' declares no modifiers:; ` +
1439
+ 'escalation.modifier must name a declared modifier');
1440
+ }
1441
+ else if (!declaredModifiers.has(l.escalation.modifier)) {
1442
+ errors.push(`step '${l.name}': escalation.modifier '${l.escalation.modifier}' is not in workflow ` +
1443
+ `'${def.name}'.modifiers (${[...declaredModifiers].join(', ')})`);
1444
+ }
1445
+ // An escalated re-offer is the same step's capabilities composed with the
1446
+ // target modifier. A step with no capabilities composes nothing, so the
1447
+ // re-offer would be byte-identical to the original offer: a rule that can
1448
+ // never route anywhere new.
1449
+ if (l.capabilities === undefined || l.capabilities.length === 0) {
1450
+ errors.push(`step '${l.name}': escalation is set but the step authors no capabilities; ` +
1451
+ 'an escalated re-offer composes <capability>:<modifier>, so there is nothing to escalate');
1452
+ }
1453
+ // The rule is REACHABILITY: at least one owed output must be able to sit at
1454
+ // `after` judgment rejects while still being re-offered. That is a MAX over
1455
+ // the per-produce caps, not a MIN, because the engine evaluates the trigger
1456
+ // per owed path and drops frozen paths from the firing rather than killing
1457
+ // the firing:
1458
+ //
1459
+ // - eligibleFirings (model.ts) filters a step's outputs to the ones that
1460
+ // are still debt AND not frozen, and emits the firing when that filtered
1461
+ // list is non-empty. A step producing `plan` (cap 6) and `consult`
1462
+ // (cap 2) keeps firing for `plan` after `consult` has stalled.
1463
+ // - routingFor (engine.ts) then tests `f.outputs.find((p) => isEscalated(
1464
+ // arts.get(p), rule.after))` — the SAME filtered list. One live path over
1465
+ // the threshold is enough to route.
1466
+ //
1467
+ // So the shortest-fused produce freezing does not end the step, and a
1468
+ // MIN ceiling would reject a def whose escalation is plainly reachable
1469
+ // through a longer-fused produce. The `>=` is still right at the MAX: an
1470
+ // artifact with `judgmentRejects >= cap` is stalled (isStalled, model.ts),
1471
+ // therefore frozen, therefore filtered out of `f.outputs` before routingFor
1472
+ // ever looks at it — so `after` equal to the highest cap can never fire.
1473
+ const attemptCeilings = l.produces.length > 0
1474
+ ? l.produces.map((p) => p.maxAttempts ?? l.maxAttempts)
1475
+ : [l.maxAttempts];
1476
+ const ceiling = Math.max(...attemptCeilings);
1477
+ if (l.escalation.after >= ceiling) {
1478
+ errors.push(`step '${l.name}': escalation.after (${l.escalation.after}) must be strictly less than ` +
1479
+ `the step's highest per-produce maxAttempts (${ceiling}); at ${ceiling} rejections every ` +
1480
+ 'output has frozen, so the escalated re-offer could never run');
1481
+ }
1482
+ }
1483
+ if (declaredModifiers.size > 0) {
1484
+ for (const l of def.steps) {
1485
+ if ((l.executor ?? 'agent') !== 'command')
1486
+ continue;
1487
+ if (l.capabilities === undefined || l.capabilities.length === 0) {
1488
+ errors.push(`step '${l.name}': workflow '${def.name}' declares modifiers:, so every command step must ` +
1489
+ 'author capabilities: — a capability-silent step is claimable by any crew and never ' +
1490
+ 'receives a modifier');
1491
+ }
1492
+ }
1493
+ }
1249
1494
  // Semantic invariant validation: unknown stem references and duplicate names.
1250
1495
  if (def.invariants && def.invariants.length > 0) {
1251
1496
  const invariantNames = new Set();
@@ -1436,6 +1681,71 @@ export function lintDef(def) {
1436
1681
  : [];
1437
1682
  return { errors, warnings };
1438
1683
  }
1684
+ // ---- WS-6: scope-aware calls: target resolution -------------------------------
1685
+ /** Stable private-map key for one installed coordinate at one verified digest. */
1686
+ export function digestScopedCallsTargetKey(digest, target) {
1687
+ return `${digest}/${target}`;
1688
+ }
1689
+ /**
1690
+ * Resolve one `calls:` edge to the def map KEY that edge names, honoring CAS
1691
+ * bundle scope. Returns `undefined` when nothing matches (the caller reports the
1692
+ * `does not exist` error, or skips, as it always has).
1693
+ *
1694
+ * THREE CASES, checked in this order:
1695
+ *
1696
+ * 1. `target` contains `/` — an explicitly QUALIFIED reference. When the
1697
+ * calling definition carries a lock digest for that exact target, prefer the
1698
+ * digest-scoped coordinate alias registered by the CAS loader. That preserves
1699
+ * an already-running parent's selection when a project coordinate later
1700
+ * shadows the global coordinate it originally pinned. Without a reachable
1701
+ * pinned alias, use the direct coordinate/package key so new lookups retain
1702
+ * project-over-global precedence and the engine can surface a pin mismatch.
1703
+ * Never fall back to a bare lookup: an author who wrote a qualified name
1704
+ * asked for one specific definition.
1705
+ *
1706
+ * 2. `from` carries a `bundleDigest` (it was loaded out of a CAS bundle) and
1707
+ * `target` is bare — resolve SIBLING-FIRST: search the map for a def whose
1708
+ * `bundleDigest` equals `from.bundleDigest` and whose own name equals
1709
+ * `target`. This is what makes `calls: build` inside bundle A bind to
1710
+ * bundle A's `build` and never to bundle B's.
1711
+ *
1712
+ * 3. Otherwise — today's plain flat-map lookup, byte-for-byte unchanged. Every
1713
+ * def loaded off the filesystem or handed to `createEngine({ defs })` has
1714
+ * no `bundleDigest`, so it takes this path exactly as before.
1715
+ *
1716
+ * A bare `calls:` from a CAS def that names NO sibling falls through case 2 into
1717
+ * case 3, so an out-of-bundle name still resolves if the flat map holds it and
1718
+ * still produces the existing `does not exist` error if it does not.
1719
+ */
1720
+ function resolveCallsTargetKey(defs, target, from) {
1721
+ if (target.includes('/')) {
1722
+ const pinnedDigest = from.bundleLock?.[target];
1723
+ if (pinnedDigest !== undefined) {
1724
+ const pinnedKey = digestScopedCallsTargetKey(pinnedDigest, target);
1725
+ if (defs.has(pinnedKey))
1726
+ return pinnedKey;
1727
+ }
1728
+ return defs.has(target) ? target : undefined;
1729
+ }
1730
+ if (from.bundleDigest !== undefined) {
1731
+ for (const [key, candidate] of defs) {
1732
+ if (candidate.bundleDigest === from.bundleDigest && candidate.name === target)
1733
+ return key;
1734
+ }
1735
+ }
1736
+ return defs.has(target) ? target : undefined;
1737
+ }
1738
+ /**
1739
+ * The def a `calls:` edge names, honoring CAS bundle scope — the value form of
1740
+ * {@link resolveCallsTargetKey}. This is the ONE resolution rule shared by
1741
+ * load-time validation (`finalizeDefs`), cycle detection, and the engine's
1742
+ * spawn path, so a def that validates at load time is the same def the engine
1743
+ * spawns at runtime.
1744
+ */
1745
+ export function resolveCallsTarget(defs, target, from) {
1746
+ const key = resolveCallsTargetKey(defs, target, from);
1747
+ return key === undefined ? undefined : defs.get(key);
1748
+ }
1439
1749
  // ---- M2-CYCLE: cross-def calls-cycle detection --------------------------------
1440
1750
  /**
1441
1751
  * Walk the calls: edges in a flat def map and throw a DefError if any cycle exists.
@@ -1448,14 +1758,21 @@ function detectCallsCycles(defs) {
1448
1758
  const WHITE = 0, GREY = 1, BLACK = 2;
1449
1759
  const color = new Map([...defs.keys()].map((k) => [k, WHITE]));
1450
1760
  const stack = [];
1761
+ // WS-6: the walk must key on RESOLVED identity, not on the bare `calls:` text.
1762
+ // Two installed bundles may each export a workflow named `build`; keying the
1763
+ // walk by that bare text would fuse them into one node and report a cycle that
1764
+ // does not exist. `resolveCallsTarget` maps (edge text, calling def) to the
1765
+ // exact map key the engine will spawn, so each bundle's `build` stays its own
1766
+ // node under its own qualified key.
1451
1767
  const visit = (name) => {
1452
1768
  color.set(name, GREY);
1453
1769
  stack.push(name);
1454
1770
  const def = defs.get(name);
1455
1771
  // Unique calls: edges from this def (multiple steps might call the same child)
1456
1772
  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))
1773
+ for (const edge of callsEdges) {
1774
+ const child = def === undefined ? undefined : resolveCallsTargetKey(defs, edge, def);
1775
+ if (child === undefined)
1459
1776
  continue; // missing-def error is reported separately in loadDefs
1460
1777
  const c = color.get(child) ?? WHITE;
1461
1778
  if (c === GREY) {
@@ -1550,35 +1867,26 @@ export function loadDefsUnfinalized(dir) {
1550
1867
  }
1551
1868
  return raw;
1552
1869
  }
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) {
1870
+ export function finalizeDefs(raw, options = {}) {
1571
1871
  const out = new Map();
1572
1872
  const resolver = (name) => raw.get(name);
1573
1873
  for (const [name, def] of raw) {
1574
1874
  const expanded = expandIncludes(def, resolver);
1575
1875
  // M2-VALIDATE cross-def: target-def existence + child input-key validity.
1576
1876
  // These cannot live in validateDef (pure per-def, no resolver) — same split as expandIncludes.
1877
+ //
1878
+ // WS-6: `calls:` targets resolve through `resolveCallsTarget` (scope-aware),
1879
+ // NOT through the plain `resolver` used for `include:` expansion above.
1880
+ // `include:` is a DIFFERENT edge kind and is deliberately left on the flat
1881
+ // lookup — this workstream is `calls:`-only.
1577
1882
  for (const l of expanded.steps) {
1578
1883
  if (!l.calls)
1579
1884
  continue;
1580
- const childDef = resolver(l.calls);
1885
+ const childDef = resolveCallsTarget(raw, l.calls, expanded);
1581
1886
  if (!childDef) {
1887
+ if (options.allowUnresolvedCalls === true
1888
+ || options.allowUnresolvedVersionedCalls?.has(l.calls) === true)
1889
+ continue;
1582
1890
  throw new DefError(`calls names workflow '${l.calls}' which does not exist`);
1583
1891
  }
1584
1892
  const childInputNames = new Set(childDef.inputs.map((i) => i.name));