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

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:

  1. Runtime authority (provider specifications; mirror and provenance policy)
  2. Bytecode authority (provider Core ISA)
  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.