🚀 Release 0.9.0

🔀 Merge feature/ts-compat-ci into main
📝 Check off the CI TypeScript-floor task
2026-09-29 21:37:53 +00:00 · 2026-09-29 21:24:16 +00:00 · 2026-09-29 21:24:05 +00:00 · 2026-09-29 21:23:15 +00:00 · 2026-09-29 21:15:01 +00:00 · 2026-09-29 21:10:15 +00:00
38 changed files with 5957 additions and 1172 deletions
@@ -77,6 +77,13 @@ jobs:
            - run: npm ci
            - run: npm run build
            - run: npm run check
            # Compile the prose examples into gitignored tests. Kept as an
            # explicit step (not a `pretest:ci` hook) so it is visible in the
            # job log and `test:ci` stays a plain command.
            - run: npm run create:doc-tests
            # Fails the build below 100% coverage on `src/` (`c8 --all --100`);
            # the same run produces the report published below. See
            # development/ci.md § Coverage threshold.
            - run: npm run test:ci
            # Publish this tag's coverage to the self-hosted pages server,
            # served read-only at
@@ -112,6 +119,35 @@ jobs:
                  name: dist
                  path: dist/
    # Consumer typecheck against the minimum supported TypeScript (README
    # § Requirements), run over `dist/`'s emitted declarations and the whole
    # suite. Deliberately a separate job, not a step in `build`: the compiler is
    # a different major picked by `npx`, and it must never enter
    # `devDependencies`, the local `check`/`verify` tiers, or the lockfile. See
    # development/ci.md § TypeScript compatibility.
    compat:
        needs: build
        runs-on: ubuntu-latest
        # Same baked image as `build` — without it this job re-downloads Node
        # per run (see docker/Dockerfile).
        container:
            image: gitea.e1nsnull.de/tmu/act-ci:26.8.2
        steps:
            - uses: actions/checkout@v4
            - uses: actions/setup-node@v4
              with:
                  node-version-file: .node-version
                  cache: "npm"
            - run: npm ci
            # Reuse the exact `dist/` that `check`, `test:ci` and `publint` were
            # run against, so the compat gate judges the shipped artifact and
            # pays no rebuild.
            - uses: actions/download-artifact@v4
              with:
                  name: dist
                  path: dist/
            - run: npm run test:compat
    # Advisory scans (dead code, dependency freshness). Non-blocking: surfaced in
    # the Actions tab for visibility, but must never gate a merge — so
    # continue-on-error and intentionally NOT in `publish`'s `needs`.
@@ -135,7 +171,9 @@ jobs:
    publish:
        if: startsWith(gitea.ref, 'refs/tags/')
-        needs: build
+        # `compat` gates the release: an artifact that is not consumable at the
        # claimed TypeScript floor must never ship.
        needs: [build, compat]
        runs-on: ubuntu-latest
        # Same baked image as `build` — setup-node still owns the registry-url
        # `.npmrc` rewrite here; only the Node download is skipped.
@@ -1,6 +1,10 @@
 node_modules
 dist
 coverage
 # Generated doc-tests (scripts/create-doc-tests.ts); the folder is kept via .gitkeep
 src/doc-test/__generated__/*.test.ts
 !src/doc-test/__generated__/.gitkeep
 *.log
 *.tsbuildinfo
 *.local
@@ -34,7 +34,9 @@
                "no-unused-expressions": "off",
                "no-empty-file": "off",
                "import/no-nodejs-modules": "off",
-                "eslint/no-magic-numbers": "off"
+                "eslint/no-magic-numbers": "off",
                "unicorn/no-null": "off",
                "typescript/no-floating-promises": "off"
            }
        },
        {
@@ -1,3 +1,3 @@
 {
-    "packages": ["npm:@spences10/pi-lsp@0.0.46"]
+    "packages": ["npm:@spences10/pi-lsp@0.0.47"]
 }
@@ -7,10 +7,11 @@ first-action facts. Do not restate evolving prose here — it will drift.
 ## First action
- Project: F#-style pattern matching for TypeScript/ESM. Node `>=26` (pinned via `.node-version`), ESM-only (no CommonJS shim).
+- Project: pattern matching for TypeScript/ESM. Node `>=26` (pinned via `.node-version`), ESM-only (no CommonJS shim).
 - **While iterating:** `npm run test` (`check:tsc` + the unit suite) for fast feedback on the files you changed.
- **Optional code intelligence:** this repo installs `@spences10/pi-lsp` (pinned in `.pi/settings.json`) as a project-local pi extension. It talks to the repo's own TypeScript 7 via `tsc --lsp --stdio` and exposes **read-only** tools — `lsp_hover`, `lsp_definition`, `lsp_references`, `lsp_find_symbol`, `lsp_document_symbols`, `lsp_diagnostics(_many)`. Prefer `lsp_references` over `grep -w` for widely-colliding identifiers (`matches`, `type`, …); use `lsp_hover` to read inferred types on generic-heavy code. It has no rename / code-action / apply-edit surface — the write side is pi's `edit` tool + `check:tsc`. Treat empty LSP output as _inconclusive_, not success: **`npm run test` / `npm run verify` remain the sole authoritative gate** (see the next bullet). The server keeps running across that gate with a ~5 min idle timeout and registers no file watchers, so if you change `tsconfig.json` / `package.json` mid-session its diagnostics can be stale — when LSP output disagrees with `check:tsc`, trust `check:tsc` and restart pi (or wait out the idle timeout) before concluding the LSP is wrong.
+- **Optional code intelligence:** this repo installs `@spences10/pi-lsp` (pinned in `.pi/settings.json`) as a project-local pi extension. It talks to the repo's own TypeScript 7 via `tsc --lsp --stdio` and exposes **read-only** tools — `lsp_hover`, `lsp_definition`, `lsp_references`, `lsp_find_symbol`, `lsp_document_symbols`, `lsp_diagnostics(_many)`. **When you are looking for a symbol, reach for the LSP before `rg`/`grep`** — `lsp_references` / `lsp_find_symbol` / `lsp_definition` / `lsp_document_symbols` are semantic and cross-file, so they see shadowing, imports and overloads that a text search cannot; use `lsp_hover` to read inferred types on generic-heavy code. Use `rg` for what the LSP cannot see — doc prose, string literals, config, task lists, file discovery — and reconcile the two sets before editing (symbols from the LSP, strings and prose from `rg`). It has no rename / code-action / apply-edit surface — the write side is pi's `edit` tool + `check:tsc`. Treat empty LSP output as _inconclusive_, not success: **`npm run test` / `npm run verify` remain the sole authoritative gate** (see the next bullet). The server keeps running across that gate with a ~5 min idle timeout and registers no file watchers, so if you change `tsconfig.json` / `package.json` mid-session its diagnostics can be stale — when LSP output disagrees with `check:tsc`, trust `check:tsc` and restart pi (or wait out the idle timeout) before concluding the LSP is wrong.
 - **Definition of done — run this before you call the work finished:** `npm run verify`. If all green, commit. If red, look at the output, fix the root cause, and re-run.
 - **Touched a `ts`-tagged fence in `README.md` / `CONTRIBUTING.md`?** Run `npm run create:doc-tests` first: it regenerates the gitignored tests under `src/doc-test/__generated__/`, formats and type-checks them, so `verify` executes the documented example. CI runs it in an explicit step before `test:ci`; the fast local tiers do not. See [development/docs.md](./development/docs.md).
 - **On commit:** write a good message (see [CONTRIBUTING.md § Commit messages](./CONTRIBUTING.md#commit-messages)). Lefthook's pre-commit hook already runs the fast, offline, staged-file checks — don't run them by hand. If the hook fails on style, `npm run fix`, restage, recommit.
 - **Document decisions where the next maintainer will look:** rationale, rejected alternatives and known issues go in `development/<category>.md` (see [development/README.md](./development/README.md)); the actionable rule stays in [CONTRIBUTING.md](./CONTRIBUTING.md) and links to it. Write each fact once — never copy the rule into `development/` or the reason into `CONTRIBUTING.md` — and change both in the same commit when a rule changes.
 - **`npm run maintain` is NOT part of the feature loop.** Its scans are advisory, never a gate; run them only on an explicit maintenance / update-deps branch.
@@ -25,10 +26,11 @@ first-action facts. Do not restate evolving prose here — it will drift.
 Don't silence the type system to force a green run. As an agent these are forbidden:
 - `// @ts-nocheck`, `// @ts-ignore`, `// @ts-expect-error`
- `// oxlint-disable` / `// oxlint-disable-next-line` — the sole exception is the fixed file-level `typescript/no-floating-promises` header at the top of a `*.test.ts` file, spelled exactly as [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) prescribes
+- `// oxlint-disable` / `// oxlint-disable-next-line`
 - editing `.oxlintrc.json` to silence a finding (e.g. turning `typescript/no-floating-promises` off)
 - `as` casts used to push an expression through (type-aware oxlint already flags unsafe assertions)
-Fix the root cause with the type system instead — narrowing, generics, `satisfies`, conditional / mapped types, utility types (`NonNullable`, `Exclude`, …). TypeScript can express it; that's the intended tool. The `oxlint-disable`-location rule in [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) is a **human** last-resort convention (so a reviewer can spot a deliberate suppression) — it is not permission for you to add one, except the one fixed `*.test.ts` file-level header named there. If the types genuinely cannot express something, stop and surface the conflict (commit message / handover) rather than suppress it.
+Fix the root cause with the type system instead — narrowing, generics, `satisfies`, conditional / mapped types, utility types (`NonNullable`, `Exclude`, …). TypeScript can express it; that's the intended tool. Suppressions — a source `oxlint-disable` **or** a `.oxlintrc.json` entry — are a **human** last resort, not a tool for you. If the types genuinely cannot express something, stop and surface the conflict (commit message / handover) rather than suppress it.
 The same applies to the checks themselves: **never `git commit --no-verify`** (or otherwise skip a pre-commit / pre-push hook). The checks are fast and offline, so a redundant run is fine — bypassing a hook to get green is the identical anti-pattern. If a commit already skipped a hook, redo it through one: `git reset --soft HEAD~1 && git commit -C <skipped-sha>`.
@@ -42,7 +44,9 @@ Never start a long-lived / blocking process such as `npm run watch`. It runs unt
 ### Working on tasks
- **Task with subtasks** (a task that has indented children): create the branch with `npm run create:branch -- <prefix>/<desc>`, inferring the prefix from the task content (`feature/…` / `fix/…` / `chore/…`) — do not hand-write `git switch -c`, the command enforces the clean-tree / current-`main` / green-baseline precondition. Work on each subtask with commits, then present a concise handover for the user to review. Use this fixed shape:
+Every task — with or without subtasks — goes through the complete branching model:
 - Create the branch with `npm run create:branch -- <prefix>/<desc>`, inferring the prefix from the task content (`feature/…` / `fix/…` / `chore/…`) — do not hand-write `git switch -c`, the command enforces the clean-tree / current-`main` / green-baseline precondition. Work with commits (each subtask gets one or more), then present a concise handover for the user to review. Use this fixed shape:
    ```md
    ## Handover — <branch>
@@ -54,9 +58,7 @@ Never start a long-lived / blocking process such as `npm run watch`. It runs unt
    Once the user has no further objections, merge back: `npm run create:finish` (on the branch — it merges `--no-ff`, runs `npm run verify`, and deletes the branch). The branching model is documented in [CONTRIBUTING.md § Branching model](./CONTRIBUTING.md#branching-model).
- **Leaf task** (no indented children): implement on the current branch and commit.
+Follow [CONTRIBUTING.md § Testing discipline (type-driven)](./CONTRIBUTING.md#testing-discipline-type-driven) throughout.
 In both cases, follow [CONTRIBUTING.md § Testing discipline (type-driven)](./CONTRIBUTING.md#testing-discipline-type-driven). Each subtask gets one or more commits.
 ## Read these
@@ -7,7 +7,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
- house shared test helpers under `src/util/__tests__/`, addressed by the `#test-utils/*` package self-reference instead of relative paths
+## [0.9.0] - 2026-09-29
 - add a CI `compat` job that type-checks the suite and a consumer fixture
  against the minimum supported TypeScript (5.9), consuming the built `dist/`
  and gating `publish`
 - correct the documented consumer floor to TypeScript >= 5.9 and drop the
  unsupported `node10` resolution claim
 ## [0.8.3] - 2026-09-28
 - upgrade dependencies: oxfmt 0.71 (the only range widened), oxlint 1.86,
  oxlint-tsgolint 7.0.2003, cspell 10.3.5 and the rest within their existing
  ranges; no rule or format fallout
 - prune the completed items from the backlog; their rationale already lives in
  the README, `development/` and the released changelog entries
 ## [0.8.2] - 2026-09-25
 - write the README's Synopsis and Examples sections
 - document the public API in the README
 - add TSDoc to the four public matcher factories
 - document alternatives
 ## [0.8.1] - 2026-09-23
 - gate CI at 100% coverage: `test:ci` runs c8 with `--all --100` over `src/`,
  and a test loads the `index.ts` barrel so it is measured
 - pin the duplicate-tag union collapse (members sharing a tag dispatch through
  one handler) with tests
 ## [0.8.0] - 2026-09-23
 - reject a universe that mixes a literal with a broad type (e.g.
  `"a" | \`x-${number}\``), which the finite-literal gate let through
 - narrow the tagged-union matcher's handler parameters for a union-valued or
  optional discriminant, and its fallback to the unhandled tags, instead of
  passing `never`
 ## [0.7.1] - 2026-09-23
 - upgrade dependencies
 ## [0.7.0] - 2026-09-23
 - reject broad universes (`string`, `number`, template literals) and
  value/stringification collisions (`true | "true"`, `1 | "1"`) at the factory
 - type handler parameters by the matched member, so a
  standalone `"true"` universe is typed `"true"` rather than `true`
 ## [0.6.0] - 2026-09-22
 - add `getTaggedUnionMatcher` / `getTaggedUnionMatcherW` for discriminated unions
 - rename the primitive matcher to primitive-union: `getMatcher` /
  `getMatcherW` → `getPrimitiveUnionMatcher` / `getPrimitiveUnionMatcherW`, and
  `src/primitive.ts` / `src/primitive.test.ts` → `src/primitive-union.*`
 ## [0.5.0] - 2026-09-21
 - reject a fallback when the handler map already covers the universe
 - allow boolean, null and undefined in the matcher universe
 ## [0.4.0] - 2026-09-20
 - move the `_` fallback out of handlers
 ## [0.3.0] - 2026-09-18
 - condensed primitive matcher factories down to 2 from formerly 4
 - house shared test helpers under `src/util/__tests__/`
 ## [0.2.0] - 2026-09-16
@@ -56,7 +124,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - basic setup
-[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.2.0...main
+[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.9.0...main
 [0.9.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.3...0.9.0
 [0.8.3]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.2...0.8.3
 [0.8.2]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.1...0.8.2
 [0.8.1]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.0...0.8.1
 [0.8.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.7.1...0.8.0
 [0.7.1]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.7.0...0.7.1
 [0.7.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.6.0...0.7.0
 [0.6.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.5.0...0.6.0
 [0.5.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.4.0...0.5.0
 [0.4.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.3.0...0.4.0
 [0.3.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.2.0...0.3.0
 [0.2.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.8...0.2.0
 [0.1.8]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.7...0.1.8
 [0.1.7]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.6...0.1.7
@@ -20,8 +20,14 @@ the rules so agents and humans don't diverge.
 - **Build:** `npm run build`
 - **Test:** `npm run test`, `npm run test:ci`
 - **Compat (CI-only, manual locally):** `npm run test:compat` — type-check the
  suite + a consumer fixture against the minimum supported TypeScript; needs a
  built `dist/` and network access (`npx`). Never part of a hook or
  `check`/`verify`
 - **Watch:** `npm run watch` - re-runs tests on file save, humans only
 - **Checks:** `npm run check`, `npm run fix`
 - **Doc tests:** `npm run create:doc-tests` — compile the `ts`-tagged fences
  in the prose docs into executed, gitignored tests
 - **Verify:** `npm run verify` — the definition of done
 - **Maintenance:** `npm run maintain` — advisory only
 - **Individual fixes:** `npm run fix:oxfmt`, `npm run fix:oxlint`
@@ -41,7 +47,8 @@ faster tiers catch less, slower tiers are more thorough":
 | `npm run verify`                 | manual                  | Definition of done: `npm run check` + unit tests, one shot                                                                                              | ~6s   |
 | `npm run fix`                    | manual                  | Auto-resolve fixable issues (lint, format)                                                                                                              | ~3s   |
 | `npm run maintain`               | manual / CI (advisory)  | `maintain:knip` + `maintain:outdated` (whole-project + network scans)                                                                                   | ~10s  |
-| CI build (auto)                  | on push to `main` / tag | `build` job (build + correctness + packaging) — see [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml)                                                | ~30s+ |
+| CI build (auto)                  | on push to `main` / tag | `build` job (build + correctness + coverage + packaging) — see [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml)                                     | ~30s+ |
 | CI compat (auto)                 | in CI only              | `compat` job — `test:compat` over the built `dist/`; never a local tier (run by hand) — see [compat/](./compat)                                         | ~15s  |
 | CI maintain (auto, non-blocking) | on push to `main`       | `npm run maintain` — reports, never fails the build                                                                                                     | ~10s  |
 | CI publish (auto)                | on tag                  | packaging checks + `publish:publint` / `publish:attw`, then the Gitea release page and `npm publish` (skipped, and the job failed, without `NPM_TOKEN`) | ~15s  |
@@ -66,9 +73,12 @@ before the implementation. The loop is **type → red → green → refactor**:
 4. **Refactor** — with the type system and the tests as the safety net, then
   `npm run verify` as the definition-of-done gate.
-Every test pairs an `expectTypeOf(...)` with an `assert.*`; keep them together.
+Every test pairs an `expectTypeOf(...)` with an `assert.*`; keep them together
 — including the expectations inside handler bodies, which pair with an
 assertion on the value dispatch passed, not only the type it inferred (see
 [development/testing.md § Handler arguments](./development/testing.md#handler-arguments)).
 The autocomplete tests (`src/util/__tests__/lsp-completion.test.ts` for the
-helper, `src/primitive.test.ts` for the matcher's popup) are the
+helper, `src/primitive-union.test.ts` for the matcher's popup) are the
 exception —
 the language server, not the type system, is the oracle (see
 [development/testing.md § Autocomplete](./development/testing.md#autocomplete)).
@@ -84,6 +94,17 @@ Per [AGENTS.md § Never do](./AGENTS.md#never-do), reach green honestly — fix
 types, never suppress the checks you can't make pass. Full rationale:
 [development/testing.md](./development/testing.md).
 ## Documentation examples
 Every `ts`-tagged fence in `README.md` / `CONTRIBUTING.md` is compiled into an
 executed test, so a documented example cannot drift from the API. Describe each
 fence with the paragraph directly above it (that text becomes the test title),
 and keep its library import self-contained;
 `npm run create:doc-tests` regenerates, formats and type-checks the tests under
 `src/doc-test/__generated__/`. CI runs it in an explicit step before `test:ci`,
 so run it yourself before `npm run verify` when you touched a fence. Why:
 [development/docs.md](./development/docs.md).
 ## Code style and formatting
 `oxfmt` is the formatter and `oxlint` is the linter (with type-aware rules).
@@ -112,17 +133,23 @@ intended to run. A `<prefix>:<name>` script is implicitly aggregated by a
 `<prefix>` script (if one exists) and run by the corresponding lefthook hook or
 CI step. Pick the prefix that matches the script's lifecycle:
- `create:*` — front doors of the repo's own workflow; these mutate git state
+- `create:*` — front doors of the repo's own workflow; these produce or mutate
-  rather than the source. `create:branch` opens a unit of work, `create:finish`
+  workflow artifacts (git state, generated doc-tests) rather than the
  hand-written source. `create:branch` opens a unit of work, `create:finish`
  closes the branch half, `create:release` closes the release half
-  (maintainer-only). No bare `create` aggregator on purpose.
+  (maintainer-only), and `create:doc-tests` regenerates the compiled prose
  examples. No bare `create` aggregator on purpose.
 - `check:*` — read-only verification; never modifies files. Aggregated by
  `npm run check`.
 - `fix:*` — mutating counterpart of a `check:*` script. Aggregated by
  `npm run fix`; the diff is the review surface.
 - `test:*` — test scripts. `test` is the canonical entry point (`check:tsc` +
  unit tests); `test:unit` skips the typecheck for fast local iteration;
-  `test:ci` adds c8 coverage.
+  `test:coverage` runs c8 over the hand-written tests only; `test:doc` runs the
  generated doc examples without coverage; `test:ci` chains the two and fails
  below 100% coverage on `src/`; `test:compat` type-checks the suite + a
  consumer fixture against the minimum supported TypeScript via `npx` (both
  CI-only; `verify` stays coverage- and network-free).
 - `watch:*` — long-running watchers for the manual inner dev loop. Aggregated by
  `watch`.
 - `maintain:*` — advisory repo-maintenance scans: read-only, but whole-project
@@ -155,12 +182,9 @@ reaches for by default:
  [Script prefix convention](#script-prefix-convention).
 - **`oxlint-disable` directives live in source, not `.oxlintrc.json`.** The
  trade-off must sit next to the code it silences. This is a _human_ last-resort
-  convention; agents must not add these — see
+  convention; agents must not add one, nor edit `.oxlintrc.json` to silence a
-  [AGENTS.md § Never do](./AGENTS.md#never-do). The sole agent exception is the
+  finding (e.g. `typescript/no-floating-promises`) — see
-  fixed file-level header at the top of a `*.test.ts` file, spelled exactly:
+  [AGENTS.md § Never do](./AGENTS.md#never-do). (why:
  `/* oxlint-disable typescript/no-floating-promises -- expectTypeOf() is a sync
 type-assertion library that the type-aware linter misidentifies as a promise
 */` — any other suppression stays human-last-resort. (why:
  [development/tooling.md](./development/tooling.md#oxlint-disable-directives-live-next-to-the-code))
 - **Don't put slow / network / whole-project scans in `check` or pre-commit.**
  Advisory scans are not correctness gates; they belong under `maintain:`. (why:
@@ -1,6 +1,6 @@
 MIT License
-Copyright (c) 2025 tmu
+Copyright (c) 2026 tmu
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -1,31 +1,336 @@
 # tiny-pattern-ts
-Pattern matching for TypeScript/ESM environments (F#-style, not regex).
+Exhaustive, type-safe pattern matching for TypeScript.
 ## Synopsis
 ```ts
 import { getTaggedUnionMatcher } from "tiny-pattern-ts";
 // 1. We have a union type
 type Contact =
    | { kind: "email"; address: string }
    | { kind: "phone"; number: string }
    | { kind: "messenger"; username: string };
 // 2. Create a matcher providing the discriminant property
 const matchContact = getTaggedUnionMatcher<Contact>()("kind");
 // 3. Define handlers for each branch of the union
 const formatContact = matchContact({
    email: (e) => `MAIL: ${e.address}`,
    phone: (p) => `PHONE: ${p.number}`,
    messenger: (m) => `MESSENGER: @${m.username}`,
 });
 // 4. Call the matcher with a value
 const mailOutput = formatContact({ kind: "email", address: "ada@example.com" });
 assert.equal(mailOutput, "MAIL: ada@example.com");
 const phoneOutput = formatContact({ kind: "phone", number: "+1 555 0100" });
 assert.equal(phoneOutput, "PHONE: +1 555 0100");
 ```
 ## Description
-`tiny-pattern-ts` brings F#-style pattern matching to TypeScript. Patterns are
+`tiny-pattern-ts` is a pattern-matching library for TypeScript.
-ordinary objects whose `matches` method is a TypeScript type guard, so narrowing
+
-composes the way any other guard does. It is deliberately not a regex engine and
+The main goal of `tiny-pattern-ts` is to make pattern matching type-safe with a
-not a macro: there is no transpiler and no DSL to learn, and the type-level
+lean syntax. This is accomplished by being exhaustive and passing typed
-contract is the feature — see [development/library.md](./development/library.md)
+parameters per branch to the handlers — supported by an outstanding
-for the design decisions and the known limitations.
+autocomplete and a tiny footprint. The matchers are data last and pipe-friendly:
 build the handler map once, then apply the resulting matcher to values
 (`match(value)`, or `pipe(value, match)`).
 See [development/library.md](./development/library.md) for the design decisions
 and [Caveats](#caveats) for the limits.
 ## Installation
 ```sh
 npm install tiny-pattern-ts
 ```
 ## Requirements
 - **Node.js >= 26** (`engines` field; pinned via `.node-version`).
- **TypeScript >= 5.0** to consume the published declarations. The emitted `.d.ts`
+- **TypeScript >= 5.9** to consume the published declarations. The floor is set
-  use `const` type parameters (TS 5.0) and keep their relative `.ts` specifiers;
+  by the `type-fest` types the declarations use and is checked in CI against a
-  both resolve on TS >= 5.0 in `node10` / `node16` / `nodenext` / `bundler`.
+  consumer fixture; see [`compat/`](./compat) and
  [development/ci.md § TypeScript compatibility](./development/ci.md#typescript-compatibility).
  The emitted `.d.ts` keep their relative `.ts` specifiers, which resolve under
  `node16` / `nodenext` / `bundler`. The package exposes only an `exports` map
  (no `main` / top-level `types`), so the legacy `node10` resolver does not
  apply.
 - The package is **ESM-only** (no CommonJS shim).
 ## Examples
 A few real-world recipes. Each binds the handler-map function once and reuses
 it, so the matcher is allocated a single time.
 ### Dispatch on a primitive union
 A result code is itself a finite union, so `getPrimitiveUnionMatcher` keys a
 handler on each member:
 ```ts
 import { getPrimitiveUnionMatcher } from "tiny-pattern-ts";
 type ResultCode = "ok" | "created" | "no-content";
 const toStatus = getPrimitiveUnionMatcher<ResultCode>()({
    ok: () => 200,
    created: () => 201,
    "no-content": () => 204,
 });
 assert.equal(toStatus("ok"), 200);
 assert.equal(toStatus("created"), 201);
 assert.equal(toStatus("no-content"), 204);
 ```
 ### Leave cases to a fallback
 Pass a fallback as the second argument to handle only part of the universe; it
 receives the members the map leaves uncovered — here the parameter is
 `"deprecated" | "gateway-timeout"`:
 ```ts
 import { getPrimitiveUnionMatcher } from "tiny-pattern-ts";
 type Status = "active" | "beta" | "deprecated" | "gateway-timeout";
 const rollout = getPrimitiveUnionMatcher<Status>()(
    { active: () => "enabled", beta: () => "enabled" },
    (status) => `blocked (${status})`,
 );
 assert.equal(rollout("active"), "enabled");
 assert.equal(rollout("deprecated"), "blocked (deprecated)");
 ```
 ### Dispatch on a property union
 The value does not have to be the union itself. When a single property carries a
 finite union, the tagged-union matcher keys on it and narrows the whole record to
 the selected value:
 ```ts
 import { getTaggedUnionMatcher } from "tiny-pattern-ts";
 interface Invoice {
    readonly currency: "eur" | "usd" | "jpy";
    readonly amount: number;
 }
 const matchCurrency = getTaggedUnionMatcher<Invoice>()("currency");
 const symbolOf = matchCurrency({
    eur: (i) => `€${i.amount.toFixed(2)}`,
    usd: (i) => `$${i.amount.toFixed(2)}`,
    jpy: (i) => `¥${i.amount.toFixed(0)}`,
 });
 assert.equal(symbolOf({ currency: "usd", amount: 12.5 }), "$12.50");
 assert.equal(symbolOf({ currency: "jpy", amount: 900 }), "¥900");
 ```
 ### Widen the return type
 When the handlers return different types, reach for the widening `W` variant: the
 matcher's return is their union rather than one common type — here
 `string | string[] | undefined`:
 ```ts
 import { getPrimitiveUnionMatcherW } from "tiny-pattern-ts";
 type Field = "name" | "tags" | "note";
 const parse = getPrimitiveUnionMatcherW<Field>()({
    name: () => "Ada",
    tags: () => ["admin", "beta"],
    note: () => undefined,
 });
 assert.equal(parse("name"), "Ada");
 assert.deepEqual(parse("tags"), ["admin", "beta"]);
 assert.equal(parse("note"), undefined);
 ```
 ## API
-Yet to be implemented
+The package exports four factories. Two axes pick one:
 - **Universe** — a _primitive-union_ matcher matches a value that is itself a
  finite union (`"yes" | "no"`); a _tagged-union_ matcher matches an object
  discriminated by a property (`{ kind: … }`).
 - **Return** — the _strict_ variant gives every handler one common return type
  `R`; the _widening_ variant (`W`) widens the return value to the union of the
  handler returns.
 | Factory                          | Use when                                                                  | Return                |
 | -------------------------------- | ------------------------------------------------------------------------- | --------------------- |
 | `getPrimitiveUnionMatcher<T>()`  | the value is the union and all handlers return the same type              | one common `R`        |
 | `getPrimitiveUnionMatcherW<T>()` | the value is the union and handlers return different types                | union of the handlers |
 | `getTaggedUnionMatcher<T>()`     | the value is a discriminated object and all handlers return the same type | one common `R`        |
 | `getTaggedUnionMatcherW<T>()`    | the value is a discriminated object and handlers return different types   | union of the handlers |
 Bind the function that takes the handler map to a `match…` variable once and
 reuse it; the [Examples](#examples) do this, so the builder is allocated once.
 ### Primitive-union matchers
 `getPrimitiveUnionMatcher<T>()` takes the finite universe `T` and returns a
 builder. Calling the builder with a handler map keyed by `T`'s members returns a
 matcher: a function from `T` to the common return type.
 ```ts
 import { getPrimitiveUnionMatcher } from "tiny-pattern-ts";
 const matchAnswer = getPrimitiveUnionMatcher<"yes" | "no">();
 const reply = matchAnswer({
    yes: () => "agreed",
    no: () => "declined",
 });
 const answer = reply("yes");
 assert.equal(answer, "agreed");
 ```
 Add a fallback as the second argument to leave members unhandled; the fallback
 receives the remainder:
 ```ts
 import { getPrimitiveUnionMatcher } from "tiny-pattern-ts";
 const matchLabel = getPrimitiveUnionMatcher<"yes" | "no" | "maybe">();
 const label = matchLabel(
    { yes: () => "agreed", no: () => "declined" },
    (other) => `not sure: ${other}`, // other: "maybe"
 );
 const answer = label("yes");
 assert.equal(answer, "agreed");
 const fallback = label("maybe");
 assert.equal(fallback, "not sure: maybe");
 ```
 `getPrimitiveUnionMatcherW` is the same builder, but the matcher's return type
 is the union of the handler return types rather than one common `R`.
 ### Tagged-union matchers
 `getTaggedUnionMatcher<T>()` takes a discriminated union `T`. The returned
 function takes the discriminant property's name and returns the handler-map
 builder, keyed by that property's tags.
 ```ts
 import { getTaggedUnionMatcher } from "tiny-pattern-ts";
 type Shape =
    { kind: "circle"; radius: number } | { kind: "square"; side: number };
 const matchShape = getTaggedUnionMatcher<Shape>()("kind");
 const area = matchShape({
    circle: (s) => Math.PI * s.radius ** 2,
    square: (s) => s.side ** 2,
 });
 const circleArea = area({ kind: "circle", radius: 2 });
 assert.equal(circleArea, Math.PI * 4);
 const squareArea = area({ kind: "square", side: 3 });
 assert.equal(squareArea, 9);
 ```
 `getTaggedUnionMatcherW` is the widening counterpart, exactly as in the
 primitive-union pair. The discriminant key is restricted to properties whose
 values are tags; see [Caveats](#caveats) for the supported tags and the
 `boolean` / `null` / `undefined` key projection.
 ### The universe
 The primitive universe `T` must be a finite union of literals with no
 value/stringification collision. A broad member (`string`, `number`, a template
 literal) or a colliding pair (`true | "true"`, `1 | "1"`) is rejected at the
 factory. The reasons and the rejected alternatives are in
 [development/library.md](./development/library.md).
 ## Caveats
 - **Only finite universes are supported.** The factory must be given a finite
  union of literals; `string`, `number` and template literals are rejected. This
  is what lets the exhaustive overload be proven, so the runtime `dispatch`
  throw stays unreachable through the typed API.
 - **A value and its stringification must not both be present.** Object keys
  stringify, so a universe containing both a member and the string it
  stringifies to — `1 | "1"`, `true | "true"`, `null | "null"` — is rejected at
  the factory. Either form alone is fine, and one value's string form may
  coexist with a _different_ value's bare form (`"true" | false`).
 - **`symbol` and `bigint` are not supported.** A `symbol` brand is a
  compile-time phantom with nothing to match at runtime, and a `bigint` is not a
  valid property key; neither satisfies the matcher's universe constraint.
 - **`NaN` and `-0` cannot be matched specifically.** They have no literal type,
  so both stay part of `number`.
 ### Why open universes are rejected
 An open universe — one carrying a broad member, as in
 `type Units = "s" | "ms" | "min" | (string & {})` — is not a dispatch concern.
 If the values arrive from outside the program, parse them at the boundary down
 to a finite union and match the narrowed result; the openness never reaches the
 matcher. If the domain is genuinely extensible, the right shape is a runtime
 `Map` of handlers, where "no handler" is a lookup, not a pattern. Either way an
 open matcher would abandon the one guarantee this library exists to give —
 provable exhaustiveness — to automate what a `switch` and a default arm already
 cover. The type-level cost of supporting open universes is recorded in
 [development/library.md](./development/library.md#supported-universes).
 ## Alternatives
 ### [`ts-pattern`](https://github.com/gvergnaud/ts-pattern)
 - is the full structural matcher — nested and partial patterns, guards, unions,
  captures — exhausting at `.exhaustive()`
 - has a fluent `.with(…)` chain that is heavy on syntax; tiny-pattern-ts is one
  handler map
 - is about 2 kB minified and gzipped; tiny-pattern-ts is 0.2 kB
 - reach for it when you need a feature tiny-pattern-ts does not cover
 ### [Effect's `Match`](https://effect.website/docs/code-style/pattern-matching/)
 - is the same piped matcher (`Match.type` / `Match.when` / `Match.exhaustive`),
  but only as part of the `effect` ecosystem
 - tiny-pattern-ts is standalone: no runtime dependency to buy into
 ### [`match-iz`](https://github.com/shuckster/match-iz)
 - expresses patterns in the TC39 proposal's style, deciding each case at runtime
 - is written in JavaScript with hand-maintained declarations, so its types do
  not prove the cases exhaustive
 - tiny-pattern-ts does: exhaustiveness is a compile-time guarantee, not an
  `otherwise` fallback
 ### plain `switch` (baseline)
 - is the zero-dependency baseline — pair it with
  [`eslint-plugin-strict-pattern-matching`](https://www.npmjs.com/package/eslint-plugin-strict-pattern-matching)
  for exhaustiveness
 - is a statement, not an expression, so it cannot produce a value directly
 - leaves the `never` guard to you; tiny-pattern-ts is an expression and does not
  need one
 The [TC39 pattern-matching proposal](https://github.com/tc39/proposal-pattern-matching)
 is still stage 1, so userland libraries remain the only option today.
 ## License
-MIT © 2025 tmu. See [LICENSE](./LICENSE).
+MIT © 2026 tmu. See [LICENSE](./LICENSE).
 ## Contributing
@@ -6,68 +6,9 @@ Backlog and tracking for tiny-pattern-ts. Managed in vscode-todotasks format.
 Setup:
 ☐ Split off template into separate package => pi --session 01a07dde-7050-7054-bb36-1606d7eb2bc3 @low
 ✔ straighten oxc rules @done
    ✔ oxc forbids ternary => remove oxc rule @done
    ✔ oxc wants comments to start comments with a capital letter => remove oxc rule @done
    ✔ there already exists a /* */ block comment in primitive.ts, => change to multi-line comment @done
 ✔ Remove example code files and its documentation and its exports from index.ts @high @done
    ✔ remove src/match.ts and its documentation @high @done
    ✔ remove src/pattern.ts and its documentation @high @done
    ✔ remove src/index.test.ts and its documentation @high @done
    ✔ exports from `src/index.ts` should only be the public API surface @done
 v1.0:
 ☐ API surface is stable and fully typed
    ☐ Finalize public exports in `src/index.ts`
    ☐ Document all exported types and functions
    ☐ Add JSDoc for public APIs
 ☐ Test coverage meets threshold
    ☐ Achieve 100% branch coverage on `src/primitive.ts`
    ☐ Achieve 100% branch coverage on `src/index.ts`
 Testing:
 ✔ Cover autocomplete with real completion test cases in the suite @medium @done
    → `src/util/__tests__/lsp-completion.ts` (`#test-utils/…`) is the helper; the suite asserts its labels (see development/testing.md § Autocomplete)
    → wire it into `node --test` so a test asserts the offered labels
    → note: `Parameters<typeof factory>[0]` resolves only the *last* overload; use `@ts-expect-error` call sites for factory negatives, not `not.toExtend<Parameters<…>>`
 ✔ Drive the LSP completion helper through the LSP protocol library instead of a hand-rolled JSON-RPC client @medium @done
    ✔ Add `vscode-languageserver-protocol` and record the tooling decision @done
    ✔ Rewrite `src/util/__tests__/lsp-completion.ts` onto `createMessageConnection` and typed requests @done
    ✔ Update `development/testing.md § Autocomplete` for the new client @done
    ✔ Run `npm run verify` and check the task off @done
 Matcher:
 ✔ Clean up: adopt the 3-overload matcher (`src/prototype-ac2.ts`) and delete the prototypes @high @done
    → `getMatcher` / `getMatcherW`, each with overloads `ExhaustiveLoose` → `Fallback` → `Handlers` (order is load-bearing)
    → fold into `src/primitive.ts` / the public API; drop `src/prototype*.ts`
 ☐ `_` should receive only the unhandled `T` keys, not all of `T` @medium
    → today `_: (shape: T) => R`; desired `_: (shape: Exclude<T, handledKeys>) => R`
 ☐ An exhaustive pattern that also carries `_` must be a compile error @medium
    → `{ a, b, _ }` for `T = "a" | "b"` is accepted today; the redundant `_` should be rejected
 Bugs:
 ✔ TS 7 LSP server logs `context canceled` on stderr at shutdown @done
    → `handleExit` returns `io.EOF`, cancelling the background context while `Session.updateWatches` is still in flight; the bare error is flushed to stderr and the server exits 1
    → close stdin after `shutdown` instead of sending `exit`; the server exits cleanly (code 0, no output), kill kept as a fallback
 Enhancements:
 ☐ Allow boolean literals in primitive union patterns (e.g. `true: () => "yes"`) @medium
 ☐ Are there other primitive types that should be supported in union patterns? (e.g. `bigint`, `symbol`) @medium
 Documentation:
 ☐ Bring README.md back to its previous form — synopsis and examples restored, in the correct place
    → previous section order: title, tagline, Synopsis, Description, Requirements, Examples, API, License, Contributing
    → previous Examples order: literal/exhaustive, typeof, structural/discriminated unions, when, any
 ☐ Create `examples/` directory with runnable snippets
 ☐ Add comparison section vs. other TS pattern-matching libs in Readme.md
 ☐ Write migration guide for users coming from discriminated unions
 ☐ Create backlog tasks for implementation
 ✔ Document the matcher design paths in `development/` — union vs overload merge, inferred universe (`NoInfer`), conditional `RequireKeys`, cases-first — and why each was abandoned @done
 ☐ Validate code fences in Markdown (start with README.md) — compile the TypeScript examples against `src/` so the docs cannot drift from the API
 Workflow:
 ✔ Resolve the finish/push tension: `create:finish` leaves `main` ahead of its upstream while `create:branch` refuses until `main` matches upstream — decide whether `finish` should push or `branch` should compare only `BEHIND` (see development/workflow.md) @done
 Maintenance:
 ☐ Serve CI coverage over a tiny self-hosted webserver (replace the zip artifact) @low
@@ -81,3 +22,4 @@ Maintenance:
    ☐ Add a minimal dir-listing webserver to the gitea docker setup for serving landing page (reuse existing reverse proxy)
    ☐ CI writes landing page to a shared volume keyed by project + tag (e.g. `/landing/tiny-pattern-ts/<tag>/`)
    ☐ Browse to `…/tiny-pattern-ts/index.html` in the browser
 ✔ Add testing with the TypeScript floor in CI @done
@@ -0,0 +1,89 @@
 // Consumer smoke test for the minimum supported TypeScript (see README
 // § Requirements). It imports the package by name, so it resolves through the
 // `exports` map to the emitted `dist/*.d.ts` — including the relative `.ts`
 // specifiers they keep — rather than to the source. Run by `npm run test:compat`
 // and the CI `compat` job only; never by `check` / `verify`.
 //
 // Why the `expectTypeOf` assertions: a compile that merely succeeds is a weak
 // oracle. An `any`-typed declaration would compile, but `expect-type`'s exact
 // equality rejects `any`, so the assertions prove the emitted types are real.
 // Every handler *parameter* is asserted too, not just the matcher: the handler's
 // member type comes from the `Member` inversion in the declarations, and a wrong
 // or `any` parameter would otherwise slip through, since the matcher's own
 // `(shape: T) => R` type is built from `T` and the handler returns. See
 // development/ci.md § TypeScript compatibility.
 import { expectTypeOf } from "expect-type";
 import {
    getPrimitiveUnionMatcher,
    getPrimitiveUnionMatcherW,
    getTaggedUnionMatcher,
    getTaggedUnionMatcherW,
 } from "tiny-pattern-ts";
 type ResultCode = "ok" | "created";
 const toStatus = getPrimitiveUnionMatcher<ResultCode>()({
    ok: (s) => {
        expectTypeOf(s).toEqualTypeOf<"ok">();
        return "OK";
    },
    created: (s) => {
        expectTypeOf(s).toEqualTypeOf<"created">();
        return "CREATED";
    },
 });
 expectTypeOf(toStatus).toEqualTypeOf<(shape: ResultCode) => string>();
 // The widening twin keeps each handler's own return type in the union.
 const toStatusW = getPrimitiveUnionMatcherW<ResultCode>()(
    {
        ok: (s) => {
            expectTypeOf(s).toEqualTypeOf<"ok">();
            return "OK" as const;
        },
    },
    (rest) => {
        expectTypeOf(rest).toEqualTypeOf<"created">();
        return "CREATED" as const;
    },
 );
 expectTypeOf(toStatusW).toEqualTypeOf<
    (shape: ResultCode) => "OK" | "CREATED"
 >();
 type Contact =
    | { kind: "email"; address: string }
    | { kind: "phone"; number: string };
 const format = getTaggedUnionMatcher<Contact>()("kind")({
    email: (e) => {
        expectTypeOf(e).toEqualTypeOf<{ kind: "email"; address: string }>();
        return e.address;
    },
    phone: (p) => {
        expectTypeOf(p).toEqualTypeOf<{ kind: "phone"; number: string }>();
        return p.number;
    },
 });
 expectTypeOf(format).toEqualTypeOf<(shape: Contact) => string>();
 const formatW = getTaggedUnionMatcherW<Contact>()("kind")(
    {
        email: (e) => {
            expectTypeOf(e).toEqualTypeOf<{ kind: "email"; address: string }>();
            return e.address;
        },
    },
    (rest) => {
        expectTypeOf(rest).toEqualTypeOf<{ kind: "phone"; number: string }>();
        return rest.number;
    },
 );
 expectTypeOf(formatW).toEqualTypeOf<(shape: Contact) => string>();
 export { format, formatW, toStatus, toStatusW };
@@ -0,0 +1,15 @@
 {
    "extends": "@tsconfig/strictest/tsconfig.json",
    "compilerOptions": {
        "lib": ["es2024"],
        "module": "nodenext",
        "target": "es2024",
        "types": ["node"],
        "skipLibCheck": false,
        "noEmit": true,
        "allowImportingTsExtensions": true,
        "verbatimModuleSyntax": true
    },
    "include": ["../src", "../scripts", "*.ts"],
    "exclude": ["../src/doc-test"]
 }
@@ -43,7 +43,10 @@
        "silverwind",
        "idris",
        "todotasks",
-        "connor"
+        "connor",
        "injective",
        "injectivity",
        "userland"
    ],
    "ignorePaths": ["dist", "node_modules", "coverage", "*.svg", ".gitignore"]
 }
@@ -24,6 +24,7 @@ One file per category:
 | [workflow.md](./workflow.md)     | Branching and merging, script prefixes, feedback tiers, commit messages |
 | [tooling.md](./tooling.md)       | Toolchain choices and configuration, editor setup                       |
 | [testing.md](./testing.md)       | Test strategy and type-driven development                               |
 | [docs.md](./docs.md)             | Validating the Markdown code fences in the prose docs                   |
 | [ci.md](./ci.md)                 | CI pipeline, runner image, coverage serving                             |
 | [publishing.md](./publishing.md) | Release and npm publishing                                              |
@@ -6,6 +6,12 @@ the job graph; this file records why it is shaped the way it is.
 ## Pipeline
 - **`build`** (push to `main` / tag) — build + correctness + packaging.
 - **`compat`** (CI only) — type-check the suite and a consumer fixture against
  the minimum supported TypeScript; consumes `build`'s `dist/` and gates
  `publish`. It has **no local tier**: it never runs in a hook or in
  `check` / `verify` / `test:ci`; run it by hand with
  `npm run build && npm run test:compat`. See
  [§ TypeScript compatibility](#typescript-compatibility).
 - **`maintain`** (push to `main`, non-blocking) — `npm run maintain`; reports,
  never fails the build.
 - **`publish`** (tag) — packaging checks + `publish:publint` / `publish:attw`,
@@ -97,6 +103,106 @@ Leave `act_runner`'s `force_pull` disabled.
  (`docker rmi gitea.e1nsnull.de/tmu/act-ci:<version>`); do not reach for
  force-pull.
 ## Coverage threshold
 #### Decision (2026-09)
 `npm run test:ci` fails below 100% statements / branches / functions / lines
 across `src/**/*.ts` (`c8 --all --include "src/**/*.ts" --100`). The gate rides
 the `build` job; `npm run verify` stays coverage-free.
 #### Why
 - The types are the feature, so an untested branch is a hole in the contract,
  not a metric to trade off; 100% is the only threshold that means "no hole".
 - `--all` counts a `src/` file no test imports. Without it c8 reports only the
  files the suite happened to load, so a new untested module is invisible and
  the threshold passes vacuously.
 - The gate rides `test:ci`, which `build` already runs — no new job or step.
 - `verify` stays fast and local; the slower coverage run is a CI-only tier (see
  [workflow.md § Feedback tiers](./workflow.md#feedback-tiers)).
 #### Rejected
 - Per-file thresholds: a global 100% already forces every counted file to 100%.
 - A `check:coverage` script: it would re-run the suite or read c8's temp dir,
  and no `check:*` script runs tests.
 - `--all` without `--include`: it would also sweep `scripts/`, which is not the
  shipped surface.
 #### Known issue
 - `src/matcher-shared.ts` is types only, so its runtime image is empty; c8 still
  lists it under `--all`. It carries a file-level `/* c8 ignore start */` with
  the reason. Adding runtime code there means removing that directive.
 ## TypeScript compatibility
 #### Decision (2026-09)
 A dedicated `compat` job runs `npm run test:compat` — the `npx`-pinned
 TypeScript 5.9 compiler (`typescript@5.9.2`) over `compat/tsconfig.json` —
 against the `dist/` artifact `build` produced, and `publish` requires it. The
 floor is TypeScript 5.9, pinned in the `test:compat` script itself (the single
 source of truth) and documented in [README § Requirements](../README.md#requirements).
 #### Why
 - The compiler is a **different major** from the repo's TypeScript 7, so it is
  resolved by `npx` at run time. It must never appear in `devDependencies`: that
  would install it for every local `npm ci` and drift the lockfile, which would
  put a second compiler in the local `check` / `verify` loop and every editor.
 - **CI-only is the point.** `npx` fetches over the network — like `maintain`'s
  scans, a network-bound check is never a local feedback tier (see
  [workflow.md § Feedback tiers](./workflow.md#feedback-tiers)). It is not in
  `check`, `verify`, `test:ci` or any hook; locally it is run **by hand** with
  `npm run build && npm run test:compat`.
 - **`compat` consumes `build`'s artifact** rather than rebuilding, so it judges
  the exact bytes `check`, `test:ci` and `publint` saw.
 - **`compat` gates `publish`** because the types are the feature: an artifact
  that is not consumable at the advertised floor must not ship.
 - **The fixture is a consumer, not a unit test.** `compat/fixture.ts` imports
  the package by name (`tiny-pattern-ts`), so it resolves through the `exports`
  map to `dist/index.d.ts` and exercises the emitted declarations' relative
  `.ts` specifiers — not the source. `expectTypeOf`'s exact-equality assertions
  are load-bearing: a bare compile would also pass if a declaration collapsed to
  `any`; they reject that.
 #### Rejected
 - **A `devDependencies` alias** (`npm:typescript@5.9`): installs the legacy
  compiler locally, defeating "CI only".
 - **A second lockfile / sub-project** (`compat/` with its own `npm ci`): a
  pinned, reproducible matrix, but a whole extra lockfile to maintain for one
  compiler. `npx -p` is enough.
 - **A `paths` / `moduleSuffixes` redirect** to typecheck the _existing_ suite
  against `dist/` without touching it: `paths` cannot remap the relative
  `./index.ts` imports the tests use; `moduleSuffixes` only lets _missing_
  source resolve to suffixed copies, so it would need generated `.compat.ts`
  declarations staged into `src/` (plus excludes). Both spend more than the
  fixture buys. See the [handover](../backlog.tasks) discussion.
 - **Writing the fixture against source** (relative import): it would prove the
  source compiles under 5.9, not that the _published_ declarations do, which is
  the promise consumers rely on.
 - **Replacing `attw`**: `attw` owns the full resolution matrix
  (`node10`/`node16`/`nodenext`/`bundler`); `compat` answers only "does the
  documented floor compile the artifact".
 #### Known issue
 - `@tsconfig/node26` cannot be extended: its `lib: ["es2025", ...]` and
  `target: es2025` are rejected by 5.9 (`TS6046`). `compat/tsconfig.json`
  extends only `@tsconfig/strictest` and sets `lib` / `target: es2024`, the
  ceiling 5.9 accepts.
 - `skipLibCheck: false` is deliberate — it is what makes the floor honest
  (`type-fest` pins it at 5.9), rather than hiding a broken dependency d.ts
  behind `true`.
 - The version appears in both the `test:compat` script and the README; a floor
  bump is a two-file change. The script is authoritative.
 - `src/doc-test` is excluded from `compat/tsconfig.json`. The generated examples
  are checked against the source by their own project; `test:compat` covers the
  suite plus the fixture.
 ## Coverage serving
 #### Decision (2026-09)
@@ -0,0 +1,61 @@
 # Docs
 Why the prose documentation is maintained the way it is. The actionable rules
 are in [CONTRIBUTING.md](../CONTRIBUTING.md); this file records the rationale.
 ## Validating Markdown code fences
 #### Decision (2026-11)
 Compile every `ts / `typescript fence in the prose docs into a real
 `node:test` case under `src/doc-test/__generated__/`, typechecked by a scoped
 `tsc` project and executed by `node --test`.
 #### Why
 - A documented example is a promise about the API. Left unchecked it drifts the
  moment a signature changes, and a reader copies broken code.
 - The repo runs TypeScript 7, the native/Go compiler. It exposes **no legacy JS
  compiler API** (`ts.createProgram`, `ts.transpileModule`, `ts.createSourceFile`
  are all `undefined`; `Object.keys(require("typescript"))` is
  `["version", "versionMajorMinor"]`). So `@typescript/vfs`, the type-aware
  `eslint-plugin-markdown` and `docs-ts` / `@effect/docgen` cannot run here.
 - `node --check` parses as JS and rejects valid TS type annotations, so it is not
  a gate. The only faithful validator is the `tsc` **CLI**, which means emitting
  real `.ts` files and letting the existing `check:tsc` / `node --test` pipeline
  judge them.
 #### Rejected
 - **A packaged doc-test tool** (see above) — no usable compiler API on TS 7.
 - **Embedding a typecheck in the generator** — duplicates the gate, and would
  not exercise the repo's own resolution.
 - **`node --check`** — wrong language level.
 #### Known issue
 - Scanned sources are hard-coded to `README.md` and `CONTRIBUTING.md`. A
  `docs/` + `examples/` list is the natural extension; `development/` must never
  be scanned (its fences are illustrative, not compilable).
 - The generator hoists and merges leading imports, rewrites `tiny-pattern-ts` to
  the `#test-tiny-pattern-ts` source alias, and rejects an example that imports
  `node:assert` / `node:test` (the prelude already binds both). Titles are the
  immediately preceding paragraph; a fence with no such paragraph is a fatal
  error, which keeps every example described.
 - `oxlint src/doc-test` reports "No files found" because the generated
  `*.test.ts` are gitignored. That is cosmetic: the files are still typechecked
  and run.
 - The generated tests are `*.test.ts`, which c8's default excludes already keep
  out of the `--100` gate. Do not add an `--exclude` for them: passing any
  `--exclude` replaces the defaults, so every hand-written test file and
  `__tests__/` helper re-enters coverage and the gate fails.
 - Generated examples must not run under `c8`: an example could cover a line no
  hand-written test reaches, so the coverage gate would pass on documentation
  alone. `test:coverage` therefore runs c8 over the tracked tests only
  (`git ls-files 'src/*.test.ts'` — the generated files are untracked), and
  `test:doc` runs the examples in a separate process without c8. `test:ci`
  chains the two, so correctness and coverage stay independent.
 - The CI `build` job runs `npm run create:doc-tests` as an explicit step before
  `npm run test:ci`, not a `pretest:ci` lifecycle hook: the hook hides the step
  from the job log and makes `test:ci` behave differently under npm than when
  run directly.
@@ -3,91 +3,309 @@
 The type-level design of the public API and the limitations it carries. The
 user-facing reference is [README § API](../README.md#api).
-The matcher below is implemented in `src/primitive.ts` and re-exported from
+The matchers are implemented in `src/primitive-union.ts` (`getPrimitiveUnionMatcher` /
-`src/index.ts` as `getMatcher` / `getMatcherW`; the rest of the library is
+`getPrimitiveUnionMatcherW`) and `src/tagged-union.ts` (`getTaggedUnionMatcher` /
-placeholder code.
+`getTaggedUnionMatcherW`), re-exported from `src/index.ts`; the rest of `src/`
 is implementation detail.
 ## Public surface
 #### Decision (2026-09)
 `src/index.ts` exports the four factories and nothing else. Every exported
 function carries TSDoc; the builder types and the `matcher-shared.ts`
 vocabulary stay internal.
 #### Why
 - The factories are the whole contract: a consumer calls one and never needs to
  name the builder type it returns.
 - The builder interfaces are already the inferred return types, so they travel
  into the emitted `.d.ts` regardless. Exporting them would only make them
  nameable while freezing the internal `Strict` / `Widening` overload split as
  API.
 - TSDoc travels into the emitted declarations, so editor hovers and the
  published package document the API without a hand-written `.d.ts`.
 #### Rejected
 - **Exporting the builder types** (`PrimitiveUnionMatcher`, …). Nameable, but it
  grows the surface for no call-site benefit and pins the `Strict` / `Widening`
  split.
 - **Exporting the `matcher-shared.ts` vocabulary** (`Matchable`, `UnaryFn`,
  `PatternKey`, `Member`, `PatternReturns`, …). They appear in the public
  signatures, but a consumer never needs to name them; exporting them would
  freeze plumbing as API.
 - **A hand-written `.d.ts` or a separate API document.** It would drift from the
  implementation; TSDoc is generated from the source.
 ## Matcher shape
 #### Decision (2026-09)
-A matcher is built by a factory and applied to a pattern:
+A factory takes the universe and returns a builder; the builder takes a handler
 map and an optional fallback:
 ```ts
-const matcher = getMatcher<"a" | "b">()({ a: (s) => …, b: (s) => … });
+const matcher = getPrimitiveUnionMatcher<"a" | "b">()({ a: (s) => …, b: (s) => … });
 const fallback = getPrimitiveUnionMatcher<"a" | "b" | "c">()({ a: (s) => … }, (s) => …);
 ```
-Whether the pattern is exhaustive or has a fallback is decided **at the call
+Exhaustive or fallback is decided **at the call site**, by whether the second
-site**, by whether it carries `_` — F#'s `| _ ->`. Only the return-strictness
+argument is present. The fallback's parameter is the remainder
-axis remains, so there are two factories:
+`Exclude<T, keyof Handled>`. Only the return-strictness axis remains, so there
 are two factories:
- `getMatcher` — one common `R`, the best common return type of every handler;
+- `getPrimitiveUnionMatcher` — one common `R`; the fallback must fit it;
- `getMatcherW` — the union of every handler's return type.
+- `getPrimitiveUnionMatcherW` — the union `PatternReturns<Handled> | R`.
-Both are three overloads whose order is load-bearing:
+Each factory is two overloads whose order is load-bearing:
-1. `ExhaustiveLoose<R, T>` = `{ [K in T]: UnaryFn<K, R> } & { _?: UnaryFn<T, R> }`
+1. `Handlers<T, R>` — the exhaustive form, and the contextual type of the
-2. `Fallback<R, T>` = `Partial<…> & { _: UnaryFn<T, R> }`
+   handler-map popup;
-3. `Handlers<R, T>` — the pure exhaustive shape
+2. `Handled extends Exact<Partial<Handlers<T, R>>, Handled>` intersected with
   `MustBePartial<T, Handled>`, plus `Fallback<T, Handled, R>` — a partial
   handler map plus the fallback, rejected when the map already covers `T`.
 #### Why
- **Autocomplete reads the first overload, the error reads the last.**
+- **The fallback is an argument, not a property.** TypeScript fixes a property's
-  TypeScript takes the first overload signature as the contextual type for the
+  contextual type before it infers its sibling keys, so `_: (s) => …` in the
-  object-literal popup, and the last for `No overload matches this call`. So
+  handler map can only see all of `T`, never `Exclude<T, keyof Handled>`. A later
-  `ExhaustiveLoose` first yields the popup `_?, a, b` (T-keys required, `_`
+  argument is contextually typed from inference on an earlier one, so the split
-  optional) while `Handlers` last yields `Property 'b' is missing`. The two can be
+  is what makes the remainder expressible.
-  tuned independently.
+- **The redundant-fallback guard is an F-bounded constraint.** A map that
- Two factories, not four: the fallback is a pattern _shape_, not a separate API.
+  already covers `T` plus a fallback is rejected by folding
- The widened return union is derived from the pattern's handler types, so it
+  `MustBePartial<T, Handled>` into `Handled`'s own constraint. The guard is
-  needs no fourth signature.
+  checked _after_ `Handled` is inferred, so the contextual pass that types the
  handler callbacks survives. The obvious conditional
  `Exclude<T, keyof Handled> extends never ? …` in the fallback's parameter
  type is evaluated while `Handled` is still its constraint and rejects every
  partial map whose callbacks are context-sensitive.
 - **Overload order keeps both messages.** #1 supplies the contextual type
  (`a, b, c`); #2 accepts a partial map once a fallback is present, so its popup
  is optional (`a?, b?, c?`). A gap without a fallback is reported against #1.
 - **`R` needs an inference site.** `R` inside the `Exact<…>` constraint is not
  one, so `handlers: Handled & Partial<Handlers<T, R>>` re-adds it; without that
  `R` collapses to `unknown` when the handler params are inferred.
 - **`Exact` restores the excess-property check.** TypeScript skips it for a
  generic constraint, so without `Exact` the handler map accepts keys outside
  `T`.
 - Two factories, not four: the fallback is an argument, not a separate API.
 #### Rejected
- **Four factories** (exhaustive and fallback each split by return handling).
+- **Single-object `_`** (the former shape). `_` sees only all of `T`; the
-  The exhaustive/fallback axis is expressible as one pattern type; four
+  remainder is not expressible there, and an exhaustive map plus `_` was
-  signatures duplicate it.
+  accepted.
- **Union merge** — one type `Exhaustive<R,T> | (Partial<…> & { _: … })`,
+- **Curried handlers-first** — `(handlers)(fallback)`. Rejected: two calls for
-  explicit `<T>()`. Type-safe and completable, but TypeScript reports the
+  the common case. It is not needed for the redundant-fallback guard, which the
-  near-miss union member, so a missing key reads `Property '_' is missing`
+  F-bounded constraint already provides (see Why).
-  instead of naming the key. Arm order does not change the report; the overload
+- **`this` / HKT self-reference.** `this` is post-construction (method bodies,
-  split does.
+  return positions); a parameter's contextual type is pre-construction.
- **Overload merge with only the exhaustive arm last.** Fixes the missing-key
+  `keyof this` in an interface method is the interface, not the literal.
-  message, but a wrong `_` parameter is then reported against the exhaustive
+- **Variance / `const` type parameters / `NoInfer` / `unique symbol` brands /
-  arm, and `Parameters<typeof factory>` sees only one arm.
+  defaulted type-param guards.** None change inference or evaluation order;
- **Inferred universe** — `match(pattern)` with `T` taken from the keys
+  `in`/`out` on the handler map broke contextual typing outright. `NoInfer`
-  (exhaustive) or from `_`'s annotated parameter (fallback), via `NoInfer<T>` and
+  specifically leaks into the emitted `.d.ts`, which would raise the consumer
-  `_?: never`, split by overloads (a plain union merges inference; measured
+  floor above the documented one (see [README § Requirements](../README.md#requirements)).
-  `T = "_" | "a"`). No explicit `<T>`, and pipe-friendly. Rejected because: with
+- **Union merge**, **overload merge with only the exhaustive arm last**,
-  no declared universe the exhaustive popup offers only `_`; an unannotated `_`
+  **inferred universe**, **conditional `RequireKeys`**, **cases-first curried** —
-  widens `T` to `string | number`; and `NoInfer` leaks into the emitted `.d.ts`,
+  decided against while the API was single-object; their reasons (reported
-  raising the consumer floor to TypeScript 5.4 (README promises `>= 5.0`).
+  near-miss member, no `_` in the exhaustive popup, `NoInfer`/floor, `keyof P`
- **Conditional `RequireKeys`** — parameter
+  counts optional keys, not pipe-friendly) hold where they still apply.
  `P & ("_" extends keyof P ? unknown : Handlers<R, T>)`. Gives the good
  missing-key message, but `keyof P` counts _optional_ keys: a widened value
  whose declared type has `_?:` bypasses the completeness check. Demanding a
  required `_` instead rejects that case but breaks `P` inference — `P` falls back
  to its constraint and partial literals then demand every key. Typos also need a
  `NoExtra` guard, whose message degrades to `not assignable to never`.
 - **Cases-first curried** — `match(["a", "b"])({ a: …, b: … })`. Completion works
  for exhaustive patterns, and the array is a single source of truth for the
  runtime list and the union. Rejected as not pipe-friendly; it needs a runtime
  array; and the single-call form `match(cases, pattern)` cannot infer `R` (the
  mapped key type `K[number]` stays deferred, so `R` widens to `unknown`).
 #### Known issue
- The `_` handler receives **all** of `T`, not the unhandled subset
+- `PatternReturns` must be
  (`Exclude<T, handledKeys>`).
 - An exhaustive pattern that also carries `_` is accepted; the redundant `_`
  should be a compile error.
 - The widened overloads carry a completeness guard
  `keyof P extends T | "_" ? unknown : never`, because TypeScript does not apply
  the excess-property check to a generic constraint: a generic parameter accepts
  extra keys, a parameter typed as a concrete object type does not.
  `PatternReturns` must be
  `ReturnType<Extract<ValueOf<P>, (...args: never[]) => unknown>>` so it survives
  the closed, partly-optional `P` constraints.
 - `Parameters<typeof factory>[0]` resolves only the **last** overload, so it is
  not a sound "rejected" oracle for a factory. Factory-negative tests use
  `@ts-expect-error` call sites (the test file only — the general ban stands).
 ## Shared internals
 #### Decision (2026-09)
 `src/matcher-shared.ts` holds the universe-agnostic pieces both matchers use:
 `UnaryFn`, `PatternReturns`, `RedundantFallback`, `HandlerMap`, the shared
 `Matchable` universe, the `PatternKey` key projection and its `Member` inverse,
 and the `Stringified` / `Collisions` / `UnsupportedReason` / `UnsupportedUniverse`
 / `UniverseGate` universe gate.
 #### Why
 - `RedundantFallback`'s property name is the diagnostic, so one definition
  keeps the two matchers' message from drifting; the other pieces appear
  verbatim in both public signatures or are the same projection over each
  matcher's universe.
 - **`Matchable` is one definition, not two.** The primitive-union matcher's
  universe and the tagged-union matcher's allowed `Tag` values are the same set,
  so aliasing them keeps the two matchers from drifting apart on what they
  accept (`symbol`/`bigint` rejected once).
 #### Rejected
 - **A generic `Matcher<Universe>` over the interface pair, `Handlers`,
  `Fallback` and `MustBePartial`.** Each is built from its own universe
  (`Tags`/`MapTaggedUnion` vs the primitive values); abstracting over the
  F-bounded `Handled` constraint that makes the remainder work risks the
  contextual typing it exists to preserve. `Matchable`, the `PatternKey` /
  `Member` projection and the `UniverseGate` are the pieces both universes
  genuinely share.
 ## Supported universes
 #### Decision (2026-09)
 A universe must be a **finite union of literals** with **no
 value/stringification collision**. Broad types (`string`, `number`, a template
 literal) and `"true" | true` / `1 | "1"` are rejected; the factory intersects
 `UniverseGate<T>` (the `UnsupportedUniverse<Reason>` diagnostic) into the
 handler and fallback parameters. `Member<T, K>` replaces the `PatternParam<K>`
 inversion: the handler parameter is the member(s) of `T` whose `PatternKey` is
 `K`, so a standalone `"true"` is `"true"`, not `true`.
 #### Why
 - **`PatternKey` is not injective.** `"true"` and `true` (and `1` / `"1"`)
  share a runtime key, so `PatternParam<K>` cannot recover the member.
  `Member<T, K>` inverts against `T`, which is exact.
 - **Broad types cannot be proven exhaustive.** An index-like map lets a partial
  object satisfy the exhaustive overload and reaches the `dispatch` throw.
  Rejecting at the boundary avoids threading an open/closed branch through
  `Handlers`, `Fallback` and `MustBePartial`.
 - **The finite-literal predicate is `IsLiteral<PatternKey<T>> extends true`.**
  `IsLiteral` is `boolean` for a union that mixes a literal with a broad type
  (`"a" | \`x-${number}\``), so `extends false`would treat the mix as
 supported;`extends true` is the check that rejects it.
 - **Collisions are rejected, not merged.** `Member<T, K>` would be sound (the
  handler gets the union), but the API is one handler per member; rejecting
  keeps `Member` a singleton and the remainder exact.
 - **The collision predicate is type-checkable.** `Collisions<T> =
 Extract<T, Stringified<T>>` catches numeric collisions too.
 - **The gate is an intersection, not a branch,** so `R` inference and the popup
  survive; a conditional parameter type would not.
 #### Rejected
 - **Open universes with a required fallback** (`fix/open-universe-*`): sound,
  but left the collision hole and added an `IsLiteral` /
  `OpenUniverseNeedsFallback` branch through every handler type. Findings, kept
  so they are not re-run: `{}` satisfies an index signature (and `Exact` misses
  it); an index signature dominates contextual typing; `R` infers only from a
  non-self-referential parameter type (`{ [K in keyof H]: … R … }` gives
  `unknown`); an F-bounded guard referencing `keyof Handled` in `Handled`'s own
  constraint sees the constraint, not the map; all handlers share one `R` (only
  the fallback widens it); `IsLiteral` is the finite-literal predicate. The
  user-facing consequence — open universes are a parsing or registry concern,
  not a dispatch one — is guidance in README § Why open universes are rejected.
 - **`Member<T, K>` without the gate:** sound, but a colliding handler gets a
  union and `1 | "1"` stays one runtime key.
 - **A round-trip injectivity gate** (`IsEqual<T, PatternParam<PatternKey<T>>>`):
  over-rejects standalone `"true"` / `"false"` / `"null"` / `"undefined"`.
 - **A case-list / ts-pattern builder:** removes the collision class but drops
  the object map (footprint, popup) and reimplements an existing library.
 - **Normalize numeric keys to strings:** makes `PatternKey` injective but
  changes "numeric keys stay numbers" and defeats the numeric dispatch fast
  path.
 #### Known issue
 - A multi-collision universe lists every collision in the diagnostic.
 - The `dispatch` throw is unreachable through the typed API; the throw tests
  widen the factory to `Function` to reach it.
 ## Tagged-union matcher
 #### Decision (2026-09)
 `getTaggedUnionMatcher` / `getTaggedUnionMatcherW` mirror the primitive-union pair
 with one extra curried step for the discriminant key:
 ```ts
 type Shape =
    | { kind: "circle"; radius: number }
    | { kind: "square"; side: number };
 const area = getTaggedUnionMatcher<Shape>()("kind")({
    circle: (s) => Math.PI * s.radius ** 2,
    square: (s) => s.side ** 2,
 });
 const fallback = getTaggedUnionMatcher<Shape>()("kind")(
    { circle: (s) => … },
    (s) => …, // s: { kind: "square"; side: number }
 );
 ```
 The key is a separate call because `K` is inferred from its literal argument and
 `T` is fixed by the first factory; one call could not infer both.
 `Discriminated<T>` restricts the key to properties whose values are tags.
 #### Why
 - **Same fallback/remainder machinery as the primitive-union matcher.** `HandledTags`
  recovers the tag values the map handled (`Member<Tags, keyof Handled>`) and
  `Narrowed<T, K, Exclude<Tags, …>>` is the fallback's parameter; the
  redundant-fallback guard is the same F-bounded constraint. Only the "universe"
  changes — `T`'s members instead of primitive values.
 - **`T extends object`, not `Record<PropertyKey, unknown>`.** An `interface` has
  no implicit index signature, so the `Record` constraint would reject
  interface-based unions. The runtime reads the tag off `object` with one
  assertion, the tagged twin of the primitive-union dispatch's `shape as string | number`.
 - **`Narrowed` distributes over `T`, narrowing `K` to the tag.** A member whose
  `K` cannot take the tag drops out; a duplicated tag yields a union of members
  instead of dropping one. `T[K] extends V` returns the exact member (a
  discriminated union's declared interface) untouched, so the mapped form only
  handles a property that is itself a union.
 - **A union-valued or optional discriminant is supported.** A single shape whose
  property is a union (`{ color: "red" | "green" | "blue" }`) is narrowed per
  handler instead of being passed `never`. Matching a defined tag on an optional
  property (`{ type?: "x" }`) proves the key is present, so it becomes required
  (`{ type: "x" }`); the `undefined` tag narrows it to `{ type?: never }` under
  `exactOptionalPropertyTypes` (absence) or `{ type?: undefined }` when the
  property explicitly admits `undefined`.
 - **A `boolean` / `null` / `undefined` tag goes through the shared
  `PatternKey` / `Member` projection.** `Discriminated` admits those tags
  (they are in `Tag`), but they cannot key a mapped type, so the handler map is
  keyed by the stringified form (`true` → `"true"`) and `Member` inverts it
  against the tag set to recover the member. This is the same projection the
  primitive-union matcher uses over its universe, which is why it lives in
  `matcher-shared.ts`.
 #### Known issue
 - A tag need not be unique across the union. Two members sharing one is not a
  soundness hole: they select a single runtime key, so one handler receiving
  their union is the only correct behavior — the key is simply not a
  discriminant. The gate rejects only the distinct-value collision
  (`true | "true"`), where two values share a key and `Member` can no longer
  invert it; see § Supported universes. Pinned by the duplicate-tag tests in
  `src/tagged-union.test.ts`.
 ## Primitive universe
 #### Decision (2026-09)
 The universe (`Matchable`) is `string | number | boolean | null | undefined`,
 with `boolean` admitted as `true | false`.
 `boolean`/`null`/`undefined` are not property keys, so handler-map keys are a
 projection (`PatternKey`: each member stringified) and `Member` inverts it
 against the universe, so callbacks receive the real member (`true`, not
 `"true"`; the standalone string `"true"` stays `"true"`). The popup offers
 `true`, `false`, `null`, `undefined` by name (verified over LSP). The same
 projection is shared with the tagged-union matcher; see § Tagged-union matcher.
 The supported universes are constrained as described in § Supported universes.
 #### Why
 - Runtime dispatch indexes with the raw `shape`; `handlers[true]` coerces to
  `"true"` at runtime exactly as `String` would. The `shape as string | number`
  assertion only placates `TS2538` and buys the number fast path (an explicit
  `String()` defeats V8's numeric-key path: measured ~2× on number-keyed
  dispatch).
 - `symbol`/`bigint`/`NaN`/`-0` are rejected, and a member colliding with its
  stringification is rejected by the gate: user-facing, stated once in
  [README § Caveats](../README.md#caveats).
@@ -28,14 +28,49 @@ before the implementation.
 - Runtime-first (classic red/green): it verifies the value, not the contract,
  and the contract is the product.
 - Testing the type only: it would not catch handler dispatch or the `_`
-  fallback (see `src/primitive.test.ts`).
+  fallback (see `src/primitive-union.test.ts`).
 The runner is `node --test --strip-types "src/**/*.test.ts"` and the tiers are
 in
 [CONTRIBUTING.md § Development commands](../CONTRIBUTING.md#development-commands).
 `c8` uses V8 coverage, so the `--strip-types` source is instrumented without a
 build step, and the runner relies on the `.ts` import-extension convention (see
-[tooling.md](./tooling.md#source-imports-use-ts-extensions)).
+[tooling.md](./tooling.md#source-imports-use-ts-extensions)). CI gates that
 coverage at 100% (see [ci.md § Coverage threshold](./ci.md#coverage-threshold)).
 ## Handler arguments
 #### Decision (2026-09)
 A handler's `expectTypeOf(shape)` is always paired with an assertion on the
 argument `dispatch` actually passed: `assert.equal` where the handler runs for
 one shape, `assert.ok(s === … || s === …)` over the set a `_` fallback accepts
 (`assert` is imported as `strict`, so each comparison is `Object.is`). Where a
 test should also prove that the _exact_ value reached the handler unchanged,
 the fallback returns the shape verbatim and the call site asserts it.
 #### Why
 - The parameter's type is what the compiler inferred from the pattern; the
  argument is what the runtime passed. Only the second can drift, and the keys
  whose property name differs from their value (`true`, `null`, `1`) are
  exactly where it can — see [library.md](./library.md).
 - `String(shape)` at the call site keeps every type expectation and every
  return-value assertion green; the argument assertions fail (10 of the 33
  tests). Without them the suite never looks at the passed argument.
 - Returning the shape verbatim costs a widening pattern nothing: the remainder
  type joins the union of handler returns in place of a marker literal, so the
  test still shows the widening it is named for.
 #### Rejected
 - A recorded `unknown[]` of every fallback call compared with `deepEqual`:
  strong, but it couples the assertion to call order, and the sink sits three
  blocks away from the value it observes.
 - `typeof` checks: they cannot separate `2` from its key text `"2"`, which is
  the drift a fallback with a numeric remainder can hit.
 - One expected value asserted inline in a fallback: its argument is a _set_ of
  shapes, so only the disjunction holds on every call.
 ## AAA ordering
@@ -133,7 +168,7 @@ The script prints the labels the server offers at a `/*COMPLETE*/` marker inside
 `<file>` (the marker is stripped before the document is sent). Its `LspSession`
 is imported by `src/util/__tests__/lsp-completion.test.ts` — which tests the
 helper itself against inline documents, never the library's code — and by
-`src/primitive.test.ts`, where the same probe asserts the matcher's popup;
+`src/primitive-union.test.ts`, where the same probe asserts the matcher's popup;
 the CLI is for manual inspection.
 #### Why
@@ -164,11 +199,16 @@ the CLI is for manual inspection.
  delay is needed.
 - The server answers some requests with a string id (`client/registerCapability`);
  the client must tolerate `string | number` ids or the server stalls.
 - `LspSession.close()` sends `shutdown` and then closes stdin instead of
  sending `exit`. The TS 7 Go server's `handleExit` returns `io.EOF`, cancelling
  the background context while a watch update is still in flight, and logs a
  bare `context canceled` before exiting 1; EOF on stdin exits 0 with no output.
  The kill stays as a fallback for a server that does not exit.
 ## Known issues
- The type-aware linter misidentifies `expectTypeOf()` as a floating promise, so
+- The type-aware linter misidentifies `expectTypeOf()` as a floating promise.
-  test files that use it (`src/primitive.test.ts`) carry a file-level
+  It is a known false positive, so `typescript/no-floating-promises` is off for
-  `oxlint-disable typescript/no-floating-promises` with an explanatory comment.
+  `**/*.test.ts` in the `.oxlintrc.json` override rather than repeated as a
-  It is a known false positive, not a rule worth disabling project-wide (see
+  file-level header (see
  [tooling.md § oxlint-disable directives live next to the code](./tooling.md#oxlint-disable-directives-live-next-to-the-code)).
@@ -106,26 +106,34 @@ Type-aware oxlint is enabled via `options.typeAware: true` in `.oxlintrc.json`
 #### Decision (2026-09)
-A type-aware rule that false-positives is silenced with a source-level
+A type-aware rule that false-positives **at one site** is silenced with a
-`oxlint-disable` directive (see `src/primitive.ts`,
+source-level `oxlint-disable` directive (see `src/primitive-union.ts`). A rule that is
-`src/primitive.test.ts`), not by turning the rule off in `.oxlintrc.json`.
+wrong for a whole **file class** is turned off in a `.oxlintrc.json` `overrides`
 entry instead — e.g. `typescript/no-floating-promises` (synchronous
 `expectTypeOf` reads as an unhandled promise) and `unicorn/no-null` (intentional
 `null` inputs) for `**/*.test.ts`. The same exemption is not repeated as a
 file-level header in every affected file.
 #### Why
- The disable sits next to the code it silences, visible to anyone reading the
+- A one-site disable sits next to the code it silences, visible to anyone
-  source.
+  reading the source, and the rule stays on everywhere else.
- The rule stays on everywhere else, so only the mis-firing line is exempted.
+- A file-class rule is a property of the file class, not of one line; the
  override states it once, where the rest of the file-class config lives.
 #### Rejected
- A project-wide disable in `.oxlintrc.json` for a false positive: it hides the
+- A project-wide disable in `.oxlintrc.json` for a one-site false positive: it
-  exemption from the reader of the affected code and switches the rule off
+  hides the exemption from the reader of the affected code and switches the rule
-  repo-wide for a one-site problem.
+  off repo-wide for a one-site problem.
 - A repeated file-level `oxlint-disable` header for a file-class false positive:
  the copies drift and scatter one config decision across the tree.
 #### Known issue
- A source-level disable is a _human_ last resort. AI agents must not add one;
+- Both placements are _human_ last resorts. AI agents must neither add a source
-  they fix the type at its root (see [AGENTS.md § Never do](../AGENTS.md#never-do)).
+  disable nor edit `.oxlintrc.json`; they fix the type at its root (see
  [AGENTS.md § Never do](../AGENTS.md#never-do)).
 ### Unwanted stylistic rules are turned off in the config
@@ -188,6 +196,29 @@ joining the oxfmt-superseded rules already off.
  are part of the public API.
 - The narrower scope keeps the signal high without config-file boilerplate.
 ### `knip` does not list the library entry
 #### Decision (2026-09)
 `knip.json` declares `"entry": ["scripts/*.ts"]`; the library entry
 `src/index.ts` is not listed.
 #### Why
 - knip derives the public entry from `package.json` `exports` and resolves it to
  `src/index.ts` itself, so naming the file is a redundant pattern and
  `maintain:knip` reports it as a configuration hint.
 - Listing `scripts/*.ts` does not switch that derivation off: the scope stays
  clean with or without `dist/`, and with the barrel's own test removed.
 #### Rejected
 - `"src/index.ts"` in `entry`: it silenced an `unused files` report for the
  barrel, which the derivation above no longer produces; keeping it only adds a
  hint.
 - `paths` mapping `dist/index.*` back to `src/index.ts`: more config to model a
  relation knip already resolves.
 ### `maintain:outdated` ignores `@types/node`
 #### Decision (2026-09)
@@ -297,7 +328,7 @@ of a hand-rolled JSON-RPC client.
 #### Decision (2026-09)
-`@spences10/pi-lsp` is pinned to `0.0.46` and used read-only.
+`@spences10/pi-lsp` is pinned to `0.0.47` and used read-only.
 #### Why
@@ -96,7 +96,8 @@ aggregator.
 #### Why
- Both members create something real: a branch, a release.
+- Every member creates something real: a branch, a release, the compiled
  doc-tests.
 - It joined both lists in [CONTRIBUTING.md](../CONTRIBUTING.md) alongside its
  first members, so it could not go invisible the way the retired `use:` prefix
  did.
@@ -1,5 +1,5 @@
 {
    "$schema": "./node_modules/knip/schema.json",
-    "entry": ["scripts/*.ts"],
+    "entry": ["scripts/*.ts", "compat/*.ts"],
    "ignoreDependencies": ["@runwisp/pubv"]
 }
@@ -1,7 +1,7 @@
 {
    "name": "tiny-pattern-ts",
-    "version": "0.2.0",
+    "version": "0.9.0",
-    "description": "Pattern matching for TypeScript/ESM environments (F#-style, not regex)",
+    "description": "Exhaustive, type-safe pattern matching for TypeScript",
    "keywords": [
        "adt",
        "algebraic-data-types",
@@ -28,7 +28,8 @@
    "type": "module",
    "sideEffects": false,
    "imports": {
-        "#test-utils/*": "./src/util/__tests__/*"
+        "#test-utils/*": "./src/util/__tests__/*",
        "#test-tiny-pattern-ts": "./src/index.ts"
    },
    "exports": {
        ".": {
@@ -47,7 +48,8 @@
        "check:oxfmt": "oxfmt --check ${LEFTHOOK_FILES:-.}",
        "check:oxlint": "oxlint ${LEFTHOOK_FILES:-src scripts}",
        "check:tsc": "tsc",
-        "clean": "rm -rf dist coverage",
+        "clean": "rm -rf dist coverage src/doc-test/__generated__/*.test.ts",
        "create:doc-tests": "node --strip-types scripts/create-doc-tests.ts && sh -c 'oxfmt src/doc-test/__generated__/*.test.ts' && tsc -p src/doc-test/tsconfig.json",
        "fix": "npm run fix:oxlint && npm run fix:oxfmt",
        "fix:oxfmt": "oxfmt ${LEFTHOOK_FILES:-.}",
        "fix:oxlint": "oxlint --fix src scripts",
@@ -58,7 +60,10 @@
        "maintain:knip": "knip --include dependencies,exports,files",
        "maintain:outdated": "check-outdated --ignore-pre-releases --ignore-packages @types/node",
        "test": "npm run check:tsc && node --test --strip-types \"src/**/*.test.ts\"",
-        "test:ci": "c8 --reporter=text --reporter=lcov --reporter=html node --test --strip-types \"src/**/*.test.ts\"",
+        "test:ci": "npm run test:coverage && npm run test:doc",
        "test:compat": "npx --yes --package typescript@5.9.2 tsc --project compat/tsconfig.json",
        "test:coverage": "c8 --all --include \"src/**/*.ts\" --reporter=text --reporter=lcov --reporter=html --100 node --test --strip-types $(git ls-files 'src/*.test.ts')",
        "test:doc": "node --test --strip-types \"src/doc-test/__generated__/*.test.ts\"",
        "test:unit": "node --test --strip-types \"src/**/*.test.ts\"",
        "verify": "npm run check && npm run test:unit",
        "watch": "npm run watch:test",
@@ -83,7 +88,8 @@
        "expect-type": "1.4.0",
        "knip": "^6.34.0",
        "lefthook": "^2.1.12",
-        "oxfmt": "^0.68.0",
+        "mdast-util-from-markdown": "^2.0.3",
        "oxfmt": "^0.71.0",
        "oxlint": "^1.83.0",
        "oxlint-tsgolint": "^7.0.2001",
        "publint": "^0.3.24",
@@ -0,0 +1,445 @@
 import fs from "node:fs";
 import path from "node:path";
 import type { Code, Heading, Paragraph, PhrasingContent, Root } from "mdast";
 import { fromMarkdown } from "mdast-util-from-markdown";
 /**
 * Compile the TypeScript examples embedded in the prose docs into runnable
 * tests, so a doc fence that drifts from the API fails CI. Every ```ts fence in
 * the scanned Markdown becomes a `test(...)` in a generated
 * `src/doc-test/__generated__/<Name>.test.ts`; the file is typechecked by
 * `tsc` and executed by `node --test` exactly like a hand-written test.
 *
 * Usage: node --strip-types scripts/create-doc-tests.ts
 *
 * Why regenerate-then-typecheck instead of a lint plugin: development/docs.md §
 * Validating Markdown code fences. The repo is TypeScript 7 (the native
 * compiler), which does not expose the legacy JS compiler API, so the only
 * faithful check is to emit real `.ts` files and let the existing `check:tsc` /
 * `node --test` pipeline judge them.
 */
 /** The package's public entry, as spelled inside the examples. */
 const LIBRARY_SOURCE = "tiny-pattern-ts";
 /** Matches the library specifier (single- or double-quoted) inside an import. */
 const LIBRARY_SPECIFIER = new RegExp(
    `(?<quote>["'])${LIBRARY_SOURCE}\\k<quote>`,
    "g",
 );
 /**
 * A source specifier resolved to `src/index.ts` by `package.json#imports`.
 * Examples import `from "tiny-pattern-ts"`, which neither `node` nor `tsc`
 * resolves to source before `dist/` exists, so the generator rewrites it.
 */
 const PRELUDE_IMPORT_SOURCE = "#test-tiny-pattern-ts";
 /** Markdown files to scan, relative to the repo root. */
 const SOURCES = ["README.md", "CONTRIBUTING.md"];
 /** Directory the generated tests are written to (gitignored contents). */
 const OUTPUT_DIR = "src/doc-test/__generated__";
 /** Fences whose info-string matches one of these are compiled; others skipped. */
 const TYPESCRIPT_LANGS: ReadonlySet<string> = new Set(["ts", "typescript"]);
 /**
 * Modules the generated file already imports. An example that imports one of
 * these would collide with the prelude binding (duplicate `test` / `assert`), so
 * it is surfaced as a fatal error and the example is rewritten.
 */
 const PRELUDE_MODULES: ReadonlySet<string> = new Set([
    "node:assert",
    "node:test",
 ]);
 /** One line of the prelude every generated file starts with. */
 const PRELUDE_TEST = 'import { test } from "node:test";';
 const PRELUDE_ASSERT = 'import { strict as assert } from "node:assert";';
 /** Indentation applied to every fence body line inside the `test` callback. */
 const INDENT = "    ";
 const EMPTY = "";
 const INITIAL_COUNT = 0;
 const WRITE_INCREMENT = 1;
 const FIRST_ITEM = 0;
 const FAILURE_EXIT_CODE = 1;
 /** Strip all leading blank lines so the import scan starts at real content. */
 const LEADING_BLANK_LINES = /^(?:[ \t]*\r?\n)+/;
 /** Collapse the plain text of a title paragraph to one line. */
 const WHITESPACE = /\s+/g;
 /** Split an info-string like `ts title="x"` into its bare language. */
 const LANG_SEPARATOR = /\s+/;
 /** One leading `import` statement, including a multi-line named import. */
 const IMPORT_STATEMENT =
    /^import\s+(?:(?:type\s+)?[\w$*{}\s,]+?\s+from\s+)?["'][^"'\n]+["']\s*;?[ \t]*(?:\r?\n|$)/;
 /** `import { a, b } from "src";`, with an optional `type` keyword. */
 const NAMED_IMPORT =
    /^import\s+(?<isType>type\s+)?\{(?<specifiers>[^}]*)\}\s+from\s+["'](?<source>[^"']+)["']\s*;?$/;
 /** The module in a `… from "src"` statement. */
 const FROM_SOURCE = /from\s+["'](?<source>[^"']+)["']/;
 /** The module in a side-effect `import "src"` statement. */
 const SIDE_EFFECT_SOURCE = /^import\s+["'](?<source>[^"']+)["']/;
 type Block = Root["children"][number];
 class DocTestError extends Error {
    public constructor(message: string) {
        super(message);
        this.name = "DocTestError";
    }
 }
 /** Merge named specifiers that target the same module into one import. */
 interface NamedImportGroup {
    readonly source: string;
    readonly isType: boolean;
    readonly names: string[];
 }
 /** One compiled fence, ready to be wrapped in a `test(...)`. */
 interface DocCase {
    readonly title: string;
    readonly body: string;
 }
 /** Accumulator threaded through the Markdown walk. */
 interface BuilderState {
    readonly named: Map<string, NamedImportGroup>;
    readonly passthrough: Set<string>;
    readonly cases: DocCase[];
    title: string | undefined;
 }
 /** Read one capture group, tolerating the type-level `groups` optionality. */
 const groupOf = (match: RegExpExecArray, name: string): string | undefined => {
    const { groups } = match;
    return groups === undefined ? undefined : groups[name];
 };
 /** Recursively concatenate the literal text of a single inline node. */
 const inlineText = (node: PhrasingContent): string => {
    if ("value" in node) {
        return node.value;
    }
    if ("children" in node) {
        return node.children.map(inlineText).join(EMPTY);
    }
    return EMPTY;
 };
 /** Render a paragraph/heading node to its plain text for use as a test title. */
 const textOf = (node: Paragraph | Heading): string =>
    node.children.map(inlineText).join(EMPTY).replace(WHITESPACE, " ").trim();
 /**
 * Split a fence into its leading `import` statements and the executable body.
 * Only a contiguous run of imports at the very top is hoisted; anything after
 * the first non-import line stays in the body verbatim.
 */
 const splitImports = (code: string): { imports: string[]; body: string } => {
    const imports: string[] = [];
    let rest = code.replace(LEADING_BLANK_LINES, EMPTY);
    let match = IMPORT_STATEMENT.exec(rest);
    while (rest.startsWith("import") && match !== null) {
        const statement = match[FIRST_ITEM] ?? EMPTY;
        imports.push(statement.trim());
        rest = rest.slice(statement.length).replace(LEADING_BLANK_LINES, EMPTY);
        match = IMPORT_STATEMENT.exec(rest);
    }
    return { imports, body: rest.trim() };
 };
 /** The module an import statement points at, or `undefined` if unreadable. */
 const importSource = (statement: string): string | undefined => {
    const fromMatch = FROM_SOURCE.exec(statement);
    if (fromMatch !== null) {
        return groupOf(fromMatch, "source");
    }
    const sideEffectMatch = SIDE_EFFECT_SOURCE.exec(statement);
    return sideEffectMatch === null
        ? undefined
        : groupOf(sideEffectMatch, "source");
 };
 /**
 * Reject an example that imports a harness-provided module, then rewrite the
 * library specifier to the source alias so the emitted file resolves.
 */
 const normalizeImport = (statement: string): string => {
    const source = importSource(statement);
    if (source !== undefined && PRELUDE_MODULES.has(source)) {
        throw new DocTestError(
            `example imports "${source}", which the harness injects; remove the line:\n  ${statement.trim()}`,
        );
    }
    return statement.replace(
        LIBRARY_SPECIFIER,
        `$<quote>${PRELUDE_IMPORT_SOURCE}$<quote>`,
    );
 };
 /** Split the `{ a, b }` contents of a named import into trimmed specifiers. */
 const specifiersOf = (raw: string): string[] =>
    raw
        .split(",")
        .map((name) => name.trim())
        .filter((name) => name.length > INITIAL_COUNT);
 /** Add named specifiers to the group for `(isType, source)`, merging. */
 const addNamedImport = (
    named: Map<string, NamedImportGroup>,
    ref: Pick<NamedImportGroup, "source" | "isType">,
    names: readonly string[],
 ): void => {
    const key = `${ref.isType ? "type:" : "value:"}${ref.source}`;
    const existing = named.get(key);
    if (existing === undefined) {
        named.set(key, {
            source: ref.source,
            isType: ref.isType,
            names: [...names],
        });
        return;
    }
    for (const name of names) {
        if (!existing.names.includes(name)) {
            existing.names.push(name);
        }
    }
 };
 /** Sort each hoisted import into a merged named group or a passthrough set. */
 const collectImports = (
    statements: readonly string[],
    named: Map<string, NamedImportGroup>,
    passthrough: Set<string>,
 ): void => {
    for (const raw of statements) {
        const statement = normalizeImport(raw);
        const match = NAMED_IMPORT.exec(statement);
        if (match === null) {
            passthrough.add(statement);
        } else {
            addNamedImport(
                named,
                {
                    source: groupOf(match, "source") ?? EMPTY,
                    isType: groupOf(match, "isType") !== undefined,
                },
                specifiersOf(groupOf(match, "specifiers") ?? EMPTY),
            );
        }
    }
 };
 /** Render the hoisted imports: merged named groups first, then the rest. */
 const renderImports = (
    named: ReadonlyMap<string, NamedImportGroup>,
    passthrough: ReadonlySet<string>,
 ): string[] => {
    const lines: string[] = [];
    for (const group of named.values()) {
        const keyword = group.isType ? "import type" : "import";
        lines.push(
            `${keyword} { ${group.names.join(", ")} } from "${group.source}";`,
        );
    }
    for (const statement of passthrough) {
        lines.push(statement);
    }
    return lines;
 };
 /** The bare language of a fence's info-string, e.g. `ts` in `ts title="x"`. */
 const typescriptLang = (code: Code): string =>
    (code.lang ?? EMPTY).trim().split(LANG_SEPARATOR)[FIRST_ITEM] ?? EMPTY;
 /** Set the title a following fence will inherit. */
 const handleTitleNode = (
    state: BuilderState,
    node: Paragraph | Heading,
 ): void => {
    state.title = textOf(node);
 };
 /** Report and reset a non-TS fence that was skipped. */
 const skipFence = (state: BuilderState, name: string, code: Code): void => {
    process.stderr.write(
        `${name}: skipped non-TypeScript fence (lang="${code.lang ?? EMPTY}")\n`,
    );
    state.title = undefined;
 };
 /** Compile a described TS fence into a case, or reject it. */
 const compileFence = (
    state: BuilderState,
    name: string,
    code: Code,
 ): DocCase => {
    const { title } = state;
    if (title === undefined) {
        const lang = typescriptLang(code);
        throw new DocTestError(
            `${name}: a \`\`\`${lang} fence has no preceding paragraph or ` +
                `heading to use as its test title — describe the example.`,
        );
    }
    const { imports, body } = splitImports(code.value);
    collectImports(imports, state.named, state.passthrough);
    return { title, body };
 };
 /** Compile one TS fence into a case, or reject/skip it. */
 const handleCodeNode = (
    state: BuilderState,
    name: string,
    code: Code,
 ): void => {
    const lang = typescriptLang(code);
    if (!TYPESCRIPT_LANGS.has(lang)) {
        skipFence(state, name, code);
        return;
    }
    state.cases.push(compileFence(state, name, code));
 };
 /** Route one Markdown block, preserving the "described fence" invariant. */
 const handleNode = (state: BuilderState, name: string, node: Block): void => {
    if (node.type === "paragraph" || node.type === "heading") {
        handleTitleNode(state, node);
    } else if (node.type === "code") {
        handleCodeNode(state, name, node);
    } else {
        // Only a paragraph/heading introduces a fence; any other block breaks
        // the "immediately preceded" chain.
        state.title = undefined;
    }
 };
 /** Walk one Markdown file and collect its cases and hoisted imports. */
 const parseDoc = (
    name: string,
    markdown: string,
 ): Omit<BuilderState, "title"> => {
    const state: BuilderState = {
        named: new Map(),
        passthrough: new Set(),
        cases: [],
        title: undefined,
    };
    for (const node of fromMarkdown(markdown).children) {
        handleNode(state, name, node);
    }
    return {
        named: state.named,
        passthrough: state.passthrough,
        cases: state.cases,
    };
 };
 /** Indent a fence body one level for the body of the `test` callback. */
 const indentBody = (body: string): string =>
    body
        .split("\n")
        .map((line) =>
            line.length > INITIAL_COUNT ? `${INDENT}${line}` : line,
        )
        .join("\n");
 /** Wrap one compiled fence in an executed `test(...)`. */
 const renderCase = (docCase: DocCase): string => {
    const indented = indentBody(docCase.body);
    return `test(${JSON.stringify(docCase.title)}, () => {\n${indented}\n});`;
 };
 /** Build the prelude + hoisted imports that top every generated file. */
 const buildHeader = (name: string, imports: readonly string[]): string[] => {
    const header = [
        "// Generated by scripts/create-doc-tests.ts — do not edit by hand.",
        `// Source: ${name}`,
        EMPTY,
        PRELUDE_TEST,
        PRELUDE_ASSERT,
    ];
    if (imports.length > INITIAL_COUNT) {
        header.push(EMPTY, ...imports);
    }
    header.push(EMPTY);
    return header;
 };
 /** Turn one Markdown file into the source of its generated test file. */
 const buildTestFile = (name: string, markdown: string): string => {
    const parsed = parseDoc(name, markdown);
    if (parsed.cases.length === INITIAL_COUNT) {
        return EMPTY;
    }
    const imports = renderImports(parsed.named, parsed.passthrough);
    const header = buildHeader(name, imports);
    const blocks = parsed.cases.map(renderCase);
    return `${header.join("\n")}\n${blocks.join("\n\n")}\n`;
 };
 /** Map a source Markdown path to its generated test path under OUTPUT_DIR. */
 const outputFor = (source: string): string =>
    path.join(
        OUTPUT_DIR,
        `${path.basename(source, path.extname(source))}.test.ts`,
    );
 /** Write a generated file when there is content, else clear a stale one. */
 const writeIfAny = (dest: string, name: string, out: string): boolean => {
    if (out === EMPTY) {
        process.stderr.write(`${name}: no TypeScript fences\n`);
        fs.rmSync(dest, { force: true });
        return false;
    }
    fs.writeFileSync(dest, out);
    return true;
 };
 /** Generate the doc-test for one source; return whether a file was written. */
 const generateFor = (root: string, source: string): boolean => {
    const abs = path.join(root, source);
    if (!fs.existsSync(abs)) {
        process.stderr.write(`skipped missing ${source}\n`);
        return false;
    }
    const name = path.basename(source);
    const out = buildTestFile(name, fs.readFileSync(abs, "utf8"));
    return writeIfAny(path.join(root, outputFor(source)), name, out);
 };
 const main = (): void => {
    const root = process.cwd();
    fs.mkdirSync(path.join(root, OUTPUT_DIR), { recursive: true });
    let written = INITIAL_COUNT;
    for (const source of SOURCES) {
        if (generateFor(root, source)) {
            written += WRITE_INCREMENT;
        }
    }
    process.stdout.write(
        `created doc-tests for ${written} file(s) under ${OUTPUT_DIR}/\n`,
    );
 };
 try {
    main();
 } catch (error) {
    if (error instanceof DocTestError) {
        process.stderr.write(`${error.message}\n`);
        process.exitCode = FAILURE_EXIT_CODE;
    } else {
        throw error;
    }
 }
@@ -0,0 +1,12 @@
 # Generated doc-tests
 `__generated__/` is the output of [`scripts/create-doc-tests.ts`](../../scripts/create-doc-tests.ts):
 each `*.test.ts` is compiled from the ```ts fences in a prose doc and is
 **gitignored**, not edited by hand. `npm run create:doc-tests` regenerates them,
 formats them with `oxfmt`, then type-checks them with
 [`tsconfig.json`](./tsconfig.json) — the scoped config that relaxes
 `noUnusedLocals` so example-only locals (and the injected `assert`) compile.
 CI regenerates them in an explicit step before `test:ci`; the fast local `test` /
 `verify` tiers do not. See [development/docs.md](../../development/docs.md) for why the
 generator is shaped this way.
@@ -0,0 +1,10 @@
 {
    "extends": "../../tsconfig.json",
    "compilerOptions": {
        "noEmit": true,
        "noUnusedLocals": false,
        "noUnusedParameters": false
    },
    "include": ["__generated__/**/*.test.ts"],
    "exclude": []
 }
@@ -0,0 +1,27 @@
 import { strict as assert } from "node:assert";
 import { test } from "node:test";
 import { expectTypeOf } from "expect-type";
 import {
    getPrimitiveUnionMatcher,
    getPrimitiveUnionMatcherW,
    getTaggedUnionMatcher,
    getTaggedUnionMatcherW,
 } from "./index.ts";
 // The published entry point is the barrel (`package.json` exports
 // `./dist/index.js`), so every factory must be reachable from here. Importing it
 // also loads the module, which is what lets c8's `--all` measure it — see
 // development/ci.md § Coverage threshold.
 test("index: the public entry point re-exports every matcher factory", () => {
    // Assert
    expectTypeOf(getPrimitiveUnionMatcher).toBeFunction();
    assert.equal(typeof getPrimitiveUnionMatcher, "function");
    expectTypeOf(getPrimitiveUnionMatcherW).toBeFunction();
    assert.equal(typeof getPrimitiveUnionMatcherW, "function");
    expectTypeOf(getTaggedUnionMatcher).toBeFunction();
    assert.equal(typeof getTaggedUnionMatcher, "function");
    expectTypeOf(getTaggedUnionMatcherW).toBeFunction();
    assert.equal(typeof getTaggedUnionMatcherW, "function");
 });
@@ -1 +1,16 @@
-export { getMatcher, getMatcherW } from "./primitive.ts";
+/**
 * The public entry point of `tiny-pattern-ts`.
 *
 * Exports the four matcher factories and nothing else; the builder types they
 * return and the rest of `src/` are implementation detail.
 *
 * @module
 */
 export {
    getPrimitiveUnionMatcher,
    getPrimitiveUnionMatcherW,
 } from "./primitive-union.ts";
 export {
    getTaggedUnionMatcher,
    getTaggedUnionMatcherW,
 } from "./tagged-union.ts";
@@ -0,0 +1,102 @@
 /* c8 ignore start -- types only: the module has no runtime image to cover */
 import type { IsLiteral, IsNever, ValueOf } from "type-fest";
 // The primitive-union and tagged-union matchers differ in their universe, but the
 // handler/fallback plumbing is identical; these are the shared pieces. The
 // boundary is deliberate: `Handlers`, `Fallback` and `MustBePartial` stay with
 // each matcher because they are built from its universe. See development/library.md.
 // A handler: one universe member in, one return value out.
 export type UnaryFn<T, R> = (shape: T) => R;
 // The primitive universe a matcher can discriminate. The primitive-union matcher
 // uses it directly; the tagged-union matcher uses it as the set of allowed
 // discriminant (`Tag`) values. `boolean` is admitted as the pair `true | false`;
 // see README § Caveats for the unsupported members.
 export type Matchable = string | number | boolean | null | undefined;
 // `boolean`, `null` and `undefined` cannot be property keys, so a mapped type
 // over a universe that includes one keys each such member by its
 // stringification. `Member` inverts that projection against the universe, so a
 // handler callback still receives the *real* member (`true`, not `"true"`).
 // Both matchers use the projection: the primitive-union matcher over its
 // universe, the tagged-union matcher over a discriminant property's values. See
 // README § Caveats for the limits.
 export type PatternKey<T> = T extends boolean
    ? T extends true
        ? "true"
        : "false"
    : T extends null
      ? "null"
      : T extends undefined
        ? "undefined"
        : T;
 // The member(s) of `T` whose `PatternKey` is `K`: the universe-keyed inverse of
 // `PatternKey`. The key alone cannot recover the member (`"true"` and `true`
 // share it), so the handler parameter is derived from `T` instead. For a
 // supported (injective) universe the result is a single member.
 export type Member<
    T extends Matchable,
    K extends PropertyKey,
 > = T extends Matchable ? (PatternKey<T> extends K ? T : never) : never;
 // The property key a `Matchable` member takes at runtime: booleans, `null` and
 // `undefined` stringify, and a numeric literal becomes its decimal string.
 export type Stringified<T> = T extends boolean
    ? T extends true
        ? "true"
        : "false"
    : T extends null
      ? "null"
      : T extends undefined
        ? "undefined"
        : T extends number
          ? `${T}`
          : never;
 // The members of `T` that are also the stringification of another member, so
 // `PatternKey` cannot invert them. `never` means the universe is injective.
 export type Collisions<T> = Extract<T, Stringified<T>>;
 // Why `T` is not a supported universe, or `never` when it is. A supported
 // universe is a finite union of literals with no value/stringification
 // collision: only then can `PatternKey` be inverted unambiguously.
 export type UnsupportedReason<T extends Matchable> =
    IsLiteral<PatternKey<T>> extends true
        ? [Collisions<T>] extends [never]
            ? never
            : `a value and its stringification collide. Value is "${Collisions<T> & string}"`
        : "broad types like string, number and template literals are not supported";
 // The diagnostic for an unsupported universe. Extends `HandlerMap` so the
 // implementation's `handlers: HandlerMap` stays assignable when the gate is
 // intersected into a parameter; the property name is the message.
 export type UnsupportedUniverse<Reason extends string> = HandlerMap &
    Readonly<Record<`unsupported universe: ${Reason}`, never>>;
 // `unknown` for a supported universe (an intersection no-op), the diagnostic
 // otherwise. Intersecting rather than branching keeps `R` inference intact.
 export type UniverseGate<T extends Matchable> =
    IsNever<UnsupportedReason<T>> extends true
        ? unknown
        : UnsupportedUniverse<UnsupportedReason<T>>;
 // `Extract` drops optional handlers (`undefined`) so `PatternReturns` also works
 // when `P`'s constraint has optional keys.
 export type PatternReturns<P> = ReturnType<
    Extract<ValueOf<P>, (...args: never[]) => unknown>
 >;
 // The diagnostic raised when a fallback is supplied for an already-exhaustive
 // handler map. Each matcher's `MustBePartial` folds it into `Handled`'s
 // constraint so the guard is checked after inference.
 export interface RedundantFallback {
    readonly "every case is already handled, so the fallback is redundant": never;
 }
 // The runtime dispatch map the handler maps and fallback erase to.
 export type HandlerMap = Record<
    string | number,
    UnaryFn<never, unknown> | undefined
 >;
@@ -0,0 +1,145 @@
 import type { Exact } from "type-fest";
 import type {
    HandlerMap,
    Matchable,
    Member,
    PatternKey,
    PatternReturns,
    RedundantFallback,
    UnaryFn,
    UniverseGate,
 } from "./matcher-shared.ts";
 type Handlers<T extends Matchable, R> = {
    [K in PatternKey<T>]: UnaryFn<Member<T, K>, R>;
 };
 // The fallback is a *second argument*, not a property of the handler map,
 // because its parameter is the remainder `Exclude<T, Member<T, keyof Handled>>` and TypeScript
 // fixes a property's contextual type before it infers its sibling keys. A later
 // argument, by contrast, is contextually typed from inference on an earlier
 // one, so the split is what makes the remainder expressible at all.
 // See development/library.md.
 type Fallback<T extends Matchable, Handled, R> = UnaryFn<
    Exclude<T, Member<T, keyof Handled>>,
    R
 >;
 // A fallback is redundant once the handler map covers `T`. The guard is folded
 // into `Handled`'s own (self-referential) constraint so it is checked *after*
 // inference; a conditional in the fallback's parameter type is evaluated while
 // `Handled` is still its constraint and would reject context-sensitive partial
 // maps. That placement also fixes where the diagnostic lands: the constraint
 // failure is reported on the argument that inferred `Handled` (the handler
 // map), so the required property is spelled as the message instead of relying
 // on its position. See development/library.md.
 type MustBePartial<T extends Matchable, Handled> =
    PatternKey<T> extends keyof Handled ? RedundantFallback : unknown;
 // TypeScript does not apply the excess-property check to a generic constraint,
 // so `Exact` restores it for the generic forms: a handler map can otherwise
 // carry keys outside `T`.
 // Strict returns: one common `R`. Overload order is load-bearing:
 //   #1 Handlers (first) -> the exhaustive form and the autocomplete popup
 //   #2 Fallback (last)  -> accepts a partial handler map plus a fallback
 interface PrimitiveUnionMatcherStrict<T extends Matchable> {
    <R>(handlers: Handlers<T, R> & UniverseGate<T>): UnaryFn<T, R>;
    <
        R,
        Handled extends Exact<Partial<Handlers<T, R>>, Handled> &
            MustBePartial<T, Handled>,
    >(
        handlers: Handled & Partial<Handlers<T, R>> & UniverseGate<T>,
        fallback: Fallback<T, Handled, R> & UniverseGate<T>,
    ): UnaryFn<T, R>;
 }
 // Widened returns: the union of every handler's return type. `P` is inferred
 // from the whole handler map, whose closed constraint supplies the
 // contextual/autocomplete type.
 interface PrimitiveUnionMatcherWidening<T extends Matchable> {
    <P extends Exact<Handlers<T, unknown>, P>>(
        handlers: P & UniverseGate<T>,
    ): UnaryFn<T, PatternReturns<P>>;
    <
        R,
        Handled extends Exact<Partial<Handlers<T, unknown>>, Handled> &
            MustBePartial<T, Handled>,
    >(
        handlers: Handled & UniverseGate<T>,
        fallback: Fallback<T, Handled, R> & UniverseGate<T>,
    ): UnaryFn<T, PatternReturns<Handled> | R>;
 }
 const dispatch =
    (handlers: HandlerMap, fallback?: UnaryFn<never, unknown>) =>
    (shape: Matchable): unknown =>
        // `handlers[true]` already coerces to the `"true"` property at runtime,
        // identical to `handlers[String(shape)]`, so indexing with `shape`
        // directly is sound: `shape` is a facade-checked universe member and
        // `PatternKey` only ever produces valid property keys. The assertion is
        // needed solely because TypeScript forbids indexing with
        // `boolean`/`null`/`undefined` (TS2538); it buys the number fast path.
        (
            handlers[
                // oxlint-disable-next-line typescript/no-unsafe-type-assertion
                shape as string | number
            ] ??
            fallback ??
            (() => {
                throw new Error(`Unhandled shape: ${String(shape)}`);
            })
        )(
            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
            shape as never,
        );
 /**
 * Create a matcher for a finite primitive universe, with one common return
 * type.
 *
 * Use it when the value itself is the union (`"yes" | "no"`) and every handler
 * returns the same type.
 *
 * The returned builder takes a handler map keyed by the members; supplying a
 * second fallback argument allows a partial map and receives the unhandled
 * remainder.
 *
 * @typeParam T - The finite universe of primitive members to match.
 * @returns A builder for the handler map, or the handler map plus a fallback.
 * @example
 *     const matchAnswer = getPrimitiveUnionMatcher<"yes" | "no">();
 *     const describe = matchAnswer({
 *         yes: () => "agreed",
 *         no: () => "declined",
 *     });
 *     describe("yes"); // "agreed"
 */
 export const getPrimitiveUnionMatcher = <
    T extends Matchable,
 >(): PrimitiveUnionMatcherStrict<T> => dispatch;
 /**
 * Create a matcher for a finite primitive universe whose return type is the
 * union of every handler's return type.
 *
 * Use it when the value itself is the union (`"yes" | "no"`) and the handlers
 * return different types. The `W` (widening) counterpart of
 * {@link getPrimitiveUnionMatcher}; the universe constraint and the optional
 * fallback are identical.
 *
 * @typeParam T - The finite universe of primitive members to match.
 * @returns A builder for the handler map, or the handler map plus a fallback.
 * @example
 *     const matchReply = getPrimitiveUnionMatcherW<"yes" | "no">();
 *     const reply = matchReply({
 *         yes: () => 1,
 *         no: () => "declined",
 *     });
 *     // reply: (shape: "yes" | "no") => number | string
 */
 export const getPrimitiveUnionMatcherW = <
    T extends Matchable,
 >(): PrimitiveUnionMatcherWidening<T> => dispatch;
@@ -1,457 +0,0 @@
 /* oxlint-disable typescript/no-floating-promises -- expectTypeOf() is a sync type-assertion library that the type-aware linter misidentifies as a promise */
 import { strict as assert } from "node:assert";
 import path from "node:path";
 import { test } from "node:test";
 import { expectTypeOf } from "expect-type";
 import {
    type CompletionTarget,
    LspSession,
 } from "#test-utils/lsp-completion.ts";
 import { getMatcher, getMatcherW } from "./primitive.ts";
 // ============================================================================
 // API: getMatcher — ✔️ Exhaustive / ✔️ ReturnsStrict
 // ============================================================================
 test("getMatcher: exhaustive pattern infers one common return type", () => {
    // Arrange
    const factory = getMatcher<"a" | "b">();
    // Act
    const matcher = factory({
        a: (s): number => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return 1;
        },
        b: (s): 1 | 2 => {
            expectTypeOf(s).toEqualTypeOf<"b">();
            return 2;
        },
    });
    // Assert
    // ✔️ ReturnsStrict: R is the best common return type, not a widening union.
    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => number>();
    // ❌ a value outside T must not be accepted by the matcher
    expectTypeOf<"c">().not.toExtend<Parameters<typeof matcher>[0]>();
    assert.equal(matcher("a"), 1);
    assert.equal(matcher("b"), 2);
 });
 test("getMatcher: dispatches on numeric literal keys", () => {
    // Arrange
    const factory = getMatcher<1 | 2>();
    // Act
    const matcher = factory({
        1: (n) => {
            expectTypeOf(n).toEqualTypeOf<1>();
            return n + 1;
        },
        2: (n) => {
            expectTypeOf(n).toEqualTypeOf<2>();
            return n * 10;
        },
    });
    // Assert
    expectTypeOf(matcher).toEqualTypeOf<(shape: 1 | 2) => number>();
    assert.equal(matcher(1), 2);
    assert.equal(matcher(2), 20);
 });
 test("getMatcher: dispatches on mixed string and numeric keys", () => {
    // Arrange
    const factory = getMatcher<"a" | "b" | 1 | 2>();
    // Act
    const matcher = factory({
        a: (s): number => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return 1;
        },
        b: (s): 1 | 2 => {
            expectTypeOf(s).toEqualTypeOf<"b">();
            return 2;
        },
        1: (n): number => {
            expectTypeOf(n).toEqualTypeOf<1>();
            return 10;
        },
        2: (n): number => {
            expectTypeOf(n).toEqualTypeOf<2>();
            return 20;
        },
    });
    // Assert
    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | 1 | 2) => number>();
    assert.equal(matcher("a"), 1);
    assert.equal(matcher("b"), 2);
    assert.equal(matcher(1), 10);
    assert.equal(matcher(2), 20);
 });
 // ============================================================================
 // API: getMatcher — ❌ Exhaustive (fallback) / ✔️ ReturnsStrict
 // ============================================================================
 test("getMatcher: a `_` fallback makes the universe keys optional", () => {
    // Arrange
    const factory = getMatcher<"a" | "b" | "c">();
    // Act
    const matcher = factory({
        a: (s): 1 | 2 => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return 1;
        },
        _: (s): 1 | 2 => {
            // The fallback sees the whole union, not a single literal.
            expectTypeOf(s).toEqualTypeOf<"a" | "b" | "c">();
            return 2;
        },
    });
    // Assert
    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | "c") => 1 | 2>();
    // ❌ a value outside T must not be accepted by the matcher
    expectTypeOf<"d">().not.toExtend<Parameters<typeof matcher>[0]>();
    assert.equal(matcher("a"), 1);
    assert.equal(matcher("b"), 2);
    assert.equal(matcher("c"), 2);
 });
 test("getMatcher: a `_` fallback also accepts an exhaustive pattern", () => {
    // Arrange
    const factory = getMatcher<"a" | "b">();
    // Act
    const matcher = factory({
        a: (s) => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return "A";
        },
        b: (s) => {
            expectTypeOf(s).toEqualTypeOf<"b">();
            return "B";
        },
    });
    // Assert
    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => string>();
    assert.equal(matcher("a"), "A");
    assert.equal(matcher("b"), "B");
 });
 test("getMatcher: a `_` fallback routes mixed string and numeric gaps", () => {
    // Arrange
    const factory = getMatcher<"a" | "b" | 1 | 2>();
    // Act
    const matcher = factory({
        a: (s): string => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return "A";
        },
        1: (n): string => {
            expectTypeOf(n).toEqualTypeOf<1>();
            return "one";
        },
        _: (s): string => {
            expectTypeOf(s).toEqualTypeOf<"a" | "b" | 1 | 2>();
            return "fallback";
        },
    });
    // Assert
    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | 1 | 2) => string>();
    assert.equal(matcher("a"), "A");
    assert.equal(matcher("b"), "fallback");
    assert.equal(matcher(1), "one");
    assert.equal(matcher(2), "fallback");
 });
 // ============================================================================
 // API: getMatcherW — ✔️ Exhaustive / ❌ ReturnsStrict
 // ============================================================================
 test("getMatcherW: exhaustive pattern widens to the union of handler returns", () => {
    // Arrange
    const factory = getMatcherW<"x" | "y">();
    // Act
    const matcher = factory({
        x: (s) => {
            expectTypeOf(s).toEqualTypeOf<"x">();
            return 1 as const;
        },
        y: (s) => {
            expectTypeOf(s).toEqualTypeOf<"y">();
            return "two" as const;
        },
    });
    // Assert
    // ❌ ReturnsStrict: mixed handler returns widen to their union.
    expectTypeOf(matcher).toEqualTypeOf<(shape: "x" | "y") => 1 | "two">();
    // ❌ a value outside T must not be accepted by the matcher
    expectTypeOf<"z">().not.toExtend<Parameters<typeof matcher>[0]>();
    assert.equal(matcher("x"), 1);
    assert.equal(matcher("y"), "two");
 });
 test("getMatcherW: dispatches on mixed string and numeric keys", () => {
    // Arrange
    const factory = getMatcherW<"a" | "b" | 1 | 2>();
    // Act
    const matcher = factory({
        a: (s) => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return "A" as const;
        },
        b: (s) => {
            expectTypeOf(s).toEqualTypeOf<"b">();
            return "B" as const;
        },
        1: (n) => {
            expectTypeOf(n).toEqualTypeOf<1>();
            return 10 as const;
        },
        2: (n) => {
            expectTypeOf(n).toEqualTypeOf<2>();
            return 20 as const;
        },
    });
    // Assert
    expectTypeOf(matcher).toEqualTypeOf<
        (shape: "a" | "b" | 1 | 2) => "A" | "B" | 10 | 20
    >();
    assert.equal(matcher("a"), "A");
    assert.equal(matcher("b"), "B");
    assert.equal(matcher(1), 10);
    assert.equal(matcher(2), 20);
 });
 // ============================================================================
 // API: getMatcherW — ❌ Exhaustive (fallback) / ❌ ReturnsStrict
 // ============================================================================
 test("getMatcherW: a `_` fallback widens gaps into the union", () => {
    // Arrange
    const factory = getMatcherW<"x" | "y" | "z">();
    // Act
    const matcher = factory({
        x: (s) => {
            expectTypeOf(s).toEqualTypeOf<"x">();
            return 1 as const;
        },
        _: (s) => {
            // The fallback sees the whole union, not a single literal.
            expectTypeOf(s).toEqualTypeOf<"x" | "y" | "z">();
            return "fallback" as const;
        },
    });
    // Assert
    expectTypeOf(matcher).toEqualTypeOf<
        (shape: "x" | "y" | "z") => 1 | "fallback"
    >();
    // ❌ a value outside T must not be accepted by the matcher
    expectTypeOf<"w">().not.toExtend<Parameters<typeof matcher>[0]>();
    assert.equal(matcher("x"), 1);
    assert.equal(matcher("y"), "fallback");
    assert.equal(matcher("z"), "fallback");
 });
 test("getMatcherW: a `_` fallback widens mixed string and numeric returns", () => {
    // Arrange
    const factory = getMatcherW<"a" | "b" | 1 | 2>();
    // Act
    const matcher = factory({
        a: (s) => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return "A" as const;
        },
        1: (n) => {
            expectTypeOf(n).toEqualTypeOf<1>();
            return 10 as const;
        },
        _: (s) => {
            expectTypeOf(s).toEqualTypeOf<"a" | "b" | 1 | 2>();
            return "fallback" as const;
        },
    });
    // Assert
    // ❌ ReturnsStrict: mixed handler returns widen to their union.
    expectTypeOf(matcher).toEqualTypeOf<
        (shape: "a" | "b" | 1 | 2) => "A" | 10 | "fallback"
    >();
    assert.equal(matcher("a"), "A");
    assert.equal(matcher("b"), "fallback");
    assert.equal(matcher(1), 10);
    assert.equal(matcher(2), "fallback");
 });
 test("getMatcherW: a `_` fallback also accepts an exhaustive pattern", () => {
    // Arrange
    const factory = getMatcherW<"x" | "y">();
    // Act
    const matcher = factory({
        x: (s) => {
            expectTypeOf(s).toEqualTypeOf<"x">();
            return 1 as const;
        },
        y: (s) => {
            expectTypeOf(s).toEqualTypeOf<"y">();
            return "two" as const;
        },
    });
    // Assert
    expectTypeOf(matcher).toEqualTypeOf<(shape: "x" | "y") => 1 | "two">();
    assert.equal(matcher("x"), 1);
    assert.equal(matcher("y"), "two");
 });
 // ============================================================================
 // Factory contracts — calls that must not compile
 // ============================================================================
 test("getMatcher factory rejects patterns outside its contract", () => {
    // Arrange
    const factory = getMatcher<"a" | "b">();
    // Act / Assert — the calls below must not compile.
    // `Parameters<typeof factory>[0]` resolves only the *last* overload, so it
    // is not a sound "rejected" oracle (an accepted partial pattern does not
    // extend it either); the call sites are the oracle instead.
    factory({
        a: () => 1,
        b: () => 2,
        // @ts-expect-error `c` is not part of the universe `"a" | "b"`
        c: () => 3,
    });
    // @ts-expect-error a gap without `_` is not exhaustive
    factory({ a: () => 1 });
 });
 test("getMatcherW factory rejects patterns outside its contract", () => {
    // Arrange
    const factory = getMatcherW<"x" | "y">();
    // Act / Assert — the calls below must not compile
    // @ts-expect-error `z` is not part of the universe `"x" | "y"`
    factory({
        x: () => 1 as const,
        y: () => 2 as const,
        z: () => 3 as const,
    });
    // @ts-expect-error a gap without `_` is not exhaustive
    factory({ x: () => 1 as const });
 });
 // ============================================================================
 // Autocomplete — the language server is the oracle, not the type system
 // ============================================================================
 // Completion is a contextual-type property that the type system cannot observe,
 // so the cases below read the popup from the repo's language server (via the
 // test helper) rather than pairing `expectTypeOf` with `assert` — see
 // development/testing.md § Autocomplete. They probe the *matcher's* overloads,
 // which is why they live with the matcher and not with the helper.
 const REPO_ROOT = path.resolve(import.meta.dirname, "..");
 const UNIVERSE = `"a" | "b" | "c"`;
 // One session per probe: the tests share no language-server state (open
 // documents, project membership), so they pass in any order.
 const labelsFor = (
    name: string,
    factory: "getMatcher" | "getMatcherW",
    body: string,
 ): Promise<readonly string[]> => {
    const session = new LspSession(REPO_ROOT);
    const target: CompletionTarget = {
        file: `src/__autocomplete_${name}.ts`,
        source: [
            `import { ${factory} } from "./index.ts";`,
            `const m = ${factory}<${UNIVERSE}>()({`,
            body,
            "});",
            "",
        ].join("\n"),
    };
    return session
        .completionLabelsAt(target)
        .then((result) => result.labels)
        .finally(() => session.close());
 };
 test("autocomplete: an exhaustive pattern requires the universe, `_` optional", () => {
    // Arrange
    const name = "getMatcher_fresh";
    // Act
    const labels = labelsFor(name, "getMatcher", "    /*COMPLETE*/");
    // Assert
    return labels.then((result) => {
        assert.deepEqual([...result], ["_?", "a", "b", "c"]);
    });
 });
 test("autocomplete: handled keys drop out of the popup", () => {
    // Arrange
    const name = "getMatcher_after_key";
    // Act
    const labels = labelsFor(
        name,
        "getMatcher",
        "    a: () => 1,\n    /*COMPLETE*/",
    );
    // Assert
    return labels.then((result) => {
        assert.deepEqual([...result], ["_?", "b", "c"]);
    });
 });
 test("autocomplete: `_` makes the remaining keys optional", () => {
    // Arrange
    const name = "getMatcher_after_fallback";
    // Act
    const labels = labelsFor(
        name,
        "getMatcher",
        "    _: () => 0,\n    /*COMPLETE*/",
    );
    // Assert
    return labels.then((result) => {
        assert.deepEqual([...result], ["a?", "b?", "c?"]);
    });
 });
 test("autocomplete: `getMatcherW` offers the same popup as `getMatcher`", () => {
    // Arrange
    const name = "getMatcherW_fresh";
    // Act
    const labels = labelsFor(name, "getMatcherW", "    /*COMPLETE*/");
    // Assert
    return labels.then((result) => {
        assert.deepEqual([...result], ["_?", "a", "b", "c"]);
    });
 });
@@ -1,63 +0,0 @@
 import type { ValueOf } from "type-fest";
 type UnaryFn<T, R> = (shape: T) => R;
 // `Extract` drops optional handlers (`undefined`) so `PatternReturns` also works
 // when `P`'s constraint has optional keys.
 type PatternReturns<P> = ReturnType<
    Extract<ValueOf<P>, (...args: never[]) => unknown>
 >;
 type Handlers<R, T extends string | number> = { [K in T]: UnaryFn<K, R> };
 // Fallback form: `_` is a required key, the T-keys are optional.
 type Fallback<R, T extends string | number> = Partial<Handlers<R, T>> & {
    _: UnaryFn<T, R>;
 };
 // Completion form: T-keys required, `_` optional. Overload #1, because
 // TypeScript takes the *first* overload as the contextual type for the popup.
 type ExhaustiveLoose<R, T extends string | number> = Handlers<R, T> & {
    _?: UnaryFn<T, R>;
 };
 // oxlint-disable typescript/unified-signatures
 // Strict returns: one common `R`. Overload order is load-bearing:
 //   #1 ExhaustiveLoose -> autocomplete `_?, a, b`
 //   #2 Fallback        -> accepts a partial pattern
 //   #3 Handlers (last) -> "Property 'b' is missing" is the reported error
 interface MatcherStrict<T extends string | number> {
    <R>(pattern: ExhaustiveLoose<R, T>): UnaryFn<T, R>;
    <R>(pattern: Fallback<R, T>): UnaryFn<T, R>;
    <R>(pattern: Handlers<R, T>): UnaryFn<T, R>;
 }
 // oxlint-enable typescript/unified-signatures
 // Widened returns: the union of every handler's return type. `P` is inferred
 // from the whole parameter, whose closed constraint supplies the
 // contextual/autocomplete type; the `keyof P` guard appended to each overload
 // rejects keys outside `T`/`_`.
 interface MatcherWidening<T extends string | number> {
    <P extends ExhaustiveLoose<unknown, T>>(
        pattern: P & (keyof P extends T | "_" ? unknown : never),
    ): UnaryFn<T, PatternReturns<P>>;
    <P extends Fallback<unknown, T>>(
        pattern: P & (keyof P extends T | "_" ? unknown : never),
    ): UnaryFn<T, PatternReturns<P>>;
    <P extends Handlers<unknown, T>>(
        pattern: P & (keyof P extends T | "_" ? unknown : never),
    ): UnaryFn<T, PatternReturns<P>>;
 }
 type HandlerMap = Record<string | number, UnaryFn<never, unknown> | undefined>;
 const dispatch =
    (pattern: HandlerMap) =>
    (shape: string | number): unknown =>
        // oxlint-disable-next-line typescript/no-non-null-assertion typescript/no-unsafe-type-assertion
        (pattern[shape] ?? pattern["_"]!)(shape as never);
 export const getMatcher = <T extends string | number>(): MatcherStrict<T> =>
    dispatch;
 export const getMatcherW = <T extends string | number>(): MatcherWidening<T> =>
    dispatch;
@@ -0,0 +1,207 @@
 import type { Exact, SetRequired, UnknownRecord } from "type-fest";
 import type {
    HandlerMap,
    Matchable,
    Member,
    PatternKey,
    PatternReturns,
    RedundantFallback,
    UnaryFn,
    UniverseGate,
 } from "./matcher-shared.ts";
 // A tagged union is discriminated by one property whose values are the tags (a
 // `Matchable`). `string` and `number` tags key a handler map directly;
 // `boolean`, `null` and `undefined` are admitted too but are not property keys,
 // so they go through the `PatternKey` projection. `symbol` has no literal syntax
 // to write a handler under, and `bigint` is not a property key.
 // The discriminant values of `T` under `K`. `Extract` keeps the finite literal
 // tags and leaves a widened `string`/`number` as itself; a broad tag is then
 // rejected by the universe gate.
 type Tags<T extends object, K extends keyof T> = Extract<T[K], Matchable>;
 // The keys of `T` that can act as a discriminant. `getTaggedUnionMatcher<T>()`
 // accepts only these, so the factory rejects a key whose values are not tags.
 type Discriminated<T extends object> = {
    [K in keyof T]: T[K] extends Matchable ? K : never;
 }[keyof T];
 // The member(s) of `T` narrowed to the tag(s) `V`. Distributes over `T`, so a
 // duplicated tag maps to a union of members rather than silently dropping one.
 // A member whose `K` cannot take `V` drops out; the rest have `K` narrowed to
 // `Extract<T[K], V>`. `T[K] extends V` keeps an exact member (a discriminated
 // union's declared interface) untouched, so only a property that is itself a
 // union — or optional — goes through the mapped form. `SetRequired` makes `K`
 // required unless `V` admits `undefined`: a defined tag yields `{ type: "x" }`,
 // while the `undefined` tag keeps `{ type?: never }` (absence) or
 // `{ type?: undefined }` when the property admits an explicit `undefined`.
 // Keyed by `PatternKey`, so `boolean`/`null`/`undefined` tags can key a mapped
 // type; `Member` inverts the projection against the tag set to recover the tag.
 type Narrowed<T extends object, K extends keyof T, V> = T extends object
    ? [Extract<T[K], V>] extends [never]
        ? never
        : T[K] extends V
          ? T
          : undefined extends V
            ? { [P in keyof T]: P extends K ? Extract<T[P], V> : T[P] }
            : SetRequired<
                  { [P in keyof T]: P extends K ? Extract<T[P], V> : T[P] },
                  K
              >
    : never;
 type MapTaggedUnion<T extends object, K extends keyof T> = {
    [P in PatternKey<Tags<T, K>>]: Narrowed<T, K, Member<Tags<T, K>, P>>;
 };
 type Handlers<T extends object, K extends keyof T, R> = {
    [P in PatternKey<Tags<T, K>>]: UnaryFn<MapTaggedUnion<T, K>[P], R>;
 };
 // The tag values whose `PatternKey` is handled.
 type HandledTags<T extends object, K extends keyof T, Handled> = Member<
    Tags<T, K>,
    keyof Handled
 >;
 // The fallback is a *second argument*, not a property of the handler map, so
 // its parameter can be the remainder the map left uncovered: the members
 // narrowed to the tags the map did not handle. See development/library.md.
 type Fallback<T extends object, K extends keyof T, Handled, R> = UnaryFn<
    Narrowed<T, K, Exclude<Tags<T, K>, HandledTags<T, K, Handled>>>,
    R
 >;
 // A fallback is redundant once the handler map covers every tag of `T`. Folded
 // into `Handled`'s own (self-referential) constraint so it is checked *after*
 // inference; see the primitive-union matcher for why a conditional in the fallback's
 // parameter is evaluated too early.
 type MustBePartial<T extends object, K extends keyof T, Handled> =
    PatternKey<Tags<T, K>> extends keyof Handled ? RedundantFallback : unknown;
 // TypeScript does not apply the excess-property check to a generic constraint,
 // so `Exact` restores it for the generic forms.
 // Strict returns: one common `R`. Overload order is load-bearing:
 //   #1 Handlers (first) -> the exhaustive form and the autocomplete popup
 //   #2 Fallback (last)  -> accepts a partial handler map plus a fallback
 interface TaggedUnionMatcherStrict<T extends object, K extends keyof T> {
    <R>(handlers: Handlers<T, K, R> & UniverseGate<Tags<T, K>>): UnaryFn<T, R>;
    <
        R,
        Handled extends Exact<Partial<Handlers<T, K, R>>, Handled> &
            MustBePartial<T, K, Handled>,
    >(
        handlers: Handled &
            Partial<Handlers<T, K, R>> &
            UniverseGate<Tags<T, K>>,
        fallback: Fallback<T, K, Handled, R> & UniverseGate<Tags<T, K>>,
    ): UnaryFn<T, R>;
 }
 // Widened returns: the union of every handler's return type. `P` is inferred
 // from the whole handler map, whose closed constraint supplies the
 // contextual/autocomplete type.
 interface TaggedUnionMatcherWidening<T extends object, K extends keyof T> {
    <P extends Exact<Handlers<T, K, unknown>, P>>(
        handlers: P & UniverseGate<Tags<T, K>>,
    ): UnaryFn<T, PatternReturns<P>>;
    <
        R,
        Handled extends Exact<Partial<Handlers<T, K, unknown>>, Handled> &
            MustBePartial<T, K, Handled>,
    >(
        handlers: Handled & UniverseGate<Tags<T, K>>,
        fallback: Fallback<T, K, Handled, R> & UniverseGate<Tags<T, K>>,
    ): UnaryFn<T, PatternReturns<Handled> | R>;
 }
 // The key-taking step of the curried factory. Naming it lets the factory return
 // `dispatch` directly, the tacit twin of the primitive-union factory's bare
 // `=> dispatch`.
 type TaggedUnionMatcherFactory<T extends object> = <K extends Discriminated<T>>(
    k: K,
 ) => TaggedUnionMatcherStrict<T, K>;
 type TaggedUnionMatcherWideningFactory<T extends object> = <
    K extends Discriminated<T>,
 >(
    k: K,
 ) => TaggedUnionMatcherWidening<T, K>;
 const dispatch =
    (k: PropertyKey) =>
    (handlers: HandlerMap, fallback?: UnaryFn<never, unknown>) =>
    (shape: object): unknown => {
        // `object` carries no index signature, so the read needs the assertion;
        // the factory admits only keys whose values are tags, and the map keys
        // them by `PatternKey`, so the result is narrowed to the map's key space.
        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
        const tag = (shape as UnknownRecord)[k] as string | number;
        return (
            handlers[tag] ??
            fallback ??
            (() => {
                throw new Error(`Unhandled tag: ${String(tag)}`);
            })
        )(
            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
            shape as never,
        );
    };
 /**
 * Create a matcher for a discriminated union, with one common return type.
 *
 * Use it when the value is an object discriminated by a property
 * (`{ kind: "circle" } | { kind: "square" }`) and every handler returns the
 * same type.
 *
 * The first call fixes the union `T`; the returned function takes the
 * discriminant property's name (`K`, restricted to properties whose values are
 * tags), and that returns the handler-map builder. Supplying a second fallback
 * argument to the builder allows a partial map and receives the members whose
 * tag was not handled. A `boolean`, `null` or `undefined` tag is keyed by its
 * stringified form (`true` -> `"true"`); see README § Caveats.
 *
 * @typeParam T - The discriminated-union type to match.
 * @returns A function that takes the discriminant property's name.
 * @example
 *     type Shape =
 *         | { kind: "circle"; radius: number }
 *         | { kind: "square"; side: number };
 *
 *     const matchShape = getTaggedUnionMatcher<Shape>()("kind");
 *     const area = matchShape({
 *         circle: (s) => Math.PI * s.radius ** 2,
 *         square: (s) => s.side ** 2,
 *     });
 */
 export const getTaggedUnionMatcher = <
    T extends object,
 >(): TaggedUnionMatcherFactory<T> => dispatch;
 /**
 * Create a matcher for a discriminated union whose return type is the union of
 * every handler's return type.
 *
 * Use it when the value is a discriminated object and the handlers return
 * different types. The `W` (widening) counterpart of
 * {@link getTaggedUnionMatcher}; the curried key step and the optional fallback
 * are identical.
 *
 * @typeParam T - The discriminated-union type to match.
 * @returns A function that takes the discriminant property's name.
 * @example
 *     const matchShape = getTaggedUnionMatcherW<Shape>()("kind");
 *     const describe = matchShape({
 *         circle: () => "round",
 *         square: () => 4,
 *     });
 *     // describe: (shape: Shape) => string | number
 */
 export const getTaggedUnionMatcherW = <
    T extends object,
 >(): TaggedUnionMatcherWideningFactory<T> => dispatch;
@@ -1,4 +1,3 @@
 /* oxlint-disable typescript/no-floating-promises -- expectTypeOf() is a sync type-assertion library that the type-aware linter misidentifies as a promise */
 import { strict as assert } from "node:assert";
 import path from "node:path";
 import { test } from "node:test";
@@ -8,5 +8,6 @@
        "allowImportingTsExtensions": true,
        "verbatimModuleSyntax": true
    },
-    "include": ["src", "scripts"]
+    "include": ["src", "scripts"],
    "exclude": ["src/doc-test"]
 }