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:
@@ -3,7 +3,7 @@
|
||||
Domain: machine timing and cycles
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-time-and-cycles.md`](../runtime/learn/mental-model-time-and-cycles.md)
|
||||
Didactic companion: [`../learn/mental-model-time-and-cycles.md`](../../../discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md)
|
||||
|
||||
## 1 Scope
|
||||
|
||||
@@ -158,3 +158,12 @@ enemy.updateAI(): 1,012 cycles
|
||||
## Program Registry v1 integration
|
||||
|
||||
The [Dynamic/reference instruction table](02c-program-registry-and-pbx-v1.md#dynamic-and-reference-instructions) specifies fixed costs of 8/4/3/4/4/5/4 cycles for opcodes 0x0090–0x0096. Each decoded attempt charges once, including a trap. Input retains the existing one-cycle INTRINSIC rule. Load work quotas are deterministic analysis units, not execution cycles or a wall-clock timeout.
|
||||
|
||||
|
||||
## Collection Attempt Charging
|
||||
|
||||
The [collection ISA table](02-vm-instruction-set.md#typed-collection-instructions) defines complete costs. Metadata widths determine costs independently of native sizeof, allocator, timing, optimizer and GC. Each decoded collection attempt is charged exactly once before validation/refusal. Fixed costs apply even to underflow, invalid receiver, bounds and rejected value groups. ARRAY_NEW charges 8 + N*w(E) whenever an available exact Int64 length is in 0..u32::MAX, including quota/allocation refusal; absent, wrong-carrier, negative or above-u32 length charges eight. Rejected loads execute and charge no guest instruction.
|
||||
|
||||
Examples: empty Struct/Array costs eight; a Struct containing Int32, vec2 and Trait costs thirteen; ten vec2 elements cost twenty-eight even on quota refusal; pixel GET costs six including bounds failure; pixel SET costs seven including group rejection; LEN costs three including receiver failure. Charged cycles are never refunded by rollback.
|
||||
|
||||
Budget admission remains between instructions. Zero executes nothing. A positive remaining budget admits the entire next instruction, which may overshoot; continuation then returns BudgetExhausted before the following instruction. Thus ARRAY_NEW of ten vec2 under run_budget(1) consumes twenty-eight cycles. Trap takes priority on refusal, with the same cycle delta and no successful target step. steps_executed counts only successful steps; cycles_used includes failed attempts. Collection operations add no implicit frame sync, tick, GC or coroutine switch, no extra length cap and no cycle pre-admission rule.
|
||||
|
||||
@@ -131,3 +131,26 @@ The PVM is:
|
||||
## Program Registry v1 integration
|
||||
|
||||
[Program Registry and PBX v1](02c-program-registry-and-pbx-v1.md) defines typed immediate domains, opcodes 0x0090–0x0096, complete multi-slot groups and conservative type-flow verification. Unknown facts require runtime validation and do not alone reject an otherwise valid join. Opcode bytes remain u16; TypeId immediates are u32 little-endian.
|
||||
|
||||
|
||||
## Typed Collection Instructions
|
||||
|
||||
These instructions require a validated Program Registry. Opcodes are u16 little-endian; TypeId and field immediates are u32 little-endian. T is the receiver descriptor, F its declared field type, E its Array element type. Stack order below is bottom to top; groups retain Registry component order.
|
||||
|
||||
| Instruction | Code | Immediate | Bytes | Stack effect | Full attempt cycles |
|
||||
| --- | --- | --- | ---: | --- | --- |
|
||||
| STRUCT_NEW T | 0x00A0 | T | 6 | [] → ref<T> | 8 + sum(w(fields)) |
|
||||
| STRUCT_GET type=T, field=f | 0x00A1 | T, f | 10 | ref<T> → slots(F) | 3 + w(F) |
|
||||
| STRUCT_SET type=T, field=f | 0x00A2 | T, f | 10 | ref<T>, slots(F) → [] | 4 + w(F) |
|
||||
| ARRAY_NEW T | 0x00A3 | T | 6 | length:Int64 → ref<T> | 8 + N*w(E), valid N; otherwise 8 |
|
||||
| ARRAY_LEN T | 0x00A4 | T | 6 | ref<T> → length:Int64 | 3 |
|
||||
| ARRAY_GET T | 0x00A5 | T | 6 | ref<T>, index:Int64 → slots(E) | 3 + w(E) |
|
||||
| ARRAY_SET T | 0x00A6 | T | 6 | ref<T>, index:Int64, slots(E) → [] | 4 + w(E) |
|
||||
|
||||
w is the resolved execution-slot width: scalar, String, color and concrete references use one; vec2, Trait and Dynamic use two; pixel uses three. Reference width never traverses referenced instances. The Struct construction sum is cached during bounded Registry resolution, with no PBX schema change. `OpCode::cycles()` supplies only the base component for these instructions.
|
||||
|
||||
STRUCT operations require a Struct descriptor; ARRAY operations require an Array descriptor, never its element TypeId or BuiltinId. Fields are immediate owner-local indices in declaration order. Every operation may trap; none branches, terminates or constitutes a safepoint. All instructions, including unreachable ones, undergo bounded structural verification and exact Registry height analysis. Finite type/group facts converge before proven conflicts are rejected. Unknown facts retain runtime checking; locals have no permanent type.
|
||||
|
||||
After charging the attempt, incomplete temporary operands trap with STACK_UNDERFLOW. Instance operations check receiver carrier, absence, liveness/generation, category, Registry and exact TypeId first; array access then checks exact Int64 index and bounds; SET checks the complete value group last. There is no numeric, Trait or Dynamic coercion. Negative lengths or indices and indices at/above length trap with OOB (0x03); wrong carriers/types/groups trap with TYPE (0x04); absent receivers with NULL_REFERENCE (0x0E); invalid/dead/stale handles with INVALID_HANDLE (0x0F). Positive lengths above u32, checked size/cost overflow, resource quotas and recoverable allocation failures trap with RESOURCE_LIMIT (0x10), preserving resource reason/requested/limit. Static invalid TypeIds/categories/fields produce LOAD_INVALID_REFERENCE; proven stack/type conflicts produce LOAD_INVALID_CODE. Runtime TrapInfo preserves the attempted PC, opcode and available source span.
|
||||
|
||||
Publication and ownership follow [typed collection memory](03-memory-stack-heap-and-allocation.md); charging follows [time and cycles](01-time-model-and-cycles.md). See the [producer handoff](../../vm-arch/collection-producer-handoff.md) for independent byte oracles and construction examples. Production consumers must enter through the validated PBX v1 image boundary described in [Program Registry](02c-program-registry-and-pbx-v1.md).
|
||||
|
||||
@@ -132,8 +132,7 @@ The PVM uses a **mark-sweep collector**.
|
||||
|
||||
GC may run when:
|
||||
|
||||
- heap usage exceeds threshold;
|
||||
- allocation pressure is high.
|
||||
- the configured allocation threshold is reached at an established safepoint.
|
||||
|
||||
### Root set
|
||||
|
||||
@@ -167,8 +166,8 @@ Implications:
|
||||
|
||||
If allocation fails:
|
||||
|
||||
- the VM may trigger GC;
|
||||
- if pressure remains unresolved, allocation may trap or fail according to the runtime contract.
|
||||
- the attempt refuses with the applicable structured resource fault;
|
||||
- it does not trigger reentrant GC or scheduling to satisfy its quota.
|
||||
|
||||
### Deallocation
|
||||
|
||||
@@ -204,3 +203,14 @@ Any violation results in a trap or rejected program image.
|
||||
## Program Registry v1 integration
|
||||
|
||||
[Program Registry and PBX v1](02c-program-registry-and-pbx-v1.md#values-storage-and-initialization) specifies compact typed layouts, defaults, native String/Dynamic ownership and generational handles. Its [memory quotas](02c-program-registry-and-pbx-v1.md#memory-ownership-and-quotas) apply jointly before allocation. Registry metadata is immutable image-owned native memory, outside guest GC. Stack/local execution retains Value.
|
||||
|
||||
|
||||
## Typed Array and Struct Storage
|
||||
|
||||
Registry-backed Arrays have fixed u32 lengths; Structs have mutable declared fields. Instances use resolved aligned offsets/strides and ownership maps. Builtins remain inline; Struct/Array fields and elements hold references. Copies preserve identity and aliasing, including nested arrays. List, Set and Map policies and implementations belong to each language SDK, composed from runtime Array capabilities.
|
||||
|
||||
NEW fully initializes all storage before publishing a handle: primitive/builtin canonical zeros, null String and concrete references, absent Trait [Null, Null], and untyped-null Dynamic [Null, Null]. Empty instances remain valid identities. No source constructor, callback or referenced instance/subarray is invoked or allocated implicitly. A frontend may root a default instance, store fields and call its own constructor.
|
||||
|
||||
GET copies a complete group and native owners without implicit boxing; SET validates the entire group before replacing it. String copies retain Arc ownership/provenance/accounting; null and empty String differ. Trait stores receiver and ImplementationId together (zero is a valid implementation); Dynamic preserves its complete pair and shares existing immutable boxes.
|
||||
|
||||
After validation, an attempt provisionally reserves net stack growth and construction resources, keeping source operands/roots alive. It prepares complete defaults/results before publication. Commit replaces the whole stored group or publishes the complete result, then consumes operands. No fallible reservation/allocation follows publication. Refusal preserves operands and prior storage/owners, publishes no partial handle, and releases provisional reservations/owners. Attempted work/cycles are retained; preexisting auxiliary capacities follow their existing growth contract. NEW never invokes reentrant GC or scheduling to satisfy quota. GC remains confined to established safepoints; live transitively rooted graphs and native owners survive them, while unrooted cycles become reclaimable.
|
||||
|
||||
@@ -12,7 +12,7 @@ Machine boundary:
|
||||
Authority rule:
|
||||
|
||||
- This document is normative for bytecode-level encoding and opcode surface.
|
||||
- Runtime-wide invariants still live in [`../../ARCHITECTURE.md`](../../ARCHITECTURE.md).
|
||||
- Runtime-wide invariants still live in [`ARCHITECTURE.md`](ARCHITECTURE.md).
|
||||
- If a bytecode-level rule here conflicts with runtime architecture, the conflict must be resolved explicitly in both documents; neither should drift silently.
|
||||
|
||||
#### Encoding Rules
|
||||
@@ -164,3 +164,7 @@ Static opcode metadata must represent Registry-dependent slot effects as unresol
|
||||
never as zero. Resolve the semantic widths and immediate categories from the validated
|
||||
Registry. Encoding/decoding support alone does not authorize execution: a slot-only
|
||||
image/verifier must reject these instructions until typed-image integration is present.
|
||||
|
||||
#### Registry-backed collections
|
||||
|
||||
STRUCT_NEW (0x00A0), STRUCT_GET (0x00A1), STRUCT_SET (0x00A2), ARRAY_NEW (0x00A3), ARRAY_LEN (0x00A4), ARRAY_GET (0x00A5) and ARRAY_SET (0x00A6) require a validated Registry. Their exact immediates, full group effects, attempt costs and failure ordering are normative in the [typed collection instruction table](../specs/runtime/02-vm-instruction-set.md#typed-collection-instructions). These operations have no implicit conversion or safepoint. See the [producer handoff](collection-producer-handoff.md) for emission oracles.
|
||||
|
||||
@@ -0,0 +1,67 @@
|
||||
# Typed collection producer and consumer handoff
|
||||
|
||||
The [collection ISA](../specs/runtime/02-vm-instruction-set.md#typed-collection-instructions), [memory contract](../specs/runtime/03-memory-stack-heap-and-allocation.md#typed-array-and-struct-storage) and [attempt charging](../specs/runtime/01-time-model-and-cycles.md#collection-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:
|
||||
|
||||
```text
|
||||
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<Int32>, independent code bytes for length two followed by LEN and HALT are:
|
||||
|
||||
```text
|
||||
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<color> 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](../../discussion/lessons/DSC-0051-game-state-collections-and-objects/LSN-0060-collection-attempts-preserve-groups-and-charge-work-before-publication.md).
|
||||
@@ -8,7 +8,7 @@ The rationale and published mechanisms are explained in [Registry Boundaries and
|
||||
|
||||
The bounded writer/owned decoder, sealed `ValidatedProgramImage::load`, shared
|
||||
session factory, typed direct-call/return boundaries, Dynamic/reference execution,
|
||||
fixed input catalogue and string accounting have executable tests. The production
|
||||
fixed input catalogue, typed collection operations and string accounting have executable tests. The production
|
||||
`initialize` transition, removal of old unchecked entry points, all producer
|
||||
migration and both regenerated runtime examples remain pending. Existing closure
|
||||
receivers need a typed callable contract; none of the four accepted Registry
|
||||
@@ -26,9 +26,7 @@ categories may be used as a provisional closure type.
|
||||
| Conformance | Add migrated producer/example/callable evidence to this handoff and the existing conformance matrix. |
|
||||
| Publication | Audit final coordinated publication, legacy removal, traceability and migrated workspace/examples. |
|
||||
|
||||
This integration reuses the delivered Registry foundation. Guest collection
|
||||
operations, new strings/bytes/save APIs, coordinated stress and representative-game
|
||||
headroom each require their own technical contract or validation workload.
|
||||
This integration reuses the delivered Registry foundation and [typed collection producer interface](collection-producer-handoff.md). New strings/bytes/save APIs, coordinated stress and representative-game headroom each require their own technical contract or validation workload.
|
||||
|
||||
The external Studio handoff targets are the build-pipeline
|
||||
`backend/bytecode/BytecodeModule.java` and `backend/irvm/IRVMIntrinsicRegistry.java`,
|
||||
|
||||
Reference in New Issue
Block a user