v0.21.0 Phase 0 Associative Collection Design Review

Result

Phase 0 is complete. The reviewed contract exposes one representation-neutral Map<K, V> and Set<T> choice for normal code, keeps their first hash-table implementation private, and defines the language, ownership, allocation, and tooling behavior needed before source implementation. No implementation blocker or unresolved public choice remains.

The review found and closed two active documentation defects. The generic-alias example in the type chapter still used Map<K, V> = HashMap<K, V>, contradicting the new absence of a public HashMap; it now uses an unrelated Vec alias. The recoverable-literal policy named try_from_entries and try_from_items without including them in the public construction surface; both declarations are now present and use the same keyed or ordinary pack contract as their aborting literal.

Authority Review

• Associative Collections solely owns Map, Set, Hash, lookup, mutation, equality, iteration, allocation, and collection-specific literal behavior.
• Argument Packs, Literal Definitions, and Sequence Spread solely owns keyed-pack evaluation, body operations, ownership, forwarding, cleanup, and ABI.
• Syntactic Grammar owns the exact future grammar fragments; it labels them unimplemented and does not silently alter current parser behavior.
• Modules, Use Declarations, and Source Visibility owns future prelude exposure. Hash and HashState remain explicit imports.
• Tooling and Editor Integration owns future hover, navigation, signature-help, and semantic-evidence presentation.
• The milestone owns work order, this review owns findings/evidence, and the implementation boundary owns only cross-responsibility direction. None is an alternate public specification.

Representation Review

The public surface contains no HashMap, HashSet, bucket, probe, control-byte, tombstone, load-factor, raw-table, final-hash, seed, or custom-hasher API. capacity is defined by how many entries can be retained without allocation rather than by bucket count. Equality ignores seed, capacity, placement, and iteration order.

Hash remains intentionally public even though table representation is private. It is a key capability contract, not permission to inspect the implementation: HashState is opaque, users cannot construct or finalize it, and implementations contribute logical fields without selecting an algorithm. A future internal table change may keep this conservative key capability without changing Map's name or exposing the replacement representation.

TreeMap and TreeSet are reserved for the observably different ordered/range-query contract. They are not alternative names for selecting an internal implementation of ordinary Map or Set.

Ownership and Failure Review

• A map never returns a readwrite key borrow; mutable iteration exposes &K plus &+V.
• Set has no readwrite iteration or index operation.
• Duplicate insertion retains the first stored key/element and destroys every rejected owner once.
• Optional lookup is separate from terminating index access, and index assignment cannot allocate or insert.
• Recoverable reserve, insertion, and construction publish no partial mutation.
• Replacement allocation and every fallible preparation complete before entry movement starts.
• One table metadata authority identifies initialized sparse slots; cleanup does not trust a caller-maintained count or parallel initialization map.
• Hash/equality behavioral coherence is the one necessarily authored semantic obligation. The compiler proves its structural prerequisite but cannot prove arbitrary bodies. The specification makes violation observable as failed logical lookup while still requiring memory safety and once-only destruction from the collection implementation.

Capability Review

Existing owners already supply generic prerequisites, equality evidence, indexing, expansion, exact-size iteration, allocator affinity, RawBuffer, typed layout, and arbitrary sparse store/take/drop. The review therefore rejects a compiler-known table or Map/Set-specific lowering.

The exact admitted gaps are:

1. 1. one keyed argument-pack identity carried from syntax through target ABI;
2. explicit unsigned wrapping and bit-mixing operations for source-defined hashing;
3. one private target entropy boundary for default collection seeds.

These gaps have distinct owners. They do not justify tuples, mapping spread, entry handles, custom hashers, stable hash output, or a second Set storage engine.

Source and Tooling Review

The mapping form is declaration-driven. Map [key: value] resolves literal [:]; Map [:] is the only empty mapping, Map [] remains a sequence shape, and bare [values] remains an array. The keyed descriptor is one ABI lane and cannot be reconstructed from alternating ordinary values.

Future tooling consumes the same keyed semantic evidence as compilation. It may not infer pair structure from colon tokens or surface private table terminology. No standard-library source was added during Phase 0, so the current compiler continues to reject the future grammar rather than partially accepting it through compatibility syntax.

Evidence

• node docs/build-docs.js
• cargo fmt --all --check
• cargo test --workspace --quiet
• git diff --check
• active-source audit for HashMap, HashSet, duplicate Map/Set contracts, and representation vocabulary

All commands passed on 2026-08-30. The full workspace test retained one existing ignored test and reported no failure.