tables: maps in the language — the spelling, the key rules and the generated entry (#380)

[gafferongames]

The LANGUAGE half of maps (docs/SPEC-TABLES.md §2.8): the map[K]V spelling, every key rule and its refusal, the variable-class derivation, the generated <Table><Field>Entry table, the names the construct claims, the two projections that record it, and every target refusing a map-bearing unit by name. The codecs are not here and the "What is NOT here" section below says exactly what that leaves.

Based on #479's page, which is merged; this PR implements it.

The spelling and the key

ships map[string(32)]ShipConfig. The value is a whole field spelling, so map[uint32]*ShipConfig, map[uint32]?[..4]int32 and map[string(16)]map[uint8]Item are one production and a map of maps is nothing special.

Keys are bounded strings and integers and nothing else. Each refusal names its reason: an enum key is refused naming [E]T with the enum the author wrote substituted in; bool, floats, flags, bits(N), bytes(N), a 128-bit integer, a fixed-point key, a type, a table, a pointer, an optional and a union each get their own sentence. A map in a type body, [..N]map, [N]map, ?map, a default on a map and an attribute on a map are refused by name. So is a qualification or a default on the KEY: the grammar takes map[uint32 | max = 4]int32 so the diagnostic can say what is wrong, which is that a key is an identity and clamping an identity merges two entries. was and json stay legal, because both are about the field rather than the construct.

The enum-key refusal is the only one that names a replacement, and it never names one this checker refuses: map[E][..4]int32 and map[E]*V get the sentence that says what [E]T takes instead, with the value spelled as written, the array bound kept.

The generated entry

Every map generates <Table><Field>Entry with the field's name in §11's PascalCase, so Fleet.by_id generates FleetByIdEntry; a map whose value is a map names the inner entry <OuterEntry>ValueEntry. The entry is a real table of the closure, declared before its holder. It rides as kind 14 over element kind 13 with the two constant field ids 0xA079 and 0x9194, which is what makes a user's own [..N]Pair the same bytes.

It is not a root. §2.8 makes the entry the one exception to §7's "a root is any table", so the C++ reference emits it no Open, no Cook, no Save and no Load; its walk, its layout and its cook body are the whole of what it carries.

A map is a variable edge, whatever its key and value are, so its holder rides with the pointers and has no block form. Neither does the entry: §2.8 states that a map's entries are never rows, and the rule is categorical rather than derived, because an entry of a string(32) key and a by-value value looks perfectly fixed and would otherwise take a block form, its counts, its storage and its projection asserts. Where a table has no block form, the reason now names the edge the walk found, a pointer or a map or the member that reaches one.

The names it claims

Eight against the field, on the rule §11 already states for the block form's row accessors: <Table> plus the field's PascalCase, then Entry, Insert, Find, Erase, Each, IndexMeasure, Index and IndexFind. The runtime names TableMap and TableMapIndex are claimed the way TableKeyed is: whenever a unit declares a table, with the construct rather than with the codec.

The two projections

A generated entry is ANONYMOUS in both. Its record line carries the holder's wire id and the map field's wire id joined by a dot, in place of a name, and both projections sort over that text, so a was rename of the map field moves no line, no record order and no build version. The map field's own line is an array line: kind=14, array=map, elem= the entry's storage size, and no bound=, because a map declares no extent.

The baseline records the map shape and the key's kind and capacity, with two policy rows: a key kind is fixed, because a key under a kind the reader does not declare empties the map; a key bound is an extent, because an entry whose key does not fit is skipped whole and counted. [..N]Pair to map[K]V is one WARN saying the bytes are the same where the element's fields are exactly a key and a value, and that the map direction gains the order check.

Two version bumps ride here, and they move numbers. The baseline rendering version goes to 5 (two new judged tokens) and the two committed baselines are regenerated with their history intact. The cook projection's FORM version goes to 2, because this rendering emits tokens the last one did not, so every unit's build version moves, map-free ones included. §20.2's worked number, the compiler's pin, docs/USAGE.md's printed number, the build-version goldens, the generated headers' BuildVersion constants and all 84 cooked conformance artifacts are re-pinned in the same commit.

schemafmt

needSpace had no case for map, so every command rewrote map[string(32)]ShipConfig to map [string(32)]ShipConfig in place, silently and idempotently. Fixed, with the pre-existing [..4]*Node to [..4] * Node mangling one line away, which is why tables/stream/Stream.schema moves. The formatter's structural safety check rendered no map at all, so it could not tell two different maps apart; it renders the whole field type now. The gate reads §2.8's example off the page and compares bytes.

Docs

docs/SPEC.md gains map in the reserved words and a Map production in the Type grammar with the same TABLE BODIES ONLY note ? and * carry; #479 is SPEC-TABLES.md only, so nothing covered it. In docs/SPEC-TABLES.md: §11's Maps list gains the 128-bit and fixed-point keys the checker already refuses, §20.1 and §20.2 say that elem= on a map line is the entry's storage size like every other array line, and §20.2's two worked numbers are re-pinned.

What is NOT here

No codec, in any language. Every target, the C++ reference included, refuses a unit whose table closure declares a map, by name, naming the fields and saying the codecs are this issue's next PR. Nothing half-emitted is reachable.

What the C++ emitter does produce for a map-bearing unit, behind that refusal, is the three entry structs with their records, their Reset, their descriptors and their cook bodies. The map field's own storage is not emitted yet: Fleet comes out with /* ? */ ships = 0; for each map slot, which does not compile. That is the codec PR's first job, and it is why the refusal is unconditional rather than a warning.

Also not here: the sixteen-byte slot's writer and reader, the sort, the ascending check, the duplicate merge, Find, the builder's insert and erase, the text form, cook-check's entry-array check, the conformance corpus and the goldens.

Gates

go build, go test ./..., make check, make tables-zero-cost, make conformance-generate with a clean tree after, gofmt -l, go vet, and golangci-lint v2.12.2 at 0 issues. The zero-cost gate's symbol list gains the map machinery, so a map symbol leaking into a map-free unit's header is a build failure.

🤖 Generated with Claude Code