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

package/dist/cjs/FlowRuntime/FlowCycleDetected.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/FlowRuntime/FlowCycleDetected.ts"],
+  "sourcesContent": ["// Deep reviewed and polished by a human on 2026-08-10.\n\n/**\n * Failure raised when executing a flow would close a cycle in the persisted\n * parent-execution chain.\n *\n * @since 0.1.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * Raised when executing a flow would close a cycle in the persisted\n * parent-execution chain, which is a child asking to execute an execution id\n * that already appears among its own ancestors.\n *\n * This is a **typed failure**, never a defect: the caller is expected to be\n * able to recover from it (see `docs/troubleshooting.md`,\n * \"FlowRuntime.FlowCycleDetected\"). Detection itself lives in\n * `@smthrs/engine-store`'s `DurableEngineState.recordRunParent`, which\n * inserts the durable parent edge and walks the parent chain in O(depth)\n * inside one storage transaction, rolling back on a hit; the error is\n * declared here because it is part of the `execute` contract this package\n * owns.\n *\n * @category errors\n * @since 0.1.0\n */\nexport class FlowCycleDetected extends Schema.TaggedError<FlowCycleDetected>()(\n  \"@smthrs/flow/FlowCycleDetected\",\n  {\n    /** Stable public error code. */\n    // This wire shape freezes at 1.0.0-rc.0.\n    code: Schema.Literal(\"flow_cycle_detected\").pipe(\n      Schema.withConstructorDefault(Effect.succeed(\"flow_cycle_detected\"))\n    ),\n    /** Ordered execution ids from the cycle's target back to itself. */\n    path: Schema.Array(Schema.String)\n  }\n) {}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AASA,aAAwB;AACxB,aAAwB;AAmBjB,MAAM,0BAA0B,OAAO,YAA+B;AAAA,EAC3E;AAAA,EACA;AAAA;AAAA;AAAA,IAGE,MAAM,OAAO,QAAQ,qBAAqB,EAAE;AAAA,MAC1C,OAAO,uBAAuB,OAAO,QAAQ,qBAAqB,CAAC;AAAA,IACrE;AAAA;AAAA,IAEA,MAAM,OAAO,MAAM,OAAO,MAAM;AAAA,EAClC;AACF,EAAE;AAAC;",
+  "names": []
+}

package/dist/cjs/FlowRuntime/FlowExecutionNotFound.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Failure raised when `poll` addresses an execution the runtime has no record
+ * of.
+ *
+ * @since 0.1.0
+ */
+import * as Schema from "effect/Schema";
+declare const FlowExecutionNotFound_base: Schema.Class<FlowExecutionNotFound, Schema.TaggedStruct<"@smthrs/flow/FlowExecutionNotFound", {
+    /** Stable public error code. */
+    readonly code: Schema.withConstructorDefault<Schema.Literal<"execution_not_found">>;
+    /** The execution id the runtime has no record of. */
+    readonly executionId: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when `poll` is asked about an execution id the runtime never
+ * recorded.
+ *
+ * This is a **typed failure**, never a defect, and never folded into the
+ * success channel: `poll` answers `Option.none` for a known execution that has
+ * not settled yet, so answering it for an unknown id as well would leave the
+ * caller unable to distinguish "still running" from "no such execution". A
+ * caller holding a stored execution id needs that distinction — a run that is
+ * still in flight is waited on, one the runtime has no record of is a wiring
+ * or retention problem to surface.
+ *
+ * The error is declared here because it is part of the `poll` contract this
+ * package owns; every runtime — the in-memory engine and the durable
+ * `@smthrs/engine-store` driver alike — raises it for an unknown id.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class FlowExecutionNotFound extends FlowExecutionNotFound_base {
+    /** @since 0.1.0 */
+    get message(): string;
+}
+export {};
+//# sourceMappingURL=FlowExecutionNotFound.d.ts.map

package/dist/cjs/FlowRuntime/FlowExecutionNotFound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlowExecutionNotFound.d.ts","sourceRoot":"","sources":["../../../src/FlowRuntime/FlowExecutionNotFound.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;;IAwBnC,gCAAgC;;IAKhC,qDAAqD;;;AA3BzD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,qBAAsB,SAAQ,0BAW1C;IACC,mBAAmB;IACnB,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF"}

package/dist/cjs/FlowRuntime/FlowExecutionNotFound.js

@@ -0,0 +1,53 @@
+"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 FlowExecutionNotFound_exports = {};
+__export(FlowExecutionNotFound_exports, {
+  FlowExecutionNotFound: () => FlowExecutionNotFound
+});
+module.exports = __toCommonJS(FlowExecutionNotFound_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+class FlowExecutionNotFound extends Schema.TaggedError()(
+  "@smthrs/flow/FlowExecutionNotFound",
+  {
+    /** Stable public error code. */
+    // This wire shape freezes at 1.0.0-rc.0.
+    code: Schema.Literal("execution_not_found").pipe(
+      Schema.withConstructorDefault(Effect.succeed("execution_not_found"))
+    ),
+    /** The execution id the runtime has no record of. */
+    executionId: Schema.String
+  }
+) {
+  /** @since 0.1.0 */
+  get message() {
+    return `No flow execution is recorded under id "${this.executionId}"`;
+  }
+}
+//# sourceMappingURL=FlowExecutionNotFound.js.map

package/dist/cjs/FlowRuntime/FlowExecutionNotFound.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/FlowRuntime/FlowExecutionNotFound.ts"],
+  "sourcesContent": ["/**\n * Failure raised when `poll` addresses an execution the runtime has no record\n * of.\n *\n * @since 0.1.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * Raised when `poll` is asked about an execution id the runtime never\n * recorded.\n *\n * This is a **typed failure**, never a defect, and never folded into the\n * success channel: `poll` answers `Option.none` for a known execution that has\n * not settled yet, so answering it for an unknown id as well would leave the\n * caller unable to distinguish \"still running\" from \"no such execution\". A\n * caller holding a stored execution id needs that distinction \u2014 a run that is\n * still in flight is waited on, one the runtime has no record of is a wiring\n * or retention problem to surface.\n *\n * The error is declared here because it is part of the `poll` contract this\n * package owns; every runtime \u2014 the in-memory engine and the durable\n * `@smthrs/engine-store` driver alike \u2014 raises it for an unknown id.\n *\n * @category errors\n * @since 0.1.0\n */\nexport class FlowExecutionNotFound extends Schema.TaggedError<FlowExecutionNotFound>()(\n  \"@smthrs/flow/FlowExecutionNotFound\",\n  {\n    /** Stable public error code. */\n    // This wire shape freezes at 1.0.0-rc.0.\n    code: Schema.Literal(\"execution_not_found\").pipe(\n      Schema.withConstructorDefault(Effect.succeed(\"execution_not_found\"))\n    ),\n    /** The execution id the runtime has no record of. */\n    executionId: Schema.String\n  }\n) {\n  /** @since 0.1.0 */\n  override get message(): string {\n    return `No flow execution is recorded under id \"${this.executionId}\"`\n  }\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,aAAwB;AACxB,aAAwB;AAqBjB,MAAM,8BAA8B,OAAO,YAAmC;AAAA,EACnF;AAAA,EACA;AAAA;AAAA;AAAA,IAGE,MAAM,OAAO,QAAQ,qBAAqB,EAAE;AAAA,MAC1C,OAAO,uBAAuB,OAAO,QAAQ,qBAAqB,CAAC;AAAA,IACrE;AAAA;AAAA,IAEA,aAAa,OAAO;AAAA,EACtB;AACF,EAAE;AAAA;AAAA,EAEA,IAAa,UAAkB;AAC7B,WAAO,2CAA2C,KAAK,WAAW;AAAA,EACpE;AACF;",
+  "names": []
+}

package/dist/cjs/FlowRuntime/FlowInstance.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The per-execution state contract flow authoring APIs read and update.
+ *
+ * @since 0.1.0
+ */
+import type * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import type * as Latch from "effect/Latch";
+import type * as Scope from "effect/Scope";
+import type * as Flow from "../Flow/index.ts";
+import type { WaitingAnnotation } from "./WaitingAnnotation.ts";
+declare const FlowInstance_base: Context.ServiceClass<FlowInstance, "@smthrs/flow/FlowRuntime/FlowInstance", {
+    /**
+     * The flow execution ID.
+     */
+    readonly executionId: string;
+    /**
+     * The journal lineage this execution's records address themselves to.
+     *
+     * `docs/concepts/the-runtime-port.md` makes a frame the journal position
+     * `(lineageId, seq)`, and `docs/guides/run-a-child-flow.md` defines the
+     * lineage id as the run id followed by the node-id path from the run root.
+     * A runtime mints it; every durable record this execution writes carries it
+     * as `meta.lineageId`, which is what lets `TimeTravel.inspect` fold an
+     * ordinary engine journal at all.
+     */
+    readonly lineageId: string;
+    /**
+     * The flow definition.
+     */
+    readonly flow: Flow.Any;
+    /**
+     * A scope that represents the lifetime of the flow.
+     *
+     * It is only closed when the flow is completed.
+     */
+    readonly scope: Scope.Closeable;
+    /**
+     * Whether the flow has requested to be suspended.
+     */
+    suspended: boolean;
+    /**
+     * Whether the flow has requested to be interrupted.
+     */
+    interrupted: boolean;
+    /**
+     * The waiting classification the flow declared for its next suspension
+     * via `annotateWaiting`. Durable drivers read it when parking the
+     * run so approval and quota waits (and their wake token) are
+     * representable; when absent the driver derives `timer`/`event` from
+     * durable state.
+     */
+    waiting: WaitingAnnotation | undefined;
+    /**
+     * The next-round invocation this round settled with, when its body's root
+     * value was a `to` rather than a `done`.
+     *
+     * A handoff is a settlement, not a failure and not a suspension, so it
+     * cannot travel out through the effect's exit; `Flow.intoResult` reads the
+     * slot and answers `Flow.Handoff` instead of `Flow.Complete`. The engine
+     * then opens the next round under the same lineage
+     * (`docs/concepts/trampoline-rounds.md`).
+     */
+    handoff: Flow.Handoff | undefined;
+    /**
+     * The lineage deadline this round inherited from the round that handed
+     * off to it, when its lineage is bounded. `Deadline.bound` runs the round
+     * under it instead of starting a deadline of its own.
+     */
+    readonly lineageDeadline?: Flow.LineageDeadline | undefined;
+    /**
+     * When SuspendOnFailure is triggered, the cause of the failure is stored
+     * here.
+     */
+    cause: Cause.Cause<never> | undefined;
+    readonly actionState: {
+        count: number;
+        readonly latch: Latch.Latch;
+        readonly nextOrdinal: (scope: string) => number;
+        readonly snapshots: Map<string, unknown>;
+        /**
+         * Allocation scopes with a keyless dispatch currently in flight
+         * (issue #111). Indistinguishable invocations of one declaration are
+         * allocation-ordered, so two in flight at once would take their
+         * ordinals from the fiber schedule and a replay could swap their
+         * recorded outcomes undetected; the engine refuses the second dispatch
+         * instead. Distinct interpreter graph sites refine the scope and do not
+         * contend here.
+         */
+        readonly keylessInFlight: Set<string>;
+    };
+}>;
+/**
+ * Service that contains flow runtime state for one execution.
+ *
+ * **When to use**
+ *
+ * Use to read or update flow execution, suspension, interruption,
+ * lifetime, failure, and action coordination state inside flow authoring
+ * combinators and runtime implementations.
+ *
+ * **Details**
+ *
+ * The service stores the execution ID, flow definition, long-lived scope,
+ * suspension and interruption flags, the stored failure cause, and action
+ * coordination state for a single flow run. `@smthrs/flow` declares the
+ * contract; a runtime — `@smthrs/engine` — constructs the value.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class FlowInstance extends FlowInstance_base {
+}
+export {};
+//# sourceMappingURL=FlowInstance.d.ts.map

package/dist/cjs/FlowRuntime/FlowInstance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlowInstance.d.ts","sourceRoot":"","sources":["../../../src/FlowRuntime/FlowInstance.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,KAAK,IAAI,MAAM,kBAAkB,CAAA;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;;IAwB3D;;OAEG;0BACmB,MAAM;IAE5B;;;;;;;;;OASG;wBACiB,MAAM;IAE1B;;OAEG;mBACY,IAAI,CAAC,GAAG;IAEvB;;;;OAIG;oBACa,KAAK,CAAC,SAAS;IAE/B;;OAEG;eACQ,OAAO;IAElB;;OAEG;iBACU,OAAO;IAEpB;;;;;;OAMG;aACM,iBAAiB,GAAG,SAAS;IAEtC;;;;;;;;;OASG;aACM,IAAI,CAAC,OAAO,GAAG,SAAS;IAEjC;;;;OAIG;+BACwB,IAAI,CAAC,eAAe,GAAG,SAAS;IAE3D;;;OAGG;WACI,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,SAAS;0BAEf;QACpB,KAAK,EAAE,MAAM,CAAA;QACb,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAA;QAC3B,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;QAC/C,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACxC;;;;;;;;WAQG;QACH,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;KACtC;;AA9GL;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,YAAa,SAAQ,iBA6FU;CAAG"}

package/dist/cjs/FlowRuntime/FlowInstance.js

@@ -0,0 +1,37 @@
+"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 FlowInstance_exports = {};
+__export(FlowInstance_exports, {
+  FlowInstance: () => FlowInstance
+});
+module.exports = __toCommonJS(FlowInstance_exports);
+var Context = __toESM(require("effect/Context"), 1);
+class FlowInstance extends Context.Service()("@smthrs/flow/FlowRuntime/FlowInstance") {
+}
+//# sourceMappingURL=FlowInstance.js.map

package/dist/cjs/FlowRuntime/FlowInstance.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/FlowRuntime/FlowInstance.ts"],
+  "sourcesContent": ["// Deep reviewed and polished by a human on 2026-08-10.\n\n/**\n * The per-execution state contract flow authoring APIs read and update.\n *\n * @since 0.1.0\n */\n\nimport type * as Cause from \"effect/Cause\"\nimport * as Context from \"effect/Context\"\nimport type * as Latch from \"effect/Latch\"\nimport type * as Scope from \"effect/Scope\"\nimport type * as Flow from \"../Flow/index.ts\"\nimport type { WaitingAnnotation } from \"./WaitingAnnotation.ts\"\n\n/**\n * Service that contains flow runtime state for one execution.\n *\n * **When to use**\n *\n * Use to read or update flow execution, suspension, interruption,\n * lifetime, failure, and action coordination state inside flow authoring\n * combinators and runtime implementations.\n *\n * **Details**\n *\n * The service stores the execution ID, flow definition, long-lived scope,\n * suspension and interruption flags, the stored failure cause, and action\n * coordination state for a single flow run. `@smthrs/flow` declares the\n * contract; a runtime \u2014 `@smthrs/engine` \u2014 constructs the value.\n *\n * @category services\n * @since 0.1.0\n */\nexport class FlowInstance extends Context.Service<\n  FlowInstance,\n  {\n    /**\n     * The flow execution ID.\n     */\n    readonly executionId: string\n\n    /**\n     * The journal lineage this execution's records address themselves to.\n     *\n     * `docs/concepts/the-runtime-port.md` makes a frame the journal position\n     * `(lineageId, seq)`, and `docs/guides/run-a-child-flow.md` defines the\n     * lineage id as the run id followed by the node-id path from the run root.\n     * A runtime mints it; every durable record this execution writes carries it\n     * as `meta.lineageId`, which is what lets `TimeTravel.inspect` fold an\n     * ordinary engine journal at all.\n     */\n    readonly lineageId: string\n\n    /**\n     * The flow definition.\n     */\n    readonly flow: Flow.Any\n\n    /**\n     * A scope that represents the lifetime of the flow.\n     *\n     * It is only closed when the flow is completed.\n     */\n    readonly scope: Scope.Closeable\n\n    /**\n     * Whether the flow has requested to be suspended.\n     */\n    suspended: boolean\n\n    /**\n     * Whether the flow has requested to be interrupted.\n     */\n    interrupted: boolean\n\n    /**\n     * The waiting classification the flow declared for its next suspension\n     * via `annotateWaiting`. Durable drivers read it when parking the\n     * run so approval and quota waits (and their wake token) are\n     * representable; when absent the driver derives `timer`/`event` from\n     * durable state.\n     */\n    waiting: WaitingAnnotation | undefined\n\n    /**\n     * The next-round invocation this round settled with, when its body's root\n     * value was a `to` rather than a `done`.\n     *\n     * A handoff is a settlement, not a failure and not a suspension, so it\n     * cannot travel out through the effect's exit; `Flow.intoResult` reads the\n     * slot and answers `Flow.Handoff` instead of `Flow.Complete`. The engine\n     * then opens the next round under the same lineage\n     * (`docs/concepts/trampoline-rounds.md`).\n     */\n    handoff: Flow.Handoff | undefined\n\n    /**\n     * The lineage deadline this round inherited from the round that handed\n     * off to it, when its lineage is bounded. `Deadline.bound` runs the round\n     * under it instead of starting a deadline of its own.\n     */\n    readonly lineageDeadline?: Flow.LineageDeadline | undefined\n\n    /**\n     * When SuspendOnFailure is triggered, the cause of the failure is stored\n     * here.\n     */\n    cause: Cause.Cause<never> | undefined\n\n    readonly actionState: {\n      count: number\n      readonly latch: Latch.Latch\n      readonly nextOrdinal: (scope: string) => number\n      readonly snapshots: Map<string, unknown>\n      /**\n       * Allocation scopes with a keyless dispatch currently in flight\n       * (issue #111). Indistinguishable invocations of one declaration are\n       * allocation-ordered, so two in flight at once would take their\n       * ordinals from the fiber schedule and a replay could swap their\n       * recorded outcomes undetected; the engine refuses the second dispatch\n       * instead. Distinct interpreter graph sites refine the scope and do not\n       * contend here.\n       */\n      readonly keylessInFlight: Set<string>\n    }\n  }\n>()(\"@smthrs/flow/FlowRuntime/FlowInstance\") {}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AASA,cAAyB;AAyBlB,MAAM,qBAAqB,QAAQ,QA6FxC,EAAE,uCAAuC,EAAE;AAAC;",
+  "names": []
+}

package/dist/cjs/FlowRuntime/FlowRuntime.d.ts

@@ -0,0 +1,198 @@
+/**
+ * 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;
+}
+declare const FlowRuntime_base: Context.ServiceClass<FlowRuntime, "@smthrs/flow/FlowRuntime/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>;
+}>;
+/**
+ * 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 declare class FlowRuntime extends FlowRuntime_base {
+}
+export {};
+//# sourceMappingURL=FlowRuntime.d.ts.map

package/dist/cjs/FlowRuntime/FlowRuntime.d.ts.map

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

package/dist/cjs/FlowRuntime/FlowRuntime.js

@@ -0,0 +1,37 @@
+"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 FlowRuntime_exports = {};
+__export(FlowRuntime_exports, {
+  FlowRuntime: () => FlowRuntime
+});
+module.exports = __toCommonJS(FlowRuntime_exports);
+var Context = __toESM(require("effect/Context"), 1);
+class FlowRuntime extends Context.Service()("@smthrs/flow/FlowRuntime/FlowRuntime") {
+}
+//# sourceMappingURL=FlowRuntime.js.map

package/dist/cjs/FlowRuntime/FlowRuntime.js.map

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