🚀 Release 0.4.0

🔀 Merge chore/unify-task-branching into main
📝 Route every task through the full branching model
2026-09-20 21:46:32 +00:00 · 2026-09-20 21:44:21 +00:00 · 2026-09-20 21:43:46 +00:00 · 2026-09-19 00:02:23 +00:00 · 2026-09-18 23:52:47 +00:00 · 2026-09-18 23:48:59 +00:00
20 changed files with 1176 additions and 699 deletions
@@ -22,7 +22,8 @@
        "eslint/sort-imports": "off",
        "import/consistent-type-specifier-style": "off",
        "unicorn/prefer-export-from": "off",
-        "typescript/method-signature-style": "off"
+        "typescript/method-signature-style": "off",
        "typescript/promise-function-async": "off"
    },
    "options": { "typeAware": true },
    "env": { "builtin": true, "es2024": true, "node": true },
@@ -41,6 +42,12 @@
            "rules": {
                "import/no-nodejs-modules": "off"
            }
        },
        {
            "files": ["src/util/__tests__/**"],
            "rules": {
                "import/no-nodejs-modules": "off"
            }
        }
    ],
    "ignorePatterns": ["dist", "node_modules", "coverage"]
@@ -25,10 +25,10 @@ first-action facts. Do not restate evolving prose here — it will drift.
 Don't silence the type system to force a green run. As an agent these are forbidden:
 - `// @ts-nocheck`, `// @ts-ignore`, `// @ts-expect-error`
- `// oxlint-disable` / `// oxlint-disable-next-line`
+- `// oxlint-disable` / `// oxlint-disable-next-line` — the sole exception is the fixed file-level `typescript/no-floating-promises` header at the top of a `*.test.ts` file, spelled exactly as [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) prescribes
 - `as` casts used to push an expression through (type-aware oxlint already flags unsafe assertions)
-Fix the root cause with the type system instead — narrowing, generics, `satisfies`, conditional / mapped types, utility types (`NonNullable`, `Exclude`, …). TypeScript can express it; that's the intended tool. The `oxlint-disable`-location rule in [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) is a **human** last-resort convention (so a reviewer can spot a deliberate suppression) — it is not permission for you to add one. If the types genuinely cannot express something, stop and surface the conflict (commit message / handover) rather than suppress it.
+Fix the root cause with the type system instead — narrowing, generics, `satisfies`, conditional / mapped types, utility types (`NonNullable`, `Exclude`, …). TypeScript can express it; that's the intended tool. The `oxlint-disable`-location rule in [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) is a **human** last-resort convention (so a reviewer can spot a deliberate suppression) — it is not permission for you to add one, except the one fixed `*.test.ts` file-level header named there. If the types genuinely cannot express something, stop and surface the conflict (commit message / handover) rather than suppress it.
 The same applies to the checks themselves: **never `git commit --no-verify`** (or otherwise skip a pre-commit / pre-push hook). The checks are fast and offline, so a redundant run is fine — bypassing a hook to get green is the identical anti-pattern. If a commit already skipped a hook, redo it through one: `git reset --soft HEAD~1 && git commit -C <skipped-sha>`.
@@ -42,7 +42,9 @@ Never start a long-lived / blocking process such as `npm run watch`. It runs unt
 ### Working on tasks
- **Task with subtasks** (a task that has indented children): create the branch with `npm run create:branch -- <prefix>/<desc>`, inferring the prefix from the task content (`feature/…` / `fix/…` / `chore/…`) — do not hand-write `git switch -c`, the command enforces the clean-tree / current-`main` / green-baseline precondition. Work on each subtask with commits, then present a concise handover for the user to review. Use this fixed shape:
+Every task — with or without subtasks — goes through the complete branching model:
 - Create the branch with `npm run create:branch -- <prefix>/<desc>`, inferring the prefix from the task content (`feature/…` / `fix/…` / `chore/…`) — do not hand-write `git switch -c`, the command enforces the clean-tree / current-`main` / green-baseline precondition. Work with commits (each subtask gets one or more), then present a concise handover for the user to review. Use this fixed shape:
    ```md
    ## Handover — <branch>
@@ -54,9 +56,7 @@ Never start a long-lived / blocking process such as `npm run watch`. It runs unt
    Once the user has no further objections, merge back: `npm run create:finish` (on the branch — it merges `--no-ff`, runs `npm run verify`, and deletes the branch). The branching model is documented in [CONTRIBUTING.md § Branching model](./CONTRIBUTING.md#branching-model).
- **Leaf task** (no indented children): implement on the current branch and commit.
+Follow [CONTRIBUTING.md § Testing discipline (type-driven)](./CONTRIBUTING.md#testing-discipline-type-driven) throughout.
 In both cases, follow [CONTRIBUTING.md § Testing discipline (type-driven)](./CONTRIBUTING.md#testing-discipline-type-driven). Each subtask gets one or more commits.
 ## Read these
@@ -7,8 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 ## [0.4.0] - 2026-09-20
 - move the `_` fallback out of handlers
 ## [0.3.0] - 2026-09-18
 - condensed primitive matcher factories down to 2 from formerly 4
 - house shared test helpers under `src/util/__tests__/`
 ## [0.2.0] - 2026-09-16
 - allow ternaries and lowercase comments in oxlint
 - switch `src/primitive.ts` prose from block comments to line comments
 - remove the template's `match`/`P` example modules and their documentation, and point `src/index.ts` at the primitive matchers
 ## [0.1.8] - 2026-09-16
@@ -51,7 +63,10 @@ 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.1.8...main
+[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.4.0...main
 [0.4.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.3.0...0.4.0
 [0.3.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.2.0...0.3.0
 [0.2.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.8...0.2.0
 [0.1.8]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.7...0.1.8
 [0.1.7]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.6...0.1.7
 [0.1.6]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.5...0.1.6
@@ -67,6 +67,11 @@ before the implementation. The loop is **type → red → green → refactor**:
   `npm run verify` as the definition-of-done gate.
 Every test pairs an `expectTypeOf(...)` with an `assert.*`; keep them together.
 The autocomplete tests (`src/util/__tests__/lsp-completion.test.ts` for the
 helper, `src/primitive.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)).
 Each test body follows **AAA (Arrange–Act–Assert)** with labeled blocks
 separated by a blank line: `// Arrange` sets up the inputs (e.g. the matcher
 factory), `// Act` exercises the subject once from them (not a second
@@ -151,7 +156,11 @@ reaches for by default:
 - **`oxlint-disable` directives live in source, not `.oxlintrc.json`.** The
  trade-off must sit next to the code it silences. This is a _human_ last-resort
  convention; agents must not add these — see
-  [AGENTS.md § Never do](./AGENTS.md#never-do). (why:
+  [AGENTS.md § Never do](./AGENTS.md#never-do). The sole agent exception is the
  fixed file-level header at the top of a `*.test.ts` file, spelled exactly:
  `/* oxlint-disable typescript/no-floating-promises -- expectTypeOf() is a sync
 type-assertion library that the type-aware linter misidentifies as a promise
 */` — any other suppression stays human-last-resort. (why:
  [development/tooling.md](./development/tooling.md#oxlint-disable-directives-live-next-to-the-code))
 - **Don't put slow / network / whole-project scans in `check` or pre-commit.**
  Advisory scans are not correctness gates; they belong under `maintain:`. (why:
@@ -2,34 +2,14 @@
 Pattern matching for TypeScript/ESM environments (F#-style, not regex).
 ## Synopsis
 ```ts
 import { match, P } from "tiny-pattern-ts";
 const reply = (answer: "yes" | "no") =>
    match(answer)
        .with(P.literal("yes"), (): "agreed" => "agreed")
        .with(P.literal("no"), (): "declined" => "declined")
        .exhaustive();
 reply("yes"); // "agreed"
 ```
 ## Description
-`tiny-pattern-ts` gives TypeScript the shape of F#-style pattern matching:
+`tiny-pattern-ts` brings F#-style pattern matching to TypeScript. Patterns are
-a value flows through a chain of patterns, the first one that matches runs its
+ordinary objects whose `matches` method is a TypeScript type guard, so narrowing
-handler, and the handler receives the value narrowed to that pattern's type. The
+composes the way any other guard does. It is deliberately not a regex engine and
-"patterns" are ordinary objects whose `matches` method is a TypeScript type
+not a macro: there is no transpiler and no DSL to learn, and the type-level
-guard, so narrowing composes the way any other guard does.
+contract is the feature — see [development/library.md](./development/library.md)
-
+for the design decisions and the known limitations.
 It is deliberately not a regex engine and not a macro. There is no transpiler
 and no DSL to learn: `match(value)` returns a builder, `.with(pattern, handler)`
 adds a case, and the chain ends in either `.exhaustive()` or `.otherwise(...)`.
 The type-level contract is the feature — see
 [development/library.md](./development/library.md) for the design decisions and
 the known limitations.
 ## Requirements
@@ -39,124 +19,6 @@ the known limitations.
  both resolve on TS >= 5.0 in `node10` / `node16` / `nodenext` / `bundler`.
 - The package is **ESM-only** (no CommonJS shim).
 ## Examples
 ### Literal matching and `exhaustive()`
 `.exhaustive()` returns the union of the handler return types and throws if no
 case matched. Annotate handler returns when you want literal types rather than
 `string`:
 ```ts
 type Answer = "yes" | "no";
 const reply = (answer: Answer): "agreed" | "declined" =>
    match(answer)
        .with(P.literal("yes"), (): "agreed" => "agreed")
        .with(P.literal("no"), (): "declined" => "declined")
        .exhaustive();
 reply("yes"); // "agreed"
 ```
 `exhaustive()` checks at runtime, not at compile time — TypeScript does not force
 every union member to have a case (see
 [development/library.md](./development/library.md#exhaustive-is-a-runtime-check)).
 Use `.otherwise(...)` when a fallback is wanted:
 ```ts
 const label = (answer: Answer): string =>
    match(answer)
        .with(P.literal("yes"), () => "agreed")
        .otherwise(() => "not agreed");
 ```
 ### Matching by `typeof`
 `P.type<T>(name)` pairs an explicit type `T` with the runtime `typeof` name it
 should test for:
 ```ts
 const describe = (value: unknown): string =>
    match(value)
        .with(P.type<string>("string"), (s) => `string of length ${s.length}`)
        .with(P.type<number>("number"), (n) => `number ${n.toFixed(2)}`)
        .otherwise(() => "something else");
 ```
 The supported names are `string`, `number`, `boolean`, `bigint`, `symbol`,
 `undefined`, `object`, and `function`. `"object"` matches non-null objects and
 functions; `"undefined"` compares against `undefined` directly.
 ### Structural matching and discriminated unions
 `P.shape(shape, refine?)` checks that every key in `shape` exists on the value.
 A value that is itself a matcher is applied, otherwise it is compared with
 strict equality. To narrow to a concrete type, pass a `refine` type guard:
 ```ts
 interface Circle {
    readonly kind: "circle";
    readonly radius: number;
 }
 interface Square {
    readonly kind: "square";
    readonly side: number;
 }
 type Shape = Circle | Square;
 const area = (shape: Shape): number =>
    match(shape)
        .with(
            P.shape({ kind: "circle" }, (v): v is Circle => "radius" in v),
            (c) => Math.PI * c.radius ** 2,
        )
        .with(
            P.shape({ kind: "square" }, (v): v is Square => "side" in v),
            (s) => s.side ** 2,
        )
        .exhaustive();
 ```
 Without `refine`, `P.shape` returns a matcher for the shape's own type, not the
 narrowed one. Nested matchers can be used in the shape object, for example
 `P.shape({ name: P.type<string>("string") })`.
 ### Custom guards with `when`
 `P.when` takes a type guard and infers the narrowed type from it:
 ```ts
 const toNumber = (value: unknown): number =>
    match(value)
        .with(
            P.when((v): v is string => typeof v === "string"),
            (s) => Number.parseInt(s, 10),
        )
        .otherwise(() => 0);
 ```
 ### Widening with `any`
 `P.any<T>(predicate)` takes a plain boolean predicate and a declared type `T`,
 for cases where the predicate cannot be written as a type guard:
 ```ts
 const firstNumber = (items: readonly unknown[]): number | undefined =>
    match(items)
        .with(
            P.any<readonly number[]>(
                (v) =>
                    Array.isArray(v) &&
                    v.every((item) => typeof item === "number"),
            ),
            (xs) => xs[0],
        )
        .otherwise(() => undefined);
 ```
 ## API
 Yet to be implemented
@@ -5,33 +5,65 @@ 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 @high
+☐ Split off template into separate package => pi --session 01a07dde-7050-7054-bb36-1606d7eb2bc3 @low
 ✔ straighten oxc rules @done
    ✔ oxc forbids ternary => remove oxc rule @done
    ✔ oxc wants comments to start comments with a capital letter => remove oxc rule @done
    ✔ there already exists a /* */ block comment in primitive.ts, => change to multi-line comment @done
 ✔ Remove example code files and its documentation and its exports from index.ts @high @done
    ✔ remove src/match.ts and its documentation @high @done
    ✔ remove src/pattern.ts and its documentation @high @done
    ✔ remove src/index.test.ts and its documentation @high @done
    ✔ exports from `src/index.ts` should only be the public API surface @done
 v1.0:
 ☐ API surface is stable and fully typed
    ☐ Finalize public exports in `src/index.ts`
    ☐ Document all exported types and functions
    ☐ Add JSDoc for public APIs
 ☐ Test coverage meets threshold
-    ☐ Achieve 100% branch coverage on `src/pattern.ts`
+    ☐ Achieve 100% branch coverage on `src/primitive.ts`
    ☐ Achieve 100% branch coverage on `src/match.ts`
    ☐ Achieve 100% branch coverage on `src/index.ts`
-Bugs:
+Testing:
 ✔ Cover autocomplete with real completion test cases in the suite @medium @done
    → `src/util/__tests__/lsp-completion.ts` (`#test-utils/…`) is the helper; the suite asserts its labels (see development/testing.md § Autocomplete)
    → wire it into `node --test` so a test asserts the offered labels
    → note: `Parameters<typeof factory>[0]` resolves only the *last* overload; use `@ts-expect-error` call sites for factory negatives, not `not.toExtend<Parameters<…>>`
 ✔ Drive the LSP completion helper through the LSP protocol library instead of a hand-rolled JSON-RPC client @medium @done
    ✔ Add `vscode-languageserver-protocol` and record the tooling decision @done
    ✔ Rewrite `src/util/__tests__/lsp-completion.ts` onto `createMessageConnection` and typed requests @done
    ✔ Update `development/testing.md § Autocomplete` for the new client @done
    ✔ Run `npm run verify` and check the task off @done
 Matcher:
 ✔ Clean up: adopt the 3-overload matcher (`src/prototype-ac2.ts`) and delete the prototypes @high @done
    → `getMatcher` / `getMatcherW`, each with overloads `ExhaustiveLoose` → `Fallback` → `Handlers` (order is load-bearing)
    → fold into `src/primitive.ts` / the public API; drop `src/prototype*.ts`
 ✔ `_` should receive only the unhandled `T` keys, not all of `T` @medium @done
    → the fallback is now a second argument: `(handlers, (s) => …)`, `s: Exclude<T, keyof handlers>`
 ☐ A fallback for an already-exhaustive handler map must be a compile error @medium
    → `(handlers, fallback)` with `handlers` covering all of `T` is accepted; the redundant fallback should be rejected (currying would allow the guard)
 Bugs:
 ✔ TS 7 LSP server logs `context canceled` on stderr at shutdown @done
    → `handleExit` returns `io.EOF`, cancelling the background context while `Session.updateWatches` is still in flight; the bare error is flushed to stderr and the server exits 1
    → close stdin after `shutdown` instead of sending `exit`; the server exits cleanly (code 0, no output), kill kept as a fallback
 Enhancements:
 ☐ Allow boolean literals in primitive union patterns (e.g. `true: () => "yes"`) @medium
 ☐ Are there other primitive types that should be supported in union patterns? (e.g. `bigint`, `symbol`) @medium
 Documentation:
 ☐ Bring README.md back to its previous form — synopsis and examples restored, in the correct place
    → previous section order: title, tagline, Synopsis, Description, Requirements, Examples, API, License, Contributing
    → previous Examples order: literal/exhaustive, typeof, structural/discriminated unions, when, any
 ☐ Create `examples/` directory with runnable snippets
 ☐ Add comparison section vs. other TS pattern-matching libs in Readme.md
 ☐ Write migration guide for users coming from discriminated unions
 ☐ Create backlog tasks for implementation
 ✔ Document the matcher design paths in `development/` — union vs overload merge, inferred universe (`NoInfer`), conditional `RequireKeys`, cases-first — and why each was abandoned @done
 ☐ Validate code fences in Markdown (start with README.md) — compile the TypeScript examples against `src/` so the docs cannot drift from the API
 Workflow:
@@ -3,4 +3,87 @@
 The type-level design of the public API and the limitations it carries. The
 user-facing reference is [README § API](../README.md#api).
-Currently the library is placeholder code.
+The matcher is implemented in `src/primitive.ts` and re-exported from
 `src/index.ts` as `getMatcher` / `getMatcherW`; the rest of the library is
 placeholder code.
 ## Matcher shape
 #### Decision (2026-09)
 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) => …);
 ```
 Exhaustive or fallback is decided **at the call site**, by whether the second
 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`.
 Each factory is two overloads whose order is load-bearing:
 1. `Handlers<T, R>` — the exhaustive form, and the contextual type of the
   handler-map popup;
 2. `Handled extends Exact<Partial<Handlers<T, R>>, Handled>` plus
   `Fallback<T, Handled, R>` — a partial handler map plus the fallback.
 #### Why
 - **The fallback is an argument, not a property.** TypeScript fixes a property's
  contextual type before it infers its sibling keys, so `_: (s) => …` in the
  handler map can only see all of `T`, never `Exclude<T, keyof Handled>`. A later
  argument is contextually typed from inference on an earlier one, so the split
  is what makes the remainder expressible.
 - **Overload order keeps both messages.** #1 supplies the contextual type
  (`a, b, c`); #2 accepts a partial map once a fallback is present, so its popup
  is optional (`a?, b?, c?`). A gap without a fallback is reported against #1.
 - **`R` needs an inference site.** `R` inside the `Exact<…>` constraint is not
  one, so `handlers: Handled & Partial<Handlers<T, R>>` re-adds it; without that
  `R` collapses to `unknown` when the handler params are inferred.
 - **`Exact` restores the excess-property check.** TypeScript skips it for a
  generic constraint, so without `Exact` the handler map accepts keys outside
  `T`.
 - Two factories, not four: the fallback is an argument, not a separate API.
 #### Rejected
 - **Single-object `_`** (the former shape). `_` sees only all of `T`; the
  remainder is not expressible there, and an exhaustive map plus `_` was
  accepted.
 - **Curried handlers-first** — `(handlers)(fallback)`. `Handled` is fixed before
  the second call, so a redundant-fallback guard would work. Rejected: two calls
  for the common case.
 - **`this` / HKT self-reference.** `this` is post-construction (method bodies,
  return positions); a parameter's contextual type is pre-construction.
  `keyof this` in an interface method is the interface, not the literal.
 - **Variance / `const` type parameters / `NoInfer` / `unique symbol` brands /
  defaulted type-param guards.** None change inference or evaluation order;
  `in`/`out` on the handler map broke contextual typing outright. `NoInfer`
  specifically leaks into the emitted `.d.ts`, raising the consumer floor to
  TypeScript 5.4 (README promises `>= 5.0`).
 - **Union merge**, **overload merge with only the exhaustive arm last**,
  **inferred universe**, **conditional `RequireKeys`**, **cases-first curried** —
  decided against while the API was single-object; their reasons (reported
  near-miss member, no `_` in the exhaustive popup, `NoInfer`/floor, `keyof P`
  counts optional keys, not pipe-friendly) hold where they still apply.
 #### Known issue
 - A redundant fallback is accepted: when the handler map already covers `T`, the
  fallback is still allowed. The guard would be
  `Exclude<T, keyof Handled> extends never ? never : unknown`, but the
  conditional is evaluated before `Handled` is inferred; currying is the only
  encoding that fixes it (see Rejected).
 - `PatternReturns` must be
  `ReturnType<Extract<ValueOf<P>, (...args: never[]) => unknown>>` so it survives
  the closed, partly-optional `P` constraints.
 - `Parameters<typeof factory>[0]` resolves only the **last** overload, so it is
  not a sound "rejected" oracle for a factory. Factory-negative tests use
  `@ts-expect-error` call sites (the test file only — the general ban stands).
@@ -27,10 +27,11 @@ 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 wiring, `exhaustive()`
+- Testing the type only: it would not catch handler dispatch or the `_`
-  throwing, or the `otherwise` fallback (see `src/index.test.ts`).
+  fallback (see `src/primitive.test.ts`).
-The runner is `node --test --strip-types "src/**/*.test.ts"` and the tiers are in
+The runner is `node --test --strip-types "src/**/*.test.ts"` and the tiers are
 in
 [CONTRIBUTING.md § Development commands](../CONTRIBUTING.md#development-commands).
 `c8` uses V8 coverage, so the `--strip-types` source is instrumented without a
 build step, and the runner relies on the `.ts` import-extension convention (see
@@ -63,11 +64,111 @@ separated by a blank line; an empty block drops its label.
 - Unlabeled ordering (bare blank lines): the seams still have to be found by
  reading; the labels cost nothing.
 ## Test helpers
 The rule is enforced by `import/no-relative-parent-imports`; this section records
 why the mechanism is shaped like this.
 #### Decision (2026-09)
 A shared test helper — code that scattered `*.test.ts` files import to do their
 testing — lives under `src/util/__tests__/` and is addressed by the
 `#test-utils/…` self-reference (`package.json#imports`:
 `"#test-utils/*": "./src/util/__tests__/*"`), never by a relative path:
 ```ts
 import { LspSession } from "#test-utils/lsp-completion.ts";
 ```
 #### Why
 - The lint rule bans upward (`../`) imports, and a cross-cutting helper can
  always be placed above _some_ scattered consumer, wherever it goes. Name
  beats path: a `#test-utils/…` specifier has no direction, so the rule never
  fires and file moves only touch the one mapping in `package.json`.
 - `#…` is Node's reserved prefix for _private_ subpath imports: publishing
  `package.json` leaks nothing and resolves nothing for consumers.
 - `__tests__` as the folder name is not about tests living there; it is the
  directory pattern `tsconfig.build.json` already excludes, so a helper can
  never be emitted into `dist/` and shipped by accident.
 - Node's own resolver handles `#…` under `--strip-types`, and `tsc` resolves it
  via the same `imports` field — one mechanism for runtime and type gate, no
  loader needed.
 - The helper uses `node:` builtins (it drives a language server), so
  `import/no-nodejs-modules` is off for `src/util/__tests__/**` in
  `.oxlintrc.json` — the same exception the `scripts/**` scope carries.
 - Helpers carry no library coupling: their tests probe in-memory documents
  whose contextual types are written inline, so only the helper's own contract
  (marker handling, position, label extraction) is under test. A test that
  asserts a _matcher's_ popup belongs with the matcher.
 #### Rejected
 - A helper beside the tests (`src/util/test.ts`, flat `src/`): composes only
  while `src/` stays flat; the first nested test reaching it reintroduces the
  banned upward import.
 - Bare `~/…` specifier: not valid in `imports` (keys must start with `#`) —
  resolution fails at runtime with `ERR_MODULE_NOT_FOUND`. A `#~/…` “home”
  shorthand was dropped in review; `#test-utils/…` states what it is.
 - tsconfig `paths` alias: resolves for `tsc` but not for plain
  `node --test --strip-types` (no loader hook), breaking the fast tier.
 - Turning `import/no-relative-parent-imports` off for test files: the rule
  still guards non-test helpers importing each other, and the exemption is
  only needed for the one specifier the mapping already solves cleanly.
 ## Autocomplete
 #### Decision (2026-09)
 Completion is verified by driving the repo's own language server
 (`tsc --lsp --stdio`, the same server pi's LSP extension talks to) through
 the test helper `#test-utils/lsp-completion.ts`
 (`src/util/__tests__/lsp-completion.ts`), not through the type system:
 ```sh
 node --strip-types src/util/__tests__/lsp-completion.ts <file> [<marker>]
 ```
 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;
 the CLI is for manual inspection.
 #### Why
 - Completion is a contextual-type property: it depends on which overload
  signature TypeScript picks for the object literal, and no type-level assertion
  observes that.
 - `Parameters<typeof factory>[0]` resolves only the _last_ overload, so it is
  not the popup's contextual type either — see
  [library.md § Matcher shape](./library.md#matcher-shape).
 - The server is the only ground truth; the script reproduces what the editor
  shows.
 #### Rejected
 - **`expect-type` would not work**: there is no operator for “the popup offers
  these labels”. `toExtend` / `toEqualTypeOf` test assignability and cannot say
  which overload supplied the contextual type.
 - **Checking by hand in the editor**: not reproducible in review or by an agent.
 - **`@ts-expect-error` at a completion position**: it asserts the absence of a
  compile error, not the presence of specific labels.
 #### Known issue
 - Each test spawns its own `tsc` server so the tests share no state and pass in
  any order; the file is an integration test (~1.6 s) that needs `node_modules`.
  `didOpen` is handled in order before the completion request, so no settle
  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.
 ## Known issues
 - The type-aware linter misidentifies `expectTypeOf()` as a floating promise, so
-  test files that use it (`src/index.test.ts`, `src/primitive.test.ts`) carry a
+  test files that use it (`src/primitive.test.ts`) carry a file-level
-  file-level `oxlint-disable
+  `oxlint-disable typescript/no-floating-promises` with an explanatory comment.
-typescript/no-floating-promises` with an explanatory comment. It is a known
+  It is a known false positive, not a rule worth disabling project-wide (see
  false positive, not a rule worth disabling project-wide (see
  [tooling.md § oxlint-disable directives live next to the code](./tooling.md#oxlint-disable-directives-live-next-to-the-code)).
@@ -24,6 +24,8 @@ in [package.json](../package.json).
 - **@spences10/pi-lsp** — read-only LSP code intelligence for AI agents
  (project-local `.pi/settings.json`); talks to this repo's TypeScript 7 via
  `tsc --lsp --stdio`.
 - **vscode-languageserver-protocol** — LSP client and protocol types for the
  autocomplete test helper (`src/util/__tests__/lsp-completion.ts`).
 When each runs is in
 [CONTRIBUTING.md § Feedback tiers](../CONTRIBUTING.md#feedback-tiers).
@@ -105,8 +107,8 @@ Type-aware oxlint is enabled via `options.typeAware: true` in `.oxlintrc.json`
 #### Decision (2026-09)
 A type-aware rule that false-positives is silenced with a source-level
-`oxlint-disable` directive (see `src/pattern.ts`, `src/match.ts`,
+`oxlint-disable` directive (see `src/primitive.ts`,
-`src/index.test.ts`), not by turning the rule off in `.oxlintrc.json`.
+`src/primitive.test.ts`), not by turning the rule off in `.oxlintrc.json`.
 #### Why
@@ -247,6 +249,38 @@ project.
 - The same script works by hand (whole project) and staged (scoped), so there is
  no second command to maintain.
 ## Language server tooling
 ### `vscode-languageserver-protocol` backs the autocomplete helper
 #### Decision (2026-09)
 The autocomplete helper (`src/util/__tests__/lsp-completion.ts`) drives
 `tsc --lsp --stdio` through `vscode-languageserver-protocol`'s
 `createMessageConnection` and its typed request / notification objects, instead
 of a hand-rolled JSON-RPC client.
 #### Why
 - Framing, `Content-Length` parsing, the pending-request map and server-request
  dispatch are protocol plumbing the helper only reimplemented; the official
  client owns them and tolerates the server's `string | number` ids.
 - `InitializeRequest`, `CompletionRequest`, `DidOpenTextDocumentNotification`,
  … carry their parameter and result types, so `CompletionList` / `CompletionItem`
  replace the helper's ad-hoc shape guards.
 - The `./node` entry re-exports `vscode-jsonrpc/node`, so one devDependency
  supplies both the transport and the protocol types. It is test-only and never
  ships (`files` publishes `dist/` only).
 #### Rejected
 - `vscode-languageclient`: the editor-side client with a full feature registry
  — far more than a test helper needs.
 - Generic JSON-RPC (`jsonrpc-lite`, `jayson`): still no LSP types, so they
  replace framing only and leave the typed protocol surface unimplemented.
 - Keeping the hand-rolled client: the low-level shape is the maintenance cost
  the helper exists to remove, and it must be re-audited against the server.
 ## Editor and agent tooling
 ### VSCode integration
@@ -1,12 +1,12 @@
 {
    "name": "tiny-pattern-ts",
-    "version": "0.1.8",
+    "version": "0.4.0",
    "lockfileVersion": 3,
    "requires": true,
    "packages": {
        "": {
            "name": "tiny-pattern-ts",
-            "version": "0.1.8",
+            "version": "0.4.0",
            "license": "MIT",
            "dependencies": {
                "type-fest": "^5.9.0"
@@ -27,7 +27,8 @@
                "oxlint": "^1.83.0",
                "oxlint-tsgolint": "^7.0.2001",
                "publint": "^0.3.24",
-                "typescript": "^7.0.2"
+                "typescript": "^7.0.2",
                "vscode-languageserver-protocol": "^3.18.3"
            },
            "engines": {
                "node": ">=26"
@@ -4822,6 +4823,27 @@
                "node": "^14.17.0 || ^16.13.0 || >=18.0.0"
            }
        },
        "node_modules/vscode-jsonrpc": {
            "version": "9.0.2",
            "resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-9.0.2.tgz",
            "integrity": "sha512-SbQSV9yRemARxeXw6LU5sS6Zq0e9/DgCCX5yelH263ZQWukbTk8EF8fjTrr1dziasf4GwlJbvTwFnTrnQFWZXQ==",
            "dev": true,
            "license": "MIT",
            "engines": {
                "node": ">=14.0.0"
            }
        },
        "node_modules/vscode-languageserver-protocol": {
            "version": "3.18.3",
            "resolved": "https://registry.npmjs.org/vscode-languageserver-protocol/-/vscode-languageserver-protocol-3.18.3.tgz",
            "integrity": "sha512-DF49+WeV5py4zO5hhobp60jjsDSK0lAqA0OuKBLBvp423HPWQcCbhZz3JgyfIewsEz2f8U+X75xNIFHdiXZm2w==",
            "dev": true,
            "license": "MIT",
            "dependencies": {
                "vscode-jsonrpc": "9.0.2",
                "vscode-languageserver-types": "3.18.3"
            }
        },
        "node_modules/vscode-languageserver-textdocument": {
            "version": "1.0.14",
            "resolved": "https://registry.npmjs.org/vscode-languageserver-textdocument/-/vscode-languageserver-textdocument-1.0.14.tgz",
@@ -4829,6 +4851,13 @@
            "dev": true,
            "license": "MIT"
        },
        "node_modules/vscode-languageserver-types": {
            "version": "3.18.3",
            "resolved": "https://registry.npmjs.org/vscode-languageserver-types/-/vscode-languageserver-types-3.18.3.tgz",
            "integrity": "sha512-XIlzJ7Qp/jzSI1ds7/FwPAWrPeTZA7pAtlW4hdJ1J6xXWJL6dR9QYnDhJOdLzdKhUQ5Mm6mvUMw+3DcOQQasPw==",
            "dev": true,
            "license": "MIT"
        },
        "node_modules/vscode-uri": {
            "version": "3.2.0",
            "resolved": "https://registry.npmjs.org/vscode-uri/-/vscode-uri-3.2.0.tgz",
@@ -1,6 +1,6 @@
 {
    "name": "tiny-pattern-ts",
-    "version": "0.1.8",
+    "version": "0.4.0",
    "description": "Pattern matching for TypeScript/ESM environments (F#-style, not regex)",
    "keywords": [
        "adt",
@@ -27,6 +27,9 @@
    ],
    "type": "module",
    "sideEffects": false,
    "imports": {
        "#test-utils/*": "./src/util/__tests__/*"
    },
    "exports": {
        ".": {
            "types": "./dist/index.d.ts",
@@ -84,7 +87,8 @@
        "oxlint": "^1.83.0",
        "oxlint-tsgolint": "^7.0.2001",
        "publint": "^0.3.24",
-        "typescript": "^7.0.2"
+        "typescript": "^7.0.2",
        "vscode-languageserver-protocol": "^3.18.3"
    },
    "engines": {
        "node": ">=26"
@@ -73,9 +73,9 @@ git show-ref --verify --quiet "refs/heads/${BASE}" || {
    exit 1
 }
-# Derive the remote rather than hardcoding it: this repo has `origin` (ssh) and
+# Derive the remote rather than hardcoding it: `main` tracks `origin` (ssh)
-# `origin_https`, and `main` tracks the latter — `git fetch origin main` would
+# here; a hardcoded name would check currency against a ref that may not
-# check currency against a ref that is never updated here.
+# exist on a differently configured clone.
 # `--quiet` echoes the unresolved `main@{upstream}` literal to stdout on
 # failure, so it cannot be paired with a `$(...) || fallback`; the non-quiet
 # form prints nothing on failure and the fallback runs.
@@ -1,71 +0,0 @@
 /* oxlint-disable typescript/no-floating-promises -- expectTypeOf() is a sync type-assertion library that the type-aware linter misidentifies as a promise */
 import { strict as assert } from "node:assert";
 import { test } from "node:test";
 import { expectTypeOf } from "expect-type";
 import { type Matcher, P, match } from "./index.ts";
 test("match returns a builder", () => {
    // Act
    const builder = match("x");
    // Assert
    expectTypeOf(builder).toHaveProperty("with");
    expectTypeOf(builder).toHaveProperty("exhaustive");
    expectTypeOf(builder).toHaveProperty("otherwise");
 });
 test("P.literal narrows to its literal type", () => {
    // Act
    const matcher = P.literal("yes");
    // Assert
    expectTypeOf(matcher).toExtend<Matcher<"yes">>();
    assert.equal(matcher.matches("yes"), true);
    assert.equal(matcher.matches("no"), false);
 });
 test("P.type narrows to the typeof target", () => {
    // Act
    const matcher = P.type<string>("string");
    // Assert
    expectTypeOf(matcher).toExtend<Matcher<string>>();
    assert.equal(matcher.matches("hi"), true);
    assert.equal(matcher.matches(42), false);
 });
 test("exhaustive() returns the union of handler return types", () => {
    // Act
    const result = match<"a" | "b">("a")
        .with(P.literal("a"), () => 1 as const)
        .with(P.literal("b"), () => "two" as const)
        .exhaustive();
    // Assert
    expectTypeOf(result).toEqualTypeOf<1 | "two">();
    assert.equal(result, 1);
 });
 test("otherwise() falls back when no case matches", () => {
    // Act
    const result = match<"x" | "y" | "z">("z")
        .with(P.literal("x"), (v): string => `got ${v}`)
        .otherwise((v): string => `fallback ${v}`);
    // Assert
    assert.equal(result, "fallback z");
 });
 test("exhaustive throws when no case matches", () => {
    // Assert
    assert.throws(
        () =>
            match<"a" | "b" | "c">("c")
                .with(P.literal("a"), () => "A")
                .with(P.literal("b"), () => "B")
                .exhaustive(),
        /no matching case/,
    );
 });
@@ -1,2 +1 @@
-export { match, P } from "./match.ts";
+export { getMatcher, getMatcherW } from "./primitive.ts";
 export type { Matcher, Pattern } from "./pattern.ts";
@@ -1,62 +0,0 @@
 import { P, type Matcher, type Pattern } from "./pattern.ts";
 type Cases<R> = readonly (readonly [Matcher<unknown>, (value: unknown) => R])[];
 interface MatchBuilder<T, R> {
    with<U extends T, V>(
        pattern: Matcher<U>,
        handler: (value: U) => V,
    ): MatchBuilder<T, R | V>;
    exhaustive(): R;
    otherwise(handler: (value: T) => R): R;
 }
 const buildMatch = <T, R>(value: T, cases: Cases<R>): MatchBuilder<T, R> => {
    const apply = (): R | undefined => {
        for (const [matcher, handler] of cases) {
            if (matcher.matches(value)) {
                return handler(value);
            }
        }
        return undefined;
    };
    const builder = {
        with<U extends T, V>(
            pattern: Matcher<U>,
            handler: (value: U) => V,
        ): MatchBuilder<T, R | V> {
            const nextCases: Cases<R | V> = [
                ...cases,
                // oxlint-disable-next-line typescript/no-unsafe-type-assertion
                [pattern, handler as (value: unknown) => R | V],
            ];
            return buildMatch(value, nextCases);
        },
        exhaustive(): R {
            const result = apply();
            if (result === undefined) {
                throw new Error(
                    "tiny-pattern-ts: match.exhaustive() called with no matching case",
                );
            }
            return result;
        },
        otherwise(handler: (value: T) => R): R {
            for (const [matcher, run] of cases) {
                if (matcher.matches(value)) {
                    return run(value);
                }
            }
            return handler(value);
        },
    };
    return builder;
 };
 export const match = <T>(value: T): MatchBuilder<T, never> =>
    buildMatch<T, never>(value, []);
 export type { Matcher, Pattern };
 export { P };
@@ -1,105 +0,0 @@
 /**
 * Pattern matching primitives. Each constructor returns a lightweight
 * matcher object whose `matches` method returns a type guard.
 */
 export interface Matcher<T> {
    readonly matches: (value: unknown) => value is T;
 }
 const literalMatcher = <
    const L extends string | number | boolean | null | undefined,
 >(
    value: L,
 ): Matcher<L> => ({
    matches: (candidate): candidate is L => candidate === value,
 });
 const typeMatcher = <T>(
        type:
            | "string"
            | "number"
            | "boolean"
            | "bigint"
            | "symbol"
            | "undefined"
            | "object"
            | "function",
    ): Matcher<T> => {
        const matches = (value: unknown): value is T => {
            if (type === "undefined") {
                return value === undefined;
            }
            if (type === "object") {
                return (
                    (typeof value === "object" && value !== null) ||
                    typeof value === "function"
                );
            }
            return typeof value === type;
        };
        return { matches };
    },
    whenMatcher = <T>(
        predicate: (value: unknown) => value is T,
    ): Matcher<T> => ({
        matches: predicate,
    }),
    whenMatcherAny = <T>(
        predicate: (value: unknown) => boolean,
    ): Matcher<T> => ({
        matches: (value: unknown): value is T => predicate(value),
    }),
    isNestedMatcher = (expected: unknown): expected is Matcher<unknown> =>
        typeof expected === "object" &&
        expected !== null &&
        "matches" in expected,
    // oxlint-disable-next-line typescript/no-unnecessary-type-parameters
    keysMatch = <S extends object>(shape: S, candidate: object): boolean => {
        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
        for (const key of Object.keys(shape) as (keyof S)[]) {
            if (!(key in candidate)) {
                return false;
            }
            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
            const expected = shape[key],
                // oxlint-disable-next-line typescript/no-unsafe-type-assertion
                actual = candidate[key as keyof object];
            if (isNestedMatcher(expected)) {
                if (!expected.matches(actual)) {
                    return false;
                }
            } else if (actual !== expected) {
                return false;
            }
        }
        return true;
    },
    structuralMatcher = <S extends object, T extends S>(
        shape: S,
        refine?: (value: S) => value is T,
    ): Matcher<T> => ({
        matches: (value: unknown): value is T => {
            if (typeof value !== "object" || value === null) {
                return false;
            }
            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
            const candidate = value as S;
            if (!keysMatch(shape, candidate)) {
                return false;
            }
            if (refine && !refine(candidate)) {
                return false;
            }
            return true;
        },
    });
 export const P = {
    literal: literalMatcher,
    type: typeMatcher,
    when: whenMatcher,
    any: whenMatcherAny,
    shape: structuralMatcher,
 } as const;
 export type Pattern<T> = Matcher<T>;
@@ -1,50 +1,49 @@
 /* oxlint-disable typescript/no-floating-promises -- expectTypeOf() is a sync type-assertion library that the type-aware linter misidentifies as a promise */
 import { strict as assert } from "node:assert";
 import path from "node:path";
 import { test } from "node:test";
 import { expectTypeOf } from "expect-type";
 import {
-    getPrimitiveUnionMatcher,
+    type CompletionTarget,
-    getPrimitiveUnionMatcherPartial,
+    LspSession,
-    getPrimitiveUnionMatcherPartialW,
+} from "#test-utils/lsp-completion.ts";
-    getPrimitiveUnionMatcherW,
+
-} from "./primitive.ts";
+import { getMatcher, getMatcherW } from "./primitive.ts";
 // ============================================================================
-// API: getPrimitiveUnionMatcherW — ✔️ Exhaustive / ❌ ReturnsStrict
+// API: getMatcher — ✔️ Exhaustive / ✔️ ReturnsStrict
 // ============================================================================
-test("getPrimitiveUnionMatcherW requires every literal key", () => {
+test("getMatcher: exhaustive pattern infers one common return type", () => {
    // Arrange
-    const factory = getPrimitiveUnionMatcherW<"a" | "b">();
+    const factory = getMatcher<"a" | "b">();
    // Act
    const matcher = factory({
        a: (s) => {
            expectTypeOf(s).toEqualTypeOf<"a">();
-            return 1 as const;
+            return 1;
        },
        b: (s) => {
            expectTypeOf(s).toEqualTypeOf<"b">();
-            return "two" as const;
+            return 2;
        },
    });
    // Assert
-    // ❌ ReturnsStrict: mixed handler returns widen to their union.
+    // ✔️ ReturnsStrict: R is the best common return type, not a widening union.
-    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => 1 | "two">();
+    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => number>();
-    // A pattern missing a key must not satisfy the parameter type.
+    // ❌ a value outside T must not be accepted by the matcher
-    expectTypeOf<{
+    expectTypeOf<"c">().not.toExtend<Parameters<typeof matcher>[0]>();
        a: () => number;
    }>().not.toExtend<Parameters<typeof factory>[0]>();
    assert.equal(matcher("a"), 1);
-    assert.equal(matcher("b"), "two");
+    assert.equal(matcher("b"), 2);
 });
-test("getPrimitiveUnionMatcherW dispatches on numeric literal keys", () => {
+test("getMatcher: dispatches on numeric literal keys", () => {
    // Arrange
-    const factory = getPrimitiveUnionMatcherW<1 | 2>();
+    const factory = getMatcher<1 | 2>();
    // Act
    const matcher = factory({
@@ -64,9 +63,132 @@ test("getPrimitiveUnionMatcherW dispatches on numeric literal keys", () => {
    assert.equal(matcher(2), 20);
 });
-test("getPrimitiveUnionMatcherW dispatches on mixed string and numeric keys", () => {
+test("getMatcher: dispatches on mixed string and numeric keys", () => {
    // Arrange
-    const factory = getPrimitiveUnionMatcherW<"a" | "b" | 1 | 2>();
+    const factory = getMatcher<"a" | "b" | 1 | 2>();
    // Act
    const matcher = factory({
        a: (s) => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return 1;
        },
        b: (s) => {
            expectTypeOf(s).toEqualTypeOf<"b">();
            return 2;
        },
        1: (n) => {
            expectTypeOf(n).toEqualTypeOf<1>();
            return 10;
        },
        2: (n) => {
            expectTypeOf(n).toEqualTypeOf<2>();
            return 20;
        },
    });
    // Assert
    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | 1 | 2) => number>();
    assert.equal(matcher("a"), 1);
    assert.equal(matcher("b"), 2);
    assert.equal(matcher(1), 10);
    assert.equal(matcher(2), 20);
 });
 // ============================================================================
 // API: getMatcher — ❌ Exhaustive (fallback) / ✔️ ReturnsStrict
 // ============================================================================
 test("getMatcher: a `_` fallback receives the unhandled keys", () => {
    // Arrange
    const factory = getMatcher<"a" | "b" | "c">();
    // Act
    const matcher = factory(
        {
            a: (s) => {
                expectTypeOf(s).toEqualTypeOf<"a">();
                return 1 as const;
            },
        },
        (s) => {
            // The fallback sees only the keys `a` did not handle.
            expectTypeOf(s).toEqualTypeOf<"b" | "c">();
            return 2 as const;
        },
    );
    // Assert
    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | "c") => 1 | 2>();
    // ❌ a value outside T must not be accepted by the matcher
    expectTypeOf<"d">().not.toExtend<Parameters<typeof matcher>[0]>();
    assert.equal(matcher("a"), 1);
    assert.equal(matcher("b"), 2);
    assert.equal(matcher("c"), 2);
 });
 test("getMatcher: a `_` fallback routes mixed string and numeric gaps", () => {
    // Arrange
    const factory = getMatcher<"a" | "b" | 1 | 2>();
    // Act
    const matcher = factory(
        {
            a: (s) => {
                expectTypeOf(s).toEqualTypeOf<"a">();
                return "A";
            },
            1: (n) => {
                expectTypeOf(n).toEqualTypeOf<1>();
                return "one";
            },
        },
        (s) => {
            expectTypeOf(s).toEqualTypeOf<"b" | 2>();
            return "fallback";
        },
    );
    // Assert
    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | 1 | 2) => string>();
    assert.equal(matcher("a"), "A");
    assert.equal(matcher("b"), "fallback");
    assert.equal(matcher(1), "one");
    assert.equal(matcher(2), "fallback");
 });
 // ============================================================================
 // API: getMatcherW — ✔️ Exhaustive / ❌ ReturnsStrict
 // ============================================================================
 test("getMatcherW: exhaustive pattern widens to the union of handler returns", () => {
    // Arrange
    const factory = getMatcherW<"x" | "y">();
    // Act
    const matcher = factory({
        x: (s) => {
            expectTypeOf(s).toEqualTypeOf<"x">();
            return 1 as const;
        },
        y: (s) => {
            expectTypeOf(s).toEqualTypeOf<"y">();
            return "two" as const;
        },
    });
    // Assert
    // ❌ ReturnsStrict: mixed handler returns widen to their union.
    expectTypeOf(matcher).toEqualTypeOf<(shape: "x" | "y") => 1 | "two">();
    // ❌ a value outside T must not be accepted by the matcher
    expectTypeOf<"z">().not.toExtend<Parameters<typeof matcher>[0]>();
    assert.equal(matcher("x"), 1);
    assert.equal(matcher("y"), "two");
 });
 test("getMatcherW: dispatches on mixed string and numeric keys", () => {
    // Arrange
    const factory = getMatcherW<"a" | "b" | 1 | 2>();
    // Act
    const matcher = factory({
@@ -99,214 +221,46 @@ test("getPrimitiveUnionMatcherW dispatches on mixed string and numeric keys", ()
 });
 // ============================================================================
-// API: getPrimitiveUnionMatcher — ✔️ Exhaustive / ✔️ ReturnsStrict
+// API: getMatcherW — ❌ Exhaustive (fallback) / ❌ ReturnsStrict
 // ============================================================================
-test("getPrimitiveUnionMatcher infers a single return type shared by all handlers", () => {
+test("getMatcherW: a `_` fallback widens gaps into the union", () => {
    // Arrange
-    const factory = getPrimitiveUnionMatcher<"a" | "b">();
+    const factory = getMatcherW<"x" | "y" | "z">();
    // Act
-    const matcher = factory({
+    const matcher = factory(
-        a: (s): number => {
+        {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return 1;
        },
        b: (s): 1 | 2 => {
            expectTypeOf(s).toEqualTypeOf<"b">();
            return 2;
        },
    });
    // Assert
    // ✔️ ReturnsStrict: R is the best common return type, not a widening union.
    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => number>();
    assert.equal(matcher("a"), 1);
    assert.equal(matcher("b"), 2);
 });
 test("getPrimitiveUnionMatcher handlers receive the matched literal", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcher<"on" | "off">();
    // Act
    const matcher = factory({
        on: (s) => {
            expectTypeOf(s).toEqualTypeOf<"on">();
            return `handler ${s}`;
        },
        off: (s) => {
            expectTypeOf(s).toEqualTypeOf<"off">();
            return `handler ${s}`;
        },
    });
    // Assert
    expectTypeOf(matcher).toEqualTypeOf<(shape: "on" | "off") => string>();
    assert.equal(matcher("on"), "handler on");
    assert.equal(matcher("off"), "handler off");
 });
 test("getPrimitiveUnionMatcher infers one return type across mixed string and numeric keys", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcher<"a" | "b" | 1 | 2>();
    // Act
    const matcher = factory({
        a: (s): number => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return 1;
        },
        b: (s): 1 | 2 => {
            expectTypeOf(s).toEqualTypeOf<"b">();
            return 2;
        },
        1: (n): number => {
            expectTypeOf(n).toEqualTypeOf<1>();
            return 10;
        },
        2: (n): number => {
            expectTypeOf(n).toEqualTypeOf<2>();
            return 20;
        },
    });
    // Assert
    // ✔️ ReturnsStrict: R is the best common return type, not a widening union.
    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | 1 | 2) => number>();
    assert.equal(matcher("a"), 1);
    assert.equal(matcher("b"), 2);
    assert.equal(matcher(1), 10);
    assert.equal(matcher(2), 20);
 });
 // ============================================================================
 // API: getPrimitiveUnionMatcherPartial — ❌ Exhaustive / ✔️ ReturnsStrict
 // ============================================================================
 test("getPrimitiveUnionMatcherPartial routes shapes without a handler to _", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcherPartial<"a" | "b" | "c">();
    // Two keys, so `{ a }` lacks only the `_` fallback, nothing else.
    const sparseFactory = getPrimitiveUnionMatcherPartial<"a" | "b">();
    // Act
    const matcher = factory({
        a: (s): 1 | 2 => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return 1;
        },
        _: (s): 1 | 2 => {
            // The fallback sees the whole union, not a single literal.
            expectTypeOf(s).toEqualTypeOf<"a" | "b" | "c">();
            return 2;
        },
    });
    // Assert
    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | "c") => 1 | 2>();
    // ❌ Exhaustive: gaps are allowed, but only with a `_` fallback.
    expectTypeOf<{
        a: () => number;
    }>().not.toExtend<Parameters<typeof sparseFactory>[0]>();
    assert.equal(matcher("a"), 1);
    assert.equal(matcher("b"), 2);
    assert.equal(matcher("c"), 2);
 });
 test("getPrimitiveUnionMatcherPartial also accepts an exhaustive pattern", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcherPartial<"a" | "b">();
    // Act
    const matcher = factory({
        a: (s) => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return "A";
        },
        b: (s) => {
            expectTypeOf(s).toEqualTypeOf<"b">();
            return "B";
        },
    });
    // Assert
    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => string>();
    assert.equal(matcher("a"), "A");
    assert.equal(matcher("b"), "B");
 });
 test("getPrimitiveUnionMatcherPartial routes mixed string and numeric keys, gaps go to _", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcherPartial<"a" | "b" | 1 | 2>();
    // Act
    const matcher = factory({
        a: (s): string => {
            expectTypeOf(s).toEqualTypeOf<"a">();
            return "A";
        },
        1: (n): string => {
            expectTypeOf(n).toEqualTypeOf<1>();
            return "one";
        },
        _: (s): string => {
            // The fallback sees the whole union, not a single literal.
            expectTypeOf(s).toEqualTypeOf<"a" | "b" | 1 | 2>();
            return "fallback";
        },
    });
    // Assert
    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | 1 | 2) => string>();
    assert.equal(matcher("a"), "A");
    assert.equal(matcher("b"), "fallback");
    assert.equal(matcher(1), "one");
    assert.equal(matcher(2), "fallback");
 });
 // ============================================================================
 // API: getPrimitiveUnionMatcherPartialW — ❌ Exhaustive / ❌ ReturnsStrict
 // ============================================================================
 test("getPrimitiveUnionMatcherPartialW allows gaps and widens to the union of handler returns", () => {
    // Arrange
    const factory = getPrimitiveUnionMatcherPartialW<"x" | "y" | "z">();
    // Two keys, so `{ x }` lacks only the `_` fallback, nothing else.
    const sparseFactory = getPrimitiveUnionMatcherPartialW<"x" | "y">();
    // Act
    const matcher = factory({
            x: (s) => {
                expectTypeOf(s).toEqualTypeOf<"x">();
                return 1 as const;
            },
-        _: (s) => {
+        },
-            // The fallback sees the whole union, not a single literal.
+        (s) => {
-            expectTypeOf(s).toEqualTypeOf<"x" | "y" | "z">();
+            // The fallback sees only the keys `x` did not handle.
            expectTypeOf(s).toEqualTypeOf<"y" | "z">();
            return "fallback" as const;
        },
-    });
+    );
    // Assert
    expectTypeOf(matcher).toEqualTypeOf<
        (shape: "x" | "y" | "z") => 1 | "fallback"
    >();
-    // ❌ Exhaustive: gaps are allowed, but only with a `_` fallback.
+    // ❌ a value outside T must not be accepted by the matcher
-    expectTypeOf<{
+    expectTypeOf<"w">().not.toExtend<Parameters<typeof matcher>[0]>();
        x: () => number;
    }>().not.toExtend<Parameters<typeof sparseFactory>[0]>();
    assert.equal(matcher("x"), 1);
    assert.equal(matcher("y"), "fallback");
    assert.equal(matcher("z"), "fallback");
 });
-test("getPrimitiveUnionMatcherPartialW widens mixed string and numeric key returns to their union", () => {
+test("getMatcherW: a `_` fallback widens mixed string and numeric returns", () => {
    // Arrange
-    const factory = getPrimitiveUnionMatcherPartialW<"a" | "b" | 1 | 2>();
+    const factory = getMatcherW<"a" | "b" | 1 | 2>();
    // Act
-    const matcher = factory({
+    const matcher = factory(
        {
            a: (s) => {
                expectTypeOf(s).toEqualTypeOf<"a">();
                return "A" as const;
@@ -315,12 +269,12 @@ test("getPrimitiveUnionMatcherPartialW widens mixed string and numeric key retur
                expectTypeOf(n).toEqualTypeOf<1>();
                return 10 as const;
            },
-        _: (s) => {
+        },
-            // The fallback sees the whole union, not a single literal.
+        (s) => {
-            expectTypeOf(s).toEqualTypeOf<"a" | "b" | 1 | 2>();
+            expectTypeOf(s).toEqualTypeOf<"b" | 2>();
            return "fallback" as const;
        },
-    });
+    );
    // Assert
    // ❌ ReturnsStrict: mixed handler returns widen to their union.
@@ -333,25 +287,205 @@ test("getPrimitiveUnionMatcherPartialW widens mixed string and numeric key retur
    assert.equal(matcher(2), "fallback");
 });
-test("getPrimitiveUnionMatcherPartialW also accepts an exhaustive pattern", () => {
+// ============================================================================
 // Factory contracts — calls that must not compile
 // ============================================================================
 test("getMatcher factory rejects patterns outside its contract", () => {
    // Arrange
-    const factory = getPrimitiveUnionMatcherPartialW<"x" | "y">();
+    const factory = getMatcher<"a" | "b">();
    // Act / Assert — the calls below must not compile.
    // `Parameters<typeof factory>[0]` resolves only the *last* overload, so it
    // is not a sound "rejected" oracle (an accepted partial pattern does not
    // extend it either); the call sites are the oracle instead.
    factory({
        a: () => 1,
        b: () => 2,
        // @ts-expect-error `c` is not part of the universe `"a" | "b"`
        c: () => 3,
    });
    // @ts-expect-error a gap without a `_` fallback is not exhaustive
    factory({ a: () => 1 });
    // @ts-expect-error a `string` fallback does not fit the `number` handler
    factory({ a: () => 1 }, () => "x");
 });
 test("getMatcherW factory rejects patterns outside its contract", () => {
    // Arrange
    const factory = getMatcherW<"x" | "y">();
    // Act / Assert — the calls below must not compile
    factory({
        x: () => 1 as const,
        y: () => 2 as const,
        // @ts-expect-error `z` is not part of the universe `"x" | "y"`
        z: () => 3 as const,
    });
    // @ts-expect-error a gap without a `_` fallback is not exhaustive
    factory({ x: () => 1 as const });
 });
 // ============================================================================
 // Dispatch — runtime behavior
 // ============================================================================
 test("getMatcher: an unhandled shape throws without a fallback", () => {
    // Arrange — an open universe types its handler map as an index signature,
    // so the type system cannot prove the runtime map is exhaustive.
    const handlers: Record<string, () => number> = { a: () => 1 };
    const matcher = getMatcher<string>()(handlers);
    // Act / Assert
    assert.equal(matcher("a"), 1);
    assert.throws(() => matcher("b"), /Unhandled shape: b/);
 });
 // ============================================================================
 // Autocomplete — the language server is the oracle, not the type system
 // ============================================================================
 // Completion is a contextual-type property that the type system cannot observe,
 // so the cases below read the popup from the repo's language server (via the
 // test helper) rather than pairing `expectTypeOf` with `assert` — see
 // development/testing.md § Autocomplete. They probe the *matcher's* overloads,
 // which is why they live with the matcher and not with the helper.
 const REPO_ROOT = path.resolve(import.meta.dirname, "..");
 const UNIVERSE = `"a" | "b" | "c"`;
 // One session per probe: the tests share no language-server state (open
 // documents, project membership), so they pass in any order.
 interface LabelsProbe {
    readonly name: string;
    readonly factory: "getMatcher" | "getMatcherW";
    readonly body: string;
    readonly tail?: string;
 }
 const labelsFor = ({
    name,
    factory,
    body,
    tail = "",
 }: LabelsProbe): Promise<readonly string[]> => {
    const session = new LspSession(REPO_ROOT);
    const target: CompletionTarget = {
        file: `src/__autocomplete_${name}.ts`,
        source: [
            `import { ${factory} } from "./index.ts";`,
            `const m = ${factory}<${UNIVERSE}>()({`,
            body,
            `}${tail});`,
            "",
        ].join("\n"),
    };
    return session
        .completionLabelsAt(target)
        .then((result) => result.labels)
        .finally(() => session.close());
 };
 test("autocomplete: an exhaustive pattern requires the universe", () => {
    // Arrange
    const name = "getMatcher_fresh";
    // Act
-    const matcher = factory({
+    const labels = labelsFor({
-        x: (s) => {
+        name,
-            expectTypeOf(s).toEqualTypeOf<"x">();
+        factory: "getMatcher",
-            return 1 as const;
+        body: "    /*COMPLETE*/",
        },
        y: (s) => {
            expectTypeOf(s).toEqualTypeOf<"y">();
            return "two" as const;
        },
    });
    // Assert
-    // ❌ ReturnsStrict: mixed handler returns widen to their union.
+    return labels.then((result) => {
-    expectTypeOf(matcher).toEqualTypeOf<(shape: "x" | "y") => 1 | "two">();
+        assert.deepEqual([...result], ["a", "b", "c"]);
-    assert.equal(matcher("x"), 1);
+    });
-    assert.equal(matcher("y"), "two");
+});
 test("autocomplete: handled keys drop out of the popup", () => {
    // Arrange
    const name = "getMatcher_after_key";
    // Act
    const labels = labelsFor({
        name,
        factory: "getMatcher",
        body: "    a: () => 1,\n    /*COMPLETE*/",
    });
    // Assert
    return labels.then((result) => {
        assert.deepEqual([...result], ["b", "c"]);
    });
 });
 test("autocomplete: a fallback makes the remaining keys optional", () => {
    // Arrange
    const name = "getMatcher_with_fallback";
    // Act
    const labels = labelsFor({
        name,
        factory: "getMatcher",
        body: "    /*COMPLETE*/",
        tail: ", () => 0",
    });
    // Assert
    return labels.then((result) => {
        assert.deepEqual([...result], ["a?", "b?", "c?"]);
    });
 });
 test("autocomplete: with a fallback, handled keys stay optional", () => {
    // Arrange
    const name = "getMatcher_with_fallback_after_key";
    // Act
    const labels = labelsFor({
        name,
        factory: "getMatcher",
        body: "    a: () => 1,\n    /*COMPLETE*/",
        tail: ", () => 0",
    });
    // Assert
    return labels.then((result) => {
        assert.deepEqual([...result], ["b?", "c?"]);
    });
 });
 test("autocomplete: `getMatcherW` offers the same popup as `getMatcher`", () => {
    // Arrange
    const name = "getMatcherW_fresh";
    // Act
    const labels = labelsFor({
        name,
        factory: "getMatcherW",
        body: "    /*COMPLETE*/",
    });
    // Assert
    return labels.then((result) => {
        assert.deepEqual([...result], ["a", "b", "c"]);
    });
 });
 test("autocomplete: `getMatcherW` also offers optional keys with a fallback", () => {
    // Arrange
    const name = "getMatcherW_with_fallback";
    // Act
    const labels = labelsFor({
        name,
        factory: "getMatcherW",
        body: "    /*COMPLETE*/",
        tail: ", () => 0",
    });
    // Assert
    return labels.then((result) => {
        assert.deepEqual([...result], ["a?", "b?", "c?"]);
    });
 });
@@ -1,71 +1,75 @@
-import type { Simplify, ValueOf } from "type-fest";
+import type { Exact, ValueOf } from "type-fest";
 type UnaryFn<T, R> = (shape: T) => R;
-// ============================================================================
+// `Extract` drops optional handlers (`undefined`) so `PatternReturns` also works
-// ✔️ Exhaustive
+// when `P`'s constraint has optional keys.
-// ❌ ReturnsStrict
+type PatternReturns<P> = ReturnType<
-// ============================================================================
+    Extract<ValueOf<P>, (...args: never[]) => unknown>
-type PatternPrimitiveUnion<R, T extends string | number> = {
+>;
    [K in T]: UnaryFn<K, R>;
 };
-type PatternReturns<
+type Handlers<T extends string | number, R> = { [K in T]: UnaryFn<K, R> };
    P extends Record<string | number, UnaryFn<never, unknown>>,
 > = ReturnType<ValueOf<P>>;
-export const getPrimitiveUnionMatcherW: <T extends string | number>() => <
+// The fallback is a *second argument*, not a property of the handler map,
-    P extends PatternPrimitiveUnion<unknown, T>,
+// because its parameter is the remainder `Exclude<T, keyof Handled>` and TypeScript
->(
+// fixes a property's contextual type before it infers its sibling keys. A later
-    pattern: Simplify<P>,
+// argument, by contrast, is contextually typed from inference on an earlier
-) => UnaryFn<T, PatternReturns<P>> = () => (pattern) => (shape) =>
+// one, so the split is what makes the remainder expressible at all.
-    // Rewrite not to use any is possible, was evaluated and solutions were
+// See development/library.md.
-    // more complex than the current solution.
+type Fallback<T extends string | number, Handled, R> = UnaryFn<
    Exclude<T, keyof Handled>,
    R
 >;
-    // oxlint-disable-next-line typescript/no-explicit-any typescript/no-unsafe-type-assertion
+// TypeScript does not apply the excess-property check to a generic constraint,
-    (pattern[shape] as any)(shape);
+// so `Exact` restores it for the generic forms: a handler map can otherwise
 // carry keys outside `T`.
-// ============================================================================
+// oxlint-disable typescript/unified-signatures
-// ✔️ Exhaustive
+// Strict returns: one common `R`. Overload order is load-bearing:
-// ✔️ ReturnsStrict
+//   #1 Handlers (first) -> the exhaustive form and the autocomplete popup
-// ============================================================================
+//   #2 Fallback (last)  -> accepts a partial handler map plus a fallback
-export const getPrimitiveUnionMatcher: <T extends string | number>() => <R>(
+interface MatcherStrict<T extends string | number> {
-    pattern: Simplify<PatternPrimitiveUnion<R, T>>,
+    <R>(handlers: Handlers<T, R>): UnaryFn<T, R>;
-) => UnaryFn<T, R> = getPrimitiveUnionMatcherW;
+    <R, Handled extends Exact<Partial<Handlers<T, R>>, Handled>>(
        handlers: Handled & Partial<Handlers<T, R>>,
        fallback: Fallback<T, Handled, R>,
    ): UnaryFn<T, R>;
 }
 // oxlint-enable typescript/unified-signatures
-// ============================================================================
+// Widened returns: the union of every handler's return type. `P` is inferred
-// ❌ Exhaustive
+// from the whole handler map, whose closed constraint supplies the
-// ✔️ ReturnsStrict
+// contextual/autocomplete type.
-// ============================================================================
+// oxlint-disable typescript/unified-signatures
-type PatternPrimitiveUnionPartial<R, T extends string | number> =
+interface MatcherWidening<T extends string | number> {
-    | PatternPrimitiveUnion<R, T>
+    <P extends Exact<Handlers<T, unknown>, P>>(
-    | (Partial<PatternPrimitiveUnion<R, T>> & {
+        handlers: P,
-          _: UnaryFn<T, R>;
+    ): UnaryFn<T, PatternReturns<P>>;
-      });
+    <R, Handled extends Exact<Partial<Handlers<T, unknown>>, Handled>>(
        handlers: Handled,
        fallback: Fallback<T, Handled, R>,
    ): UnaryFn<T, PatternReturns<Handled> | R>;
 }
 // oxlint-enable typescript/unified-signatures
-export const getPrimitiveUnionMatcherPartial: <T extends string | number>() => <
+type HandlerMap = Record<string | number, UnaryFn<never, unknown> | undefined>;
    R,
 >(
    pattern: Simplify<PatternPrimitiveUnionPartial<R, T>>,
 ) => UnaryFn<T, R> = () => (pattern) => (shape) =>
    // Rewrite not to use any is possible, was evaluated and solutions were
    // more complex than the current solution.
-    // oxlint-disable-next-line typescript/no-explicit-any typescript/no-unsafe-type-assertion
+const dispatch =
-    (pattern[shape] ?? (pattern as any)["_"])(shape);
+    (handlers: HandlerMap, fallback?: UnaryFn<never, unknown>) =>
    (shape: string | number): unknown =>
        (
            handlers[shape] ??
            fallback ??
            (() => {
                throw new Error(`Unhandled shape: ${shape}`);
            })
        )(
            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
            shape as never,
        );
-// ============================================================================
+export const getMatcher = <T extends string | number>(): MatcherStrict<T> =>
-// ❌ Exhaustive
+    dispatch;
-// ❌ ReturnsStrict
+export const getMatcherW = <T extends string | number>(): MatcherWidening<T> =>
-// ============================================================================
+    dispatch;
 export const getPrimitiveUnionMatcherPartialW: <
    T extends string | number,
 >() => <P extends PatternPrimitiveUnionPartial<unknown, T>>(
    // `Simplify<P>` is the inference hook: callers infer `P` from the argument.
    // the second half pins the impl parameter's `R` to `PatternReturns<P>`.
    // that makes the `= getPrimitiveUnionMatcherPartial` assignment type-check.
    // neither half works alone.
    // without the witness the union's `_` arm demands `_ ∈ keyof P`.
    // without `Simplify<P>` the parameter types do not compare.
    pattern: Simplify<P> & PatternPrimitiveUnionPartial<PatternReturns<P>, T>,
 ) => UnaryFn<T, PatternReturns<P>> = getPrimitiveUnionMatcherPartial;
@@ -0,0 +1,148 @@
 /* oxlint-disable typescript/no-floating-promises -- expectTypeOf() is a sync type-assertion library that the type-aware linter misidentifies as a promise */
 import { strict as assert } from "node:assert";
 import path from "node:path";
 import { test } from "node:test";
 import { expectTypeOf } from "expect-type";
 import {
    type CompletionResult,
    type CompletionTarget,
    LspSession,
 } from "#test-utils/lsp-completion.ts";
 const REPO_ROOT = path.resolve(import.meta.dirname, "../../..");
 // The `#test-utils/*` self-reference (package.json#imports) is the one route
 // scattered test files take to reach test helpers; this pins that it resolves
 // and types without starting a language server
 // (development/testing.md § Test helpers).
 test("test-helper home: `#test-utils/…` resolves to the helper and types it", () => {
    // Arrange
    const target: CompletionTarget = {
        file: "src/util/__tests__/lsp-completion.ts",
        source: "",
    };
    // Assert — no session is constructed: the constructor spawns `tsc --lsp`,
    // so only the resolved values and their types are checked here.
    expectTypeOf(LspSession).toBeConstructibleWith("repo-root");
    expectTypeOf<CompletionResult>().toMatchTypeOf<{
        labels: readonly string[];
    }>();
    assert.equal(typeof LspSession, "function");
    assert.equal(target.file, "src/util/__tests__/lsp-completion.ts");
 });
 // The helper drives a language server, so its contract is asserted against the
 // server. Every document below is probed from memory and carries its
 // contextual type inline, so the helper is tested without the library's code.
 const probe = (source: string, marker?: string): Promise<CompletionResult> => {
    const session = new LspSession(REPO_ROOT);
    const target: CompletionTarget =
        marker === undefined
            ? { file: "src/__probe.ts", source }
            : { file: "src/__probe.ts", source, marker };
    return session.completionLabelsAt(target).finally(() => session.close());
 };
 const HANDLERS = [
    "type Handlers = { a: () => number; b: () => number; _?: () => number };",
    "declare const apply: (handlers: Handlers) => Handlers;",
 ];
 test("helper: a fresh object literal completes with its contextual keys", () => {
    // Arrange
    const source = [
        ...HANDLERS,
        "const done = apply({",
        "    /*COMPLETE*/",
        "});",
        "export { done };",
    ].join("\n");
    // Act
    const probed = probe(source);
    // Assert — the position is the marker's, which the helper strips
    expectTypeOf(probed).toEqualTypeOf<Promise<CompletionResult>>();
    return probed.then((result) => {
        assert.deepEqual(result.position, { line: 3, character: 4 });
        assert.deepEqual([...result.labels], ["_?", "a", "b"]);
    });
 });
 test("helper: a handled key drops out of the popup", () => {
    // Arrange
    const source = [
        ...HANDLERS,
        "const done = apply({",
        "    b: () => 1,",
        "    /*COMPLETE*/",
        "});",
        "export { done };",
    ].join("\n");
    // Act
    const probed = probe(source);
    // Assert
    expectTypeOf<CompletionResult["labels"]>().toEqualTypeOf<
        readonly string[]
    >();
    return probed.then((result) => {
        assert.deepEqual([...result.labels], ["_?", "a"]);
    });
 });
 test("helper: a custom marker is located at the line start", () => {
    // Arrange
    const source = [
        "type Handlers = { a: () => number; _?: () => number };",
        "declare const apply: (handlers: Handlers) => Handlers;",
        "const done = apply({",
        "@@@",
        "});",
        "export { done };",
    ].join("\n");
    // Act
    const probed = probe(source, "@@@");
    // Assert
    expectTypeOf(probed).resolves.toEqualTypeOf<CompletionResult>();
    return probed.then((result) => {
        assert.deepEqual(result.position, { line: 3, character: 0 });
        assert.deepEqual([...result.labels], ["_?", "a"]);
    });
 });
 test("helper: labels are read from the server, not from a pattern literal", () => {
    // Arrange
    const source = [
        'const text = "x";',
        "const upper = text./*COMPLETE*/;",
        "export { upper };",
    ].join("\n");
    // Act
    const probed = probe(source);
    // Assert
    expectTypeOf(probed).resolves.toHaveProperty("labels");
    return probed.then((result) => {
        assert.ok(result.labels.includes("toUpperCase"));
    });
 });
 test("helper: a source without the marker rejects", () => {
    // Arrange
    const source = "const text = 1;\nexport { text };\n";
    // Act
    const probed = probe(source);
    // Assert
    expectTypeOf(probed).resolves.toEqualTypeOf<CompletionResult>();
    return assert.rejects(probed, /marker not found/);
 });
@@ -0,0 +1,254 @@
 // oxlint-disable no-magic-numbers unicorn/no-null - tolerable here, this is a helper
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { pathToFileURL } from "node:url";
 import {
    type CompletionItem,
    type CompletionList,
    CompletionRequest,
    ConfigurationRequest,
    createMessageConnection,
    DidOpenTextDocumentNotification,
    InitializedNotification,
    InitializeRequest,
    type MessageConnection,
    ShutdownRequest,
    StreamMessageReader,
    StreamMessageWriter,
 } from "vscode-languageserver-protocol/node";
 /**
 * Print the completion labels TypeScript's language server offers at a marker
 * inside a source file.
 *
 * Usage: node --strip-types src/util/__tests__/lsp-completion.ts <file> [<marker>]
 *
 * The marker (default `DEFAULT_MARKER`, a `COMPLETE` block comment) is stripped
 * from the source before it is sent; the request position is where the marker
 * stood. Point it at a scratch file whose expected type is a matcher pattern to
 * inspect the popup.
 *
 * `LspSession` exposes the same probe to the test suite, so completion is
 * asserted against the server rather than the type system.
 *
 * Why a script and not a type assertion: completion is a contextual-type
 * property that `expect-type` cannot observe, and `Parameters<…>` resolves only
 * a single overload. The server is the only ground truth. See
 * development/testing.md § Autocomplete.
 */
 const DEFAULT_MARKER = "/*COMPLETE*/";
 const ARGV_PREFIX_LENGTH = 2;
 const EXIT_DELAY_MS = 200;
 const FAILURE_EXIT_CODE = 1;
 const USAGE = "usage: lsp-completion.ts <file> [<marker>]";
 export interface Position {
    readonly line: number;
    readonly character: number;
 }
 /** A document to probe: `source` carries `marker`, which is stripped. */
 export interface CompletionTarget {
    /** Path relative to the session's repo root; drives URI and resolution. */
    readonly file: string;
    readonly source: string;
    readonly marker?: string;
 }
 export interface CompletionResult {
    readonly position: Position;
    readonly labels: readonly string[];
 }
 const completionLabels = (
    result: CompletionItem[] | CompletionList | null,
 ): readonly string[] => {
    if (result === null) {
        return [];
    }
    const items = Array.isArray(result) ? result : result.items;
    return items
        .map((item) => item.label)
        .toSorted((left, right) => left.localeCompare(right));
 };
 const markerPosition = (source: string, marker: string): Position => {
    const index = source.indexOf(marker);
    if (index === -1) {
        throw new Error(`marker not found: ${marker}`);
    }
    const lines = source.slice(0, index).split("\n");
    const lineIndex = lines.length - 1;
    const line = lines[lineIndex];
    return { line: lineIndex, character: line === undefined ? 0 : line.length };
 };
 /**
 * One language server, initialized on first use, shared across probes. Callers
 * own the lifecycle and must `close()` it.
 */
 export class LspSession {
    readonly #child: ChildProcessWithoutNullStreams;
    readonly #connection: MessageConnection;
    readonly #repoRoot: string;
    #ready: Promise<void> | undefined;
    public constructor(repoRoot: string) {
        this.#repoRoot = repoRoot;
        this.#child = spawn(
            path.join(repoRoot, "node_modules", ".bin", "tsc"),
            ["--lsp", "--stdio"],
            { cwd: repoRoot },
        );
        this.#child.stderr.on("data", (chunk: Buffer) => {
            process.stderr.write(chunk);
        });
        this.#connection = createMessageConnection(
            new StreamMessageReader(this.#child.stdout),
            new StreamMessageWriter(this.#child.stdin),
        );
        // Server -> client requests the server waits on: answer so it proceeds.
        // `workspace/configuration` wants one reply per requested item; a
        // catch-all covers the rest (e.g. `client/registerCapability`).
        this.#connection.onRequest(ConfigurationRequest.type, ({ items }) =>
            items.map(() => null),
        );
        this.#connection.onRequest(() => null);
        this.#connection.listen();
    }
    public completionLabelsAt(
        target: CompletionTarget,
    ): Promise<CompletionResult> {
        return this.#ensureInitialized()
            .then(() => this.#open(target))
            .then(({ uri, position }) =>
                this.#connection
                    .sendRequest(CompletionRequest.type, {
                        textDocument: { uri },
                        position,
                        context: { triggerKind: 1 },
                    })
                    .then((result) => ({
                        position,
                        labels: completionLabels(result),
                    })),
            );
    }
    /** `shutdown` + close stdin, then kill the server; safe after a failed probe. */
    public close(): Promise<void> {
        return (
            this.#connection
                .sendRequest(ShutdownRequest.type)
                // The TS 7 Go server logs a bare `context canceled` to stderr
                // when it handles `exit`; EOF on stdin shuts it down cleanly
                // (exit 0, no output) instead.
                .then(() => {
                    this.#child.stdin.end();
                })
                .then(() => delay(EXIT_DELAY_MS))
                .finally(() => {
                    this.#connection.dispose();
                    this.#child.kill();
                })
        );
    }
    #ensureInitialized(): Promise<void> {
        this.#ready ??= this.#initialize();
        return this.#ready;
    }
    #initialize(): Promise<void> {
        return this.#connection
            .sendRequest(InitializeRequest.type, {
                processId: process.pid,
                rootUri: pathToFileURL(this.#repoRoot).href,
                workspaceFolders: [
                    { uri: pathToFileURL(this.#repoRoot).href, name: "repo" },
                ],
                capabilities: {
                    textDocument: {
                        completion: {
                            completionItem: { snippetSupport: false },
                        },
                        publishDiagnostics: {},
                    },
                },
            })
            .then(() =>
                this.#connection.sendNotification(
                    InitializedNotification.type,
                    {},
                ),
            );
    }
    #open(target: CompletionTarget): Promise<{
        readonly uri: string;
        readonly position: Position;
    }> {
        const absolute = path.resolve(this.#repoRoot, target.file);
        const marker = target.marker ?? DEFAULT_MARKER;
        const position = markerPosition(target.source, marker);
        const text = target.source.replace(marker, "");
        const uri = pathToFileURL(absolute).href;
        // The server handles `didOpen` in order before the completion request,
        // so no settle delay is needed.
        return this.#connection
            .sendNotification(DidOpenTextDocumentNotification.type, {
                textDocument: {
                    uri,
                    languageId: "typescript",
                    version: 1,
                    text,
                },
            })
            .then(() => ({ uri, position }));
    }
 }
 const main = (args: readonly string[]): Promise<void> => {
    const [file, markerArgument] = args;
    if (file === undefined) {
        process.stderr.write(`${USAGE}\n`);
        process.exitCode = FAILURE_EXIT_CODE;
        return Promise.resolve();
    }
    const repoRoot = path.resolve(import.meta.dirname, "../../..");
    const absolute = path.resolve(repoRoot, file);
    const source = fs.readFileSync(absolute, "utf8");
    const session = new LspSession(repoRoot);
    return session
        .completionLabelsAt({
            file,
            source,
            marker: markerArgument ?? DEFAULT_MARKER,
        })
        .then(({ position, labels }) => {
            process.stdout.write(
                `\n[${file}] completions @ ${position.line}:${position.character}:\n${labels.join(", ")}\n`,
            );
        })
        .finally(() => session.close());
 };
 const isEntryPoint = (): boolean => {
    const [entry] = process.argv.slice(1, 2);
    return entry !== undefined && import.meta.url === pathToFileURL(entry).href;
 };
 if (isEntryPoint()) {
    main(process.argv.slice(ARGV_PREFIX_LENGTH)).catch((error: unknown) => {
        process.stderr.write(
            `${error instanceof Error ? error.message : String(error)}\n`,
        );
        process.exitCode = FAILURE_EXIT_CODE;
    });
 }
Author	SHA1	Message	Date
tmu	7e7f716424	🚀 Release 0.4.0 CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 30s Details CI / maintain (push) Failing after 14s Details CI / publish (push) Failing after 16s Details	2026-09-20 21:46:32 +00:00
tmu	62db7de537	🔀 Merge chore/unify-task-branching into main	2026-09-20 21:44:21 +00:00
tmu	ff823b3cba	📝 Route every task through the full branching model Drop the leaf-task exception in AGENTS.md: a task without subtasks was implemented on the current branch, bypassing create:branch / create:finish. Every task now opens and closes a branch, so the clean-tree / current-main / green-baseline preconditions and the post-merge verify always apply.	2026-09-20 21:43:46 +00:00
tmu	eeb831b717	🔀 Merge feature/fallback-remainder into main CI / release-gate (push) Successful in 3s Details CI / build (push) Successful in 24s Details CI / publish (push) Skipped Details CI / maintain (push) Failing after 15s Details	2026-09-19 00:02:23 +00:00
tmu	ae7ffb6fa2	📝 Document the two-argument fallback Rewrite development/library.md around the new shape: the fallback is a second argument (so it can receive the remainder), `R` needs an inference site in the handler map, `Exact` restores the excess-property check, and the overload order is load-bearing. Record this branch's rejected alternatives (single-object `_`, currying, `this`/HKT, variance/`const`/`NoInfer`/brands) and the redundant- fallback known issue. Add the changelog note and check off the backlog task.	2026-09-18 23:52:47 +00:00
tmu	0d6a3f1b9b	✅ Cover the dispatch throw An open universe (`getMatcher<string>()`) types its handler map as an index signature, so a runtime map with fewer keys still satisfies the exhaustive overload. Calling the matcher with a missing shape reaches the dispatch guard and throws — no cast needed.	2026-09-18 23:48:59 +00:00
tmu	8615723c64	✅ Cover fallback autocompletes When a fallback argument is present, the second overload supplies the contextual type, so the handler map popup offers optional keys (`a? b? c?`) and handled keys stay optional (`b? c?`). The exhaustive one-argument popup is unchanged. Covered for both factories.	2026-09-18 23:44:51 +00:00
tmu	935e82d205	✅ Reject a mismatched strict fallback The factory-contract test now also covers a fallback whose return does not fit the common return of the handler map — a `number` handler with a `string` fallback — which `getMatcherW` accepts as `number \| string`.	2026-09-18 23:37:44 +00:00
tmu	c7223dbe69	🐛 Infer strict return from the handler map The fallback overload could not infer `R` from the handlers: `R` appeared only inside the `Exact` constraint, which is not an inference site, so with inferred handler params it collapsed to `unknown` and the matcher silently returned `UnaryFn<T, unknown>`. Adding `Partial<Handlers<T, R>>` to the handler parameter gives `R` an inference site, so the common return is inferred from the handlers and the fallback alike. Tests drop their explicit handler return annotations: real handlers are short and unannotated, and the common type is now inferred from them.	2026-09-18 23:33:34 +00:00
tmu	2d3577716d	✨ Narrow the fallback to unhandled keys The fallback is now the second factory argument — `(handlers, (s) => …)` — so its parameter is `Exclude<T, keyof handlers>`. A property's contextual type is fixed before TypeScript infers its sibling keys, so the remainder is not expressible while the fallback sits in the handler map; a later argument is contextually typed from inference on an earlier one. Both factories take the new shape; the tests and autocomplete probes follow. The generic overloads guard excess keys with type-fest's `Exact`, so the error lands on the offending property. A redundant fallback (a full handler map plus one) is still accepted — the guard for it does not survive inference and is left to its backlog task.	2026-09-18 23:08:16 +00:00
tmu	cc88c07961	🚀 Release 0.3.0 CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 29s Details CI / maintain (push) Failing after 15s Details CI / publish (push) Failing after 18s Details	2026-09-18 07:51:16 +00:00
tmu	62c37e6d89	🔀 Merge chore/protocol-backed-lsp-helper into main CI / release-gate (push) Successful in 3s Details CI / build (push) Successful in 24s Details CI / publish (push) Skipped Details CI / maintain (push) Failing after 14s Details	2026-09-18 07:45:22 +00:00
tmu	947eac8089	⏪ Revert the LSP notes in testing.md The protocol cross-link and the TS-internal shutdown-race explanation were too detailed for the category doc. The helper comment keeps a short, self-contained note on the stdin-EOF workaround.	2026-09-18 07:43:36 +00:00
tmu	eea2fbb17d	🚨 Silence helper oxlint warnings The completion helper is test-only (excluded from dist/), so the style-only no-magic-numbers and unicorn/no-null warnings are tolerable here. A file-level disable keeps them out of check:oxlint without touching the project config.	2026-09-18 07:38:13 +00:00
tmu	b278a153d3	📝 Check off the LSP shutdown bug Record the cause (Session.updateWatches raced against exit) and the stdin-EOF fix now that npm run verify is green with no context-canceled output.	2026-09-18 07:31:10 +00:00
tmu	8b73143740	🐛 Stop the LSP shutdown context-canceled log The TS 7 Go server races Session.updateWatches against the exit notification; handleExit returns io.EOF, the background context is cancelled, and the bare error is flushed to stderr once the outgoing queue closes (server.go / logger.go). Send shutdown and close stdin instead: EOF makes the server exit cleanly (code 0, no output), with the kill kept as a fallback. testing.md records the cause.	2026-09-18 07:31:04 +00:00
tmu	13497d1df8	📝 Check off the LSP helper task npm run verify is green: 23 tests pass, check:tsc, check:oxlint, check:oxfmt and check:cspell clean with the protocol-backed helper.	2026-09-18 07:17:19 +00:00
tmu	998c4bfd80	📝 Document the protocol-backed LSP helper Note that the autocomplete helper drives the server through vscode-languageserver-protocol, cross-link the tooling decision, and replace the obsolete string-id known issue with the benign context-canceled stderr the Go server emits on shutdown.	2026-09-18 07:16:45 +00:00
tmu	9f56d7ae8e	♻️ Back LSP helper with protocol library Replace the hand-rolled JSON-RPC client (framing, pending map, reply dispatch) with createMessageConnection and typed requests from vscode-languageserver-protocol. A catch-all onRequest answers the server requests the old client replied to, and CompletionList/CompletionItem replace the ad-hoc shape guards. Public LspSession API is unchanged.	2026-09-18 07:16:25 +00:00
tmu	94ccc16963	➕ Add the LSP protocol dependency The autocomplete helper drives tsc --lsp --stdio; vscode-languageserver-protocol supplies the transport (re-exported vscode-jsonrpc/node) and the typed LSP requests, replacing the hand-rolled JSON-RPC client. Record the choice and the rejected alternatives in tooling.md.	2026-09-18 07:14:45 +00:00
tmu	0b97632a7c	📝 Track protocol-backed LSP helper The autocomplete helper still carries a hand-rolled JSON-RPC client (Content-Length framing, a pending-request map, server-request replies). vscode-languageserver-protocol provides all of it plus typed requests, so track the move as a task with subtasks.	2026-09-18 07:14:18 +00:00
tmu	6f87c2f3b5	🔀 Merge chore/adopt-three-overload-matcher into main	2026-09-17 21:56:41 +00:00
tmu	88159296d4	📝 Drop the stale scripts test glob from testing.md No tests live under scripts/, and every test script (test, test:unit, test:ci, watch:test) globs only src/*/.test.ts, so state that. The scripts/** oxlint scope it was confused with still exists and carries the same import/no-nodejs-modules exception as the test-helper scope.	2026-09-17 21:55:41 +00:00
tmu	800c11139d	♻️ Name the matcher factories getMatcher / getMatcherW Drop the strict/widened aliases from src/index.ts so the factories are exported under their own names, and align the type tests, the autocomplete probe (which now imports the public surface from ./index.ts) and library.md with them. Also correct the widened-overload comment: the excess-property check does not apply to a generic P, so MatcherWidening's keyof guard — not the closed constraint — is what rejects keys outside T/_, as library.md already documented.	2026-09-17 21:48:54 +00:00
tmu	05fad0fcd6	📝 Record the autocomplete and matcher-design decisions The matcher is now two three-overload factories; library.md documents why the union merge, inferred universe, conditional RequireKeys and cases-first paths were rejected, and lists the two open issues (the fallback sees all of T; a redundant _ is still accepted). testing.md records the language server as the autocomplete oracle, and CONTRIBUTING points the exception at the matcher's own test file. The backlog marks the design-doc and autocomplete groundwork done alongside the adoption.	2026-09-17 20:59:28 +00:00
tmu	58d127da4e	✅ Test the LSP completion helper against the server The helper's own contract — marker handling, requested position, label extraction and the rejection when the marker is absent — is asserted against in-memory documents whose contextual types are written inline, so the helper is tested without coupling to the library's code.	2026-09-17 20:59:19 +00:00
tmu	165bd9e3df	♻️ Adopt the three-overload matcher strict/widened each take the exhaustive/fallback pattern shape in three overloads ordered ExhaustiveLoose -> Fallback -> Handlers. TypeScript reads the first overload for the object-literal popup (_?, a, b) and the last for the missing-key error, so autocomplete and the error message are tuned independently. The fallback is a pattern shape, not a factory, so the four getPrimitiveUnionMatcher* factories collapse to two. src/index.ts re-exports the two factories; the prototype scratch files that explored the alternatives are removed.	2026-09-17 20:59:09 +00:00
tmu	02634f41de	🔀 Merge chore/test-util-home into main	2026-09-17 13:33:41 +00:00
tmu	9da5b5dbf2	📝 Note the test-helper home in the changelog	2026-09-17 13:23:36 +00:00
tmu	dc57529f0f	📝 Correct the upstream claim in branch.sh `main` tracks `origin` (ssh); the comment claiming it tracked an https companion remote was stale.	2026-09-17 13:23:34 +00:00
tmu	484e5c8ca5	📝 Allow the floating-promise header in test files Agents may add the fixed file-level typescript/no-floating-promises oxlint-disable header at the top of a `*.test.ts` file — the expectTypeOf() misidentification is a documented false positive (development/testing.md § Known issues) and the await/void workarounds collide with eslint/no-void. Every other suppression stays the human last resort it was.	2026-09-17 13:23:32 +00:00
tmu	c51e32d6a6	📝 Record the test-helper home decision development/testing.md § Test helpers: why name beats path under import/no-relative-parent-imports, why the key needs `#`, why the `__tests__` folder name, and what was rejected (flat placement, tsconfig paths, rule exemptions).	2026-09-17 13:23:29 +00:00
tmu	9e5522c131	🚚 Home test helpers behind #test-utils/* src/util/__tests__/ holds shared test helpers, reached from anywhere in the source tree as `#test-utils/<name>.ts` through package.json#imports. A bare `~/…` is not a valid imports key — Node requires `#` — and a direction-free specifier keeps import/no-relative-parent-imports from ever firing. The `__tests__` folder name is the pattern tsconfig.build.json already excludes, so helpers can never ship. Lint scoping: import/no-nodejs-modules off for the folder (the probe spawns a language server) and typescript/promise-function-async off to match its promise-returning style. The LSP probe moves in from scripts/; a smoke test pins the specifier's resolution and typing without starting a server.	2026-09-17 13:23:27 +00:00
tmu	ee146ce350	🚀 Release 0.2.0 CI / release-gate (push) Successful in 3s Details CI / build (push) Successful in 24s Details CI / maintain (push) Failing after 15s Details CI / publish (push) Failing after 17s Details	2026-09-16 22:07:16 +00:00
tmu	33c6d9dc8d	🔀 Merge chore/remove-example-code into main	2026-09-16 22:06:17 +00:00
tmu	65e885989b	📝 Backlog the README walkthrough restoration The example-code removal stripped the synopsis and examples with the template modules; track bringing them back around the real API, with the previous section order recorded so its placement is not re-guessed.	2026-09-16 22:05:05 +00:00
tmu	16092350b8	📝 Check off example-code removal in backlog Note the finished work under [Unreleased] and mark the task and its subtasks done; retarget the v1.0 coverage tasks at the surviving primitive module.	2026-09-16 21:58:14 +00:00
tmu	a3eb6183af	🔥 Remove the match and pattern example modules They were the template's demo API, not the library's real surface. Drop them, their README walkthrough, and the tooling note that cited their disable directives, and point index.ts at the primitive matchers that remain.	2026-09-16 21:57:55 +00:00
tmu	ce3d618757	🔥 Remove the example index spec The spec only exercised the template's match/P example API. Removing it first lets the modules and exports it imports go next without leaving a dangling reference.	2026-09-16 21:57:42 +00:00
`@@ -1,2 +1 @@`
	`export { match, P } from "./match.ts";`	`export { getMatcher, getMatcherW } from "./primitive.ts";`
	`export type { Matcher, Pattern } from "./pattern.ts";`