@parcha/agentrun-dsl 0.1.0-beta.18 → 0.1.0-beta.19

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.
package/dist/workflow.js CHANGED
@@ -7,10 +7,11 @@ import { validateAnswers, answerConfidence, answersSidecar, answersToValue, comp
7
7
  import { DECISION_RECEIPT_VERSION } from "./decision-receipts.js";
8
8
  import { Compile } from "typebox/compile";
9
9
  import { compileTransform, compileTransformSyntax } from "./code-exec.js";
10
- import { workflowShapeErrors } from "./workflow-shape.js";
10
+ import { workflowShapeIssues } from "./workflow-shape.js";
11
11
  import { resolveSchemaForWorkflow } from "./schema-references.js";
12
12
  export { resolveSchemaForWorkflow } from "./schema-references.js";
13
13
  import { setLongTimeout } from "./long-timer.js";
14
+ import { isRecoveryError } from "./recovery/errors.js";
14
15
  export const routesByValue = (node) => typeof node.valuePath === "string";
15
16
  export function artifactNodeIsProse(node) {
16
17
  return PROSE_ARTIFACT_TYPES.includes(node.type);
@@ -66,8 +67,11 @@ export const declaredWrites = (node) => {
66
67
  out.add("report_markdown");
67
68
  else if (typeof n.as === "string" && n.as.trim())
68
69
  out.add(n.as);
69
- if (n.node === "map")
70
+ if (n.node === "map") {
71
+ if (typeof n.failedAs === "string" && n.failedAs.trim())
72
+ out.add(n.failedAs);
70
73
  return;
74
+ }
71
75
  if (Array.isArray(n.steps))
72
76
  n.steps.forEach(visit);
73
77
  if (Array.isArray(n.branches))
@@ -97,6 +101,8 @@ const loopBodyWrites = (body) => {
97
101
  out.add(n.as);
98
102
  else if (["agent", "decide", "extract"].includes(n.node) && typeof n.label === "string")
99
103
  out.add(n.label);
104
+ if (n.node === "map" && typeof n.failedAs === "string" && n.failedAs.trim())
105
+ out.add(n.failedAs);
100
106
  if (n.node === "map" || n.node === "workflow")
101
107
  return;
102
108
  if (Array.isArray(n.steps))
@@ -327,6 +333,7 @@ export function workflowDocumentError(value) {
327
333
  }
328
334
  return undefined;
329
335
  }
336
+ const pointerKey = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
330
337
  /** Set executeCode:false for untrusted author feedback: check syntax and mechanical contracts
331
338
  * without evaluating authored expressions or probing transforms. This is not execution admission;
332
339
  * trusted/default validation and runtime output checks remain authoritative. */
@@ -374,12 +381,18 @@ function workflowWarnings(workflow) {
374
381
  export function validateWorkflow(workflow, opts) {
375
382
  const bounded = workflowDocumentError(workflow);
376
383
  if (bounded)
377
- return { ok: false, errors: [bounded] };
378
- const shapeErrors = workflowShapeErrors(workflow);
379
- if (shapeErrors.length)
380
- 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 })) };
381
388
  workflow = desugarWorkflow(workflow);
382
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) ?? "";
383
396
  const declaredInput = workflow.input && Object.hasOwn(workflow.schemas, workflow.input.schemaId)
384
397
  ? resolveSchemaForWorkflow(workflow, workflow.schemas[workflow.input.schemaId]) : undefined;
385
398
  const inputKeys = opts?.input !== undefined ? Object.keys(opts.input ?? {}) : opts?.inputKeys;
@@ -395,7 +408,7 @@ export function validateWorkflow(workflow, opts) {
395
408
  };
396
409
  for (const [key, schema] of Object.entries((declaredInput?.properties ?? {})))
397
410
  rememberOutput(key, schema);
398
- const checkTypedPath = (dotted, at) => {
411
+ const checkTypedPath = (dotted, at, node) => {
399
412
  if (!reachability || reachability.unknowable)
400
413
  return;
401
414
  const [head, ...tail] = dotted.split(".");
@@ -414,7 +427,7 @@ export function validateWorkflow(workflow, opts) {
414
427
  schema = schema.properties[segment];
415
428
  else {
416
429
  if (schema.additionalProperties === false && !schema.patternProperties)
417
- 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`);
418
431
  return;
419
432
  }
420
433
  }
@@ -519,7 +532,7 @@ export function validateWorkflow(workflow, opts) {
519
532
  // own fail-closed guard (or a structural mismatch with the actual files) fired. Code that
520
533
  // also threw under the tolerant probe is state-dependent and stands down as before.
521
534
  if (!tolerantThrew)
522
- 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)}`);
523
536
  }
524
537
  }
525
538
  return patches;
@@ -603,7 +616,7 @@ export function validateWorkflow(workflow, opts) {
603
616
  if (!missing)
604
617
  return;
605
618
  }
606
- 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`);
607
620
  };
608
621
  // A mechanical predicate reads one state key; when no input key or earlier node writes it, the guard can never fire.
609
622
  const checkPredicateHead = (pred, label, path, field, produced) => {
@@ -616,9 +629,9 @@ export function validateWorkflow(workflow, opts) {
616
629
  return;
617
630
  const head = read.split(".")[0];
618
631
  if (!available.has(head))
619
- errors.push(`${path} (${label}): ${field} reads "${read}" but no input key or earlier node produces "${head}"; the guard can never fire`);
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`);
620
633
  else if (!produced)
621
- checkTypedPath(read, `${path} (${label}) ${field}`);
634
+ checkTypedPath(read, `${path} (${label}) ${field}`, ptrOf(path));
622
635
  };
623
636
  const checkInterpolations = (value, label, path) => {
624
637
  if (!reachability || reachability.unknowable || value === undefined)
@@ -630,16 +643,16 @@ export function validateWorkflow(workflow, opts) {
630
643
  continue;
631
644
  const head = (m[1].startsWith("state.") ? m[1].slice(6) : m[1]).split(".")[0];
632
645
  if (!reachability.available.has(head))
633
- 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}"`);
634
647
  else
635
- 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));
636
649
  }
637
650
  };
638
651
  const checkRequires = (node, path) => {
639
652
  if (node.requires === undefined)
640
653
  return;
641
654
  if (!Array.isArray(node.requires) || node.requires.some((p) => typeof p !== "string" || !p.trim())) {
642
- 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`);
643
656
  return;
644
657
  }
645
658
  if (!reachability || reachability.unknowable)
@@ -647,10 +660,10 @@ export function validateWorkflow(workflow, opts) {
647
660
  for (const required of node.requires) {
648
661
  const head = String(required).split(".")[0];
649
662
  if (!reachability.available.has(head)) {
650
- 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(", ")}`);
651
664
  }
652
665
  else
653
- checkTypedPath(required, `${path} (${node.label}) requires`);
666
+ checkTypedPath(required, `${path} (${node.label}) requires`, ptrOf(path));
654
667
  }
655
668
  };
656
669
  const checkItemsPath = (node, path) => {
@@ -658,23 +671,23 @@ export function validateWorkflow(workflow, opts) {
658
671
  return;
659
672
  const head = node.itemsPath.split(".")[0];
660
673
  if (!reachability.available.has(head))
661
- 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)`);
662
675
  else
663
- checkTypedPath(node.itemsPath, `${path} (${node.label}) itemsPath`);
676
+ checkTypedPath(node.itemsPath, `${path} (${node.label}) itemsPath`, ptrOf(path));
664
677
  };
665
678
  if (workflow?.v !== 2)
666
- errors.push("workflow.v must be 2");
679
+ fail("WORKFLOW_FIELD_INVALID", "", "workflow.v must be 2");
667
680
  if (!workflow?.name)
668
- errors.push("workflow.name is required");
681
+ fail("WORKFLOW_FIELD_INVALID", "", "workflow.name is required");
669
682
  if (!workflow?.schemas || typeof workflow.schemas !== "object")
670
- errors.push("workflow.schemas is required");
683
+ fail("WORKFLOW_FIELD_INVALID", "", "workflow.schemas is required");
671
684
  if (workflow?.input !== undefined && (!workflow.input || typeof workflow.input.schemaId !== "string" || !Object.hasOwn(workflow.schemas, workflow.input.schemaId)))
672
- errors.push("workflow.input.schemaId must name a schema");
685
+ fail("WORKFLOW_FIELD_INVALID", "", "workflow.input.schemaId must name a schema");
673
686
  if (!workflow?.output?.schemaId || !Object.hasOwn(workflow.schemas, workflow.output.schemaId))
674
- errors.push("workflow.output.schemaId must name a schema");
687
+ fail("WORKFLOW_FIELD_INVALID", "", "workflow.output.schemaId must name a schema");
675
688
  for (const [id, schema] of Object.entries(workflow?.schemas || {})) {
676
689
  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
677
- 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})`);
678
691
  continue;
679
692
  }
680
693
  // Fail closed on refs: typebox compiles an unresolvable $ref to a never-matching schema
@@ -703,25 +716,26 @@ export function validateWorkflow(workflow, opts) {
703
716
  for (const ref of refs) {
704
717
  const match = ref.match(/^#\/definitions\/(.+)$/);
705
718
  if (!match)
706
- 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)`);
707
720
  else if (!Object.hasOwn(definitions, match[1]))
708
- 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`);
709
722
  }
710
723
  try {
711
724
  Compile(resolved);
712
725
  }
713
726
  catch (e) {
714
- 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}`);
715
728
  }
716
729
  }
717
730
  if (opts?.input !== undefined) {
718
731
  if (!opts.input || typeof opts.input !== "object" || Array.isArray(opts.input))
719
- errors.push("input must be a JSON object");
732
+ fail("INPUT_INVALID", "", "input must be a JSON object");
720
733
  else if (declaredInput) {
721
734
  try {
722
735
  const validator = Compile(declaredInput);
723
736
  if (!validator.Check(opts.input))
724
- 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}`);
725
739
  }
726
740
  catch { /* Schema diagnostics above retain the original compilation failure. */ }
727
741
  }
@@ -730,19 +744,20 @@ export function validateWorkflow(workflow, opts) {
730
744
  if (map === undefined)
731
745
  return;
732
746
  if (!map || typeof map !== "object" || Array.isArray(map)) {
733
- 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`);
734
748
  return;
735
749
  }
736
750
  checkInterpolations(map, label, path);
737
751
  };
738
752
  const checkQuestionSchema = (schemaId, label, path) => {
739
753
  if (typeof schemaId !== "string" || !Object.hasOwn(workflow.schemas, schemaId)) {
740
- 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`);
741
755
  return null;
742
756
  }
743
757
  const compiled = compileQuestions(workflow.schemas[schemaId], workflow.schemas);
744
758
  if (compiled.ok === false) {
745
- 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}`);
746
761
  return null;
747
762
  }
748
763
  return compiled.questions;
@@ -753,42 +768,45 @@ export function validateWorkflow(workflow, opts) {
753
768
  // (GRE-2809), naming a predicate the object used as a key when it did.
754
769
  if (pred && typeof pred === "object" && !Array.isArray(pred) && name === undefined) {
755
770
  const keyed = Object.keys(pred).find((key) => PREDICATES.has(key));
756
- errors.push(`${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}": {...}}` : ""}`);
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}": {...}}` : ""}`);
757
772
  return false;
758
773
  }
759
774
  if (!pred || !PREDICATES.has(name) || (mechanicalOnly && !MECHANICAL_PREDICATE_NAMES.has(name))) {
760
- 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)" : ""}`);
761
776
  return false;
762
777
  }
763
- 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}`);
764
780
  if (name === "ask")
765
781
  checkStateMap(pred.state, label, path, `${field}.state`);
766
782
  return true;
767
783
  };
768
- 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);
769
787
  if (!node || typeof node !== "object" || !KINDS.has(node.node)) {
770
- errors.push(`${path}: unknown node kind "${node?.node}"`);
788
+ fail("NODE_KIND_UNKNOWN", ptrOf(path), `${path}: unknown node kind "${node?.node}"`);
771
789
  return;
772
790
  }
773
791
  {
774
792
  const allowed = KIND_KEYS[node.node];
775
793
  const extraneous = Object.keys(node).filter((key) => !allowed.has(key));
776
794
  if (extraneous.length)
777
- 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(", ")}`);
778
796
  // `$`-prefixed state keys are engine-owned (`$host`, `<as>$verify`): no node may write one. A label
779
797
  // is the state key whenever `as` is omitted, so labels are held to the same rule.
780
798
  if (typeof node.as === "string" && node.as.startsWith("$"))
781
- 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}")`);
782
800
  // Only an unaliased generative or code node writes under its label; every other label is a name, not a key.
783
801
  const labelIsKey = (node.node === "agent" || node.node === "decide" || node.node === "extract" || node.node === "code") && node.as === undefined;
784
802
  if (labelIsKey && typeof node.label === "string" && node.label.startsWith("$"))
785
- 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`);
786
804
  }
787
805
  switch (node.node) {
788
806
  case "chain":
789
807
  if (!Array.isArray(node.steps) || !node.steps.length)
790
- errors.push(`${path}: chain needs steps`);
791
- (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}`));
792
810
  return;
793
811
  case "code":
794
812
  try {
@@ -798,7 +816,7 @@ export function validateWorkflow(workflow, opts) {
798
816
  compileTransform(node.code);
799
817
  }
800
818
  catch (e) {
801
- errors.push(`${path} (${node.label}): ${e?.message || e}`);
819
+ fail("CODE_INVALID", ptrOf(path), `${path} (${node.label}): ${e?.message || e}`);
802
820
  }
803
821
  if (reachability) {
804
822
  const patches = probeCodePatches(node.code, { path, label: node.label });
@@ -828,34 +846,34 @@ export function validateWorkflow(workflow, opts) {
828
846
  if (node.state !== undefined)
829
847
  checkStateMap(node.state, node.label, path);
830
848
  if (!node.instructions?.trim())
831
- errors.push(`${path} (${node.label}): instructions required`);
849
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): instructions required`);
832
850
  if (node.node !== "report" && !Object.hasOwn(workflow.schemas, node.out))
833
- errors.push(`${path} (${node.label}): out schema "${node.out}" not in workflow.schemas`);
851
+ fail("SCHEMA_UNKNOWN", ptrOf(path), `${path} (${node.label}): out schema "${node.out}" not in workflow.schemas`);
834
852
  if (node.thinking !== undefined && !THINKING_LEVELS.includes(String(node.thinking)))
835
- errors.push(`${path} (${node.label}): thinking must be low|medium|high — thinking is never off`);
853
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): thinking must be low|medium|high — thinking is never off`);
836
854
  if (node.tools !== undefined && (!Array.isArray(node.tools) || node.tools.some((t) => typeof t !== "string" || !t.trim())))
837
- 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)`);
838
856
  checkRequires(node, path);
839
857
  if (node.tier !== undefined && !MODEL_TIERS.includes(String(node.tier)))
840
- errors.push(`${path} (${node.label}): tier must be fast|default|strong`);
858
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): tier must be fast|default|strong`);
841
859
  if (node.node === "agent" && node.budget_usd !== undefined && !(typeof node.budget_usd === "number" && Number.isFinite(node.budget_usd) && node.budget_usd > 0))
842
- errors.push(`${path} (${node.label}): budget_usd must be a number of dollars greater than 0`);
860
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): budget_usd must be a number of dollars greater than 0`);
843
861
  if (node.node === "agent" && node.context !== undefined && !AGENT_CONTEXTS.includes(String(node.context)))
844
- errors.push(`${path} (${node.label}): context must be ${AGENT_CONTEXTS.join("|")}`);
862
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): context must be ${AGENT_CONTEXTS.join("|")}`);
845
863
  if (node.node !== "report" && node.verify !== undefined) {
846
864
  const v = node.verify;
847
865
  if (!v || typeof v !== "object" || typeof v.out !== "string")
848
- 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)`);
849
867
  else {
850
868
  const qs = checkQuestionSchema(v.out, node.label, path);
851
869
  if (qs && !Object.values(qs).some((q) => q.type === "noul"))
852
- 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)`);
853
871
  if (v.state !== undefined)
854
872
  checkStateMap(v.state, node.label, path, "verify.state");
855
873
  if (v.maxDrives !== undefined && (!Number.isInteger(v.maxDrives) || v.maxDrives < 1))
856
- errors.push(`${path} (${node.label}): verify.maxDrives must be an integer >= 1`);
874
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): verify.maxDrives must be an integer >= 1`);
857
875
  if (v.override !== undefined && (typeof v.override?.below !== "number" || v.override.below <= 0 || v.override.below >= 1))
858
- 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)`);
859
877
  }
860
878
  }
861
879
  if (reachability && node.node === "report") {
@@ -874,32 +892,44 @@ export function validateWorkflow(workflow, opts) {
874
892
  return;
875
893
  case "map":
876
894
  if (node.resultPath !== undefined && (typeof node.resultPath !== "string" || !node.resultPath.trim()))
877
- 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`);
878
896
  if (node.maxConcurrency !== undefined && (!Number.isSafeInteger(node.maxConcurrency) || node.maxConcurrency < 1))
879
- 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`);
880
898
  if (!node.itemsPath)
881
- errors.push(`${path} (${node.label}): itemsPath required`);
899
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): itemsPath required`);
882
900
  checkItemsPath(node, path);
883
901
  if (!node.as)
884
- 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"`);
885
915
  if (containsReportNode(node.body))
886
- 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)`);
887
917
  if (reachability)
888
918
  reachability.unknowable = true;
889
- walk(node.body, `${path}.body`);
919
+ walk(node.body, `${path}.body`, `${ptr}/body`);
890
920
  return;
891
921
  case "parallel":
892
922
  if (!Array.isArray(node.branches) || node.branches.length < 2)
893
- 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`);
894
924
  if (containsReportNode(node))
895
- errors.push(`${path} (${node.label}): a report node cannot live inside a parallel branch — the report is rendered once, after every branch has landed`);
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`);
896
926
  {
897
927
  const writers = new Map();
898
928
  (node.branches || []).forEach((branch, i) => {
899
929
  for (const key of declaredWrites(branch)) {
900
930
  const prior = writers.get(key);
901
931
  if (prior !== undefined && prior !== i)
902
- 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`);
903
933
  writers.set(key, i);
904
934
  }
905
935
  });
@@ -911,7 +941,7 @@ export function validateWorkflow(workflow, opts) {
911
941
  const after = [];
912
942
  (node.branches || []).forEach((branch, i) => {
913
943
  restoreKnowledge(before);
914
- walk(branch, `${path}.branches[${i}]`);
944
+ walk(branch, `${path}.branches[${i}]`, `${ptr}/branches/${i}`);
915
945
  after.push(snapshotKnowledge());
916
946
  });
917
947
  if (after.length)
@@ -922,11 +952,11 @@ export function validateWorkflow(workflow, opts) {
922
952
  return;
923
953
  case "loop":
924
954
  if (!Number.isInteger(node.maxIters) || node.maxIters < 1)
925
- errors.push(`${path} (${node.label}): maxIters must be an integer >= 1`);
955
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): maxIters must be an integer >= 1`);
926
956
  if (node.expect_iters !== undefined && (!Number.isInteger(node.expect_iters) || node.expect_iters < 1))
927
- errors.push(`${path} (${node.label}): expect_iters must be an integer >= 1`);
957
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): expect_iters must be an integer >= 1`);
928
958
  if (containsReportNode(node.body))
929
- 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`);
930
960
  checkPredicate(node.until, node.label, path, "until");
931
961
  {
932
962
  // `until` reads the state after the body: the keys before the loop plus every key the body writes.
@@ -936,25 +966,25 @@ export function validateWorkflow(workflow, opts) {
936
966
  }
937
967
  if (reachability)
938
968
  reachability.unknowable = true;
939
- walk(node.body, `${path}.body`);
969
+ walk(node.body, `${path}.body`, `${ptr}/body`);
940
970
  return;
941
971
  case "escalate":
942
972
  mayEscalate = true;
943
973
  checkPredicate(node.when, node.label, path, "when");
944
974
  if (!node.kind?.trim() || !node.stage?.trim() || !node.summary?.trim())
945
- errors.push(`${path} (${node.label}): kind, stage, summary required`);
975
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): kind, stage, summary required`);
946
976
  checkPredicateHead(node.when, node.label, path, "when");
947
977
  checkPredicatePath(node.when, node.label, path);
948
978
  return;
949
979
  case "judge": {
950
980
  const label = node.label || "judge";
951
981
  if (!node.state || typeof node.state !== "object" || Array.isArray(node.state) || !Object.keys(node.state).length)
952
- 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`);
953
983
  else
954
984
  checkStateMap(node.state, label, path);
955
985
  checkQuestionSchema(node.out, label, path);
956
986
  if (!node.as?.trim())
957
- errors.push(`${path} (${label}): as required`);
987
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): as required`);
958
988
  checkRequires({ label, requires: node.requires }, path);
959
989
  if (reachability && node.as) {
960
990
  reachability.available.add(node.as);
@@ -969,17 +999,17 @@ export function validateWorkflow(workflow, opts) {
969
999
  case "pick": {
970
1000
  const label = node.label || "pick";
971
1001
  if (!node.itemsPath?.trim())
972
- errors.push(`${path} (${label}): itemsPath required`);
1002
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): itemsPath required`);
973
1003
  checkItemsPath(node, path);
974
1004
  if (typeof node.describe !== "string" || !node.describe.trim())
975
- 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`);
976
1006
  if (typeof node.instructions !== "string" || !node.instructions.trim())
977
- errors.push(`${path} (${label}): instructions (the one question) required`);
1007
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): instructions (the one question) required`);
978
1008
  checkStateMap(node.state, label, path);
979
1009
  if (!node.as?.trim())
980
- errors.push(`${path} (${label}): as required`);
1010
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): as required`);
981
1011
  if (node.allowNone !== undefined && typeof node.allowNone !== "boolean")
982
- errors.push(`${path} (${label}): allowNone must be boolean`);
1012
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): allowNone must be boolean`);
983
1013
  checkRequires({ label, requires: node.requires }, path);
984
1014
  if (reachability && node.as) {
985
1015
  reachability.available.add(node.as);
@@ -993,27 +1023,27 @@ export function validateWorkflow(workflow, opts) {
993
1023
  case "sift": {
994
1024
  const label = node.label || "sift";
995
1025
  if (!node.itemsPath?.trim())
996
- errors.push(`${path} (${label}): itemsPath required`);
1026
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): itemsPath required`);
997
1027
  checkItemsPath(node, path);
998
1028
  if (node.describe !== undefined && (typeof node.describe !== "string" || !node.describe.trim()))
999
- 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`);
1000
1030
  checkStateMap(node.state, label, path);
1001
1031
  const compiled = checkQuestionSchema(node.out, label, path);
1002
1032
  if (!node.as?.trim())
1003
- errors.push(`${path} (${label}): as required`);
1033
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): as required`);
1004
1034
  if (node.keep !== undefined) {
1005
1035
  const k = node.keep;
1006
1036
  if (!k || typeof k !== "object" || typeof k.path !== "string" || !k.path.trim())
1007
- 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)`);
1008
1038
  else if (compiled) {
1009
1039
  const [id, tail] = k.path.split(".");
1010
1040
  if (!Object.hasOwn(compiled, id) || (tail !== undefined && tail !== "confidence"))
1011
- 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)}"`);
1012
1042
  else if (compiled[id].type === "choice" && tail !== "confidence")
1013
- 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`);
1014
1044
  }
1015
1045
  if (k?.gte !== undefined && !(typeof k.gte === "number" && Number.isFinite(k.gte)))
1016
- 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`);
1017
1047
  }
1018
1048
  checkRequires({ label, requires: node.requires }, path);
1019
1049
  if (reachability && node.as) {
@@ -1032,50 +1062,50 @@ export function validateWorkflow(workflow, opts) {
1032
1062
  if (byValue) {
1033
1063
  const valuePath = raw.valuePath;
1034
1064
  if (typeof valuePath !== "string" || !valuePath.trim())
1035
- errors.push(`${path} (${label}): valuePath must be the state path of the branch name`);
1065
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): valuePath must be the state path of the branch name`);
1036
1066
  for (const key of ["state", "instructions", "unsure"])
1037
1067
  if (raw[key] !== undefined)
1038
- errors.push(`${path} (${label}): ${key} belongs to a route Jev chooses; a route by valuePath asks no question`);
1068
+ fail("NODE_KEY_UNKNOWN", ptrOf(path), `${path} (${label}): ${key} belongs to a route Jev chooses; a route by valuePath asks no question`);
1039
1069
  if (names.length < 2)
1040
- errors.push(`${path} (${label}): route needs at least two named branches`);
1070
+ fail("STRUCTURE_INVALID", ptrOf(path), `${path} (${label}): route needs at least two named branches`);
1041
1071
  if (names.some(name => !name.trim()))
1042
- errors.push(`${path} (${label}): branch names must be non-empty`);
1072
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): branch names must be non-empty`);
1043
1073
  if (raw.otherwise !== undefined && (typeof raw.otherwise !== "string" || !names.includes(raw.otherwise)))
1044
- errors.push(`${path} (${label}): otherwise must name one of the branches`);
1074
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): otherwise must name one of the branches`);
1045
1075
  if (typeof valuePath === "string" && valuePath.trim() && reachability && !reachability.unknowable) {
1046
1076
  const head = valuePath.split(".")[0];
1047
1077
  if (!reachability.available.has(head))
1048
- errors.push(`${path} (${label}): valuePath "${valuePath}" has no upstream producer; route by the key an earlier node writes`);
1078
+ fail("STATE_PATH_UNPRODUCED", ptrOf(path), `${path} (${label}): valuePath "${valuePath}" has no upstream producer; route by the key an earlier node writes`);
1049
1079
  else
1050
- checkTypedPath(valuePath, `${path} (${label}) valuePath`);
1080
+ checkTypedPath(valuePath, `${path} (${label}) valuePath`, ptrOf(path));
1051
1081
  }
1052
1082
  }
1053
1083
  else {
1054
1084
  const judged = node;
1055
1085
  if (!judged.state || typeof judged.state !== "object" || Array.isArray(judged.state) || !Object.keys(judged.state).length)
1056
- errors.push(`${path} (${label}): state must be a non-empty object map of what the question sees`);
1086
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): state must be a non-empty object map of what the question sees`);
1057
1087
  else
1058
1088
  checkStateMap(judged.state, label, path);
1059
1089
  if (typeof judged.instructions !== "string" || !judged.instructions.trim())
1060
- errors.push(`${path} (${label}): instructions (the one question) required`);
1090
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): instructions (the one question) required`);
1061
1091
  if (raw.otherwise !== undefined)
1062
- errors.push(`${path} (${label}): otherwise belongs to a route by valuePath; a route Jev chooses takes unsure for its fallback`);
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`);
1063
1093
  if (names.length < 2)
1064
- errors.push(`${path} (${label}): route needs at least two named branches`);
1094
+ fail("STRUCTURE_INVALID", ptrOf(path), `${path} (${label}): route needs at least two named branches`);
1065
1095
  if (names.length > SYSTEM_ONE_LIMITS.maxChoiceOptions)
1066
- errors.push(`${path} (${label}): route takes at most ${SYSTEM_ONE_LIMITS.maxChoiceOptions} branches`);
1096
+ fail("STRUCTURE_INVALID", ptrOf(path), `${path} (${label}): route takes at most ${SYSTEM_ONE_LIMITS.maxChoiceOptions} branches`);
1067
1097
  if (judged.unsure !== undefined) {
1068
1098
  const u = judged.unsure;
1069
1099
  if (!u || typeof u.branch !== "string" || !names.includes(u.branch))
1070
- errors.push(`${path} (${label}): unsure.branch must name one of the branches`);
1100
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): unsure.branch must name one of the branches`);
1071
1101
  if (!(typeof u?.gte === "number" && u.gte > 0 && u.gte <= 1))
1072
- errors.push(`${path} (${label}): unsure.gte must be in (0, 1]`);
1102
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): unsure.gte must be in (0, 1]`);
1073
1103
  }
1074
1104
  }
1075
1105
  if (containsReportNode(node))
1076
- 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`);
1077
1107
  if (node.as !== undefined && (typeof node.as !== "string" || !node.as.trim()))
1078
- 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`);
1079
1109
  checkRequires({ label, requires: node.requires }, path);
1080
1110
  if (reachability) {
1081
1111
  if (typeof node.as === "string" && node.as.trim()) {
@@ -1088,14 +1118,14 @@ export function validateWorkflow(workflow, opts) {
1088
1118
  for (const name of names) {
1089
1119
  const branch = raw.branches[name];
1090
1120
  if (!branch || typeof branch !== "object" || !branch.body) {
1091
- errors.push(`${path} (${label}): branch "${name}" needs a body`);
1121
+ fail("STRUCTURE_INVALID", ptrOf(path), `${path} (${label}): branch "${name}" needs a body`);
1092
1122
  continue;
1093
1123
  }
1094
1124
  if (byValue && branch.criteria !== undefined)
1095
- errors.push(`${path} (${label}): branch "${name}" criteria are for Jev; a route by valuePath matches the branch name exactly`);
1125
+ fail("NODE_KEY_UNKNOWN", ptrOf(path), `${path} (${label}): branch "${name}" criteria are for Jev; a route by valuePath matches the branch name exactly`);
1096
1126
  else if (branch.criteria !== undefined && typeof branch.criteria !== "string")
1097
- errors.push(`${path} (${label}): branch "${name}" criteria must be a string`);
1098
- walk(branch.body, `${path}.branches.${name}`);
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`);
1099
1129
  }
1100
1130
  return;
1101
1131
  }
@@ -1103,14 +1133,14 @@ export function validateWorkflow(workflow, opts) {
1103
1133
  const label = node.label || "artifact";
1104
1134
  const type = typeof node.type === "string" && node.type.trim() ? node.type : null;
1105
1135
  if (!type)
1106
- 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`);
1107
1137
  for (const key of ["instructions", "state", "sopSection", "tools", "effort", "thinking"])
1108
1138
  if (node[key] !== undefined)
1109
- 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`);
1110
1140
  if (typeof node.path !== "string" || !node.path.trim() || node.path.startsWith("/") || node.path.split("/").includes(".."))
1111
- 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`);
1112
1142
  else if (reachability && !producedFiles.has(node.path))
1113
- 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)`);
1114
1144
  checkRequires({ label, requires: node.requires }, path);
1115
1145
  if (reachability) {
1116
1146
  reachability.available.add("artifact");
@@ -1121,25 +1151,26 @@ export function validateWorkflow(workflow, opts) {
1121
1151
  case "workflow": {
1122
1152
  const label = typeof node.label === "string" && node.label.trim() ? node.label : "workflow";
1123
1153
  if (typeof node.label !== "string" || !node.label.trim() || typeof node.as !== "string" || !node.as.trim())
1124
- 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`);
1125
1155
  if (!Object.hasOwn(workflow.schemas, node.out))
1126
- 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`);
1127
1157
  if (!node.input || typeof node.input !== "object" || Array.isArray(node.input))
1128
- 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`);
1129
1159
  else if (Object.hasOwn(node.input, HOST_STATE_KEY))
1130
- errors.push(`${path} (${label}): input must not contain the reserved "${HOST_STATE_KEY}" key`);
1160
+ fail("STATE_KEY_RESERVED", ptrOf(path), `${path} (${label}): input must not contain the reserved "${HOST_STATE_KEY}" key`);
1131
1161
  const child = node.workflow;
1132
1162
  const steps = childSteps(child);
1133
1163
  if (!child || typeof child !== "object" || !steps || !steps.length)
1134
- 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`);
1135
1165
  else {
1136
1166
  if (containsReportNode(child.root))
1137
- 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`);
1138
1168
  if (typeof child.input?.schemaId !== "string" || !Object.hasOwn(child.schemas, child.input.schemaId))
1139
- 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`);
1140
1170
  const validated = validateWorkflow(child, { executeCode: opts?.executeCode, inputKeys: Object.keys(node.input && typeof node.input === "object" ? node.input : {}) });
1141
1171
  if (!validated.ok)
1142
- 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}`);
1143
1174
  for (const step of steps)
1144
1175
  if (step.node === "call" && Array.isArray(step.produces))
1145
1176
  for (const file of step.produces)
@@ -1156,91 +1187,91 @@ export function validateWorkflow(workflow, opts) {
1156
1187
  case "call": {
1157
1188
  const label = node.label || "call";
1158
1189
  if (!CALL_TRANSPORTS.includes(String(node.via)))
1159
- errors.push(`${path} (${label}): via must be tool|executor|shell`);
1190
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): via must be tool|executor|shell`);
1160
1191
  if (node.via === "tool") {
1161
1192
  if (!node.tool?.trim())
1162
- 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`);
1163
1194
  if (node.args !== undefined && (!node.args || typeof node.args !== "object" || Array.isArray(node.args)))
1164
- errors.push(`${path} (${label}): args must be an object`);
1195
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): args must be an object`);
1165
1196
  for (const key of ["code", "input", "command", "env"])
1166
1197
  if (node[key] !== undefined)
1167
- 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`);
1168
1199
  }
1169
1200
  if (node.via === "executor") {
1170
1201
  if (!node.code?.trim())
1171
- 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`);
1172
1203
  if (!/\breturn\b/.test(String(node.code || "")))
1173
- 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`);
1174
1205
  if (/\b(require|process|fetch|eval|Function|import)\s*\(?/.test(String(node.code || "")))
1175
- 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)`);
1176
1207
  if (node.input !== undefined && (!node.input || typeof node.input !== "object" || Array.isArray(node.input)))
1177
- errors.push(`${path} (${label}): input must be an object`);
1208
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): input must be an object`);
1178
1209
  for (const key of ["tool", "args", "command", "env"])
1179
1210
  if (node[key] !== undefined)
1180
- 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`);
1181
1212
  }
1182
1213
  if (node.via === "shell") {
1183
1214
  if (!node.command?.trim())
1184
- errors.push(`${path} (${label}): via shell needs a command`);
1215
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): via shell needs a command`);
1185
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")))
1186
- 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`);
1187
1218
  if (node.out !== undefined)
1188
- 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`);
1189
1220
  for (const key of ["tool", "args", "code", "input"])
1190
1221
  if (node[key] !== undefined)
1191
- 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`);
1192
1223
  }
1193
1224
  else if (node.produces?.length) {
1194
- 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`);
1195
1226
  }
1196
1227
  if (node.via !== "shell") {
1197
1228
  if (!node.out)
1198
- 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`);
1199
1230
  else if (!Object.hasOwn(workflow.schemas, node.out))
1200
- 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`);
1201
1232
  }
1202
1233
  if (!node.as?.trim())
1203
- errors.push(`${path} (${label}): as required`);
1234
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): as required`);
1204
1235
  if (node.where !== undefined && node.where !== "sandbox")
1205
- errors.push(`${path} (${label}): where accepts only "sandbox"`);
1236
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): where accepts only "sandbox"`);
1206
1237
  if (!(Number.isFinite(node.deadline_s) && node.deadline_s > 0))
1207
- errors.push(`${path} (${label}): deadline_s is required and must be a finite number greater than 0 seconds`);
1238
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): deadline_s is required and must be a finite number greater than 0 seconds`);
1208
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(".."))))
1209
- 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`);
1210
1241
  else
1211
1242
  for (const f of node.produces || [])
1212
1243
  producedFiles.add(f);
1213
1244
  if (node.retry !== undefined) {
1214
1245
  const r = node.retry;
1215
1246
  if (!r || !Number.isInteger(r.attempts) || r.attempts < 1)
1216
- errors.push(`${path} (${label}): retry.attempts must be an integer >= 1`);
1247
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): retry.attempts must be an integer >= 1`);
1217
1248
  if (r?.backoff_s !== undefined && !(Number.isFinite(r.backoff_s) && r.backoff_s >= 0))
1218
- errors.push(`${path} (${label}): retry.backoff_s must be a finite number >= 0`);
1249
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): retry.backoff_s must be a finite number >= 0`);
1219
1250
  if (r?.on !== undefined && (!Array.isArray(r.on) || r.on.some((c) => !RETRY_ON_NAMES.includes(String(c)))))
1220
- errors.push(`${path} (${label}): retry.on may name only ${RETRY_ON_NAMES.join("|")}`);
1251
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): retry.on may name only ${RETRY_ON_NAMES.join("|")}`);
1221
1252
  }
1222
1253
  if (node.poll !== undefined) {
1223
1254
  const p = node.poll;
1224
1255
  if (!p || typeof p !== "object" || Array.isArray(p))
1225
- errors.push(`${path} (${label}): poll must be an object`);
1256
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): poll must be an object`);
1226
1257
  else {
1227
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;
1228
1259
  for (const [name, pred] of [["until", p.until], ["fail_when", p.fail_when]]) {
1229
1260
  if (pred === undefined) {
1230
1261
  if (name === "until")
1231
- errors.push(`${path} (${label}): poll.until is required`);
1262
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): poll.until is required`);
1232
1263
  continue;
1233
1264
  }
1234
1265
  if (!checkPredicate(pred, label, path, `poll.${name}`, true))
1235
1266
  continue;
1236
1267
  const predPath = pred.path;
1237
1268
  if (resultShape && typeof resultShape === "object" && predPath && resultPathMissing(resultShape, predPath))
1238
- 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`);
1239
1270
  }
1240
1271
  if (!(Number.isFinite(p.interval_s) && p.interval_s >= 0.1))
1241
- errors.push(`${path} (${label}): poll.interval_s must be a finite number of at least 0.1 seconds`);
1272
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): poll.interval_s must be a finite number of at least 0.1 seconds`);
1242
1273
  if (!(Number.isFinite(p.deadline_s) && p.deadline_s >= (Number(node.deadline_s) || 0)))
1243
- errors.push(`${path} (${label}): poll.deadline_s must be a finite number at least deadline_s`);
1274
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): poll.deadline_s must be a finite number at least deadline_s`);
1244
1275
  }
1245
1276
  }
1246
1277
  checkRequires({ label, requires: node.requires }, path);
@@ -1257,7 +1288,7 @@ export function validateWorkflow(workflow, opts) {
1257
1288
  }
1258
1289
  }
1259
1290
  };
1260
- walk(workflow?.root, "root");
1291
+ walk(workflow?.root, "root", "/root");
1261
1292
  {
1262
1293
  const countReports = (node) => {
1263
1294
  if (!node || typeof node !== "object")
@@ -1276,39 +1307,42 @@ export function validateWorkflow(workflow, opts) {
1276
1307
  };
1277
1308
  const total = countReports(workflow?.root);
1278
1309
  if (total > 1)
1279
- 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`);
1280
1311
  else if (total === 1) {
1281
1312
  const rootSteps = workflow?.root?.node === "chain" ? workflow.root.steps || [] : [workflow?.root];
1282
1313
  const lastStep = rootSteps[rootSteps.length - 1];
1283
1314
  if (!lastStep || (lastStep.node !== "report" && lastStep.node !== "artifact")) {
1284
- 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`);
1285
1316
  }
1286
1317
  }
1287
1318
  }
1288
1319
  {
1320
+ // Each placement with its pointer: one node object a TypeScript author placed twice is two nodes of the document.
1289
1321
  const llmNodes = [];
1290
- const collect = (node) => {
1322
+ const collect = (node, ptr) => {
1291
1323
  if (!node || typeof node !== "object")
1292
1324
  return;
1293
1325
  if (node.node === "agent" || node.node === "decide" || node.node === "extract" || node.node === "report")
1294
- llmNodes.push(node);
1326
+ llmNodes.push({ node, ptr });
1295
1327
  if (node.node === "chain")
1296
- (node.steps || []).forEach(collect);
1328
+ (node.steps || []).forEach((step, i) => collect(step, `${ptr}/steps/${i}`));
1297
1329
  if (node.node === "parallel")
1298
- (node.branches || []).forEach(collect);
1330
+ (node.branches || []).forEach((branch, i) => collect(branch, `${ptr}/branches/${i}`));
1299
1331
  if (node.node === "map" || node.node === "loop")
1300
- collect(node.body);
1332
+ collect(node.body, `${ptr}/body`);
1301
1333
  if (node.node === "route")
1302
- 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`);
1303
1337
  };
1304
- collect(workflow?.root);
1305
- if (llmNodes.some((n) => n.node === "report")) {
1306
- 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) {
1307
1341
  if (node.node === "report" || node.node === "agent")
1308
1342
  continue;
1309
1343
  const properties = (Object.hasOwn(workflow.schemas, node.out) ? workflow.schemas[node.out] : undefined)?.properties;
1310
1344
  if (properties && Object.prototype.hasOwnProperty.call(properties, "report_markdown")) {
1311
- 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}"`);
1312
1346
  }
1313
1347
  }
1314
1348
  }
@@ -1316,9 +1350,9 @@ export function validateWorkflow(workflow, opts) {
1316
1350
  if (reachability && !reachability.unknowable && !mayEscalate && workflow?.output?.path) {
1317
1351
  const head = workflow.output.path.split(".")[0];
1318
1352
  if (!reachability.available.has(head))
1319
- 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)`);
1320
1354
  else
1321
- checkTypedPath(workflow.output.path, "output");
1355
+ checkTypedPath(workflow.output.path, "output", "");
1322
1356
  }
1323
1357
  // Output-completeness: when the node writing the output path is a probeable code node, its
1324
1358
  // probed shape must carry every REQUIRED key of the output schema. A required field added to
@@ -1364,14 +1398,15 @@ export function validateWorkflow(workflow, opts) {
1364
1398
  bestMissing = missing;
1365
1399
  }
1366
1400
  if (bestMissing?.length) {
1367
- 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`);
1368
1402
  }
1369
1403
  }
1370
1404
  }
1371
1405
  if (!errors.length)
1372
- errors.push(...workflowShapeErrors(workflow, true));
1406
+ for (const issue of workflowShapeIssues(workflow, true))
1407
+ fail("SHAPE_INVALID", issue.path, issue.message);
1373
1408
  const warnings = workflowWarnings(workflow);
1374
- return errors.length ? { ok: false, errors, ...(warnings.length ? { warnings } : {}) } : { ok: true, ...(warnings.length ? { warnings } : {}) };
1409
+ return errors.length ? { ok: false, errors, issues, ...(warnings.length ? { warnings } : {}) } : { ok: true, ...(warnings.length ? { warnings } : {}) };
1375
1410
  }
1376
1411
  function interpolate(template, state) {
1377
1412
  return template.replace(/\{([a-zA-Z0-9_.$]+)\}/g, (_, p) => {
@@ -1425,12 +1460,15 @@ export function schemaProblems(validator, candidate) {
1425
1460
  export class WorkflowInvalidError extends Error {
1426
1461
  workflowName;
1427
1462
  problems;
1463
+ issues;
1428
1464
  code = "workflow_invalid";
1429
1465
  stage = "validate";
1430
- constructor(workflowName, problems) {
1466
+ /** `problems` are validateWorkflow's `errors`; `issues` its issues, one per problem in the same order. */
1467
+ constructor(workflowName, problems, issues = []) {
1431
1468
  super(`workflow "${workflowName}" is invalid: ${problems.join("; ")}`);
1432
1469
  this.workflowName = workflowName;
1433
1470
  this.problems = problems;
1471
+ this.issues = issues;
1434
1472
  this.name = "WorkflowInvalidError";
1435
1473
  }
1436
1474
  }
@@ -1518,6 +1556,46 @@ export class WorkflowStateError extends Error {
1518
1556
  this.name = "WorkflowStateError";
1519
1557
  }
1520
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
+ }
1521
1599
  export function stageSchemaForNode(workflow, node) {
1522
1600
  if (node.node === "report")
1523
1601
  return REPORT_SCHEMA;
@@ -2246,6 +2324,8 @@ function scopeDepsToItem(deps, item, signal) {
2246
2324
  pollStartedAt: (node, nestedItem, path) => recovery.pollStartedAt(node, nestedItem ?? item, path),
2247
2325
  wait: (node, ms, nestedItem, path) => recovery.wait(node, ms, nestedItem ?? item, path),
2248
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) } : {}),
2249
2329
  ...(recovery.decision ? { decision: id => recovery.decision(id) } : {}),
2250
2330
  } } : {}),
2251
2331
  };
@@ -2270,6 +2350,8 @@ function scopeDepsToChild(deps, invocation) {
2270
2350
  pollStartedAt: (node, item, path) => recovery.pollStartedAt(relabel(node), item, path),
2271
2351
  wait: (node, ms, item, path) => recovery.wait(relabel(node), ms, item, path),
2272
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) } : {}),
2273
2355
  ...(recovery.decision ? { decision: id => recovery.decision(id) } : {}),
2274
2356
  } } : {}),
2275
2357
  ...(deps.onEvent ? { onEvent: forwardObserver(deps.onEvent, event => ({ ...event, label: `${prefix}/${event.label}` })) } : {}),
@@ -2366,6 +2448,14 @@ async function runNodeOnState(node, state, workflow, deps) {
2366
2448
  catch (error) {
2367
2449
  if (isStep)
2368
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
+ }
2369
2459
  throw error;
2370
2460
  }
2371
2461
  }
@@ -2499,6 +2589,10 @@ async function runNodeBody(node, state, workflow, deps) {
2499
2589
  if (!Array.isArray(items))
2500
2590
  throw new WorkflowStateError(`map node "${node.label}": ${node.itemsPath} is not a list`, node.label, node.itemsPath, "expected_list");
2501
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);
2502
2596
  let cursor = 0;
2503
2597
  const width = Math.min(node.maxConcurrency ?? 4, Math.max(items.length, 1));
2504
2598
  const siblings = new AbortController();
@@ -2506,6 +2600,18 @@ async function runNodeBody(node, state, workflow, deps) {
2506
2600
  let failure;
2507
2601
  let failed = false;
2508
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
+ };
2509
2615
  await Promise.all(Array.from({ length: width }, async () => {
2510
2616
  while (!signal.aborted) {
2511
2617
  const i = cursor++;
@@ -2516,9 +2622,17 @@ async function runNodeBody(node, state, workflow, deps) {
2516
2622
  // Under recovery each item is its own child: the body's session, effects and commit
2517
2623
  // carry the item, so a resumed map answers finished items from their rows and
2518
2624
  // continues the ones that were running.
2625
+ const itemDeps = scopeDepsToItem(scopeExecution(deps, "items", i, "body"), { label: node.label, index: i }, signal);
2519
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
+ }
2520
2634
  const itemState = snapshotState({ ...state, item: items[i], item_index: i });
2521
- 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);
2522
2636
  if (node.resultPath !== undefined) {
2523
2637
  const selected = node.resultPath.split(".").reduce((value, key) => value == null ? undefined : value[key], out);
2524
2638
  if (selected === undefined)
@@ -2529,20 +2643,30 @@ async function runNodeBody(node, state, workflow, deps) {
2529
2643
  results[i] = node.body.as ? out[node.body.as] : out;
2530
2644
  }
2531
2645
  catch (error) {
2532
- uncertainEffects(error, uncertainties);
2533
- if (!failed) {
2534
- failed = true;
2535
- failure = error;
2536
- 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;
2537
2650
  }
2538
- 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 } });
2539
2662
  }
2540
2663
  }
2541
2664
  }));
2542
2665
  if (failed) {
2543
- failure = withSiblingUncertainty(failure, uncertainties);
2666
+ failure = withSiblingUncertainty(reportedFailure(failure, later), uncertainties);
2544
2667
  const escalated = failure instanceof EscalationSignal;
2545
- 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) } });
2546
2670
  if (!escalated && deps.recovery?.fail) {
2547
2671
  try {
2548
2672
  await deps.recovery.fail(node, results, failure, executionPath(deps));
@@ -2553,7 +2677,7 @@ async function runNodeBody(node, state, workflow, deps) {
2553
2677
  }
2554
2678
  throw failure;
2555
2679
  }
2556
- return { ...state, [node.as]: results };
2680
+ return { ...state, [node.as]: results, ...(collect ? { [node.failedAs]: rows.filter(Boolean) } : {}) };
2557
2681
  }
2558
2682
  case "parallel": {
2559
2683
  // Every branch starts from the same state and runs at once; what comes back is each branch's
@@ -2566,6 +2690,7 @@ async function runNodeBody(node, state, workflow, deps) {
2566
2690
  let failure;
2567
2691
  let failed = false;
2568
2692
  const uncertainties = new Set();
2693
+ const later = [];
2569
2694
  const outs = await Promise.all((node.branches || []).map(async (branch, i) => {
2570
2695
  try {
2571
2696
  return await runNodeOnState(branch, inputs[i], workflow, scopeExecution({ ...deps, signal, checkpoint: undefined }, "branches", i));
@@ -2577,11 +2702,13 @@ async function runNodeBody(node, state, workflow, deps) {
2577
2702
  failure = error;
2578
2703
  siblings.abort(error);
2579
2704
  }
2705
+ else
2706
+ later.push(error);
2580
2707
  return inputs[i];
2581
2708
  }
2582
2709
  }));
2583
2710
  if (failed)
2584
- throw withSiblingUncertainty(failure, uncertainties);
2711
+ throw withSiblingUncertainty(reportedFailure(failure, later), uncertainties);
2585
2712
  const merged = { ...state };
2586
2713
  const writer = new Map();
2587
2714
  // Host state is engine-owned and merges by delta: every branch started from the same `$host`, so an
@@ -2832,6 +2959,9 @@ export function assertWorkflowCapabilities(node, deps, workflow) {
2832
2959
  node.node === "loop" && node.until?.predicate === "ask" ||
2833
2960
  node.node === "escalate" && node.when?.predicate === "ask") && !deps.runJudge)
2834
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");
2835
2965
  if (node.node === "chain")
2836
2966
  node.steps.forEach(n => assertWorkflowCapabilities(n, deps, workflow));
2837
2967
  if (node.node === "parallel")
@@ -2850,7 +2980,7 @@ export async function runWorkflow(workflow, input, deps) {
2850
2980
  const executeCode = deps.runCode ? false : undefined;
2851
2981
  const valid = validateWorkflow(workflow, { executeCode });
2852
2982
  if (!valid.ok)
2853
- throw new WorkflowInvalidError(String(workflow?.name), valid.errors);
2983
+ throw new WorkflowInvalidError(String(workflow?.name), valid.errors, valid.issues);
2854
2984
  workflow = desugarWorkflow(workflow);
2855
2985
  if (workflow.input) {
2856
2986
  const validator = Compile(resolveSchemaForWorkflow(workflow, workflow.schemas[workflow.input.schemaId]));
@@ -2859,7 +2989,7 @@ export async function runWorkflow(workflow, input, deps) {
2859
2989
  }
2860
2990
  const reachable = validateWorkflow(workflow, { executeCode, inputKeys: Object.keys(input) });
2861
2991
  if (!reachable.ok)
2862
- throw new WorkflowInvalidError(workflow.name, reachable.errors);
2992
+ throw new WorkflowInvalidError(workflow.name, reachable.errors, reachable.issues);
2863
2993
  assertWorkflowCapabilities(workflow.root, deps, workflow);
2864
2994
  if (needsComposedRecovery(workflow.root))
2865
2995
  deps = { ...deps, [SCOPED_EFFECTS]: true };
@@ -2890,7 +3020,7 @@ export async function runWorkflow(workflow, input, deps) {
2890
3020
  export async function runWorkflowSlice(workflow, input, focus, deps) {
2891
3021
  const valid = validateWorkflow(workflow, { executeCode: deps.runCode ? false : undefined });
2892
3022
  if (!valid.ok)
2893
- throw new WorkflowInvalidError(String(workflow?.name), valid.errors);
3023
+ throw new WorkflowInvalidError(String(workflow?.name), valid.errors, valid.issues);
2894
3024
  const desugared = desugarWorkflow(workflow);
2895
3025
  const root = desugared.root.node === "chain" ? desugared.root.steps : [desugared.root];
2896
3026
  const labels = root.map((n) => n.label ?? "");