193 lines
12 KiB
Markdown
193 lines
12 KiB
Markdown
# 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).
|
||
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 v1 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 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, 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 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.
|
||
|
||
## 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<Int32>` 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_v1.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-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 | 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<Arc<str>>`;
|
||
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.
|