# 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`