# 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 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 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>: 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,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 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.