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

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

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