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

package/src/FileSet.ts

@@ -0,0 +1,411 @@
+/**
+ * Static filesystem declaration vocabulary shared by planning and execution.
+ *
+ * Declared paths use `/` as their canonical separator and normalize Unicode
+ * to NFC. Workspace-relative paths reject C0 controls (U+0000 through U+001F)
+ * and DEL (U+007F), which name nothing a supported filesystem can open. C1
+ * controls (U+0080 through U+009F) remain accepted because those bytes are
+ * legal in a POSIX file name.
+ *
+ * @since 0.1.0
+ */
+
+import * as Schema from "effect/Schema"
+
+/**
+ * How strictly a declared file set is enforced at the boundary.
+ *
+ * `hard` rejects undeclared access. `expected` records access for validation
+ * after execution without requiring the sandbox to reject it immediately.
+ *
+ * This is the ONE spelling of the pair. `Plan.NodeEffects.boundaryMode` is this
+ * schema and so is `@smthrs/flow`'s `Action.BoundaryMode`; the literal used to
+ * be written out in all three places.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const BoundaryMode = Schema.Literals(["hard", "expected"])
+
+/**
+ * The value form of {@link BoundaryMode}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type BoundaryMode = typeof BoundaryMode.Type
+
+/**
+ * The canonical spelling of a declared path or pattern: every separator is
+ * `/`, and Unicode is normalized to NFC.
+ *
+ * {@link workspaceRelative} accepts a backslash as a separator, so
+ * `dist\same.js` and `dist/same.js` are two spellings of ONE workspace path.
+ * Every exact-path comparison in this module goes through this form, because
+ * comparing the raw spellings would let the separator alias defeat overlap
+ * detection exactly as `.` segments and empty segments would.
+ *
+ * @category accessors
+ * @since 0.1.0
+ * @slop
+ */
+export const canonical = (path: string): string => path.replaceAll("\\", "/").normalize("NFC")
+
+/**
+ * The {@link canonical} spelling with letter case folded away.
+ *
+ * A case-insensitive filesystem (default macOS APFS, Windows NTFS) opens
+ * `src/A.ts` and `src/a.ts` as one file, so static overlap compares this form:
+ * two declarations that differ only in case must serialize. Folding goes
+ * through upper case because that mapping is context-free, so it folds each
+ * character alone and commutes with splitting a path into segments.
+ *
+ * @category accessors
+ * @since 1.0.0-rc.0
+ */
+export const folded = (path: string): string => canonical(path).toUpperCase().normalize("NFC")
+
+/** Workspace-relative glob pattern.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const Pattern = Schema.NonEmptyString.check(
+  Schema.makeFilter(
+    (pattern) => workspaceRelative(pattern) || "file patterns must be workspace-relative and cannot traverse upward",
+    { title: "workspaceRelativePattern" }
+  )
+)
+
+/**
+ * Whether a declared path or pattern stays inside the workspace and names it
+ * one way only. Refuses absolute paths (POSIX and drive-letter), upward
+ * traversal, and the aliasing forms — `.` segments, empty segments — that
+ * would let two spellings of one file defeat exact-string overlap detection.
+ *
+ * @category predicates
+ * @since 0.1.0
+ * @slop
+ */
+export const workspaceRelative = (pattern: string): boolean => {
+  for (let index = 0; index < pattern.length; index++) {
+    const code = pattern.charCodeAt(index)
+    if (code <= 0x1f || code === 0x7f) return false
+  }
+  if (pattern.startsWith("/")) return false
+  const segments = canonical(pattern).split("/")
+  // `C:foo` is drive-relative on Windows, so any drive-letter prefix escapes.
+  if (/^[A-Za-z]:/.test(segments[0]!) || segments[0]!.endsWith(":")) return false
+  return segments.every((segment) => segment !== ".." && segment !== "." && segment !== "")
+}
+
+/** Bazel-style file glob.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const Glob = Schema.TaggedStruct("Glob", {
+  include: Schema.NonEmptyArray(Pattern),
+  exclude: Schema.optional(Schema.Array(Pattern))
+})
+
+/** Bazel-style file glob.
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type Glob = typeof Glob.Type
+
+/** A directory output captured and replayed as one tree artifact.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const TreeArtifact = Schema.TaggedStruct("TreeArtifact", {
+  path: Pattern
+})
+
+/** A directory output captured and replayed as one tree artifact.
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type TreeArtifact = typeof TreeArtifact.Type
+
+/** One leaf of a named filegroup.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const Entry = Schema.Union([Pattern, Glob, TreeArtifact])
+
+/** One leaf of a named filegroup.
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type Entry = typeof Entry.Type
+
+/** A declaration valid in a read set.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const ReadEntry = Schema.Union([Pattern, Glob])
+
+/** A declaration valid in a read set.
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type ReadEntry = typeof ReadEntry.Type
+
+/** A named reusable collection expanded before measurement.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const Filegroup = Schema.TaggedStruct("Filegroup", {
+  name: Schema.NonEmptyString,
+  entries: Schema.Array(Entry)
+})
+
+/** A named reusable collection expanded before measurement.
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type Filegroup = typeof Filegroup.Type
+
+/** A named read-only collection.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const ReadFilegroup = Schema.TaggedStruct("Filegroup", {
+  name: Schema.NonEmptyString,
+  entries: Schema.Array(ReadEntry)
+})
+
+/** A named read-only collection.
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type ReadFilegroup = typeof ReadFilegroup.Type
+
+/** Any declaration accepted by a plan effect set.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const Declaration = Schema.Union([Entry, Filegroup])
+
+/** Any declaration accepted by a plan effect set.
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type Declaration = typeof Declaration.Type
+
+/** Any declaration accepted by a plan read set.
+ * @category schemas
+ * @since 0.1.0
+ * @slop
+ */
+export const ReadDeclaration = Schema.Union([ReadEntry, ReadFilegroup])
+
+/** Any declaration accepted by a plan read set.
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type ReadDeclaration = typeof ReadDeclaration.Type
+
+/** Creates a named filegroup.
+ * @category constructors
+ * @since 0.1.0
+ * @slop
+ */
+export const makeFilegroup = (name: string, entries: ReadonlyArray<Entry>): Filegroup => ({
+  _tag: "Filegroup",
+  name,
+  entries
+})
+
+/** Expands filegroups deterministically, preserving declaration order.
+ * @category accessors
+ * @since 0.1.0
+ * @slop
+ */
+export const expand = (declarations: ReadonlyArray<Declaration>): ReadonlyArray<Entry> =>
+  declarations.flatMap((declaration) =>
+    typeof declaration !== "string" && declaration._tag === "Filegroup" ? declaration.entries : [declaration]
+  )
+
+/** Expands read filegroups deterministically, preserving declaration order.
+ * @category accessors
+ * @since 0.1.0
+ * @slop
+ */
+export const expandReads = (declarations: ReadonlyArray<ReadDeclaration>): ReadonlyArray<ReadEntry> =>
+  declarations.flatMap((declaration) =>
+    typeof declaration !== "string" && declaration._tag === "Filegroup" ? declaration.entries : [declaration]
+  )
+
+/** Whether a value is a glob declaration.
+ * @category guards
+ * @since 0.1.0
+ * @slop
+ */
+export const isGlob = (value: unknown): value is Glob =>
+  typeof value === "object" && value !== null && "_tag" in value && value._tag === "Glob"
+
+/** Whether a value is a tree artifact declaration.
+ * @category guards
+ * @since 0.1.0
+ * @slop
+ */
+export const isTreeArtifact = (value: unknown): value is TreeArtifact =>
+  typeof value === "object" && value !== null && "_tag" in value && value._tag === "TreeArtifact"
+
+/** KMP searches a literal without rescanning a long near-matching prefix. */
+const literalSearch = (literal: string) => {
+  const fallback = new Uint32Array(literal.length)
+  let matched = 0
+  for (let index = 1; index < literal.length; index++) {
+    while (matched > 0 && literal[index] !== literal[matched]) matched = fallback[matched - 1]!
+    if (literal[index] === literal[matched]) matched++
+    fallback[index] = matched
+  }
+  return (path: string, start: number, end: number): number => {
+    let matched = 0
+    for (let index = start; index < end; index++) {
+      while (matched > 0 && path[index] !== literal[matched]) matched = fallback[matched - 1]!
+      if (path[index] === literal[matched]) matched++
+      if (matched === literal.length) return index + 1
+    }
+    return -1
+  }
+}
+
+/** Anchored ends and disjoint literal searches make each segment match linear. */
+const segmentMatcher = (segment: string): (path: string) => boolean => {
+  const chunks = segment.split(/\*+/)
+  const prefix = chunks.shift()!
+  if (chunks.length === 0) return (path) => path === prefix
+  const suffix = chunks.pop()!
+  const searches = chunks.map(literalSearch)
+  return (path) => {
+    const end = path.length - suffix.length
+    if (prefix.length > end || !path.startsWith(prefix) || !path.endsWith(suffix)) return false
+    let position = prefix.length
+    for (const search of searches) {
+      position = search(path, position, end)
+      if (position === -1) return false
+    }
+    return true
+  }
+}
+
+const patternMatchers = new Map<string, (path: string) => boolean>()
+
+/** Compile once per canonical spelling; recursive segments use no backtracking. */
+const patternMatcher = (pattern: string): (path: string) => boolean => {
+  const key = canonical(pattern)
+  const cached = patternMatchers.get(key)
+  if (cached !== undefined) return cached
+  const segments = key.split("/").map((segment) => segment === "**" ? undefined : segmentMatcher(segment))
+  const matcher = (path: string): boolean => {
+    const parts = path.split("/")
+    // Suffix membership: next[j] says the remaining pattern matches parts[j..].
+    // Each pattern/path segment pair is visited once, even with repeated **.
+    let next = new Uint8Array(parts.length + 1)
+    next[parts.length] = 1
+    for (let index = segments.length - 1; index >= 0; index--) {
+      const segment = segments[index]
+      const current = new Uint8Array(parts.length + 1)
+      for (let part = parts.length - 1; part >= 0; part--) {
+        current[part] = segment === undefined
+          // A trailing ** accepts every remaining code unit. It still needs
+          // the separator preceding it: src/** does not match bare src.
+          ? Number(
+            index === segments.length - 1 || next[part] === 1 ||
+              (parts[part] !== "" && current[part + 1] === 1)
+          )
+          : Number(next[part + 1] === 1 && segment(parts[part]!))
+      }
+      next = current
+    }
+    return next[0] === 1
+  }
+  patternMatchers.set(key, matcher)
+  return matcher
+}
+
+/** Tests one workspace-relative path against one Bazel-style pattern.
+ * @category predicates
+ * @since 0.1.0
+ * @slop
+ */
+export const matchesPattern = (pattern: string, path: string): boolean => patternMatcher(pattern)(path)
+
+/** Tests one file path against a glob, including exclusions.
+ * @category predicates
+ * @since 0.1.0
+ * @slop
+ */
+export const matchesGlob = (glob: Glob, path: string): boolean =>
+  glob.include.some((pattern) => matchesPattern(pattern, path)) &&
+  !(glob.exclude ?? []).some((pattern) => matchesPattern(pattern, path))
+
+const beneath = (tree: string, path: string): boolean => {
+  const root = folded(tree)
+  const inside = folded(path)
+  return inside === root || inside.startsWith(`${root}/`)
+}
+
+/** {@link matchesGlob} over {@link folded} spellings of the glob and the path. */
+const matchesGlobFolded = (glob: Glob, path: string): boolean => {
+  const inside = folded(path)
+  return glob.include.some((pattern) => matchesPattern(folded(pattern), inside)) &&
+    !(glob.exclude ?? []).some((pattern) => matchesPattern(folded(pattern), inside))
+}
+
+/**
+ * Conservative static overlap. `true` may over-serialize; `false` proves that
+ * no path can belong to both declarations.
+ *
+ * A plain string is a literal path, even when it contains `*` or `**`, as it
+ * is at execution (sandbox admission, capture, removal, and replay); wildcard
+ * matching belongs to a Glob.
+ *
+ * Exact paths and tree roots compare in their
+ * {@link folded} form, so separator aliases, canonically equivalent Unicode
+ * spellings, and spellings that differ only in letter case overlap. A Glob
+ * against an exact path matches both its `include` and `exclude` patterns in
+ * folded form. {@link matchesGlob} itself stays case-sensitive and tests the path bytes it
+ * is handed; its property suite pins a backslash inside a path segment as
+ * literal text, so canonicalizing a measured path before matching is its
+ * caller's decision, not this module's.
+ *
+ * @category predicates
+ * @since 0.1.0
+ * @slop
+ */
+export const overlaps = (left: Entry, right: Entry): boolean => {
+  if (typeof left === "string" && typeof right === "string") return folded(left) === folded(right)
+  if (typeof left === "string" && isGlob(right)) return matchesGlobFolded(right, left)
+  if (isGlob(left) && typeof right === "string") return matchesGlobFolded(left, right)
+  if (isGlob(left) && isGlob(right)) return true
+  if (isTreeArtifact(left) && typeof right === "string") return beneath(left.path, right)
+  if (typeof left === "string" && isTreeArtifact(right)) return beneath(right.path, left)
+  if (isTreeArtifact(left) && isTreeArtifact(right)) {
+    return beneath(left.path, right.path) || beneath(right.path, left.path)
+  }
+  if (isTreeArtifact(left) && isGlob(right)) return true
+  /* v8 ignore else -- the closed Entry union leaves only Glob/TreeArtifact here */
+  if (isGlob(left) && isTreeArtifact(right)) return overlaps(right, left)
+  /* v8 ignore next -- Entry's closed union makes every pair return above */
+  return true
+}

package/src/GraphBuildError.ts

@@ -0,0 +1,158 @@
+/**
+ * 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
+ * @slop
+ */
+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"
+])
+
+/**
+ * The value form of {@link GraphBuildErrorCode}.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export type GraphBuildErrorCode = typeof GraphBuildErrorCode.Type
+
+/**
+ * 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
+ * @slop
+ */
+export class GraphBuildError extends Schema.TaggedError<GraphBuildError>()("@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: ReadonlySet<GraphBuildErrorCode> = new Set<GraphBuildErrorCode>(["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.
+ *
+ * @since 0.1.0
+ * @category predicates
+ * @slop
+ */
+export const isFatalDiagnostic = (diagnostic: GraphBuildError): boolean => !advisoryCodes.has(diagnostic.code)

package/src/KeyMaterial.ts

@@ -0,0 +1,106 @@
+/**
+ * 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://smithers.sh/docs/concepts/content-addressing. 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.ts"
+
+/**
+ * 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.
+ *
+ * @since 0.1.0
+ * @category schemas
+ * @slop
+ */
+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 })
+])
+
+/**
+ * A reference to one declared input of a node.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+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
+ * @slop
+ */
+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.
+ *
+ * @since 0.1.0
+ * @category schemas
+ * @slop
+ */
+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)
+})
+
+/**
+ * Everything that can change a node's result, handed to the digest.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+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.
+ *
+ * @since 0.1.0
+ * @category accessors
+ * @slop
+ */
+export const dependencies = (material: KeyMaterial): ReadonlyArray<string> => {
+  const seen = new Set<string>()
+  for (const input of material.inputs) {
+    if (input._tag !== "Literal") seen.add(input.from)
+  }
+  return [...seen]
+}