🚀 Release 0.6.0

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.

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,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
@@ -68,7 +75,8 @@ 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.6.0...main
+[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)).

backlog.tasks

@@ -24,7 +24,7 @@ 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:
@@ -37,6 +37,12 @@ Testing:
     ✔ 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
+☐ Type hole when using broad types like string as a universe @high
+    ☐ handlers cannot be exhaustive, yet it is possible to not have a fallback
+    ☐ one test even exploits this, I think for a negative test
+    ☐ does the same type hole exist for tagged-union matchers or primitive-union matchers only?
 
 Matcher:
 ✔ Clean up: adopt the 3-overload matcher (`src/prototype-ac2.ts`) and delete the prototypes @high @done
@@ -46,6 +52,18 @@ Matcher:
     → 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 @done
+    → `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
+    → shipped as `getPrimitiveUnionMatcher` / `getPrimitiveUnionMatcherW`; kept `Union` for symmetry with the tagged-union pair
+☐ when using a union type as a property, the current behavior of tagged union matcher is
+    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
 
 Bugs:
 ✔ TS 7 LSP server logs `context canceled` on stderr at shutdown @done
@@ -55,6 +73,8 @@ 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 @done
+    → moved the `PatternKey` / `PatternParam` projection to `matcher-shared.ts` and keyed the tagged-union handler map through it; see development/library.md § Tagged-union matcher
 
 Documentation:
 ☐ Bring README.md back to its previous form — synopsis and examples restored, in the correct place

development/library.md

@@ -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
+The matchers are implemented in `src/primitive-union.ts` (`getPrimitiveUnionMatcher` /
-`src/index.ts` as `getMatcher` / `getMatcherW`; the rest of the library is
+`getPrimitiveUnionMatcherW`) and `src/tagged-union.ts` (`getTaggedUnionMatcher` /
-placeholder code.
+`getTaggedUnionMatcherW`), re-exported from `src/index.ts`; the rest of 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 matcher = getPrimitiveUnionMatcher<"a" | "b">()({ a: (s) => …, b: (s) => … });
-const fallback = getMatcher<"a" | "b" | "c">()({ a: (s) => … }, (s) => …);
+const fallback = getPrimitiveUnionMatcher<"a" | "b" | "c">()({ a: (s) => … }, (s) => …);
 ```
 
 Exhaustive or fallback is decided **at the call site**, by whether the second
@@ -24,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;
+- `getPrimitiveUnionMatcher` — one common `R`; the fallback must fit it;
-- `getMatcherW` — the union `PatternReturns<Handled> | R`.
+- `getPrimitiveUnionMatcherW` — the union `PatternReturns<Handled> | R`.
 
 Each factory is two overloads whose order is load-bearing:
 
@@ -92,6 +93,85 @@ Each factory is two overloads whose order is load-bearing:
   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 seven universe-agnostic pieces both matchers
+use: `UnaryFn`, `PatternReturns`, `RedundantFallback`, `HandlerMap`, the shared
+`Matchable` universe, and the `PatternKey` / `PatternParam` key projection.
+
+#### 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` and the `PatternKey` /
+  `PatternParam` projection are the pieces both universes genuinely share.
+
+## 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.** `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.
+- **`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`.
+- **`MapTaggedUnion` distributes with `Extract`.** A duplicated tag yields a
+  union of members instead of dropping one.
+- **A `boolean` / `null` / `undefined` tag goes through the shared
+  `PatternKey` / `PatternParam` 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 `PatternParam` inverts
+  it 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 member's tag must be unique across the union; two members with the same tag
+  collapse to a union under one handler. The same holds for a tag colliding with
+  its stringification (`true | "true"`) — see [README § Caveats](../README.md#caveats).
+
 ## Primitive universe
 
 #### Decision (2026-09)
@@ -102,7 +182,9 @@ 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).
+offers `true`, `false`, `null`, `undefined` by name (verified over LSP). The
+same projection is shared with the tagged-union matcher; see
+§ Tagged-union matcher.
 
 #### Why
 

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

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

package-lock.json

@@ -1,12 +1,12 @@
 {
     "name": "tiny-pattern-ts",
-    "version": "0.5.0",
+    "version": "0.6.0",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
             "name": "tiny-pattern-ts",
-            "version": "0.5.0",
+            "version": "0.6.0",
             "license": "MIT",
             "dependencies": {
                 "type-fest": "^5.9.0"

package.json

@@ -1,6 +1,6 @@
 {
     "name": "tiny-pattern-ts",
-    "version": "0.5.0",
+    "version": "0.6.0",
     "description": "Pattern matching for TypeScript/ESM environments (F#-style, not regex)",
     "keywords": [
         "adt",

src/index.ts

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

src/matcher-shared.ts

@@ -0,0 +1,60 @@
+import type { 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. `PatternParam` inverts that projection, 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;
+export type PatternParam<K> = K extends "true"
+    ? true
+    : K extends "false"
+      ? false
+      : K extends "null"
+        ? null
+        : K extends "undefined"
+          ? undefined
+          : K;
+
+// `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
+>;

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,9 +495,9 @@ test("getMatcher factory rejects non-exhaustive boolean and nullish maps", () =>
     );
 });
 
-test("getMatcher: an open universe keeps the fallback's remainder open", () => {
+test("getPrimitiveUnionMatcher: an open universe keeps the fallback's remainder open", () => {
     // Arrange
-    const factory = getMatcher<string>();
+    const factory = getPrimitiveUnionMatcher<string>();
 
     // Act
     const matcher = factory({ a: () => 1 }, (s) => {
@@ -512,9 +517,9 @@ test("getMatcher: an open universe keeps the fallback's remainder open", () => {
     assert.equal(matcher("b"), 2);
 });
 
-test("getMatcherW factory rejects patterns outside its contract", () => {
+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,7 +538,7 @@ test("getMatcherW factory rejects patterns outside its contract", () => {
 // Dispatch — runtime behavior
 // ============================================================================
 
-test("getMatcher: an unhandled shape throws without a fallback", () => {
+test("getPrimitiveUnionMatcher: 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> = {
@@ -543,14 +548,14 @@ test("getMatcher: an unhandled shape throws without a fallback", () => {
             return 1;
         },
     };
-    const matcher = getMatcher<string>()(handlers);
+    const matcher = getPrimitiveUnionMatcher<string>()(handlers);
 
     // Act / Assert
     assert.equal(matcher("a"), 1);
     assert.throws(() => matcher("b"), /Unhandled shape: b/);
 });
 
-test("getMatcher: an unhandled boolean shape throws without a fallback", () => {
+test("getPrimitiveUnionMatcher: 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> = {
@@ -561,7 +566,7 @@ test("getMatcher: an unhandled boolean shape throws without a fallback", () => {
             return 1;
         },
     };
-    const matcher = getMatcher<string | boolean>()(handlers);
+    const matcher = getPrimitiveUnionMatcher<string | boolean>()(handlers);
 
     // Act / Assert
     assert.equal(matcher(true), 1);
@@ -584,7 +589,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 +621,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 +638,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 +655,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 +673,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 +689,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 +706,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 +726,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 +744,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

@@ -1,39 +1,14 @@
-import type { Exact, ValueOf } from "type-fest";
+import type { Exact } from "type-fest";
 
-type UnaryFn<T, R> = (shape: T) => R;
+import type {
-
+    HandlerMap,
-// The primitive universe a matcher can discriminate. `boolean` is admitted as
+    Matchable,
-// the pair `true | false`; see README § Caveats for the unsupported members.
+    PatternKey,
-type Matchable = string | number | boolean | null | undefined;
+    PatternParam,
-
+    PatternReturns,
-// `boolean`, `null` and `undefined` cannot be property keys, so a mapped type
+    RedundantFallback,
-// over the universe keys each non-key member by its stringification. `Param`
+    UnaryFn,
-// inverts that projection, so a handler callback still receives the *real*
+} from "./matcher-shared.ts";
-// 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;
-
-// `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 Matchable, R> = {
     [K in PatternKey<T>]: UnaryFn<PatternParam<K>, R>;
@@ -58,9 +33,6 @@ type Fallback<T extends Matchable, Handled, R> = UnaryFn<
 // 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.
-interface RedundantFallback {
-    readonly "every case is already handled, so the fallback is redundant": never;
-}
 type MustBePartial<T extends Matchable, Handled> =
     PatternKey<T> extends keyof Handled ? RedundantFallback : unknown;
 
@@ -68,11 +40,10 @@ 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> {
+interface PrimitiveUnionMatcherStrict<T extends Matchable> {
     <R>(handlers: Handlers<T, R>): UnaryFn<T, R>;
     <
         R,
@@ -83,13 +54,11 @@ interface MatcherStrict<T extends Matchable> {
         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 PrimitiveUnionMatcherWidening<T extends Matchable> {
-interface MatcherWidening<T extends Matchable> {
     <P extends Exact<Handlers<T, unknown>, P>>(
         handlers: P,
     ): UnaryFn<T, PatternReturns<P>>;
@@ -102,9 +71,6 @@ interface MatcherWidening<T extends Matchable> {
         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>) =>
@@ -129,6 +95,9 @@ const dispatch =
             shape as never,
         );
 
-export const getMatcher = <T extends Matchable>(): MatcherStrict<T> => dispatch;
+export const getPrimitiveUnionMatcher = <
-export const getMatcherW = <T extends Matchable>(): MatcherWidening<T> =>
+    T extends Matchable,
-    dispatch;
+>(): PrimitiveUnionMatcherStrict<T> => dispatch;
+export const getPrimitiveUnionMatcherW = <
+    T extends Matchable,
+>(): PrimitiveUnionMatcherWidening<T> => dispatch;

src/tagged-union.test.ts

@@ -0,0 +1,640 @@
+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 {
+    getTaggedUnionMatcher,
+    getTaggedUnionMatcherW,
+} from "./tagged-union.ts";
+
+interface Circle {
+    readonly kind: "circle";
+    readonly radius: number;
+}
+interface Square {
+    readonly kind: "square";
+    readonly side: number;
+}
+interface Triangle {
+    readonly kind: "triangle";
+    readonly base: number;
+    readonly height: number;
+}
+type Shape = Circle | Square | Triangle;
+
+// ============================================================================
+// API: getTaggedUnionMatcher — ✔️ Exhaustive / ✔️ ReturnsStrict
+// ============================================================================
+
+test("getTaggedUnionMatcher: exhaustive pattern infers one common return type", () => {
+    // Arrange
+    const factory = getTaggedUnionMatcher<Shape>()("kind");
+
+    // Act
+    const area = factory({
+        circle: (s) => {
+            // Each handler receives the member its tag selects, not the union.
+            expectTypeOf(s).toEqualTypeOf<Circle>();
+            assert.equal(s.kind, "circle");
+            return Math.PI * s.radius ** 2;
+        },
+        square: (s) => {
+            expectTypeOf(s).toEqualTypeOf<Square>();
+            assert.equal(s.kind, "square");
+            return s.side ** 2;
+        },
+        triangle: (s) => {
+            expectTypeOf(s).toEqualTypeOf<Triangle>();
+            assert.equal(s.kind, "triangle");
+            return (s.base * s.height) / 2;
+        },
+    });
+
+    // Assert
+    // ✔️ ReturnsStrict: R is the best common return type, not a widening union.
+    expectTypeOf(area).toEqualTypeOf<(shape: Shape) => number>();
+    assert.equal(area({ kind: "square", side: 2 }), 4);
+    assert.equal(area({ kind: "triangle", base: 2, height: 3 }), 3);
+});
+
+test("getTaggedUnionMatcher: dispatches on numeric tags", () => {
+    // Arrange
+    type Version =
+        | { readonly kind: 1; readonly a: number }
+        | {
+              readonly kind: 2;
+              readonly b: number;
+          };
+    const factory = getTaggedUnionMatcher<Version>()("kind");
+
+    // Act
+    const pick = factory({
+        1: (v) => {
+            expectTypeOf(v).toEqualTypeOf<{
+                readonly kind: 1;
+                readonly a: number;
+            }>();
+            assert.equal(v.kind, 1);
+            return v.a;
+        },
+        2: (v) => {
+            expectTypeOf(v).toEqualTypeOf<{
+                readonly kind: 2;
+                readonly b: number;
+            }>();
+            assert.equal(v.kind, 2);
+            return v.b;
+        },
+    });
+
+    // Assert
+    expectTypeOf(pick).toEqualTypeOf<(shape: Version) => number>();
+    assert.equal(pick({ kind: 1, a: 10 }), 10);
+    assert.equal(pick({ kind: 2, b: 20 }), 20);
+});
+
+test("getTaggedUnionMatcher: dispatches on boolean tags", () => {
+    // Arrange — a boolean discriminant is not a property key, so the handler
+    // map is keyed `true`/`false` and the callback still receives the boolean.
+    interface Ok {
+        readonly status: true;
+        readonly value: number;
+    }
+    interface Err {
+        readonly status: false;
+        readonly message: string;
+    }
+    type Result = Ok | Err;
+    const factory = getTaggedUnionMatcher<Result>()("status");
+
+    // Act
+    const pick = factory({
+        true: (s) => {
+            expectTypeOf(s).toEqualTypeOf<Ok>();
+            assert.equal(s.status, true);
+            return s.value;
+        },
+        false: (s) => {
+            expectTypeOf(s).toEqualTypeOf<Err>();
+            assert.equal(s.status, false);
+            return s.message.length;
+        },
+    });
+
+    // Assert
+    expectTypeOf(pick).toEqualTypeOf<(shape: Result) => number>();
+    assert.equal(pick({ status: true, value: 3 }), 3);
+    assert.equal(pick({ status: false, message: "hi" }), 2);
+});
+
+test("getTaggedUnionMatcher: dispatches on null and undefined tags", () => {
+    // Arrange
+    type Maybe =
+        | { readonly kind: null; readonly text: string }
+        | { readonly kind: undefined; readonly code: number };
+    const factory = getTaggedUnionMatcher<Maybe>()("kind");
+
+    // Act
+    const pick = factory({
+        null: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{
+                readonly kind: null;
+                readonly text: string;
+            }>();
+            assert.equal(s.kind, null);
+            return s.text.length;
+        },
+        undefined: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{
+                readonly kind: undefined;
+                readonly code: number;
+            }>();
+            assert.equal(s.kind, undefined);
+            return s.code;
+        },
+    });
+
+    // Assert
+    expectTypeOf(pick).toEqualTypeOf<(shape: Maybe) => number>();
+    assert.equal(pick({ kind: null, text: "hi" }), 2);
+    assert.equal(pick({ kind: undefined, code: 7 }), 7);
+});
+
+test("getTaggedUnionMatcher: a fallback receives unhandled boolean and nullish members", () => {
+    // Arrange
+    type Mixed =
+        | { readonly kind: "a"; readonly a: number }
+        | { readonly kind: true; readonly b: number }
+        | { readonly kind: false; readonly c: number }
+        | { readonly kind: null; readonly d: number };
+    const factory = getTaggedUnionMatcher<Mixed>()("kind");
+
+    // Act
+    const pick = factory({ a: () => 1 as const }, (s) => {
+        // The fallback sees the real members, not the projected keys.
+        expectTypeOf(s).toEqualTypeOf<
+            | { readonly kind: true; readonly b: number }
+            | { readonly kind: false; readonly c: number }
+            | { readonly kind: null; readonly d: number }
+        >();
+        // `true`/`false`/`null` are keyed as `"true"`/`"false"`/`"null"`,
+        // but the fallback still receives the boolean/null, not the string.
+        assert.ok(s.kind === true || s.kind === false || s.kind === null);
+        return 2 as const;
+    });
+
+    // Assert
+    expectTypeOf(pick).toEqualTypeOf<(shape: Mixed) => 1 | 2>();
+    assert.equal(pick({ kind: "a", a: 1 }), 1);
+    assert.equal(pick({ kind: true, b: 1 }), 2);
+    assert.equal(pick({ kind: false, c: 1 }), 2);
+    assert.equal(pick({ kind: null, d: 1 }), 2);
+});
+
+test("getTaggedUnionMatcherW: boolean and nullish tags widen to the union", () => {
+    // Arrange
+    type Maybe =
+        | { readonly kind: true; readonly a: number }
+        | { readonly kind: false; readonly b: number }
+        | { readonly kind: null; readonly c: number };
+    const factory = getTaggedUnionMatcherW<Maybe>()("kind");
+
+    // Act
+    const matcher = factory({
+        true: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{
+                readonly kind: true;
+                readonly a: number;
+            }>();
+            assert.equal(s.kind, true);
+            return "yes" as const;
+        },
+        false: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{
+                readonly kind: false;
+                readonly b: number;
+            }>();
+            assert.equal(s.kind, false);
+            return 0 as const;
+        },
+        null: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{
+                readonly kind: null;
+                readonly c: number;
+            }>();
+            assert.equal(s.kind, null);
+            return null;
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<(shape: Maybe) => "yes" | 0 | null>();
+    assert.equal(matcher({ kind: true, a: 1 }), "yes");
+    assert.equal(matcher({ kind: false, b: 1 }), 0);
+    assert.equal(matcher({ kind: null, c: 1 }), null);
+});
+
+// ============================================================================
+// API: getTaggedUnionMatcher — ❌ Exhaustive (fallback) / ✔️ ReturnsStrict
+// ============================================================================
+
+test("getTaggedUnionMatcher: a fallback receives the unhandled members", () => {
+    // Arrange
+    const factory = getTaggedUnionMatcher<Shape>()("kind");
+
+    // Act
+    const area = factory(
+        {
+            circle: (s) => {
+                expectTypeOf(s).toEqualTypeOf<Circle>();
+                assert.equal(s.kind, "circle");
+                return 1 as const;
+            },
+        },
+        (s) => {
+            // The fallback sees only the members `circle` did not handle.
+            expectTypeOf(s).toEqualTypeOf<Square | Triangle>();
+            assert.ok(s.kind === "square" || s.kind === "triangle");
+            return 2 as const;
+        },
+    );
+
+    // Assert
+    expectTypeOf(area).toEqualTypeOf<(shape: Shape) => 1 | 2>();
+    assert.equal(area({ kind: "circle", radius: 1 }), 1);
+    assert.equal(area({ kind: "square", side: 1 }), 2);
+    assert.equal(area({ kind: "triangle", base: 1, height: 1 }), 2);
+});
+
+test("getTaggedUnionMatcher: an open discriminant keeps the fallback open", () => {
+    // Arrange
+    interface Message {
+        readonly kind: string;
+        readonly text: string;
+    }
+    const factory = getTaggedUnionMatcher<Message>()("kind");
+
+    // Act
+    const matcher = factory({ info: () => 1 as const }, (s) => {
+        // The map's literal key does not close an open discriminant, so the
+        // remainder stays `Message` and the fallback is not redundant.
+        expectTypeOf(s).toEqualTypeOf<Message>();
+        assert.equal(typeof s.text, "string");
+        return 2 as const;
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<(shape: Message) => 1 | 2>();
+    assert.equal(matcher({ kind: "info", text: "" }), 1);
+    assert.equal(matcher({ kind: "warn", text: "" }), 2);
+});
+
+// ============================================================================
+// API: getTaggedUnionMatcherW — ✔️ Exhaustive / ❌ ReturnsStrict
+// ============================================================================
+
+test("getTaggedUnionMatcherW: exhaustive pattern widens to the union of returns", () => {
+    // Arrange
+    const factory = getTaggedUnionMatcherW<Shape>()("kind");
+
+    // Act
+    const describe = factory({
+        circle: (s) => {
+            expectTypeOf(s).toEqualTypeOf<Circle>();
+            assert.equal(s.kind, "circle");
+            return "round" as const;
+        },
+        square: (s) => {
+            expectTypeOf(s).toEqualTypeOf<Square>();
+            assert.equal(s.kind, "square");
+            return 4 as const;
+        },
+        triangle: (s) => {
+            expectTypeOf(s).toEqualTypeOf<Triangle>();
+            assert.equal(s.kind, "triangle");
+            return true as const;
+        },
+    });
+
+    // Assert
+    // ❌ ReturnsStrict: mixed handler returns widen to their union.
+    expectTypeOf(describe).toEqualTypeOf<
+        (shape: Shape) => "round" | 4 | true
+    >();
+    assert.equal(describe({ kind: "circle", radius: 1 }), "round");
+    assert.equal(describe({ kind: "square", side: 1 }), 4);
+    assert.equal(describe({ kind: "triangle", base: 1, height: 1 }), true);
+});
+
+// ============================================================================
+// API: getTaggedUnionMatcherW — ❌ Exhaustive (fallback) / ❌ ReturnsStrict
+// ============================================================================
+
+test("getTaggedUnionMatcherW: a fallback widens gaps into the union", () => {
+    // Arrange
+    const factory = getTaggedUnionMatcherW<Shape>()("kind");
+
+    // Act
+    const matcher = factory({ circle: () => 1 as const }, (s) => {
+        expectTypeOf(s).toEqualTypeOf<Square | Triangle>();
+        // Returning the member verbatim lets the `Assert` block check the
+        // exact value dispatch passed.
+        return s;
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<
+        (shape: Shape) => 1 | Square | Triangle
+    >();
+    assert.equal(matcher({ kind: "circle", radius: 1 }), 1);
+    assert.deepEqual(matcher({ kind: "square", side: 1 }), {
+        kind: "square",
+        side: 1,
+    });
+    assert.deepEqual(matcher({ kind: "triangle", base: 1, height: 1 }), {
+        kind: "triangle",
+        base: 1,
+        height: 1,
+    });
+});
+
+// ============================================================================
+// Factory contracts — calls that must not compile
+// ============================================================================
+
+test("getTaggedUnionMatcher factory rejects patterns outside its contract", () => {
+    // Arrange
+    const factory = getTaggedUnionMatcher<Shape>()("kind");
+
+    // Act / Assert — the calls below must not compile
+    factory({
+        circle: () => 1,
+        square: () => 2,
+        triangle: () => 3,
+        // @ts-expect-error `hexagon` is not a tag of Shape
+        hexagon: () => 4,
+    });
+    // @ts-expect-error a gap without a fallback is not exhaustive
+    factory({ circle: () => 1 });
+    // @ts-expect-error a `string` fallback does not fit the `number` handlers
+    factory({ circle: () => 1 }, () => "x");
+    // @ts-expect-error a fallback is redundant once the map covers the union
+    factory({ circle: () => 1, square: () => 2, triangle: () => 3 }, () => 0);
+});
+
+test("getTaggedUnionMatcher factory rejects a non-discriminant key", () => {
+    // Arrange
+    type Mixed =
+        | { readonly id: Date; readonly kind: "a" }
+        | { readonly id: Date; readonly kind: "b" };
+
+    // Act / Assert — the calls below must not compile
+    // @ts-expect-error `id` is a common key but its value is not a tag
+    getTaggedUnionMatcher<Mixed>()("id");
+    getTaggedUnionMatcher<Mixed>()("kind");
+});
+
+test("getTaggedUnionMatcher factory rejects non-exhaustive boolean and nullish maps", () => {
+    // Arrange
+    type Result =
+        | { readonly status: true; readonly a: number }
+        | { readonly status: false; readonly b: number };
+    type Maybe =
+        | { readonly status: null; readonly c: number }
+        | { readonly status: undefined; readonly d: number };
+    const resultFactory = getTaggedUnionMatcher<Result>()("status");
+    const maybeFactory = getTaggedUnionMatcher<Maybe>()("status");
+
+    // Act / Assert — the calls below must not compile
+    // @ts-expect-error only `true` is handled; `false` is not
+    resultFactory({ true: () => 1 });
+    // @ts-expect-error only `null` is handled; `undefined` is not
+    maybeFactory({ null: () => 1 });
+    // @ts-expect-error a fallback is redundant once both tags are handled
+    resultFactory({ true: () => 1, false: () => 2 }, () => 0);
+});
+
+test("getTaggedUnionMatcherW factory rejects patterns outside its contract", () => {
+    // Arrange
+    const factory = getTaggedUnionMatcherW<Shape>()("kind");
+
+    // Act / Assert — the calls below must not compile
+    factory({
+        circle: () => 1 as const,
+        square: () => 2 as const,
+        triangle: () => 3 as const,
+        // @ts-expect-error `hexagon` is not a tag of Shape
+        hexagon: () => 4 as const,
+    });
+    // @ts-expect-error a gap without a fallback is not exhaustive
+    factory({ circle: () => 1 as const });
+    factory(
+        // @ts-expect-error a fallback is redundant once the map covers the union
+        {
+            circle: () => 1 as const,
+            square: () => 2 as const,
+            triangle: () => 3 as const,
+        },
+        () => 0,
+    );
+});
+
+// ============================================================================
+// Dispatch — runtime behavior
+// ============================================================================
+
+test("getTaggedUnionMatcher: an unhandled tag throws without a fallback", () => {
+    // Arrange — an open discriminant widens its handler map to an index
+    // signature, so the type system cannot prove the runtime map is exhaustive.
+    interface Message {
+        readonly kind: string;
+    }
+    const handlers: Record<string, (shape: Message) => number> = {
+        info: (shape) => {
+            // The full member reaches the handler, not its tag.
+            assert.equal(shape.kind, "info");
+            return 1;
+        },
+    };
+    const matcher = getTaggedUnionMatcher<Message>()("kind")(handlers);
+
+    // Act / Assert
+    assert.equal(matcher({ kind: "info" }), 1);
+    assert.throws(() => matcher({ kind: "warn" }), /Unhandled tag: warn/);
+});
+
+// ============================================================================
+// Autocomplete — the language server is the oracle, not the type system
+// ============================================================================
+
+const REPO_ROOT = path.resolve(import.meta.dirname, "..");
+const SHAPE_SOURCE = `type Shape = { kind: "a"; a: number } | { kind: "b"; b: number } | { kind: "c"; c: number };`;
+
+interface LabelsProbe {
+    readonly name: string;
+    readonly factory: "getTaggedUnionMatcher" | "getTaggedUnionMatcherW";
+    readonly body: string;
+    readonly tail?: string;
+    readonly typeName?: string;
+    readonly typeSource?: string;
+}
+
+const labelsFor = ({
+    name,
+    factory,
+    body,
+    tail = "",
+    typeName = "Shape",
+    typeSource = SHAPE_SOURCE,
+}: LabelsProbe): Promise<readonly string[]> => {
+    const session = new LspSession(REPO_ROOT);
+    const target: CompletionTarget = {
+        file: `src/__autocomplete_${name}.ts`,
+        source: [
+            `import { ${factory} } from "./index.ts";`,
+            typeSource,
+            `const m = ${factory}<${typeName}>()("kind")({`,
+            body,
+            `}${tail});`,
+            "",
+        ].join("\n"),
+    };
+    return session
+        .completionLabelsAt(target)
+        .then((result) => result.labels)
+        .finally(() => session.close());
+};
+
+test("autocomplete: a tagged-union pattern requires the tags", () => {
+    // Arrange
+    const name = "tagged_union_fresh";
+
+    // Act
+    const labels = labelsFor({
+        name,
+        factory: "getTaggedUnionMatcher",
+        body: "    /*COMPLETE*/",
+    });
+
+    // Assert
+    return labels.then((result) => {
+        assert.deepEqual([...result], ["a", "b", "c"]);
+    });
+});
+
+test("autocomplete: a handled tag drops out of the popup", () => {
+    // Arrange
+    const name = "tagged_union_after_key";
+
+    // Act
+    const labels = labelsFor({
+        name,
+        factory: "getTaggedUnionMatcher",
+        body: "    a: () => 1,\n    /*COMPLETE*/",
+    });
+
+    // Assert
+    return labels.then((result) => {
+        assert.deepEqual([...result], ["b", "c"]);
+    });
+});
+
+test("autocomplete: a fallback makes the remaining tags optional", () => {
+    // Arrange
+    const name = "tagged_union_with_fallback";
+
+    // Act
+    const labels = labelsFor({
+        name,
+        factory: "getTaggedUnionMatcher",
+        body: "    /*COMPLETE*/",
+        tail: ", () => 0",
+    });
+
+    // Assert
+    return labels.then((result) => {
+        assert.deepEqual([...result], ["a?", "b?", "c?"]);
+    });
+});
+
+// `true`/`false`/`null`/`undefined` tags are not property keys, so the popup
+// must offer them by name through the `PatternKey` projection.
+const STATUS_SOURCE = `type Status = { kind: true; a: number } | { kind: false; b: number } | { kind: null; c: number } | { kind: undefined; d: number };`;
+
+test("autocomplete: boolean and nullish tags are offered by name", () => {
+    // Arrange
+    const name = "tagged_union_boolean_nullish";
+
+    // Act
+    const labels = labelsFor({
+        name,
+        factory: "getTaggedUnionMatcher",
+        typeName: "Status",
+        typeSource: STATUS_SOURCE,
+        body: "    /*COMPLETE*/",
+    });
+
+    // Assert
+    return labels.then((result) => {
+        assert.deepEqual([...result], ["false", "null", "true", "undefined"]);
+    });
+});
+
+// `Mixed` has two common keys, but `id`'s value is not a tag, so only `kind`
+// may serve as the discriminant.
+const MIXED_SOURCE = `type Mixed = { id: Date; kind: "a"; a: number } | { id: Date; kind: "b"; b: number };`;
+
+const discriminantLabelsFor = ({
+    name,
+    factory,
+    typeName,
+    typeSource,
+}: {
+    readonly name: string;
+    readonly factory: "getTaggedUnionMatcher" | "getTaggedUnionMatcherW";
+    readonly typeName: string;
+    readonly typeSource: string;
+}): Promise<readonly string[]> => {
+    const session = new LspSession(REPO_ROOT);
+    const target: CompletionTarget = {
+        file: `src/__autocomplete_${name}.ts`,
+        source: [
+            `import { ${factory} } from "./index.ts";`,
+            typeSource,
+            `const m = ${factory}<${typeName}>()(/*COMPLETE*/);`,
+            "",
+        ].join("\n"),
+    };
+    return session
+        .completionLabelsAt(target)
+        .then((result) => result.labels)
+        .finally(() => session.close());
+};
+
+test("autocomplete: the discriminant key is offered at the key argument", () => {
+    // Arrange
+    const name = "tagged_union_discriminant";
+
+    // Act
+    const labels = discriminantLabelsFor({
+        name,
+        factory: "getTaggedUnionMatcher",
+        typeName: "Mixed",
+        typeSource: MIXED_SOURCE,
+    });
+
+    // Assert
+    return labels.then((result) => {
+        // The argument position also offers every global identifier, so assert
+        // inclusion of the discriminant and exclusion of the non-tag key.
+        assert.ok(result.includes('"kind"'));
+        assert.ok(!result.includes('"id"'));
+    });
+});

src/tagged-union.ts

@@ -0,0 +1,142 @@
+import type { Exact, UnknownRecord } from "type-fest";
+
+import type {
+    HandlerMap,
+    Matchable,
+    PatternKey,
+    PatternParam,
+    PatternReturns,
+    RedundantFallback,
+    UnaryFn,
+} 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, so an open universe
+// keeps an open fallback.
+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` tagged `V`. `Extract` distributes over the union, so a
+// duplicated tag maps to a union of members rather than silently dropping one.
+// Keyed by `PatternKey`, so `boolean`/`null`/`undefined` tags can key a mapped
+// type; `PatternParam` inverts the projection to recover the member.
+type MapTaggedUnion<T extends object, K extends keyof T> = {
+    [P in PatternKey<Tags<T, K>>]: Extract<T, Record<K, PatternParam<P>>>;
+};
+
+type Handlers<T extends object, K extends keyof T, R> = {
+    [P in PatternKey<Tags<T, K>>]: UnaryFn<MapTaggedUnion<T, K>[P], R>;
+};
+
+// The members `Handled` covers. Mapping over the projected keys 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-union matcher's
+// `Exclude<T, PatternParam<keyof Handled>>`.
+type HandledMembers<T extends object, K extends keyof T, Handled> = {
+    [P in PatternKey<Tags<T, K>>]: P extends keyof Handled
+        ? MapTaggedUnion<T, K>[P]
+        : never;
+}[PatternKey<Tags<T, K>>];
+
+// 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.
+type Fallback<T extends object, K extends keyof T, Handled, R> = UnaryFn<
+    Exclude<T, HandledMembers<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>): 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>,
+    ): 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,
+    ): 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>,
+    ): 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;