Home /Modules/collections/SLList-Heterogeneous-Design.md

SLList-Heterogeneous-Design.md

lib/collections/SLList-Heterogeneous-Design.md · 60 line(s) · markdown

Heterogeneous SLList: design and verification plan

Status: runtime checked casts and type tests committed; compile/runtime verification remains outstanding

This document records the source/VM audit for a non-generic list that can retain values of different concrete types, including class/struct instances, and pass those values through recursive calls. It deliberately separates the current String-only SLList from the future heterogeneous contract.

1. What the current VM already supports

The core SLValue tagged union includes SL_NULL, SL_INT, SL_DOUBLE, SL_BOOL, SL_STR, SL_STRUCT, and SL_ARRAY. Structs and arrays are VM-local handles, not raw pointers. The garbage collector's value traversal marks struct/array handles stored in struct fields and array elements, and it marks globals, the last result, mailboxes, and the active stack.

The array store uses SLValue elements, and arrayPush accepts an SLValue at the core boundary. This makes the runtime representation a good basis for a mixed-value list.

2. Why the current SLList cannot yet promise this

Until these checks exist, changing SLList.add to accept arbitrary objects would overstate the guarantees and could allow type confusion.

Keep the existing SLList as a concrete String list for compatibility. SLValueList is now added as a first implementation of mixed storage; its safe public contract is intentionally limited until runtime type inspection/casting is implemented:

This is a dynamic top type, not Generics. It must preserve object identity: appending a class/struct handle stores the handle, not a serialized copy. The same handle should be safe to pass through recursive method parameters.

4. Required implementation safeguards

  1. Implemented: add a source-level Any type to semantic analysis. Values of Any can be passed through Any parameters; Any does not silently convert to concrete class types.
  2. Partially implemented: heterogeneous storage uses Any[]; semantic checks cover ordinary typed-array writes where the declared array type is known.
  3. Semantic analysis now checks arrayPush and arraySet when the first argument has a statically known array type. Runtime array instances still do not record element contracts, so native/unknown-typed boundaries remain a gap.
  4. Implemented: instanceof checks runtime tags and registered class ancestry; casts validate the runtime tag or class hierarchy before returning a value usable through a concrete type.
  5. Preserve GC reachability and alias identity across list storage, list reads, recursive calls, and collections. Do not expose raw handles as integers.

5. Regression test matrix

The implementation is not complete until the compiler and runtime tests cover all of the following. The current mixed-list example is illustrative and has not been compiled or executed here:

6. Verification status

The repository now contains Any, semantic checks for typed arrayPush/arraySet calls with known array types, SLValueList, checked instanceof and cast opcodes, runtime class-parent metadata, documentation, and an illustrative example. Branches main and master contain matching implementation files. A local build/test run was not possible in this environment because a repository clone could not be obtained; no successful compilation or runtime test is claimed.