fyflow-orchestration 0.13.0 → 0.14.0

package/AGENTS.md

@@ -2687,7 +2687,7 @@ flow, and the class says which document to open.
 member and the group's key; `GroupNotBuildable` — a group type with no `create`; since W89, `RunIdInUse`
 — a `start` or `resume` naming a run id that runtime has already built a driver for, a finished run's included (`RN-R25`, ADR 0091);
 and, since W163, **`LimitKeyMissing`** — a `start` or `resume` given no `createTask`, of a flow a node of which reaches a
-group the built-in `KeyedRateLimitGroup` factory built (`FD-R6`, [ADR 0097](doc/decisions/0097-what-start-refuses-that-the-flow-does-not-decide.md), section 12), its `at` the node.
+group a built-in keyed factory built — `KeyedRateLimitGroup`, or since spec v0.56 `KeyedConcurrentLimitGroup` (`FD-R6`, [ADR 0097](doc/decisions/0097-what-start-refuses-that-the-flow-does-not-decide.md), section 12), its `at` the node.
 *(`LanguageNotBuilt` — a flow transforming on a type no pool was built for — was another until W162 removed it
 with `createRuntime`'s `flows`: every typed pool carries every registered language since
 [ADR 0096](doc/decisions/0096-a-runtime-is-its-registry-and-start-refuses-from-runtime-check.md), section 12.)* A bare
@@ -3237,7 +3237,7 @@ if (!haltedRun.haltedBy?.startsWith('UncloneableResult')) throw new Error(`halte
 |---|---|
 | flow-level **retry** — re-dispatching a NODE under a new attempt, possibly routing elsewhere | **task-level retry IS built** since [W58](doc/work-items/w58-what-a-node-says-about-its-own-task.md): declare `retryPolicy` on the node (section 3) and the scheduler retries inside the same task id, reported on the record's `attempts`. Re-dispatching the node is [Q16](doc/questions/q16.md)'s other half and the task id's fourth segment, and nothing mints one |
 | **`runtime.register()`** — adding node types, pools, groups or languages to a RUNNING runtime | **declined** — [P37](doc/plans/p37-a-runtime-is-its-registry.md) decision 1, [ADR 0096](doc/decisions/0096-a-runtime-is-its-registry-and-start-refuses-from-runtime-check.md): `fyflow-scheduler` cannot add a pool after construction. A changed registry is a NEW runtime; a run on the old one finishes there or moves by stop-and-resume ([P34](doc/plans/p34-what-cancelling-stopping-and-pausing-a-run-do.md)). **A FLOW is not a registry entry**: `runtime.check(flow)`, then `runtime.start(flow, …)`, takes any flow the registry can run, at any time (section 12) |
-| **a `limitKey` from the FLOW** — a node or a document saying which key a task of a keyed group is counted under | **deferred** — [Q248](doc/questions/q248.md). Pass `start` a `createTask` that sets `limitKey` on the task it builds, or register a group type whose `create` builds a `KeyedRateLimitGroup` with a `keyFrom` (section 12). A node reaching a document's built-in keyed group with neither is refused before its run starts — `FD-R6`, `LimitKeyMissing` |
+| **a `limitKey` from the FLOW** — a node or a document saying which key a task of a keyed group is counted under | **deferred** — [Q248](doc/questions/q248.md). Pass `start` a `createTask` that sets `limitKey` on the task it builds, or register a group type whose `create` builds a `KeyedRateLimitGroup` or a `KeyedConcurrentLimitGroup` with a `keyFrom` (section 12). A node reaching a document's built-in keyed group with neither is refused before its run starts — `FD-R6`, `LimitKeyMissing` |
 | **a `start()` that checks a TRANSFORMING task's payload** — the transform run first and its result held to the `inputSchema` | **no** — [ADR 0101](doc/decisions/0101-a-transforming-task-is-not-held-at-start.md): `start()` is synchronous and the transform runs only in the worker, so a task declaring one is UNCHECKED at `start` (`FD-R4`), as a worker declaring no `inputSchema` is. Call `givenVerdict(registry, flow, task, received)` — `tryTransform(…, { input: received })` on the declared transform — first, on each transforming target with the value it RECEIVES (section 15), then start |
 | **redaction by `writeOnly`** — a schema annotation keeping a value out of what a run retains or reports | **no** — [ADR 0098](doc/decisions/0098-four-annotations-join-the-schema-subset-and-constrain-nothing.md) rule 4: `writeOnly`, like `readOnly`, `title` and `description`, is admitted as an annotation since v0.36, held to its shape and read by nothing after. Redact in your own code, before the value reaches a run (section 13) |
 | **pool options on a CLASS type's instance**, and the scheduler's `idleCheckIntervalMs`, `requeueFailedTasks` and `maxWorkerRestarts` anywhere | **no** — [ADR 0099](doc/decisions/0099-a-named-instance-of-a-document-type-may-declare-its-own-pool-options.md) rules 4 and 7: a named instance of a DOCUMENT type may declare `pool` (section 13); a class computes its pool from the instance's `config` and key, so give it a `configSchema` knob. The three are refused as undeclared keys |
@@ -3344,7 +3344,7 @@ if (Object.keys(runtime.groups).join() !== 'gate') throw new Error(`groups: ${Ob
 
 **A custom group type is a FACTORY, and the runtime holds its output to what the scheduler CALLS.**
 The document names a group by KEY with a `type`; the code supplies `{ configSchema?, create(config,
-key) }` under that type name; the three built-ins are pre-registered in the same shape. What comes
+key) }` under that type name; the five built-ins are pre-registered in the same shape (section 13). What comes
 back is checked for ADR 0055's six members and refused by name otherwise. Read the counts off the
 object the runtime built — [W70](doc/work-items/w70-a-flow-that-decides-and-a-custom-group-on-the-runtime.md):
 
@@ -3376,8 +3376,9 @@ class CountingGroup extends EventTarget implements ResourceGroup {
 }
 
 // THE REGISTRY declares the group by KEY, with its TYPE by name and its config; the CODE supplies the
-// factory for that type name — `{ configSchema?, create(config, key) }`. The three built-ins,
-// `ConcurrentLimitGroup`, `RateLimitGroup` and `KeyedRateLimitGroup`, are pre-registered in the same
+// factory for that type name — `{ configSchema?, create(config, key) }`. The five built-ins,
+// `ConcurrentLimitGroup`, `RateLimitGroup`, `KeyedRateLimitGroup`, `UnitGroup` and
+// `KeyedConcurrentLimitGroup` (section 13), are pre-registered in the same
 // shape, so `"type": "ConcurrentLimitGroup"` needs no code at all. A node type names the groups its
 // pool's tasks acquire.
 const registry: RegistryDocument = {
@@ -3444,14 +3445,14 @@ so a flow published after the runtime started runs on it, transforming on any ty
 rules — every one but `FD-R6`, below — before any run id is spent, so the two cannot disagree: *register* a flow by checking it, then
 start it. `check` leaves out what depends on a RUN rather than the flow — a payload `FD-R4` refuses,
 and a run id in use. **One finding it returns is not a definition defect: `FD-R6`**
-([ADR 0097](doc/decisions/0097-what-start-refuses-that-the-flow-does-not-decide.md)) — a node reaching a group of the BUILT-IN `KeyedRateLimitGroup` type, through the
+([ADR 0097](doc/decisions/0097-what-start-refuses-that-the-flow-does-not-decide.md)) — a node reaching a group of a BUILT-IN keyed type — `KeyedRateLimitGroup`, or (spec v0.56) `KeyedConcurrentLimitGroup` (section 13) — through the
 pool it runs on — the named instance its `pool` says, else its type's default — or its `workerGroups`. The runtime builds that group with no `keyFrom`, so the scheduler counts each task
 under its `limitKey` — and nothing sets one unless you pass `start` a `createTask` that does, `(c) => new FyflowTask({
 ...c, limitKey: tenant })`; without one the scheduler's `addTask` throws. So `start` with no `createTask` throws
 **`LimitKeyMissing`** for it — after any `InvalidDefinition`, before any run id is spent — and with one, `FD-R6` refuses
 nothing (a factory that sets no key meets the scheduler's own throw). `check` cannot know what you will pass, so it
 reports `FD-R6` as if you pass none: filter it out by `f.rule` if you start with a keying `createTask`. A group a CODE
-group type builds — a `KeyedRateLimitGroup` with a `keyFrom` — is never `FD-R6`. A pool's `residentGroups` is not read
+group type builds — a keyed group with a `keyFrom` — is never `FD-R6`. A pool's `residentGroups` is not read
 here: a built-in keyed group held RESIDENT is refused earlier, at `createRuntime` (`DerivationRefused`, section 13,
 [Q619](doc/questions/q619.md)). A key derived from the flow is
 [Q248](doc/questions/q248.md), deferred. **And `createRuntime` refuses a malformed `defaultRetryPolicy`** —
@@ -3621,10 +3622,10 @@ anywhere else.)* This library's listener boundary is written against **0.3.0 sem
 `task.progress`'s detail changed shape at 0.3.0 (the id is `id`, not `taskId`), the second
 `task.user_action` dispatch site arrived there, and `task.timestamp` did not exist before it.
 **`core/FyflowScheduler.ts` was byte-identical between 0.3.0, 0.5.1 and 0.5.2**; it is not at the
-current pin, and W157 re-read what this library rests on there rather than inferring it: the
+current pin, and W157 and W224 re-read what this library rests on there rather than inferring it: the
 `user_action` pair is unchanged on both of its paths, and `task.progress` is built from the same
 fields. What 0.5.1 added is a `worker.setup.*` / `worker.teardown.*` event family this library
-subscribes to not at all. **The current pin adds a sixth task state, `cancelled`, reached only through
+subscribes to not at all. **A sixth task state, `cancelled`, arrived at 0.6.0 and is still the pin's (re-read by W224), reached only through
 `scheduler.cancel(id)`**, and a run hears it: a cancelled task ends its run `cancelled` and settles
 its `done` (section 6, [P33](doc/plans/p33-what-a-run-does-when-a-task-ends-cancelled.md)) — on real
 workers in ladder L6, a task cancelled while running and while queued — and `driver.cancel` asks for one on
@@ -3956,11 +3957,88 @@ a hand-written `NodeTypeDefinition`, or a copy of a resolved one, is a class to
 **A `residentGroups` naming a group of the built-in `KeyedRateLimitGroup` type is refused at `createRuntime`** (v0.39,
 [Q619](doc/questions/q619.md), W169) — `DerivationRefused`, naming the pool and the group, whether a type, a named
 instance or your class's `pool()` put it there. The scheduler resolves no key for a RESIDENT group, so every worker
-holding it would be counted in ONE `""` bucket, in silence. Name a keyed group in `groups` instead — each task is then
-counted under its `limitKey` (`FD-R6`, section 12) — or hold a `ConcurrentLimitGroup` or `RateLimitGroup` resident. A
+holding it would be counted in ONE `""` bucket, in silence. **A built-in `KeyedConcurrentLimitGroup` is refused the same
+way** (spec v0.56, W225) — the scheduler rejects one held resident at construction. Name a keyed group in `groups` instead — each task is then
+counted under its `limitKey` (`FD-R6`, section 12) — or hold a `ConcurrentLimitGroup` or `RateLimitGroup` resident (or a `UnitGroup`). A
 group your own `code.groupTypes` factory builds is never refused. **BREAKING in 0.8.0**: such a document built a
-runtime at 0.7.0. **`bootstrap` called by hand is not covered** — it is handed group OBJECTS and cannot tell the
+runtime at orchestration 0.7.0. **`bootstrap` called by hand is not covered** — it is handed group OBJECTS and cannot tell the
 built-in factory's keyed group from your own — as a `Driver` built by hand is not covered by `FD-R6`.
+
+**Units with names, a limit per key, and a resident REQUEST — as data** — `spec/flow-definition.md` v0.56,
+[ADR 0143](doc/decisions/0143-unit-and-keyed-concurrent-groups-are-built-ins-and-a-resident-request-is-checked-against-the-group.md),
+[W225](doc/work-items/w225-unit-and-keyed-concurrent-groups-and-a-resident-request.md). Two more built-in group types, beside
+`ConcurrentLimitGroup`, `RateLimitGroup` and `KeyedRateLimitGroup`, each the scheduler's own class:
+
+| `type` | `config` | built as |
+|---|---|---|
+| `UnitGroup` | `{ "units": 2 }` (units `0` and `1`) or `{ "units": ["gpu0", "gpu1"] }` — at least one, the names DISTINCT | `new UnitGroup(units, { id: key })` — a hold is granted named units; no `requestFrom` |
+| `KeyedConcurrentLimitGroup` | `{ "limit": 4, "limits": { "E:": 1 } }` — every per-key limit a positive integer | `new KeyedConcurrentLimitGroup(limit, { id: key, limitFor })`, `limitFor(k)` reading a COPY of `limits`, else `limit`; no `keyFrom` |
+
+A repeated unit, or a per-key limit that is not a positive integer, is `GroupConfigRefused` naming the group. **A
+`KeyedConcurrentLimitGroup` is held to `KeyedRateLimitGroup`'s rules**: a node reaching one is `FD-R6` (section 12), and one
+held resident is refused, as above. **A `residentGroups` value may be a REQUEST** — `{ "gpu": { "cost": 1, "from":
+["gpu1"] } }`, `{ cost?, from?, prefer? }`: `from` the units a worker of the pool may hold, `prefer` a hint that never
+blocks, each a non-empty list of distinct ids (an integer for a `UnitGroup` declared by count). **A resident cost is a
+positive INTEGER** — a fraction, which the scheduler throws on, was accepted until spec v0.56. Every cost and request is
+held against the group it names when the runtime is built, `DerivationRefused` naming the pool and the group, each a pool
+the scheduler would throw on at construction: an id a `UnitGroup` lacks, a cost above `from`'s size or above a group's
+limit (a `RateLimitGroup`'s smallest window), and `from` / `prefer` on a `ConcurrentLimitGroup` or `RateLimitGroup`, which
+take no request — `{ cost }` alone is a cost for any group. A request to a group your `code.groupTypes` factory builds is
+handed on untouched WITHIN the request shape `{ cost?, from?, prefer? }`, for its own `checkRequest` — a request
+language beyond that shape is not declarable in a document. A TASK's request is its `units`, set by your `createTask`; nothing in a
+flow declares one.
+
+```ts run
+import { createRuntime } from 'fyflow-orchestration/scheduler';
+import { DerivationRefused, GroupConfigRefused, type FlowDefinition, type RegistryDocument } from 'fyflow-orchestration';
+import { KeyedConcurrentLimitGroup, UnitGroup } from 'fyflow-scheduler';
+
+// Two cards, a worker per card, and this pool pinned to the second; a per-disk limit with a slow USB disk.
+const registry = (resident: unknown, units: unknown = ['gpu0', 'gpu1']): RegistryDocument => ({
+  workers: { ingest: { url: '../../examples/workers/ingest.ts' } },
+  groups: {
+    gpu: { type: 'UnitGroup', config: { units } },
+    disk: { type: 'KeyedConcurrentLimitGroup', config: { limit: 4, limits: { 'E:': 1 } } },
+  },
+  nodeTypes: {
+    Model: { worker: 'ingest', inline: true, pool: { idleTimeout: 1000, residentGroups: resident as never } },
+    Copy: { worker: 'ingest', inline: true, groups: ['disk'] },
+  },
+});
+
+const runtime = createRuntime(registry({ gpu: { cost: 1, from: ['gpu1'] } }), {}, { base: import.meta.url });
+const gpu = runtime.groups['gpu'] as unknown as UnitGroup;
+const disk = runtime.groups['disk'] as unknown as KeyedConcurrentLimitGroup;
+if (!(gpu instanceof UnitGroup) || gpu.getFreeUnits().join() !== 'gpu0,gpu1') throw new Error('the scheduler`s own UnitGroup, both cards free');
+if (!(disk instanceof KeyedConcurrentLimitGroup) || disk.getKeyMetrics('E:').limit !== 1 || disk.getKeyMetrics('C:').limit !== 4) {
+  throw new Error('the per-key limits: E: 1, any other disk 4');
+}
+// The pool is handed the request as declared — the scheduler grants this pool's workers gpu1 and nothing else.
+if (JSON.stringify(runtime.pools['Model']!.spec.residentGroups) !== '{"gpu":{"cost":1,"from":["gpu1"]}}') throw new Error('the request');
+
+// A node reaching the keyed group needs a `limitKey`, which only your createTask sets: FD-R6, as for KeyedRateLimitGroup.
+const copy: FlowDefinition = {
+  flowId: 'copy', version: 1, entry: 'c',
+  nodes: [{ id: 'c', kind: 'task', type: 'Copy', edges: [{ to: 'done' }] }, { id: 'done', kind: 'end', outcome: 'completed' }],
+};
+if (runtime.check(copy).map((f) => f.rule).join() !== 'FD-R6') throw new Error('FD-R6 at the node reaching `disk`');
+await runtime.shutdown();
+
+// What the scheduler would throw on at construction is refused here, naming the pool and the group.
+const refusal = (doc: RegistryDocument): Error => {
+  try { createRuntime(doc, {}, { base: import.meta.url }); } catch (e) { return e as Error; }
+  return new Error('expected a refusal');   // not a refusal class, so every check below throws
+};
+const missing = refusal(registry({ gpu: { from: ['gpu7'] } }));
+if (!(missing instanceof DerivationRefused) || !missing.message.includes('node type "Model"') || !missing.message.includes('unit "gpu7"')) throw new Error(missing.message);
+const tooMany = refusal(registry({ gpu: { cost: 2, from: ['gpu1'] } }));
+if (!(tooMany instanceof DerivationRefused) || !tooMany.message.includes('a cost of 2 from 1')) throw new Error(tooMany.message);
+const keyedResident = refusal(registry(['disk']));
+if (!(keyedResident instanceof DerivationRefused) || !keyedResident.message.includes('KeyedConcurrentLimitGroup')) throw new Error(keyedResident.message);
+const twice = refusal(registry(['gpu'], ['gpu0', 'gpu0']));
+if (!(twice instanceof GroupConfigRefused) || twice.at !== 'gpu') throw new Error(twice.message);
+```
+
 **Your worker's `run(payload, context)` gets the scheduler's own task context as its second argument** —
 the same object the scheduler handed the envelope worker, so `context.signal` (an `AbortSignal`, aborted
 when `scheduler.cancel(taskId)` is called for the task) and `context.emit(name, data)` (a `task.message`
@@ -3970,6 +4048,62 @@ pass `onTaskMessage` to `start` (since 0.8.0, section 8) and each message of the
 its run, node, branch and attempts as fields — or listen for it on `runtime.scheduler` yourself, as before; what
 cancelling a task does to its RUN is section 6's.
 
+**Which UNITS your worker holds reaches it in both places the scheduler puts it** — P46,
+[W226](doc/work-items/w226-grants-reach-a-types-worker-the-reply-and-p46s-close.md), held on real workers by ladder L6's
+*W226 exit* block, threaded and inline, in Node 24 and Deno. The constructor's second argument is the scheduler's own
+**worker context**, so **`workerContext.grants`** is what the worker's `residentGroups` granted it — a `UnitGroup`'s
+units as an array, `{ gpu: ['gpu1'] }` — set BEFORE the constructor runs, so `setup()` can load onto that card; keep the
+argument (a class extending the scheduler's `BaseWorker` passes it to `super` and reads `this.workerContext`). `run`'s
+second argument is the task's **`context`**, and **`context.grants`** is that attempt's: the task's own units plus its
+worker's resident ones — in the scheduler's words, *"its own winning on a clash"*, so a task holding the group its worker
+holds resident reads its own unit there — per attempt (a retry may get another unit, so read it every time), *"frozen one
+level down - a copy, on inline pools too"*, and `{}` when nothing was granted — a `ConcurrentLimitGroup` grants nothing. **A task's request is `units` on the task, and `units` set by your
+`createTask` reaches the scheduler as `limitKey` does**: `(c) => new FyflowTask({ ...c, units: { gpu: { from: ['gpu1']
+} } })`. A named instance's request reaches the scheduler the same way (section 13's `residentGroups` above); what `from`
+and `prefer` each mean is the scheduler's own.
+
+```ts run
+import { createRuntime, type StartOptions } from 'fyflow-orchestration/scheduler';
+import type { FlowDefinition, RegistryDocument } from 'fyflow-orchestration';
+import { FyflowTask } from 'fyflow-scheduler';
+
+// A type's worker reading both: the card its worker holds (read in the constructor) and what its task was granted.
+const worker = `data:text/javascript,${encodeURIComponent(`export default class {
+  constructor(config, workerContext) { this.card = workerContext.grants.gpu?.[0] ?? null; }
+  async setup() {}
+  run(p, context) { return { card: this.card, task: context.grants }; } }`)}`;
+const registry: RegistryDocument = {
+  workers: { model: { url: worker } },
+  groups: { gpu: { type: 'UnitGroup', config: { units: ['gpu0', 'gpu1'] } } },
+  nodeTypes: {
+    Model: { worker: 'model', inline: true, pool: { residentGroups: { gpu: 1 } } },   // a card per WORKER
+    Batch: { worker: 'model', inline: true, groups: ['gpu'] },                        // a card per TASK
+  },
+  pools: { 'model-1': { type: 'Model', pool: { residentGroups: { gpu: { cost: 1, from: ['gpu1'] } } } } },
+};
+const seen = async (type: string, pool?: string, options: StartOptions = {}): Promise<string> => {
+  const flow: FlowDefinition = { flowId: type, version: 1, entry: 't', nodes: [
+    { id: 't', kind: 'task', type, ...(pool === undefined ? {} : { pool }), edges: [{ to: 'done' }] },
+    { id: 'done', kind: 'end', outcome: 'completed' }] };
+  const runtime = createRuntime(registry, {}, { base: import.meta.url });   // its own gpu, both cards free
+  try {
+    const run = runtime.start(flow, {}, options);
+    if ((await run.done).outcome !== 'completed') return `${type} did not complete`;   // a sentinel no check below accepts
+    const results = run.driver.foldInputs().flatMap((i) => (i.kind === 'outcome' && i.record.kind === 'outcome' ? [i.record.result] : []));
+    return JSON.stringify(results);
+  } finally {
+    await runtime.shutdown();
+  }
+};
+// Resident: the worker holds a card from its constructor on, and its task sees it; the named instance's request reaches it.
+if (await seen('Model') !== '[{"card":"gpu0","task":{"gpu":["gpu0"]}}]') throw new Error('the lowest free card');
+if (await seen('Model', 'model-1') !== '[{"card":"gpu1","task":{"gpu":["gpu1"]}}]') throw new Error('the named instance`s request');
+// Per task: the worker holds nothing, and `units` set by createTask picks the card.
+const pinned: StartOptions = { createTask: (c) => new FyflowTask({ ...c, units: { gpu: { from: ['gpu1'] } } }) };
+if (await seen('Batch', undefined, pinned) !== '[{"card":null,"task":{"gpu":["gpu1"]}}]') throw new Error('units through createTask');
+if (await seen('Batch') !== '[{"card":null,"task":{"gpu":["gpu0"]}}]') throw new Error('no request, the lowest free card');
+```
+
 **A transform — what a node may DO to its input before its worker sees it** — `spec/flow-definition.md`
 v0.18, [ADR 0051](doc/decisions/0051-a-transform-is-a-declared-expression-in-a-registered-language-applied-in-the-types-worker-wrapper.md),
 [W61](doc/work-items/w61-what-a-transform-is.md). When the value a typed node receives is not the

package/README.md

@@ -17,7 +17,7 @@ worker returned, routing can **fan out** into parallel branches, and a **join**
 The scheduler runs tasks; this library decides **which task runs next**. `fyflow-scheduler` has no
 dependency graph of its own, so sequence, decision, fan-out and join live here.
 
-Published on npm as `fyflow-orchestration` and on JSR as `@fyflow/orchestration`. The manifests read `0.13.0`.
+Published on npm as `fyflow-orchestration` and on JSR as `@fyflow/orchestration`. The manifests read `0.14.0`.
 
 ## Install
 

package/dist/browser/chunks/{chunk-53EDI674.js → chunk-5KUYTCXI.js}

@@ -1684,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"];
@@ -1728,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 = {
@@ -1775,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)) {
@@ -1796,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;
@@ -1826,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 {
@@ -1913,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) } : {} };
 }
@@ -2024,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());
@@ -2062,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 ?? [];

package/dist/browser/index.js

@@ -152,7 +152,7 @@ import {
   visibilityKey,
   witness,
   workersOf
-} from "./chunks/chunk-53EDI674.js";
+} from "./chunks/chunk-5KUYTCXI.js";
 
 // src/definition/definition-schema.ts
 var DRAFT_2020_12 = "https://json-schema.org/draft/2020-12/schema";

package/dist/browser/scheduler/index.js

@@ -26,7 +26,7 @@ import {
   retryPolicyProblem,
   validateDefinition,
   workersOf
-} from "../chunks/chunk-53EDI674.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;

package/dist/node/chunks/{chunk-53EDI674.js → chunk-5KUYTCXI.js}

@@ -1684,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"];
@@ -1728,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 = {
@@ -1775,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)) {
@@ -1796,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;
@@ -1826,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 {
@@ -1913,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) } : {} };
 }
@@ -2024,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());
@@ -2062,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 ?? [];

package/dist/node/index.js

@@ -152,7 +152,7 @@ import {
   visibilityKey,
   witness,
   workersOf
-} from "./chunks/chunk-53EDI674.js";
+} from "./chunks/chunk-5KUYTCXI.js";
 
 // src/definition/definition-schema.ts
 var DRAFT_2020_12 = "https://json-schema.org/draft/2020-12/schema";

package/dist/node/scheduler/index.js

@@ -26,7 +26,7 @@ import {
   retryPolicyProblem,
   validateDefinition,
   workersOf
-} from "../chunks/chunk-53EDI674.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;

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

@@ -61,10 +61,14 @@ export declare class ConfigRefused extends RegistryError {
 /** A type's OWN config — its default instance's — fails its own `configSchema` or, derived, the worker's; the type has no valid default. */
 export declare class TypeDefaultRefused extends RegistryError {
 }
-/** A group's `type` names no group type — none of the three built-ins, none registered in `code`. */
+/** A group's `type` names no group type — none of the built-ins (`BUILT_IN_GROUP_TYPES`), none registered in `code`. */
 export declare class GroupTypeMissing extends RegistryError {
 }
-/** A group's config fails its group type's `configSchema`. */
+/**
+ * A group's config fails its group type's `configSchema` — or, since v0.56 (ADR 0143 rules 1 and 2), a built-in's rule the
+ * schema subset cannot state: a `UnitGroup` listing a unit twice, a `KeyedConcurrentLimitGroup` per-key limit that is not
+ * a positive integer.
+ */
 export declare class GroupConfigRefused extends RegistryError {
 }
 /** One name, two definitions: a node type in the document AND in `code`, a pool named as a type, a group type named as a built-in. */
@@ -82,7 +86,9 @@ export declare class NameMissing extends RegistryError {
 /**
  * A derivation returned something that is not a `PoolSpec`, threw, or produced a pool the runtime refuses: a resident group
  * beside `idleTimeout: 0`, or — since v0.39 ([Q619](../../doc/questions/q619.md) option B) — a group of the built-in
- * `KeyedRateLimitGroup` type held in `residentGroups`, which the scheduler would count in one `""` bucket.
+ * `KeyedRateLimitGroup` type held in `residentGroups`, which the scheduler would count in one `""` bucket, and since v0.56 one
+ * of the built-in `KeyedConcurrentLimitGroup` type, which it rejects at construction; or, since v0.56 (ADR 0143 rules 4 and
+ * 5), a resident cost or request of the wrong shape, or one the built-in group it names refuses.
  */
 export declare class DerivationRefused extends RegistryError {
 }
@@ -98,12 +104,14 @@ export declare class DerivationRefused extends RegistryError {
 export declare class GateTypeRefused extends RegistryError {
 }
 /**
- * **The three group types the runtime ships, by name and by config schema** — P18 decision 4 and
- * fact 2. Their constructors differ (`ConcurrentLimitGroup(limit, id?)`, `RateLimitGroup(windows, id?)`,
- * `KeyedRateLimitGroup(windows, options?)`), so each has a factory; the FACTORIES construct scheduler
+ * **The group types the runtime ships, by name and by config schema** — P18 decision 4 and
+ * fact 2; three until v0.56, five since (P46 decisions 3 and 5, ADR 0143). Their constructors differ
+ * (`ConcurrentLimitGroup(limit, id?)`, `RateLimitGroup(windows, id?)`, `KeyedRateLimitGroup(windows, options?)`,
+ * `UnitGroup(units, options?)`, `KeyedConcurrentLimitGroup(limit, options?)`), so each has a factory; the FACTORIES construct scheduler
  * objects and live in the scheduler sub-path, beside `bootstrap` (W66; there is no `/runtime` sub-path — P16 decision 5's *one sub-path that constructs scheduler objects*). What this module needs of them is the NAME — a
  * custom group type colliding with one is refused — and the SCHEMA its config is checked against, and
- * both are data. `RateWindow` is `{ limit, windowMs }` verbatim from the scheduler's `.d.ts`.
+ * both are data. `RateWindow` is `{ limit, windowMs }` verbatim from the scheduler's `.d.ts`. **Two rules the
+ * subset cannot state** (P46 fact 7) are `builtInConfigProblem`'s, below, checked beside the schema.
  */
 export declare const BUILT_IN_GROUP_TYPES: Readonly<Record<string, {
     readonly configSchema: JsonSchema;
@@ -157,8 +165,8 @@ export declare function nodeTypeFromDeclaration(decl: NodeTypeDeclaration, over?
  * **Why a derivation's output is not a `PoolSpec`, or `null`** — the check BOTH forms pass through
  * (decision 2's *a class cannot compute around a check*). The scheduler coerces or ignores a wrong
  * option in silence exactly as it does a retry policy (`FD-V30`'s measurements), so the shape is
- * pinned here: numbers where numbers, a string list for `groups`, a string list or a `{ key: cost }`
- * record for `residentGroups`, and no key beside the eight.
+ * pinned here: numbers where numbers, a string list for `groups`, a string list or a record of a cost
+ * or (v0.56) a request per key for `residentGroups` (`residentValueProblem`), and no key beside the eight.
  *
  * **`cancelGraceMs` and `messages` (v0.33, P33 decision 6, W159) are held to the SCHEDULER's own rules**, read
  * at the pin in its `validateGraceMs` and `resolveMessageOptions`, where it throws at `new WorkerManager`:
@@ -193,7 +201,7 @@ export declare function poolOptionsOf(spec: PoolSpec, inline: boolean | undefine
  * a document type has none — its knobs are the fields an instance may override), the derivation RUN,
  * its output held to `PoolSpec`'s shape, the derived config against the WORKER's `configSchema`,
  * every group it names present, and decision 9's refusal — a resident group beside `idleTimeout: 0`
- * deadlocks a contended group (P18 fact 6, the scheduler reference's own sentence).
+ * deadlocks a contended group (P18 fact 6, re-measured at P46 fact 6; the scheduler reference's own sentence).
  *
  * **`pool` is a named instance's OWN pool options** (v0.37, ADR 0099): the instance is derived by its type's identity
  * derivation with them merged over the type's declared ones (`nodeTypeFromDeclaration(declaration, pool)`), and the

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

@@ -328,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
@@ -341,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
@@ -430,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/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.13.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"