add agendas and decisions
This commit is contained in:
parent
5bfb70979f
commit
2e640a14ae
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -1,122 +0,0 @@
|
||||
# PBS Frontend IR and Lowering Agenda
|
||||
|
||||
Status: Active
|
||||
|
||||
## Purpose
|
||||
|
||||
Drive closure of `13. Lowering IRBackend Specification.md` for frontend scope only.
|
||||
|
||||
This agenda exists to define the first normative lowering boundary:
|
||||
|
||||
- PBS source to frontend IR (`IRBackend` / `IRBackendFile`),
|
||||
- deterministic diagnostic behavior for unsupported or invalid source forms,
|
||||
- and test-backed acceptance criteria for Gate U.
|
||||
|
||||
## Scope Boundary
|
||||
|
||||
In scope:
|
||||
|
||||
- lexer/parser/AST/linking outputs consumed by frontend lowering,
|
||||
- semantic facts that must be preserved in frontend IR,
|
||||
- deterministic rejection classes and diagnostic attribution,
|
||||
- and conformance evidence for frontend gates.
|
||||
|
||||
Out of scope:
|
||||
|
||||
- VM lowering,
|
||||
- bytecode/PBX mapping,
|
||||
- runtime execution behavior,
|
||||
- verifier/loader algorithms.
|
||||
|
||||
## Decisions To Produce
|
||||
|
||||
1. Decide whether `13` standardizes one frontend IR shape or only preserved obligations.
|
||||
2. Decide the minimum preconditions before frontend lowering begins.
|
||||
3. Decide which semantic facts must be explicit in frontend IR for v1.
|
||||
4. Decide the minimum deterministic rejection set for unsupported frontend-lowering cases.
|
||||
5. Decide the gate evidence expected from tests (`lexer/parser/AST/IRBackend/diagnostics`).
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. What is the minimum frontend IR contract that keeps implementation practical and testable now?
|
||||
2. Which source-observable guarantees must already be explicit before any backend stage exists?
|
||||
3. Which constructs are in-scope for v1 lowering and which must fail deterministically?
|
||||
4. What diagnostics identity must be stable for lowering-related frontend failures?
|
||||
5. Which regression fixtures become mandatory Gate U evidence?
|
||||
|
||||
## Proposed Workshop Sequence
|
||||
|
||||
### Workshop 1: Frontend Lowering Contract and Preconditions
|
||||
|
||||
Purpose:
|
||||
|
||||
- close input preconditions,
|
||||
- and close the normative status of frontend IR.
|
||||
|
||||
Expected decisions:
|
||||
|
||||
- obligations-only versus canonical frontend IR model,
|
||||
- and minimum required bound-program state before lowering.
|
||||
|
||||
### Workshop 2: Expressions, Control Flow, and Propagation in Frontend IR
|
||||
|
||||
Purpose:
|
||||
|
||||
- close frontend-lowering obligations for core expression/control-flow forms.
|
||||
|
||||
Expected decisions:
|
||||
|
||||
- once-only evaluation obligations in frontend IR terms,
|
||||
- representation obligations for branching and propagation constructs.
|
||||
|
||||
### Workshop 3: Callable Categories in Frontend IR
|
||||
|
||||
Purpose:
|
||||
|
||||
- close frontend-lowering obligations for functions, callbacks, services, and contracts as source-level categories.
|
||||
|
||||
Expected decisions:
|
||||
|
||||
- minimum callable metadata preserved in frontend IR,
|
||||
- and deterministic rejection boundaries for unsupported callable forms.
|
||||
|
||||
### Workshop 4: Builtins, Diagnostics, and Test Gates
|
||||
|
||||
Purpose:
|
||||
|
||||
- close builtin-facing frontend obligations plus gate-ready diagnostics/test evidence.
|
||||
|
||||
Expected decisions:
|
||||
|
||||
- frontend treatment of builtin shells/metadata at lowering boundary,
|
||||
- minimum diagnostics identity and attribution for lowering-related failures,
|
||||
- and required fixture families for Gate U.
|
||||
|
||||
## Expected Spec Material
|
||||
|
||||
The resulting `13` content should close:
|
||||
|
||||
- lowering preconditions for frontend scope,
|
||||
- frontend IR preserved-obligation model,
|
||||
- construct-by-construct frontend lowering baseline,
|
||||
- deterministic unsupported-case rejection policy,
|
||||
- and frontend-facing diagnostic/test evidence hooks.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Defining VM or bytecode artifacts.
|
||||
- Freezing runtime semantics in this agenda.
|
||||
- Defining verifier or loader internals.
|
||||
- Freezing optimizer architecture.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `docs/pbs/specs/3. Core Syntax Specification.md`
|
||||
- `docs/pbs/specs/4. Static Semantics Specification.md`
|
||||
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
|
||||
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
|
||||
- `docs/pbs/specs/12. Diagnostics Specification.md`
|
||||
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
|
||||
- `docs/general/specs/13. Conformance Test Specification.md`
|
||||
- `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
|
||||
- `docs/general/specs/19. Verification and Safety Checks Specification.md`
|
||||
@ -1,86 +0,0 @@
|
||||
# PBS Frontend IR and Lowering Workshop 2
|
||||
|
||||
Status: Active
|
||||
|
||||
## Purpose
|
||||
|
||||
Run the second focused discussion for `13. Lowering IRBackend Specification.md` on frontend-lowering obligations for:
|
||||
|
||||
- expression evaluation order,
|
||||
- branching behavior,
|
||||
- and propagation-related constructs at frontend IR boundary.
|
||||
|
||||
## Why This Slice Second
|
||||
|
||||
After Workshop 1 closes contract/preconditions, this workshop closes construct-level obligations that must be testable in frontend scope.
|
||||
|
||||
## Proposed Meeting Order
|
||||
|
||||
1. Reconfirm preserved obligations from Workshop 1.
|
||||
2. Close once-only evaluation obligations in frontend IR terms.
|
||||
3. Close branch and abrupt-completion representation obligations.
|
||||
4. Close propagation construct obligations (`optional`, `result`, `!`, `handle`) at frontend boundary.
|
||||
5. Record callable-category leftovers for Workshop 3.
|
||||
|
||||
## Decisions To Produce
|
||||
|
||||
1. Which evaluation-order guarantees must remain explicit in frontend IR obligations.
|
||||
2. Which branch/abrupt-completion facts are mandatory in v1 frontend lowering.
|
||||
3. Which propagation constructs are in-scope versus deterministic rejection in v1 slice.
|
||||
4. Which diagnostics are required when unsupported propagation constructs are used.
|
||||
|
||||
## Candidate Decisions
|
||||
|
||||
### 1. Frontend Lowering Must Preserve Once-Only Evaluation Facts
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- source-observable single-evaluation points are preserved as explicit lowering obligations,
|
||||
- independent of one exact IR node taxonomy.
|
||||
|
||||
### 2. Branching Obligations Are Normative At Frontend Boundary
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- selected/non-selected branch semantics remain explicit in frontend lowering contract,
|
||||
- with no implicit permissive fallbacks.
|
||||
|
||||
### 3. Propagation Constructs Have Explicit V1 Status
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- each construct is marked `supported in v1 frontend lowering` or `deterministic reject`,
|
||||
- and this status is mirrored in Gate U fixtures.
|
||||
|
||||
### 4. Diagnostics Identity Must Be Stable For Unsupported Forms
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- unsupported forms emit stable code/severity/primary attribution,
|
||||
- so regression tests can lock behavior.
|
||||
|
||||
## Questions To Resolve In The Room
|
||||
|
||||
1. Which propagation constructs are fully represented now versus deferred?
|
||||
2. What minimum frontend IR evidence is enough to prove evaluation-order obligations?
|
||||
3. Which failures should be classified as parse/static errors versus lowering errors?
|
||||
4. Which fixture shapes are mandatory for Gate U here?
|
||||
|
||||
## Expected Outputs
|
||||
|
||||
1. a decision note on expression/control-flow lowering obligations,
|
||||
2. a decision note on propagation status map (support/reject),
|
||||
3. and fixture targets for frontend conformance tests.
|
||||
|
||||
## Explicit Deferrals For Workshop 3
|
||||
|
||||
- callable-category representation details,
|
||||
- and service/contract/callback-specific obligations.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
|
||||
- `docs/pbs/specs/12. Diagnostics Specification.md`
|
||||
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
|
||||
- `docs/general/specs/13. Conformance Test Specification.md`
|
||||
- `docs/pbs/agendas/archive/13.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md`
|
||||
@ -1,88 +0,0 @@
|
||||
# PBS Frontend IR and Lowering Workshop 3
|
||||
|
||||
Status: Active
|
||||
|
||||
## Purpose
|
||||
|
||||
Run the third focused discussion for `13. Lowering IRBackend Specification.md` on callable categories in frontend scope:
|
||||
|
||||
- top-level functions,
|
||||
- callbacks,
|
||||
- services,
|
||||
- and contracts as source-level callable surfaces.
|
||||
|
||||
## Why This Slice Third
|
||||
|
||||
Callable categories depend on the core expression/control-flow obligations from Workshop 2 and now need explicit frontend representation/rejection boundaries.
|
||||
|
||||
## Proposed Meeting Order
|
||||
|
||||
1. Reconfirm callable and identity facts already settled by syntax/static/linking specs.
|
||||
2. Close frontend-lowering obligations for function and callback forms.
|
||||
3. Close frontend-lowering obligations for service/contract callable surfaces.
|
||||
4. Close deterministic rejection policy for unsupported callable forms.
|
||||
5. Record builtin/diagnostics gate closure points for Workshop 4.
|
||||
|
||||
## Decisions To Produce
|
||||
|
||||
1. Minimum callable metadata preserved by frontend IR for each callable category.
|
||||
2. V1 support map for callable categories (`supported` versus deterministic reject).
|
||||
3. Required diagnostics identity for rejected callable forms.
|
||||
4. Required regression fixtures for callable categories in Gate U.
|
||||
|
||||
## Candidate Decisions
|
||||
|
||||
### 1. Callable Identity Must Be Explicit In Frontend IR Contract
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- callable name/category/arity/source attribution are mandatory preserved facts,
|
||||
- regardless of internal object-model differences.
|
||||
|
||||
### 2. Callback/Service/Contract Surfaces Need Explicit V1 Status
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- each callable surface is classified now as `represented` or `rejected`,
|
||||
- with no silent fallback behavior.
|
||||
|
||||
### 3. Unsupported Callable Forms Are Deterministic Diagnostics
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- unsupported callable patterns must emit stable diagnostics,
|
||||
- and become mandatory regression tests.
|
||||
|
||||
### 4. Gate U Must Cover Callable Categories Explicitly
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- representative valid+invalid fixtures per callable category are mandatory,
|
||||
- including diagnostics assertions for rejected forms.
|
||||
|
||||
## Questions To Resolve In The Room
|
||||
|
||||
1. Which callable category fields are mandatory in `IRBackend` today?
|
||||
2. Which callable constructs remain deferred in v1 frontend scope?
|
||||
3. What is the minimum fixture set to protect callable behavior regressions?
|
||||
4. Which diagnostics codes must be fixed now versus later?
|
||||
|
||||
## Expected Outputs
|
||||
|
||||
1. a decision note on callable frontend-lowering obligations,
|
||||
2. a decision note on callable support/rejection map,
|
||||
3. and Gate U fixture requirements for callable categories.
|
||||
|
||||
## Explicit Deferrals For Workshop 4
|
||||
|
||||
- builtin-specific lowering obligations,
|
||||
- and final diagnostics/gate packaging for spec closure.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `docs/pbs/specs/4. Static Semantics Specification.md`
|
||||
- `docs/pbs/specs/12. Diagnostics Specification.md`
|
||||
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
|
||||
- `docs/general/specs/13. Conformance Test Specification.md`
|
||||
- `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
|
||||
- `docs/pbs/agendas/13.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md`
|
||||
@ -1,89 +0,0 @@
|
||||
# PBS Frontend IR and Lowering Workshop 4
|
||||
|
||||
Status: Active
|
||||
|
||||
## Purpose
|
||||
|
||||
Run the fourth focused discussion for `13. Lowering IRBackend Specification.md` to close frontend-specific pending points:
|
||||
|
||||
- builtin-facing source semantics at frontend lowering boundary,
|
||||
- diagnostics stability for lowering-related failures,
|
||||
- and test-gate evidence needed to close v1 frontend slice.
|
||||
|
||||
## Why This Slice Last
|
||||
|
||||
This workshop should close only after Workshops 1 to 3 define the base lowering contract and callable status map.
|
||||
|
||||
## Proposed Meeting Order
|
||||
|
||||
1. Reconfirm frontend-only scope and deferred backend concerns.
|
||||
2. Close builtin-shell obligations at frontend lowering boundary.
|
||||
3. Close diagnostics identity/attribution obligations for lowering-related failures.
|
||||
4. Close minimum gate evidence package (Gate U).
|
||||
5. Produce closure checklist for spec `13` frontend slice.
|
||||
|
||||
## Decisions To Produce
|
||||
|
||||
1. Frontend-lowering obligations for builtin-facing constructs in v1.
|
||||
2. Stable diagnostics contract for frontend-lowering rejections.
|
||||
3. Mandatory fixture families to prove `13` frontend obligations.
|
||||
4. Explicit list of deferred topics that belong to future backend-focused agenda.
|
||||
|
||||
## Candidate Decisions
|
||||
|
||||
### 1. Builtin Surfaces Are Frontend-Validated Before Any Backend Contract
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- builtin names and metadata usage are validated at frontend scope per existing specs,
|
||||
- and lowering emits deterministic outcomes or deterministic rejection.
|
||||
|
||||
### 2. Diagnostics Contract Is Mandatory For Frontend-Lowering Failures
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- code/severity/primary attribution are fixed and test-backed for required rejection classes,
|
||||
- enabling reliable regression protection.
|
||||
|
||||
### 3. Gate Evidence Is Small But Mandatory
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- each required obligation has at least one positive and one negative fixture where applicable,
|
||||
- with assertions for lexer/parser/AST/IRBackend/diagnostics.
|
||||
|
||||
### 4. Backend Topics Are Explicitly Deferred
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- VM lowering, bytecode mapping, runtime, verifier, and loader remain out of this agenda,
|
||||
- and are listed as deferred backlog topics.
|
||||
|
||||
## Questions To Resolve In The Room
|
||||
|
||||
1. Which builtin scenarios are mandatory in v1 fixture corpus?
|
||||
2. Which lowering-related diagnostics are mandatory to freeze now?
|
||||
3. What is the minimum evidence bar to declare `13` frontend slice closed?
|
||||
4. Which open points are explicitly deferred without blocking frontend progress?
|
||||
|
||||
## Expected Outputs
|
||||
|
||||
1. a decision note on builtin frontend-lowering obligations,
|
||||
2. a decision note on diagnostics/test evidence obligations,
|
||||
3. and a closure checklist for `13` frontend scope.
|
||||
|
||||
## Explicit Deferrals
|
||||
|
||||
- VM lowering design,
|
||||
- bytecode/PBX mapping,
|
||||
- runtime execution contracts,
|
||||
- verifier and loader internals.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `docs/pbs/specs/12. Diagnostics Specification.md`
|
||||
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
|
||||
- `docs/general/specs/13. Conformance Test Specification.md`
|
||||
- `docs/general/specs/19. Verification and Safety Checks Specification.md`
|
||||
- `docs/pbs/agendas/13.3. IR and Lowering Workshop 3 - Callables, Services, Contracts, and Callbacks.md`
|
||||
@ -0,0 +1,61 @@
|
||||
# 18.0. Backend VM Pipeline - Orchestration Agenda
|
||||
|
||||
Status: Active (Draft)
|
||||
|
||||
## Purpose
|
||||
|
||||
Definir a ordem de fechamento arquitetural para o backend executável:
|
||||
|
||||
1. contrato de entrada `IRBackend` vindo do frontend,
|
||||
2. lowering `IRBackend -> IRVM`,
|
||||
3. marshaling `IRVM -> bytecode/PBX` executável no runtime.
|
||||
|
||||
## Context
|
||||
|
||||
- O pipeline já prevê `LowerToVMPipelineStage` e `EmitBytecodePipelineStage`, mas ambos estão vazios.
|
||||
- O runtime já impõe contratos concretos de loader/verifier/VM que precisam ser respeitados pelo backend.
|
||||
- Nesta rodada, `packer` está explicitamente fora de escopo.
|
||||
|
||||
## Decisions to Produce
|
||||
|
||||
1. Ordem oficial de workshops e critérios de saída por etapa.
|
||||
2. Fronteiras normativas entre:
|
||||
- frontend (`IRBackend`),
|
||||
- backend (`IRVM` + emissão),
|
||||
- runtime (loader/verifier/execução).
|
||||
3. Critérios de “backend integration-ready” para um artefato bytecode mínimo rodar no runtime.
|
||||
4. Estratégia de fechamento em docs (`agendas -> decisions -> specs -> PR`).
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. Quais decisões precisam ser fechadas antes de qualquer implementação de `LowerToVM`?
|
||||
2. Quais invariantes são obrigatórias na fronteira `IRBackend` para evitar ambiguidade no backend?
|
||||
3. Quais invariantes são obrigatórias na fronteira `IRVM` para emissão determinística?
|
||||
4. Quais verificações devem ocorrer no compilador antes de delegar ao loader/verifier do runtime?
|
||||
5. Como organizar testes de integração sem introduzir dependência de packer?
|
||||
|
||||
## Expected Spec Material
|
||||
|
||||
1. Nova spec de contrato `IRBackend -> IRVM` (backend-facing).
|
||||
2. Nova spec de contrato de `IRVM` (shape, invariantes, diagnóstico).
|
||||
3. Atualização de `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`.
|
||||
4. Atualização de `docs/general/specs/19. Verification and Safety Checks Specification.md`.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Definir formato final de packer/cartucho.
|
||||
- Redesenhar ISA do runtime.
|
||||
- Redesenhar loader/verifier do runtime.
|
||||
- Fechar otimizações de backend (peephole, SSA, etc.).
|
||||
|
||||
## Inputs
|
||||
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToVMPipelineStage.java`
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/EmitBytecodePipelineStage.java`
|
||||
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
|
||||
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
|
||||
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `../runtime/docs/runtime/virtual-machine/ISA_CORE.md`
|
||||
- `../runtime/crates/console/prometeu-vm/src/virtual_machine/loader.rs`
|
||||
- `../runtime/crates/console/prometeu-vm/src/verifier.rs`
|
||||
|
||||
@ -0,0 +1,68 @@
|
||||
# 18.1. Backend Workshop 1 - IRBackend Input Contract
|
||||
|
||||
Status: Active (Draft)
|
||||
|
||||
## Purpose
|
||||
|
||||
Fechar o `IRBackend` como contrato de entrada do backend executável, de forma suficientemente explícita para permitir lowering determinístico para `IRVM`.
|
||||
|
||||
## Context
|
||||
|
||||
- A spec atual de `IRBackend` cobre sobretudo a fronteira frontend e não fecha `IRBackend -> IRVM`.
|
||||
- O runtime exige contratos rígidos para chamadas host-backed (`SYSC`/`HOSTCALL`) e VM-owned (`INTRINSIC`).
|
||||
- O backend precisa receber um IR que preserve semântica e também fatos de artefato necessários para bytecode.
|
||||
|
||||
## Decisions to Produce
|
||||
|
||||
1. Shape mínima obrigatória de `IRBackend` para backend executável:
|
||||
- identidade de módulo/arquivo/callable,
|
||||
- assinatura (parâmetros/retorno),
|
||||
- corpo executável em forma backend-lowerable,
|
||||
- âncoras de source attribution.
|
||||
2. Modelo de representação para operações VM-owned vs host-backed no `IRBackend`.
|
||||
3. Contrato de metadados reservados obrigatório:
|
||||
- host bindings canônicos `(module, name, version)`,
|
||||
- metadados de intrinsics/builtin VM-owned,
|
||||
- `requiredCapabilities` determinístico.
|
||||
4. Regras de ordenação/deduplicação obrigatórias ainda no `IRBackend`.
|
||||
5. Política de rejeição determinística para formas que não entram no backend executável.
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. O `IRBackend` deve carregar código em forma estruturada (blocos/expressões) ou linearizada?
|
||||
2. Quais informações de tipos precisam sobreviver para o backend sem “re-tipagem” implícita?
|
||||
3. Como representar chamadas host-backed no `IRBackend`:
|
||||
- por identidade canônica,
|
||||
- por índice lógico,
|
||||
- ou por ambos?
|
||||
4. Como representar intrinsics VM-owned:
|
||||
- identidade canônica apenas,
|
||||
- id final já conhecido,
|
||||
- ou modelo híbrido?
|
||||
5. Quais invariantes de estabilidade de ordenação são obrigatórias para conformance?
|
||||
6. Quais campos mínimos de span/source mapping são mandatórios para erros backend-atribuíveis?
|
||||
|
||||
## Expected Spec Material
|
||||
|
||||
1. Atualização de `docs/pbs/specs/13. Lowering IRBackend Specification.md` com adendo backend-facing.
|
||||
2. Decision record específico para “IRBackend executável v1”.
|
||||
3. Fixture set de conformance Gate U focado no contrato de entrada do backend.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Definir ainda o bytecode final.
|
||||
- Definir políticas de otimização.
|
||||
- Definir o formato final de debug/source map rico.
|
||||
- Introduzir dependência de packer.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRBackend.java`
|
||||
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRBackendFile.java`
|
||||
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRFunction.java`
|
||||
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRReservedMetadata.java`
|
||||
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
|
||||
- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `../runtime/docs/runtime/decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
|
||||
|
||||
@ -0,0 +1,69 @@
|
||||
# 18.2. Backend Workshop 2 - LowerToVM and IRVM Contract
|
||||
|
||||
Status: Active (Draft)
|
||||
|
||||
## Purpose
|
||||
|
||||
Definir o contrato intermediário `IRVM` e as regras normativas de lowering `IRBackend -> IRVM`, garantindo que a emissão de bytecode seja mecânica e determinística.
|
||||
|
||||
## Context
|
||||
|
||||
- O runtime já define ISA e calling rules concretas.
|
||||
- No runtime atual, jumps usam imediato `u32` absoluto relativo ao início da função.
|
||||
- O verificador e o loader já têm validações rígidas que devem ser antecipadas pelo backend sempre que possível.
|
||||
|
||||
## Decisions to Produce
|
||||
|
||||
1. Modelo oficial de `IRVM`:
|
||||
- unidades (módulo/função/bloco),
|
||||
- instruções VM-like,
|
||||
- referência a constantes/globais/locals/callables,
|
||||
- metadados mínimos por função.
|
||||
2. Regras de lowering para controle de fluxo:
|
||||
- labels simbólicos,
|
||||
- normalização de blocos,
|
||||
- política de branch/jump target.
|
||||
3. Regras de lowering para chamadas:
|
||||
- `CALL`,
|
||||
- `HOSTCALL` pré-load,
|
||||
- `INTRINSIC` VM-owned.
|
||||
4. Regras de layout de função e slots:
|
||||
- `param_slots`,
|
||||
- `local_slots`,
|
||||
- `return_slots`.
|
||||
5. Política de diagnósticos determinísticos no lowering para rejeições backend-originadas.
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. `IRVM` permite pseudo-opcodes que não existem na ISA final?
|
||||
2. Onde ocorre a resolução final de labels para offsets: no próprio lowering ou apenas no emitter?
|
||||
3. Como garantir que cada função tenha finalização válida (`RET`/terminador) sem depender só do verificador?
|
||||
4. Qual o limite de checagens estáticas no compiler vs checagens delegadas ao verifier do runtime?
|
||||
5. Como representar efeitos de stack no `IRVM` para detectar underflow/mismatch antes de emitir bytes?
|
||||
6. Como versionar `IRVM` em relação à linha de ISA do runtime selecionada?
|
||||
|
||||
## Expected Spec Material
|
||||
|
||||
1. Nova spec: `IRBackend -> IRVM` lowering contract.
|
||||
2. Nova spec: `IRVM` model e invariantes.
|
||||
3. Tabela de mapeamento `IRVM op -> ISA op` por linha de runtime suportada.
|
||||
4. Critérios de testes unitários do `LowerToVMPipelineStage`.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Implementar ainda otimizações avançadas.
|
||||
- Expandir ISA com novos opcodes.
|
||||
- Resolver políticas de linking multi-artifact além do necessário para execução v1.
|
||||
- Definir packer/cart assembly.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToVMPipelineStage.java`
|
||||
- `../runtime/docs/runtime/virtual-machine/ISA_CORE.md`
|
||||
- `../runtime/docs/runtime/specs/02-vm-instruction-set.md`
|
||||
- `../runtime/docs/runtime/specs/02a-vm-values-and-calling-convention.md`
|
||||
- `../runtime/crates/console/prometeu-bytecode/src/opcode.rs`
|
||||
- `../runtime/crates/console/prometeu-bytecode/src/opcode_spec.rs`
|
||||
- `../runtime/crates/console/prometeu-bytecode/src/decoder.rs`
|
||||
- `../runtime/crates/console/prometeu-vm/src/verifier.rs`
|
||||
|
||||
@ -0,0 +1,72 @@
|
||||
# 18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance
|
||||
|
||||
Status: Active (Draft)
|
||||
|
||||
## Purpose
|
||||
|
||||
Fechar o contrato de emissão de bytecode/PBX a partir de `IRVM`, com conformidade explícita ao loader/verifier/runtime atual.
|
||||
|
||||
## Context
|
||||
|
||||
- O runtime já define layout de módulo, parser de seções e invariantes de load-time.
|
||||
- `SYSC` é seção obrigatória (mesmo vazia), `HOSTCALL` é forma pré-load, `SYSCALL` final só após patching do loader.
|
||||
- O verifier rejeita `HOSTCALL` não patchado e valida estrutura de controle/stack sobre imagem final.
|
||||
|
||||
## Decisions to Produce
|
||||
|
||||
1. Contrato de marshaling de `IRVM -> BytecodeModule`:
|
||||
- `const_pool`,
|
||||
- `functions`,
|
||||
- `code`,
|
||||
- `debug_info` (mínimo obrigatório),
|
||||
- `exports`,
|
||||
- `syscalls`.
|
||||
2. Política de encoding de instruções:
|
||||
- little-endian,
|
||||
- `[opcode u16][immediate]`,
|
||||
- encoding de saltos/calls conforme ISA.
|
||||
3. Política de emissão de `SYSC`:
|
||||
- deduplicação por identidade canônica,
|
||||
- ordenação por primeira ocorrência,
|
||||
- `arg_slots`/`ret_slots` coerentes com metadado host.
|
||||
4. Contrato explícito “pre-load artifact vs executable image”:
|
||||
- backend emite `HOSTCALL` quando host-backed,
|
||||
- backend não emite `SYSCALL` bruto no artefato pré-load,
|
||||
- intrinsics VM-owned seguem caminho distinto.
|
||||
5. Estratégia de conformidade e regressão contra runtime real.
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. Qual política oficial de ordenação de funções no bytecode (ordem de source, topo sort, entry-first)?
|
||||
2. Como calcular `code_offset`/`code_len` por função em flatten final de `code`?
|
||||
3. Quais hooks mínimos de source attribution serão emitidos no `debug_info` v1?
|
||||
4. Quais validações o emitter faz antes de serializar vs o que é delegado ao loader/verifier?
|
||||
5. Como padronizar mensagens/erros de marshaling para manter diagnóstico determinístico?
|
||||
6. Qual suíte mínima de integração prova “bytecode emitido roda no runtime” sem packer?
|
||||
|
||||
## Expected Spec Material
|
||||
|
||||
1. Atualização de `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`.
|
||||
2. Atualização de `docs/general/specs/19. Verification and Safety Checks Specification.md`.
|
||||
3. Decision record de “bytecode backend v1 marshaling contract”.
|
||||
4. Plano de testes Gate I para backend executável.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Definir fluxo de empacotamento final de cartucho.
|
||||
- Alterar o contrato do loader/runtime.
|
||||
- Definir formato final de symbolication completo.
|
||||
- Cobrir perf tuning de emissor.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/EmitBytecodePipelineStage.java`
|
||||
- `../runtime/crates/console/prometeu-bytecode/src/model.rs`
|
||||
- `../runtime/crates/console/prometeu-bytecode/src/assembler.rs`
|
||||
- `../runtime/crates/console/prometeu-bytecode/src/program_image.rs`
|
||||
- `../runtime/crates/console/prometeu-vm/src/virtual_machine/loader.rs`
|
||||
- `../runtime/crates/console/prometeu-vm/src/vm_init_error.rs`
|
||||
- `../runtime/crates/console/prometeu-vm/src/verifier.rs`
|
||||
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
|
||||
|
||||
@ -4,6 +4,13 @@ This directory contains active PBS discussion agendas.
|
||||
|
||||
Closed agendas are moved to `docs/pbs/agendas/archive`.
|
||||
|
||||
## Active Agendas
|
||||
|
||||
1. `18.0. Backend VM Pipeline - Orchestration Agenda.md`
|
||||
2. `18.1. Backend Workshop 1 - IRBackend Input Contract.md`
|
||||
3. `18.2. Backend Workshop 2 - LowerToVM and IRVM Contract.md`
|
||||
4. `18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md`
|
||||
|
||||
## Purpose
|
||||
|
||||
An agenda exists to drive a decision, not to serve as final normative text.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user