docs: consolidate canonical specs and preserve PBS reference IDs
This commit is contained in:
@@ -0,0 +1,147 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user