clean up
This commit is contained in:
@@ -0,0 +1,135 @@
|
||||
# PBS Conformance Test Specification
|
||||
|
||||
Status: Draft v1 (Quality-Gate Baseline)
|
||||
Applies to: executable quality gates for PBS language frontends and language-level regression evidence
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the minimum quality-gate contract for PBS language implementations.
|
||||
|
||||
The goal is practical and test-driven:
|
||||
|
||||
- keep quality measurable while language, lowering, and runtime integration are still evolving,
|
||||
- require only gates that can be proved with tests today,
|
||||
- avoid freezing speculative backend policy too early.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- required unit-test gates for language frontend work,
|
||||
- required regression gate behavior for published language behavior,
|
||||
- and the boundary for runtime integration regression tests when a backend can emit executable artifacts.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- runtime semantics or VM behavior taxonomy,
|
||||
- full artifact-level compatibility matrices,
|
||||
- one test harness layout,
|
||||
- or one repository structure for fixtures.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `1. Language Charter.md`
|
||||
2. `2. Governance and Versioning.md`
|
||||
3. `3. Core Syntax Specification.md`
|
||||
4. `4. Static Semantics Specification.md`
|
||||
5. `12. Diagnostics Specification.md`
|
||||
6. `13. Lowering IRBackend Specification.md`
|
||||
7. `20. IRBackend to IRVM Lowering Specification.md`
|
||||
8. `21. IRVM Optimization Pipeline Specification.md`
|
||||
9. This document
|
||||
|
||||
This document must not weaken normative requirements from higher-precedence specs.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on:
|
||||
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `12. Diagnostics Specification.md`
|
||||
- `13. Lowering IRBackend Specification.md`
|
||||
- `20. IRBackend to IRVM Lowering Specification.md`
|
||||
- `21. IRVM Optimization Pipeline Specification.md`
|
||||
- `17. Compatibility and Evolution Policy.md`
|
||||
|
||||
## 5. Quality Gate Model
|
||||
|
||||
PBS v1 uses two practical gate families.
|
||||
|
||||
### 5.1 Gate U: Language Unit Quality Gate (Required)
|
||||
|
||||
Every language frontend integrated into Studio/compiler must have passing unit tests that cover, at minimum:
|
||||
|
||||
1. lexer behavior (valid tokenization and deterministic lexical rejection),
|
||||
2. parser behavior (valid parse and deterministic syntax rejection),
|
||||
3. AST shape for representative valid programs,
|
||||
4. frontend-to-IR backend emission (`IRBackend`/`IRBackendFile`) for representative valid programs,
|
||||
5. diagnostics surface for required rejection cases (`code`, `severity`, and primary attribution).
|
||||
|
||||
This gate is mandatory for each language regardless of backend maturity.
|
||||
|
||||
### 5.2 Gate I: Integration Regression Gate With Runtime (Conditional)
|
||||
|
||||
When a language backend can emit executable artifacts (for example bytecode), integration regression tests must be introduced for that language.
|
||||
|
||||
At minimum, those tests must:
|
||||
|
||||
1. compile selected fixtures through the executable pipeline for that language,
|
||||
2. execute them against the runtime line declared for that backend,
|
||||
3. assert deterministic observable outcomes for supported fixtures,
|
||||
4. preserve fixed bugs and published supported examples as regression tests,
|
||||
5. and cover deterministic behavior across `LowerToVM`, `OptimizeIRVM`, and `EmitBytecode` boundaries when those stages are present.
|
||||
|
||||
Until executable artifact emission exists for a language, Gate I is explicitly `deferred` for that language and does not block frontend progress.
|
||||
|
||||
## 6. Regression Policy
|
||||
|
||||
Published supported behavior must remain regression-protected.
|
||||
|
||||
At minimum, each language corpus must retain:
|
||||
|
||||
1. bug reproductions for fixes that remain in supported scope,
|
||||
2. published supported examples,
|
||||
3. and core gate fixtures required to justify the language support state.
|
||||
|
||||
Regression grouping by language is expected; one shared monolithic corpus is not required.
|
||||
|
||||
## 7. Claims and Evidence
|
||||
|
||||
For PBS quality claims at this stage:
|
||||
|
||||
- a language may be considered `frontend-ready` only with Gate U passing,
|
||||
- a language may be considered `integration-ready` only with Gate U and Gate I passing where Gate I applies,
|
||||
- and a published support claim must map to executable evidence from these gates.
|
||||
- conformance-relevant FE/BE changes in executable backend paths MUST update `22. Backend Spec-to-Test Conformance Matrix.md` and pass matrix hard-gate policy checks.
|
||||
|
||||
The exact publication vocabulary is owned by `17. Compatibility and Evolution Policy.md`.
|
||||
|
||||
## 8. Explicit Deferrals
|
||||
|
||||
The following are intentionally deferred until backend/runtime contracts stabilize further:
|
||||
|
||||
- detailed artifact-level conformance taxonomy,
|
||||
- verifier-facing conformance taxonomy,
|
||||
- full compatibility matrix axes beyond the current minimum support table,
|
||||
- and one mandatory fixture repository layout.
|
||||
|
||||
## 9. Non-Goals
|
||||
|
||||
- Replacing normative language specs with tests.
|
||||
- Defining runtime semantics in this document.
|
||||
- Freezing backend architecture decisions prematurely.
|
||||
- Treating performance benchmarks as conformance gates.
|
||||
|
||||
## 10. Exit Criteria
|
||||
|
||||
This document is in a healthy state when:
|
||||
|
||||
1. every active language has an explicit Gate U status,
|
||||
2. languages with executable backends have an explicit Gate I status,
|
||||
3. published supported language behavior has regression evidence,
|
||||
4. and no support claim exists without mapped test evidence.
|
||||
@@ -0,0 +1,405 @@
|
||||
# PBS Name Resolution and Module Linking Specification
|
||||
|
||||
Status: Draft v1 (Normative)
|
||||
Applies to: scope formation, name lookup, imports, exports, barrel visibility, cross-module resolution, and semantic linking of PBS programs
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the normative name-resolution and semantic-linking model for PBS v1.
|
||||
|
||||
Its purpose is to make the visible declaration space of a PBS program deterministic enough that:
|
||||
|
||||
- frontend implementations do not invent lookup or collision rules,
|
||||
- diagnostics can classify failures consistently,
|
||||
- conformance can test source-facing rejection classes,
|
||||
- and lowering begins from an already-linked visible program.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- module scope construction,
|
||||
- lookup order by namespace,
|
||||
- import and alias resolution,
|
||||
- barrel-mediated visibility,
|
||||
- reserved stdlib shell resolution for builtin and host-backed surfaces,
|
||||
- callable visibility across modules,
|
||||
- and linking-time rejection conditions before lowering.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- runtime execution behavior,
|
||||
- optimizer or backend internals,
|
||||
- full PBX binary linking,
|
||||
- or loader/runtime artifact behavior after lowering.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `3. Core Syntax Specification.md`
|
||||
2. `4. Static Semantics Specification.md`
|
||||
3. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
4. `6. VM-owned vs Host-backed.md`
|
||||
5. `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
6. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
7. `8. Stdlib Environment Packaging and Loading Specification.md`
|
||||
8. `18. Standard Library Surface Specification.md`
|
||||
9. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence specs, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6. VM-owned vs Host-backed.md`
|
||||
- `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `8. Stdlib Environment Packaging and Loading Specification.md`
|
||||
- `18. Standard Library Surface Specification.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- PBS has distinct type, value, callable, and host-owner namespaces.
|
||||
- `mod.barrel` is the single source of module visibility.
|
||||
- Imports target modules, not files.
|
||||
- Reserved stdlib project spaces are resolved only from the selected stdlib environment.
|
||||
- Only `pub` symbols may be imported from another module.
|
||||
- Reserved stdlib/interface modules may expose compile-time-only shells for both host-backed and VM-owned surfaces, and may expose service facades over non-public host owners.
|
||||
- Source-visible builtin names are resolved through imported builtin shell declarations rather than by hardcoded source spelling alone.
|
||||
- Canonical builtin identity and canonical intrinsic identity are governed by builtin metadata rather than by the imported PBS-visible declaration name alone.
|
||||
- Canonical host identity is governed by host metadata rather than by imported owner spelling alone.
|
||||
|
||||
## 6. Module Scope Construction
|
||||
|
||||
### 6.1 Module collection
|
||||
|
||||
For one module:
|
||||
|
||||
- the compiler collects top-level declarations from all `.pbs` files in that module,
|
||||
- forms one module-level declaration space,
|
||||
- and only then applies `mod.barrel` to determine `mod` and `pub` visibility.
|
||||
|
||||
Rules:
|
||||
|
||||
- declaration existence is not derived from barrel entries,
|
||||
- module-internal top-level declaration availability does not depend on source-file order,
|
||||
- and `mod.barrel` is a visibility filter over existing declarations rather than a declaration source.
|
||||
|
||||
### 6.2 Lexical scope
|
||||
|
||||
Inside executable bodies:
|
||||
|
||||
- lexical block scope nests normally over module scope,
|
||||
- nearest local bindings win within value lookup,
|
||||
- and lexical nesting remains independent from cross-module visibility.
|
||||
|
||||
## 7. Lookup Order By Namespace
|
||||
|
||||
Lookup in PBS remains namespace-based.
|
||||
|
||||
### 7.1 Value position
|
||||
|
||||
Value-position lookup follows this order:
|
||||
|
||||
1. nearest local lexical bindings,
|
||||
2. parameters in the current lexical function scope,
|
||||
3. visible module-local values,
|
||||
4. visible imported values.
|
||||
|
||||
For lookup purposes, parameters and local `let` bindings participate in one nearest lexical value layer.
|
||||
|
||||
### 7.2 Type position
|
||||
|
||||
Type-position lookup follows this order:
|
||||
|
||||
1. visible module-local type declarations,
|
||||
2. visible imported type declarations,
|
||||
3. builtin simple types `int`, `float`, `bool`, and `str` as always-available reserved type names.
|
||||
|
||||
Builtin simple types:
|
||||
|
||||
- are not treated as ordinary imported declarations,
|
||||
- do not participate in ordinary import competition,
|
||||
- and remain always available without import.
|
||||
|
||||
### 7.3 Callable position
|
||||
|
||||
Callable-position lookup follows this order:
|
||||
|
||||
1. visible module-local callables,
|
||||
2. visible imported callables.
|
||||
|
||||
Callable lookup operates only on already-formed visible callable sets as defined later in this document.
|
||||
|
||||
### 7.4 Host-owner position
|
||||
|
||||
Host-owner lookup follows this order:
|
||||
|
||||
1. visible module-local host owners,
|
||||
2. visible imported host owners.
|
||||
|
||||
Host-owner lookup remains separate from type, value, and callable lookup.
|
||||
|
||||
## 8. Import Surface And Naming
|
||||
|
||||
### 8.1 Effective local imported name
|
||||
|
||||
The local visible name introduced by an import is always the post-alias name when an alias is present.
|
||||
|
||||
Rules:
|
||||
|
||||
- `import { X } from @project:path;` introduces the visible local name `X`,
|
||||
- `import { X as Y } from @project:path;` introduces only the visible local name `Y`,
|
||||
- and alias spelling changes only the local visible name, never canonical builtin identity or canonical host identity.
|
||||
|
||||
### 8.2 Named import
|
||||
|
||||
`import { X } from @project:path;`:
|
||||
|
||||
- resolves the target module,
|
||||
- checks that `X` is exported and importable from that module,
|
||||
- and introduces `X` into the corresponding namespace locally.
|
||||
|
||||
### 8.3 Whole-module import
|
||||
|
||||
`import { * } from @project:path;`:
|
||||
|
||||
- resolves the target module,
|
||||
- introduces the target module's exported visible names under their exported spellings,
|
||||
- but does not create a module-valued binding,
|
||||
- does not create a namespace object,
|
||||
- and does not authorize qualified member access by itself.
|
||||
|
||||
If PBS later wants module-object or namespace-qualified source semantics, that must be added explicitly rather than inferred from this import form.
|
||||
|
||||
## 9. Collision And Ambiguity Rules
|
||||
|
||||
### 9.1 Local versus imported
|
||||
|
||||
If a module-local declaration and an imported declaration produce the same visible name in the same namespace:
|
||||
|
||||
- the program is rejected,
|
||||
- and the implementation must not silently shadow either declaration.
|
||||
|
||||
This includes function names.
|
||||
A module-local function and an imported function with the same visible name are rejected rather than merged.
|
||||
|
||||
### 9.2 Imported versus imported
|
||||
|
||||
If two imports produce the same visible name in the same namespace:
|
||||
|
||||
- the program is not rejected only when both imports resolve to the same canonical underlying declaration after module resolution,
|
||||
- such same-origin duplication is redundant but tolerated,
|
||||
- and the program is rejected if the imports resolve to different canonical underlying declarations.
|
||||
|
||||
### 9.3 Namespace separation
|
||||
|
||||
Names in different namespaces do not collide merely by spelling.
|
||||
|
||||
For example:
|
||||
|
||||
- a host owner and a type declaration do not collide by spelling alone,
|
||||
- because host-owner namespace remains distinct from type namespace.
|
||||
|
||||
### 9.4 Non-callable names do not merge
|
||||
|
||||
Non-callable namespaces do not merge by name.
|
||||
|
||||
## 10. Callable Sets And Cross-Module Linking
|
||||
|
||||
### 10.1 Imported callable set
|
||||
|
||||
`import { f } from @project:path;` imports the exported callable set named `f` from the target module.
|
||||
|
||||
Rules:
|
||||
|
||||
- the imported callable set for `f` consists only of those overload signatures of `f` that are exported through that module's `mod.barrel`,
|
||||
- non-exported overloads in the target module do not participate in the imported callable set,
|
||||
- and import operates on the exported callable name rather than on one overload at a time.
|
||||
|
||||
### 10.2 Same-origin versus different-origin callable imports
|
||||
|
||||
If the same visible callable name is imported more than once:
|
||||
|
||||
- same-origin duplicate imports are tolerated as redundancy when they resolve to the same canonical callable-set origin,
|
||||
- different-origin imports are rejected immediately,
|
||||
- and the implementation must not wait until a callsite to reject different-origin callable-name collisions.
|
||||
|
||||
### 10.3 Local versus imported callable names
|
||||
|
||||
If a module-local function name and an imported function name are the same visible callable name:
|
||||
|
||||
- the program is rejected immediately,
|
||||
- and the implementation must not merge the local and imported callable sets.
|
||||
|
||||
### 10.4 Overload-resolution boundary
|
||||
|
||||
PBS separates:
|
||||
|
||||
- callable-set formation,
|
||||
- and overload resolution at a callsite.
|
||||
|
||||
Rules:
|
||||
|
||||
- the implementation must first form one unambiguous visible callable set,
|
||||
- only then may ordinary overload resolution operate on the candidate signatures of that set,
|
||||
- and callsite context must not be used to resolve ambiguity between different imported callable origins.
|
||||
|
||||
## 11. Reserved Stdlib Shell Resolution
|
||||
|
||||
### 11.1 Reserved shells as imported declarations
|
||||
|
||||
Source-visible declarations exposed by reserved builtin shells are imported into their ordinary corresponding namespaces.
|
||||
|
||||
This means:
|
||||
|
||||
- builtin-exposed types enter type lookup as imported type declarations,
|
||||
- builtin-exposed constants enter value lookup as imported values,
|
||||
- and host owners enter host-owner lookup as imported host-owner declarations.
|
||||
|
||||
`declare builtin type` itself remains a reserved stdlib/toolchain declaration form rather than ordinary user-authored source syntax.
|
||||
|
||||
### 11.2 Builtin simple types versus imported builtin shells
|
||||
|
||||
PBS distinguishes:
|
||||
|
||||
- the predeclared builtin simple-type set `int`, `float`, `bool`, `str`,
|
||||
- and imported builtin shells such as `Vec2` or `Color`.
|
||||
|
||||
Imported builtin shells are not promoted to the same always-available status as builtin simple types.
|
||||
|
||||
### 11.3 Intrinsic member lookup
|
||||
|
||||
Builtin intrinsic methods:
|
||||
|
||||
- never participate in free lookup,
|
||||
- are not introduced by import as free functions,
|
||||
- and are resolved only through member lookup on a receiver already known to have the corresponding builtin type.
|
||||
|
||||
Alias changes to the imported builtin type affect only the local visible owner spelling, not the canonical builtin or intrinsic identity.
|
||||
|
||||
### 11.4 Collision policy for reserved shells
|
||||
|
||||
Reserved builtin shells and host owners follow the same collision policy as ordinary imported declarations.
|
||||
|
||||
Rules:
|
||||
|
||||
- same visible name in the same namespace is an error unless another already-closed rule explicitly permits otherwise,
|
||||
- reserved-shell status does not authorize silent shadowing,
|
||||
- and host owners do not collide with types or values merely by spelling because host-owner namespace remains separate.
|
||||
|
||||
### 11.5 Reserved project-space policy
|
||||
|
||||
For source-level policy:
|
||||
|
||||
- builtin shells are preferred under `@core:*`,
|
||||
- and host-facing capability surfaces remain the natural fit for `@sdk:*`.
|
||||
|
||||
### 11.6 Canonical identity
|
||||
|
||||
Canonical builtin identity and canonical host identity are not derived from local alias spelling.
|
||||
|
||||
Duplicate canonical builtin identities or duplicate canonical host identities in one resolved environment are rejected as linking failures.
|
||||
|
||||
## 12. Linking Phase Boundary And Deterministic Failures
|
||||
|
||||
### 12.1 Normative phase baseline
|
||||
|
||||
PBS v1 adopts the following normative phase baseline for name resolution and related frontend failures:
|
||||
|
||||
1. `syntax`
|
||||
2. `manifest/import resolution`
|
||||
3. `linking`
|
||||
4. `static semantics`
|
||||
|
||||
### 12.2 Syntax
|
||||
|
||||
`syntax` owns malformed import grammar and other token-shape or grammar-shape failures.
|
||||
|
||||
### 12.3 Manifest and import resolution
|
||||
|
||||
`manifest/import resolution` owns failures to resolve:
|
||||
|
||||
- project space,
|
||||
- reserved stdlib space,
|
||||
- dependency graph target,
|
||||
- module path,
|
||||
- or environment source.
|
||||
|
||||
### 12.4 Linking
|
||||
|
||||
`linking` owns assembly of visible declarations across files and modules.
|
||||
|
||||
At minimum, `linking` owns:
|
||||
|
||||
1. import of non-exported names,
|
||||
2. unresolved barrel entries against module declarations,
|
||||
3. collisions between visible imported names from different canonical origins,
|
||||
4. local-versus-import visibility collisions,
|
||||
5. callable-origin conflicts across module boundaries,
|
||||
6. duplicate canonical builtin identities in one resolved environment,
|
||||
7. duplicate canonical host identities in one resolved environment.
|
||||
|
||||
### 12.5 Static semantics
|
||||
|
||||
`static semantics` owns:
|
||||
|
||||
1. duplicate local declarations,
|
||||
2. declaration validity,
|
||||
3. type checking,
|
||||
4. member lookup once the receiver type is known,
|
||||
5. overload resolution within an already-formed visible callable set.
|
||||
|
||||
Member lookup failure on an already-typed builtin receiver therefore belongs to `static semantics`.
|
||||
|
||||
### 12.6 Imported-origin conflicts are rejected before callsite analysis
|
||||
|
||||
Conflicts between different imported origins are rejected in `linking` immediately.
|
||||
|
||||
The implementation must not:
|
||||
|
||||
- wait for a specific callsite,
|
||||
- use overload resolution to rescue imported-origin ambiguity,
|
||||
- or defer visible declaration conflicts to later typing work.
|
||||
|
||||
## 13. Deterministic Resolution Failures
|
||||
|
||||
At minimum, a conforming implementation must reject:
|
||||
|
||||
1. import of a non-exported builtin type shell,
|
||||
2. import of a non-exported builtin constant shell,
|
||||
3. import of a non-exported host owner shell,
|
||||
4. import of any non-exported name from a resolved module,
|
||||
5. unresolved barrel entries against module declarations,
|
||||
6. local-versus-import same-namespace collisions,
|
||||
7. imported same-name collisions from different canonical origins,
|
||||
8. local-versus-import function-name collisions,
|
||||
9. duplicate visible builtin type declarations that claim the same canonical builtin identity in one resolved environment,
|
||||
10. duplicate visible builtin constants that claim the same canonical builtin constant identity in one resolved environment,
|
||||
11. duplicate visible host owners that claim the same canonical host identity in one resolved environment,
|
||||
12. member lookup on a builtin receiver where the imported builtin shell does not declare the requested field or intrinsic member,
|
||||
13. any resolution path that attempts to derive host or builtin canonical identity from alias spelling alone.
|
||||
|
||||
## 14. Non-Goals
|
||||
|
||||
- Reopening the already-settled import surface syntax.
|
||||
- Defining runtime loader behavior.
|
||||
- Freezing one compiler symbol-table implementation.
|
||||
- Freezing one internal compiler pass graph.
|
||||
|
||||
## 15. Exit Criteria
|
||||
|
||||
This document is ready to move beyond its current draft status only when:
|
||||
|
||||
1. name lookup is deterministic across all relevant scopes,
|
||||
2. barrel and module linking behavior is explicit,
|
||||
3. reserved stdlib shell resolution is explicit for host-backed and VM-owned surfaces,
|
||||
4. cross-module callable visibility and ambiguity behavior are normatively defined,
|
||||
5. and the phase ownership of source-facing name-resolution failures is explicit enough for diagnostics and conformance.
|
||||
@@ -0,0 +1,178 @@
|
||||
# PBS Bytecode and PBX Mapping Specification
|
||||
|
||||
Status: Draft v1 (Backend Baseline)
|
||||
Applies to: mapping from lowered/optimized backend programs into PBX sections, bytecode-facing artifacts, and source-to-artifact invariants required by loader/verifier/runtime
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the normative mapping between backend-lowered semantics and emitted PBX/bytecode-facing artifacts.
|
||||
|
||||
Its purpose is to keep artifact emission deterministic and compatible with runtime loader/verifier contracts.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- artifact-level obligations at `IRVM -> BytecodeModule` emission boundary,
|
||||
- mapping invariants for function layout, code layout, callsite forms, and host-binding declarations,
|
||||
- minimum debug/source-attribution hooks for v1 backend/runtime diagnostics and conformance,
|
||||
- and deterministic artifact rejection expectations for emitter-side failures.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- full ISA semantics,
|
||||
- runtime loader patching internals,
|
||||
- or one mandatory emitter implementation architecture.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
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`)
|
||||
3. `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
4. `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
5. `20. IRBackend to IRVM Lowering Specification.md`
|
||||
6. `21. IRVM Optimization Pipeline Specification.md`
|
||||
7. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `20. IRBackend to IRVM Lowering Specification.md`
|
||||
- `21. IRVM Optimization Pipeline Specification.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following are fixed and must not be contradicted:
|
||||
|
||||
- The compiler emits host-binding declarations in PBX `SYSC`.
|
||||
- Host-backed callsites are emitted in pre-load form as `HOSTCALL <sysc_index>`.
|
||||
- `SYSC` entries are deduplicated by canonical identity and ordered by first occurrence.
|
||||
- The loader resolves host bindings and rewrites `HOSTCALL` to `SYSCALL` before execution.
|
||||
- Raw `SYSCALL` in pre-load artifacts is rejected.
|
||||
- VM-owned intrinsic artifacts are distinct from `SYSC`, `HOSTCALL`, and `SYSCALL`.
|
||||
- `SYSC` section is mandatory in valid PBX artifacts (empty section is valid).
|
||||
|
||||
## 6. Artifact Mapping Contract (v1)
|
||||
|
||||
### 6.1 Required module surfaces
|
||||
|
||||
Emitter output must map to a `BytecodeModule` shape containing:
|
||||
|
||||
1. `const_pool`,
|
||||
2. `functions`,
|
||||
3. `code`,
|
||||
4. `exports`,
|
||||
5. `syscalls`,
|
||||
6. optional `debug_info` that still satisfies v1 minimum debug obligations.
|
||||
|
||||
### 6.2 Function ordering and IDs
|
||||
|
||||
Function ordering must be deterministic:
|
||||
|
||||
1. entrypoint function index is `0`,
|
||||
2. entrypoint index `0` is selected from qualified `EntrypointRef(entryPointModuleId, entryPointCallableName)`,
|
||||
3. remaining functions are ordered by `(moduleId -> modulePool canonical key, callable_name, source_start)`,
|
||||
4. identical admitted input graph yields identical function ordering and function ids.
|
||||
|
||||
### 6.3 Function code layout
|
||||
|
||||
Emitter must satisfy:
|
||||
|
||||
1. `code_offset` values are unique and monotonic over function order,
|
||||
2. `code_len` exactly matches emitted bytes for each function body,
|
||||
3. `code_offset + code_len` stays within `code.len`,
|
||||
4. and final code concatenation is deterministic.
|
||||
|
||||
### 6.4 Instruction encoding
|
||||
|
||||
Emitter must satisfy:
|
||||
|
||||
1. little-endian encoding,
|
||||
2. instruction layout `[opcode: u16][immediate]`,
|
||||
3. jump immediates as `u32` offsets relative to function start,
|
||||
4. immediate sizes matching selected Core ISA opcode spec.
|
||||
|
||||
### 6.5 Host-backed mapping obligations
|
||||
|
||||
For host-backed operations:
|
||||
|
||||
1. emit canonical declarations in `SYSC` (`module`, `name`, `version`, `arg_slots`, `ret_slots`),
|
||||
2. deduplicate by canonical identity,
|
||||
3. order by first occurrence,
|
||||
4. emit callsites as `HOSTCALL <sysc_index>` only,
|
||||
5. do not emit raw `SYSCALL` in pre-load artifact form.
|
||||
|
||||
### 6.6 VM-owned intrinsic mapping obligations
|
||||
|
||||
For VM-owned intrinsic operations:
|
||||
|
||||
1. emit VM-owned intrinsic call form (`INTRINSIC <id>`),
|
||||
2. resolve `<id>` from the canonical ISA-scoped intrinsic registry artifact,
|
||||
3. keep intrinsic path distinct from host-binding metadata and host call opcodes,
|
||||
4. and do not emit VM-owned builtin/intrinsic semantics through `SYSC`.
|
||||
|
||||
### 6.7 Internal symbolic-to-index mapping
|
||||
|
||||
Compilers may use internal symbolic references before final index materialization.
|
||||
|
||||
If used, symbolic references must be resolved deterministically to final numeric indices before serialization.
|
||||
|
||||
## 7. Minimum Debug Attribution Contract (v1)
|
||||
|
||||
For v1 backend/runtime diagnostics and conformance support, emitted artifacts must preserve at minimum:
|
||||
|
||||
1. `function_names` entries for all emitted function indices,
|
||||
2. `pc_to_span` entries for each emitted instruction start PC.
|
||||
|
||||
This minimum does not require one universal source-map format.
|
||||
|
||||
## 8. Deterministic Emitter Rejection
|
||||
|
||||
Emitter-side rejection must be deterministic for malformed or inconsistent artifact candidates, including at minimum:
|
||||
|
||||
1. inconsistent function layout bounds,
|
||||
2. unresolved symbolic references at serialization boundary,
|
||||
3. illegal pre-load host call form (`SYSCALL` in pre-load image),
|
||||
4. duplicate `SYSC` canonical identities,
|
||||
5. and declared host ABI shape mismatch detectable at compile target metadata line.
|
||||
|
||||
## 9. Conformance-Facing Baseline
|
||||
|
||||
At minimum, artifact conformance checks should assert:
|
||||
|
||||
1. canonical `SYSC` declarations for admitted host-backed operations,
|
||||
2. deterministic `SYSC` dedup/order,
|
||||
3. pre-load `HOSTCALL` callsites for host-backed paths,
|
||||
4. no host-binding leakage for VM-owned intrinsic/builtin operations,
|
||||
5. minimum debug attribution hooks required by v1,
|
||||
6. deterministic function ordering and code layout invariants.
|
||||
|
||||
## 10. Explicit Deferrals
|
||||
|
||||
The following remain deferred:
|
||||
|
||||
- richer optional debug/source-map formats,
|
||||
- additional PBX section-level contracts beyond current baseline,
|
||||
- and profile-specific binary compatibility policy details beyond current v1 baseline.
|
||||
|
||||
## 11. Non-Goals
|
||||
|
||||
- Repeating full ISA/runtime documentation.
|
||||
- Mandating one byte-for-byte whole-image golden as sole conformance oracle.
|
||||
- Defining loader patching internals already owned elsewhere.
|
||||
|
||||
## 12. Exit Criteria
|
||||
|
||||
This document is healthy when:
|
||||
|
||||
1. artifact mapping obligations are explicit and testable,
|
||||
2. host-backed and VM-owned emission boundaries are explicit,
|
||||
3. deterministic ordering/layout rules are explicit,
|
||||
4. and v1 minimum debug/source attribution contract is explicit.
|
||||
+155
@@ -0,0 +1,155 @@
|
||||
# PBS Runtime Execution and Initialization Specification
|
||||
|
||||
Status: Draft v1 (Temporary)
|
||||
Applies to: runtime startup, entry behavior, module/service initialization, and execution lifecycle of PBS programs after successful load
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the PBS-visible runtime entry and execution-lifecycle contract after successful artifact load.
|
||||
|
||||
Its purpose is to keep runtime startup, frame-driven execution, and fatal-failure behavior aligned with:
|
||||
|
||||
- runtime authority,
|
||||
- dynamic semantics,
|
||||
- memory/lifetime guarantees,
|
||||
- and the closed capability-gated host model.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- when PBS program execution may begin,
|
||||
- which preconditions must already hold before userland runs,
|
||||
- the runtime execution model of a loaded PBS program instance,
|
||||
- the only normative frame/safepoint boundary in v1,
|
||||
- and which startup or fatal-failure outcomes are PBS-visible.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- loader-side host resolution details,
|
||||
- the full packaging or process model,
|
||||
- scheduler models outside the v1 single-threaded execution contract,
|
||||
- shutdown/finalization APIs or hooks,
|
||||
- or subsystem-specific host resource lifecycles.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
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. `1. Language Charter.md`
|
||||
3. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
4. `9. Dynamic Semantics Specification.md`
|
||||
5. `10. Memory and Lifetime Specification.md`
|
||||
6. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `1. Language Charter.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
||||
- `9. Dynamic Semantics Specification.md`
|
||||
- `10. Memory and Lifetime Specification.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- `FRAME_SYNC`-based execution semantics are preserved.
|
||||
- Loader-side host binding resolution and capability gating happen before program execution begins.
|
||||
- A PBS program instance executes single-threaded in v1.
|
||||
- Dynamic semantics are deterministic at the language-observable level.
|
||||
- Any runtime trap aborts PBS program execution and enters the runtime/firmware crash path rather than a userland recovery path.
|
||||
- Service values are canonical module-owned singleton values.
|
||||
- Top-level executable statements are forbidden in PBS source modules.
|
||||
|
||||
## 6. Runtime Entry Preconditions
|
||||
|
||||
PBS userland execution may begin only after all of the following are true:
|
||||
|
||||
1. the program artifact has been accepted by the relevant runtime/load authority,
|
||||
2. capability gating and host-binding resolution required for startup have completed successfully,
|
||||
3. runtime state required to begin frame-driven execution has been established,
|
||||
4. and no prior fatal startup failure has occurred.
|
||||
|
||||
If these preconditions are not satisfied, ordinary PBS userland execution does not begin.
|
||||
|
||||
This document does not define loader-internal sequencing in detail; it only defines that the userland-visible start boundary occurs after successful load- and capability-level admission.
|
||||
|
||||
## 7. Program Instance Model
|
||||
|
||||
Each loaded PBS program executes as one single-threaded program instance in v1.
|
||||
|
||||
Within a program instance:
|
||||
|
||||
- userland execution is not concurrently interleaved by another userland thread,
|
||||
- the dynamic-semantics evaluation order defined in `9. Dynamic Semantics Specification.md` remains authoritative,
|
||||
- and runtime/host activity must not perturb that language-level sequencing.
|
||||
|
||||
PBS source modules do not contribute a user-authored top-level execution phase. Any startup activity that exists outside ordinary function/method execution is runtime-owned unless and until another specification makes a narrower PBS-visible contract explicit.
|
||||
|
||||
## 8. Frame Boundary and Host Work
|
||||
|
||||
`FRAME_SYNC` is the only normative runtime step boundary and the only normative safepoint in PBS v1.
|
||||
|
||||
Consequences:
|
||||
|
||||
- the runtime may use the interval around `FRAME_SYNC` to process host-side demands and internal work,
|
||||
- userland execution must remain semantically ordered as defined by `9. Dynamic Semantics Specification.md`,
|
||||
- and PBS user code cannot rely on any other boundary as a guaranteed safepoint, collection point, or scheduling point.
|
||||
|
||||
Internal runtime work may exist outside `FRAME_SYNC`, but it must remain semantically invisible to PBS userland unless a higher-precedence authority explicitly defines otherwise.
|
||||
|
||||
## 9. Failure and Non-Start Conditions
|
||||
|
||||
PBS distinguishes between two broad classes of failure at this layer:
|
||||
|
||||
1. non-start conditions, where userland never begins because artifact admission, capability checks, or required startup preconditions fail;
|
||||
2. fatal runtime traps, where an already-running PBS program aborts.
|
||||
|
||||
Traps are not recoverable in PBS userland. When a trap occurs:
|
||||
|
||||
- it does not enter `result` flow,
|
||||
- it is not intercepted by `handle`,
|
||||
- and it aborts the PBS program execution path into the runtime/firmware crash path.
|
||||
|
||||
This document does not define a userland-visible trap catalog.
|
||||
|
||||
## 10. Service and Module Initialization Boundaries
|
||||
|
||||
The current v1 baseline is intentionally narrow:
|
||||
|
||||
- service values are canonical singleton values,
|
||||
- top-level executable statements do not exist,
|
||||
- and no userland-visible module-initialization statement phase is defined here.
|
||||
|
||||
The exact timing at which service-owned runtime state becomes initialized and observable remains an open item for this document. Until that is closed, implementations must not infer extra userland-visible initialization hooks beyond what is already guaranteed by higher-precedence specs.
|
||||
|
||||
## 11. TODO
|
||||
|
||||
The following items remain open for later closure:
|
||||
|
||||
- the exact runtime entry contract between successful load and first userland-observable execution,
|
||||
- whether service-owned runtime state has a more precise initialization point than the baseline stated here,
|
||||
- which runtime lifecycle boundaries, if any, are userland-observable beyond `FRAME_SYNC` and trap abort,
|
||||
- and whether shutdown behavior has any PBS-visible contract in v1.
|
||||
|
||||
## 12. Non-Goals
|
||||
|
||||
- Defining OS/process lifecycle outside Prometeu runtime authority.
|
||||
- Reopening the ban on top-level executable statements.
|
||||
- Designing a future async runtime.
|
||||
- Defining userland recovery from trap.
|
||||
|
||||
## 13. Exit Criteria
|
||||
|
||||
This document is ready to move beyond temporary status only when:
|
||||
|
||||
1. runtime startup and non-start boundaries are normatively described,
|
||||
2. service and module runtime lifecycle assumptions are explicit enough to remove the remaining TODO items,
|
||||
3. execution lifecycle boundaries are aligned with dynamic semantics and runtime authority,
|
||||
4. and the document no longer relies on unresolved TODO items for ordinary v1 runtime startup behavior.
|
||||
@@ -0,0 +1,119 @@
|
||||
# PBS Compatibility and Evolution Policy
|
||||
|
||||
Status: Draft v0 (Quality-Gate Baseline)
|
||||
Applies to: practical support states and compatibility publication policy tied to executable quality gates
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines how PBS support is published at the current project stage.
|
||||
|
||||
The policy is intentionally minimal:
|
||||
|
||||
- publish only support claims that are backed by tests,
|
||||
- use a small support-state model that a solo project can maintain,
|
||||
- and avoid over-specifying compatibility promises before backend/runtime contracts settle.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- support-state vocabulary for language lines,
|
||||
- minimum published support table fields,
|
||||
- and how support-state changes must be recorded.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- full deprecation-window math per domain,
|
||||
- one binary/PBX compatibility model,
|
||||
- one release process implementation.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `1. Language Charter.md`
|
||||
2. `2. Governance and Versioning.md`
|
||||
3. `13. Conformance Test Specification.md`
|
||||
4. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on:
|
||||
|
||||
- `2. Governance and Versioning.md`
|
||||
- `13. Conformance Test Specification.md`
|
||||
|
||||
## 5. Support States
|
||||
|
||||
PBS currently uses three support states:
|
||||
|
||||
- `unsupported`
|
||||
- `experimental`
|
||||
- `supported`
|
||||
|
||||
Meaning:
|
||||
|
||||
- `unsupported`: no compatibility promise.
|
||||
- `experimental`: active development; behavior may change; tests may exist but are not yet a stable support promise.
|
||||
- `supported`: active compatibility promise for declared scope, backed by required quality gates.
|
||||
|
||||
## 6. Gate-Backed Support Rule
|
||||
|
||||
Support states must map to quality-gate evidence:
|
||||
|
||||
1. `frontend-ready` evidence requires Gate U from `13`.
|
||||
2. `integration-ready` evidence requires Gate U plus Gate I when Gate I applies to the language/backend.
|
||||
3. `supported` state requires maintained evidence for the scope being promised.
|
||||
|
||||
No published `supported` claim may exist without mapped test evidence.
|
||||
Unsupported executable surfaces excluded from a claim (for example `SPAWN`/`YIELD` outside `core-v1`) MUST be stated explicitly in published notes.
|
||||
|
||||
## 7. Minimum Published Support Table
|
||||
|
||||
A published support table must include, at minimum:
|
||||
|
||||
1. language identifier,
|
||||
2. language line/version scope,
|
||||
3. runtime line (or `N/A` when Gate I is not applicable yet),
|
||||
4. Gate U status,
|
||||
5. Gate I status (`pass`, `fail`, or `deferred`),
|
||||
6. support state (`unsupported`, `experimental`, `supported`),
|
||||
7. optional notes.
|
||||
|
||||
No additional matrix dimensions are mandatory at this stage.
|
||||
|
||||
## 8. Support-State Changes
|
||||
|
||||
When support changes, the project must update together:
|
||||
|
||||
1. support table state,
|
||||
2. gate evidence status,
|
||||
3. and a short rationale note when users could be affected.
|
||||
|
||||
This document requires visibility of change, not a specific changelog format.
|
||||
|
||||
## 9. Explicit Deferrals
|
||||
|
||||
The following remain intentionally open:
|
||||
|
||||
- domain-specific promise strength beyond the current gate-backed model,
|
||||
- exact deprecation/removal windows,
|
||||
- PBX/binary compatibility policy details,
|
||||
- mandatory migration tooling triggers.
|
||||
|
||||
## 10. Non-Goals
|
||||
|
||||
- Simulating large-organization compatibility governance.
|
||||
- Freezing domains that are still not implemented.
|
||||
- Requiring one matrix tooling format.
|
||||
|
||||
## 11. Exit Criteria
|
||||
|
||||
This document is in a healthy state when:
|
||||
|
||||
1. every active language line has an explicit support state,
|
||||
2. every `supported` state has mapped gate evidence,
|
||||
3. support changes are reflected in table + evidence + note,
|
||||
4. and no compatibility promise depends on undocumented assumptions.
|
||||
@@ -0,0 +1,188 @@
|
||||
# PBS Standard Library Surface Specification
|
||||
|
||||
Status: Draft v0 (Skeleton)
|
||||
Applies to: normative stdlib-facing API surface, reserved stdlib project spaces, and versioned standard-library contracts exposed to PBS programs
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document will define the normative user-facing standard-library surface for PBS.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document is intended to define:
|
||||
|
||||
- what counts as part of the PBS stdlib contract,
|
||||
- how stdlib modules are grouped and versioned,
|
||||
- which APIs are normative versus implementation-private,
|
||||
- how VM-owned builtin shells are exposed to user code,
|
||||
- how reserved stdlib project spaces expose user-facing surfaces over host-backed capabilities.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- one physical packaging layout,
|
||||
- registry/publication mechanics,
|
||||
- host loader behavior,
|
||||
- implementation-private helper modules.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
2. `8. Stdlib Environment Packaging and Loading Specification.md`
|
||||
3. `6. VM-owned vs Host-backed.md`
|
||||
4. `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
5. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
6. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence specs, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6. VM-owned vs Host-backed.md`
|
||||
- `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `8. Stdlib Environment Packaging and Loading Specification.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- Reserved stdlib project spaces include `@sdk:*` and `@core:*`.
|
||||
- Stdlib interface modules are compile-time-only and loaded as PBS-like modules.
|
||||
- Stdlib interface modules may include service facades whose bodies delegate to reserved host owners; such bodies are source-surface ergonomics and not standalone runtime modules.
|
||||
- User code must import stdlib modules explicitly.
|
||||
- Canonical host identity comes from reserved host-binding metadata, not from source owner spelling.
|
||||
- VM-owned builtin type, builtin constant, and intrinsic surfaces may be exposed through reserved stdlib shells without transferring semantic ownership away from the VM.
|
||||
|
||||
## 6. Initial Section Targets
|
||||
|
||||
At minimum, the completed document should contain normative sections for:
|
||||
|
||||
1. stdlib contract boundaries,
|
||||
2. reserved stdlib project spaces and module families,
|
||||
3. normative versus non-normative API surfaces,
|
||||
4. VM-owned builtin shells exposed to user code,
|
||||
5. host-backed SDK surfaces exposed to user code,
|
||||
6. versioning and deprecation expectations for stdlib APIs.
|
||||
|
||||
## 7. TODO
|
||||
|
||||
The following items remain to be closed in future agenda discussion.
|
||||
|
||||
- Which stdlib modules are mandatory in each active stdlib line.
|
||||
- Which APIs are part of the normative core teaching surface versus optional library growth.
|
||||
- Whether `@core:*` is specified as language-adjacent utility surface or as ordinary stdlib contract.
|
||||
- How stdlib API evolution is documented and conformance-tested.
|
||||
- Whether some interface modules remain toolchain-private and outside user-facing stdlib surface.
|
||||
- Whether builtin shells may appear in `@sdk:*` as well as `@core:*`, or whether `@sdk:*` should remain host-facing only by policy.
|
||||
|
||||
## 8. Non-Goals
|
||||
|
||||
- Replacing the resolution/packaging specs.
|
||||
- Defining all future libraries in one pass.
|
||||
- Hardcoding one distribution format.
|
||||
|
||||
## 9. Exit Criteria
|
||||
|
||||
This document is ready to move beyond skeleton status only when:
|
||||
|
||||
1. the normative user-facing stdlib surface is explicitly bounded,
|
||||
2. reserved project-space API responsibilities are clear,
|
||||
3. VM-owned and host-backed stdlib surfaces are explicitly separated,
|
||||
4. stdlib versioning and deprecation expectations are aligned with compatibility policy,
|
||||
5. the document no longer relies on unresolved `TODO` items for ordinary v1 stdlib contract claims.
|
||||
|
||||
## 10. Reserved Project-Space Responsibilities
|
||||
|
||||
The current stdlib direction distinguishes two user-facing reserved spaces.
|
||||
|
||||
### 10.1 `@core:*`
|
||||
|
||||
`@core:*` is the preferred surface for VM-owned declarations that belong to the
|
||||
language-adjacent semantic platform.
|
||||
|
||||
Examples:
|
||||
|
||||
- builtin type shells,
|
||||
- builtin constants,
|
||||
- and other VM-owned helper declarations that are not host capability surfaces.
|
||||
|
||||
### 10.2 `@sdk:*`
|
||||
|
||||
`@sdk:*` is the preferred surface for host-backed capability-facing APIs.
|
||||
|
||||
Examples:
|
||||
|
||||
- `declare host` surfaces,
|
||||
- capability-facing wrappers over host services,
|
||||
- and domain SDK modules whose execution meaning ultimately depends on host-backed operations.
|
||||
|
||||
Rules:
|
||||
|
||||
- source packaging location is part of the stdlib contract surface,
|
||||
- but ownership remains governed by the VM-owned vs host-backed classification,
|
||||
- and placing a builtin shell in stdlib does not make it host-backed.
|
||||
|
||||
## 11. Builtin Shell Surfaces
|
||||
|
||||
Reserved stdlib modules may expose builtin declarations as compile-time-only
|
||||
shells.
|
||||
|
||||
Rules:
|
||||
|
||||
- stdlib builtin shells may expose `declare builtin type` declarations,
|
||||
- stdlib builtin shells may expose reserved `declare const` declarations carrying `BuiltinConst(...)`,
|
||||
- stdlib builtin shells may expose builtin methods carrying `IntrinsicCall(...)`,
|
||||
- these shells exist for import, name resolution, type checking, and lowering,
|
||||
- and these shells do not provide executable PBS bodies for builtin behavior.
|
||||
|
||||
Stdlib is therefore the delivery surface, not the semantic owner.
|
||||
|
||||
## 12. Host-backed SDK Surfaces
|
||||
|
||||
Reserved stdlib modules may expose host-backed declarations as compile-time-only
|
||||
shells.
|
||||
|
||||
Rules:
|
||||
|
||||
- host-backed stdlib surfaces use `declare host`,
|
||||
- host-backed stdlib modules may also expose `declare service` facades that call internal non-public host owners,
|
||||
- host-backed method signatures carry `Host(...)`,
|
||||
- internal low-level host owners can remain non-public via `mod` barrel visibility while higher-level services are exported with `pub`,
|
||||
- user code may import those host owners through ordinary stdlib module imports,
|
||||
- and lowering continues through canonical host identity, `SYSC`, `HOSTCALL`, loader resolution, and final `SYSCALL`.
|
||||
|
||||
## 13. Stdlib Contract Expectations for Builtin MVP
|
||||
|
||||
For the current builtin MVP, stdlib should be able to expose at least:
|
||||
|
||||
1. a builtin type shell for `Color`,
|
||||
2. a builtin type shell for `Vec2`,
|
||||
3. a builtin type shell for `Pixel`,
|
||||
4. a builtin constant shell for `vec2.zero`,
|
||||
5. and any associated documentation-level or teaching-level module organization needed to make those surfaces discoverable.
|
||||
|
||||
Illustrative example:
|
||||
|
||||
```pbs
|
||||
import { Vec2, ZERO } from @core:math;
|
||||
```
|
||||
|
||||
The imported names are source-visible conveniences.
|
||||
Their canonical runtime-facing identities still come from builtin metadata such
|
||||
as `BuiltinType(name="vec2", version=1)` and
|
||||
`BuiltinConst(target="vec2", name="zero", version=1)`.
|
||||
|
||||
## 14. Deterministic Stdlib Surface Failures
|
||||
|
||||
At minimum, a conforming implementation must reject:
|
||||
|
||||
1. a stdlib builtin shell that attempts to use host-binding metadata for VM-owned intrinsic behavior,
|
||||
2. a stdlib host shell that attempts to use builtin metadata in place of host-binding metadata,
|
||||
3. a user-facing stdlib module that exports executable PBS bodies for builtin semantics,
|
||||
4. a stdlib line that exposes conflicting canonical builtin identities through the same resolved environment,
|
||||
5. a stdlib line that exposes conflicting canonical host identities through the same resolved environment.
|
||||
@@ -0,0 +1,135 @@
|
||||
# PBS Verification and Safety Checks Specification
|
||||
|
||||
Status: Draft v1 (Quality-Gate Baseline)
|
||||
Applies to: test-backed safety gates for backend compiler stages and integration regression safety checks against runtime
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the minimum safety/verification quality gates that must be enforced for executable backend pipelines.
|
||||
|
||||
Its purpose is to keep safety measurable and deterministic across:
|
||||
|
||||
- lowering,
|
||||
- optimization,
|
||||
- emission,
|
||||
- and runtime integration boundaries.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- mandatory compiler-stage safety checks for executable pipeline stages,
|
||||
- conditional integration safety regression checks against runtime line,
|
||||
- and evidence requirements for safety-related support claims.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- full runtime verifier algorithm internals,
|
||||
- formal proof of all runtime safety properties,
|
||||
- or one mandatory verifier/optimizer architecture.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `docs/pbs/specs/2. Governance and Versioning.md`
|
||||
2. `docs/pbs/specs/12. Diagnostics Specification.md`
|
||||
3. `20. IRBackend to IRVM Lowering Specification.md`
|
||||
4. `21. IRVM Optimization Pipeline Specification.md`
|
||||
5. `15. Bytecode and PBX Mapping Specification.md`
|
||||
6. `13. Conformance Test Specification.md`
|
||||
7. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on:
|
||||
|
||||
- `docs/pbs/specs/12. Diagnostics Specification.md`
|
||||
- `13. Conformance Test Specification.md`
|
||||
- `15. Bytecode and PBX Mapping Specification.md`
|
||||
- `20. IRBackend to IRVM Lowering Specification.md`
|
||||
- `21. IRVM Optimization Pipeline Specification.md`
|
||||
|
||||
## 5. Safety Gate Model
|
||||
|
||||
### 5.1 Gate S-U: Compiler-Stage Safety Unit Tests (Required)
|
||||
|
||||
For executable pipelines, S-U must cover stage-level safety checks at minimum:
|
||||
|
||||
1. `LowerToVM` safety checks:
|
||||
- deterministic control-flow lowering checks,
|
||||
- deterministic function-id assignment checks,
|
||||
- mandatory slot/return shape checks,
|
||||
- mandatory callsite form checks.
|
||||
2. `OptimizeIRVM` safety checks:
|
||||
- semantic-preservation regression checks,
|
||||
- deterministic output checks for same input graph,
|
||||
- profile-compatibility checks (`vm_profile`).
|
||||
3. `EmitBytecode` safety checks:
|
||||
- deterministic function/code layout checks,
|
||||
- host-backed pre-load form checks (`HOSTCALL`, `SYSC`),
|
||||
- deterministic rejection for malformed emission candidates,
|
||||
- minimum debug-attribution output checks.
|
||||
4. deterministic diagnostics identity for required rejection surfaces (`code`, `severity`, primary attribution when applicable).
|
||||
|
||||
This gate is mandatory regardless of backend maturity stage.
|
||||
|
||||
### 5.2 Gate S-I: Integration Safety Regression With Runtime (Required for Executable Backends)
|
||||
|
||||
For backends that emit executable artifacts, S-I must cover integration safety at minimum:
|
||||
|
||||
1. valid pre-load host path that loader patches and runtime executes,
|
||||
2. rejection of out-of-bounds `HOSTCALL` index,
|
||||
3. rejection of unused `SYSC` declarations,
|
||||
4. rejection of raw `SYSCALL` in pre-load artifact,
|
||||
5. rejection of host ABI mismatch (`arg_slots`/`ret_slots`),
|
||||
6. rejection of missing capability at load-time,
|
||||
7. valid VM-owned intrinsic path,
|
||||
8. repeatability across declared runtime line.
|
||||
|
||||
When executable artifact emission is not present, S-I may be explicitly `deferred`.
|
||||
|
||||
## 6. Evidence Requirements
|
||||
|
||||
Safety claims must map to gate evidence:
|
||||
|
||||
1. S-U evidence is required for baseline safety posture,
|
||||
2. S-I evidence is required for integration-ready safety claims,
|
||||
3. and published safety-related support claims must remain evidence-backed and current.
|
||||
|
||||
For executable backends, evidence should include deterministic regression fixtures that prove pipeline order and stage-boundary safety behavior.
|
||||
|
||||
## 7. Deterministic Failure Taxonomy Expectations
|
||||
|
||||
Backend safety checks should expose stable rejection families at minimum:
|
||||
|
||||
1. `MARSHAL_FORMAT_*`,
|
||||
2. `MARSHAL_LINKAGE_*`,
|
||||
3. `MARSHAL_VERIFY_PRECHECK_*`.
|
||||
|
||||
This taxonomy complements existing diagnostics contracts and does not replace runtime loader/verifier error surfaces.
|
||||
|
||||
## 8. Explicit Deferrals
|
||||
|
||||
The following are intentionally deferred:
|
||||
|
||||
- full formal verifier obligation catalog,
|
||||
- formal proof frameworks for optimizer equivalence,
|
||||
- and richer standardized source-map formats beyond v1 minimum hooks.
|
||||
|
||||
## 9. Non-Goals
|
||||
|
||||
- Replacing runtime or bytecode authority.
|
||||
- Freezing optimizer/verifier internal architecture prematurely.
|
||||
- Defining performance tooling in a safety specification.
|
||||
|
||||
## 10. Exit Criteria
|
||||
|
||||
This document is healthy when:
|
||||
|
||||
1. required stage-level safety checks are test-backed,
|
||||
2. executable backends have explicit S-I status (`pass`/`fail`/`deferred`),
|
||||
3. integration safety regressions are preserved in tests,
|
||||
4. and safety-related support claims remain evidence-backed.
|
||||
@@ -0,0 +1,174 @@
|
||||
# PBS IRBackend to IRVM Lowering Specification
|
||||
|
||||
Status: Draft v1 (Backend Baseline)
|
||||
Applies to: executable-backend lowering from `IRBackend` handoff into `IRVM`
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the normative lowering contract from executable `IRBackend` to `IRVM`.
|
||||
|
||||
Its purpose is to make backend lowering deterministic, reviewable, and compatible with runtime ISA/verification authority.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- required backend preconditions before `IRBackend -> IRVM` starts,
|
||||
- `IRVM` structural obligations needed before optimization/emission,
|
||||
- deterministic function-id assignment and control-flow lowering obligations,
|
||||
- callsite lowering obligations across function, host-backed, and VM-owned intrinsic paths,
|
||||
- mandatory compiler-side structural pre-verification before bytecode emission,
|
||||
- and deterministic rejection obligations for backend-originated failures.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- binary PBX layout details,
|
||||
- loader patching internals,
|
||||
- runtime execution internals,
|
||||
- or one mandatory optimizer implementation.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
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`)
|
||||
3. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
|
||||
4. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on:
|
||||
|
||||
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
|
||||
- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `15. Bytecode and PBX Mapping Specification.md`
|
||||
- `21. IRVM Optimization Pipeline Specification.md`
|
||||
|
||||
## 5. Backend Entry Preconditions
|
||||
|
||||
Lowering from `IRBackend` to `IRVM` may start only when:
|
||||
|
||||
1. frontend admission to `IRBackend` is complete for the active slice,
|
||||
2. required callsite categories (`CALL_FUNC`/`CALL_HOST`/`CALL_INTRINSIC`) are available,
|
||||
3. required canonical host/intrinsic metadata is available for admitted callsites,
|
||||
4. dependency-scoped fail-fast exclusions have already been applied at the `IRBackend` boundary,
|
||||
5. frontend-declared qualified `EntrypointRef` is present:
|
||||
- `IRBackend.entryPointCallableName` is non-blank,
|
||||
- `IRBackend.entryPointModuleId` is non-none,
|
||||
6. and target `vm_profile` is selected deterministically.
|
||||
|
||||
## 6. IRVM Model Obligations
|
||||
|
||||
`IRVM` v1 is a quasi-ISA backend form:
|
||||
|
||||
1. it may contain Core ISA ops and internal extension ops (`IRVM_EXT`),
|
||||
2. each `IRVM_EXT` must declare structural metadata equivalent to opcode-spec needs:
|
||||
- `pops`,
|
||||
- `pushes`,
|
||||
- `is_branch`,
|
||||
- `is_terminator`,
|
||||
3. and `IRVM_EXT` must be eliminable before bytecode emission.
|
||||
|
||||
`IRVM` must preserve, per function:
|
||||
|
||||
1. `param_slots`,
|
||||
2. `local_slots`,
|
||||
3. `return_slots`,
|
||||
4. `max_stack_slots`,
|
||||
5. function entry mapping and deterministic identity.
|
||||
|
||||
## 7. Control-Flow Lowering Obligations
|
||||
|
||||
Control-flow lowering must satisfy:
|
||||
|
||||
1. symbolic labels are allowed internally in lowering,
|
||||
2. final jump immediates must be resolved to `u32` offsets relative to function start before emission,
|
||||
3. jump targets must be instruction-boundary-valid within function ranges,
|
||||
4. and reachable fallthrough beyond function end without terminator is rejected.
|
||||
|
||||
## 8. Deterministic Function-ID Assignment
|
||||
|
||||
Function indexing must be deterministic:
|
||||
|
||||
1. entrypoint callable is selected by exact qualified match against `EntrypointRef(entryPointModuleId, entryPointCallableName)`,
|
||||
2. selected entrypoint function id is `0`,
|
||||
3. remaining functions are ordered by `(moduleId -> modulePool canonical key, callable_name, source_start)`,
|
||||
4. name-only entrypoint fallback is forbidden,
|
||||
5. and identical admitted input graphs must produce identical function-id assignments.
|
||||
|
||||
## 9. Callsite Lowering Obligations
|
||||
|
||||
### 9.1 Function calls
|
||||
|
||||
`CALL_FUNC` lowers to `CALL <func_id>` with valid index and arity-consistent signature contracts.
|
||||
|
||||
### 9.2 Host-backed calls
|
||||
|
||||
`CALL_HOST` lowers to pre-load `HOSTCALL <sysc_index>`, not raw `SYSCALL`.
|
||||
|
||||
### 9.3 VM-owned intrinsic calls
|
||||
|
||||
`CALL_INTRINSIC` lowers to VM-owned intrinsic path and must remain distinct from host-binding paths.
|
||||
|
||||
Final intrinsic id resolution rules:
|
||||
|
||||
1. compiler must resolve final intrinsic ids from the canonical ISA-scoped intrinsic registry artifact,
|
||||
2. compiler-local hardcoded maps or runtime-source parsing must not be authoritative identity sources,
|
||||
3. runtime and compiler consumers must validate parity against the same canonical artifact in strict CI mode.
|
||||
|
||||
### 9.4 Closure and coroutine constraints (v1)
|
||||
|
||||
1. closure calls with unknown static callee are rejected in v1,
|
||||
2. `SPAWN` and `YIELD` are outside the executable `core-v1` claim scope and MUST be rejected as unsupported forms in v1 backend admission,
|
||||
3. `SPAWN` argument-count and `YIELD` stack-shape invariants remain reserved for a future profile that explicitly admits these opcodes,
|
||||
4. and any profile that admits `SPAWN`/`YIELD` MUST publish dedicated conformance evidence before claiming support.
|
||||
|
||||
## 10. Mandatory Compiler-Side Pre-Verification
|
||||
|
||||
Before bytecode emission, backend must run structural pre-verification on lowered `IRVM` (after resolving to Core-ISA-compatible form), covering at minimum:
|
||||
|
||||
1. jump target validity,
|
||||
2. stack-depth join consistency,
|
||||
3. underflow/overflow against declared limits,
|
||||
4. return-shape consistency,
|
||||
5. function-id validity,
|
||||
6. callsite arity consistency,
|
||||
7. and structural validity of host/intrinsic call forms.
|
||||
|
||||
This pre-verification does not replace runtime verifier authority.
|
||||
|
||||
## 11. Deterministic Rejection Policy
|
||||
|
||||
When backend lowering fails at this boundary:
|
||||
|
||||
1. rejection must be deterministic,
|
||||
2. diagnostics identity and phase must remain stable,
|
||||
3. and source attribution must be preserved whenever the failure remains source-attributable and user-actionable.
|
||||
|
||||
## 12. Explicit Deferrals
|
||||
|
||||
The following are intentionally deferred:
|
||||
|
||||
- optimizer pass catalog and tuning policy,
|
||||
- richer internal IR analysis models beyond v1 obligations,
|
||||
- advanced closure/lifetime optimizations beyond v1 constraints,
|
||||
- and executable support for `SPAWN`/`YIELD` in `core-v1`.
|
||||
|
||||
## 13. Non-Goals
|
||||
|
||||
- Defining one in-memory IR implementation graph.
|
||||
- Redefining runtime verifier/loader internals.
|
||||
- Defining PBX binary chunk policy in this document.
|
||||
|
||||
## 14. Exit Criteria
|
||||
|
||||
This document is healthy when:
|
||||
|
||||
1. `IRBackend -> IRVM` obligations are explicit and testable,
|
||||
2. deterministic function/call/control-flow lowering rules are explicit,
|
||||
3. mandatory pre-verification boundary is explicit,
|
||||
4. and scope boundaries with optimization/emission specs are explicit.
|
||||
@@ -0,0 +1,124 @@
|
||||
# PBS IRVM Optimization Pipeline Specification
|
||||
|
||||
Status: Draft v1 (Pipeline Baseline)
|
||||
Applies to: placement and invariants of the `OptimizeIRVM` stage between lowering and bytecode emission
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the normative placement and safety invariants of the `OptimizeIRVM` stage.
|
||||
|
||||
Its purpose is to allow optimization in the backend pipeline without transferring semantic optimization responsibility to runtime.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- canonical stage placement for `OptimizeIRVM`,
|
||||
- input/output contracts of optimization stage boundaries,
|
||||
- semantic-preservation invariants for optimization passes,
|
||||
- profile-compatibility obligations (`vm_profile`) across optimization and emission,
|
||||
- and minimum validation expectations for optimization-stage regressions.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- a mandatory list of optimization passes,
|
||||
- pass scheduling heuristics,
|
||||
- or runtime dynamic optimization/JIT policies.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
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`)
|
||||
3. `20. IRBackend to IRVM Lowering Specification.md`
|
||||
4. `15. Bytecode and PBX Mapping Specification.md`
|
||||
5. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on:
|
||||
|
||||
- `20. IRBackend to IRVM Lowering Specification.md`
|
||||
- `15. Bytecode and PBX Mapping Specification.md`
|
||||
- `19. Verification and Safety Checks Specification.md`
|
||||
- `docs/pbs/decisions/IRVM Optimization Stage Placement Decision.md`
|
||||
|
||||
## 5. Canonical Backend Pipeline Order
|
||||
|
||||
For executable backends, the canonical order is:
|
||||
|
||||
1. `LowerToVM`: `IRBackend -> IRVM`,
|
||||
2. `OptimizeIRVM`: `IRVM -> IRVM` optimized,
|
||||
3. `EmitBytecode`: optimized `IRVM -> BytecodeModule` pre-load artifact.
|
||||
|
||||
`OptimizeIRVM` must not be skipped in a pipeline that claims this profile unless explicitly configured as a no-op stage that still preserves contracts.
|
||||
|
||||
## 6. Input and Output Contracts
|
||||
|
||||
### 6.1 Input contract
|
||||
|
||||
`OptimizeIRVM` input must:
|
||||
|
||||
1. satisfy lowering obligations from `20`,
|
||||
2. carry selected `vm_profile`,
|
||||
3. and remain structurally valid for optimizer analyses.
|
||||
|
||||
### 6.2 Output contract
|
||||
|
||||
`OptimizeIRVM` output must:
|
||||
|
||||
1. be semantically equivalent to input under the selected `vm_profile`,
|
||||
2. preserve callable/slot/return contracts,
|
||||
3. preserve deterministic mapping behavior required by emission,
|
||||
4. and be valid for bytecode emission and subsequent runtime verification.
|
||||
|
||||
## 7. Optimization Invariants
|
||||
|
||||
Optimization passes must satisfy all of:
|
||||
|
||||
1. semantic preservation of observable program behavior,
|
||||
2. determinism for the same admitted input graph and selected profile,
|
||||
3. profile compatibility (no introduction of out-of-profile executable opcode forms),
|
||||
4. preservation of host-backed vs VM-owned call-boundary classification,
|
||||
5. and preservation of diagnostics/source-attribution hooks required at v1 minimum.
|
||||
|
||||
## 8. Runtime Responsibility Boundary
|
||||
|
||||
1. Semantic/structural program optimization belongs to compile-time backend stages.
|
||||
2. Runtime remains responsible for load, patch, verify, and execute responsibilities.
|
||||
3. Runtime-internal micro-optimizations are allowed only when they do not alter bytecode-observable semantics or contract behavior.
|
||||
|
||||
## 9. Validation Expectations
|
||||
|
||||
At minimum, optimization-stage validation must include:
|
||||
|
||||
1. equivalence-oriented regression fixtures across optimized vs non-optimized pipeline outputs,
|
||||
2. preservation of known negative loader/verifier rejection behavior,
|
||||
3. and deterministic reproduction of artifact-level invariants required by `15`.
|
||||
|
||||
## 10. Explicit Deferrals
|
||||
|
||||
The following are intentionally deferred:
|
||||
|
||||
- target-specific optimization profitability models,
|
||||
- advanced interprocedural pipelines beyond v1 baseline,
|
||||
- and formal equivalence proof frameworks.
|
||||
|
||||
## 11. Non-Goals
|
||||
|
||||
- Defining runtime JIT or adaptive execution.
|
||||
- Replacing loader/verifier contracts.
|
||||
- Mandating one optimizer architecture or pass framework.
|
||||
|
||||
## 12. Exit Criteria
|
||||
|
||||
This document is healthy when:
|
||||
|
||||
1. stage placement is explicit and implemented in pipeline order,
|
||||
2. optimization invariants are explicit and test-backed,
|
||||
3. backend/runtime responsibility boundary is explicit,
|
||||
4. and integration safety evidence references this stage concretely.
|
||||
|
||||
@@ -0,0 +1,113 @@
|
||||
# Backend Spec-to-Test Conformance Matrix
|
||||
|
||||
Status: Draft v1 (Traceability Baseline)
|
||||
Applies to: backend conformance traceability for `IRBackend -> IRVM -> OptimizeIRVM -> EmitBytecode`
|
||||
|
||||
Last Updated: 2026-03-09
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This matrix maps each normative backend MUST from:
|
||||
|
||||
1. `docs/general/specs/19. Verification and Safety Checks Specification.md`
|
||||
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
|
||||
3. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md`
|
||||
4. `docs/pbs/specs/13. Lowering IRBackend Specification.md` (Section 12 addendum only)
|
||||
|
||||
to concrete positive/negative test evidence and current status.
|
||||
|
||||
## 2. Status Legend
|
||||
|
||||
- `pass`: requirement has explicit positive and/or negative evidence and currently passes.
|
||||
- `partial`: requirement is partially covered; evidence exists but scope is incomplete.
|
||||
- `missing`: no concrete automated evidence yet.
|
||||
- `deferred`: intentionally out of current executable scope.
|
||||
|
||||
## 3. Normative Matrix
|
||||
|
||||
| Requirement ID | Source MUST | Positive Tests | Negative Tests | Status | Notes |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| G19-5.1.1 | Gate S-U MUST cover LowerToVM stage safety checks. | `LowerToIRVMServiceTest#lowerMustAssignEntrypointIdZeroAndSortRemainingDeterministically`; `LowerToIRVMServiceTest#lowerMustResolveJumpTargetsFromLabels` | `LowerToIRVMServiceTest#lowerMustRejectMissingCallee`; `LowerToIRVMServiceTest#lowerMustRejectMissingJumpTargetLabel`; `LowerToIRVMServiceTest#lowerMustRejectUnterminatedFunction` | pass | Includes deterministic id/callsite/control-flow checks. |
|
||||
| G19-5.1.2 | Gate S-U MUST cover OptimizeIRVM stage safety checks. | `OptimizeIRVMServiceTest#optimizeDefaultPassesMustRemoveUnreachableInstructions`; `OptimizeIRVMServiceTest#simplifyJumpToNextPcPassMustRemoveDirectFallthroughJump` | `OptimizeIRVMServiceTest#optimizeMustRejectPassThatMutatesVmProfile` | pass | Determinism also covered by `BackendSafetyGateSUTest#optimizeStageMustBeDeterministicForSameInputProgram`. |
|
||||
| G19-5.1.3 | Gate S-U MUST cover EmitBytecode stage safety checks. | `EmitBytecodePipelineStageTest#runMustEmitBytecodeWhenPreconditionsAreSatisfied`; `BytecodeEmitterTest#emitMustDeduplicateSyscallsByCanonicalIdentityAndPreserveFirstOccurrenceOrder` | `EmitBytecodePipelineStageTest#runMustFailWhenInternalOpcodesRemain`; `BytecodeEmitterTest#emitMustRejectRawSyscallInPreloadPlan` | pass | Covers layout, host-backed preload form and deterministic rejection. |
|
||||
| G19-5.1.4 | Gate S-U MUST cover deterministic diagnostics identity for required rejection surfaces. | `BackendSafetyGateSUTest#lowerStageMustExposeDeterministicFailureCodeForSameInvalidInput` | `BackendSafetyGateSUTest#emitStageMustExposeMarshalingLinkageFailureDeterministically` | pass | Uses stable `code` and `phase`. |
|
||||
| G19-5.2.1 | Gate S-I MUST cover valid pre-load host path. | `BackendGateIIntegrationTest#gateI_validHostcallPath` | N/A | pass | Runtime-backed and local adapter paths covered. |
|
||||
| G19-5.2.2 | Gate S-I MUST reject out-of-bounds HOSTCALL index. | N/A | `BackendGateIIntegrationTest#gateI_rejectHostcallOutOfBounds` | pass | |
|
||||
| G19-5.2.3 | Gate S-I MUST reject unused SYSC declarations. | N/A | `BackendGateIIntegrationTest#gateI_rejectUnusedSyscallDeclaration` | pass | |
|
||||
| G19-5.2.4 | Gate S-I MUST reject raw SYSCALL in pre-load artifact. | N/A | `BackendGateIIntegrationTest#gateI_rejectRawSyscallInPreloadArtifact` | pass | |
|
||||
| G19-5.2.5 | Gate S-I MUST reject host ABI mismatch. | N/A | `BackendGateIIntegrationTest#gateI_rejectHostAbiMismatchAtEmitTime` | pass | |
|
||||
| G19-5.2.6 | Gate S-I MUST reject missing capability at load-time. | N/A | `BackendGateIIntegrationTest#gateI_rejectMissingCapability` | pass | |
|
||||
| G19-5.2.7 | Gate S-I MUST cover valid VM-owned intrinsic path. | `BackendGateIIntegrationTest#gateI_validIntrinsicPath` | N/A | pass | |
|
||||
| G19-5.2.8 | Gate S-I MUST cover repeatability across runtime line. | `RuntimeBackedCompatibilityAdapterTest#checkMustPassInStrictModeWhenRuntimeCommandIsValid`; `RuntimeBackedCompatibilityAdapterTest#checkMustBeRepeatableAcrossDeclaredRuntimeLinesInStrictMode` | `RuntimeBackedCompatibilityAdapterTest#checkMustFailInStrictModeWhenRuntimeCommandIsUnavailable` | pass | Multi-line repeatability is asserted with strict runtime-backed checks over distinct declared runtime lines. |
|
||||
| G20-6.2 | `IRVM_EXT` MUST declare structural metadata (`pops/pushes/is_branch/is_terminator`). | `IRVMValidatorTest#validateMustApplyStructuralMetadataForCustomInternalExtension`; `IRVMValidatorTest#validateMustRejectCustomInternalExtensionWhenStructuralMetadataUnderflowsStack`; `IRVMOp` record contract (`pops/pushes/branch/terminator/internal`) | N/A | pass | Dedicated extension fixtures now assert structural metadata is consumed by validation behavior. |
|
||||
| G20-6.3 | `IRVM_EXT` MUST be eliminable before bytecode emission. | `OptimizeIRVMServiceTest#optimizeDefaultPassesMustEliminateUnreachableInternalExtensionBeforeEmission` | `EmitBytecodePipelineStageTest#runMustFailWhenInternalOpcodesRemain`; `EmitBytecodePipelineStageTest#runMustFailWhenInternalOpcodesRemainEvenWithNonEmptyEmissionPlan`; `IRVMValidatorTest#validateMustRejectInternalOpcodeWhenConfigured` | pass | Optimizer elimination path and emit-stage hard rejection path are both covered. |
|
||||
| G20-6.4 | IRVM MUST preserve per-function slot and identity headers. | `IRVMProgramTest#constructorMustRejectModuleAndEmissionPlanMismatch` | `IRVMProgramTest#constructorMustRejectModuleAndEmissionPlanMismatch` | pass | Header mismatch is rejected deterministically. |
|
||||
| G20-7.2 | Jump immediates MUST resolve to u32 function-relative offsets before emission. | `LowerToIRVMServiceTest#lowerMustResolveJumpTargetsFromLabels`; `BytecodeEmitterTest#emitMustEncodeJumpOpcodesWithU32Immediate` | `LowerToIRVMServiceTest#lowerMustRejectMissingJumpTargetLabel` | pass | |
|
||||
| G20-7.3 | Jump targets MUST be instruction-boundary valid. | N/A | `IRVMValidatorTest#validateMustRejectInvalidJumpTarget` | pass | |
|
||||
| G20-7.4 | Reachable fallthrough beyond function end MUST be rejected. | N/A | `LowerToIRVMServiceTest#lowerMustRejectUnterminatedFunction`; `IRVMValidatorTest#validateMustRejectRetShapeMismatch` | pass | |
|
||||
| G20-8.1 | Qualified entrypoint function id MUST be 0. | `LowerToIRVMServiceTest#lowerMustAssignEntrypointIdZeroAndSortRemainingDeterministically`; `LowerToIRVMServiceTest#lowerMustUseQualifiedEntrypointIdentityWhenProvided` | `LowerToIRVMServiceTest#lowerMustRejectWhenEntrypointDeclarationIsMissing`; `LowerToIRVMServiceTest#lowerMustRejectMissingQualifiedEntrypointIdentity`; `LowerToIRVMServiceTest#lowerMustRejectWhenEntrypointIsAmbiguous` | pass | Entrypoint is resolved strictly by `EntrypointRef(entryPointModuleId, entryPointCallableName)`. |
|
||||
| G20-8.2 | Remaining function ids MUST follow deterministic moduleId-only ordering. | `LowerToIRVMServiceTest#lowerMustAssignEntrypointIdZeroAndSortRemainingDeterministically`; `LowerToIRVMServiceTest#lowerMustUseModulePoolCanonicalIdentityForNonEntrypointOrdering` | N/A | pass | Ordering key is `(moduleId -> modulePool canonical key, callable_name, source_start)`. |
|
||||
| G20-8.3 | Same admitted input graph MUST produce identical function-id assignment. | `BackendSafetyGateSUTest#fullPipelineMustProduceDeterministicBytecodeForSameInput` | N/A | pass | Artifact determinism implies stable function mapping for fixed input. |
|
||||
| G20-9.3 | `CALL_INTRINSIC` MUST remain distinct from host-binding path and resolve ids from canonical registry artifact. | `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites`; `BackendGateIIntegrationTest#gateI_validIntrinsicPath`; `IRVMIntrinsicRegistryParityTest#registryResourceMustExposeExpectedCanonicalEntries`; `IRVMIntrinsicRegistryParityTest#registryMustStayInSyncWithRuntimeBuiltinsTable` | `IRVMValidatorTest#validateProgramMustRejectIntrinsicWithoutSignatureMetadata` | pass | Distinct operation kinds and canonical registry parity checks are enforced. |
|
||||
| G20-9.4.2 | `SPAWN` arg count MUST match callee `param_slots`. | `BackendClaimScopeSpecTest#loweringSpecMustDeclareSpawnYieldOutsideCoreV1ClaimScope`; `BackendClaimScopeSpecTest#matrixMustMarkSpawnYieldRowsAsClaimRescoped`; `BackendClaimScopeSpecTest#decisionRecordMustExistForSpawnYieldClaimRescope` | N/A | pass | Requirement is out of scope for core-v1 claim by accepted Track B rescope decision; future profile must reintroduce executable coverage with dedicated tests. |
|
||||
| G20-9.4.3 | `YIELD` with non-empty operand stack MUST be rejected. | `BackendClaimScopeSpecTest#loweringSpecMustDeclareSpawnYieldOutsideCoreV1ClaimScope`; `BackendClaimScopeSpecTest#matrixMustMarkSpawnYieldRowsAsClaimRescoped`; `BackendClaimScopeSpecTest#decisionRecordMustExistForSpawnYieldClaimRescope` | N/A | pass | Requirement is out of scope for core-v1 claim by accepted Track B rescope decision; future profile must reintroduce executable coverage with dedicated tests. |
|
||||
| G20-10 | Backend MUST run structural pre-verification before emission. | `LowerToIRVMService` + `OptimizeIRVMService` validator invocation; `LowerToIRVMServiceTest` positive fixtures | `IRVMValidatorTest#validateMustRejectStackMismatchJoin`; `IRVMValidatorTest#validateProgramMustApplyHostcallStackEffectsFromMetadata` | pass | Pre-verification checks jump/stack/ret/callsite constraints. |
|
||||
| G20-11.1 | Lowering rejection MUST be deterministic. | `BackendSafetyGateSUTest#lowerStageMustExposeDeterministicFailureCodeForSameInvalidInput` | same | pass | |
|
||||
| G20-11.2 | Diagnostics identity/phase MUST remain stable. | `BackendSafetyGateSUTest#lowerStageMustExposeDeterministicFailureCodeForSameInvalidInput` | `BackendSafetyGateSUTest#emitStageMustExposeMarshalingLinkageFailureDeterministically` | pass | Stable rejection families are exercised. |
|
||||
| G20-11.3 | Source attribution MUST be preserved when source-actionable. | `LowerToIRVMPipelineStageTest#runMustAttachSourceAttributionForLoweringFailure`; `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites` | `LowerToIRVMServiceTest#lowerMustRejectMissingCallee` | pass | Stage-level failure now carries explicit `file/start/end` attribution for lowering errors. |
|
||||
| G21-5 | `OptimizeIRVM` MUST NOT be skipped in canonical pipeline order. | `BuilderPipelineServiceOrderTest#canonicalOrderMustContainOptimizeBetweenLowerAndEmit` | N/A | pass | Canonical stage order is enforced. |
|
||||
| G21-6.1 | Optimize input MUST satisfy lowering obligations/profile/structural validity. | `OptimizeIRVMPipelineStageTest#runMustAcceptSupportedNonDefaultVmProfile` | `OptimizeIRVMPipelineStageTest#runMustRejectUnsupportedVmProfile` | pass | Input validation occurs before pass execution. |
|
||||
| G21-6.2 | Optimize output MUST preserve semantics/contracts and remain emission-valid. | `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForLoweredHostIntrinsicFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForConditionalJoinFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForSimpleLoopFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForLinearCallFixture`; `EmitBytecodePipelineStageTest#runMustEmitBytecodeWhenPreconditionsAreSatisfied` | `OptimizeIRVMServiceTest#optimizeMustRejectPassThatMutatesVmProfile` | pass | Equivalence harness now validates on/off semantics and emission validity over CFG corpus with host/intrinsic paths. |
|
||||
| G21-7.1 | Optimization passes MUST preserve observable semantics. | `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForConditionalJoinFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForSimpleLoopFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForLinearCallFixture` | N/A | pass | Observable trace equivalence is asserted across branching, loops, and call graphs. |
|
||||
| G21-7.2 | Optimization passes MUST be deterministic for same input/profile. | `BackendSafetyGateSUTest#optimizeStageMustBeDeterministicForSameInputProgram` | N/A | pass | |
|
||||
| G21-7.3 | Optimization passes MUST preserve profile compatibility. | `OptimizeIRVMPipelineStageTest#runMustAcceptSupportedNonDefaultVmProfile` | `OptimizeIRVMServiceTest#optimizeMustRejectPassThatMutatesVmProfile` | pass | |
|
||||
| G21-7.4 | Optimization passes MUST preserve host-vs-intrinsic boundary classification. | `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites`; `BackendGateIIntegrationTest#gateI_validIntrinsicPath` | N/A | pass | No pass rewrites operation kind domains. |
|
||||
| G21-7.5 | Optimization passes MUST preserve diagnostics/source-attribution hooks. | `OptimizeIRVMServiceTest#unreachableInstructionEliminationPassMustPreserveJumpSpanWhenTargetIsRemapped`; `OptimizeIRVMServiceTest#normalizeRedundantJumpTargetsPassMustPreserveJumpSpanAfterRewrite`; `OptimizeIRVMServiceTest#simplifyJumpToNextPcPassMustPreserveSpanOnSurvivingOperation`; `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites` | N/A | pass | Dedicated optimizer regressions now assert span/source-hook preservation for rewrite and elimination paths. |
|
||||
| G21-9.1 | Validation MUST include optimized-vs-non-optimized equivalence fixtures. | `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForLoweredHostIntrinsicFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForConditionalJoinFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForSimpleLoopFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForLinearCallFixture` | N/A | pass | Dedicated opt on/off harness with reusable interpreter and deterministic trace assertions is in place. |
|
||||
| G21-9.2 | Validation MUST preserve known negative loader/verifier behavior. | `BackendSafetyGateSUTest#emitStageMustExposeMarshalingLinkageFailureDeterministically`; `BackendGateIIntegrationTest` rejection suite | N/A | pass | |
|
||||
| G21-9.3 | Validation MUST preserve deterministic artifact-level invariants. | `BackendSafetyGateSUTest#fullPipelineMustProduceDeterministicBytecodeForSameInput`; `BytecodeEmitterTest#emitMustRemainDeterministicAfterInterning` | N/A | pass | |
|
||||
| PBS13-12.0 | Executable backend handoff MUST satisfy addendum obligations. | `IRBackendExecutableContractTest` suite | N/A | pass | Row group `PBS13-12.x` details each obligation. |
|
||||
| PBS13-12.1.1 | Callable identity MUST be preserved at handoff. | `IRBackendExecutableContractTest#aggregatorMustPreserveExecutableFunctionOrderDeterministically` | N/A | pass | |
|
||||
| PBS13-12.1.2 | Observable callable signature MUST be preserved at handoff. | `IRBackendExecutableContractTest#functionContractMustRejectInvalidSlotAndSpanBounds` | N/A | pass | |
|
||||
| PBS13-12.1.3 | Callable category MUST be preserved at handoff. | `PbsFrontendCompilerTest#shouldLowerExecutableFunctionsWithCallsiteCategories` | N/A | pass | |
|
||||
| PBS13-12.1.4 | Source anchor (`fileId/start/end`) MUST be preserved. | `IRBackendExecutableContractTest#aggregatorMustPreserveExecutableSourceAttribution`; `IRBackendExecutableContractTest#functionContractMustRejectInvalidSlotAndSpanBounds` | N/A | pass | Handoff preserves function and instruction source anchors after aggregation/reindexing. |
|
||||
| PBS13-12.1.5 | Executable body representation MUST be backend-lowerable. | `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites` | `LowerToIRVMServiceTest#lowerMustRejectMissingCallee` | pass | |
|
||||
| PBS13-12.2.1 | Callsite MUST be exactly one of `CALL_FUNC/CALL_HOST/CALL_INTRINSIC`. | `IRBackendExecutableContractTest#callInstructionMustRequireCategorySpecificMetadata` | `IRBackendExecutableContractTest#instructionContractMustRejectMixedMetadataKinds` | pass | |
|
||||
| PBS13-12.2.2 | Backend MUST NOT infer callsite category by textual heuristics. | `PbsFrontendCompilerTest#shouldClassifyCallableCallEvenWhenNameLooksHostLike`; `PbsFrontendCompilerTest#shouldNotInferCallableCategoryFromMemberCallText`; `PbsFrontendCompilerTest#shouldRejectAmbiguousCallableIdentityInsteadOfGuessingByText`; `IRBackendExecutableContractTest#callInstructionMustRequireCategorySpecificMetadata` | N/A | pass | Dedicated regression fixtures now cover textually misleading names and ambiguous callable identity without category guessing. |
|
||||
| PBS13-12.3.1 | Host-backed callsite MUST preserve canonical `(module,name,version)`. | `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites` | N/A | pass | |
|
||||
| PBS13-12.3.2 | Host ABI shape (`arg_slots`,`ret_slots`) MUST be preserved when available. | `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites` | `BytecodeEmitterTest#emitMustRejectAbiMismatch` | pass | |
|
||||
| PBS13-12.4.1 | Intrinsic callsite MUST preserve canonical intrinsic identity. | `IRBackendExecutableContractTest#aggregatorMustReindexIntrinsicsToBuildGlobalPool` | N/A | pass | |
|
||||
| PBS13-12.4.2 | VM-owned intrinsics MUST NOT be reclassified as host bindings. | `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites`; `BackendGateIIntegrationTest#gateI_validIntrinsicPath` | N/A | pass | |
|
||||
| PBS13-12.5 | `requiredCapabilities` MUST be deterministic for same admitted graph. | `PbsFrontendCompilerTest#shouldExtractReservedMetadataForInterfaceModuleSurfaces` | `PbsFrontendCompilerTest#shouldRejectHostBindingCapabilityNotDeclaredInStrictContext`; `PBSFrontendPhaseServiceTest#shouldBlockDependentModulesWhenUpstreamModuleFailsHostAdmission` | pass | Deterministic derivation + strict admission path. |
|
||||
|
||||
## 4. PR-05.0.X Identity Foundation Coverage
|
||||
|
||||
| PR Item | Scope | Evidence | Status |
|
||||
| --- | --- | --- | --- |
|
||||
| PR-05.0.1 | Shared `NameTable` context across frontend phases | `NameTableTest`; `PBSFrontendPhaseServiceTest` multi-module fixtures | pass |
|
||||
| PR-05.0.2 | `ModuleId` dense table and module wiring | `ModuleTableTest`; `PBSFrontendPhaseServiceTest#shouldBlockDependentModulesTransitivelyWhenUpstreamModuleFailsLinking` | pass |
|
||||
| PR-05.0.3 | Typed `CallableId`/`IntrinsicId` in executable contract | `IRBackendExecutableContractTest`; `LowerToIRVMServiceTest` | pass |
|
||||
| PR-05.0.4 | Callable shape and type-surface interning | `CallableShapeTableTest`; `TypeSurfaceTableTest`; `PbsModuleVisibilityTest` | pass |
|
||||
| PR-05.0.5 | Synthetic stdlib `FileId` via `FileTable` | `InterfaceModuleLoaderTest#shouldRegisterSyntheticStdlibFilesInFileTable` | pass |
|
||||
| PR-05.0.6 | Host binding canonical identity interning | `HostBindingTableTest`; host admission fixtures in `PbsFrontendCompilerTest` | pass |
|
||||
|
||||
## 5. Maintenance Procedure
|
||||
|
||||
1. Any backend PR that changes conformance-relevant behavior in FE/BE pipeline MUST update this matrix.
|
||||
2. If requirement coverage changes, update: mapped tests, status, and `Last Updated` date.
|
||||
3. New normative MUSTs in specs `19/20/21` or PBS `13` addendum MUST add a new matrix row before merge.
|
||||
4. Conformance-relevant FE/BE code paths for hard-gate are:
|
||||
- `prometeu-compiler/prometeu-build-pipeline/`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/`
|
||||
- `prometeu-compiler/prometeu-frontend-api/`
|
||||
- `prometeu-compiler/prometeu-compiler-core/`
|
||||
|
||||
## 6. Review/Lint Gate
|
||||
|
||||
Matrix integrity is enforced by automated document lint:
|
||||
|
||||
- `BackendConformanceMatrixSpecTest` validates file presence, required requirement IDs, and row status integrity.
|
||||
- `BackendConformanceMatrixSpecTest` enforces hard-gate policy:
|
||||
- if `PROMETEU_MATRIX_HARD_GATE=true` and `PROMETEU_CHANGED_FILES` contains a path under conformance-relevant FE/BE prefixes,
|
||||
- then this matrix file MUST be present in `PROMETEU_CHANGED_FILES`, otherwise the gate fails.
|
||||
- CI policy uses strict Gate I mode via `PROMETEU_GATE_I_STRICT=true` (or `CI=true`) and requires `PROMETEU_RUNTIME_CHECK_CMD` for runtime-backed evidence.
|
||||
@@ -0,0 +1,24 @@
|
||||
# General Specs
|
||||
|
||||
This directory contains shared acceptance specifications for all supported languages in Prometeu.
|
||||
|
||||
## Scope
|
||||
|
||||
These specs are above language-specific specs and should be reused by each language line.
|
||||
|
||||
Typical topics:
|
||||
|
||||
- conformance gates and evidence,
|
||||
- compatibility publication policy,
|
||||
- verification/safety acceptance boundaries,
|
||||
- artifact/runtime acceptance contracts.
|
||||
|
||||
Current backend-facing chapter additions:
|
||||
|
||||
- `20. IRBackend to IRVM Lowering Specification.md`
|
||||
- `21. IRVM Optimization Pipeline Specification.md`
|
||||
- `22. Backend Spec-to-Test Conformance Matrix.md`
|
||||
|
||||
## Rule
|
||||
|
||||
Language-specific specs (for example `docs/pbs/specs`) must reference this layer instead of duplicating cross-language acceptance policy.
|
||||
Reference in New Issue
Block a user