prometeu-studio/discussion/lessons/DSC-0056-multi-frontend-remove-pbs-branches/LSN-0058-generic-frontend-editorial-contract-for-lsp.md

id	ticket	title	created	tags
LSN-0058	multi-frontend-remove-pbs-branches	Generic Frontend Editorial Contract for LSP	2026-07-15	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:

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.