Files
prometeu-runtime/docs/specs/runtime/02c-program-registry-and-pbx-v1.md
T

25 KiB
Raw Blame History

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<Arc>: 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.