Files
prometeu-studio/docs/specs/compiler/19. Verification and Safety Checks Specification.md
bquarkz ea1cc26fe3
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit
feat(studio): improve compiler reliability and AI diagnostics
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.
2026-11-10 12:36:25 +00:00

361 lines
20 KiB
Markdown

# Compiler Verification and Safety Checks Specification
The current typed Registry/PBX v0 contract is normative in
[Typed common Registry and PBX v0](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
Its complete typed function records, mandatory sections and verification rules
replace the earlier slot-only artifact baseline.
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:
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `20. IRBackend to IRVM Lowering Specification.md`
4. `21. IRVM Optimization Pipeline Specification.md`
5. `15. Bytecode and PBX Mapping Specification.md`
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 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.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
### 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.
## 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. 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 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 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.