feat(core)!: match the error channel exhaustively with ts-pattern

[btravers]

What

Every error is now handled explicitly, and enriching the error channel E
is a compile error at every consuming site until each new case is handled.
The error combinators — mapErr, flatMapErr, recoverErr, tapErr,
flatTapErr — receive a ts-pattern
match builder over the error (match(error)) plus the injected defect helper,
and return the un-terminated builder — the combinator calls .exhaustive()
for you:

import { P, tag } from "unthrown";

// before — a future tag lands in the fallthrough unnoticed
.mapErr((error) => {
  if (error._tag === "RecordNotFound") return new NotFoundException(id);
  throw error.cause;
})

// after — exhaustive; the type checker forces every case to be handled
.mapErr((m, defect) =>
  m
    .with(tag("RecordNotFound"), () => new NotFoundException(id))
    .with(tag("DriverError"), (e) => defect(e.cause)),
)

Because the combinator runs .exhaustive(), a missing case does not compile —
there is no .exhaustive() to forget and no .otherwise() to smuggle in a
fallback. Errors-as-values only pays off if the values can't be silently
dropped; this makes sure they aren't.

Design journey (why not the record)

This PR started as a per-tag record ({ RecordNotFound: …, DriverError: … })
with a mergeTags escape hatch. Review surfaced two real limits of that shape:
it only keyed on _tag (breaking code-discriminated unions like oRPC's), and
it couldn't share one strategy across several cases. ts-pattern dissolves both —
and, crucially, keeps the forced-exhaustiveness the record was invented to
provide, because the combinator owns .exhaustive(). So the whole bespoke
machinery (ErrTriage/mergeTags/TriageReturns/TriageKeysOk/NoDefects)
is deleted in favor of the matcher.

The rules

• Match on anything — _tag, code, structural shapes, guards, and grouped
  patterns (.with(a, b, handler) — one strategy for several cases). tag("X")
  is sugar for { _tag: "X" }.
• P._ is the deliberate catch-all — the uniform "handle everything else"
  branch that replaces the old single callback, made explicit and greppable.
• Each branch receives the narrowed variant and the injected defect helper;
  its Defect arm is subtracted from the outgoing E (Exclude<O, Defect>, the
  boundary inference). A throwing branch also becomes a Defect (safety net).
• Observers match exhaustively too (tapErr/flatTapErr, P._ for a
  catch-all); the error is observed and flows through unchanged.

Type-machinery notes (recorded in CLAUDE.md → Internal design)

• ErrMatcher<E> = ReturnType<typeof match<E>>; the callback returns an
  ExhaustiveMatch<O> whose .exhaustive is typed callable only when ts-pattern
  narrowed the input to never. Outgoing E = Exclude<MatchOut<M>, Defect>.
• ErrMatcher<E> must stay a contravariant callback parameter only.
  ts-pattern's Match is invariant in its input; unioning an M-derived output
  with the class E in a covariant return re-invaded E's variance and
  collapsed inference (combine<T,E>(rs: AsyncResult<T,E>[]) → unknown). That
  is why flatTapErr infers a plain E2 and returns E | E2 — verified by a
  regression assertion in types.test-d.ts.
• runMatch(f, error) = f(match(error), defect).run(); a value slipping past the
  types throws NonExhaustiveError, which the throw-to-defect net turns into a
  Defect. AsyncRes's five methods are typed loosely (never channels) across
  the implements boundary; the public surface re-imposes precision.
• Async-branch handling: only flatMapErr/flatTapErr await, so only they
  reject an async branch (via the builder-output constraint); mapErr/
  recoverErr/tapErr run synchronously, so an async branch is a visible
  Promise-valued result, not a rejection bypass.

@unthrown/pattern removed; ts-pattern folded into core

Core now depends on ts-pattern (small, types-heavy, and dual-copy-safe —
its matcher protocol keys off a global Symbol.for), and re-exports match and
P, plus tag. The standalone @unthrown/pattern package is deleted: tag
moved into core; the P.Ok/P.Err/P.Defect sugar is dropped (match the union
structurally with ts-pattern instead — match(r).with(P.Ok(), …) still works
since Result is a discriminated union).

Also breaking

• Deprecated error-channel aliases orElse / recover removed. The
  extractor aliases (unwrap, unwrapErr, unwrapOr, unwrapOrElse) remain.
• AsyncOkOf / AsyncErrOf now infer through the Awaitable channel only
  (same results for ordinary AsyncResult types).

Verification

• Full gate green: format --check, lint, typecheck, knip, test, build
  — 36/36 turbo tasks, 386 tests across the workspace (incl. prisma SQLite and
  orpc end-to-end suites). Core 236 tests, 100% line/function coverage;
  typedoc warning-free.
• types.test-d.ts pins: forced exhaustiveness (a missing case doesn't compile),
  P._ catch-all, grouped patterns, code-discriminated and untagged unions,
  defect/throw-branch subtraction, flatMapErr/flatTapErr async-branch
  rejection, and the combine inference regression guard.
• Docs: the "Triaging the error channel" guide leads with the
  handle-everything-explicitly / compile-error-on-enrichment guarantee; migration
  tables, orpc guide/README, core-concepts, and the CLAUDE.md spec (Thesis chore: migrate repo + docs URLs to btravstack org #5,
  invariants, internal design, monorepo layout) all updated; the pattern package
  guide/API pages removed.

[Copilot]

Pull request overview

This PR introduces a breaking-change update to unthrown’s core API by replacing the error-transformer callback form with a per-_tag triage object (ErrTriage) for mapErr, flatMapErr, and recoverErr, ensuring compile-time exhaustiveness for tagged error unions and making blanket handling explicit via Else.

Changes:

• Refactors mapErr/flatMapErr/recoverErr (sync + async surfaces) to accept an ErrTriage object and adds supporting type machinery (TriageReturns, TriageKeysOk, NoThenables), plus updated AsyncOkOf/AsyncErrOf inference.
• Removes deprecated error-channel aliases orElse / recover, and updates tests and type-level assertions accordingly.
• Updates docs, guides, and oRPC examples/migration tables to reflect triage-based error transformations, and adds a major changeset entry.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/orpc/src/server.ts	Updates inline example to use mapErr({ Else: … }) triage form.
packages/orpc/src/extensions/result.ts	Updates extension example to use triage form.
packages/orpc/README.md	Updates README examples to use triage object (including multiline formatting).
packages/core/typedoc.json	Adds triage helper types to intentionallyNotExported for docs generation.
packages/core/src/types.ts	Adds ErrTriage + triage helper types; updates method surface signatures and variance annotations; updates async extractor inference.
packages/core/src/types.test-d.ts	Adds/updates type-level assertions for triage exhaustiveness, Else forms, and async-branch rejection.
packages/core/src/result.spec.ts	Adds runtime tests for triage dispatch semantics, Else fallback/precedence, and unhandled-tag behavior.
packages/core/src/invariants.spec.ts	Updates invariants to use triage form for error transformers.
packages/core/src/index.ts	Re-exports ErrTriage type from the public entry point.
packages/core/src/deprecated-aliases.spec.ts	Removes tests for deleted orElse/recover aliases; keeps extractor-alias tests.
packages/core/src/core.ts	Implements triage-based dispatch in Res and AsyncRes via triageHandlerFor.
packages/core/src/async-result.spec.ts	Updates async runtime tests to use triage form; keeps async composition coverage.
docs/guide/the-defect-channel.md	Updates examples to triage syntax for mapErr/recoverErr.
docs/guide/recipes.md	Updates recipe wording + example to use triage form.
docs/guide/orpc.md	Updates oRPC guide examples to triage form; updates a more complex mapping example to be per-tag.
docs/guide/migrating-from-neverthrow.md	Updates migration table entries for mapErr/orElse to triage-based equivalents.
docs/guide/from-try-catch.md	Updates mapping examples/table to triage-based mapErr({ Else: … }).
docs/guide/core-concepts.md	Clarifies that error transformers are triage-based and updates examples.
docs/guide/choosing-a-combinator.md	Adds a “Triaging the error channel” section and updates signatures/tables to reflect triage objects.
CLAUDE.md	Updates the project spec (Thesis #5) and invariants/internal design notes for triage.
.changeset/triage-error-channel.md	Adds a major changeset describing the breaking change and migration guidance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (7)

packages/core/src/types.ts:354

• This section still references a missing Else branch ("no branch and no Else"). The behavior is simply "no branch" (only reachable outside the typed contract), which becomes a Defect.

   * An error whose tag has no branch and no `Else` (unreachable through
   * well-typed code) becomes a `Defect` carrying it. An async branch is
   * rejected at compile time ({@link NotThenable}).

packages/core/src/types.ts:359

• The @param docs still mention using an Else branch for blanket handling, but uniform handling is done via mergeTags(fn) rather than a reserved object key.

   * @param handlers - the triage object: per-tag branches, each mapping its
   * error to a new one (or `Else` for the deliberate blanket case).

packages/core/src/types.ts:375

• flatMapErr’s TSDoc repeats the idea of an Else fallthrough branch. The triage object is exhaustive; the explicit uniform form is mergeTags(fn).

   * mirror of {@link ResultMethods.flatMap | flatMap}, **triaging the error by
   * tag** ({@link ErrTriage}: exhaustive unless `Else` is present).

packages/core/src/types.ts:404

• recoverErr’s TSDoc still says the triage is "exhaustive unless Else is present", which doesn’t match the current API (no fallthrough key; mergeTags is the opt-out).

   * Recover from an `Err` by producing a success value, emptying the error
   * channel — **triaging the error by tag** ({@link ErrTriage}: exhaustive
   * unless `Else` is present). Pairs with
   * {@link ResultMethods.recoverDefect | recoverDefect}.

packages/core/src/types.ts:434

• tapErr’s TSDoc claims the partial triage includes an Else branch and later shows { Else: ... } as uniform observation. Uniform observation is via tapErr(mergeTags(fn)); Else is just an ordinary tag name if it exists in E.

   * Run a side effect on the error — **observed by tag** through a *partial*
   * triage object ({@link ErrTriagePartial}: every branch optional, `Else`
   * included) — and pass the `Result` through unchanged.

packages/core/src/types.ts:438

• The uniform-observation example uses { Else: ... }, but the uniform form is mergeTags(fn) (and the per-tag partial object doesn’t have a reserved fallthrough key).

   * Runs the matching branch only on `Err`; a tag without a branch is simply
   * not observed. Uniform observation is `{ Else: (e) => log(e) }`. If a
   * branch throws, the result is a `Defect` whose cause is an `AggregateError`

packages/core/src/core.ts:507

• triageHandlerFor can throw when handlers is null/undefined (and it’s called outside the surrounding try/catch). That would violate the library’s “throw → Defect” invariant for sync Results, and can also cause AsyncRes’s internal promise chain to reject (breaking the “AsyncResult promise never rejects” invariant). Adding a null/typeof guard here keeps invalid handler values contained as a Defect instead of escaping as a raw throw/rejection.

  if (isMergedTriage(handlers)) {
    // The explicit uniform form: one handler for every error, tagged or not.
    return handlers.handler as (error: unknown, defect?: (cause: unknown) => Defect) => unknown;
  }
  const triage = handlers as Record<string, unknown>;

[Copilot]

Pull request overview

Copilot reviewed 39 out of 40 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

[Copilot]

Pull request overview

Copilot reviewed 56 out of 57 changed files in this pull request and generated 6 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Comments suppressed due to low confidence (1)

docs/guide/the-defect-channel.md:52

• This example again uses P._ without defining P. Since d’s error channel is never, the vacuously-exhaustive matcher => matcher form keeps the example consistent and self-contained.

```ts
const recovered = d.recoverErr((matcher) => matcher.with(P._, () => 99));
// type: Result<number, never>