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

src/primitive.ts

@@ -1,4 +1,4 @@
-import type { ValueOf } from "type-fest";
+import type { Exact, ValueOf } from "type-fest";
 
 type UnaryFn<T, R> = (shape: T) => R;
 
@@ -8,54 +8,66 @@ type PatternReturns<P> = ReturnType<
     Extract<ValueOf<P>, (...args: never[]) => unknown>
 >;
 
-type Handlers<R, T extends string | number> = { [K in T]: UnaryFn<K, R> };
+type Handlers<T extends string | number, R> = { [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>;
-};
+// The fallback is a *second argument*, not a property of the handler map,
+// because its parameter is the remainder `Exclude<T, keyof Handled>` and TypeScript
+// fixes a property's contextual type before it infers its sibling keys. A later
+// argument, by contrast, is contextually typed from inference on an earlier
+// one, so the split is what makes the remainder expressible at all.
+// See development/library.md.
+type Fallback<T extends string | number, Handled, R> = UnaryFn<
+    Exclude<T, keyof Handled>,
+    R
+>;
 
-// 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>;
-};
+// TypeScript does not apply the excess-property check to a generic constraint,
+// so `Exact` restores it for the generic forms: a handler map can otherwise
+// carry keys outside `T`.
 
 // oxlint-disable typescript/unified-signatures
 // Strict returns: one common `R`. Overload order is load-bearing:
-//   #1 ExhaustiveLoose -> autocomplete `_?, a, b`
-//   #2 Fallback        -> accepts a partial pattern
-//   #3 Handlers (last) -> "Property 'b' is missing" is the reported error
+//   #1 Handlers (first) -> the exhaustive form and the autocomplete popup
+//   #2 Fallback (last)  -> accepts a partial handler map plus a fallback
 interface MatcherStrict<T extends string | number> {
-    <R>(pattern: ExhaustiveLoose<R, T>): UnaryFn<T, R>;
-    <R>(pattern: Fallback<R, T>): UnaryFn<T, R>;
-    <R>(pattern: Handlers<R, T>): UnaryFn<T, R>;
+    <R>(handlers: Handlers<T, R>): UnaryFn<T, R>;
+    <R, Handled extends Exact<Partial<Handlers<T, R>>, Handled>>(
+        handlers: Handled,
+        fallback: Fallback<T, Handled, R>,
+    ): UnaryFn<T, R>;
 }
 // oxlint-enable typescript/unified-signatures
 
 // Widened returns: the union of every handler's return type. `P` is inferred
-// from the whole parameter, whose closed constraint supplies the
-// contextual/autocomplete type; the `keyof P` guard appended to each overload
-// rejects keys outside `T`/`_`.
+// from the whole handler map, whose closed constraint supplies the
+// contextual/autocomplete type.
+// oxlint-disable typescript/unified-signatures
 interface MatcherWidening<T extends string | number> {
-    <P extends 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),
+    <P extends Exact<Handlers<T, unknown>, P>>(
+        handlers: P,
     ): UnaryFn<T, PatternReturns<P>>;
+    <R, Handled extends Exact<Partial<Handlers<T, unknown>>, Handled>>(
+        handlers: Handled,
+        fallback: Fallback<T, Handled, R>,
+    ): UnaryFn<T, PatternReturns<Handled> | R>;
 }
+// oxlint-enable typescript/unified-signatures
 
 type HandlerMap = Record<string | number, UnaryFn<never, unknown> | undefined>;
 
 const dispatch =
-    (pattern: HandlerMap) =>
+    (handlers: HandlerMap, fallback?: UnaryFn<never, unknown>) =>
     (shape: string | number): unknown =>
-        // oxlint-disable-next-line typescript/no-non-null-assertion typescript/no-unsafe-type-assertion
-        (pattern[shape] ?? pattern["_"]!)(shape as never);
+        (
+            handlers[shape] ??
+            fallback ??
+            (() => {
+                throw new Error(`Unhandled shape: ${shape}`);
+            })
+        )(
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+            shape as never,
+        );
 
 export const getMatcher = <T extends string | number>(): MatcherStrict<T> =>
     dispatch;