effect 4.0.0-beta.78 → 4.0.0-beta.79

package/src/unstable/sql/SqlError.ts

@@ -1,37 +1,12 @@
 /**
- * Structured SQL failures for unstable SQL clients and driver integrations.
+ * Defines structured failures for SQL clients and driver integrations.
  *
- * This module provides the top-level `SqlError` wrapper, the concrete
- * `SqlErrorReason` variants used by adapters, schemas for encoding or decoding
- * those errors, guards for recognizing them, and a SQLite classifier for native
- * driver causes. The model keeps query mistakes, authentication and
- * authorization failures, constraint violations, connection failures, lock
- * waits, deadlocks, serialization conflicts, statement timeouts, and unknown
- * failures distinguishable in the Effect error channel.
- *
- * **Mental model**
- *
- * `SqlError` wraps exactly one reason. Its `message`, `cause`, and
- * `isRetryable` values are delegated to that reason, so recovery code can branch
- * on either the reason tag or the retryability flag without losing the original
- * native cause. Reasons are intentionally driver-neutral; adapters translate
- * database-specific error codes into this shared vocabulary.
- *
- * **Common tasks**
- *
- * Construct a reason when adapting a driver failure, wrap it in `SqlError` for
- * client APIs, use `isSqlError` or `isSqlErrorReason` at boundaries that receive
- * unknown failures, and use `classifySqliteError` when mapping SQLite `code` or
- * `errno` values.
- *
- * **Gotchas**
- *
- * Preserve the native `cause` and `operation` metadata when constructing these
- * errors; they are often the only way to diagnose dialect-specific failures.
- * Retryable reasons represent transient infrastructure or concurrency problems,
- * while syntax, credential, permission, and constraint failures generally need a
- * changed query, configuration, or data set. SQLite unique violations include a
- * best-effort constraint name when one can be extracted.
+ * `SqlError` wraps the different reasons a SQL operation can fail, such as
+ * connection, authentication, authorization, syntax, constraint, or transaction
+ * problems. Each reason keeps the original cause, optional message and
+ * operation metadata, and whether retrying may succeed. This module also
+ * includes schemas, guards, a SQLite error classifier, and the
+ * `ResultLengthMismatch` error used by ordered batched SQL resolvers.
  *
  * @since 4.0.0
  */

package/src/unstable/sql/SqlModel.ts

@@ -1,20 +1,12 @@
 /**
  * Builds SQL repositories and request resolvers from Effect schema models.
  *
- * Use this module when a `Model` describes rows in a concrete SQL table and
- * you want the common insert, update, find-by-id, and delete operations without
- * hand-writing the schema encoding, row decoding, and resolver batching each
- * time. The helpers are intended for model-backed tables where the model field
- * names line up with the encoded table columns and the chosen `idColumn` is
- * present in both the model fields and update schema.
- *
- * Returned rows are decoded with the full model schema, while insert and update
- * requests are encoded with the model's dedicated input schemas. Soft deletes
- * are opt-in via `softDeleteColumn`: reads and updates only see rows where that
- * column is `null`, and deletes set it to `CURRENT_TIMESTAMP` instead of
- * removing the row. Dialects with `returning` support return changed rows
- * directly; MySQL performs a follow-up `select`, so generated ids, defaults,
- * and trigger-updated values must be observable from that query.
+ * Use this module when a schema `Model` represents rows in a SQL table and the
+ * usual insert, update, find-by-id, delete, and batching behavior should be
+ * derived from that model. The helpers encode insert and update input with the
+ * model's input schemas and decode returned rows with the full model schema.
+ * Soft deletes are optional, and SQL dialect differences such as `returning`
+ * support are handled by the repository implementation.
  *
  * @since 4.0.0
  */

package/src/unstable/sql/SqlResolver.ts

@@ -1,29 +1,12 @@
 /**
  * Schema-aware `RequestResolver` helpers for SQL-backed data loading.
  *
- * This module bridges `Effect.request` with `SqlClient` by representing each
- * lookup or mutation as a `SqlRequest` and batching concurrent requests into a
- * single SQL operation. Request payloads are encoded with the request schema
- * before `execute` is called, and rows returned by the query are decoded with
- * the result schema before entries are completed.
- *
- * Use `ordered` when a query returns exactly one row per request in the same
- * order, `findById` for `where id in (...)` lookups, `grouped` for one-to-many
- * relationships, and `void` for inserts, updates, deletes, or other
- * side-effecting statements where no row is needed.
- *
- * **Gotchas**
- *
- * - `ordered` requires the result count and order to match the request batch.
- * - `grouped` and `findById` rely on stable request/result keys and fail
- *   missing requests with `NoSuchElementError`.
- * - Equal payloads are equal `SqlRequest`s, which enables request batching,
- *   deduplication, and cache reuse; model payload identity deliberately.
- * - Batches are split by the active SQL transaction connection, so requests
- *   made in different transactions are not resolved together.
- * - Queries like `where id in (...)` often return rows in database order; use
- *   `findById` or `grouped`, or preserve input order explicitly before choosing
- *   `ordered`.
+ * This module represents each lookup or mutation as a `SqlRequest` and batches
+ * concurrent requests into SQL operations. Request payloads are encoded with the
+ * request schema before `execute` is called, and returned rows are decoded with
+ * the result schema before requests are completed. It provides ordered,
+ * grouped, id-based, and side-effect-only resolver constructors, and keeps
+ * batches separated by the active SQL transaction connection.
  *
  * @since 4.0.0
  */

package/src/unstable/sql/SqlSchema.ts

@@ -4,33 +4,9 @@
  * `SqlSchema` is a small adapter between Effect Schema and SQL statements. Each
  * helper builds a function that accepts the decoded request type used by
  * application code, encodes it before calling `execute`, and decodes unknown
- * driver rows into the result schema. The helpers differ only in how many rows
- * they expect and how they represent an empty result set.
- *
- * **Mental model**
- *
- * The request schema protects the boundary going into SQL, and the result
- * schema protects the boundary coming back out. `execute` still owns statement
- * construction and database execution; this module only shapes the values that
- * cross that boundary.
- *
- * **Common tasks**
- *
- * - Use {@link findAll} for queries that may return any number of rows.
- * - Use {@link findNonEmpty} when an empty result is a failure.
- * - Use {@link findOne} when the first row is required.
- * - Use {@link findOneOption} when the first row is optional.
- * - Use `void` for writes where the encoded request matters but the driver
- *   result should be discarded.
- *
- * **Gotchas**
- *
- * `execute` receives `Req["Encoded"]`, not `Req["Type"]`. Any schema
- * transformations, encoding services, nullable columns, JSON values, dates, and
- * bigint representations must match the SQL builder and dialect in use. Result
- * schemas decode rows after SQL client row transforms have run. {@link findOne}
- * and {@link findOneOption} only inspect the first returned row; they do not
- * assert that the query returned exactly one row.
+ * driver rows into the result schema. The helpers cover returning all rows, a
+ * non-empty row list, the first row, an optional first row, or discarding the
+ * SQL result for side-effect-only statements.
  *
  * @since 4.0.0
  */

package/src/unstable/sql/SqlStream.ts

@@ -9,16 +9,6 @@
  * `Connection.executeStream`, so callers can process large result sets
  * incrementally instead of materializing every row in memory.
  *
- * The adapter is scoped: driver cursors, query streams, or reserved
- * connections should be acquired in the registration effect and released with
- * finalizers. The internal queue is bounded and calls the producer's
- * `onPause`/`onResume` hooks when downstream consumption falls behind, but the
- * underlying driver still has to honor those hooks for backpressure to be
- * effective. Slow consumers may keep a database cursor and connection open for
- * the lifetime of the stream, so integrations should close or destroy driver
- * resources on interruption, failure, or normal completion and should signal
- * terminal events with `fail` or `end` exactly once.
- *
  * @since 4.0.0
  */
 import * as Cause from "../../Cause.ts"

package/src/unstable/sql/Statement.ts

@@ -1,40 +1,12 @@
 /**
  * Low-level SQL statement and fragment primitives.
  *
- * This module is the foundation used by SQL clients to build executable,
- * parameterized SQL. It defines the {@link Statement} and {@link Fragment}
- * models, the tagged-template {@link Constructor}, segment constructors for
- * identifiers, parameters, literals, arrays, records, and custom dialect data,
- * plus compilers that render those segments into dialect-specific SQL text and
- * bind parameters.
- *
- * **Mental model**
- *
- * A statement is a sequence of {@link Segment} values. In a tagged template,
- * nested fragments and known segments are spliced into that sequence, while
- * ordinary interpolated values become bound parameters. A {@link Compiler}
- * turns the sequence into SQL for one dialect, escaping identifiers and
- * formatting placeholders for that dialect. Executing a {@link Statement} uses
- * the connection acquirer captured by {@link make} and can return rows, raw
- * results, streams, values, or unprepared execution paths.
- *
- * **Common tasks**
- *
- * - Build statements with a {@link Constructor} tagged template
- * - Use {@link identifier} for table and column names rather than interpolating
- *   plain strings
- * - Compose optional clauses with {@link and}, {@link or}, {@link csv}, and
- *   {@link join}
- * - Create insert and update fragments with record helpers
- * - Add custom segment handling with {@link custom} and {@link makeCompiler}
- *
- * **Gotchas**
- *
- * Bound parameters protect values, not SQL syntax. Use `literal` and `unsafe`
- * only for trusted SQL text, and use identifiers for names that need escaping.
- * Compiled SQL is dialect-specific and cached on the statement;
- * `withoutTransform` intentionally bypasses identifier or row transforms, so
- * its output can differ from normal execution.
+ * `SqlClient` uses this module to build executable, parameterized SQL from
+ * reusable fragments. A statement can be executed, streamed, run without row
+ * transformation, or compiled to SQL text and parameters for a specific
+ * dialect. The module also contains helpers for identifiers, parameters,
+ * inserts, updates, custom dialect fragments, statement compilation, and row
+ * transformation.
  *
  * @since 4.0.0
  */

package/src/unstable/workers/Transferable.ts

@@ -8,27 +8,6 @@
  * Worker platforms then pass the collected values as the transfer list for the
  * same `postMessage` call, avoiding copies for large payloads and ports.
  *
- * **Mental model**
- *
- * A `Collector` is an optional context service. During encoding, `getterAddAll`
- * and `schema` add transferable values when a collector is present and leave the
- * encoded value unchanged. The built-in `Uint8Array`, `ImageData`, and
- * `MessagePort` schemas are convenience wrappers around the same behavior.
- *
- * **Common tasks**
- *
- * Wrap a worker message field with `schema` when the transferable is nested or
- * derived from the encoded value. Provide a fresh collector around each message
- * encode, read or clear it after encoding, and pass the resulting list to the
- * worker transport.
- *
- * **Gotchas**
- *
- * Transfer annotations do not make unsupported values structured-cloneable.
- * Ownership moves to the receiver after `postMessage`, so buffers are detached
- * from the sender. For typed array views, collecting `view.buffer` transfers the
- * whole backing buffer, including bytes used by other views.
- *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"

package/src/unstable/workers/Worker.ts

@@ -1,40 +1,12 @@
 /**
  * Client-side worker primitives shared by browser, Node, and Bun adapters.
  *
- * This module defines the platform-neutral {@link Worker} client and the
- * {@link WorkerPlatform} service that creates one for a numeric worker id.
- * Platform packages provide the runtime-specific spawn, setup, listen, and
- * cleanup logic; higher-level code uses the resulting worker to send messages
- * and run an Effect handler for messages coming back from the worker.
- *
- * **Mental model**
- *
- * A {@link Spawner} locates or creates the native worker value, and
- * {@link makePlatform} turns platform hooks into a scoped {@link Worker}.
- * Sending and receiving are separate: `send` queues outbound values until
- * `run` observes the platform ready signal, then `run` keeps the message loop
- * alive and owns the cleanup scope for the active port.
- *
- * **Common tasks**
- *
- * Use {@link layerSpawner} to provide the runtime's worker lookup function,
- * {@link makePlatform} to build browser, Node, Bun, or custom adapters, and
- * {@link makeUnsafe} when an adapter already exposes the low-level platform
- * protocol. Worker-backed RPC clients use these primitives to communicate with
- * dedicated workers, shared workers, `MessagePort`s, worker threads, or child
- * processes.
- *
- * **Gotchas**
- *
- * - Messages sent before readiness are buffered, so the returned worker must be
- *   run or those messages never leave the client
- * - Values pass through `postMessage`; callers must use values supported by
- *   the selected runtime's structured clone implementation
- * - Transfer lists can avoid copies, but ownership moves to the worker and
- *   invalid transfer lists fail with `WorkerSendError`
- * - Incoming messages are handled concurrently in the run fiber set; add a
- *   queue, semaphore, or protocol acknowledgement when ordering or back
- *   pressure matters
+ * This module defines the platform-neutral `Worker` client, the `WorkerPlatform`
+ * service that creates workers by numeric id, and the `Spawner` service used to
+ * find platform-specific worker instances. `makePlatform` wraps platform setup
+ * and listen hooks into a `WorkerPlatform`, buffers outgoing messages until the
+ * worker is ready, runs incoming messages with Effect handlers, and ties worker
+ * cleanup to scope lifetime.
  *
  * @since 4.0.0
  */

package/src/unstable/workers/WorkerError.ts

@@ -1,38 +1,9 @@
 /**
- * The `WorkerError` module defines the typed error model shared by the
- * unstable worker APIs. Worker client and runner platforms use
- * {@link WorkerError} when platform setup, sending, receiving, or
- * runtime-specific worker behavior fails.
+ * Typed error model for worker APIs.
  *
- * **Mental model**
- *
- * - {@link WorkerError} is the outer error exposed in worker effect error
- *   channels
- * - {@link WorkerErrorReason} records one tagged reason: spawn, send,
- *   receive, or unknown
- * - The outer error delegates `message` and `cause` to the nested reason
- * - Reason schemas can be encoded and decoded when worker or RPC layers need
- *   structured diagnostics
- *
- * **Common tasks**
- *
- * - Detect worker failures with {@link isWorkerError}
- * - Classify startup and setup problems with {@link WorkerSpawnError}
- * - Classify `postMessage` or transfer-list failures with
- *   {@link WorkerSendError}
- * - Classify inbound event, `messageerror`, or worker-exit failures with
- *   {@link WorkerReceiveError}
- * - Preserve runtime-specific failures that do not fit another case with
- *   {@link WorkerUnknownError}
- *
- * **Gotchas**
- *
- * - The `cause` is diagnostic data and can have different shapes across
- *   browser, Node, Bun, and child-process transports
- * - A `WorkerSendError` often means the payload was invalid for the selected
- *   structured-clone or transfer-list rules
- * - A `WorkerSpawnError` can mean the runner code is not executing inside the
- *   expected worker context
+ * This module defines the `WorkerError` wrapper, the reason variants for spawn,
+ * send, receive, and unknown worker failures, a schema union for those reasons,
+ * and a guard for recognizing worker errors at runtime.
  *
  * @since 4.0.0
  */

package/src/unstable/workers/WorkerRunner.ts

@@ -1,35 +1,10 @@
 /**
- * Platform-neutral primitives for code running inside worker-like runtimes.
+ * Worker-side primitives for worker-like runtimes.
  *
- * This module gives browser workers, shared workers, Node worker threads, Bun
- * workers, and child-process adapters the same server-side shape: start a
- * runner, receive messages tagged by a numeric port id, and send replies back
- * through the matching transport.
- *
- * **Mental model**
- *
- * `WorkerRunnerPlatform` is installed inside the worker-like runtime. Starting
- * it yields a `WorkerRunner`, and `WorkerRunner.run` attaches the message
- * handler. Incoming values use the small `PlatformMessage` protocol:
- * `[0, payload]` delivers a request and `[1]` closes a port. Higher-level
- * protocols, such as RPC over workers, decide how payloads are encoded before
- * they reach this layer.
- *
- * **Common tasks**
- *
- * - Start the current platform from the {@link WorkerRunnerPlatform} service
- * - Handle inbound messages with `WorkerRunner.run`
- * - Send responses or notifications with `WorkerRunner.send`
- * - Observe optional disconnect notifications through `WorkerRunner.disconnects`
- *
- * **Gotchas**
- *
- * This module does not serialize payloads; values must already be acceptable to
- * the selected runtime's message mechanism. Structured-clone support, transfer
- * lists, `messageerror` events, and single-port runtimes such as Node or Bun
- * all affect which payloads and resource lifetimes are safe. Handler effects
- * run on the runtime captured by `run`, so services required by a handler must
- * be provided to that running effect.
+ * A `WorkerRunner` receives messages tagged by a numeric port id, sends replies
+ * back through the same transport, and can expose disconnect notifications. The
+ * module also defines the small platform message shape and the
+ * `WorkerRunnerPlatform` service that starts a platform-specific runner.
  *
  * @since 4.0.0
  */

package/src/unstable/workflow/Activity.ts

@@ -1,23 +1,10 @@
 /**
- * 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.
+ * Defines named effects whose results can be stored by a workflow engine.
  *
- * 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.
+ * An `Activity` is an `Effect` with a stable name and schemas for its success
+ * and error values. `make` wraps an effect so the `WorkflowEngine` can execute
+ * it, store its result, or replay that result during a workflow run. This module
+ * also includes helpers for retry attempts, idempotency keys, and durable races.
  *
  * @since 4.0.0
  */

package/src/unstable/workflow/DurableClock.ts

@@ -1,29 +1,10 @@
 /**
- * Workflow-safe sleeps that can be replayed, suspended, and resumed by a
- * workflow engine.
+ * Durable timers for workflow sleeps.
  *
- * 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.
- *
- * **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.
+ * `make` creates a `DurableClock` with a name, duration, and deferred wake-up
+ * signal. `sleep` ignores zero durations, runs short sleeps through an
+ * in-memory activity, and schedules longer sleeps through the `WorkflowEngine`
+ * before awaiting the durable deferred tied to the clock.
  *
  * @since 4.0.0
  */

package/src/unstable/workflow/DurableDeferred.ts

@@ -1,23 +1,11 @@
 /**
- * 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`.
+ * Defines named wait points for durable workflow executions.
  *
- * 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.
+ * A `DurableDeferred` has a stable name and schemas for the value that will be
+ * recorded later. Workflows can await it, suspend when no result exists yet, and
+ * resume after its result is recorded. Tokens identify the workflow name,
+ * execution id, and deferred name so external code can complete the correct
+ * wait point later.
  *
  * @since 4.0.0
  */

package/src/unstable/workflow/DurableQueue.ts

@@ -8,31 +8,6 @@
  * 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
  */
 import * as Effect from "../../Effect.ts"

package/src/unstable/workflow/Workflow.ts

@@ -1,24 +1,12 @@
 /**
- * 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 tag 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.
+ * Defines typed durable workflows.
+ *
+ * A `Workflow` has a stable tag, schemas for payload, success, and failure, and
+ * an idempotency key used to derive execution ids. Workflow definitions can be
+ * executed, discarded, polled, interrupted, resumed, and registered with a
+ * handler layer. This module also includes workflow result types, compensation
+ * and cleanup helpers, suspension support, and settings for defect capture or
+ * failure suspension.
  *
  * @since 4.0.0
  */
@@ -104,7 +92,7 @@ export interface Workflow<
   >
 
   /**
-   * Execute the workflow with the given payload.
+   * Poll the current status of a workflow execution.
    */
   readonly poll: (
     executionId: string

package/src/unstable/workflow/WorkflowEngine.ts

@@ -1,23 +1,11 @@
 /**
- * Workflow engine service definitions and the default in-memory engine used to
- * run durable workflows.
+ * Defines workflow engine services and an in-memory implementation.
  *
- * 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.
+ * `WorkflowEngine` registers workflow handlers, runs executions, polls results,
+ * resumes suspended runs, executes activities, stores durable deferred results,
+ * and schedules durable clocks. `WorkflowInstance` holds the runtime state for
+ * one workflow run. The in-memory layer is useful for tests and local
+ * development.
  *
  * @since 4.0.0
  */
@@ -111,7 +99,7 @@ export class WorkflowEngine extends Context.Service<
     >
 
     /**
-     * Execute a registered workflow.
+     * Poll the current status of a registered workflow execution.
      */
     readonly poll: <
       Name extends string,

package/src/unstable/workflow/WorkflowProxy.ts

@@ -1,27 +1,11 @@
 /**
- * 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.
+ * RPC and HTTP API definitions for workflows.
+ *
+ * Given one or more `Workflow` values, `toRpcGroup` creates the RPC definitions
+ * for clients and servers, while `toHttpApiGroup` creates HTTP POST endpoints
+ * that can be mounted in an API. Each workflow gets execute, discard, and
+ * resume operations, so callers can start a workflow or resume a suspended run
+ * by `executionId` without importing the workflow handler directly.
  *
  * @since 4.0.0
  */