agendas/decisions/plans for re-shape of compiler pipeline
This commit is contained in:
+164
@@ -0,0 +1,164 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user