🚀 Release 0.3.0

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.

.gitignore

@@ -10,5 +10,6 @@ coverage
 !.vscode/extensions.json
 !.vscode/settings.json
 !.vscode/tasks.json
+!.vscode/launch.json
 .idea
-.DS_Store
+.DS_Store

.oxlintrc.json

@@ -13,6 +13,8 @@
         "eslint/no-undefined": "off",
         "eslint/sort-keys": "off",
         "eslint/id-length": "off",
+        "eslint/capitalized-comments": "off",
+        "eslint/no-ternary": "off",
         "import/no-named-export": "off",
         "eslint/one-var": "off",
         "import/group-exports": "off",
@@ -20,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 },
@@ -39,6 +42,12 @@
             "rules": {
                 "import/no-nodejs-modules": "off"
             }
+        },
+        {
+            "files": ["src/util/__tests__/**"],
+            "rules": {
+                "import/no-nodejs-modules": "off"
+            }
         }
     ],
     "ignorePatterns": ["dist", "node_modules", "coverage"]

.vscode/extensions.json

@@ -1,5 +1,6 @@
 {
     "recommendations": [
+        "connor4312.nodejs-testing",
         "oxc.oxc-vscode",
         "streetsidesoftware.code-spell-checker",
         "typescriptteam.native-preview",

.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Debug current test file",
+            "runtimeExecutable": "node",
+            "runtimeArgs": ["--test", "--strip-types"],
+            "args": ["${file}"],
+            "cwd": "${workspaceFolder}",
+            "console": "integratedTerminal"
+        }
+    ]
+}

.vscode/settings.json

@@ -1,4 +1,14 @@
 {
+    "nodejs-testing.extensions": [
+        {
+            "extensions": ["mjs", "cjs", "js"],
+            "parameters": []
+        },
+        {
+            "extensions": ["ts"],
+            "parameters": ["--strip-types"]
+        }
+    ],
     "[typescript]": {
         "editor.defaultFormatter": "oxc.oxc-vscode",
         "editor.formatOnSave": true

AGENTS.md

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

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
 
 - upgrade dependencies
@@ -48,7 +59,9 @@ 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.3.0...main
+[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

CONTRIBUTING.md

@@ -67,6 +67,17 @@ 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
+throwaway call), `// Assert` holds every check — type expectations first,
+runtime assertions last; an empty block drops its label (see
+[development/testing.md § AAA ordering](./development/testing.md#aaa-ordering)).
 Type-first is enforced structurally: `npm test` runs `check:tsc` before the
 test runner, so a wrong type can never be papered over by a passing assertion.
 Per [AGENTS.md § Never do](./AGENTS.md#never-do), reach green honestly — fix the
@@ -145,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:

README.md

@@ -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:
-a value flows through a chain of patterns, the first one that matches runs its
-handler, and the handler receives the value narrowed to that pattern's type. The
-"patterns" are ordinary objects whose `matches` method is a TypeScript type
-guard, so narrowing composes the way any other guard does.
-
-It is deliberately not a regex engine and not a macro. There is no transpiler
-and no DSL to learn: `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.
+`tiny-pattern-ts` brings F#-style pattern matching to TypeScript. Patterns are
+ordinary objects whose `matches` method is a TypeScript type guard, so narrowing
+composes the way any other guard does. It is deliberately not a regex engine and
+not a macro: there is no transpiler and no DSL to learn, and the type-level
+contract is the feature — see [development/library.md](./development/library.md)
+for the design decisions and the known limitations.
 
 ## 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

backlog.tasks

@@ -5,7 +5,18 @@ 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
@@ -13,19 +24,46 @@ v1.0:
     ☐ 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/match.ts`
+    ☐ Achieve 100% branch coverage on `src/primitive.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
+    → today `_: (shape: T) => R`; desired `_: (shape: Exclude<T, handledKeys>) => R`
+☐ An exhaustive pattern that also carries `_` must be a compile error @medium
+    → `{ a, b, _ }` for `T = "a" | "b"` is accepted today; the redundant `_` should be rejected
+
+Bugs:
+✔ TS 7 LSP server logs `context canceled` on stderr at shutdown @done
+    → `handleExit` returns `io.EOF`, cancelling the background context while `Session.updateWatches` is still in flight; the bare error is flushed to stderr and the server exits 1
+    → close stdin after `shutdown` instead of sending `exit`; the server exits cleanly (code 0, no output), kill kept as a fallback
 Enhancements:
+☐ Allow boolean literals in primitive union patterns (e.g. `true: () => "yes"`) @medium
+☐ Are there other primitive types that should be supported in union patterns? (e.g. `bigint`, `symbol`) @medium
 
 Documentation:
+☐ Bring README.md back to its previous form — synopsis and examples restored, in the correct place
+    → previous section order: title, tagline, Synopsis, Description, Requirements, Examples, API, License, Contributing
+    → previous Examples order: literal/exhaustive, typeof, structural/discriminated unions, when, any
 ☐ Create `examples/` directory with runnable snippets
 ☐ Add comparison section vs. other TS pattern-matching libs in Readme.md
 ☐ Write migration guide for users coming from discriminated unions
 ☐ Create backlog tasks for implementation
+✔ Document the matcher design paths in `development/` — union vs overload merge, inferred universe (`NoInfer`), conditional `RequireKeys`, cases-first — and why each was abandoned @done
 ☐ Validate code fences in Markdown (start with README.md) — compile the TypeScript examples against `src/` so the docs cannot drift from the API
 
 Workflow:

cspell.json

@@ -42,7 +42,8 @@
         "bestikk",
         "silverwind",
         "idris",
-        "todotasks"
+        "todotasks",
+        "connor"
     ],
     "ignorePaths": ["dist", "node_modules", "coverage", "*.svg", ".gitignore"]
 }

development/library.md

@@ -3,4 +3,91 @@
 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 below 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 matcher is built by a factory and applied to a pattern:
+
+```ts
+const matcher = getMatcher<"a" | "b">()({ a: (s) => …, b: (s) => … });
+```
+
+Whether the pattern is exhaustive or has a fallback is decided **at the call
+site**, by whether it carries `_` — F#'s `| _ ->`. Only the return-strictness
+axis remains, so there are two factories:
+
+- `getMatcher` — one common `R`, the best common return type of every handler;
+- `getMatcherW` — the union of every handler's return type.
+
+Both are three overloads whose order is load-bearing:
+
+1. `ExhaustiveLoose<R, T>` = `{ [K in T]: UnaryFn<K, R> } & { _?: UnaryFn<T, R> }`
+2. `Fallback<R, T>` = `Partial<…> & { _: UnaryFn<T, R> }`
+3. `Handlers<R, T>` — the pure exhaustive shape
+
+#### Why
+
+- **Autocomplete reads the first overload, the error reads the last.**
+  TypeScript takes the first overload signature as the contextual type for the
+  object-literal popup, and the last for `No overload matches this call`. So
+  `ExhaustiveLoose` first yields the popup `_?, a, b` (T-keys required, `_`
+  optional) while `Handlers` last yields `Property 'b' is missing`. The two can be
+  tuned independently.
+- Two factories, not four: the fallback is a pattern _shape_, not a separate API.
+- The widened return union is derived from the pattern's handler types, so it
+  needs no fourth signature.
+
+#### Rejected
+
+- **Four factories** (exhaustive and fallback each split by return handling).
+  The exhaustive/fallback axis is expressible as one pattern type; four
+  signatures duplicate it.
+- **Union merge** — one type `Exhaustive<R,T> | (Partial<…> & { _: … })`,
+  explicit `<T>()`. Type-safe and completable, but TypeScript reports the
+  near-miss union member, so a missing key reads `Property '_' is missing`
+  instead of naming the key. Arm order does not change the report; the overload
+  split does.
+- **Overload merge with only the exhaustive arm last.** Fixes the missing-key
+  message, but a wrong `_` parameter is then reported against the exhaustive
+  arm, and `Parameters<typeof factory>` sees only one arm.
+- **Inferred universe** — `match(pattern)` with `T` taken from the keys
+  (exhaustive) or from `_`'s annotated parameter (fallback), via `NoInfer<T>` and
+  `_?: never`, split by overloads (a plain union merges inference; measured
+  `T = "_" | "a"`). No explicit `<T>`, and pipe-friendly. Rejected because: with
+  no declared universe the exhaustive popup offers only `_`; an unannotated `_`
+  widens `T` to `string | number`; and `NoInfer` leaks into the emitted `.d.ts`,
+  raising the consumer floor to TypeScript 5.4 (README promises `>= 5.0`).
+- **Conditional `RequireKeys`** — parameter
+  `P & ("_" extends keyof P ? unknown : Handlers<R, T>)`. Gives the good
+  missing-key message, but `keyof P` counts _optional_ keys: a widened value
+  whose declared type has `_?:` bypasses the completeness check. Demanding a
+  required `_` instead rejects that case but breaks `P` inference — `P` falls back
+  to its constraint and partial literals then demand every key. Typos also need a
+  `NoExtra` guard, whose message degrades to `not assignable to never`.
+- **Cases-first curried** — `match(["a", "b"])({ a: …, b: … })`. Completion works
+  for exhaustive patterns, and the array is a single source of truth for the
+  runtime list and the union. Rejected as not pipe-friendly; it needs a runtime
+  array; and the single-call form `match(cases, pattern)` cannot infer `R` (the
+  mapped key type `K[number]` stays deferred, so `R` widens to `unknown`).
+
+#### Known issue
+
+- The `_` handler receives **all** of `T`, not the unhandled subset
+  (`Exclude<T, handledKeys>`).
+- An exhaustive pattern that also carries `_` is accepted; the redundant `_`
+  should be a compile error.
+- The widened overloads carry a completeness guard
+  `keyof P extends T | "_" ? unknown : never`, because TypeScript does not apply
+  the excess-property check to a generic constraint: a generic parameter accepts
+  extra keys, a parameter typed as a concrete object type does not.
+  `PatternReturns` must be
+  `ReturnType<Extract<ValueOf<P>, (...args: never[]) => unknown>>` so it survives
+  the closed, partly-optional `P` constraints.
+- `Parameters<typeof factory>[0]` resolves only the **last** overload, so it is
+  not a sound "rejected" oracle for a factory. Factory-negative tests use
+  `@ts-expect-error` call sites (the test file only — the general ban stands).

development/testing.md

@@ -27,19 +27,148 @@ 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()`
-  throwing, or the `otherwise` fallback (see `src/index.test.ts`).
+- Testing the type only: it would not catch handler dispatch or the `_`
+  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
 [tooling.md](./tooling.md#source-imports-use-ts-extensions)).
 
+## AAA ordering
+
+The rule is in
+[CONTRIBUTING.md § Testing discipline (type-driven)](../CONTRIBUTING.md#testing-discipline-type-driven).
+
+#### Decision (2026-09)
+
+Test bodies read arrange → act → assert: inputs (the factory) set up first, the
+subject exercised once from them, all checks last — types then runtime. The
+blocks are labeled with `// Arrange` / `// Act` / `// Assert` comments and
+separated by a blank line; an empty block drops its label.
+
+#### Why
+
+- Interleaved setup/checks hide what runs vs. what is observed; the eye
+  re-reads the block to find the seams.
+- A factory built mid-test invites a second throwaway call of the subject;
+  arranging it once makes the positive construction and the negative
+  `Parameters<…>` check share one source of truth.
+- Labels make the seams explicit, not inferred — grep-able and reviewable
+  without reading the statements.
+
+#### Rejected
+
+- 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
-  `src/index.test.ts` carries a file-level `oxlint-disable
-typescript/no-floating-promises` with an explanatory comment. It is a known
-  false positive, not a rule worth disabling project-wide (see
+  test files that use it (`src/primitive.test.ts`) carry a file-level
+  `oxlint-disable typescript/no-floating-promises` with an explanatory comment.
+  It is a known false positive, not a rule worth disabling project-wide (see
   [tooling.md § oxlint-disable directives live next to the code](./tooling.md#oxlint-disable-directives-live-next-to-the-code)).

development/tooling.md

@@ -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).
@@ -104,25 +106,48 @@ Type-aware oxlint is enabled via `options.typeAware: true` in `.oxlintrc.json`
 
 #### Decision (2026-09)
 
-Known type-aware false positives are silenced with source-level `oxlint-disable`
-directives (see `src/pattern.ts`, `src/match.ts`, `src/index.test.ts`), not with
-rules disabled in `.oxlintrc.json`.
+A type-aware rule that false-positives is silenced with a source-level
+`oxlint-disable` directive (see `src/primitive.ts`,
+`src/primitive.test.ts`), not by turning the rule off in `.oxlintrc.json`.
 
 #### Why
 
 - The disable sits next to the code it silences, visible to anyone reading the
   source.
+- The rule stays on everywhere else, so only the mis-firing line is exempted.
 
 #### Rejected
 
-- A project-wide disable in `.oxlintrc.json`: it hides the suppression from the
-  reader of the affected code.
+- A project-wide disable in `.oxlintrc.json` for a false positive: it hides the
+  exemption from the reader of the affected code and switches the rule off
+  repo-wide for a one-site problem.
 
 #### Known issue
 
 - A source-level disable is a _human_ last resort. AI agents must not add one;
   they fix the type at its root (see [AGENTS.md § Never do](../AGENTS.md#never-do)).
 
+### Unwanted stylistic rules are turned off in the config
+
+#### Decision (2026-09)
+
+A stylistic rule the project rejects is `"off"` in the `.oxlintrc.json` `rules`
+map, not silenced at a use site. Current entries: `eslint/capitalized-comments`
+(comments may start lowercase) and `eslint/no-ternary` (ternaries are allowed),
+joining the oxfmt-superseded rules already off.
+
+#### Why
+
+- The rule is wrong for the whole project, not mis-firing at one site, so there
+  is no line to annotate.
+- Keeping the two mechanisms separate keeps a source-level `oxlint-disable`
+  meaningful: it marks a lone exception.
+
+#### Rejected
+
+- A source-level `oxlint-disable` per use: the same exemption repeated at every
+  site, and oxfmt can move the site.
+
 ### `check:tsc` runs first
 
 #### Decision (2026-09)
@@ -224,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

package-lock.json

@@ -1,13 +1,16 @@
 {
     "name": "tiny-pattern-ts",
-    "version": "0.1.8",
+    "version": "0.3.0",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
             "name": "tiny-pattern-ts",
-            "version": "0.1.8",
+            "version": "0.3.0",
             "license": "MIT",
+            "dependencies": {
+                "type-fest": "^5.9.0"
+            },
             "devDependencies": {
                 "@arethetypeswrong/cli": "^0.18.5",
                 "@runwisp/pubv": "^1.5.1",
@@ -24,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"
@@ -4622,6 +4626,18 @@
                 "url": "https://github.com/chalk/supports-hyperlinks?sponsor=1"
             }
         },
+        "node_modules/tagged-tag": {
+            "version": "1.0.0",
+            "resolved": "https://registry.npmjs.org/tagged-tag/-/tagged-tag-1.0.0.tgz",
+            "integrity": "sha512-yEFYrVhod+hdNyx7g5Bnkkb0G6si8HJurOoOEgC8B/O0uXLHlaey/65KRv6cuWBNhBgHKAROVpc7QyYqE5gFng==",
+            "license": "MIT",
+            "engines": {
+                "node": ">=20"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/sindresorhus"
+            }
+        },
         "node_modules/test-exclude": {
             "version": "8.0.0",
             "resolved": "https://registry.npmjs.org/test-exclude/-/test-exclude-8.0.0.tgz",
@@ -4705,6 +4721,21 @@
             "license": "0BSD",
             "optional": true
         },
+        "node_modules/type-fest": {
+            "version": "5.9.0",
+            "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-5.9.0.tgz",
+            "integrity": "sha512-yANm3Jr3GiJ1qgJlxGAVxTOIcEOk1rhQHamlXtnrCK7EHP4HeM9OGxtMg/W7HFdrVzw/ZWJKGVIJusVH85sLtw==",
+            "license": "(MIT OR CC0-1.0)",
+            "dependencies": {
+                "tagged-tag": "^1.0.0"
+            },
+            "engines": {
+                "node": ">=20"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/sindresorhus"
+            }
+        },
         "node_modules/typescript": {
             "version": "7.0.2",
             "resolved": "https://registry.npmjs.org/typescript/-/typescript-7.0.2.tgz",
@@ -4792,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",
@@ -4799,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",

package.json

@@ -1,6 +1,6 @@
 {
     "name": "tiny-pattern-ts",
-    "version": "0.1.8",
+    "version": "0.3.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",
@@ -65,6 +68,9 @@
         "setup": "npm run setup:git-commit-message",
         "setup:git-commit-message": "git config commit.template commit-message-template"
     },
+    "dependencies": {
+        "type-fest": "^5.9.0"
+    },
     "devDependencies": {
         "@arethetypeswrong/cli": "^0.18.5",
         "@runwisp/pubv": "^1.5.1",
@@ -81,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"

scripts/branch.sh

@@ -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
-# `origin_https`, and `main` tracks the latter — `git fetch origin main` would
-# check currency against a ref that is never updated here.
+# Derive the remote rather than hardcoding it: `main` tracks `origin` (ssh)
+# here; a hardcoded name would check currency against a ref that may not
+# 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.

src/index.test.ts

@@ -1,56 +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", () => {
-    const builder = match("x");
-    expectTypeOf(builder).toHaveProperty("with");
-    expectTypeOf(builder).toHaveProperty("exhaustive");
-    expectTypeOf(builder).toHaveProperty("otherwise");
-});
-
-test("P.literal narrows to its literal type", () => {
-    const matcher = P.literal("yes");
-    expectTypeOf(matcher).toMatchTypeOf<Matcher<"yes">>();
-    assert.equal(matcher.matches("yes"), true);
-    assert.equal(matcher.matches("no"), false);
-});
-
-test("P.type narrows to the typeof target", () => {
-    const matcher = P.type<string>("string");
-    expectTypeOf(matcher).toMatchTypeOf<Matcher<string>>();
-    assert.equal(matcher.matches("hi"), true);
-    assert.equal(matcher.matches(42), false);
-});
-
-test("exhaustive() returns the union of handler return types", () => {
-    const result = match<"a" | "b">("a")
-        .with(P.literal("a"), () => 1 as const)
-        .with(P.literal("b"), () => "two" as const)
-        .exhaustive();
-
-    expectTypeOf(result).toEqualTypeOf<1 | "two">();
-    assert.equal(result, 1);
-});
-
-test("otherwise() falls back when no case matches", () => {
-    const result = match<"x" | "y" | "z">("z")
-        .with(P.literal("x"), (v): string => `got ${v}`)
-        .otherwise((v): string => `fallback ${v}`);
-    assert.equal(result, "fallback z");
-});
-
-test("exhaustive throws when no case matches", () => {
-    assert.throws(
-        () =>
-            match<"a" | "b" | "c">("c")
-                .with(P.literal("a"), () => "A")
-                .with(P.literal("b"), () => "B")
-                .exhaustive(),
-        /no matching case/,
-    );
-});

src/index.ts

@@ -1,2 +1 @@
-export { match, P } from "./match.ts";
-export type { Matcher, Pattern } from "./pattern.ts";
+export { getMatcher, getMatcherW } from "./primitive.ts";

src/match.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 };

src/pattern.ts

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

src/primitive.test.ts

@@ -0,0 +1,457 @@
+/* oxlint-disable typescript/no-floating-promises -- expectTypeOf() is a sync type-assertion library that the type-aware linter misidentifies as a promise */
+import { strict as assert } from "node:assert";
+import path from "node:path";
+import { test } from "node:test";
+
+import { expectTypeOf } from "expect-type";
+
+import {
+    type CompletionTarget,
+    LspSession,
+} from "#test-utils/lsp-completion.ts";
+
+import { getMatcher, getMatcherW } from "./primitive.ts";
+
+// ============================================================================
+// API: getMatcher — ✔️ Exhaustive / ✔️ ReturnsStrict
+// ============================================================================
+
+test("getMatcher: exhaustive pattern infers one common return type", () => {
+    // Arrange
+    const factory = getMatcher<"a" | "b">();
+
+    // Act
+    const matcher = factory({
+        a: (s): number => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            return 1;
+        },
+        b: (s): 1 | 2 => {
+            expectTypeOf(s).toEqualTypeOf<"b">();
+            return 2;
+        },
+    });
+
+    // Assert
+    // ✔️ ReturnsStrict: R is the best common return type, not a widening union.
+    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => number>();
+    // ❌ a value outside T must not be accepted by the matcher
+    expectTypeOf<"c">().not.toExtend<Parameters<typeof matcher>[0]>();
+    assert.equal(matcher("a"), 1);
+    assert.equal(matcher("b"), 2);
+});
+
+test("getMatcher: dispatches on numeric literal keys", () => {
+    // Arrange
+    const factory = getMatcher<1 | 2>();
+
+    // Act
+    const matcher = factory({
+        1: (n) => {
+            expectTypeOf(n).toEqualTypeOf<1>();
+            return n + 1;
+        },
+        2: (n) => {
+            expectTypeOf(n).toEqualTypeOf<2>();
+            return n * 10;
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<(shape: 1 | 2) => number>();
+    assert.equal(matcher(1), 2);
+    assert.equal(matcher(2), 20);
+});
+
+test("getMatcher: dispatches on mixed string and numeric keys", () => {
+    // Arrange
+    const factory = getMatcher<"a" | "b" | 1 | 2>();
+
+    // Act
+    const matcher = factory({
+        a: (s): number => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            return 1;
+        },
+        b: (s): 1 | 2 => {
+            expectTypeOf(s).toEqualTypeOf<"b">();
+            return 2;
+        },
+        1: (n): number => {
+            expectTypeOf(n).toEqualTypeOf<1>();
+            return 10;
+        },
+        2: (n): number => {
+            expectTypeOf(n).toEqualTypeOf<2>();
+            return 20;
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | 1 | 2) => number>();
+    assert.equal(matcher("a"), 1);
+    assert.equal(matcher("b"), 2);
+    assert.equal(matcher(1), 10);
+    assert.equal(matcher(2), 20);
+});
+
+// ============================================================================
+// API: getMatcher — ❌ Exhaustive (fallback) / ✔️ ReturnsStrict
+// ============================================================================
+
+test("getMatcher: a `_` fallback makes the universe keys optional", () => {
+    // Arrange
+    const factory = getMatcher<"a" | "b" | "c">();
+
+    // Act
+    const matcher = factory({
+        a: (s): 1 | 2 => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            return 1;
+        },
+        _: (s): 1 | 2 => {
+            // The fallback sees the whole union, not a single literal.
+            expectTypeOf(s).toEqualTypeOf<"a" | "b" | "c">();
+            return 2;
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | "c") => 1 | 2>();
+    // ❌ a value outside T must not be accepted by the matcher
+    expectTypeOf<"d">().not.toExtend<Parameters<typeof matcher>[0]>();
+    assert.equal(matcher("a"), 1);
+    assert.equal(matcher("b"), 2);
+    assert.equal(matcher("c"), 2);
+});
+
+test("getMatcher: a `_` fallback also accepts an exhaustive pattern", () => {
+    // Arrange
+    const factory = getMatcher<"a" | "b">();
+
+    // Act
+    const matcher = factory({
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            return "A";
+        },
+        b: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"b">();
+            return "B";
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => string>();
+    assert.equal(matcher("a"), "A");
+    assert.equal(matcher("b"), "B");
+});
+
+test("getMatcher: a `_` fallback routes mixed string and numeric gaps", () => {
+    // Arrange
+    const factory = getMatcher<"a" | "b" | 1 | 2>();
+
+    // Act
+    const matcher = factory({
+        a: (s): string => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            return "A";
+        },
+        1: (n): string => {
+            expectTypeOf(n).toEqualTypeOf<1>();
+            return "one";
+        },
+        _: (s): string => {
+            expectTypeOf(s).toEqualTypeOf<"a" | "b" | 1 | 2>();
+            return "fallback";
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | 1 | 2) => string>();
+    assert.equal(matcher("a"), "A");
+    assert.equal(matcher("b"), "fallback");
+    assert.equal(matcher(1), "one");
+    assert.equal(matcher(2), "fallback");
+});
+
+// ============================================================================
+// API: getMatcherW — ✔️ Exhaustive / ❌ ReturnsStrict
+// ============================================================================
+
+test("getMatcherW: exhaustive pattern widens to the union of handler returns", () => {
+    // Arrange
+    const factory = getMatcherW<"x" | "y">();
+
+    // Act
+    const matcher = factory({
+        x: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"x">();
+            return 1 as const;
+        },
+        y: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"y">();
+            return "two" as const;
+        },
+    });
+
+    // Assert
+    // ❌ ReturnsStrict: mixed handler returns widen to their union.
+    expectTypeOf(matcher).toEqualTypeOf<(shape: "x" | "y") => 1 | "two">();
+    // ❌ a value outside T must not be accepted by the matcher
+    expectTypeOf<"z">().not.toExtend<Parameters<typeof matcher>[0]>();
+    assert.equal(matcher("x"), 1);
+    assert.equal(matcher("y"), "two");
+});
+
+test("getMatcherW: dispatches on mixed string and numeric keys", () => {
+    // Arrange
+    const factory = getMatcherW<"a" | "b" | 1 | 2>();
+
+    // Act
+    const matcher = factory({
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            return "A" as const;
+        },
+        b: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"b">();
+            return "B" as const;
+        },
+        1: (n) => {
+            expectTypeOf(n).toEqualTypeOf<1>();
+            return 10 as const;
+        },
+        2: (n) => {
+            expectTypeOf(n).toEqualTypeOf<2>();
+            return 20 as const;
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<
+        (shape: "a" | "b" | 1 | 2) => "A" | "B" | 10 | 20
+    >();
+    assert.equal(matcher("a"), "A");
+    assert.equal(matcher("b"), "B");
+    assert.equal(matcher(1), 10);
+    assert.equal(matcher(2), 20);
+});
+
+// ============================================================================
+// API: getMatcherW — ❌ Exhaustive (fallback) / ❌ ReturnsStrict
+// ============================================================================
+
+test("getMatcherW: a `_` fallback widens gaps into the union", () => {
+    // Arrange
+    const factory = getMatcherW<"x" | "y" | "z">();
+
+    // Act
+    const matcher = factory({
+        x: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"x">();
+            return 1 as const;
+        },
+        _: (s) => {
+            // The fallback sees the whole union, not a single literal.
+            expectTypeOf(s).toEqualTypeOf<"x" | "y" | "z">();
+            return "fallback" as const;
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<
+        (shape: "x" | "y" | "z") => 1 | "fallback"
+    >();
+    // ❌ a value outside T must not be accepted by the matcher
+    expectTypeOf<"w">().not.toExtend<Parameters<typeof matcher>[0]>();
+    assert.equal(matcher("x"), 1);
+    assert.equal(matcher("y"), "fallback");
+    assert.equal(matcher("z"), "fallback");
+});
+
+test("getMatcherW: a `_` fallback widens mixed string and numeric returns", () => {
+    // Arrange
+    const factory = getMatcherW<"a" | "b" | 1 | 2>();
+
+    // Act
+    const matcher = factory({
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"a">();
+            return "A" as const;
+        },
+        1: (n) => {
+            expectTypeOf(n).toEqualTypeOf<1>();
+            return 10 as const;
+        },
+        _: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"a" | "b" | 1 | 2>();
+            return "fallback" as const;
+        },
+    });
+
+    // Assert
+    // ❌ ReturnsStrict: mixed handler returns widen to their union.
+    expectTypeOf(matcher).toEqualTypeOf<
+        (shape: "a" | "b" | 1 | 2) => "A" | 10 | "fallback"
+    >();
+    assert.equal(matcher("a"), "A");
+    assert.equal(matcher("b"), "fallback");
+    assert.equal(matcher(1), 10);
+    assert.equal(matcher(2), "fallback");
+});
+
+test("getMatcherW: a `_` fallback also accepts an exhaustive pattern", () => {
+    // Arrange
+    const factory = getMatcherW<"x" | "y">();
+
+    // Act
+    const matcher = factory({
+        x: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"x">();
+            return 1 as const;
+        },
+        y: (s) => {
+            expectTypeOf(s).toEqualTypeOf<"y">();
+            return "two" as const;
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<(shape: "x" | "y") => 1 | "two">();
+    assert.equal(matcher("x"), 1);
+    assert.equal(matcher("y"), "two");
+});
+
+// ============================================================================
+// Factory contracts — calls that must not compile
+// ============================================================================
+
+test("getMatcher factory rejects patterns outside its contract", () => {
+    // Arrange
+    const factory = getMatcher<"a" | "b">();
+
+    // Act / Assert — the calls below must not compile.
+    // `Parameters<typeof factory>[0]` resolves only the *last* overload, so it
+    // is not a sound "rejected" oracle (an accepted partial pattern does not
+    // extend it either); the call sites are the oracle instead.
+    factory({
+        a: () => 1,
+        b: () => 2,
+        // @ts-expect-error `c` is not part of the universe `"a" | "b"`
+        c: () => 3,
+    });
+    // @ts-expect-error a gap without `_` is not exhaustive
+    factory({ a: () => 1 });
+});
+
+test("getMatcherW factory rejects patterns outside its contract", () => {
+    // Arrange
+    const factory = getMatcherW<"x" | "y">();
+
+    // Act / Assert — the calls below must not compile
+    // @ts-expect-error `z` is not part of the universe `"x" | "y"`
+    factory({
+        x: () => 1 as const,
+        y: () => 2 as const,
+        z: () => 3 as const,
+    });
+    // @ts-expect-error a gap without `_` is not exhaustive
+    factory({ x: () => 1 as const });
+});
+
+// ============================================================================
+// Autocomplete — the language server is the oracle, not the type system
+// ============================================================================
+
+// Completion is a contextual-type property that the type system cannot observe,
+// so the cases below read the popup from the repo's language server (via the
+// test helper) rather than pairing `expectTypeOf` with `assert` — see
+// development/testing.md § Autocomplete. They probe the *matcher's* overloads,
+// which is why they live with the matcher and not with the helper.
+const REPO_ROOT = path.resolve(import.meta.dirname, "..");
+const UNIVERSE = `"a" | "b" | "c"`;
+
+// One session per probe: the tests share no language-server state (open
+// documents, project membership), so they pass in any order.
+const labelsFor = (
+    name: string,
+    factory: "getMatcher" | "getMatcherW",
+    body: string,
+): Promise<readonly string[]> => {
+    const session = new LspSession(REPO_ROOT);
+    const target: CompletionTarget = {
+        file: `src/__autocomplete_${name}.ts`,
+        source: [
+            `import { ${factory} } from "./index.ts";`,
+            `const m = ${factory}<${UNIVERSE}>()({`,
+            body,
+            "});",
+            "",
+        ].join("\n"),
+    };
+    return session
+        .completionLabelsAt(target)
+        .then((result) => result.labels)
+        .finally(() => session.close());
+};
+
+test("autocomplete: an exhaustive pattern requires the universe, `_` optional", () => {
+    // Arrange
+    const name = "getMatcher_fresh";
+
+    // Act
+    const labels = labelsFor(name, "getMatcher", "    /*COMPLETE*/");
+
+    // Assert
+    return labels.then((result) => {
+        assert.deepEqual([...result], ["_?", "a", "b", "c"]);
+    });
+});
+
+test("autocomplete: handled keys drop out of the popup", () => {
+    // Arrange
+    const name = "getMatcher_after_key";
+
+    // Act
+    const labels = labelsFor(
+        name,
+        "getMatcher",
+        "    a: () => 1,\n    /*COMPLETE*/",
+    );
+
+    // Assert
+    return labels.then((result) => {
+        assert.deepEqual([...result], ["_?", "b", "c"]);
+    });
+});
+
+test("autocomplete: `_` makes the remaining keys optional", () => {
+    // Arrange
+    const name = "getMatcher_after_fallback";
+
+    // Act
+    const labels = labelsFor(
+        name,
+        "getMatcher",
+        "    _: () => 0,\n    /*COMPLETE*/",
+    );
+
+    // Assert
+    return labels.then((result) => {
+        assert.deepEqual([...result], ["a?", "b?", "c?"]);
+    });
+});
+
+test("autocomplete: `getMatcherW` offers the same popup as `getMatcher`", () => {
+    // Arrange
+    const name = "getMatcherW_fresh";
+
+    // Act
+    const labels = labelsFor(name, "getMatcherW", "    /*COMPLETE*/");
+
+    // Assert
+    return labels.then((result) => {
+        assert.deepEqual([...result], ["_?", "a", "b", "c"]);
+    });
+});

src/primitive.ts

@@ -0,0 +1,63 @@
+import type { ValueOf } from "type-fest";
+
+type UnaryFn<T, R> = (shape: T) => R;
+
+// `Extract` drops optional handlers (`undefined`) so `PatternReturns` also works
+// when `P`'s constraint has optional keys.
+type PatternReturns<P> = ReturnType<
+    Extract<ValueOf<P>, (...args: never[]) => unknown>
+>;
+
+type Handlers<R, T extends string | number> = { [K in T]: UnaryFn<K, R> };
+
+// Fallback form: `_` is a required key, the T-keys are optional.
+type Fallback<R, T extends string | number> = Partial<Handlers<R, T>> & {
+    _: UnaryFn<T, R>;
+};
+
+// Completion form: T-keys required, `_` optional. Overload #1, because
+// TypeScript takes the *first* overload as the contextual type for the popup.
+type ExhaustiveLoose<R, T extends string | number> = Handlers<R, T> & {
+    _?: UnaryFn<T, R>;
+};
+
+// oxlint-disable typescript/unified-signatures
+// Strict returns: one common `R`. Overload order is load-bearing:
+//   #1 ExhaustiveLoose -> autocomplete `_?, a, b`
+//   #2 Fallback        -> accepts a partial pattern
+//   #3 Handlers (last) -> "Property 'b' is missing" is the reported error
+interface MatcherStrict<T extends string | number> {
+    <R>(pattern: ExhaustiveLoose<R, T>): UnaryFn<T, R>;
+    <R>(pattern: Fallback<R, T>): UnaryFn<T, R>;
+    <R>(pattern: Handlers<R, T>): UnaryFn<T, R>;
+}
+// oxlint-enable typescript/unified-signatures
+
+// Widened returns: the union of every handler's return type. `P` is inferred
+// from the whole parameter, whose closed constraint supplies the
+// contextual/autocomplete type; the `keyof P` guard appended to each overload
+// rejects keys outside `T`/`_`.
+interface MatcherWidening<T extends string | number> {
+    <P extends ExhaustiveLoose<unknown, T>>(
+        pattern: P & (keyof P extends T | "_" ? unknown : never),
+    ): UnaryFn<T, PatternReturns<P>>;
+    <P extends Fallback<unknown, T>>(
+        pattern: P & (keyof P extends T | "_" ? unknown : never),
+    ): UnaryFn<T, PatternReturns<P>>;
+    <P extends Handlers<unknown, T>>(
+        pattern: P & (keyof P extends T | "_" ? unknown : never),
+    ): UnaryFn<T, PatternReturns<P>>;
+}
+
+type HandlerMap = Record<string | number, UnaryFn<never, unknown> | undefined>;
+
+const dispatch =
+    (pattern: HandlerMap) =>
+    (shape: string | number): unknown =>
+        // oxlint-disable-next-line typescript/no-non-null-assertion typescript/no-unsafe-type-assertion
+        (pattern[shape] ?? pattern["_"]!)(shape as never);
+
+export const getMatcher = <T extends string | number>(): MatcherStrict<T> =>
+    dispatch;
+export const getMatcherW = <T extends string | number>(): MatcherWidening<T> =>
+    dispatch;

src/util/__tests__/lsp-completion.test.ts

@@ -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/);
+});

src/util/__tests__/lsp-completion.ts

@@ -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;
+    });
+}