discussion framework migration
This commit is contained in:
-689
@@ -1,689 +0,0 @@
|
||||
# Globals, Synthetic Module Init, and FRAME_RET Agenda
|
||||
|
||||
## Status
|
||||
|
||||
Open
|
||||
|
||||
## Purpose
|
||||
|
||||
Define how PBS should introduce runtime globals and lifecycle-driven executable bootstrap without changing the runtime contract in this phase.
|
||||
|
||||
This document is the umbrella agenda for topic `19`.
|
||||
|
||||
It exists to:
|
||||
|
||||
- keep the full problem framed in one place;
|
||||
- define the dependency order between discussions;
|
||||
- prevent later discussions from re-opening earlier boundaries casually;
|
||||
- and provide the parent reference for any follow-up agendas created under this topic.
|
||||
|
||||
This agenda must converge on:
|
||||
|
||||
- the source-level model for mutable module storage;
|
||||
- the lifecycle model for module init, optional program init, and frame execution;
|
||||
- the ownership of `FRAME_RET` once the published entrypoint stops being the user's `frame()` directly;
|
||||
- the migration path from explicit `FrontendSpec` entrypoint configuration to source-derived PBS entrypoint discovery.
|
||||
|
||||
## Domain Owner
|
||||
|
||||
`docs/compiler/pbs`
|
||||
|
||||
Este tema pertence ao domínio PBS do compiler porque afeta diretamente:
|
||||
|
||||
- a surface language de declarações top-level;
|
||||
- a detecção de entrypoints pelo frontend PBS;
|
||||
- o modelo de inicialização de módulo e programa;
|
||||
- o lowering de entrypoint de frame;
|
||||
- a relação entre entrypoint lógico do usuário e entrypoint publicado no artefato;
|
||||
- o contrato interno entre frontend, `IRBackend`, `IRVM` lowering e bytecode final.
|
||||
|
||||
Nesta fase, o owner continua sendo `compiler/pbs` mesmo quando o resultado reutilizar capacidades já existentes da VM, porque a discussão é sobre como o compiler vai expor e orquestrar essas capacidades.
|
||||
|
||||
## Problema
|
||||
|
||||
Hoje o PBS não expõe variáveis globais mutáveis de módulo.
|
||||
|
||||
O topo do arquivo aceita `declare const`, mas `declare const` é compile-time e não storage runtime. Isso impede formas como:
|
||||
|
||||
```pbs
|
||||
declare struct Vec2(x: int, y: int);
|
||||
|
||||
declare global origin: Vec2 = new Vec2(0, 0);
|
||||
```
|
||||
|
||||
Ao mesmo tempo:
|
||||
|
||||
1. a VM já tem suporte operacional para globals por slot;
|
||||
2. o compiler não modela globals no IR executável atual;
|
||||
3. o entrypoint de frame do usuário hoje coincide, na prática, com a função que delimita o frame lógico;
|
||||
4. o pipeline atual usa `FRAME_RET` no final desse fluxo de frame lógico.
|
||||
5. a seleção do entrypoint ainda depende de configuração explícita em `FrontendSpec`, em vez de ser derivada da própria source language do PBS.
|
||||
|
||||
Se introduzirmos `declare global`, o compiler precisará definir:
|
||||
|
||||
1. como globals são inicializados;
|
||||
2. quando essa inicialização roda;
|
||||
3. como garantir execução uma única vez;
|
||||
4. como conviver com um `init()` custom do usuário;
|
||||
5. como detectar de forma canônica quais funções do usuário exercem os papéis de `init` e `frame`;
|
||||
6. como preservar o contrato de frame lógico quando a função publicada deixar de ser a função `frame()` original do usuário.
|
||||
|
||||
## Contexto
|
||||
|
||||
O estado atual do sistema é:
|
||||
|
||||
- PBS proíbe `let` top-level e não expõe storage mutável de módulo;
|
||||
- `declare const` é avaliado em compile time e pode ser inlinado/foldado;
|
||||
- inicializadores não constantes como `new`, call sugar, `some`, `none`, `if`, `switch` e outras formas executáveis não pertencem ao modelo de `declare const`;
|
||||
- a VM do runtime já possui `GetGlobal` e `SetGlobal`;
|
||||
- o `IRBackend` executável atual modela locals, calls, jumps e literais, mas não modela globals;
|
||||
- o entrypoint de frame hoje é tratado como raiz do frame lógico, inclusive para o ponto final onde `FRAME_RET` é emitido;
|
||||
- o frontend PBS ainda depende de configuração explícita em `FrontendSpec` para saber qual callable é o entrypoint publicado;
|
||||
- hoje isso aparece como acoplamento a nomes/configuração que deveriam ser deduzidos pela própria linguagem.
|
||||
|
||||
O cenário motivador é permitir globals de módulo no PBS sem exigir, nesta fase, mudança de runtime.
|
||||
|
||||
Também queremos aproveitar essa discussão para mover a detecção de entrypoint para a source language do PBS, usando atributos explícitos:
|
||||
|
||||
```pbs
|
||||
[Init]
|
||||
fn init() -> void {}
|
||||
|
||||
[Frame]
|
||||
fn frame() -> void {}
|
||||
```
|
||||
|
||||
Essa direção permitiria ao frontend PBS:
|
||||
|
||||
1. localizar explicitamente o init do usuário;
|
||||
2. localizar explicitamente o frame root do usuário;
|
||||
3. montar o wrapper sintético final sem depender de configuração paralela em `FrontendSpec`;
|
||||
4. eliminar, nesta linha de evolução, a configuração explícita atual de entrypoint no registry/spec do frontend.
|
||||
|
||||
Esta agenda também cobre a extensão desse modelo para discutir:
|
||||
|
||||
1. se `[Init]` deve existir apenas como hook final de programa ou também como surface por módulo;
|
||||
2. qual é exatamente o comportamento operacional de `[Frame]` como root lógico de frame do usuário;
|
||||
3. como `[Init]` por módulo, `[Init]` final de programa, wrapper sintético e `FRAME_RET` se compõem sem ambiguidade.
|
||||
|
||||
Isso empurra a solução para o compiler:
|
||||
|
||||
1. synth de init por módulo;
|
||||
2. synth de wrapper do frame published entrypoint;
|
||||
3. eventual símbolo privado `boot_done`;
|
||||
4. redefinição do ponto onde o frame lógico realmente termina;
|
||||
5. detecção de `init`/`frame` a partir de atributos de source;
|
||||
6. remoção progressiva das configs explícitas atuais em `FrontendSpec`.
|
||||
|
||||
## Inputs
|
||||
|
||||
Relevant inputs already present in the repository:
|
||||
|
||||
- `docs/vm-arch/ISA_CORE.md` already exposes `GET_GLOBAL` and `SET_GLOBAL`;
|
||||
- `docs/compiler/pbs/specs/13. Lowering IRBackend Specification.md` currently requires a canonical executable entrypoint to be declared through `FrontendSpec`;
|
||||
- `docs/compiler/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md` currently expects PBS v1 manifest `entrypoint` to align with frontend-declared `frame`.
|
||||
|
||||
The discussion here must preserve compatibility with those contracts unless it explicitly proposes the propagation work needed to evolve them.
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. PBS deve introduzir `declare global` como declaração top-level distinta de `declare const`?
|
||||
2. `declare global` deve aceitar inicializadores executáveis como `new Vec2(...)`, calls e outras expressões lowerables?
|
||||
3. O compiler deve sintetizar um module init por módulo que contenha `declare global`?
|
||||
4. A inicialização deve rodar eager no boot lógico do programa ou lazy no primeiro frame?
|
||||
5. Deve existir um `init()` custom do usuário que roda depois de todos os module inits e antes do primeiro `frame()`?
|
||||
6. O PBS deve introduzir atributos explícitos `[Init]` e `[Frame]` para identificar as funções corretas do usuário?
|
||||
7. A descoberta de entrypoint no frontend PBS deve deixar de depender de configuração explícita em `FrontendSpec`?
|
||||
8. `[Init]` deve poder existir também em escopo/módulo de forma declarativa para orientar module init explícito, ou o compiler deve manter module init sempre totalmente sintético?
|
||||
9. Qual é o contrato preciso de comportamento de `[Frame]` no PBS: callable obrigatório, assinatura fixa, frequência esperada e relação com o frame lógico publicado?
|
||||
10. O published frame entrypoint deve passar a ser um wrapper sintético, por exemplo `__pbs_frame()`, em vez do `frame()` do usuário?
|
||||
11. `FRAME_RET` deve continuar significando "fim do frame lógico" e apenas mudar de owner, saindo da função do usuário para o wrapper sintético?
|
||||
12. Como o compiler deve tratar ordem topológica, dependências e ciclos entre globals de módulos distintos?
|
||||
13. Qual política vale quando algum module init ou `init()` do usuário falha: retry no próximo frame, fail-fast, ou outra forma?
|
||||
14. Globals exportados por `mod.barrel` devem se comportar como storage compartilhado de módulo ou como snapshot/importação por valor?
|
||||
|
||||
## Inputs Already Fixed Elsewhere
|
||||
|
||||
Os seguintes pontos já parecem fixos ou fortemente estabelecidos e não devem ser contraditos nesta agenda:
|
||||
|
||||
- a VM já suporta globals em nível de bytecode/execução;
|
||||
- `declare const` não é storage mutável/runtime-initialized;
|
||||
- o runtime já sabe executar um entrypoint published por frame;
|
||||
- `FRAME_RET` já é usado como marcador do fim de um frame lógico;
|
||||
- o frontend PBS hoje ainda carrega configuração explícita de entrypoint fora da source language;
|
||||
- nesta fase queremos evitar mudanças novas no runtime e concentrar a evolução no compiler.
|
||||
|
||||
## Decisions To Produce
|
||||
|
||||
Como umbrella agenda, esta agenda não deve tentar fechar toda a solução normativa de uma vez.
|
||||
|
||||
Ela deve sair com:
|
||||
|
||||
1. a decomposição oficial do tema em discussões derivadas;
|
||||
2. a ordem canônica dessas discussões;
|
||||
3. os inputs e outputs esperados de cada boundary;
|
||||
4. a lista de artefatos que não podem ser editados antes do boundary anterior fechar.
|
||||
|
||||
Depois que as discussões derivadas fecharem, o conjunto deve produzir direção suficiente para virar uma `decision` cobrindo pelo menos:
|
||||
|
||||
1. a surface syntax e o modelo semântico de `declare global`;
|
||||
2. o modelo de bootstrap entre module init sintético, `[Init]` de programa e `[Frame]`;
|
||||
3. o owner real do frame lógico publicado e o ponto correto de emissão de `FRAME_RET`;
|
||||
4. a política de descoberta de entrypoint a partir da source language do PBS;
|
||||
5. a política de ordenação, ciclos e falhas para globals e module init;
|
||||
6. a política de imports/exports para globals entre módulos.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A
|
||||
|
||||
Adicionar `declare global`, introduzir `[Init]` e `[Frame]` como superfícies explícitas para lifecycle/entrypoint, discutir `[Init]` final vs `[Init]` por módulo, gerar module init sintético por módulo, gerar wrapper sintético de frame published entrypoint e mover o `FRAME_RET` para esse wrapper.
|
||||
|
||||
### Option B
|
||||
|
||||
Adicionar `declare global`, mas exigir init totalmente estático ou restrito, sem `init()` custom do usuário e sem wrapper published separado do `frame()` atual.
|
||||
|
||||
### Option C
|
||||
|
||||
Não adicionar `declare global` agora; manter apenas `declare const` e postergar a discussão até existir um modelo maior de bootstrap/program lifecycle.
|
||||
|
||||
### Option D
|
||||
|
||||
Adicionar `declare global`, mas exigir lazy materialization no primeiro acesso em vez de module init explícito por ordem topológica.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
### Option A
|
||||
|
||||
- Prós:
|
||||
- modelo explícito e fácil de explicar;
|
||||
- acomoda `declare global` com inicializadores realmente executáveis;
|
||||
- faz o PBS declarar na própria linguagem quais são os callables de `init` e `frame`;
|
||||
- abre espaço para discutir de forma unificada `init` por módulo, `init` final e root de frame;
|
||||
- permite `init()` custom do usuário sem mudar o runtime;
|
||||
- preserva o significado de `FRAME_RET` como fim do frame lógico;
|
||||
- remove um acoplamento indesejado entre frontend PBS e configuração manual de entrypoint em `FrontendSpec`.
|
||||
- Contras:
|
||||
- exige nova modelagem no compiler para globals, init synthesis e published frame wrapper;
|
||||
- exige regras novas de atributo e validação de unicidade para `[Init]` e `[Frame]`;
|
||||
- obriga decisão clara sobre ordem, ciclos e falhas;
|
||||
- muda a relação atual entre `frame()` do usuário e entrypoint publicado.
|
||||
|
||||
### Option B
|
||||
|
||||
- Prós:
|
||||
- escopo menor;
|
||||
- reduz a superfície de lifecycle;
|
||||
- pode evitar parte da complexidade de wrapper e boot state.
|
||||
- Contras:
|
||||
- resolve mal o caso motivador com `new Vec2(...)`;
|
||||
- produz uma feature de globais com restrição semântica forte demais;
|
||||
- deixa o `init()` do usuário para outra rodada e pode forçar redesign posterior.
|
||||
|
||||
### Option C
|
||||
|
||||
- Prós:
|
||||
- nenhum risco imediato em pipeline/backend;
|
||||
- preserva o estado atual do compiler.
|
||||
- Contras:
|
||||
- não resolve o caso desejado;
|
||||
- mantém uma lacuna entre capacidade da VM e surface language do PBS;
|
||||
- posterga um problema arquitetural que já apareceu de forma concreta.
|
||||
|
||||
### Option D
|
||||
|
||||
- Prós:
|
||||
- evita bootstrap eager explícito;
|
||||
- pode reduzir custo de init em módulos não usados.
|
||||
- Contras:
|
||||
- complica determinismo e observabilidade;
|
||||
- torna mais difícil explicar dependências entre módulos;
|
||||
- aumenta risco semântico para reentrância, ciclos e ordem de efeitos;
|
||||
- parece desnecessariamente sofisticado para v1.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Seguir com a **Option A**.
|
||||
|
||||
Direção recomendada para discussão:
|
||||
|
||||
1. introduzir `declare global` como nova declaração top-level distinta de `declare const`;
|
||||
2. permitir inicializadores executáveis lowerables, incluindo `new` e calls compatíveis com o modelo de lowering executável;
|
||||
3. sintetizar um module init por módulo owner de globals;
|
||||
4. ordenar os module inits de forma determinística e topológica;
|
||||
5. introduzir `[Init]` e `[Frame]` como superfícies explícitas de detecção do init/frame do usuário;
|
||||
6. remover da evolução do PBS a dependência de configuração explícita de entrypoint em `FrontendSpec`, migrando a seleção para a análise da source language;
|
||||
7. discutir explicitamente se `[Init]` por módulo será uma surface do usuário ou se módulo continuará com init apenas sintético;
|
||||
8. permitir um `init()` custom opcional do usuário, executado depois de todos os module inits;
|
||||
9. publicar um wrapper sintético de frame, por exemplo `__pbs_frame()`, como verdadeiro frame root;
|
||||
10. tratar `frame()` do usuário como callable normal invocado por esse wrapper;
|
||||
11. manter `FRAME_RET` como marcador do fim do frame lógico, mas emitido no wrapper sintético publicado em vez de no `frame()` do usuário;
|
||||
12. manter toda a primeira fase restrita ao compiler e ao backend pipeline, sem novos requisitos para o runtime além dos contratos já existentes.
|
||||
|
||||
Essa recomendação ainda deixa alguns pontos para fechamento na `decision`, mas já estabelece um shape arquitetural coerente:
|
||||
|
||||
- storage global pertence ao módulo owner;
|
||||
- bootstrap observável pertence ao compiler, não ao runtime;
|
||||
- `frame()` do usuário deixa de ser o entrypoint publicado e passa a ser o root lógico invocado pelo wrapper;
|
||||
- `FRAME_RET` continua significando fim do frame lógico, apenas com novo owner sintético;
|
||||
- a seleção de entrypoint deixa de ser configuração paralela e vira semântica explícita da linguagem.
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. O nome surface deve ser exatamente `declare global`, ou outra forma top-level?
|
||||
2. Globals devem exigir initializer obrigatório em v1, ou existirão shells reservados parecidos com builtin const?
|
||||
3. `[Init]` e `[Frame]` devem ser atributos reservados do PBS ou outra forma de marker surface?
|
||||
4. `[Init]` deve exigir assinatura fixa `fn init() -> void`?
|
||||
5. `[Frame]` deve exigir assinatura fixa `fn frame() -> void`?
|
||||
6. Deve existir no máximo um `[Init]` e um `[Frame]` por programa, por módulo owner, ou por outro escopo?
|
||||
7. Module init deve permanecer sempre sintético em v1, ou o usuário pode anotar hooks por módulo em alguma forma futura?
|
||||
8. A política de falha de init deve ser fail-fast definitivo no boot, ou existe algum caso legítimo para retry controlado?
|
||||
9. Reexport de globals entre módulos deve preservar identidade de storage do owner original ou materializar aliases/import bindings sem storage próprio?
|
||||
10. O manifest `entrypoint` deve continuar expondo `frame` por compatibilidade nominal ou passar a refletir o símbolo sintético publicado?
|
||||
|
||||
## Main Difficulties
|
||||
|
||||
Os principais pontos de dificuldade desta agenda não são sintáticos; eles estão na composição entre contratos já existentes.
|
||||
|
||||
### 1. `declare global` colide com o recorte atual de `declare const`
|
||||
|
||||
Hoje a semântica estática do PBS fixa que:
|
||||
|
||||
- `declare const` entra no value namespace;
|
||||
- `declare const` não materializa storage mutável runtime;
|
||||
- inicializadores de `declare const` pertencem a um subset estritamente compile-time;
|
||||
- dependências entre `declare const` são acíclicas e resolvidas por análise de dependência, não por ordem textual.
|
||||
|
||||
Introduzir `declare global` exige decidir o que é reaproveitado desse modelo e o que deixa de valer:
|
||||
|
||||
- namespace e visibilidade podem reaproveitar parte do modelo atual;
|
||||
- constant evaluation não pode ser reutilizada como está;
|
||||
- o modelo de dependência deixa de ser apenas compile-time e passa a produzir efeitos runtime.
|
||||
|
||||
### 2. A surface de atributos hoje tem um conjunto reservado fechado
|
||||
|
||||
O PBS já trata atributos como metadata compile-time com lowering explícito apenas quando outra spec define esse efeito.
|
||||
|
||||
Isso é favorável para `[Init]` e `[Frame]`, mas cria trabalho em três frentes:
|
||||
|
||||
- reservar novos atributos no conjunto normativo;
|
||||
- definir targets válidos, unicidade e diagnóstico;
|
||||
- definir o lowering sem deixar atributos "soltos" como metadata sem efeito operacional claro.
|
||||
|
||||
### 3. O entrypoint publicado hoje ainda está acoplado ao `FrontendSpec`
|
||||
|
||||
Existe uma obrigação atual em `13. Lowering IRBackend Specification.md` para o frontend declarar um `EntrypointRef` canônico.
|
||||
|
||||
A agenda 19 quer mover a descoberta para a source language, mas isso abre uma transição delicada:
|
||||
|
||||
- PBS precisa derivar esse `EntrypointRef` da source language;
|
||||
- o contrato de `IRBackend` não deve perder determinismo;
|
||||
- a migração não pode deixar coexistirem por muito tempo duas autoridades independentes para entrypoint.
|
||||
|
||||
### 4. O manifest ainda assume `frame` como callable publicado
|
||||
|
||||
`7. Cartridge Manifest and Runtime Capabilities Specification.md` hoje sugere alinhamento nominal entre manifest `entrypoint` e callable `frame`.
|
||||
|
||||
Se o compiler publicar `__pbs_frame()`:
|
||||
|
||||
- ou o manifest passa a refletir o símbolo sintético real;
|
||||
- ou o manifest preserva um nome lógico enquanto o símbolo real do artefato muda;
|
||||
- ou a pipeline passa a distinguir entrypoint lógico e entrypoint físico.
|
||||
|
||||
Sem fechar isso, a solução de wrapper fica tecnicamente incompleta.
|
||||
|
||||
### 5. `FRAME_RET` hoje coincide com o fim do callable do usuário
|
||||
|
||||
O ponto difícil não é só "mover um opcode". É redefinir qual callable delimita semanticamente o frame lógico:
|
||||
|
||||
- `frame()` do usuário continua sendo apenas código de frame;
|
||||
- o wrapper sintético vira o owner do frame published entrypoint;
|
||||
- `FRAME_RET` continua com o mesmo significado semântico, mas sua posição material muda.
|
||||
|
||||
Isso afeta lowering, testes de conformance e a forma de explicar o modelo da linguagem.
|
||||
|
||||
### 6. Globals intermodulares introduzem um problema novo de identidade e ordem
|
||||
|
||||
Hoje `declare const` exportado via `mod.barrel` é simples porque não há storage mutável compartilhado.
|
||||
|
||||
Com `declare global`, a agenda precisa fechar:
|
||||
|
||||
- quem é o owner real do storage;
|
||||
- o que um import recebe: binding para o owner ou cópia/snapshot;
|
||||
- como ciclos entre módulos são detectados;
|
||||
- se init pode ler globals de módulos predecessores;
|
||||
- qual é a ordem determinística entre módulos quando há efeitos de inicialização.
|
||||
|
||||
### 7. A política de falha deixa de ser apenas rejeição de build
|
||||
|
||||
Hoje boa parte do pipeline falha antes da emissão.
|
||||
|
||||
Com module init e `init()` do usuário, surge um problema runtime-observable:
|
||||
|
||||
- o que acontece quando o boot parcial falha;
|
||||
- se o programa entra em estado terminal;
|
||||
- se existe retry;
|
||||
- como isso se relaciona com o fato de `FRAME_SYNC` permanecer o safepoint normativo.
|
||||
|
||||
## Work Boundaries
|
||||
|
||||
Para manter a agenda executável e evitar mistura de artefatos, o trabalho pode ser separado nos seguintes boundaries.
|
||||
|
||||
### Boundary A. Surface Language and AST
|
||||
|
||||
Owner principal: syntax + AST.
|
||||
|
||||
Inclui:
|
||||
|
||||
- gramática de `declare global`;
|
||||
- superfície de atributos `[Init]` e `[Frame]`;
|
||||
- targets permitidos desses atributos;
|
||||
- novos nós ou flags obrigatórios no AST para globals e lifecycle markers.
|
||||
|
||||
Pergunta de fechamento:
|
||||
|
||||
- o parser apenas aceita as superfícies ou já impõe parte das restrições estruturais de target/shape?
|
||||
|
||||
### Boundary B. Static Semantics and Linking
|
||||
|
||||
Owner principal: static semantics + linking.
|
||||
|
||||
Inclui:
|
||||
|
||||
- namespace e visibilidade de `declare global`;
|
||||
- regras de initializer obrigatório ou opcional;
|
||||
- compatibilidade de tipo do initializer;
|
||||
- unicidade e assinatura válida para `[Init]` e `[Frame]`;
|
||||
- regras de import/export/barrel para globals;
|
||||
- detecção de ciclos de dependência entre globals;
|
||||
- política de identidade do storage através de imports e reexports.
|
||||
|
||||
Pergunta de fechamento:
|
||||
|
||||
- globals entram no mesmo value namespace de `let`/`declare const` ou exigem distinção semântica adicional apesar do namespace compartilhado?
|
||||
|
||||
### Boundary C. Dynamic Semantics and Lifecycle Model
|
||||
|
||||
Owner principal: dynamic semantics.
|
||||
|
||||
Inclui:
|
||||
|
||||
- ordem observável entre module init, `[Init]` de programa e `[Frame]`;
|
||||
- definição de boot one-shot;
|
||||
- política de falha de init;
|
||||
- contrato semântico de `[Frame]` como raiz lógica do tick/frame do usuário;
|
||||
- relação entre frame lógico do usuário e entrypoint efetivamente publicado.
|
||||
|
||||
Pergunta de fechamento:
|
||||
|
||||
- o programa tem dois conceitos distintos, `logical frame root` e `published runtime entrypoint`, ou a spec tenta esconder essa distinção do usuário?
|
||||
|
||||
### Boundary D. IR and Backend Lowering
|
||||
|
||||
Owner principal: lowering executável.
|
||||
|
||||
Inclui:
|
||||
|
||||
- representação de globals no `IRBackend` ou boundary imediatamente anterior;
|
||||
- synthesis de module init;
|
||||
- synthesis de wrapper published entrypoint;
|
||||
- materialização do guard one-shot de boot;
|
||||
- reposicionamento do `FRAME_RET`;
|
||||
- preservação do `EntrypointRef` canônico para o restante do backend.
|
||||
|
||||
Pergunta de fechamento:
|
||||
|
||||
- globals entram como primitivo explícito no IR ou aparecem apenas em lowering posterior antes de IRVM/bytecode?
|
||||
|
||||
### Boundary E. Artifact and Manifest Publication
|
||||
|
||||
Owner principal: artifact contracts.
|
||||
|
||||
Inclui:
|
||||
|
||||
- nome do entrypoint exposto no manifest;
|
||||
- relação entre callable do usuário, símbolo sintético e entrypoint published;
|
||||
- compatibilidade com o contrato atual do cartridge manifest;
|
||||
- possíveis ajustes na leitura de tooling sobre qual callable é o entrypoint "real".
|
||||
|
||||
Pergunta de fechamento:
|
||||
|
||||
- o manifest publica identidade lógica da linguagem ou identidade física do artefato executável?
|
||||
|
||||
### Boundary F. Diagnostics and Conformance
|
||||
|
||||
Owner principal: diagnostics + fixture model.
|
||||
|
||||
Inclui:
|
||||
|
||||
- diagnósticos para target inválido de `[Init]` e `[Frame]`;
|
||||
- duplicidade ou ausência de markers obrigatórios;
|
||||
- initializer inválido de `declare global`;
|
||||
- ciclos intra/inter-módulo;
|
||||
- imports/reexports ilegais de globals;
|
||||
- fixture coverage para init ordering, wrapper published entrypoint e `FRAME_RET`.
|
||||
|
||||
Pergunta de fechamento:
|
||||
|
||||
- quais erros pertencem ao frontend/linking e quais só podem ser cobertos por fixtures de toolchain completo?
|
||||
|
||||
## Discussion Order
|
||||
|
||||
As discussões derivadas desta umbrella agenda devem seguir a ordem abaixo.
|
||||
|
||||
O objetivo da ordem é simples:
|
||||
|
||||
- fechar primeiro autoridade semântica e surface;
|
||||
- depois fechar comportamento observável;
|
||||
- só então descer para lowering, artefato publicado e conformance.
|
||||
|
||||
### Stage 1. Globals Surface and Static Identity
|
||||
|
||||
Boundary owner:
|
||||
|
||||
- `Boundary A. Surface Language and AST`
|
||||
- `Boundary B. Static Semantics and Linking`
|
||||
|
||||
Esta discussão deve fechar primeiro porque todas as outras dependem da definição do que é um global no PBS.
|
||||
|
||||
Ela precisa decidir:
|
||||
|
||||
- a forma exata de `declare global`;
|
||||
- initializer obrigatório ou opcional;
|
||||
- namespace, visibilidade e barrel/export/import;
|
||||
- identidade do storage owner;
|
||||
- política de reexport;
|
||||
- ciclos e dependências entre globals em nível de linking/static semantics.
|
||||
|
||||
Sem esse fechamento:
|
||||
|
||||
- lifecycle ainda não sabe o que precisa inicializar;
|
||||
- lowering ainda não sabe que entidade precisa materializar;
|
||||
- manifest ainda não sabe se está publicando símbolos que dependem de storage global importado.
|
||||
|
||||
### Stage 2. Lifecycle Markers and Program Bootstrap Semantics
|
||||
|
||||
Boundary owner:
|
||||
|
||||
- `Boundary C. Dynamic Semantics and Lifecycle Model`
|
||||
|
||||
Esta discussão vem depois de Stage 1 porque init e frame só fazem sentido quando o modelo de globals já estiver fixado.
|
||||
|
||||
Ela precisa decidir:
|
||||
|
||||
- se `[Init]` e `[Frame]` entram como superfícies oficiais;
|
||||
- unicidade e assinatura desses markers;
|
||||
- ordem entre module init, `[Init]` de programa e `[Frame]`;
|
||||
- política de boot one-shot;
|
||||
- política de falha;
|
||||
- papel semântico exato de `frame()` do usuário.
|
||||
|
||||
Sem esse fechamento:
|
||||
|
||||
- o wrapper sintético não tem contrato observável estável;
|
||||
- `FRAME_RET` não tem owner definido;
|
||||
- qualquer modelagem de IR corre risco de materializar o comportamento errado.
|
||||
|
||||
### Stage 3. Published Entrypoint, Wrapper Ownership, and `FRAME_RET`
|
||||
|
||||
Boundary owner:
|
||||
|
||||
- `Boundary C. Dynamic Semantics and Lifecycle Model`
|
||||
- `Boundary D. IR and Backend Lowering`
|
||||
- `Boundary E. Artifact and Manifest Publication`
|
||||
|
||||
Esta discussão depende de Stage 2 porque ela não decide mais "o que é lifecycle"; ela decide como lifecycle é publicado.
|
||||
|
||||
Ela precisa decidir:
|
||||
|
||||
- se o published entrypoint é um wrapper sintético;
|
||||
- qual é a relação entre `frame()` do usuário e esse wrapper;
|
||||
- onde `FRAME_RET` passa a ser emitido;
|
||||
- se o manifest expõe entrypoint lógico, entrypoint físico ou ambos;
|
||||
- como o `EntrypointRef` do frontend continua determinístico durante a transição.
|
||||
|
||||
Sem esse fechamento:
|
||||
|
||||
- não existe contrato estável para lowering final;
|
||||
- specs de manifest e `IRBackend` ficam em tensão;
|
||||
- o tooling pode continuar com duas autoridades concorrentes para entrypoint.
|
||||
|
||||
### Stage 4. IR Representation and Lowering Mechanics
|
||||
|
||||
Boundary owner:
|
||||
|
||||
- `Boundary D. IR and Backend Lowering`
|
||||
|
||||
Esta discussão vem depois de Stage 3 porque a forma do IR depende do que exatamente precisa ser publicado e executado.
|
||||
|
||||
Ela precisa decidir:
|
||||
|
||||
- se globals entram como primitivo explícito do IR ou apenas em lowering posterior;
|
||||
- como module init é representado;
|
||||
- como o guard de boot é materializado;
|
||||
- como o wrapper published entrypoint é emitido;
|
||||
- como `FRAME_RET` é reposicionado mantendo o mesmo significado.
|
||||
|
||||
Sem esse fechamento:
|
||||
|
||||
- código pode ser implementado cedo demais sobre contratos ainda móveis;
|
||||
- a propagação para specs gerais de lowering fica prematura;
|
||||
- testes de backend podem congelar um shape errado.
|
||||
|
||||
### Stage 5. Diagnostics, Gates, and Conformance Coverage
|
||||
|
||||
Boundary owner:
|
||||
|
||||
- `Boundary F. Diagnostics and Conformance`
|
||||
|
||||
Esta discussão deve vir por último porque ela consolida o que as anteriores já fixaram.
|
||||
|
||||
Ela precisa decidir:
|
||||
|
||||
- catálogo mínimo de diagnósticos novos;
|
||||
- divisão entre erro de syntax/AST, linking/static semantics, lowering e toolchain;
|
||||
- fixtures obrigatórios para globals, lifecycle, wrapper e entrypoint publication;
|
||||
- critérios de aceite para a migração de `FrontendSpec` entrypoint config para source-derived entrypoint discovery.
|
||||
|
||||
Fazer isso antes cria dois riscos:
|
||||
|
||||
- congelar diagnósticos para regras ainda instáveis;
|
||||
- ou escrever fixtures de conformance que depois precisam ser reabertas por mudança arquitetural.
|
||||
|
||||
## Derived Agenda Outline
|
||||
|
||||
Se quisermos quebrar a umbrella agenda em agendas filhas, a ordem recomendada é:
|
||||
|
||||
1. `19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda`
|
||||
2. `19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda`
|
||||
3. `19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda`
|
||||
4. `19.4. Globals and Lifecycle Lowering to IRBackend/IRVM Agenda`
|
||||
5. `19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda`
|
||||
|
||||
Cada agenda filha deve declarar explicitamente:
|
||||
|
||||
- que deriva da umbrella agenda `19`;
|
||||
- quais stages anteriores já são input fixo;
|
||||
- e quais outputs ela precisa entregar para a agenda seguinte.
|
||||
|
||||
## Boundary Locking Rules
|
||||
|
||||
Para evitar que discussões posteriores prejudiquem as anteriores, esta umbrella agenda fixa as seguintes regras de sequenciamento:
|
||||
|
||||
1. `19.2` não redefine surface syntax ou identidade de globals já fechadas em `19.1`.
|
||||
2. `19.3` não redefine o significado semântico de `[Init]`, `[Frame]` ou boot ordering já fechados em `19.2`.
|
||||
3. `19.4` não reabre decisões de linguagem ou de lifecycle; ela apenas escolhe a representação e o mecanismo de lowering compatíveis com elas.
|
||||
4. `19.5` não reabre arquitetura; ela consolida diagnostics, manifest propagation e coverage.
|
||||
5. Qualquer ponto que force reabertura de stage anterior deve voltar explicitamente para a agenda filha owner correta, em vez de ser resolvido informalmente na etapa posterior.
|
||||
|
||||
## Likely Propagation Targets
|
||||
|
||||
Mesmo sem virar `decision` ainda, esta agenda já mostra impacto provável nos seguintes artefatos.
|
||||
|
||||
### 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`
|
||||
|
||||
### Cross-Domain / VM Architecture
|
||||
|
||||
- `docs/vm-arch/ISA_CORE.md` provavelmente não precisa mudar em capability, mas precisa ser referenciado explicitamente como base de `GET_GLOBAL`/`SET_GLOBAL`;
|
||||
- specs gerais de lowering fora de `docs/compiler/pbs` podem precisar propagação posterior se `IRBackend` ganhar representação explícita de globals ou novo contrato para entrypoint published.
|
||||
|
||||
### Compiler / Implementation Areas
|
||||
|
||||
- parser e AST model;
|
||||
- linking/resolution;
|
||||
- static semantics;
|
||||
- IR model do frontend PBS;
|
||||
- executable lowering para `IRBackend` e `IRVM`;
|
||||
- montagem do manifest/cartridge metadata;
|
||||
- suites de fixture de frontend, lowering e toolchain.
|
||||
|
||||
## Boundary Risks
|
||||
|
||||
Se os boundaries acima não forem respeitados, os riscos mais prováveis são:
|
||||
|
||||
1. criar `declare global` como açúcar superficial sem lifecycle coerente;
|
||||
2. introduzir `[Init]` e `[Frame]` sem autoridade clara sobre `FrontendSpec`;
|
||||
3. mover `FRAME_RET` sem redefinir com precisão o owner do frame lógico;
|
||||
4. resolver globals intra-módulo mas deixar imports/reexports semanticamente ambíguos;
|
||||
5. fechar a solução do compiler sem fechar o contrato do manifest;
|
||||
6. misturar nesta agenda decisões de produto/runtime que deveriam continuar fora de escopo.
|
||||
|
||||
## Expected Spec Material
|
||||
|
||||
Se esta agenda virar `decision`, a propagação esperada deve atingir pelo menos:
|
||||
|
||||
- spec de declarações top-level do PBS para introduzir `declare global`;
|
||||
- spec de lifecycle/entrypoint attributes para `[Init]` e `[Frame]`;
|
||||
- spec de lowering executável/`IRBackend` para module init synthesis, wrapper published entrypoint e ownership de `FRAME_RET`;
|
||||
- spec de cartridge manifest para esclarecer a relação entre entrypoint lógico do usuário e entrypoint publicado no artefato;
|
||||
- diagnósticos de validação para unicidade, assinatura inválida, ciclos de init e uso incorreto de globals.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
Esta agenda não deve:
|
||||
|
||||
1. redesenhar o runtime ou introduzir novas instruções de VM;
|
||||
2. escrever a spec normativa final de globals e lifecycle;
|
||||
3. redefinir o modelo geral de módulos do compiler fora do necessário para globals/init;
|
||||
4. resolver todos os possíveis hooks futuros de programa além de `[Init]` e `[Frame]`;
|
||||
5. discutir otimizações de performance de init além do necessário para garantir semântica determinística.
|
||||
|
||||
## Next Step
|
||||
|
||||
Usar esta agenda como parent reference e abrir as agendas filhas na ordem abaixo:
|
||||
|
||||
1. `19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda`
|
||||
2. `19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda`
|
||||
3. `19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda`
|
||||
4. `19.4. Globals and Lifecycle Lowering to IRBackend/IRVM Agenda`
|
||||
5. `19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda`
|
||||
|
||||
Somente depois do fechamento dessas agendas derivadas esta linha deve virar uma `decision` consolidada em `docs/compiler/pbs/decisions`.
|
||||
-406
@@ -1,406 +0,0 @@
|
||||
# PBS Globals Surface, Identity, and Module Boundaries Agenda
|
||||
|
||||
## Status
|
||||
|
||||
Open
|
||||
|
||||
## Parent Agenda
|
||||
|
||||
This agenda derives from:
|
||||
|
||||
- `19. Globals, Synthetic Module Init, and FRAME_RET Agenda`
|
||||
|
||||
This is the first derived discussion under umbrella topic `19`.
|
||||
|
||||
## Purpose
|
||||
|
||||
Define the source-level and module-level model for PBS runtime globals before lifecycle, entrypoint publication, or lowering details are discussed.
|
||||
|
||||
This agenda exists to close the semantic base for:
|
||||
|
||||
- the `declare global` surface;
|
||||
- storage ownership;
|
||||
- import/export/alias behavior;
|
||||
- and dependency/cycle rules at module boundary level.
|
||||
|
||||
Later agendas under topic `19` must treat the outputs of this agenda as fixed input.
|
||||
|
||||
## Domain Owner
|
||||
|
||||
`docs/compiler/pbs`
|
||||
|
||||
Este tema pertence ao domínio PBS do compiler porque define surface language, linking semantics e boundaries de módulo para uma nova categoria de declaração top-level.
|
||||
|
||||
## Context
|
||||
|
||||
Hoje o PBS já possui `declare const`, mas esse surface é estritamente compile-time:
|
||||
|
||||
- `declare const` entra no value namespace;
|
||||
- `declare const` continua reservado a valores imutáveis que não representam storage mutável de módulo;
|
||||
- `declare const` não materializa storage mutável runtime;
|
||||
- o initializer de `declare const` pertence a um subset constante;
|
||||
- dependências de `declare const` são resolvidas por análise de dependência compile-time.
|
||||
|
||||
Ao mesmo tempo:
|
||||
|
||||
- a VM já expõe `GET_GLOBAL` e `SET_GLOBAL`;
|
||||
- a linguagem ainda não expõe globals mutáveis de módulo;
|
||||
- `mod.barrel` hoje já governa export/import de `const`, `fn`, tipos e outras famílias de declaração;
|
||||
- não existe ainda contrato explícito para storage compartilhado intermodular em source PBS.
|
||||
|
||||
Antes de discutir init, frame wrapper ou `FRAME_RET`, precisamos fechar o que um `global` é no modelo da linguagem.
|
||||
|
||||
## Inputs Already Fixed Elsewhere
|
||||
|
||||
Os seguintes inputs já parecem fixos e não devem ser reabertos aqui:
|
||||
|
||||
- `declare const` não é storage mutável/runtime-initialized;
|
||||
- `declare const` continua semanticamente separado de `declare global`;
|
||||
- `declare const` continua voltado a valores imutáveis e não deve ser reutilizado como surface de global;
|
||||
- modules e globals devem compartilhar o mesmo tipo estrutural de análise de dependência;
|
||||
- essa análise comum deve vir de um refactor do algoritmo atual de modules para um `DependencyGraphAnaliser` em `util.structures` na infra;
|
||||
- top-level executable statements continuam proibidos;
|
||||
- a VM já suporta globals por slot;
|
||||
- esta fase ainda é compiler-driven e não deve exigir capability nova do runtime;
|
||||
- barrel continua sendo a fonte de visibilidade entre módulos.
|
||||
|
||||
## Decisions To Produce
|
||||
|
||||
Esta agenda deve produzir direção suficiente para fechar:
|
||||
|
||||
1. a surface exata de `declare global`;
|
||||
2. a obrigatoriedade de initializer em todos os globals de v1;
|
||||
3. o namespace ocupado por globals;
|
||||
4. a política de visibility/barrel para globals;
|
||||
5. a identidade do storage owner;
|
||||
6. a semântica de import, export e alias;
|
||||
7. a política de dependência e ciclos entre globals.
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. PBS deve introduzir exatamente `declare global name: T = expr;` como nova forma top-level?
|
||||
2. `declare global` deve exigir type annotation explícita em todos os casos?
|
||||
3. Quais formas de initializer executável são admissíveis para `declare global` em v1?
|
||||
4. `declare global` entra no mesmo value namespace de `let` e `declare const`?
|
||||
5. O barrel deve ganhar uma entrada `global` distinta?
|
||||
6. Um `global` importado referencia sempre o storage do módulo owner original?
|
||||
7. Como imports de globals usam alias quando necessário sem introduzir shadowing?
|
||||
8. O que é proibido em imports de globals para evitar ambiguidade?
|
||||
9. A dependência entre globals deve ser modelada por grafo determinístico semelhante ao de `declare const`, mas agora com efeito runtime?
|
||||
10. Como ciclos entre globals intra-módulo e inter-módulo devem ser detectados e reportados?
|
||||
11. Como o grafo de globals mapeia para o `DependencyGraphAnaliser` comum sem perder owner canônico nem attribution?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A
|
||||
|
||||
Adicionar `declare global` como nova declaração top-level explícita, com type annotation obrigatória, initializer obrigatório em v1, entry própria `global` em barrel, sem reexport e identidade de storage sempre pertencente ao módulo owner original.
|
||||
|
||||
### Option B
|
||||
|
||||
Adicionar `declare global`, mas permitir globals sem initializer em v1 e tratar inicialização default como parte do modelo base.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
### Option A
|
||||
|
||||
- Prós:
|
||||
- semântica explícita e fácil de ensinar;
|
||||
- evita ambiguidade entre constant value e mutable storage;
|
||||
- força o barrel e os imports a refletirem corretamente a nova categoria declarativa;
|
||||
- reduz risco de globals parcialmente formados sem política clara de init.
|
||||
- Contras:
|
||||
- aumenta a superfície da linguagem;
|
||||
- exige atualização de parser, AST, linking e barrel matching.
|
||||
|
||||
### Option B
|
||||
|
||||
- Prós:
|
||||
- maior flexibilidade futura;
|
||||
- permite reservar globals antes de decidir a inicialização concreta.
|
||||
- Contras:
|
||||
- empurra complexidade para lifecycle e diagnostics;
|
||||
- enfraquece a previsibilidade de v1;
|
||||
- cria edge cases sobre leitura antes de materialização.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Seguir com a **Option A**.
|
||||
|
||||
Direção recomendada:
|
||||
|
||||
1. `declare global` deve ser uma declaração top-level distinta de `declare const`;
|
||||
2. type annotation explícita deve ser obrigatória;
|
||||
3. initializer deve ser obrigatório em v1;
|
||||
4. `declare const` não deve ser reutilizado para globals e continua reservado a valores imutáveis;
|
||||
5. globals devem entrar no value namespace, mas com categoria declarativa distinta;
|
||||
6. barrel deve refletir essa distinção explicitamente com `mod global` e `pub global`;
|
||||
7. PBS não deve introduzir reexport de globals nesta linha;
|
||||
8. imports de globals devem preservar a identidade do storage owner original e usar alias quando necessário;
|
||||
9. shadowing entre imports de `fn`, `service`, `global` e `const` deve ser compile-time error;
|
||||
10. dependências entre globals devem ser determinísticas e diagnosticáveis.
|
||||
|
||||
Também fica registrado nesta agenda um direction técnico já decidido:
|
||||
|
||||
1. modules e globals usarão o mesmo tipo estrutural de análise de dependência;
|
||||
2. isso deve nascer de um refactor do algoritmo atual de modules;
|
||||
3. o artefato comum deve viver na infra como `DependencyGraphAnaliser` em `util.structures`;
|
||||
4. cada domínio continua responsável por construir seus próprios nós canônicos, suas arestas e seu mapeamento de diagnóstico;
|
||||
5. o que é compartilhado é o kernel estrutural de ordenação topológica e detecção de ciclos, não a semântica específica de cada grafo.
|
||||
|
||||
## Global Dependencies
|
||||
|
||||
O ponto mais sensível desta agenda é a dependência entre globals.
|
||||
|
||||
Com `declare const`, dependência significa apenas ordem de avaliação compile-time.
|
||||
Com `declare global`, dependência passa a significar ordem de materialização runtime, identidade de storage e risco real de efeito parcial.
|
||||
|
||||
Exemplos do tipo de dependência que passam a existir:
|
||||
|
||||
```pbs
|
||||
declare global a: int = 1;
|
||||
declare global b: int = a + 1;
|
||||
```
|
||||
|
||||
Aqui `b` depende de `a` porque o initializer de `b` lê o valor de `a`.
|
||||
|
||||
```pbs
|
||||
declare global origin: Vec2 = new Vec2(0, 0);
|
||||
declare global camera: Camera = new Camera(origin);
|
||||
```
|
||||
|
||||
Aqui `camera` depende de `origin` porque o initializer usa o valor já materializado de outro global.
|
||||
|
||||
Quando há múltiplos módulos, o problema cresce:
|
||||
|
||||
```pbs
|
||||
// module A
|
||||
declare global seed: int = 7;
|
||||
|
||||
// module B
|
||||
import { seed } from @project:A;
|
||||
declare global rng: Rng = new Rng(seed);
|
||||
```
|
||||
|
||||
Agora a ordem de materialização não é apenas intra-módulo. Ela atravessa módulos e precisa continuar determinística.
|
||||
|
||||
### Dependency Kinds
|
||||
|
||||
Esta agenda precisa distinguir pelo menos três formas de dependência:
|
||||
|
||||
1. dependência local entre globals do mesmo módulo;
|
||||
2. dependência intermodular por import de global do módulo owner original;
|
||||
3. dependência indireta por alias de import, onde o nome local muda, mas o owner do storage permanece igual.
|
||||
|
||||
### Main Problems
|
||||
|
||||
Os principais problemas de dependência de globals são:
|
||||
|
||||
1. ordem de inicialização deixa de poder depender de ordem textual do arquivo;
|
||||
2. imports com alias podem esconder o owner real do storage;
|
||||
3. leitura de global ainda não materializado precisa ser proibida por modelo, não tratada como comportamento oportunista;
|
||||
4. ciclos deixam de ser apenas "ciclos de expressão" e passam a ser ciclos de materialização runtime;
|
||||
5. o grafo de dependências pode cruzar múltiplos módulos e aliases, o que piora atribuição de diagnóstico.
|
||||
|
||||
### Risks
|
||||
|
||||
Se a política de dependência de globals ficar frouxa, os riscos são altos:
|
||||
|
||||
1. inicialização parcialmente observável:
|
||||
um global pode ler outro antes de ele existir semanticamente;
|
||||
2. ordem acidental por arquivo:
|
||||
a implementação pode acabar usando ordem textual ou ordem de carregamento do projeto, o que quebra determinismo;
|
||||
3. aliasing ambíguo:
|
||||
aliases de import podem parecer símbolo novo quando na verdade são só outro nome para o mesmo owner;
|
||||
4. ciclos opacos:
|
||||
`A -> B -> C -> A` pode ficar escondido atrás de import e alias, dificultando explicação ao usuário;
|
||||
5. bootstrap contaminado:
|
||||
se essa agenda deixar dependência frouxa, a 19.2 herda um lifecycle impossível de explicar;
|
||||
6. lowering prematuro:
|
||||
se o compiler materializar a ordem no backend sem política semântica firme, a arquitetura congela cedo demais.
|
||||
|
||||
### Direction for Discussion
|
||||
|
||||
Minha direção recomendada para dependências de globals nesta agenda é:
|
||||
|
||||
1. toda leitura de outro global no initializer cria uma edge explícita no grafo de dependência;
|
||||
2. a resolução do grafo deve ser determinística e independente de source-file order;
|
||||
3. imports e aliases devem preservar o owner original do storage no grafo;
|
||||
4. ciclos entre globals devem ser erro estático, não comportamento runtime com retry ou valor parcial;
|
||||
5. a agenda deve deixar claro que esta política fecha apenas identidade e dependência;
|
||||
boot ordering completo continua pertencendo à `19.2`.
|
||||
|
||||
### Structural Reuse Decision
|
||||
|
||||
Esta agenda também registra uma decisão arquitetural de implementação que afeta a evolução futura:
|
||||
|
||||
1. o algoritmo atual usado para dependência de modules deve ser refatorado em um componente estrutural reutilizável;
|
||||
2. esse componente comum deve se chamar `DependencyGraphAnaliser`;
|
||||
3. ele deve viver em `util.structures` na infra;
|
||||
4. modules e globals devem consumir esse mesmo componente estrutural;
|
||||
5. a semântica que descobre edges continua separada por domínio.
|
||||
|
||||
Isso significa:
|
||||
|
||||
- o import graph de modules e o init graph de globals não serão o mesmo grafo semântico;
|
||||
- mas ambos deverão usar o mesmo kernel estrutural para:
|
||||
- topological ordering,
|
||||
- cycle detection,
|
||||
- e suporte a diagnóstico determinístico.
|
||||
|
||||
## Current Direction
|
||||
|
||||
Os pontos abaixo já podem ser tratados como direção fechada desta agenda, salvo objeção nova forte:
|
||||
|
||||
1. a surface correta é `declare global BLA: int = 1;`;
|
||||
2. type annotation é obrigatória, como em `declare const`;
|
||||
3. initializer é sempre obrigatório;
|
||||
4. globals entram no value namespace como categoria declarativa distinta;
|
||||
5. `mod.barrel` deve expor globals com entradas `mod global Name;` e `pub global Name;`;
|
||||
6. imports de globals usam o mesmo esquema de alias quando necessário;
|
||||
7. PBS não introduz reexport de globals nesta linha;
|
||||
8. shadowing entre imports de `fn`, `service`, `global` e `const` é compile-time error e deve ser resolvido com alias;
|
||||
9. detecção de dependência, ordenação e ciclo deve nascer do `DependencyGraphAnaliser` comum, com contexto semântico próprio de globals.
|
||||
|
||||
Também fica explicitado o modelo de namespace:
|
||||
|
||||
1. globals entram no value namespace;
|
||||
2. `declare const`, `declare global` e o singleton canônico de `service` convivem no espaço nominal de valores;
|
||||
3. `fn`, `service`, `global` e `const` não podem introduzir o mesmo nome visível no mesmo scope de resolução;
|
||||
4. essa colisão é erro de compile time, mesmo quando a ambiguidade nasce de import;
|
||||
5. `locals > struct/class members > globals`, inclusive quando o global veio por import.
|
||||
|
||||
## Remaining Open Points
|
||||
|
||||
Com a direção já consolidada nesta agenda, não restam pontos substantivos em aberto dentro do boundary de `19.1`.
|
||||
|
||||
Os temas adicionais de lifecycle seguem encaminhados para a `19.2`.
|
||||
|
||||
## Initializer Boundary
|
||||
|
||||
Esta agenda também precisa deixar explícita a fronteira entre:
|
||||
|
||||
1. init da declaração `global`;
|
||||
2. init por módulo;
|
||||
3. init de projeto.
|
||||
|
||||
Direção recomendada:
|
||||
|
||||
- o initializer de `declare global` deve permanecer restrito e simples;
|
||||
- ele existe para materializar o valor inicial da storage de módulo;
|
||||
- ele não deve carregar lógica procedural maior nem depender de top-level `fn`;
|
||||
- lógica adicional de setup pertence ao init por módulo;
|
||||
- setup de programa pertence ao init de projeto.
|
||||
|
||||
Com isso, a linha proposta fica:
|
||||
|
||||
1. init da global:
|
||||
permite primitivas, operações simples com valor, member access com valor nessa etapa, `new`, e leitura de outras globals compatíveis com o dep graph;
|
||||
2. init do módulo:
|
||||
permite lógica adicional de conveniência e mutações nas globals do próprio módulo após a materialização inicial;
|
||||
3. init do projeto:
|
||||
permite setup do projeto como um todo, depois do fechamento do estado de módulo necessário.
|
||||
|
||||
### Consequence for `fn` in Global Initializers
|
||||
|
||||
Seguindo essa separação, esta agenda recomenda que:
|
||||
|
||||
1. calls para top-level `fn` não sejam permitidas em initializer de `global` em v1;
|
||||
2. a necessidade de lógica mais rica seja absorvida pelo init de módulo discutido na `19.2`;
|
||||
3. isso mantenha o dep graph de globals focado em materialização declarativa, não em execução procedural arbitrária.
|
||||
|
||||
Também fica recomendado que, em v1:
|
||||
|
||||
1. `some(...)` e `none` não façam parte do initializer declarativo de `global`;
|
||||
2. `if` e `switch` não sejam permitidos diretamente na declaração de `global`.
|
||||
|
||||
## Diagnostics Recommendation
|
||||
|
||||
Esta agenda fecha o seguinte catálogo pequeno, forte e didático de diagnósticos obrigatórios.
|
||||
|
||||
### 1. Invalid Global Initializer
|
||||
|
||||
Quando o initializer usar uma forma não admissível em v1, o compiler deve emitir um erro apontando a subexpressão inválida.
|
||||
|
||||
Mensagem semântica recomendada:
|
||||
|
||||
- `global initializer uses unsupported form`
|
||||
|
||||
Exemplos de motivo associado:
|
||||
|
||||
- top-level `fn` call not allowed in global initializer;
|
||||
- `some(...)` not allowed in global initializer;
|
||||
- `if` not allowed in global initializer.
|
||||
|
||||
### 2. Global Dependency Cycle
|
||||
|
||||
Quando houver ciclo, o compiler deve diagnosticar o global owner local e, quando possível, renderizar o caminho canônico do ciclo.
|
||||
|
||||
Mensagem semântica recomendada:
|
||||
|
||||
- `global dependency cycle detected`
|
||||
|
||||
Detalhe recomendado:
|
||||
|
||||
- incluir o símbolo local que participa do ciclo;
|
||||
- incluir o caminho canônico quando disponível, por exemplo:
|
||||
`@project:A.seed -> @project:B.rng -> @project:C.config -> @project:A.seed`
|
||||
|
||||
### 3. Shadowing Requires Alias
|
||||
|
||||
Quando um import introduzir nome que colide com `fn`, `service`, `global` ou `const` já visível, o compiler deve rejeitar e exigir alias explícito.
|
||||
|
||||
Mensagem semântica recomendada:
|
||||
|
||||
- `imported symbol shadows existing visible symbol; alias required`
|
||||
|
||||
### 4. Global Import Category Mismatch
|
||||
|
||||
Se o barrel e a importação não preservarem corretamente a categoria declarativa `global`, o compiler deve rejeitar explicitamente em vez de tentar degradar para `const` ou valor genérico.
|
||||
|
||||
Mensagem semântica recomendada:
|
||||
|
||||
- `global import must resolve through a global barrel entry`
|
||||
|
||||
Essa escolha existe para preservar:
|
||||
|
||||
- clareza semântica;
|
||||
- diagnósticos mais simples;
|
||||
- e uma separação limpa entre storage initialization e lifecycle hooks.
|
||||
|
||||
## Forwarded To 19.2
|
||||
|
||||
Os seguintes temas surgiram desta agenda, mas pertencem ao boundary de lifecycle e devem ser tratados na `19.2`:
|
||||
|
||||
1. init por módulo como fase procedural separada do initializer declarativo de `global`;
|
||||
2. init de projeto como fase distinta de coordenação final;
|
||||
3. permissão de loops em init de módulo e init de projeto;
|
||||
4. proibição de host calls por padrão durante init;
|
||||
5. permissão apenas para host calls marcadas com atributo reservado `[InitAllowed]`;
|
||||
6. validação compile-time dessa admissibilidade;
|
||||
7. separação entre restrição normativa de host interaction e recomendação de design para manter bootstrap leve.
|
||||
|
||||
## Expected Spec Material
|
||||
|
||||
Se esta agenda fechar, a propagação esperada atinge pelo menos:
|
||||
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `11. AST Specification.md`
|
||||
- `12. Diagnostics Specification.md`
|
||||
|
||||
## Non-Goals
|
||||
|
||||
Esta agenda não deve:
|
||||
|
||||
1. definir boot ordering;
|
||||
2. definir `[Init]` ou `[Frame]`;
|
||||
3. definir wrapper published entrypoint;
|
||||
4. definir posicionamento de `FRAME_RET`;
|
||||
5. escolher a representação de IR/bytecode para globals.
|
||||
|
||||
## Next Step
|
||||
|
||||
Depois de fechar esta agenda, abrir ou aprofundar:
|
||||
|
||||
- `19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda`
|
||||
-361
@@ -1,361 +0,0 @@
|
||||
# PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda
|
||||
|
||||
## Status
|
||||
|
||||
Open
|
||||
|
||||
## Parent Agenda
|
||||
|
||||
This agenda derives from:
|
||||
|
||||
- `19. Globals, Synthetic Module Init, and FRAME_RET Agenda`
|
||||
|
||||
Expected fixed input from previous stage:
|
||||
|
||||
- `19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda`
|
||||
|
||||
## Purpose
|
||||
|
||||
Define the observable lifecycle model of PBS once runtime globals exist.
|
||||
|
||||
This agenda must close:
|
||||
|
||||
- whether `[Init]` and `[Frame]` become official source markers;
|
||||
- the relationship between module init and program init;
|
||||
- boot one-shot behavior;
|
||||
- failure policy;
|
||||
- and the semantic role of the user's frame root.
|
||||
|
||||
## Domain Owner
|
||||
|
||||
`docs/compiler/pbs`
|
||||
|
||||
Este tema pertence ao domínio PBS porque define lifecycle observável da linguagem, não apenas mecanismo de backend.
|
||||
|
||||
## Context
|
||||
|
||||
Depois que `declare global` existir como storage runtime de módulo, o compiler precisará definir:
|
||||
|
||||
- quando os globals são materializados;
|
||||
- em que ordem isso acontece;
|
||||
- se existe um hook explícito de init de programa;
|
||||
- se existe um init procedural por módulo separado do initializer declarativo de `global`;
|
||||
- como a linguagem identifica o frame root do usuário;
|
||||
- e o que acontece quando o boot falha.
|
||||
|
||||
Esta agenda ainda não decide a forma exata do wrapper published entrypoint nem o shape do IR. Ela define primeiro o comportamento observável que essas camadas posteriores terão de respeitar.
|
||||
|
||||
## Inputs Already Fixed Elsewhere
|
||||
|
||||
Os seguintes inputs devem ser tratados como fechados ou fortemente estáveis aqui:
|
||||
|
||||
- o modelo base de globals vindo de `19.1`;
|
||||
- o initializer declarativo de `global` permanece restrito a primitivas, `new` e leitura de outras globals compatíveis com o dep graph;
|
||||
- top-level `fn` não são permitidas em initializer de `global` em v1;
|
||||
- `FRAME_SYNC` permanece como safepoint normativo;
|
||||
- PBS v1 continua determinístico e single-threaded;
|
||||
- esta fase continua evitando mudanças novas no runtime.
|
||||
|
||||
## Decisions To Produce
|
||||
|
||||
Esta agenda deve produzir direção suficiente para fechar:
|
||||
|
||||
1. se `[Init]` e `[Frame]` entram na surface oficial;
|
||||
2. targets válidos, unicidade e assinaturas exigidas;
|
||||
3. ordem entre module init, init de programa e frame;
|
||||
4. política de boot one-shot;
|
||||
5. política de falha;
|
||||
6. papel semântico de `frame()` do usuário;
|
||||
7. política de loops e host calls admissíveis durante init.
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. PBS deve introduzir `[Init]` e `[Frame]` como atributos reservados?
|
||||
2. `[Init]` deve ser permitido tanto por módulo quanto no init final de projeto?
|
||||
3. `[Frame]` deve existir exatamente uma vez por programa?
|
||||
4. `[Init]` deve existir no máximo uma vez por programa?
|
||||
5. `[Init]` e `[Frame]` devem exigir assinatura fixa `fn ...() -> void`?
|
||||
6. Todos os module inits devem rodar antes do `[Init]` do usuário?
|
||||
7. A ausência de `[Init]` deve ser válida?
|
||||
8. A ausência de `[Frame]` deve ser erro hard para programa executável?
|
||||
9. Em caso de falha durante module init ou `[Init]`, o programa deve falhar definitivamente ou pode haver retry?
|
||||
10. Qual é a definição semântica correta de `frame()` do usuário: root lógico do tick, callable publicado, ou apenas callable invocado por infraestrutura sintética futura?
|
||||
11. Loops devem ser permitidos em init de módulo e init de projeto?
|
||||
12. Host calls devem ser proibidas por padrão durante init?
|
||||
13. Apenas host calls marcadas com `[InitAllowed]` devem ser admissíveis durante init?
|
||||
14. Como a admissibilidade de `[InitAllowed]` é validada em compile time?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A
|
||||
|
||||
Introduzir `[Init]` e `[Frame]` como markers reservados explícitos, com assinaturas fixas, `[Init]` opcional por módulo e por projeto, `[Frame]` obrigatório e único por projeto executável, permitindo init procedural por módulo e mantendo política restritiva de host interaction durante init.
|
||||
|
||||
### Option B
|
||||
|
||||
Introduzir apenas `[Frame]` e manter init inteiramente sintético, sem hook de programa do usuário nesta fase.
|
||||
|
||||
### Option C
|
||||
|
||||
Manter lifecycle implícito, sem markers source-level, e continuar derivando entrypoint/configuração fora da linguagem.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
### Option A
|
||||
|
||||
- Prós:
|
||||
- deixa lifecycle explícito na linguagem;
|
||||
- reduz dependência de configuração paralela;
|
||||
- dá base clara para wrapper, manifest e lowering posteriores.
|
||||
- Contras:
|
||||
- amplia a surface de atributos reservados;
|
||||
- exige validação de target, unicidade e assinatura.
|
||||
|
||||
### Option B
|
||||
|
||||
- Prós:
|
||||
- escopo menor;
|
||||
- adia parte da discussão de init.
|
||||
- Contras:
|
||||
- resolve só metade do lifecycle;
|
||||
- pode forçar redesign quando o hook de init do usuário voltar.
|
||||
|
||||
### Option C
|
||||
|
||||
- Prós:
|
||||
- menor custo imediato.
|
||||
- Contras:
|
||||
- mantém a autoridade do lifecycle fora da linguagem;
|
||||
- enfraquece a coerência da série 19.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Seguir com a **Option A**.
|
||||
|
||||
Direção recomendada:
|
||||
|
||||
1. `[Init]` e `[Frame]` devem ser markers reservados explícitos;
|
||||
2. `declare global` sempre lowera para o init sintético do módulo owner;
|
||||
3. `[Init]` de módulo deve ser opcional e executar depois de todos os `declare global` do módulo;
|
||||
4. o init de projeto deve seguir o mesmo modelo, mas associado ao projeto que contém o `[Frame]`;
|
||||
5. `[Init]` de projeto deve ser opcional;
|
||||
6. `[Frame]` deve ser obrigatório para programa executável e único por projeto;
|
||||
7. `[Init]` e `[Frame]` devem exigir assinatura fixa `fn name() -> void`;
|
||||
8. boot deve ser one-shot;
|
||||
9. falha de boot deve seguir direção fail-fast, salvo argumento forte em contrário;
|
||||
10. loops devem ser permitidos em init de módulo e init de projeto;
|
||||
11. host calls devem ser proibidas por padrão durante init;
|
||||
12. apenas host calls com atributo reservado `[InitAllowed]` devem ser admissíveis durante init;
|
||||
13. `[InitAllowed]` é atributo reservado de SDK, não userland.
|
||||
|
||||
## Additional Lifecycle Concerns
|
||||
|
||||
Esta agenda também precisa fechar a separação entre três camadas de bootstrap:
|
||||
|
||||
1. initializer declarativo de `global`;
|
||||
2. init por módulo;
|
||||
3. init de projeto.
|
||||
|
||||
Direção herdada da `19.1`:
|
||||
|
||||
- `global` materializa storage inicial;
|
||||
- init de módulo executa lógica procedural de conveniência sobre globals do próprio módulo;
|
||||
- init de projeto executa coordenação final do programa.
|
||||
|
||||
Com esse modelo:
|
||||
|
||||
- loops são legítimos em init de módulo e init de projeto, especialmente para carga e preparação de arrays e estruturas derivadas;
|
||||
- a restrição normativa mais forte deve cair sobre host interaction;
|
||||
- "bootstrap leve" continua sendo recomendação de design, não um limite impossível de verificar semanticamente.
|
||||
|
||||
## Current Direction
|
||||
|
||||
Os pontos abaixo já podem ser tratados como direção fechada desta agenda, salvo objeção nova forte:
|
||||
|
||||
1. `[Init]` e `[Frame]` entram como atributos reservados explícitos;
|
||||
2. `declare global X: T = expr;` lowera sempre para o init sintético do módulo owner;
|
||||
3. cada arquivo pode declarar opcionalmente um `[Init]` procedural próprio;
|
||||
4. o `[Init]` de cada arquivo roda sempre depois das globals daquele arquivo e participa do init sintético do módulo;
|
||||
5. existe também um init de projeto opcional, que é o `[Init]` associado ao projeto que contém o `[Frame]`;
|
||||
6. `[Frame]` é obrigatório e único por projeto executável;
|
||||
7. `[Init]` e `[Frame]` seguem a forma recomendada:
|
||||
|
||||
```pbs
|
||||
[Init]
|
||||
fn init() -> void { ... }
|
||||
```
|
||||
|
||||
```pbs
|
||||
[Frame]
|
||||
fn frame() -> void { ... }
|
||||
```
|
||||
|
||||
8. a assinatura exigida é sempre `fn name() -> void`;
|
||||
9. loops são permitidos nos inits;
|
||||
10. host calls são proibidas por padrão durante init;
|
||||
11. apenas host calls com `[InitAllowed]` podem ser usadas durante init;
|
||||
12. `[InitAllowed]` pertence às superfícies reservadas de SDK, não a userland;
|
||||
13. falha de boot é fail-fast com mensagem coerente.
|
||||
|
||||
Também fica fechada a seguinte regra operacional:
|
||||
|
||||
14. o `[Init]` que estiver no mesmo arquivo que o `[Frame]` é o init de projeto;
|
||||
15. `[Init]` em outros arquivos continuam sendo init de módulo;
|
||||
16. `[Frame]` e o init de projeto devem ser co-localizados no mesmo arquivo por decisão deliberada de source organization.
|
||||
17. cada arquivo pode declarar no máximo um `[Init]`;
|
||||
18. cada módulo possui exatamente um init sintético de módulo, dentro do qual os inits por arquivo são ordenados e compostos;
|
||||
19. a distinção entre init de módulo e init de projeto é apenas de ordenação e papel semântico, não de surface diferente;
|
||||
20. como consequência, existe no máximo um `[Init]` de projeto por projeto executável.
|
||||
21. arquivos sem globals podem declarar um `[Init]`, desde que continuem respeitando a regra de no máximo um `[Init]` por arquivo;
|
||||
22. o `project init` segue exatamente a mesma assinatura `fn init() -> void`.
|
||||
|
||||
## Lifecycle Order Direction
|
||||
|
||||
Esta agenda também já aponta para a seguinte ordem lógica de bootstrap:
|
||||
|
||||
1. materialização das globals de cada arquivo do módulo conforme a ordem determinada pelo dependency graph;
|
||||
2. execução do `[Init]` daquele arquivo, quando existir;
|
||||
3. composição desses passos em um único init sintético do módulo;
|
||||
4. depois do fechamento dos módulos necessários, execução do `[Init]` de projeto, quando existir;
|
||||
5. entrada no primeiro `frame()`.
|
||||
|
||||
Lendo essa ordem de forma operacional:
|
||||
|
||||
1. cada arquivo inicializa suas próprias globals;
|
||||
2. cada arquivo pode então executar seu `[Init]` opcional;
|
||||
3. tudo isso se aninha dentro de um único init sintético por módulo;
|
||||
4. o `[Init]` co-localizado com `[Frame]` é elevado a init de projeto por ordem e papel semântico.
|
||||
|
||||
Também fica fechada a seguinte direção adicional:
|
||||
|
||||
5. a ordem entre arquivos do mesmo módulo deve seguir a ordem derivada do `DependencyGraphAnaliser` das globals;
|
||||
6. quando dois arquivos não tiverem dependência entre si, o compiler deve usar uma ordem determinística estável.
|
||||
|
||||
## Remaining Open Points
|
||||
|
||||
Com a direção já consolidada nesta agenda, não restam pontos substantivos em aberto dentro do boundary de `19.2`.
|
||||
|
||||
Os temas seguintes agora pertencem à `19.3`.
|
||||
|
||||
## InitAllowed Direction
|
||||
|
||||
Esta agenda fecha também o seguinte shape normativo inicial para `[InitAllowed]`:
|
||||
|
||||
1. `[InitAllowed]` é um atributo reservado sem argumentos em v1;
|
||||
2. ele é válido apenas em host methods de SDK;
|
||||
3. ele é inválido em userland;
|
||||
4. ele é inválido em `fn`, `global`, `service` e demais superfícies que não sejam host methods de SDK;
|
||||
5. seu papel é exclusivamente validar, em compile time, quais host calls podem aparecer durante init;
|
||||
6. ele não faz distinção entre init de módulo e init de projeto;
|
||||
7. a diferença entre esses inits é de ordenação e papel semântico, não de permissão separada de host call.
|
||||
|
||||
Exemplo recomendado:
|
||||
|
||||
```pbs
|
||||
declare host Runtime {
|
||||
[Host(module = "runtime", name = "random_u32", version = 1)]
|
||||
[Capability(name = "runtime")]
|
||||
[InitAllowed]
|
||||
fn random_u32() -> int;
|
||||
}
|
||||
```
|
||||
|
||||
## Diagnostics Recommendation
|
||||
|
||||
Esta agenda fecha o seguinte catálogo mínimo de diagnósticos de lifecycle e bootstrap.
|
||||
|
||||
### 1. Project Init Must Be Colocated With Frame
|
||||
|
||||
Mensagem semântica recomendada:
|
||||
|
||||
- `project init must be colocated with frame`
|
||||
|
||||
### 2. Multiple Project Init Functions Detected
|
||||
|
||||
Mensagem semântica recomendada:
|
||||
|
||||
- `multiple project init functions detected`
|
||||
|
||||
### 3. Multiple Frame Functions Detected
|
||||
|
||||
Mensagem semântica recomendada:
|
||||
|
||||
- `multiple frame functions detected`
|
||||
|
||||
### 4. Missing Frame Function For Executable Project
|
||||
|
||||
Mensagem semântica recomendada:
|
||||
|
||||
- `missing frame function for executable project`
|
||||
|
||||
### 5. Invalid Init Signature
|
||||
|
||||
Mensagem semântica recomendada:
|
||||
|
||||
- `init function must have signature fn name() -> void`
|
||||
|
||||
### 6. Invalid Frame Signature
|
||||
|
||||
Mensagem semântica recomendada:
|
||||
|
||||
- `frame function must have signature fn name() -> void`
|
||||
|
||||
### 7. Host Call Not Allowed During Init
|
||||
|
||||
Mensagem semântica recomendada:
|
||||
|
||||
- `host call not allowed during init`
|
||||
|
||||
### 8. Invalid InitAllowed Target
|
||||
|
||||
Mensagem semântica recomendada:
|
||||
|
||||
- `InitAllowed is valid only on SDK host methods`
|
||||
|
||||
### 9. Boot Failed During Module Init
|
||||
|
||||
Mensagem semântica recomendada:
|
||||
|
||||
- `boot failed during module init`
|
||||
|
||||
### 10. Boot Failed During Project Init
|
||||
|
||||
Mensagem semântica recomendada:
|
||||
|
||||
- `boot failed during project init`
|
||||
|
||||
### 11. Multiple Module Init Functions Detected
|
||||
|
||||
Mensagem semântica recomendada:
|
||||
|
||||
- `multiple module init functions detected`
|
||||
|
||||
### 12. Init Attribute Target Invalid
|
||||
|
||||
Mensagem semântica recomendada:
|
||||
|
||||
- `Init attribute target invalid`
|
||||
|
||||
## Expected Spec Material
|
||||
|
||||
Se esta agenda fechar, a propagação esperada atinge pelo menos:
|
||||
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `9. Dynamic Semantics Specification.md`
|
||||
- `12. Diagnostics Specification.md`
|
||||
|
||||
## Non-Goals
|
||||
|
||||
Esta agenda não deve:
|
||||
|
||||
1. decidir o nome físico do wrapper published entrypoint;
|
||||
2. decidir o nome físico do entrypoint no manifest;
|
||||
3. definir shape de IR;
|
||||
4. definir como `FRAME_RET` será reposicionado materialmente.
|
||||
|
||||
## Next Step
|
||||
|
||||
Depois de fechar esta agenda, abrir ou aprofundar:
|
||||
|
||||
- `19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda`
|
||||
-203
@@ -1,203 +0,0 @@
|
||||
# Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda
|
||||
|
||||
## Status
|
||||
|
||||
Open
|
||||
|
||||
## 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`
|
||||
|
||||
## Purpose
|
||||
|
||||
Define how PBS lifecycle is published into the executable artifact once globals and lifecycle semantics are already fixed.
|
||||
|
||||
This agenda must close:
|
||||
|
||||
- whether the published entrypoint becomes a synthetic wrapper;
|
||||
- the semantic and publication relationship between user `frame()` and the published entrypoint;
|
||||
- the new owner of `FRAME_RET`;
|
||||
- and the contract boundary between source-derived entrypoint discovery, `FrontendSpec`, and cartridge manifest publication.
|
||||
|
||||
## Domain Owner
|
||||
|
||||
`docs/compiler/pbs`
|
||||
|
||||
Este tema pertence ao domínio PBS porque decide a fronteira entre semântica da linguagem, entrypoint publicado e artefato executável.
|
||||
|
||||
## Context
|
||||
|
||||
Se `frame()` do usuário deixar de ser o callable publicado diretamente, o compiler precisará publicar outro root executável.
|
||||
|
||||
Isso abre quatro perguntas acopladas:
|
||||
|
||||
- quem é o entrypoint físico do artefato;
|
||||
- qual callable continua sendo o root lógico do código do usuário;
|
||||
- onde `FRAME_RET` passa a ser emitido;
|
||||
- e como manifest e `FrontendSpec` representam isso sem ambiguidade.
|
||||
|
||||
Esta agenda existe para fechar esse contrato antes de discutir detalhe de representação de IR.
|
||||
|
||||
## Inputs Already Fixed Elsewhere
|
||||
|
||||
Os seguintes inputs devem ser tratados como fixos aqui:
|
||||
|
||||
- o modelo de globals vindo de `19.1`;
|
||||
- o modelo de lifecycle e markers vindo de `19.2`;
|
||||
- `FRAME_RET` continua significando fim do frame lógico;
|
||||
- o runtime continua esperando um entrypoint published por frame.
|
||||
|
||||
## Decisions To Produce
|
||||
|
||||
Esta agenda deve produzir direção suficiente para fechar:
|
||||
|
||||
1. se o published entrypoint é um wrapper sintético;
|
||||
2. qual é a relação entre `frame()` do usuário e esse wrapper;
|
||||
3. onde `FRAME_RET` passa a viver;
|
||||
4. como a autoridade de entrypoint sai de `FrontendSpec` e passa ao compiler PBS;
|
||||
5. como o protocolo de runtime/manifest representa esse entrypoint.
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. O compiler deve publicar um wrapper sintético como entrypoint real?
|
||||
2. `frame()` do usuário deixa de ser o callable publicado e passa a ser apenas root lógico interno?
|
||||
3. `FRAME_RET` deve ser emitido no wrapper, não mais no callable do usuário?
|
||||
4. O compiler PBS deve se tornar a única autoridade para definir o entrypoint publicado?
|
||||
5. O wrapper sintético deve ocupar protocolarmente o entrypoint físico `0`?
|
||||
6. O campo `entrypoint` deve deixar de existir no `manifest.json` como estado alvo do protocolo?
|
||||
7. Existe algum caso em que o wrapper não seja necessário depois de `19.2`?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A
|
||||
|
||||
Publicar um wrapper sintético como entrypoint físico, tratar `frame()` do usuário como root lógico interno, mover `FRAME_RET` para o wrapper, tornar o compiler PBS a autoridade exclusiva de entrypoint e fixar protocolarmente o entrypoint físico em `0`.
|
||||
|
||||
### Option B
|
||||
|
||||
Manter `frame()` do usuário como entrypoint publicado e tentar acoplar boot/lifecycle diretamente nele.
|
||||
|
||||
### Option C
|
||||
|
||||
Publicar wrapper sintético, mas manter `entrypoint` no manifest como autoridade nominal paralela.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
### Option A
|
||||
|
||||
- Prós:
|
||||
- separa lifecycle publicado do callable do usuário;
|
||||
- acomoda boot one-shot de forma limpa;
|
||||
- preserva o significado de `FRAME_RET` com owner mais correto.
|
||||
- alinha melhor o protocolo físico do artefato com a política já existente de `func_id = 0` como entrypoint;
|
||||
- remove autoridade duplicada entre compiler, manifest e `FrontendSpec`.
|
||||
- Contras:
|
||||
- exige trabalho claro de migração em manifest, runtime e `FrontendSpec`;
|
||||
- torna a relação lógico/físico explicitamente dupla.
|
||||
|
||||
### Option B
|
||||
|
||||
- Prós:
|
||||
- preserva a superfície atual de publicação.
|
||||
- Contras:
|
||||
- mistura responsabilidades demais no callable do usuário;
|
||||
- enfraquece a clareza do lifecycle.
|
||||
|
||||
### Option C
|
||||
|
||||
- Prós:
|
||||
- parece reduzir custo de transição imediata.
|
||||
- Contras:
|
||||
- mantém duas autoridades para entrypoint;
|
||||
- cria dívida documental e de runtime desnecessária;
|
||||
- enfraquece a ideia de entrypoint como protocolo fixo do artefato.
|
||||
|
||||
## 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. o compiler deve publicar um wrapper sintético como entrypoint físico real;
|
||||
2. esse wrapper deve conter:
|
||||
- boot one-shot,
|
||||
- os inits necessários apenas uma vez,
|
||||
- a chamada ao `frame()` do usuário,
|
||||
- e o `FRAME_RET` final;
|
||||
3. `frame()` anotado com `[Frame]` permanece como root lógico do usuário;
|
||||
4. o wrapper sintético é o root físico publicado;
|
||||
5. `FRAME_RET` sai do final do `frame()` do usuário e passa a existir no wrapper;
|
||||
6. `FrontendSpec` perde autoridade para referenciar quem é o entrypoint;
|
||||
7. a autoridade de entrypoint fica outorgada exclusivamente ao compiler PBS;
|
||||
8. o wrapper sintético deve ser compilado no entrypoint físico `0`;
|
||||
9. o estado alvo do protocolo deve remover `entrypoint` do `manifest.json`;
|
||||
10. o runtime/loader deve tratar o entrypoint como protocolo fixo do artefato, não como metadado nominal configurável no manifest.
|
||||
|
||||
## Manifest and Runtime Direction
|
||||
|
||||
Esta agenda também já aponta para a seguinte direção de contrato:
|
||||
|
||||
1. o campo `entrypoint` deve deixar de existir no `manifest.json` como estado final do protocolo;
|
||||
2. o runtime deve assumir protocolarmente o entrypoint físico `0`;
|
||||
3. o compiler garante que esse índice `0` pertence ao wrapper sintético publicado;
|
||||
4. export nominal do callable deixa de ser a autoridade de boot;
|
||||
5. qualquer compatibilidade temporária com manifest nominal deve ser tratada apenas como transição, não como contrato final desejado.
|
||||
|
||||
## Exports Boundary
|
||||
|
||||
Esta agenda também fecha a seguinte separação:
|
||||
|
||||
1. exports nominais de funções podem continuar existindo no artefato;
|
||||
2. esses exports deixam de ser usados como autoridade de loader/boot;
|
||||
3. boot passa a depender exclusivamente do entrypoint físico `0` publicado pelo compiler;
|
||||
4. exports nominais permanecem apenas como superfície útil para tooling, debug, introspection e casos correlatos.
|
||||
|
||||
## Remaining Open Points
|
||||
|
||||
Com a direção acima, os pontos que ainda pedem fechamento real nesta agenda ficam reduzidos a:
|
||||
|
||||
1. a forma de propagação normativa dessa mudança para specs gerais de bytecode, lowering e cartridge contract.
|
||||
|
||||
## Runtime Propagation
|
||||
|
||||
Esta agenda também deve referenciar explicitamente a discussão correspondente no domínio runtime:
|
||||
|
||||
- `../runtime/docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`
|
||||
|
||||
Direção fechada desta agenda:
|
||||
|
||||
1. não há linha de compatibilidade desejada como estado-alvo;
|
||||
2. a remoção de `entrypoint` do runtime deve ser executada em prioridade alinhada ao compiler;
|
||||
3. a agenda de runtime é o owner da discussão operacional de loader/VM/manifest no outro domínio.
|
||||
|
||||
## Expected Spec Material
|
||||
|
||||
Se esta agenda fechar, a propagação esperada atinge pelo menos:
|
||||
|
||||
- `9. Dynamic Semantics Specification.md`
|
||||
- `13. Lowering IRBackend Specification.md`
|
||||
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
||||
- `12. Diagnostics Specification.md`
|
||||
|
||||
## Non-Goals
|
||||
|
||||
Esta agenda não deve:
|
||||
|
||||
1. escolher o encoding exato do wrapper no IR;
|
||||
2. definir estrutura detalhada de module init lowering;
|
||||
3. escrever fixtures completos de conformance.
|
||||
|
||||
## Next Step
|
||||
|
||||
Depois de fechar esta agenda, abrir ou aprofundar:
|
||||
|
||||
- `19.4. Globals and Lifecycle Lowering to IRBackend/IRVM Agenda`
|
||||
-305
@@ -1,305 +0,0 @@
|
||||
# Globals and Lifecycle Lowering to IRBackend/IRVM Agenda
|
||||
|
||||
## Status
|
||||
|
||||
Open
|
||||
|
||||
## 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`
|
||||
|
||||
## Purpose
|
||||
|
||||
Define how the already-decided globals and lifecycle model are represented and lowered through the executable compiler pipeline.
|
||||
|
||||
This agenda must close:
|
||||
|
||||
- the representation boundary for globals;
|
||||
- module init synthesis;
|
||||
- boot guard materialization;
|
||||
- wrapper lowering;
|
||||
- and the executable path that preserves the chosen `FRAME_RET` ownership.
|
||||
|
||||
## Domain Owner
|
||||
|
||||
`docs/compiler/pbs`
|
||||
|
||||
Este tema pertence ao domínio PBS, mas encosta diretamente nas specs gerais de lowering e nas interfaces entre frontend e backend.
|
||||
|
||||
## Context
|
||||
|
||||
Depois que surface, lifecycle e publication contract estiverem fechados, ainda restará decidir:
|
||||
|
||||
- em que boundary globals passam a existir como entidade explícita;
|
||||
- se `IRBackend` carrega globals diretamente ou só uma forma anterior;
|
||||
- como module init sintético é representado;
|
||||
- como o wrapper published entrypoint é emitido;
|
||||
- como o guard one-shot de boot é materializado.
|
||||
|
||||
Esta agenda é mecânica/arquitetural. Ela não deve reabrir decisões de linguagem.
|
||||
|
||||
## Inputs Already Fixed Elsewhere
|
||||
|
||||
Os seguintes inputs devem ser tratados como fixos aqui:
|
||||
|
||||
- surface e identidade de globals vindas de `19.1`;
|
||||
- lifecycle semântico vindo de `19.2`;
|
||||
- owner do published entrypoint e de `FRAME_RET` vindo de `19.3`;
|
||||
- `GET_GLOBAL` e `SET_GLOBAL` já existem na VM.
|
||||
|
||||
## Decisions To Produce
|
||||
|
||||
Esta agenda deve produzir direção suficiente para fechar:
|
||||
|
||||
1. se globals entram explicitamente no `IRBackend` ou apenas em lowering posterior;
|
||||
2. como module init é sintetizado;
|
||||
3. como o guard one-shot de boot é materializado;
|
||||
4. como o wrapper é lowered;
|
||||
5. como `FRAME_RET` é preservado no ponto correto;
|
||||
6. quais contracts gerais de lowering precisam propagação.
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. `IRBackend` deve ganhar representação explícita para globals?
|
||||
2. Se não, qual é o boundary intermediário responsável por materializá-los antes de `IRVM`?
|
||||
3. Module init sintético é emitido como callable próprio por módulo?
|
||||
4. O boot guard é global oculto, local estático de wrapper, ou outra forma interna?
|
||||
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
|
||||
|
||||
### Option A
|
||||
|
||||
Dar representação explícita a globals e callables sintéticos já no boundary de `IRBackend`, preservando attribution e identidade suficientes para lowering posterior.
|
||||
|
||||
### Option B
|
||||
|
||||
Manter `IRBackend` sem globals explícitos e adiar essa materialização para um lowering mais baixo.
|
||||
|
||||
### Option C
|
||||
|
||||
Tratar globals como açúcar compilado diretamente para slots/ops sem entidade intermediária estável.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
### Option A
|
||||
|
||||
- Prós:
|
||||
- boundary mais explícito e testável;
|
||||
- menor inferência textual em lowers posteriores;
|
||||
- facilita explicar wrapper e init synthesis.
|
||||
- Contras:
|
||||
- aumenta o contrato do `IRBackend`;
|
||||
- pode exigir propagação além do domínio PBS.
|
||||
|
||||
### Option B
|
||||
|
||||
- Prós:
|
||||
- preserva o boundary atual por mais tempo.
|
||||
- Contras:
|
||||
- empurra complexidade para fases posteriores;
|
||||
- dificulta conformance do shape intermediário.
|
||||
|
||||
### Option C
|
||||
|
||||
- Prós:
|
||||
- menor aparente custo de modelagem.
|
||||
- Contras:
|
||||
- fraco para teste, attribution e manutenção;
|
||||
- mistura lowering demais cedo.
|
||||
|
||||
## Recommendation
|
||||
|
||||
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:
|
||||
|
||||
- `13. Lowering IRBackend Specification.md`
|
||||
- specs gerais de lowering/backend fora do domínio PBS, se necessário
|
||||
- `12. Diagnostics Specification.md`
|
||||
|
||||
## Non-Goals
|
||||
|
||||
Esta agenda não deve:
|
||||
|
||||
1. redefinir surface syntax;
|
||||
2. redefinir lifecycle;
|
||||
3. redefinir manifest publication;
|
||||
4. fechar catálogo final de fixtures.
|
||||
|
||||
## Next Step
|
||||
|
||||
Depois de fechar esta agenda, abrir ou aprofundar:
|
||||
|
||||
- `19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda`
|
||||
-277
@@ -1,277 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,76 +0,0 @@
|
||||
# PBS Agendas
|
||||
|
||||
This directory contains active PBS discussion agendas.
|
||||
|
||||
Closed agendas are moved to `docs/compiler/pbs/agendas/archive`.
|
||||
|
||||
## Active Agendas
|
||||
|
||||
1. `18.4. Asset References in Game Code - Names vs Compile-Time Lowering Agenda.md`
|
||||
2. `18.5. Ignored Call Results in Executable Lowering Agenda.md`
|
||||
3. `19. Globals, Synthetic Module Init, and FRAME_RET Agenda.md`
|
||||
4. `19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda.md`
|
||||
5. `19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda.md`
|
||||
6. `19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda.md`
|
||||
7. `19.4. Globals and Lifecycle Lowering to IRBackend-IRVM Agenda.md`
|
||||
8. `19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda.md`
|
||||
|
||||
## Consolidated Agenda 18 Material
|
||||
|
||||
Agenda 18 backend-orchestration material (`18.0` through `18.3`) is no longer part of the active agenda set.
|
||||
|
||||
That slice has already been propagated into:
|
||||
|
||||
1. the backend execution plan in `docs/compiler/pbs/pull-requests/INDEX.md` under `Backend VM Pipeline PR Sequence (Agenda 18)`,
|
||||
2. decision material such as `docs/compiler/pbs/decisions/IRVM Optimization Stage Placement Decision.md`,
|
||||
3. normative backend specs:
|
||||
- `docs/compiler/general/specs/19. Verification and Safety Checks Specification.md`,
|
||||
- `docs/compiler/general/specs/20. IRBackend to IRVM Lowering Specification.md`,
|
||||
- `docs/compiler/general/specs/21. IRVM Optimization Pipeline Specification.md`,
|
||||
- `docs/compiler/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`,
|
||||
4. and implemented/tested backend pipeline stages in `prometeu-compiler/prometeu-build-pipeline`.
|
||||
|
||||
Only `18.4` and `18.5` remain open from the `18.*` family.
|
||||
|
||||
## Purpose
|
||||
|
||||
An agenda exists to drive a decision, not to serve as final normative text.
|
||||
|
||||
Use an agenda when:
|
||||
|
||||
- the topic is still open,
|
||||
- multiple options or tradeoffs must be evaluated,
|
||||
- the scope and non-goals need to be made explicit,
|
||||
- the order of discussion matters.
|
||||
|
||||
Move an agenda to `docs/compiler/pbs/agendas/archive` once the topic is no longer active.
|
||||
|
||||
## Expected Format
|
||||
|
||||
An agenda should usually include:
|
||||
|
||||
1. Title
|
||||
2. Status
|
||||
3. Purpose
|
||||
4. Context
|
||||
5. Decisions to Produce
|
||||
6. Core Questions
|
||||
7. Expected Spec Material
|
||||
8. Non-Goals
|
||||
9. Inputs
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Keep the document oriented around unresolved questions.
|
||||
- Separate open questions from assumptions already fixed elsewhere.
|
||||
- Name the concrete decisions the discussion must produce.
|
||||
- Avoid drafting large blocks of final normative spec text here.
|
||||
- Prefer explicit non-goals to prevent scope drift.
|
||||
|
||||
## Exit Rule
|
||||
|
||||
An agenda should move out of the active set when:
|
||||
|
||||
- the key questions have been answered,
|
||||
- the architectural direction is clear enough to record,
|
||||
- and the topic is ready to become a decision record and then a spec update.
|
||||
Reference in New Issue
Block a user