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

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,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/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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"}

package/dist/cjs/StepKey.js

@@ -0,0 +1,311 @@
+"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 StepKey_exports = {};
+__export(StepKey_exports, {
+  EnvironmentIdentity: () => EnvironmentIdentity,
+  KeyMaterialError: () => KeyMaterialError,
+  content: () => content,
+  digestInput: () => digestInput,
+  dispatchIdentity: () => dispatchIdentity,
+  environmentIdentity: () => environmentIdentity,
+  fromKeyMaterial: () => fromKeyMaterial,
+  isDigestInput: () => isDigestInput,
+  makeDigestMemo: () => makeDigestMemo,
+  ordinal: () => ordinal,
+  planIdentity: () => planIdentity,
+  project: () => project
+});
+module.exports = __toCommonJS(StepKey_exports);
+var import_keys = require("@smthrs/keys");
+var Cause = __toESM(require("effect/Cause"), 1);
+var Deferred = __toESM(require("effect/Deferred"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Exit = __toESM(require("effect/Exit"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+const DigestInputTypeId = /* @__PURE__ */ Symbol.for("@smthrs/plan/StepKey/DigestInput");
+const digestInput = (digest, reference) => ({
+  [DigestInputTypeId]: DigestInputTypeId,
+  digest,
+  ...reference === void 0 ? {} : { reference: reference.reference },
+  ...reference?.path === void 0 ? {} : { path: reference.path }
+});
+const isDigestInput = (value) => typeof value === "object" && value !== null && DigestInputTypeId in value && value[DigestInputTypeId] === DigestInputTypeId;
+const EnvironmentIdentity = Schema.Union([
+  Schema.Struct({
+    declared: Schema.Literal(true),
+    layers: Schema.Array(Schema.String),
+    capabilities: Schema.Record(Schema.String, Schema.Array(Schema.String)),
+    runScope: Schema.optionalKey(Schema.Undefined)
+  }),
+  Schema.Struct({
+    declared: Schema.Literal(false),
+    layers: Schema.Array(Schema.String),
+    capabilities: Schema.Record(Schema.String, Schema.Array(Schema.String)),
+    runScope: Schema.NonEmptyString
+  })
+]);
+const makeDigestMemo = () => {
+  const entries = /* @__PURE__ */ new Map();
+  const digest = (from, path, compute) => Effect.suspend(() => {
+    const address = JSON.stringify([from, path]);
+    const existing = entries.get(address);
+    if (existing !== void 0) {
+      return Effect.flatMap(Effect.exit(Deferred.await(existing)), (exit) => {
+        if (Exit.isSuccess(exit)) return Effect.succeed(exit.value);
+        return Cause.hasInterrupts(exit.cause) ? digest(from, path, compute) : Effect.failCause(exit.cause);
+      });
+    }
+    const pending = Deferred.makeUnsafe();
+    entries.set(address, pending);
+    return compute.pipe(
+      Effect.onExit(
+        (exit) => Effect.gen(function* () {
+          if (Exit.isFailure(exit) && entries.get(address) === pending) {
+            entries.delete(address);
+          }
+          yield* Deferred.done(pending, exit);
+        })
+      )
+    );
+  });
+  return { digest };
+};
+class KeyMaterialError extends Schema.TaggedError()("@smthrs/plan/KeyMaterialError", {
+  code: Schema.Literals(["invalid_environment", "missing_dependency", "non_content_material"]),
+  message: Schema.String
+}) {
+}
+const validateEnvironment = (environment) => {
+  const candidate = environment;
+  if (candidate.declared === false) {
+    if (typeof candidate.runScope !== "string" || candidate.runScope.length === 0) {
+      return new KeyMaterialError({
+        code: "invalid_environment",
+        message: "Undeclared environment identity requires a non-empty runScope"
+      });
+    }
+    return void 0;
+  }
+  if (candidate.declared === true) {
+    return candidate.runScope === void 0 ? void 0 : new KeyMaterialError({
+      code: "invalid_environment",
+      message: "Declared environment identity must not include runScope"
+    });
+  }
+  return new KeyMaterialError({
+    code: "invalid_environment",
+    message: "Environment identity requires a boolean declared field"
+  });
+};
+const decodeEnvironment = (environment) => Effect.try({
+  try: () => {
+    const invalid = validateEnvironment(environment);
+    if (invalid !== void 0) throw invalid;
+    return Schema.decodeUnknownSync(EnvironmentIdentity)(environment, { onExcessProperty: "error" });
+  },
+  catch: (cause) => cause instanceof KeyMaterialError ? cause : new KeyMaterialError({
+    code: "invalid_environment",
+    message: "Environment identity must contain only its declared fields, string layers, and string capability patterns"
+  })
+});
+const sortStrings = (values) => [...new Set(values.map((value) => value.normalize("NFC")))].sort();
+const normalizeInputs = (inputs) => Object.fromEntries(
+  Object.entries(inputs).map(([name, value]) => [
+    name,
+    isDigestInput(value) ? {
+      kind: "digest",
+      digest: value.digest,
+      ...value.reference === void 0 ? {} : { reference: value.reference },
+      ...value.path === void 0 ? {} : { path: value.path }
+    } : { kind: "literal", value }
+  ])
+);
+const normalizeCapabilities = (capabilities) => Object.fromEntries(Object.entries(capabilities).map(([group, patterns]) => [group, sortStrings(patterns)]));
+const normalizeEnvironment = (environment) => ({
+  declared: environment.declared,
+  layers: environment.layers.map((layer) => layer.normalize("NFC")),
+  capabilities: normalizeCapabilities(environment.capabilities),
+  ...environment.runScope === void 0 ? {} : { runScope: environment.runScope }
+});
+const compareCodeUnits = (left, right) => left < right ? -1 : 1;
+const writeEntryKey = (entry) => typeof entry === "string" ? JSON.stringify(["Path", entry]) : entry._tag === "TreeArtifact" ? JSON.stringify([entry._tag, entry.path]) : JSON.stringify([entry._tag, entry.include, entry.exclude ?? null]);
+const normalizeHermetic = (hermetic) => {
+  const readSet = [...hermetic.readSet].map((entry) => ({ path: entry.path.normalize("NFC"), digest: entry.digest })).sort((left, right) => {
+    if (left.path !== right.path) return left.path < right.path ? -1 : 1;
+    return left.digest < right.digest ? -1 : left.digest > right.digest ? 1 : 0;
+  }).filter(
+    (entry, index, entries) => index === 0 || entry.path !== entries[index - 1].path || entry.digest !== entries[index - 1].digest
+  );
+  const normalizedWrites = [...hermetic.writeSet].map((entry) => {
+    if (typeof entry === "string") return entry.normalize("NFC");
+    if (entry._tag === "TreeArtifact") return { ...entry, path: entry.path.normalize("NFC") };
+    return {
+      ...entry,
+      include: sortStrings(entry.include),
+      ...entry.exclude === void 0 ? {} : { exclude: sortStrings(entry.exclude) }
+    };
+  });
+  const writeSet = [...new Map(normalizedWrites.map((entry) => [writeEntryKey(entry), entry])).entries()].sort(([left], [right]) => compareCodeUnits(left, right)).map(([, entry]) => entry);
+  return {
+    readSet,
+    writeSet,
+    ...hermetic.removes === void 0 ? {} : { removes: sortStrings(hermetic.removes) },
+    boundaryMode: hermetic.boundaryMode
+  };
+};
+const decodeKey = Schema.decodeUnknownEffect(import_keys.DerivedKey);
+const environmentIdentity = (environment) => Effect.gen(function* () {
+  const captured = environment === void 0 ? void 0 : yield* decodeEnvironment(environment);
+  return yield* decodeKey({
+    kind: "execution-environment/v1",
+    environment: captured === void 0 ? null : normalizeEnvironment(captured)
+  });
+});
+const content = (identity) => Effect.gen(function* () {
+  const environment = identity.environment === void 0 ? void 0 : yield* decodeEnvironment(identity.environment);
+  return yield* decodeKey({
+    kind: "content",
+    body: identity.body,
+    inputs: normalizeInputs(identity.inputs),
+    layers: sortStrings(identity.layers),
+    capabilities: normalizeCapabilities(identity.capabilities),
+    ...environment === void 0 ? {} : { environment: normalizeEnvironment(environment) },
+    ...identity.hermetic === void 0 ? {} : { hermetic: normalizeHermetic(identity.hermetic) }
+  });
+});
+const ordinal = (identity) => decodeKey({ kind: "ordinal", ...identity });
+const fromKeyMaterial = (material, dependencyDigests) => {
+  if (material.kind !== "sealed") {
+    return Effect.fail(
+      new KeyMaterialError({
+        code: "non_content_material",
+        message: `Cannot create a content key for ${material.kind} material`
+      })
+    );
+  }
+  return materialIdentity(material, dependencyDigests).pipe(Effect.flatMap(content));
+};
+const planIdentity = (material, dependencyDigests) => material.kind === "sealed" ? fromKeyMaterial(material, dependencyDigests) : materialIdentity(material, dependencyDigests).pipe(Effect.flatMap(
+  (identity) => decodeKey({
+    kind: "plan-declaration",
+    tier: material.kind,
+    body: identity.body,
+    inputs: normalizeInputs(identity.inputs),
+    layers: sortStrings(identity.layers),
+    capabilities: normalizeCapabilities(identity.capabilities)
+  })
+));
+const ownDataProperty = (record, from, label) => {
+  const descriptor = Object.getOwnPropertyDescriptor(record, from);
+  if (descriptor === void 0) {
+    return Effect.fail(
+      new KeyMaterialError({
+        code: "missing_dependency",
+        message: `Missing ${label.toLowerCase()} for graph dependency ${from}`
+      })
+    );
+  }
+  if (!("value" in descriptor)) {
+    return Effect.fail(
+      new KeyMaterialError({
+        code: "missing_dependency",
+        message: `${label} for graph dependency ${from} must be a data property`
+      })
+    );
+  }
+  return Effect.succeed(descriptor.value);
+};
+const resolveInputs = (material, resolve) => Effect.gen(function* () {
+  const inputs = {};
+  for (let index = 0; index < material.inputs.length; index++) {
+    const input = material.inputs[index];
+    if (input._tag === "Literal") {
+      inputs[String(index)] = input.value;
+      continue;
+    }
+    const digest = yield* resolve(input);
+    inputs[String(index)] = input._tag === "Pending" ? digestInput(digest, { reference: "pending" }) : input.path.length > 0 ? digestInput(digest, { reference: "ref-projected", path: input.path }) : digestInput(digest, { reference: "ref" });
+  }
+  return inputs;
+});
+const materialIdentity = (material, dependencyDigests) => resolveInputs(
+  material,
+  (reference) => Effect.flatMap(ownDataProperty(dependencyDigests, reference.from, "Digest"), (digest) => typeof digest === "string" ? Effect.succeed(digest) : Effect.fail(
+    new KeyMaterialError({
+      code: "missing_dependency",
+      message: `Digest for graph dependency ${reference.from} must be a string`
+    })
+  ))
+).pipe(Effect.map((inputs) => ({
+  body: materialBody(material),
+  inputs,
+  layers: material.layers,
+  capabilities: { declared: material.capabilities }
+})));
+const materialBody = (material) => ({
+  version: material.version,
+  declaration: material.body,
+  ...material.nondeterministic === void 0 ? {} : { nondeterministic: material.nondeterministic },
+  ...material.effects === void 0 ? {} : { effects: material.effects },
+  ...material.placement === void 0 ? {} : { placement: material.placement }
+});
+const orderingOnly = "ordering-only";
+const project = (value, path) => {
+  let current = value;
+  for (const segment of path) {
+    if (typeof current !== "object" || current === null) return void 0;
+    const descriptor = Object.getOwnPropertyDescriptor(current, segment);
+    if (descriptor === void 0 || !("value" in descriptor)) return void 0;
+    current = descriptor.value;
+  }
+  return current;
+};
+const dispatchIdentity = (options) => Effect.gen(function* () {
+  const material = options.material;
+  if (material.kind !== "sealed") {
+    return yield* new KeyMaterialError({
+      code: "non_content_material",
+      message: `Cannot create a dispatch key for ${material.kind} material`
+    });
+  }
+  const environment = options.environment === void 0 ? void 0 : yield* decodeEnvironment(options.environment);
+  const inputs = yield* resolveInputs(material, (reference) => reference._tag === "Pending" ? Effect.succeed(orderingOnly) : Effect.flatMap(ownDataProperty(options.results, reference.from, "Settled result"), (settled) => {
+    const compute = decodeKey({ kind: "input-value", value: project(settled, reference.path) });
+    return options.digestMemo === void 0 ? compute : options.digestMemo.digest(reference.from, reference.path, compute);
+  }));
+  return yield* content({
+    body: materialBody(material),
+    inputs,
+    layers: material.layers,
+    capabilities: { declared: material.capabilities },
+    environment,
+    hermetic: options.hermetic
+  });
+});
+//# sourceMappingURL=StepKey.js.map