resultar 3.7.0 → 3.9.0

package/README.md

@@ -494,13 +494,12 @@ The callback runs only when the task executes. Use `tryPromise({ try, catch })`
 specific error type; both forms receive the runtime signal and preserve interruption semantics.
 
 Workflows can request typed services with `yield*` and receive them at the boundary. Pass the service
-type and its literal identifier so the named environment remains checked:
+type first, then let the second call infer its literal identifier:
 
 ```ts
 const Database = ResultTask.service<
-  { findUser: (id: string) => Promise<string> },
-  'Database'
->('Database')
+  { findUser: (id: string) => Promise<string> }
+>()('Database')
 
 const taskWithDatabase = ResultTask.gen(function* () {
   const database = yield* Database
@@ -529,6 +528,16 @@ await ResultTask.runResult(readyWithOne)
 await ResultTask.runResult(readyWithAll)
 ```
 
+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;
@@ -962,6 +971,16 @@ The
 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.
+
 ## More Documentation
 
 - [Full Resultar guide](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md)

package/dist/agent/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: resultar
+description: Build, review, migrate, test, and document TypeScript code using Resultar v3.7+, including Result, ResultAsync, ResultTask, StrictResult, createTaggedError, Result.gen/safeTry, request adapters, and resultar-check. Use when expected failures should become typed values, thrown or rejected work must be wrapped, Resultar pipelines or async policies need design, HTTP JSON needs TypeBox or Zod validation, Resultar diagnostics need configuration, or an existing Resultar codebase needs review or migration.
+metadata:
+  tags: [typescript, error-handling]
+  domains: [foundation]
+---
+
+# Resultar Engineering
+
+Use Resultar to keep expected failures explicit in TypeScript without introducing an application
+runtime. Produce code that preserves concrete success and error types from the domain boundary to
+the final transport, job, CLI, or integration boundary.
+
+## Start From Repository Truth
+
+1. Inspect the consuming project's `package.json`, lockfile, Resultar version, module format, and
+   TypeScript version before proposing code.
+2. Prefer the installed package types and local source over remembered APIs. The core package
+   ships this guide at `node_modules/resultar/dist/agent/SKILL.md`; check its `versions.json` before
+   using companion-package recipes. Online `main` documentation may describe a newer release.
+3. In the Resultar repository, use these sources in order:
+   - `packages/resultar/src/index.ts` for public exports.
+   - `packages/resultar/README.md` and `DOCUMENTATION.md` for current semantics and examples.
+   - `packages/check/README.md` for diagnostics.
+   - `packages/request*/README.md` and `examples/request/` for request integrations.
+4. Adapt examples when the consumer uses an older Resultar version; do not silently emit APIs
+   that are absent locally.
+
+## Choose The Execution Model
+
+| Contract | `Result` / `Result.gen` | `ResultAsync` | `ResultTask` |
+| --- | --- | --- | --- |
+| Execution | Sync values; `Result.gen` also accepts async generators | Starts immediately | Building/composing starts nothing; each `run*` executes again |
+| Generator return | `return ok(value)`; `yield*` short-circuits failures | Compose through `Result.gen` with `yield*` | `return value`; compose tasks, services and Results with `yield*` |
+| Error transform / recovery | `mapErr` / `orElse` | `mapErr` / `orElse` | `mapError` / `catchAll` |
+| `tap` / `tapError` failure | Ignored observation failure | Ignored observation failure | Returned task failures join `E`; throws/rejected Promises become `Die` |
+| Cleanup | Disposal callbacks are best-effort | `withResource` release is best-effort | `acquireRelease` + `scoped` await release and preserve failures |
+
+Use `ResultAsync` for existing Promise-shaped use cases. Choose `ResultTask` for reusable lazy
+work, typed service requirements, or owned resource lifetimes. Preserve existing eager/lazy
+contracts; converting an already-started Promise or ResultAsync cannot undo its execution.
+`ResultTask.runResult` can reject on defects, interruption, and composite causes. Use `runExit`
+when the boundary must inspect every exit without rejection. See [API details](references/api.md).
+For DI, Hono and Fastify, read [services and HTTP scopes](references/services.md). Use
+`ResultTask.service<T>()(name)` or DI `Service.require<T>()(name)` for inferred identifiers. Class
+services support optional `requires` with a factory returning ResultTask; generator-only `make`
+remains available. Check installed versions before using these overloads.
+
+## Apply Opinionated Defaults
+
+- Return `Result<T, E>` for synchronous fallible work and `ResultAsync<T, E>` for asynchronous
+  fallible work.
+- Prefer `StrictResult<T, E extends Error>` and `StrictResultAsync<T, E extends Error>` at
+  application, service, HTTP, job, queue, CLI, and integration boundaries.
+- Return `ResultAsync` / `StrictResultAsync` directly from async services and repositories instead
+  of `Promise<T>`, `Promise<Result>` or `Promise<StrictResult>`. Map external driver failures to
+  typed errors in the repository adapter; services compose that result directly. Remove the
+  function's `async` wrapper; changing only its return annotation cannot change the runtime value.
+- Use `preferResultAsync: "error"` with `preferResultAsyncMode: "all"` to enforce these application
+  contracts. Document local rule suppressions for native framework/driver callbacks that require
+  Promise interoperability.
+- Prefer `createTaggedError` for expected domain and application failures that need stable identity,
+  metadata, causes, serialization, or exhaustive handling.
+- Keep error unions specific. Let composition widen them naturally; do not collapse them to `Error`
+  before the boundary.
+- Return `Err` for expected failures. Reserve `throw` for programmer defects, invalid library
+  arguments, or deliberate terminal/process boundaries.
+- Wrap third-party throws and promise rejections at the edge, then keep the internal flow Resultar-
+  native.
+- Avoid `T | Error`, sentinel `null`, broad `try/catch`, rejected expected failures, and unsafe casts
+  as substitutes for a Resultar error channel.
+- Keep `_unsafeUnwrap()` and `_unsafeUnwrapErr()` in tests. Use `unwrapOrThrow()` only when throwing
+  is explicitly the intended boundary behavior.
+
+## Choose The Composition Operator
+
+| Need                                      | Prefer                   |
+| ----------------------------------------- | ------------------------ |
+| Transform an `Ok` without failure         | `map`                    |
+| Transform an `Err`                        | `mapErr`                 |
+| Validate an `Ok` with a predicate         | `filterOrElse`           |
+| Continue with a sync fallible step        | `andThen`                |
+| Continue from `Result` into `ResultAsync` | `asyncAndThen`           |
+| Recover the whole error channel           | `orElse`                 |
+| Recover selected tagged errors            | `catchTag` / `catchTags` |
+| Branch directly                           | `isOk()` / `isErr()`     |
+| Convert a result at a boundary            | `match` / `matchTags`    |
+| Map selected tagged errors with fallback  | `matchTagsPartial`       |
+| Reuse a named Result combinator           | `pipe`                   |
+| Write a readable linear pipeline          | `safeTry` with `yield*`  |
+
+Use `catchTags` for partial pipeline recovery; unhandled tags stay in the error channel. Do not
+invent `partialCatchTags`. Use `matchTagsPartial` only for boundary matching with a deliberate
+fallback.
+
+## Model Tagged Errors
+
+```ts
+import { createTaggedError, ok } from "resultar";
+import type { StrictResult } from "resultar";
+
+class InvalidEmailError extends createTaggedError({
+  name: "InvalidEmailError",
+  message: "Invalid email $email",
+}) {}
+
+const validateEmail = (email: string): StrictResult<string, InvalidEmailError> =>
+  email.includes("@") ? ok(email) : InvalidEmailError.err({ email });
+```
+
+- Let message-template variables define required constructor props.
+- Preserve `cause` when converting an external failure.
+- Treat `ErrorClass.is(value)` as nominal; do not rely on spoofed `_tag` objects.
+- Use `TaggedEnum` only for lightweight tagged domain variants that do not need to be real errors.
+- Include an `Error` handler when a matched union can contain untagged errors.
+
+## Compose Async Work
+
+Wrap uncontrolled async work with the helper that matches how it is created:
+
+- Use `fromPromise(promise, toError)` for an already-created promise.
+- Use `tryResultAsync({ try, catch })` or `tryResultAsync(factory, toError)` when creating the
+  promise can throw synchronously.
+- Use `fromSafePromise` only when rejection is impossible by contract.
+- Use `fromCallback` for callback or subscription APIs with explicit cleanup.
+- Use `runPromise` only at a terminal boundary that intentionally resolves or throws.
+
+Prefer lazy Resultar policies over ad hoc timers or `Promise.race`:
+
+- Use `ResultAsync.retry` / `retryOrElse` for typed retry and fallback policy.
+- Use `timeout`, `race`, `raceAll`, or `raceFirst` for signal-aware concurrency.
+- Use mapped `forEach` for first-error batch work and mapped `validateAll` for collecting every
+  independent validation error.
+- Use `withResource` when successful acquisition must always trigger best-effort release.
+- Pass the provided abort signal into the underlying client; cancellation is cooperative.
+
+On `Result` and `ResultAsync`, use `tap`, `tapError`, and `log` for best-effort observation.
+`ResultTask.tap` and `tapError` participate in failure handling; they do not swallow failures. Use `andThen`, `orElse`, or a
+Resultar wrapper when callback failure must change control flow.
+
+## Use `Result.gen` For Linear Result Flows
+
+```ts
+const createUser = (input: CreateUserInput): StrictResultAsync<User, CreateUserError> =>
+  Result.gen(async function* () {
+    const email = yield* validateEmail(input.email);
+    const available = yield* ensureEmailAvailable(email);
+    const user = yield* insertUser({ ...input, email: available });
+
+    return ok(user);
+  });
+```
+
+- `safeTry` is the top-level alias of `Result.gen`; both have the same rules.
+- Use `yield*` for both `Result` and `ResultAsync` values.
+- Wrap raw promises before yielding them.
+- Do not use raw `await` or broad `try/catch` inside a Resultar `safeTry` workflow.
+- Prefer `yield* result` over legacy `safeUnwrap()`.
+
+## Keep Boundaries Concrete
+
+- Define request, command, and event payloads with concrete types; do not widen them to generic JSON
+  records before the use case.
+- Keep transport concerns out of domain code. Convert tagged errors to HTTP responses, CLI exit
+  codes, job outcomes, or logs at the outer boundary.
+- Use exhaustive `matchTags` when every tagged error needs a distinct mapping.
+- Use local `catchTag` / `catchTags` only when recovery belongs to domain policy.
+
+## Handle HTTP JSON Requests
+
+Use the Resultar request family instead of repeating fetch, parsing, validation, retry, and error
+mapping logic:
+
+- Use `resultar-request` with `validator` or `decode` for schema-library-agnostic boundaries.
+- Use `resultar-request-typebox` when contracts use TypeBox and preserve `Static<typeof schema>`.
+- Use `resultar-request-zod` when contracts use Zod and preserve transformed
+  `z.output<typeof schema>`.
+- Map request, HTTP, invalid-JSON, and validation failures to concrete tagged errors when they cross
+  an application boundary.
+
+Read `references/integrations.md` before implementing request adapters or diagnostics.
+
+## Validate In The Preferred Order
+
+1. Run the `resultar-check` CLI as the authoritative project and CI gate. It runs TypeScript and the
+   full Resultar rule set against the project.
+2. Configure `resultar-check lsp` as the editor's stdio language server for inline diagnostics and
+   quick fixes. It reads the same project configuration as the CLI.
+3. Use JSONL, SARIF, or JUnit output when another CI or review system needs structured diagnostics;
+   do not present those consumers as replacements for the native checker.
+4. Run the repository's native formatting, build, tests, analysis, package smoke, and example
+   workflows when available.
+
+JSONL fixes distinguish `correction` from `intentional-discard`; LSP actions carry the same
+classification in `data.kind`. Do not apply a discard just to silence the checker: `void task`
+does not execute a lazy task or handle its errors. Corrections still need compilation and tests.
+
+Treat stable `resultar/*` rule IDs as architecture feedback. Fix the typed boundary or composition
+problem instead of suppressing diagnostics broadly. Use narrow ignore patterns only for deliberate
+test, script, generated, or process-boundary exceptions.
+
+## Test And Document Behavior
+
+- Cover `Ok` and every expected `Err` path with runtime tests.
+- Cover inferred error unions, tagged-error props, narrowing, and exhaustive handlers with type
+  tests. Use `expectTypeOf` and `@ts-expect-error` where supported.
+- Use the consuming project's test runner. Use `vite-plus/test` inside this repository.
+- Test retry, timeout, cancellation, concurrency, and cleanup policies with deterministic fakes.
+- Derive documentation examples from checked source or runnable examples and keep package links
+  reciprocal when packages are alternatives or adapters.
+
+## Review Before Finishing
+
+- Run the project's Resultar CLI check after edits.
+- Confirm no Result, ResultAsync, or ResultTask value is silently discarded.
+- Confirm mapped errors preserve `cause` and useful metadata.
+- Confirm boundary handlers cover the actual error union.
+- Confirm request validation derives the downstream type instead of widening it.
+- Confirm validation claims match commands that actually passed.
+
+## Load References Selectively
+
+- Read `references/api.md` for current exports, collection helpers, and async policy semantics.
+- Read `references/patterns.md` for copyable implementation and migration patterns.
+- Read `references/integrations.md` for request adapters and the CLI/editor/lint workflow.
+- Read `references/review-checklist.md` for reviews, migrations, and final validation.

package/dist/agent/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Resultar Engineering"
+  short_description: "Build and review typed Resultar workflows"
+  default_prompt: "Use $resultar to build or review a typed Resultar workflow."

package/dist/agent/examples/workflow.mjs

@@ -0,0 +1,21 @@
+import { createTaggedError, ok, Result, ResultTask } from 'resultar';
+export class InvalidEmailError extends createTaggedError({
+    name: 'InvalidEmailError',
+    message: 'Invalid email $email',
+}) {
+}
+export const validateEmail = (email) => {
+    const normalized = email.trim().toLowerCase();
+    return normalized.includes('@') ? ok(normalized) : InvalidEmailError.err({ email });
+};
+export const account = (email) => Result.gen(function* () {
+    const normalized = yield* validateEmail(email);
+    return ok({ email: normalized });
+});
+export const Greeting = ResultTask.service('greeting');
+// Creating this task runs no work. The boundary supplies its typed dependency.
+export const welcome = (email) => ResultTask.gen(function* () {
+    const normalized = yield* validateEmail(email);
+    const greeting = yield* Greeting;
+    return `${greeting}, ${normalized}`;
+});

package/dist/agent/examples/workflow.mts

@@ -0,0 +1,27 @@
+import { createTaggedError, ok, Result, ResultTask } from 'resultar'
+import type { StrictResult } from 'resultar'
+
+export class InvalidEmailError extends createTaggedError({
+  name: 'InvalidEmailError',
+  message: 'Invalid email $email',
+}) {}
+
+export const validateEmail = (email: string): StrictResult<string, InvalidEmailError> => {
+  const normalized = email.trim().toLowerCase()
+  return normalized.includes('@') ? ok(normalized) : InvalidEmailError.err({ email })
+}
+
+export const account = (email: string): StrictResult<{ email: string }, InvalidEmailError> =>
+  Result.gen(function* () {
+    const normalized = yield* validateEmail(email)
+    return ok({ email: normalized })
+  })
+
+export const Greeting = ResultTask.service<string, 'greeting'>('greeting')
+
+// Creating this task runs no work. The boundary supplies its typed dependency.
+export const welcome = (email: string) => ResultTask.gen(function* () {
+  const normalized = yield* validateEmail(email)
+  const greeting = yield* Greeting
+  return `${greeting}, ${normalized}`
+})

package/dist/agent/references/api.md

@@ -0,0 +1,249 @@
+# Resultar v3.7+ API Guide
+
+Use this reference after checking the version installed by the consuming project. The local package
+types and source are authoritative when they differ from this guide.
+
+## Contents
+
+- [Package Baseline](#package-baseline)
+- [Core Types And Constructors](#core-types-and-constructors)
+- [Composition And Recovery](#composition-and-recovery)
+- [Tagged Errors](#tagged-errors)
+- [Boundary Matching](#boundary-matching)
+- [Async Boundaries](#async-boundaries)
+- [Async Policies](#async-policies)
+- [Collections And Control Flow](#collections-and-control-flow)
+- [`safeTry`](#safetry)
+- [ResultTask (Lazy Workflows)](#resulttask-lazy-workflows)
+- [Observation And Cleanup](#observation-and-cleanup)
+
+## Package Baseline
+
+Resultar v3.7 is an ESM package targeting Node.js 24+. The repository currently uses TypeScript 7.
+Do not infer consumer requirements from memory: inspect `package.json`, the lockfile, and exported
+types first.
+
+Prefer named imports and type-only imports:
+
+```ts
+import { ResultAsync, createTaggedError, ok, safeTry, tryResult, tryResultAsync } from "resultar";
+import type { StrictResult, StrictResultAsync } from "resultar";
+```
+
+`tryCatch` and `tryCatchAsync` remain compatibility aliases. Prefer `tryResult` and
+`tryResultAsync` in new v3.7+ code.
+
+## Core Types And Constructors
+
+| Need                                                | API                                      |
+| --------------------------------------------------- | ---------------------------------------- |
+| Synchronous fallible value                          | `Result<T, E>`                           |
+| Asynchronous fallible value                         | `ResultAsync<T, E>`                      |
+| Error-only sync channel                             | `StrictResult<T, E extends Error>`       |
+| Error-only async channel                            | `StrictResultAsync<T, E extends Error>`  |
+| Successful value                                    | `ok(value)` / `okAsync(value)`           |
+| Successful `undefined`                              | `unit()` / `unitAsync()`                 |
+| Expected failure                                    | `err(error)` / `errAsync(error)`         |
+| Catch synchronous throws now                        | `tryResult(fn, toError)`                 |
+| Wrap a synchronous throwing function                | `fromThrowable(fn, toError)`             |
+| Catch promise rejection or a throwing async factory | `tryResultAsync(input, toError)`         |
+| Wrap an async throwing function                     | `fromThrowableAsync(fn, toError)`        |
+| Deliberately leave Resultar at a terminal boundary  | `runSync(result)` / `runPromise(result)` |
+
+Use the named options form when it improves readability:
+
+```ts
+const parsed = tryResult({
+  try: () => JSON.parse(input) as unknown,
+  catch: (cause) => new ParsePayloadError({ cause }),
+});
+```
+
+`runSync` returns the `Ok` value or throws the `Err`; `runPromise` resolves the `Ok` value or
+rejects with the `Err`. Keep both at framework, bootstrap, CLI, or test boundaries.
+
+## Composition And Recovery
+
+- `map` transforms an `Ok` value with an infallible function.
+- `mapErr` transforms an `Err` value.
+- `filterOrElse` validates or narrows an `Ok` value and introduces a typed error on failure.
+- `andThen` chains fallible work. On `ResultAsync`, it accepts sync or async Resultar work.
+- `asyncAndThen` bridges a synchronous `Result` into `ResultAsync`.
+- `orElse` recovers the complete error channel.
+- `catchTag` recovers one tagged error.
+- `catchTags` recovers selected tagged errors; unhandled variants stay in the error union.
+- `pipe` applies named combinators without changing Result semantics.
+
+Let each step expose its narrow error type and let composition infer the union:
+
+```ts
+type CreateUserError = InvalidEmailError | UserExistsError | SaveUserError;
+
+const createUser = (input: CreateUserInput): StrictResultAsync<User, CreateUserError> =>
+  validateEmail(input.email)
+    .asyncAndThen(ensureEmailAvailable)
+    .andThen((email) => saveUser({ ...input, email }));
+```
+
+Do not manually cast the final error union. A surprising inferred union is usually evidence that a
+step has a broad or inaccurate signature.
+
+## Tagged Errors
+
+`createTaggedError` creates nominal `Error` subclasses with stable `_tag`, message-template props,
+`cause`, `fingerprint`, `toJSON()`, and `.err()` support.
+
+```ts
+class UserNotFoundError extends createTaggedError({
+  name: "UserNotFoundError",
+  message: "User $userId was not found in $source",
+}) {}
+
+const missing = UserNotFoundError.err({ userId, source: "database" });
+```
+
+- Let `$variables` in the message template define required constructor props.
+- Preserve the original failure with `cause` when adapting external code.
+- Keep the configured `name` equal to the class name.
+- Do not override the generated constructor.
+- Treat `ErrorClass.is(value)` as a nominal `instanceof`-based guard; a matching `_tag` is not
+  sufficient.
+- Avoid reserved template fields such as `_tag`, `name`, `message`, `messageTemplate`,
+  `fingerprint`, `stack`, and `cause`.
+- Use `TaggedEnum`/`taggedEnum` for lightweight tagged data that should not be an `Error`.
+- Use `redact`, `isRedacted`, and `revealRedacted` when sensitive error metadata must not serialize
+  or log by default.
+- Use `findCause` or an instance's `findCause` to inspect a typed cause chain.
+
+## Boundary Matching
+
+Use branch methods inside an algorithm and matching when converting the completed result:
+
+- `isOk()` / `isErr()` narrow for direct control flow.
+- `match(onOk, onErr)` handles a simple boundary.
+- `matchTags(onOk, handlers)` exhaustively maps tagged errors.
+- `matchTagsPartial(onOk, handlers, fallback)` handles selected tags with a deliberate fallback.
+- `matchError(error, handlers)` handles an error value directly.
+- `matchErrorPartial(error, handlers, fallback)` partially handles an error value.
+
+Include an `Error` handler whenever an error union can contain an untagged `Error`. Do not invent
+`partialCatchTags`; `catchTags` already supports partial recovery.
+
+## Async Boundaries
+
+Choose the wrapper based on ownership of the promise:
+
+- `fromPromise(existingPromise, toError)` wraps a promise that has already been created.
+- `tryResultAsync(() => createPromise(), toError)` also catches synchronous factory throws and is
+  preferred when the agent controls creation.
+- `fromSafePromise(promise)` is only for promises guaranteed not to reject by contract.
+- `fromCallback(options)` adapts callback or subscription APIs and returns
+  `ResultAsync<T, E | AbortError>`. Supply cleanup and forward cancellation where supported.
+- `AbortError` and `isAbortError` identify Resultar cancellation.
+
+Always map `unknown` causes into a specific error near the external boundary:
+
+```ts
+const loadUser = (id: string): StrictResultAsync<User, LoadUserError> =>
+  tryResultAsync(
+    () => client.loadUser(id),
+    (cause) => new LoadUserError({ cause, id }),
+  );
+```
+
+## Async Policies
+
+Use the built-in lazy policies instead of hand-written `Promise.race`, timers, or retry loops:
+
+- `ResultAsync.retry(task, options)` retries typed failures and includes `AbortError` in the error
+  channel. Use `times`, `delayMs`, `jittered`, `while`, and the provided signal deliberately.
+- `ResultAsync.retryOrElse(task, options)` applies a typed fallback after retry exhaustion. The
+  exhausted task error is replaced by the fallback error channel.
+- `ResultAsync.timeout(task, options)` returns the task error or the typed `onTimeout` error.
+- `ResultAsync.race(left, right)` and `raceAll(tasks)` return the first settled result.
+- `ResultAsync.raceFirst(left, right)` returns the first `Ok`; if both fail, it returns the last
+  observed `Err`.
+- `ResultAsync.raceWith(left, right, handlers)` exposes the winner and a handle to the still-running
+  task for custom cooperative policy.
+- `ResultAsync.withResource({ acquire, use, release })` releases after every acquire-success path.
+  Release errors are best-effort and do not enter the result channel; model cleanup in `use` when it
+  must affect control flow.
+
+Race, timeout, retry, callback, and resource helpers rely on cooperative cancellation. Pass their
+`AbortSignal` into fetch, database, SDK, timer, or subscription work; aborting a wrapper cannot stop
+an underlying operation that ignores the signal.
+
+## Collections And Control Flow
+
+Both `Result` and `ResultAsync` provide collection helpers:
+
+- `combine` preserves array/tuple/record shape and returns the first error.
+- `combineWithAllErrors` collects every error.
+- `validateAll` collects all validation errors; async mapped use supports bounded `concurrency`.
+- `zip` combines exactly two values.
+- `firstSuccessOf` tries candidates until one succeeds and otherwise returns the final error.
+- `forEach` stops at the first error; use `{ discard: true }` when successful values are irrelevant.
+- `when`, `unless`, `loop`, and `iterate` model Resultar-native control flow where they improve
+  clarity.
+
+Prefer `ResultAsync.forEach(items, mapper, { concurrency })` for bounded first-error processing and
+`ResultAsync.validateAll(items, mapper, { concurrency })` for independent validation where every
+error matters.
+
+## `safeTry`
+
+Use `safeTry` when a linear generator is clearer than a chain:
+
+```ts
+const workflow = safeTry(async function* () {
+  const input = yield* validateInput(raw);
+  const remote = yield* loadRemote(input);
+  const saved = yield* saveRemote(remote);
+
+  return ok(saved);
+});
+```
+
+Use `yield*` for `Result` and `ResultAsync`. Wrap raw promises before yielding. Avoid raw `await`,
+`try/catch`, and legacy `safeUnwrap()` inside the generator.
+
+## ResultTask (Lazy Workflows)
+
+`ResultTask<A, E, R>` is a lazy, reusable description of work: building one starts nothing, and
+each `run*` call executes it again. Never substitute `ResultAsync` (already-started) where
+laziness matters.
+
+- Build: `succeed`, `fail`, `fromResult`, `sync`, `try`, `tryPromise` (`try`/`tryPromise` map
+  external throws into `E`; `sync` treats them as defects).
+- Compose lazily: `map`, `flatMap`, `catchAll`, `tap`, `gen` with `yield*` (also accepts
+  `yield* result`: `Ok` unwraps, `Err` short-circuits into `E`).
+- Provide services: `yield* Tag`, then `provideService` / `provideServices` /
+  `provideServiceResolver` (data-first and curried); missing or incompatible providers are
+  compile-time errors, never runtime surprises.
+- Resources: `acquireRelease` + `scoped`; LIFO awaited finalizers run on every exit; deferred
+  release errors live in `R` until `scoped` folds them into `E`; `catchAll` recovers a release
+  failure only after `scoped`.
+- Boundaries: `runExit` preserves `Success`/`Fail`/`Die`/`Interrupt`/`Sequential`; `runResult`
+  returns one `Err` and rejects the rest (`AbortError` for interrupts, `ResultTaskCauseError`
+  for composites); `runPromise` unwraps or rejects. Cancellation is cooperative: no fibers,
+  `race`, `timeout`, or scheduler exist on `ResultTask` yet — use the `ResultAsync` helpers.
+
+`Result.gen` is the canonical name for linear Result workflows; `safeTry` remains as its alias.
+For lazy `ResultTask` workflows with typed services and scopes, see `packages/resultar/README.md`
+(Lazy Workflows With ResultTask) and `docs/rfcs/rfc-0001-result-task-core.md`.
+
+## Observation And Cleanup
+
+On `Result` and `ResultAsync`, `tap`, `tapError`, and `log` preserve the original result. Callback throws and rejected callback
+promises are intentionally ignored, so use them only for best-effort logging, metrics, tracing, and
+observation. Use `andThen`, `orElse`, or a Resultar boundary when side-effect failure must alter the
+workflow.
+
+`toDisposable` and `toAsyncDisposable` integrate with Node.js `using` / `await using`; their
+cleanup callbacks are also best-effort. Prefer `withResource` for acquire/use/release workflows.
+
+On `ResultTask`, `tap` and `tapError` are lazy effectful composition. Returned task errors and
+requirements join the workflow type. A thrown callback or rejected Promise becomes `Die`;
+a returned `ResultTask.fail(error)` becomes a typed failure. Use an explicitly recovered task
+when observation must be best-effort. `runExit` preserves these exits; `runResult` can reject.
+Do not substitute `ResultAsync.withResource` for awaited ResultTask resource ownership.