docs: consolidate canonical specs and preserve PBS reference IDs

This commit is contained in:
2026-10-28 15:11:00 +00:00
parent 9504f4694a
commit 3a3417eb44
74 changed files with 3231 additions and 270 deletions
@@ -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.
+38 -16
View File
@@ -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.