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

package/dist/esm/Flow/Outcome.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Serializable values with which one flow round can settle.
+ *
+ * Engine handoff semantics are intentionally separate. These values contain
+ * only the completed value, the next flow invocation, or the durable waiting
+ * classification described by `docs/concepts/trampoline-rounds.md`.
+ *
+ * @since 0.1.0
+ */
+import type { CapabilityPattern } from "@smthrs/capability/Capability";
+import * as Node from "@smthrs/plan/Node";
+import * as Schema from "effect/Schema";
+import { WaitingAnnotation } from "../FlowRuntime/WaitingAnnotation.ts";
+/**
+ * A completed trampoline lineage value.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Done<A> {
+    readonly _tag: "Done";
+    /**
+     * The completed value in its author-facing form. The engine encodes it with
+     * the settling flow's success schema at the settlement boundary; callers do
+     * not pre-encode values passed to {@link done}.
+     */
+    readonly value: A;
+}
+/**
+ * A serializable invocation of the next flow round.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface To<Payload> {
+    readonly _tag: "To";
+    readonly flow: string;
+    readonly capabilityCeilings?: ReadonlyArray<ReadonlyArray<CapabilityPattern>>;
+    /**
+     * The next round's payload in its author-facing form. The engine encodes it
+     * with the target flow's payload schema at settlement, before persisting the
+     * handoff; callers do not pre-encode values passed to `Flow.to`.
+     */
+    readonly payload: Payload;
+}
+/**
+ * A request to durably park the current flow round.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Park {
+    readonly _tag: "Park";
+    readonly reason: WaitingAnnotation;
+}
+/**
+ * The three pure-data settlements a trampoline round can produce.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Outcome<A = unknown, Payload = unknown> = Done<A> | To<Payload> | Park;
+/**
+ * Schema for completed trampoline lineage values.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const Done: Schema.Struct<{
+    readonly _tag: Schema.tag<"Done">;
+    readonly value: Schema.Unknown;
+}>;
+/**
+ * Schema for next-round flow invocations.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const To: Schema.Struct<{
+    readonly _tag: Schema.tag<"To">;
+    readonly flow: Schema.String;
+    readonly payload: Schema.Unknown;
+}>;
+/**
+ * Schema for durable trampoline parking requests.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const Park: Schema.Struct<{
+    readonly _tag: Schema.tag<"Park">;
+    readonly reason: Schema.Struct<{
+        readonly reason: Schema.String;
+        readonly wakeAt: Schema.optional<Schema.Number>;
+        readonly token: Schema.optional<Schema.String>;
+        readonly request: Schema.optional<Schema.String>;
+    }>;
+}>;
+/**
+ * Schema for every pure-data trampoline settlement.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const Outcome: Schema.Union<readonly [Schema.Struct<{
+    readonly _tag: Schema.tag<"Done">;
+    readonly value: Schema.Unknown;
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"To">;
+    readonly flow: Schema.String;
+    readonly payload: Schema.Unknown;
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"Park">;
+    readonly reason: Schema.Struct<{
+        readonly reason: Schema.String;
+        readonly wakeAt: Schema.optional<Schema.Number>;
+        readonly token: Schema.optional<Schema.String>;
+        readonly request: Schema.optional<Schema.String>;
+    }>;
+}>]>;
+/**
+ * Constructs a completed trampoline lineage value using Node.succeed's JSON
+ * projection. Pass a planned reference to retain an upstream domain value.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const done: <A>(value: A) => Node.Node<Node.Succeed<Done<A>>>;
+/**
+ * Constructs a durable parking request using the runtime waiting vocabulary.
+ *
+ * The two forms describe the same wait. The record is the whole waiting
+ * vocabulary, and is what a park with a deadline needs; the positional form is
+ * the common case — a reason and the token a wake handler matches against —
+ * written the way an author says it out loud, `Flow.park("approval", requestId)`.
+ * A positional call with no token omits the field rather than parking under an
+ * empty one.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const park: {
+    (reason: WaitingAnnotation): Node.Node<Park>;
+    (reason: string, token?: string | undefined): Node.Node<Park>;
+};
+/**
+ * Whether a settled body value is one of the three trampoline settlements.
+ *
+ * A body's root node may settle with anything its author wrote; only these
+ * three values authored through {@link done}, a flow's `to` method, or
+ * {@link park} ask the engine for a settlement other than "this value is the
+ * answer". Shape alone is deliberately insufficient: ordinary success data
+ * may legally contain the same `_tag` fields. Graph construction carries a
+ * non-enumerable marker from the explicit authoring node to its hydrated
+ * value, and encoded outcome records remain plain data until decoded by the
+ * runtime surface that owns them.
+ *
+ * @category refinements
+ * @since 0.1.0
+ */
+export declare const isOutcome: (value: unknown) => value is Outcome;
+//# sourceMappingURL=Outcome.d.ts.map

package/dist/esm/Flow/Outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Outcome.d.ts","sourceRoot":"","sources":["../../../src/Flow/Outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA;AACtE,OAAO,KAAK,IAAI,MAAM,mBAAmB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAA;AAcvE;;;;;GAKG;AACH,MAAM,WAAW,IAAI,CAAC,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,EAAE,CAAC,OAAO;IACzB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,iBAAiB,CAAC,CAAC,CAAA;IAC7E;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;CACnC;AAED;;;;;GAKG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;AAElF;;;;;GAKG;AACH,eAAO,MAAM,IAAI;;;EAGf,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,EAAE;;;;EAIb,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,IAAI;;;;;;;;EAGf,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;IAAiC,CAAA;AAErD;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAkD,CAAA;AAEpH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,IAAI,EAAE;IACjB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC5C,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;CAS3D,CAAA;AAEJ;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,OAMnD,CAAA"}

package/dist/esm/Flow/Outcome.js

@@ -0,0 +1,115 @@
+/**
+ * Serializable values with which one flow round can settle.
+ *
+ * Engine handoff semantics are intentionally separate. These values contain
+ * only the completed value, the next flow invocation, or the durable waiting
+ * classification described by `docs/concepts/trampoline-rounds.md`.
+ *
+ * @since 0.1.0
+ */
+import * as Node from "@smthrs/plan/Node";
+import * as Schema from "effect/Schema";
+import { WaitingAnnotation } from "../FlowRuntime/WaitingAnnotation.js";
+import { OutcomeNodeTypeId, OutcomeValueTypeId } from "../internal/OutcomeMarker.js";
+const outcomeNode = (value) => {
+    const node = Node.succeed(value);
+    Object.defineProperty(node.ast, OutcomeNodeTypeId, {
+        configurable: false,
+        enumerable: false,
+        value: value._tag,
+        writable: false
+    });
+    return node;
+};
+/**
+ * Schema for completed trampoline lineage values.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Done = Schema.Struct({
+    _tag: Schema.tag("Done"),
+    value: Schema.Unknown
+});
+/**
+ * Schema for next-round flow invocations.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const To = Schema.Struct({
+    _tag: Schema.tag("To"),
+    flow: Schema.String,
+    payload: Schema.Unknown
+});
+/**
+ * Schema for durable trampoline parking requests.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Park = Schema.Struct({
+    _tag: Schema.tag("Park"),
+    reason: WaitingAnnotation
+});
+/**
+ * Schema for every pure-data trampoline settlement.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Outcome = Schema.Union([Done, To, Park]);
+/**
+ * Constructs a completed trampoline lineage value using Node.succeed's JSON
+ * projection. Pass a planned reference to retain an upstream domain value.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const done = (value) => outcomeNode({ _tag: "Done", value });
+/**
+ * Constructs a durable parking request using the runtime waiting vocabulary.
+ *
+ * The two forms describe the same wait. The record is the whole waiting
+ * vocabulary, and is what a park with a deadline needs; the positional form is
+ * the common case — a reason and the token a wake handler matches against —
+ * written the way an author says it out loud, `Flow.park("approval", requestId)`.
+ * A positional call with no token omits the field rather than parking under an
+ * empty one.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const park = (reason, token) => outcomeNode({
+    _tag: "Park",
+    reason: typeof reason !== "string"
+        ? reason
+        : token === undefined
+            ? { reason }
+            : { reason, token }
+});
+/**
+ * Whether a settled body value is one of the three trampoline settlements.
+ *
+ * A body's root node may settle with anything its author wrote; only these
+ * three values authored through {@link done}, a flow's `to` method, or
+ * {@link park} ask the engine for a settlement other than "this value is the
+ * answer". Shape alone is deliberately insufficient: ordinary success data
+ * may legally contain the same `_tag` fields. Graph construction carries a
+ * non-enumerable marker from the explicit authoring node to its hydrated
+ * value, and encoded outcome records remain plain data until decoded by the
+ * runtime surface that owns them.
+ *
+ * @category refinements
+ * @since 0.1.0
+ */
+export const isOutcome = (value) => {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const marker = Object.getOwnPropertyDescriptor(value, OutcomeValueTypeId);
+    if (marker === undefined || !("value" in marker))
+        return false;
+    const tag = Object.getOwnPropertyDescriptor(value, "_tag");
+    return tag !== undefined && "value" in tag && marker.value === tag.value && Schema.is(Outcome)(value);
+};
+//# sourceMappingURL=Outcome.js.map

package/dist/esm/Flow/Outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Outcome.js","sourceRoot":"","sources":["../../../src/Flow/Outcome.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Serializable values with which one flow round can settle.\n *\n * Engine handoff semantics are intentionally separate. These values contain\n * only the completed value, the next flow invocation, or the durable waiting\n * classification described by `docs/concepts/trampoline-rounds.md`.\n *\n * @since 0.1.0\n */\n\nimport type { CapabilityPattern } from \"@smthrs/capability/Capability\"\nimport * as Node from \"@smthrs/plan/Node\"\nimport * as Schema from \"effect/Schema\"\nimport { WaitingAnnotation } from \"../FlowRuntime/WaitingAnnotation.ts\"\nimport { OutcomeNodeTypeId, OutcomeValueTypeId } from \"../internal/OutcomeMarker.ts\"\n\nconst outcomeNode = <A extends Outcome>(value: A): Node.Node<Node.Succeed<A>> => {\n  const node = Node.succeed(value)\n  Object.defineProperty(node.ast, OutcomeNodeTypeId, {\n    configurable: false,\n    enumerable: false,\n    value: value._tag,\n    writable: false\n  })\n  return node\n}\n\n/**\n * A completed trampoline lineage value.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Done<A> {\n  readonly _tag: \"Done\"\n  /**\n   * The completed value in its author-facing form. The engine encodes it with\n   * the settling flow's success schema at the settlement boundary; callers do\n   * not pre-encode values passed to {@link done}.\n   */\n  readonly value: A\n}\n\n/**\n * A serializable invocation of the next flow round.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface To<Payload> {\n  readonly _tag: \"To\"\n  readonly flow: string\n  readonly capabilityCeilings?: ReadonlyArray<ReadonlyArray<CapabilityPattern>>\n  /**\n   * The next round's payload in its author-facing form. The engine encodes it\n   * with the target flow's payload schema at settlement, before persisting the\n   * handoff; callers do not pre-encode values passed to `Flow.to`.\n   */\n  readonly payload: Payload\n}\n\n/**\n * A request to durably park the current flow round.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Park {\n  readonly _tag: \"Park\"\n  readonly reason: WaitingAnnotation\n}\n\n/**\n * The three pure-data settlements a trampoline round can produce.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Outcome<A = unknown, Payload = unknown> = Done<A> | To<Payload> | Park\n\n/**\n * Schema for completed trampoline lineage values.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const Done = Schema.Struct({\n  _tag: Schema.tag(\"Done\"),\n  value: Schema.Unknown\n})\n\n/**\n * Schema for next-round flow invocations.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const To = Schema.Struct({\n  _tag: Schema.tag(\"To\"),\n  flow: Schema.String,\n  payload: Schema.Unknown\n})\n\n/**\n * Schema for durable trampoline parking requests.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const Park = Schema.Struct({\n  _tag: Schema.tag(\"Park\"),\n  reason: WaitingAnnotation\n})\n\n/**\n * Schema for every pure-data trampoline settlement.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const Outcome = Schema.Union([Done, To, Park])\n\n/**\n * Constructs a completed trampoline lineage value using Node.succeed's JSON\n * projection. Pass a planned reference to retain an upstream domain value.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const done = <A>(value: A): Node.Node<Node.Succeed<Done<A>>> => outcomeNode<Done<A>>({ _tag: \"Done\", value })\n\n/**\n * Constructs a durable parking request using the runtime waiting vocabulary.\n *\n * The two forms describe the same wait. The record is the whole waiting\n * vocabulary, and is what a park with a deadline needs; the positional form is\n * the common case — a reason and the token a wake handler matches against —\n * written the way an author says it out loud, `Flow.park(\"approval\", requestId)`.\n * A positional call with no token omits the field rather than parking under an\n * empty one.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const park: {\n  (reason: WaitingAnnotation): Node.Node<Park>\n  (reason: string, token?: string | undefined): Node.Node<Park>\n} = (reason: WaitingAnnotation | string, token?: string | undefined): Node.Node<Park> =>\n  outcomeNode({\n    _tag: \"Park\",\n    reason: typeof reason !== \"string\"\n      ? reason\n      : token === undefined\n      ? { reason }\n      : { reason, token }\n  })\n\n/**\n * Whether a settled body value is one of the three trampoline settlements.\n *\n * A body's root node may settle with anything its author wrote; only these\n * three values authored through {@link done}, a flow's `to` method, or\n * {@link park} ask the engine for a settlement other than \"this value is the\n * answer\". Shape alone is deliberately insufficient: ordinary success data\n * may legally contain the same `_tag` fields. Graph construction carries a\n * non-enumerable marker from the explicit authoring node to its hydrated\n * value, and encoded outcome records remain plain data until decoded by the\n * runtime surface that owns them.\n *\n * @category refinements\n * @since 0.1.0\n */\nexport const isOutcome = (value: unknown): value is Outcome => {\n  if (typeof value !== \"object\" || value === null) return false\n  const marker = Object.getOwnPropertyDescriptor(value, OutcomeValueTypeId)\n  if (marker === undefined || !(\"value\" in marker)) return false\n  const tag = Object.getOwnPropertyDescriptor(value, \"_tag\")\n  return tag !== undefined && \"value\" in tag && marker.value === tag.value && Schema.is(Outcome)(value)\n}\n"]}

package/dist/esm/Flow/Result.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Serializable completion and suspension states returned by flow executions.
+ *
+ * @since 0.1.0
+ */
+import { CapabilityPattern } from "@smthrs/capability/Capability";
+import type * as Exit from "effect/Exit";
+import * as Schema from "effect/Schema";
+import type { ExitEncoded } from "effect/unstable/rpc/RpcMessage";
+declare const ResultTypeId = "@smthrs/flow/Flow/Result";
+/**
+ * Returns `true` when a value is a flow `Result`.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export declare const isResult: <A = unknown, E = unknown>(u: unknown) => u is Result<A, E>;
+/**
+ * Result of a flow execution: a completed exit, a suspended flow state, or a
+ * handoff to the next round of a trampoline lineage.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export type Result<A, E> = Complete<A, E> | Suspended | Handoff;
+/**
+ * Encoded representation of a flow `Result`.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export type ResultEncoded<A, E> = CompleteEncoded<A, E> | typeof Suspended.Encoded | typeof Handoff.Encoded;
+/**
+ * Encoded representation of a completed flow result containing an encoded
+ * `Exit`.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export interface CompleteEncoded<A, E> {
+    readonly _tag: "Complete";
+    readonly exit: ExitEncoded<A, E>;
+}
+/**
+ * Schema constructor for `Complete` flow results using the supplied
+ * success and error schemas.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export interface CompleteSchema<Success extends Schema.Constraint, Error extends Schema.Constraint> extends Schema.declareConstructor<Complete<Success["Type"], Error["Type"]>, Complete<Success["Encoded"], Error["Encoded"]>, readonly [Schema.Exit<Success, Error, Schema.Defect>]> {
+    readonly success: Success;
+    readonly error: Error;
+}
+declare const Complete_base: new <A_1 extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A_1 as P extends "_tag" ? never : P]: A_1[P]; }>) => Readonly<A_1> & {
+    readonly _tag: "Complete";
+} & import("effect/Pipeable").Pipeable;
+/**
+ * Represents a completed flow execution with its success or failure `Exit`.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export declare class Complete<A, E> extends Complete_base<{
+    readonly exit: Exit.Exit<A, E>;
+}> {
+    /**
+     * Marks this value as a flow result for runtime guards.
+     *
+     * @since 0.1.0
+     */
+    readonly [ResultTypeId] = "@smthrs/flow/Flow/Result";
+    /**
+     * Builds the schema for completed flow results from success and error schemas.
+     *
+     * @since 0.1.0
+     */
+    static Schema<Success extends Schema.Constraint, Error extends Schema.Constraint>(options: {
+        readonly success: Success;
+        readonly error: Error;
+    }): CompleteSchema<Success, Error>;
+}
+declare const Suspended_base: Schema.Class<Suspended, Schema.Struct<{
+    readonly _tag: Schema.tag<"Suspended">;
+    readonly cause: Schema.optional<Schema.Cause<Schema.Never, Schema.Defect>>;
+}>, {}>;
+/**
+ * Represents a suspended flow execution, optionally carrying the cause that
+ * triggered suspension.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export declare class Suspended extends Suspended_base {
+    /**
+     * Marks this value as a flow result for runtime guards.
+     *
+     * @since 0.1.0
+     */
+    readonly [ResultTypeId] = "@smthrs/flow/Flow/Result";
+}
+/**
+ * The deadline a trampoline lineage's rounds share: the journaled first start
+ * of its originating round and the bound in milliseconds, so every round
+ * expires at `startedAtMs + deadlineMs`.
+ *
+ * @category results
+ * @since 1.0.0
+ */
+export declare const LineageDeadline: Schema.Struct<{
+    readonly startedAtMs: Schema.Number;
+    readonly deadlineMs: Schema.Number;
+}>;
+/**
+ * The deadline a trampoline lineage's rounds share.
+ *
+ * @category results
+ * @since 1.0.0
+ */
+export type LineageDeadline = typeof LineageDeadline.Type;
+declare const Handoff_base: Schema.Class<Handoff, Schema.Struct<{
+    readonly _tag: Schema.tag<"Handoff">;
+    readonly flow: Schema.NonEmptyString;
+    readonly capabilityCeilings: Schema.optionalKey<Schema.$Array<Schema.$Array<typeof CapabilityPattern>>>;
+    readonly payload: Schema.Unknown;
+    /**
+     * The lineage deadline the next round runs under, stamped by the round
+     * that handed off when its lineage is bounded (`Deadline.bound`).
+     */
+    readonly deadline: Schema.optionalKey<Schema.Struct<{
+        readonly startedAtMs: Schema.Number;
+        readonly deadlineMs: Schema.Number;
+    }>>;
+}>, {}>;
+/**
+ * Represents a flow round that ended by handing off to the next round of its
+ * trampoline lineage.
+ *
+ * A round settles this way when its body's root value is a `to` invocation
+ * (`docs/concepts/trampoline-rounds.md`): the round produced no answer of
+ * its own, it produced the NEXT flow to run. `flow` is the target's tag, so the
+ * value survives the journal and the run row unchanged.
+ *
+ * DECIDED: `payload` is the target's payload in
+ * ENCODED form. The target's `to` method accepts its ordinary constructor
+ * shape so authoring stays aligned with `call` and `execute`; the body
+ * interpreter resolves planned references and encodes the invocation through
+ * the target declaration before constructing `Handoff`. The receiving round
+ * decodes those bytes through the same schema.
+ *
+ * It is a third settlement rather than a `Complete` carrying a magic value
+ * because the engine has to tell "this run answered" from "this run continues
+ * elsewhere" without decoding against a success schema the handoff never
+ * satisfies.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export declare class Handoff extends Handoff_base {
+    /**
+     * Marks this value as a flow result for runtime guards.
+     *
+     * @since 0.1.0
+     */
+    readonly [ResultTypeId] = "@smthrs/flow/Flow/Result";
+}
+/**
+ * Creates a schema for flow results using the supplied success and error
+ * schemas.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export declare const Result: <Success extends Schema.Constraint, Error extends Schema.Constraint>(options: {
+    readonly success: Success;
+    readonly error: Error;
+}) => Schema.Union<readonly [CompleteSchema<Success, Error>, typeof Suspended, typeof Handoff]>;
+/**
+ * Schema for encoded flow results with generic success and error payloads.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export declare const ResultEncoded: Schema.Codec<ResultEncoded<any, any>>;
+export {};
+//# sourceMappingURL=Result.d.ts.map

package/dist/esm/Flow/Result.d.ts.map

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

package/dist/esm/Flow/Result.js

@@ -0,0 +1,171 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+/**
+ * Serializable completion and suspension states returned by flow executions.
+ *
+ * @since 0.1.0
+ */
+import { CapabilityPattern } from "@smthrs/capability/Capability";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import * as SchemaParser from "effect/SchemaParser";
+import * as Transformation from "effect/SchemaTransformation";
+const ResultTypeId = "@smthrs/flow/Flow/Result";
+/**
+ * Returns `true` when a value is a flow `Result`.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export const isResult = (u) => {
+    if (u !== Object(u))
+        return false;
+    const marker = Object.getOwnPropertyDescriptor(u, ResultTypeId);
+    if (marker === undefined || !("value" in marker) || marker.value !== ResultTypeId)
+        return false;
+    const tag = Object.getOwnPropertyDescriptor(u, "_tag");
+    return tag !== undefined && "value" in tag &&
+        (tag.value === "Complete" || tag.value === "Suspended" || tag.value === "Handoff");
+};
+/**
+ * Represents a completed flow execution with its success or failure `Exit`.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export class Complete extends Data.TaggedClass("Complete") {
+    /**
+     * Marks this value as a flow result for runtime guards.
+     *
+     * @since 0.1.0
+     */
+    [ResultTypeId] = ResultTypeId;
+    /**
+     * Builds the schema for completed flow results from success and error schemas.
+     *
+     * @since 0.1.0
+     */
+    static Schema(options) {
+        // The declaration stays inline because it closes over this constructor's schemas.
+        const schema = Schema.declareConstructor()([Schema.Exit(options.success, options.error, Schema.Defect())], ([exit]) => (input, ast, options) => {
+            if (!(isResult(input) && input._tag === "Complete")) {
+                return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
+            }
+            return Effect.mapBothEager(SchemaParser.decodeEffect(exit)(input.exit, options), {
+                onSuccess: (exit) => new Complete({ exit }),
+                onFailure: (issue) => new SchemaIssue.Composite(ast, [
+                    new SchemaIssue.Pointer(["exit"], issue)
+                ], input, options)
+            });
+        }, {
+            expected: "Flow.Complete",
+            toCodecJson: ([exit]) => Schema.link()(Schema.Struct({
+                _tag: Schema.tag("Complete"),
+                exit
+            }), Transformation.transform({
+                decode: (encoded) => new Complete({ exit: encoded.exit }),
+                encode: (result) => ({
+                    _tag: "Complete",
+                    exit: result.exit
+                })
+            }))
+        });
+        return Schema.make(schema.ast, {
+            success: options.success,
+            error: options.error
+        });
+    }
+}
+/**
+ * Represents a suspended flow execution, optionally carrying the cause that
+ * triggered suspension.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export class Suspended extends Schema.Class("@smthrs/flow/Flow/Suspended")({
+    _tag: Schema.tag("Suspended"),
+    cause: Schema.optional(Schema.Cause(Schema.Never, Schema.Defect()))
+}) {
+    /**
+     * Marks this value as a flow result for runtime guards.
+     *
+     * @since 0.1.0
+     */
+    [ResultTypeId] = ResultTypeId;
+}
+/**
+ * The deadline a trampoline lineage's rounds share: the journaled first start
+ * of its originating round and the bound in milliseconds, so every round
+ * expires at `startedAtMs + deadlineMs`.
+ *
+ * @category results
+ * @since 1.0.0
+ */
+export const LineageDeadline = Schema.Struct({
+    startedAtMs: Schema.Number,
+    deadlineMs: Schema.Number
+});
+/**
+ * Represents a flow round that ended by handing off to the next round of its
+ * trampoline lineage.
+ *
+ * A round settles this way when its body's root value is a `to` invocation
+ * (`docs/concepts/trampoline-rounds.md`): the round produced no answer of
+ * its own, it produced the NEXT flow to run. `flow` is the target's tag, so the
+ * value survives the journal and the run row unchanged.
+ *
+ * DECIDED: `payload` is the target's payload in
+ * ENCODED form. The target's `to` method accepts its ordinary constructor
+ * shape so authoring stays aligned with `call` and `execute`; the body
+ * interpreter resolves planned references and encodes the invocation through
+ * the target declaration before constructing `Handoff`. The receiving round
+ * decodes those bytes through the same schema.
+ *
+ * It is a third settlement rather than a `Complete` carrying a magic value
+ * because the engine has to tell "this run answered" from "this run continues
+ * elsewhere" without decoding against a success schema the handoff never
+ * satisfies.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export class Handoff extends Schema.Class("@smthrs/flow/Flow/Handoff")({
+    _tag: Schema.tag("Handoff"),
+    flow: Schema.NonEmptyString,
+    capabilityCeilings: Schema.optionalKey(Schema.Array(Schema.Array(CapabilityPattern))),
+    payload: Schema.Unknown,
+    /**
+     * The lineage deadline the next round runs under, stamped by the round
+     * that handed off when its lineage is bounded (`Deadline.bound`).
+     */
+    deadline: Schema.optionalKey(LineageDeadline)
+}) {
+    /**
+     * Marks this value as a flow result for runtime guards.
+     *
+     * @since 0.1.0
+     */
+    [ResultTypeId] = ResultTypeId;
+}
+/**
+ * Creates a schema for flow results using the supplied success and error
+ * schemas.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export const Result = (options) => Schema.Union([Complete.Schema(options), Suspended, Handoff]);
+const AnyOrVoid = Schema.Union([Schema.Any, Schema.Void]);
+/**
+ * Schema for encoded flow results with generic success and error payloads.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export const ResultEncoded = Schema.toEncoded(Schema.toCodecJson(Result({
+    success: AnyOrVoid,
+    error: AnyOrVoid
+})));
+//# sourceMappingURL=Result.js.map