prometeu-studio/docs/compiler/pbs/agendas/19. Globals, Synthetic Module Init, and FRAME_RET Agenda.md

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:

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:

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