@smthrs/plan 1.0.0-rc.7 → 1.0.0-rc.9

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

@@ -1,6 +1,6 @@
 ---
 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, why node ids are positional, and why the report is in no digest."
+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, how a step whose positional id moved is paired by its key, and why the report is in no digest."
 sidebar:
   order: 5
 ---
@@ -17,10 +17,10 @@ add this package and `@smthrs/flow` at the version of `@smthrs/flows` you have,
 plus the platform package:
 
 ```bash
-npm install @smthrs/plan@1.0.0-rc.7 @smthrs/flow@1.0.0-rc.7 @effect/platform-node
+npm install @smthrs/plan@1.0.0-rc.9 @smthrs/flow@1.0.0-rc.9 @effect/platform-node
 ```
 
-The outputs below are real output from 1.0.0-rc.6.
+The outputs below are real output from the release that install line names.
 
 ## Compare a re-plan
 
@@ -90,15 +90,16 @@ 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:
+Two nodes with the same key are the same step, under the same id or a moved
+one. 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.                              |
+| Field       | Contents                                                              |
+| ----------- | --------------------------------------------------------------------- |
+| `added`     | Node ids in `next` that pair with no node in `previous`.              |
+| `removed`   | Node ids in `previous` that pair with no node in `next`.              |
+| `rekeyed`   | Nodes paired by id whose key moved, with `from`, `to`, and `changed`. |
+| `unchanged` | Node ids in `next` paired with a node of the same key.                |
 
 ## The attribution is for a human
 
@@ -126,90 +127,76 @@ on a re-keyed node as a bug report, not as noise.
 ## Node ids are positional
 
 A node id is the node's structural address in the body, such as
-`root.flow.andThen`, not the name of its step. Appending a step to a flow
-nests the steps before it one level deeper, so a diff by id reports an
-unchanged step as `added` under its new address and reports the addresses it
-left as `rekeyed`. The step's key does not change.
+`root.flow.andThen`, not the name of its step. Adding a step to a flow can move
+the steps around it to new addresses while their keys stay the same. `diff`
+therefore pairs nodes in three passes, each over the nodes no earlier pass
+paired:
 
-Create `positional.ts`. It compiles a two-step flow and the same flow with a
-third step appended, diffs them, then matches the steps by key:
+1. The same id with the same key: unchanged.
+2. The same key under a different id: the same step at a new address, reported
+   as unchanged under its id in `next`.
+3. The same id with a different key: re-keyed.
+
+Whatever is left in `next` is `added`, and whatever is left in `previous` is
+`removed`. `added`, `rekeyed`, and `unchanged` name nodes by their id in
+`next`; `removed` names nodes by their id in `previous`.
+
+Create `inserted.ts`. It compiles two steps, then the same two steps with a
+third inserted before them, so every id shifts by one:
 
 ```ts
 import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
-import { Action, Flow, Graph } from "@smthrs/flow"
-import { Node } from "@smthrs/plan"
+import * as KeyMaterial from "@smthrs/plan/KeyMaterial"
 import * as Plan from "@smthrs/plan/Plan"
 import * as PlanDiff from "@smthrs/plan/PlanDiff"
 import * as Effect from "effect/Effect"
-import * as Schema from "effect/Schema"
-
-const Draft = Action.make("fix/Draft", { payload: { issue: Schema.String }, success: Schema.String })
-const Test = Action.make("fix/Test", { payload: { plan: Schema.String }, success: Schema.String })
-const Report = Action.make("fix/Report", { payload: { result: Schema.String }, success: Schema.String })
 
-const before = Flow.make("fix/Fix", {
-  payload: { issue: Schema.String },
-  success: Schema.String,
-  body: (input) => Draft.call(input).pipe(Node.bindPlanned((plan) => Test.call({ plan })))
-})
-
-/** The same flow with one step appended. Draft and Test are unchanged. */
-const after = Flow.make("fix/Fix", {
-  payload: { issue: Schema.String },
-  success: Schema.String,
-  body: (input) =>
-    Draft.call(input).pipe(
-      Node.bindPlanned((plan) => Test.call({ plan })),
-      Node.bindPlanned((result) => Report.call({ result }))
-    )
+/** A step whose id is its position, as a flow's structural ids are. */
+const step = (position: number, action: string): Plan.NodeDraft => ({
+  id: `step-${position}`,
+  material: {
+    version: KeyMaterial.version,
+    kind: "sealed",
+    body: { action },
+    inputs: [],
+    layers: [],
+    capabilities: []
+  },
+  effects: { reads: [], writes: [], boundaryMode: "hard" }
 })
 
-const planOf = (flow: Parameters<typeof Graph.build>[0]) =>
-  Plan.compile({ planId: "fix-1", flow: "fix/Fix", nodes: Graph.drafts(Graph.build(flow, { issue: "#42" })) })
-
-/** The action a step node runs, read from its key material. */
-const actionOf = (node: Plan.PlanNode) => {
-  const body = node.material.body
-  return typeof body === "object" && body !== null && "action" in body ? String(body.action) : undefined
-}
+const compile = (actions: ReadonlyArray<string>) =>
+  Plan.compile({
+    planId: "checks-1",
+    flow: "example/Checks",
+    nodes: actions.map((action, index) => step(index, action))
+  })
 
 const program = Effect.gen(function*() {
-  const previous = yield* planOf(before)
-  const next = yield* planOf(after)
-  const changes = PlanDiff.diff(previous, next)
-  console.log("added    ", changes.added)
-  console.log("rekeyed  ", changes.rekeyed.map((entry) => entry.id))
-  console.log("unchanged", changes.unchanged)
-
-  // Match steps by key, not by id: an equal key is the same step.
-  const recorded = new Set(previous.nodes.map((node) => node.key))
-  for (const node of next.nodes) {
-    const action = actionOf(node)
-    if (action !== undefined) console.log(`${action.padEnd(11)} ${recorded.has(node.key) ? "same key" : "new key"}`)
-  }
+  const previous = yield* compile(["lint", "test"])
+  const next = yield* compile(["format", "lint", "test"])
+  console.log(PlanDiff.diff(previous, next))
 }).pipe(Effect.provide(NodeCrypto.layer))
 
 await Effect.runPromise(program)
 ```
 
 ```bash
-node positional.ts
+node inserted.ts
 ```
 
 ```text
-added     [ 'root.flow.andThen.andThen', 'root.flow.andThen.then' ]
-rekeyed   [ 'root.flow.andThen', 'root.flow.then', 'root.flow', 'root' ]
-unchanged []
-fix/Draft   same key
-fix/Test    same key
-fix/Report  new key
+{
+  added: [ 'step-0' ],
+  removed: [],
+  rekeyed: [],
+  unchanged: [ 'step-1', 'step-2' ]
+}
 ```
 
-Only `Report` is new. `Draft` and `Test` moved to `root.flow.andThen.andThen`
-and `root.flow.andThen.then` with the keys they had, so they come back under
-`added`; their old ids now hold other nodes and come back under `rekeyed`. To
-ask which steps changed, compare keys rather than ids, as the last loop does: a
-key present in both plans is the same step.
+Only the inserted `format` step is new. `lint` and `test` moved from `step-0`
+and `step-1` to `step-1` and `step-2` with the keys they had, so they come back
+as `unchanged`.
 
 ## Comparison uses the key's own JSON semantics
 
@@ -229,10 +216,87 @@ 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. That reading holds while the shape stays put. Once a step is added
-or removed, ids move, so read the work by key as
+will skip. That reading holds when a step is added or removed and ids move,
+because `diff` pairs a moved step by its key, as
 [Node ids are positional](#node-ids-are-positional) shows.
 
+On a body built with `Flow.make`, `added` and `rekeyed` also list structural
+nodes: each `AndThen` that sequences steps, and the `FlowCall` at `root`. Their
+keys fold their children's keys, so they move whenever a child does, and they
+run no work. Count steps as the entries whose material body names an `action`.
+
+Create `replan.ts`. It appends a `Summarize` step to a two-step review and
+compares the two plans:
+
+```ts
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
+import { Action, Flow, Graph } from "@smthrs/flow"
+import { Node } from "@smthrs/plan"
+import * as Plan from "@smthrs/plan/Plan"
+import * as PlanDiff from "@smthrs/plan/PlanDiff"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+
+const ReadPr = Action.make("review/ReadPr", { payload: { pr: Schema.Number }, success: Schema.String })
+const RunTests = Action.make("review/RunTests", { payload: { diff: Schema.String }, success: Schema.String })
+const Summarize = Action.make("review/Summarize", { payload: { report: Schema.String }, success: Schema.String })
+
+const review = (summarize: boolean) =>
+  Flow.make("review/Review", {
+    payload: { pr: Schema.Number },
+    success: Schema.String,
+    body: (payload) => {
+      const tested = ReadPr.call(payload).pipe(Node.bindPlanned((diff) => RunTests.call({ diff })))
+      return summarize ? tested.pipe(Node.bindPlanned((report) => Summarize.call({ report }))) : tested
+    }
+  })
+
+const compile = (summarize: boolean) =>
+  Plan.compile({
+    planId: "review-4821",
+    flow: "review/Review",
+    nodes: Graph.drafts(Graph.build(review(summarize), { pr: 4821 }))
+  })
+
+/** A step is a node whose material body names an action; the rest only compose steps. */
+const isStep = (node: Plan.PlanNode) => {
+  const body = node.material.body
+  return typeof body === "object" && body !== null && "action" in body
+}
+
+const program = Effect.gen(function*() {
+  const previous = yield* compile(false)
+  const next = yield* compile(true)
+  const changes = PlanDiff.diff(previous, next)
+  const steps = new Set(next.nodes.filter(isStep).map((node) => node.id))
+  console.log({
+    added: changes.added,
+    rekeyed: changes.rekeyed.map((entry) => entry.id),
+    addedSteps: changes.added.filter((id) => steps.has(id)),
+    rekeyedSteps: changes.rekeyed.filter((entry) => steps.has(entry.id)).map((entry) => entry.id)
+  })
+}).pipe(Effect.provide(NodeCrypto.layer))
+
+await Effect.runPromise(program)
+```
+
+```bash
+node replan.ts
+```
+
+```text
+{
+  added: [ 'root.flow.andThen', 'root.flow.then' ],
+  rekeyed: [ 'root.flow', 'root' ],
+  addedSteps: [ 'root.flow.then' ],
+  rekeyedSteps: []
+}
+```
+
+One step was added: `Summarize`, at `root.flow.then`. `ReadPr` and `RunTests`
+moved under the new `AndThen` with the keys they had, so they are `unchanged`.
+The other three entries are structure: two `AndThen` nodes and the `FlowCall`.
+
 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.

package/docs/installation.md

@@ -13,7 +13,11 @@ sidebar:
 
 ## Install
 
-Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+```bash
+npm install @smthrs/plan@next effect
+```
+
+The `next` tag carries the 1.0 release candidates.
 
 That is enough to build node graphs, compile plans, and diff them. Compiling
 asks for Effect's `Crypto` service, which a platform package supplies:

package/docs/quickstart.md

@@ -17,7 +17,7 @@ Nothing here executes a node or writes a row. A plan is inert: persisting one is
 ## 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).
+- A project with the packages installed: `npm install @smthrs/plan@next @effect/platform-node effect`.
 
 `@effect/platform-node` supplies Effect's `Crypto` service, which is the only
 thing compiling a plan asks for.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@smthrs/plan",
   "type": "module",
-  "version": "1.0.0-rc.7",
+  "version": "1.0.0-rc.9",
   "license": "MIT",
   "smthrs": {
     "group": "engine"
@@ -218,9 +218,9 @@
     "tag": "next"
   },
   "dependencies": {
-    "@smthrs/crypto": "1.0.0-rc.7",
-    "@smthrs/keys": "1.0.0-rc.7",
-    "@smthrs/canonical": "1.0.0-rc.7"
+    "@smthrs/crypto": "1.0.0-rc.9",
+    "@smthrs/keys": "1.0.0-rc.9",
+    "@smthrs/canonical": "1.0.0-rc.9"
   },
   "devDependencies": {
     "@effect/language-service": "0.87.2",

package/src/Effects.ts

@@ -139,17 +139,21 @@ export {
 
 /**
  * A normalized description of the resources a flow or step may read and
- * write.
+ * write. Build one with {@link make}.
  *
  * @category models
  * @since 0.0.0
- * @slop
  */
 export interface Declaration {
+  /** Readable paths or envelope patterns, sorted and duplicate-free. */
   readonly reads: ReadonlyArray<string>
+  /** Writable paths or envelope patterns, sorted and duplicate-free. */
   readonly writes: ReadonlyArray<string>
+  /** `hermetic` or `expected` enforcement. */
   readonly mode: Mode
+  /** What a plan does when another node writes an overlapping path. */
   readonly onConflict: ConflictStrategy
+  /** The effect tier. Absent means `sealed`. */
   readonly tier?: Tier | undefined
 }
 
@@ -163,7 +167,6 @@ export interface Declaration {
  *
  * @category models
  * @since 0.0.0
- * @slop
  */
 export interface MakeOptions {
   readonly reads: Iterable<string>
@@ -176,9 +179,13 @@ export interface MakeOptions {
 /**
  * A result of checking that a step declaration narrows a flow envelope.
  *
+ * On failure, `code` names the first rule broken, checked in this order:
+ * `effect_outside_envelope` (with the uncovered read and write paths, sorted),
+ * `effect_mode_widening`, then `effect_tier_widening` (both with empty
+ * `paths`).
+ *
  * @category models
  * @since 0.0.0
- * @slop
  */
 export type NarrowResult =
   | { readonly ok: true }
@@ -191,11 +198,14 @@ export type NarrowResult =
 const normalize = (paths: Iterable<string>): ReadonlyArray<string> => [...new Set(paths)].sort()
 
 /**
- * Constructs a deterministic effect declaration.
+ * Constructs a deterministic effect declaration: `reads` and `writes` are
+ * collected, deduplicated, and sorted; an absent `tier` is omitted. Paths are
+ * not validated or rewritten.
  *
+ * @param input - The paths, mode, conflict strategy, and optional tier.
+ * @returns The normalized declaration.
  * @category constructors
  * @since 0.0.0
- * @slop
  */
 export const make = (input: MakeOptions): Declaration => ({
   reads: normalize(input.reads),
@@ -216,9 +226,11 @@ export const make = (input: MakeOptions): Declaration => ({
  * covered, so {@link narrow} reports it as `effect_outside_envelope` rather
  * than silently accepting an escape.
  *
+ * @param envelope - One envelope entry.
+ * @param path - One declared path.
+ * @returns `true` when the entry covers the path.
  * @category predicates
  * @since 0.0.0
- * @slop
  */
 export const covers = (envelope: string, path: string): boolean => {
   if (Index.hasDotSegment(path)) return false
@@ -239,9 +251,11 @@ export const covers = (envelope: string, path: string): boolean => {
  * patterns nest. A graph build prepares each envelope once for every node it
  * encloses.
  *
+ * @param envelope - The flow's declaration.
+ * @param step - The step's declaration.
+ * @returns `{ ok: true }`, or the first rule the step breaks.
  * @category validation
  * @since 0.0.0
- * @slop
  */
 export const narrow = (envelope: Declaration, step: Declaration): NarrowResult =>
   Index.narrowPrepared(Index.prepareEnvelope(envelope), step)
@@ -263,9 +277,11 @@ export const narrow = (envelope: Declaration, step: Declaration): NarrowResult =
  * ranks inside its interval, so the cost is linear in the two declarations
  * plus the matches, whatever the paths' lengths or how many patterns nest.
  *
+ * @param a - One declaration.
+ * @param b - The other declaration.
+ * @returns The shared write paths; empty when the writes are disjoint.
  * @category analysis
  * @since 0.0.0
- * @slop
  */
 export const overlaps = (a: Declaration, b: Declaration): ReadonlyArray<string> => {
   const indexed = Index.indexPaths([a.writes, b.writes])
@@ -274,11 +290,13 @@ export const overlaps = (a: Declaration, b: Declaration): ReadonlyArray<string>
 }
 
 /**
- * Returns a sealed, hermetic copy of an effect declaration.
+ * Returns a sealed, hermetic copy of an effect declaration, normalized by
+ * {@link make}. Paths and `onConflict` are kept.
  *
+ * @param declaration - The declaration to copy.
+ * @returns The copy with `mode: "hermetic"` and `tier: "sealed"`.
  * @category constructors
  * @since 0.0.0
- * @slop
  */
 export const sealed = (declaration: Declaration): Declaration =>
   make({ ...declaration, mode: "hermetic", tier: "sealed" })