spec: unbounded []T and []*T in the variable class (#523)

[gafferongames]

Ruling 3 on #523: unbounded []T and []*T in the variable class, yes. The map's storage, walks and measure without the key and the sort, wire-neutral under the existing kind and 64-bit lengths.

Specification only, no code. New §2.9, plus the clauses the construct needs in §2, §2.2, §2.6, §2.8, §3, §4, §4.1, §6.5, §6.6, §7.2, §7.4, §8.1, §11, §15, §16.2, §18.1, §18.2, §20.1 and §20.2, and one clause in SPEC.md §1.

Updated for the cold read of #531: three owner rulings and thirteen named changes, all made.

The construct

• []T and []*T, legal in a table body only. A type body refuses one by name, which keeps SPEC.md's "no unbounded collections" true of the type wire and refuses one on a packet. A UNION ARM refuses one too (ruling below).
• Storage is the map's slot exactly: an int64 self-relative TableRef and an int32 count, sixteen bytes, with the elements laid by value in the holder's node extent at alignof( T ), zero slack. Lists and maps are one population in that extent, placed pre-order in the declaration order of the fields that hold them.
• The wire is the existing kind 14 at the element's own element kind with the live count, elided at zero. []T and [..N]T are the same bytes, and a bound is added or removed without touching a stored file.
• LoadMeasure's term is N × sizeof( T ) rounded up to alignof( T ), at every depth, reached by the same header walk a map's N needs. The block form is none, by absence.

The three owner rulings from the cold read

1. Erase exists, by the map's own mechanism. An element is erased by its pointer — dead bit in the segment's slot, live count decremented, the four walks skip it — exactly as a map entry is, with the storage reclaimed at reset and never reused mid-build. The key is what differs: a map erases by the key, a list by the element's own address, which is the one thing the builder already promises never moves. Why the builder carries it: the save-edit cycle (LoadBuilder, edit, Save) is the tool's path, and a game's inventory removes items in slot order, which a map[K]T keyed by an id cannot keep. Indices are not stable across an erase and the pointer is, which is why the pointer is the handle.
   The retention paragraph now states §6.6's hazard honestly: on the region path a list's count and elements are ordinary writable memory like any array's, §6.6's rule applies unchanged, and the builder is irrelevant to retention because retention is a region round trip.
2. LoadMeasure's -1 carries a reason, from the same enum ruling 8 gives Open and BlockOpen (§7, §19.2), with the same spellings in every target. Stated once in §6.5 as a table, on §7's own rule of one value per clause: unknown_form, count_over_length, count_over_extent_cap, blob_over_size_cap, data_cycle (the authoring side's). §2.9 cites it rather than restating it. A refusal still moves no counter.
3. The index accessor is bounds-checked in every build, on §2.4's rule and for §2.4's reason: size() came from a file, NDEBUG does not remove the compare, and there is no undefined-behavior path in any configuration. C++ asserts then aborts, C# throws, Rust and Go panic.
4. A map is not a union arm either, refused by name in §2.6 and §11 on the same ground []T is: both put their elements in the holder's node extent through a placement walk over what the record reaches by value, and an arm is reached by value only when its tag says so, so an arm's array would make the extent's contents and every offset after it depend on a discriminant — a layout no cook can be byte-stable under and no cook-check clause can bound. §2.6's admission of a map at an arm predates this PR; it is corrected here because §2.9's refusal made it load-bearing. No corpus schema declares one, so the refusal breaks nothing, and §20.2's arm grammar already excluded array=map — the prose now says why.

The thirteen named changes

1. Both overflow outcomes, per path, as a two-row table: into a region, LoadMeasure answers -1 with its reason, no Load, no report; into a builder, a count the body cannot cover is §4's malformed with the covered prefix kept, and a count above the int32 cap is a NULL from LoadBuilder with the partial builder discarded and the report as it stood. "Never disagree about a wire" is scoped: the two paths agree on every wire either of them decodes, and where they differ is at a refusal, which is not a decode. The five LoadMeasure controls moved off the report surface.
2. The [][]T fix is a TABLE wrapper, spelled — SPEC.md's "wrap the inner array in a type" does not reach here, because a type body refuses a list:

   table Row   { items []Sample }
   table Sheet { rows  []Row }
   

3. The int32 cap control is a named unit test, make tables-list-measure-refusals, with synthetic counts: no golden can carry two gigabytes, and a refusal produces no counters for a report row to pin. It covers the cap, the count over L, both at depth, and a clean wire beside them.
4. The baseline rule replaces the arm-disjointness analogy: bound= appearing or vanishing on an array= move is the capacity fact, judged as a shrink (warn) or a growth (silence); elem=, type=, enum=, union= and kind= keep judging exactly as before. It still bumps no rendering version.
5. unbounded added to §20.2's array= grammar, with the prose and a row in §20.1's fact table. It carries no bound=, for the map's reason.
6. §8.1 now carries the rule for a map's and a list's descriptor — neither had one — as one shape for both: kind/element kind, element_size as the pitch, counted with count_offset, table naming the element's descriptor, and array_bound = 0 as the one tell that the field's offset names an int64 reference rather than the first element. Zero is free because every other shape's bound is at least one, so it costs no new column in nine ports.
   Backend status is stated on the page, because the reference does not carry it yet. The C++ map descriptor emitted today leaves kind at 0 and is_array false and describes the map through the entry's own TableTypeInfo beside three map-specific function columns (map_count, map_at, map_insert). It moves to the columns above when the list lands, and they land together for one reason: a second out-of-line shape would otherwise need a second set of function columns, and three per construct is how a descriptor becomes a per-construct API instead of a vocabulary. The resolver the text walk genuinely cannot spell for itself stays; what changes is that the SHAPE is read from the array columns like every other array's rather than inferred from a non-NULL entry.
7. []T as a union arm: refused by name in §2.6 and §11. An arm's storage is overlaid and a list's elements live in the holder's node extent for every list the record reaches by value, so an arm's array would make the extent depend on the tag. An arm holding a list is a table arm's job.
8. The clamp control's count is pinned above 2^16 (100,000 elements), so no bound a control author happens to pick can clamp it and let the row pass.
9. list_migrates golden added: one content, two declarations of the holder ([..N]T and []T), one pinned wire both write byte for byte and both read into equal values, report silent both directions. list_erased added beside it for the dead-element control.
10. SPEC.md §1's non-goal scoped to the type wire, naming the table wire's map and []T and why neither is reachable from a packet.
11. Cites fixed: §4.2 for the truncated bound, §4.3 for arrays of arrays; ?[..N]T (a presence bit on the array, landed) distinguished from []?T (an element's presence bit, a follow-on); and the additions count corrected against the bullets that follow it.
12. string(N) and bytes(N) dropped from the element-set sentence, which is now the rule rather than a list: whatever [..N]T admits, []T admits, and whatever it refuses, []T refuses on the bounded array's own diagnostic.
13. []*T with a null slot named as what serves the []?T case today.

The decisions the page made beyond the ruling

The element set is [..N]T's and not the map's value list, so every element refusal is one an array already carries; no entry type is generated, which is where four of the map's six framing bytes an entry go; clamped cannot fire on the count; what bounds a load is the arena, the caller's allocation under LoadMeasure, and the int32 count slot; the construct claims three names against its field (Add, Each, Erase) where a map claims eight; §4.1's silent class stays at four; retain-unknown addresses an element by its ordinal (§6.6); and position here is not a vocabulary, so §2.4's [E.Max]T refusal is not reopened.

Ports

Backend status is the map's: the C++ reference and the tool carry it, every other backend refuses a unit that declares one by name, and the ports are a named follow-on (§15). What a port needs is smaller than what a map needed, by exactly the key.

Merge check

Rebased onto main at 8fd34f1 (after #507, #527, #529, #530). git merge-tree --write-tree reports zero conflicts against main and against #532's head. #530's §3.3, its reserved-id rule and its §5/§11 edits touch nothing this PR touches: an unbounded array spends no reserved id and adds no framing, so the message form carries it exactly as the file form does. The §11 and §6.6 edits were re-checked in place after the rebase.

Two edits were deliberately relocated to keep them off lines #532 touches: the §11 runtime-name claim and the §16.2 text row.

One landing-order note: §6.5's refusal-reason table shares the enum ruling 8 gives Open and BlockOpen, which #532 defines as TableOpenReason. This page refers to it by description and by section rather than by type name, so nothing here claims that name or conflicts with it. Whichever of the two merges second adds the back-reference; a build with one has the other.

🤖 Generated with Claude Code

[gafferongames]

Rulings from the cold read, under the owner's word of 2026-09-04:

1. Erase exists, by the map's own mechanism: an element erased by its pointer is marked dead with a live count and the four walks skip it. The save-edit cycle is the tool's path, and an inventory removes items in slot order, which a map by id cannot keep.
2. LoadMeasure's -1 carries a reason from the enum family Open and BlockOpen received (unknown form, count over L, count over the int32 cap, a cycle), the same names in every target.
3. The index accessor's bounds check stands in every build, as the keyed accessor's does: one compare per index over data from a file, no undefined-behavior path in release.
4. A []T is not a union arm, refused by name.

The named page changes from the read land on this branch before it leaves draft.