unthrown 3.0.1 → 4.0.0

package/dist/index.d.cts

@@ -16,13 +16,37 @@ type Prettify<T> = { [K in keyof T]: T[K] } & {};
  */
 type Bound<T, K extends string, U> = Prettify<Omit<T, K> & { readonly [P in K]: U }>;
 /**
- * The method surface every {@link Result} variant carries. Factored out so the
- * three variants ({@link OkView}, {@link ErrView}, {@link DefectView}) can each
- * intersect it. Not part of the public API on its own.
+ * Compile-time rejection of a thenable callback result — the type-level
+ * enforcement of "combinator callbacks are synchronous" (see the
+ * {@link AsyncResult} remarks).
+ *
+ * @remarks
+ * Resolves to `unknown` (a no-op in an intersection) for any non-thenable `R`,
+ * and to an explanatory string-literal type when `R` is a `PromiseLike` — so an
+ * `async` callback fails to compile with the explanation in the error. Without
+ * this, `async () => …` would be assignable to `() => void`, and its rejection
+ * would escape the pipeline as an unhandled rejection instead of a `Defect`.
+ * Lift async work with {@link fromPromise} and compose it with `flatMap`.
+ *
+ * @typeParam R - the callback's inferred return type.
+ * @category Types
+ */
+type NotThenable<R> = [R] extends [PromiseLike<unknown>] ? "unthrown: combinator callbacks are synchronous — lift async work with fromPromise and compose with flatMap" : unknown;
+/**
+ * The fluent method surface every {@link Result} variant carries — the
+ * combinators (`map`, `flatMap`, `mapErr`, `match`, `unwrap`, …), documented one
+ * per entry below. Factored out so the three variants ({@link OkView},
+ * {@link ErrView}, {@link DefectView}) can each intersect it; {@link AsyncResult}
+ * mirrors this surface with async signatures.
+ *
+ * @remarks
+ * This type exists to **document** the surface and to power narrowing — not to be
+ * authored against. You obtain it by holding a `Result` (or `AsyncResult`), never
+ * by implementing your own `Result`-like; treat it as read-only reference.
  *
  * @typeParam T - the success value type.
  * @typeParam E - the modeled error type.
- * @internal
+ * @category Methods
  */
 type ResultMethods<T, E> = {
   /**
@@ -31,10 +55,12 @@ type ResultMethods<T, E> = {
    * Runs `f` only on `Ok`; `Err` and `Defect` pass through untouched. If `f`
    * throws, the thrown value is captured as a `Defect`.
    *
+   * An async callback is rejected at compile time ({@link NotThenable}).
+   *
    * @typeParam U - the mapped success type.
    * @param f - maps the current success value to a new one.
    */
-  map<U>(f: (value: T) => U): Result$1<U, E>;
+  map<U>(f: (value: T) => U & NotThenable<U>): Result$1<U, E>;
   /**
    * Sequence a dependent, `Result`-returning step (monadic bind).
    *
@@ -50,11 +76,12 @@ type ResultMethods<T, E> = {
    * Run a side effect on the success value and pass the `Result` through
    * unchanged.
    *
-   * Runs only on `Ok`. If `f` throws, the throw becomes a `Defect`.
+   * Runs only on `Ok`. If `f` throws, the throw becomes a `Defect`. An async
+   * callback is rejected at compile time ({@link NotThenable}).
    *
    * @param f - the side effect (its return value is ignored).
    */
-  tap(f: (value: T) => void): Result$1<T, E>;
+  tap<R>(f: (value: T) => R & NotThenable<R>): Result$1<T, E>;
   /**
    * Run a **failable** side effect on the success value, keeping the original
    * value but threading the effect's error.
@@ -99,14 +126,15 @@ type ResultMethods<T, E> = {
    * @remarks
    * `f` receives the scope and returns a value (not a `Result`); it is added as
    * `{ ...scope, [name]: value }`. Runs only on `Ok`; `Err`/`Defect` pass
-   * through. A throw becomes a `Defect`.
+   * through. A throw becomes a `Defect`. An async callback is rejected at
+   * compile time ({@link NotThenable}).
    *
    * @typeParam K - the key the value is stored under.
    * @typeParam U - the value type.
    * @param name - the scope key.
    * @param f - computes a value from the accumulated scope.
    */
-  let<K extends string, U>(name: K, f: (scope: T) => U): Result$1<Bound<T, K, U>, E>;
+  let<K extends string, U>(name: K, f: (scope: T) => U & NotThenable<U>): Result$1<Bound<T, K, U>, E>;
   /**
    * Replace the success value with a constant `value`.
    *
@@ -119,12 +147,13 @@ type ResultMethods<T, E> = {
    * Transform the modeled error with `f`.
    *
    * Runs `f` only on `Err`; `Ok` passes through and a `Defect` is **never**
-   * touched. If `f` throws, the throw becomes a `Defect`.
+   * touched. If `f` throws, the throw becomes a `Defect`. An async callback is
+   * rejected at compile time ({@link NotThenable}).
    *
    * @typeParam E2 - the mapped error type.
    * @param f - maps the current error to a new one.
    */
-  mapErr<E2>(f: (error: E) => E2): Result$1<T, E2>;
+  mapErr<E2>(f: (error: E) => E2 & NotThenable<E2>): Result$1<T, E2>;
   /**
    * Recover from an `Err` by producing another `Result`.
    *
@@ -144,20 +173,24 @@ type ResultMethods<T, E> = {
    * The result type is `Result<T | U, never>`, but `never` describes only the
    * **error** channel — a `Defect` can still be present at runtime, so do not
    * read `never` as "total". Runs `f` only on `Err`; `Ok` and `Defect` pass
-   * through. If `f` throws, the throw becomes a `Defect`.
+   * through. If `f` throws, the throw becomes a `Defect`. An async callback is
+   * rejected at compile time ({@link NotThenable}).
    *
    * @typeParam U - the recovered success type.
    * @param f - produces a success value from the current error.
    */
-  recover<U>(f: (error: E) => U): Result$1<T | U, never>;
+  recover<U>(f: (error: E) => U & NotThenable<U>): Result$1<T | U, never>;
   /**
    * Run a side effect on the error and pass the `Result` through unchanged.
    *
-   * Runs only on `Err`. If `f` throws, the throw becomes a `Defect`.
+   * Runs only on `Err`. If `f` throws, the result is a `Defect` whose cause is
+   * an `AggregateError` of `[thrown, original failure]` — observing a failure
+   * never destroys it. An async callback is rejected at compile time
+   * ({@link NotThenable}).
    *
    * @param f - the side effect (its return value is ignored).
    */
-  tapErr(f: (error: E) => void): Result$1<T, E>;
+  tapErr<R>(f: (error: E) => R & NotThenable<R>): Result$1<T, E>;
   /**
    * Run a **failable** side effect on the error, keeping the original error but
    * threading the effect's own error.
@@ -167,9 +200,10 @@ type ResultMethods<T, E> = {
    * returns a `Result`, but its **success value is discarded** — on the effect's
    * `Ok` the original `Err` flows through unchanged, while an `Err` (or `Defect`)
    * from `f` short-circuits and threads its error (`Result<T, E | E2>`). Runs only
-   * on `Err`; `Ok` and `Defect` pass through. If `f` throws, the throw becomes a
-   * `Defect`. Use it for a failable effect _during_ error handling (e.g. writing
-   * the error to an audit log that may itself fail).
+   * on `Err`; `Ok` and `Defect` pass through. If `f` throws, the result is a
+   * `Defect` whose cause is an `AggregateError` of `[thrown, original failure]` —
+   * observing a failure never destroys it. Use it for a failable effect _during_
+   * error handling (e.g. writing the error to an audit log that may itself fail).
    *
    * @typeParam E2 - the error type the effect may introduce.
    * @param f - the failable side effect; its `Ok` value is ignored.
@@ -191,11 +225,14 @@ type ResultMethods<T, E> = {
   recoverDefect<U, E2>(f: (cause: unknown) => Result$1<U, E2>): Result$1<T | U, E | E2>;
   /**
    * Run a side effect on a present `Defect`'s cause (e.g. logging) and pass the
-   * `Defect` through unchanged. If `f` throws, the throw becomes a new `Defect`.
+   * `Defect` through unchanged. If `f` throws, the result is a `Defect` whose
+   * cause is an `AggregateError` of `[thrown, original failure]` — observing a
+   * failure never destroys it. An async callback is rejected at compile time
+   * ({@link NotThenable}).
    *
    * @param f - the side effect over the unknown cause.
    */
-  tapDefect(f: (cause: unknown) => void): Result$1<T, E>;
+  tapDefect<R>(f: (cause: unknown) => R & NotThenable<R>): Result$1<T, E>;
   /**
    * Exhaustively fold all three runtime states into a single value of type `R`.
    *
@@ -217,35 +254,51 @@ type ResultMethods<T, E> = {
   /**
    * Extract the success value.
    *
+   * @remarks
+   * Compiles only when the error channel is empty (`E = never`) — eliminate
+   * modeled errors first (`match` / `recover` / `orElse`), or reach for the
+   * `unwrapOr` / `unwrapOrElse` / `getOrNull` / `getOrUndefined` family (which
+   * recover an `Err`). If you get a `'this' context` type error here, that is
+   * the gate: the receiver still has a non-`never` error channel.
+   *
+   * `E = never` empties only the **modeled** error channel — a `Defect` can
+   * still be present, and `unwrap()` **rethrows its original cause** (it
+   * _panics_); `Result<T, never>` does not mean `unwrap()` cannot throw.
+   *
    * @returns the `Ok` value.
-   * @throws On `Err`, an {@link UnwrapError} carrying the error. On a `Defect`,
-   * re-throws the **original cause** with its original stack, so an unhandled
-   * Defect surfaces at the global handler as the real failure.
    */
-  unwrap(): T;
+  unwrap(this: Result$1<T, never>): T;
   /**
    * Extract the modeled error.
    *
+   * @remarks
+   * Compiles only when the success channel is empty (`T = never`) — eliminate
+   * the success case first. `T = never` is rarely the case in practice (a
+   * `Result` you hold usually still has a success type), so to inspect an
+   * error prefer an `isErr()` guard or, in tests, `@unthrown/vitest`'s
+   * `toBeErrWith`. A `Defect` still **rethrows its original cause** (a defect is
+   * a bug, not an absent value), so this does not mean `unwrapErr()` can't throw.
+   *
    * @returns the `Err` value.
-   * @throws On `Ok`, an {@link UnwrapError} carrying the value. On a `Defect`,
-   * re-throws the original cause.
    */
-  unwrapErr(): E;
+  unwrapErr(this: Result$1<never, E>): E;
   /**
    * The success value, or `fallback` on `Err`.
    *
-   * @param fallback - returned when the result is an `Err`.
+   * @typeParam U - the fallback type (may differ from `T`; the return widens to `T | U`).
+   * @param fallback - returned when the result is an `Err` (may be a different type; the return widens to `T | U`).
    * @throws Re-throws on a `Defect` — a Defect is a bug, not an absent value, so
    * it is never silently replaced.
    */
-  unwrapOr(fallback: T): T;
+  unwrapOr<U>(fallback: U): T | U;
   /**
    * The success value, or `f(error)` on `Err`.
    *
-   * @param f - lazily computes the fallback from the error.
+   * @typeParam U - the fallback type (may differ from `T`; the return widens to `T | U`).
+   * @param f - lazily computes the fallback from the error (may return a different type; the return widens to `T | U`).
    * @throws Re-throws on a `Defect`.
    */
-  unwrapOrElse(f: (error: E) => T): T;
+  unwrapOrElse<U>(f: (error: E) => U): T | U;
   /**
    * The success value, or `null` on `Err`.
    *
@@ -263,17 +316,58 @@ type ResultMethods<T, E> = {
   isDefect(): this is DefectView<T, E>; /** Lift this synchronous `Result` into an {@link AsyncResult}. */
   toAsync(): AsyncResult$1<T, E>;
 };
-/** The `Ok` variant of a {@link Result}: a success carrying a `value`. */
+/**
+ * The `Ok` variant of a {@link Result}: a success carrying a `value`. This is
+ * what a successful `isOk` guard narrows to, making `.value` reachable. It also
+ * carries the shared fluent surface ({@link ResultMethods}).
+ *
+ * @example
+ * ```ts
+ * if (r.isOk()) r.value; // r: OkView<T, E> here — .value is a T
+ * ```
+ *
+ * @category Types
+ */
 type OkView<T, E = never> = ResultMethods<T, E> & {
   readonly tag: "Ok";
   readonly value: T;
 };
-/** The `Err` variant of a {@link Result}: a modeled failure carrying an `error`. */
+/**
+ * The `Err` variant of a {@link Result}: a modeled failure carrying an `error`.
+ * This is what a successful `isErr` guard narrows to, exposing `.error`. It also
+ * carries the shared fluent surface ({@link ResultMethods}).
+ *
+ * @remarks
+ * **Note the parameter order: `ErrView<E, T>` puts the error type _first_** — the
+ * reverse of the `<T, E>` order used by {@link OkView}, {@link DefectView}, and
+ * {@link Result} — because `Result<T, E>` narrows to `ErrView<E, T>` (the error is
+ * the payload the guard makes reachable). You rarely write it by hand (a failed
+ * `isErr()` narrows to it for you); if you do, mind the flip — `ErrView<MyError,
+ * MyValue>`, not `ErrView<MyValue, MyError>`.
+ *
+ * @example
+ * ```ts
+ * if (r.isErr()) r.error; // r: ErrView<E, T> here — .error is an E
+ * ```
+ *
+ * @category Types
+ */
 type ErrView<E, T = never> = ResultMethods<T, E> & {
   readonly tag: "Err";
   readonly error: E;
 };
-/** The `Defect` variant of a {@link Result}: an unmodeled failure carrying a `cause`. */
+/**
+ * The `Defect` variant of a {@link Result}: an unmodeled failure carrying a
+ * `cause`. This is what a successful `isDefect` guard narrows to, exposing
+ * `.cause`. It also carries the shared fluent surface ({@link ResultMethods}).
+ *
+ * @example
+ * ```ts
+ * if (r.isDefect()) r.cause; // r: DefectView<T, E> here — .cause is `unknown`
+ * ```
+ *
+ * @category Types
+ */
 type DefectView<T = never, E = never> = ResultMethods<T, E> & {
   readonly tag: "Defect";
   readonly cause: unknown;
@@ -324,107 +418,233 @@ type Result$1<T, E> = OkView<T, E> | ErrView<E, T> | DefectView<T, E>;
  * An {@link AsyncResult}'s internal promise never rejects, so `await`-ing one
  * always yields a {@link Result} and never throws — there is no rejection
  * channel to model, and none is advertised. At runtime it is still a thenable
- * (the only way `await` can collapse it); the narrowing simply keeps it from
- * being treated as a raw promise (e.g. dropped into `Promise.all`).
+ * (the only way `await` can collapse it), and `Promise.all` / `Promise.resolve`
+ * will still adopt it — harmlessly, since it settles to a `Result` and never
+ * rejects. What the narrowing prevents is treating it as a full promise:
+ * `.catch()` / `.finally()` do not type-check, because there is no rejection to
+ * handle.
  *
  * @typeParam T - the value `await` resolves to.
+ *
+ * @category Types
  */
 type Awaitable<T> = {
   then<R = T>(onfulfilled?: ((value: T) => R | PromiseLike<R>) | null): PromiseLike<R>;
 };
 /**
- * The asynchronous counterpart of {@link Result}: an awaitable wrapper with the
- * same method surface, collapsing to a `Result<T, E>` when `await`-ed.
+ * The async method surface every {@link AsyncResult} carries — the combinators
+ * (`map`, `flatMap`, `mapErr`, `match`, `unwrap`, …) with their asynchronous
+ * signatures, documented one per entry below. The async mirror of
+ * {@link ResultMethods}: each entry links its synchronous counterpart and states
+ * only the async delta.
  *
  * @remarks
- * **Combinator callbacks are synchronous.** A raw `Promise` may never enter an
- * `AsyncResult` method — that would be an un-qualified async boundary, and its
- * rejection would silently become a `Defect`, skipping the triage that
- * {@link fromPromise} forces. To do further async work, re-enter through a
- * qualified boundary and compose it: `ar.flatMap((v) => fromPromise(work(v),
- * qualify))`. The eliminators (`unwrap`, …) return promises; the binds
- * (`flatMap`, `flatTap`, `orElse`, `recoverDefect`) additionally accept an
- * `AsyncResult`.
- *
- * To pattern-match an `AsyncResult`, `await` it first: `match(await ar)`.
+ * Like {@link ResultMethods}, this type exists to **document** the surface — not
+ * to be authored against; you obtain it by holding an `AsyncResult`. Its
+ * combinator callbacks are **synchronous** (a raw `Promise` may never enter — see
+ * the {@link AsyncResult} remarks); async work re-enters via {@link fromPromise}
+ * and composes with `flatMap`. Systematic differences from the sync surface: the
+ * binds return an `AsyncResult` (and additionally accept one), and the
+ * eliminators return a `Promise`.
  *
  * @typeParam T - the success value type.
  * @typeParam E - the modeled error type.
+ * @category Methods
  */
-type AsyncResult$1<T, E> = Awaitable<Result$1<T, E>> & {
-  /** Asynchronous `map`. `f` is synchronous; a throw becomes a `Defect`. */map<U>(f: (value: T) => U): AsyncResult$1<U, E>;
+type AsyncResultMethods<T, E> = {
   /**
-   * Asynchronous `flatMap`. `f` may return a `Result` **or** an `AsyncResult`
-   * (never a raw `Promise`); a throw becomes a `Defect`.
+   * Asynchronous {@link ResultMethods.map | map}: transforms the success value
+   * with `f`. `f` is synchronous; a throw becomes a `Defect`. An async callback
+   * is rejected at compile time ({@link NotThenable}).
    */
-  flatMap<U, E2>(f: (value: T) => Result$1<U, E2> | AsyncResult$1<U, E2>): AsyncResult$1<U, E | E2>; /** Asynchronous `tap`. `f` is synchronous; a throw becomes a `Defect`. */
-  tap(f: (value: T) => void): AsyncResult$1<T, E>;
+  map<U>(f: (value: T) => U & NotThenable<U>): AsyncResult$1<U, E>;
   /**
-   * Asynchronous `flatTap` — a failable tap that keeps the original value. `f`
-   * may return a `Result` **or** an `AsyncResult`; its `Ok` value is discarded,
-   * an `Err`/`Defect` short-circuits, and a throw becomes a `Defect`.
+   * Asynchronous {@link ResultMethods.flatMap | flatMap}. Unlike the sync form,
+   * `f` may return a `Result` **or** an `AsyncResult` (never a raw `Promise`); a
+   * throw becomes a `Defect`.
    */
-  flatTap<E2>(f: (value: T) => Result$1<unknown, E2> | AsyncResult$1<unknown, E2>): AsyncResult$1<T, E | E2>;
+  flatMap<U, E2>(f: (value: T) => Result$1<U, E2> | AsyncResult$1<U, E2>): AsyncResult$1<U, E | E2>;
   /**
-   * Asynchronous `bind` (do-notation). `f` may return a `Result` **or** an
-   * `AsyncResult`; its value is bound under `name` in the accumulating scope.
+   * Asynchronous {@link ResultMethods.tap | tap}. `f` is synchronous; a throw
+   * becomes a `Defect`. An async callback is rejected at compile time
+   * ({@link NotThenable}).
    */
-  bind<K extends string, U, E2>(name: K, f: (scope: T) => Result$1<U, E2> | AsyncResult$1<U, E2>): AsyncResult$1<Bound<T, K, U>, E | E2>; /** Asynchronous `let` (do-notation). `f` returns a plain value, bound under `name`. */
-  let<K extends string, U>(name: K, f: (scope: T) => U): AsyncResult$1<Bound<T, K, U>, E>; /** Asynchronous `as`. */
-  as<U>(value: U): AsyncResult$1<U, E>; /** Asynchronous `mapErr`. `f` is synchronous; a throw becomes a `Defect`. */
-  mapErr<E2>(f: (error: E) => E2): AsyncResult$1<T, E2>; /** Asynchronous `orElse`. `f` may return a `Result` or an `AsyncResult`. */
-  orElse<U, E2>(f: (error: E) => Result$1<U, E2> | AsyncResult$1<U, E2>): AsyncResult$1<T | U, E2>; /** Asynchronous `recover`. `f` is synchronous; a throw becomes a `Defect`. */
-  recover<U>(f: (error: E) => U): AsyncResult$1<T | U, never>; /** Asynchronous `tapErr`. `f` is synchronous; a throw becomes a `Defect`. */
-  tapErr(f: (error: E) => void): AsyncResult$1<T, E>;
+  tap<R>(f: (value: T) => R & NotThenable<R>): AsyncResult$1<T, E>;
   /**
-   * Asynchronous `flatTapErr` — a failable tap on the error that keeps the
-   * original error. `f` may return a `Result` **or** an `AsyncResult`; its `Ok`
-   * value is discarded, an `Err`/`Defect` from `f` threads through, and a throw
+   * Asynchronous {@link ResultMethods.flatTap | flatTap} — a failable tap that
+   * keeps the original value. `f` may return a `Result` **or** an `AsyncResult`;
+   * its `Ok` value is discarded, an `Err`/`Defect` short-circuits, and a throw
    * becomes a `Defect`.
    */
-  flatTapErr<E2>(f: (error: E) => Result$1<unknown, E2> | AsyncResult$1<unknown, E2>): AsyncResult$1<T, E | E2>; /** Asynchronous `recoverDefect`. `f` may return a `Result` or an `AsyncResult`. */
-  recoverDefect<U, E2>(f: (cause: unknown) => Result$1<U, E2> | AsyncResult$1<U, E2>): AsyncResult$1<T | U, E | E2>; /** Asynchronous `tapDefect`. */
-  tapDefect(f: (cause: unknown) => void): AsyncResult$1<T, E>; /** Asynchronous `match`. Handlers are synchronous; resolves to `R`. */
+  flatTap<E2>(f: (value: T) => Result$1<unknown, E2> | AsyncResult$1<unknown, E2>): AsyncResult$1<T, E | E2>;
+  /**
+   * Asynchronous {@link ResultMethods.bind | bind} (do-notation). `f` may return
+   * a `Result` **or** an `AsyncResult`; its value is bound under `name` in the
+   * accumulating scope.
+   */
+  bind<K extends string, U, E2>(name: K, f: (scope: T) => Result$1<U, E2> | AsyncResult$1<U, E2>): AsyncResult$1<Bound<T, K, U>, E | E2>;
+  /**
+   * Asynchronous {@link ResultMethods.let | let} (do-notation). `f` returns a
+   * plain value, bound under `name`. An async callback is rejected at compile
+   * time ({@link NotThenable}).
+   */
+  let<K extends string, U>(name: K, f: (scope: T) => U & NotThenable<U>): AsyncResult$1<Bound<T, K, U>, E>; /** Asynchronous {@link ResultMethods.as | as}: replaces the value with `value`. */
+  as<U>(value: U): AsyncResult$1<U, E>;
+  /**
+   * Asynchronous {@link ResultMethods.mapErr | mapErr}. `f` is synchronous; a
+   * throw becomes a `Defect`. An async callback is rejected at compile time
+   * ({@link NotThenable}).
+   */
+  mapErr<E2>(f: (error: E) => E2 & NotThenable<E2>): AsyncResult$1<T, E2>;
+  /**
+   * Asynchronous {@link ResultMethods.orElse | orElse}. `f` may return a `Result`
+   * or an `AsyncResult`.
+   */
+  orElse<U, E2>(f: (error: E) => Result$1<U, E2> | AsyncResult$1<U, E2>): AsyncResult$1<T | U, E2>;
+  /**
+   * Asynchronous {@link ResultMethods.recover | recover}. `f` is synchronous; a
+   * throw becomes a `Defect`. An async callback is rejected at compile time
+   * ({@link NotThenable}).
+   */
+  recover<U>(f: (error: E) => U & NotThenable<U>): AsyncResult$1<T | U, never>;
+  /**
+   * Asynchronous {@link ResultMethods.tapErr | tapErr}. `f` is synchronous; if it
+   * throws, the result is a `Defect` whose cause is an `AggregateError` of
+   * `[thrown, original failure]` — observing a failure never destroys it. An
+   * async callback is rejected at compile time ({@link NotThenable}).
+   */
+  tapErr<R>(f: (error: E) => R & NotThenable<R>): AsyncResult$1<T, E>;
+  /**
+   * Asynchronous {@link ResultMethods.flatTapErr | flatTapErr} — the
+   * error-channel mirror of `flatTap`. `f` may return a `Result` **or** an
+   * `AsyncResult`; its `Ok` value is discarded, an `Err`/`Defect` from `f`
+   * threads through, and if `f` throws, the result is a `Defect` whose cause is
+   * an `AggregateError` of `[thrown, original failure]` — observing a failure
+   * never destroys it.
+   */
+  flatTapErr<E2>(f: (error: E) => Result$1<unknown, E2> | AsyncResult$1<unknown, E2>): AsyncResult$1<T, E | E2>;
+  /**
+   * Asynchronous {@link ResultMethods.recoverDefect | recoverDefect}. `f` may
+   * return a `Result` or an `AsyncResult`.
+   */
+  recoverDefect<U, E2>(f: (cause: unknown) => Result$1<U, E2> | AsyncResult$1<U, E2>): AsyncResult$1<T | U, E | E2>;
+  /**
+   * Asynchronous {@link ResultMethods.tapDefect | tapDefect}. If `f` throws, the
+   * result is a `Defect` whose cause is an `AggregateError` of `[thrown,
+   * original failure]` — observing a failure never destroys it. An async
+   * callback is rejected at compile time ({@link NotThenable}).
+   */
+  tapDefect<R>(f: (cause: unknown) => R & NotThenable<R>): AsyncResult$1<T, E>;
+  /**
+   * Asynchronous {@link ResultMethods.match | match}. Handlers are synchronous;
+   * resolves to a `Promise<R>`.
+   */
   match<R>(cases: {
     ok: (value: T) => R;
     err: (error: E) => R;
     defect: (cause: unknown) => R;
-  }): Promise<R>; /** Asynchronous `unwrap`. The returned promise rejects on `Err`/`Defect`. */
-  unwrap(): Promise<T>; /** Asynchronous `unwrapErr`. */
-  unwrapErr(): Promise<E>; /** Asynchronous `unwrapOr`. */
-  unwrapOr(fallback: T): Promise<T>; /** Asynchronous `unwrapOrElse`. */
-  unwrapOrElse(f: (error: E) => T): Promise<T>; /** Asynchronous `getOrNull`. */
-  getOrNull(): Promise<T | null>; /** Asynchronous `getOrUndefined`. */
+  }): Promise<R>;
+  /**
+   * Asynchronous {@link ResultMethods.unwrap | unwrap}. Compiles only when the
+   * error channel is empty (`this: AsyncResult<T, never>`); the returned promise
+   * rejects on a `Defect` (rethrowing its cause).
+   */
+  unwrap(this: AsyncResult$1<T, never>): Promise<T>;
+  /**
+   * Asynchronous {@link ResultMethods.unwrapErr | unwrapErr}. Compiles only when
+   * the success channel is empty (`this: AsyncResult<never, E>`); the returned
+   * promise rejects on a `Defect` (rethrowing its cause).
+   */
+  unwrapErr(this: AsyncResult$1<never, E>): Promise<E>; /** Asynchronous {@link ResultMethods.unwrapOr | unwrapOr}. */
+  unwrapOr<U>(fallback: U): Promise<T | U>; /** Asynchronous {@link ResultMethods.unwrapOrElse | unwrapOrElse}. */
+  unwrapOrElse<U>(f: (error: E) => U): Promise<T | U>; /** Asynchronous {@link ResultMethods.getOrNull | getOrNull}. */
+  getOrNull(): Promise<T | null>; /** Asynchronous {@link ResultMethods.getOrUndefined | getOrUndefined}. */
   getOrUndefined(): Promise<T | undefined>;
 };
 /**
- * Extract the success type `T` from a `Result`.
+ * The asynchronous counterpart of {@link Result}: an awaitable wrapper carrying
+ * the {@link AsyncResultMethods} surface, collapsing to a `Result<T, E>` when
+ * `await`-ed.
+ *
+ * @remarks
+ * **Combinator callbacks are synchronous.** A raw `Promise` may never enter an
+ * `AsyncResult` method — that would be an un-qualified async boundary, and its
+ * rejection would silently become a `Defect`, skipping the triage that
+ * {@link fromPromise} forces. To do further async work, re-enter through a
+ * qualified boundary and compose it: `ar.flatMap((v) => fromPromise(work(v),
+ * qualify))`. The eliminators (`unwrap`, …) return promises; the binds
+ * (`flatMap`, `flatTap`, `orElse`, `recoverDefect`) additionally accept an
+ * `AsyncResult`. Its combinators are documented one per entry on
+ * {@link AsyncResultMethods}.
+ *
+ * To pattern-match an `AsyncResult`, `await` it first: `match(await ar)`.
+ *
+ * @typeParam T - the success value type.
+ * @typeParam E - the modeled error type.
+ */
+type AsyncResult$1<T, E> = Awaitable<Result$1<T, E>> & AsyncResultMethods<T, E>;
+/**
+ * Extract the success type `T` from a `Result` type — derive one type from
+ * another instead of restating it (e.g. the payload a function returns).
  *
  * @typeParam R - the `Result` type to inspect.
+ *
+ * @example
+ * ```ts
+ * type R = Result<User, NotFound>;
+ * type U = OkOf<R>; // User
+ * type E = ErrOf<R>; // NotFound
+ * ```
+ *
+ * @category Types
  */
 type OkOf<R> = R extends {
   readonly tag: "Ok";
   readonly value: infer T;
 } ? T : never;
 /**
- * Extract the error type `E` from a `Result`.
+ * Extract the error type `E` from a `Result` type — the counterpart of
+ * {@link OkOf}.
  *
  * @typeParam R - the `Result` type to inspect.
+ *
+ * @example
+ * ```ts
+ * type E = ErrOf<Result<User, NotFound>>; // NotFound
+ * ```
+ *
+ * @category Types
  */
 type ErrOf<R> = R extends {
   readonly tag: "Err";
   readonly error: infer E;
 } ? E : never;
 /**
- * Extract the success type `T` from an {@link AsyncResult}.
+ * Extract the success type `T` from an {@link AsyncResult} type — the async
+ * counterpart of {@link OkOf}.
  *
  * @typeParam R - the `AsyncResult` type to inspect.
+ *
+ * @example
+ * ```ts
+ * type T = AsyncOkOf<AsyncResult<User, NotFound>>; // User
+ * ```
+ *
+ * @category Types
  */
 type AsyncOkOf<R> = R extends AsyncResult$1<infer T, unknown> ? T : never;
 /**
- * Extract the error type `E` from an {@link AsyncResult}.
+ * Extract the error type `E` from an {@link AsyncResult} type — the async
+ * counterpart of {@link ErrOf}.
  *
  * @typeParam R - the `AsyncResult` type to inspect.
+ *
+ * @example
+ * ```ts
+ * type E = AsyncErrOf<AsyncResult<User, NotFound>>; // NotFound
+ * ```
+ *
+ * @category Types
  */
 type AsyncErrOf<R> = R extends AsyncResult$1<unknown, infer E> ? E : never;
 //#endregion
@@ -438,8 +658,12 @@ type AsyncErrOf<R> = R extends AsyncResult$1<unknown, infer E> ? E : never;
  * @example
  * ```ts
  * import { Ok } from "unthrown";
- * Ok(42).unwrap(); // 42
+ *
+ * Ok(2).map((n) => n + 1); // => Ok(3)
+ * Ok(42).unwrap(); // => 42
  * ```
+ *
+ * @category Constructors
  */
 declare function Ok<T>(value: T): Result$1<T, never>;
 /**
@@ -451,8 +675,12 @@ declare function Ok<T>(value: T): Result$1<T, never>;
  * @example
  * ```ts
  * import { Err } from "unthrown";
- * Err("not_found").unwrapErr(); // "not_found"
+ *
+ * Err("not_found").map((n) => n + 1); // => Err("not_found") (map skipped)
+ * Err("not_found").unwrapErr(); // => "not_found"
  * ```
+ *
+ * @category Constructors
  */
 declare function Err<E>(error: E): Result$1<never, E>;
 /**
@@ -462,22 +690,61 @@ declare function Err<E>(error: E): Result$1<never, E>;
  *
  * @example
  * ```ts
- * import { isOk, type Result } from "unthrown";
+ * import { isOk, Ok, Err, type Result } from "unthrown";
+ *
+ * isOk(Ok(1)); // => true
+ * isOk(Err("boom")); // => false
+ *
  * declare const r: Result<number, string>;
  * if (isOk(r)) r.value; // number, narrowed
  * ```
+ *
+ * @category Guards
  */
 declare function isOk<T, E>(r: Result$1<T, E>): r is OkView<T, E>;
 /**
  * Type guard: narrow a {@link Result} to its `Err` variant, exposing `.error`.
  *
  * @returns `true` when `r` is `Err`.
+ *
+ * @example
+ * ```ts
+ * import { isErr, Ok, Err, type Result } from "unthrown";
+ *
+ * isErr(Err("boom")); // => true
+ * isErr(Ok(1)); // => false
+ *
+ * declare const r: Result<number, string>;
+ * if (isErr(r)) r.error; // string, narrowed
+ * ```
+ *
+ * @category Guards
  */
 declare function isErr<T, E>(r: Result$1<T, E>): r is ErrView<E, T>;
 /**
  * Type guard: narrow a {@link Result} to its `Defect` variant, exposing `.cause`.
  *
+ * @remarks
+ * A `Defect` has no public constructor — it only arises at a boundary (e.g. a
+ * callback throwing inside a combinator). This guard is how you detect one.
+ *
  * @returns `true` when `r` is a `Defect`.
+ *
+ * @example
+ * ```ts
+ * import { isDefect, Ok } from "unthrown";
+ *
+ * // A throw inside a combinator is captured as a Defect:
+ * const r = Ok(1).map(() => {
+ *   throw new Error("boom");
+ * });
+ * isDefect(r); // => true
+ * isDefect(Ok(1)); // => false
+ *
+ * if (isDefect(r)) r.cause; // unknown, narrowed
+ * ```
+ *
+ * @category Guards
  */
 declare function isDefect<T, E>(r: Result$1<T, E>): r is DefectView<T, E>;
 //#endregion
@@ -496,7 +763,14 @@ declare function isDefect<T, E>(r: Result$1<T, E>): r is DefectView<T, E>;
  * A `Defect` is never wrapped in an `UnwrapError`: its original cause is
  * re-thrown (with its original stack) instead.
  *
+ * `unwrap()` and `unwrapErr()` are type-gated (`this: Result<T, never>` /
+ * `Result<never, E>`), so the wrong-variant branch that throws this is
+ * unreachable through well-typed code — it remains only as a defensive guard
+ * against unsound runtime misuse (e.g. an `as` cast past the gate).
+ *
  * @typeParam E - the type of the {@link UnwrapError.error} it carries.
+ *
+ * @category Errors
  */
 declare class UnwrapError<E = unknown> extends Error {
   /**
@@ -517,6 +791,20 @@ declare class UnwrapError<E = unknown> extends Error {
  * is not a `Result` and returns `false`.
  *
  * @returns `true` when `x` is a `Result` produced by this library.
+ *
+ * @example
+ * ```ts
+ * import { isResult, Ok } from "unthrown";
+ *
+ * isResult(Ok(1)); // => true
+ * isResult({ tag: "Ok" }); // => false (look-alike, wrong prototype)
+ * isResult(Ok(1).toAsync()); // => false (an AsyncResult is not a Result)
+ *
+ * const x: unknown = Ok(1);
+ * if (isResult(x)) x.match({ ok: () => 1, err: () => 0, defect: () => -1 });
+ * ```
+ *
+ * @category Guards
  */
 declare function isResult(x: unknown): x is Result$1<unknown, unknown>;
 //#endregion
@@ -542,6 +830,24 @@ declare function isResult(x: unknown): x is Result$1<unknown, unknown>;
  *   .map(({ user, org, label }) => render(user, org, label));
  * // Result<View, NotFound>
  * ```
+ *
+ * @example
+ * ```ts
+ * import { Do, Ok, Err } from "unthrown";
+ *
+ * // Ok path — the scope accumulates:
+ * Do()
+ *   .bind("a", () => Ok(2))
+ *   .let("b", ({ a }) => a * 10)
+ *   .map(({ a, b }) => a + b); // => Ok(22)
+ *
+ * // Err path — the first Err short-circuits the rest:
+ * Do()
+ *   .bind("a", () => Err("boom"))
+ *   .let("b", ({ a }) => a); // => Err("boom")
+ * ```
+ *
+ * @category Do-notation
  */
 declare function Do(): Result$1<{}, never>;
 //#endregion
@@ -580,10 +886,16 @@ type Defect = {
  * @param value - the possibly-absent value.
  * @param onAbsent - lazily produces the error for the absent case.
  *
+ * @category Interop
+ *
  * @example
  * ```ts
  * import { fromNullable } from "unthrown";
- * fromNullable(map.get(key), () => "missing").unwrap();
+ *
+ * const map = new Map([["a", 1]]);
+ * fromNullable(map.get("a"), () => "absent").unwrapOr(0); // => 1
+ * fromNullable(map.get("z"), () => "absent"); // => Err("absent")
+ * fromNullable(0, () => "absent").unwrapOr(-1); // => 0 (falsy but present)
  * ```
  */
 declare function fromNullable<T, E>(value: T | null | undefined, onAbsent: () => E): Result$1<NonNullable<T>, E>;
@@ -612,11 +924,21 @@ declare function fromNullable<T, E>(value: T | null | undefined, onAbsent: () =>
  * unmodeled by returning `defect(cause)` (the helper passed as its second arg).
  * @returns a function with the same arguments returning `Result<T, E>`.
  *
+ * @category Interop
+ *
  * @example
  * ```ts
  * import { fromThrowable } from "unthrown";
- * const parse = fromThrowable(JSON.parse, (cause, defect) => defect(cause));
- * parse("{}").unwrap();
+ *
+ * // Model the parse failure as an `Err`, everything unexpected as a `Defect`.
+ * const parse = fromThrowable(
+ *   (text: string) => JSON.parse(text) as unknown,
+ *   (cause, defect) =>
+ *     cause instanceof SyntaxError ? ("invalid_json" as const) : defect(cause),
+ * );
+ *
+ * parse('{"ok":true}').unwrapOr(null); // => { ok: true }
+ * parse("nope"); // => Err("invalid_json")
  * ```
  */
 declare function fromThrowable<A extends unknown[], T, R>(fn: (...args: A) => T, qualify: (cause: unknown, defect: (cause: unknown) => Defect) => R): (...args: A) => Result$1<T, Exclude<R, Defect>>;
@@ -642,12 +964,19 @@ declare function fromThrowable<A extends unknown[], T, R>(fn: (...args: A) => T,
  * @param qualify - triages a rejection `cause` into a modeled `E`, or marks it
  * unmodeled by returning `defect(cause)` (the helper passed as its second arg).
  *
+ * @category Interop
+ *
  * @example
  * ```ts
  * import { fromPromise } from "unthrown";
+ *
+ * // A rejection with a NotFoundError becomes a modeled `Err`; anything else a Defect.
  * const user = await fromPromise(fetchUser(id), (cause, defect) =>
  *   cause instanceof NotFoundError ? ("not_found" as const) : defect(cause),
  * );
+ *
+ * if (user.isOk()) user.value; // => the fetched user
+ * // when fetchUser rejects with NotFoundError: user is Err("not_found")
  * ```
  */
 declare function fromPromise<T, R>(promise: Promise<T> | (() => Promise<T>), qualify: (cause: unknown, defect: (cause: unknown) => Defect) => R): AsyncResult$1<T, Exclude<R, Defect>>;
@@ -662,6 +991,17 @@ declare function fromPromise<T, R>(promise: Promise<T> | (() => Promise<T>), qua
  *
  * @typeParam T - the resolved value type.
  * @param promise - the promise, or a thunk returning one.
+ *
+ * @category Interop
+ *
+ * @example
+ * ```ts
+ * import { fromSafePromise } from "unthrown";
+ *
+ * (await fromSafePromise(Promise.resolve(3))).unwrap(); // => 3
+ * // a rejection becomes a Defect (never a modeled Err):
+ * await fromSafePromise(Promise.reject(new Error("boom"))); // => Defect(Error("boom"))
+ * ```
  */
 declare function fromSafePromise<T>(promise: Promise<T> | (() => Promise<T>)): AsyncResult$1<T, never>;
 /**
@@ -698,11 +1038,14 @@ type AsyncResultRecord = Record<string, AsyncResult$1<unknown, unknown>>;
  * collapses to `Result<T[], E>` with no cast. For a **record** keyed by name,
  * use {@link allFromDict}.
  *
+ * @category Aggregate
+ *
  * @example
  * ```ts
- * import { all, Ok } from "unthrown";
- * all([Ok(1), Ok("a"), Ok(true)]).unwrap(); // [1, "a", true] (typed [number, string, boolean])
- * all([Ok(1), Ok(2)] as Result<number, never>[]).unwrap(); // number[]
+ * import { all, Ok, Err } from "unthrown";
+ *
+ * all([Ok(1), Ok("a"), Ok(true)]).unwrap(); // => [1, "a", true] (typed [number, string, boolean])
+ * all([Ok(1), Err("e"), Ok(3)]); // => Err("e") (short-circuits on the first Err)
  * ```
  */
 declare function all<Rs extends readonly Result$1<unknown, unknown>[]>(results: readonly [...Rs]): Result$1<AllOk<Rs, { [K in keyof Rs]: OkOf<Rs[K]> }>, ErrOf<Rs[number]>>;
@@ -716,10 +1059,14 @@ declare function all<Rs extends readonly Result$1<unknown, unknown>[]>(results:
  * Same folding rules as {@link all}: first `Err` short-circuits, any `Defect`
  * dominates. This is **not** error accumulation.
  *
+ * @category Aggregate
+ *
  * @example
  * ```ts
- * import { allFromDict, Ok } from "unthrown";
- * allFromDict({ id: Ok(1), name: Ok("ada") }).unwrap(); // { id: 1, name: "ada" }
+ * import { allFromDict, Ok, Err } from "unthrown";
+ *
+ * allFromDict({ id: Ok(1), name: Ok("ada") }).unwrap(); // => { id: 1, name: "ada" }
+ * allFromDict({ id: Ok(1), name: Err("missing") }); // => Err("missing")
  * ```
  */
 declare function allFromDict<R extends ResultRecord>(results: R): Result$1<{ [K in keyof R]: OkOf<R[K]> }, ErrOf<R[keyof R]>>;
@@ -733,10 +1080,14 @@ declare function allFromDict<R extends ResultRecord>(results: R): Result$1<{ [K
  * short-circuits, any `Defect` dominates. As ever, the returned `AsyncResult`'s
  * internal promise never rejects. For a **record**, use {@link allFromDictAsync}.
  *
+ * @category Aggregate
+ *
  * @example
  * ```ts
  * import { allAsync, fromSafePromise } from "unthrown";
- * await allAsync([fromSafePromise(a()), fromSafePromise(b())]);
+ *
+ * const both = allAsync([fromSafePromise(Promise.resolve(1)), fromSafePromise(Promise.resolve(2))]);
+ * (await both).unwrap(); // => [1, 2]
  * ```
  */
 declare function allAsync<Rs extends readonly AsyncResult$1<unknown, unknown>[]>(results: readonly [...Rs]): AsyncResult$1<AllOk<Rs, { [K in keyof Rs]: AsyncOkOf<Rs[K]> }>, AsyncErrOf<Rs[number]>>;
@@ -748,10 +1099,17 @@ declare function allAsync<Rs extends readonly AsyncResult$1<unknown, unknown>[]>
  * Resolved concurrently (order preserved), folded with the {@link all} rules,
  * and the internal promise never rejects.
  *
+ * @category Aggregate
+ *
  * @example
  * ```ts
  * import { allFromDictAsync, fromSafePromise } from "unthrown";
- * await allFromDictAsync({ a: fromSafePromise(a()), b: fromSafePromise(b()) });
+ *
+ * const both = allFromDictAsync({
+ *   a: fromSafePromise(Promise.resolve(1)),
+ *   b: fromSafePromise(Promise.resolve("x")),
+ * });
+ * (await both).unwrap(); // => { a: 1, b: "x" }
  * ```
  */
 declare function allFromDictAsync<R extends AsyncResultRecord>(results: R): AsyncResult$1<{ [K in keyof R]: AsyncOkOf<R[K]> }, AsyncErrOf<R[keyof R]>>;
@@ -774,10 +1132,12 @@ declare function allFromDictAsync<R extends AsyncResultRecord>(results: R): Asyn
  * (`AsyncResult.fromPromise`, `AsyncResult.all`, …), grouped by what they
  * return — a static lives in exactly one namespace.
  *
+ * @category Facade
+ *
  * @example
  * ```ts
  * import { Result } from "unthrown";
- * Result.Ok(1).flatMap((n) => Result.Ok(n + 1)).unwrap(); // 2
+ * Result.Ok(1).flatMap((n) => Result.Ok(n + 1)).unwrap(); // => 2
  * ```
  */
 declare const Result: {
@@ -793,6 +1153,20 @@ declare const Result: {
   readonly isDefect: typeof isDefect;
   readonly isResult: typeof isResult;
 };
+/**
+ * `Result<T, E>` — the core discriminated union. Shares its name with the
+ * {@link Result | companion object} above (the value and type are one name); this
+ * is the type half.
+ *
+ * @remarks
+ * A `Result` is a discriminated union, so TypeDoc can't list its methods on this
+ * alias. Its fluent combinators (`map`, `flatMap`, `match`, `unwrap`, …) are
+ * documented one per entry on {@link ResultMethods} — the shared method surface
+ * every variant carries. For "which one do I reach for?", see the
+ * [Choosing a combinator](/guide/choosing-a-combinator) guide.
+ *
+ * @category Facade
+ */
 type Result<T, E> = Result$1<T, E>;
 /**
  * Companion object grouping the **`AsyncResult`-producing** entry points under
@@ -809,10 +1183,13 @@ type Result<T, E> = Result$1<T, E>;
  * {@link Result}, the free functions remain the primary, tree-shakeable API; the
  * value `AsyncResult` and the type {@link AsyncResult} share one name.
  *
+ * @category Facade
+ *
  * @example
  * ```ts
  * import { AsyncResult } from "unthrown";
  * const user = await AsyncResult.fromPromise(fetchUser(id), (c, defect) => defect(c));
+ * user.unwrap(); // => the fetched user (on success)
  * ```
  */
 declare const AsyncResult: {
@@ -821,6 +1198,19 @@ declare const AsyncResult: {
   readonly all: typeof allAsync;
   readonly allFromDict: typeof allFromDictAsync;
 };
+/**
+ * `AsyncResult<T, E>` — the async counterpart of {@link Result}. Shares its name
+ * with the {@link AsyncResult | companion object} above (value and type are one
+ * name); this is the type half.
+ *
+ * @remarks
+ * `AsyncResult` carries the async fluent surface; its combinators (`map`,
+ * `flatMap`, `match`, `unwrap`, …) are documented one per entry — with their
+ * async signatures — on {@link AsyncResultMethods}. For "which one do I reach
+ * for?", see the [Choosing a combinator](/guide/choosing-a-combinator) guide.
+ *
+ * @category Facade
+ */
 type AsyncResult<T, E> = AsyncResult$1<T, E>;
 //#endregion
 //#region src/tagged.d.ts
@@ -831,8 +1221,10 @@ type Props = Record<string, unknown>;
  *
  * @typeParam Tag - the string literal discriminant.
  * @typeParam A - the payload object type.
+ *
+ * @category Types
  */
-type TaggedErrorInstance<Tag extends string, A extends Props> = Error & Readonly<A> & {
+type TaggedErrorInstance<Tag extends string, A extends Props> = Error & Readonly<Omit<A, "name" | "message">> & {
   readonly _tag: Tag;
 };
 /**
@@ -841,12 +1233,23 @@ type TaggedErrorInstance<Tag extends string, A extends Props> = Error & Readonly
  *
  * @remarks
  * When the payload is empty, the constructor takes **no** arguments (the
- * `keyof A extends never ? void : A` trick); otherwise it takes the payload.
+ * `keyof A extends never ? void : A` trick); otherwise it takes the payload. The
+ * `name` and `message` keys are both **rejected** (`name?: never` /
+ * `message?: never`) because both are reserved: `name` is the display label, and
+ * `message` is the human string owned by `Error`. Set the message the standard
+ * way — `override message = "…"` (or a constructor override) on the subclass —
+ * never as a free-form per-call payload field. The reservations are enforced at
+ * the call site, mirroring how {@link TaggedErrorInstance} excludes both.
  *
  * @typeParam Tag - the string literal discriminant.
+ *
+ * @category Types
  */
 type TaggedErrorConstructor<Tag extends string> = {
-  new <A extends Props = {}>(args: keyof A extends never ? void : A): TaggedErrorInstance<Tag, A>;
+  new <A extends Props = {}>(args: keyof A extends never ? void : A & {
+    readonly name?: never;
+    readonly message?: never;
+  }): TaggedErrorInstance<Tag, A>;
 };
 /**
  * Build a base class for a tagged error — a class extending `Error` with a
@@ -854,9 +1257,17 @@ type TaggedErrorConstructor<Tag extends string> = {
  *
  * @remarks
  * Extend the returned class to declare a concrete error. Supply the payload with
- * an instantiation expression; omit it for a payload-less error. A `message`
- * field in the payload is forwarded to `Error`. The `_tag` always reflects
- * `tag` and cannot be overridden by the payload.
+ * an instantiation expression; omit it for a payload-less error. The `message`
+ * is **not** a payload field — it is the human string owned by `Error`, not
+ * structured data, so it is reserved. Define it once per subclass the standard
+ * way, `override message = "…"` (it may interpolate the payload via `this`,
+ * which the base populates before the subclass field initialiser runs); a
+ * payload `message` is rejected at compile time, so contextual detail lives in
+ * typed fields, never baked into per-call prose. The `_tag` always reflects
+ * `tag` and cannot be overridden by the payload. `name` is likewise reserved —
+ * it is the display label (set it with `options.name`); a payload `name` is
+ * rejected at compile time (and excluded from the instance type), so it can't
+ * shadow `Error.name`.
  *
  * `_tag` is the discriminant used by {@link matchTags}; `Error.name` is the
  * human-facing label in stack traces and logs. By default they coincide, but
@@ -867,11 +1278,14 @@ type TaggedErrorConstructor<Tag extends string> = {
  * ```ts
  * class RetryableError extends TaggedError("@my-lib/RetryableError", {
  *   name: "RetryableError",
- * })<{ message: string }> {}
+ * }) {
+ *   override message = "operation failed; safe to retry";
+ * }
  *
- * const e = new RetryableError({ message: "boom" });
- * e._tag; // "@my-lib/RetryableError" — namespaced discriminant
- * e.name; // "RetryableError"          — clean display name
+ * const e = new RetryableError();
+ * e._tag;    // "@my-lib/RetryableError" — namespaced discriminant
+ * e.name;    // "RetryableError"          — clean display name
+ * e.message; // "operation failed; safe to retry" — the standard Error.message
  * ```
  *
  * @typeParam Tag - the string literal discriminant.
@@ -879,13 +1293,15 @@ type TaggedErrorConstructor<Tag extends string> = {
  * @param options - optional overrides. `options.name` sets `Error.name`
  * independently of `tag` (defaults to `tag`).
  *
+ * @category Tagged errors
+ *
  * @example
  * ```ts
  * class NotFound extends TaggedError("NotFound") {}
  * class HttpError extends TaggedError("HttpError")<{ status: number }> {}
  *
- * new NotFound()._tag; // "NotFound"
- * new HttpError({ status: 500 }).status; // 500
+ * new NotFound()._tag; // => "NotFound"
+ * new HttpError({ status: 500 }).status; // => 500
  * ```
  */
 declare function TaggedError<Tag extends string>(tag: Tag, options?: {
@@ -899,6 +1315,8 @@ declare function TaggedError<Tag extends string>(tag: Tag, options?: {
  * @typeParam T - the success value type.
  * @typeParam E - the tagged error union.
  * @typeParam R - the folded result type.
+ *
+ * @category Types
  */
 type TagHandlers<T, E extends {
   _tag: string;
@@ -908,6 +1326,14 @@ type TagHandlers<T, E extends {
 } & { [K in E["_tag"]]: (error: Extract<E, {
   _tag: K;
 }>) => R };
+/**
+ * The channel-handler names are reserved: an error tag named `"Ok"` or
+ * `"Defect"` would collide with them inside {@link TagHandlers}, so
+ * {@link matchTags} rejects such unions at the call site.
+ *
+ * @internal
+ */
+type ReservedTagError = 'unthrown: error tags "Ok" and "Defect" are reserved by matchTags — rename the colliding tag (TaggedError\'s options.name can keep the display name)';
 /**
  * Exhaustively fold a {@link Result} (or {@link AsyncResult}) whose error type is
  * a tagged union, dispatching each error to the handler matching its `_tag`.
@@ -916,7 +1342,10 @@ type TagHandlers<T, E extends {
  * The `handlers` object must provide `Ok`, `Defect`, and exactly one function
  * per error tag; each tag's handler receives the narrowed error variant. A
  * missing tag is a compile error. For an `AsyncResult`, the fold resolves to a
- * `Promise<R>`.
+ * `Promise<R>`. At runtime, an error whose `_tag` has no handler (possible only
+ * outside the typed contract) is routed to the `Defect` handler — an unmodeled
+ * tag is an unmodeled failure. Tags named `"Ok"` or `"Defect"` are rejected at
+ * compile time.
  *
  * @typeParam T - the success value type.
  * @typeParam E - the tagged error union (`E extends { _tag: string }`).
@@ -924,26 +1353,33 @@ type TagHandlers<T, E extends {
  * @param result - the result to fold.
  * @param handlers - one branch per channel/tag.
  *
+ * @category Tagged errors
+ *
  * @example
  * ```ts
+ * import { Ok, Err, matchTags, TaggedError, type Result } from "unthrown";
+ *
  * class NotFound extends TaggedError("NotFound") {}
  * class Forbidden extends TaggedError("Forbidden")<{ user: string }> {}
  *
- * declare const r: Result<number, NotFound | Forbidden>;
- * matchTags(r, {
- *   Ok: (n) => `got ${n}`,
- *   Defect: (cause) => `bug: ${String(cause)}`,
- *   NotFound: () => "404",
- *   Forbidden: (e) => `403 for ${e.user}`,
- * });
+ * const fold = (r: Result<number, NotFound | Forbidden>) =>
+ *   matchTags(r, {
+ *     Ok: (n) => `got ${n}`,
+ *     Defect: (cause) => `bug: ${String(cause)}`,
+ *     NotFound: () => "404",
+ *     Forbidden: (e) => `403 for ${e.user}`,
+ *   });
+ *
+ * fold(Ok(1)); // => "got 1"
+ * fold(Err(new Forbidden({ user: "ada" }))); // => "403 for ada"
  * ```
  */
 declare function matchTags<T, E extends {
   _tag: string;
-}, R>(result: Result$1<T, E>, handlers: TagHandlers<T, E, R>): R;
+}, R>(result: Result$1<T, E>, handlers: TagHandlers<T, E, R> & ([Extract<E["_tag"], "Ok" | "Defect">] extends [never] ? unknown : ReservedTagError)): R;
 declare function matchTags<T, E extends {
   _tag: string;
-}, R>(result: AsyncResult$1<T, E>, handlers: TagHandlers<T, E, R>): Promise<R>;
+}, R>(result: AsyncResult$1<T, E>, handlers: TagHandlers<T, E, R> & ([Extract<E["_tag"], "Ok" | "Defect">] extends [never] ? unknown : ReservedTagError)): Promise<R>;
 //#endregion
-export { type AsyncErrOf, type AsyncOkOf, AsyncResult, type Awaitable, type DefectView, Do, Err, type ErrOf, type ErrView, Ok, type OkOf, type OkView, Result, type TagHandlers, TaggedError, type TaggedErrorConstructor, type TaggedErrorInstance, UnwrapError, all, allAsync, allFromDict, allFromDictAsync, fromNullable, fromPromise, fromSafePromise, fromThrowable, isDefect, isErr, isOk, isResult, matchTags };
+export { type AsyncErrOf, type AsyncOkOf, AsyncResult, type AsyncResultMethods, type Awaitable, type DefectView, Do, Err, type ErrOf, type ErrView, type NotThenable, Ok, type OkOf, type OkView, Result, type ResultMethods, type TagHandlers, TaggedError, type TaggedErrorConstructor, type TaggedErrorInstance, UnwrapError, all, allAsync, allFromDict, allFromDictAsync, fromNullable, fromPromise, fromSafePromise, fromThrowable, isDefect, isErr, isOk, isResult, matchTags };
 //# sourceMappingURL=index.d.cts.map