🚀 Release 0.8.0

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`.

AGENTS.md

@@ -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.

CHANGELOG.md

@@ -7,7 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
 
@@ -70,7 +94,11 @@ 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.5.0...main
+[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.0...main
+[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

CONTRIBUTING.md

@@ -71,7 +71,7 @@ Every test pairs an `expectTypeOf(...)` with an `assert.*`; keep them together
 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)).

README.md

@@ -25,10 +25,15 @@ Yet to be implemented
 
 ## Caveats
 
-- **A value and its stringification collide.** Object keys stringify, so a
-  universe that mixes a member with the string it stringifies to — `1 | "1"`,
-  `true | "true"`, `null | "null"` — collapses to a single handler key and both
-  members are routed to it. Use one form or the other.
+- **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.

backlog.tasks

@@ -6,17 +6,6 @@ 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
@@ -24,48 +13,14 @@ v1.0:
     ☐ 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/primitive-union.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 a literal union widened with `(string & {})` — `"red" | "green" | "yellow" | (string & {})` @medium
-    → autocomplete should still offer the literals; arbitrary strings stay assignable and fall through to the fallback
-
 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 @done
-    → rejected by an F-bounded constraint on `Handled` (checked *after* inference); a conditional in the fallback parameter is evaluated too early and breaks contextual typing
-✔ Implement matcher with similar API like matcher from primitive.ts @high @done
-    → `getTaggedUnionMatcher` / `getTaggedUnionMatcherW`, curried on the discriminant key
-    → fallback is the second argument; `_` removed
-☐ Rename `primitive` to `primitive-union` and `getMatcher` to `getPrimitiveMatcher` @medium
-    → `src/primitive.ts` / `src/primitive.test.ts` → `primitive-union.*`
-    → `getMatcherW` → `getPrimitiveMatcherW` for symmetry with the tagged-union pair
-    → update `src/index.ts`, `development/library.md` and any README references
-
-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 @done
-    ✔ Are there other primitive types that should be supported in union patterns? (e.g. `bigint`, `symbol`) @medium @done
-        → added boolean, null and undefined; rejected `symbol` (compile-time brand, nothing at runtime) and `bigint` (not a property key)
-☐ Allow boolean, null and undefined discriminant values in tagged-union patterns @medium
-    → needs the primitive matcher's `PatternKey` / `PatternParam` projection; see development/library.md § Tagged-union matcher
+✔ 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
@@ -75,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

cspell.json

@@ -43,7 +43,9 @@
         "silverwind",
         "idris",
         "todotasks",
-        "connor"
+        "connor",
+        "injective",
+        "injectivity"
     ],
     "ignorePaths": ["dist", "node_modules", "coverage", "*.svg", ".gitignore"]
 }

development/library.md

@@ -3,8 +3,8 @@
 The type-level design of the public API and the limitations it carries. The
 user-facing reference is [README § API](../README.md#api).
 
-The matchers are implemented in `src/primitive.ts` (`getMatcher` /
-`getMatcherW`) and `src/tagged-union.ts` (`getTaggedUnionMatcher` /
+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.
 
@@ -16,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
@@ -25,8 +25,8 @@ 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:
 
@@ -97,28 +97,98 @@ Each factory is two overloads whose order is load-bearing:
 
 #### Decision (2026-09)
 
-`src/matcher-shared.ts` holds the four universe-agnostic pieces both matchers
-use: `UnaryFn`, `PatternReturns`, `RedundantFallback`, `HandlerMap`.
+`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 three appear verbatim
-  in both public signatures.
+  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
-  (`PatternKey`/`PatternParam` vs `Tags`/`MapTaggedUnion`); abstracting over the
+  (`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.
+  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.
+- **`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 pair
+`getTaggedUnionMatcher` / `getTaggedUnionMatcherW` mirror the primitive-union pair
 with one extra curried step for the discriminant key:
 
 ```ts
@@ -142,25 +212,41 @@ The key is a separate call because `K` is inferred from its literal argument and
 
 #### Why
 
-- **Same fallback/remainder machinery as the primitive matcher.** `HandledMembers`
-  maps the handled tags to their members and `Exclude<T, …>` 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.
+- **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 dispatch's `shape as string | number`.
-- **`MapTaggedUnion` distributes with `Extract`.** A duplicated tag yields a
-  union of members instead of dropping 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
 
-- Tags are `string | number` only. A `boolean` / `null` / `undefined`
-  discriminant (`{ ok: true } | { ok: false }`) is rejected by `Discriminated`,
-  because those values are not property keys; supporting them needs the
-  primitive matcher's `PatternKey` / `PatternParam` projection.
 - A member's tag must be unique across the union; two members with the same tag
-  collapse to a union under one handler.
+  collapse to a union under one handler. A tag colliding with its
+  stringification (`true | "true"`) is rejected by the universe gate — see
+  § Supported universes.
 
 ## Primitive universe
 
@@ -170,9 +256,12 @@ 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 `PatternParam` inverts
-it, so callbacks receive the real member (`true`, not `"true"`). The popup
-offers `true`, `false`, `null`, `undefined` by name (verified over LSP).
+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
 
@@ -182,5 +271,5 @@ offers `true`, `false`, `null`, `undefined` by name (verified over LSP).
   `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 unguarded: user-facing, stated once in
+  stringification is rejected by the gate: user-facing, stated once in
   [README § Caveats](../README.md#caveats).

development/testing.md

@@ -28,7 +28,7 @@ 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
@@ -167,7 +167,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
@@ -198,6 +198,11 @@ 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
 

development/tooling.md

@@ -107,7 +107,7 @@ Type-aware oxlint is enabled via `options.typeAware: true` in `.oxlintrc.json`
 #### Decision (2026-09)
 
 A type-aware rule that false-positives **at one site** is silenced with a
-source-level `oxlint-disable` directive (see `src/primitive.ts`). A rule that is
+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
@@ -196,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)

knip.json

@@ -1,5 +1,5 @@
 {
     "$schema": "./node_modules/knip/schema.json",
-    "entry": ["scripts/*.ts"],
+    "entry": ["src/index.ts", "scripts/*.ts"],
     "ignoreDependencies": ["@runwisp/pubv"]
 }

package.json

@@ -1,6 +1,6 @@
 {
     "name": "tiny-pattern-ts",
-    "version": "0.5.0",
+    "version": "0.8.0",
     "description": "Pattern matching for TypeScript/ESM environments (F#-style, not regex)",
     "keywords": [
         "adt",
@@ -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",

src/index.ts

@@ -1,4 +1,7 @@
-export { getMatcher, getMatcherW } from "./primitive.ts";
+export {
+    getPrimitiveUnionMatcher,
+    getPrimitiveUnionMatcherW,
+} from "./primitive-union.ts";
 export {
     getTaggedUnionMatcher,
     getTaggedUnionMatcherW,

src/matcher-shared.ts

@@ -1,6 +1,6 @@
-import type { ValueOf } from "type-fest";
+import type { IsLiteral, IsNever, ValueOf } from "type-fest";
 
-// The primitive and tagged-union matchers differ in their universe, but the
+// 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.
@@ -8,6 +8,79 @@ import type { ValueOf } from "type-fest";
 // 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<

src/primitive-union.test.ts

@@ -9,15 +9,18 @@ import {
     LspSession,
 } from "#test-utils/lsp-completion.ts";
 
-import { getMatcher, getMatcherW } from "./primitive.ts";
+import {
+    getPrimitiveUnionMatcher,
+    getPrimitiveUnionMatcherW,
+} from "./primitive-union.ts";
 
 // ============================================================================
-// API: getMatcher — ✔️ Exhaustive / ✔️ ReturnsStrict
+// API: getPrimitiveUnionMatcher — ✔️ Exhaustive / ✔️ ReturnsStrict
 // ============================================================================
 
-test("getMatcher: exhaustive pattern infers one common return type", () => {
+test("getPrimitiveUnionMatcher: exhaustive pattern infers one common return type", () => {
     // Arrange
-    const factory = getMatcher<"a" | "b">();
+    const factory = getPrimitiveUnionMatcher<"a" | "b">();
 
     // Act
     const matcher = factory({
@@ -42,9 +45,9 @@ test("getMatcher: exhaustive pattern infers one common return type", () => {
     assert.equal(matcher("b"), 2);
 });
 
-test("getMatcher: dispatches on numeric literal keys", () => {
+test("getPrimitiveUnionMatcher: dispatches on numeric literal keys", () => {
     // Arrange
-    const factory = getMatcher<1 | 2>();
+    const factory = getPrimitiveUnionMatcher<1 | 2>();
 
     // Act
     const matcher = factory({
@@ -67,9 +70,9 @@ test("getMatcher: dispatches on numeric literal keys", () => {
     assert.equal(matcher(2), 20);
 });
 
-test("getMatcher: dispatches on mixed string and numeric keys", () => {
+test("getPrimitiveUnionMatcher: dispatches on mixed string and numeric keys", () => {
     // Arrange
-    const factory = getMatcher<"a" | "b" | 1 | 2>();
+    const factory = getPrimitiveUnionMatcher<"a" | "b" | 1 | 2>();
 
     // Act
     const matcher = factory({
@@ -103,9 +106,9 @@ test("getMatcher: dispatches on mixed string and numeric keys", () => {
     assert.equal(matcher(2), 20);
 });
 
-test("getMatcher: dispatches on boolean literals", () => {
+test("getPrimitiveUnionMatcher: dispatches on boolean literals", () => {
     // Arrange
-    const factory = getMatcher<boolean>();
+    const factory = getPrimitiveUnionMatcher<boolean>();
 
     // Act
     const matcher = factory({
@@ -129,9 +132,9 @@ test("getMatcher: dispatches on boolean literals", () => {
     assert.equal(matcher(false), 2);
 });
 
-test("getMatcher: dispatches on null and undefined", () => {
+test("getPrimitiveUnionMatcher: dispatches on null and undefined", () => {
     // Arrange
-    const factory = getMatcher<null | undefined>();
+    const factory = getPrimitiveUnionMatcher<null | undefined>();
 
     // Act
     const matcher = factory({
@@ -154,12 +157,12 @@ test("getMatcher: dispatches on null and undefined", () => {
 });
 
 // ============================================================================
-// API: getMatcher — ❌ Exhaustive (fallback) / ✔️ ReturnsStrict
+// API: getPrimitiveUnionMatcher — ❌ Exhaustive (fallback) / ✔️ ReturnsStrict
 // ============================================================================
 
-test("getMatcher: a `_` fallback receives the unhandled keys", () => {
+test("getPrimitiveUnionMatcher: a `_` fallback receives the unhandled keys", () => {
     // Arrange
-    const factory = getMatcher<"a" | "b" | "c">();
+    const factory = getPrimitiveUnionMatcher<"a" | "b" | "c">();
 
     // Act
     const matcher = factory(
@@ -187,9 +190,9 @@ test("getMatcher: a `_` fallback receives the unhandled keys", () => {
     assert.equal(matcher("c"), 2);
 });
 
-test("getMatcher: a `_` fallback routes mixed string and numeric gaps", () => {
+test("getPrimitiveUnionMatcher: a `_` fallback routes mixed string and numeric gaps", () => {
     // Arrange
-    const factory = getMatcher<"a" | "b" | 1 | 2>();
+    const factory = getPrimitiveUnionMatcher<"a" | "b" | 1 | 2>();
 
     // Act
     const matcher = factory(
@@ -222,9 +225,11 @@ test("getMatcher: a `_` fallback routes mixed string and numeric gaps", () => {
     assert.equal(matcher(2), "fallback");
 });
 
-test("getMatcher: a `_` fallback receives unhandled boolean and nullish keys", () => {
+test("getPrimitiveUnionMatcher: a `_` fallback receives unhandled boolean and nullish keys", () => {
     // Arrange
-    const factory = getMatcher<"a" | true | false | null | undefined>();
+    const factory = getPrimitiveUnionMatcher<
+        "a" | true | false | null | undefined
+    >();
 
     // Act
     const matcher = factory(
@@ -261,12 +266,12 @@ test("getMatcher: a `_` fallback receives unhandled boolean and nullish keys", (
 });
 
 // ============================================================================
-// API: getMatcherW — ✔️ Exhaustive / ❌ ReturnsStrict
+// API: getPrimitiveUnionMatcherW — ✔️ Exhaustive / ❌ ReturnsStrict
 // ============================================================================
 
-test("getMatcherW: exhaustive pattern widens to the union of handler returns", () => {
+test("getPrimitiveUnionMatcherW: exhaustive pattern widens to the union of handler returns", () => {
     // Arrange
-    const factory = getMatcherW<"x" | "y">();
+    const factory = getPrimitiveUnionMatcherW<"x" | "y">();
 
     // Act
     const matcher = factory({
@@ -291,9 +296,9 @@ test("getMatcherW: exhaustive pattern widens to the union of handler returns", (
     assert.equal(matcher("y"), "two");
 });
 
-test("getMatcherW: dispatches on mixed string and numeric keys", () => {
+test("getPrimitiveUnionMatcherW: dispatches on mixed string and numeric keys", () => {
     // Arrange
-    const factory = getMatcherW<"a" | "b" | 1 | 2>();
+    const factory = getPrimitiveUnionMatcherW<"a" | "b" | 1 | 2>();
 
     // Act
     const matcher = factory({
@@ -329,9 +334,9 @@ test("getMatcherW: dispatches on mixed string and numeric keys", () => {
     assert.equal(matcher(2), 20);
 });
 
-test("getMatcherW: exhaustive boolean and nullish widen to the union", () => {
+test("getPrimitiveUnionMatcherW: exhaustive boolean and nullish widen to the union", () => {
     // Arrange
-    const factory = getMatcherW<boolean | null | undefined>();
+    const factory = getPrimitiveUnionMatcherW<boolean | null | undefined>();
 
     // Act
     const matcher = factory({
@@ -368,12 +373,12 @@ test("getMatcherW: exhaustive boolean and nullish widen to the union", () => {
 });
 
 // ============================================================================
-// API: getMatcherW — ❌ Exhaustive (fallback) / ❌ ReturnsStrict
+// API: getPrimitiveUnionMatcherW — ❌ Exhaustive (fallback) / ❌ ReturnsStrict
 // ============================================================================
 
-test("getMatcherW: a `_` fallback widens gaps into the union", () => {
+test("getPrimitiveUnionMatcherW: a `_` fallback widens gaps into the union", () => {
     // Arrange
-    const factory = getMatcherW<"x" | "y" | "z">();
+    const factory = getPrimitiveUnionMatcherW<"x" | "y" | "z">();
 
     // Act
     const matcher = factory(
@@ -404,9 +409,9 @@ test("getMatcherW: a `_` fallback widens gaps into the union", () => {
     assert.equal(matcher("z"), "z");
 });
 
-test("getMatcherW: a `_` fallback widens mixed string and numeric returns", () => {
+test("getPrimitiveUnionMatcherW: a `_` fallback widens mixed string and numeric returns", () => {
     // Arrange
-    const factory = getMatcherW<"a" | "b" | 1 | 2>();
+    const factory = getPrimitiveUnionMatcherW<"a" | "b" | 1 | 2>();
 
     // Act
     const matcher = factory(
@@ -447,9 +452,9 @@ test("getMatcherW: a `_` fallback widens mixed string and numeric returns", () =
 // Factory contracts — calls that must not compile
 // ============================================================================
 
-test("getMatcher factory rejects patterns outside its contract", () => {
+test("getPrimitiveUnionMatcher factory rejects patterns outside its contract", () => {
     // Arrange
-    const factory = getMatcher<"a" | "b">();
+    const factory = getPrimitiveUnionMatcher<"a" | "b">();
 
     // Act / Assert — the calls below must not compile.
     // `Parameters<typeof factory>[0]` resolves only the *last* overload, so it
@@ -469,9 +474,9 @@ test("getMatcher factory rejects patterns outside its contract", () => {
     factory({ a: () => 1, b: () => 2 }, () => 0);
 });
 
-test("getMatcher factory rejects non-exhaustive boolean and nullish maps", () => {
+test("getPrimitiveUnionMatcher factory rejects non-exhaustive boolean and nullish maps", () => {
     // Arrange
-    const factory = getMatcher<boolean | null | undefined>();
+    const factory = getPrimitiveUnionMatcher<boolean | null | undefined>();
 
     // Act / Assert — the calls below must not compile
     // @ts-expect-error only `true` is handled; `false`, `null`, `undefined` are not
@@ -490,31 +495,399 @@ test("getMatcher factory rejects non-exhaustive boolean and nullish maps", () =>
     );
 });
 
-test("getMatcher: an open universe keeps the fallback's remainder open", () => {
+test("getPrimitiveUnionMatcher: a standalone stringified literal is typed by the member, not its key", () => {
+    // `"true"` is a string member whose `PatternKey` is `"true"`; inverting the
+    // key must recover the string, not the boolean that also stringifies to it.
     // Arrange
-    const factory = getMatcher<string>();
+    const factory = getPrimitiveUnionMatcher<"true" | "1">();
 
     // Act
-    const matcher = factory({ a: () => 1 }, (s) => {
-        // The map's literal keys do not close an open universe, so the
-        // remainder stays `string` and the fallback is not redundant.
-        expectTypeOf(s).toEqualTypeOf<string>();
-        // A strict pattern fixes one `R` for every handler, so this fallback
-        // cannot return its shape; `typeof` is the strongest claim the value
-        // makes on its own — any string passes, including `""`.
-        assert.equal(typeof s, "string");
-        return 2 as const;
+    const matcher = factory({
+        true: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"true">();
+            assert.equal(s, "true");
+            return 1;
+        },
+        "1": (s) => {
+            expectTypeOf(s).toEqualTypeOf<"1">();
+            assert.equal(s, "1");
+            return 2;
+        },
     });
 
     // Assert
-    expectTypeOf(matcher).toEqualTypeOf<(shape: string) => number>();
-    assert.equal(matcher("a"), 1);
-    assert.equal(matcher("b"), 2);
+    assert.equal(matcher("true"), 1);
+    assert.equal(matcher("1"), 2);
 });
 
-test("getMatcherW factory rejects patterns outside its contract", () => {
+test("getPrimitiveUnionMatcher: a broad universe is rejected", () => {
+    // Act / Assert — the calls below must not compile
+    // @ts-expect-error `string` is not a finite union of literals
+    getPrimitiveUnionMatcher<string>()({ a: () => 1 });
+    // @ts-expect-error `number` is not a finite union of literals
+    getPrimitiveUnionMatcher<number>()({ 1: () => 1 });
+    // @ts-expect-error a template literal is open
+    getPrimitiveUnionMatcher<`a${string}`>()({ a: () => 1 });
+    // @ts-expect-error a literal mixed with a template literal is open
+    getPrimitiveUnionMatcher<"a" | `x-${number}`>()({ a: () => 1 });
+    // @ts-expect-error `string | boolean` is open because of `string`
+    getPrimitiveUnionMatcher<string | boolean>()({ true: () => 1 });
+    // @ts-expect-error the widening factory rejects broad universes too
+    getPrimitiveUnionMatcherW<string>()({ a: () => 1 });
+});
+
+test("getPrimitiveUnionMatcher: a value/stringification collision is rejected", () => {
+    // Act / Assert — the calls below must not compile
+    // @ts-expect-error `true` collides with the string `"true"`
+    getPrimitiveUnionMatcher<"true" | true>()({ true: () => 1 });
+    // @ts-expect-error `false` collides with the string `"false"`
+    getPrimitiveUnionMatcher<"false" | false>()({ false: () => 1 });
+    // @ts-expect-error `null` collides with the string `"null"`
+    getPrimitiveUnionMatcher<"null" | null>()({ null: () => 1 });
+    // @ts-expect-error `undefined` collides with the string `"undefined"`
+    getPrimitiveUnionMatcher<"undefined" | undefined>()({
+        undefined: () => 1,
+    });
+    // @ts-expect-error the number `1` collides with the string `"1"`
+    getPrimitiveUnionMatcher<1 | "1">()({ 1: () => 1 });
+});
+
+test("getPrimitiveUnionMatcher: a collision is rejected beside legal members", () => {
+    // Act / Assert — the calls below must not compile; the legal members do not
+    // mask the collision. Each map is otherwise complete, so only the collision
+    // can make it invalid.
+    // @ts-expect-error `true` collides with `"true"` beside legal members
+    getPrimitiveUnionMatcher<"true" | true | "a" | 2>()({
+        true: () => 1,
+        a: () => 2,
+        2: () => 3,
+    });
+    // @ts-expect-error `false` collides with `"false"` beside legal members
+    getPrimitiveUnionMatcher<"false" | false | "a" | 2>()({
+        false: () => 1,
+        a: () => 2,
+        2: () => 3,
+    });
+    // @ts-expect-error `null` collides with `"null"` beside legal members
+    getPrimitiveUnionMatcher<"null" | null | "a" | 2>()({
+        null: () => 1,
+        a: () => 2,
+        2: () => 3,
+    });
+    // @ts-expect-error `undefined` collides with `"undefined"` beside legal members
+    getPrimitiveUnionMatcher<"undefined" | undefined | "a" | 2>()({
+        undefined: () => 1,
+        a: () => 2,
+        2: () => 3,
+    });
+    // @ts-expect-error `1` collides with `"1"` beside legal members
+    getPrimitiveUnionMatcher<1 | "1" | "a" | true>()({
+        1: () => 1,
+        a: () => 2,
+        true: () => 3,
+    });
+});
+
+test('getPrimitiveUnionMatcher: `"true"` and a bare `false` are legal together', () => {
+    // Arrange — `false` stringifies to `"false"`, so it does not collide with
+    // the string member `"true"`.
+    const factory = getPrimitiveUnionMatcher<"true" | false | "a" | 2>();
+
+    // Act
+    const matcher = factory({
+        true: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"true">();
+            assert.equal(s, "true");
+            return 1;
+        },
+        false: (s) => {
+            expectTypeOf(s).toEqualTypeOf<false>();
+            assert.equal(s, false);
+            return 2;
+        },
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            assert.equal(s, "a");
+            return 3;
+        },
+        2: (s) => {
+            expectTypeOf(s).toEqualTypeOf<2>();
+            assert.equal(s, 2);
+            return 4;
+        },
+    });
+
+    // Assert
+    assert.equal(matcher("true"), 1);
+    assert.equal(matcher(false), 2);
+    assert.equal(matcher("a"), 3);
+    assert.equal(matcher(2), 4);
+});
+
+test('getPrimitiveUnionMatcher: `"false"` and a bare `true` are legal together', () => {
+    // Arrange — `true` stringifies to `"true"`, not `"false"`.
+    const factory = getPrimitiveUnionMatcher<"false" | true | "a" | 2>();
+
+    // Act
+    const matcher = factory({
+        false: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"false">();
+            assert.equal(s, "false");
+            return 1;
+        },
+        true: (s) => {
+            expectTypeOf(s).toEqualTypeOf<true>();
+            assert.equal(s, true);
+            return 2;
+        },
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            assert.equal(s, "a");
+            return 3;
+        },
+        2: (s) => {
+            expectTypeOf(s).toEqualTypeOf<2>();
+            assert.equal(s, 2);
+            return 4;
+        },
+    });
+
+    // Assert
+    assert.equal(matcher("false"), 1);
+    assert.equal(matcher(true), 2);
+    assert.equal(matcher("a"), 3);
+    assert.equal(matcher(2), 4);
+});
+
+test('getPrimitiveUnionMatcher: `"null"` and a bare `undefined` are legal together', () => {
+    // Arrange — `undefined` stringifies to `"undefined"`, not `"null"`.
+    const factory = getPrimitiveUnionMatcher<"null" | undefined | "a" | 2>();
+
+    // Act
+    const matcher = factory({
+        null: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"null">();
+            assert.equal(s, "null");
+            return 1;
+        },
+        undefined: (s) => {
+            expectTypeOf(s).toEqualTypeOf<undefined>();
+            assert.equal(s, undefined);
+            return 2;
+        },
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            assert.equal(s, "a");
+            return 3;
+        },
+        2: (s) => {
+            expectTypeOf(s).toEqualTypeOf<2>();
+            assert.equal(s, 2);
+            return 4;
+        },
+    });
+
+    // Assert
+    assert.equal(matcher("null"), 1);
+    assert.equal(matcher(undefined), 2);
+    assert.equal(matcher("a"), 3);
+    assert.equal(matcher(2), 4);
+});
+
+test('getPrimitiveUnionMatcher: `"undefined"` and a bare `null` are legal together', () => {
+    // Arrange — `null` stringifies to `"null"`, not `"undefined"`.
+    const factory = getPrimitiveUnionMatcher<"undefined" | null | "a" | 2>();
+
+    // Act
+    const matcher = factory({
+        undefined: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"undefined">();
+            assert.equal(s, "undefined");
+            return 1;
+        },
+        null: (s) => {
+            expectTypeOf(s).toEqualTypeOf<null>();
+            assert.equal(s, null);
+            return 2;
+        },
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            assert.equal(s, "a");
+            return 3;
+        },
+        2: (s) => {
+            expectTypeOf(s).toEqualTypeOf<2>();
+            assert.equal(s, 2);
+            return 4;
+        },
+    });
+
+    // Assert
+    assert.equal(matcher("undefined"), 1);
+    assert.equal(matcher(null), 2);
+    assert.equal(matcher("a"), 3);
+    assert.equal(matcher(2), 4);
+});
+
+test('getPrimitiveUnionMatcher: `"1"` beside other numbers and strings is legal', () => {
+    // Arrange — the task's example: `"1"` is the string member, `2` and `3`
+    // are bare numbers, `"4"` is another string. No stringification lands on
+    // another member.
+    const factory = getPrimitiveUnionMatcher<"1" | 2 | 3 | "4">();
+
+    // Act
+    const matcher = factory({
+        "1": (s) => {
+            expectTypeOf(s).toEqualTypeOf<"1">();
+            assert.equal(s, "1");
+            return 1;
+        },
+        2: (s) => {
+            expectTypeOf(s).toEqualTypeOf<2>();
+            assert.equal(s, 2);
+            return 2;
+        },
+        3: (s) => {
+            expectTypeOf(s).toEqualTypeOf<3>();
+            assert.equal(s, 3);
+            return 3;
+        },
+        "4": (s) => {
+            expectTypeOf(s).toEqualTypeOf<"4">();
+            assert.equal(s, "4");
+            return 4;
+        },
+    });
+
+    // Assert
+    assert.equal(matcher("1"), 1);
+    assert.equal(matcher(2), 2);
+    assert.equal(matcher(3), 3);
+    assert.equal(matcher("4"), 4);
+});
+
+// The maximum legal universe needs one handler per member; the statement count
+// is inherent to the case.
+// oxlint-disable-next-line max-statements
+test("getPrimitiveUnionMatcher: the maximum legal universe is supported", () => {
+    // Arrange — every Matchable kind, one representation per value, plus extra
+    // literals. No member's stringification is another member.
+    type Legal =
+        | "true"
+        | false
+        | null
+        | undefined
+        | "1"
+        | 2
+        | 3
+        | "a"
+        | "b"
+        | "4";
+    const factory = getPrimitiveUnionMatcher<Legal>();
+
+    // Act
+    const matcher = factory({
+        true: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"true">();
+            assert.equal(s, "true");
+            return 1;
+        },
+        false: (s) => {
+            expectTypeOf(s).toEqualTypeOf<false>();
+            assert.equal(s, false);
+            return 2;
+        },
+        null: (s) => {
+            expectTypeOf(s).toEqualTypeOf<null>();
+            assert.equal(s, null);
+            return 3;
+        },
+        undefined: (s) => {
+            expectTypeOf(s).toEqualTypeOf<undefined>();
+            assert.equal(s, undefined);
+            return 4;
+        },
+        "1": (s) => {
+            expectTypeOf(s).toEqualTypeOf<"1">();
+            assert.equal(s, "1");
+            return 5;
+        },
+        2: (s) => {
+            expectTypeOf(s).toEqualTypeOf<2>();
+            assert.equal(s, 2);
+            return 6;
+        },
+        3: (s) => {
+            expectTypeOf(s).toEqualTypeOf<3>();
+            assert.equal(s, 3);
+            return 7;
+        },
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            assert.equal(s, "a");
+            return 8;
+        },
+        b: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"b">();
+            assert.equal(s, "b");
+            return 9;
+        },
+        "4": (s) => {
+            expectTypeOf(s).toEqualTypeOf<"4">();
+            assert.equal(s, "4");
+            return 10;
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<(shape: Legal) => number>();
+    assert.equal(matcher("true"), 1);
+    assert.equal(matcher(false), 2);
+    assert.equal(matcher(null), 3);
+    assert.equal(matcher(undefined), 4);
+    assert.equal(matcher("1"), 5);
+    assert.equal(matcher(2), 6);
+    assert.equal(matcher(3), 7);
+    assert.equal(matcher("a"), 8);
+    assert.equal(matcher("b"), 9);
+    assert.equal(matcher("4"), 10);
+});
+
+test("getPrimitiveUnionMatcher: the maximum illegal universe is rejected", () => {
+    // Arrange — every value paired with its stringification.
+    type Illegal =
+        | "true"
+        | true
+        | "false"
+        | false
+        | "null"
+        | null
+        | "undefined"
+        | undefined
+        | "1"
+        | 1;
+
+    // Act / Assert — the call below must not compile
+    // @ts-expect-error every value collides with its stringification
+    getPrimitiveUnionMatcher<Illegal>()({
+        true: () => 1,
+        false: () => 2,
+        null: () => 3,
+        undefined: () => 4,
+        "1": () => 5,
+    });
+});
+
+test("getPrimitiveUnionMatcher: an open universe is rejected with a fallback too", () => {
+    // Act / Assert — the call below must not compile; a broad universe is
+    // unsupported whether or not a fallback is supplied.
+    // @ts-expect-error `string` is not a finite union of literals
+    getPrimitiveUnionMatcher<string>()({ a: () => 1 }, () => 2);
+});
+
+test("getPrimitiveUnionMatcherW factory rejects patterns outside its contract", () => {
     // Arrange
-    const factory = getMatcherW<"x" | "y">();
+    const factory = getPrimitiveUnionMatcherW<"x" | "y">();
 
     // Act / Assert — the calls below must not compile
     factory({
@@ -533,35 +906,28 @@ test("getMatcherW factory rejects patterns outside its contract", () => {
 // 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, (shape: unknown) => number> = {
-        a: (shape) => {
-            // The raw shape reaches the handler, not the property key's text.
-            assert.equal(shape, "a");
-            return 1;
-        },
-    };
-    const matcher = getMatcher<string>()(handlers);
+test("getPrimitiveUnionMatcher: an unhandled shape throws without a fallback", () => {
+    // Arrange — a finite universe is exhaustive through the typed API, so the
+    // defensive throw is reachable only by widening the factory and dropping a
+    // handler.
+    const bypass: Function = getPrimitiveUnionMatcher<"a" | "b">();
+    const matcher: (shape: "a" | "b") => number = bypass({ a: () => 1 });
 
     // Act / Assert
     assert.equal(matcher("a"), 1);
     assert.throws(() => matcher("b"), /Unhandled shape: b/);
 });
 
-test("getMatcher: an unhandled boolean shape throws without a fallback", () => {
-    // Arrange — an `string | boolean` universe widens its handler map to an
-    // index signature, so the runtime map's exhaustiveness is not provable.
-    const handlers: Record<string, (shape: unknown) => number> = {
-        true: (shape) => {
-            // `true` indexes the map as the property `"true"`, but the handler
-            // is still called with the boolean.
+test("getPrimitiveUnionMatcher: an unhandled boolean shape throws without a fallback", () => {
+    // Arrange — as above; `true` indexes the map as the property `"true"`, but
+    // the handler is still called with the boolean.
+    const bypass: Function = getPrimitiveUnionMatcher<true | false>();
+    const matcher: (shape: boolean) => number = bypass({
+        true: (shape: boolean) => {
             assert.equal(shape, true);
             return 1;
         },
-    };
-    const matcher = getMatcher<string | boolean>()(handlers);
+    });
 
     // Act / Assert
     assert.equal(matcher(true), 1);
@@ -584,7 +950,7 @@ const UNIVERSE = `"a" | "b" | "c"`;
 // documents, project membership), so they pass in any order.
 interface LabelsProbe {
     readonly name: string;
-    readonly factory: "getMatcher" | "getMatcherW";
+    readonly factory: "getPrimitiveUnionMatcher" | "getPrimitiveUnionMatcherW";
     readonly body: string;
     readonly universe?: string;
     readonly tail?: string;
@@ -616,12 +982,12 @@ const labelsFor = ({
 
 test("autocomplete: an exhaustive pattern requires the universe", () => {
     // Arrange
-    const name = "getMatcher_fresh";
+    const name = "getPrimitiveUnionMatcher_fresh";
 
     // Act
     const labels = labelsFor({
         name,
-        factory: "getMatcher",
+        factory: "getPrimitiveUnionMatcher",
         body: "    /*COMPLETE*/",
     });
 
@@ -633,12 +999,12 @@ test("autocomplete: an exhaustive pattern requires the universe", () => {
 
 test("autocomplete: handled keys drop out of the popup", () => {
     // Arrange
-    const name = "getMatcher_after_key";
+    const name = "getPrimitiveUnionMatcher_after_key";
 
     // Act
     const labels = labelsFor({
         name,
-        factory: "getMatcher",
+        factory: "getPrimitiveUnionMatcher",
         body: "    a: () => 1,\n    /*COMPLETE*/",
     });
 
@@ -650,12 +1016,12 @@ test("autocomplete: handled keys drop out of the popup", () => {
 
 test("autocomplete: a fallback makes the remaining keys optional", () => {
     // Arrange
-    const name = "getMatcher_with_fallback";
+    const name = "getPrimitiveUnionMatcher_with_fallback";
 
     // Act
     const labels = labelsFor({
         name,
-        factory: "getMatcher",
+        factory: "getPrimitiveUnionMatcher",
         body: "    /*COMPLETE*/",
         tail: ", () => 0",
     });
@@ -668,12 +1034,12 @@ test("autocomplete: a fallback makes the remaining keys optional", () => {
 
 test("autocomplete: with a fallback, handled keys stay optional", () => {
     // Arrange
-    const name = "getMatcher_with_fallback_after_key";
+    const name = "getPrimitiveUnionMatcher_with_fallback_after_key";
 
     // Act
     const labels = labelsFor({
         name,
-        factory: "getMatcher",
+        factory: "getPrimitiveUnionMatcher",
         body: "    a: () => 1,\n    /*COMPLETE*/",
         tail: ", () => 0",
     });
@@ -684,14 +1050,14 @@ test("autocomplete: with a fallback, handled keys stay optional", () => {
     });
 });
 
-test("autocomplete: `getMatcherW` offers the same popup as `getMatcher`", () => {
+test("autocomplete: `getPrimitiveUnionMatcherW` offers the same popup as `getPrimitiveUnionMatcher`", () => {
     // Arrange
-    const name = "getMatcherW_fresh";
+    const name = "getPrimitiveUnionMatcherW_fresh";
 
     // Act
     const labels = labelsFor({
         name,
-        factory: "getMatcherW",
+        factory: "getPrimitiveUnionMatcherW",
         body: "    /*COMPLETE*/",
     });
 
@@ -701,14 +1067,14 @@ test("autocomplete: `getMatcherW` offers the same popup as `getMatcher`", () =>
     });
 });
 
-test("autocomplete: `getMatcherW` also offers optional keys with a fallback", () => {
+test("autocomplete: `getPrimitiveUnionMatcherW` also offers optional keys with a fallback", () => {
     // Arrange
-    const name = "getMatcherW_with_fallback";
+    const name = "getPrimitiveUnionMatcherW_with_fallback";
 
     // Act
     const labels = labelsFor({
         name,
-        factory: "getMatcherW",
+        factory: "getPrimitiveUnionMatcherW",
         body: "    /*COMPLETE*/",
         tail: ", () => 0",
     });
@@ -721,12 +1087,12 @@ test("autocomplete: `getMatcherW` also offers optional keys with a fallback", ()
 
 test("autocomplete: boolean and nullish keys are offered by name", () => {
     // Arrange
-    const name = "getMatcher_boolean_nullish";
+    const name = "getPrimitiveUnionMatcher_boolean_nullish";
 
     // Act
     const labels = labelsFor({
         name,
-        factory: "getMatcher",
+        factory: "getPrimitiveUnionMatcher",
         universe: "boolean | null | undefined",
         body: "    /*COMPLETE*/",
     });
@@ -739,12 +1105,12 @@ test("autocomplete: boolean and nullish keys are offered by name", () => {
 
 test("autocomplete: a handled boolean literal drops out of the popup", () => {
     // Arrange
-    const name = "getMatcher_boolean_after_key";
+    const name = "getPrimitiveUnionMatcher_boolean_after_key";
 
     // Act
     const labels = labelsFor({
         name,
-        factory: "getMatcher",
+        factory: "getPrimitiveUnionMatcher",
         universe: "boolean | null | undefined",
         body: "    true: () => 1,\n    /*COMPLETE*/",
     });

src/primitive-union.ts

@@ -2,50 +2,27 @@ import type { Exact } from "type-fest";
 
 import type {
     HandlerMap,
+    Matchable,
+    Member,
+    PatternKey,
     PatternReturns,
     RedundantFallback,
     UnaryFn,
+    UniverseGate,
 } from "./matcher-shared.ts";
 
-// The primitive universe a matcher can discriminate. `boolean` is admitted as
-// the pair `true | false`; see README § Caveats for the unsupported members.
-type Matchable = string | number | boolean | null | undefined;
-
-// `boolean`, `null` and `undefined` cannot be property keys, so a mapped type
-// over the universe keys each non-key member by its stringification. `Param`
-// inverts that projection, so a handler callback still receives the *real*
-// member (`true`, not `"true"`) — see README § Caveats for the limits.
-type PatternKey<T> = T extends boolean
-    ? T extends true
-        ? "true"
-        : "false"
-    : T extends null
-      ? "null"
-      : T extends undefined
-        ? "undefined"
-        : T;
-type PatternParam<K> = K extends "true"
-    ? true
-    : K extends "false"
-      ? false
-      : K extends "null"
-        ? null
-        : K extends "undefined"
-          ? undefined
-          : K;
-
 type Handlers<T extends Matchable, R> = {
-    [K in PatternKey<T>]: UnaryFn<PatternParam<K>, 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, keyof Handled>` and TypeScript
+// 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, PatternParam<keyof Handled>>,
+    Exclude<T, Member<T, keyof Handled>>,
     R
 >;
 
@@ -64,41 +41,37 @@ type MustBePartial<T extends Matchable, Handled> =
 // 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 Matchable> {
-    <R>(handlers: Handlers<T, R>): UnaryFn<T, R>;
+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>>,
-        fallback: Fallback<T, Handled, R>,
+        handlers: Handled & Partial<Handlers<T, R>> & UniverseGate<T>,
+        fallback: Fallback<T, Handled, R> & UniverseGate<T>,
     ): UnaryFn<T, R>;
 }
-// oxlint-enable typescript/unified-signatures
 
 // Widened returns: the union of every handler's return type. `P` is inferred
 // from the whole handler map, whose closed constraint supplies the
 // contextual/autocomplete type.
-// oxlint-disable typescript/unified-signatures
-interface MatcherWidening<T extends Matchable> {
+interface PrimitiveUnionMatcherWidening<T extends Matchable> {
     <P extends Exact<Handlers<T, unknown>, P>>(
-        handlers: P,
+        handlers: P & UniverseGate<T>,
     ): UnaryFn<T, PatternReturns<P>>;
     <
         R,
         Handled extends Exact<Partial<Handlers<T, unknown>>, Handled> &
             MustBePartial<T, Handled>,
     >(
-        handlers: Handled,
-        fallback: Fallback<T, Handled, R>,
+        handlers: Handled & UniverseGate<T>,
+        fallback: Fallback<T, Handled, R> & UniverseGate<T>,
     ): UnaryFn<T, PatternReturns<Handled> | R>;
 }
-// oxlint-enable typescript/unified-signatures
 
 const dispatch =
     (handlers: HandlerMap, fallback?: UnaryFn<never, unknown>) =>
@@ -123,6 +96,9 @@ const dispatch =
             shape as never,
         );
 
-export const getMatcher = <T extends Matchable>(): MatcherStrict<T> => dispatch;
-export const getMatcherW = <T extends Matchable>(): MatcherWidening<T> =>
-    dispatch;
+export const getPrimitiveUnionMatcher = <
+    T extends Matchable,
+>(): PrimitiveUnionMatcherStrict<T> => dispatch;
+export const getPrimitiveUnionMatcherW = <
+    T extends Matchable,
+>(): PrimitiveUnionMatcherWidening<T> => dispatch;

src/tagged-union.ts

@@ -1,61 +1,85 @@
-import type { Exact, UnknownRecord } from "type-fest";
+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.
-// Only `string` and `number` tags can key a handler map: `symbol` has no
-// literal syntax to write a handler under, and `bigint` is not a property key.
-type Tag = string | number;
+// 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, so an open universe
-// keeps an open fallback.
-type Tags<T extends object, K extends keyof T> = Extract<T[K], Tag>;
+// 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 Tag ? K : never;
+    [K in keyof T]: T[K] extends Matchable ? K : never;
 }[keyof T];
 
-// The member(s) of `T` tagged `V`. `Extract` distributes over the union, so a
+// 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> = {
-    [V in Tags<T, K>]: Extract<T, Record<K, V>>;
+    [P in PatternKey<Tags<T, K>>]: Narrowed<T, K, Member<Tags<T, K>, P>>;
 };
 
 type Handlers<T extends object, K extends keyof T, R> = {
-    [V in Tags<T, K>]: UnaryFn<MapTaggedUnion<T, K>[V], R>;
+    [P in PatternKey<Tags<T, K>>]: UnaryFn<MapTaggedUnion<T, K>[P], R>;
 };
 
-// The members `Handled` covers. Mapping over `Tags` keeps every index within
-// `MapTaggedUnion`'s keys, and the conditional drops a stray key outside `T` so
-// it cannot widen the remainder. The remainder is `Exclude<T, …>`, mirroring
-// the primitive matcher's `Exclude<T, PatternParam<keyof Handled>>`.
-type HandledMembers<T extends object, K extends keyof T, Handled> = {
-    [V in Tags<T, K>]: V extends keyof Handled
-        ? MapTaggedUnion<T, K>[V]
-        : never;
-}[Tags<T, K>];
+// 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 open. See development/library.md.
+// 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<
-    Exclude<T, HandledMembers<T, K, Handled>>,
+    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 matcher for why a conditional in the fallback's
+// 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> =
-    Tags<T, K> extends keyof Handled ? RedundantFallback : unknown;
+    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.
@@ -64,14 +88,16 @@ type MustBePartial<T extends object, K extends keyof T, Handled> =
 //   #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>): UnaryFn<T, R>;
+    <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>>,
-        fallback: Fallback<T, K, Handled, R>,
+        handlers: Handled &
+            Partial<Handlers<T, K, R>> &
+            UniverseGate<Tags<T, K>>,
+        fallback: Fallback<T, K, Handled, R> & UniverseGate<Tags<T, K>>,
     ): UnaryFn<T, R>;
 }
 
@@ -80,25 +106,38 @@ interface TaggedUnionMatcherStrict<T extends object, K extends keyof T> {
 // contextual/autocomplete type.
 interface TaggedUnionMatcherWidening<T extends object, K extends keyof T> {
     <P extends Exact<Handlers<T, K, unknown>, P>>(
-        handlers: 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,
-        fallback: Fallback<T, K, Handled, R>,
+        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 `string | number` tags,
-        // so the result is narrowed to the map's key space.
+        // 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 (
@@ -113,12 +152,10 @@ const dispatch =
         );
     };
 
-export const getTaggedUnionMatcher =
-    <T extends object>() =>
-    <K extends Discriminated<T>>(k: K): TaggedUnionMatcherStrict<T, K> =>
-        dispatch(k);
+export const getTaggedUnionMatcher = <
+    T extends object,
+>(): TaggedUnionMatcherFactory<T> => dispatch;
 
-export const getTaggedUnionMatcherW =
-    <T extends object>() =>
-    <K extends Discriminated<T>>(k: K): TaggedUnionMatcherWidening<T, K> =>
-        dispatch(k);
+export const getTaggedUnionMatcherW = <
+    T extends object,
+>(): TaggedUnionMatcherWideningFactory<T> => dispatch;