@smthrs/plan 1.0.0-rc.6 → 1.0.0-rc.8

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, 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
 ---
@@ -8,28 +8,81 @@ sidebar:
 "What is different about this run" is a set comparison, not archaeology.
 `PlanDiff.diff` is that comparison as a value.
 
+## Before you start
+
+The examples run with `node <file>.ts` on Node.js 26.4.0 or later and need no
+engine, database, or jj. Compiling a plan needs Effect's `Crypto` service, which
+`@effect/platform-node` supplies. In a project that installed `@smthrs/flows`,
+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.8 @smthrs/flow@1.0.0-rc.8 @effect/platform-node
+```
+
+The outputs below are real output from the release that install line names.
+
+## Compare a re-plan
+
+Create `diff.ts`. It compiles the two drafts from
+[Compile drafts into a plan](./compile-a-plan.md), edits one field of one
+draft's body, compiles again, and compares:
+
 ```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 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>
+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" }
+}
+
+const compile = (nodes: ReadonlyArray<Plan.NodeDraft>) =>
+  Plan.compile({ planId: "review-4821", flow: "example/Review", nodes })
 
 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 before = yield* compile([readPr, runTests])
+  const after = yield* compile([
+    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))
+
+console.log(await Effect.runPromise(compare))
+```
+
+```bash
+node diff.ts
+```
+
+```text
+[ 'run-tests: body' ]
 ```
 
 `compare` answers `["run-tests: body"]`. The edit moved one field of one node's
@@ -37,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
 
@@ -70,6 +124,80 @@ reported as nothing changed.
 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.
 
+## 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. 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:
+
+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 * 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"
+
+/** 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 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* 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 inserted.ts
+```
+
+```text
+{
+  added: [ 'step-0' ],
+  removed: [],
+  rekeyed: [],
+  unchanged: [ 'step-1', 'step-2' ]
+}
+```
+
+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
 
 Each compared field is projected through the same JSON mirror the keys are
@@ -88,7 +216,9 @@ 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.
+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.
 
 The command line prints the same comparison through
 [`smthrs flow plan`](/cli/flow), and the plan card it renders is what
@@ -96,6 +226,8 @@ The command line prints the same comparison through
 
 ## Next
 
+- [Inspect the plan a body builds](../../../flow/docs/guides/inspect-the-plan.md):
+  build a flow's graph and read its nodes before anything runs.
 - [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

@@ -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.6",
+  "version": "1.0.0-rc.8",
   "license": "MIT",
   "smthrs": {
     "group": "engine"
@@ -218,9 +218,9 @@
     "tag": "next"
   },
   "dependencies": {
-    "@smthrs/crypto": "1.0.0-rc.6",
-    "@smthrs/keys": "1.0.0-rc.6",
-    "@smthrs/canonical": "1.0.0-rc.6"
+    "@smthrs/crypto": "1.0.0-rc.8",
+    "@smthrs/keys": "1.0.0-rc.8",
+    "@smthrs/canonical": "1.0.0-rc.8"
   },
   "devDependencies": {
     "@effect/language-service": "0.87.2",

package/src/PlanDiff.ts

@@ -6,10 +6,10 @@
  * 'what is different about this run' is a set comparison, not archaeology."
  * This module is the set comparison.
  *
- * The **verdict** is the key: two nodes with the same id and the same key are
- * the same step and nothing else needs saying. The **attribution** —
- * `changed: ["input[1]"]` — is a report for a human, derived by comparing the
- * declarations field by field. It is deliberately not part of any digest.
+ * The **verdict** is the key: two nodes with the same key are the same step,
+ * under the same id or a moved one, and nothing else needs saying. The
+ * **attribution** — `changed: ["input[1]"]` — is a report for a human, derived
+ * by comparing the declarations field by field. It is deliberately not part of any digest.
  *
  * @since 0.1.0
  */
@@ -157,24 +157,65 @@ const changedFields = (
 /**
  * Compares a plan against the last plan for the same flow.
  *
+ * Nodes pair in three passes, each over the nodes no earlier pass paired:
+ * the same id with the same key, then the same key under any id, then the
+ * same id with a different key. The second pass exists because flow node ids
+ * can be positional: inserting a step shifts the ids after it while their
+ * keys stay equal, and that is one added step, not a re-key of every later
+ * one (#3905).
+ *
+ * `added`, `rekeyed`, and `unchanged` name nodes by their id in `next`;
+ * `removed` names nodes by their id in `previous`. A moved id can therefore
+ * appear once in `removed` or `added` and once in `unchanged`.
+ *
+ * @param previous - The last plan recorded for the flow.
+ * @param next - The plan to compare against it.
+ * @returns The added, removed, re-keyed, and unchanged node ids, each in its
+ * plan's node order.
  * @since 0.1.0
  * @category constructors
  * @slop
  */
 export const diff = (previous: Plan.Plan, next: Plan.Plan): PlanDiff => {
+  // pairs maps a next node to the previous node it is the same step as.
+  const pairs = new Map<Plan.PlanNode, Plan.PlanNode>()
+  const paired = new Set<Plan.PlanNode>()
+  const pair = (node: Plan.PlanNode, original: Plan.PlanNode) => {
+    pairs.set(node, original)
+    paired.add(original)
+  }
   const before = new Map(previous.nodes.map((node) => [node.id, node]))
-  const after = new Map(next.nodes.map((node) => [node.id, node]))
+  for (const node of next.nodes) {
+    const original = before.get(node.id)
+    if (original !== undefined && original.key === node.key) pair(node, original)
+  }
+  const byKey = new Map<string, Array<Plan.PlanNode>>()
+  for (const node of previous.nodes) {
+    if (paired.has(node)) continue
+    const same = byKey.get(node.key)
+    if (same === undefined) byKey.set(node.key, [node])
+    else same.push(node)
+  }
+  for (const node of next.nodes) {
+    if (pairs.has(node)) continue
+    const original = byKey.get(node.key)?.shift()
+    if (original !== undefined) pair(node, original)
+  }
   const rekeyedIds = new Set<string>()
   for (const node of next.nodes) {
+    if (pairs.has(node)) continue
     const original = before.get(node.id)
-    if (original !== undefined && original.key !== node.key) rekeyedIds.add(node.id)
+    if (original !== undefined && !paired.has(original)) {
+      pair(node, original)
+      rekeyedIds.add(node.id)
+    }
   }
   const added: Array<string> = []
   const rekeyed: Array<Rekeyed> = []
   const unchanged: Array<string> = []
   const sameField = fieldComparison()
   for (const node of next.nodes) {
-    const original = before.get(node.id)
+    const original = pairs.get(node)
     if (original === undefined) {
       added.push(node.id)
       continue
@@ -192,7 +233,7 @@ export const diff = (previous: Plan.Plan, next: Plan.Plan): PlanDiff => {
   }
   return {
     added,
-    removed: previous.nodes.filter((node) => !after.has(node.id)).map((node) => node.id),
+    removed: previous.nodes.filter((node) => !paired.has(node)).map((node) => node.id),
     rekeyed,
     unchanged
   }

package/src/StepKey.ts

@@ -202,31 +202,36 @@ export interface DigestMemo {
  */
 export const makeDigestMemo = (): DigestMemo => {
   const entries = new Map<string, Deferred.Deferred<StepKey, Schema.SchemaError>>()
+  // Registering the entry and installing its exit handler run uninterruptibly,
+  // so an interrupt can never land between them and strand a Deferred that no
+  // fiber will complete. The wait and the computation stay interruptible.
   const digest: DigestMemo["digest"] = (from, path, compute) =>
-    Effect.suspend(() => {
-      const address = JSON.stringify([from, path])
-      const existing = entries.get(address)
-      if (existing !== undefined) {
-        return Effect.flatMap(Effect.exit(Deferred.await(existing)), (exit) => {
-          if (Exit.isSuccess(exit)) return Effect.succeed(exit.value)
-          // A waiter did not request the leader's cancellation. It competes to
-          // become the replacement leader instead of inheriting that interrupt.
-          return Cause.hasInterrupts(exit.cause) ? digest(from, path, compute) : Effect.failCause(exit.cause)
-        })
-      }
-      const pending = Deferred.makeUnsafe<StepKey, Schema.SchemaError>()
-      entries.set(address, pending)
-      return compute.pipe(
-        Effect.onExit((exit) =>
-          Effect.gen(function*() {
-            if (Exit.isFailure(exit) && entries.get(address) === pending) {
-              entries.delete(address)
-            }
-            yield* Deferred.done(pending, exit)
-          })
+    Effect.uninterruptibleMask((restore) =>
+      Effect.suspend(() => {
+        const address = JSON.stringify([from, path])
+        const existing = entries.get(address)
+        if (existing !== undefined) {
+          return restore(Effect.flatMap(Effect.exit(Deferred.await(existing)), (exit) => {
+            if (Exit.isSuccess(exit)) return Effect.succeed(exit.value)
+            // A waiter did not request the leader's cancellation. It competes to
+            // become the replacement leader instead of inheriting that interrupt.
+            return Cause.hasInterrupts(exit.cause) ? digest(from, path, compute) : Effect.failCause(exit.cause)
+          }))
+        }
+        const pending = Deferred.makeUnsafe<StepKey, Schema.SchemaError>()
+        entries.set(address, pending)
+        return restore(compute).pipe(
+          Effect.onExit((exit) =>
+            Effect.gen(function*() {
+              if (Exit.isFailure(exit) && entries.get(address) === pending) {
+                entries.delete(address)
+              }
+              yield* Deferred.done(pending, exit)
+            })
+          )
         )
-      )
-    })
+      })
+    )
   return { digest }
 }