---
id: DEC-0040
ticket: multi-frontend-provider-contract
title: FrontendProvider explicito como contrato de frontend
status: accepted
created: 2026-07-15
ref_agenda: AGD-0057
tags: [compiler, compiler-general, studio, frontend, registry, multi-frontend]
---

## Context

This decision belongs to domain owner `compiler/general`, with impact on `studio`.

The repository already has `FrontendRegistryService`, `FrontendSpec`, `FrontendPhaseService`, and `languageId` based selection. Those surfaces are enough to keep PBS working, but common compiler and Studio code still has places where PBS-specific classes or assumptions can leak into composition and consumption paths.

The multi-frontend direction requires a stable provider boundary before removing PBS-specific branches from common code. The boundary must make frontend registration explicit without turning the Studio or compiler into a dynamic plugin platform.

This decision resolves `AGD-0057`.

## Decision

The repository MUST introduce an explicit `FrontendProvider` contract as the common frontend registration unit.

`FrontendProvider` MUST expose the following minimum responsibilities:

- `specification()`: returns the frontend specification, including its stable `languageId`;
- `compiler()`: returns the compiler-facing frontend service or phase equivalent used by the build pipeline;
- `languageService()`: returns an optional editor-facing language service capability for Studio consumers.

`languageService()` MUST be optional. A frontend that can compile but does not provide editor services MUST remain a valid provider.

`FrontendRegistryService` MUST resolve providers by `languageId`. The common consumption shape SHOULD become `provider = registry.require(languageId)` or an equivalent explicit lookup that fails clearly for unknown languages.

PBS MUST be registered as the only initial real provider through a `PBSFrontendProvider` or equivalent concrete provider object. This work MUST NOT introduce another real frontend.

Provider registration MUST remain explicit in the application composition root. `prometeu-app/src/main/java/p/studio/AppContainer.java` is the preferred initial composition point for registering the PBS provider.

Common compiler, build pipeline, and Studio code MUST NOT instantiate PBS-specific frontend services directly. In particular, common code MUST NOT directly instantiate `PBSFrontendPhaseService`; it MUST obtain the relevant service through the provider resolved from the registry.

This decision MUST NOT introduce dynamic plugin discovery, reflection-based discovery, classpath scanning, external JAR loading, or runtime plugin installation.

## Rationale

An explicit provider object gives the project one stable unit for frontend identity, compilation, and optional editorial capability. It keeps `languageId` as the selection key while avoiding scattered direct knowledge of PBS in common code.

Keeping the provider small prevents a premature plugin architecture. The immediate goal is static multi-frontend readiness inside the repository, not external extensibility.

Making language services optional separates build correctness from Studio editor assistance. A frontend should be able to participate in compilation without being forced to implement editor features in the same wave.

Using the application composition root for registration keeps ownership clear: composition may know that PBS exists, but shared compiler and Studio consumers should only know the provider contract.

## Implications

- `FrontendRegistryService` will need to evolve from spec/phase lookups into provider lookup, while preserving compatibility during migration where necessary.
- Existing PBS registration must be wrapped behind a provider object.
- Common consumers that currently request `FrontendSpec` or `FrontendPhaseService` directly may be migrated incrementally to provider lookup.
- Studio catalog code may continue listing specifications, but its source should become provider-derived rather than PBS-specific.
- Build pipeline code should obtain compiler-facing frontend behavior from the resolved provider.
- Error handling for unknown `languageId` must remain explicit and diagnostic-friendly.
- No product or runtime behavior should change for PBS as the only registered provider.

## Propagation Targets

- specs:
  - Add or update a `compiler/general` specification for the frontend provider and registry contract.
  - Reference Studio-facing optional language service capability where relevant.
- plans:
  - Create an implementation plan for provider contract introduction, PBS provider registration, consumer migration, and tests.
- code:
  - `prometeu-compiler/prometeu-frontend-registry/src/main/java/p/studio/compiler/FrontendRegistryService.java`
  - PBS frontend module provider implementation.
  - `prometeu-compiler/prometeu-build-pipeline/...` consumers that resolve frontend services.
  - `prometeu-studio/src/main/java/p/studio/projects/ProjectLanguageCatalogService.java`
  - `prometeu-app/src/main/java/p/studio/AppContainer.java`
- tests:
  - Registry resolves a provider by `languageId`.
  - PBS is registered as the only initial real provider.
  - Unknown `languageId` fails with a clear error.
  - Common code can obtain compiler-facing frontend behavior without directly instantiating `PBSFrontendPhaseService`.
- docs:
  - Decision-derived implementation plan.
  - Lessons after implementation and housekeeping, if the completed work produces reusable guidance.

## References

- Agenda: AGD-0057
- Source discussion: DSC-0054

## Revision Log

- 2026-07-15: Initial decision drafted from accepted `AGD-0057`.