clean up
This commit is contained in:
@@ -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.
|
||||
+59
@@ -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.
|
||||
+62
@@ -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.
|
||||
+59
@@ -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.
|
||||
+78
@@ -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.
|
||||
+73
@@ -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.
|
||||
+70
@@ -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.
|
||||
+70
@@ -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.
|
||||
+72
@@ -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)?
|
||||
+73
@@ -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.
|
||||
+74
@@ -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.
|
||||
+77
@@ -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?
|
||||
+80
@@ -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?
|
||||
+72
@@ -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?
|
||||
+74
@@ -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?
|
||||
+81
@@ -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.
|
||||
+68
@@ -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.
|
||||
+72
@@ -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.
|
||||
+84
@@ -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.
|
||||
+76
@@ -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.
|
||||
+84
@@ -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
|
||||
+76
@@ -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.
|
||||
+69
@@ -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`.
|
||||
+73
@@ -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.
|
||||
+74
@@ -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.
|
||||
+80
@@ -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.
|
||||
+68
@@ -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.
|
||||
+74
@@ -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.
|
||||
+73
@@ -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.
|
||||
+75
@@ -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.
|
||||
+69
@@ -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.
|
||||
+71
@@ -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.
|
||||
+72
@@ -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.
|
||||
+73
@@ -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.
|
||||
+77
@@ -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.
|
||||
+67
@@ -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.
|
||||
+71
@@ -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.
|
||||
+72
@@ -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.
|
||||
+72
@@ -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.
|
||||
+77
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user