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

package/dist/esm/DurableDeferred.d.ts

@@ -0,0 +1,311 @@
+import type { NonEmptyReadonlyArray } from "effect/Array";
+import type * as Brand from "effect/Brand";
+import * as Cause from "effect/Cause";
+import type * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Schema from "effect/Schema";
+import * as Flow from "./Flow/index.ts";
+import { FlowInstance } from "./FlowRuntime/FlowInstance.ts";
+import { FlowRuntime } from "./FlowRuntime/FlowRuntime.ts";
+declare const TypeId = "@smthrs/flow/DurableDeferred";
+/**
+ * Named durable deferred value whose completion is persisted by the flow
+ * engine and encoded with success and error schemas.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface DurableDeferred<Success extends Schema.Constraint, Error extends Schema.Constraint = Schema.Never> {
+    readonly [TypeId]: typeof TypeId;
+    readonly name: string;
+    readonly successSchema: Success;
+    readonly errorSchema: Error;
+    readonly exitSchema: Schema.Exit<Schema.Top, Schema.Top, Schema.Top>;
+    readonly withActionAttempt: Effect.Effect<DurableDeferred<Success, Error>>;
+}
+/**
+ * Type-erased durable deferred shape for APIs that only need the deferred
+ * identity and name.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Any {
+    readonly [TypeId]: typeof TypeId;
+    readonly name: string;
+}
+/**
+ * Type-erased durable deferred shape that also exposes success, error, and
+ * exit schemas.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface AnyWithProps {
+    readonly [TypeId]: typeof TypeId;
+    readonly name: string;
+    readonly successSchema: Schema.Top;
+    readonly errorSchema: Schema.Top;
+    readonly exitSchema: Schema.Exit<any, any, any>;
+}
+/**
+ * Creates a named durable deferred with optional success and error schemas for
+ * persisted completion.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: <Success extends Schema.Constraint = Schema.Void, Error extends Schema.Constraint = Schema.Never>(name: string, options?: {
+    readonly success?: Success | undefined;
+    readonly error?: Error | undefined;
+}) => DurableDeferred<Success, Error>;
+declare const await_: <Success extends Schema.Constraint, Error extends Schema.Constraint>(self: DurableDeferred<Success, Error>) => Effect.Effect<Success["Type"], Error["Type"], FlowRuntime | FlowInstance | Success["DecodingServices"] | Error["DecodingServices"]>;
+export { 
+/**
+ * Waits for the durable deferred, suspending the current flow when no
+ * persisted completion is available.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+await_ as await };
+/**
+ * Runs an effect and records its exit into the durable deferred, resuming
+ * flows that are waiting on that deferred.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export declare const into: {
+    <Success extends Schema.Constraint, Error extends Schema.Constraint>(self: DurableDeferred<Success, Error>): <R>(effect: Effect.Effect<Success["Type"], Error["Type"], R>) => Effect.Effect<Success["Type"], Error["Type"], R | FlowRuntime | FlowInstance | Success["DecodingServices"] | Success["EncodingServices"] | Error["DecodingServices"] | Error["EncodingServices"]>;
+    <Success extends Schema.Constraint, Error extends Schema.Constraint, R>(effect: Effect.Effect<Success["Type"], Error["Type"], R>, self: DurableDeferred<Success, Error>): Effect.Effect<Success["Type"], Error["Type"], R | FlowRuntime | FlowInstance | Success["DecodingServices"] | Success["EncodingServices"] | Error["DecodingServices"] | Error["EncodingServices"]>;
+};
+/**
+ * Runs effects as a durable race, returning a previously persisted result when
+ * present or completing a named deferred with the first success. The race
+ * fails only when every effect fails.
+ *
+ * @category racing
+ * @since 0.1.0
+ */
+export declare const raceAll: <const Effects extends NonEmptyReadonlyArray<Effect.Effect<any, any, any>>, Success extends Schema.Schema<Effect.Success<Effects[number]>>, Error extends Schema.Schema<Effect.Error<Effects[number]>>>(options: {
+    name: string;
+    success: Success;
+    error: Error;
+    effects: Effects;
+}) => Effect.Effect<Effect.Success<Effects[number]>, Effect.Error<Effects[number]>, Effect.Services<Effects[number]> | Success["DecodingServices"] | Success["EncodingServices"] | Error["DecodingServices"] | Error["EncodingServices"] | FlowRuntime | FlowInstance>;
+/**
+ * Runtime brand identifier for durable deferred tokens.
+ *
+ * @category type IDs
+ * @since 0.1.0
+ */
+export declare const TokenTypeId = "@smthrs/flow/DurableDeferred/Token";
+/**
+ * Type-level brand identifier for `Token` values.
+ *
+ * @category type IDs
+ * @since 0.1.0
+ */
+export type TokenTypeId = typeof TokenTypeId;
+/**
+ * Branded string token identifying a durable deferred for a flow
+ * execution.
+ *
+ * A token is an address, not a credential. It is unsigned base64url JSON of
+ * the flow name, execution id, and deferred name, and `tokenFromExecutionId`
+ * and `tokenFromPayload` rebuild it from those values alone. Anyone who can
+ * call `done`, `succeed`, `fail`, `failCause`, or `HumanTask.answer` against
+ * the run's `FlowRuntime` can complete an open wait whose address they know or
+ * derive. A host that exposes completion to other parties must authorize the
+ * caller before it calls one of them.
+ *
+ * @category token
+ * @since 0.1.0
+ */
+export type Token = Brand.Branded<string, TokenTypeId>;
+/**
+ * Schema for branded durable deferred tokens.
+ *
+ * @category token
+ * @since 0.1.0
+ */
+export declare const Token: Schema.brand<Schema.String, TokenTypeId>;
+declare const TokenInvalid_base: Schema.Class<TokenInvalid, Schema.TaggedStruct<"@smthrs/flow/DurableDeferred/TokenInvalid", {
+    readonly code: Schema.withConstructorDefault<Schema.Literals<readonly ["malformed_token", "deferred_mismatch"]>>;
+    readonly message: Schema.String;
+}>, Cause.YieldableError>;
+/**
+ * A completion token could not be decoded into its durable address.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class TokenInvalid extends TokenInvalid_base {
+}
+declare const TokenParsed_base: Schema.Class<TokenParsed, Schema.Struct<{
+    readonly flowName: Schema.String;
+    readonly executionId: Schema.String;
+    readonly deferredName: Schema.String;
+}>, {}>;
+/**
+ * Schema for a decoded durable deferred token containing the flow
+ * name, execution ID, and deferred name.
+ *
+ * @category token
+ * @since 0.1.0
+ */
+export declare class TokenParsed extends TokenParsed_base {
+    /**
+     * Encodes the parsed flow, execution, and deferred names back into a token.
+     *
+     * @since 0.1.0
+     */
+    get asToken(): Token;
+    /**
+     * Schema for decoding and encoding durable deferred tokens as strings.
+     *
+     * @since 0.1.0
+     */
+    static readonly FromString: Schema.decodeTo<typeof TokenParsed, Schema.decodeTo<Schema.fromJsonString<Schema.Tuple<readonly [Schema.String, Schema.String, Schema.String]>>, Schema.String, never, never>, never, never>;
+    /**
+     * Decodes a durable deferred token string into its parsed components.
+     *
+     * @since 0.1.0
+     */
+    static readonly fromString: (input: string, options?: import("effect/SchemaAST").ParseOptions) => TokenParsed;
+    /**
+     * Encodes parsed durable deferred token components into a token string.
+     *
+     * @since 0.1.0
+     */
+    static readonly encode: (input: TokenParsed, options?: import("effect/SchemaAST").ParseOptions) => string;
+    /**
+     * Parses an untrusted token into its durable address with a typed,
+     * bounded diagnostic on failure.
+     *
+     * @category token
+     * @since 1.0.0
+     */
+    static readonly parse: (token: string) => Effect.Effect<TokenParsed, TokenInvalid>;
+}
+/**
+ * Creates a token for a durable deferred using the current flow instance's
+ * flow name and execution ID.
+ *
+ * @category token
+ * @since 0.1.0
+ */
+export declare const token: <Success extends Schema.Constraint, Error extends Schema.Constraint>(self: DurableDeferred<Success, Error>) => Effect.Effect<Token, never, FlowInstance>;
+/**
+ * Creates a durable deferred token from an explicit flow, execution ID,
+ * and deferred name.
+ *
+ * @category token
+ * @since 0.1.0
+ */
+export declare const tokenFromExecutionId: {
+    (options: {
+        readonly flow: Flow.Any;
+        readonly executionId: string;
+    }): <Success extends Schema.Constraint, Error extends Schema.Constraint>(self: DurableDeferred<Success, Error>) => Token;
+    <Success extends Schema.Constraint, Error extends Schema.Constraint>(self: DurableDeferred<Success, Error>, options: {
+        readonly flow: Flow.Any;
+        readonly executionId: string;
+    }): Token;
+};
+/**
+ * Creates a durable deferred token by deriving the flow execution ID from
+ * the supplied flow payload.
+ *
+ * The payload identifies a previously started execution only when the flow
+ * declares `idempotencyKey` or the host installs the opt-in `derived`
+ * execution-id source. Otherwise the default `fresh` source mints a new
+ * execution ID on every call, so the token addresses no earlier run. To
+ * complete an existing execution without stable identity, keep its execution
+ * ID and use {@link tokenFromExecutionId}.
+ *
+ * @category token
+ * @since 0.1.0
+ */
+export declare const tokenFromPayload: {
+    <W extends Flow.Any>(options: {
+        readonly flow: W;
+        readonly payload: Flow.PayloadSchema<W>["~type.make.in"];
+    }): <Success extends Schema.Constraint, Error extends Schema.Constraint>(self: DurableDeferred<Success, Error>) => Effect.Effect<Token, never, Crypto.Crypto | Flow.PayloadSchema<W>["EncodingServices"]>;
+    <Success extends Schema.Constraint, Error extends Schema.Constraint, W extends Flow.Any>(self: DurableDeferred<Success, Error>, options: {
+        readonly flow: W;
+        readonly payload: Flow.PayloadSchema<W>["~type.make.in"];
+    }): Effect.Effect<Token, never, Crypto.Crypto | Flow.PayloadSchema<W>["EncodingServices"]>;
+};
+/**
+ * Completes the durable deferred identified by a token with the supplied exit,
+ * encoding the result through the deferred schemas.
+ *
+ * The token is not a credential (see {@link Token}): authorize the caller
+ * before completing a wait on its behalf.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export declare const done: {
+    <Success extends Schema.Constraint, Error extends Schema.Constraint>(options: {
+        readonly token: Token;
+        readonly exit: Exit.Exit<Success["Type"], Error["Type"]>;
+    }): (self: DurableDeferred<Success, Error>) => Effect.Effect<void, TokenInvalid, FlowRuntime | Success["EncodingServices"] | Error["EncodingServices"]>;
+    <Success extends Schema.Constraint, Error extends Schema.Constraint>(self: DurableDeferred<Success, Error>, options: {
+        readonly token: Token;
+        readonly exit: Exit.Exit<Success["Type"], Error["Type"]>;
+    }): Effect.Effect<void, TokenInvalid, FlowRuntime | Success["EncodingServices"] | Error["EncodingServices"]>;
+};
+/**
+ * Completes the durable deferred identified by a token with a successful
+ * value.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export declare const succeed: {
+    <Success extends Schema.Constraint, Error extends Schema.Constraint>(options: {
+        readonly token: Token;
+        readonly value: Success["Type"];
+    }): (self: DurableDeferred<Success, Error>) => Effect.Effect<void, TokenInvalid, FlowRuntime | Success["EncodingServices"]>;
+    <Success extends Schema.Constraint, Error extends Schema.Constraint>(self: DurableDeferred<Success, Error>, options: {
+        readonly token: Token;
+        readonly value: Success["Type"];
+    }): Effect.Effect<void, TokenInvalid, FlowRuntime | Success["EncodingServices"]>;
+};
+/**
+ * Completes the durable deferred identified by a token with a typed failure.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export declare const fail: {
+    <Success extends Schema.Constraint, Error extends Schema.Constraint>(options: {
+        readonly token: Token;
+        readonly error: Error["Type"];
+    }): (self: DurableDeferred<Success, Error>) => Effect.Effect<void, TokenInvalid, FlowRuntime | Error["EncodingServices"]>;
+    <Success extends Schema.Constraint, Error extends Schema.Constraint>(self: DurableDeferred<Success, Error>, options: {
+        readonly token: Token;
+        readonly error: Error["Type"];
+    }): Effect.Effect<void, TokenInvalid, FlowRuntime | Error["EncodingServices"]>;
+};
+/**
+ * Completes the durable deferred identified by a token with a failure cause.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export declare const failCause: {
+    <Success extends Schema.Constraint, Error extends Schema.Constraint>(options: {
+        readonly token: Token;
+        readonly cause: Cause.Cause<Error["Type"]>;
+    }): (self: DurableDeferred<Success, Error>) => Effect.Effect<void, TokenInvalid, FlowRuntime | Error["EncodingServices"]>;
+    <Success extends Schema.Constraint, Error extends Schema.Constraint>(self: DurableDeferred<Success, Error>, options: {
+        readonly token: Token;
+        readonly cause: Cause.Cause<Error["Type"]>;
+    }): Effect.Effect<void, TokenInvalid, FlowRuntime | Error["EncodingServices"]>;
+};
+//# sourceMappingURL=DurableDeferred.d.ts.map

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

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

package/dist/esm/DurableDeferred.js

@@ -0,0 +1,357 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+/**
+ * Defines named wait points for durable flow executions.
+ *
+ * A `DurableDeferred` has a stable name and schemas for the value that will be
+ * recorded later. Flows can await it, suspend when no result exists yet, and
+ * resume after its result is recorded. Tokens identify the flow name,
+ * execution id, and deferred name so external code can complete the correct
+ * wait point later.
+ *
+ * @since 0.1.0
+ */
+import * as Arr from "effect/Array";
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Base64Url from "effect/encoding/Base64Url";
+import * as Exit from "effect/Exit";
+import * as Filter from "effect/Filter";
+import { dual } from "effect/Function";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SchemaGetter from "effect/SchemaGetter";
+import { CurrentAttempt } from "./Action/Context.js";
+import * as Flow from "./Flow/index.js";
+import { FlowInstance } from "./FlowRuntime/FlowInstance.js";
+import { FlowRuntime } from "./FlowRuntime/FlowRuntime.js";
+const TypeId = "@smthrs/flow/DurableDeferred";
+// Queues, human tasks and clocks mint a deferred per item, attempt or sleep.
+// Effect caches compiled parsers by AST identity, so the exit schema is shared
+// per (success, error) pair rather than rebuilt for every deferred.
+const exitSchemaCache = new WeakMap();
+const exitSchemaFor = (success, error) => {
+    let byError = exitSchemaCache.get(success);
+    if (byError === undefined) {
+        byError = new WeakMap();
+        exitSchemaCache.set(success, byError);
+    }
+    let cached = byError.get(error);
+    if (cached === undefined) {
+        cached = Schema.Exit(Schema.toCodecJson(success), Schema.toCodecJson(error), Schema.toCodecJson(Schema.Defect()));
+        byError.set(error, cached);
+    }
+    return cached;
+};
+/**
+ * Creates a named durable deferred with optional success and error schemas for
+ * persisted completion.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (name, options) => {
+    const successSchema = options?.success ?? Schema.Void;
+    const errorSchema = options?.error ?? Schema.Never;
+    return {
+        [TypeId]: TypeId,
+        name,
+        successSchema,
+        errorSchema,
+        exitSchema: exitSchemaFor(successSchema, errorSchema),
+        withActionAttempt: Effect.gen(function* () {
+            const attempt = yield* CurrentAttempt;
+            return make(`${name}/${attempt}`, {
+                success: successSchema,
+                error: errorSchema
+            });
+        })
+    };
+};
+const await_ = 
+// Untraced because deferred polling participates in the flow scheduler hot path.
+Effect.fnUntraced(function* (self) {
+    const engine = yield* FlowRuntime;
+    const instance = yield* FlowInstance;
+    const exit = yield* Flow.wrapActionResult(engine.deferredResult(self), Option.isNone);
+    if (Option.isNone(exit)) {
+        return yield* Flow.suspend(instance);
+    }
+    const value = exit.value;
+    // A recorded interruption is a durable *outcome*, not a request to
+    // suspend: mark the instance interrupted before re-raising so
+    // `Flow.intoResult` classifies the interrupt-only cause as a `Complete`
+    // failure. Without this the driver mistakes the cause for an external
+    // suspension interrupt, aborts without a terminal transition, and the
+    // run spins in the suspended-retry loop forever.
+    if (Exit.isFailure(value) && Cause.hasInterruptsOnly(value.cause)) {
+        instance.interrupted = true;
+    }
+    return yield* value;
+});
+export { 
+/**
+ * Waits for the durable deferred, suspending the current flow when no
+ * persisted completion is available.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+await_ as await };
+/**
+ * Runs an effect and records its exit into the durable deferred, resuming
+ * flows that are waiting on that deferred.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export const into = dual(2, (effect, self) => Effect.contextWith((context) => {
+    const engine = Context.get(context, FlowRuntime);
+    const instance = Context.get(context, FlowInstance);
+    // Keep the original instance: action regions identify their ancestors
+    // by reference, and suspension metadata belongs to the enclosing flow.
+    return Effect.onExit(effect, 
+    // Untraced because completion encoding is called for each deferred result.
+    Effect.fnUntraced(function* (exit) {
+        if (Exit.isFailure(exit)) {
+            const [interrupts, reasons] = Arr.partition(exit.cause.reasons, Filter.fromPredicate(Cause.isInterruptReason));
+            const hasInterruptsOnly = interrupts.length === exit.cause.reasons.length;
+            if (hasInterruptsOnly) {
+                // An interrupt-only exit is never a result: the effect was
+                // suspended, preempted, or interrupted, so record nothing.
+                // Recording here would durably persist the empty non-interrupt
+                // partition, and first-writer-wins would replay that empty
+                // cause forever instead of the real completion.
+                return;
+            }
+            else if (interrupts.length > 0) {
+                exit = Exit.failCause(Cause.fromReasons(reasons));
+            }
+        }
+        yield* engine.deferredDone(self, {
+            flowName: instance.flow._tag,
+            executionId: instance.executionId,
+            deferredName: self.name,
+            exit
+        });
+    }));
+}));
+/**
+ * Runs effects as a durable race, returning a previously persisted result when
+ * present or completing a named deferred with the first success. The race
+ * fails only when every effect fails.
+ *
+ * @category racing
+ * @since 0.1.0
+ */
+export const raceAll = (options) => {
+    const deferred = make(`raceAll/${options.name}`, {
+        success: options.success,
+        error: options.error
+    });
+    return Effect.gen(function* () {
+        const engine = yield* FlowRuntime;
+        const exit = yield* engine.deferredResult(deferred);
+        if (Option.isSome(exit)) {
+            return yield* exit.value;
+        }
+        return yield* into(Effect.raceAll(options.effects), deferred);
+    });
+};
+/**
+ * Runtime brand identifier for durable deferred tokens.
+ *
+ * @category type IDs
+ * @since 0.1.0
+ */
+export const TokenTypeId = "@smthrs/flow/DurableDeferred/Token";
+/**
+ * Schema for branded durable deferred tokens.
+ *
+ * @category token
+ * @since 0.1.0
+ */
+export const Token = Schema.String.pipe(Schema.brand(TokenTypeId));
+/**
+ * A completion token could not be decoded into its durable address.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class TokenInvalid extends Schema.TaggedError()("@smthrs/flow/DurableDeferred/TokenInvalid", {
+    code: Schema.Literals(["malformed_token", "deferred_mismatch"]).pipe(Schema.withConstructorDefault(Effect.succeed("malformed_token"))),
+    message: Schema.String
+}) {
+}
+/**
+ * Schema for a decoded durable deferred token containing the flow
+ * name, execution ID, and deferred name.
+ *
+ * @category token
+ * @since 0.1.0
+ */
+export class TokenParsed extends Schema.Class("@smthrs/flow/DurableDeferred/TokenParsed")({
+    flowName: Schema.String,
+    executionId: Schema.String,
+    deferredName: Schema.String
+}) {
+    /**
+     * Encodes the parsed flow, execution, and deferred names back into a token.
+     *
+     * @since 0.1.0
+     */
+    get asToken() {
+        return Base64Url.encode(JSON.stringify([this.flowName, this.executionId, this.deferredName]));
+    }
+    /**
+     * Schema for decoding and encoding durable deferred tokens as strings.
+     *
+     * @since 0.1.0
+     */
+    static FromString = Schema.String.pipe(Schema.decodeTo(Schema.fromJsonString(Schema.Tuple([Schema.String, Schema.String, Schema.String])), {
+        decode: SchemaGetter.decodeBase64UrlString(),
+        encode: SchemaGetter.encodeBase64Url()
+    }), Schema.decodeTo(TokenParsed, {
+        decode: SchemaGetter.transform(([flowName, executionId, deferredName]) => new TokenParsed({
+            flowName,
+            executionId,
+            deferredName
+        })),
+        encode: SchemaGetter.transform((parsed) => [
+            parsed.flowName,
+            parsed.executionId,
+            parsed.deferredName
+        ])
+    }));
+    /**
+     * Decodes a durable deferred token string into its parsed components.
+     *
+     * @since 0.1.0
+     */
+    static fromString = Schema.decodeSync(TokenParsed.FromString);
+    /**
+     * Encodes parsed durable deferred token components into a token string.
+     *
+     * @since 0.1.0
+     */
+    static encode = Schema.encodeSync(TokenParsed.FromString);
+    /**
+     * Parses an untrusted token into its durable address with a typed,
+     * bounded diagnostic on failure.
+     *
+     * @category token
+     * @since 1.0.0
+     */
+    static parse = (token) => Effect.mapError(Schema.decodeEffect(TokenParsed.FromString)(token), (issue) => new TokenInvalid({
+        message: `The supplied token "${tokenExcerpt(token)}" is not a durable deferred token: ${issue.message}`
+    }));
+}
+const maxTokenExcerptChars = 64;
+/** Renders a bounded excerpt of untrusted token content for a diagnostic. */
+const tokenExcerpt = (token) => token.length <= maxTokenExcerptChars
+    ? token
+    : `${token.slice(0, maxTokenExcerptChars)} [${token.length - maxTokenExcerptChars} characters dropped]`;
+/**
+ * Creates a token for a durable deferred using the current flow instance's
+ * flow name and execution ID.
+ *
+ * @category token
+ * @since 0.1.0
+ */
+export const token = 
+// Untraced because token allocation is on the durable-deferred hot path.
+Effect.fnUntraced(function* (self) {
+    const instance = yield* FlowInstance;
+    return tokenFromExecutionId(self, instance);
+});
+/**
+ * Creates a durable deferred token from an explicit flow, execution ID,
+ * and deferred name.
+ *
+ * @category token
+ * @since 0.1.0
+ */
+export const tokenFromExecutionId = dual(2, (self, options) => new TokenParsed({
+    flowName: options.flow._tag,
+    executionId: options.executionId,
+    deferredName: self.name
+}).asToken);
+/**
+ * Creates a durable deferred token by deriving the flow execution ID from
+ * the supplied flow payload.
+ *
+ * The payload identifies a previously started execution only when the flow
+ * declares `idempotencyKey` or the host installs the opt-in `derived`
+ * execution-id source. Otherwise the default `fresh` source mints a new
+ * execution ID on every call, so the token addresses no earlier run. To
+ * complete an existing execution without stable identity, keep its execution
+ * ID and use {@link tokenFromExecutionId}.
+ *
+ * @category token
+ * @since 0.1.0
+ */
+export const tokenFromPayload = dual(2, (self, options) => Effect.map(options.flow.executionId(options.payload), (executionId) => tokenFromExecutionId(self, {
+    flow: options.flow,
+    executionId
+})));
+/**
+ * Completes the durable deferred identified by a token with the supplied exit,
+ * encoding the result through the deferred schemas.
+ *
+ * The token is not a credential (see {@link Token}): authorize the caller
+ * before completing a wait on its behalf.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export const done = dual(2, 
+// Untraced because awaiting a deferred re-enters the scheduler recursively.
+Effect.fnUntraced(function* (self, options) {
+    const token = yield* TokenParsed.parse(options.token);
+    if (token.deferredName !== self.name) {
+        return yield* Effect.fail(new TokenInvalid({
+            code: "deferred_mismatch",
+            message: `The token addresses deferred "${tokenExcerpt(token.deferredName)}", but it was submitted through ` +
+                `deferred "${self.name}".`
+        }));
+    }
+    const engine = yield* FlowRuntime;
+    yield* engine.deferredDone(self, {
+        flowName: token.flowName,
+        executionId: token.executionId,
+        deferredName: token.deferredName,
+        exit: options.exit
+    });
+}));
+/**
+ * Completes the durable deferred identified by a token with a successful
+ * value.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export const succeed = dual(2, (self, options) => done(self, {
+    token: options.token,
+    exit: Exit.succeed(options.value)
+}));
+/**
+ * Completes the durable deferred identified by a token with a typed failure.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export const fail = dual(2, (self, options) => done(self, {
+    token: options.token,
+    exit: Exit.fail(options.error)
+}));
+/**
+ * Completes the durable deferred identified by a token with a failure cause.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export const failCause = dual(2, (self, options) => done(self, {
+    token: options.token,
+    exit: Exit.failCause(options.cause)
+}));
+//# sourceMappingURL=DurableDeferred.js.map