docs/SPEC-TABLES.md §2.8: maps, the specification

[gafferongames]

§2.8 is the maps design, 654 lines, and this PR is the whole of it in prose: no code, no goldens. It states the construct as present fact so an implementation can be built from it and held to it.

What the page states

A map is a lookup the runtime provides over entries the wire carries. On the wire, in a region and in a cook it is an array of one generated { key, value } table held in ascending key order, riding on kind 14 over kind 13. The wire spends no kind. The section states the spelling and the two spellings it refuses, the key set (string(N) and the integer kinds) with every other key refused by name and its reason, the total order, the unbounded count, the value set, and the map as a by-value edge of §3.1's one declaration-order walk.

The entry. Its name and its casing (<Table><Field>Entry, by_id on Fleet giving FleetByIdEntry), the nested form (<OuterEntry>ValueEntry), the file that declares it and where in that file, its two constant field ids at both wire widths, its wire shape, and the fact that it is the one exception to "a root is any table". It claims §11's suffix set as every closure member does.

The reader, rule by rule. The key is read before the slot is chosen, by a scan of the entry's field headers, so field order inside a body stays non-contractual. Ascending, equal and descending each say what happens to the slot, the counters and the parent. Keys never clamp: an entry whose key does not fit is dropped and counted clamped, one per entry, and the order check compares the wire keys of the entries that land. The key kind is the reader's declaration, and at the first entry that disagrees the map reads empty, one kind_mismatch is counted for the map, and the rest of the map is skipped by its L. One report per wire, so the region load and LoadBuilder never disagree.

The rest. The text form and its integer-key rule, the cook and Find, the absent block form, the memory layout down to the sixteen-byte slot and the pre-order placement of entry arrays inside the node's extent, LoadMeasure's term and its refusal, the optional runtime index and why its hash is not a cross-port contract, the builder's segments, growth and deletes, the cost model, the negative controls, the C++ surface, why the kind stays unspent and what that costs, and the row-by-row comparison with Protocol Buffers and FlatBuffers.

What this PR changes

It applies the rulings on a cold read of the previous revision. The read found four rules a port could not derive, two sentences that contradicted the rest of the standard, and a control list that named no corpus row.

The rules the page did not carry:

• The key before the slot. The reader scans the entry's field headers for the key's id and reads the key, and the scan decides the slot. Where the body repeats the key's id the scan reads the occurrence §3 keeps. An entry with no key field has the key's default.
• Keys never clamp. A tightened key bound is lossy by whole entries and never malformed. A widened one is lossless. A key a string value would refuse as malformed makes the map malformed.
• The key kind is the reader's declaration, never the first entry's. One kind_mismatch for the map, the rest skipped by the map's L, and events counted inside earlier entries stand. A value field of the wrong kind stays the entry's ordinary per-field event.
• One report per wire. The builder forgiveness is gone, and a hand-made body is held to the sort like any other.
• LoadMeasure. The term is N x sizeof( Entry ) rounded up to alignof( Entry ), at every depth. A wire it refuses answers the -1 every measure's refusal answers (§7.6). §4.2's EXACT claim is scoped to a read that reports nothing, and its bound is restated from an entry rather than a record, at six wire bytes.
• The build version and the baseline. The entry is anonymous in both, keyed by the holder's wire id and the map field's wire id, so a was rename moves no line. §20.1's closed table gains the map rows, §20.2's grammar gains array=map and the entry's record line, and §18.1's shape list gains the map with the key's kind and capacity.
• The claimed names. §11 states the eight a map takes against its field (Entry, Insert, Find, Erase, Each, IndexMeasure, Index, IndexFind) and the two runtime types (TableMap, TableMapIndex).
• The count is int32 like every companion, and §2.2's extent cap is the cap, at both wire widths.
• An integer key's text is §16.2's integer rule and nothing else, so -0 is zero, and a malformed key stops the read where §16.1 stops it.
• The surface. The const Find on map[K]*T answers what a pointer field's accessor answers. Insert answers NULL for a key that does not fit and for an arena that cannot grow alike, and NULL means not inserted.
• An unreached non-empty map slot is refused by Cook and Lock, the refusal §7.6 gives a pointer there.

The contradictions:

• A map of the holder's own type is refused as a by-value cycle (§2), not for infinite size.
• cook-check reads containment, alignment, fit and no overlap, not the offset the layout rule computes, so §7's independence sentence stands unchanged.
• An empty map is elided by §3's by-value elision rule, not §2.3's.
• The [..N]Pair edit is not silent and safe. The bytes are identical, the read gains the order check, and a wire whose pairs were not ascending reads short, so the baseline warns.
• A map's entry is the one exception to "a root is any table", and §7 now says so where that rule is stated.

The #435 seam. The wire widths are marked as the wire as it stands, with schema#435's beside them: ids become references, L and N become canonical LEB128, and the terminator becomes the zero reference. The cost table's wire rows say the same.

The tests. Every negative control names the corpus row or instance that meets it and the one instrument that goes red. Five are added: the walk-order pin, the parent-continues half of the descending rule, one kind_mismatch when the disagreeing entry is a later one, LoadMeasure over a map of maps, and cook-check's entry-array check. The one that was data rather than a control is gone, as is the one that stood on the deleted tool path.

The prose. The status paragraph, THE SEQUENCING, the owner quotations, the history and the plans are gone. Every twice-stated fact is stated once and cross-referenced. No gate name the page does not define, and no "reds" as a verb.

VERSIONING.md rides this PR for the two facts it owes: the map row in the three-frames table, and the read report paragraph naming the wire event that raises duplicate.

What the implementation PRs owe

The page is now ahead of the tree in four places, each deliberate and each a line #487 or the codec PR closes:

1. The map field's build-version line. schema build-version --facts emits kind=0 with no tokens for a map field today. The page states kind=14, elem=13 and array=map.
2. The entry's anonymity. Both projections emit record FleetShipsEntry and table FleetShipsEntry today. The page states the holder-id plus field-id key, in both.
3. The baseline rendering version. The page prints schema-tables-baseline 5; internal/baseline's constant is 4 on main, and the map lines are what moves it.
4. The claimed names and the entry's surface. The checker claims <Table><Field>Entry and nothing else, and with the C++ refusal lifted the generator gives the entry the full table surface. The page claims the eight and the two runtime types, and states that an entry gets no Open, Cook, Save or Load.

The cook projection's own form version is not bumped here, because §20.2's worked example is pinned against the compiler by compiler/tables_test.go. The PR that emits the map tokens bumps it and re-pins that number in the same change.

Held by

go test ./... and make check are green. The page is prose, so what holds every sentence is the implementation PR built from it.

🤖 Generated with Claude Code

[gafferongames]

Rulings on the #479 cold read (maps spec, docs/SPEC-TABLES.md §2.8)

Numbers follow the reader's report (sections 1 to 5). Line numbers there are at 6cd17b9 on maps-spec. Every ruling below is a rule the page states as present fact, in the page's voice, with no history, no plan, no owner quotation.

1. Underdetermined

1.1 The key before the slot. Before an entry's body decodes, the reader scans the entry's field headers for the key's id and reads the key (a bounded string or an integer, always a primitive). The scan decides the slot: ascending lands the body in the next slot; equal resets the previous slot to defaults and decodes the body into it (last wins whole); descending stops the map as malformed, the parent continues. An entry whose body carries no key field has the key's default. Where the body repeats the key's id, the scan reads the occurrence §3's repeated-field rule keeps. The writer emits the key first in every entry, so on any wire this schema wrote the scan ends at the first header; the rule is the scan, not the position.

1.2 Keys never clamp. An entry whose key does not fit the reader's bound (longer than N, or one a string value would clamp) is skipped by its L and counted clamped, one per entry. The order check compares the wire keys of the entries that land, so a skip cannot reorder or collide. A tightened key bound is therefore lossy by whole entries and never malformed; a widened one is lossless. A key a string value would refuse as malformed makes the map malformed. Rewrite L1538 to L1541 to this.

1.3 Key kind. The reader's declaration is the reference, never the first entry. At the first entry whose key kind disagrees with it, the map resets to empty, ONE kind_mismatch is counted for the map, and the map's remaining bytes are skipped by the map's L: nothing after that entry is decoded or counted. Events counted inside earlier entries of that map stand. A value field of the wrong kind is §4's ordinary per-field event inside the entry: the value reads its default, the entry stays. A map header whose element kind is not 13 is the ordinary array kind mismatch.

1.4 One report per wire. Delete the builder forgiveness. LoadBuilder applies the same rules as Load and produces the same five counters and flag, so §4.2's oracle and §17.5's differential hold. A hand-made body must be sorted like any other; there is no tool path.

1.5 LoadMeasure. A map's term is N × sizeof(Entry) padded to alignof(Entry), at every depth. On refusal LoadMeasure answers with the spelling it already uses for a wire it refuses (the worker finds it on the page and cites it). §4.2's EXACT claim is scoped: exact for a wire that reads with an empty report; a read that reports uses at most the measure (an empty map on kind mismatch and a skipped entry both leave slots unused). Restate §4.2's bound from the smallest wire footprint that yields one storage unit, which is now an entry, not a record.

1.6 Build version and baseline. The entry record is anonymous in both. It is identified by the holder's wire id plus the field's wire id, never by its generated name. §20.1's closed table gains the map field line (an array line, element kind 13, bound N, key kind, key bound) and the entry's record line keyed as above; §20.2's grammar gains the tokens; the worker mirrors the existing token forms exactly. §18.1's shape gains a map value carrying key kind and key bound. The verdict for [..N]Pair to map[K]V is WARN, with the reason: the bytes are identical when Pair's fields are exactly key and value, and the read gains the order check, so a wire whose pairs were not ascending reads short. Strike "silent and safe". §4.1's table gains §2.8's four evolution events.

1.7 Entry name.

Entry with the field's name in PascalCase by §11's rule, cited. A map value that is itself a map names its entry ValueEntry. The entry is declared in the holder's file, immediately before the holder.

1.8 Claimed names. §11 claims the map surface:

followed by Entry, Insert, Find, Erase, Each, IndexMeasure, Index and IndexFind, and the runtime names TableMap and TableMapIndex. The entry is a table of the closure for walk, layout and cook, and it claims §11's suffixes like every table; it is not a root and has no Open, Cook, Save or Load of its own. The worker reads what #487's generator emits for a map field and makes the page's claim match that list exactly, naming internal helpers under whatever internal convention §11 already has.

1.9 An unreached non-empty map slot is refused by Cook and Lock, the same refusal §7.6 gives a pointer there, cited.

1.10 The count is int32 like every companion; §2.2's extent cap is the cap; a wire N above it is refused as any array's is, at both widths.

1.11 Integer key text is parsed by §16.2's integer rule and nothing else, so -0 is zero and anything §16.2 rejects is malformed. A malformed key stops the read by §16.1's rule; say so in §2.8 rather than leaving it to the cross-reference.

1.12 The const Find on map[K]*T returns what a pointer field's accessor returns (cite the convention). Iteration yields the stored key in the form a string field's accessor yields. Insert returns NULL for a key that does not fit and for a full map alike; NULL means not inserted, and a caller who needs the reason checks the key's length first.

2. Contradictions

2.1 A map of the holder's own type is refused as a by-value cycle (§2's rule), not for infinite size. Fix the reason.
2.2 Settled by 1.6: a was rename moves nothing because the entry has no name in the digest or the baseline.
2.3 Settled by 1.2.
2.4 Settled by 1.4.
2.5 Settled by 1.8.
2.6 cook-check verifies the entry array's containment, alignment, fit and no overlap, not the offset the layout rule computes. §7's independence sentence stands unchanged.
2.7 VERSIONING.md changes in this PR: the map row in the three-frames table and the duplicate sentence corrected to name the wire event.
2.8 Delete the status paragraph. The page states the contract; what parses on which branch belongs in the PR.
2.9 Cite §3's by-value elision rule for the empty map.

3. The #435 seam

One sentence at the head of the wire bullets: these widths are §3's today; under schema#435 ids are references, L and N are canonical LEB128, and the terminator is the zero reference. Mark the cost table as today's wire. Apply 1.10 at L1606.

4. The tests

Rewrite the control list so every control names the corpus row or instance that makes it red: #1 an instance built out of key order; #2 the shuffled report row; #3 a duplicate whose repeat elides a field the first occurrence set; #7 the report row under a changed key kind; #9 leaves the control list, it is data; #11 an erasing instance; #13 is deleted with the tool path; #15 the value half, not the counter; #17 the key bound as the isolating half. Add the missing controls: the walk-order pin (a map with *T values declared before a pointer field that reaches a shared node first), the parent-continues half of the descending rule, ONE kind_mismatch when the disagreeing entry is a later one, LoadMeasure exactness over a map of maps, and cook-check's entry-array check. Drop "reds" as a verb and every gate name the page does not define.

5. Prose

Remove the owner quotations, the history, the plans and THE SEQUENCING. State each twice-stated fact once. Split L1463 to L1468. Fix the log formula to floor(log2 n) + 1. Fix the broken bold span. No em dashes in rewritten prose. British spellings outside §2.8 are #402's and stay.