@smthrs/plan 1.0.0-rc.7 → 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, 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.8 @smthrs/flow@1.0.0-rc.8 @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,8 +216,8 @@ 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.
 
 The command line prints the same comparison through

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.8",
   "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.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 }
 }