# Registry producer and consumer handoff This document describes the Registry producer and consumer interfaces. The normative contract is [Program Registry and PBX v0](../specs/runtime/02c-program-registry-and-pbx-v0.md). The rationale and published mechanisms are explained in [Registry Boundaries and Owned Values](../../discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md). The completed callable and production integration is explained in [Typed Callables and Frame-Owned Continuations](../../discussion/lessons/DSC-0052-vm-closures-captures-and-dynamic-calls/LSN-0061-typed-callables-and-frame-owned-continuations.md). ## Publication state The production `initialize` path uses bounded `ValidatedProgramImage::load` and `VirtualMachine::from_image`. The v0 decoder, slot-only verifier, scheduler and unchecked executable constructors have been removed. Internal test producers, Dummy Boy and Stress emit sealed v0 with typed Fn metadata and mandatory captures. The runtime retains existing constant/string ownership, collections, Dynamic and reference boundaries. The separate render frame scheduler remains active. Fn values, frame-owned capture environments, typed indirect calls and receiver-first trait dispatch use [the function-value contract](../specs/runtime/02b-vm-function-values-and-closures.md). FRAME_SYNC resumes next PC; successful root RET permits recurring entry preparation. The memcard byte carrier and bootstrap use the [save-memory contract](../specs/runtime/08-save-memory-and-memcard.md). General string/byte APIs, long-run stress and representative-game headroom require separate technical contracts and workloads. The external Studio handoff targets are the build-pipeline `backend/bytecode/BytecodeModule.java` and `backend/irvm/IRVMIntrinsicRegistry.java`, compiler-core `source/tables/IntrinsicTableReader.java`, PBS `lowering/PbsExecutableBodyLowerer.java`, `lowering/PbsExecutableCallsiteEmitter.java` and `semantics/PbsBuiltinLayoutResolver.java`, with their producer tests. This repository publishes requirements and oracles; those modules have not been edited. ## Exact producer obligations Emit PBX version 0 only. The header is 32 bytes: magic at 0, u16 version at 4, little-endian flag 0 at 6, reserved zero at 7, section count at 8 and twenty zero bytes at 12. Directory entries are file-relative u32 kind/offset/length triples. Mandatory kinds are 0, 1, 2, 4, 5, 6, 7 and 8; debug kind 3 is optional. Keep empty mandatory tables with count zero. Never skip unknown sections or retain a legacy fallback. Use the canonical chapter's field order and UTF-8 rules, not Rust layouts. TypeId, FunctionId and ImplementationId are independent image-local table indices; zero is valid. BuiltinIds are imports, not local TypeIds. Function records contain a lifecycle-role byte followed by optional name, ordered named parameters, ordered result TypeIds, code offset/length, extra local slots and maximum temporary slots. Names are independent of debug. Widths are derived from TypeIds; serialize no parameter/result width caches. `max_stack_slots = 0` is a literal zero limit. Boot authority remains FunctionId 0. The ten BuiltinIds are color `0x0001`, vec2 `0x0002`, pixel `0x0003`, Int32 `0x0010`, Int64 `0x0011`, Float `0x0012`, Bool `0x0013`, String `0x0014`, Dynamic `0x0015`, and Random `0x0016`. Removed input BuiltinIds `0x0100`–`0x0102` have no aliases. Struct/Trait identity is nominal; Array identity is its exact element TypeId. Do not deduplicate declarations by name or shape, or introduce array covariance. Preserve complete multi-slot groups and exact parameter/result order; use explicit accepted conversions at boundaries. HOSTCALL `0x0071` carries a syscall-declaration index. Declare canonical native module/name/version and exact ABI counts; every declaration must be used. Loading binds it to SYSCALL after capability/ABI validation. Raw SYSCALL in producer PBX, unknown declarations, invalid indices and unused declarations are rejected. ## Memcard and controlled-call lowering Emit role 0 for ordinary functions, role 1 for optional BeforePause and role 2 for optional BeforeResume. Both lifecycle hooks have no parameters, results or captures. A memcard-enabled cartridge declares capability `memcard`, a manifest `memcard_slots` count in 1..64, and exactly one role 3 function with signature `(Int64 context) -> Int32`, no captures, and a FunctionId different from zero. The compiler chooses source-level spelling; the runtime binds only the role. After frontend-owned initialization and before the first frame, emit the declared `mem.bootstrap` HOSTCALL (0 arguments, 1 Int32 result). The runtime invokes role 3 on the same VM, then resumes the producer continuation after READY and coherent registration. The producer must not directly call the role as a substitute for this gate. Use 0 READY or 1 INCONSISTENT, with bounded `mem.diagnostic` text when needed. This function executes once per boot with controlled-call fuel, outside frame accounting; Init and Frame remain frontend concepts. Declare the exact [mem ABI](../specs/runtime/08-save-memory-and-memcard.md#guest-abi). Use concrete `Array` storage for bytes 0..255, transfer at most 4096 bytes per call, and preserve the session context for subsequent calls. The array's storage charge is four bytes per element. Save requests return an opaque ID; query reports durable success/failure/indeterminate or memory-only completion, and explicit release frees the retained result. Hooks may submit/query; they must not busy-wait for disk. Initial commits are held until READY so registration and payload publication cannot deadlock each other. ## Independent binary oracles The manually specified minimal executable in `crates/console/prometeu-bytecode/tests/registry_v0.rs::minimal_bytes` is 194 bytes. Its directory begins at 32; eight entries end at 128: | Kind | Offset | Length | Payload | | --- | ---: | ---: | --- | | constants | 128 | 4 | count 0 | | functions | 132 | 30 | role 0, one unnamed zero-parameter/result function, offset 0, length 2, locals/max 0 | | code | 162 | 2 | `01 00` (HALT) | | exports | 164 | 4 | count 0 | | syscalls | 168 | 4 | count 0 | | types | 172 | 10 | one unnamed Bool import, BuiltinId `0x0013` | | implementations | 182 | 4 | count 0 | | captures | 186 | 8 | function count 1; empty environment | The independent multi-slot fixture in the same suite declares `fn(vec2)->vec2` with TypeId 0, no serialized widths, no extra locals and max 2. Its fourteen code bytes are `42 00 00 00 00 00 42 00 01 00 00 00 51 00`: GET_LOCAL 0, GET_LOCAL 1, RET. Both signature widths resolve to 2. Complement these oracles with roundtrips; do not derive every expected byte from the producer under test. ## Named arguments and observable evaluation order For a frontend whose expressions evaluate left to right, use this source-level pseudocode oracle; it is not a claim that PBS syntax has already been implemented: ```text combine(x: Int32, y: Int32) -> Int32 = x * 100 + y combine(y: effect("Y", 20), x: effect("X", 10)) ``` Expected effect order is **Y, X**. Evaluate `y` first into a temporary, then `x` into another temporary. Load the temporaries in signature order **x=10, y=20** before CALL. The result is **1020**. Reordering evaluation into parameter order would produce the wrong effect trace; pushing source order would produce **2010**. Parameter names resolve positions in the frontend; runtime CALL remains positional. An absent name prevents name-only resolution from that metadata, while positional execution remains valid. Names do not adapt trait method compatibility. ## Endpoint-free input lowering The [complete 54-entry table](../specs/runtime/02c-program-registry-and-pbx-v0.md#input) defines every accepted name/ID/result. Queries take zero guest arguments, read the logical-frame snapshot and cost one intrinsic cycle. States return Bool; hold/x/y return Int64. For example, `input.pad.a.down` lowers directly to `72 00 12 21 00 00`; `input.touch.x` uses ID `0x2134`. Do not produce an endpoint value, load it into a local or pass a selector. Removed intrinsic IDs are `0x2000`/`0x2001`, `0x2010`–`0x201B`, `0x2020`–`0x2022`, `0x2030`–`0x2033`. A removed/unknown ID differs from a known query whose platform is unavailable; the latter raises TRAP_UNAVAILABLE, not a fabricated false/zero. ## Diagnostics, ownership and consumer status Load failures preserve stable LOAD_* tags, typed reasons and available section/offset/record/member/ID/function/PC/resource fields. Native binding preserves its specific identity/capability/ABI context. Runtime resource faults preserve resource/reason/requested/limit plus opcode/PC/source span. Headless and desktop share initialization serialization; the strict `devtools/headless-protocol/response.schema.json` is the machine shape. Never parse human wording or manufacture runtime PCs for rejected loads. | Consumer | Accepted handoff | Status / remaining ownership | | --- | --- | --- | | Studio/PBS | PBX schema, signatures/names, effect-order and binary oracles, ten imports, all input IDs and diagnostics | External implementation and source-language tests pending; no external edits claimed | | Collections | Typed aligned layouts/defaults, exact storage groups, reference/native maps and checked adapters | Typed collection operations, costs, complete-group storage and GC execute through the active sealed loader | | Callables | Function/implementation tables and direct-call contracts; exact trait views | Fn, typed captures, CALL_CLOSURE/GET_CAPTURE/CALL_TRAIT and single-context production migration are implemented | | Strings/bytes/save | Arc strings, image/session Weak ledgers, bounded native writers and explicit import/export provenance | Existing string paths are integrated; new operations and their operation-specific evidence remain pending | | Resource stability | Product ceilings, generational handles, fallible capacity reservations and structured faults | Focused ownership/quota rollback is core evidence; coordinated long-run/cross-host stress requires separate workloads | | Reference game | Runtime contract, migrated example images and focused technical measurements | Game workload/headroom/readiness requires representative-game evidence, not unit test counts | Image constant allocations are shared between sessions without a session-content charge. New/imported runtime allocations belong to their session; equal text does not merge independent allocations. Native owners retain provenance alongside their Arc. `ValueSnapshot` keeps domain owners alive while tooling retains values and serializes only the ordinary value list. Cross-session import copies external content into the destination domain. Stored String slots remain `Option>`; native ownership is not a guest GC reference or an input hardware carrier. ## Callable producer obligations Emit Fn tag 4 with ordered logical parameter AND result TypeIds; parameter names do not change identity. Emit one descriptor per signature. Array/Fn structural cycles must terminate at nominal Struct/Trait anchors. Function bodies carry no hidden arg0. Captures section 8 contains a u32 function count and, for every FunctionId in order, a u32 capture count followed by ordered TypeIds; emit explicit empty lists too. Mutable bindings lower to shared private typed Struct cells; immutable captures copy their complete values. CALL/host preparation cannot enter capturing bodies. MAKE_CLOSURE 0x52 carries FunctionId/FnTypeId (10 bytes), CALL_CLOSURE 0x53 carries expected FnTypeId (6), GET_CAPTURE 0x57 carries environment-group index (6), and CALL_TRAIT 0x58 carries TraitTypeId/method index (10). Costs are 8+C, 6, 2+W and 6. Trait views follow explicit arguments; the target receives its concrete receiver first. Typed Fn can be stored in Struct/Array/Dynamic but cannot implement Trait. SPAWN/YIELD/SLEEP 0x54–0x56 reject anywhere in code. Old captures=/argc= assembler forms reject. Neither callbacks nor captures introduce a scheduling phase. External compiler acceptance requires these exact bytes and signatures, Fn pass/return/storage, shared cells, named-argument evaluation order, nested sync continuation and structured failure tests. The runtime's binary/behavioral oracles are available; no external implementation is claimed. ## Random reference consumer The runtime supports Random BuiltinId 0x0016 and the four VM-owned random intrinsics. The [random handoff](random-producer-handoff.md) supplies PBX emission, effects, variable costs and pending frontend/game acceptance tests.