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

package/src/FlowRuntime/FlowRuntime.ts

@@ -0,0 +1,333 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * The execution contract flow authoring APIs are written against.
+ *
+ * `FlowRuntime` is the port: the smallest service a `Flow`, an `Action`, a
+ * `DurableDeferred`, or a `DurableClock` needs in order to be executed,
+ * polled, suspended, and resumed. `@smthrs/flow` declares it and depends on
+ * nothing that implements it; `@smthrs/engine` supplies the implementation,
+ * so the dependency runs one way only.
+ *
+ * Every method here takes a flow whatever its requirement channel says, and
+ * demands none of it. The channel is a compile-time statement about which
+ * action implementations a body names, and this port is below the place that
+ * statement is settled: a runtime resolves each call by the tag the node
+ * carries, which is the only thing left of a plan read back out of a journal.
+ * `Flow.execute` — written against this port, one level up — is where the
+ * requirements are collected, so the erasure is deliberate rather than a hole:
+ * a caller reaching the port directly has already been asked, or is replaying a
+ * persisted plan and has nothing to be asked about.
+ *
+ * @since 0.1.0
+ */
+
+import * as Context from "effect/Context"
+import type * as Crypto from "effect/Crypto"
+import type * as Effect from "effect/Effect"
+import type * as Exit from "effect/Exit"
+import type * as Option from "effect/Option"
+import type * as Schema from "effect/Schema"
+import type * as Scope from "effect/Scope"
+import type * as Action from "../Action/index.ts"
+import type { DurableClock } from "../DurableClock.ts"
+import type * as DurableDeferred from "../DurableDeferred.ts"
+import type * as Flow from "../Flow/index.ts"
+import type * as RetryPolicy from "../RetryPolicy.ts"
+import type { CancelRequestFailed } from "./CancelRequestFailed.ts"
+import type { FlowCycleDetected } from "./FlowCycleDetected.ts"
+import type { FlowExecutionNotFound } from "./FlowExecutionNotFound.ts"
+import type { FlowInstance } from "./FlowInstance.ts"
+import type * as NodeRecord from "./NodeRecord.ts"
+
+/**
+ * Result of atomically completing a deferred only while its run is parked.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type DeferredDoneIfWaitingOutcome = "Completed" | "Existing" | "NotWaiting"
+
+/**
+ * How a caller asks a suspended execution to resume.
+ *
+ * `delegated` marks a background resume a host takes up on someone else's
+ * behalf: an approval decision, a saved request, a peer's delegation. It is
+ * not recovery consent, so a durable engine refuses it for a quarantined
+ * execution in the same transaction that reads the park. A host that checks
+ * the park first and resumes after has a window in which a peer can
+ * quarantine the run; only the engine's own check closes it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface ResumeOptions {
+  readonly poll?: boolean | undefined
+  readonly delegated?: boolean | undefined
+}
+
+/**
+ * Service that represents a flow runtime, responsible for registering and
+ * executing flows and coordinating actions, durable deferreds,
+ * interrupts, resumes, and clocks.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class FlowRuntime extends Context.Service<
+  FlowRuntime,
+  {
+    /** Storage capability advertised by the runtime implementation. Absence is volatile. */
+    readonly durability?: "durable" | undefined
+    /**
+     * Register a flow with the runtime. `ifAbsent` preserves a live registration
+     * when discovering a reachable child. Explicit registrations otherwise
+     * replace the registered handler; the registration scope owns its removal.
+     */
+    readonly register: <
+      Name extends string,
+      Payload extends Flow.AnyStructSchema,
+      Success extends Schema.Top,
+      Error extends Schema.Top,
+      R
+    >(
+      flow: Flow.Flow<Name, Payload, Success, Error, any>,
+      execute: (
+        payload: Payload["Type"],
+        executionId: string
+      ) => Effect.Effect<Success["Type"], Error["Type"], R>,
+      options?: { readonly ifAbsent?: boolean | undefined }
+    ) => Effect.Effect<
+      void,
+      never,
+      | Scope.Scope
+      | Exclude<
+        R,
+        | FlowRuntime
+        | FlowInstance
+        | Flow.Execution<Name>
+        | Scope.Scope
+      >
+      | Payload["DecodingServices"]
+      | Payload["EncodingServices"]
+      | Success["DecodingServices"]
+      | Success["EncodingServices"]
+      | Error["DecodingServices"]
+      | Error["EncodingServices"]
+    >
+
+    /**
+     * Execute a registered flow.
+     */
+    readonly execute: <
+      Name extends string,
+      Payload extends Flow.AnyStructSchema,
+      Success extends Schema.Top,
+      Error extends Schema.Top,
+      const Discard extends boolean = false
+    >(
+      flow: Flow.Flow<Name, Payload, Success, Error, any>,
+      options: {
+        readonly executionId: string
+        readonly payload: Payload["Type"]
+        readonly discard?: Discard | undefined
+        readonly suspendedRetryPolicy?:
+          | RetryPolicy.RetryPolicy
+          | undefined
+      }
+    ) => Effect.Effect<
+      Discard extends true ? string : Success["Type"],
+      Error["Type"] | FlowCycleDetected,
+      | Payload["EncodingServices"]
+      | Success["DecodingServices"]
+      | Error["DecodingServices"]
+    >
+
+    /**
+     * Poll the current status of a registered flow execution.
+     *
+     * `Option.none` means the execution is known and has not settled;
+     * {@link FlowExecutionNotFound} means the runtime has no record of the
+     * execution id at all. Folding the two together would leave a caller
+     * unable to tell a run still in flight from an id that names nothing.
+     */
+    readonly poll: <
+      Name extends string,
+      Payload extends Flow.AnyStructSchema,
+      Success extends Schema.Top,
+      Error extends Schema.Top
+    >(
+      flow: Flow.Flow<Name, Payload, Success, Error, any>,
+      executionId: string
+    ) => Effect.Effect<
+      Option.Option<Flow.Result<Success["Type"], Error["Type"]>>,
+      FlowExecutionNotFound,
+      Success["DecodingServices"] | Error["DecodingServices"]
+    >
+
+    /**
+     * Requests cancellation of a registered execution while preserving normal
+     * cleanup, compensation, and child-flow handling. This is not a pause, and
+     * a later `resume` does not undo the cancellation request.
+     *
+     * A durable runtime records the request before it interrupts anything, and
+     * reports {@link CancelRequestFailed} when that record could not be
+     * written: the execution is then still running and still cancellable, so
+     * the caller must see the failure rather than a false success. An
+     * in-memory runtime has nothing to record and never raises it.
+     */
+    readonly interrupt: (
+      flow: Flow.Any,
+      executionId: string
+    ) => Effect.Effect<void, CancelRequestFailed>
+
+    /**
+     * Immediately cancels a registered execution, potentially ignoring
+     * compensation finalizers and orphaning child flows. This unsafe operation
+     * is intended for forced shutdown, not ordinary cancellation or pausing.
+     *
+     * It reports {@link CancelRequestFailed} on the same terms as
+     * `interrupt`: forcing cancellation without a durable record would leave a
+     * run that nothing later re-cancels.
+     */
+    readonly interruptUnsafe: (
+      flow: Flow.Any,
+      executionId: string
+    ) => Effect.Effect<void, CancelRequestFailed>
+
+    /**
+     * Re-drives a registered execution that returned `Suspended`, allowing it
+     * to replay durable history and continue after an awaited condition becomes
+     * ready. It does not undo `interrupt` and is not a general unpause operation.
+     *
+     * Without options this is the operator's own resume, which is authority
+     * to recover a quarantined execution. `poll` is background wake intent and
+     * does not authorize recovery of quarantined work. See {@link ResumeOptions}.
+     */
+    readonly resume: (
+      flow: Flow.Any,
+      executionId: string,
+      options?: ResumeOptions | undefined
+    ) => Effect.Effect<void>
+
+    /**
+     * Execute an action from a flow.
+     */
+    readonly actionExecute: <
+      Success extends Schema.Constraint,
+      Error extends Schema.Constraint,
+      R
+    >(
+      action: Action.Action<Success, Error, R>,
+      attempt: number
+    ) => Effect.Effect<
+      Flow.Result<Success["Type"], Error["Type"]>,
+      never,
+      | Success["DecodingServices"]
+      | Error["DecodingServices"]
+      | R
+      | Crypto.Crypto
+      | FlowInstance
+    >
+
+    /**
+     * Try to retrieve the result of an DurableDeferred
+     */
+    readonly deferredResult: <
+      Success extends Schema.Constraint,
+      Error extends Schema.Constraint
+    >(
+      deferred: DurableDeferred.DurableDeferred<Success, Error>
+    ) => Effect.Effect<
+      Option.Option<Exit.Exit<Success["Type"], Error["Type"]>>,
+      never,
+      FlowInstance
+    >
+
+    /**
+     * Records the result of a DurableDeferred and schedules waiting flows to
+     * resume. Returning acknowledges delivery; it does not wait for the resumed
+     * flow to complete. Use `poll` to observe the flow's eventual result.
+     */
+    readonly deferredDone: <
+      Success extends Schema.Constraint,
+      Error extends Schema.Constraint
+    >(
+      deferred: DurableDeferred.DurableDeferred<Success, Error>,
+      options: {
+        readonly flowName: string
+        readonly executionId: string
+        readonly deferredName: string
+        readonly exit: Exit.Exit<Success["Type"], Error["Type"]>
+      }
+    ) => Effect.Effect<
+      void,
+      never,
+      Success["EncodingServices"] | Error["EncodingServices"]
+    >
+
+    /**
+     * Completes a deferred only when the addressed execution is currently
+     * parked on the exact reason and token supplied. The check and the
+     * first-writer completion are one runtime mutation, preventing guessed,
+     * stale, or already-advanced approval tokens from pre-answering a run.
+     */
+    readonly deferredDoneIfWaiting: <
+      Success extends Schema.Constraint,
+      Error extends Schema.Constraint
+    >(
+      deferred: DurableDeferred.DurableDeferred<Success, Error>,
+      options: {
+        readonly flowName: string
+        readonly executionId: string
+        readonly deferredName: string
+        readonly reason: string
+        readonly token: string
+        readonly exit: Exit.Exit<Success["Type"], Error["Type"]>
+      }
+    ) => Effect.Effect<
+      DeferredDoneIfWaitingOutcome,
+      never,
+      Success["EncodingServices"] | Error["EncodingServices"]
+    >
+
+    /**
+     * Records what a driven graph is and how its nodes settled.
+     *
+     * OPTIONAL, and optional in the strong sense: a runtime that keeps no
+     * history has nothing to record, and the interpreter skips journal preflight when none does. An engine with a journal implements it by
+     * writing the record; an in-memory or test runtime leaves it absent and
+     * the walk is unchanged. That is also why it is not `void`-returning
+     * bookkeeping bolted onto `actionExecute`: a node is not an action, and
+     * three of the four records describe nodes no action ever dispatched.
+     *
+     * The record carries its own replay-stable `sourceId`. An implementation
+     * MUST use it as the record's producer identity rather than minting one,
+     * because that is what makes a resumed walk collapse onto the rows the
+     * first walk wrote instead of doubling every node.
+     */
+    readonly recordNode?:
+      | ((record: NodeRecord.NodeRecord) => Effect.Effect<void, never, FlowInstance>)
+      | undefined
+
+    /**
+     * Upper bound on UTF-8 bytes for a node record's persisted journal entry,
+     * including the writer's envelope. Used to page a plan before any writes.
+     * Must be deterministic for the execution so resume keeps page identities.
+     */
+    readonly nodeRecordBytes?:
+      | ((record: NodeRecord.NodeRecord) => Effect.Effect<number, never, FlowInstance>)
+      | undefined
+
+    /**
+     * Schedule a wake up for a DurableClock
+     */
+    readonly scheduleClock: (
+      flow: Flow.Any,
+      options: {
+        readonly executionId: string
+        readonly clock: DurableClock
+      }
+    ) => Effect.Effect<void>
+  }
+>()("@smthrs/flow/FlowRuntime/FlowRuntime") {}

package/src/FlowRuntime/NodeRecord.ts

@@ -0,0 +1,183 @@
+/**
+ * What a driven graph tells its runtime about itself.
+ *
+ * The interpreter knows the whole plan before the first action runs, and it
+ * knows when each node is scheduled and how each one settled. Nothing
+ * downstream can derive those facts: an attempt record carries a step key and
+ * no node id, so a monitor reading a journal can see the work and not the
+ * graph it belongs to. These records are the missing half, and this module is
+ * the only thing `@smthrs/flow` says about them — the port takes them, and an
+ * engine with a journal is what turns them into durable records. A runtime
+ * without one keeps its no-op and the interpreter is unchanged.
+ *
+ * Every record carries its own `sourceId`, and that is the replay-stability
+ * contract: a resumed walk rebuilds the same graph and re-derives the same
+ * ids, so a journal keyed by `(run, source, sequence)` collapses the second
+ * observation onto the first row instead of recording the node twice.
+ *
+ * @since 1.0.0
+ */
+
+import type * as Plan from "@smthrs/plan/Plan"
+import type { DeclaredAt } from "../internal/DeclarationSite.ts"
+
+/**
+ * One node of the graph a run was driven from.
+ *
+ * `tier` and `effects` are the declaration's own, and `dependsOn` is the
+ * material dependency set the plan compiles edges from. `action` is the tag a
+ * node dispatches, absent on every node that dispatches nothing. `declaredAt`
+ * is provenance and never identity: it is outside key material by
+ * construction, so adding it re-keys nothing.
+ *
+ * A node whose dependency list is wider than one page appears on several,
+ * each carrying the next DISJOINT slice of `dependsOn` and everything else
+ * unchanged. A reader assembles pages in order and unions `dependsOn` per id;
+ * keeping only the last summary would read a thousand-way fan-in as a node
+ * with two dependencies.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface NodeSummary {
+  readonly id: string
+  readonly kind: string
+  readonly dependsOn: ReadonlyArray<string>
+  readonly tier: "sealed" | "compensable" | "irreversible"
+  readonly action?: string | undefined
+  readonly effects?: Plan.NodeEffects | undefined
+  readonly declaredAt?: DeclaredAt | undefined
+}
+
+/**
+ * One edge of the graph, with the reason the builder drew it.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface EdgeSummary {
+  readonly from: string
+  readonly to: string
+  readonly reason: "value" | "continuation" | "failure"
+}
+
+/**
+ * How a node left the walk.
+ *
+ * `built` ran, `clean` was served entirely from durable records, `failed`
+ * raised, and `skipped` is a node the walk never reached — an untaken branch
+ * arm, or a dependent of something that failed.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export type NodeOutcome = "built" | "clean" | "failed" | "skipped"
+
+/**
+ * The graph a run is about to be driven from, or one page of it.
+ *
+ * A large plan is paged rather than truncated: the first page is the plan
+ * record and the rest are appended subgraphs, because a journal entry has a
+ * byte bound and a projection that clips one loses nodes silently. Nothing
+ * about one node has to fit one page — its summary, its dependency list and
+ * the edges that end on it may each run onto the next — so a page's `nodes`
+ * and `edges` are a SLICE of the graph and only the assembled pages are the
+ * whole of it.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface PlanRecorded {
+  readonly _tag: "PlanRecorded"
+  readonly sourceId: string
+  readonly flow: string
+  readonly generation: number
+  readonly page: number
+  readonly pages: number
+  /** Every node of the whole graph, not of this page. */
+  readonly nodeCount: number
+  readonly nodes: ReadonlyArray<NodeSummary>
+  readonly edges: ReadonlyArray<EdgeSummary>
+}
+
+/**
+ * A page of a graph too large for one record.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface SubgraphAppended {
+  readonly _tag: "SubgraphAppended"
+  readonly sourceId: string
+  readonly flow: string
+  readonly generation: number
+  readonly page: number
+  readonly pages: number
+  readonly nodes: ReadonlyArray<NodeSummary>
+  readonly edges: ReadonlyArray<EdgeSummary>
+}
+
+/**
+ * A node the walk is about to compute.
+ *
+ * `attempt` is the walk's, and it is always 1: the interpreter settles each
+ * node once. No step key digest rides here, because none exists yet — the
+ * engine allocates a dispatch's ordinal when the dispatch happens, which is
+ * after this record is written. The digests arrive on {@link NodeSettled}.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface NodeScheduled {
+  readonly _tag: "NodeScheduled"
+  readonly sourceId: string
+  readonly nodeId: string
+  readonly kind: string
+  readonly attempt: number
+  readonly action?: string | undefined
+}
+
+/**
+ * A node that reached an outcome.
+ *
+ * `attempts` is the highest durable attempt any of this node's dispatches ran
+ * as, and 1 for a node that dispatched nothing. It is the engine's count, not
+ * the walk's: the interpreter settles each node once, and a retry happens
+ * underneath it inside one dispatch, so a node whose action failed and was
+ * retried says two.
+ *
+ * `stepKeyDigests` names the dispatches this node drove, in the order they
+ * were first reported and without repeats — a retried dispatch keeps one step
+ * key, because the attempt is folded into no key. It is the join a monitor
+ * could not make before: `flows.engine.attempt-started` carries a step key
+ * digest and no node id, so an attempt row belongs to the node that claims
+ * its digest. A node that dispatches nothing claims none, and a runtime that
+ * derives no digests reports an empty list.
+ *
+ * `value` is what the node settled with — the success value for `built` and
+ * `clean`, the typed failure for `failed` — handed over whole and unbounded.
+ * It is NOT a summary: bounding and redacting it belongs to the writer that
+ * knows where it is going, because a durable row has a byte budget and a
+ * credential redactor and an in-memory monitor has neither.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface NodeSettled {
+  readonly _tag: "NodeSettled"
+  readonly sourceId: string
+  readonly nodeId: string
+  readonly outcome: NodeOutcome
+  readonly attempts: number
+  readonly action?: string | undefined
+  readonly stepKeyDigests: ReadonlyArray<string>
+  readonly value?: unknown
+}
+
+/**
+ * Everything a walk can tell its runtime.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export type NodeRecord = PlanRecorded | SubgraphAppended | NodeScheduled | NodeSettled

package/src/FlowRuntime/WaitingAnnotation.ts

@@ -0,0 +1,85 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * Declares how a flow is about to wait before it suspends.
+ *
+ * @since 0.1.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { FlowInstance } from "./FlowInstance.ts"
+
+/**
+ * The waiting classification a flow can declare before suspending.
+ *
+ * Mirrors the durable store's waiting payload: `reason` is the supervisor
+ * vocabulary (`approval`, `event`, `timer`, `quota`, or a plugin-defined
+ * reason), `wakeAt` an absolute deadline, and `token` compare-and-swap
+ * material a wake handler matches against.
+ *
+ * `request` is what the wait declares ABOUT itself, as JSON text, for a reader
+ * rather than for a matcher: the question a `HumanTask` is parked on, its
+ * kind, and its attempt budget. Nothing routes on it. It exists because `reason` and `token`
+ * say only that a person owes the run an answer and which wait point holds it,
+ * so an approvals inbox reading a parked run could name the gate and never
+ * state the question — which is what left run-3's `coding-clarification`
+ * unanswerable.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface WaitingAnnotation {
+  readonly reason: string
+  readonly wakeAt?: number | undefined
+  readonly token?: string | undefined
+  readonly request?: string | undefined
+}
+
+/**
+ * Schema for {@link WaitingAnnotation}, the one encodable spelling of the
+ * waiting vocabulary. `Flow.Park` carries it so a parking request and the
+ * annotation that precedes a suspension cannot describe different waits.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const WaitingAnnotation = Schema.Struct({
+  reason: Schema.String,
+  wakeAt: Schema.optional(Schema.Number),
+  token: Schema.optional(Schema.String),
+  // JSON TEXT, not a decoded value. `Flow.Park` carries this struct, and a
+  // recursive `Json` schema here pushed `Flow.Outcome`'s inference past
+  // TypeScript's instantiation depth; a string also keeps one spelling of the
+  // question from the declaring flow all the way to the durable column, which
+  // stores exactly this text under a `json_valid` check.
+  request: Schema.optional(Schema.String)
+})
+
+/**
+ * Declares how the flow is about to wait, so a durable driver parks the run
+ * with that reason and token instead of the derived `timer`/`event` default.
+ *
+ * The annotation is scoped to the wait it precedes: once the awaited
+ * deferred passes through with a persisted result — including replays after
+ * the wait resolved — the declared classification is consumed, so a later
+ * suspension parks under its own reason (and keeps its timer `wakeAt`)
+ * instead of the stale one (issue #42).
+ *
+ * Call it immediately before awaiting the deferred that models the wait:
+ *
+ * ```ts
+ * yield* FlowRuntime.annotateWaiting({ reason: "approval", token: requestId })
+ * const decision = yield* DurableDeferred.await(approvalGate)
+ * ```
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export const annotateWaiting = (
+  waiting: WaitingAnnotation | undefined
+): Effect.Effect<void, never, FlowInstance> =>
+  Effect.gen(function*() {
+    const instance = yield* FlowInstance
+    instance.waiting = waiting
+  })

package/src/FlowRuntime/index.ts

@@ -0,0 +1,17 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * The runtime port: the execution contract flow authoring APIs require.
+ *
+ * @since 0.1.0
+ */
+
+export * from "./CancelRequestFailed.ts"
+export * from "./FlowCycleDetected.ts"
+export * from "./FlowExecutionNotFound.ts"
+export * from "./FlowInstance.ts"
+export * from "./FlowRuntime.ts"
+export * from "./NodeRecord.ts"
+export * from "./WaitingAnnotation.ts"
+
+export * from "./ExecutionIdentityConflict.ts"