prometeu-studio/docs/compiler/pbs/agendas/19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda.md

Diagnostics, Manifest Propagation, and Conformance Coverage Agenda

Status

Closed

Parent Agenda

This agenda derives from:

• 19. Globals, Synthetic Module Init, and FRAME_RET Agenda

Expected fixed inputs from previous stages:

• 19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda
• 19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda
• 19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda
• 19.4. Globals and Lifecycle Lowering to IRBackend/IRVM Agenda

Purpose

Consolidate the propagation layer of topic 19 after the architectural decisions are already fixed.

This agenda must close:

• the diagnostics surface;
• manifest-facing propagation details;
• fixture and conformance coverage;
• and the acceptance gates for declaring topic 19 ready to become a decision plus implementation plan.

Domain Owner

docs/compiler/pbs

Este tema pertence ao domínio PBS, mas toca tanto specs normativas quanto critérios de teste e artefato publicado.

Context

Depois que surface, lifecycle, published entrypoint e lowering estiverem fechados, ainda faltará consolidar:

• quais erros novos são obrigatórios;
• em que fase cada erro aparece;
• como o manifest final reflete a arquitetura escolhida;
• e que coverage mínima de fixtures e gates garante que a série 19 ficou estável.

Esta agenda é de consolidação. Ela não deve rediscutir a arquitetura central.

Inputs Already Fixed Elsewhere

Os seguintes inputs devem ser tratados como fixos aqui:

• shape de globals vindo de 19.1;
• lifecycle vindo de 19.2;
• publication contract vindo de 19.3;
• lowering mechanics vindo de 19.4.

Decisions To Produce

Esta agenda deve produzir direção suficiente para fechar:

1. catálogo mínimo de diagnósticos;
2. fase responsável por cada diagnóstico;
3. propagação final para manifest/specs;
4. fixture matrix mínima;
5. critérios de aceite para converter a série 19 em decision e depois pull-request/plan.

Core Questions

1. Quais diagnósticos são obrigatórios para declare global, imports/reexports e ciclos?
2. Quais diagnósticos são obrigatórios para [Init] e [Frame]?
3. Quais erros pertencem a parser/AST, static semantics/linking, lowering, ou toolchain full pipeline?
4. Como o manifest final deve refletir entrypoint lógico e/ou físico escolhido em 19.3?
5. Que fixtures mínimas precisam existir para globals, module init, boot failure, wrapper e FRAME_RET?
6. Em que ponto a configuração explícita antiga de entrypoint em FrontendSpec pode ser considerada removida?
7. Quais gates de conformance precisam ser atualizados para cobrir a série 19?

Options

Option A

Consolidar diagnostics e coverage somente depois que os quatro stages anteriores estiverem fechados, com fixture matrix explícita por fase.

Option B

Começar fixtures e diagnostics cedo, mesmo com arquitetura ainda mudando.

Tradeoffs

Option A

• Prós:
  • reduz retrabalho;
  • evita congelar erro e coverage cedo demais;
  • combina melhor com a disciplina de umbrella agenda.
• Contras:
  • posterga parte da validação final.

Option B

• Prós:
  • feedback mais cedo.
• Contras:
  • alto risco de churn e reabertura de artefatos;
  • conflita com os locking rules da umbrella 19.

Recommendation

Seguir com a Option A.

Current Direction

Os pontos abaixo já podem ser tratados como direção fechada desta agenda, salvo objeção nova forte:

1. a 19.5 não reabre arquitetura; ela consolida diagnostics, propagation e coverage da série 19;
2. o catálogo final deve ser agrupado por fase, não apenas por ordem histórica das agendas;
3. a propagation final deve nomear explicitamente:
   • PBS specs,
   • general compiler specs,
   • runtime cross-domain owner,
   • e learn;
4. a conformance matrix mínima deve cobrir:
   • positive source flow,
   • negative frontend cases,
   • negative lowering/structural cases,
   • runtime integration.

Consolidated Diagnostics Direction

Esta agenda fecha a seguinte consolidação de diagnósticos por fase.

Frontend / Static Semantics

• global initializer uses unsupported form
• global dependency cycle detected
• imported symbol shadows existing visible symbol; alias required
• global import must resolve through a global barrel entry
• init function must have signature fn name() -> void
• frame function must have signature fn name() -> void
• multiple module init functions detected
• multiple project init functions detected
• multiple frame functions detected
• missing frame function for executable project
• Init attribute target invalid
• project init must be colocated with frame
• InitAllowed is valid only on SDK host methods
• host call not allowed during init

Lowering / Structural Validation

• synthetic wrapper entrypoint missing
• published entrypoint is not function index 0
• hidden boot guard is missing
• synthetic callable origin missing

Runtime / Boot Failure

• boot failed during module init
• boot failed during project init

Também fica fechada a seguinte leitura:

1. diagnósticos de frontend/static semantics são user-facing do compiler;
2. checks de lowering podem aparecer como diagnostics, validation failures ou invariant violations, desde que a falha seja observável e testável;
3. falhas de boot do runtime pertencem à superfície de falha operacional, não ao frontend static diagnostic catalog.

Propagation Targets Direction

Esta agenda fecha a seguinte lista mínima de propagation targets.

PBS Specs

• 3. Core Syntax Specification.md
• 4. Static Semantics Specification.md
• 9. Dynamic Semantics Specification.md
• 11. AST Specification.md
• 12. Diagnostics Specification.md
• 13. Lowering IRBackend Specification.md
• 7. Cartridge Manifest and Runtime Capabilities Specification.md

General Compiler Specs

• 15. Bytecode and PBX Mapping Specification.md
• 20. IRBackend to IRVM Lowering Specification.md

Runtime Cross-Domain Owner

• ../runtime/docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md

Learn

• um learn consolidado para globals + lifecycle + published wrapper + entrypoint protocol
• com explicação source-first e depois lowering/publication

Conformance Matrix Direction

Esta agenda fecha a seguinte matrix mínima de coverage.

Positive Coverage

Projeto com:

• declare global
• [Init] por arquivo
• [Init] de projeto
• [Frame]

Assert mínimo:

• globals aceitos
• ordering aceito
• wrapper publicado
• func_id = 0
• FRAME_RET no wrapper
• boot guard presente

Negative Frontend Coverage

• global com fn no initializer
• global com if
• ciclo entre globals
• collision entre import e const/global/service/fn
• [Init] com assinatura errada
• [Frame] com assinatura errada
• dois [Frame]
• dois project init
• project init fora do arquivo do [Frame]
• host call em init sem [InitAllowed]
• [InitAllowed] em target inválido

Negative Lowering Coverage

• ausência de wrapper publicado
• wrapper fora do índice 0
• ausência de boot guard
• callable sintético sem origin metadata

Runtime Integration Coverage

• artefato sobe com entrypoint físico 0
• runtime não depende de export nominal para boot
• boot failure em module init gera falha coerente
• boot failure em project init gera falha coerente

Exit Direction

Esta agenda considera a série 19 pronta para virar execução quando houver:

1. catálogo consolidado de diagnósticos fechado;
2. propagation targets explicitamente nomeados;
3. conformance matrix mínima aceita;
4. owner explícito para a frente cross-domain de runtime.

Expected Spec Material

Se esta agenda fechar, a propagação esperada atinge pelo menos:

• 7. Cartridge Manifest and Runtime Capabilities Specification.md
• 12. Diagnostics Specification.md
• 13. Lowering IRBackend Specification.md
• docs de conformance/fixtures relevantes

Non-Goals

Esta agenda não deve:

1. redefinir semântica de globals;
2. redefinir lifecycle;
3. redefinir wrapper ou ownership de FRAME_RET;
4. redefinir shape de IR.

Next Step

Esta agenda foi consolidada em:

• docs/compiler/pbs/decisions/Diagnostics, Manifest Propagation, and Conformance Coverage Decision.md

Com isso, a família 19 fica pronta para ser decomposta em pull-request/plan de execução.