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

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"]}

package/dist/esm/StepKey.d.ts

@@ -0,0 +1,333 @@
+/**
+ * The KeyMaterial → step-key compiler.
+ *
+ * Revived from the deleted `packages/smithers/flows/keys/src/StepKey.ts`. Two
+ * deliberate deviations from the original:
+ *
+ * 1. **It lives here, not in `@smthrs/keys`.** That package owns generic
+ *    derivation and stored-key validation; a compiler that understands plan
+ *    material belongs above it.
+ * 2. **It produces `@smthrs/keys` `StoredKey` values, not a second `sk1_` digest
+ *    format.** The original minted its own prefix over a private `Digest`
+ *    module. The engine dispatches under `StoredKey` (`FlowEngine/ActionKey.ts`),
+ *    so a plan whose node keys were a *different* string format could never be
+ *    the thing the cache is consulted against, and that is the whole point of
+ *    a `Plan`. One key format, one hashing
+ *    chokepoint (canonical JSON + injected `Crypto`), one namespace field
+ *    (`kind`) distinguishing content keys from ordinal ones.
+ *
+ * Everything the original earned is kept: nominally branded digest inputs (a
+ * literal that merely *looks* like `{digest}` hashes as a literal), set
+ * normalization, the separate environment namespace, per-variant tagging of
+ * resolved references, and the hashed `version`.
+ *
+ * Governing contract: the step-key rules at
+ * https://smithers.sh/docs/concepts/content-addressing.
+ *
+ * @since 0.1.0
+ */
+import { type StoredKey } from "@smthrs/keys";
+import * as Cause from "effect/Cause";
+import type * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type * as FileSet from "./FileSet.ts";
+import type * as KeyMaterial from "./KeyMaterial.ts";
+/**
+ * A computed step key. Identical in representation to any other flow key —
+ * `key1_` plus a SHA-256 digest of the canonical serialization of the material.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export type StepKey = StoredKey;
+/**
+ * The nominal brand carried by every {@link DigestInput}. Kept private: the
+ * only way to produce a value bearing it is {@link digestInput}, so a plain
+ * value that merely happens to look like `{ digest: "..." }` — actions pass
+ * content hashes around as ordinary data — can never be mistaken for a genuine
+ * upstream-result digest reference. This closes a step-key collision where
+ * shape-sniffing (`"digest" in value`) hashed the two identically.
+ *
+ * @since 0.1.0
+ * @category symbols
+ */
+declare const DigestInputTypeId: unique symbol;
+/**
+ * Which kind of graph reference a {@link DigestInput} stands for. Declared
+ * once here so the field on `DigestInput` and the parameter of
+ * {@link digestInput} name one set and cannot drift apart.
+ */
+type GraphReference = "ref" | "pending" | "ref-projected";
+/**
+ * A precomputed digest supplied as a step input rather than a literal value.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export interface DigestInput {
+    readonly [DigestInputTypeId]: typeof DigestInputTypeId;
+    readonly digest: string;
+    /**
+     * Which kind of graph reference resolved to this digest.
+     *
+     * Carrying the discriminator on the digest input keeps `normalizeInputs` the
+     * single normalizer: it wraps every variant once, and the variants stay
+     * mutually distinct because they differ in this field rather than in a
+     * hand-built object a second wrap would hide.
+     */
+    readonly reference?: GraphReference;
+    /** The projection applied to the referenced result, for `ref-projected`. */
+    readonly path?: ReadonlyArray<string>;
+}
+/**
+ * Nominally tags a precomputed digest so it is hashed as a digest reference
+ * rather than a literal value.
+ *
+ * @since 0.1.0
+ * @category constructors
+ * @slop
+ */
+export declare const digestInput: (digest: string, reference?: {
+    readonly reference: GraphReference;
+    readonly path?: ReadonlyArray<string>;
+}) => DigestInput;
+/**
+ * Type guard for values produced by {@link digestInput}.
+ *
+ * @since 0.1.0
+ * @category guards
+ * @slop
+ */
+export declare const isDigestInput: (value: unknown) => value is DigestInput;
+/**
+ * The engine-resolved execution environment a content key is computed under,
+ * hashed in its OWN namespace rather than merged into the caller's `layers`
+ * and `capabilities`.
+ *
+ * Three properties matter and none survives a merge:
+ *
+ * 1. **Non-aliasing.** Concatenating environment material onto the caller's
+ *    made `caller{fs:["a"]} + env{fs:["b"]}` hash identically to
+ *    `caller{fs:["a","b"]} + env{}` — a cross-run collision in the very
+ *    material whose purpose is preventing one.
+ * 2. **Declared vs undeclared.** `declared: false` is not the same value as
+ *    `declared: true` with empty sets.
+ * 3. **Composition order.** Environment layers retain declaration order,
+ *    because plugin and service composition order can change behavior. The
+ *    caller-owned `ContentIdentity.layers` stays set-normalized.
+ *
+ * `runScope` is set only when `declared` is `false`: it pins the key to one
+ * run, so a step whose environment identity is unknown can never serve a
+ * cross-run hit. The union enforces this for typed callers; both
+ * {@link content} and {@link dispatchIdentity} validate it at run time.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export type EnvironmentIdentity = typeof EnvironmentIdentity.Type;
+/**
+ * Validated, copyable runtime environment identity. Layer order matters;
+ * capability patterns are set-like. Unknown fields are not identity material.
+ * @since 1.0.0
+ * @category schemas
+ */
+export declare const EnvironmentIdentity: Schema.Union<readonly [Schema.Struct<{
+    readonly declared: Schema.Literal<true>;
+    readonly layers: Schema.$Array<Schema.String>;
+    readonly capabilities: Schema.$Record<Schema.String, Schema.$Array<Schema.String>>;
+    readonly runScope: Schema.optionalKey<Schema.Undefined>;
+}>, Schema.Struct<{
+    readonly declared: Schema.Literal<false>;
+    readonly layers: Schema.$Array<Schema.String>;
+    readonly capabilities: Schema.$Record<Schema.String, Schema.$Array<Schema.String>>;
+    readonly runScope: Schema.NonEmptyString;
+}>]>;
+/**
+ * Caller-owned memoization context for projected dependency-value digests.
+ *
+ * This is the flows counterpart of Bazel's `ActionKeyContext`: one context is
+ * passed through related key computations so shared input material is hashed
+ * once. Concurrent requests for the same projection share the in-flight
+ * digest. Entries are sound only while each settled `from` value is immutable;
+ * callers must create a fresh memo when those values can change.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export interface DigestMemo {
+    readonly digest: (from: string, path: ReadonlyArray<string>, compute: Effect.Effect<StepKey, Schema.SchemaError, Crypto.Crypto>) => Effect.Effect<StepKey, Schema.SchemaError, Crypto.Crypto>;
+}
+/**
+ * Creates an empty projected-value digest memo. Projection addresses are
+ * JSON-encoded `[from, path]` tuples so segment boundaries are unambiguous.
+ *
+ * @since 0.1.0
+ * @category constructors
+ * @slop
+ */
+export declare const makeDigestMemo: () => DigestMemo;
+/**
+ * Material describing a sealed or hermetic content-addressed step.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export interface ContentIdentity {
+    readonly body: unknown;
+    readonly inputs: Readonly<Record<string, unknown | DigestInput>>;
+    readonly layers: ReadonlyArray<string>;
+    readonly capabilities: Readonly<Record<string, ReadonlyArray<string>>>;
+    readonly environment?: EnvironmentIdentity | undefined;
+    readonly hermetic?: {
+        readonly readSet: ReadonlyArray<{
+            readonly path: string;
+            readonly digest: string;
+        }>;
+        readonly writeSet: ReadonlyArray<FileSet.Entry>;
+        readonly removes?: ReadonlyArray<string> | undefined;
+        readonly boundaryMode: FileSet.BoundaryMode;
+    } | undefined;
+}
+/**
+ * Material describing the run-local identity of a non-cacheable step.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export interface OrdinalIdentity {
+    readonly runId: string;
+    readonly parentScope?: string | undefined;
+    readonly ordinal: number;
+    readonly tier: "compensable" | "irreversible" | "unsealed";
+}
+declare const KeyMaterialError_base: Schema.Class<KeyMaterialError, Schema.TaggedStruct<"@smthrs/plan/KeyMaterialError", {
+    readonly code: Schema.Literals<readonly ["invalid_environment", "missing_dependency", "non_content_material"]>;
+    readonly message: Schema.String;
+}>, Cause.YieldableError>;
+/**
+ * Stable failures while resolving graph-local dependency references.
+ *
+ * @since 0.1.0
+ * @category errors
+ * @slop
+ */
+export declare class KeyMaterialError extends KeyMaterialError_base {
+}
+/**
+ * Fingerprint for binding one execution to its runtime environment, not an
+ * action dispatch key. Uses the same normalization as content/dispatch keys.
+ * An omitted environment is distinct from declared-empty and run-scoped ones.
+ * @since 1.0.0
+ * @category constructors
+ */
+export declare const environmentIdentity: (environment?: EnvironmentIdentity) => Effect.Effect<StoredKey, KeyMaterialError | Schema.SchemaError, Crypto.Crypto>;
+/**
+ * Produces a cross-run reusable key for a sealed or hermetic step. Set-like
+ * declarations are normalized before serialization; write declarations remain
+ * part of the identity even when the step writes nothing.
+ *
+ * @since 0.1.0
+ * @category constructors
+ * @slop
+ */
+export declare const content: (identity: ContentIdentity) => Effect.Effect<StepKey, KeyMaterialError | Schema.SchemaError, Crypto.Crypto>;
+/**
+ * Produces a run-local ordinal key for compensable, irreversible, or unsealed
+ * work. These keys intentionally cannot be reused across runs.
+ *
+ * @since 0.1.0
+ * @category constructors
+ * @slop
+ */
+export declare const ordinal: (identity: OrdinalIdentity) => Effect.Effect<StepKey, Schema.SchemaError, Crypto.Crypto>;
+/**
+ * Resolves graph-local references to dependency digests and constructs a
+ * sealed content key. Use {@link planIdentity} to compile any effect tier.
+ *
+ * This is the handoff the Flow Builder Brief describes: the planner hands over
+ * a topologically ordered sequence of `{ nodeId, material }`, and for each one
+ * the compiler substitutes every `Ref`/`Pending` with the *already computed
+ * key of the referenced node*. Structural node ids are lookup addresses only
+ * and never enter the hashed value — rename a node and nothing re-keys; change
+ * what a node consumes and everything downstream of it does.
+ *
+ * @since 0.1.0
+ * @category constructors
+ * @slop
+ */
+export declare const fromKeyMaterial: (material: KeyMaterial.KeyMaterial, dependencyDigests: Readonly<Record<string, string>>) => Effect.Effect<StepKey, KeyMaterialError | Schema.SchemaError, Crypto.Crypto>;
+/**
+ * Identifies a declaration in a plan, independently of whether its execution
+ * can be cached. Sealed material retains its existing content-key format;
+ * compensable and irreversible material use a distinct, tier-bearing plan
+ * namespace. These fingerprints bind approvals, not cross-run result reuse.
+ * Dispatch non-cacheable work under a run-local {@link ordinal} instead.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export declare const planIdentity: (material: KeyMaterial.KeyMaterial, dependencyDigests: Readonly<Record<string, string>>) => Effect.Effect<StepKey, KeyMaterialError | Schema.SchemaError, Crypto.Crypto>;
+/**
+ * Projects a settled result along a `Ref` path. Only own data properties
+ * resolve, so a missing, inherited, or accessor segment yields `undefined`
+ * without invoking a getter. This is a stable, distinct value: a projection that
+ * walks off the end of a result is a fact about the graph, not a failure.
+ * `undefined` drops out of the canonical form, so it hashes distinctly from
+ * every JSON value including `null`.
+ *
+ * Exported because it is the ONE projection semantics for the value channel:
+ * {@link dispatchIdentity} digests what this returns, so every consumer that
+ * resolves a `Ref` at execution time must resolve it the same way, or two
+ * inputs that key identically could be consumed differently — a stale-hit
+ * vector.
+ *
+ * @since 0.1.0
+ * @category utilities
+ * @slop
+ */
+export declare const project: (value: unknown, path: ReadonlyArray<string>) => unknown;
+/**
+ * The key a dispatch is *cached* under, as distinct from the plan key a node
+ * is *identified* by.
+ *
+ * A plan key folds the resolved keys of every upstream node, transitively, so
+ * an edit anywhere upstream re-keys everything below it — even when the edited
+ * node's output value is byte for byte what it was before. Bazel does not work
+ * that way: `ActionCacheChecker` keys an action by the *content* of its
+ * inputs, so an unchanged output stops invalidation dead. The file channel in
+ * flows already had that property through the measured boundary digests; the
+ * JSON value channel did not, and this is what gives it one.
+ *
+ * The derivation folds the node's OWN material — body, version, effects,
+ * placement, layers, capabilities — and never an upstream key. Each material
+ * input contributes content instead: a `Literal` its value, a `Ref` the digest
+ * of the settled result of `from` projected along `path`, and a `Pending`
+ * nothing beyond its tag. The measured hermetic boundary is folded unchanged.
+ *
+ * `results` must hold every dependency the material names. The scheduler's
+ * halt rule guarantees it: a dependent of failed or skipped work never
+ * dispatches, so a `Ref` always resolves against a success.
+ *
+ * @since 0.1.0
+ * @category constructors
+ * @slop
+ */
+export declare const dispatchIdentity: (options: {
+    readonly material: KeyMaterial.KeyMaterial;
+    /** The settled output value of each dependency, by node id. */
+    readonly results: Readonly<Record<string, unknown>>;
+    readonly hermetic: NonNullable<ContentIdentity["hermetic"]>;
+    /** The engine-resolved execution environment this dispatch runs under. */
+    readonly environment?: EnvironmentIdentity | undefined;
+    /** Reuses projected-value digests while the corresponding settled values remain immutable. */
+    readonly digestMemo?: DigestMemo | undefined;
+}) => Effect.Effect<StepKey, KeyMaterialError | Schema.SchemaError, Crypto.Crypto>;
+export {};
+//# sourceMappingURL=StepKey.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StepKey.d.ts","sourceRoot":"","sources":["../../src/StepKey.ts"],"names":[],"mappings":"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"}