implements PLN-0126
Intrepid/Prometeu/Studio/pipeline/pr-master Build started...
JaCoCo Coverage #### Project Overview No changes detected, that affect the code coverage. * Line Coverage: 61.95% (17766/28676) * Branch Coverage: 52.69% (6860/13019) * Lines of Code: 28676 * Cyclomatic Complexity: 11490 #### Quality Gates Summary Output truncated.
Test / Build skipped: 15, passed: 645
Intrepid/Prometeu/Studio/pipeline/head This commit looks good

Publish the language-versus-platform validation matrix in compiler-general
specs, retitle spec 19, and recut PBS diagnostics so common structural
failures are not PBS coverage.

Housekeep DSC-0060 with LSN-0063.
This commit is contained in:
2026-09-19 01:11:50 +01:00
parent c248b91147
commit d7c2ec880f
10 changed files with 323 additions and 100 deletions
@@ -82,7 +82,8 @@ The following inputs are already fixed elsewhere and must not be contradicted he
- Stable source span metadata is required at the token level and must remain useful to later diagnostics.
- Traps are fatal runtime outcomes rather than a recoverable userland diagnostic flow.
- Qualitative cost facts such as retention-bearing operations and host-boundary crossings are normative, but quantitative performance metrics are not.
- Topic `19` requires deterministic diagnostics for globals, lifecycle markers, init admission, and published-wrapper structural failures.
- PBS requires deterministic diagnostics for source-form globals, lifecycle markers, and init admission.
- Published-wrapper, boot-guard, synthetic-origin, and invalid-lifecycle-declaration failures are compiler-general. See `docs/specs/compiler/19. Verification and Safety Checks Specification.md` section 11 and `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`.
## 6. Required Diagnostic Phases
@@ -97,6 +98,8 @@ PBS-facing tooling must distinguish at least the following external diagnostic p
`linking` is a first-class phase in the external diagnostics contract and must not be collapsed away into a generic resolution bucket.
The `host-binding/capability admission` phase covers the source shape of `[Host]` and `[Capability]`. Canonical host-binding identity and capability consistency over `IRReservedMetadata` are platform-owned and are not moved by this specification.
This document does not require one finer-grained public phase split for verifier internals, artifact offsets, or transport-specific backend stages beyond what is stated here.
## 7. Required Diagnostic Identity, Payload, and Attribution
@@ -180,7 +183,7 @@ At minimum, the PBS diagnostics baseline must cover:
5. malformed, unauthorized, or capability-rejected host usage required by `6.2. Host ABI Binding and Loader Resolution Specification.md` and `7. Cartridge Manifest and Runtime Capabilities Specification.md`,
6. source-attributable backend-originated failures that remain user-actionable under normative lowering or load-facing rules.
7. dependency-scoped fail-fast admission at frontend boundary: when one module is rejected, modules that import it (directly or transitively) must not be emitted, while diagnostics collection for independent modules must continue.
8. lifecycle and globals diagnostics required by topic `19`, including:
8. lifecycle-marker and source-form global diagnostics, including:
- `global initializer uses unsupported form`,
- `global dependency cycle detected`,
- `global import must resolve through a global barrel entry`,
@@ -195,14 +198,7 @@ At minimum, the PBS diagnostics baseline must cover:
- `Init attribute target invalid`,
- `InitAllowed is valid only on SDK host methods`,
- `host call not allowed during init`.
9. common lifecycle structural diagnostics owned by lifecycle assembly and backend preconditions, including:
- invalid or unresolved lifecycle declaration ids and roles,
- missing frame root on an executable declaration,
- frontend-preassembled derived lifecycle artifacts,
- `synthetic wrapper entrypoint missing`,
- `published entrypoint is not function index 0`,
- `hidden boot guard is missing`,
- `synthetic callable origin missing`.
9. compiler-general lifecycle-assembly and IRVM-precondition failures, which this PBS catalog MUST NOT claim as PBS required coverage; see `docs/specs/compiler/19. Verification and Safety Checks Specification.md` section 11 and `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`.
10. symbolic asset-reference diagnostics required by backend-owned `Addressable` resolution, including:
- unresolved terminal asset reference,
- namespace-versus-terminal asset misuse,
@@ -1,18 +1,21 @@
# PBS Verification and Safety Checks Specification
# Compiler 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
Applies to: test-backed safety gates for common compiler stages, validation ownership across executable frontends, 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.
This document defines the minimum safety/verification quality gates that must be enforced for executable compiler pipelines, and the ownership rule that separates language validation from platform validation.
Its purpose is to keep safety measurable and deterministic across:
- lowering,
- optimization,
- emission,
- and runtime integration boundaries.
- runtime integration boundaries,
- and the classification of diagnostics that every executable frontend must obey.
PBS is the current executable frontend. It is an example, not the owner of this specification.
## 2. Scope
@@ -20,37 +23,41 @@ 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.
- evidence requirements for safety-related support claims,
- and validation-ownership rules that apply to all executable frontends.
This document does not define:
- full runtime verifier algorithm internals,
- formal proof of all runtime safety properties,
- or one mandatory verifier/optimizer architecture.
- one mandatory verifier/optimizer architecture,
- PBS syntax or static-semantics catalogs,
- or a generic validator-core package.
## 3. Authority and Precedence
Normative precedence:
1. `docs/pbs/specs/2. Governance and Versioning.md`
2. `docs/pbs/specs/12. Diagnostics Specification.md`
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. `21. IRVM Optimization Pipeline Specification.md`
5. `15. Bytecode and PBX Mapping Specification.md`
6. `13. Conformance Test Specification.md`
7. This document
8. Frontend diagnostics specifications, including `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md`, for language-owned coverage only
If a rule here conflicts with higher-precedence authorities, it is invalid.
If a rule here conflicts with a higher-precedence authority, it is invalid. Frontend diagnostics documents MUST NOT redefine compiler-general safety gates or platform validation ownership.
## 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`
- `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md` as the current frontend diagnostics catalog, not as the owner of this specification
## 5. Safety Gate Model
@@ -133,3 +140,74 @@ This document is healthy when:
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.
## 11. Validation Ownership
A validation MUST live at the lowest layer that understands the failure without knowing the source language.
- A check is language-owned if it needs AST, tokens, a language marker, a barrel, or another source-language rule.
- A check is platform-owned if it can be performed on `IRBackend`, `IRLifecycleDeclaration`, IRVM, PBX, host/capability tables, or ids.
Adding a validation MUST record:
1. the input artifact the check reads;
2. whether that artifact is language source/AST/marker or a common contract;
3. the matrix owner;
4. the code family (`E_PARSE_*` / `E_SEM_*` / `E_LINK_*` / `E_HOST_*` versus `COMMON_*` / `LOWER_IRVM_*` / `MARSHAL_*`);
5. whether the span comes from a common-contract origin or from language tokens/AST.
If item 2 is both, the implementation MUST emit two diagnostics with distinct identities, not one hybrid.
### 11.1 Diagnostic identity and span
Platform diagnostics MUST use `COMMON_*`, `LOWER_IRVM_*`, or `MARSHAL_*` codes and the phase of the pipeline stage that reports them.
PBS MUST keep its current `E_PARSE_*`, `E_SEM_*`, `E_LINK_*`, and `E_HOST_*` codes.
This specification MUST NOT rewrite diagnostic messages or renumber existing codes.
Common code MUST copy origin/span when the declaration, instruction, or metadata carries one. A missing origin MUST be a structural error. Implementations MUST NOT invent a span.
The same fact MAY exist on both sides. PBS explains the language rule; the common layer rejects an invalid handoff even when the frontend has no PBS markers. The two errors MUST keep distinct identities. Example: `E_SEM_MISSING_PROJECT_FRAME` and a missing frame root on an executable `IRLifecycleDeclaration`.
### 11.2 Initial ownership matrix
| Family | Owner | Status | Notes |
| --- | --- | --- | --- |
| Parse / syntax (`ParseErrors`) | `compiler/pbs` | language | remains |
| Type, flow, declaration, const, and source-form global semantics | `compiler/pbs` | language | remains |
| Markers `[Init]`, `[Frame]`, `InitAllowed`, signature, colocation | `compiler/pbs` | language | already split by lifecycle assembly |
| `host call not allowed during init` | `compiler/pbs` | language | marker/source rule |
| PBS linking (`PbsLinkErrors`, barrel, import, visibility) | `compiler/pbs` | language | do not extract |
| Source shape of `[Host]` / `[Capability]` | `compiler/pbs` | language | host-admission split |
| Canonical host-binding identity and capability over `IRReservedMetadata` | `compiler/general` | platform | classified; validator remains in the PBS package until a later plan |
| Lifecycle assembler | `compiler/general` | platform | already implemented |
| IRVM preconditions for wrapper, boot guard, origin | `compiler/general` | platform | already implemented |
| `IRVMValidator`, lowering, marshal/bytecode | `compiler/general` | platform | already implemented |
| `Addressable` / asset path | `compiler/general` | platform | classified; no extra migration in this specification |
| Gates S-U/S-I | `compiler/general` | platform | this document |
### 11.3 Host admission, assets, and linking
Host admission is split:
- language owns the source shape of `[Host]` and `[Capability]`;
- platform owns canonical binding identity `(module, name, version)`, unknown capability, undeclared capability, and inconsistent binding once those facts exist on `IRReservedMetadata`.
`PbsHostAdmissionValidator` MAY remain in the PBS package until a later plan. `E_HOST_*` MUST NOT be treated as eternal PBS semantics.
`Addressable` / asset-path resolution is platform-owned. This specification classifies it and MUST NOT move additional asset code.
PBS linking, barrel files, and `PbsLinkErrors` remain language-owned. `ResolveDeps` does not authorize extracting them.
### 11.4 What this section does not authorize
This specification MUST NOT be read as authorizing:
- a generic validator-core package;
- moving `PbsHostAdmissionValidator` into a common package;
- moving asset-resolution production code;
- extracting PBS linking;
- or reopening lifecycle-assembly ownership.
Platform validators MUST NOT import `p.studio.compiler.pbs` and MUST NOT discover roles from `__pbs.` prefixes.
@@ -151,6 +151,8 @@ Lowering from `IRBackend` to `IRVM` may start only when:
Declaration validation, role uniqueness, explicit order, and rejection of frontend-preassembled derived artifacts belong to `LifecycleAssemblerService`. `IRBackend -> IRVM` MUST keep only backend preconditions on the assembled graph, such as published-wrapper identity, synthetic origin presence, and hidden boot-guard presence. It MUST NOT reconstruct lifecycle order from callable names.
Those common structural diagnostics are compiler-general. Classification, code families, and dual language/platform reporting are owned by `docs/specs/compiler/19. Verification and Safety Checks Specification.md` section 11. They MUST NOT be catalogued as PBS-facing required coverage.
## 6. IRVM Model Obligations
`IRVM` v1 is a quasi-ISA backend form:
@@ -3,7 +3,7 @@
Status: Draft v1 (Traceability Baseline)
Applies to: compiler/backend conformance traceability for canonical stage order and entrypoint-specific contracts
Last Updated: 2026-09-18
Last Updated: 2026-09-19
## 1. Purpose
@@ -40,6 +40,13 @@ to concrete positive/negative test evidence and current status.
| 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. |
| G19-11.1 | A validation MUST live at the lowest layer that understands the failure without knowing the source language. | `ValidationOwnershipSpecTest#spec19MustBeCompilerGeneralAndPublishValidationOwnership` | N/A | pass | Spec 19 section 11 states the classification rule. |
| G19-11.2 | Spec 19 MUST publish the validation ownership matrix. | `ValidationOwnershipSpecTest#spec19MustBeCompilerGeneralAndPublishValidationOwnership` | N/A | pass | Matrix families include parse/syntax, PBS linking, and lifecycle assembler. |
| G19-11.3 | Platform diagnostics MUST use `COMMON_*` / `LOWER_IRVM_*` / `MARSHAL_*` and MUST copy origin/span when present. | `ValidationOwnershipSpecTest#spec19MustBeCompilerGeneralAndPublishValidationOwnership`; `LifecycleAssemblerServiceTest#assembleMustRejectMissingFrameRootWithoutRepair` | N/A | pass | Code families and span policy are normative in spec 19 section 11.1. |
| G19-11.4 | The same fact MAY exist as a language diagnostic and a platform diagnostic with distinct identities. | `ValidationOwnershipSpecTest#spec19MustBeCompilerGeneralAndPublishValidationOwnership` | N/A | pass | Dual reporting is required when a check reads both source and common contract. |
| G19-11.5 | Host admission MUST split source attribute shape from canonical `IRReservedMetadata` identity without moving the PBS validator in this plan. | `ValidationOwnershipSpecTest#spec19MustBeCompilerGeneralAndPublishValidationOwnership` | N/A | pass | Classified as platform; validator remains in the PBS package. |
| G19-11.6 | Platform validators MUST NOT import PBS packages or match `__pbs.` prefixes. | `CommonBackendArchitectureTest#commonBackendMustNotImportPbsFrontendPackages`; `CommonBackendArchitectureTest#commonLifecycleAndBackendMustNotDiscoverRolesFromPbsNamePrefixes` | N/A | pass | Guard covers backend, lifecycle, and all common pipeline stages. |
| PBS12-11 | PBS diagnostics MUST NOT claim common structural lifecycle/IRVM failures as PBS required coverage. | `ValidationOwnershipSpecTest#pbsDiagnosticsMustNotClaimCommonStructuralFailures` | N/A | pass | PBS spec 12 points those failures at spec 19 section 11 and spec 20. |
| G20-4.1.1 | `IRBackend` MUST be the common frontend-to-backend executable handoff. | `LowerToIRVMServiceTest#lowerMustAcceptManuallyConstructedCommonIRBackend` | N/A | pass | Direct backend lowering from manually constructed common IRBackend proves PBS parser/frontend services are not required. |
| G20-4.1.2 | Common backend code MUST NOT depend on `p.studio.compiler.pbs`. | `CommonBackendArchitectureTest#commonBackendMustNotImportPbsFrontendPackages` | N/A | pass | Source-level architectural guard rejects PBS frontend imports in common backend packages. |
| G20-4.1.3 | Public `IRBackend` contract MUST NOT expose PBS AST, token, parser, semantic, or editorial types. | `IRBackendExecutableContractTest#publicIRBackendContractMustNotExposePbsTypes` | N/A | pass | Reflection guard covers public contract fields, constructors, methods, and record components. |