# 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. Static intrinsic String facts MUST follow the provider verifier's String-only mask: a proven null is rejected at load time. The dispatcher's acceptance of null for the String ABI does not broaden that static rule. Random's static reference mask includes null; native handle validity is still checked at runtime. 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. ## 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](typed-registry-and-pbx-v0.md) for the frontend/backend boundary and [mirror policy](../../../vm-arch/README.md) for explicit verification commands. ## PBS consumer The [PBS input and value alignment contract](../../pbs/specs/input-and-existing-type-runtime-alignment.md) 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.