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

package/src/Flow/Runtime.ts

@@ -0,0 +1,309 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * Runtime helpers for flow completion, suspension, scopes, and rollback.
+ *
+ * @since 0.1.0
+ */
+
+import * as Arr from "effect/Array"
+import * as Cause from "effect/Cause"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import * as Fiber from "effect/Fiber"
+import * as Filter from "effect/Filter"
+import { dual, identity } from "effect/Function"
+import * as Scope from "effect/Scope"
+import { FlowInstance } from "../FlowRuntime/FlowInstance.ts"
+import { CaptureDefects, SuspendOnFailure } from "./Annotations.ts"
+import { Complete, isResult, type Result, Suspended } from "./Result.ts"
+
+/**
+ * Runs an effect as a flow execution and converts its outcome into a
+ * `Result`, handling suspension, defect capture, interruption, and flow
+ * scope finalization.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export const intoResult = <A, E, R>(
+  effect: Effect.Effect<A, E, R>
+): Effect.Effect<
+  Result<A, E>,
+  never,
+  Exclude<R, Scope.Scope> | FlowInstance
+> =>
+  Effect.contextWith((context: Context.Context<FlowInstance>) => {
+    const instance = Context.get(context, FlowInstance)
+    const captureDefects = Context.get(instance.flow.annotations, CaptureDefects)
+    const suspendOnFailure = Context.get(instance.flow.annotations, SuspendOnFailure)
+    return effect.pipe(
+      // so we can use external interruption to suspend the flow
+      Effect.forkChild({ startImmediately: true }),
+      Effect.flatMap((fiber) => Effect.onInterrupt(Fiber.join(fiber), () => Fiber.interrupt(fiber))),
+      Effect.interruptible,
+      suspendOnFailure
+        ? Effect.catchCause((cause) => {
+          instance.suspended = true
+          if (!Cause.hasInterruptsOnly(cause)) {
+            instance.cause = Cause.die(Cause.squash(cause))
+          }
+          return Effect.interrupt
+        })
+        : identity,
+      Effect.scoped,
+      Effect.matchCauseEffect({
+        // A body that handed off produced no answer of its own, so the slot
+        // the handoff was recorded in wins over the value the handler returned
+        // (`docs/concepts/trampoline-rounds.md`).
+        onSuccess: (value) =>
+          Effect.succeed(
+            instance.handoff ?? new Complete({ exit: Exit.succeed(value) })
+          ),
+        onFailure: (cause): Effect.Effect<Result<A, E>> => {
+          const [reasons, interrupts] = Arr.partition(
+            cause.reasons,
+            Filter.fromPredicate(Cause.isInterruptReason)
+          )
+          const hasInterruptsOnly = interrupts.length === cause.reasons.length
+          const filtered = reasons.length === 0 ? cause : Cause.fromReasons(reasons)
+          return instance.suspended && hasInterruptsOnly
+            ? Effect.succeed(new Suspended({ cause: instance.cause }))
+            : (!instance.interrupted && hasInterruptsOnly) ||
+                (!captureDefects && Cause.hasDies(cause))
+            ? Effect.failCause(filtered as Cause.Cause<never>)
+            : Effect.succeed(new Complete({ exit: Exit.failCause(filtered) }))
+        }
+      }),
+      (eff) =>
+        Effect.onExitPrimitive(eff, (exit) => {
+          if (Exit.isFailure(exit)) {
+            return Scope.close(instance.scope, exit)
+          } else if (exit.value._tag === "Complete") {
+            return Scope.close(instance.scope, exit.value.exit)
+          } else if (exit.value._tag === "Handoff") {
+            // A handoff ends this round for good — the next round is a separate
+            // execution with its own instance and its own scope — so the round's
+            // scope closes here exactly as a completion closes it. A suspension
+            // is the only settlement that keeps the scope open.
+            return Scope.close(instance.scope, Exit.void)
+          }
+          return Effect.void
+        }, true),
+      Effect.uninterruptible
+    )
+  })
+
+/**
+ * The action regions open on the current fiber's dynamic call stack.
+ *
+ * `actionState.count` says how many regions are open on an instance; it does
+ * not say which of them the current region is nested inside. That difference is
+ * the whole of {@link wrapActionResult}'s liveness: a region that suspends
+ * waits for the *other* open regions to settle, and an enclosing region can
+ * never settle before the region inside it returns. Carrying the enclosing
+ * instances in the context is what lets a suspension tell a sibling — which
+ * will settle — from an ancestor, which is waiting on the very fiber that is
+ * waiting on it.
+ *
+ * It is a context reference rather than a fiber-local counter because the chain
+ * crosses fibers: {@link intoResult} forks the body, and an engine gives every
+ * action dispatch a fiber of its own. Context propagates to forked children;
+ * a per-fiber counter would restart at each fork and read every ancestor as a
+ * sibling again.
+ */
+const EnclosingActions = Context.Reference<ReadonlyArray<FlowInstance["Service"]>>(
+  "@smthrs/flow/Flow/EnclosingActions",
+  { defaultValue: () => [] }
+)
+
+/**
+ * Wraps an action-like effect so flow suspension waits for currently
+ * running actions to finish or suspend.
+ *
+ * The wait is for *siblings*. An action that suspends holds work its siblings
+ * have not journaled yet, so the flow must not park out from under them; an
+ * enclosing region holds no such work, because everything it is doing is this
+ * region. Waiting for one is a deadlock, and it was a real one: a harness cell
+ * call is an action, the `wait` flow it dispatches awaits a `DurableClock`
+ * under the run's own instance, and the round that should have parked instead
+ * blocked forever inside an uninterruptible finalizer — not cancellable, not
+ * resumable, and invisible in the journal past the `clock-scheduled` record.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export const wrapActionResult = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  isSuspend: (value: A) => boolean
+): Effect.Effect<A, E, R | FlowInstance> =>
+  Effect.contextWith((context: Context.Context<FlowInstance>) => {
+    const instance = Context.get(context, FlowInstance)
+    const enclosing = Context.getUnsafe(context, EnclosingActions)
+    // How many of the regions counted on this instance are this one's own
+    // ancestors, and so how many of them will still be open once every sibling
+    // has settled.
+    let ancestors = 0
+    for (const open of enclosing) if (open === instance) ancestors++
+    const state = instance.actionState
+    if (state.count === 0) state.latch.closeUnsafe()
+    state.count++
+    return Effect.onExit(
+      Effect.provideService(effect, EnclosingActions, [...enclosing, instance]),
+      (exit) => {
+        state.count--
+        const isSuspended = Exit.isSuccess(exit) && isSuspend(exit.value)
+        if (
+          Exit.isSuccess(exit) &&
+          isResult(exit.value) &&
+          exit.value._tag === "Suspended" &&
+          exit.value.cause
+        ) {
+          instance.cause = instance.cause
+            ? Cause.combine(instance.cause, exit.value.cause)
+            : exit.value.cause
+        }
+        if (state.count === 0) return state.latch.open
+        // Every decrement can satisfy a waiter whose threshold is not zero, so
+        // the waiters are released to re-test their own. `release` wakes them
+        // without opening the latch, so the ones still short of their threshold
+        // park again on the next turn of the loop.
+        return isSuspended
+          ? Effect.andThen(state.latch.release, waitForSiblings(instance, ancestors))
+          : Effect.asVoid(state.latch.release)
+      }
+    )
+  })
+
+// Untraced because this latch loop is a flow scheduler hot path.
+const waitForSiblings = Effect.fnUntraced(function*(
+  instance: FlowInstance["Service"],
+  ancestors: number
+) {
+  const state = instance.actionState
+  while (true) {
+    if (state.count > ancestors) {
+      yield* state.latch.await
+      yield* Effect.yieldNow
+      continue
+    }
+    yield* Effect.yieldNow
+    if (state.count <= ancestors) return
+  }
+})
+
+/**
+ * Accesses the current round's flow scope. Suspension keeps it open;
+ * completion or handoff closes it.
+ *
+ * @category resource management
+ * @since 0.1.0
+ */
+export const scope: Effect.Effect<
+  Scope.Scope,
+  never,
+  FlowInstance
+> = Effect.map(
+  FlowInstance,
+  (instance) => instance.scope as Scope.Scope
+)
+
+/**
+ * Provides the current round's flow scope to the given effect. Suspension keeps
+ * the scope open; completion or handoff closes it.
+ *
+ * @category resource management
+ * @since 0.1.0
+ */
+export const provideScope = <A, E, R>(
+  effect: Effect.Effect<A, E, R>
+): Effect.Effect<A, E, Exclude<R, Scope.Scope> | FlowInstance> =>
+  Effect.flatMap(scope, (scope) => Scope.provide(effect, scope))
+
+/**
+ * Adds an exit finalizer to the current flow scope, preserving the
+ * services available when the finalizer is registered.
+ *
+ * @category resource management
+ * @since 0.1.0
+ */
+export const addFinalizer: <R>(
+  f: (exit: Exit.Exit<unknown, unknown>) => Effect.Effect<void, never, R>
+) => Effect.Effect<
+  void,
+  never,
+  FlowInstance | R
+> =
+  // Untraced because suspension recursively re-enters flow execution.
+  Effect.fnUntraced(function*<R>(
+    f: (exit: Exit.Exit<unknown, unknown>) => Effect.Effect<void, never, R>
+  ) {
+    const instance = yield* FlowInstance
+    const services = yield* Effect.context<R>()
+    yield* Scope.addFinalizerExit(instance.scope, (exit) => Effect.provideContext(f(exit), services))
+  })
+
+/**
+ * Runs an effect and registers how to undo its successful result if the
+ * current round later exits unsuccessfully.
+ *
+ * **When to use**
+ *
+ * Use when a top-level flow operation changes something that must be undone if
+ * a later operation causes the same round to fail or be interrupted.
+ *
+ * **Details**
+ *
+ * The effect runs first. If it fails, no rollback is registered. If it
+ * succeeds, its value is captured in a round-scope finalizer. The finalizer does
+ * nothing when the round succeeds; when the round exits unsuccessfully
+ * it calls `rollback(value, cause)`. Suspension keeps that scope open.
+ *
+ * A handoff completes the round successfully and discards its `withRollback` registrations.
+ * A later round's failure cannot invoke those rollbacks. The engine does not
+ * provide lineage-scoped compensation.
+ *
+ * **Gotchas**
+ *
+ * This applies only to effects run directly inside the flow execution. It does
+ * not attach rollback behavior to nested actions. The rollback's typed error
+ * channel is `never`; handle expected rollback failures inside the callback.
+ *
+ * @category resource management
+ * @since 0.1.0
+ */
+export const withRollback: {
+  <A, R2>(
+    rollback: (value: A, cause: Cause.Cause<unknown>) => Effect.Effect<void, never, R2>
+  ): <E, R>(
+    effect: Effect.Effect<A, E, R>
+  ) => Effect.Effect<A, E, R | R2 | FlowInstance | Scope.Scope>
+  <A, E, R, R2>(
+    effect: Effect.Effect<A, E, R>,
+    rollback: (value: A, cause: Cause.Cause<unknown>) => Effect.Effect<void, never, R2>
+  ): Effect.Effect<A, E, R | R2 | FlowInstance | Scope.Scope>
+} = dual(2, <A, E, R, R2>(
+  effect: Effect.Effect<A, E, R>,
+  rollback: (value: A, cause: Cause.Cause<unknown>) => Effect.Effect<void, never, R2>
+): Effect.Effect<A, E, R | R2 | FlowInstance | Scope.Scope> =>
+  Effect.uninterruptibleMask((restore) =>
+    Effect.tap(
+      restore(effect),
+      (value) => addFinalizer((exit) => Exit.isSuccess(exit) ? Effect.void : rollback(value, exit.cause))
+    )
+  ))
+
+/**
+ * Marks a flow instance as suspended and interrupts the current fiber to
+ * stop execution until it is resumed.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export const suspend = (instance: FlowInstance["Service"]): Effect.Effect<never> =>
+  Effect.interruptible(Effect.callback<never>(() => {
+    instance.suspended = true
+    const fiber = Fiber.getCurrent()!
+    fiber.interruptUnsafe(fiber.id)
+  }))

package/src/Flow/TypeId.ts

@@ -0,0 +1,9 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * Runtime identity shared by flow interfaces and constructors.
+ *
+ * @private
+ * @since 0.1.0
+ */
+export const TypeId = "@smthrs/flow/Flow"

package/src/Flow/index.ts

@@ -0,0 +1,19 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * Typed durable flow definitions, results, and runtime helpers.
+ *
+ * @since 0.1.0
+ */
+
+export * from "./Annotations.ts"
+export * from "./CapabilityCeiling.ts"
+export * from "./DeadlineExceeded.ts"
+export * from "./ExecutionIdRequired.ts"
+export * from "./ExecutionIds.ts"
+export * from "./Flow.ts"
+export * from "./make.ts"
+export * from "./MaxRoundsExceeded.ts"
+export * from "./Outcome.ts"
+export * from "./Result.ts"
+export * from "./Runtime.ts"

package/src/Flow/internal.ts

@@ -0,0 +1,237 @@
+/**
+ * Private flow construction shared by declarations and action registration.
+ *
+ * @since 1.0.0
+ * @private
+ */
+
+import { Sha256 } from "@smthrs/crypto"
+import * as Node from "@smthrs/plan/Node"
+import * as Cause from "effect/Cause"
+import * as Context from "effect/Context"
+import * as Crypto from "effect/Crypto"
+import type * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { ExecutionIdentityConflict } from "../FlowRuntime/ExecutionIdentityConflict.ts"
+import { FlowRuntime } from "../FlowRuntime/FlowRuntime.ts"
+import * as DeclarationSite from "../internal/DeclarationSite.ts"
+import type * as RetryPolicy from "../RetryPolicy.ts"
+import { CurrentExecutionIds } from "./ExecutionIds.ts"
+import type { Any, AnyStructSchema, AnyWithProps, BodySuccess, DeclarationMetadata, Flow } from "./Flow.ts"
+import type { To } from "./Outcome.ts"
+import { withRollback } from "./Runtime.ts"
+import { TypeId } from "./TypeId.ts"
+
+/**
+ * The identity of an invocation that named no `executionId`: the flow's own
+ * declared key when it has one, and the ambient source otherwise.
+ *
+ * A declared key wins over the ambient source because it is the narrower
+ * statement — this author said what makes two invocations of THIS flow the
+ * same — where the source is the host's blanket answer for every flow it
+ * drives.
+ *
+ * The tag and declared key are JSON-tuple framed before hashing. Their strings
+ * are used exactly as given and encoded as UTF-8, with no Unicode
+ * normalization. This preimage encoding freezes at rc.0.
+ */
+const makeExecutionIdFromPayload = (
+  self: AnyWithProps,
+  payload: unknown
+): Effect.Effect<string, never, any> => {
+  const idempotencyKey = self.idempotencyKey
+  return idempotencyKey === undefined
+    ? Effect.flatMap(CurrentExecutionIds, (source) => source.mint(self, payload))
+    // The JSON tuple prevents delimiter splicing. This exact framing freezes at rc.0.
+    : Schema.decodeUnknownEffect(Sha256)(JSON.stringify([self._tag, idempotencyKey(payload)])).pipe(Effect.orDie)
+}
+
+const resolveExecutionId = (
+  self: AnyWithProps,
+  payload: unknown,
+  executionId: string | undefined
+): Effect.Effect<string, never, any> =>
+  executionId === undefined
+    ? makeExecutionIdFromPayload(self, payload)
+    : Effect.succeed(executionId)
+
+const Proto = {
+  [TypeId]: TypeId,
+  annotate(this: AnyWithProps, tag: Context.Key<any, any>, value: any) {
+    return DeclarationSite.annotate(
+      makeProto({
+        _tag: this._tag,
+        description: this.description,
+        model: this.model,
+        effort: this.effort,
+        system: this.system,
+        chat: this.chat,
+        flows: this.flows,
+        prompt: this.prompt,
+        action: this.action,
+        payloadSchema: this.payloadSchema,
+        successSchema: this.successSchema,
+        errorSchema: this.errorSchema,
+        annotations: Context.add(this.annotations, tag, value),
+        body: this.body,
+        idempotencyKey: this.idempotencyKey,
+        suspendedRetryPolicy: this.suspendedRetryPolicy,
+        maxRounds: this.maxRounds,
+        deadline: this.deadline
+      }),
+      DeclarationSite.declaredAt(this)
+    )
+  },
+  annotateMerge(this: AnyWithProps, context: Context.Context<any>) {
+    return DeclarationSite.annotate(
+      makeProto({
+        _tag: this._tag,
+        description: this.description,
+        model: this.model,
+        effort: this.effort,
+        system: this.system,
+        chat: this.chat,
+        flows: this.flows,
+        prompt: this.prompt,
+        action: this.action,
+        payloadSchema: this.payloadSchema,
+        successSchema: this.successSchema,
+        errorSchema: this.errorSchema,
+        annotations: Context.merge(this.annotations, context),
+        body: this.body,
+        idempotencyKey: this.idempotencyKey,
+        suspendedRetryPolicy: this.suspendedRetryPolicy,
+        maxRounds: this.maxRounds,
+        deadline: this.deadline
+      }),
+      DeclarationSite.declaredAt(this)
+    )
+  },
+  call(this: AnyWithProps, payload: unknown) {
+    return Node.flowCall(this, this._tag, "inline", payload)
+  },
+  child(this: AnyWithProps, payload: unknown) {
+    return Node.flowCall(this, this._tag, "boundary", payload)
+  },
+  to(this: AnyWithProps, payload: unknown): Node.Node<To<unknown>> {
+    return Node.flowCall(this, this._tag, "handoff", payload)
+  },
+  execute<const Discard extends boolean = false>(
+    this: AnyWithProps,
+    fields: any,
+    opts?: {
+      readonly discard?: Discard
+      readonly executionId?: string | undefined
+    } | undefined
+  ) {
+    // Caller input that fails the payload schema is data, not programmer
+    // wiring, so it FAILS with the schema's typed `SchemaError` — carrying
+    // the offending field path — instead of dying with the raw constructor
+    // throw `payloadSchema.make` would produce.
+    return this.payloadSchema.makeEffect(fields).pipe(
+      Effect.mapError((issue) => new Schema.SchemaError(issue)),
+      Effect.flatMap((payload) =>
+        Effect.flatMap(
+          resolveExecutionId(this, payload, opts?.executionId),
+          (executionId) =>
+            Effect.flatMap(FlowRuntime, (engine) =>
+              Effect.andThen(
+                Effect.annotateCurrentSpan({ executionId }),
+                engine.execute(this as any, {
+                  executionId,
+                  payload,
+                  discard: opts?.discard,
+                  suspendedRetryPolicy: this.suspendedRetryPolicy
+                }).pipe(Effect.catchCause((cause) => {
+                  const reason = cause.reasons.length === 1 ? cause.reasons.find(Cause.isDieReason) : undefined
+                  return reason?.defect instanceof ExecutionIdentityConflict
+                    ? Effect.fail(reason.defect)
+                    : Effect.failCause(cause)
+                }))
+              ))
+        )
+      )
+    ).pipe(
+      Effect.withSpan(
+        `${this._tag}.execute`,
+        {},
+        { captureStackTrace: false }
+      )
+    ) as any
+  },
+  start(this: AnyWithProps, payload: unknown) {
+    return Effect.flatMap(
+      Crypto.Crypto,
+      (crypto) =>
+        Effect.flatMap(
+          Effect.orDie(crypto.randomUUIDv4),
+          (executionId) => this.execute(payload, { executionId, discard: true })
+        )
+    )
+  },
+  ensure(this: AnyWithProps, payload: unknown, options: { readonly key: string }) {
+    return Schema.decodeUnknownEffect(Schema.String)(options.key).pipe(
+      Effect.flatMap((key) => Effect.orDie(Schema.decodeUnknownEffect(Sha256)(JSON.stringify([this._tag, key])))),
+      Effect.flatMap((executionId) => this.execute(payload, { executionId, discard: true }))
+    )
+  },
+  poll(this: Flow<string, AnyStructSchema, Schema.Top, Schema.Top, any>, executionId: string) {
+    return Effect.flatMap(FlowRuntime, (engine) => engine.poll(this, executionId)).pipe(
+      Effect.withSpan(`${this._tag}.poll`, { attributes: { executionId } }, { captureStackTrace: false })
+    )
+  },
+  interrupt(this: AnyWithProps, executionId: string) {
+    return Effect.flatMap(FlowRuntime, (engine) => engine.interrupt(this, executionId)).pipe(
+      Effect.withSpan(`${this._tag}.interrupt`, { attributes: { executionId } }, { captureStackTrace: false })
+    )
+  },
+  resume(this: Flow<string, AnyStructSchema, Schema.Top, Schema.Top, any>, executionId: string) {
+    return Effect.flatMap(FlowRuntime, (engine) => engine.resume(this, executionId)).pipe(
+      Effect.withSpan(`${this._tag}.resume`, { attributes: { executionId } }, { captureStackTrace: false })
+    )
+  },
+  executionId(this: AnyWithProps, payload: any) {
+    return Effect.flatMap(
+      // The channel stays never: precomputing callers must validate first, and an invalid payload dies here.
+      Effect.orDie(this.payloadSchema.makeEffect(payload)),
+      (payload) => makeExecutionIdFromPayload(this, payload)
+    )
+  },
+  withRollback: ((...args: ReadonlyArray<any>) => (withRollback as any)(...args))
+}
+
+/**
+ * Builds the private prototype from normalized declaration data.
+ *
+ * @since 1.0.0
+ * @private
+ */
+export const makeProto = <
+  const Tag extends string,
+  Payload extends AnyStructSchema,
+  Success extends Schema.Top,
+  Error extends Schema.Top,
+  Requires
+>(
+  options: DeclarationMetadata & {
+    readonly _tag: Tag
+    readonly description?: string | undefined
+    readonly payloadSchema: Payload
+    readonly successSchema: Success
+    readonly errorSchema: Error
+    readonly annotations: Context.Context<never>
+    readonly body: (payload: Payload["Type"]) => Node.Node<BodySuccess<Success["Type"]>, Error["Type"], Requires>
+    readonly prompt?: ((payload: Payload["Type"]) => string) | undefined
+    readonly action?: Any["action"] | undefined
+    readonly idempotencyKey?: ((payload: Payload["Type"]) => string) | undefined
+    readonly suspendedRetryPolicy?: RetryPolicy.RetryPolicy | undefined
+    readonly maxRounds?: number | undefined
+    readonly deadline?: Duration.Duration | undefined
+  }
+): Flow<Tag, Payload, Success, Error, Requires> => {
+  function Flow() {}
+  Object.setPrototypeOf(Flow, Proto)
+  Object.assign(Flow, options)
+  return Flow as any
+}