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

package/docs/guides/implement-an-action.md

@@ -68,11 +68,19 @@ fails to compile the same way a missing action implementation does.
 The tier tells the engine what retrying this action means. It is part of the step
 key, so it is not a hint.
 
-| Tier           | Choose it when                                        | What the engine does                                                                                                                                                                                                                                            |
-| -------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `sealed`       | The result is a pure function of the declared inputs. | Records the result and replays it. With the right declarations, reuses it across runs.                                                                                                                                                                          |
-| `compensable`  | The body changes the workspace.                       | Takes a pre-image before each attempt and restores it before the next one, so attempt two does not trip over attempt one's half-written files. Requires a `FlowEngine.SnapshotBoundary` in context, which [`@smthrs/engine-store`](/api/engine-store) supplies. |
-| `irreversible` | The body changes the world outside the workspace.     | Refuses to retry without a declared `idempotencyKey`, dying with `IrreversibleRetryRequiresIdempotencyKey`.                                                                                                                                                     |
+| Tier           | Choose it when                                        | What the engine does                                                                                                                                                                                                                                                                                     |
+| -------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sealed`       | The result is a pure function of the declared inputs. | Records the result and replays it. With the right declarations, reuses it across runs.                                                                                                                                                                                                                   |
+| `compensable`  | The body changes the workspace.                       | Takes a pre-image before each attempt and restores it before the next one, so attempt two does not trip over attempt one's half-written files. Requires a `FlowEngine.SnapshotBoundary` in context, which [`@smthrs/engine-store`](/api/engine-store) supplies, and a workspace that is a jj repository. |
+| `irreversible` | The body changes the world outside the workspace.     | Refuses to retry without a declared `idempotencyKey`, dying with `IrreversibleRetryRequiresIdempotencyKey`.                                                                                                                                                                                              |
+
+The `compensable` pre-image is a jj snapshot of the workspace, so the
+workspace must be a jj repository: run `jj git init` in it first. Without one,
+the step dies before its first attempt runs:
+
+```text
+@smthrs/jj/JjError: jj snapshot: Error: There is no jj repo in "."
+```
 
 `sealed` is the default, and it is a claim about the body: this result is worth
 replaying. Add `nondeterministic: true` when several legitimate results may race

package/docs/guides/inspect-the-plan.md

@@ -11,15 +11,57 @@ tool to reach for when a step key changed unexpectedly, when a branch took the
 arm you did not expect, or when you want to show an operator what a run is about
 to do.
 
+## 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: planning reads declarations only. They import
+`@smthrs/flow` and `@smthrs/plan`. In a project that installed `@smthrs/flows`,
+add both at the version of `@smthrs/flows` you have:
+
+```bash
+npm install @smthrs/flow@1.0.0-rc.7 @smthrs/plan@1.0.0-rc.7
+```
+
+`@smthrs/flows` re-exports the same modules, so `import { Graph } from "@smthrs/flows"`
+and its `Plan.Node` work too. The outputs below are real output from 1.0.0-rc.6.
+
 ## Build the graph
 
+Create `inspect.ts`. The flow runs two checks in parallel, joins them into a
+report, and then ships or explains:
+
 ```ts
-import { Graph } from "@smthrs/flow"
+import { Action, Flow, Graph } from "@smthrs/flow"
+import { Node } from "@smthrs/plan"
+import * as Schema from "effect/Schema"
+
+const Lint = Action.make("release/Lint", { payload: { target: Schema.String }, success: Schema.String })
+const Types = Action.make("release/Types", { payload: { target: Schema.String }, success: Schema.String })
+const Report = Action.make("release/Report", {
+  payload: { lint: Schema.String, types: Schema.String },
+  success: Schema.String
+})
+const Ship = Action.make("release/Ship", { payload: { report: Schema.String }, success: Schema.String })
+const Explain = Action.make("release/Explain", { payload: { reason: Schema.String }, success: Schema.String })
+
+const Release = Flow.make("release/Release", {
+  payload: { target: Schema.String },
+  success: Schema.String,
+  body: ({ target }) =>
+    Node.all({ lint: Lint.call({ target }), types: Types.call({ target }) }).pipe(
+      Node.bindPlanned((checks) => Report.call({ lint: checks.lint, types: checks.types })),
+      Node.branch({
+        if: (report) => report.includes("clean"),
+        then: (report) => Ship.call({ report }),
+        else: (reason) => Explain.call({ reason })
+      })
+    )
+})
 
 const graph = Graph.build(Release, { target: "web" })
 
 for (const node of Graph.nodes(graph)) {
-  console.log(node.id, node.kind, node.dependencies)
+  console.log(`${node.id} ${node.kind} [${node.dependencies.join(", ")}]`)
 }
 
 for (const edge of Graph.edges(graph)) {
@@ -27,6 +69,33 @@ for (const edge of Graph.edges(graph)) {
 }
 ```
 
+```bash
+node inspect.ts
+```
+
+```text
+root.flow.branch.andThen.all.lint ActionCall []
+root.flow.branch.andThen.all.types ActionCall []
+root.flow.branch.andThen All [root.flow.branch.andThen.all.lint, root.flow.branch.andThen.all.types]
+root.flow.branch.then ActionCall [root.flow.branch.andThen]
+root.flow.branch AndThen [root.flow.branch.andThen, root.flow.branch.then]
+root.flow.then ActionCall [root.flow.branch]
+root.flow.else ActionCall [root.flow.branch]
+root.flow Branch [root.flow.branch, root.flow.then, root.flow.else]
+root FlowCall [root.flow]
+root.flow.branch.andThen.all.lint -> root.flow.branch.andThen (value)
+root.flow.branch.andThen.all.types -> root.flow.branch.andThen (value)
+root.flow.branch.andThen -> root.flow.branch (value)
+root.flow.branch.andThen -> root.flow.branch.then (continuation)
+root.flow.branch.then -> root.flow.branch (value)
+root.flow.branch -> root.flow (value)
+root.flow.branch -> root.flow.then (continuation)
+root.flow.then -> root.flow (value)
+root.flow.branch -> root.flow.else (continuation)
+root.flow.else -> root.flow (value)
+root.flow -> root (value)
+```
+
 `Graph.build` takes a flow declaration or a bare node, the payload, and options.
 Nothing runs. It refuses a nesting depth past its bound and a duplicate node id,
 because a node id is durable dispatch identity and two nodes answering to one
@@ -79,9 +148,14 @@ partial drafts. Check diagnostics before asking for drafts:
 const issues = Graph.diagnostics(graph)
 if (issues.length === 0) {
   const drafts = Graph.drafts(graph) // ready for Plan.compile or Plan.append
+  console.log(`${drafts.length} drafts`)
 }
 ```
 
+Appended to `inspect.ts`, it prints `9 drafts`: one per node above.
+[Diff two plans](../../../plan/docs/guides/diff-two-plans.md) compiles drafts like
+these and compares two versions of a flow.
+
 ## Resolve layers while building
 
 `BuildOptions.resolveLayers` is invoked once per node and is told a
@@ -103,17 +177,22 @@ that read the world would make a plan a function of more than its declarations.
 ## Drive one interpretation
 
 `Interpreter.interpret` builds the graph and walks it against real values,
-without registering the flow. It answers an `Interpretation`:
+without registering the flow. It is the walk `Interpreter.layer` runs for each
+round of an execution, and it requires the `FlowInstance` the runtime provides
+to an executing round, so a program reaches it through `execute` rather than by
+calling it at top level. It answers an `Interpretation`:
 
 ```ts
-import { Interpreter } from "@smthrs/flow"
-
-const interpretation = yield* Interpreter.interpret(Release, { target: "web" })
-
-interpretation.value // the root's value
-interpretation.settled // ReadonlyMap<string, unknown>: every node that settled
-interpretation.failed // the typed failures observed before a catch recovered them
-interpretation.skipped // the nodes a branch went the other way on
+interface Interpretation {
+  /** The root's value. */
+  readonly value: unknown
+  /** Every node that settled. */
+  readonly settled: ReadonlyMap<string, unknown>
+  /** The typed failures observed before a catch recovered them. */
+  readonly failed: ReadonlyMap<string, unknown>
+  /** The nodes a branch went the other way on. */
+  readonly skipped: ReadonlyArray<string>
+}
 ```
 
 `skipped` is the field that answers "why did nothing happen here". The walk is
@@ -147,6 +226,8 @@ implementation layers instead of provided under them.
 
 ## Related pages
 
+- [Diff two plans](../../../plan/docs/guides/diff-two-plans.md): compile two
+  versions of a flow and see which steps were added, removed, or re-keyed.
 - [Bodies are plans](../concepts/bodies-and-plans.md): why the build is pure and
   what it refuses.
 - [Execution identity](../concepts/execution-identity.md): how a node id becomes

package/docs/installation.md

@@ -1,6 +1,6 @@
 ---
 title: "Installation"
-description: "Install @smthrs/flow, its runtime requirements and pinned effect version, its import forms, and the packages a runnable composition adds."
+description: "Install @smthrs/flow, its runtime requirements and effect range, its import forms, and the packages a runnable composition adds."
 sidebar:
   order: 1
 ---
@@ -9,8 +9,8 @@ sidebar:
 
 `@smthrs/flow` is not on npm yet. Link the source packages as described in [Use the libraries](#use-the-libraries).
 
-`effect` is a runtime dependency of this package and installs with it. Add it to
-your own dependencies at the same version anyway: your declarations import
+`effect` is a peer dependency of this package, in the range `^4.0.4`. Add one
+`effect` in that range to your own dependencies: your declarations import
 `effect/Schema` and your implementations import `effect/Effect` directly, and two
 copies of `effect` in one program are two sets of service tags.
 
@@ -23,7 +23,7 @@ from, and the canonical JSON checks applied to values.
 
 ## Use the libraries
 
-First [install the source checkout](https://github.com/smithersai/smithers/blob/main/packages/smithers/docs/installation.md#install-the-cli). The checkout's `examples` workspace carries the packages used by the flow tutorials and their pinned `effect@4.0.0-rc.115`.
+First [install the source checkout](https://github.com/smithersai/smithers/blob/main/packages/smithers/docs/installation.md#install-the-cli). The checkout's `examples` workspace carries the packages used by the flow tutorials and their pinned `effect@4.0.4`.
 
 Create a project beside the checkout:
 

package/docs/reference/flow.md

@@ -5,7 +5,7 @@ area: api
 order: 10
 ---
 
-Install the package with its exact `effect` peer. Not on npm yet; see [Installation](../installation.md#use-the-libraries).
+Install the package with its `effect` peer. Not on npm yet; see [Installation](../installation.md#use-the-libraries).
 
 ## Entry points
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@smthrs/flow",
   "type": "module",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0-rc.7",
   "license": "MIT",
   "smthrs": {
     "group": "engine"
@@ -289,21 +289,21 @@
     "tag": "next"
   },
   "dependencies": {
-    "@smthrs/crypto": "1.0.0-rc.5",
-    "@smthrs/keys": "1.0.0-rc.5",
-    "@smthrs/plan": "1.0.0-rc.5",
-    "@smthrs/canonical": "1.0.0-rc.5",
-    "@smthrs/capability": "1.0.0-rc.5"
+    "@smthrs/crypto": "1.0.0-rc.7",
+    "@smthrs/keys": "1.0.0-rc.7",
+    "@smthrs/plan": "1.0.0-rc.7",
+    "@smthrs/canonical": "1.0.0-rc.7",
+    "@smthrs/capability": "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",
@@ -316,7 +316,7 @@
     "vitest": "5.0.0"
   },
   "peerDependencies": {
-    "effect": "4.0.0-rc.115"
+    "effect": "^4.0.4"
   },
   "scripts": {
     "lint": "eslint src --max-warnings=0 && dprint check",

package/src/DurableDeferred.ts

@@ -19,7 +19,7 @@ import * as Cause from "effect/Cause"
 import * as Context from "effect/Context"
 import type * as Crypto from "effect/Crypto"
 import * as Effect from "effect/Effect"
-import * as Encoding from "effect/Encoding"
+import * as Base64Url from "effect/encoding/Base64Url"
 import * as Exit from "effect/Exit"
 import * as Filter from "effect/Filter"
 import { dual } from "effect/Function"
@@ -249,7 +249,7 @@ export const into: {
           // Untraced because completion encoding is called for each deferred result.
           Effect.fnUntraced(function*(exit) {
             if (Exit.isFailure(exit)) {
-              const [reasons, interrupts] = Arr.partition(
+              const [interrupts, reasons] = Arr.partition(
                 exit.cause.reasons,
                 Filter.fromPredicate(Cause.isInterruptReason)
               )
@@ -396,7 +396,7 @@ export class TokenParsed extends Schema.Class<TokenParsed>(
    * @since 0.1.0
    */
   get asToken(): Token {
-    return Encoding.encodeBase64Url(
+    return Base64Url.encode(
       JSON.stringify([this.flowName, this.executionId, this.deferredName])
     ) as Token
   }

package/src/DurableQueue.ts

@@ -20,10 +20,10 @@ import * as Effect from "effect/Effect"
 import * as Exit from "effect/Exit"
 import * as Filter from "effect/Filter"
 import * as Layer from "effect/Layer"
+import * as PersistedQueue from "effect/persistence/PersistedQueue"
 import * as Schedule from "effect/Schedule"
 import * as Schema from "effect/Schema"
 import * as Tracer from "effect/Tracer"
-import * as PersistedQueue from "effect/unstable/persistence/PersistedQueue"
 import * as Action from "./Action/index.ts"
 import * as DurableDeferred from "./DurableDeferred.ts"
 import { annotateWaiting, type FlowInstance, type FlowRuntime } from "./FlowRuntime/index.ts"
@@ -367,7 +367,7 @@ const makeWorkerEffect = Effect.fnUntraced(function*<
           })
           let exit = yield* Effect.exit(f(item.payload))
           if (Exit.isFailure(exit)) {
-            const [reasons, interrupts] = Arr.partition(
+            const [interrupts, reasons] = Arr.partition(
               exit.cause.reasons,
               Filter.fromPredicate(Cause.isInterruptReason)
             )

package/src/Flow/ExecutionIds.ts

@@ -99,7 +99,7 @@ export const derived: ExecutionIdSource = {
  * @since 0.1.0
  */
 export const fresh: ExecutionIdSource = {
-  mint: () => Effect.flatMap(Crypto.Crypto, (crypto) => Effect.orDie(crypto.randomUUIDv4))
+  mint: () => Effect.flatMap(Crypto.Crypto, (crypto) => Effect.orDie(crypto.randomUUIDv4()))
 }
 
 /**

package/src/Flow/Result.ts

@@ -10,11 +10,11 @@ import { CapabilityPattern } from "@smthrs/capability/Capability"
 import * as Data from "effect/Data"
 import * as Effect from "effect/Effect"
 import type * as Exit from "effect/Exit"
+import type { ExitEncoded } from "effect/rpc/RpcMessage"
 import * as Schema from "effect/Schema"
 import * as SchemaIssue from "effect/SchemaIssue"
 import * as SchemaParser from "effect/SchemaParser"
 import * as Transformation from "effect/SchemaTransformation"
-import type { ExitEncoded } from "effect/unstable/rpc/RpcMessage"
 
 const ResultTypeId = "@smthrs/flow/Flow/Result"
 

package/src/Flow/Runtime.ts

@@ -62,7 +62,7 @@ export const intoResult = <A, E, R>(
             instance.handoff ?? new Complete({ exit: Exit.succeed(value) })
           ),
         onFailure: (cause): Effect.Effect<Result<A, E>> => {
-          const [reasons, interrupts] = Arr.partition(
+          const [interrupts, reasons] = Arr.partition(
             cause.reasons,
             Filter.fromPredicate(Cause.isInterruptReason)
           )

package/src/Flow/internal.ts

@@ -165,7 +165,7 @@ const Proto = {
       Crypto.Crypto,
       (crypto) =>
         Effect.flatMap(
-          Effect.orDie(crypto.randomUUIDv4),
+          Effect.orDie(crypto.randomUUIDv4()),
           (executionId) => this.execute(payload, { executionId, discard: true })
         )
     )

package/src/Graph.ts

@@ -65,7 +65,7 @@ import * as Planned from "@smthrs/plan/Planned"
 import * as Context from "effect/Context"
 import * as Option from "effect/Option"
 import * as Predicate from "effect/Predicate"
-import * as Schema from "effect/Schema"
+import type * as Schema from "effect/Schema"
 import type * as Action from "./Action/Action.ts"
 import { TypeId as ActionTypeId } from "./Action/TypeId.ts"
 import * as Annotations from "./Flow/Annotations.ts"
@@ -321,12 +321,15 @@ const refusalMessage = (
  * transformation and needs the call re-keyed renames the declaration.
  * `@smthrs/core` carries the same algorithm and the same limit.
  *
+ * `Node.schemaIdentity` prints the document, not the installed `effect`: a
+ * release that prints a schema differently must not move the identity.
+ *
  * @private
  */
 const schemaIdentity = (schema: Schema.Top): unknown => {
   const cached = schemaDocuments.get(schema)
   if (cached !== undefined) return cached
-  const document = Schema.toJsonSchemaDocument(schema, { onExcessProperty: "error" })
+  const document = Node.schemaIdentity(schema, { onExcessProperty: "error" })
   schemaDocuments.set(schema, document)
   return document
 }