From 2e640a14ae370c37a4cf1f588c0872535f06a447 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Sat, 7 Mar 2026 14:46:11 +0000 Subject: [PATCH] add agendas and decisions --- .../pbs/agendas/13. IR and Lowering Agenda.md | 122 ------------------ ...Flow, Evaluation Order, and Propagation.md | 86 ------------ ...les, Services, Contracts, and Callbacks.md | 88 ------------- ... Host Bindings, and Artifact Invariants.md | 89 ------------- ...kend VM Pipeline - Orchestration Agenda.md | 61 +++++++++ ...d Workshop 1 - IRBackend Input Contract.md | 68 ++++++++++ ...orkshop 2 - LowerToVM and IRVM Contract.md | 69 ++++++++++ ...code Marshaling and Runtime Conformance.md | 72 +++++++++++ docs/pbs/agendas/README.md | 7 + 9 files changed, 277 insertions(+), 385 deletions(-) delete mode 100644 docs/pbs/agendas/13. IR and Lowering Agenda.md delete mode 100644 docs/pbs/agendas/13.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md delete mode 100644 docs/pbs/agendas/13.3. IR and Lowering Workshop 3 - Callables, Services, Contracts, and Callbacks.md delete mode 100644 docs/pbs/agendas/13.4. IR and Lowering Workshop 4 - Builtins, Host Bindings, and Artifact Invariants.md create mode 100644 docs/pbs/agendas/18.0. Backend VM Pipeline - Orchestration Agenda.md create mode 100644 docs/pbs/agendas/18.1. Backend Workshop 1 - IRBackend Input Contract.md create mode 100644 docs/pbs/agendas/18.2. Backend Workshop 2 - LowerToVM and IRVM Contract.md create mode 100644 docs/pbs/agendas/18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md diff --git a/docs/pbs/agendas/13. IR and Lowering Agenda.md b/docs/pbs/agendas/13. IR and Lowering Agenda.md deleted file mode 100644 index 76bba2a7..00000000 --- a/docs/pbs/agendas/13. IR and Lowering Agenda.md +++ /dev/null @@ -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` diff --git a/docs/pbs/agendas/13.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md b/docs/pbs/agendas/13.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md deleted file mode 100644 index a89410ca..00000000 --- a/docs/pbs/agendas/13.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md +++ /dev/null @@ -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` diff --git a/docs/pbs/agendas/13.3. IR and Lowering Workshop 3 - Callables, Services, Contracts, and Callbacks.md b/docs/pbs/agendas/13.3. IR and Lowering Workshop 3 - Callables, Services, Contracts, and Callbacks.md deleted file mode 100644 index 63ce58f2..00000000 --- a/docs/pbs/agendas/13.3. IR and Lowering Workshop 3 - Callables, Services, Contracts, and Callbacks.md +++ /dev/null @@ -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` diff --git a/docs/pbs/agendas/13.4. IR and Lowering Workshop 4 - Builtins, Host Bindings, and Artifact Invariants.md b/docs/pbs/agendas/13.4. IR and Lowering Workshop 4 - Builtins, Host Bindings, and Artifact Invariants.md deleted file mode 100644 index 6b9f0f12..00000000 --- a/docs/pbs/agendas/13.4. IR and Lowering Workshop 4 - Builtins, Host Bindings, and Artifact Invariants.md +++ /dev/null @@ -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` diff --git a/docs/pbs/agendas/18.0. Backend VM Pipeline - Orchestration Agenda.md b/docs/pbs/agendas/18.0. Backend VM Pipeline - Orchestration Agenda.md new file mode 100644 index 00000000..1178c7ec --- /dev/null +++ b/docs/pbs/agendas/18.0. Backend VM Pipeline - Orchestration Agenda.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` + diff --git a/docs/pbs/agendas/18.1. Backend Workshop 1 - IRBackend Input Contract.md b/docs/pbs/agendas/18.1. Backend Workshop 1 - IRBackend Input Contract.md new file mode 100644 index 00000000..6bc69bf1 --- /dev/null +++ b/docs/pbs/agendas/18.1. Backend Workshop 1 - IRBackend Input Contract.md @@ -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` + diff --git a/docs/pbs/agendas/18.2. Backend Workshop 2 - LowerToVM and IRVM Contract.md b/docs/pbs/agendas/18.2. Backend Workshop 2 - LowerToVM and IRVM Contract.md new file mode 100644 index 00000000..301c4468 --- /dev/null +++ b/docs/pbs/agendas/18.2. Backend Workshop 2 - LowerToVM and IRVM Contract.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` + diff --git a/docs/pbs/agendas/18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md b/docs/pbs/agendas/18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md new file mode 100644 index 00000000..8493e357 --- /dev/null +++ b/docs/pbs/agendas/18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md @@ -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` + diff --git a/docs/pbs/agendas/README.md b/docs/pbs/agendas/README.md index fef94f28..80879afb 100644 --- a/docs/pbs/agendas/README.md +++ b/docs/pbs/agendas/README.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.