pure-effect 0.6.0 → 0.8.0

package/.claude/settings.local.json

@@ -5,7 +5,9 @@
       "Bash(npm test *)",
       "Bash(git *)",
       "Bash(node *)",
-      "Bash(npx tsc *)"
+      "Bash(npx tsc *)",
+      "Bash(npx tsd *)",
+      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); hooks=d.get\\('hooks',{}\\); print\\(json.dumps\\(hooks, indent=2\\)\\)\")"
     ]
   }
 }

package/CLAUDE.md

@@ -17,41 +17,55 @@ No build or lint step — the library ships as plain ES modules with no transpil
 
 ### Core abstractions (all in `index.js`)
 
-| Export                         | Shape                                      | Purpose                                                                                |
-| ------------------------------ | ------------------------------------------ | -------------------------------------------------------------------------------------- |
-| `Success(value)`               | `{ type: 'Success', value }`               | Wraps a successful result                                                              |
-| `Failure(error, initialInput)` | `{ type: 'Failure', error, initialInput }` | Short-circuits the pipeline                                                            |
-| `Command(cmdFn, nextFn, meta)` | `{ type: 'Command', cmd, next, meta }`     | Defers a side effect for the interpreter                                               |
-| `Ask(nextFn)`                  | `{ type: 'Ask', next }`                    | Reads the `context` passed to `runEffect`; passes it to `nextFn`                       |
-| `effectPipe(...fns)`           | —                                          | Composes functions into a sequential pipeline via `chain`                              |
-| `runEffect(effect, context)`   | async                                      | Interpreter: traverses the effect tree, executes Commands; resolves `Ask` with context |
-| `configureEffect(options)`     | —                                          | Injects telemetry hooks (`onStep`, `onRun`, `onBeforeCommand`)                         |
+| Export                                    | Shape                                      | Purpose                                                                                                                                                  |
+| ----------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Success(value)`                          | `{ type: 'Success', value }`               | Wraps a successful result                                                                                                                                |
+| `Failure(error, initialInput)`            | `{ type: 'Failure', error, initialInput }` | Short-circuits the pipeline                                                                                                                              |
+| `Command(cmdFn, nextFn, meta)`            | `{ type: 'Command', cmd, next, meta }`     | Defers a side effect for the interpreter                                                                                                                 |
+| `Ask(nextFn)`                             | `{ type: 'Ask', next }`                    | Reads the `context` passed to `runEffect`; passes it to `nextFn`                                                                                         |
+| `Retry(effect, options)`                  | `{ type: 'Retry', effect, options, next }` | Wraps any Effect tree with retry-on-failure semantics; handled natively by the interpreter                                                               |
+| `Parallel(effects, next)`                 | `{ type: 'Parallel', effects, next }`      | Runs multiple Effect trees concurrently via `Promise.all`; returns the first Failure by array order if any effect fails; context flows into all branches |
+| `effectPipe(...fns)`                      | —                                          | Composes functions into a sequential pipeline via `chain`                                                                                                |
+| `runEffect(effect, context, callConfig?)` | async                                      | Interpreter: traverses the effect tree, executes Commands; resolves `Ask` and `Retry`; per-call `callConfig` overrides global defaults                   |
+| `configureEffect(options)`                | —                                          | Sets process-wide telemetry hooks (`onStep`, `onRun`, `onBeforeCommand`) and global `retry` defaults; overridden by per-call `callConfig`                |
 
 ### Data flow
 
 ```
 effectPipe(f1, f2, f3)(input)
-  → returns tree of Success / Failure / Command / Ask values
-  → f1 runs eagerly here
+  → returns tree of Success / Failure / Command / Ask / Retry values
+  → f1 runs eagerly here; initialInput is threaded through chain so every
+    node in the tree carries it without post-construction mutation
 
-runEffect(tree, context)
+runEffect(tree, context, callConfig?)
+  → per-call callConfig merges over global configureEffect defaults
   → executes Commands async, passes results into next(result), repeats
   → resolves Ask by calling next(context), continues
+  → resolves Retry via an inner execute() loop (not recursive runEffect),
+    so onRun fires exactly once per runEffect call regardless of attempts;
+    on exhaustion returns Failure({ retryExhausted: true, lastError, attempts })
+  → resolves Parallel by running all effects via Promise.all with the same
+    context; if any effect returns Failure, returns the first Failure by
+    array index and skips next; otherwise calls next with the array of
+    unwrapped success values
   → resolves to final Success or Failure
 ```
 
-The `chain` combinator (internal) drives composition: `Success` passes its value to the next function, `Failure` short-circuits, `Command` defers execution, `Ask` wraps its continuation so the chain propagates through it. `runEffect` loops through the tree with a `while` loop rather than recursion.
+The `chain` combinator (internal) drives composition: `Success` passes its value to the next function, `Failure` short-circuits, `Command` defers execution, `Ask` wraps its continuation so the chain propagates through it, `Retry` wraps its continuation via object spread (same pattern as `Ask`). `chain` accepts an optional `initialInput` parameter; `effectPipe` passes the pipeline's starting value through every `chain` call so that `initialInput` is stamped on all nodes — including mid-pipeline `Failure`s — without mutation. `runEffect` loops through the tree with a `while` loop rather than recursion.
 
-`configureEffect` hooks:
+`configureEffect` options (all overridable per-call via `runEffect`'s third argument):
 
 - `onStep` — fires on every Command execution; wraps the `cmd` call (use for per-command tracing)
-- `onRun` — fires once per `runEffect` call; wraps the whole workflow (use for top-level spans); receives `context.flowName` as the third argument
+- `onRun` — fires once per `runEffect` call; wraps the whole workflow (use for top-level spans); receives `context.flowName` as the third argument; does **not** fire again for Retry attempts
 - `onBeforeCommand` — intercepts each Command before execution; receives the Command and the `context` passed to `runEffect`
+- `retry` — global Retry defaults `{ attempts, delay, backoff }`; per-use options passed to `Retry(effect, options)` merge on top (defaults: `attempts: 3`, `delay: 100ms`, `backoff: 1` flat)
 
 ### TypeScript
 
 Full generic type declarations are in `index.d.ts` and referenced via the `types` field in `package.json`. Type-level tests live in `test/types.test-d.ts` and run via `tsd` as part of `npm test`.
 
+`Effect<T, E, Ctx>` carries three type parameters: value type, error union, and context type. `Ctx` flows through `AskState`, `CommandState`, `RetryState`, and all `effectPipe` overloads. `Ask<T, E, Ctx>` types the context callback parameter, and `runEffect<T, E, Ctx>` enforces that the supplied context matches. `Ctx` defaults to `unknown` so existing code without context typing is unaffected.
+
 ### Observability
 
 `opentelemetry-example.js` shows how to wire OpenTelemetry spans into `configureEffect`'s hooks — it is reference code, not part of the library.

package/README.md

@@ -1,10 +1,30 @@
 # Pure Effect
 
-**Pure Effect** is a tiny, zero-dependency effect system for writing pure, testable JavaScript without mocks.
-
-It implements the "Functional Core, Imperative Shell" pattern, allowing you to decouple your business logic from external side effects like database calls or API requests. Instead of executing side effects immediately, your functions return Commands which are executed later by an interpreter.
-
-**Pure Effect** ships with JSDoc type annotations for JavaScript users and a bundled declaration file with full generic types for TypeScript users.
+[![npm version](https://img.shields.io/npm/v/pure-effect)](https://www.npmjs.com/package/pure-effect)
+[![bundle size](https://img.shields.io/badge/minified%2Bgzipped-%3C1KB-brightgreen)](https://bundlephobia.com/package/pure-effect)
+[![license](https://img.shields.io/npm/l/pure-effect)](./LICENSE)
+
+**Pure Effect** is a zero-dependency effect library for JavaScript and TypeScript with built-in support for dependency injection, retry, and OpenTelemetry where business logic is plain data you can test without mocks.
+
+- No mocks needed to test async pipelines
+- Inject context without touching function signatures
+- Built-in retry and parallel execution with configurable delay, backoff, and `Promise.all` semantics
+- OpenTelemetry-ready via lifecycle hooks
+- Zero dependencies, under 1 KB minified and gzipped
+- Works in JavaScript and TypeScript (full generics, bundled `.d.ts`)
+- Six primitives: learn the whole API in an afternoon
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Testing Without Mocks](#testing-without-mocks)
+- [Passing Runtime Context](#passing-runtime-context)
+- [Retrying Transient Failures](#retrying-transient-failures)
+- [Running Effects in Parallel](#running-effects-in-parallel)
+- [TypeScript: Typed Errors and Context](#typescript-typed-errors-and-context)
+- [Why Pure Effect](#why-pure-effect)
+- [API Reference](#api-reference)
 
 ## Installation
 
@@ -12,9 +32,9 @@ It implements the "Functional Core, Imperative Shell" pattern, allowing you to d
 npm install pure-effect
 ```
 
-## Usage
+## Quick Start
 
-Here is a complete example of a User Registration flow.
+Here is a complete example of a user registration flow:
 
 ```js
 import { Success, Failure, Command, effectPipe, runEffect } from 'pure-effect';
@@ -25,40 +45,33 @@ const validateRegistration = (input) => {
     return Success(input);
 };
 
-// These functions do NOT run the DB call. They return a Command object.
-// The 'next' function defines what happens with the result of the async call.
+// These functions return a Command object. They do NOT call the database.
 const findUser = (email) => {
-    const cmdFindUser = () => db.findUser(email); // The work to do later
-    const next = (user) => Success(user); // Wrap result in Success
-    return Command(cmdFindUser, next);
+    const cmdFindUser = () => db.findUser(email);
+    return Command(cmdFindUser, (user) => Success(user));
 };
 
 const saveUser = (input) => {
     const cmdSaveUser = () => db.saveUser(input);
-    const next = (saved) => Success(saved);
-    return Command(cmdSaveUser, next);
+    return Command(cmdSaveUser, (saved) => Success(saved));
 };
 
-const ensureEmailAvailable = (user) => {
-    return user ? Failure('Email already in use.') : Success(true);
-};
+const ensureEmailAvailable = (user) => (user ? Failure('Email already in use.') : Success(true));
 
-// The Pipeline uses arrow functions to capture 'input' from the scope where needed.
+// effectPipe threads the output of each step into the next.
+// When you need to use a captured variable instead of the piped value,
+// wrap the call in an arrow function.
 const registerUserFlow = (input) =>
     effectPipe(
-        validateRegistration,
-        () => findUser(input.email),
-        ensureEmailAvailable,
-        () => saveUser(input)
+        validateRegistration, // input -> Success(input)
+        () => findUser(input.email), // ignores piped value, uses captured input
+        ensureEmailAvailable, // found user (or null) -> Success(true)
+        () => saveUser(input) // ignores piped value, uses captured input
     )(input);
 
-// The Imperative Shell
+// Imperative shell: this is the only place side effects run
 async function registerUser(input) {
-    // logic is just a data structure until we pass it to runEffect
-    const logic = registerUserFlow(input);
-
-    // runEffect performs the actual async work
-    const result = await runEffect(logic);
+    const result = await runEffect(registerUserFlow(input));
 
     if (result.type === 'Success') {
         console.log('User created:', result.value);
@@ -70,142 +83,290 @@ async function registerUser(input) {
 
 ## Testing Without Mocks
 
-The biggest benefit of **Pure Effect** is testability. Because `registerUserFlow` returns a data structure (a tree of objects) instead of running a Promise, you can test your logic without mocking the database.
+Because pipelines return plain objects, you can assert on _what the code intends to do_ without executing any of it. Using the registration flow defined in the previous section:
 
 ```js
-// 1. Test Validation Failure
+// 1. Test validation failure synchronously
 const badInput = { email: 'bad-email', password: '123' };
 const result = registerUserFlow(badInput);
 
-assert.deepEqual(result, Failure('Invalid email format.', badInput));
-// ✅ Logic tested instantly, no async needed.
+assert.deepEqual(result, Failure('Invalid email.', badInput));
 
-// 2. Test Flow Intent (Introspection)
+// 2. Walk the pipeline to verify intent
 const goodInput = { email: 'test@test.com', password: 'password123' };
 const step1 = registerUserFlow(goodInput);
 
-// Check if the first thing the code does is try to find a user
+// First thing the code does: look up the user
 assert.equal(step1.type, 'Command');
 assert.equal(step1.cmd.name, 'cmdFindUser');
 
-// Check if the next thing the code will do is to save a user
+// Next thing: save the user (simulate "user not found" result)
 const step2 = step1.next(null);
 assert.equal(step2.type, 'Command');
 assert.equal(step2.cmd.name, 'cmdSaveUser');
-// ✅ We verified the *intent* of the code without touching a real DB.
+// The full flow is verified. The database was never touched.
 ```
 
 ## Passing Runtime Context
 
-Some values come from the framework layer such as the authenticated tenant, a request trace ID, environment config rather than from the data being processed. `Ask` lets a pipeline step read the `context` object passed to `runEffect` without touching the function signatures around it.
+Some values come from the framework layer such as an authenticated tenant, a request trace ID, an environment config rather than from the data being processed. `Ask` lets a pipeline step read the `context` object passed to `runEffect` without threading it through every function signature.
 
-In the example below, `ctx.tenant` is identified from the subdomain or JWT by the router. The domain layer never needs it as a parameter; it just asks for it when needed:
+In the example below, `ctx.tenant` is resolved from the JWT by the router. The domain layer never receives it as a parameter; it just asks for it when needed:
 
 ```js
 import { Success, Failure, Command, Ask, effectPipe, runEffect } from 'pure-effect';
 
 const findProduct = (productId) =>
-    Ask((ctx) =>
-        Command(
-            () => db[ctx.tenant].findProduct(productId),
-            (product) => (product ? Success(product) : Failure('Product not found.'))
-        )
-    );
+    Ask((ctx) => {
+        const cmdFindProduct = () => db[ctx.tenant].findProduct(productId);
+        return Command(cmdFindProduct, (product) => (product ? Success(product) : Failure('Product not found.')));
+    });
 
 const reserveStock = (product) =>
-    Ask((ctx) =>
-        Command(
-            () => db[ctx.tenant].reserveStock(product.id),
-            (reserved) => Success({ product, reserved })
-        )
-    );
-
-const checkoutFlow = (productId) =>
-    effectPipe(
-        () => findProduct(productId),
-        ({ product }) => reserveStock(product)
-    )(productId);
-```
+    Ask((ctx) => {
+        const cmdReserveStock = () => db[ctx.tenant].reserveStock(product.id);
+        return Command(cmdReserveStock, (reserved) => Success({ product, reserved }));
+    });
 
-The router identifies the tenant and passes it as context. `checkoutFlow` never needs a tenant parameter:
+const checkoutFlow = (productId) => effectPipe(findProduct, ({ product }) => reserveStock(product))(productId);
 
-```js
 app.post('/checkout', async (req, res) => {
     const result = await runEffect(checkoutFlow(req.body.productId), {
-        tenant: req.subdomains[0] // e.g. 'acme' from acme.myapp.com
+        tenant: req.tenant
     });
     res.json(result);
 });
 ```
 
+## Retrying Transient Failures
+
+`Retry` wraps any Effect tree with retry-on-failure semantics. Like everything else in Pure Effect, the retry configuration is a plain object you can inspect and assert on without running anything.
+
+```js
+import { Success, Failure, Command, Retry, effectPipe, runEffect } from 'pure-effect';
+
+const fetchWeather = (city) => {
+    const cmdFetchWeather = () =>
+        fetch(`https://example-weather-api.com/v1/current?city=${city}`).then((r) => r.json());
+    return Retry(
+        Command(cmdFetchWeather, (data) => (data.error ? Failure(data.error) : Success(data))),
+        { attempts: 3, delay: 200, backoff: 2 } // 200ms, 400ms, 800ms
+    );
+};
+
+// Assert on the retry config without making any network calls
+const weatherFn = fetchWeather('Tokyo');
+assert.equal(weatherFn.type, 'Retry');
+assert.equal(weatherFn.options.attempts, 3);
+assert.equal(weatherFn.effect.type, 'Command');
+```
+
+When all attempts are exhausted, `runEffect` returns a structured `Failure`:
+
+```js
+{
+    retryExhausted: true,
+    lastError: <the last error>,
+    attempts: 3
+}
+```
+
+Global defaults can be set via `configureEffect` and overridden per-use:
+
+```js
+configureEffect({
+    retry: { attempts: 3, delay: 100, backoff: 1 } // flat delay by default
+});
+
+// Per-use options are merged on top of global defaults
+Retry(effect, { delay: 500 }); // uses global attempts, custom delay
+```
+
+## Running Effects in Parallel
+
+`Parallel` runs multiple Effect trees concurrently and passes their results to `next` as an ordered array. If any effect fails, `next` is not called and the `Failure` propagates immediately.
+
+```js
+import { Success, Failure, Command, Parallel, effectPipe, runEffect } from 'pure-effect';
+
+const getUser = (id) => {
+    const cmdGetUser = () => db.users.findById(id);
+    return Command(cmdGetUser, (user) => (user ? Success(user) : Failure('user_not_found')));
+};
+
+const getPermissions = (id) => {
+    const cmdGetPermissions = () => db.permissions.findByUserId(id);
+    return Command(cmdGetPermissions, (perms) => Success(perms));
+};
+
+const loadProfile = (userId) =>
+    Parallel([getUser(userId), getPermissions(userId)], ([user, permissions]) => Success({ user, permissions }));
+```
+
+Because `Parallel` is a plain object, you can assert on its structure without running anything:
+
+```js
+const flow = loadProfile('user-123');
+assert.equal(flow.type, 'Parallel');
+assert.equal(flow.effects.length, 2);
+assert.equal(flow.effects[0].type, 'Command');
+assert.equal(flow.effects[0].cmd.name, 'cmdGetUser');
+```
+
+`Parallel` composes naturally inside `effectPipe`:
+
+```js
+const checkoutFlow = (input) =>
+    effectPipe(
+        validate,
+        ({ productId, userId }) =>
+            Parallel([getProduct(productId), getUser(userId)], ([product, user]) => Success({ product, user })),
+        ({ product, user }) => reserveStock(product, user)
+    )(input);
+```
+
+`Ask` context flows into all parallel branches without any extra wiring.
+
+## TypeScript: Typed Errors and Context
+
+### Error union across pipeline steps
+
+Each step in `effectPipe` carries its own error type. The compiler collects them into a union automatically, so the return type of `runEffect` tells you exactly which errors are possible with full exhaustive narrowing, no extra boilerplate.
+
+```ts
+import { effectPipe, runEffect, Failure, Success, Command } from 'pure-effect';
+import type { Effect } from 'pure-effect';
+
+type ValidationError = 'invalid_email' | 'weak_password';
+type ApiError = 'network_timeout' | 'rate_limited';
+
+const validate = (input: { email: string }): Effect<{ email: string }, ValidationError> => {
+    if (!input.email.includes('@')) return Failure('invalid_email');
+    return Success(input);
+};
+
+const submit = (input: { email: string }): Effect<{ id: number }, ApiError> => {
+    const cmdSubmitUser = () =>
+        fetch('/api/users', { method: 'POST', body: JSON.stringify(input) }).then((r) => r.json());
+    return Command(cmdSubmitUser, (data) => Success(data));
+};
+
+const flow = effectPipe(validate, submit);
+const result = await runEffect(flow({ email: 'user@example.com' }));
+// result: SuccessState<{ id: number }> | FailureState<ValidationError | ApiError>
+
+if (result.type === 'Failure') {
+    result.error; // 'invalid_email' | 'weak_password' | 'network_timeout' | 'rate_limited'
+}
+```
+
+### Typed context with `Ask`
+
+`Effect<T, E, Ctx>` carries a third type parameter for the context object. TypeScript enforces that `runEffect` receives a matching value when you annotate `Ask` with a context type:
+
+```ts
+import { Ask, Command, Success, Failure, effectPipe, runEffect } from 'pure-effect';
+import type { Effect } from 'pure-effect';
+
+type AppContext = { tenant: string; requestId: string };
+
+const findProduct = (productId: string): Effect<Product, 'not_found', AppContext> =>
+    Ask<Product, 'not_found', AppContext>((ctx) => {
+        const cmdFindProduct = () => db[ctx.tenant].findProduct(productId);
+        return Command(cmdFindProduct, (product) => (product ? Success(product) : Failure('not_found')));
+    });
+
+// ctx is typed as AppContext, no cast needed
+const result = await runEffect(findProduct('abc'), { tenant: 'acme', requestId: '123' });
+```
+
+## Why Pure Effect
+
+**vs. Effect-TS:** Effect-TS is a full functional programming ecosystem with fibers, streaming, schema validation, structured concurrency, and more, though it comes with a steep learning curve. Pure Effect covers a narrower scope: testable pipelines, context injection, retry, and parallel execution. If your problem is testability and async pipeline boilerplate, Pure Effect solves it with just six primitives you can learn in an afternoon. If you need fibers, in-flight cancellation, or streaming, Effect-TS is the right tool.
+
+**vs. fp-ts:** fp-ts brings category theory abstractions (functors, monads, applicatives) to TypeScript. Pure Effect borrows only the concept of effects as data, without that vocabulary.
+
+**vs. plain async/await with mocks:** A mock that passes all your tests but diverges from what the real database driver or HTTP client actually does is worse than no test at all; it gives false confidence. Pure Effect eliminates the problem at the source: business logic never executes I/O, so there is nothing to mock. You assert on what the code _intends_ to do, not on a substitute that approximates it.
+
+**When to use something else:** If your codebase has little async I/O or test isolation isn't a pain point, plain async/await is the simpler choice.
+
 ## API Reference
 
 ### `Success(value)`
 
-Returns an object `{ type: 'Success', value }`. Represents a successful computation.
+Returns `{ type: 'Success', value }`. Represents a successful computation result.
 
-### `Failure(error)`
+### `Failure(error, initialInput?)`
 
-Returns an object `{ type: 'Failure', error, initialInput }`. Represents a failed computation. Stops the pipeline immediately.
+Returns `{ type: 'Failure', error, initialInput }`. Stops the pipeline immediately and short-circuits any remaining steps.
 
-### `Command(cmdFn, nextFn, meta)`
+### `Command(cmdFn, nextFn, meta?)`
 
-Returns an object `{ type: 'Command', cmd, next, meta }`.
+Returns `{ type: 'Command', cmd, next, meta }`.
 
 - `cmdFn`: A function (sync or async) that performs the side effect.
-- `nextFn`: A function that receives the result of `cmdFn` and returns the next Effect (Success, Failure, or another Command).
-- `meta`: Optional metadata.
+- `nextFn`: Receives the result of `cmdFn` and returns the next Effect.
+- `meta`: Optional metadata (available to `onBeforeCommand`).
 
 ### `Ask(nextFn)`
 
-Returns an object `{ type: 'Ask', next }`. Reads the `context` passed to `runEffect` and passes it to `nextFn`, which returns the next Effect. Works at any point in the pipeline, before or after `Command`s.
+Returns `{ type: 'Ask', next }`. Passes the `context` from `runEffect` into `nextFn`, which returns the next Effect. Works at any point in a pipeline.
 
 ```js
 const findProduct = (productId) =>
-    Ask((ctx) =>
-        Command(
-            () => db[ctx.tenant].findProduct(productId),
-            (product) => (product ? Success(product) : Failure('Product not found.'))
-        )
-    );
+    Ask((ctx) => {
+        const cmdFindProduct = () => db[ctx.tenant].findProduct(productId);
+        return Command(cmdFindProduct, (product) => (product ? Success(product) : Failure('Product not found.')));
+    });
 ```
 
-See [Passing Runtime Context](#passing-runtime-context) for a full example.
+### `Retry(effect, options?)`
 
-### `effectPipe(...functions)`
+Returns `{ type: 'Retry', effect, options, next }`. Wraps any Effect with retry-on-failure semantics.
 
-A combinator that runs functions in sequence. It automatically handles unpacking `Success` values and passing them to the next function. If a `Failure` occurs, the pipe stops.
+- `effect`: Any Effect: a `Command`, an `effectPipe` result, or another `Retry`.
+- `options.attempts`: Max retries, not counting the first try (default: `3`).
+- `options.delay`: Ms before the first retry (default: `100`).
+- `options.backoff`: Multiplier applied to delay on each attempt (default: `1`, flat).
 
-### `runEffect(effect, context = {})`
+On exhaustion, returns `Failure({ retryExhausted: true, lastError, attempts })`.
 
-The interpreter. It takes an `effect` object, executes any nested Commands using `async/await`, and returns the final `Success` or `Failure`. The optional `context` object is available to:
+### `Parallel(effects, next)`
 
-- `Ask` continuations — use `Ask` to read context inside pipeline steps
-- The `onBeforeCommand` interceptor (see `configureEffect` below)
+Returns `{ type: 'Parallel', effects, next }`. Runs all effects concurrently via `Promise.all`. If any effect fails, the first `Failure` is returned immediately and `next` is not called. `Ask` context flows into all branches.
 
-`context.flowName` may be used for naming workflows in telemetry.
+- `effects`: Array of any Effects such as `Command`s, `effectPipe` results, nested `Retry`s, etc.
+- `next`: Receives the array of unwrapped success values in the same order as `effects`, returns the next Effect.
 
----
+### `effectPipe(...functions)`
 
-### `configureEffect(options)`
+Composes functions into a sequential pipeline. Each function receives the unwrapped `Success` value from the previous step. A `Failure` from any step stops the pipeline immediately.
 
-A configuration function that injects observability, tracing, or logging interceptors into the `runEffect` interpreter. By default, **Pure Effect** executes with zero overhead. By providing `onRun` and `onStep` callbacks, you can wrap pipeline executions and individual commands (e.g., inside OpenTelemetry spans). Please see **opentelemetry-example.js** for a quick example.
+When a step needs to use a captured variable instead of the piped value, wrap it in an arrow function:
 
-`configureEffect` also accepts `onBeforeCommand`, which can be used to intercept each `Command` and the context passed to `runEffect` before execution.
+```js
+const flow = (input) =>
+    effectPipe(
+        validate, // receives input
+        () => findUser(input.email), // ignores piped value, uses captured input
+        ensureAvailable,
+        () => saveUser(input) // ignores piped value, uses captured input
+    )(input);
+```
+
+### `runEffect(effect, context?, callConfig?)`
+
+The interpreter. Traverses the effect tree, executes Commands with `async/await`, resolves `Ask` with the supplied `context`, and returns the final `Success` or `Failure`.
 
-- `onRun (effect, pipeline, flowName)`  
-  Fires once per `runEffect` call. It wraps the entire workflow execution.
-    - `effect`: The initial state of the effect tree (useful for extracting `initialInput`).
-    - `pipeline`: The actual interpreter. You must `await pipeline()` inside this callback to run the logic.
-    - `flowName`: The optional name of the workflow passed to `runEffect`.
+- `context`: Optional object passed to `Ask` continuations and `onBeforeCommand`. `context.flowName` names the workflow in telemetry.
+- `callConfig`: Per-call overrides for `onStep`, `onRun`, `onBeforeCommand`, and `retry`. Takes precedence over `configureEffect` globals.
+- `onRun` fires exactly once per `runEffect` call. Retry attempts run inside that single span. The interpreter does not re-enter `runEffect` per attempt.
+
+### `configureEffect(options)`
 
-- `onStep (name, type, op)`  
-  Fires every time a `Command` is executed.
-    - `name`: The name of the command function (e.g., `cmdFindUser`).
-    - `type`: Effect type.
-    - `op`: The actual side-effect function. You must `await op()` inside this callback and return its result.
+- `onRun(effect, pipeline, flowName)` wraps the entire workflow; must `await pipeline()`.
+- `onStep(name, type, op)` wraps each Command; must `await op()` and return its result.
+- `onBeforeCommand(command, context)` fires before each Command; throw to abort the pipeline.
+- `retry: { attempts?, delay?, backoff? }` global retry defaults.
 
-- `onBeforeCommand (command, context)`
-  Fires before a `Command` is executed. Ideal for inspecting metadata and context. If you throw, the pipeline stops immediately.
-    - `command`: The `Command` object.
-    - `context`: The context object passed to `runEffect`, if any.
+See **opentelemetry-example.js** in the repository for a complete OpenTelemetry wiring example.