resultar 3.9.1 → 4.0.0

package/README.md

@@ -1,903 +1,827 @@
 # Resultar
 
-Typed, composable error handling for TypeScript.
+**Typed, composable error handling and resilient workflows for TypeScript — from a single `Result<T, E>` to lazy, dependency-injected `ResultTask<T, E, R>`.**
 
-Resultar makes expected failures visible in function signatures instead of hiding them behind
-`throw`, rejected promises, nullable values, or undocumented conventions.
+[![Node.js 24+](https://img.shields.io/badge/node-%3E%3D24-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org)
+[![ESM Only](https://img.shields.io/badge/module-ESM-f7df1e?logo=javascript&logoColor=black)](https://github.com/inaiat/resultar/blob/main/packages/resultar/package.json)
+[![TypeScript 7 Native Checks](https://img.shields.io/badge/resultar--check-TypeScript--Go-3178c6?logo=typescript&logoColor=white)](https://github.com/inaiat/resultar/blob/main/packages/check/README.md)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/inaiat/resultar/blob/main/LICENSE)
 
-```ts
-Result<T, E>
-ResultAsync<T, E>
-ResultTask<T, E, R>
-```
-
-- `T` is the success value.
-- `E` is the expected failure.
-- `R` is the typed service environment still required by a `ResultTask`.
-- Callers must handle the result before they can use the value.
-
-Resultar stays focused on explicit values. It does not require a framework, dependency injection
-container, scheduler, or application runtime.
+[What's New in v4](#whats-new-in-v4) · [v4 Migration](https://github.com/inaiat/resultar/blob/main/docs/migrations/v4.md) · [Gradual Adoption](https://github.com/inaiat/resultar/blob/main/docs/gradual-adoption.md) · [Full Reference (`DOCUMENTATION.md`)](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md) · [`resultar-check` Compiler CLI/LSP](https://github.com/inaiat/resultar/blob/main/packages/check/README.md) · [Benchmarks](https://github.com/inaiat/resultar/blob/main/benchmarks/README.md) · [API Decision Guide](#api-decision-guide)
 
-## Highlights
+In standard TypeScript, `throw` and rejected promises are invisible in function signatures. Callers have no way of knowing what can fail—or whether they handled every failure case—without reading the implementation.
 
-| You need | Resultar gives you |
-| --- | --- |
-| Expected failures in the type system | `Result<T, E>` and `ResultAsync<T, E>` |
-| Reusable lazy workflows | `ResultTask<T, E, R>` with explicit execution boundaries and typed services |
-| Production errors with useful metadata | Real `Error` subclasses from `createTaggedError` |
-| Composable sync and async workflows | `map`, `mapErr`, `andThen`, `asyncAndThen`, and `orElse` |
-| Linear code without scattered `try/catch` | `safeTry` with `yield*` short-circuiting |
-| Explicit production async policy | Typed timeout, retry, race, concurrency, and cleanup helpers |
-| Exhaustive application boundaries | `matchTags` for tagged error unions |
-| Guardrails for ignored results | The optional native `resultar-check` CLI |
+Resultar moves expected failures into the type system and gives you a complete toolkit to compose, recover, retry, time out, and exhaustively match them from synchronous domain logic to production async workflows.
 
-Resultar began as a fork of `neverthrow`. The current API keeps the familiar explicit Result model
-and adds Resultar-specific tagged errors, production async helpers, exhaustive tagged boundaries,
-and optional TypeScript-backed diagnostics.
+---
 
-## Contents
-
-- [Install](#install)
-- [Why Resultar](#why-resultar)
-- [Quick Start](#quick-start)
-- [Compose Results](#compose-results)
-- [Tagged Errors](#tagged-errors)
-- [Async Work](#async-work)
-- [Lazy Workflows With ResultTask](#lazy-workflows-with-resulttask)
-- [Production Async Policies](#production-async-policies)
-- [Linear Workflows With Result.gen](#linear-workflows-with-resultgen)
-- [Recover Inside A Workflow](#recover-inside-a-workflow)
-- [Handle Results At Boundaries](#handle-results-at-boundaries)
-- [Strict Results At Production Boundaries](#strict-results-at-production-boundaries)
-- [Prevent Ignored Results](#prevent-ignored-results)
-- [HTTP Request Packages](#http-request-packages)
-- [API Decision Guide](#api-decision-guide)
-- [More Documentation](#more-documentation)
-- [Limitations](#limitations)
+## Why Resultar in 30 Seconds
 
-## Install
+### Before: Hidden failures
 
-```sh
-pnpm add resultar
-```
-
-```sh
-npm install resultar
-```
-
-Requirements:
-
-- Node.js 24+
-- ESM only
-- TypeScript 7+ for the canonical `resultar-check` diagnostics workflow
-
-```ts
-import { createTaggedError, ok } from 'resultar'
-import type { Result } from 'resultar'
-```
-
-CommonJS `require('resultar')` is not exported.
-
-## Why Resultar
-
-This signature does not tell callers that parsing can fail:
+This signature promises a `number`, but silently throws at runtime:
 
 ```ts
 const parsePort = (input: string): number => {
-  const port = Number(input)
-
+  const port = Number(input);
   if (!Number.isInteger(port) || port <= 0) {
-    throw new Error(`Invalid port ${input}`)
+    throw new Error(`Invalid port ${input}`); // invisible to TypeScript!
   }
-
-  return port
-}
+  return port;
+};
 ```
 
-Resultar moves the expected failure into the contract:
+### After: Explicit, typed contracts
+
+With Resultar, expected failures are first-class values in the return type:
 
 ```ts
-import { createTaggedError, ok } from 'resultar'
-import type { Result } from 'resultar'
+import { createTaggedError, ok, type Result } from "resultar";
 
 class InvalidPortError extends createTaggedError({
-  name: 'InvalidPortError',
-  message: 'Invalid port $input',
+  name: "InvalidPortError",
+  message: "Invalid port $input",
 }) {}
 
 const parsePort = (input: string): Result<number, InvalidPortError> => {
-  const port = Number(input)
-
-  return Number.isInteger(port) && port > 0 ? ok(port) : InvalidPortError.err({ input })
-}
-```
-
-The caller can now see both outcomes without reading the implementation:
-
-```ts
-const port = parsePort(process.env.PORT ?? '3000')
-
-const message = port.match(
-  (value) => `Listening on ${value}`,
-  (error) => error.message,
-)
+  const port = Number(input);
+  return Number.isInteger(port) && port > 0 ? ok(port) : InvalidPortError.err({ input });
+};
 ```
 
-Use `Err` for failures the caller can reasonably handle: invalid input, conflicts, missing records,
-rate limits, timeouts, and unavailable dependencies. Keep programming bugs and impossible states as
-normal JavaScript throws.
+### End-to-End: Compose linearly, handle exhaustively
 
-## Quick Start
-
-The examples below build one account-creation workflow.
-
-Start with real tagged errors. Variables in the message template become required constructor props:
+Write linear workflows without nested `try/catch` blocks. TypeScript automatically infers the combined error union across every `yield*` step and enforces exhaustive handling at your application boundary:
 
 ```ts
-import { createTaggedError, ok } from 'resultar'
-import type { Result } from 'resultar'
+import { createTaggedError, ok, ResultTask, type Result } from "resultar";
 
+// 1. Define real Error subclasses with typed template props ($email, $operation)
 class InvalidEmailError extends createTaggedError({
-  name: 'InvalidEmailError',
-  message: 'Invalid email $email',
+  name: "InvalidEmailError",
+  message: "Invalid email $email",
 }) {}
 
-class AccountAlreadyExistsError extends createTaggedError({
-  name: 'AccountAlreadyExistsError',
-  message: 'Account $email already exists',
+class AccountExistsError extends createTaggedError({
+  name: "AccountExistsError",
+  message: "Account $email already exists",
 }) {}
 
-type Account = {
-  readonly email: string
-  readonly id: string
-}
-```
-
-Return `Ok` for success and `Err` for an expected failure:
+class DatabaseError extends createTaggedError({
+  name: "DatabaseError",
+  message: "Database $operation failed",
+}) {}
 
-```ts
-const normalizeEmail = (input: string): Result<string, InvalidEmailError> => {
-  const email = input.trim().toLowerCase()
+// 2. Write domain & infrastructure steps with explicit error channels
+const normalizeEmail = (raw: string): Result<string, InvalidEmailError> => {
+  const email = raw.trim().toLowerCase();
+  return email.includes("@") ? ok(email) : InvalidEmailError.err({ email });
+};
+
+const registerAccount = (input: string) =>
+  ResultTask.gen(function* () {
+    const email = yield* normalizeEmail(input);
+
+    if (email === "taken@example.com") {
+      return yield* AccountExistsError.err({ email });
+    }
+
+    return yield* ResultTask.tryPromise({
+      try: () => db.accounts.insert({ email }),
+      catch: (cause) => new DatabaseError({ cause, operation: "insert-account" }),
+    });
+  });
+// Inferred return type:
+// ResultTask<Account, InvalidEmailError | AccountExistsError | DatabaseError>
+
+// 3. Handle every possible error at the HTTP boundary (compile error if a tag is missed!)
+const result = await registerAccount(req.body.email).runResult();
+const response = result.matchTags((account) => ({ status: 201, body: account }), {
+  InvalidEmailError: (err) => ({ status: 400, body: { code: err._tag, message: err.message } }),
+  AccountExistsError: (err) => ({ status: 409, body: { code: err._tag, message: err.message } }),
+  DatabaseError: (err) => ({ status: 503, body: { code: err._tag, message: err.message } }),
+});
+```
+
+---
+
+## Highlights & Positioning
+
+| What you need                            | What Resultar provides                                                                                                                                                      |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Expected failures in the type system** | `Result<T, E>` for sync values, `ResultTask<T, E, R>` for lazy async workflows, and `ResultAsync<T, E>` as the in-flight `Result` returned by `task.runResult()`            |
+| **Structured production errors**         | Real `Error` subclasses via `createTaggedError` with `$prop` interpolation, `cause`, fingerprints, and secret redaction                                                     |
+| **Linear code without `try/catch`**      | `Result.gen` / `Result.fn` and `ResultTask.gen` / `ResultTask.fn` using `yield*` short-circuiting                                                                           |
+| **Exhaustive boundary handling**         | `matchTags`, `catchTag`, `catchTags`, and general-purpose `Match` pattern matching                                                                                          |
+| **Production async resilience**          | Built-in `timeout`, `retry` (with portable `Retry.policy`), `race`, bounded `forEach`, and resource cleanup                                                                 |
+| **Lazy tasks & typed dependencies**      | `ResultTask<T, E, R>` with typed service requirements (`R`), `AbortSignal` cancellation, and LIFO resource scopes                                                           |
+| **Compiler guardrails**                  | Optional native [`resultar-check`](https://github.com/inaiat/resultar/blob/main/packages/check/README.md) CLI & LSP to forbid ignored results (`noDiscard`) and raw `throw` |
+
+### Where Resultar Sits Between `neverthrow` and `Effect`
+
+Resultar began as a fork of `neverthrow`. It keeps the approachable `Ok` / `Err` mental model while adding structured concurrency, scoped resources, typed DI, and native compiler diagnostics—without forcing a global runtime on your codebase:
+
+| Capability                                        | `neverthrow`                | `Resultar`                                                                 | `Effect`                                             |
+| ------------------------------------------------- | --------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------- |
+| **Adoption unit**                                 | 1 function (`Result<T, E>`) | **1 function (`Result<T, E>`)**                                            | Full `Effect<A, E, R>` ecosystem                     |
+| **Direct `await` on async results**               | Yes (`ResultAsync<T, E>`)   | **Task uses explicit `task.runResult()`, returning awaitable `ResultAsync`** | No (requires `Effect.runPromise` / runtime)          |
+| **Tagged `Error` classes & secret redaction**     | Manual                      | **Built-in (`createTaggedError`, `redact`)**                               | Built-in (`Data.TaggedError`, `Redacted`)            |
+| **Retries, timeouts, races & virtual clock**      | Manual                      | **Built-in (`Retry.policy`, `timeout`, `Clock.virtual`)**                  | Built-in (`Schedule`, `TestClock`)                   |
+| **Typed DI (`R`), LIFO resource scopes & fibers** | No                          | **Opt-in via `ResultTask<T, E, R>` & `resultar-di`**                       | Always present (`Effect<A, E, R>`, `Layer`, `Scope`) |
+| **Compiler enforcement (`noDiscard`)**            | ESLint plugin               | **Native TypeScript-Go CLI & LSP (`resultar-check`)**                      | Language service plugin                              |
+
+---
 
-  return email.includes('@') ? ok(email) : InvalidEmailError.err({ email })
-}
-
-const ensureAccountIsAvailable = (
-  email: string,
-): Result<string, AccountAlreadyExistsError> =>
-  email === 'taken@example.com' ? AccountAlreadyExistsError.err({ email }) : ok(email)
+## Install
 
-const buildAccount = (email: string): Result<Account, never> =>
-  ok({ email, id: 'acct_123' })
+```sh
+pnpm add resultar
+# or
+npm install resultar
 ```
 
-Compose the steps with `andThen`. The resulting error type is inferred as a union:
+- **Runtime**: Node.js 24+, ESM-only (`import { ok, Result } from 'resultar'`)
+- **JSR**: Also available as [`@inaiat/resultar`](https://jsr.io/@inaiat/resultar)
+- **Diagnostics (optional)**: `pnpm add -D resultar-check` (requires TypeScript 7+)
 
-```ts
-type CreateAccountError = InvalidEmailError | AccountAlreadyExistsError
+---
 
-const createAccount = (input: string): Result<Account, CreateAccountError> =>
-  normalizeEmail(input).andThen(ensureAccountIsAvailable).andThen(buildAccount)
-```
+## What's New in v4
 
-Inspect a result directly when local branching is clearer:
+- **`ResultTask<T, E, R>` is the default for new async workflows**: Lazy, repeatable execution blueprints with typed service requirements (`R`), LIFO resource cleanup (`acquireRelease`, `acquireDisposable`, `scoped`), structured child fibers (`forkChild`, `Fiber`), bounded collection concurrency (`all`, `forEach`, `validateAll`, `makeSemaphore`), portable retry policies (`Retry.policy`), and deterministic virtual time (`Clock.virtual()`).
+- **Unified execution boundary (`task.runResult()` returns `ResultAsync<T, E>`)**: Execute tasks explicitly via instance or static runners (`runResult`, `runPromise`, `runExit`, `runFork`). `task.runResult()` starts the task and returns an in-flight `ResultAsync<T, E>` (`PromiseLike<Result<T, E>>`) that can be awaited directly or transformed and folded with `Result` methods (`map`, `andThen`, `catchTag`, `matchTags`, `unwrapOr`, etc.).
+- **Plain-return generators (`Result.gen` / `Result.fn` & `ResultTask.gen` / `ResultTask.fn`)**: Generator workflows unwrap steps with `yield*` and return plain success values (`return value`), while legacy `safeTry` remains supported for final-`Result` generator bodies.
+- **Canonical error boundaries & sound tagged recovery**: `Result.try`, `ResultAsync.try`, `ResultTask.try`, and `ResultTask.tryPromise` accept both `(fn, catchFn)` and `{ try, catch }`. Tagged recovery (`catchTag`, `catchTags`, `matchTagsPartial`) removes an error from `E` only when its handler is required and defined across all table variants.
+- **Context-aware pattern matching & framework scopes**: `Match.context<Input, [ctx]>()` builds reusable route/event matchers without repeating the matched input, and [`resultar-di`](https://www.npmjs.com/package/resultar-di), [`resultar-hono`](https://www.npmjs.com/package/resultar-hono), and [`resultar-fastify`](https://www.npmjs.com/package/resultar-fastify) wire application and request scopes automatically.
+- **Gradual migration & eager `ResultAsync` compatibility**: In-flight constructors (`okAsync`, `errAsync`, `unitAsync`, `fromPromise`, `fromSafePromise`, `tryResultAsync`) remain active in `resultar`, while legacy eager `ResultAsync` orchestration helpers remain supported as `@deprecated` compatibility APIs.
 
-```ts
-const account = createAccount('person@example.com')
+> Upgrading from v3? Read the full **[v4 Migration & Compatibility Guide (`docs/migrations/v4.md`)](https://github.com/inaiat/resultar/blob/main/docs/migrations/v4.md)** for the complete before/after API table, retained aliases, and `PromiseLike` boundary notes.
 
-if (account.isOk()) {
-  account.value.email
-}
+---
 
-if (account.isErr()) {
-  account.error.message
-}
-```
+## Adopt Gradually: Three Primitives, One Mental Model
 
-Or consume both outcomes with `match`:
+You do not need to rewrite your application to use Resultar. Start with a single function returning `Result<T, E>` and scale up only when a workflow needs async I/O or typed dependencies:
 
-```ts
-const label = createAccount('person@example.com').match(
-  (created) => `Created ${created.id}`,
-  (error) => `Could not create account: ${error.message}`,
-)
+```mermaid
+flowchart LR
+  R["<b>1. Result&lt;T, E&gt;</b><br/>Synchronous value (Ok / Err)<br/>Zero async overhead"]
+  RT["<b>2. ResultTask&lt;T, E, R&gt;</b><br/>Default for new async workflows<br/>Lazy, repeatable, explicit runners"]
+  RA["<b>ResultAsync&lt;T, E&gt;</b><br/>In-flight Result (PromiseLike)<br/>Await or chain like Result"]
+
+  R -->|"async I/O, retry, timeout"| RT
+  RT -->|"task.runResult()"| RA
+  RA -->|"fromResultAsync(existing or factory)"| RT
 ```
 
-## Compose Results
+- **`T`** is the success value.
+- **`E`** is the expected failure type.
+- **`R`** is the typed service environment or resource scope required before a `ResultTask` can run (`never` when no external requirements remain).
 
-Resultar composition keeps success and failure channels separate.
+Prefer `ResultTask` for new asynchronous workflows and run it explicitly, including when
+`R = never`. Providing services or closing a scope leaves a Task. Calling `task.runResult()`
+(or `ResultTask.runResult(task)`) starts the task and returns `ResultAsync<T, E>` — an in-flight
+`Result` (`PromiseLike<Result<T, E>>`) that can be awaited directly or transformed and folded
+with the same methods as `Result`. In-flight constructors (`okAsync`, `errAsync`, `unitAsync`, `fromPromise`, `fromSafePromise`, `tryResultAsync`) are active in `resultar`, while static orchestration methods on
+`ResultAsync` remain deprecated in `resultar` for existing eager contracts.
+Its inbound `fromResultAsync` bridge accepts structural `PromiseLike<Result<T, E>>` values.
 
-### Transform success with `map`
+| Stage                        | When to use it                                                                                 | Key APIs                                                                                  |
+| ---------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| **1. `Result<T, E>`**        | Synchronous validation, parsing, and domain rules                                              | `ok`, `err`, `map`, `andThen`, `Result.gen`, `match`                                      |
+| **2. `ResultTask<T, E, R>`** | New asynchronous workflows; add typed services, cooperative cancellation, and scopes as needed | `ResultTask.gen`, `ResultTask.fn`, `tryPromise`, `service`, `acquireRelease`, `runResult` |
+| **`ResultAsync<T, E>`**      | In-flight `Result` returned by `task.runResult()` (and existing eager async contracts)         | `await`, `map`, `andThen`, `catchTag`, `match`, `matchTags`, `unwrapOr`, `unwrapOrThrow`  |
 
-```ts
-const accountId = createAccount('person@example.com').map((account) => account.id)
-```
+### Sync-First, Pay-As-You-Go Execution Engine
 
-### Add a fallible condition with `filterOrElse`
+Result values remain synchronous, and the Task runtime uses synchronous fast paths until an
+asynchronous step is needed. The separate Async facade retains its memoized Promise contract:
 
-```ts
-class UnsupportedEmailDomainError extends createTaggedError({
-  name: 'UnsupportedEmailDomainError',
-  message: 'Email domain $domain is not supported',
-}) {}
+- **Explicit `yield*` interop**: Core `Result.gen` / `Result.fn` support sync and eager async generators. `ResultTask.gen` composes Results, Tasks and service tags; adapt Async with `fromResultAsync`. Satisfying `R` keeps the Task contract.
+- **Zero-microtask synchronous fast path**: `Result.gen`, synchronous `ResultTask` pipelines, and `ResultTask.scoped` workflows without async steps execute inside a tight synchronous `while` loop (`runTaskLoop` / `#runGen`) without scheduling microtasks—reusing static singletons (`sharedSuccessExit`, `idleTaskIterator`, `idleRunContext`) on the happy path until a real `Promise` or cooperative `yieldEvery` checkpoint is encountered.
+- **Pay only for the stage you use**: Service maps, LIFO finalizer stacks, and fiber schedulers are allocated lazily only when a workflow invokes `service()`, `acquireRelease()`, or `forkChild()`.
 
-const requireCompanyEmail = (
-  email: string,
-): Result<string, InvalidEmailError | UnsupportedEmailDomainError> =>
-  normalizeEmail(email).filterOrElse(
-    (normalized) => normalized.endsWith('@company.com'),
-    (normalized) =>
-      new UnsupportedEmailDomainError({ domain: normalized.split('@')[1] ?? 'unknown' }),
-  )
-```
+See the [Gradual Adoption Guide](https://github.com/inaiat/resultar/blob/main/docs/gradual-adoption.md) for a step-by-step walkthrough and the [Benchmarks Guide](https://github.com/inaiat/resultar/blob/main/benchmarks/README.md) for the architectural and runtime profile.
 
-### Continue with fallible work using `andThen`
+---
 
-```ts
-const createCompanyAccount = (input: string) =>
-  requireCompanyEmail(input).andThen(ensureAccountIsAvailable).andThen(buildAccount)
-```
+## Contents
 
-### Transform a failure with `mapErr`
+- [What's New in v4](#whats-new-in-v4)
+- [Tagged Errors (`createTaggedError`)](#tagged-errors)
+- [Synchronous Workflows (`Result`)](#synchronous-workflows)
+- [Linear Workflows (Result and Task generators)](#linear-workflows-with-resultgen)
+- [Recovering & Handling Boundaries](#recover-and-handle-results-at-boundaries)
+- [Lazy Workflows (`ResultTask`)](#lazy-workflows-with-resulttask)
+  - [Parameterized tasks and tagged recovery](#parameterized-tasks-and-tagged-recovery)
+  - [Resource scopes and application lifecycle](#resource-scopes-and-application-lifecycle)
+  - [Task concurrency and resilience](#task-concurrency-and-resilience)
+  - [Portable retry policies](#portable-retry-policies)
+  - [Inspect failure causes](#inspect-failure-causes)
+- [In-Flight `ResultAsync` & Deprecated Eager Compatibility](#in-flight-resultasync--deprecated-eager-compatibility)
+- [Pattern Matching (`Match`)](#pattern-matching-with-match)
+- [Prevent Ignored Results (`resultar-check`)](#prevent-ignored-results)
+- [Ecosystem Packages (HTTP, Validation, DI)](#ecosystem-packages)
+- [API Decision Guide](#api-decision-guide)
+- [More Documentation & Limitations](#more-documentation)
 
-```ts
-class AccountServiceError extends createTaggedError({
-  name: 'AccountServiceError',
-  message: 'Account service failed for $email',
-}) {}
+---
 
-const account = createAccount(input).mapErr(
-  (cause) => new AccountServiceError({ cause, email: input }),
-)
-```
+## Tagged Errors
 
-### Recover with `orElse`
+`createTaggedError` builds real `Error` subclasses with a stable `_tag` discriminant, automatic `$variable` message interpolation, and structured serialization:
 
 ```ts
-const account = findAccountByEmail(email).orElse(() => createAccount(email))
-```
-
-Use `pipe` when a result transform should be named and reused:
+import { createTaggedError } from "resultar";
 
-```ts
-import type { Result } from 'resultar'
+class AccountAlreadyExistsError extends createTaggedError({
+  name: "AccountAlreadyExistsError",
+  message: "Account $email already exists",
+}) {}
 
-const auditAccount = <E>(result: Result<Account, E>): Result<Account, E> =>
-  result.tap((account) => logger.info({ accountId: account.id }, 'account ready'))
+const error = new AccountAlreadyExistsError({ email: "ada@example.com" });
 
-const accountEmail = createAccount(input)
-  .pipe(auditAccount)
-  .map((account) => account.email)
+error instanceof Error; // true
+error instanceof AccountAlreadyExistsError; // true
+error._tag; // 'AccountAlreadyExistsError'
+error.message; // 'Account ada@example.com already exists'
+error.email; // 'ada@example.com'
+error.fingerprint; // 'AccountAlreadyExistsError:Account $email already exists'
+error.toJSON(); // cycle-safe serializable object
 ```
 
-Callbacks passed to transform methods are normal application code. Resultar does not silently catch
-exceptions thrown by `map`, `andThen`, or `pipe` callbacks. Wrap uncontrolled code at the edge
-instead.
-
-## Tagged Errors
-
-`createTaggedError` produces real `Error` subclasses with stable tags and structured metadata:
+Every tagged error class includes static helpers to construct failures directly without `new`:
 
 ```ts
-const error = new AccountAlreadyExistsError({ email: 'person@example.com' })
-
-error instanceof Error // true
-error instanceof AccountAlreadyExistsError // true
-error._tag // 'AccountAlreadyExistsError'
-error.message // 'Account person@example.com already exists'
-error.email // string | number
-error.fingerprint // stable error fingerprint
-error.toJSON() // serializable metadata
+AccountAlreadyExistsError.err({ email }); // Err<never, AccountAlreadyExistsError>
+AccountAlreadyExistsError.taskErr({ email }); // ResultTask<never, AccountAlreadyExistsError>
+AccountAlreadyExistsError.errAsync({ email }); // deprecated eager ResultAsync<never, AccountAlreadyExistsError>
+AccountAlreadyExistsError.is(unknownValue); // nominal type guard
 ```
 
-Tagged errors support:
-
-- `_tag` for exhaustive handling;
-- typed message-template props;
-- `cause` and stack traces;
-- `fingerprint` and `messageTemplate`;
-- cycle-safe `.toJSON()` output;
-- `.findCause(ErrorClass)` for nested causes;
-- static `.is(value)` for nominal checks;
-- static `.err(props)` for returning an `Err` directly.
+### Refining metadata types with `.withProps()`
 
-Preserve the original failure as `cause` when translating infrastructure errors:
+Template variables default to `string | number | Redacted<unknown>`. Chain `.withProps<...>()` to refine template property types or require additional structured metadata:
 
 ```ts
-class DatabaseError extends createTaggedError({
-  name: 'DatabaseError',
-  message: 'Database $operation failed',
-}) {}
+class UserNotFoundError extends createTaggedError({
+  name: "UserNotFoundError",
+  message: "User $id was not found",
+}).withProps<{ id: string; details?: { source: string } }>() {}
 
-const databaseError = new DatabaseError({
-  cause: new Error('connection refused'),
-  operation: 'insert-account',
-})
-
-databaseError.findCause(Error)
+const missing = new UserNotFoundError({ id: "user_1", details: { source: "replica" } });
 ```
 
-Use `redact` when metadata must remain available to authorized code without leaking through error
-messages or JSON:
+### Preserving causes and redacting secrets
+
+Pass `cause` to preserve the underlying exception chain and inspect it with `.findCause(ErrorClass)`. Wrap sensitive fields in `redact(value, label)` so secrets never leak into `.message` or `.toJSON()` logs:
 
 ```ts
-import { createTaggedError, isRedacted, redact, revealRedacted } from 'resultar'
+import { createTaggedError, isRedacted, redact, revealRedacted } from "resultar";
 
 class TokenRejectedError extends createTaggedError({
-  name: 'TokenRejectedError',
-  message: 'Token $token was rejected',
+  name: "TokenRejectedError",
+  message: "Token $token was rejected",
 }) {}
 
 const error = new TokenRejectedError({
-  token: redact('secret-token', 'api-token'),
-})
+  token: redact("sk_live_secret", "api-token"),
+  cause: new Error("signature mismatch"),
+});
 
-error.message // 'Token <redacted:api-token> was rejected'
+error.message; // 'Token <redacted:api-token> was rejected'
 
 if (isRedacted(error.token)) {
-  revealRedacted(error.token) // 'secret-token'
+  revealRedacted(error.token); // 'sk_live_secret' (explicit access for authorized code)
 }
 ```
 
-Use `taggedEnum` for lightweight tagged states or nested reasons that do not need to be real
-`Error` instances. See the
-[tagged enum guide](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#tagged-enums)
-for the complete API.
+> Need lightweight tagged variants or nested error reasons without full `Error` stack traces? Use `taggedEnum` — see the [Tagged Enums guide](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#tagged-enums).
 
-## Async Work
+---
 
-`ResultAsync<T, E>` is the async counterpart to `Result<T, E>`. It is awaitable and exposes the same
-composition style.
+## Synchronous Workflows
 
-Map rejections from external code into a documented error type:
+### Creating Results
+
+In addition to `ok(value)` and `err(error)`, Resultar provides helpers to lift nullable values, predicates, and throwing functions into `Result`:
 
 ```ts
-import { tryResultAsync } from 'resultar'
-import type { ResultAsync } from 'resultar'
+import { ok, pipe, Result, tryResult } from "resultar";
 
-class DatabaseError extends createTaggedError({
-  name: 'DatabaseError',
-  message: 'Database $operation failed',
-}) {}
+// Reject null or undefined (preserves 0, false, and "")
+const envName = Result.fromNullishOr(process.env.USER_NAME, () => "missing-name" as const);
 
-const persistAccount = (email: string): ResultAsync<Account, DatabaseError> =>
-  tryResultAsync(
-    () => accountRepository.insert({ email }),
-    (cause) => new DatabaseError({ cause, operation: 'insert-account' }),
-  )
+// Narrow or validate with a predicate (direct or curried in pipe)
+const positivePort = pipe(
+  3000,
+  Result.liftPredicate(
+    (n: number) => n > 0,
+    (n) => `invalid port: ${n}` as const,
+  ),
+);
+
+// Wrap synchronous code that might throw
+const parsedJson = tryResult(
+  () => JSON.parse(rawInput) as Record<string, unknown>,
+  (cause) => new InvalidJsonError({ cause }),
+);
 ```
 
-Continue from synchronous validation into async work with `asyncAndThen`:
+### Chaining and transforming
+
+Success (`Ok`) and failure (`Err`) travel on separate channels:
 
 ```ts
-type CreateAccountAsyncError =
-  | InvalidEmailError
-  | AccountAlreadyExistsError
-  | DatabaseError
-
-const createAccountAsync = (
-  input: string,
-): ResultAsync<Account, CreateAccountAsyncError> =>
-  normalizeEmail(input).andThen(ensureAccountIsAvailable).asyncAndThen(persistAccount)
+const accountEmail = normalizeEmail(input)
+  .filterOrElse(
+    (email) => email.endsWith("@company.com"),
+    (email) => new UnsupportedDomainError({ domain: email.split("@")[1] ?? "unknown" }),
+  )
+  .andThen(ensureAccountIsAvailable) // runs only on Ok; merges error unions
+  .map((email) => ({ id: "acct_1", email })) // transforms Ok value
+  .inspect((acct) => logger.info(acct.id)) // best-effort side effect on Ok
+  .mapErr((cause) => new AccountError({ cause })); // transforms Err value
 ```
 
-Once a workflow is already asynchronous, `andThen` accepts callbacks that return either `Result` or
-`ResultAsync`:
+### Functional pipelines (`pipe`, `flow`, `identity`, `constant`)
+
+Result and Task transformations support fluent methods and curried functions inside `pipe`
+and `flow`. `ResultAsync` also retains its existing functional forms:
 
 ```ts
-const provisioned = createAccountAsync(input)
-  .andThen(assignDefaultPlan)
-  .andThen(sendWelcomeEmail)
-  .map((account) => ({ account, status: 'ready' as const }))
-```
+import { constant, flow, identity, pipe, Result } from "resultar";
 
-Choose the wrapper that matches the external boundary:
+const sanitize = flow(
+  (input: string) => input.trim(),
+  (input) => input.toLowerCase(),
+);
 
-| External work | Use |
-| --- | --- |
-| Run throwing synchronous code now | `tryResult(fn, toError)` |
-| Wrap a throwing synchronous function | `fromThrowable(fn, toError)` |
-| Adapt an existing promise | `fromPromise(promise, toError)` |
-| Run a promise or async factory | `tryResultAsync(factory, toError)` |
-| Wrap an async function | `fromThrowableAsync(fn, toError)` |
-| Adapt a callback or subscription | `ResultAsync.fromCallback(options)` |
+const label = pipe(
+  "  ADA@COMPANY.COM  ",
+  sanitize,
+  normalizeEmail,
+  Result.map((email) => `User: ${email}`),
+  Result.match({ ok: identity, err: constant("Invalid user") }),
+);
+```
 
-Prefer a factory with `tryResultAsync` when creating the promise can also throw synchronously.
+---
 
-## Lazy Workflows With ResultTask
+<a id="linear-workflows-with-resultgen"></a>
 
-`ResultTask<T, E, R>` is the lazy workflow primitive in Resultar. Creating one does not start the
-work; `runResult`, `runExit`, or `runPromise` executes it explicitly. `R` records required service
-tags and resource scope requirements. Run boundaries supply the root scope automatically and
-require an explicit environment for any remaining service tags.
-
-Unlike `ResultAsync`, a `ResultTask` is a reusable description of work rather than an already-started
-operation. Mapping, chaining, recovery, service provision, and generator composition all remain lazy.
-
-| Need | API |
-| --- | --- |
-| Create an immediate success or failure | `succeed`, `fail`, `fromResult` |
-| Defer synchronous work | `sync`, `try` |
-| Defer promise-producing work | `tryPromise` |
-| Transform, observe, or chain | `map`, `mapError`, `flatMap`, `andThen`, `tap`, `tapError`, `as`, `match` |
-| Recover typed failures | `catchAll` |
-| Write a linear lazy workflow | `gen` with `yield*` |
-| Declare and provide dependencies | `service`, `provideService`, `provideServices`, `provideServiceResolver` |
-| Own resources and await cleanup | `acquireRelease`, `scoped` |
-| Execute at the application boundary | `runExit`, `runResult`, `runPromise` |
-| Bridge to started promises | `fromResultAsync`, `toResultAsync`, `ResultAsync.fromTask` |
+## Linear Workflows With Result And Task Generators
+
+Use `Result.gen` / `Result.fn` for synchronous domain steps, and `ResultTask.gen` /
+`ResultTask.fn` for new asynchronous workflows. Both use plain success returns;
+`yield*` unwraps successes and short-circuits expected failures.
 
 ```ts
-import { ResultTask } from 'resultar'
+import { Result, ResultTask } from "resultar";
 
-const loadUser = (id: string) =>
-  ResultTask.tryPromise({
-    try: (signal) => fetch(`/users/${id}`, { signal }).then((response) => response.json()),
-    catch: (cause) => new Error(`Could not load user: ${String(cause)}`),
-  })
+const validateAccount = Result.fn(function* (input: string) {
+  const email = yield* normalizeEmail(input);
+  yield* ensureAccountIsAvailable(email);
+  return email;
+});
+
+// persistAccount and findAccountByEmail return ResultTask<Account, ...>.
+const createAccount = ResultTask.fn(function* (input: string) {
+  const email = yield* validateAccount(input);
+  return yield* persistAccount(email);
+});
+
+const getOrCreateAccount = ResultTask.fn(
+  function* (input: string) {
+    return yield* createAccount(input);
+  },
+  ResultTask.catchTag("AccountExistsError", (error) => findAccountByEmail(String(error.email))),
+);
 
-const task = loadUser('user_123')
-const result = await ResultTask.runResult(task)
+const result = await getOrCreateAccount(input).runResult();
 ```
 
-`sync` treats a thrown value as an unexpected defect. Use `try` or `tryPromise` when the boundary is
-expected to throw or reject and should map that cause into `E`. `tryPromise` receives the execution
-`AbortSignal`, so callers can cancel cooperative work without starting it early.
+- Return `value` for success; use `return yield* step()` or `return yield* MyError.err(...)` for a final fallible step.
+- Task generators are synchronous `function*` bodies describing asynchronous steps. Compose those steps with `yield*`; execute the completed Task with an explicit runner.
+- Core `Result.gen` / `Result.fn` and legacy `safeTry` support sync and eager async bodies; see [compatibility](#in-flight-resultasync--deprecated-eager-compatibility).
+- Deprecated `safeTry` remains a separate helper returning the final Result. It is not an identity alias of modern `Result.gen`.
+- Its implementation belongs to the Async compatibility layer; root imports re-export the same deprecated helper. Use `ResultTask.gen` for Task workflows; Task has no `safeTry` alias.
 
-Choose the execution boundary based on how much information the application needs:
+---
 
-| Boundary | Result |
-| --- | --- |
-| `runExit(task)` | Preserves `Success`, typed `Fail`, `Die`, `Interrupt`, and `Sequential` causes |
-| `runResult(task)` | Returns a single typed failure as `Err`; rejects defects, interruption, and composite causes |
-| `runPromise(task)` | Returns `T`; rejects every failure for integration with Promise-only APIs |
+## Recover And Handle Results At Boundaries
 
-The error type of `runExit` and `runResult` includes deferred release failures from the root scope.
-Interruption rejects with `AbortError`. A composite cause rejects with `ResultTaskCauseError`, whose
-`cause` preserves the complete tree; use `runExit` to inspect it without rejection.
+### Local recovery inside a workflow
+
+Use `catchTag` or `catchTags` to recover from specific tagged errors while leaving remaining error types untouched in the union:
 
 ```ts
-const controller = new AbortController()
-const exit = await ResultTask.runExit(loadUser('user_123'), {
-  signal: controller.signal,
-})
+// Recover a single tag; InvalidEmailError and DatabaseError stay in the error type
+const account = createAccount(input).catchTag("AccountExistsError", (error) =>
+  findAccountByEmail(String(error.email)),
+);
 
-if (exit._tag === 'Failure' && exit.cause._tag === 'Die') {
-  console.error('Unexpected defect', exit.cause.defect)
-}
+// Or recover multiple tags at once
+const accountOrDraft = createAccount(input).catchTags({
+  AccountExistsError: (error) => findAccountByEmail(String(error.email)),
+  InvalidEmailError: (error) => ok({ id: "draft", email: String(error.email) }),
+});
 ```
 
-Instance methods and their static functional forms preserve laziness and infer combined error and
-environment types:
+Use `orElse` when recovering from the entire error channel, or `orElseSucceed` / `unwrapOr` to fall back to a plain default value.
 
-```ts
-const userName = loadUser('user_123')
-  .map((user) => String(user.name))
-  .andThen((name) => ResultTask.succeed(name.trim()))
-  .catchAll((error) => ResultTask.succeed(`unavailable: ${error.message}`))
-```
+### Exhaustive handling at application boundaries
 
-`catchAll` recovers a single typed failure. Defects and interruption bypass recovery. Composite
-causes bypass recovery as `Die(ResultTaskCauseError)` with the original tree on the error's `cause`;
-this prevents removed error types from escaping as typed failures. The equivalent functional forms
-are `ResultTask.map`, `ResultTask.flatMap`, and `ResultTask.catchAll`.
+At the edge of your application (HTTP controllers, CLI commands, queue consumers), turn the `Result` into a final response:
 
-For promise adapters that do not need an error mapper, pass the lazy callback directly:
+- **`matchTags(onOk, handlers)`**: Requires a handler for every `_tag` in `E`. If a deeper layer adds a new error type, TypeScript flags the boundary at compile time.
+- **`matchTagsPartial(onOk, handlers, onUnhandled)`**: Handle specific tags and route the rest to a fallback.
+- **`match(onOk, onErr)` / `match({ ok, err })`**: Handle `Ok` and `Err` directly when individual tags don't matter.
 
-```ts
-const response = ResultTask.tryPromise((signal) => fetch(url, { signal }))
-// ResultTask<Response, unknown>: synchronous throws and rejections remain typed failures.
-```
+> On `Result`, `match`, `matchTags`, `matchTagsPartial`, and `unwrapOr` return `Out` directly. On `ResultAsync` instances (such as `task.runResult()`), they return native `Promise<Out>` terminals; their static/direct/curried forms return composable `ResultAsync<Out, never>` values. On Task, they return lazy `ResultTask<Out, never, R>` operators; use `folded.runPromise()` for `Out`, or fold directly on `task.runResult()`.
 
-The callback runs only when the task executes. Use `tryPromise({ try, catch })` when you need a
-specific error type; both forms receive the runtime signal and preserve interruption semantics.
+### Strict Error-only boundaries (`StrictResult` & `StrictResultAsync`)
 
-Workflows can request typed services with `yield*` and receive them at the boundary. Pass the service
-type first, then let the second call infer its literal identifier:
+While `Result<T, E>` allows any error type, `StrictResult<T, E extends Error>` and
+`StrictResultAsync<T, E extends Error>` constrain synchronous and in-flight boundaries to real
+`Error` subclasses. New async workflow definitions return `ResultTask<User, UserError>` with a
+concrete Error union, and `task.runResult()` returns `StrictResultAsync<User, UserError>`.
 
-```ts
-const Database = ResultTask.service<
-  { findUser: (id: string) => Promise<string> }
->()('Database')
-
-const taskWithDatabase = ResultTask.gen(function* () {
-  const database = yield* Database
-  return yield* ResultTask.tryPromise({
-    try: () => database.findUser('user_123'),
-    catch: () => 'database-error' as const,
-  })
-})
-
-const resultWithDatabase = await ResultTask.runResult(taskWithDatabase, {
-  services: { Database: { findUser: async () => 'Ada' } },
-})
-```
+---
+
+## Lazy Workflows With ResultTask
 
-The environment requirement is part of the task type. A missing or misspelled `Database` property is
-a compile-time error at `runResult`, `runExit`, or `runPromise`. Dependencies can also be bound before
-the final boundary:
+`ResultTask<T, E, R>` is the preferred primitive for new async workflows. It is an
+immutable, reusable blueprint that executes only at an explicit `run*` boundary.
+Prefer `ok` / `err`, `mapErr`, `andThen`, and `orElse` in new code. Deprecated `succeed` / `fail`,
+`mapError`, `flatMap`, and `catchAll` retain their original contracts, as do older retry options
+and match handler objects; prefer `Retry.policy(...)` and `{ ok, err }` for new recipes.
+Task has no `.then` method; `await task` leaves it unexecuted, including when `R = never`.
+Prefer the instance runners in new recipes: `task.runResult()`, `task.runPromise()`,
+`task.runExit()`, and `task.runFork()`. The static runners remain supported with the same behavior.
+
+Use `ok`, `err`, `mapErr`, `andThen` and `orElse` as the Task API names. Object handlers
+use `{ ok, err }`, and retries take a policy created with `Retry.policy(...)`.
 
 ```ts
-const database = { findUser: async () => 'Ada' }
+import { ResultTask } from "resultar";
+
+const fetchUser = (id: string) =>
+  ResultTask.tryPromise({
+    try: (signal) => fetch(`/api/users/${id}`, { signal }).then((res) => res.json()),
+    catch: (cause) => new UserLoadError({ cause, id }),
+  });
 
-const readyWithOne = ResultTask.provideService(taskWithDatabase, Database, database)
-const readyWithAll = ResultTask.provideServices(taskWithDatabase, { Database: database })
+const task = fetchUser("user_123"); // Nothing has executed yet!
 
-await ResultTask.runResult(readyWithOne)
-await ResultTask.runResult(readyWithAll)
+// Execute explicitly at your application boundary (returns ResultAsync<User, UserLoadError>):
+const result = await task.runResult();
 ```
 
-The direct form `ResultTask.service<DatabaseContract, 'Database'>('Database')` remains supported.
-The curried form can also be yielded inline: `yield* ResultTask.service<DatabaseContract>()('Database')`.
-Requirements belong to `R` in `ResultTask<T, E, R>`; `Result` has no service lookup API.
-
-Every tag creation has its own symbol identity. Inline tags resolve through named environments
-(`provideServices` or the DI module). `provideService(token, value)` supplies both an exact token binding and a named fallback.
-Reuse the same token to select its exact binding when identifiers collide; a separately created
-same-name tag can resolve the named fallback. Exact token bindings take precedence. For class services and explicit dependency maps, see
-[`Service.require` and `requires` in resultar-di](../di/README.md#class-services-and-explicit-requirements).
-
-Infrastructure such as a dependency-injection adapter can resolve service tags lazily with
-`provideServiceResolver(task, { Logger: () => loggerTask })`. Each required identifier has a
-typed lazy provider. Provider errors and external requirements remain in the resulting task type;
-resource-scope requirements also remain visible. All three providers (`provideService`,
-`provideServices`, `provideServiceResolver`) support data-first and curried (`.pipe`) forms.
-A provider whose value is incompatible with the required service contract is rejected at compile
-time, including through a reused curried provider; partial providers keep the remaining
-requirements until they are satisfied at the boundary.
-
-Adapters can use `ResultTask.makeScope()` to own resources across executions. Run tasks with
-`owner.use(task)` and execute `owner.close()` after consumers finish. Failed uses roll back their
-partial acquisitions. `ResultTask.memoize(task)` shares pending and successful executions and
-allows retry after failure; its first execution supplies the environment and resource scope.
-
-`ResultTask.gen` composes tasks and services linearly. On short-circuit, generator `finally` blocks
-are closed and any yielded cleanup tasks or services are interpreted before execution completes:
+| Instance boundary           | Equivalent static boundary              | Return type             | Behavior                                                                                                                 |
+| --------------------------- | --------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `task.runResult(options?)`  | `ResultTask.runResult(task, options?)`  | `ResultAsync<T, E>`     | Returns an in-flight `ResultAsync` resolving typed failures as `Err`; rejects defects, interruption, and composite causes |
+| `task.runPromise(options?)` | `ResultTask.runPromise(task, options?)` | `Promise<T>`            | Resolves the success value; rejects every failure                                                                        |
+| `task.runExit(options?)`    | `ResultTask.runExit(task, options?)`    | `Promise<Exit<T, E>>`   | Never rejects; preserves every success or failure cause as a value                                                       |
+| `task.runFork(options?)`    | `ResultTask.runFork(task, options?)`    | `FiberHandle<T, E>`     | Starts a root fiber immediately, with interruption, observation, and cleanup ownership                                   |
+
+Both forms accept the same `ResultTaskRunOptions<R>`: `services`, `signal`, `clock`, `scheduler`,
+and `yieldEvery`. Missing or incompatible services remain compile-time errors. If `R` includes
+pending scope release errors, `runResult`, `runExit`, and `runFork` include them in their error
+types (`E | ScopeError<R>` internally). Every call starts a separate execution; results are not
+memoized. Because `runResult` returns `ResultAsync<T, E>`, you can either `await task.runResult()`
+to inspect the resolved `Result<T, E>` or chain `.map()`, `.andThen()`, `.catchTag()`, `.match()`,
+`.unwrapOr()`, and `.unwrapOrThrow()` directly on `task.runResult()`. There is no public `task.run()` runner.
 
 ```ts
-const program = ResultTask.gen(function* () {
-  try {
-    return yield* loadUser('user_123')
-  } finally {
-    yield* ResultTask.sync(() => logger.info('load-user finished'))
-  }
-})
+const task = ResultTask.sync(() => "ready");
+const first = await task.runResult();
+const second = await ResultTask.runResult(task); // Same contract, another execution
 ```
 
-Generator `finally` retains its existing replacement policy if its cleanup fails. Use resource
-scopes below when both the body and cleanup failure must be preserved.
+### Parameterized tasks and tagged recovery
+
+Declare typed service requirements with `ResultTask.service<Contract>()('Tag')` and compose lazy workflows with `ResultTask.gen` or `ResultTask.fn`. If a required service is missing at an explicit runner, TypeScript reports a compile-time error. `map` is synchronous; compose asynchronous steps with `andThen` and `tryPromise`:
+
+```ts
+import { createTaggedError, ok, ResultTask } from "resultar";
+
+class UserNotFoundError extends createTaggedError({
+  name: "UserNotFoundError",
+  message: "User $id was not found",
+}) {}
 
-Generators also accept `yield* result` for plain `Result` values: `Ok` unwraps its value and
-`Err` short-circuits into `E`.
+const UsersRepo = ResultTask.service<{
+  findById(id: string): ResultTask<{ id: string; name: string }, UserNotFoundError>;
+}>()("UsersRepo");
+
+// ResultTask.fn wraps a generator and applies post-body operators lazily per call
+const loadUserDisplayName = ResultTask.fn(
+  function* (id: string) {
+    const repo = yield* UsersRepo;
+    const user = yield* repo.findById(id);
+    return user.name;
+  },
+  ResultTask.catchTag("UserNotFoundError", (err) => ok(`Guest (${err.id})`)),
+);
+// Type: (id: string) => ResultTask<string, never, Service<'UsersRepo', ...>>
+
+// Provide services at the boundary (or ahead of time via ResultTask.provideServices)
+const nameResult = await loadUserDisplayName("u_42").runResult({
+  services: {
+    UsersRepo: {
+      findById: (id) => UserNotFoundError.taskErr({ id }),
+    },
+  },
+});
+```
 
 ### Resource scopes and application lifecycle
 
+Use `ResultTask.acquireRelease` (or `ResultTask.acquireDisposable` for native `Disposable` / `AsyncDisposable` objects) to tie resource cleanup to a scope. Finalizers always run in reverse acquisition order (LIFO)—even when the workflow fails, throws a defect, or is interrupted:
+
 ```ts
-const connection = ResultTask.acquireRelease({
+const dbResource = ResultTask.acquireRelease({
   acquire: ResultTask.tryPromise({
     try: (signal) => connectDatabase(signal),
     catch: (cause) => new ConnectionError({ cause }),
   }),
-  release: (database, exit) => ResultTask.tryPromise({
-    try: () => database.close(exit),
-    catch: (cause) => new CloseError({ cause }),
+  release: (db, exit) =>
+    ResultTask.tryPromise({
+      try: () => db.close(exit),
+      catch: (cause) => new CloseError({ cause }),
+    }),
+});
+
+const queryProgram = ResultTask.scoped(
+  ResultTask.gen(function* () {
+    const db = yield* dbResource;
+    return yield* ResultTask.tryPromise({
+      try: (signal) => db.query("SELECT 1", signal),
+      catch: (cause) => new QueryError({ cause }),
+    });
   }),
-})
+);
+```
 
-const program = ResultTask.scoped(ResultTask.gen(function* () {
-  const database = yield* connection
-  return yield* ResultTask.tryPromise({
-    try: (signal) => database.query('SELECT 1', signal),
-    catch: (cause) => new QueryError({ cause }),
-  })
-}))
+`acquireRelease` tracks any release error in `R` (`ResultTaskScope<CloseError>`) so inner `orElse` calls cannot accidentally swallow a pending finalizer failure before `ResultTask.scoped` (or a `run*` boundary) closes the scope.
 
-const exit = await ResultTask.runExit(program)
-```
+### Task concurrency and resilience
 
-Every run owns a root scope. `scoped` closes a child scope before the next task continues. Successful
-acquisitions register finalizers in LIFO order; every finalizer is awaited once, even after a body
-failure, defect, or interruption. Failed acquisition does not register its release. Earlier resources
-are still released if a later acquisition fails. Each finalizer receives the same region exit,
-before release failures are appended. Services provided around acquisition remain available during
-release, including services used only by the release callback.
-
-`acquireRelease` tracks deferred errors with `ResultTaskScope<ReleaseError>` in `R`. `scoped` removes
-that requirement and adds its errors to `E`; run boundaries do the same for the root scope. Service
-provision and `catchAll` before scope closure cannot erase pending release failures. To recover a
-single release failure, put `catchAll` after `scoped`.
-
-If use succeeds but release fails, the failure is returned as `Err`. If both fail, `runExit` retains
-them as `Sequential(useCause, releaseCause)`; subsequent release failures are appended in order.
-Release callbacks that throw produce defects. Resources acquired during a finalizer belong to a
-private cleanup scope, which is closed before the next finalizer starts.
-
-Cancellation is cooperative: tasks check the signal before starting, and promise operations receive
-it. Rejection after abort is classified as interruption. The runtime waits for in-flight operations
-to settle so a resource acquired during cancellation can still be registered and released. Cleanup
-uses a fresh, non-aborted signal. An operation or finalizer that never settles can therefore keep
-the run pending; there is no preemptive cancellation, scheduler, or `Fiber` runtime in this slice.
-
-For application composition, keep ordinary factories and existing `StrictResultAsync` use cases.
-Use service tags only when a program needs requirements supplied at execution. Put the **whole server
-lifetime** inside the resource scope: acquire database, session, then HTTP; wait for shutdown; drain
-HTTP, close session, then close database. Returning a server from a completed scope would return
-already-released resources. TypeScript does not enforce resource reference lifetimes.
-
-See the runnable [application lifecycle example](../../examples/resultar/src/application-lifecycle.ts)
-and its [smoke test](../../examples/resultar/scripts/lifecycle-smoke.ts). Run `pnpm run example:resultar`
-from the workspace root. Its factory and resource contracts return `ResultTask` with database,
-session, and HTTP error types. Drivers expose Promises only inside `ResultTask.tryPromise` adapters,
-which receive the runtime signal without threading it through every application interface.
-Concrete adapters must clean up partial acquisitions before returning a
-failure and implement request draining, SSE termination, and suitable deadlines.
-
-`ResultAsync.withResource` keeps its existing best-effort release behavior. Existing `ResultAsync`
-instances have already started; wrapping one does not make it lazy or automatically cancelable.
-Use `ResultTask.fromResultAsync` to run a `ResultAsync` inside a task boundary: pass a
-`(signal) => ResultAsync` factory to defer creation until execution, or an existing instance to
-capture an already-started execution. Use `ResultTask.toResultAsync(task)` — or the
-`ResultAsync.fromTask(task)` alias — to start a requirement-free task immediately on the default
-runtime and consume it as `ResultAsync`.
-
-## Production Async Policies
-
-Resultar models common resilience policy in the expected error channel. These helpers use lazy tasks
-so retries can start fresh work and racing helpers can pass a cooperative abort signal.
-
-### Timeout stays typed
+`ResultTask` pipelines share the active `AbortSignal`, `Clock`, and resource scope across retries, timeouts, races, bounded collections, and child fibers:
 
 ```ts
-class AccountTimeoutError extends createTaggedError({
-  name: 'AccountTimeoutError',
-  message: 'Account $accountId timed out after $timeoutMs milliseconds',
-}) {}
+import { Clock, Fiber, ResultTask, Retry } from "resultar";
 
-const account = ResultAsync.timeout(
-  (signal) => loadAccount(accountId, { signal }),
-  {
-    timeoutMs: 1_500,
-    onTimeout: () => new AccountTimeoutError({ accountId, timeoutMs: 1_500 }),
-  },
-)
+const resilientTask = fetchUser("user_123")
+  .retry(Retry.policy({ times: 2, delayMs: 100, backoff: 2, jittered: 0.2 }))
+  .timeout(2_000, () => new UserTimeoutError());
+
+// Deterministic testing with a virtual clock (no real timers):
+const clock = Clock.virtual();
+const pending = resilientTask.runResult({ clock });
+await clock.advanceBy(2_000);
+const outcome = await pending;
 ```
 
-If the timer wins, the timeout is returned as `Err<AccountTimeoutError>` and the task receives an
-abort signal. No rejected timeout promise is introduced.
+- **Collections & concurrency limits**: `ResultTask.all`, `ResultTask.forEach`, and `ResultTask.validateAll` run sequentially by default or concurrently via `{ concurrency: 8 | 'unbounded' }`. Use `ResultTask.makeSemaphore(permits)` to limit concurrency across independent tasks.
+- **Structured child fibers**: `yield* ResultTask.forkChild(task)` starts background work attached to the current scope. Join or cancel it with `Fiber.join(fiber)`, `Fiber.await(fiber)`, or `Fiber.interrupt(fiber)`.
 
-### Retry transient failures
+### Portable retry policies
 
-```ts
-const account = ResultAsync.retry(
-  (attempt, signal) => loadAccount(accountId, { attempt, signal }),
-  {
-    times: 2,
-    delayMs: ({ nextAttempt }) => nextAttempt * 100,
-    jittered: 0.2,
-    while: (error) => error._tag === 'DatabaseBusyError',
-  },
-)
-```
-
-`times` is the number of retries after the first attempt. Use `retryOrElse` when retry exhaustion
-should continue into an explicit fallback:
+Use `Retry.policy` to share an immutable retry configuration between Task workflows.
+The same policy can also be passed to retained eager Async factories:
 
 ```ts
-const account = ResultAsync.retryOrElse(
-  (attempt, signal) => loadAccount(accountId, { attempt, signal }),
-  {
-    times: 2,
-    orElse: () => loadCachedAccount(accountId),
-  },
-)
-```
+import { ResultTask, Retry } from "resultar";
 
-### Race equivalent providers
+const transientPolicy = Retry.policy({
+  times: 3,
+  delayMs: 100,
+  backoff: 2,
+  jittered: 0.2,
+});
 
-```ts
-const account = ResultAsync.race(
-  (signal) => loadAccountFromPrimary(accountId, { signal }),
-  (signal) => loadAccountFromReplica(accountId, { signal }),
-)
+const taskWithRetry = fetchUser("user_123").retry(transientPolicy);
+const result = await taskWithRetry.runResult();
 ```
 
-`race` returns the first success and keeps waiting after an early failure. Use `raceFirst` when the
-first completed success or failure should win, or `raceAll` for several equivalent providers.
+### Inspect failure causes
 
-### Bound concurrent work
+When executing a task with `task.runExit()`, failures are represented as a `Cause<E>` tree (`Fail`, `Die`, `Interrupt`, `Sequential`, or `Parallel`). Use the `Cause` namespace to inspect or format them:
 
 ```ts
-const imported = ResultAsync.forEach(
-  accountInputs,
-  (input) => createAccountAsync(input.email),
-  { concurrency: 8, discard: true },
-)
-```
+import { Cause, ResultTask } from "resultar";
 
-`forEach` is sequential by default and stops scheduling new work after the first `Err`. Pass a
-positive concurrency number for bounded work or `"unbounded"` to start every mapped task.
+const exit = await queryProgram.runExit();
 
-Use mapped `validateAll` when every independent item should run and all failures should be returned:
-
-```ts
-const validated = ResultAsync.validateAll(
-  accountInputs,
-  (input) => normalizeEmail(input.email).asyncMap(async (email) => email),
-  { concurrency: 8 },
-)
+if (exit._tag === "Failure") {
+  Cause.failures(exit.cause); // E[] — all expected typed errors in order
+  Cause.defects(exit.cause); // unknown[] — all unexpected Die defects
+  Cause.pretty(exit.cause); // human-readable diagnostic trace with stacks & redaction
+}
 ```
 
-### Pair acquisition with cleanup
+> For advanced `ResultTask` details—including `interruption: 'detach'`, custom `Scheduler` instruction budgets, `provideServiceResolver`, and `catchCause` / `sandbox`—see the [Full Resultar Guide](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#lazy-tasks-and-service-requirements).
 
-```ts
-const account = ResultAsync.withResource({
-  acquire: (signal) => databasePool.connect({ signal }),
-  use: (connection, signal) => connection.insertAccount(input, { signal }),
-  release: (connection) => connection.close(),
-})
-```
+---
 
-After successful acquisition, `release` runs when `use` succeeds, returns `Err`, or rejects. For
-stream-shaped work, use native `AsyncIterable<Result<T, E>>`; Resultar intentionally does not add a
-stream runtime or scheduler.
+<a id="async-work-and-resilience"></a>
+<a id="deprecated-resultasync-compatibility"></a>
+<a id="in-flight-resultasync--deprecated-eager-compatibility"></a>
 
-See the full guides for
-[racing and timeout](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#concurrent-racing-and-timeouts),
-[retry](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#retrying-async-work),
-[concurrency](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#async-concurrency-mapping),
-and [resource cleanup](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#resourceful-async-iterables).
+## In-Flight `ResultAsync` & Deprecated Eager Compatibility
 
-## Linear Workflows With `Result.gen`
+`ResultAsync<T, E>` (and `StrictResultAsync<T, E>`) is the official in-flight `Result`
+(`PromiseLike<Result<T, E>>`), exported from `resultar`.
+When you execute a `ResultTask` with `task.runResult(options?)` (or `ResultTask.runResult(task, options?)`),
+it returns a `ResultAsync<T, E>` that can be awaited directly for `Result<T, E>` or transformed
+and consumed with the same methods as `Result` (`map`, `mapErr`, `andThen`, `orElse`,
+`orElseSucceed`, `catchTag`, `catchTags`, `catchReason`, `catchReasons`, `unwrapReason`,
+`filterOrElse`, `as`, `asVoid`, `if`, `when`, `whenResult`, `unless`, `unlessResult`, `inspect`,
+`inspectError`, `inspectBoth`, `log`, `match`, `matchTags`, `matchTagsPartial`, `unwrapOr`,
+`unwrapOrThrow`, `toAsyncDisposable`, `[Symbol.asyncIterator]`, `pipe`).
 
-Use `Result.gen` when a longer chain reads better as linear code. `yield*` extracts the `Ok` value and
-short-circuits on the first `Err`. `safeTry` remains an exact compatibility alias.
+```sh
+pnpm add resultar
+```
 
-```ts
-import { Result } from 'resultar'
-import type { ResultAsync } from 'resultar'
+In-flight value and Promise constructors (`ResultAsync.ok`, `ResultAsync.err`, `ResultAsync.unit`,
+`ResultAsync.fromPromise`, `ResultAsync.fromSafePromise`, `ResultAsync.try`, and top-level `okAsync`,
+`errAsync`, `unitAsync`, `fromPromise`, `fromSafePromise`, `tryResultAsync`) remain active for
+in-flight values, mocks, and Promise boundary adaptation. Legacy eager adapters (`fromCallback`,
+`fromThrowableAsync`, `tryAsync`, `tryCatchAsync`, `safeTry`, `runPromise`, `ResultAsync.tryCatch`,
+`ResultAsync.fromThrowable`, `ResultAsync.fromTask`, `ResultAsync.fromCallback`) and static
+orchestration helpers on `ResultAsync` (`retry`, `retryOrElse`, `race`, `raceAll`, `raceFirst`,
+`raceWith`, `timeout`, `withResource`, `forEach`, `validateAll`, `loop`, `iterate`, `firstSuccessOf`,
+`all`, `combine`, `combineWithAllErrors`, `zip`) remain available in `resultar` as deprecated
+compatibility APIs for existing eager contracts. Prefer `ResultTask` for new asynchronous workflows
+and orchestration.
 
-const createAccountLinear = (
-  input: string,
-): ResultAsync<Account, CreateAccountAsyncError> =>
-  Result.gen(async function* () {
-    const email = yield* normalizeEmail(input)
-    yield* ensureAccountIsAvailable(email)
+### Wrapping external async boundaries (eager compatibility)
 
-    return persistAccount(email)
-  })
-```
+| External boundary                                             | Helper                              |
+| ------------------------------------------------------------- | ----------------------------------- |
+| Wrap an async/promise factory (catches sync throws too)       | `tryResultAsync(factory, toError)`  |
+| Adapt an already-created Promise                              | `fromPromise(promise, toError)`     |
+| Wrap an async function into a reusable `ResultAsync` function | `fromThrowableAsync(fn, toError)`   |
+| Adapt a callback or event subscription                        | `ResultAsync.fromCallback(options)` |
 
-The object form can map unexpected throws from inside the generator while leaving yielded `Err`
-values unchanged:
+### Existing eager resilience policies
+
+Existing Async timeouts, retries, races, bounded collections and best-effort release keep
+their signatures and eager behavior. Preserve them during migration; new workflows use
+the Task policies above. Transformation callback defects can still reject the Async Promise:
 
 ```ts
-const account = Result.gen({
-  async *try() {
-    const email = yield* normalizeEmail(input)
-    return persistAccount(email)
-  },
-  catch: (cause) => new AccountServiceError({ cause, email: input }),
-})
-```
+import { ResultAsync } from "resultar";
 
-Prefer `yield* result`. Compatibility helpers such as `safeUnwrap` are not needed in new workflows.
+// 1. Timeout with cooperative AbortSignal
+const timedAccount = ResultAsync.timeout((signal) => loadAccount(accountId, { signal }), {
+  timeoutMs: 1_500,
+  onTimeout: () => new AccountTimeoutError({ accountId, timeoutMs: 1_500 }),
+});
 
-## Recover Inside A Workflow
+// 2. Retry transient failures with backoff, jitter, and fallback
+const retriedAccount = ResultAsync.retryOrElse(
+  (attempt, signal) => loadAccount(accountId, { attempt, signal }),
+  {
+    times: 2,
+    delayMs: ({ nextAttempt }) => nextAttempt * 100,
+    jittered: 0.2,
+    while: (error) => error._tag === "DatabaseBusyError",
+    orElse: () => loadCachedAccount(accountId),
+  },
+);
 
-Use recovery methods when a failure has a useful local alternative.
+// 3. Race redundant providers (returns first Ok, aborts losers)
+const fastestAccount = ResultAsync.race(
+  (signal) => loadFromPrimary(accountId, { signal }),
+  (signal) => loadFromReplica(accountId, { signal }),
+);
 
-Recover from one tagged error with `catchTag`:
+// 4. Bounded concurrency over collections
+const imported = ResultAsync.forEach(
+  users,
+  (user) => provisionAccount(user.email),
+  { concurrency: 8 }, // or validateAll(...) to collect all errors
+);
 
-```ts
-const account = createAccountAsync(input).catchTag(
-  'AccountAlreadyExistsError',
-  (error) => findAccountByEmail(String(error.email)),
-)
+// 5. Acquire-use-release bracket
+const inserted = ResultAsync.withResource({
+  acquire: (signal) => dbPool.connect({ signal }),
+  use: (conn, signal) => conn.insertAccount(input, { signal }),
+  release: (conn) => conn.close(),
+});
 ```
 
-Recover several tagged errors with `catchTags`:
+---
 
-```ts
-const account = createAccountAsync(input).catchTags({
-  AccountAlreadyExistsError: (error) => findAccountByEmail(String(error.email)),
-  InvalidEmailError: (error) =>
-    ok({ email: String(error.email), id: 'draft_account' }),
-})
-```
+### Async Result generators and bridges
 
-Unhandled tags remain in the error channel. Use `mapErr` when the failure should be translated and
-`orElse` when recovery should run another Result-producing branch.
+Core `Result.gen` / `Result.fn` support sync and async bodies. Async bodies
+start eagerly and return `ResultAsync`:
 
 ```ts
-const account = loadCachedAccount(accountId)
-  .orElse(() => loadAccount(accountId))
-  .mapErr((cause) => new AccountServiceError({ cause, email: input }))
+import { Result, ResultTask, tryResultAsync } from "resultar";
+
+const loadLegacyAccount = (id: string) =>
+  Result.gen(async function* () {
+    const account = yield* tryResultAsync(
+      () => accountClient.load(id),
+      (cause) => new AccountLoadError({ cause }),
+    );
+    return account;
+  });
+
+// The factory creates a fresh eager operation on each Task run.
+const task = ResultTask.fromResultAsync(() => loadLegacyAccount("acct_1"));
+const result = await task.runResult();
+
+// task.runResult() returns ResultAsync directly.
+const inFlight = task.runResult();
+const sameExecution = await inFlight;
 ```
 
-Use recovery inside a workflow. At an application boundary, consume the final result with `match`,
-`matchTags`, or `matchTagsPartial`.
+Passing an existing Async to `fromResultAsync(existing)` reuses its execution on every run.
+The factory form receives the active signal; pass it to cooperative clients when supported.
+Provide all services and close required scopes before calling `task.runResult()`.
+Static/instance `ResultTask.toResultAsync` and `ResultAsync.fromTask(task)` remain supported as
+deprecated aliases of `task.runResult()`, and tagged-error `.errAsync` helpers remain supported.
+Result `asyncMap` / `asyncAndThen` methods and statics remain supported.
 
-## Handle Results At Boundaries
+Async instance `match`, `matchTags`, `matchTagsPartial` and `unwrapOr` remain native Promise terminals.
+Their static/direct/curried forms return Async values for composition. At an instance boundary,
+`await inFlight.match({ ok: account => account.id, err: () => 'unavailable' })` produces the raw
+handler output. Async `tap` / `tapError` remain deprecated best-effort aliases of
+`inspect` / `inspectError`; Task's fallible `tap` operations have a separate contract.
 
-Boundary code turns a Result into an HTTP response, queue acknowledgement, CLI exit code, log entry,
-or UI state.
+---
 
-Use `matchTags` when tagged errors should be handled exhaustively:
+## Pattern Matching With Match
+
+`Match` brings exhaustive, type-narrowing pattern matching to ordinary TypeScript unions, domain events, and HTTP route error mappers. Tag and discriminator tables compile into $O(1)$ lookup tables:
 
 ```ts
-const response = await createAccountAsync(input).matchTags(
-  (account) => ({
-    body: account,
-    statusCode: 201,
-  }),
-  {
-    AccountAlreadyExistsError: (error) => ({
-      body: { code: error._tag, message: error.message },
-      statusCode: 409,
-    }),
-    DatabaseError: (error) => ({
-      body: { code: error._tag, message: error.message },
-      statusCode: 503,
-    }),
-    InvalidEmailError: (error) => ({
-      body: { code: error._tag, message: error.message },
-      statusCode: 400,
-    }),
-  },
-)
-```
+import { Match } from "resultar";
 
-If a handler is missing, TypeScript reports it. If only selected errors need special handling, use
-`matchTagsPartial` with a fallback. Use plain `match` when the distinction between individual error
-tags does not matter.
+type DomainEvent = { _tag: "UserCreated"; id: string } | { _tag: "UserDeleted"; count: number };
 
-Avoid unwrapping in normal application flows. `unwrapOr`, `unwrapOrThrow`, `_unsafeUnwrap`, and
-`_unsafeUnwrapErr` are best reserved for deliberate final boundaries or tests.
+// Build a reusable matcher function
+const describeEvent = Match.type<DomainEvent>()
+  .tag("UserCreated", (event) => `Created ${event.id}`)
+  .tag("UserDeleted", (event) => `Deleted ${event.count} records`)
+  .exhaustive();
 
-## Strict Results At Production Boundaries
+// Or match a value immediately by tag
+const summary = Match.valueTags(event, {
+  UserCreated: (e) => e.id,
+  UserDeleted: (e) => String(e.count),
+});
+```
 
-`Result<T, E>` intentionally allows any failure type. Strings, enums, and small objects can be useful
-inside narrow local workflows.
+### Reusable HTTP error handlers with `Match.context`
 
-For service, HTTP, job, queue, CLI, and integration boundaries, prefer the Error-only aliases:
+When multiple Hono or Fastify routes share the same error-to-HTTP mapping, extract a context-aware matcher:
 
 ```ts
-import type { StrictResult, StrictResultAsync } from 'resultar'
+import type { Context } from "hono";
+import { Match } from "resultar";
 
-const validateAccount = (
-  input: string,
-): StrictResult<string, InvalidEmailError> => normalizeEmail(input)
+const respondError = Match.context<
+  UserNotFoundError | DatabaseError,
+  [c: Context]
+>().tagsExhaustive({
+  UserNotFoundError: (err, c) => c.json({ error: err.message }, 404),
+  DatabaseError: (_err, c) => c.json({ error: "Service unavailable" }, 503),
+});
 
-const provisionAccount = (
-  input: string,
-): StrictResultAsync<Account, CreateAccountAsyncError> => createAccountAsync(input)
+// Inside a route handler:
+const result = await users.findById(id);
+return result.match({
+  ok: (user) => c.json(user, 200),
+  err: (error) => respondError(error, c),
+});
 ```
 
-`StrictResult<T, E extends Error>` and `StrictResultAsync<T, E extends Error>` are type-only aliases.
-They keep the same Resultar API while documenting that failures carry standard `Error` behavior:
-messages, causes, stack traces, and structured metadata.
+| Pattern need                                                                                                                       | `Match` API                                                               |
+| ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Match literals, shapes, predicates, or built-in guards (`Match.string`, `Match.number`, `Match.defined`, `Match.instanceOf`, etc.) | `when`, `whenOr`, `whenAnd`, `not`                                        |
+| Match `_tag` unions                                                                                                                | `tag`, `tags`, `tagsExhaustive`, `valueTags`, `typeTags`                  |
+| Match custom discriminant fields or prefixes                                                                                       | `discriminator`, `discriminatorsExhaustive`, `tagStartsWith`              |
+| Finalize matcher                                                                                                                   | `exhaustive`, `orElse`, `result` (`Result<Matched, Remaining>`), `option` |
+
+---
 
 ## Prevent Ignored Results
 
-Result values are useful only when callers handle them. Install the native `resultar-check` CLI:
+A `Result` only protects your application if callers actually handle it. Install [`resultar-check`](https://github.com/inaiat/resultar/blob/main/packages/check/README.md)—a native TypeScript-Go CLI and LSP server that runs compiler typechecks and Resultar-specific rules in a single pass:
 
 ```sh
 pnpm add -D resultar-check
 ```
 
-Use the CLI as the authoritative local and CI check:
-
-```json
-{
-  "scripts": {
-    "check": "resultar-check"
-  }
-}
-```
-
-The CLI uses TypeScript-Go to run compiler and Resultar diagnostics over the same `tsconfig.json`.
-Configure its rules in the project file:
+Add the rule configuration to `tsconfig.json`:
 
 ```json
 {
@@ -913,108 +837,94 @@ Configure its rules in the project file:
 }
 ```
 
-The `plugins` entry is configuration consumed by the native CLI and stdio LSP server; it does not
-install an editor extension. Run `resultar-check lsp` from an editor language-server configuration.
-A separate TypeScript installation is not required.
+Run `resultar-check` in CI or `resultar-check lsp` in your editor to catch discarded `Result` / `ResultAsync` / `ResultTask` values, unprovided `any` task requirements, raw `throw` statements (`noThrow`), and ad-hoc `try/catch` blocks (`noTryCatch`). See the [`resultar-check` README](https://github.com/inaiat/resultar/blob/main/packages/check/README.md) for all rules and editor setup.
+
+---
+
+## Ecosystem Packages
 
-See the
-[`resultar-check` guide](https://github.com/inaiat/resultar/blob/main/packages/check/README.md)
-for all diagnostics, severities, modes, and ignore patterns.
+Resultar's companion packages integrate directly with the core primitives:
 
-## HTTP Request Packages
+| Package                                                                              | When to use it                                                                    | Documentation                                                                             |
+| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| [`resultar-check`](https://www.npmjs.com/package/resultar-check)                     | Native TypeScript-Go compiler + Resultar linter & LSP                             | [README](https://github.com/inaiat/resultar/blob/main/packages/check/README.md)           |
+| [`resultar-request`](https://www.npmjs.com/package/resultar-request)                 | Fetch-first JSON HTTP client returning `ResultAsync` with retries & typed errors  | [README](https://github.com/inaiat/resultar/blob/main/packages/request/README.md)         |
+| [`resultar-request-zod`](https://www.npmjs.com/package/resultar-request-zod)         | Zod schema validation adapter for `resultar-request`                              | [README](https://github.com/inaiat/resultar/blob/main/packages/request-zod/README.md)     |
+| [`resultar-request-typebox`](https://www.npmjs.com/package/resultar-request-typebox) | TypeBox schema validation adapter for `resultar-request`                          | [README](https://github.com/inaiat/resultar/blob/main/packages/request-typebox/README.md) |
+| [`resultar-di`](https://www.npmjs.com/package/resultar-di)                           | Typed dependency injection, class services, and scoped resources for `ResultTask` | [README](https://github.com/inaiat/resultar/blob/main/packages/di/README.md)              |
+| [`resultar-hono`](https://www.npmjs.com/package/resultar-hono)                       | Hono integration with per-request DI scopes and graceful shutdown                 | [README](https://github.com/inaiat/resultar/blob/main/packages/hono/README.md)            |
+| [`resultar-fastify`](https://www.npmjs.com/package/resultar-fastify)                 | Fastify plugin with application/request DI scopes and lifecycle cleanup           | [README](https://github.com/inaiat/resultar/blob/main/packages/fastify/README.md)         |
 
-Resultar's Fetch-first request packages return `ResultAsync` values for request creation, network,
-HTTP status, JSON parsing, validation, and retry failures.
+Deprecated eager compatibility is included directly in [`resultar`](#in-flight-resultasync--deprecated-eager-compatibility); no additional package or subpath is needed.
 
-| Package | Use it when | Guide |
-| --- | --- | --- |
-| [`resultar-request`](https://www.npmjs.com/package/resultar-request) | You use a custom validator or decoder | [README](https://github.com/inaiat/resultar/blob/main/packages/request/README.md) |
-| [`resultar-request-typebox`](https://www.npmjs.com/package/resultar-request-typebox) | Your response contract is a TypeBox schema | [README](https://github.com/inaiat/resultar/blob/main/packages/request-typebox/README.md) |
-| [`resultar-request-zod`](https://www.npmjs.com/package/resultar-request-zod) | Your response contract is a Zod schema or transform | [README](https://github.com/inaiat/resultar/blob/main/packages/request-zod/README.md) |
+Request helpers return an in-flight `ResultAsync` (`StrictResultAsync`) that starts executing on call. Their public
+execution contract is unchanged. Wrap the call in a factory to create a new request per Task run:
 
-The adapters delegate transport, JSON parsing, retries, and error mapping to `resultar-request` and
-re-export its public request types. Install only the core request package and schema adapter your
-service needs.
+```ts
+import { ResultTask } from "resultar";
+import { requestJson } from "resultar-request";
+
+const loadAccount = (id: string) =>
+  ResultTask.fromResultAsync((signal) =>
+    requestJson({
+      request: () => fetch(`/api/accounts/${id}`, { signal }),
+      validator: (value): value is { readonly id: string } =>
+        typeof value === "object" &&
+        value !== null &&
+        "id" in value &&
+        typeof value.id === "string",
+    }),
+  );
+
+const result = await loadAccount("acct_1").runResult();
+```
+
+---
 
 ## API Decision Guide
 
-| Need | Use |
-| --- | --- |
-| Create success or failure | `ok`, `err`, `okAsync`, `errAsync` |
-| Create an `Ok(undefined)` | `unit`, `unitAsync` |
-| Transform success | `map`, `asyncMap`, `as` |
-| Add a fallible condition | `filterOrElse` |
-| Transform failure | `mapErr` |
-| Continue fallible work | `andThen`, `asyncAndThen` |
-| Recover from failure | `orElse`, `catchTag`, `catchTags` |
-| Wrap throwing or rejecting code | `tryResult`, `tryResultAsync`, `fromPromise` |
-| Write linear Result code | `Result.gen` (`safeTry` compatibility alias) |
-| Describe reusable lazy work | `ResultTask.succeed`, `sync`, `try`, `tryPromise` |
-| Compose or recover lazy work | `ResultTask.map`, `flatMap`, `andThen`, `catchAll`, `gen` |
-| Require or bind typed services | `ResultTask.service`, `provideService`, `provideServices`, `provideServiceResolver` |
-| Execute lazy work explicitly | `ResultTask.runExit`, `runResult`, `runPromise` |
-| Bridge to started promises | `ResultTask.fromResultAsync`, `toResultAsync`, `ResultAsync.fromTask` |
-| Handle a final boundary | `match`, `matchTags`, `matchTagsPartial` |
-| Combine independent results | `zip`, `combine`, `combineWithAllErrors` |
-| Try ordered fallback candidates | `firstSuccessOf` |
-| Process async collections | `ResultAsync.forEach`, `ResultAsync.validateAll` |
-| Race concurrent tasks | `ResultAsync.race`, `raceAll`, `raceFirst` |
-| Apply a timeout | `ResultAsync.timeout` |
-| Retry transient work | `ResultAsync.retry`, `retryOrElse` |
-| Pair acquisition and cleanup | `ResultAsync.withResource` |
-| Observe without changing the result | `tap`, `tapError`, `log` |
-| Default deliberately at an edge | `unwrapOr` |
-| Throw deliberately at an edge | `unwrapOrThrow` |
-
-The
-[complete API map](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#api-map)
-covers overloads, aliases, callback semantics, collection helpers, conditional helpers, tagged
-reasons, disposable results, and compatibility APIs.
-
-## Coding agents
-
-Each npm build includes `dist/llms.txt`, `dist/agent/SKILL.md`, focused references, a compiled
-core workflow example, and `dist/agent/versions.json`. Start from these installed files so the
-guide matches the package version. Companion package READMEs take precedence when their installed
-versions differ from the recorded companion versions. The online `main` guide tracks development.
-
-The guide distinguishes `Result.gen` from `ResultTask.gen`, immediate from lazy execution,
-observation from effectful `tap`, and `runResult` from the non-rejecting `runExit` boundary.
+| Goal                                           | Recommended API                                                                            |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Create success or failure                      | Sync: `ok`, `err`, `unit`; Task: `ResultTask.ok`, `ResultTask.err`                         |
+| Define a structured error class                | `createTaggedError({ name, message })` (`.withProps<...>()` for custom field types)        |
+| Lift nullable values or predicates             | `Result.fromNullishOr`, `Result.liftPredicate`                                             |
+| Wrap throwing sync or async code               | Sync: `tryResult` / `fromThrowable`; async: `ResultTask.tryPromise`                        |
+| Transform or chain results                     | `map`, `mapErr`, `andThen`, `filterOrElse`, `as`, `asVoid`; Task `map` is synchronous      |
+| Write linear generator workflows               | `Result.gen`, `Result.fn`, `ResultTask.gen`, `ResultTask.fn`                               |
+| Recover from specific errors                   | `catchTag`, `catchTags`, `orElse`, `orElseSucceed`, `unwrapOr`                             |
+| Handle results at a boundary                   | `matchTags`, `matchTagsPartial`, `match`                                                   |
+| Combine multiple results                       | Sync: `Result.all`; Task: `ResultTask.all`, `forEach`, `validateAll`, `firstSuccessOf`     |
+| Add async timeout, retry, or race              | `task.timeout`, `task.retry`, `ResultTask.race`, `raceFirst`, `Retry.policy`               |
+| Build lazy, cancelable workflows               | `ResultTask.tryPromise`, `sync`, `try`, `service`, `provideServices`                       |
+| Manage resource lifecycles                     | `ResultTask.acquireRelease`, `acquireDisposable`, `scoped`, `ensuring`                     |
+| Run lazy tasks at an edge                      | `task.runResult()`, `runExit()`, `runPromise()`, `runFork()` (static forms also supported) |
+| Observe without altering the channel           | `inspect`, `inspectError`, `inspectBoth`, `log`                                            |
+| Preserve an existing eager Async boundary      | `tryResultAsync`, `fromPromise`, `fromThrowableAsync`, `okAsync`, `errAsync`               |
+| Adapt eager Async or request helpers into Task | `ResultTask.fromResultAsync(signal => load(signal))`                                       |
+
+See the [Complete API Map](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#api-map) for all overloads, collection helpers, and compatibility aliases.
+
+---
+
+## Coding Agents
+
+Every npm release bundles `dist/llms.txt`, `dist/agent/SKILL.md`, focused API and service references, and a compiled workflow example inside `node_modules/resultar/dist/agent/`. Point your coding agent to those installed files so its guidance always matches the exact installed version.
+
+---
 
 ## More Documentation
 
-- [Full Resultar guide](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md)
-- [ResultTask core RFC](https://github.com/inaiat/resultar/blob/main/docs/rfcs/rfc-0001-result-task-core.md)
-- [Runnable core cookbook](https://github.com/inaiat/resultar/tree/main/examples/resultar)
-- [Catching and recovering errors](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#catching-and-recovering-errors)
-- [Safe Try](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#safe-try)
-- [Validation error recipes](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#validation-error-recipes)
-- [Coming from other error-handling styles](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#coming-from-other-styles)
-- [Public exports and compatibility aliases](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#public-entry-point)
-- [Type-safe error handling article](https://github.com/inaiat/resultar/blob/main/articles/en/type-safe.md)
-- [Artigo sobre tratamento de erros type-safe](https://github.com/inaiat/resultar/blob/main/articles/pt/type-safe.md)
-
-Resultar is also published on [JSR as `@inaiat/resultar`](https://jsr.io/@inaiat/resultar).
-
-## Limitations
-
-ResultTask implements the RFC 0001 lazy core, generator with services, and resource scopes. The
-following are explicitly out of scope for this slice:
-
-- No `Stream`, STM, caching, clustering, RPC, or platform layer; this is not a full Effect API port.
-- No implicit global runtime: every `run*` call creates its own root scope and signal, and simple
-  tasks need no services or configuration.
-- No fibers or structured concurrency yet: `forkChild`/`join`/`interrupt`, task `race`/`timeout`,
-  and uniform `all`/`forEach` over the task runtime are still Phase 3. The `Cause` model covers
-  `Fail`, `Die`, `Interrupt`, and `Sequential`; `Parallel` is reserved for that future work. Use the
-  `ResultAsync` race, timeout, retry, and concurrency helpers in the meantime — they keep their own
-  eager, per-helper protocols.
-- No `Schedule`, schedule-based retry, or injectable clock yet (Phase 4).
-- No `Layer` system in the core: service graphs with their own lifecycle belong to the optional
-  `resultar-di` package, and the core does not depend on it.
-- `ResultAsync` stays eager and awaitable. `fromResultAsync` on an existing instance captures an
-  already-started execution; only the factory form defers creation.
-- Validated on Node.js 24+ only; other runtimes such as Bun are unvalidated.
+- [Gradual Adoption: `Result` to `ResultTask`](https://github.com/inaiat/resultar/blob/main/docs/gradual-adoption.md)
+- [Full Resultar Reference (`DOCUMENTATION.md`)](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md)
+- [v4 Migration & Deprecated API Notes](https://github.com/inaiat/resultar/blob/main/docs/migrations/v4.md)
+- [Runnable Examples (`examples/`)](https://github.com/inaiat/resultar/tree/main/examples)
+- [Type-Safe Error Handling Article (EN)](https://github.com/inaiat/resultar/blob/main/articles/en/type-safe.md) | [Artigo em Português (PT-BR)](https://github.com/inaiat/resultar/blob/main/articles/pt/type-safe.md)
+
+### Scope & Limitations
+
+- **Focused scope**: Resultar is not a full Effect port—it intentionally omits `Stream`, STM, distributed clustering, and a global application runtime.
+- **Cooperative cancellation**: Task timeouts and fiber interruptions abort the `AbortSignal` and await scope finalizers; underlying drivers must respect the signal. `ResultTask.tryPromise` can opt into `interruption: 'detach'`. Legacy Async signal-aware helpers remain cooperative, with best-effort resource release.
+- **Deferred execution vs. already-started Promises**: Task factories defer work until an explicit `run*`. Eager async helpers and async `Result.gen` / `Result.fn` start eagerly and share one execution. Wrapping an already-created Promise cannot defer or replay it.
 
 ## License