---
id: LSN-0058
ticket: multi-frontend-remove-pbs-branches
title: Generic Frontend Editorial Contract for LSP
created: 2026-07-15
tags: [compiler, compiler-general, compiler-pbs, studio, frontend, lsp, coupling, multi-frontend]
---

## Original Problem

Prometeu was preparing for multiple compiler frontends while the LSP bridge still knew too much about PBS internals. The first framing was broad: remove explicit PBS checks from common code. After inspection, that was too blunt.

PBS was already mostly centered in `prometeu-frontend-pbs`. Defaults, templates, `.pbs` fixtures, VS Code language registration, semantic keys, and composition-root bootstrap were legitimate PBS references. The real architectural problem was narrower: common LSP code imported and called PBS-specific editorial types and services for semantic tokens, completion, hover, signature help, and semantic read preparation.

## Consolidated Decision

The common LSP/editorial path must consume frontend-provided editorial capabilities through generic contracts exposed by `prometeu-frontend-api`.

The provider contract remains stable:

1. `FrontendProvider.compiler()` is mandatory.
2. `FrontendProvider.languageService()` is optional.
3. Compile-only frontends are valid.
4. Unknown `languageId` values fail explicitly.
5. PBS may be the product default only when the user has not chosen a language.

PBS is not the shared editor model. PBS implements the generic contract from inside its frontend boundary.

## Final Implementation Shape

The implementation introduced generic frontend editorial DTOs and default methods in `FrontendLanguageService`:

1. `FrontendDocumentRequest`
2. `FrontendEditorialContext`
3. `FrontendCompletionCandidate`
4. `FrontendHover`
5. `FrontendSignatureHelp`
6. `FrontendSignature`
7. `FrontendSymbolKind`
8. `FrontendDocumentation`

`CompilerLanguageServiceBridge` now resolves the selected provider and calls generic `FrontendLanguageService` methods for semantic tokens, completion, hover, and signature help.

PBS-specific analysis setup moved behind `PBSFrontendLanguageService.prepareEditorialContext(...)`. The bridge no longer imports `p.studio.compiler.pbs.*`, no longer knows `PbsAst.File`, and no longer calls `PBSFrontendPhaseService.semanticReadSurface(...)` directly.

An architectural test now protects the common LSP code from reintroducing PBS implementation imports.

## Examples

A frontend with no language service remains valid:

```java
public final class CompileOnlyFrontendProvider implements FrontendProvider {
    @Override
    public FrontendSpec specification() {
        return SPEC;
    }

    @Override
    public FrontendPhaseService compiler() {
        return compiler;
    }
}
```

An LSP consumer should resolve the selected provider, ask for `languageService()`, and fall back deterministically when editorial capability is absent.

PBS can still keep rich internal models such as `PbsEditorialResolvedSymbol`, but those models must be mapped to generic `FrontendHover`, `FrontendCompletionCandidate`, or `FrontendSignatureHelp` before common LSP consumes them.

## Pitfalls

Do not remove legitimate PBS defaults just because they mention PBS. PBS remains the product default when the user has not chosen another language.

Do not use PBS as a fallback for unknown `languageId`. Unknown language identity is a configuration error and must fail explicitly.

Do not make editor assistance mandatory. Compilation and editor support are separate frontend capabilities.

Do not move frontend semantic ownership into LSP or Studio. The LSP bridge transports frontend-owned editorial results; it does not author language semantics.

Do not reintroduce PBS imports in common LSP code for convenience. If a capability needs PBS-specific state, create or extend a frontend-owned generic boundary and keep the PBS mapping inside `prometeu-frontend-pbs`.

## References

- `DEC-0042` locked the generic frontend editorial language-service contract.
- `PLN-0111` introduced generic frontend editorial DTOs and defaults.
- `PLN-0112` migrated semantic tokens.
- `PLN-0113` migrated completion.
- `PLN-0114` migrated hover and documentation.
- `PLN-0115` migrated signature help.
- `PLN-0116` removed PBS imports from common LSP and added boundary coverage.
- Related lesson: `LSN-0055` Static frontend providers before plugin architecture.
- Related lesson: `LSN-0056` Compile-first frontends with optional editorial capabilities.