clean up

docs/pbs/pull-requests/PR-09.1-irbackend-modulekey-hard-removal-from-contract.md

@@ -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.

docs/pbs/pull-requests/PR-09.2-pbs-frontend-moduleid-only-lowering-and-import-surfaces.md

@@ -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.

docs/pbs/pull-requests/PR-09.3-lower-to-irvm-moduleid-only-ordering-and-strict-qualified-entrypoint.md

@@ -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.

docs/pbs/pull-requests/PR-09.4-specs-refresh-moduleid-only-entrypointref-and-bytecode-alignment.md

@@ -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.

docs/pbs/pull-requests/PR-09.5-hard-gates-no-modulekey-regression-and-migration-cleanup.md

@@ -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.

docs/pbs/pull-requests/PR-09.6-isa-intrinsic-registry-single-source-artifact.md

@@ -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

docs/pbs/pull-requests/PR-09.7-compiler-normalization-to-isa-registry-artifact.md

@@ -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.

prometeu-compiler/prometeu-compiler-core/src/main/java/p/studio/compiler/source/identifiers/NodeId.java

@@ -1,7 +0,0 @@
-package p.studio.compiler.source.identifiers;
-
-public class NodeId extends SourceIdentifier {
-    public NodeId(int id) {
-        super(id);
-    }
-}

prometeu-compiler/prometeu-compiler-core/src/main/java/p/studio/compiler/source/identifiers/SymbolId.java

@@ -1,7 +0,0 @@
-package p.studio.compiler.source.identifiers;
-
-public class SymbolId extends SourceIdentifier {
-    public SymbolId(int id) {
-        super(id);
-    }
-}

prometeu-compiler/prometeu-compiler-core/src/main/java/p/studio/compiler/source/identifiers/TypeId.java

@@ -1,7 +0,0 @@
-package p.studio.compiler.source.identifiers;
-
-public class TypeId extends SourceIdentifier {
-    public TypeId(int id) {
-        super(id);
-    }
-}