feat(vm): add typed array and struct guest operations
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
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.
This commit is contained in:
+63
@@ -0,0 +1,63 @@
|
||||
---
|
||||
id: LSN-0060
|
||||
ticket: game-state-collections-and-objects
|
||||
title: Collection Attempts Preserve Groups and Charge Work Before Publication
|
||||
created: 2026-10-08
|
||||
tags: [vm, bytecode, collections, ownership, budget]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
DEC-0046, accepted from AGD-0054, established seven typed Array/Struct guest operations. PLN-0177 implemented them through the delivered Registry and sealed PBX v1 image/session boundary. This lesson explains the published result; the normative sources are the [collection ISA](../../../docs/specs/runtime/02-vm-instruction-set.md#typed-collection-instructions), [memory contract](../../../docs/specs/runtime/03-memory-stack-heap-and-allocation.md#typed-array-and-struct-storage) and [attempt charging](../../../docs/specs/runtime/01-time-model-and-cycles.md#collection-attempt-charging). The [producer handoff](../../../docs/vm-arch/collection-producer-handoff.md) supplies emission and integration oracles.
|
||||
|
||||
The Registry foundation already separated semantic identity, execution carriers and stored layouts. Collection instructions make that separation observable to guest code. The independent delivery leaves production initialize and v0 example migration with their existing integration owner; validated local programs demonstrate the new capabilities without claiming consumer activation.
|
||||
|
||||
## Key Decisions and Published Patterns
|
||||
|
||||
### A Runtime Capability Is Smaller Than an SDK Library
|
||||
|
||||
Fixed-length Array access and mutable Struct fields are enough to support language-defined containers. List growth, Set equality/hashing and Map collision policies belong to SDKs. Keeping those policies outside the runtime allows languages to share storage primitives while choosing their own abstractions. Array<Struct> stores references: copying an element preserves identity and aliasing instead of cloning an object graph.
|
||||
|
||||
A vec2 is two execution slots, but an Array reference is one regardless of its length. NEW initialization work uses those semantic widths; native size/alignment still determines memory reservations. The Struct width sum is cached once in bounded Registry resolution. Conflating these quantities would make virtual cycles depend on host representation or recursively charge referenced instances.
|
||||
|
||||
### Attempted Work and Published State Are Separate Accounts
|
||||
|
||||
A failed operation can preserve all guest-visible values while still consuming cycles. For ten vec2 elements, the attempt costs 8 + 10*2 = 28 even if memory quota refuses it. Invalid length carriers cannot supply a valid N and take the base path. This distinction makes refusal observable as charged work rather than a free repeated probe.
|
||||
|
||||
The instruction obtains validated metadata, detects incomplete temporary operands, charges once, validates ordered inputs and then reserves/prepares its result. NEW stages operand growth, object header and handle-table candidates before typed initialization. Complete publication has no subsequent fallible reservation. On failure, provisional owners drop; source operands and old storage remain live. Existing auxiliary capacity semantics remain distinct from rollback of unpublished candidates.
|
||||
|
||||
This is also why a parameterless opcode cost API is insufficient for collection accounting. It supplies a base; execution resolves the full attempt cost and returns outside the fixed-cost dispatch epilogue. Otherwise the VM could silently undercharge or charge twice.
|
||||
|
||||
### Complete Groups Keep Native and Guest Ownership Together
|
||||
|
||||
GET and SET handle complete Registry groups. Trait receiver and ImplementationId move together; implementation zero remains valid. Dynamic retains its TypeId/payload relation and shares existing immutable boxes. String copies retain Arc identity and accounting provenance, with null distinct from an empty String. A rejected overwrite does not release the prior native owner.
|
||||
|
||||
Receiver validation precedes index carrier/bounds, and SET group validation follows both. This order provides a stable first fault while avoiding mutation or early source consumption. The finite verifier rejects proven type/group conflicts after convergence, but an Unknown join still reaches runtime checks. Static proof does not remove generation, null or bounds checking.
|
||||
|
||||
### An Indivisible Instruction Can Overshoot Its Slice
|
||||
|
||||
The scheduler's cycle slice is an admission boundary between instructions. A positive balance admits a complete collection operation. At ten-vec2 ARRAY_NEW, run_budget(1) reports 28 cycles and one successful step before BudgetExhausted when continuation exists. A quota-refused attempt reports Trap and the same cycles, with zero successful target steps. Zero budget executes nothing.
|
||||
|
||||
Collection allocation does not create an implicit safepoint to satisfy quota. Roots and native owners remain live through the instruction and are reconciled at established FRAME_SYNC boundaries. A guest-created cycle can survive while an Array root reaches it, then become reclaimable when roots disappear. Weak String ledgers release content charges after the last native owner disappears and reconciliation runs; quota counters do not promise immediate RSS reduction.
|
||||
|
||||
## Evidence and Practical Limits
|
||||
|
||||
The bytecode suite checks independent literal encodings, every truncated prefix, textual roundtrips, exact effects and cached weights. Sealed serialized-v1 conformance executes default initialization, builtin groups, nested arrays, aliases and conservative Unknown joins. Decoded VM tests cover exact costs, malformed groups, stale/foreign/nominal receivers, a real frame temporary floor, resource refusals and test-only allocation failure. The layer graph crosses actual FRAME_SYNC using the unchanged default GC trigger, retaining a Node/Array/Trait/Dynamic box and reclaiming them after roots are removed. Native ownership evidence retains one String allocation shared through field/array/direct Dynamic until final-owner reconciliation.
|
||||
|
||||
Final validation ran formatting, workspace Clippy, workspace tests, optimized collection suites, LLVM coverage and all eight unchanged domain gates. The workspace and coverage runs each passed 925 tests with 9 explicitly ignored tests. Optimized collection suites passed 15 VM tests and 8 sealed conformance tests. Ignored cases are three measurement probes, five localhost debugger tests and one packaged-installation smoke; none is counted as executed. The code baseline was `8732f4b0f4a944d234037687c5cfb5be22b756a8`, followed by this working-tree delivery.
|
||||
|
||||
A repeated workspace run exposed an intermittent preexisting headless fixture boot failure. Its isolated test and full host suite passed. The fixture used clock-derived temporary directory names; adding a process-local atomic sequence and exclusive directory creation removes that collision risk without changing host or runtime behavior. The final fresh workspace and coverage runs include this fixture correction.
|
||||
|
||||
These results establish operation-specific behavior on the validated v1 path. They do not establish external compiler/SDK activation, production migration, prolonged cross-host stability, representative-game headroom or native allocator/RSS guarantees. Dummy Boy and Stress still emit v0; the optional palette smoke is explicitly excluded and handed off with its prerequisite and frame/allocation/root oracles.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Treating the Array TypeId as its element TypeId, or accepting a physically similar nominal type, breaks the semantic contract.
|
||||
- Splitting a Trait/Dynamic group, popping a receiver before checking the full attempt, or dropping an old String before validation creates partial state changes.
|
||||
- Charging only on success, using only the opcode base, or rejecting an instruction because its full cycles exceed the remaining slice changes the accepted time model.
|
||||
- Triggering eager GC inside NEW to fit quota creates a new scheduling/root boundary.
|
||||
- Using raw heap helper tests alone misses decode, bounded verification, frame floors, cost epilogues and the sealed image boundary.
|
||||
|
||||
## Takeaways
|
||||
|
||||
Treat a collection instruction as a charged ownership transaction. Resolve widths from immutable metadata, keep groups whole, validate before dependent mutation/allocation and publish only complete results. Use serialized guest programs and real safepoints to prove those boundaries, then let language SDKs compose container policies from the runtime capabilities.
|
||||
Reference in New Issue
Block a user