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

package/README.md

@@ -6,7 +6,7 @@ This package declares `effect` as a `^4.0.4` peer dependency. Install one
 `effect` release in that range so all Smithers packages share one Effect
 runtime.
 
-**Documentation:** https://plan.smithers.sh
+**Documentation:** https://github.com/smithersai/smithers/tree/main/packages/smithers/flows/plan/docs
 
 The persisted plan: a keyed action graph, its append-only store, its diff, and
 the step-key compiler that gives every node its identity.
@@ -17,7 +17,7 @@ from what that node declares, records that graph in a SQLite store that only
 ever grows, and compares two graphs to say exactly what changed. It runs
 nothing itself: it performs no I/O beyond the database, and driving a compiled
 plan is a scheduler's job, such as
-[`@smthrs/engine-store`](https://engine-store.smithers.sh)'s `PlanScheduler`.
+[`@smthrs/engine-store`](https://github.com/smithersai/smithers/tree/main/packages/smithers/flows/engine-store/docs)'s `PlanScheduler`.
 
 Reach for it when you are building a scheduler, a cache, or an approval flow
 over declared work and you need step identity, declared file effects, and an
@@ -35,8 +35,8 @@ pnpm add @effect/platform-node @effect/platform-node-shared
 ```
 
 Node.js 26.4.0 or later, and `effect` `^4.0.4` as a peer. Recording a plan
-is [`@smthrs/plan-store`](https://plan-store.smithers.sh), which owns the SQL
-and brings [`@smthrs/database`](https://database.smithers.sh) with it.
+is [`@smthrs/plan-store`](https://github.com/smithersai/smithers/tree/main/packages/smithers/flows/plan-store/docs), which owns the SQL
+and brings [`@smthrs/database`](https://github.com/smithersai/smithers/tree/main/packages/smithers/flows/database/docs) with it.
 
 ## Compile a plan
 
@@ -100,8 +100,8 @@ another number and both keys move; rename `read-pr` to `fetch-pr` and neither
 does.
 
 Recording that plan is
-[`@smthrs/plan-store`](https://plan-store.smithers.sh), whose
-[quickstart](https://plan-store.smithers.sh/quickstart/) builds the whole
+[`@smthrs/plan-store`](https://github.com/smithersai/smithers/tree/main/packages/smithers/flows/plan-store/docs), whose
+[quickstart](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/plan-store/docs/quickstart.md) builds the whole
 composition against an in-memory database.
 
 ## What is in here
@@ -168,7 +168,7 @@ edge: `compile` puts the reader behind its producer by growing `dependsOn`, and
 fails with `cycle` when no edge set can satisfy both that and the declared
 order.
 
-[Declared effects and conflicts](https://plan.smithers.sh/concepts/effects-and-conflicts/)
+[Declared effects and conflicts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/plan/docs/concepts/effects-and-conflicts.md)
 covers both passes in full.
 
 ## When it refuses
@@ -183,9 +183,9 @@ through `GraphBuildError`, whose closed code set names the site and the fix;
 `unstable_callback` in that set is raised by `@smthrs/flow` when a stable build
 meets a callback without a `Node.capture` declaration. Persistence has its own
 refusals, all of them
-[`@smthrs/plan-store`](https://plan-store.smithers.sh)'s.
+[`@smthrs/plan-store`](https://github.com/smithersai/smithers/tree/main/packages/smithers/flows/plan-store/docs)'s.
 
-[Troubleshooting](https://plan.smithers.sh/troubleshooting/) lists every code
+[Troubleshooting](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/plan/docs/troubleshooting.md) lists every code
 with the change that clears it.
 
 ## Paths, payloads, and immutability
@@ -220,10 +220,10 @@ Persistence is a separate package, which is where a platform choice enters.
 
 ## Links
 
-- [Documentation](https://plan.smithers.sh)
-- [API reference](https://plan.smithers.sh/reference/api/)
-- [`@smthrs/plan-store`](https://plan-store.smithers.sh), the append-only store
+- [Documentation](https://github.com/smithersai/smithers/tree/main/packages/smithers/flows/plan/docs)
+- [API reference](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/plan/docs/api.md)
+- [`@smthrs/plan-store`](https://github.com/smithersai/smithers/tree/main/packages/smithers/flows/plan-store/docs), the append-only store
   a compiled plan is recorded in
-- [`@smthrs/flows`](https://flows.smithers.sh), the whole engine as a single
+- [`@smthrs/flows`](https://github.com/smithersai/smithers/tree/main/packages/smithers/flows/docs), the whole engine as a single
   dependency, which re-exports this package as its `Plan` namespace
 - [License: MIT](./LICENSE)

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, why node ids are positional, 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.7 @smthrs/flow@1.0.0-rc.7 @effect/platform-node
+```
+
+The outputs below are real output from 1.0.0-rc.6.
+
+## 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
@@ -70,6 +123,94 @@ 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. 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.
+
+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:
+
+```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 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 }))
+    )
+})
+
+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 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"}`)
+  }
+}).pipe(Effect.provide(NodeCrypto.layer))
+
+await Effect.runPromise(program)
+```
+
+```bash
+node positional.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
+```
+
+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.
+
 ## Comparison uses the key's own JSON semantics
 
 Each compared field is projected through the same JSON mirror the keys are
@@ -88,7 +229,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 while the shape stays put. Once a step is added
+or removed, ids move, so read the work by 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 +239,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@smthrs/plan",
   "type": "module",
-  "version": "1.0.0-rc.6",
+  "version": "1.0.0-rc.7",
   "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.7",
+    "@smthrs/keys": "1.0.0-rc.7",
+    "@smthrs/canonical": "1.0.0-rc.7"
   },
   "devDependencies": {
     "@effect/language-service": "0.87.2",