prometeu-studio/discussion/workflow/decisions/DEC-0040-frontendprovider-explicito-como-contrato-de-frontend.md

id	ticket	title	status	created	ref_agenda	tags
DEC-0040	multi-frontend-provider-contract	FrontendProvider explicito como contrato de frontend	accepted	2026-07-15	AGD-0057	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.