# 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?