@yabgu_gm/tensionscript 0.11.4 → 0.12.0

package/README.md

@@ -52,7 +52,9 @@ shares, and how it stays current: [`docs/fork-posture.md`](docs/fork-posture.md)
   TensionScript name), `COPY_STRUCT`, and a C-compatible `sizeof` that includes
   trailing padding. A `layout_hash` computed against the engine catches layout
   drift when a session opens. See [showcase §1](docs/showcase.md) and
-  §2 for `@managed struct`.
+  §2 for `@managed struct`. The external contract for the dynamic-array form —
+  `include/`, and [`docs/interop-c-abi.md`](docs/interop-c-abi.md) — is what a C
+  consumer includes; it is checked by `npm run check:headers`.
 - **Value types.** `@inline struct` gives a record value semantics: SROA locals,
   copy on assignment, flattened (SROA) parameters, sret returns through a hidden
   destination parameter, an `@external` argument temp, and an export-side byval

package/dist/asc.generated.d.ts

@@ -1763,6 +1763,8 @@ declare module "types:tensionscript/src/common" {
         const Object = "Object";
         const Array = "Array";
         const StaticArray = "StaticArray";
+        /** The descriptor behind `@managed @dynamic [T * n]` (Landing 4d.1). */
+        const DynamicArray = "DynamicArray";
         const Set = "Set";
         const Map = "Map";
         const Function = "Function";
@@ -3083,6 +3085,57 @@ declare module "types:tensionscript/src/resolver" {
          * `@unmanaged` records carry GC edges they cannot describe. Refused by name.
          */
         private resolveFixedArrayType;
+        /**
+         * Resolves an {@link UnmanagedArrayTypeNode} to a
+         * {@link TypeKind.UnmanagedArray}.
+         *
+         * Deliberately **not** a copy of {@link resolveFixedArrayType}: none of that
+         * function's refusals belong here, and copying them would refuse the form's
+         * whole purpose.
+         *
+         * A fixed array *contains* its elements, so a record element would claim `N`
+         * records sit inline -- refused by name (`resolver.ts`, the `AS100` record
+         * arm). An unmanaged array contains one address, so a record element is the
+         * ordinary case: `[BodyState *]` is a pointer to a run of records, which is
+         * exactly what the collision solver needs and what `BodyState[N]` cannot say.
+         *
+         * What *is* refused is an element with no bytes to point at, which is the same
+         * `byteSize` question `sizeof` asks. An `@inline` element is admitted here on
+         * purpose: it is a value type with a layout, and a pointer to it is a pointer
+         * to those bytes -- the refusal that applies to it is the *field* form's, not
+         * the pointer's.
+         *
+         * A **GC-managed** element is refused (see the arm below). Measured before it
+         * existed: `[Foo *]` over a `class Foo` compiled and emitted
+         * `base + i*4`, `i32.load`, `call Foo#get:x` -- the buffer holds bare
+         * references that nothing scans.
+         */
+        private resolveUnmanagedArrayType;
+        /**
+         * Resolves a {@link DynamicArrayTypeNode} to a {@link TypeKind.DynamicArray}.
+         *
+         * The type is **one pointer** to a `[u32 length][pad][data]` header; the length
+         * is not in the type, which is the whole point — it is a runtime value, read
+         * from the buffer. `n` is spelling here and a binding where a function scope
+         * exists (see `Program#bindDynamicLengthLocals`).
+         *
+         * Three refusals, each for a different reason:
+         *
+         * - **`@managed`** is Landing 4d. The buffer would need a collector-visible
+         *   header, which this landing does not produce.
+         *
+         * - **No model at all** cannot be honoured by any emitter: an inline
+         *   runtime-length array would need variable stack allocation, which WASM does
+         *   not have. Naming a model is the source saying where the bytes live.
+         *
+         * - **A GC-managed element** is the same hazard Landing 3's CX1 closed for
+         *   `[T *]`: the buffer is not scanned, so a reference stored in it is not a
+         *   root.
+         *
+         * An `@inline` element is accepted: it is a value type, so its extent is
+         * `byteSize` and Landing 3 measured that stride works.
+         */
+        private resolveDynamicArrayType;
         private resolveTupleType;
         private resolveBuiltinNotNullableType;
         /** Resolves a type name to the program element it refers to. */
@@ -3195,6 +3248,28 @@ declare module "types:tensionscript/src/resolver" {
         private lookupPropertyAccessExpression;
         /** Resolves a property access expression to its static type. */
         private resolvePropertyAccessExpression;
+        /**
+         * The element type of an array-kind receiver, or `null` when `type` is not one.
+         *
+         * Three kinds answer here, and they are one family even though only two are a
+         * `TypeKind`:
+         *
+         * - `[T *]` — `TypeKind.UnmanagedArray`, element on the type;
+         * - `@unmanaged @dynamic [T * n]` — `TypeKind.DynamicArray`, element on the type;
+         * - `@managed @dynamic [T * n]` — a **class reference** to the std
+         *   `DynamicArray<T>` descriptor (Landing 4d.1), so the element is the class's
+         *   type argument.
+         *
+         * The third case is why this is a helper. Landing 2 added the first arm by
+         * hand, Landing 4b added the second by hand, and the managed form would be the
+         * third copy of the same two-line idea — in two places, since the element is
+         * wanted both as a *type* (`resolveElementAccessExpression`) and as an
+         * *element* (`lookupElementAccessExpression`, which peels `y[i].field` through
+         * the element's class). One definition, three kinds, two consumers.
+         */
+        private arrayKindElementType;
+        /** Whether `classReference` is the std `DynamicArray<T>` descriptor class. */
+        private isManagedDynamicArrayClass;
         /** Looks up the program element the specified element access expression refers to. */
         private lookupElementAccessExpression;
         /** Resolves an element access expression to its static type. */
@@ -3465,6 +3540,25 @@ declare module "types:tensionscript/src/parser" {
         finish(): void;
         /** Parses a type name. */
         parseTypeName(tn: Tokenizer): TypeName | null;
+        /**
+         * Whether a `[` at the start of a type begins the unmanaged-array family
+         * (`[T *]`, `[T * N]`) rather than a tuple.
+         *
+         * The discriminator is one token after the element type: `*` commits, and
+         * anything else (`]`, `,`, `:`, `|`) belongs to the tuple arm. The lookahead
+         * speculates with errors suppressed and rewinds either way -- the same shape
+         * as `tryParseFunctionType` / `tryParseSignatureIsSignature`, and the reason
+         * the tuple arm's body needs no change: it is entered with the tokenizer
+         * exactly where its own `tn.skip(Token.CloseBracket)` expects it.
+         *
+         * A pre-type decorator is excluded before speculating. `parseType`'s decorator
+         * arm reports `AS212` ("Decorator '@x' is not valid here") *before*
+         * `suppressErrors` is consulted, so speculating into `[@unmanaged T *]` would
+         * emit a diagnostic for a form this family does not accept anyway -- and then
+         * emit the tuple/`Type expected` error on the rewind, giving two errors for
+         * one mistake.
+         */
+        startsUnmanagedArrayType(tn: Tokenizer): boolean;
         /** Parses a type. */
         parseType(tn: Tokenizer, acceptParenthesized?: boolean, suppressErrors?: boolean): TypeNode | null;
         private tryParseSignatureIsSignature;
@@ -3764,6 +3858,17 @@ declare module "types:tensionscript/src/program" {
         /** Gets the standard `StaticArray` prototype. */
         get staticArrayPrototype(): ClassPrototype;
         private _staticArrayPrototype;
+        /**
+         * Gets the `DynamicArray` prototype — the descriptor class behind
+         * `@managed @dynamic [T * n]`.
+         *
+         * Follows `staticArrayPrototype` exactly: a lazily-cached `require` of the
+         * std prototype, so `@managed @dynamic [T * n]` can resolve through
+         * `resolveClass(program.dynamicArrayPrototype, [elementType])` and come back
+         * as an ordinary generic class instance.
+         */
+        get dynamicArrayPrototype(): ClassPrototype;
+        private _dynamicArrayPrototype;
         /** Gets the standard `Set` prototype. */
         get setPrototype(): ClassPrototype;
         private _setPrototype;
@@ -4430,6 +4535,15 @@ declare module "types:tensionscript/src/program" {
          * is what gives it one `i32` slot instead of the record's reference type.
          */
         isViewLocal: boolean;
+        /**
+         * Whether this local is a **dynamic-array length binding** — the `n` in
+         * `[T * n]`, introduced by the signature rather than written as a declaration.
+         *
+         * It is read-only by construction: its value comes from the buffer header at
+         * function entry, so assigning it would make the compiler's idea of the length
+         * disagree with the buffer's. The assignment and shadowing rules key on this.
+         */
+        isDynamicLength: boolean;
         /** Constructs a new local variable. */
         constructor(
         /** Simple name. */
@@ -4886,7 +5000,37 @@ declare module "types:tensionscript/src/types" {
         /** String iterator. */
         StringviewIter = 25,
         /** No return type. */
-        Void = 26
+        Void = 26,
+        /**
+         * A pointer to `T` with unknown length, `[T *]`.
+         *
+         * **Appended at the end**, not beside {@link FixedArray}, on purpose. This is
+         * a `const enum` with implicit numbering, so an insert would renumber the
+         * twelve kinds between `FixedArray` and `Void`; the compiler is self-hosted, so
+         * a partial rebuild could then disagree with `dist/` about what
+         * `TypeKind.Extern` means -- silently. The order here carries no meaning.
+         *
+         * One slot holding an address: not a value (no extent to inline), not a
+         * reference (the collector owns nothing). `toRef` answers the pointer type,
+         * which is what lets a `[T *]` parameter, local, global and return bind as one
+         * slot where `T[N]` reaches `Type#toRef`'s `assert(false)`.
+         */
+        UnmanagedArray = 27,
+        /**
+         * `@unmanaged @dynamic [T * n]` — a header-prefixed array whose length is a
+         * runtime value.
+         *
+         * Appended for the same reason {@link UnmanagedArray} was: an insert would
+         * renumber every kind after it, and the compiler is self-hosted.
+         *
+         * A separate kind rather than a flag on `UnmanagedArray` because the two have
+         * different layouts — one addresses bare elements, the other a
+         * `[u32 length][pad][data]` header — and every element access has to know
+         * which it is looking at. The storage *model* is a field
+         * ({@link dynamicMemoryModel}), not a kind, so `@managed @dynamic` (Landing 4d)
+         * is the same kind under a different owner.
+         */
+        DynamicArray = 28
     }
     /** Indicates capabilities of a type. */
     export const enum TypeFlags {
@@ -4936,6 +5080,28 @@ declare module "types:tensionscript/src/types" {
         fixedElementType: Type | null;
         /** Element count of a {@link TypeKind.FixedArray}, else `0`. */
         fixedLength: number;
+        /**
+         * Element type of a {@link TypeKind.UnmanagedArray}, else `null`.
+         *
+         * Kept apart from {@link fixedElementType} rather than shared. The two kinds
+         * say different things -- an extent versus an address -- and a shared field
+         * would force every `kind == FixedArray` test in the compiler to become a
+         * three-way test, with the risk that one of them silently starts treating an
+         * address as an extent. `size` differs for the same reason: this kind's size is
+         * the pointer's, not the element's replicated.
+         */
+        unmanagedElementType: Type | null;
+        /** Element type of a {@link TypeKind.DynamicArray}, else `null`. */
+        dynamicArrayElementType: Type | null;
+        /**
+         * Who owns a {@link TypeKind.DynamicArray}'s buffer.
+         *
+         * {@link MemoryModelCode.Unmanaged} for a C-compatible header-prefixed buffer;
+         * {@link MemoryModelCode.Managed} is Landing 4d. Part of {@link equals}, so the
+         * two cannot be confused for one another even though they share a kind and a
+         * layout.
+         */
+        dynamicMemoryModel: MemoryModelCode;
         /**
          * Alignment (log2) of a {@link TypeKind.FixedArray}: its element's.
          *
@@ -4959,7 +5125,15 @@ declare module "types:tensionscript/src/types" {
         get exceptVoid(): Type;
         /** Size in bytes. */
         get byteSize(): number;
-        /** Gets this type's logarithmic alignment in memory. */
+        /**
+         * Gets this type's logarithmic alignment in memory.
+         *
+         * An `UnmanagedArray` deliberately does **not** take the {@link fixedAlignLog2}
+         * branch. It is one pointer, so its alignment is the pointer's -- which is what
+         * the `byteSize` fallback already yields, since this kind's `size` is the
+         * pointer's and not the element's replicated. There is no element alignment to
+         * borrow here; the element is not stored in this type.
+         */
         get alignLog2(): number;
         /** Tests if this type represents a basic value. */
         get isValue(): boolean;
@@ -5099,6 +5273,55 @@ declare module "types:tensionscript/src/types" {
         static fixedArray(elementType: Type, length: number): Type;
         /** Gets the element type of a {@link TypeKind.FixedArray}. */
         get fixedArrayElementType(): Type;
+        /** Interned unmanaged-array types, keyed by element type and pointer width. */
+        private static _unmanagedArrays;
+        /**
+         * Gets the {@link TypeKind.UnmanagedArray} of `elementType`: a pointer to a run
+         * of `elementType`, with no length.
+         *
+         * `pointerSize` is `options.usizeType.size` -- 32 or 64 bits. It is a
+         * parameter rather than a constant because a `Type` carries its own size, and
+         * `size` here must be the **pointer's**, not the element's: there is no extent
+         * to measure. It is part of the cache key for the same reason -- `equals`
+         * compares element types only, so two types differing solely in pointer width
+         * must not be the same object.
+         *
+         * Unlike {@link Type.fixedArray} this consults nothing about the element but
+         * its identity: the count is unknown, which is the entire point of the kind.
+         *
+         * The cache is validated by **identity** of the element, not just by the key.
+         * This is what keeps interning a per-program property rather than a
+         * per-process one: the map is a static that outlives a `Program`, so a second
+         * `asc.main` in the same process (which is exactly what the compiler test
+         * harness does -- debug then release) would otherwise be handed the first
+         * program's `Type`, whose `unmanagedElementType` carries the first program's
+         * `Class`. A property read through that class then emitted a call to a getter
+         * the new module never compiled, and the module failed to validate:
+         * `wasm-validator error ... call target must exist`.
+         *
+         * So a cached entry is returned only when its element is the *same object* the
+         * current program just resolved. Within one program that is always true --
+         * `resolveType` interns a record's `Type` -- so interning still holds there.
+         */
+        static unmanagedArray(elementType: Type, pointerSize: number): Type;
+        /** Gets the element type of a {@link TypeKind.UnmanagedArray}. */
+        get unmanagedArrayElementType(): Type;
+        /** Interned dynamic-array types, keyed by model, element and pointer width. */
+        private static _dynamicArrays;
+        /**
+         * Gets the {@link TypeKind.DynamicArray} of `elementType`.
+         *
+         * The key carries the **model** as well as the element, because `equals`
+         * compares both: two models over one element are different types, and
+         * interning them together would make them the same object.
+         *
+         * Like {@link Type.unmanagedArray} the entry is validated by element identity
+         * on the way out — the map outlives a `Program`, so a second compile in one
+         * process must not be handed the first one's element `Class`.
+         */
+        static dynamicArray(elementType: Type, memoryModel: MemoryModelCode, pointerSize: number): Type;
+        /** Gets the element type of a {@link TypeKind.DynamicArray}. */
+        get dynamicElementType(): Type;
         static readonly f64: Type;
         /** A 128-bit vector. */
         static readonly v128: Type;
@@ -7778,7 +8001,26 @@ declare module "types:tensionscript/src/ast" {
         ExportMember = 67,
         SwitchCase = 68,
         IndexSignature = 69,
-        Comment = 70
+        Comment = 70,
+        /**
+         * `[T *]` — a pointer to T with unknown length.
+         *
+         * Appended at the end rather than beside {@link FixedArrayType}. `NodeKind`
+         * is a `const enum` with implicit numbering, so an insert would renumber every
+         * node kind after it; the compiler is self-hosted, so a partial rebuild could
+         * then disagree with `dist/` about what `NodeKind.Comment` means -- silently.
+         * The position carries no meaning.
+         */
+        UnmanagedArrayType = 71,
+        /**
+         * `@unmanaged @dynamic [T * n]` — a header-prefixed array whose length is a
+         * runtime value read from the buffer.
+         *
+         * Appended for the same reason {@link UnmanagedArrayType} was: this is an
+         * implicit-numbering `const enum`, so an insert would renumber every node kind
+         * after it.
+         */
+        DynamicArrayType = 72
     }
     /** Base class of all nodes. */
     export abstract class Node {
@@ -7796,6 +8038,8 @@ declare module "types:tensionscript/src/ast" {
         static createFunctionType(parameters: ParameterNode[], returnType: TypeNode, explicitThisType: NamedTypeNode | null, isNullable: boolean, range: Range): FunctionTypeNode;
         static createTupleType(elements: TypeNode[], elementNames: (IdentifierExpression | null)[] | null, isNullable: boolean, range: Range): TupleTypeNode;
         static createFixedArrayType(elementType: TypeNode, length: number, range: Range): FixedArrayTypeNode;
+        static createUnmanagedArrayType(elementType: TypeNode, range: Range): UnmanagedArrayTypeNode;
+        static createDynamicArrayType(elementType: TypeNode, lengthName: IdentifierExpression, memoryModel: MemoryModel, range: Range): DynamicArrayTypeNode;
         static createOmittedType(range: Range): NamedTypeNode;
         static createTypeParameter(name: IdentifierExpression, extendsType: NamedTypeNode | null, defaultType: NamedTypeNode | null, range: Range): TypeParameterNode;
         static createParameter(parameterKind: ParameterKind, name: IdentifierExpression, type: TypeNode, initializer: Expression | null, range: Range): ParameterNode;
@@ -8035,6 +8279,56 @@ declare module "types:tensionscript/src/ast" {
         /** Source range. */
         range: Range);
     }
+    /**
+     * Represents an unmanaged array type, `[T *]` — a pointer to `T` with no length.
+     *
+     * The difference from {@link FixedArrayTypeNode} is the missing `length`, and it
+     * is the whole difference: a fixed array *contains* its elements, so it has an
+     * extent the layout can size; this one *addresses* them, so its own size is the
+     * pointer's. That is why `[T *]` binds as one `i32` slot where `T[N]` has no
+     * reference representation at all (`Type#toRef` asserts on a fixed array).
+     *
+     * Not a reference: the collector owns nothing here, the address is the caller's.
+     * Not a value either: there is nothing to inline. `changetype` and a parameter
+     * are the two ways one comes into being.
+     */
+    export class UnmanagedArrayTypeNode extends TypeNode {
+        /** Element type. */
+        elementType: TypeNode;
+        constructor(
+        /** Element type. */
+        elementType: TypeNode, 
+        /** Source range. */
+        range: Range);
+    }
+    /**
+     * Represents a dynamic array type, `@unmanaged @dynamic [T * n]`.
+     *
+     * The `n` is **spelling, not an expression**: the parser cannot evaluate it (it
+     * has no symbol table), so it is carried as a name and the length is read at
+     * runtime from the buffer header. That is why the form is admissible at parse
+     * time without knowing whether `n` is a constant — resolution decides that, and
+     * `resolveDynamicArrayType` refuses a name that turns out to be compile-time.
+     *
+     * One i32 slot at the ABI, holding a pointer to `[u32 length][pad][T data[n]]`.
+     */
+    export class DynamicArrayTypeNode extends TypeNode {
+        /** Element type. */
+        elementType: TypeNode;
+        /** The length's name. Bound as a read-only local where a function scope exists. */
+        lengthName: IdentifierExpression;
+        /** Storage model of the buffer. `Unmanaged` for now; `Managed` is Landing 4d. */
+        dynamicMemoryModel: MemoryModel;
+        constructor(
+        /** Element type. */
+        elementType: TypeNode, 
+        /** The length's name. Bound as a read-only local where a function scope exists. */
+        lengthName: IdentifierExpression, 
+        /** Storage model of the buffer. `Unmanaged` for now; `Managed` is Landing 4d. */
+        dynamicMemoryModel: MemoryModel, 
+        /** Source range. */
+        range: Range);
+    }
     /** Represents a type parameter. */
     export class TypeParameterNode extends Node {
         /** Identifier reference. */
@@ -10387,6 +10681,15 @@ declare module "types:tensionscript/src/compiler" {
         indexExpression: Expression | null, 
         /** Whether to tee the value. */
         tee: boolean): ExpressionRef;
+        /**
+         * The {@link DynamicArrayTypeNode} a declaration names, if it names one.
+         *
+         * Two spellings carry the length's name: the annotation (`const y: [T * n]`)
+         * and `changetype`'s type argument (`const y = changetype<[T * n]>(p)`). Both
+         * are read here so the local-position binding does not depend on which one the
+         * source chose.
+         */
+        private dynamicArrayTypeNodeOf;
         /** Makes an assignment to a local, keeping track of wrap and null states. */
         private makeLocalAssignment;
         /** Makes an assignment to a global. */
@@ -10459,6 +10762,177 @@ declare module "types:tensionscript/src/compiler" {
         /** Creates an indirect call to a first-class function. */
         makeCallIndirect(signature: Signature, functionArg: ExpressionRef, reportNode: Node, operands?: ExpressionRef[] | null, immediatelyDropped?: boolean): ExpressionRef;
         private compileCommaExpression;
+        /**
+         * The byte extent of one element of a `[T *]` — the stride `y[i]` walks by.
+         *
+         * For a scalar this is `Type.byteSize`. For a record it is **not**: an
+         * `@unmanaged`/`@managed` record's `Type` is reference-like, so its `byteSize`
+         * is the 4-byte address, and the extent lives on the `Class` that laid the
+         * fields out. `builtin_sizeof` already answers this way for the same reason
+         * (`builtins.ts`, the `Unmanaged | ManagedStruct` branch answers
+         * `nextMemoryOffset`), so the two cannot disagree about how big a record is.
+         *
+         * An `@inline struct` needs no arm: it *is* a value type, so its
+         * `byteSize` is already the extent. Measured — `[Inl *]` over
+         * `@inline struct Inl { x: f64; y: f64 }` strides 16, which is
+         * `sizeof<Inl>()`.
+         *
+         * Measured, and the reason this helper exists: using `byteSize` directly gave
+         * a stride of 4 for a two-`f64` record of 16 bytes — the same "alignment or
+         * reference size instead of the extent" mistake the fixed-array arm avoids
+         * only because it refuses records outright.
+         */
+        private unmanagedArrayElementSize;
+        /**
+         * Whether `type` is a record whose elements live **at** the address rather
+         * than being a value loaded from it: `@unmanaged`, `@managed` or `@inline`.
+         *
+         * This is the discriminator between "the address is the element" and "load the
+         * element from the address", and it is deliberately about the *element kind*
+         * rather than about type equality — see {@link compileUnmanagedArrayElementAccess}.
+         */
+        private isRecordValueType;
+        /**
+         * The header an `@unmanaged @dynamic [T * n]` buffer carries in front of its
+         * elements: `align_up(4, alignof(T))`.
+         *
+         * Four bytes hold the `u32` length; anything needing stronger alignment than
+         * that gets padding after it. So `u32` elements sit at `ptr + 4`, and a
+         * two-`f64` record sits at `ptr + 8`.
+         *
+         * Reported in Landing 4a: **no header-size helper existed**, because nothing
+         * in 4a needed one — `.length` reads offset 0, and 4a's own V5 recorded that
+         * the constant could not be observed from outside. This is its first
+         * definition; `.length` and the element address both go through it so they
+         * cannot drift.
+         *
+         * A record's alignment is `Class#alignLog2` rather than `Type#alignLog2` for
+         * the same reason its size is `nextMemoryOffset`: a record's `Type` is
+         * reference-like and would report the 4-byte pointer's alignment for every
+         * record, including the `f64`-only ones that are aligned 8.
+         */
+        /**
+         * Whether `type` is the **managed** dynamic-array descriptor — the std
+         * `DynamicArray<T>` class that `@managed @dynamic [T * n]` resolves to
+         * (Landing 4d.1).
+         *
+         * Answered by class identity rather than by a memory-model field, because the
+         * managed form is a class reference now: its `Type` is the class instance's
+         * type, and the "model" is implicit in `isManaged`. That is the whole point of
+         * the redesign — `TypeKind.DynamicArray` carries `TypeFlags.None` and is not
+         * traced, so a descriptor stored as one would not be rooted.
+         */
+        /**
+         * The element type of either dynamic-array form.
+         *
+         * `@unmanaged @dynamic [T * n]` carries the element on its type;
+         * `@managed @dynamic [T * n]` is a `DynamicArray<T>` class reference, so the
+         * element is the class's type argument. One accessor for both, because every
+         * consumer below — access, compound, increment — would otherwise branch.
+         */
+        private dynamicArrayElementOf;
+        private isManagedDynamicArrayType;
+        private dynamicArrayHeaderSize;
+        /**
+         * Compiles the byte address of `y[i]` for a dynamic array:
+         * `ptr + headerSize + i*sizeof(T)`.
+         *
+         * Shared by the read and the write arm, so the two cannot disagree about which
+         * bytes they address — the same split the fixed and unmanaged arms use.
+         *
+         * Two constants, each of which was a bug somewhere else in this family:
+         *
+         * - **`headerSize` is present.** It is what separates a dynamic array from a
+         *   `[T *]`: the data starts after the length word and its padding.
+         * - **The stride is a multiply by the element's extent**, not a shift by its
+         *   alignment. For a two-`f64` record those differ (16 vs 8), which is Landing
+         *   2's lesson and the reason `unmanagedArrayElementSize` exists.
+         */
+        private compileDynamicArrayElementAddress;
+        /**
+         * The bounds check an `@unmanaged @dynamic [T * n]` access performs before it
+         * touches memory: `if ((u32)index >= (u32)length) trap`.
+         *
+         * **Unsigned** on purpose. A negative index is a huge `u32`, so it fails the
+         * same comparison as any other out-of-range value — one check covers both ends
+         * without a second comparison, and `y[-1]` cannot walk backwards out of the
+         * buffer.
+         *
+         * The length comes from the header directly rather than from the `n` binding.
+         * `n` is a snapshot taken at entry (D5 of 4a); the header is what the buffer
+         * currently says, and a bounds check is about the memory that exists now.
+         *
+         * The message is a literal: `makeAbort` takes a string expression, and nothing
+         * in this compiler formats an index and a length into one (measured — 4a's
+         * `changetype` trap is the same shape). Naming the two causes would mean
+         * building a string at every check.
+         */
+        private compileDynamicArrayBoundsCheck;
+        /**
+         * Compiles the byte address of `y[i]` for an unmanaged array: `base + i*sizeof(T)`.
+         *
+         * Shared by the read and the write arm, so the two cannot disagree about which
+         * bytes they address — the same reason `compileFixedArrayElementAccess` and
+         * `compileFixedArrayElementAddress` are split.
+         *
+         * The stride is a **multiply**, not the fixed-array arm's `1 << alignof(T)`.
+         * That shift is right only for the elements the fixed arm admits (records are
+         * refused there, so every element is a scalar, where size and alignment
+         * coincide). A record element is the ordinary case here, and for a record the
+         * two disagree: two `f64`s give `sizeof` 16 and `alignof` 8.
+         */
+        private compileUnmanagedArrayElementAddress;
+        /**
+         * Compiles `y[i]` for an unmanaged array, `[T *]` — both directions.
+         *
+         * Two things separate this from {@link compileFixedArrayElementAccess}:
+         *
+         * - **The stride is a multiply** (see the address helper).
+         *
+         * - **A record element compiles to an address, not a load.** A record's
+         *   `toRef` is the 4-byte reference, so loading there would read the record's
+         *   first four bytes and call them a pointer. So the address is yielded typed
+         *   as the element, and `.field` on it resolves through the record's own
+         *   accessor — a load or a store at `addr + offsetof`. **That is also how a
+         *   field write works**: `y[i].x = v` reaches the property setter, whose
+         *   `this` is this address. No separate arm.
+         *
+         * Reads are unchecked. `*` says the length is unknown, so there is nothing to
+         * check against; `@dynamic` is where a checked form lives.
+         *
+         * A whole-record **write** is refused, keyed on the element being a record.
+         * The key is the element kind, not "both sides have the same type": a scalar
+         * element assignment (`a[i] = 5` over `[u32 *]`) is an ordinary store and must
+         * keep compiling. Refusing by type equality would have caught that case too,
+         * which is the trap this comment exists to keep shut.
+         */
+        private compileUnmanagedArrayElementAccess;
+        /**
+         * Compiles `y[i]` for an `@unmanaged @dynamic [T * n]` — both directions.
+         *
+         * Differs from {@link compileUnmanagedArrayElementAccess} in exactly one place,
+         * and it is the whole point of the kind: **the bounds check**. A `[T *]` has no
+         * length to check against, so its access is unchecked by contract; a dynamic
+         * array carries one in its header, and an index outside it is a diagnostic
+         * rather than whatever memory happens to follow.
+         *
+         * Everything else is the unmanaged arm's shape, deliberately:
+         *
+         * - a **record element** compiles to the address, typed as the element, so
+         *   `.field` reads and writes go through the record's own accessor — which is
+         *   also how `y[i].field = v` works, with no arm of its own;
+         * - a **scalar element** is loaded or stored at its own width;
+         * - a whole-record **write** is refused, keyed on the element being a record
+         *   rather than on type equality, so `a[i] = 5` over `[u32 * n]` still
+         *   compiles.
+         *
+         * Compound assignment and increment call this **twice** — once by way of the
+         * read the operator performs, once for the store — so the check is emitted
+         * twice. That is the smaller of the two correct shapes: sharing one check
+         * would mean threading the checked address through the operator's own codegen,
+         * which does not know this arm exists.
+         */
+        private compileDynamicArrayElementAccess;
         /**
          * Compiles `array[index]` for a `T[N]` inline array: read and write.
          *