effect 4.0.0-beta.70 → 4.0.0-beta.72

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

@@ -2,98 +2,18 @@
  * @since 4.0.0
  */
 /**
- * Utilities for marking the parts of worker messages that should be transferred
- * through `postMessage` instead of copied by the structured clone algorithm.
- *
- * This module is used with worker message schemas to collect
- * `globalThis.Transferable` values while encoding a message, so the worker
- * platform can pass the collected list as the `postMessage` transfer list.
- * Common cases include sending large `Uint8Array` payloads, `ImageData` pixel
- * buffers, or `MessagePort` channels without paying for an extra copy.
- *
- * Transferable annotations do not make an otherwise unsupported value
- * structured-cloneable; the encoded message still has to be valid for
- * `postMessage`. Transferring also moves ownership to the receiver, so buffers
- * are detached from the sender after the send completes. Be careful when a
- * typed array view shares a backing buffer with other data, since collecting
- * that buffer transfers ownership of the whole buffer.
- *
  * @since 4.0.0
  */
 export * as Transferable from "./Transferable.ts";
 /**
- * Client-side worker primitives shared by browser, Node, and Bun platform
- * packages.
- *
- * A `WorkerPlatform` turns a numeric worker id into a long-lived `Worker`
- * client using a runtime-specific `Spawner`. This module is the low-level
- * building block used by worker-backed RPC clients and by platform adapters
- * that need to communicate with dedicated workers, shared workers,
- * `MessagePort`s, worker threads, or child-process transports while keeping
- * setup, message handling, and cleanup inside `Effect` scopes.
- *
- * The worker protocol separates spawning from message delivery. Calls to
- * `send` made before the platform reports readiness are buffered and flushed
- * after `run` receives the ready signal, so a spawned worker must eventually be
- * run or buffered messages will never leave the client. Message values are
- * passed through `postMessage`, which means callers are responsible for
- * encoding payloads into values supported by the selected runtime's structured
- * clone implementation. Transfer lists can avoid copies for buffers, ports, or
- * other transferable values, but ownership moves to the worker and invalid
- * transfer lists surface as `WorkerSendError`s. Incoming messages are handled
- * by forking each handler invocation into the worker run's `FiberSet`, so
- * processing is concurrent rather than serialized; use an explicit queue,
- * semaphore, or protocol-level acknowledgement when ordering or back pressure
- * matters.
- *
  * @since 4.0.0
  */
 export * as Worker from "./Worker.ts";
 /**
- * Typed error definitions for the unstable worker APIs.
- *
- * `WorkerError` is the shared error channel for `WorkerPlatform` and
- * `WorkerRunnerPlatform` implementations. The nested reason identifies where a
- * platform failure happened: spawning or setting up a worker, sending through
- * `postMessage`, receiving worker events, or handling a runtime-specific
- * failure that does not fit the other categories. This is useful when building
- * worker-backed RPC clients and servers, implementing a platform adapter, or
- * recovering differently from startup, transport, and worker-exit failures.
- *
- * Worker transports cross browser, Node, Bun, and child-process runtimes, so the
- * original cause is best treated as diagnostic data. Spawn failures can mean the
- * runner is not actually executing inside a worker context, send failures often
- * come from structured-clone or transfer-list problems, and receive failures
- * may be reported as `messageerror`, `error`, or exit events depending on the
- * runtime. The `WorkerErrorReason` schema supports encoding and decoding the
- * tagged reasons, but message payloads still need to be valid for the selected
- * worker protocol and runtime.
- *
  * @since 4.0.0
  */
 export * as WorkerError from "./WorkerError.ts";
 /**
- * Server-side worker runner primitives shared by the browser, Node, and Bun
- * platform packages.
- *
- * A `WorkerRunnerPlatform` is installed in code that is already running inside
- * a worker-like runtime. Starting it yields a `WorkerRunner`, which listens for
- * parent or client requests, identifies each connection with a numeric port id,
- * and sends responses back through the same transport. The main Effect use case
- * is `RpcServer.layerProtocolWorkerRunner`, but platform adapters can also use
- * these types to expose lower-level request handlers for dedicated workers,
- * shared workers, worker threads, or child-process channels.
- *
- * The wire protocol is intentionally small: inbound messages are
- * `PlatformMessage` values where `[0, payload]` is a request and `[1]` closes a
- * port. Higher-level protocols are responsible for encoding request and
- * response payloads before they cross the worker boundary. Values must still be
- * accepted by the selected runtime's message mechanism, so structured-clone
- * support, transfer lists, `messageerror` events, and single-port runtimes such
- * as Node or Bun should be considered when choosing payload schemas and
- * resource lifetimes. Handler effects run on the runtime captured by `run`, so
- * services required by the handler must be provided to the running effect.
- *
  * @since 4.0.0
  */
 export * as WorkerRunner from "./WorkerRunner.ts";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/unstable/workers/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAE/C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/unstable/workers/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD;;GAEG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;GAEG;AACH,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAE/C;;GAEG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA"}

package/dist/unstable/workers/index.js

@@ -3,98 +3,18 @@
  */
 // @barrel: Auto-generated exports. Do not edit manually.
 /**
- * Utilities for marking the parts of worker messages that should be transferred
- * through `postMessage` instead of copied by the structured clone algorithm.
- *
- * This module is used with worker message schemas to collect
- * `globalThis.Transferable` values while encoding a message, so the worker
- * platform can pass the collected list as the `postMessage` transfer list.
- * Common cases include sending large `Uint8Array` payloads, `ImageData` pixel
- * buffers, or `MessagePort` channels without paying for an extra copy.
- *
- * Transferable annotations do not make an otherwise unsupported value
- * structured-cloneable; the encoded message still has to be valid for
- * `postMessage`. Transferring also moves ownership to the receiver, so buffers
- * are detached from the sender after the send completes. Be careful when a
- * typed array view shares a backing buffer with other data, since collecting
- * that buffer transfers ownership of the whole buffer.
- *
  * @since 4.0.0
  */
 export * as Transferable from "./Transferable.js";
 /**
- * Client-side worker primitives shared by browser, Node, and Bun platform
- * packages.
- *
- * A `WorkerPlatform` turns a numeric worker id into a long-lived `Worker`
- * client using a runtime-specific `Spawner`. This module is the low-level
- * building block used by worker-backed RPC clients and by platform adapters
- * that need to communicate with dedicated workers, shared workers,
- * `MessagePort`s, worker threads, or child-process transports while keeping
- * setup, message handling, and cleanup inside `Effect` scopes.
- *
- * The worker protocol separates spawning from message delivery. Calls to
- * `send` made before the platform reports readiness are buffered and flushed
- * after `run` receives the ready signal, so a spawned worker must eventually be
- * run or buffered messages will never leave the client. Message values are
- * passed through `postMessage`, which means callers are responsible for
- * encoding payloads into values supported by the selected runtime's structured
- * clone implementation. Transfer lists can avoid copies for buffers, ports, or
- * other transferable values, but ownership moves to the worker and invalid
- * transfer lists surface as `WorkerSendError`s. Incoming messages are handled
- * by forking each handler invocation into the worker run's `FiberSet`, so
- * processing is concurrent rather than serialized; use an explicit queue,
- * semaphore, or protocol-level acknowledgement when ordering or back pressure
- * matters.
- *
  * @since 4.0.0
  */
 export * as Worker from "./Worker.js";
 /**
- * Typed error definitions for the unstable worker APIs.
- *
- * `WorkerError` is the shared error channel for `WorkerPlatform` and
- * `WorkerRunnerPlatform` implementations. The nested reason identifies where a
- * platform failure happened: spawning or setting up a worker, sending through
- * `postMessage`, receiving worker events, or handling a runtime-specific
- * failure that does not fit the other categories. This is useful when building
- * worker-backed RPC clients and servers, implementing a platform adapter, or
- * recovering differently from startup, transport, and worker-exit failures.
- *
- * Worker transports cross browser, Node, Bun, and child-process runtimes, so the
- * original cause is best treated as diagnostic data. Spawn failures can mean the
- * runner is not actually executing inside a worker context, send failures often
- * come from structured-clone or transfer-list problems, and receive failures
- * may be reported as `messageerror`, `error`, or exit events depending on the
- * runtime. The `WorkerErrorReason` schema supports encoding and decoding the
- * tagged reasons, but message payloads still need to be valid for the selected
- * worker protocol and runtime.
- *
  * @since 4.0.0
  */
 export * as WorkerError from "./WorkerError.js";
 /**
- * Server-side worker runner primitives shared by the browser, Node, and Bun
- * platform packages.
- *
- * A `WorkerRunnerPlatform` is installed in code that is already running inside
- * a worker-like runtime. Starting it yields a `WorkerRunner`, which listens for
- * parent or client requests, identifies each connection with a numeric port id,
- * and sends responses back through the same transport. The main Effect use case
- * is `RpcServer.layerProtocolWorkerRunner`, but platform adapters can also use
- * these types to expose lower-level request handlers for dedicated workers,
- * shared workers, worker threads, or child-process channels.
- *
- * The wire protocol is intentionally small: inbound messages are
- * `PlatformMessage` values where `[0, payload]` is a request and `[1]` closes a
- * port. Higher-level protocols are responsible for encoding request and
- * response payloads before they cross the worker boundary. Values must still be
- * accepted by the selected runtime's message mechanism, so structured-clone
- * support, transfer lists, `messageerror` events, and single-port runtimes such
- * as Node or Bun should be considered when choosing payload schemas and
- * resource lifetimes. Handler effects run on the runtime captured by `run`, so
- * services required by the handler must be provided to the running effect.
- *
  * @since 4.0.0
  */
 export * as WorkerRunner from "./WorkerRunner.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["Transferable","Worker","WorkerError","WorkerRunner"],"sources":["../../../src/unstable/workers/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AAEA;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,KAAKA,YAAY,MAAM,mBAAmB;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,OAAO,KAAKC,MAAM,MAAM,aAAa;AAErC;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,KAAKC,WAAW,MAAM,kBAAkB;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAO,KAAKC,YAAY,MAAM,mBAAmB","ignoreList":[]}
+{"version":3,"file":"index.js","names":["Transferable","Worker","WorkerError","WorkerRunner"],"sources":["../../../src/unstable/workers/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AAEA;;;AAGA,OAAO,KAAKA,YAAY,MAAM,mBAAmB;AAEjD;;;AAGA,OAAO,KAAKC,MAAM,MAAM,aAAa;AAErC;;;AAGA,OAAO,KAAKC,WAAW,MAAM,kBAAkB;AAE/C;;;AAGA,OAAO,KAAKC,YAAY,MAAM,mBAAmB","ignoreList":[]}

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

@@ -29,10 +29,10 @@ export declare const make: (options: {
     readonly duration: Duration.Input;
 }) => DurableClock;
 /**
- * Sleeps inside a workflow, using an in-memory activity for durations at or
+ * Waits inside a workflow, using an in-memory activity for durations at or
  * below the threshold and scheduling a durable clock for longer durations.
  *
- * @category Sleeping
+ * @category sleeping
  * @since 4.0.0
  */
 export declare const sleep: (options: {

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

@@ -1 +1 @@
-{"version":3,"file":"DurableClock.d.ts","sourceRoot":"","sources":["../../../src/unstable/workflow/DurableClock.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,QAAQ,MAAM,mBAAmB,CAAA;AAC7C,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,KAAK,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAE9C,OAAO,KAAK,eAAe,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAE3E,QAAA,MAAM,MAAM,kCAAkC,CAAA;AAE9C;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,MAAM,CAAA;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAA;IACpC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC,eAAe,CAAC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAA;CACvE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAA;CAClC,KAAG,YAKF,CAAA;AAaF;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,EAAE,CAClB,OAAO,EAAE;IACP,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAA;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;CACxD,KACE,MAAM,CAAC,MAAM,CAChB,IAAI,EACJ,KAAK,EACL,cAAc,GAAG,gBAAgB,CA8BjC,CAAA"}
+{"version":3,"file":"DurableClock.d.ts","sourceRoot":"","sources":["../../../src/unstable/workflow/DurableClock.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,QAAQ,MAAM,mBAAmB,CAAA;AAC7C,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,KAAK,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAE9C,OAAO,KAAK,eAAe,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAE3E,QAAA,MAAM,MAAM,kCAAkC,CAAA;AAE9C;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,MAAM,CAAA;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAA;IACpC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC,eAAe,CAAC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAA;CACvE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAA;CAClC,KAAG,YAKF,CAAA;AAaF;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,EAAE,CAClB,OAAO,EAAE;IACP,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAA;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;CACxD,KACE,MAAM,CAAC,MAAM,CAChB,IAAI,EACJ,KAAK,EACL,cAAc,GAAG,gBAAgB,CA8BjC,CAAA"}

package/dist/unstable/workflow/DurableClock.js

@@ -1,17 +1,29 @@
 /**
- * Durable workflow clocks provide workflow-safe timers and sleep operations.
+ * Workflow-safe sleeps that can be replayed, suspended, and resumed by a
+ * workflow engine.
  *
- * 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.
+ * Use this module when a workflow needs to pause for a timeout, reminder,
+ * deadline, retry delay, or scheduled wake-up. `sleep` keeps very short delays
+ * in the current process as an activity, and turns longer delays into durable
+ * clocks that the engine can schedule and resume through a durable deferred.
  *
- * 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.
+ * **Mental model**
+ *
+ * A `DurableClock` is a stable timer name, a normalized duration, and the
+ * deferred completed when the timer wakes. `sleep` is the workflow-facing
+ * helper: zero durations complete immediately, durations at or below the
+ * in-memory threshold run with `Effect.sleep` inside an activity, and longer
+ * durations are scheduled with the `WorkflowEngine` before awaiting the
+ * clock's deferred.
+ *
+ * **Gotchas**
+ *
+ * Timer names, durations, and thresholds are part of workflow behavior. Keep
+ * them deterministic for a given workflow path, avoid deriving them from
+ * ambient wall-clock state, and give distinct logical waits distinct names so
+ * replayed executions match the correct scheduled wake-up. Lower the in-memory
+ * threshold when a delay must survive the current process rather than relying
+ * on an in-process sleep.
  *
  * @since 4.0.0
  */
@@ -37,10 +49,10 @@ export const make = options => ({
 const EngineTag = /*#__PURE__*/Context.Service("effect/workflow/WorkflowEngine");
 const InstanceTag = /*#__PURE__*/Context.Service("effect/workflow/WorkflowEngine/WorkflowInstance");
 /**
- * Sleeps inside a workflow, using an in-memory activity for durations at or
+ * Waits inside a workflow, using an in-memory activity for durations at or
  * below the threshold and scheduling a durable clock for longer durations.
  *
- * @category Sleeping
+ * @category sleeping
  * @since 4.0.0
  */
 export const sleep = /*#__PURE__*/Effect.fnUntraced(function* (options) {

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

@@ -1 +1 @@
-{"version":3,"file":"DurableClock.js","names":["Context","Duration","Effect","Activity","DurableDeferred","TypeId","make","options","name","duration","fromInputUnsafe","deferred","EngineTag","Service","InstanceTag","sleep","fnUntraced","isZero","inMemoryThreshold","defaultInMemoryThreshold","isLessThanOrEqualTo","execute","engine","instance","clock","scheduleClock","workflow","executionId","await","seconds"],"sources":["../../../src/unstable/workflow/DurableClock.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;AAiBA,OAAO,KAAKA,OAAO,MAAM,kBAAkB;AAC3C,OAAO,KAAKC,QAAQ,MAAM,mBAAmB;AAC7C,OAAO,KAAKC,MAAM,MAAM,iBAAiB;AAEzC,OAAO,KAAKC,QAAQ,MAAM,eAAe;AACzC,OAAO,KAAKC,eAAe,MAAM,sBAAsB;AAGvD,MAAMC,MAAM,GAAG,+BAA+B;AAgB9C;;;;;;;AAOA,OAAO,MAAMC,IAAI,GAAIC,OAGpB,KAAoB;EACnB,CAACF,MAAM,GAAGA,MAAM;EAChBG,IAAI,EAAED,OAAO,CAACC,IAAI;EAClBC,QAAQ,EAAER,QAAQ,CAACS,eAAe,CAACH,OAAO,CAACE,QAAQ,CAAC;EACpDE,QAAQ,EAAEP,eAAe,CAACE,IAAI,CAAC,gBAAgBC,OAAO,CAACC,IAAI,EAAE;CAC9D,CAAC;AAEF,MAAMI,SAAS,gBAAGZ,OAAO,CAACa,OAAO,CAC/B,gCAAoE,CACrE;AAED,MAAMC,WAAW,gBAAGd,OAAO,CAACa,OAAO,CAIjC,iDAAuF,CACxF;AAED;;;;;;;AAOA,OAAO,MAAME,KAAK,gBAgBdb,MAAM,CAACc,UAAU,CAAC,WAAUT,OAI/B;EACC,MAAME,QAAQ,GAAGR,QAAQ,CAACS,eAAe,CAACH,OAAO,CAACE,QAAQ,CAAC;EAC3D,IAAIR,QAAQ,CAACgB,MAAM,CAACR,QAAQ,CAAC,EAAE;IAC7B;EACF;EAEA,MAAMS,iBAAiB,GAAGX,OAAO,CAACW,iBAAiB,GAC/CjB,QAAQ,CAACS,eAAe,CAACH,OAAO,CAACW,iBAAiB,CAAC,GACnDC,wBAAwB;EAE5B,IAAIlB,QAAQ,CAACmB,mBAAmB,CAACX,QAAQ,EAAES,iBAAiB,CAAC,EAAE;IAC7D,OAAO,OAAOf,QAAQ,CAACG,IAAI,CAAC;MAC1BE,IAAI,EAAE,gBAAgBD,OAAO,CAACC,IAAI,EAAE;MACpCa,OAAO,EAAEnB,MAAM,CAACa,KAAK,CAACN,QAAQ;KAC/B,CAAC;EACJ;EAEA,MAAMa,MAAM,GAAG,OAAOV,SAAS;EAC/B,MAAMW,QAAQ,GAAG,OAAOT,WAAW;EACnC,MAAMU,KAAK,GAAGlB,IAAI,CAACC,OAAO,CAAC;EAC3B,OAAOe,MAAM,CAACG,aAAa,CAACF,QAAQ,CAACG,QAAQ,EAAE;IAC7CC,WAAW,EAAEJ,QAAQ,CAACI,WAAW;IACjCH;GACD,CAAC;EACF,OAAO,OAAOpB,eAAe,CAACwB,KAAK,CAACJ,KAAK,CAACb,QAAQ,CAAC;AACrD,CAAC,CAAC;AAEF,MAAMQ,wBAAwB,gBAAGlB,QAAQ,CAAC4B,OAAO,CAAC,EAAE,CAAC","ignoreList":[]}
+{"version":3,"file":"DurableClock.js","names":["Context","Duration","Effect","Activity","DurableDeferred","TypeId","make","options","name","duration","fromInputUnsafe","deferred","EngineTag","Service","InstanceTag","sleep","fnUntraced","isZero","inMemoryThreshold","defaultInMemoryThreshold","isLessThanOrEqualTo","execute","engine","instance","clock","scheduleClock","workflow","executionId","await","seconds"],"sources":["../../../src/unstable/workflow/DurableClock.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,OAAO,KAAKA,OAAO,MAAM,kBAAkB;AAC3C,OAAO,KAAKC,QAAQ,MAAM,mBAAmB;AAC7C,OAAO,KAAKC,MAAM,MAAM,iBAAiB;AAEzC,OAAO,KAAKC,QAAQ,MAAM,eAAe;AACzC,OAAO,KAAKC,eAAe,MAAM,sBAAsB;AAGvD,MAAMC,MAAM,GAAG,+BAA+B;AAgB9C;;;;;;;AAOA,OAAO,MAAMC,IAAI,GAAIC,OAGpB,KAAoB;EACnB,CAACF,MAAM,GAAGA,MAAM;EAChBG,IAAI,EAAED,OAAO,CAACC,IAAI;EAClBC,QAAQ,EAAER,QAAQ,CAACS,eAAe,CAACH,OAAO,CAACE,QAAQ,CAAC;EACpDE,QAAQ,EAAEP,eAAe,CAACE,IAAI,CAAC,gBAAgBC,OAAO,CAACC,IAAI,EAAE;CAC9D,CAAC;AAEF,MAAMI,SAAS,gBAAGZ,OAAO,CAACa,OAAO,CAC/B,gCAAoE,CACrE;AAED,MAAMC,WAAW,gBAAGd,OAAO,CAACa,OAAO,CAIjC,iDAAuF,CACxF;AAED;;;;;;;AAOA,OAAO,MAAME,KAAK,gBAgBdb,MAAM,CAACc,UAAU,CAAC,WAAUT,OAI/B;EACC,MAAME,QAAQ,GAAGR,QAAQ,CAACS,eAAe,CAACH,OAAO,CAACE,QAAQ,CAAC;EAC3D,IAAIR,QAAQ,CAACgB,MAAM,CAACR,QAAQ,CAAC,EAAE;IAC7B;EACF;EAEA,MAAMS,iBAAiB,GAAGX,OAAO,CAACW,iBAAiB,GAC/CjB,QAAQ,CAACS,eAAe,CAACH,OAAO,CAACW,iBAAiB,CAAC,GACnDC,wBAAwB;EAE5B,IAAIlB,QAAQ,CAACmB,mBAAmB,CAACX,QAAQ,EAAES,iBAAiB,CAAC,EAAE;IAC7D,OAAO,OAAOf,QAAQ,CAACG,IAAI,CAAC;MAC1BE,IAAI,EAAE,gBAAgBD,OAAO,CAACC,IAAI,EAAE;MACpCa,OAAO,EAAEnB,MAAM,CAACa,KAAK,CAACN,QAAQ;KAC/B,CAAC;EACJ;EAEA,MAAMa,MAAM,GAAG,OAAOV,SAAS;EAC/B,MAAMW,QAAQ,GAAG,OAAOT,WAAW;EACnC,MAAMU,KAAK,GAAGlB,IAAI,CAACC,OAAO,CAAC;EAC3B,OAAOe,MAAM,CAACG,aAAa,CAACF,QAAQ,CAACG,QAAQ,EAAE;IAC7CC,WAAW,EAAEJ,QAAQ,CAACI,WAAW;IACjCH;GACD,CAAC;EACF,OAAO,OAAOpB,eAAe,CAACwB,KAAK,CAACJ,KAAK,CAACb,QAAQ,CAAC;AACrD,CAAC,CAAC;AAEF,MAAMQ,wBAAwB,gBAAGlB,QAAQ,CAAC4B,OAAO,CAAC,EAAE,CAAC","ignoreList":[]}

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

@@ -61,7 +61,7 @@ export declare const make: <Success extends Schema.Top = Schema.Void, Error exte
 declare const await_: <Success extends Schema.Top, Error extends Schema.Top>(self: DurableDeferred<Success, Error>) => Effect.Effect<Success["Type"], Error["Type"], WorkflowEngine | WorkflowInstance | Success["DecodingServices"] | Error["DecodingServices"]>;
 export { 
 /**
- * Awaits the durable deferred, suspending the current workflow when no
+ * Waits for the durable deferred, suspending the current workflow when no
  * persisted completion is available.
  *
  * @category combinators
@@ -124,14 +124,14 @@ export type TokenTypeId = typeof TokenTypeId;
  * Branded string token identifying a durable deferred for a workflow
  * execution.
  *
- * @category Token
+ * @category token
  * @since 4.0.0
  */
 export type Token = Brand.Branded<string, TokenTypeId>;
 /**
  * Schema for branded durable deferred tokens.
  *
- * @category Token
+ * @category token
  * @since 4.0.0
  */
 export declare const Token: Schema.brand<Schema.String, TokenTypeId>;
@@ -141,10 +141,10 @@ declare const TokenParsed_base: Schema.Class<TokenParsed, Schema.Struct<{
     readonly deferredName: Schema.String;
 }>, {}>;
 /**
- * Decoded representation of a durable deferred token containing the workflow
+ * Schema for a decoded durable deferred token containing the workflow
  * name, execution ID, and deferred name.
  *
- * @category Token
+ * @category token
  * @since 4.0.0
  */
 export declare class TokenParsed extends TokenParsed_base {
@@ -177,7 +177,7 @@ export declare class TokenParsed extends TokenParsed_base {
  * Creates a token for a durable deferred using the current workflow instance's
  * workflow name and execution ID.
  *
- * @category Token
+ * @category token
  * @since 4.0.0
  */
 export declare const token: <Success extends Schema.Top, Error extends Schema.Top>(self: DurableDeferred<Success, Error>) => Effect.Effect<Token, never, WorkflowInstance>;
@@ -185,7 +185,7 @@ export declare const token: <Success extends Schema.Top, Error extends Schema.To
  * Creates a durable deferred token from an explicit workflow, execution ID,
  * and deferred name.
  *
- * @category Token
+ * @category token
  * @since 4.0.0
  */
 export declare const tokenFromExecutionId: {
@@ -193,7 +193,7 @@ export declare const tokenFromExecutionId: {
      * Creates a durable deferred token from an explicit workflow, execution ID,
      * and deferred name.
      *
-     * @category Token
+     * @category token
      * @since 4.0.0
      */
     (options: {
@@ -204,7 +204,7 @@ export declare const tokenFromExecutionId: {
      * Creates a durable deferred token from an explicit workflow, execution ID,
      * and deferred name.
      *
-     * @category Token
+     * @category token
      * @since 4.0.0
      */
     <Success extends Schema.Top, Error extends Schema.Top>(self: DurableDeferred<Success, Error>, options: {
@@ -216,7 +216,7 @@ export declare const tokenFromExecutionId: {
  * Creates a durable deferred token by deriving the workflow execution ID from
  * the supplied workflow payload.
  *
- * @category Token
+ * @category token
  * @since 4.0.0
  */
 export declare const tokenFromPayload: {
@@ -224,7 +224,7 @@ export declare const tokenFromPayload: {
      * Creates a durable deferred token by deriving the workflow execution ID from
      * the supplied workflow payload.
      *
-     * @category Token
+     * @category token
      * @since 4.0.0
      */
     <W extends Workflow.Any>(options: {
@@ -235,7 +235,7 @@ export declare const tokenFromPayload: {
      * Creates a durable deferred token by deriving the workflow execution ID from
      * the supplied workflow payload.
      *
-     * @category Token
+     * @category token
      * @since 4.0.0
      */
     <Success extends Schema.Top, Error extends Schema.Top, W extends Workflow.Any>(self: DurableDeferred<Success, Error>, options: {

package/dist/unstable/workflow/DurableDeferred.js

@@ -75,7 +75,7 @@ const await_ = /*#__PURE__*/Effect.fnUntraced(function* (self) {
 });
 export {
 /**
- * Awaits the durable deferred, suspending the current workflow when no
+ * Waits for the durable deferred, suspending the current workflow when no
  * persisted completion is available.
  *
  * @category combinators
@@ -145,15 +145,15 @@ export const TokenTypeId = "~effect/workflow/DurableDeferred/Token";
 /**
  * Schema for branded durable deferred tokens.
  *
- * @category Token
+ * @category token
  * @since 4.0.0
  */
 export const Token = /*#__PURE__*/Schema.String.pipe(/*#__PURE__*/Schema.brand(TokenTypeId));
 /**
- * Decoded representation of a durable deferred token containing the workflow
+ * Schema for a decoded durable deferred token containing the workflow
  * name, execution ID, and deferred name.
  *
- * @category Token
+ * @category token
  * @since 4.0.0
  */
 export class TokenParsed extends /*#__PURE__*/Schema.Class("effect/workflow/DurableDeferred/TokenParsed")({
@@ -202,7 +202,7 @@ export class TokenParsed extends /*#__PURE__*/Schema.Class("effect/workflow/Dura
  * Creates a token for a durable deferred using the current workflow instance's
  * workflow name and execution ID.
  *
- * @category Token
+ * @category token
  * @since 4.0.0
  */
 export const token = /*#__PURE__*/Effect.fnUntraced(function* (self) {
@@ -213,7 +213,7 @@ export const token = /*#__PURE__*/Effect.fnUntraced(function* (self) {
  * Creates a durable deferred token from an explicit workflow, execution ID,
  * and deferred name.
  *
- * @category Token
+ * @category token
  * @since 4.0.0
  */
 export const tokenFromExecutionId = /*#__PURE__*/dual(2, (self, options) => new TokenParsed({
@@ -225,7 +225,7 @@ export const tokenFromExecutionId = /*#__PURE__*/dual(2, (self, options) => new
  * Creates a durable deferred token by deriving the workflow execution ID from
  * the supplied workflow payload.
  *
- * @category Token
+ * @category token
  * @since 4.0.0
  */
 export const tokenFromPayload = /*#__PURE__*/dual(2, (self, options) => Effect.map(options.workflow.executionId(options.payload), executionId => tokenFromExecutionId(self, {

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

@@ -1,19 +1,37 @@
 /**
- * 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.
+ * Durable workflow queues delegate work to persisted background workers and
+ * resume the waiting workflow with the worker result.
+ *
+ * A workflow 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 workflow can
+ * continue with the typed success or error.
+ *
+ * **Mental model**
+ *
+ * A `DurableQueue` definition names the persisted queue and carries the payload,
+ * success, and error schemas shared by producers and workers. The
+ * `idempotencyKey` becomes the persisted queue item id, while `process` also
+ * stores trace context and a deferred token alongside the payload. Worker
+ * concurrency is local to the worker layer; delivery and retry behavior come
+ * from the underlying `PersistedQueue`.
+ *
+ * **Common tasks**
+ *
+ * Use `make` to define the queue once, call `process` from workflow code, and
+ * run `worker` in the service responsible for executing queued work. Tune
+ * `process` retries for transient persistence failures, and tune worker
+ * concurrency for the downstream system being called.
+ *
+ * **Gotchas**
+ *
+ * Queue names, schemas, result types, and idempotency keys are persisted
+ * coordination state. Keep them deterministic and stable across deployments;
+ * changing them is a persistence migration. Delivery is at least once according
+ * to the backing `PersistedQueue`, so handlers should be idempotent and prepared
+ * for retries, duplicate observations, worker restarts, and completions that are
+ * decoded by a later version of the queue definition.
  *
  * @since 4.0.0
  */
@@ -53,8 +71,8 @@ export interface DurableQueue<Payload extends Schema.Top, Success extends Schema
     readonly deferred: DurableDeferred.DurableDeferred<Success, Error>;
 }
 /**
- * A `DurableQueue` wraps a `PersistedQueue`, providing a way to wait for items
- * to finish processing using a `DurableDeferred`.
+ * Creates a `DurableQueue` that waits for persisted items to finish processing
+ * using a `DurableDeferred`.
  *
  * **Example** (Defining a durable queue with workers)
  *
@@ -118,7 +136,7 @@ export declare const make: <Payload extends Schema.Top | Schema.Struct.Fields, S
     readonly error?: Error | undefined;
 }) => DurableQueue<Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload, Success, Error>;
 /**
- * Add an item to the queue and wait for a worker to process it.
+ * Adds an item to the queue and wait for a worker to process it.
  *
  * @category Processing
  * @since 4.0.0

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

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

package/dist/unstable/workflow/DurableQueue.js

@@ -1,19 +1,37 @@
 /**
- * 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.
+ * Durable workflow queues delegate work to persisted background workers and
+ * resume the waiting workflow with the worker result.
+ *
+ * A workflow 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 workflow can
+ * continue with the typed success or error.
+ *
+ * **Mental model**
+ *
+ * A `DurableQueue` definition names the persisted queue and carries the payload,
+ * success, and error schemas shared by producers and workers. The
+ * `idempotencyKey` becomes the persisted queue item id, while `process` also
+ * stores trace context and a deferred token alongside the payload. Worker
+ * concurrency is local to the worker layer; delivery and retry behavior come
+ * from the underlying `PersistedQueue`.
+ *
+ * **Common tasks**
+ *
+ * Use `make` to define the queue once, call `process` from workflow code, and
+ * run `worker` in the service responsible for executing queued work. Tune
+ * `process` retries for transient persistence failures, and tune worker
+ * concurrency for the downstream system being called.
+ *
+ * **Gotchas**
+ *
+ * Queue names, schemas, result types, and idempotency keys are persisted
+ * coordination state. Keep them deterministic and stable across deployments;
+ * changing them is a persistence migration. Delivery is at least once according
+ * to the backing `PersistedQueue`, so handlers should be idempotent and prepared
+ * for retries, duplicate observations, worker restarts, and completions that are
+ * decoded by a later version of the queue definition.
  *
  * @since 4.0.0
  */
@@ -33,8 +51,8 @@ import * as DurableDeferred from "./DurableDeferred.js";
  */
 export const TypeId = "~effect/workflow/DurableQueue";
 /**
- * A `DurableQueue` wraps a `PersistedQueue`, providing a way to wait for items
- * to finish processing using a `DurableDeferred`.
+ * Creates a `DurableQueue` that waits for persisted items to finish processing
+ * using a `DurableDeferred`.
  *
  * **Example** (Defining a durable queue with workers)
  *
@@ -116,7 +134,7 @@ const getQueueSchema = payload => {
   return schema;
 };
 /**
- * Add an item to the queue and wait for a worker to process it.
+ * Adds an item to the queue and wait for a worker to process it.
  *
  * @category Processing
  * @since 4.0.0