Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
73 lines
6.8 KiB
Markdown
73 lines
6.8 KiB
Markdown
# 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 v0, `ValidatedProgramImage::load` and `VirtualMachine::from_image`. Production initialize, internal test producers and both example generators use the same sealed v0 path. External SDK/frontend adaptation remains a separate consumer obligation.
|
|
|
|
## 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. The metadata-free verifier and legacy decoder have been removed. 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 emit sealed PBX v0, including empty captures sections, and
|
|
run through the production host. Fn is a one-slot nullable HeapRef value in fields
|
|
and arrays; Dynamic can carry it with its exact Fn TypeId. Closure environments and
|
|
shared private cells participate in existing reference maps. Default construction
|
|
never invokes callbacks. Threshold GC runs at FRAME_SYNC and successful last-root
|
|
RET after rooting results. Quota refusal cannot invoke rescue GC.
|
|
|
|
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).
|