diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 3494e7d9..731aace8 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,4 +1,4 @@ -{"type":"meta","next_id":{"DSC":66,"AGD":69,"DEC":41,"PLN":107,"LSN":55,"CLSN":1}} +{"type":"meta","next_id":{"DSC":66,"AGD":69,"DEC":41,"PLN":107,"LSN":56,"CLSN":1}} {"type":"discussion","id":"DSC-0065","status":"open","ticket":"multi-frontend-avoid-premature-abstractions","title":"Evitar abstracoes prematuras na preparacao multi-frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","architecture","multi-frontend","simplicity"],"agendas":[{"id":"AGD-0068","file":"AGD-0068-multi-frontend-avoid-premature-abstractions.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0064","status":"open","ticket":"multi-frontend-architectural-tests","title":"Testes arquiteturais para fronteiras multi-frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","architecture","tests","multi-frontend"],"agendas":[{"id":"AGD-0067","file":"AGD-0067-multi-frontend-architectural-tests.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0063","status":"open","ticket":"multi-frontend-synthetic-test-frontend","title":"Frontend sintetico de teste para provar neutralidade do pipeline","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","frontend","tests","backend","multi-frontend"],"agendas":[{"id":"AGD-0066","file":"AGD-0066-multi-frontend-synthetic-test-frontend.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]} @@ -10,7 +10,7 @@ {"type":"discussion","id":"DSC-0057","status":"open","ticket":"multi-frontend-frontend-backend-contract","title":"Estabilizar contrato entre frontend e backend comum","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","compiler-pbs","ir","backend","multi-frontend"],"agendas":[{"id":"AGD-0060","file":"AGD-0060-multi-frontend-frontend-backend-contract.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0056","status":"open","ticket":"multi-frontend-remove-pbs-branches","title":"Remover verificacoes explicitas de PBS do codigo comum","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","compiler-pbs","studio","frontend","coupling","multi-frontend"],"agendas":[{"id":"AGD-0059","file":"AGD-0059-multi-frontend-remove-pbs-branches.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0055","status":"open","ticket":"multi-frontend-compiler-vs-language-services","title":"Separar compilacao de servicos editoriais de frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","lsp","editor","frontend","multi-frontend"],"agendas":[{"id":"AGD-0058","file":"AGD-0058-multi-frontend-compiler-vs-language-services.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]} -{"type":"discussion","id":"DSC-0054","status":"in_progress","ticket":"multi-frontend-provider-contract","title":"Introduzir provider completo de frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","registry","multi-frontend"],"agendas":[{"id":"AGD-0057","file":"AGD-0057-multi-frontend-provider-contract.md","status":"accepted","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[{"id":"DEC-0040","file":"DEC-0040-frontendprovider-explicito-como-contrato-de-frontend.md","status":"accepted","created_at":"2026-07-15","updated_at":"2026-07-15","ref_agenda":"AGD-0057"}],"plans":[{"id":"PLN-0103","file":"PLN-0103-specify-frontend-provider-and-registry-contract.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0040"]},{"id":"PLN-0104","file":"PLN-0104-introduce-frontendprovider-registry-api.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0040"]},{"id":"PLN-0105","file":"PLN-0105-wrap-pbs-frontend-as-explicit-provider.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0040"]},{"id":"PLN-0106","file":"PLN-0106-migrate-common-consumers-to-provider-lookup.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0040"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0054","status":"done","ticket":"multi-frontend-provider-contract","title":"Introduzir provider completo de frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","registry","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0055","file":"discussion/lessons/DSC-0054-multi-frontend-provider-contract/LSN-0055-static-frontend-providers-before-plugin-architecture.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]} {"type":"discussion","id":"DSC-0053","status":"open","ticket":"pbs-lsp-call-and-type-hierarchy","title":"PBS LSP Call and Type Hierarchy","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","call-hierarchy","type-hierarchy"],"agendas":[{"id":"AGD-0056","file":"AGD-0056-pbs-lsp-call-and-type-hierarchy.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0052","status":"open","ticket":"pbs-lsp-document-links","title":"PBS LSP Document Links","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","document-links","imports"],"agendas":[{"id":"AGD-0055","file":"AGD-0055-pbs-lsp-document-links.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0051","status":"open","ticket":"pbs-lsp-diagnostics-ux","title":"PBS LSP Diagnostics UX","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","diagnostics","ux"],"agendas":[{"id":"AGD-0054","file":"AGD-0054-pbs-lsp-diagnostics-ux.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]} diff --git a/discussion/lessons/DSC-0054-multi-frontend-provider-contract/LSN-0055-static-frontend-providers-before-plugin-architecture.md b/discussion/lessons/DSC-0054-multi-frontend-provider-contract/LSN-0055-static-frontend-providers-before-plugin-architecture.md new file mode 100644 index 00000000..9958d468 --- /dev/null +++ b/discussion/lessons/DSC-0054-multi-frontend-provider-contract/LSN-0055-static-frontend-providers-before-plugin-architecture.md @@ -0,0 +1,74 @@ +--- +id: LSN-0055 +ticket: multi-frontend-provider-contract +title: Static frontend providers before plugin architecture +created: 2026-07-15 +tags: [compiler, compiler-general, studio, frontend, registry, multi-frontend] +--- + +## Context + +Prometeu needed a multi-frontend boundary without turning the compiler or Studio into a dynamic plugin platform. Before this work, shared code could ask the registry for frontend specs or phase services, and PBS was registered directly as the default language. That worked for a single frontend, but it made the next frontend harder because common code could still depend on PBS-specific construction details. + +The durable ownership rule is now: common compiler and Studio code select a frontend by `languageId`, then consume a provider contract. PBS remains the first and only real provider, but it is no longer the shape of the shared abstraction. + +## Key Decisions + +### `FrontendProvider` is the common registration unit + +**What:** Each registered frontend is represented by a `FrontendProvider` with: + +- `specification()`, for the static frontend contract and `languageId`; +- `compiler()`, for compiler-facing frontend execution; +- `languageService()`, as an optional editor-facing capability. + +**Why:** This groups the frontend identity, compiler entrypoint, and optional tooling capability without forcing every frontend to implement Studio/editor services. + +**Trade-offs:** The provider is intentionally small. It does not solve dynamic discovery, plugin installation, external loading, or all future language-service APIs. Those are separate architectural decisions. + +### Registration is explicit + +**What:** Frontend registration is static and composition-root-owned. The application composition path bootstraps the default provider set, and the registry resolves providers by `languageId`. + +**Why:** Explicit registration keeps dependencies visible and testable. It lets composition know about PBS while preventing common compiler and Studio consumers from directly constructing PBS services. + +**Trade-offs:** Adding a new in-repository frontend still requires a code change in composition. That is acceptable because this decision optimizes for repository-internal multi-frontend readiness, not external plugin extensibility. + +### PBS is a provider, not the shared model + +**What:** PBS is wrapped by `PBSFrontendProvider`. Shared build and Studio consumers obtain frontend behavior through `FrontendRegistryService.require(languageId)` or provider-derived listings. + +**Why:** PBS remains the correctness baseline, but it must not become the exclusive owner of compiler pipeline semantics. + +**Trade-offs:** PBS-specific tests may still instantiate `PBSFrontendPhaseService` directly because they test PBS internals. Common modules should not. + +## Patterns and Algorithms + +Use this path for common compiler execution: + +1. Resolve the project language from the manifest or default provider. +2. Resolve `FrontendProvider` by `languageId`. +3. Use `provider.specification()` for static metadata. +4. Use `provider.compiler()` for frontend compilation. +5. Use `provider.languageService()` only when a tooling consumer needs optional editor services. + +Use this path for Studio language catalogs: + +1. List providers from the registry. +2. Derive templates from `provider.specification()`. +3. Do not hardcode PBS templates in Studio catalog code. + +## Pitfalls + +- Do not add reflection, classpath scanning, external JAR loading, or runtime plugin installation to solve repository-internal frontend registration. +- Do not make `languageService()` mandatory. Compilation and editor assistance are separate capabilities. +- Do not instantiate `PBSFrontendPhaseService` from common build, dependency, Studio, or app code. +- Do not use PBS as a fallback for unknown `languageId`. Unknown languages must fail explicitly. +- Do not move frontend semantic ownership into Studio just because Studio consumes provider metadata. + +## Takeaways + +- Static providers are enough to prepare for multiple in-repository frontends. +- The registry boundary is provider-based, not PBS-based. +- Composition may know which frontends exist; common consumers should only know `FrontendProvider`. +- Optional editor capabilities keep compiler readiness independent from Studio feature depth. diff --git a/discussion/workflow/agendas/AGD-0057-multi-frontend-provider-contract.md b/discussion/workflow/agendas/AGD-0057-multi-frontend-provider-contract.md deleted file mode 100644 index dbb0267f..00000000 --- a/discussion/workflow/agendas/AGD-0057-multi-frontend-provider-contract.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -id: AGD-0057 -ticket: multi-frontend-provider-contract -title: Introduzir provider completo de frontend -status: accepted -created: 2026-07-15 -resolved: -decision: -tags: [compiler, compiler-general, studio, frontend, registry, multi-frontend] ---- - -# Agenda - Introduzir provider completo de frontend - -## Objetivo - -Domain owner: `compiler/general`, com impacto em `studio`. - -Discutir como consolidar um contrato de `FrontendProvider` que agrupe especificacao, compilador e servicos editoriais opcionais sem transformar o Studio em uma plataforma de plugins. - -## Contexto atual - -O repositorio ja possui `prometeu-compiler/prometeu-frontend-registry/src/main/java/p/studio/compiler/FrontendRegistryService.java` e superficies relacionadas a `FrontendSpec`, `FrontendPhaseService` e `languageId`. Ainda ha sinais de registro ou uso direto do PBS em composition roots e chamadas comuns. - -## Escopo - -- Inspecionar o registry atual e seus consumidores. -- Definir se `FrontendProvider` deve ser novo contrato ou evolucao de contrato existente. -- Planejar `PBSFrontendProvider` como unico provider inicial. -- Preservar selecao atual por `languageId`. - -## Fora de escopo - -- Descoberta dinamica de plugins. -- Reflection, classpath scanning ou carregamento externo de JARs. -- Implementar qualquer frontend real alem do PBS. - -## Arquivos e componentes a inspecionar - -- `prometeu-compiler/prometeu-frontend-registry/src/main/java/p/studio/compiler/FrontendRegistryService.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/...` -- `prometeu-compiler/prometeu-build-pipeline/...` -- `prometeu-studio/src/main/java/p/studio/projects/ProjectLanguageCatalogService.java` -- `prometeu-app/src/main/java/p/studio/AppContainer.java` - -## Alteracoes propostas - -Opcao A: criar `FrontendProvider` explicito com `specification()`, `compiler()` e `languageService()` opcional. - -Opcao B: evoluir o registry para devolver um objeto existente que ja represente provider, adicionando apenas os campos faltantes. - -Recomendacao inicial: preferir a menor mudanca que faca o codigo comum resolver `provider = registry.require(languageId)` e pare de conhecer classes PBS fora do composition root. - -## Estrategia de implementacao - -Comecar por uma auditoria de chamadas atuais ao registry e de instanciacoes diretas do PBS. Introduzir o contrato sem remover APIs antigas no mesmo passo, migrar PBS para o contrato e so entao substituir consumidores comuns. - -## Testes necessarios - -- Teste do registry exigindo resolucao por `languageId`. -- Teste de registro unico do PBS como provider inicial. -- Teste de erro claro para `languageId` desconhecido. - -## Criterios de aceitacao - -- O codigo comum consulta o provider, nao instancia `PBSFrontendPhaseService`. -- PBS permanece funcional. -- Nenhum frontend real novo e criado. - -## Riscos - -- Criar uma abstracao grande demais antes de mapear os consumidores reais. -- Misturar contrato de build com contrato editorial. - -## Decisoes que devem ser registradas - -- Nome final do contrato. -- Responsabilidades minimas do provider. -- Onde fica o composition root autorizado a registrar PBS. - -## Resolucao aceita - -O contrato deve ser introduzido como `FrontendProvider`. - -Responsabilidades minimas: - -- expor a especificacao do frontend por `specification()`; -- expor o compilador ou fase de compilacao equivalente por `compiler()`; -- expor servicos editoriais por `languageService()` somente como capacidade opcional, quando necessaria para o Studio. - -O contrato nao deve incluir descoberta dinamica de plugins, reflection, classpath scanning ou carregamento externo de JARs. - -O registro inicial deve continuar explicito no composition root da aplicacao, com `prometeu-app/src/main/java/p/studio/AppContainer.java` como ponto preferencial de composicao. Codigo comum deve consumir o provider via `registry.require(languageId)` e nao deve instanciar diretamente classes PBS, incluindo `PBSFrontendPhaseService`. - -PBS permanece o unico provider inicial. Nenhum frontend real novo deve ser criado por esta frente. diff --git a/discussion/workflow/decisions/DEC-0040-frontendprovider-explicito-como-contrato-de-frontend.md b/discussion/workflow/decisions/DEC-0040-frontendprovider-explicito-como-contrato-de-frontend.md deleted file mode 100644 index b9782807..00000000 --- a/discussion/workflow/decisions/DEC-0040-frontendprovider-explicito-como-contrato-de-frontend.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -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`. diff --git a/discussion/workflow/plans/PLN-0103-specify-frontend-provider-and-registry-contract.md b/discussion/workflow/plans/PLN-0103-specify-frontend-provider-and-registry-contract.md deleted file mode 100644 index e16d4b3c..00000000 --- a/discussion/workflow/plans/PLN-0103-specify-frontend-provider-and-registry-contract.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -id: PLN-0103 -ticket: multi-frontend-provider-contract -title: Specify frontend provider and registry contract -status: done -created: 2026-07-15 -ref_decisions: [DEC-0040] -tags: [compiler, compiler-general, studio, frontend, registry, multi-frontend] ---- - -## Briefing - -DEC-0040 locks an explicit `FrontendProvider` contract as the common frontend registration unit. The first implementation step is to make that contract normative in the compiler/general specs before changing code. - -Domain owner: `compiler/general`, with impact on `studio`. - -## Objective - -Specify the frontend provider and registry contract so implementation can introduce the API without relying on implicit behavior or PBS-specific assumptions. - -## Dependencies - -- Accepted decision: `DEC-0040`. -- Existing compiler specs under `docs/specs/compiler/`. -- Existing Studio/editor references may be linked but must not become the owner of the contract. - -## Scope - -- Add or update a compiler/general spec section defining `FrontendProvider`. -- Define required provider responsibilities: - - `specification()`; - - `compiler()`; - - optional `languageService()`. -- Define `languageId` as the registry lookup key. -- Define explicit provider registration as the only supported v1 registration model. -- Define PBS as the only initial real provider. -- Define unknown-language failure behavior as explicit and diagnostic-friendly. -- Define that common code must obtain compiler-facing frontend behavior through provider lookup. - -## Non-Goals - -- Do not specify dynamic plugin discovery. -- Do not specify reflection, classpath scanning, external JAR loading, or runtime plugin installation. -- Do not introduce a second real frontend. -- Do not define the full Studio language-service API beyond optional provider capability. - -## Execution Method - -1. Inspect existing compiler/general spec organization and choose the nearest owner document for registry and frontend composition. -2. Add a `FrontendProvider` section with normative `MUST` language for required and optional responsibilities. -3. Add a registry section stating that providers are resolved by `languageId` and that unknown languages fail clearly. -4. Add a registration section stating that provider registration is explicit and composition-root-owned. -5. Add a PBS v1 section stating that PBS is the only initial real provider and no new frontend is introduced by this work. -6. Cross-reference Studio only as an optional language-service consumer, not as the owner of the provider contract. - -## Acceptance Criteria - -- A compiler/general spec defines `FrontendProvider`, registry lookup, explicit registration, and PBS-only initial provider status. -- The spec prohibits plugin discovery, reflection discovery, scanning, external JAR loading, and runtime plugin installation for this decision. -- The spec makes `languageService()` optional and does not require editor support for a compilable frontend. -- The spec is written in English. - -## Tests - -- Documentation validation through review against `DEC-0040`. -- No code tests are required in this plan. - -## Affected Artifacts - -- `docs/specs/compiler/...` -- `discussion/workflow/decisions/DEC-0040-frontendprovider-explicito-como-contrato-de-frontend.md` diff --git a/discussion/workflow/plans/PLN-0104-introduce-frontendprovider-registry-api.md b/discussion/workflow/plans/PLN-0104-introduce-frontendprovider-registry-api.md deleted file mode 100644 index c0a65a12..00000000 --- a/discussion/workflow/plans/PLN-0104-introduce-frontendprovider-registry-api.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -id: PLN-0104 -ticket: multi-frontend-provider-contract -title: Introduce FrontendProvider registry API -status: done -created: 2026-07-15 -ref_decisions: [DEC-0040] -tags: [compiler, compiler-general, studio, frontend, registry, multi-frontend] ---- - -## Briefing - -DEC-0040 requires common code to resolve frontend behavior through a provider. This plan introduces the API surface in the frontend registry without forcing all consumers to migrate in the same change. - -Domain owner: `compiler/general`. - -## Objective - -Introduce `FrontendProvider` and provider-based registry lookup while preserving existing PBS behavior during migration. - -## Dependencies - -- `PLN-0103` should define the normative spec first. -- Accepted decision: `DEC-0040`. -- Existing registry module: `prometeu-compiler/prometeu-frontend-registry`. - -## Scope - -- Add the `FrontendProvider` contract in the frontend registry module. -- Add an optional language-service return shape, using an existing interface if one already exists or a minimal neutral placeholder only if required. -- Add provider registration and provider lookup by `languageId`. -- Add `require(languageId)` or equivalent explicit lookup that fails clearly for unknown languages. -- Preserve compatibility methods during migration if existing consumers still call spec or phase lookup. - -## Non-Goals - -- Do not register PBS in this plan unless needed for API tests with a simple fixture. -- Do not migrate build pipeline or Studio consumers in this plan. -- Do not add plugin discovery, reflection, scanning, external JAR loading, or runtime plugin installation. -- Do not define a broad editor API. - -## Execution Method - -1. Inspect `FrontendRegistryService`, `FrontendSpec`, and `FrontendPhaseService` to confirm current method names and package ownership. -2. Add `FrontendProvider` to the registry-facing package with `specification()`, `compiler()`, and optional `languageService()`. -3. Update `FrontendRegistryService` so its primary storage is provider keyed by `languageId`. -4. Add `require(languageId)` or the nearest local naming equivalent for provider lookup. -5. Keep old spec/phase accessor methods as provider-derived compatibility wrappers if they are still used. -6. Add registry unit tests for provider registration, provider lookup, duplicate language handling if currently supported, and unknown-language errors. - -## Acceptance Criteria - -- `FrontendProvider` exists and exposes all responsibilities required by `DEC-0040`. -- `FrontendRegistryService` can resolve a provider by `languageId`. -- Unknown `languageId` lookup fails with a clear exception or diagnostic message. -- Existing callers can still compile until their migration plan runs. - -## Tests - -- Registry test: registered provider is returned by `languageId`. -- Registry test: unknown `languageId` fails clearly. -- Registry test: provider-derived spec listing remains correct if compatibility methods remain. -- Run the relevant Gradle test task for `prometeu-frontend-registry`. - -## Affected Artifacts - -- `prometeu-compiler/prometeu-frontend-registry/src/main/java/p/studio/compiler/FrontendRegistryService.java` -- New `FrontendProvider` contract in the same registry API surface. -- Registry tests under `prometeu-compiler/prometeu-frontend-registry/src/test/...` diff --git a/discussion/workflow/plans/PLN-0105-wrap-pbs-frontend-as-explicit-provider.md b/discussion/workflow/plans/PLN-0105-wrap-pbs-frontend-as-explicit-provider.md deleted file mode 100644 index 2d2b024b..00000000 --- a/discussion/workflow/plans/PLN-0105-wrap-pbs-frontend-as-explicit-provider.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -id: PLN-0105 -ticket: multi-frontend-provider-contract -title: Wrap PBS frontend as explicit provider -status: done -created: 2026-07-15 -ref_decisions: [DEC-0040] -tags: [compiler, compiler-general, studio, frontend, registry, multi-frontend] ---- - -## Briefing - -DEC-0040 requires PBS to become the only initial real provider behind the new `FrontendProvider` contract. This plan wraps existing PBS frontend behavior without changing PBS product behavior. - -Domain owner: `compiler/general`, with implementation in `compiler/pbs` and composition impact in `prometeu-app`. - -## Objective - -Create and register an explicit PBS provider through the application composition root. - -## Dependencies - -- `PLN-0104` must introduce `FrontendProvider` and provider lookup first. -- Accepted decision: `DEC-0040`. -- Existing PBS frontend phase/service implementation. -- Application composition root in `prometeu-app`. - -## Scope - -- Add `PBSFrontendProvider` or equivalent concrete provider object. -- Make the provider return the existing PBS `FrontendSpec`. -- Make the provider return the existing PBS compiler-facing service or phase. -- Return no language service, or the existing PBS language-service adapter only if already present and compatible. -- Register PBS explicitly in `prometeu-app/src/main/java/p/studio/AppContainer.java` or the nearest current application composition point. -- Ensure PBS remains the only initial real provider. - -## Non-Goals - -- Do not create another real frontend. -- Do not change PBS parsing, semantics, lowering, or runtime output. -- Do not migrate all common consumers in this plan. -- Do not introduce dynamic provider discovery. - -## Execution Method - -1. Inspect PBS frontend module boundaries and locate the current `FrontendSpec` and `FrontendPhaseService` construction. -2. Add `PBSFrontendProvider` in the PBS frontend module or an existing integration package that can legally depend on PBS. -3. Implement `specification()` and `compiler()` by delegating to the existing PBS objects. -4. Implement `languageService()` as empty unless a current Studio-compatible PBS language service already exists. -5. Update `AppContainer` or the existing composition root to register the PBS provider explicitly with `FrontendRegistryService`. -6. Remove direct PBS registration paths that duplicate the provider registration if they become redundant. -7. Add tests proving only PBS is registered as the real provider in the default composition path. - -## Acceptance Criteria - -- PBS is represented by a concrete provider object. -- Default application composition registers PBS explicitly as a provider. -- PBS remains functional through existing compile/build flows. -- No additional real frontend is introduced. -- No dynamic discovery mechanism is added. - -## Tests - -- Provider test: `PBSFrontendProvider.specification()` returns the PBS language id. -- Provider test: `PBSFrontendProvider.compiler()` returns working compiler-facing behavior. -- Composition test: default registry contains PBS as the only real provider. -- Existing PBS compile/build tests continue to pass. - -## Affected Artifacts - -- PBS frontend module under `prometeu-compiler/frontends/prometeu-frontend-pbs/...` -- `prometeu-app/src/main/java/p/studio/AppContainer.java` -- Registry or application composition tests. diff --git a/discussion/workflow/plans/PLN-0106-migrate-common-consumers-to-provider-lookup.md b/discussion/workflow/plans/PLN-0106-migrate-common-consumers-to-provider-lookup.md deleted file mode 100644 index a1400a7a..00000000 --- a/discussion/workflow/plans/PLN-0106-migrate-common-consumers-to-provider-lookup.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -id: PLN-0106 -ticket: multi-frontend-provider-contract -title: Migrate common consumers to provider lookup -status: done -created: 2026-07-15 -ref_decisions: [DEC-0040] -tags: [compiler, compiler-general, studio, frontend, registry, multi-frontend] ---- - -## Briefing - -DEC-0040 forbids common compiler, build pipeline, and Studio code from directly instantiating PBS-specific frontend services. After the registry API and PBS provider exist, consumers must move to provider lookup. - -Domain owner: `compiler/general`, with impact on `studio`. - -## Objective - -Migrate common consumers from direct spec/phase/PBS access to provider-based lookup by `languageId`. - -## Dependencies - -- `PLN-0104` must provide provider lookup. -- `PLN-0105` must register PBS as a provider. -- Accepted decision: `DEC-0040`. - -## Scope - -- Audit common compiler, build pipeline, Studio, and app code for direct PBS frontend service construction. -- Replace common code service lookup with provider lookup. -- Make build pipeline frontend execution obtain compiler-facing behavior from `provider.compiler()`. -- Make Studio project language catalog list specifications from providers. -- Keep PBS-specific construction inside PBS provider or composition root only. -- Add or update tests that prove common code does not directly instantiate `PBSFrontendPhaseService`. - -## Non-Goals - -- Do not remove compatibility registry APIs unless all callers have migrated and the removal is local. -- Do not introduce new frontend behavior. -- Do not change backend IR, validation boundaries, or lifecycle semantics beyond provider lookup. -- Do not implement optional Studio language services that do not already exist. - -## Execution Method - -1. Search for `PBSFrontendPhaseService`, PBS frontend constructors, `getFrontendPhaseService`, and `getFrontendSpec` usage outside PBS and composition-owned code. -2. Classify each usage as composition-owned, PBS-owned, or common consumer. -3. Update common consumers to resolve `FrontendProvider` by `languageId`. -4. Update `FrontendPhasePipelineStage` so it calls provider compiler behavior rather than direct phase lookup. -5. Update `ProjectLanguageCatalogService` so its catalog is provider-derived. -6. Keep compatibility wrappers only where they reduce migration risk and are provider-derived. -7. Add architectural tests or focused unit tests that fail if common modules instantiate `PBSFrontendPhaseService` directly. -8. Run relevant compiler, build pipeline, Studio, and app tests. - -## Acceptance Criteria - -- Common compiler/build pipeline/Studio code obtains frontend behavior through provider lookup. -- Direct `PBSFrontendPhaseService` instantiation remains only in PBS provider or approved composition code. -- `ProjectLanguageCatalogService` is provider-derived. -- Unknown `languageId` failures remain clear after consumer migration. -- PBS compile/build behavior remains unchanged. - -## Tests - -- Unit or integration test: build pipeline resolves PBS through provider and compiles an existing PBS fixture. -- Unit test: Studio language catalog lists PBS from provider specs. -- Architecture test or grep-backed test: common modules do not instantiate `PBSFrontendPhaseService`. -- Existing PBS and build pipeline tests pass. - -## Affected Artifacts - -- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/FrontendPhasePipelineStage.java` -- `prometeu-studio/src/main/java/p/studio/projects/ProjectLanguageCatalogService.java` -- Common code currently using `FrontendRegistryService.getFrontendSpec` or `getFrontendPhaseService`. -- Tests in compiler, build pipeline, Studio, and app modules.