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

package/dist/esm/WaitFor.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The system wait point, as an ordinary declared action.
+ *
+ * `docs/concepts/flows-and-actions.md` names wait-for-event the
+ * other half of the timer gap and says how to close it: ship it over the
+ * existing `DurableDeferred`, so an external signal is a visible, keyed plan
+ * node. That is this module. {@link action} is a plain `Action.make`
+ * declaration — catalogable, `.call()`-able, one node in the built plan — and
+ * {@link layer} is the implementation.
+ *
+ * Nothing about resolution is new. The wait is a `DurableDeferred`, so whoever
+ * satisfies it completes it the way every other durable deferred is completed:
+ * a token, and `DurableDeferred.succeed`, `fail`, `failCause`, or `done`.
+ * {@link deferred} is how a resolver names the same wait point the action
+ * awaits. The park is declared through the ordinary waiting vocabulary
+ * ({@link module:WaitingAnnotation.annotateWaiting}) under `event`, carrying
+ * that token as the compare-and-swap material a wake handler matches. Replay is
+ * the deferred's: once a result is recorded, a re-driven round reads it and
+ * runs through instead of parking again.
+ *
+ * @since 0.1.0
+ */
+import type * as Crypto from "effect/Crypto";
+import type * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Action from "./Action/index.ts";
+import * as DurableDeferred from "./DurableDeferred.ts";
+import type { FlowRuntime } from "./FlowRuntime/FlowRuntime.ts";
+declare const WaitForRequestInvalid_base: Schema.Class<WaitForRequestInvalid, Schema.TaggedStruct<"@smthrs/flow/WaitForRequestInvalid", {
+    readonly code: Schema.Literals<readonly ["missing_target", "ambiguous_target", "malformed_token", "foreign_execution"]>;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A wait whose payload does not name exactly one reachable wait point.
+ *
+ * A payload names the wait point by `name`, relative to the running execution,
+ * or by an absolute `token`. Naming both, or neither, leaves nothing to await;
+ * a token that does not parse names nothing either; and a token addressed to a
+ * different flow or a different execution names a wait point this execution
+ * cannot observe, because a durable deferred result is recorded against the
+ * flow and execution that own it.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class WaitForRequestInvalid extends WaitForRequestInvalid_base {
+}
+/**
+ * The tag the wait declaration is catalogued and resolved under.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const tag = "system/wait-for";
+/**
+ * The durable deferred a named wait point resolves through.
+ *
+ * This is the resolver's half of {@link action}: the value to hand
+ * `DurableDeferred.tokenFromExecutionId` and `DurableDeferred.succeed`, so a
+ * wait that a body declared by name is completed through the existing deferred
+ * completion path rather than a second one.
+ *
+ * ```ts
+ * const gate = WaitFor.deferred("approval")
+ * const token = DurableDeferred.tokenFromExecutionId(gate, { flow, executionId })
+ * yield* DurableDeferred.succeed(gate, { token, value: { approved: true } })
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const deferred: (name: string) => DurableDeferred.DurableDeferred<typeof Schema.Json>;
+/**
+ * The declared wait action: a wait point named by `name` or by `token`.
+ *
+ * **When to use**
+ *
+ * Use it in a body wherever a round has to wait for something outside the run —
+ * an approval, a webhook, a human — `WaitFor.action.call({ name: "approval"
+ * })`. The node settles with whatever value resolved the wait, so downstream
+ * steps read it the way they read any other step result.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const action: Action.Declared<typeof tag, Schema.Struct<{
+    readonly token: Schema.optional<Schema.String>;
+    readonly name: Schema.optional<Schema.String>;
+}>, typeof Schema.Json, typeof WaitForRequestInvalid, never>;
+/**
+ * The wait implementation: park under `event` with the wake token, and settle
+ * with the value that resolved the wait.
+ *
+ * Provide it beside the other action implementation layers a body calls, over
+ * the {@link module:Implementations.layerImplementations} table they file
+ * themselves in:
+ *
+ * ```ts
+ * Layer.mergeAll(WaitFor.layer, Interpreter.layer(Pipeline)).pipe(
+ *   Layer.provideMerge(Action.layerImplementations)
+ * )
+ * ```
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<never, never, Crypto.Crypto | FlowRuntime>;
+export {};
+//# sourceMappingURL=WaitFor.d.ts.map

package/dist/esm/WaitFor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WaitFor.d.ts","sourceRoot":"","sources":["../../src/WaitFor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAE5C,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAA;AAC3C,OAAO,KAAK,eAAe,MAAM,sBAAsB,CAAA;AAEvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAA;;;;;AAG/D;;;;;;;;;;;;GAYG;AACH,qBAAa,qBAAsB,SAAQ,0BAW1C;CAAG;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,GAAG,oBAAoB,CAAA;AAEpC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,KAAG,eAAe,CAAC,eAAe,CAAC,OAAO,MAAM,CAAC,IAAI,CACvB,CAAA;AAEnE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,QAAQ,CAClC,OAAO,GAAG,EACV,MAAM,CAAC,MAAM,CAAC;IACZ,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;CAC9C,CAAC,EACF,OAAO,MAAM,CAAC,IAAI,EAClB,OAAO,qBAAqB,EAC5B,KAAK,CASL,CAAA;AAkFF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,GAAG,WAAW,CAWxE,CAAA"}

package/dist/esm/WaitFor.js

@@ -0,0 +1,184 @@
+/**
+ * The system wait point, as an ordinary declared action.
+ *
+ * `docs/concepts/flows-and-actions.md` names wait-for-event the
+ * other half of the timer gap and says how to close it: ship it over the
+ * existing `DurableDeferred`, so an external signal is a visible, keyed plan
+ * node. That is this module. {@link action} is a plain `Action.make`
+ * declaration — catalogable, `.call()`-able, one node in the built plan — and
+ * {@link layer} is the implementation.
+ *
+ * Nothing about resolution is new. The wait is a `DurableDeferred`, so whoever
+ * satisfies it completes it the way every other durable deferred is completed:
+ * a token, and `DurableDeferred.succeed`, `fail`, `failCause`, or `done`.
+ * {@link deferred} is how a resolver names the same wait point the action
+ * awaits. The park is declared through the ordinary waiting vocabulary
+ * ({@link module:WaitingAnnotation.annotateWaiting}) under `event`, carrying
+ * that token as the compare-and-swap material a wake handler matches. Replay is
+ * the deferred's: once a result is recorded, a re-driven round reads it and
+ * runs through instead of parking again.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Action from "./Action/index.js";
+import * as DurableDeferred from "./DurableDeferred.js";
+import { FlowInstance } from "./FlowRuntime/FlowInstance.js";
+import { annotateWaiting } from "./FlowRuntime/WaitingAnnotation.js";
+/**
+ * A wait whose payload does not name exactly one reachable wait point.
+ *
+ * A payload names the wait point by `name`, relative to the running execution,
+ * or by an absolute `token`. Naming both, or neither, leaves nothing to await;
+ * a token that does not parse names nothing either; and a token addressed to a
+ * different flow or a different execution names a wait point this execution
+ * cannot observe, because a durable deferred result is recorded against the
+ * flow and execution that own it.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class WaitForRequestInvalid extends Schema.TaggedError()("@smthrs/flow/WaitForRequestInvalid", {
+    code: Schema.Literals([
+        "missing_target",
+        "ambiguous_target",
+        "malformed_token",
+        "foreign_execution"
+    ]),
+    message: Schema.String
+}) {
+}
+/**
+ * The tag the wait declaration is catalogued and resolved under.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const tag = "system/wait-for";
+/**
+ * The durable deferred a named wait point resolves through.
+ *
+ * This is the resolver's half of {@link action}: the value to hand
+ * `DurableDeferred.tokenFromExecutionId` and `DurableDeferred.succeed`, so a
+ * wait that a body declared by name is completed through the existing deferred
+ * completion path rather than a second one.
+ *
+ * ```ts
+ * const gate = WaitFor.deferred("approval")
+ * const token = DurableDeferred.tokenFromExecutionId(gate, { flow, executionId })
+ * yield* DurableDeferred.succeed(gate, { token, value: { approved: true } })
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const deferred = (name) => DurableDeferred.make(`WaitFor/${name}`, { success: Schema.Json });
+/**
+ * The declared wait action: a wait point named by `name` or by `token`.
+ *
+ * **When to use**
+ *
+ * Use it in a body wherever a round has to wait for something outside the run —
+ * an approval, a webhook, a human — `WaitFor.action.call({ name: "approval"
+ * })`. The node settles with whatever value resolved the wait, so downstream
+ * steps read it the way they read any other step result.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const action = Action.makeSystem(tag, {
+    payload: {
+        token: Schema.optional(Schema.String),
+        name: Schema.optional(Schema.String)
+    },
+    success: Schema.Json,
+    error: WaitForRequestInvalid,
+    tier: "sealed"
+});
+/**
+ * The deferred name a token addresses, refused when the token does not parse.
+ *
+ * @private
+ */
+const parseToken = (token) => Effect.mapError(DurableDeferred.TokenParsed.parse(token), (error) => new WaitForRequestInvalid({
+    code: "malformed_token",
+    message: `${tag} was called with a token that is not a durable deferred token. ${error.message}`
+}));
+/**
+ * The wait point a payload names, resolved against the running execution.
+ *
+ * DECIDED: a payload names EXACTLY one of `name`
+ * and `token`, and a token must address the execution that is waiting. A
+ * deferred result is recorded against (flow name, execution id, deferred name)
+ * and read back the same way, so awaiting a foreign token would park forever
+ * while the value it names was recorded elsewhere; refusing it names the
+ * mistake instead. BOTH halves of the owning execution's identity are compared:
+ * a token carries its own flow name, so a same-execution token minted for
+ * another flow completes under that flow while this one reads under its own,
+ * which is the same permanent park by a different route.
+ *
+ * DECIDED: a wait point is addressed by the
+ * PAYLOAD, and the per-dispatch identity {@link module:Sleep} derives its clock
+ * from is deliberately NOT applied here. A wait is a rendezvous with something
+ * outside the run, and a resolver has to name the same wait point to complete
+ * it, so the name is the author's and two calls naming one wait point await one
+ * fact — which is the intended reading, not an aliasing bug. A sleep has no
+ * counterpart to agree with, which is why it takes its identity from the node.
+ *
+ * @private
+ */
+const target = (payload, flowName, executionId) => {
+    if (payload.token !== undefined && payload.name !== undefined) {
+        return Effect.fail(new WaitForRequestInvalid({
+            code: "ambiguous_target",
+            message: `${tag} was called with both "token" and "name". A wait names one wait point: ` +
+                "a name relative to this execution, or an absolute token."
+        }));
+    }
+    if (payload.name !== undefined)
+        return Effect.succeed(deferred(payload.name));
+    if (payload.token !== undefined) {
+        return Effect.flatMap(parseToken(payload.token), (parsed) => parsed.flowName !== flowName || parsed.executionId !== executionId
+            ? Effect.fail(new WaitForRequestInvalid({
+                code: "foreign_execution",
+                message: `${tag} was called with a token addressed to flow "${parsed.flowName}" in execution ` +
+                    `"${parsed.executionId}", but it is running as flow "${flowName}" in execution ` +
+                    `"${executionId}". A durable deferred result is recorded against the execution that owns it, ` +
+                    "so only that execution can await it."
+            }))
+            : Effect.succeed(DurableDeferred.make(parsed.deferredName, { success: Schema.Json })));
+    }
+    return Effect.fail(new WaitForRequestInvalid({
+        code: "missing_target",
+        message: `${tag} was called with neither "token" nor "name", so there is no wait point to await.`
+    }));
+};
+/**
+ * The wait implementation: park under `event` with the wake token, and settle
+ * with the value that resolved the wait.
+ *
+ * Provide it beside the other action implementation layers a body calls, over
+ * the {@link module:Implementations.layerImplementations} table they file
+ * themselves in:
+ *
+ * ```ts
+ * Layer.mergeAll(WaitFor.layer, Interpreter.layer(Pipeline)).pipe(
+ *   Layer.provideMerge(Action.layerImplementations)
+ * )
+ * ```
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = action.toLayer((payload) => Effect.gen(function* () {
+    const instance = yield* FlowInstance;
+    const waitPoint = yield* target(payload, instance.flow._tag, instance.executionId);
+    const token = DurableDeferred.tokenFromExecutionId(waitPoint, {
+        flow: instance.flow,
+        executionId: instance.executionId
+    });
+    yield* annotateWaiting({ reason: "event", token });
+    return yield* DurableDeferred.await(waitPoint);
+}));
+//# sourceMappingURL=WaitFor.js.map

package/dist/esm/WaitFor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WaitFor.js","sourceRoot":"","sources":["../../src/WaitFor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The system wait point, as an ordinary declared action.\n *\n * `docs/concepts/flows-and-actions.md` names wait-for-event the\n * other half of the timer gap and says how to close it: ship it over the\n * existing `DurableDeferred`, so an external signal is a visible, keyed plan\n * node. That is this module. {@link action} is a plain `Action.make`\n * declaration — catalogable, `.call()`-able, one node in the built plan — and\n * {@link layer} is the implementation.\n *\n * Nothing about resolution is new. The wait is a `DurableDeferred`, so whoever\n * satisfies it completes it the way every other durable deferred is completed:\n * a token, and `DurableDeferred.succeed`, `fail`, `failCause`, or `done`.\n * {@link deferred} is how a resolver names the same wait point the action\n * awaits. The park is declared through the ordinary waiting vocabulary\n * ({@link module:WaitingAnnotation.annotateWaiting}) under `event`, carrying\n * that token as the compare-and-swap material a wake handler matches. Replay is\n * the deferred's: once a result is recorded, a re-driven round reads it and\n * runs through instead of parking again.\n *\n * @since 0.1.0\n */\n\nimport type * as Crypto from \"effect/Crypto\"\nimport * as Effect from \"effect/Effect\"\nimport type * as Layer from \"effect/Layer\"\nimport * as Schema from \"effect/Schema\"\nimport * as Action from \"./Action/index.ts\"\nimport * as DurableDeferred from \"./DurableDeferred.ts\"\nimport { FlowInstance } from \"./FlowRuntime/FlowInstance.ts\"\nimport type { FlowRuntime } from \"./FlowRuntime/FlowRuntime.ts\"\nimport { annotateWaiting } from \"./FlowRuntime/WaitingAnnotation.ts\"\n\n/**\n * A wait whose payload does not name exactly one reachable wait point.\n *\n * A payload names the wait point by `name`, relative to the running execution,\n * or by an absolute `token`. Naming both, or neither, leaves nothing to await;\n * a token that does not parse names nothing either; and a token addressed to a\n * different flow or a different execution names a wait point this execution\n * cannot observe, because a durable deferred result is recorded against the\n * flow and execution that own it.\n *\n * @category errors\n * @since 0.1.0\n */\nexport class WaitForRequestInvalid extends Schema.TaggedError<WaitForRequestInvalid>()(\n  \"@smthrs/flow/WaitForRequestInvalid\",\n  {\n    code: Schema.Literals([\n      \"missing_target\",\n      \"ambiguous_target\",\n      \"malformed_token\",\n      \"foreign_execution\"\n    ]),\n    message: Schema.String\n  }\n) {}\n\n/**\n * The tag the wait declaration is catalogued and resolved under.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const tag = \"system/wait-for\"\n\n/**\n * The durable deferred a named wait point resolves through.\n *\n * This is the resolver's half of {@link action}: the value to hand\n * `DurableDeferred.tokenFromExecutionId` and `DurableDeferred.succeed`, so a\n * wait that a body declared by name is completed through the existing deferred\n * completion path rather than a second one.\n *\n * ```ts\n * const gate = WaitFor.deferred(\"approval\")\n * const token = DurableDeferred.tokenFromExecutionId(gate, { flow, executionId })\n * yield* DurableDeferred.succeed(gate, { token, value: { approved: true } })\n * ```\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const deferred = (name: string): DurableDeferred.DurableDeferred<typeof Schema.Json> =>\n  DurableDeferred.make(`WaitFor/${name}`, { success: Schema.Json })\n\n/**\n * The declared wait action: a wait point named by `name` or by `token`.\n *\n * **When to use**\n *\n * Use it in a body wherever a round has to wait for something outside the run —\n * an approval, a webhook, a human — `WaitFor.action.call({ name: \"approval\"\n * })`. The node settles with whatever value resolved the wait, so downstream\n * steps read it the way they read any other step result.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const action: Action.Declared<\n  typeof tag,\n  Schema.Struct<{\n    readonly token: Schema.optional<Schema.String>\n    readonly name: Schema.optional<Schema.String>\n  }>,\n  typeof Schema.Json,\n  typeof WaitForRequestInvalid,\n  never\n> = Action.makeSystem(tag, {\n  payload: {\n    token: Schema.optional(Schema.String),\n    name: Schema.optional(Schema.String)\n  },\n  success: Schema.Json,\n  error: WaitForRequestInvalid,\n  tier: \"sealed\"\n})\n\n/**\n * The deferred name a token addresses, refused when the token does not parse.\n *\n * @private\n */\nconst parseToken = (token: string): Effect.Effect<DurableDeferred.TokenParsed, WaitForRequestInvalid> =>\n  Effect.mapError(\n    DurableDeferred.TokenParsed.parse(token),\n    (error) =>\n      new WaitForRequestInvalid({\n        code: \"malformed_token\",\n        message: `${tag} was called with a token that is not a durable deferred token. ${error.message}`\n      })\n  )\n\n/**\n * The wait point a payload names, resolved against the running execution.\n *\n * DECIDED: a payload names EXACTLY one of `name`\n * and `token`, and a token must address the execution that is waiting. A\n * deferred result is recorded against (flow name, execution id, deferred name)\n * and read back the same way, so awaiting a foreign token would park forever\n * while the value it names was recorded elsewhere; refusing it names the\n * mistake instead. BOTH halves of the owning execution's identity are compared:\n * a token carries its own flow name, so a same-execution token minted for\n * another flow completes under that flow while this one reads under its own,\n * which is the same permanent park by a different route.\n *\n * DECIDED: a wait point is addressed by the\n * PAYLOAD, and the per-dispatch identity {@link module:Sleep} derives its clock\n * from is deliberately NOT applied here. A wait is a rendezvous with something\n * outside the run, and a resolver has to name the same wait point to complete\n * it, so the name is the author's and two calls naming one wait point await one\n * fact — which is the intended reading, not an aliasing bug. A sleep has no\n * counterpart to agree with, which is why it takes its identity from the node.\n *\n * @private\n */\nconst target = (\n  payload: { readonly token?: string | undefined; readonly name?: string | undefined },\n  flowName: string,\n  executionId: string\n): Effect.Effect<DurableDeferred.DurableDeferred<typeof Schema.Json>, WaitForRequestInvalid> => {\n  if (payload.token !== undefined && payload.name !== undefined) {\n    return Effect.fail(\n      new WaitForRequestInvalid({\n        code: \"ambiguous_target\",\n        message: `${tag} was called with both \"token\" and \"name\". A wait names one wait point: ` +\n          \"a name relative to this execution, or an absolute token.\"\n      })\n    )\n  }\n  if (payload.name !== undefined) return Effect.succeed(deferred(payload.name))\n  if (payload.token !== undefined) {\n    return Effect.flatMap(\n      parseToken(payload.token),\n      (parsed) =>\n        parsed.flowName !== flowName || parsed.executionId !== executionId\n          ? Effect.fail(\n            new WaitForRequestInvalid({\n              code: \"foreign_execution\",\n              message: `${tag} was called with a token addressed to flow \"${parsed.flowName}\" in execution ` +\n                `\"${parsed.executionId}\", but it is running as flow \"${flowName}\" in execution ` +\n                `\"${executionId}\". A durable deferred result is recorded against the execution that owns it, ` +\n                \"so only that execution can await it.\"\n            })\n          )\n          : Effect.succeed(\n            DurableDeferred.make(parsed.deferredName, { success: Schema.Json })\n          )\n    )\n  }\n  return Effect.fail(\n    new WaitForRequestInvalid({\n      code: \"missing_target\",\n      message: `${tag} was called with neither \"token\" nor \"name\", so there is no wait point to await.`\n    })\n  )\n}\n\n/**\n * The wait implementation: park under `event` with the wake token, and settle\n * with the value that resolved the wait.\n *\n * Provide it beside the other action implementation layers a body calls, over\n * the {@link module:Implementations.layerImplementations} table they file\n * themselves in:\n *\n * ```ts\n * Layer.mergeAll(WaitFor.layer, Interpreter.layer(Pipeline)).pipe(\n *   Layer.provideMerge(Action.layerImplementations)\n * )\n * ```\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layer: Layer.Layer<never, never, Crypto.Crypto | FlowRuntime> = action.toLayer((payload) =>\n  Effect.gen(function*() {\n    const instance = yield* FlowInstance\n    const waitPoint = yield* target(payload, instance.flow._tag, instance.executionId)\n    const token = DurableDeferred.tokenFromExecutionId(waitPoint, {\n      flow: instance.flow,\n      executionId: instance.executionId\n    })\n    yield* annotateWaiting({ reason: \"event\", token })\n    return yield* DurableDeferred.await(waitPoint)\n  })\n)\n"]}

package/dist/esm/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @since 0.1.0
+ */
+/**
+ * Durable action definitions and combinators.
+ *
+ * @since 0.1.0
+ */
+export * as Action from "./Action/index.ts";
+/**
+ * Durable clock and timer services.
+ *
+ * @since 0.1.0
+ */
+export * as Deadline from "./Deadline.ts";
+export * as DurableClock from "./DurableClock.ts";
+/**
+ * Durable deferred values.
+ *
+ * @since 0.1.0
+ */
+export * as DurableDeferred from "./DurableDeferred.ts";
+/**
+ * Durable queues.
+ *
+ * @since 0.1.0
+ */
+export * as DurableQueue from "./DurableQueue.ts";
+/**
+ * Durable flow definitions.
+ *
+ * @since 0.1.0
+ */
+export * as Flow from "./Flow/index.ts";
+/**
+ * The execution contract flow authoring APIs are written against.
+ *
+ * @since 0.1.0
+ */
+export * as FlowRuntime from "./FlowRuntime/index.ts";
+/**
+ * One typed fault for every failure, and the response table that reads it.
+ *
+ * @since 1.0.0
+ */
+export * as Fault from "./Fault.ts";
+/**
+ * External workers observed through durable actions and timers.
+ *
+ * @since 1.0.0
+ */
+export * as ExternalJob from "./ExternalJob.ts";
+/**
+ * Plan-time graph building from flow declarations.
+ *
+ * @since 0.1.0
+ */
+export * as Graph from "./Graph.ts";
+/**
+ * Asking a person something: typed answers, re-asking, and a deadline.
+ *
+ * @since 0.1.0
+ */
+export * as HumanTask from "./HumanTask.ts";
+/**
+ * Execution of a flow body, and the layer that registers it.
+ *
+ * @since 0.1.0
+ */
+export * as Interpreter from "./Interpreter.ts";
+/**
+ * The durable poller: attempts as rounds, waits as durable timers.
+ *
+ * @since 0.1.0
+ */
+export * as Poll from "./Poll.ts";
+/**
+ * The stall breaker: rounds whose tree, failing checks, or output held still.
+ *
+ * @since 1.0.0
+ */
+export * as Stall from "./Stall.ts";
+/**
+ * Retry policy models and constructors.
+ *
+ * @since 0.1.0
+ */
+export * as RetryPolicy from "./RetryPolicy.ts";
+/**
+ * The system timer action and its implementation layer.
+ *
+ * @since 0.1.0
+ */
+export * as Sleep from "./Sleep.ts";
+/**
+ * Stable step identity construction.
+ *
+ * @since 0.1.0
+ */
+export * as StepIdentity from "./Action/StepIdentity.ts";
+/**
+ * The system wait-point action and its implementation layer.
+ *
+ * @since 0.1.0
+ */
+export * as WaitFor from "./WaitFor.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAEA;;GAEG;AAEH;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAA;AAE3C;;;;GAIG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD;;;;GAIG;AACH,OAAO,KAAK,eAAe,MAAM,sBAAsB,CAAA;AAEvD;;;;GAIG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD;;;;GAIG;AACH,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAA;AAEvC;;;;GAIG;AACH,OAAO,KAAK,WAAW,MAAM,wBAAwB,CAAA;AAErD;;;;GAIG;AACH,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAEnC;;;;GAIG;AACH,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAE/C;;;;GAIG;AACH,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAEnC;;;;GAIG;AACH,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAE3C;;;;GAIG;AACH,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAE/C;;;;GAIG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAEjC;;;;GAIG;AACH,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAEnC;;;;GAIG;AACH,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAE/C;;;;GAIG;AACH,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAEnC;;;;GAIG;AACH,OAAO,KAAK,YAAY,MAAM,0BAA0B,CAAA;AAExD;;;;GAIG;AACH,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA"}

package/dist/esm/index.js

@@ -0,0 +1,108 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+/**
+ * @since 0.1.0
+ */
+/**
+ * Durable action definitions and combinators.
+ *
+ * @since 0.1.0
+ */
+export * as Action from "./Action/index.js";
+/**
+ * Durable clock and timer services.
+ *
+ * @since 0.1.0
+ */
+export * as Deadline from "./Deadline.js";
+export * as DurableClock from "./DurableClock.js";
+/**
+ * Durable deferred values.
+ *
+ * @since 0.1.0
+ */
+export * as DurableDeferred from "./DurableDeferred.js";
+/**
+ * Durable queues.
+ *
+ * @since 0.1.0
+ */
+export * as DurableQueue from "./DurableQueue.js";
+/**
+ * Durable flow definitions.
+ *
+ * @since 0.1.0
+ */
+export * as Flow from "./Flow/index.js";
+/**
+ * The execution contract flow authoring APIs are written against.
+ *
+ * @since 0.1.0
+ */
+export * as FlowRuntime from "./FlowRuntime/index.js";
+/**
+ * One typed fault for every failure, and the response table that reads it.
+ *
+ * @since 1.0.0
+ */
+export * as Fault from "./Fault.js";
+/**
+ * External workers observed through durable actions and timers.
+ *
+ * @since 1.0.0
+ */
+export * as ExternalJob from "./ExternalJob.js";
+/**
+ * Plan-time graph building from flow declarations.
+ *
+ * @since 0.1.0
+ */
+export * as Graph from "./Graph.js";
+/**
+ * Asking a person something: typed answers, re-asking, and a deadline.
+ *
+ * @since 0.1.0
+ */
+export * as HumanTask from "./HumanTask.js";
+/**
+ * Execution of a flow body, and the layer that registers it.
+ *
+ * @since 0.1.0
+ */
+export * as Interpreter from "./Interpreter.js";
+/**
+ * The durable poller: attempts as rounds, waits as durable timers.
+ *
+ * @since 0.1.0
+ */
+export * as Poll from "./Poll.js";
+/**
+ * The stall breaker: rounds whose tree, failing checks, or output held still.
+ *
+ * @since 1.0.0
+ */
+export * as Stall from "./Stall.js";
+/**
+ * Retry policy models and constructors.
+ *
+ * @since 0.1.0
+ */
+export * as RetryPolicy from "./RetryPolicy.js";
+/**
+ * The system timer action and its implementation layer.
+ *
+ * @since 0.1.0
+ */
+export * as Sleep from "./Sleep.js";
+/**
+ * Stable step identity construction.
+ *
+ * @since 0.1.0
+ */
+export * as StepIdentity from "./Action/StepIdentity.js";
+/**
+ * The system wait-point action and its implementation layer.
+ *
+ * @since 0.1.0
+ */
+export * as WaitFor from "./WaitFor.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD;;GAEG;AAEH;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAA;AAE3C;;;;GAIG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD;;;;GAIG;AACH,OAAO,KAAK,eAAe,MAAM,sBAAsB,CAAA;AAEvD;;;;GAIG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD;;;;GAIG;AACH,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAA;AAEvC;;;;GAIG;AACH,OAAO,KAAK,WAAW,MAAM,wBAAwB,CAAA;AAErD;;;;GAIG;AACH,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAEnC;;;;GAIG;AACH,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAE/C;;;;GAIG;AACH,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAEnC;;;;GAIG;AACH,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAE3C;;;;GAIG;AACH,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAE/C;;;;GAIG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAEjC;;;;GAIG;AACH,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAEnC;;;;GAIG;AACH,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAE/C;;;;GAIG;AACH,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAEnC;;;;GAIG;AACH,OAAO,KAAK,YAAY,MAAM,0BAA0B,CAAA;AAExD;;;;GAIG;AACH,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA","sourcesContent":["// Deep reviewed and polished by a human on 2026-08-10.\n\n/**\n * @since 0.1.0\n */\n\n/**\n * Durable action definitions and combinators.\n *\n * @since 0.1.0\n */\nexport * as Action from \"./Action/index.ts\"\n\n/**\n * Durable clock and timer services.\n *\n * @since 0.1.0\n */\nexport * as Deadline from \"./Deadline.ts\"\nexport * as DurableClock from \"./DurableClock.ts\"\n\n/**\n * Durable deferred values.\n *\n * @since 0.1.0\n */\nexport * as DurableDeferred from \"./DurableDeferred.ts\"\n\n/**\n * Durable queues.\n *\n * @since 0.1.0\n */\nexport * as DurableQueue from \"./DurableQueue.ts\"\n\n/**\n * Durable flow definitions.\n *\n * @since 0.1.0\n */\nexport * as Flow from \"./Flow/index.ts\"\n\n/**\n * The execution contract flow authoring APIs are written against.\n *\n * @since 0.1.0\n */\nexport * as FlowRuntime from \"./FlowRuntime/index.ts\"\n\n/**\n * One typed fault for every failure, and the response table that reads it.\n *\n * @since 1.0.0\n */\nexport * as Fault from \"./Fault.ts\"\n\n/**\n * External workers observed through durable actions and timers.\n *\n * @since 1.0.0\n */\nexport * as ExternalJob from \"./ExternalJob.ts\"\n\n/**\n * Plan-time graph building from flow declarations.\n *\n * @since 0.1.0\n */\nexport * as Graph from \"./Graph.ts\"\n\n/**\n * Asking a person something: typed answers, re-asking, and a deadline.\n *\n * @since 0.1.0\n */\nexport * as HumanTask from \"./HumanTask.ts\"\n\n/**\n * Execution of a flow body, and the layer that registers it.\n *\n * @since 0.1.0\n */\nexport * as Interpreter from \"./Interpreter.ts\"\n\n/**\n * The durable poller: attempts as rounds, waits as durable timers.\n *\n * @since 0.1.0\n */\nexport * as Poll from \"./Poll.ts\"\n\n/**\n * The stall breaker: rounds whose tree, failing checks, or output held still.\n *\n * @since 1.0.0\n */\nexport * as Stall from \"./Stall.ts\"\n\n/**\n * Retry policy models and constructors.\n *\n * @since 0.1.0\n */\nexport * as RetryPolicy from \"./RetryPolicy.ts\"\n\n/**\n * The system timer action and its implementation layer.\n *\n * @since 0.1.0\n */\nexport * as Sleep from \"./Sleep.ts\"\n\n/**\n * Stable step identity construction.\n *\n * @since 0.1.0\n */\nexport * as StepIdentity from \"./Action/StepIdentity.ts\"\n\n/**\n * The system wait-point action and its implementation layer.\n *\n * @since 0.1.0\n */\nexport * as WaitFor from \"./WaitFor.ts\"\n"]}

package/dist/esm/internal/BoundedJson.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Human-task diagnostics over the shared inert JSON boundary.
+ * @since 1.0.0
+ */
+import * as BoundedJson from "@smthrs/canonical/BoundedJson";
+/** Resource limits for one human-task value.
+ * @private
+ * @since 1.0.0
+ */
+export type Limits = Required<Omit<BoundedJson.Limits, "maxTotalMembers">>;
+/** Encoded JSON bytes, without allocating an encoded copy.
+ * @private
+ * @since 1.0.0
+ */
+export declare const encodedStringBytes: (value: string, maximum?: number) => number | undefined;
+/** Whether text is well-formed and fits its encoded byte budget.
+ * @private
+ * @since 1.0.0
+ */
+export declare const textFits: (value: string, maximum: number) => boolean;
+/** Admits a detached snapshot and gives failures a bounded field path.
+ * @private
+ * @since 1.0.0
+ */
+export declare const admit: (input: unknown, limits: Limits) => {
+    ok: true;
+    value: BoundedJson.Json;
+    complaint?: never;
+} | {
+    ok: false;
+    complaint: string;
+    value?: never;
+};
+/**
+ * Returns a Unicode-scalar-safe bounded prefix.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare function scalarPrefix(value: string, maximumCodeUnits: number): string;
+/**
+ * Renders an untrusted value without invoking its code or allocating from its full size.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const render: (value: unknown, maximumCodeUnits: number) => string;
+//# sourceMappingURL=BoundedJson.d.ts.map

package/dist/esm/internal/BoundedJson.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BoundedJson.d.ts","sourceRoot":"","sources":["../../../src/internal/BoundedJson.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,WAAW,MAAM,+BAA+B,CAAA;AAE5D;;;GAGG;AACH,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAA;AAE1E;;;GAGG;AACH,eAAO,MAAM,kBAAkB,yDAAiC,CAAA;AAEhE;;;GAGG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,MAAM,EAAE,SAAS,MAAM,KAAG,OAA2D,CAAA;AAErH;;;GAGG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,OAAO,EAAE,QAAQ,MAAM;;;;;;;;CAYnD,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAwB5E;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,OAAO,EAAE,kBAAkB,MAAM,KAAG,MA2BjE,CAAA"}