fyflow-orchestration 0.12.0 → 0.14.0

package/dist/types/src/definition/types.d.ts

@@ -86,10 +86,12 @@ export type PredicateOp = typeof PREDICATE_OPS[number];
 /** The two roots a predicate's key path may start at — the two members of `DecisionContext`, and no other. */
 export declare const PREDICATE_ROOTS: readonly ["outcome", "needs"];
 /**
- * **What a declared comparison may compare AGAINST** — a scalar, and nothing else (`FD-V44`).
+ * **What a declared comparison's LITERAL may be** — a scalar, and nothing else (`FD-V44`).
  * Every one of the ten predicate bodies in this tree compares to one (`0.5`, `50`, `true`,
  * `'r1:publish:'`, `0`), and admitting an object would need a deep-equality semantics with no
- * instance and no obvious right answer for `NaN`, key order or a prototype.
+ * instance and no obvious right answer for `NaN`, key order or a prototype. *Since v0.55 a comparison
+ * may compare against ANOTHER key path instead — `valueFrom` (ADR 0140) — and a resolved object or
+ * array there is no match, for the same reason.*
  */
 export type PredicateScalar = null | boolean | number | string;
 /** A registered predicate NAME, resolved against the registry at instantiation (`FD-V4`). */
@@ -97,21 +99,20 @@ export interface PredicateName {
     predicate: string;
 }
 /**
- * **One comparison over the decision's own context** — `FD-V43` owns the path and `FD-V44` the
- * operator and the value.
+ * **What every comparison carries, whichever right side it names** — `FD-V43` owns the path and `FD-V44` the
+ * operator and the modifiers.
  */
-export interface PredicateLeaf {
+export interface PredicateLeafBase {
     /**
      * A KEY PATH over the `DecisionContext` itself, read by `readKeyPath` — the same resolution a
      * gate's `settings.key` gets, measured unchanged at this scope. **Its first segment is `outcome`
      * or `needs` and nothing else** (`FD-V43`), because a first segment that is neither resolves to
      * `undefined` in silence and a typo would be a wrong key rather than a refusal. A key past the root may
      * carry array indexes — `outcome.result.items[0].score` — and the root never does (v0.53, ADR 0137).
+     * **A `needs` path names a key that edge's `needs` DECLARES** (v0.55, P45 (g1)): any other is absent for ever.
      */
     path: string;
     op: PredicateOp;
-    /** The literal compared against. Required — there is no operator here that takes one operand. */
-    value: PredicateScalar;
     /**
      * **What is compared when the path does not resolve, or resolves to `null`.** Absent is NO MATCH
      * by default; where this is declared it is substituted instead — which is `?? 0` and `?? []`
@@ -136,6 +137,29 @@ export interface PredicateLeaf {
      */
     length?: true;
 }
+/**
+ * **One comparison over the decision's own context — against a LITERAL, or against ANOTHER KEY PATH** (v0.55,
+ * [ADR 0140](../../doc/decisions/0140-a-comparison-may-compare-against-another-key-path-and-an-absent-one-is-no-match.md),
+ * P45 (a1)). Exactly one of `value` / `valueFrom` (`FD-V42`), so a TWO-member union rather than one interface with
+ * both optional — `PredicateGroup`'s precedent: `{ path, op }` with neither, and both at once, fail at L0. **The type
+ * change, stated** (P45 decision 8): until 0.13.0 `value` was required, so code READING `leaf.value` now sees
+ * `PredicateScalar | undefined` and tells the two apart by `'valueFrom' in leaf`.
+ */
+export type PredicateLeaf = (PredicateLeafBase & {
+    /** The literal compared against. */
+    value: PredicateScalar;
+    valueFrom?: never;
+}) | (PredicateLeafBase & {
+    /**
+     * **A key path over the SAME context, compared against as a literal would be** — the same roots as `path` (and
+     * the same `needs` rule), held to `FD-V43`; resolved by `readKeyPath` when the comparison is asked. Type-strict, a
+     * resolved `null` compared as `null`; **a resolved object or array is NO MATCH for every operator, `ne` included**;
+     * and **an ABSENT one is NO MATCH** — the left side's `default` does not stand in for it, so `x gt y` and `x lte y`
+     * are both false where `y` is absent. `default` and `length` are the LEFT side's only.
+     */
+    valueFrom: string;
+    value?: never;
+});
 /**
  * **A FLAT group — `all` or `any`, and its members are LEAVES.** Nesting is refused by name
  * (`FD-V45`), and so is a `{ predicate }` member: a group holding a registered name could be
@@ -304,6 +328,20 @@ export interface WorkerEntry {
     /** What the worker's `run()` returns. Declared and carried; not enforced (P19). */
     outputSchema?: JsonSchema;
 }
+/**
+ * **A resident group's REQUEST: which units a worker of the pool may hold** — `spec/flow-definition.md` v0.56, P46
+ * decision 4, [ADR 0143](../../doc/decisions/0143-unit-and-keyed-concurrent-groups-are-built-ins-and-a-resident-request-is-checked-against-the-group.md).
+ * The scheduler's own `ResidentGroupRequest`, written out rather than imported, as `PoolSpec`'s other fields are: `cost`
+ * a positive integer (absent: 1); `from` the candidate units, granted from these only; `prefer` a hint that never blocks.
+ * Each a non-empty list of distinct ids — a string, or an integer for a `UnitGroup` declared by count. `{ cost }` alone is
+ * a cost written as an object, for any group; `from` / `prefer` are for a group that takes a request (a `UnitGroup`, or a
+ * code group type with a `checkRequest`), and the registry holds them against a built-in group's declared units.
+ */
+export interface ResidentGroupRequest {
+    cost?: number;
+    from?: readonly (string | number)[];
+    prefer?: readonly (string | number)[];
+}
 /**
  * **What a derivation RETURNS: what ONE `WorkerManager` needs, minus the two things the TYPE states
  * beside it** (`worker`, `inline`) — decision 2. `config` is the worker's constructor argument and
@@ -317,8 +355,11 @@ export interface PoolSpec {
     idleTimeout?: number;
     /** Group KEYS every task of the pool acquires; the scheduler unions them with a node's `workerGroups`. */
     groups?: readonly string[];
-    /** Group keys held for the WORKER's lifetime rather than per task, at a cost each — never beside `idleTimeout: 0` (decision 9). */
-    residentGroups?: readonly string[] | Readonly<Record<string, number>>;
+    /**
+     * Group keys held for the WORKER's lifetime rather than per task — a list (a cost of 1 each), or a record of a cost (a
+     * positive integer) or a {@link ResidentGroupRequest} per key (v0.56) — never beside `idleTimeout: 0` (decision 9).
+     */
+    residentGroups?: readonly string[] | Readonly<Record<string, number | ResidentGroupRequest>>;
     /**
      * **Threaded pools: the ms a cancelled task's worker gets to stop by itself before it is forced** — the
      * scheduler's own option, declarable since `spec/flow-definition.md` v0.33 (P33 decision 6, W159). Zero or
@@ -406,13 +447,16 @@ export interface PoolInstance {
 }
 /** A resource group the runtime constructs — an instance of a group TYPE, by name, with the config its factory's schema admits. */
 export interface GroupInstance {
-    /** One of the three built-ins (`ConcurrentLimitGroup`, `RateLimitGroup`, `KeyedRateLimitGroup`) or a group type registered in `code`. */
+    /**
+     * One of the five built-ins (`ConcurrentLimitGroup`, `RateLimitGroup`, `KeyedRateLimitGroup`, and since v0.56
+     * `UnitGroup` and `KeyedConcurrentLimitGroup`) or a group type registered in `code`.
+     */
     type: string;
     config?: unknown;
 }
 /**
- * **A resource group is a FACTORY** — decision 4 and P18 fact 2: the scheduler's three group classes
- * have three different constructors, so each is a `create(config, key)` behind one shape, and a
+ * **A resource group is a FACTORY** — decision 4 and P18 fact 2: the scheduler's group classes (five
+ * built in since v0.56) have different constructors, so each is a `create(config, key)` behind one shape, and a
  * consumer registers a custom class the same way. `create` returns the scheduler's own `ResourceGroup`
  * interface. **The runtime holds what it returns to SIX members** — `canRun`, `onStart` and
  * `onFinish` because the scheduler calls them, `getMetrics`, `id` and `type` because the interface

package/dist/types/src/definition/validate.d.ts

@@ -18,7 +18,8 @@
  * ADR 0002 rule 3: this runs in full, at instantiation, before any task is queued.
  */
 import type { Finding, FlowDefinition, GateType, GateTypes, JsonSchema, StaticGateType, LanguageAdapter, Languages, NodeTypeEntry, NodeTypes, Pools, Registry, WorkerEntry, Workers } from './types.js';
-export { readKeyPath } from './condition.js';
+export { keyPathSteps, readKeyPath } from './condition.js';
+export type { KeyPathStep } from './condition.js';
 declare const KINDS: readonly ["task", "fanout", "map", "join", "end", "gate", "ask"];
 /**
  * **`FD-V16`'s charset — a flow's and a node's id** ([spec/task-id.md](../../spec/task-id.md)'s) — v0.50 (W210,
@@ -269,7 +270,7 @@ export declare const PREDICATE_GROUP_KEYS: readonly string[];
  * has owned *an edge's `when` names a predicate absent from the registry* since P1 and whose only
  * change at v0.27 is where the name is written.
  */
-export declare function predicateProblem(v: unknown): {
+export declare function predicateProblem(v: unknown, edgeNeeds?: readonly string[]): {
     rule: string;
     message: string;
 } | null;

package/dist/types/src/scheduler/runtime.d.ts

@@ -13,7 +13,7 @@
  *
  * **What it does, in one sentence: `resolveRegistry` says what the document MEANS, and this module
  * builds it.** The resolver checks every name, every schema and every derivation and constructs
- * nothing (W65); here the three built-in group types get their factories, every group is created and
+ * nothing (W65); here the built-in group types (five since v0.56) get their factories, every group is created and
  * held to what the scheduler actually calls, every worker URL is resolved against the consumer's
  * `base`, `bootstrap` turns every derived instance into a pool, and the driver's registry is derived
  * once and exposed as `runtime.registry` (decision 14).
@@ -27,7 +27,7 @@
  * | omitted | the `.d.ts` says | what the task does |
  * |---|---|---|
  * | `onStart` | optional | THROWS `group.onStart is not a function` |
- * | `onFinish` | optional | **never finishes** — `running` for ever, the scheduler reporting idle |
+ * | `onFinish` | optional | **never finishes** — `running` for ever, and `stats` counts it `running` |
  * | `getMetrics` | required | runs to `done` |
  * | `canRun` | required | THROWS |
  * | `type` | required | runs to `done` |
@@ -96,9 +96,9 @@ export declare class RunIdInUse extends RuntimeError {
 }
 /**
  * **A `start` or a `resume` given no `createTask`, of a flow a node of which reaches a group the BUILT-IN
- * `KeyedRateLimitGroup` factory built** — `FD-R6`,
+ * `KeyedRateLimitGroup` factory built — or, since v0.56, the built-in `KeyedConcurrentLimitGroup` factory** — `FD-R6`,
  * [ADR 0097](../../doc/decisions/0097-what-start-refuses-that-the-flow-does-not-decide.md), P37 fact 1 and
- * stop-and-ask (c). That factory gives the group no `keyFrom`, so its key is the task's `limitKey`, which nothing here
+ * stop-and-ask (c). Each such factory gives the group no `keyFrom`, so its key is the task's `limitKey`, which nothing here
  * sets — and the scheduler THROWS in `addTask` for a keyed group with no key. `at` is the first such node in the flow's
  * order; the message carries every `FD-R6` finding `check` returned. Thrown before a run id is minted or a driver built,
  * so the refused call costs nothing.
@@ -106,8 +106,12 @@ export declare class RunIdInUse extends RuntimeError {
 export declare class LimitKeyMissing extends RuntimeError {
 }
 /**
- * **The three built-in group types' FACTORIES, and they are three different constructors** (P18
- * fact 2, re-run at W66): `(limit, id)`, `(windows, id)` and `(windows, { id })`, the third keyed.
+ * **The built-in group types' FACTORIES, and they are different constructors** (P18
+ * fact 2, re-run at W66): `(limit, id)`, `(windows, id)` and `(windows, { id })`, the third keyed — and since v0.56 (P46
+ * decisions 3 and 5, ADR 0143 rules 1 and 2) `UnitGroup(units, { id })` and `KeyedConcurrentLimitGroup(limit, { id,
+ * limitFor })`, the fifth keyed. **Neither keyed factory gives a `keyFrom`**, so each keys a task by its `limitKey` (`FD-R6`).
+ * `limitFor` reads a COPY of the document's `limits`, taken here, by OWN key — a later edit to the document moves no limit,
+ * and a key called `constructor` is not answered by `Object.prototype`. No `requestFrom`: a task's request is its `units`.
  * `BUILT_IN_GROUP_TYPES` in `src/definition/registry.ts` carries their schemas and no factory,
  * deliberately — the pure entry constructs nothing (`RT-R13`) — so the two halves meet here and are
  * compared both ways by a test.
@@ -121,10 +125,10 @@ export declare const BUILT_IN_GROUP_FACTORIES: Readonly<Record<string, (config:
  * **What a created group must carry.** The first three are what the scheduler CALLS on the acquire
  * path, the last three what the interface requires and a viewer reads — the union, by the
  * maintainer's decision at W66's declaration step. `EventTarget` is deliberately not required.
- * **The `why` strings say "measured on 0.5.2" and stay dated**: W157 re-read the current pin's source
+ * **The `why` strings say "measured on 0.5.2" and stay dated**: W224 re-read the current pin's source
  * rather than re-running the table above — `onStart`/`onFinish` are still optional in
- * `ResourceGroup` (`groups/resourceGroup.ts:114`, `:117`) and still called unguarded
- * (`core/FyflowScheduler.ts:894`, `:976`), so S10 stands unchanged.
+ * `ResourceGroup` (`groups/resourceGroup.ts:140`, `:147`) and still called unguarded
+ * (`core/FyflowScheduler.ts:1332`, `:1456`), so S10 stands unchanged.
  */
 export declare const GROUP_MEMBERS: readonly {
     readonly name: string;
@@ -395,7 +399,7 @@ export interface Runtime {
      * rule 4, P37 stop-and-ask (b). `[]` means `start` will not refuse the flow; a non-empty result is what `start`
      * throws, built from this same call (rule 5): the `FD-V` findings as `InvalidDefinition`, and — since
      * [ADR 0097](../../doc/decisions/0097-what-start-refuses-that-the-flow-does-not-decide.md) — the `FD-R6` findings, a
-     * node reaching a group the built-in `KeyedRateLimitGroup` factory built, as `LimitKeyMissing` when `start` is given
+     * node reaching a group the built-in `KeyedRateLimitGroup` or (since v0.56) `KeyedConcurrentLimitGroup` factory built, as `LimitKeyMissing` when `start` is given
      * no `createTask`. **`check` reads as `start` given none** (P37 stop-and-ask (c)), so a caller who will pass a
      * `createTask` setting `limitKey` filters `FD-R6` out by its rule id. **It never throws for a flow's defect**: every
      * finding is returned, as `validateDefinition` returns them, against this runtime's own registry. **Not included,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fyflow-orchestration",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Flow orchestration over fyflow-scheduler: sequence, decision, fan-out and join",
   "keywords": [
     "workflow",
@@ -127,12 +127,12 @@
     "@cfworker/json-schema": "4.1.1",
     "@types/node": "^24.13.3",
     "esbuild": "^0.25.12",
-    "fyflow-scheduler": "0.6.0",
+    "fyflow-scheduler": "0.7.0",
     "playwright": "^1.62.1",
     "typescript": "^5.9.2"
   },
   "peerDependencies": {
-    "fyflow-scheduler": "0.6.0"
+    "fyflow-scheduler": "0.7.0"
   },
   "dependencies": {
     "jsonata": "2.2.2"