prometeu-studio/discussion/workflow/decisions/DEC-0041-separate-frontend-compilation-from-editorial-language-services.md

id	ticket	title	status	created	ref_agenda	tags
DEC-0041	multi-frontend-compiler-vs-language-services	Separate frontend compilation from editorial language services	accepted	2026-07-15	AGD-0058	compiler compiler-general studio lsp editor frontend multi-frontend

Context

Prometeu is preparing the compiler and editor stack for multiple frontends. PBS currently provides compilation and rich editor assistance, and existing LSP/Studio paths can still assume that diagnostics, semantic tokens, completion, hover, and signature help are all backed by the PBS frontend implementation.

This decision belongs to domain owner compiler/general.

Touched subdomains:

• studio/lsp
• compiler/pbs

The existing API already points in the right direction: FrontendProvider exposes mandatory compiler behavior through compiler() and optional editor behavior through languageService(). However, the LSP bridge still contains PBS-specific editorial logic, so the boundary needs to be made normative before implementation plans migrate consumers.

This decision resolves AGD-0058.

Decision

Frontend compilation and editorial language services MUST be separate contracts.

Every frontend MUST provide a compiler contract. A frontend MAY provide editorial language services. A frontend that can compile but does not provide completion, hover, definition, signature help, semantic tokens, or other editor assistance MUST still be considered a valid frontend.

FrontendProvider.compiler() is the required frontend capability. It MUST remain sufficient for build, analyze, compile, and backend-facing pipeline flows.

FrontendProvider.languageService() is the optional editorial capability boundary. The absence of a language service MUST NOT prevent compilation, project analysis, or backend execution.

The first common editorial contract SHOULD remain aggregated as FrontendLanguageService plus explicit capabilities, rather than immediately splitting every feature into separate top-level service interfaces. Smaller feature interfaces MAY be introduced later when implementation pressure proves that independent ownership, testing, or lifecycle is needed.

LSP and Studio consumers MUST query editorial capability availability before invoking editor-specific behavior. They MUST NOT assume that a frontend with a compiler also supports completion, hover, definition, semantic tokens, signature help, formatting, rename, code actions, or similar editor features.

When an editorial capability is absent, LSP and Studio MUST degrade gracefully:

• collection-shaped responses SHOULD be empty;
• scalar optional responses SHOULD be absent or use a documented neutral response;
• protocol-level unsupported behavior SHOULD be explicit when the host protocol supports that distinction;
• absence MUST NOT be reported as a compiler failure.

PBS MAY continue to expose the rich editorial behavior it has today. That behavior is a PBS-provided capability, not a requirement imposed on all future frontends.

Compiler diagnostics and editorial diagnostics MUST remain distinct concepts. Build/analyze diagnostics belong to the compiler contract. Editorial diagnostics MAY reuse compiler analysis results, but a frontend MUST NOT be required to provide a separate editor diagnostics service in order to compile.

Semantic presentation metadata, such as frontend-owned semantic token vocabularies and visual themes, remains frontend-owned presentation data. Producing semantic tokens for a live document is an editorial capability and MUST be optional unless a future decision narrows that requirement for a specific host.

The LSP implementation SHOULD migrate from direct PBS editorial calls toward resolving the active frontend provider and consulting its optional language-service capabilities. Until that migration is planned and implemented, PBS-specific bridge code is tolerated as legacy coupling, not as the normative architecture.

Rationale

Multi-frontend support requires a low floor: a new language frontend should be able to join the build pipeline before it has IDE-grade assistance. Requiring all editor features up front would turn frontend adoption into a large all-or-nothing task and would couple compiler correctness to UX completeness.

Keeping the first editorial boundary aggregated avoids premature interface explosion. The codebase already has a marker FrontendLanguageService, while the real uncertainty is how LSP/Studio should discover and handle absent capabilities. Capability negotiation solves that problem without forcing a final taxonomy before there is enough implementation evidence.

Separating compiler diagnostics from editorial diagnostics protects latency and ownership boundaries. Build diagnostics can be produced as part of normal analysis, while editor diagnostics may need live overlays, partial results, cancellation, caching, or host-specific behavior.

PBS should remain the reference rich frontend, but it should not define the minimum contract for all future languages. Treating PBS editor support as optional capability data makes the current implementation useful without freezing PBS assumptions into the common compiler API.

Implications

• Common compiler code MUST depend on the compiler capability, not on PBS-specific frontend services.
• LSP/Studio code that invokes editor behavior MUST handle absent capabilities deterministically.
• Existing PBS editor assistance should be preserved while being moved behind the common optional language-service boundary over time.
• Future frontend tests should include at least one compile-capable frontend with no language service.
• Future LSP/Studio tests should prove that absent capabilities produce empty or unsupported responses rather than build failures.
• Introducing smaller editorial interfaces is allowed later, but only after a plan identifies real feature lifecycle boundaries.
• Plans derived from this decision MUST NOT reinterpret optional editorial services as required for frontend validity.

Propagation Targets

• specs:
  • docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md
  • A future compiler/frontend provider contract spec if one is created.
  • LSP/editor-facing specs if/when a dedicated Studio/LSP spec surface exists.
• plans:
  • Create a plan to specify the frontend provider/editorial capability boundary.
  • Create a plan to migrate LSP/Studio consumers away from direct PBS editorial assumptions.
• code:
  • prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/services/FrontendProvider.java
  • prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/services/FrontendLanguageService.java
  • prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/CompilerLanguageServiceBridge.java
  • PBS frontend editorial support classes.
• tests:
  • Frontend provider tests proving compilation works without a language service.
  • LSP/Studio tests for absent completion, hover, signature help, semantic tokens, and future editorial capabilities.
  • Regression tests proving PBS still exposes current editorial behavior.
• docs:
  • Specs updated by implementation plans.
  • Lessons generated after implementation and housekeeping.

References

• Agenda: AGD-0058
• Source discussion: DSC-0055

Revision Log

• 2026-07-15: Initial decision drafted from accepted AGD-0058.