prometeu-studio/docs/compiler/pbs/agendas/19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda.md

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