This commit is contained in:
2026-03-24 13:42:37 +00:00
parent b33dc7c18d
commit e0f1d74204
112 changed files with 0 additions and 0 deletions
+197
View File
@@ -0,0 +1,197 @@
# PBS Frontend PR Sequence
Este indice organiza uma sequencia de PRs atomicas para levar `frontends/pbs` ao contrato das specs.
1. `PR-001-pbs-lexer-core-syntax-alignment.md`
2. `PR-002-pbs-ast-contract-v1.md`
3. `PR-003-pbs-parser-declarations-and-types.md`
4. `PR-004-pbs-parser-statements-and-control-flow.md`
5. `PR-005-pbs-parser-expressions-optional-result-apply.md`
6. `PR-006-pbs-barrel-and-module-visibility.md`
7. `PR-006.2-pbs-parser-ast-syntax-hardening.md`
8. `PR-006.3-pbs-syntax-completeness-and-module-hygiene.md`
9. `PR-007-pbs-static-semantics-declaration-validation.md`
10. `PR-008-pbs-static-semantics-call-resolution-and-flow.md`
11. `PR-009-pbs-diagnostics-contract-v1.md`
12. `PR-010-pbs-irbackend-lowering-contract.md`
13. `PR-011-pbs-gate-u-conformance-fixtures.md`
Cada documento e auto contido e inclui: `Briefing`, `Target`, `Method`, `Acceptance Criteria` e `Tests`.
## Non-Conformance Remediation PRs
14. `PR-012-pbs-byte-offset-spans.md`
15. `PR-013-pbs-import-unresolved-diagnostics.md`
16. `PR-014-pbs-switch-wildcard-rules.md`
17. `PR-015-pbs-this-self-context-validation.md`
18. `PR-016-pbs-assignment-target-and-field-access-semantics.md`
19. `PR-017-pbs-const-evaluation-and-dependency-rules.md`
20. `PR-018-pbs-result-flow-ok-err-handle-rules.md`
21. `PR-019-pbs-non-unit-fallthrough-diagnostics.md`
22. `PR-020-pbs-lowering-admission-gates.md`
23. `PR-021-pbs-handle-aware-fallthrough-completion.md`
24. `PR-022-pbs-source-kind-and-module-origin-pipeline.md`
25. `PR-023-pbs-stdlib-environment-resolver-and-loader.md`
26. `PR-024-pbs-parser-ast-interface-module-mode.md`
27. `PR-025-pbs-interface-module-semantics-and-linking.md`
28. `PR-026-pbs-sdk-minimal-core-color-and-gfx.md`
29. `PR-027-pbs-builtin-metadata-extraction-and-ir-lowering-admission.md`
30. `PR-028-pbs-gate-u-sdk-interface-module-fixtures.md`
31. `PR-029-pbs-builtin-slot-inference-and-layout-semantics.md`
32. `PR-030-pbs-host-admission-capability-gating.md`
33. `PR-031-pbs-dependency-scoped-fail-fast-admission.md`
## Backend VM Pipeline PR Sequence (Agenda 18)
Esta sequencia organiza implementacao atomica para `IRBackend -> IRVM -> OptimizeIRVM -> EmitBytecode`, com trilha de montagem do output para o input (bytecode ate IRBackend).
34. `PR-032-backend-bytecode-module-serializer-baseline.md`
35. `PR-033-backend-bytecode-function-layout-and-debug-minimum.md`
36. `PR-034-backend-emitter-hostcall-sysc-contract.md`
37. `PR-035-backend-emit-stage-pipeline-wiring.md`
38. `PR-036-backend-irvm-core-model-and-validator.md`
39. `PR-037-backend-optimize-irvm-noop-stage-and-guards.md`
40. `PR-038-irbackend-v2-executable-contract-model.md`
41. `PR-039-pbs-frontend-irbackend-v2-lowering.md`
42. `PR-040-backend-lower-to-irvm-stage-implementation.md`
43. `PR-041-backend-gate-i-runtime-compat-integration-fixtures.md`
## JVM-Grade Remediation Waves (Execution Plan)
Esta trilha organiza as PRs por ondas para execucao incremental com rollback simples por item.
### Onda O1 - Conformance and Correctness Hardening
1. `PR-O1.1-backend-diagnostics-taxonomy-and-attribution.md`
2. `PR-O1.2-irbackend-executable-contract-hardening.md`
3. `PR-O1.3-pbs-executable-lowering-fidelity.md`
4. `PR-O1.4-lower-to-irvm-callsite-prechecks.md`
5. `PR-O1.5-bytecode-debug-minimum-completeness.md`
6. `PR-O1.6-gate-su-safety-matrix-completion.md`
### Onda O2 - JVM-Inspired Verification and Linking Boundaries
1. `PR-O2.1-bytecode-link-precheck-stage.md`
2. `PR-O2.2-bytecode-preload-verifier.md`
3. `PR-O2.3-optimize-irvm-pass-manager-and-equivalence.md`
4. `PR-O2.4-gate-i-runtime-backed-compat-harness.md`
### Onda O3 - Evolution and Scale
1. `PR-O3.1-irvm-control-flow-lowering-label-resolution.md`
2. `PR-O3.2-bytecode-constpool-symbol-interning-determinism.md`
3. `PR-O3.3-irvm-profile-evolution-and-feature-gates.md`
### Onda O4 - JVM-Grade Uplift
1. `PR-O4.1-callable-signature-identity-and-dense-symbol-table.md`
2. `PR-O4.2-global-intrinsic-table-and-reindexing.md`
3. `PR-O4.3-semantic-lowering-cfg-and-stack-analysis.md`
4. `PR-O4.4-irvm-program-single-source-of-truth.md`
5. `PR-O4.5-vm-profile-end-to-end-pipeline.md`
6. `PR-O4.6-strict-bytecode-precheck-unknown-opcode-rejection.md`
7. `PR-O4.7-gate-i-runtime-backed-execution-adapter.md`
8. `PR-O4.8-jvm-grade-regression-matrix-and-golden-artifacts.md`
### Onda O5.0 - Dense Table Identity Foundation (Pre-O5)
1. `PR-05.0.1-frontend-phase-shared-name-table-context.md`
2. `PR-05.0.2-module-identity-dense-table-and-moduleid-wiring.md`
3. `PR-05.0.3-irbackend-typed-callable-and-intrinsic-ids.md`
4. `PR-05.0.4-callable-shape-and-signature-interning.md`
5. `PR-05.0.5-synthetic-stdlib-fileid-via-filetable.md`
6. `PR-05.0.6-host-binding-key-interning-and-capability-identity.md`
### Onda O5 - JVM-Grade Score Evolution (5.6 -> 8.5+)
Prerequisito de execucao: concluir a Onda O5.0.
1. `PR-05.1-pbs-frontend-semantic-executable-lowering-cfg.md`
2. `PR-05.2-irbackend-callsite-classification-by-semantic-identity.md`
3. `PR-05.3-irvm-deterministic-function-id-and-entrypoint-policy.md`
4. `PR-05.4-irvm-program-coherence-without-bypass.md`
5. `PR-05.5-irvm-validator-real-stack-effects-hostcall-intrinsic.md`
6. `PR-05.6-optimize-irvm-real-deterministic-passes.md`
7. `PR-05.7-gate-i-runtime-backed-mandatory-in-ci.md`
8. `PR-05.8-backend-spec-to-test-conformance-matrix.md`
### Onda O6 - JVM-Grade Score Evolution (8.0 -> 9.0+)
Foco: fechar `partial/deferred` relevantes da matriz normativa e endurecer evidencia de conformidade.
1. `PR-06.1-source-attribution-and-diagnostics-evidence-hardening.md`
2. `PR-06.2-optimize-irvm-semantic-equivalence-harness.md`
3. `PR-06.3-irvm-ext-contract-and-elimination-fixtures.md`
4. `PR-06.4-gate-i-runtime-line-repeatability-ci.md`
5. `PR-06.5-conformance-matrix-hard-gate-policy.md`
6. `PR-06.6-spawn-yield-v1-or-claim-rescope.md`
### Onda O7 - Partial Closure Before IDE Focus
Foco: eliminar os dois `partial` remanescentes na matriz backend antes de mover foco principal para IDE.
1. `PR-07.1-optimize-irvm-span-source-hook-preservation.md`
2. `PR-07.2-pbs-callsite-category-no-textual-heuristics-regression.md`
3. `PR-07.3-irvm-entrypoint-export-emission-for-runtime-loader.md`
### Onda O8 - Canonical Identity and Dense Addressing Hardening
Foco: fechar lacunas estruturais em identidade canonica de intrinsic/modulo/entrypoint e remover riscos de ambiguidade no handoff FE->BE.
1. `PR-08.1-intrinsic-resolution-canonical-identity-keying.md`
2. `PR-08.2-irbackend-moduleid-contract-and-modulepool.md`
3. `PR-08.3-qualified-entrypoint-identity-contract.md`
4. `PR-08.4-call-func-callee-module-identity-correctness.md`
5. `PR-08.5-intrinsic-registry-single-source-sync-with-runtime.md`
### Onda O9 - ModuleId-Only Contract Cutover
Foco: remover definitivamente `moduleKey` textual do contrato estrutural FE->BE, endurecer entrypoint qualificado e alinhar specs/matriz com o modelo `ModuleId`-only.
1. `PR-09.1-irbackend-modulekey-hard-removal-from-contract.md`
2. `PR-09.2-pbs-frontend-moduleid-only-lowering-and-import-surfaces.md`
3. `PR-09.3-lower-to-irvm-moduleid-only-ordering-and-strict-qualified-entrypoint.md`
4. `PR-09.4-specs-refresh-moduleid-only-entrypointref-and-bytecode-alignment.md`
5. `PR-09.5-hard-gates-no-modulekey-regression-and-migration-cleanup.md`
6. `PR-09.6-isa-intrinsic-registry-single-source-artifact.md`
7. `PR-09.7-compiler-normalization-to-isa-registry-artifact.md`
### Onda O10 - Parser Maintainability Refactor (No Functional Change)
Foco: reduzir complexidade estrutural de `PbsParser` sem alterar gramatica, AST, spans ou contrato de diagnosticos observavel.
1. `PR-10.1-pbs-parser-shared-context-and-safe-delegation.md`
2. `PR-10.2-pbs-parser-attribute-and-type-subparsers.md`
3. `PR-10.3-pbs-parser-top-level-declaration-decomposition.md`
4. `PR-10.4-pbs-parser-block-and-statement-decomposition.md`
5. `PR-10.5-pbs-parser-recovery-utilities-and-regression-hardening.md`
### Onda O11 - Expression Parser Maintainability Refactor (No Functional Change)
Foco: reduzir complexidade estrutural de `PbsExprParser` sem alterar precedence, AST, spans, recovery ou diagnosticos observaveis.
1. `PR-11.1-pbs-expr-parser-shared-context-and-precedence-spine.md`
2. `PR-11.2-pbs-expr-parser-control-flow-subparsers.md`
3. `PR-11.3-pbs-expr-parser-postfix-primary-and-construction-decomposition.md`
4. `PR-11.4-pbs-expr-parser-literals-patterns-and-shared-token-utilities.md`
5. `PR-11.5-pbs-expr-parser-regression-hardening-and-final-cleanup.md`
### Onda O12 - Flow Expression Analyzer Maintainability Refactor (No Functional Change)
Foco: reduzir complexidade estrutural de `PbsFlowExpressionAnalyzer` sem alterar inferencia, diagnosticos, matching de tipos ou comportamento observavel da analise semantica.
1. `PR-12.1-flow-expression-analyzer-context-and-dispatch-foundation.md`
2. `PR-12.2-flow-expression-analyzer-literal-and-structural-expression-splitting.md`
3. `PR-12.3-flow-expression-analyzer-call-and-member-resolution-decomposition.md`
4. `PR-12.4-flow-expression-analyzer-switch-and-handle-decomposition.md`
5. `PR-12.5-flow-expression-analyzer-regression-hardening-and-final-cleanup.md`
### Onda O13 - Flow Body Analyzer Maintainability Refactor (No Functional Change)
Foco: reduzir complexidade estrutural de `PbsFlowBodyAnalyzer` sem alterar regras de flow, completion, assignment checking ou diagnosticos observaveis.
1. `PR-13.1-flow-body-analyzer-context-and-entrypoint-foundation.md`
2. `PR-13.2-flow-body-analyzer-callable-body-and-completion-decomposition.md`
3. `PR-13.3-flow-body-analyzer-statement-analysis-splitting.md`
4. `PR-13.4-flow-body-analyzer-assignment-target-resolution-decomposition.md`
5. `PR-13.5-flow-body-analyzer-regression-hardening-and-final-cleanup.md`
@@ -0,0 +1,63 @@
# PR-05.0.1 - Frontend Phase Shared NameTable Context
## Briefing
Hoje o frontend PBS cria `NameTable` em componentes diferentes (linking, declarative semantics, rules), o que fragmenta identidade de nome por fase.
Esta PR centraliza `NameTable` no `FrontendPhaseContext` para toda a fase de frontend, com um ciclo de vida unico por compilacao.
## Motivation
### Dor que esta PR resolve
1. Mesma string pode receber `NameId` diferente dependendo da fase.
2. Dificulta evoluir para identidades tipadas cross-phase sem adaptadores de conversao.
3. Complica debug e rastreabilidade de diagnosticos semanticos entre linking e lowering.
## Target
Uniformizar identidade de nomes no FE inteiro, com `NameId` estavel durante a fase de frontend.
## Scope
1. `FrontendPhaseContext` passa a expor `NameTable`.
2. Validators e binders do PBS passam a receber `NameTable` do contexto, sem criar tabela local.
3. Ajuste de testes que dependem de instanciacao direta.
## Non-Goals
1. Nao altera regras semanticas.
2. Nao altera parser/AST.
## Method
### O que deve ser feito explicitamente
1. Adicionar `NameTable` ao contexto da fase de frontend.
2. Remover `new NameTable()` locais em linking/semantics.
3. Injetar o `NameTable` compartilhado em:
- `PbsModuleVisibilityValidator`,
- `PbsDeclarationSemanticsValidator`,
- `PbsDeclarationRuleValidator`,
- `PbsNamespaceBinder`.
4. Garantir que o ciclo de vida da tabela seja por execucao de fase, nao global estatico.
## Acceptance Criteria
1. Nao existe mais alocacao local de `NameTable` nas fases PBS do frontend.
2. Mesmo nome gera mesmo `NameId` em linking e semantica na mesma compilacao.
3. Testes de linking/semantica continuam passando sem regressao comportamental.
## Tests
1. Teste de identidade cruzada (linking vs declaration validation) para nomes iguais.
2. Teste de isolamento entre duas compilacoes diferentes (nao vazar IDs entre runs).
## Affected Documents
1. `docs/pbs/specs/11. AST Specification.md`
2. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
## Open Questions
Sem bloqueios arquiteturais.
@@ -0,0 +1,59 @@
# PR-05.0.2 - Module Identity Dense Table and ModuleId Wiring
## Briefing
O FE usa `String moduleKey` em varios mapas e no handoff para backend.
Esta PR introduz identidade densa de modulo (`ModuleTable` + `ModuleId`) e faz o FE operar internamente por ID, mantendo string apenas como representacao de borda quando necessario.
## Motivation
### Dor que esta PR resolve
1. Chaves string de modulo sao repetidas e suscetiveis a inconsistencia de normalizacao.
2. Custos de hash/string crescem com o grafo de modulos.
3. Dificuldade de garantir determinismo e joins estaveis em agregacao multi-modulo.
## Target
Substituir identidade interna de modulo baseada em string por `ModuleId` internado.
## Scope
1. Criacao de `ModuleTable` no core.
2. Uso de `ModuleId` em `PBSFrontendPhaseService` para mapas de modulo/dependencias.
3. Adaptacao de pontos de diagnostico e exibição para renderizar nome canônico quando preciso.
## Non-Goals
1. Nao altera sintaxe de import.
2. Nao altera formato de mensagens ao usuario final alem do necessario.
## Method
### O que deve ser feito explicitamente
1. Implementar `ModuleTable extends InternTable<ModuleId, ModuleRef>` (ou valor equivalente canonico).
2. Trocar `Map<String,...>` de modulo em `PBSFrontendPhaseService` por `Map<ModuleId,...>`.
3. Trocar grafo de dependencia de `String` para `ModuleId`.
4. Manter funcao unica de render de modulo para diagnostico.
## Acceptance Criteria
1. Fluxo principal do FE nao depende de `moduleKey` string para joins internos.
2. Dependencias e bloqueios por falha de modulo usam `ModuleId`.
3. Nao ha regressao funcional em linking/import gating.
## Tests
1. Teste de determinismo de IDs de modulo para mesmo grafo admitido.
2. Teste de propagacao de falha por dependencia usando IDs.
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
## Open Questions
Sem bloqueios arquiteturais.
@@ -0,0 +1,62 @@
# PR-05.0.3 - IRBackend Typed Callable and Intrinsic IDs
## Briefing
O contrato `IRBackendExecutableFunction` ainda carrega `callableId`, `calleeCallableId` e `intrinsicId` como `int/Integer`.
Esta PR tipa esses campos com `CallableId` e `IntrinsicId`, alinhando model com Dense Tables e reduzindo erro de classe de ID.
## Motivation
### Dor que esta PR resolve
1. Mistura acidental entre dominios de ID diferentes em tempo de desenvolvimento.
2. Validacoes repetitivas de faixa/semantica por usar primitivo nu.
3. API de backend menos segura para evolucao de lowering/remap.
## Target
Evoluir o contrato de FE->BE para IDs tipados em vez de inteiros crus.
## Scope
1. `IRBackendExecutableFunction` e metadados de instrucao.
2. `IRBackendAggregator` remap de callables e intrinsecos.
3. Ajustes de serializers/tests que assumem `int`.
## Non-Goals
1. Nao muda semantica de chamada.
2. Nao muda ordenacao de remap por si so.
## Method
### O que deve ser feito explicitamente
1. Trocar:
- `int callableId` -> `CallableId`,
- `Integer calleeCallableId` -> `CallableId` (nullable quando aplicavel),
- `int intrinsicId` -> `IntrinsicId`.
2. Atualizar construtores/guards para validar `.isNone()` e nao-negatividade via tipo.
3. Atualizar `IRBackendAggregator` para trabalhar com vetores/tabelas de IDs tipados.
4. Atualizar FE lowering PBS para emitir IDs tipados desde origem.
## Acceptance Criteria
1. Nao ha mais campos de callable/intrinsic ID como inteiro cru no contrato executavel.
2. Tentativas de misturar dominio de ID falham em compile-time.
3. Testes de remap e merge seguem verdes.
## Tests
1. Testes unitarios de construcao de instrucao com tipos corretos/incorretos.
2. Testes de agregacao multi-arquivo validando remap tipado.
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
## Open Questions
Sem bloqueios arquiteturais.
@@ -0,0 +1,62 @@
# PR-05.0.4 - Callable Shape and Signature Interning
## Briefing
O FE ainda monta chaves semanticas por concat string (`name#arity`, `signatureSurface`, `typeShape`).
Esta PR cria internacao para superfícies de assinatura/shape e remove concatenação textual como identidade primaria.
## Motivation
### Dor que esta PR resolve
1. Chave textual e fragil para evolucao de formato.
2. Custo de alocacao/hash desnecessario em caminhos quentes.
3. Risco de colisao logica por normalizacao incompleta.
## Target
Internar shapes de callable e superfícies de assinatura em tabela dedicada, com ID estavel.
## Scope
1. Estruturas de assinatura do linking e lowering.
2. `CallableSignatureRef` com suporte a referencia internada de shape.
3. Remocao gradual de `callableArityKey` e derivados string.
## Non-Goals
1. Nao altera regra de overload.
2. Nao altera formato externo de diagnostico.
## Method
### O que deve ser feito explicitamente
1. Introduzir tabela de shapes (ex.: `CallableShapeTable` / `TypeSurfaceTable`).
2. Representar identidade de callable por tupla tipada (`NameId`, aridade, `ShapeId`).
3. Atualizar:
- linking (`FunctionSymbolKey`),
- FE lowering executavel (`callableIdsByNameAndArity`),
- referencias em `CallableSignatureRef`.
4. Manter conversao para string apenas para logs/debug.
## Acceptance Criteria
1. Fluxo principal de resolução de callable nao depende de concat string.
2. Determinismo de shape/signature comprovado por ID internado.
3. Nenhuma regressao de resolução de overload/documentada.
## Tests
1. Teste de internacao idempotente para shape identico.
2. Testes de distinção para shapes diferentes com mesmo nome/arity.
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
## Open Questions
Sem bloqueios arquiteturais.
@@ -0,0 +1,59 @@
# PR-05.0.5 - Synthetic Stdlib FileId via FileTable
## Briefing
`InterfaceModuleLoader` hoje aloca `FileId` sintetico por `AtomicInteger`.
Esta PR move a alocacao de arquivos sinteticos para o `FileTable`, mantendo uma unica autoridade de identidade de arquivo.
## Motivation
### Dor que esta PR resolve
1. Risco de colisao/deriva de `FileId` fora da infraestrutura oficial.
2. Arquivos sinteticos ficam fora da trilha normal de metadata de source.
3. Diagnosticos e spans de stdlib perdem consistencia de origem no pipeline.
## Target
Fazer todo `FileId` (incluindo sintetico) vir do `FileTable`.
## Scope
1. `InterfaceModuleLoader`.
2. Contexto de carga de stdlib/interface para suportar registro no `FileTable`.
3. Source handle sintetico minimo para parser/diagnostico.
## Non-Goals
1. Nao altera conteudo dos modulos stdlib.
2. Nao altera parse mode de interface.
## Method
### O que deve ser feito explicitamente
1. Criar `SourceHandle` sintetico para fontes carregadas da stdlib/interface.
2. Registrar cada handle no `FileTable` e usar `FileId` retornado.
3. Remover contador `AtomicInteger` de `InterfaceModuleLoader`.
4. Preservar caminho lógico para mensagens (ex.: origem virtual stdlib).
## Acceptance Criteria
1. `InterfaceModuleLoader` nao usa mais `new FileId(...)`.
2. Todo `FileId` de stdlib/interface existe no `FileTable`.
3. Diagnosticos em fontes sinteticas mantem atribuicao consistente.
## Tests
1. Teste de carga de interface garantindo que `FileId` sintetico foi registrado no `FileTable`.
2. Teste de span/diagnostico para arquivo sintetico.
## Affected Documents
1. `docs/pbs/specs/11. AST Specification.md`
2. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
## Open Questions
Sem bloqueios arquiteturais.
@@ -0,0 +1,59 @@
# PR-05.0.6 - Host Binding Key Interning and Capability Identity
## Briefing
A validacao de host admission ainda usa chave composta em string (`module|method|version`) para deduplicacao e consistencia.
Esta PR troca chave textual por identidade internada de binding host e prepara capacidade para validacoes mais seguras.
## Motivation
### Dor que esta PR resolve
1. Concatenacao textual para chave critica de ABI e fragil.
2. Risco de bug por normalizacao inconsistente de partes da chave.
3. Menor clareza para evoluir validacao de capabilities por dominio tipado.
## Target
Internar identidade canonica de host binding em tabela dedicada e usar ID no validador de host admission.
## Scope
1. `PbsHostAdmissionValidator`.
2. Infra de tabela de binding host no core/frontend.
3. Ajustes em metadados reservados quando necessario.
## Non-Goals
1. Nao altera semantica de capability policy.
2. Nao altera contrato de host ABI no runtime.
## Method
### O que deve ser feito explicitamente
1. Introduzir valor canônico `HostBindingRef(module,name,version)` e tabela internada.
2. Substituir map com chave string por map com `HostBindingId` (ou `HostBindingRef` internado).
3. Manter normalizacao de capability separada da identidade de binding.
4. Preservar diagnosticos com referencias claras ao binding original.
## Acceptance Criteria
1. `PbsHostAdmissionValidator` nao usa mais chave formatada por string para binding.
2. Inconsistencia de capability para mesmo binding continua detectada de forma deterministica.
3. Nao ha regressao em cenarios conhecidos de host admission.
## Tests
1. Teste de deduplicacao de binding por identidade internada.
2. Teste de mismatch de capability para mesmo binding.
## Affected Documents
1. `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
2. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
## Open Questions
Sem bloqueios arquiteturais.
@@ -0,0 +1,78 @@
# PR-05.1 - PBS Frontend Semantic Executable Lowering (CFG)
## Briefing
O frontend PBS ainda gera `IRBackendExecutableFunction` por varredura de callsites no AST, o que perde semântica de execução real.
Esta PR substitui esse caminho por lowering semântico baseado em fluxo de controle (CFG), preservando ordem de execução, terminadores e formas de desvio.
## Motivation
### Dor atual que esta PR resolve
1. Execução divergente entre programa fonte e artefato gerado em cenários com `if`, `while`, `for`, `switch`, `handle` e `return` antecipado.
2. Impossibilidade de elevar o backend para JVM-grade porque o contrato executável nasce semanticamente incompleto.
3. Falsos positivos de conformidade: testes passam para casos lineares, mas o modelo quebra em fluxo real.
## Target
Esta PR altera o frontend PBS para que `IRBackendExecutableFunction.instructions` represente fluxo executável real, não apenas uma lista de chamadas encontradas.
## Dependencies
Prerequisitos diretos:
1. `PR-05.0.1` (NameTable compartilhada por fase).
2. `PR-05.0.2` (identidade de modulo por `ModuleId`).
3. `PR-05.0.3` (IDs tipados de callable/intrinseco no contrato).
4. `PR-05.0.4` (internacao de shape/signature).
## Scope
1. Gerador de IR executável no frontend PBS.
2. Emissão de labels e jumps para estruturas de controle.
3. Recalculo de `maxStackSlots` com base no fluxo emitido.
4. Testes de fidelidade semântica do FE para IR executável.
## Non-Goals
1. Não introduz otimizações.
2. Não altera formato binário PBX.
3. Não altera runtime.
## Method
### O que deve ser feito explicitamente
1. Substituir o mecanismo de `collectCallsFrom*` por lowering orientado a nós semânticos de statements/expressions.
2. Emitir instruções de controle (`LABEL`, `JMP`, `JMP_IF_TRUE`, `JMP_IF_FALSE`, `RET`) para cada forma de fluxo suportada.
3. Garantir que `return` termine bloco/caminho e que caminhos alcançáveis terminem em instrução terminadora.
4. Preservar spans de origem em cada instrução emitida para diagnóstico.
5. Manter validação fail-fast quando existir forma semântica não lowerável em v1.
6. Atualizar análise de stack para operar sobre o programa realmente emitido.
7. Emitir referências de chamada via IDs tipados (`CallableId`/`IntrinsicId`) sem chave textual ad-hoc.
## Acceptance Criteria
1. `IRBackendExecutableFunction` deixa de ser construído por varredura cega de callsites.
2. Para casos com ramificação e laço, a ordem de execução no IR executável é semanticamente equivalente ao AST validado.
3. Funções com `return` antecipado não emitem execução espúria após ponto de saída.
4. `maxStackSlots` calculado bate com programa emitido e passa em validação backend.
5. Diagnósticos de lowering preservam fase e span corretamente.
6. Não há lookup de identidade de callsite baseado em concatenação string no caminho principal.
## Tests
1. Testes positivos com fixtures de `if/else`, `while`, `for`, `switch`, `handle`, `return` antecipado.
2. Testes negativos para caminhos sem terminador, labels inválidos e formas não suportadas.
3. Teste de regressão comparando resultado anterior vs novo para provar correção em casos não lineares.
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/19. Verification and Safety Checks Specification.md`
## Open Questions
Sem bloqueios arquiteturais. Implementação deve seguir decisões já fechadas na Agenda 18.
@@ -0,0 +1,73 @@
# PR-05.2 - IRBackend Callsite Classification by Semantic Identity
## Briefing
A classificação de callsites no frontend executável ainda depende de heurística textual de callee.
Esta PR torna obrigatória a classificação por identidade semântica resolvida no binding, eliminando inferência por nome/forma textual.
## Motivation
### Dor atual que esta PR resolve
1. Risco de classificar callsite no bucket errado (`CALL_FUNC`, `CALL_HOST`, `CALL_INTRINSIC`).
2. Ambiguidade em member/bind/group callee com nome coincidente.
3. Falta de robustez em evolução de sintaxe semântica do FE.
## Target
Fronteira `PBS FE -> IRBackend` com identidade de callsite estável e sem heurística textual para decisão de categoria.
## Dependencies
Prerequisitos diretos:
1. `PR-05.0.1` (NameTable compartilhada).
2. `PR-05.0.2` (ModuleId no FE).
3. `PR-05.0.3` (CallableId/IntrinsicId tipados no contrato).
4. `PR-05.0.4` (shape/signature internadas).
## Scope
1. Resultado de resolução semântica para chamadas.
2. Estrutura de lowering para carregar identidade resolvida.
3. Diagnósticos quando identidade não estiver resolvida no ponto exigido.
## Non-Goals
1. Não muda política de overload além do já definido em semântica.
2. Não introduz novas categorias de callsite.
## Method
### O que deve ser feito explicitamente
1. Propagar do analisador semântico para lowering um descritor explícito de destino de chamada.
2. O descritor deve carregar identidade canônica tipada (ao menos categoria + id alvo), sem depender de nome textual.
3. Remover dependência de `extractSimpleCalleeName` para classificação.
4. Exigir que cada callsite emitido em `IRBackend` esteja em exatamente uma categoria válida.
5. Emitir erro determinístico quando o FE não possuir identidade semântica suficiente para classificar o callsite.
6. Validar compatibilidade de metadados obrigatórios por categoria no ato de emissão.
## Acceptance Criteria
1. Classificação de callsite não depende de parsing textual de callee.
2. Cada callsite em `IRBackend` possui categoria única e metadados obrigatórios.
3. Casos ambíguos geram diagnóstico estável em fase correta, sem fallback heurístico.
4. Não há regressão em casos já válidos.
5. O payload de callsite no contrato executável é tipado por ID, não por inferência textual.
## Tests
1. Testes positivos para chamadas de função, host e intrínseco com diferentes formas sintáticas.
2. Testes negativos de ambiguidade e callee não resolvido.
3. Testes de estabilidade diagnóstica (code/phase/span).
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
## Open Questions
Sem bloqueios arquiteturais.
@@ -0,0 +1,70 @@
# PR-05.3 - IRVM Deterministic Function-ID and Entrypoint Policy
## Briefing
A regra de indexação de funções e seleção de entrypoint precisa ficar estritamente alinhada ao contrato normativo para evitar divergência entre builds equivalentes.
Esta PR fecha política determinística de `func_id` e entrypoint único explícito.
## Motivation
### Dor atual que esta PR resolve
1. Possível variação de `func_id` quando ordem de merge muda.
2. Risco de entrypoint implícito ou ambíguo.
3. Dificuldade para gerar artefatos reproduzíveis e goldens estáveis.
## Target
`LowerToIRVMService` com regra única e testável de ordenação/indexação/entrypoint.
## Dependencies
Prerequisitos diretos:
1. `PR-05.0.2` (identidade de modulo por `ModuleId`).
2. `PR-05.0.3` (IDs tipados de callable).
## Scope
1. Ordenação determinística de funções.
2. Política explícita de entrypoint.
3. Diagnóstico para ausência ou ambiguidade de entrypoint.
## Non-Goals
1. Não altera ABI de chamada.
2. Não altera layout binário do bytecode.
## Method
### O que deve ser feito explicitamente
1. Definir ordenação canônica apenas pelos campos normativos aprovados.
2. Tornar explícita a ordenação de módulo a partir do `ModuleId` canônico.
3. Exigir exatamente um entrypoint válido no grafo admitido.
4. Atribuir `func_id=0` ao entrypoint e indexar demais por ordem canônica.
5. Rejeitar determinísticamente casos sem entrypoint ou com entrypoint múltiplo.
6. Cobrir cenários de permutação de entrada com mesma saída de indexação.
## Acceptance Criteria
1. Mesma entrada admitida gera mesma tabela de `func_id` em execuções repetidas.
2. Mudança na ordem de merge dos módulos não altera indexação final.
3. Ausência ou ambiguidade de entrypoint falha com diagnóstico estável.
4. A ordenação não depende de string derivada não canônica de módulo.
## Tests
1. Teste de determinismo com permutação de ordem de merge.
2. Teste de entrypoint único válido.
3. Testes negativos para zero entrypoint e múltiplos entrypoints.
## Affected Documents
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
2. `docs/general/specs/19. Verification and Safety Checks Specification.md`
## Open Questions
Sem bloqueios arquiteturais.
@@ -0,0 +1,68 @@
# PR-05.4 - IRVM Program Coherence Without Bypass
## Briefing
Existe bypass de coerência no `IRVMProgram` em presença de `RAW_SYSCALL` e derivação com placeholders (`__unknown__`).
Esta PR remove esses atalhos do fluxo canônico e endurece o contrato de coerência `IRVM <-> EmissionPlan`.
## Motivation
### Dor atual que esta PR resolve
1. Programa pode aparentar coerente e mesmo assim carregar informação inválida para emissão.
2. Brecha para mascarar erro estrutural antes do Gate de emissão/verificação.
3. Diagnóstico tardio e pouco preciso para falhas de marshaling.
## Target
`IRVMProgram` com coerência obrigatória, sem exceção silenciosa para formas proibidas no pipeline canônico.
## Dependencies
Prerequisito direto:
1. `PR-05.0.3` (payload de IDs tipados no contrato executável).
## Scope
1. Regras de coerência no construtor e no `coherentEmissionPlan()`.
2. Eliminação de placeholder de syscall desconhecida em caminho de derivação canônico.
3. Taxonomia de erro para incoerência estrutural.
## Non-Goals
1. Não muda verificador runtime.
2. Não muda decisão de proibir `RAW_SYSCALL` em pre-load.
## Method
### O que deve ser feito explicitamente
1. Remover condição que pula validação de coerência quando detecta `RAW_SYSCALL`.
2. Tornar inválido no caminho canônico qualquer plano com operação proibida para pre-load.
3. Remover geração de `HOSTCALL` com `SyscallDecl("__unknown__",...)` em derivação automática.
4. Falhar cedo com erro determinístico e mensagem orientada a ação.
## Acceptance Criteria
1. `IRVMProgram` nunca retorna plano incoerente no fluxo canônico.
2. Não existe mais derivação com placeholders desconhecidos para hostcall.
3. Erros de coerência aparecem antes da emissão binária.
4. Coerência valida vínculos de IDs de call/intrinsic com tipo correto de domínio.
## Tests
1. Testes negativos para `RAW_SYSCALL` no plano e para hostcall sem metadado válido.
2. Testes de regressão para caminhos válidos existentes.
3. Testes de estabilidade de códigos de erro.
## Affected Documents
1. `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/19. Verification and Safety Checks Specification.md`
## Open Questions
Sem bloqueios arquiteturais.
@@ -0,0 +1,70 @@
# PR-05.5 - IRVM Validator Real Stack Effects for HOSTCALL and INTRINSIC
## Briefing
O validador IRVM hoje modela `HOSTCALL` e `INTRINSIC` com efeito de stack genérico insuficiente para rigor JVM-grade.
Esta PR passa a validar efeitos reais de stack por assinatura (`arg_slots`/`ret_slots`) nessas operações.
## Motivation
### Dor atual que esta PR resolve
1. Possíveis underflow/overflow não detectados em chamadas host/intrínseco.
2. Retorno efetivo divergente sem falha no precheck.
3. Confiança excessiva na emissão sem validação semântica de pilha completa.
## Target
`IRVMValidator` e metadados de operação com informação suficiente para calcular efeito real de stack.
## Dependencies
Prerequisitos diretos:
1. `PR-05.0.3` (IDs tipados de callable/intrinseco).
2. `PR-05.0.6` (identidade canônica de host binding).
## Scope
1. Modelo de metadados para chamadas host e intrínseco no estágio IRVM.
2. Regras de validação de stack baseadas em assinatura.
3. Diagnósticos determinísticos de mismatch.
## Non-Goals
1. Não define política de otimização.
2. Não altera opcode wire format.
## Method
### O que deve ser feito explicitamente
1. Introduzir acesso a `arg_slots`/`ret_slots` efetivos durante validação de `HOSTCALL`.
2. Introduzir contrato equivalente para `INTRINSIC` (a partir de tabela canônica no pipeline).
3. Aplicar stack effect real no data-flow do validador.
4. Rejeitar mismatch de altura de retorno em joins e `RET` final.
5. Preservar mensagens de erro estáveis na taxonomia `MARSHAL_VERIFY_PRECHECK_*`.
6. Consumir metadados canônicos por ID, sem lookup textual ad-hoc.
## Acceptance Criteria
1. `HOSTCALL` e `INTRINSIC` participam do cálculo real de pilha no validador.
2. Casos de mismatch de assinatura falham no precheck com erro determinístico.
3. Casos válidos seguem aprovando sem regressão.
4. O caminho de validação não depende de composição textual de chave de binding.
## Tests
1. Testes positivos com combinações de arg/ret slots para host e intrínsecos.
2. Testes negativos para underflow, overflow e retorno incompatível.
3. Testes de join mismatch com chamadas em blocos ramificados.
## Affected Documents
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
2. `docs/general/specs/19. Verification and Safety Checks Specification.md`
## Open Questions
Sem bloqueios arquiteturais.
@@ -0,0 +1,75 @@
# PR-05.6 - OptimizeIRVM Real Deterministic Passes
## Briefing
A etapa `OptimizeIRVM` está corretamente posicionada no pipeline, mas ainda opera como `NoOp`.
Esta PR introduz o primeiro conjunto de passes reais, seguros e determinísticos, mantendo equivalência semântica e compatibilidade de perfil.
## Motivation
### Dor atual que esta PR resolve
1. Etapa de otimização existe formalmente, mas não entrega valor técnico.
2. Difícil sustentar evolução de performance e limpeza de IRVM sem regressão.
3. Falta de contrato de execução de pass manager com evidência forte.
## Target
`OptimizeIRVMService` com pass manager produtivo e baseline de passes v1.
## Dependencies
Prerequisitos diretos:
1. `PR-05.0.3` (IDs tipados no contrato executável).
2. `PR-05.0.4` (shape/signature internadas).
## Scope
1. Pass manager determinístico com ordem estável.
2. Passes iniciais semânticamente conservadores.
3. Validação antes/depois de cada pass.
## Non-Goals
1. Não inclui otimizações agressivas interprocedurais.
2. Não inclui JIT/runtime optimization.
## Method
### O que deve ser feito explicitamente
1. Implementar baseline de passes v1:
- eliminação de bloco inalcançável,
- normalização de labels redundantes,
- simplificação de salto para próximo PC.
2. Manter invariantes obrigatórias:
- sem mudança de `vm_profile`,
- sem introdução de opcode fora do perfil,
- sem alteração de contratos de slots/retorno observáveis.
3. Validar programa antes e após cada pass.
4. Registrar nome/ordem de pass para rastreabilidade de regressão.
## Acceptance Criteria
1. `OptimizeIRVM` deixa de ser apenas `NoOp` no caminho padrão.
2. Mesma entrada produz mesma saída otimizada (determinismo).
3. Testes de equivalência semântica passam para fixtures representativas.
4. Nenhum pass viola perfil de VM ou contrato de emissão.
5. Nenhum pass degrada identidade tipada para chave textual ad-hoc.
## Tests
1. Testes unitários por pass com entradas mínimas e edge cases.
2. Testes de pipeline comparando saída otimizada vs não otimizada para equivalência.
3. Testes negativos para pass que tenta alterar perfil/semântica.
## Affected Documents
1. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md`
2. `docs/general/specs/19. Verification and Safety Checks Specification.md`
## Open Questions
Sem bloqueios arquiteturais para baseline v1.
@@ -0,0 +1,66 @@
# PR-05.7 - Gate I Runtime-Backed Mandatory in CI
## Briefing
O harness de compatibilidade runtime-backed pode cair para `local-fallback` quando comando não está configurado.
Esta PR separa modo dev e modo CI, tornando obrigatório runtime-backed real em CI para suportar claim forte de conformidade.
## Motivation
### Dor atual que esta PR resolve
1. Falsa sensação de conformidade quando ambiente cai para fallback local.
2. Regressões de integração com runtime real podem passar despercebidas.
3. Evidência de Gate I fica fraca para suporte externo.
## Target
Pipeline de testes com política explícita: em CI, fallback local não é aceito para Gate I.
## Dependencies
Dependencia recomendada:
1. `PR-05.8` para registrar o status do Gate I na matriz de conformidade.
## Scope
1. Política de execução do adapter runtime-backed.
2. Configuração de CI para `PROMETEU_RUNTIME_CHECK_CMD`.
3. Diagnóstico claro quando runtime-backed obrigatório não está ativo.
## Non-Goals
1. Não altera runtime.
2. Não remove adapter local para uso de desenvolvimento.
## Method
### O que deve ser feito explicitamente
1. Introduzir flag de modo estrito para Gate I em CI.
2. Em modo estrito, falhar teste se adapter entrar em `local-fallback`.
3. Publicar comando e contrato mínimo do check runtime em pipeline.
4. Preservar modo permissivo local para desenvolvimento fora de CI.
## Acceptance Criteria
1. CI falha se Gate I não executar em modo runtime-backed real.
2. Execução local mantém fallback disponível quando não for modo estrito.
3. Resultado de Gate I reporta claramente `adapterMode` e motivo.
## Tests
1. Teste de modo estrito com comando ausente deve falhar.
2. Teste de modo estrito com comando válido deve passar.
3. Regressão local em modo não estrito permanece funcional.
## Affected Documents
1. `docs/general/specs/19. Verification and Safety Checks Specification.md`
2. `docs/general/specs/13. Conformance Test Specification.md`
## Open Questions
Sem bloqueios arquiteturais.
@@ -0,0 +1,73 @@
# PR-05.8 - Backend Spec-to-Test Conformance Matrix
## Briefing
Falta uma matriz única ligando cada MUST normativo de backend aos testes que provam conformidade.
Esta PR cria a matriz de rastreabilidade para `18.1`, `18.2`, `18.3`, specs `19`, `20`, `21` e Gate I/S-U.
## Motivation
### Dor atual que esta PR resolve
1. Dificuldade de provar cobertura de conformidade por requisito.
2. Buracos de teste ficam escondidos por ausência de rastreabilidade.
3. Evolução de arquitetura sem visão clara de impacto em evidência.
## Target
Artefato de conformidade auditável que mapeia requisito -> teste positivo -> teste negativo -> status.
## Dependencies
Prerequisito de conteúdo:
1. Incorporar explicitamente a trilha `PR-05.0.X` como fundação de identidade/IDs.
## Scope
1. Matriz normativa de backend FE/BE.
2. Classificação de status por requisito (`pass`, `missing`, `partial`, `deferred`).
3. Regra de atualização obrigatória da matriz em toda PR backend relevante.
4. Seção dedicada para rastrear requisitos de identidade tipada e Dense Tables.
## Non-Goals
1. Não cria nova semântica de linguagem.
2. Não substitui specs normativas.
## Method
### O que deve ser feito explicitamente
1. Criar documento de matriz em `docs/general/specs` ou `docs/pbs/specs` com tabela por requisito normativo.
2. Para cada MUST, vincular explicitamente:
- teste(s) positivo(s),
- teste(s) negativo(s),
- módulo/classe de teste,
- status atual.
3. Adicionar quality gate de revisão: PR backend sem atualização da matriz deve ser rejeitada quando impactar conformidade.
4. Definir procedimento de manutenção para não deixar entradas órfãs.
## Acceptance Criteria
1. Todo MUST de `19`, `20`, `21` e addendum executável de `13` aparece na matriz.
2. Cada item tem referência concreta a teste ou marcação explícita de ausência.
3. Revisão de PR consegue identificar rapidamente gaps de conformidade.
4. A matriz explicita dependência e cobertura dos itens `PR-05.0.1` a `PR-05.0.6`.
## Tests
1. Não exige testes executáveis novos por si só.
2. Exige checagem de integridade da matriz em revisão CI/lint documental.
## Affected Documents
1. `docs/general/specs/19. Verification and Safety Checks Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md`
4. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
## Open Questions
Sem bloqueios arquiteturais.
@@ -0,0 +1,72 @@
# PR-06.1 - Source Attribution and Diagnostics Evidence Hardening
## Briefing
Ha cobertura parcial para preservacao de `source attribution` em rejeicoes backend e no handoff executavel.
Esta PR fecha os gaps de evidencia para requisitos de atribuicao de origem e estabilidade de diagnostico.
## Motivation
### Dor atual que esta PR resolve
1. Falta de prova forte de que erros backend preservam `file/start/end` quando acionaveis pelo usuario.
2. Parte da matriz marca `partial` para requisitos de atribuicao (`G20-11.3`, `PBS13-12.1.4`).
3. Revisao de regressao de spans depende de inspeccao manual.
## Target
Cobertura automatizada para atribuicao de origem em diagnosticos de falha backend e no contrato executavel.
## Dependencies
Prerequisitos recomendados:
1. `PR-05.5` (stack effects reais host/intrinsic).
2. `PR-05.8` (matriz de conformidade existente).
## Scope
1. Testes de atribuicao de origem para falhas deterministicas no `LowerToIRVM`.
2. Testes de atribuicao para falhas de pipeline (`BACKEND_LOWER_IRVM` e `BACKEND_EMIT_BYTECODE`) quando aplicavel.
3. Atualizacao da matriz para migrar `G20-11.3` e `PBS13-12.1.4` de `partial` para `pass` se houver cobertura completa.
## Non-Goals
1. Nao altera semantica de linguagem.
2. Nao introduz novas classes de diagnostico.
## Method
### O que deve ser feito explicitamente
1. Criar fixtures negativas onde erro e claramente source-actionable e verificar:
- `code` estavel,
- `phase` estavel,
- `file/start/end` presentes e coerentes.
2. Garantir que spans de instrucoes/callsites sejam propagadas ativamente para as mensagens de falha.
3. Atualizar a matriz com referencias exatas de teste.
## Acceptance Criteria
1. Falhas source-actionable do backend expõem atribuicao de origem valida.
2. Requisitos `G20-11.3` e `PBS13-12.1.4` saem de `partial` se cobertura completa for atingida.
3. Nenhuma regressao em testes existentes de taxonomia de erro.
## Tests
1. Novos testes unitarios/integracao para spans em diagnosticos de falha.
2. Reexecucao obrigatoria:
- `:prometeu-compiler:prometeu-build-pipeline:test`
- `:prometeu-compiler:prometeu-frontend-api:test`
## Affected Documents
1. `docs/general/specs/19. Verification and Safety Checks Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
4. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
## Open Questions
Sem bloqueios arquiteturais.
@@ -0,0 +1,75 @@
# PR-06.2 - OptimizeIRVM Semantic Equivalence Harness
## Briefing
A etapa `OptimizeIRVM` ja possui passes reais, mas a prova de equivalencia semantica ainda esta parcial.
Esta PR cria harness sistematico para validar comportamento observavel com `opt on/off`.
## Motivation
### Dor atual que esta PR resolve
1. Evidencia de equivalencia semantica ainda e fixture-level limitada.
2. Itens `G21-6.2`, `G21-7.1` e `G21-9.1` permanecem `partial`.
3. Risco de pass regressivo sem deteccao ampla.
## Target
Harness de equivalencia deterministica com corpus de CFG e chamadas host/intrinsic.
## Dependencies
Prerequisitos diretos:
1. `PR-05.6` (pass manager real).
2. `PR-05.7` (Gate I estrito em CI).
## Scope
1. Framework de comparacao `optimized` vs `non-optimized`.
2. Fixtures representativas:
- sequencias lineares,
- condicional com joins,
- loops simples,
- hostcall/intrinsic.
3. Assercoes de invariantes:
- semantica observavel equivalente,
- determinismo de output,
- contratos de slots preservados.
## Non-Goals
1. Nao inclui prova formal completa.
2. Nao adiciona otimizacoes agressivas interprocedurais.
## Method
### O que deve ser feito explicitamente
1. Expor no teste caminho `optimize on/off` para o mesmo `IRVMProgram`.
2. Comparar resultado observavel em nivel de artefato e checagens Gate I/S-U.
3. Cobrir casos negativos em que pass invalido deve falhar por perfil/contrato.
4. Atualizar a matriz para converter requisitos `partial` quando cobertos.
## Acceptance Criteria
1. Existe harness reutilizavel de equivalencia `opt on/off`.
2. Cobertura de CFG e chamadas host/intrinsic com assercao de equivalencia.
3. `G21-6.2`, `G21-7.1`, `G21-9.1` evoluem para `pass` se cobertura completa.
## Tests
1. Novos testes no pacote `backend/irvm` e/ou `integration`.
2. Reexecucao obrigatoria:
- `:prometeu-compiler:prometeu-build-pipeline:test`
## Affected Documents
1. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md`
2. `docs/general/specs/19. Verification and Safety Checks Specification.md`
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
Sem bloqueios arquiteturais.
@@ -0,0 +1,69 @@
# PR-06.3 - IRVM_EXT Contract and Elimination Fixtures
## Briefing
O contrato de `IRVM_EXT` esta parcialmente coberto apenas pelo `INTERNAL_EXT` atual.
Esta PR amplia cobertura para garantir metadados estruturais e eliminacao antes da emissao.
## Motivation
### Dor atual que esta PR resolve
1. Requisito `G20-6.2` permanece `partial`.
2. Falta evidencia para mais de um formato de extensao interna.
3. Dificuldade de evoluir extensoes com seguranca sem regressao de precheck.
## Target
Suite de fixtures para contrato de `IRVM_EXT` e precondicao de eliminacao no caminho de emissao.
## Dependencies
Prerequisitos diretos:
1. `PR-05.6` (otimizador ativo).
2. `PR-05.4` (coerencia de programa sem bypass).
## Scope
1. Fixtures com multiplas op variantes internas (ou metadados distintos equivalentes).
2. Validacao explicita de metadados estruturais (`pops/pushes/branch/terminator`).
3. Prova de rejeicao quando opcode interno residual chega ao emit.
## Non-Goals
1. Nao define novas extensoes de runtime.
2. Nao altera ISA core publicado.
## Method
### O que deve ser feito explicitamente
1. Adicionar cenarios de teste para `IRVM_EXT` alem do caso trivial existente.
2. Verificar que `OptimizeIRVM` elimina extensoes internas em caminho canônico.
3. Verificar que `EmitBytecode` falha deterministicamente quando extensao residual permanece.
4. Atualizar a matriz para `G20-6.2` conforme cobertura final.
## Acceptance Criteria
1. Contrato estrutural de `IRVM_EXT` fica provado por testes dedicados.
2. Caminho de eliminacao pre-emissao e coberto com positivo/negativo.
3. `G20-6.2` evolui para `pass` se cobertura completa.
## Tests
1. `IRVMValidatorTest` e `OptimizeIRVMServiceTest` com novos casos.
2. `EmitBytecodePipelineStageTest` para residual interno.
3. Reexecucao:
- `:prometeu-compiler:prometeu-build-pipeline:test`
## Affected Documents
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
2. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md`
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
Sem bloqueios arquiteturais.
@@ -0,0 +1,68 @@
# PR-06.4 - Gate I Runtime-Line Repeatability in CI
## Briefing
Gate I ja suporta modo estrito runtime-backed, mas a prova de repetibilidade por runtime line ainda esta parcial.
Esta PR endurece CI para validar repetibilidade em mais de uma linha de runtime suportada.
## Motivation
### Dor atual que esta PR resolve
1. `G19-5.2.8` permanece `partial`.
2. Falta evidencia de comportamento repetivel entre linhas de runtime.
3. Claim de integracao forte fica fragil sem execucao multi-line.
## Target
Pipeline CI com Gate I estrito e validacao de repetibilidade em matrix de runtime line.
## Dependencies
Prerequisitos diretos:
1. `PR-05.7` (modo estrito runtime-backed).
2. disponibilidade de pelo menos duas linhas de runtime executaveis no CI.
## Scope
1. Configuracao CI para `PROMETEU_GATE_I_STRICT=true`.
2. Parametrizacao de `PROMETEU_RUNTIME_CHECK_CMD` por runtime line.
3. Registro de evidencia de execucao por linha (log/sumario de job).
## Non-Goals
1. Nao altera implementacao do runtime.
2. Nao define politica de suporte de longo prazo entre linhas.
## Method
### O que deve ser feito explicitamente
1. Adicionar jobs ou matrix de CI para linhas de runtime alvo.
2. Garantir falha obrigatoria quando runtime-backed nao estiver ativo.
3. Adicionar teste/documentacao que explicite `adapterMode`, `runtimeLine` e motivo.
4. Atualizar matriz de conformidade para `G19-5.2.8`.
## Acceptance Criteria
1. CI falha se Gate I cair em fallback em modo estrito.
2. CI executa Gate I em >= 2 linhas de runtime declaradas.
3. `G19-5.2.8` evolui para `pass` se repetibilidade multi-line for comprovada.
## Tests
1. Testes de adapter strict ja existentes continuam verdes.
2. Execucao obrigatoria de Gate I em matrix CI com runtime-backed real.
## Affected Documents
1. `docs/general/specs/13. Conformance Test Specification.md`
2. `docs/general/specs/19. Verification and Safety Checks Specification.md`
3. `docs/general/specs/17. Compatibility and Evolution Policy.md`
4. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Definir oficialmente quais runtime lines entram na matrix minima obrigatoria.
@@ -0,0 +1,68 @@
# PR-06.5 - Conformance Matrix Hard-Gate Policy
## Briefing
A matriz de conformidade existe e possui lint basico, mas ainda nao bloqueia de forma forte PRs que degradam evidencia.
Esta PR transforma a matriz em hard gate processual para mudancas FE/BE com impacto de conformidade.
## Motivation
### Dor atual que esta PR resolve
1. Possibilidade de drift entre comportamento real e status da matriz.
2. Risco de PR alterar pipeline sem atualizar rastreabilidade normativa.
3. Revisao depende demais de disciplina manual.
## Target
Politica automatizada que rejeita PR backend sem atualizacao de matriz quando ha impacto de conformidade.
## Dependencies
Prerequisitos diretos:
1. `PR-05.8` (matriz + lint documental inicial).
## Scope
1. Regra de CI/revisao para detectar mudanca relevante em FE/BE backend.
2. Exigencia de atualizacao da matriz quando requisito normativo e impactado.
3. Politica clara para `partial/missing/deferred` e justificativa obrigatoria.
## Non-Goals
1. Nao substituir julgamento tecnico de revisao.
2. Nao bloquear PR puramente documental sem impacto tecnico.
## Method
### O que deve ser feito explicitamente
1. Definir regra objetiva de impacto (arquivos/pacotes gatilho).
2. Implementar verificacao automatica em CI para forcar update da matriz quando gatilho ocorrer.
3. Exigir no PR referencia explicita aos Requirement IDs alterados.
4. Atualizar docs de contribuicao/qualidade com o novo gate.
## Acceptance Criteria
1. PR com mudanca backend relevante e sem update de matriz e rejeitada.
2. PR que altera status de requisito exige justificativa e testes referenciados.
3. Processo de revisao fica reproduzivel e auditavel.
## Tests
1. Testes de lint/matriz existentes continuam passando.
2. Teste de politica (script/check) com cenarios:
- mudanca relevante sem matriz -> fail,
- mudanca relevante com matriz -> pass.
## Affected Documents
1. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
2. `docs/general/specs/13. Conformance Test Specification.md`
3. `docs/pbs/specs/2. Governance and Versioning.md`
## Open Questions
1. Definir lista final de caminhos de codigo que acionam hard gate de matriz.
@@ -0,0 +1,76 @@
# PR-06.6 - SPAWN/YIELD v1 or Claim Rescope
## Briefing
Os requisitos `G20-9.4.2` e `G20-9.4.3` estao `deferred` porque `SPAWN/YIELD` nao fazem parte do surface executavel v1 atual.
Esta PR fecha a pendencia por uma de duas trilhas exclusivas:
1. implementar `SPAWN/YIELD` em v1 com testes; ou
2. ajustar claim/perfil/spec para remover obrigacao deste escopo no v1 claimado.
## Motivation
### Dor atual que esta PR resolve
1. Nota JVM-grade fica penalizada por requisitos deferidos.
2. Claim de conformidade pode ficar ambiguo para auditoria externa.
3. Planejamento tecnico fica travado entre implementacao e re-scope.
## Target
Decisao implementada e test-backed para encerrar `deferred` com status claro.
## Dependencies
Prerequisitos variam por trilha:
1. Trilha A (implementar): depende de extensao do modelo `IRBackend/IRVM` para opcodes e verificacao.
2. Trilha B (re-scope): depende de alinhamento normativo com specs/decision.
## Scope
1. Trilha A:
- adicionar suporte `SPAWN/YIELD`,
- validar aridade e stack constraints,
- cobrir com testes positivos/negativos.
2. Trilha B:
- ajustar documentos para deixar explicito que nao e parte do profile v1 claimado,
- atualizar matriz e policy de claim.
## Non-Goals
1. Nao introduzir modelo completo de concorrencia/corrotina alem do minimo normativo.
2. Nao conflitar com autoridade de runtime/ISA.
## Method
### O que deve ser feito explicitamente
1. Escolher uma trilha oficial (A ou B) por decisao registrada.
2. Executar implementacao ou re-scope end-to-end (codigo + specs + matriz).
3. Garantir que `G20-9.4.2` e `G20-9.4.3` saiam de `deferred` para `pass` (A) ou status normativo explicitamente nao-aplicavel no claim v1 (B).
## Acceptance Criteria
1. Nao existe mais ambiguidade sobre `SPAWN/YIELD` no claim atual.
2. Matriz e specs refletem exatamente o comportamento implementado e claimado.
3. Gate de conformidade nao deixa regressao silenciosa nesses itens.
## Tests
1. Trilha A:
- testes de lowering/validator para `SPAWN` arg count e `YIELD` stack constraint.
2. Trilha B:
- testes de integridade documental/policy com checks de claim.
## Affected Documents
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
2. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
3. `docs/general/specs/17. Compatibility and Evolution Policy.md`
4. `docs/pbs/decisions/*` (decision de escopo, quando aplicavel)
## Open Questions
1. Qual trilha oficial deve ser adotada: implementacao v1 (A) ou re-scope de claim (B)?
@@ -0,0 +1,73 @@
# PR-07.1 - OptimizeIRVM Span and Source-Hook Preservation
## Briefing
A matriz de conformidade ainda marca `G21-7.5` como `partial`.
Hoje existe evidencia de spans no lowering, mas falta regressao dedicada provando que passes de `OptimizeIRVM` preservam hooks de atribuicao de origem (spans/source hooks) apos reescritas de instrucoes e remapeamento de saltos.
## Motivation
### Dor atual que esta PR resolve
1. Risco de regressao silenciosa em spans durante otimização.
2. Evidencia insuficiente para fechar `G21-7.5`.
3. Diagnosticos pos-otimizacao podem perder rastreabilidade sem prova dedicada.
## Target
Fechar `G21-7.5` com suite de regressao explicita para preservacao de source hooks/spans no caminho `LowerToIRVM -> OptimizeIRVM -> EmitBytecode`.
## Dependencies
Prerequisitos diretos:
1. `PR-06.2` (harness de equivalencia de otimizacao).
2. `PR-06.3` (passes reais de reescrita/remocao no optimizer).
## Scope
1. Testes dedicados para verificacao de span retention por pass:
- `UnreachableInstructionEliminationPass`,
- `NormalizeRedundantJumpTargetsPass`,
- `SimplifyJumpToNextPcPass`.
2. Assercoes de preservacao de `BytecodeEmitter.Operation.span` para operacoes sobreviventes.
3. Assercoes de preservacao de spans em operacoes de salto apos remapeamento de target.
4. Atualizacao da matriz para converter `G21-7.5` de `partial` para `pass`.
## Non-Goals
1. Nao introduz novo formato de source map.
2. Nao altera contrato de diagnostico fora do backend pipeline.
## Method
### O que deve ser feito explicitamente
1. Criar fixture IRVM com spans distintos por instrucao/op.
2. Executar optimize com passes reais e comparar mapeamento de spans esperado no output.
3. Incluir caso com salto reescrito para validar span do salto apos remap.
4. Incluir caso com eliminacao de instrucoes para validar que operacoes restantes mantem spans originais.
5. Atualizar matriz (`docs/general/specs/22...`) com referencias aos novos testes.
## Acceptance Criteria
1. Existe suite de teste dedicada para preservacao de spans/source hooks no optimizer.
2. Reescritas de salto preservam spans da operacao original.
3. Eliminacao de instrucoes nao corrompe spans das operacoes remanescentes.
4. `G21-7.5` evolui para `pass`.
## Tests
1. Novos testes em `backend/irvm` (ex.: `OptimizeIRVMSourceAttributionTest` ou equivalente).
2. Reexecucao obrigatoria:
- `:prometeu-compiler:prometeu-build-pipeline:test`
## Affected Documents
1. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md`
2. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
Sem bloqueios arquiteturais.
@@ -0,0 +1,74 @@
# PR-07.2 - PBS Callsite Category Without Textual Heuristics (Regression Fixtures)
## Briefing
A matriz de conformidade ainda marca `PBS13-12.2.2` como `partial`.
Ja existe enforce de metadados no contrato executavel, mas falta fixture regressiva dedicada para provar que o frontend/backend nao classifica callsite por heuristica textual quando identidades entram em colisao.
## Motivation
### Dor atual que esta PR resolve
1. Ambiguidade residual na evidencia de `CALL_FUNC/CALL_HOST/CALL_INTRINSIC`.
2. Risco de regressao para classificacao por nome textual em casos limítrofes.
3. `PBS13-12.2.2` permanece `partial` por falta de caso dedicado de identidade ambigua.
## Target
Fechar `PBS13-12.2.2` com fixtures explicitas de identidade e ambiguidade, garantindo que categoria de callsite e derivada de identidade semantica/admitida, nao de heuristica textual.
## Dependencies
Prerequisitos diretos:
1. `PR-05.2` (classificacao de callsite por identidade semantica).
2. `PR-05.0.1` e `PR-05.0.6` (name/host identity foundation).
## Scope
1. Fixture positiva:
- nome textual com "cara de host", mas identidade resolvida como callable local -> deve lower para `CALL_FUNC`.
2. Fixture positiva:
- nome textual sobreposto entre dominios, com identidade univoca admitida para host ou intrinsic -> deve lower categoria correta.
3. Fixture negativa dedicada:
- colisao real entre categorias (callable/host/intrinsic) para o mesmo callsite -> rejeicao deterministica por ambiguidade.
4. Atualizacao de matriz para converter `PBS13-12.2.2` de `partial` para `pass`.
## Non-Goals
1. Nao altera gramatica PBS.
2. Nao redefine regras de admission de host/intrinsics fora do escopo desta prova.
## Method
### O que deve ser feito explicitamente
1. Adicionar testes em `PbsFrontendCompilerTest` (ou suite semantica correlata) para os tres cenarios acima.
2. Assertar `InstructionKind` resultante (`CALL_FUNC`, `CALL_HOST`, `CALL_INTRINSIC`) em casos positivos.
3. Assertar codigo diagnostico deterministico em caso ambiguo.
4. Garantir que nao ha branch de fallback por string pattern no caminho de lowering executavel.
5. Atualizar matriz de conformidade com referencias dos novos testes.
## Acceptance Criteria
1. Existe fixture dedicada cobrindo ambiguidade de categoria por identidade.
2. Casos positivos provam classificacao correta mesmo quando nome textual engana.
3. Caso ambiguo falha deterministicamente com diagnostico estavel.
4. `PBS13-12.2.2` evolui para `pass`.
## Tests
1. Novos testes no frontend PBS:
- `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
2. Reexecucao obrigatoria de integracao backend:
- `:prometeu-compiler:prometeu-build-pipeline:test`
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
Sem bloqueios arquiteturais.
@@ -0,0 +1,77 @@
# PR-07.3 - IRVM Entrypoint Export Emission for Runtime Loader Compatibility
## Briefing
Hoje um cartridge pode compilar com `entrypoint: "frame"` no `manifest.json` e `pub fn frame()` no `mod.barrel`, mas ainda falhar em runtime com `EntrypointNotFound`.
A causa observada e que o `program.pbx` pode ser emitido sem secao `exports` (section kind `4`), enquanto o loader resolve entrypoint nominal usando `program.exports`.
## Motivation
### Dor atual que esta PR resolve
1. Build aparentemente valido, mas falha de bootstrap em runtime.
2. Divergencia entre contrato de manifesto (`entrypoint` nominal) e artefato PBX emitido.
3. Falta de evidencia automatizada para evitar regressao de exports no caminho `IRBackend -> IRVM -> Bytecode`.
## Target
Corrigir o pipeline backend para sempre emitir export nominal do entrypoint no PBX de preload, garantindo compatibilidade com o loader quando o `manifest.json` declara entrypoint por nome.
## Dependencies
Prerequisitos diretos:
1. `PR-05.3` (politica deterministica de entrypoint no indice `0`).
2. `PR-05.4` (coerencia unica entre IRVM e EmissionPlan).
## Scope
1. `LowerToIRVMService` deve preencher `EmissionPlan.exports` com o simbolo do entrypoint apontando para `func_idx = 0`.
2. Adicionar regressao dedicada para garantir que `coherentEmissionPlan()` preserva export do entrypoint.
3. Validar serializacao PBX com secao `exports` presente quando houver entrypoint nominal.
4. Cobrir cenario de integracao onde `manifest.entrypoint = "frame"` inicializa VM sem `EntrypointNotFound`.
## Non-Goals
1. Nao exportar toda a superficie de funcoes executaveis neste passo.
2. Nao alterar formato binario PBX alem da presenca correta da secao `exports`.
3. Nao mudar semantica de resolucao por indice numerico de entrypoint.
## Method
### O que deve ser feito explicitamente
1. No `LowerToIRVMService`, construir `BytecodeEmitter.EmissionPlan` com `exports` contendo, no minimo, `Export(entryPointCallableName, 0)`.
2. Garantir determinismo do export do entrypoint a partir da mesma politica que fixa `func_id = 0`.
3. Adicionar teste unitario em `LowerToIRVMServiceTest` para verificar export nominal do entrypoint no plano coerente.
4. Adicionar teste de emissao/link para verificar secao `exports` no modulo serializado.
5. Adicionar teste de integracao runtime-backed para falhar se regressar para `EntrypointNotFound` em cartridge com entrypoint nominal valido.
## Acceptance Criteria
1. Build de projeto PBS com entrypoint `frame` gera PBX com secao `exports`.
2. O simbolo `frame` aponta para `func_idx = 0` no artefato emitido.
3. Execucao de cartridge com `manifest.entrypoint = "frame"` nao falha por `EntrypointNotFound` quando o programa contem o entrypoint admitido.
4. Rebuilds equivalentes produzem mapping de export deterministico.
## Tests
1. Novos testes de backend:
- `:prometeu-compiler:prometeu-build-pipeline:test`
2. Reexecucao de compatibilidade runtime-backed:
- `:prometeu-compiler:prometeu-build-pipeline:test --tests *Runtime*`
3. Smoke local recomendado:
- `./runtime/prometeu build .`
- `./runtime/prometeu run cartridge`
## Affected Documents
1. `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md`
4. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Em evolucao futura, devemos exportar apenas o entrypoint ou tambem funcoes explicitamente marcadas para linking externo?
@@ -0,0 +1,80 @@
# PR-08.1 - Intrinsic Resolution by Canonical Identity (Owner+Name+Version)
## Briefing
Hoje a resolucao de intrinsic no frontend PBS ainda depende de chave por `sourceMethodName` simples.
Isso permite ambiguidade quando existem metodos com o mesmo nome em owners diferentes e enfraquece o contrato de canonical addressing.
## Motivation
### Dor atual que esta PR resolve
1. Ambiguidade potencial de resolucao de intrinsic por nome de metodo sem owner.
2. Dependencia implícita de heuristica textual ao inves de identidade canonica.
3. Risco de regressao quando ampliar superficie de builtins/intrinsics stateful.
## Target
Tornar a resolucao de `CALL_INTRINSIC` no frontend semanticamente canonica e nao ambigua, usando chave composta deterministica:
1. `owner canonical`,
2. `intrinsic name canonical`,
3. `canonical version`.
## Dependencies
Prerequisitos diretos:
1. `PR-05.2` (classificacao de callsite sem heuristica textual).
2. `PR-07.2` (regressao contra heuristica textual de categoria).
## Scope
1. Substituir o map por `sourceMethodName` no lowering executavel por indice por identidade canonica.
2. Ajustar `PbsReservedMetadataExtractor`/surface helper para expor owner canonical explicitamente na chave de resolucao.
3. Tornar erro de ambiguidade explicito quando mais de uma intrinsic disputar o mesmo callsite apos resolver receiver/owner.
4. Cobrir cenarios com nomes repetidos em owners diferentes.
## Non-Goals
1. Nao alterar ids finais de intrinsics no bytecode/runtime nesta PR.
2. Nao introduzir novo opcode.
3. Nao expandir parser/sintaxe de `IntrinsicCall`.
## Method
### O que deve ser feito explicitamente
1. Introduzir chave tipada para intrinsic de lowering (ex.: `IntrinsicResolutionKey(ownerCanonical, nameCanonical, version)`).
2. Popular lookup de intrinsics com essa chave em vez de `sourceMethodName`.
3. Resolver owner canonical a partir do receiver sem fallback textual opaco.
4. Rejeitar deterministicamente callsite intrinsic sem mapeamento canonico univoco.
5. Adicionar testes positivos/negativos para:
- owners distintos com mesmo metodo,
- override de versao,
- callsite sem receiver compativel.
## Acceptance Criteria
1. Nenhum callsite intrinsic e resolvido apenas por `sourceMethodName`.
2. Colisao de metodo entre owners diferentes nao gera escolha implicita.
3. Diagnosticos de ambiguidade/nao resolucao sao estaveis e testados.
4. Build equivalente gera mesma classificacao e mesmo `intrinsicPool`.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
2. `:prometeu-compiler:prometeu-build-pipeline:test --tests *LowerToIRVMServiceTest*`
3. Regressao dedicada para callsites `input.pad.*` vs outros owners com nome coincidente.
## Affected Documents
1. `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
2. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
3. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
4. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. O contrato final deve expor owner canonico como campo separado em `IntrinsicSurface`, ou apenas como nome canonico fully-qualified?
@@ -0,0 +1,79 @@
# PR-08.2 - IRBackend Module Identity via Dense Table (ModuleId + ModulePool)
## Briefing
`moduleKey` hoje e string no contrato executavel e vira identificador estrutural em multiplos pontos.
Isso funciona, mas ainda nao aproveita plenamente a infraestrutura de dense tables ja existente (`ModuleTable`/`ModuleId`) para identidade canonica de modulo no handoff FE->BE.
## Motivation
### Dor atual que esta PR resolve
1. Identidade de modulo dependente de serializacao textual (`project:path`) no contrato.
2. Maior risco de drift/normalizacao inconsistente entre fronteiras.
3. Custo de comparacao/armazenamento pior do que id tipado em larga escala.
## Target
Evoluir o contrato `IRBackend` para carregar identidade de modulo tipada por dense table:
1. `ModuleId` nas entidades executaveis,
2. `modulePool` canonico no payload,
3. `moduleKey` textual mantido apenas como campo auxiliar/debug no periodo de transicao.
## Dependencies
Prerequisitos diretos:
1. `PR-05.0.2` (infra de `ModuleId` e `ModuleTable`).
2. `PR-05.0.3` (migração previa de ids tipados no contrato executavel).
## Scope
1. Introduzir `modulePool` no `IRBackend` e remapeamento na agregacao multi-arquivo.
2. Trocar referencias estruturais de modulo para `ModuleId` em executable/callable surfaces.
3. Adaptar sorting/canonical ordering para usar `ModuleId` + leitura canonica da tabela.
4. Preservar backward compatibility local durante migracao (camada de adaptacao).
## Non-Goals
1. Nao redefinir formato PBX nesta PR.
2. Nao alterar semantica de modulo no parser/linker.
3. Nao remover imediatamente todos os campos textuais de debug.
## Method
### O que deve ser feito explicitamente
1. Adicionar `modulePool: ReadOnlyList<ModuleReference>` em `IRBackend`.
2. Adicionar `moduleId` em `IRBackendExecutableFunction` e `CallableSignatureRef` (ou equivalente de assinatura).
3. Atualizar `IRBackendAggregator` para reindexar modulos via `ModuleTable` (dense table).
4. Atualizar FE PBS para emitir `moduleId` usando tabela canonica de modulos.
5. Atualizar BE (`LowerToIRVMService`) para ordenar por identidade de modulo canonica sem dependencia de concat textual.
6. Incluir testes de determinismo para remapeamento multi-modulo com ids estaveis.
## Acceptance Criteria
1. `IRBackend` possui pool canonico de modulos com ids densos.
2. Caminho estrutural nao depende de `moduleKey` string para identidade.
3. Merges de `IRBackendFile` preservam reindexacao deterministica de modulo.
4. Funcoes equivalentes em builds equivalentes recebem ids de modulo identicos.
## Tests
1. `:prometeu-compiler:prometeu-frontend-api:test`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
3. `:prometeu-compiler:prometeu-build-pipeline:test`
4. Novos testes de agregacao multi-modulo com colisao textual potencial.
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
4. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Fase de transicao deve manter `moduleKey` como shadow field por quantas ondas?
@@ -0,0 +1,80 @@
# PR-08.3 - Qualified Entrypoint Identity (No Name-Only Resolution)
## Briefing
A selecao de entrypoint no backend ainda filtra apenas por `callableName`.
Em projetos multi-modulo isso amplia risco de ambiguidade e cria acoplamento desnecessario a nomes globais.
## Motivation
### Dor atual que esta PR resolve
1. Ambiguidade de entrypoint quando existem callables homonimos.
2. Diagnostico tardio por nome sem contexto de modulo.
3. Divergencia potencial entre contrato de frontend e selecao real no backend.
## Target
Evoluir o contrato para entrypoint qualificado e deterministico:
1. `entryPointCallableName` + `entryPointModuleId` (ou `entryPointCallableId`),
2. resolucao backend por identidade qualificada,
3. politicas de erro claras para mismatch/ausencia.
## Dependencies
Prerequisitos diretos:
1. `PR-08.2` (ModuleId no contrato IRBackend).
2. `PR-05.3` (politica deterministica de indexacao e `func_id=0`).
## Scope
1. Expandir `FrontendSpec` e handoff FE para declarar entrypoint qualificado.
2. Atualizar `IRBackend` para carregar declaracao qualificada de entrypoint.
3. Atualizar `LowerToIRVMService` para selecionar entrypoint por identidade qualificada.
4. Preservar fallback de compatibilidade durante migracao (com warning deterministico).
## Non-Goals
1. Nao alterar semantica de `func_id=0`.
2. Nao mudar contrato de manifesto de cartridge nesta PR.
3. Nao introduzir multiple entrypoints por linguagem.
## Method
### O que deve ser feito explicitamente
1. Introduzir estrutura de entrada qualificada (ex.: `EntrypointRef(moduleId, callableName)`).
2. Popular estrutura no frontend PBS a partir do modulo de `frame`.
3. Modificar `orderFunctions` para usar referencia qualificada.
4. Em caso de fallback por nome, emitir diagnostico de deprecacao controlado.
5. Adicionar testes para:
- homonimos em modulos distintos,
- entrypoint valido qualificado,
- entrypoint ausente com erro estavel.
## Acceptance Criteria
1. Selecao de entrypoint nao depende apenas de nome.
2. Homonimos em modulos distintos nao geram ambiguidade quando entrypoint qualificado existe.
3. `func_id=0` continua pertencendo ao entrypoint declarado.
4. Rebuilds equivalentes mantem func ordering deterministico.
## Tests
1. `:prometeu-compiler:prometeu-frontend-api:test`
2. `:prometeu-compiler:prometeu-build-pipeline:test --tests *LowerToIRVMServiceTest*`
3. Testes de integracao com dois modulos contendo `frame`.
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
4. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Melhor contrato final: `EntrypointRef(moduleId, callableName)` ou `CallableId` global direto?
@@ -0,0 +1,72 @@
# PR-08.4 - CALL_FUNC Callee Module Identity Correctness
## Briefing
No lowering executavel PBS, instrucoes `CALL_FUNC` podem carregar `calleeModuleKey` do contexto local, e nao necessariamente do callable alvo.
Isso compromete rastreabilidade, debug e futuras validacoes de linking por modulo.
## Motivation
### Dor atual que esta PR resolve
1. Metadado de callsite incorreto para chamadas inter-modulo.
2. Dificulta diagnostico e verificacao de integridade no backend.
3. Introduz risco de regressao quando modulo vira identidade tipada no contrato.
## Target
Garantir que todo `CALL_FUNC` preserva identidade real do alvo (`callee module`) de forma deterministica, sem usar contexto local como proxy.
## Dependencies
Prerequisitos diretos:
1. `PR-05.0.4` (assinatura/callable internados).
2. `PR-08.2` (quando `ModuleId` tipado estiver ativo, usar id do alvo).
## Scope
1. Corrigir montagem de callsite para puxar modulo do `calleeCallableId` resolvido.
2. Ajustar modelos auxiliares de resolucao de callable para incluir modulo do alvo.
3. Expandir testes de lowering com chamadas cross-module.
## Non-Goals
1. Nao alterar categoria de callsite.
2. Nao introduzir linking dinamico de funcoes.
3. Nao alterar bytecode emitido para opcodes de chamada.
## Method
### O que deve ser feito explicitamente
1. Enriquecer lookup de callable para retornar identidade completa (`callableId + module identity`).
2. Em `CALL_FUNC`, preencher `callee module` com identidade do alvo real.
3. Adicionar validacao de consistencia em contrato executavel para evitar modulo invalido em chamada.
4. Criar regressao com:
- modulo A chamando funcao em modulo B,
- assert do modulo do callee no IRBackend.
## Acceptance Criteria
1. Nenhuma instrução `CALL_FUNC` usa modulo local quando alvo e externo.
2. Testes cross-module passam com metadado correto de callee.
3. Diagnosticos mantem atribuicao correta em falhas de resolucao.
4. Contrato segue deterministico em rebuilds equivalentes.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsFrontendCompilerTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PBSFrontendPhaseServiceTest*`
3. `:prometeu-compiler:prometeu-build-pipeline:test --tests *LowerToIRVMPipelineStageTest*`
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Durante a transicao, manter `calleeCallableName` textual para debug ou derivar sempre da assinatura por id?
@@ -0,0 +1,74 @@
# PR-08.5 - Intrinsic Registry Single Source of Truth (Compiler <-> Runtime)
## Briefing
O compiler backend hoje possui `IRVMIntrinsicRegistry` hardcoded e o runtime possui registry propio em `builtins.rs`.
Mesmo estando alinhados agora, a manutencao manual em dois lugares cria risco alto de drift.
## Motivation
### Dor atual que esta PR resolve
1. Duplicacao de source-of-truth para ids finais de intrinsic.
2. Risco de regressao silenciosa quando runtime evoluir surface intrinsic.
3. Custo operacional para garantir paridade manual em cada mudanca.
## Target
Estabelecer uma fonte unica versionada para mapeamento canonico de intrinsics (`canonicalName@version -> finalId`) e consumir isso em compiler + runtime com teste de paridade automatizado.
## Dependencies
Prerequisitos diretos:
1. `PR-08.1` (resolucao canonica consistente no frontend).
2. `PR-05.7` (caminho de verificacao runtime-backed robusto).
## Scope
1. Definir artefato de registry canonico (ex.: JSON/TOML) sob controle de versionamento.
2. Gerar/consumir mapeamento no compiler (`IRVMIntrinsicRegistry`) a partir desse artefato.
3. Adicionar checagem de paridade em teste para impedir divergencia com runtime.
4. Documentar fluxo de evolucao de intrinsic id sem quebra de compatibilidade.
## Non-Goals
1. Nao reescrever todas as implementacoes de intrinsic do runtime nesta PR.
2. Nao alterar semantica de execucao de `INTRINSIC`.
3. Nao migrar para discovery dinamico em tempo de execucao.
## Method
### O que deve ser feito explicitamente
1. Introduzir arquivo canonico de registry em local acordado (`docs` ou `shared metadata`).
2. Criar utilitario de leitura/geracao para preencher `IRVMIntrinsicRegistry` no compiler.
3. Adicionar teste no compiler que compara mapeamento esperado com runtime (snapshot/paridade).
4. Adicionar regra de CI para falhar em desvio de paridade.
5. Atualizar docs de contribuicao para fluxo de adicao/upgrade de intrinsics.
## Acceptance Criteria
1. Existe uma unica fonte versionada de mapeamento de intrinsic ids finais.
2. Compiler nao depende de lista manual duplicada para esse mapeamento.
3. CI falha quando runtime e compiler divergem em identidade/ID de intrinsic.
4. Inclusao de nova intrinsic segue workflow documentado e testavel.
## Tests
1. `:prometeu-compiler:prometeu-build-pipeline:test --tests *Intrinsic*`
2. Teste de paridade compiler-runtime dedicado.
3. Smoke runtime-backed com intrinsic valido e id invalido.
## Affected Documents
1. `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
4. `../runtime/docs/runtime/specs/06-input-peripheral.md`
5. `../runtime/docs/runtime/specs/02-vm-instruction-set.md`
## Open Questions
1. Melhor local da fonte unica: repo `runtime`, repo `studio`, ou pacote compartilhado dedicado?
@@ -0,0 +1,81 @@
# PR-09.1 - IRBackend Contract Cut: Remove `moduleKey` and `calleeModuleKey` (String)
## Briefing
O contrato executavel ainda carrega `moduleKey` textual como trilha de compatibilidade.
Isso mantem dupla identidade (`ModuleId` + string) em area critica de handoff.
## Motivation
### Dor atual que esta PR resolve
1. Identidade estrutural ainda pode cair em fallback textual.
2. Contrato permite dados redundantes e potencialmente divergentes.
3. A transicao para dense-only ainda nao esta fechada.
## Target
Encerrar a transicao no contrato FE->BE:
1. remover `moduleKey` de `IRBackendExecutableFunction`,
2. remover `calleeModuleKey` de instrucoes executaveis,
3. remover `moduleKey` de `CallableSignatureRef`,
4. eliminar parsing/fallback textual em `IRBackendAggregator`.
## Dependencies
Prerequisitos diretos:
1. `PR-08.2`
2. `PR-08.3`
3. `PR-08.4`
## Scope
1. Atualizar modelos em `prometeu-frontend-api` e `prometeu-compiler-core`.
2. Remover construtores de compatibilidade que aceitam `moduleKey` string.
3. Atualizar agregacao para reindexar apenas por `ModuleId` + `modulePool`.
4. Atualizar todos os testes afetados.
## Non-Goals
1. Nao alterar formato PBX nesta PR.
2. Nao mudar semantica de host/intrinsic callsites.
## Method
### O que deve ser feito explicitamente
1. Em `IRBackendExecutableFunction`:
- remover campo `moduleKey`,
- remover `calleeModuleKey`,
- manter apenas `ModuleId` estrutural.
2. Em `CallableSignatureRef`:
- remover `moduleKey`,
- manter `moduleId` + assinatura.
3. Em `IRBackend` agregador:
- remover `moduleReferenceFromKey(...)` e qualquer fallback textual.
4. Em testes:
- converter fixtures para `ModuleId` + `modulePool`.
## Acceptance Criteria
1. Nao existe mais `moduleKey` string em contratos estruturais FE/BE.
2. Reindexacao multi-file usa somente dense tables.
3. Build/test passam sem camadas de compatibilidade textual.
## Tests
1. `:prometeu-compiler:prometeu-compiler-core:test`
2. `:prometeu-compiler:prometeu-frontend-api:test`
3. `:prometeu-compiler:prometeu-build-pipeline:test`
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Nenhuma. Esta PR fecha corte de transicao.
@@ -0,0 +1,68 @@
# PR-09.2 - PBS Frontend Lowering: ModuleId-Only (No `moduleKey` in lowering surfaces)
## Briefing
Mesmo apos o contrato aceitar `ModuleId`, o lowering PBS ainda trafega `moduleKey` em estruturas internas (`ImportedCallableSurface`, indices auxiliares e fixtures).
## Motivation
### Dor atual que esta PR resolve
1. FE ainda acopla resolucao de callable/import a string de modulo.
2. A remocao de `moduleKey` no contrato quebra se FE nao migrar totalmente.
3. Risco de divergencia entre metadado textual e identidade internada.
## Target
Migrar lowering PBS para `ModuleId` como identidade unica:
1. `ImportedCallableSurface` sem `moduleKey`,
2. callsite/callable lookup por ids internados,
3. diagnosticos e logs usando renderizacao derivada de `modulePool` apenas quando necessario.
## Dependencies
Prerequisito direto:
1. `PR-09.1`
## Scope
1. Atualizar `PbsFrontendCompiler` para operar com `ModuleId` nas superfices de import/callable.
2. Atualizar `PBSFrontendPhaseService` para fornecer metadados densos sem string estrutural.
3. Atualizar testes PBS e artifacts golden.
## Non-Goals
1. Nao alterar parser PBS.
2. Nao alterar admission de host capabilities.
## Method
### O que deve ser feito explicitamente
1. Remover `moduleKey` de `ImportedCallableSurface`.
2. Em `collect/lower callsites`, propagar `calleeModuleId` via assinatura internada.
3. Ajustar renderizacao de debug para usar `modulePool` quando mostrar modulo.
4. Atualizar golden printer para mostrar `moduleId` (e opcionalmente nome renderizado derivado).
## Acceptance Criteria
1. FE PBS nao depende de `moduleKey` string para resolver/importar/lower callables.
2. Todas as callsites `CALL_FUNC` carregam `calleeModuleId` coerente.
3. Testes PBS passam sem acessos estruturais a chave textual.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
2. `:prometeu-compiler:prometeu-frontend-api:test --tests *IRBackendExecutableContractTest*`
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Nenhuma. Regra fica `ModuleId`-only para identidade estrutural.
@@ -0,0 +1,72 @@
# PR-09.3 - LowerToIRVM: ModuleId-Only Ordering + Strict Qualified Entrypoint
## Briefing
`LowerToIRVMService` ainda possui fallback para `moduleKey` textual e fallback de entrypoint por nome quando `entryPointModuleId` nao e informado.
## Motivation
### Dor atual que esta PR resolve
1. Ordenacao de funcoes ainda pode depender de string legado.
2. Entrypoint pode cair em selecao name-only, mantendo ambiguidade residual.
3. Contrato qualificado existe, mas nao e estrito.
## Target
Tornar lowering estritamente orientado por identidade:
1. ordenacao por `ModuleId -> modulePool` somente,
2. entrypoint obrigatoriamente qualificado (`entryPointModuleId + callableName`),
3. remover fallback textual/heuristico.
## Dependencies
Prerequisitos diretos:
1. `PR-09.1`
2. `PR-09.2`
## Scope
1. Atualizar `LowerToIRVMService` para eliminar `fallbackModuleKey`.
2. Validar presenca obrigatoria de `entryPointModuleId` para entrada executavel.
3. Atualizar testes de ordenacao, ambiguidades e erros deterministas.
## Non-Goals
1. Nao alterar regra `func_id=0` (continua entrypoint).
2. Nao alterar emissao de opcodes.
## Method
### O que deve ser feito explicitamente
1. Substituir `moduleSortKey(...)` textual por leitura canonica direta do `modulePool` indexado por `ModuleId`.
2. Em `orderFunctions`, rejeitar entrada sem `entryPointModuleId`.
3. Remover caminho de erro/controle baseado em entrypoint name-only.
4. Cobrir com testes:
- entrypoint qualificado valido,
- entrypoint qualificado ausente,
- homonimos em modulos distintos com qualificacao.
## Acceptance Criteria
1. Nenhum fallback para `moduleKey` no LowerToIRVM.
2. Entrypoint e sempre resolvido por identidade qualificada.
3. Determinismo preservado em rebuild equivalente.
## Tests
1. `:prometeu-compiler:prometeu-build-pipeline:test --tests *LowerToIRVMServiceTest*`
2. `:prometeu-compiler:prometeu-build-pipeline:test --tests *BackendSafetyGateSUTest*`
## Affected Documents
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
2. `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Nenhuma. Esta PR fecha o fallback de entrypoint name-only.
@@ -0,0 +1,84 @@
# PR-09.4 - Specs Refresh: ModuleId-Only + EntrypointRef Normative Alignment
## Briefing
Com a remocao estrutural de `moduleKey`, as specs normativas precisam refletir:
1. identidade de modulo densa (`ModuleId`),
2. entrypoint qualificado (`EntrypointRef`),
3. ausencia de fallback textual.
## Motivation
### Dor atual que esta PR resolve
1. Specs ainda descrevem partes name-only/text-based em pontos criticos.
2. Matriz pode afirmar `pass` sem refletir contratos mais estritos.
3. Risco de regressao por lacuna documento->implementacao.
## Target
Atualizar o baseline normativo para o modelo final:
1. `IRBackend` estrutural sem `moduleKey`,
2. `EntrypointRef(moduleId, callableName)` obrigatorio em handoff executavel,
3. ordenacao/lowering sem dependencias textuais.
## Dependencies
Prerequisitos diretos:
1. `PR-09.1`
2. `PR-09.2`
3. `PR-09.3`
## Scope
1. Revisar e atualizar specs:
- PBS 13 (Lowering IRBackend),
- General 20 (IRBackend -> IRVM),
- General 15 (Bytecode mapping entrypoint linkage),
- General 22 (matriz de conformidade).
2. Registrar decisao de corte definitivo (`moduleKey` removido).
## Non-Goals
1. Nao alterar implementação de runtime nesta PR.
2. Nao introduzir novo formato de arquivo para `program.pbx`.
## Method
### O que deve ser feito explicitamente
1. Em PBS13 e G20:
- trocar obrigacoes name-only por `EntrypointRef` qualificado,
- declarar `ModuleId` como identidade estrutural unica.
2. Em G15:
- manter `func_id=0` como entrypoint selecionado por `EntrypointRef`.
3. Em G22:
- adicionar/ajustar requirement rows para:
- no-moduleKey structural identity,
- strict qualified entrypoint,
- moduleid-only ordering.
## Acceptance Criteria
1. Nenhuma spec normativa relevante menciona `moduleKey` como identidade estrutural.
2. Matriz de conformidade cobre explicitamente obrigações novas.
3. `BackendConformanceMatrixSpecTest` e gate hard-policy permanecem verdes.
## Tests
1. `:prometeu-compiler:prometeu-build-pipeline:test --tests *BackendConformanceMatrixSpecTest*`
2. `:prometeu-compiler:prometeu-build-pipeline:test --tests *BackendClaimScopeSpecTest*`
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
4. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Nenhuma. Esta PR e de alinhamento normativo.
@@ -0,0 +1,76 @@
# PR-09.5 - Hard Gates: No-`moduleKey` Regression + Migration Cleanup
## Briefing
Depois do corte `ModuleId`-only, precisamos impedir reintroducao acidental de `moduleKey` estrutural e limpar residuos de migracao.
## Motivation
### Dor atual que esta PR resolve
1. Sem gate dedicado, regressao textual pode voltar por conveniencia.
2. Testes/golden antigos ainda podem carregar nomenclatura de transicao.
3. Confianca de manutencao cai sem verificacao automatica de proibicao.
## Target
Fechar o ciclo de migracao:
1. adicionar gate anti-regressao (`moduleKey` proibido em contratos estruturais),
2. atualizar fixtures/golden para contrato final,
3. consolidar notas de migracao e contribuicao.
## Dependencies
Prerequisitos diretos:
1. `PR-09.1`
2. `PR-09.2`
3. `PR-09.3`
4. `PR-09.4`
## Scope
1. Criar teste/lint de proibicao para `moduleKey` em pacotes de contrato/lowering.
2. Atualizar `golden` de frontend/backend para `ModuleId`-only.
3. Atualizar docs de contribuicao para adicao de callables/modulos sem chave textual.
## Non-Goals
1. Nao alterar semantica de parser/lexer PBS.
2. Nao introduzir novo gate externo ao gradle test.
## Method
### O que deve ser feito explicitamente
1. Adicionar teste de policy:
- falha se campos/assinaturas estruturais de FE/BE usarem `moduleKey`.
2. Atualizar snapshots golden e testes que assumiam debug key textual.
3. Registrar checklist de migracao final:
- FE lowering,
- IRBackend contract,
- LowerToIRVM,
- docs/matriz.
## Acceptance Criteria
1. Nao existe `moduleKey` em contratos estruturais FE/BE.
2. Gate automatizado falha ao tentar reintroduzir o campo.
3. Testes/golden passam no modo novo sem artefatos legados.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
2. `:prometeu-compiler:prometeu-frontend-api:test`
3. `:prometeu-compiler:prometeu-build-pipeline:test`
## Affected Documents
1. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
2. `docs/pbs/pull-requests/INDEX.md`
3. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
## Open Questions
1. Nenhuma. PR de fechamento e anti-regressao.
@@ -0,0 +1,84 @@
# PR-09.6 - ISA-Scoped Intrinsic Registry as Single Source of Truth
## Briefing
Hoje o mapeamento `canonicalName@version -> finalId` ainda e mantido em dois lugares (compiler e runtime), com teste de paridade.
Isso reduz risco, mas ainda nao elimina dual-authoring.
## Motivation
### Dor atual que esta PR resolve
1. Fonte duplicada para IDs finais de intrinsic.
2. Risco operacional de drift entre compiler e runtime.
3. Evolucao de intrinsics depende de sincronizacao manual.
## Target
Definir um artefato unico, versionado e vinculado ao profile ISA para o registry de intrinsics:
1. artefato canonico de registry (`intrinsic-registry-v1`),
2. ownership normativo no boundary ISA/profile,
3. consumo por compiler e runtime a partir da mesma fonte.
## Dependencies
Prerequisitos diretos:
1. `PR-08.5` (paridade compiler-runtime existente)
2. `PR-09.7` (normalizacao de consumo no compiler)
## Scope
1. Definir formato normativo do artefato (CSV/TOML/JSON) no boundary ISA.
2. Definir local canonico e versionamento do artefato.
3. Definir contrato de evolucao:
- adicao de intrinsic,
- deprecacao,
- compatibilidade de IDs.
4. Definir gate de paridade contra consumidores.
## Non-Goals
1. Nao alterar semantica de opcode `INTRINSIC`.
2. Nao redesenhar toda a arquitetura de builtins do runtime nesta PR.
## Method
### O que deve ser feito explicitamente
1. Criar documento de formato canonico do registry:
- chave canonica,
- versao canonica,
- final id,
- constraints de unicidade.
2. Declarar ownership do artefato no profile ISA.
3. Definir pipeline de validacao:
- parser estrito,
- check de unicidade de identity e final id,
- check de ordenacao deterministica.
4. Definir workflow de manutencao para adicao de intrinsic.
## Acceptance Criteria
1. Existe uma unica fonte versionada para IDs finais de intrinsic.
2. Runtime e compiler referenciam formalmente essa fonte.
3. Processo de evolucao de intrinsics fica deterministico e auditavel.
## Tests
1. Testes de parser/validacao do artefato canonico.
2. Testes de paridade de consumidores contra o artefato.
3. Gate de CI que falha em divergia do mapping.
## Affected Documents
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
2. `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
3. `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
4. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
5. Runtime specs correspondentes (ajuste posterior no repo runtime).
## Open Questions
1. Local canonico final do artefato: `runtime` (recomendado) ou `shared-metadata` dedicado. runtime
@@ -0,0 +1,76 @@
# PR-09.7 - Compiler Normalization to ISA Intrinsic Registry Artifact
## Briefing
Apos estabelecer o artefato unico do registry (PR-09.6), o compiler precisa consumir exclusivamente esse artefato e remover caminhos residuais de dual-authoring.
## Motivation
### Dor atual que esta PR resolve
1. Compiler ainda pode depender de representacao local paralela.
2. Teste de paridade atual com parse de `builtins.rs` e acoplamento fragil de formato.
3. Falta um caminho de consumo unico no pipeline backend.
## Target
Normalizar o lado compiler para source-of-truth unico:
1. `IRVMIntrinsicRegistry` carregando apenas o artefato canonico ISA,
2. remover/encapsular validacoes que dependem de parsing textual de runtime internals,
3. reforcar gate de consistencia do consumidor compiler.
## Dependencies
Prerequisito direto:
1. `PR-09.6`
## Scope
1. Ajustar `IRVMIntrinsicRegistry` para modo canonical-only.
2. Revisar testes de paridade:
- principal: paridade com artefato canonico,
- opcional/informativo: runtime-backed check separado.
3. Garantir mensagens de erro e diagnostico estaveis para registry invalido.
## Non-Goals
1. Nao alterar implementacao de intrinsics no runtime.
2. Nao mover ownership de docs runtime nesta PR.
## Method
### O que deve ser feito explicitamente
1. Consolidar parser/loader do registry no compiler com contrato estrito.
2. Substituir assercoes hardcoded por fixtures derivadas do artefato.
3. Separar teste de compatibilidade runtime:
- nao bloquear desenvolvimento local quando runtime repo ausente,
- bloquear em modo strict/CI quando configurado.
4. Atualizar docs de contribuicao do compiler para fluxo de update de intrinsics.
## Acceptance Criteria
1. Compiler nao tem mais fonte duplicada de mapping de intrinsic IDs.
2. `LowerToIRVMService` resolve IDs finais exclusivamente via artefato canonico.
3. Suite de testes backend cobre:
- carregamento valido,
- invalid registry,
- mismatch detectavel em strict mode.
## Tests
1. `:prometeu-compiler:prometeu-build-pipeline:test --tests *IRVMIntrinsicRegistry*`
2. `:prometeu-compiler:prometeu-build-pipeline:test --tests *LowerToIRVMServiceTest*`
3. `:prometeu-compiler:prometeu-build-pipeline:test --tests *BackendConformanceMatrixSpecTest*`
## Affected Documents
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
2. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
3. `docs/pbs/pull-requests/INDEX.md`
## Open Questions
1. Nenhuma bloqueante para lado compiler.
@@ -0,0 +1,69 @@
# PR-10.1 - PBS Parser Shared Context and Safe Delegation
## Briefing
`PbsParser` concentra estado compartilhado (`cursor`, `diagnostics`, `fileId`, `parseMode`, `loopDepth`) e responsabilidades de parsing em uma unica classe.
Esta PR introduz uma fundacao estrutural para decomposicao, sem alterar comportamento: um contexto compartilhado e pontos de delegacao seguros, mantendo `PbsParser` como fachada publica.
## Motivation
### Dor atual que esta PR resolve
1. Extracoes futuras dependem de copiar estado ou expor detalhes internos do parser.
2. O acoplamento entre navegação, diagnostico e parse impede quebrar a classe sem risco alto.
3. A refatoracao fica mais segura se a infraestrutura de compartilhamento vier antes da movimentacao de logica.
## Target
Estabelecer a base de refactor sem mudar funcionalidade:
1. Introduzir um contexto compartilhado para parser.
2. Encapsular helpers comuns de span/report/consume no contexto ou utilitarios proximos.
3. Permitir delegacao gradual para subparsers mantendo `PbsParser.parse(...)` como API unica.
## Dependencies
Nenhuma.
## Scope
1. Criar `ParserContext` ou equivalente com acesso a `cursor`, `diagnostics`, `fileId`, `parseMode` e `loopDepth`.
2. Mover helpers estruturais triviais para o contexto onde isso nao altere semantica.
3. Adaptar `PbsExprParser` bootstrap para consumir o mesmo contexto, ou uma visao compatível, sem mudar seu comportamento.
## Non-Goals
1. Nao alterar gramatica PBS.
2. Nao mover ainda parsing de tipos, atributos, blocos ou declaracoes para classes separadas.
3. Nao alterar mensagens, codigos de erro ou spans.
## Method
### O que deve ser feito explicitamente
1. Introduzir um objeto de contexto pequeno e explicito.
2. Manter `PbsParser` como orquestrador/fachada durante toda a PR.
3. Preservar o contrato de `parse(...)` e a ordem de consumo de tokens.
4. Validar que a nova camada e puramente estrutural.
## Acceptance Criteria
1. `PbsParser` continua sendo o unico entrypoint publico de parse.
2. Nenhum teste de parser, semantica ou frontend muda comportamento esperado.
3. Nao ha alteracao observavel em AST, spans ou diagnosticos.
4. A PR reduz acoplamento e prepara extracoes futuras sem mover regras complexas ainda.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. O `loopDepth` deve viver no contexto mutavel compartilhado ou em um helper especializado de block parsing? Esta PR pode manter no contexto; a decisao final pode vir na `PR-10.4`.
@@ -0,0 +1,70 @@
# PR-10.2 - PBS Parser Attribute and Type Subparsers
## Briefing
`PbsParser` ainda centraliza parsing de atributos, `typeRef` e `returnSpec`, que sao superficies coesas e amplamente reutilizadas.
Esta PR extrai essas responsabilidades para subparsers dedicados, sem alterar sintaxe aceita, AST produzido ou diagnosticos.
## Motivation
### Dor atual que esta PR resolve
1. `PbsParser` mistura topo de arquivo, declaracoes, blocos, atributos e tipos.
2. `parseTypeRef`, `parseAttribute*` e `parseCallableReturnSpec` sao hotspots claros de complexidade e reuso.
3. Sem extrair essa camada, as PRs seguintes continuam dependendo de uma classe central grande demais.
## Target
Separar parsing de tipos e atributos em colaboradores dedicados:
1. `PbsAttributeParser` ou equivalente.
2. `PbsTypeParser` ou equivalente.
3. Delegacao explicita a partir de `PbsParser`.
## Dependencies
Prerequisito direto:
1. `PR-10.1`
## Scope
1. Extrair `parseAttributeList`, `parseAttribute`, `parseAttributeArguments`, `parseAttributeArgument`, `parseAttributeValue`.
2. Extrair `parseTypeRef`, `parseNamedTupleTypeFields`, `parseCallableReturnSpec`, `parseReturnSpecFromMarker`, `isTypeStart`.
3. Preservar integralmente `PbsAst` e `ParseErrors`.
## Non-Goals
1. Nao alterar regras de atributos em modos `ORDINARY` e `INTERFACE_MODULE`.
2. Nao alterar aridade de named tuple.
3. Nao alterar recuperacao de erro alem do necessario para manter equivalencia.
## Method
### O que deve ser feito explicitamente
1. Mover parsing de atributos e tipos para classes pequenas, focadas e package-private.
2. Reusar o contexto compartilhado introduzido na PR anterior.
3. Manter `PbsParser` apenas como delegador nessas superficies.
4. Adicionar regressao para spans e diagnosticos de tipos/atributos se ainda nao houver cobertura suficiente.
## Acceptance Criteria
1. `PbsParser` deixa de implementar diretamente a maior parte do parsing de atributos e tipos.
2. AST e diagnosticos dessas superficies permanecem equivalentes.
3. A cobertura existente de parser continua verde sem mudancas semanticas.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsInterfaceModuleSemanticsTest*`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. Se `returnSpec` deve ficar no parser de tipos ou em um parser de callable surface. A recomendacao desta PR e manter em `PbsTypeParser`, porque o contrato de retorno depende diretamente de `typeRef`.
@@ -0,0 +1,73 @@
# PR-10.3 - PBS Parser Top-Level Declaration Decomposition
## Briefing
O maior concentrador de branching restante em `PbsParser` e a montagem de topo de arquivo e o dispatch de `declare ...`.
Esta PR extrai o parsing de declaracoes top-level e de corpos declarativos para colaboradores especificos, mantendo a mesma gramatica e o mesmo comportamento observavel.
## Motivation
### Dor atual que esta PR resolve
1. `parseFile` e `parseDeclareTopDecl` acumulam roteamento de muitas formas de declaracao.
2. Declaracoes como `host`, `builtin type`, `struct`, `contract`, `service`, `enum` e `implements` convivem no mesmo arquivo e elevam acoplamento.
3. Essa parte do parser muda com frequencia e hoje tem custo alto de manutencao.
## Target
Separar a camada de declaracoes top-level:
1. parsing de imports,
2. dispatch de `declare`,
3. parsing de corpos declarativos,
4. roteamento por `ParseMode`.
## Dependencies
Prerequisitos diretos:
1. `PR-10.1`
2. `PR-10.2`
## Scope
1. Extrair `parseFile` em conjunto com o dispatch de topo para um colaborador dedicado.
2. Extrair `parseDeclareTopDecl` e parsers correlatos (`host`, `builtin type`, `struct`, `contract`, `service`, `error`, `enum`, `callback`, `const`, `implements`).
3. Preservar o comportamento atual de atributos permitidos/proibidos por tipo de declaracao.
## Non-Goals
1. Nao alterar a ordem de imports/declarations no AST.
2. Nao alterar as regras de `INTERFACE_MODULE`.
3. Nao reescrever `PbsExprParser`.
## Method
### O que deve ser feito explicitamente
1. Criar um `PbsTopLevelParser` e um `PbsDeclarationParser`, ou divisao equivalente.
2. Manter em `PbsParser` apenas a montagem final da fachada e o fio de chamada principal.
3. Extrair por familias coesas de declaracao, evitando uma nova classe monolitica.
4. Preservar sincronia/recovery de topo no mesmo fluxo observavel.
## Acceptance Criteria
1. `parseFile` e `parseDeclareTopDecl` deixam de concentrar o dispatch completo de todas as declaracoes.
2. O parse de topo continua deterministico e equivalente ao estado anterior.
3. Testes de parser e frontend continuam verdes sem necessidade de atualizar fixtures por mudanca funcional.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsBarrelParserTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsInterfaceModuleSemanticsTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `implements` deve ficar junto de declaracoes top-level gerais ou em um parser especializado de contract/service surfaces? A recomendacao e mantê-lo no parser top-level por depender fortemente do roteamento de arquivo.
@@ -0,0 +1,74 @@
# PR-10.4 - PBS Parser Block and Statement Decomposition
## Briefing
Depois de extrair tipos/atributos e declaracoes top-level, o maior hotspot restante de `PbsParser` passa a ser parsing de blocos e statements.
Esta PR separa `block`, `statement`, `assignment`, `loop` e controle de fluxo em um parser dedicado, sem alterar a funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. `parseBlock`, `parseStatement`, `parseIfStatement`, `parseForStatement` e correlatos mantem alta complexidade e forte acoplamento com `loopDepth`.
2. A mistura de statement parsing com helpers de token/erro dificulta evolucao e leitura.
3. O parser de blocos e o ponto mais sensivel para regressao e precisa de uma fronteira estrutural clara.
## Target
Extrair a superficie de blocos e statements para um colaborador dedicado:
1. blocos,
2. statements estruturados,
3. assignment detection,
4. controle de `loopDepth`.
## Dependencies
Prerequisitos diretos:
1. `PR-10.1`
2. `PR-10.2`
3. `PR-10.3`
## Scope
1. Extrair `parseBlock`, `parseStatement`, `parseLetStatement`, `parseAssignStatement`, `parseLValue`.
2. Extrair `parseIfStatement`, `parseForStatement`, `parseWhileStatement`, `parseBreakStatement`, `parseContinueStatement`, `parseReturnStatement`.
3. Extrair `isAssignmentStatementStart` e helpers locais associados.
## Non-Goals
1. Nao alterar regras de tail expression.
2. Nao alterar precedence de expressoes.
3. Nao alterar as mensagens atuais de erro para loop control e assignment targets.
## Method
### O que deve ser feito explicitamente
1. Introduzir um `PbsBlockParser` ou equivalente.
2. Encapsular `loopDepth` dentro do contexto compartilhado ou de uma API pequena de entrada/saida de loop.
3. Reutilizar `PbsExprParser` como dependencia, sem alterar seu contrato.
4. Preservar spans e forma de recovery dentro de blocos.
## Acceptance Criteria
1. `PbsParser` deixa de conter a maior parte do parsing de blocos e statements.
2. `loopDepth` continua correto para `break` e `continue`.
3. Nenhum teste de parser, semantica de flow ou lowering sofre alteracao funcional.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserStatementsTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsControlFlowTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsFallthroughTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `isAssignmentStatementStart` deve permanecer no parser de bloco ou virar helper de cursor/lookahead. A recomendacao e mantê-lo no parser de bloco nesta PR e avaliar extração posterior apenas se necessário.
@@ -0,0 +1,80 @@
# PR-10.5 - PBS Parser Recovery Utilities and Regression Hardening
## Briefing
As PRs anteriores reduzem a complexidade estrutural de `PbsParser`. Esta PR fecha a trilha com consolidacao de recovery/utilitarios e endurecimento de regressao, ainda sem alterar funcionalidade.
O objetivo e evitar que a decomposicao introduza pequenas divergencias em diagnosticos, spans ou pontos de reinicio.
## Motivation
### Dor atual que esta PR resolve
1. Recovery e helpers de consumo sao sensiveis e podem ficar duplicados apos a extracao.
2. Sem cobertura adicional, uma refatoracao estrutural grande pode preservar testes principais e ainda mudar detalhes de parser.
3. O parser precisa terminar menor, mas tambem com fronteiras de manutencao claras.
## Target
Consolidar a etapa final do refactor:
1. recovery de topo e de atributos,
2. helpers de consumo/report,
3. regressao de spans/diagnosticos,
4. limpeza final de `PbsParser`.
## Dependencies
Prerequisitos diretos:
1. `PR-10.1`
2. `PR-10.2`
3. `PR-10.3`
4. `PR-10.4`
## Scope
1. Consolidar `consume`, `consumeForToken`, `consumeDeclarationTerminator`, `consumeBalancedBraces`, `synchronizeTopLevel` e recovery de atributo em utilitarios coesos.
2. Remover duplicacao residual entre subparsers.
3. Adicionar ou endurecer testes de regressao para:
- spans,
- erros esperados,
- recovery em topo e em bloco,
- modos `ORDINARY` e `INTERFACE_MODULE`.
## Non-Goals
1. Nao alterar taxonomia de `ParseErrors`.
2. Nao introduzir novas construcoes sintaticas.
3. Nao reescrever o lexer ou `PbsExprParser`.
## Method
### O que deve ser feito explicitamente
1. Fazer uma passada final de consolidacao estrutural.
2. Eliminar helpers obsoletos ou duplicados apos as extracoes.
3. Verificar equivalencia observavel com foco em spans e recovery.
4. Encerrar a trilha com `PbsParser` como fachada pequena e clara.
## Acceptance Criteria
1. `PbsParser` fica restrito a composicao/orquestracao e nao volta a concentrar logica de parse pesado.
2. Recovery e consumo de token ficam centralizados e sem duplicacao relevante.
3. Suite do frontend PBS passa integralmente.
4. Nao ha mudanca funcional observavel em parse, AST ou diagnosticos.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserStatementsTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. Nenhuma de arquitetura. A partir desta PR, qualquer mudanca adicional deve ser tratada como evolucao funcional separada, nao como parte do refactor estrutural.
@@ -0,0 +1,68 @@
# PR-11.1 - PBS Expr Parser Shared Context and Precedence Spine
## Briefing
`PbsExprParser` hoje concentra estado compartilhado, helpers basicos e toda a espinha de precedence em uma unica classe.
Esta PR introduz a fundacao estrutural para decompor o parser de expressoes sem alterar comportamento: contexto compartilhado, helpers comuns e uma organizacao mais clara da cadeia de precedence.
## Motivation
### Dor atual que esta PR resolve
1. Extracoes futuras dependem de duplicar acesso a `cursor`, `diagnostics`, `fileId` e `blockParserDelegate`.
2. A cadeia de precedence existe, mas toda a infraestrutura esta acoplada a uma unica classe.
3. Refatorar primeiro a fundacao reduz risco antes de mover control-flow e postfix/primary.
## Target
Estabelecer uma base segura para o refactor de `PbsExprParser`:
1. contexto compartilhado,
2. helpers de span/report/consume reutilizaveis,
3. espinha de precedence claramente separada do restante.
## Dependencies
Nenhuma.
## Scope
1. Introduzir `ExprParserContext` ou equivalente.
2. Encapsular `cursor`, `diagnostics`, `fileId` e `blockParserDelegate` nessa camada.
3. Reorganizar a espinha de precedence (`parseExpression`, `parseApply`, `parseOr`, `parseAnd`, `parseEquality`, `parseComparison`, `parseAs`, `parseTerm`, `parseFactor`, `parseUnary`) sem mudar a ordem semantica.
## Non-Goals
1. Nao alterar associatividade ou precedence.
2. Nao mover ainda parsing de `if/switch/handle`.
3. Nao alterar `PbsParser` nem `PbsTokenCursor`.
## Method
### O que deve ser feito explicitamente
1. Criar um contexto compartilhado pequeno e explicito.
2. Manter `PbsExprParser` como entrypoint package-private.
3. Preservar a ordem atual de chamadas na chain de precedence.
4. Validar que esta PR e puramente estrutural.
## Acceptance Criteria
1. `PbsExprParser` continua com o mesmo contrato de entrada/saida.
2. Precedence e associatividade permanecem equivalentes.
3. Nao ha mudanca observavel em AST, spans ou diagnosticos de expressoes.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `blockParserDelegate` deve continuar como callback simples ou migrar para interface mais rica de surface parsing? Nesta PR, manter callback simples minimiza risco.
@@ -0,0 +1,72 @@
# PR-11.2 - PBS Expr Parser Control-Flow Subparsers
## Briefing
As formas de expressao com maior branching em `PbsExprParser` sao `if`, `switch`, `handle` e `else`.
Esta PR extrai essas construcoes para subparsers dedicados, mantendo a mesma sintaxe, mesmos diagnosticos e o mesmo AST.
## Motivation
### Dor atual que esta PR resolve
1. `if/switch/handle` compartilham recovery, parsing de blocos e recursion, elevando bastante a complexidade local.
2. Essas formas sao semanticamente coesas e podem viver fora do parser principal de precedence.
3. Sem essa extracao, `PbsExprParser` continua grande mesmo apos separar a fundacao.
## Target
Separar parsing de expressoes de controle de fluxo:
1. `handle`,
2. `else`,
3. `if expression`,
4. `switch expression`.
## Dependencies
Prerequisito direto:
1. `PR-11.1`
## Scope
1. Extrair `parseHandle`, `parseHandlePattern`, `parseElse`, `parseIfExpression`, `parseIfExpressionFromToken`, `parseSwitchExpression`, `parseSwitchPattern`.
2. Preservar uso de `parseSurfaceBlock` para blocos de expressao.
3. Manter exatamente a precedence atual dessas superficies.
## Non-Goals
1. Nao alterar a regra de `if expression` exigir `else`.
2. Nao alterar curingas de `switch`.
3. Nao alterar formatos aceitos de `handle` e remapeamento de erro.
## Method
### O que deve ser feito explicitamente
1. Introduzir subparsers pequenos por familia de construcao.
2. Reusar o contexto compartilhado da PR anterior.
3. Garantir que `parseExpression()` continue entrando pela mesma superficie sintatica.
4. Proteger a equivalencia com testes focados em control-flow expressions.
## Acceptance Criteria
1. A logica de `if/switch/handle/else` nao fica mais centralizada em `PbsExprParser`.
2. ASTs gerados para essas construcoes permanecem equivalentes.
3. Diagnosticos de formas invalidas continuam com o mesmo contrato observavel.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserStatementsTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsResultFlowRulesTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `else` deve viver junto do control-flow parser ou continuar na espinha de precedence. A recomendacao e movê-lo junto porque a associatividade e as mensagens de erro fazem parte do mesmo cluster conceitual.
@@ -0,0 +1,74 @@
# PR-11.3 - PBS Expr Parser Postfix, Primary and Construction Decomposition
## Briefing
O segundo grande concentrador de complexidade em `PbsExprParser` esta nas superficies de `postfix` e `primary`: chamadas, membros, propagate, tuplas, blocos, `new`, `bind`, `some/ok/err`.
Esta PR separa essas familias em colaboradores menores, sem alterar a funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. `parsePostfix`, `parsePrimary` e `parseParenthesizedPrimary` misturam muitas formas sintaticas distintas.
2. Tuple literals, grouped expressions e construction surfaces compartilham lookahead delicado.
3. A manutencao dessas regras num unico metodo torna alto o custo de qualquer evolucao futura.
## Target
Separar parsing de superficies primarias e postfix:
1. postfix chaining,
2. primary literals/identifiers/blocks,
3. tuple/group handling,
4. construction/result surfaces (`new`, `bind`, `some`, `ok`, `err`).
## Dependencies
Prerequisitos diretos:
1. `PR-11.1`
2. `PR-11.2`
## Scope
1. Extrair `parsePostfix`.
2. Extrair `parsePrimary`, `parseParenthesizedPrimary`, `parseTupleItems`, `parseTupleItem`.
3. Extrair `parseNewExpression`, `parseBindExpression`, `parseSomeExpression`, `parseOkExpression`, `parseErrExpression`.
4. Preservar recovery atual para `?`, tuple malformed e parens.
## Non-Goals
1. Nao alterar a aridade de tuple literal.
2. Nao alterar mixed labeled/unlabeled tuple validation.
3. Nao alterar o formato aceito de `new Vec.zero(...)` e `bind(ctx, fn)`.
## Method
### O que deve ser feito explicitamente
1. Introduzir subparsers por familia sintatica em vez de criar um novo monolito.
2. Manter a ordem atual de postfix chaining.
3. Preservar lookahead de tuple/group exatamente como hoje.
4. Reforcar testes de tupla, construction e propagate operator invalido.
## Acceptance Criteria
1. `parsePostfix` e `parsePrimary` deixam de concentrar todas as superficies primarias.
2. Tuplas, grupos, constructions e postfix chains continuam equivalentes.
3. Nao ha mudanca funcional em AST, spans ou diagnosticos.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsOptionalResultTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsApplyResolutionTest*`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. O parsing de tuple/group deve ficar junto de primary ou em helper especializado de parenthesized surfaces. A recomendacao e extrair para helper especializado, porque esse e o trecho com lookahead mais sensivel.
@@ -0,0 +1,73 @@
# PR-11.4 - PBS Expr Parser Literals, Patterns and Shared Token Utilities
## Briefing
Depois de extrair control-flow e primary/postfix, restam em `PbsExprParser` alguns clusters menores mas sensiveis: parsing de literais/padroes, `error path`, consumo de tokens e utilitarios de parse numerico/string.
Esta PR consolida esses pontos em utilitarios dedicados, ainda sem mudanca funcional.
## Motivation
### Dor atual que esta PR resolve
1. Parsing de literal aparece em mais de um lugar (`primary` e switch pattern).
2. `error path`, `consumeMemberName`, `parseLong/Int/DoubleOrDefault` e `unescapeString` sao infra compartilhada e hoje permanecem acoplados ao parser principal.
3. Sem consolidar essa base, o parser termina menor, mas ainda com detalhes mecanicos espalhados.
## Target
Extrair infra compartilhada de expressao:
1. parsing de literais,
2. parsing de `error path`,
3. parsing de patterns simples,
4. token utilities e decode helpers.
## Dependencies
Prerequisitos diretos:
1. `PR-11.1`
2. `PR-11.2`
3. `PR-11.3`
## Scope
1. Extrair `parseLiteralPatternExpression`, `parseErrorPath`, `parseHandlePattern` e helpers correlatos.
2. Consolidar `consume`, `consumeMemberName`, `span`, `report`.
3. Consolidar `parseLongOrDefault`, `parseIntOrDefault`, `parseDoubleOrDefault`, `unescapeString`.
## Non-Goals
1. Nao alterar as regras de literal recovery.
2. Nao alterar o decode de strings.
3. Nao alterar a estrutura de `PbsAst.ErrorPath`.
## Method
### O que deve ser feito explicitamente
1. Reunir parsing de literal/pattern em componente reutilizavel.
2. Mover utilitarios mecanicos para helpers claros e pequenos.
3. Garantir que toda chamada mantenha a mesma atribuicao de spans e diagnosticos.
4. Evitar criar uma util-class genérica demais; manter helpers focados no dominio de expression parsing.
## Acceptance Criteria
1. `PbsExprParser` deixa de concentrar parsing repetido de literais/padroes e utilitarios basicos.
2. Parsing de strings, numeros e `error path` permanece equivalente.
3. A suite de parser continua verde sem atualizar comportamento esperado.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsDeclarationsTest*`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. Nenhuma de arquitetura. Esta PR e de consolidacao local.
@@ -0,0 +1,75 @@
# PR-11.5 - PBS Expr Parser Regression Hardening and Final Cleanup
## Briefing
As PRs anteriores reduzem a complexidade estrutural de `PbsExprParser`. Esta PR fecha a trilha com limpeza final, eliminacao de duplicacao residual e endurecimento de regressao, sem alterar funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. Refactors estruturais em parser de expressao podem mudar detalhes finos sem quebrar imediatamente todos os testes.
2. Ao final da decomposicao, costuma restar duplicacao pequena e helpers obsoletos.
3. O fechamento da trilha precisa garantir equivalencia observavel e uma fachada final pequena.
## Target
Concluir a trilha de refactor do parser de expressoes:
1. limpeza estrutural final,
2. consolidacao dos helpers remanescentes,
3. cobertura de regressao para precedence, postfix, tuples e control-flow expressions.
## Dependencies
Prerequisitos diretos:
1. `PR-11.1`
2. `PR-11.2`
3. `PR-11.3`
4. `PR-11.4`
## Scope
1. Remover codigo duplicado ou caminhos obsoletos apos as extracoes.
2. Garantir que `PbsExprParser` fique reduzido a composicao/orquestracao.
3. Expandir regressao quando necessario para spans, diagnosticos e precedence.
## Non-Goals
1. Nao alterar gramatica de expressoes.
2. Nao introduzir novas formas sintaticas.
3. Nao alterar `PbsAst` ou `ParseErrors`.
## Method
### O que deve ser feito explicitamente
1. Fazer uma passada final de consolidacao.
2. Verificar equivalencia com foco em:
- precedence,
- associatividade,
- tuple/group lookahead,
- control-flow expression recovery.
3. Encerrar a trilha com um `PbsExprParser` pequeno, claro e estavel.
## Acceptance Criteria
1. `PbsExprParser` termina como fachada/orquestrador, nao como concentrador de todas as regras.
2. Nao ha mudanca funcional observavel em AST, spans ou diagnosticos.
3. Suite do frontend PBS passa integralmente.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserStatementsTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. Nenhuma. A partir desta PR, qualquer ajuste restante deve ser tratado como mudanca funcional separada.
@@ -0,0 +1,69 @@
# PR-12.1 - Flow Expression Analyzer Context and Dispatch Foundation
## Briefing
`PbsFlowExpressionAnalyzer` concentra estado compartilhado e um dispatch grande de `Expression -> semantic analysis` em uma unica classe.
Esta PR introduz a base estrutural para decomposicao sem alterar funcionalidade: contexto compartilhado, helpers comuns e uma fronteira clara entre fachada e implementacoes especializadas.
## Motivation
### Dor atual que esta PR resolve
1. A classe combina orquestracao, recursion, block delegation e regras semanticas detalhadas.
2. Extracoes futuras ficam arriscadas sem um contexto compartilhado explicito.
3. O maior hotspot da classe e o dispatch principal de `analyzeExpressionInternal`, que hoje depende de muitos parametros repetidos.
## Target
Estabelecer uma fundacao segura para o refactor:
1. contexto compartilhado para analise de expressao,
2. encapsulamento de argumentos recorrentes,
3. fachada pequena em `PbsFlowExpressionAnalyzer`.
## Dependencies
Nenhuma.
## Scope
1. Introduzir um contexto/request object para `scope`, `expectedType`, `returnType`, `resultErrorName`, `receiverType`, `model`, `diagnostics`, `use` e `valueContext`.
2. Encapsular a dependencia de `BlockAnalyzer` nessa camada.
3. Reorganizar o dispatch principal sem mover ainda regras complexas para outras classes.
## Non-Goals
1. Nao alterar inferencia de tipos.
2. Nao alterar diagnosticos ou spans.
3. Nao reescrever `PbsFlowTypeOps` ou `PbsFlowBodyAnalyzer`.
## Method
### O que deve ser feito explicitamente
1. Criar um contexto pequeno e explicito para a analise recursiva.
2. Manter `PbsFlowExpressionAnalyzer` como entrypoint package-private.
3. Preservar a ordem atual de recursion e emissao de diagnosticos.
4. Garantir que esta PR seja puramente estrutural.
## Acceptance Criteria
1. `PbsFlowExpressionAnalyzer` continua com o mesmo contrato observavel.
2. A quantidade de parametros repetidos no dispatch recursivo e reduzida.
3. Nao ha mudanca funcional em inferencia, erros ou comportamento da suite.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsDeclarationsTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsAssignmentTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsApplyResolutionTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. O contexto deve ser imutavel por chamada recursiva ou permitir derivacao incremental. A recomendacao e usar derivacao imutavel leve para reduzir risco de regressao.
@@ -0,0 +1,71 @@
# PR-12.2 - Flow Expression Analyzer Literal and Structural Expression Splitting
## Briefing
Grande parte do dispatch de `PbsFlowExpressionAnalyzer` cobre formas literais e estruturais de expressao: literais, `this`, identificadores, grupos, tuplas, blocos, unarios, binarios, `none/some`, `new`, `as`, `ok/err`.
Esta PR extrai essas familias para componentes menores, sem alterar funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. O dispatch principal mistura casos triviais com regras mais complexas de call/member/switch/handle.
2. Formas estruturais simples podem ser separadas com risco baixo e alta reducao de complexidade.
3. Sem esse corte, o dispatch central continua inchado mesmo com contexto compartilhado.
## Target
Separar a analise de expressoes literais e estruturais:
1. literais e identificadores,
2. grupos, tuplas e blocos,
3. unario/binario,
4. `none/some`, `new`, `bind`-independent simple forms, `as`, `ok/err`.
## Dependencies
Prerequisito direto:
1. `PR-12.1`
## Scope
1. Extrair casos simples de `analyzeExpressionInternal` para helpers/colaboradores dedicados.
2. Manter o resultado em `ExprResult` exatamente como hoje.
3. Preservar todas as chamadas a `typeOps` e `blockAnalyzer`.
## Non-Goals
1. Nao alterar regras de callback/bind.
2. Nao alterar member access ou overload resolution.
3. Nao alterar switch/handle/result propagation.
## Method
### O que deve ser feito explicitamente
1. Mover primeiro os casos com menor acoplamento semantico.
2. Manter o dispatch principal apenas como roteador.
3. Preservar a ordem atual de recursion para evitar mudanca em diagnosticos acumulados.
## Acceptance Criteria
1. Casos literais e estruturais deixam de ficar todos dentro do dispatch principal.
2. AST/semantics observados pela suite permanecem equivalentes.
3. O hotspot principal da classe reduz tamanho e branching sem alterar comportamento.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsOptionalResultTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsDeclarationsTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `BindExpr` deve entrar aqui ou junto de call resolution. A recomendacao e mantê-lo para `PR-12.3`, porque ele depende de matching de callback/callable.
@@ -0,0 +1,72 @@
# PR-12.3 - Flow Expression Analyzer Call and Member Resolution Decomposition
## Briefing
`analyzeCallExpression`, `analyzeApplyExpression`, `resolveCallableApplication`, `analyzeMemberExpression` e parte de `BindExpr` concentram a logica de resolucao mais sensivel do analisador.
Esta PR extrai essa superficie para colaboradores menores, sem alterar regras de overload, bare method extraction, acesso a campos ou matching de callback.
## Motivation
### Dor atual que esta PR resolve
1. Member access e callable resolution sao os clusters mais densos depois do dispatch principal.
2. A classe mistura regras de acesso a tuple/struct/service/contract com overload resolution e bind matching.
3. Qualquer ajuste nessas regras hoje exige tocar um arquivo muito central e com alta chance de regressao.
## Target
Separar a analise de resolucao:
1. member access,
2. call/apply overload resolution,
3. bind-to-callback matching,
4. field access permission checks.
## Dependencies
Prerequisitos diretos:
1. `PR-12.1`
2. `PR-12.2`
## Scope
1. Extrair `analyzeCallExpression`, `analyzeApplyExpression`, `resolveCallableApplication`.
2. Extrair `analyzeMemberExpression` e `canReadStructField`.
3. Mover a parte especifica de `BindExpr` para o mesmo cluster de resolucao.
## Non-Goals
1. Nao alterar diagnosticos de overload ambiguous/unresolved.
2. Nao alterar regras de leitura de campo privado/publico.
3. Nao alterar a proibicao de bare method extraction.
## Method
### O que deve ser feito explicitamente
1. Criar um resolver focado em call/member semantics.
2. Preservar o mesmo uso de `TypeView`, `CallableSymbol` e `ExprResult`.
3. Garantir que o order of checks permaneça equivalente, especialmente em erros e narrowing por `expectedType`.
## Acceptance Criteria
1. Call/member resolution deixa de ficar concentrada em `PbsFlowExpressionAnalyzer`.
2. Bare method extraction, field access e overload matching permanecem equivalentes.
3. Suite semantica continua verde sem mudancas funcionais.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsApplyResolutionTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsAssignmentTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsFrontendCompilerTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `BindExpr` deve compartilhar exatamente o mesmo narrowing path de `call/apply` ou ficar em helper proprio. A recomendacao e helper proprio dentro do mesmo resolver, para evitar acoplamento artificial.
@@ -0,0 +1,73 @@
# PR-12.4 - Flow Expression Analyzer Switch and Handle Decomposition
## Briefing
`switch` e `handle` sao as maiores superfices especializadas restantes em `PbsFlowExpressionAnalyzer`, com regras de exaustividade, pattern typing, matching de erro e arm typing.
Esta PR separa essas construcoes em analisadores dedicados, mantendo exatamente o comportamento atual.
## Motivation
### Dor atual que esta PR resolve
1. `analyzeSwitchExpression` e `analyzeHandleExpression` concentram regras de alto branching e recovery semantico.
2. Essas regras sao semanticamente coesas e merecem fronteiras proprias.
3. Sem esse corte, a classe principal continua com os hotspots mais caros de manutencao.
## Target
Extrair a analise especializada de:
1. `switch expression`,
2. `switch pattern typing/keying`,
3. `handle expression`,
4. `handle block arm` e matching de error targets.
## Dependencies
Prerequisitos diretos:
1. `PR-12.1`
2. `PR-12.2`
3. `PR-12.3`
## Scope
1. Extrair `analyzeSwitchExpression`, `switchPatternKey`, `switchPatternType`.
2. Extrair `analyzeHandleExpression`, `analyzeHandleBlockArm`, `matchesTargetError`, `unwrapGroup`.
3. Preservar a interacao com `blockAnalyzer`, `typeOps` e `model`.
## Non-Goals
1. Nao alterar regras de exaustividade de switch em value position.
2. Nao alterar regras de wildcard/default duplication.
3. Nao alterar regras de `handle` para `ok(...)` / `err(...)` terminais.
## Method
### O que deve ser feito explicitamente
1. Criar analisadores especializados por construcao.
2. Preservar ordem de validacoes e diagnosticos.
3. Reusar o contexto compartilhado para evitar nova explosao de parametros.
## Acceptance Criteria
1. `switch` e `handle` deixam de ficar implementados diretamente na classe principal.
2. Exaustividade, arm typing e error matching permanecem equivalentes.
3. Nenhum teste de result flow, control flow ou optional/result muda comportamento esperado.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsResultFlowRulesTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsOptionalResultTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsControlFlowTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `switchPatternKey` e `switchPatternType` devem ficar juntos no mesmo colaborador. A recomendacao e sim, porque ambos definem a semantica da superficie de pattern.
@@ -0,0 +1,77 @@
# PR-12.5 - Flow Expression Analyzer Regression Hardening and Final Cleanup
## Briefing
As PRs anteriores reduzem a complexidade estrutural de `PbsFlowExpressionAnalyzer`. Esta PR fecha a trilha com consolidacao final, limpeza de duplicacao residual e endurecimento de regressao, sem alterar funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. Refactors estruturais em analise semantica podem preservar casos principais e ainda mudar detalhes finos de diagnostico.
2. Ao final da decomposicao, tendem a restar helpers redundantes ou caminhos duplicados.
3. O fechamento da trilha precisa garantir equivalencia observavel e uma fachada final pequena.
## Target
Concluir a trilha de refactor:
1. limpeza estrutural final,
2. consolidacao dos helpers remanescentes,
3. cobertura de regressao para inferencia e diagnosticos.
## Dependencies
Prerequisitos diretos:
1. `PR-12.1`
2. `PR-12.2`
3. `PR-12.3`
4. `PR-12.4`
## Scope
1. Remover duplicacao residual apos as extracoes.
2. Garantir que `PbsFlowExpressionAnalyzer` fique reduzido a composicao/orquestracao.
3. Reforcar testes de regressao para call/member resolution, result flow, switch e handle.
## Non-Goals
1. Nao alterar taxonomia de `PbsSemanticsErrors`.
2. Nao alterar `TypeView`, `ExprResult` ou `PbsFlowTypeOps`.
3. Nao introduzir novas regras semanticas.
## Method
### O que deve ser feito explicitamente
1. Fazer uma passada final de consolidacao.
2. Verificar equivalencia com foco em:
- inferencia de tipos,
- overload resolution,
- access checks,
- switch/handle exhaustiveness e matching,
- diagnosticos emitidos.
3. Encerrar a trilha com uma fachada pequena e clara.
## Acceptance Criteria
1. `PbsFlowExpressionAnalyzer` termina como orquestrador, nao como concentrador de toda a logica.
2. Nao ha mudanca funcional observavel em analise, tipos inferidos ou diagnosticos.
3. Suite do frontend PBS passa integralmente.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsApplyResolutionTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsResultFlowRulesTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsOptionalResultTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsControlFlowTest*`
5. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. Nenhuma. A partir desta PR, qualquer mudanca adicional deve ser tratada como evolucao funcional separada.
@@ -0,0 +1,67 @@
# PR-13.1 - Flow Body Analyzer Context and Entrypoint Foundation
## Briefing
`PbsFlowBodyAnalyzer` concentra montagem de contexto, iteracao de callables e delegacao recursiva de block/statement analysis em uma unica classe.
Esta PR introduz a base estrutural para decomposicao sem alterar funcionalidade: contexto compartilhado, encapsulamento dos argumentos recorrentes e uma fachada mais clara para a classe.
## Motivation
### Dor atual que esta PR resolve
1. A classe repassa muitos parametros repetidos entre `validate`, `validateCallableBody`, `analyzeBlock` e `analyzeStatement`.
2. Extracoes futuras ficam arriscadas sem um contexto comum explicito.
3. A fundacao estrutural reduz risco antes de mover regras de completion, statements e assignment resolution.
## Target
Estabelecer uma base segura para o refactor:
1. contexto compartilhado de body analysis,
2. encapsulamento de `returnType`, `resultErrorName`, `receiverType`, `model` e `diagnostics`,
3. fachada pequena para `validate(...)`.
## Dependencies
Nenhuma.
## Scope
1. Introduzir um contexto/request object para analise de corpo.
2. Reorganizar `validate` e `validateCallableBody` sem mover ainda regras complexas.
3. Preservar a relacao atual com `PbsFlowExpressionAnalyzer`.
## Non-Goals
1. Nao alterar inferencia de tipos ou diagnosticos.
2. Nao alterar `Model.from(...)`.
3. Nao mover ainda completion analysis ou assignment target resolution para classes separadas.
## Method
### O que deve ser feito explicitamente
1. Criar um contexto pequeno e explicito para analise recursiva de blocos/callables.
2. Manter `PbsFlowBodyAnalyzer` como entrypoint package-private.
3. Preservar a ordem atual de validacao e emissao de erros.
## Acceptance Criteria
1. `PbsFlowBodyAnalyzer` continua com o mesmo contrato observavel.
2. A quantidade de parametros repetidos nas chamadas internas e reduzida.
3. Nao ha mudanca funcional em flow analysis, completion ou diagnosticos.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsControlFlowTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsDeclarationsTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. O contexto deve ser derivado imutavelmente por bloco ou mutado localmente. A recomendacao e derivacao leve para reduzir risco de vazamento entre branches.
@@ -0,0 +1,71 @@
# PR-13.2 - Flow Body Analyzer Callable Body and Completion Decomposition
## Briefing
As regras de entrada de callable e de completion/fallthrough em `PbsFlowBodyAnalyzer` formam um cluster coeso, mas hoje ficam misturadas com statement analysis e assignment resolution.
Esta PR extrai essa superficie para colaboradores dedicados, sem alterar funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. `validateCallableBody`, `validateCallableCompletion`, `blockAlwaysReturns`, `statementAlwaysReturns`, `expressionAlwaysReturns`, `switchAlwaysReturns` e `handleAlwaysReturns` concentram regras de completion com alto branching.
2. Completion analysis e statement analysis sao preocupacoes diferentes e hoje dividem a mesma classe.
3. Essa parte e muito sensivel e merece uma fronteira estrutural propria.
## Target
Separar a camada de body entry/completion:
1. bootstrap de callable body,
2. validacao de fallthrough/completion,
3. regras de `always returns`,
4. exaustividade relevante para completion.
## Dependencies
Prerequisito direto:
1. `PR-13.1`
## Scope
1. Extrair `validateCallableBody`.
2. Extrair `validateCallableCompletion`, `blockAlwaysReturns`, `statementAlwaysReturns`, `expressionAlwaysReturns`.
3. Extrair `switchAlwaysReturns`, `switchIsExhaustive`, `handleAlwaysReturns`, `handleArmAlwaysReturns`, `isKnownErrorPath`.
## Non-Goals
1. Nao alterar as regras atuais de fallthrough para result/plain non-unit.
2. Nao alterar a semantica de exaustividade usada apenas para completion.
3. Nao alterar statement analysis ou assignment checks.
## Method
### O que deve ser feito explicitamente
1. Introduzir um analisador de completion ou divisao equivalente.
2. Manter `PbsFlowBodyAnalyzer` como orquestrador do processo.
3. Preservar rigorosamente a ordem atual de checks e codigos de diagnostico.
## Acceptance Criteria
1. A logica de completion/fallthrough deixa de ficar centralizada em `PbsFlowBodyAnalyzer`.
2. As regras de `always returns` permanecem equivalentes.
3. Nenhum teste de fallthrough, control flow ou result flow muda comportamento esperado.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsFallthroughTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsControlFlowTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsResultFlowRulesTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `switch`/`handle` completion deve ficar junto do completion analyzer ou reaproveitar colaboradores do expression analyzer. A recomendacao e manter local ao completion analyzer para evitar acoplamento indevido entre analise de tipo e analise de terminacao.
@@ -0,0 +1,72 @@
# PR-13.3 - Flow Body Analyzer Statement Analysis Splitting
## Briefing
Depois de separar entry/completion, o maior hotspot restante em `PbsFlowBodyAnalyzer` passa a ser `analyzeBlock` e `analyzeStatement`, com tratamento de `let`, `return`, `if`, `for`, `while`, expression statement e delegacao para `PbsFlowExpressionAnalyzer`.
Esta PR extrai essa superficie para colaboradores menores, sem alterar funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. `analyzeStatement` concentra varias formas de statement com regras semanticas distintas.
2. Loops, `if` e `return` usam os mesmos parametros e diagnosticos, mas pertencem a clusters semanticos diferentes.
3. A manutencao dessa logica em um unico metodo torna a classe dificil de evoluir.
## Target
Separar a analise de statements:
1. blocos e escopos,
2. `let` e expression statements,
3. `return` flow,
4. `if/for/while`.
## Dependencies
Prerequisitos diretos:
1. `PR-13.1`
2. `PR-13.2`
## Scope
1. Extrair `analyzeBlock` e o dispatch de `analyzeStatement`.
2. Extrair regras de `let`, `if`, `for`, `while` e expression statement para helpers/colaboradores dedicados.
3. Deixar `return` bootstrap pronto para corte proprio, sem ainda mexer em assignment target resolution.
## Non-Goals
1. Nao alterar mutabilidade de escopo local.
2. Nao alterar validacao de tipos de condicao ou bounds de loop.
3. Nao alterar assignment resolution.
## Method
### O que deve ser feito explicitamente
1. Introduzir um statement analyzer ou divisao equivalente por familias.
2. Reusar o contexto compartilhado da `PR-13.1`.
3. Preservar a ordem atual de chamadas ao `expressionAnalyzer`.
## Acceptance Criteria
1. `analyzeStatement` deixa de concentrar todas as formas de statement.
2. Scoping, condition checks e loop bound checks permanecem equivalentes.
3. Suite semantica continua verde sem mudanca funcional.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsControlFlowTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsAssignmentTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsDeclarationsTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `return` deve ficar no statement analyzer ou em um colaborador proprio de result flow. A recomendacao e deixar o corte final para a PR seguinte se isso simplificar mais a classe.
@@ -0,0 +1,72 @@
# PR-13.4 - Flow Body Analyzer Assignment Target Resolution Decomposition
## Briefing
`resolveAssignmentTarget` e a logica correlata de assignment compatibility concentram um dos trechos mais densos e sensiveis de `PbsFlowBodyAnalyzer`.
Esta PR extrai a resolucao de assignment target e as regras de acesso/leitura/escrita de campo para colaboradores dedicados, sem alterar funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. Assignment resolution mistura lookup de locals, `this`, singleton services, consts e navegação em campos de struct.
2. Regras de leitura e escrita de campo estao acopladas ao fluxo do statement analyzer.
3. A superficie e densa e merece um resolver proprio com foco em diagnósticos de assignability.
## Target
Separar a camada de assignment semantics:
1. resolucao de assignment target,
2. assignability de roots conhecidos,
3. leitura/escrita de campos,
4. type compatibility por operador de atribuicao.
## Dependencies
Prerequisitos diretos:
1. `PR-13.1`
2. `PR-13.2`
3. `PR-13.3`
## Scope
1. Extrair `analyzeAssignmentStatement`.
2. Extrair `resolveAssignmentTarget`, `assignmentCompatible`, `canReadStructField`, `canWriteStructField`, `isKnownNonAssignableRoot`.
3. Manter `AssignmentTargetResolution` ou mover para um modelo focado de assignment.
## Non-Goals
1. Nao alterar regras de mutabilidade/local const.
2. Nao alterar regras de acesso a campos privados/publicos.
3. Nao alterar o mapeamento de operadores compostos para inferencia binaria.
## Method
### O que deve ser feito explicitamente
1. Criar um resolver dedicado para assignment targets.
2. Preservar exatamente os mesmos erros emitidos para target nao resolvido, nao assignable ou field access denied.
3. Reusar `PbsFlowTypeOps` sem alterar sua logica.
## Acceptance Criteria
1. Assignment target resolution deixa de ficar centralizada em `PbsFlowBodyAnalyzer`.
2. Regras de assignability e field access permanecem equivalentes.
3. Nenhum teste de assignment ou control flow muda comportamento esperado.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsAssignmentTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsDeclarationsTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `AssignmentTargetResolution` deve permanecer como record local ou migrar para um modelo package-private dedicado. A recomendacao e mover para o resolver de assignment para reduzir acoplamento.
@@ -0,0 +1,77 @@
# PR-13.5 - Flow Body Analyzer Regression Hardening and Final Cleanup
## Briefing
As PRs anteriores reduzem a complexidade estrutural de `PbsFlowBodyAnalyzer`. Esta PR fecha a trilha com consolidacao final, limpeza de duplicacao residual e endurecimento de regressao, sem alterar funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. Refactors estruturais em flow/body analysis podem preservar casos principais e ainda mudar detalhes finos de diagnostico ou scoping.
2. Ao final da decomposicao, tendem a restar helpers redundantes ou caminhos duplicados.
3. O fechamento da trilha precisa garantir equivalencia observavel e uma fachada final pequena.
## Target
Concluir a trilha de refactor:
1. limpeza estrutural final,
2. consolidacao dos helpers remanescentes,
3. cobertura de regressao para completion, statements e assignment semantics.
## Dependencies
Prerequisitos diretos:
1. `PR-13.1`
2. `PR-13.2`
3. `PR-13.3`
4. `PR-13.4`
## Scope
1. Remover duplicacao residual apos as extracoes.
2. Garantir que `PbsFlowBodyAnalyzer` fique reduzido a composicao/orquestracao.
3. Reforcar testes de regressao para fallthrough, return flow, loops e assignments.
## Non-Goals
1. Nao alterar taxonomia de `PbsSemanticsErrors`.
2. Nao alterar `PbsFlowTypeOps` ou `PbsFlowExpressionAnalyzer`.
3. Nao introduzir novas regras semanticas.
## Method
### O que deve ser feito explicitamente
1. Fazer uma passada final de consolidacao.
2. Verificar equivalencia com foco em:
- completion/fallthrough,
- scoping local,
- return result flow,
- assignment target resolution,
- field access diagnostics.
3. Encerrar a trilha com uma fachada pequena e clara.
## Acceptance Criteria
1. `PbsFlowBodyAnalyzer` termina como orquestrador, nao como concentrador da logica completa.
2. Nao ha mudanca funcional observavel em flow analysis ou diagnosticos.
3. Suite do frontend PBS passa integralmente.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsFallthroughTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsAssignmentTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsControlFlowTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsResultFlowRulesTest*`
5. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. Nenhuma. A partir desta PR, qualquer mudanca adicional deve ser tratada como evolucao funcional separada.
+78
View File
@@ -0,0 +1,78 @@
# PBS Pull Requests
This directory contains self-contained PBS change proposals for review.
## Purpose
A pull request document packages a proposed change so it can be reviewed as a coherent unit before final integration.
Use this directory when a change:
- touches multiple documents,
- changes architecture or semantics,
- needs explicit review criteria,
- or should be assessed before editing the final normative corpus.
Architecture and decisions come before implementation.
## Required Properties
Every pull request document must be self-contained.
A reviewer should be able to understand the proposal without reconstructing context from chat history or scattered notes.
## Required Sections
Each pull request should include, at minimum:
1. Briefing
2. Target
3. Method
4. Acceptance Criteria
5. Tests, when needed
Recommended additional sections:
6. Motivation
7. Scope
8. Non-Goals
9. Affected Documents
10. Open Questions
## Section Expectations
### Briefing
Summarize the problem and the proposed change in a short, readable form.
### Target
State exactly what documents, behaviors, or contracts the proposal changes.
### Method
Explain the architectural and editorial approach.
If the proposal depends on prior decisions, name them explicitly.
### Acceptance Criteria
List the conditions that must be true for the proposal to be accepted.
These should be specific and reviewable.
### Tests
Include tests when the change affects executable behavior, conformance, verification, lowering, or observable runtime semantics.
If tests are not necessary, say why.
## Writing Rules
- Keep the proposal self-contained.
- Prefer explicit architectural reasoning over implementation detail.
- Do not bury acceptance criteria inside prose.
- Do not assume unresolved details.
- If a required decision is missing, stop and raise the question instead of inferring an answer.
## Review Rule
A pull request may propose implementation consequences, but it must not smuggle in unresolved architectural choices as implementation details.