# Registry v1 producer and consumer handoff This document describes the Registry v1 producer and consumer interfaces. The normative contract is [Program Registry and PBX v1](../specs/runtime/02c-program-registry-and-pbx-v1.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). ## Publication state The bounded writer/owned decoder, sealed `ValidatedProgramImage::load`, shared session factory, typed direct-call/return boundaries, Dynamic/reference execution, fixed input catalogue, typed collection operations and string accounting have executable tests. The production `initialize` transition, removal of old unchecked entry points, all producer migration and both regenerated runtime examples remain pending. Existing closure receivers need a typed callable contract; none of the four accepted Registry categories may be used as a provisional closure type. ### Pending production integration | Component | Pending implementation and validation | | --- | --- | | Loader and image | Switch production initialize to the sealed strict v1 factory; retire old decoder and unchecked entry points while preserving typed callable behavior. | | Constant ownership | Complete image/constant provenance on migrated production entry points using the delivered ledgers and native retention domains. | | Verification | Route production loads through bounded Registry verification; remove the old verifier while adding typed callable checks. | | Diagnostics | Audit structured load/runtime/native diagnostics through the final active loader and hosts. | | Producers and examples | Migrate producers/fixtures, regenerate dummy-boy and stress-console PBX files, and execute both through the active runtime. These generators are ordinary programs sharing the production consumer being migrated. | | Conformance | Add migrated producer/example/callable evidence to this handoff and the existing conformance matrix. | | Publication | Audit final coordinated publication, legacy removal, traceability and migrated workspace/examples. | This integration reuses the delivered Registry foundation and [typed collection producer interface](collection-producer-handoff.md). New strings/bytes/save APIs, coordinated stress and representative-game headroom each require their own technical contract or validation workload. 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 1 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 and 7; 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 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 nine BuiltinIds are color `0x0001`, vec2 `0x0002`, pixel `0x0003`, Int32 `0x0010`, Int64 `0x0011`, Float `0x0012`, Bool `0x0013`, String `0x0014`, Dynamic `0x0015`. 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. ## Independent binary oracles The manually specified minimal executable in `crates/console/prometeu-bytecode/tests/registry_v1.rs::minimal_bytes` is 173 bytes. Its directory begins at 32; seven entries end at 116: | Kind | Offset | Length | Payload | | --- | ---: | ---: | --- | | constants | 116 | 4 | count 0 | | functions | 120 | 29 | one unnamed zero-parameter/result function, offset 0, length 2, locals/max 0 | | code | 149 | 2 | `01 00` (HALT) | | exports | 151 | 4 | count 0 | | syscalls | 155 | 4 | count 0 | | types | 159 | 10 | one unnamed Bool import, BuiltinId `0x0013` | | implementations | 169 | 4 | count 0 | 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-v1.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, nine 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 | Internal containers are tested; guest collection operations/costs/GC integration require a complete operation contract | | Callables | Function/implementation tables and direct-call contracts; exact trait views | Callable/capture/dispatch/coroutine semantics and coordinated producer migration remain pending | | 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, example migration requirement and 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.