7.9 KiB
Runtime catalog support
Status: normative. Owner: compiler/general.
Authority and update boundary
The runtime owns intrinsic identities, ABI layouts, effects, costs and builtin
constants. Studio MUST keep byte-identical copies of the selected provider's
INTRINSICS.csv and BUILTIN_CONSTANTS.csv under docs/vm-arch. The sibling
runtime-catalog.properties records the provider revision and SHA-256 of both
files. These mirrors are reference data, not an independent runtime contract.
An update MUST import both catalogs, inventory additions/removals and field changes, manually port the compiler consumers, verify behavior and update the packaged provenance together. A CSV-only change is not a completed integration. Read the selected runtime's implementation and tests when porting behavior; CSV fields alone do not explain dispatch, reference validation or charging.
Normal builds MUST use local versioned sources and resources. They MUST NOT query the latest runtime or depend on a sibling runtime checkout. An explicit provider verification command requires the recorded revision and fails when the source is missing, modified or different. That evidence requirement does not make a different runtime revision inherently incompatible.
Manual intrinsic representation
IRVMIntrinsicDefinition is the explicit compiler representation of its runtime
target. It MUST preserve every published record and field: IDs, canonical
identity/version, owner/name, argument/result counts and layouts, determinism,
allocation, parameter names, guest-state mutation, base/fixed cycles, cost model,
attempt cycles and maximum attempts. IRVMIntrinsicRegistry resolves exact
identities and IDs. Retired entries MUST NOT survive as aliases.
Lowering MUST validate caller-supplied counts against the selected definition. Validation and emission MUST reject unknown IDs and inconsistent signatures, including unknown IDs in unreachable bytecode. A name retained by the provider does not imply an unchanged ABI; input touch coordinates illustrate a change from receiver-based calls to zero-argument queries.
Carrier mappings MUST be explicit. Int32 and Int64 remain distinct despite equal slot widths. Layout order and complete groups MUST be preserved. Native color and Random contracts MUST NOT be inferred from arbitrary one-slot integers or references. Producer checks validate proven carrier facts; runtime admission and execution remain authoritative for reference identity, session ownership, platform availability and traps. Unsupported carrier tokens MUST fail explicitly.
Intrinsic arguments MUST use each schema-2 entry's ordered nullable mask. A proven null is admitted for hash.string's String slot; older String entries remain non-nullable. Random nullable reference admission does not remove runtime receiver/provenance checks. Do not infer nullable admission from carrier width, name, determinism or a different entry using the same ABI atom.
Determinism MUST NOT be interpreted as purity. In particular, all Random calls
mutate guest state. Reachable calls cannot be removed, merged or reordered in a
way that changes effects, traps or charged work, even when their results are
discarded. Variable-cost descriptors MUST remain variable: random.range has
base cost 4, cost 8 per attempt and a maximum of 64 attempts in the selected
contract. The runtime performs charging; Java metadata does not implement a
second scheduler or random algorithm.
Schema 2 invocation and cost metadata
Every entry MUST preserve all 25 CSV columns, including schema_version=2, arg_nullable, invocation_model, scratch_model, context_access, cost_arg_index and cost_per_byte in addition to the original 18 fields. Nullable bits are lowercase booleans in flattened argument order, exactly one per slot; zero arguments use an empty mask. Numeric carriers cannot be nullable.
Supported coherent profiles are host_buffered_v1/existing_contract_v1/host, vm_owned_v1/existing_contract_v1/vm_state and borrowed_inline_v1/none/none. The borrowed profile requires its separately declared deterministic/nonallocating/ nonmutating effects; existing Host/VM entries do not acquire borrowed semantics. Unsupported schemas, models, profiles and incoherent layouts, masks, indices or cost parameters MUST fail explicitly.
Fixed costs have no argument index, zero per-byte/attempt cost and zero attempts. random_rejection_v1 retains base 4, attempt cost 8 and at most 64 draws with the VM-owned profile. argument_utf8_bytes_v1 selects String argument zero with the borrowed profile, base 8, one cycle per UTF-8 byte and zero attempt fields. Empty or null String costs base 8 and remains subject to that entry's nullable mask. No consumer-side scheduler or hash implementation is added by importing metadata. All 108 provider entries, including hash.i64/hash.float/hash.string, are represented; metadata parity does not declare PBS hashing facades delivered.
Constants
Builtin constants have their own lookup identity (target, name, version) and
ordered slot values. They MUST NOT be resolved by inventing an intrinsic with
the same name. Some color names have both a constant and a separately published
intrinsic; this does not establish a generic equivalence.
The manual constant representation MUST preserve all carriers and exact values.
Float constants are materialized from published IEEE-754 bits. vec2.zero is
two ordered Float slots and has no intrinsic ID. Materialization and emission
MUST preserve the whole group; source-language exposure remains frontend-owned.
Distribution and conformance
The compiler JAR packages the two catalogs and provenance at
runtime-catalog/compiler/; the PBS SDK JAR packages the same three files at
runtime-catalog/pbs-sdk/. Both copies MUST derive from the checked-in mirrors
and agree byte-for-byte. The metadata identifies the represented target contract;
it does not assert that every catalog entry already has a PBS facade.
Normal tests MUST compare every manually maintained field with the independently published CSV, verify constant bits/groups and check packaged hashes. They MUST run without a runtime checkout and MUST NOT be disabled or silently skip parity. Explicit provider checks also run the real runtime catalog exporter test; parsing only one Rust table is insufficient because the catalog spans several implementation modules.
Behavioral tests MUST cover changed signatures, retired IDs, scalar carriers, complete groups, stateful call order and emitted values. Evidence from the selected runtime MUST identify revision, platform and configuration and distinguish catalog comparison, image loading and execution. PBS facade delivery and installed-runtime qualification remain separate consumer claims.
See typed common Registry and PBX v0 for the frontend/backend boundary and mirror policy for explicit verification commands.
PBS consumer
The PBS input and value alignment contract
requires typed Pad/Button dispatch, direct LowPad endpoints and complete builtin
value groups. Frontend numeric literal and builtin-constant operations retain
explicit identity and width; common lowering resolves constant groups against
IRVMBuiltinConstantDefinition and checks the declared result width. PBS does
not introduce another catalog. Source execution and the full installed example
are separate consumer gates beyond CSV parity.
The PBS hashing/Identity facade consumes hash.i64@1, hash.float@1 and hash.string@1 with exact schema-2 profiles, null admission and attempted costs. Reference hash/equality are typed Registry instructions rather than intrinsic catalog rows. Consumer support includes their common IR/emission/verification and full source-to-VM/installed qualification; catalog parity alone does not establish that integration. Collection algorithms remain source SDK code and do not add provider collection syscalls.