docs(api): note the façade guard's intended scope boundary (type-name clashes are tsc-caught)

2026-07-28 23:14:32 +02:00
parent 95db151565
commit 1fd4c2f7b3
1 changed files with 7 additions and 0 deletions
@@ -4,6 +4,13 @@ import { describe, it, expect, beforeAll } from "vitest";
 // mechanise the two invariants that make that structure safe — so a future edit that reintroduces
 // the interleave (a method dropped into two slices → a silent last-wins spread override) or bloats
 // the barrel (a method defined inline instead of in a domain module) fails CI instead of shipping.
+//
+// Scope, on purpose: this covers RUNTIME method-key collisions — the only *silent* failure mode,
+// since tsc does not flag overlapping spread keys. It deliberately does NOT cover exported-TYPE-name
+// clashes across slices (two slices exporting the same interface name): types are erased at runtime
+// so they're invisible here, and that case is already build-caught — the barrel's `export type *`
+// makes the ambiguous name a downstream tsc "no exported member" error, so nothing ships. Left to
+// tsc rather than re-checked by a fragile source parse.

 type Slice = Record<string, unknown>;