Preserve structured diagnostics, source attribution, phase outcomes and revision context through compiler, Studio, LSP, MCP and JavaFX. Add project service discovery and resilient VS Code reconnection. Correct all eight reproduced PBS production failures in expression context, sibling executable bindings and nominal owner identity. Consolidate specs, lessons, immutable baseline evidence and the maintained source-to-guest qualification runner. Validation: required Gradle gate recorded 724 tests, with 711 passed and 13 skipped. Full corpus passed 168 compilation observations and 108 guest runs (104 successes and four deliberate faults); supplemental controls passed 42 compilations and 16 guest runs. TypeScript compilation, two Node discovery tests and discussion validation passed.
20 KiB
Compiler Verification and Safety Checks Specification
The current typed Registry/PBX v0 contract is normative in Typed common Registry and PBX v0. Its complete typed function records, mandatory sections and verification rules replace the earlier slot-only artifact baseline.
Status: Draft v1 (Quality-Gate Baseline)
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 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,
- 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
This document defines:
- mandatory compiler-stage safety checks for executable pipeline stages,
- conditional integration safety regression checks against runtime line,
- 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,
- one mandatory verifier/optimizer architecture,
- PBS syntax or static-semantics catalogs,
- or a generic validator-core package.
3. Authority and Precedence
Normative precedence:
- Runtime authority (provider specifications; mirror and provenance policy)
- Bytecode authority (provider Core ISA)
20. IRBackend to IRVM Lowering Specification.md21. IRVM Optimization Pipeline Specification.md15. Bytecode and PBX Mapping Specification.md13. Conformance Test Specification.md- This document
- Frontend diagnostics specifications, including
docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md, for language-owned coverage only
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:
13. Conformance Test Specification.md15. Bytecode and PBX Mapping Specification.md20. IRBackend to IRVM Lowering Specification.md21. IRVM Optimization Pipeline Specification.mddocs/specs/compiler-languages/pbs/12. Diagnostics Specification.mdas the current frontend diagnostics catalog, not as the owner of this specification
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:
LowerToVMsafety checks:- deterministic control-flow lowering checks,
- deterministic function-id assignment checks,
- mandatory slot/return shape checks,
- mandatory callsite form checks.
OptimizeIRVMsafety checks:- semantic-preservation regression checks,
- deterministic output checks for same input graph,
- profile-compatibility checks (
vm_profile).
EmitBytecodesafety 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.
- 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:
- valid pre-load host path that loader patches and runtime executes,
- rejection of out-of-bounds
HOSTCALLindex, - rejection of unused
SYSCdeclarations, - rejection of raw
SYSCALLin pre-load artifact, - rejection of host ABI mismatch (
arg_slots/ret_slots), - rejection of missing capability at load-time,
- valid VM-owned intrinsic path,
- 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:
- S-U evidence is required for baseline safety posture,
- S-I evidence is required for integration-ready safety claims,
- 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:
MARSHAL_FORMAT_*,MARSHAL_LINKAGE_*,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:
- required stage-level safety checks are test-backed,
- executable backends have explicit S-I status (
pass/fail/deferred), - integration safety regressions are preserved in tests,
- 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:
- the input artifact the check reads;
- whether that artifact is language source/AST/marker or a common contract;
- the matrix owner;
- the code family (
E_PARSE_*/E_SEM_*/E_LINK_*/E_HOST_*versusCOMMON_*/LOWER_IRVM_*/MARSHAL_*); - 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. An origin required by a common handoff contract MUST remain a structural obligation; missing that required origin is a structural error. Diagnostic enrichment itself MUST NOT invent a span or change the underlying acceptance rules. Source-free inputs and failures without available source remain diagnosable through the explicit absence states in section 12.
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 onIRReservedMetadata.
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
PbsHostAdmissionValidatorinto a common package; - moving asset-resolution production code;
- extracting PBS linking;
- or reopening lifecycle-assembly ownership.
Platform validators MUST NOT depend on types from the PBS frontend module (prometeu-frontend-pbs). The package p.studio.compiler.pbs is not the complete boundary; facades shipped by that module remain PBS-owned. Platform validators MUST NOT discover roles from __pbs. prefixes.
12. Structured Verification Attribution
12.1 Capture and coordinates
IRVM validation failures MUST retain their existing code, function index and PC. While the checked function and coherent emission plan are available, the validator MUST capture the corresponding operation's attribution and known function/module identity. The reporting stage MUST preserve that context, including when lowering fails before assigning its result to the pipeline context.
Coordinates MUST identify pcSpace=irvm-function and pcUnit=byte, with PC measured
from zero within the function using instruction encoded sizes. Lookup MUST match
an exact instruction boundary in the checked program. Source attribution MUST NOT
be reconstructed from a different program, a later PBX image or a nearest span.
The technical stageId is separate from a frontend diagnostic's semantic phase.
Validation identifies lowering-output, optimization-input or
optimization-pass-output; the latter includes the pass name. A pass name records
where detection occurred and does not establish causality. The optimizer MUST
preserve operation and function attribution when rewriting or deleting instructions.
12.2 Provenance, precision and absence
Attribution uses independent, explicit fields:
| Field | Values and meaning |
|---|---|
originKind |
source, generated or unknown, based on producer evidence. |
locationKind |
instruction, function or none; a function span supplies context only. |
role |
detection or context; generated source anchors and related locations are context. |
span |
Real FileId and half-open interval when available, preserving existing Span conventions. |
absenceReason |
no-emission-plan, no-source-span, generated-without-anchor or unknown when no span is available. |
Missing source MUST NOT imply generated provenance. A known generated instruction may have a real source anchor or no anchor. Missing primary source MUST remain visible even if an enclosing function or other related location is known. Real offset zero is valid; an invented zero/first line is not a fallback. No unmeasured confidence percentage is part of the contract.
Module-only validation and programs without emission plans MUST retain their
original rejection and known coordinates with no-emission-plan. This absence is
diagnostic information, not permission to weaken a required handoff invariant.
Frontend diagnostics keep their original source spans without being assigned an
IRVM instruction or execution PC.
12.3 Detection and technical evidence
MARSHAL_VERIFY_PRECHECK_BAD_RET_STACK_HEIGHT MUST expose expectedHeight and
actualHeight as structured parameters from the check. Its origin identifies the
RET at which the mismatch was detected.
MARSHAL_VERIFY_PRECHECK_STACK_MISMATCH_JOIN MUST expose existingHeight and
incomingHeight. Its primary PC/span identifies the join destination. It MUST NOT
be presented as proof that this destination caused the conflict.
Related locations MUST retain their span, contextual role and recorded relation, such as declaration, callee, predecessor or enclosing function. They MUST NOT invent a relationship from names or physical proximity. Full causal CFG or call chain reconstruction is not required by this contract.
12.4 Shared models and classification
BuildingIssue and Diagnostic MUST preserve code, severity, original phase, message, available function/module identity, source and verification context, related locations, templates/placeholders and structured parameters through their projections. The shared value types MUST remain independent of Studio and transport DTOs. A backend phase absent from a frontend enum MUST remain observable through its technical stage context.
Diagnostic exposes the original reported phase separately from its semantic
DiagnosticPhase classification. A backend phase without a corresponding enum
member MUST round-trip unchanged through getReportedPhase() and BuildingIssue;
the semantic classification may remain unknown.
Failure classification distinguishes program-rejection, internal-failure,
verification-limit, infrastructure-failure and unknown. Classification MUST
come from the detecting mechanism. An invalid IR invariant produced by the
compiler is an internal failure even when it has a user's source anchor. Source
semantic rejection remains program rejection. An unclassified technical exception
MUST NOT be relabeled by parsing its message or observing a span.
The existing preload work/scratch guards MUST report verification-limit with
structured resource, actual and limit values, preserving their budgets and
rejection codes. Artifact-write IOException MUST report infrastructure-failure
with its known outputPath. These categories come from the detecting guards and
I/O boundary; they do not redefine artifact admission or error-code ownership.
Throwable/stack trace may remain available locally, but MUST NOT replace the structured payload or be serialized indiscriminately. Compiler diagnostics do not occupy the native runtime error field.
13. Public Pipeline Failure Contract
The existing analyze, compile and build entrypoints and result contracts remain
the common facade. Analysis may complete with program diagnostics. Compile/build
MUST reject error diagnostics through BuildException while preserving accumulated
issues, including earlier warnings, the failed stage and known source identities.
The legacy exception constructors remain available; absence of their structured
payload MUST be distinguishable from a complete empty analysis.
Successful results retain their analysis snapshot and its file table. Failures MUST retain an immutable snapshot of compilation-local FileId to known project/path identity, resolvable after the original stage/context ends. Another compilation's reused FileId MUST NOT replace that identity. Snapshotting identity MUST NOT reread live source or treat size/mtime as a content revision. Document/build version and operation correlation belong to the Studio consumer contract.
Stage outcomes MUST be coherent with structured data: error issues reject that stage, technical exceptions fail the operation, and stages not executed are not approved. Logging MUST agree; completion of one stage group is not final build approval. Frontend diagnostic adaptation MUST precede a frontend success claim.
These obligations MUST be qualified with controlled RET/join failures, missing and generated origins, shifted-PC transformations, reused FileIds, a synthetic frontend and real reduced PBS sources. Controlled failures qualify diagnostics; they do not prove reproduction or correction of a historical production defect. Compiler evidence alone does not qualify Studio/MCP integration or runtime safety.
Guest hook verification boundary
Frontend diagnostics validate source marker targets/signatures and image-wide uniqueness. Common typed validation MUST independently reject duplicate roles, pause/resume parameters/results/captures and final FunctionId-zero targets. These producer defenses do not replace runtime loading/admission. Assembly and optimization MUST preserve hook metadata and externally entered bodies/callees. Regression tests MUST inspect production PBX from source and execute it through the production runtime. Source errors, common emission errors, loader failures and executed traps retain distinct diagnostics; preserve the runtime envelope.
Explained detector context and consumed-source identity
Verification diagnostics MUST identify the detector separately from the existing error code. Required checks are compiler.verify.ret-stack-height (expectedHeight/actualHeight), compiler.verify.join-stack-height (existingHeight/incomingHeight and join destination context), and compiler.verify.resource-limit (resource/actual/limit). Keep original codes and budgets unchanged. Choose check identity at the detector; never parse a human message to identify a mechanism.
DiagnosticContext carries immutable producer/check/explanation/semantic enrichment. All stage/attribution/parameter/failure conversions, BuildingIssue and generic wrappers MUST preserve it. Common executable function metadata and emission/optimization copies retain language-neutral semantic facts; the backend MUST NOT import PBS AST or redo frontend resolution to explain a failure. Explanation describes the verified rule and observed failure, without claiming a source cause.
SourceHandle records SHA-256 of bytes actually returned by its provider. Reading diagnostic context MUST NOT reread the live source. SourceReference snapshots retain compilation-local FileId/project/path and observed revision/mixed-read status. If input revisions mix, preserve that limitation and do not assert a UTF-16 range derived from one captured revision as the exact detection revision. Convert UTF-8 span offsets only at valid codepoint boundaries using captured matching content.
CompilerDiagnosticProjection provides a neutral immutable issue vocabulary for app and LSP adapters, including stable analysis-local issue identity, original templates/parameters, facts, deterministic explanation, semantic availability, origins, related context and suggested checks. Captured input coverage does not claim a whole-filesystem snapshot or pack/assets/configuration-byte revisions. Studio API/Core consume translated values without compiler dependencies.
Conformance: IRVMAttributionTest verifies RET/join identity, heights, qualified function-byte PC, origins and conversions; BytecodePreloadVerifierServiceTest uses the actual resource guard; StructuredDiagnosticsIntegrationTest and McpTaskToolsTest prove frontend and backend propagation through real services and authenticated MCP. The historical Zelda BAD_RET/Scene reports remain outside this reproduction claim.