effect 4.0.0-beta.67 → 4.0.0-beta.68

package/src/unstable/workflow/DurableDeferred.ts

@@ -44,7 +44,7 @@ const TypeId = "~effect/workflow/DurableDeferred"
  * Named durable deferred value whose completion is persisted by the workflow
  * engine and encoded with success and error schemas.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface DurableDeferred<
@@ -63,7 +63,7 @@ export interface DurableDeferred<
  * Type-erased durable deferred shape for APIs that only need the deferred
  * identity and name.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface Any {
@@ -75,7 +75,7 @@ export interface Any {
  * Type-erased durable deferred shape that also exposes success, error, and
  * exit schemas.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface AnyWithProps {
@@ -90,7 +90,7 @@ export interface AnyWithProps {
  * Creates a named durable deferred with optional success and error schemas for
  * persisted completion.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const make = <
@@ -168,7 +168,7 @@ const await_: <Success extends Schema.Top, Error extends Schema.Top>(
 
 export {
   /**
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   await_ as await
@@ -178,7 +178,7 @@ export {
  * Runs an effect and records its exit into the durable deferred, resuming
  * workflows that are waiting on that deferred.
  *
- * @category Combinators
+ * @category combinators
  * @since 4.0.0
  */
 export const into: {
@@ -186,7 +186,7 @@ export const into: {
    * Runs an effect and records its exit into the durable deferred, resuming
    * workflows that are waiting on that deferred.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(self: DurableDeferred<Success, Error>): <R>(
@@ -204,7 +204,7 @@ export const into: {
    * Runs an effect and records its exit into the durable deferred, resuming
    * workflows that are waiting on that deferred.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top, R>(
@@ -313,6 +313,7 @@ export const raceAll = <
 /**
  * Runtime brand identifier for durable deferred tokens.
  *
+ * @category type IDs
  * @since 4.0.0
  */
 export const TokenTypeId = "~effect/workflow/DurableDeferred/Token"
@@ -320,6 +321,7 @@ export const TokenTypeId = "~effect/workflow/DurableDeferred/Token"
 /**
  * Type-level brand identifier for `Token` values.
  *
+ * @category type IDs
  * @since 4.0.0
  */
 export type TokenTypeId = typeof TokenTypeId
@@ -549,7 +551,7 @@ export const tokenFromPayload: {
  * Completes the durable deferred identified by a token with the supplied exit,
  * encoding the result through the deferred schemas.
  *
- * @category Combinators
+ * @category combinators
  * @since 4.0.0
  */
 export const done: {
@@ -557,7 +559,7 @@ export const done: {
    * Completes the durable deferred identified by a token with the supplied exit,
    * encoding the result through the deferred schemas.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
@@ -576,7 +578,7 @@ export const done: {
    * Completes the durable deferred identified by a token with the supplied exit,
    * encoding the result through the deferred schemas.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
@@ -617,7 +619,7 @@ export const done: {
  * Completes the durable deferred identified by a token with a successful
  * value.
  *
- * @category Combinators
+ * @category combinators
  * @since 4.0.0
  */
 export const succeed: {
@@ -625,7 +627,7 @@ export const succeed: {
    * Completes the durable deferred identified by a token with a successful
    * value.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
@@ -640,7 +642,7 @@ export const succeed: {
    * Completes the durable deferred identified by a token with a successful
    * value.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
@@ -668,14 +670,14 @@ export const succeed: {
 /**
  * Completes the durable deferred identified by a token with a typed failure.
  *
- * @category Combinators
+ * @category combinators
  * @since 4.0.0
  */
 export const fail: {
   /**
    * Completes the durable deferred identified by a token with a typed failure.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
@@ -689,7 +691,7 @@ export const fail: {
   /**
    * Completes the durable deferred identified by a token with a typed failure.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
@@ -717,14 +719,14 @@ export const fail: {
 /**
  * Completes the durable deferred identified by a token with a failure cause.
  *
- * @category Combinators
+ * @category combinators
  * @since 4.0.0
  */
 export const failCause: {
   /**
    * Completes the durable deferred identified by a token with a failure cause.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
@@ -738,7 +740,7 @@ export const failCause: {
   /**
    * Completes the durable deferred identified by a token with a failure cause.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(

package/src/unstable/workflow/DurableQueue.ts

@@ -30,7 +30,7 @@ import type { WorkflowEngine, WorkflowInstance } from "./WorkflowEngine.ts"
 /**
  * Type-level identifier used to recognize `DurableQueue` values.
  *
- * @category Type IDs
+ * @category type IDs
  * @since 4.0.0
  */
 export type TypeId = "~effect/workflow/DurableQueue"
@@ -38,7 +38,7 @@ export type TypeId = "~effect/workflow/DurableQueue"
 /**
  * Runtime identifier attached to `DurableQueue` values.
  *
- * @category Type IDs
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId: TypeId = "~effect/workflow/DurableQueue"
@@ -47,7 +47,7 @@ export const TypeId: TypeId = "~effect/workflow/DurableQueue"
  * Durable workflow queue definition containing a payload schema, idempotency
  * key, and deferred used to await worker results.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface DurableQueue<
@@ -66,9 +66,11 @@ export interface DurableQueue<
  * A `DurableQueue` wraps a `PersistedQueue`, providing a way to wait for items
  * to finish processing using a `DurableDeferred`.
  *
+ * **Example** (Defining a durable queue with workers)
+ *
  * ```ts
- * import { DurableQueue, Workflow } from "effect/unstable/workflow"
  * import { Effect, Schema } from "effect"
+ * import { DurableQueue, Workflow } from "effect/unstable/workflow"
  *
  * // Define a DurableQueue that can be used to derive workers and offer items for
  * // processing.
@@ -115,7 +117,7 @@ export interface DurableQueue<
  * )
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const make = <

package/src/unstable/workflow/Workflow.ts

@@ -51,7 +51,7 @@ const TypeId = "~effect/workflow/Workflow"
  * plus operations for execution, polling, interruption, resumption, and
  * registration.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface Workflow<
@@ -194,6 +194,7 @@ export interface Workflow<
 /**
  * Schema constraint for workflow payload schemas that expose struct fields.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export interface AnyStructSchema extends Schema.Top {
@@ -204,7 +205,7 @@ export interface AnyStructSchema extends Schema.Top {
  * Type-level marker for services associated with a specific workflow
  * execution name.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface Execution<Name extends string> {
@@ -216,7 +217,7 @@ export interface Execution<Name extends string> {
  * Type-erased workflow shape for APIs that operate on workflows without
  * preserving their specific payload, success, or error types.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface Any {
@@ -233,7 +234,7 @@ export interface Any {
  * Type-erased workflow shape that also exposes executable operations needed by
  * workflow proxy and engine helpers.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface AnyWithProps extends Any {
@@ -252,7 +253,7 @@ export interface AnyWithProps extends Any {
 /**
  * Extracts the payload schema from a `Workflow`.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export type PayloadSchema<W> = W extends Workflow<
@@ -267,7 +268,7 @@ export type PayloadSchema<W> = W extends Workflow<
  * Computes the schema services required by clients that execute or poll
  * workflows.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export type RequirementsClient<Workflows extends Any> = Workflows extends Workflow<
@@ -285,7 +286,7 @@ export type RequirementsClient<Workflows extends Any> = Workflows extends Workfl
  * Computes the schema services required by handlers that decode workflow
  * payloads and encode workflow results.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export type RequirementsHandler<Workflows extends Any> = Workflows extends Workflow<
@@ -318,7 +319,7 @@ const InstanceTag = Context.Service<
  * deterministic execution IDs derived from the workflow name and idempotency
  * key.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const make = <
@@ -485,6 +486,7 @@ export interface CompleteEncoded<A, E> {
  * Schema constructor for `Complete` workflow results using the supplied
  * success and error schemas.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export interface CompleteSchema<
@@ -867,7 +869,7 @@ export const suspend = (instance: WorkflowInstance["Service"]): Effect.Effect<ne
  *
  * By default, this is set to `true`, meaning that defects will be captured.
  *
- * @category Annotations
+ * @category annotations
  * @since 4.0.0
  */
 export const CaptureDefects = Context.Reference<boolean>(
@@ -883,7 +885,7 @@ export const CaptureDefects = Context.Reference<boolean>(
  * The suspended execution can later be resumed with the workflow's `resume`
  * method, for example `MyWorkflow.resume(executionId)`.
  *
- * @category Annotations
+ * @category annotations
  * @since 4.0.0
  */
 export const SuspendOnFailure = Context.Reference<boolean>(

package/src/unstable/workflow/WorkflowEngine.ts

@@ -43,7 +43,7 @@ import * as Workflow from "./Workflow.ts"
  * executing workflows and coordinating activities, durable deferreds,
  * interrupts, resumes, and clocks.
  *
- * @category Services
+ * @category services
  * @since 4.0.0
  */
 export class WorkflowEngine extends Context.Service<
@@ -224,7 +224,7 @@ export class WorkflowEngine extends Context.Service<
  * definition, long-lived scope, suspension state, interruption state, and
  * activity coordination state.
  *
- * @category Services
+ * @category services
  * @since 4.0.0
  */
 export class WorkflowInstance extends Context.Service<
@@ -365,7 +365,7 @@ export interface Encoded {
  * implementation. This is unsafe because the implementation must correctly
  * persist, resume, and encode workflow state.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const makeUnsafe = (options: Encoded): WorkflowEngine["Service"] =>
@@ -559,7 +559,7 @@ const defaultRetrySchedule = Schedule.exponential(200, 1.5).pipe(
  * and local development, but is not suitable for production use as it does not
  * provide durability guarantees.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEngine)(

package/src/unstable/workflow/WorkflowProxy.ts

@@ -36,14 +36,12 @@ import type * as Workflow from "./Workflow.ts"
 /**
  * Derives an `RpcGroup` from a list of workflows.
  *
+ * **Example** (Deriving RPC endpoints from workflows)
+ *
  * ```ts
  * import { Layer, Schema } from "effect"
  * import { RpcServer } from "effect/unstable/rpc"
- * import {
- *   Workflow,
- *   WorkflowProxy,
- *   WorkflowProxyServer
- * } from "effect/unstable/workflow"
+ * import { Workflow, WorkflowProxy, WorkflowProxyServer } from "effect/unstable/workflow"
  *
  * const EmailWorkflow = Workflow.make({
  *   name: "EmailWorkflow",
@@ -67,7 +65,7 @@ import type * as Workflow from "./Workflow.ts"
  * )
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const toRpcGroup = <
@@ -103,6 +101,7 @@ export const toRpcGroup = <
  * Maps each workflow to the RPC definitions generated for execute, discard,
  * and resume operations.
  *
+ * @category converting
  * @since 4.0.0
  */
 export type ConvertRpcs<Workflows extends Workflow.Any, Prefix extends string> = Workflows extends Workflow.Workflow<
@@ -119,14 +118,12 @@ export type ConvertRpcs<Workflows extends Workflow.Any, Prefix extends string> =
 /**
  * Derives an `HttpApiGroup` from a list of workflows.
  *
+ * **Example** (Deriving HTTP API endpoints from workflows)
+ *
  * ```ts
  * import { Layer, Schema } from "effect"
  * import { HttpApi, HttpApiBuilder } from "effect/unstable/httpapi"
- * import {
- *   Workflow,
- *   WorkflowProxy,
- *   WorkflowProxyServer
- * } from "effect/unstable/workflow"
+ * import { Workflow, WorkflowProxy, WorkflowProxyServer } from "effect/unstable/workflow"
  *
  * const EmailWorkflow = Workflow.make({
  *   name: "EmailWorkflow",
@@ -154,7 +151,7 @@ export type ConvertRpcs<Workflows extends Workflow.Any, Prefix extends string> =
  * )
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const toHttpApiGroup = <const Name extends string, const Workflows extends NonEmptyReadonlyArray<Workflow.Any>>(
@@ -192,6 +189,7 @@ const tagToPath = (tag: string): string =>
  * Maps each workflow to the HTTP API endpoints generated for execute,
  * discard, and resume operations.
  *
+ * @category converting
  * @since 4.0.0
  */
 export type ConvertHttpApi<Workflows extends Workflow.Any> = Workflows extends Workflow.Workflow<

package/src/unstable/workflow/WorkflowProxyServer.ts

@@ -41,7 +41,7 @@ import type { WorkflowEngine } from "./WorkflowEngine.ts"
  * Creates handlers for a workflow HTTP API group, wiring execute, discard, and
  * resume endpoints to the supplied workflows.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerHttpApi = <
@@ -108,7 +108,7 @@ export const layerHttpApi = <
  * Creates RPC handlers for the supplied workflows, wiring execute, discard,
  * and resume RPCs to workflow operations.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerRpcHandlers = <
@@ -156,6 +156,7 @@ export const layerRpcHandlers = <
  * Union of RPC handler services required to serve the generated workflow
  * execute, discard, and resume RPCs.
  *
+ * @category services
  * @since 4.0.0
  */
 export type RpcHandlers<Workflows extends Workflow.Any, Prefix extends string> = Workflows extends Workflow.Workflow<

package/src/unstable/workflow/index.ts

@@ -5,41 +5,201 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
+ * The `Activity` module defines named, schema-backed effects that run at the
+ * side-effect boundary of a durable workflow. Activities are executed through a
+ * `WorkflowEngine`, encode their success and failure values with the provided
+ * schemas, and can be replayed from persisted results instead of rerunning the
+ * underlying effect.
+ *
+ * Use activities for work that should not be embedded directly in workflow
+ * control flow, such as calling external services, writing to databases,
+ * enqueueing durable jobs, short sleeps delegated by `DurableClock`, or racing
+ * multiple external operations with `raceAll`. Keep activity names and schemas
+ * stable because engines use them, together with the workflow execution and
+ * retry attempt, to identify stored results.
+ *
+ * Activities can be interrupted and retried, and workflow resumes may observe a
+ * completed encoded result or run the activity again depending on what the
+ * engine has persisted. Make external side effects idempotent, use
+ * `idempotencyKey` for stable request keys derived from the workflow execution,
+ * and include the current attempt only when each retry must address a distinct
+ * external operation.
+ *
  * @since 4.0.0
  */
 export * as Activity from "./Activity.ts"
 
 /**
+ * Durable workflow clocks provide workflow-safe timers and sleep operations.
+ *
+ * Use this module when a workflow needs to pause until a timeout, reminder,
+ * deadline, retry delay, or other scheduled wake-up. Short sleeps can run as
+ * in-memory activities, while longer sleeps are scheduled with the workflow
+ * engine and resumed through a durable deferred signal when the timer fires.
+ *
+ * Because workflows may be replayed, timer names and durations should be
+ * deterministic and stable for a given workflow path. Avoid deriving them from
+ * ambient wall-clock state, and give distinct sleeps distinct names so replayed
+ * executions can be matched with the correct scheduled wake-up. Lower the
+ * in-memory threshold when a delay must be handled by the workflow engine
+ * rather than the current process.
+ *
  * @since 4.0.0
  */
 export * as DurableClock from "./DurableClock.ts"
 
 /**
+ * Durable deferreds are named workflow wait points whose result is stored by
+ * the workflow engine as an encoded `Exit`. A workflow can `await` one and
+ * suspend until an activity, worker, timer, or external callback completes it
+ * with `done`, `succeed`, `fail`, or `failCause`.
+ *
+ * Use this module to coordinate work that finishes outside the current
+ * workflow turn: durable races, queues that report worker results, timers,
+ * human approvals, webhooks, and other callback-style integrations. Tokens
+ * encode the workflow name, execution ID, and deferred name so completion can
+ * be routed back to the correct workflow execution without keeping an
+ * in-memory handle.
+ *
+ * Deferred names are part of persisted workflow state, so keep them stable
+ * across replays and unique for each logical wait. Completion is persisted as
+ * an `Exit` and decoded through the success and error schemas when awaited
+ * again; changing schemas or reusing a name for a different result type can
+ * make old completions fail to decode or resume the wrong wait. Complete a
+ * deferred once, and use `withActivityAttempt` when an activity retry needs an
+ * attempt-scoped completion name.
+ *
  * @since 4.0.0
  */
 export * as DurableDeferred from "./DurableDeferred.ts"
 
 /**
+ * Durable queues bridge workflow executions with persisted background workers.
+ * A workflow calls `process` to enqueue a schema-encoded payload in a named
+ * `PersistedQueue`, attach a durable deferred token, and suspend until a worker
+ * records the handler's `Exit` back through that deferred.
+ *
+ * Use this module for workflow steps that should be delegated to independent
+ * workers: long-running side effects, rate-limited or concurrency-limited
+ * integrations, fan-out jobs, API calls, and other work that must survive
+ * workflow suspension, process restarts, or handoff to another service.
+ *
+ * Queue names, payload schemas, result schemas, and idempotency keys become
+ * persisted coordination state. Keep them deterministic and stable across
+ * deployments; changing them is a persistence migration. Delivery follows the
+ * underlying `PersistedQueue` semantics, so handlers should be idempotent and
+ * prepared for retries, duplicate observations, and worker restarts.
+ *
  * @since 4.0.0
  */
 export * as DurableQueue from "./DurableQueue.ts"
 
 /**
+ * The `Workflow` module defines typed durable workflow descriptions and the
+ * helpers used to execute them through a `WorkflowEngine`. A workflow combines
+ * a stable name, a struct payload schema, success and error schemas, and an
+ * idempotency key so callers can derive deterministic execution IDs, execute or
+ * discard runs, poll results, interrupt or resume suspended executions, and
+ * register handlers with `toLayer`.
+ *
+ * Workflows are intended for long-running business processes that coordinate
+ * activities, durable deferreds, durable clocks, retries, and compensation.
+ * Keep external side effects at activity boundaries so engine implementations
+ * can safely persist, suspend, and resume execution state. Running activities
+ * can delay workflow suspension until they finish or suspend, and compensation
+ * registered with `withCompensation` only applies to top-level workflow
+ * effects, not nested activities.
+ *
+ * When exposing workflows through `WorkflowProxy`, remember that proxy APIs are
+ * derived from the workflow name and schemas. Discard execution returns the
+ * `executionId` instead of the workflow result, resume requires the persisted
+ * `executionId`, and idempotency keys must remain stable for the same logical
+ * request.
+ *
  * @since 4.0.0
  */
 export * as Workflow from "./Workflow.ts"
 
 /**
+ * Workflow engine service definitions and the default in-memory engine used to
+ * run durable workflows.
+ *
+ * This module is the runtime boundary for `Workflow` values. It registers
+ * workflow handlers, starts or polls executions by stable execution ID, links
+ * child workflow interruption to parents, and coordinates activities, durable
+ * deferred values, and durable clocks. Library users usually depend on the
+ * typed `WorkflowEngine` service, while persistence backends implement the
+ * lower-level `Encoded` contract and pass it to `makeUnsafe`.
+ *
+ * Durable execution requires engine implementations to make retries and resumes
+ * idempotent. Reusing an execution ID should observe the existing execution
+ * instead of starting duplicate work, suspended executions are retried according
+ * to `suspendedRetrySchedule`, and concurrent deferred completions or clock
+ * wake-ups must be serialized by the backend. Use `interrupt` when
+ * compensation and child workflow cleanup matter; `interruptUnsafe` can stop
+ * work more directly but may bypass those guarantees. The provided
+ * `layerMemory` is useful for tests and local development, but it keeps state
+ * in process memory and does not provide production durability.
+ *
  * @since 4.0.0
  */
 export * as WorkflowEngine from "./WorkflowEngine.ts"
 
 /**
+ * The `WorkflowProxy` module derives transport contracts from durable
+ * `Workflow` definitions.
+ *
+ * Use it when workflows should be invoked through RPC or HTTP instead of by
+ * importing the workflow implementation directly. `toRpcGroup` creates the
+ * `RpcGroup` that RPC clients and servers share, while `toHttpApiGroup` creates
+ * the `HttpApiGroup` that can be mounted in an HTTP API. Each workflow expands
+ * into execute, discard, and resume operations so external callers can start a
+ * workflow, start it through the discard path, or resume a suspended execution
+ * by `executionId`.
+ *
+ * The generated names and schemas come from the workflow definitions, so keep
+ * workflow names stable and pass the same workflow list to the matching
+ * `WorkflowProxyServer` layer. RPC proxies may be prefixed, but the same prefix
+ * must be used by the server handlers. HTTP endpoint paths are derived from the
+ * lower-cased workflow name. Preserve workflow arrays as const tuples when you
+ * want the generated RPC and HTTP API types to retain each workflow's literal
+ * name, payload, success, and error types.
+ *
+ * Discard and resume are control operations rather than ordinary workflow
+ * result reads. The discard proxy does not expose the normal success or error
+ * schemas, and resume expects the persisted `executionId`; it cannot recreate
+ * that boundary value from the original payload.
+ *
  * @since 4.0.0
  */
 export * as WorkflowProxy from "./WorkflowProxy.ts"
 
 /**
+ * The `WorkflowProxyServer` module provides server-side layers for exposing
+ * workflows through the proxy APIs generated by `WorkflowProxy`. It connects
+ * HTTP API endpoints or RPC handlers to the supplied workflow definitions,
+ * routing execute, discard, and resume requests to the corresponding workflow
+ * operation while keeping the `WorkflowEngine` and workflow implementation
+ * services on the server side.
+ *
+ * **Common tasks**
+ *
+ * - Serve a workflow proxy over an HTTP API group with {@link layerHttpApi}
+ * - Serve the RPC group produced by `WorkflowProxy.toRpcGroup` with
+ *   {@link layerRpcHandlers}
+ * - Expose durable workflow starts and explicit resume operations to clients
+ *   without exposing the workflow implementation itself
+ *
+ * **Gotchas**
+ *
+ * - The workflows passed to these layers must match the group produced by
+ *   `WorkflowProxy`; RPC prefixes must be the same on both sides
+ * - Discard handlers use the workflow discard execution path, so callers should
+ *   not rely on receiving the normal workflow success or error value
+ * - Resume handlers expect a payload with the persisted `executionId`; clients
+ *   must preserve that boundary value because it is not recomputed from the
+ *   original workflow payload
+ *
  * @since 4.0.0
  */
 export * as WorkflowProxyServer from "./WorkflowProxyServer.ts"