@parcha/agentrun-dsl 0.1.0-beta.2 → 0.1.0-beta.20

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 (102) hide show
  1. package/README.md +46 -16
  2. package/dist/author.d.ts +96 -0
  3. package/dist/author.js +320 -0
  4. package/dist/authoring.js +1 -1
  5. package/dist/cli.js +8 -3
  6. package/dist/code-exec.d.ts +6 -0
  7. package/dist/code-exec.js +126 -0
  8. package/dist/decision-receipts.d.ts +98 -0
  9. package/dist/decision-receipts.js +51 -0
  10. package/dist/dry-run.d.ts +14 -1
  11. package/dist/dry-run.js +39 -13
  12. package/dist/graph.d.ts +83 -0
  13. package/dist/graph.js +231 -0
  14. package/dist/index.d.ts +12 -4
  15. package/dist/index.js +6 -2
  16. package/dist/inspection.js +2 -2
  17. package/dist/job.d.ts +14 -0
  18. package/dist/job.js +5 -0
  19. package/dist/long-timer.d.ts +7 -0
  20. package/dist/long-timer.js +22 -0
  21. package/dist/observer-snapshot.d.ts +3 -0
  22. package/dist/observer-snapshot.js +46 -0
  23. package/dist/predicates.d.ts +4 -0
  24. package/dist/predicates.js +19 -2
  25. package/dist/recovery/binding.d.ts +10 -0
  26. package/dist/recovery/binding.js +43 -0
  27. package/dist/recovery/call-key.d.ts +13 -0
  28. package/dist/recovery/call-key.js +24 -0
  29. package/dist/recovery/canonical-hash.d.ts +7 -0
  30. package/dist/recovery/canonical-hash.js +22 -0
  31. package/dist/recovery/driver.d.ts +208 -0
  32. package/dist/recovery/driver.js +1222 -0
  33. package/dist/recovery/effect-failure.d.ts +34 -0
  34. package/dist/recovery/effect-failure.js +62 -0
  35. package/dist/recovery/errors.d.ts +31 -0
  36. package/dist/recovery/errors.js +51 -0
  37. package/dist/recovery/execution-path.d.ts +53 -0
  38. package/dist/recovery/execution-path.js +167 -0
  39. package/dist/recovery/file-store.d.ts +7 -0
  40. package/dist/recovery/file-store.js +131 -0
  41. package/dist/recovery/frozen-snapshot.d.ts +244 -0
  42. package/dist/recovery/frozen-snapshot.js +171 -0
  43. package/dist/recovery/handoff-block.d.ts +36 -0
  44. package/dist/recovery/handoff-block.js +148 -0
  45. package/dist/recovery/handoff-digest.d.ts +58 -0
  46. package/dist/recovery/handoff-digest.js +195 -0
  47. package/dist/recovery/handoff-files.d.ts +54 -0
  48. package/dist/recovery/handoff-files.js +162 -0
  49. package/dist/recovery/handoff-receipts.d.ts +42 -0
  50. package/dist/recovery/handoff-receipts.js +53 -0
  51. package/dist/recovery/handoff-redact.d.ts +12 -0
  52. package/dist/recovery/handoff-redact.js +44 -0
  53. package/dist/recovery/handoff.d.ts +44 -0
  54. package/dist/recovery/handoff.js +46 -0
  55. package/dist/recovery/index.d.ts +18 -0
  56. package/dist/recovery/index.js +16 -0
  57. package/dist/recovery/item-state.d.ts +48 -0
  58. package/dist/recovery/item-state.js +89 -0
  59. package/dist/recovery/journal.d.ts +28 -0
  60. package/dist/recovery/journal.js +139 -0
  61. package/dist/recovery/memory-store.d.ts +4 -0
  62. package/dist/recovery/memory-store.js +20 -0
  63. package/dist/recovery/store.d.ts +105 -0
  64. package/dist/recovery/store.js +6 -0
  65. package/dist/recovery/testing/conformance.d.ts +4 -0
  66. package/dist/recovery/testing/conformance.js +268 -0
  67. package/dist/recovery/testing/crash-points.d.ts +18 -0
  68. package/dist/recovery/testing/crash-points.js +43 -0
  69. package/dist/recovery/testing/crash-sweep.d.ts +65 -0
  70. package/dist/recovery/testing/crash-sweep.js +146 -0
  71. package/dist/recovery/testing/index.d.ts +3 -0
  72. package/dist/recovery/testing/index.js +4 -0
  73. package/dist/recovery/testing/preload.d.ts +1 -0
  74. package/dist/recovery/testing/preload.js +3 -0
  75. package/dist/recovery/transport-facts.d.ts +23 -0
  76. package/dist/recovery/transport-facts.js +46 -0
  77. package/dist/recovery/with-recovery.d.ts +44 -0
  78. package/dist/recovery/with-recovery.js +87 -0
  79. package/dist/system-one.d.ts +17 -1
  80. package/dist/system-one.js +62 -5
  81. package/dist/vocabulary.d.ts +42 -0
  82. package/dist/vocabulary.js +74 -0
  83. package/dist/workflow-shape.d.ts +7 -0
  84. package/dist/workflow-shape.js +85 -62
  85. package/dist/workflow.d.ts +187 -16
  86. package/dist/workflow.js +967 -324
  87. package/package.json +18 -2
  88. package/schema/workflow.schema.json +251 -15
  89. package/skills/author/SKILL.md +122 -0
  90. package/skills/author/examples/evidence-gate.input.json +6 -0
  91. package/skills/author/examples/evidence-gate.json +125 -0
  92. package/skills/author/examples/read-file.input.json +1 -0
  93. package/skills/author/examples/read-file.json +44 -0
  94. package/skills/author/examples/read-source-decision.input.json +4 -0
  95. package/skills/author/examples/read-source-decision.json +37 -0
  96. package/skills/author/examples/release-note.txt +10 -0
  97. package/skills/author/examples/review-release-notes.input.json +6 -0
  98. package/skills/author/examples/review-release-notes.json +123 -0
  99. package/skills/author/references/jev-decisions.md +125 -0
  100. package/skills/author/references/language.md +118 -0
  101. package/skills/author/references/sdk-authoring.md +11 -0
  102. package/skills/author/references/workflow-format.md +137 -0
package/dist/workflow.js CHANGED
@@ -1,14 +1,20 @@
1
+ import { observerSnapshot } from "./observer-snapshot.js";
1
2
  import { createHash } from "node:crypto";
2
3
  import { isDeepStrictEqual, types as utilTypes } from "node:util";
3
- import { predicateMatches, MECHANICAL_PREDICATE_NAMES } from "./predicates.js";
4
+ import { predicateMatches, getPath, MECHANICAL_PREDICATE_NAMES } from "./predicates.js";
5
+ import { WORKFLOW_NODE_KINDS, NODE_FIELDS, HOST_NODE_FIELDS, IGNORED_NODE_FIELDS, WORKFLOW_PREDICATES, THINKING_LEVELS, MODEL_TIERS, AGENT_CONTEXTS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, EFFECT_FAILURE_CODES, PROSE_ARTIFACT_TYPES } from "./vocabulary.js";
4
6
  import { validateAnswers, answerConfidence, answersSidecar, answersToValue, compileQuestions, SYSTEM_ONE_LIMITS } from "./system-one.js";
7
+ import { DECISION_RECEIPT_VERSION } from "./decision-receipts.js";
5
8
  import { Compile } from "typebox/compile";
6
9
  import { compileTransform, compileTransformSyntax } from "./code-exec.js";
7
- import { workflowShapeErrors } from "./workflow-shape.js";
10
+ import { workflowShapeIssues } from "./workflow-shape.js";
8
11
  import { resolveSchemaForWorkflow } from "./schema-references.js";
9
12
  export { resolveSchemaForWorkflow } from "./schema-references.js";
13
+ import { setLongTimeout } from "./long-timer.js";
14
+ import { isRecoveryError } from "./recovery/errors.js";
15
+ export const routesByValue = (node) => typeof node.valuePath === "string";
10
16
  export function artifactNodeIsProse(node) {
11
- return node.type === "markdown" || node.type === "report";
17
+ return PROSE_ARTIFACT_TYPES.includes(node.type);
12
18
  }
13
19
  export function desugarWorkflow(workflow) {
14
20
  const visit = (node) => {
@@ -61,8 +67,11 @@ export const declaredWrites = (node) => {
61
67
  out.add("report_markdown");
62
68
  else if (typeof n.as === "string" && n.as.trim())
63
69
  out.add(n.as);
64
- if (n.node === "map")
70
+ if (n.node === "map") {
71
+ if (typeof n.failedAs === "string" && n.failedAs.trim())
72
+ out.add(n.failedAs);
65
73
  return;
74
+ }
66
75
  if (Array.isArray(n.steps))
67
76
  n.steps.forEach(visit);
68
77
  if (Array.isArray(n.branches))
@@ -75,6 +84,43 @@ export const declaredWrites = (node) => {
75
84
  visit(node);
76
85
  return out;
77
86
  };
87
+ /** The top-level keys a loop body writes, with engine sidecars; null when an unaliased code node makes them unknowable. */
88
+ const loopBodyWrites = (body) => {
89
+ const out = new Set();
90
+ let known = true;
91
+ const visit = (n) => {
92
+ if (!n || typeof n !== "object" || !known)
93
+ return;
94
+ if (n.node === "code" && n.as === undefined) {
95
+ known = false;
96
+ return;
97
+ }
98
+ if (n.node === "report")
99
+ out.add("report_markdown");
100
+ else if (typeof n.as === "string" && n.as.trim())
101
+ out.add(n.as);
102
+ else if (["agent", "decide", "extract"].includes(n.node) && typeof n.label === "string")
103
+ out.add(n.label);
104
+ if (n.node === "map" && typeof n.failedAs === "string" && n.failedAs.trim())
105
+ out.add(n.failedAs);
106
+ if (n.node === "map" || n.node === "workflow")
107
+ return;
108
+ if (Array.isArray(n.steps))
109
+ n.steps.forEach(visit);
110
+ if (Array.isArray(n.branches))
111
+ n.branches.forEach(visit);
112
+ else if (n.node === "route" && n.branches && typeof n.branches === "object")
113
+ Object.values(n.branches).forEach((b) => visit(b?.body));
114
+ if (n.body)
115
+ visit(n.body);
116
+ };
117
+ visit(body);
118
+ if (!known)
119
+ return null;
120
+ for (const key of [...out])
121
+ out.add(`${key}$answers`).add(`${key}$verify`);
122
+ return out;
123
+ };
78
124
  const routeBodies = (node) => node.node === "route" ? Object.values(node.branches || {}).map((b) => b?.body).filter(Boolean) : [];
79
125
  const snapshotState = (state) => {
80
126
  try {
@@ -84,19 +130,31 @@ const snapshotState = (state) => {
84
130
  throw new Error("Workflow state must be structured-cloneable", { cause });
85
131
  }
86
132
  };
87
- const KINDS = new Set(["chain", "code", "agent", "decide", "extract", "report", "map", "parallel", "loop", "escalate", "call", "artifact", "workflow", "judge", "pick", "sift", "route"]);
133
+ const KINDS = new Set(WORKFLOW_NODE_KINDS);
134
+ const kindsMatchType = true;
135
+ void kindsMatchType;
136
+ const KIND_KEYS = Object.fromEntries(WORKFLOW_NODE_KINDS.map((kind) => [kind, new Set([...NODE_FIELDS[kind], ...HOST_NODE_FIELDS, ...(IGNORED_NODE_FIELDS[kind] ?? [])])]));
88
137
  export const childSteps = (child) => {
89
138
  const root = child?.root;
90
139
  if (!root || typeof root !== "object")
91
140
  return null;
92
141
  return root.node === "chain" ? (Array.isArray(root.steps) ? root.steps : null) : [root];
93
142
  };
143
+ /** The code a retry class implies when the failure names none. */
144
+ const codeOfRetryClass = (retryClass) => retryClass === null ? null : retryClass === "timeout" ? "effect_timeout" : retryClass === "exit" ? "effect_exit" : "effect_transport";
145
+ /** A failed effect: its retry class (null when the failure is not transient by nature), its closed code,
146
+ * and what the host observed (`detail`, written onto the attempt's `effect.failed` event). */
94
147
  export class EffectFailure extends Error {
95
148
  retryClass;
96
- constructor(message, retryClass = null) {
97
- super(message);
149
+ code;
150
+ detail;
151
+ constructor(message, retryClass = null, options = {}) {
152
+ super(message, options.cause === undefined ? undefined : { cause: options.cause });
98
153
  this.retryClass = retryClass;
99
154
  this.name = "EffectFailure";
155
+ this.code = options.code === undefined ? codeOfRetryClass(retryClass) : options.code;
156
+ if (options.detail)
157
+ this.detail = options.detail;
100
158
  }
101
159
  }
102
160
  function containsReportNode(node) {
@@ -114,7 +172,7 @@ function containsReportNode(node) {
114
172
  return routeBodies(node).some(containsReportNode);
115
173
  return false;
116
174
  }
117
- const PREDICATES = new Set([...MECHANICAL_PREDICATE_NAMES, "ask"]);
175
+ const PREDICATES = new Set(WORKFLOW_PREDICATES);
118
176
  function predicateShapeErrors(pred) {
119
177
  const out = [];
120
178
  if (pred.predicate === "in") {
@@ -275,18 +333,66 @@ export function workflowDocumentError(value) {
275
333
  }
276
334
  return undefined;
277
335
  }
336
+ const pointerKey = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
278
337
  /** Set executeCode:false for untrusted author feedback: check syntax and mechanical contracts
279
338
  * without evaluating authored expressions or probing transforms. This is not execution admission;
280
339
  * trusted/default validation and runtime output checks remain authoritative. */
340
+ const RETRY_ON_NAMES = [...CALL_RETRY_CLASSES, ...EFFECT_FAILURE_CODES];
341
+ /** Advice the validator gives without refusing: a shape that runs and costs more than it needs to. A map with no
342
+ * `resultPath` whose body writes no `as` returns each item's whole state, which holds the list the map ran over: the
343
+ * map's result, and every state after it, grow with the square of its items. */
344
+ function workflowWarnings(workflow) {
345
+ const warnings = [];
346
+ // Warnings are given for a document the validator refuses too, so a field may be missing or of the wrong kind.
347
+ const list = (value) => (Array.isArray(value) ? value : []);
348
+ const visit = (node) => {
349
+ if (!node || typeof node !== "object")
350
+ return;
351
+ switch (node.node) {
352
+ case "chain":
353
+ list(node.steps).forEach(visit);
354
+ break;
355
+ case "parallel":
356
+ list(node.branches).forEach(visit);
357
+ break;
358
+ case "map":
359
+ if (node.resultPath === undefined && node.body && typeof node.body === "object" && !node.body.as) {
360
+ warnings.push(`map "${node.label}": each item's result is its whole state, including ${node.itemsPath}; set resultPath (or an as in the body) for a large map`);
361
+ }
362
+ visit(node.body);
363
+ break;
364
+ case "loop":
365
+ visit(node.body);
366
+ break;
367
+ case "route":
368
+ if (node.branches && typeof node.branches === "object")
369
+ Object.values(node.branches).forEach((branch) => visit(branch?.body));
370
+ break;
371
+ case "workflow":
372
+ visit(node.workflow?.root);
373
+ break;
374
+ default: break;
375
+ }
376
+ };
377
+ visit(workflow.root);
378
+ return warnings;
379
+ }
380
+ /** Whether a workflow can run, checked without running it: `errors` refuse it, `warnings` advise and never refuse. */
281
381
  export function validateWorkflow(workflow, opts) {
282
382
  const bounded = workflowDocumentError(workflow);
283
383
  if (bounded)
284
- return { ok: false, errors: [bounded] };
285
- const shapeErrors = workflowShapeErrors(workflow);
286
- if (shapeErrors.length)
287
- return { ok: false, errors: shapeErrors };
384
+ return { ok: false, errors: [bounded], issues: [{ path: "", code: "DOCUMENT_INVALID", message: bounded }] };
385
+ const shapeIssues = workflowShapeIssues(workflow);
386
+ if (shapeIssues.length)
387
+ return { ok: false, errors: shapeIssues.map(issue => issue.message), issues: shapeIssues.map(issue => ({ path: issue.path, code: "SHAPE_INVALID", message: issue.message })) };
288
388
  workflow = desugarWorkflow(workflow);
289
389
  const errors = [];
390
+ const issues = [];
391
+ const fail = (code, path, message) => { errors.push(message); issues.push({ path, code, message }); };
392
+ // Each node's walk path (the text its messages begin with) to its JSON Pointer. Desugaring replaces nodes in place, so
393
+ // the pointer names the same node in the document as written.
394
+ const pointers = new Map();
395
+ const ptrOf = (path) => pointers.get(path) ?? "";
290
396
  const declaredInput = workflow.input && Object.hasOwn(workflow.schemas, workflow.input.schemaId)
291
397
  ? resolveSchemaForWorkflow(workflow, workflow.schemas[workflow.input.schemaId]) : undefined;
292
398
  const inputKeys = opts?.input !== undefined ? Object.keys(opts.input ?? {}) : opts?.inputKeys;
@@ -302,7 +408,7 @@ export function validateWorkflow(workflow, opts) {
302
408
  };
303
409
  for (const [key, schema] of Object.entries((declaredInput?.properties ?? {})))
304
410
  rememberOutput(key, schema);
305
- const checkTypedPath = (dotted, at) => {
411
+ const checkTypedPath = (dotted, at, node) => {
306
412
  if (!reachability || reachability.unknowable)
307
413
  return;
308
414
  const [head, ...tail] = dotted.split(".");
@@ -321,7 +427,7 @@ export function validateWorkflow(workflow, opts) {
321
427
  schema = schema.properties[segment];
322
428
  else {
323
429
  if (schema.additionalProperties === false && !schema.patternProperties)
324
- errors.push(`${at}: state path "${dotted}" is excluded by the upstream schema at "${head}"; check the producer's as key and declared properties`);
430
+ fail("STATE_PATH_EXCLUDED", node, `${at}: state path "${dotted}" is excluded by the upstream schema at "${head}"; check the producer's as key and declared properties`);
325
431
  return;
326
432
  }
327
433
  }
@@ -426,11 +532,59 @@ export function validateWorkflow(workflow, opts) {
426
532
  // own fail-closed guard (or a structural mismatch with the actual files) fired. Code that
427
533
  // also threw under the tolerant probe is state-dependent and stands down as before.
428
534
  if (!tolerantThrew)
429
- errors.push(`${at.path} (${at.label}): code node throws against the real reference data: ${thrown instanceof Error ? thrown.message : String(thrown)}`);
535
+ fail("CODE_INVALID", ptrOf(at.path), `${at.path} (${at.label}): code node throws against the real reference data: ${thrown instanceof Error ? thrown.message : String(thrown)}`);
430
536
  }
431
537
  }
432
538
  return patches;
433
539
  };
540
+ const snapshotKnowledge = () => ({
541
+ available: reachability ? new Set(reachability.available) : null, unknowable: reachability?.unknowable ?? true,
542
+ typed: new Map(typedOutputs), probed: new Map([...probedSubtrees].map(([key, values]) => [key, [...values]])),
543
+ spread: new Set(spreadTaintedKeys), files: new Set(producedFiles),
544
+ });
545
+ const restoreKnowledge = (knowledge) => {
546
+ if (reachability && knowledge.available) {
547
+ reachability.available = new Set(knowledge.available);
548
+ reachability.unknowable = knowledge.unknowable;
549
+ }
550
+ typedOutputs.clear();
551
+ for (const [key, value] of knowledge.typed)
552
+ typedOutputs.set(key, value);
553
+ probedSubtrees.clear();
554
+ for (const [key, values] of knowledge.probed)
555
+ probedSubtrees.set(key, [...values]);
556
+ spreadTaintedKeys.clear();
557
+ for (const key of knowledge.spread)
558
+ spreadTaintedKeys.add(key);
559
+ producedFiles.clear();
560
+ for (const file of knowledge.files)
561
+ producedFiles.add(file);
562
+ };
563
+ /** After a parallel node: each branch's own changes applied over the state before it; keys, files and shapes accumulate. */
564
+ const mergeKnowledge = (before, branches) => {
565
+ restoreKnowledge(before);
566
+ for (const branch of branches) {
567
+ if (reachability && branch.available)
568
+ for (const key of branch.available)
569
+ reachability.available.add(key);
570
+ for (const [key, value] of branch.typed)
571
+ if (before.typed.get(key) !== value)
572
+ typedOutputs.set(key, value);
573
+ for (const key of before.typed.keys())
574
+ if (!branch.typed.has(key))
575
+ typedOutputs.delete(key);
576
+ for (const [key, values] of branch.probed)
577
+ if (before.probed.get(key)?.length !== values.length || before.probed.get(key)?.some((v, i) => v !== values[i]))
578
+ probedSubtrees.set(key, [...values]);
579
+ for (const key of branch.spread)
580
+ spreadTaintedKeys.add(key);
581
+ for (const file of branch.files)
582
+ producedFiles.add(file);
583
+ }
584
+ // The merged state depends on which branches ran how; later reachability checks stand down, as before.
585
+ if (reachability)
586
+ reachability.unknowable = true;
587
+ };
434
588
  const checkPredicatePath = (when, label, path) => {
435
589
  if (!reachability || !when?.path)
436
590
  return;
@@ -462,7 +616,22 @@ export function validateWorkflow(workflow, opts) {
462
616
  if (!missing)
463
617
  return;
464
618
  }
465
- errors.push(`${path} (${label}): predicate path "${when.path}" is not produced by the code node that writes "${head}" (its shape has: ${missingAt && typeof missingAt === "object" ? Object.keys(missingAt).join(", ") : typeof missingAt}); the guard can never fire`);
619
+ fail("STATE_PATH_EXCLUDED", ptrOf(path), `${path} (${label}): predicate path "${when.path}" is not produced by the code node that writes "${head}" (its shape has: ${missingAt && typeof missingAt === "object" ? Object.keys(missingAt).join(", ") : typeof missingAt}); the guard can never fire`);
620
+ };
621
+ // A mechanical predicate reads one state key; when no input key or earlier node writes it, the guard can never fire.
622
+ const checkPredicateHead = (pred, label, path, field, produced) => {
623
+ if (!reachability || reachability.unknowable || !pred || typeof pred !== "object")
624
+ return;
625
+ const available = produced ?? reachability.available;
626
+ const { predicate, path: at, key } = pred;
627
+ const read = predicate === "no_new_items" ? key : predicate === "ask" ? undefined : at;
628
+ if (typeof read !== "string" || !read.trim())
629
+ return;
630
+ const head = read.split(".")[0];
631
+ if (!available.has(head))
632
+ fail("STATE_PATH_UNPRODUCED", ptrOf(path), `${path} (${label}): ${field} reads "${read}" but no input key or earlier node produces "${head}"; the guard can never fire`);
633
+ else if (!produced)
634
+ checkTypedPath(read, `${path} (${label}) ${field}`, ptrOf(path));
466
635
  };
467
636
  const checkInterpolations = (value, label, path) => {
468
637
  if (!reachability || reachability.unknowable || value === undefined)
@@ -474,16 +643,16 @@ export function validateWorkflow(workflow, opts) {
474
643
  continue;
475
644
  const head = (m[1].startsWith("state.") ? m[1].slice(6) : m[1]).split(".")[0];
476
645
  if (!reachability.available.has(head))
477
- errors.push(`${path} (${label}): interpolates {${m[1]}} but no upstream node produces "${head}"`);
646
+ fail("STATE_PATH_UNPRODUCED", ptrOf(path), `${path} (${label}): interpolates {${m[1]}} but no upstream node produces "${head}"`);
478
647
  else
479
- checkTypedPath(m[1].startsWith("state.") ? m[1].slice(6) : m[1], `${path} (${label})`);
648
+ checkTypedPath(m[1].startsWith("state.") ? m[1].slice(6) : m[1], `${path} (${label})`, ptrOf(path));
480
649
  }
481
650
  };
482
651
  const checkRequires = (node, path) => {
483
652
  if (node.requires === undefined)
484
653
  return;
485
654
  if (!Array.isArray(node.requires) || node.requires.some((p) => typeof p !== "string" || !p.trim())) {
486
- errors.push(`${path} (${node.label}): requires must be non-empty state paths`);
655
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): requires must be non-empty state paths`);
487
656
  return;
488
657
  }
489
658
  if (!reachability || reachability.unknowable)
@@ -491,10 +660,10 @@ export function validateWorkflow(workflow, opts) {
491
660
  for (const required of node.requires) {
492
661
  const head = String(required).split(".")[0];
493
662
  if (!reachability.available.has(head)) {
494
- errors.push(`${path} (${node.label}): requires "${required}" but no upstream node produces it; state here has only: ${[...reachability.available].join(", ")}`);
663
+ fail("STATE_PATH_UNPRODUCED", ptrOf(path), `${path} (${node.label}): requires "${required}" but no upstream node produces it; state here has only: ${[...reachability.available].join(", ")}`);
495
664
  }
496
665
  else
497
- checkTypedPath(required, `${path} (${node.label}) requires`);
666
+ checkTypedPath(required, `${path} (${node.label}) requires`, ptrOf(path));
498
667
  }
499
668
  };
500
669
  const checkItemsPath = (node, path) => {
@@ -502,23 +671,23 @@ export function validateWorkflow(workflow, opts) {
502
671
  return;
503
672
  const head = node.itemsPath.split(".")[0];
504
673
  if (!reachability.available.has(head))
505
- errors.push(`${path} (${node.label}): itemsPath "${node.itemsPath}" has no upstream producer; read the value under the producing node's as key (or its label when as is omitted)`);
674
+ fail("STATE_PATH_UNPRODUCED", ptrOf(path), `${path} (${node.label}): itemsPath "${node.itemsPath}" has no upstream producer; read the value under the producing node's as key (or its label when as is omitted)`);
506
675
  else
507
- checkTypedPath(node.itemsPath, `${path} (${node.label}) itemsPath`);
676
+ checkTypedPath(node.itemsPath, `${path} (${node.label}) itemsPath`, ptrOf(path));
508
677
  };
509
678
  if (workflow?.v !== 2)
510
- errors.push("workflow.v must be 2");
679
+ fail("WORKFLOW_FIELD_INVALID", "", "workflow.v must be 2");
511
680
  if (!workflow?.name)
512
- errors.push("workflow.name is required");
681
+ fail("WORKFLOW_FIELD_INVALID", "", "workflow.name is required");
513
682
  if (!workflow?.schemas || typeof workflow.schemas !== "object")
514
- errors.push("workflow.schemas is required");
683
+ fail("WORKFLOW_FIELD_INVALID", "", "workflow.schemas is required");
515
684
  if (workflow?.input !== undefined && (!workflow.input || typeof workflow.input.schemaId !== "string" || !Object.hasOwn(workflow.schemas, workflow.input.schemaId)))
516
- errors.push("workflow.input.schemaId must name a schema");
685
+ fail("WORKFLOW_FIELD_INVALID", "", "workflow.input.schemaId must name a schema");
517
686
  if (!workflow?.output?.schemaId || !Object.hasOwn(workflow.schemas, workflow.output.schemaId))
518
- errors.push("workflow.output.schemaId must name a schema");
687
+ fail("WORKFLOW_FIELD_INVALID", "", "workflow.output.schemaId must name a schema");
519
688
  for (const [id, schema] of Object.entries(workflow?.schemas || {})) {
520
689
  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
521
- errors.push(`schema "${id}" must be a JSON-schema object (got ${schema === null ? "null" : Array.isArray(schema) ? "array" : typeof schema})`);
690
+ fail("SCHEMA_INVALID", `/schemas/${pointerKey(id)}`, `schema "${id}" must be a JSON-schema object (got ${schema === null ? "null" : Array.isArray(schema) ? "array" : typeof schema})`);
522
691
  continue;
523
692
  }
524
693
  // Fail closed on refs: typebox compiles an unresolvable $ref to a never-matching schema
@@ -547,106 +716,97 @@ export function validateWorkflow(workflow, opts) {
547
716
  for (const ref of refs) {
548
717
  const match = ref.match(/^#\/definitions\/(.+)$/);
549
718
  if (!match)
550
- errors.push(`schema "${id}": unsupported $ref form "${ref}" — only "#/definitions/<name>" resolves (against inline definitions or a sibling schema)`);
719
+ fail("SCHEMA_INVALID", `/schemas/${pointerKey(id)}`, `schema "${id}": unsupported $ref form "${ref}" — only "#/definitions/<name>" resolves (against inline definitions or a sibling schema)`);
551
720
  else if (!Object.hasOwn(definitions, match[1]))
552
- errors.push(`schema "${id}": $ref "${ref}" resolves to no inline definition and no sibling schema`);
721
+ fail("SCHEMA_INVALID", `/schemas/${pointerKey(id)}`, `schema "${id}": $ref "${ref}" resolves to no inline definition and no sibling schema`);
553
722
  }
554
723
  try {
555
724
  Compile(resolved);
556
725
  }
557
726
  catch (e) {
558
- errors.push(`schema "${id}" does not compile: ${e?.message || e}`);
727
+ fail("SCHEMA_INVALID", `/schemas/${pointerKey(id)}`, `schema "${id}" does not compile: ${e?.message || e}`);
559
728
  }
560
729
  }
561
730
  if (opts?.input !== undefined) {
562
731
  if (!opts.input || typeof opts.input !== "object" || Array.isArray(opts.input))
563
- errors.push("input must be a JSON object");
732
+ fail("INPUT_INVALID", "", "input must be a JSON object");
564
733
  else if (declaredInput) {
565
734
  try {
566
735
  const validator = Compile(declaredInput);
567
736
  if (!validator.Check(opts.input))
568
- errors.push(...schemaProblems(validator, opts.input).map(problem => `input: ${problem}`));
737
+ for (const problem of schemaProblems(validator, opts.input))
738
+ fail("INPUT_INVALID", "", `input: ${problem}`);
569
739
  }
570
740
  catch { /* Schema diagnostics above retain the original compilation failure. */ }
571
741
  }
572
742
  }
573
- const KIND_KEYS = {
574
- chain: new Set(["node", "steps"]),
575
- code: new Set(["node", "label", "code", "as"]),
576
- // "budget" (agent) and "samples"/"voteField" (decide) are deprecated-and-ignored: tolerated
577
- // for legacy v2 documents. The engine invokes the adapter once per node.
578
- agent: new Set(["node", "label", "state", "instructions", "sopSection", "out", "as", "requires", "tools", "effort", "thinking", "budget", "verify", "tier"]),
579
- decide: new Set(["node", "label", "state", "instructions", "sopSection", "out", "as", "requires", "tools", "effort", "thinking", "samples", "voteField", "verify", "tier"]),
580
- extract: new Set(["node", "label", "state", "instructions", "sopSection", "out", "as", "requires", "tools", "effort", "thinking", "verify", "tier"]),
581
- report: new Set(["node", "label", "state", "instructions", "sopSection", "requires", "tools", "effort", "thinking"]),
582
- artifact: new Set(["node", "label", "state", "type", "path", "instructions", "sopSection", "requires", "tools", "effort", "thinking"]),
583
- map: new Set(["node", "label", "itemsPath", "body", "as", "resultPath", "maxConcurrency"]),
584
- parallel: new Set(["node", "label", "branches"]),
585
- loop: new Set(["node", "label", "body", "until", "maxIters"]),
586
- escalate: new Set(["node", "label", "when", "kind", "stage", "summary"]),
587
- call: new Set(["node", "label", "via", "tool", "args", "code", "input", "command", "where", "out", "as", "produces", "deadline_s", "retry", "poll", "requires", "env"]),
588
- workflow: new Set(["node", "label", "workflow", "input", "out", "as"]),
589
- judge: new Set(["node", "label", "state", "out", "as", "requires"]),
590
- pick: new Set(["node", "label", "itemsPath", "describe", "instructions", "state", "allowNone", "as", "requires"]),
591
- sift: new Set(["node", "label", "itemsPath", "describe", "state", "out", "as", "keep", "requires"]),
592
- route: new Set(["node", "label", "state", "instructions", "branches", "unsure", "as", "requires"]),
593
- };
594
743
  const checkStateMap = (map, label, path, field = "state") => {
595
744
  if (map === undefined)
596
745
  return;
597
746
  if (!map || typeof map !== "object" || Array.isArray(map)) {
598
- errors.push(`${path} (${label}): ${field} must be an object map of what the questions see`);
747
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): ${field} must be an object map of what the questions see`);
599
748
  return;
600
749
  }
601
750
  checkInterpolations(map, label, path);
602
751
  };
603
752
  const checkQuestionSchema = (schemaId, label, path) => {
604
753
  if (typeof schemaId !== "string" || !Object.hasOwn(workflow.schemas, schemaId)) {
605
- errors.push(`${path} (${label}): out schema "${String(schemaId)}" not in workflow.schemas`);
754
+ fail("SCHEMA_UNKNOWN", ptrOf(path), `${path} (${label}): out schema "${String(schemaId)}" not in workflow.schemas`);
606
755
  return null;
607
756
  }
608
757
  const compiled = compileQuestions(workflow.schemas[schemaId], workflow.schemas);
609
758
  if (compiled.ok === false) {
610
- errors.push(...compiled.errors.map((e) => `${path} (${label}): schema "${schemaId}": ${e}`));
759
+ for (const e of compiled.errors)
760
+ fail("SCHEMA_INVALID", `/schemas/${pointerKey(schemaId)}`, `${path} (${label}): schema "${schemaId}": ${e}`);
611
761
  return null;
612
762
  }
613
763
  return compiled.questions;
614
764
  };
615
765
  const checkPredicate = (pred, label, path, field, mechanicalOnly = false) => {
616
766
  const name = pred?.predicate;
767
+ // A predicate with no `predicate` field is the shape mistaken, not an unknown name: say the shape
768
+ // (GRE-2809), naming a predicate the object used as a key when it did.
769
+ if (pred && typeof pred === "object" && !Array.isArray(pred) && name === undefined) {
770
+ const keyed = Object.keys(pred).find((key) => PREDICATES.has(key));
771
+ fail("PREDICATE_INVALID", ptrOf(path), `${path} (${label}): ${field}: a predicate names itself in its "predicate" field beside its own fields, e.g. {"predicate": "${keyed ?? "field_true"}", "path": "..."}${keyed ? `, not {"${keyed}": {...}}` : ""}`);
772
+ return false;
773
+ }
617
774
  if (!pred || !PREDICATES.has(name) || (mechanicalOnly && !MECHANICAL_PREDICATE_NAMES.has(name))) {
618
- errors.push(`${path} (${label}): ${field}: unknown predicate "${name}"${mechanicalOnly && name === "ask" ? " (a poll reads a value, never asks a question)" : ""}`);
775
+ fail("PREDICATE_INVALID", ptrOf(path), `${path} (${label}): ${field}: unknown predicate "${name}"${mechanicalOnly && name === "ask" ? " (a poll reads a value, never asks a question)" : ""}`);
619
776
  return false;
620
777
  }
621
- errors.push(...predicateShapeErrors(pred).map((e) => `${path} (${label}): ${field}: ${e}`));
778
+ for (const e of predicateShapeErrors(pred))
779
+ fail("PREDICATE_INVALID", ptrOf(path), `${path} (${label}): ${field}: ${e}`);
622
780
  if (name === "ask")
623
781
  checkStateMap(pred.state, label, path, `${field}.state`);
624
782
  return true;
625
783
  };
626
- const walk = (node, path) => {
784
+ const walk = (node, path, ptr) => {
785
+ // A node that is missing (a map or loop without a body) is reported on the node that should hold it.
786
+ pointers.set(path, node === undefined ? ptr.slice(0, ptr.lastIndexOf("/")) : ptr);
627
787
  if (!node || typeof node !== "object" || !KINDS.has(node.node)) {
628
- errors.push(`${path}: unknown node kind "${node?.node}"`);
788
+ fail("NODE_KIND_UNKNOWN", ptrOf(path), `${path}: unknown node kind "${node?.node}"`);
629
789
  return;
630
790
  }
631
791
  {
632
792
  const allowed = KIND_KEYS[node.node];
633
793
  const extraneous = Object.keys(node).filter((key) => !allowed.has(key));
634
794
  if (extraneous.length)
635
- errors.push(`${path} (${node.label || node.node}): unknown key(s) for a ${node.node} node: ${extraneous.join(", ")}`);
795
+ fail("NODE_KEY_UNKNOWN", ptrOf(path), `${path} (${node.label || node.node}): unknown key(s) for a ${node.node} node: ${extraneous.join(", ")}`);
636
796
  // `$`-prefixed state keys are engine-owned (`$host`, `<as>$verify`): no node may write one. A label
637
797
  // is the state key whenever `as` is omitted, so labels are held to the same rule.
638
798
  if (typeof node.as === "string" && node.as.startsWith("$"))
639
- errors.push(`${path} (${node.label || node.node}): "as" must not name an engine-owned "$" state key ("${node.as}")`);
799
+ fail("STATE_KEY_RESERVED", ptrOf(path), `${path} (${node.label || node.node}): "as" must not name an engine-owned "$" state key ("${node.as}")`);
640
800
  // Only an unaliased generative or code node writes under its label; every other label is a name, not a key.
641
801
  const labelIsKey = (node.node === "agent" || node.node === "decide" || node.node === "extract" || node.node === "code") && node.as === undefined;
642
802
  if (labelIsKey && typeof node.label === "string" && node.label.startsWith("$"))
643
- errors.push(`${path} (${node.label}): label must not begin with "$" — an unaliased ${node.node} node writes under its label, and "$" keys are engine-owned`);
803
+ fail("STATE_KEY_RESERVED", ptrOf(path), `${path} (${node.label}): label must not begin with "$" — an unaliased ${node.node} node writes under its label, and "$" keys are engine-owned`);
644
804
  }
645
805
  switch (node.node) {
646
806
  case "chain":
647
807
  if (!Array.isArray(node.steps) || !node.steps.length)
648
- errors.push(`${path}: chain needs steps`);
649
- (node.steps || []).forEach((s, i) => walk(s, `${path}.steps[${i}]`));
808
+ fail("STRUCTURE_INVALID", ptrOf(path), `${path}: chain needs steps`);
809
+ (node.steps || []).forEach((s, i) => walk(s, `${path}.steps[${i}]`, `${ptr}/steps/${i}`));
650
810
  return;
651
811
  case "code":
652
812
  try {
@@ -656,7 +816,7 @@ export function validateWorkflow(workflow, opts) {
656
816
  compileTransform(node.code);
657
817
  }
658
818
  catch (e) {
659
- errors.push(`${path} (${node.label}): ${e?.message || e}`);
819
+ fail("CODE_INVALID", ptrOf(path), `${path} (${node.label}): ${e?.message || e}`);
660
820
  }
661
821
  if (reachability) {
662
822
  const patches = probeCodePatches(node.code, { path, label: node.label });
@@ -686,30 +846,34 @@ export function validateWorkflow(workflow, opts) {
686
846
  if (node.state !== undefined)
687
847
  checkStateMap(node.state, node.label, path);
688
848
  if (!node.instructions?.trim())
689
- errors.push(`${path} (${node.label}): instructions required`);
849
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): instructions required`);
690
850
  if (node.node !== "report" && !Object.hasOwn(workflow.schemas, node.out))
691
- errors.push(`${path} (${node.label}): out schema "${node.out}" not in workflow.schemas`);
692
- if (node.thinking !== undefined && !["low", "medium", "high"].includes(String(node.thinking)))
693
- errors.push(`${path} (${node.label}): thinking must be low|medium|high — thinking is never off`);
851
+ fail("SCHEMA_UNKNOWN", ptrOf(path), `${path} (${node.label}): out schema "${node.out}" not in workflow.schemas`);
852
+ if (node.thinking !== undefined && !THINKING_LEVELS.includes(String(node.thinking)))
853
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): thinking must be low|medium|high — thinking is never off`);
694
854
  if (node.tools !== undefined && (!Array.isArray(node.tools) || node.tools.some((t) => typeof t !== "string" || !t.trim())))
695
- errors.push(`${path} (${node.label}): tools must be a list of non-empty tool names when present (an empty list disables tools)`);
855
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): tools must be a list of non-empty tool names when present (an empty list disables tools)`);
696
856
  checkRequires(node, path);
697
- if (node.tier !== undefined && !["fast", "default", "strong"].includes(String(node.tier)))
698
- errors.push(`${path} (${node.label}): tier must be fast|default|strong`);
857
+ if (node.tier !== undefined && !MODEL_TIERS.includes(String(node.tier)))
858
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): tier must be fast|default|strong`);
859
+ if (node.node === "agent" && node.budget_usd !== undefined && !(typeof node.budget_usd === "number" && Number.isFinite(node.budget_usd) && node.budget_usd > 0))
860
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): budget_usd must be a number of dollars greater than 0`);
861
+ if (node.node === "agent" && node.context !== undefined && !AGENT_CONTEXTS.includes(String(node.context)))
862
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): context must be ${AGENT_CONTEXTS.join("|")}`);
699
863
  if (node.node !== "report" && node.verify !== undefined) {
700
864
  const v = node.verify;
701
865
  if (!v || typeof v !== "object" || typeof v.out !== "string")
702
- errors.push(`${path} (${node.label}): verify needs an out (a question schema id)`);
866
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): verify needs an out (a question schema id)`);
703
867
  else {
704
868
  const qs = checkQuestionSchema(v.out, node.label, path);
705
869
  if (qs && !Object.values(qs).some((q) => q.type === "noul"))
706
- errors.push(`${path} (${node.label}): verify.out "${v.out}" carries no yes/no question — a verifier decides by yes/no (a boolean named after a submission field verifies it; any other boolean is a requirement)`);
870
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): verify.out "${v.out}" carries no yes/no question — a verifier decides by yes/no (a boolean named after a submission field verifies it; any other boolean is a requirement)`);
707
871
  if (v.state !== undefined)
708
872
  checkStateMap(v.state, node.label, path, "verify.state");
709
- if (v.maxDrives !== undefined && (!Number.isInteger(v.maxDrives) || v.maxDrives < 1 || v.maxDrives > 4))
710
- errors.push(`${path} (${node.label}): verify.maxDrives must be an integer 1..4`);
873
+ if (v.maxDrives !== undefined && (!Number.isInteger(v.maxDrives) || v.maxDrives < 1))
874
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): verify.maxDrives must be an integer >= 1`);
711
875
  if (v.override !== undefined && (typeof v.override?.below !== "number" || v.override.below <= 0 || v.override.below >= 1))
712
- errors.push(`${path} (${node.label}): verify.override.below must be in (0, 1)`);
876
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): verify.override.below must be in (0, 1)`);
713
877
  }
714
878
  }
715
879
  if (reachability && node.node === "report") {
@@ -728,66 +892,99 @@ export function validateWorkflow(workflow, opts) {
728
892
  return;
729
893
  case "map":
730
894
  if (node.resultPath !== undefined && (typeof node.resultPath !== "string" || !node.resultPath.trim()))
731
- errors.push(`${path} (${node.label}): resultPath must be a non-empty path in the completed item state`);
895
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): resultPath must be a non-empty path in the completed item state`);
732
896
  if (node.maxConcurrency !== undefined && (!Number.isSafeInteger(node.maxConcurrency) || node.maxConcurrency < 1))
733
- errors.push(`${path} (${node.label}): maxConcurrency must be a positive safe integer`);
897
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): maxConcurrency must be a positive safe integer`);
734
898
  if (!node.itemsPath)
735
- errors.push(`${path} (${node.label}): itemsPath required`);
899
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): itemsPath required`);
736
900
  checkItemsPath(node, path);
737
901
  if (!node.as)
738
- errors.push(`${path} (${node.label}): as required`);
902
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): as required`);
903
+ if (node.onItemFailure !== undefined && node.onItemFailure !== "stop" && node.onItemFailure !== "collect")
904
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): onItemFailure must be "stop" or "collect"`);
905
+ if (node.onItemFailure === "collect") {
906
+ if (typeof node.failedAs !== "string" || !node.failedAs.trim())
907
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): onItemFailure "collect" needs failedAs, the state key the map writes its failed items under`);
908
+ else if (node.failedAs.startsWith("$"))
909
+ fail("STATE_KEY_RESERVED", ptrOf(path), `${path} (${node.label}): failedAs must not name an engine-owned "$" state key ("${node.failedAs}")`);
910
+ else if (node.failedAs === node.as)
911
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): failedAs must differ from as: the map writes its results and its failed items under two keys`);
912
+ }
913
+ else if (node.failedAs !== undefined)
914
+ fail("NODE_KEY_UNKNOWN", ptrOf(path), `${path} (${node.label}): failedAs is written only with onItemFailure "collect"`);
739
915
  if (containsReportNode(node.body))
740
- errors.push(`${path} (${node.label}): a report node cannot live inside a map body — the report is the workflow's ONE terminal rendering (a mapped copy lands in the item results, never at state.report_markdown)`);
916
+ fail("STRUCTURE_INVALID", ptrOf(path), `${path} (${node.label}): a report node cannot live inside a map body — the report is the workflow's ONE terminal rendering (a mapped copy lands in the item results, never at state.report_markdown)`);
741
917
  if (reachability)
742
918
  reachability.unknowable = true;
743
- walk(node.body, `${path}.body`);
919
+ walk(node.body, `${path}.body`, `${ptr}/body`);
744
920
  return;
745
921
  case "parallel":
746
922
  if (!Array.isArray(node.branches) || node.branches.length < 2)
747
- errors.push(`${path} (${node.label}): parallel needs at least two branches`);
923
+ fail("STRUCTURE_INVALID", ptrOf(path), `${path} (${node.label}): parallel needs at least two branches`);
748
924
  if (containsReportNode(node))
749
- errors.push(`${path} (${node.label}): a report node cannot live inside a parallel branch — the report is rendered once, after every branch has landed`);
750
- if (reachability)
751
- reachability.unknowable = true;
925
+ fail("STRUCTURE_INVALID", ptrOf(path), `${path} (${node.label}): a report node cannot live inside a parallel branch — the report is rendered once, after every branch has landed`);
752
926
  {
753
927
  const writers = new Map();
754
928
  (node.branches || []).forEach((branch, i) => {
755
929
  for (const key of declaredWrites(branch)) {
756
930
  const prior = writers.get(key);
757
931
  if (prior !== undefined && prior !== i)
758
- errors.push(`${path} (${node.label}): branches ${prior} and ${i} both write state.${key} — parallel branches must write disjoint keys`);
932
+ fail("PARALLEL_WRITE_CONFLICT", ptrOf(path), `${path} (${node.label}): branches ${prior} and ${i} both write state.${key} — parallel branches must write disjoint keys`);
759
933
  writers.set(key, i);
760
934
  }
761
935
  });
762
936
  }
763
- (node.branches || []).forEach((branch, i) => walk(branch, `${path}.branches[${i}]`));
937
+ {
938
+ // Every branch starts from the state before the parallel node: a branch never sees a sibling's writes.
939
+ // All walk knowledge is restored per branch, then the branches' results merge (their writes are disjoint).
940
+ const before = snapshotKnowledge();
941
+ const after = [];
942
+ (node.branches || []).forEach((branch, i) => {
943
+ restoreKnowledge(before);
944
+ walk(branch, `${path}.branches[${i}]`, `${ptr}/branches/${i}`);
945
+ after.push(snapshotKnowledge());
946
+ });
947
+ if (after.length)
948
+ mergeKnowledge(before, after);
949
+ if (reachability)
950
+ reachability.unknowable = true;
951
+ }
764
952
  return;
765
953
  case "loop":
766
- if (!Number.isInteger(node.maxIters) || node.maxIters < 1 || node.maxIters > 20)
767
- errors.push(`${path} (${node.label}): maxIters must be 1..20`);
954
+ if (!Number.isInteger(node.maxIters) || node.maxIters < 1)
955
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): maxIters must be an integer >= 1`);
956
+ if (node.expect_iters !== undefined && (!Number.isInteger(node.expect_iters) || node.expect_iters < 1))
957
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): expect_iters must be an integer >= 1`);
768
958
  if (containsReportNode(node.body))
769
- errors.push(`${path} (${node.label}): a report node cannot live inside a loop body — the report is rendered once, after the record is final`);
959
+ fail("STRUCTURE_INVALID", ptrOf(path), `${path} (${node.label}): a report node cannot live inside a loop body — the report is rendered once, after the record is final`);
770
960
  checkPredicate(node.until, node.label, path, "until");
961
+ {
962
+ // `until` reads the state after the body: the keys before the loop plus every key the body writes.
963
+ const bodyWrites = loopBodyWrites(node.body);
964
+ if (reachability && !reachability.unknowable && bodyWrites)
965
+ checkPredicateHead(node.until, node.label, path, "until", new Set([...reachability.available, ...bodyWrites]));
966
+ }
771
967
  if (reachability)
772
968
  reachability.unknowable = true;
773
- walk(node.body, `${path}.body`);
969
+ walk(node.body, `${path}.body`, `${ptr}/body`);
774
970
  return;
775
971
  case "escalate":
776
972
  mayEscalate = true;
777
973
  checkPredicate(node.when, node.label, path, "when");
778
974
  if (!node.kind?.trim() || !node.stage?.trim() || !node.summary?.trim())
779
- errors.push(`${path} (${node.label}): kind, stage, summary required`);
975
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): kind, stage, summary required`);
976
+ checkPredicateHead(node.when, node.label, path, "when");
780
977
  checkPredicatePath(node.when, node.label, path);
781
978
  return;
782
979
  case "judge": {
783
980
  const label = node.label || "judge";
784
981
  if (!node.state || typeof node.state !== "object" || Array.isArray(node.state) || !Object.keys(node.state).length)
785
- errors.push(`${path} (${label}): state must be a non-empty object map of what the questions see`);
982
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): state must be a non-empty object map of what the questions see`);
786
983
  else
787
984
  checkStateMap(node.state, label, path);
788
985
  checkQuestionSchema(node.out, label, path);
789
986
  if (!node.as?.trim())
790
- errors.push(`${path} (${label}): as required`);
987
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): as required`);
791
988
  checkRequires({ label, requires: node.requires }, path);
792
989
  if (reachability && node.as) {
793
990
  reachability.available.add(node.as);
@@ -802,17 +999,17 @@ export function validateWorkflow(workflow, opts) {
802
999
  case "pick": {
803
1000
  const label = node.label || "pick";
804
1001
  if (!node.itemsPath?.trim())
805
- errors.push(`${path} (${label}): itemsPath required`);
1002
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): itemsPath required`);
806
1003
  checkItemsPath(node, path);
807
1004
  if (typeof node.describe !== "string" || !node.describe.trim())
808
- errors.push(`${path} (${label}): describe (the option text per item, e.g. "{item.name}, born {item.dob}") required`);
1005
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): describe (the option text per item, e.g. "{item.name}, born {item.dob}") required`);
809
1006
  if (typeof node.instructions !== "string" || !node.instructions.trim())
810
- errors.push(`${path} (${label}): instructions (the one question) required`);
1007
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): instructions (the one question) required`);
811
1008
  checkStateMap(node.state, label, path);
812
1009
  if (!node.as?.trim())
813
- errors.push(`${path} (${label}): as required`);
1010
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): as required`);
814
1011
  if (node.allowNone !== undefined && typeof node.allowNone !== "boolean")
815
- errors.push(`${path} (${label}): allowNone must be boolean`);
1012
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): allowNone must be boolean`);
816
1013
  checkRequires({ label, requires: node.requires }, path);
817
1014
  if (reachability && node.as) {
818
1015
  reachability.available.add(node.as);
@@ -826,27 +1023,27 @@ export function validateWorkflow(workflow, opts) {
826
1023
  case "sift": {
827
1024
  const label = node.label || "sift";
828
1025
  if (!node.itemsPath?.trim())
829
- errors.push(`${path} (${label}): itemsPath required`);
1026
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): itemsPath required`);
830
1027
  checkItemsPath(node, path);
831
1028
  if (node.describe !== undefined && (typeof node.describe !== "string" || !node.describe.trim()))
832
- errors.push(`${path} (${label}): describe must be a non-empty template when present`);
1029
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): describe must be a non-empty template when present`);
833
1030
  checkStateMap(node.state, label, path);
834
1031
  const compiled = checkQuestionSchema(node.out, label, path);
835
1032
  if (!node.as?.trim())
836
- errors.push(`${path} (${label}): as required`);
1033
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): as required`);
837
1034
  if (node.keep !== undefined) {
838
1035
  const k = node.keep;
839
1036
  if (!k || typeof k !== "object" || typeof k.path !== "string" || !k.path.trim())
840
- errors.push(`${path} (${label}): keep.path must name a question id (or <id>.confidence)`);
1037
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): keep.path must name a question id (or <id>.confidence)`);
841
1038
  else if (compiled) {
842
1039
  const [id, tail] = k.path.split(".");
843
1040
  if (!Object.hasOwn(compiled, id) || (tail !== undefined && tail !== "confidence"))
844
- errors.push(`${path} (${label}): keep.path "${k.path}" names no question of schema "${String(node.out)}"`);
1041
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): keep.path "${k.path}" names no question of schema "${String(node.out)}"`);
845
1042
  else if (compiled[id].type === "choice" && tail !== "confidence")
846
- errors.push(`${path} (${label}): keep.path "${k.path}" is a choice — keep on a boolean or score question, or on <id>.confidence`);
1043
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): keep.path "${k.path}" is a choice — keep on a boolean or score question, or on <id>.confidence`);
847
1044
  }
848
1045
  if (k?.gte !== undefined && !(typeof k.gte === "number" && Number.isFinite(k.gte)))
849
- errors.push(`${path} (${label}): keep.gte must be a number`);
1046
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): keep.gte must be a number`);
850
1047
  }
851
1048
  checkRequires({ label, requires: node.requires }, path);
852
1049
  if (reachability && node.as) {
@@ -858,45 +1055,77 @@ export function validateWorkflow(workflow, opts) {
858
1055
  }
859
1056
  case "route": {
860
1057
  const label = node.label || "route";
861
- if (!node.state || typeof node.state !== "object" || Array.isArray(node.state) || !Object.keys(node.state).length)
862
- errors.push(`${path} (${label}): state must be a non-empty object map of what the question sees`);
863
- else
864
- checkStateMap(node.state, label, path);
865
- if (typeof node.instructions !== "string" || !node.instructions.trim())
866
- errors.push(`${path} (${label}): instructions (the one question) required`);
867
- const names = node.branches && typeof node.branches === "object" && !Array.isArray(node.branches) ? Object.keys(node.branches) : [];
868
- if (names.length < 2)
869
- errors.push(`${path} (${label}): route needs at least two named branches`);
870
- if (names.length > SYSTEM_ONE_LIMITS.maxChoiceOptions)
871
- errors.push(`${path} (${label}): route takes at most ${SYSTEM_ONE_LIMITS.maxChoiceOptions} branches`);
872
- if (node.unsure !== undefined) {
873
- const u = node.unsure;
874
- if (!u || typeof u.branch !== "string" || !names.includes(u.branch))
875
- errors.push(`${path} (${label}): unsure.branch must name one of the branches`);
876
- if (!(typeof u?.gte === "number" && u.gte > 0 && u.gte <= 1))
877
- errors.push(`${path} (${label}): unsure.gte must be in (0, 1]`);
1058
+ const raw = node;
1059
+ // Two forms, never mixed: Jev chooses (state + instructions) or state already holds the choice (valuePath).
1060
+ const byValue = raw.valuePath !== undefined;
1061
+ const names = raw.branches && typeof raw.branches === "object" && !Array.isArray(raw.branches) ? Object.keys(raw.branches) : [];
1062
+ if (byValue) {
1063
+ const valuePath = raw.valuePath;
1064
+ if (typeof valuePath !== "string" || !valuePath.trim())
1065
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): valuePath must be the state path of the branch name`);
1066
+ for (const key of ["state", "instructions", "unsure"])
1067
+ if (raw[key] !== undefined)
1068
+ fail("NODE_KEY_UNKNOWN", ptrOf(path), `${path} (${label}): ${key} belongs to a route Jev chooses; a route by valuePath asks no question`);
1069
+ if (names.length < 2)
1070
+ fail("STRUCTURE_INVALID", ptrOf(path), `${path} (${label}): route needs at least two named branches`);
1071
+ if (names.some(name => !name.trim()))
1072
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): branch names must be non-empty`);
1073
+ if (raw.otherwise !== undefined && (typeof raw.otherwise !== "string" || !names.includes(raw.otherwise)))
1074
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): otherwise must name one of the branches`);
1075
+ if (typeof valuePath === "string" && valuePath.trim() && reachability && !reachability.unknowable) {
1076
+ const head = valuePath.split(".")[0];
1077
+ if (!reachability.available.has(head))
1078
+ fail("STATE_PATH_UNPRODUCED", ptrOf(path), `${path} (${label}): valuePath "${valuePath}" has no upstream producer; route by the key an earlier node writes`);
1079
+ else
1080
+ checkTypedPath(valuePath, `${path} (${label}) valuePath`, ptrOf(path));
1081
+ }
1082
+ }
1083
+ else {
1084
+ const judged = node;
1085
+ if (!judged.state || typeof judged.state !== "object" || Array.isArray(judged.state) || !Object.keys(judged.state).length)
1086
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): state must be a non-empty object map of what the question sees`);
1087
+ else
1088
+ checkStateMap(judged.state, label, path);
1089
+ if (typeof judged.instructions !== "string" || !judged.instructions.trim())
1090
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): instructions (the one question) required`);
1091
+ if (raw.otherwise !== undefined)
1092
+ fail("NODE_KEY_UNKNOWN", ptrOf(path), `${path} (${label}): otherwise belongs to a route by valuePath; a route Jev chooses takes unsure for its fallback`);
1093
+ if (names.length < 2)
1094
+ fail("STRUCTURE_INVALID", ptrOf(path), `${path} (${label}): route needs at least two named branches`);
1095
+ if (names.length > SYSTEM_ONE_LIMITS.maxChoiceOptions)
1096
+ fail("STRUCTURE_INVALID", ptrOf(path), `${path} (${label}): route takes at most ${SYSTEM_ONE_LIMITS.maxChoiceOptions} branches`);
1097
+ if (judged.unsure !== undefined) {
1098
+ const u = judged.unsure;
1099
+ if (!u || typeof u.branch !== "string" || !names.includes(u.branch))
1100
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): unsure.branch must name one of the branches`);
1101
+ if (!(typeof u?.gte === "number" && u.gte > 0 && u.gte <= 1))
1102
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): unsure.gte must be in (0, 1]`);
1103
+ }
878
1104
  }
879
1105
  if (containsReportNode(node))
880
- errors.push(`${path} (${label}): a report node cannot live inside a route branch — the report is rendered once, after the record is final`);
1106
+ fail("STRUCTURE_INVALID", ptrOf(path), `${path} (${label}): a report node cannot live inside a route branch — the report is rendered once, after the record is final`);
881
1107
  if (node.as !== undefined && (typeof node.as !== "string" || !node.as.trim()))
882
- errors.push(`${path} (${label}): as must be a state key when present`);
1108
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): as must be a state key when present`);
883
1109
  checkRequires({ label, requires: node.requires }, path);
884
1110
  if (reachability) {
885
1111
  if (typeof node.as === "string" && node.as.trim()) {
886
1112
  reachability.available.add(node.as);
887
- reachability.available.add(`${node.as}$answers`);
1113
+ if (!byValue)
1114
+ reachability.available.add(`${node.as}$answers`);
888
1115
  }
889
1116
  reachability.unknowable = true;
890
1117
  }
891
1118
  for (const name of names) {
892
- const branch = node.branches[name];
1119
+ const branch = raw.branches[name];
893
1120
  if (!branch || typeof branch !== "object" || !branch.body) {
894
- errors.push(`${path} (${label}): branch "${name}" needs a body`);
1121
+ fail("STRUCTURE_INVALID", ptrOf(path), `${path} (${label}): branch "${name}" needs a body`);
895
1122
  continue;
896
1123
  }
897
- if (branch.criteria !== undefined && typeof branch.criteria !== "string")
898
- errors.push(`${path} (${label}): branch "${name}" criteria must be a string`);
899
- walk(branch.body, `${path}.branches.${name}`);
1124
+ if (byValue && branch.criteria !== undefined)
1125
+ fail("NODE_KEY_UNKNOWN", ptrOf(path), `${path} (${label}): branch "${name}" criteria are for Jev; a route by valuePath matches the branch name exactly`);
1126
+ else if (branch.criteria !== undefined && typeof branch.criteria !== "string")
1127
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): branch "${name}" criteria must be a string`);
1128
+ walk(branch.body, `${path}.branches.${name}`, `${ptr}/branches/${pointerKey(name)}/body`);
900
1129
  }
901
1130
  return;
902
1131
  }
@@ -904,14 +1133,14 @@ export function validateWorkflow(workflow, opts) {
904
1133
  const label = node.label || "artifact";
905
1134
  const type = typeof node.type === "string" && node.type.trim() ? node.type : null;
906
1135
  if (!type)
907
- errors.push(`${path} (${label}): artifact type must be a non-empty string`);
1136
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): artifact type must be a non-empty string`);
908
1137
  for (const key of ["instructions", "state", "sopSection", "tools", "effort", "thinking"])
909
1138
  if (node[key] !== undefined)
910
- errors.push(`${path} (${label}): ${key} is a prose-artifact field; a ${type ?? "file"} artifact has no model in the loop`);
1139
+ fail("NODE_KEY_UNKNOWN", ptrOf(path), `${path} (${label}): ${key} is a prose-artifact field; a ${type ?? "file"} artifact has no model in the loop`);
911
1140
  if (typeof node.path !== "string" || !node.path.trim() || node.path.startsWith("/") || node.path.split("/").includes(".."))
912
- errors.push(`${path} (${label}): path must be a workspace-relative file`);
1141
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): path must be a workspace-relative file`);
913
1142
  else if (reachability && !producedFiles.has(node.path))
914
- errors.push(`${path} (${label}): path "${node.path}" is not produced by any earlier shell call (declare it in that call's produces)`);
1143
+ fail("STATE_PATH_UNPRODUCED", ptrOf(path), `${path} (${label}): path "${node.path}" is not produced by any earlier shell call (declare it in that call's produces)`);
915
1144
  checkRequires({ label, requires: node.requires }, path);
916
1145
  if (reachability) {
917
1146
  reachability.available.add("artifact");
@@ -922,23 +1151,26 @@ export function validateWorkflow(workflow, opts) {
922
1151
  case "workflow": {
923
1152
  const label = typeof node.label === "string" && node.label.trim() ? node.label : "workflow";
924
1153
  if (typeof node.label !== "string" || !node.label.trim() || typeof node.as !== "string" || !node.as.trim())
925
- errors.push(`${path} (${label}): a workflow invocation requires label and as`);
1154
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): a workflow invocation requires label and as`);
926
1155
  if (!Object.hasOwn(workflow.schemas, node.out))
927
- errors.push(`${path} (${label}): out schema "${String(node.out)}" not in workflow.schemas`);
1156
+ fail("SCHEMA_UNKNOWN", ptrOf(path), `${path} (${label}): out schema "${String(node.out)}" not in workflow.schemas`);
928
1157
  if (!node.input || typeof node.input !== "object" || Array.isArray(node.input))
929
- errors.push(`${path} (${label}): input must be an object mapping onto the child's initial state`);
1158
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): input must be an object mapping onto the child's initial state`);
1159
+ else if (Object.hasOwn(node.input, HOST_STATE_KEY))
1160
+ fail("STATE_KEY_RESERVED", ptrOf(path), `${path} (${label}): input must not contain the reserved "${HOST_STATE_KEY}" key`);
930
1161
  const child = node.workflow;
931
1162
  const steps = childSteps(child);
932
1163
  if (!child || typeof child !== "object" || !steps || !steps.length)
933
- errors.push(`${path} (${label}): the child workflow must contain a root node`);
1164
+ fail("STRUCTURE_INVALID", ptrOf(path), `${path} (${label}): the child workflow must contain a root node`);
934
1165
  else {
935
1166
  if (containsReportNode(child.root))
936
- errors.push(`${path} (${label}): a child cannot render a report or deliver an artifact; the parent owns the terminal`);
1167
+ fail("STRUCTURE_INVALID", ptrOf(path), `${path} (${label}): a child cannot render a report or deliver an artifact; the parent owns the terminal`);
937
1168
  if (typeof child.input?.schemaId !== "string" || !Object.hasOwn(child.schemas, child.input.schemaId))
938
- errors.push(`${path} (${label}): the child must declare input.schemaId in its own schemas`);
1169
+ fail("WORKFLOW_FIELD_INVALID", `${ptrOf(path)}/workflow`, `${path} (${label}): the child must declare input.schemaId in its own schemas`);
939
1170
  const validated = validateWorkflow(child, { executeCode: opts?.executeCode, inputKeys: Object.keys(node.input && typeof node.input === "object" ? node.input : {}) });
940
1171
  if (!validated.ok)
941
- errors.push(...validated.errors.map(error => `${path} (${label}) child: ${error}`));
1172
+ for (const issue of validated.issues)
1173
+ fail(issue.code, `${ptr}/workflow${issue.path}`, `${path} (${label}) child: ${issue.message}`);
942
1174
  for (const step of steps)
943
1175
  if (step.node === "call" && Array.isArray(step.produces))
944
1176
  for (const file of step.produces)
@@ -954,92 +1186,92 @@ export function validateWorkflow(workflow, opts) {
954
1186
  }
955
1187
  case "call": {
956
1188
  const label = node.label || "call";
957
- if (!["tool", "executor", "shell"].includes(String(node.via)))
958
- errors.push(`${path} (${label}): via must be tool|executor|shell`);
1189
+ if (!CALL_TRANSPORTS.includes(String(node.via)))
1190
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): via must be tool|executor|shell`);
959
1191
  if (node.via === "tool") {
960
1192
  if (!node.tool?.trim())
961
- errors.push(`${path} (${label}): via tool needs a tool address`);
1193
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): via tool needs a tool address`);
962
1194
  if (node.args !== undefined && (!node.args || typeof node.args !== "object" || Array.isArray(node.args)))
963
- errors.push(`${path} (${label}): args must be an object`);
1195
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): args must be an object`);
964
1196
  for (const key of ["code", "input", "command", "env"])
965
1197
  if (node[key] !== undefined)
966
- errors.push(`${path} (${label}): ${key} is not a via tool field`);
1198
+ fail("NODE_KEY_UNKNOWN", ptrOf(path), `${path} (${label}): ${key} is not a via tool field`);
967
1199
  }
968
1200
  if (node.via === "executor") {
969
1201
  if (!node.code?.trim())
970
- errors.push(`${path} (${label}): via executor needs a code body`);
1202
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): via executor needs a code body`);
971
1203
  if (!/\breturn\b/.test(String(node.code || "")))
972
- errors.push(`${path} (${label}): the executor body must return its JSON result`);
1204
+ fail("CODE_INVALID", ptrOf(path), `${path} (${label}): the executor body must return its JSON result`);
973
1205
  if (/\b(require|process|fetch|eval|Function|import)\s*\(?/.test(String(node.code || "")))
974
- errors.push(`${path} (${label}): the executor body may use only tools and input (no require/process/fetch/eval/import)`);
1206
+ fail("CODE_INVALID", ptrOf(path), `${path} (${label}): the executor body may use only tools and input (no require/process/fetch/eval/import)`);
975
1207
  if (node.input !== undefined && (!node.input || typeof node.input !== "object" || Array.isArray(node.input)))
976
- errors.push(`${path} (${label}): input must be an object`);
1208
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): input must be an object`);
977
1209
  for (const key of ["tool", "args", "command", "env"])
978
1210
  if (node[key] !== undefined)
979
- errors.push(`${path} (${label}): ${key} is not a via executor field`);
1211
+ fail("NODE_KEY_UNKNOWN", ptrOf(path), `${path} (${label}): ${key} is not a via executor field`);
980
1212
  }
981
1213
  if (node.via === "shell") {
982
1214
  if (!node.command?.trim())
983
- errors.push(`${path} (${label}): via shell needs a command`);
1215
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): via shell needs a command`);
984
1216
  if (node.env !== undefined && (!node.env || typeof node.env !== "object" || Array.isArray(node.env) || Object.entries(node.env).some(([k, v]) => !/^[A-Z_][A-Z0-9_]*$/.test(k) || typeof v !== "string")))
985
- errors.push(`${path} (${label}): env must map UPPER_CASE names to strings`);
1217
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): env must map UPPER_CASE names to strings`);
986
1218
  if (node.out !== undefined)
987
- errors.push(`${path} (${label}): a shell call's result is the fixed shell shape; drop out`);
1219
+ fail("NODE_KEY_UNKNOWN", ptrOf(path), `${path} (${label}): a shell call's result is the fixed shell shape; drop out`);
988
1220
  for (const key of ["tool", "args", "code", "input"])
989
1221
  if (node[key] !== undefined)
990
- errors.push(`${path} (${label}): ${key} is not a via shell field`);
1222
+ fail("NODE_KEY_UNKNOWN", ptrOf(path), `${path} (${label}): ${key} is not a via shell field`);
991
1223
  }
992
1224
  else if (node.produces?.length) {
993
- errors.push(`${path} (${label}): only a via shell call may declare produces`);
1225
+ fail("NODE_KEY_UNKNOWN", ptrOf(path), `${path} (${label}): only a via shell call may declare produces`);
994
1226
  }
995
1227
  if (node.via !== "shell") {
996
1228
  if (!node.out)
997
- errors.push(`${path} (${label}): out schema required for a ${node.via} call`);
1229
+ fail("SCHEMA_UNKNOWN", ptrOf(path), `${path} (${label}): out schema required for a ${node.via} call`);
998
1230
  else if (!Object.hasOwn(workflow.schemas, node.out))
999
- errors.push(`${path} (${label}): out schema "${node.out}" not in workflow.schemas`);
1231
+ fail("SCHEMA_UNKNOWN", ptrOf(path), `${path} (${label}): out schema "${node.out}" not in workflow.schemas`);
1000
1232
  }
1001
1233
  if (!node.as?.trim())
1002
- errors.push(`${path} (${label}): as required`);
1234
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): as required`);
1003
1235
  if (node.where !== undefined && node.where !== "sandbox")
1004
- errors.push(`${path} (${label}): where accepts only "sandbox"`);
1005
- if (!(Number.isFinite(node.deadline_s) && node.deadline_s > 0 && node.deadline_s <= 3600))
1006
- errors.push(`${path} (${label}): deadline_s must be greater than 0 and at most 3600 seconds`);
1236
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): where accepts only "sandbox"`);
1237
+ if (!(Number.isFinite(node.deadline_s) && node.deadline_s > 0))
1238
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): deadline_s is required and must be a finite number greater than 0 seconds`);
1007
1239
  if (node.produces !== undefined && (!Array.isArray(node.produces) || !node.produces.length || node.produces.some((f) => typeof f !== "string" || !f.trim() || f.startsWith("/") || f.split("/").includes(".."))))
1008
- errors.push(`${path} (${label}): produces must be non-empty workspace-relative paths`);
1240
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): produces must be non-empty workspace-relative paths`);
1009
1241
  else
1010
1242
  for (const f of node.produces || [])
1011
1243
  producedFiles.add(f);
1012
1244
  if (node.retry !== undefined) {
1013
1245
  const r = node.retry;
1014
- if (!r || !Number.isInteger(r.attempts) || r.attempts < 1 || r.attempts > 5)
1015
- errors.push(`${path} (${label}): retry.attempts must be 1..5`);
1016
- if (r?.backoff_s !== undefined && !(Number.isFinite(r.backoff_s) && r.backoff_s >= 0 && r.backoff_s <= 60))
1017
- errors.push(`${path} (${label}): retry.backoff_s must be 0..60`);
1018
- if (r?.on !== undefined && (!Array.isArray(r.on) || r.on.some((c) => !["timeout", "http_5xx", "http_429", "connection", "exit"].includes(String(c)))))
1019
- errors.push(`${path} (${label}): retry.on may name only timeout|http_5xx|http_429|connection|exit`);
1246
+ if (!r || !Number.isInteger(r.attempts) || r.attempts < 1)
1247
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): retry.attempts must be an integer >= 1`);
1248
+ if (r?.backoff_s !== undefined && !(Number.isFinite(r.backoff_s) && r.backoff_s >= 0))
1249
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): retry.backoff_s must be a finite number >= 0`);
1250
+ if (r?.on !== undefined && (!Array.isArray(r.on) || r.on.some((c) => !RETRY_ON_NAMES.includes(String(c)))))
1251
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): retry.on may name only ${RETRY_ON_NAMES.join("|")}`);
1020
1252
  }
1021
1253
  if (node.poll !== undefined) {
1022
1254
  const p = node.poll;
1023
1255
  if (!p || typeof p !== "object" || Array.isArray(p))
1024
- errors.push(`${path} (${label}): poll must be an object`);
1256
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): poll must be an object`);
1025
1257
  else {
1026
1258
  const resultShape = node.via === "shell" ? shapeFromSchema(SHELL_RESULT_SCHEMA) : node.out && (Object.hasOwn(workflow.schemas, node.out) ? workflow.schemas[node.out] : undefined) ? shapeFromSchema(workflow.schemas[node.out]) : undefined;
1027
1259
  for (const [name, pred] of [["until", p.until], ["fail_when", p.fail_when]]) {
1028
1260
  if (pred === undefined) {
1029
1261
  if (name === "until")
1030
- errors.push(`${path} (${label}): poll.until is required`);
1262
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): poll.until is required`);
1031
1263
  continue;
1032
1264
  }
1033
1265
  if (!checkPredicate(pred, label, path, `poll.${name}`, true))
1034
1266
  continue;
1035
1267
  const predPath = pred.path;
1036
1268
  if (resultShape && typeof resultShape === "object" && predPath && resultPathMissing(resultShape, predPath))
1037
- errors.push(`${path} (${label}): poll.${name} path "${predPath}" is not in the declared result shape (${Object.keys(resultShape).join(", ")}); the poll could never settle`);
1269
+ fail("STATE_PATH_EXCLUDED", ptrOf(path), `${path} (${label}): poll.${name} path "${predPath}" is not in the declared result shape (${Object.keys(resultShape).join(", ")}); the poll could never settle`);
1038
1270
  }
1039
- if (!(Number.isFinite(p.interval_s) && p.interval_s >= 0.1 && p.interval_s <= 300))
1040
- errors.push(`${path} (${label}): poll.interval_s must be 0.1..300 seconds`);
1041
- if (!(Number.isFinite(p.deadline_s) && p.deadline_s >= (Number(node.deadline_s) || 0) && p.deadline_s <= 7200))
1042
- errors.push(`${path} (${label}): poll.deadline_s must be at least deadline_s and at most 7200 seconds`);
1271
+ if (!(Number.isFinite(p.interval_s) && p.interval_s >= 0.1))
1272
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): poll.interval_s must be a finite number of at least 0.1 seconds`);
1273
+ if (!(Number.isFinite(p.deadline_s) && p.deadline_s >= (Number(node.deadline_s) || 0)))
1274
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): poll.deadline_s must be a finite number at least deadline_s`);
1043
1275
  }
1044
1276
  }
1045
1277
  checkRequires({ label, requires: node.requires }, path);
@@ -1056,7 +1288,7 @@ export function validateWorkflow(workflow, opts) {
1056
1288
  }
1057
1289
  }
1058
1290
  };
1059
- walk(workflow?.root, "root");
1291
+ walk(workflow?.root, "root", "/root");
1060
1292
  {
1061
1293
  const countReports = (node) => {
1062
1294
  if (!node || typeof node !== "object")
@@ -1075,39 +1307,42 @@ export function validateWorkflow(workflow, opts) {
1075
1307
  };
1076
1308
  const total = countReports(workflow?.root);
1077
1309
  if (total > 1)
1078
- errors.push(`root: at most ONE terminal node (report or artifact) — a second rendering overwrites the first at its fixed state key`);
1310
+ fail("STRUCTURE_INVALID", "/root", `root: at most ONE terminal node (report or artifact) — a second rendering overwrites the first at its fixed state key`);
1079
1311
  else if (total === 1) {
1080
1312
  const rootSteps = workflow?.root?.node === "chain" ? workflow.root.steps || [] : [workflow?.root];
1081
1313
  const lastStep = rootSteps[rootSteps.length - 1];
1082
1314
  if (!lastStep || (lastStep.node !== "report" && lastStep.node !== "artifact")) {
1083
- errors.push(`root: the terminal node (report or artifact) must be the LAST step of the root chain — rendered earlier it ships a record that later nodes still change`);
1315
+ fail("STRUCTURE_INVALID", "/root", `root: the terminal node (report or artifact) must be the LAST step of the root chain — rendered earlier it ships a record that later nodes still change`);
1084
1316
  }
1085
1317
  }
1086
1318
  }
1087
1319
  {
1320
+ // Each placement with its pointer: one node object a TypeScript author placed twice is two nodes of the document.
1088
1321
  const llmNodes = [];
1089
- const collect = (node) => {
1322
+ const collect = (node, ptr) => {
1090
1323
  if (!node || typeof node !== "object")
1091
1324
  return;
1092
1325
  if (node.node === "agent" || node.node === "decide" || node.node === "extract" || node.node === "report")
1093
- llmNodes.push(node);
1326
+ llmNodes.push({ node, ptr });
1094
1327
  if (node.node === "chain")
1095
- (node.steps || []).forEach(collect);
1328
+ (node.steps || []).forEach((step, i) => collect(step, `${ptr}/steps/${i}`));
1096
1329
  if (node.node === "parallel")
1097
- (node.branches || []).forEach(collect);
1330
+ (node.branches || []).forEach((branch, i) => collect(branch, `${ptr}/branches/${i}`));
1098
1331
  if (node.node === "map" || node.node === "loop")
1099
- collect(node.body);
1332
+ collect(node.body, `${ptr}/body`);
1100
1333
  if (node.node === "route")
1101
- routeBodies(node).forEach(collect);
1334
+ for (const [name, branch] of Object.entries(node.branches || {}))
1335
+ if (branch?.body)
1336
+ collect(branch.body, `${ptr}/branches/${pointerKey(name)}/body`);
1102
1337
  };
1103
- collect(workflow?.root);
1104
- if (llmNodes.some((n) => n.node === "report")) {
1105
- for (const node of llmNodes) {
1338
+ collect(workflow?.root, "/root");
1339
+ if (llmNodes.some(({ node }) => node.node === "report")) {
1340
+ for (const { node, ptr } of llmNodes) {
1106
1341
  if (node.node === "report" || node.node === "agent")
1107
1342
  continue;
1108
1343
  const properties = (Object.hasOwn(workflow.schemas, node.out) ? workflow.schemas[node.out] : undefined)?.properties;
1109
1344
  if (properties && Object.prototype.hasOwnProperty.call(properties, "report_markdown")) {
1110
- errors.push(`root (${node.label}): a ${node.node} node must not emit report_markdown — the report node owns the report; drop the field from schema "${node.out}"`);
1345
+ fail("STRUCTURE_INVALID", ptr, `root (${node.label}): a ${node.node} node must not emit report_markdown — the report node owns the report; drop the field from schema "${node.out}"`);
1111
1346
  }
1112
1347
  }
1113
1348
  }
@@ -1115,9 +1350,9 @@ export function validateWorkflow(workflow, opts) {
1115
1350
  if (reachability && !reachability.unknowable && !mayEscalate && workflow?.output?.path) {
1116
1351
  const head = workflow.output.path.split(".")[0];
1117
1352
  if (!reachability.available.has(head))
1118
- errors.push(`output: path "${workflow.output.path}" has no input or upstream producer; select the final node's as key (or label when as is omitted)`);
1353
+ fail("STATE_PATH_UNPRODUCED", "", `output: path "${workflow.output.path}" has no input or upstream producer; select the final node's as key (or label when as is omitted)`);
1119
1354
  else
1120
- checkTypedPath(workflow.output.path, "output");
1355
+ checkTypedPath(workflow.output.path, "output", "");
1121
1356
  }
1122
1357
  // Output-completeness: when the node writing the output path is a probeable code node, its
1123
1358
  // probed shape must carry every REQUIRED key of the output schema. A required field added to
@@ -1163,16 +1398,15 @@ export function validateWorkflow(workflow, opts) {
1163
1398
  bestMissing = missing;
1164
1399
  }
1165
1400
  if (bestMissing?.length) {
1166
- errors.push(`output: the code node writing "${workflow.output.path}" never emits required field(s) ${bestMissing.join(", ")} of schema "${workflow.output.schemaId}" — every run would fail output validation`);
1401
+ fail("STATE_PATH_EXCLUDED", "", `output: the code node writing "${workflow.output.path}" never emits required field(s) ${bestMissing.join(", ")} of schema "${workflow.output.schemaId}" — every run would fail output validation`);
1167
1402
  }
1168
1403
  }
1169
1404
  }
1170
1405
  if (!errors.length)
1171
- errors.push(...workflowShapeErrors(workflow, true));
1172
- return errors.length ? { ok: false, errors } : { ok: true };
1173
- }
1174
- function getPath(value, path) {
1175
- return path.split(".").reduce((acc, key) => (acc == null ? acc : acc[key]), value);
1406
+ for (const issue of workflowShapeIssues(workflow, true))
1407
+ fail("SHAPE_INVALID", issue.path, issue.message);
1408
+ const warnings = workflowWarnings(workflow);
1409
+ return errors.length ? { ok: false, errors, issues, ...(warnings.length ? { warnings } : {}) } : { ok: true, ...(warnings.length ? { warnings } : {}) };
1176
1410
  }
1177
1411
  function interpolate(template, state) {
1178
1412
  return template.replace(/\{([a-zA-Z0-9_.$]+)\}/g, (_, p) => {
@@ -1193,17 +1427,18 @@ async function evaluatePredicate(pred, state, deps, at) {
1193
1427
  if (pred.predicate !== "ask")
1194
1428
  return { holds: predicateMatches(pred, state) };
1195
1429
  const ask = pred;
1196
- const runJudge = requireJudge(deps, `${at.kind} (ask predicate)`, at.label);
1197
1430
  const asked = ask.state ? interpolateValue(ask.state, state, at.label) : promptStateOf(state);
1198
1431
  const questions = { holds: { type: "noul", instructions: ask.instructions, ...(ask.criteria ? { criteria: ask.criteria } : {}) } };
1199
- const result = await runJudge({ label: at.label, kind: "ask", state: asked, questions, signal: deps.signal });
1200
- validateAnswers(questions, result.answers);
1201
- const answer = result.answers.holds;
1202
- const p = answer?.type === "noul" ? answer.noul : NaN;
1203
- if (!Number.isFinite(p))
1204
- throw new Error(`${at.kind} node "${at.label}": the ask predicate got no yes/no answer`);
1205
1432
  const gte = ask.gte ?? 0.6;
1206
- deps.onEvent?.({ type: "ask.evaluated", label: at.label, detail: { kind: at.kind, p_yes: +p.toFixed(4), gte, holds: p >= gte, model: result.model ?? null, cost_usd: result.cost_usd ?? null } });
1433
+ const decided = await decide(deps, { nodeKind: `${at.kind} (ask predicate)`, kind: "ask", judgeKind: "ask", label: at.label, state: asked, questions }, (answers) => {
1434
+ const answer = answers.holds;
1435
+ const p = answer?.type === "noul" ? answer.noul : NaN;
1436
+ if (!Number.isFinite(p))
1437
+ throw new Error(`${at.kind} node "${at.label}": the ask predicate got no yes/no answer`);
1438
+ return { rule: { kind: "ask", gte }, action: { holds: p >= gte }, value: p };
1439
+ });
1440
+ const p = decided.value;
1441
+ deps.onEvent?.({ type: "ask.evaluated", label: at.label, detail: { kind: at.kind, p_yes: +p.toFixed(4), gte, holds: p >= gte, ...meteringOf(decided), decision_id: decided.id } });
1207
1442
  return { holds: p >= gte, detail: { p_yes: p, gte } };
1208
1443
  }
1209
1444
  function promptStateOf(state) {
@@ -1225,12 +1460,15 @@ export function schemaProblems(validator, candidate) {
1225
1460
  export class WorkflowInvalidError extends Error {
1226
1461
  workflowName;
1227
1462
  problems;
1463
+ issues;
1228
1464
  code = "workflow_invalid";
1229
1465
  stage = "validate";
1230
- constructor(workflowName, problems) {
1466
+ /** `problems` are validateWorkflow's `errors`; `issues` its issues, one per problem in the same order. */
1467
+ constructor(workflowName, problems, issues = []) {
1231
1468
  super(`workflow "${workflowName}" is invalid: ${problems.join("; ")}`);
1232
1469
  this.workflowName = workflowName;
1233
1470
  this.problems = problems;
1471
+ this.issues = issues;
1234
1472
  this.name = "WorkflowInvalidError";
1235
1473
  }
1236
1474
  }
@@ -1318,6 +1556,46 @@ export class WorkflowStateError extends Error {
1318
1556
  this.name = "WorkflowStateError";
1319
1557
  }
1320
1558
  }
1559
+ /** Whether an item's failure is one a map with `onItemFailure: "collect"` ends the item on: one of the interpreter's own
1560
+ * typed node failures (a call that failed after its retries, output that does not match its schema, a state contract, a
1561
+ * code transform, a failed verification), or a host's failure that declares itself one, with a string `code` and
1562
+ * `itemFailure: true`. Never one whose cause chain holds an effect whose outcome is unknown, a recovery failure, an
1563
+ * escalation or an abort, never several failures at once, and nothing else: a new error class is never collected by
1564
+ * accident. */
1565
+ export function isItemFailure(error) {
1566
+ if (!(error instanceof Error) || error instanceof AggregateError || isRecoveryError(error))
1567
+ return false;
1568
+ for (let current = error, depth = 0; current && depth < 16; current = current.cause, depth += 1) {
1569
+ if (current instanceof EffectOutcomeUnknownError || current instanceof EscalationSignal || current instanceof AggregateError
1570
+ || current.name === "AbortError")
1571
+ return false;
1572
+ }
1573
+ if (error instanceof EffectFailure || error instanceof WorkflowOutputInvalidError || error instanceof WorkflowStateError
1574
+ || error instanceof WorkflowCodeError || error instanceof WorkflowVerificationError)
1575
+ return true;
1576
+ return typeof error.code === "string" && error.itemFailure === true;
1577
+ }
1578
+ /** The failure a structure reports when several of its branches (a parallel's, a stopping map's items) fail at once: the
1579
+ * first, unless that is an item failure and another is not, whichever came first. An item failure never hides a failure a
1580
+ * collecting map must stop on. A sibling that ended on the structure's own stop (its reason, or an abort) is not one. */
1581
+ function reportedFailure(first, others) {
1582
+ if (!isItemFailure(first))
1583
+ return first;
1584
+ return others.find((error) => error !== first && error?.name !== "AbortError" && !isItemFailure(error)) ?? first;
1585
+ }
1586
+ /** The label of the step an error failed in, set as the error leaves the innermost step and prefixed by every child
1587
+ * invocation it leaves, as the child's events are: the row of a collected item names the node that failed. */
1588
+ const failedSteps = new WeakMap();
1589
+ /** A collected item's row. A failure that left no step (the map's own `resultPath` check) is the map's. */
1590
+ function itemFailureRow(index, error, mapLabel) {
1591
+ const code = error.code;
1592
+ return {
1593
+ item_index: index,
1594
+ label: failedSteps.get(error) ?? mapLabel,
1595
+ code: typeof code === "string" ? code : "effect_failed",
1596
+ message: String(error.message || error).slice(0, 300),
1597
+ };
1598
+ }
1321
1599
  export function stageSchemaForNode(workflow, node) {
1322
1600
  if (node.node === "report")
1323
1601
  return REPORT_SCHEMA;
@@ -1394,8 +1672,8 @@ const sleep = (ms, signal) => new Promise((resolve, reject) => {
1394
1672
  reject(signal.reason ?? new Error("workflow aborted"));
1395
1673
  return;
1396
1674
  }
1397
- const aborted = () => { clearTimeout(timer); reject(signal?.reason ?? new Error("workflow aborted")); };
1398
- const timer = setTimeout(() => { signal?.removeEventListener("abort", aborted); resolve(); }, ms);
1675
+ const aborted = () => { timer.clear(); reject(signal?.reason ?? new Error("workflow aborted")); };
1676
+ const timer = setLongTimeout(() => { signal?.removeEventListener("abort", aborted); resolve(); }, ms);
1399
1677
  signal?.addEventListener("abort", aborted, { once: true });
1400
1678
  });
1401
1679
  async function runCallNode(node, state, workflow, deps) {
@@ -1434,7 +1712,7 @@ async function runCallNode(node, state, workflow, deps) {
1434
1712
  throw new EffectFailure(`call node "${node.label}" poll exceeded its ${node.poll?.deadline_s}s deadline`, "timeout");
1435
1713
  const controller = new AbortController();
1436
1714
  const attemptMs = Math.max(1, Math.min(node.deadline_s * 1000, remainingMs <= 0 && deps.recovery ? Infinity : remainingMs));
1437
- const attemptDeadlineMs = Date.now() + attemptMs;
1715
+ const attemptDeadlineMs = performance.now() + attemptMs;
1438
1716
  let settled;
1439
1717
  let unknownOutcome;
1440
1718
  let interruptionCheck;
@@ -1470,16 +1748,29 @@ async function runCallNode(node, state, workflow, deps) {
1470
1748
  };
1471
1749
  const onAbort = () => interrupt("cancelled", deps.signal?.reason);
1472
1750
  deps.signal?.addEventListener("abort", onAbort, { once: true });
1473
- const timer = setTimeout(() => interrupt("deadline"), attemptMs);
1751
+ // libuv may fire a timer up to 1 ms before the requested instant. Re-read the monotonic
1752
+ // clock and re-arm for the remainder, so the deadline never interrupts an effect early.
1753
+ // setLongTimeout keeps a deadline past Node's 2^31-1 ms timer limit from overflowing.
1754
+ let timer;
1755
+ const armDeadline = (ms) => {
1756
+ timer = setLongTimeout(() => {
1757
+ const remainingMs = attemptDeadlineMs - performance.now();
1758
+ if (remainingMs > 0)
1759
+ armDeadline(Math.ceil(remainingMs));
1760
+ else
1761
+ interrupt("deadline");
1762
+ }, ms);
1763
+ };
1764
+ armDeadline(attemptMs);
1474
1765
  try {
1475
1766
  deps.onEvent?.({ type: "effect.attempt", label: node.label, detail: { via: node.via, attempt, idempotency_key: idempotencyKey } });
1476
1767
  Promise.resolve().then(() => {
1477
1768
  if (deps.signal?.aborted)
1478
1769
  throw deps.signal.reason ?? new Error("workflow aborted");
1479
- if (controller.signal.aborted || Date.now() >= attemptDeadlineMs) {
1770
+ if (controller.signal.aborted || performance.now() >= attemptDeadlineMs) {
1480
1771
  throw new EffectFailure(`call node "${node.label}" deadline elapsed before effect admission`, "timeout");
1481
1772
  }
1482
- return deps.runEffect({ node: effectNode, schema, input, produces, attempt, idempotencyKey, signal: controller.signal });
1773
+ return deps.runEffect({ node: effectNode, schema, input, produces, attempt, idempotencyKey, signal: controller.signal, ...(Number.isFinite(attemptDeadlineMs) ? { deadlineAt: attemptDeadlineMs } : {}) });
1483
1774
  }).then(value => finish({ status: "fulfilled", value }), reason => finish({ status: "rejected", reason }));
1484
1775
  const outcome = await Promise.race([settlement, interrupted]);
1485
1776
  if (outcome.status === "unknown")
@@ -1489,7 +1780,7 @@ async function runCallNode(node, state, workflow, deps) {
1489
1780
  result = outcome.value;
1490
1781
  if (deps.signal?.aborted)
1491
1782
  throw deps.signal.reason ?? new Error("workflow aborted");
1492
- if (controller.signal.aborted || Date.now() >= attemptDeadlineMs)
1783
+ if (controller.signal.aborted || performance.now() >= attemptDeadlineMs)
1493
1784
  throw new EffectDeadlineExceededError(node.label, result);
1494
1785
  failed = false;
1495
1786
  lastError = undefined;
@@ -1504,16 +1795,21 @@ async function runCallNode(node, state, workflow, deps) {
1504
1795
  ? new EffectFailure(cutByPoll ? `call node "${node.label}" poll exceeded its ${node.poll?.deadline_s}s deadline` : `call node "${node.label}" exceeded its ${node.deadline_s}s deadline`, "timeout")
1505
1796
  : error;
1506
1797
  const retryClass = lastError instanceof EffectFailure ? lastError.retryClass : null;
1798
+ // The row's `code` is closed: an EffectFailure's code when it is one of EFFECT_FAILURE_CODES, else
1799
+ // null. Any other typed error's own code (an unknown outcome, a host's receipts failure) rides
1800
+ // beside it as `error_code`, never as `code`.
1801
+ const code = lastError instanceof EffectFailure && EFFECT_FAILURE_CODES.includes(lastError.code) ? lastError.code : null;
1802
+ const errorCode = code === null && typeof lastError?.code === "string" ? lastError.code : null;
1507
1803
  // Durable admission is uncertain after failure; only the host can reconcile it.
1508
- const retryable = !deps.signal?.aborted && !deps.recovery && retryClass !== null && retryOn.has(retryClass) && attempt < attempts;
1509
- deps.onEvent?.({ type: "effect.failed", label: node.label, detail: { via: node.via, attempt, retry_class: retryClass, retrying: retryable, ...(lastError instanceof EffectOutcomeUnknownError ? { outcome: "unknown", interruption: lastError.interruption, idempotency_key: idempotencyKey } : {}), message: String(lastError?.message || lastError).slice(0, 300) } });
1804
+ const retryable = !deps.signal?.aborted && !deps.recovery && ((retryClass !== null && retryOn.has(retryClass)) || (code !== null && retryOn.has(code))) && attempt < attempts;
1805
+ deps.onEvent?.({ type: "effect.failed", label: node.label, detail: { ...(lastError instanceof EffectFailure ? lastError.detail : undefined), via: node.via, attempt, code, ...(errorCode !== null ? { error_code: errorCode } : {}), retry_class: retryClass, retrying: retryable, ...(lastError instanceof EffectOutcomeUnknownError ? { outcome: "unknown", interruption: lastError.interruption, idempotency_key: idempotencyKey } : {}), message: String(lastError?.message || lastError).slice(0, 300) } });
1510
1806
  if (!retryable || (budgetUntilMs !== undefined && Date.now() >= budgetUntilMs))
1511
1807
  break;
1512
1808
  const delay = Math.min((node.retry?.backoff_s ?? 1) * 1000 * attempt, budgetUntilMs === undefined ? Infinity : Math.max(0, budgetUntilMs - Date.now()));
1513
1809
  await sleep(delay, deps.signal);
1514
1810
  }
1515
1811
  finally {
1516
- clearTimeout(timer);
1812
+ timer?.clear();
1517
1813
  if (interruptionCheck)
1518
1814
  clearImmediate(interruptionCheck);
1519
1815
  deps.signal?.removeEventListener("abort", onAbort);
@@ -1571,13 +1867,62 @@ async function runCallNode(node, state, workflow, deps) {
1571
1867
  }
1572
1868
  return { ...state, [node.as]: result };
1573
1869
  }
1574
- function assertQuestionCount(deps, count, label) {
1870
+ function questionLimit(deps) {
1575
1871
  const limit = deps.maxQuestionsPerRequest ?? 256;
1576
1872
  if (!Number.isSafeInteger(limit) || limit < 1)
1577
1873
  throw new Error("maxQuestionsPerRequest must be a positive safe integer");
1874
+ return limit;
1875
+ }
1876
+ function stateByteLimit(deps) {
1877
+ const limit = deps.maxStateBytesPerRequest;
1878
+ if (limit === undefined)
1879
+ return null;
1880
+ if (!Number.isSafeInteger(limit) || limit < 1)
1881
+ throw new Error("maxStateBytesPerRequest must be a positive safe integer");
1882
+ return limit;
1883
+ }
1884
+ function assertQuestionCount(deps, count, label) {
1885
+ const limit = questionLimit(deps);
1886
+ stateByteLimit(deps);
1578
1887
  if (count > limit)
1579
1888
  throw new Error(`node "${label}": ${count} questions exceed maxQuestionsPerRequest (${limit}); reduce the collection/question set or raise the host limit`);
1580
1889
  }
1890
+ const utf8Bytes = (text) => Buffer.byteLength(text, "utf8");
1891
+ /** A split sift's requests in flight at once: the same default as `map.maxConcurrency`. A host that
1892
+ * needs fewer bounds its own `runJudge`. */
1893
+ const SIFT_REQUESTS_IN_FLIGHT = 4;
1894
+ /** Splits a sift's items, in order, into requests that each fit the host's question limit and, when set,
1895
+ * its state byte limit: the UTF-8 length of the JSON state the judge receives, as the Jev adapter
1896
+ * measures it. Sizes are exact: JSON of `{...base, items: [a, b]}` is JSON of `{...base, items: []}`
1897
+ * plus each item's JSON plus one comma between items. */
1898
+ function siftChunks(deps, label, questionsPerItem, base, named) {
1899
+ const maxQuestions = questionLimit(deps);
1900
+ const maxBytes = stateByteLimit(deps);
1901
+ if (questionsPerItem > maxQuestions)
1902
+ throw new Error(`node "${label}": ${questionsPerItem} questions exceed maxQuestionsPerRequest (${maxQuestions}); reduce the question set or raise the host limit`);
1903
+ const perRequest = Math.floor(maxQuestions / questionsPerItem);
1904
+ const emptyBytes = maxBytes === null ? 0 : utf8Bytes(JSON.stringify({ ...base, items: [] }));
1905
+ if (maxBytes !== null && emptyBytes > maxBytes)
1906
+ throw new Error(`sift node "${label}": its state alone, before any item, is ${emptyBytes} bytes, over maxStateBytesPerRequest (${maxBytes}); every request carries that state, so make the sift's state smaller or raise the host limit`);
1907
+ const chunks = [];
1908
+ let chunk = [], bytes = emptyBytes;
1909
+ for (let i = 0; i < named.length; i += 1) {
1910
+ const itemBytes = maxBytes === null ? 0 : utf8Bytes(JSON.stringify(named[i]));
1911
+ if (maxBytes !== null && emptyBytes + itemBytes > maxBytes)
1912
+ throw new Error(`sift node "${label}": item ${i} alone makes a ${emptyBytes + itemBytes}-byte judge state, over maxStateBytesPerRequest (${maxBytes}); send less of each item (a code step before the sift) or raise the host limit`);
1913
+ const grown = bytes + itemBytes + (chunk.length ? 1 : 0);
1914
+ if (chunk.length && (chunk.length >= perRequest || (maxBytes !== null && grown > maxBytes))) {
1915
+ chunks.push(chunk);
1916
+ chunk = [];
1917
+ bytes = emptyBytes;
1918
+ }
1919
+ bytes += itemBytes + (chunk.length ? 1 : 0);
1920
+ chunk.push(i);
1921
+ }
1922
+ if (chunk.length)
1923
+ chunks.push(chunk);
1924
+ return chunks;
1925
+ }
1581
1926
  const requireJudge = (deps, kind, label) => {
1582
1927
  if (!deps.runJudge)
1583
1928
  throw new Error(`${kind} node "${label}": this runner has no System One runner (deps.runJudge)`);
@@ -1586,6 +1931,124 @@ const requireJudge = (deps, kind, label) => {
1586
1931
  return deps.runJudge(params);
1587
1932
  };
1588
1933
  };
1934
+ const sha256Hex = (text) => createHash("sha256").update(text).digest("hex");
1935
+ /** A text of any value, for a digest, in which two values that differ never read the same. JSON values are
1936
+ * spelled as JSON with sorted keys. Everything JSON cannot say is a bare word no JSON value produces: a
1937
+ * bigint as its digits and `n`, `undefined`, a non-finite number by name, a date, map or set under its
1938
+ * type's name, an object of another class under its constructor's name, and a reference back to an
1939
+ * enclosing object as `~` and how far out it is. So hashing never refuses a state a host is free to hand
1940
+ * its judge, and a state can share a decision id only with itself. */
1941
+ function digestText(value, enclosing = []) {
1942
+ switch (typeof value) {
1943
+ case "string":
1944
+ case "boolean": return JSON.stringify(value);
1945
+ case "number": return Number.isFinite(value) ? JSON.stringify(value) : String(value);
1946
+ case "bigint": return `${value}n`;
1947
+ case "undefined":
1948
+ case "function":
1949
+ case "symbol": return typeof value;
1950
+ }
1951
+ if (value === null)
1952
+ return "null";
1953
+ const object = value;
1954
+ const out = enclosing.lastIndexOf(object);
1955
+ if (out !== -1)
1956
+ return `~${enclosing.length - 1 - out}`;
1957
+ const inside = [...enclosing, object];
1958
+ const list = (entries) => `[${entries.map((entry) => digestText(entry, inside)).join(",")}]`;
1959
+ if (Array.isArray(object))
1960
+ return list(object);
1961
+ if (object instanceof Date)
1962
+ return `Date(${object.getTime()})`;
1963
+ if (object instanceof Map)
1964
+ return `Map${list([...object])}`;
1965
+ if (object instanceof Set)
1966
+ return `Set${list([...object])}`;
1967
+ if (ArrayBuffer.isView(object))
1968
+ return `${object.constructor.name}${list([...new Uint8Array(object.buffer, object.byteOffset, object.byteLength)])}`;
1969
+ const prototype = Object.getPrototypeOf(object);
1970
+ const name = prototype === null || prototype === Object.prototype ? "" : String(prototype.constructor?.name ?? "?");
1971
+ const record = object;
1972
+ return `${name}{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${digestText(record[key], inside)}`).join(",")}}`;
1973
+ }
1974
+ /** A persistence failure of a decision receipt. It fails the node: the answers were never applied. */
1975
+ export class WorkflowDecisionRecordError extends Error {
1976
+ label;
1977
+ decisionId;
1978
+ constructor(label, decisionId, cause) {
1979
+ super(`node "${label}": the decision receipt ${decisionId} could not be recorded: ${String(cause?.message || cause).slice(0, 300)}`, { cause });
1980
+ this.label = label;
1981
+ this.decisionId = decisionId;
1982
+ this.name = "WorkflowDecisionRecordError";
1983
+ }
1984
+ }
1985
+ /** One typed-question request from identity to receipt. `settle` turns validated answers into the rule,
1986
+ * the action and whatever the caller applies; it throws exactly what the node would throw for answers it
1987
+ * refuses. In order: an `answered` receipt the host's recovery holds under the request's id answers it
1988
+ * with no judge call and no new receipt; otherwise the judge is asked, and the receipt (answered, failed
1989
+ * or cancelled) is recorded and awaited before this returns or throws. */
1990
+ async function decide(deps, ask, settle) {
1991
+ const runJudge = requireJudge(deps, ask.nodeKind, ask.label);
1992
+ const path = executionPath(deps);
1993
+ const item = deps[MAP_ITEM];
1994
+ const signal = ask.signal ?? deps.signal;
1995
+ const position = ask.request ?? { index: 0, count: 1 };
1996
+ const state_sha256 = sha256Hex(digestText(ask.state));
1997
+ const id = sha256Hex(canonicalJson(["decision-v1", path, ask.kind, position.index, ask.questions, state_sha256]));
1998
+ const recorded = deps.recovery?.decision ? await deps.recovery.decision(id) : undefined;
1999
+ if (recorded?.status === "answered") {
2000
+ validateAnswers(ask.questions, recorded.answers);
2001
+ const { value } = settle(recorded.answers);
2002
+ return { id, answers: recorded.answers, value, model: recorded.model ?? null, cost_usd: 0, replayed: true };
2003
+ }
2004
+ const request = { label: ask.label, kind: ask.judgeKind, ...(item ? { item } : {}), executionPath: path, signal, state: ask.state, questions: ask.questions, decisionId: id };
2005
+ const startedAt = Date.now();
2006
+ const receipt = (result, outcome) => ({
2007
+ v: DECISION_RECEIPT_VERSION, id, at: new Date().toISOString(), node: ask.label, kind: ask.kind, item: item?.index ?? null, execution_path: path, request: position,
2008
+ status: outcome.status, state_sha256, questions: ask.questions,
2009
+ answers: result?.answers && typeof result.answers === "object" && !Array.isArray(result.answers) ? result.answers : {},
2010
+ rule: outcome.rule, action: outcome.action,
2011
+ model: result?.model ?? null, usage: result?.usage ?? null, cost_usd: typeof result?.cost_usd === "number" ? result.cost_usd : null, request_sha256: result?.request_sha256 ?? null,
2012
+ latency_ms: Date.now() - startedAt,
2013
+ ...(outcome.error !== undefined ? { error: String(outcome.error?.message || outcome.error).slice(0, 2000) } : {}),
2014
+ });
2015
+ /** Records `made`; with `failure`, the request's own failure, a recorder that also fails surfaces both. */
2016
+ const record = async (made, result, failure) => {
2017
+ if (!deps.recordDecision)
2018
+ return;
2019
+ try {
2020
+ await deps.recordDecision(made, { request, ...(result !== undefined ? { result } : {}) });
2021
+ }
2022
+ catch (cause) {
2023
+ const lost = new WorkflowDecisionRecordError(ask.label, id, cause);
2024
+ throw failure ? new AggregateError([failure.error, lost], `${String(failure.error?.message || failure.error)}; and ${lost.message}`) : lost;
2025
+ }
2026
+ };
2027
+ let result;
2028
+ try {
2029
+ result = await runJudge(request);
2030
+ }
2031
+ catch (error) {
2032
+ // The status is read before the caller reacts: a request that fails on its own is `failed`, even when
2033
+ // its failure is what cancels the others.
2034
+ const failed = receipt(undefined, { status: signal?.aborted ? "cancelled" : "failed", rule: null, action: null, error });
2035
+ ask.onFailure?.(error);
2036
+ await record(failed, undefined, { error });
2037
+ throw error;
2038
+ }
2039
+ let settled;
2040
+ try {
2041
+ validateAnswers(ask.questions, result.answers);
2042
+ settled = settle(result.answers);
2043
+ }
2044
+ catch (error) {
2045
+ ask.onFailure?.(error);
2046
+ await record(receipt(result, { status: "failed", rule: null, action: null, error }), result, { error });
2047
+ throw error;
2048
+ }
2049
+ await record(receipt(result, { status: "answered", rule: settled.rule, action: settled.action }), result);
2050
+ return { id, answers: result.answers, value: settled.value, model: result.model ?? null, cost_usd: result.cost_usd ?? null, replayed: false };
2051
+ }
1589
2052
  function questionSetOf(workflow, node) {
1590
2053
  const schema = resolveSchemaForWorkflow(workflow, workflow.schemas[node.out]);
1591
2054
  const compiled = compileQuestions(schema, workflow.schemas);
@@ -1603,18 +2066,19 @@ function questionSetOf(workflow, node) {
1603
2066
  };
1604
2067
  }
1605
2068
  const describeItem = (template, state, item, index) => interpolate(template, { ...state, item, item_index: index }).replace(/\s+/g, " ").trim();
1606
- async function askQuestions(deps, node, asked, questions) {
1607
- const runJudge = requireJudge(deps, node.node, node.label);
1608
- const result = await runJudge({ label: node.label, kind: node.node, state: asked, questions, signal: deps.signal });
1609
- validateAnswers(questions, result.answers);
1610
- return { answers: result.answers, sidecar: answersSidecar(result.answers), model: result.model ?? null, cost_usd: result.cost_usd ?? null };
1611
- }
2069
+ /** What a decision event says of the request behind it: who answered, what it cost, and that a recorded
2070
+ * decision answered it when one did. */
2071
+ const meteringOf = (decided) => ({ model: decided.model, cost_usd: decided.cost_usd, ...(decided.replayed ? { replayed: true } : {}) });
1612
2072
  async function runJudgeNode(node, state, workflow, deps) {
1613
2073
  assertNodeInputs(node, state);
1614
2074
  const set = questionSetOf(workflow, node);
1615
- const { answers, sidecar, model, cost_usd } = await askQuestions(deps, node, interpolateValue(node.state, state, node.label), set.questions);
1616
- const value = set.decode(answers);
1617
- deps.onEvent?.({ type: "judge.answered", label: node.label, detail: { kind: "judge", as: node.as, value, sidecar, model, cost_usd } });
2075
+ const decided = await decide(deps, { nodeKind: "judge", kind: "judge", judgeKind: "judge", label: node.label, state: interpolateValue(node.state, state, node.label), questions: set.questions }, (answers) => {
2076
+ const value = set.decode(answers);
2077
+ return { rule: { kind: "judge" }, action: value, value };
2078
+ });
2079
+ const value = decided.value;
2080
+ const sidecar = answersSidecar(decided.answers);
2081
+ deps.onEvent?.({ type: "judge.answered", label: node.label, detail: { kind: "judge", as: node.as, value, sidecar, ...meteringOf(decided), decision_id: decided.id } });
1618
2082
  return { ...state, [node.as]: value, [`${node.as}$answers`]: sidecar };
1619
2083
  }
1620
2084
  async function runPickNode(node, state, deps) {
@@ -1637,16 +2101,20 @@ async function runPickNode(node, state, deps) {
1637
2101
  const options = Object.fromEntries(items.map((item, i) => [`item_${i}`, describeItem(node.describe, state, item, i) || `item ${i}`]));
1638
2102
  const criteria = node.allowNone ? { ...options, [NONE]: "none of the items fits" } : options;
1639
2103
  const asked = { ...(node.state ? interpolateValue(node.state, state, node.label) : { context: promptStateOf(state) }), candidates: options };
1640
- const { answers, sidecar, model, cost_usd } = await askQuestions(deps, node, asked, { pick: { type: "choice", instructions: node.instructions, criteria } });
1641
- const a = answers.pick;
1642
- if (!a || a.type !== "choice")
1643
- throw new Error(`pick node "${node.label}": no choice came back`);
1644
- const none = a.choice === NONE;
1645
- const index = none ? null : Object.keys(options).indexOf(a.choice);
1646
- if (index !== null && index < 0)
1647
- throw new Error(`pick node "${node.label}": the choice "${a.choice}" names no item`);
1648
- const value = { index, item: index === null ? null : items[index], none, option: none ? null : options[a.choice] };
1649
- deps.onEvent?.({ type: "judge.answered", label: node.label, detail: { kind: "pick", as: node.as, value, sidecar, model, cost_usd } });
2104
+ const decided = await decide(deps, { nodeKind: "pick", kind: "pick", judgeKind: "pick", label: node.label, state: asked, questions: { pick: { type: "choice", instructions: node.instructions, criteria } } }, (answers) => {
2105
+ const a = answers.pick;
2106
+ if (!a || a.type !== "choice")
2107
+ throw new Error(`pick node "${node.label}": no choice came back`);
2108
+ const none = a.choice === NONE;
2109
+ const index = none ? null : Object.keys(options).indexOf(a.choice);
2110
+ if (index !== null && index < 0)
2111
+ throw new Error(`pick node "${node.label}": the choice "${a.choice}" names no item`);
2112
+ const value = { index, item: index === null ? null : items[index], none, option: none ? null : options[a.choice] };
2113
+ return { rule: { kind: "pick", options: Object.keys(options), none: node.allowNone ? NONE : null }, action: { index, none }, value };
2114
+ });
2115
+ const value = decided.value;
2116
+ const sidecar = answersSidecar(decided.answers);
2117
+ deps.onEvent?.({ type: "judge.answered", label: node.label, detail: { kind: "pick", as: node.as, value, sidecar, ...meteringOf(decided), decision_id: decided.id } });
1650
2118
  return { ...state, [node.as]: value, [`${node.as}$answers`]: sidecar };
1651
2119
  }
1652
2120
  async function runSiftNode(node, state, workflow, deps) {
@@ -1656,58 +2124,133 @@ async function runSiftNode(node, state, workflow, deps) {
1656
2124
  throw new WorkflowStateError(`sift node "${node.label}": ${node.itemsPath} is not a list`, node.label, node.itemsPath, "expected_list");
1657
2125
  const set = questionSetOf(workflow, node);
1658
2126
  const ids = Object.keys(set.questions);
1659
- assertQuestionCount(deps, items.length * ids.length, node.label);
1660
2127
  const [keepId, keepTail] = node.keep ? node.keep.path.split(".") : [];
1661
2128
  const values = [];
1662
2129
  const sidecars = [];
1663
2130
  const kept = [];
1664
2131
  let metering = null;
2132
+ const decisionIds = [];
1665
2133
  if (items.length) {
1666
2134
  const base = node.state ? interpolateValue(node.state, state, node.label) : {};
1667
2135
  const named = items.map((item, i) => ({ id: `item_${i}`, ...(node.describe ? { summary: describeItem(node.describe, state, item, i) } : {}), item }));
1668
- const questions = {};
1669
- for (let i = 0; i < items.length; i += 1)
1670
- for (const id of ids)
1671
- questions[`${i}.${id}`] = { ...set.questions[id], instructions: `For \`items[${i}]\` (id item_${i}): ${set.questions[id].instructions}` };
1672
- const { answers, model, cost_usd } = await askQuestions(deps, node, { ...base, items: named }, questions);
1673
- metering = { model, cost_usd };
1674
- for (let i = 0; i < items.length; i += 1) {
1675
- const mine = Object.create(null);
1676
- for (const id of ids) {
1677
- const a = answers[`${i}.${id}`];
1678
- if (!a)
1679
- throw new Error(`sift node "${node.label}": no answer for item ${i} question "${id}"`);
1680
- mine[id] = a;
1681
- }
1682
- values.push(set.decode(mine, ` answers for item ${i}`));
1683
- sidecars.push(answersSidecar(mine));
1684
- if (!node.keep) {
1685
- kept.push(i);
1686
- continue;
1687
- }
1688
- const a = mine[keepId];
1689
- const measure = keepTail === "confidence" ? answerConfidence(a) : a.type === "noul" ? a.noul : a.type === "score" ? a.score : NaN;
1690
- const threshold = node.keep.gte ?? (a.type === "noul" && keepTail !== "confidence" ? 0.5 : 0);
1691
- if (Number.isFinite(measure) && measure >= threshold)
1692
- kept.push(i);
2136
+ const chunks = siftChunks(deps, node.label, ids.length, base, named);
2137
+ const measure = keepTail === "confidence" ? "confidence" : "value";
2138
+ // The keep rule, as applied and as a receipt states it: the author's threshold, else 0.5 for a yes/no
2139
+ // value and 0 otherwise (an answer has its question's type).
2140
+ const keep = node.keep ? { id: keepId, measure, gte: node.keep.gte ?? (set.questions[keepId]?.type === "noul" && measure === "value" ? 0.5 : 0) } : null;
2141
+ // Each chunk is its own request and its own decision: item ids stay global (item_<i>), `items[j]`
2142
+ // indexes the chunk, and the chunk's receipt names its kept items by that position. A sift that fits
2143
+ // in one request sends exactly the request it always did. Several requests run at most
2144
+ // SIFT_REQUESTS_IN_FLIGHT at a time; the first failure stops dispatch and cancels the requests in
2145
+ // flight, each of which is recorded as cancelled, and is thrown once they settle. A request that had
2146
+ // already answered keeps its receipt; no event names it, since the sift decided nothing.
2147
+ const ask = (chunk, c, signal, onFailure) => {
2148
+ const questions = {};
2149
+ chunk.forEach((i, j) => { for (const id of ids)
2150
+ questions[`${j}.${id}`] = { ...set.questions[id], instructions: `For \`items[${j}]\` (id item_${i}): ${set.questions[id].instructions}` }; });
2151
+ return decide(deps, { nodeKind: "sift", kind: "sift", judgeKind: "sift", label: node.label, state: { ...base, items: chunk.map((i) => named[i]) }, questions, signal, request: { index: c, count: chunks.length, items: chunk }, ...(onFailure ? { onFailure } : {}) }, (answers) => {
2152
+ const decoded = [];
2153
+ const sides = [];
2154
+ const keptHere = [];
2155
+ chunk.forEach((i, j) => {
2156
+ const mine = Object.create(null);
2157
+ for (const id of ids) {
2158
+ const a = answers[`${j}.${id}`];
2159
+ if (!a)
2160
+ throw new Error(`sift node "${node.label}": no answer for item ${i} question "${id}"`);
2161
+ mine[id] = a;
2162
+ }
2163
+ decoded.push(set.decode(mine, ` answers for item ${i}`));
2164
+ sides.push(answersSidecar(mine));
2165
+ if (!keep) {
2166
+ keptHere.push(j);
2167
+ return;
2168
+ }
2169
+ const a = mine[keepId];
2170
+ const measured = keepTail === "confidence" ? answerConfidence(a) : a.type === "noul" ? a.noul : a.type === "score" ? a.score : NaN;
2171
+ if (Number.isFinite(measured) && measured >= keep.gte)
2172
+ keptHere.push(j);
2173
+ });
2174
+ return { rule: { kind: "sift", items: chunk.length, ids, keep }, action: { kept: keptHere }, value: { values: decoded, sidecars: sides, kept: keptHere.map((j) => chunk[j]) } };
2175
+ });
2176
+ };
2177
+ let results;
2178
+ if (chunks.length === 1)
2179
+ results = [await ask(chunks[0], 0, deps.signal)];
2180
+ else {
2181
+ const stop = new AbortController();
2182
+ const signal = deps.signal ? AbortSignal.any([deps.signal, stop.signal]) : stop.signal;
2183
+ results = new Array(chunks.length);
2184
+ let next = 0, failure;
2185
+ // The first request to fail is the sift's failure, from the moment it fails: dispatch stops and the
2186
+ // requests in flight are cancelled then, not when its receipt has been written. What it finally
2187
+ // throws (its own error, or that and a receipt that could not be recorded) replaces what it flagged.
2188
+ const fail = (request, error) => { if (!failure || failure.request === request)
2189
+ failure = { request, error }; stop.abort(); };
2190
+ await Promise.all(Array.from({ length: Math.min(SIFT_REQUESTS_IN_FLIGHT, chunks.length) }, async () => {
2191
+ while (!failure && next < chunks.length) {
2192
+ const c = next++;
2193
+ try {
2194
+ results[c] = await ask(chunks[c], c, signal, (error) => fail(c, error));
2195
+ }
2196
+ catch (error) {
2197
+ fail(c, error);
2198
+ }
2199
+ }
2200
+ }));
2201
+ if (failure)
2202
+ throw failure.error;
2203
+ }
2204
+ const models = new Set(results.map((r) => r.model));
2205
+ metering = {
2206
+ model: models.size === 1 ? results[0].model : null,
2207
+ cost_usd: results.every((r) => r.cost_usd !== null) ? results.reduce((sum, r) => sum + r.cost_usd, 0) : null,
2208
+ ...(chunks.length > 1 ? { requests: chunks.length } : {}),
2209
+ ...(results.every((r) => r.replayed) ? { replayed: true } : {}),
2210
+ };
2211
+ // Chunks cover the list in order, so their results concatenate into list order.
2212
+ for (const r of results) {
2213
+ values.push(...r.value.values);
2214
+ sidecars.push(...r.value.sidecars);
2215
+ kept.push(...r.value.kept);
2216
+ decisionIds.push(r.id);
1693
2217
  }
1694
2218
  }
1695
2219
  const value = { items: kept.map((i) => items[i]), values, answers: sidecars, kept };
1696
- deps.onEvent?.({ type: "judge.answered", label: node.label, detail: { kind: "sift", as: node.as, value, count: items.length, kept: kept.length, ...(metering ?? {}) } });
2220
+ deps.onEvent?.({ type: "judge.answered", label: node.label, detail: { kind: "sift", as: node.as, value, count: items.length, kept: kept.length, ...(metering ?? {}), decision_ids: decisionIds } });
1697
2221
  return { ...state, [node.as]: value };
1698
2222
  }
1699
2223
  async function runRouteNode(node, state, workflow, deps) {
1700
2224
  assertNodeInputs(node, state);
2225
+ if (routesByValue(node)) {
2226
+ // The choice is already in state: no model is asked, and nothing is coerced into a branch name.
2227
+ const value = getPath(state, node.valuePath);
2228
+ if (value !== undefined && typeof value !== "string")
2229
+ throw new WorkflowStateError(`route node "${node.label}": ${node.valuePath} is not a string; a route by value reads a branch name`, node.label, node.valuePath, "route_type");
2230
+ const matched = typeof value === "string" && Object.hasOwn(node.branches, value);
2231
+ const taken = matched ? value : node.otherwise;
2232
+ if (taken === undefined)
2233
+ throw new WorkflowStateError(`route node "${node.label}": ${node.valuePath} ${value === undefined ? "is missing" : "names no branch"} and the route declares no otherwise`, node.label, node.valuePath, value === undefined ? "route_missing" : "route_unknown");
2234
+ const selection = { value: value ?? null, taken, fallback: !matched };
2235
+ // The event names only a declared branch, never an unexpected source string.
2236
+ deps.onEvent?.({ type: "route.chosen", label: node.label, detail: { kind: "route", by: "value", as: node.as ?? null, value: { taken, fallback: !matched } } });
2237
+ const routed = node.as ? { ...state, [node.as]: selection } : state;
2238
+ return runNodeOnState(node.branches[taken].body, routed, workflow, scopeExecution(deps, "branches", taken, "body"));
2239
+ }
1701
2240
  const names = Object.keys(node.branches);
1702
2241
  const criteria = Object.fromEntries(names.map((n) => [n, node.branches[n]?.criteria?.trim() || null]));
1703
- const { answers, sidecar, model, cost_usd } = await askQuestions(deps, node, interpolateValue(node.state, state, node.label), { branch: { type: "choice", instructions: node.instructions, criteria } });
1704
- const a = answers.branch;
1705
- if (!a || a.type !== "choice" || !names.includes(a.choice))
1706
- throw new Error(`route node "${node.label}": the choice "${String(a?.choice)}" names no branch`);
1707
- const unsure = Boolean(node.unsure && a.confidence < node.unsure.gte);
1708
- const taken = unsure ? node.unsure.branch : a.choice;
1709
- const value = { branch: a.choice, taken, unsure };
1710
- deps.onEvent?.({ type: "route.chosen", label: node.label, detail: { kind: "route", as: node.as ?? null, value, sidecar, model, cost_usd } });
2242
+ const decided = await decide(deps, { nodeKind: "route", kind: "route", judgeKind: "route", label: node.label, state: interpolateValue(node.state, state, node.label), questions: { branch: { type: "choice", instructions: node.instructions, criteria } } }, (answers) => {
2243
+ const a = answers.branch;
2244
+ if (!a || a.type !== "choice" || !names.includes(a.choice))
2245
+ throw new Error(`route node "${node.label}": the choice "${String(a?.choice)}" names no branch`);
2246
+ const unsure = Boolean(node.unsure && a.confidence < node.unsure.gte);
2247
+ const value = { branch: a.choice, taken: unsure ? node.unsure.branch : a.choice, unsure };
2248
+ return { rule: { kind: "route", unsure: node.unsure ? { gte: node.unsure.gte, branch: node.unsure.branch } : null }, action: value, value };
2249
+ });
2250
+ const value = decided.value;
2251
+ const taken = value.taken;
2252
+ const sidecar = answersSidecar(decided.answers);
2253
+ deps.onEvent?.({ type: "route.chosen", label: node.label, detail: { kind: "route", as: node.as ?? null, value, sidecar, ...meteringOf(decided), decision_id: decided.id } });
1711
2254
  const routed = node.as ? { ...state, [node.as]: value, [`${node.as}$answers`]: sidecar } : state;
1712
2255
  return runNodeOnState(node.branches[taken].body, routed, workflow, scopeExecution(deps, "branches", taken, "body"));
1713
2256
  }
@@ -1744,7 +2287,7 @@ function withExecutionLocation(deps) {
1744
2287
  ...(deps.runNode ? { runNode: params => deps.runNode({ ...params, executionPath: params.executionPath ?? path }) } : {}),
1745
2288
  ...(deps.runEffect ? { runEffect: params => deps.runEffect({ ...params, executionPath: params.executionPath ?? path }) } : {}),
1746
2289
  ...(deps.runJudge ? { runJudge: params => deps.runJudge({ ...params, executionPath: params.executionPath ?? path }) } : {}),
1747
- ...(deps.onEvent ? { onEvent: event => deps.onEvent({ ...event, executionPath: event.executionPath ?? path }) } : {}),
2290
+ ...(deps.onEvent ? { onEvent: forwardObserver(deps.onEvent, event => ({ ...event, executionPath: event.executionPath ?? path })) } : {}),
1748
2291
  };
1749
2292
  }
1750
2293
  /** Older hosts only support flat child chains outside repeated/branching structure. They must
@@ -1781,6 +2324,9 @@ function scopeDepsToItem(deps, item, signal) {
1781
2324
  pollStartedAt: (node, nestedItem, path) => recovery.pollStartedAt(node, nestedItem ?? item, path),
1782
2325
  wait: (node, ms, nestedItem, path) => recovery.wait(node, ms, nestedItem ?? item, path),
1783
2326
  ...(recovery.fail ? { fail: (node, results, error, path) => recovery.fail(node, results, error, path) } : {}),
2327
+ ...(recovery.failItem ? { failItem: (node, failure, path) => recovery.failItem(node, failure, path) } : {}),
2328
+ ...(recovery.itemFailure ? { itemFailure: (node, path) => recovery.itemFailure(node, path) } : {}),
2329
+ ...(recovery.decision ? { decision: id => recovery.decision(id) } : {}),
1784
2330
  } } : {}),
1785
2331
  };
1786
2332
  }
@@ -1795,6 +2341,8 @@ function scopeDepsToChild(deps, invocation) {
1795
2341
  ...(deps.runNode ? { runNode: params => deps.runNode({ ...params, label: `${prefix}/${params.label}` }) } : {}),
1796
2342
  ...(deps.runEffect ? { runEffect: params => deps.runEffect({ ...params, node: relabel(params.node) }) } : {}),
1797
2343
  ...(deps.runJudge ? { runJudge: params => deps.runJudge({ ...params, label: `${prefix}/${params.label}` }) } : {}),
2344
+ ...(deps.recordDecision ? { recordDecision: (receipt, exchange) => deps.recordDecision({ ...receipt, node: `${prefix}/${receipt.node}` }, { ...exchange, request: { ...exchange.request, label: `${prefix}/${exchange.request.label}` } }) } : {}),
2345
+ ...(deps.runCode ? { runCode: (node, state, ctx) => deps.runCode(relabel(node), state, { ...ctx, label: `${prefix}/${ctx.label}` }) } : {}),
1798
2346
  ...(recovery ? { recovery: {
1799
2347
  supportsExecutionPaths: recovery.supportsExecutionPaths,
1800
2348
  resume: (node, state, item, path) => recovery.resume(relabel(node), state, item, path),
@@ -1802,22 +2350,41 @@ function scopeDepsToChild(deps, invocation) {
1802
2350
  pollStartedAt: (node, item, path) => recovery.pollStartedAt(relabel(node), item, path),
1803
2351
  wait: (node, ms, item, path) => recovery.wait(relabel(node), ms, item, path),
1804
2352
  ...(recovery.fail ? { fail: (node, results, error, path) => recovery.fail(relabel(node), results, error, path) } : {}),
2353
+ ...(recovery.failItem ? { failItem: (node, failure, path) => recovery.failItem(relabel(node), failure, path) } : {}),
2354
+ ...(recovery.itemFailure ? { itemFailure: (node, path) => recovery.itemFailure(relabel(node), path) } : {}),
2355
+ ...(recovery.decision ? { decision: id => recovery.decision(id) } : {}),
1805
2356
  } } : {}),
1806
- ...(deps.onEvent ? { onEvent: event => deps.onEvent({ ...event, label: `${prefix}/${event.label}` }) } : {}),
2357
+ ...(deps.onEvent ? { onEvent: forwardObserver(deps.onEvent, event => ({ ...event, label: `${prefix}/${event.label}` })) } : {}),
1807
2358
  };
1808
2359
  }
1809
2360
  const STEP_KINDS = new Set(["agent", "decide", "extract", "report", "code", "call", "artifact", "workflow", "judge", "pick", "sift"]);
1810
2361
  const CHECKPOINTED_STRUCTURE_KINDS = new Set(["map", "parallel", "loop", "route"]);
1811
2362
  const guardedObservers = new WeakSet();
2363
+ function forwardObserver(observer, transform) {
2364
+ const forwarded = (event) => observer(transform(event));
2365
+ if (guardedObservers.has(observer))
2366
+ guardedObservers.add(forwarded);
2367
+ return forwarded;
2368
+ }
1812
2369
  async function runNodeOnState(node, state, workflow, deps) {
1813
2370
  deps = withExecutionLocation(deps);
1814
2371
  const observer = deps.onEvent;
1815
2372
  if (observer && !guardedObservers.has(observer)) {
1816
2373
  const guarded = event => {
2374
+ let detached;
2375
+ try {
2376
+ detached = deps.prepareEvent ? deps.prepareEvent(event) : observerSnapshot(event);
2377
+ }
2378
+ catch {
2379
+ return;
2380
+ }
2381
+ if (detached === undefined)
2382
+ return;
1817
2383
  try {
1818
2384
  // TypeScript void callbacks can still return promises. Consume rejection without
1819
2385
  // awaiting telemetry or allowing it to replace an execution or recovery outcome.
1820
- const returned = observer(event);
2386
+ // Observers receive snapshots, never objects shared with execution state.
2387
+ const returned = observer(detached);
1821
2388
  if (returned && typeof returned.then === "function") {
1822
2389
  void Promise.resolve(returned).catch(() => { });
1823
2390
  }
@@ -1881,6 +2448,14 @@ async function runNodeOnState(node, state, workflow, deps) {
1881
2448
  catch (error) {
1882
2449
  if (isStep)
1883
2450
  deps.onEvent?.({ type: "node.end", label, detail: { kind: node.node, status: error instanceof EscalationSignal ? "escalated" : "failed", duration_ms: Date.now() - startedAt, error: String(error?.message || error).slice(0, 300) } });
2451
+ if (error !== null && typeof error === "object") {
2452
+ const inner = failedSteps.get(error);
2453
+ // A step names itself; so does a structural node whose own failure this is (its stage is its label).
2454
+ if (inner === undefined && (isStep || error.stage === label))
2455
+ failedSteps.set(error, label);
2456
+ else if (inner !== undefined && node.node === "workflow")
2457
+ failedSteps.set(error, `${label}/${inner}`);
2458
+ }
1884
2459
  throw error;
1885
2460
  }
1886
2461
  }
@@ -1912,12 +2487,18 @@ async function runNodeBody(node, state, workflow, deps) {
1912
2487
  }
1913
2488
  case "code": {
1914
2489
  let out;
1915
- try {
1916
- const fn = compileTransform(node.code);
1917
- out = fn(state, { sop: deps.sop || "" });
2490
+ if (deps.runCode) {
2491
+ const item = deps[MAP_ITEM];
2492
+ out = await deps.runCode(node, state, { sop: deps.sop || "", label: node.label, executionPath: executionPath(deps), ...(item ? { item } : {}), ...(deps.signal ? { signal: deps.signal } : {}) });
1918
2493
  }
1919
- catch (cause) {
1920
- throw new WorkflowCodeError(node.label, cause);
2494
+ else {
2495
+ try {
2496
+ const fn = compileTransform(node.code);
2497
+ out = fn(state, { sop: deps.sop || "" });
2498
+ }
2499
+ catch (cause) {
2500
+ throw new WorkflowCodeError(node.label, cause);
2501
+ }
1921
2502
  }
1922
2503
  const patch = node.as ? { [node.as]: out } : (out && typeof out === "object" && !Array.isArray(out) ? out : { [node.label]: out });
1923
2504
  if (Object.prototype.hasOwnProperty.call(patch, HOST_STATE_KEY))
@@ -1981,6 +2562,8 @@ async function runNodeBody(node, state, workflow, deps) {
1981
2562
  kind: node.node, label: node.label,
1982
2563
  ...(review ? { review } : {}),
1983
2564
  ...(node.tier ? { tier: node.tier } : {}),
2565
+ ...(node.node === "agent" && node.budget_usd !== undefined ? { budgetUsd: node.budget_usd } : {}),
2566
+ ...(node.node === "agent" && node.context !== undefined ? { context: node.context } : {}),
1984
2567
  system: [sopSlice, deps.skill, node.instructions, ...(policy?.systemBlocks && context ? policy.systemBlocks(context) : [])].filter(Boolean),
1985
2568
  user: JSON.stringify(promptState),
1986
2569
  schema: transportSchema,
@@ -2006,6 +2589,10 @@ async function runNodeBody(node, state, workflow, deps) {
2006
2589
  if (!Array.isArray(items))
2007
2590
  throw new WorkflowStateError(`map node "${node.label}": ${node.itemsPath} is not a list`, node.label, node.itemsPath, "expected_list");
2008
2591
  const results = new Array(items.length);
2592
+ // With `collect`, an item that ends on an item failure is a row here and `null` in its slot of `as`: the slots stay
2593
+ // aligned with the items, so a later node reads item i's result at i.
2594
+ const collect = node.onItemFailure === "collect";
2595
+ const rows = new Array(items.length);
2009
2596
  let cursor = 0;
2010
2597
  const width = Math.min(node.maxConcurrency ?? 4, Math.max(items.length, 1));
2011
2598
  const siblings = new AbortController();
@@ -2013,6 +2600,18 @@ async function runNodeBody(node, state, workflow, deps) {
2013
2600
  let failure;
2014
2601
  let failed = false;
2015
2602
  const uncertainties = new Set();
2603
+ /** Failures after the first: one the map must stop on is reported over an item failure (`reportedFailure`). */
2604
+ const later = [];
2605
+ const stop = (error) => {
2606
+ uncertainEffects(error, uncertainties);
2607
+ if (!failed) {
2608
+ failed = true;
2609
+ failure = error;
2610
+ siblings.abort(error);
2611
+ }
2612
+ else
2613
+ later.push(error);
2614
+ };
2016
2615
  await Promise.all(Array.from({ length: width }, async () => {
2017
2616
  while (!signal.aborted) {
2018
2617
  const i = cursor++;
@@ -2023,9 +2622,17 @@ async function runNodeBody(node, state, workflow, deps) {
2023
2622
  // Under recovery each item is its own child: the body's session, effects and commit
2024
2623
  // carry the item, so a resumed map answers finished items from their rows and
2025
2624
  // continues the ones that were running.
2625
+ const itemDeps = scopeDepsToItem(scopeExecution(deps, "items", i, "body"), { label: node.label, index: i }, signal);
2026
2626
  try {
2627
+ // A failure an earlier process committed ends the item again: its body never runs twice.
2628
+ const committed = collect ? await itemDeps.recovery?.itemFailure?.(node, executionPath(itemDeps)) : undefined;
2629
+ if (committed) {
2630
+ rows[i] = committed;
2631
+ results[i] = null;
2632
+ continue;
2633
+ }
2027
2634
  const itemState = snapshotState({ ...state, item: items[i], item_index: i });
2028
- const out = await runNodeOnState(node.body, itemState, workflow, scopeDepsToItem(scopeExecution(deps, "items", i, "body"), { label: node.label, index: i }, signal));
2635
+ const out = await runNodeOnState(node.body, itemState, workflow, itemDeps);
2029
2636
  if (node.resultPath !== undefined) {
2030
2637
  const selected = node.resultPath.split(".").reduce((value, key) => value == null ? undefined : value[key], out);
2031
2638
  if (selected === undefined)
@@ -2036,20 +2643,30 @@ async function runNodeBody(node, state, workflow, deps) {
2036
2643
  results[i] = node.body.as ? out[node.body.as] : out;
2037
2644
  }
2038
2645
  catch (error) {
2039
- uncertainEffects(error, uncertainties);
2040
- if (!failed) {
2041
- failed = true;
2042
- failure = error;
2043
- siblings.abort(error);
2646
+ // An item failure ends its item; the map's stop and every other failure stop the map.
2647
+ if (!collect || signal.aborted || !isItemFailure(error)) {
2648
+ stop(error);
2649
+ return;
2044
2650
  }
2045
- return;
2651
+ const row = itemFailureRow(i, error, node.label);
2652
+ try {
2653
+ await itemDeps.recovery?.failItem?.(node, row, executionPath(itemDeps));
2654
+ }
2655
+ catch (persistenceError) {
2656
+ stop(persistenceError);
2657
+ return;
2658
+ }
2659
+ rows[i] = row;
2660
+ results[i] = null;
2661
+ deps.onEvent?.({ type: "map.item_failed", label: node.label, detail: { item_index: i, label: row.label, code: row.code } });
2046
2662
  }
2047
2663
  }
2048
2664
  }));
2049
2665
  if (failed) {
2050
- failure = withSiblingUncertainty(failure, uncertainties);
2666
+ failure = withSiblingUncertainty(reportedFailure(failure, later), uncertainties);
2051
2667
  const escalated = failure instanceof EscalationSignal;
2052
- deps.onEvent?.({ type: escalated ? "map.escalated" : "map.failed", label: node.label, detail: { completed: results.reduce((n, r) => n + (r === undefined ? 0 : 1), 0), of: items.length, message: String(failure?.message || failure).slice(0, 300) } });
2668
+ const collected = rows.filter(Boolean).length;
2669
+ deps.onEvent?.({ type: escalated ? "map.escalated" : "map.failed", label: node.label, detail: { completed: results.reduce((n, r) => n + (r === undefined ? 0 : 1), 0) - collected, of: items.length, ...(collect ? { collected } : {}), message: String(failure?.message || failure).slice(0, 300) } });
2053
2670
  if (!escalated && deps.recovery?.fail) {
2054
2671
  try {
2055
2672
  await deps.recovery.fail(node, results, failure, executionPath(deps));
@@ -2060,7 +2677,7 @@ async function runNodeBody(node, state, workflow, deps) {
2060
2677
  }
2061
2678
  throw failure;
2062
2679
  }
2063
- return { ...state, [node.as]: results };
2680
+ return { ...state, [node.as]: results, ...(collect ? { [node.failedAs]: rows.filter(Boolean) } : {}) };
2064
2681
  }
2065
2682
  case "parallel": {
2066
2683
  // Every branch starts from the same state and runs at once; what comes back is each branch's
@@ -2073,6 +2690,7 @@ async function runNodeBody(node, state, workflow, deps) {
2073
2690
  let failure;
2074
2691
  let failed = false;
2075
2692
  const uncertainties = new Set();
2693
+ const later = [];
2076
2694
  const outs = await Promise.all((node.branches || []).map(async (branch, i) => {
2077
2695
  try {
2078
2696
  return await runNodeOnState(branch, inputs[i], workflow, scopeExecution({ ...deps, signal, checkpoint: undefined }, "branches", i));
@@ -2084,11 +2702,13 @@ async function runNodeBody(node, state, workflow, deps) {
2084
2702
  failure = error;
2085
2703
  siblings.abort(error);
2086
2704
  }
2705
+ else
2706
+ later.push(error);
2087
2707
  return inputs[i];
2088
2708
  }
2089
2709
  }));
2090
2710
  if (failed)
2091
- throw withSiblingUncertainty(failure, uncertainties);
2711
+ throw withSiblingUncertainty(reportedFailure(failure, later), uncertainties);
2092
2712
  const merged = { ...state };
2093
2713
  const writer = new Map();
2094
2714
  // Host state is engine-owned and merges by delta: every branch started from the same `$host`, so an
@@ -2108,15 +2728,21 @@ async function runNodeBody(node, state, workflow, deps) {
2108
2728
  if (hostWriter.has(key) && isDeepStrictEqual(mergedHost[key], value))
2109
2729
  continue;
2110
2730
  const base = baseHost[key];
2731
+ const prior = hostWriter.get(key);
2732
+ const conflict = () => new WorkflowStateError(`parallel node "${node.label}": branches ${prior} and ${i} both wrote host state ${HOST_STATE_KEY}.${key} to different values`, node.label, `${HOST_STATE_KEY}.${key}`, "parallel_write_conflict");
2733
+ // An append is an array that extends the base array (or a new array on a key with no base).
2734
+ // Appends from several branches join in branch order. An append meets a prior non-append
2735
+ // write of the same key as a conflict, whichever branch came first: no shape wins silently.
2111
2736
  if (Array.isArray(value) && (base === undefined || Array.isArray(base)) && (!Array.isArray(base) || (value.length >= base.length && base.every((entry, n) => isDeepStrictEqual(entry, value[n]))))) {
2737
+ if (prior !== undefined && !Array.isArray(mergedHost[key]))
2738
+ throw conflict();
2112
2739
  const appended = value.slice(Array.isArray(base) ? base.length : 0);
2113
2740
  mergedHost[key] = [...(Array.isArray(mergedHost[key]) ? mergedHost[key] : []), ...appended];
2114
2741
  hostWriter.set(key, i);
2115
2742
  continue;
2116
2743
  }
2117
- const prior = hostWriter.get(key);
2118
2744
  if (prior !== undefined && !isDeepStrictEqual(mergedHost[key], value))
2119
- throw new WorkflowStateError(`parallel node "${node.label}": branches ${prior} and ${i} both wrote host state ${HOST_STATE_KEY}.${key} to different values`, node.label, `${HOST_STATE_KEY}.${key}`, "parallel_write_conflict");
2745
+ throw conflict();
2120
2746
  hostWriter.set(key, i);
2121
2747
  mergedHost[key] = value;
2122
2748
  }
@@ -2235,7 +2861,8 @@ function compileVerifier(workflow, node, state, deps) {
2235
2861
  const schema = workflow.schemas[clause.out].properties ?? {};
2236
2862
  const maxDrives = clause.maxDrives ?? 2;
2237
2863
  const floor = clause.override?.below ?? 0.3;
2238
- const runJudge = requireJudge(deps, "judge", `${node.label} (verify)`);
2864
+ // A runner with no judge refuses the node here, before its generative call.
2865
+ requireJudge(deps, "judge", `${node.label} (verify)`);
2239
2866
  const drives = [];
2240
2867
  let reviewedCandidate;
2241
2868
  let last = null;
@@ -2250,29 +2877,36 @@ function compileVerifier(workflow, node, state, deps) {
2250
2877
  if (outSchema)
2251
2878
  normalizeStringNullsForSchema(sub, outSchema);
2252
2879
  const asked = interpolateValue({ ...(clause.state ?? {}), submission: "{submission}" }, { ...state, submission: sub, ...(node.as ? { [node.as]: sub } : {}) }, node.label);
2253
- const result = await runJudge({ label: `${node.label} (verify)`, kind: "judge", state: asked, questions, signal: deps.signal });
2254
- validateAnswers(questions, result.answers);
2255
- const answers = result.answers;
2256
- const doubted = [];
2257
- const unmet = [];
2258
- for (const [id, q] of Object.entries(questions)) {
2259
- if (q.type !== "noul")
2260
- continue;
2261
- const p = pYes(answers[id]);
2262
- if (Object.prototype.hasOwnProperty.call(sub, id)) {
2263
- if (filled(sub[id]) && p < floor)
2264
- doubted.push(id);
2265
- }
2266
- else if (p < 0.5)
2267
- unmet.push(id);
2268
- }
2269
2880
  const drive = drives.length + 1;
2270
- const accepted = doubted.length === 0 && unmet.length === 0;
2881
+ const decided = await decide(deps, { nodeKind: "judge", kind: "verify", judgeKind: "judge", label: `${node.label} (verify)`, state: asked, questions, request: { index: drive - 1, count: maxDrives } }, (answers) => {
2882
+ const doubted = [];
2883
+ const unmet = [];
2884
+ const present = Object.keys(questions).filter((id) => Object.prototype.hasOwnProperty.call(sub, id));
2885
+ const thresholds = {};
2886
+ for (const [id, q] of Object.entries(questions)) {
2887
+ if (q.type !== "noul")
2888
+ continue;
2889
+ const p = pYes(answers[id]);
2890
+ if (Object.prototype.hasOwnProperty.call(sub, id)) {
2891
+ if (filled(sub[id]) && p < floor)
2892
+ doubted.push(id);
2893
+ }
2894
+ else if (p < 0.5)
2895
+ unmet.push(id);
2896
+ // A field the submission holds is judged at the floor, one it holds empty is not judged, and a
2897
+ // requirement that is not a field is judged at 0.5.
2898
+ thresholds[id] = !present.includes(id) ? 0.5 : filled(sub[id]) ? floor : null;
2899
+ }
2900
+ const accepted = doubted.length === 0 && unmet.length === 0;
2901
+ return { rule: { kind: "verify", thresholds, present }, action: { accepted, doubted, unmet }, value: { doubted, unmet, accepted } };
2902
+ });
2903
+ const answers = decided.answers;
2904
+ const { doubted, unmet, accepted } = decided.value;
2271
2905
  reviewedCandidate = JSON.stringify(sub);
2272
2906
  const sidecar = answersSidecar(answers);
2273
2907
  drives.push({ drive, doubted, unmet, accepted, sidecar });
2274
2908
  last = { answers, doubted, unmet };
2275
- deps.onEvent?.({ type: "verify.answered", label: node.label, detail: { drive, doubted, unmet, accepted, sidecar, model: result.model ?? null, cost_usd: result.cost_usd ?? null } });
2909
+ deps.onEvent?.({ type: "verify.answered", label: node.label, detail: { drive, doubted, unmet, accepted, sidecar, ...meteringOf(decided), decision_id: decided.id } });
2276
2910
  if (accepted)
2277
2911
  return { accepted: true };
2278
2912
  if (drive >= maxDrives)
@@ -2321,10 +2955,13 @@ export function assertWorkflowCapabilities(node, deps, workflow) {
2321
2955
  missing("runNode");
2322
2956
  if (node.node === "call" && !deps.runEffect)
2323
2957
  missing("runEffect");
2324
- if ((["judge", "pick", "sift", "route"].includes(node.node) || "verify" in node && node.verify ||
2958
+ if ((["judge", "pick", "sift"].includes(node.node) || node.node === "route" && !routesByValue(node) || "verify" in node && node.verify ||
2325
2959
  node.node === "loop" && node.until?.predicate === "ask" ||
2326
2960
  node.node === "escalate" && node.when?.predicate === "ask") && !deps.runJudge)
2327
2961
  missing("runJudge");
2962
+ // A store that cannot commit an item's failure would run the item again in the next process.
2963
+ if (node.node === "map" && node.onItemFailure === "collect" && deps.recovery && !(deps.recovery.failItem && deps.recovery.itemFailure))
2964
+ missing("recovery.failItem and recovery.itemFailure");
2328
2965
  if (node.node === "chain")
2329
2966
  node.steps.forEach(n => assertWorkflowCapabilities(n, deps, workflow));
2330
2967
  if (node.node === "parallel")
@@ -2339,18 +2976,20 @@ export function assertWorkflowCapabilities(node, deps, workflow) {
2339
2976
  export async function runWorkflow(workflow, input, deps) {
2340
2977
  if (!input || typeof input !== "object" || Array.isArray(input))
2341
2978
  throw new WorkflowInputInvalidError(String(workflow?.name), ["input must be a JSON object"]);
2342
- const valid = validateWorkflow(workflow);
2979
+ // A host that executes code nodes itself never has them executed here, not even as validation probes.
2980
+ const executeCode = deps.runCode ? false : undefined;
2981
+ const valid = validateWorkflow(workflow, { executeCode });
2343
2982
  if (!valid.ok)
2344
- throw new WorkflowInvalidError(String(workflow?.name), valid.errors);
2983
+ throw new WorkflowInvalidError(String(workflow?.name), valid.errors, valid.issues);
2345
2984
  workflow = desugarWorkflow(workflow);
2346
2985
  if (workflow.input) {
2347
2986
  const validator = Compile(resolveSchemaForWorkflow(workflow, workflow.schemas[workflow.input.schemaId]));
2348
2987
  if (!validator.Check(input))
2349
2988
  throw new WorkflowInputInvalidError(workflow.name, schemaProblems(validator, input));
2350
2989
  }
2351
- const reachable = validateWorkflow(workflow, { inputKeys: Object.keys(input) });
2990
+ const reachable = validateWorkflow(workflow, { executeCode, inputKeys: Object.keys(input) });
2352
2991
  if (!reachable.ok)
2353
- throw new WorkflowInvalidError(workflow.name, reachable.errors);
2992
+ throw new WorkflowInvalidError(workflow.name, reachable.errors, reachable.issues);
2354
2993
  assertWorkflowCapabilities(workflow.root, deps, workflow);
2355
2994
  if (needsComposedRecovery(workflow.root))
2356
2995
  deps = { ...deps, [SCOPED_EFFECTS]: true };
@@ -2360,6 +2999,8 @@ export async function runWorkflow(workflow, input, deps) {
2360
2999
  throw new WorkflowInputInvalidError(workflow.name, [`input must not contain the reserved "${HOST_STATE_KEY}" key`]);
2361
3000
  try {
2362
3001
  const state = await runNodeOnState(workflow.root, snapshotState(input), workflow, deps);
3002
+ if (deps.signal?.aborted)
3003
+ throw deps.signal.reason ?? new Error("workflow aborted");
2363
3004
  const host = hostStateOf(state);
2364
3005
  const output = workflow.output.path
2365
3006
  ? getPath(state, workflow.output.path)
@@ -2377,9 +3018,9 @@ export async function runWorkflow(workflow, input, deps) {
2377
3018
  }
2378
3019
  }
2379
3020
  export async function runWorkflowSlice(workflow, input, focus, deps) {
2380
- const valid = validateWorkflow(workflow);
3021
+ const valid = validateWorkflow(workflow, { executeCode: deps.runCode ? false : undefined });
2381
3022
  if (!valid.ok)
2382
- throw new WorkflowInvalidError(String(workflow?.name), valid.errors);
3023
+ throw new WorkflowInvalidError(String(workflow?.name), valid.errors, valid.issues);
2383
3024
  const desugared = desugarWorkflow(workflow);
2384
3025
  const root = desugared.root.node === "chain" ? desugared.root.steps : [desugared.root];
2385
3026
  const labels = root.map((n) => n.label ?? "");
@@ -2405,6 +3046,8 @@ export async function runWorkflowSlice(workflow, input, focus, deps) {
2405
3046
  let out = state;
2406
3047
  for (let i = a; i <= b; i++)
2407
3048
  out = await runNodeOnState(root[i], out, desugared, desugared.root.node === "chain" ? scopeExecution(deps, "steps", i) : deps);
3049
+ if (deps.signal?.aborted)
3050
+ throw deps.signal.reason ?? new Error("workflow aborted");
2408
3051
  return { status: "complete", state: out, focus: { from: labels[a], to: labels[b] } };
2409
3052
  }
2410
3053
  catch (error) {