---
id: DEC-0007
ticket: compiler-analyze-compile-build-pipeline-split
title: Canonical compiler entrypoints for analyze, compile, and build
status: in_progress
created: 2026-03-30
accepted: 2026-03-30
agenda: AGD-0011
plans:
  - PLN-0009
  - PLN-0010
  - PLN-0011
tags:
  - compiler
  - pipeline
  - artifacts
  - build
  - analysis
---

## Decision

O dominio `compiler` SHALL expor tres entrypoints canonicos sobre um unico pipeline compartilhado:

1. `analyze`
2. `compile`
3. `build`

Esses entrypoints MUST corresponder aos seguintes cortes normativos de stages:

1. `analyze = ResolveDeps + LoadSources + FrontendPhase`
2. `compile = analyze + LowerToIRVM + OptimizeIRVM + EmitBytecode + LinkBytecode + VerifyBytecode`
3. `build = compile + WriteBytecodeArtifact`

`BuilderPipelineService` MUST deixar de expor `run` como entrypoint publico.
O comportamento atualmente observado em `run` MUST ser preservado como o comportamento default de `build`, usando config/contexto de filesystem construido fora do pipeline em si.

LSP, editor e outros consumidores MUST reutilizar esse mesmo pipeline canonico.
Eles MAY fornecer configs/contextos distintos por entrypoint, mas esses contextos MUST NOT alterar a semantica central dos stages canonicos nem introduzir um pipeline paralelo disfarçado.

## Rationale

O pipeline atual ja possui um seam natural entre:

1. analise semantica da workspace;
2. producao de artefato executavel em memoria;
3. persistencia terminal em disco.

Transformar esses cortes em entrypoints explicitos melhora a superficie operacional do compiler sem duplicar infraestrutura nem esconder semantica em flags ad hoc.

Essa decisao tambem preserva duas propriedades importantes:

1. compatibilidade comportamental com o fluxo atual que produz artefato executavel para PBS, que passa a ser tratado como baseline de corretude;
2. generalidade suficiente para que outros frontends consumam o compiler sem herdarem regras exclusivas de PBS.

Remover `run` evita que o nome antigo continue funcionando como conceito normativo opaco.
O nome correto do fluxo default passa a ser `build`.

## Technical Specification

### 1. Canonical pipeline

O compiler MUST manter um unico pipeline canonico compartilhado.
Esse pipeline MUST preservar a semantica e a ordem dos stages normativos:

1. `ResolveDepsPipelineStage`
2. `LoadSourcesPipelineStage`
3. `FrontendPhasePipelineStage`
4. `LowerToIRVMPipelineStage`
5. `OptimizeIRVMPipelineStage`
6. `EmitBytecodePipelineStage`
7. `LinkBytecodePipelineStage`
8. `VerifyBytecodePipelineStage`
9. `WriteBytecodeArtifactPipelineStage`

Nenhum entrypoint MAY reordenar esses stages.

### 2. Entry point contracts

`analyze` MUST terminar em `FrontendPhasePipelineStage`.
`analyze` MUST retornar um `AnalysisSnapshot` estavel ou equivalente de mesmo papel semantico.
Esse resultado MUST expor, no minimo:

1. diagnosticos;
2. facts semanticos produzidos pelo frontend;
3. referencias estaveis para os sources carregados, incluindo o equivalente ao `FileTable`;
4. metadados de resolucao da workspace necessarios para tooling.

Implementacoes MAY expor campos adicionais, mas MUST NOT omitir esses elementos minimos.
`analyze` MUST NOT executar lowering, emissao, verificacao de bytecode ou persistencia de artefato.

`compile` MUST terminar em `VerifyBytecodePipelineStage`.
`compile` MUST produzir resultado executavel validado em memoria, incluindo `bytecodeModule` e `bytecodeBytes` ou equivalentes de mesmo papel semantico.
`compile` MUST incluir `LinkBytecode` e `VerifyBytecode`.
`compile` MUST NOT persistir artefato em disco.

`build` MUST terminar em `WriteBytecodeArtifactPipelineStage`.
`build` MUST ser definido como `compile` seguido apenas da persistencia terminal.
`build` MUST preservar o comportamento default atual de escrita de artefato em filesystem.

### 3. Service surface

`BuilderPipelineService` MUST evoluir para uma superficie com entrypoints explicitos equivalentes a:

1. `analyze(config, logs)`
2. `compile(config, logs)`
3. `build(config, logs)`

Os nomes exatos MAY variar, mas a separacao semantica MUST ser preservada.

`run` MUST ser removido como entrypoint publico.
Qualquer composicao equivalente ao comportamento atual MUST ser expressa por `build` com config/contexto apropriado.

### 4. Context and config model

Configs/contextos distintos por entrypoint MAY existir para suportar CLI, editor, LSP e outros callsites.

Esses contextos MAY ajustar:

1. fontes de entrada;
2. sinks/collectors;
3. shape de retorno;
4. estrategia de composicao externa.

Esses contextos MUST NOT:

1. redefinir a semantica central dos stages canonicos;
2. introduzir ordem diferente de stages para os mesmos entrypoints;
3. criar um pipeline paralelo com regras semanticas proprias sob os mesmos nomes `analyze`, `compile` ou `build`.

A construcao do contexto default de filesystem MUST acontecer fora do pipeline itself, no callsite ou camada de composicao apropriada.

### 5. Compatibility and propagation

Esta decisao MUST preservar compatibilidade comportamental com o fluxo atual que produz artefato executavel para PBS.
Essa compatibilidade MUST cobrir, no minimo:

1. a mesma ordem semantica de stages hoje usada para chegar ao artefato executavel;
2. o mesmo nivel de corretude do resultado executavel produzido em memoria antes da persistencia;
3. a ausencia de regressao nos gates de emissao, link e verificacao que hoje protegem esse fluxo.

PBS MUST ser tratado como consumidor importante e baseline de corretude, mas MUST NOT virar detalhe normativo exclusivo da API publica.

Esta decisao MUST ser propagada para:

1. a spec operacional do pipeline do compiler;
2. os contratos de CLI e callsites existentes;
3. a documentacao dos resultados intermediarios (`AnalysisSnapshot`, resultado de `compile`, resultado de `build`).

Esta decisao MUST NOT reinterpretar a spec de PBX como requisito de persistencia em disco.
A authority da spec de PBX permanece na fronteira de emissao e mapeamento de artefatos.

## Constraints

1. `SourceProviderFactory` permanece como boundary de leitura do compiler nesta decisao.
2. Esta decisao nao define ainda novos providers especificos de editor.
3. Esta decisao nao autoriza pipelines paralelos por frontend.
4. Esta decisao nao permite tratar requisito normativo aqui definido como opcional em plan ou implement.
5. Qualquer revisao futura sobre os cortes de stage, o modelo de contexto ou a remocao de `run` MUST ocorrer por nova decisao explicita.

## Revision Log

- 2026-03-30: Initial draft from AGD-0011.
- 2026-03-30: Accepted and decomposed into PLN-0009, PLN-0010, and PLN-0011.