148 lines
8.5 KiB
Markdown
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.
|