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

package/dist/esm/GraphBuildError.js

@@ -0,0 +1,145 @@
+/**
+ * The refusals a plan-time build raises instead of producing a wrong plan.
+ *
+ * Every one of these fails LOUDLY at build time: a planned value that was computed on must not
+ * bake `NaN` into a plan, an arm that returned something other than a node must
+ * not silently vanish from the topology, and a recursive `.call()` must direct
+ * the author to `.to()` or `.child()` rather than expanding forever. Each
+ * failure therefore names the site (`node` plus the recorded property `path`)
+ * and states the fix in `message`, because the author reading it is mid-body
+ * and needs the correction, not a classification.
+ *
+ * The codes are a closed schema literal so a caller can switch on them, and so
+ * a new refusal is a deliberate addition rather than a new free-form string.
+ *
+ * @since 0.1.0
+ */
+import * as Schema from "effect/Schema";
+/**
+ * The stable code of a build refusal.
+ *
+ * `planned_value_computed` is a body computing on a step result;
+ * `invalid_all_member` is a non-node handed to {@link module:Node.all};
+ * `invalid_join` is a race, any, or quorum with a non-node member, no members,
+ * or a quorum count its members cannot reach;
+ * `invalid_continuation` is a branch arm or continuation that did not return a
+ * node; `recursion_requires_boundary` is a flow calling itself inline, which
+ * has to become a trampoline handoff or an explicit child boundary;
+ * `placement_requires_boundary` is an inline call whose callee declares a
+ * placement the enclosing flow cannot satisfy, which has to become that same
+ * explicit child boundary; `cyclic_payload` is a payload that contains itself,
+ * which no plan could serialize or hash; `payload_too_deep` is a payload
+ * nested past the build bound, which has to be flattened into shallower data;
+ * `graph_too_deep` is authored topology nested past the build bound, which
+ * has to be split with `.child()` boundaries or trampoline handoffs;
+ * `duplicate_node` is two structural graph addresses resolving to one durable
+ * node id;
+ * `invalid_priority` is a scheduling priority that is not a safe integer,
+ * which no ordering could compare; `invalid_payload` is a payload member that
+ * cannot be captured as inert JSON without executing author code or losing
+ * identity; `unstable_callback` is a function with process-local identity in a
+ * graph that requires stable callbacks. Declare its complete inert captures
+ * with `Node.capture`, including semantic implementation versions. The two
+ * depth refusals exist because graph building walks with an explicit stack
+ * and refuses at a bound, rather than recursing until the native stack
+ * overflows without a typed error.
+ *
+ * The four effect-authority refusals are raised when a declaration claims more
+ * than the declaration enclosing it granted:
+ * `effect_outside_envelope` is a read or write path the envelope does not
+ * cover, and it names those paths in `path`; `effect_mode_widening` is an
+ * `expected` declaration inside a `hermetic` envelope; `effect_tier_widening`
+ * is a tier less reversible than the envelope's; and
+ * `capability_outside_grant` is a called flow or action requiring a capability
+ * the caller does not hold, which names the dropped capabilities in `path`. The
+ * first three are fatal by {@link isFatalDiagnostic}; the fourth is advisory,
+ * because dropping a capability narrows authority rather than widening it.
+ *
+ * The last six are raised by `@smthrs/core`'s graph builder, which uses this
+ * one error rather than a second class of its own. `write_conflict` is two work
+ * nodes overlapping under `onConflict: "fail"`, and `node` names the first of
+ * the pair while `Graph.conflicts` carries both; `missing_key_material` is a
+ * node that reached key compilation without any; `dependency_cycle` is a
+ * dependency set that cannot be ordered, and `node` names a node in the cycle;
+ * `plan_too_large` is a node, edge, conflict, or effect-path limit crossed, and
+ * `node` names the node whose admission crossed it; `payload_too_large` is a
+ * plan value with more members than the bound, and `path` names the offending
+ * value path; `invalid_node` is a malformed node AST. All six are fatal.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const GraphBuildErrorCode = Schema.Literals([
+    "planned_value_computed",
+    "invalid_all_member",
+    "invalid_join",
+    "invalid_continuation",
+    "recursion_requires_boundary",
+    "placement_requires_boundary",
+    "cyclic_payload",
+    "payload_too_deep",
+    "graph_too_deep",
+    "duplicate_node",
+    "invalid_priority",
+    "invalid_payload",
+    "unstable_callback",
+    "effect_outside_envelope",
+    "effect_mode_widening",
+    "effect_tier_widening",
+    "capability_outside_grant",
+    "write_conflict",
+    "missing_key_material",
+    "dependency_cycle",
+    "plan_too_large",
+    "payload_too_large",
+    "invalid_node"
+]);
+/**
+ * A build the planner refuses, naming the site and the fix.
+ *
+ * `node` is the node reference the failure belongs to — a planned value's
+ * origin node, an `all` member name, a branch arm, or the node whose admission
+ * crossed a bound. `path` is the property path recorded on a planned value
+ * before it was misused, the effect paths an over-claiming declaration named,
+ * the capabilities a call lost, or the value path of an oversized payload; it
+ * is empty for every other code.
+ *
+ * This is the ONE build refusal. `@smthrs/core`'s graph builder raised a second
+ * `GraphBuildError` of its own, with `paths`, `nodeId` and `nodes` in place of
+ * these fields, and the two code sets diverged instead of merging. A conflict's
+ * second node is read from `Graph.conflicts`, which carries the pair.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export class GraphBuildError extends Schema.TaggedError()("@smthrs/plan/GraphBuildError", {
+    code: GraphBuildErrorCode,
+    node: Schema.String,
+    path: Schema.Array(Schema.String),
+    message: Schema.String
+}) {
+}
+/**
+ * The one advisory code. Everything else a build records blocks the drafts.
+ *
+ * A capability the caller does not grant is DROPPED, not granted: the callee
+ * runs with less authority than it asked for, which is the safe direction. The
+ * author still needs to know, because a flow that silently loses a capability
+ * fails later at the action that needed it, so the build records the refusal
+ * and lets the graph compile.
+ */
+const advisoryCodes = new Set(["capability_outside_grant"]);
+/**
+ * Whether a recorded refusal blocks the drafts a plan is compiled from.
+ *
+ * A fatal refusal means the graph describes something no plan could execute as
+ * written, so the drafts are withheld. An advisory one reports a narrowing the
+ * author should see while the graph still compiles.
+ *
+ * @param diagnostic - A recorded refusal.
+ * @returns `false` only for an advisory code (`capability_outside_grant`).
+ * @since 0.1.0
+ * @category predicates
+ */
+export const isFatalDiagnostic = (diagnostic) => !advisoryCodes.has(diagnostic.code);
+//# sourceMappingURL=GraphBuildError.js.map

package/dist/esm/GraphBuildError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphBuildError.js","sourceRoot":"","sources":["../../src/GraphBuildError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,QAAQ,CAAC;IACjD,wBAAwB;IACxB,oBAAoB;IACpB,cAAc;IACd,sBAAsB;IACtB,6BAA6B;IAC7B,6BAA6B;IAC7B,gBAAgB;IAChB,kBAAkB;IAClB,gBAAgB;IAChB,gBAAgB;IAChB,kBAAkB;IAClB,iBAAiB;IACjB,mBAAmB;IACnB,yBAAyB;IACzB,sBAAsB;IACtB,sBAAsB;IACtB,0BAA0B;IAC1B,gBAAgB;IAChB,sBAAsB;IACtB,kBAAkB;IAClB,gBAAgB;IAChB,mBAAmB;IACnB,cAAc;CACf,CAAC,CAAA;AAUF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,eAAgB,SAAQ,MAAM,CAAC,WAAW,EAAmB,CAAC,8BAA8B,EAAE;IACzG,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,MAAM,CAAC,MAAM;IACnB,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC,MAAM;CACvB,CAAC;CAAG;AAEL;;;;;;;;GAQG;AACH,MAAM,aAAa,GAAqC,IAAI,GAAG,CAAsB,CAAC,0BAA0B,CAAC,CAAC,CAAA;AAElH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,UAA2B,EAAW,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA","sourcesContent":["/**\n * The refusals a plan-time build raises instead of producing a wrong plan.\n *\n * Every one of these fails LOUDLY at build time: a planned value that was computed on must not\n * bake `NaN` into a plan, an arm that returned something other than a node must\n * not silently vanish from the topology, and a recursive `.call()` must direct\n * the author to `.to()` or `.child()` rather than expanding forever. Each\n * failure therefore names the site (`node` plus the recorded property `path`)\n * and states the fix in `message`, because the author reading it is mid-body\n * and needs the correction, not a classification.\n *\n * The codes are a closed schema literal so a caller can switch on them, and so\n * a new refusal is a deliberate addition rather than a new free-form string.\n *\n * @since 0.1.0\n */\n\nimport * as Schema from \"effect/Schema\"\n\n/**\n * The stable code of a build refusal.\n *\n * `planned_value_computed` is a body computing on a step result;\n * `invalid_all_member` is a non-node handed to {@link module:Node.all};\n * `invalid_join` is a race, any, or quorum with a non-node member, no members,\n * or a quorum count its members cannot reach;\n * `invalid_continuation` is a branch arm or continuation that did not return a\n * node; `recursion_requires_boundary` is a flow calling itself inline, which\n * has to become a trampoline handoff or an explicit child boundary;\n * `placement_requires_boundary` is an inline call whose callee declares a\n * placement the enclosing flow cannot satisfy, which has to become that same\n * explicit child boundary; `cyclic_payload` is a payload that contains itself,\n * which no plan could serialize or hash; `payload_too_deep` is a payload\n * nested past the build bound, which has to be flattened into shallower data;\n * `graph_too_deep` is authored topology nested past the build bound, which\n * has to be split with `.child()` boundaries or trampoline handoffs;\n * `duplicate_node` is two structural graph addresses resolving to one durable\n * node id;\n * `invalid_priority` is a scheduling priority that is not a safe integer,\n * which no ordering could compare; `invalid_payload` is a payload member that\n * cannot be captured as inert JSON without executing author code or losing\n * identity; `unstable_callback` is a function with process-local identity in a\n * graph that requires stable callbacks. Declare its complete inert captures\n * with `Node.capture`, including semantic implementation versions. The two\n * depth refusals exist because graph building walks with an explicit stack\n * and refuses at a bound, rather than recursing until the native stack\n * overflows without a typed error.\n *\n * The four effect-authority refusals are raised when a declaration claims more\n * than the declaration enclosing it granted:\n * `effect_outside_envelope` is a read or write path the envelope does not\n * cover, and it names those paths in `path`; `effect_mode_widening` is an\n * `expected` declaration inside a `hermetic` envelope; `effect_tier_widening`\n * is a tier less reversible than the envelope's; and\n * `capability_outside_grant` is a called flow or action requiring a capability\n * the caller does not hold, which names the dropped capabilities in `path`. The\n * first three are fatal by {@link isFatalDiagnostic}; the fourth is advisory,\n * because dropping a capability narrows authority rather than widening it.\n *\n * The last six are raised by `@smthrs/core`'s graph builder, which uses this\n * one error rather than a second class of its own. `write_conflict` is two work\n * nodes overlapping under `onConflict: \"fail\"`, and `node` names the first of\n * the pair while `Graph.conflicts` carries both; `missing_key_material` is a\n * node that reached key compilation without any; `dependency_cycle` is a\n * dependency set that cannot be ordered, and `node` names a node in the cycle;\n * `plan_too_large` is a node, edge, conflict, or effect-path limit crossed, and\n * `node` names the node whose admission crossed it; `payload_too_large` is a\n * plan value with more members than the bound, and `path` names the offending\n * value path; `invalid_node` is a malformed node AST. All six are fatal.\n *\n * @since 0.1.0\n * @category schemas\n */\nexport const GraphBuildErrorCode = Schema.Literals([\n  \"planned_value_computed\",\n  \"invalid_all_member\",\n  \"invalid_join\",\n  \"invalid_continuation\",\n  \"recursion_requires_boundary\",\n  \"placement_requires_boundary\",\n  \"cyclic_payload\",\n  \"payload_too_deep\",\n  \"graph_too_deep\",\n  \"duplicate_node\",\n  \"invalid_priority\",\n  \"invalid_payload\",\n  \"unstable_callback\",\n  \"effect_outside_envelope\",\n  \"effect_mode_widening\",\n  \"effect_tier_widening\",\n  \"capability_outside_grant\",\n  \"write_conflict\",\n  \"missing_key_material\",\n  \"dependency_cycle\",\n  \"plan_too_large\",\n  \"payload_too_large\",\n  \"invalid_node\"\n])\n\n/**\n * The value form of {@link GraphBuildErrorCode}.\n *\n * @since 0.1.0\n * @category models\n */\nexport type GraphBuildErrorCode = typeof GraphBuildErrorCode.Type\n\n/**\n * A build the planner refuses, naming the site and the fix.\n *\n * `node` is the node reference the failure belongs to — a planned value's\n * origin node, an `all` member name, a branch arm, or the node whose admission\n * crossed a bound. `path` is the property path recorded on a planned value\n * before it was misused, the effect paths an over-claiming declaration named,\n * the capabilities a call lost, or the value path of an oversized payload; it\n * is empty for every other code.\n *\n * This is the ONE build refusal. `@smthrs/core`'s graph builder raised a second\n * `GraphBuildError` of its own, with `paths`, `nodeId` and `nodes` in place of\n * these fields, and the two code sets diverged instead of merging. A conflict's\n * second node is read from `Graph.conflicts`, which carries the pair.\n *\n * @since 0.1.0\n * @category errors\n */\nexport class GraphBuildError extends Schema.TaggedError<GraphBuildError>()(\"@smthrs/plan/GraphBuildError\", {\n  code: GraphBuildErrorCode,\n  node: Schema.String,\n  path: Schema.Array(Schema.String),\n  message: Schema.String\n}) {}\n\n/**\n * The one advisory code. Everything else a build records blocks the drafts.\n *\n * A capability the caller does not grant is DROPPED, not granted: the callee\n * runs with less authority than it asked for, which is the safe direction. The\n * author still needs to know, because a flow that silently loses a capability\n * fails later at the action that needed it, so the build records the refusal\n * and lets the graph compile.\n */\nconst advisoryCodes: ReadonlySet<GraphBuildErrorCode> = new Set<GraphBuildErrorCode>([\"capability_outside_grant\"])\n\n/**\n * Whether a recorded refusal blocks the drafts a plan is compiled from.\n *\n * A fatal refusal means the graph describes something no plan could execute as\n * written, so the drafts are withheld. An advisory one reports a narrowing the\n * author should see while the graph still compiles.\n *\n * @param diagnostic - A recorded refusal.\n * @returns `false` only for an advisory code (`capability_outside_grant`).\n * @since 0.1.0\n * @category predicates\n */\nexport const isFatalDiagnostic = (diagnostic: GraphBuildError): boolean => !advisoryCodes.has(diagnostic.code)\n"]}

package/dist/esm/KeyMaterial.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The key-material contract: what a planner hands the step-key compiler.
+ *
+ * Revived from the deleted `packages/smithers/flows/keys/src/KeyMaterial.ts`.
+ * It does NOT return to `@smthrs/keys`: that package owns generic derivation
+ * and stored-key validation, while material is a *plan-shaped* concept. It
+ * lives here, above `@smthrs/keys`, so the key package stays a leaf.
+ *
+ * Governing contract: the step-key rules at
+ * https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/plan/docs/concepts/step-keys.md. Material is computed with no I/O,
+ * and two hardening rules shape it: the nominal, never shape-sniffed
+ * `InputRef` and the hashed `version`.
+ *
+ * @since 0.1.0
+ */
+import * as Schema from "effect/Schema";
+/**
+ * A reference to one declared input of a node: a value hashed inline, or the
+ * key of an upstream node whose result this node consumes.
+ *
+ * The three variants are tagged, and the tag is hashed, so `Pending{from}` and
+ * `Ref{from, path: []}` — which resolve to the same dependency digest — can
+ * never collide.
+ *
+ * - `Literal` hashes `value` inline.
+ * - `Ref` consumes the value at `path` inside node `from`'s result.
+ * - `Pending` consumes node `from`'s whole result.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export declare const InputRef: Schema.Union<readonly [Schema.TaggedStruct<"Literal", {
+    readonly value: Schema.Unknown;
+}>, Schema.TaggedStruct<"Ref", {
+    readonly from: Schema.NonEmptyString;
+    readonly path: Schema.$Array<Schema.String>;
+}>, Schema.TaggedStruct<"Pending", {
+    readonly from: Schema.NonEmptyString;
+}>]>;
+/**
+ * The value form of {@link InputRef}.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type InputRef = typeof InputRef.Type;
+/**
+ * The material version. Folded into every hashed body so a bump re-keys every
+ * node derived from it — the original's second collision fix, kept.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export declare const version = "flows/key-material/v2";
+/**
+ * Everything that can change a node's result, handed to the digest.
+ *
+ * `effects` and `placement` are opaque: canonically serialized, never
+ * interpreted, which is what keeps the compiler independent of whatever the
+ * flow builder decides an effect declaration looks like.
+ *
+ * `version` must equal {@link version}. `kind` is the effect tier. `inputs`
+ * are hashed in order; `layers` and `capabilities` name what the node runs
+ * with.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export declare const KeyMaterial: Schema.Struct<{
+    readonly version: Schema.Literal<"flows/key-material/v2">;
+    readonly kind: Schema.Literals<readonly ["sealed", "compensable", "irreversible"]>;
+    readonly nondeterministic: Schema.optional<Schema.Literal<true>>;
+    readonly body: Schema.Unknown;
+    readonly inputs: Schema.$Array<Schema.Union<readonly [Schema.TaggedStruct<"Literal", {
+        readonly value: Schema.Unknown;
+    }>, Schema.TaggedStruct<"Ref", {
+        readonly from: Schema.NonEmptyString;
+        readonly path: Schema.$Array<Schema.String>;
+    }>, Schema.TaggedStruct<"Pending", {
+        readonly from: Schema.NonEmptyString;
+    }>]>>;
+    readonly layers: Schema.$Array<Schema.String>;
+    readonly capabilities: Schema.$Array<Schema.String>;
+    readonly effects: Schema.optional<Schema.Unknown>;
+    readonly placement: Schema.optional<Schema.Unknown>;
+}>;
+/**
+ * The value form of {@link KeyMaterial}.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type KeyMaterial = typeof KeyMaterial.Type;
+/**
+ * The graph-local dependencies a material names, in declaration order and
+ * without duplicates. The compiler resolves exactly these before hashing, and
+ * {@link module:Plan} uses them as the edge set — one derivation, so an edge
+ * and a hashed reference can never disagree.
+ *
+ * @param material - The node's key material.
+ * @returns The `from` of every `Ref` and `Pending` input, first occurrence
+ * order, deduplicated.
+ * @since 0.1.0
+ * @category accessors
+ */
+export declare const dependencies: (material: KeyMaterial) => ReadonlyArray<string>;
+//# sourceMappingURL=KeyMaterial.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"KeyMaterial.d.ts","sourceRoot":"","sources":["../../src/KeyMaterial.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ;;;;;;;IAInB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,0BAA0B,CAAA;AAE9C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;EAWtB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAEjD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,GAAI,UAAU,WAAW,KAAG,aAAa,CAAC,MAAM,CAMxE,CAAA"}

package/dist/esm/KeyMaterial.js

@@ -0,0 +1,92 @@
+/**
+ * The key-material contract: what a planner hands the step-key compiler.
+ *
+ * Revived from the deleted `packages/smithers/flows/keys/src/KeyMaterial.ts`.
+ * It does NOT return to `@smthrs/keys`: that package owns generic derivation
+ * and stored-key validation, while material is a *plan-shaped* concept. It
+ * lives here, above `@smthrs/keys`, so the key package stays a leaf.
+ *
+ * Governing contract: the step-key rules at
+ * https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/plan/docs/concepts/step-keys.md. Material is computed with no I/O,
+ * and two hardening rules shape it: the nominal, never shape-sniffed
+ * `InputRef` and the hashed `version`.
+ *
+ * @since 0.1.0
+ */
+import * as Schema from "effect/Schema";
+import * as Effects from "./Effects.js";
+/**
+ * A reference to one declared input of a node: a value hashed inline, or the
+ * key of an upstream node whose result this node consumes.
+ *
+ * The three variants are tagged, and the tag is hashed, so `Pending{from}` and
+ * `Ref{from, path: []}` — which resolve to the same dependency digest — can
+ * never collide.
+ *
+ * - `Literal` hashes `value` inline.
+ * - `Ref` consumes the value at `path` inside node `from`'s result.
+ * - `Pending` consumes node `from`'s whole result.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const InputRef = Schema.Union([
+    Schema.TaggedStruct("Literal", { value: Schema.Unknown }),
+    Schema.TaggedStruct("Ref", { from: Schema.NonEmptyString, path: Schema.Array(Schema.String) }),
+    Schema.TaggedStruct("Pending", { from: Schema.NonEmptyString })
+]);
+/**
+ * The material version. Folded into every hashed body so a bump re-keys every
+ * node derived from it — the original's second collision fix, kept.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export const version = "flows/key-material/v2";
+/**
+ * Everything that can change a node's result, handed to the digest.
+ *
+ * `effects` and `placement` are opaque: canonically serialized, never
+ * interpreted, which is what keeps the compiler independent of whatever the
+ * flow builder decides an effect declaration looks like.
+ *
+ * `version` must equal {@link version}. `kind` is the effect tier. `inputs`
+ * are hashed in order; `layers` and `capabilities` name what the node runs
+ * with.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const KeyMaterial = Schema.Struct({
+    version: Schema.Literal(version),
+    kind: Effects.Tier,
+    // Absence claims determinism; only the explicit declaration changes identity.
+    nondeterministic: Schema.optional(Schema.Literal(true)),
+    body: Schema.Unknown,
+    inputs: Schema.Array(InputRef),
+    layers: Schema.Array(Schema.String),
+    capabilities: Schema.Array(Schema.String),
+    effects: Schema.optional(Schema.Unknown),
+    placement: Schema.optional(Schema.Unknown)
+});
+/**
+ * The graph-local dependencies a material names, in declaration order and
+ * without duplicates. The compiler resolves exactly these before hashing, and
+ * {@link module:Plan} uses them as the edge set — one derivation, so an edge
+ * and a hashed reference can never disagree.
+ *
+ * @param material - The node's key material.
+ * @returns The `from` of every `Ref` and `Pending` input, first occurrence
+ * order, deduplicated.
+ * @since 0.1.0
+ * @category accessors
+ */
+export const dependencies = (material) => {
+    const seen = new Set();
+    for (const input of material.inputs) {
+        if (input._tag !== "Literal")
+            seen.add(input.from);
+    }
+    return [...seen];
+};
+//# sourceMappingURL=KeyMaterial.js.map

package/dist/esm/KeyMaterial.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeyMaterial.js","sourceRoot":"","sources":["../../src/KeyMaterial.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC;IACnC,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;IACzD,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,cAAc,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;IAC9F,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,cAAc,EAAE,CAAC;CAChE,CAAC,CAAA;AAUF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,uBAAuB,CAAA;AAE9C;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;IAChC,IAAI,EAAE,OAAO,CAAC,IAAI;IAClB,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,IAAI,EAAE,MAAM,CAAC,OAAO;IACpB,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;IACnC,YAAY,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC;CAC3C,CAAC,CAAA;AAUF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,QAAqB,EAAyB,EAAE;IAC3E,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QACpC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;YAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACpD,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,CAAC,CAAA;AAClB,CAAC,CAAA","sourcesContent":["/**\n * The key-material contract: what a planner hands the step-key compiler.\n *\n * Revived from the deleted `packages/smithers/flows/keys/src/KeyMaterial.ts`.\n * It does NOT return to `@smthrs/keys`: that package owns generic derivation\n * and stored-key validation, while material is a *plan-shaped* concept. It\n * lives here, above `@smthrs/keys`, so the key package stays a leaf.\n *\n * Governing contract: the step-key rules at\n * https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/plan/docs/concepts/step-keys.md. Material is computed with no I/O,\n * and two hardening rules shape it: the nominal, never shape-sniffed\n * `InputRef` and the hashed `version`.\n *\n * @since 0.1.0\n */\n\nimport * as Schema from \"effect/Schema\"\nimport * as Effects from \"./Effects.ts\"\n\n/**\n * A reference to one declared input of a node: a value hashed inline, or the\n * key of an upstream node whose result this node consumes.\n *\n * The three variants are tagged, and the tag is hashed, so `Pending{from}` and\n * `Ref{from, path: []}` — which resolve to the same dependency digest — can\n * never collide.\n *\n * - `Literal` hashes `value` inline.\n * - `Ref` consumes the value at `path` inside node `from`'s result.\n * - `Pending` consumes node `from`'s whole result.\n *\n * @since 0.1.0\n * @category schemas\n */\nexport const InputRef = Schema.Union([\n  Schema.TaggedStruct(\"Literal\", { value: Schema.Unknown }),\n  Schema.TaggedStruct(\"Ref\", { from: Schema.NonEmptyString, path: Schema.Array(Schema.String) }),\n  Schema.TaggedStruct(\"Pending\", { from: Schema.NonEmptyString })\n])\n\n/**\n * The value form of {@link InputRef}.\n *\n * @since 0.1.0\n * @category models\n */\nexport type InputRef = typeof InputRef.Type\n\n/**\n * The material version. Folded into every hashed body so a bump re-keys every\n * node derived from it — the original's second collision fix, kept.\n *\n * @since 0.1.0\n * @category constants\n */\nexport const version = \"flows/key-material/v2\"\n\n/**\n * Everything that can change a node's result, handed to the digest.\n *\n * `effects` and `placement` are opaque: canonically serialized, never\n * interpreted, which is what keeps the compiler independent of whatever the\n * flow builder decides an effect declaration looks like.\n *\n * `version` must equal {@link version}. `kind` is the effect tier. `inputs`\n * are hashed in order; `layers` and `capabilities` name what the node runs\n * with.\n *\n * @since 0.1.0\n * @category schemas\n */\nexport const KeyMaterial = Schema.Struct({\n  version: Schema.Literal(version),\n  kind: Effects.Tier,\n  // Absence claims determinism; only the explicit declaration changes identity.\n  nondeterministic: Schema.optional(Schema.Literal(true)),\n  body: Schema.Unknown,\n  inputs: Schema.Array(InputRef),\n  layers: Schema.Array(Schema.String),\n  capabilities: Schema.Array(Schema.String),\n  effects: Schema.optional(Schema.Unknown),\n  placement: Schema.optional(Schema.Unknown)\n})\n\n/**\n * The value form of {@link KeyMaterial}.\n *\n * @since 0.1.0\n * @category models\n */\nexport type KeyMaterial = typeof KeyMaterial.Type\n\n/**\n * The graph-local dependencies a material names, in declaration order and\n * without duplicates. The compiler resolves exactly these before hashing, and\n * {@link module:Plan} uses them as the edge set — one derivation, so an edge\n * and a hashed reference can never disagree.\n *\n * @param material - The node's key material.\n * @returns The `from` of every `Ref` and `Pending` input, first occurrence\n * order, deduplicated.\n * @since 0.1.0\n * @category accessors\n */\nexport const dependencies = (material: KeyMaterial): ReadonlyArray<string> => {\n  const seen = new Set<string>()\n  for (const input of material.inputs) {\n    if (input._tag !== \"Literal\") seen.add(input.from)\n  }\n  return [...seen]\n}\n"]}