From 05258c5363942bbef5ecfdc529756be93beee961 Mon Sep 17 00:00:00 2001
From: bQUARKz <bquarkz@gmail.com>
Date: Fri, 6 Mar 2026 10:44:03 +0000
Subject: [PATCH] added PRs

---
 docs/pbs/pull-requests/INDEX.md               |  7 +++
 ...-source-kind-and-module-origin-pipeline.md | 55 +++++++++++++++++++
 ...-stdlib-environment-resolver-and-loader.md | 53 ++++++++++++++++++
 ...24-pbs-parser-ast-interface-module-mode.md | 55 +++++++++++++++++++
 ...-interface-module-semantics-and-linking.md | 55 +++++++++++++++++++
 ...-026-pbs-sdk-minimal-core-color-and-gfx.md | 54 ++++++++++++++++++
 ...ta-extraction-and-ir-lowering-admission.md | 52 ++++++++++++++++++
 ...bs-gate-u-sdk-interface-module-fixtures.md | 55 +++++++++++++++++++
 8 files changed, 386 insertions(+)
 create mode 100644 docs/pbs/pull-requests/PR-022-pbs-source-kind-and-module-origin-pipeline.md
 create mode 100644 docs/pbs/pull-requests/PR-023-pbs-stdlib-environment-resolver-and-loader.md
 create mode 100644 docs/pbs/pull-requests/PR-024-pbs-parser-ast-interface-module-mode.md
 create mode 100644 docs/pbs/pull-requests/PR-025-pbs-interface-module-semantics-and-linking.md
 create mode 100644 docs/pbs/pull-requests/PR-026-pbs-sdk-minimal-core-color-and-gfx.md
 create mode 100644 docs/pbs/pull-requests/PR-027-pbs-builtin-metadata-extraction-and-ir-lowering-admission.md
 create mode 100644 docs/pbs/pull-requests/PR-028-pbs-gate-u-sdk-interface-module-fixtures.md

diff --git a/docs/pbs/pull-requests/INDEX.md b/docs/pbs/pull-requests/INDEX.md
index 3bf0d172..c701c8cd 100644
--- a/docs/pbs/pull-requests/INDEX.md
+++ b/docs/pbs/pull-requests/INDEX.md
@@ -30,3 +30,10 @@ Cada documento e auto contido e inclui: `Briefing`, `Target`, `Method`, `Accepta
 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`
diff --git a/docs/pbs/pull-requests/PR-022-pbs-source-kind-and-module-origin-pipeline.md b/docs/pbs/pull-requests/PR-022-pbs-source-kind-and-module-origin-pipeline.md
new file mode 100644
index 00000000..1a4fe93d
--- /dev/null
+++ b/docs/pbs/pull-requests/PR-022-pbs-source-kind-and-module-origin-pipeline.md
@@ -0,0 +1,55 @@
+# PR-022 - PBS Source Kind and Module Origin in Frontend Pipeline
+
+## Briefing
+
+O pipeline atual trata todo `.pbs` como fonte ordinaria de projeto.
+As specs exigem distincao entre source ordinario e interface-module de SDK/stdlib.
+
+Esta PR introduz classificacao explicita de origem de fonte no frontend para permitir regras diferentes por contexto.
+
+## Motivation
+
+Sem classificacao de origem, o parser e os validadores nao conseguem aplicar corretamente:
+
+- rejeicao de forms reservadas em projeto ordinario,
+- admissao de forms reservadas em interface modules,
+- e ownership correto de diagnosticos de resolucao/import.
+
+## Target
+
+- `FrontendPhaseContext` e dados de projeto consumidos pelo frontend PBS.
+- `PBSFrontendPhaseService` e fluxo de descoberta/roteamento de fontes.
+
+## Scope
+
+- Introduzir `SourceKind`/`ModuleOrigin` no pipeline (`PROJECT`, `SDK_INTERFACE`).
+- Preservar comportamento atual para fontes ordinarias.
+- Nao alterar ainda parser/semantica de forms reservadas (vem nas PRs seguintes).
+
+## Method
+
+- Adicionar modelagem de origem por unidade de modulo no frontend phase.
+- Classificar modulo pelo project space (`@core:*`, `@sdk:*` vs projetos ordinarios), conforme specs de resolucao.
+- Propagar `SourceKind` ate o ponto de parsing/validacao para habilitar gating por contexto nas PRs seguintes.
+
+## Acceptance Criteria
+
+- Cada arquivo `.pbs` processado pelo frontend possui `SourceKind` deterministico.
+- Modulos ordinarios continuam no caminho atual sem regressao.
+- Modulos reservados ficam marcados para fluxo de interface-module.
+
+## Tests
+
+- Testes unitarios para classificacao de origem de modulo por project space.
+- Testes de nao regressao em projeto ordinario sem stdlib.
+
+## Non-Goals
+
+- Implementar stdlib loader completo.
+- Alterar AST ou parser de forms reservadas.
+
+## Affected Documents
+
+- `docs/pbs/specs/3. Core Syntax Specification.md`
+- `docs/pbs/specs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
+- `docs/pbs/specs/8. Stdlib Environment Packaging and Loading Specification.md`
diff --git a/docs/pbs/pull-requests/PR-023-pbs-stdlib-environment-resolver-and-loader.md b/docs/pbs/pull-requests/PR-023-pbs-stdlib-environment-resolver-and-loader.md
new file mode 100644
index 00000000..dc7c15d2
--- /dev/null
+++ b/docs/pbs/pull-requests/PR-023-pbs-stdlib-environment-resolver-and-loader.md
@@ -0,0 +1,53 @@
+# PR-023 - PBS Stdlib Environment Resolver and Interface Loader
+
+## Briefing
+
+Para suportar interface modules reais, o frontend precisa resolver project spaces reservados (`@core:*`, `@sdk:*`) fora da trilha de dependencias ordinarias.
+
+Esta PR introduz o loader/resolver de stdlib environment com fronteiras explicitas.
+
+## Motivation
+
+As specs definem que stdlib e import ordinario possuem resolucoes distintas e sem fallback cruzado.
+Sem essa separacao, interface modules nao podem ser montados de forma normativa.
+
+## Target
+
+- Abstracoes de stdlib no frontend/compiler pipeline.
+- Fluxo de import para project spaces reservados.
+
+## Scope
+
+- Introduzir `StdlibEnvironment`, `StdlibModuleResolver`, `StdlibModuleSource`, `InterfaceModuleLoader`.
+- Integrar roteamento no `PBSFrontendPhaseService` para imports reservados.
+- Manter resolucao ordinaria inalterada para `@project:*` nao reservado.
+
+## Method
+
+- Implementar resolucao por linha de stdlib selecionada no root manifest.
+- Carregar modulo reservado como fonte PBS real (nao tabela hardcoded).
+- Emitir erro deterministico quando modulo reservado nao for encontrado/carregado.
+
+## Acceptance Criteria
+
+- Imports reservados nao passam por resolver ordinario.
+- Imports ordinarios nao passam por stdlib resolver.
+- Falha de resolucao reservada gera diagnostico deterministico e atribuivel.
+
+## Tests
+
+- Fixture: import reservado resolvido via stdlib resolver.
+- Fixture: modulo reservado inexistente com erro deterministico.
+- Fixture: tentativa de resolver reservado via trilha ordinaria rejeitada.
+
+## Non-Goals
+
+- Validacao semantica de forms reservadas dentro do modulo carregado.
+- Extracao de metadata de builtins/host para lowering.
+
+## Affected Documents
+
+- `docs/pbs/specs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
+- `docs/pbs/specs/8. Stdlib Environment Packaging and Loading Specification.md`
+- `docs/pbs/specs/12. Diagnostics Specification.md`
+
diff --git a/docs/pbs/pull-requests/PR-024-pbs-parser-ast-interface-module-mode.md b/docs/pbs/pull-requests/PR-024-pbs-parser-ast-interface-module-mode.md
new file mode 100644
index 00000000..26740bd2
--- /dev/null
+++ b/docs/pbs/pull-requests/PR-024-pbs-parser-ast-interface-module-mode.md
@@ -0,0 +1,55 @@
+# PR-024 - PBS Parser and AST Support for Interface-Module Mode
+
+## Briefing
+
+Hoje o parser rejeita atributos no topo e `declare host`/`declare builtin type` sempre.
+Em interface-module mode, essas forms reservadas devem ser parseadas e representadas no AST.
+
+## Motivation
+
+Sem AST/parser para forms reservadas:
+
+- nao ha como validar semantica de SDK/stdlib,
+- nao ha como extrair metadata (`Host`, `BuiltinType`, `Slot`, `IntrinsicCall`),
+- e nao ha base para linking/lowering dessas surfaces.
+
+## Target
+
+- `PbsAst` (novos nodes de declaracao e metadata de atributo).
+- `PbsParser` com `SourceKind`/mode-aware parsing.
+
+## Scope
+
+- Adicionar no AST: `HostDecl`, `BuiltinTypeDecl`, shapes de atributo e anexacao por posicao valida.
+- Em modo `PROJECT`: manter rejeicao de forms reservadas e atributos fora de regras.
+- Em modo `SDK_INTERFACE`: parsear forms reservadas e attributes permitidas.
+
+## Method
+
+- Tornar parser mode-aware (`ORDINARY`, `INTERFACE_MODULE`).
+- Substituir rejeicao hardcoded por gating por mode.
+- Preservar spans, recovery e diagnosticos deterministicos.
+
+## Acceptance Criteria
+
+- Modulo ordinario continua rejeitando `declare host`/`declare builtin type` e usos invalidos de atributos.
+- Interface module aceita as forms reservadas sintaticamente previstas.
+- AST exposto inclui metadata necessaria para fases seguintes.
+
+## Tests
+
+- Parser tests para ordinario vs interface-module com mesmos tokens.
+- Tests de recovery e spans nas novas declaracoes.
+- Tests negativos para formas reservadas malformadas.
+
+## Non-Goals
+
+- Julgamento semantico completo das attributes reservadas.
+- Resolucao de imports reservados (ja coberta em PR anterior).
+
+## Affected Documents
+
+- `docs/pbs/specs/3. Core Syntax Specification.md`
+- `docs/pbs/specs/11. AST Specification.md`
+- `docs/pbs/specs/12. Diagnostics Specification.md`
+
diff --git a/docs/pbs/pull-requests/PR-025-pbs-interface-module-semantics-and-linking.md b/docs/pbs/pull-requests/PR-025-pbs-interface-module-semantics-and-linking.md
new file mode 100644
index 00000000..4a0a1ff3
--- /dev/null
+++ b/docs/pbs/pull-requests/PR-025-pbs-interface-module-semantics-and-linking.md
@@ -0,0 +1,55 @@
+# PR-025 - PBS Interface-Module Semantics and Linking Rules
+
+## Briefing
+
+Depois de parsear forms reservadas, o frontend precisa validar regras semanticas especificas de interface modules e integrar host/builtin shells ao linking.
+
+## Motivation
+
+Sem essa etapa:
+
+- declarations reservadas entram sem contrato semantico,
+- host owners nao entram corretamente no namespace/linking,
+- e o barrel contract para `host` nao fecha.
+
+## Target
+
+- Validadores semanticos (`declaration`, `flow` quando aplicavel).
+- `PbsNamespaceBinder` e `PbsModuleVisibilityValidator`.
+
+## Scope
+
+- Validar restricoes declarativas de interface module (nao executavel, assinatura-only onde requerido).
+- Validar posicionamento/shape de `Host`, `BuiltinType`, `BuiltinConst`, `IntrinsicCall`, `Slot`.
+- Incluir host owners em namespace e linking (incluindo barrel host entry resolution).
+
+## Method
+
+- Adicionar caminho semantico para `SDK_INTERFACE` com regras de admissao dedicadas.
+- Reusar estrutura de diagnosticos com codigos estaveis.
+- Garantir ownership de fase para erros de linking vs static semantics.
+
+## Acceptance Criteria
+
+- `host` barrel entries resolvem quando `declare host` existe no modulo reservado.
+- Violacoes de posicionamento/shape de attributes reservadas sao rejeitadas deterministicamente.
+- Modulos ordinarios continuam com as regras atuais e sem regressao.
+
+## Tests
+
+- Fixtures positivos de interface module valido com host/builtin declarations.
+- Fixtures negativos de attributes mal posicionadas e host/builtin invalido.
+- Fixtures de linking para barrel host item resolvido e nao resolvido.
+
+## Non-Goals
+
+- Materializacao final de metadata no artifact/lowering.
+- Politica completa de runtime capabilities.
+
+## Affected Documents
+
+- `docs/pbs/specs/4. Static Semantics Specification.md`
+- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
+- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
+- `docs/pbs/specs/12. Diagnostics Specification.md`
+
diff --git a/docs/pbs/pull-requests/PR-026-pbs-sdk-minimal-core-color-and-gfx.md b/docs/pbs/pull-requests/PR-026-pbs-sdk-minimal-core-color-and-gfx.md
new file mode 100644
index 00000000..43862276
--- /dev/null
+++ b/docs/pbs/pull-requests/PR-026-pbs-sdk-minimal-core-color-and-gfx.md
@@ -0,0 +1,54 @@
+# PR-026 - PBS Minimal SDK Bootstrap with Core Color and Gfx Host Surface
+
+## Briefing
+
+Precisamos de um SDK minimo funcional para iniciar implementacao de builtins e validar o fluxo interface-module end-to-end.
+
+Esta PR introduz um pacote minimo de modulos reservados com exemplo `Color` e `Gfx`.
+
+## Motivation
+
+Sem SDK minimo, o suporte a interface mode fica sem fixture real de uso.
+Com ele, conseguimos exercitar import reservado, metadata, linking e base para lowering.
+
+## Target
+
+- Conteudo inicial do stdlib environment para linha v1.
+- Modulos reservados `@core:*` e `@sdk:*` com superfícies declarativas minimas.
+
+## Scope
+
+- Criar modulo `@core:color` com shell builtin `Color` (e opcional `Pixel`) como exemplo.
+- Criar modulo `@sdk:gfx` com `declare host Gfx` e assinatura anotada com `Host(...)`.
+- Fornecer `mod.barrel` coerente para os modulos criados.
+
+## Method
+
+- Publicar fontes `.pbs` de interface module no armazenamento escolhido para stdlib bootstrap (ex.: resources).
+- Manter tudo declarativo e nao executavel.
+- Garantir nomes/cases/assinaturas pequenas, estaveis e didaticas para suite inicial.
+
+## Acceptance Criteria
+
+- Import de `Color` via `@core:color` resolve e participa do type namespace.
+- Import de `Gfx` via `@sdk:gfx` resolve no host-owner namespace.
+- Modulos do SDK minimo passam parser+semantica+linking de interface-module.
+
+## Tests
+
+- Fixture de compilacao que importa `Color` e usa em assinatura/tipo.
+- Fixture de compilacao que importa `Gfx` e valida superficie host.
+- Fixtures negativas de barrel inconsistente no SDK minimo.
+
+## Non-Goals
+
+- Cobertura completa de builtins do stdlib.
+- Qualquer implementacao de comportamento runtime da API grafica.
+
+## Affected Documents
+
+- `docs/pbs/specs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
+- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
+- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
+- `docs/pbs/specs/8. Stdlib Environment Packaging and Loading Specification.md`
+
diff --git a/docs/pbs/pull-requests/PR-027-pbs-builtin-metadata-extraction-and-ir-lowering-admission.md b/docs/pbs/pull-requests/PR-027-pbs-builtin-metadata-extraction-and-ir-lowering-admission.md
new file mode 100644
index 00000000..15b4f8ea
--- /dev/null
+++ b/docs/pbs/pull-requests/PR-027-pbs-builtin-metadata-extraction-and-ir-lowering-admission.md
@@ -0,0 +1,52 @@
+# PR-027 - PBS Builtin Metadata Extraction and IR Lowering Admission
+
+## Briefing
+
+Com interface modules e SDK minimo ativos, precisamos fechar a fronteira entre metadata reservada e lowering frontend (`IRBackend`), sem degradacao silenciosa.
+
+## Motivation
+
+As specs exigem que metadata reservada seja compilacao-only e consumivel por lowering posterior.
+Tambem exigem rejeicao deterministica quando suporte ainda nao cobre algum caso.
+
+## Target
+
+- Extracao de metadata de attributes reservadas no grafo de interface.
+- Regras de admissao/rejeicao no lowering frontend (`IRBackend` boundary).
+
+## Scope
+
+- Extrair e armazenar canonical metadata de `Host`, `BuiltinType`, `IntrinsicCall`, `Slot`, `BuiltinConst`.
+- Preservar informacao minima necessaria no contrato de lowering frontend.
+- Emitir diagnostico deterministico para formas nao suportadas pela fronteira atual.
+
+## Method
+
+- Introduzir modelo interno de metadata reservada desacoplado da sintaxe bruta.
+- Atualizar contrato de admissao do frontend para recusar deterministicamente casos fora da fatia implementada.
+- Garantir fase/codigo/template/attribution estaveis nos diagnosticos de rejeicao.
+
+## Acceptance Criteria
+
+- Metadata reservada valida e acessivel apos parse+semantica+linking.
+- Nenhum caso nao suportado passa silenciosamente para `IRBackend` com comportamento alterado.
+- Rejeicoes de lowering frontend sao deterministicas e rastreaveis.
+
+## Tests
+
+- Fixtures positivas para extracao de metadata de `Color`/`Gfx`.
+- Fixtures negativas com metadata invalida e rejeicao deterministica.
+- Asserts de contrato diagnostico (phase, code, templateId, span).
+
+## Non-Goals
+
+- Implementar `IRBackend -> IRVM`.
+- Definir encoding final de artifact/PBX.
+
+## Affected Documents
+
+- `docs/pbs/specs/12. Diagnostics Specification.md`
+- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
+- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
+- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
+
diff --git a/docs/pbs/pull-requests/PR-028-pbs-gate-u-sdk-interface-module-fixtures.md b/docs/pbs/pull-requests/PR-028-pbs-gate-u-sdk-interface-module-fixtures.md
new file mode 100644
index 00000000..e9bfccd6
--- /dev/null
+++ b/docs/pbs/pull-requests/PR-028-pbs-gate-u-sdk-interface-module-fixtures.md
@@ -0,0 +1,55 @@
+# PR-028 - PBS Gate U Conformance Fixtures for SDK Interface Modules
+
+## Briefing
+
+A trilha de interface-module e SDK minimo precisa de evidencia Gate U para sustentar claim de conformidade e evitar regressao silenciosa.
+
+## Motivation
+
+Sem fixtures dedicadas:
+
+- nao ha prova objetiva do comportamento reservado,
+- nao ha protecao contra regressao de parser/semantica/linking/lowering,
+- e claims de conformidade ficam fracos.
+
+## Target
+
+- Suite de conformance no frontend PBS para o slice de SDK/interface-module.
+
+## Scope
+
+- Fixtures positivas e negativas para:
+  - classificacao de origem de fonte,
+  - resolucao de imports reservados,
+  - parser/AST em interface mode,
+  - semantica/linking de host/builtin shells,
+  - extracao de metadata e admissao/rejeicao de lowering frontend.
+
+## Method
+
+- Criar corpus Gate U minimalista e estavel, com asserts de diagnostico por codigo/fase/templateId.
+- Reusar exemplos `@core:color` e `@sdk:gfx` como base.
+- Cobrir casos de erro ownership (`manifest/import`, `linking`, `static semantics`, `load-facing` quando aplicavel).
+
+## Acceptance Criteria
+
+- Cada obrigacao introduzida nas PRs 022-027 possui ao menos 1 fixture positiva e 1 negativa quando aplicavel.
+- Diagnosticos sao validados por campos maquina-estaveis e nao por texto renderizado.
+- Suite do frontend PBS executa integralmente sem flakes.
+
+## Tests
+
+- Nova suite Gate U em `prometeu-frontend-pbs` com fixtures de sdk/interface-mode.
+- Execucao automatizada no `check` do modulo.
+
+## Non-Goals
+
+- Cobertura total de todo stdlib real.
+- Benchmarks de performance do loader.
+
+## Affected Documents
+
+- `docs/general/specs/13. Conformance Test Specification.md`
+- `docs/pbs/specs/12. Diagnostics Specification.md`
+- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
+