278 lines
8.3 KiB
Markdown
278 lines
8.3 KiB
Markdown
# 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.
|