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

package/docs/guides/diff-two-plans.md

@@ -0,0 +1,101 @@
+---
+title: "Diff two plans"
+description: "Compare a re-plan against the plan before it: what the verdict is, how a re-key is attributed to the field that caused it, and why the report is in no digest."
+sidebar:
+  order: 5
+---
+
+"What is different about this run" is a set comparison, not archaeology.
+`PlanDiff.diff` is that comparison as a value.
+
+```ts
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
+import * as Plan from "@smthrs/plan/Plan"
+import * as PlanDiff from "@smthrs/plan/PlanDiff"
+import type * as Crypto from "effect/Crypto"
+import * as Effect from "effect/Effect"
+
+/** The drafts and the compiled effect from "Compile drafts into a plan". */
+declare const readPr: Plan.NodeDraft
+declare const runTests: Plan.NodeDraft
+declare const compiled: Effect.Effect<Plan.Plan, never, Crypto.Crypto>
+
+export const compare = Effect.gen(function*() {
+  const before = yield* compiled
+  const after = yield* Plan.compile({
+    planId: "review-4821",
+    flow: "example/Review",
+    nodes: [readPr, { ...runTests, material: { ...runTests.material, body: { action: "run-tests", jobs: 4 } } }]
+  })
+  const changes: PlanDiff.PlanDiff = PlanDiff.diff(before, after)
+  return changes.rekeyed.map((entry) => `${entry.id}: ${entry.changed.join(", ")}`)
+}).pipe(Effect.provide(NodeCrypto.layer))
+```
+
+`compare` answers `["run-tests: body"]`. The edit moved one field of one node's
+body, so that node re-keyed and the report says which field did it.
+
+## The verdict is the key
+
+Two nodes with the same id and the same key are the same step. Nothing else
+needs saying, and `diff` says nothing else. Four lists come back:
+
+| Field       | Contents                                                                 |
+| ----------- | ------------------------------------------------------------------------ |
+| `added`     | Node ids present in `next` and absent from `previous`.                   |
+| `removed`   | Node ids present in `previous` and absent from `next`.                   |
+| `rekeyed`   | Nodes present in both whose key moved, with `from`, `to`, and `changed`. |
+| `unchanged` | Node ids present in both with the same key.                              |
+
+## The attribution is for a human
+
+`Rekeyed.changed` is a list of field labels: `["body", "input[1]"]`. It is
+derived by comparing declarations field by field, and it is deliberately part of
+no digest. Changing how the report reads can never change what a plan hashes to.
+
+The labels mirror the hashed declaration: the effect tier `kind`, the fields
+the hashed material body folds, and the input positions:
+
+```text
+kind  body  layers  capabilities  effects  version  nondeterministic  placement  input[n]
+```
+
+An `input[n]` entry appears when that input's declaration changed, and also when
+the declaration is unchanged but the node it references itself re-keyed. A node
+re-keyed purely by an upstream edit is therefore attributed to the input
+position that references it, even behind an unprojected `Pending`, rather than
+reported as nothing changed.
+
+`changed` is empty only when none of the compared fields moved, which means the
+key moved for a reason the comparison does not model. Treat an empty `changed`
+on a re-keyed node as a bug report, not as noise.
+
+## Comparison uses the key's own JSON semantics
+
+Each compared field is projected through the same JSON mirror the keys are
+derived from, so two `Date` bodies a generation apart attribute to `body` rather
+than to nothing. The projection runs no accessor.
+
+A field the projection refuses compares by an identity token scoped to that node
+and field. The same value stays equal to itself, two distinct refused values
+never compare equal, and `diff` stays a total function even for a value
+canonical serialization would reject. `diff` never fails and never needs a
+service.
+
+## Reporting a re-plan
+
+The pairing this is built for is a re-plan of the same flow: compile the flow
+again against the current source and compare the result with the plan an
+operator last saw. `added` and `removed` are the shape change, `rekeyed` is the
+work that will not come from cache, and `unchanged` is everything a cache hit
+will skip.
+
+The command line prints the same comparison through
+[`smthrs flow plan`](/cli/flow), and the plan card it renders is what
+[`smthrs approvals approve`](/cli/approvals) binds a decision to.
+
+## Next
+
+- [Step keys](../concepts/step-keys.md): why an upstream edit re-keys a
+  downstream node whose own declaration did not change.
+- [The plan value](../concepts/plan-value.md): the digests a diff sits beside.

package/docs/installation.md

@@ -0,0 +1,71 @@
+---
+title: "Installation"
+description: "Install @smthrs/plan and satisfy its peer requirements."
+sidebar:
+  order: 1
+---
+
+## Requirements
+
+- Node.js 26.4.0 or later.
+- `effect` 4.0.0-rc.115. The package's schemas, layers, and error classes are
+  Effect values, so the version has to match the one your application uses.
+
+## Install
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+That is enough to build node graphs, compile plans, and diff them. Compiling
+asks for Effect's `Crypto` service, which a platform package supplies:
+
+```bash
+pnpm add @effect/platform-node@4.0.0-rc.115 @effect/platform-node-shared@4.0.0-rc.115
+```
+
+`@smthrs/crypto`, `@smthrs/canonical` and [`@smthrs/keys`](/api/keys) arrive as
+dependencies of this package; you do not install them yourself unless you use
+them directly.
+
+## What persistence adds
+
+This package performs no I/O. Recording a compiled plan is
+[`@smthrs/plan-store`](/api/plan-store), which owns the SQL and brings
+[`@smthrs/database`](/api/database) with it.
+
+## Import forms
+
+The root entry point re-exports every module as a namespace:
+
+```ts
+import { FileSet, Node, Plan, PlanDiff } from "@smthrs/plan"
+```
+
+Each module is also its own entry point. Prefer this form: it keeps a bundle to
+the modules you actually reach for.
+
+```ts
+import * as Node from "@smthrs/plan/Node"
+import * as Plan from "@smthrs/plan/Plan"
+```
+
+Both forms resolve to the same values.
+
+## What you cannot import
+
+`@smthrs/plan/internal/*` is blocked by the export map, and so is
+`@smthrs/plan/<Module>/index`. Node reports `ERR_PACKAGE_PATH_NOT_EXPORTED` for
+either.
+
+`@smthrs/plan/test/PlanFixtures` is the exception that is meant for test code:
+it builds drafts and compiles them, and
+[`@smthrs/plan-store`](/api/plan-store) drives the same fixtures against the
+persisted form.
+
+## Browser support
+
+The package is browser-safe: it resolves no `node:` built-in and binds no
+database. Compiling, diffing, and building node graphs all work in a browser.
+
+## Next
+
+[Quickstart](./quickstart.md) compiles a plan, appends to it, and diffs it.

package/docs/quickstart.md

@@ -0,0 +1,128 @@
+---
+title: "Quickstart"
+description: "Compile a two-node plan, read its step keys, append a third node at the next generation, and diff the two graphs."
+sidebar:
+  order: 2
+---
+
+This quickstart takes one plan from drafts to a keyed graph and grows it. By the
+end you will have a compiled graph with real step keys, a third node added at
+generation 1 with the first two untouched, and a diff that says exactly what
+changed.
+
+Nothing here executes a node or writes a row. A plan is inert: persisting one is
+[`@smthrs/plan-store`](/api/plan-store), and driving one is
+[`@smthrs/engine-store`](/api/engine-store)'s `PlanScheduler`.
+
+## Prerequisites
+
+- Node.js 26.4.0 or later.
+- A package with the dependencies installed. Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+`@effect/platform-node` supplies Effect's `Crypto` service, which is the only
+thing compiling a plan asks for.
+
+## Declare two nodes
+
+Create `quickstart.ts`. A `Plan.NodeDraft` is a node without its key: an id, the
+key material that decides its identity, and the file effects it declares.
+
+```ts
+import * as KeyMaterial from "@smthrs/plan/KeyMaterial"
+import * as Plan from "@smthrs/plan/Plan"
+
+/** Everything hashed about one node. `sealed` is the tier that may be reused across runs. */
+const material = (body: unknown, inputs: ReadonlyArray<KeyMaterial.InputRef> = []): KeyMaterial.KeyMaterial => ({
+  version: KeyMaterial.version,
+  kind: "sealed",
+  body,
+  inputs,
+  layers: [],
+  capabilities: []
+})
+
+/** Two steps: the second consumes the first's result and reads the file it wrote. */
+const drafts: ReadonlyArray<Plan.NodeDraft> = [
+  {
+    id: "read-pr",
+    material: material({ action: "read-pr", pr: 4821 }),
+    effects: { reads: [], writes: ["pr.json"], boundaryMode: "hard" }
+  },
+  {
+    id: "run-tests",
+    material: material({ action: "run-tests" }, [{ _tag: "Ref", from: "read-pr", path: [] }]),
+    effects: { reads: ["pr.json"], writes: ["report.json"], boundaryMode: "hard" }
+  }
+]
+```
+
+The `Ref` input is the only place `run-tests` names `read-pr`. That one
+declaration becomes both the hashed dependency and the graph edge, so an edge
+and a key can never disagree about what a node consumes.
+
+## Compile, append, diff
+
+```ts
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
+import * as PlanDiff from "@smthrs/plan/PlanDiff"
+import * as Effect from "effect/Effect"
+
+const program = Effect.gen(function*() {
+  const plan = yield* Plan.compile({ planId: "review-4821", flow: "example/Review", nodes: drafts })
+  console.log(plan.digest)
+
+  const grown = yield* Plan.append(plan, [{
+    id: "post-comment",
+    material: material({ action: "post-comment" }, [{ _tag: "Pending", from: "run-tests" }]),
+    effects: { reads: ["report.json"], writes: [], boundaryMode: "hard" }
+  }])
+
+  for (const node of grown.nodes) {
+    console.log(node.generation, node.id, node.key, node.dependsOn)
+  }
+  console.log(grown.generation, grown.baseDigest === plan.digest)
+  console.log(PlanDiff.diff(plan, grown).added)
+})
+
+await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer), Effect.orDie))
+```
+
+Run the file with your TypeScript runner. The digests on your machine match
+these, because a plan is a pure function of its declarations:
+
+```text
+key1_61edccc875ff69b798e0c3874d167f65ff0a250b9fe67d27558b854fa2832302
+0 read-pr key1_6353326ab2a03804d6acfe916debc4f04f09f9deb8f0e93c1ebea3cdd983db18 []
+0 run-tests key1_e58229e3be2f6abf6f818baf8577fe7045edba6f5e88097b633898478da93985 [ 'read-pr' ]
+1 post-comment key1_0ac2aef1d5d4226849c6009450ad987b47dc02cf39d39ab975db3c673698241d [ 'run-tests' ]
+1 true
+[ 'post-comment' ]
+```
+
+## What just happened
+
+`Plan.compile` put the drafts in topological order, substituted each dependency
+reference for the already computed key of the node it names, annotated the
+overlap between write sets, and derived the plan digest. It read no file, no
+clock, and no network: the only service it asked for was `Crypto`.
+
+`Plan.append` then produced generation 1. The two original nodes kept their id,
+key, edges, and generation byte for byte, and `post-comment` arrived pre-keyed
+against them. The `true` line is `baseDigest` still naming the digest a human
+would have approved, even though `digest` has moved on.
+
+Read `post-comment`'s edge: it depends on `run-tests`, which it never consumed a
+value from. Two separate declarations put it there. Its `Pending` input is an
+ordering reference, and it reads `report.json`, which `run-tests` writes, so the
+reader-after-writer pass would have ordered it behind the producer anyway.
+
+## Next steps
+
+- [The plan value](./concepts/plan-value.md): generations, digests, and why a
+  plan grows instead of being rewritten.
+- [Step keys](./concepts/step-keys.md): what goes into a key, what deliberately
+  does not, and why invalidation is re-keying.
+- [Diff two plans](./guides/diff-two-plans.md): report what a re-plan changed,
+  attributed to the field that changed it.
+- [Persist a plan](https://plan-store.smithers.sh/guides/persist-a-plan/): the
+  append-only store, in production shape.

package/docs/testing.md

@@ -0,0 +1,73 @@
+---
+title: "Testing"
+description: "How to test code that builds plans: the one service to provide, a real in-memory store, and the assertions worth writing."
+---
+
+## Testing code that builds plans
+
+Compiling asks for Effect's `Crypto` service and nothing else, so a plan test
+needs one layer:
+
+```ts
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
+import type * as Crypto from "effect/Crypto"
+import * as Effect from "effect/Effect"
+
+/** Provides concrete Node cryptography to a test Effect. */
+export const withCrypto = <A, E>(effect: Effect.Effect<A, E, Crypto.Crypto>): Effect.Effect<A, E> =>
+  Effect.provide(effect, NodeCrypto.layer)
+
+/** The same, for an Effect expected to fail: yields the typed error. */
+export const withCryptoFailure = <A, E>(effect: Effect.Effect<A, E, Crypto.Crypto>): Effect.Effect<E, A> =>
+  withCrypto(Effect.flip(effect))
+```
+
+Those two helpers are the whole harness. No clock, no filesystem, and no fake
+anything: a plan is a pure function of its declarations, so a plan test is an
+ordinary value test.
+
+Testing persistence is [`@smthrs/plan-store`](/api/plan-store)'s
+[testing page](https://plan-store.smithers.sh/testing/). It drives the same
+fixtures this package ships at `@smthrs/plan/test/PlanFixtures`, so a draft
+builder is written once and used on both sides.
+
+### Assert on keys, not on shape
+
+A plan's value is that identity is computable. The assertions that earn their
+place say so:
+
+- An edit re-keys its node and its dependent cone, and nothing else.
+- A rename re-keys nothing, because ids are lookup addresses.
+- An ordering edge, a priority change, or a conflict annotation leaves every key
+  where it was.
+- Compiling the same drafts twice produces the same digest.
+
+### Mutate the caller's draft after compiling
+
+A compiled plan is a deep-frozen snapshot. The cheapest proof is to compile,
+mutate the object you passed in, and assert the stored material and the plan
+digest did not move. The values worth trying are a `Date`, a `URL`, and an
+object with a custom `toJSON`, because each one keys through a different path.
+
+### Keep fixtures out of test modules
+
+Importing a `*.test.ts` module registers its suites in the importer, so shared
+fixtures belong in an ordinary module. When one suite pulls a helper out of
+another suite's file, it re-runs every case in that file, and a fast suite
+inherits a slow one's runtime and its timeouts for work it never asked for.
+
+### Keep resource checks independent of wall time
+
+The package runs files serially, including the dense compiler cases with their
+original graph sizes, digest and edge-order assertions. FileSet's synchronous
+adversarial matcher tests charge thread CPU time against the existing 100 ms
+budget, excluding descheduling and work on other threads.
+
+The planned-value lint test builds a dedicated consumer fixture project against
+the real Node types. It asserts the exact conditional-truthiness diagnostics
+without asking the editor project service to discover other workspace projects.
+An isolated Node 24 run measured 6.96 seconds user plus 1.56 seconds system CPU
+with `/usr/bin/time -p`. This case alone allows 70 seconds: eight times that CPU
+cost, rounded up, for a heavily shared host. The package's 30-second default is
+unchanged. Coverage reports and V8 scratch files use a per-process directory so
+concurrent package invocations cannot clean each other's reports.

package/docs/troubleshooting.md

@@ -0,0 +1,314 @@
+---
+title: "Troubleshooting"
+description: "Every refusal @smthrs/plan raises, what causes it, and what to change: build errors, compile errors, and key material errors."
+---
+
+Every failure this package reports is typed and carries a code. Find the code
+and read the matching section. The full error schemas are in the
+[API reference](./api.md).
+
+Three error types, from three layers:
+
+| Type               | Raised by                                      |
+| ------------------ | ---------------------------------------------- |
+| `GraphBuildError`  | Building a node graph, before there is a plan. |
+| `PlanError`        | `Plan.compile` and `Plan.append`.              |
+| `KeyMaterialError` | The step-key compiler.                         |
+
+Persistence raises a fourth, `PlanStoreError`, from
+[`@smthrs/plan-store`](/api/plan-store); its
+[troubleshooting page](https://plan-store.smithers.sh/troubleshooting/) covers
+every code.
+
+## GraphBuildError
+
+Thrown, not failed, because the author reading it is mid-body. Each one names
+the site through `node` plus the recorded property `path`, and states the fix in
+`message`.
+
+### planned_value_computed
+
+**What happened.** A body computed on a step result. The message names the
+value and the operation:
+
+```text
+Planned value read-pr.count was computed at plan time by Symbol.toPrimitive.
+Use Node.map to compute, Node.branch to decide, or pass the value into a payload.
+```
+
+Template interpolation, `String(value)`, arithmetic through a coercion,
+`JSON.stringify` of a payload holding one, calling it, `in`, and enumerating it
+all land here.
+
+**What to change.** Do the computation where it belongs. `Node.map` transforms a
+result, `Node.branch` decides on one, and passing the value into a payload field
+or reading a field off it stays a reference.
+
+`Boolean(value)` and `value === other` cannot be refused, because JavaScript
+exposes no trap for them. They reveal only proxy truthiness or identity and
+never the planned result, so a decision written that way is silently wrong. Use
+`Node.branch`.
+
+### invalid_all_member
+
+**What happened.** `Node.all` received something that is not a node at the named
+member.
+
+**What to change.** Pass a node. An object that merely carries `Node.TypeId` is
+not one: the marker is a public string, and every combinator reads `ast` as
+trusted topology, so a lookalike is refused exactly like any other non-node.
+
+### invalid_join
+
+**What happened.** `Node.race`, `Node.any`, or `Node.quorum` received a non-node
+member, no members, or a quorum count outside 1 to its member count. `node` names
+the member, or the combinator for a count.
+
+**What to change.** Pass at least one node, and a whole-number quorum its members
+can reach.
+
+### invalid_continuation
+
+**What happened.** A branch arm, a catch arm, or a direct `andThen`
+continuation did not return a node. `node` says which: `branch/subject/then`,
+`catch/subject`, or `andThen/next`.
+
+**What to change.** Return a node from the arm. An arm that has nothing to do
+returns `Node.succeed(value)`.
+
+### invalid_priority
+
+**What happened.** `Node.priority` received a value that is not a safe integer.
+
+**What to change.** Pass a safe integer. No ordering could compare anything
+else.
+
+### invalid_payload
+
+**What happened.** A payload member cannot be captured as inert JSON without
+running author code or losing identity: an accessor, or a prototype with no
+`toJSON`. The message names the path:
+
+```text
+Plan payload at $.config.timeout is an accessor
+```
+
+**What to change.** Pass data. Read the accessor yourself and put the value in
+the payload, or give the object a `toJSON` that returns data.
+
+### cyclic_payload
+
+**What happened.** A payload member has a `toJSON` that returns its own
+receiver. It once collapsed to an empty object, which keyed two different values
+identically.
+
+**What to change.** Return data from `toJSON`, not the object itself.
+
+### The codes this package does not raise
+
+`GraphBuildErrorCode` also carries `recursion_requires_boundary`,
+`placement_requires_boundary`, `graph_too_deep`, `duplicate_node`,
+`payload_too_deep`, `unstable_callback`, `effect_outside_envelope`,
+`effect_mode_widening`, `effect_tier_widening`, and
+`capability_outside_grant`. Those come from
+[`@smthrs/flow`](/api/flow)'s graph walk, which shares this vocabulary.
+
+Six more come from [`@smthrs/core`](/api/core)'s graph builder, which raises
+this error rather than a second class of its own: `write_conflict` for two work
+nodes overlapping under `onConflict: "fail"`, where `node` names the first of
+the pair and `Graph.conflicts` carries both; `missing_key_material` for a node
+that reached key compilation without any; `dependency_cycle` for a dependency
+set that cannot be ordered, where `node` names a node in the cycle;
+`plan_too_large` for a node, edge, conflict, or effect-path limit crossed, where
+`node` names the node whose admission crossed it; `payload_too_large` for one
+plan value with more members than the bound, where `path` names the offending
+value path; and `invalid_node` for a malformed node AST. All six are fatal.
+
+The code set is closed so a caller can switch on it across all three packages.
+
+The last four are the effect-authority refusals. `Effects` above defines the
+rule: a declaration may narrow the envelope enclosing it and never widen it.
+
+```text
+Flow "build/write-dist" at "root.flow" declares a path its caller's effect
+envelope does not cover: etc/hosts.
+```
+
+`effect_outside_envelope` names the escaping paths, `effect_mode_widening`
+means an `expected` declaration sits inside a `hermetic` envelope, and
+`effect_tier_widening` means a tier rose where it may only narrow. All three
+are fatal: widen the caller's declared effects, or narrow the callee's.
+
+`capability_outside_grant` is the one advisory code. The call still runs, with
+the capability dropped, so declare it on the caller or stop requiring it on the
+callee.
+
+`unstable_callback` deserves its own note because the fix lives in your flow
+body. `Graph.build` with `callbackIdentity: "stable"` refuses a callback whose
+identity is process-local:
+
+```text
+Callback run at "review" has process-local identity and cannot enter a stable graph.
+```
+
+Wrap the callback in `Node.capture` and declare every semantic capture,
+including the version of any imported implementation, so it keys by content
+instead of by process.
+
+## PlanError
+
+Failed, not thrown: `compile` and `append` return an Effect.
+
+### cycle
+
+**What happened.** Either material dependencies close a cycle:
+
+```text
+Plan cycle through node run-tests
+```
+
+or a reader-after-writer edge contradicts an inferred ordering:
+
+```text
+Plan cycle: node lint reads dist/bundle.js, which node bundle produces, so lint must
+follow bundle, but bundle already depends on lint through bundle -> report -> lint
+```
+
+**What to change.** For the first, break the dependency loop in the declarations.
+For the second, inspect the inferred producer and `serialize` edges. If the
+reader needs the new output, put the producer first or separate unrelated
+overlapping writes. If it intentionally reads the earlier version, express that
+sequence with a `Ref` or `Pending` dependency path from the writer to the reader.
+Explicit read-before-write sequencing is valid; declaration order alone is not
+an explicit version choice. Two unordered nodes that each need the other's new
+output still form a cycle and must be split into stages.
+
+### unknown_dependency
+
+**What happened.** A `Ref` or `Pending` names a node that is neither in the
+drafts nor already in the plan.
+
+**What to change.** Check the `from` spelling against the node ids in the same
+compile. On an `append`, remember that the reference may name a node from an
+earlier generation, which is legal, but not one that was never recorded.
+
+### duplicate_node
+
+**What happened.** A draft reuses an id the plan already holds.
+
+**What to change.** Rename one of them. A node id is durable dispatch identity,
+so two nodes may never share one.
+
+### overlap_forbidden
+
+**What happened.** Two nodes that both asked for the `fail` verdict genuinely
+write overlapping paths, and no dependency path orders them:
+
+```text
+Nodes bundle and minify both write dist/bundle.js
+```
+
+**What to change.** `fail` is the verdict for a flow that promises disjointness,
+so the declaration is the thing that broke the promise. Narrow one write set,
+add a dependency that orders the pair, or change `conflictStrategy` to
+`serialize` if serializing is acceptable after all.
+
+### invalid_effects
+
+**What happened.** One path is declared as both a write and a removal.
+
+**What to change.** Pick one. A removal mutates the world exactly as a write
+does, and both plan passes fold the two together, so the pair is a contradiction
+rather than a refinement.
+
+### invalid_node
+
+**What happened.** The broadest code, covering everything a draft can get
+wrong: an empty plan id, flow, or node id; a priority that is not a safe
+integer; a `kind`, `conflictStrategy`, or `runtimeStrategy` outside its literal
+set; key material or an effect declaration this release cannot decode, which
+includes a path that is not workspace-relative; and a material payload holding
+an accessor or an unsupported prototype.
+
+The message names the node and, for a payload, the path:
+
+```text
+Node run-tests has invalid material payload at $.config.timeout
+```
+
+**What to change.** Read the message. Every case names the exact field. For a
+path refusal, [Declare the files a node touches](./guides/declare-file-effects.md)
+lists the forms `workspaceRelative` rejects and why each one is a correctness
+hole rather than a style rule.
+
+### graph_too_large
+
+**What happened.** The plan would hold more than `Plan.maximumPlanNodes` nodes,
+which is 10,000, or effect analysis exceeded 250,000 candidate pairs or
+10,000,000 work units.
+
+```text
+A plan may contain at most 10000 nodes, received 12000
+```
+
+**What to change.** Split the work across flow boundaries. The node ceiling is checked
+before effect analysis. A separate work budget bounds dense conflicts and
+reachability updates, and applies across generations during verification.
+
+### invalid_plan
+
+**What happened.** `Plan.verify` decoded a plan whose content does not hold
+together. Every [`@smthrs/plan-store`](/api/plan-store) read and write runs it,
+so this surfaces from `record`, `append`, and `get`, never from `compile`:
+
+```text
+Plan approval digest does not match its compiled content
+Plan nodes do not match their compiled keys, effects, ordering, or generations
+Node run-tests has an invalid or out-of-order generation
+```
+
+**What to change.** Pass the value `Plan.compile` or `Plan.append` returned.
+A plan that fails here was assembled by hand, mutated after compiling, or
+edited in the database. The store raises a `PlanStoreError` of the same name for
+its own preconditions.
+
+## KeyMaterialError
+
+### non_content_material
+
+**What happened.** `StepKey.fromKeyMaterial` or `StepKey.dispatchIdentity` was
+asked for a key on material whose `kind` is `compensable` or `irreversible`.
+
+**What to change.** Only `sealed` work gets a cross-run content key. Use
+`StepKey.planIdentity` when compiling any tier's declaration, and
+`StepKey.ordinal` when dispatching the other tiers: it mints a run-local key.
+Do not change an action to `sealed` merely to make it plannable.
+
+### missing_dependency
+
+**What happened.** A `Ref` or `Pending` resolved to nothing usable: no entry for
+`from`, an entry that is not an own data property, or a digest that is not a
+string. On the dispatch path, a missing settled result.
+
+**What to change.** Supply every dependency the material names. A `Ref` naming
+`toString` or `constructor` lands here on purpose, because a prototype-named
+dependency would otherwise resolve to an inherited function and collide.
+
+If you see this from a scheduler, a dependent dispatched before its dependency
+settled. The halt rule is what guarantees it cannot: a dependent of failed or
+skipped work never dispatches.
+
+### invalid_environment
+
+**What happened.** An `EnvironmentIdentity` that is neither properly declared
+nor properly run-scoped:
+
+```text
+Undeclared environment identity requires a non-empty runScope
+Declared environment identity must not include runScope
+Environment identity requires a boolean declared field
+```
+
+**What to change.** `declared: true` carries no `runScope`. `declared: false`
+carries a non-empty one, which pins the key to a single run so a step whose
+environment is unknown never serves a cross-run hit.