tables: map values of array, enum-extent, unbounded and blob kinds in the C++ reference (#628)

[rowan-claude]

map[K][N]T, map[K][..N]T, map[K][E]T, map[K][]T, map[K]*string and
map[K]*bytes now emit C++ that compiles, and the corpus, the goldens, the
oracle and the controls say so.

Closes #628.

What lands

The emitter. internal/codegen/cpptable/maps.go. The entry's own storage
was right in all six: §2.8 makes the entry a real table whose value is an
ordinary field, so int32_t value[3], the element array beside value_count,
TableKeyed<int32_t, Slot>, TableList<Item> and the eight-byte TableRef
were all already emitted. What had no spelling was the HANDLE, because
mapValueStorageType asked cppFieldType for one type name and that function
answers a field's ELEMENT type, not its array, its keyed slot, its list slot or
its blob.

The rule the fix states is one sentence: the handle follows the storage.

value	storage	handle
[N]T	T value[N], one member	<Entry>Value *, a pointer to the ARRAY
[..N]T	T value[N] + int32 value_count, a PAIR	the ENTRY
[E]T	TableKeyed<T, E>, one member	TableKeyed<T, E> *
[]T	TableList<T>, one member	TableList<T> *
*string, *bytes	TableRef, one member	the SLOT on the builder, const TableBlob * on the const Find

mapValueIsText becomes mapValueIsPair and now covers [..N]T as well as
the three text kinds, which is #626's rule applied to the second storage shape
that has two members. [N]T gains one alias per entry, <Entry>Value, because
a return type cannot spell T (*)[N] without wrapping the declarator around
the function name. A blob takes its own arm in the pointer branch because it
has no declared type name, which is exactly what the two At( errors below
were.

The corpus. Six units under tables/maps, landed on their own in 588af57
before any emitter change, each a map and a field past it so a stop is visible:

table Cells  { rows   map[string(8)][3]int32   after int32 }
table Runs   { spans  map[uint16][..4]Item     after int32 }
table Slots  { seats  map[int32][Slot]int32    after int32 }
table Spans  { tracks map[uint8][]Item         after int32 }
table Docs   { pages  map[string(8)]*string    after int32 }
table Chunks { blobs  map[int32]*bytes         after int32 }

Red first

Against 1f62d47, the merge with origin/main at bb5f3bd and before any
emitter change. clang at the repo's own table flags, over a translation unit
that includes one generated header and nothing else:

CellsTable.h:6144: cannot initialize return object of type 'const int32_t *'
  with an rvalue of type 'const int32_t (*)[3]'
RunsTable.h:6134: cannot initialize return object of type 'const Item *'
  with an rvalue of type 'const Item (*)[4]'
SlotsTable.h:6204: cannot initialize return object of type 'const int32_t *'
  with an rvalue of type 'const TableKeyed<int32_t, Slot> *'
SpansTable.h:6141: cannot initialize return object of type 'const Item *'
  with an rvalue of type 'const TableList<Item> *'
DocsTable.h:6154: a type specifier is required for all declarations
  inline const  * TableEntryFound( const DocsPagesEntry * entry )
ChunksTable.h:6145: use of undeclared identifier 'At'

The pointer types in the first four are the whole diagnosis: the storage was
already the array, the keyed slot and the list slot, and only the return type
was unspellable.

The second defect, found by the corpus

internal/tablewire's visitEdges had no case for a MAP field, so the tool's
node-table numbering never reached the pointer slots inside an entry. The old
corpus hid it: Fleet.by_id's two keys name the node Fleet.flagship names,
so every node reachable through a map was already numbered through a pointer
field beside it. Docs.pages and Chunks.blobs are the first slots to name a
node NOTHING ELSE names, and the engine read the reference's bytes clean and
then re-encoded short:

map_docs: the engine re-encoded 64 bytes, the reference wrote 123
map_chunks: the engine re-encoded 61 bytes, the reference wrote 107

Fixed in fcf707f with the page's own sentence: a map is a by-value edge of the
one declaration-order walk, reached at its field's position, entries in
ascending key order, each descended before the next (§2.8, §3.1).
MapEntryOrder is that order, lifted out of encodeMap so the numbering and
the writer take it from one place.

Both engines

test/tables/maps_main.cpp gains six rows, one per unit, each pinning its wire,
holding measure == save, loading the region, re-saving it byte for byte, and
reading the text form back to the same wire.
test/conformance/harness/maps_test.go gains the six names, so the compiler's
own engine reads the reference's bytes, writes them back byte for byte, renders
the text and reads that text to the same bytes. The two engines' TEXTS agree:

{ "rows":   { "alpha": [ 10, 11, 12 ], "beta": [ 0, 1, 2 ] } }
{ "spans":  { "4": [ { "count": 40 }, { "count": 41 } ], "9": [ { "count": 90 } ] } }
{ "seats":  { "-2": { "Alpha": 2, "Beta": 101 }, "6": { "Alpha": 1, "Beta": 100 } } }
{ "tracks": { "1": [ ..., 3 items ], "8": [ ..., 2 items ] } }
{ "pages":  { "alpha": "first page", "beta": "second page" } }
{ "blobs":  { "-3": "3q2+7w==", "2": "AAGA/w==" } }

Every map is built OUT OF KEY ORDER, so the pinned wire says the four writing
walks sorted. Spans carries three elements under key 1 and two under key 8,
the SECOND-inserted key holding the longer list, so a walk that laid the
entries' lists in insertion order would read one list's elements as another's.
Slots and Chunks use signed keys, so -3 and -2 sort first.

The controls

New: tables-maps-entry-node-negative-control. It short-circuits the
per-entry Number call in the map's by-value edge, so a node named ONLY by a
map entry takes no index. Docs and Chunks are what meet it, and the answer
is the -1 §7.6 gives an unreached pointer rather than a wrong wire:

FAIL table wire golden map_docs: -1 bytes written, 123 pinned
FAIL test/tables/maps_main.cpp:1873: need > 0
FAIL test/tables/maps_main.cpp:1874: need = -1, past the 268435456 byte measure ceiling
FAIL table wire golden map_chunks: -1 bytes written, 107 pinned
FAIL test/tables/maps_main.cpp:1959: chunk_need > 0
FAIL test/tables/maps_main.cpp:1960: chunk_need = -1, past the 268435456 byte measure ceiling

Fleet.by_id cannot meet it, because Fleet.flagship names the same node.
Its sabotage carries an unbalanced parenthesis a $(call) argument cannot, so
the recipe is spelled out as the keylength one is.

tables-maps-value-reset-negative-control goes 4 to 10 failures, one per
value kind's duplicate row, which is the runtime behaviour each kind adds:

FAIL test/tables/maps_main.cpp:1571: repeat != NULL && ( *repeat )[0] == 0                    # [3]int32 reset whole
FAIL test/tables/maps_main.cpp:1655: repeat != NULL && repeat->value_count == 0               # [..4]Item, the count
FAIL test/tables/maps_main.cpp:1656: repeat != NULL && repeat->value[0].count == 0            # and the elements
FAIL test/tables/maps_main.cpp:1739: repeat != NULL && ( *repeat )[Slot::Alpha] == 0          # every keyed slot
FAIL test/tables/maps_main.cpp:1843: repeat != NULL && repeat->count == 0                     # the list slot, back to empty
FAIL test/tables/maps_main.cpp:1927: repeat != NULL && repeat->value == 0                     # the blob slot, back to null

tables-maps-depth-negative-control now names the Spans rows. An entry's
list elements are a term of the map's extent at the entry's depth, so a measure
summed at one depth only leaves them unplaced:

FAIL test/tables/maps_main.cpp:1791: one != NULL && one->count == 3
FAIL test/tables/maps_main.cpp:1797: eight != NULL && eight->count == 2
FAIL test/tables/maps_main.cpp:1804: SpansSave( loaded, again, sizeof( again ) ) = 55, want 121

The compile-time half has NO runtime control, by construction: a sabotage of
the storage line produces no binary to run. Its evidence is the red-first quote
above.

Seventeen map controls, all red on purpose:
sort 78, dead 6, ascending 4, duplicate 2, keykind 3, clamp 2, fit 2, cap 1, depth 38, textorder 6, keylength 4, keyidentity 2, keydomain 3, placefail 1, valuereset 10, entrynode 6, unreached 2.

Two rows moved so the instrument survives the sabotages beside it, and each
was a real hole in the gate rather than a convenience. The Chunks half left
the tail of test_blob_values for its own function, because a sabotage that
refuses one unit's save must leave the other unit reporting. And the Spans
element reads sit under their count, because a list whose elements were never
placed has a NULL element pointer: under the depth sabotage that read
faulted, and a fault takes the buffered output of every row with it, which is
what "the gate went red, but not on a CHECK" was saying.

The refusal

map[K]*wstring is the one value kind §2.8 lists that is refused BY NAME, and
internal/check/tables_test.go gains the case. The entry is where the refusal
has to reach a map's value, because the value is a field of a table nobody
wrote:

field value: *wstring is specified ahead of its implementation and no backend
emits it (docs/SPEC-TABLES.md §2.5)

No kind is refused under a map KEY that is not already refused there: the key
refusals are unchanged and their fourteen diagnostics cases stand.

The page

§2.8 gains two paragraphs. THE VALUE'S STORAGE IS THE ROW ITS KIND TAKES AT
A FIELD, kind by kind. THE HANDLE FOLLOWS THE STORAGE: a pointer to the value
member where the storage is one member, the ENTRY where it is two, the ARRAY
rather than its first element for a [N]T, and for a pointer value the SLOT on
the builder against the RESOLVED node on the const Find.

§4.2 gains one: a map's value is a FIELD POSITION, so the array element
kind, the kind 17 node index and the kind 12 and kind 33 payloads the mutator
list already names all land inside an entry without a strategy of their own,
and what stays the map's is the KEY.

§15 gains a named follow-on, below.

The goldens

NEW: testdata/golden/tables/maps/{Cells,Runs,Slots,Spans,Docs,Chunks}Table.{h,cpp}
and six wires, testdata/wire/tables/map_{cells,runs,slots,spans,docs,chunks}.bin.

MOVED, and every one has a named reason.

The unit's SHARED VOCABULARY (§3.3) grew, because mapdemo gained twelve
tables: the six holders and the six entries their maps generate. The vocabulary
is emitted identically into every header of a unit, which is why three
unrelated headers move and why no per-type codec does:

	before	after
TableIds::kCapacity	50	67
kTableRetainKnownIds	50	67
kTableMessageEntriesHere	52	66
kTableNodeTableFieldSlot	40	48
kTableAnnounceBytes	615	786
BuildVersion	0x28abc7f5927a7539	0xe4ae2b700e9c3e19

plus every w.put( <slot>, kTableMessageRefBitsHere ) and node.type_slot,
because the vocabulary is sorted and new types shift the slots after them. The
two message wires follow from the same fact: map_conn IS the announcement,
615 to 786 bytes, and map_full_message is 172 to 179 bytes and repacks,
because a body's type reference is an index into that vocabulary.

And the four <Base>Table.cpp files gained the JSON LIST WALK, which is the
one movement mapdemo has never had before: Spans.tracks's []Item value is
the unit's first unbounded array, so TableJsonIsList, TableJsonWriteList and
TableJsonReadList stop being the three unreachable stubs a list-free unit
emits and become the walk. It is the unit's shared vocabulary too, emitted into
every map-bearing .cpp of the unit, which is why all four move identically.
make tables-json-map-walk still reports one map half, byte-identical in ten
map-bearing .cpp files and in no map-free one.

tables/maps/tables.baseline is ADDITIVE, regenerated with its reason through
schema tables-baseline --update over the merge rather than hand-merged. The
value lines record kind=14 elem=4 array=fixed bound=3,
kind=14 elem=13 type=Item array=bounded bound=4,
kind=16 elem=4 array=keyed bound=2 key=Slot,
kind=14 elem=13 type=Item array=unbounded, kind=17 type=string and
kind=17 type=bytes.

Page silences decided, for the owner rather than quietly

1. What a [N]T value's HANDLE is. §2.8 said nothing. Decided: the ARRAY,
   <Entry>Value *, which keeps the extent. The alternative, the decayed
   T *, loses the bound a caller would need to write the last slot, and the
   entry, tables: text map values, string(N), wstring(N) and bytes(N), in the C++ reference (#619) #626's answer for a pair, is not warranted here because the storage
   is one member and reaching it needs no second name. The cost, stated: one
   typedef per such entry in the header.
2. What a BLOB value's const Find answers. §2.8 says a *T value's
   Find answers the resolved pointer. A blob has no declared type and no
   <T>At. Decided: const TableBlob *, through TableBlobAt, which is what
   the same slot answers at a field (§2.5, §6.3), with TableStringViewOf and
   TableBytesViewOf beside it as at a field. The builder handle stays the
   SLOT, which is what TableStringEmplace and TableBytesEmplace fill.
3. Whether an entry's LIST elements ride in the holder's node extent.
   §2.8's memory layout states the pre-order placement for a map inside an
   entry's value and says nothing about a list there. Decided: the same rule,
   because §2.9 makes a list's elements the holder's node extent and an entry
   is by value inside that extent. Both engines and LoadMeasure agree, and
   tables-maps-depth-negative-control is red on it, so it is pinned either
   way and worth a ruling if it should read otherwise.

Named follow-on, found by probing every value kind §2.8 lists

An optional map value's presence companion has no handle (§15, new row).
?T and ?[N]T store the value beside a bool presence companion, which is
two members, so §2.8's handle rule answers the ENTRY. The reference answers the
value member instead, so a caller can fill a map[K]?T's value and cannot set
its presence, and the value is elided on every wire. ?[..N]T is the exception
by accident: its count companion already makes it a pair. Same root cause, one
predicate away, and left for its own issue rather than widened into this one.

Everything else §2.8 lists compiles as the ordinary field it is, each confirmed
by generating a unit and compiling the header and its walk alone: a scalar, an
enum, a flags mask, a declared type, a table by value, *T, a map, and a
union.

Merged, not rebased

origin/main was at bb5f3bd (#626) when this branch resumed with one commit
on it. Integrated with git merge origin/main; the one conflict was
tables/maps/tables.baseline, resolved by taking main's file and regenerating
with schema tables-baseline --update --reason. No golden was hand-merged.

Test

make tables-maps, make tables-json-map-walk and
make tables-maps-negative-controls green. go test ./... green across 30
packages. make test whole; the run is still going as this opens and its result,
with the absent-toolchain failures classified apart, lands in this body.

🤖 Generated with Claude Code

Correction from the cold read

The sentence above claiming everything else §2.8 lists compiles was wrong for one set: arrays of pointers under a map key, [N]*T, [..N]*T and []*T, take the map[K]*T arm through mapValueIsPointer (maps.go:87 tests Type.Pointer alone) and emit ItemAt on an array; red on main too, so inherited rather than introduced here. Owed as #666, the last of #628's class; this PR lands the six kinds it names.