prometeu-studio/docs/compiler/pbs/pull-requests/PR-08.1-intrinsic-resolution-canonical-identity-keying.md

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?