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

package/docs/concepts/step-keys.md

@@ -0,0 +1,179 @@
+---
+title: "Step keys"
+description: "How key material becomes a step key: sealed content keys, run-local ordinal keys, dependency substitution, and the collisions the compiler is built to refuse."
+sidebar:
+  order: 2
+---
+
+A step key identifies a declaration or a durable execution. It is not, by
+itself, permission to reuse a result across runs. `StepKey` produces these
+identities from the declared `KeyMaterial`.
+
+The derivations answer different questions:
+
+- `StepKey.planIdentity` produces the **plan key** for every effect tier: the key a node is
+  _identified_ by, computed at plan time from the resolved keys of its
+  dependencies.
+- `StepKey.dispatchIdentity` produces a sealed **dispatch key**: the key a run is
+  _cached_ under, computed at execution time from the settled content its
+  dependencies produced.
+
+- `StepKey.ordinal` produces a run-local execution key for non-cacheable work.
+  The plan scheduler scopes it by run, plan, structural node, and declaration
+  fingerprint, so repeated identical effects do not collapse into one action.
+
+Sealed plan keys still use `StepKey.fromKeyMaterial` and retain the existing
+content-key format. Other tiers use a distinct `plan-declaration` namespace
+that binds approvals without claiming cacheability.
+
+## Key material
+
+`KeyMaterial.KeyMaterial` is everything that can change a node's result:
+
+| Field              | What it contributes                                                                   |
+| ------------------ | ------------------------------------------------------------------------------------- |
+| `version`          | `KeyMaterial.version`. Folded into every hashed body, so a bump re-keys everything.   |
+| `kind`             | The tier: `sealed`, `compensable`, or `irreversible`.                                 |
+| `nondeterministic` | Optional. Absence claims determinism; only the explicit declaration changes identity. |
+| `body`             | The node's own opaque declaration.                                                    |
+| `inputs`           | Ordered `InputRef` values: what this node consumes.                                   |
+| `layers`           | The composition identity the step runs under.                                         |
+| `capabilities`     | The authority the step declares.                                                      |
+| `effects`          | Opaque here: canonically serialized, never interpreted.                               |
+| `placement`        | Opaque here, for the same reason.                                                     |
+
+Keeping `effects` and `placement` opaque is what keeps the key compiler
+independent of whatever the flow builder decides an effect declaration looks
+like. `Plan.compile` is stricter than the compiler underneath it: it decodes
+`NodeDraft.effects` through `NodeEffects` and writes the result into
+`material.effects`, replacing anything a caller put there. That makes the draft
+declaration the single derivation point for effect identity, so a node's key
+cannot disagree with the effects its conflict annotations and approval payload
+were computed from.
+
+## Input references
+
+An `InputRef` is one of three tagged variants:
+
+| Variant           | Meaning                                                   |
+| ----------------- | --------------------------------------------------------- |
+| `Literal{value}`  | A value hashed inline.                                    |
+| `Ref{from, path}` | The result of node `from`, projected along `path`.        |
+| `Pending{from}`   | An ordering reference to node `from`, consuming no value. |
+
+The tag is hashed, so `Pending{from}` and `Ref{from, path: []}` cannot collide
+even though both resolve to the same dependency digest.
+
+`KeyMaterial.dependencies` reads the graph-local dependencies a material names,
+in declaration order and without duplicates. It is the single derivation of a
+node's edge set, which is why a hashed reference and an edge can never disagree.
+
+## Sealed, and everything else
+
+Only `sealed` material may become a content key. `StepKey.fromKeyMaterial` fails
+`non_content_material` for the other two tiers, and so does
+`StepKey.dispatchIdentity`.
+
+`StepKey.ordinal` mints the deliberately run-local key of compensable,
+irreversible, or unsealed work, from a run id, an optional parent scope, an
+ordinal, and a `tier` of `compensable`, `irreversible`, or `unsealed`. Those
+keys cannot be reused across runs, which is the point: work that changed the
+world outside the workspace must not be served from a cache.
+
+## What a plan key folds in
+
+`planIdentity` substitutes each `Ref` and `Pending` for the already computed
+key of the referenced node. For sealed material it delegates to
+`fromKeyMaterial`; other tiers produce a tier-bearing declaration fingerprint.
+
+Structural node ids do not enter the plan key. Renaming a node preserves its
+declaration fingerprint. A non-cacheable execution key does include its
+structural address: renaming an effect must not accidentally replay a different
+invocation. Changing what a node consumes changes downstream plan keys.
+
+A dependency digest is resolved as an own data property. A `Ref` naming
+`toString` or `constructor` is a `missing_dependency` refusal rather than a
+colliding key, and so is a digest supplied through an accessor or as a non-string.
+
+## What a dispatch key folds in instead
+
+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.
+
+`dispatchIdentity` gives the JSON value channel the property the file channel
+already had through measured boundary digests. It folds the node's own material
+and never an upstream key. Each 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, because ordering does not change
+what a node consumes.
+
+`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.
+
+## Projection
+
+`StepKey.project` is the one projection semantics for the value channel. It
+resolves only own data properties, so a path segment that is missing, inherited,
+or an accessor yields `undefined` and no getter runs during key derivation.
+
+Walking 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`.
+
+Every consumer that resolves a `Ref` at execution time must resolve it this same
+way. Two inputs that key identically but are consumed differently is a stale-hit
+vector, and one shared projection is what closes it.
+
+## The collisions this compiler refuses
+
+Each of these is a fix that stayed.
+
+**A literal that looks like a digest.** The brand behind `StepKey.digestInput`
+is private, so a plain object that merely has a `digest` field hashes as a
+literal. Actions pass content hashes around as ordinary data; shape sniffing
+would have hashed a genuine upstream-result reference and an ordinary content
+hash identically.
+
+**Environment material merged into the caller's.** `environment` is hashed in
+its own namespace, so `caller{fs:["a"]} + env{fs:["b"]}` cannot alias
+`caller{fs:["a","b"]} + env{}`. Environment layers keep declaration order,
+because composition order can change behavior; caller-owned layers are
+set-normalized.
+
+**An unknown environment serving a cross-run hit.** `EnvironmentIdentity` is a
+discriminated union. A declared environment carries no `runScope`; an undeclared
+one must carry a non-empty one, which pins the key to a single run. Both
+`content` and `dispatchIdentity` enforce that at run time with
+`invalid_environment`.
+
+**A bumped format keying like the old one.** `version` is folded into every
+hashed body, so a change to what material means re-keys every node derived from
+it.
+
+## Sharing work between keys
+
+`StepKey.makeDigestMemo` creates a memo that shares one in-flight projected
+value digest between concurrent callers, addressed by the `[from, path]` tuple.
+Pass it to `dispatchIdentity` through `digestMemo` when several keys in one
+wavefront project the same upstream result.
+
+Entries are sound only while each settled `from` value is immutable, so create a
+fresh memo when those values can change.
+
+A waiter never inherits the leader's interruption. If the leader's fiber is
+cancelled, the waiter competes to become the replacement leader and recomputes,
+rather than failing on an interrupt it did not request.
+
+## Failures
+
+`StepKey.KeyMaterialError` carries one of three codes:
+
+| `code`                 | Cause                                                                         |
+| ---------------------- | ----------------------------------------------------------------------------- |
+| `invalid_environment`  | An environment identity that is neither properly declared nor run-scoped.     |
+| `missing_dependency`   | A reference whose digest or settled result is absent, inherited, or mistyped. |
+| `non_content_material` | A content or dispatch key was asked for on non-sealed material.               |
+
+[Troubleshooting](../troubleshooting.md) states the fix for each one.

package/docs/guides/author-a-node-graph.md

@@ -0,0 +1,182 @@
+---
+title: "Author a node graph"
+description: "Build topology with the Node combinators, pass step results as planned values, and turn the result into the drafts Plan.compile takes."
+sidebar:
+  order: 1
+---
+
+`Node` is the authoring AST: pure, pipeable values that describe what a run will
+do. This guide builds a graph with it and turns that graph into
+`Plan.NodeDraft` values.
+
+Most flow authors reach this layer through [`@smthrs/flow`](/api/flow), which
+walks a flow body for you. Reach for `Node` directly when you are writing that
+walk, testing topology, or composing a graph outside a flow declaration.
+
+## Start from a value
+
+`Node.succeed` lifts a constant. Nothing runs:
+
+```ts
+import * as Node from "@smthrs/plan/Node"
+
+const lint = Node.succeed("lint")
+```
+
+## Transform with map
+
+`Node.map` defers a pure function. It is digested at build time and applied to
+the real value later:
+
+```ts
+const shouted = Node.map(Node.succeed({ name: "world" }), (value) => value.name.toUpperCase())
+```
+
+Use `map` for computation only. A `map` that chooses what happens next is a
+`branch` written wrongly, and the plan loses the topology a reviewer needs to
+see.
+
+## Sequence nodes and bind planned references
+
+`Node.andThen(first, next)` sequences two nodes when the first result is not needed.
+Use `Node.bindPlanned(first, build)` when the next node consumes a reference to
+that result. The builder runs once at plan time against a `Planned` placeholder:
+
+```ts
+import { Action } from "@smthrs/flow"
+import type * as Planned from "@smthrs/plan/Planned"
+import * as Schema from "effect/Schema"
+
+const Draft = Action.make("docs/Draft", {
+  payload: { topic: Schema.String },
+  success: Schema.String,
+  error: Schema.String
+})
+
+const Publish = Action.make("docs/Publish", {
+  payload: { text: Schema.String, urgent: Schema.Boolean },
+  success: Schema.String
+})
+
+const article = Node.bindPlanned(
+  Draft.call({ topic: "durable plans" }),
+  (text: Planned.Planned<string>) => Publish.call({ text, urgent: false })
+)
+```
+
+`text` is a placeholder, not a string. Pass it into a payload field, read a
+field off it, hand it to a branch: all of that records a reference. Computing on
+it can throw `planned_value_computed` with the node and path named. JavaScript
+truthiness and strict equality cannot be trapped: they inspect the reference,
+not its future result. Use `Node.branch` for decisions and `Node.map` for real-value
+computation. Enable the type-aware ESLint rule
+`@typescript-eslint/strict-boolean-expressions: "error"` to reject planned values
+in conditions. Explicit `Boolean(reference)` and reference equality still require
+review. [The authoring AST](../concepts/authoring-ast.md) explains the reference contract.
+
+## Decide with branch
+
+Both arms are built once, symbolically, so the plan carries the exit condition
+and both continuations before anything runs:
+
+```ts
+const decided = Node.bindPlanned(
+  Draft.call({ topic: "durable plans" }),
+  (text: Planned.Planned<string>) =>
+    Node.branch(Node.succeed({ urgent: true }), {
+      if: (flags) => flags.urgent,
+      then: () => Publish.call({ text, urgent: true }),
+      else: () => Publish.call({ text, urgent: false })
+    })
+)
+```
+
+`if` runs later, on the real value. `then` and `else` run now, once each.
+
+## Recover with catch
+
+`Node.catch` stores the failure arm as topology beside the protected graph.
+Without an `error` schema it handles the whole typed error channel; with one it
+handles only the values that schema accepts, and the rest survives in the
+resulting error type:
+
+```ts
+const recovered = Node.catch(Draft.call({ topic: "fallbacks" }), {
+  onFailure: () => Node.succeed("draft unavailable")
+})
+```
+
+## Fan out with all
+
+`Node.all` combines independent children by name. Its width is fixed here, at
+build time:
+
+```ts
+const batched = Node.all({
+  lint: Node.priority(Node.succeed("lint"), 10),
+  types: Node.succeed("types")
+})
+```
+
+To fan out over something a step discovered, end the round and carry the list in
+the next flow's payload, where it is real data. A plan is a DAG and cannot grow
+a leg it did not declare.
+
+## Prioritize without re-keying
+
+`Node.priority` attaches a scheduling priority and leaves the original node
+unchanged. Higher runs first among ready work, so a priority changes latency and
+nothing else. It never enters key material, so a prioritized node keeps its
+cache hit. Children inherit the value lexically when the graph is built, and a
+child that states its own keeps it.
+
+`Node.declaredPriority(ast)` reads back the value a node states, or `undefined`
+when it inherits.
+
+`Node.priority` refuses anything that is not a safe integer with
+`invalid_priority`, because no ordering could compare it.
+
+## Declare captures for a deterministic digest
+
+The AST stores a digest of a function's exact source, never the closure. A
+function with undeclared captures also carries process-local entropy, so two
+indistinguishable sources fail closed rather than sharing a cache key. Declare
+the inert values a function closes over to get a deterministic identity instead:
+
+```ts
+const suffixed = Node.capture({ suffix: "!" }, (value: string) => `${value}!`)
+```
+
+## Turn the graph into drafts
+
+`Plan.compile` takes `NodeDraft` values, and [`@smthrs/flow`](/api/flow) is what
+produces them. `Graph.build` walks a flow declaration or a bare node once;
+`Graph.drafts` reads the drafts back:
+
+```ts
+import { Flow, Graph } from "@smthrs/flow"
+import * as Plan from "@smthrs/plan/Plan"
+
+const Article = Flow.make("docs/Article", {
+  payload: { topic: Schema.String },
+  success: Schema.String,
+  error: Schema.String,
+  body: ({ topic }: { readonly topic: string }) =>
+    Node.bindPlanned(Draft.call({ topic }), (text: Planned.Planned<string>) => Publish.call({ text, urgent: false }))
+})
+
+const drafts: ReadonlyArray<Plan.NodeDraft> = Graph.drafts(Graph.build(Article, { topic: "plans" }))
+```
+
+`Graph.drafts` throws the first typed build refusal rather than returning
+partial drafts, because returning them would turn missing topology into a valid
+plan. `Graph.diagnostics` lists the recoverable issues a build recorded; fatal
+refusals, including computing on a planned value, throw from `Graph.build`
+itself.
+
+## Next
+
+- [Compile drafts into a plan](./compile-a-plan.md): keys, ordering, conflict
+  annotation, and the digest.
+- [The authoring AST](../concepts/authoring-ast.md): why building runs nothing,
+  and how a closure survives as a digest.

package/docs/guides/compile-a-plan.md

@@ -0,0 +1,146 @@
+---
+title: "Compile drafts into a plan"
+description: "Turn NodeDraft values into a keyed graph: what compile does in order, the one service it needs, and every refusal it can answer with."
+sidebar:
+  order: 2
+---
+
+`Plan.compile` is the whole plan phase in one function. Hand it drafts, get back
+a keyed graph with a digest.
+
+```ts
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
+import * as KeyMaterial from "@smthrs/plan/KeyMaterial"
+import * as Plan from "@smthrs/plan/Plan"
+import * as Effect from "effect/Effect"
+
+const readPr: Plan.NodeDraft = {
+  id: "read-pr",
+  material: {
+    version: KeyMaterial.version,
+    kind: "sealed",
+    body: { action: "read-pr", pr: 4821 },
+    inputs: [],
+    layers: [],
+    capabilities: ["net:get"]
+  },
+  effects: { reads: [], writes: ["pr.json"], boundaryMode: "hard" }
+}
+
+const runTests: Plan.NodeDraft = {
+  id: "run-tests",
+  material: {
+    version: KeyMaterial.version,
+    kind: "sealed",
+    body: { action: "run-tests" },
+    inputs: [{ _tag: "Ref", from: "read-pr", path: [] }],
+    layers: [],
+    capabilities: []
+  },
+  effects: { reads: ["pr.json"], writes: ["report.json"], boundaryMode: "hard" },
+  priority: 10,
+  conflictStrategy: "serialize",
+  runtimeStrategy: "delay-rebase"
+}
+
+const compiled = Plan.compile({
+  planId: "review-4821",
+  flow: "example/Review",
+  nodes: [readPr, runTests]
+}).pipe(Effect.provide(NodeCrypto.layer))
+```
+
+## What a draft carries
+
+| Field              | Required | What it decides                                                                                                            |
+| ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `id`               | yes      | The durable lookup address. Not part of the declaration fingerprint; non-cacheable execution uses it as a run-local scope. |
+| `material`         | yes      | Everything the key is derived from.                                                                                        |
+| `effects`          | yes      | Declared reads, writes, optional removals, and the boundary mode.                                                          |
+| `kind`             | no       | `step`, `agent`, or `merge`. Defaults to `step`.                                                                           |
+| `priority`         | no       | Scheduling tie-break. Defaults to 0.                                                                                       |
+| `conflictStrategy` | no       | This node's preferred plan-time verdict for an overlap. Defaults to `serialize`.                                           |
+| `runtimeStrategy`  | no       | This node's preferred response when an overlap bites. Defaults to `delay-rebase`.                                          |
+
+## What compile does, in order
+
+1. Validates `planId`, `flow`, and every draft, decoding `material` and
+   `effects` through their schemas.
+2. Puts the drafts in topological order from the dependencies their material
+   names.
+3. Keys each node, substituting every `Ref` and `Pending` for the already
+   computed key of the node it names.
+4. Annotates overlapping write sets and adds the ordering edges the verdicts
+   imply.
+5. Adds reader-after-writer edges where explicit `Ref`/`Pending` paths have not
+   already selected read-before-write sequencing. A read before a writer
+   consumes an earlier version, not that later writer's output. Contradictory
+   inferred orderings still fail with `cycle`.
+6. Derives the plan digest over the whole result.
+
+The nodes come back in topological order of material dependencies, deep-frozen,
+at generation 0, with `baseDigest` equal to `digest`. Inferred edges extend
+`dependsOn` without reordering the array. For example, a reader declared before
+an independent writer stays first in `plan.nodes`, even when its `dependsOn`
+contains that writer. Schedule nodes from the complete `dependsOn` graph;
+iterating the array alone can run a reader before its producer.
+
+## The one service it needs
+
+Compiling asks for Effect's `Crypto` service and nothing else. Provide it from a
+platform package:
+
+```ts
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
+
+const plan = compiled.pipe(Effect.provide(NodeCrypto.layer))
+```
+
+In a browser, provide the browser platform's `Crypto` layer instead. No part of
+compilation reaches a file, a clock, or a network.
+
+## Your drafts are copied, not held
+
+`compile` snapshots its options before it does anything else, and the plan it
+returns is deep-frozen. Mutating a draft afterwards cannot change the plan, its
+keys, or its digest. Material is stored as the inert JSON mirror its key already
+covers, so a `Date` or `URL` in a body is stored as the value it serializes to.
+
+## When compile refuses
+
+`PlanError` is a closed set of seven codes, so a caller can switch on `code`.
+
+| `code`               | Cause                                                                                                                              |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `cycle`              | Material dependencies close a cycle, or a reader-after-writer edge would close one.                                                |
+| `unknown_dependency` | A `Ref` or `Pending` names a node that is neither in the drafts nor already in the plan.                                           |
+| `duplicate_node`     | A draft reuses an id the plan already holds.                                                                                       |
+| `overlap_forbidden`  | A `fail` pair genuinely overlaps and no dependency path orders it.                                                                 |
+| `invalid_effects`    | One path is declared as both a write and a removal.                                                                                |
+| `invalid_node`       | An empty id or flow, a priority that is not a safe integer, a value outside a literal set, or material this release cannot decode. |
+| `graph_too_large`    | The plan would hold more than `Plan.maximumPlanNodes` nodes.                                                                       |
+
+All three effect tiers compile. `StepKey.planIdentity` produces approval-bound
+declaration fingerprints; compilation does not grant cache eligibility.
+`compile` can also fail with `StepKey.KeyMaterialError` when a dependency
+digest is missing, and with a `Schema.SchemaError` from decoding.
+[Troubleshooting](../troubleshooting.md) states the fix for each one.
+
+## Size
+
+`Plan.maximumPlanNodes` is 10,000. The conflict and reader-after-writer passes
+compare node pairs, so the cost is at least quadratic in node count, and each
+pair whose write sets actually overlap adds one on-demand reachability walk.
+A plan above the ceiling is refused before any pair is compared.
+
+If you are approaching the ceiling, split the work across flow boundaries rather
+than raising it: a plan that large is also a plan no operator can review.
+
+## Next
+
+- [Persist a plan](https://plan-store.smithers.sh/guides/persist-a-plan/): record the compiled value and read it
+  back.
+- [Declare the files a node touches](./declare-file-effects.md): the vocabulary
+  behind step 4 and step 5.
+- [Step keys](../concepts/step-keys.md): what step 3 folds in, and what it
+  deliberately leaves out.

package/docs/guides/declare-file-effects.md

@@ -0,0 +1,143 @@
+---
+title: "Declare the files a node touches"
+description: "Write a node's read, write, and removal sets with FileSet: literal paths, globs, tree artifacts, filegroups, and the forms a workspace-relative path may not take."
+sidebar:
+  order: 6
+---
+
+`FileSet` is the static filesystem vocabulary planning and execution share.
+A node's `effects` are written in it, and everything the plan knows about
+conflicts comes from what you declare here.
+
+```ts
+import * as Plan from "@smthrs/plan/Plan"
+
+const effects: Plan.NodeEffects = {
+  reads: [{ _tag: "Glob", include: ["src/**/*.ts"] }],
+  writes: ["dist/bundle.js"],
+  removes: ["dist/stale.js"],
+  boundaryMode: "hard"
+}
+```
+
+## The four declaration forms
+
+| Form           | Written as                                | Where it is valid          |
+| -------------- | ----------------------------------------- | -------------------------- |
+| `Pattern`      | A workspace-relative literal path string. | reads, writes, and removes |
+| `Glob`         | `{_tag: "Glob", include, exclude?}`       | reads and writes           |
+| `TreeArtifact` | `{_tag: "TreeArtifact", path}`            | writes only                |
+| `Filegroup`    | `{_tag: "Filegroup", name, entries}`      | reads and writes           |
+
+Bare string entries are literal paths at both overlap analysis and execution,
+even when they contain `*` or `**`. Use `Glob.include` and `Glob.exclude` for
+wildcard matching in read and write declarations.
+
+```ts
+import * as FileSet from "@smthrs/plan/FileSet"
+
+const sources: FileSet.Glob = {
+  _tag: "Glob",
+  include: ["src/**/*.ts"],
+  exclude: ["src/**/*.test.ts"]
+}
+
+const bundle: FileSet.TreeArtifact = { _tag: "TreeArtifact", path: "dist" }
+
+const group: FileSet.Filegroup = FileSet.makeFilegroup("sources", [sources, "package.json"])
+```
+
+A tree artifact is a whole directory captured and replayed as one output. It
+belongs in a write set, and `ReadEntry` deliberately excludes it: a read set
+names what the node consumes, and a directory output is not that.
+
+## Expanding a filegroup
+
+A filegroup is a name for a reusable collection. Both plan passes expand groups
+before they compare anything, and `expand` does the same for a caller,
+deterministically and in declaration order:
+
+```ts
+const flattened: ReadonlyArray<FileSet.Entry> = FileSet.expand([group, bundle])
+const reads: ReadonlyArray<FileSet.ReadEntry> = FileSet.expandReads([
+  { _tag: "Filegroup", name: "sources", entries: [sources] }
+])
+```
+
+`expandReads` is the read-set counterpart, typed so a tree artifact cannot
+appear in the result.
+
+## What a workspace-relative path may not be
+
+`workspaceRelative` decides whether a declaration names a file one way only. It
+refuses:
+
+- Absolute paths, POSIX (`/etc/passwd`) and drive-letter (`C:/tmp`), and the
+  drive-relative `C:tmp`.
+- Upward traversal: any `..` segment.
+- Aliasing forms: `.` segments and empty segments.
+- C0 controls (U+0000 through U+001F) and DEL (U+007F).
+
+C1 controls (U+0080 through U+009F) stay legal, because those bytes are valid in
+a POSIX file name.
+
+The aliasing rules are correctness, not tidiness. Two spellings of one file that
+the overlap check cannot see would let a plan run a reader and its writer in the
+same wavefront round.
+
+## Canonical form
+
+`canonical` rewrites every separator to `/` and normalizes Unicode to NFC. Every
+exact-path comparison in the module goes through it:
+
+```ts
+const same = FileSet.canonical("dist\\bundle.js") === FileSet.canonical("dist/bundle.js") // true
+```
+
+So the backslash spelling and the NFD spelling of one workspace path overlap.
+A glob, by contrast, tests the path bytes it is handed: canonicalizing a
+_measured_ path before matching it is the caller's decision, because a backslash
+inside a path segment is literal text on a POSIX filesystem.
+
+Overlap goes one step further and compares `folded`, the canonical form with
+letter case folded away. A case-insensitive filesystem opens `src/A.ts` and
+`src/a.ts` as one file, so two nodes writing them serialize.
+
+## Matching and overlap
+
+| Function                        | Answers                                           |
+| ------------------------------- | ------------------------------------------------- |
+| `matchesPattern(pattern, path)` | Whether one path matches one Bazel-style pattern. |
+| `matchesGlob(glob, path)`       | The same, honoring the glob's `exclude` list.     |
+| `overlaps(left, right)`         | Whether two entries might share a path.           |
+| `isGlob`, `isTreeArtifact`      | Which variant an entry is.                        |
+
+In `Glob.include`, `Glob.exclude`, and the `matchesPattern` helper, `**` matches
+path segments; `*` matches within one segment and never crosses a separator. A
+trailing `**` matches the rest of the path. Calling `matchesPattern` directly does
+not change how a bare string declaration is interpreted.
+
+`overlaps` is conservative by design: `true` may over-serialize, and `false`
+proves that no path can belong to both declarations. Two globs always overlap,
+and so do a glob and a tree artifact.
+
+## Writes and removals are one set
+
+A removal mutates the world exactly as a write does, so both plan passes fold
+`writes` and `removes` together. Declaring one path as both fails compilation
+with `invalid_effects`, because the declaration contradicts itself.
+
+`removes` accepts literal path strings only, not globs or tree artifacts.
+
+## Boundary mode
+
+`boundaryMode` is `hard` or `expected`. It travels with the declaration into the
+measured boundary at execution time. The plan passes do not interpret it: they
+only need to know which paths a node produces and which it consumes.
+
+## Next
+
+- [Declared effects and conflicts](../concepts/effects-and-conflicts.md): what
+  the two plan passes do with these declarations.
+- [Compile drafts into a plan](./compile-a-plan.md): where effects are decoded
+  and written back into key material.