An array is a reference to a header that never moves (#453, #477)

[ASDAlexander77]

PR 2 of 3 for arrays as references (spec: tslang/docs/superpowers/specs/2026-10-03-array-reference-design.md, plan: tslang/docs/superpowers/plans/2026-10-03-array-reference.md). PR 1 (#478, the ArrayLayout helper) is merged; PR 3 (amortised growth) follows.

The representation

An array value (T[], the typed-array aliases, string[]) is now one pointer to a heap header { data, length, capacity } that never moves; only data is reallocated. Assigning, passing, returning, storing, capturing and boxing copy the pointer, and === compares headers, so push, pop, splice and length = through any name are seen through every name (#453). Capacity equals length in this PR.

• gc: header and data from GC_malloc. none: nothing freed, one more allocation. rc: the header is the counted block; it holds one counted reference to its data block (see the amendment below). own: the header is a single-owned block; a borrowed array parameter is the owner's header, so a push through it is the owner's. Own's rules are unchanged (aliases stay compile errors).
• The ABI of every function taking or returning an array changes; objects built before this PR do not link with objects built after it.
• Debug info: an array is a pointer to a { data, length, capacity } struct.

Rulings

• R1 - null header = empty array. A null header (zeroed element of new Array<T[]>(n), a field with no initializer, undefined cast to an array) reads as an empty array; an op that changes an array through its slot stores a fresh empty header into a null slot first. Documented edge (spec section 3): a null slot passed by value to a parameter (an unset field, an element made by length =) - a push through the parameter materialises a header in the parameter's copy, so the slot's owner does not see it and, under rc and own, that header leaks. Accepted: such a slot holds undefined in TypeScript terms, where .push would throw.
• R3 - rest copy built in MLIRGen. [a, ...rest] = src gives rest a new array holding a copy of the slice (Array destructuring rest element aliases the source array (writes leak into it; rc crash on push) #477), built in MLIRGen (a new array of the slice's length and an element copy) instead of ts.ArrayView, so the ownership passes see a fresh array.
• main's argv (replaces the plan's R2). argv is Ref<string> (C's char **) only. A main(argc, argv: string[]) is a compile error naming the Ref<string> form, under the JIT and ahead of time (--emit=exe/obj); a DLL has no main entry point and is not checked.
• Amendment found by the default library gate (spec section 4, rc). The first version freed the data block outright when the header died ("the header holds its only reference"). The default library makes strings over an array's data block (<string><Opaque>Ref(buffer[0]) in convertNumber, convertInteger and the date formatters), and such a string takes a reference to the block, so under rc five default-library tests read freed memory ahead of time. Now under rc the data block keeps its own count: the header holds one reference (given when the header is made over the block, or when an empty array's first change allocates it), and the block and its elements are freed on the block's last reference, as on main. Under own the header still frees its block outright. A reallocating change still moves the block under such a string, as on main. Please overrule here if the intent was different.

Tests added

• 00array_reference.ts - the 14 shapes of spec section 2 as asserts (compile, JIT, rc and none corpora).
• 00array_rest_copy.ts (Array destructuring rest element aliases the source array (writes leak into it; rc crash on push) #477), 00array_zero_slots.ts, 00array_static_nested.ts, 00array_view.ts (updated: element counts per view).
• 00array_data_string_alias.ts - a string made over an array's data block outlives the array (fails under rc, JIT, -O0 and -O3, without the amendment).
• own/own_array_param_push.ts - a push through a borrowed parameter is the owner's (JIT, compile, no-counting); the pre-switch compiler (alpha88, gc) fails its assert.
• lowering-errors/main_argv_string_array.ts - the argv error under --emit=jit, exe, obj, and no error under --emit=dll (linked from the build tree, -mm=none, so it does not depend on GC_LIB_PATH/TSLANG_LIB_PATH).

Gates

Gate	Result
Windows Release suite (ctest -C Release -j 12 --timeout 300, DEFAULT_LIB_PATH = the rebuilt default library)	3734 / 3734 passed
Linux (WSL, this diff applied on origin/main 5e203fc, ninja release, ctest -j 8 --timeout 300)	3719 / 3719 passed (1 pre-existing disabled test). The first run failed only the argv DLL test (link needed GC_LIB_PATH), fixed in this PR
own corpus (--emit=llvm -mm=own --no-default-lib, every file of test/tester/tests)	plain 454 / 593, --opt 452 / 593; main's baseline 453 / 593 and 451 / 593 (+1 is 00nullable_to_any, added on main after the baseline). No file goes from ok to failing. Changed first errors: 00types, callWithSpread (run-to-run hash in a name), 00var_bindings (still rejected, by the element-borrow rule instead)
own memory (measure.ps1, AOT -O3)	flat - see below
default library rebuilt (release and debug, gc / rc / none) and its suite run under each model, release/debug x compile/JIT	gc 159/159 x4; rc 158/159 x4; none 158/159 x4 - the one failure is weakref_basic, gc-only by design (#420)
test-compile-gc-defaultlib-collector (+ JIT twin) with the rebuilt library	pass (fails against a library built before the switch, as expected)

Memory, MB (gc / rc / none / own):

program	this PR	own spec's last numbers
own_fresh_string	5.9 / 4.4 / 81.1 / 4.4	5.8 / 4.2 / 80.9 / 4.2
own_return_new	5.9 / 4.4 / 50.4 / 4.4	5.8 / 4.2 / 50.2 / 4.2
own_try_local	5.9 / 8.3 / 6.7 / 6.7	5.9 / 6.5 / 6.5 / 6.5
own_fresh_array	5.7 / 4.4 / 4.3 / 4.4	5.6 / 4.2 / 4.2 / 4.2
own_literals	5.7 / 4.4 / 4.3 / 4.4	5.6 / 4.1 / 4.1 / 4.1
own_array_param_push (new)	5.8 / 4.4 / 4.3 / 4.4	-
Shared leaf in two arrays, 20000	5.9 / 4.4 / 13.4 / 4.4	5.9 / 4.4 / 10.6 / 4.4
Shared leaf in two arrays, 200000	5.9 / 4.4 / 93.5 / 4.4	5.9 / 4.4 / 65.9 / 4.4
push through a parameter + spread copy, 200000	6.0 / 4.4 / 50.4 / 4.4	-

own and rc stay flat. none grows by the extra header per array (it frees nothing). own_try_local under rc is the known throw-path leak (a local is not released when the function throws, under every model): it now leaks a header and a data block per throw.

After merge

• The default library must be rebuilt with this compiler for every model and both build types - the array ABI changed - including CI's default-library artifact. Installs built before this PR will not link with programs built after it.
• Follow-up filed: Pushing onto an array inside a constant tuple literal crashes (realloc of static data) #479 - a push onto an array inside an unannotated constant tuple literal writes into constant global data (pre-existing; the old layout also pushed onto static data).

Closes #453
Closes #477

🤖 Generated with Claude Code