feat(registry): checkpoint PLN-0176 foundations and validated partial integrations

This commit is contained in:
2026-10-07 17:49:46 +01:00
parent 01fab56cc6
commit 126a9e50e7
63 changed files with 8499 additions and 1462 deletions
@@ -154,3 +154,7 @@ Used: 5,612 cycles
Primary cause:
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.
@@ -127,3 +127,7 @@ The PVM is:
- closure-capable;
- coroutine-capable;
- embedded inside the larger PROMETEU console model, not equal to it.
## 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.
@@ -13,7 +13,8 @@ All runtime values are stored in VM slots as `Value`.
| Type | Description |
| ------- | --------------------- |
| `int` | 64-bit signed integer |
| `Int32` | 32-bit signed integer |
| `Int64` | 64-bit signed integer |
| `bool` | Boolean value |
| `float` | 64-bit floating point |
@@ -114,3 +115,17 @@ There is no separate public ISA for manual frame stack manipulation.
- [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md) defines first-class function values.
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines stack/heap and handle-backed objects.
- [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md) reuses the same slot-oriented argument/return philosophy for syscalls.
## Typed signatures and frames
Derive P=sum(parameter widths), L=local_slots and R=sum(result widths). A frame contains parameters, L extra locals then temporaries. GET/SET_LOCAL address only P+L; operand operations cannot consume below the temporary base. CALL consumes P caller temporaries in signature/component order and validates complete groups before publishing the frame. Concrete method receiver is the first declared parameter. No hidden closure receiver is invented by this rule.
RET requires exactly R temporaries, validates ordered types, releases frame owners and returns R slots. Wrong height uses TRAP_BAD_RET_SLOTS; unproved runtime type mismatch uses TRAP_TYPE. Locals begin as Value::Null, not numeric defaults or Uninitialized. Parameter/local slots can be reused after entry; SET_LOCAL updates abstract knowledge. Definite assignment/source variable types remain frontend concerns. Do not introduce silent Int32/Int64, concrete/trait or concrete/Dynamic conversions at boundaries.
Verifier decodes every function range, validates instruction boundaries/IDs/jump destinations, and analyzes structurally reachable control flow. Track temporary height and local/temporary facts in a finite domain: Unknown, known null, carrier facts and proven semantic/multi-slot groups. Initial parameters follow signatures; other locals start null. GET copies facts; SET replaces. Equal facts survive joins; conflicting facts become Unknown, while unequal heights are rejected. Do not require one permanent local type or infer unbounded unions/branch conditions.
Use a bounded worklist to fixed point, reprocessing widened states; decide state-dependent type errors after convergence so visitation order cannot cause rejection. Signature contracts suffice for calls; no interprocedural body inference is required. Partial group mutation invalidates relational facts. Unknown is not proof of compatibility and does not alone reject code: retain complete runtime checks. Type knowledge alone does not eliminate null/generation/bounds checks. Retain current UnknownClosureCallee protection until the separate callable/closure/coroutine contract provides a replacement contract. Exceeding memory/work budget rejects loading, never skips verification.
Builtin IDs, exact slot carriers, nullable defaults and stored layouts are defined in [Program Registry and PBX v1](02c-program-registry-and-pbx-v1.md#values-storage-and-initialization). A fixed list of results does not imply a tuple object or boxing. Parameter names are optional signature metadata; frontend argument reordering must preserve source evaluation order.
@@ -0,0 +1,234 @@
# Program Registry, Typed Values and PBX v1
Domain: VM program metadata, binary format, typed storage and resource boundaries
Function: normative
This chapter publishes DEC-0045 through PLN-0176. It defines the required v1 contract; implementation is being migrated and this publication is not a claim that all execution paths already satisfy it. The callable/closure/coroutine type boundary remains separately specified: no provisional untyped reference type is authorized. Existing closure/coroutine behavior must be preserved until its approved replacement can be integrated.
The requirements below use MUST/MUST NOT semantics. The Registry owns type/function identity, storage shapes and signatures; other chapters retain authority over scheduling, collection operations, cartridge boot and host ABI behavior outside these requirements.
## Registry, identities and signatures
- Registry logically joins Type Registry and Function Registry. It belongs to ProgramImage, is immutable after successful resolution, and is shared across sessions. Metadata is native, outside the guest GC heap; it has no HeapRef and remains alive while any image consumer needs it. Code, constants, exports and debug are separate responsibilities.
- TypeId, FunctionId and ImplementationId are distinct u32 newtypes, dense zero-based table indices local to the image. TraitId is a TypeId checked as Trait, not a separate namespace. Field and method indices are owner-local. BuiltinId, IntrinsicId and constant-pool tags are separate domains. Names never establish identity.
- Struct/Trait are nominal; identical names/layouts do not merge them. Producers link references and deduplicate the same declaration across modules. Array identity is structural by element TypeId, invariant and mutable, with length on instances; nested arrays store array references.
- One descriptor per imported BuiltinId and per Array element TypeId; duplicate records are rejected without loader remapping. Forward references and nominal reference recursion are legal. Array-only cycles and infinite inline layouts, overflow and wrong-category references are rejected with bounded graph processing. Runtime object cycles remain legal.
- Four descriptor categories: Builtin, Struct, Array, Trait. No Service or input endpoint category. Services lower to a nominal Struct and one rooted global instance per session; singleton language rules stay in the frontend. Builtin-value trait adapters are explicit Struct allocations with separate nominal identity.
- Function signatures contain ordered typed parameters/results. Results have fixed semantic arity; zero results means zero slots, not null, and multiple results do not require tuple objects. A vec2 is one semantic result occupying two slots. Widths are derived, not duplicated in PBX.
- Parameter names are optional signature metadata independent of debug. Frontends reorder named arguments to signature order while preserving source evaluation order, using temporaries. Mixing/default-argument syntax and diagnostics stay with frontends; optional/default parameters are not implicitly introduced.
- Trait implementations are unique per (Struct, Trait), complete, immutable and ordered by method index. Explicit parameter/result TypeIds, order and arity match exactly; the implementation function has its concrete receiver as first parameter. No variance or implicit adaptation: frontend adapter functions may satisfy the exact signature. Actual trait dispatch belongs to the separate callable/closure/coroutine contract.
## PBX v1 encoding
PBX v1 only: magic `PBX\0`, little-endian, 32-byte header, zero reserved bytes and directory triples `(kind:u32, offset:u32, length:u32)`. Preserve existing non-Registry section encodings except expressly required changes. Reject unsupported versions, unknown/duplicate/missing sections, overlap, overflow, truncation and trailing table bytes. Section Code is raw instructions without a count prefix.
| Kind | Section | Presence |
| --- | --- | --- |
| 0 | constants | exactly once |
| 1 | functions | exactly once |
| 2 | code | exactly once |
| 3 | debug | optional, at most once |
| 4 | exports | exactly once |
| 5 | syscalls | exactly once |
| 6 | types | exactly once |
| 7 | implementations | exactly once |
The fixed header is:
| Byte offset | Encoding | Meaning |
| --- | --- | --- |
| 0 | four bytes | `PBX\0` |
| 4 | u16 | version 1 |
| 6 | u8 | endianness 0 (little-endian) |
| 7 | u8 | reserved, zero |
| 8 | u32 | section count |
| 12 | 20 bytes | reserved, all zero |
| 32 | section_count × 12 bytes | directory triples |
Directory offsets are file-relative. Section ranges must not overlap the header,
directory or other nonempty sections; empty Code does not make an executable entry.
Unchanged section payload encodings are also field-by-field and little-endian:
- Constants: count:u32, then tag:u8 plus payload. Tags are 0 Null (no payload),
1 Int64 (i64), 2 Float64 (f64 bits), 3 Boolean (u8 0/1), 4 String
(byte_len:u32 then UTF-8), 5 Int32 (i32). UTF-8 must be valid, never repaired
with replacement characters. Constant quotas apply before materialization.
- Exports: count:u32, then FunctionId:u32, byte_len:u32 and UTF-8 symbol.
- Debug: span_count:u32, then records (pc:u32, file_id:u32, start:u32, end:u32);
name_count:u32, then records (FunctionId:u32, byte_len:u32, UTF-8 name).
Function references and code/source ranges must be valid. Debug names do not
replace optional signature names.
- Syscalls: count:u32, then module_byte_len:u16, UTF-8 module,
name_byte_len:u16, UTF-8 name, version:u16, arg_slots:u16, ret_slots:u16.
Canonical (module, name, version) identities are unique; binding resolution
remains a separate load phase.
Empty tables use count zero where legal; section presence alone does not establish a valid boot entry. Preserve the existing boot-entry contract and validate it before execution.
Encoding primitives: list=`count:u32` followed by records; optional name=`present:u8` (0/1), then `byte_len:u32 + UTF-8` if present. Absent and empty are distinct. Parameter/field=`type_id:u32 + optional name`; result=`type_id:u32`. Records have no padding.
| Record | Exact field order |
| --- | --- |
| Type | kind:u8, optional name, category payload; tags 0 Builtin / 1 Struct / 2 Array / 3 Trait |
| Builtin payload | builtin_id:u32 |
| Struct payload | ordered field list |
| Array payload | element_type_id:u32 |
| Trait payload | ordered method list; each method has optional name, explicit-parameter list, result list; concrete receiver is not repeated here |
| Function | optional name, parameter list, result list, code_offset:u32, code_len:u32, local_slots:u32, max_stack_slots:u32 |
| Implementation | owner_type_id:u32, trait_type_id:u32, method_count:u32, FunctionIds:u32 in trait-method order; count must match |
Code offsets are relative to Code. Local and temporary counts widen from current u16 without truncation. `max_stack_slots` counts temporaries only; zero means zero, never infer. No guest-controlled builtin layouts or raw Rust structures/pointers are serialized. Remove old/external compatibility; regeneration is mandatory.
## Values, storage and initialization
Value remains the generic stack/local representation. Structs/arrays are references; primitive and builtin-value array elements are stored directly. Layout descriptors distinguish value-slot width from heap-instance layout and distinguish GC references from native ownership. Derive offsets/defaults/maps once; access by indices/offsets rather than repeatedly traversing semantic metadata. Measure bitmap versus offset/block lists; changing the map encoding must not change the contract.
| BuiltinId | Type | Value slots | Stored size / alignment |
| --- | --- | --- | --- |
| 0x0001 | color | 1 | 4 / 4 bytes |
| 0x0002 | vec2 | 2 | 16 / 8 bytes |
| 0x0003 | pixel | 3 | 24 / 8 bytes |
| 0x0010 | Int32 | 1 | 4 / 4 bytes |
| 0x0011 | Int64 | 1 | 8 / 8 bytes |
| 0x0012 | Float | 1 | 8 / 8 bytes, f64 |
| 0x0013 | Bool | 1 | 1 / 1 byte; canonical 0/1 |
| 0x0014 | String | 1 | native StringSlot size_of/align_of |
| 0x0015 | Dynamic | 2 | native DynamicSlot size_of/align_of |
Unlisted BuiltinIds, including zero and removed input IDs 0x0100–0x0102, cannot be imported. No implicit Int/Number/Void/Null aliases. `color` is numeric RGBA8888 `0xRRGGBBAA`; its stack carrier is Int64 constrained to u32 range. `vec2` stores f64 x/y at offsets 0/8. `pixel` stores i64 x/y at 0/8 and u32 color at 16 plus four padding bytes, with stack carriers [Int64,Int64,Int64]. Do not narrow coordinates or infer framebuffer byte order from the numeric color representation. These builtins contain no guest references/native ownership.
Preserve declared field order; round each offset to field alignment and final payload size to maximum alignment. Empty Struct has payload zero, alignment one, but retains object identity/header. Array stride is aligned stored-element size; Array<Struct> stores references, not Struct payloads. Checked arithmetic precedes allocation. Padding is not data or a GC reference. Allocate truly aligned storage or use appropriate accesses; Vec<u8> does not justify unsafe casts. Native Arc/Value layouts are target-dependent and never a portable PBX ABI.
Defaults apply before publication/GC, including reused storage: Int32/Int64 zero, Float +0.0, Bool false, Struct/Array/String references null, vec2 (+0,+0), color transparent raw zero, pixel (0,0,transparent), trait absent, Dynamic untyped null. Do not instantiate referenced objects/subarrays or invoke source constructors. Empty arrays require no element values. Catalog defaults are resolved without arbitrary per-element callbacks. Native values must be constructed correctly rather than assumed valid after memset.
Heap references: index:u32 + generation:u32, stored size/alignment 8, still one Value::HeapRef slot. Generation starts at one; zero is reserved. Compact null=(0,0), while index zero remains valid with a live generation. Other generation-zero pairs are invalid. Validate index/liveness/generation/type before dereference. Increment generation on reclamation; retire the slot after its maximum-generation incarnation rather than wrap. Handles belong to their heap/session; native boundaries preserve provenance without introducing a heap ID into this encoding.
StringSlot is native Option<Arc<str>>: None is null, Some(empty) is distinct. Reads/copies creating owners clone Arc; moves transfer; overwrite/drop/GC releases the old owner. Validate before overwrite and clean up only initialized native slots after failure. GC must not follow Arc as HeapRef.
Trait stack form: [HeapRef(receiver), Int64(ImplementationId)] with validated u32 ID and a coherent owner/trait pair; absence=[Null,Null]. Stored trait occupies 16 bytes, alignment 8: receiver at 0 (8 bytes), ImplementationId at 8 (4), padding at 12 (4). Stored absence uses null receiver plus ID zero; receiver discriminates absence, so implementation zero remains valid for present values. Null receiver with nonzero ID is malformed. GC follows only receiver. Copying/converting preserves object identity without a wrapper; methods invoked on absent views fault.
## Dynamic and reference instructions
Dynamic stack form is [type,payload], with Int64(u32 TypeId) or Null in the type slot. Native DynamicSlot={type_id:Option<TypeId>,payload:Value}. Untyped null=[Null,Null]; typed null=[Int64(T),Null] only for nullable T, including absent traits without boxing. Unknown type with present payload is invalid. Preserve exact semantic type despite shared physical carriers.
Single-slot values use direct Value payload (including strings/references). Present multi-slot values use a HeapRef to an internal immutable box containing TypeId and exactly width(T) Values in Box<[Value]>. Its category is distinct from user Struct/Array/Closure. The box is not a public nominal type and cannot be accessed as a guest object/array. Root source values across allocation. Extraction checks category/type/width and copies complete slots, retaining contained aliases/native ownership. Dynamic copies share the box; repacking never nests or allocates another layer.
Present extraction and typed-null extraction require exact TypeId. Untyped null extracts only into nullable types. Compatibility query differs from object-instance tests: null can be extractable while never an instance. Numeric/trait conversions are separate. Destination/source Dynamic identity validates and preserves its pair.
| Opcode | Code | Immediate(s) | Stack effect | Cycles |
| --- | --- | --- | --- | --- |
| DYN_PACK T | 0x0090 | TypeId:u32 | slots(T) -> type,payload | 8 |
| DYN_UNPACK T | 0x0091 | TypeId:u32 | type,payload -> slots(T) | 4 |
| DYN_CAN_UNPACK T | 0x0092 | TypeId:u32 | type,payload -> Bool | 3 |
| REF_IS_EXACT | 0x0093 | source:TypeId, target:TypeId | slots(source) -> Bool | 4 |
| REF_IMPLEMENTS | 0x0094 | source:TypeId, trait:TypeId | slots(source) -> Bool | 4 |
| REF_TO_TRAIT | 0x0095 | source:TypeId, trait:TypeId | slots(source) -> slots(trait) | 5 |
| REF_CAST | 0x0096 | source:TypeId, target:TypeId | slots(source) -> HeapRef or Null | 4 |
Opcodes are u16 and immediates little-endian u32: Dynamic instructions occupy 6 bytes, reference instructions 10. Types are immediate metadata validated by the loader, never arbitrary selector arguments. Queries consume their operands; producers preserve a copy in locals before querying then extracting. Compatibility returns false only for ordinary mismatch of a well-formed Dynamic; malformed carriers/boxes/handles fault. It does not allocate or copy the extracted value.
Reference source must be Struct, Array or Trait; exact-test/cast target Struct or Array; implementation-test/conversion target Trait. Reject invalid immediate categories. Validate source type or complete trait pair before examining its underlying object. Null tests return false; conversions preserve null. Present incompatible casts/conversions fault. REF_TO_TRAIT resolves the underlying concrete type directly across traits; REF_CAST requires exact concrete type. No hierarchy, array covariance, structural reinterpretation, implicit numeric conversion or Dynamic-as-source shortcut. Arrays cannot implement traits because owners are Struct only. No operation allocates wrappers; tests do not create views.
New Dynamic/reference instructions charge exactly once per decoded execution attempt, including traps. Costs are fixed for direct/box/null/identity and independent of host timing, optimizer, Arc/allocator or GC behavior. Do not double-charge in common VM dispatch. Load rejection executes no instruction. No intra-instruction preemption or global GC-cycle redesign is introduced.
## Calls, locals and verifier
Derive P=sum(parameter widths), L=local_slots and R=sum(result widths). A frame contains parameters, L extra locals then temporaries. GET/SET_LOCAL address only P+L; operand operations cannot consume below the temporary base. CALL consumes P caller temporaries in signature/component order and validates complete groups before publishing the frame. Concrete method receiver is the first declared parameter. No hidden closure receiver is invented by this rule.
RET requires exactly R temporaries, validates ordered types, releases frame owners and returns R slots. Wrong height uses TRAP_BAD_RET_SLOTS; unproved runtime type mismatch uses TRAP_TYPE. Locals begin as Value::Null, not numeric defaults or Uninitialized. Parameter/local slots can be reused after entry; SET_LOCAL updates abstract knowledge. Definite assignment/source variable types remain frontend concerns. Do not introduce silent Int32/Int64, concrete/trait or concrete/Dynamic conversions at boundaries.
Verifier decodes every function range, validates instruction boundaries/IDs/jump destinations, and analyzes structurally reachable control flow. Track temporary height and local/temporary facts in a finite domain: Unknown, known null, carrier facts and proven semantic/multi-slot groups. Initial parameters follow signatures; other locals start null. GET copies facts; SET replaces. Equal facts survive joins; conflicting facts become Unknown, while unequal heights are rejected. Do not require one permanent local type or infer unbounded unions/branch conditions.
Use a bounded worklist to fixed point, reprocessing widened states; decide state-dependent type errors after convergence so visitation order cannot cause rejection. Signature contracts suffice for calls; no interprocedural body inference is required. Partial group mutation invalidates relational facts. Unknown is not proof of compatibility and does not alone reject code: retain complete runtime checks. Type knowledge alone does not eliminate null/generation/bounds checks. Retain current UnknownClosureCallee protection until the separate callable/closure/coroutine contract provides a replacement contract. Exceeding memory/work budget rejects loading, never skips verification.
## Input
Input endpoints are not guest values, even transiently: no locals/globals/fields/arrays/arguments/results/Dynamic/traits. Frontends lower names directly to INTRINSIC (u16 0x0072 + u32 ID). Each query takes zero arguments; states return Bool, hold/x/y Int64. Each reads the immutable logical-frame snapshot; hold counts frames. No guest allocation, no per-query hardware polling, no stack selector. Use the existing 1-cycle intrinsic charge without redesigning global intrinsic accounting. A known unavailable query faults, never fabricates false/zero.
| Name prefix | pressed | released | down | hold |
| --- | --- | --- | --- | --- |
| input.pad.up | 0x2100 | 0x2101 | 0x2102 | 0x2103 |
| input.pad.down | 0x2104 | 0x2105 | 0x2106 | 0x2107 |
| input.pad.left | 0x2108 | 0x2109 | 0x210A | 0x210B |
| input.pad.right | 0x210C | 0x210D | 0x210E | 0x210F |
| input.pad.a | 0x2110 | 0x2111 | 0x2112 | 0x2113 |
| input.pad.b | 0x2114 | 0x2115 | 0x2116 | 0x2117 |
| input.pad.x | 0x2118 | 0x2119 | 0x211A | 0x211B |
| input.pad.y | 0x211C | 0x211D | 0x211E | 0x211F |
| input.pad.l | 0x2120 | 0x2121 | 0x2122 | 0x2123 |
| input.pad.r | 0x2124 | 0x2125 | 0x2126 | 0x2127 |
| input.pad.start | 0x2128 | 0x2129 | 0x212A | 0x212B |
| input.pad.select | 0x212C | 0x212D | 0x212E | 0x212F |
| input.touch.button | 0x2130 | 0x2131 | 0x2132 | 0x2133 |
Full name=prefix.property; input.touch.x=0x2134 and y=0x2135. Total 54 entries. Prefixes are catalogue names, not guest types. Remove old endpoint intrinsics 0x2000/0x2001, 0x2010–0x201B, 0x2020–0x2022, 0x2030–0x2033 without aliases.
## Errors and publication
| Stable load tag | Meaning |
| --- | --- |
| LOAD_INVALID_FORMAT | Binary structure, flags/UTF-8, missing/duplicate/overlapping sections, truncation or trailing bytes |
| LOAD_UNSUPPORTED_FORMAT | Unsupported PBX version, section/category or BuiltinId; no fallback |
| LOAD_INVALID_REFERENCE | Out-of-range IDs or wrong referenced categories, including immediates |
| LOAD_INVALID_REGISTRY | Forbidden duplicates/cycles, incompatible implementation signatures or inconsistent layouts |
| LOAD_INVALID_CODE | Invalid instruction/control flow/heights/proven types or declared per-function limits |
| LOAD_RESOURCE_LIMIT | Load/verification quota, unrepresentable computed size or recoverable allocation failure |
| LOAD_INVALID_ENTRYPOINT | Missing or incompatible entry under the existing boot contract |
Preserve typed reasons and available section/file offset, ID domain/record/member/parameter, function/PC and resource/requested/limit fields. Names/debug are optional; text is for humans, not parsing. Keep VerifierError structured inside VmInitError and preserve specific native/syscall resolution errors. Validate structure, records/references, layouts/signatures/implementations, bindings and code before publishing an executable image. Check budgets before dependent loops/allocations throughout. Report one error per attempt with deterministic traversal, but do not promise the same first error for multi-invalid inputs across revisions. Release partial state; never fabricate runtime PC/traps for load failures.
| Runtime fault | Code | Meaning |
| --- | --- | --- |
| TRAP_OOB | 0x00000003 | Collection/field bounds; retain specific existing local errors |
| TRAP_TYPE | 0x00000004 | Mismatch, malformed carrier/pair, wrong box type/category or incompatible implementation |
| TRAP_NULL_REFERENCE | 0x0000000E | Valid absence used where an instance is required |
| TRAP_INVALID_HANDLE | 0x0000000F | Invalid index, dead slot, stale/invalid generation |
| TRAP_RESOURCE_LIMIT | 0x00000010 | Runtime quota/size overflow/recoverable allocation failure |
| TRAP_UNAVAILABLE | 0x00000011 | Known input query unavailable on the platform |
Keep TrapInfo(code,opcode,pc,message,optional span) and current trap interruption behavior; no guest-catchable exception system. Untyped null to Int32 is TRAP_TYPE, not null dereference. Invalid handles never become false/null and are validated before following them. Preserve existing stack/function/return/intrinsic error categories. No promise to recover process/allocator abort; use fallible new allocation paths rather than operational panics.
## Memory ownership and quotas
Image constants and session-created strings are separate accounting domains; charge once per allocation identity, not text equality or reference count. Clone/pass/store shares Arc without recopying content; duplicate independent equal strings count separately. No global interning requirement. Native slots/containers pay their own storage; Registry names are not also guest constants.
Each domain tracks UTF-8 bytes and allocation count using a bounded Weak<str> ledger without a strong accounting owner. Reads remain direct Arc accesses, not handle-table lookups. Reconcile dead entries at safepoints and before quota refusal, release Weak plus charge then; Weak may retain native allocation after last strong drop, so no immediate-release promise. Keep accounting domains alive while tracked allocations survive, including host/tool retention. Import untracked native strings as charged new allocations; explicit session transfer copies into the destination domain, while shared-image constants remain shared.
Check result sizes/overflow and reserve before materializing; roll back reservations and initialized state on failure. Charge transient buffer/result coexistence. No hidden unmetered concatenation/native result paths. Do not introduce reentrant GC or scheduling at arbitrary allocation points to satisfy quotas; dead guest objects stay charged until safe sweep. Layout headers, metadata, payload capacities, native ownership, auxiliary buffers and temporary storage must have explicit nonduplicated domains. Limits are not RSS or upfront reservations.
LoadLimits uses the same defaults on hosts; cartridges cannot raise them. Test configurations may lower limits. MiB=1,048,576 bytes.
| Load resource | Accepted limit |
| --- | --- |
| PBX file | 64 MiB |
| Code section | 32 MiB |
| Type records / function records | 65,536 each |
| Implementation records | 262,144 |
| Aggregate nested Registry records | 1,048,576 |
| Individual UTF-8 name | 4,096 bytes |
| Aggregate Registry names | 4 MiB |
| Retained resolved Registry | 64 MiB per image |
| Temporary load/verifier storage | 128 MiB |
| Parameters + locals + declared maximum temporaries per frame | 16,384 slots |
| Results per function | 1,024 slots |
| Load/verifier work | 268,435,456 units |
Nested records count fields, methods, parameters/results and implementation FunctionIds. Registry charge includes capacities, names, resolution indices and reference maps, once per image, not each session. Input buffer is bounded separately from scratch. Temporary copies simultaneously alive count in their domains. Work charges one unit per input byte examined/copied/validated, record/edge processed, instruction transfer or abstract slot read/written/compared; reprocessing charges again. Charge proportional helpers, not only iterations; this is deterministic work, not wall time. Reject excess before work/reservation, never truncate/remap/infer away limits.
| Runtime/image resource | Accepted limit |
| --- | --- |
| Retained guest objects | 256 MiB per session |
| Handle-table slots including free/retired | 1,048,576 per session |
| Runtime-created/imported UTF-8 content | 64 MiB per session |
| Tracked runtime string allocations | 262,144 per session |
| Constant-string UTF-8 content | 64 MiB per image |
| Constant-pool entries, all types | 1,048,576 per image |
| Individual UTF-8 string | 4 MiB |
| Persistent auxiliary execution state | 64 MiB per session |
| Runtime operation temporary buffers | 64 MiB per session |
| Call depth including entry frame | 1,024 frames per execution flow |
Auxiliary state includes capacities of active/suspended Value stacks, frames, globals, handles/free lists, scheduler queues, string ledgers and persistent GC structures. Moving stacks between VM and coroutine transfers charges; never bill the same stack in both auxiliary and heap domains. Coroutine header/own payload remains heap-owned. Per-flow depth and per-frame cap coexist with aggregate session auxiliary cap. No separate task quota/lifecycle design is added here. Constants are checked at load; runtime excess traps. Growth must not geometrically reserve beyond available quota. Cycle/frame budgets remain separate. Asset and host admission limits are outside these totals.
@@ -78,7 +78,7 @@ GateEntry {
When an object is freed:
- `alive` becomes false;
- `generation` is incremented.
- `generation` is incremented, or the slot is permanently retired after its maximum-generation incarnation; generation must never wrap.
When a handle is used:
@@ -109,7 +109,7 @@ Object {
Properties:
- fields are stored in slot order;
- fields use declared-order typed offsets with alignment and padding; stack Value slots are not the heap layout;
- there is no raw pointer arithmetic in the VM model;
- layout rules are explicit and verifier/runtime-friendly.
@@ -200,3 +200,7 @@ Any violation results in a trap or rejected program image.
- [`15-asset-management.md`](15-asset-management.md) defines asset-bank surfaces outside VM heap ownership.
- [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md) defines save storage outside VM heap ownership.
- [`16a-syscall-policies.md`](16a-syscall-policies.md) defines host-root rules and host/heap interaction policy.
## 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.
+4 -4
View File
@@ -53,7 +53,7 @@ Within the same frame:
- `pressed: bool` (true only on transition up -> down in this frame)
- `released: bool` (true only on transition down -> up in this frame)
- `down: bool` (true while physically pressed in this frame snapshot)
- `hold: int` (count of consecutive pressed frames)
- `hold: Int64` (count of consecutive pressed frames)
`pad` is a fixed set of buttons:
@@ -63,8 +63,8 @@ Within the same frame:
`touch` exposes:
- `x: int`
- `y: int`
- `x: Int64`
- `y: Int64`
- `button` with the same `pressed/released/down/hold` semantics
PROMETEU handheld v1 uses single-touch active pointer semantics.
@@ -84,7 +84,7 @@ Input.pad().up().hold()
Input.touch().x()
```
The normative contract is intrinsic identity/version and semantics, not source syntax.
Source syntax MUST lower directly to one fixed zero-argument query; pad/touch/button are catalogue prefixes, not guest values. Endpoints cannot be stored or passed, even transiently. The complete 54-query table and removed IDs are specified in [Program Registry input](02c-program-registry-and-pbx-v1.md#input). Unknown IDs are invalid intrinsics; a known unavailable query raises TRAP_UNAVAILABLE (0x11), never a fabricated false/zero.
## 6 Determinism and Replay
+10 -6
View File
@@ -37,19 +37,19 @@ TOUCH is **absolute**:
```
TOUCH:
present : bool
down : bool
pressed : bool
released : bool
x : int
y : int
hold : Int64
x : Int64
y : Int64
```
### 3.2 Field Semantics
- **present**
- `true` if the TOUCH peripheral is available
- `false` if there is no physical touch (desktop, hardware without touch)
- **availability**
- is not a guest field or endpoint value
- a known query without a platform source raises `TRAP_UNAVAILABLE`
- **down**
- `true` while the active pointer is pressed
- **pressed**
@@ -169,3 +169,7 @@ Every PROMETEU game that uses TOUCH:
- behaves identically on all platforms
- does not depend on host-specific capabilities
- does not suffer semantic variation between desktop, mobile, and dedicated hardware
## Fixed query catalogue
Touch button queries occupy 0x2130–0x2133 (pressed/released/down/hold); x/y use 0x2134/0x2135. All have zero arguments and read the frame snapshot. Button states return Bool; hold and coordinates return Int64. See the [complete input contract](02c-program-registry-and-pbx-v1.md#input).
@@ -351,3 +351,7 @@ All machine diagnostics and profiling data:
- are collected deterministically;
- do not require a guest-visible debug ABI;
- are consistent regardless of whether host diagnostics are active or not.
## Program Registry v1 integration
Loader diagnostics MUST preserve the [structured load tags, reasons and context](02c-program-registry-and-pbx-v1.md#errors-and-publication). Signature names remain available independently of debug data; names do not establish identity. Tools must distinguish image Registry, guest heap, native strings, auxiliary execution state and temporary quotas rather than reporting their sum as RSS.
@@ -159,3 +159,9 @@ PNG pixel equality, independent logical/render identity, repeat/reset determinis
structured faults, progress on partial failure and retained desktop run/debug.
Neither Studio UI nor an AI model is required. See `tests/automation_process.rs`
in prometeu-cli and the in-process deterministic-control tests in the headless crate.
## Program Registry v1 integration
When exposing initialization failures, retain the [structured load error](02c-program-registry-and-pbx-v1.md#errors-and-publication) code, typed reason and available context. Human-readable messages are not a parsing contract; a load error has no fabricated runtime PC. Failed loads must not publish executable sessions. Existing protocol request names and transport behavior are unchanged.
Heap reference inspection values use `{"kind":"heap_ref","value":{"index":u32,"generation":u32}}`. Both components are required to distinguish a live incarnation from a reused slot; the wire representation must not truncate handles to indices. Inspection does not grant cross-session transfer authority.
+4
View File
@@ -217,3 +217,7 @@ The cartridge spec therefore distinguishes:
- [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) defines how firmware consumes cartridge metadata.
- [`14-boot-profiles.md`](14-boot-profiles.md) defines cartridge selection at boot.
- [`15-asset-management.md`](15-asset-management.md) defines the `assets.pa` envelope, asset table semantics, preload lifecycle, and residency semantics.
## Program Registry v1 integration
Program payloads MUST use the PBX v1 envelope and mandatory sections defined in [Program Registry and PBX v1](02c-program-registry-and-pbx-v1.md#pbx-v1-encoding). The file limit is 64 MiB and Code is limited to 32 MiB. Unsupported versions are rejected; runtime examples are regenerated rather than converted by a compatibility loader. The existing func_id = 0 boot authority is unchanged.
@@ -380,3 +380,7 @@ Only user-defined functions and closures are first-class.
- [`15-asset-management.md`](15-asset-management.md) defines asset-domain semantics behind some syscall families.
- [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md) defines persistent save-domain semantics.
- [`02a-vm-values-and-calling-convention.md`](02a-vm-values-and-calling-convention.md) defines the slot/call philosophy reused by the syscall ABI.
## Program Registry v1 integration
Native boundaries MUST respect the [Registry typed-value and ownership contract](02c-program-registry-and-pbx-v1.md): exact carriers and complete groups, generational reference validation, string provenance and preallocation quotas. Existing SYSC binding errors remain structured and separate from Registry errors. Input consists of 54 VM-owned fixed queries, never endpoint objects or host syscalls.
+7 -6
View File
@@ -8,7 +8,7 @@ The organization here is intentionally flat. The taxonomy is conceptual, not str
## Scope Boundary
Belongs in `docs/runtime/specs/`:
Belongs in `docs/specs/runtime/`:
- the technical contract of the PROMETEU machine;
- virtual hardware and its peripherals;
@@ -16,7 +16,7 @@ Belongs in `docs/runtime/specs/`:
- cartridge, asset, and load surfaces;
- the VM-to-host ABI.
Does not belong in `docs/runtime/specs/` as the primary canonical source:
Does not belong in `docs/specs/runtime/` as the primary canonical source:
- internal architectural invariants of the VM/runtime:
[`../virtual-machine/ARCHITECTURE.md`](../../vm-arch/ARCHITECTURE.md);
@@ -25,7 +25,7 @@ Does not belong in `docs/runtime/specs/` as the primary canonical source:
- pedagogical guides and learning material:
[`../learn/README.md`](../runtime/learn/README.md);
- agendas, proposals, and plans:
`docs/runtime/agendas/` and `docs/runtime/pull-requests/`.
`discussion/workflow/agendas/`, `discussion/workflow/decisions/` and `discussion/workflow/plans/`.
## Organization Rules
@@ -70,7 +70,7 @@ worker-owned RGBA8888 frame production and host-owned native upload/present.
- `historical`: archived material; not the authority for new implementation work.
- `pedagogical`: teaching material; does not define the technical contract on its own.
In the current state, no chapter under the active `docs/runtime/specs/` root is purely `historical`. If historical material appears, it must not compete with the primary normative surface.
In the current state, no chapter under the active `docs/specs/runtime/` root is purely `historical`. If historical material appears, it must not compete with the primary normative surface.
## Current Chapter Map
@@ -80,6 +80,7 @@ In the current state, no chapter under the active `docs/runtime/specs/` root is
| [`02-vm-instruction-set.md`](02-vm-instruction-set.md) | VM subsystem overview | normative |
| [`02a-vm-values-and-calling-convention.md`](02a-vm-values-and-calling-convention.md) | VM values and calling convention | normative |
| [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md) | VM closures and function values | normative |
| [`02c-program-registry-and-pbx-v1.md`](02c-program-registry-and-pbx-v1.md) | Registry, typed storage, PBX v1 and quotas | normative |
| [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) | VM memory model | normative |
| [`04-gfx-peripheral.md`](04-gfx-peripheral.md) | virtual hardware: graphics | normative |
| [`05-audio-peripheral.md`](05-audio-peripheral.md) | virtual hardware: audio | normative |
@@ -100,7 +101,7 @@ In the current state, no chapter under the active `docs/runtime/specs/` root is
## Authority Model
- `docs/runtime/specs/` defines the PROMETEU machine and its external execution surfaces.
- `docs/specs/runtime/` defines the PROMETEU machine and its external execution surfaces.
- [`../virtual-machine/ARCHITECTURE.md`](../../vm-arch/ARCHITECTURE.md) remains the canonical authority for internal VM/runtime invariants.
- [`../virtual-machine/ISA_CORE.md`](../../vm-arch/ISA_CORE.md) remains the authority for the bytecode ISA.
- When a chapter here touches the VM, it may complement but must not contradict the canonical VM/runtime architecture.
@@ -124,7 +125,7 @@ A topic should be created as a `spec` + `learn` pair when:
In those cases:
- `docs/runtime/specs/` defines the contract;
- `docs/specs/runtime/` defines the contract;
- `docs/runtime/learn/` explains the why, the intuition, and the examples;
- the spec should point to the pedagogical companion near the top;
- the pedagogical guide should point back to the canonical spec.