tables: text map values, string(N), wstring(N) and bytes(N), in the C++ reference (#619)

[rowan-claude]

map[K]string(N), map[K]wstring(N) and map[K]bytes(N) now emit C++ that
compiles, and the corpus, the goldens, the oracle and a control say so.

Closes #619.

What lands

The emitter. internal/codegen/cpptable/maps.go gains mapValueIsText,
and mapValueStorageType answers the ENTRY for those three kinds. The entry's
own storage was never wrong: §2.8 makes the entry a real table whose value is
an ordinary field, so it already emitted char value[N + 1] beside
int32_t value_length, the §7.2 row. What was missing was the HANDLE.
mapValueStorageType asked cppFieldType for one type spelling, and that
function answers types, not pairs, so it returned /* ? */ and the entry
surface, Insert, Find and IndexFind all spelled it.

TableEntryValue and TableEntryFound now answer <Entry> * and
const <Entry> *. Nothing about the entry's layout, its descriptor, its codec,
its cook or its text form moves: each of the three was always an ordinary field
of the entry, and only the accessor was unspellable.

The corpus. tables/maps/Text.schema, one table, three maps and a field
past them:

table Text
{
    names map[string(8)]string(16) // kind 12 under a string key
    wide  map[uint16]wstring(6) // kind 33, the value kind that is never a key
    blobs map[int32]bytes(10) // a byte buffer by value, under a signed key
    after int32
}

Both engines. test/tables/maps_main.cpp's test_text_values pins
testdata/wire/tables/map_text.bin, holds measure == save, loads the region
and re-saves it byte for byte, and reads the text form back to the same wire.
test/conformance/harness/maps_test.go gains {"map_text", "Text"}, 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 are the same bytes too:

{
  "names": { "alpha": "first", "beta": "second" },
  "wide": { "5": "Aé中😀" },
  "blobs": { "-3": "3q2+7w==", "2": "AAGA/w==" },
  "after": 9
}

The wide value is five UTF-16 code units ending in a SURROGATE PAIR, so the
transcode runs both ways and a clamp that split the pair would show; the byte
values carry a zero byte and a high byte, which text cannot hold.

Red first

tables/maps/Text.schema landed on its own in 77403e2, before any emitter
change. Against main's emitter the generated header does not compile. clang at
the repo's own table flags, over a translation unit that includes TextTable.h
and nothing else, gives twenty-one errors (clang stops printing at twenty):

TextTable.h:4643:24: error: a type specifier is required for all declarations
 4643 | inline const /* ? */ * TableEntryFound( const TextNamesEntry * entry ) { return entry != NULL ? &entry->value : NULL; }
TextTable.h:4643:81: error: cannot initialize return object of type 'const int *' with an rvalue of type 'const char (*)[17]'
TextTable.h:4719:80: error: cannot initialize return object of type 'const int *' with an rvalue of type 'const char16_t (*)[7]'
TextTable.h:4797:81: error: cannot initialize return object of type 'const int *' with an rvalue of type 'const uint8_t (*)[10]'

The pointer types in those three messages are the whole diagnosis: the storage
was already char[17], char16_t[7] and uint8_t[10], and only the return
type was unspellable.

The control

tables-maps-value-reset-negative-control drops TableResetMapValue at its
call site in TableMapPlace, so a DUPLICATE key no longer resets the value
half §2.8 says is reset WHOLE. A TEXT value is where that bites hardest, which
is why the control arrives with Text: the storage is a PAIR, so the repeat
rides the first insert's bytes AND its length.

RED under the sabotage, three of the four in the new rows:

FAIL test/tables/maps_main.cpp:257: again->health = 100, want 0
FAIL test/tables/maps_main.cpp:1453: repeat != NULL && repeat->value_length == 0
FAIL test/tables/maps_main.cpp:1454: repeat != NULL && repeat->value[0] == 0
FAIL test/tables/maps_main.cpp:1468: landed != NULL && landed->value_length == 0
4 map check(s) failed
negative control: valuereset turns the MAP GATE red — 4 failures

GREEN without it:

maps: all checks passed (docs/SPEC-TABLES.md §2.8)

Stated plainly: that sabotage was reachable before this PR too, through the
Fleet row at line 257. What the new rows add is the PAIR half of the
evidence, the two members a text value's storage is.

The compile-time half of the fix has no runtime control, and cannot: a sabotage
of the storage line does not produce a binary to run. Its evidence is the
red-first quote above.

The goldens

NEW: testdata/golden/tables/maps/TextTable.{h,cpp} and
testdata/wire/tables/map_text.bin.

MOVED, and every one is the UNIT'S SHARED VOCABULARY (§3.3) growing because
mapdemo gained four tables, Text and the three entries its 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	44	50
kTableMessageEntriesHere	44	52
kTableNodeTableFieldSlot	33	40
kTableAnnounceBytes	521	615
BuildVersion	0xe763b68d79174b68	0x28abc7f5927a7539

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,
521 to 615 bytes, and map_full_message stays 172 bytes and repacks, because a
body's type reference is an index into that vocabulary. Those hunks are the
whole diff in DepthTable.h, FleetTable.h and RowsTable.h.

AND SINCE THE MERGE with origin/main (#615, retain-unknown), one more row of the
same class: kTableRetainKnownIds, a unit-wide sorted list of known field ids,
44 to 50, growing by the six the Text unit adds. TextTable.h is regenerated
whole over that merge, because it was first generated before it.

tables/maps/tables.baseline is ADDITIVE, updated with its reason: the Text
line and the three anonymous entry lines §2.8 keys by the holder's and the
field's wire id. The value lines record kind=12 size=16, kind=33 size=6 and
kind=14 elem=6 size=10.

Page silences decided, for the owner rather than quietly

1. What a text value's HANDLE is. §2.8 makes the entry a real table whose
   value is an ordinary field, and §7.2 gives that field a buffer beside an
   int32 length. Neither says what Find, Insert and Each hand back when
   the value's storage is TWO members. Decided: the ENTRY, which reaches both.
   The two alternatives were rejected on the page's own words. A pointer to the
   buffer alone loses the length an Insert exists to let a caller set. And
   wrapping the pair in an unnamed struct, the way §2.6 does for a union ARM,
   would move offsetof( Entry, value_length ), which the descriptor's
   count_offset spells (§8.1), and would contradict §2.8's "It has two
   fields". The cost of the decision, stated: the handle also reaches key, so
   a caller CAN write it and break the order. The emitted comment says not to.
   If the page would rather have a narrower handle, this is the line to rule on.

2. A bytes(N) value's framing under a map key. §4.2's fuzz list names
   kind 33 under a map key and says nothing about a byte buffer there. Decided:
   the value takes the FIELD's framing, kind 14 over element kind 6, because
   §2.8's rule is that a value is a field of the entry and nothing in it carves
   an exception. The baseline records it that way.

3. The text form of a text value under a map key. §16.2's map[K]V row
   says the value takes its own row; §2.8's worked example only ever shows a
   table value. Decided: the value's own §16.2 row verbatim, a string as
   itself, wstring(N) transcoded to UTF-8, bytes(N) base64 and padded. Both
   engines produce the same bytes, quoted above, so this is now pinned either
   way and worth a ruling if it should read otherwise.

Not a silence, checked and closed: a map value never carries a declared
default. The parser refuses a default on the map FIELD by name, and the grammar
has no place to spell one on the value, so the elision rule is exercised at the
empty end only.

Neighbours found and NOT fixed here

The same root cause reaches four more value kinds that #619 does not name. Each
was confirmed by generating and compiling, and each is left for its own issue
rather than widened into this one:

• map[K][N]T, map[K][..N]T, map[K][E]T and map[K][]T:
  mapValueStorageType answers the ELEMENT type, so &entry->value is a
  pointer to an array and the header does not compile. Same class, different
  kinds.
• map[K]*string and map[K]*bytes: mapValueIsPointer is true and
  TableEntryFound spells %sAt( entry->value ) from value.Type.Name, which
  a blob has none of, so the header carries At( entry->value ) and does not
  compile.

map[K]*wstring is refused by name at the front end and is not in that set.

Merged, not rebased

origin/main moved mid-branch when #615 landed. Integrated with
git merge origin/main, then make update-goldens over the merge. No golden
was hand-merged.

Test

make test whole, log kept. Five hard failures, all Error 127, all the
absent toolchains this box was briefed to have: dotnet (build-cs-cook,
build-conformance-cs), dart (build/conformance-dart), elixirc
(build/elixir-tables-ebin), and javac under a dist/ that does not exist
(build-conformance-java). Nothing else failed: every other FAILED line in
the log is a negative control going red on purpose. The C++, C, Go and Rust
legs built and ran. go test ./... is green across 30 packages.

🤖 Generated with Claude Code