prometeu-studio/docs/compiler/pbs/agendas/19.4. Globals and Lifecycle Lowering to IRBackend/IRVM Agenda.md

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