📝 Document the finite-only universe decision

Record why open universes and value/stringification collisions are
rejected, the `Member<T, K>` inversion, and the findings from the
rejected open-universe attempt so they are not re-run.
This commit is contained in:
tmu committed 2026-09-23 13:42:12 +00:00
1 parent 3b5269f9e1
commit aaeeef1e11
2 files changed
+88 -21

No files matched your search

+9 -4
View File
@@ -25,10 +25,15 @@ Yet to be implemented
## Caveats
- **A value and its stringification collide.** Object keys stringify, so a
universe that mixes a member with the string it stringifies to — `1 | "1"`,
`true | "true"`, `null | "null"` — collapses to a single handler key and both
members are routed to it. Use one form or the other.
- **Only finite universes are supported.** The factory must be given a finite
union of literals; `string`, `number` and template literals are rejected. This
is what lets the exhaustive overload be proven, so the runtime `dispatch`
throw stays unreachable through the typed API.
- **A value and its stringification must not both be present.** Object keys
stringify, so a universe containing both a member and the string it
stringifies to — `1 | "1"`, `true | "true"`, `null | "null"` — is rejected at
the factory. Either form alone is fine, and one value's string form may
coexist with a _different_ value's bare form (`"true" | false`).
- **`symbol` and `bigint` are not supported.** A `symbol` brand is a
compile-time phantom with nothing to match at runtime, and a `bigint` is not a
valid property key; neither satisfies the matcher's universe constraint.