fyflow-orchestration 0.11.0 → 0.12.0

package/dist/browser/chunks/{chunk-5CVSWDCB.js → chunk-4JFQX7DL.js}

@@ -360,10 +360,32 @@ function describeFindings(fs) {
 }
 
 // src/definition/condition.ts
+var INDEX_SPELLING = "\\[(0|[1-9][0-9]{0,8})\\]";
+var INDEXED_SEGMENT = new RegExp(`^([A-Za-z0-9_-]{1,64})((?:${INDEX_SPELLING})+)$`);
+var INDEX2 = new RegExp(INDEX_SPELLING, "g");
+function keyPathSteps(path) {
+  const out = [];
+  for (const seg of path.split(".")) {
+    const m = INDEXED_SEGMENT.exec(seg);
+    if (m === null) {
+      out.push({ key: seg });
+      continue;
+    }
+    out.push({ key: m[1] });
+    for (const i of m[2].matchAll(INDEX2)) out.push({ index: Number(i[1]) });
+  }
+  return out;
+}
 function readKeyPath(value, path) {
   let v = value;
-  for (const seg of path.split(".")) {
+  for (const step2 of keyPathSteps(path)) {
     if (typeof v !== "object" || v === null) return void 0;
+    if ("index" in step2) {
+      if (!Array.isArray(v) || step2.index >= v.length || !Object.prototype.hasOwnProperty.call(v, step2.index)) return void 0;
+      v = v[step2.index];
+      continue;
+    }
+    const seg = step2.key;
     const proto = Object.getPrototypeOf(v);
     if (proto !== Object.prototype && proto !== null) return void 0;
     if (!Object.prototype.hasOwnProperty.call(v, seg)) return void 0;
@@ -514,11 +536,12 @@ function languagesOf(x) {
   if (x instanceof Map) return x;
   return new Map(Object.entries(x));
 }
-var KEY_PATH_RE = /^[A-Za-z0-9_-]{1,64}(?:\.[A-Za-z0-9_-]{1,64})*$/;
+var KEY_PATH_RE = /^[A-Za-z0-9_-]{1,64}(?:\[(?:0|[1-9][0-9]{0,8})\])*(?:\.[A-Za-z0-9_-]{1,64}(?:\[(?:0|[1-9][0-9]{0,8})\])*)*$/;
+var KEY_PATH_WORDS = "dot-separated object keys, each [A-Za-z0-9_-]{1,64} and optionally followed by array indexes [n] (n is 0 or a number with no leading zero, at most 999999999 \u2014 files[0].series, m[0][2]); no index leading the path, no quoted key, no wildcard, no expression";
 function keyPathProblem(v) {
   if (typeof v !== "string") return `settings.key must be a key path string, got ${JSON.stringify(v)}`;
   if (KEY_PATH_RE.test(v)) return null;
-  return `settings.key ${JSON.stringify(v)} is not a key path \u2014 dot-separated object keys, each [A-Za-z0-9_-]{1,64}; no array index, no wildcard, no expression (a key that must be computed is computed in the task before the gate)`;
+  return `settings.key ${JSON.stringify(v)} is not a key path \u2014 ${KEY_PATH_WORDS} (a key that must be computed is computed in the task before the gate)`;
 }
 var GATE_TYPE_KEYS = ["routes", "defaultRoute", "settingsSchema", "keyResolvedRoutes", "routesFor", "settingsProblem", "fn"];
 var STATIC_ROUTE_KEYS = ["routes", "defaultRoute", "keyResolvedRoutes"];
@@ -770,12 +793,17 @@ function leafProblem(o, where, scope = EDGE_SCOPE) {
   }
   const path = o.path;
   if (typeof path !== "string" || !KEY_PATH_RE.test(path)) {
-    return { rule: "FD-V43", message: `${where} path ${JSON.stringify(path)} is not a key path \u2014 dot-separated object keys, each [A-Za-z0-9_-]{1,64}; no array index, no wildcard, no expression` };
+    return { rule: "FD-V43", message: `${where} path ${JSON.stringify(path)} is not a key path \u2014 ${KEY_PATH_WORDS}` };
   }
-  const root = path.split(".")[0];
+  const first = path.split(".")[0];
+  const bracket = first.indexOf("[");
+  const root = bracket === -1 ? first : first.slice(0, bracket);
   if (!scope.roots.includes(root)) {
     return { rule: "FD-V43", message: `${where} path ${JSON.stringify(path)} starts at ${JSON.stringify(root)}, ${scope.foreignRoot(root)}` };
   }
+  if (bracket !== -1) {
+    return { rule: "FD-V43", message: `${where} path ${JSON.stringify(path)} indexes its root ${JSON.stringify(root)} \u2014 a path names a KEY inside its root first, as a gate's key path names a key inside the value that reached it; an index follows a key (${root}.items[0])` };
+  }
   if (path.split(".").length < 2) {
     return { rule: "FD-V43", message: `${where} path ${JSON.stringify(path)} is a root alone ${scope.rootAlone(root)}` };
   }
@@ -1263,8 +1291,15 @@ function validateDefinition(doc, registry) {
       if (nd.edges !== void 0) add("FD-V9", where, "fanout has edges");
       if (nd.branches !== void 0 && !Array.isArray(nd.branches)) {
         add("FD-V21", where, "fanout branches must be an array");
+      } else if (Array.isArray(nd.branches)) {
+        nd.branches.forEach((b, i) => {
+          if (typeof b !== "string") add("FD-V21", where, `fanout branches[${i}] must be a string, got ${describeValue(b)}`);
+        });
       }
     }
+    if (nd.kind === "join" && nd.of !== void 0 && typeof nd.of !== "string") {
+      add("FD-V21", where, `join of must be a string, got ${describeValue(nd.of)}`);
+    }
     if (nd.kind === "map") {
       if (nd.edges !== void 0) add("FD-V25", where, "map has edges");
       if (nd.branch !== void 0 && typeof nd.branch !== "string") {
@@ -2063,7 +2098,7 @@ var typesOf = (s) => {
 };
 var widen = (ts) => ts.flatMap((t) => t === "integer" ? ["integer"] : t === "number" ? ["number", "integer"] : [t]);
 var canon = (v) => JSON.stringify(v);
-var BRANCH_KEY = /^\d+(\.\d+)*$/;
+var BRANCH_KEY = /^(?:0|[1-9][0-9]*)$/;
 var ERROR_SCHEMA = Object.freeze({ type: ["string", "null"] });
 function fits(P, C, path = "$") {
   const p = P;
@@ -2095,7 +2130,7 @@ function fits(P, C, path = "$") {
       if (!own2(pp, k)) {
         if (record !== void 0 && BRANCH_KEY.test(k)) {
           const r2 = fits(record, cp[k], `${path}.${k}`);
-          if (r2.verdict !== "fits") return { verdict: "no", why: `${r2.why} (a branch path the map's record may mint)` };
+          if (r2.verdict !== "fits") return { verdict: "no", why: `${r2.why} (an item index the map's record may mint)` };
           continue;
         }
         if (p.additionalProperties === false) continue;
@@ -2199,14 +2234,21 @@ var Wiring = class {
    * key-resolved route licenses. A step the producer's schema does not describe is left alone rather than
    * invented: `required` on a key no `properties` entry mentions is still a promise the value carries it,
    * which is what the consumer asked about, and describing its SHAPE is not this function's to guess.
+   * **An index step `[n]` raises the array's `minItems` to `n + 1` and ends the walk** (v0.53, ADR 0137) — below.
    */
   requireAlong(schema, key) {
     if (schema === void 0 || key === "") return schema;
-    const steps = key.split(".");
+    const steps = keyPathSteps(key);
     const go = (s, i) => {
       if (i >= steps.length || typeof s !== "object" || s === null || Array.isArray(s)) return s;
       const o = s;
-      const here = steps[i];
+      const step2 = steps[i];
+      if ("index" in step2) {
+        const floor = step2.index + 1;
+        const had = typeof o.minItems === "number" ? o.minItems : 0;
+        return had >= floor ? o : { ...o, minItems: floor };
+      }
+      const here = step2.key;
       const req = Array.isArray(o.required) ? o.required : [];
       const props = o.properties ?? {};
       const described = own2(props, here);
@@ -2226,9 +2268,10 @@ var Wiring = class {
    * the producer can emit.
    *
    * **The question is per STEP and about the CONTAINER, because that is what `readKeyPath` is** —
-   * the DRIVER's own resolution (`src/definition/validate.ts`, W93), where each segment is an OWN key
-   * of a PLAIN object and a missing key, a `null`, an array mid-path or a primitive is `undefined`.
-   * So two shapes forbid a step and the third is a silence:
+   * the DRIVER's own resolution (`src/definition/condition.ts`, W93), where each KEY step is an OWN key
+   * of a PLAIN object and a missing key, a `null`, an array under a key step or a primitive is `undefined`
+   * — and, since v0.53, each INDEX step `[n]` an element of a REAL array (ADR 0137), asked below in the loop.
+   * So, for a key step, two shapes forbid it and the third is a silence:
    *
    * - **its declared types cannot include `object`** — `name.id` where the producer calls `name` a
    *   string. No value the schema admits carries the path.
@@ -2250,13 +2293,21 @@ var Wiring = class {
    * Every rung this repository has is green on a flow that did none of the work it exists for.
    */
   keyPathRefusal(schema, key, gateId, route) {
-    const steps = key.split(".");
+    const steps = keyPathSteps(key);
     let s = schema;
-    const because = (at, detail) => `gate "${gateId}" is keyed on "${key}", which the producer's schema FORBIDS at ${at}: ${detail} \u2014 so route "${route}" can never be taken, and a run may route every branch by another route, doing none of the work this gate guards`;
-    for (let i = 0; i < steps.length; i++) {
-      const here = steps[i];
-      const at = i === 0 ? "$" : `$.${steps.slice(0, i).join(".")}`;
+    let at = "$";
+    const because = (at2, detail) => `gate "${gateId}" is keyed on "${key}", which the producer's schema FORBIDS at ${at2}: ${detail} \u2014 so route "${route}" can never be taken, and a run may route every branch by another route, doing none of the work this gate guards`;
+    for (const step2 of steps) {
       const ts = typesOf(s);
+      if ("index" in step2) {
+        if (!ts.includes("array")) return because(at, `the schema calls it ${ts.join("|")}, and an index [${step2.index}] reads an element of an array`);
+        if (s.items === void 0) return null;
+        if (!isPlainObject3(s.items)) return null;
+        s = s.items;
+        at = `${at}[${step2.index}]`;
+        continue;
+      }
+      const here = step2.key;
       if (!ts.includes("object")) return because(at, `the schema calls it ${ts.join("|")}, and a key path reads an own key of a plain object`);
       const props = s.properties ?? {};
       if (!own2(props, here)) {
@@ -2269,6 +2320,7 @@ var Wiring = class {
       const next = props[here];
       if (!isPlainObject3(next)) return null;
       s = next;
+      at = at === "$" ? `$.${here}` : `${at}.${here}`;
     }
     return null;
   }
@@ -2361,7 +2413,7 @@ var Wiring = class {
     const members = region.branchOf.get(branch) ?? /* @__PURE__ */ new Set();
     return [...members].map((id) => this.byId.get(id)).filter((n) => (n.kind === "task" || n.kind === "ask" || n.kind === "join" || n.kind === "gate") && (n.edges ?? []).some((e) => e.to === region.joinId));
   }
-  /** `JP-R12`'s record for the region a join closes — exact for a fan-out, keyed by minted paths for a map. */
+  /** `JP-R12`'s record for the region a join closes — exact for a fan-out, keyed by entry id; keyed by item index for a map. */
   record(j) {
     const region = this.regions.find((r) => r.joinId === j.id);
     const base = { shape: "record", producer: j.id };
@@ -2385,22 +2437,16 @@ var Wiring = class {
       values.push({ branch: b, schema: firstSchema, sample: first.sample ?? { value: null, source: "witness" } });
     }
     const source = values.every((v2) => v2.sample.source === "example") ? "example" : "witness";
-    const enclosing = new Map(this.regions.filter((r) => r.opensWith === "map" && r.members.has(region.fanoutId)).map((r) => [r.fanoutId, 0]));
     if (opener.kind === "fanout") {
-      const props = {};
-      const sample2 = {};
-      for (const v2 of values) {
-        const path = branchPathOf(this.regions, v2.branch, enclosing);
-        props[path] = v2.schema;
-        sample2[path] = v2.sample.value;
-      }
+      const props = Object.fromEntries(values.map((v2) => [v2.branch, v2.schema]));
+      const sample2 = Object.fromEntries(values.map((v2) => [v2.branch, v2.sample.value]));
       return { ...base, schema: { type: "object", required: [], properties: props, additionalProperties: false }, sample: { value: sample2, source, arity: values.length } };
     }
     const v = values[0];
     if (!v) return { ...base, unchecked: `map "${opener.id}"'s branch never arrives at "${j.id}"` };
     const arity = this.arrivals(opener.branch)[0]?.sample?.arity ?? 1;
     const sample = {};
-    for (let i = 0; i < arity; i++) sample[branchPathOf(this.regions, opener.branch, new Map([...enclosing, [opener.id, i]]))] = v.sample.value;
+    for (let i = 0; i < arity; i++) sample[String(i)] = v.sample.value;
     return {
       ...base,
       schema: { type: "object", additionalProperties: v.schema, branchKeys: true },
@@ -2633,7 +2679,7 @@ var WIRING_SHAPES = ["edge", "branch", "item", "record", "needs", "given"];
 var SEGMENT = /^[A-Za-z0-9_-]{1,64}$/;
 var BRANCH_PATH = /^(?:-|(?:0|[1-9][0-9]*)(?:\.(?:0|[1-9][0-9]*))*)$/;
 var ATTEMPT = /^(?:0|[1-9][0-9]*)$/;
-var INDEX2 = /^(?:0|[1-9][0-9]*)$/;
+var INDEX3 = /^(?:0|[1-9][0-9]*)$/;
 var InvalidRunId = class extends Error {
 };
 var InvalidTaskId = class extends Error {
@@ -2657,7 +2703,7 @@ function branchPathSegment(branchIndex) {
     throw new InvalidTaskId("branchPath must be null for a node in no region, never an empty path");
   }
   for (const n of parts) {
-    if (!INDEX2.test(String(n))) {
+    if (!INDEX3.test(String(n))) {
       throw new InvalidTaskId(`branchPath segment ${JSON.stringify(n)} is not a non-negative integer`);
     }
   }
@@ -2981,7 +3027,7 @@ var RunControlRefused = class extends Error {
     this.reason = reason;
   }
 };
-var CHECKPOINT_FORMAT = 1;
+var CHECKPOINT_FORMAT = 2;
 var ResumeRefused = class extends Error {
   reason;
   /** The position `halted`, `cancelled` and `diverged` name; `null` for the three a header decides. */
@@ -3180,11 +3226,12 @@ function compareBranchPaths(a, b) {
   }
   return 0;
 }
-function collectArrivals(arrived) {
-  const out = {};
-  if (!arrived) return out;
-  for (const path of [...arrived.keys()].sort(compareBranchPaths)) out[path] = arrived.get(path);
-  return out;
+function collectArrivals(arrived, region) {
+  if (!arrived) return {};
+  return Object.fromEntries([...arrived.keys()].sort(compareBranchPaths).map((path) => {
+    const segment = path.slice(path.lastIndexOf(".") + 1);
+    return [region.opensWith === "fanout" ? region.branches[Number(segment)] : segment, arrived.get(path)];
+  }));
 }
 var EMPTY_INDICES = /* @__PURE__ */ new Map();
 var EMPTY_NEEDS = Object.freeze({});
@@ -3367,7 +3414,8 @@ var Driver = class _Driver {
   firedJoins = /* @__PURE__ */ new Map();
   /**
    * **What each branch carried into its join, keyed by region and then by
-   * `branchPath`** — [ADR 0037](../../doc/decisions/0037-what-a-branch-receives-is-a-property-of-the-fan-out-and-what-a-join-carries-is-a-property-of-the-region.md)
+   * `branchPath`** — the FULL path, here where it is recorded; the collection a join hands on is keyed by each
+   * branch's OWN key, derived from these paths by `collectArrivals` at the exit (ADR 0138) —[ADR 0037](../../doc/decisions/0037-what-a-branch-receives-is-a-property-of-the-fan-out-and-what-a-join-carries-is-a-property-of-the-region.md)
    * rule 4, and `JP-R11` in [spec/join-policy.md](../../spec/join-policy.md)
    * section 4.
    *
@@ -6262,7 +6310,7 @@ var Driver = class _Driver {
       fired: true
     });
     if (this.shut()) return;
-    const collected = collectArrivals(this.arrivals.get(region.fanoutId)?.get(rp));
+    const collected = collectArrivals(this.arrivals.get(region.fanoutId)?.get(rp), region);
     this.releaseArrivals(region.fanoutId, rp);
     const reading = this.replay?.reading ?? null;
     if (reading !== null && region.joinId === reading.nodeId) {

package/dist/browser/index.js

@@ -151,11 +151,10 @@ import {
   visibilityKey,
   witness,
   workersOf
-} from "./chunks/chunk-5CVSWDCB.js";
+} from "./chunks/chunk-4JFQX7DL.js";
 
 // src/definition/definition-schema.ts
 var DRAFT_2020_12 = "https://json-schema.org/draft/2020-12/schema";
-var idOrNonString = () => ({ anyOf: [ref("id"), { not: { type: "string" } }] });
 var ref = (name) => ({ $ref: `#/$defs/${name}` });
 function body(re, name) {
   const s = re.source;
@@ -164,6 +163,14 @@ function body(re, name) {
   }
   return s.slice(1, -1);
 }
+function keyPathSegment(id) {
+  const seg = `${id}(?:\\[(?:0|[1-9][0-9]{0,8})\\])*`;
+  const whole = body(KEY_PATH_RE, "KEY_PATH_RE");
+  if (whole !== `${seg}(?:\\.${seg})*`) {
+    throw new Error(`definitionSchema: KEY_PATH_RE (${String(KEY_PATH_RE)}) is no longer one segment pattern repeated \u2014 a comparison's path pattern cannot be derived from it`);
+  }
+  return seg;
+}
 function described(table, key, where) {
   const d = Object.prototype.hasOwnProperty.call(table, key) ? table[key] : void 0;
   if (d === void 0) throw new Error(`definitionSchema: ${where} declares the key "${key}" and no description is written for it`);
@@ -197,7 +204,7 @@ var KIND_DESCRIPTIONS = {
   },
   fanout: {
     kind: "A `fanout`: opens a region of N branches declared HERE, closed by the one `join` naming it. Dispatches nothing.",
-    branches: "The region's branch entries: at least two distinct node ids (FD-V9), each a task or an ask, none of them its own join (FD-V9, FD-V12 \u2014 validateDefinition's)."
+    branches: "The region's branch entries: at least two distinct node ids (FD-V9), each a string (FD-V21), each a task or an ask, none of them its own join (FD-V9, FD-V12 \u2014 validateDefinition's)."
   },
   map: {
     kind: "A `map`: opens a region of ONE branch, opened once per item of an array at run time, closed by the one `join` naming it. Dispatches nothing.",
@@ -207,7 +214,7 @@ var KIND_DESCRIPTIONS = {
   },
   join: {
     kind: "A `join`: closes the region its `of` opened, by the join policy the driver is given. Dispatches nothing.",
-    of: "The id of the `fanout` or `map` whose region this closes (FD-V6, validateDefinition's).",
+    of: "The id of the `fanout` or `map` whose region this closes: a string (FD-V21); that it names an existing node (FD-V2) and that the node is one (FD-V6) are validateDefinition's.",
     edges: "Exactly one edge, carrying neither `when` nor `on` (FD-V7): a join has no outcome for either to read."
   },
   end: {
@@ -244,7 +251,7 @@ var TRANSFORM_DESCRIPTIONS = {
 };
 var PREDICATE_DESCRIPTIONS = {
   predicate: "A registered predicate's name (FD-V4, validateDefinition's).",
-  path: `A key path over the decision's context, starting at ${PREDICATE_ROOTS.map((r) => `"${r}"`).join(" or ")} and naming a key beyond it (FD-V43).`,
+  path: `A key path over the decision's context, starting at ${PREDICATE_ROOTS.map((r) => `"${r}"`).join(" or ")} and naming a key beyond it; a key past the root may be followed by array indexes [n], the root never (FD-V43).`,
   op: `One of ${PREDICATE_OPS.join(", ")} (FD-V44). The ordering operators compare numbers and "startsWith" a string \u2014 a comparison between kinds is no match, never a coercion.`,
   value: "The scalar compared against: null, a boolean, a number or a string (FD-V44).",
   default: "What is compared where the path does not resolve or resolves to null: a scalar, or \u2014 with `length` \u2014 an array or a string (FD-V44).",
@@ -284,7 +291,7 @@ function nodeKeySchema(kind, key) {
     case "pool":
       return { type: "string" };
     case "settings":
-      return kind === "gate" ? { type: "object", properties: { key: { type: "string", pattern: KEY_PATH_RE.source, description: "A key path: dot-separated object keys, each [A-Za-z0-9_-]{1,64} \u2014 no index, no wildcard, no expression (FD-V40)." } } } : { type: "object" };
+      return kind === "gate" ? { type: "object", properties: { key: { type: "string", pattern: KEY_PATH_RE.source, description: "A key path: dot-separated object keys, each [A-Za-z0-9_-]{1,64} and optionally followed by array indexes [n] (n is 0 or has no leading zero, at most 999999999; never leading the path) \u2014 files[0].series; no quoted key, no wildcard, no expression (FD-V40)." } } } : { type: "object" };
     case "transform":
       return ref("transform");
     case "optional":
@@ -295,14 +302,14 @@ function nodeKeySchema(kind, key) {
       return ref("retryPolicy");
     case "workerGroups":
       return { type: "array", minItems: 1, uniqueItems: true, items: { type: "string" } };
-    // **`branches`' entries and `of` admit a NON-string** — W210's conformity reader, B1: the validator holds both only
-    // through the graph (`FD-V2`, `FD-V6` and `FD-V9` read a string and pass anything else over), so `of: null` on a join
-    // of no region and `["b", "c", 5]` are ACCEPTED there, and refusing them here would refuse what the validator accepts
-    // (ADR 0132 rule 2). A string is held to the id charset. That `FD-V21` should refuse the rest is Q774.
+    // **`branches`' entries and `of` are ids, unconditionally** — v0.52, W215, Q774 resolved (P44 (d1)): `FD-V21` refuses
+    // a non-string `of` and a non-string branch entry, so the schema may too (ADR 0132 rule 2). Until then both admitted
+    // a non-string here, because the validator accepted one (W210's conformity reader, B1). A string outside the charset
+    // names no node — every node id is `FD-V16`'s — so `FD-V2` refuses it.
     case "branches":
-      return { type: "array", minItems: 2, uniqueItems: true, items: idOrNonString() };
+      return { type: "array", minItems: 2, uniqueItems: true, items: ref("id") };
     case "of":
-      return idOrNonString();
+      return ref("id");
     case "over":
     case "branch":
       return ref("id");
@@ -425,7 +432,7 @@ function referenceSchema(withSelf, id) {
   };
 }
 function leafSchema(id) {
-  const path = `^(?:${PREDICATE_ROOTS.join("|")})(?:\\.${id})+$`;
+  const path = `^(?:${PREDICATE_ROOTS.join("|")})(?:\\.${keyPathSegment(id)})+$`;
   const scalar = () => ({ type: ["null", "boolean", "number", "string"] });
   const keySchemas = {
     path: { type: "string", pattern: path },

package/dist/browser/scheduler/index.js

@@ -26,7 +26,7 @@ import {
   retryPolicyProblem,
   validateDefinition,
   workersOf
-} from "../chunks/chunk-5CVSWDCB.js";
+} from "../chunks/chunk-4JFQX7DL.js";
 
 // src/scheduler/bootstrap.ts
 import { WorkerManager } from "fyflow-scheduler";