--- id: DEC-0042 ticket: multi-frontend-remove-pbs-branches title: Frontend editorial language service contract for LSP status: accepted created: 2026-07-15 ref_agenda: AGD-0059 tags: [compiler, compiler-general, compiler-pbs, studio, frontend, coupling, multi-frontend] --- ## Context This decision belongs to domain owner `compiler/general`. Touched subdomains: - `studio/lsp` - `compiler/pbs` - `compiler/frontend-api` - `tests/architecture` PBS is currently the default Prometeu language and remains the only rich frontend with full editor assistance. The earlier provider work already established that shared compiler and Studio code must resolve behavior through `FrontendProvider`, where `compiler()` is mandatory and `languageService()` is optional. Local inspection for `AGD-0059` showed that PBS is already mostly centered in `prometeu-frontend-pbs`. The remaining architectural issue is narrower: `CompilerLanguageServiceBridge` still imports and calls PBS-specific editorial types and services directly, including `PBSFrontendLanguageService`, `PBSFrontendPhaseService`, `PbsAst`, and `PbsEditorial*` models. This makes the LSP path harder to reuse for another frontend. It also keeps a temporary PBS adapter shape in common LSP code after the provider boundary has already made language services optional. ## Decision The common LSP/editorial path MUST consume frontend-provided editorial capabilities through a generic contract exposed from `prometeu-frontend-api`. `FrontendProvider` remains the common registration unit. This decision MUST NOT replace or fragment the provider contract: - `FrontendProvider.compiler()` MUST remain the only mandatory executable frontend capability. - `FrontendProvider.languageService()` MUST remain optional. - A compile-only frontend with no language service MUST remain valid. - Unknown `languageId` values MUST continue to fail explicitly. The generic editorial contract MUST live behind the optional `languageService()` surface. It SHOULD be represented as an aggregated frontend language-service surface with small capability methods or capability records for: - semantic tokens and semantic presentation; - completion; - hover; - signature help. Each editorial capability MUST be optional or have deterministic empty/fallback behavior. Missing editor assistance MUST NOT block analyze, compile, build, backend lowering, bytecode emission, verification, or artifact writing. The common LSP implementation MUST move toward consuming only generic frontend/editorial models. It MUST NOT permanently import `p.studio.compiler.pbs.*`, know `PbsAst.File`, call `PBSFrontendPhaseService.semanticReadSurface(...)`, or depend on `PbsEditorial*` models in the common path. PBS MUST implement or adapt to the generic editorial models from inside the PBS frontend boundary. PBS-specific types may remain internal implementation details of `prometeu-frontend-pbs`. Temporary PBS adapters MAY exist during migration, but only as staged compatibility while each capability is extracted. They MUST NOT be treated as the permanent LSP contract. PBS remains the product default language and MAY be used as the fallback when the user has not explicitly chosen a language. That default/fallback rule applies only to absence of choice. It MUST NOT be used to reinterpret an unknown `languageId` as PBS. The following PBS references are allowed: - references inside the PBS frontend implementation; - PBS-specific tests; - `.pbs` fixtures; - PBS templates; - VS Code language registration for `.pbs`; - PBS semantic keys and visual presentation metadata; - PBS as product default/fallback when there is no explicit language choice; - composition-root/bootstrap registration while PBS is the concrete default frontend. The following PBS references are not allowed in the intended final state: - common LSP code importing `p.studio.compiler.pbs.*`; - common compiler, build, Studio, or app code instantiating PBS services outside provider/composition-root ownership; - treating unknown `languageId` as PBS. ## Rationale The provider contract already separates compilation from editor assistance. Keeping `languageService()` optional protects compile-first frontends from having to implement a complete IDE experience before they can participate in the compiler pipeline. The remaining PBS coupling in LSP is a known temporary gap, not a desired architecture. Generalizing the LSP/editorial contract lets the selected frontend provide editor capabilities while keeping LSP as a protocol bridge instead of a PBS semantic owner. The decision deliberately chooses incremental extraction. A one-shot abstraction over every current PBS editorial type would be high risk because there is still only one rich frontend. Incremental capability extraction preserves PBS behavior while letting the generic contract grow from actual LSP needs. Keeping the contract in `prometeu-frontend-api` avoids making frontends depend on `prometeu-lsp`. It also avoids putting editor-specific DTOs into `compiler-core` unless future implementation pressure proves that they are truly compiler-core concepts. Allowing PBS as product default is compatible with multi-frontend architecture. Using PBS as fallback for unknown language IDs is not compatible, because it hides configuration errors and makes language identity ambiguous. ## Implications - `CompilerLanguageServiceBridge` must be migrated away from PBS-specific imports in stages. - Generic editorial DTOs must preserve the information currently needed by PBS completion, hover, signature help, documentation Markdown, and semantic tokens. - PBS can keep rich internal models, but it must map them to generic frontend-facing models before LSP consumes them. - Future frontends can implement only the editorial capabilities they support. - LSP fallback behavior for missing capabilities must be explicit and deterministic. - Architectural tests should eventually enforce that common LSP code does not import PBS implementation packages. - PBS default project creation and composition bootstrap should not be removed merely because they mention PBS. ## Technical Specification The first generic editorial model set SHOULD be small and focused on existing LSP v1 needs: - `FrontendCompletionCandidate` - `FrontendHover` - `FrontendSignatureHelp` - `FrontendSignature` - `FrontendSymbolKind` - `FrontendDocumentation`, if documentation format needs to be explicit instead of plain Markdown text The generic model MUST represent: - display labels and details needed for completion; - completion kind in language-neutral terms; - hover Markdown or structured hover sections; - signature labels and parameter labels; - active signature and active parameter; - semantic token keys already owned by `FrontendSpec`/semantic presentation; - documentation text without requiring LSP to know PBS documentation internals. The migration order SHOULD be: 1. preserve or tighten semantic tokens and semantic presentation as frontend-owned metadata; 2. migrate completion to generic frontend models; 3. migrate hover to generic frontend models, including Markdown/documentation and signatures; 4. migrate signature help to generic frontend models; 5. remove PBS imports from the common LSP path; 6. propagate import-boundary enforcement to the architectural-tests discussion. During migration, temporary adapter code MUST be clearly local and removable. It MUST NOT introduce a second permanent PBS-specific LSP API. ## Constraints - This decision MUST NOT introduce plugin marketplace behavior, dynamic JAR loading, reflection-based discovery, RPC, sandboxing, or service locator infrastructure. - This decision MUST NOT make language services mandatory. - This decision MUST NOT require a second real frontend before the contract can be improved. - This decision MUST NOT weaken PBS regression coverage for existing completion, hover, signature help, documentation Markdown, or semantic tokens. - This decision MUST NOT move frontend semantic ownership into Studio or LSP. - This decision MUST NOT change the rule that unknown languages fail explicitly. - This decision MUST NOT remove PBS defaults, templates, fixtures, VS Code language registration, or composition-root bootstrap solely because they mention PBS. ## Propagation Targets - specs: - compiler/provider and frontend API specs that describe `FrontendProvider.languageService()`; - LSP/editor-facing specs if a current Studio/LSP spec surface is active; - architectural-boundary specs or lessons if they mention PBS import allowlists. - plans: - create staged plans for generic editorial DTOs and capability migration; - coordinate the import-boundary rule with `AGD-0067`. - code: - `prometeu-compiler/prometeu-frontend-api`; - `prometeu-lsp/prometeu-lsp-v1`; - `prometeu-compiler/frontends/prometeu-frontend-pbs`; - provider and language-service adapters as needed. - tests: - PBS regression tests for completion, hover, signature help, documentation Markdown, and semantic tokens; - LSP tests for missing language-service capability fallback; - tests with a compile-only or fake provider; - architectural tests preventing PBS implementation imports in common LSP code after migration. - docs: - this discussion's future implementation plans; - future lesson after the staged migration is complete. ## References - Agenda: AGD-0059 - Source discussion: DSC-0056 - Related lesson: `LSN-0055` Static frontend providers before plugin architecture - Related lesson: `LSN-0056` Compile-first frontends with optional editorial capabilities ## Revision Log - 2026-07-15: Initial decision drafted from accepted `AGD-0059`.