Files
prometeu-studio/docs/specs/compiler/24. Runtime Catalog Support Specification.md

148 lines
8.5 KiB
Markdown

# Runtime catalog support
Status: Normative. Owner: `compiler/general`.
Scope: Runtime Catalog Support.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## 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](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.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](../compiler-languages/pbs/18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.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.
The [PBS hashing/Identity facade](../compiler-languages/pbs/23.%20SDK%20Set%20and%20Identity%20Specification.md#hash-facade-and-typed-query-boundary)
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.