fyflow-orchestration 0.12.0 → 0.14.0

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

@@ -402,7 +402,13 @@ function evalLeaf(scope, p, unknownOp) {
     else if (typeof v === "string") v = v.length;
     else return false;
   }
-  const w = p.value;
+  let w;
+  if (p.valueFrom !== void 0) {
+    w = readKeyPath(scope, p.valueFrom);
+    if (w === void 0 || typeof w === "object" && w !== null) return false;
+  } else {
+    w = p.value;
+  }
   switch (p.op) {
     // **Type-STRICT, and it is a departure measured rather than assumed.** Under JS comparison
     // `{confidence: "0.4"} < 0.5` is true and every `typeof`-guarded predicate in this tree is false;
@@ -755,8 +761,9 @@ function gateTypeCollisions(x) {
   return names.filter((n) => Object.prototype.hasOwnProperty.call(BUILT_IN_GATE_TYPES, n)).sort();
 }
 var PREDICATE_NAME_KEYS = ["predicate"];
-var PREDICATE_LEAF_KEYS = ["path", "op", "value", "default", "length"];
-var PREDICATE_LEAF_REQUIRED = ["path", "op", "value"];
+var PREDICATE_LEAF_KEYS = ["path", "op", "value", "valueFrom", "default", "length"];
+var PREDICATE_LEAF_REQUIRED = ["path", "op"];
+var RIGHT_SIDE_KEYS = ["value", "valueFrom"];
 var PREDICATE_GROUP_KEYS = ["all", "any"];
 function predicateShapeOf(o) {
   const marks = [];
@@ -783,29 +790,53 @@ var GATE_SCOPE = {
   foreignRoot: () => 'which an if gate cannot see \u2014 its one root is "input", the value that reached the gate; a gate has no outcome and no edge needs, and any other first segment would resolve to nothing in silence',
   rootAlone: () => "and names no key \u2014 a gate's path names a key INSIDE the value that reached it, as every gate's key path does; a value that must be compared whole is wrapped by the task before the gate"
 };
-function leafProblem(o, where, scope = EDGE_SCOPE) {
-  const extra = Object.keys(o).filter((k) => !PREDICATE_LEAF_KEYS.includes(k));
-  if (extra.length) {
-    return { rule: "FD-V42", message: `${where} carries ${extra.map((k) => JSON.stringify(k)).join(", ")}, which a comparison does not declare; it is { ${PREDICATE_LEAF_KEYS.join(", ")} }` };
-  }
-  for (const k of PREDICATE_LEAF_REQUIRED) {
-    if (!(k in o)) return { rule: "FD-V42", message: `${where} is missing required key "${k}"; a comparison is { ${PREDICATE_LEAF_KEYS.join(", ")} } with ${PREDICATE_LEAF_REQUIRED.join(", ")} required` };
-  }
-  const path = o.path;
+function comparisonPathProblem(o, key, where, scope) {
+  const path = o[key];
   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 ${KEY_PATH_WORDS}` };
+    return { rule: "FD-V43", message: `${where} ${key} ${JSON.stringify(path)} is not a key path \u2014 ${KEY_PATH_WORDS}` };
   }
-  const first = path.split(".")[0];
+  const segments = path.split(".");
+  const first = segments[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)}` };
+    return { rule: "FD-V43", message: `${where} ${key} ${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])` };
+    return { rule: "FD-V43", message: `${where} ${key} ${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)}` };
+  if (segments.length < 2) {
+    return { rule: "FD-V43", message: `${where} ${key} ${JSON.stringify(path)} is a root alone ${scope.rootAlone(root)}` };
+  }
+  if (root === "needs" && scope.needsDeclared !== void 0) {
+    const seg = segments[1];
+    const at = seg.indexOf("[");
+    const name = at === -1 ? seg : seg.slice(0, at);
+    if (!scope.needsDeclared.includes(name)) {
+      const declared = scope.needsDeclared.length === 0 ? "declares no `needs`, so its `ctx.needs` is {}" : `declares needs ${scope.needsDeclared.map((k2) => JSON.stringify(k2)).join(", ")}`;
+      return { rule: "FD-V43", message: `${where} ${key} ${JSON.stringify(path)} reads needs key ${JSON.stringify(name)}, and this edge ${declared} \u2014 the key would be absent for ever and the comparison no match for ever; declare it in the edge's needs` };
+    }
+  }
+  return null;
+}
+function leafProblem(o, where, scope = EDGE_SCOPE) {
+  const extra = Object.keys(o).filter((k) => !PREDICATE_LEAF_KEYS.includes(k));
+  if (extra.length) {
+    return { rule: "FD-V42", message: `${where} carries ${extra.map((k) => JSON.stringify(k)).join(", ")}, which a comparison does not declare; it is { ${PREDICATE_LEAF_KEYS.join(", ")} }` };
+  }
+  for (const k of PREDICATE_LEAF_REQUIRED) {
+    if (!(k in o)) return { rule: "FD-V42", message: `${where} is missing required key "${k}"; a comparison is { ${PREDICATE_LEAF_KEYS.join(", ")} } with ${PREDICATE_LEAF_REQUIRED.join(", ")} required and exactly one of ${RIGHT_SIDE_KEYS.map((k2) => JSON.stringify(k2)).join(" or ")}` };
+  }
+  const sides = RIGHT_SIDE_KEYS.filter((k) => k in o);
+  if (sides.length !== 1) {
+    return { rule: "FD-V42", message: `${where} carries ${sides.length === 0 ? "neither" : "both"} "value" and "valueFrom"; a comparison compares against exactly one \u2014 a literal "value", or "valueFrom", a key path over the same context` };
+  }
+  const pathProblem = comparisonPathProblem(o, "path", where, scope);
+  if (pathProblem !== null) return pathProblem;
+  const fromValue = "valueFrom" in o;
+  if (fromValue) {
+    const fromProblem = comparisonPathProblem(o, "valueFrom", where, scope);
+    if (fromProblem !== null) return fromProblem;
   }
   const op = o.op;
   if (typeof op !== "string" || !PREDICATE_OPS.includes(op)) {
@@ -815,6 +846,12 @@ function leafProblem(o, where, scope = EDGE_SCOPE) {
     return { rule: "FD-V44", message: `${where} length is ${JSON.stringify(o.length)}; it is exactly true or absent \u2014 there is no "compare the value, not its length" to ask for` };
   }
   const takesLength = o.length === true;
+  if (fromValue) {
+    if (takesLength && STRING_OPS.has(op)) {
+      return { rule: "FD-V44", message: `${where} takes a length and uses "${op}"; a length is a number and has no prefix` };
+    }
+    return defaultProblem(o, where, takesLength);
+  }
   if (!isScalar(o.value)) {
     return { rule: "FD-V44", message: `${where} value is ${scalarName(o.value)}; a comparison compares against a SCALAR \u2014 null, a boolean, a finite number or a string` };
   }
@@ -830,6 +867,9 @@ function leafProblem(o, where, scope = EDGE_SCOPE) {
   if (takesLength && STRING_OPS.has(op)) {
     return { rule: "FD-V44", message: `${where} takes a length and uses "${op}"; a length is a number and has no prefix` };
   }
+  return defaultProblem(o, where, takesLength);
+}
+function defaultProblem(o, where, takesLength) {
   if ("default" in o) {
     const d = o.default;
     const okDefault = Array.isArray(d) ? d.every(isScalar) : isScalar(d);
@@ -845,7 +885,8 @@ function leafProblem(o, where, scope = EDGE_SCOPE) {
   }
   return null;
 }
-function predicateProblem(v) {
+function predicateProblem(v, edgeNeeds) {
+  const scope = edgeNeeds === void 0 ? EDGE_SCOPE : { ...EDGE_SCOPE, needsDeclared: edgeNeeds };
   if (typeof v !== "object" || v === null || Array.isArray(v)) {
     return {
       rule: "FD-V42",
@@ -866,8 +907,8 @@ function predicateProblem(v) {
     if (typeof o.predicate !== "string") return { rule: "FD-V42", message: `when predicate is ${scalarName(o.predicate)}; it is the name of a registered predicate` };
     return null;
   }
-  if (shape === "leaf") return leafProblem(o, "when");
-  return groupProblem(o, "when", EDGE_SCOPE);
+  if (shape === "leaf") return leafProblem(o, "when", scope);
+  return groupProblem(o, "when", scope);
 }
 function groupProblem(o, label, scope) {
   const extra = Object.keys(o).filter((k) => !PREDICATE_GROUP_KEYS.includes(k));
@@ -1360,7 +1401,9 @@ function validateDefinition(doc, registry) {
         }
       }
       if (ed?.when !== void 0) {
-        const problem = predicateProblem(ed.when);
+        const nv = ed.needs;
+        const edgeNeeds = nv === void 0 ? [] : typeof nv === "object" && nv !== null && !Array.isArray(nv) && Object.keys(nv).length > 0 ? Object.keys(nv) : void 0;
+        const problem = predicateProblem(ed.when, edgeNeeds);
         if (problem) add(problem.rule, at, problem.message);
         else for (const name of predicateNamesIn(ed.when)) {
           if (!preds.has(name)) add("FD-V4", at, `when names "${name}", which is not a registered predicate`);
@@ -1641,11 +1684,38 @@ var GateTypeRefused = class extends RegistryError {
 var BUILT_IN_GROUP_TYPES = {
   ConcurrentLimitGroup: { configSchema: { type: "object", required: ["limit"], properties: { limit: { type: "integer", minimum: 1 } }, additionalProperties: false } },
   RateLimitGroup: { configSchema: { type: "object", required: ["windows"], properties: { windows: RATE_WINDOWS() }, additionalProperties: false } },
-  KeyedRateLimitGroup: { configSchema: { type: "object", required: ["windows"], properties: { windows: RATE_WINDOWS() }, additionalProperties: false } }
+  KeyedRateLimitGroup: { configSchema: { type: "object", required: ["windows"], properties: { windows: RATE_WINDOWS() }, additionalProperties: false } },
+  // v0.56: `units` a count (the units `0`…`n-1`) or a list of names — `type` may be a list in the subset (P46 fact 7), and
+  // `minimum` reads a number and `minItems` / `items` an array, so each keyword holds its own form. Distinct: beside it.
+  UnitGroup: { configSchema: { type: "object", required: ["units"], properties: { units: { type: ["integer", "array"], minimum: 1, minItems: 1, items: { type: "string", minLength: 1 } } }, additionalProperties: false } },
+  // v0.56: `limits` an object of per-key limits; each value a positive integer is beside it (no schema-valued
+  // `additionalProperties` in the subset).
+  KeyedConcurrentLimitGroup: { configSchema: { type: "object", required: ["limit"], properties: { limit: { type: "integer", minimum: 1 }, limits: { type: "object" } }, additionalProperties: false } }
 };
 function RATE_WINDOWS() {
   return { type: "array", minItems: 1, items: { type: "object", required: ["limit", "windowMs"], properties: { limit: { type: "integer", minimum: 1 }, windowMs: { type: "integer", minimum: 1 } }, additionalProperties: false } };
 }
+var isPositiveInteger = (v) => typeof v === "number" && Number.isInteger(v) && v >= 1;
+function builtInConfigProblem(type, config) {
+  if (type === "UnitGroup") {
+    const units = config.units;
+    if (Array.isArray(units)) {
+      const seen = /* @__PURE__ */ new Set();
+      for (const u of units) {
+        if (seen.has(u)) return `$.units lists unit ${JSON.stringify(u)} twice \u2014 a UnitGroup's units are distinct`;
+        seen.add(u);
+      }
+    }
+  } else if (type === "KeyedConcurrentLimitGroup") {
+    const limits = config.limits;
+    if (limits !== void 0) {
+      for (const [k, v] of Object.entries(limits)) {
+        if (!isPositiveInteger(v)) return `$.limits[${q(k)}] must be a positive integer \u2014 a per-key limit, as \`limit\` is \u2014 got ${shown(v)}`;
+      }
+    }
+  }
+  return null;
+}
 var DOCUMENT_KEYS = ["workers", "groups", "nodeTypes", "pools", "predicates", "languages"];
 var WORKER_KEYS = ["url", "configSchema", "settingsSchema", "inputSchema", "outputSchema"];
 var CHECKED_WORKER_SCHEMAS = ["configSchema", "settingsSchema"];
@@ -1685,9 +1755,12 @@ function mergePool(base, over) {
 }
 function copyResident(r) {
   if (Array.isArray(r)) return [...r];
-  if (isPlainObject2(r)) return { ...r };
+  if (isPlainObject2(r)) return Object.fromEntries(Object.entries(r).map(([k, v]) => [k, isPlainObject2(v) ? copyRequest(v) : v]));
   return r;
 }
+function copyRequest(v) {
+  return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, Array.isArray(x) ? [...x] : x]));
+}
 function nodeTypeFromDeclaration(decl, over) {
   const declaredPool = mergePool(decl.pool ?? {}, over);
   const def = {
@@ -1732,7 +1805,10 @@ function poolSpecProblem(v) {
       if (r.some((g) => typeof g !== "string" || g.length === 0)) return `PoolSpec.residentGroups must be an array of group keys or a { key: cost } record, got ${JSON.stringify(r)}`;
       if (new Set(r).size !== r.length) return "PoolSpec.residentGroups repeats a key";
     } else if (isPlainObject2(r)) {
-      for (const [k, c] of Object.entries(r)) if (!(typeof c === "number" && Number.isFinite(c) && c > 0)) return `PoolSpec.residentGroups[${q(k)}] must be a cost > 0, got ${JSON.stringify(c)}`;
+      for (const [k, c] of Object.entries(r)) {
+        const p = residentValueProblem(c);
+        if (p !== null) return `PoolSpec.residentGroups[${q(k)}] ${p}`;
+      }
     } else return `PoolSpec.residentGroups must be an array of group keys or a { key: cost } record, got ${JSON.stringify(r)}`;
   }
   if (v.cancelGraceMs !== void 0 && !(typeof v.cancelGraceMs === "number" && v.cancelGraceMs >= 0)) {
@@ -1753,6 +1829,27 @@ function poolSpecProblem(v) {
   }
   return null;
 }
+var RESIDENT_REQUEST_KEYS = ["cost", "from", "prefer"];
+function residentValueProblem(c) {
+  if (typeof c === "number") return isPositiveInteger(c) ? null : `must be a cost > 0, an INTEGER (the scheduler's rule), or a request { ${RESIDENT_REQUEST_KEYS.map((k) => `${k}?`).join(", ")} }, got ${shown(c)}`;
+  if (!isPlainObject2(c) || !isPlainPrototype(c)) {
+    return `must be a cost (a positive integer) or a request { ${RESIDENT_REQUEST_KEYS.map((k) => `${k}?`).join(", ")} } \u2014 a plain object \u2014 got ${describeNonPlain(c)}`;
+  }
+  for (const k of Object.keys(c)) if (!RESIDENT_REQUEST_KEYS.includes(k)) return `is a request carrying undeclared key ${q(k)}; it declares ${RESIDENT_REQUEST_KEYS.join(", ")}`;
+  if (ownKey(c, "cost") && !isPositiveInteger(c.cost)) return `.cost must be a positive integer, got ${shown(c.cost)}`;
+  for (const f of ["from", "prefer"]) {
+    if (!ownKey(c, f)) continue;
+    const list = c[f];
+    if (!Array.isArray(list) || list.length === 0) return `.${f} must be a non-empty list of unit ids, got ${shown(list)}`;
+    for (const u of list) {
+      if (!(typeof u === "string" && u.length > 0 || typeof u === "number" && Number.isInteger(u) && u >= 0)) {
+        return `.${f} holds ${shown(u)} \u2014 a unit id is a non-empty string, or an integer >= 0 for a UnitGroup declared by count`;
+      }
+    }
+    if (new Set(list).size !== list.length) return `.${f} repeats a unit id`;
+  }
+  return null;
+}
 function isPlainPrototype(o) {
   const proto = Object.getPrototypeOf(o);
   return proto === Object.prototype || proto === null;
@@ -1783,6 +1880,45 @@ function groupsNamedBy(spec) {
 function residentKeysOf(spec) {
   return spec.residentGroups === void 0 ? [] : Array.isArray(spec.residentGroups) ? [...spec.residentGroups] : Object.keys(spec.residentGroups);
 }
+function residentEntriesOf(spec) {
+  const r = spec.residentGroups;
+  return r === void 0 ? [] : Array.isArray(r) ? r.map((g) => [g, 1]) : Object.entries(r);
+}
+var KEYED_BUILT_INS = {
+  KeyedRateLimitGroup: 'the scheduler resolves no key for a resident group, so every worker holding it is counted in ONE "" bucket, in silence',
+  KeyedConcurrentLimitGroup: "the scheduler REJECTS a KeyedConcurrentLimitGroup in residentGroups when it is constructed: a worker holds its units across tasks, and so across keys, with no key to hold them under"
+};
+function residentAgainstGroupProblem(group, value) {
+  if (!hasOwn(BUILT_IN_GROUP_TYPES, group.type)) return null;
+  const request = isPlainObject2(value) ? value : void 0;
+  const cost = typeof value === "number" ? value : request?.cost ?? 1;
+  const named = `group ${q(group.key)}, of the built-in type ${q(group.type)}`;
+  if (group.type === "UnitGroup") {
+    const declared = group.config.units;
+    const units = typeof declared === "number" ? Array.from({ length: declared }, (_, i) => i) : [...declared];
+    const has = new Set(units);
+    for (const f of ["from", "prefer"]) {
+      for (const u of request?.[f] ?? []) {
+        if (!has.has(u)) {
+          return `${f} names unit ${shown(u)}, which ${named} does not have \u2014 its units are ${units.map((x) => shown(x)).join(", ")}` + (typeof declared === "number" ? " (declared by count: integers, never strings)" : "");
+        }
+      }
+    }
+    if (request?.from !== void 0 && cost > request.from.length) {
+      return `a cost of ${cost} from ${request.from.length} candidate unit(s) in from can never be granted by ${named}`;
+    }
+    if (cost > units.length) return `a cost of ${cost} is above the ${units.length} unit(s) of ${named} \u2014 a worker of this pool could never start`;
+    return null;
+  }
+  if (request !== void 0 && (ownKey(request, "from") || ownKey(request, "prefer"))) {
+    return `a request naming ${["from", "prefer"].filter((f) => ownKey(request, f)).join(" and ")} on ${named}, which takes no request \u2014 from and prefer are a UnitGroup's (or a code group type's with a checkRequest); { cost } alone is a cost, for any group`;
+  }
+  const limit = group.type === "ConcurrentLimitGroup" ? group.config.limit : group.type === "RateLimitGroup" ? Math.min(...group.config.windows.map((w) => w.limit)) : void 0;
+  if (limit !== void 0 && cost > limit) {
+    return `a cost of ${cost} is above the limit of ${limit} of ${named}${group.type === "RateLimitGroup" ? " (its smallest window's)" : ""} \u2014 a worker of this pool could never start`;
+  }
+  return null;
+}
 function poolOptionsOf(spec, inline, workerUrl, languages) {
   const { config, groups, ...rest } = spec;
   return {
@@ -1870,7 +2006,7 @@ function derivePool(key, typeName, def, worker, config, groupKeys, refuse, pool)
   }
   const resident = spec.residentGroups === void 0 ? 0 : Array.isArray(spec.residentGroups) ? spec.residentGroups.length : Object.keys(spec.residentGroups).length;
   if (resident > 0 && spec.idleTimeout === 0) {
-    throw new DerivationRefused(key, `${who}: residentGroups beside idleTimeout: 0 \u2014 a worker that never idles never releases a resident group, and a second pool contending for it waits for ever (measured on 0.5.2, P18 fact 6); give the pool a positive idleTimeout`);
+    throw new DerivationRefused(key, `${who}: residentGroups beside idleTimeout: 0 \u2014 a worker that never idles never releases a resident group, and a second pool contending for it waits for ever (measured at P18 fact 6 and re-measured at P46 fact 6); give the pool a positive idleTimeout`);
   }
   return { key, type: typeName, definition: def, worker, config, spec, ...pool !== void 0 ? { pool: copyPool(pool) } : {} };
 }
@@ -1981,6 +2117,10 @@ function resolveRegistry(doc, code = {}) {
       const fs = findings(gt.configSchema, inst.config ?? {});
       if (fs.length) throw new GroupConfigRefused(key, `group ${q(key)}: config fails ${q(inst.type)}'s configSchema \u2014 ${describeFindings(fs)}`);
     }
+    if (hasOwn(BUILT_IN_GROUP_TYPES, inst.type)) {
+      const p = builtInConfigProblem(inst.type, inst.config);
+      if (p !== null) throw new GroupConfigRefused(key, `group ${q(key)}: config fails ${q(inst.type)}'s rule beside its configSchema \u2014 ${p}`);
+    }
     groups.set(key, { key, type: inst.type, groupType: gt, config: inst.config });
   }
   const groupKeys = new Set(groups.keys());
@@ -2019,10 +2159,16 @@ function resolveRegistry(doc, code = {}) {
     pools.set(key, derivePool(key, inst.type, def, def.worker === void 0 ? void 0 : workers.get(def.worker), inst.config, groupKeys, ConfigRefused, inst.pool));
   }
   for (const p of pools.values()) {
-    for (const g of residentKeysOf(p.spec)) {
-      if (groups.get(g)?.type !== "KeyedRateLimitGroup") continue;
-      const who = p.key === p.type ? `node type ${q(p.type)}'s default instance` : `pool ${q(p.key)} (an instance of ${q(p.type)})`;
-      throw new DerivationRefused(p.key, `${who}: the derived pool holds group ${q(g)}, of the built-in type "KeyedRateLimitGroup", in residentGroups \u2014 the scheduler resolves no key for a resident group, so every worker holding it is counted in ONE "" bucket, in silence (Q619). Name ${q(g)} in groups, where each task is counted under its limitKey (FD-R6), or hold a ConcurrentLimitGroup or RateLimitGroup resident`);
+    const who = p.key === p.type ? `node type ${q(p.type)}'s default instance` : `pool ${q(p.key)} (an instance of ${q(p.type)})`;
+    for (const [g, value] of residentEntriesOf(p.spec)) {
+      const group = groups.get(g);
+      if (group === void 0) continue;
+      const keyed = KEYED_BUILT_INS[group.type];
+      if (hasOwn(KEYED_BUILT_INS, group.type) && keyed !== void 0) {
+        throw new DerivationRefused(p.key, `${who}: the derived pool holds group ${q(g)}, of the built-in type ${q(group.type)}, in residentGroups \u2014 ${keyed} (Q619). Name ${q(g)} in groups, where each task is counted under its limitKey (FD-R6), or hold a ConcurrentLimitGroup or RateLimitGroup resident (or a UnitGroup)`);
+      }
+      const problem = residentAgainstGroupProblem(group, value);
+      if (problem !== null) throw new DerivationRefused(p.key, `${who}: residentGroups[${q(g)}] \u2014 ${problem}`);
     }
   }
   const predicateNames = doc.predicates ?? [];
@@ -7028,6 +7174,7 @@ export {
   canonical,
   findings,
   describeFindings,
+  keyPathSteps,
   readKeyPath,
   ID_RE_COPY,
   KINDS_COPY,

package/dist/browser/index.js

@@ -111,6 +111,7 @@ import {
   isTerminal,
   isTerminalEvent,
   keyPathProblem,
+  keyPathSteps,
   languagesOf,
   lastRecordFor,
   liveToken,
@@ -151,7 +152,7 @@ import {
   visibilityKey,
   witness,
   workersOf
-} from "./chunks/chunk-4JFQX7DL.js";
+} from "./chunks/chunk-5KUYTCXI.js";
 
 // src/definition/definition-schema.ts
 var DRAFT_2020_12 = "https://json-schema.org/draft/2020-12/schema";
@@ -237,7 +238,7 @@ var KIND_DESCRIPTIONS = {
 var EDGE_DESCRIPTIONS = {
   to: "The id of the node this edge leads to (FD-V2, validateDefinition's).",
   on: 'The terminal states this edge is eligible for: a non-empty list of distinct "done" / "failed" (FD-V18). Absent: ["done"]. "user_action" suspends rather than routes.',
-  when: "The decision: a registered predicate NAME { predicate }, a declared COMPARISON { path, op, value, default?, length? }, or a flat GROUP { all } or { any } of comparisons (FD-V42-FD-V45). Absent: the edge is the default for its state.",
+  when: "The decision: a registered predicate NAME { predicate }, a declared COMPARISON { path, op, value or valueFrom, default?, length? }, or a flat GROUP { all } or { any } of comparisons (FD-V42-FD-V45). Absent: the edge is the default for its state.",
   needs: "What this edge's predicate sees beyond its node's outcome \u2014 `needs`' grammar minus \".\" (FD-V26).",
   route: "On a gate's edge, which of the gate type's routes it carries; absent: the type's DEFAULT route (FD-V41). Refused on every other kind's edge."
 };
@@ -251,9 +252,10 @@ 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; a key past the root may be followed by array indexes [n], the root never (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; a "needs" key the edge declares (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).",
+  value: "The scalar compared against: null, a boolean, a number or a string (FD-V44). Exactly one of value and valueFrom (FD-V42).",
+  valueFrom: `A key path over the same context, compared against as a literal would be \u2014 the same roots as path, ${PREDICATE_ROOTS.map((r) => `"${r}"`).join(" or ")}, and a "needs" key the edge declares (FD-V43). Exactly one of value and valueFrom (FD-V42). Where it does not resolve, or resolves to an object or an array, the comparison is no match for every operator.`,
   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).",
   length: "Exactly true: compare the LENGTH of the array or string, against a number (FD-V44).",
   all: "A flat group: a non-empty list of comparisons that must all hold (FD-V45).",
@@ -438,6 +440,9 @@ function leafSchema(id) {
     path: { type: "string", pattern: path },
     op: { enum: [...PREDICATE_OPS] },
     value: scalar(),
+    // v0.55 (ADR 0140): the RIGHT side as a key path — `path`'s own pattern, so the two keys cannot be held to different
+    // grammars; (g1)'s *a `needs` key the edge declares* needs the edge's own `needs` and is the validator's alone.
+    valueFrom: { type: "string", pattern: path },
     default: { anyOf: [scalar(), { type: "array", items: scalar() }] },
     length: { const: true }
   };
@@ -445,6 +450,8 @@ function leafSchema(id) {
     description: "A declared comparison over the decision's context.",
     type: "object",
     required: [...PREDICATE_LEAF_REQUIRED],
+    // **Exactly one of `value` / `valueFrom`** (`FD-V42`, v0.55): both satisfy both branches and neither satisfies none.
+    oneOf: [{ required: ["value"] }, { required: ["valueFrom"] }],
     properties: Object.fromEntries(PREDICATE_LEAF_KEYS.map((k) => {
       const s = keySchemas[k];
       if (s === void 0) throw new Error(`definitionSchema: a comparison declares the key "${k}" and no schema is written for it`);
@@ -942,6 +949,7 @@ export {
   isTerminal,
   isTerminalEvent,
   keyPathProblem,
+  keyPathSteps,
   languagesOf,
   lastRecordFor,
   liveToken,

package/dist/browser/scheduler/index.js

@@ -26,7 +26,7 @@ import {
   retryPolicyProblem,
   validateDefinition,
   workersOf
-} from "../chunks/chunk-4JFQX7DL.js";
+} from "../chunks/chunk-5KUYTCXI.js";
 
 // src/scheduler/bootstrap.ts
 import { WorkerManager } from "fyflow-scheduler";
@@ -83,7 +83,7 @@ function bootstrap(registry, groups = {}, options = {}) {
 }
 
 // src/scheduler/runtime.ts
-import { ConcurrentLimitGroup, FyflowScheduler, KeyedRateLimitGroup, RateLimitGroup } from "fyflow-scheduler";
+import { ConcurrentLimitGroup, FyflowScheduler, KeyedConcurrentLimitGroup, KeyedRateLimitGroup, RateLimitGroup, UnitGroup } from "fyflow-scheduler";
 var RuntimeError = class extends Error {
   /** The entry this refusal is about — a worker's key, a group's key, a type's name. `RegistryError`'s field, one layer out. */
   at;
@@ -107,8 +107,18 @@ var KEYED_RULE = "FD-R6";
 var BUILT_IN_GROUP_FACTORIES = {
   ConcurrentLimitGroup: (config, key) => new ConcurrentLimitGroup(config.limit, key),
   RateLimitGroup: (config, key) => new RateLimitGroup(config.windows, key),
-  KeyedRateLimitGroup: (config, key) => new KeyedRateLimitGroup(config.windows, { id: key })
+  KeyedRateLimitGroup: (config, key) => new KeyedRateLimitGroup(config.windows, { id: key }),
+  UnitGroup: (config, key) => {
+    const units = config.units;
+    return new UnitGroup(typeof units === "number" ? units : [...units], { id: key });
+  },
+  KeyedConcurrentLimitGroup: (config, key) => {
+    const { limit, limits } = config;
+    const own = new Map(Object.entries(limits ?? {}));
+    return new KeyedConcurrentLimitGroup(limit, { id: key, limitFor: (k) => own.get(k) ?? limit });
+  }
 };
+var KEYED_BUILT_IN_GROUP_TYPES = ["KeyedRateLimitGroup", "KeyedConcurrentLimitGroup"];
 var GROUP_MEMBERS = [
   { name: "canRun", kind: "function", why: "the scheduler calls it before every admission; a group without it throws on the first task" },
   { name: "onStart", kind: "function", why: "the scheduler calls it unguarded at admission, though the interface marks it optional; a group without it throws on the first task (measured on 0.5.2)" },
@@ -210,8 +220,8 @@ function createRuntime(document, code = {}, options = {}) {
     pools: poolsOf(registry.pools),
     ...registry.gateTypes !== void 0 ? { gateTypes: registry.gateTypes } : {}
   };
-  const keyedByBuiltIn = /* @__PURE__ */ new Set();
-  for (const [key, g] of resolved.groups) if (g.type === "KeyedRateLimitGroup") keyedByBuiltIn.add(key);
+  const keyedByBuiltIn = /* @__PURE__ */ new Map();
+  for (const [key, g] of resolved.groups) if (KEYED_BUILT_IN_GROUP_TYPES.includes(g.type)) keyedByBuiltIn.set(key, g.type);
   const keyedFindings = (flow) => {
     const nodes = flow?.nodes;
     if (keyedByBuiltIn.size === 0 || typeof nodes?.[Symbol.iterator] !== "function") return [];
@@ -226,10 +236,11 @@ function createRuntime(document, code = {}, options = {}) {
       const reached = [.../* @__PURE__ */ new Set([...fromPool, ...fromNode])].filter((g) => keyedByBuiltIn.has(g)).sort();
       if (reached.length === 0) continue;
       const at = typeof n.id === "string" ? n.id : null;
+      const types = [...new Set(reached.map((g) => keyedByBuiltIn.get(g)))].sort().join(" and ");
       out.push({
         rule: KEYED_RULE,
         at,
-        detail: `node ${at === null ? "<unnamed>" : q(at)} reaches keyed group${reached.length > 1 ? "s" : ""} ${reached.map(q).join(", ")}, built by the built-in KeyedRateLimitGroup factory with no keyFrom \u2014 so every task of it needs a limitKey, which nothing sets unless start is given a createTask, and without one the scheduler's addTask throws "Missing limit key". Two roads work: pass start a createTask that sets limitKey on the task it builds, or declare the group with a code group type (code.groupTypes) whose create() builds a KeyedRateLimitGroup with a keyFrom that derives the key. A key derived from the flow itself is Q248, deferred`
+        detail: `node ${at === null ? "<unnamed>" : q(at)} reaches keyed group${reached.length > 1 ? "s" : ""} ${reached.map(q).join(", ")}, built by the built-in ${types} factory with no keyFrom \u2014 so every task of it needs a limitKey, which nothing sets unless start is given a createTask, and without one the scheduler's addTask throws "Missing limit key". Two roads work: pass start a createTask that sets limitKey on the task it builds, or declare the group with a code group type (code.groupTypes) whose create() builds a ${types} with a keyFrom that derives the key. A key derived from the flow itself is Q248, deferred`
       });
     }
     return out;