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

package/dist/cjs/PlanDiff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlanDiff.d.ts","sourceRoot":"","sources":["../../src/PlanDiff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAA;AAGtC;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACxC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACvC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IACxC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAC1C;AAuGD;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GAAI,UAAU,IAAI,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC,IAAI,KAAG,QAmC3D,CAAA"}

package/dist/cjs/PlanDiff.js

@@ -0,0 +1,124 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var PlanDiff_exports = {};
+__export(PlanDiff_exports, {
+  diff: () => diff
+});
+module.exports = __toCommonJS(PlanDiff_exports);
+var import_JsonMirror = require("./internal/JsonMirror.js");
+const stable = (value) => {
+  if (typeof value === "bigint") return `${value}n`;
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "undefined";
+  if (Array.isArray(value)) return `[${value.map(stable).join(",")}]`;
+  const entries = Object.entries(value).sort(([left], [right]) => left < right ? -1 : 1);
+  return `{${entries.map(([name, entry]) => `${JSON.stringify(name)}:${stable(entry)}`).join(",")}}`;
+};
+const plannedReference = (_value, reference) => ({
+  _tag: "PlannedReference",
+  node: reference.node,
+  path: reference.path
+});
+const fieldComparison = () => {
+  const refused = /* @__PURE__ */ new Map();
+  const token = (input, nodeId, field) => {
+    try {
+      return stable((0, import_JsonMirror.jsonMirror)(input, plannedReference));
+    } catch {
+      const address = JSON.stringify([nodeId, field]);
+      let fields = refused.get(input);
+      if (fields === void 0) {
+        fields = /* @__PURE__ */ new Map();
+        refused.set(input, fields);
+      }
+      let sentinel = fields.get(address);
+      if (sentinel === void 0) {
+        sentinel = Symbol(address);
+        fields.set(address, sentinel);
+      }
+      return sentinel;
+    }
+  };
+  return (previous, next, nodeId, field) => token(previous, nodeId, field) === token(next, nodeId, field);
+};
+const changedFields = (previous, next, rekeyedDependencies, sameField) => {
+  const changed = [];
+  if (!sameField(previous.material.version, next.material.version, next.id, "version")) changed.push("version");
+  if (previous.material.kind !== next.material.kind) changed.push("kind");
+  if (!sameField(previous.material.body, next.material.body, next.id, "body")) changed.push("body");
+  if (!sameField(previous.material.nondeterministic, next.material.nondeterministic, next.id, "nondeterministic")) {
+    changed.push("nondeterministic");
+  }
+  if (!sameField(previous.material.effects, next.material.effects, next.id, "effects")) changed.push("effects");
+  if (!sameField(previous.material.placement, next.material.placement, next.id, "placement")) {
+    changed.push("placement");
+  }
+  const width = Math.max(previous.material.inputs.length, next.material.inputs.length);
+  for (let index = 0; index < width; index++) {
+    const before = previous.material.inputs[index];
+    const after = next.material.inputs[index];
+    const field = `input[${index}]`;
+    if (before === void 0 || after === void 0 || !sameField(before, after, next.id, field)) {
+      changed.push(field);
+      continue;
+    }
+    if (after._tag !== "Literal" && rekeyedDependencies.has(after.from)) changed.push(field);
+  }
+  if (!sameField(previous.material.layers, next.material.layers, next.id, "layers")) changed.push("layers");
+  if (!sameField(previous.material.capabilities, next.material.capabilities, next.id, "capabilities")) {
+    changed.push("capabilities");
+  }
+  return changed;
+};
+const diff = (previous, next) => {
+  const before = new Map(previous.nodes.map((node) => [node.id, node]));
+  const after = new Map(next.nodes.map((node) => [node.id, node]));
+  const rekeyedIds = /* @__PURE__ */ new Set();
+  for (const node of next.nodes) {
+    const original = before.get(node.id);
+    if (original !== void 0 && original.key !== node.key) rekeyedIds.add(node.id);
+  }
+  const added = [];
+  const rekeyed = [];
+  const unchanged = [];
+  const sameField = fieldComparison();
+  for (const node of next.nodes) {
+    const original = before.get(node.id);
+    if (original === void 0) {
+      added.push(node.id);
+      continue;
+    }
+    if (original.key === node.key) {
+      unchanged.push(node.id);
+      continue;
+    }
+    rekeyed.push({
+      id: node.id,
+      from: original.key,
+      to: node.key,
+      changed: changedFields(original, node, rekeyedIds, sameField)
+    });
+  }
+  return {
+    added,
+    removed: previous.nodes.filter((node) => !after.has(node.id)).map((node) => node.id),
+    rekeyed,
+    unchanged
+  };
+};
+//# sourceMappingURL=PlanDiff.js.map

package/dist/cjs/PlanDiff.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/PlanDiff.ts"],
+  "sourcesContent": ["/**\n * A plan comparison, as a value.\n *\n * A plan diff answers \"which steps changed key (and _which input_\n * changed them), what entered the envelope, what joined the release set \u2014\n * 'what is different about this run' is a set comparison, not archaeology.\"\n * This module is the set comparison.\n *\n * The **verdict** is the key: two nodes with the same id and the same key are\n * the same step and nothing else needs saying. The **attribution** \u2014\n * `changed: [\"input[1]\"]` \u2014 is a report for a human, derived by comparing the\n * declarations field by field. It is deliberately not part of any digest.\n *\n * @since 0.1.0\n */\n\nimport { jsonMirror } from \"./internal/JsonMirror.ts\"\nimport type * as Plan from \"./Plan.ts\"\nimport type * as Planned from \"./Planned.ts\"\n\n/**\n * A node whose key moved, with the fields that moved it.\n *\n * @since 0.1.0\n * @category models\n * @slop\n */\nexport interface Rekeyed {\n  readonly id: string\n  readonly from: string\n  readonly to: string\n  /**\n   * Field labels such as `\"kind\"`, `\"body\"`, `\"layers\"`, `\"capabilities\"`,\n   * `\"effects\"`, and `\"input[0]\"` whose declaration differs. `\"kind\"` is the\n   * effect tier (`sealed`, `compensable`, or `irreversible`). A\n   * `Pending`-referenced upstream re-key is attributed to that input position\n   * too. `changed` is empty only when none of the compared fields moved.\n   */\n  readonly changed: ReadonlyArray<string>\n}\n\n/**\n * What changed between two plans of the same flow.\n *\n * @since 0.1.0\n * @category models\n * @slop\n */\nexport interface PlanDiff {\n  readonly added: ReadonlyArray<string>\n  readonly removed: ReadonlyArray<string>\n  readonly rekeyed: ReadonlyArray<Rekeyed>\n  readonly unchanged: ReadonlyArray<string>\n}\n\n/**\n * Order-insensitive structural comparison for the attribution report only.\n * Digests go through RFC 8785 canonical JSON; this does not have to, and\n * saying so keeps the two from being confused.\n *\n * @private\n */\nconst stable = (value: unknown): string => {\n  if (typeof value === \"bigint\") return `${value}n`\n  if (value === null || typeof value !== \"object\") return JSON.stringify(value) ?? \"undefined\"\n  if (Array.isArray(value)) return `[${value.map(stable).join(\",\")}]`\n  const entries = Object.entries(value as Record<string, unknown>).sort(([left], [right]) => left < right ? -1 : 1)\n  return `{${entries.map(([name, entry]) => `${JSON.stringify(name)}:${stable(entry)}`).join(\",\")}}`\n}\n\n/**\n * A planned value compares as the reference an AST stores for it, so the same\n * reference at the same place is unchanged.\n *\n * @private\n */\nconst plannedReference = (_value: unknown, reference: Planned.Reference) => ({\n  _tag: \"PlannedReference\",\n  node: reference.node,\n  path: reference.path\n})\n\n/** @private */\ntype ComparisonToken = string | symbol\n\n/**\n * Projects compared fields through the key's JSON semantics. A refused value\n * receives an identity token scoped to its node and field, so the same value\n * remains equal to itself without equating two distinct refused values.\n *\n * @private\n */\nconst fieldComparison = () => {\n  const refused = new Map<unknown, Map<string, symbol>>()\n  const token = (input: unknown, nodeId: string, field: string): ComparisonToken => {\n    try {\n      return stable(jsonMirror(input, plannedReference))\n    } catch {\n      const address = JSON.stringify([nodeId, field])\n      let fields = refused.get(input)\n      if (fields === undefined) {\n        fields = new Map()\n        refused.set(input, fields)\n      }\n      let sentinel = fields.get(address)\n      if (sentinel === undefined) {\n        sentinel = Symbol(address)\n        fields.set(address, sentinel)\n      }\n      return sentinel\n    }\n  }\n  return (previous: unknown, next: unknown, nodeId: string, field: string): boolean =>\n    token(previous, nodeId, field) === token(next, nodeId, field)\n}\n\n/** @private */\nconst changedFields = (\n  previous: Plan.PlanNode,\n  next: Plan.PlanNode,\n  rekeyedDependencies: ReadonlySet<string>,\n  sameField: ReturnType<typeof fieldComparison>\n): ReadonlyArray<string> => {\n  const changed: Array<string> = []\n  // StepKey.materialBody is the identity list this attribution must mirror.\n  // Inputs, layers, and capabilities complete fromKeyMaterial's hashed value,\n  // and material.kind selects the key namespace (content versus tier-bearing\n  // plan declaration), so a tier-only move still re-keys and is blamed here.\n  if (!sameField(previous.material.version, next.material.version, next.id, \"version\")) changed.push(\"version\")\n  if (previous.material.kind !== next.material.kind) changed.push(\"kind\")\n  if (!sameField(previous.material.body, next.material.body, next.id, \"body\")) changed.push(\"body\")\n  if (!sameField(previous.material.nondeterministic, next.material.nondeterministic, next.id, \"nondeterministic\")) {\n    changed.push(\"nondeterministic\")\n  }\n  if (!sameField(previous.material.effects, next.material.effects, next.id, \"effects\")) changed.push(\"effects\")\n  if (!sameField(previous.material.placement, next.material.placement, next.id, \"placement\")) {\n    changed.push(\"placement\")\n  }\n  const width = Math.max(previous.material.inputs.length, next.material.inputs.length)\n  for (let index = 0; index < width; index++) {\n    const before = previous.material.inputs[index]\n    const after = next.material.inputs[index]\n    const field = `input[${index}]`\n    if (before === undefined || after === undefined || !sameField(before, after, next.id, field)) {\n      changed.push(field)\n      continue\n    }\n    if (after._tag !== \"Literal\" && rekeyedDependencies.has(after.from)) changed.push(field)\n  }\n  if (!sameField(previous.material.layers, next.material.layers, next.id, \"layers\")) changed.push(\"layers\")\n  if (!sameField(previous.material.capabilities, next.material.capabilities, next.id, \"capabilities\")) {\n    changed.push(\"capabilities\")\n  }\n  return changed\n}\n\n/**\n * Compares a plan against the last plan for the same flow.\n *\n * @since 0.1.0\n * @category constructors\n * @slop\n */\nexport const diff = (previous: Plan.Plan, next: Plan.Plan): PlanDiff => {\n  const before = new Map(previous.nodes.map((node) => [node.id, node]))\n  const after = new Map(next.nodes.map((node) => [node.id, node]))\n  const rekeyedIds = new Set<string>()\n  for (const node of next.nodes) {\n    const original = before.get(node.id)\n    if (original !== undefined && original.key !== node.key) rekeyedIds.add(node.id)\n  }\n  const added: Array<string> = []\n  const rekeyed: Array<Rekeyed> = []\n  const unchanged: Array<string> = []\n  const sameField = fieldComparison()\n  for (const node of next.nodes) {\n    const original = before.get(node.id)\n    if (original === undefined) {\n      added.push(node.id)\n      continue\n    }\n    if (original.key === node.key) {\n      unchanged.push(node.id)\n      continue\n    }\n    rekeyed.push({\n      id: node.id,\n      from: original.key,\n      to: node.key,\n      changed: changedFields(original, node, rekeyedIds, sameField)\n    })\n  }\n  return {\n    added,\n    removed: previous.nodes.filter((node) => !after.has(node.id)).map((node) => node.id),\n    rekeyed,\n    unchanged\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/Planned.d.ts

@@ -0,0 +1,121 @@
+/**
+ * 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 type * as Types from "effect/Types";
+/**
+ * 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 declare const TypeId: unique symbol;
+/**
+ * The type-level form of {@link TypeId}.
+ *
+ * @since 0.1.0
+ * @category symbols
+ * @slop
+ */
+export type TypeId = typeof TypeId;
+/**
+ * What a planned value points at: the node that will produce the result, and
+ * the property path read from it. `path` is empty for the result itself.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export interface Reference {
+    readonly node: string;
+    readonly path: ReadonlyArray<string>;
+}
+/**
+ * A {@link Reference} plus the phantom type of the value it stands for, so
+ * `Planned<string>` and `Planned<number>` are not interchangeable.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export interface Identity<out T> extends Reference {
+    readonly _T: Types.Covariant<T>;
+}
+/**
+ * A step result that has not been produced yet.
+ *
+ * The brand rejects arithmetic and ordinary value arguments. The mapped half keeps field
+ * access typed — `result.files` is a `Planned` of the field, which is what
+ * makes "pass it on, never compute on it" expressible rather than merely
+ * documented.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export type Planned<T> = {
+    readonly [TypeId]: Identity<T>;
+} & ([T] extends [object] ? {
+    readonly [K in keyof T]: Planned<T[K]>;
+} : unknown);
+/**
+ * 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 declare const make: <T>(node: string) => Planned<T>;
+/**
+ * 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 declare const reference: (value: unknown) => Reference | undefined;
+/**
+ * Checks whether a value is a planned placeholder.
+ *
+ * @since 0.1.0
+ * @category guards
+ * @slop
+ */
+export declare const isPlanned: (value: unknown) => value is Planned<unknown>;
+//# sourceMappingURL=Planned.d.ts.map

package/dist/cjs/Planned.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Planned.d.ts","sourceRoot":"","sources":["../../src/Planned.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAG1C;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM,EAAE,OAAO,MAA2C,CAAA;AAEvE;;;;;;GAMG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAA;AAElC;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACrC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAE,SAAQ,SAAS;IAChD,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAA;CAChC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IACjB;IAAE,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;CAAE,GAClC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,OAAO,CAAC,CAAA;AAmEjF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,MAAM,MAAM,KAAG,OAAO,CAAC,CAAC,CAAkD,CAAA;AAalG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,SAAS,GAAG,SAItD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,OAAO,CAAC,OAAO,CAAmC,CAAA"}

package/dist/cjs/Planned.js

@@ -0,0 +1,72 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Planned_exports = {};
+__export(Planned_exports, {
+  TypeId: () => TypeId,
+  isPlanned: () => isPlanned,
+  make: () => make,
+  reference: () => reference
+});
+module.exports = __toCommonJS(Planned_exports);
+var import_GraphBuildError = require("./GraphBuildError.js");
+const TypeId = /* @__PURE__ */ Symbol.for("@smthrs/plan/Planned");
+const refusals = /* @__PURE__ */ new Map([
+  [Symbol.toPrimitive, "Symbol.toPrimitive"],
+  ["valueOf", "valueOf"],
+  ["toString", "toString"],
+  ["toJSON", "toJSON"]
+]);
+const describe = (reference2) => reference2.path.length === 0 ? reference2.node : `${reference2.node}.${reference2.path.join(".")}`;
+const refuse = (reference2, operation) => new import_GraphBuildError.GraphBuildError({
+  code: "planned_value_computed",
+  node: reference2.node,
+  path: reference2.path,
+  message: `Planned value ${describe(reference2)} was computed at plan time by ${operation}. Use Node.map to compute, Node.branch to decide, or pass the value into a payload.`
+});
+const placeholder = (reference2) => {
+  const target = () => void 0;
+  return new Proxy(target, {
+    get: (_target, key) => {
+      if (key === TypeId) return reference2;
+      const refusal = refusals.get(key);
+      if (refusal !== void 0) throw refuse(reference2, refusal);
+      if (key === "then") return void 0;
+      return placeholder({ node: reference2.node, path: [...reference2.path, String(key)] });
+    },
+    apply: () => {
+      throw refuse(reference2, "function application");
+    },
+    has: () => {
+      throw refuse(reference2, "property existence (`in`)");
+    },
+    ownKeys: () => {
+      throw refuse(reference2, "property enumeration");
+    }
+  });
+};
+const make = (node) => placeholder({ node, path: [] });
+const carrier = (value) => typeof value === "object" && value !== null || typeof value === "function";
+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");
+const reference = (value) => {
+  if (!carrier(value)) return void 0;
+  const candidate = value[TypeId];
+  return validReference(candidate) ? candidate : void 0;
+};
+const isPlanned = (value) => reference(value) !== void 0;
+//# sourceMappingURL=Planned.js.map

package/dist/cjs/Planned.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Planned.ts"],
+  "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** \u2014 into a payload field,\n * into a branch, into a map \u2014 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 \u2014 `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 \u2014 a branch arm, a continuation \u2014 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"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA8BA,6BAAgC;AAYzB,MAAM,SAAwB,uBAAO,IAAI,sBAAsB;AA2DtE,MAAM,WAAW,oBAAI,IAAyB;AAAA,EAC5C,CAAC,OAAO,aAAa,oBAAoB;AAAA,EACzC,CAAC,WAAW,SAAS;AAAA,EACrB,CAAC,YAAY,UAAU;AAAA,EACvB,CAAC,UAAU,QAAQ;AACrB,CAAC;AAGD,MAAM,WAAW,CAACA,eAChBA,WAAU,KAAK,WAAW,IAAIA,WAAU,OAAO,GAAGA,WAAU,IAAI,IAAIA,WAAU,KAAK,KAAK,GAAG,CAAC;AAS9F,MAAM,SAAS,CAACA,YAAsB,cACpC,IAAI,uCAAgB;AAAA,EAClB,MAAM;AAAA,EACN,MAAMA,WAAU;AAAA,EAChB,MAAMA,WAAU;AAAA,EAChB,SAAS,iBAAiB,SAASA,UAAS,CAAC,iCAAiC,SAAS;AAEzF,CAAC;AAQH,MAAM,cAAc,CAACA,eAAkC;AAErD,QAAM,SAAS,MAAiB;AAChC,SAAO,IAAI,MAAM,QAAQ;AAAA,IACvB,KAAK,CAAC,SAAS,QAAQ;AACrB,UAAI,QAAQ,OAAQ,QAAOA;AAC3B,YAAM,UAAU,SAAS,IAAI,GAAG;AAChC,UAAI,YAAY,OAAW,OAAM,OAAOA,YAAW,OAAO;AAG1D,UAAI,QAAQ,OAAQ,QAAO;AAC3B,aAAO,YAAY,EAAE,MAAMA,WAAU,MAAM,MAAM,CAAC,GAAGA,WAAU,MAAM,OAAO,GAAG,CAAC,EAAE,CAAC;AAAA,IACrF;AAAA,IACA,OAAO,MAAM;AACX,YAAM,OAAOA,YAAW,sBAAsB;AAAA,IAChD;AAAA,IACA,KAAK,MAAM;AACT,YAAM,OAAOA,YAAW,2BAA2B;AAAA,IACrD;AAAA,IACA,SAAS,MAAM;AACb,YAAM,OAAOA,YAAW,sBAAsB;AAAA,IAChD;AAAA,EACF,CAAC;AACH;AAaO,MAAM,OAAO,CAAI,SAA6B,YAAY,EAAE,MAAM,MAAM,CAAC,EAAE,CAAC;AAGnF,MAAM,UAAU,CAAC,UACd,OAAO,UAAU,YAAY,UAAU,QAAS,OAAO,UAAU;AAGpE,MAAM,iBAAiB,CAAC,UACtB,OAAO,UAAU,YAAY,UAAU,QACvC,OAAQ,MAAoB,SAAS,YAAa,MAAoB,KAAK,SAAS,KACpF,MAAM,QAAS,MAAoB,IAAI,KACvC,MAAM,KAAM,MAAoB,IAAI,EAAE,MAAM,CAAC,YAAY,OAAO,YAAY,QAAQ;AAa/E,MAAM,YAAY,CAAC,UAA0C;AAClE,MAAI,CAAC,QAAQ,KAAK,EAAG,QAAO;AAC5B,QAAM,YAAY,MAAM,MAAM;AAC9B,SAAO,eAAe,SAAS,IAAI,YAAY;AACjD;AASO,MAAM,YAAY,CAAC,UAA8C,UAAU,KAAK,MAAM;",
+  "names": ["reference"]
+}

package/dist/cjs/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/cjs/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/cjs/Repetition.js

@@ -0,0 +1,36 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Repetition_exports = {};
+__export(Repetition_exports, {
+  AtCeiling: () => AtCeiling
+});
+module.exports = __toCommonJS(Repetition_exports);
+var Schema = __toESM(require("effect/Schema"), 1);
+const AtCeiling = Schema.Literals(["fail", "return-last"]);
+//# sourceMappingURL=Repetition.js.map

package/dist/cjs/Repetition.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Repetition.ts"],
+  "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"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAcA,aAAwB;AAUjB,MAAM,YAAY,OAAO,SAAS,CAAC,QAAQ,aAAa,CAAC;",
+  "names": []
+}

package/dist/cjs/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/cjs/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/cjs/Scheduling.js

@@ -0,0 +1,76 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Scheduling_exports = {};
+__export(Scheduling_exports, {
+  make: () => make
+});
+module.exports = __toCommonJS(Scheduling_exports);
+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;
+};
+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 = /* @__PURE__ */ new Set();
+    const positions = /* @__PURE__ */ 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