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

package/dist/cjs/Flow/Runtime.d.ts

@@ -0,0 +1,98 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Scope from "effect/Scope";
+import { FlowInstance } from "../FlowRuntime/FlowInstance.ts";
+import { type Result } 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 declare const intoResult: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<Result<A, E>, never, Exclude<R, Scope.Scope> | FlowInstance>;
+/**
+ * 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 declare const wrapActionResult: <A, E, R>(effect: Effect.Effect<A, E, R>, isSuspend: (value: A) => boolean) => Effect.Effect<A, E, R | FlowInstance>;
+/**
+ * Accesses the current round's flow scope. Suspension keeps it open;
+ * completion or handoff closes it.
+ *
+ * @category resource management
+ * @since 0.1.0
+ */
+export declare const scope: Effect.Effect<Scope.Scope, never, FlowInstance>;
+/**
+ * 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 declare const provideScope: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Scope.Scope> | FlowInstance>;
+/**
+ * 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 declare const addFinalizer: <R>(f: (exit: Exit.Exit<unknown, unknown>) => Effect.Effect<void, never, R>) => Effect.Effect<void, never, FlowInstance | R>;
+/**
+ * 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 declare 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>;
+};
+/**
+ * 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 declare const suspend: (instance: FlowInstance["Service"]) => Effect.Effect<never>;
+//# sourceMappingURL=Runtime.d.ts.map

package/dist/cjs/Flow/Runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Runtime.d.ts","sourceRoot":"","sources":["../../../src/Flow/Runtime.ts"],"names":[],"mappings":"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"}

package/dist/cjs/Flow/Runtime.js

@@ -0,0 +1,160 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Runtime_exports = {};
+__export(Runtime_exports, {
+  addFinalizer: () => addFinalizer,
+  intoResult: () => intoResult,
+  provideScope: () => provideScope,
+  scope: () => scope,
+  suspend: () => suspend,
+  withRollback: () => withRollback,
+  wrapActionResult: () => wrapActionResult
+});
+module.exports = __toCommonJS(Runtime_exports);
+var Arr = __toESM(require("effect/Array"), 1);
+var Cause = __toESM(require("effect/Cause"), 1);
+var Context = __toESM(require("effect/Context"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Exit = __toESM(require("effect/Exit"), 1);
+var Fiber = __toESM(require("effect/Fiber"), 1);
+var Filter = __toESM(require("effect/Filter"), 1);
+var import_Function = require("effect/Function");
+var Scope = __toESM(require("effect/Scope"), 1);
+var import_FlowInstance = require("../FlowRuntime/FlowInstance.js");
+var import_Annotations = require("./Annotations.js");
+var import_Result = require("./Result.js");
+const intoResult = (effect) => Effect.contextWith((context) => {
+  const instance = Context.get(context, import_FlowInstance.FlowInstance);
+  const captureDefects = Context.get(instance.flow.annotations, import_Annotations.CaptureDefects);
+  const suspendOnFailure = Context.get(instance.flow.annotations, import_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;
+    }) : import_Function.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 import_Result.Complete({ exit: Exit.succeed(value) })
+      ),
+      onFailure: (cause) => {
+        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 import_Result.Suspended({ cause: instance.cause })) : !instance.interrupted && hasInterruptsOnly || !captureDefects && Cause.hasDies(cause) ? Effect.failCause(filtered) : Effect.succeed(new import_Result.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") {
+        return Scope.close(instance.scope, Exit.void);
+      }
+      return Effect.void;
+    }, true),
+    Effect.uninterruptible
+  );
+});
+const EnclosingActions = Context.Reference(
+  "@smthrs/flow/Flow/EnclosingActions",
+  { defaultValue: () => [] }
+);
+const wrapActionResult = (effect, isSuspend) => Effect.contextWith((context) => {
+  const instance = Context.get(context, import_FlowInstance.FlowInstance);
+  const enclosing = Context.getUnsafe(context, EnclosingActions);
+  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) && (0, import_Result.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;
+      return isSuspended ? Effect.andThen(state.latch.release, waitForSiblings(instance, ancestors)) : Effect.asVoid(state.latch.release);
+    }
+  );
+});
+const waitForSiblings = Effect.fnUntraced(function* (instance, ancestors) {
+  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;
+  }
+});
+const scope = Effect.map(
+  import_FlowInstance.FlowInstance,
+  (instance) => instance.scope
+);
+const provideScope = (effect) => Effect.flatMap(scope, (scope2) => Scope.provide(effect, scope2));
+const addFinalizer = (
+  // Untraced because suspension recursively re-enters flow execution.
+  Effect.fnUntraced(function* (f) {
+    const instance = yield* import_FlowInstance.FlowInstance;
+    const services = yield* Effect.context();
+    yield* Scope.addFinalizerExit(instance.scope, (exit) => Effect.provideContext(f(exit), services));
+  })
+);
+const withRollback = (0, import_Function.dual)(2, (effect, rollback) => Effect.uninterruptibleMask(
+  (restore) => Effect.tap(
+    restore(effect),
+    (value) => addFinalizer((exit) => Exit.isSuccess(exit) ? Effect.void : rollback(value, exit.cause))
+  )
+));
+const suspend = (instance) => Effect.interruptible(Effect.callback(() => {
+  instance.suspended = true;
+  const fiber = Fiber.getCurrent();
+  fiber.interruptUnsafe(fiber.id);
+}));
+//# sourceMappingURL=Runtime.js.map

package/dist/cjs/Flow/Runtime.js.map

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

package/dist/cjs/Flow/TypeId.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Runtime identity shared by flow interfaces and constructors.
+ *
+ * @private
+ * @since 0.1.0
+ */
+export declare const TypeId = "@smthrs/flow/Flow";
+//# sourceMappingURL=TypeId.d.ts.map

package/dist/cjs/Flow/TypeId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TypeId.d.ts","sourceRoot":"","sources":["../../../src/Flow/TypeId.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,eAAO,MAAM,MAAM,sBAAsB,CAAA"}

package/dist/cjs/Flow/TypeId.js

@@ -0,0 +1,25 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var TypeId_exports = {};
+__export(TypeId_exports, {
+  TypeId: () => TypeId
+});
+module.exports = __toCommonJS(TypeId_exports);
+const TypeId = "@smthrs/flow/Flow";
+//# sourceMappingURL=TypeId.js.map

package/dist/cjs/Flow/TypeId.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/Flow/TypeId.ts"],
+  "sourcesContent": ["// Deep reviewed and polished by a human on 2026-08-10.\n\n/**\n * Runtime identity shared by flow interfaces and constructors.\n *\n * @private\n * @since 0.1.0\n */\nexport const TypeId = \"@smthrs/flow/Flow\"\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAQO,MAAM,SAAS;",
+  "names": []
+}

package/dist/cjs/Flow/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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";
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/Flow/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/Flow/index.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,cAAc,kBAAkB,CAAA;AAChC,cAAc,wBAAwB,CAAA;AACtC,cAAc,uBAAuB,CAAA;AACrC,cAAc,0BAA0B,CAAA;AACxC,cAAc,mBAAmB,CAAA;AACjC,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,wBAAwB,CAAA;AACtC,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA"}

package/dist/cjs/Flow/index.js

@@ -0,0 +1,29 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Flow_exports = {};
+module.exports = __toCommonJS(Flow_exports);
+__reExport(Flow_exports, require("./Annotations.js"), module.exports);
+__reExport(Flow_exports, require("./CapabilityCeiling.js"), module.exports);
+__reExport(Flow_exports, require("./DeadlineExceeded.js"), module.exports);
+__reExport(Flow_exports, require("./ExecutionIdRequired.js"), module.exports);
+__reExport(Flow_exports, require("./ExecutionIds.js"), module.exports);
+__reExport(Flow_exports, require("./Flow.js"), module.exports);
+__reExport(Flow_exports, require("./make.js"), module.exports);
+__reExport(Flow_exports, require("./MaxRoundsExceeded.js"), module.exports);
+__reExport(Flow_exports, require("./Outcome.js"), module.exports);
+__reExport(Flow_exports, require("./Result.js"), module.exports);
+__reExport(Flow_exports, require("./Runtime.js"), module.exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/Flow/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/Flow/index.ts"],
+  "sourcesContent": ["// Deep reviewed and polished by a human on 2026-08-10.\n\n/**\n * Typed durable flow definitions, results, and runtime helpers.\n *\n * @since 0.1.0\n */\n\nexport * from \"./Annotations.ts\"\nexport * from \"./CapabilityCeiling.ts\"\nexport * from \"./DeadlineExceeded.ts\"\nexport * from \"./ExecutionIdRequired.ts\"\nexport * from \"./ExecutionIds.ts\"\nexport * from \"./Flow.ts\"\nexport * from \"./make.ts\"\nexport * from \"./MaxRoundsExceeded.ts\"\nexport * from \"./Outcome.ts\"\nexport * from \"./Result.ts\"\nexport * from \"./Runtime.ts\"\n"],
+  "mappings": ";;;;;;;;;;;;;;;AAAA;AAAA;AAQA,yBAAc,6BARd;AASA,yBAAc,mCATd;AAUA,yBAAc,kCAVd;AAWA,yBAAc,qCAXd;AAYA,yBAAc,8BAZd;AAaA,yBAAc,sBAbd;AAcA,yBAAc,sBAdd;AAeA,yBAAc,mCAfd;AAgBA,yBAAc,yBAhBd;AAiBA,yBAAc,wBAjBd;AAkBA,yBAAc,yBAlBd;",
+  "names": []
+}

package/dist/cjs/Flow/internal.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Private flow construction shared by declarations and action registration.
+ *
+ * @since 1.0.0
+ * @private
+ */
+import * as Node from "@smthrs/plan/Node";
+import * as Context from "effect/Context";
+import type * as Duration from "effect/Duration";
+import * as Schema from "effect/Schema";
+import type * as RetryPolicy from "../RetryPolicy.ts";
+import type { Any, AnyStructSchema, BodySuccess, DeclarationMetadata, Flow } from "./Flow.ts";
+/**
+ * Builds the private prototype from normalized declaration data.
+ *
+ * @since 1.0.0
+ * @private
+ */
+export declare 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>;
+//# sourceMappingURL=internal.d.ts.map

package/dist/cjs/Flow/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../../src/Flow/internal.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,IAAI,MAAM,mBAAmB,CAAA;AAEzC,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAEzC,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAEhD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAIvC,OAAO,KAAK,KAAK,WAAW,MAAM,mBAAmB,CAAA;AAErD,OAAO,KAAK,EAAE,GAAG,EAAE,eAAe,EAAgB,WAAW,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAuL3G;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GACpB,KAAK,CAAC,GAAG,SAAS,MAAM,EACxB,OAAO,SAAS,eAAe,EAC/B,OAAO,SAAS,MAAM,CAAC,GAAG,EAC1B,KAAK,SAAS,MAAM,CAAC,GAAG,EACxB,QAAQ,EAER,SAAS,mBAAmB,GAAG;IAC7B,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAA;IAClB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAA;IAC3B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAC5C,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAA;IAC7G,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC,GAAG,SAAS,CAAA;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IAC3C,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC,GAAG,SAAS,CAAA;IAC5E,QAAQ,CAAC,oBAAoB,CAAC,EAAE,WAAW,CAAC,WAAW,GAAG,SAAS,CAAA;IACnE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,QAAQ,GAAG,SAAS,CAAA;CAClD,KACA,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,CAK7C,CAAA"}

package/dist/cjs/Flow/internal.js

@@ -0,0 +1,187 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var internal_exports = {};
+__export(internal_exports, {
+  makeProto: () => makeProto
+});
+module.exports = __toCommonJS(internal_exports);
+var import_crypto = require("@smthrs/crypto");
+var Node = __toESM(require("@smthrs/plan/Node"), 1);
+var Cause = __toESM(require("effect/Cause"), 1);
+var Context = __toESM(require("effect/Context"), 1);
+var Crypto = __toESM(require("effect/Crypto"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var import_ExecutionIdentityConflict = require("../FlowRuntime/ExecutionIdentityConflict.js");
+var import_FlowRuntime = require("../FlowRuntime/FlowRuntime.js");
+var DeclarationSite = __toESM(require("../internal/DeclarationSite.js"), 1);
+var import_ExecutionIds = require("./ExecutionIds.js");
+var import_Runtime = require("./Runtime.js");
+var import_TypeId = require("./TypeId.js");
+const makeExecutionIdFromPayload = (self, payload) => {
+  const idempotencyKey = self.idempotencyKey;
+  return idempotencyKey === void 0 ? Effect.flatMap(import_ExecutionIds.CurrentExecutionIds, (source) => source.mint(self, payload)) : Schema.decodeUnknownEffect(import_crypto.Sha256)(JSON.stringify([self._tag, idempotencyKey(payload)])).pipe(Effect.orDie);
+};
+const resolveExecutionId = (self, payload, executionId) => executionId === void 0 ? makeExecutionIdFromPayload(self, payload) : Effect.succeed(executionId);
+const Proto = {
+  [import_TypeId.TypeId]: import_TypeId.TypeId,
+  annotate(tag, value) {
+    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(context) {
+    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(payload) {
+    return Node.flowCall(this, this._tag, "inline", payload);
+  },
+  child(payload) {
+    return Node.flowCall(this, this._tag, "boundary", payload);
+  },
+  to(payload) {
+    return Node.flowCall(this, this._tag, "handoff", payload);
+  },
+  execute(fields, opts) {
+    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(import_FlowRuntime.FlowRuntime, (engine) => Effect.andThen(
+            Effect.annotateCurrentSpan({ executionId }),
+            engine.execute(this, {
+              executionId,
+              payload,
+              discard: opts?.discard,
+              suspendedRetryPolicy: this.suspendedRetryPolicy
+            }).pipe(Effect.catchCause((cause) => {
+              const reason = cause.reasons.length === 1 ? cause.reasons.find(Cause.isDieReason) : void 0;
+              return reason?.defect instanceof import_ExecutionIdentityConflict.ExecutionIdentityConflict ? Effect.fail(reason.defect) : Effect.failCause(cause);
+            }))
+          ))
+        )
+      )
+    ).pipe(
+      Effect.withSpan(
+        `${this._tag}.execute`,
+        {},
+        { captureStackTrace: false }
+      )
+    );
+  },
+  start(payload) {
+    return Effect.flatMap(
+      Crypto.Crypto,
+      (crypto) => Effect.flatMap(
+        Effect.orDie(crypto.randomUUIDv4),
+        (executionId) => this.execute(payload, { executionId, discard: true })
+      )
+    );
+  },
+  ensure(payload, options) {
+    return Schema.decodeUnknownEffect(Schema.String)(options.key).pipe(
+      Effect.flatMap((key) => Effect.orDie(Schema.decodeUnknownEffect(import_crypto.Sha256)(JSON.stringify([this._tag, key])))),
+      Effect.flatMap((executionId) => this.execute(payload, { executionId, discard: true }))
+    );
+  },
+  poll(executionId) {
+    return Effect.flatMap(import_FlowRuntime.FlowRuntime, (engine) => engine.poll(this, executionId)).pipe(
+      Effect.withSpan(`${this._tag}.poll`, { attributes: { executionId } }, { captureStackTrace: false })
+    );
+  },
+  interrupt(executionId) {
+    return Effect.flatMap(import_FlowRuntime.FlowRuntime, (engine) => engine.interrupt(this, executionId)).pipe(
+      Effect.withSpan(`${this._tag}.interrupt`, { attributes: { executionId } }, { captureStackTrace: false })
+    );
+  },
+  resume(executionId) {
+    return Effect.flatMap(import_FlowRuntime.FlowRuntime, (engine) => engine.resume(this, executionId)).pipe(
+      Effect.withSpan(`${this._tag}.resume`, { attributes: { executionId } }, { captureStackTrace: false })
+    );
+  },
+  executionId(payload) {
+    return Effect.flatMap(
+      // The channel stays never: precomputing callers must validate first, and an invalid payload dies here.
+      Effect.orDie(this.payloadSchema.makeEffect(payload)),
+      (payload2) => makeExecutionIdFromPayload(this, payload2)
+    );
+  },
+  withRollback: ((...args) => (0, import_Runtime.withRollback)(...args))
+};
+const makeProto = (options) => {
+  function Flow() {
+  }
+  Object.setPrototypeOf(Flow, Proto);
+  Object.assign(Flow, options);
+  return Flow;
+};
+//# sourceMappingURL=internal.js.map