🐛 Gate the universe to finite, literal keys

An open universe (`string`, `number`, a template literal) makes the
handler map index-like, so a partial object satisfied the exhaustive
overload and the runtime `dispatch` throw was reachable. A universe
containing a member and its stringification (`"true" | true`, `1 | "1"`)
collapsed two members onto one key.

- reject broad universes and value/stringification collisions at the
  factory, with a diagnostic naming the reason
- invert `PatternKey` against the universe (`Member<T, K>`) instead of
  `PatternParam<K>`, so a standalone `"true"` is typed `"true"`
- intersect `UniverseGate<T>` into the handler and fallback parameters,
  preserving `R` inference and the popup

src/tagged-union.test.ts

@@ -273,27 +273,17 @@ test("getTaggedUnionMatcher: a fallback receives the unhandled members", () => {
     assert.equal(area({ kind: "triangle", base: 1, height: 1 }), 2);
 });
 
-test("getTaggedUnionMatcher: an open discriminant keeps the fallback open", () => {
+test("getTaggedUnionMatcher: an open discriminant is rejected with a fallback too", () => {
     // Arrange
     interface Message {
         readonly kind: string;
         readonly text: string;
     }
-    const factory = getTaggedUnionMatcher<Message>()("kind");
 
-    // Act
-    const matcher = factory({ info: () => 1 as const }, (s) => {
-        // The map's literal key does not close an open discriminant, so the
-        // remainder stays `Message` and the fallback is not redundant.
-        expectTypeOf(s).toEqualTypeOf<Message>();
-        assert.equal(typeof s.text, "string");
-        return 2 as const;
-    });
-
-    // Assert
-    expectTypeOf(matcher).toEqualTypeOf<(shape: Message) => 1 | 2>();
-    assert.equal(matcher({ kind: "info", text: "" }), 1);
-    assert.equal(matcher({ kind: "warn", text: "" }), 2);
+    // Act / Assert — the call below must not compile; a broad tag is unsupported
+    // whether or not a fallback is supplied.
+    // @ts-expect-error `string` tags are not a finite union of literals
+    getTaggedUnionMatcher<Message>()("kind")({ info: () => 1 }, () => 2);
 });
 
 // ============================================================================
@@ -446,28 +436,489 @@ test("getTaggedUnionMatcherW factory rejects patterns outside its contract", ()
     );
 });
 
+test("getTaggedUnionMatcher: a standalone stringified tag is typed by the member, not its key", () => {
+    // `kind: "true"` is a string tag whose `PatternKey` is `"true"`; inverting
+    // the key must recover the member, not the boolean tag.
+    // Arrange
+    interface StringTag {
+        readonly kind: "true";
+        readonly a: number;
+    }
+    const factory = getTaggedUnionMatcher<StringTag>()("kind");
+
+    // Act
+    const matcher = factory({
+        true: (s) => {
+            expectTypeOf(s).toEqualTypeOf<StringTag>();
+            assert.equal(s.kind, "true");
+            return 1;
+        },
+    });
+
+    // Assert
+    assert.equal(matcher({ kind: "true", a: 1 }), 1);
+});
+
+test("getTaggedUnionMatcher: a broad tag is rejected", () => {
+    // Arrange
+    interface Message {
+        readonly kind: string;
+    }
+    interface Count {
+        readonly kind: number;
+    }
+
+    // Act / Assert — the calls below must not compile
+    // @ts-expect-error `string` tags are not a finite union of literals
+    getTaggedUnionMatcher<Message>()("kind")({ a: () => 1 });
+    // @ts-expect-error `number` tags are not a finite union of literals
+    getTaggedUnionMatcher<Count>()("kind")({ 1: () => 1 });
+    // @ts-expect-error the widening factory rejects broad tags too
+    getTaggedUnionMatcherW<Message>()("kind")({ a: () => 1 });
+});
+
+test("getTaggedUnionMatcher: a value/stringification tag collision is rejected", () => {
+    // Arrange
+    type Colliding =
+        | { readonly kind: "true"; readonly a: number }
+        | { readonly kind: true; readonly b: number };
+    type NumericColliding =
+        | { readonly kind: "1"; readonly a: number }
+        | { readonly kind: 1; readonly b: number };
+
+    // Act / Assert — the calls below must not compile
+    // @ts-expect-error `true` collides with the string tag `"true"`
+    getTaggedUnionMatcher<Colliding>()("kind")({ true: () => 1 });
+    // @ts-expect-error the number tag `1` collides with the string tag `"1"`
+    getTaggedUnionMatcher<NumericColliding>()("kind")({ "1": () => 1 });
+});
+
+test("getTaggedUnionMatcher: a tag collision is rejected beside legal members", () => {
+    // Act / Assert — the calls below must not compile. Each map is otherwise
+    // complete, so only the collision can make it invalid.
+    type TrueColliding =
+        | { readonly kind: "true"; readonly a: number }
+        | { readonly kind: true; readonly b: number }
+        | { readonly kind: "a"; readonly c: number };
+    // @ts-expect-error `true` collides with the string tag `"true"`
+    getTaggedUnionMatcher<TrueColliding>()("kind")({
+        true: () => 1,
+        a: () => 2,
+    });
+
+    type FalseColliding =
+        | { readonly kind: "false"; readonly a: number }
+        | { readonly kind: false; readonly b: number }
+        | { readonly kind: "a"; readonly c: number };
+    // @ts-expect-error `false` collides with the string tag `"false"`
+    getTaggedUnionMatcher<FalseColliding>()("kind")({
+        false: () => 1,
+        a: () => 2,
+    });
+
+    type NullColliding =
+        | { readonly kind: "null"; readonly a: number }
+        | { readonly kind: null; readonly b: number }
+        | { readonly kind: "a"; readonly c: number };
+    // @ts-expect-error `null` collides with the string tag `"null"`
+    getTaggedUnionMatcher<NullColliding>()("kind")({
+        null: () => 1,
+        a: () => 2,
+    });
+
+    type UndefinedColliding =
+        | { readonly kind: "undefined"; readonly a: number }
+        | { readonly kind: undefined; readonly b: number }
+        | { readonly kind: "a"; readonly c: number };
+    // @ts-expect-error `undefined` collides with the string tag `"undefined"`
+    getTaggedUnionMatcher<UndefinedColliding>()("kind")({
+        undefined: () => 1,
+        a: () => 2,
+    });
+
+    type NumericColliding =
+        | { readonly kind: "1"; readonly a: number }
+        | { readonly kind: 1; readonly b: number }
+        | { readonly kind: "a"; readonly c: number };
+    // @ts-expect-error the number tag `1` collides with the string tag `"1"`
+    getTaggedUnionMatcher<NumericColliding>()("kind")({
+        "1": () => 1,
+        a: () => 2,
+    });
+});
+
+test('getTaggedUnionMatcher: a `"true"` tag and a `false` tag are legal together', () => {
+    // Arrange
+    interface TrueString {
+        readonly kind: "true";
+        readonly a: number;
+    }
+    interface FalseBare {
+        readonly kind: false;
+        readonly b: number;
+    }
+    interface Extra {
+        readonly kind: "a";
+        readonly c: number;
+    }
+    type Legal = TrueString | FalseBare | Extra;
+
+    // Act
+    const matcher = getTaggedUnionMatcher<Legal>()("kind")({
+        true: (s) => {
+            expectTypeOf(s).toEqualTypeOf<TrueString>();
+            assert.equal(s.kind, "true");
+            return 1;
+        },
+        false: (s) => {
+            expectTypeOf(s).toEqualTypeOf<FalseBare>();
+            assert.equal(s.kind, false);
+            return 2;
+        },
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<Extra>();
+            assert.equal(s.kind, "a");
+            return 3;
+        },
+    });
+
+    // Assert
+    assert.equal(matcher({ kind: "true", a: 1 }), 1);
+    assert.equal(matcher({ kind: false, b: 2 }), 2);
+    assert.equal(matcher({ kind: "a", c: 3 }), 3);
+});
+
+test('getTaggedUnionMatcher: a `"false"` tag and a `true` tag are legal together', () => {
+    // Arrange
+    interface FalseString {
+        readonly kind: "false";
+        readonly a: number;
+    }
+    interface TrueBare {
+        readonly kind: true;
+        readonly b: number;
+    }
+    interface Extra {
+        readonly kind: "a";
+        readonly c: number;
+    }
+    type Legal = FalseString | TrueBare | Extra;
+
+    // Act
+    const matcher = getTaggedUnionMatcher<Legal>()("kind")({
+        false: (s) => {
+            expectTypeOf(s).toEqualTypeOf<FalseString>();
+            assert.equal(s.kind, "false");
+            return 1;
+        },
+        true: (s) => {
+            expectTypeOf(s).toEqualTypeOf<TrueBare>();
+            assert.equal(s.kind, true);
+            return 2;
+        },
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<Extra>();
+            assert.equal(s.kind, "a");
+            return 3;
+        },
+    });
+
+    // Assert
+    assert.equal(matcher({ kind: "false", a: 1 }), 1);
+    assert.equal(matcher({ kind: true, b: 2 }), 2);
+    assert.equal(matcher({ kind: "a", c: 3 }), 3);
+});
+
+test('getTaggedUnionMatcher: a `"null"` tag and an `undefined` tag are legal together', () => {
+    // Arrange
+    interface NullString {
+        readonly kind: "null";
+        readonly a: number;
+    }
+    interface UndefinedBare {
+        readonly kind: undefined;
+        readonly b: number;
+    }
+    interface Extra {
+        readonly kind: "a";
+        readonly c: number;
+    }
+    type Legal = NullString | UndefinedBare | Extra;
+
+    // Act
+    const matcher = getTaggedUnionMatcher<Legal>()("kind")({
+        null: (s) => {
+            expectTypeOf(s).toEqualTypeOf<NullString>();
+            assert.equal(s.kind, "null");
+            return 1;
+        },
+        undefined: (s) => {
+            expectTypeOf(s).toEqualTypeOf<UndefinedBare>();
+            assert.equal(s.kind, undefined);
+            return 2;
+        },
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<Extra>();
+            assert.equal(s.kind, "a");
+            return 3;
+        },
+    });
+
+    // Assert
+    assert.equal(matcher({ kind: "null", a: 1 }), 1);
+    assert.equal(matcher({ kind: undefined, b: 2 }), 2);
+    assert.equal(matcher({ kind: "a", c: 3 }), 3);
+});
+
+test('getTaggedUnionMatcher: an `"undefined"` tag and a `null` tag are legal together', () => {
+    // Arrange
+    interface UndefinedString {
+        readonly kind: "undefined";
+        readonly a: number;
+    }
+    interface NullBare {
+        readonly kind: null;
+        readonly b: number;
+    }
+    interface Extra {
+        readonly kind: "a";
+        readonly c: number;
+    }
+    type Legal = UndefinedString | NullBare | Extra;
+
+    // Act
+    const matcher = getTaggedUnionMatcher<Legal>()("kind")({
+        undefined: (s) => {
+            expectTypeOf(s).toEqualTypeOf<UndefinedString>();
+            assert.equal(s.kind, "undefined");
+            return 1;
+        },
+        null: (s) => {
+            expectTypeOf(s).toEqualTypeOf<NullBare>();
+            assert.equal(s.kind, null);
+            return 2;
+        },
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<Extra>();
+            assert.equal(s.kind, "a");
+            return 3;
+        },
+    });
+
+    // Assert
+    assert.equal(matcher({ kind: "undefined", a: 1 }), 1);
+    assert.equal(matcher({ kind: null, b: 2 }), 2);
+    assert.equal(matcher({ kind: "a", c: 3 }), 3);
+});
+
+test('getTaggedUnionMatcher: a `"1"` tag beside other tags is legal', () => {
+    // Arrange
+    interface OneString {
+        readonly kind: "1";
+        readonly a: number;
+    }
+    interface TwoBare {
+        readonly kind: 2;
+        readonly b: number;
+    }
+    interface ThreeBare {
+        readonly kind: 3;
+        readonly c: number;
+    }
+    interface FourString {
+        readonly kind: "4";
+        readonly d: number;
+    }
+    type Legal = OneString | TwoBare | ThreeBare | FourString;
+
+    // Act
+    const matcher = getTaggedUnionMatcher<Legal>()("kind")({
+        "1": (s) => {
+            expectTypeOf(s).toEqualTypeOf<OneString>();
+            assert.equal(s.kind, "1");
+            return 1;
+        },
+        2: (s) => {
+            expectTypeOf(s).toEqualTypeOf<TwoBare>();
+            assert.equal(s.kind, 2);
+            return 2;
+        },
+        3: (s) => {
+            expectTypeOf(s).toEqualTypeOf<ThreeBare>();
+            assert.equal(s.kind, 3);
+            return 3;
+        },
+        "4": (s) => {
+            expectTypeOf(s).toEqualTypeOf<FourString>();
+            assert.equal(s.kind, "4");
+            return 4;
+        },
+    });
+
+    // Assert
+    assert.equal(matcher({ kind: "1", a: 1 }), 1);
+    assert.equal(matcher({ kind: 2, b: 2 }), 2);
+    assert.equal(matcher({ kind: 3, c: 3 }), 3);
+    assert.equal(matcher({ kind: "4", d: 4 }), 4);
+});
+
+// The maximum legal tag universe needs one handler per member; the statement
+// count is inherent to the case.
+// oxlint-disable-next-line max-statements
+test("getTaggedUnionMatcher: the maximum legal tag universe is supported", () => {
+    // Arrange — every tag kind, one representation per value, plus extra tags.
+    interface M1 {
+        readonly kind: "true";
+        readonly a: 1;
+    }
+    interface M2 {
+        readonly kind: false;
+        readonly b: 2;
+    }
+    interface M3 {
+        readonly kind: null;
+        readonly c: 3;
+    }
+    interface M4 {
+        readonly kind: undefined;
+        readonly d: 4;
+    }
+    interface M5 {
+        readonly kind: "1";
+        readonly e: 5;
+    }
+    interface M6 {
+        readonly kind: 2;
+        readonly f: 6;
+    }
+    interface M7 {
+        readonly kind: 3;
+        readonly g: 7;
+    }
+    interface M8 {
+        readonly kind: "a";
+        readonly h: 8;
+    }
+    interface M9 {
+        readonly kind: "b";
+        readonly i: 9;
+    }
+    type Legal = M1 | M2 | M3 | M4 | M5 | M6 | M7 | M8 | M9;
+
+    // Act
+    const matcher = getTaggedUnionMatcher<Legal>()("kind")({
+        true: (s) => {
+            expectTypeOf(s).toEqualTypeOf<M1>();
+            assert.equal(s.kind, "true");
+            return 1;
+        },
+        false: (s) => {
+            expectTypeOf(s).toEqualTypeOf<M2>();
+            assert.equal(s.kind, false);
+            return 2;
+        },
+        null: (s) => {
+            expectTypeOf(s).toEqualTypeOf<M3>();
+            assert.equal(s.kind, null);
+            return 3;
+        },
+        undefined: (s) => {
+            expectTypeOf(s).toEqualTypeOf<M4>();
+            assert.equal(s.kind, undefined);
+            return 4;
+        },
+        "1": (s) => {
+            expectTypeOf(s).toEqualTypeOf<M5>();
+            assert.equal(s.kind, "1");
+            return 5;
+        },
+        2: (s) => {
+            expectTypeOf(s).toEqualTypeOf<M6>();
+            assert.equal(s.kind, 2);
+            return 6;
+        },
+        3: (s) => {
+            expectTypeOf(s).toEqualTypeOf<M7>();
+            assert.equal(s.kind, 3);
+            return 7;
+        },
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<M8>();
+            assert.equal(s.kind, "a");
+            return 8;
+        },
+        b: (s) => {
+            expectTypeOf(s).toEqualTypeOf<M9>();
+            assert.equal(s.kind, "b");
+            return 9;
+        },
+    });
+
+    // Assert
+    expectTypeOf(matcher).toEqualTypeOf<(shape: Legal) => number>();
+    assert.equal(matcher({ kind: "true", a: 1 }), 1);
+    assert.equal(matcher({ kind: false, b: 2 }), 2);
+    assert.equal(matcher({ kind: null, c: 3 }), 3);
+    assert.equal(matcher({ kind: undefined, d: 4 }), 4);
+    assert.equal(matcher({ kind: "1", e: 5 }), 5);
+    assert.equal(matcher({ kind: 2, f: 6 }), 6);
+    assert.equal(matcher({ kind: 3, g: 7 }), 7);
+    assert.equal(matcher({ kind: "a", h: 8 }), 8);
+    assert.equal(matcher({ kind: "b", i: 9 }), 9);
+});
+
+test("getTaggedUnionMatcher: the maximum illegal tag universe is rejected", () => {
+    // Arrange — every tag paired with its stringification.
+    type Illegal =
+        | { readonly kind: "true"; readonly a: 1 }
+        | { readonly kind: true; readonly a: 1 }
+        | { readonly kind: "false"; readonly b: 2 }
+        | { readonly kind: false; readonly b: 2 }
+        | { readonly kind: "null"; readonly c: 3 }
+        | { readonly kind: null; readonly c: 3 }
+        | { readonly kind: "undefined"; readonly d: 4 }
+        | { readonly kind: undefined; readonly d: 4 }
+        | { readonly kind: "1"; readonly e: 5 }
+        | { readonly kind: 1; readonly e: 5 };
+
+    // Act / Assert — the call below must not compile
+    // @ts-expect-error every tag collides with its stringification
+    getTaggedUnionMatcher<Illegal>()("kind")({
+        true: () => 1,
+        false: () => 2,
+        null: () => 3,
+        undefined: () => 4,
+        "1": () => 5,
+    });
+});
+
 // ============================================================================
 // Dispatch — runtime behavior
 // ============================================================================
 
 test("getTaggedUnionMatcher: an unhandled tag throws without a fallback", () => {
-    // Arrange — an open discriminant widens its handler map to an index
-    // signature, so the type system cannot prove the runtime map is exhaustive.
+    // Arrange — a finite tag set is exhaustive through the typed API, so the
+    // defensive throw is reachable only by widening the factory and dropping a
+    // handler.
     interface Message {
-        readonly kind: string;
+        readonly kind: "info" | "warn";
+        readonly text: string;
     }
-    const handlers: Record<string, (shape: Message) => number> = {
-        info: (shape) => {
+    const bypass: Function = getTaggedUnionMatcher<Message>()("kind");
+    const matcher: (shape: Message) => number = bypass({
+        info: (shape: Message) => {
             // The full member reaches the handler, not its tag.
             assert.equal(shape.kind, "info");
             return 1;
         },
-    };
-    const matcher = getTaggedUnionMatcher<Message>()("kind")(handlers);
+    });
 
     // Act / Assert
-    assert.equal(matcher({ kind: "info" }), 1);
-    assert.throws(() => matcher({ kind: "warn" }), /Unhandled tag: warn/);
+    assert.equal(matcher({ kind: "info", text: "" }), 1);
+    assert.throws(
+        () => matcher({ kind: "warn", text: "" }),
+        /Unhandled tag: warn/,
+    );
 });
 
 // ============================================================================