tables: the C++ codec for unbounded arrays (#531)

[gafferongames]

The second half of #531, after #548 landed the front end, the IR, the tool's wire and text halves and every backend's refusal by name. The C++ reference now carries the codec, held by the tables/lists corpus, and the page's §2.9 status line is gone.

What lands

• The TableList runtime: the sixteen-byte slot (a self-relative reference and an int32 count), segments carved from the builder's arena in bulk, the dead bit and the live count, Add answering NULL at the arena or at the int32 cap, Erase by the element's own pointer, Each in index order over live elements, and a const form whose size(), operator[] and iteration are members of the storage type. operator[] is bounds-checked in every build, NDEBUG included, on §2.4's rule.
• Measure, write and read for the five element classes: scalar, enum or flags, union, table by value, and *T. The four writing walks run in index order and skip dead elements. measure == save holds on every instance.
• The node extent and pack: a holder's storage is its record plus the extent its lists and maps command, in declaration order, pre-order. An unreached non-empty list slot is refused by Cook and by Lock.
• The cook write side and schema cook-check's element-array clause (§7.4): containment, alignment, fit and no overlap against the holder's own extent, then the elements' own slots, companions and tags. The gate writes cooks from the runtime, checks them with the tool, and refuses a forgery whose list slot points past its holder.
• The JSON walk both ways: a list as a JSON array in index order, read back element by element, one list half emitted only in a unit that declares one, byte-identical across the corpus, absent from a list-free unit.
• The §8.1 descriptor migration, with the map's emission moved to the same columns in this PR as the page says: kind is the element kind, is_array set, array_bound = 0 the tell for an out-of-line array, counted with count_offset naming the count, element_size the pitch, and one function column, place, serving both constructs.
• LoadMeasure's -1 with a reason: TableRefuseReason as a native C++ enum carried as a trailing out-parameter (TableRefuseReason * reason_out = NULL), never an exception, with the two values this PR needs, count_over_length and count_over_extent_cap, emitted only by a unit that declares a map or a list. The other three values are owed as schema#523 and the page says so.
• The two overflow outcomes per path: the region load refuses with a reason and no report, the builder load counts malformed.
• The corpus tables/lists: list_empty, list_scalars, list_tables, list_mixed, list_shared, list_before_pointer, list_erased, list_of_maps, list_nested and the migration golden list_migrates (one content, two declarations, one pinned wire, both read into equal values), each crossing the wire, the text and the cook in test/tables/lists_main.cpp, wire goldens pinned under testdata/wire/tables/, header goldens under testdata/golden/tables/lists/, the two cooks pinned beside the wires.
• make tables-list-measure-refusals: four synthetic wires (a count above the int32 cap, a count the field's L cannot carry, both at depth inside an element's own list) each answering -1 with its own reason, a clean wire beside them that measures, and no report counter moved.
• The clamp control at 100,000 elements, past 2^16, decoded count checked.
• Rulings on tool: unbounded arrays in the front end, the IR and the tool's wire and text (#531) #548 applied: bar attributes on a []T qualify the element as on a [..N]T (§2.9 and §11 restated), a list renders kind=14 in the cook projection where a bounded array renders its element's kind (§20.2), []?T unreachable stands.

What this PR changed on the way

• schema cook-check refuses a MAP SLOT by name where its scan meets one, instead of refusing every cook from a unit that declares a map anywhere. The unit-level refusal made the whole tables/lists corpus uncheckable because one holder's element carries a map. The scan's refusal names Squad.roster, the reference that reads it, and schema#380 as the PR that lands the map's clause (§7.4 item 4), which stays owed. A cook of a map-free root in the same unit checks as any other does. internal/tablecook holds the test, and the gate asserts the map-holding cook is refused on exactly that clause.
• Two Makefile defects in the work in progress: a blank line inside the aggregate controls target's continuation had ended its dependency list, and the element-kind control's sed script carried commas and an unbalanced parenthesis that $(call) split and cut. Both fixed, the aggregate target now runs all twelve.

Gates

lists: all checks passed (docs/SPEC-TABLES.md §2.9)            [build/schema_test_lists]
lists: all checks passed (docs/SPEC-TABLES.md §2.9)            [build/schema_test_lists_asan]
list gate: cook-check reads two cooks the runtime wrote, refuses the forged list slot, and refuses the map-holding cook by name
list measure refusals: four -1s with their reasons, one clean measure, no counter moved (docs/SPEC-TABLES.md §2.9, §6.5)
tables list-walk gate: one list half, byte-identical in 5 list-bearing .cpp files, and none in a list-free one

Every negative control the page names, red on a CHECK:

negative control: allocation turns the LIST GATE red
negative control: order turns the LIST GATE red: 76 failures
negative control: dead turns the LIST GATE red: 4 failures
negative control: preorder turns the LIST GATE red: 4 failures
negative control: walkorder turns the LIST GATE red: 1 failures
negative control: shared turns the LIST GATE red: 9 failures
negative control: clamp turns the LIST GATE red: 4 failures
negative control: elemkind turns the LIST GATE red: 6 failures
negative control: depth turns the LIST GATE red: 28 failures
negative control: fit turns the LIST GATE red: 6 failures
negative control: unreached turns the LIST GATE red: 3 failures
negative control: dropping cook-check's element-array clause turns its test RED

The checker's refusals (type-body, []Self, the claimed names) and the build-version rule are held in compiler and internal/check tests. go test ./... green. The committed generated/ tree regenerated as CI does and current: the one moved file is generated/bench/tables/cpp/BenchTableTable.cpp, the list-free bench unit gaining the JSON walk's list adapter stubs (TableJsonIsList answering false) exactly as it carries the map's.

The zero-cost law (#546)

The table read and write benchmarks over the existing corpus (bench/corpus/BenchTable.schema, corpus_id b51387f36d9b59c4, 2147 wire bytes per record), before at d46eea1e (origin/main) and after at this branch, the same bench/tables/cpp/table_main.cpp against each tree's generated/bench/tables/cpp/BenchTableTable.h. The two leg binaries are byte-identical (cmp clean, 106408 bytes each): the one moved file in the bench unit is BenchTableTable.cpp's JSON walk, which the leg does not compile, and the header is unchanged. The sitting is therefore a noise reading of one machine code, and it reads as one.

MacBook Air M2, 2026-09-05 08:31, five interleaved rounds (§2.4), --round K each, one-minute load 1.95 when the sitting started and 2.04 to 2.09 with the bench itself running (macOS, no core pinning, Spotlight had just finished indexing a worktree).

path	before, median of 5 (msg/s)	after, median of 5 (msg/s)	before's own spread	after's own spread
write	759271	759190	754694 to 761728 (0.9%)	741292 to 761748 (2.7%)
round_trip	260774	256508	256606 to 262569 (2.3%)	255580 to 261912 (2.5%)

Unchanged within noise: write 0.01% apart, round_trip 1.6% apart with each side's own spread wider than the gap. No cost measured, none landed.

Owed, named

• The tool's COOK and UNCOOK halves for a []T, beside the map's (§15).
• schema cook-check's map-slot clause, §7.4 item 4, schema#380.
• The three remaining TableRefuseReason values, §7's check order and §19.2's block clauses, schema#523.
• The ports, one per language, on the page's terms (§15).

#366

The C++ cell for unbounded arrays moves to ✅. Every other column stays ❌, refusing by name.

🤖 Generated with Claude Code