diff --git a/docs/pbs/pull-requests/INDEX.md b/docs/pbs/pull-requests/INDEX.md index c701c8cd..a975b06f 100644 --- a/docs/pbs/pull-requests/INDEX.md +++ b/docs/pbs/pull-requests/INDEX.md @@ -37,3 +37,6 @@ Cada documento e auto contido e inclui: `Briefing`, `Target`, `Method`, `Accepta 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` diff --git a/docs/pbs/pull-requests/PR-029-pbs-builtin-slot-inference-and-layout-semantics.md b/docs/pbs/pull-requests/PR-029-pbs-builtin-slot-inference-and-layout-semantics.md new file mode 100644 index 00000000..9271793f --- /dev/null +++ b/docs/pbs/pull-requests/PR-029-pbs-builtin-slot-inference-and-layout-semantics.md @@ -0,0 +1,72 @@ +# PR-029 - PBS Builtin Slot Inference and Canonical Layout Semantics + +## Briefing + +Hoje o frontend aceita `Slot(index=...)` manual em `declare builtin type`, e parte da validacao de layout fica empurrada para `load-facing`. +Isso abre espaco para inconsistencias entre declaracao de campos, flattening e offsets. + +Esta PR move ownership de slot para o compilador: offsets passam a ser inferidos deterministicamente a partir do layout canonico flattenado, sem autoria manual de `Slot`. + +## Motivation + +- Reduzir superficie de erro humano em builtin layout. +- Alinhar semantica estatica com o contrato de layout flattenado. +- Evitar que erros de layout aparecam tarde em `load-facing` quando sao semanticos. + +## Target + +- Tornar `Slot(index=...)` proibido na superficie de fonte de builtin field. +- Banir `Slot(...)` da gramatica PBS (erro de sintaxe), sem fallback transitorio. +- Inferir `slotStart` automaticamente no frontend com base em: + - ordem canonica dos campos, + - largura flattenada dos tipos admissiveis, + - composicao builtin aninhada. +- Mover validacoes de layout para `static semantics`. +- Atualizar extracao de metadata reservada para usar slots inferidos (nao lidos de atributo). +- Atualizar fixtures do SDK minimo (`@core:color` etc.) removendo `Slot`. + +## Scope + +- `frontends/prometeu-frontend-pbs` (semantica + metadata extraction + testes). +- Atualizacao de specs PBS relacionadas a builtin layout e diagnosticos. + +## Method + +1. Introduzir um resolvedor de layout builtin na fase semantica. +2. Calcular largura flattenada por tipo builtin e mapear offsets por campo. +3. Banir `Slot(...)` no parser (erro de sintaxe deterministico) com remocao da forma da superficie da linguagem. +4. Produzir diagnosticos `E_SEM_*` deterministicos para: + - tipo de campo nao admissivel para layout builtin, + - composicao ciclica de builtin layout, + - impossibilidade de resolver largura flattenada. +5. Persistir offsets inferidos no metadata model de lowering (`IRReservedMetadata`). +6. Remover a exigencia de `Slot` no loader/extractor. + +## Acceptance Criteria + +- Builtin fields sem `Slot` compilam quando o layout e admissivel. +- Qualquer `Slot(...)` manual e rejeitado como erro de sintaxe (breaking imediato). +- `Pixel(x:int, y:int, color:Color)` recebe offsets inferidos consistentes com flattening. +- Erros de layout builtin deixam de depender de `E_LOAD_*` para serem detectados. +- Suite Gate U cobre positivo e negativo para inferencia de slot. + +## Tests + +- Positivo: inferencia de offsets em builtin simples e composto. +- Negativo: `Slot` manual presente (falha de parser). +- Negativo: campo com tipo nao admissivel. +- Negativo: ciclo de composicao builtin. +- Asserts por `code`, `phase`, `templateId`, `span`. + +## Non-Goals + +- Alterar o contrato de runtime/verifier para alem da inferencia de layout no frontend. +- Definir encoding final de artifact/PBX. + +## Affected Documents + +- `docs/pbs/specs/4. Static Semantics Specification.md` +- `docs/pbs/specs/3. Core Syntax Specification.md` +- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md` +- `docs/pbs/specs/8. Stdlib Environment Packaging and Loading Specification.md` +- `docs/pbs/specs/12. Diagnostics Specification.md` diff --git a/docs/pbs/pull-requests/PR-030-pbs-host-admission-capability-gating.md b/docs/pbs/pull-requests/PR-030-pbs-host-admission-capability-gating.md new file mode 100644 index 00000000..4574a97b --- /dev/null +++ b/docs/pbs/pull-requests/PR-030-pbs-host-admission-capability-gating.md @@ -0,0 +1,70 @@ +# PR-030 - PBS Host Admission and Capability Gating Diagnostics + +## Briefing + +O pipeline PBS ja distingue fases `host-admission` e `load-facing`, mas hoje nao emite `E_HOST_*` no frontend/build pipeline. +Sem essa etapa, problemas de capability para host bindings aparecem tarde demais ou ficam sem trilha diagnostica alinhada ao contrato das specs. + +Esta PR introduz uma etapa explicita de host-admission com diagnosticos deterministas e explicita o boundary de autoridade: build calcula requirements; concessao acontece no runtime. + +## Motivation + +- Alinhar o frontend/build pipeline com `6.2` e `7` para capability gating. +- Produzir falha previsivel e rastreavel por `code/phase/templateId`. +- Evitar aceitacao silenciosa de host surface sem capacidade declarada. + +## Target + +- Criar fase de host-admission no pipeline PBS apos linking/metadata extraction. +- Calcular `requiredCapabilities` a partir dos host bindings usados. +- Validar consistencia de metadata de capability por binding. +- Emitir `E_HOST_*` com fase `HOST_ADMISSION`. +- Expor `requiredCapabilities` para o packer auxiliar emissao/validacao de `manifest.json`. + +## Scope + +- `prometeu-build-pipeline` + `frontends/prometeu-frontend-pbs`. +- Contrato de contexto para capabilities requeridas no build (nao concedidas). +- Testes de conformance (positivo/negativo) para host-admission. + +## Method + +1. Introduzir metadata dedicada de capability no host binding: + - `[Capability(name = "...")]` na assinatura host, sem sobrecarregar `Host(...)`. +2. Introduzir `HostAdmissionContext` no frontend/build para carregar capabilities requeridas no build. +3. Coletar host bindings canonicos a partir de metadata reservada extraida (`Host(module,name,version)` + `Capability(name)`). +4. Calcular deterministicamente `requiredCapabilities` por programa/modulo. +5. Rejeitar deterministicamente inconsistencias de metadata de capability (`E_HOST_*`). +6. Exportar `requiredCapabilities` para consumo do packer na geracao/validacao de `manifest.json`. +7. Manter regra de autoridade: + - frontend/build nao concede capabilities, + - loader/plataforma continua autoridade final de admissao e grant. + +## Acceptance Criteria + +- Pipeline emite `E_HOST_*` com `phase=HOST_ADMISSION` para metadata invalida/ausente de capability. +- `code`, `templateId`, `span` estaveis e assertaveis em testes. +- `requiredCapabilities` e produzido deterministicamente para o mesmo source set. +- Sem metadata invalida de capability, o mesmo programa passa sem `E_HOST_*`. +- Gate U cobre ao menos 1 fixture positiva e 1 negativa de host-admission. + +## Tests + +- Positivo: binding `@sdk:gfx` com `[Capability(name = "gfx")]`. +- Negativo: binding host sem `Capability`. +- Negativo: capability desconhecida/declaracao invalida no contexto. +- Asserts por campos maquina-estaveis do diagnostico. + +## Non-Goals + +- Substituir validacao final do loader. +- Definir policy UX/prompts de permissao. +- Concluir modelo final de grants por plataforma. + +## Affected Documents + +- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md` +- `docs/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md` +- `docs/pbs/specs/12. Diagnostics Specification.md` +- `docs/pbs/specs/13. Lowering IRBackend Specification.md` + diff --git a/docs/pbs/pull-requests/PR-031-pbs-dependency-scoped-fail-fast-admission.md b/docs/pbs/pull-requests/PR-031-pbs-dependency-scoped-fail-fast-admission.md new file mode 100644 index 00000000..cb2f23bd --- /dev/null +++ b/docs/pbs/pull-requests/PR-031-pbs-dependency-scoped-fail-fast-admission.md @@ -0,0 +1,60 @@ +# PR-031 - PBS Dependency-Scoped Fail-Fast Admission + +## Briefing + +Hoje o pipeline pode continuar emitindo parte do `IRBackend` mesmo após erros de admissão em módulos dependidos (ex.: `E_LOAD_*`). +Isso permite artefato parcialmente válido em build com erro, o que aumenta risco de interpretação incorreta do resultado. + +Esta PR formaliza política de fail-fast por dependência: módulos que dependem de módulo reprovado não devem ser lowered/emitidos, sem interromper globalmente a coleta de diagnósticos. + +## Motivation + +- Evitar saída parcial enganosa quando há falha estrutural em módulo upstream. +- Manter diagnósticos úteis e completos no restante do grafo. +- Preservar determinismo do contrato de admissão no boundary do frontend. + +## Target + +- Ajustar admissão do `PBSFrontendPhaseService` para bloqueio transitivo por dependência de módulo falho. +- Preservar compilação/diagnóstico de módulos independentes no mesmo build. +- Tornar comportamento explícito e testável. + +## Scope + +- `prometeu-compiler/frontends/prometeu-frontend-pbs` (pipeline de admissão e merge de `IRBackendFile`). +- Testes de integração em `PBSFrontendPhaseServiceTest`. + +## Method + +1. Introduzir rastreamento de dependências entre módulos no frontend pipeline (import graph por módulo) usando apenas `import` explícito de source `.pbs`. +2. Quando um módulo falhar em admissão (`syntax`, `static semantics`, `linking`, `load-facing`, `host-admission` quando aplicável), marcar módulo como reprovado. +3. Propagar reprovação somente para módulos que importam (direta ou transitivamente) o módulo reprovado. +4. Impedir merge no `IRBackend` para: + - módulo reprovado, + - módulos bloqueados por dependência. +5. Manter emissão de diagnósticos e processamento para módulos independentes. + +## Acceptance Criteria + +- Se `A` falha e `B` depende de `A`, `B` não é emitido no `IRBackend`. +- Se `C` é independente de `A`, `C` continua apto a ser emitido. +- Build com erro não produz artefato parcial inconsistente no subgrafo dependente. +- Diagnósticos permanecem completos e com identidade estável (`code`, `phase`, `templateId`, `span`). + +## Tests + +- Cenário positivo: módulos independentes sobrevivem ao fail-fast por dependência. +- Cenário negativo: módulo dependente de módulo com `E_LOAD_*` não é lowered. +- Cenário negativo: módulo dependente de módulo com `E_LINK_*` não é lowered. +- Asserts por diagnóstico e por conteúdo final de `IRBackend`. + +## Non-Goals + +- Fail-fast global do build ao primeiro erro. +- Alterar contrato de runtime/loader. +- Redefinir severidade de diagnósticos existentes. + +## Affected Documents + +- `docs/pbs/specs/12. Diagnostics Specification.md` +- `docs/pbs/specs/13. Lowering IRBackend Specification.md`