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

package/src/Action/raceAll.ts

@@ -0,0 +1,48 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * Races actions through durable deferred execution.
+ *
+ * @since 0.1.0
+ */
+
+import type { NonEmptyReadonlyArray } from "effect/Array"
+import type * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import * as DurableDeferred from "../DurableDeferred.ts"
+import type { FlowInstance, FlowRuntime } from "../FlowRuntime/index.ts"
+import type { Action, Any } from "./Action.ts"
+
+/**
+ * Runs a non-empty collection of actions as a durable race and returns the
+ * first success using unioned success and error schemas. A losing failure is
+ * ignored while another action is still running; the race fails only when
+ * every action fails. To settle on whichever action exits first, success or
+ * failure, race `Effect.exit` of each action and unwrap the winning exit.
+ *
+ * @category racing
+ * @since 0.1.0
+ */
+export const raceAll = <const Actions extends NonEmptyReadonlyArray<Any>>(
+  name: string,
+  actions: Actions
+): Effect.Effect<
+  Actions[number] extends Action<infer _A, infer _E, infer _R> ? _A["Type"] : never,
+  Actions[number] extends Action<infer _A, infer _E, infer _R> ? _E["Type"] : never,
+  | Effect.Services<Actions[number]>
+  | (Actions[number] extends Action<infer Success, infer Error, infer _R>
+    ? Success["DecodingServices"] | Success["EncodingServices"] | Error["DecodingServices"] | Error["EncodingServices"]
+    : never)
+  | FlowRuntime
+  | FlowInstance
+> =>
+  DurableDeferred.raceAll({
+    name: `Action/${name}`,
+    success: Schema.Union(
+      actions.map((action) => (action as any).successSchema)
+    ),
+    error: Schema.Union(
+      actions.map((action) => (action as any).errorSchema)
+    ),
+    effects: actions.map((action) => (action as any)) as any
+  }) as any

package/src/Action/retry.ts

@@ -0,0 +1,92 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * Retries effects while preserving durable action identity.
+ *
+ * @since 0.1.0
+ */
+
+import * as Effect from "effect/Effect"
+import { dual } from "effect/Function"
+import type * as Types from "effect/Types"
+import { CurrentAttempt, CurrentOrdinal, type OrdinalSlot } from "./Context.ts"
+
+/**
+ * Retries an effect with `Effect.retry` while updating `CurrentAttempt` for
+ * each attempt.
+ *
+ * @category error handling
+ * @since 0.1.0
+ */
+export const retry: {
+  <E, O extends Types.NoExcessProperties<Omit<Effect.Retry.Options<E>, "schedule">, O>>(
+    options: O
+  ): <A, R>(self: Effect.Effect<A, E, R>) => Effect.Retry.Return<R, E, A, O>
+  <A, E, R, O extends Types.NoExcessProperties<Omit<Effect.Retry.Options<E>, "schedule">, O>>(
+    self: Effect.Effect<A, E, R>,
+    options: O
+  ): Effect.Retry.Return<R, E, A, O>
+} = dual(
+  2,
+  (effect: Effect.Effect<any, any, any>, options: object) =>
+    Effect.gen(function*() {
+      // A nested retry block shares the enclosing block's slot instead of
+      // shadowing it with a fresh one (issue #108): a per-invocation slot was
+      // rebuilt on every outer attempt, discarding the pinned `values`, so a
+      // completed irreversible inner dispatch drew a brand-new ordinal — a
+      // new step key — and re-executed instead of replaying. Sharing the
+      // outermost slot keeps every pin alive for the whole outer sequence.
+      const enclosing = yield* CurrentOrdinal
+      // One `values` map for the whole retry sequence: the engine fills each
+      // action's scope with the ordinal it allocates on the first attempt,
+      // and every later attempt of the same sequence reuses those ordinals
+      // (issues #73, #84). The `cursors` map, however, is *per block*
+      // (issue #116): #108 shared the enclosing block's mutable cursor map
+      // wholesale, so a sibling block's attempt boundary — sanctioned to run
+      // concurrently under keyed overlap (issue #111) — cleared every
+      // scope's cursor and rewound another block's mid-flight dispatch onto
+      // an already-consumed pinned ordinal, a duplicate step key. Each block
+      // now owns a private cursor view seeded from the enclosing block's
+      // cursors at entry, so its attempt boundaries reset only its own view.
+      const slot: OrdinalSlot = {
+        values: enclosing?.values ?? new Map(),
+        cursors: new Map(enclosing?.cursors)
+      }
+      // Where each scope's dispatch cursor stood when this block was entered.
+      // An inner attempt replays the block from its own first dispatch, not
+      // from the outer attempt's start, so its cursors rewind to the block
+      // entry rather than to zero (issues #100, #108). At the top level the
+      // snapshot is empty and rewinding degenerates to a plain reset.
+      const entryCursors = new Map(slot.cursors)
+      let attempt = 1
+      return yield* Effect.suspend(() => {
+        // Every attempt replays the block from its first dispatch, so the
+        // per-scope dispatch cursors restart with it (issue #100); the pinned
+        // ordinal sequences in `values` persist across attempts.
+        slot.cursors.clear()
+        for (const [scope, cursor] of entryCursors) {
+          slot.cursors.set(scope, cursor)
+        }
+        return effect.pipe(
+          Effect.provideService(CurrentAttempt, attempt++),
+          Effect.provideService(CurrentOrdinal, slot)
+        )
+      }).pipe(
+        Effect.retry(options),
+        // On exit, fold this block's final cursor positions back into the
+        // enclosing block's view (max-merge, so a concurrent sibling's later
+        // propagation never rewinds a scope): an enclosing dispatch of a
+        // scope this block consumed must take the next pinned position, not
+        // re-consume this block's ordinals.
+        Effect.onExit(() =>
+          Effect.sync(() => {
+            if (enclosing === undefined) return
+            for (const [scope, cursor] of slot.cursors) {
+              const current = enclosing.cursors.get(scope) ?? 0
+              if (cursor > current) enclosing.cursors.set(scope, cursor)
+            }
+          })
+        )
+      )
+    })
+)

package/src/Deadline.ts

@@ -0,0 +1,201 @@
+/**
+ * The wall-clock bound one run of a flow settles by.
+ *
+ * A deadline counts from the run's FIRST start, which is journaled, so it
+ * survives park, resume and process death: a restarted engine honors the
+ * original deadline instead of starting a new one. A trampoline lineage is one
+ * run, so its rounds share one deadline: the round that hands off stamps the
+ * lineage's start and bound on the {@link module:Result.Handoff}, and the next
+ * round runs under that stamp rather than starting a clock of its own. Like
+ * `maxRounds`, the bound belongs to the lineage originator; a handoff target
+ * cannot reset or replace it.
+ *
+ * The engine applies {@link bound} to every execution of a flow that declares
+ * `Flow.make(tag, { deadline })`. A control plane applies it inside a run body
+ * to bound a run by an approved envelope's deadline. Both settle an expired
+ * run with the same {@link module:DeadlineExceeded.DeadlineExceeded} defect.
+ *
+ * @since 1.0.0
+ */
+
+import * as Clock from "effect/Clock"
+import type * as Crypto from "effect/Crypto"
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import * as Schema from "effect/Schema"
+import * as Action from "./Action/index.ts"
+import * as DurableClock from "./DurableClock.ts"
+import { DeadlineExceeded } from "./Flow/DeadlineExceeded.ts"
+import { Handoff, type LineageDeadline } from "./Flow/Result.ts"
+import { FlowInstance } from "./FlowRuntime/FlowInstance.ts"
+import { FlowRuntime } from "./FlowRuntime/FlowRuntime.ts"
+
+/**
+ * The execution's first start, journaled once.
+ *
+ * A sealed action's result is recorded with its attempt and replayed on every
+ * later drive, so the origin a deadline counts from is the time the execution
+ * first ran, on this engine or on the one that resumes it after a restart.
+ */
+const origin = Action.make({
+  name: "@smthrs/engine/deadline-origin",
+  tier: "sealed",
+  success: Schema.Number,
+  execute: Clock.currentTimeMillis.pipe(Effect.map(Math.floor))
+})
+
+/**
+ * Starts the current execution's deadline: the lineage deadline this round
+ * inherited from a handoff, or `deadline` counted from the execution's
+ * journaled first start, or from `startedAtMs` when the host supplies a
+ * durable start of its own. Answers `undefined` when neither applies, which is
+ * an unbounded execution.
+ *
+ * **Details**
+ *
+ * The first start is a sealed action, so every later drive of the execution,
+ * on this engine or one that resumes it after a restart, reads the same
+ * origin. A durable clock is armed at the deadline so a parked execution is
+ * driven again when it passes; the clock keeps the due time it was first armed
+ * with, so arming it on every drive is idempotent.
+ *
+ * **Gotchas**
+ *
+ * Start at most one deadline per execution, before any other dispatch that a
+ * replay must line up with: the origin and the clock are addressed by fixed
+ * names within the execution.
+ *
+ * A deadline that is not a positive finite duration, a `startedAtMs` that is
+ * not finite, or a bound that would expire after epoch millisecond
+ * `Number.MAX_SAFE_INTEGER` dies with a `RangeError`: a durable store records
+ * the clock's due time as a safe integer.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const start = (options: {
+  /** The flow the refusal names. */
+  readonly flowName: string
+  /** The bound; a positive finite duration. Absent means unbounded. */
+  readonly deadline?: Duration.Input | undefined
+  /**
+   * Where the bound counts from, when the host already holds a durable
+   * start of its own, such as the time a control plane accepted the run.
+   * Absent, the execution's first start is journaled and read back.
+   */
+  readonly startedAtMs?: number | undefined
+}): Effect.Effect<LineageDeadline | undefined, never, FlowRuntime | FlowInstance | Crypto.Crypto> =>
+  Effect.gen(function*() {
+    const instance = yield* FlowInstance
+    let lineage = instance.lineageDeadline
+    if (lineage === undefined) {
+      if (options.deadline === undefined) return undefined
+      const deadlineMs = Option.match(Duration.fromInput(options.deadline), {
+        onNone: () => Number.NaN,
+        onSome: Duration.toMillis
+      })
+      if (!Number.isFinite(deadlineMs) || deadlineMs <= 0) {
+        return yield* Effect.die(
+          new RangeError(`Deadline.start: "${options.flowName}" deadline must be a positive finite duration`)
+        )
+      }
+      const startedAtMs = options.startedAtMs ?? (yield* origin)
+      // The clock armed below is due at `startedAtMs + deadlineMs`, and a
+      // durable store records a due time as a safe integer.
+      if (!Number.isFinite(startedAtMs) || startedAtMs + deadlineMs > Number.MAX_SAFE_INTEGER) {
+        return yield* Effect.die(
+          new RangeError(
+            `Deadline.start: "${options.flowName}" deadline must expire by epoch millisecond ` +
+              `${Number.MAX_SAFE_INTEGER}, and a ${deadlineMs} ms deadline from ${startedAtMs} does not`
+          )
+        )
+      }
+      lineage = { startedAtMs, deadlineMs }
+    }
+    const remaining = yield* remainingMs(lineage)
+    if (remaining > 0) {
+      yield* (yield* FlowRuntime).scheduleClock(instance.flow, {
+        executionId: instance.executionId,
+        clock: DurableClock.make({ name: "@smthrs/engine/deadline", duration: remaining })
+      })
+    }
+    return lineage
+  })
+
+/**
+ * The whole milliseconds left before `deadline` passes, as the durable clock
+ * row stores its due time; zero or less once it has passed.
+ *
+ * @category getters
+ * @since 1.0.0
+ */
+export const remainingMs = (deadline: LineageDeadline): Effect.Effect<number> =>
+  Effect.map(Clock.currentTimeMillis, (now) => Math.ceil(deadline.startedAtMs + deadline.deadlineMs - now))
+
+/**
+ * Runs `body` within a started deadline.
+ *
+ * A body that starts at or past the deadline settles at once, and one that
+ * starts before it races the time remaining in this fiber, so a running
+ * execution is stopped too. Both settle with the same `DeadlineExceeded`
+ * defect. The race is `raceFirst`: a body that parks exits first, so parking
+ * still parks. A round that hands off stamps the deadline on its handoff, so
+ * the next round of the lineage runs under it. An `undefined` deadline runs
+ * `body` unbounded.
+ *
+ * @category combinators
+ * @since 1.0.0
+ */
+export const within =
+  (deadline: LineageDeadline | undefined, flowName: string) =>
+  <A, E, R>(body: Effect.Effect<A, E, R>): Effect.Effect<A, E, R | FlowInstance> =>
+    deadline === undefined ? body : Effect.gen(function*() {
+      const instance = yield* FlowInstance
+      const expired = new DeadlineExceeded({
+        flowName,
+        executionId: instance.executionId,
+        deadlineMs: deadline.deadlineMs,
+        startedAtMs: deadline.startedAtMs,
+        message: `${flowName} execution ${instance.executionId} ran past its ${deadline.deadlineMs} ms deadline, ` +
+          `counted from its start at ${new Date(deadline.startedAtMs).toISOString()}`
+      })
+      const remaining = yield* remainingMs(deadline)
+      if (remaining <= 0) return yield* Effect.die(expired)
+      const value = yield* Effect.raceFirst(body, Effect.andThen(Effect.sleep(remaining), Effect.die(expired)))
+      const handoff = instance.handoff
+      if (handoff !== undefined && handoff.deadline === undefined) {
+        instance.handoff = new Handoff({
+          flow: handoff.flow,
+          payload: handoff.payload,
+          ...(handoff.capabilityCeilings === undefined ? {} : { capabilityCeilings: handoff.capabilityCeilings }),
+          deadline
+        })
+      }
+      return value
+    })
+
+/**
+ * Bounds the current execution by `deadline`, counted from its journaled first
+ * start, or by the lineage deadline this round inherited from a handoff:
+ * {@link start}, then {@link within}.
+ *
+ * A round that inherited a lineage deadline runs under it whatever it
+ * declares, so every round of a lineage expires at the originator's time. With
+ * no inherited deadline and `deadline` absent, the body runs unbounded.
+ *
+ * @category combinators
+ * @since 1.0.0
+ */
+export const bound = (options: {
+  /** The flow the refusal names. */
+  readonly flowName: string
+  /** The bound; a positive finite duration. Absent means unbounded. */
+  readonly deadline?: Duration.Input | undefined
+  /** Where the bound counts from; see {@link start}. */
+  readonly startedAtMs?: number | undefined
+}) =>
+<A, E, R>(
+  body: Effect.Effect<A, E, R>
+): Effect.Effect<A, E, R | FlowRuntime | FlowInstance | Crypto.Crypto> =>
+  Effect.flatMap(start(options), (deadline) => within(deadline, options.flowName)(body))

package/src/DurableClock.ts

@@ -0,0 +1,176 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * Durable timers for flow sleeps.
+ *
+ * `make` creates a `DurableClock` with a name, duration, and deferred wake-up
+ * signal. `sleep` ignores zero durations, runs short sleeps through an
+ * in-memory action, and schedules longer sleeps through the `FlowRuntime`
+ * before awaiting the durable deferred tied to the clock.
+ *
+ * @since 0.1.0
+ */
+
+import * as Clock from "effect/Clock"
+import type * as Crypto from "effect/Crypto"
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import type * as Schema from "effect/Schema"
+import * as Action from "./Action/index.ts"
+import * as DurableDeferred from "./DurableDeferred.ts"
+import { FlowInstance } from "./FlowRuntime/FlowInstance.ts"
+import { FlowRuntime } from "./FlowRuntime/FlowRuntime.ts"
+
+const TypeId = "@smthrs/flow/DurableClock"
+
+/**
+ * Represents a durable flow timer with a name, duration, and deferred
+ * completed when the timer wakes.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface DurableClock {
+  readonly [TypeId]: typeof TypeId
+  readonly name: string
+  readonly duration: Duration.Duration
+  readonly deferred: DurableDeferred.DurableDeferred<typeof Schema.Void>
+}
+
+/**
+ * Parses one author-supplied duration and requires it to be finite and
+ * nonnegative. Invalid input throws `RangeError` so the authoring mistake is
+ * caught at declaration time, matching `Flow.make` and `Poll.make`.
+ *
+ * @private
+ */
+const durationFromInput = (input: Duration.Input, field: string): Duration.Duration => {
+  const parsed = Duration.fromInput(input)
+  if (Option.isNone(parsed)) {
+    throw new RangeError(`DurableClock: "${field}" must be a valid finite duration that is not negative.`)
+  }
+  const millis = Duration.toMillis(parsed.value)
+  if (!Duration.isFinite(parsed.value) || !Number.isFinite(millis) || millis < 0) {
+    throw new RangeError(`DurableClock: "${field}" must be a valid finite duration that is not negative.`)
+  }
+  return parsed.value
+}
+
+/**
+ * The latest due time a durable timer records, in epoch milliseconds: a store
+ * keeps a clock's due time as a safe integer.
+ *
+ * @private
+ */
+const latestDueAtMs = Number.MAX_SAFE_INTEGER
+
+/**
+ * Parses a clock's own duration, which a store adds to the current time and
+ * records, so it is at most {@link latestDueAtMs} milliseconds.
+ *
+ * @private
+ */
+const clockDuration = (input: Duration.Input): Duration.Duration => {
+  const duration = durationFromInput(input, "duration")
+  if (Duration.toMillis(duration) > latestDueAtMs) {
+    throw new RangeError(`DurableClock: "duration" must be at most ${latestDueAtMs} milliseconds.`)
+  }
+  return duration
+}
+
+const makeClock = (name: string, duration: Duration.Duration): DurableClock => ({
+  [TypeId]: TypeId,
+  name,
+  duration,
+  deferred: DurableDeferred.make(`DurableClock/${name}`)
+})
+
+/**
+ * Declares one durable clock after validating its finite nonnegative duration.
+ *
+ * Throws a `RangeError` for a malformed, infinite or negative duration, or one
+ * longer than `Number.MAX_SAFE_INTEGER` milliseconds: a durable store records
+ * a clock's due time as a safe integer.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (options: {
+  readonly name: string
+  readonly duration: Duration.Input
+}): DurableClock => makeClock(options.name, clockDuration(options.duration))
+
+/**
+ * Waits inside a flow, using an in-memory action for durations at or
+ * below the threshold and scheduling a durable clock for longer durations.
+ *
+ * Throws a `RangeError` for the same durations {@link make} refuses, and for
+ * a malformed, infinite or negative threshold. A durable sleep that would
+ * wake after epoch millisecond `Number.MAX_SAFE_INTEGER` dies with a
+ * `RangeError` instead of arming its clock.
+ *
+ * @category sleeping
+ * @since 0.1.0
+ */
+export const sleep = (
+  options: {
+    readonly name: string
+    readonly duration: Duration.Input
+    /**
+     * If the duration is less than or equal to this threshold, the clock will
+     * be executed in memory.
+     *
+     * @default 60 seconds
+     */
+    readonly inMemoryThreshold?: Duration.Input | undefined
+  }
+): Effect.Effect<
+  void,
+  never,
+  Crypto.Crypto | FlowRuntime | FlowInstance
+> => {
+  const name = options.name
+  const duration = clockDuration(options.duration)
+  const inMemoryThreshold = durationFromInput(
+    options.inMemoryThreshold ?? defaultInMemoryThreshold,
+    "inMemoryThreshold"
+  )
+
+  // Untraced because durable sleeps are recursively resumed by the engine.
+  return Effect.fnUntraced(function*() {
+    if (Duration.isZero(duration)) {
+      return
+    }
+
+    if (Duration.isLessThanOrEqualTo(duration, inMemoryThreshold)) {
+      return yield* Action.make({
+        name: `DurableClock/${name}`,
+        tier: "sealed",
+        execute: Effect.sleep(duration)
+      })
+    }
+
+    // A due time past the latest one a store records would fail the park
+    // write deep in the engine, so the sleep refuses it here by name.
+    const now = yield* Clock.currentTimeMillis
+    if (now + Duration.toMillis(duration) > latestDueAtMs) {
+      return yield* Effect.die(
+        new RangeError(
+          `DurableClock: "${name}" would wake after epoch millisecond ${latestDueAtMs}, ` +
+            `the latest due time a durable timer records.`
+        )
+      )
+    }
+    const engine = yield* FlowRuntime
+    const instance = yield* FlowInstance
+    const clock = makeClock(name, duration)
+    yield* engine.scheduleClock(instance.flow, {
+      executionId: instance.executionId,
+      clock
+    })
+    return yield* DurableDeferred.await(clock.deferred)
+  })()
+}
+
+const defaultInMemoryThreshold = Duration.seconds(60)