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

package/dist/esm/DurableDeferred.js.map

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

package/dist/esm/DurableQueue.d.ts

@@ -0,0 +1,160 @@
+import type * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+import * as PersistedQueue from "effect/unstable/persistence/PersistedQueue";
+import * as DurableDeferred from "./DurableDeferred.ts";
+import { type FlowInstance, type FlowRuntime } from "./FlowRuntime/index.ts";
+/**
+ * Type-level identifier used to recognize `DurableQueue` values.
+ *
+ * @category type IDs
+ * @since 0.1.0
+ */
+export type TypeId = "@smthrs/flow/DurableQueue";
+/**
+ * Runtime identifier attached to `DurableQueue` values.
+ *
+ * @category type IDs
+ * @since 0.1.0
+ */
+export declare const TypeId: TypeId;
+/**
+ * Durable flow queue definition containing a payload schema, idempotency
+ * key, and deferred used to await worker results.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface DurableQueue<Payload extends Schema.Top, Success extends Schema.Top = Schema.Void, Error extends Schema.Top = Schema.Never> {
+    readonly [TypeId]: TypeId;
+    readonly name: string;
+    readonly payloadSchema: Payload;
+    readonly idempotencyKey: (payload: Payload["Type"]) => string;
+    readonly deferred: DurableDeferred.DurableDeferred<Success, Error>;
+}
+/**
+ * Creates a `DurableQueue` that waits for persisted items to finish processing
+ * using a `DurableDeferred`.
+ *
+ * **Example** (Defining a durable queue with workers)
+ *
+ * ```ts
+ * import { Action, DurableQueue, Flow, Interpreter } from "@smthrs/flow"
+ * import { Effect, Layer, Schema } from "effect"
+ *
+ * // Define a DurableQueue that can be used to derive workers and offer items for
+ * // processing.
+ * const ApiQueue = DurableQueue.make({
+ *   name: "ApiQueue",
+ *   payload: {
+ *     id: Schema.String
+ *   },
+ *   success: Schema.Void,
+ *   error: Schema.Never,
+ *   idempotencyKey(payload) {
+ *     return payload.id
+ *   }
+ * })
+ *
+ * // Offering an item is work, so it is a declared Action: the declaration is
+ * // pure data, and the implementation attaches separately.
+ * const Offer = Action.make("MyFlow/offer", {
+ *   payload: {
+ *     id: Schema.String
+ *   }
+ * })
+ *
+ * const OfferLive = Offer.toLayer(
+ *   Effect.fnUntraced(function*({ id }) {
+ *     // Add an item to the DurableQueue defined above.
+ *     //
+ *     // When the worker has finished processing the item, the flow will
+ *     // resume.
+ *     //
+ *     yield* DurableQueue.process(ApiQueue, { id })
+ *
+ *     yield* Effect.log("Flow succeeded!")
+ *   })
+ * )
+ *
+ * // The flow is the composite, and its body names the step it is made of.
+ * const MyFlow = Flow.make("MyFlow", {
+ *   payload: {
+ *     id: Schema.String
+ *   },
+ *   idempotencyKey: ({ id }) => id,
+ *   body: (payload) => Offer.call(payload)
+ * })
+ *
+ * const MyFlowLayer = Layer.mergeAll(OfferLive, Interpreter.layer(MyFlow)).pipe(
+ *   Layer.provideMerge(Action.layerImplementations)
+ * )
+ *
+ * // Define a worker layer that can process items from the DurableQueue.
+ * const ApiWorker = DurableQueue.worker(
+ *   ApiQueue,
+ *   Effect.fnUntraced(function*({ id }) {
+ *     yield* Effect.log(`Worker processing API call with id: ${id}`)
+ *   }),
+ *   { concurrency: 5 } // Process up to 5 items concurrently
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: <Payload extends Schema.Top | Schema.Struct.Fields, Success extends Schema.Top = Schema.Void, Error extends Schema.Top = Schema.Never>(options: {
+    readonly name: string;
+    readonly payload: Payload;
+    readonly idempotencyKey: (payload: Payload extends Schema.Struct.Fields ? Schema.Struct.Type<Payload> : Payload["Type"]) => string;
+    readonly success?: Success | undefined;
+    readonly error?: Error | undefined;
+}) => DurableQueue<Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload, Success, Error>;
+/**
+ * Adds an item to the queue and waits for a worker to process it.
+ *
+ * `retrySchedule` controls retries when the persisted offer fails. The default
+ * is unbounded, with exponential delays capped at one minute, so a transient
+ * store outage does not lose the item. A caller-supplied schedule may exhaust;
+ * its final offer failure becomes a defect to keep the public error channel
+ * reserved for the worker's declared error.
+ *
+ * Payload construction also becomes a defect when `fields` does not satisfy
+ * the queue's payload schema. The public error channel is the worker result,
+ * not malformed caller input.
+ *
+ * @category processing
+ * @since 0.1.0
+ */
+export declare const process: <Payload extends Schema.Top, Success extends Schema.Top, Error extends Schema.Top>(self: DurableQueue<Payload, Success, Error>, payload: Payload["~type.make.in"], options?: {
+    readonly retrySchedule?: Schedule.Schedule<any, PersistedQueue.PersistedQueueError> | undefined;
+}) => Effect.Effect<Success["Type"], Error["Type"], FlowRuntime | FlowInstance | Crypto.Crypto | PersistedQueue.PersistedQueueFactory | Payload["EncodingServices"] | Payload["DecodingServices"] | Success["DecodingServices"] | Error["DecodingServices"]>;
+/**
+ * Create a worker effect that processes items from the durable queue.
+ *
+ * `concurrency` defaults to one and must be a positive safe integer. It is
+ * checked before the persisted queue is opened. `maxAttempts` defaults to ten
+ * and is passed to the persisted queue. Completion-write failures can rerun the
+ * handler; side effects must be idempotent. Exhaustion leaves the flow waiting.
+ *
+ * @throws A `RangeError` when `concurrency` is not a positive safe integer.
+ * @category worker
+ * @since 0.1.0
+ */
+export declare const makeWorker: <Payload extends Schema.Top, Success extends Schema.Top, Error extends Schema.Top, R>(self: DurableQueue<Payload, Success, Error>, f: (payload: Payload["Type"]) => Effect.Effect<Success["Type"], Error["Type"], R>, options?: {
+    readonly concurrency?: number | undefined;
+    readonly maxAttempts?: number | undefined;
+} | undefined) => Effect.Effect<never, never, FlowRuntime | PersistedQueue.PersistedQueueFactory | R | Payload["EncodingServices"] | Payload["DecodingServices"] | Success["EncodingServices"] | Error["EncodingServices"]>;
+/**
+ * Create a layer that runs workers for the durable queue.
+ *
+ * @category worker
+ * @since 0.1.0
+ */
+export declare const worker: <Payload extends Schema.Top, Success extends Schema.Top, Error extends Schema.Top, R>(self: DurableQueue<Payload, Success, Error>, f: (payload: Payload["Type"]) => Effect.Effect<Success["Type"], Error["Type"], R>, options?: {
+    readonly concurrency?: number | undefined;
+    readonly maxAttempts?: number | undefined;
+} | undefined) => Layer.Layer<never, never, FlowRuntime | PersistedQueue.PersistedQueueFactory | R | Payload["EncodingServices"] | Payload["DecodingServices"] | Success["EncodingServices"] | Error["EncodingServices"]>;
+//# sourceMappingURL=DurableQueue.d.ts.map

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

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

package/dist/esm/DurableQueue.js

@@ -0,0 +1,303 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+/**
+ * Durable flow queues delegate work to persisted background workers and
+ * resume the waiting flow with the worker result.
+ *
+ * A flow calls `process` to encode a payload, offer it to a named
+ * `PersistedQueue`, attach a `DurableDeferred` token, and suspend. A worker
+ * created with `makeWorker` or `worker` takes the item, runs the handler, and
+ * records the handler's `Exit` through that token so the original flow can
+ * continue with the typed success or error.
+ *
+ * @since 0.1.0
+ */
+import * as Arr from "effect/Array";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Filter from "effect/Filter";
+import * as Layer from "effect/Layer";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+import * as Tracer from "effect/Tracer";
+import * as PersistedQueue from "effect/unstable/persistence/PersistedQueue";
+import * as Action from "./Action/index.js";
+import * as DurableDeferred from "./DurableDeferred.js";
+import { annotateWaiting } from "./FlowRuntime/index.js";
+/**
+ * Runtime identifier attached to `DurableQueue` values.
+ *
+ * @category type IDs
+ * @since 0.1.0
+ */
+export const TypeId = "@smthrs/flow/DurableQueue";
+/**
+ * Creates a `DurableQueue` that waits for persisted items to finish processing
+ * using a `DurableDeferred`.
+ *
+ * **Example** (Defining a durable queue with workers)
+ *
+ * ```ts
+ * import { Action, DurableQueue, Flow, Interpreter } from "@smthrs/flow"
+ * import { Effect, Layer, Schema } from "effect"
+ *
+ * // Define a DurableQueue that can be used to derive workers and offer items for
+ * // processing.
+ * const ApiQueue = DurableQueue.make({
+ *   name: "ApiQueue",
+ *   payload: {
+ *     id: Schema.String
+ *   },
+ *   success: Schema.Void,
+ *   error: Schema.Never,
+ *   idempotencyKey(payload) {
+ *     return payload.id
+ *   }
+ * })
+ *
+ * // Offering an item is work, so it is a declared Action: the declaration is
+ * // pure data, and the implementation attaches separately.
+ * const Offer = Action.make("MyFlow/offer", {
+ *   payload: {
+ *     id: Schema.String
+ *   }
+ * })
+ *
+ * const OfferLive = Offer.toLayer(
+ *   Effect.fnUntraced(function*({ id }) {
+ *     // Add an item to the DurableQueue defined above.
+ *     //
+ *     // When the worker has finished processing the item, the flow will
+ *     // resume.
+ *     //
+ *     yield* DurableQueue.process(ApiQueue, { id })
+ *
+ *     yield* Effect.log("Flow succeeded!")
+ *   })
+ * )
+ *
+ * // The flow is the composite, and its body names the step it is made of.
+ * const MyFlow = Flow.make("MyFlow", {
+ *   payload: {
+ *     id: Schema.String
+ *   },
+ *   idempotencyKey: ({ id }) => id,
+ *   body: (payload) => Offer.call(payload)
+ * })
+ *
+ * const MyFlowLayer = Layer.mergeAll(OfferLive, Interpreter.layer(MyFlow)).pipe(
+ *   Layer.provideMerge(Action.layerImplementations)
+ * )
+ *
+ * // Define a worker layer that can process items from the DurableQueue.
+ * const ApiWorker = DurableQueue.worker(
+ *   ApiQueue,
+ *   Effect.fnUntraced(function*({ id }) {
+ *     yield* Effect.log(`Worker processing API call with id: ${id}`)
+ *   }),
+ *   { concurrency: 5 } // Process up to 5 items concurrently
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (options) => ({
+    [TypeId]: TypeId,
+    name: options.name,
+    payloadSchema: Schema.isSchema(options.payload)
+        ? options.payload
+        : Schema.Struct(options.payload),
+    idempotencyKey: options.idempotencyKey,
+    deferred: DurableDeferred.make(`DurableQueue/${options.name}`, {
+        success: options.success,
+        error: options.error
+    })
+});
+const queueSchemas = new WeakMap();
+const getQueueSchema = (payload) => {
+    let schema = queueSchemas.get(payload);
+    if (!schema) {
+        schema = Schema.Struct({
+            token: DurableDeferred.Token,
+            traceId: Schema.String,
+            spanId: Schema.String,
+            sampled: Schema.Boolean,
+            payload
+        });
+        queueSchemas.set(payload, schema);
+    }
+    return schema;
+};
+/**
+ * Adds an item to the queue and waits for a worker to process it.
+ *
+ * `retrySchedule` controls retries when the persisted offer fails. The default
+ * is unbounded, with exponential delays capped at one minute, so a transient
+ * store outage does not lose the item. A caller-supplied schedule may exhaust;
+ * its final offer failure becomes a defect to keep the public error channel
+ * reserved for the worker's declared error.
+ *
+ * Payload construction also becomes a defect when `fields` does not satisfy
+ * the queue's payload schema. The public error channel is the worker result,
+ * not malformed caller input.
+ *
+ * @category processing
+ * @since 0.1.0
+ */
+export const process = 
+// Untraced because queue offer is a worker hot path.
+Effect.fnUntraced(function* (self, fields, options) {
+    const payload = yield* self.payloadSchema.makeEffect(fields).pipe(Effect.mapError((issue) => new Schema.SchemaError(issue)), Effect.orDie);
+    const queueName = `DurableQueue/${self.name}`;
+    const queue = yield* PersistedQueue.make({
+        name: queueName,
+        schema: getQueueSchema(self.payloadSchema)
+    });
+    const key = yield* Action.idempotencyKey(queueName, {
+        parentScope: self.idempotencyKey(payload)
+    });
+    const deferred = DurableDeferred.make(`${self.deferred.name}/${key}`, {
+        success: self.deferred.successSchema,
+        error: self.deferred.errorSchema
+    });
+    const token = yield* DurableDeferred.token(deferred);
+    yield* Effect.useSpan(`DurableQueue/${self.name}/process`, {
+        attributes: { key }
+    }, (span) => queue.offer({
+        token,
+        payload,
+        traceId: span.traceId,
+        spanId: span.spanId,
+        sampled: span.sampled
+    }, { id: key }).pipe(Effect.tapCause(Effect.logWarning), Effect.catchTag("SchemaError", Effect.die), Effect.retry(options?.retrySchedule ?? defaultRetrySchedule), Effect.orDie, Effect.annotateLogs({
+        package: "@smthrs/flow",
+        module: "DurableQueue",
+        fiber: "process",
+        queueName: self.name
+    })));
+    yield* annotateWaiting({ reason: "event", token });
+    return yield* DurableDeferred.await(deferred);
+});
+const maxDeferredNameExcerptChars = 128;
+/** Renders a bounded excerpt of a stored deferred name for a diagnostic. */
+const deferredNameExcerpt = (name) => name.length <= maxDeferredNameExcerptChars
+    ? name
+    : `${name.slice(0, maxDeferredNameExcerptChars)} [${name.length - maxDeferredNameExcerptChars} characters dropped]`;
+const traceIdPattern = /^[0-9a-f]{32}$/;
+const spanIdPattern = /^[0-9a-f]{16}$/;
+/**
+ * The offering span as the worker span's parent, when the stored ids have the
+ * W3C trace-context shape every Effect and OpenTelemetry tracer writes. A
+ * stored item is not trusted to splice arbitrary identifiers into a trace.
+ */
+const externalParent = (item) => traceIdPattern.test(item.traceId) && spanIdPattern.test(item.spanId)
+    ? Tracer.externalSpan({ traceId: item.traceId, spanId: item.spanId, sampled: item.sampled })
+    : undefined;
+const defaultRetrySchedule = Schedule.min([
+    Schedule.exponential(500, 1.5),
+    Schedule.spaced("1 minute")
+]);
+const makeWorkerEffect = Effect.fnUntraced(function* (self, f, concurrency, maxAttempts) {
+    const queue = yield* PersistedQueue.make({
+        name: `DurableQueue/${self.name}`,
+        schema: getQueueSchema(self.payloadSchema),
+        maxAttempts,
+        // The worker owns the 500 ms retry pause below. Keep an upstream queue
+        // default from introducing an additional backoff after an Effect upgrade.
+        retrySchedule: Schedule.spaced(0)
+    });
+    const worker = Effect.suspend(() => {
+        let completion;
+        return queue.take((item_, metadata) => {
+            const item = item_;
+            return Effect.withSpan(Effect.gen(function* () {
+                // Parse before running the handler. A malformed completion address
+                // cannot strand a handler result that was already produced.
+                const parsed = yield* DurableDeferred.TokenParsed.parse(item.token);
+                // `process` offers each item under its key and addresses the
+                // deferred `<queue deferred>/<key>`. Anything else in this queue
+                // names a wait point the queue does not own (another queue's item,
+                // a WaitFor gate, a human task), so completing it here would settle
+                // a foreign wait under this queue's success schema.
+                const expected = `${self.deferred.name}/${metadata.id}`;
+                if (parsed.deferredName !== expected) {
+                    return yield* new DurableDeferred.TokenInvalid({
+                        code: "deferred_mismatch",
+                        message: `The item "${metadata.id}" addresses the deferred "${deferredNameExcerpt(parsed.deferredName)}", not "${deferredNameExcerpt(expected)}".`
+                    });
+                }
+                const deferred = DurableDeferred.make(parsed.deferredName, {
+                    success: self.deferred.successSchema,
+                    error: self.deferred.errorSchema
+                });
+                let exit = yield* Effect.exit(f(item.payload));
+                if (Exit.isFailure(exit)) {
+                    const [reasons, interrupts] = Arr.partition(exit.cause.reasons, Filter.fromPredicate(Cause.isInterruptReason));
+                    // Match DurableDeferred.into: interruption alone is not a durable
+                    // outcome, and must leave the item available without an attempt.
+                    if (interrupts.length === exit.cause.reasons.length) {
+                        return yield* Effect.failCause(Cause.fromReasons(interrupts));
+                    }
+                    else if (interrupts.length > 0) {
+                        exit = Exit.failCause(Cause.fromReasons(reasons));
+                    }
+                }
+                completion = { token: item.token, ...metadata };
+                yield* DurableDeferred.done(deferred, {
+                    token: item.token,
+                    exit
+                });
+            }).pipe(Effect.catchTag("@smthrs/flow/DurableDeferred/TokenInvalid", (error) => Effect.logError(`DurableQueue "${self.name}" could not complete an item because its token was invalid. ${error.message}`))), `DurableQueue/${self.name}/worker`, {
+                captureStackTrace: false,
+                parent: externalParent(item)
+            });
+        }).pipe(Effect.tapCause((cause) => {
+            if (!completion)
+                return Effect.void;
+            return Effect.logError("DurableQueue failed to persist or acknowledge a handler result", cause).pipe(Effect.annotateLogs({
+                token: completion.token,
+                itemId: completion.id,
+                attempt: completion.attempts,
+                maxAttempts,
+                exhausted: !Cause.hasInterrupts(cause) && completion.attempts >= maxAttempts
+            }));
+        }));
+    }).pipe(
+    // A persistently failing take would otherwise consume a core in a tight
+    // loop while the queue store is unavailable.
+    Effect.catchCause((cause) => Effect.logWarning(cause).pipe(Effect.andThen(Effect.sleep(500)))), Effect.forever, Effect.annotateLogs({
+        package: "@smthrs/flow",
+        module: "DurableQueue",
+        fiber: "worker",
+        queueName: self.name
+    }));
+    return yield* Effect.replicateEffect(worker, concurrency, { concurrency, discard: true }).pipe(Effect.andThen(Effect.never));
+});
+/**
+ * Create a worker effect that processes items from the durable queue.
+ *
+ * `concurrency` defaults to one and must be a positive safe integer. It is
+ * checked before the persisted queue is opened. `maxAttempts` defaults to ten
+ * and is passed to the persisted queue. Completion-write failures can rerun the
+ * handler; side effects must be idempotent. Exhaustion leaves the flow waiting.
+ *
+ * @throws A `RangeError` when `concurrency` is not a positive safe integer.
+ * @category worker
+ * @since 0.1.0
+ */
+export const makeWorker = (self, f, options) => {
+    const concurrency = options?.concurrency ?? 1;
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
+        throw new RangeError(`DurableQueue.makeWorker: concurrency must be a positive safe integer, and was ${concurrency}.`);
+    }
+    return makeWorkerEffect(self, f, concurrency, options?.maxAttempts ?? 10);
+};
+/**
+ * Create a layer that runs workers for the durable queue.
+ *
+ * @category worker
+ * @since 0.1.0
+ */
+export const worker = (self, f, options) => Layer.effectDiscard(Effect.forkScoped(makeWorker(self, f, options)));
+//# sourceMappingURL=DurableQueue.js.map

package/dist/esm/DurableQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DurableQueue.js","sourceRoot":"","sources":["../../src/DurableQueue.ts"],"names":[],"mappings":"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","sourcesContent":["// Deep reviewed and polished by a human on 2026-08-10.\n\n/**\n * Durable flow queues delegate work to persisted background workers and\n * resume the waiting flow with the worker result.\n *\n * A flow calls `process` to encode a payload, offer it to a named\n * `PersistedQueue`, attach a `DurableDeferred` token, and suspend. A worker\n * created with `makeWorker` or `worker` takes the item, runs the handler, and\n * records the handler's `Exit` through that token so the original flow can\n * continue with the typed success or error.\n *\n * @since 0.1.0\n */\n\nimport * as Arr from \"effect/Array\"\nimport * as Cause from \"effect/Cause\"\nimport type * as Crypto from \"effect/Crypto\"\nimport * as Effect from \"effect/Effect\"\nimport * as Exit from \"effect/Exit\"\nimport * as Filter from \"effect/Filter\"\nimport * as Layer from \"effect/Layer\"\nimport * as Schedule from \"effect/Schedule\"\nimport * as Schema from \"effect/Schema\"\nimport * as Tracer from \"effect/Tracer\"\nimport * as PersistedQueue from \"effect/unstable/persistence/PersistedQueue\"\nimport * as Action from \"./Action/index.ts\"\nimport * as DurableDeferred from \"./DurableDeferred.ts\"\nimport { annotateWaiting, type FlowInstance, type FlowRuntime } from \"./FlowRuntime/index.ts\"\n\n/**\n * Type-level identifier used to recognize `DurableQueue` values.\n *\n * @category type IDs\n * @since 0.1.0\n */\nexport type TypeId = \"@smthrs/flow/DurableQueue\"\n\n/**\n * Runtime identifier attached to `DurableQueue` values.\n *\n * @category type IDs\n * @since 0.1.0\n */\nexport const TypeId: TypeId = \"@smthrs/flow/DurableQueue\"\n\n/**\n * Durable flow queue definition containing a payload schema, idempotency\n * key, and deferred used to await worker results.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface DurableQueue<\n  Payload extends Schema.Top,\n  Success extends Schema.Top = Schema.Void,\n  Error extends Schema.Top = Schema.Never\n> {\n  readonly [TypeId]: TypeId\n  readonly name: string\n  readonly payloadSchema: Payload\n  readonly idempotencyKey: (payload: Payload[\"Type\"]) => string\n  readonly deferred: DurableDeferred.DurableDeferred<Success, Error>\n}\n\n/**\n * Creates a `DurableQueue` that waits for persisted items to finish processing\n * using a `DurableDeferred`.\n *\n * **Example** (Defining a durable queue with workers)\n *\n * ```ts\n * import { Action, DurableQueue, Flow, Interpreter } from \"@smthrs/flow\"\n * import { Effect, Layer, Schema } from \"effect\"\n *\n * // Define a DurableQueue that can be used to derive workers and offer items for\n * // processing.\n * const ApiQueue = DurableQueue.make({\n *   name: \"ApiQueue\",\n *   payload: {\n *     id: Schema.String\n *   },\n *   success: Schema.Void,\n *   error: Schema.Never,\n *   idempotencyKey(payload) {\n *     return payload.id\n *   }\n * })\n *\n * // Offering an item is work, so it is a declared Action: the declaration is\n * // pure data, and the implementation attaches separately.\n * const Offer = Action.make(\"MyFlow/offer\", {\n *   payload: {\n *     id: Schema.String\n *   }\n * })\n *\n * const OfferLive = Offer.toLayer(\n *   Effect.fnUntraced(function*({ id }) {\n *     // Add an item to the DurableQueue defined above.\n *     //\n *     // When the worker has finished processing the item, the flow will\n *     // resume.\n *     //\n *     yield* DurableQueue.process(ApiQueue, { id })\n *\n *     yield* Effect.log(\"Flow succeeded!\")\n *   })\n * )\n *\n * // The flow is the composite, and its body names the step it is made of.\n * const MyFlow = Flow.make(\"MyFlow\", {\n *   payload: {\n *     id: Schema.String\n *   },\n *   idempotencyKey: ({ id }) => id,\n *   body: (payload) => Offer.call(payload)\n * })\n *\n * const MyFlowLayer = Layer.mergeAll(OfferLive, Interpreter.layer(MyFlow)).pipe(\n *   Layer.provideMerge(Action.layerImplementations)\n * )\n *\n * // Define a worker layer that can process items from the DurableQueue.\n * const ApiWorker = DurableQueue.worker(\n *   ApiQueue,\n *   Effect.fnUntraced(function*({ id }) {\n *     yield* Effect.log(`Worker processing API call with id: ${id}`)\n *   }),\n *   { concurrency: 5 } // Process up to 5 items concurrently\n * )\n * ```\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = <\n  Payload extends Schema.Top | Schema.Struct.Fields,\n  Success extends Schema.Top = Schema.Void,\n  Error extends Schema.Top = Schema.Never\n>(options: {\n  readonly name: string\n  readonly payload: Payload\n  readonly idempotencyKey: (\n    payload: Payload extends Schema.Struct.Fields ? Schema.Struct.Type<Payload>\n      : Payload[\"Type\"]\n  ) => string\n  readonly success?: Success | undefined\n  readonly error?: Error | undefined\n}): DurableQueue<\n  Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload,\n  Success,\n  Error\n> => ({\n  [TypeId]: TypeId,\n  name: options.name,\n  payloadSchema: Schema.isSchema(options.payload)\n    ? options.payload\n    : Schema.Struct(options.payload as any) as any,\n  idempotencyKey: options.idempotencyKey as any,\n  deferred: DurableDeferred.make(`DurableQueue/${options.name}`, {\n    success: options.success,\n    error: options.error\n  })\n})\n\nconst queueSchemas = new WeakMap<Schema.Top, Schema.Top>()\n\nconst getQueueSchema = <Payload extends Schema.Top>(\n  payload: Payload\n): Schema.Struct<{\n  token: typeof DurableDeferred.Token\n  payload: Payload\n  traceId: typeof Schema.String\n  spanId: typeof Schema.String\n  sampled: typeof Schema.Boolean\n}> => {\n  let schema = queueSchemas.get(payload)\n  if (!schema) {\n    schema = Schema.Struct({\n      token: DurableDeferred.Token,\n      traceId: Schema.String,\n      spanId: Schema.String,\n      sampled: Schema.Boolean,\n      payload\n    })\n    queueSchemas.set(payload, schema)\n  }\n  return schema as any\n}\n\n/**\n * Adds an item to the queue and waits for a worker to process it.\n *\n * `retrySchedule` controls retries when the persisted offer fails. The default\n * is unbounded, with exponential delays capped at one minute, so a transient\n * store outage does not lose the item. A caller-supplied schedule may exhaust;\n * its final offer failure becomes a defect to keep the public error channel\n * reserved for the worker's declared error.\n *\n * Payload construction also becomes a defect when `fields` does not satisfy\n * the queue's payload schema. The public error channel is the worker result,\n * not malformed caller input.\n *\n * @category processing\n * @since 0.1.0\n */\nexport const process: <\n  Payload extends Schema.Top,\n  Success extends Schema.Top,\n  Error extends Schema.Top\n>(\n  self: DurableQueue<Payload, Success, Error>,\n  payload: Payload[\"~type.make.in\"],\n  options?: {\n    readonly retrySchedule?: Schedule.Schedule<any, PersistedQueue.PersistedQueueError> | undefined\n  }\n) => Effect.Effect<\n  Success[\"Type\"],\n  Error[\"Type\"],\n  | FlowRuntime\n  | FlowInstance\n  | Crypto.Crypto\n  | PersistedQueue.PersistedQueueFactory\n  | Payload[\"EncodingServices\"]\n  | Payload[\"DecodingServices\"]\n  | Success[\"DecodingServices\"]\n  | Error[\"DecodingServices\"]\n> =\n  // Untraced because queue offer is a worker hot path.\n  Effect.fnUntraced(function*<\n    Payload extends Schema.Top,\n    Success extends Schema.Top,\n    Error extends Schema.Top\n  >(self: DurableQueue<Payload, Success, Error>, fields: Payload[\"~type.make.in\"], options?: {\n    readonly retrySchedule?: Schedule.Schedule<any, PersistedQueue.PersistedQueueError> | undefined\n  }) {\n    const payload = yield* self.payloadSchema.makeEffect(fields).pipe(\n      Effect.mapError((issue) => new Schema.SchemaError(issue)),\n      Effect.orDie\n    )\n    const queueName = `DurableQueue/${self.name}`\n    const queue = yield* PersistedQueue.make({\n      name: queueName,\n      schema: getQueueSchema(self.payloadSchema)\n    })\n    const key = yield* Action.idempotencyKey(queueName, {\n      parentScope: self.idempotencyKey(payload)\n    })\n\n    const deferred = DurableDeferred.make(`${self.deferred.name}/${key}`, {\n      success: self.deferred.successSchema,\n      error: self.deferred.errorSchema\n    })\n    const token = yield* DurableDeferred.token(deferred)\n\n    yield* Effect.useSpan(`DurableQueue/${self.name}/process`, {\n      attributes: { key }\n    }, (span) =>\n      queue.offer({\n        token,\n        payload,\n        traceId: span.traceId,\n        spanId: span.spanId,\n        sampled: span.sampled\n      } as any, { id: key }).pipe(\n        Effect.tapCause(Effect.logWarning),\n        Effect.catchTag(\"SchemaError\", Effect.die),\n        Effect.retry(options?.retrySchedule ?? defaultRetrySchedule),\n        Effect.orDie,\n        Effect.annotateLogs({\n          package: \"@smthrs/flow\",\n          module: \"DurableQueue\",\n          fiber: \"process\",\n          queueName: self.name\n        })\n      ))\n\n    yield* annotateWaiting({ reason: \"event\", token })\n    return yield* DurableDeferred.await(deferred)\n  })\n\nconst maxDeferredNameExcerptChars = 128\n\n/** Renders a bounded excerpt of a stored deferred name for a diagnostic. */\nconst deferredNameExcerpt = (name: string): string =>\n  name.length <= maxDeferredNameExcerptChars\n    ? name\n    : `${name.slice(0, maxDeferredNameExcerptChars)} [${name.length - maxDeferredNameExcerptChars} characters dropped]`\n\nconst traceIdPattern = /^[0-9a-f]{32}$/\nconst spanIdPattern = /^[0-9a-f]{16}$/\n\n/**\n * The offering span as the worker span's parent, when the stored ids have the\n * W3C trace-context shape every Effect and OpenTelemetry tracer writes. A\n * stored item is not trusted to splice arbitrary identifiers into a trace.\n */\nconst externalParent = (item: {\n  readonly traceId: string\n  readonly spanId: string\n  readonly sampled: boolean\n}): Tracer.ExternalSpan | undefined =>\n  traceIdPattern.test(item.traceId) && spanIdPattern.test(item.spanId)\n    ? Tracer.externalSpan({ traceId: item.traceId, spanId: item.spanId, sampled: item.sampled })\n    : undefined\n\nconst defaultRetrySchedule = Schedule.min([\n  Schedule.exponential(500, 1.5),\n  Schedule.spaced(\"1 minute\")\n])\n\nconst makeWorkerEffect = Effect.fnUntraced(function*<\n  Payload extends Schema.Top,\n  Success extends Schema.Top,\n  Error extends Schema.Top,\n  R\n>(\n  self: DurableQueue<Payload, Success, Error>,\n  f: (payload: Payload[\"Type\"]) => Effect.Effect<Success[\"Type\"], Error[\"Type\"], R>,\n  concurrency: number,\n  maxAttempts: number\n) {\n  const queue = yield* PersistedQueue.make({\n    name: `DurableQueue/${self.name}`,\n    schema: getQueueSchema(self.payloadSchema),\n    maxAttempts,\n    // The worker owns the 500 ms retry pause below. Keep an upstream queue\n    // default from introducing an additional backoff after an Effect upgrade.\n    retrySchedule: Schedule.spaced(0)\n  })\n\n  const worker = Effect.suspend(() => {\n    let completion:\n      | { readonly token: DurableDeferred.Token; readonly id: string; readonly attempts: number }\n      | undefined\n    return queue.take((item_, metadata) => {\n      const item = item_ as {\n        readonly token: DurableDeferred.Token\n        readonly payload: Payload[\"Type\"]\n        readonly traceId: string\n        readonly spanId: string\n        readonly sampled: boolean\n      }\n      return Effect.withSpan(\n        Effect.gen(function*() {\n          // Parse before running the handler. A malformed completion address\n          // cannot strand a handler result that was already produced.\n          const parsed = yield* DurableDeferred.TokenParsed.parse(item.token)\n          // `process` offers each item under its key and addresses the\n          // deferred `<queue deferred>/<key>`. Anything else in this queue\n          // names a wait point the queue does not own (another queue's item,\n          // a WaitFor gate, a human task), so completing it here would settle\n          // a foreign wait under this queue's success schema.\n          const expected = `${self.deferred.name}/${metadata.id}`\n          if (parsed.deferredName !== expected) {\n            return yield* new DurableDeferred.TokenInvalid({\n              code: \"deferred_mismatch\",\n              message: `The item \"${metadata.id}\" addresses the deferred \"${\n                deferredNameExcerpt(parsed.deferredName)\n              }\", not \"${deferredNameExcerpt(expected)}\".`\n            })\n          }\n          const deferred = DurableDeferred.make(parsed.deferredName, {\n            success: self.deferred.successSchema,\n            error: self.deferred.errorSchema\n          })\n          let exit = yield* Effect.exit(f(item.payload))\n          if (Exit.isFailure(exit)) {\n            const [reasons, interrupts] = Arr.partition(\n              exit.cause.reasons,\n              Filter.fromPredicate(Cause.isInterruptReason)\n            )\n            // Match DurableDeferred.into: interruption alone is not a durable\n            // outcome, and must leave the item available without an attempt.\n            if (interrupts.length === exit.cause.reasons.length) {\n              return yield* Effect.failCause(Cause.fromReasons<never>(interrupts))\n            } else if (interrupts.length > 0) {\n              exit = Exit.failCause(Cause.fromReasons(reasons))\n            }\n          }\n          completion = { token: item.token, ...metadata }\n          yield* DurableDeferred.done(deferred, {\n            token: item.token,\n            exit\n          })\n        }).pipe(\n          Effect.catchTag(\"@smthrs/flow/DurableDeferred/TokenInvalid\", (error) =>\n            Effect.logError(\n              `DurableQueue \"${self.name}\" could not complete an item because its token was invalid. ${error.message}`\n            ))\n        ),\n        `DurableQueue/${self.name}/worker`,\n        {\n          captureStackTrace: false,\n          parent: externalParent(item)\n        }\n      )\n    }).pipe(\n      Effect.tapCause((cause) => {\n        if (!completion) return Effect.void\n        return Effect.logError(\"DurableQueue failed to persist or acknowledge a handler result\", cause).pipe(\n          Effect.annotateLogs({\n            token: completion.token,\n            itemId: completion.id,\n            attempt: completion.attempts,\n            maxAttempts,\n            exhausted: !Cause.hasInterrupts(cause) && completion.attempts >= maxAttempts\n          })\n        )\n      })\n    )\n  }).pipe(\n    // A persistently failing take would otherwise consume a core in a tight\n    // loop while the queue store is unavailable.\n    Effect.catchCause((cause) =>\n      Effect.logWarning(cause).pipe(\n        Effect.andThen(Effect.sleep(500))\n      )\n    ),\n    Effect.forever,\n    Effect.annotateLogs({\n      package: \"@smthrs/flow\",\n      module: \"DurableQueue\",\n      fiber: \"worker\",\n      queueName: self.name\n    })\n  )\n\n  return yield* Effect.replicateEffect(worker, concurrency, { concurrency, discard: true }).pipe(\n    Effect.andThen(Effect.never)\n  )\n})\n\n/**\n * Create a worker effect that processes items from the durable queue.\n *\n * `concurrency` defaults to one and must be a positive safe integer. It is\n * checked before the persisted queue is opened. `maxAttempts` defaults to ten\n * and is passed to the persisted queue. Completion-write failures can rerun the\n * handler; side effects must be idempotent. Exhaustion leaves the flow waiting.\n *\n * @throws A `RangeError` when `concurrency` is not a positive safe integer.\n * @category worker\n * @since 0.1.0\n */\nexport const makeWorker: <\n  Payload extends Schema.Top,\n  Success extends Schema.Top,\n  Error extends Schema.Top,\n  R\n>(\n  self: DurableQueue<Payload, Success, Error>,\n  f: (payload: Payload[\"Type\"]) => Effect.Effect<Success[\"Type\"], Error[\"Type\"], R>,\n  options?: {\n    readonly concurrency?: number | undefined\n    readonly maxAttempts?: number | undefined\n  } | undefined\n) => Effect.Effect<\n  never,\n  never,\n  | FlowRuntime\n  | PersistedQueue.PersistedQueueFactory\n  | R\n  | Payload[\"EncodingServices\"]\n  | Payload[\"DecodingServices\"]\n  | Success[\"EncodingServices\"]\n  | Error[\"EncodingServices\"]\n> = <\n  Payload extends Schema.Top,\n  Success extends Schema.Top,\n  Error extends Schema.Top,\n  R\n>(\n  self: DurableQueue<Payload, Success, Error>,\n  f: (payload: Payload[\"Type\"]) => Effect.Effect<Success[\"Type\"], Error[\"Type\"], R>,\n  options?: {\n    readonly concurrency?: number | undefined\n    readonly maxAttempts?: number | undefined\n  }\n) => {\n  const concurrency = options?.concurrency ?? 1\n  if (!Number.isSafeInteger(concurrency) || concurrency < 1) {\n    throw new RangeError(\n      `DurableQueue.makeWorker: concurrency must be a positive safe integer, and was ${concurrency}.`\n    )\n  }\n  return makeWorkerEffect(self, f, concurrency, options?.maxAttempts ?? 10)\n}\n\n/**\n * Create a layer that runs workers for the durable queue.\n *\n * @category worker\n * @since 0.1.0\n */\nexport const worker: <\n  Payload extends Schema.Top,\n  Success extends Schema.Top,\n  Error extends Schema.Top,\n  R\n>(\n  self: DurableQueue<Payload, Success, Error>,\n  f: (payload: Payload[\"Type\"]) => Effect.Effect<Success[\"Type\"], Error[\"Type\"], R>,\n  options?: {\n    readonly concurrency?: number | undefined\n    readonly maxAttempts?: number | undefined\n  } | undefined\n) => Layer.Layer<\n  never,\n  never,\n  | FlowRuntime\n  | PersistedQueue.PersistedQueueFactory\n  | R\n  | Payload[\"EncodingServices\"]\n  | Payload[\"DecodingServices\"]\n  | Success[\"EncodingServices\"]\n  | Error[\"EncodingServices\"]\n> = (self, f, options) => Layer.effectDiscard(Effect.forkScoped(makeWorker(self, f, options)))\n"]}