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