prometeu-studio/discussion/workflow/decisions/DEC-0007-compiler-analyze-compile-build-pipeline-split.md

id	ticket	title	status	created	accepted	agenda	plans	tags
DEC-0007	compiler-analyze-compile-build-pipeline-split	Canonical compiler entrypoints for analyze, compile, and build	in_progress	2026-03-30	2026-03-30	AGD-0011	PLN-0009 PLN-0010 PLN-0011	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.