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

package/dist/cjs/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/cjs/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/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  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

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/FlowRuntime/WaitingAnnotation.ts"],
+  "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 \u2014 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 \u2014 including replays after\n * the wait resolved \u2014 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"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAQA,aAAwB;AACxB,aAAwB;AACxB,0BAA6B;AAoCtB,MAAM,oBAAoB,OAAO,OAAO;AAAA,EAC7C,QAAQ,OAAO;AAAA,EACf,QAAQ,OAAO,SAAS,OAAO,MAAM;AAAA,EACrC,OAAO,OAAO,SAAS,OAAO,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMpC,SAAS,OAAO,SAAS,OAAO,MAAM;AACxC,CAAC;AAsBM,MAAM,kBAAkB,CAC7B,YAEA,OAAO,IAAI,aAAY;AACrB,QAAM,WAAW,OAAO;AACxB,WAAS,UAAU;AACrB,CAAC;",
+  "names": []
+}

package/dist/cjs/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/cjs/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/cjs/FlowRuntime/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var FlowRuntime_exports = {};
+module.exports = __toCommonJS(FlowRuntime_exports);
+__reExport(FlowRuntime_exports, require("./CancelRequestFailed.js"), module.exports);
+__reExport(FlowRuntime_exports, require("./FlowCycleDetected.js"), module.exports);
+__reExport(FlowRuntime_exports, require("./FlowExecutionNotFound.js"), module.exports);
+__reExport(FlowRuntime_exports, require("./FlowInstance.js"), module.exports);
+__reExport(FlowRuntime_exports, require("./FlowRuntime.js"), module.exports);
+__reExport(FlowRuntime_exports, require("./NodeRecord.js"), module.exports);
+__reExport(FlowRuntime_exports, require("./WaitingAnnotation.js"), module.exports);
+__reExport(FlowRuntime_exports, require("./ExecutionIdentityConflict.js"), module.exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/FlowRuntime/index.ts"],
+  "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"],
+  "mappings": ";;;;;;;;;;;;;;;AAAA;AAAA;AAQA,gCAAc,qCARd;AASA,gCAAc,mCATd;AAUA,gCAAc,uCAVd;AAWA,gCAAc,8BAXd;AAYA,gCAAc,6BAZd;AAaA,gCAAc,4BAbd;AAcA,gCAAc,mCAdd;AAgBA,gCAAc,2CAhBd;",
+  "names": []
+}