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

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/docs/installation.md

@@ -8,8 +8,8 @@ sidebar:
 ## Requirements
 
 - Node.js 26.4.0 or later.
-- `effect` 4.0.0-rc.115. The package's schemas, layers, and error classes are
-  Effect values, so the version has to match the one your application uses.
+- `effect` `^4.0.4`. The package's schemas, layers, and error classes are
+  Effect values, so it uses the one `effect` your application installs.
 
 ## Install
 
@@ -19,7 +19,7 @@ That is enough to build node graphs, compile plans, and diff them. Compiling
 asks for Effect's `Crypto` service, which a platform package supplies:
 
 ```bash
-pnpm add @effect/platform-node@4.0.0-rc.115 @effect/platform-node-shared@4.0.0-rc.115
+pnpm add @effect/platform-node @effect/platform-node-shared
 ```
 
 `@smthrs/crypto`, `@smthrs/canonical` and [`@smthrs/keys`](/api/keys) arrive as

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@smthrs/plan",
   "type": "module",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0-rc.7",
   "license": "MIT",
   "smthrs": {
     "group": "engine"
@@ -207,6 +207,7 @@
     "dist/**/*.d.ts.map",
     "dist/**/package.json",
     "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
     "README.md",
     "CHANGELOG.md",
     "docs/"
@@ -217,19 +218,19 @@
     "tag": "next"
   },
   "dependencies": {
-    "@smthrs/crypto": "1.0.0-rc.5",
-    "@smthrs/keys": "1.0.0-rc.5",
-    "@smthrs/canonical": "1.0.0-rc.5"
+    "@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",
-    "@effect/platform-node": "4.0.0-rc.115",
-    "@effect/vitest": "4.0.0-rc.115",
+    "@effect/platform-node": "4.0.4",
+    "@effect/vitest": "4.0.4",
     "@eslint/js": "9.39.5",
     "@types/node": "26.4.1",
     "@vitest/coverage-v8": "5.0.0",
     "dprint": "0.57.1",
-    "effect": "4.0.0-rc.115",
+    "effect": "4.0.4",
     "esbuild": "0.28.2",
     "eslint": "9.39.5",
     "eslint-import-resolver-typescript": "4.4.5",
@@ -243,7 +244,7 @@
     "fast-check": "4.9.0"
   },
   "peerDependencies": {
-    "effect": "4.0.0-rc.115"
+    "effect": "^4.0.4"
   },
   "scripts": {
     "lint": "eslint src --max-warnings=0 && dprint check",

package/src/KeyMaterial.ts

@@ -7,7 +7,7 @@
  * lives here, above `@smthrs/keys`, so the key package stays a leaf.
  *
  * Governing contract: the step-key rules at
- * https://smithers.sh/docs/concepts/content-addressing. Material is computed with no I/O,
+ * https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/plan/docs/concepts/step-keys.md. Material is computed with no I/O,
  * and two hardening rules shape it: the nominal, never shape-sniffed
  * `InputRef` and the hashed `version`.
  *

package/src/Node.ts

@@ -31,9 +31,11 @@
 import { dual } from "effect/Function"
 import type * as Pipeable from "effect/Pipeable"
 import type * as Schema from "effect/Schema"
+import type * as SchemaAST from "effect/SchemaAST"
 import type * as Types from "effect/Types"
 import { GraphBuildError } from "./GraphBuildError.ts"
 import * as internal from "./internal/node.ts"
+import * as internalSchemaIdentity from "./internal/SchemaIdentity.ts"
 import * as Planned from "./Planned.ts"
 
 /**
@@ -843,6 +845,83 @@ export const catchFilter = (ast: Ast): Schema.Top | undefined => ast._tag === "C
  */
 export const functionIdentity = (operation: unknown): FunctionIdentity => internal.functionIdentity(operation)
 
+/**
+ * The document a schema's identity is: JSON-Schema-shaped, and the same bytes
+ * under every `effect` release this package supports.
+ *
+ * @since 1.0.0
+ * @category engine
+ */
+export type SchemaIdentity = internalSchemaIdentity.Document
+
+/**
+ * The one option a schema's identity is taken under: whether an object closes
+ * over the keys it declares (`"error"`) or leaves others open (`"ignore"`,
+ * the default). It has the meaning it has in `Schema.toJsonSchemaDocument`.
+ *
+ * @since 1.0.0
+ * @category engine
+ */
+export type SchemaIdentityOptions = internalSchemaIdentity.Options
+
+/**
+ * The refusal `schemaIdentity` and `representationIdentity` raise for a schema
+ * a step key cannot be derived from. Its message is the one
+ * `effect@4.0.0-rc.115` gave for the same schema, where it gave one.
+ *
+ * @since 1.0.0
+ * @category errors
+ */
+export const SchemaIdentityError = internalSchemaIdentity.SchemaIdentityError
+
+/**
+ * The type of {@link SchemaIdentityError}.
+ *
+ * @since 1.0.0
+ * @category errors
+ */
+export type SchemaIdentityError = internalSchemaIdentity.SchemaIdentityError
+
+/**
+ * Identifies a schema by the constraints it documents, so a call re-keys when
+ * what its callee accepts or produces changes, and a catch re-keys when its
+ * filter does.
+ *
+ * The document is what `Schema.toJsonSchemaDocument(schema, options)`
+ * returned under `effect@4.0.0-rc.115`. It is printed by this package, not by
+ * the installed `effect`, because a later release prints a different document
+ * for the same schema and a moved identity re-keys every recorded step. Use
+ * it wherever the document is hashed, compared or pinned; a JSON Schema shown
+ * to a model or a person comes from `Schema.toJsonSchemaDocument`.
+ *
+ * Reserved for the packages that derive identities. Authors never call it; it
+ * throws for a schema that has no JSON Schema form.
+ *
+ * @since 1.0.0
+ * @category engine
+ */
+export const schemaIdentity = (schema: Schema.Top, options?: SchemaIdentityOptions): SchemaIdentity =>
+  internalSchemaIdentity.schemaIdentity(schema, options)
+
+/**
+ * Identifies a schema AST by its encoded representation, the material a
+ * sealed action's step key folds in for its success and error schemas.
+ *
+ * The value is what `SchemaRepresentation.toJson(SchemaRepresentation.toRepresentation(ast))`
+ * returned under `effect@4.0.0-rc.115`, so a later `effect` release does not
+ * re-key recorded steps. The one exception is `Schema.brand`: from
+ * `effect@4.0.4` on a brand is not part of the AST, so a declaration with a
+ * brand re-keys once.
+ *
+ * Reserved for the packages that derive step keys. Authors never call it; it
+ * throws for an AST that has no representation.
+ *
+ * @since 1.0.0
+ * @category engine
+ */
+export const representationIdentity = (ast: SchemaAST.AST): Schema.Json =>
+  internalSchemaIdentity.representationIdentity(ast)
+
 /**
  * Binds a frozen plain copy of inert captures as the callback's this receiver.
  *

package/src/StepKey.ts

@@ -22,7 +22,7 @@
  * resolved references, and the hashed `version`.
  *
  * Governing contract: the step-key rules at
- * https://smithers.sh/docs/concepts/content-addressing.
+ * https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/plan/docs/concepts/step-keys.md.
  *
  * @since 0.1.0
  */