From e11cfee9a4b5a76fb8d109d73af09d20bf3ff031 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Mon, 9 Mar 2026 13:45:45 +0000 Subject: [PATCH] added PRs --- docs/pbs/pull-requests/INDEX.md | 10 +++ ...ic-resolution-canonical-identity-keying.md | 80 +++++++++++++++++++ ...ackend-moduleid-contract-and-modulepool.md | 79 ++++++++++++++++++ ...-qualified-entrypoint-identity-contract.md | 80 +++++++++++++++++++ ...func-callee-module-identity-correctness.md | 72 +++++++++++++++++ ...egistry-single-source-sync-with-runtime.md | 74 +++++++++++++++++ 6 files changed, 395 insertions(+) create mode 100644 docs/pbs/pull-requests/PR-08.1-intrinsic-resolution-canonical-identity-keying.md create mode 100644 docs/pbs/pull-requests/PR-08.2-irbackend-moduleid-contract-and-modulepool.md create mode 100644 docs/pbs/pull-requests/PR-08.3-qualified-entrypoint-identity-contract.md create mode 100644 docs/pbs/pull-requests/PR-08.4-call-func-callee-module-identity-correctness.md create mode 100644 docs/pbs/pull-requests/PR-08.5-intrinsic-registry-single-source-sync-with-runtime.md diff --git a/docs/pbs/pull-requests/INDEX.md b/docs/pbs/pull-requests/INDEX.md index 9aca769d..5b48cc1a 100644 --- a/docs/pbs/pull-requests/INDEX.md +++ b/docs/pbs/pull-requests/INDEX.md @@ -133,3 +133,13 @@ Foco: eliminar os dois `partial` remanescentes na matriz backend antes de mover 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` diff --git a/docs/pbs/pull-requests/PR-08.1-intrinsic-resolution-canonical-identity-keying.md b/docs/pbs/pull-requests/PR-08.1-intrinsic-resolution-canonical-identity-keying.md new file mode 100644 index 00000000..6a8f4813 --- /dev/null +++ b/docs/pbs/pull-requests/PR-08.1-intrinsic-resolution-canonical-identity-keying.md @@ -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? diff --git a/docs/pbs/pull-requests/PR-08.2-irbackend-moduleid-contract-and-modulepool.md b/docs/pbs/pull-requests/PR-08.2-irbackend-moduleid-contract-and-modulepool.md new file mode 100644 index 00000000..336c35d4 --- /dev/null +++ b/docs/pbs/pull-requests/PR-08.2-irbackend-moduleid-contract-and-modulepool.md @@ -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` 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? diff --git a/docs/pbs/pull-requests/PR-08.3-qualified-entrypoint-identity-contract.md b/docs/pbs/pull-requests/PR-08.3-qualified-entrypoint-identity-contract.md new file mode 100644 index 00000000..aefb8e88 --- /dev/null +++ b/docs/pbs/pull-requests/PR-08.3-qualified-entrypoint-identity-contract.md @@ -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? diff --git a/docs/pbs/pull-requests/PR-08.4-call-func-callee-module-identity-correctness.md b/docs/pbs/pull-requests/PR-08.4-call-func-callee-module-identity-correctness.md new file mode 100644 index 00000000..46342e6a --- /dev/null +++ b/docs/pbs/pull-requests/PR-08.4-call-func-callee-module-identity-correctness.md @@ -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? diff --git a/docs/pbs/pull-requests/PR-08.5-intrinsic-registry-single-source-sync-with-runtime.md b/docs/pbs/pull-requests/PR-08.5-intrinsic-registry-single-source-sync-with-runtime.md new file mode 100644 index 00000000..1197f8d1 --- /dev/null +++ b/docs/pbs/pull-requests/PR-08.5-intrinsic-registry-single-source-sync-with-runtime.md @@ -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?