docs: consolidate canonical specs and preserve PBS reference IDs
This commit is contained in:
@@ -1,7 +1,7 @@
|
||||
# Bytecode and PBX Mapping Specification
|
||||
|
||||
The current typed Registry/PBX v0 contract is normative in
|
||||
[Typed common Registry and PBX v0](../../compiler/general/specs/typed-registry-and-pbx-v0.md).
|
||||
[Typed common Registry and PBX v0](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
|
||||
Its complete typed function records, mandatory sections and verification rules
|
||||
replace the earlier slot-only artifact baseline.
|
||||
|
||||
@@ -37,8 +37,8 @@ This document does not define:
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
||||
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
|
||||
2. Bytecode authority ([provider Core ISA](../../../../runtime/docs/vm-arch/ISA_CORE.md))
|
||||
3. `docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
4. `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
5. `20. IRBackend to IRVM Lowering Specification.md`
|
||||
|
||||
@@ -36,7 +36,7 @@ This document does not define:
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
|
||||
2. `1. Language Charter.md`
|
||||
3. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
4. `9. Dynamic Semantics Specification.md`
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Compiler Verification and Safety Checks Specification
|
||||
|
||||
The current typed Registry/PBX v0 contract is normative in
|
||||
[Typed common Registry and PBX v0](../../compiler/general/specs/typed-registry-and-pbx-v0.md).
|
||||
[Typed common Registry and PBX v0](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
|
||||
Its complete typed function records, mandatory sections and verification rules
|
||||
replace the earlier slot-only artifact baseline.
|
||||
|
||||
@@ -43,8 +43,8 @@ This document does not define:
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
||||
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
|
||||
2. Bytecode authority ([provider Core ISA](../../../../runtime/docs/vm-arch/ISA_CORE.md))
|
||||
3. `20. IRBackend to IRVM Lowering Specification.md`
|
||||
4. `21. IRVM Optimization Pipeline Specification.md`
|
||||
5. `15. Bytecode and PBX Mapping Specification.md`
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# IRBackend to IRVM Lowering Specification
|
||||
|
||||
The current typed Registry/PBX v0 contract is normative in
|
||||
[Typed common Registry and PBX v0](../../compiler/general/specs/typed-registry-and-pbx-v0.md).
|
||||
[Typed common Registry and PBX v0](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
|
||||
Its complete typed function records, mandatory sections and verification rules
|
||||
replace the earlier slot-only artifact baseline.
|
||||
|
||||
@@ -46,8 +46,8 @@ This document does not define:
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
||||
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
|
||||
2. Bytecode authority ([provider Core ISA](../../../../runtime/docs/vm-arch/ISA_CORE.md))
|
||||
3. This document
|
||||
4. Frontend-specific lowering specifications, including `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md`
|
||||
|
||||
|
||||
@@ -33,8 +33,8 @@ This document does not define:
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
||||
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
|
||||
2. Bytecode authority ([provider Core ISA](../../../../runtime/docs/vm-arch/ISA_CORE.md))
|
||||
3. `20. IRBackend to IRVM Lowering Specification.md`
|
||||
4. `15. Bytecode and PBX Mapping Specification.md`
|
||||
5. This document
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Backend Spec-to-Test Conformance Matrix
|
||||
|
||||
The current typed Registry/PBX v0 contract is normative in
|
||||
[Typed common Registry and PBX v0](../../compiler/general/specs/typed-registry-and-pbx-v0.md).
|
||||
[Typed common Registry and PBX v0](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
|
||||
Its complete typed function records, mandatory sections and verification rules
|
||||
replace the earlier slot-only artifact baseline.
|
||||
|
||||
|
||||
@@ -33,8 +33,8 @@ This document does not define:
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
||||
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
|
||||
2. Bytecode authority ([provider Core ISA](../../../../runtime/docs/vm-arch/ISA_CORE.md))
|
||||
3. `14. Name Resolution and Module Linking Specification.md`
|
||||
4. `20. IRBackend to IRVM Lowering Specification.md`
|
||||
5. `21. IRVM Optimization Pipeline Specification.md`
|
||||
|
||||
@@ -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.
|
||||
@@ -0,0 +1,289 @@
|
||||
# Typed common Registry and PBX v0
|
||||
|
||||
Status: Normative. Owner: `compiler/general`.
|
||||
Scope: Typed Registry and PBX v0.
|
||||
|
||||
Runtime contract reference:
|
||||
`runtime` revision `d9b9eeb171d2861ec660d4cf5703b0795eac49a9`,
|
||||
`docs/specs/runtime/02c-program-registry-and-pbx-v0.md` and
|
||||
`docs/vm-arch/ISA_CORE.md` in that repository.
|
||||
|
||||
## 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.
|
||||
|
||||
## Ownership and handoff
|
||||
|
||||
Every executable frontend MUST provide its semantic types through the common
|
||||
`IRRegistry` model and typed `FunctionMetadata`. The backend MUST NOT inspect
|
||||
language ASTs, PBS names, Optional/Result syntax, or frontend-specific classes.
|
||||
Language carriers and their lowering remain owned by the frontend. A carrier
|
||||
can use ordinary Struct, Array, Trait, Fn and Builtin declarations without
|
||||
introducing a language category in the backend.
|
||||
|
||||
The public model consists of immutable values and ordered `ReadOnlyList`
|
||||
collections. References use explicit declaration keys and callable IDs, not
|
||||
object identity or recursive object graphs. It is serializable by design;
|
||||
no concrete IR codec, wire format or persistence protocol is selected.
|
||||
|
||||
A function declares ordered named parameters, ordered logical results, ordered
|
||||
captures, a lifecycle role and an optional name. Empty names differ from absent
|
||||
names. Captures are an environment, never hidden parameters. Slot counts are
|
||||
derived from types; existing count fields are checked caches, not semantic
|
||||
input. Missing nonempty type metadata is an invalid handoff, not a request to
|
||||
infer types from counts. Optimizers MUST preserve metadata and typed operands.
|
||||
|
||||
## Identity and linking
|
||||
|
||||
TypeId, FunctionId and ImplementationId are separate dense image-local index
|
||||
domains. Index zero is valid. Trait references use TypeIds; field and method
|
||||
indices are local to their owner. Source declaration keys MUST identify the
|
||||
same declaration across repeated module imports and distinguish unrelated
|
||||
nominal declarations, even when names and shapes coincide.
|
||||
|
||||
Linking is deterministic. The selected physical entry is FunctionId zero;
|
||||
remaining functions follow canonical module/callable/source ordering. Struct
|
||||
and Trait retain nominal identity. Builtin imports deduplicate by BuiltinId,
|
||||
Array by canonical element identity, and Fn by ordered parameter/result type
|
||||
identities, excluding names. Forward references and recursion through nominal
|
||||
anchors are valid. Pure Array/Fn cycles are invalid. Every reference must
|
||||
resolve before emission. Frontends should supply only used imports.
|
||||
|
||||
File-local global slots MUST be relocated to unique image-wide slots when common
|
||||
IR files are merged. Every GET_GLOBAL and SET_GLOBAL operand must use the same
|
||||
relocation as its declaration. Lifecycle assembly preserves those linked slots
|
||||
and allocates its initialization guard after all existing image globals. Module
|
||||
boundaries do not create separate runtime global namespaces.
|
||||
|
||||
| BuiltinId | Type | Slots |
|
||||
| --- | --- | --- |
|
||||
| `0x0001` | color | 1 |
|
||||
| `0x0002` | vec2 | 2 |
|
||||
| `0x0003` | pixel | 3 |
|
||||
| `0x0010` | Int32 | 1 |
|
||||
| `0x0011` | Int64 | 1 |
|
||||
| `0x0012` | Float | 1 |
|
||||
| `0x0013` | Bool | 1 |
|
||||
| `0x0014` | String | 1 |
|
||||
| `0x0015` | Dynamic | 2 |
|
||||
| `0x0016` | Random | 1 |
|
||||
|
||||
The retired input IDs `0x0100`–`0x0102` have no aliases. Struct, Array and Fn
|
||||
values occupy one reference slot; Trait values occupy two slots. Width does
|
||||
not establish type identity or authorize conversion.
|
||||
|
||||
## Binary contract
|
||||
|
||||
All fields are little-endian. The header is 32 bytes: `PBX\0`, u16 version zero,
|
||||
zero endian/reserved bytes, u32 section count and twenty zero reserved bytes.
|
||||
Directory entries are u32 kind, file-relative offset and length. Ranges must
|
||||
not overlap or overflow. The version remains zero; no legacy fallback exists.
|
||||
|
||||
Mandatory sections are constants (0), functions (1), Code (2), exports (4),
|
||||
syscalls (5), types (6), implementations (7) and captures (8). Debug (3) is
|
||||
optional. Empty tables contain a u32 zero count. Code is raw bytes, not a
|
||||
counted table. An empty table set is serializable but is not an executable
|
||||
program: production loading requires a valid ordinary entry.
|
||||
|
||||
Lists have u32 counts. Optional names use u8 presence 0/1, then u32 UTF-8 byte
|
||||
length and bytes when present. UTF-8 is strict. Named types contain TypeId then
|
||||
optional name; results and captures contain TypeIds without names.
|
||||
|
||||
| Record | Ordered payload |
|
||||
| --- | --- |
|
||||
| Type | u8 tag, optional name, category payload |
|
||||
| Builtin (tag 0) | u32 BuiltinId |
|
||||
| Struct (tag 1) | named fields |
|
||||
| Array (tag 2) | u32 element TypeId |
|
||||
| Trait (tag 3) | methods: optional name, parameters, results |
|
||||
| Fn (tag 4) | parameters, results |
|
||||
| Function | u8 role, optional name, parameters, results, u32 Code offset, length, extra locals, max temporaries |
|
||||
| Implementation | u32 owner TypeId, trait TypeId, method count, ordered FunctionIds |
|
||||
| Captures | function count and one ordered TypeId list per function, including empty lists |
|
||||
|
||||
Function Code offsets are Code-relative. Parameter/result slot counts MUST NOT
|
||||
be serialized. Max temporaries zero means zero. Signature names are independent
|
||||
of debug names. Constants retain tags Null 0, Int64 1, Float64 2, Boolean 3,
|
||||
String 4 and Int32 5. Float payloads must be finite. Constant deduplication
|
||||
requires relocating every PUSH_CONST index; changing only the table is invalid.
|
||||
|
||||
Roles are None 0, BeforePause 1, BeforeResume 2 and MemcardBoot 3. Nonzero roles
|
||||
are unique, cannot target entry zero and cannot capture. Pause/resume have empty
|
||||
signatures; MemcardBoot has `(Int64) -> Int32`. This metadata does not implement
|
||||
frontend hook selection, mem.bootstrap gating or persistence.
|
||||
|
||||
Implementations are unique per Struct/Trait pair, complete and ordered. Each
|
||||
method target has an exact signature with a concrete Struct receiver first,
|
||||
followed by the trait method's explicit parameters. Targets cannot capture.
|
||||
|
||||
## Instructions and verification
|
||||
|
||||
Instructions use u16 opcodes. Jump operands are absolute u32 byte offsets from
|
||||
the current function start, not displacements from the next instruction.
|
||||
A taken jump to the current function end is a return boundary; ordinary
|
||||
fallthrough past the end is invalid.
|
||||
|
||||
| Opcode | Typed operands |
|
||||
| --- | --- |
|
||||
| MAKE_CLOSURE `0x52` | FunctionId, Fn TypeId |
|
||||
| CALL_CLOSURE `0x53` | expected Fn TypeId |
|
||||
| GET_CAPTURE `0x57` | capture group index |
|
||||
| CALL_TRAIT `0x58` | Trait TypeId, method index |
|
||||
| DYN_PACK/UNPACK/CAN_UNPACK `0x90`–`0x92` | TypeId |
|
||||
| Reference operations `0x93`–`0x96` | source TypeId, target TypeId |
|
||||
| REF_IDENTITY_HASH `0x97` | source TypeId; full source group → Int64 |
|
||||
| REF_IDENTITY_EQ `0x98` | left TypeId, right TypeId; full left/right groups → Bool |
|
||||
| STRUCT_NEW `0xa0` | Struct TypeId |
|
||||
| STRUCT_GET/SET `0xa1`–`0xa2` | Struct TypeId, field index |
|
||||
| Array operations `0xa3`–`0xa6` | Array TypeId |
|
||||
|
||||
Direct CALL cannot target a capturing body. Closure signatures match exactly.
|
||||
Retired SPAWN/YIELD/SLEEP (`0x54`–`0x56`) and raw producer SYSCALL are invalid,
|
||||
even when unreachable. All function ranges must decode completely; references,
|
||||
categories, operand boundaries, finite immediates and branch destinations are
|
||||
checked even in unreachable instructions.
|
||||
|
||||
Reachable analysis uses a bounded worklist. Parameters initialize local facts;
|
||||
extra locals start Null and may change type. Joins require equal temporary
|
||||
heights. Equal facts survive; conflicting facts widen to Unknown. Type errors
|
||||
are diagnosed after convergence. Unknown alone neither proves compatibility
|
||||
nor justifies rejection. Runtime group checks remain authoritative. RET and
|
||||
jump-to-end require exact result width and compatible known facts. GET/SET_LOCAL
|
||||
address only parameters plus extra locals. No implicit numeric, trait or Dynamic
|
||||
conversion is introduced by linking, writing or verification.
|
||||
|
||||
Typed identity queries accept exactly Struct, Array, Fn, Trait and builtin Random.
|
||||
They do not widen older reference-conversion category rules. Trait validates its
|
||||
complete receiver/ImplementationId pair, including valid zero, before querying
|
||||
the receiver. Both operands validate left-to-right; absent/different left does not
|
||||
short-circuit right-side validation. Scalar String/Dynamic/private value carriers
|
||||
are ineligible. Hash consumes w(source) slots and costs 8+w(source); equality
|
||||
consumes both complete groups and costs 4+w(left)+w(right). Immediates are static
|
||||
program-local TypeIds (u32 LE after u16 LE opcode), and results preserve provider
|
||||
faults, signed long bits, provenance and charged attempts, including unused results.
|
||||
Set algorithms and equality policy remain frontend/SDK consumers, described for
|
||||
PBS in [Set/Identity](../compiler-languages/pbs/23.%20SDK%20Set%20and%20Identity%20Specification.md).
|
||||
|
||||
HOSTCALL references a declared canonical `(module, name, version)` identity
|
||||
with exact argument/result slot ABI. Duplicate identities with conflicting ABI,
|
||||
unused declarations and invalid indices are rejected. Only the runtime loader
|
||||
binds capabilities and rewrites HOSTCALL to SYSCALL. Intrinsic signatures are
|
||||
explicit compiler metadata; their IDs and definitive ABI remain runtime-owned.
|
||||
|
||||
## Bounds and diagnostics
|
||||
|
||||
Product ceilings: PBX 64 MiB, Code 32 MiB, 65,536 types and functions each,
|
||||
262,144 implementations, 1,048,576 nested records, names 4,096 bytes individually
|
||||
and 4 MiB aggregate, frame 16,384 slots and results 1,024 slots. Runtime admission
|
||||
also owns retained Registry 64 MiB, scratch 128 MiB and work 268,435,456. A guest
|
||||
cannot raise these limits. Java validation is not a substitute for runtime
|
||||
allocation accounting or final `ValidatedProgramImage::load` admission.
|
||||
|
||||
Compilation failures use common LOWER_IRVM/MARSHAL stage diagnostics. Load,
|
||||
binding and resource failures remain distinct from executed traps. Studio
|
||||
preserves the full runtime error envelope in `AutomationFailure.runtimeError`,
|
||||
including null fields and native binding details. The outer initialization
|
||||
fault PC remains null. A verifier PC stays in `initError.load.pc`; a file offset
|
||||
MUST NOT become an executed PC.
|
||||
|
||||
## Reproducible conformance
|
||||
|
||||
Run the focused common tests, then the production harness:
|
||||
|
||||
```sh
|
||||
./gradlew :prometeu-compiler:prometeu-build-pipeline:test --tests '*LinkedRegistryTest' --tests '*PbxRegistryConformanceTest' --tests '*TypedCommonPipelineTest'
|
||||
python3 tools/pbx-conformance/run.py --runtime ../runtime
|
||||
```
|
||||
|
||||
The Java tests write `build/registry-conformance` inside the build-pipeline
|
||||
module. The harness builds outside the runtime checkout using its Cargo.lock,
|
||||
loads Java-produced bytes, executes admitted zero-argument fixtures, validates
|
||||
structured failures against the published schema and records the runtime hash,
|
||||
platform, capabilities and limits. Parsing, loading and execution are separate
|
||||
claims. The vec2 signature fixture is load-only; it is not a zero-argument boot.
|
||||
|
||||
The fixed 194-byte minimal image comes from the independent runtime test oracle.
|
||||
Synthetic common IR additionally exercises linking, lowering, optimization and
|
||||
emission without PBS. Frontend migration and integrated release readiness are
|
||||
tracked separately in AGD75; passing common conformance does not claim complete
|
||||
PBS lowering or complete Studio/runtime integration.
|
||||
|
||||
## Minimal typed storage and range copy
|
||||
|
||||
The supported collection storage operations are STRUCT_NEW/GET/SET (0xA0–0xA2),
|
||||
ARRAY_NEW/LEN/GET/SET (0xA3–0xA6) and ARRAY_COPY (0xA9). Logical bounds and
|
||||
multi-owner collection algorithms belong to producers. Encodings 0xA7, 0xA8,
|
||||
0xAA and 0xAB MUST be rejected at actual instruction positions, including dead
|
||||
code; identical bytes in immediates or data are not opcodes. No guard, publication
|
||||
schema, batch transaction or atomic region replaces the retired instructions.
|
||||
|
||||
ARRAY_COPY encodes u16 LE 0xA9 followed by Array TypeId u32 LE. Its five operands,
|
||||
bottom to top, are source, sourceStart, target, targetStart and count, with no
|
||||
result. Receivers MUST match the exact Array descriptor; offsets/count MUST use
|
||||
Int64. Ranges are physical, nonnegative and strict; an empty range may start at
|
||||
length. Snapshot source groups before writing for overlap. Preserve complete
|
||||
presence tags, immutable boxes, native owners and identities without unpacking
|
||||
and repacking existing values.
|
||||
|
||||
Reserve the complete TemporaryBytes scratch before writing and release it on
|
||||
success or failure. A refused instruction preserves its own operands, complete
|
||||
destinations and owners. No callback, GC or scheduler interleaves its preparation
|
||||
and commit. This guarantee covers that instruction only, not earlier instructions
|
||||
in a source method.
|
||||
|
||||
For N=count and Registry-derived element width W, attempted work is C=4+2*N*W.
|
||||
With five temporary operands and exact Int64 N in 0..u32::MAX, precharge the whole
|
||||
representable C before receiver/range/group/scratch validation and retain it on
|
||||
refusal. Underflow, wrong count carrier or count outside that interval costs base
|
||||
4 and follows ordinary fault precedence, without reading frame locals or
|
||||
converting N. Checked C overflow costs 4 and raises SizeOverflow before ordinary
|
||||
validation. Above-u32 N is not automatically an allocation SizeOverflow.
|
||||
|
||||
Otherwise fault order is height, source, target, offset/count carriers in source
|
||||
order, source range, target range, scratch reservation, source groups in order.
|
||||
N=0 still validates receivers/ranges and costs 4; aliases give no discount.
|
||||
N=10/W=1 costs 24 on success or receiver/range/scratch refusal. Zero budget does
|
||||
nothing; positive budget admits the full instruction with overshoot. A failed
|
||||
attempt reports Trap rather than BudgetExhausted and is not a successful step.
|
||||
Optimizers MUST NOT erase empty-copy validation, faults or required charged work.
|
||||
|
||||
## Neutral terminal failure and producer mutation boundaries
|
||||
|
||||
Common executable IR and IRVM represent existing TRAP (0x05) as a zero-operand,
|
||||
zero-result block terminator, preserving its source span. It raises
|
||||
TRAP_EXPLICIT, distinct from a debugger breakpoint. It neither returns nor falls
|
||||
through, and optimization MUST retain its observable failure. There is no new
|
||||
runtime opcode or encoded error argument.
|
||||
|
||||
Source producers implement logical checks with comparisons and branches. A
|
||||
trusted private PBS SDK failure binding selects this terminal instruction, not
|
||||
a backend-implemented bounds algorithm. Physical ARRAY operations retain their
|
||||
own faults/resource context. Per-instruction cycle costs and real emitted work
|
||||
apply; the retired guard costs are not simulated.
|
||||
|
||||
Collection methods prepare bounds, next sizes, values, candidates and optional
|
||||
results before the first visible mutation. A refusal before that boundary MUST
|
||||
preserve the previous collection. A fault after it may leave earlier writes and
|
||||
incomplete collection invariants; no whole-method rollback, retry or safe-reuse
|
||||
guarantee exists. Successful methods MUST restore all published invariants.
|
||||
Prepare-before-mutation does not prove every later operand/call/store infallible.
|
||||
BudgetExhausted and debugger pauses can occur between instructions and resume at
|
||||
the current PC; they neither roll back nor complete a method. No atomic observation
|
||||
of source operations by host/debugger is promised. SDK methods introduce no user
|
||||
callbacks or explicit suspension during the updates that complete their invariants.
|
||||
|
||||
## Producer-selected guest hook roots
|
||||
|
||||
BeforePause/BeforeResume role targets and their transitive dependencies MUST
|
||||
remain in the executable set even without ordinary callers. Preserve typed
|
||||
metadata through merge, lifecycle assembly, optimization and linking. Names,
|
||||
exports and frontend ASTs MUST NOT become a common role-selection mechanism.
|
||||
Common emission validates unique nonzero roles, empty pause/resume signatures
|
||||
and capture lists, and final hook FunctionIds other than zero. The ordinary
|
||||
entry and synthetic Init/Frame assembly keep role None. Calling a hook as an
|
||||
ordinary function does not request an OS transition. PBS marker syntax belongs
|
||||
to its frontend; MemcardBoot selection/bootstrap is a separate producer scope.
|
||||
@@ -1,25 +1,47 @@
|
||||
# General Specs
|
||||
# General Compiler Specifications
|
||||
|
||||
This directory contains shared acceptance specifications for all supported languages in Prometeu.
|
||||
Owner: `compiler/general`. Canonical source: `docs/specs/compiler`.
|
||||
|
||||
## Scope
|
||||
These specifications define shared frontend/backend acceptance, compilation,
|
||||
linking, typed handoff and emission. They apply across supported languages.
|
||||
[Language contracts](../compiler-languages/pbs/README.md) define PBS rules and
|
||||
refer to this layer for shared policy rather than duplicating it.
|
||||
|
||||
These specs are above language-specific specs and should be reused by each language line.
|
||||
## Authority and reading order
|
||||
|
||||
Typical topics:
|
||||
The runtime owns PBX binary layout, Core ISA, admission and VM execution.
|
||||
Read the [mirror and provenance policy](../../vm-arch/README.md) for that boundary.
|
||||
Chapters 24–25 own the detailed compiler catalog/typed-Registry consumer contracts;
|
||||
earlier pipeline, verification and matrix chapters reference them for these topics.
|
||||
Equal storage widths never replace logical identity or transfer runtime authority.
|
||||
|
||||
- conformance gates and evidence,
|
||||
- compatibility publication policy,
|
||||
- verification/safety acceptance boundaries,
|
||||
- artifact/runtime acceptance contracts.
|
||||
Start with pipeline entry points (23), then name/linking (14), typed handoff (25),
|
||||
lowering/optimization (20–21), runtime/catalog integration (16, 18, 24), and
|
||||
conformance/verification/compatibility (13, 17, 19, 22). Existing chapter numbers
|
||||
are stable and do not imply language-version numbers.
|
||||
|
||||
Current backend-facing chapter additions:
|
||||
## Chapter index
|
||||
|
||||
- `20. IRBackend to IRVM Lowering Specification.md`
|
||||
- `21. IRVM Optimization Pipeline Specification.md`
|
||||
- `22. Backend Spec-to-Test Conformance Matrix.md`
|
||||
- `23. Compiler Pipeline Entry Points Specification.md`
|
||||
- [13. Conformance Test Specification](13.%20Conformance%20Test%20Specification.md)
|
||||
- [14. Name Resolution and Module Linking Specification](14.%20Name%20Resolution%20and%20Module%20Linking%20Specification.md)
|
||||
- [15. Bytecode and PBX Mapping Specification](15.%20Bytecode%20and%20PBX%20Mapping%20Specification.md)
|
||||
- [16. Runtime Execution and Initialization Specification](16.%20Runtime%20Execution%20and%20Initialization%20Specification.md)
|
||||
- [17. Compatibility and Evolution Policy](17.%20Compatibility%20and%20Evolution%20Policy.md)
|
||||
- [18. Standard Library Surface Specification](18.%20Standard%20Library%20Surface%20Specification.md)
|
||||
- [19. Verification and Safety Checks Specification](19.%20Verification%20and%20Safety%20Checks%20Specification.md)
|
||||
- [20. IRBackend to IRVM Lowering Specification](20.%20IRBackend%20to%20IRVM%20Lowering%20Specification.md)
|
||||
- [21. IRVM Optimization Pipeline Specification](21.%20IRVM%20Optimization%20Pipeline%20Specification.md)
|
||||
- [22. Backend Spec-to-Test Conformance Matrix](22.%20Backend%20Spec-to-Test%20Conformance%20Matrix.md)
|
||||
- [23. Compiler Pipeline Entry Points Specification](23.%20Compiler%20Pipeline%20Entry%20Points%20Specification.md)
|
||||
- [24. Runtime Catalog Support Specification](24.%20Runtime%20Catalog%20Support%20Specification.md)
|
||||
- [25. Typed Registry and PBX v0 Specification](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md)
|
||||
|
||||
## Rule
|
||||
## Editorial and workflow rules
|
||||
|
||||
Language-specific specs (for example `docs/pbs/specs`) must reference this layer instead of duplicating cross-language acceptance policy.
|
||||
Write specs in English with title, status, scope, authority, normative rules,
|
||||
non-goals and conformance/exit criteria. Keep one owner per detailed contract;
|
||||
summaries link to it. Only settled decisions may change normative behavior.
|
||||
Agendas, decisions and plans live in `discussion/`, and completed teaching
|
||||
material lives in `discussion/lessons/`; they are not parallel spec sources.
|
||||
|
||||
See the [specification guide](../README.md) for other domains.
|
||||
|
||||
Reference in New Issue
Block a user