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

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

@@ -0,0 +1,23 @@
+/** Execution identity refusals shared by authoring and engine layers.
+ * @since 1.0.0
+ */
+import * as Schema from "effect/Schema";
+declare const ExecutionIdentityConflict_base: Schema.Class<ExecutionIdentityConflict, Schema.TaggedStruct<"@smthrs/engine/ExecutionIdentityConflict", {
+    readonly code: Schema.withConstructorDefault<Schema.Literal<"execution_identity_conflict">>;
+    readonly executionId: Schema.String;
+    readonly field: Schema.Literals<readonly ["flow", "payload", "capabilities", "lineage", "round", "parent"]>;
+    readonly expected: Schema.String;
+    readonly actual: Schema.String;
+    readonly status: Schema.withConstructorDefault<Schema.Literals<readonly ["pending", "running", "suspended", "completed", "failed", "cancelled", "unknown"]>>;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A caller reused an execution id for different persisted run identity.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare class ExecutionIdentityConflict extends ExecutionIdentityConflict_base {
+}
+export {};
+//# sourceMappingURL=ExecutionIdentityConflict.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionIdentityConflict.d.ts","sourceRoot":"","sources":["../../../src/FlowRuntime/ExecutionIdentityConflict.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;;;;;;;;;;AAGvC;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,8BAe9C;CAAG"}

package/dist/cjs/FlowRuntime/ExecutionIdentityConflict.js

@@ -0,0 +1,55 @@
+"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 ExecutionIdentityConflict_exports = {};
+__export(ExecutionIdentityConflict_exports, {
+  ExecutionIdentityConflict: () => ExecutionIdentityConflict
+});
+module.exports = __toCommonJS(ExecutionIdentityConflict_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var Fault = __toESM(require("../Fault.js"), 1);
+class ExecutionIdentityConflict extends Schema.TaggedError()(
+  "@smthrs/engine/ExecutionIdentityConflict",
+  {
+    code: Schema.Literal("execution_identity_conflict").pipe(
+      Schema.withConstructorDefault(Effect.succeed("execution_identity_conflict"))
+    ),
+    executionId: Schema.String,
+    field: Schema.Literals(["flow", "payload", "capabilities", "lineage", "round", "parent"]),
+    expected: Schema.String,
+    actual: Schema.String,
+    status: Schema.Literals(["pending", "running", "suspended", "completed", "failed", "cancelled", "unknown"]).pipe(
+      Schema.withConstructorDefault(Effect.succeed("unknown"))
+    ),
+    message: Schema.String
+  }
+) {
+}
+Fault.register("@smthrs/engine/ExecutionIdentityConflict", "bug");
+//# sourceMappingURL=ExecutionIdentityConflict.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/FlowRuntime/ExecutionIdentityConflict.ts"],
+  "sourcesContent": ["/** Execution identity refusals shared by authoring and engine layers.\n * @since 1.0.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\nimport * as Fault from \"../Fault.ts\"\n\n/**\n * A caller reused an execution id for different persisted run identity.\n *\n * @category errors\n * @since 1.0.0\n */\nexport class ExecutionIdentityConflict extends Schema.TaggedError<ExecutionIdentityConflict>()(\n  \"@smthrs/engine/ExecutionIdentityConflict\",\n  {\n    code: Schema.Literal(\"execution_identity_conflict\").pipe(\n      Schema.withConstructorDefault(Effect.succeed(\"execution_identity_conflict\"))\n    ),\n    executionId: Schema.String,\n    field: Schema.Literals([\"flow\", \"payload\", \"capabilities\", \"lineage\", \"round\", \"parent\"]),\n    expected: Schema.String,\n    actual: Schema.String,\n    status: Schema.Literals([\"pending\", \"running\", \"suspended\", \"completed\", \"failed\", \"cancelled\", \"unknown\"]).pipe(\n      Schema.withConstructorDefault(Effect.succeed(\"unknown\"))\n    ),\n    message: Schema.String\n  }\n) {}\n\nFault.register(\"@smthrs/engine/ExecutionIdentityConflict\", \"bug\")\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAIA,aAAwB;AACxB,aAAwB;AACxB,YAAuB;AAQhB,MAAM,kCAAkC,OAAO,YAAuC;AAAA,EAC3F;AAAA,EACA;AAAA,IACE,MAAM,OAAO,QAAQ,6BAA6B,EAAE;AAAA,MAClD,OAAO,uBAAuB,OAAO,QAAQ,6BAA6B,CAAC;AAAA,IAC7E;AAAA,IACA,aAAa,OAAO;AAAA,IACpB,OAAO,OAAO,SAAS,CAAC,QAAQ,WAAW,gBAAgB,WAAW,SAAS,QAAQ,CAAC;AAAA,IACxF,UAAU,OAAO;AAAA,IACjB,QAAQ,OAAO;AAAA,IACf,QAAQ,OAAO,SAAS,CAAC,WAAW,WAAW,aAAa,aAAa,UAAU,aAAa,SAAS,CAAC,EAAE;AAAA,MAC1G,OAAO,uBAAuB,OAAO,QAAQ,SAAS,CAAC;AAAA,IACzD;AAAA,IACA,SAAS,OAAO;AAAA,EAClB;AACF,EAAE;AAAC;AAEH,MAAM,SAAS,4CAA4C,KAAK;",
+  "names": []
+}

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

@@ -0,0 +1,28 @@
+import * as Schema from "effect/Schema";
+declare const FlowCycleDetected_base: Schema.Class<FlowCycleDetected, Schema.TaggedStruct<"@smthrs/flow/FlowCycleDetected", {
+    /** Stable public error code. */
+    readonly code: Schema.withConstructorDefault<Schema.Literal<"flow_cycle_detected">>;
+    /** Ordered execution ids from the cycle's target back to itself. */
+    readonly path: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when executing a flow would close a cycle in the persisted
+ * parent-execution chain, which is a child asking to execute an execution id
+ * that already appears among its own ancestors.
+ *
+ * This is a **typed failure**, never a defect: the caller is expected to be
+ * able to recover from it (see `docs/troubleshooting.md`,
+ * "FlowRuntime.FlowCycleDetected"). Detection itself lives in
+ * `@smthrs/engine-store`'s `DurableEngineState.recordRunParent`, which
+ * inserts the durable parent edge and walks the parent chain in O(depth)
+ * inside one storage transaction, rolling back on a hit; the error is
+ * declared here because it is part of the `execute` contract this package
+ * owns.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class FlowCycleDetected extends FlowCycleDetected_base {
+}
+export {};
+//# sourceMappingURL=FlowCycleDetected.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FlowCycleDetected.d.ts","sourceRoot":"","sources":["../../../src/FlowRuntime/FlowCycleDetected.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;;IAsBnC,gCAAgC;;IAKhC,oEAAoE;;;AAzBxE;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,iBAAkB,SAAQ,sBAWtC;CAAG"}

package/dist/cjs/FlowRuntime/FlowCycleDetected.js

@@ -0,0 +1,49 @@
+"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 FlowCycleDetected_exports = {};
+__export(FlowCycleDetected_exports, {
+  FlowCycleDetected: () => FlowCycleDetected
+});
+module.exports = __toCommonJS(FlowCycleDetected_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+class FlowCycleDetected extends Schema.TaggedError()(
+  "@smthrs/flow/FlowCycleDetected",
+  {
+    /** Stable public error code. */
+    // This wire shape freezes at 1.0.0-rc.0.
+    code: Schema.Literal("flow_cycle_detected").pipe(
+      Schema.withConstructorDefault(Effect.succeed("flow_cycle_detected"))
+    ),
+    /** Ordered execution ids from the cycle's target back to itself. */
+    path: Schema.Array(Schema.String)
+  }
+) {
+}
+//# sourceMappingURL=FlowCycleDetected.js.map

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": []
+}