From 4574aa17c3a1a4a5afa968265dea0fa1bd574ded Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Sat, 19 Sep 2026 03:44:10 +0100 Subject: [PATCH] implements PLN-0130 Record the multi-frontend simplicity guardrails in an English lesson: static registry is allowed, new abstractions need a real in-repo consumer, and plugin-style infrastructure stays forbidden. Housekeep DSC-0065 with LSN-0067. --- discussion/index.ndjson | 4 +- ...-phase-rejects-premature-infrastructure.md | 167 ++++++++++++++++++ ...i-frontend-avoid-premature-abstractions.md | 77 -------- 3 files changed, 169 insertions(+), 79 deletions(-) create mode 100644 discussion/lessons/DSC-0065-multi-frontend-avoid-premature-abstractions/LSN-0067-multi-frontend-phase-rejects-premature-infrastructure.md delete mode 100644 discussion/workflow/agendas/AGD-0068-multi-frontend-avoid-premature-abstractions.md diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 55bb71a0..adb26d14 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,5 +1,5 @@ -{"type":"meta","next_id":{"DSC":66,"AGD":69,"DEC":51,"PLN":130,"LSN":67,"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":"meta","next_id":{"DSC":66,"AGD":69,"DEC":52,"PLN":131,"LSN":68,"CLSN":1}} +{"type":"discussion","id":"DSC-0065","status":"done","ticket":"multi-frontend-avoid-premature-abstractions","title":"Evitar abstracoes prematuras na preparacao multi-frontend","created_at":"2026-07-15","updated_at":"2026-09-19","tags":["compiler","compiler-general","studio","frontend","architecture","multi-frontend","simplicity"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0067","file":"discussion/lessons/DSC-0065-multi-frontend-avoid-premature-abstractions/LSN-0067-multi-frontend-phase-rejects-premature-infrastructure.md","status":"done","created_at":"2026-09-19","updated_at":"2026-09-19"}]} {"type":"discussion","id":"DSC-0064","status":"done","ticket":"multi-frontend-architectural-tests","title":"Testes arquiteturais para fronteiras multi-frontend","created_at":"2026-07-15","updated_at":"2026-09-19","tags":["compiler","compiler-general","studio","frontend","architecture","tests","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0066","file":"discussion/lessons/DSC-0064-multi-frontend-architectural-tests/LSN-0066-archunit-guards-java-multi-frontend-boundaries.md","status":"done","created_at":"2026-09-19","updated_at":"2026-09-19"}]} {"type":"discussion","id":"DSC-0063","status":"done","ticket":"multi-frontend-synthetic-test-frontend","title":"Frontend sintetico de teste para provar neutralidade do pipeline","created_at":"2026-07-15","updated_at":"2026-09-19","tags":["compiler","compiler-general","frontend","tests","backend","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0065","file":"discussion/lessons/DSC-0063-multi-frontend-synthetic-test-frontend/LSN-0065-synthetic-test-frontend-proves-pipeline-neutrality.md","status":"done","created_at":"2026-09-19","updated_at":"2026-09-19"}]} {"type":"discussion","id":"DSC-0062","status":"done","ticket":"multi-frontend-pvm-neutrality","title":"Neutralidade da PVM e identificacao PBX independente de PBS","created_at":"2026-07-15","updated_at":"2026-09-18","tags":["vm-arch","runtime","pvm","pbx","compiler","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0061","file":"discussion/lessons/DSC-0062-multi-frontend-pvm-neutrality/LSN-0061-pbx-runtime-boundary.md","status":"done","created_at":"2026-09-18","updated_at":"2026-09-18"}]} diff --git a/discussion/lessons/DSC-0065-multi-frontend-avoid-premature-abstractions/LSN-0067-multi-frontend-phase-rejects-premature-infrastructure.md b/discussion/lessons/DSC-0065-multi-frontend-avoid-premature-abstractions/LSN-0067-multi-frontend-phase-rejects-premature-infrastructure.md new file mode 100644 index 00000000..80f65acf --- /dev/null +++ b/discussion/lessons/DSC-0065-multi-frontend-avoid-premature-abstractions/LSN-0067-multi-frontend-phase-rejects-premature-infrastructure.md @@ -0,0 +1,167 @@ +--- +id: LSN-0067 +ticket: multi-frontend-avoid-premature-abstractions +title: Multi-frontend phase rejects premature infrastructure +created: 2026-09-19 +tags: [compiler, compiler-general, studio, frontend, architecture, multi-frontend, simplicity] +--- + +# Multi-frontend phase rejects premature infrastructure + +## Original Problem + +The multi-frontend preparation needed a standing simplicity rule. The original +agenda asked for that rule *before* the other multi-frontend discussions. +Those discussions already closed (DSC-0054 through DSC-0064). The remaining +risk was not a missing plugin platform. + +The remaining risk was twofold: + +1. using "keep it simple" to put PBS construction back into common compiler, + Studio, LSP, or app code; +2. inventing marketplace, JAR loading, RPC, validator-core, or a generic SPI + "for a future language" that does not exist in this repository. + +`FrontendRegistryService` is a static singleton. The original agenda listed +a global service locator as out of scope. Without an explicit exception, a +later change could inject a `Registry` into the pipeline for purity, which +DSC-0063 already refused. + +## Consolidated Decision + +This is standing policy for *future* work in the current phase: PBS as the +only product frontend, `synth` as a test-only provider, frontends in-repo. +It is not an audit of closed discussions and must not rewrite them. + +Durable locks from DEC-0051: + +- Implementation of this discussion is the decision plus this lesson. There + is no new spec, no new ArchUnit rule, and no production refactor. +- Spec 23 §2 and §8.3 remain the discovery MUST NOT surface. Do not copy + those sentences into a new spec. +- Architectural tests stay owned by LSN-0066. + +### Static registry is allowed + +`FrontendRegistryService` as a static singleton, with public `register` and +`unregister` and `bootstrapDefaults()` registering only PBS, is the +composition mechanism of this phase. Treat that as an explicit exception, +not as a banned service locator. + +Discovery must not use `ServiceLoader`, classpath scanning, reflection-based +discovery, an external JAR, or runtime plugin installation. + +Do not inject a `Registry` into the pipeline, LSP, or `AppContainer`. +`AppContainer` is not a PBS composition root. It may call +`FrontendRegistryService.bootstrapDefaults()`. It must not instantiate PBS +types. + +### Real in-repo consumer + +A new interface, module, SPI, generator, or framework is allowed only when +a real in-repo consumer exists. In this phase that consumer is one of: + +- the PBS product frontend; +- the `synth` test frontend; +- a second product frontend accepted by its own decision. + +"For a future language", "for the marketplace", or "when we have plugins" +is not a consumer. + +`FrontendProvider`, `IRBackend`, common lifecycle assembly, and test-only +ArchUnit are not premature. They already have consumers. + +### Forbidden in this phase + +Until a later decision authorizes it with a real consumer, do not introduce: + +1. dynamic frontend discovery (plugin, `ServiceLoader`, scan, external JAR, + runtime install); +2. RPC, sockets, a process supervisor, or version negotiation between + compiler and frontend; +3. a marketplace, hot reload, or frontend sandbox; +4. a validator-core or generic validation framework; +5. an SDK schema/generator or `HOSTCALLS.csv` as canonical ABI (LSN-0064); +6. a product module `frontends/synth`; +7. an injected `Registry`, or `AppContainer` as the PBS composition root. + +This list is not a monorepo-wide simplicity charter. It does not govern +JavaFX, packer, or LSP protocol design. Owner is `compiler/general`, with +impact on `studio` on the multi-frontend axis. + +### Neighbors stay closed + +Do not reinterpret, relax, "simplify", or reimplement: + +- provider/registry (LSN-0055 / spec 23 §8.3); +- common lifecycle; +- console ABI / PBS delivery; +- `synth`; +- ArchUnit / PBS module identity. + +Using this policy to keep `new PBSFrontendPhaseService()` (or equivalent) +in common code is refused. That is PBS recoupling, not simplicity. + +A second product frontend needs its own decision. This lesson neither +replaces that decision nor blocks it. + +## Final Implementation + +No production Java, Gradle, spec, or ArchUnit file changed. + +The map above is the implementation. Future compiler/studio plans on this +axis should cite it when they propose a new module, SPI, or discovery +mechanism. + +Code that already matches the phase: + +- `FrontendProvider` exposes `specification()`, `compiler()`, and optional + `languageService()`; +- `FrontendRegistryService.bootstrapDefaults()` registers PBS only; +- `AppContainer` only calls that bootstrap; +- `synth` lives in build-pipeline test sources; +- ArchUnit lives in `:prometeu-architecture-tests`. + +## Examples + +Good: + +- add a method to `FrontendProvider` because PBS or `synth` cannot compile + or register without it; +- keep `unregister` on the static registry so `synth` tests can clean up; +- reject a proposal to load language JARs from a plugin directory. + +Bad: + +- inject `Registry` into `BuilderPipelineService` because static state looks + like a service locator; +- create `frontends/synth` as a product module; +- add validator-core "so the next language has somewhere to put checks"; +- keep `new PBSFrontendPhaseService()` in pipeline code and call that + simpler than going through the provider. + +## Pitfalls + +- The original agenda order ("before the other agendas") is historical. + Do not reopen DSC-0054..DSC-0064 to satisfy it. +- Static registry plus explicit `register`/`unregister` is visible. Hidden + `ServiceLoader` discovery is not the same thing. +- A second product frontend *is* a real consumer. Do not use this lesson to + refuse that frontend; use it to refuse infrastructure that frontend does + not yet need. +- Spec 23 already forbids plugin discovery. Do not duplicate it. Do not + treat silence in spec 23 as permission for RPC or validator-core. +- Simplicity does not mean PBS may leak into common modules. LSN-0066 still + owns that boundary. + +## References + +- Decision: `DEC-0051` +- Plan: `PLN-0130` +- Related lessons: `LSN-0055`, `LSN-0060`, `LSN-0063`, `LSN-0064`, + `LSN-0065`, `LSN-0066` +- `docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md` + (§2, §8.3) +- `prometeu-compiler/prometeu-frontend-registry/src/main/java/p/studio/compiler/FrontendRegistryService.java` +- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/services/FrontendProvider.java` +- `prometeu-app/src/main/java/p/studio/AppContainer.java` diff --git a/discussion/workflow/agendas/AGD-0068-multi-frontend-avoid-premature-abstractions.md b/discussion/workflow/agendas/AGD-0068-multi-frontend-avoid-premature-abstractions.md deleted file mode 100644 index a7033734..00000000 --- a/discussion/workflow/agendas/AGD-0068-multi-frontend-avoid-premature-abstractions.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -id: AGD-0068 -ticket: multi-frontend-avoid-premature-abstractions -title: Evitar abstracoes prematuras na preparacao multi-frontend -status: open -created: 2026-07-15 -resolved: -decision: -tags: [compiler, compiler-general, studio, frontend, architecture, multi-frontend, simplicity] ---- - -# Agenda - Evitar abstracoes prematuras - -## Objetivo - -Domain owner: `compiler/general`, com impacto em `studio`. - -Definir limites para a preparacao multi-frontend: remover acoplamento com baixo custo sem construir marketplace, hot reload, RPC, sandbox ou infraestrutura generica antes da necessidade real. - -## Contexto atual - -O PBS continuara sendo o unico frontend implementado no curto prazo. O objetivo e preparar contratos, fronteiras e testes de neutralidade, nao criar uma plataforma completa de plugins. - -## Escopo - -- Estabelecer principios para as agendas derivadas. -- Definir o que e explicitamente proibido nesta fase. -- Criar criterio para rejeitar abstracoes sem uso real. - -## Fora de escopo - -- Plugin marketplace. -- Carregamento dinamico de JARs. -- RPC, sockets, process supervisor ou version negotiation complexa. -- Service locator global. - -## Arquivos e componentes a inspecionar - -- `prometeu-compiler/prometeu-frontend-registry/...` -- `prometeu-app/src/main/java/p/studio/AppContainer.java` -- `prometeu-studio/src/main/java/p/studio/...` -- planos futuros derivados das discussions multi-frontend - -## Alteracoes propostas - -Opcao A: registrar esta decisao como guardrail transversal antes das demais. - -Opcao B: deixar cada agenda repetir suas restricoes locais. - -Recomendacao inicial: criar uma decisao curta e transversal apos discussao, para guiar provider, language services, synthetic frontend e testes arquiteturais. - -## Estrategia de implementacao - -Transformar o alinhamento em criterios de review: interface pequena, registro explicito, DI/composicao, records imutaveis e testes; rejeitar infra que nao seja exigida pelo PBS ou pelo frontend sintetico de teste. - -## Testes necessarios - -- Nao ha teste direto para simplicidade, mas plans devem incluir criterio de aceite contra reflection/scanning/RPC quando aplicavel. -- Testes arquiteturais podem proteger contra service locator global ou acoplamentos indevidos. - -## Criterios de aceitacao - -- Plans derivados nao introduzem infraestrutura de plugin antes da necessidade. -- Registro manual do PBS e suficiente. -- O frontend sintetico prova neutralidade sem virar plataforma externa. - -## Riscos - -- Usar "evitar abstracao" como desculpa para manter acoplamento PBS. -- Criar contratos tao pequenos que precisem ser quebrados imediatamente. - -## Decisoes que devem ser registradas - -- Guardrails obrigatorios para esta fase. -- Lista de mecanismos proibidos. -- Criterio para aceitar uma nova abstracao. - -- 2.47.2