165 lines
6.5 KiB
Markdown
165 lines
6.5 KiB
Markdown
---
|
|
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.
|