🚀 Release 0.8.1

🔀 Merge chore/coverage-threshold into main
👷 Gate CI at 100% coverage
2026-09-23 21:24:42 +00:00 · 2026-09-23 21:23:37 +00:00 · 2026-09-23 21:12:24 +00:00 · 2026-09-23 20:55:56 +00:00 · 2026-09-23 20:52:45 +00:00 · 2026-09-23 20:30:44 +00:00
25 changed files with 3995 additions and 1092 deletions
@@ -77,6 +77,9 @@ jobs:
            - run: npm ci
            - run: npm run build
            - run: npm run check
+            # 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
@@ -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"
            }
        },
        {
@@ -9,7 +9,7 @@ first-action facts. Do not restate evolving prose here — it will drift.

 - Project: F#-style 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.
 - **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.
@@ -25,10 +25,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>`.

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [Unreleased]

+## [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
@@ -63,7 +101,13 @@ 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.4.0...main
+[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.1...main
+[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
@@ -41,7 +41,7 @@ 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 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 +66,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)).
@@ -122,7 +125,8 @@ CI step. Pick the prefix that matches the script's lifecycle:
  `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:ci` runs the suite under c8 and fails below 100% coverage on `src/`
+  (CI-only; `verify` stays coverage-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 +159,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
-  [AGENTS.md § Never do](./AGENTS.md#never-do). The sole agent exception is the
-  fixed file-level header at the top of a `*.test.ts` file, spelled exactly:
-  `/* 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:
+  convention; agents must not add one, nor edit `.oxlintrc.json` to silence a
+  finding (e.g. `typescript/no-floating-promises`) — see
+  [AGENTS.md § Never do](./AGENTS.md#never-do). (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:
@@ -9,7 +9,7 @@ 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
 not a macro: there is no transpiler and no DSL to learn, and the type-level
 contract is the feature — see [development/library.md](./development/library.md)
-for the design decisions and the known limitations.
+for the design decisions and [Caveats](#caveats) for the limits.

 ## Requirements

@@ -23,6 +23,36 @@ for the design decisions and the known limitations.

 Yet to be implemented

+## 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).
+
 ## License

 MIT © 2025 tmu. See [LICENSE](./LICENSE).
@@ -6,54 +6,21 @@ 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
+✔ Test coverage meets threshold @done
+    ✔ Achieve 100% branch coverage on `src/primitive-union.ts` @done
+    ✔ Achieve 100% branch coverage on `src/index.ts` @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 @done
-    → the fallback is now a second argument: `(handlers, (s) => …)`, `s: Exclude<T, keyof handlers>`
-☐ A fallback for an already-exhaustive handler map must be a compile error @medium
-    → `(handlers, fallback)` with `handlers` covering all of `T` is accepted; the redundant fallback should be rejected (currying would allow the guard)
-
-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
+✔ when using a union type as a property, the current behavior of tagged union matcher is @done
+    to pass never to handler parameters
+    → new matcher function needed or can be fixed in tagged union matcher
+    ✔ optional discriminant (`{ type?: "x" }`) is the same hole: the boolean/nullish change now admits the `undefined` tag, so the factory accepts the key, but `Extract<T, Record<K, V>>` still passes `never` to both the `x` and `undefined` handlers @done

 Documentation:
 ☐ Bring README.md back to its previous form — synopsis and examples restored, in the correct place
@@ -63,12 +30,8 @@ Documentation:
 ☐ 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
    ☐ Explore serving coverage for non-tag pushes (e.g. `main/coverage`, PR previews) @low
@@ -81,3 +44,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 TypeScript 5.0 baseline in CI
@@ -43,7 +43,9 @@
        "silverwind",
        "idris",
        "todotasks",
-        "connor"
+        "connor",
+        "injective",
+        "injectivity"
    ],
    "ignorePaths": ["dist", "node_modules", "coverage", "*.svg", ".gitignore"]
 }
@@ -97,6 +97,39 @@ 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.
+
 ## Coverage serving

 #### Decision (2026-09)
@@ -3,9 +3,10 @@
 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 is implemented in `src/primitive.ts` and re-exported from
-`src/index.ts` as `getMatcher` / `getMatcherW`; the rest of the library is
-placeholder code.
+The matchers are implemented in `src/primitive-union.ts` (`getPrimitiveUnionMatcher` /
+`getPrimitiveUnionMatcherW`) and `src/tagged-union.ts` (`getTaggedUnionMatcher` /
+`getTaggedUnionMatcherW`), re-exported from `src/index.ts`; the rest of the
+library is placeholder code.

 ## Matcher shape

@@ -15,8 +16,8 @@ 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 fallback = getMatcher<"a" | "b" | "c">()({ a: (s) => … }, (s) => …);
+const matcher = getPrimitiveUnionMatcher<"a" | "b">()({ a: (s) => …, b: (s) => … });
+const fallback = getPrimitiveUnionMatcher<"a" | "b" | "c">()({ a: (s) => … }, (s) => …);
 ```

 Exhaustive or fallback is decided **at the call site**, by whether the second
@@ -24,15 +25,16 @@ argument is present. The fallback's parameter is the remainder
 `Exclude<T, keyof Handled>`. Only the return-strictness axis remains, so there
 are two factories:

- `getMatcher` — one common `R`; the fallback must fit it;
- `getMatcherW` — the union `PatternReturns<Handled> | R`.
+- `getPrimitiveUnionMatcher` — one common `R`; the fallback must fit it;
+- `getPrimitiveUnionMatcherW` — the union `PatternReturns<Handled> | R`.

 Each factory is two overloads whose order is load-bearing:

 1. `Handlers<T, R>` — the exhaustive form, and the contextual type of the
   handler-map popup;
-2. `Handled extends Exact<Partial<Handlers<T, R>>, Handled>` plus
-   `Fallback<T, Handled, R>` — a partial handler map plus the fallback.
+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

@@ -41,6 +43,14 @@ Each factory is two overloads whose order is load-bearing:
  handler map can only see all of `T`, never `Exclude<T, keyof Handled>`. A later
  argument is contextually typed from inference on an earlier one, so the split
  is what makes the remainder expressible.
+- **The redundant-fallback guard is an F-bounded constraint.** A map that
+  already covers `T` plus a fallback is rejected by folding
+  `MustBePartial<T, Handled>` into `Handled`'s own constraint. The guard is
+  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.
@@ -57,9 +67,9 @@ Each factory is two overloads whose order is load-bearing:
 - **Single-object `_`** (the former shape). `_` sees only all of `T`; the
  remainder is not expressible there, and an exhaustive map plus `_` was
  accepted.
- **Curried handlers-first** — `(handlers)(fallback)`. `Handled` is fixed before
-  the second call, so a redundant-fallback guard would work. Rejected: two calls
-  for the common case.
+- **Curried handlers-first** — `(handlers)(fallback)`. Rejected: two calls for
+  the common case. It is not needed for the redundant-fallback guard, which the
+  F-bounded constraint already provides (see Why).
 - **`this` / HKT self-reference.** `this` is post-construction (method bodies,
  return positions); a parameter's contextual type is pre-construction.
  `keyof this` in an interface method is the interface, not the literal.
@@ -76,14 +86,195 @@ Each factory is two overloads whose order is load-bearing:

 #### Known issue

- A redundant fallback is accepted: when the handler map already covers `T`, the
-  fallback is still allowed. The guard would be
-  `Exclude<T, keyof Handled> extends never ? never : unknown`, but the
-  conditional is evaluated before `Handled` is inferred; currying is the only
-  encoding that fixes it (see Rejected).
 - `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
-  test files that use it (`src/primitive.test.ts`) carry a file-level
-  `oxlint-disable typescript/no-floating-promises` with an explanatory comment.
-  It is a known false positive, not a rule worth disabling project-wide (see
+- The type-aware linter misidentifies `expectTypeOf()` as a floating promise.
+  It is a known false positive, so `typescript/no-floating-promises` is off for
+  `**/*.test.ts` in the `.oxlintrc.json` override rather than repeated as a
+  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
-`oxlint-disable` directive (see `src/primitive.ts`,
-`src/primitive.test.ts`), not by turning the rule off in `.oxlintrc.json`.
+A type-aware rule that false-positives **at one site** is silenced with a
+source-level `oxlint-disable` directive (see `src/primitive-union.ts`). A rule that is
+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
-  source.
- The rule stays on everywhere else, so only the mis-firing line is exempted.
+- A one-site disable sits next to the code it silences, visible to anyone
+  reading the source, and the rule stays on everywhere else.
+- 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
-  exemption from the reader of the affected code and switches the rule off
-  repo-wide for a one-site problem.
+- A project-wide disable in `.oxlintrc.json` for a one-site false positive: it
+  hides the exemption from the reader of the affected code and switches the rule
+  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;
-  they fix the type at its root (see [AGENTS.md § Never do](../AGENTS.md#never-do)).
+- Both placements are _human_ last resorts. AI agents must neither add a source
+  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,28 @@ 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` lists `src/index.ts` as an entry
+
+#### Decision (2026-09)
+
+`knip.json` declares `"entry": ["src/index.ts", "scripts/*.ts"]`.
+
+#### Why
+
+- Supplying `entry` **replaces** knip's default entry detection, which otherwise
+  derives the public entry from `package.json` `exports`. Adding `scripts/*.ts`
+  there therefore dropped the library entry, so knip resolved the package through
+  its `dist/index.js` output and reported the unreferenced source entry file
+  `src/index.ts` as an unused file.
+- Naming the source entry restores the link between the public API and the
+  source graph without pointing knip at build output.
+
+#### Rejected
+
+- `paths` mapping `dist/index.*` back to `src/index.ts`: more config to model a
+  relation the explicit entry states directly, and it would break whenever the
+  build layout changes.
+
 ### `maintain:outdated` ignores `@types/node`

 #### Decision (2026-09)
@@ -1,5 +1,5 @@
 {
    "$schema": "./node_modules/knip/schema.json",
-    "entry": ["scripts/*.ts"],
+    "entry": ["src/index.ts", "scripts/*.ts"],
    "ignoreDependencies": ["@runwisp/pubv"]
 }
@@ -1,6 +1,6 @@
 {
    "name": "tiny-pattern-ts",
-    "version": "0.4.0",
+    "version": "0.8.1",
    "description": "Pattern matching for TypeScript/ESM environments (F#-style, not regex)",
    "keywords": [
        "adt",
@@ -58,7 +58,7 @@
        "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": "c8 --all --include \"src/**/*.ts\" --reporter=text --reporter=lcov --reporter=html --100 node --test --strip-types \"src/**/*.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 +83,7 @@
        "expect-type": "1.4.0",
        "knip": "^6.34.0",
        "lefthook": "^2.1.12",
-        "oxfmt": "^0.68.0",
+        "oxfmt": "^0.70.0",
        "oxlint": "^1.83.0",
        "oxlint-tsgolint": "^7.0.2001",
        "publint": "^0.3.24",
@@ -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,8 @@
-export { getMatcher, getMatcherW } from "./primitive.ts";
+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,104 @@
+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,
+        );
+
+export const getPrimitiveUnionMatcher = <
+    T extends Matchable,
+>(): PrimitiveUnionMatcherStrict<T> => dispatch;
+export const getPrimitiveUnionMatcherW = <
+    T extends Matchable,
+>(): PrimitiveUnionMatcherWidening<T> => dispatch;
@@ -1,491 +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) => {
-            expectTypeOf(s).toEqualTypeOf<"a">();
-            return 1;
-        },
-        b: (s) => {
-            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) => {
-            expectTypeOf(s).toEqualTypeOf<"a">();
-            return 1;
-        },
-        b: (s) => {
-            expectTypeOf(s).toEqualTypeOf<"b">();
-            return 2;
-        },
-        1: (n) => {
-            expectTypeOf(n).toEqualTypeOf<1>();
-            return 10;
-        },
-        2: (n) => {
-            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 receives the unhandled keys", () => {
-    // Arrange
-    const factory = getMatcher<"a" | "b" | "c">();
-
-    // Act
-    const matcher = factory(
-        {
-            a: (s) => {
-                expectTypeOf(s).toEqualTypeOf<"a">();
-                return 1 as const;
-            },
-        },
-        (s) => {
-            // The fallback sees only the keys `a` did not handle.
-            expectTypeOf(s).toEqualTypeOf<"b" | "c">();
-            return 2 as const;
-        },
-    );
-
-    // 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 routes mixed string and numeric gaps", () => {
-    // Arrange
-    const factory = getMatcher<"a" | "b" | 1 | 2>();
-
-    // Act
-    const matcher = factory(
-        {
-            a: (s) => {
-                expectTypeOf(s).toEqualTypeOf<"a">();
-                return "A";
-            },
-            1: (n) => {
-                expectTypeOf(n).toEqualTypeOf<1>();
-                return "one";
-            },
-        },
-        (s) => {
-            expectTypeOf(s).toEqualTypeOf<"b" | 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 only the keys `x` did not handle.
-            expectTypeOf(s).toEqualTypeOf<"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<"b" | 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");
-});
-
-// ============================================================================
-// 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 a `_` fallback is not exhaustive
-    factory({ a: () => 1 });
-    // @ts-expect-error a `string` fallback does not fit the `number` handler
-    factory({ a: () => 1 }, () => "x");
-});
-
-test("getMatcherW factory rejects patterns outside its contract", () => {
-    // Arrange
-    const factory = getMatcherW<"x" | "y">();
-
-    // Act / Assert — the calls below must not compile
-    factory({
-        x: () => 1 as const,
-        y: () => 2 as const,
-        // @ts-expect-error `z` is not part of the universe `"x" | "y"`
-        z: () => 3 as const,
-    });
-    // @ts-expect-error a gap without a `_` fallback is not exhaustive
-    factory({ x: () => 1 as const });
-});
-
-// ============================================================================
-// Dispatch — runtime behavior
-// ============================================================================
-
-test("getMatcher: an unhandled shape throws without a fallback", () => {
-    // Arrange — an open universe types its handler map as an index signature,
-    // so the type system cannot prove the runtime map is exhaustive.
-    const handlers: Record<string, () => number> = { a: () => 1 };
-    const matcher = getMatcher<string>()(handlers);
-
-    // Act / Assert
-    assert.equal(matcher("a"), 1);
-    assert.throws(() => matcher("b"), /Unhandled shape: b/);
-});
-
-// ============================================================================
-// 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.
-interface LabelsProbe {
-    readonly name: string;
-    readonly factory: "getMatcher" | "getMatcherW";
-    readonly body: string;
-    readonly tail?: string;
-}
-
-const labelsFor = ({
-    name,
-    factory,
-    body,
-    tail = "",
-}: LabelsProbe): 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,
-            `}${tail});`,
-            "",
-        ].join("\n"),
-    };
-    return session
-        .completionLabelsAt(target)
-        .then((result) => result.labels)
-        .finally(() => session.close());
-};
-
-test("autocomplete: an exhaustive pattern requires the universe", () => {
-    // Arrange
-    const name = "getMatcher_fresh";
-
-    // Act
-    const labels = labelsFor({
-        name,
-        factory: "getMatcher",
-        body: "    /*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,
-        factory: "getMatcher",
-        body: "    a: () => 1,\n    /*COMPLETE*/",
-    });
-
-    // Assert
-    return labels.then((result) => {
-        assert.deepEqual([...result], ["b", "c"]);
-    });
-});
-
-test("autocomplete: a fallback makes the remaining keys optional", () => {
-    // Arrange
-    const name = "getMatcher_with_fallback";
-
-    // Act
-    const labels = labelsFor({
-        name,
-        factory: "getMatcher",
-        body: "    /*COMPLETE*/",
-        tail: ", () => 0",
-    });
-
-    // Assert
-    return labels.then((result) => {
-        assert.deepEqual([...result], ["a?", "b?", "c?"]);
-    });
-});
-
-test("autocomplete: with a fallback, handled keys stay optional", () => {
-    // Arrange
-    const name = "getMatcher_with_fallback_after_key";
-
-    // Act
-    const labels = labelsFor({
-        name,
-        factory: "getMatcher",
-        body: "    a: () => 1,\n    /*COMPLETE*/",
-        tail: ", () => 0",
-    });
-
-    // Assert
-    return labels.then((result) => {
-        assert.deepEqual([...result], ["b?", "c?"]);
-    });
-});
-
-test("autocomplete: `getMatcherW` offers the same popup as `getMatcher`", () => {
-    // Arrange
-    const name = "getMatcherW_fresh";
-
-    // Act
-    const labels = labelsFor({
-        name,
-        factory: "getMatcherW",
-        body: "    /*COMPLETE*/",
-    });
-
-    // Assert
-    return labels.then((result) => {
-        assert.deepEqual([...result], ["a", "b", "c"]);
-    });
-});
-
-test("autocomplete: `getMatcherW` also offers optional keys with a fallback", () => {
-    // Arrange
-    const name = "getMatcherW_with_fallback";
-
-    // Act
-    const labels = labelsFor({
-        name,
-        factory: "getMatcherW",
-        body: "    /*COMPLETE*/",
-        tail: ", () => 0",
-    });
-
-    // Assert
-    return labels.then((result) => {
-        assert.deepEqual([...result], ["a?", "b?", "c?"]);
-    });
-});
@@ -1,75 +0,0 @@
-import type { Exact, 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<T extends string | number, R> = { [K in T]: UnaryFn<K, R> };
-
-// The fallback is a *second argument*, not a property of the handler map,
-// because its parameter is the remainder `Exclude<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 string | number, Handled, R> = UnaryFn<
-    Exclude<T, keyof Handled>,
-    R
->;
-
-// 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`.
-
-// oxlint-disable typescript/unified-signatures
-// 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 MatcherStrict<T extends string | number> {
-    <R>(handlers: Handlers<T, R>): UnaryFn<T, R>;
-    <R, Handled extends Exact<Partial<Handlers<T, R>>, Handled>>(
-        handlers: Handled & Partial<Handlers<T, R>>,
-        fallback: Fallback<T, Handled, R>,
-    ): UnaryFn<T, R>;
-}
-// oxlint-enable typescript/unified-signatures
-
-// 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.
-// oxlint-disable typescript/unified-signatures
-interface MatcherWidening<T extends string | number> {
-    <P extends Exact<Handlers<T, unknown>, P>>(
-        handlers: P,
-    ): UnaryFn<T, PatternReturns<P>>;
-    <R, Handled extends Exact<Partial<Handlers<T, unknown>>, Handled>>(
-        handlers: Handled,
-        fallback: Fallback<T, Handled, R>,
-    ): UnaryFn<T, PatternReturns<Handled> | R>;
-}
-// oxlint-enable typescript/unified-signatures
-
-type HandlerMap = Record<string | number, UnaryFn<never, unknown> | undefined>;
-
-const dispatch =
-    (handlers: HandlerMap, fallback?: UnaryFn<never, unknown>) =>
-    (shape: string | number): unknown =>
-        (
-            handlers[shape] ??
-            fallback ??
-            (() => {
-                throw new Error(`Unhandled shape: ${shape}`);
-            })
-        )(
-            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
-            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,161 @@
+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,
+        );
+    };
+
+export const getTaggedUnionMatcher = <
+    T extends object,
+>(): TaggedUnionMatcherFactory<T> => dispatch;
+
+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";
Author	SHA1	Message	Date
tmu	acf9d06ddd	🚀 Release 0.8.1 CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 35s Details CI / maintain (push) Successful in 14s Details CI / publish (push) Failing after 16s Details	2026-09-23 21:24:42 +00:00
tmu	eba60f6569	🔀 Merge chore/coverage-threshold into main	2026-09-23 21:23:37 +00:00
tmu	52ce655d8e	👷 Gate CI at 100% coverage test:ci now runs c8 with --all --include "src/*/.ts" --100, so the build job fails when any runtime file under src/ is untested. --all is what makes the gate non-vacuous: without it c8 counts only the files the suite happened to load, and a new untested module stays invisible. Add src/index.test.ts to load the public barrel, which was previously never imported at runtime and so read as 0% under --all. matcher-shared.ts is types-only (an empty runtime image) and carries a file-level c8 ignore with the reason. Why 100% and the rejected alternatives: development/ci.md § Coverage threshold.	2026-09-23 21:12:24 +00:00
tmu	76327a8c47	🔀 Merge chore/duplicate-tag-union-test into main	2026-09-23 20:55:56 +00:00
tmu	d7004c0f71	📝 Clarify the duplicate-tag known issue	2026-09-23 20:52:45 +00:00
tmu	69231eb9ac	📝 Note the duplicate-tag tests in the changelog	2026-09-23 20:30:44 +00:00
tmu	7ff371c569	✅ Pin the duplicate-tag union collapse	2026-09-23 20:30:35 +00:00
tmu	0339a493a2	📝 Track the TypeScript 5.0 CI baseline	2026-09-23 20:28:53 +00:00
tmu	2c856f28e3	🔀 Merge chore/open-universe-guidance into main	2026-09-23 20:01:52 +00:00
tmu	4260a4732c	📝 Document why open universes are rejected Add a README Caveats subsection with user-facing guidance for the two open-universe shapes: parse external input at the boundary down to a finite union, or use a runtime Map registry for extensible domains. Point the finite-universe bullet at it, and point the rejected fix/open-universe-* entry in development/library.md back at the new guidance, so rule and decision cross-reference without duplicating each other.	2026-09-23 19:51:19 +00:00
tmu	11d364e187	🚀 Release 0.8.0 CI / release-gate (push) Successful in 3s Details CI / build (push) Successful in 34s Details CI / maintain (push) Successful in 15s Details CI / publish (push) Failing after 19s Details	2026-09-23 17:42:32 +00:00
tmu	8dc0b95320	🔀 Merge fix/union-valued-discriminant into main	2026-09-23 17:37:37 +00:00
tmu	7b90f898d3	✅ Cover property-union autocomplete and rejection Add property-union tests for the completion popup, a broad value in the union, and value/stringification collisions. Rename the existing property-union tests to a `property union:` prefix so they can be selected with `--test-name-pattern`, and extend the autocomplete helper with a `key` option so a probe can complete on a property other than `kind`.	2026-09-23 16:32:16 +00:00
tmu	1bdf7f0315	🐛 Reject mixed literal and broad universes `UnsupportedReason` tested `IsLiteral<PatternKey<T>> extends false`. `IsLiteral` is `boolean` for a union that mixes a literal with a broad type (`"a" \| \`x-${number}\``), so `boolean extends false` is false and the mix was accepted. Test `extends true` instead, which rejects it. Found while adding property-union broad-universe coverage; the gate is shared with the primitive-union matcher.	2026-09-23 16:32:09 +00:00
tmu	55bf6c24a7	🐛 Narrow union-valued and optional discriminants The tagged-union matcher selected handler parameters with `Extract<T, Record<K, V>>`, which only keeps a member whose discriminant is a singleton literal. A property that is itself a union (`{ color: "red" \| "green" \| "blue" }`) or optional (`{ type?: "x" }`) matched no member, so every handler received `never`, and the fallback saw the whole shape instead of the unhandled tags. Replace the selector with `Narrowed`, which distributes over `T`, drops a member whose `K` cannot take the tag, and narrows `K`. The `T[K] extends V` fast path keeps an exact member (a discriminated union's declared interface) untouched. The fallback reuses `Narrowed` over `Exclude<Tags, HandledTags>`, so a union-valued property narrows to the unhandled tags rather than the whole shape. Matching a defined tag on an optional property makes the key required (`{ type: "x" }`); the `undefined` tag yields `{ type?: never }` under `exactOptionalPropertyTypes` (absence) or `{ type?: undefined }` when the property admits an explicit `undefined`.	2026-09-23 16:04:00 +00:00
tmu	e7b5c0284d	🔀 Merge chore/prune-backlog into main	2026-09-23 15:27:05 +00:00
tmu	013bfa883b	📝 Prune the backlog; document the LSP shutdown fix Remove every done/cancelled backlog item; the reasons they recorded are already in development/ (library.md, testing.md, tooling.md, workflow.md) and git history is the archive. The one exception was the TS 7 LSP shutdown workaround, which lived only in a code comment. Record it under development/testing.md § Autocomplete (Known issue) before dropping the bug item.	2026-09-23 15:12:54 +00:00
tmu	d99d84d387	🚀 Release 0.7.1 CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 34s Details CI / maintain (push) Successful in 15s Details CI / publish (push) Failing after 17s Details	2026-09-23 14:56:59 +00:00
tmu	02f64f804e	🔀 Merge fix/knip-library-entry into main	2026-09-23 14:56:15 +00:00
tmu	cbaed8fabc	🐛 Stop knip reporting the source entry Listing scripts/*.ts in knip's `entry` replaced its default entry detection, which derives the public entry from package.json `exports`. Adding the CLI scripts therefore dropped the library entry, so knip resolved the package through dist/index.js and flagged the unreferenced src/index.ts as unused. Name the source entry alongside the scripts. Record the rationale in development/tooling.md.	2026-09-23 14:55:27 +00:00
tmu	410903198e	🔀 Merge chore/upgrade-deps into main	2026-09-23 14:51:49 +00:00
tmu	2e4262383c	⬆️ Upgrade dependencies Bump every direct dependency to the latest registry version: cspell 10.3.3, knip 6.38.0, oxfmt 0.70.0, oxlint 1.85.0, oxlint-tsgolint 7.0.2002 and type-fest 5.10.0, plus their transitive updates. oxfmt is the only range widened (^0.68.0 -> ^0.70.0); the rest moved within their existing semver ranges. `npm run maintain:outdated` is now clean and `npm run verify` is green with no rule or format fallout. `maintain:knip` still reports the pre-existing `src/index.ts` false positive (dist-only `exports`), which predates this bump.	2026-09-23 14:50:29 +00:00
tmu	a8f1a05db2	🚀 Release 0.7.0 CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 34s Details CI / maintain (push) Failing after 16s Details CI / publish (push) Failing after 17s Details	2026-09-23 14:34:51 +00:00
tmu	675fd0bb54	🔀 Merge feature/finite-universes into main CI / release-gate (push) Successful in 3s Details CI / build (push) Successful in 25s Details CI / publish (push) Skipped Details CI / maintain (push) Failing after 14s Details	2026-09-23 13:48:11 +00:00
tmu	ce287b384f	📝 Note the gate in changelog and backlog Close the broad-universe type-hole task and cancel the widened-literal test task, since arbitrary strings no longer fall through to a fallback.	2026-09-23 13:42:25 +00:00
tmu	aaeeef1e11	📝 Document the finite-only universe decision Record why open universes and value/stringification collisions are rejected, the `Member<T, K>` inversion, and the findings from the rejected open-universe attempt so they are not re-run.	2026-09-23 13:42:12 +00:00
tmu	3b5269f9e1	🐛 Gate the universe to finite, literal keys An open universe (`string`, `number`, a template literal) makes the handler map index-like, so a partial object satisfied the exhaustive overload and the runtime `dispatch` throw was reachable. A universe containing a member and its stringification (`"true" \| true`, `1 \| "1"`) collapsed two members onto one key. - reject broad universes and value/stringification collisions at the factory, with a diagnostic naming the reason - invert `PatternKey` against the universe (`Member<T, K>`) instead of `PatternParam<K>`, so a standalone `"true"` is typed `"true"` - intersect `UniverseGate<T>` into the handler and fallback parameters, preserving `R` inference and the popup	2026-09-23 13:41:57 +00:00
tmu	1723419e69	🚀 Release 0.6.0 CI / release-gate (push) Successful in 3s Details CI / build (push) Successful in 33s Details CI / maintain (push) Failing after 13s Details CI / publish (push) Failing after 16s Details	2026-09-22 11:10:34 +00:00
tmu	dcd5f8d1c4	🔀 Merge feature/tagged-union-boolean-nullish-tags into main	2026-09-22 11:09:21 +00:00
tmu	4ebe18adb1	♻️ Align primitive-union matcher names and drop stale lint disables Rename `MatcherStrict` / `MatcherWidening` to `PrimitiveUnionMatcherStrict` / `PrimitiveUnionMatcherWidening`, matching the exported `getPrimitiveUnionMatcher(W)` names and the `TaggedUnionMatcher*` pair. Folds in the working-tree lint cleanups: drop the now-unneeded `typescript/unified-signatures` disables and turn the tagged-union factory interfaces into type aliases.	2026-09-22 11:05:16 +00:00
tmu	09e1c12270	♻️ Return dispatch tacitly from the tagged-union factory	2026-09-22 10:57:03 +00:00
tmu	6228b4922d	♻️ Share the Matchable universe between both matchers	2026-09-22 10:54:27 +00:00
tmu	d88a4eeb45	📝 Track optional discriminants under the union-property task	2026-09-22 10:45:54 +00:00
tmu	fcec637f01	✅ Check the runtime member in every boolean/nullish handler	2026-09-22 10:36:03 +00:00
tmu	f7b7a06f1a	✅ Assert the fallback receives real boolean/nullish tags	2026-09-22 10:33:26 +00:00
tmu	c06538d6c1	📝 Check off the tagged-union non-key tags task	2026-09-22 10:23:06 +00:00
tmu	e96ca12149	✨ Allow boolean and nullish tags in tagged unions A `boolean` / `null` / `undefined` discriminant cannot key a handler map, so the tagged-union matcher now routes it through the `PatternKey` / `PatternParam` projection the primitive-union matcher already used. Both matchers share the projection from `matcher-shared.ts`; `MapTaggedUnion`, `Handlers`, `HandledMembers` and `MustBePartial` key off the projected form and invert it to recover the real member. Covers exhaustive and fallback dispatch, the redundant-fallback guard, and the LSP popup offering the tags by name.	2026-09-22 10:22:59 +00:00
tmu	b81a8149d9	🔀 Merge chore/rename-primitive-union into main	2026-09-22 09:58:28 +00:00
tmu	a88d49ffe2	📝 Check off the primitive-union rename	2026-09-22 09:47:05 +00:00
tmu	02f736507c	♻️ Rename primitive to primitive-union `getMatcher` / `getMatcherW` become `getPrimitiveUnionMatcher` / `getPrimitiveUnionMatcherW`; `src/primitive.ts` and its test move to `src/primitive-union.*`. The `Union` suffix mirrors `getTaggedUnionMatcher`.	2026-09-22 09:46:59 +00:00
tmu	0727117afb	🔀 Merge chore/lsp-symbol-search-rule into main	2026-09-22 09:43:56 +00:00
tmu	b293e611b2	📝 Prefer LSP for symbol lookup in AGENTS	2026-09-22 09:43:08 +00:00
tmu	63b020338e	🔀 Merge chore/backlog-notes into main	2026-09-22 09:15:04 +00:00
tmu	32b9ce0987	📝 Note two matcher gaps in the backlog Record the non-exhaustive broad-type hole in the primitive matcher and the never-typed handler parameters the tagged-union matcher produces when a property is a union, so both can be picked up as their own work units.	2026-09-22 09:14:58 +00:00
tmu	434c3a2222	🔀 Merge feature/tagged-union-matcher into main CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 27s Details CI / publish (push) Skipped Details CI / maintain (push) Failing after 15s Details	2026-09-21 23:29:48 +00:00
tmu	6280061737	📝 Note the primitive-union rename in the backlog	2026-09-21 23:24:06 +00:00
tmu	23a2776d55	📝 Note the widened-string-union matcher test	2026-09-21 23:21:19 +00:00
tmu	937d84ea48	♻️ Share matcher internals	2026-09-21 23:15:09 +00:00
tmu	6f4f509b69	⚡ Inline the tag read into dispatch	2026-09-21 23:02:56 +00:00
tmu	3f22e5ca01	🔥 Drop unused unified-signature disables	2026-09-21 22:53:42 +00:00
tmu	78e9af600d	✅ Cover the discriminant-key popup	2026-09-21 22:36:30 +00:00
tmu	8ab3c6dbc6	📝 Document the tagged-union matcher	2026-09-21 22:14:22 +00:00
tmu	c0fc090ee4	✨ Add a matcher for tagged unions	2026-09-21 22:14:10 +00:00
tmu	a4b4618c9f	🚀 Release 0.5.0 CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 30s Details CI / maintain (push) Failing after 14s Details CI / publish (push) Failing after 17s Details	2026-09-21 13:11:27 +00:00
tmu	bf711cf9fc	🔀 Merge chore/test-handler-runtime-arguments into main	2026-09-21 13:09:10 +00:00
tmu	9e03c52473	✅ Assert the shape each handler receives A handler's `expectTypeOf(shape)` only proved the type the compiler inferred; nothing observed the argument `dispatch` passed. Passing `String(shape)` at the call site therefore kept the whole suite green while breaking every key whose property name differs from its value (`true`, `null`, `1`). Pair each handler expectation with a runtime assertion: `assert.equal` where a handler runs for one shape, the disjunction over the set a `_` fallback accepts where it runs for several. Where the exact value matters the fallback returns its shape verbatim and the call site asserts it; a widening pattern absorbs the remainder type into the return union, so the claim stays strict-free. The mutation above now fails 10 of the 33 tests. Rule: CONTRIBUTING.md, rationale: development/testing.md § Handler arguments.	2026-09-21 12:52:58 +00:00
tmu	aa6d71076c	🔀 Merge feature/boolean-null-undefined-patterns into main	2026-09-21 11:27:29 +00:00
tmu	80d498e4f4	⚡ Index dispatch with the raw shape key String(shape) defeats V8's numeric-key fast path (measured ~2x on number-keyed dispatch). JS already coerces boolean/null/undefined to the same property key, so assert shape to string \| number and index directly. The assertion is TS2538-only; the facade keeps it sound. Needs a source no-unsafe-type-assertion disable, next to the existing one.	2026-09-21 11:23:14 +00:00
tmu	1ad19ba308	📝 Document matcher caveats in the README State the end-user limits once, in README § Caveats: a member colliding with its stringification, the unsupported symbol/bigint, and NaN/-0. Drop the duplicated known-issue prose from development/library.md and the source comment; link to the README instead.	2026-09-21 10:33:36 +00:00
tmu	16904440cf	📝 Place test-wide suppressions in the config Drop the fixed no-floating-promises header exception from CONTRIBUTING.md and AGENTS.md; agents must not add a source disable or edit .oxlintrc.json. Record the split in tooling.md and testing.md: a one-site false positive is a source disable, a file-class one lives in the test override.	2026-09-21 10:01:30 +00:00
tmu	9b7dec96e0	🔧 Move test lint disables to oxlint config The no-floating-promises header was repeated at the top of every test file. Centralize it, and the no-null suppression the new null/undefined cases need, in the */.test.ts override.	2026-09-21 09:56:39 +00:00
tmu	45495fe2a8	✨ Match boolean, null and undefined Extend the matcher universe beyond string \| number so a union can carry boolean, null and undefined members. true\|false, null and undefined are not property keys, so handler keys are their stringification while the callback still receives the real member. Symbols are rejected (a brand is compile-time only) and bigint is not a property key.	2026-09-21 09:44:44 +00:00
tmu	c32fe08c73	🔀 Merge chore/spike-redundant-fallback into main CI / release-gate (push) Successful in 3s Details CI / build (push) Successful in 24s Details CI / publish (push) Skipped Details CI / maintain (push) Failing after 16s Details	2026-09-20 22:08:35 +00:00
tmu	f27966e803	✨ Reject a fallback for an exhaustive map A fallback paired with a handler map that already covers `T` was still accepted, even though its remainder is empty. Fold the guard into `Handled`'s own (F-bounded) constraint so it is checked after inference; a conditional in the fallback parameter is evaluated while `Handled` is still its constraint and rejects every partial map whose handler callbacks need contextual typing.	2026-09-20 22:05:40 +00:00