@smthrs/plan 0.0.0-stage → 1.0.0-rc.12

package/dist/esm/Planned.js

@@ -0,0 +1,147 @@
+/**
+ * The placeholder a body sees where a step result will be.
+ *
+ * A flow body runs at PLAN time, so its
+ * own payload is real data while every step result is a value that does not
+ * exist yet. That value has a name and one rule: a planned value may be **passed** — into a payload field,
+ * into a branch, into a map — and field access is allowed, because it records a
+ * reference path. It may never be **computed on**.
+ *
+ * {@link Planned} is branded, so arithmetic is a compile error.
+ * {@link make} returns a strict proxy
+ * whose `Symbol.toPrimitive`, `valueOf`, `toString`, `toJSON`, and call traps
+ * throw {@link module:GraphBuildError.GraphBuildError} rather than let a plan be
+ * built around `NaN` or `"[object Object]"`. The lenient proxy this adapts
+ * (`@smthrs/core`'s `Graph.plannedValue`) answered `toPrimitive` with a
+ * readable string, which is exactly the silent-wrong-plan path this module
+ * exists to close.
+ *
+ * JavaScript does not expose traps for `Boolean(value)` or strict identity
+ * (`value === other`), so those operations cannot be refused at run time.
+ * They reveal only proxy truthiness or identity and never the planned result;
+ * authors must use {@link module:Node.branch} for decisions on real values.
+ * Type-aware ESLint `@typescript-eslint/strict-boolean-expressions` rejects
+ * planned conditions, but does not reject explicit Boolean coercion or all
+ * reference comparisons. Those still require review.
+ *
+ * @since 0.1.0
+ */
+import { GraphBuildError } from "./GraphBuildError.js";
+/**
+ * The brand carried by every planned value, and the key its reference is read
+ * from. Interned with `Symbol.for` so a value that crossed a module boundary is
+ * still recognised. The interned symbol is a recognition aid, not a
+ * capability, so {@link reference} validates the value stored under it.
+ *
+ * @since 0.1.0
+ * @category symbols
+ * @slop
+ */
+export const TypeId = Symbol.for("@smthrs/plan/Planned");
+/**
+ * The operations that are computation rather than reference, keyed by the
+ * property that performs them. `toJSON` is here because `JSON.stringify` reads
+ * it, and a plan that serialized a placeholder would look correct.
+ *
+ * @private
+ */
+const refusals = new Map([
+    [Symbol.toPrimitive, "Symbol.toPrimitive"],
+    ["valueOf", "valueOf"],
+    ["toString", "toString"],
+    ["toJSON", "toJSON"]
+]);
+/** @private */
+const describe = (reference) => reference.path.length === 0 ? reference.node : `${reference.node}.${reference.path.join(".")}`;
+/**
+ * The one refusal this module raises. The guidance is spelled out rather than
+ * linked because the author reading it is inside a body and needs the
+ * correction on the spot.
+ *
+ * @private
+ */
+const refuse = (reference, operation) => new GraphBuildError({
+    code: "planned_value_computed",
+    node: reference.node,
+    path: reference.path,
+    message: `Planned value ${describe(reference)} was computed at plan time by ${operation}. ` +
+        "Use Node.map to compute, Node.branch to decide, or pass the value into a payload."
+});
+/**
+ * The proxy itself. `_T` of {@link Identity} is a phantom and never exists at
+ * run time, so the trap carries the plain {@link Reference}.
+ *
+ * @private
+ */
+const placeholder = (reference) => {
+    /* v8 ignore next -- a Proxy application always enters the `apply` trap below, so the callable target is unreachable by construction */
+    const target = () => undefined;
+    return new Proxy(target, {
+        get: (_target, key) => {
+            if (key === TypeId)
+                return reference;
+            const refusal = refusals.get(key);
+            if (refusal !== undefined)
+                throw refuse(reference, refusal);
+            // Not a thenable: a body that returns a planned value inside a promise
+            // must resolve to the placeholder, not hang awaiting a proxy.
+            if (key === "then")
+                return undefined;
+            return placeholder({ node: reference.node, path: [...reference.path, String(key)] });
+        },
+        apply: () => {
+            throw refuse(reference, "function application");
+        },
+        has: () => {
+            throw refuse(reference, "property existence (`in`)");
+        },
+        ownKeys: () => {
+            throw refuse(reference, "property enumeration");
+        }
+    });
+};
+/**
+ * Creates the strict placeholder standing for a node's result.
+ *
+ * Planning hands one of these to every builder that consumes an upstream
+ * value — a branch arm, a continuation — and reads the {@link Reference} back
+ * off whatever the builder passed it into.
+ *
+ * @since 0.1.0
+ * @category constructors
+ * @slop
+ */
+export const make = (node) => placeholder({ node, path: [] });
+/** @private */
+const carrier = (value) => (typeof value === "object" && value !== null) || typeof value === "function";
+/** @private */
+const validReference = (value) => typeof value === "object" && value !== null &&
+    typeof value.node === "string" && value.node.length > 0 &&
+    Array.isArray(value.path) &&
+    Array.from(value.path).every((segment) => typeof segment === "string");
+/**
+ * Reads the reference a planned value records, or `undefined` for anything
+ * else. An interned symbol is a recognition aid rather than a capability, so a
+ * forged carrier is accepted only when its node and path have the complete
+ * reference shape. This is how a payload is scanned for the upstream results
+ * it consumes.
+ *
+ * @since 0.1.0
+ * @category accessors
+ * @slop
+ */
+export const reference = (value) => {
+    if (!carrier(value))
+        return undefined;
+    const candidate = value[TypeId];
+    return validReference(candidate) ? candidate : undefined;
+};
+/**
+ * Checks whether a value is a planned placeholder.
+ *
+ * @since 0.1.0
+ * @category guards
+ * @slop
+ */
+export const isPlanned = (value) => reference(value) !== undefined;
+//# sourceMappingURL=Planned.js.map

package/dist/esm/Planned.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Planned.js","sourceRoot":"","sources":["../../src/Planned.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The placeholder a body sees where a step result will be.\n *\n * A flow body runs at PLAN time, so its\n * own payload is real data while every step result is a value that does not\n * exist yet. That value has a name and one rule: a planned value may be **passed** — into a payload field,\n * into a branch, into a map — and field access is allowed, because it records a\n * reference path. It may never be **computed on**.\n *\n * {@link Planned} is branded, so arithmetic is a compile error.\n * {@link make} returns a strict proxy\n * whose `Symbol.toPrimitive`, `valueOf`, `toString`, `toJSON`, and call traps\n * throw {@link module:GraphBuildError.GraphBuildError} rather than let a plan be\n * built around `NaN` or `\"[object Object]\"`. The lenient proxy this adapts\n * (`@smthrs/core`'s `Graph.plannedValue`) answered `toPrimitive` with a\n * readable string, which is exactly the silent-wrong-plan path this module\n * exists to close.\n *\n * JavaScript does not expose traps for `Boolean(value)` or strict identity\n * (`value === other`), so those operations cannot be refused at run time.\n * They reveal only proxy truthiness or identity and never the planned result;\n * authors must use {@link module:Node.branch} for decisions on real values.\n * Type-aware ESLint `@typescript-eslint/strict-boolean-expressions` rejects\n * planned conditions, but does not reject explicit Boolean coercion or all\n * reference comparisons. Those still require review.\n *\n * @since 0.1.0\n */\n\nimport type * as Types from \"effect/Types\"\nimport { GraphBuildError } from \"./GraphBuildError.ts\"\n\n/**\n * The brand carried by every planned value, and the key its reference is read\n * from. Interned with `Symbol.for` so a value that crossed a module boundary is\n * still recognised. The interned symbol is a recognition aid, not a\n * capability, so {@link reference} validates the value stored under it.\n *\n * @since 0.1.0\n * @category symbols\n * @slop\n */\nexport const TypeId: unique symbol = Symbol.for(\"@smthrs/plan/Planned\")\n\n/**\n * The type-level form of {@link TypeId}.\n *\n * @since 0.1.0\n * @category symbols\n * @slop\n */\nexport type TypeId = typeof TypeId\n\n/**\n * What a planned value points at: the node that will produce the result, and\n * the property path read from it. `path` is empty for the result itself.\n *\n * @since 0.1.0\n * @category models\n * @slop\n */\nexport interface Reference {\n  readonly node: string\n  readonly path: ReadonlyArray<string>\n}\n\n/**\n * A {@link Reference} plus the phantom type of the value it stands for, so\n * `Planned<string>` and `Planned<number>` are not interchangeable.\n *\n * @since 0.1.0\n * @category models\n * @slop\n */\nexport interface Identity<out T> extends Reference {\n  readonly _T: Types.Covariant<T>\n}\n\n/**\n * A step result that has not been produced yet.\n *\n * The brand rejects arithmetic and ordinary value arguments. The mapped half keeps field\n * access typed — `result.files` is a `Planned` of the field, which is what\n * makes \"pass it on, never compute on it\" expressible rather than merely\n * documented.\n *\n * @since 0.1.0\n * @category models\n * @slop\n */\nexport type Planned<T> =\n  & { readonly [TypeId]: Identity<T> }\n  & ([T] extends [object] ? { readonly [K in keyof T]: Planned<T[K]> } : unknown)\n\n/**\n * The operations that are computation rather than reference, keyed by the\n * property that performs them. `toJSON` is here because `JSON.stringify` reads\n * it, and a plan that serialized a placeholder would look correct.\n *\n * @private\n */\nconst refusals = new Map<PropertyKey, string>([\n  [Symbol.toPrimitive, \"Symbol.toPrimitive\"],\n  [\"valueOf\", \"valueOf\"],\n  [\"toString\", \"toString\"],\n  [\"toJSON\", \"toJSON\"]\n])\n\n/** @private */\nconst describe = (reference: Reference): string =>\n  reference.path.length === 0 ? reference.node : `${reference.node}.${reference.path.join(\".\")}`\n\n/**\n * The one refusal this module raises. The guidance is spelled out rather than\n * linked because the author reading it is inside a body and needs the\n * correction on the spot.\n *\n * @private\n */\nconst refuse = (reference: Reference, operation: string): GraphBuildError =>\n  new GraphBuildError({\n    code: \"planned_value_computed\",\n    node: reference.node,\n    path: reference.path,\n    message: `Planned value ${describe(reference)} was computed at plan time by ${operation}. ` +\n      \"Use Node.map to compute, Node.branch to decide, or pass the value into a payload.\"\n  })\n\n/**\n * The proxy itself. `_T` of {@link Identity} is a phantom and never exists at\n * run time, so the trap carries the plain {@link Reference}.\n *\n * @private\n */\nconst placeholder = (reference: Reference): unknown => {\n  /* v8 ignore next -- a Proxy application always enters the `apply` trap below, so the callable target is unreachable by construction */\n  const target = (): undefined => undefined\n  return new Proxy(target, {\n    get: (_target, key) => {\n      if (key === TypeId) return reference\n      const refusal = refusals.get(key)\n      if (refusal !== undefined) throw refuse(reference, refusal)\n      // Not a thenable: a body that returns a planned value inside a promise\n      // must resolve to the placeholder, not hang awaiting a proxy.\n      if (key === \"then\") return undefined\n      return placeholder({ node: reference.node, path: [...reference.path, String(key)] })\n    },\n    apply: () => {\n      throw refuse(reference, \"function application\")\n    },\n    has: () => {\n      throw refuse(reference, \"property existence (`in`)\")\n    },\n    ownKeys: () => {\n      throw refuse(reference, \"property enumeration\")\n    }\n  })\n}\n\n/**\n * Creates the strict placeholder standing for a node's result.\n *\n * Planning hands one of these to every builder that consumes an upstream\n * value — a branch arm, a continuation — and reads the {@link Reference} back\n * off whatever the builder passed it into.\n *\n * @since 0.1.0\n * @category constructors\n * @slop\n */\nexport const make = <T>(node: string): Planned<T> => placeholder({ node, path: [] }) as Planned<T>\n\n/** @private */\nconst carrier = (value: unknown): value is { readonly [TypeId]?: Reference } =>\n  (typeof value === \"object\" && value !== null) || typeof value === \"function\"\n\n/** @private */\nconst validReference = (value: unknown): value is Reference =>\n  typeof value === \"object\" && value !== null &&\n  typeof (value as Reference).node === \"string\" && (value as Reference).node.length > 0 &&\n  Array.isArray((value as Reference).path) &&\n  Array.from((value as Reference).path).every((segment) => typeof segment === \"string\")\n\n/**\n * Reads the reference a planned value records, or `undefined` for anything\n * else. An interned symbol is a recognition aid rather than a capability, so a\n * forged carrier is accepted only when its node and path have the complete\n * reference shape. This is how a payload is scanned for the upstream results\n * it consumes.\n *\n * @since 0.1.0\n * @category accessors\n * @slop\n */\nexport const reference = (value: unknown): Reference | undefined => {\n  if (!carrier(value)) return undefined\n  const candidate = value[TypeId]\n  return validReference(candidate) ? candidate : undefined\n}\n\n/**\n * Checks whether a value is a planned placeholder.\n *\n * @since 0.1.0\n * @category guards\n * @slop\n */\nexport const isPlanned = (value: unknown): value is Planned<unknown> => reference(value) !== undefined\n"]}

package/dist/esm/Repetition.d.ts

@@ -0,0 +1,31 @@
+/**
+ * What a bounded repetition does when it reaches its ceiling.
+ *
+ * This is the ONE ceiling vocabulary. `@smthrs/flow`'s `Poll.make` takes it as
+ * `onTimeout`, for the attempt a poll gives up on, and `@smthrs/patterns`'
+ * `Loop` takes it as `onMaxReached`, for the iteration a loop gives up on. It
+ * was the same two words written out in both packages, with no edge between
+ * them, so a third member added on one side would have been invisible to the
+ * other. It lives here because `@smthrs/plan` is the package both already
+ * depend on.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Schema from "effect/Schema";
+/**
+ * What a bounded repetition answers with at its ceiling: `fail` raises the
+ * repetition's own typed failure, and `return-last` settles with the last
+ * value it produced.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export declare const AtCeiling: Schema.Literals<readonly ["fail", "return-last"]>;
+/**
+ * The value form of {@link AtCeiling}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type AtCeiling = typeof AtCeiling.Type;
+//# sourceMappingURL=Repetition.d.ts.map

package/dist/esm/Repetition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Repetition.d.ts","sourceRoot":"","sources":["../../src/Repetition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,mDAA2C,CAAA;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAA"}

package/dist/esm/Repetition.js

@@ -0,0 +1,24 @@
+/**
+ * What a bounded repetition does when it reaches its ceiling.
+ *
+ * This is the ONE ceiling vocabulary. `@smthrs/flow`'s `Poll.make` takes it as
+ * `onTimeout`, for the attempt a poll gives up on, and `@smthrs/patterns`'
+ * `Loop` takes it as `onMaxReached`, for the iteration a loop gives up on. It
+ * was the same two words written out in both packages, with no edge between
+ * them, so a third member added on one side would have been invisible to the
+ * other. It lives here because `@smthrs/plan` is the package both already
+ * depend on.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Schema from "effect/Schema";
+/**
+ * What a bounded repetition answers with at its ceiling: `fail` raises the
+ * repetition's own typed failure, and `return-last` settles with the last
+ * value it produced.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export const AtCeiling = Schema.Literals(["fail", "return-last"]);
+//# sourceMappingURL=Repetition.js.map

package/dist/esm/Repetition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Repetition.js","sourceRoot":"","sources":["../../src/Repetition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAA","sourcesContent":["/**\n * What a bounded repetition does when it reaches its ceiling.\n *\n * This is the ONE ceiling vocabulary. `@smthrs/flow`'s `Poll.make` takes it as\n * `onTimeout`, for the attempt a poll gives up on, and `@smthrs/patterns`'\n * `Loop` takes it as `onMaxReached`, for the iteration a loop gives up on. It\n * was the same two words written out in both packages, with no edge between\n * them, so a third member added on one side would have been invisible to the\n * other. It lives here because `@smthrs/plan` is the package both already\n * depend on.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Schema from \"effect/Schema\"\n\n/**\n * What a bounded repetition answers with at its ceiling: `fail` raises the\n * repetition's own typed failure, and `return-last` settles with the last\n * value it produced.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport const AtCeiling = Schema.Literals([\"fail\", \"return-last\"])\n\n/**\n * The value form of {@link AtCeiling}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type AtCeiling = typeof AtCeiling.Type\n"]}

package/dist/esm/Scheduling.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Shared ready-work admission policy. This module decides priority, aging,
+ * deterministic ties, and step/agent capacity. It does not decide which nodes
+ * are ready, evaluate branches, launch effects, or own execution lifetimes.
+ * Those decisions must use the compiled graph and the caller's activation
+ * state before presenting candidates here.
+ *
+ * @since 1.0.0
+ */
+import type * as Plan from "./Plan.ts";
+/**
+ * Admission limits, independent of graph width and provider capacity.
+ * Omitted limits are unbounded within JavaScript's safe-integer range.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Concurrency {
+    readonly steps?: number | undefined;
+    readonly agents?: number | undefined;
+}
+/**
+ * Currently held permits. Every agent also holds a step permit.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Usage {
+    readonly steps: number;
+    readonly agents: number;
+}
+/**
+ * The part of a plan node admission reads. Declared once here so the three
+ * places that name it, {@link Candidate}, {@link Admission} and
+ * {@link Policy.admit}, cannot drift apart.
+ */
+type Schedulable = Pick<Plan.PlanNode, "id" | "kind" | "priority">;
+/**
+ * A ready node's scheduling state. `order` is its position in the compiled
+ * plan, not arrival order. `waited` counts capacity-constrained admission
+ * passes, not wall-clock time.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Candidate<N extends Schedulable = Plan.PlanNode> {
+    readonly node: N;
+    readonly order: number;
+    readonly waited: number;
+}
+/**
+ * One admission decision. Deferred candidates carry their incremented age;
+ * admitted candidates retain their age for dispatch diagnostics. No input is
+ * mutated and neither array owns or freezes the caller's node values.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Admission<N extends Schedulable = Plan.PlanNode> {
+    readonly admitted: ReadonlyArray<Candidate<N>>;
+    readonly deferred: ReadonlyArray<Candidate<N>>;
+    readonly agents: number;
+}
+/**
+ * Pure policy shared by execution coordinators.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Policy {
+    readonly limits: Usage;
+    readonly admit: <N extends Schedulable>(ready: ReadonlyArray<Candidate<N>>, active: Usage) => Admission<N>;
+}
+/**
+ * Snapshots validated limits. Admission orders by declared priority plus age,
+ * using exact integer arithmetic even when their sum exceeds MAX_SAFE_INTEGER.
+ * Ties preserve compiled plan order. An agent blocked by its subset cap does
+ * not prevent ordinary ready work from using spare step capacity.
+ *
+ * Invalid candidate/permit state is refused before any decision is returned.
+ * At MAX_SAFE_INTEGER the age saturates; a bounded plan cannot require that
+ * many capacity-constrained passes to drain finite work.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export declare const make: (concurrency?: Concurrency) => Policy;
+export {};
+//# sourceMappingURL=Scheduling.d.ts.map

package/dist/esm/Scheduling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scheduling.d.ts","sourceRoot":"","sources":["../../src/Scheduling.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAA;AAEtC;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACrC;AAED;;;;;GAKG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;GAIG;AACH,KAAK,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,GAAG,MAAM,GAAG,UAAU,CAAC,CAAA;AAElE;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,WAAW,GAAG,IAAI,CAAC,QAAQ;IAC9D,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;IAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,WAAW,GAAG,IAAI,CAAC,QAAQ;IAC9D,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA;IAC9C,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,SAAS,WAAW,EACpC,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAClC,MAAM,EAAE,KAAK,KACV,SAAS,CAAC,CAAC,CAAC,CAAA;CAClB;AASD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,IAAI,GAAI,cAAa,WAAgB,KAAG,MAiDpD,CAAA"}

package/dist/esm/Scheduling.js

@@ -0,0 +1,82 @@
+/**
+ * Shared ready-work admission policy. This module decides priority, aging,
+ * deterministic ties, and step/agent capacity. It does not decide which nodes
+ * are ready, evaluate branches, launch effects, or own execution lifetimes.
+ * Those decisions must use the compiled graph and the caller's activation
+ * state before presenting candidates here.
+ *
+ * @since 1.0.0
+ */
+const integer = (name, value, minimum) => {
+    if (!Number.isSafeInteger(value) || value < minimum) {
+        throw new RangeError(`${name} must be a ${minimum === 1 ? "positive" : "non-negative"} safe integer`);
+    }
+    return value;
+};
+/**
+ * Snapshots validated limits. Admission orders by declared priority plus age,
+ * using exact integer arithmetic even when their sum exceeds MAX_SAFE_INTEGER.
+ * Ties preserve compiled plan order. An agent blocked by its subset cap does
+ * not prevent ordinary ready work from using spare step capacity.
+ *
+ * Invalid candidate/permit state is refused before any decision is returned.
+ * At MAX_SAFE_INTEGER the age saturates; a bounded plan cannot require that
+ * many capacity-constrained passes to drain finite work.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export const make = (concurrency = {}) => {
+    const limits = Object.freeze({
+        steps: integer("concurrency.steps", concurrency.steps ?? Number.MAX_SAFE_INTEGER, 1),
+        agents: integer("concurrency.agents", concurrency.agents ?? Number.MAX_SAFE_INTEGER, 1)
+    });
+    const admit = (ready, active) => {
+        integer("active.steps", active.steps, 0);
+        integer("active.agents", active.agents, 0);
+        if (active.agents > active.steps)
+            throw new RangeError("active.agents cannot exceed active.steps");
+        const ids = new Set();
+        const positions = new Set();
+        const ranked = ready.map((candidate) => {
+            const { node, order, waited } = candidate;
+            integer("candidate.order", order, 0);
+            integer("candidate.waited", waited, 0);
+            if (!Number.isSafeInteger(node.priority))
+                throw new RangeError("candidate.priority must be a safe integer");
+            if (node.kind !== "step" && node.kind !== "agent" && node.kind !== "merge") {
+                throw new RangeError("invalid candidate kind");
+            }
+            if (typeof node.id !== "string" || node.id === "" || ids.has(node.id)) {
+                throw new RangeError("candidate ids must be non-empty and unique");
+            }
+            if (positions.has(order))
+                throw new RangeError("candidate plan positions must be unique");
+            ids.add(node.id);
+            positions.add(order);
+            return { candidate, priority: BigInt(node.priority) + BigInt(waited) };
+        });
+        ranked.sort((left, right) => left.priority === right.priority
+            ? left.candidate.order - right.candidate.order
+            : left.priority > right.priority
+                ? -1
+                : 1);
+        const admitted = [];
+        const deferred = [];
+        let agents = 0;
+        for (const { candidate } of ranked) {
+            const isAgent = candidate.node.kind === "agent";
+            if (admitted.length >= limits.steps - active.steps || (isAgent && agents >= limits.agents - active.agents)) {
+                deferred.push(Object.freeze({ ...candidate, waited: Math.min(Number.MAX_SAFE_INTEGER, candidate.waited + 1) }));
+            }
+            else {
+                admitted.push(Object.freeze({ ...candidate }));
+                if (isAgent)
+                    agents++;
+            }
+        }
+        return Object.freeze({ admitted: Object.freeze(admitted), deferred: Object.freeze(deferred), agents });
+    };
+    return Object.freeze({ limits, admit });
+};
+//# sourceMappingURL=Scheduling.js.map

package/dist/esm/Scheduling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scheduling.js","sourceRoot":"","sources":["../../src/Scheduling.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared ready-work admission policy. This module decides priority, aging,\n * deterministic ties, and step/agent capacity. It does not decide which nodes\n * are ready, evaluate branches, launch effects, or own execution lifetimes.\n * Those decisions must use the compiled graph and the caller's activation\n * state before presenting candidates here.\n *\n * @since 1.0.0\n */\n\nimport type * as Plan from \"./Plan.ts\"\n\n/**\n * Admission limits, independent of graph width and provider capacity.\n * Omitted limits are unbounded within JavaScript's safe-integer range.\n *\n * @since 1.0.0\n * @category models\n */\nexport interface Concurrency {\n  readonly steps?: number | undefined\n  readonly agents?: number | undefined\n}\n\n/**\n * Currently held permits. Every agent also holds a step permit.\n *\n * @since 1.0.0\n * @category models\n */\nexport interface Usage {\n  readonly steps: number\n  readonly agents: number\n}\n\n/**\n * The part of a plan node admission reads. Declared once here so the three\n * places that name it, {@link Candidate}, {@link Admission} and\n * {@link Policy.admit}, cannot drift apart.\n */\ntype Schedulable = Pick<Plan.PlanNode, \"id\" | \"kind\" | \"priority\">\n\n/**\n * A ready node's scheduling state. `order` is its position in the compiled\n * plan, not arrival order. `waited` counts capacity-constrained admission\n * passes, not wall-clock time.\n *\n * @since 1.0.0\n * @category models\n */\nexport interface Candidate<N extends Schedulable = Plan.PlanNode> {\n  readonly node: N\n  readonly order: number\n  readonly waited: number\n}\n\n/**\n * One admission decision. Deferred candidates carry their incremented age;\n * admitted candidates retain their age for dispatch diagnostics. No input is\n * mutated and neither array owns or freezes the caller's node values.\n *\n * @since 1.0.0\n * @category models\n */\nexport interface Admission<N extends Schedulable = Plan.PlanNode> {\n  readonly admitted: ReadonlyArray<Candidate<N>>\n  readonly deferred: ReadonlyArray<Candidate<N>>\n  readonly agents: number\n}\n\n/**\n * Pure policy shared by execution coordinators.\n *\n * @since 1.0.0\n * @category models\n */\nexport interface Policy {\n  readonly limits: Usage\n  readonly admit: <N extends Schedulable>(\n    ready: ReadonlyArray<Candidate<N>>,\n    active: Usage\n  ) => Admission<N>\n}\n\nconst integer = (name: string, value: number, minimum: number): number => {\n  if (!Number.isSafeInteger(value) || value < minimum) {\n    throw new RangeError(`${name} must be a ${minimum === 1 ? \"positive\" : \"non-negative\"} safe integer`)\n  }\n  return value\n}\n\n/**\n * Snapshots validated limits. Admission orders by declared priority plus age,\n * using exact integer arithmetic even when their sum exceeds MAX_SAFE_INTEGER.\n * Ties preserve compiled plan order. An agent blocked by its subset cap does\n * not prevent ordinary ready work from using spare step capacity.\n *\n * Invalid candidate/permit state is refused before any decision is returned.\n * At MAX_SAFE_INTEGER the age saturates; a bounded plan cannot require that\n * many capacity-constrained passes to drain finite work.\n *\n * @since 1.0.0\n * @category constructors\n */\nexport const make = (concurrency: Concurrency = {}): Policy => {\n  const limits = Object.freeze({\n    steps: integer(\"concurrency.steps\", concurrency.steps ?? Number.MAX_SAFE_INTEGER, 1),\n    agents: integer(\"concurrency.agents\", concurrency.agents ?? Number.MAX_SAFE_INTEGER, 1)\n  })\n  const admit: Policy[\"admit\"] = (ready, active) => {\n    integer(\"active.steps\", active.steps, 0)\n    integer(\"active.agents\", active.agents, 0)\n    if (active.agents > active.steps) throw new RangeError(\"active.agents cannot exceed active.steps\")\n    const ids = new Set<string>()\n    const positions = new Set<number>()\n    const ranked = ready.map((candidate) => {\n      const { node, order, waited } = candidate\n      integer(\"candidate.order\", order, 0)\n      integer(\"candidate.waited\", waited, 0)\n      if (!Number.isSafeInteger(node.priority)) throw new RangeError(\"candidate.priority must be a safe integer\")\n      if (node.kind !== \"step\" && node.kind !== \"agent\" && node.kind !== \"merge\") {\n        throw new RangeError(\"invalid candidate kind\")\n      }\n      if (typeof node.id !== \"string\" || node.id === \"\" || ids.has(node.id)) {\n        throw new RangeError(\"candidate ids must be non-empty and unique\")\n      }\n      if (positions.has(order)) throw new RangeError(\"candidate plan positions must be unique\")\n      ids.add(node.id)\n      positions.add(order)\n      return { candidate, priority: BigInt(node.priority) + BigInt(waited) }\n    })\n    ranked.sort((left, right) =>\n      left.priority === right.priority\n        ? left.candidate.order - right.candidate.order\n        : left.priority > right.priority\n        ? -1\n        : 1\n    )\n    const admitted: Array<typeof ready[number]> = []\n    const deferred: Array<typeof ready[number]> = []\n    let agents = 0\n    for (const { candidate } of ranked) {\n      const isAgent = candidate.node.kind === \"agent\"\n      if (admitted.length >= limits.steps - active.steps || (isAgent && agents >= limits.agents - active.agents)) {\n        deferred.push(Object.freeze({ ...candidate, waited: Math.min(Number.MAX_SAFE_INTEGER, candidate.waited + 1) }))\n      } else {\n        admitted.push(Object.freeze({ ...candidate }))\n        if (isAgent) agents++\n      }\n    }\n    return Object.freeze({ admitted: Object.freeze(admitted), deferred: Object.freeze(deferred), agents })\n  }\n  return Object.freeze({ limits, admit })\n}\n"]}