Files
prometeu-runtime/docs/vm-arch/collection-producer-handoff.md
T
bquarkz 86bade3e1f
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
feat(vm): add typed array and struct guest operations
Add seven Registry-backed collection opcodes with bounded verification, complete value groups, transactional publication and exact attempt costs. Publish ISA, memory and cycle contracts, producer handoff and the completed lesson.

Validate with 925 workspace tests, optimized collection suites and all eight coverage domain gates. Make headless fixture directory names unique for parallel tests.
2026-10-08 10:36:20 +01:00

6.9 KiB

Typed collection producer and consumer handoff

The collection ISA, memory contract and attempt charging are normative. This interface has executable evidence through locally serialized PBX v1, ValidatedProgramImage::load and VirtualMachine::from_image. Production initialize and example generators still require coordinated v1 migration; no external SDK or frontend activation is implied.

Encoding and complete groups

Opcodes are little-endian u16, followed by little-endian u32 immediates. TypeId is the receiver descriptor, independent of BuiltinId and element TypeId. Struct field indices are immediate, owner-local declaration positions. Array lengths/indices and LEN results use exact Int64 carriers; length must fit u32. References are exact nominal/invariant Registry types. There is no implicit conversion or array covariance.

Operation Code Payload Stack bottom → top
STRUCT_NEW 0xA0 TypeId [] → ref
STRUCT_GET 0xA1 TypeId, field ref → complete field group
STRUCT_SET 0xA2 TypeId, field ref, complete field group → []
ARRAY_NEW 0xA3 TypeId Int64 length → ref
ARRAY_LEN 0xA4 TypeId ref → Int64 length
ARRAY_GET 0xA5 TypeId ref, Int64 index → complete element group
ARRAY_SET 0xA6 TypeId ref, Int64 index, complete element group → []

The single-immediate forms are six bytes; field forms are ten. Width is one for scalar/String/color/concrete references, two for vec2/Trait/Dynamic, three for pixel. A Trait contains receiver then ImplementationId; Dynamic contains TypeId then payload. Preserve the whole group, including absent [Null, Null]. ImplementationId zero is valid. GET does not implicitly box; Dynamic copies share immutable boxes. NEW initializes canonical defaults without constructing referenced instances. Arrays have fixed lengths. SDKs implement List, Set and Map algorithms using these runtime capabilities.

Evaluate source expressions under the language's ordering rules into temporaries, then load receiver, index (if applicable) and components in Registry order. Runtime validation does not define source expression evaluation order: it checks receiver first, index carrier/bounds next, and a SET group last.

Default-then-store construction oracle

With TypeId 0 = Int32 and TypeId 1 = Struct{value: TypeId 0}, the frontend can emit:

STRUCT_NEW 1
SET_GLOBAL 0
GET_GLOBAL 0
PUSH_I32 42
STRUCT_SET type=1, field=0
GET_GLOBAL 0
STRUCT_GET type=1, field=0
HALT

The default value before the store is Int32 zero; the final value is Int32 42. A language-specific constructor can be called after rooting/storing under its own rules. NEW does not call it. Global/local slots used by this example remain the producer's responsibility.

With TypeId 11 = Array, independent code bytes for length two followed by LEN and HALT are:

14 00 02 00 00 00 00 00 00 00
A3 00 0B 00 00 00
A4 00 0B 00 00 00
01 00

The final stack is [Int64(2)]. Generic independent immediate oracles use T=0x01020304 and f=0x05060708: NEW is A0 00 04 03 02 01; GET is A1 00 04 03 02 01 08 07 06 05; SET starts A2 00 with that same payload. Array NEW/LEN/GET/SET start A3 00, A4 00, A5 00, A6 00, each with 04 03 02 01. Their descriptor tables must actually contain the referenced IDs for execution; these large-ID bytes are encoding oracles only.

Costs, budgets and faults

Full costs are NEW 8 plus initialized execution slots, GET 3 plus value width, SET 4 plus value width, LEN 3. Struct sums are resolved/cached at load. ARRAY_NEW with valid Int64 N in 0..u32::MAX charges 8+N*w(E), including allocation refusal; unavailable/wrong/negative/above-u32 length charges eight. Every decoded attempt charges once, including traps. OpCode::cycles() is only the base for collection operations.

Ten vec2 elements cost 28; pixel GET/SET cost 6/7; empty construction costs 8. With positive remaining budget, the whole instruction executes, possibly overshooting. Budget zero does nothing. run_budget(1) at ARRAY_NEW ten vec2 with continuation returns BudgetExhausted, 28 cycles, one successful step; refused construction returns Trap, 28 cycles, zero successful target steps. No intra-instruction GC/tick/switch occurs.

Static bad IDs/categories/fields reject load with typed LOAD_INVALID_REFERENCE context; proven heights/types reject with LOAD_INVALID_CODE. Runtime faults retain attempted opcode/PC/span: incomplete temporary operands use STACK_UNDERFLOW; absence NULL_REFERENCE 0x0E; invalid/dead/stale handle INVALID_HANDLE 0x0F; wrong carrier/category/Registry/exact type/group TYPE 0x04; negative/out-of-range index or negative length OOB 0x03; above-u32 length, checked overflow and quotas/allocation refusal RESOURCE_LIMIT 0x10. Resource reason/requested/limit remain attached. Failed attempts preserve source operands and previous complete storage/owners, publish no partial handle and release provisional resources without refunding cycles.

Consumer integration and evidence

Consumers must recognize all seven encodings, invoke Registry-derived effects in bounded structural/height/type verification and use validated-image execution. Metadata-free/legacy verification rejects these instructions with RegistryRequired. Reuse compact typed storage, default initialization, native ownership maps and generational handles; do not replace them with raw Value arrays or SDK container implementations.

Executable oracles live in bytecode tests/registry_isa.rs, VM tests/collection_conformance.rs, VM virtual_machine/collections_tests.rs and layer tests/typed_collections.rs. They cover independent bytes, default/alias/group operations, attempt costs and refusals, malformed/proven types, ownership and actual FRAME_SYNC graph reclamation. VM unit tests inject otherwise unreachable invalid state only inside tests. Optimized ownership/conformance runs complement debug evidence.

Dummy Boy and Stress currently emit PBX version 0. The optional Dummy Boy palette migration therefore belongs with production v1 integration: initialize one global-rooted Array containing red/green/blue, mirror its frame counter in exact Int64 at the same initialization/increment points, select mirror modulo ARRAY_LEN using ARRAY_GET, and compare six logical frames. Preserve phase/drawing and verify one array allocation plus safepoint retention. This independent collection delivery does not migrate those producers or claim that smoke has run.

The published patterns and validation limits are explained in Collection Attempts Preserve Groups and Charge Work Before Publication.