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

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

package/dist/cjs/Scheduling.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Scheduling.ts"],
+  "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"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAoFA,MAAM,UAAU,CAAC,MAAc,OAAe,YAA4B;AACxE,MAAI,CAAC,OAAO,cAAc,KAAK,KAAK,QAAQ,SAAS;AACnD,UAAM,IAAI,WAAW,GAAG,IAAI,cAAc,YAAY,IAAI,aAAa,cAAc,eAAe;AAAA,EACtG;AACA,SAAO;AACT;AAeO,MAAM,OAAO,CAAC,cAA2B,CAAC,MAAc;AAC7D,QAAM,SAAS,OAAO,OAAO;AAAA,IAC3B,OAAO,QAAQ,qBAAqB,YAAY,SAAS,OAAO,kBAAkB,CAAC;AAAA,IACnF,QAAQ,QAAQ,sBAAsB,YAAY,UAAU,OAAO,kBAAkB,CAAC;AAAA,EACxF,CAAC;AACD,QAAM,QAAyB,CAAC,OAAO,WAAW;AAChD,YAAQ,gBAAgB,OAAO,OAAO,CAAC;AACvC,YAAQ,iBAAiB,OAAO,QAAQ,CAAC;AACzC,QAAI,OAAO,SAAS,OAAO,MAAO,OAAM,IAAI,WAAW,0CAA0C;AACjG,UAAM,MAAM,oBAAI,IAAY;AAC5B,UAAM,YAAY,oBAAI,IAAY;AAClC,UAAM,SAAS,MAAM,IAAI,CAAC,cAAc;AACtC,YAAM,EAAE,MAAM,OAAO,OAAO,IAAI;AAChC,cAAQ,mBAAmB,OAAO,CAAC;AACnC,cAAQ,oBAAoB,QAAQ,CAAC;AACrC,UAAI,CAAC,OAAO,cAAc,KAAK,QAAQ,EAAG,OAAM,IAAI,WAAW,2CAA2C;AAC1G,UAAI,KAAK,SAAS,UAAU,KAAK,SAAS,WAAW,KAAK,SAAS,SAAS;AAC1E,cAAM,IAAI,WAAW,wBAAwB;AAAA,MAC/C;AACA,UAAI,OAAO,KAAK,OAAO,YAAY,KAAK,OAAO,MAAM,IAAI,IAAI,KAAK,EAAE,GAAG;AACrE,cAAM,IAAI,WAAW,4CAA4C;AAAA,MACnE;AACA,UAAI,UAAU,IAAI,KAAK,EAAG,OAAM,IAAI,WAAW,yCAAyC;AACxF,UAAI,IAAI,KAAK,EAAE;AACf,gBAAU,IAAI,KAAK;AACnB,aAAO,EAAE,WAAW,UAAU,OAAO,KAAK,QAAQ,IAAI,OAAO,MAAM,EAAE;AAAA,IACvE,CAAC;AACD,WAAO;AAAA,MAAK,CAAC,MAAM,UACjB,KAAK,aAAa,MAAM,WACpB,KAAK,UAAU,QAAQ,MAAM,UAAU,QACvC,KAAK,WAAW,MAAM,WACtB,KACA;AAAA,IACN;AACA,UAAM,WAAwC,CAAC;AAC/C,UAAM,WAAwC,CAAC;AAC/C,QAAI,SAAS;AACb,eAAW,EAAE,UAAU,KAAK,QAAQ;AAClC,YAAM,UAAU,UAAU,KAAK,SAAS;AACxC,UAAI,SAAS,UAAU,OAAO,QAAQ,OAAO,SAAU,WAAW,UAAU,OAAO,SAAS,OAAO,QAAS;AAC1G,iBAAS,KAAK,OAAO,OAAO,EAAE,GAAG,WAAW,QAAQ,KAAK,IAAI,OAAO,kBAAkB,UAAU,SAAS,CAAC,EAAE,CAAC,CAAC;AAAA,MAChH,OAAO;AACL,iBAAS,KAAK,OAAO,OAAO,EAAE,GAAG,UAAU,CAAC,CAAC;AAC7C,YAAI,QAAS;AAAA,MACf;AAAA,IACF;AACA,WAAO,OAAO,OAAO,EAAE,UAAU,OAAO,OAAO,QAAQ,GAAG,UAAU,OAAO,OAAO,QAAQ,GAAG,OAAO,CAAC;AAAA,EACvG;AACA,SAAO,OAAO,OAAO,EAAE,QAAQ,MAAM,CAAC;AACxC;",
+  "names": []
+}

package/dist/cjs/StepKey.d.ts

@@ -0,0 +1,354 @@
+/**
+ * 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://github.com/smithersai/smithers/blob/main/packages/smithers/flows/plan/docs/concepts/step-keys.md.
+ *
+ * @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
+ */
+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
+ */
+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.
+ *
+ * @param digest - The precomputed digest.
+ * @param reference - Which graph reference resolved to the digest, and the
+ *   projection path for `ref-projected`. Omit for a plain digest.
+ * @returns The tagged digest input.
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const digestInput: (digest: string, reference?: {
+    readonly reference: GraphReference;
+    readonly path?: ReadonlyArray<string>;
+}) => DigestInput;
+/**
+ * Type guard for values produced by {@link digestInput}. A plain object
+ * shaped like `{ digest: "..." }` is not one.
+ *
+ * @param value - Any value.
+ * @returns `true` only for a value carrying the private digest-input brand.
+ * @since 0.1.0
+ * @category guards
+ */
+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
+ */
+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.
+ *
+ * `digest(from, path, compute)` runs `compute` once per address and shares its
+ * result with concurrent callers. A failed or interrupted computation is not
+ * kept: the next caller recomputes, and a waiter whose leader was interrupted
+ * becomes the new leader instead of inheriting the interrupt.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+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.
+ *
+ * @returns A memo with no entries.
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const makeDigestMemo: () => DigestMemo;
+/**
+ * Material describing a sealed or hermetic content-addressed step.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+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
+ */
+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 deriving a key. `code` names the rule:
+ *
+ * - `invalid_environment`: an {@link EnvironmentIdentity} that is neither
+ *   declared nor run-scoped.
+ * - `missing_dependency`: a `Ref` or `Pending` input names a node with no
+ *   recorded digest, or, at dispatch, a `Ref` names one with no settled
+ *   result.
+ * - `non_content_material`: a content-key constructor received material whose
+ *   tier is not `sealed`.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+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.
+ *
+ * @param identity - The step's content material.
+ * @returns The content key. Fails with `invalid_environment` for a malformed
+ * environment, or `SchemaError` when the material cannot be serialized.
+ * @since 0.1.0
+ * @category constructors
+ */
+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.
+ *
+ * @param identity - The run id, optional parent scope, ordinal, and tier.
+ * @returns The ordinal key.
+ * @since 0.1.0
+ * @category constructors
+ */
+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.
+ *
+ * @param material - The node's key material; its tier must be `sealed`.
+ * @param dependencyDigests - The key of every node the material references,
+ *   by node id.
+ * @returns The content key. Fails with `non_content_material` for a
+ * non-sealed tier and `missing_dependency` for an unresolved reference.
+ * @since 0.1.0
+ * @category constructors
+ */
+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
+ */
+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.
+ *
+ * @param options - The material, the dependencies' settled results, the
+ *   measured hermetic boundary, and an optional environment and memo.
+ * @returns The dispatch key. Fails with `non_content_material` for a
+ * non-sealed tier, `missing_dependency` for a `Ref` absent from `results`,
+ * or `invalid_environment` for a malformed environment.
+ * @since 0.1.0
+ * @category constructors
+ */
+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/cjs/StepKey.d.ts.map

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