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

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

@@ -0,0 +1,204 @@
+/**
+ * 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 { InterpreterError } from "../Interpreter.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.
+     *
+     * Unknown ids and ids belonging to another flow are ignored. The caller's
+     * authority, intersected with the host and flow ceilings, must cover the
+     * authority recorded at admission; otherwise cancellation is refused with
+     * an execution identity conflict defect, before changing the run.
+     *
+     * 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, InterpreterError, 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 { InterpreterError } from \"../Interpreter.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     * Unknown ids and ids belonging to another flow are ignored. The caller's\n     * authority, intersected with the host and flow ceilings, must cover the\n     * authority recorded at admission; otherwise cancellation is refused with\n     * an execution identity conflict defect, before changing the run.\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, InterpreterError, 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;AAqDlB,MAAM,oBAAoB,QAAQ,QAqQvC,EAAE,sCAAsC,EAAE;AAAC;",
+  "names": []
+}

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

@@ -0,0 +1,177 @@
+/**
+ * What a driven graph tells its runtime about itself.
+ *
+ * The interpreter knows the whole plan before the first action runs, and it
+ * knows when each node is scheduled and how each one settled. Nothing
+ * downstream can derive those facts: an attempt record carries a step key and
+ * no node id, so a monitor reading a journal can see the work and not the
+ * graph it belongs to. These records are the missing half, and this module is
+ * the only thing `@smthrs/flow` says about them — the port takes them, and an
+ * engine with a journal is what turns them into durable records. A runtime
+ * without one keeps its no-op and the interpreter is unchanged.
+ *
+ * Every record carries its own `sourceId`, and that is the replay-stability
+ * contract: a resumed walk rebuilds the same graph and re-derives the same
+ * ids, so a journal keyed by `(run, source, sequence)` collapses the second
+ * observation onto the first row instead of recording the node twice.
+ *
+ * @since 1.0.0
+ */
+import type * as Plan from "@smthrs/plan/Plan";
+import type { DeclaredAt } from "../internal/DeclarationSite.ts";
+/**
+ * One node of the graph a run was driven from.
+ *
+ * `tier` and `effects` are the declaration's own, and `dependsOn` is the
+ * material dependency set the plan compiles edges from. `action` is the tag a
+ * node dispatches, absent on every node that dispatches nothing. `declaredAt`
+ * is provenance and never identity: it is outside key material by
+ * construction, so adding it re-keys nothing.
+ *
+ * A node whose dependency list is wider than one page appears on several,
+ * each carrying the next DISJOINT slice of `dependsOn` and everything else
+ * unchanged. A reader assembles pages in order and unions `dependsOn` per id;
+ * keeping only the last summary would read a thousand-way fan-in as a node
+ * with two dependencies.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface NodeSummary {
+    readonly id: string;
+    readonly kind: string;
+    readonly dependsOn: ReadonlyArray<string>;
+    readonly tier: "sealed" | "compensable" | "irreversible";
+    readonly action?: string | undefined;
+    readonly effects?: Plan.NodeEffects | undefined;
+    readonly declaredAt?: DeclaredAt | undefined;
+}
+/**
+ * One edge of the graph, with the reason the builder drew it.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface EdgeSummary {
+    readonly from: string;
+    readonly to: string;
+    readonly reason: "value" | "continuation" | "failure";
+}
+/**
+ * How a node left the walk.
+ *
+ * `built` ran, `clean` was served entirely from durable records, `failed`
+ * raised, and `skipped` is a node the walk never reached — an untaken branch
+ * arm, or a dependent of something that failed.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export type NodeOutcome = "built" | "clean" | "failed" | "skipped";
+/**
+ * The graph a run is about to be driven from, or one page of it.
+ *
+ * A large plan is paged rather than truncated: the first page is the plan
+ * record and the rest are appended subgraphs, because a journal entry has a
+ * byte bound and a projection that clips one loses nodes silently. Nothing
+ * about one node has to fit one page — its summary, its dependency list and
+ * the edges that end on it may each run onto the next — so a page's `nodes`
+ * and `edges` are a SLICE of the graph and only the assembled pages are the
+ * whole of it.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface PlanRecorded {
+    readonly _tag: "PlanRecorded";
+    /** Whole-graph identity; absent only on records from older producers. */
+    readonly digest?: string | undefined;
+    readonly sourceId: string;
+    readonly flow: string;
+    readonly generation: number;
+    readonly page: number;
+    readonly pages: number;
+    /** Every node of the whole graph, not of this page. */
+    readonly nodeCount: number;
+    readonly nodes: ReadonlyArray<NodeSummary>;
+    readonly edges: ReadonlyArray<EdgeSummary>;
+}
+/**
+ * A page of a graph too large for one record.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface SubgraphAppended {
+    readonly _tag: "SubgraphAppended";
+    readonly sourceId: string;
+    readonly flow: string;
+    readonly generation: number;
+    readonly page: number;
+    readonly pages: number;
+    readonly nodes: ReadonlyArray<NodeSummary>;
+    readonly edges: ReadonlyArray<EdgeSummary>;
+}
+/**
+ * A node the walk is about to compute.
+ *
+ * `attempt` is the walk's, and it is always 1: the interpreter settles each
+ * node once. No step key digest rides here, because none exists yet — the
+ * engine allocates a dispatch's ordinal when the dispatch happens, which is
+ * after this record is written. The digests arrive on {@link NodeSettled}.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface NodeScheduled {
+    readonly _tag: "NodeScheduled";
+    readonly sourceId: string;
+    readonly nodeId: string;
+    readonly kind: string;
+    readonly attempt: number;
+    readonly action?: string | undefined;
+}
+/**
+ * A node that reached an outcome.
+ *
+ * `attempts` is the highest durable attempt any of this node's dispatches ran
+ * as, and 1 for a node that dispatched nothing. It is the engine's count, not
+ * the walk's: the interpreter settles each node once, and a retry happens
+ * underneath it inside one dispatch, so a node whose action failed and was
+ * retried says two.
+ *
+ * `stepKeyDigests` names the dispatches this node drove, in the order they
+ * were first reported and without repeats — a retried dispatch keeps one step
+ * key, because the attempt is folded into no key. It is the join a monitor
+ * could not make before: `flows.engine.attempt-started` carries a step key
+ * digest and no node id, so an attempt row belongs to the node that claims
+ * its digest. A node that dispatches nothing claims none, and a runtime that
+ * derives no digests reports an empty list.
+ *
+ * `value` is what the node settled with — the success value for `built` and
+ * `clean`, the typed failure for `failed` — handed over whole and unbounded.
+ * It is NOT a summary: bounding and redacting it belongs to the writer that
+ * knows where it is going, because a durable row has a byte budget and a
+ * credential redactor and an in-memory monitor has neither.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface NodeSettled {
+    readonly _tag: "NodeSettled";
+    readonly sourceId: string;
+    readonly nodeId: string;
+    readonly outcome: NodeOutcome;
+    readonly attempts: number;
+    readonly action?: string | undefined;
+    readonly stepKeyDigests: ReadonlyArray<string>;
+    readonly value?: unknown;
+}
+/**
+ * Everything a walk can tell its runtime.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export type NodeRecord = PlanRecorded | SubgraphAppended | NodeScheduled | NodeSettled;
+//# sourceMappingURL=NodeRecord.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NodeRecord.d.ts","sourceRoot":"","sources":["../../../src/FlowRuntime/NodeRecord.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,KAAK,IAAI,MAAM,mBAAmB,CAAA;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAEhE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACzC,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,aAAa,GAAG,cAAc,CAAA;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,WAAW,GAAG,SAAS,CAAA;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAA;CAC7C;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAAA;CACtD;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAA;AAElE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;IAC1C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;CAC3C;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;IAC1C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;CAC3C;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACzB;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,gBAAgB,GAAG,aAAa,GAAG,WAAW,CAAA"}

package/dist/cjs/FlowRuntime/NodeRecord.js

@@ -0,0 +1,17 @@
+"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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var NodeRecord_exports = {};
+module.exports = __toCommonJS(NodeRecord_exports);
+//# sourceMappingURL=NodeRecord.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/FlowRuntime/NodeRecord.ts"],
+  "sourcesContent": ["/**\n * What a driven graph tells its runtime about itself.\n *\n * The interpreter knows the whole plan before the first action runs, and it\n * knows when each node is scheduled and how each one settled. Nothing\n * downstream can derive those facts: an attempt record carries a step key and\n * no node id, so a monitor reading a journal can see the work and not the\n * graph it belongs to. These records are the missing half, and this module is\n * the only thing `@smthrs/flow` says about them \u2014 the port takes them, and an\n * engine with a journal is what turns them into durable records. A runtime\n * without one keeps its no-op and the interpreter is unchanged.\n *\n * Every record carries its own `sourceId`, and that is the replay-stability\n * contract: a resumed walk rebuilds the same graph and re-derives the same\n * ids, so a journal keyed by `(run, source, sequence)` collapses the second\n * observation onto the first row instead of recording the node twice.\n *\n * @since 1.0.0\n */\n\nimport type * as Plan from \"@smthrs/plan/Plan\"\nimport type { DeclaredAt } from \"../internal/DeclarationSite.ts\"\n\n/**\n * One node of the graph a run was driven from.\n *\n * `tier` and `effects` are the declaration's own, and `dependsOn` is the\n * material dependency set the plan compiles edges from. `action` is the tag a\n * node dispatches, absent on every node that dispatches nothing. `declaredAt`\n * is provenance and never identity: it is outside key material by\n * construction, so adding it re-keys nothing.\n *\n * A node whose dependency list is wider than one page appears on several,\n * each carrying the next DISJOINT slice of `dependsOn` and everything else\n * unchanged. A reader assembles pages in order and unions `dependsOn` per id;\n * keeping only the last summary would read a thousand-way fan-in as a node\n * with two dependencies.\n *\n * @since 1.0.0\n * @category models\n */\nexport interface NodeSummary {\n  readonly id: string\n  readonly kind: string\n  readonly dependsOn: ReadonlyArray<string>\n  readonly tier: \"sealed\" | \"compensable\" | \"irreversible\"\n  readonly action?: string | undefined\n  readonly effects?: Plan.NodeEffects | undefined\n  readonly declaredAt?: DeclaredAt | undefined\n}\n\n/**\n * One edge of the graph, with the reason the builder drew it.\n *\n * @since 1.0.0\n * @category models\n */\nexport interface EdgeSummary {\n  readonly from: string\n  readonly to: string\n  readonly reason: \"value\" | \"continuation\" | \"failure\"\n}\n\n/**\n * How a node left the walk.\n *\n * `built` ran, `clean` was served entirely from durable records, `failed`\n * raised, and `skipped` is a node the walk never reached \u2014 an untaken branch\n * arm, or a dependent of something that failed.\n *\n * @since 1.0.0\n * @category models\n */\nexport type NodeOutcome = \"built\" | \"clean\" | \"failed\" | \"skipped\"\n\n/**\n * The graph a run is about to be driven from, or one page of it.\n *\n * A large plan is paged rather than truncated: the first page is the plan\n * record and the rest are appended subgraphs, because a journal entry has a\n * byte bound and a projection that clips one loses nodes silently. Nothing\n * about one node has to fit one page \u2014 its summary, its dependency list and\n * the edges that end on it may each run onto the next \u2014 so a page's `nodes`\n * and `edges` are a SLICE of the graph and only the assembled pages are the\n * whole of it.\n *\n * @since 1.0.0\n * @category models\n */\nexport interface PlanRecorded {\n  readonly _tag: \"PlanRecorded\"\n  /** Whole-graph identity; absent only on records from older producers. */\n  readonly digest?: string | undefined\n  readonly sourceId: string\n  readonly flow: string\n  readonly generation: number\n  readonly page: number\n  readonly pages: number\n  /** Every node of the whole graph, not of this page. */\n  readonly nodeCount: number\n  readonly nodes: ReadonlyArray<NodeSummary>\n  readonly edges: ReadonlyArray<EdgeSummary>\n}\n\n/**\n * A page of a graph too large for one record.\n *\n * @since 1.0.0\n * @category models\n */\nexport interface SubgraphAppended {\n  readonly _tag: \"SubgraphAppended\"\n  readonly sourceId: string\n  readonly flow: string\n  readonly generation: number\n  readonly page: number\n  readonly pages: number\n  readonly nodes: ReadonlyArray<NodeSummary>\n  readonly edges: ReadonlyArray<EdgeSummary>\n}\n\n/**\n * A node the walk is about to compute.\n *\n * `attempt` is the walk's, and it is always 1: the interpreter settles each\n * node once. No step key digest rides here, because none exists yet \u2014 the\n * engine allocates a dispatch's ordinal when the dispatch happens, which is\n * after this record is written. The digests arrive on {@link NodeSettled}.\n *\n * @since 1.0.0\n * @category models\n */\nexport interface NodeScheduled {\n  readonly _tag: \"NodeScheduled\"\n  readonly sourceId: string\n  readonly nodeId: string\n  readonly kind: string\n  readonly attempt: number\n  readonly action?: string | undefined\n}\n\n/**\n * A node that reached an outcome.\n *\n * `attempts` is the highest durable attempt any of this node's dispatches ran\n * as, and 1 for a node that dispatched nothing. It is the engine's count, not\n * the walk's: the interpreter settles each node once, and a retry happens\n * underneath it inside one dispatch, so a node whose action failed and was\n * retried says two.\n *\n * `stepKeyDigests` names the dispatches this node drove, in the order they\n * were first reported and without repeats \u2014 a retried dispatch keeps one step\n * key, because the attempt is folded into no key. It is the join a monitor\n * could not make before: `flows.engine.attempt-started` carries a step key\n * digest and no node id, so an attempt row belongs to the node that claims\n * its digest. A node that dispatches nothing claims none, and a runtime that\n * derives no digests reports an empty list.\n *\n * `value` is what the node settled with \u2014 the success value for `built` and\n * `clean`, the typed failure for `failed` \u2014 handed over whole and unbounded.\n * It is NOT a summary: bounding and redacting it belongs to the writer that\n * knows where it is going, because a durable row has a byte budget and a\n * credential redactor and an in-memory monitor has neither.\n *\n * @since 1.0.0\n * @category models\n */\nexport interface NodeSettled {\n  readonly _tag: \"NodeSettled\"\n  readonly sourceId: string\n  readonly nodeId: string\n  readonly outcome: NodeOutcome\n  readonly attempts: number\n  readonly action?: string | undefined\n  readonly stepKeyDigests: ReadonlyArray<string>\n  readonly value?: unknown\n}\n\n/**\n * Everything a walk can tell its runtime.\n *\n * @since 1.0.0\n * @category models\n */\nexport type NodeRecord = PlanRecorded | SubgraphAppended | NodeScheduled | NodeSettled\n"],
+  "mappings": ";;;;;;;;;;;;;;AAAA;AAAA;",
+  "names": []
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Declares how a flow is about to wait before it suspends.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { FlowInstance } from "./FlowInstance.ts";
+/**
+ * The waiting classification a flow can declare before suspending.
+ *
+ * Mirrors the durable store's waiting payload: `reason` is the supervisor
+ * vocabulary (`approval`, `event`, `timer`, `quota`, or a plugin-defined
+ * reason), `wakeAt` an absolute deadline, and `token` compare-and-swap
+ * material a wake handler matches against.
+ *
+ * `request` is what the wait declares ABOUT itself, as JSON text, for a reader
+ * rather than for a matcher: the question a `HumanTask` is parked on, its
+ * kind, and its attempt budget. Nothing routes on it. It exists because `reason` and `token`
+ * say only that a person owes the run an answer and which wait point holds it,
+ * so an approvals inbox reading a parked run could name the gate and never
+ * state the question — which is what left run-3's `coding-clarification`
+ * unanswerable.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface WaitingAnnotation {
+    readonly reason: string;
+    readonly wakeAt?: number | undefined;
+    readonly token?: string | undefined;
+    readonly request?: string | undefined;
+}
+/**
+ * Schema for {@link WaitingAnnotation}, the one encodable spelling of the
+ * waiting vocabulary. `Flow.Park` carries it so a parking request and the
+ * annotation that precedes a suspension cannot describe different waits.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const WaitingAnnotation: Schema.Struct<{
+    readonly reason: Schema.String;
+    readonly wakeAt: Schema.optional<Schema.Number>;
+    readonly token: Schema.optional<Schema.String>;
+    readonly request: Schema.optional<Schema.String>;
+}>;
+/**
+ * Declares how the flow is about to wait, so a durable driver parks the run
+ * with that reason and token instead of the derived `timer`/`event` default.
+ *
+ * The annotation is scoped to the wait it precedes: once the awaited
+ * deferred passes through with a persisted result — including replays after
+ * the wait resolved — the declared classification is consumed, so a later
+ * suspension parks under its own reason (and keeps its timer `wakeAt`)
+ * instead of the stale one (issue #42).
+ *
+ * Call it immediately before awaiting the deferred that models the wait:
+ *
+ * ```ts
+ * yield* FlowRuntime.annotateWaiting({ reason: "approval", token: requestId })
+ * const decision = yield* DurableDeferred.await(approvalGate)
+ * ```
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export declare const annotateWaiting: (waiting: WaitingAnnotation | undefined) => Effect.Effect<void, never, FlowInstance>;
+//# sourceMappingURL=WaitingAnnotation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WaitingAnnotation.d.ts","sourceRoot":"","sources":["../../../src/FlowRuntime/WaitingAnnotation.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAEhD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACtC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB;;;;;EAU5B,CAAA;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe,GAC1B,SAAS,iBAAiB,GAAG,SAAS,KACrC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,YAAY,CAItC,CAAA"}

package/dist/cjs/FlowRuntime/WaitingAnnotation.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 WaitingAnnotation_exports = {};
+__export(WaitingAnnotation_exports, {
+  WaitingAnnotation: () => WaitingAnnotation,
+  annotateWaiting: () => annotateWaiting
+});
+module.exports = __toCommonJS(WaitingAnnotation_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var import_FlowInstance = require("./FlowInstance.js");
+const WaitingAnnotation = Schema.Struct({
+  reason: Schema.String,
+  wakeAt: Schema.optional(Schema.Number),
+  token: Schema.optional(Schema.String),
+  // JSON TEXT, not a decoded value. `Flow.Park` carries this struct, and a
+  // recursive `Json` schema here pushed `Flow.Outcome`'s inference past
+  // TypeScript's instantiation depth; a string also keeps one spelling of the
+  // question from the declaring flow all the way to the durable column, which
+  // stores exactly this text under a `json_valid` check.
+  request: Schema.optional(Schema.String)
+});
+const annotateWaiting = (waiting) => Effect.gen(function* () {
+  const instance = yield* import_FlowInstance.FlowInstance;
+  instance.waiting = waiting;
+});
+//# sourceMappingURL=WaitingAnnotation.js.map