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

package/CHANGELOG.md

@@ -0,0 +1,160 @@
+# @smthrs/flow
+
+## Unreleased
+
+### Added
+
+- Canonical `Flow.make(tag, options)` accepts typed prompt declarations lowered
+  to ordinary actions with explicit host implementations (#2271). Empty tags
+  and declarations without exactly one callable body or prompt are refused.
+
+### Fixed
+
+- Preserve dynamic flow expansion and declaration source mappings when a bundled host loads project flows. ([#1991](https://github.com/smithersai/smithers/issues/1991)).
+
+## [Unreleased]
+
+### Changed
+
+- The package reference page now lives at `docs/reference/flow.md`, written by
+  the `referenceDocs` target. The `docs/pages/api/flow.md` page,
+  `scripts/docs.mjs` and the `docsPages` target described under 0.1.0 no
+  longer exist. (`flows-flow/maintainability/7`)
+
+### Removed
+
+- `FlowInstance.awaitedDeferreds`. No runtime read the set, and
+  `DurableDeferred.await` no longer writes it. A completion wakes a parked run
+  through `FlowRuntime.resume`, unchanged. (`flows-flow/simplicity/1`)
+
+### Fixed
+
+- Nested explicit `Node.andThen` continuations now carry only their nearest
+  success barrier, preserving transitive ordering while making continuation
+  edges and `Pending` inputs linear for right-nested chains. This is a
+  pre-freeze key-affecting change: affected compiled keys/digests change and
+  require a newly approved plan; existing executions are not rewritten.
+  Structural `.andThen`/`.then` node IDs retain their spelling and durable
+  dispatch identity. Their depth growth and quadratic total ID bytes are now
+  documented, with bounded trampoline rounds or `.child()` boundaries for long
+  chains. (`flows-flow/performance/1`, `flows-flow/performance/5`)
+
+- Explicit `Node.andThen` now gates its entire next subtree on upstream
+  success. Nested combinations, maps, inline flows, branches, catches and
+  sequences no longer start actions before the first node finishes or after
+  it fails. Graph drafts propagate that prerequisite to every descendant.
+  Affected compiled keys/digests change and require a newly approved plan;
+  old executions are not silently rewritten. `bindPlanned` retains its data-
+  dependency semantics and can expose independent work concurrently. This
+  does not close compiled/public scheduler parity or unfinished-run migration.
+
+## [1.0.0-rc.0] - 2026-08-31
+
+### Breaking Changes
+
+- `Flow.make` now requires `body`. A flow with nothing to plan is a category
+  error under `docs/specs/Concepts/Unified Flow Authoring.md`: that work is an
+  `Action`. Every declaration therefore carries a body, and `Flow.Any.body`
+  is no longer optional.
+- Removed `toLayer` from the flow surface. Actions carry implementations,
+  attached separately with `Action.toLayer`; flows carry bodies, driven by
+  `Interpreter.layer`. Registering a behavior under a flow tag is the runtime's
+  own seam and is now internal to this package.
+- Removed `Flow.Bodied`, which existed only to describe a flow that had a body.
+  `Flow.Flow` is that type now.
+- Removed `Flow.BodyDefinesBehavior`, the defect a bodied flow raised when a
+  second, opaque behavior was attached to it. There is nothing to attach.
+- Removed the `missing_body` code from `Interpreter.InterpreterError`.
+  `Interpreter.layer` takes a flow that has a body by construction.
+- `CancelRequestFailed` now carries the `_tag`
+  `@smthrs/flow/CancelRequestFailed`. It was the one error in the package still
+  reading `flows/engine/CancelRequestFailed`, a name that was never even the
+  old package's. A `_tag` is wire format and freezes at the RC.
+- The runtime type identifiers moved out of effect's brand namespace. Every
+  `~effect/flow/...` marker now reads `@smthrs/flow/...`, including the
+  exported `DurableDeferred.TokenTypeId` and `DurableQueue.TypeId`.
+- Execution ids derived from a declared `idempotencyKey`, and from the default
+  ambient source, now hash a framed `JSON.stringify([flowTag, key])` tuple
+  instead of an unframed `` `${tag}-${key}` `` string, so a tag and a key that
+  spliced onto one preimage no longer address one durable invocation. Ids
+  derived before this change do not match ids derived after it.
+
+### Added
+
+- Added `@smthrs/flow`, the flow authoring model split out of
+  `@smthrs/engine`: `Flow`, `Action`, `RetryPolicy`, `DurableDeferred`,
+  `DurableClock`, `DurableQueue`, `StepIdentity`, and their schemas, errors,
+  results, boundaries, and combinators.
+- Added `FlowRuntime`, the execution contract those APIs are written against.
+  It replaces the direct dependency the authoring modules had on the engine's
+  `FlowEngine` module, so the dependency now runs `@smthrs/flow` then
+  `@smthrs/engine`. The service formerly exported as `FlowEngine.FlowEngine` is
+  `FlowRuntime.FlowRuntime`, `FlowEngine.FlowInstance` is
+  `FlowRuntime.FlowInstance`, and `FlowEngine.annotateWaiting` and
+  `FlowEngine.FlowCycleDetected` moved with them.
+- `Graph.build` copies an authored `Node.priority` onto `NodeDraft.priority`,
+  so `PlanScheduler` orders ready work by it. A node inherits the priority of
+  the nearest enclosing node that declares one, and a node that declares its
+  own keeps it. Priority stays out of key material.
+- Added `Action.InfraInterruptRetriesExhausted`, the typed identity an
+  exhausted `interruptRetryPolicy` now dies with. It carries the action name,
+  the attempts made, and the final `InfraInterrupt` including its `reason`,
+  which the previous bare-string defect discarded.
+- Added the `invalid_deadline` code to `Sleep.SleepRequestInvalid`.
+- Added the `duplicate_node_id` code to `Interpreter.InterpreterError`, and a
+  matching build diagnostic, so two nodes that would answer to one dispatch
+  address are refused instead of resolving last-write-wins.
+- Added the `deferred_mismatch` code to `DurableDeferred.TokenInvalid`.
+- Added the stable `poll_exhausted` code to `Poll.PollExhausted`, and a
+  constructor default for the `code` of `FlowRuntime.FlowCycleDetected` and
+  `FlowRuntime.FlowExecutionNotFound`.
+- Added documented size bounds to `HumanTask`: `maxAttemptBudget`,
+  `maxSchemaDepth`, `maxSchemaNodes`, `maxAnswerNodes`, `maxDiagnosticChars`,
+  and `maxRetainedRejectionChars`.
+- Added package-owned documentation. `docs/api.md` plus the JSDoc on every
+  exported declaration generate `docs/pages/api/flow.md` through
+  `scripts/docs.mjs`, declared as the `docsPages` target, so the published page
+  cannot drift from the source it describes.
+
+### Fixed
+
+- `RetryPolicy.make` validates its bounds and throws a `RangeError` naming the
+  offending field, and copies and freezes `nonRetryable`. `nextDelay` is total
+  for a policy that never went through `make`: a jitter ratio out of range no
+  longer returns a negative delay, and a non-finite bound, attempt, elapsed
+  time, or computed delay answers `None` instead of handing the engine a `NaN`
+  duration to sleep for.
+- `Sleep.action` refuses a `millis` or `until` that is not a length of time.
+  `Infinity` armed a timer nobody wakes, and `NaN` did not wait at all while
+  leaving a waiting annotation whose `wakeAt` serialized to null.
+- `HumanTask` compares `enum` membership structurally, so an object-valued or
+  array-valued member can be answered. It previously compared with `===`, which
+  refused every answer and ended the task `rejected`.
+- `HumanTask` refuses a `schema` supplied with a kind other than `json`, and
+  refuses a malformed `required` or `nullable`, instead of silently dropping
+  the constraint.
+- `DurableDeferred.into` propagates `interrupted` to the parent instance beside
+  `suspended`, so a recorded interruption awaited through `raceAll` settles as
+  a durable outcome instead of being misread as an external suspension.
+- `DurableDeferred.done` refuses a token that names a different deferred than
+  the one it was submitted through, so an exit cannot be written into one
+  deferred's row under another's schemas.
+- `DurableDeferred.TokenInvalid` carries the parse failure and a bounded
+  excerpt of the offending token instead of one fixed sentence.
+- `DurableQueue.makeWorker` validates `concurrency`, reports a malformed item
+  token at error level instead of dropping the item behind one warning, and
+  backs off instead of spinning when `take` fails repeatedly. Both log
+  annotations now name `@smthrs/flow` rather than `effect`.
+- `Graph.placementConflicts` compares directives structurally instead of
+  through `JSON.stringify`, which erased a present `undefined`, mapped `NaN` to
+  `null`, and threw on a `BigInt`.
+- `Flow.isResult` requires an own data property carrying the exact marker and a
+  known result tag, so a forged or getter-backed value no longer passes.
+- `Interpreter.childExecutionId` finds the versioned key prefix instead of
+  slicing a hardcoded length.
+- Corrected the module headers in `Action/Errors.ts` and `RetryPolicy.ts`,
+  which claimed the error tags keep an `@smthrs/engine/` prefix that no tag in
+  either file uses, and the `FlowInstance.awaitedDeferreds` JSDoc, which
+  asserted preemption behaviour no runtime in this repository implements.
+- Normalized the inherited `@since 4.0.0` tags, which named effect's version
+  rather than any version of this package.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Cory and the Smithers Flows contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,211 @@
-# Temporary Holding Version
+# @smthrs/flow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Release candidate scope, host requirements and compatibility review are defined in the [library support policy](https://github.com/smithersai/smithers/blob/main/RELEASE_SUPPORT.md).
+
+This package declares `effect` as an exact
+`4.0.0-rc.115` peer dependency. Keep the application on that version so
+all Smithers packages share one Effect runtime.
+
+**Documentation:** https://flow.smithers.sh
+
+`@smthrs/flow` is the authoring model for durable workflows in TypeScript. You
+declare each step as an **action**: a stable name and the schemas on either side
+of it, with no code. You compose those declarations into a **flow** whose body is
+a pure function that builds a plan. The code that does the work attaches
+separately, as an Effect layer.
+
+A typed `prompt` can declare a single model-backed step with the same
+`Flow.make(tag, options)` signature. It lowers to an ordinary action; the host
+implements `flow.action` and renders `flow.prompt` at execution. See
+[Prompt-backed flows](./docs/guides/use-a-prompt.md).
+
+The package carries no engine. It declares the `FlowRuntime` port that an engine
+implements, so the whole authoring surface bundles for a browser and a test can
+swap the runtime for a fixture without touching a declaration.
+[`@smthrs/engine`](https://engine.smithers.sh) implements that port;
+[`@smthrs/engine-store`](https://engine-store.smithers.sh) makes it durable.
+
+## Why
+
+A job that calls a model, spawns a build, uploads an artifact, or waits on a
+person cannot afford to start over when the process dies. Recovering by hand
+means writing your own checkpoint table, your own idempotency keys, and your own
+"did this already run" branch around every call.
+
+A flow builds its plan before anything runs. Reproducible keys require callbacks
+whose source and complete semantic captures are stable. `Node.capture` declares
+those captures; the canonical `Interpreter.layerWithImplementations` composition
+refuses callbacks with process-local identity before dispatch. An engine records
+each step as it settles, so a re-run
+under the same execution id reads the recorded result rather than repeating the
+work. The same property is what lets the engine retry a step, cache it, park a
+run on a timer or a human answer for a week, and put one step on another machine,
+none of which the flow's author arranges.
+
+## Install
+
+Not on npm yet; see [Installation](./docs/installation.md#use-the-libraries).
+
+Node.js 26.4.0 or later. `effect` is a peer at exactly `4.0.0-rc.115`: two copies of
+`effect` in one program are two sets of service tags.
+
+Running a flow adds an engine and a platform crypto service.
+
+## Declare a flow and run it
+
+This program declares one recorded step, attaches its implementation, and runs
+the flow on the in-memory engine.
+
+```ts
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
+import { FlowEngine } from "@smthrs/engine"
+import { Action, Flow, Interpreter } from "@smthrs/flow"
+import { Node } from "@smthrs/plan"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Schema from "effect/Schema"
+
+/** A step declaration is data: a stable tag and the schemas either side of it. */
+const Summarize = Action.make("digest/Summarize", {
+  implementationVersion: "summarize/v1",
+  payload: { url: Schema.String },
+  success: Schema.String
+})
+
+/** A flow body records nodes. `Summarize.call` plans a step and runs nothing. */
+const Digest = Flow.make("digest/Digest", {
+  payload: { url: Schema.String },
+  success: Schema.String,
+  body: Node.capture(
+    { action: Summarize.name, implementationVersion: "digest/v1" },
+    (payload) => Summarize.call(payload)
+  )
+})
+
+/** The code arrives separately, filed against the tag by `toLayer`. */
+const layer = Interpreter.layerWithImplementations(
+  Digest,
+  Summarize.toLayer(
+    ({ url }) => Effect.succeed(`A summary of ${url}.`),
+    { implementationVersion: "summarize/v1" }
+  )
+).pipe(
+  Layer.provideMerge(FlowEngine.layerMemory),
+  Layer.provideMerge(NodeCrypto.layer)
+)
+
+const main = Digest.execute(
+  { url: "https://example.com/post" },
+  { executionId: "digest-example-post" }
+).pipe(Effect.orDie, Effect.provide(layer))
+
+console.log(await Effect.runPromise(main))
+```
+
+Run it and the implementation runs once. Run the same execution id again and it
+does not: the engine finds the execution that already settled and answers with
+its recorded result. Swap `FlowEngine.layerMemory` for the SQLite-backed engine
+in `@smthrs/engine-store` and the same behavior survives a restart, with nothing
+above the swap changing.
+
+Forgetting an implementation is a compile error rather than a run that dies
+partway through. `Summarize.call(payload)` puts a requirement in the node's type,
+`Flow.make` reads the union of those off the node its body returns, and
+`Summarize.toLayer(...)` is what discharges it.
+
+## Callback identity and persisted compatibility
+
+Use `Node.capture` for flow bodies, `Node.map` callbacks, `Node.branch` predicates,
+and `Node.bindPlanned` builders. Validate external configuration with its schema
+first, then close over the exact record passed to `Node.capture`; it is deeply
+frozen. Include every semantic value, including payload fields used by a nested
+callback and an explicit version for imported implementation behavior. JavaScript
+cannot inspect closures, so the library cannot prove that a capture declaration
+is complete. Capturing `{}` is valid only when no semantic state outside the
+callback source affects its behavior.
+
+`Graph.build(flow, payload, { callbackIdentity: "stable" })` reports unstable
+callback sites and `Graph.drafts` refuses them. `Interpreter.layerWithImplementations`
+uses that policy by default and rejects the graph before any action dispatch.
+The lower-level `Graph.build`, `Interpreter.interpret`, and `Interpreter.layer`
+default to `process-local` for compatibility; they make no reproducible callback
+identity guarantee unless `callbackIdentity: "stable"` is selected. An explicit
+`process-local` option is available on the canonical composition for experimentation.
+
+`sha256-source-captures/v5` includes shared-reference topology in capture
+identity. Equal source and captures reproduce identity across processes.
+The v5 encoding re-keys captured callbacks from earlier versions. Changed source, captures, or captured implementation version require
+a newly planned run; this check does not migrate or reapprove existing plans.
+Action implementations use a separate `implementationVersion` contract.
+Canonical `Interpreter.layerWithImplementations` requires it for sealed actions
+that declare an idempotency key, because those actions can reuse recorded content.
+Declare the version on `Action.make`, and attest the same version in `toLayer`.
+A missing or different registration version is refused. The interpreter also
+checks each graph declaration against the registry before dispatching any action,
+including actions in untaken branches. The declared version enters plan material,
+sealed result keys, and ordinal invocation scopes. Object-form idempotency keys
+remain rename-stable; their caller-owned input cannot override the explicit
+implementation version.
+
+The version is a semantic compatibility declaration. Cover the handler and every
+service/configuration change that can affect its result. Equal versions authorize
+reuse even if JavaScript source changed. Different versions require a new plan
+and execution ID; this is not an upgrade API for an already persisted run. Existing
+completed executions keep their recorded outcomes. Omitted versions preserve
+legacy key material exactly and do not infer handler identity from source.
+The low-level `Interpreter.layer` and `Interpreter.interpret` retain this legacy
+behavior: equal identity inputs can return the old handler's recorded result
+after its code changes. Selecting stable callback identity alone does not change
+that handler-reuse contract.
+
+Canonical version admission is independent of `callbackIdentity`; choosing
+`process-local` callbacks cannot bypass it. Keyless sealed actions use run-local
+invocation keys, while compensable and irreversible actions do not use content-key
+caching, so those declarations may omit a version. The canonical interpreter also
+refuses detached action nodes whose declarations are unavailable for checking.
+No policy can verify that an author's semantic version declaration is complete.
+
+## What is in the package
+
+Every namespace below is exported from the root and from a matching
+`@smthrs/flow/*` subpath.
+
+| Namespace         | Role                                                                                    |
+| ----------------- | --------------------------------------------------------------------------------------- |
+| `Flow`            | Declares a durable program and its execute, poll, interrupt, resume, and rollback API.  |
+| `Action`          | Declares one recorded step: schemas, tier, idempotency identity, retry policy, caching. |
+| `Graph`           | Builds the plan a body describes, before any of it runs.                                |
+| `Interpreter`     | Drives that plan, and registers a flow with the runtime.                                |
+| `FlowRuntime`     | The execution port this package declares and an engine implements.                      |
+| `DurableDeferred` | A persisted promise a flow awaits across process restarts, completed by token.          |
+| `DurableClock`    | A timer that eventually completes a `DurableDeferred`.                                  |
+| `DurableQueue`    | Sends work to a persisted worker and awaits its result.                                 |
+| `Sleep`           | The system timer, declared as an ordinary action.                                       |
+| `WaitFor`         | The system wait point, declared as an ordinary action.                                  |
+| `Poll`            | The durable poller: attempts as rounds, waits as durable timers.                        |
+| `Stall`           | The stall breaker: ends rounds whose tree, failing checks, or output held still.        |
+| `HumanTask`       | Asking a person something, with validation, re-asking, and a deadline.                  |
+| `RetryPolicy`     | Data describing when a runtime should retry a failed action.                            |
+| `StepIdentity`    | The one canonical derivation of ordinal step identity.                                  |
+
+## Documentation
+
+Full documentation is at [flow.smithers.sh](https://flow.smithers.sh).
+
+- [Quickstart](https://flow.smithers.sh/quickstart/): the program above end to
+  end, including what happens on the second run.
+- [Flows and actions](https://flow.smithers.sh/concepts/flows-and-actions/): the
+  two nouns, and why an implementation attaches as a layer.
+- [Bodies are plans](https://flow.smithers.sh/concepts/bodies-and-plans/): what a
+  body may not do, and why that restriction is what makes replay work.
+- [Guides](https://flow.smithers.sh/guides/build-a-body/): composing a body,
+  retries, durable waits, human decisions, child flows, and rollback.
+- [API reference](https://flow.smithers.sh/reference/api/): every public export.
+- [Testing](https://flow.smithers.sh/testing/): topology, interpretation, and
+  execution, and which level a given assertion belongs at.
+
+## License
+
+MIT. See `LICENSE`.
+
+`Action.InfraInterrupt` is an explicit adapter marker for `interruptRetryPolicy`; ordinary fiber interruption is never converted to it.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,52 @@
+# Third-party notices
+
+This distribution contains third-party software. The notices below are
+reproduced to satisfy the terms of the licenses those components are
+distributed under. They are in addition to, and do not replace, the project's
+own `LICENSE`.
+
+## Effect (`Effect-TS/effect`)
+
+`@smthrs/flow` carries the flow-authoring half of a fork of Effect's unstable
+durable-flow runtime and
+contains substantial portions of that source. The fork point, upstream package
+version, and a module-by-module record of what was vendored and how it was
+changed are documented in `packages/smithers/flows/engine/VENDOR.md`:
+
+- Upstream repository: `Effect-TS/effect`
+- Upstream commit: `23e176a4f05ed3e81cc13a5d70111099692ea9a5`
+- Upstream package: `effect@4.0.0-beta.102`
+- Upstream source: `packages/effect/src/unstable/workflow`
+- Vendored modules: `Flow.ts`, `Activity.ts`, `FlowEngine.ts`,
+  `DurableClock.ts`, `DurableDeferred.ts`, `DurableQueue.ts`, `FlowProxy.ts`,
+  `FlowProxyServer.ts`, and `index.ts`
+
+Effect is distributed under the MIT License. Its copyright and permission
+notice is reproduced here verbatim:
+
+```
+MIT License
+
+Copyright (c) 2023 Effectful Technologies Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+Every `@smthrs/*` package also depends on Effect at runtime, so the notice
+above applies to those dependencies as well as to the vendored engine source.