Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity

discussion framework migration

Browse Source
This commit is contained in:
bQUARKz 2026-03-26 20:17:12 +00:00
parent 928ea53eb8
commit e2de6c5913
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
105 changed files with 18 additions and 11420 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
docs/compiler/pbs/README.md
View File

@ -1,90 +1,28 @@
# PBS Documentation # PBS Documentation
This directory contains the working and normative documentation for PBS. This directory now contains durable PBS domain knowledge.
## Tree ## Tree
```text ```text
docs/pbs/ docs/compiler/pbs/
├── agendas/ └── learn/
├── decisions/
├── pull-requests/
└── specs/
``` ```
## Responsibilities Normative PBS specifications live in:
### `agendas/` - `docs/specs/compiler-languages/pbs/`
- `docs/specs/compiler/`
`agendas/` contains open topics. ## Purpose
`docs/compiler/pbs/learn/` is the long-term didactic layer for PBS.
Use it to: Use it to:
- record unresolved questions, - explain the final architectural model,
- define scope, dependencies, and non-goals, - preserve implementation-relevant lessons,
- structure discussion order, - summarize the reasoning that survived workflow closure,
- keep only active TODO topics visible. - and accelerate onboarding for future PBS work.
An agenda is a discussion artifact, not a final normative document. Transient workflow artifacts such as agendas, decision records, and execution plans are intentionally pruned from this directory once their knowledge has been consolidated here or into the normative specs.
Once a topic is settled, it should leave this directory.
### `decisions/`
`decisions/` contains closed decision records between discussion and spec integration.
Use it to:
- record the adopted decision clearly,
- capture invariants and architectural constraints,
- state what was explicitly left undecided,
- identify which specs must be updated,
- preserve traceability without turning specs into debate logs.
Architecture and decisions come before implementation.
### `specs/`
`specs/` contains the normative PBS corpus.
Use it to:
- consolidate the official PBS contract,
- integrate already-closed decisions in normative language,
- define precedence, scope, rules, and exit criteria,
- provide the baseline for implementation, verification, and conformance.
`docs/pbs/specs` is language-specific.
Cross-language acceptance specs live in `docs/general/specs`.
Specs must not operate as discussion backlogs.
If a point is still disputed or underspecified, it belongs in `agendas/` or `decisions/`, not directly in `specs/`.
### `pull-requests/`
`pull-requests/` contains self-contained change proposals for review.
Use it to:
- package a proposed change across multiple documents,
- explain motivation, target, method, acceptance criteria, and tests,
- make the review surface explicit before final integration,
- keep architectural and decision-level review ahead of implementation work.
If implementation reveals an unresolved ambiguity, stop and ask the question explicitly.
Do not infer missing architectural decisions during implementation.
## Recommended Flow
The preferred pipeline is:
1. `agendas/`: open and discuss unresolved topics.
2. `decisions/`: record the decision and its constraints.
3. `specs/`: integrate the closed decision into normative text.
4. `pull-requests/`: use when a change should be reviewed as a self-contained proposal before merge.
## Practical Rule
- `agendas/` stores open questions.
- `decisions/` stores closed answers.
- `specs/` stores the PBS-specific normative contract.
- `pull-requests/` stores reviewable change packages.

689
docs/compiler/pbs/agendas/19. Globals, Synthetic Module Init, and FRAME_RET Agenda.md
View File

@ -1,689 +0,0 @@
# Globals, Synthetic Module Init, and FRAME_RET Agenda
## Status
Open
## Purpose
Define how PBS should introduce runtime globals and lifecycle-driven executable bootstrap without changing the runtime contract in this phase.
This document is the umbrella agenda for topic `19`.
It exists to:
- keep the full problem framed in one place;
- define the dependency order between discussions;
- prevent later discussions from re-opening earlier boundaries casually;
- and provide the parent reference for any follow-up agendas created under this topic.
This agenda must converge on:
- the source-level model for mutable module storage;
- the lifecycle model for module init, optional program init, and frame execution;
- the ownership of `FRAME_RET` once the published entrypoint stops being the user's `frame()` directly;
- the migration path from explicit `FrontendSpec` entrypoint configuration to source-derived PBS entrypoint discovery.
## Domain Owner
`docs/compiler/pbs`
Este tema pertence ao domínio PBS do compiler porque afeta diretamente:
- a surface language de declarações top-level;
- a detecção de entrypoints pelo frontend PBS;
- o modelo de inicialização de módulo e programa;
- o lowering de entrypoint de frame;
- a relação entre entrypoint lógico do usuário e entrypoint publicado no artefato;
- o contrato interno entre frontend, `IRBackend`, `IRVM` lowering e bytecode final.
Nesta fase, o owner continua sendo `compiler/pbs` mesmo quando o resultado reutilizar capacidades já existentes da VM, porque a discussão é sobre como o compiler vai expor e orquestrar essas capacidades.
## Problema
Hoje o PBS não expõe variáveis globais mutáveis de módulo.
O topo do arquivo aceita `declare const`, mas `declare const` é compile-time e não storage runtime. Isso impede formas como:
```pbs
declare struct Vec2(x: int, y: int);
declare global origin: Vec2 = new Vec2(0, 0);
```
Ao mesmo tempo:
1. a VM já tem suporte operacional para globals por slot;
2. o compiler não modela globals no IR executável atual;
3. o entrypoint de frame do usuário hoje coincide, na prática, com a função que delimita o frame lógico;
4. o pipeline atual usa `FRAME_RET` no final desse fluxo de frame lógico.
5. a seleção do entrypoint ainda depende de configuração explícita em `FrontendSpec`, em vez de ser derivada da própria source language do PBS.
Se introduzirmos `declare global`, o compiler precisará definir:
1. como globals são inicializados;
2. quando essa inicialização roda;
3. como garantir execução uma única vez;
4. como conviver com um `init()` custom do usuário;
5. como detectar de forma canônica quais funções do usuário exercem os papéis de `init` e `frame`;
6. como preservar o contrato de frame lógico quando a função publicada deixar de ser a função `frame()` original do usuário.
## Contexto
O estado atual do sistema é:
- PBS proíbe `let` top-level e não expõe storage mutável de módulo;
- `declare const` é avaliado em compile time e pode ser inlinado/foldado;
- inicializadores não constantes como `new`, call sugar, `some`, `none`, `if`, `switch` e outras formas executáveis não pertencem ao modelo de `declare const`;
- a VM do runtime já possui `GetGlobal` e `SetGlobal`;
- o `IRBackend` executável atual modela locals, calls, jumps e literais, mas não modela globals;
- o entrypoint de frame hoje é tratado como raiz do frame lógico, inclusive para o ponto final onde `FRAME_RET` é emitido;
- o frontend PBS ainda depende de configuração explícita em `FrontendSpec` para saber qual callable é o entrypoint publicado;
- hoje isso aparece como acoplamento a nomes/configuração que deveriam ser deduzidos pela própria linguagem.
O cenário motivador é permitir globals de módulo no PBS sem exigir, nesta fase, mudança de runtime.
Também queremos aproveitar essa discussão para mover a detecção de entrypoint para a source language do PBS, usando atributos explícitos:
```pbs
[Init]
fn init() -> void {}
[Frame]
fn frame() -> void {}
```
Essa direção permitiria ao frontend PBS:
1. localizar explicitamente o init do usuário;
2. localizar explicitamente o frame root do usuário;
3. montar o wrapper sintético final sem depender de configuração paralela em `FrontendSpec`;
4. eliminar, nesta linha de evolução, a configuração explícita atual de entrypoint no registry/spec do frontend.
Esta agenda também cobre a extensão desse modelo para discutir:
1. se `[Init]` deve existir apenas como hook final de programa ou também como surface por módulo;
2. qual é exatamente o comportamento operacional de `[Frame]` como root lógico de frame do usuário;
3. como `[Init]` por módulo, `[Init]` final de programa, wrapper sintético e `FRAME_RET` se compõem sem ambiguidade.
Isso empurra a solução para o compiler:
1. synth de init por módulo;
2. synth de wrapper do frame published entrypoint;
3. eventual símbolo privado `boot_done`;
4. redefinição do ponto onde o frame lógico realmente termina;
5. detecção de `init`/`frame` a partir de atributos de source;
6. remoção progressiva das configs explícitas atuais em `FrontendSpec`.
## Inputs
Relevant inputs already present in the repository:
- `docs/vm-arch/ISA_CORE.md` already exposes `GET_GLOBAL` and `SET_GLOBAL`;
- `docs/compiler/pbs/specs/13. Lowering IRBackend Specification.md` currently requires a canonical executable entrypoint to be declared through `FrontendSpec`;
- `docs/compiler/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md` currently expects PBS v1 manifest `entrypoint` to align with frontend-declared `frame`.
The discussion here must preserve compatibility with those contracts unless it explicitly proposes the propagation work needed to evolve them.
## Core Questions
1. PBS deve introduzir `declare global` como declaração top-level distinta de `declare const`?
2. `declare global` deve aceitar inicializadores executáveis como `new Vec2(...)`, calls e outras expressões lowerables?
3. O compiler deve sintetizar um module init por módulo que contenha `declare global`?
4. A inicialização deve rodar eager no boot lógico do programa ou lazy no primeiro frame?
5. Deve existir um `init()` custom do usuário que roda depois de todos os module inits e antes do primeiro `frame()`?
6. O PBS deve introduzir atributos explícitos `[Init]` e `[Frame]` para identificar as funções corretas do usuário?
7. A descoberta de entrypoint no frontend PBS deve deixar de depender de configuração explícita em `FrontendSpec`?
8. `[Init]` deve poder existir também em escopo/módulo de forma declarativa para orientar module init explícito, ou o compiler deve manter module init sempre totalmente sintético?
9. Qual é o contrato preciso de comportamento de `[Frame]` no PBS: callable obrigatório, assinatura fixa, frequência esperada e relação com o frame lógico publicado?
10. O published frame entrypoint deve passar a ser um wrapper sintético, por exemplo `__pbs_frame()`, em vez do `frame()` do usuário?
11. `FRAME_RET` deve continuar significando "fim do frame lógico" e apenas mudar de owner, saindo da função do usuário para o wrapper sintético?
12. Como o compiler deve tratar ordem topológica, dependências e ciclos entre globals de módulos distintos?
13. Qual política vale quando algum module init ou `init()` do usuário falha: retry no próximo frame, fail-fast, ou outra forma?
14. Globals exportados por `mod.barrel` devem se comportar como storage compartilhado de módulo ou como snapshot/importação por valor?
## Inputs Already Fixed Elsewhere
Os seguintes pontos já parecem fixos ou fortemente estabelecidos e não devem ser contraditos nesta agenda:
- a VM já suporta globals em nível de bytecode/execução;
- `declare const` não é storage mutável/runtime-initialized;
- o runtime já sabe executar um entrypoint published por frame;
- `FRAME_RET` já é usado como marcador do fim de um frame lógico;
- o frontend PBS hoje ainda carrega configuração explícita de entrypoint fora da source language;
- nesta fase queremos evitar mudanças novas no runtime e concentrar a evolução no compiler.
## Decisions To Produce
Como umbrella agenda, esta agenda não deve tentar fechar toda a solução normativa de uma vez.
Ela deve sair com:
1. a decomposição oficial do tema em discussões derivadas;
2. a ordem canônica dessas discussões;
3. os inputs e outputs esperados de cada boundary;
4. a lista de artefatos que não podem ser editados antes do boundary anterior fechar.
Depois que as discussões derivadas fecharem, o conjunto deve produzir direção suficiente para virar uma `decision` cobrindo pelo menos:
1. a surface syntax e o modelo semântico de `declare global`;
2. o modelo de bootstrap entre module init sintético, `[Init]` de programa e `[Frame]`;
3. o owner real do frame lógico publicado e o ponto correto de emissão de `FRAME_RET`;
4. a política de descoberta de entrypoint a partir da source language do PBS;
5. a política de ordenação, ciclos e falhas para globals e module init;
6. a política de imports/exports para globals entre módulos.
## Options
### Option A
Adicionar `declare global`, introduzir `[Init]` e `[Frame]` como superfícies explícitas para lifecycle/entrypoint, discutir `[Init]` final vs `[Init]` por módulo, gerar module init sintético por módulo, gerar wrapper sintético de frame published entrypoint e mover o `FRAME_RET` para esse wrapper.
### Option B
Adicionar `declare global`, mas exigir init totalmente estático ou restrito, sem `init()` custom do usuário e sem wrapper published separado do `frame()` atual.
### Option C
Não adicionar `declare global` agora; manter apenas `declare const` e postergar a discussão até existir um modelo maior de bootstrap/program lifecycle.
### Option D
Adicionar `declare global`, mas exigir lazy materialization no primeiro acesso em vez de module init explícito por ordem topológica.
## Tradeoffs
### Option A
- Prós:
- modelo explícito e fácil de explicar;
- acomoda `declare global` com inicializadores realmente executáveis;
- faz o PBS declarar na própria linguagem quais são os callables de `init` e `frame`;
- abre espaço para discutir de forma unificada `init` por módulo, `init` final e root de frame;
- permite `init()` custom do usuário sem mudar o runtime;
- preserva o significado de `FRAME_RET` como fim do frame lógico;
- remove um acoplamento indesejado entre frontend PBS e configuração manual de entrypoint em `FrontendSpec`.
- Contras:
- exige nova modelagem no compiler para globals, init synthesis e published frame wrapper;
- exige regras novas de atributo e validação de unicidade para `[Init]` e `[Frame]`;
- obriga decisão clara sobre ordem, ciclos e falhas;
- muda a relação atual entre `frame()` do usuário e entrypoint publicado.
### Option B
- Prós:
- escopo menor;
- reduz a superfície de lifecycle;
- pode evitar parte da complexidade de wrapper e boot state.
- Contras:
- resolve mal o caso motivador com `new Vec2(...)`;
- produz uma feature de globais com restrição semântica forte demais;
- deixa o `init()` do usuário para outra rodada e pode forçar redesign posterior.
### Option C
- Prós:
- nenhum risco imediato em pipeline/backend;
- preserva o estado atual do compiler.
- Contras:
- não resolve o caso desejado;
- mantém uma lacuna entre capacidade da VM e surface language do PBS;
- posterga um problema arquitetural que já apareceu de forma concreta.
### Option D
- Prós:
- evita bootstrap eager explícito;
- pode reduzir custo de init em módulos não usados.
- Contras:
- complica determinismo e observabilidade;
- torna mais difícil explicar dependências entre módulos;
- aumenta risco semântico para reentrância, ciclos e ordem de efeitos;
- parece desnecessariamente sofisticado para v1.
## Recommendation
Seguir com a **Option A**.
Direção recomendada para discussão:
1. introduzir `declare global` como nova declaração top-level distinta de `declare const`;
2. permitir inicializadores executáveis lowerables, incluindo `new` e calls compatíveis com o modelo de lowering executável;
3. sintetizar um module init por módulo owner de globals;
4. ordenar os module inits de forma determinística e topológica;
5. introduzir `[Init]` e `[Frame]` como superfícies explícitas de detecção do init/frame do usuário;
6. remover da evolução do PBS a dependência de configuração explícita de entrypoint em `FrontendSpec`, migrando a seleção para a análise da source language;
7. discutir explicitamente se `[Init]` por módulo será uma surface do usuário ou se módulo continuará com init apenas sintético;
8. permitir um `init()` custom opcional do usuário, executado depois de todos os module inits;
9. publicar um wrapper sintético de frame, por exemplo `__pbs_frame()`, como verdadeiro frame root;
10. tratar `frame()` do usuário como callable normal invocado por esse wrapper;
11. manter `FRAME_RET` como marcador do fim do frame lógico, mas emitido no wrapper sintético publicado em vez de no `frame()` do usuário;
12. manter toda a primeira fase restrita ao compiler e ao backend pipeline, sem novos requisitos para o runtime além dos contratos já existentes.
Essa recomendação ainda deixa alguns pontos para fechamento na `decision`, mas já estabelece um shape arquitetural coerente:
- storage global pertence ao módulo owner;
- bootstrap observável pertence ao compiler, não ao runtime;
- `frame()` do usuário deixa de ser o entrypoint publicado e passa a ser o root lógico invocado pelo wrapper;
- `FRAME_RET` continua significando fim do frame lógico, apenas com novo owner sintético;
- a seleção de entrypoint deixa de ser configuração paralela e vira semântica explícita da linguagem.
## Open Questions
1. O nome surface deve ser exatamente `declare global`, ou outra forma top-level?
2. Globals devem exigir initializer obrigatório em v1, ou existirão shells reservados parecidos com builtin const?
3. `[Init]` e `[Frame]` devem ser atributos reservados do PBS ou outra forma de marker surface?
4. `[Init]` deve exigir assinatura fixa `fn init() -> void`?
5. `[Frame]` deve exigir assinatura fixa `fn frame() -> void`?
6. Deve existir no máximo um `[Init]` e um `[Frame]` por programa, por módulo owner, ou por outro escopo?
7. Module init deve permanecer sempre sintético em v1, ou o usuário pode anotar hooks por módulo em alguma forma futura?
8. A política de falha de init deve ser fail-fast definitivo no boot, ou existe algum caso legítimo para retry controlado?
9. Reexport de globals entre módulos deve preservar identidade de storage do owner original ou materializar aliases/import bindings sem storage próprio?
10. O manifest `entrypoint` deve continuar expondo `frame` por compatibilidade nominal ou passar a refletir o símbolo sintético publicado?
## Main Difficulties
Os principais pontos de dificuldade desta agenda não são sintáticos; eles estão na composição entre contratos já existentes.
### 1. `declare global` colide com o recorte atual de `declare const`
Hoje a semântica estática do PBS fixa que:
- `declare const` entra no value namespace;
- `declare const` não materializa storage mutável runtime;
- inicializadores de `declare const` pertencem a um subset estritamente compile-time;
- dependências entre `declare const` são acíclicas e resolvidas por análise de dependência, não por ordem textual.
Introduzir `declare global` exige decidir o que é reaproveitado desse modelo e o que deixa de valer:
- namespace e visibilidade podem reaproveitar parte do modelo atual;
- constant evaluation não pode ser reutilizada como está;
- o modelo de dependência deixa de ser apenas compile-time e passa a produzir efeitos runtime.
### 2. A surface de atributos hoje tem um conjunto reservado fechado
O PBS já trata atributos como metadata compile-time com lowering explícito apenas quando outra spec define esse efeito.
Isso é favorável para `[Init]` e `[Frame]`, mas cria trabalho em três frentes:
- reservar novos atributos no conjunto normativo;
- definir targets válidos, unicidade e diagnóstico;
- definir o lowering sem deixar atributos "soltos" como metadata sem efeito operacional claro.
### 3. O entrypoint publicado hoje ainda está acoplado ao `FrontendSpec`
Existe uma obrigação atual em `13. Lowering IRBackend Specification.md` para o frontend declarar um `EntrypointRef` canônico.
A agenda 19 quer mover a descoberta para a source language, mas isso abre uma transição delicada:
- PBS precisa derivar esse `EntrypointRef` da source language;
- o contrato de `IRBackend` não deve perder determinismo;
- a migração não pode deixar coexistirem por muito tempo duas autoridades independentes para entrypoint.
### 4. O manifest ainda assume `frame` como callable publicado
`7. Cartridge Manifest and Runtime Capabilities Specification.md` hoje sugere alinhamento nominal entre manifest `entrypoint` e callable `frame`.
Se o compiler publicar `__pbs_frame()`:
- ou o manifest passa a refletir o símbolo sintético real;
- ou o manifest preserva um nome lógico enquanto o símbolo real do artefato muda;
- ou a pipeline passa a distinguir entrypoint lógico e entrypoint físico.
Sem fechar isso, a solução de wrapper fica tecnicamente incompleta.
### 5. `FRAME_RET` hoje coincide com o fim do callable do usuário
O ponto difícil não é só "mover um opcode". É redefinir qual callable delimita semanticamente o frame lógico:
- `frame()` do usuário continua sendo apenas código de frame;
- o wrapper sintético vira o owner do frame published entrypoint;
- `FRAME_RET` continua com o mesmo significado semântico, mas sua posição material muda.
Isso afeta lowering, testes de conformance e a forma de explicar o modelo da linguagem.
### 6. Globals intermodulares introduzem um problema novo de identidade e ordem
Hoje `declare const` exportado via `mod.barrel` é simples porque não há storage mutável compartilhado.
Com `declare global`, a agenda precisa fechar:
- quem é o owner real do storage;
- o que um import recebe: binding para o owner ou cópia/snapshot;
- como ciclos entre módulos são detectados;
- se init pode ler globals de módulos predecessores;
- qual é a ordem determinística entre módulos quando há efeitos de inicialização.
### 7. A política de falha deixa de ser apenas rejeição de build
Hoje boa parte do pipeline falha antes da emissão.
Com module init e `init()` do usuário, surge um problema runtime-observable:
- o que acontece quando o boot parcial falha;
- se o programa entra em estado terminal;
- se existe retry;
- como isso se relaciona com o fato de `FRAME_SYNC` permanecer o safepoint normativo.
## Work Boundaries
Para manter a agenda executável e evitar mistura de artefatos, o trabalho pode ser separado nos seguintes boundaries.
### Boundary A. Surface Language and AST
Owner principal: syntax + AST.
Inclui:
- gramática de `declare global`;
- superfície de atributos `[Init]` e `[Frame]`;
- targets permitidos desses atributos;
- novos nós ou flags obrigatórios no AST para globals e lifecycle markers.
Pergunta de fechamento:
- o parser apenas aceita as superfícies ou já impõe parte das restrições estruturais de target/shape?
### Boundary B. Static Semantics and Linking
Owner principal: static semantics + linking.
Inclui:
- namespace e visibilidade de `declare global`;
- regras de initializer obrigatório ou opcional;
- compatibilidade de tipo do initializer;
- unicidade e assinatura válida para `[Init]` e `[Frame]`;
- regras de import/export/barrel para globals;
- detecção de ciclos de dependência entre globals;
- política de identidade do storage através de imports e reexports.
Pergunta de fechamento:
- globals entram no mesmo value namespace de `let`/`declare const` ou exigem distinção semântica adicional apesar do namespace compartilhado?
### Boundary C. Dynamic Semantics and Lifecycle Model
Owner principal: dynamic semantics.
Inclui:
- ordem observável entre module init, `[Init]` de programa e `[Frame]`;
- definição de boot one-shot;
- política de falha de init;
- contrato semântico de `[Frame]` como raiz lógica do tick/frame do usuário;
- relação entre frame lógico do usuário e entrypoint efetivamente publicado.
Pergunta de fechamento:
- o programa tem dois conceitos distintos, `logical frame root` e `published runtime entrypoint`, ou a spec tenta esconder essa distinção do usuário?
### Boundary D. IR and Backend Lowering
Owner principal: lowering executável.
Inclui:
- representação de globals no `IRBackend` ou boundary imediatamente anterior;
- synthesis de module init;
- synthesis de wrapper published entrypoint;
- materialização do guard one-shot de boot;
- reposicionamento do `FRAME_RET`;
- preservação do `EntrypointRef` canônico para o restante do backend.
Pergunta de fechamento:
- globals entram como primitivo explícito no IR ou aparecem apenas em lowering posterior antes de IRVM/bytecode?
### Boundary E. Artifact and Manifest Publication
Owner principal: artifact contracts.
Inclui:
- nome do entrypoint exposto no manifest;
- relação entre callable do usuário, símbolo sintético e entrypoint published;
- compatibilidade com o contrato atual do cartridge manifest;
- possíveis ajustes na leitura de tooling sobre qual callable é o entrypoint "real".
Pergunta de fechamento:
- o manifest publica identidade lógica da linguagem ou identidade física do artefato executável?
### Boundary F. Diagnostics and Conformance
Owner principal: diagnostics + fixture model.
Inclui:
- diagnósticos para target inválido de `[Init]` e `[Frame]`;
- duplicidade ou ausência de markers obrigatórios;
- initializer inválido de `declare global`;
- ciclos intra/inter-módulo;
- imports/reexports ilegais de globals;
- fixture coverage para init ordering, wrapper published entrypoint e `FRAME_RET`.
Pergunta de fechamento:
- quais erros pertencem ao frontend/linking e quais só podem ser cobertos por fixtures de toolchain completo?
## Discussion Order
As discussões derivadas desta umbrella agenda devem seguir a ordem abaixo.
O objetivo da ordem é simples:
- fechar primeiro autoridade semântica e surface;
- depois fechar comportamento observável;
- só então descer para lowering, artefato publicado e conformance.
### Stage 1. Globals Surface and Static Identity
Boundary owner:
- `Boundary A. Surface Language and AST`
- `Boundary B. Static Semantics and Linking`
Esta discussão deve fechar primeiro porque todas as outras dependem da definição do que é um global no PBS.
Ela precisa decidir:
- a forma exata de `declare global`;
- initializer obrigatório ou opcional;
- namespace, visibilidade e barrel/export/import;
- identidade do storage owner;
- política de reexport;
- ciclos e dependências entre globals em nível de linking/static semantics.
Sem esse fechamento:
- lifecycle ainda não sabe o que precisa inicializar;
- lowering ainda não sabe que entidade precisa materializar;
- manifest ainda não sabe se está publicando símbolos que dependem de storage global importado.
### Stage 2. Lifecycle Markers and Program Bootstrap Semantics
Boundary owner:
- `Boundary C. Dynamic Semantics and Lifecycle Model`
Esta discussão vem depois de Stage 1 porque init e frame só fazem sentido quando o modelo de globals já estiver fixado.
Ela precisa decidir:
- se `[Init]` e `[Frame]` entram como superfícies oficiais;
- unicidade e assinatura desses markers;
- ordem entre module init, `[Init]` de programa e `[Frame]`;
- política de boot one-shot;
- política de falha;
- papel semântico exato de `frame()` do usuário.
Sem esse fechamento:
- o wrapper sintético não tem contrato observável estável;
- `FRAME_RET` não tem owner definido;
- qualquer modelagem de IR corre risco de materializar o comportamento errado.
### Stage 3. Published Entrypoint, Wrapper Ownership, and `FRAME_RET`
Boundary owner:
- `Boundary C. Dynamic Semantics and Lifecycle Model`
- `Boundary D. IR and Backend Lowering`
- `Boundary E. Artifact and Manifest Publication`
Esta discussão depende de Stage 2 porque ela não decide mais "o que é lifecycle"; ela decide como lifecycle é publicado.
Ela precisa decidir:
- se o published entrypoint é um wrapper sintético;
- qual é a relação entre `frame()` do usuário e esse wrapper;
- onde `FRAME_RET` passa a ser emitido;
- se o manifest expõe entrypoint lógico, entrypoint físico ou ambos;
- como o `EntrypointRef` do frontend continua determinístico durante a transição.
Sem esse fechamento:
- não existe contrato estável para lowering final;
- specs de manifest e `IRBackend` ficam em tensão;
- o tooling pode continuar com duas autoridades concorrentes para entrypoint.
### Stage 4. IR Representation and Lowering Mechanics
Boundary owner:
- `Boundary D. IR and Backend Lowering`
Esta discussão vem depois de Stage 3 porque a forma do IR depende do que exatamente precisa ser publicado e executado.
Ela precisa decidir:
- se globals entram como primitivo explícito do IR ou apenas em lowering posterior;
- como module init é representado;
- como o guard de boot é materializado;
- como o wrapper published entrypoint é emitido;
- como `FRAME_RET` é reposicionado mantendo o mesmo significado.
Sem esse fechamento:
- código pode ser implementado cedo demais sobre contratos ainda móveis;
- a propagação para specs gerais de lowering fica prematura;
- testes de backend podem congelar um shape errado.
### Stage 5. Diagnostics, Gates, and Conformance Coverage
Boundary owner:
- `Boundary F. Diagnostics and Conformance`
Esta discussão deve vir por último porque ela consolida o que as anteriores já fixaram.
Ela precisa decidir:
- catálogo mínimo de diagnósticos novos;
- divisão entre erro de syntax/AST, linking/static semantics, lowering e toolchain;
- fixtures obrigatórios para globals, lifecycle, wrapper e entrypoint publication;
- critérios de aceite para a migração de `FrontendSpec` entrypoint config para source-derived entrypoint discovery.
Fazer isso antes cria dois riscos:
- congelar diagnósticos para regras ainda instáveis;
- ou escrever fixtures de conformance que depois precisam ser reabertas por mudança arquitetural.
## Derived Agenda Outline
Se quisermos quebrar a umbrella agenda em agendas filhas, a ordem recomendada é:
1. `19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda`
2. `19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda`
3. `19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda`
4. `19.4. Globals and Lifecycle Lowering to IRBackend/IRVM Agenda`
5. `19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda`
Cada agenda filha deve declarar explicitamente:
- que deriva da umbrella agenda `19`;
- quais stages anteriores já são input fixo;
- e quais outputs ela precisa entregar para a agenda seguinte.
## Boundary Locking Rules
Para evitar que discussões posteriores prejudiquem as anteriores, esta umbrella agenda fixa as seguintes regras de sequenciamento:
1. `19.2` não redefine surface syntax ou identidade de globals já fechadas em `19.1`.
2. `19.3` não redefine o significado semântico de `[Init]`, `[Frame]` ou boot ordering já fechados em `19.2`.
3. `19.4` não reabre decisões de linguagem ou de lifecycle; ela apenas escolhe a representação e o mecanismo de lowering compatíveis com elas.
4. `19.5` não reabre arquitetura; ela consolida diagnostics, manifest propagation e coverage.
5. Qualquer ponto que force reabertura de stage anterior deve voltar explicitamente para a agenda filha owner correta, em vez de ser resolvido informalmente na etapa posterior.
## Likely Propagation Targets
Mesmo sem virar `decision` ainda, esta agenda já mostra impacto provável nos seguintes artefatos.
### PBS Specs
- `3. Core Syntax Specification.md`
- `4. Static Semantics Specification.md`
- `9. Dynamic Semantics Specification.md`
- `11. AST Specification.md`
- `12. Diagnostics Specification.md`
- `13. Lowering IRBackend Specification.md`
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
### Cross-Domain / VM Architecture
- `docs/vm-arch/ISA_CORE.md` provavelmente não precisa mudar em capability, mas precisa ser referenciado explicitamente como base de `GET_GLOBAL`/`SET_GLOBAL`;
- specs gerais de lowering fora de `docs/compiler/pbs` podem precisar propagação posterior se `IRBackend` ganhar representação explícita de globals ou novo contrato para entrypoint published.
### Compiler / Implementation Areas
- parser e AST model;
- linking/resolution;
- static semantics;
- IR model do frontend PBS;
- executable lowering para `IRBackend` e `IRVM`;
- montagem do manifest/cartridge metadata;
- suites de fixture de frontend, lowering e toolchain.
## Boundary Risks
Se os boundaries acima não forem respeitados, os riscos mais prováveis são:
1. criar `declare global` como açúcar superficial sem lifecycle coerente;
2. introduzir `[Init]` e `[Frame]` sem autoridade clara sobre `FrontendSpec`;
3. mover `FRAME_RET` sem redefinir com precisão o owner do frame lógico;
4. resolver globals intra-módulo mas deixar imports/reexports semanticamente ambíguos;
5. fechar a solução do compiler sem fechar o contrato do manifest;
6. misturar nesta agenda decisões de produto/runtime que deveriam continuar fora de escopo.
## Expected Spec Material
Se esta agenda virar `decision`, a propagação esperada deve atingir pelo menos:
- spec de declarações top-level do PBS para introduzir `declare global`;
- spec de lifecycle/entrypoint attributes para `[Init]` e `[Frame]`;
- spec de lowering executável/`IRBackend` para module init synthesis, wrapper published entrypoint e ownership de `FRAME_RET`;
- spec de cartridge manifest para esclarecer a relação entre entrypoint lógico do usuário e entrypoint publicado no artefato;
- diagnósticos de validação para unicidade, assinatura inválida, ciclos de init e uso incorreto de globals.
## Non-Goals
Esta agenda não deve:
1. redesenhar o runtime ou introduzir novas instruções de VM;
2. escrever a spec normativa final de globals e lifecycle;
3. redefinir o modelo geral de módulos do compiler fora do necessário para globals/init;
4. resolver todos os possíveis hooks futuros de programa além de `[Init]` e `[Frame]`;
5. discutir otimizações de performance de init além do necessário para garantir semântica determinística.
## Next Step
Usar esta agenda como parent reference e abrir as agendas filhas na ordem abaixo:
1. `19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda`
2. `19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda`
3. `19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda`
4. `19.4. Globals and Lifecycle Lowering to IRBackend/IRVM Agenda`
5. `19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda`
Somente depois do fechamento dessas agendas derivadas esta linha deve virar uma `decision` consolidada em `docs/compiler/pbs/decisions`.

406
docs/compiler/pbs/agendas/19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda.md
View File

@ -1,406 +0,0 @@
# PBS Globals Surface, Identity, and Module Boundaries Agenda
## Status
Open
## Parent Agenda
This agenda derives from:
- `19. Globals, Synthetic Module Init, and FRAME_RET Agenda`
This is the first derived discussion under umbrella topic `19`.
## Purpose
Define the source-level and module-level model for PBS runtime globals before lifecycle, entrypoint publication, or lowering details are discussed.
This agenda exists to close the semantic base for:
- the `declare global` surface;
- storage ownership;
- import/export/alias behavior;
- and dependency/cycle rules at module boundary level.
Later agendas under topic `19` must treat the outputs of this agenda as fixed input.
## Domain Owner
`docs/compiler/pbs`
Este tema pertence ao domínio PBS do compiler porque define surface language, linking semantics e boundaries de módulo para uma nova categoria de declaração top-level.
## Context
Hoje o PBS já possui `declare const`, mas esse surface é estritamente compile-time:
- `declare const` entra no value namespace;
- `declare const` continua reservado a valores imutáveis que não representam storage mutável de módulo;
- `declare const` não materializa storage mutável runtime;
- o initializer de `declare const` pertence a um subset constante;
- dependências de `declare const` são resolvidas por análise de dependência compile-time.
Ao mesmo tempo:
- a VM já expõe `GET_GLOBAL` e `SET_GLOBAL`;
- a linguagem ainda não expõe globals mutáveis de módulo;
- `mod.barrel` hoje já governa export/import de `const`, `fn`, tipos e outras famílias de declaração;
- não existe ainda contrato explícito para storage compartilhado intermodular em source PBS.
Antes de discutir init, frame wrapper ou `FRAME_RET`, precisamos fechar o que um `global` é no modelo da linguagem.
## Inputs Already Fixed Elsewhere
Os seguintes inputs já parecem fixos e não devem ser reabertos aqui:
- `declare const` não é storage mutável/runtime-initialized;
- `declare const` continua semanticamente separado de `declare global`;
- `declare const` continua voltado a valores imutáveis e não deve ser reutilizado como surface de global;
- modules e globals devem compartilhar o mesmo tipo estrutural de análise de dependência;
- essa análise comum deve vir de um refactor do algoritmo atual de modules para um `DependencyGraphAnaliser` em `util.structures` na infra;
- top-level executable statements continuam proibidos;
- a VM já suporta globals por slot;
- esta fase ainda é compiler-driven e não deve exigir capability nova do runtime;
- barrel continua sendo a fonte de visibilidade entre módulos.
## Decisions To Produce
Esta agenda deve produzir direção suficiente para fechar:
1. a surface exata de `declare global`;
2. a obrigatoriedade de initializer em todos os globals de v1;
3. o namespace ocupado por globals;
4. a política de visibility/barrel para globals;
5. a identidade do storage owner;
6. a semântica de import, export e alias;
7. a política de dependência e ciclos entre globals.
## Core Questions
1. PBS deve introduzir exatamente `declare global name: T = expr;` como nova forma top-level?
2. `declare global` deve exigir type annotation explícita em todos os casos?
3. Quais formas de initializer executável são admissíveis para `declare global` em v1?
4. `declare global` entra no mesmo value namespace de `let` e `declare const`?
5. O barrel deve ganhar uma entrada `global` distinta?
6. Um `global` importado referencia sempre o storage do módulo owner original?
7. Como imports de globals usam alias quando necessário sem introduzir shadowing?
8. O que é proibido em imports de globals para evitar ambiguidade?
9. A dependência entre globals deve ser modelada por grafo determinístico semelhante ao de `declare const`, mas agora com efeito runtime?
10. Como ciclos entre globals intra-módulo e inter-módulo devem ser detectados e reportados?
11. Como o grafo de globals mapeia para o `DependencyGraphAnaliser` comum sem perder owner canônico nem attribution?
## Options
### Option A
Adicionar `declare global` como nova declaração top-level explícita, com type annotation obrigatória, initializer obrigatório em v1, entry própria `global` em barrel, sem reexport e identidade de storage sempre pertencente ao módulo owner original.
### Option B
Adicionar `declare global`, mas permitir globals sem initializer em v1 e tratar inicialização default como parte do modelo base.
## Tradeoffs
### Option A
- Prós:
- semântica explícita e fácil de ensinar;
- evita ambiguidade entre constant value e mutable storage;
- força o barrel e os imports a refletirem corretamente a nova categoria declarativa;
- reduz risco de globals parcialmente formados sem política clara de init.
- Contras:
- aumenta a superfície da linguagem;
- exige atualização de parser, AST, linking e barrel matching.
### Option B
- Prós:
- maior flexibilidade futura;
- permite reservar globals antes de decidir a inicialização concreta.
- Contras:
- empurra complexidade para lifecycle e diagnostics;
- enfraquece a previsibilidade de v1;
- cria edge cases sobre leitura antes de materialização.
## Recommendation
Seguir com a **Option A**.
Direção recomendada:
1. `declare global` deve ser uma declaração top-level distinta de `declare const`;
2. type annotation explícita deve ser obrigatória;
3. initializer deve ser obrigatório em v1;
4. `declare const` não deve ser reutilizado para globals e continua reservado a valores imutáveis;
5. globals devem entrar no value namespace, mas com categoria declarativa distinta;
6. barrel deve refletir essa distinção explicitamente com `mod global` e `pub global`;
7. PBS não deve introduzir reexport de globals nesta linha;
8. imports de globals devem preservar a identidade do storage owner original e usar alias quando necessário;
9. shadowing entre imports de `fn`, `service`, `global` e `const` deve ser compile-time error;
10. dependências entre globals devem ser determinísticas e diagnosticáveis.
Também fica registrado nesta agenda um direction técnico já decidido:
1. modules e globals usarão o mesmo tipo estrutural de análise de dependência;
2. isso deve nascer de um refactor do algoritmo atual de modules;
3. o artefato comum deve viver na infra como `DependencyGraphAnaliser` em `util.structures`;
4. cada domínio continua responsável por construir seus próprios nós canônicos, suas arestas e seu mapeamento de diagnóstico;
5. o que é compartilhado é o kernel estrutural de ordenação topológica e detecção de ciclos, não a semântica específica de cada grafo.
## Global Dependencies
O ponto mais sensível desta agenda é a dependência entre globals.
Com `declare const`, dependência significa apenas ordem de avaliação compile-time.
Com `declare global`, dependência passa a significar ordem de materialização runtime, identidade de storage e risco real de efeito parcial.
Exemplos do tipo de dependência que passam a existir:
```pbs
declare global a: int = 1;
declare global b: int = a + 1;
```
Aqui `b` depende de `a` porque o initializer de `b` lê o valor de `a`.
```pbs
declare global origin: Vec2 = new Vec2(0, 0);
declare global camera: Camera = new Camera(origin);
```
Aqui `camera` depende de `origin` porque o initializer usa o valor já materializado de outro global.
Quando há múltiplos módulos, o problema cresce:
```pbs
// module A
declare global seed: int = 7;
// module B
import { seed } from @project:A;
declare global rng: Rng = new Rng(seed);
```
Agora a ordem de materialização não é apenas intra-módulo. Ela atravessa módulos e precisa continuar determinística.
### Dependency Kinds
Esta agenda precisa distinguir pelo menos três formas de dependência:
1. dependência local entre globals do mesmo módulo;
2. dependência intermodular por import de global do módulo owner original;
3. dependência indireta por alias de import, onde o nome local muda, mas o owner do storage permanece igual.
### Main Problems
Os principais problemas de dependência de globals são:
1. ordem de inicialização deixa de poder depender de ordem textual do arquivo;
2. imports com alias podem esconder o owner real do storage;
3. leitura de global ainda não materializado precisa ser proibida por modelo, não tratada como comportamento oportunista;
4. ciclos deixam de ser apenas "ciclos de expressão" e passam a ser ciclos de materialização runtime;
5. o grafo de dependências pode cruzar múltiplos módulos e aliases, o que piora atribuição de diagnóstico.
### Risks
Se a política de dependência de globals ficar frouxa, os riscos são altos:
1. inicialização parcialmente observável:
um global pode ler outro antes de ele existir semanticamente;
2. ordem acidental por arquivo:
a implementação pode acabar usando ordem textual ou ordem de carregamento do projeto, o que quebra determinismo;
3. aliasing ambíguo:
aliases de import podem parecer símbolo novo quando na verdade são só outro nome para o mesmo owner;
4. ciclos opacos:
`A -> B -> C -> A` pode ficar escondido atrás de import e alias, dificultando explicação ao usuário;
5. bootstrap contaminado:
se essa agenda deixar dependência frouxa, a 19.2 herda um lifecycle impossível de explicar;
6. lowering prematuro:
se o compiler materializar a ordem no backend sem política semântica firme, a arquitetura congela cedo demais.
### Direction for Discussion
Minha direção recomendada para dependências de globals nesta agenda é:
1. toda leitura de outro global no initializer cria uma edge explícita no grafo de dependência;
2. a resolução do grafo deve ser determinística e independente de source-file order;
3. imports e aliases devem preservar o owner original do storage no grafo;
4. ciclos entre globals devem ser erro estático, não comportamento runtime com retry ou valor parcial;
5. a agenda deve deixar claro que esta política fecha apenas identidade e dependência;
boot ordering completo continua pertencendo à `19.2`.
### Structural Reuse Decision
Esta agenda também registra uma decisão arquitetural de implementação que afeta a evolução futura:
1. o algoritmo atual usado para dependência de modules deve ser refatorado em um componente estrutural reutilizável;
2. esse componente comum deve se chamar `DependencyGraphAnaliser`;
3. ele deve viver em `util.structures` na infra;
4. modules e globals devem consumir esse mesmo componente estrutural;
5. a semântica que descobre edges continua separada por domínio.
Isso significa:
- o import graph de modules e o init graph de globals não serão o mesmo grafo semântico;
- mas ambos deverão usar o mesmo kernel estrutural para:
- topological ordering,
- cycle detection,
- e suporte a diagnóstico determinístico.
## Current Direction
Os pontos abaixo já podem ser tratados como direção fechada desta agenda, salvo objeção nova forte:
1. a surface correta é `declare global BLA: int = 1;`;
2. type annotation é obrigatória, como em `declare const`;
3. initializer é sempre obrigatório;
4. globals entram no value namespace como categoria declarativa distinta;
5. `mod.barrel` deve expor globals com entradas `mod global Name;` e `pub global Name;`;
6. imports de globals usam o mesmo esquema de alias quando necessário;
7. PBS não introduz reexport de globals nesta linha;
8. shadowing entre imports de `fn`, `service`, `global` e `const` é compile-time error e deve ser resolvido com alias;
9. detecção de dependência, ordenação e ciclo deve nascer do `DependencyGraphAnaliser` comum, com contexto semântico próprio de globals.
Também fica explicitado o modelo de namespace:
1. globals entram no value namespace;
2. `declare const`, `declare global` e o singleton canônico de `service` convivem no espaço nominal de valores;
3. `fn`, `service`, `global` e `const` não podem introduzir o mesmo nome visível no mesmo scope de resolução;
4. essa colisão é erro de compile time, mesmo quando a ambiguidade nasce de import;
5. `locals > struct/class members > globals`, inclusive quando o global veio por import.
## Remaining Open Points
Com a direção já consolidada nesta agenda, não restam pontos substantivos em aberto dentro do boundary de `19.1`.
Os temas adicionais de lifecycle seguem encaminhados para a `19.2`.
## Initializer Boundary
Esta agenda também precisa deixar explícita a fronteira entre:
1. init da declaração `global`;
2. init por módulo;
3. init de projeto.
Direção recomendada:
- o initializer de `declare global` deve permanecer restrito e simples;
- ele existe para materializar o valor inicial da storage de módulo;
- ele não deve carregar lógica procedural maior nem depender de top-level `fn`;
- lógica adicional de setup pertence ao init por módulo;
- setup de programa pertence ao init de projeto.
Com isso, a linha proposta fica:
1. init da global:
permite primitivas, operações simples com valor, member access com valor nessa etapa, `new`, e leitura de outras globals compatíveis com o dep graph;
2. init do módulo:
permite lógica adicional de conveniência e mutações nas globals do próprio módulo após a materialização inicial;
3. init do projeto:
permite setup do projeto como um todo, depois do fechamento do estado de módulo necessário.
### Consequence for `fn` in Global Initializers
Seguindo essa separação, esta agenda recomenda que:
1. calls para top-level `fn` não sejam permitidas em initializer de `global` em v1;
2. a necessidade de lógica mais rica seja absorvida pelo init de módulo discutido na `19.2`;
3. isso mantenha o dep graph de globals focado em materialização declarativa, não em execução procedural arbitrária.
Também fica recomendado que, em v1:
1. `some(...)` e `none` não façam parte do initializer declarativo de `global`;
2. `if` e `switch` não sejam permitidos diretamente na declaração de `global`.
## Diagnostics Recommendation
Esta agenda fecha o seguinte catálogo pequeno, forte e didático de diagnósticos obrigatórios.
### 1. Invalid Global Initializer
Quando o initializer usar uma forma não admissível em v1, o compiler deve emitir um erro apontando a subexpressão inválida.
Mensagem semântica recomendada:
- `global initializer uses unsupported form`
Exemplos de motivo associado:
- top-level `fn` call not allowed in global initializer;
- `some(...)` not allowed in global initializer;
- `if` not allowed in global initializer.
### 2. Global Dependency Cycle
Quando houver ciclo, o compiler deve diagnosticar o global owner local e, quando possível, renderizar o caminho canônico do ciclo.
Mensagem semântica recomendada:
- `global dependency cycle detected`
Detalhe recomendado:
- incluir o símbolo local que participa do ciclo;
- incluir o caminho canônico quando disponível, por exemplo:
`@project:A.seed -> @project:B.rng -> @project:C.config -> @project:A.seed`
### 3. Shadowing Requires Alias
Quando um import introduzir nome que colide com `fn`, `service`, `global` ou `const` já visível, o compiler deve rejeitar e exigir alias explícito.
Mensagem semântica recomendada:
- `imported symbol shadows existing visible symbol; alias required`
### 4. Global Import Category Mismatch
Se o barrel e a importação não preservarem corretamente a categoria declarativa `global`, o compiler deve rejeitar explicitamente em vez de tentar degradar para `const` ou valor genérico.
Mensagem semântica recomendada:
- `global import must resolve through a global barrel entry`
Essa escolha existe para preservar:
- clareza semântica;
- diagnósticos mais simples;
- e uma separação limpa entre storage initialization e lifecycle hooks.
## Forwarded To 19.2
Os seguintes temas surgiram desta agenda, mas pertencem ao boundary de lifecycle e devem ser tratados na `19.2`:
1. init por módulo como fase procedural separada do initializer declarativo de `global`;
2. init de projeto como fase distinta de coordenação final;
3. permissão de loops em init de módulo e init de projeto;
4. proibição de host calls por padrão durante init;
5. permissão apenas para host calls marcadas com atributo reservado `[InitAllowed]`;
6. validação compile-time dessa admissibilidade;
7. separação entre restrição normativa de host interaction e recomendação de design para manter bootstrap leve.
## Expected Spec Material
Se esta agenda fechar, a propagação esperada atinge pelo menos:
- `3. Core Syntax Specification.md`
- `4. Static Semantics Specification.md`
- `11. AST Specification.md`
- `12. Diagnostics Specification.md`
## Non-Goals
Esta agenda não deve:
1. definir boot ordering;
2. definir `[Init]` ou `[Frame]`;
3. definir wrapper published entrypoint;
4. definir posicionamento de `FRAME_RET`;
5. escolher a representação de IR/bytecode para globals.
## Next Step
Depois de fechar esta agenda, abrir ou aprofundar:
- `19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda`

361
docs/compiler/pbs/agendas/19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda.md
View File

@ -1,361 +0,0 @@
# PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda
## Status
Open
## Parent Agenda
This agenda derives from:
- `19. Globals, Synthetic Module Init, and FRAME_RET Agenda`
Expected fixed input from previous stage:
- `19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda`
## Purpose
Define the observable lifecycle model of PBS once runtime globals exist.
This agenda must close:
- whether `[Init]` and `[Frame]` become official source markers;
- the relationship between module init and program init;
- boot one-shot behavior;
- failure policy;
- and the semantic role of the user's frame root.
## Domain Owner
`docs/compiler/pbs`
Este tema pertence ao domínio PBS porque define lifecycle observável da linguagem, não apenas mecanismo de backend.
## Context
Depois que `declare global` existir como storage runtime de módulo, o compiler precisará definir:
- quando os globals são materializados;
- em que ordem isso acontece;
- se existe um hook explícito de init de programa;
- se existe um init procedural por módulo separado do initializer declarativo de `global`;
- como a linguagem identifica o frame root do usuário;
- e o que acontece quando o boot falha.
Esta agenda ainda não decide a forma exata do wrapper published entrypoint nem o shape do IR. Ela define primeiro o comportamento observável que essas camadas posteriores terão de respeitar.
## Inputs Already Fixed Elsewhere
Os seguintes inputs devem ser tratados como fechados ou fortemente estáveis aqui:
- o modelo base de globals vindo de `19.1`;
- o initializer declarativo de `global` permanece restrito a primitivas, `new` e leitura de outras globals compatíveis com o dep graph;
- top-level `fn` não são permitidas em initializer de `global` em v1;
- `FRAME_SYNC` permanece como safepoint normativo;
- PBS v1 continua determinístico e single-threaded;
- esta fase continua evitando mudanças novas no runtime.
## Decisions To Produce
Esta agenda deve produzir direção suficiente para fechar:
1. se `[Init]` e `[Frame]` entram na surface oficial;
2. targets válidos, unicidade e assinaturas exigidas;
3. ordem entre module init, init de programa e frame;
4. política de boot one-shot;
5. política de falha;
6. papel semântico de `frame()` do usuário;
7. política de loops e host calls admissíveis durante init.
## Core Questions
1. PBS deve introduzir `[Init]` e `[Frame]` como atributos reservados?
2. `[Init]` deve ser permitido tanto por módulo quanto no init final de projeto?
3. `[Frame]` deve existir exatamente uma vez por programa?
4. `[Init]` deve existir no máximo uma vez por programa?
5. `[Init]` e `[Frame]` devem exigir assinatura fixa `fn ...() -> void`?
6. Todos os module inits devem rodar antes do `[Init]` do usuário?
7. A ausência de `[Init]` deve ser válida?
8. A ausência de `[Frame]` deve ser erro hard para programa executável?
9. Em caso de falha durante module init ou `[Init]`, o programa deve falhar definitivamente ou pode haver retry?
10. Qual é a definição semântica correta de `frame()` do usuário: root lógico do tick, callable publicado, ou apenas callable invocado por infraestrutura sintética futura?
11. Loops devem ser permitidos em init de módulo e init de projeto?
12. Host calls devem ser proibidas por padrão durante init?
13. Apenas host calls marcadas com `[InitAllowed]` devem ser admissíveis durante init?
14. Como a admissibilidade de `[InitAllowed]` é validada em compile time?
## Options
### Option A
Introduzir `[Init]` e `[Frame]` como markers reservados explícitos, com assinaturas fixas, `[Init]` opcional por módulo e por projeto, `[Frame]` obrigatório e único por projeto executável, permitindo init procedural por módulo e mantendo política restritiva de host interaction durante init.
### Option B
Introduzir apenas `[Frame]` e manter init inteiramente sintético, sem hook de programa do usuário nesta fase.
### Option C
Manter lifecycle implícito, sem markers source-level, e continuar derivando entrypoint/configuração fora da linguagem.
## Tradeoffs
### Option A
- Prós:
- deixa lifecycle explícito na linguagem;
- reduz dependência de configuração paralela;
- dá base clara para wrapper, manifest e lowering posteriores.
- Contras:
- amplia a surface de atributos reservados;
- exige validação de target, unicidade e assinatura.
### Option B
- Prós:
- escopo menor;
- adia parte da discussão de init.
- Contras:
- resolve só metade do lifecycle;
- pode forçar redesign quando o hook de init do usuário voltar.
### Option C
- Prós:
- menor custo imediato.
- Contras:
- mantém a autoridade do lifecycle fora da linguagem;
- enfraquece a coerência da série 19.
## Recommendation
Seguir com a **Option A**.
Direção recomendada:
1. `[Init]` e `[Frame]` devem ser markers reservados explícitos;
2. `declare global` sempre lowera para o init sintético do módulo owner;
3. `[Init]` de módulo deve ser opcional e executar depois de todos os `declare global` do módulo;
4. o init de projeto deve seguir o mesmo modelo, mas associado ao projeto que contém o `[Frame]`;
5. `[Init]` de projeto deve ser opcional;
6. `[Frame]` deve ser obrigatório para programa executável e único por projeto;
7. `[Init]` e `[Frame]` devem exigir assinatura fixa `fn name() -> void`;
8. boot deve ser one-shot;
9. falha de boot deve seguir direção fail-fast, salvo argumento forte em contrário;
10. loops devem ser permitidos em init de módulo e init de projeto;
11. host calls devem ser proibidas por padrão durante init;
12. apenas host calls com atributo reservado `[InitAllowed]` devem ser admissíveis durante init;
13. `[InitAllowed]` é atributo reservado de SDK, não userland.
## Additional Lifecycle Concerns
Esta agenda também precisa fechar a separação entre três camadas de bootstrap:
1. initializer declarativo de `global`;
2. init por módulo;
3. init de projeto.
Direção herdada da `19.1`:
- `global` materializa storage inicial;
- init de módulo executa lógica procedural de conveniência sobre globals do próprio módulo;
- init de projeto executa coordenação final do programa.
Com esse modelo:
- loops são legítimos em init de módulo e init de projeto, especialmente para carga e preparação de arrays e estruturas derivadas;
- a restrição normativa mais forte deve cair sobre host interaction;
- "bootstrap leve" continua sendo recomendação de design, não um limite impossível de verificar semanticamente.
## Current Direction
Os pontos abaixo já podem ser tratados como direção fechada desta agenda, salvo objeção nova forte:
1. `[Init]` e `[Frame]` entram como atributos reservados explícitos;
2. `declare global X: T = expr;` lowera sempre para o init sintético do módulo owner;
3. cada arquivo pode declarar opcionalmente um `[Init]` procedural próprio;
4. o `[Init]` de cada arquivo roda sempre depois das globals daquele arquivo e participa do init sintético do módulo;
5. existe também um init de projeto opcional, que é o `[Init]` associado ao projeto que contém o `[Frame]`;
6. `[Frame]` é obrigatório e único por projeto executável;
7. `[Init]` e `[Frame]` seguem a forma recomendada:
```pbs
[Init]
fn init() -> void { ... }
```
```pbs
[Frame]
fn frame() -> void { ... }
```
8. a assinatura exigida é sempre `fn name() -> void`;
9. loops são permitidos nos inits;
10. host calls são proibidas por padrão durante init;
11. apenas host calls com `[InitAllowed]` podem ser usadas durante init;
12. `[InitAllowed]` pertence às superfícies reservadas de SDK, não a userland;
13. falha de boot é fail-fast com mensagem coerente.
Também fica fechada a seguinte regra operacional:
14. o `[Init]` que estiver no mesmo arquivo que o `[Frame]` é o init de projeto;
15. `[Init]` em outros arquivos continuam sendo init de módulo;
16. `[Frame]` e o init de projeto devem ser co-localizados no mesmo arquivo por decisão deliberada de source organization.
17. cada arquivo pode declarar no máximo um `[Init]`;
18. cada módulo possui exatamente um init sintético de módulo, dentro do qual os inits por arquivo são ordenados e compostos;
19. a distinção entre init de módulo e init de projeto é apenas de ordenação e papel semântico, não de surface diferente;
20. como consequência, existe no máximo um `[Init]` de projeto por projeto executável.
21. arquivos sem globals podem declarar um `[Init]`, desde que continuem respeitando a regra de no máximo um `[Init]` por arquivo;
22. o `project init` segue exatamente a mesma assinatura `fn init() -> void`.
## Lifecycle Order Direction
Esta agenda também já aponta para a seguinte ordem lógica de bootstrap:
1. materialização das globals de cada arquivo do módulo conforme a ordem determinada pelo dependency graph;
2. execução do `[Init]` daquele arquivo, quando existir;
3. composição desses passos em um único init sintético do módulo;
4. depois do fechamento dos módulos necessários, execução do `[Init]` de projeto, quando existir;
5. entrada no primeiro `frame()`.
Lendo essa ordem de forma operacional:
1. cada arquivo inicializa suas próprias globals;
2. cada arquivo pode então executar seu `[Init]` opcional;
3. tudo isso se aninha dentro de um único init sintético por módulo;
4. o `[Init]` co-localizado com `[Frame]` é elevado a init de projeto por ordem e papel semântico.
Também fica fechada a seguinte direção adicional:
5. a ordem entre arquivos do mesmo módulo deve seguir a ordem derivada do `DependencyGraphAnaliser` das globals;
6. quando dois arquivos não tiverem dependência entre si, o compiler deve usar uma ordem determinística estável.
## Remaining Open Points
Com a direção já consolidada nesta agenda, não restam pontos substantivos em aberto dentro do boundary de `19.2`.
Os temas seguintes agora pertencem à `19.3`.
## InitAllowed Direction
Esta agenda fecha também o seguinte shape normativo inicial para `[InitAllowed]`:
1. `[InitAllowed]` é um atributo reservado sem argumentos em v1;
2. ele é válido apenas em host methods de SDK;
3. ele é inválido em userland;
4. ele é inválido em `fn`, `global`, `service` e demais superfícies que não sejam host methods de SDK;
5. seu papel é exclusivamente validar, em compile time, quais host calls podem aparecer durante init;
6. ele não faz distinção entre init de módulo e init de projeto;
7. a diferença entre esses inits é de ordenação e papel semântico, não de permissão separada de host call.
Exemplo recomendado:
```pbs
declare host Runtime {
[Host(module = "runtime", name = "random_u32", version = 1)]
[Capability(name = "runtime")]
[InitAllowed]
fn random_u32() -> int;
}
```
## Diagnostics Recommendation
Esta agenda fecha o seguinte catálogo mínimo de diagnósticos de lifecycle e bootstrap.
### 1. Project Init Must Be Colocated With Frame
Mensagem semântica recomendada:
- `project init must be colocated with frame`
### 2. Multiple Project Init Functions Detected
Mensagem semântica recomendada:
- `multiple project init functions detected`
### 3. Multiple Frame Functions Detected
Mensagem semântica recomendada:
- `multiple frame functions detected`
### 4. Missing Frame Function For Executable Project
Mensagem semântica recomendada:
- `missing frame function for executable project`
### 5. Invalid Init Signature
Mensagem semântica recomendada:
- `init function must have signature fn name() -> void`
### 6. Invalid Frame Signature
Mensagem semântica recomendada:
- `frame function must have signature fn name() -> void`
### 7. Host Call Not Allowed During Init
Mensagem semântica recomendada:
- `host call not allowed during init`
### 8. Invalid InitAllowed Target
Mensagem semântica recomendada:
- `InitAllowed is valid only on SDK host methods`
### 9. Boot Failed During Module Init
Mensagem semântica recomendada:
- `boot failed during module init`
### 10. Boot Failed During Project Init
Mensagem semântica recomendada:
- `boot failed during project init`
### 11. Multiple Module Init Functions Detected
Mensagem semântica recomendada:
- `multiple module init functions detected`
### 12. Init Attribute Target Invalid
Mensagem semântica recomendada:
- `Init attribute target invalid`
## Expected Spec Material
Se esta agenda fechar, a propagação esperada atinge pelo menos:
- `3. Core Syntax Specification.md`
- `4. Static Semantics Specification.md`
- `9. Dynamic Semantics Specification.md`
- `12. Diagnostics Specification.md`
## Non-Goals
Esta agenda não deve:
1. decidir o nome físico do wrapper published entrypoint;
2. decidir o nome físico do entrypoint no manifest;
3. definir shape de IR;
4. definir como `FRAME_RET` será reposicionado materialmente.
## Next Step
Depois de fechar esta agenda, abrir ou aprofundar:
- `19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda`

203
docs/compiler/pbs/agendas/19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda.md
View File

@ -1,203 +0,0 @@
# Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda
## Status
Open
## Parent Agenda
This agenda derives from:
- `19. Globals, Synthetic Module Init, and FRAME_RET Agenda`
Expected fixed inputs from previous stages:
- `19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda`
- `19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda`
## Purpose
Define how PBS lifecycle is published into the executable artifact once globals and lifecycle semantics are already fixed.
This agenda must close:
- whether the published entrypoint becomes a synthetic wrapper;
- the semantic and publication relationship between user `frame()` and the published entrypoint;
- the new owner of `FRAME_RET`;
- and the contract boundary between source-derived entrypoint discovery, `FrontendSpec`, and cartridge manifest publication.
## Domain Owner
`docs/compiler/pbs`
Este tema pertence ao domínio PBS porque decide a fronteira entre semântica da linguagem, entrypoint publicado e artefato executável.
## Context
Se `frame()` do usuário deixar de ser o callable publicado diretamente, o compiler precisará publicar outro root executável.
Isso abre quatro perguntas acopladas:
- quem é o entrypoint físico do artefato;
- qual callable continua sendo o root lógico do código do usuário;
- onde `FRAME_RET` passa a ser emitido;
- e como manifest e `FrontendSpec` representam isso sem ambiguidade.
Esta agenda existe para fechar esse contrato antes de discutir detalhe de representação de IR.
## Inputs Already Fixed Elsewhere
Os seguintes inputs devem ser tratados como fixos aqui:
- o modelo de globals vindo de `19.1`;
- o modelo de lifecycle e markers vindo de `19.2`;
- `FRAME_RET` continua significando fim do frame lógico;
- o runtime continua esperando um entrypoint published por frame.
## Decisions To Produce
Esta agenda deve produzir direção suficiente para fechar:
1. se o published entrypoint é um wrapper sintético;
2. qual é a relação entre `frame()` do usuário e esse wrapper;
3. onde `FRAME_RET` passa a viver;
4. como a autoridade de entrypoint sai de `FrontendSpec` e passa ao compiler PBS;
5. como o protocolo de runtime/manifest representa esse entrypoint.
## Core Questions
1. O compiler deve publicar um wrapper sintético como entrypoint real?
2. `frame()` do usuário deixa de ser o callable publicado e passa a ser apenas root lógico interno?
3. `FRAME_RET` deve ser emitido no wrapper, não mais no callable do usuário?
4. O compiler PBS deve se tornar a única autoridade para definir o entrypoint publicado?
5. O wrapper sintético deve ocupar protocolarmente o entrypoint físico `0`?
6. O campo `entrypoint` deve deixar de existir no `manifest.json` como estado alvo do protocolo?
7. Existe algum caso em que o wrapper não seja necessário depois de `19.2`?
## Options
### Option A
Publicar um wrapper sintético como entrypoint físico, tratar `frame()` do usuário como root lógico interno, mover `FRAME_RET` para o wrapper, tornar o compiler PBS a autoridade exclusiva de entrypoint e fixar protocolarmente o entrypoint físico em `0`.
### Option B
Manter `frame()` do usuário como entrypoint publicado e tentar acoplar boot/lifecycle diretamente nele.
### Option C
Publicar wrapper sintético, mas manter `entrypoint` no manifest como autoridade nominal paralela.
## Tradeoffs
### Option A
- Prós:
- separa lifecycle publicado do callable do usuário;
- acomoda boot one-shot de forma limpa;
- preserva o significado de `FRAME_RET` com owner mais correto.
- alinha melhor o protocolo físico do artefato com a política já existente de `func_id = 0` como entrypoint;
- remove autoridade duplicada entre compiler, manifest e `FrontendSpec`.
- Contras:
- exige trabalho claro de migração em manifest, runtime e `FrontendSpec`;
- torna a relação lógico/físico explicitamente dupla.
### Option B
- Prós:
- preserva a superfície atual de publicação.
- Contras:
- mistura responsabilidades demais no callable do usuário;
- enfraquece a clareza do lifecycle.
### Option C
- Prós:
- parece reduzir custo de transição imediata.
- Contras:
- mantém duas autoridades para entrypoint;
- cria dívida documental e de runtime desnecessária;
- enfraquece a ideia de entrypoint como protocolo fixo do artefato.
## Recommendation
Seguir com a **Option A**.
## Current Direction
Os pontos abaixo já podem ser tratados como direção fechada desta agenda, salvo objeção nova forte:
1. o compiler deve publicar um wrapper sintético como entrypoint físico real;
2. esse wrapper deve conter:
- boot one-shot,
- os inits necessários apenas uma vez,
- a chamada ao `frame()` do usuário,
- e o `FRAME_RET` final;
3. `frame()` anotado com `[Frame]` permanece como root lógico do usuário;
4. o wrapper sintético é o root físico publicado;
5. `FRAME_RET` sai do final do `frame()` do usuário e passa a existir no wrapper;
6. `FrontendSpec` perde autoridade para referenciar quem é o entrypoint;
7. a autoridade de entrypoint fica outorgada exclusivamente ao compiler PBS;
8. o wrapper sintético deve ser compilado no entrypoint físico `0`;
9. o estado alvo do protocolo deve remover `entrypoint` do `manifest.json`;
10. o runtime/loader deve tratar o entrypoint como protocolo fixo do artefato, não como metadado nominal configurável no manifest.
## Manifest and Runtime Direction
Esta agenda também já aponta para a seguinte direção de contrato:
1. o campo `entrypoint` deve deixar de existir no `manifest.json` como estado final do protocolo;
2. o runtime deve assumir protocolarmente o entrypoint físico `0`;
3. o compiler garante que esse índice `0` pertence ao wrapper sintético publicado;
4. export nominal do callable deixa de ser a autoridade de boot;
5. qualquer compatibilidade temporária com manifest nominal deve ser tratada apenas como transição, não como contrato final desejado.
## Exports Boundary
Esta agenda também fecha a seguinte separação:
1. exports nominais de funções podem continuar existindo no artefato;
2. esses exports deixam de ser usados como autoridade de loader/boot;
3. boot passa a depender exclusivamente do entrypoint físico `0` publicado pelo compiler;
4. exports nominais permanecem apenas como superfície útil para tooling, debug, introspection e casos correlatos.
## Remaining Open Points
Com a direção acima, os pontos que ainda pedem fechamento real nesta agenda ficam reduzidos a:
1. a forma de propagação normativa dessa mudança para specs gerais de bytecode, lowering e cartridge contract.
## Runtime Propagation
Esta agenda também deve referenciar explicitamente a discussão correspondente no domínio runtime:
- `../runtime/docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`
Direção fechada desta agenda:
1. não há linha de compatibilidade desejada como estado-alvo;
2. a remoção de `entrypoint` do runtime deve ser executada em prioridade alinhada ao compiler;
3. a agenda de runtime é o owner da discussão operacional de loader/VM/manifest no outro domínio.
## Expected Spec Material
Se esta agenda fechar, a propagação esperada atinge pelo menos:
- `9. Dynamic Semantics Specification.md`
- `13. Lowering IRBackend Specification.md`
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
- `12. Diagnostics Specification.md`
## Non-Goals
Esta agenda não deve:
1. escolher o encoding exato do wrapper no IR;
2. definir estrutura detalhada de module init lowering;
3. escrever fixtures completos de conformance.
## Next Step
Depois de fechar esta agenda, abrir ou aprofundar:
- `19.4. Globals and Lifecycle Lowering to IRBackend/IRVM Agenda`

305
docs/compiler/pbs/agendas/19.4. Globals and Lifecycle Lowering to IRBackend-IRVM Agenda.md
View File

@ -1,305 +0,0 @@
# Globals and Lifecycle Lowering to IRBackend/IRVM Agenda
## Status
Open
## Parent Agenda
This agenda derives from:
- `19. Globals, Synthetic Module Init, and FRAME_RET Agenda`
Expected fixed inputs from previous stages:
- `19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda`
- `19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda`
- `19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda`
## Purpose
Define how the already-decided globals and lifecycle model are represented and lowered through the executable compiler pipeline.
This agenda must close:
- the representation boundary for globals;
- module init synthesis;
- boot guard materialization;
- wrapper lowering;
- and the executable path that preserves the chosen `FRAME_RET` ownership.
## Domain Owner
`docs/compiler/pbs`
Este tema pertence ao domínio PBS, mas encosta diretamente nas specs gerais de lowering e nas interfaces entre frontend e backend.
## Context
Depois que surface, lifecycle e publication contract estiverem fechados, ainda restará decidir:
- em que boundary globals passam a existir como entidade explícita;
- se `IRBackend` carrega globals diretamente ou só uma forma anterior;
- como module init sintético é representado;
- como o wrapper published entrypoint é emitido;
- como o guard one-shot de boot é materializado.
Esta agenda é mecânica/arquitetural. Ela não deve reabrir decisões de linguagem.
## Inputs Already Fixed Elsewhere
Os seguintes inputs devem ser tratados como fixos aqui:
- surface e identidade de globals vindas de `19.1`;
- lifecycle semântico vindo de `19.2`;
- owner do published entrypoint e de `FRAME_RET` vindo de `19.3`;
- `GET_GLOBAL` e `SET_GLOBAL` já existem na VM.
## Decisions To Produce
Esta agenda deve produzir direção suficiente para fechar:
1. se globals entram explicitamente no `IRBackend` ou apenas em lowering posterior;
2. como module init é sintetizado;
3. como o guard one-shot de boot é materializado;
4. como o wrapper é lowered;
5. como `FRAME_RET` é preservado no ponto correto;
6. quais contracts gerais de lowering precisam propagação.
## Core Questions
1. `IRBackend` deve ganhar representação explícita para globals?
2. Se não, qual é o boundary intermediário responsável por materializá-los antes de `IRVM`?
3. Module init sintético é emitido como callable próprio por módulo?
4. O boot guard é global oculto, local estático de wrapper, ou outra forma interna?
5. O wrapper published entrypoint é um callable sintético explícito no graph do frontend?
6. Como manter attribution e diagnostics úteis para código sintético?
7. Que mudanças mínimas precisam acontecer em specs gerais fora de `docs/compiler/pbs`?
8. O lowering deve introduzir uma classe explícita de funções sintéticas com ergonomia própria, em vez de emissão ad hoc?
## Options
### Option A
Dar representação explícita a globals e callables sintéticos já no boundary de `IRBackend`, preservando attribution e identidade suficientes para lowering posterior.
### Option B
Manter `IRBackend` sem globals explícitos e adiar essa materialização para um lowering mais baixo.
### Option C
Tratar globals como açúcar compilado diretamente para slots/ops sem entidade intermediária estável.
## Tradeoffs
### Option A
- Prós:
- boundary mais explícito e testável;
- menor inferência textual em lowers posteriores;
- facilita explicar wrapper e init synthesis.
- Contras:
- aumenta o contrato do `IRBackend`;
- pode exigir propagação além do domínio PBS.
### Option B
- Prós:
- preserva o boundary atual por mais tempo.
- Contras:
- empurra complexidade para fases posteriores;
- dificulta conformance do shape intermediário.
### Option C
- Prós:
- menor aparente custo de modelagem.
- Contras:
- fraco para teste, attribution e manutenção;
- mistura lowering demais cedo.
## Recommendation
Seguir com a **Option A**, salvo impedimento forte de boundary cross-domain.
## Current Direction
Os pontos abaixo já podem ser tratados como direção fechada desta agenda, salvo objeção nova forte:
1. globals devem entrar explicitamente no `IRBackend`;
2. o pipeline não deve adiar globals para uma materialização implícita tardia abaixo desse boundary;
3. fragments de init por arquivo, init sintético por módulo, init de projeto e wrapper published entrypoint devem existir como callables sintéticos explícitos;
4. o boot guard deve ser materializado como um global oculto;
5. esse global oculto não pode ser referenciado nem alterado por userland;
6. o wrapper published entrypoint deve existir explicitamente no graph de lowering;
7. o lowering deve seguir direção direta para as operações de globals já suportadas em `IRVM`/VM, isto é, `GET_GLOBAL` e `SET_GLOBAL`;
8. attribution e diagnostics devem preservar separadamente:
- origem em source userland,
- e origem sintética gerada pelo compiler;
9. quando algum erro estrutural ou de lowering surgir em código sintetizado, a superfície sintética deve ser capaz de carregar attribution de volta ao código real que originou aquele trecho;
10. spans e diagnostics devem preferir apontar para código real de userland sempre que essa origem existir;
11. o frontend/lowering deve introduzir uma classe explícita de funções sintéticas com ergonomia própria;
12. a emissão dessas funções não deve ser ad hoc caso a caso.
## Synthetic Callable Direction
Esta agenda também fecha a seguinte direção arquitetural:
1. callables sintéticos não devem ser tratados como acidentes de emissão;
2. eles devem possuir classe/identidade própria no lowering;
3. essa classe deve cobrir pelo menos:
- fragmentos de init por arquivo,
- init sintético por módulo,
- init de projeto,
- wrapper físico publicado;
4. a ergonomia dessa classe própria deve facilitar:
- ordenação,
- attribution,
- debug,
- testes,
- e futuras extensões de lifecycle sem reabrir o modelo básico.
Também fica fechada a seguinte exigência de diagnóstico:
1. a superfície sintética precisa carregar origem suficiente para remapear erros ao código real;
2. quando existir origem userland inequívoca, o diagnóstico deve preferir essa origem em vez de um span puramente sintético;
3. spans puramente sintéticos só devem aparecer quando não houver origem real defensável.
## Hidden Boot Guard Direction
O boot guard também fica com direção fechada nesta agenda:
1. ele deve existir como global oculto de programa;
2. ele pertence ao estado interno publicado pelo compiler;
3. userland não pode nomeá-lo, ler seu valor ou alterá-lo;
4. sua única função é garantir a semântica one-shot do bootstrap no wrapper físico.
## IRBackend Shape Direction
Esta agenda também fecha o seguinte shape estrutural mínimo para o `IRBackend`.
### 1. Backend Globals
O `IRBackend` deve carregar globals explicitamente como entidades estruturais, não apenas como efeitos implícitos no corpo de funções.
Direção mínima recomendada para cada global:
- `name`
- `ownerModuleId`
- `type`
- `slot`
- `visibility`
- `isHidden`
- `origin`
Isso deve cobrir:
- globals de userland;
- e globals ocultos do compiler, incluindo o boot guard.
### 2. Backend Callables
O `IRBackend` deve distinguir explicitamente:
- callables normais de userland;
- callables sintéticos gerados pelo compiler.
### 3. Synthetic Callable Kind
O conjunto mínimo de kinds sintéticos desta agenda deve cobrir:
- `FILE_INIT_FRAGMENT`
- `MODULE_INIT`
- `PROJECT_INIT`
- `PUBLISHED_FRAME_WRAPPER`
### 4. Synthetic Origin
Todo callable ou global sintético deve carregar metadados suficientes para attribution e remapeamento de diagnóstico.
Direção mínima recomendada:
- `derivedFromFile`
- `derivedFromModule`
- `derivedFromUserSymbol`
- `primarySpan`
- `fallbackSyntheticLabel`
### 5. Hidden Global Kind
O boot guard deve aparecer como global oculto com identidade estrutural explícita, não como convenção informal de nome.
Direção mínima recomendada:
- `BOOT_GUARD`
## Diagnostics and Conformance Direction
Esta agenda também fecha o seguinte conjunto mínimo de checks estruturais e evidências de conformance.
### Structural Diagnostics / Validation
1. `synthetic wrapper entrypoint missing`
- quando o pipeline não conseguir publicar o wrapper exigido.
2. `published entrypoint is not function index 0`
- quando o lowering violar o protocolo físico.
3. `hidden boot guard is missing`
- quando a semântica one-shot exigir o guard e ele não existir.
4. `synthetic callable origin missing`
- quando o lowering gerar callable sintético sem attribution suficiente para diagnóstico defensável.
### Conformance / Fixture Expectations
1. fixture com `declare global` + `[Init]` por arquivo + `[Init]` de projeto + `[Frame]`;
2. evidência de geração de:
- file init fragment,
- module init,
- project init,
- published wrapper,
- hidden boot guard;
3. evidência de que o wrapper ocupa `func_id = 0`;
4. evidência de que `FRAME_RET` está no wrapper;
5. evidência de que erro em lowering sintético remapeia para span real quando houver origem de userland defensável.
## Spec and Learn Propagation Direction
Esta agenda também fecha a seguinte direção editorial:
1. specs de lowering devem explicar de forma normativa:
- a classe de callables sintéticos,
- o lifecycle de init no lowering,
- o wrapper publicado,
- o hidden boot guard,
- e a relação desses artefatos com attribution e diagnostics;
2. `learn` deve explicar esse modelo de forma didática com exemplos de código source;
3. `learn` deve mostrar como:
- `declare global`,
- `[Init]` por arquivo,
- `[Init]` de projeto,
- e `[Frame]`
se compõem até virar o wrapper físico publicado;
4. a explicação didática em `learn` deve privilegiar exemplos concretos de source e composição, não apenas descrição abstrata do pipeline.
## Expected Spec Material
Se esta agenda fechar, a propagação esperada atinge pelo menos:
- `13. Lowering IRBackend Specification.md`
- specs gerais de lowering/backend fora do domínio PBS, se necessário
- `12. Diagnostics Specification.md`
## Non-Goals
Esta agenda não deve:
1. redefinir surface syntax;
2. redefinir lifecycle;
3. redefinir manifest publication;
4. fechar catálogo final de fixtures.
## Next Step
Depois de fechar esta agenda, abrir ou aprofundar:
- `19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda`

277
docs/compiler/pbs/agendas/19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda.md
View File

@ -1,277 +0,0 @@
# Diagnostics, Manifest Propagation, and Conformance Coverage Agenda
## Status
Closed
## Parent Agenda
This agenda derives from:
- `19. Globals, Synthetic Module Init, and FRAME_RET Agenda`
Expected fixed inputs from previous stages:
- `19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda`
- `19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda`
- `19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda`
- `19.4. Globals and Lifecycle Lowering to IRBackend/IRVM Agenda`
## Purpose
Consolidate the propagation layer of topic `19` after the architectural decisions are already fixed.
This agenda must close:
- the diagnostics surface;
- manifest-facing propagation details;
- fixture and conformance coverage;
- and the acceptance gates for declaring topic `19` ready to become a decision plus implementation plan.
## Domain Owner
`docs/compiler/pbs`
Este tema pertence ao domínio PBS, mas toca tanto specs normativas quanto critérios de teste e artefato publicado.
## Context
Depois que surface, lifecycle, published entrypoint e lowering estiverem fechados, ainda faltará consolidar:
- quais erros novos são obrigatórios;
- em que fase cada erro aparece;
- como o manifest final reflete a arquitetura escolhida;
- e que coverage mínima de fixtures e gates garante que a série 19 ficou estável.
Esta agenda é de consolidação. Ela não deve rediscutir a arquitetura central.
## Inputs Already Fixed Elsewhere
Os seguintes inputs devem ser tratados como fixos aqui:
- shape de globals vindo de `19.1`;
- lifecycle vindo de `19.2`;
- publication contract vindo de `19.3`;
- lowering mechanics vindo de `19.4`.
## Decisions To Produce
Esta agenda deve produzir direção suficiente para fechar:
1. catálogo mínimo de diagnósticos;
2. fase responsável por cada diagnóstico;
3. propagação final para manifest/specs;
4. fixture matrix mínima;
5. critérios de aceite para converter a série 19 em `decision` e depois `pull-request/plan`.
## Core Questions
1. Quais diagnósticos são obrigatórios para `declare global`, imports/reexports e ciclos?
2. Quais diagnósticos são obrigatórios para `[Init]` e `[Frame]`?
3. Quais erros pertencem a parser/AST, static semantics/linking, lowering, ou toolchain full pipeline?
4. Como o manifest final deve refletir entrypoint lógico e/ou físico escolhido em `19.3`?
5. Que fixtures mínimas precisam existir para globals, module init, boot failure, wrapper e `FRAME_RET`?
6. Em que ponto a configuração explícita antiga de entrypoint em `FrontendSpec` pode ser considerada removida?
7. Quais gates de conformance precisam ser atualizados para cobrir a série 19?
## Options
### Option A
Consolidar diagnostics e coverage somente depois que os quatro stages anteriores estiverem fechados, com fixture matrix explícita por fase.
### Option B
Começar fixtures e diagnostics cedo, mesmo com arquitetura ainda mudando.
## Tradeoffs
### Option A
- Prós:
- reduz retrabalho;
- evita congelar erro e coverage cedo demais;
- combina melhor com a disciplina de umbrella agenda.
- Contras:
- posterga parte da validação final.
### Option B
- Prós:
- feedback mais cedo.
- Contras:
- alto risco de churn e reabertura de artefatos;
- conflita com os locking rules da umbrella 19.
## Recommendation
Seguir com a **Option A**.
## Current Direction
Os pontos abaixo já podem ser tratados como direção fechada desta agenda, salvo objeção nova forte:
1. a 19.5 não reabre arquitetura; ela consolida diagnostics, propagation e coverage da série 19;
2. o catálogo final deve ser agrupado por fase, não apenas por ordem histórica das agendas;
3. a propagation final deve nomear explicitamente:
- PBS specs,
- general compiler specs,
- runtime cross-domain owner,
- e `learn`;
4. a conformance matrix mínima deve cobrir:
- positive source flow,
- negative frontend cases,
- negative lowering/structural cases,
- runtime integration.
## Consolidated Diagnostics Direction
Esta agenda fecha a seguinte consolidação de diagnósticos por fase.
### Frontend / Static Semantics
- `global initializer uses unsupported form`
- `global dependency cycle detected`
- `imported symbol shadows existing visible symbol; alias required`
- `global import must resolve through a global barrel entry`
- `init function must have signature fn name() -> void`
- `frame function must have signature fn name() -> void`
- `multiple module init functions detected`
- `multiple project init functions detected`
- `multiple frame functions detected`
- `missing frame function for executable project`
- `Init attribute target invalid`
- `project init must be colocated with frame`
- `InitAllowed is valid only on SDK host methods`
- `host call not allowed during init`
### Lowering / Structural Validation
- `synthetic wrapper entrypoint missing`
- `published entrypoint is not function index 0`
- `hidden boot guard is missing`
- `synthetic callable origin missing`
### Runtime / Boot Failure
- `boot failed during module init`
- `boot failed during project init`
Também fica fechada a seguinte leitura:
1. diagnósticos de frontend/static semantics são user-facing do compiler;
2. checks de lowering podem aparecer como diagnostics, validation failures ou invariant violations, desde que a falha seja observável e testável;
3. falhas de boot do runtime pertencem à superfície de falha operacional, não ao frontend static diagnostic catalog.
## Propagation Targets Direction
Esta agenda fecha a seguinte lista mínima de propagation targets.
### PBS Specs
- `3. Core Syntax Specification.md`
- `4. Static Semantics Specification.md`
- `9. Dynamic Semantics Specification.md`
- `11. AST Specification.md`
- `12. Diagnostics Specification.md`
- `13. Lowering IRBackend Specification.md`
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
### General Compiler Specs
- `15. Bytecode and PBX Mapping Specification.md`
- `20. IRBackend to IRVM Lowering Specification.md`
### Runtime Cross-Domain Owner
- `../runtime/docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`
### Learn
- um learn consolidado para globals + lifecycle + published wrapper + entrypoint protocol
- com explicação source-first e depois lowering/publication
## Conformance Matrix Direction
Esta agenda fecha a seguinte matrix mínima de coverage.
### Positive Coverage
Projeto com:
- `declare global`
- `[Init]` por arquivo
- `[Init]` de projeto
- `[Frame]`
Assert mínimo:
- globals aceitos
- ordering aceito
- wrapper publicado
- `func_id = 0`
- `FRAME_RET` no wrapper
- boot guard presente
### Negative Frontend Coverage
- `global` com `fn` no initializer
- `global` com `if`
- ciclo entre globals
- collision entre import e `const`/`global`/`service`/`fn`
- `[Init]` com assinatura errada
- `[Frame]` com assinatura errada
- dois `[Frame]`
- dois `project init`
- `project init` fora do arquivo do `[Frame]`
- host call em init sem `[InitAllowed]`
- `[InitAllowed]` em target inválido
### Negative Lowering Coverage
- ausência de wrapper publicado
- wrapper fora do índice `0`
- ausência de boot guard
- callable sintético sem origin metadata
### Runtime Integration Coverage
- artefato sobe com entrypoint físico `0`
- runtime não depende de export nominal para boot
- boot failure em module init gera falha coerente
- boot failure em project init gera falha coerente
## Exit Direction
Esta agenda considera a série 19 pronta para virar execução quando houver:
1. catálogo consolidado de diagnósticos fechado;
2. propagation targets explicitamente nomeados;
3. conformance matrix mínima aceita;
4. owner explícito para a frente cross-domain de runtime.
## Expected Spec Material
Se esta agenda fechar, a propagação esperada atinge pelo menos:
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
- `12. Diagnostics Specification.md`
- `13. Lowering IRBackend Specification.md`
- docs de conformance/fixtures relevantes
## Non-Goals
Esta agenda não deve:
1. redefinir semântica de globals;
2. redefinir lifecycle;
3. redefinir wrapper ou ownership de `FRAME_RET`;
4. redefinir shape de IR.
## Next Step
Esta agenda foi consolidada em:
- `docs/compiler/pbs/decisions/Diagnostics, Manifest Propagation, and Conformance Coverage Decision.md`
Com isso, a família `19` fica pronta para ser decomposta em `pull-request/plan` de execução.

76
docs/compiler/pbs/agendas/README.md
View File

@ -1,76 +0,0 @@
# PBS Agendas
This directory contains active PBS discussion agendas.
Closed agendas are moved to `docs/compiler/pbs/agendas/archive`.
## Active Agendas
1. `18.4. Asset References in Game Code - Names vs Compile-Time Lowering Agenda.md`
2. `18.5. Ignored Call Results in Executable Lowering Agenda.md`
3. `19. Globals, Synthetic Module Init, and FRAME_RET Agenda.md`
4. `19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda.md`
5. `19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda.md`
6. `19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda.md`
7. `19.4. Globals and Lifecycle Lowering to IRBackend-IRVM Agenda.md`
8. `19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda.md`
## Consolidated Agenda 18 Material
Agenda 18 backend-orchestration material (`18.0` through `18.3`) is no longer part of the active agenda set.
That slice has already been propagated into:
1. the backend execution plan in `docs/compiler/pbs/pull-requests/INDEX.md` under `Backend VM Pipeline PR Sequence (Agenda 18)`,
2. decision material such as `docs/compiler/pbs/decisions/IRVM Optimization Stage Placement Decision.md`,
3. normative backend specs:
- `docs/compiler/general/specs/19. Verification and Safety Checks Specification.md`,
- `docs/compiler/general/specs/20. IRBackend to IRVM Lowering Specification.md`,
- `docs/compiler/general/specs/21. IRVM Optimization Pipeline Specification.md`,
- `docs/compiler/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`,
4. and implemented/tested backend pipeline stages in `prometeu-compiler/prometeu-build-pipeline`.
Only `18.4` and `18.5` remain open from the `18.*` family.
## Purpose
An agenda exists to drive a decision, not to serve as final normative text.
Use an agenda when:
- the topic is still open,
- multiple options or tradeoffs must be evaluated,
- the scope and non-goals need to be made explicit,
- the order of discussion matters.
Move an agenda to `docs/compiler/pbs/agendas/archive` once the topic is no longer active.
## Expected Format
An agenda should usually include:
1. Title
2. Status
3. Purpose
4. Context
5. Decisions to Produce
6. Core Questions
7. Expected Spec Material
8. Non-Goals
9. Inputs
## Writing Rules
- Keep the document oriented around unresolved questions.
- Separate open questions from assumptions already fixed elsewhere.
- Name the concrete decisions the discussion must produce.
- Avoid drafting large blocks of final normative spec text here.
- Prefer explicit non-goals to prevent scope drift.
## Exit Rule
An agenda should move out of the active set when:
- the key questions have been answered,
- the architectural direction is clear enough to record,
- and the topic is ready to become a decision record and then a spec update.

53
docs/compiler/pbs/decisions/AST Contract and Root Model Decision.md
View File

@ -1,53 +0,0 @@
# AST Contract and Root Model Decision
Status: Accepted
Date: 2026-03-05
Related Agenda: `docs/pbs/agendas/archive/11.1. AST Workshop 1 - AST Contract and Root Model.md`
## Context
PBS introduced `11. AST Specification.md` as the language-specific AST layer between parser output and frontend lowering to `IRBackend`.
The open question was whether AST should be standardized by one mandatory implementation model (for example one Java class hierarchy) or by observable contract obligations.
## Decision
PBS adopts an obligations-first AST contract.
The specification standardizes required observable AST behavior and invariants, not one mandatory in-memory representation.
The following are required:
1. one AST root per source file;
2. deterministic child ordering consistent with source order;
3. mandatory source attribution (`file`, `start`, `end`) on nodes consumed by diagnostics or lowering;
4. explicit declaration/statement/expression node families for the supported v1 source slice;
5. deterministic rejection for unsupported forms, without permissive synthetic AST that hides rejection.
## Invariants
1. AST conformance is implementation-language agnostic.
2. Missing required attribution on mandatory nodes is non-conformant.
3. Parser recovery may produce partial AST, but structural integrity must remain valid for continued diagnostics.
4. Lowering and diagnostics are allowed to depend on the required AST invariants above.
## Explicit Non-Decisions
1. This decision does not freeze one parser architecture.
2. This decision does not define full static-semantics rules.
3. This decision does not define `IRBackend -> IRVM` lowering.
4. This decision does not define runtime/bytecode/verifier policies.
## Spec Impact
1. `docs/pbs/specs/11. AST Specification.md` must encode the obligations-first contract and invariants.
2. `docs/pbs/specs/12. Diagnostics Specification.md` remains the authority for diagnostic identity/phase/attribution payload rules consumed by AST-facing diagnostics.
3. `docs/pbs/specs/13. Lowering IRBackend Specification.md` may assume the mandatory AST invariants as lowering preconditions.
## Validation Notes
At minimum, Gate U evidence (per `docs/general/specs/13. Conformance Test Specification.md`) should include:
1. valid AST shape fixtures for representative declarations/statements/expressions;
2. deterministic syntax rejection fixtures with stable diagnostics;
3. attribution checks (`file/start/end`) on nodes required by diagnostics and lowering.

69
docs/compiler/pbs/decisions/AST Declarations and Type Surfaces Decision.md
View File

@ -1,69 +0,0 @@
# AST Declarations and Type Surfaces Decision
Status: Accepted
Date: 2026-03-05
Related Agenda: `docs/pbs/agendas/archive/11.2. AST Workshop 2 - Declarations and Type Surfaces.md`
## Context
After closing the AST contract/root model, PBS needed a precise declaration-layer AST decision for v1 so parser output, diagnostics, and IRBackend lowering remain aligned.
The open points were:
- mandatory declaration families in AST,
- declaration identity preservation,
- declaration metadata requirements for downstream phases,
- AST/static-semantics phase boundary,
- rejection and recovery behavior for malformed declarations,
- and minimum Gate U evidence.
## Decision
PBS adopts the following declaration/type-surface AST policy for v1:
1. Mandatory declaration families include:
- imports,
- top-level `fn`,
- `struct`, `contract`, `service`, `error`, `enum`, `callback`,
- `declare const`,
- and declaration nodes required by barrel/linking flow.
2. Declaration identity is preserved at AST boundary; implementations must not prematurely merge declarations (including overload sets).
3. Minimum declaration metadata includes:
- declaration name,
- declared signature/surface (parameters/return when applicable),
- stable source attribution (`file/start/end`),
- and required declaration-level syntactic flags/attributes needed by later phases.
4. AST/static boundary is explicit:
- AST preserves structure,
- static/linking phases own semantic compatibility and resolution rules.
5. Unsupported declaration forms are deterministic parser/AST rejection with stable diagnostics.
6. Recovery may continue after declaration syntax errors, but recovered AST must remain structurally coherent and attribution-consistent.
7. Gate U evidence must include positive and negative declaration fixtures with AST-shape, attribution, and diagnostics assertions.
## Invariants
1. Declaration AST remains obligations-first and implementation-language agnostic.
2. Overload identity is not collapsed at AST layer.
3. Missing required declaration metadata on mandatory nodes is non-conformant.
4. Recovery must not fabricate permissive declaration shapes that hide syntax failures.
## Explicit Non-Decisions
1. This decision does not define static type-checking algorithms.
2. This decision does not define lowering from `IRBackend` to `IRVM`.
3. This decision does not define runtime/bytecode/verifier policy.
4. This decision does not freeze one parser architecture.
## Spec Impact
1. `docs/pbs/specs/11. AST Specification.md` must encode declaration families, identity preservation, metadata minimums, and recovery/rejection invariants.
2. `docs/pbs/specs/12. Diagnostics Specification.md` remains authority for diagnostic identity/phase/attribution semantics consumed by declaration diagnostics.
3. `docs/pbs/specs/13. Lowering IRBackend Specification.md` may assume declaration metadata invariants as lowering preconditions.
## Validation Notes
Gate U evidence (per `docs/general/specs/13. Conformance Test Specification.md`) should include:
1. valid declaration fixtures for each mandatory family,
2. malformed declaration fixtures with deterministic rejection diagnostics,
3. AST assertions for declaration identity, spans, and required metadata fields.

64
docs/compiler/pbs/decisions/AST Diagnostics, Recovery, and Gate Evidence Decision.md
View File

@ -1,64 +0,0 @@
# AST Diagnostics, Recovery, and Gate Evidence Decision
Status: Accepted
Date: 2026-03-05
Related Agenda: `docs/pbs/agendas/archive/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md`
## Context
After closing AST contract, declaration surfaces, and statement/expression surfaces, PBS needed to close AST-facing diagnostics and parser-recovery policy plus the minimum Gate U evidence baseline.
Additionally, localization policy needed explicit alignment: diagnostics wording is locale-dependent and should be keyed by stable message tokens/template ids.
## Decision
PBS adopts the following AST diagnostics/recovery/evidence policy:
1. AST must preserve diagnostic fidelity:
- required syntax diagnostics remain stable in `code`, `severity`, `phase`, `primary file`, and `primary span`.
2. Human-readable message text is locale/rendering-dependent and not a conformance identity key.
3. Stable diagnostics identity for i18n is carried by:
- `diagnostic code`,
- `phase`,
- `message template id` (token),
- and primary attribution.
4. Parser recovery is allowed to continue diagnostics, but recovered AST must remain structurally coherent and attribution-consistent.
5. Recovery must not fabricate permissive valid shapes that hide real syntax failures.
6. Gate U AST evidence must include:
- representative valid AST fixtures,
- malformed/recovery fixtures,
- deterministic diagnostics assertions,
- and attribution assertions (`file/start/end`) on required nodes.
7. Minimum mandatory negative fixture families include:
- unexpected token in declaration context,
- missing required closer (`)`, `}`, or `;`) as applicable,
- non-associative forbidden chain forms,
- unsupported form outside the active syntax slice with deterministic rejection.
## Invariants
1. Diagnostics identity is token-based and locale-agnostic.
2. Recovery cannot downgrade a required rejection into accepted semantics.
3. AST attribution quality remains sufficient for `12` diagnostics contract and `13` lowering preconditions.
4. Gate U fixtures must lock rejection stability for required AST-facing failures.
## Explicit Non-Decisions
1. This decision does not define transport-specific wire schemas.
2. This decision does not define static type-checking rules.
3. This decision does not define backend/runtime/verifier algorithms.
4. This decision does not require one exact localized wording set.
## Spec Impact
1. `docs/pbs/specs/11. AST Specification.md` must encode recovery integrity and AST-facing rejection/recovery invariants.
2. `docs/pbs/specs/12. Diagnostics Specification.md` remains authority for diagnostics identity fields, including template/token identity.
3. `docs/general/specs/13. Conformance Test Specification.md` provides Gate U evidence obligations referenced here.
## Validation Notes
Gate U validation should assert:
1. stable diagnostic identity keys (`code`, `phase`, template/token id, primary attribution),
2. recovery integrity without semantic masking,
3. deterministic results for the mandatory negative fixture families above.

51
docs/compiler/pbs/decisions/AST Statements and Expressions Decision.md
View File

@ -1,51 +0,0 @@
# AST Statements and Expressions Decision
Status: Accepted
Date: 2026-03-05
Related Agenda: `docs/pbs/agendas/archive/11.3. AST Workshop 3 - Statements and Expressions.md`
## Context
After closing AST contract/root and declaration surfaces, PBS needed a precise v1 decision for statement/expression AST obligations, including precedence/associativity representation, unsupported-form behavior, and Gate U evidence.
## Decision
PBS adopts the following statement/expression AST policy for v1:
1. Mandatory statement/expression AST families must cover the supported PBS core syntax slice, including at minimum:
- statements: `block`, `let`, `return`, expression statement, and other supported statement forms;
- expressions: `identifier`, literals, `unary`, `binary`, `call`, `group`, and other supported expression forms.
2. Precedence and associativity parsing outcomes are normative via AST shape and must be preserved explicitly.
3. Non-associative or forbidden chained forms are deterministic reject with stable diagnostics.
4. AST remains structural; semantic compatibility/type decisions are owned by static semantics/linking phases.
5. Unsupported statement/expression forms are deterministic reject and must not be represented by permissive synthetic placeholder nodes that mask real rejection.
6. Parser recovery may continue after syntax errors, but recovered AST must remain structurally coherent with stable attribution.
7. Gate U evidence must include positive and negative fixtures with AST-shape assertions and diagnostics assertions.
## Invariants
1. Statement/expression AST obligations are implementation-language agnostic.
2. AST shape must not be post-rewritten in a way that changes source-observable parse meaning.
3. Required nodes for diagnostics/lowering must preserve stable `file/start/end`.
4. Recovery must preserve integrity and must not silently convert invalid syntax into valid semantics.
## Explicit Non-Decisions
1. This decision does not define static type-checking algorithms.
2. This decision does not define `IRBackend -> IRVM` lowering.
3. This decision does not define runtime/bytecode/verifier policy.
4. This decision does not freeze one parser implementation strategy.
## Spec Impact
1. `docs/pbs/specs/11. AST Specification.md` must encode statement/expression node-family obligations, precedence/associativity shape obligations, and recovery/rejection invariants.
2. `docs/pbs/specs/12. Diagnostics Specification.md` remains the authority for stable diagnostics identity/phase/attribution requirements.
3. `docs/pbs/specs/13. Lowering IRBackend Specification.md` may assume statement/expression AST invariants as lowering preconditions.
## Validation Notes
Gate U evidence (per `docs/general/specs/13. Conformance Test Specification.md`) should include:
1. valid fixtures proving expected precedence/associativity AST shape;
2. invalid fixtures for non-associative or unsupported forms with deterministic diagnostics;
3. assertions for stable node attribution (`file/start/end`) where diagnostics and lowering consume those nodes.

154
docs/compiler/pbs/decisions/Allocation and Cost Visibility Decision.md
View File

@ -1,154 +0,0 @@
# Allocation and Cost Visibility Decision
Status: Accepted (Implemented)
Cycle: Initial allocation-and-cost closure pass
## 1. Context
PBS v1 needs a minimal but explicit contract for which runtime cost facts matter semantically and which belong only to diagnostics/profiling quality.
Earlier decisions already fixed important inputs:
- `bind(context, fn_name)` has real retention/storage consequences,
- `optional`, `result`, `handle`, `!`, `if`, and `switch` are not intended to hide implicit allocation semantics,
- host/userland interaction is stack-only across the boundary,
- and value categories already distinguish copied payload from preserved aliasing.
## 2. Decision
PBS v1 adopts the following cost-visibility baseline:
1. The normatively relevant cost facts are:
- whether an operation may allocate VM-owned runtime storage,
- whether an operation retains state beyond the current evaluation,
- whether an operation copies payload versus preserves aliasing,
- whether an operation crosses the host boundary,
- and whether an operation may trap.
2. `bind(context, fn_name)` is normatively retention-bearing and requires runtime storage sufficient to keep the callback target and captured context alive.
3. `apply` is not allocation-bearing by itself.
4. `optional`, `result`, `handle`, `!`, `if`, and `switch` are not allocation-bearing by themselves.
5. Host-boundary crossing is a normatively relevant cost fact, but concrete host-side allocation details belong to subsystem-specific contracts rather than to a general PBS rule.
6. Quantitative reporting such as exact byte counts, exact object counts, or precise collector timing is not a normative language guarantee in v1.
## 3. Normatively Relevant Cost Facts
The following cost facts are part of the PBS semantic model and may be relied on by later tooling/spec work:
- VM allocation-bearing versus non-allocation-bearing behavior,
- retention-bearing versus non-retention-bearing behavior,
- copy versus aliasing preservation,
- host-boundary crossing,
- trap possibility.
These facts matter because they affect how advanced tooling, diagnostics, and performance reasoning should interpret a construct.
## 4. `bind`
`bind(context, fn_name)` is the strongest closed cost case in the current PBS core.
Rules:
- `bind` is not semantically free,
- `bind` is retention-bearing,
- `bind` requires runtime storage sufficient to preserve the callback target and captured context,
- the captured context remains alive while the callback value remains alive.
This decision does not require the spec to freeze the exact runtime layout used to implement that storage.
## 5. Non-Allocation-Bearing Surfaces
The following constructs are not allocation-bearing by themselves in PBS v1:
- `optional`
- `result`
- `handle`
- `!`
- `if`
- `switch`
- `apply`
If allocation or retention occurs while evaluating one of these constructs, that cost arises from:
- subexpression evaluation,
- called targets,
- payload formation already defined elsewhere,
- or runtime behavior outside the surface itself.
## 6. Copy Versus Aliasing
Copy versus aliasing is a normatively relevant cost fact.
The language already distinguishes:
- pure values copied by value,
- identity-bearing values passed by preserved aliasing,
- carriers that preserve the semantics of their contained values.
Tooling and later specs may rely on these distinctions even if PBS v1 does not require a warning at every such site.
## 7. Host Boundary
Crossing the host boundary is a normatively relevant cost fact.
However, this decision does not impose a universal rule for:
- host-side allocation volume,
- host-side object count,
- or host-side retention internals.
Those details belong to subsystem-specific contracts when and if they become relevant.
## 8. Normative Versus Best-Effort Reporting
### 8.1 Normative facts
The following facts are normative and may be surfaced by diagnostics/tooling:
- whether a construct is retention-bearing,
- whether a construct crosses the host boundary,
- whether semantics preserve aliasing or copy payload,
- whether a construct may trap.
### 8.2 Best-effort facts
The following facts are not normative language guarantees in v1:
- exact byte counts,
- exact object counts,
- exact collector timing,
- exact host-side allocation volume,
- precise performance ranking beyond the semantic facts above.
These may be surfaced by implementations as profiling or tooling enrichment, but they are not part of the core language contract.
## 9. Invariants
- The language must not imply hidden allocation semantics where none were intentionally specified.
- `bind` remains the canonical retention-bearing callback-forming construct in v1.
- Cost visibility must be strong enough for advanced tooling without forcing exact runtime accounting into the language spec.
- Host-boundary cost reporting must not pretend to know subsystem-specific runtime internals unless those are explicitly specified.
## 10. Explicit Non-Decisions
This decision record does not yet close:
- the final diagnostics wording for warnings or notes,
- subsystem-specific host cost contracts,
- precise collection/profiling metrics,
- optimizer-facing reporting policy.
## 11. Spec Impact
This decision should feed at least:
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
## 12. Validation Notes
The intended split is:
- semantic cost facts are explicit,
- `bind` is the main retained-storage construct already closed,
- most other core surfaces are not allocation-bearing by themselves,
- and quantitative performance reporting remains tooling-quality rather than normative language behavior.

133
docs/compiler/pbs/decisions/Artifact-Level Conformance and Fixture Model Decision.md
View File

@ -1,133 +0,0 @@
# Artifact-Level Conformance and Fixture Model Decision
Status: Superseded
Cycle: Conformance agenda closure pass
Superseded by:
- `docs/general/specs/13. Conformance Test Specification.md` (Quality-Gate Baseline)
- `docs/general/specs/19. Verification and Safety Checks Specification.md` (Quality-Gate Baseline)
Superseded on: 2026-03-04
## 1. Context
PBS v1 needed a decision for the point where conformance stops being source-only and begins asserting artifact-facing behavior.
The open questions from the conformance agenda closure pass and Workshop 3 were:
- whether artifact-level conformance is mandatory for every claim or only for full toolchain claims,
- whether conformance should snapshot whole binaries or only stable invariants,
- what the smallest honest fixture model is for stdlib and host-backed scenarios,
- and how `13`, `12`, `15`, and `19` divide responsibility.
The adopted direction needed to keep full conformance meaningful without freezing one emitter layout, one repository structure, or one implementation-specific binary image.
## 2. Decision
PBS v1 adopts the following artifact-level conformance baseline:
1. Artifact-level conformance belongs only to `full toolchain conformance`.
2. `frontend conformance` and `source-runtime conformance` do not require artifact-level oracle checks.
3. Full toolchain conformance must assert stable artifact invariants rather than one opaque byte-for-byte binary snapshot.
4. The conformance fixture model must explicitly declare the resolved environment assumptions that affect observable admission or lowering behavior.
5. `12` defines what semantic and artifact-boundary facts lowering must preserve.
6. `15` defines how the conformance-facing artifact facts appear in PBX/bytecode-visible form.
7. `19` defines which later safety and validation obligations are checked by loader and verifier rather than by lowering itself.
## 3. Artifact-Level Oracle Baseline
The v1 artifact-level oracle is invariant-based.
Full toolchain conformance must be able to assert, at minimum:
1. required canonical host-binding declarations are emitted for admitted host-backed uses;
2. `SYSC` entries are deduplicated by canonical identity;
3. `SYSC` entry order follows first occurrence in the lowered program;
4. host-backed callsites are emitted in pre-load form as `HOSTCALL <sysc_index>` referencing the emitted canonical binding set;
5. VM-owned builtin projections, builtin constants, and intrinsic callsites do not leak into host-binding metadata such as `SYSC`;
6. stdlib interface modules remain compile-time-only and do not emit executable bytecode by themselves;
7. emitted artifacts preserve at least one source-attribution hook for backend failures that remain source-attributable and user-actionable under the diagnostics contract.
This baseline does not require:
- one full PBX binary snapshot,
- one exact section byte layout outside the stable invariants above,
- one exact source-map format,
- or one verifier-internal trace shape.
## 4. Fixture Model
Conformance fixtures must model the resolved environment honestly whenever the selected environment affects acceptance, lowering, or artifact meaning.
Every fixture that depends on environment selection must declare, as applicable:
- selected stdlib environment or reserved stdlib line,
- selected host registry line,
- granted capability set,
- and selected runtime line.
If an axis is irrelevant for a fixture, the fixture should declare that explicitly rather than leaving it implicit.
The minimum reusable fixture families for v1 are:
1. source-only fixtures whose expectations do not depend on host registry or runtime selection;
2. stdlib-resolved fixtures that name the selected stdlib environment when reserved modules affect acceptance or behavior;
3. host-admitted fixtures that name both host registry line and granted capabilities for positive host-backed cases;
4. host-rejected fixtures that name the missing or unauthorized capability or host-registry condition for deterministic negative cases;
5. full-toolchain artifact fixtures that name the runtime line whenever emitted intrinsic or host-binding form depends on the selected executable target line.
This model is intentionally small. It is sufficient to prevent fake portability claims while avoiding one mandatory repository layout.
## 5. Boundary Across `13`, `12`, `15`, and `19`
The adopted boundary is:
- `13. Conformance Test Specification.md` defines which invariant families are pass/fail conformance obligations and which fixture assumptions must be declared;
- `13. Lowering IRBackend Specification.md` defines the semantic and artifact-boundary facts that lowering must preserve before loader or verifier work begins;
- `15. Bytecode and PBX Mapping Specification.md` defines the PBX/bytecode-visible mapping of those facts into inspectable artifact surfaces;
- `19. Verification and Safety Checks Specification.md` defines the later validation and rejection obligations applied after lowering and, where relevant, after loader patching.
Conformance therefore does not require `12` to define one binary encoding and does not require `15` to redefine semantic ownership already fixed in `12`.
## 6. Invariants
- Artifact-level conformance is required only for the full toolchain claim.
- The v1 artifact oracle is invariant-based, not whole-image-based.
- Fixture assumptions that change observable behavior must be explicit.
- Host-binding metadata remains distinct from VM-owned builtin and intrinsic lowering.
- The boundary among lowering, encoding, and verification must remain reviewable and non-overlapping.
- Source-attributable backend failures must retain at least one recoverable source location, but richer debug surfaces remain optional.
## 7. Explicit Non-Decisions
This decision record does not yet close:
- which PBX sections beyond the current stable invariant baseline become part of the PBS-facing contract,
- whether intrinsic declarations require an additional dedicated PBX preload section in v1,
- the full verifier test surface for conformance,
- the compatibility-matrix policy for aging and retirement of published combinations,
- or one repository structure for the conformance corpus.
## 8. Spec Impact
This decision should feed at least:
- `docs/general/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
It should also constrain later work in:
- `docs/general/specs/19. Verification and Safety Checks Specification.md`
- `docs/general/specs/17. Compatibility and Evolution Policy.md`
- `docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md`
- `docs/pbs/agendas/13.4. IR and Lowering Workshop 4 - Builtins, Host Bindings, and Artifact Invariants.md`
## 9. Validation Notes
The intended operational reading is:
- a direct interpreter may still claim `source-runtime conformance` without artifact checks,
- a full compiler toolchain must expose enough artifact surface to prove the stable invariants above,
- and a host-backed test is not valid conformance evidence unless the selected registry, capability set, and runtime assumptions are declared where they affect the outcome.

164
docs/compiler/pbs/decisions/Compatibility Matrix and Published Claims Decision.md
View File

@ -1,164 +0,0 @@
# Compatibility Matrix and Published Claims Decision
Status: Superseded
Cycle: Conformance and compatibility agenda closure pass
Superseded by:
- `docs/general/specs/13. Conformance Test Specification.md` (Quality-Gate Baseline)
- `docs/general/specs/17. Compatibility and Evolution Policy.md` (Quality-Gate Baseline)
Superseded on: 2026-03-04
## 1. Context
PBS v1 needed one operational policy for how support claims are published, tested, aged, and retired over time.
The open questions from the conformance closure pass, especially Workshop 4, and from `17. Compatibility and Evolution Policy Agenda.md`, Workshop 3 were:
- what enters the regression corpus,
- which compatibility dimensions PBS must publish explicitly,
- what counts as a published support claim,
- how claims relate to conformance evidence,
- and how supported combinations retire without becoming ambiguous.
The adopted direction needed to ensure that compatibility tables and support statements are executable commitments rather than prose-only promises.
## 2. Decision
PBS v1 adopts the following baseline policy:
1. Published support claims must be represented by an explicit compatibility matrix.
2. Every published supported combination must be backed by maintained conformance or regression evidence appropriate to the claim level being published.
3. The regression corpus is not limited to bug reproductions; it also includes already-published normative examples, accepted behavior claims, and supported matrix combinations.
4. Unsupported combinations must be stated explicitly rather than inferred from silence.
5. Claim retirement must be deliberate: when support narrows or ends, the matrix entry, supporting tests, and migration/support note must all change together.
## 3. Compatibility Matrix Baseline
The minimum PBS compatibility matrix must expose, at minimum, the following dimensions where support is published:
1. language line,
2. stdlib line when reserved stdlib environment selection affects the claim,
3. runtime line when execution target selection affects the claim,
4. conformance claim level.
The matrix must also expose an explicit support state for each published combination.
The minimum support states are:
- `supported`
- `unsupported`
- `provisional`
Meanings:
- `supported` means the combination is promised by the publisher and backed by maintained evidence.
- `unsupported` means the combination is intentionally not promised and tools may reject or decline it without violating the published support policy.
- `provisional` means the combination is published as incomplete or experimental and must not be confused with ordinary stable support.
Silence must not be used where a published matrix exists and a reasonable reader could infer support.
## 4. Published Claims and Evidence
A published support claim exists whenever a publisher represents, in user-facing or tool-facing form, that a combination or behavior is supported, conforming, or maintained.
This includes, at minimum:
- a matrix entry marked `supported`,
- an unqualified or qualified PBS conformance claim,
- compatibility statements in product or release documentation,
- and published examples or fixtures presented as normative or supported behavior.
Every published claim must map to maintained executable evidence.
The evidence may be:
- conformance tests,
- regression tests,
- or both,
provided the evidence covers the claim scope actually being published.
`frontend conformance`, `source-runtime conformance`, and `full toolchain conformance` may therefore have different evidence sets, but each published claim still needs evidence inside its own scope.
## 5. Regression Corpus Policy
The regression corpus must preserve already-published behavior inside the scope of active support claims.
At minimum, the regression corpus must include:
1. bug reproductions for behavior that was fixed and remains within a supported scope;
2. published examples that are treated as normative or supported behavior;
3. accepted conformance claims and the behavior they promise;
4. supported compatibility-matrix combinations and their required outcomes.
The regression corpus may be organized into separate slices by claim level or domain.
What matters normatively is:
- published supported behavior is regression-protected,
- evidence remains attributable to the claim it protects,
- and narrowing support requires deliberate retirement rather than silent drift.
## 6. Retirement and Narrowing Policy
When a supported combination is retired or narrowed:
1. the matrix entry must change explicitly;
2. the old support state must not remain implied by stale documentation;
3. the corresponding evidence must be retired, reclassified, or moved to a historical/non-supporting corpus deliberately;
4. a migration, support-boundary, or rationale note must accompany the change when users could reasonably depend on the retired combination.
Retirement does not require one universal changelog format in this decision.
It does require that the support boundary become visible and reviewable.
## 7. Boundary Between `13` and `17`
The adopted split is:
- `13. Conformance Test Specification.md` defines the executable evidence obligations: what must enter the conformance or regression corpus and how supported claims become test-backed;
- `17. Compatibility and Evolution Policy.md` defines the publication policy: which matrix dimensions and support states are required and how supported combinations age or retire.
This keeps `13` test-oriented and `17` promise-oriented while ensuring both documents describe the same support contract.
## 8. Invariants
- Published support claims must be test-backed.
- A compatibility matrix is normative only when its states have executable meaning.
- `unsupported` must be explicit when omission would mislead users.
- `provisional` must not be mistaken for ordinary supported compatibility.
- Regression protection follows published supported behavior, not only bug history.
- Narrowing support is a deliberate policy act, not an accidental omission.
## 9. Explicit Non-Decisions
This decision record does not yet close:
- exact compatibility-window lengths by domain,
- exact migration-tooling triggers,
- PBX-specific binary compatibility policy,
- release tooling implementation,
- or one repository layout for matrix and regression data.
## 10. Spec Impact
This decision should feed at least:
- `docs/general/specs/13. Conformance Test Specification.md`
- `docs/general/specs/17. Compatibility and Evolution Policy.md`
It should also constrain later work in:
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/pbs/agendas/17.4. Compatibility Workshop 4 - Artifact and PBX Compatibility Policy.md`
## 11. Validation Notes
The intended operational reading is:
- if a publisher marks one matrix row as `supported`, there must be maintained evidence for that row;
- if a combination is no longer supported, the matrix must say so explicitly rather than simply dropping mention of it;
- and if an example or claim is published as supported behavior, it belongs in the regression story even if it did not originate as a bug report.

167
docs/compiler/pbs/decisions/Conformance Claim Levels Decision.md
View File

@ -1,167 +0,0 @@
# Conformance Claim Levels Decision
Status: Superseded
Cycle: Conformance agenda closure pass
Superseded by:
- `docs/general/specs/13. Conformance Test Specification.md` (Quality-Gate Baseline)
- `docs/general/specs/17. Compatibility and Evolution Policy.md` (Quality-Gate Baseline)
Superseded on: 2026-03-04
## 1. Context
PBS v1 needed a conformance-claim model that stays honest while the conformance corpus matures across frontend, runtime, and artifact-facing work.
The open questions from the conformance agenda closure pass and Workshop 1 were:
- whether PBS should use one conformance label or staged claims,
- what a partial implementation is allowed to claim,
- how published conformance claims must describe missing coverage,
- and how claim levels constrain later compatibility policy.
The adopted direction needed to avoid two failure modes:
- pretending an unfinished backend is already full PBS v1 conformance,
- and allowing vague marketing language that hides excluded domains such as artifact emission or verifier behavior.
## 2. Decision
PBS v1 adopts staged conformance claims.
The canonical claim levels are:
1. `frontend conformance`
2. `source-runtime conformance`
3. `full toolchain conformance`
These claims mean:
1. `frontend conformance` covers deterministic source acceptance and rejection behavior through parsing, manifest/import resolution, linking/static semantics, and the stable diagnostics surface required for those rejection tests.
2. `source-runtime conformance` covers all frontend obligations plus source-level runtime, memory/identity, and host-boundary behavior already defined as language-observable in the active specs.
3. `full toolchain conformance` covers all source-runtime obligations plus the artifact-facing, loader-facing, verifier-facing, and compatibility obligations required by the full active PBS v1 spec set.
Only `full toolchain conformance` may be published without qualifier as `PBS v1 conforming`.
Any narrower claim must remain explicitly qualified in published wording, for example:
- `PBS v1 frontend conforming`
- `PBS v1 source-runtime conforming`
An implementation that does not satisfy one complete canonical level must not claim PBS conformance merely because it implements a subset such as parsing-only or parser-plus-binder behavior.
Any partial claim must explicitly state excluded domains when they matter to user expectations, including as applicable:
- artifact emission,
- loader interaction,
- verifier behavior,
- supported runtime line,
- selected stdlib environment,
- host-registry line,
- and capability assumptions.
The unqualified claim `PBS v1 conforming` is reserved until the artifact-facing conformance surface is fully closed in `13`, `12`, `15`, and `19`.
## 3. Claim Meanings
### 3.1 Frontend Conformance
`frontend conformance` is the minimum canonical PBS conformance claim.
It requires:
- deterministic parsing behavior,
- deterministic source rejection for in-scope syntax, linking, and static-semantics failures,
- deterministic manifest/import resolution outcomes,
- regression protection for already-published behavior inside that claim scope,
- and the stable diagnostics fields required by the diagnostics contract for those failures.
It does not imply:
- runtime execution support,
- host-backed call execution,
- artifact emission,
- loader integration,
- or verifier integration.
### 3.2 Source-Runtime Conformance
`source-runtime conformance` extends `frontend conformance`.
It additionally requires:
- source-level runtime oracle coverage,
- source-level memory and identity oracle coverage,
- host-boundary behavior already fixed by the Host ABI and capability specs at source-visible level,
- and regression protection for already-published behavior inside that claim scope.
It does not by itself imply:
- one normative PBX image shape,
- one artifact-level golden contract,
- loader patching behavior beyond source-visible requirements,
- or verifier-surface conformance.
### 3.3 Full Toolchain Conformance
`full toolchain conformance` is the top-level PBS v1 conformance claim.
It requires:
- all `source-runtime conformance` obligations,
- all artifact-level oracle requirements once closed,
- loader/verifier-facing acceptance and rejection obligations that belong to PBS-facing conformance,
- required fixture modeling for stdlib, registry, capability, and runtime lines,
- and maintained regression/compatibility evidence for every published supported combination inside the claim.
Until those artifact-facing obligations are normatively closed, implementations may publish only the narrower qualified claims above.
## 4. Naming and Publication Rules
- If the word `conforming` is used in a PBS v1 product claim, it must use one of the canonical claim levels.
- The bare wording `PBS v1 conforming` is reserved for the full toolchain claim only.
- `frontend` and `source-runtime` claims must keep the qualifier adjacent to the published claim and must not be shortened to imply full PBS v1 conformance.
- If an implementation is still below `frontend conformance`, it should describe itself as partial, experimental, or implementation-specific rather than conforming.
- Published conformance claims must state the tested scope when environment selection changes observable behavior.
## 5. Invariants
- PBS conformance is staged, not all-or-nothing, during the v1 maturation path.
- The meaning of the unqualified top-level claim must remain stronger than any partial claim.
- Partial claims must not hide excluded domains behind vague wording.
- Conformance claims and compatibility claims are related but not identical; compatibility policy may refine promise strength per claim level without redefining the claim levels themselves.
- Published claims must be backed by executable evidence in the conformance or regression corpus appropriate to that claim level.
## 6. Explicit Non-Decisions
This decision record does not yet close:
- the full fixture model for stdlib, host-registry, capability, and runtime-line scenarios,
- the final artifact-level oracle for PBX or lowering invariants,
- the compatibility-matrix dimensions and retirement policy,
- or the exact repository layout of the conformance corpus.
## 7. Spec Impact
This decision should feed at least:
- `docs/general/specs/13. Conformance Test Specification.md`
- `docs/general/specs/17. Compatibility and Evolution Policy.md`
It should also constrain later work in:
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/general/specs/19. Verification and Safety Checks Specification.md`
- `docs/pbs/decisions/Artifact-Level Conformance and Fixture Model Decision.md`
- `docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md`
- `docs/pbs/agendas/17.1. Compatibility Workshop 1 - Compatibility Domains and Promise Levels.md`
## 8. Validation Notes
The intended operational reading is:
- a parser-plus-binder implementation may claim `frontend conformance` only if it actually satisfies the complete frontend obligations, including deterministic rejection behavior and the stable diagnostics surface in scope,
- an interpreter or direct-execution implementation may claim `source-runtime conformance` without yet claiming artifact or verifier conformance,
- and no implementation should imply full PBS v1 conformance until the artifact-facing contract is normatively testable.

215
docs/compiler/pbs/decisions/Diagnostics Contract Decision.md
View File

@ -1,215 +0,0 @@
# Diagnostics Contract Decision
Status: Accepted (Implemented)
Cycle: Diagnostics agenda closure pass
## 1. Context
PBS v1 needed one coherent diagnostics contract that closes the open questions from the diagnostics agenda:
- diagnostic identity,
- attribution and cross-file reporting,
- wording and localization boundaries,
- warning and cost-diagnostics policy,
- and the boundary between PBS-facing diagnostics and backend/artifact-facing failures.
The adopted direction needed to stay deterministic and conformance-friendly without freezing one editor UX, one compiler architecture, or one backend-internal reporting format.
## 2. Decision
PBS v1 adopts the following diagnostics baseline:
1. Every PBS-facing diagnostic has a mandatory `diagnostic code`.
2. Every PBS-facing diagnostic has a mandatory `severity`.
3. The stable external diagnostic phases include:
- `syntax`,
- `static semantics`,
- `manifest/import resolution`,
- `linking`,
- `host-binding/capability admission`,
- and load-facing rejection when directly attributable to malformed or unauthorized PBS-facing artifact usage.
4. `linking` is a first-class diagnostics phase and should remain visible to users as part of the didactic pipeline.
5. The minimum source-facing payload is:
- `diagnostic code`,
- `severity`,
- `phase`,
- `primary file`,
- `primary span/location`,
- and a human-readable message.
6. The diagnostics model must also carry a stable `message template id` with stable named placeholders for localized rendering.
7. Human wording is not byte-for-byte normative. The normative contract is the stable association among diagnostic code, message template id, placeholders, and rejection meaning.
8. Implementations may localize rendered messages by language, provided the rendered message preserves the same normative rejection meaning.
9. For future interoperability-oriented transports such as a possible LSP integration, implementations should preserve the ability to render an English default/fallback message even when a product renders another locale locally.
10. In cross-file failures, the primary site must be the source location where the user action triggered the failure.
11. `notes` and `related sites` are optional by default.
12. For `duplicate` and `conflict` classes, at least one related site is mandatory.
13. `hint` is a reserved diagnostics category in v1, but hint content is not mandatory.
14. `help` and guided remediation are outside the core conformance contract in v1.
15. Warnings are supported and recommended in v1, but they are not part of the minimum mandatory conformance baseline.
16. Qualitative cost facts may be surfaced as warnings or notes, especially for:
- retention-bearing `bind`,
- host-boundary crossings,
- and observable copy-versus-alias behavior.
17. Quantitative reporting such as byte counts, allocation counts, and performance ranking is outside the diagnostics contract and belongs to profiling/tooling.
18. Only backend-originated failures that remain source-attributable and user-actionable belong to the PBS-facing diagnostics contract.
19. Pure artifact corruption, verifier internals, loader internals, and compiler implementation bugs remain outside the PBS-facing diagnostics contract unless they are directly attributable to validly analyzed PBS source or to malformed/unauthorized PBS-facing artifact usage already in scope.
20. When a backend-originated failure remains in scope for PBS-facing diagnostics, v1 requires at least one source location but does not require one standardized source-map, artifact-offset, or verifier-trace format.
## 3. Diagnostic Identity and Payload
The minimum stable identity of a PBS-facing diagnostic is not free-form wording.
The stable identity is carried by:
- `diagnostic code`,
- stable phase attribution,
- and the rejection class semantics represented by the code/template pair.
The minimum externally relevant fields are:
- `diagnostic code`,
- `severity`,
- `phase`,
- `primary file`,
- `primary span/location`,
- `message template id`,
- stable named placeholders,
- and a rendered human-readable message.
This baseline keeps diagnostics testable and localizable without forcing one exact byte-for-byte phrasing.
## 4. Cross-File Attribution
Cross-file attribution follows an action-first rule.
Rules:
- import failures point primarily to the importing site,
- barrel failures point primarily to the barrel entry or reference site that triggered the failure,
- linking or cross-module lookup failures point primarily to the use or reference site that could not be resolved,
- related sites may be attached when known,
- and `duplicate` or `conflict` diagnostics must include at least one related site in addition to the primary site.
This keeps diagnostics actionable for users and stable enough for conformance.
## 5. Message Rendering and Localization
PBS v1 permits localized diagnostics, including localized editor-first experiences.
The normative boundary is:
- codes are stable,
- template ids are stable,
- placeholders are stable,
- and rendered wording may vary by locale and product surface.
Examples in specs should therefore be treated as illustrative unless a spec explicitly marks a template shape or placeholder contract as normative.
## 6. Categories, Notes, and Hints
The stable visible categories currently reserved are:
- `error`,
- `warning`,
- `note`,
- `hint`.
`notes` are optional by default in v1.
`hint` exists in the diagnostics model from v1 onward so implementations can grow into educational guidance without changing the core schema.
This decision does not require one exact distinction between short hints and richer remediation flows.
## 7. Warning and Cost-Diagnostics Boundary
PBS v1 deliberately keeps warnings out of the minimum conformance baseline.
This means:
- implementations may emit warnings,
- the editor can use warnings aggressively for pedagogy,
- but conformance does not currently fail merely because an implementation omits optional warnings.
The diagnostics contract does recognize the importance of qualitative cost facts already fixed elsewhere, but it does not promote them to mandatory warnings in v1.
## 8. Backend-Originated Failure Boundary
PBS-facing diagnostics stop where failures stop being source-attributable and user-actionable.
In scope for PBS-facing diagnostics:
- lowering failures that reflect a normative source-facing lowering rule or impossibility,
- verifier or loader rejections that are directly attributable to malformed or unauthorized PBS-facing artifact usage,
- and backend-originated failures that can still be mapped back to source in a way the user can act on.
Out of scope for PBS-facing diagnostics:
- internal compiler exceptions,
- implementation bugs,
- artifact corruption not attributable to valid PBS source or to in-scope malformed/unauthorized artifact usage,
- and backend-internal failure surfaces with no stable user-facing source attribution.
## 9. Conformance Boundary
The conformance surface for diagnostics should check only stable external fields.
Conformance may assert:
- rejection versus acceptance,
- diagnostic code,
- severity/category when in scope,
- phase,
- source attribution,
- and related-site requirements for narrow classes such as `duplicate` or `conflict`.
Conformance should not require:
- one exact rendered message,
- one exact localized wording,
- one exact note shape outside explicitly required classes,
- one verifier/loader internal format,
- or one profiling/reporting style.
Warnings remain outside pass/fail conformance in v1, though any emitted warning must remain semantically compatible with the spec.
## 10. Invariants
- The diagnostics contract must remain deterministic across conforming implementations.
- Diagnostic identity must not depend on one locale or one exact rendered sentence.
- `linking` remains a visible diagnostics phase rather than being collapsed away into a generic resolution bucket.
- Cross-file diagnostics must remain action-oriented from the user's point of view.
- Localized rendering must not erase the stable machine-readable identity of a diagnostic.
- The contract must stay narrow enough that more than one toolchain can implement it.
- Backend-internal reporting must not leak into the PBS language contract unless the failure is source-attributable and user-actionable.
## 11. Explicit Non-Decisions
This decision record does not yet close:
- the full warning catalog for future versions,
- whether a future version promotes a subset of warnings into mandatory conformance,
- exact remediation/help-content policy,
- exact source-map or artifact-offset formats,
- verifier trace schemas,
- transport-specific LSP field mapping,
- or internal compiler bug-reporting policy.
## 12. Spec Impact
This decision should feed at least:
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/general/specs/19. Verification and Safety Checks Specification.md`
## 13. Validation Notes
The intended operational reading is:
- diagnostics are machine-identifiable first and human-rendered second,
- localized editor UX is fully compatible with the contract,
- a future interoperable transport can still fall back to English rendering,
- warnings are available for pedagogy without being required for conformance,
- and backend-originated failures only enter the PBS-facing contract when they still behave like actionable source diagnostics rather than internal tool failures.

210
docs/compiler/pbs/decisions/Diagnostics, Manifest Propagation, and Conformance Coverage Decision.md
View File

@ -1,210 +0,0 @@
# Diagnostics, Manifest Propagation, and Conformance Coverage Decision
Status: Accepted
Date: 2026-03-22
Related Agenda: `docs/compiler/pbs/agendas/19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda.md`
## Context
After closing globals, lifecycle markers, published wrapper ownership, and lowering structure, PBS v1 still needed one final consolidation step for topic `19`.
The remaining work was no longer architectural debate.
It was operational consolidation across the whole line:
- which diagnostics are now mandatory,
- which phase owns each failure surface,
- which specs and cross-domain artifacts must be updated,
- and what minimum conformance evidence is required before execution planning begins.
Important fixed inputs already existed:
- `19.1` closed the source surface and dependency rules for globals;
- `19.2` closed lifecycle markers, init ordering, and init restrictions;
- `19.3` closed published wrapper ownership, physical entrypoint `0`, and manifest protocol direction;
- `19.4` closed explicit lowering structure, synthetic callable classes, hidden boot guard policy, and lowering-side invariants.
## Decision
PBS accepts the following consolidation for topic `19`:
1. The diagnostics line for family `19` is grouped by phase rather than by historical agenda order.
2. The final propagation line for family `19` must name PBS specs, general compiler specs, runtime cross-domain ownership, and `learn`.
3. The conformance line for family `19` must cover positive flow, negative frontend coverage, negative lowering coverage, and runtime integration.
4. Runtime-side work required by entrypoint protocol changes remains explicitly cross-domain and is owned through:
- `../runtime/docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`
## Consolidated Diagnostics
PBS adopts the following minimum diagnostics and failure surfaces for family `19`.
### Frontend / Static Semantics
The compiler must provide, at minimum:
1. `global initializer uses unsupported form`
2. `global dependency cycle detected`
3. `imported symbol shadows existing visible symbol; alias required`
4. `global import must resolve through a global barrel entry`
5. `init function must have signature fn name() -> void`
6. `frame function must have signature fn name() -> void`
7. `multiple module init functions detected`
8. `multiple project init functions detected`
9. `multiple frame functions detected`
10. `missing frame function for executable project`
11. `Init attribute target invalid`
12. `project init must be colocated with frame`
13. `InitAllowed is valid only on SDK host methods`
14. `host call not allowed during init`
### Lowering / Structural Validation
The lowering line must enforce, at minimum:
1. `synthetic wrapper entrypoint missing`
2. `published entrypoint is not function index 0`
3. `hidden boot guard is missing`
4. `synthetic callable origin missing`
These may appear as backend diagnostics, validation failures, or invariant violations, as long as the failure is observable and testable.
### Runtime / Boot Failure
The runtime-facing failure surface must distinguish, at minimum:
1. `boot failed during module init`
2. `boot failed during project init`
These belong to operational boot failure reporting rather than to the static compiler diagnostic catalog.
## Propagation Targets
PBS adopts the following minimum propagation line for family `19`.
### PBS Specs
This decision must propagate to at least:
1. `docs/compiler/pbs/specs/3. Core Syntax Specification.md`
2. `docs/compiler/pbs/specs/4. Static Semantics Specification.md`
3. `docs/compiler/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md`
4. `docs/compiler/pbs/specs/9. Dynamic Semantics Specification.md`
5. `docs/compiler/pbs/specs/11. AST Specification.md`
6. `docs/compiler/pbs/specs/12. Diagnostics Specification.md`
7. `docs/compiler/pbs/specs/13. Lowering IRBackend Specification.md`
### General Compiler Specs
This decision must also propagate to at least:
1. `docs/compiler/general/specs/15. Bytecode and PBX Mapping Specification.md`
2. `docs/compiler/general/specs/20. IRBackend to IRVM Lowering Specification.md`
### Runtime Cross-Domain Owner
The runtime half of the protocol change remains explicitly cross-domain and must be tracked through:
1. `../runtime/docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`
### Learn
PBS must also produce a consolidated `learn` artifact explaining:
1. globals,
2. lifecycle markers,
3. published wrapper composition,
4. fixed entrypoint protocol,
5. and the relationship between source flow and lowered artifacts.
## Conformance Matrix
PBS adopts the following minimum conformance matrix for family `19`.
### Positive Coverage
At minimum, one positive fixture must cover:
1. `declare global`
2. file-level `[Init]`
3. project-level `[Init]`
4. `[Frame]`
That fixture must provide evidence for:
1. accepted globals and ordering,
2. generated wrapper publication,
3. `func_id = 0`,
4. `FRAME_RET` in the wrapper path,
5. and hidden boot guard presence.
### Negative Frontend Coverage
At minimum, negative frontend coverage must include:
1. `global` using `fn` in its initializer
2. `global` using `if` in its initializer
3. cycle between globals
4. symbol collision between imported and visible `const` / `global` / `service` / `fn`
5. invalid `[Init]` signature
6. invalid `[Frame]` signature
7. multiple `[Frame]`
8. multiple project init candidates
9. project init outside the `[Frame]` file
10. host call during init without `[InitAllowed]`
11. invalid `[InitAllowed]` target
### Negative Lowering Coverage
At minimum, negative lowering coverage must include:
1. missing published wrapper
2. published wrapper outside physical index `0`
3. missing hidden boot guard
4. missing synthetic origin metadata
### Runtime Integration Coverage
At minimum, runtime integration coverage must include:
1. artifact boot through physical entrypoint `0`
2. evidence that runtime boot no longer depends on nominal export resolution
3. coherent fail-fast reporting for module init failure
4. coherent fail-fast reporting for project init failure
## Rationale
This decision intentionally turns the last umbrella stage of topic `19` into an execution gate rather than another semantic layer.
That matters because the line is already architecturally closed.
What remained was the discipline required to make implementation safe:
- explicit diagnostics,
- explicit propagation ownership,
- explicit cross-domain runtime ownership,
- and explicit conformance evidence.
Without this consolidation step, execution work would still have room to drift across specs, runtime, and compiler validation.
## Invariants
1. Family `19` diagnostics remain partitioned by phase.
2. Family `19` propagation remains explicit across PBS specs, general specs, runtime, and `learn`.
3. Runtime entrypoint-protocol work remains a named cross-domain dependency rather than an implicit follow-up.
4. Family `19` is not considered implementation-ready without the declared conformance matrix.
## Explicit Non-Decisions
1. This decision does not redefine globals surface semantics.
2. This decision does not redefine lifecycle marker semantics.
3. This decision does not redefine published wrapper ownership.
4. This decision does not redefine lowering structure.
5. This decision does not replace the runtime-domain decision work required outside the PBS domain.
## Execution Readiness
With this decision accepted, family `19` is considered ready to move into `pull-request/plan` decomposition for:
1. spec propagation,
2. compiler implementation,
3. runtime cross-domain coordination,
4. diagnostics integration,
5. and conformance fixture execution.

128
docs/compiler/pbs/decisions/Dynamic Semantics - Branch Selection Decision.md
View File

@ -1,128 +0,0 @@
# Dynamic Semantics - Branch Selection Decision
Status: Accepted (Implemented)
Cycle: Initial branch-selection closure pass
## 1. Context
PBS v1 needs a closed runtime contract for `if` and `switch` before the dynamic semantics spec can be completed.
The remaining questions were:
- whether conditions and selectors are evaluated once,
- whether non-selected branches evaluate at all,
- which selector categories are admitted for `switch`,
- and whether branch selection itself may trap.
## 2. Decision
PBS v1 adopts the following branch-selection rules:
1. `if` evaluates its condition exactly once.
2. `switch` evaluates its selector exactly once.
3. Only the selected branch or arm executes.
4. Non-selected branches and arms perform no evaluation.
5. `if` and `switch` are trap-free by themselves; only selected subexpressions may trap.
6. `switch` is limited to statically discriminable selector categories.
7. `switch` does not accept `result`, `error`, structs, string objects, or heap-backed types as selectors in v1.
## 3. `if`
For:
```text
if cond { then_block } else { else_block }
```
the runtime behaves as follows:
1. evaluate `cond` exactly once,
2. if it yields `true`, execute only `then_block`,
3. if it yields `false`, execute only `else_block`.
The non-selected branch is not evaluated, even partially.
Any trap associated with `if` arises only from:
- evaluating `cond`,
- or executing the selected branch.
## 4. `switch`
### 4.1 Selector evaluation
For:
```text
switch selector { ... }
```
the runtime:
1. evaluates `selector` exactly once,
2. determines the matching arm using the canonical matching rule for the selector category,
3. executes exactly one selected arm.
No non-selected arm is evaluated.
### 4.2 Admitted selector categories
In v1, `switch` is restricted to selector categories with static, deterministic matching behavior.
These include:
- literal-comparable scalar values,
- enum values,
- `str` values with canonical static identity,
- and other compile-time-constant-compatible selector categories only if explicitly admitted elsewhere.
`switch` does not accept:
- `result` values,
- `error` values,
- structs,
- string object/reference types distinct from canonical `str`,
- or heap-backed selector categories.
Dynamic or structural matching belongs to a future `match`-style construct rather than to `switch`.
### 4.3 Matching rule
`switch` arm selection is exact and deterministic for the admitted selector type.
- Enum selectors match by canonical enum-case identity.
- Scalar selectors match by the exact equality rule already defined for that scalar category.
- `str` selectors match by canonical static string identity rather than by heap-object comparison.
`switch` does not perform structural matching, guard evaluation, or user-defined equality dispatch.
## 5. Invariants
- `if` and `switch` never evaluate more than one branch or arm.
- Branch selection is deterministic for the same selector value.
- `switch` remains a static discriminant-selection construct, not a result/error-processing construct.
- Error processing with logic belongs to `handle`, not to `switch`.
## 6. Explicit Non-Decisions
This decision record does not yet close:
- the final future design of `match`,
- whether additional scalar-like selector categories will be admitted later,
- the complete memory/cost wording associated with selector evaluation.
## 7. Spec Impact
This decision should feed at least:
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
- `docs/pbs/specs/4. Static Semantics Specification.md`
- `docs/pbs/specs/3. Core Syntax Specification.md`
## 8. Validation Notes
The intended split is:
- `if` and `switch` perform static, deterministic branch selection,
- `handle` processes modeled `result` errors,
- future dynamic or structural branching belongs to `match`, not to `switch`.

355
docs/compiler/pbs/decisions/Dynamic Semantics - Effect Surfaces Decision.md
View File

@ -1,355 +0,0 @@
# Dynamic Semantics - Effect Surfaces Decision
Status: Accepted (Implemented)
Cycle: Initial effect-surfaces closure pass
## 1. Context
PBS v1 already commits to several effect and control surfaces in syntax and static semantics, but their runtime behavior must be closed before normative dynamic semantics can be written.
This decision record captures the first closed subset of that work:
- `optional`,
- `result<E>`,
- `!` propagation,
- `handle` processing.
Allocation, retention, copy visibility, and heap-facing cost wording are delegated to the memory and heap decision track.
## 2. Decision
PBS v1 adopts the following baseline runtime rules for `optional` and `result<E>` surfaces:
1. `optional` is a runtime presence/absence carrier with canonical `some(payload)` and `none` states.
2. `some(expr)` evaluates `expr` eagerly and exactly once before forming the `some` carrier.
3. `opt else fallback` evaluates the left operand exactly once and evaluates `fallback` only when the left operand is `none`.
4. `optional` is trap-free by itself; only subexpression evaluation may trap.
5. `result<E>` is the runtime carrier for expected, modelable failure in function return flow.
6. `expr!` evaluates `expr` exactly once and performs immediate enclosing-function error propagation on failure.
7. `handle expr { ... }` evaluates `expr` exactly once and, on error, executes exactly one matching arm.
8. A `handle` arm may execute user-defined logic.
9. A `handle` arm must terminate with either `ok(payload)` or `err(E2.case)`.
10. `ok(payload)` in a `handle` arm recovers locally and yields the payload as the value of the `handle` expression.
11. `err(E2.case)` in a `handle` arm performs immediate enclosing-function return with that error.
12. `handle` supports a short remap form `E1.case -> E2.case` as sugar for a block that returns `err(E2.case)`.
13. Neither `!` nor `handle` intercepts or converts traps.
14. `apply` is the canonical universal call surface for PBS v1 across all callable categories.
15. `apply` chains parse right-associatively but preserve the already-closed left-to-right observable evaluation model.
16. `apply` does not introduce implicit composition of `optional` or `result` surfaces.
17. `bind(context, fn_name)` forms a nominal callback value by attaching a struct context to a top-level function target.
18. `bind` evaluates its context expression exactly once, captures the same runtime context identity without copying it, and injects that context as the first argument when the callback is invoked.
19. `bind` is not a general closure mechanism and is trap-free at the language level.
## 3. `optional`
### 3.1 Runtime model
`optional` has exactly two runtime states:
- `some(payload)`
- `none`
`none` is the canonical absence of payload.
### 3.2 Construction
`some(expr)`:
- evaluates `expr` eagerly,
- evaluates it exactly once,
- then forms the `some(payload)` carrier from the produced payload.
### 3.3 Extraction
`opt else fallback`:
1. evaluates `opt` exactly once,
2. if the result is `some(payload)`, yields the extracted payload and does not evaluate `fallback`,
3. if the result is `none`, evaluates `fallback` and yields that value.
`else` is extraction with fallback, not error handling.
### 3.4 Trap behavior
`optional` itself does not trap.
Any trap associated with `some(expr)` or `opt else fallback` arises only from:
- evaluating `expr`,
- evaluating the left operand,
- or evaluating the fallback when it is needed.
## 4. `result<E>`
### 4.1 Runtime role
`result<E>` is the runtime carrier for success-or-modeled-failure at function boundaries and in expressions whose static type is `result<E> P`.
In v1, `ok(...)` and `err(...)` are special result-flow forms.
They are not general-purpose first-class userland constructors for arbitrary data modeling.
They are valid in:
- function return flow for `result<E>`,
- and `handle` arms, where they control recovery or propagation.
### 4.2 `!` propagation
`expr!`:
1. evaluates `expr` exactly once,
2. if `expr` yields success, yields the extracted success payload as the value of the expression,
3. if `expr` yields error, performs immediate enclosing-function return with the same `err(...)`.
`!` does not:
- remap the error,
- intercept traps,
- or continue ordinary evaluation after the propagated error path is chosen.
### 4.3 `handle`
`handle expr { ... }`:
1. evaluates `expr` exactly once,
2. if `expr` yields success, yields the extracted success payload directly,
3. if `expr` yields error, selects exactly one matching handle arm,
4. executes the selected arm,
5. requires that arm to terminate with either `ok(payload)` or `err(E2.case)`.
### 4.4 `handle` arm results
The selected `handle` arm has two admissible result forms:
- `ok(payload)`
- `err(E2.case)`
Their semantics are:
- `ok(payload)` recovers locally and makes the `handle` expression yield `payload`,
- `err(E2.case)` performs immediate enclosing-function return with `err(E2.case)`.
The `payload` in `ok(payload)` must be compatible with the success payload shape produced by the surrounding `handle` expression.
The `E2.case` in `err(E2.case)` must belong to the target error type required by the enclosing context.
### 4.5 `handle` sugar
For the common remap-only case, `handle` supports a short arm form:
```text
E1.case -> E2.case
```
This is sugar for:
```text
E1.case -> { err(E2.case) }
```
Recovery with `ok(payload)` requires the explicit block form.
### 4.6 `handle` scope
`handle` may execute user-defined logic inside an arm, but it remains specific to modeled `result` errors.
It does not provide:
- trap interception,
- arbitrary processing of non-`result` failure channels,
- or a general-purpose exception system.
## 5. Invariants
- `optional` models absence, not failure.
- Expected recoverable failure remains in `result<E>`, not in `optional`.
- `!` is an early-return propagation surface.
- `handle` is a typed result-processing surface with controlled recovery or propagation.
- Success paths produce payload values directly.
- Error paths in `result<E>` remain explicit and typed.
- Trap remains outside ordinary recoverable error flow.
- `apply` remains the single semantic call surface even when user code uses direct-call sugar.
- Callable-specific dispatch differences do not change the user-visible call pipeline.
- Effect boundaries remain explicit; `apply` does not auto-lift through `optional` or `result`.
## 6. `apply`
### 6.1 Canonical role
`apply` is the canonical universal call surface in PBS v1.
Direct call syntax is only sugar over `apply` and does not define separate runtime semantics.
The same observable call model applies to:
- top-level functions,
- struct methods,
- service methods,
- contract calls,
- callback calls,
- host-backed calls.
### 6.2 Shared observable pipeline
For `lhs apply rhs`, the shared observable runtime pipeline is:
1. form the call target from `lhs`,
2. evaluate any receiver or callable artifact needed for target formation exactly once,
3. evaluate `rhs` exactly once,
4. invoke the resolved target,
5. produce one of:
- normal return,
- explicit `result<Error>` propagation,
- or `trap`.
Callable-specific dispatch strategy may differ internally, but it does not change this user-visible sequencing model.
### 6.3 Chained `apply`
`apply` chains are parsed right-associatively.
For example:
```text
f1 apply f2 apply f3 apply params
```
parses as:
```text
f1 apply (f2 apply (f3 apply params))
```
The observable evaluation order still follows the already-closed left-to-right model:
1. form the target of `f1`,
2. evaluate the argument expression for `f1`,
3. within that argument expression, form the target of `f2`,
4. evaluate the argument expression for `f2`,
5. within that argument expression, form the target of `f3`,
6. evaluate `params`,
7. invoke `f3`,
8. invoke `f2`,
9. invoke `f1`.
### 6.4 Effect boundaries
`apply` does not introduce implicit effect composition.
If a callable returns:
- `optional<P>`, extraction remains explicit through `else`,
- `result<E> P`, propagation or remapping remains explicit through `!` or `handle`.
PBS v1 does not auto-lift ordinary call chains through `optional` or `result` boundaries.
## 7. `bind`
### 7.1 Role
`bind(context, fn_name)` is the explicit callback-formation mechanism in PBS v1.
It exists to attach a struct context to a compatible top-level function without introducing general lexical closures.
### 7.2 Context and target
`bind` requires:
- a context expression whose runtime value is a struct instance,
- a top-level function target whose first parameter is compatible with that struct type,
- and an expected callback type already validated by static semantics.
### 7.3 Runtime artifact
`bind(context, fn_name)` produces a nominal callback value that stores:
- the resolved top-level function target,
- the captured runtime identity of the context value.
The context is not copied or rematerialized during binding.
When the callback is later invoked, the runtime behaves as if it calls:
```text
fn_name(context, ...)
```
where `context` is the same captured runtime instance.
### 7.4 Evaluation and identity
The context expression is evaluated exactly once at bind time.
That evaluation exists only to obtain the struct instance that will be attached to the callback.
After capture:
- the same runtime context identity remains attached,
- mutations performed through the callback observe and affect that same context instance,
- `bind` does not create a detached copy of the context.
### 7.5 Storage and retention
`bind` is not semantically free.
Forming a callback through `bind` requires runtime storage sufficient to keep:
- the callback target identity,
- and the captured context alive while the callback value remains alive.
For the purposes of PBS v1 semantics, `bind` should be treated as a callback-forming operation with real retention and heap-facing consequences, even though the final memory/lifetime wording belongs in the dedicated memory specification.
### 7.6 Trap behavior
At the language-semantics level, `bind` is trap-free.
Incompatible context type, incompatible function target, or invalid callback shape are compile-time errors rather than runtime traps.
`bind` introduces no ordinary recoverable error surface and no bind-specific trap surface.
### 7.7 Non-goal
`bind` is not:
- general closure capture,
- arbitrary local-environment capture,
- or a promise that future closure features must behave identically.
It is the explicit v1 callback-binding mechanism only.
## 8. Explicit Non-Decisions
This decision record does not yet close:
- the final memory/lifetime wording for allocation, copy, and retention visibility,
- the final catalog of trap sources that may arise from subexpression evaluation.
## 9. Spec Impact
This decision should feed at least:
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
The unresolved cost and retention wording for these surfaces should be completed through:
- `docs/pbs/agendas/Memory and Lifetime - Agenda.md`
- `docs/pbs/agendas/Heap Model - Agenda.md`
## 10. Validation Notes
The intended behavior is:
- `some(expr)` is eager,
- `opt else fallback` is short-circuit on `some`,
- `!` propagates the same typed error unchanged,
- `handle` remaps typed errors without introducing custom logic,
- `apply` remains the universal call surface across callable kinds,
- chained `apply` does not create implicit optional/result composition,
- `bind` captures a struct context identity without copying it,
- `bind` forms a callback with real retention/storage consequences,
- `handle` may recover with `ok(payload)` or propagate with `err(E2.case)`,
- short-form `handle` arms are sugar for propagation-only remap blocks,
- `trap` remains outside both `!` and `handle`.

131
docs/compiler/pbs/decisions/Dynamic Semantics - Execution Model Decision.md
View File

@ -1,131 +0,0 @@
# Dynamic Semantics - Execution Model Decision
Status: Accepted (Implemented)
Cycle: Initial execution-model closure pass
## 1. Context
PBS needs a closed execution-model baseline before effect surfaces and memory/lifetime semantics can be specified normatively.
The key open questions were:
- whether execution is single-threaded per program instance,
- which runtime effects are observable to user code,
- what the default evaluation order is,
- which constructs guarantee single evaluation,
- how abrupt completion behaves,
- how `result<Error>` differs from `trap`,
- and how host calls interact with `FRAME_SYNC` without perturbing user-visible sequencing.
## 2. Decision
PBS v1 adopts the following execution-model baseline:
1. Execution is single-threaded per program instance.
2. User-visible execution is deterministic and does not expose concurrent interleaving.
3. The default evaluation rule is strict left-to-right unless a construct explicitly states otherwise.
4. Call evaluation proceeds by forming the call target first, then evaluating arguments left-to-right, then invoking the target.
5. Abrupt completion terminates the current construct immediately and prevents later sibling evaluation.
6. Recoverable, expected failures belong to `result<Error>`, not to `trap`.
7. `trap` is reserved for non-recoverable runtime failures outside ordinary userland error flow.
8. Any trap aborts the current PBS program execution rather than returning control to ordinary userland flow.
9. `FRAME_SYNC` is the only normative safepoint in PBS v1.
10. `FRAME_SYNC` remains the execution boundary for userland progress; host-side work during that boundary must not reorder PBS-observable semantics.
## 3. Invariants
- PBS v1 does not expose a user-visible concurrent execution model.
- User-visible sequencing is defined by evaluation order, branch selection, abrupt completion, result propagation, trap propagation, and host-call boundaries.
- Traps are not recoverable in userland and do not resume PBS execution.
- VM-internal frame layout, temporary storage, and lowering steps are not observable unless they change the semantic effects above.
- Unless a construct states otherwise, subexpressions are evaluated once and in left-to-right order.
- `return`, `break`, `continue`, result propagation via `!`, and `trap` abort further evaluation in the current construct.
- Host calls must not introduce user-visible reordering of already-defined PBS evaluation order.
- No normative safepoint exists in v1 other than `FRAME_SYNC`.
## 4. Call Evaluation Rule
The runtime call rule for v1 is:
1. Form the call target.
2. Evaluate any receiver that participates in target formation.
3. Evaluate arguments in source order from left to right.
4. Invoke the resolved target.
5. Produce one of:
- normal return,
- explicit `result<Error>` propagation,
- or `trap`.
This rule applies to canonical `apply` and to ordinary call sugar that desugars to `apply`.
## 5. Error Boundary
`result<Error>` and `trap` are distinct runtime categories.
### 5.1 `result<Error>`
`result<Error>` is the required mechanism for failures that are:
- expected by the API contract,
- recoverable in ordinary userland control flow,
- modelable through an explicit PBS error type.
Such failures may be:
- processed with `handle`,
- propagated with `!`,
- and discussed as part of ordinary function contract design.
### 5.2 `trap`
`trap` is reserved for failures that are:
- outside the ordinary userland contract,
- not suitably representable as the declared `result<Error>` surface,
- caused by runtime or host invariant failure,
- or severe enough that ordinary userland recovery is not part of the v1 language model.
PBS v1 does not define `try/catch` for traps.
Traps are not part of ordinary recoverable control flow.
Once a trap is raised, PBS userland execution aborts and control transfers to runtime or firmware crash handling outside the ordinary language model.
## 6. Consequences
- User-authored code does not explicitly throw traps as part of ordinary PBS semantics.
- API surfaces must not use trap as a substitute for a modelable `result<Error>` failure.
- Host-backed operations must expose predictable operational failures through `result<Error>` when those failures are part of the callable contract.
- Residual host or runtime failures that cannot be represented by the declared PBS contract may still trap.
- The language-level consequence of trap is program abort rather than catchable failure handling.
- In v1, no safepoint inventory is normative beyond `FRAME_SYNC`.
## 7. Explicit Non-Decisions
This decision does not yet close:
- the exact list of constructs with explicit single-evaluation wording as finally integrated into the dynamic-semantics spec,
- the final wording split between dynamic semantics and runtime-initialization for trap/crash handoff.
Those points must be integrated by the remaining dynamic-semantics and memory/lifetime decisions.
## 8. Spec Impact
This decision should feed at least:
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/general/specs/16. Runtime Execution and Initialization Specification.md`
It should also constrain future work in:
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
## 9. Validation Notes
The intended rule is:
- expected domain failure: `result<Error>`
- remappable, processable, or propagatable failure: `result<Error>`
- runtime invariant breakage or non-contract catastrophic failure: `trap`
In practical terms, a host-backed API must not rely on trap for ordinary operational failures if those failures can be declared and modeled explicitly in PBS. The only normative safepoint in v1 is `FRAME_SYNC`, and any trap aborts PBS userland execution rather than returning through an in-language recovery path.

130
docs/compiler/pbs/decisions/GC and Reachability Decision.md
View File

@ -1,130 +0,0 @@
# GC and Reachability Decision
Status: Accepted (Implemented)
Cycle: Initial GC-and-reachability closure pass
## 1. Context
PBS v1 uses GC as the baseline runtime model, but the language still needs a precise statement of:
- what reachability guarantees are normative,
- what reclamation guarantees are normative,
- what remains implementation-defined,
- how GC interacts with the single normative safepoint at `FRAME_SYNC`,
- and what user code may or may not observe.
## 2. Decision
PBS v1 adopts the following GC-and-reachability baseline:
1. GC is the baseline runtime model for VM-owned memory in PBS core.
2. Reachability is the normative liveness criterion for GC-managed values.
3. Eventual reclamation is the strongest reclamation guarantee in v1.
4. `FRAME_SYNC` is the only normative safepoint relevant to GC-observable behavior.
5. User code cannot observe reclamation directly.
6. PBS v1 defines no user-authored finalizers, destructors, or reclamation callbacks.
7. Implementations may perform internal GC work outside `FRAME_SYNC` only if doing so creates no additional user-visible semantic effects.
## 3. Normative Reachability Contract
For GC-managed VM-owned values, liveness is defined by reachability from the runtime roots that matter to PBS semantics.
At minimum, these roots include:
- currently active local/frame state,
- reachable fields of reachable struct instances,
- service singleton roots,
- retained callback state that remains reachable,
- and any other runtime roots required to preserve already-observable PBS behavior.
If a GC-managed value remains reachable through the normative runtime state, the implementation must preserve its continued semantic availability.
If a value becomes unreachable, user code must not rely on when reclamation occurs.
## 4. Reclamation Guarantee
PBS v1 guarantees eventual reclamation, not prompt reclamation.
This means:
- unreachable GC-managed memory may be reclaimed later,
- the language does not promise immediate reclamation,
- the language does not promise reclamation at a specific frame boundary,
- and the language does not expose a semantic event when reclamation occurs.
## 5. Safepoint Relationship
`FRAME_SYNC` is the only normative safepoint in PBS v1.
For GC semantics, this means:
- the language does not promise any additional observable GC safepoints,
- no user-visible program rule may depend on another safepoint existing,
- and any internal collector work outside `FRAME_SYNC` must remain semantically invisible to PBS userland.
The spec does not require a specific collector architecture.
It only constrains what may become observable.
## 6. Observability
User code cannot observe reclamation directly.
PBS v1 provides no user-visible mechanism for:
- detecting that a value was collected,
- registering a callback on reclamation,
- forcing immediate collection,
- or sequencing user code against GC timing.
GC-related information may appear in diagnostics, profiling, or runtime tooling, but those surfaces are not ordinary language semantics.
## 7. Finalization and Cleanup
PBS v1 forbids user-authored finalizers and destructor-like reclamation hooks.
GC reclamation of pure VM-owned values does not trigger user code.
Host-backed cleanup policy is not defined by GC finalization semantics in this decision.
If host-backed resources require explicit or contract-specific cleanup rules, those belong to the host-boundary decision track rather than to GC finalization in userland.
## 8. Invariants
- Reachability, not timing, is the normative semantic axis.
- Reclamation timing remains implementation-defined.
- No direct user-visible behavior is allowed to depend on collector timing.
- The only normative safepoint is `FRAME_SYNC`.
- GC must not create extra user-visible sequencing effects outside the already-closed execution model.
## 9. Beginner-Facing Model
The user-facing explanation should be:
- if a value can still be reached by the program, it remains alive,
- once it can no longer be reached, the runtime may clean it up later,
- the program does not control or directly observe that cleanup moment.
## 10. Explicit Non-Decisions
This decision record does not yet close:
- the exact collector algorithm,
- host-backed resource cleanup semantics,
- diagnostics wording for GC-related tooling surfaces,
- the full root-set wording as finally integrated into the memory specification.
## 11. Spec Impact
This decision should feed at least:
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/general/specs/16. Runtime Execution and Initialization Specification.md`
## 12. Validation Notes
The intended split is:
- GC defines reachability and eventual reclamation,
- `FRAME_SYNC` is the only normative safepoint,
- reclamation timing is not user-observable,
- host-backed cleanup is a separate boundary question rather than a user finalization feature.

154
docs/compiler/pbs/decisions/Globals Surface, Identity, and Module Boundaries Decision.md
View File

@ -1,154 +0,0 @@
# Globals Surface, Identity, and Module Boundaries Decision
Status: Accepted
Date: 2026-03-22
Related Agenda: `docs/compiler/pbs/agendas/19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda.md`
## Context
PBS v1 needed a precise language and linking policy for runtime globals before lifecycle, published entrypoint, and lowering work under topic `19` could proceed safely.
The open problem was not merely syntax.
It also required closing:
- how globals differ from `declare const`,
- how globals participate in value visibility and import flow,
- how module ownership of storage is preserved,
- how dependency order between globals is modeled,
- and which diagnostics are mandatory when that model is violated.
Important fixed inputs already existed:
- `declare const` is compile-time only and does not denote mutable module storage,
- top-level executable statements remain forbidden,
- the VM already exposes global-slot access,
- and `mod.barrel` remains the visibility authority for module exports.
## Decision
PBS adopts the following policy for runtime globals in v1:
1. PBS introduces a distinct top-level declaration form:
- `declare global Name: T = expr;`
2. `declare global` is not a variant of `declare const`.
3. `declare const` remains reserved to immutable values and must not be reused as runtime module storage.
4. `declare global` requires:
- an explicit type annotation,
- and an explicit initializer in all ordinary v1 cases.
5. Globals participate in the value namespace, but remain a distinct declaration category.
6. `mod.barrel` must expose globals through explicit `global` entries:
- `mod global Name;`
- `pub global Name;`
7. PBS does not introduce global re-export in this line of work.
8. Import of a global preserves the storage identity of the original owner module.
9. Imports may use aliasing when needed, but aliasing changes only the local visible name, never the canonical storage owner.
10. Shadowing between visible `fn`, `service`, `global`, and `const` names is a compile-time error and must be resolved with aliasing.
11. Lookup precedence remains:
- locals,
- then struct/class members,
- then globals,
including globals introduced by import.
12. Global dependency order is defined by a deterministic dependency graph:
- every read of another global in a global initializer creates a dependency edge,
- imports and aliases preserve canonical owner identity in that graph,
- source-file order must not affect dependency resolution.
13. Cycles between globals are compile-time errors.
14. Modules and globals must share the same structural dependency-analysis kernel through a refactor of the existing module dependency algorithm into:
- `DependencyGraphAnaliser`
- located in infra `util.structures`.
15. What is shared is the structural graph analysis kernel:
- topological ordering,
- cycle detection,
- deterministic traversal support.
16. What is not shared is domain semantics:
- each domain remains responsible for constructing canonical nodes, edges, and diagnostics.
## Global Initializer Policy
PBS v1 adopts the following initializer policy for `declare global`:
1. The initializer exists only to materialize the initial module storage value.
2. Admissible forms in v1 include:
- primitive literals and simple value operations,
- value-bearing member access at this stage,
- `new Struct(...)`,
- and reads of other globals compatible with the dependency graph.
3. Top-level `fn` calls are not permitted in a global initializer in v1.
4. `some(...)` and `none` are not permitted in a global initializer in v1.
5. `if` and `switch` are not permitted directly in the declaration initializer in v1.
6. Richer procedural setup belongs to later lifecycle stages rather than the declaration initializer itself.
## Rationale
This decision intentionally keeps global declarations narrow and explicit.
That choice:
- prevents semantic collapse between immutable constants and mutable runtime storage,
- keeps import and visibility rules legible,
- makes dependency analysis deterministic and explainable,
- avoids hiding lifecycle logic inside declaration expressions,
- and prepares a clean handoff to later topic `19` work on module init, project init, and published entrypoint behavior.
The decision also rejects implicit complexity:
- no silent reuse of `const`,
- no global re-export,
- no ambiguous cross-category name merging,
- and no procedural `fn`-driven initialization inside `declare global`.
## Mandatory Diagnostics
PBS must provide, at minimum, the following diagnostics for this policy:
1. `global initializer uses unsupported form`
- emitted at the invalid subexpression inside a global initializer.
2. `global dependency cycle detected`
- emitted on the local participating global,
- and should include the canonical cycle path when available.
3. `imported symbol shadows existing visible symbol; alias required`
- emitted when an imported `fn`, `service`, `global`, or `const` collides with an already-visible symbol of those categories.
4. `global import must resolve through a global barrel entry`
- emitted when import resolution would otherwise degrade a global into another category.
## Invariants
1. `declare const` and `declare global` remain semantically distinct.
2. Runtime storage ownership remains attached to the canonical owner module.
3. Global dependency order is semantic, not textual.
4. Alias spelling must not change canonical global identity.
5. The dependency-analysis kernel may be shared structurally, but semantic graph construction remains domain-owned.
## Explicit Non-Decisions
1. This decision does not define module init or project init behavior.
2. This decision does not define `[INIT]`, `[FRAME]`, or lifecycle markers.
3. This decision does not define published entrypoint or `FRAME_RET` ownership.
4. This decision does not define the final IR representation of globals.
5. This decision does not define host-call admissibility during lifecycle hooks.
## Spec Impact
This decision should feed at least:
1. `docs/compiler/pbs/specs/3. Core Syntax Specification.md`
2. `docs/compiler/pbs/specs/4. Static Semantics Specification.md`
3. `docs/compiler/pbs/specs/11. AST Specification.md`
4. `docs/compiler/pbs/specs/12. Diagnostics Specification.md`
It also constrains future topic `19` work in:
1. `docs/compiler/pbs/agendas/19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda.md`
2. `docs/compiler/pbs/agendas/19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda.md`
3. `docs/compiler/pbs/agendas/19.4. Globals and Lifecycle Lowering to IRBackend/IRVM Agenda.md`
## Validation Notes
At minimum, validation for this decision should include:
1. accepted fixtures for `declare global` with primitive, member-value, `new`, and dependent-global initializers;
2. rejection fixtures for forbidden initializer forms such as top-level `fn`, `some(...)`, `if`, and `switch`;
3. import fixtures proving alias-based disambiguation;
4. negative fixtures for cross-category collisions;
5. dependency fixtures proving deterministic ordering independent of source-file order;
6. cycle fixtures proving deterministic detection and diagnostics for intra-module and inter-module cycles.

194
docs/compiler/pbs/decisions/Globals and Lifecycle Lowering to IRBackend and IRVM Decision.md
View File

@ -1,194 +0,0 @@
# Globals and Lifecycle Lowering to IRBackend and IRVM Decision
Status: Accepted
Date: 2026-03-22
Related Agenda: `docs/compiler/pbs/agendas/19.4. Globals and Lifecycle Lowering to IRBackend/IRVM Agenda.md`
## Context
After closing globals, lifecycle markers, and published wrapper ownership, PBS v1 still needed a precise lowering contract for how those decisions appear in executable compiler artifacts.
The remaining problem was not semantic policy anymore.
It was structural representation:
- where globals become explicit,
- how synthetic lifecycle callables are represented,
- how one-shot boot state is materialized,
- how diagnostics and attribution survive synthetic lowering,
- and what minimum backend shape must be preserved before `IRVM`.
Important fixed inputs already existed:
- runtime globals are part of the PBS source model,
- module init and project init are semantically defined,
- the published wrapper is the physical entrypoint,
- `FRAME_RET` belongs to that wrapper,
- and VM-level global access already exists as `GET_GLOBAL` / `SET_GLOBAL`.
## Decision
PBS adopts the following lowering policy in v1:
1. Globals must become explicit structural entities at the `IRBackend` boundary.
2. Globals must not be deferred to an implicit late materialization below that boundary.
3. The lowering pipeline must represent synthetic lifecycle artifacts explicitly as synthetic callables rather than ad hoc emitted fragments.
4. The following synthetic callable classes are mandatory:
- `FILE_INIT_FRAGMENT`
- `MODULE_INIT`
- `PROJECT_INIT`
- `PUBLISHED_FRAME_WRAPPER`
5. The wrapper published as the physical entrypoint must exist explicitly in the lowered graph.
6. The one-shot boot guard must exist explicitly as a hidden global.
7. That hidden global is compiler-owned internal state and is not user-visible.
8. The lowering path must target the already-existing VM global operations:
- `GET_GLOBAL`
- `SET_GLOBAL`
## IRBackend Shape
PBS adopts the following minimum structural shape for `IRBackend`-level representation.
### Globals
Each backend global must preserve, at minimum:
1. `name`
2. `ownerModuleId`
3. `type`
4. `slot`
5. `visibility`
6. `isHidden`
7. `origin`
This applies both to:
- user-authored globals,
- and compiler-generated hidden globals such as the boot guard.
### Callables
The backend must distinguish explicitly between:
1. ordinary userland callables,
2. synthetic compiler-generated callables.
Synthetic callables must carry stable class identity rather than being inferred from naming convention alone.
### Hidden Global Kind
The hidden boot guard must carry explicit structural identity:
1. `BOOT_GUARD`
It must not be modeled merely as an informal hidden symbol name.
## Attribution and Diagnostics
PBS adopts the following attribution policy for synthetic lowering:
1. Synthetic globals and synthetic callables must carry origin metadata sufficient for remapping errors to real userland code where possible.
2. Synthetic origin metadata must preserve, at minimum:
- `derivedFromFile`
- `derivedFromModule`
- `derivedFromUserSymbol`
- `primarySpan`
- `fallbackSyntheticLabel`
3. When an error originates from synthetic lowering but has a defensible real userland origin, diagnostics must prefer the real userland span.
4. Purely synthetic spans should be shown only when no defensible userland origin exists.
## Synthetic Callable Policy
PBS adopts the following architectural rule:
1. Synthetic callables are first-class lowering artifacts.
2. They are not incidental codegen accidents.
3. Their explicit class identity exists to support:
- deterministic ordering,
- attribution,
- debug and tooling,
- conformance tests,
- and future lifecycle extensions without reopening the lowering model.
## Hidden Boot Guard Policy
PBS adopts the following policy for the boot guard:
1. It exists as a hidden program-owned global.
2. Userland cannot name it.
3. Userland cannot read it.
4. Userland cannot mutate it.
5. Its sole role is to enforce one-shot bootstrap semantics in the physical wrapper.
## Rationale
This decision intentionally chooses an explicit backend shape over implicit late-stage magic.
That matters because:
- globals are now part of the language contract,
- lifecycle artifacts now exist as semantically meaningful structure,
- diagnostics must remain attributable to real source even after synthesis,
- and backend conformance becomes much harder if the representation boundary stays implicit.
The chosen model also creates a stable editorial split:
- specs explain the structure normatively,
- and `learn` explains the composition through real source examples.
## Structural Diagnostics and Validation
PBS must provide, at minimum, the following structural checks or equivalent validation evidence:
1. `synthetic wrapper entrypoint missing`
2. `published entrypoint is not function index 0`
3. `hidden boot guard is missing`
4. `synthetic callable origin missing`
These may be implemented as backend diagnostics, validation failures, or conformance assertions, as long as the invariant remains enforced and observable.
## Invariants
1. Globals are explicit at the `IRBackend` boundary.
2. Synthetic lifecycle callables are explicit at the `IRBackend` boundary.
3. Hidden compiler state remains distinguishable from user state.
4. Synthetic lowering must preserve enough origin metadata for defensible remapping.
5. The lowering path to `IRVM` must preserve the previously accepted wrapper and entrypoint protocol.
## Explicit Non-Decisions
1. This decision does not redefine source syntax.
2. This decision does not redefine lifecycle semantics.
3. This decision does not redefine manifest publication.
4. This decision does not freeze one concrete implementation class hierarchy.
## Spec and Learn Impact
This decision should feed at least:
1. `docs/compiler/pbs/specs/13. Lowering IRBackend Specification.md`
2. relevant general lowering specs outside the PBS domain, when they need the new explicit shape
3. `docs/compiler/pbs/specs/12. Diagnostics Specification.md`
It also requires didactic propagation to PBS `learn`, where the model should be explained with source-level examples showing how:
1. `declare global`
2. file `[Init]`
3. project `[Init]`
4. and `[Frame]`
compose into synthetic lowered artifacts and the published wrapper.
## Validation Notes
At minimum, validation for this decision should include:
1. a fixture combining globals, file init, project init, and frame;
2. evidence of generated:
- file init fragment,
- module init,
- project init,
- published wrapper,
- hidden boot guard;
3. evidence that the wrapper occupies `func_id = 0`;
4. evidence that `FRAME_RET` lives in the wrapper path;
5. evidence that a synthetic-lowering error remaps to real userland span when a defensible origin exists.

115
docs/compiler/pbs/decisions/Host Memory Boundary Decision.md
View File

@ -1,115 +0,0 @@
# Host Memory Boundary Decision
Status: Accepted (Implemented)
Cycle: Initial host-boundary closure pass
## 1. Context
PBS needs a user-visible contract for the boundary between VM-owned semantics and host-provided runtime services.
At the current stage of the language, userland does not expose complex host-owned resource models.
The runtime offers features and the frontend consumes them; PBS should be careful not to project unnecessary language-level memory abstractions into runtime internals too early.
## 2. Decision
PBS v1 adopts the following host-memory boundary baseline:
1. Cross-boundary interaction between host and PBS userland is restricted to stack-only values.
2. PBS userland does not expose host memory as ordinary language values.
3. Raw pointers are not exposed in PBS userland.
4. Borrowed host-memory views are not exposed in PBS userland.
5. Pinning is not exposed in PBS v1.
6. Zero-copy transfer is not exposed in PBS v1.
7. Heap-shared boundary values between host and PBS userland are not part of the v1 model.
8. Long-lived host resources, if later exposed, must be specified explicitly by subsystem contract rather than inferred from a general host-memory model.
## 3. Boundary Rule
The host/userland boundary in PBS v1 is value-based rather than memory-sharing-based.
This means:
- host-backed interaction happens through explicit call boundaries,
- data crossing that boundary is limited to stack-only value forms,
- and userland never receives direct access to host-owned memory regions.
PBS therefore does not model host memory as something the language can directly hold, borrow, pin, or traverse.
## 4. What Is Not Exposed
PBS v1 does not expose any general userland model for:
- raw host pointers,
- borrowed host slices or views,
- pinned host memory,
- zero-copy host/userland transfer,
- shared heap objects spanning host memory and VM memory.
These features are out of scope for the v1 language model.
## 5. Role of Syscalls
At the current stage, host interaction should be understood primarily through syscall-style host-backed contracts.
Those contracts may accept and return stack-only values, but they do not imply that PBS userland owns, borrows, or directly manipulates host memory.
## 6. Long-Lived Host Resources
PBS v1 does not yet define a general-purpose language model for long-lived host-owned resources such as:
- banks,
- mixers,
- or other subsystem-specific retained resources.
If such resources are exposed later, they must be specified by explicit subsystem contract rather than by assuming a general host-memory-handle model in core PBS.
## 7. Failure Model Scope
This decision does not force a universal language-level error projection for all runtime-internal host behavior.
It only closes the memory-boundary side of the question:
- PBS userland does not directly manipulate host memory,
- and cross-boundary interaction remains stack-value-based.
Concrete error modeling for particular host-backed surfaces belongs to the contract of those surfaces rather than to a general raw-memory boundary rule.
## 8. Invariants
- The host/runtime may own internal memory and resource lifetimes that PBS userland never sees directly.
- PBS userland remains insulated from host-memory unsoundness by not exposing raw memory access at the language level.
- The absence of pointers and borrowed host views is a core v1 safety property.
- Boundary simplicity takes priority over premature expressiveness in this area.
## 9. Beginner-Facing Model
The user-facing explanation should be:
- the runtime can provide services to PBS programs,
- programs pass ordinary values into those services and receive ordinary values back,
- but programs do not directly hold or manipulate host memory.
## 10. Explicit Non-Decisions
This decision record does not yet close:
- the future design of subsystem-specific long-lived host resources,
- the future design of any explicit resource-release APIs,
- the concrete error contract of each host-backed surface,
- the final wording of host-boundary diagnostics.
## 11. Spec Impact
This decision should feed at least:
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/6. VM-owned vs Host-backed.md`
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
## 12. Validation Notes
The intended split is:
- runtime and host internals may remain complex,
- PBS userland sees only stack-only value exchange across the boundary,
- and any richer host-resource model must be introduced later by explicit subsystem contract.

64
docs/compiler/pbs/decisions/IRVM Optimization Stage Placement Decision.md
View File

@ -1,64 +0,0 @@
# IRVM Optimization Stage Placement Decision
Status: Accepted
Date: 2026-03-07
Related Agendas:
- `docs/pbs/agendas/18.0. Backend VM Pipeline - Orchestration Agenda.md`
- `docs/pbs/agendas/18.2. Backend Workshop 2 - LowerToIRVM and IRVM Contract.md`
- `docs/pbs/agendas/18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md`
## Context
Ao fechar a trilha backend executavel (`IRBackend -> IRVM -> bytecode`), surgiu a necessidade de definir onde a otimizacao deve ocorrer.
As opcoes praticas eram:
1. otimizar no runtime,
2. otimizar durante emissao de bytecode,
3. otimizar em etapa dedicada sobre `IRVM` antes da emissao.
O runtime atual privilegia determinismo, loader/verifier estritos e execucao numeric-only.
## Decision
PBS adota etapa dedicada de otimizacao entre lowering e emissao:
1. `LowerToIRVM` gera `IRVM`;
2. `OptimizeIRVM` aplica transformacoes `IRVM -> IRVM` semanticamente equivalentes;
3. `EmitBytecode` serializa o `IRVM` otimizado em artefato pre-load.
A etapa `OptimizeIRVM` passa a ser parte canônica do pipeline backend executavel.
## Invariants
1. `OptimizeIRVM` e compile-time, nao runtime.
2. `OptimizeIRVM` MUST preservar semantica observavel do programa.
3. `OptimizeIRVM` MUST preservar contratos de chamada/retorno/slots.
4. `OptimizeIRVM` MUST preservar determinismo para o mesmo grafo de entrada admitido.
5. `OptimizeIRVM` MUST respeitar `vm_profile` alvo e nao deixar opcodes internos nao-eliminados para a emissao final.
6. `EmitBytecode` continua responsavel por produzir artefato pre-load conforme contrato de loader/verifier.
7. Runtime nao assume papel de otimizador semantico do programa.
## Explicit Non-Decisions
1. Esta decisao nao define o catalogo completo de passes de otimizacao.
2. Esta decisao nao define heuristicas de custo/performance por alvo.
3. Esta decisao nao redefine regras de verifier/loader do runtime.
4. Esta decisao nao define fluxo de packer/cartucho.
## Spec Impact
1. A orquestracao de pipeline em `18.0` passa a incluir `OptimizeIRVM` entre `LowerToIRVM` e `EmitBytecode`.
2. A futura spec de `IRVM` (`18.2`) deve explicitar pre/post-condicoes da etapa de otimizacao.
3. A futura spec de marshaling (`18.3`) deve explicitar que a emissao opera sobre `IRVM` pos-otimizacao.
4. `docs/general/specs/19. Verification and Safety Checks Specification.md` deve refletir cobertura de regressao para pipeline com otimizacao intermediaria.
## Validation Notes
Para validacao minima da decisao:
1. o pipeline executa na ordem `LowerToIRVM -> OptimizeIRVM -> EmitBytecode`;
2. fixtures equivalentes com e sem otimizacao produzem comportamento runtime equivalente;
3. casos negativos de loader/verifier continuam falhando de forma deterministica apos a introducao de `OptimizeIRVM`.

194
docs/compiler/pbs/decisions/Lifecycle Markers, Program Init, and Frame Root Semantics Decision.md
View File

@ -1,194 +0,0 @@
# Lifecycle Markers, Program Init, and Frame Root Semantics Decision
Status: Accepted
Date: 2026-03-22
Related Agenda: `docs/compiler/pbs/agendas/19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda.md`
## Context
After closing the globals surface and module-boundary model, PBS v1 needed a precise lifecycle policy for:
- module bootstrap,
- project bootstrap,
- frame-root identification,
- host-call admissibility during init,
- and failure behavior at boot.
The key requirement was to keep initialization expressive enough for real setup work, while preserving deterministic semantics and preventing the declaration initializer of `global` from becoming a general procedural execution surface.
Important fixed inputs already existed:
- `declare global` lowers into module-owned runtime storage,
- global initializers remain declarative and restricted,
- top-level `fn` calls are not allowed inside `declare global` initializers,
- `FRAME_SYNC` remains the only normative safepoint,
- and PBS v1 remains deterministic and single-threaded.
## Decision
PBS adopts the following lifecycle-marker and bootstrap policy in v1:
1. PBS introduces the reserved userland attributes:
- `[Init]`
- `[Frame]`
2. `[Frame]` is mandatory for an executable project.
3. `[Frame]` is unique per executable project.
4. `[Init]` is optional.
5. `[Init]` may appear in ordinary userland source both for module-local bootstrap and for project bootstrap.
6. Both `[Init]` and `[Frame]` require the same signature shape:
- `fn name() -> void`
7. Recommended canonical source forms are:
```pbs
[Init]
fn init() -> void { ... }
```
```pbs
[Frame]
fn frame() -> void { ... }
```
## Module Init and Project Init Policy
PBS adopts the following bootstrap layering:
1. Every module has exactly one synthetic module init.
2. `declare global` always lowers into that synthetic module init.
3. Each file may declare at most one `[Init]`.
4. A file may declare `[Init]` even when it declares no globals.
5. For one file:
- that file's globals are materialized first,
- then that file's `[Init]`, if present, executes.
6. File-level init fragments are then composed into the one synthetic module init.
7. The `[Init]` colocated in the same file as `[Frame]` is the project init.
8. `[Init]` in other files remains module init.
9. The distinction between module init and project init is one of ordering and semantic role, not one of different source syntax.
10. There is therefore at most one project init per executable project.
11. Project init uses the same signature shape:
- `fn init() -> void`
## Bootstrap Order
PBS adopts the following logical bootstrap order:
1. materialize globals for each file according to dependency order,
2. execute that file's `[Init]`, if present,
3. compose those steps into one synthetic module init,
4. after required module work is complete, execute project init, if present,
5. then enter the first `frame()`.
Within one module:
1. file ordering must follow the order derived from the globals `DependencyGraphAnaliser`,
2. and when two files have no dependency edge between them, the compiler must still use a deterministic stable order.
## Host Interaction During Init
PBS adopts the following init-time host-call policy:
1. Loops are permitted in module init and project init.
2. Host calls are forbidden by default during init.
3. The only host calls admissible during init are host methods marked with `[InitAllowed]`.
4. `[InitAllowed]` is a reserved SDK attribute, not a userland attribute.
5. `[InitAllowed]` has no arguments in v1.
6. `[InitAllowed]` is valid only on SDK host methods.
7. `[InitAllowed]` is invalid on userland `fn`, `global`, `service`, or any non-host-method surface.
8. `[InitAllowed]` does not distinguish module init from project init.
9. The difference between those phases is ordering and semantic role, not a separate host-permission class.
10. Admissibility of `[InitAllowed]` must be checked at compile time.
Illustrative shape:
```pbs
declare host Runtime {
[Host(module = "runtime", name = "random_u32", version = 1)]
[Capability(name = "runtime")]
[InitAllowed]
fn random_u32() -> int;
}
```
## Failure Policy
PBS adopts a fail-fast boot policy:
1. Failure during module init aborts boot.
2. Failure during project init aborts boot.
3. No automatic retry occurs on the next frame.
4. Implementations must surface a coherent failure message identifying the failing boot phase.
## Rationale
This decision keeps the declaration initializer of `global` simple, while still allowing practical bootstrap work in later lifecycle stages.
That balance matters because:
- arrays and derived data often require loops during setup,
- module bootstrap must remain expressive enough for real projects,
- host interaction during boot must still be tightly controlled,
- and the runtime model must remain deterministic and explainable.
Colocation of project init with frame was chosen deliberately as a source-organization rule.
It avoids introducing a second project-level marker while keeping project bootstrap discoverable in source.
## Mandatory Diagnostics
PBS must provide, at minimum, the following diagnostics for this policy:
1. `project init must be colocated with frame`
2. `multiple project init functions detected`
3. `multiple frame functions detected`
4. `missing frame function for executable project`
5. `init function must have signature fn name() -> void`
6. `frame function must have signature fn name() -> void`
7. `host call not allowed during init`
8. `InitAllowed is valid only on SDK host methods`
9. `boot failed during module init`
10. `boot failed during project init`
11. `multiple module init functions detected`
12. `Init attribute target invalid`
## Invariants
1. `[Frame]` remains unique per executable project.
2. Project init is identified by colocation with `[Frame]`.
3. Each file contributes at most one init fragment.
4. Each module contributes exactly one synthetic module init.
5. Host-call admissibility during init is explicit and compile-time validated.
6. Boot ordering remains deterministic.
## Explicit Non-Decisions
1. This decision does not define the published synthetic wrapper entrypoint.
2. This decision does not define `FRAME_RET` ownership.
3. This decision does not define the final IR encoding of bootstrap.
4. This decision does not define cartridge manifest publication details.
## Spec Impact
This decision should feed at least:
1. `docs/compiler/pbs/specs/3. Core Syntax Specification.md`
2. `docs/compiler/pbs/specs/4. Static Semantics Specification.md`
3. `docs/compiler/pbs/specs/9. Dynamic Semantics Specification.md`
4. `docs/compiler/pbs/specs/12. Diagnostics Specification.md`
It also constrains future topic `19` work in:
1. `docs/compiler/pbs/agendas/19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda.md`
2. `docs/compiler/pbs/agendas/19.4. Globals and Lifecycle Lowering to IRBackend/IRVM Agenda.md`
3. `docs/compiler/pbs/agendas/19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda.md`
## Validation Notes
At minimum, validation for this decision should include:
1. accepted fixtures for `[Init]` and `[Frame]` with correct signatures;
2. accepted fixtures for file-level `[Init]` without globals;
3. accepted fixtures for loops inside module init and project init;
4. rejection fixtures for invalid marker targets and invalid signatures;
5. rejection fixtures for illegal host calls during init;
6. accepted fixtures for SDK host calls marked `[InitAllowed]`;
7. failure fixtures that distinguish module-init boot failure from project-init boot failure;
8. ordering fixtures proving deterministic file ordering within one module.

121
docs/compiler/pbs/decisions/Lifetime Control and Future Profiles Decision.md
View File

@ -1,121 +0,0 @@
# Lifetime Control and Future Profiles Decision
Status: Accepted (Implemented)
Cycle: Initial lifetime-control policy closure pass
## 1. Context
PBS v1 no longer uses the old RC/HIP model as an active core-language direction.
The remaining question is not how to design explicit lifetime control now, but how the project should treat legacy concepts and what policy should govern any future reintroduction of lifetime-oriented language features.
## 2. Decision
PBS v1 adopts the following lifetime-control policy baseline:
1. No lifetime-control keyword is reserved in core PBS merely for possible future use.
2. If a lifetime-control surface is not active in v1, it should not remain in the language as a reserved future-only keyword on that basis alone.
3. Advanced memory workflows should default to library/tooling-first exploration rather than syntax-first activation.
4. GC remains the default core model; future explicit lifetime control, if ever introduced, must be profile-gated rather than silently folded into the default language.
5. Future lifetime-oriented syntax may be introduced only when there is concrete evidence that library/tooling approaches are insufficient.
## 3. Legacy RC/HIP Concepts
Legacy concepts such as:
- `alloc`
- `borrow`
- `take`
- `weak`
- pool-style and arena-style control patterns
- object reuse patterns
do not remain active merely by historical inertia.
For PBS v1 policy:
- legacy concepts may survive as historical or design-reference material,
- but they do not imply reserved syntax commitment,
- and they do not imply a roadmap promise of later activation.
## 4. Language Versus Library Boundary
The default policy is:
- library first,
- tooling first,
- profile later only if justified,
- syntax last.
This means advanced workflows should first be explored through:
- stdlib APIs,
- tooling support,
- diagnostics,
- profiling guidance,
- subsystem-specific contracts where needed.
The language should not absorb explicit lifetime syntax simply because a legacy concept existed before.
## 5. Migration Narrative
The official migration narrative is:
- PBS v1 moves away from RC/HIP-style user-authored lifetime control as the core user model,
- GC plus deterministic execution is the baseline,
- performance-sensitive reasoning remains important,
- but performance and memory control should rise through explicit APIs and tooling before new syntax is considered.
This is a deliberate simplification, not a temporary placeholder awaiting automatic return to explicit ownership syntax.
## 6. Future Activation Criteria
Any future lifetime-oriented language/profile work must satisfy all of the following:
1. Real implementation and product evidence shows that library/tooling-first approaches are insufficient.
2. The proposed feature has a coherent semantic model that does not break the GC baseline by accident.
3. The feature can be isolated behind an explicit profile or equivalent opt-in boundary.
4. Diagnostics, conformance, and migration obligations are clear.
5. The feature does not degrade the beginner-facing default language without strong justification.
Future activation must be justified by present need and validated design, not by preserving speculative syntax in the current language.
## 7. Invariants
- GC remains the default core runtime model.
- Core PBS v1 does not promise future activation of legacy lifetime syntax.
- Absence of reserved lifetime keywords is a deliberate policy choice.
- Future explicit control must be explicit, justified, and profile-gated.
## 8. Beginner-Facing Model
The user-facing explanation should be:
- PBS v1 does not require ownership or lifetime syntax in ordinary code,
- advanced control is not removed as a future possibility,
- but it will be introduced only if it proves necessary and only through explicit design, not through dormant keywords left in the language.
## 9. Explicit Non-Decisions
This decision record does not yet close:
- the exact shape of any future profile mechanism,
- the exact syntax of any future explicit lifetime feature,
- the future stdlib design for pools, arenas, or weak-reference-like patterns.
## 10. Spec Impact
This decision should feed at least:
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/general/specs/17. Compatibility and Evolution Policy.md`
- `docs/pbs/specs/3. Core Syntax Specification.md`
## 11. Validation Notes
The intended policy is:
- no dormant lifetime keywords in core v1,
- no nostalgia-based reservation policy,
- library/tooling first,
- profile-gated language activation only when clearly justified.

168
docs/compiler/pbs/decisions/Name Resolution - Builtin Shells and Host Owners Decision.md
View File

@ -1,168 +0,0 @@
# Name Resolution - Builtin Shells and Host Owners Decision
Status: Accepted (Implemented)
Cycle: Initial name-resolution closure pass
## 1. Context
PBS v1 needs a deterministic rule for how reserved stdlib shells participate in source-level name resolution.
The open questions were:
- whether builtin shells and host owners enter lookup as ordinary imported declarations or as special compiler-only names,
- whether builtin intrinsic methods participate in free callable lookup,
- whether reserved shells receive special collision priority,
- whether builtin shells belong under `@core:*` or `@sdk:*` by policy,
- and which phase owns failures related to builtin member lookup and canonical identity duplication.
Important fixed inputs already existed:
- reserved stdlib project spaces are resolved from the selected stdlib environment,
- source-visible builtin names resolve through imported builtin shell declarations,
- canonical builtin and host identities come from metadata rather than local spelling,
- builtin intrinsic methods are not imported as free functions,
- and host-owner namespace remains distinct from type, value, and callable namespaces.
## 2. Decision
PBS v1 adopts the following baseline for builtin shells and host-owner resolution:
1. Source-visible declarations exposed by reserved builtin shells are imported into their ordinary corresponding namespaces.
2. This means builtin-exposed types enter type lookup as imported type declarations, builtin-exposed constants enter value lookup as imported values, and host owners enter host-owner lookup as imported host-owner declarations.
3. `declare builtin type` itself remains a reserved stdlib/toolchain declaration form rather than ordinary user-authored source syntax.
4. Reserved-shell metadata exists to drive canonical identity and later lowering, not to create special source-level lookup priority.
5. Builtin simple types `int`, `float`, `bool`, and `str` remain separate always-available reserved type names and are not treated as ordinary imported builtin shells.
6. Builtin intrinsic methods never participate in free lookup.
7. Builtin intrinsic methods are resolved only through member lookup on a receiver already known to have the corresponding builtin type.
8. Reserved builtin shells and host owners follow the same collision policy as ordinary imported declarations: same visible name in the same namespace is an error unless another already-closed rule explicitly permits otherwise.
9. By policy, builtin shells are preferred under `@core:*`.
10. Member lookup failure on an already-typed builtin receiver belongs to static semantics.
11. Duplicate canonical builtin identities or duplicate canonical host identities in one resolved environment belong normatively to linking rather than to syntax or ordinary static semantics.
## 3. Reserved Shells As Imported Declarations
Reserved shells are source-visible through ordinary import and visibility rules.
This means:
- the user imports the shell from a reserved stdlib module,
- the imported shell becomes visible in the matching namespace,
- and source-level lookup treats that visible declaration like other imported declarations of the same namespace.
The compiler still recognizes the reserved metadata attached to those declarations, but that metadata does not create a parallel hidden namespace.
## 4. Builtin Simple Types Versus Imported Builtin Shells
PBS distinguishes:
- the tiny predeclared builtin simple-type set: `int`, `float`, `bool`, `str`,
- and imported builtin shells such as `Vec2`, `Color`, or similar stdlib-exposed types.
Rules:
- builtin simple types remain always available without import,
- imported builtin shells are not promoted to that same status,
- and the two categories must not be conflated in source-level lookup.
## 5. Intrinsic Member Lookup
Builtin intrinsic members are resolved only through receiver-member lookup.
Rules:
- they do not appear in top-level callable lookup,
- they are not introduced by import as free functions,
- and aliasing the owner builtin type changes only the local visible owner spelling, not the intrinsic's canonical identity.
This keeps member semantics uniform and avoids special free-function treatment for reserved surfaces.
## 6. Collision Policy
Reserved shells receive no special collision privilege.
Rules:
- if an imported builtin shell declaration and another visible declaration produce the same visible name in the same namespace, the program is rejected under the ordinary collision rules already chosen,
- if a host owner shares a spelling with a type or value, that alone is not a conflict because host-owner namespace remains distinct,
- and reserved-shell status does not authorize silent shadowing.
## 7. Reserved Project-Space Policy
For source-level policy:
- builtin shells are preferred under `@core:*`,
- host-facing capability surfaces remain the natural fit for `@sdk:*`.
This is a policy direction for clarity and separation of concerns.
It does not change the underlying ownership model governed by other specs.
## 8. Failure Ownership Baseline
The current baseline is:
- failure to resolve a reserved stdlib module remains manifest/import resolution,
- import of a non-exported reserved shell remains linking,
- member lookup failure on an already-typed builtin receiver remains static semantics,
- duplicate canonical builtin or host identities in one resolved environment remain linking failures.
Implementations may internally perform some of these checks during environment validation, but the normative external phase ownership is linking where the linking-phase decision assigns it.
## 9. Invariants
- Reserved-shell metadata does not create special source-level lookup priority.
- Builtin intrinsic methods are never free functions in source-level lookup.
- Builtin simple types remain separate from stdlib-delivered builtin shells.
- Host owners remain in the host-owner namespace only.
- Ordinary collision rules apply to reserved-shell imports unless a later explicit rule says otherwise.
- Canonical identity conflicts are linking problems, not syntax problems.
## 10. Explicit Non-Decisions
This decision record does not yet close:
- the full stdlib-surface policy of `18. Standard Library Surface Specification.md`,
- and the final lowering consequences in `13. Lowering IRBackend Specification.md`.
## 11. Spec Impact
This decision should feed at least:
- `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/general/specs/18. Standard Library Surface Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
It should also constrain future work in:
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
## 12. Validation Notes
The intended baseline is:
- reserved builtin shells are imported like ordinary declarations into the matching namespace,
- builtin methods are found only through receiver-member lookup,
- builtin simple types remain always available without import,
- `@core:*` is the preferred home for builtin shells,
- and duplicate canonical builtin or host identities are rejected at linking time.
Illustrative examples:
```pbs
import { Vec2 } from @core:math;
```
`Vec2` becomes an imported visible type declaration with builtin metadata.
```pbs
import { Vec2 } from @core:math;
Vec2.zero()
```
If `zero` is a builtin intrinsic member, it resolves through builtin member lookup on `Vec2`-typed receiver use and not through free callable lookup by the name `zero`.
```pbs
import { Vec2 } from @core:math;
declare const Vec2: int = 1;
```
This is rejected as an ordinary same-namespace collision rather than resolved by reserved-shell priority.

173
docs/compiler/pbs/decisions/Name Resolution - Callable Sets and Cross-Module Linking Decision.md
View File

@ -1,173 +0,0 @@
# Name Resolution - Callable Sets and Cross-Module Linking Decision
Status: Accepted (Implemented)
Cycle: Initial name-resolution closure pass
## 1. Context
PBS v1 needs a deterministic rule for how callable names cross module boundaries.
The open questions were:
- what exactly `import { f } from @project:path;` imports when `f` has multiple exported signatures,
- whether callable sets from different origins may merge,
- whether same-name imported callables from different origins are tolerated until callsite analysis,
- whether local and imported callable names may coexist under one visible function name,
- and how `mod.barrel` bounds the callable set that becomes importable.
Earlier closure already fixed important inputs:
- `mod.barrel` is the single source of module visibility,
- only `pub` names may be imported from another module,
- local function names and imported function names with the same visible name are already being treated as collisions in this closure pass,
- and callable identity is determined by callable shape rather than parameter-label spelling alone.
## 2. Decision
PBS v1 adopts the following baseline for callable sets and cross-module linking:
1. `import { f } from @project:path;` imports the exported callable set named `f` from the target module.
2. The imported callable set for `f` consists only of those overload signatures of `f` that are exported through that module's `mod.barrel`.
3. Non-exported overloads in the target module do not participate in the imported callable set.
4. Two imports of the same visible callable name are tolerated when they resolve to the same canonical underlying callable-set origin after module resolution.
5. Such same-origin duplicate imports are redundant but not errors.
6. Two imports of the same visible callable name from different canonical origins are rejected immediately.
7. The program must not wait until a callsite to reject different-origin callable-name collisions.
8. A module-local function name and an imported function name with the same visible name are rejected immediately.
9. Automatic merging of callable sets across different origins is not permitted in this closure pass.
10. Ordinary overload resolution occurs only after one unambiguous visible callable set has already been formed.
## 3. Imported Callable Set
The meaning of:
```pbs
import { f } from @project:path;
```
is:
- resolve the target module,
- collect the exported callable entries named `f` from that module,
- form the callable set consisting only of those exported overloads,
- and make that callable set visible locally under the imported visible name.
This import does not:
- reach non-exported overloads,
- merge with hidden module-internal overloads,
- or import one overload at a time independently from the exported callable name.
## 4. Same-Origin Versus Different-Origin Imports
### 4.1 Same origin
If the same visible callable name is imported more than once and both imports resolve to the same canonical underlying callable-set origin:
- the duplicate import is tolerated,
- but it remains redundant.
### 4.2 Different origin
If the same visible callable name is imported from different canonical origins:
- the program is rejected immediately,
- and one of the imports must be removed or aliased.
The implementation must not:
- merge the callable sets,
- defer the conflict to overload resolution,
- or allow callsite context to decide which imported origin wins.
## 5. Local Versus Imported Callable Names
If a module-local function name and an imported function name are the same visible callable name:
- the program is rejected immediately,
- and the implementation must not merge the local and imported callable sets.
This preserves deterministic visibility and keeps callable origin traceable.
## 6. Barrel Boundary
`mod.barrel` defines the exact boundary of the callable set that may cross module boundaries.
Rules:
- only overloads exported through `mod.barrel` are part of the importable callable set,
- overloads with the same source-level function name but not exported through `mod.barrel` are invisible to importing modules,
- and imported callable-set visibility is therefore a direct consequence of the source module's barrel contract.
## 7. Overload Resolution Boundary
This decision deliberately separates:
- callable-set formation,
- and overload resolution at a callsite.
The implementation must first form one unambiguous visible callable set.
Only then may ordinary overload resolution operate on the candidate signatures of that set.
Callsite context must not be used to resolve ambiguity between different imported callable origins.
## 8. Invariants
- Imported callable visibility is bounded by barrel export.
- Different callable origins must not merge automatically.
- Same-origin duplicate imports may be tolerated as redundancy, not as new callable contributions.
- Local and imported function names do not coexist under one merged visible callable name in this closure pass.
- Overload resolution happens after visible callable-set formation, not instead of it.
## 9. Explicit Non-Decisions
This decision record does not yet close:
- per-overload import syntax,
- aliasing policy for callable imports beyond the already-closed generic alias rules,
- and any lowering consequences in `13. Lowering IRBackend Specification.md`.
## 10. Spec Impact
This decision should feed at least:
- `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
It should also constrain future work in:
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
## 11. Validation Notes
The intended baseline is:
- callable imports operate on exported callable names,
- all exported overloads of that name come together from one module,
- same-origin duplicate imports are tolerated,
- different-origin same-name imports are rejected immediately,
- and local/import callable collisions are also rejected immediately.
Illustrative examples:
```pbs
import { f } from @a:m;
import { f } from @a:m;
```
This is tolerated as redundant same-origin duplication.
```pbs
import { f } from @a:m;
import { f } from @b:n;
```
This is rejected immediately because the visible callable names match but the canonical origins differ.
```pbs
fn f(a: int) -> int { ... }
import { f } from @a:m;
```
This is rejected as a local-versus-import callable collision.

200
docs/compiler/pbs/decisions/Name Resolution - Linking Phase Boundary Decision.md
View File

@ -1,200 +0,0 @@
# Name Resolution - Linking Phase Boundary Decision
Status: Accepted (Implemented)
Cycle: Initial name-resolution closure pass
## 1. Context
PBS v1 needs an explicit phase boundary around source-level name resolution so that:
- frontend implementation does not invent phase ownership,
- diagnostics can attribute failures consistently,
- conformance can test rejection classes coherently,
- and later lowering work does not have to guess whether a failure belongs to syntax, linking, or typing.
Earlier closure already established rules for:
- module scope construction,
- import naming and aliasing,
- builtin shell visibility,
- callable-set visibility across modules.
The remaining open question was how to classify the failure classes that arise while assembling visible declarations across files and modules.
## 2. Decision
PBS v1 adopts the following normative phase baseline for name resolution and related frontend failures:
1. `syntax` is a distinct normative phase.
2. `manifest/import resolution` is a distinct normative phase.
3. `linking` is a distinct normative phase.
4. `static semantics` is a distinct normative phase.
5. `syntax` owns malformed import grammar and other token-shape or grammar-shape failures.
6. `manifest/import resolution` owns failures to resolve project space, reserved stdlib space, dependency graph, module path, or environment source.
7. `linking` owns assembly of visible declarations across files and modules.
8. `linking` therefore owns:
- import of non-exported names,
- unresolved barrel entries against module declarations,
- collisions between visible imported names from different canonical origins,
- local-versus-import visibility collisions,
- callable-origin conflicts across module boundaries,
- and duplicate canonical builtin or host identities in one resolved environment.
9. `static semantics` owns declaration validity, type checking, member lookup once the receiver type is known, and overload resolution within an already-formed visible callable set.
10. Member lookup failure on an already-typed builtin receiver belongs to `static semantics`.
11. Ambiguity between different imported origins must be rejected in `linking` before any callsite analysis.
## 3. Phase Roles
### 3.1 Syntax
`syntax` owns failures that arise before module or declaration assembly.
Examples:
- malformed import declaration shape,
- malformed alias syntax,
- malformed declaration grammar,
- unexpected tokens.
### 3.2 Manifest and Import Resolution
`manifest/import resolution` owns failures of locating and loading the source of a module or reserved environment.
Examples:
- unresolved `@project:*` dependency target,
- unresolved reserved stdlib module,
- invalid project-space selection,
- failure to load the module source from the selected environment.
### 3.3 Linking
`linking` owns the assembly of the visible declaration space after modules have been found and loaded.
Examples:
- imported name is not exported by the target module,
- `mod.barrel` entry does not resolve against declarations of the module,
- two imports expose the same visible name from different canonical origins,
- a local visible declaration collides with an imported visible declaration,
- callable-origin conflicts across module boundaries,
- duplicate canonical builtin identities in one resolved environment,
- duplicate canonical host identities in one resolved environment.
### 3.4 Static Semantics
`static semantics` owns validation and typing of the already-linked visible program.
Examples:
- duplicate local declarations,
- invalid declaration validity conditions,
- type mismatch,
- member lookup on a known receiver type,
- overload resolution inside one already-visible callable set.
## 4. Linking As A Real Normative Phase
PBS keeps `linking` as a distinct normative phase rather than collapsing it fully into `static semantics`.
Reasoning:
- some failures arise only when assembling visible declarations across files and modules,
- those failures are neither pure grammar failures nor ordinary local typing failures,
- and naming `linking` gives diagnostics and conformance a stable vocabulary for them.
This does not require every implementation to expose one identical internal compiler pass graph.
It only requires the externally visible failure ownership to map back to this normative phase model.
## 5. Barrel Matching And Visible Assembly
`mod.barrel` matching belongs to `linking`.
This means:
- failure of a barrel item to resolve to a declaration of the module is not merely a syntax issue,
- and it is not deferred until later typing or lowering.
Barrel matching is part of assembling the module's visible declaration contract.
## 6. Imported-Origin Conflicts
Conflicts between different imported origins are rejected in `linking` immediately.
This means:
- the implementation must not wait for a specific callsite or use-site,
- overload resolution is not allowed to rescue ambiguity between different imported origins,
- and visible declaration conflicts are resolved structurally before later typing work proceeds.
## 7. Builtin Receiver Lookup
Member lookup on a builtin receiver whose type is already known remains `static semantics`.
The reason is:
- by that point the relevant shell visibility work has already completed,
- and the remaining question is ordinary typed member validity rather than module assembly.
## 8. Invariants
- The phase model exposed to users and conformance must remain deterministic.
- `linking` remains the phase for visible declaration assembly across module boundaries.
- Callsite analysis must not be used to resolve imported-origin conflicts.
- `static semantics` operates on an already-linked visible declaration space.
- Syntax and manifest/import resolution remain narrower than linking and do not absorb visible-name conflicts that arise only after module loading.
## 9. Explicit Non-Decisions
This decision record does not yet close:
- the full diagnostics-code taxonomy,
- whether implementations expose one explicit user-facing `linking` label or a mapped equivalent wording class,
- the final artifact-facing phase vocabulary after lowering and verification specs close,
- and the exact implementation architecture of one compiler pipeline.
## 10. Spec Impact
This decision should feed at least:
- `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
It should also constrain future work in:
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/pbs/decisions/Name Resolution - Scope, Lookup, and Imports Decision.md`
- `docs/pbs/decisions/Name Resolution - Builtin Shells and Host Owners Decision.md`
- `docs/pbs/decisions/Name Resolution - Callable Sets and Cross-Module Linking Decision.md`
## 11. Validation Notes
The intended phase split is:
- `syntax` parses declaration and import shape,
- `manifest/import resolution` finds and loads modules,
- `linking` assembles visible names across modules and barrels,
- `static semantics` validates and types the already-linked visible program.
Illustrative examples:
```pbs
import { Missing } from @a:m;
```
If `@a:m` resolves successfully but does not export `Missing`, this is a `linking` failure.
```pbs
import { f } from @a:m;
import { f } from @b:n;
```
If the canonical origins differ, this is a `linking` failure and is rejected before any callsite analysis.
```pbs
import { Vec2 } from @core:math;
value.zero()
```
If `value` is already known to have builtin type `Vec2` and `.zero` is not a valid member on that receiver type, the failure is `static semantics`.

270
docs/compiler/pbs/decisions/Name Resolution - Scope, Lookup, and Imports Decision.md
View File

@ -1,270 +0,0 @@
# Name Resolution - Scope, Lookup, and Imports Decision
Status: Accepted (Implemented)
Cycle: Initial name-resolution closure pass
## 1. Context
PBS v1 needs a deterministic frontend-visible rule for:
- how module scope is formed,
- how lookup works by namespace,
- what imports actually introduce into local scope,
- how collisions between local and imported names are handled,
- and which failures belong to syntax, manifest/import resolution, static semantics, or linking.
Existing specs already fix important inputs:
- `mod.barrel` is the single source of module visibility,
- imports target modules, not files,
- only `pub` names may be imported from another module,
- PBS has distinct type, value, callable, and host-owner namespaces,
- builtin simple types `int`, `float`, `bool`, and `str` are always available in type position,
- and reserved stdlib project spaces resolve only from the selected stdlib environment.
The remaining goal of this decision is to close the minimum name-resolution baseline needed for normative frontend work around ordinary scope construction, ordinary lookup, and import naming.
## 2. Decision
PBS v1 adopts the following baseline for scope construction, lookup, and imports:
1. Top-level declarations of a module are collected across all `.pbs` files in the module before visibility filtering is applied.
2. `mod.barrel` is a visibility filter over existing module declarations, not the source of declaration existence.
3. Module-internal top-level availability does not depend on source-file order.
4. Local block scopes nest normally over module scope.
5. In value position, lookup prefers the nearest lexical value binding before any module-level or imported value.
6. Parameters and local `let` bindings participate in the same nearest lexical value-scope layer for lookup purposes.
7. In type position, visible module-local type declarations are considered before imported type declarations, and builtin simple types remain always-available reserved type names outside ordinary import competition.
8. In callable position, visible module-local callable declarations are considered before imported callable declarations.
9. In host-owner position, visible module-local host owners are considered before imported host owners.
10. The local visible name introduced by an import is always the post-alias name when an alias is present.
11. `import { X } from @project:path;` introduces the imported exported name `X` into the matching namespace.
12. `import { X as Y } from @project:path;` introduces only the local visible name `Y` into the matching namespace.
13. Alias spelling changes only the local visible name, never canonical builtin identity or canonical host identity.
14. `import { * } from @project:path;` is the whole-module import form for bringing the target module's exported names into local visibility under their exported names.
15. A collision between a module-local declaration and an imported visible name in the same namespace is a deterministic error rather than silent shadowing.
16. A collision between two imported visible names in the same namespace is not an error only when both imports denote the same canonical underlying declaration after module resolution.
17. If two imported visible names in the same namespace come from different canonical underlying declarations, the program is rejected and one of the imports must be aliased or removed.
18. `import { * } from @project:path;` does not create a first-class module object, module namespace value, or other source-visible binding by itself; it only introduces the exported names of the target module.
19. A module-local function and an imported function with the same visible name produce a deterministic error in this closure pass.
20. Non-callable namespaces do not merge by name.
## 3. Scope Construction
### 3.1 Module collection
For one module:
- the compiler collects top-level declarations from all `.pbs` files in that module,
- forms one module-level declaration space,
- then applies `mod.barrel` to determine `mod` and `pub` visibility.
This means:
- declaration existence is not derived from barrel entries,
- and module-internal declaration availability is not ordered by file traversal.
### 3.2 Lexical scope
Inside executable bodies:
- lexical block scope is nested normally,
- nearest local bindings win within value lookup,
- and lexical nesting remains independent from cross-module visibility.
## 4. Lookup By Namespace
### 4.1 Value position
Value-position lookup follows this order:
1. nearest local lexical bindings,
2. parameters in the current lexical function scope,
3. visible module-local values,
4. visible imported values.
For lookup purposes, parameters and local `let` bindings are one nearest lexical value layer.
The distinction between them may still matter for diagnostics wording.
### 4.2 Type position
Type-position lookup follows this order:
1. visible module-local type declarations,
2. visible imported type declarations,
3. builtin simple types `int`, `float`, `bool`, and `str` as always-available reserved type names.
Builtin simple types are not treated as ordinary imported declarations and do not participate in ordinary import competition.
### 4.3 Callable position
Callable-position lookup follows this order:
1. visible module-local callables,
2. visible imported callables.
If a visible module-local function name and a visible imported function name are the same, the program is rejected in this closure pass rather than merged.
### 4.4 Host-owner position
Host-owner lookup follows this order:
1. visible module-local host owners,
2. visible imported host owners.
Host-owner lookup remains separate from type, value, and callable lookup.
## 5. Import Surface
### 5.1 Named import
`import { X } from @project:path;`:
- resolves the target module,
- checks that `X` is exported and importable from that module,
- and introduces `X` into the corresponding namespace locally.
### 5.2 Aliased import
`import { X as Y } from @project:path;`:
- resolves the same exported declaration as the non-aliased form,
- but introduces only `Y` as the local visible name.
Alias spelling does not change canonical identity governed elsewhere.
### 5.3 Whole-module import
`import { * } from @project:path;`:
- validates and resolves the target module,
- introduces the target module's exported visible names under their exported spellings,
- but does not create a module-valued binding,
- does not create a namespace object,
- and does not authorize qualified member access by itself.
If PBS later wants module-object or namespace-qualified source semantics, that must be added explicitly rather than inferred from this form.
## 6. Collision Policy
### 6.1 Local versus imported
If a module-local declaration and an imported declaration produce the same visible name in the same namespace:
- the program is rejected,
- and the implementation must not silently shadow the imported declaration or the local declaration.
This includes function names.
In this closure pass, a local function and an imported function with the same visible name are rejected rather than merged.
### 6.2 Imported versus imported
If two imports produce the same visible name in the same namespace:
- the program is not rejected if both imports resolve to the same canonical underlying declaration after module resolution,
- but the duplicate import is still redundant,
- and the program is rejected if the imports resolve to different canonical underlying declarations.
### 6.3 Namespace separation
Names in different namespaces do not collide merely by spelling.
For example:
- a host owner and a type declaration do not collide by spelling alone,
- because host-owner namespace remains distinct from type namespace.
## 7. Relationship To Later Name-Resolution Decisions
This decision is intentionally limited to:
- ordinary scope construction,
- ordinary namespace lookup,
- import naming,
- and ordinary collision policy.
Later name-resolution decisions close:
- reserved builtin shells and host owners,
- callable-set visibility across modules,
- and the final phase boundary between syntax, manifest/import resolution, linking, and static semantics.
## 8. Invariants
- Name lookup must be deterministic.
- Module-internal top-level declaration availability must not depend on file order.
- `mod.barrel` remains a visibility mechanism rather than a declaration source.
- Imports must not invent first-class module-object semantics accidentally.
- The effective visible name of an import is always the post-alias name when an alias is present.
- Builtin simple types remain a reserved always-available core type set, distinct from ordinary imported declarations.
- Implementations must not assume silent local-over-import shadowing.
- Implementations must not merge local and imported function names automatically.
## 9. Explicit Non-Decisions
This decision record does not yet close:
- reserved-shell-specific lookup and collision details,
- callable-set import behavior across module boundaries beyond the local-versus-import collision baseline,
- and backend-facing lowering consequences of the resolved lookup model.
## 10. Spec Impact
This decision should feed at least:
- `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
It should also constrain future work in:
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/pbs/decisions/Name Resolution - Builtin Shells and Host Owners Decision.md`
- `docs/pbs/decisions/Name Resolution - Callable Sets and Cross-Module Linking Decision.md`
- `docs/pbs/decisions/Name Resolution - Linking Phase Boundary Decision.md`
## 11. Validation Notes
The intended baseline is:
- all top-level declarations in a module exist before barrel filtering,
- lookup is namespace-specific and deterministic,
- the effective visible import name is the alias name when an alias is present,
- whole-module import through `import { * } from @project:path;` introduces exported names rather than a module object,
- local/import collisions are rejected rather than shadowed,
- and builtin simple types remain reserved always-available names outside ordinary import competition.
Illustrative examples:
```pbs
import { Foo } from @a:m;
declare const Foo: int = 1;
```
This is rejected as a local-versus-import collision in the value namespace.
```pbs
import { f } from @a:m;
import { f } from @b:n;
```
This is rejected because the visible imported names match but the canonical origins differ.
```pbs
fn f(a: int) -> int { ... }
import { f } from @a:m;
```
This is rejected as a local-versus-import collision in callable position.
```pbs
import { * } from @a:m;
```
This introduces the exported visible names of `@a:m`, but does not introduce a source-visible module object in v1.
```pbs
import { A as aaa } from @a:m;
```
The visible local declaration name is `aaa`, not `A`.

130
docs/compiler/pbs/decisions/Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Decision.md
View File

@ -1,130 +0,0 @@
# Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Decision
Status: Accepted
Date: 2026-03-22
Related Agenda: `docs/compiler/pbs/agendas/19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda.md`
## Context
After closing globals and lifecycle semantics, PBS v1 still needed a precise publication contract for executable boot.
The remaining problem was no longer how initialization behaves in userland.
It was how that behavior is published into the artifact and consumed by backend stages and runtime.
The open points were:
- whether the published entrypoint is still the user `frame()` callable,
- whether a synthetic wrapper becomes the true physical entrypoint,
- where `FRAME_RET` must live once lifecycle bootstrap exists,
- whether `FrontendSpec` continues to hold authority over entrypoint identity,
- and whether `manifest.json` remains part of entrypoint authority.
Important fixed inputs already existed:
- `[Frame]` identifies the userland logical frame root,
- module init and project init are already defined in lifecycle terms,
- boot is one-shot and fail-fast,
- and general backend specs already converge on entrypoint function index `0`.
## Decision
PBS adopts the following publication and ownership policy for executable boot in v1:
1. The compiler publishes a synthetic wrapper as the physical executable entrypoint.
2. The userland callable marked with `[Frame]` remains the logical frame root of user code.
3. The synthetic wrapper is therefore the physical root, while `[Frame]` remains the logical root.
4. The wrapper must contain:
- one-shot boot orchestration,
- the required init execution exactly once,
- invocation of the userland `[Frame]` callable,
- and the final `FRAME_RET`.
5. `FRAME_RET` no longer belongs at the end of the userland `frame()` body.
6. `FRAME_RET` belongs to the published wrapper.
7. The published wrapper must occupy physical entrypoint index `0`.
## Entrypoint Authority
PBS adopts the following authority model:
1. `FrontendSpec` no longer holds authority to decide which callable is the published entrypoint for PBS.
2. Entrypoint authority is owned exclusively by the PBS compiler.
3. Source-derived lifecycle semantics determine the logical frame root.
4. The compiler then publishes the physical wrapper that realizes that lifecycle contract.
5. Backend handoff must therefore preserve the compiler-selected published wrapper as the effective entrypoint identity.
## Manifest and Runtime Protocol
PBS adopts the following target protocol direction:
1. `entrypoint` must stop being part of the final `manifest.json` contract.
2. Runtime boot must not depend on nominal entrypoint resolution from the manifest.
3. Runtime boot must treat physical entrypoint index `0` as protocol.
4. The compiler guarantees that the published wrapper occupies that index.
5. Any temporary compatibility line with manifest-declared nominal entrypoint is transitional only and is not the target contract.
## Exports Boundary
PBS adopts the following boundary for nominal exports:
1. Nominal function exports may continue to exist in the emitted artifact.
2. Those exports are no longer authoritative for loader or boot.
3. Boot depends exclusively on the published physical entrypoint at index `0`.
4. Nominal exports remain useful only for tooling, debug, introspection, and related non-boot concerns.
## Rationale
This decision keeps logical user semantics and physical boot publication clearly separated.
That matters because:
- the user `frame()` callable should remain the semantic root of frame logic,
- the one-shot bootstrap sequence must still execute before normal frame work,
- `FRAME_RET` should mark the true end of the logical published frame,
- and the compiler must be the single authority that turns source lifecycle into executable publication.
The decision also deliberately removes duplicated authority:
- not `FrontendSpec`,
- not manifest nominal metadata,
- and not PBX nominal exports
are allowed to compete with the compiler-selected physical wrapper as boot authority.
## Invariants
1. `[Frame]` remains the userland logical frame root.
2. The published wrapper remains the physical executable root.
3. `FRAME_RET` belongs to the published wrapper.
4. Physical entrypoint index `0` belongs to that wrapper.
5. Nominal exports are not boot authority.
6. Entrypoint authority for PBS belongs to the compiler, not to `FrontendSpec` or manifest metadata.
## Explicit Non-Decisions
1. This decision does not define the final IR encoding of the wrapper body.
2. This decision does not define the detailed lowering mechanics of globals and lifecycle into IR.
3. This decision does not define the runtime-side migration implementation plan in detail.
4. This decision does not define the final diagnostics catalog for backend/runtime structural failures.
## Spec Impact
This decision should feed at least:
1. `docs/compiler/pbs/specs/9. Dynamic Semantics Specification.md`
2. `docs/compiler/pbs/specs/13. Lowering IRBackend Specification.md`
3. `docs/compiler/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md`
4. `docs/compiler/general/specs/15. Bytecode and PBX Mapping Specification.md`
5. `docs/compiler/general/specs/20. IRBackend to IRVM Lowering Specification.md`
It also requires explicit cross-domain propagation to:
1. `../runtime/docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`
## Validation Notes
At minimum, validation for this decision should include:
1. emitted artifact evidence that the published wrapper occupies function index `0`;
2. conformance evidence that the userland `[Frame]` callable is invoked by that wrapper rather than being published directly;
3. evidence that `FRAME_RET` is emitted in the wrapper path;
4. evidence that nominal exports, when present, do not participate in boot authority;
5. integration evidence that runtime boot aligns with the fixed physical entrypoint protocol.

44
docs/compiler/pbs/decisions/README.md
View File

@ -1,44 +0,0 @@
# PBS Decisions
This directory contains PBS decision records.
## Purpose
A decision record is the bridge between agenda discussion and normative spec text.
Use this directory to capture:
- what was decided,
- why that direction was chosen,
- which constraints now apply,
- what remains intentionally out of scope,
- which specs must be updated.
Architecture and decisions must be resolved before implementation.
## Expected Format
A decision record should usually include:
1. Title
2. Status
3. Date or Cycle
4. Context
5. Decision
6. Invariants
7. Explicit Non-Decisions
8. Spec Impact
9. Validation Notes or Examples
## Writing Rules
- Write in stable, reviewable language.
- State the adopted decision first and clearly.
- Capture architectural constraints and invariants explicitly.
- Record what is still not decided so later implementation does not guess.
- Point to the exact specs that need integration.
## Implementation Rule
If implementation work exposes a missing decision, do not infer it.
Stop, surface the ambiguity, and return it to agenda or decision review.

41
docs/compiler/pbs/decisions/SPAWN-YIELD v1 Claim Rescope Decision.md
View File

@ -1,41 +0,0 @@
# SPAWN-YIELD v1 Claim Rescope Decision
Status: Accepted
Cycle: Agenda 18 / PR-06.6
## Context
Os requisitos `G20-9.4.2` e `G20-9.4.3` estavam em estado `deferred` porque `SPAWN` e `YIELD` ainda nao fazem parte da superficie executavel v1 atualmente claimada pelo backend.
Sem uma decisao formal, o claim ficava ambiguo para auditoria externa.
## Decision
Adotamos oficialmente a **Trilha B**.
1. `SPAWN` e `YIELD` ficam fora do escopo do claim executavel `core-v1`.
2. O backend v1 deve tratar essas formas como nao-suportadas no escopo claimado.
3. Invariantes especificas de aridade/stack para `SPAWN` e `YIELD` ficam reservadas para um perfil futuro que as admita explicitamente.
## Invariants
1. Nenhum claim `core-v1` pode implicar suporte executavel a `SPAWN`/`YIELD`.
2. Se um perfil futuro admitir `SPAWN`/`YIELD`, deve publicar evidencias de conformidade dedicadas antes de claim de suporte.
3. Matriz de conformidade deve explicitar o rescope para evitar regressao silenciosa de claim.
## Spec Impact
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`:
- secao 9.4 passa a declarar `SPAWN`/`YIELD` fora do escopo de `core-v1`.
2. `docs/general/specs/17. Compatibility and Evolution Policy.md`:
- claims suportados devem explicitar superficies executaveis excluidas.
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`:
- linhas `G20-9.4.2` e `G20-9.4.3` saem de `deferred` para status alinhado ao rescope.
## Validation Notes
Validacao desta decisao e documental/policy:
1. testes de integridade de spec/matriz para `SPAWN`/`YIELD` claim rescope;
2. verificacao explicita de status e notas na matriz;
3. rastreabilidade via esta decision record.

190
docs/compiler/pbs/decisions/Value Representation and Identity Decision.md
View File

@ -1,190 +0,0 @@
# Value Representation and Identity Decision
Status: Accepted (Implemented)
Cycle: Initial value-representation closure pass
## 1. Context
PBS v1 needs a stable user-visible model for:
- which values are pure copied payloads,
- which values preserve shared runtime identity,
- which carriers merely wrap other values,
- and how callback values fit into the language without exposing general first-class functions or closures.
Earlier decisions already fixed important inputs:
- structs are reference-like in ordinary use,
- services are canonical singleton values,
- `bind(context, fn_name)` captures the same struct identity without copying it,
- `optional` and `result` remain explicit carriers rather than implicit effect-lifting mechanisms.
## 2. Decision
PBS v1 adopts the following value-representation baseline:
1. Pure scalar-like values are copied by value and do not carry user-visible identity.
2. Struct values are identity-bearing, heap-backed reference values.
3. Service values are identity-bearing canonical singleton values.
4. Host-backed resource values are identity-bearing values on the PBS side, even though their backing authority remains host-owned.
5. Tuple, `optional`, and `result` carriers do not introduce identity of their own.
6. Contract values do not introduce a new user-visible identity distinct from the underlying struct or service value.
7. Callback values are first-class callable values in PBS v1, but callback identity is not promoted as a user-visible identity concept.
8. Assignment, parameter passing, and return preserve aliasing for identity-bearing values and copy payload for pure value kinds.
## 3. Value Categories
### 3.1 Pure copied values
The following value kinds are pure copied values in the user model:
- `int`
- `float`
- `bool`
- enum values
- canonical `str`
Assignment, parameter passing, and return of these values copy the value itself.
### 3.2 Identity-bearing values
The following value kinds carry stable user-visible identity:
- struct values
- service values
- host-backed resource/handle values
Assignment, parameter passing, and return of these values preserve aliasing to the same runtime entity rather than copying an independent underlying object.
### 3.3 Carrier-only values
The following value kinds are carriers and do not create identity of their own:
- tuples
- `optional`
- `result`
They preserve the semantics of the values they contain.
If a carrier contains an identity-bearing payload, the carrier transports that same payload identity rather than inventing a new one.
## 4. Structs
Struct values are always reference-like in PBS v1.
Rules:
- `new Struct(...)` produces a fresh struct identity.
- Assignment of a struct value copies the reference, not the underlying field storage.
- Passing or returning a struct value preserves aliasing to the same struct instance.
- Mutation through one alias is observable through other aliases to that same struct instance.
## 5. Services
Service values are canonical module-owned singleton values.
Rules:
- A service value denotes the same singleton identity wherever it is used in the same resolved program.
- Assignment, parameter passing, and return preserve that same singleton identity.
- Service use does not create fresh service instances.
## 6. Contract Values
Contract values do not introduce a new user-visible entity.
A contract value is a runtime view over:
- an underlying struct identity or service singleton identity,
- together with the selected contract implementation used for dispatch.
For user-facing semantics:
- aliasing is defined by the underlying struct or service value,
- not by treating the contract wrapper as a separate identity-bearing object.
## 7. Callback Values
Callback values are first-class callable values in PBS v1.
This means they may be:
- assigned to variables,
- passed as arguments,
- and returned from functions.
However, PBS v1 does not promote callback identity as an explicit user-visible identity concept.
### 7.1 Plain callback values
When a callback value is formed from a compatible top-level `fn`, it denotes a callable value over that target function.
### 7.2 Bound callback values
When a callback value is formed through `bind(context, fn_name)`:
- the same struct context identity is captured,
- the context is not copied,
- the callback retains the target function together with that captured context,
- and invoking the callback behaves as if the target function is called with the captured context as its first argument.
### 7.3 User model
The language must explain callback behavior without requiring the user to reason about callback identity as if callbacks were ordinary heap objects.
It is sufficient to state that:
- callbacks are first-class callable values,
- bound callbacks retain their captured context,
- and copies of a callback value preserve the same callable meaning and retained context.
## 8. Copy Versus Aliasing Rule
The general rule for PBS v1 is:
- pure value kinds are copied by value,
- identity-bearing kinds preserve aliasing,
- carrier kinds preserve the semantics of their contained values and do not create identity of their own.
Examples:
- assigning an `int` copies the integer value,
- assigning a `Struct` value copies the reference to the same struct instance,
- assigning an `optional<Player>` that contains `some(player)` preserves the same `Player` identity inside the carrier,
- assigning a `result<E> Player` success payload preserves the same `Player` identity inside the carrier.
## 9. Beginner-Facing Model
The user-facing explanation should be:
- some values are plain data, so passing them passes the value,
- structs and services are shared entities, so passing them passes access to the same entity,
- tuples, `optional`, and `result` only package values and do not become new entities by themselves,
- callbacks are callable values, and bound callbacks keep the same captured context rather than copying it.
This wording is simple enough for beginners while still preserving the performance-relevant truth about aliasing and mutation.
## 10. Explicit Non-Decisions
This decision record does not yet close:
- the exact runtime layout of any heap object,
- collection value categories in detail,
- the final host-backed handle representation syntax,
- the final diagnostics wording for aliasing/copy visibility.
## 11. Spec Impact
This decision should feed at least:
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/4. Static Semantics Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
## 12. Validation Notes
The intended split is:
- structs, services, and host-backed resources behave like identity-bearing entities,
- tuples, `optional`, and `result` are carriers,
- callbacks are first-class callable values without promoted callback identity in the user model.

211
docs/compiler/pbs/pull-requests/INDEX.md
View File

@ -1,211 +0,0 @@
# PBS Frontend PR Sequence
Este indice organiza uma sequencia de PRs atomicas para levar `frontends/pbs` ao contrato das specs.
1. `PR-001-pbs-lexer-core-syntax-alignment.md`
2. `PR-002-pbs-ast-contract-v1.md`
3. `PR-003-pbs-parser-declarations-and-types.md`
4. `PR-004-pbs-parser-statements-and-control-flow.md`
5. `PR-005-pbs-parser-expressions-optional-result-apply.md`
6. `PR-006-pbs-barrel-and-module-visibility.md`
7. `PR-006.2-pbs-parser-ast-syntax-hardening.md`
8. `PR-006.3-pbs-syntax-completeness-and-module-hygiene.md`
9. `PR-007-pbs-static-semantics-declaration-validation.md`
10. `PR-008-pbs-static-semantics-call-resolution-and-flow.md`
11. `PR-009-pbs-diagnostics-contract-v1.md`
12. `PR-010-pbs-irbackend-lowering-contract.md`
13. `PR-011-pbs-gate-u-conformance-fixtures.md`
Cada documento e auto contido e inclui: `Briefing`, `Target`, `Method`, `Acceptance Criteria` e `Tests`.
## Non-Conformance Remediation PRs
14. `PR-012-pbs-byte-offset-spans.md`
15. `PR-013-pbs-import-unresolved-diagnostics.md`
16. `PR-014-pbs-switch-wildcard-rules.md`
17. `PR-015-pbs-this-self-context-validation.md`
18. `PR-016-pbs-assignment-target-and-field-access-semantics.md`
19. `PR-017-pbs-const-evaluation-and-dependency-rules.md`
20. `PR-018-pbs-result-flow-ok-err-handle-rules.md`
21. `PR-019-pbs-non-unit-fallthrough-diagnostics.md`
22. `PR-020-pbs-lowering-admission-gates.md`
23. `PR-021-pbs-handle-aware-fallthrough-completion.md`
24. `PR-022-pbs-source-kind-and-module-origin-pipeline.md`
25. `PR-023-pbs-stdlib-environment-resolver-and-loader.md`
26. `PR-024-pbs-parser-ast-interface-module-mode.md`
27. `PR-025-pbs-interface-module-semantics-and-linking.md`
28. `PR-026-pbs-sdk-minimal-core-color-and-gfx.md`
29. `PR-027-pbs-builtin-metadata-extraction-and-ir-lowering-admission.md`
30. `PR-028-pbs-gate-u-sdk-interface-module-fixtures.md`
31. `PR-029-pbs-builtin-slot-inference-and-layout-semantics.md`
32. `PR-030-pbs-host-admission-capability-gating.md`
33. `PR-031-pbs-dependency-scoped-fail-fast-admission.md`
## Backend VM Pipeline PR Sequence (Agenda 18)
Esta sequencia organiza implementacao atomica para `IRBackend -> IRVM -> OptimizeIRVM -> EmitBytecode`, com trilha de montagem do output para o input (bytecode ate IRBackend).
34. `PR-032-backend-bytecode-module-serializer-baseline.md`
35. `PR-033-backend-bytecode-function-layout-and-debug-minimum.md`
36. `PR-034-backend-emitter-hostcall-sysc-contract.md`
37. `PR-035-backend-emit-stage-pipeline-wiring.md`
38. `PR-036-backend-irvm-core-model-and-validator.md`
39. `PR-037-backend-optimize-irvm-noop-stage-and-guards.md`
40. `PR-038-irbackend-v2-executable-contract-model.md`
41. `PR-039-pbs-frontend-irbackend-v2-lowering.md`
42. `PR-040-backend-lower-to-irvm-stage-implementation.md`
43. `PR-041-backend-gate-i-runtime-compat-integration-fixtures.md`
## JVM-Grade Remediation Waves (Execution Plan)
Esta trilha organiza as PRs por ondas para execucao incremental com rollback simples por item.
### Onda O1 - Conformance and Correctness Hardening
1. `PR-O1.1-backend-diagnostics-taxonomy-and-attribution.md`
2. `PR-O1.2-irbackend-executable-contract-hardening.md`
3. `PR-O1.3-pbs-executable-lowering-fidelity.md`
4. `PR-O1.4-lower-to-irvm-callsite-prechecks.md`
5. `PR-O1.5-bytecode-debug-minimum-completeness.md`
6. `PR-O1.6-gate-su-safety-matrix-completion.md`
### Onda O2 - JVM-Inspired Verification and Linking Boundaries
1. `PR-O2.1-bytecode-link-precheck-stage.md`
2. `PR-O2.2-bytecode-preload-verifier.md`
3. `PR-O2.3-optimize-irvm-pass-manager-and-equivalence.md`
4. `PR-O2.4-gate-i-runtime-backed-compat-harness.md`
### Onda O3 - Evolution and Scale
1. `PR-O3.1-irvm-control-flow-lowering-label-resolution.md`
2. `PR-O3.2-bytecode-constpool-symbol-interning-determinism.md`
3. `PR-O3.3-irvm-profile-evolution-and-feature-gates.md`
### Onda O4 - JVM-Grade Uplift
1. `PR-O4.1-callable-signature-identity-and-dense-symbol-table.md`
2. `PR-O4.2-global-intrinsic-table-and-reindexing.md`
3. `PR-O4.3-semantic-lowering-cfg-and-stack-analysis.md`
4. `PR-O4.4-irvm-program-single-source-of-truth.md`
5. `PR-O4.5-vm-profile-end-to-end-pipeline.md`
6. `PR-O4.6-strict-bytecode-precheck-unknown-opcode-rejection.md`
7. `PR-O4.7-gate-i-runtime-backed-execution-adapter.md`
8. `PR-O4.8-jvm-grade-regression-matrix-and-golden-artifacts.md`
### Onda O5.0 - Dense Table Identity Foundation (Pre-O5)
1. `PR-05.0.1-frontend-phase-shared-name-table-context.md`
2. `PR-05.0.2-module-identity-dense-table-and-moduleid-wiring.md`
3. `PR-05.0.3-irbackend-typed-callable-and-intrinsic-ids.md`
4. `PR-05.0.4-callable-shape-and-signature-interning.md`
5. `PR-05.0.5-synthetic-stdlib-fileid-via-filetable.md`
6. `PR-05.0.6-host-binding-key-interning-and-capability-identity.md`
### Onda O5 - JVM-Grade Score Evolution (5.6 -> 8.5+)
Prerequisito de execucao: concluir a Onda O5.0.
1. `PR-05.1-pbs-frontend-semantic-executable-lowering-cfg.md`
2. `PR-05.2-irbackend-callsite-classification-by-semantic-identity.md`
3. `PR-05.3-irvm-deterministic-function-id-and-entrypoint-policy.md`
4. `PR-05.4-irvm-program-coherence-without-bypass.md`
5. `PR-05.5-irvm-validator-real-stack-effects-hostcall-intrinsic.md`
6. `PR-05.6-optimize-irvm-real-deterministic-passes.md`
7. `PR-05.7-gate-i-runtime-backed-mandatory-in-ci.md`
8. `PR-05.8-backend-spec-to-test-conformance-matrix.md`
### Onda O6 - JVM-Grade Score Evolution (8.0 -> 9.0+)
Foco: fechar `partial/deferred` relevantes da matriz normativa e endurecer evidencia de conformidade.
1. `PR-06.1-source-attribution-and-diagnostics-evidence-hardening.md`
2. `PR-06.2-optimize-irvm-semantic-equivalence-harness.md`
3. `PR-06.3-irvm-ext-contract-and-elimination-fixtures.md`
4. `PR-06.4-gate-i-runtime-line-repeatability-ci.md`
5. `PR-06.5-conformance-matrix-hard-gate-policy.md`
6. `PR-06.6-spawn-yield-v1-or-claim-rescope.md`
### Onda O7 - Partial Closure Before IDE Focus
Foco: eliminar os dois `partial` remanescentes na matriz backend antes de mover foco principal para IDE.
1. `PR-07.1-optimize-irvm-span-source-hook-preservation.md`
2. `PR-07.2-pbs-callsite-category-no-textual-heuristics-regression.md`
3. `PR-07.3-irvm-entrypoint-export-emission-for-runtime-loader.md`
### Onda O8 - Canonical Identity and Dense Addressing Hardening
Foco: fechar lacunas estruturais em identidade canonica de intrinsic/modulo/entrypoint e remover riscos de ambiguidade no handoff FE->BE.
1. `PR-08.1-intrinsic-resolution-canonical-identity-keying.md`
2. `PR-08.2-irbackend-moduleid-contract-and-modulepool.md`
3. `PR-08.3-qualified-entrypoint-identity-contract.md`
4. `PR-08.4-call-func-callee-module-identity-correctness.md`
5. `PR-08.5-intrinsic-registry-single-source-sync-with-runtime.md`
### Onda O9 - ModuleId-Only Contract Cutover
Foco: remover definitivamente `moduleKey` textual do contrato estrutural FE->BE, endurecer entrypoint qualificado e alinhar specs/matriz com o modelo `ModuleId`-only.
1. `PR-09.1-irbackend-modulekey-hard-removal-from-contract.md`
2. `PR-09.2-pbs-frontend-moduleid-only-lowering-and-import-surfaces.md`
3. `PR-09.3-lower-to-irvm-moduleid-only-ordering-and-strict-qualified-entrypoint.md`
4. `PR-09.4-specs-refresh-moduleid-only-entrypointref-and-bytecode-alignment.md`
5. `PR-09.5-hard-gates-no-modulekey-regression-and-migration-cleanup.md`
6. `PR-09.6-isa-intrinsic-registry-single-source-artifact.md`
7. `PR-09.7-compiler-normalization-to-isa-registry-artifact.md`
### Onda O10 - Parser Maintainability Refactor (No Functional Change)
Foco: reduzir complexidade estrutural de `PbsParser` sem alterar gramatica, AST, spans ou contrato de diagnosticos observavel.
1. `PR-10.1-pbs-parser-shared-context-and-safe-delegation.md`
2. `PR-10.2-pbs-parser-attribute-and-type-subparsers.md`
3. `PR-10.3-pbs-parser-top-level-declaration-decomposition.md`
4. `PR-10.4-pbs-parser-block-and-statement-decomposition.md`
5. `PR-10.5-pbs-parser-recovery-utilities-and-regression-hardening.md`
### Onda O11 - Expression Parser Maintainability Refactor (No Functional Change)
Foco: reduzir complexidade estrutural de `PbsExprParser` sem alterar precedence, AST, spans, recovery ou diagnosticos observaveis.
1. `PR-11.1-pbs-expr-parser-shared-context-and-precedence-spine.md`
2. `PR-11.2-pbs-expr-parser-control-flow-subparsers.md`
3. `PR-11.3-pbs-expr-parser-postfix-primary-and-construction-decomposition.md`
4. `PR-11.4-pbs-expr-parser-literals-patterns-and-shared-token-utilities.md`
5. `PR-11.5-pbs-expr-parser-regression-hardening-and-final-cleanup.md`
### Onda O12 - Flow Expression Analyzer Maintainability Refactor (No Functional Change)
Foco: reduzir complexidade estrutural de `PbsFlowExpressionAnalyzer` sem alterar inferencia, diagnosticos, matching de tipos ou comportamento observavel da analise semantica.
1. `PR-12.1-flow-expression-analyzer-context-and-dispatch-foundation.md`
2. `PR-12.2-flow-expression-analyzer-literal-and-structural-expression-splitting.md`
3. `PR-12.3-flow-expression-analyzer-call-and-member-resolution-decomposition.md`
4. `PR-12.4-flow-expression-analyzer-switch-and-handle-decomposition.md`
5. `PR-12.5-flow-expression-analyzer-regression-hardening-and-final-cleanup.md`
### Onda O13 - Flow Body Analyzer Maintainability Refactor (No Functional Change)
Foco: reduzir complexidade estrutural de `PbsFlowBodyAnalyzer` sem alterar regras de flow, completion, assignment checking ou diagnosticos observaveis.
1. `PR-13.1-flow-body-analyzer-context-and-entrypoint-foundation.md`
2. `PR-13.2-flow-body-analyzer-callable-body-and-completion-decomposition.md`
3. `PR-13.3-flow-body-analyzer-statement-analysis-splitting.md`
4. `PR-13.4-flow-body-analyzer-assignment-target-resolution-decomposition.md`
5. `PR-13.5-flow-body-analyzer-regression-hardening-and-final-cleanup.md`
### Onda O19 - Globals, Lifecycle, Published Wrapper, and Conformance
Foco: implementar a familia `19` em sequencia executavel, com runtime boot protocol ja alinhado e `learn` deliberadamente postergado para fechamento posterior.
1. `PR-19.1-pbs-topic-19-spec-propagation-and-normative-cutover.md`
2. `PR-19.2-infra-dependencygraphanaliser-extraction-and-module-cutover.md`
3. `PR-19.3-pbs-parser-ast-globals-barrel-and-lifecycle-markers.md`
4. `PR-19.4-pbs-semantics-global-surface-identity-and-collision-validation.md`
5. `PR-19.5-pbs-semantics-global-dependency-graph-and-cycle-validation.md`
6. `PR-19.6-pbs-semantics-lifecycle-init-frame-and-initallowed-validation.md`
7. `PR-19.7-pbs-lowering-irbackend-globals-and-synthetic-callable-model.md`
8. `PR-19.8-pbs-lowering-published-wrapper-entrypoint-zero-and-frame-ret.md`
9. `PR-19.9-pbs-conformance-fixtures-diagnostics-and-gate-closure.md`

63
docs/compiler/pbs/pull-requests/PR-05.0.1-frontend-phase-shared-name-table-context.md
View File

@ -1,63 +0,0 @@
# PR-05.0.1 - Frontend Phase Shared NameTable Context
## Briefing
Hoje o frontend PBS cria `NameTable` em componentes diferentes (linking, declarative semantics, rules), o que fragmenta identidade de nome por fase.
Esta PR centraliza `NameTable` no `FrontendPhaseContext` para toda a fase de frontend, com um ciclo de vida unico por compilacao.
## Motivation
### Dor que esta PR resolve
1. Mesma string pode receber `NameId` diferente dependendo da fase.
2. Dificulta evoluir para identidades tipadas cross-phase sem adaptadores de conversao.
3. Complica debug e rastreabilidade de diagnosticos semanticos entre linking e lowering.
## Target
Uniformizar identidade de nomes no FE inteiro, com `NameId` estavel durante a fase de frontend.
## Scope
1. `FrontendPhaseContext` passa a expor `NameTable`.
2. Validators e binders do PBS passam a receber `NameTable` do contexto, sem criar tabela local.
3. Ajuste de testes que dependem de instanciacao direta.
## Non-Goals
1. Nao altera regras semanticas.
2. Nao altera parser/AST.
## Method
### O que deve ser feito explicitamente
1. Adicionar `NameTable` ao contexto da fase de frontend.
2. Remover `new NameTable()` locais em linking/semantics.
3. Injetar o `NameTable` compartilhado em:
- `PbsModuleVisibilityValidator`,
- `PbsDeclarationSemanticsValidator`,
- `PbsDeclarationRuleValidator`,
- `PbsNamespaceBinder`.
4. Garantir que o ciclo de vida da tabela seja por execucao de fase, nao global estatico.
## Acceptance Criteria
1. Nao existe mais alocacao local de `NameTable` nas fases PBS do frontend.
2. Mesmo nome gera mesmo `NameId` em linking e semantica na mesma compilacao.
3. Testes de linking/semantica continuam passando sem regressao comportamental.
## Tests
1. Teste de identidade cruzada (linking vs declaration validation) para nomes iguais.
2. Teste de isolamento entre duas compilacoes diferentes (nao vazar IDs entre runs).
## Affected Documents
1. `docs/pbs/specs/11. AST Specification.md`
2. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
## Open Questions
Sem bloqueios arquiteturais.

59
docs/compiler/pbs/pull-requests/PR-05.0.2-module-identity-dense-table-and-moduleid-wiring.md
View File

@ -1,59 +0,0 @@
# PR-05.0.2 - Module Identity Dense Table and ModuleId Wiring
## Briefing
O FE usa `String moduleKey` em varios mapas e no handoff para backend.
Esta PR introduz identidade densa de modulo (`ModuleTable` + `ModuleId`) e faz o FE operar internamente por ID, mantendo string apenas como representacao de borda quando necessario.
## Motivation
### Dor que esta PR resolve
1. Chaves string de modulo sao repetidas e suscetiveis a inconsistencia de normalizacao.
2. Custos de hash/string crescem com o grafo de modulos.
3. Dificuldade de garantir determinismo e joins estaveis em agregacao multi-modulo.
## Target
Substituir identidade interna de modulo baseada em string por `ModuleId` internado.
## Scope
1. Criacao de `ModuleTable` no core.
2. Uso de `ModuleId` em `PBSFrontendPhaseService` para mapas de modulo/dependencias.
3. Adaptacao de pontos de diagnostico e exibição para renderizar nome canônico quando preciso.
## Non-Goals
1. Nao altera sintaxe de import.
2. Nao altera formato de mensagens ao usuario final alem do necessario.
## Method
### O que deve ser feito explicitamente
1. Implementar `ModuleTable extends InternTable<ModuleId, ModuleRef>` (ou valor equivalente canonico).
2. Trocar `Map<String,...>` de modulo em `PBSFrontendPhaseService` por `Map<ModuleId,...>`.
3. Trocar grafo de dependencia de `String` para `ModuleId`.
4. Manter funcao unica de render de modulo para diagnostico.
## Acceptance Criteria
1. Fluxo principal do FE nao depende de `moduleKey` string para joins internos.
2. Dependencias e bloqueios por falha de modulo usam `ModuleId`.
3. Nao ha regressao funcional em linking/import gating.
## Tests
1. Teste de determinismo de IDs de modulo para mesmo grafo admitido.
2. Teste de propagacao de falha por dependencia usando IDs.
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
## Open Questions
Sem bloqueios arquiteturais.

62
docs/compiler/pbs/pull-requests/PR-05.0.3-irbackend-typed-callable-and-intrinsic-ids.md
View File

@ -1,62 +0,0 @@
# PR-05.0.3 - IRBackend Typed Callable and Intrinsic IDs
## Briefing
O contrato `IRBackendExecutableFunction` ainda carrega `callableId`, `calleeCallableId` e `intrinsicId` como `int/Integer`.
Esta PR tipa esses campos com `CallableId` e `IntrinsicId`, alinhando model com Dense Tables e reduzindo erro de classe de ID.
## Motivation
### Dor que esta PR resolve
1. Mistura acidental entre dominios de ID diferentes em tempo de desenvolvimento.
2. Validacoes repetitivas de faixa/semantica por usar primitivo nu.
3. API de backend menos segura para evolucao de lowering/remap.
## Target
Evoluir o contrato de FE->BE para IDs tipados em vez de inteiros crus.
## Scope
1. `IRBackendExecutableFunction` e metadados de instrucao.
2. `IRBackendAggregator` remap de callables e intrinsecos.
3. Ajustes de serializers/tests que assumem `int`.
## Non-Goals
1. Nao muda semantica de chamada.
2. Nao muda ordenacao de remap por si so.
## Method
### O que deve ser feito explicitamente
1. Trocar:
- `int callableId` -> `CallableId`,
- `Integer calleeCallableId` -> `CallableId` (nullable quando aplicavel),
- `int intrinsicId` -> `IntrinsicId`.
2. Atualizar construtores/guards para validar `.isNone()` e nao-negatividade via tipo.
3. Atualizar `IRBackendAggregator` para trabalhar com vetores/tabelas de IDs tipados.
4. Atualizar FE lowering PBS para emitir IDs tipados desde origem.
## Acceptance Criteria
1. Nao ha mais campos de callable/intrinsic ID como inteiro cru no contrato executavel.
2. Tentativas de misturar dominio de ID falham em compile-time.
3. Testes de remap e merge seguem verdes.
## Tests
1. Testes unitarios de construcao de instrucao com tipos corretos/incorretos.
2. Testes de agregacao multi-arquivo validando remap tipado.
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
## Open Questions
Sem bloqueios arquiteturais.

62
docs/compiler/pbs/pull-requests/PR-05.0.4-callable-shape-and-signature-interning.md
View File

@ -1,62 +0,0 @@
# PR-05.0.4 - Callable Shape and Signature Interning
## Briefing
O FE ainda monta chaves semanticas por concat string (`name#arity`, `signatureSurface`, `typeShape`).
Esta PR cria internacao para superfícies de assinatura/shape e remove concatenação textual como identidade primaria.
## Motivation
### Dor que esta PR resolve
1. Chave textual e fragil para evolucao de formato.
2. Custo de alocacao/hash desnecessario em caminhos quentes.
3. Risco de colisao logica por normalizacao incompleta.
## Target
Internar shapes de callable e superfícies de assinatura em tabela dedicada, com ID estavel.
## Scope
1. Estruturas de assinatura do linking e lowering.
2. `CallableSignatureRef` com suporte a referencia internada de shape.
3. Remocao gradual de `callableArityKey` e derivados string.
## Non-Goals
1. Nao altera regra de overload.
2. Nao altera formato externo de diagnostico.
## Method
### O que deve ser feito explicitamente
1. Introduzir tabela de shapes (ex.: `CallableShapeTable` / `TypeSurfaceTable`).
2. Representar identidade de callable por tupla tipada (`NameId`, aridade, `ShapeId`).
3. Atualizar:
- linking (`FunctionSymbolKey`),
- FE lowering executavel (`callableIdsByNameAndArity`),
- referencias em `CallableSignatureRef`.
4. Manter conversao para string apenas para logs/debug.
## Acceptance Criteria
1. Fluxo principal de resolução de callable nao depende de concat string.
2. Determinismo de shape/signature comprovado por ID internado.
3. Nenhuma regressao de resolução de overload/documentada.
## Tests
1. Teste de internacao idempotente para shape identico.
2. Testes de distinção para shapes diferentes com mesmo nome/arity.
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
## Open Questions
Sem bloqueios arquiteturais.

59
docs/compiler/pbs/pull-requests/PR-05.0.5-synthetic-stdlib-fileid-via-filetable.md
View File

@ -1,59 +0,0 @@
# PR-05.0.5 - Synthetic Stdlib FileId via FileTable
## Briefing
`InterfaceModuleLoader` hoje aloca `FileId` sintetico por `AtomicInteger`.
Esta PR move a alocacao de arquivos sinteticos para o `FileTable`, mantendo uma unica autoridade de identidade de arquivo.
## Motivation
### Dor que esta PR resolve
1. Risco de colisao/deriva de `FileId` fora da infraestrutura oficial.
2. Arquivos sinteticos ficam fora da trilha normal de metadata de source.
3. Diagnosticos e spans de stdlib perdem consistencia de origem no pipeline.
## Target
Fazer todo `FileId` (incluindo sintetico) vir do `FileTable`.
## Scope
1. `InterfaceModuleLoader`.
2. Contexto de carga de stdlib/interface para suportar registro no `FileTable`.
3. Source handle sintetico minimo para parser/diagnostico.
## Non-Goals
1. Nao altera conteudo dos modulos stdlib.
2. Nao altera parse mode de interface.
## Method
### O que deve ser feito explicitamente
1. Criar `SourceHandle` sintetico para fontes carregadas da stdlib/interface.
2. Registrar cada handle no `FileTable` e usar `FileId` retornado.
3. Remover contador `AtomicInteger` de `InterfaceModuleLoader`.
4. Preservar caminho lógico para mensagens (ex.: origem virtual stdlib).
## Acceptance Criteria
1. `InterfaceModuleLoader` nao usa mais `new FileId(...)`.
2. Todo `FileId` de stdlib/interface existe no `FileTable`.
3. Diagnosticos em fontes sinteticas mantem atribuicao consistente.
## Tests
1. Teste de carga de interface garantindo que `FileId` sintetico foi registrado no `FileTable`.
2. Teste de span/diagnostico para arquivo sintetico.
## Affected Documents
1. `docs/pbs/specs/11. AST Specification.md`
2. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
## Open Questions
Sem bloqueios arquiteturais.

59
docs/compiler/pbs/pull-requests/PR-05.0.6-host-binding-key-interning-and-capability-identity.md
View File

@ -1,59 +0,0 @@
# PR-05.0.6 - Host Binding Key Interning and Capability Identity
## Briefing
A validacao de host admission ainda usa chave composta em string (`module|method|version`) para deduplicacao e consistencia.
Esta PR troca chave textual por identidade internada de binding host e prepara capacidade para validacoes mais seguras.
## Motivation
### Dor que esta PR resolve
1. Concatenacao textual para chave critica de ABI e fragil.
2. Risco de bug por normalizacao inconsistente de partes da chave.
3. Menor clareza para evoluir validacao de capabilities por dominio tipado.
## Target
Internar identidade canonica de host binding em tabela dedicada e usar ID no validador de host admission.
## Scope
1. `PbsHostAdmissionValidator`.
2. Infra de tabela de binding host no core/frontend.
3. Ajustes em metadados reservados quando necessario.
## Non-Goals
1. Nao altera semantica de capability policy.
2. Nao altera contrato de host ABI no runtime.
## Method
### O que deve ser feito explicitamente
1. Introduzir valor canônico `HostBindingRef(module,name,version)` e tabela internada.
2. Substituir map com chave string por map com `HostBindingId` (ou `HostBindingRef` internado).
3. Manter normalizacao de capability separada da identidade de binding.
4. Preservar diagnosticos com referencias claras ao binding original.
## Acceptance Criteria
1. `PbsHostAdmissionValidator` nao usa mais chave formatada por string para binding.
2. Inconsistencia de capability para mesmo binding continua detectada de forma deterministica.
3. Nao ha regressao em cenarios conhecidos de host admission.
## Tests
1. Teste de deduplicacao de binding por identidade internada.
2. Teste de mismatch de capability para mesmo binding.
## Affected Documents
1. `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
2. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
## Open Questions
Sem bloqueios arquiteturais.

78
docs/compiler/pbs/pull-requests/PR-05.1-pbs-frontend-semantic-executable-lowering-cfg.md
View File

@ -1,78 +0,0 @@
# PR-05.1 - PBS Frontend Semantic Executable Lowering (CFG)
## Briefing
O frontend PBS ainda gera `IRBackendExecutableFunction` por varredura de callsites no AST, o que perde semântica de execução real.
Esta PR substitui esse caminho por lowering semântico baseado em fluxo de controle (CFG), preservando ordem de execução, terminadores e formas de desvio.
## Motivation
### Dor atual que esta PR resolve
1. Execução divergente entre programa fonte e artefato gerado em cenários com `if`, `while`, `for`, `switch`, `handle` e `return` antecipado.
2. Impossibilidade de elevar o backend para JVM-grade porque o contrato executável nasce semanticamente incompleto.
3. Falsos positivos de conformidade: testes passam para casos lineares, mas o modelo quebra em fluxo real.
## Target
Esta PR altera o frontend PBS para que `IRBackendExecutableFunction.instructions` represente fluxo executável real, não apenas uma lista de chamadas encontradas.
## Dependencies
Prerequisitos diretos:
1. `PR-05.0.1` (NameTable compartilhada por fase).
2. `PR-05.0.2` (identidade de modulo por `ModuleId`).
3. `PR-05.0.3` (IDs tipados de callable/intrinseco no contrato).
4. `PR-05.0.4` (internacao de shape/signature).
## Scope
1. Gerador de IR executável no frontend PBS.
2. Emissão de labels e jumps para estruturas de controle.
3. Recalculo de `maxStackSlots` com base no fluxo emitido.
4. Testes de fidelidade semântica do FE para IR executável.
## Non-Goals
1. Não introduz otimizações.
2. Não altera formato binário PBX.
3. Não altera runtime.
## Method
### O que deve ser feito explicitamente
1. Substituir o mecanismo de `collectCallsFrom*` por lowering orientado a nós semânticos de statements/expressions.
2. Emitir instruções de controle (`LABEL`, `JMP`, `JMP_IF_TRUE`, `JMP_IF_FALSE`, `RET`) para cada forma de fluxo suportada.
3. Garantir que `return` termine bloco/caminho e que caminhos alcançáveis terminem em instrução terminadora.
4. Preservar spans de origem em cada instrução emitida para diagnóstico.
5. Manter validação fail-fast quando existir forma semântica não lowerável em v1.
6. Atualizar análise de stack para operar sobre o programa realmente emitido.
7. Emitir referências de chamada via IDs tipados (`CallableId`/`IntrinsicId`) sem chave textual ad-hoc.
## Acceptance Criteria
1. `IRBackendExecutableFunction` deixa de ser construído por varredura cega de callsites.
2. Para casos com ramificação e laço, a ordem de execução no IR executável é semanticamente equivalente ao AST validado.
3. Funções com `return` antecipado não emitem execução espúria após ponto de saída.
4. `maxStackSlots` calculado bate com programa emitido e passa em validação backend.
5. Diagnósticos de lowering preservam fase e span corretamente.
6. Não há lookup de identidade de callsite baseado em concatenação string no caminho principal.
## Tests
1. Testes positivos com fixtures de `if/else`, `while`, `for`, `switch`, `handle`, `return` antecipado.
2. Testes negativos para caminhos sem terminador, labels inválidos e formas não suportadas.
3. Teste de regressão comparando resultado anterior vs novo para provar correção em casos não lineares.
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/19. Verification and Safety Checks Specification.md`
## Open Questions
Sem bloqueios arquiteturais. Implementação deve seguir decisões já fechadas na Agenda 18.

73
docs/compiler/pbs/pull-requests/PR-05.2-irbackend-callsite-classification-by-semantic-identity.md
View File

@ -1,73 +0,0 @@
# PR-05.2 - IRBackend Callsite Classification by Semantic Identity
## Briefing
A classificação de callsites no frontend executável ainda depende de heurística textual de callee.
Esta PR torna obrigatória a classificação por identidade semântica resolvida no binding, eliminando inferência por nome/forma textual.
## Motivation
### Dor atual que esta PR resolve
1. Risco de classificar callsite no bucket errado (`CALL_FUNC`, `CALL_HOST`, `CALL_INTRINSIC`).
2. Ambiguidade em member/bind/group callee com nome coincidente.
3. Falta de robustez em evolução de sintaxe semântica do FE.
## Target
Fronteira `PBS FE -> IRBackend` com identidade de callsite estável e sem heurística textual para decisão de categoria.
## Dependencies
Prerequisitos diretos:
1. `PR-05.0.1` (NameTable compartilhada).
2. `PR-05.0.2` (ModuleId no FE).
3. `PR-05.0.3` (CallableId/IntrinsicId tipados no contrato).
4. `PR-05.0.4` (shape/signature internadas).
## Scope
1. Resultado de resolução semântica para chamadas.
2. Estrutura de lowering para carregar identidade resolvida.
3. Diagnósticos quando identidade não estiver resolvida no ponto exigido.
## Non-Goals
1. Não muda política de overload além do já definido em semântica.
2. Não introduz novas categorias de callsite.
## Method
### O que deve ser feito explicitamente
1. Propagar do analisador semântico para lowering um descritor explícito de destino de chamada.
2. O descritor deve carregar identidade canônica tipada (ao menos categoria + id alvo), sem depender de nome textual.
3. Remover dependência de `extractSimpleCalleeName` para classificação.
4. Exigir que cada callsite emitido em `IRBackend` esteja em exatamente uma categoria válida.
5. Emitir erro determinístico quando o FE não possuir identidade semântica suficiente para classificar o callsite.
6. Validar compatibilidade de metadados obrigatórios por categoria no ato de emissão.
## Acceptance Criteria
1. Classificação de callsite não depende de parsing textual de callee.
2. Cada callsite em `IRBackend` possui categoria única e metadados obrigatórios.
3. Casos ambíguos geram diagnóstico estável em fase correta, sem fallback heurístico.
4. Não há regressão em casos já válidos.
5. O payload de callsite no contrato executável é tipado por ID, não por inferência textual.
## Tests
1. Testes positivos para chamadas de função, host e intrínseco com diferentes formas sintáticas.
2. Testes negativos de ambiguidade e callee não resolvido.
3. Testes de estabilidade diagnóstica (code/phase/span).
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
## Open Questions
Sem bloqueios arquiteturais.

70
docs/compiler/pbs/pull-requests/PR-05.3-irvm-deterministic-function-id-and-entrypoint-policy.md
View File

@ -1,70 +0,0 @@
# PR-05.3 - IRVM Deterministic Function-ID and Entrypoint Policy
## Briefing
A regra de indexação de funções e seleção de entrypoint precisa ficar estritamente alinhada ao contrato normativo para evitar divergência entre builds equivalentes.
Esta PR fecha política determinística de `func_id` e entrypoint único explícito.
## Motivation
### Dor atual que esta PR resolve
1. Possível variação de `func_id` quando ordem de merge muda.
2. Risco de entrypoint implícito ou ambíguo.
3. Dificuldade para gerar artefatos reproduzíveis e goldens estáveis.
## Target
`LowerToIRVMService` com regra única e testável de ordenação/indexação/entrypoint.
## Dependencies
Prerequisitos diretos:
1. `PR-05.0.2` (identidade de modulo por `ModuleId`).
2. `PR-05.0.3` (IDs tipados de callable).
## Scope
1. Ordenação determinística de funções.
2. Política explícita de entrypoint.
3. Diagnóstico para ausência ou ambiguidade de entrypoint.
## Non-Goals
1. Não altera ABI de chamada.
2. Não altera layout binário do bytecode.
## Method
### O que deve ser feito explicitamente
1. Definir ordenação canônica apenas pelos campos normativos aprovados.
2. Tornar explícita a ordenação de módulo a partir do `ModuleId` canônico.
3. Exigir exatamente um entrypoint válido no grafo admitido.
4. Atribuir `func_id=0` ao entrypoint e indexar demais por ordem canônica.
5. Rejeitar determinísticamente casos sem entrypoint ou com entrypoint múltiplo.
6. Cobrir cenários de permutação de entrada com mesma saída de indexação.
## Acceptance Criteria
1. Mesma entrada admitida gera mesma tabela de `func_id` em execuções repetidas.
2. Mudança na ordem de merge dos módulos não altera indexação final.
3. Ausência ou ambiguidade de entrypoint falha com diagnóstico estável.
4. A ordenação não depende de string derivada não canônica de módulo.
## Tests
1. Teste de determinismo com permutação de ordem de merge.
2. Teste de entrypoint único válido.
3. Testes negativos para zero entrypoint e múltiplos entrypoints.
## Affected Documents
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
2. `docs/general/specs/19. Verification and Safety Checks Specification.md`
## Open Questions
Sem bloqueios arquiteturais.

68
docs/compiler/pbs/pull-requests/PR-05.4-irvm-program-coherence-without-bypass.md
View File

@ -1,68 +0,0 @@
# PR-05.4 - IRVM Program Coherence Without Bypass
## Briefing
Existe bypass de coerência no `IRVMProgram` em presença de `RAW_SYSCALL` e derivação com placeholders (`__unknown__`).
Esta PR remove esses atalhos do fluxo canônico e endurece o contrato de coerência `IRVM <-> EmissionPlan`.
## Motivation
### Dor atual que esta PR resolve
1. Programa pode aparentar coerente e mesmo assim carregar informação inválida para emissão.
2. Brecha para mascarar erro estrutural antes do Gate de emissão/verificação.
3. Diagnóstico tardio e pouco preciso para falhas de marshaling.
## Target
`IRVMProgram` com coerência obrigatória, sem exceção silenciosa para formas proibidas no pipeline canônico.
## Dependencies
Prerequisito direto:
1. `PR-05.0.3` (payload de IDs tipados no contrato executável).
## Scope
1. Regras de coerência no construtor e no `coherentEmissionPlan()`.
2. Eliminação de placeholder de syscall desconhecida em caminho de derivação canônico.
3. Taxonomia de erro para incoerência estrutural.
## Non-Goals
1. Não muda verificador runtime.
2. Não muda decisão de proibir `RAW_SYSCALL` em pre-load.
## Method
### O que deve ser feito explicitamente
1. Remover condição que pula validação de coerência quando detecta `RAW_SYSCALL`.
2. Tornar inválido no caminho canônico qualquer plano com operação proibida para pre-load.
3. Remover geração de `HOSTCALL` com `SyscallDecl("__unknown__",...)` em derivação automática.
4. Falhar cedo com erro determinístico e mensagem orientada a ação.
## Acceptance Criteria
1. `IRVMProgram` nunca retorna plano incoerente no fluxo canônico.
2. Não existe mais derivação com placeholders desconhecidos para hostcall.
3. Erros de coerência aparecem antes da emissão binária.
4. Coerência valida vínculos de IDs de call/intrinsic com tipo correto de domínio.
## Tests
1. Testes negativos para `RAW_SYSCALL` no plano e para hostcall sem metadado válido.
2. Testes de regressão para caminhos válidos existentes.
3. Testes de estabilidade de códigos de erro.
## Affected Documents
1. `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/19. Verification and Safety Checks Specification.md`
## Open Questions
Sem bloqueios arquiteturais.

70
docs/compiler/pbs/pull-requests/PR-05.5-irvm-validator-real-stack-effects-hostcall-intrinsic.md
View File

@ -1,70 +0,0 @@
# PR-05.5 - IRVM Validator Real Stack Effects for HOSTCALL and INTRINSIC
## Briefing
O validador IRVM hoje modela `HOSTCALL` e `INTRINSIC` com efeito de stack genérico insuficiente para rigor JVM-grade.
Esta PR passa a validar efeitos reais de stack por assinatura (`arg_slots`/`ret_slots`) nessas operações.
## Motivation
### Dor atual que esta PR resolve
1. Possíveis underflow/overflow não detectados em chamadas host/intrínseco.
2. Retorno efetivo divergente sem falha no precheck.
3. Confiança excessiva na emissão sem validação semântica de pilha completa.
## Target
`IRVMValidator` e metadados de operação com informação suficiente para calcular efeito real de stack.
## Dependencies
Prerequisitos diretos:
1. `PR-05.0.3` (IDs tipados de callable/intrinseco).
2. `PR-05.0.6` (identidade canônica de host binding).
## Scope
1. Modelo de metadados para chamadas host e intrínseco no estágio IRVM.
2. Regras de validação de stack baseadas em assinatura.
3. Diagnósticos determinísticos de mismatch.
## Non-Goals
1. Não define política de otimização.
2. Não altera opcode wire format.
## Method
### O que deve ser feito explicitamente
1. Introduzir acesso a `arg_slots`/`ret_slots` efetivos durante validação de `HOSTCALL`.
2. Introduzir contrato equivalente para `INTRINSIC` (a partir de tabela canônica no pipeline).
3. Aplicar stack effect real no data-flow do validador.
4. Rejeitar mismatch de altura de retorno em joins e `RET` final.
5. Preservar mensagens de erro estáveis na taxonomia `MARSHAL_VERIFY_PRECHECK_*`.
6. Consumir metadados canônicos por ID, sem lookup textual ad-hoc.
## Acceptance Criteria
1. `HOSTCALL` e `INTRINSIC` participam do cálculo real de pilha no validador.
2. Casos de mismatch de assinatura falham no precheck com erro determinístico.
3. Casos válidos seguem aprovando sem regressão.
4. O caminho de validação não depende de composição textual de chave de binding.
## Tests
1. Testes positivos com combinações de arg/ret slots para host e intrínsecos.
2. Testes negativos para underflow, overflow e retorno incompatível.
3. Testes de join mismatch com chamadas em blocos ramificados.
## Affected Documents
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
2. `docs/general/specs/19. Verification and Safety Checks Specification.md`
## Open Questions
Sem bloqueios arquiteturais.

75
docs/compiler/pbs/pull-requests/PR-05.6-optimize-irvm-real-deterministic-passes.md
View File

@ -1,75 +0,0 @@
# PR-05.6 - OptimizeIRVM Real Deterministic Passes
## Briefing
A etapa `OptimizeIRVM` está corretamente posicionada no pipeline, mas ainda opera como `NoOp`.
Esta PR introduz o primeiro conjunto de passes reais, seguros e determinísticos, mantendo equivalência semântica e compatibilidade de perfil.
## Motivation
### Dor atual que esta PR resolve
1. Etapa de otimização existe formalmente, mas não entrega valor técnico.
2. Difícil sustentar evolução de performance e limpeza de IRVM sem regressão.
3. Falta de contrato de execução de pass manager com evidência forte.
## Target
`OptimizeIRVMService` com pass manager produtivo e baseline de passes v1.
## Dependencies
Prerequisitos diretos:
1. `PR-05.0.3` (IDs tipados no contrato executável).
2. `PR-05.0.4` (shape/signature internadas).
## Scope
1. Pass manager determinístico com ordem estável.
2. Passes iniciais semânticamente conservadores.
3. Validação antes/depois de cada pass.
## Non-Goals
1. Não inclui otimizações agressivas interprocedurais.
2. Não inclui JIT/runtime optimization.
## Method
### O que deve ser feito explicitamente
1. Implementar baseline de passes v1:
- eliminação de bloco inalcançável,
- normalização de labels redundantes,
- simplificação de salto para próximo PC.
2. Manter invariantes obrigatórias:
- sem mudança de `vm_profile`,
- sem introdução de opcode fora do perfil,
- sem alteração de contratos de slots/retorno observáveis.
3. Validar programa antes e após cada pass.
4. Registrar nome/ordem de pass para rastreabilidade de regressão.
## Acceptance Criteria
1. `OptimizeIRVM` deixa de ser apenas `NoOp` no caminho padrão.
2. Mesma entrada produz mesma saída otimizada (determinismo).
3. Testes de equivalência semântica passam para fixtures representativas.
4. Nenhum pass viola perfil de VM ou contrato de emissão.
5. Nenhum pass degrada identidade tipada para chave textual ad-hoc.
## Tests
1. Testes unitários por pass com entradas mínimas e edge cases.
2. Testes de pipeline comparando saída otimizada vs não otimizada para equivalência.
3. Testes negativos para pass que tenta alterar perfil/semântica.
## Affected Documents
1. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md`
2. `docs/general/specs/19. Verification and Safety Checks Specification.md`
## Open Questions
Sem bloqueios arquiteturais para baseline v1.

66
docs/compiler/pbs/pull-requests/PR-05.7-gate-i-runtime-backed-mandatory-in-ci.md
View File

@ -1,66 +0,0 @@
# PR-05.7 - Gate I Runtime-Backed Mandatory in CI
## Briefing
O harness de compatibilidade runtime-backed pode cair para `local-fallback` quando comando não está configurado.
Esta PR separa modo dev e modo CI, tornando obrigatório runtime-backed real em CI para suportar claim forte de conformidade.
## Motivation
### Dor atual que esta PR resolve
1. Falsa sensação de conformidade quando ambiente cai para fallback local.
2. Regressões de integração com runtime real podem passar despercebidas.
3. Evidência de Gate I fica fraca para suporte externo.
## Target
Pipeline de testes com política explícita: em CI, fallback local não é aceito para Gate I.
## Dependencies
Dependencia recomendada:
1. `PR-05.8` para registrar o status do Gate I na matriz de conformidade.
## Scope
1. Política de execução do adapter runtime-backed.
2. Configuração de CI para `PROMETEU_RUNTIME_CHECK_CMD`.
3. Diagnóstico claro quando runtime-backed obrigatório não está ativo.
## Non-Goals
1. Não altera runtime.
2. Não remove adapter local para uso de desenvolvimento.
## Method
### O que deve ser feito explicitamente
1. Introduzir flag de modo estrito para Gate I em CI.
2. Em modo estrito, falhar teste se adapter entrar em `local-fallback`.
3. Publicar comando e contrato mínimo do check runtime em pipeline.
4. Preservar modo permissivo local para desenvolvimento fora de CI.
## Acceptance Criteria
1. CI falha se Gate I não executar em modo runtime-backed real.
2. Execução local mantém fallback disponível quando não for modo estrito.
3. Resultado de Gate I reporta claramente `adapterMode` e motivo.
## Tests
1. Teste de modo estrito com comando ausente deve falhar.
2. Teste de modo estrito com comando válido deve passar.
3. Regressão local em modo não estrito permanece funcional.
## Affected Documents
1. `docs/general/specs/19. Verification and Safety Checks Specification.md`
2. `docs/general/specs/13. Conformance Test Specification.md`
## Open Questions
Sem bloqueios arquiteturais.

73
docs/compiler/pbs/pull-requests/PR-05.8-backend-spec-to-test-conformance-matrix.md
View File

@ -1,73 +0,0 @@
# PR-05.8 - Backend Spec-to-Test Conformance Matrix
## Briefing
Falta uma matriz única ligando cada MUST normativo de backend aos testes que provam conformidade.
Esta PR cria a matriz de rastreabilidade para `18.1`, `18.2`, `18.3`, specs `19`, `20`, `21` e Gate I/S-U.
## Motivation
### Dor atual que esta PR resolve
1. Dificuldade de provar cobertura de conformidade por requisito.
2. Buracos de teste ficam escondidos por ausência de rastreabilidade.
3. Evolução de arquitetura sem visão clara de impacto em evidência.
## Target
Artefato de conformidade auditável que mapeia requisito -> teste positivo -> teste negativo -> status.
## Dependencies
Prerequisito de conteúdo:
1. Incorporar explicitamente a trilha `PR-05.0.X` como fundação de identidade/IDs.
## Scope
1. Matriz normativa de backend FE/BE.
2. Classificação de status por requisito (`pass`, `missing`, `partial`, `deferred`).
3. Regra de atualização obrigatória da matriz em toda PR backend relevante.
4. Seção dedicada para rastrear requisitos de identidade tipada e Dense Tables.
## Non-Goals
1. Não cria nova semântica de linguagem.
2. Não substitui specs normativas.
## Method
### O que deve ser feito explicitamente
1. Criar documento de matriz em `docs/general/specs` ou `docs/pbs/specs` com tabela por requisito normativo.
2. Para cada MUST, vincular explicitamente:
- teste(s) positivo(s),
- teste(s) negativo(s),
- módulo/classe de teste,
- status atual.
3. Adicionar quality gate de revisão: PR backend sem atualização da matriz deve ser rejeitada quando impactar conformidade.
4. Definir procedimento de manutenção para não deixar entradas órfãs.
## Acceptance Criteria
1. Todo MUST de `19`, `20`, `21` e addendum executável de `13` aparece na matriz.
2. Cada item tem referência concreta a teste ou marcação explícita de ausência.
3. Revisão de PR consegue identificar rapidamente gaps de conformidade.
4. A matriz explicita dependência e cobertura dos itens `PR-05.0.1` a `PR-05.0.6`.
## Tests
1. Não exige testes executáveis novos por si só.
2. Exige checagem de integridade da matriz em revisão CI/lint documental.
## Affected Documents
1. `docs/general/specs/19. Verification and Safety Checks Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md`
4. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
## Open Questions
Sem bloqueios arquiteturais.

72
docs/compiler/pbs/pull-requests/PR-06.1-source-attribution-and-diagnostics-evidence-hardening.md
View File

@ -1,72 +0,0 @@
# PR-06.1 - Source Attribution and Diagnostics Evidence Hardening
## Briefing
Ha cobertura parcial para preservacao de `source attribution` em rejeicoes backend e no handoff executavel.
Esta PR fecha os gaps de evidencia para requisitos de atribuicao de origem e estabilidade de diagnostico.
## Motivation
### Dor atual que esta PR resolve
1. Falta de prova forte de que erros backend preservam `file/start/end` quando acionaveis pelo usuario.
2. Parte da matriz marca `partial` para requisitos de atribuicao (`G20-11.3`, `PBS13-12.1.4`).
3. Revisao de regressao de spans depende de inspeccao manual.
## Target
Cobertura automatizada para atribuicao de origem em diagnosticos de falha backend e no contrato executavel.
## Dependencies
Prerequisitos recomendados:
1. `PR-05.5` (stack effects reais host/intrinsic).
2. `PR-05.8` (matriz de conformidade existente).
## Scope
1. Testes de atribuicao de origem para falhas deterministicas no `LowerToIRVM`.
2. Testes de atribuicao para falhas de pipeline (`BACKEND_LOWER_IRVM` e `BACKEND_EMIT_BYTECODE`) quando aplicavel.
3. Atualizacao da matriz para migrar `G20-11.3` e `PBS13-12.1.4` de `partial` para `pass` se houver cobertura completa.
## Non-Goals
1. Nao altera semantica de linguagem.
2. Nao introduz novas classes de diagnostico.
## Method
### O que deve ser feito explicitamente
1. Criar fixtures negativas onde erro e claramente source-actionable e verificar:
- `code` estavel,
- `phase` estavel,
- `file/start/end` presentes e coerentes.
2. Garantir que spans de instrucoes/callsites sejam propagadas ativamente para as mensagens de falha.
3. Atualizar a matriz com referencias exatas de teste.
## Acceptance Criteria
1. Falhas source-actionable do backend expõem atribuicao de origem valida.
2. Requisitos `G20-11.3` e `PBS13-12.1.4` saem de `partial` se cobertura completa for atingida.
3. Nenhuma regressao em testes existentes de taxonomia de erro.
## Tests
1. Novos testes unitarios/integracao para spans em diagnosticos de falha.
2. Reexecucao obrigatoria:
- `:prometeu-compiler:prometeu-build-pipeline:test`
- `:prometeu-compiler:prometeu-frontend-api:test`
## Affected Documents
1. `docs/general/specs/19. Verification and Safety Checks Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
4. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
## Open Questions
Sem bloqueios arquiteturais.

75
docs/compiler/pbs/pull-requests/PR-06.2-optimize-irvm-semantic-equivalence-harness.md
View File

@ -1,75 +0,0 @@
# PR-06.2 - OptimizeIRVM Semantic Equivalence Harness
## Briefing
A etapa `OptimizeIRVM` ja possui passes reais, mas a prova de equivalencia semantica ainda esta parcial.
Esta PR cria harness sistematico para validar comportamento observavel com `opt on/off`.
## Motivation
### Dor atual que esta PR resolve
1. Evidencia de equivalencia semantica ainda e fixture-level limitada.
2. Itens `G21-6.2`, `G21-7.1` e `G21-9.1` permanecem `partial`.
3. Risco de pass regressivo sem deteccao ampla.
## Target
Harness de equivalencia deterministica com corpus de CFG e chamadas host/intrinsic.
## Dependencies
Prerequisitos diretos:
1. `PR-05.6` (pass manager real).
2. `PR-05.7` (Gate I estrito em CI).
## Scope
1. Framework de comparacao `optimized` vs `non-optimized`.
2. Fixtures representativas:
- sequencias lineares,
- condicional com joins,
- loops simples,
- hostcall/intrinsic.
3. Assercoes de invariantes:
- semantica observavel equivalente,
- determinismo de output,
- contratos de slots preservados.
## Non-Goals
1. Nao inclui prova formal completa.
2. Nao adiciona otimizacoes agressivas interprocedurais.
## Method
### O que deve ser feito explicitamente
1. Expor no teste caminho `optimize on/off` para o mesmo `IRVMProgram`.
2. Comparar resultado observavel em nivel de artefato e checagens Gate I/S-U.
3. Cobrir casos negativos em que pass invalido deve falhar por perfil/contrato.
4. Atualizar a matriz para converter requisitos `partial` quando cobertos.
## Acceptance Criteria
1. Existe harness reutilizavel de equivalencia `opt on/off`.
2. Cobertura de CFG e chamadas host/intrinsic com assercao de equivalencia.
3. `G21-6.2`, `G21-7.1`, `G21-9.1` evoluem para `pass` se cobertura completa.
## Tests
1. Novos testes no pacote `backend/irvm` e/ou `integration`.
2. Reexecucao obrigatoria:
- `:prometeu-compiler:prometeu-build-pipeline:test`
## Affected Documents
1. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md`
2. `docs/general/specs/19. Verification and Safety Checks Specification.md`
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
Sem bloqueios arquiteturais.

69
docs/compiler/pbs/pull-requests/PR-06.3-irvm-ext-contract-and-elimination-fixtures.md
View File

@ -1,69 +0,0 @@
# PR-06.3 - IRVM_EXT Contract and Elimination Fixtures
## Briefing
O contrato de `IRVM_EXT` esta parcialmente coberto apenas pelo `INTERNAL_EXT` atual.
Esta PR amplia cobertura para garantir metadados estruturais e eliminacao antes da emissao.
## Motivation
### Dor atual que esta PR resolve
1. Requisito `G20-6.2` permanece `partial`.
2. Falta evidencia para mais de um formato de extensao interna.
3. Dificuldade de evoluir extensoes com seguranca sem regressao de precheck.
## Target
Suite de fixtures para contrato de `IRVM_EXT` e precondicao de eliminacao no caminho de emissao.
## Dependencies
Prerequisitos diretos:
1. `PR-05.6` (otimizador ativo).
2. `PR-05.4` (coerencia de programa sem bypass).
## Scope
1. Fixtures com multiplas op variantes internas (ou metadados distintos equivalentes).
2. Validacao explicita de metadados estruturais (`pops/pushes/branch/terminator`).
3. Prova de rejeicao quando opcode interno residual chega ao emit.
## Non-Goals
1. Nao define novas extensoes de runtime.
2. Nao altera ISA core publicado.
## Method
### O que deve ser feito explicitamente
1. Adicionar cenarios de teste para `IRVM_EXT` alem do caso trivial existente.
2. Verificar que `OptimizeIRVM` elimina extensoes internas em caminho canônico.
3. Verificar que `EmitBytecode` falha deterministicamente quando extensao residual permanece.
4. Atualizar a matriz para `G20-6.2` conforme cobertura final.
## Acceptance Criteria
1. Contrato estrutural de `IRVM_EXT` fica provado por testes dedicados.
2. Caminho de eliminacao pre-emissao e coberto com positivo/negativo.
3. `G20-6.2` evolui para `pass` se cobertura completa.
## Tests
1. `IRVMValidatorTest` e `OptimizeIRVMServiceTest` com novos casos.
2. `EmitBytecodePipelineStageTest` para residual interno.
3. Reexecucao:
- `:prometeu-compiler:prometeu-build-pipeline:test`
## Affected Documents
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
2. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md`
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
Sem bloqueios arquiteturais.

68
docs/compiler/pbs/pull-requests/PR-06.4-gate-i-runtime-line-repeatability-ci.md
View File

@ -1,68 +0,0 @@
# PR-06.4 - Gate I Runtime-Line Repeatability in CI
## Briefing
Gate I ja suporta modo estrito runtime-backed, mas a prova de repetibilidade por runtime line ainda esta parcial.
Esta PR endurece CI para validar repetibilidade em mais de uma linha de runtime suportada.
## Motivation
### Dor atual que esta PR resolve
1. `G19-5.2.8` permanece `partial`.
2. Falta evidencia de comportamento repetivel entre linhas de runtime.
3. Claim de integracao forte fica fragil sem execucao multi-line.
## Target
Pipeline CI com Gate I estrito e validacao de repetibilidade em matrix de runtime line.
## Dependencies
Prerequisitos diretos:
1. `PR-05.7` (modo estrito runtime-backed).
2. disponibilidade de pelo menos duas linhas de runtime executaveis no CI.
## Scope
1. Configuracao CI para `PROMETEU_GATE_I_STRICT=true`.
2. Parametrizacao de `PROMETEU_RUNTIME_CHECK_CMD` por runtime line.
3. Registro de evidencia de execucao por linha (log/sumario de job).
## Non-Goals
1. Nao altera implementacao do runtime.
2. Nao define politica de suporte de longo prazo entre linhas.
## Method
### O que deve ser feito explicitamente
1. Adicionar jobs ou matrix de CI para linhas de runtime alvo.
2. Garantir falha obrigatoria quando runtime-backed nao estiver ativo.
3. Adicionar teste/documentacao que explicite `adapterMode`, `runtimeLine` e motivo.
4. Atualizar matriz de conformidade para `G19-5.2.8`.
## Acceptance Criteria
1. CI falha se Gate I cair em fallback em modo estrito.
2. CI executa Gate I em >= 2 linhas de runtime declaradas.
3. `G19-5.2.8` evolui para `pass` se repetibilidade multi-line for comprovada.
## Tests
1. Testes de adapter strict ja existentes continuam verdes.
2. Execucao obrigatoria de Gate I em matrix CI com runtime-backed real.
## Affected Documents
1. `docs/general/specs/13. Conformance Test Specification.md`
2. `docs/general/specs/19. Verification and Safety Checks Specification.md`
3. `docs/general/specs/17. Compatibility and Evolution Policy.md`
4. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Definir oficialmente quais runtime lines entram na matrix minima obrigatoria.

68
docs/compiler/pbs/pull-requests/PR-06.5-conformance-matrix-hard-gate-policy.md
View File

@ -1,68 +0,0 @@
# PR-06.5 - Conformance Matrix Hard-Gate Policy
## Briefing
A matriz de conformidade existe e possui lint basico, mas ainda nao bloqueia de forma forte PRs que degradam evidencia.
Esta PR transforma a matriz em hard gate processual para mudancas FE/BE com impacto de conformidade.
## Motivation
### Dor atual que esta PR resolve
1. Possibilidade de drift entre comportamento real e status da matriz.
2. Risco de PR alterar pipeline sem atualizar rastreabilidade normativa.
3. Revisao depende demais de disciplina manual.
## Target
Politica automatizada que rejeita PR backend sem atualizacao de matriz quando ha impacto de conformidade.
## Dependencies
Prerequisitos diretos:
1. `PR-05.8` (matriz + lint documental inicial).
## Scope
1. Regra de CI/revisao para detectar mudanca relevante em FE/BE backend.
2. Exigencia de atualizacao da matriz quando requisito normativo e impactado.
3. Politica clara para `partial/missing/deferred` e justificativa obrigatoria.
## Non-Goals
1. Nao substituir julgamento tecnico de revisao.
2. Nao bloquear PR puramente documental sem impacto tecnico.
## Method
### O que deve ser feito explicitamente
1. Definir regra objetiva de impacto (arquivos/pacotes gatilho).
2. Implementar verificacao automatica em CI para forcar update da matriz quando gatilho ocorrer.
3. Exigir no PR referencia explicita aos Requirement IDs alterados.
4. Atualizar docs de contribuicao/qualidade com o novo gate.
## Acceptance Criteria
1. PR com mudanca backend relevante e sem update de matriz e rejeitada.
2. PR que altera status de requisito exige justificativa e testes referenciados.
3. Processo de revisao fica reproduzivel e auditavel.
## Tests
1. Testes de lint/matriz existentes continuam passando.
2. Teste de politica (script/check) com cenarios:
- mudanca relevante sem matriz -> fail,
- mudanca relevante com matriz -> pass.
## Affected Documents
1. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
2. `docs/general/specs/13. Conformance Test Specification.md`
3. `docs/pbs/specs/2. Governance and Versioning.md`
## Open Questions
1. Definir lista final de caminhos de codigo que acionam hard gate de matriz.

76
docs/compiler/pbs/pull-requests/PR-06.6-spawn-yield-v1-or-claim-rescope.md
View File

@ -1,76 +0,0 @@
# PR-06.6 - SPAWN/YIELD v1 or Claim Rescope
## Briefing
Os requisitos `G20-9.4.2` e `G20-9.4.3` estao `deferred` porque `SPAWN/YIELD` nao fazem parte do surface executavel v1 atual.
Esta PR fecha a pendencia por uma de duas trilhas exclusivas:
1. implementar `SPAWN/YIELD` em v1 com testes; ou
2. ajustar claim/perfil/spec para remover obrigacao deste escopo no v1 claimado.
## Motivation
### Dor atual que esta PR resolve
1. Nota JVM-grade fica penalizada por requisitos deferidos.
2. Claim de conformidade pode ficar ambiguo para auditoria externa.
3. Planejamento tecnico fica travado entre implementacao e re-scope.
## Target
Decisao implementada e test-backed para encerrar `deferred` com status claro.
## Dependencies
Prerequisitos variam por trilha:
1. Trilha A (implementar): depende de extensao do modelo `IRBackend/IRVM` para opcodes e verificacao.
2. Trilha B (re-scope): depende de alinhamento normativo com specs/decision.
## Scope
1. Trilha A:
- adicionar suporte `SPAWN/YIELD`,
- validar aridade e stack constraints,
- cobrir com testes positivos/negativos.
2. Trilha B:
- ajustar documentos para deixar explicito que nao e parte do profile v1 claimado,
- atualizar matriz e policy de claim.
## Non-Goals
1. Nao introduzir modelo completo de concorrencia/corrotina alem do minimo normativo.
2. Nao conflitar com autoridade de runtime/ISA.
## Method
### O que deve ser feito explicitamente
1. Escolher uma trilha oficial (A ou B) por decisao registrada.
2. Executar implementacao ou re-scope end-to-end (codigo + specs + matriz).
3. Garantir que `G20-9.4.2` e `G20-9.4.3` saiam de `deferred` para `pass` (A) ou status normativo explicitamente nao-aplicavel no claim v1 (B).
## Acceptance Criteria
1. Nao existe mais ambiguidade sobre `SPAWN/YIELD` no claim atual.
2. Matriz e specs refletem exatamente o comportamento implementado e claimado.
3. Gate de conformidade nao deixa regressao silenciosa nesses itens.
## Tests
1. Trilha A:
- testes de lowering/validator para `SPAWN` arg count e `YIELD` stack constraint.
2. Trilha B:
- testes de integridade documental/policy com checks de claim.
## Affected Documents
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
2. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
3. `docs/general/specs/17. Compatibility and Evolution Policy.md`
4. `docs/pbs/decisions/*` (decision de escopo, quando aplicavel)
## Open Questions
1. Qual trilha oficial deve ser adotada: implementacao v1 (A) ou re-scope de claim (B)?

73
docs/compiler/pbs/pull-requests/PR-07.1-optimize-irvm-span-source-hook-preservation.md
View File

@ -1,73 +0,0 @@
# PR-07.1 - OptimizeIRVM Span and Source-Hook Preservation
## Briefing
A matriz de conformidade ainda marca `G21-7.5` como `partial`.
Hoje existe evidencia de spans no lowering, mas falta regressao dedicada provando que passes de `OptimizeIRVM` preservam hooks de atribuicao de origem (spans/source hooks) apos reescritas de instrucoes e remapeamento de saltos.
## Motivation
### Dor atual que esta PR resolve
1. Risco de regressao silenciosa em spans durante otimização.
2. Evidencia insuficiente para fechar `G21-7.5`.
3. Diagnosticos pos-otimizacao podem perder rastreabilidade sem prova dedicada.
## Target
Fechar `G21-7.5` com suite de regressao explicita para preservacao de source hooks/spans no caminho `LowerToIRVM -> OptimizeIRVM -> EmitBytecode`.
## Dependencies
Prerequisitos diretos:
1. `PR-06.2` (harness de equivalencia de otimizacao).
2. `PR-06.3` (passes reais de reescrita/remocao no optimizer).
## Scope
1. Testes dedicados para verificacao de span retention por pass:
- `UnreachableInstructionEliminationPass`,
- `NormalizeRedundantJumpTargetsPass`,
- `SimplifyJumpToNextPcPass`.
2. Assercoes de preservacao de `BytecodeEmitter.Operation.span` para operacoes sobreviventes.
3. Assercoes de preservacao de spans em operacoes de salto apos remapeamento de target.
4. Atualizacao da matriz para converter `G21-7.5` de `partial` para `pass`.
## Non-Goals
1. Nao introduz novo formato de source map.
2. Nao altera contrato de diagnostico fora do backend pipeline.
## Method
### O que deve ser feito explicitamente
1. Criar fixture IRVM com spans distintos por instrucao/op.
2. Executar optimize com passes reais e comparar mapeamento de spans esperado no output.
3. Incluir caso com salto reescrito para validar span do salto apos remap.
4. Incluir caso com eliminacao de instrucoes para validar que operacoes restantes mantem spans originais.
5. Atualizar matriz (`docs/general/specs/22...`) com referencias aos novos testes.
## Acceptance Criteria
1. Existe suite de teste dedicada para preservacao de spans/source hooks no optimizer.
2. Reescritas de salto preservam spans da operacao original.
3. Eliminacao de instrucoes nao corrompe spans das operacoes remanescentes.
4. `G21-7.5` evolui para `pass`.
## Tests
1. Novos testes em `backend/irvm` (ex.: `OptimizeIRVMSourceAttributionTest` ou equivalente).
2. Reexecucao obrigatoria:
- `:prometeu-compiler:prometeu-build-pipeline:test`
## Affected Documents
1. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md`
2. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
Sem bloqueios arquiteturais.

74
docs/compiler/pbs/pull-requests/PR-07.2-pbs-callsite-category-no-textual-heuristics-regression.md
View File

@ -1,74 +0,0 @@
# PR-07.2 - PBS Callsite Category Without Textual Heuristics (Regression Fixtures)
## Briefing
A matriz de conformidade ainda marca `PBS13-12.2.2` como `partial`.
Ja existe enforce de metadados no contrato executavel, mas falta fixture regressiva dedicada para provar que o frontend/backend nao classifica callsite por heuristica textual quando identidades entram em colisao.
## Motivation
### Dor atual que esta PR resolve
1. Ambiguidade residual na evidencia de `CALL_FUNC/CALL_HOST/CALL_INTRINSIC`.
2. Risco de regressao para classificacao por nome textual em casos limítrofes.
3. `PBS13-12.2.2` permanece `partial` por falta de caso dedicado de identidade ambigua.
## Target
Fechar `PBS13-12.2.2` com fixtures explicitas de identidade e ambiguidade, garantindo que categoria de callsite e derivada de identidade semantica/admitida, nao de heuristica textual.
## Dependencies
Prerequisitos diretos:
1. `PR-05.2` (classificacao de callsite por identidade semantica).
2. `PR-05.0.1` e `PR-05.0.6` (name/host identity foundation).
## Scope
1. Fixture positiva:
- nome textual com "cara de host", mas identidade resolvida como callable local -> deve lower para `CALL_FUNC`.
2. Fixture positiva:
- nome textual sobreposto entre dominios, com identidade univoca admitida para host ou intrinsic -> deve lower categoria correta.
3. Fixture negativa dedicada:
- colisao real entre categorias (callable/host/intrinsic) para o mesmo callsite -> rejeicao deterministica por ambiguidade.
4. Atualizacao de matriz para converter `PBS13-12.2.2` de `partial` para `pass`.
## Non-Goals
1. Nao altera gramatica PBS.
2. Nao redefine regras de admission de host/intrinsics fora do escopo desta prova.
## Method
### O que deve ser feito explicitamente
1. Adicionar testes em `PbsFrontendCompilerTest` (ou suite semantica correlata) para os tres cenarios acima.
2. Assertar `InstructionKind` resultante (`CALL_FUNC`, `CALL_HOST`, `CALL_INTRINSIC`) em casos positivos.
3. Assertar codigo diagnostico deterministico em caso ambiguo.
4. Garantir que nao ha branch de fallback por string pattern no caminho de lowering executavel.
5. Atualizar matriz de conformidade com referencias dos novos testes.
## Acceptance Criteria
1. Existe fixture dedicada cobrindo ambiguidade de categoria por identidade.
2. Casos positivos provam classificacao correta mesmo quando nome textual engana.
3. Caso ambiguo falha deterministicamente com diagnostico estavel.
4. `PBS13-12.2.2` evolui para `pass`.
## Tests
1. Novos testes no frontend PBS:
- `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
2. Reexecucao obrigatoria de integracao backend:
- `:prometeu-compiler:prometeu-build-pipeline:test`
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
Sem bloqueios arquiteturais.

77
docs/compiler/pbs/pull-requests/PR-07.3-irvm-entrypoint-export-emission-for-runtime-loader.md
View File

@ -1,77 +0,0 @@
# PR-07.3 - IRVM Entrypoint Export Emission for Runtime Loader Compatibility
## Briefing
Hoje um cartridge pode compilar com `entrypoint: "frame"` no `manifest.json` e `pub fn frame()` no `mod.barrel`, mas ainda falhar em runtime com `EntrypointNotFound`.
A causa observada e que o `program.pbx` pode ser emitido sem secao `exports` (section kind `4`), enquanto o loader resolve entrypoint nominal usando `program.exports`.
## Motivation
### Dor atual que esta PR resolve
1. Build aparentemente valido, mas falha de bootstrap em runtime.
2. Divergencia entre contrato de manifesto (`entrypoint` nominal) e artefato PBX emitido.
3. Falta de evidencia automatizada para evitar regressao de exports no caminho `IRBackend -> IRVM -> Bytecode`.
## Target
Corrigir o pipeline backend para sempre emitir export nominal do entrypoint no PBX de preload, garantindo compatibilidade com o loader quando o `manifest.json` declara entrypoint por nome.
## Dependencies
Prerequisitos diretos:
1. `PR-05.3` (politica deterministica de entrypoint no indice `0`).
2. `PR-05.4` (coerencia unica entre IRVM e EmissionPlan).
## Scope
1. `LowerToIRVMService` deve preencher `EmissionPlan.exports` com o simbolo do entrypoint apontando para `func_idx = 0`.
2. Adicionar regressao dedicada para garantir que `coherentEmissionPlan()` preserva export do entrypoint.
3. Validar serializacao PBX com secao `exports` presente quando houver entrypoint nominal.
4. Cobrir cenario de integracao onde `manifest.entrypoint = "frame"` inicializa VM sem `EntrypointNotFound`.
## Non-Goals
1. Nao exportar toda a superficie de funcoes executaveis neste passo.
2. Nao alterar formato binario PBX alem da presenca correta da secao `exports`.
3. Nao mudar semantica de resolucao por indice numerico de entrypoint.
## Method
### O que deve ser feito explicitamente
1. No `LowerToIRVMService`, construir `BytecodeEmitter.EmissionPlan` com `exports` contendo, no minimo, `Export(entryPointCallableName, 0)`.
2. Garantir determinismo do export do entrypoint a partir da mesma politica que fixa `func_id = 0`.
3. Adicionar teste unitario em `LowerToIRVMServiceTest` para verificar export nominal do entrypoint no plano coerente.
4. Adicionar teste de emissao/link para verificar secao `exports` no modulo serializado.
5. Adicionar teste de integracao runtime-backed para falhar se regressar para `EntrypointNotFound` em cartridge com entrypoint nominal valido.
## Acceptance Criteria
1. Build de projeto PBS com entrypoint `frame` gera PBX com secao `exports`.
2. O simbolo `frame` aponta para `func_idx = 0` no artefato emitido.
3. Execucao de cartridge com `manifest.entrypoint = "frame"` nao falha por `EntrypointNotFound` quando o programa contem o entrypoint admitido.
4. Rebuilds equivalentes produzem mapping de export deterministico.
## Tests
1. Novos testes de backend:
- `:prometeu-compiler:prometeu-build-pipeline:test`
2. Reexecucao de compatibilidade runtime-backed:
- `:prometeu-compiler:prometeu-build-pipeline:test --tests *Runtime*`
3. Smoke local recomendado:
- `./runtime/prometeu build .`
- `./runtime/prometeu run cartridge`
## Affected Documents
1. `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md`
4. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Em evolucao futura, devemos exportar apenas o entrypoint ou tambem funcoes explicitamente marcadas para linking externo?

80
docs/compiler/pbs/pull-requests/PR-08.1-intrinsic-resolution-canonical-identity-keying.md
View File

@ -1,80 +0,0 @@
# PR-08.1 - Intrinsic Resolution by Canonical Identity (Owner+Name+Version)
## Briefing
Hoje a resolucao de intrinsic no frontend PBS ainda depende de chave por `sourceMethodName` simples.
Isso permite ambiguidade quando existem metodos com o mesmo nome em owners diferentes e enfraquece o contrato de canonical addressing.
## Motivation
### Dor atual que esta PR resolve
1. Ambiguidade potencial de resolucao de intrinsic por nome de metodo sem owner.
2. Dependencia implícita de heuristica textual ao inves de identidade canonica.
3. Risco de regressao quando ampliar superficie de builtins/intrinsics stateful.
## Target
Tornar a resolucao de `CALL_INTRINSIC` no frontend semanticamente canonica e nao ambigua, usando chave composta deterministica:
1. `owner canonical`,
2. `intrinsic name canonical`,
3. `canonical version`.
## Dependencies
Prerequisitos diretos:
1. `PR-05.2` (classificacao de callsite sem heuristica textual).
2. `PR-07.2` (regressao contra heuristica textual de categoria).
## Scope
1. Substituir o map por `sourceMethodName` no lowering executavel por indice por identidade canonica.
2. Ajustar `PbsReservedMetadataExtractor`/surface helper para expor owner canonical explicitamente na chave de resolucao.
3. Tornar erro de ambiguidade explicito quando mais de uma intrinsic disputar o mesmo callsite apos resolver receiver/owner.
4. Cobrir cenarios com nomes repetidos em owners diferentes.
## Non-Goals
1. Nao alterar ids finais de intrinsics no bytecode/runtime nesta PR.
2. Nao introduzir novo opcode.
3. Nao expandir parser/sintaxe de `IntrinsicCall`.
## Method
### O que deve ser feito explicitamente
1. Introduzir chave tipada para intrinsic de lowering (ex.: `IntrinsicResolutionKey(ownerCanonical, nameCanonical, version)`).
2. Popular lookup de intrinsics com essa chave em vez de `sourceMethodName`.
3. Resolver owner canonical a partir do receiver sem fallback textual opaco.
4. Rejeitar deterministicamente callsite intrinsic sem mapeamento canonico univoco.
5. Adicionar testes positivos/negativos para:
- owners distintos com mesmo metodo,
- override de versao,
- callsite sem receiver compativel.
## Acceptance Criteria
1. Nenhum callsite intrinsic e resolvido apenas por `sourceMethodName`.
2. Colisao de metodo entre owners diferentes nao gera escolha implicita.
3. Diagnosticos de ambiguidade/nao resolucao sao estaveis e testados.
4. Build equivalente gera mesma classificacao e mesmo `intrinsicPool`.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
2. `:prometeu-compiler:prometeu-build-pipeline:test --tests *LowerToIRVMServiceTest*`
3. Regressao dedicada para callsites `input.pad.*` vs outros owners com nome coincidente.
## Affected Documents
1. `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
2. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
3. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
4. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. O contrato final deve expor owner canonico como campo separado em `IntrinsicSurface`, ou apenas como nome canonico fully-qualified?

79
docs/compiler/pbs/pull-requests/PR-08.2-irbackend-moduleid-contract-and-modulepool.md
View File

@ -1,79 +0,0 @@
# PR-08.2 - IRBackend Module Identity via Dense Table (ModuleId + ModulePool)
## Briefing
`moduleKey` hoje e string no contrato executavel e vira identificador estrutural em multiplos pontos.
Isso funciona, mas ainda nao aproveita plenamente a infraestrutura de dense tables ja existente (`ModuleTable`/`ModuleId`) para identidade canonica de modulo no handoff FE->BE.
## Motivation
### Dor atual que esta PR resolve
1. Identidade de modulo dependente de serializacao textual (`project:path`) no contrato.
2. Maior risco de drift/normalizacao inconsistente entre fronteiras.
3. Custo de comparacao/armazenamento pior do que id tipado em larga escala.
## Target
Evoluir o contrato `IRBackend` para carregar identidade de modulo tipada por dense table:
1. `ModuleId` nas entidades executaveis,
2. `modulePool` canonico no payload,
3. `moduleKey` textual mantido apenas como campo auxiliar/debug no periodo de transicao.
## Dependencies
Prerequisitos diretos:
1. `PR-05.0.2` (infra de `ModuleId` e `ModuleTable`).
2. `PR-05.0.3` (migração previa de ids tipados no contrato executavel).
## Scope
1. Introduzir `modulePool` no `IRBackend` e remapeamento na agregacao multi-arquivo.
2. Trocar referencias estruturais de modulo para `ModuleId` em executable/callable surfaces.
3. Adaptar sorting/canonical ordering para usar `ModuleId` + leitura canonica da tabela.
4. Preservar backward compatibility local durante migracao (camada de adaptacao).
## Non-Goals
1. Nao redefinir formato PBX nesta PR.
2. Nao alterar semantica de modulo no parser/linker.
3. Nao remover imediatamente todos os campos textuais de debug.
## Method
### O que deve ser feito explicitamente
1. Adicionar `modulePool: ReadOnlyList<ModuleReference>` em `IRBackend`.
2. Adicionar `moduleId` em `IRBackendExecutableFunction` e `CallableSignatureRef` (ou equivalente de assinatura).
3. Atualizar `IRBackendAggregator` para reindexar modulos via `ModuleTable` (dense table).
4. Atualizar FE PBS para emitir `moduleId` usando tabela canonica de modulos.
5. Atualizar BE (`LowerToIRVMService`) para ordenar por identidade de modulo canonica sem dependencia de concat textual.
6. Incluir testes de determinismo para remapeamento multi-modulo com ids estaveis.
## Acceptance Criteria
1. `IRBackend` possui pool canonico de modulos com ids densos.
2. Caminho estrutural nao depende de `moduleKey` string para identidade.
3. Merges de `IRBackendFile` preservam reindexacao deterministica de modulo.
4. Funcoes equivalentes em builds equivalentes recebem ids de modulo identicos.
## Tests
1. `:prometeu-compiler:prometeu-frontend-api:test`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
3. `:prometeu-compiler:prometeu-build-pipeline:test`
4. Novos testes de agregacao multi-modulo com colisao textual potencial.
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
4. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Fase de transicao deve manter `moduleKey` como shadow field por quantas ondas?

80
docs/compiler/pbs/pull-requests/PR-08.3-qualified-entrypoint-identity-contract.md
View File

@ -1,80 +0,0 @@
# PR-08.3 - Qualified Entrypoint Identity (No Name-Only Resolution)
## Briefing
A selecao de entrypoint no backend ainda filtra apenas por `callableName`.
Em projetos multi-modulo isso amplia risco de ambiguidade e cria acoplamento desnecessario a nomes globais.
## Motivation
### Dor atual que esta PR resolve
1. Ambiguidade de entrypoint quando existem callables homonimos.
2. Diagnostico tardio por nome sem contexto de modulo.
3. Divergencia potencial entre contrato de frontend e selecao real no backend.
## Target
Evoluir o contrato para entrypoint qualificado e deterministico:
1. `entryPointCallableName` + `entryPointModuleId` (ou `entryPointCallableId`),
2. resolucao backend por identidade qualificada,
3. politicas de erro claras para mismatch/ausencia.
## Dependencies
Prerequisitos diretos:
1. `PR-08.2` (ModuleId no contrato IRBackend).
2. `PR-05.3` (politica deterministica de indexacao e `func_id=0`).
## Scope
1. Expandir `FrontendSpec` e handoff FE para declarar entrypoint qualificado.
2. Atualizar `IRBackend` para carregar declaracao qualificada de entrypoint.
3. Atualizar `LowerToIRVMService` para selecionar entrypoint por identidade qualificada.
4. Preservar fallback de compatibilidade durante migracao (com warning deterministico).
## Non-Goals
1. Nao alterar semantica de `func_id=0`.
2. Nao mudar contrato de manifesto de cartridge nesta PR.
3. Nao introduzir multiple entrypoints por linguagem.
## Method
### O que deve ser feito explicitamente
1. Introduzir estrutura de entrada qualificada (ex.: `EntrypointRef(moduleId, callableName)`).
2. Popular estrutura no frontend PBS a partir do modulo de `frame`.
3. Modificar `orderFunctions` para usar referencia qualificada.
4. Em caso de fallback por nome, emitir diagnostico de deprecacao controlado.
5. Adicionar testes para:
- homonimos em modulos distintos,
- entrypoint valido qualificado,
- entrypoint ausente com erro estavel.
## Acceptance Criteria
1. Selecao de entrypoint nao depende apenas de nome.
2. Homonimos em modulos distintos nao geram ambiguidade quando entrypoint qualificado existe.
3. `func_id=0` continua pertencendo ao entrypoint declarado.
4. Rebuilds equivalentes mantem func ordering deterministico.
## Tests
1. `:prometeu-compiler:prometeu-frontend-api:test`
2. `:prometeu-compiler:prometeu-build-pipeline:test --tests *LowerToIRVMServiceTest*`
3. Testes de integracao com dois modulos contendo `frame`.
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
4. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Melhor contrato final: `EntrypointRef(moduleId, callableName)` ou `CallableId` global direto?

72
docs/compiler/pbs/pull-requests/PR-08.4-call-func-callee-module-identity-correctness.md
View File

@ -1,72 +0,0 @@
# PR-08.4 - CALL_FUNC Callee Module Identity Correctness
## Briefing
No lowering executavel PBS, instrucoes `CALL_FUNC` podem carregar `calleeModuleKey` do contexto local, e nao necessariamente do callable alvo.
Isso compromete rastreabilidade, debug e futuras validacoes de linking por modulo.
## Motivation
### Dor atual que esta PR resolve
1. Metadado de callsite incorreto para chamadas inter-modulo.
2. Dificulta diagnostico e verificacao de integridade no backend.
3. Introduz risco de regressao quando modulo vira identidade tipada no contrato.
## Target
Garantir que todo `CALL_FUNC` preserva identidade real do alvo (`callee module`) de forma deterministica, sem usar contexto local como proxy.
## Dependencies
Prerequisitos diretos:
1. `PR-05.0.4` (assinatura/callable internados).
2. `PR-08.2` (quando `ModuleId` tipado estiver ativo, usar id do alvo).
## Scope
1. Corrigir montagem de callsite para puxar modulo do `calleeCallableId` resolvido.
2. Ajustar modelos auxiliares de resolucao de callable para incluir modulo do alvo.
3. Expandir testes de lowering com chamadas cross-module.
## Non-Goals
1. Nao alterar categoria de callsite.
2. Nao introduzir linking dinamico de funcoes.
3. Nao alterar bytecode emitido para opcodes de chamada.
## Method
### O que deve ser feito explicitamente
1. Enriquecer lookup de callable para retornar identidade completa (`callableId + module identity`).
2. Em `CALL_FUNC`, preencher `callee module` com identidade do alvo real.
3. Adicionar validacao de consistencia em contrato executavel para evitar modulo invalido em chamada.
4. Criar regressao com:
- modulo A chamando funcao em modulo B,
- assert do modulo do callee no IRBackend.
## Acceptance Criteria
1. Nenhuma instrução `CALL_FUNC` usa modulo local quando alvo e externo.
2. Testes cross-module passam com metadado correto de callee.
3. Diagnosticos mantem atribuicao correta em falhas de resolucao.
4. Contrato segue deterministico em rebuilds equivalentes.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsFrontendCompilerTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PBSFrontendPhaseServiceTest*`
3. `:prometeu-compiler:prometeu-build-pipeline:test --tests *LowerToIRVMPipelineStageTest*`
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Durante a transicao, manter `calleeCallableName` textual para debug ou derivar sempre da assinatura por id?

74
docs/compiler/pbs/pull-requests/PR-08.5-intrinsic-registry-single-source-sync-with-runtime.md
View File

@ -1,74 +0,0 @@
# PR-08.5 - Intrinsic Registry Single Source of Truth (Compiler <-> Runtime)
## Briefing
O compiler backend hoje possui `IRVMIntrinsicRegistry` hardcoded e o runtime possui registry propio em `builtins.rs`.
Mesmo estando alinhados agora, a manutencao manual em dois lugares cria risco alto de drift.
## Motivation
### Dor atual que esta PR resolve
1. Duplicacao de source-of-truth para ids finais de intrinsic.
2. Risco de regressao silenciosa quando runtime evoluir surface intrinsic.
3. Custo operacional para garantir paridade manual em cada mudanca.
## Target
Estabelecer uma fonte unica versionada para mapeamento canonico de intrinsics (`canonicalName@version -> finalId`) e consumir isso em compiler + runtime com teste de paridade automatizado.
## Dependencies
Prerequisitos diretos:
1. `PR-08.1` (resolucao canonica consistente no frontend).
2. `PR-05.7` (caminho de verificacao runtime-backed robusto).
## Scope
1. Definir artefato de registry canonico (ex.: JSON/TOML) sob controle de versionamento.
2. Gerar/consumir mapeamento no compiler (`IRVMIntrinsicRegistry`) a partir desse artefato.
3. Adicionar checagem de paridade em teste para impedir divergencia com runtime.
4. Documentar fluxo de evolucao de intrinsic id sem quebra de compatibilidade.
## Non-Goals
1. Nao reescrever todas as implementacoes de intrinsic do runtime nesta PR.
2. Nao alterar semantica de execucao de `INTRINSIC`.
3. Nao migrar para discovery dinamico em tempo de execucao.
## Method
### O que deve ser feito explicitamente
1. Introduzir arquivo canonico de registry em local acordado (`docs` ou `shared metadata`).
2. Criar utilitario de leitura/geracao para preencher `IRVMIntrinsicRegistry` no compiler.
3. Adicionar teste no compiler que compara mapeamento esperado com runtime (snapshot/paridade).
4. Adicionar regra de CI para falhar em desvio de paridade.
5. Atualizar docs de contribuicao para fluxo de adicao/upgrade de intrinsics.
## Acceptance Criteria
1. Existe uma unica fonte versionada de mapeamento de intrinsic ids finais.
2. Compiler nao depende de lista manual duplicada para esse mapeamento.
3. CI falha quando runtime e compiler divergem em identidade/ID de intrinsic.
4. Inclusao de nova intrinsic segue workflow documentado e testavel.
## Tests
1. `:prometeu-compiler:prometeu-build-pipeline:test --tests *Intrinsic*`
2. Teste de paridade compiler-runtime dedicado.
3. Smoke runtime-backed com intrinsic valido e id invalido.
## Affected Documents
1. `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
4. `../runtime/docs/runtime/specs/06-input-peripheral.md`
5. `../runtime/docs/runtime/specs/02-vm-instruction-set.md`
## Open Questions
1. Melhor local da fonte unica: repo `runtime`, repo `studio`, ou pacote compartilhado dedicado?

81
docs/compiler/pbs/pull-requests/PR-09.1-irbackend-modulekey-hard-removal-from-contract.md
View File

@ -1,81 +0,0 @@
# PR-09.1 - IRBackend Contract Cut: Remove `moduleKey` and `calleeModuleKey` (String)
## Briefing
O contrato executavel ainda carrega `moduleKey` textual como trilha de compatibilidade.
Isso mantem dupla identidade (`ModuleId` + string) em area critica de handoff.
## Motivation
### Dor atual que esta PR resolve
1. Identidade estrutural ainda pode cair em fallback textual.
2. Contrato permite dados redundantes e potencialmente divergentes.
3. A transicao para dense-only ainda nao esta fechada.
## Target
Encerrar a transicao no contrato FE->BE:
1. remover `moduleKey` de `IRBackendExecutableFunction`,
2. remover `calleeModuleKey` de instrucoes executaveis,
3. remover `moduleKey` de `CallableSignatureRef`,
4. eliminar parsing/fallback textual em `IRBackendAggregator`.
## Dependencies
Prerequisitos diretos:
1. `PR-08.2`
2. `PR-08.3`
3. `PR-08.4`
## Scope
1. Atualizar modelos em `prometeu-frontend-api` e `prometeu-compiler-core`.
2. Remover construtores de compatibilidade que aceitam `moduleKey` string.
3. Atualizar agregacao para reindexar apenas por `ModuleId` + `modulePool`.
4. Atualizar todos os testes afetados.
## Non-Goals
1. Nao alterar formato PBX nesta PR.
2. Nao mudar semantica de host/intrinsic callsites.
## Method
### O que deve ser feito explicitamente
1. Em `IRBackendExecutableFunction`:
- remover campo `moduleKey`,
- remover `calleeModuleKey`,
- manter apenas `ModuleId` estrutural.
2. Em `CallableSignatureRef`:
- remover `moduleKey`,
- manter `moduleId` + assinatura.
3. Em `IRBackend` agregador:
- remover `moduleReferenceFromKey(...)` e qualquer fallback textual.
4. Em testes:
- converter fixtures para `ModuleId` + `modulePool`.
## Acceptance Criteria
1. Nao existe mais `moduleKey` string em contratos estruturais FE/BE.
2. Reindexacao multi-file usa somente dense tables.
3. Build/test passam sem camadas de compatibilidade textual.
## Tests
1. `:prometeu-compiler:prometeu-compiler-core:test`
2. `:prometeu-compiler:prometeu-frontend-api:test`
3. `:prometeu-compiler:prometeu-build-pipeline:test`
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Nenhuma. Esta PR fecha corte de transicao.

68
docs/compiler/pbs/pull-requests/PR-09.2-pbs-frontend-moduleid-only-lowering-and-import-surfaces.md
View File

@ -1,68 +0,0 @@
# PR-09.2 - PBS Frontend Lowering: ModuleId-Only (No `moduleKey` in lowering surfaces)
## Briefing
Mesmo apos o contrato aceitar `ModuleId`, o lowering PBS ainda trafega `moduleKey` em estruturas internas (`ImportedCallableSurface`, indices auxiliares e fixtures).
## Motivation
### Dor atual que esta PR resolve
1. FE ainda acopla resolucao de callable/import a string de modulo.
2. A remocao de `moduleKey` no contrato quebra se FE nao migrar totalmente.
3. Risco de divergencia entre metadado textual e identidade internada.
## Target
Migrar lowering PBS para `ModuleId` como identidade unica:
1. `ImportedCallableSurface` sem `moduleKey`,
2. callsite/callable lookup por ids internados,
3. diagnosticos e logs usando renderizacao derivada de `modulePool` apenas quando necessario.
## Dependencies
Prerequisito direto:
1. `PR-09.1`
## Scope
1. Atualizar `PbsFrontendCompiler` para operar com `ModuleId` nas superfices de import/callable.
2. Atualizar `PBSFrontendPhaseService` para fornecer metadados densos sem string estrutural.
3. Atualizar testes PBS e artifacts golden.
## Non-Goals
1. Nao alterar parser PBS.
2. Nao alterar admission de host capabilities.
## Method
### O que deve ser feito explicitamente
1. Remover `moduleKey` de `ImportedCallableSurface`.
2. Em `collect/lower callsites`, propagar `calleeModuleId` via assinatura internada.
3. Ajustar renderizacao de debug para usar `modulePool` quando mostrar modulo.
4. Atualizar golden printer para mostrar `moduleId` (e opcionalmente nome renderizado derivado).
## Acceptance Criteria
1. FE PBS nao depende de `moduleKey` string para resolver/importar/lower callables.
2. Todas as callsites `CALL_FUNC` carregam `calleeModuleId` coerente.
3. Testes PBS passam sem acessos estruturais a chave textual.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
2. `:prometeu-compiler:prometeu-frontend-api:test --tests *IRBackendExecutableContractTest*`
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Nenhuma. Regra fica `ModuleId`-only para identidade estrutural.

72
docs/compiler/pbs/pull-requests/PR-09.3-lower-to-irvm-moduleid-only-ordering-and-strict-qualified-entrypoint.md
View File

@ -1,72 +0,0 @@
# PR-09.3 - LowerToIRVM: ModuleId-Only Ordering + Strict Qualified Entrypoint
## Briefing
`LowerToIRVMService` ainda possui fallback para `moduleKey` textual e fallback de entrypoint por nome quando `entryPointModuleId` nao e informado.
## Motivation
### Dor atual que esta PR resolve
1. Ordenacao de funcoes ainda pode depender de string legado.
2. Entrypoint pode cair em selecao name-only, mantendo ambiguidade residual.
3. Contrato qualificado existe, mas nao e estrito.
## Target
Tornar lowering estritamente orientado por identidade:
1. ordenacao por `ModuleId -> modulePool` somente,
2. entrypoint obrigatoriamente qualificado (`entryPointModuleId + callableName`),
3. remover fallback textual/heuristico.
## Dependencies
Prerequisitos diretos:
1. `PR-09.1`
2. `PR-09.2`
## Scope
1. Atualizar `LowerToIRVMService` para eliminar `fallbackModuleKey`.
2. Validar presenca obrigatoria de `entryPointModuleId` para entrada executavel.
3. Atualizar testes de ordenacao, ambiguidades e erros deterministas.
## Non-Goals
1. Nao alterar regra `func_id=0` (continua entrypoint).
2. Nao alterar emissao de opcodes.
## Method
### O que deve ser feito explicitamente
1. Substituir `moduleSortKey(...)` textual por leitura canonica direta do `modulePool` indexado por `ModuleId`.
2. Em `orderFunctions`, rejeitar entrada sem `entryPointModuleId`.
3. Remover caminho de erro/controle baseado em entrypoint name-only.
4. Cobrir com testes:
- entrypoint qualificado valido,
- entrypoint qualificado ausente,
- homonimos em modulos distintos com qualificacao.
## Acceptance Criteria
1. Nenhum fallback para `moduleKey` no LowerToIRVM.
2. Entrypoint e sempre resolvido por identidade qualificada.
3. Determinismo preservado em rebuild equivalente.
## Tests
1. `:prometeu-compiler:prometeu-build-pipeline:test --tests *LowerToIRVMServiceTest*`
2. `:prometeu-compiler:prometeu-build-pipeline:test --tests *BackendSafetyGateSUTest*`
## Affected Documents
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
2. `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Nenhuma. Esta PR fecha o fallback de entrypoint name-only.

84
docs/compiler/pbs/pull-requests/PR-09.4-specs-refresh-moduleid-only-entrypointref-and-bytecode-alignment.md
View File

@ -1,84 +0,0 @@
# PR-09.4 - Specs Refresh: ModuleId-Only + EntrypointRef Normative Alignment
## Briefing
Com a remocao estrutural de `moduleKey`, as specs normativas precisam refletir:
1. identidade de modulo densa (`ModuleId`),
2. entrypoint qualificado (`EntrypointRef`),
3. ausencia de fallback textual.
## Motivation
### Dor atual que esta PR resolve
1. Specs ainda descrevem partes name-only/text-based em pontos criticos.
2. Matriz pode afirmar `pass` sem refletir contratos mais estritos.
3. Risco de regressao por lacuna documento->implementacao.
## Target
Atualizar o baseline normativo para o modelo final:
1. `IRBackend` estrutural sem `moduleKey`,
2. `EntrypointRef(moduleId, callableName)` obrigatorio em handoff executavel,
3. ordenacao/lowering sem dependencias textuais.
## Dependencies
Prerequisitos diretos:
1. `PR-09.1`
2. `PR-09.2`
3. `PR-09.3`
## Scope
1. Revisar e atualizar specs:
- PBS 13 (Lowering IRBackend),
- General 20 (IRBackend -> IRVM),
- General 15 (Bytecode mapping entrypoint linkage),
- General 22 (matriz de conformidade).
2. Registrar decisao de corte definitivo (`moduleKey` removido).
## Non-Goals
1. Nao alterar implementação de runtime nesta PR.
2. Nao introduzir novo formato de arquivo para `program.pbx`.
## Method
### O que deve ser feito explicitamente
1. Em PBS13 e G20:
- trocar obrigacoes name-only por `EntrypointRef` qualificado,
- declarar `ModuleId` como identidade estrutural unica.
2. Em G15:
- manter `func_id=0` como entrypoint selecionado por `EntrypointRef`.
3. Em G22:
- adicionar/ajustar requirement rows para:
- no-moduleKey structural identity,
- strict qualified entrypoint,
- moduleid-only ordering.
## Acceptance Criteria
1. Nenhuma spec normativa relevante menciona `moduleKey` como identidade estrutural.
2. Matriz de conformidade cobre explicitamente obrigações novas.
3. `BackendConformanceMatrixSpecTest` e gate hard-policy permanecem verdes.
## Tests
1. `:prometeu-compiler:prometeu-build-pipeline:test --tests *BackendConformanceMatrixSpecTest*`
2. `:prometeu-compiler:prometeu-build-pipeline:test --tests *BackendClaimScopeSpecTest*`
## Affected Documents
1. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
3. `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
4. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
## Open Questions
1. Nenhuma. Esta PR e de alinhamento normativo.

76
docs/compiler/pbs/pull-requests/PR-09.5-hard-gates-no-modulekey-regression-and-migration-cleanup.md
View File

@ -1,76 +0,0 @@
# PR-09.5 - Hard Gates: No-`moduleKey` Regression + Migration Cleanup
## Briefing
Depois do corte `ModuleId`-only, precisamos impedir reintroducao acidental de `moduleKey` estrutural e limpar residuos de migracao.
## Motivation
### Dor atual que esta PR resolve
1. Sem gate dedicado, regressao textual pode voltar por conveniencia.
2. Testes/golden antigos ainda podem carregar nomenclatura de transicao.
3. Confianca de manutencao cai sem verificacao automatica de proibicao.
## Target
Fechar o ciclo de migracao:
1. adicionar gate anti-regressao (`moduleKey` proibido em contratos estruturais),
2. atualizar fixtures/golden para contrato final,
3. consolidar notas de migracao e contribuicao.
## Dependencies
Prerequisitos diretos:
1. `PR-09.1`
2. `PR-09.2`
3. `PR-09.3`
4. `PR-09.4`
## Scope
1. Criar teste/lint de proibicao para `moduleKey` em pacotes de contrato/lowering.
2. Atualizar `golden` de frontend/backend para `ModuleId`-only.
3. Atualizar docs de contribuicao para adicao de callables/modulos sem chave textual.
## Non-Goals
1. Nao alterar semantica de parser/lexer PBS.
2. Nao introduzir novo gate externo ao gradle test.
## Method
### O que deve ser feito explicitamente
1. Adicionar teste de policy:
- falha se campos/assinaturas estruturais de FE/BE usarem `moduleKey`.
2. Atualizar snapshots golden e testes que assumiam debug key textual.
3. Registrar checklist de migracao final:
- FE lowering,
- IRBackend contract,
- LowerToIRVM,
- docs/matriz.
## Acceptance Criteria
1. Nao existe `moduleKey` em contratos estruturais FE/BE.
2. Gate automatizado falha ao tentar reintroduzir o campo.
3. Testes/golden passam no modo novo sem artefatos legados.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
2. `:prometeu-compiler:prometeu-frontend-api:test`
3. `:prometeu-compiler:prometeu-build-pipeline:test`
## Affected Documents
1. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
2. `docs/pbs/pull-requests/INDEX.md`
3. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
## Open Questions
1. Nenhuma. PR de fechamento e anti-regressao.

84
docs/compiler/pbs/pull-requests/PR-09.6-isa-intrinsic-registry-single-source-artifact.md
View File

@ -1,84 +0,0 @@
# PR-09.6 - ISA-Scoped Intrinsic Registry as Single Source of Truth
## Briefing
Hoje o mapeamento `canonicalName@version -> finalId` ainda e mantido em dois lugares (compiler e runtime), com teste de paridade.
Isso reduz risco, mas ainda nao elimina dual-authoring.
## Motivation
### Dor atual que esta PR resolve
1. Fonte duplicada para IDs finais de intrinsic.
2. Risco operacional de drift entre compiler e runtime.
3. Evolucao de intrinsics depende de sincronizacao manual.
## Target
Definir um artefato unico, versionado e vinculado ao profile ISA para o registry de intrinsics:
1. artefato canonico de registry (`intrinsic-registry-v1`),
2. ownership normativo no boundary ISA/profile,
3. consumo por compiler e runtime a partir da mesma fonte.
## Dependencies
Prerequisitos diretos:
1. `PR-08.5` (paridade compiler-runtime existente)
2. `PR-09.7` (normalizacao de consumo no compiler)
## Scope
1. Definir formato normativo do artefato (CSV/TOML/JSON) no boundary ISA.
2. Definir local canonico e versionamento do artefato.
3. Definir contrato de evolucao:
- adicao de intrinsic,
- deprecacao,
- compatibilidade de IDs.
4. Definir gate de paridade contra consumidores.
## Non-Goals
1. Nao alterar semantica de opcode `INTRINSIC`.
2. Nao redesenhar toda a arquitetura de builtins do runtime nesta PR.
## Method
### O que deve ser feito explicitamente
1. Criar documento de formato canonico do registry:
- chave canonica,
- versao canonica,
- final id,
- constraints de unicidade.
2. Declarar ownership do artefato no profile ISA.
3. Definir pipeline de validacao:
- parser estrito,
- check de unicidade de identity e final id,
- check de ordenacao deterministica.
4. Definir workflow de manutencao para adicao de intrinsic.
## Acceptance Criteria
1. Existe uma unica fonte versionada para IDs finais de intrinsic.
2. Runtime e compiler referenciam formalmente essa fonte.
3. Processo de evolucao de intrinsics fica deterministico e auditavel.
## Tests
1. Testes de parser/validacao do artefato canonico.
2. Testes de paridade de consumidores contra o artefato.
3. Gate de CI que falha em divergia do mapping.
## Affected Documents
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
2. `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
3. `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
4. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
5. Runtime specs correspondentes (ajuste posterior no repo runtime).
## Open Questions
1. Local canonico final do artefato: `runtime` (recomendado) ou `shared-metadata` dedicado. runtime

76
docs/compiler/pbs/pull-requests/PR-09.7-compiler-normalization-to-isa-registry-artifact.md
View File

@ -1,76 +0,0 @@
# PR-09.7 - Compiler Normalization to ISA Intrinsic Registry Artifact
## Briefing
Apos estabelecer o artefato unico do registry (PR-09.6), o compiler precisa consumir exclusivamente esse artefato e remover caminhos residuais de dual-authoring.
## Motivation
### Dor atual que esta PR resolve
1. Compiler ainda pode depender de representacao local paralela.
2. Teste de paridade atual com parse de `builtins.rs` e acoplamento fragil de formato.
3. Falta um caminho de consumo unico no pipeline backend.
## Target
Normalizar o lado compiler para source-of-truth unico:
1. `IRVMIntrinsicRegistry` carregando apenas o artefato canonico ISA,
2. remover/encapsular validacoes que dependem de parsing textual de runtime internals,
3. reforcar gate de consistencia do consumidor compiler.
## Dependencies
Prerequisito direto:
1. `PR-09.6`
## Scope
1. Ajustar `IRVMIntrinsicRegistry` para modo canonical-only.
2. Revisar testes de paridade:
- principal: paridade com artefato canonico,
- opcional/informativo: runtime-backed check separado.
3. Garantir mensagens de erro e diagnostico estaveis para registry invalido.
## Non-Goals
1. Nao alterar implementacao de intrinsics no runtime.
2. Nao mover ownership de docs runtime nesta PR.
## Method
### O que deve ser feito explicitamente
1. Consolidar parser/loader do registry no compiler com contrato estrito.
2. Substituir assercoes hardcoded por fixtures derivadas do artefato.
3. Separar teste de compatibilidade runtime:
- nao bloquear desenvolvimento local quando runtime repo ausente,
- bloquear em modo strict/CI quando configurado.
4. Atualizar docs de contribuicao do compiler para fluxo de update de intrinsics.
## Acceptance Criteria
1. Compiler nao tem mais fonte duplicada de mapping de intrinsic IDs.
2. `LowerToIRVMService` resolve IDs finais exclusivamente via artefato canonico.
3. Suite de testes backend cobre:
- carregamento valido,
- invalid registry,
- mismatch detectavel em strict mode.
## Tests
1. `:prometeu-compiler:prometeu-build-pipeline:test --tests *IRVMIntrinsicRegistry*`
2. `:prometeu-compiler:prometeu-build-pipeline:test --tests *LowerToIRVMServiceTest*`
3. `:prometeu-compiler:prometeu-build-pipeline:test --tests *BackendConformanceMatrixSpecTest*`
## Affected Documents
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
2. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
3. `docs/pbs/pull-requests/INDEX.md`
## Open Questions
1. Nenhuma bloqueante para lado compiler.

69
docs/compiler/pbs/pull-requests/PR-10.1-pbs-parser-shared-context-and-safe-delegation.md
View File

@ -1,69 +0,0 @@
# PR-10.1 - PBS Parser Shared Context and Safe Delegation
## Briefing
`PbsParser` concentra estado compartilhado (`cursor`, `diagnostics`, `fileId`, `parseMode`, `loopDepth`) e responsabilidades de parsing em uma unica classe.
Esta PR introduz uma fundacao estrutural para decomposicao, sem alterar comportamento: um contexto compartilhado e pontos de delegacao seguros, mantendo `PbsParser` como fachada publica.
## Motivation
### Dor atual que esta PR resolve
1. Extracoes futuras dependem de copiar estado ou expor detalhes internos do parser.
2. O acoplamento entre navegação, diagnostico e parse impede quebrar a classe sem risco alto.
3. A refatoracao fica mais segura se a infraestrutura de compartilhamento vier antes da movimentacao de logica.
## Target
Estabelecer a base de refactor sem mudar funcionalidade:
1. Introduzir um contexto compartilhado para parser.
2. Encapsular helpers comuns de span/report/consume no contexto ou utilitarios proximos.
3. Permitir delegacao gradual para subparsers mantendo `PbsParser.parse(...)` como API unica.
## Dependencies
Nenhuma.
## Scope
1. Criar `ParserContext` ou equivalente com acesso a `cursor`, `diagnostics`, `fileId`, `parseMode` e `loopDepth`.
2. Mover helpers estruturais triviais para o contexto onde isso nao altere semantica.
3. Adaptar `PbsExprParser` bootstrap para consumir o mesmo contexto, ou uma visao compatível, sem mudar seu comportamento.
## Non-Goals
1. Nao alterar gramatica PBS.
2. Nao mover ainda parsing de tipos, atributos, blocos ou declaracoes para classes separadas.
3. Nao alterar mensagens, codigos de erro ou spans.
## Method
### O que deve ser feito explicitamente
1. Introduzir um objeto de contexto pequeno e explicito.
2. Manter `PbsParser` como orquestrador/fachada durante toda a PR.
3. Preservar o contrato de `parse(...)` e a ordem de consumo de tokens.
4. Validar que a nova camada e puramente estrutural.
## Acceptance Criteria
1. `PbsParser` continua sendo o unico entrypoint publico de parse.
2. Nenhum teste de parser, semantica ou frontend muda comportamento esperado.
3. Nao ha alteracao observavel em AST, spans ou diagnosticos.
4. A PR reduz acoplamento e prepara extracoes futuras sem mover regras complexas ainda.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. O `loopDepth` deve viver no contexto mutavel compartilhado ou em um helper especializado de block parsing? Esta PR pode manter no contexto; a decisao final pode vir na `PR-10.4`.

70
docs/compiler/pbs/pull-requests/PR-10.2-pbs-parser-attribute-and-type-subparsers.md
View File

@ -1,70 +0,0 @@
# PR-10.2 - PBS Parser Attribute and Type Subparsers
## Briefing
`PbsParser` ainda centraliza parsing de atributos, `typeRef` e `returnSpec`, que sao superficies coesas e amplamente reutilizadas.
Esta PR extrai essas responsabilidades para subparsers dedicados, sem alterar sintaxe aceita, AST produzido ou diagnosticos.
## Motivation
### Dor atual que esta PR resolve
1. `PbsParser` mistura topo de arquivo, declaracoes, blocos, atributos e tipos.
2. `parseTypeRef`, `parseAttribute*` e `parseCallableReturnSpec` sao hotspots claros de complexidade e reuso.
3. Sem extrair essa camada, as PRs seguintes continuam dependendo de uma classe central grande demais.
## Target
Separar parsing de tipos e atributos em colaboradores dedicados:
1. `PbsAttributeParser` ou equivalente.
2. `PbsTypeParser` ou equivalente.
3. Delegacao explicita a partir de `PbsParser`.
## Dependencies
Prerequisito direto:
1. `PR-10.1`
## Scope
1. Extrair `parseAttributeList`, `parseAttribute`, `parseAttributeArguments`, `parseAttributeArgument`, `parseAttributeValue`.
2. Extrair `parseTypeRef`, `parseNamedTupleTypeFields`, `parseCallableReturnSpec`, `parseReturnSpecFromMarker`, `isTypeStart`.
3. Preservar integralmente `PbsAst` e `ParseErrors`.
## Non-Goals
1. Nao alterar regras de atributos em modos `ORDINARY` e `INTERFACE_MODULE`.
2. Nao alterar aridade de named tuple.
3. Nao alterar recuperacao de erro alem do necessario para manter equivalencia.
## Method
### O que deve ser feito explicitamente
1. Mover parsing de atributos e tipos para classes pequenas, focadas e package-private.
2. Reusar o contexto compartilhado introduzido na PR anterior.
3. Manter `PbsParser` apenas como delegador nessas superficies.
4. Adicionar regressao para spans e diagnosticos de tipos/atributos se ainda nao houver cobertura suficiente.
## Acceptance Criteria
1. `PbsParser` deixa de implementar diretamente a maior parte do parsing de atributos e tipos.
2. AST e diagnosticos dessas superficies permanecem equivalentes.
3. A cobertura existente de parser continua verde sem mudancas semanticas.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsInterfaceModuleSemanticsTest*`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. Se `returnSpec` deve ficar no parser de tipos ou em um parser de callable surface. A recomendacao desta PR e manter em `PbsTypeParser`, porque o contrato de retorno depende diretamente de `typeRef`.

73
docs/compiler/pbs/pull-requests/PR-10.3-pbs-parser-top-level-declaration-decomposition.md
View File

@ -1,73 +0,0 @@
# PR-10.3 - PBS Parser Top-Level Declaration Decomposition
## Briefing
O maior concentrador de branching restante em `PbsParser` e a montagem de topo de arquivo e o dispatch de `declare ...`.
Esta PR extrai o parsing de declaracoes top-level e de corpos declarativos para colaboradores especificos, mantendo a mesma gramatica e o mesmo comportamento observavel.
## Motivation
### Dor atual que esta PR resolve
1. `parseFile` e `parseDeclareTopDecl` acumulam roteamento de muitas formas de declaracao.
2. Declaracoes como `host`, `builtin type`, `struct`, `contract`, `service`, `enum` e `implements` convivem no mesmo arquivo e elevam acoplamento.
3. Essa parte do parser muda com frequencia e hoje tem custo alto de manutencao.
## Target
Separar a camada de declaracoes top-level:
1. parsing de imports,
2. dispatch de `declare`,
3. parsing de corpos declarativos,
4. roteamento por `ParseMode`.
## Dependencies
Prerequisitos diretos:
1. `PR-10.1`
2. `PR-10.2`
## Scope
1. Extrair `parseFile` em conjunto com o dispatch de topo para um colaborador dedicado.
2. Extrair `parseDeclareTopDecl` e parsers correlatos (`host`, `builtin type`, `struct`, `contract`, `service`, `error`, `enum`, `callback`, `const`, `implements`).
3. Preservar o comportamento atual de atributos permitidos/proibidos por tipo de declaracao.
## Non-Goals
1. Nao alterar a ordem de imports/declarations no AST.
2. Nao alterar as regras de `INTERFACE_MODULE`.
3. Nao reescrever `PbsExprParser`.
## Method
### O que deve ser feito explicitamente
1. Criar um `PbsTopLevelParser` e um `PbsDeclarationParser`, ou divisao equivalente.
2. Manter em `PbsParser` apenas a montagem final da fachada e o fio de chamada principal.
3. Extrair por familias coesas de declaracao, evitando uma nova classe monolitica.
4. Preservar sincronia/recovery de topo no mesmo fluxo observavel.
## Acceptance Criteria
1. `parseFile` e `parseDeclareTopDecl` deixam de concentrar o dispatch completo de todas as declaracoes.
2. O parse de topo continua deterministico e equivalente ao estado anterior.
3. Testes de parser e frontend continuam verdes sem necessidade de atualizar fixtures por mudanca funcional.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsBarrelParserTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsInterfaceModuleSemanticsTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `implements` deve ficar junto de declaracoes top-level gerais ou em um parser especializado de contract/service surfaces? A recomendacao e mantê-lo no parser top-level por depender fortemente do roteamento de arquivo.

74
docs/compiler/pbs/pull-requests/PR-10.4-pbs-parser-block-and-statement-decomposition.md
View File

@ -1,74 +0,0 @@
# PR-10.4 - PBS Parser Block and Statement Decomposition
## Briefing
Depois de extrair tipos/atributos e declaracoes top-level, o maior hotspot restante de `PbsParser` passa a ser parsing de blocos e statements.
Esta PR separa `block`, `statement`, `assignment`, `loop` e controle de fluxo em um parser dedicado, sem alterar a funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. `parseBlock`, `parseStatement`, `parseIfStatement`, `parseForStatement` e correlatos mantem alta complexidade e forte acoplamento com `loopDepth`.
2. A mistura de statement parsing com helpers de token/erro dificulta evolucao e leitura.
3. O parser de blocos e o ponto mais sensivel para regressao e precisa de uma fronteira estrutural clara.
## Target
Extrair a superficie de blocos e statements para um colaborador dedicado:
1. blocos,
2. statements estruturados,
3. assignment detection,
4. controle de `loopDepth`.
## Dependencies
Prerequisitos diretos:
1. `PR-10.1`
2. `PR-10.2`
3. `PR-10.3`
## Scope
1. Extrair `parseBlock`, `parseStatement`, `parseLetStatement`, `parseAssignStatement`, `parseLValue`.
2. Extrair `parseIfStatement`, `parseForStatement`, `parseWhileStatement`, `parseBreakStatement`, `parseContinueStatement`, `parseReturnStatement`.
3. Extrair `isAssignmentStatementStart` e helpers locais associados.
## Non-Goals
1. Nao alterar regras de tail expression.
2. Nao alterar precedence de expressoes.
3. Nao alterar as mensagens atuais de erro para loop control e assignment targets.
## Method
### O que deve ser feito explicitamente
1. Introduzir um `PbsBlockParser` ou equivalente.
2. Encapsular `loopDepth` dentro do contexto compartilhado ou de uma API pequena de entrada/saida de loop.
3. Reutilizar `PbsExprParser` como dependencia, sem alterar seu contrato.
4. Preservar spans e forma de recovery dentro de blocos.
## Acceptance Criteria
1. `PbsParser` deixa de conter a maior parte do parsing de blocos e statements.
2. `loopDepth` continua correto para `break` e `continue`.
3. Nenhum teste de parser, semantica de flow ou lowering sofre alteracao funcional.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserStatementsTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsControlFlowTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsFallthroughTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `isAssignmentStatementStart` deve permanecer no parser de bloco ou virar helper de cursor/lookahead. A recomendacao e mantê-lo no parser de bloco nesta PR e avaliar extração posterior apenas se necessário.

80
docs/compiler/pbs/pull-requests/PR-10.5-pbs-parser-recovery-utilities-and-regression-hardening.md
View File

@ -1,80 +0,0 @@
# PR-10.5 - PBS Parser Recovery Utilities and Regression Hardening
## Briefing
As PRs anteriores reduzem a complexidade estrutural de `PbsParser`. Esta PR fecha a trilha com consolidacao de recovery/utilitarios e endurecimento de regressao, ainda sem alterar funcionalidade.
O objetivo e evitar que a decomposicao introduza pequenas divergencias em diagnosticos, spans ou pontos de reinicio.
## Motivation
### Dor atual que esta PR resolve
1. Recovery e helpers de consumo sao sensiveis e podem ficar duplicados apos a extracao.
2. Sem cobertura adicional, uma refatoracao estrutural grande pode preservar testes principais e ainda mudar detalhes de parser.
3. O parser precisa terminar menor, mas tambem com fronteiras de manutencao claras.
## Target
Consolidar a etapa final do refactor:
1. recovery de topo e de atributos,
2. helpers de consumo/report,
3. regressao de spans/diagnosticos,
4. limpeza final de `PbsParser`.
## Dependencies
Prerequisitos diretos:
1. `PR-10.1`
2. `PR-10.2`
3. `PR-10.3`
4. `PR-10.4`
## Scope
1. Consolidar `consume`, `consumeForToken`, `consumeDeclarationTerminator`, `consumeBalancedBraces`, `synchronizeTopLevel` e recovery de atributo em utilitarios coesos.
2. Remover duplicacao residual entre subparsers.
3. Adicionar ou endurecer testes de regressao para:
- spans,
- erros esperados,
- recovery em topo e em bloco,
- modos `ORDINARY` e `INTERFACE_MODULE`.
## Non-Goals
1. Nao alterar taxonomia de `ParseErrors`.
2. Nao introduzir novas construcoes sintaticas.
3. Nao reescrever o lexer ou `PbsExprParser`.
## Method
### O que deve ser feito explicitamente
1. Fazer uma passada final de consolidacao estrutural.
2. Eliminar helpers obsoletos ou duplicados apos as extracoes.
3. Verificar equivalencia observavel com foco em spans e recovery.
4. Encerrar a trilha com `PbsParser` como fachada pequena e clara.
## Acceptance Criteria
1. `PbsParser` fica restrito a composicao/orquestracao e nao volta a concentrar logica de parse pesado.
2. Recovery e consumo de token ficam centralizados e sem duplicacao relevante.
3. Suite do frontend PBS passa integralmente.
4. Nao ha mudanca funcional observavel em parse, AST ou diagnosticos.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserStatementsTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. Nenhuma de arquitetura. A partir desta PR, qualquer mudanca adicional deve ser tratada como evolucao funcional separada, nao como parte do refactor estrutural.

68
docs/compiler/pbs/pull-requests/PR-11.1-pbs-expr-parser-shared-context-and-precedence-spine.md
View File

@ -1,68 +0,0 @@
# PR-11.1 - PBS Expr Parser Shared Context and Precedence Spine
## Briefing
`PbsExprParser` hoje concentra estado compartilhado, helpers basicos e toda a espinha de precedence em uma unica classe.
Esta PR introduz a fundacao estrutural para decompor o parser de expressoes sem alterar comportamento: contexto compartilhado, helpers comuns e uma organizacao mais clara da cadeia de precedence.
## Motivation
### Dor atual que esta PR resolve
1. Extracoes futuras dependem de duplicar acesso a `cursor`, `diagnostics`, `fileId` e `blockParserDelegate`.
2. A cadeia de precedence existe, mas toda a infraestrutura esta acoplada a uma unica classe.
3. Refatorar primeiro a fundacao reduz risco antes de mover control-flow e postfix/primary.
## Target
Estabelecer uma base segura para o refactor de `PbsExprParser`:
1. contexto compartilhado,
2. helpers de span/report/consume reutilizaveis,
3. espinha de precedence claramente separada do restante.
## Dependencies
Nenhuma.
## Scope
1. Introduzir `ExprParserContext` ou equivalente.
2. Encapsular `cursor`, `diagnostics`, `fileId` e `blockParserDelegate` nessa camada.
3. Reorganizar a espinha de precedence (`parseExpression`, `parseApply`, `parseOr`, `parseAnd`, `parseEquality`, `parseComparison`, `parseAs`, `parseTerm`, `parseFactor`, `parseUnary`) sem mudar a ordem semantica.
## Non-Goals
1. Nao alterar associatividade ou precedence.
2. Nao mover ainda parsing de `if/switch/handle`.
3. Nao alterar `PbsParser` nem `PbsTokenCursor`.
## Method
### O que deve ser feito explicitamente
1. Criar um contexto compartilhado pequeno e explicito.
2. Manter `PbsExprParser` como entrypoint package-private.
3. Preservar a ordem atual de chamadas na chain de precedence.
4. Validar que esta PR e puramente estrutural.
## Acceptance Criteria
1. `PbsExprParser` continua com o mesmo contrato de entrada/saida.
2. Precedence e associatividade permanecem equivalentes.
3. Nao ha mudanca observavel em AST, spans ou diagnosticos de expressoes.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `blockParserDelegate` deve continuar como callback simples ou migrar para interface mais rica de surface parsing? Nesta PR, manter callback simples minimiza risco.

72
docs/compiler/pbs/pull-requests/PR-11.2-pbs-expr-parser-control-flow-subparsers.md
View File

@ -1,72 +0,0 @@
# PR-11.2 - PBS Expr Parser Control-Flow Subparsers
## Briefing
As formas de expressao com maior branching em `PbsExprParser` sao `if`, `switch`, `handle` e `else`.
Esta PR extrai essas construcoes para subparsers dedicados, mantendo a mesma sintaxe, mesmos diagnosticos e o mesmo AST.
## Motivation
### Dor atual que esta PR resolve
1. `if/switch/handle` compartilham recovery, parsing de blocos e recursion, elevando bastante a complexidade local.
2. Essas formas sao semanticamente coesas e podem viver fora do parser principal de precedence.
3. Sem essa extracao, `PbsExprParser` continua grande mesmo apos separar a fundacao.
## Target
Separar parsing de expressoes de controle de fluxo:
1. `handle`,
2. `else`,
3. `if expression`,
4. `switch expression`.
## Dependencies
Prerequisito direto:
1. `PR-11.1`
## Scope
1. Extrair `parseHandle`, `parseHandlePattern`, `parseElse`, `parseIfExpression`, `parseIfExpressionFromToken`, `parseSwitchExpression`, `parseSwitchPattern`.
2. Preservar uso de `parseSurfaceBlock` para blocos de expressao.
3. Manter exatamente a precedence atual dessas superficies.
## Non-Goals
1. Nao alterar a regra de `if expression` exigir `else`.
2. Nao alterar curingas de `switch`.
3. Nao alterar formatos aceitos de `handle` e remapeamento de erro.
## Method
### O que deve ser feito explicitamente
1. Introduzir subparsers pequenos por familia de construcao.
2. Reusar o contexto compartilhado da PR anterior.
3. Garantir que `parseExpression()` continue entrando pela mesma superficie sintatica.
4. Proteger a equivalencia com testes focados em control-flow expressions.
## Acceptance Criteria
1. A logica de `if/switch/handle/else` nao fica mais centralizada em `PbsExprParser`.
2. ASTs gerados para essas construcoes permanecem equivalentes.
3. Diagnosticos de formas invalidas continuam com o mesmo contrato observavel.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserStatementsTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsResultFlowRulesTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `else` deve viver junto do control-flow parser ou continuar na espinha de precedence. A recomendacao e movê-lo junto porque a associatividade e as mensagens de erro fazem parte do mesmo cluster conceitual.

74
docs/compiler/pbs/pull-requests/PR-11.3-pbs-expr-parser-postfix-primary-and-construction-decomposition.md
View File

@ -1,74 +0,0 @@
# PR-11.3 - PBS Expr Parser Postfix, Primary and Construction Decomposition
## Briefing
O segundo grande concentrador de complexidade em `PbsExprParser` esta nas superficies de `postfix` e `primary`: chamadas, membros, propagate, tuplas, blocos, `new`, `bind`, `some/ok/err`.
Esta PR separa essas familias em colaboradores menores, sem alterar a funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. `parsePostfix`, `parsePrimary` e `parseParenthesizedPrimary` misturam muitas formas sintaticas distintas.
2. Tuple literals, grouped expressions e construction surfaces compartilham lookahead delicado.
3. A manutencao dessas regras num unico metodo torna alto o custo de qualquer evolucao futura.
## Target
Separar parsing de superficies primarias e postfix:
1. postfix chaining,
2. primary literals/identifiers/blocks,
3. tuple/group handling,
4. construction/result surfaces (`new`, `bind`, `some`, `ok`, `err`).
## Dependencies
Prerequisitos diretos:
1. `PR-11.1`
2. `PR-11.2`
## Scope
1. Extrair `parsePostfix`.
2. Extrair `parsePrimary`, `parseParenthesizedPrimary`, `parseTupleItems`, `parseTupleItem`.
3. Extrair `parseNewExpression`, `parseBindExpression`, `parseSomeExpression`, `parseOkExpression`, `parseErrExpression`.
4. Preservar recovery atual para `?`, tuple malformed e parens.
## Non-Goals
1. Nao alterar a aridade de tuple literal.
2. Nao alterar mixed labeled/unlabeled tuple validation.
3. Nao alterar o formato aceito de `new Vec.zero(...)` e `bind(ctx, fn)`.
## Method
### O que deve ser feito explicitamente
1. Introduzir subparsers por familia sintatica em vez de criar um novo monolito.
2. Manter a ordem atual de postfix chaining.
3. Preservar lookahead de tuple/group exatamente como hoje.
4. Reforcar testes de tupla, construction e propagate operator invalido.
## Acceptance Criteria
1. `parsePostfix` e `parsePrimary` deixam de concentrar todas as superficies primarias.
2. Tuplas, grupos, constructions e postfix chains continuam equivalentes.
3. Nao ha mudanca funcional em AST, spans ou diagnosticos.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsOptionalResultTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsApplyResolutionTest*`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. O parsing de tuple/group deve ficar junto de primary ou em helper especializado de parenthesized surfaces. A recomendacao e extrair para helper especializado, porque esse e o trecho com lookahead mais sensivel.

73
docs/compiler/pbs/pull-requests/PR-11.4-pbs-expr-parser-literals-patterns-and-shared-token-utilities.md
View File

@ -1,73 +0,0 @@
# PR-11.4 - PBS Expr Parser Literals, Patterns and Shared Token Utilities
## Briefing
Depois de extrair control-flow e primary/postfix, restam em `PbsExprParser` alguns clusters menores mas sensiveis: parsing de literais/padroes, `error path`, consumo de tokens e utilitarios de parse numerico/string.
Esta PR consolida esses pontos em utilitarios dedicados, ainda sem mudanca funcional.
## Motivation
### Dor atual que esta PR resolve
1. Parsing de literal aparece em mais de um lugar (`primary` e switch pattern).
2. `error path`, `consumeMemberName`, `parseLong/Int/DoubleOrDefault` e `unescapeString` sao infra compartilhada e hoje permanecem acoplados ao parser principal.
3. Sem consolidar essa base, o parser termina menor, mas ainda com detalhes mecanicos espalhados.
## Target
Extrair infra compartilhada de expressao:
1. parsing de literais,
2. parsing de `error path`,
3. parsing de patterns simples,
4. token utilities e decode helpers.
## Dependencies
Prerequisitos diretos:
1. `PR-11.1`
2. `PR-11.2`
3. `PR-11.3`
## Scope
1. Extrair `parseLiteralPatternExpression`, `parseErrorPath`, `parseHandlePattern` e helpers correlatos.
2. Consolidar `consume`, `consumeMemberName`, `span`, `report`.
3. Consolidar `parseLongOrDefault`, `parseIntOrDefault`, `parseDoubleOrDefault`, `unescapeString`.
## Non-Goals
1. Nao alterar as regras de literal recovery.
2. Nao alterar o decode de strings.
3. Nao alterar a estrutura de `PbsAst.ErrorPath`.
## Method
### O que deve ser feito explicitamente
1. Reunir parsing de literal/pattern em componente reutilizavel.
2. Mover utilitarios mecanicos para helpers claros e pequenos.
3. Garantir que toda chamada mantenha a mesma atribuicao de spans e diagnosticos.
4. Evitar criar uma util-class genérica demais; manter helpers focados no dominio de expression parsing.
## Acceptance Criteria
1. `PbsExprParser` deixa de concentrar parsing repetido de literais/padroes e utilitarios basicos.
2. Parsing de strings, numeros e `error path` permanece equivalente.
3. A suite de parser continua verde sem atualizar comportamento esperado.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsDeclarationsTest*`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. Nenhuma de arquitetura. Esta PR e de consolidacao local.

75
docs/compiler/pbs/pull-requests/PR-11.5-pbs-expr-parser-regression-hardening-and-final-cleanup.md
View File

@ -1,75 +0,0 @@
# PR-11.5 - PBS Expr Parser Regression Hardening and Final Cleanup
## Briefing
As PRs anteriores reduzem a complexidade estrutural de `PbsExprParser`. Esta PR fecha a trilha com limpeza final, eliminacao de duplicacao residual e endurecimento de regressao, sem alterar funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. Refactors estruturais em parser de expressao podem mudar detalhes finos sem quebrar imediatamente todos os testes.
2. Ao final da decomposicao, costuma restar duplicacao pequena e helpers obsoletos.
3. O fechamento da trilha precisa garantir equivalencia observavel e uma fachada final pequena.
## Target
Concluir a trilha de refactor do parser de expressoes:
1. limpeza estrutural final,
2. consolidacao dos helpers remanescentes,
3. cobertura de regressao para precedence, postfix, tuples e control-flow expressions.
## Dependencies
Prerequisitos diretos:
1. `PR-11.1`
2. `PR-11.2`
3. `PR-11.3`
4. `PR-11.4`
## Scope
1. Remover codigo duplicado ou caminhos obsoletos apos as extracoes.
2. Garantir que `PbsExprParser` fique reduzido a composicao/orquestracao.
3. Expandir regressao quando necessario para spans, diagnosticos e precedence.
## Non-Goals
1. Nao alterar gramatica de expressoes.
2. Nao introduzir novas formas sintaticas.
3. Nao alterar `PbsAst` ou `ParseErrors`.
## Method
### O que deve ser feito explicitamente
1. Fazer uma passada final de consolidacao.
2. Verificar equivalencia com foco em:
- precedence,
- associatividade,
- tuple/group lookahead,
- control-flow expression recovery.
3. Encerrar a trilha com um `PbsExprParser` pequeno, claro e estavel.
## Acceptance Criteria
1. `PbsExprParser` termina como fachada/orquestrador, nao como concentrador de todas as regras.
2. Nao ha mudanca funcional observavel em AST, spans ou diagnosticos.
3. Suite do frontend PBS passa integralmente.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsParserStatementsTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. Nenhuma. A partir desta PR, qualquer ajuste restante deve ser tratado como mudanca funcional separada.

69
docs/compiler/pbs/pull-requests/PR-12.1-flow-expression-analyzer-context-and-dispatch-foundation.md
View File

@ -1,69 +0,0 @@
# PR-12.1 - Flow Expression Analyzer Context and Dispatch Foundation
## Briefing
`PbsFlowExpressionAnalyzer` concentra estado compartilhado e um dispatch grande de `Expression -> semantic analysis` em uma unica classe.
Esta PR introduz a base estrutural para decomposicao sem alterar funcionalidade: contexto compartilhado, helpers comuns e uma fronteira clara entre fachada e implementacoes especializadas.
## Motivation
### Dor atual que esta PR resolve
1. A classe combina orquestracao, recursion, block delegation e regras semanticas detalhadas.
2. Extracoes futuras ficam arriscadas sem um contexto compartilhado explicito.
3. O maior hotspot da classe e o dispatch principal de `analyzeExpressionInternal`, que hoje depende de muitos parametros repetidos.
## Target
Estabelecer uma fundacao segura para o refactor:
1. contexto compartilhado para analise de expressao,
2. encapsulamento de argumentos recorrentes,
3. fachada pequena em `PbsFlowExpressionAnalyzer`.
## Dependencies
Nenhuma.
## Scope
1. Introduzir um contexto/request object para `scope`, `expectedType`, `returnType`, `resultErrorName`, `receiverType`, `model`, `diagnostics`, `use` e `valueContext`.
2. Encapsular a dependencia de `BlockAnalyzer` nessa camada.
3. Reorganizar o dispatch principal sem mover ainda regras complexas para outras classes.
## Non-Goals
1. Nao alterar inferencia de tipos.
2. Nao alterar diagnosticos ou spans.
3. Nao reescrever `PbsFlowTypeOps` ou `PbsFlowBodyAnalyzer`.
## Method
### O que deve ser feito explicitamente
1. Criar um contexto pequeno e explicito para a analise recursiva.
2. Manter `PbsFlowExpressionAnalyzer` como entrypoint package-private.
3. Preservar a ordem atual de recursion e emissao de diagnosticos.
4. Garantir que esta PR seja puramente estrutural.
## Acceptance Criteria
1. `PbsFlowExpressionAnalyzer` continua com o mesmo contrato observavel.
2. A quantidade de parametros repetidos no dispatch recursivo e reduzida.
3. Nao ha mudanca funcional em inferencia, erros ou comportamento da suite.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsDeclarationsTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsAssignmentTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsApplyResolutionTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. O contexto deve ser imutavel por chamada recursiva ou permitir derivacao incremental. A recomendacao e usar derivacao imutavel leve para reduzir risco de regressao.

71
docs/compiler/pbs/pull-requests/PR-12.2-flow-expression-analyzer-literal-and-structural-expression-splitting.md
View File

@ -1,71 +0,0 @@
# PR-12.2 - Flow Expression Analyzer Literal and Structural Expression Splitting
## Briefing
Grande parte do dispatch de `PbsFlowExpressionAnalyzer` cobre formas literais e estruturais de expressao: literais, `this`, identificadores, grupos, tuplas, blocos, unarios, binarios, `none/some`, `new`, `as`, `ok/err`.
Esta PR extrai essas familias para componentes menores, sem alterar funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. O dispatch principal mistura casos triviais com regras mais complexas de call/member/switch/handle.
2. Formas estruturais simples podem ser separadas com risco baixo e alta reducao de complexidade.
3. Sem esse corte, o dispatch central continua inchado mesmo com contexto compartilhado.
## Target
Separar a analise de expressoes literais e estruturais:
1. literais e identificadores,
2. grupos, tuplas e blocos,
3. unario/binario,
4. `none/some`, `new`, `bind`-independent simple forms, `as`, `ok/err`.
## Dependencies
Prerequisito direto:
1. `PR-12.1`
## Scope
1. Extrair casos simples de `analyzeExpressionInternal` para helpers/colaboradores dedicados.
2. Manter o resultado em `ExprResult` exatamente como hoje.
3. Preservar todas as chamadas a `typeOps` e `blockAnalyzer`.
## Non-Goals
1. Nao alterar regras de callback/bind.
2. Nao alterar member access ou overload resolution.
3. Nao alterar switch/handle/result propagation.
## Method
### O que deve ser feito explicitamente
1. Mover primeiro os casos com menor acoplamento semantico.
2. Manter o dispatch principal apenas como roteador.
3. Preservar a ordem atual de recursion para evitar mudanca em diagnosticos acumulados.
## Acceptance Criteria
1. Casos literais e estruturais deixam de ficar todos dentro do dispatch principal.
2. AST/semantics observados pela suite permanecem equivalentes.
3. O hotspot principal da classe reduz tamanho e branching sem alterar comportamento.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsExprParserTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsOptionalResultTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsDeclarationsTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `BindExpr` deve entrar aqui ou junto de call resolution. A recomendacao e mantê-lo para `PR-12.3`, porque ele depende de matching de callback/callable.

72
docs/compiler/pbs/pull-requests/PR-12.3-flow-expression-analyzer-call-and-member-resolution-decomposition.md
View File

@ -1,72 +0,0 @@
# PR-12.3 - Flow Expression Analyzer Call and Member Resolution Decomposition
## Briefing
`analyzeCallExpression`, `analyzeApplyExpression`, `resolveCallableApplication`, `analyzeMemberExpression` e parte de `BindExpr` concentram a logica de resolucao mais sensivel do analisador.
Esta PR extrai essa superficie para colaboradores menores, sem alterar regras de overload, bare method extraction, acesso a campos ou matching de callback.
## Motivation
### Dor atual que esta PR resolve
1. Member access e callable resolution sao os clusters mais densos depois do dispatch principal.
2. A classe mistura regras de acesso a tuple/struct/service/contract com overload resolution e bind matching.
3. Qualquer ajuste nessas regras hoje exige tocar um arquivo muito central e com alta chance de regressao.
## Target
Separar a analise de resolucao:
1. member access,
2. call/apply overload resolution,
3. bind-to-callback matching,
4. field access permission checks.
## Dependencies
Prerequisitos diretos:
1. `PR-12.1`
2. `PR-12.2`
## Scope
1. Extrair `analyzeCallExpression`, `analyzeApplyExpression`, `resolveCallableApplication`.
2. Extrair `analyzeMemberExpression` e `canReadStructField`.
3. Mover a parte especifica de `BindExpr` para o mesmo cluster de resolucao.
## Non-Goals
1. Nao alterar diagnosticos de overload ambiguous/unresolved.
2. Nao alterar regras de leitura de campo privado/publico.
3. Nao alterar a proibicao de bare method extraction.
## Method
### O que deve ser feito explicitamente
1. Criar um resolver focado em call/member semantics.
2. Preservar o mesmo uso de `TypeView`, `CallableSymbol` e `ExprResult`.
3. Garantir que o order of checks permaneça equivalente, especialmente em erros e narrowing por `expectedType`.
## Acceptance Criteria
1. Call/member resolution deixa de ficar concentrada em `PbsFlowExpressionAnalyzer`.
2. Bare method extraction, field access e overload matching permanecem equivalentes.
3. Suite semantica continua verde sem mudancas funcionais.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsApplyResolutionTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsAssignmentTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsFrontendCompilerTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `BindExpr` deve compartilhar exatamente o mesmo narrowing path de `call/apply` ou ficar em helper proprio. A recomendacao e helper proprio dentro do mesmo resolver, para evitar acoplamento artificial.

73
docs/compiler/pbs/pull-requests/PR-12.4-flow-expression-analyzer-switch-and-handle-decomposition.md
View File

@ -1,73 +0,0 @@
# PR-12.4 - Flow Expression Analyzer Switch and Handle Decomposition
## Briefing
`switch` e `handle` sao as maiores superfices especializadas restantes em `PbsFlowExpressionAnalyzer`, com regras de exaustividade, pattern typing, matching de erro e arm typing.
Esta PR separa essas construcoes em analisadores dedicados, mantendo exatamente o comportamento atual.
## Motivation
### Dor atual que esta PR resolve
1. `analyzeSwitchExpression` e `analyzeHandleExpression` concentram regras de alto branching e recovery semantico.
2. Essas regras sao semanticamente coesas e merecem fronteiras proprias.
3. Sem esse corte, a classe principal continua com os hotspots mais caros de manutencao.
## Target
Extrair a analise especializada de:
1. `switch expression`,
2. `switch pattern typing/keying`,
3. `handle expression`,
4. `handle block arm` e matching de error targets.
## Dependencies
Prerequisitos diretos:
1. `PR-12.1`
2. `PR-12.2`
3. `PR-12.3`
## Scope
1. Extrair `analyzeSwitchExpression`, `switchPatternKey`, `switchPatternType`.
2. Extrair `analyzeHandleExpression`, `analyzeHandleBlockArm`, `matchesTargetError`, `unwrapGroup`.
3. Preservar a interacao com `blockAnalyzer`, `typeOps` e `model`.
## Non-Goals
1. Nao alterar regras de exaustividade de switch em value position.
2. Nao alterar regras de wildcard/default duplication.
3. Nao alterar regras de `handle` para `ok(...)` / `err(...)` terminais.
## Method
### O que deve ser feito explicitamente
1. Criar analisadores especializados por construcao.
2. Preservar ordem de validacoes e diagnosticos.
3. Reusar o contexto compartilhado para evitar nova explosao de parametros.
## Acceptance Criteria
1. `switch` e `handle` deixam de ficar implementados diretamente na classe principal.
2. Exaustividade, arm typing e error matching permanecem equivalentes.
3. Nenhum teste de result flow, control flow ou optional/result muda comportamento esperado.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsResultFlowRulesTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsOptionalResultTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsControlFlowTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `switchPatternKey` e `switchPatternType` devem ficar juntos no mesmo colaborador. A recomendacao e sim, porque ambos definem a semantica da superficie de pattern.

77
docs/compiler/pbs/pull-requests/PR-12.5-flow-expression-analyzer-regression-hardening-and-final-cleanup.md
View File

@ -1,77 +0,0 @@
# PR-12.5 - Flow Expression Analyzer Regression Hardening and Final Cleanup
## Briefing
As PRs anteriores reduzem a complexidade estrutural de `PbsFlowExpressionAnalyzer`. Esta PR fecha a trilha com consolidacao final, limpeza de duplicacao residual e endurecimento de regressao, sem alterar funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. Refactors estruturais em analise semantica podem preservar casos principais e ainda mudar detalhes finos de diagnostico.
2. Ao final da decomposicao, tendem a restar helpers redundantes ou caminhos duplicados.
3. O fechamento da trilha precisa garantir equivalencia observavel e uma fachada final pequena.
## Target
Concluir a trilha de refactor:
1. limpeza estrutural final,
2. consolidacao dos helpers remanescentes,
3. cobertura de regressao para inferencia e diagnosticos.
## Dependencies
Prerequisitos diretos:
1. `PR-12.1`
2. `PR-12.2`
3. `PR-12.3`
4. `PR-12.4`
## Scope
1. Remover duplicacao residual apos as extracoes.
2. Garantir que `PbsFlowExpressionAnalyzer` fique reduzido a composicao/orquestracao.
3. Reforcar testes de regressao para call/member resolution, result flow, switch e handle.
## Non-Goals
1. Nao alterar taxonomia de `PbsSemanticsErrors`.
2. Nao alterar `TypeView`, `ExprResult` ou `PbsFlowTypeOps`.
3. Nao introduzir novas regras semanticas.
## Method
### O que deve ser feito explicitamente
1. Fazer uma passada final de consolidacao.
2. Verificar equivalencia com foco em:
- inferencia de tipos,
- overload resolution,
- access checks,
- switch/handle exhaustiveness e matching,
- diagnosticos emitidos.
3. Encerrar a trilha com uma fachada pequena e clara.
## Acceptance Criteria
1. `PbsFlowExpressionAnalyzer` termina como orquestrador, nao como concentrador de toda a logica.
2. Nao ha mudanca funcional observavel em analise, tipos inferidos ou diagnosticos.
3. Suite do frontend PBS passa integralmente.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsApplyResolutionTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsResultFlowRulesTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsOptionalResultTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsControlFlowTest*`
5. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. Nenhuma. A partir desta PR, qualquer mudanca adicional deve ser tratada como evolucao funcional separada.

67
docs/compiler/pbs/pull-requests/PR-13.1-flow-body-analyzer-context-and-entrypoint-foundation.md
View File

@ -1,67 +0,0 @@
# PR-13.1 - Flow Body Analyzer Context and Entrypoint Foundation
## Briefing
`PbsFlowBodyAnalyzer` concentra montagem de contexto, iteracao de callables e delegacao recursiva de block/statement analysis em uma unica classe.
Esta PR introduz a base estrutural para decomposicao sem alterar funcionalidade: contexto compartilhado, encapsulamento dos argumentos recorrentes e uma fachada mais clara para a classe.
## Motivation
### Dor atual que esta PR resolve
1. A classe repassa muitos parametros repetidos entre `validate`, `validateCallableBody`, `analyzeBlock` e `analyzeStatement`.
2. Extracoes futuras ficam arriscadas sem um contexto comum explicito.
3. A fundacao estrutural reduz risco antes de mover regras de completion, statements e assignment resolution.
## Target
Estabelecer uma base segura para o refactor:
1. contexto compartilhado de body analysis,
2. encapsulamento de `returnType`, `resultErrorName`, `receiverType`, `model` e `diagnostics`,
3. fachada pequena para `validate(...)`.
## Dependencies
Nenhuma.
## Scope
1. Introduzir um contexto/request object para analise de corpo.
2. Reorganizar `validate` e `validateCallableBody` sem mover ainda regras complexas.
3. Preservar a relacao atual com `PbsFlowExpressionAnalyzer`.
## Non-Goals
1. Nao alterar inferencia de tipos ou diagnosticos.
2. Nao alterar `Model.from(...)`.
3. Nao mover ainda completion analysis ou assignment target resolution para classes separadas.
## Method
### O que deve ser feito explicitamente
1. Criar um contexto pequeno e explicito para analise recursiva de blocos/callables.
2. Manter `PbsFlowBodyAnalyzer` como entrypoint package-private.
3. Preservar a ordem atual de validacao e emissao de erros.
## Acceptance Criteria
1. `PbsFlowBodyAnalyzer` continua com o mesmo contrato observavel.
2. A quantidade de parametros repetidos nas chamadas internas e reduzida.
3. Nao ha mudanca funcional em flow analysis, completion ou diagnosticos.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsControlFlowTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsDeclarationsTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. O contexto deve ser derivado imutavelmente por bloco ou mutado localmente. A recomendacao e derivacao leve para reduzir risco de vazamento entre branches.

71
docs/compiler/pbs/pull-requests/PR-13.2-flow-body-analyzer-callable-body-and-completion-decomposition.md
View File

@ -1,71 +0,0 @@
# PR-13.2 - Flow Body Analyzer Callable Body and Completion Decomposition
## Briefing
As regras de entrada de callable e de completion/fallthrough em `PbsFlowBodyAnalyzer` formam um cluster coeso, mas hoje ficam misturadas com statement analysis e assignment resolution.
Esta PR extrai essa superficie para colaboradores dedicados, sem alterar funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. `validateCallableBody`, `validateCallableCompletion`, `blockAlwaysReturns`, `statementAlwaysReturns`, `expressionAlwaysReturns`, `switchAlwaysReturns` e `handleAlwaysReturns` concentram regras de completion com alto branching.
2. Completion analysis e statement analysis sao preocupacoes diferentes e hoje dividem a mesma classe.
3. Essa parte e muito sensivel e merece uma fronteira estrutural propria.
## Target
Separar a camada de body entry/completion:
1. bootstrap de callable body,
2. validacao de fallthrough/completion,
3. regras de `always returns`,
4. exaustividade relevante para completion.
## Dependencies
Prerequisito direto:
1. `PR-13.1`
## Scope
1. Extrair `validateCallableBody`.
2. Extrair `validateCallableCompletion`, `blockAlwaysReturns`, `statementAlwaysReturns`, `expressionAlwaysReturns`.
3. Extrair `switchAlwaysReturns`, `switchIsExhaustive`, `handleAlwaysReturns`, `handleArmAlwaysReturns`, `isKnownErrorPath`.
## Non-Goals
1. Nao alterar as regras atuais de fallthrough para result/plain non-unit.
2. Nao alterar a semantica de exaustividade usada apenas para completion.
3. Nao alterar statement analysis ou assignment checks.
## Method
### O que deve ser feito explicitamente
1. Introduzir um analisador de completion ou divisao equivalente.
2. Manter `PbsFlowBodyAnalyzer` como orquestrador do processo.
3. Preservar rigorosamente a ordem atual de checks e codigos de diagnostico.
## Acceptance Criteria
1. A logica de completion/fallthrough deixa de ficar centralizada em `PbsFlowBodyAnalyzer`.
2. As regras de `always returns` permanecem equivalentes.
3. Nenhum teste de fallthrough, control flow ou result flow muda comportamento esperado.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsFallthroughTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsControlFlowTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsResultFlowRulesTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `switch`/`handle` completion deve ficar junto do completion analyzer ou reaproveitar colaboradores do expression analyzer. A recomendacao e manter local ao completion analyzer para evitar acoplamento indevido entre analise de tipo e analise de terminacao.

72
docs/compiler/pbs/pull-requests/PR-13.3-flow-body-analyzer-statement-analysis-splitting.md
View File

@ -1,72 +0,0 @@
# PR-13.3 - Flow Body Analyzer Statement Analysis Splitting
## Briefing
Depois de separar entry/completion, o maior hotspot restante em `PbsFlowBodyAnalyzer` passa a ser `analyzeBlock` e `analyzeStatement`, com tratamento de `let`, `return`, `if`, `for`, `while`, expression statement e delegacao para `PbsFlowExpressionAnalyzer`.
Esta PR extrai essa superficie para colaboradores menores, sem alterar funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. `analyzeStatement` concentra varias formas de statement com regras semanticas distintas.
2. Loops, `if` e `return` usam os mesmos parametros e diagnosticos, mas pertencem a clusters semanticos diferentes.
3. A manutencao dessa logica em um unico metodo torna a classe dificil de evoluir.
## Target
Separar a analise de statements:
1. blocos e escopos,
2. `let` e expression statements,
3. `return` flow,
4. `if/for/while`.
## Dependencies
Prerequisitos diretos:
1. `PR-13.1`
2. `PR-13.2`
## Scope
1. Extrair `analyzeBlock` e o dispatch de `analyzeStatement`.
2. Extrair regras de `let`, `if`, `for`, `while` e expression statement para helpers/colaboradores dedicados.
3. Deixar `return` bootstrap pronto para corte proprio, sem ainda mexer em assignment target resolution.
## Non-Goals
1. Nao alterar mutabilidade de escopo local.
2. Nao alterar validacao de tipos de condicao ou bounds de loop.
3. Nao alterar assignment resolution.
## Method
### O que deve ser feito explicitamente
1. Introduzir um statement analyzer ou divisao equivalente por familias.
2. Reusar o contexto compartilhado da `PR-13.1`.
3. Preservar a ordem atual de chamadas ao `expressionAnalyzer`.
## Acceptance Criteria
1. `analyzeStatement` deixa de concentrar todas as formas de statement.
2. Scoping, condition checks e loop bound checks permanecem equivalentes.
3. Suite semantica continua verde sem mudanca funcional.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsControlFlowTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsAssignmentTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsDeclarationsTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `return` deve ficar no statement analyzer ou em um colaborador proprio de result flow. A recomendacao e deixar o corte final para a PR seguinte se isso simplificar mais a classe.

72
docs/compiler/pbs/pull-requests/PR-13.4-flow-body-analyzer-assignment-target-resolution-decomposition.md
View File

@ -1,72 +0,0 @@
# PR-13.4 - Flow Body Analyzer Assignment Target Resolution Decomposition
## Briefing
`resolveAssignmentTarget` e a logica correlata de assignment compatibility concentram um dos trechos mais densos e sensiveis de `PbsFlowBodyAnalyzer`.
Esta PR extrai a resolucao de assignment target e as regras de acesso/leitura/escrita de campo para colaboradores dedicados, sem alterar funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. Assignment resolution mistura lookup de locals, `this`, singleton services, consts e navegação em campos de struct.
2. Regras de leitura e escrita de campo estao acopladas ao fluxo do statement analyzer.
3. A superficie e densa e merece um resolver proprio com foco em diagnósticos de assignability.
## Target
Separar a camada de assignment semantics:
1. resolucao de assignment target,
2. assignability de roots conhecidos,
3. leitura/escrita de campos,
4. type compatibility por operador de atribuicao.
## Dependencies
Prerequisitos diretos:
1. `PR-13.1`
2. `PR-13.2`
3. `PR-13.3`
## Scope
1. Extrair `analyzeAssignmentStatement`.
2. Extrair `resolveAssignmentTarget`, `assignmentCompatible`, `canReadStructField`, `canWriteStructField`, `isKnownNonAssignableRoot`.
3. Manter `AssignmentTargetResolution` ou mover para um modelo focado de assignment.
## Non-Goals
1. Nao alterar regras de mutabilidade/local const.
2. Nao alterar regras de acesso a campos privados/publicos.
3. Nao alterar o mapeamento de operadores compostos para inferencia binaria.
## Method
### O que deve ser feito explicitamente
1. Criar um resolver dedicado para assignment targets.
2. Preservar exatamente os mesmos erros emitidos para target nao resolvido, nao assignable ou field access denied.
3. Reusar `PbsFlowTypeOps` sem alterar sua logica.
## Acceptance Criteria
1. Assignment target resolution deixa de ficar centralizada em `PbsFlowBodyAnalyzer`.
2. Regras de assignability e field access permanecem equivalentes.
3. Nenhum teste de assignment ou control flow muda comportamento esperado.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsAssignmentTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsDeclarationsTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. `AssignmentTargetResolution` deve permanecer como record local ou migrar para um modelo package-private dedicado. A recomendacao e mover para o resolver de assignment para reduzir acoplamento.

77
docs/compiler/pbs/pull-requests/PR-13.5-flow-body-analyzer-regression-hardening-and-final-cleanup.md
View File

@ -1,77 +0,0 @@
# PR-13.5 - Flow Body Analyzer Regression Hardening and Final Cleanup
## Briefing
As PRs anteriores reduzem a complexidade estrutural de `PbsFlowBodyAnalyzer`. Esta PR fecha a trilha com consolidacao final, limpeza de duplicacao residual e endurecimento de regressao, sem alterar funcionalidade.
## Motivation
### Dor atual que esta PR resolve
1. Refactors estruturais em flow/body analysis podem preservar casos principais e ainda mudar detalhes finos de diagnostico ou scoping.
2. Ao final da decomposicao, tendem a restar helpers redundantes ou caminhos duplicados.
3. O fechamento da trilha precisa garantir equivalencia observavel e uma fachada final pequena.
## Target
Concluir a trilha de refactor:
1. limpeza estrutural final,
2. consolidacao dos helpers remanescentes,
3. cobertura de regressao para completion, statements e assignment semantics.
## Dependencies
Prerequisitos diretos:
1. `PR-13.1`
2. `PR-13.2`
3. `PR-13.3`
4. `PR-13.4`
## Scope
1. Remover duplicacao residual apos as extracoes.
2. Garantir que `PbsFlowBodyAnalyzer` fique reduzido a composicao/orquestracao.
3. Reforcar testes de regressao para fallthrough, return flow, loops e assignments.
## Non-Goals
1. Nao alterar taxonomia de `PbsSemanticsErrors`.
2. Nao alterar `PbsFlowTypeOps` ou `PbsFlowExpressionAnalyzer`.
3. Nao introduzir novas regras semanticas.
## Method
### O que deve ser feito explicitamente
1. Fazer uma passada final de consolidacao.
2. Verificar equivalencia com foco em:
- completion/fallthrough,
- scoping local,
- return result flow,
- assignment target resolution,
- field access diagnostics.
3. Encerrar a trilha com uma fachada pequena e clara.
## Acceptance Criteria
1. `PbsFlowBodyAnalyzer` termina como orquestrador, nao como concentrador da logica completa.
2. Nao ha mudanca funcional observavel em flow analysis ou diagnosticos.
3. Suite do frontend PBS passa integralmente.
## Tests
1. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsFallthroughTest*`
2. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsAssignmentTest*`
3. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsControlFlowTest*`
4. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests *PbsSemanticsResultFlowRulesTest*`
5. `:prometeu-compiler:frontends:prometeu-frontend-pbs:test`
## Affected Documents
1. Nenhum documento normativo.
## Open Questions
1. Nenhuma. A partir desta PR, qualquer mudanca adicional deve ser tratada como evolucao funcional separada.

98
docs/compiler/pbs/pull-requests/PR-19.1-pbs-topic-19-spec-propagation-and-normative-cutover.md
View File

@ -1,98 +0,0 @@
# PR-19.1 - PBS Topic 19 Spec Propagation and Normative Cutover
## Briefing
As decisions `19.1` a `19.5` fecharam a arquitetura de globals, lifecycle markers, published wrapper, lowering e conformance para PBS v1.
Esta PR abre a execucao da familia `19` pela frente editorial normativa:
1. propagar as decisions para specs PBS e specs gerais relevantes;
2. remover lacunas documentais entre source model, lowering e publication contract;
3. alinhar o contrato final com entrypoint fisico `0` e sem autoridade de `entrypoint` no `manifest.json`.
## Target
Atualizar o baseline normativo para o modelo final de topic `19` em:
1. syntax and AST,
2. static semantics,
3. dynamic semantics,
4. diagnostics,
5. lowering,
6. bytecode/publication handoff.
## Dependencies
Prerequisitos diretos:
1. `Globals Surface, Identity, and Module Boundaries Decision.md`
2. `Lifecycle Markers, Program Init, and Frame Root Semantics Decision.md`
3. `Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Decision.md`
4. `Globals and Lifecycle Lowering to IRBackend and IRVM Decision.md`
5. `Diagnostics, Manifest Propagation, and Conformance Coverage Decision.md`
## Scope
1. Atualizar:
- PBS 3,
- PBS 4,
- PBS 7,
- PBS 9,
- PBS 11,
- PBS 12,
- PBS 13.
2. Atualizar:
- General 15,
- General 20.
3. Fixar normativamente:
- `declare global`,
- `[Init]`,
- `[Frame]`,
- `[InitAllowed]`,
- wrapper publicado,
- `FRAME_RET` no wrapper,
- entrypoint fisico `0`,
- `manifest.json` sem `entrypoint`.
## Non-Goals
1. Nao alterar parser, AST classes ou semantics code.
2. Nao implementar lowering.
3. Nao adicionar fixtures executaveis nesta PR.
4. Nao produzir `learn`.
## Method
1. Aplicar as decisions 19.x sem reabrir arquitetura.
2. Escrever os contratos em ingles normativo e com terminologia uniforme.
3. Fazer o corte documental completo do antigo modelo nominal de entrypoint.
4. Nomear explicitamente dependencias cross-domain quando a spec PBS depender do runtime protocol ja aceito.
## Acceptance Criteria
1. Nenhuma spec normativa relevante da linha PBS/general contradiz as decisions 19.x.
2. `declare global`, `[Init]`, `[Frame]` e `[InitAllowed]` aparecem com semantica consistente entre syntax, AST e static semantics.
3. O publication contract normativo aponta para wrapper sintetico em `func_id = 0`.
4. O `manifest.json` deixa de carregar autoridade de entrypoint nas specs PBS.
5. As specs gerais de handoff refletem o wrapper e o entrypoint fisico `0`.
## Tests
1. Revisao editorial integral dos documentos afetados.
2. Se houver harness de spec-to-test matrix para as specs gerais/pbs, mantelo verde.
## Affected Documents
1. `docs/compiler/pbs/specs/3. Core Syntax Specification.md`
2. `docs/compiler/pbs/specs/4. Static Semantics Specification.md`
3. `docs/compiler/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md`
4. `docs/compiler/pbs/specs/9. Dynamic Semantics Specification.md`
5. `docs/compiler/pbs/specs/11. AST Specification.md`
6. `docs/compiler/pbs/specs/12. Diagnostics Specification.md`
7. `docs/compiler/pbs/specs/13. Lowering IRBackend Specification.md`
8. `docs/compiler/general/specs/15. Bytecode and PBX Mapping Specification.md`
9. `docs/compiler/general/specs/20. IRBackend to IRVM Lowering Specification.md`
## Open Questions
1. Nenhuma. Esta PR e de propagacao normativa.

74
docs/compiler/pbs/pull-requests/PR-19.2-infra-dependencygraphanaliser-extraction-and-module-cutover.md
View File

@ -1,74 +0,0 @@
# PR-19.2 - Infra DependencyGraphAnaliser Extraction and Module Cutover
## Briefing
As decisions da familia `19` fixaram que modules e globals compartilham o mesmo kernel estrutural de analise de dependencias, vindo de um refactor do algoritmo atual de modules para `DependencyGraphAnaliser` em `util.structures`.
Esta PR faz somente esse corte de infra:
1. extrair o kernel estrutural reutilizavel;
2. migrar o uso atual de modules para esse novo componente;
3. deixar a superficie pronta para a futura aplicacao no graph de globals.
## Target
Introduzir um analizador estrutural generico para:
1. topological ordering,
2. deterministic traversal,
3. cycle detection,
4. e, quando util, exposicao de SCC/path para diagnostics.
## Dependencies
Prerequisitos diretos:
1. `Globals Surface, Identity, and Module Boundaries Decision.md`
## Scope
1. Extrair o algoritmo atual de dependency ordering de modules para `DependencyGraphAnaliser`.
2. Definir uma API estrutural baseada em nos canonicos e edges preconstruidas.
3. Migrar a linha atual de modules para usar esse componente comum.
4. Preservar comportamento observavel dos diagnostics de modules.
## Non-Goals
1. Nao introduzir ainda globals no pipeline semantico.
2. Nao misturar semantica de modules com semantica de globals.
3. Nao alterar parser ou AST.
4. Nao alterar diagnostics user-facing da linha de globals nesta PR.
## Method
1. Extrair apenas o kernel estrutural; sem abstrair semantica de descoberta de edges.
2. Manter cada dominio responsavel por:
- nos canonicos,
- edges,
- mapeamento para diagnostics.
3. Garantir regressao zero para a linha atual de dependency ordering de modules.
## Acceptance Criteria
1. Existe um `DependencyGraphAnaliser` reutilizavel em infra `util.structures`.
2. Modules passam a usar esse componente sem mudar o contrato observavel atual.
3. O componente nao carrega conhecimento de modulo, global ou PBS-specific semantics.
4. A futura linha de globals consegue consumir o novo kernel sem novo refactor estrutural.
## Tests
1. Testes atuais de dependency ordering e cycle detection de modules permanecem verdes.
2. Testes unitarios diretos do `DependencyGraphAnaliser` cobrem:
- DAG simples,
- ciclo,
- ordering deterministico,
- graph desconexo.
## Affected Artifacts
1. `prometeu-deps` e/ou infra estrutural equivalente
2. fases atuais que usam o algoritmo de dependency ordering de modules
## Open Questions
1. A exposicao de SCC/path pode ser minima nesta PR, desde que nao force novo refactor na PR-19.5.

70
docs/compiler/pbs/pull-requests/PR-19.3-pbs-parser-ast-globals-barrel-and-lifecycle-markers.md
View File

@ -1,70 +0,0 @@
# PR-19.3 - PBS Parser and AST for Globals, Barrel, and Lifecycle Markers
## Briefing
Depois do corte normativo e do refactor estrutural do dependency graph, PBS precisa aceitar a nova surface da familia `19` no frontend sintatico e no AST:
1. `declare global`,
2. entradas `global` em `mod.barrel`,
3. atributos `[Init]` e `[Frame]`.
Esta PR faz o corte parser+AST, sem ainda fechar toda a semantica.
## Target
Estender parser e AST para suportar:
1. declaracoes `global`,
2. barrel declarations `mod global` / `pub global`,
3. markers `[Init]` e `[Frame]` sobre `fn name() -> void`.
## Dependencies
Prerequisitos diretos:
1. `PR-19.1`
2. `PR-19.2`
## Scope
1. Atualizar lexer/parser/top-level declaration parsing conforme necessario.
2. Atualizar AST model para representar globals e markers de lifecycle.
3. Atualizar barrel AST para distinguir `global` de `const`.
4. Preservar spans e attribution adequados.
## Non-Goals
1. Nao validar ainda dependency graph de globals.
2. Nao validar ainda `[InitAllowed]` em host methods.
3. Nao implementar lowering.
4. Nao implementar published wrapper.
## Method
1. Introduzir novos nodes/surfaces com identidade explicita no AST.
2. Reusar padroes atuais de attributes/markers sem heuristicas textuais.
3. Preservar recovery e diagnosticos sintaticos existentes.
## Acceptance Criteria
1. Parser aceita `declare global Name: T = expr;`.
2. Parser aceita `mod global Name;` e `pub global Name;`.
3. AST distingue `global` de `const`.
4. AST registra `[Init]` e `[Frame]` como markers explicitos.
5. Spans e recovery permanecem defensaveis.
## Tests
1. Fixtures positivas de parse para `declare global`, barrel `global`, `[Init]` e `[Frame]`.
2. Fixtures negativas de parse para formas claramente malformed.
3. Regressao do conjunto atual de parser/AST.
## Affected Artifacts
1. parser PBS
2. AST model PBS
3. testes de parser/AST
## Open Questions
1. Nenhuma. A semantica fina fica para as PRs 19.4 a 19.6.

76
docs/compiler/pbs/pull-requests/PR-19.4-pbs-semantics-global-surface-identity-and-collision-validation.md
View File

@ -1,76 +0,0 @@
# PR-19.4 - PBS Semantics for Global Surface, Identity, and Collision Validation
## Briefing
Com parser e AST aceitando a nova surface, a primeira frente semantica precisa fechar o contrato local de `declare global`:
1. categoria declarativa distinta de `const`,
2. regras de namespace e colisao,
3. barrel/import visibility,
4. admissibilidade local do initializer.
Esta PR nao fecha ainda ordering nem ciclo entre globals.
## Target
Implementar validacao semantica para:
1. `declare global` como categoria propria,
2. barrel `global`,
3. colisao entre `fn`, `service`, `global` e `const`,
4. alias obrigatorio em imports quando houver conflito,
5. formas suportadas e nao suportadas no initializer.
## Dependencies
Prerequisitos diretos:
1. `PR-19.1`
2. `PR-19.3`
## Scope
1. Resolver `global` no value namespace sem colapsar categoria com `const`.
2. Enforcar collisions compile-time entre top-level visible symbols.
3. Validar import through `global` barrel entry.
4. Validar formas proibidas no initializer de `global`.
## Non-Goals
1. Nao construir ainda o dependency graph entre globals.
2. Nao validar lifecycle markers.
3. Nao implementar lowering.
## Method
1. Introduzir validacao de declaracao e linking local antes do graph global.
2. Emitir diagnosticos diretamente nos spans reais do codigo do usuario.
3. Tratar barrel/import como autoridade de visibilidade para globals.
## Acceptance Criteria
1. `global` e `const` permanecem semanticamente distintos.
2. Collisions entre `fn` / `service` / `global` / `const` geram erro compile-time.
3. Alias e exigido quando import criaria shadowing invalido.
4. Initializers proibidos de `global` sao rejeitados com diagnostico especifico.
5. Imports de global so resolvem via barrel `global`.
## Tests
1. Fixtures positivas para globals simples, `new`, member-value e import por barrel `global`.
2. Fixtures negativas para:
- collision cross-category,
- import sem alias quando exigido,
- `fn` no initializer,
- `if` no initializer,
- `some(...)` / `none`.
## Affected Artifacts
1. validadores semanticos PBS
2. linking/import resolution PBS
3. testes de semantics/declarations
## Open Questions
1. Nenhuma. Dependency graph fica para `PR-19.5`.

66
docs/compiler/pbs/pull-requests/PR-19.5-pbs-semantics-global-dependency-graph-and-cycle-validation.md
View File

@ -1,66 +0,0 @@
# PR-19.5 - PBS Semantics for Global Dependency Graph and Cycle Validation
## Briefing
Depois da superficie semantica local de `global`, PBS precisa implementar o ordering deterministico e a deteccao de ciclos entre globals usando o kernel compartilhado `DependencyGraphAnaliser`.
Esta PR fecha a parte de semantica que transforma leituras em initializers no graph canonico de globals.
## Target
Implementar:
1. nos canonicos de globals por owner module,
2. edges derivadas de leitura de globals em initializers,
3. ordering deterministico independente de source-file order,
4. diagnostico de ciclo entre globals.
## Dependencies
Prerequisitos diretos:
1. `PR-19.2`
2. `PR-19.4`
## Scope
1. Construir o graph semantico de globals.
2. Resolver alias/import para owner canonico.
3. Reusar `DependencyGraphAnaliser` como kernel estrutural.
4. Emitir diagnostico de ciclo com caminho canonicamente util quando possivel.
## Non-Goals
1. Nao validar ainda `[Init]` / `[Frame]`.
2. Nao implementar init sintetico de modulo.
3. Nao implementar lowering.
## Method
1. Modelar cada global como no canonico `(module, global_name)` ou equivalente interno estavel.
2. Criar edge quando initializer depende do valor materializado de outro global.
3. Usar ordering deterministico para fixar ordem de materializacao.
4. Manter source-file order fora da semantica.
## Acceptance Criteria
1. Ordering de globals e estavel e independe de ordem textual de arquivos.
2. Imports e aliases nao quebram identidade canonica do storage owner.
3. Ciclos intra-modulo e inter-modulo sao detectados como compile-time error.
4. Diagnostics apontam para globals reais, nao para estrutura sintetica.
## Tests
1. Fixtures positivas para dependency chains intra e inter-modulo.
2. Fixtures que provem mesma ordem mesmo com source-file order trocada.
3. Fixtures negativas para ciclos simples e ciclos via import/alias.
## Affected Artifacts
1. semantica de globals PBS
2. `DependencyGraphAnaliser` consumers
3. testes de dependency ordering/cycle diagnostics
## Open Questions
1. Nenhuma. A integracao com module/project init fica para `PR-19.6`.

82
docs/compiler/pbs/pull-requests/PR-19.6-pbs-semantics-lifecycle-init-frame-and-initallowed-validation.md
View File

@ -1,82 +0,0 @@
# PR-19.6 - PBS Semantics for Lifecycle Markers, Init Ordering, and InitAllowed Validation
## Briefing
Com globals e seu dependency graph fechados, a ultima frente semantica da familia `19` precisa validar a camada de lifecycle:
1. `[Init]`,
2. `[Frame]`,
3. ordenacao por arquivo/modulo/projeto,
4. e admissibilidade de host calls via `[InitAllowed]`.
## Target
Implementar a validacao de:
1. signatures de `[Init]` e `[Frame]`,
2. unicidade e colocacao de `[Frame]`,
3. um `[Init]` por arquivo,
4. elevacao do `[Init]` co-localizado com `[Frame]` para project init,
5. restricao de host calls durante init.
## Dependencies
Prerequisitos diretos:
1. `PR-19.3`
2. `PR-19.5`
## Scope
1. Validar `fn name() -> void` para `[Init]` e `[Frame]`.
2. Validar unicidade de `[Frame]` por projeto executavel.
3. Validar que project init e o `[Init]` no mesmo arquivo do `[Frame]`.
4. Validar que arquivos podem ter no maximo um `[Init]`.
5. Validar host call em init apenas quando o target SDK carregar `[InitAllowed]`.
## Non-Goals
1. Nao implementar ainda wrapper publicado.
2. Nao implementar ainda callables sinteticos de lowering.
3. Nao produzir ainda artifacts de conformance finais.
## Method
1. Construir a semantica de lifecycle em cima do ordering ja definido para globals.
2. Tratar module init e project init como diferenca de ordenacao e papel, nao de syntax.
3. Validar `[InitAllowed]` somente em host methods da SDK.
## Acceptance Criteria
1. `[Init]` e `[Frame]` exigem `fn name() -> void`.
2. Existe exatamente um `[Frame]` por projeto executavel.
3. `project init` e identificado apenas no arquivo do `[Frame]`.
4. Um arquivo nao pode declarar mais de um `[Init]`.
5. Host calls em init sem `[InitAllowed]` sao rejeitadas.
6. Uso invalido de `[InitAllowed]` e rejeitado.
## Tests
1. Fixtures positivas para:
- file `[Init]`,
- project `[Init]`,
- `[Frame]`,
- loops em init,
- host call admissivel com `[InitAllowed]`.
2. Fixtures negativas para:
- assinatura invalida,
- multiplos `[Frame]`,
- project init fora do arquivo do `[Frame]`,
- multiplos `[Init]` no arquivo,
- host call sem `[InitAllowed]`,
- `[InitAllowed]` em target invalido.
## Affected Artifacts
1. validadores semanticos/lifecycle PBS
2. admission de host methods em init
3. testes de lifecycle e diagnostics
## Open Questions
1. Nenhuma. O passo seguinte e lowering.

70
docs/compiler/pbs/pull-requests/PR-19.7-pbs-lowering-irbackend-globals-and-synthetic-callable-model.md
View File

@ -1,70 +0,0 @@
# PR-19.7 - PBS Lowering for IRBackend Globals and Synthetic Callable Model
## Briefing
As decisions de topic `19` fixaram que globals e artifacts de lifecycle precisam ficar explicitos no `IRBackend`, sem materializacao tardia implicita.
Esta PR faz o primeiro corte de lowering:
1. introduz globals explicitos no handoff,
2. introduz callables sinteticos com kind proprio,
3. introduz origin metadata sintetica suficiente para remapear diagnosticos.
## Target
Implementar no lowering PBS -> `IRBackend`:
1. modelagem explicita de backend globals,
2. distincao entre callables userland e callables sinteticos,
3. kinds sinteticos obrigatorios,
4. attribution/origin metadata para artifacts sinteticos.
## Dependencies
Prerequisitos diretos:
1. `PR-19.1`
2. `PR-19.5`
3. `PR-19.6`
## Scope
1. Introduzir globals explicitos no `IRBackend`.
2. Introduzir `FILE_INIT_FRAGMENT`, `MODULE_INIT`, `PROJECT_INIT` e `PUBLISHED_FRAME_WRAPPER` como identidade estrutural.
3. Introduzir `SyntheticOrigin` ou equivalente.
4. Preservar remap para spans reais quando houver origem defensavel.
## Non-Goals
1. Nao publicar ainda o wrapper final em `func_id = 0`.
2. Nao fechar ainda `FRAME_RET` ownership path.
3. Nao fechar ainda conformance final.
## Method
1. Modelar globals e callables sinteticos como first-class artifacts.
2. Evitar conventions baseadas apenas em nome textual.
3. Garantir que diagnosticos prefiram spans reais em vez de spans sinteticos.
## Acceptance Criteria
1. `IRBackend` passa a carregar globals explicitamente.
2. Callables sinteticos possuem class identity observavel.
3. Artifacts sinteticos carregam attribution suficiente para remap de diagnosticos.
4. O lowering nao depende de magic late-stage para globals/lifecycle.
## Tests
1. Fixtures de lowering com inspecao do `IRBackend`.
2. Verificacao de kinds sinteticos presentes.
3. Verificacao de origin metadata e remap defensavel.
## Affected Artifacts
1. lowering PBS -> `IRBackend`
2. modelo `IRBackend`
3. testes de lowering/attribution
## Open Questions
1. Nenhuma. Wrapper publication fica para `PR-19.8`.

70
docs/compiler/pbs/pull-requests/PR-19.8-pbs-lowering-published-wrapper-entrypoint-zero-and-frame-ret.md
View File

@ -1,70 +0,0 @@
# PR-19.8 - PBS Lowering for Published Wrapper, Entrypoint Zero, and FRAME_RET
## Briefing
Com globals e callables sinteticos explicitos no `IRBackend`, a proxima PR fecha a publicacao executavel da linha `19`:
1. wrapper sintetico publicado,
2. boot guard one-shot,
3. project/module init orchestration,
4. `[Frame]` do usuario como root logico,
5. `FRAME_RET` no wrapper,
6. entrypoint fisico `0`.
## Target
Implementar a publicacao executavel final alinhada as decisions `19.2`, `19.3` e `19.4`.
## Dependencies
Prerequisitos diretos:
1. `PR-19.7`
2. runtime boot protocol ja implementado/alinhado fora deste dominio
## Scope
1. Materializar `BOOT_GUARD` oculto.
2. Compor file init fragments, module init, project init e user `[Frame]` no wrapper final.
3. Publicar o wrapper como root fisico em `func_id = 0`.
4. Mover `FRAME_RET` para o wrapper.
5. Remover qualquer dependencia restante de autoridade de entrypoint em `FrontendSpec` para PBS.
## Non-Goals
1. Nao alterar runtime nesta PR.
2. Nao produzir `learn`.
3. Nao fechar sozinho toda a matriz de conformance final.
## Method
1. Compor o wrapper em ordem semantica fechada nas decisions.
2. Garantir one-shot boot via hidden guard.
3. Tratar `[Frame]` como callable logical-root invocado pelo wrapper, nao como entrypoint fisico publicado.
## Acceptance Criteria
1. O wrapper sintetico publicado existe no artifact executavel.
2. O wrapper ocupa `func_id = 0`.
3. `FRAME_RET` aparece no wrapper path, nao no final do body do user `[Frame]`.
4. Boot/inits executam uma unica vez.
5. O pipeline PBS deixa de depender de autoridade de entrypoint em `FrontendSpec`.
## Tests
1. Fixtures de artifact/lowering provando:
- wrapper publicado,
- boot guard,
- entrypoint `0`,
- `FRAME_RET` no wrapper.
2. Integracao compiler/runtime se o harness local ja estiver disponivel no studio.
## Affected Artifacts
1. lowering PBS -> `IRBackend`/`IRVM`
2. publication contract no pipeline do compiler
3. pontos PBS que ainda assumam `FrontendSpec` como autoridade de entrypoint
## Open Questions
1. Nenhuma. A evidencia final fica para `PR-19.9`.

Some files were not shown because too many files have changed in this diff Show More