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

package/dist/esm/FlowRuntime/FlowRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlowRuntime.js","sourceRoot":"","sources":["../../../src/FlowRuntime/FlowRuntime.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AA4CzC;;;;;;;GAOG;AACH,MAAM,OAAO,WAAY,SAAQ,OAAO,CAAC,OAAO,EAgQ7C,CAAC,sCAAsC,CAAC;CAAG","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` — written against this port, one level up — 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"]}

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

@@ -0,0 +1,175 @@
+/**
+ * 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";
+    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/esm/FlowRuntime/NodeRecord.d.ts.map

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

package/dist/esm/FlowRuntime/NodeRecord.js

@@ -0,0 +1,21 @@
+/**
+ * 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
+ */
+export {};
+//# sourceMappingURL=NodeRecord.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NodeRecord.js","sourceRoot":"","sources":["../../../src/FlowRuntime/NodeRecord.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG","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 — 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 — 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 — its summary, its dependency list and\n * the edges that end on it may each run onto the next — 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  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 — 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 — 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 — the success value for `built` and\n * `clean`, the typed failure for `failed` — 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"]}

package/dist/esm/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/esm/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/esm/FlowRuntime/WaitingAnnotation.js

@@ -0,0 +1,53 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+/**
+ * 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.js";
+/**
+ * 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 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)
+});
+/**
+ * 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 const annotateWaiting = (waiting) => Effect.gen(function* () {
+    const instance = yield* FlowInstance;
+    instance.waiting = waiting;
+});
+//# sourceMappingURL=WaitingAnnotation.js.map

package/dist/esm/FlowRuntime/WaitingAnnotation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WaitingAnnotation.js","sourceRoot":"","sources":["../../../src/FlowRuntime/WaitingAnnotation.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD;;;;GAIG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AA4BhD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC,MAAM;IACrB,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACtC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACrC,yEAAyE;IACzE,sEAAsE;IACtE,4EAA4E;IAC5E,4EAA4E;IAC5E,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;CACxC,CAAC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,OAAsC,EACI,EAAE,CAC5C,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,YAAY,CAAA;IACpC,QAAQ,CAAC,OAAO,GAAG,OAAO,CAAA;AAC5B,CAAC,CAAC,CAAA","sourcesContent":["// Deep reviewed and polished by a human on 2026-08-10.\n\n/**\n * Declares how a flow is about to wait before it suspends.\n *\n * @since 0.1.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\nimport { FlowInstance } from \"./FlowInstance.ts\"\n\n/**\n * The waiting classification a flow can declare before suspending.\n *\n * Mirrors the durable store's waiting payload: `reason` is the supervisor\n * vocabulary (`approval`, `event`, `timer`, `quota`, or a plugin-defined\n * reason), `wakeAt` an absolute deadline, and `token` compare-and-swap\n * material a wake handler matches against.\n *\n * `request` is what the wait declares ABOUT itself, as JSON text, for a reader\n * rather than for a matcher: the question a `HumanTask` is parked on, its\n * kind, and its attempt budget. Nothing routes on it. It exists because `reason` and `token`\n * say only that a person owes the run an answer and which wait point holds it,\n * so an approvals inbox reading a parked run could name the gate and never\n * state the question — which is what left run-3's `coding-clarification`\n * unanswerable.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface WaitingAnnotation {\n  readonly reason: string\n  readonly wakeAt?: number | undefined\n  readonly token?: string | undefined\n  readonly request?: string | undefined\n}\n\n/**\n * Schema for {@link WaitingAnnotation}, the one encodable spelling of the\n * waiting vocabulary. `Flow.Park` carries it so a parking request and the\n * annotation that precedes a suspension cannot describe different waits.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const WaitingAnnotation = Schema.Struct({\n  reason: Schema.String,\n  wakeAt: Schema.optional(Schema.Number),\n  token: Schema.optional(Schema.String),\n  // JSON TEXT, not a decoded value. `Flow.Park` carries this struct, and a\n  // recursive `Json` schema here pushed `Flow.Outcome`'s inference past\n  // TypeScript's instantiation depth; a string also keeps one spelling of the\n  // question from the declaring flow all the way to the durable column, which\n  // stores exactly this text under a `json_valid` check.\n  request: Schema.optional(Schema.String)\n})\n\n/**\n * Declares how the flow is about to wait, so a durable driver parks the run\n * with that reason and token instead of the derived `timer`/`event` default.\n *\n * The annotation is scoped to the wait it precedes: once the awaited\n * deferred passes through with a persisted result — including replays after\n * the wait resolved — the declared classification is consumed, so a later\n * suspension parks under its own reason (and keeps its timer `wakeAt`)\n * instead of the stale one (issue #42).\n *\n * Call it immediately before awaiting the deferred that models the wait:\n *\n * ```ts\n * yield* FlowRuntime.annotateWaiting({ reason: \"approval\", token: requestId })\n * const decision = yield* DurableDeferred.await(approvalGate)\n * ```\n *\n * @category combinators\n * @since 0.1.0\n */\nexport const annotateWaiting = (\n  waiting: WaitingAnnotation | undefined\n): Effect.Effect<void, never, FlowInstance> =>\n  Effect.gen(function*() {\n    const instance = yield* FlowInstance\n    instance.waiting = waiting\n  })\n"]}

package/dist/esm/FlowRuntime/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The runtime port: the execution contract flow authoring APIs require.
+ *
+ * @since 0.1.0
+ */
+export * from "./CancelRequestFailed.ts";
+export * from "./FlowCycleDetected.ts";
+export * from "./FlowExecutionNotFound.ts";
+export * from "./FlowInstance.ts";
+export * from "./FlowRuntime.ts";
+export * from "./NodeRecord.ts";
+export * from "./WaitingAnnotation.ts";
+export * from "./ExecutionIdentityConflict.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/FlowRuntime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/FlowRuntime/index.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,cAAc,0BAA0B,CAAA;AACxC,cAAc,wBAAwB,CAAA;AACtC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,mBAAmB,CAAA;AACjC,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,wBAAwB,CAAA;AAEtC,cAAc,gCAAgC,CAAA"}

package/dist/esm/FlowRuntime/index.js

@@ -0,0 +1,15 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+/**
+ * The runtime port: the execution contract flow authoring APIs require.
+ *
+ * @since 0.1.0
+ */
+export * from "./CancelRequestFailed.js";
+export * from "./FlowCycleDetected.js";
+export * from "./FlowExecutionNotFound.js";
+export * from "./FlowInstance.js";
+export * from "./FlowRuntime.js";
+export * from "./NodeRecord.js";
+export * from "./WaitingAnnotation.js";
+export * from "./ExecutionIdentityConflict.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/FlowRuntime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/FlowRuntime/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD;;;;GAIG;AAEH,cAAc,0BAA0B,CAAA;AACxC,cAAc,wBAAwB,CAAA;AACtC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,mBAAmB,CAAA;AACjC,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,wBAAwB,CAAA;AAEtC,cAAc,gCAAgC,CAAA","sourcesContent":["// Deep reviewed and polished by a human on 2026-08-10.\n\n/**\n * The runtime port: the execution contract flow authoring APIs require.\n *\n * @since 0.1.0\n */\n\nexport * from \"./CancelRequestFailed.ts\"\nexport * from \"./FlowCycleDetected.ts\"\nexport * from \"./FlowExecutionNotFound.ts\"\nexport * from \"./FlowInstance.ts\"\nexport * from \"./FlowRuntime.ts\"\nexport * from \"./NodeRecord.ts\"\nexport * from \"./WaitingAnnotation.ts\"\n\nexport * from \"./ExecutionIdentityConflict.ts\"\n"]}