globals and synthetic inits

This commit is contained in:
2026-03-24 13:42:58 +00:00
parent ecea7e96c0
commit 42255c38d0
4 changed files with 711 additions and 5 deletions
@@ -75,6 +75,7 @@ Esta agenda deve produzir direção suficiente para fechar:
5. O wrapper published entrypoint é um callable sintético explícito no graph do frontend?
6. Como manter attribution e diagnostics úteis para código sintético?
7. Que mudanças mínimas precisam acontecer em specs gerais fora de `docs/compiler/pbs`?
8. O lowering deve introduzir uma classe explícita de funções sintéticas com ergonomia própria, em vez de emissão ad hoc?
## Options
@@ -122,6 +123,164 @@ Tratar globals como açúcar compilado diretamente para slots/ops sem entidade i
Seguir com a **Option A**, salvo impedimento forte de boundary cross-domain.
## Current Direction
Os pontos abaixo já podem ser tratados como direção fechada desta agenda, salvo objeção nova forte:
1. globals devem entrar explicitamente no `IRBackend`;
2. o pipeline não deve adiar globals para uma materialização implícita tardia abaixo desse boundary;
3. fragments de init por arquivo, init sintético por módulo, init de projeto e wrapper published entrypoint devem existir como callables sintéticos explícitos;
4. o boot guard deve ser materializado como um global oculto;
5. esse global oculto não pode ser referenciado nem alterado por userland;
6. o wrapper published entrypoint deve existir explicitamente no graph de lowering;
7. o lowering deve seguir direção direta para as operações de globals já suportadas em `IRVM`/VM, isto é, `GET_GLOBAL` e `SET_GLOBAL`;
8. attribution e diagnostics devem preservar separadamente:
- origem em source userland,
- e origem sintética gerada pelo compiler;
9. quando algum erro estrutural ou de lowering surgir em código sintetizado, a superfície sintética deve ser capaz de carregar attribution de volta ao código real que originou aquele trecho;
10. spans e diagnostics devem preferir apontar para código real de userland sempre que essa origem existir;
11. o frontend/lowering deve introduzir uma classe explícita de funções sintéticas com ergonomia própria;
12. a emissão dessas funções não deve ser ad hoc caso a caso.
## Synthetic Callable Direction
Esta agenda também fecha a seguinte direção arquitetural:
1. callables sintéticos não devem ser tratados como acidentes de emissão;
2. eles devem possuir classe/identidade própria no lowering;
3. essa classe deve cobrir pelo menos:
- fragmentos de init por arquivo,
- init sintético por módulo,
- init de projeto,
- wrapper físico publicado;
4. a ergonomia dessa classe própria deve facilitar:
- ordenação,
- attribution,
- debug,
- testes,
- e futuras extensões de lifecycle sem reabrir o modelo básico.
Também fica fechada a seguinte exigência de diagnóstico:
1. a superfície sintética precisa carregar origem suficiente para remapear erros ao código real;
2. quando existir origem userland inequívoca, o diagnóstico deve preferir essa origem em vez de um span puramente sintético;
3. spans puramente sintéticos só devem aparecer quando não houver origem real defensável.
## Hidden Boot Guard Direction
O boot guard também fica com direção fechada nesta agenda:
1. ele deve existir como global oculto de programa;
2. ele pertence ao estado interno publicado pelo compiler;
3. userland não pode nomeá-lo, ler seu valor ou alterá-lo;
4. sua única função é garantir a semântica one-shot do bootstrap no wrapper físico.
## IRBackend Shape Direction
Esta agenda também fecha o seguinte shape estrutural mínimo para o `IRBackend`.
### 1. Backend Globals
O `IRBackend` deve carregar globals explicitamente como entidades estruturais, não apenas como efeitos implícitos no corpo de funções.
Direção mínima recomendada para cada global:
- `name`
- `ownerModuleId`
- `type`
- `slot`
- `visibility`
- `isHidden`
- `origin`
Isso deve cobrir:
- globals de userland;
- e globals ocultos do compiler, incluindo o boot guard.
### 2. Backend Callables
O `IRBackend` deve distinguir explicitamente:
- callables normais de userland;
- callables sintéticos gerados pelo compiler.
### 3. Synthetic Callable Kind
O conjunto mínimo de kinds sintéticos desta agenda deve cobrir:
- `FILE_INIT_FRAGMENT`
- `MODULE_INIT`
- `PROJECT_INIT`
- `PUBLISHED_FRAME_WRAPPER`
### 4. Synthetic Origin
Todo callable ou global sintético deve carregar metadados suficientes para attribution e remapeamento de diagnóstico.
Direção mínima recomendada:
- `derivedFromFile`
- `derivedFromModule`
- `derivedFromUserSymbol`
- `primarySpan`
- `fallbackSyntheticLabel`
### 5. Hidden Global Kind
O boot guard deve aparecer como global oculto com identidade estrutural explícita, não como convenção informal de nome.
Direção mínima recomendada:
- `BOOT_GUARD`
## Diagnostics and Conformance Direction
Esta agenda também fecha o seguinte conjunto mínimo de checks estruturais e evidências de conformance.
### Structural Diagnostics / Validation
1. `synthetic wrapper entrypoint missing`
- quando o pipeline não conseguir publicar o wrapper exigido.
2. `published entrypoint is not function index 0`
- quando o lowering violar o protocolo físico.
3. `hidden boot guard is missing`
- quando a semântica one-shot exigir o guard e ele não existir.
4. `synthetic callable origin missing`
- quando o lowering gerar callable sintético sem attribution suficiente para diagnóstico defensável.
### Conformance / Fixture Expectations
1. fixture com `declare global` + `[Init]` por arquivo + `[Init]` de projeto + `[Frame]`;
2. evidência de geração de:
- file init fragment,
- module init,
- project init,
- published wrapper,
- hidden boot guard;
3. evidência de que o wrapper ocupa `func_id = 0`;
4. evidência de que `FRAME_RET` está no wrapper;
5. evidência de que erro em lowering sintético remapeia para span real quando houver origem de userland defensável.
## Spec and Learn Propagation Direction
Esta agenda também fecha a seguinte direção editorial:
1. specs de lowering devem explicar de forma normativa:
- a classe de callables sintéticos,
- o lifecycle de init no lowering,
- o wrapper publicado,
- o hidden boot guard,
- e a relação desses artefatos com attribution e diagnostics;
2. `learn` deve explicar esse modelo de forma didática com exemplos de código source;
3. `learn` deve mostrar como:
- `declare global`,
- `[Init]` por arquivo,
- `[Init]` de projeto,
- e `[Frame]`
se compõem até virar o wrapper físico publicado;
4. a explicação didática em `learn` deve privilegiar exemplos concretos de source e composição, não apenas descrição abstrata do pipeline.
## Expected Spec Material
Se esta agenda fechar, a propagação esperada atinge pelo menos:
@@ -144,4 +303,3 @@ Esta agenda não deve:
Depois de fechar esta agenda, abrir ou aprofundar:
- `19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda`
@@ -2,7 +2,7 @@
## Status
Open
Closed
## Parent Agenda
@@ -107,6 +107,149 @@ Começar fixtures e diagnostics cedo, mesmo com arquitetura ainda mudando.
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:
@@ -127,7 +270,8 @@ Esta agenda não deve:
## Next Step
Depois do fechamento desta agenda, a linha `19` fica pronta para:
Esta agenda foi consolidada em:
- virar uma `decision` consolidada em `docs/compiler/pbs/decisions`;
- e então ser decomposta em `pull-request/plan` de execução.
- `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.