effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/unstable/workflow/WorkflowProxy.js

@@ -6,14 +6,12 @@ import * as RpcGroup from "../rpc/RpcGroup.js";
 /**
  * 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",
@@ -37,8 +35,8 @@ import * as RpcGroup from "../rpc/RpcGroup.js";
  * )
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const toRpcGroup = (workflows, options) => {
   const prefix = options?.prefix ?? "";
@@ -60,14 +58,12 @@ export const toRpcGroup = (workflows, options) => {
 /**
  * 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",
@@ -95,8 +91,8 @@ export const toRpcGroup = (workflows, options) => {
  * )
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const toHttpApiGroup = (name, workflows) => {
   let group = HttpApiGroup.make(name);

package/dist/unstable/workflow/WorkflowProxy.js.map

@@ -1 +1 @@
-{"version":3,"file":"WorkflowProxy.js","names":["Schema","HttpApiEndpoint","HttpApiGroup","Rpc","RpcGroup","toRpcGroup","workflows","options","prefix","rpcs","workflow_","workflow","push","make","name","payload","payloadSchema","error","errorSchema","success","successSchema","annotateMerge","annotations","ResumePayload","toHttpApiGroup","group","path","tagToPath","add","post","tag","toLowerCase","Struct","executionId","String"],"sources":["../../../src/unstable/workflow/WorkflowProxy.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"WorkflowProxy.js","names":["Schema","HttpApiEndpoint","HttpApiGroup","Rpc","RpcGroup","toRpcGroup","workflows","options","prefix","rpcs","workflow_","workflow","push","make","name","payload","payloadSchema","error","errorSchema","success","successSchema","annotateMerge","annotations","ResumePayload","toHttpApiGroup","group","path","tagToPath","add","post","tag","toLowerCase","Struct","executionId","String"],"sources":["../../../src/unstable/workflow/WorkflowProxy.ts"],"sourcesContent":[null],"mappings":"AA4BA,OAAO,KAAKA,MAAM,MAAM,iBAAiB;AACzC,OAAO,KAAKC,eAAe,MAAM,+BAA+B;AAChE,OAAO,KAAKC,YAAY,MAAM,4BAA4B;AAC1D,OAAO,KAAKC,GAAG,MAAM,eAAe;AACpC,OAAO,KAAKC,QAAQ,MAAM,oBAAoB;AAG9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,OAAO,MAAMC,UAAU,GAAGA,CAIxBC,SAAoB,EACpBC,OAEC,KAC4D;EAC7D,MAAMC,MAAM,GAAGD,OAAO,EAAEC,MAAM,IAAI,EAAE;EACpC,MAAMC,IAAI,GAAmB,EAAE;EAC/B,KAAK,MAAMC,SAAS,IAAIJ,SAAS,EAAE;IACjC,MAAMK,QAAQ,GAAGD,SAAkC;IACnDD,IAAI,CAACG,IAAI,CACPT,GAAG,CAACU,IAAI,CAAC,GAAGL,MAAM,GAAGG,QAAQ,CAACG,IAAI,EAAE,EAAE;MACpCC,OAAO,EAAEJ,QAAQ,CAACK,aAAa;MAC/BC,KAAK,EAAEN,QAAQ,CAACO,WAAW;MAC3BC,OAAO,EAAER,QAAQ,CAACS;KACnB,CAAC,CAACC,aAAa,CAACV,QAAQ,CAACW,WAAW,CAAC,EACtCnB,GAAG,CAACU,IAAI,CAAC,GAAGL,MAAM,GAAGG,QAAQ,CAACG,IAAI,SAAS,EAAE;MAC3CC,OAAO,EAAEJ,QAAQ,CAACK;KACnB,CAAC,CAACK,aAAa,CAACV,QAAQ,CAACW,WAAW,CAAC,EACtCnB,GAAG,CAACU,IAAI,CAAC,GAAGL,MAAM,GAAGG,QAAQ,CAACG,IAAI,QAAQ,EAAE;MAAEC,OAAO,EAAEQ;IAAa,CAAE,CAAC,CACpEF,aAAa,CAACV,QAAQ,CAACW,WAAW,CAAC,CACvC;EACH;EACA,OAAOlB,QAAQ,CAACS,IAAI,CAAC,GAAGJ,IAAI,CAAQ;AACtC,CAAC;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,OAAO,MAAMe,cAAc,GAAGA,CAC5BV,IAAU,EACVR,SAAoB,KACkD;EACtE,IAAImB,KAAK,GAAGvB,YAAY,CAACW,IAAI,CAACC,IAAI,CAAC;EACnC,KAAK,MAAMJ,SAAS,IAAIJ,SAAS,EAAE;IACjC,MAAMK,QAAQ,GAAGD,SAAkC;IACnD,MAAMgB,IAAI,GAAG,IAAIC,SAAS,CAAChB,QAAQ,CAACG,IAAI,CAAC,EAAW;IACpDW,KAAK,GAAGA,KAAK,CAACG,GAAG,CACf3B,eAAe,CAAC4B,IAAI,CAAClB,QAAQ,CAACG,IAAI,EAAEY,IAAI,EAAE;MACxCX,OAAO,EAAEJ,QAAQ,CAACK,aAAa;MAC/BG,OAAO,EAAER,QAAQ,CAACS,aAAa;MAC/BH,KAAK,EAAEN,QAAQ,CAACO;KACjB,CAAC,CAACG,aAAa,CAACV,QAAQ,CAACW,WAAW,CAAC,EACtCrB,eAAe,CAAC4B,IAAI,CAAClB,QAAQ,CAACG,IAAI,GAAG,SAAS,EAAE,GAAGY,IAAI,UAAU,EAAE;MACjEX,OAAO,EAAEJ,QAAQ,CAACK;KACnB,CAAC,CAACK,aAAa,CAACV,QAAQ,CAACW,WAAW,CAAC,EACtCrB,eAAe,CAAC4B,IAAI,CAAClB,QAAQ,CAACG,IAAI,GAAG,QAAQ,EAAE,GAAGY,IAAI,SAAS,EAAE;MAC/DX,OAAO,EAAEQ;KACV,CAAC,CAACF,aAAa,CAACV,QAAQ,CAACW,WAAW,CAAC,CAChC;EACV;EACA,OAAOG,KAAY;AACrB,CAAC;AAED,MAAME,SAAS,GAAIG,GAAW,IAC5BA;AACE;AACA;AAAA,CACCC,WAAW,EAAE;AA4ClB,MAAMR,aAAa,gBAAGvB,MAAM,CAACgC,MAAM,CAAC;EAAEC,WAAW,EAAEjC,MAAM,CAACkC;AAAM,CAAE,CAAC","ignoreList":[]}

package/dist/unstable/workflow/WorkflowProxyServer.d.ts

@@ -1,4 +1,29 @@
 /**
+ * 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
  */
 import type { NonEmptyReadonlyArray } from "../../Array.ts";
@@ -9,18 +34,28 @@ import type * as Rpc from "../rpc/Rpc.ts";
 import type * as Workflow from "./Workflow.ts";
 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
  * @since 4.0.0
- * @category Layers
  */
 export declare const layerHttpApi: <ApiId extends string, Groups extends HttpApiGroup.Any, Name extends HttpApiGroup.Name<Groups>, const Workflows extends NonEmptyReadonlyArray<Workflow.Any>>(api: HttpApi.HttpApi<ApiId, Groups>, name: Name, workflows: Workflows) => Layer.Layer<HttpApiGroup.ApiGroup<ApiId, Name>, never, WorkflowEngine | Workflow.RequirementsHandler<Workflows[number]>>;
 /**
+ * Creates RPC handlers for the supplied workflows, wiring execute, discard,
+ * and resume RPCs to workflow operations.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export declare const layerRpcHandlers: <const Workflows extends NonEmptyReadonlyArray<Workflow.Any>, const Prefix extends string = "">(workflows: Workflows, options?: {
     readonly prefix?: Prefix;
 }) => Layer.Layer<RpcHandlers<Workflows[number], Prefix>, never, WorkflowEngine | Workflow.RequirementsHandler<Workflows[number]>>;
 /**
+ * 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<infer _Name, infer _Payload, infer _Success, infer _Error> ? Rpc.Handler<`${Prefix}${_Name}`> | Rpc.Handler<`${Prefix}${_Name}Discard`> | Rpc.Handler<`${Prefix}${_Name}Resume`> : never;

package/dist/unstable/workflow/WorkflowProxyServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WorkflowProxyServer.d.ts","sourceRoot":"","sources":["../../../src/unstable/workflow/WorkflowProxyServer.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAG3D,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAA;AACvC,OAAO,KAAK,KAAK,OAAO,MAAM,uBAAuB,CAAA;AAErD,OAAO,KAAK,KAAK,YAAY,MAAM,4BAA4B,CAAA;AAC/D,OAAO,KAAK,KAAK,GAAG,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,KAAK,QAAQ,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEzD;;;GAGG;AACH,eAAO,MAAM,YAAY,GACvB,KAAK,SAAS,MAAM,EACpB,MAAM,SAAS,YAAY,CAAC,GAAG,EAC/B,IAAI,SAAS,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,EACtC,KAAK,CAAC,SAAS,SAAS,qBAAqB,CAAC,QAAQ,CAAC,GAAG,CAAC,EAE3D,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,EACnC,MAAM,IAAI,EACV,WAAW,SAAS,KACnB,KAAK,CAAC,KAAK,CACZ,YAAY,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,EAClC,KAAK,EACL,cAAc,GAAG,QAAQ,CAAC,mBAAmB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CA8C/D,CAAA;AAEH;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,KAAK,CAAC,SAAS,SAAS,qBAAqB,CAAC,QAAQ,CAAC,GAAG,CAAC,EAC3D,KAAK,CAAC,MAAM,SAAS,MAAM,GAAG,EAAE,EAChC,WAAW,SAAS,EAAE,UAAU;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB,KAAG,KAAK,CAAC,KAAK,CACb,WAAW,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EACtC,KAAK,EACL,cAAc,GAAG,QAAQ,CAAC,mBAAmB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CA+B7D,CAAA;AAEL;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,SAAS,SAAS,QAAQ,CAAC,GAAG,EAAE,MAAM,SAAS,MAAM,IAAI,SAAS,SAAS,QAAQ,CAAC,QAAQ,CAClH,MAAM,KAAK,EACX,MAAM,QAAQ,EACd,MAAM,QAAQ,EACd,MAAM,MAAM,CACb,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,MAAM,GAAG,KAAK,EAAE,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,MAAM,GAAG,KAAK,SAAS,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,MAAM,GAAG,KAAK,QAAQ,CAAC,GACnH,KAAK,CAAA"}
+{"version":3,"file":"WorkflowProxyServer.d.ts","sourceRoot":"","sources":["../../../src/unstable/workflow/WorkflowProxyServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAG3D,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAA;AACvC,OAAO,KAAK,KAAK,OAAO,MAAM,uBAAuB,CAAA;AAErD,OAAO,KAAK,KAAK,YAAY,MAAM,4BAA4B,CAAA;AAC/D,OAAO,KAAK,KAAK,GAAG,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,KAAK,QAAQ,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEzD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GACvB,KAAK,SAAS,MAAM,EACpB,MAAM,SAAS,YAAY,CAAC,GAAG,EAC/B,IAAI,SAAS,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,EACtC,KAAK,CAAC,SAAS,SAAS,qBAAqB,CAAC,QAAQ,CAAC,GAAG,CAAC,EAE3D,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,EACnC,MAAM,IAAI,EACV,WAAW,SAAS,KACnB,KAAK,CAAC,KAAK,CACZ,YAAY,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,EAClC,KAAK,EACL,cAAc,GAAG,QAAQ,CAAC,mBAAmB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CA8C/D,CAAA;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,KAAK,CAAC,SAAS,SAAS,qBAAqB,CAAC,QAAQ,CAAC,GAAG,CAAC,EAC3D,KAAK,CAAC,MAAM,SAAS,MAAM,GAAG,EAAE,EAChC,WAAW,SAAS,EAAE,UAAU;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB,KAAG,KAAK,CAAC,KAAK,CACb,WAAW,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EACtC,KAAK,EACL,cAAc,GAAG,QAAQ,CAAC,mBAAmB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CA+B7D,CAAA;AAEL;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,CAAC,SAAS,SAAS,QAAQ,CAAC,GAAG,EAAE,MAAM,SAAS,MAAM,IAAI,SAAS,SAAS,QAAQ,CAAC,QAAQ,CAClH,MAAM,KAAK,EACX,MAAM,QAAQ,EACd,MAAM,QAAQ,EACd,MAAM,MAAM,CACb,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,MAAM,GAAG,KAAK,EAAE,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,MAAM,GAAG,KAAK,SAAS,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,MAAM,GAAG,KAAK,QAAQ,CAAC,GACnH,KAAK,CAAA"}

package/dist/unstable/workflow/WorkflowProxyServer.js

@@ -3,8 +3,11 @@ import * as Effect from "../../Effect.js";
 import * as Layer from "../../Layer.js";
 import * as HttpApiBuilder from "../httpapi/HttpApiBuilder.js";
 /**
+ * Creates handlers for a workflow HTTP API group, wiring execute, discard, and
+ * resume endpoints to the supplied workflows.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layerHttpApi = (api, name, workflows) => HttpApiBuilder.group(api, name, Effect.fnUntraced(function* (handlers_) {
   let handlers = handlers_;
@@ -32,11 +35,14 @@ export const layerHttpApi = (api, name, workflows) => HttpApiBuilder.group(api,
   return handlers;
 }));
 /**
+ * Creates RPC handlers for the supplied workflows, wiring execute, discard,
+ * and resume RPCs to workflow operations.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layerRpcHandlers = (workflows, options) => Layer.effectContext(Effect.gen(function* () {
-  const services = yield* Effect.context();
+  const context = yield* Effect.context();
   const prefix = options?.prefix ?? "";
   const handlers = new Map();
   for (const workflow_ of workflows) {
@@ -48,19 +54,19 @@ export const layerRpcHandlers = (workflows, options) => Layer.effectContext(Effe
     const keyDiscard = `${key}Discard`;
     const keyResume = `${key}Resume`;
     handlers.set(key, {
-      services,
+      context,
       tag,
       handler: payload => workflow.execute(payload)
     });
     handlers.set(keyDiscard, {
-      services,
+      context,
       tag: tagDiscard,
       handler: payload => workflow.execute(payload, {
         discard: true
       })
     });
     handlers.set(keyResume, {
-      services,
+      context,
       tag: tagResume,
       handler: payload => workflow.resume(payload.executionId)
     });

package/dist/unstable/workflow/WorkflowProxyServer.js.map

@@ -1 +1 @@
-{"version":3,"file":"WorkflowProxyServer.js","names":["Context","Effect","Layer","HttpApiBuilder","layerHttpApi","api","name","workflows","group","fnUntraced","handlers_","handlers","workflow_","workflow","handle","payload","execute","pipe","tapDefect","logError","annotateLogs","module","method","discard","resume","executionId","layerRpcHandlers","options","effectContext","gen","services","context","prefix","Map","tag","tagDiscard","tagResume","key","keyDiscard","keyResume","set","handler","makeUnsafe"],"sources":["../../../src/unstable/workflow/WorkflowProxyServer.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"WorkflowProxyServer.js","names":["Context","Effect","Layer","HttpApiBuilder","layerHttpApi","api","name","workflows","group","fnUntraced","handlers_","handlers","workflow_","workflow","handle","payload","execute","pipe","tapDefect","logError","annotateLogs","module","method","discard","resume","executionId","layerRpcHandlers","options","effectContext","gen","context","prefix","Map","tag","tagDiscard","tagResume","key","keyDiscard","keyResume","set","handler","makeUnsafe"],"sources":["../../../src/unstable/workflow/WorkflowProxyServer.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/unstable/workflow/index.d.ts

@@ -2,34 +2,194 @@
  * @since 4.0.0
  */
 /**
+ * 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";

package/dist/unstable/workflow/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/unstable/workflow/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;GAEG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD;;GAEG;AACH,OAAO,KAAK,eAAe,MAAM,sBAAsB,CAAA;AAEvD;;GAEG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD;;GAEG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;GAEG;AACH,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAA;AAErD;;GAEG;AACH,OAAO,KAAK,aAAa,MAAM,oBAAoB,CAAA;AAEnD;;GAEG;AACH,OAAO,KAAK,mBAAmB,MAAM,0BAA0B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/unstable/workflow/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,eAAe,MAAM,sBAAsB,CAAA;AAEvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAA;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,aAAa,MAAM,oBAAoB,CAAA;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,mBAAmB,MAAM,0BAA0B,CAAA"}

package/dist/unstable/workflow/index.js

@@ -3,34 +3,194 @@
  */
 // @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.js";
 /**
+ * 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.js";
 /**
+ * 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.js";
 /**
+ * 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.js";
 /**
+ * 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.js";
 /**
+ * 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.js";
 /**
+ * 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.js";
 /**
+ * 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.js";

package/dist/unstable/workflow/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["Activity","DurableClock","DurableDeferred","DurableQueue","Workflow","WorkflowEngine","WorkflowProxy","WorkflowProxyServer"],"sources":["../../../src/unstable/workflow/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AAEA;;;AAGA,OAAO,KAAKA,QAAQ,MAAM,eAAe;AAEzC;;;AAGA,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AAEjD;;;AAGA,OAAO,KAAKC,eAAe,MAAM,sBAAsB;AAEvD;;;AAGA,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AAEjD;;;AAGA,OAAO,KAAKC,QAAQ,MAAM,eAAe;AAEzC;;;AAGA,OAAO,KAAKC,cAAc,MAAM,qBAAqB;AAErD;;;AAGA,OAAO,KAAKC,aAAa,MAAM,oBAAoB;AAEnD;;;AAGA,OAAO,KAAKC,mBAAmB,MAAM,0BAA0B","ignoreList":[]}
+{"version":3,"file":"index.js","names":["Activity","DurableClock","DurableDeferred","DurableQueue","Workflow","WorkflowEngine","WorkflowProxy","WorkflowProxyServer"],"sources":["../../../src/unstable/workflow/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AAEA;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,KAAKA,QAAQ,MAAM,eAAe;AAEzC;;;;;;;;;;;;;;;;;AAiBA,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AAEjD;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,KAAKC,eAAe,MAAM,sBAAsB;AAEvD;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,KAAKC,YAAY,MAAM,mBAAmB;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAO,KAAKC,QAAQ,MAAM,eAAe;AAEzC;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,KAAKC,cAAc,MAAM,qBAAqB;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,OAAO,KAAKC,aAAa,MAAM,oBAAoB;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,OAAO,KAAKC,mBAAmB,MAAM,0BAA0B","ignoreList":[]}