71 lines
3.2 KiB
Markdown
71 lines
3.2 KiB
Markdown
# 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`
|
|
|