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.
This commit is contained in:
@@ -171,7 +171,7 @@ PBS MUST keep its current `E_PARSE_*`, `E_SEM_*`, `E_LINK_*`, and `E_HOST_*` cod
|
||||
|
||||
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.
|
||||
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`.
|
||||
|
||||
@@ -217,6 +217,124 @@ This specification MUST NOT be read as authorizing:
|
||||
|
||||
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
|
||||
|
||||
@@ -228,3 +346,15 @@ 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.
|
||||
|
||||
Reference in New Issue
Block a user