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:
@@ -347,3 +347,24 @@ fuel exhaustion across slices and direct/transitive FRAME_SYNC are required;
|
||||
sync fixtures use synthetic common IR because PBS exposes no sync construct.
|
||||
Record revisions, platform/configuration, commands, scenarios, oracles and
|
||||
results. Existing runtime tests alone are not producer integration evidence.
|
||||
|
||||
## Deterministic explanations and observed semantic context
|
||||
|
||||
PBS diagnostics retain their original code/message/template and add a detector-specific checkId, owner explanation and immutable semanticContext. This instrumentation MUST NOT change resolution, visibility, typing, lowering acceptance or source language rules. An observed resolution constraint is evidence about the implementation's lookup, not a declaration that the language requires that constraint.
|
||||
|
||||
| Check | Observed context |
|
||||
| --- | --- |
|
||||
| pbs.lowering.call-resolution | Requested call, receiver/type, argument count, declared candidates, enclosing return type and actual expected-type constraint. |
|
||||
| pbs.lowering.structured-overload | Structured call, actual owner lookup key, parameter/return lookup types and observed lookup result. |
|
||||
| pbs.flow.call-target | Applied symbol/construction, callable classification, argument/constraint, candidates and scope. |
|
||||
| pbs.flow.assignment-target | Assignment symbol/construction, binding classification and scope. |
|
||||
| pbs.lowering.stack-shape | Executable function, declared result slots, instruction count and recorded stack-check condition; known internal failure remains distinct from unsupported source construction. |
|
||||
|
||||
Each semantic fact has {value,availability,reason}. Known null differs from not-recorded/unavailable/not-applicable. Keep declaredTypes, expressionTypes and resolutionConstraints distinct. Unknown module/dependency/expression information is marked not-recorded; source identity is available separately in the origin/input map. Related declarations/candidates are included only when actually recorded. Generic-instantiation diagnostic reconstruction MUST preserve the complete context and reported phase.
|
||||
|
||||
The unchanged frozen cases F1-direct/F1-two-calls/F1-service-this, F3-function/F3-global/F3-service and F4-same-dependency/F4-same-direct qualify these mechanisms through real LSP analysis and Studio build/MCP. F3-service demonstrates that the shared unsupported-lowering code can represent distinct structured-overload and stack-shape checks. The original rejected observations are retained in the Studio diagnostic lesson. Following the production corrections, those eight valid sources MUST compile without their former false rejection; invalid file-private access remains a source rejection. Existing detector IDs, source attribution and operation-failure semantics remain unchanged.
|
||||
|
||||
|
||||
## Production correction regressions
|
||||
|
||||
The compiler must no longer emit the received false call-resolution, peer-binding or nominal-owner rejections for the eight valid production cases. Negative visibility controls still return structured source errors, independently from loader/infrastructure/guest failures. Diagnostics remain producer-owned; a compiler correctness fix does not weaken source attribution or reinterpret callable completion as approval. PbsFacadeDiagnosticTest uses the unchanged F3-file-private negative fixture, and StructuredDiagnosticsIntegrationTest now verifies the corrected positive corpus plus that negative control. The earlier rejection evidence remains immutable.
|
||||
|
||||
@@ -298,3 +298,13 @@ Its requirements apply in addition to this chapter; pause/resume remain independ
|
||||
Emit an existing typed return group: Int32 status 0 for success or canonical nominal error case index 1..N, followed by the complete plain payload group. Unit result has only status. Error payloads use admitted typed defaults, including nullable references, without constructing payload objects. Preserve typed reference/builtin/Fn/trait groups across signatures, Registry, direct/contract calls, branches and discard. Propagation fills the enclosing inactive payload and returns immediately; handle recovers locally or remaps outward. The common backend consumes neutral typed IR with no PBS branches.
|
||||
|
||||
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
|
||||
|
||||
## Production binding preservation
|
||||
|
||||
Comparison lowering MUST scope expected types to the operands rather than leaking the enclosing bool result expectation into nested calls. Type inference does not execute an operand; emission evaluates each receiver and explicit argument once in the existing order. Legitimate contextual overload selection remains available at the owning expression boundary.
|
||||
|
||||
The module assembly supplies admitted sibling declaration/signature identities. Lowering references ordinary sibling functions and service methods/accessors in their defining module. Global accesses resolve to the defining file's single storage slot; they MUST NOT allocate or initialize another global in each caller. Services retain one canonical singleton/accessor at their definition. Internal symbolic global bindings MUST be fully resolved within PBS before publishing common IR; the common instruction contract, ABI and backend remain unchanged.
|
||||
|
||||
Runtime owner lookup and imported callable selection MUST preserve canonical declaration origin, rather than flattening private types into a name-only owner map. Synthesized receiver parameter types retain the defining source scope. Callable shape matching is qualified by the known owner declaration so distinct private owners with identical method spelling cannot replace or ambiguate one another. Aliases remain source-facing names for their original declaration.
|
||||
|
||||
Conformance includes F1-direct/two-calls/service-this, F3-function/global/service and F4-same-dependency/direct with their original files/names/imports. All original F1/F2/F3/F4/F5 controls, file-private rejection and deliberate guest fault remain mandatory. An investigation-only unoptimized probe omits OptimizeIRVMPipelineStage and emits original IRVM; this is not a public compiler optimization option. See [Static Semantics](4.%20Static%20Semantics%20Specification.md) and [Diagnostics](12.%20Diagnostics%20Specification.md).
|
||||
|
||||
@@ -873,3 +873,13 @@ Its requirements apply in addition to this chapter; pause/resume remain independ
|
||||
Factory-only admission uses trusted canonical declaration origin, never visible spelling or slot count. Reject external positional/named construction and forged metadata; omit prohibited constructors from completion/signature help and expose public factories. Result error identity is nominal through imports and aliases; a result-effect function cannot be converted to plain Fn.
|
||||
|
||||
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
|
||||
|
||||
## Production expression and module conformance
|
||||
|
||||
Expected result types constrain the expression node that owns the expectation. A returned bool comparison MUST NOT force an int-returning operand call to return bool. Operand inference/resolution MUST retain its own type and use the opposite operand's known type when contextual disambiguation is required. This does not remove legitimate expected-return overload selection. Receiver/argument evaluation count and order remain those of [Dynamic Semantics](9.%20Dynamic%20Semantics%20Specification.md).
|
||||
|
||||
Sibling-file callable/global/service surfaces MUST use declaration/signature-level admission from mod.barrel. Both mod and pub entries admit same-module access; omission leaves the declaration file-private. Publishing one overload MUST NOT publish every overload sharing its name. Caller-visible names and definition-scoped private dependencies are different surfaces. The existing [syntax visibility contract](3.%20Core%20Syntax%20Specification.md) and [resolution contract](5.%20Manifest%2C%20Stdlib%2C%20and%20SDK%20Resolution%20Specification.md) remain authoritative.
|
||||
|
||||
Nominal receiver/method binding MUST retain the originating declaration and lexical scope, including aliases and synthesized receiver types. A private homonym introduced through a dependency cannot replace a local declaration or create an ambiguous executable target merely by sharing spelling. Transient IDs and PBX byte equality across builds are not nominal-identity requirements.
|
||||
|
||||
Conformance: PbsProductionLoweringRegressionTest and PbsNominalOwnerRegressionTest cover the frozen 28-case corpus, contextual overloads, privacy by signature, shared storage/singletons and order-sensitive effects. The maintained source-to-guest matrix is tools/pbs-production-corpus/run.py.
|
||||
|
||||
@@ -148,6 +148,26 @@ For v1 backend/runtime diagnostics and conformance support, emitted artifacts mu
|
||||
|
||||
This minimum does not require one universal source-map format.
|
||||
|
||||
### 7.1 Compilation attribution before artifact emission
|
||||
|
||||
Compiler failures before PBX emission MUST use attribution from the program being
|
||||
checked. The IRVM function plan associates each instruction with its emission
|
||||
operation and optional source origin. Lowering and optimization MUST preserve
|
||||
that association, including recorded generated provenance, when expanding,
|
||||
removing or rewriting instructions.
|
||||
|
||||
An IRVM verification PC is a zero-based byte offset within a function in the
|
||||
checked program. It MUST be identified as `pcSpace=irvm-function`, `pcUnit=byte`,
|
||||
and accompanied by the reporting stage and validation point. It is not an emitted
|
||||
PBX offset or executed runtime PC. A validation after an optimization pass uses
|
||||
that pass's output, including its remapped instruction boundaries and origins.
|
||||
|
||||
These in-memory diagnostics do not change PBX serialization or the minimum debug
|
||||
hooks above. A missing instruction origin MUST remain explicit; neither a nearby
|
||||
instruction nor a function's first line supplies an exact fallback. The complete
|
||||
diagnostic and public-failure contract is defined in
|
||||
[Compiler 19, sections 12–13](19.%20Verification%20and%20Safety%20Checks%20Specification.md).
|
||||
|
||||
## 8. Deterministic Emitter Rejection
|
||||
|
||||
Emitter-side rejection must be deterministic for malformed or inconsistent artifact candidates, including at minimum:
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -5,6 +5,37 @@ The current typed Registry/PBX v0 contract is normative in
|
||||
Its complete typed function records, mandatory sections and verification rules
|
||||
replace the earlier slot-only artifact baseline.
|
||||
|
||||
## Structured Compiler Diagnostic Qualification
|
||||
|
||||
These rows qualify Compiler 15 §7.1 and Compiler 19 §§12–13. They preserve the
|
||||
original verifier rules and codes. Controlled RET/join failures qualify attribution,
|
||||
not reproduction or correction of the historical Zelda reports. Local compiler
|
||||
qualification does not release the separate Studio/MCP integration gate.
|
||||
|
||||
| Obligation | Required behavior | Tests | Status |
|
||||
| --- | --- | --- | --- |
|
||||
| G19-12.1-RET | Exact checked-program attribution, qualified function-relative byte PC and structured expected/actual heights. | `IRVMAttributionTest#retMustRetainOriginCoordinatesAndStructuredHeights` | pass |
|
||||
| G19-12.1-JOIN | Join destination and conflicting heights; detection does not claim cause. | `IRVMAttributionTest#joinMustPointAtDestinationAndRetainConflictingHeights` | pass |
|
||||
| G19-12.1-LOWERING | Preserve context when lowering fails before assigning IRVM. | `LowerToIRVMPipelineStageTest#validationMustPreserveOriginBeforeIrvmIsAssigned` | pass |
|
||||
| G19-12.1-PASS | Input and pass-output validation identify their actual programs and shifted PCs. | `IRVMAttributionTest#optimizationInputMustHaveItsOwnValidationPoint`; `IRVMAttributionTest#failingPassMustUseShiftedOutputAndSurvivingOrigin` | pass |
|
||||
| G19-12.2-PROVENANCE | Generated anchors, generated absence and unknown origin remain distinguishable. | `IRVMAttributionTest#generatedAndMissingOriginsMustBeExplicit`; `StructuredDiagnosticTest#provenanceMustRemainIndependentFromAvailability` | pass |
|
||||
| G19-12.2-CONTEXT | Function context does not replace missing primary source; real zero offsets survive. | `IRVMAttributionTest#functionContextMustNotReplaceMissingInstructionSpan`; `IRVMAttributionTest#retMustRetainOriginCoordinatesAndStructuredHeights` | pass |
|
||||
| G19-12.2-NOPLAN | Module-only and no-plan failures retain known coordinates and explicit absence. | `IRVMAttributionTest#moduleOnlyValidationMustPreserveFailureWithoutInventingSource` | pass |
|
||||
| G15-7.1-REMAP | Rewrites/removals preserve operation provenance and function context. | `IRVMAttributionTest#jumpRemappingMustRetainGeneratedOriginAndFunctionContext`; existing G21-7.5 preservation tests | pass |
|
||||
| G19-12.4-PROJECTION | Preserve message/phase, related relationships, template parameters and classification without transport dependencies. | `StructuredDiagnosticTest#projectionMustPreservePhaseParametersRelatedAndLongSpan`; `FrontendDiagnosticProjectionTest#frontendProjectionMustRetainMessageRelatedAndParameters` | pass |
|
||||
| G19-12.4-PHASE | Preserve a reported backend phase through the semantic diagnostic model without inventing an enum classification. | `StructuredDiagnosticTest#backendPhaseMustRoundTripWithoutInventingASemanticPhase` | pass |
|
||||
| G19-12.4-LIMIT | Existing verifier guards supply typed limit category and structured values through the stage adapter. | `BytecodePreloadVerifierServiceTest#resourceGuardsMustKeepLimitCategoryAndValuesWithoutMessageParsing`; `VerifyBytecodePipelineStageTest#stageMustPreserveTypedVerificationLimit` | pass |
|
||||
| G19-12.4-IO | An observed artifact-write I/O failure retains infrastructure category and output identity. | `WriteBytecodeArtifactPipelineStageTest#ioFailureMustBeInfrastructureWithStructuredOutputPath` | pass |
|
||||
| G19-13-ANALYSIS | Rejected analysis returns issues, stops later stages and makes no false success claim. | `CompilerFailurePayloadTest#rejectedAnalysisMustReturnIssuesWithoutSuccessOrLaterStages` | pass |
|
||||
| G19-13-FACADE | Compile/build fail-fast retains earlier warnings and technical failures are not empty analysis. | `CompilerFailurePayloadTest#failFastCompileAndBuildMustPreserveEarlierWarnings`; `CompilerFailurePayloadTest#technicalFailureMustNotBecomeAnEmptyAnalysis` | pass |
|
||||
| G19-13-FILES | Immutable source snapshots remain distinct when FileIds are reused and contexts end; legacy payload absence is explicit. | `CompilerFailurePayloadTest#compileMustPreserveAnalysisDiagnosticsAndIndependentSourceIdentities`; `StructuredDiagnosticTest#failuresMustKeepIndependentFileIdsAfterTablesAreCleared` | pass |
|
||||
| G19-13-SYNTH | Common invalid IR reaches the public facade with origin without PBS sources. | `SyntheticFrontendPipelineTest#invalidCommonIrMustReachFacadeWithSourceWithoutPbs` | pass |
|
||||
| G19-13-PBS | Original reduced PBS rejection has structured source and truthful logs; its materialized control still compiles. | `PbsFacadeDiagnosticTest#realPbsRejectionMustKeepStructuredSourceAndNoFalseSuccess`; `PbsFacadeDiagnosticTest#materializedControlMustStillCompileThroughPublicFacade` | pass |
|
||||
|
||||
Existing positive lowering, optimizer equivalence, emitter determinism and verifier
|
||||
tests remain required controls. No new PBX format or runtime behavior is asserted
|
||||
by these rows.
|
||||
|
||||
Status: Draft v1 (Traceability Baseline)
|
||||
Applies to: compiler/backend conformance traceability for canonical stage order and entrypoint-specific contracts
|
||||
|
||||
@@ -161,3 +192,18 @@ frontend syntax and lowering remain consumer-owned.
|
||||
| Structured initialization and binding diagnostics | HeadlessProcessSessionTest; observed runtime JSON fixtures | pass | Preserves full payload through MCP, including null outer PC |
|
||||
| Published schema covers current runtime reasons | Actual LifecycleRole/NonFiniteValue payloads against runtime schema | partial | Runtime enum/schema mismatch recorded in AGD75; no payload rewriting |
|
||||
| PBS migration and integrated delivery | AGD75 and consumer tickets | partial | Existing PBS suite passing is not complete executable lowering evidence |
|
||||
|
||||
## Explained diagnostic propagation qualification
|
||||
|
||||
| Contract | Required executable proof |
|
||||
| --- | --- |
|
||||
| Backend check identity/explanation/qualified coordinates | IRVMAttributionTest; controlledInvalidCommonIrRetAndJoinSurviveTheRealBuildGatewayAndAuthenticatedMcp in McpTaskToolsTest. |
|
||||
| Real resource guard, unchanged code/budget | BytecodePreloadVerifierServiceTest.resourceGuardsMustKeepLimitCategoryAndValuesWithoutMessageParsing. |
|
||||
| Eight unchanged PBS production sources, successful/negative controls, actual revisions, UI/MCP parity | StructuredDiagnosticsIntegrationTest with frozen corpus SHA-256 0ad291942af21e990f5cae3348a5be368dee865aa2843ba0d0effd1a9136cb87; authenticated MCP + production LSP/compiler/packer. |
|
||||
| Retained analysis, version/digest mismatch and unavailable result | DiagnosticAnalysisProtocolTest; AutomationLspQueriesTest. |
|
||||
| Failure codes and actual child termination/admission | LanguageFailureContractTest; TaskLanguageQueriesTest; existing task/revocation regressions. |
|
||||
| Packer failed status/empty assets, payload preservation and cancellation | StructuredShipperTest. |
|
||||
| Immutable values, known null, whole-issue count/UTF-8 detail budgets | DiagnosticPayloadTest. |
|
||||
| Navigation revision and Unicode selection | DiagnosticNavigationTest; desktop evidence is recorded separately from projection tests. |
|
||||
|
||||
Controlled invalid common IR and protocol faults are labelled fixtures. They do not reproduce historical Zelda failures or claim guest/runtime qualification.
|
||||
|
||||
@@ -409,3 +409,19 @@ modifying approval policy. Revocation removes published access even before
|
||||
asynchronous worker/runtime cleanup finishes. New grants never restore old task
|
||||
IDs or receipts. Full integrated native-client acceptance belongs to PLN-0140;
|
||||
the prior HTTP acceptance alone is insufficient.
|
||||
|
||||
## Explained build and language outcomes
|
||||
|
||||
ShipperPrepareResult preserves status/logs/manifestPath/emittedArtifacts/diagnostics and adds issues/summary/context. Shipper remains an internal orchestration structure; this contract does not require direct public access. Existing automation tools and DEV snapshots expose its result.
|
||||
|
||||
OperationState.SUCCEEDED means the callable completed mechanically. Build approval is independent: compiler-build, pack-validation, pack and manifest MUST all pass. Packer validation MUST have SUCCESS status and canPack=true. A failed validation with an empty asset list is still a rejection. A usable buildId is issued only for a successful current task build. Compiler warnings survive successful builds and pack failures.
|
||||
|
||||
summary includes scope (document/project/build), validationStatus (passed/rejected/failed/incomplete/not-evaluated/cancelled), nullable errors/warnings/infos counts, stage states and coverage. Unknown counts are null, never invented zeroes. Stage states are not-run/running/passed/rejected/failed/cancelled. Producer/verification failures are distinct from program rejection; a bounded detail sample never determines approval. Detail coverage and input-revision coverage are independent.
|
||||
|
||||
Cancellation is ShipperPreparationStatus.CANCELLED and validationStatus=cancelled. Preserve known partial issues/stages and do not issue a buildId. Cancel acknowledgement is independent of workerTerminated. Final tracked build results and the canonical session diagnostic view are published only after actual managed-worker termination. A cancelled worker's late return must not overwrite task revocation or turn into successful approval. Existing task admission, deduplication and explicit return authority remain unchanged.
|
||||
|
||||
DEV and the existing build surface render the canonical public view: summary, counts, stages, code/check, explanation, and individually expandable facts, semantic context, related origins and suggested checks. They MUST NOT reclassify logs or invoke another compiler. Source navigation checks project admission and the current digest before selecting a range. Changed source is labelled stale; unavailable revisions do not guarantee a current range. The diagnostic viewer is read-only, and generated/external navigation retains its existing read-only authority.
|
||||
|
||||
Language queries use a 10000 ms execution budget from admission (including queue/read/connect/initialize/analysis/query) plus a 2000 ms cleanup response window. Cancel pending requests and owned socket/listener/executors. shutdownNow is not evidence of termination. If a child remains alive, the caller may return the primary failure with workerTerminated=false, but the managed worker remains alive/busy until that child actually stops. Manual control and successor admission cannot be released early. Preserve the first failure and attach cleanup state rather than replacing it with a later failure.
|
||||
|
||||
Conformance distinguishes model/projection tests, source-navigation tests and real JavaFX desktop inspection. Model tests alone do not establish visual inspection. The integrated corpus uses production compiler/packer/LSP and authenticated MCP; controlled invalid IR and stubborn-child/protocol fixtures are explicitly identified test injections.
|
||||
|
||||
@@ -266,7 +266,7 @@ IDs from another task or project cannot be used. Client sockets/listeners close
|
||||
on success, failure, timeout or cancellation; project-server shutdown closes its
|
||||
accepted sockets and executor. A lost client does not independently grant control.
|
||||
|
||||
The adapter bounds connect time to 2 seconds and the LSP exchange to 10 seconds;
|
||||
The adapter bounds connect time to 2 seconds within the shared 10-second admission-relative execution budget, followed by a 2-second cleanup response window;
|
||||
Core bounds the request worker wait to 12 seconds. Documents are limited to 4 MiB
|
||||
of UTF-8 and task-local hierarchy state to 1024 items. These are adapter resource
|
||||
guards, unrelated to the runtime's deterministic frame/watchdog semantics.
|
||||
@@ -638,3 +638,35 @@ The coding client continues to own its configured stdio process and initial trus
|
||||
Glyph-bank animation authoring, generated-source navigation, strict task-scoped MCP tools and preview use the shared animation service and validation contract. UI/MCP preserve project authority, expected revisions, conflict/cancellation/revocation and document handoff. Persist only the canonical animation sidecar; keep generated PBS read-only and neutral services independent of JavaFX/transports.
|
||||
|
||||
See the [complete animation contract](12.%20Animation%20Authoring%20Specification.md).
|
||||
|
||||
## Explained diagnostics and same-analysis LSP extension
|
||||
|
||||
The existing tools remain the entry points. studio_operation_get adds issues/summary/context to its build result; studio_language_query preserves operation/result/limitations and adds analysis/context. AutomationFailure adds neutral details. runtimeError remains reserved for native runtime data. Result fields and errors are declared in mcp/studio-tools-v1.json.
|
||||
|
||||
Correlation uses the applicable projectRoot/taskId/operationId/clientRequestId/queryId/analysisId/buildId. queryId identifies the admitted synchronous language query; it does not imply a new persisted operation registry. source FileId remains compilation-local and is qualified by analysis/input identity. Context identifies actual observed source inputs with SHA-256, language/SDK/target/profile values and honest partial coverage. A per-connection version=1 is not a global disk revision. Configuration values without a captured manifest-byte revision and pack/assets inputs MUST remain explicitly limited.
|
||||
|
||||
The LSP client advertises experimental.prometeuDiagnosticAnalysis={version:1}. A supporting real compiler-backed project server returns:
|
||||
|
||||
```json
|
||||
{"prometeuDiagnosticAnalysis":{"version":1,"method":"prometeu/documentAnalysis","diagnosticDataVersion":1}}
|
||||
```
|
||||
|
||||
For each didOpen/didChange, the server retains one analysisId and its complete analysis result. Located standard diagnostics contain data.prometeu={version:1,analysisId,issueId,issue}. Under the shared detail budget, identity and an explicit omission limitation replace the omitted issue. Locationless/project issues remain in the complementary analysis envelope and MUST NOT be coerced into standard zero ranges.
|
||||
|
||||
The request prometeu/documentAnalysis accepts {textDocument:{uri,version},contentSha256}. It returns {analysisId,document,issues,summary,inputs,configuration} from that retained analysis, without running a second backend/semantic analysis to produce details. document identifies the exact opened content. Current URI/version/digest mismatch returns JSON-RPC -32020 with reason ANALYSIS_REVISION_MISMATCH; unavailable retained analysis returns -32021 with ANALYSIS_UNAVAILABLE. Closing/disconnecting clears retained data. Analysis execution failure is an error, never successful empty diagnostics.
|
||||
|
||||
When the capability is absent, preserve standard results, report ANALYSIS_DETAILS_UNAVAILABLE, and use limited/unavailable rich coverage with not-evaluated validation. This fallback does not qualify the enriched integration. Empty standard diagnostics alone cannot establish project/build validity.
|
||||
|
||||
| Failure code | Mechanism |
|
||||
| --- | --- |
|
||||
| LANGUAGE_QUERY_TIMEOUT | Admission-relative execution deadline expired. |
|
||||
| LANGUAGE_QUERY_CANCELLED | Query interrupted or cancelled. |
|
||||
| LANGUAGE_SERVER_UNAVAILABLE | Project endpoint absent/unreachable. |
|
||||
| LANGUAGE_QUERY_PROTOCOL_FAILURE | Unexpected JSON-RPC/protocol failure. |
|
||||
| LANGUAGE_QUERY_INTERNAL_FAILURE | Analysis/query execution failed internally or advertised analysis is unavailable. |
|
||||
| LANGUAGE_QUERY_CLEANUP_FAILED | Owned query resource cleanup failed. |
|
||||
| LANGUAGE_QUERY_REVISION_MISMATCH | Analysis document identity differs from requested revision. |
|
||||
|
||||
Details retain component, operation/method, queryId, applicable identity, executionBudgetMs, cleanupBudgetMs, workerTerminated and cleanup. Preserve existing authority, read-only, unsupported and parameter errors. The first failure wins; cleanup status is attached independently. The default budget is 10000+2000 ms as specified by Studio 10. This does not alter runtime deadlines.
|
||||
|
||||
Conformance: StructuredDiagnosticsIntegrationTest exercises all eight unchanged PBS sources (now corrected positives), F1-local and the file-private negative control through authenticated HTTP MCP and the real project LSP; McpTaskToolsTest controlled invalid common IR exercises RET/join through the production backend/gateway/build tool. DiagnosticAnalysisProtocolTest checks retained identity/mismatch/unavailable; LanguageFailureContractTest checks real-socket controlled faults, fallback and delayed child termination. Existing task tests retain deduplication, cross-project isolation and revocation gates.
|
||||
|
||||
@@ -208,3 +208,26 @@ writes before retrying cleanup. Canceling that confirmation sends no consent.
|
||||
Neither task release, Stop, reclaim nor a timeout implicitly permits discard.
|
||||
Forced termination remains infrastructure failure with unknown publication
|
||||
outcome; it MUST NOT manufacture a durable save result.
|
||||
|
||||
|
||||
## Project LSP endpoint discovery
|
||||
|
||||
An open project's Studio LSP adapter MUST atomically publish `.studio/lsp.json`
|
||||
after its loopback server starts. Schema version 1 contains `schemaVersion`,
|
||||
`projectRoot` (canonical filesystem path), `sessionId` (fresh for each boot),
|
||||
`processId`, `host` (`127.0.0.1`) and `port` (the actual OS-assigned port).
|
||||
Publication failure MUST stop the newly started server. Shutdown MUST stop the
|
||||
server and remove discovery only when its session identity still owns the file.
|
||||
The file is transient, unversioned, carries no credential and MUST be independent
|
||||
of automation grants. It does not change the public LSP configuration default.
|
||||
|
||||
The VS Code extension MUST default to discovering this file for exactly one local
|
||||
workspace project, validate schema/root/process/host/port, and initialize against
|
||||
that canonical workspace. It MUST NOT silently select one of several roots or
|
||||
fall back to a fixed port. Absent or dead-process discovery means waiting for
|
||||
Studio; malformed metadata MUST be reported without connecting. File creation,
|
||||
replacement or deletion and workspace/configuration changes MUST restart discovery.
|
||||
Retries MUST use capped exponential backoff (2–30 seconds), reset after connection,
|
||||
and stop at extension shutdown. Connection state MUST be visible without recurring
|
||||
error popups. Explicit manual mode MAY use configured host/port for other hosts.
|
||||
The server's project binding validation remains authoritative.
|
||||
|
||||
@@ -199,3 +199,25 @@ Filesystem publication MUST NOT run under a long-held authority monitor.
|
||||
Glyph-bank animation authoring, generated-source navigation, strict task-scoped MCP tools and preview use the shared animation service and validation contract. UI/MCP preserve project authority, expected revisions, conflict/cancellation/revocation and document handoff. Persist only the canonical animation sidecar; keep generated PBS read-only and neutral services independent of JavaFX/transports.
|
||||
|
||||
See the [complete animation contract](12.%20Animation%20Authoring%20Specification.md).
|
||||
|
||||
## Explained diagnostic values and producer boundaries
|
||||
|
||||
StudioDiagnostic MUST carry the canonical logical issue through immutable JSON-compatible values. Studio API/Core MUST NOT depend on compiler AST/IR classes, PBS, LSP4j, transport objects or Throwable serialization. Existing code/severity/message constructors remain compatible.
|
||||
|
||||
| Field group | Contract |
|
||||
| --- | --- |
|
||||
| Identity | issueId identifies one producer event within analysisId. The same event keeps its ID in standard LSP data, complementary analysis, MCP and UI. Repeated events remain distinct. |
|
||||
| Producer and rule | producer has component, owner and languageId; code is the original producer code. codeOrigin marks producer versus studio-adapter. templateId/templateParameters remain separate from message. checkId identifies the detector independently of a shared code. |
|
||||
| Classification | severity, phase, stageId and failureKind preserve the producer's classification. Detection phase MUST NOT become an inferred cause. |
|
||||
| Explanation | explanation has id, summary, rule and availability. Text is deterministic and owner-maintained, never generated by an LLM at query time. Unknown checks report unavailable explanation. |
|
||||
| Evidence | facts, semanticContext, origin, related, suggestedChecks and limitations retain observed values and their availability. Suggested checks are investigations, not automatic source edits. |
|
||||
|
||||
semanticContext contains availability (available/partial/unavailable/not-applicable) and facts. Each fact is {value,availability,reason}, where availability is available/not-recorded/unavailable/not-applicable. An observed null is available; missing observations MUST NOT be represented as an observed null. Declared types, expression types and actual resolution constraints are separate concepts.
|
||||
|
||||
Origins keep UTF-8 byte spans, UTF-16 ranges and qualified IRVM coordinates separate. Convert a span only using matching captured source bytes. Missing origins, generated code, mixed input revisions and unavailable source text MUST NOT produce a fabricated zero range. Function context belongs in related context when no instruction source is recorded. Detection and context are not causal attribution.
|
||||
|
||||
The app compiler gateway translates complete warnings and BuildException payloads into neutral output or CompilerBuildFailure. Core MUST NOT catch compiler-domain exceptions directly. Packer adaptation preserves severity/category/blocking/evidencePath and asset identity; PACKER_<CATEGORY> is explicitly an adapter code. Asset ID MUST NOT be interpreted as a bank ID.
|
||||
|
||||
A shared public view contains issues, summary and context. Detail projection is limited to 1024 whole issues and 1 MiB of UTF-8 JSON issues. At a boundary, include a whole prefix, report partial detail coverage and LIMIT_EXCEEDED with budgets/total count, and retain full authoritative counts/evaluation separately. No issue field may be silently cut. UI and MCP consume this same view; underlying producer results remain complete.
|
||||
|
||||
Conformance: DiagnosticPayloadTest, StructuredShipperTest, StructuredDiagnosticsIntegrationTest and the compiler attribution/conversion regressions.
|
||||
|
||||
Reference in New Issue
Block a user