@smthrs/flow 0.0.0-stage → 1.0.0-rc.4

package/docs/guides/use-a-prompt.md

@@ -0,0 +1,38 @@
+---
+title: "Prompt-backed flows"
+description: "Declare a typed prompt with Flow.make and attach its host implementation to the ordinary action it lowers to."
+---
+
+Declare exactly one of `body` or `prompt` with the same tagged constructor:
+
+```ts
+import { Flow } from "@smthrs/flow"
+import * as Schema from "effect/Schema"
+
+export const Draft = Flow.make("draft", {
+  description: "Drafts a response.",
+  payload: { message: Schema.String },
+  success: Schema.String,
+  prompt: ({ message }) => `Respond to: ${message}`
+})
+```
+
+`Draft` is an ordinary flow. Its body calls `Draft.action`, an ordinary action
+named `draft/prompt`. Constructing the declaration and building its graph never
+render the prompt or call a model. The host renders `Draft.prompt(payload)`
+inside the implementation it attaches with `Draft.action.toLayer(...)`.
+
+The prompt receives the decoded payload. Missing or incorrectly typed props
+are TypeScript errors. A host may render an imported typed MDX component from
+that callback; see [MDX prompts](/pkg/registry/guides/mdx-prompts).
+
+`model` may name a seat or an ordered nonempty fallback list. When omitted,
+the host supplies its resolved seat. `effort`, `flows`, `system`, and `chat`
+retain host metadata. They do not start a model or widen authority. Declare
+`capabilities` and `effects` for the same ceiling a body-backed flow uses.
+
+Supply the model implementation's failure schema as `error`. For the existing
+agent host, use `AgentAction.AgentFailure` from `@smthrs/agent/AgentAction`.
+A prompt action defaults to the irreversible tier and has no content cache key.
+Register `Interpreter.layer(Draft)` and the action implementation under the
+host's ordinary runtime and `Action.layerImplementations`.

package/docs/guides/wait-for-a-deadline.md

@@ -0,0 +1,141 @@
+---
+title: "Wait for a deadline"
+description: "Park a round on a durable timer with Sleep.action, sleep inside an implementation with DurableClock, and read the refusals an unarmable deadline earns."
+sidebar:
+  order: 4
+---
+
+There are two ways to wait for time to pass, and which one you reach for depends
+on where you are standing.
+
+- In a **body**, call `Sleep.action`. The wait becomes a keyed plan node: visible
+  in the graph, skippable by a branch, and replayed like any other step.
+- In an **implementation**, call `DurableClock.sleep`. A body cannot see it, but
+  a handler can reach it.
+
+Both park the execution rather than holding a fiber, so the wait outlives the
+process.
+
+## Wait inside a body
+
+```ts
+import { Action, Flow, Interpreter, Sleep } from "@smthrs/flow"
+import { Node } from "@smthrs/plan"
+import * as Layer from "effect/Layer"
+import * as Schema from "effect/Schema"
+
+const Notify = Action.make("release/Notify", {
+  payload: { build: Schema.String },
+  success: Schema.String
+})
+
+export const Cooldown = Flow.make("release/Cooldown", {
+  payload: { build: Schema.String },
+  success: Schema.String,
+  error: Sleep.SleepRequestInvalid,
+  body: ({ build }) =>
+    Sleep.action.call({ millis: 60_000 }).pipe(
+      Node.andThen(Notify.call({ build }))
+    )
+})
+
+export const layer = Layer.mergeAll(
+  Sleep.layer,
+  Notify.toLayer(({ build }) => notifyRelease(build)),
+  Interpreter.layer(Cooldown)
+).pipe(Layer.provideMerge(Action.layerImplementations))
+```
+
+`Sleep.layer` is not optional. `Sleep.action` is declared with
+`Action.makeSystem`, so it pushes no compile-time obligation onto callers, but a
+composition without the layer has a plan node no implementation answers.
+
+The implementation arms a durable clock, declares its park as `timer` with the
+deadline as `wakeAt`, and awaits the clock's deferred. Once the clock has fired,
+its result is persisted, so a re-driven round reads it and runs straight through
+instead of parking a second time.
+
+## Name exactly one deadline
+
+A payload carries a relative `millis` or an absolute `until` in epoch
+milliseconds, and exactly one of them. `Sleep.SleepRequestInvalid` is the typed
+refusal, so a body can recover from it with `Node.catch` like any other declared
+failure:
+
+| Code                 | What was wrong                                                                                                                          |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `missing_deadline`   | The payload named neither `millis` nor `until`.                                                                                         |
+| `ambiguous_deadline` | It named both, which are the same fact stated twice.                                                                                    |
+| `invalid_deadline`   | It named a number that is not a length of time: a non-finite or negative `millis`, a non-finite `until`, or an addition that overflows. |
+
+Two behaviors are worth knowing before you write the body:
+
+- **Two waits of the same length are two waits.** Each call is its own node with
+  its own identity, so a sleep followed by a sleep waits twice.
+- **A deadline that has already passed settles the node instead of parking it.**
+  A run that resumes after its own deadline has to make progress.
+
+## Wait inside an implementation
+
+`DurableClock.sleep` is the handler-side wait:
+
+```ts
+import { DurableClock } from "@smthrs/flow"
+
+const wait = DurableClock.sleep({
+  name: "cooldown",
+  duration: "2 days",
+  inMemoryThreshold: "30 seconds"
+})
+```
+
+The threshold decides the mechanism. A duration at or below
+`inMemoryThreshold`, 60 seconds by default, runs as an in-memory sealed action.
+A longer one schedules a durable clock and suspends the execution. A zero
+duration returns immediately. Both the duration and the threshold must be finite
+and not negative.
+
+`DurableClock.make({ name, duration })` builds the clock value on its own, which
+is what you want when you need the clock's deferred rather than the wait, for
+example to race it against real work.
+
+## Bound work with a clock
+
+Racing a durable clock against the work is how you put a durable time limit on
+something that can hang. The race records its winner, so a re-driven round reads
+the recorded outcome instead of racing again:
+
+```ts
+import { DurableDeferred } from "@smthrs/flow"
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+
+const bounded = DurableDeferred.raceAll({
+  name: "deploy/status",
+  success: Schema.String,
+  error: Schema.Never,
+  effects: [
+    readDeployment("web"),
+    Effect.as(
+      DurableClock.sleep({
+        name: "deploy/status",
+        duration: Duration.seconds(30),
+        inMemoryThreshold: Duration.zero
+      }),
+      "unknown"
+    )
+  ]
+})
+```
+
+`inMemoryThreshold: Duration.zero` forces the durable path, so the bound outlives
+the process waiting on it rather than living in a fiber.
+
+## Related pages
+
+- [Wait for an external signal](./wait-for-an-external-signal.md): the other
+  system wait, and the tokens that resolve it.
+- [Poll until something is ready](./poll-until-ready.md): a timer and a check,
+  packaged as a lineage of rounds.
+- [Suspension and replay](../concepts/suspension-and-replay.md): what parking
+  does to the run.

package/docs/guides/wait-for-an-external-signal.md

@@ -0,0 +1,151 @@
+---
+title: "Wait for an external signal"
+description: "Park a round on a named wait point, resolve it from another process with a completion token, and use durable deferreds directly."
+sidebar:
+  order: 5
+---
+
+A run often has to wait for something that is not time and not a step: an
+approval, a webhook, a human closing a ticket. `WaitFor.action` is that wait as an
+ordinary plan node, and a `DurableDeferred` token is how the outside world
+resolves it.
+
+## Park the body on a named wait point
+
+```ts
+import { Action, Flow, Interpreter, WaitFor } from "@smthrs/flow"
+import { Node } from "@smthrs/plan"
+import * as Layer from "effect/Layer"
+import * as Schema from "effect/Schema"
+
+const Deploy = Action.make("release/Deploy", {
+  payload: { build: Schema.String },
+  success: Schema.String
+})
+
+export const Ship = Flow.make("release/Ship", {
+  payload: { build: Schema.String },
+  success: Schema.String,
+  error: WaitFor.WaitForRequestInvalid,
+  body: ({ build }) =>
+    WaitFor.action.call({ name: "ship" }).pipe(
+      Node.andThen(Deploy.call({ build }))
+    )
+})
+
+export const layer = Layer.mergeAll(
+  WaitFor.layer,
+  Deploy.toLayer(({ build }) => deployBuild(build)),
+  Interpreter.layer(Ship)
+).pipe(Layer.provideMerge(Action.layerImplementations))
+```
+
+The implementation parks the execution under the `event` waiting reason, carrying
+the wake token a completion is matched against, and settles with whatever value
+resolved the wait. `WaitFor.action` succeeds with `Schema.Json`, so decode the
+answer with a schema when you need a typed value.
+
+`WaitFor.layer` is required in the composition for the same reason `Sleep.layer`
+is: the node is a system declaration, so the compiler does not ask for it, but
+the run does.
+
+## Resolve it from outside
+
+`WaitFor.deferred(name)` is the resolver's half of the same wait point. Derive
+the token from the flow and the execution id, then complete it:
+
+```ts
+import { DurableDeferred } from "@smthrs/flow"
+import * as Effect from "effect/Effect"
+
+const gate = WaitFor.deferred("ship")
+
+export const approve = (executionId: string) =>
+  Effect.gen(function*() {
+    const token = DurableDeferred.tokenFromExecutionId(gate, { flow: Ship, executionId })
+    yield* DurableDeferred.succeed(gate, { token, value: { approved: true } })
+  })
+```
+
+The resolver needs the `FlowRuntime` the run was started on, because a completion
+is recorded against the flow and execution that own the wait point. In practice
+that means the resolver and the engine share a store.
+
+`DurableDeferred.tokenFromPayload(gate, { flow, payload })` derives the same token
+from a payload, for a resolver that knows what was asked for but not which id it
+was admitted under. This requires the flow to declare `idempotencyKey`; use
+`tokenFromExecutionId` when the caller supplied an execution id explicitly.
+
+A token is an address, not a credential. Anyone who knows the flow and the
+execution id, or the payload, can rebuild it, so a resolver that accepts
+completions from other parties must authorize the caller before it calls
+`DurableDeferred.succeed`.
+
+## Name exactly one target
+
+A `WaitFor` payload names the wait point by `name`, relative to the running
+execution, or by an absolute `token`. `WaitFor.WaitForRequestInvalid` is the
+typed refusal:
+
+| Code                | What was wrong                                                                                    |
+| ------------------- | ------------------------------------------------------------------------------------------------- |
+| `missing_target`    | The payload named neither `name` nor `token`.                                                     |
+| `ambiguous_target`  | It named both.                                                                                    |
+| `malformed_token`   | The token does not parse.                                                                         |
+| `foreign_execution` | The token is addressed to another flow or another execution, which this execution cannot observe. |
+
+`foreign_execution` is a refusal rather than a silent park because a foreign
+token would park forever while the value it names was recorded somewhere else.
+
+## Durable deferreds on their own
+
+`WaitFor` is a thin declaration over `DurableDeferred`, and you can use the
+primitive directly inside an implementation:
+
+```ts
+const Approval = DurableDeferred.make("Approval", {
+  success: Schema.Boolean,
+  error: Schema.String
+})
+
+// Inside a flow: park until it is completed.
+const awaited = DurableDeferred.await(Approval)
+
+// Or run an effect and record its exit into the deferred.
+const computed = DurableDeferred.into(Effect.succeed(true), Approval)
+
+// Race several, persisting the first exit under `raceAll/first-answer`.
+const winner = DurableDeferred.raceAll({
+  name: "first-answer",
+  success: Schema.Boolean,
+  error: Schema.String,
+  effects: [awaited, computed]
+})
+```
+
+Four surfaces complete a deferred from outside, and all four take a token:
+`DurableDeferred.succeed`, `fail`, `failCause`, and `done` with a full `Exit`.
+Inside a running flow, `DurableDeferred.token(self)` mints the token for the
+current execution.
+
+Two rules govern every completion:
+
+- **First writer wins.** The first recorded exit is the one every later read
+  replays. A second completion does not overwrite it.
+- **A token names one deferred.** A token whose `deferredName` is not this
+  deferred's fails with `DurableDeferred.TokenInvalid` carrying
+  `deferred_mismatch`, and a token that does not parse fails with
+  `malformed_token`.
+
+A token encodes the flow name, the execution id, and the deferred name, which is
+exactly what another process needs to write to the right durable address.
+`DurableDeferred.TokenParsed` is the decoded form.
+
+## Related pages
+
+- [Ask a person for a decision](./ask-a-person.md): the same wait point machinery
+  with validation, re-asking, and a deadline on top.
+- [Wait for a deadline](./wait-for-a-deadline.md): the timer half of the same
+  vocabulary.
+- [Hand work to a durable worker](./queue-work-to-a-worker.md): a deferred used
+  as a request and response channel.

package/docs/installation.md

@@ -0,0 +1,82 @@
+---
+title: "Installation"
+description: "Install @smthrs/flow, its runtime requirements and pinned effect version, its import forms, and the packages a runnable composition adds."
+sidebar:
+  order: 1
+---
+
+## Install the package
+
+`@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/Schema` and your implementations import `effect/Effect` directly, and two
+copies of `effect` in one program are two sets of service tags.
+
+The package requires Node.js 26.4.0 or later. It ships as both ESM and
+CommonJS with TypeScript declarations, and it pulls in
+[`@smthrs/plan`](/api/plan), [`@smthrs/crypto`](/api/crypto),
+[`@smthrs/keys`](/api/keys), and [`@smthrs/canonical`](/api/canonical), which
+supply the node vocabulary a body is written in, the digests identity is built
+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`.
+
+Create a project beside the checkout:
+
+```bash
+mkdir my-flows && cd my-flows
+echo '{ "type": "module" }' > package.json
+ln -s /path/to/smithers/examples/node_modules node_modules
+```
+
+Replace `/path/to/smithers` with the absolute path to your installed checkout. Run programs with `node <file>.ts`. Packages absent from the examples workspace, such as `@smthrs/artifacts`, resolve only inside the checkout; use the owning package's workspace for those examples. This linking recipe uses source exports and requires no package build.
+
+## Import forms
+
+The root entry point re-exports every module as a namespace:
+
+```ts
+import { Action, DurableDeferred, Flow, Interpreter, RetryPolicy } from "@smthrs/flow"
+```
+
+Several modules are also importable from their own subpath, which is the form the
+reference uses:
+
+```ts
+import * as CacheEnvironment from "@smthrs/flow/CacheEnvironment"
+import * as Flow from "@smthrs/flow/Flow"
+```
+
+The `exports` map publishes `@smthrs/flow/Action`, `/CacheEnvironment`,
+`/FileBoundary`, `/FileInput`, `/Flow`, `/FlowRuntime`, `/StepIdentity`, and one
+subpath per top-level module (`DurableClock`, `DurableDeferred`, `DurableQueue`,
+`Graph`, `HumanTask`, `Interpreter`, `Poll`, `RetryPolicy`, `Sleep`, `WaitFor`).
+Four subpath shapes resolve to nothing on purpose: `@smthrs/flow/internal/*`,
+`@smthrs/flow/*/index`, and the per-file paths under `Action/`, `Flow/`, and
+`FlowRuntime/`. Reach those namespaces through their directory subpath instead.
+`@smthrs/flow/package.json` is exported.
+
+## What a runnable composition adds
+
+This package declares the `FlowRuntime` port and implements none of it, so a
+composition that runs a flow adds an engine and a platform crypto service.
+
+- [`@smthrs/engine`](/api/engine) implements `FlowRuntime`. Its
+  `FlowEngine.layerMemory` keeps every recorded step in the process, which is
+  what the [Quickstart](./quickstart.md) and most tests use.
+- `@effect/platform-node` supplies `NodeCrypto.layer`. An action dispatch is
+  recorded under a derived step identity, so the engine needs a `Crypto` service
+  even in memory. A browser host supplies its own, such as `BrowserCrypto` from
+  `@effect/platform-browser`; nothing in this package imports a Node built-in.
+
+Add [`@smthrs/engine-store`](/api/engine-store) when the recorded steps have to
+outlive the process. It backs the same port with SQLite, which is what turns a
+suspended run into one a later process resumes.
+
+## Next step
+
+Run a flow end to end in the [Quickstart](./quickstart.md).

package/docs/quickstart.md

@@ -0,0 +1,155 @@
+---
+title: "Quickstart"
+description: "Declare an action and a flow, compose the layers, run the flow on the in-memory engine, and read a typed result."
+sidebar:
+  order: 2
+---
+
+This quickstart runs one flow end to end on the in-memory engine. Nothing here
+touches a database or the network, and the result arrives as a typed value
+decoded by the schema you declared.
+
+A runnable copy of this program is published in the Smithers examples,
+[`01-define-and-run.ts`](https://github.com/smithersai/smithers/blob/main/examples/src/01-define-and-run.ts).
+
+## Prerequisites
+
+- Node.js 26.4.0 or later.
+- A package with the dependencies installed. Not on npm yet; see [Installation](./installation.md#use-the-libraries).
+
+## Declare the action and the flow
+
+Create `quickstart.ts`. `Action.make` with a string tag is the declared form:
+schemas and a stable name, no code.
+
+```ts
+import { Action, Flow } from "@smthrs/flow"
+import { Node } from "@smthrs/plan"
+import * as Schema from "effect/Schema"
+
+export const Greet = Action.make("examples/Greet", {
+  payload: { name: Schema.String },
+  success: Schema.String
+})
+
+export const Greeting = Flow.make("examples/Greeting", {
+  payload: { name: Schema.String },
+  success: Schema.String,
+  body: Node.capture(
+    { action: Greet.name, implementationVersion: "greeting/v1" },
+    (payload) => Greet.call(payload)
+  )
+})
+```
+
+`Greet.call(payload)` records one node and runs nothing. It also puts a
+requirement in the node's type, which `Flow.make` reads off the body: the flow
+now says in its own type that it names an implementation it does not carry.
+
+## Attach the implementation and compose the layers
+
+`Node.capture` declares every semantic value outside the callback source. Here
+it names the action and versions the imported behavior. Change that version when
+that behavior changes. JavaScript cannot verify capture completeness.
+
+`toLayer` is where the code lives. `Interpreter.layerWithImplementations`
+registers the flow and its implementations with stable callback admission. It
+refuses uncaptured callbacks before dispatch. The lower-level `Graph.build` and
+`Interpreter.layer` default to `process-local`, which makes no cross-process
+callback identity guarantee.
+
+Compose the layers:
+
+```ts
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
+import { FlowEngine } from "@smthrs/engine"
+import { Interpreter } from "@smthrs/flow"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+
+const GreetingLayer = Interpreter.layerWithImplementations(
+  Greeting,
+  Greet.toLayer(({ name }) => Effect.succeed(`Hello, ${name}.`))
+).pipe(
+  Layer.provideMerge(FlowEngine.layerMemory),
+  Layer.provideMerge(NodeCrypto.layer)
+)
+```
+
+`layerWithImplementations` supplies the action registry while building the
+implementation layers. The remaining providers supply the runtime and digest:
+
+- `FlowEngine.layerMemory` supplies the `FlowRuntime` port. Swap it for the
+  durable engine from [`@smthrs/engine-store`](/api/engine-store) and nothing
+  above changes.
+- `NodeCrypto.layer` supplies `Crypto`. Every dispatch is recorded under a
+  derived step identity, so the engine needs a digest even in memory.
+
+## Run it
+
+`execute` takes the payload and an execution id:
+
+```ts
+export const main: Effect.Effect<string> = Greeting.execute(
+  { name: "Ada" },
+  { executionId: "greeting-ada-1" }
+).pipe(
+  // A payload that misses the flow's schema is a typed failure, not a defect.
+  // This payload is statically valid, so a refusal here would be a bug.
+  Effect.orDie,
+  Effect.provide(GreetingLayer)
+)
+
+console.log(await Effect.runPromise(main))
+```
+
+Run the file with your TypeScript runner. The output is the decoded success
+value:
+
+```text
+Hello, Ada.
+```
+
+## Run it twice
+
+Execute the same flow again under the same execution id. The action does not run
+a second time:
+
+```ts
+export const twice: Effect.Effect<string> = Effect.gen(function*() {
+  const run = Effect.orDie(
+    Greeting.execute({ name: "Ada" }, { executionId: "greeting-ada-1" })
+  )
+  yield* run
+  return yield* run
+}).pipe(Effect.provide(GreetingLayer))
+```
+
+An execution id names one run. The second call finds the run that already
+settled and answers with its result instead of starting another, and a durable
+engine behaves the same way across a restart: it rebuilds the plan, derives the
+same key for the same node, reads the recorded result, and reaches only the
+steps that never settled. That is what separating the plan from the code buys.
+Identity is a function of the declaration, so a repeat is a read.
+
+An execution id is also a claim about what the run is. Reusing one for a
+different flow, or for a different payload, is refused rather than silently
+joined.
+
+## What just happened
+
+`Greeting.execute` asked the runtime for an execution under
+`greeting-ada-1`. The interpreter built the graph of the body, walked it, and
+dispatched `examples/Greet` through the engine, which recorded the attempt and
+its result. With a pure body, complete captures, and stable callback admission,
+unchanged source, captures, declarations, and payload reproduce the same plan
+keys across processes. Changed source, captures, or implementation versions
+require a newly planned run.
+
+## Next steps
+
+- [Flows and actions](./concepts/flows-and-actions.md): why the implementation
+  attaches separately, and what the requirement channel buys you.
+- [Build a body](./guides/build-a-body.md): sequencing, fan-out, branches, and
+  recovering from a typed failure.
+- [Testing](./testing.md): the same in-memory composition as a test habit.