From bd989eab3290c9fc3a89f7e2bdb6b7512a5bc2be Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Mon, 30 Mar 2026 10:05:44 +0100 Subject: [PATCH] clean up --- discussion/index.ndjson | 4 +- ...t-metadata-and-ignored-value-discipline.md | 80 ++++ ...cing-asset-refs-and-call-result-discard.md | 373 ------------------ ...s-asset-address-surface-and-be-lowering.md | 147 ------- ...pbs-ignored-values-lowering-and-warning.md | 88 ----- ...-asset-address-surface-spec-propagation.md | 152 ------- ...bs-asset-address-surface-implementation.md | 184 --------- ...s-ignored-values-warning-implementation.md | 151 ------- ...ring-host-metadata-and-callsite-rewrite.md | 196 --------- 9 files changed, 82 insertions(+), 1293 deletions(-) create mode 100644 discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md delete mode 100644 discussion/workflow/agendas/AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md delete mode 100644 discussion/workflow/decisions/DEC-0005-pbs-asset-address-surface-and-be-lowering.md delete mode 100644 discussion/workflow/decisions/DEC-0006-pbs-ignored-values-lowering-and-warning.md delete mode 100644 discussion/workflow/plans/PLN-0005-pbs-asset-address-surface-spec-propagation.md delete mode 100644 discussion/workflow/plans/PLN-0006-pbs-asset-address-surface-implementation.md delete mode 100644 discussion/workflow/plans/PLN-0007-pbs-ignored-values-warning-implementation.md delete mode 100644 discussion/workflow/plans/PLN-0008-pbs-assetlowering-host-metadata-and-callsite-rewrite.md diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 6c4909ae..3cabcc2f 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,9 +1,9 @@ -{"type":"meta","next_id":{"DSC":9,"AGD":9,"DEC":7,"PLN":9,"LSN":24,"CLSN":1}} +{"type":"meta","next_id":{"DSC":9,"AGD":9,"DEC":7,"PLN":9,"LSN":25,"CLSN":1}} {"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} {"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} {"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} -{"type":"discussion","id":"DSC-0006","status":"open","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[{"id":"AGD-0006","file":"AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[{"id":"DEC-0005","file":"DEC-0005-pbs-asset-address-surface-and-be-lowering.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-03-27","ref_agenda":"AGD-0006"},{"id":"DEC-0006","file":"DEC-0006-pbs-ignored-values-lowering-and-warning.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-03-27","ref_agenda":"AGD-0006"}],"plans":[{"id":"PLN-0005","file":"PLN-0005-pbs-asset-address-surface-spec-propagation.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27","ref_decisions":["DEC-0005"]},{"id":"PLN-0006","file":"PLN-0006-pbs-asset-address-surface-implementation.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27","ref_decisions":["DEC-0005"]},{"id":"PLN-0007","file":"PLN-0007-pbs-ignored-values-warning-implementation.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27","ref_decisions":["DEC-0006"]},{"id":"PLN-0008","file":"PLN-0008-pbs-assetlowering-host-metadata-and-callsite-rewrite.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27","ref_decisions":["DEC-0005"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]} {"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} {"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} diff --git a/discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md b/discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md new file mode 100644 index 00000000..0c6bf41c --- /dev/null +++ b/discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md @@ -0,0 +1,80 @@ +--- +id: LSN-0024 +ticket: pbs-game-facing-asset-refs-and-call-result-discard +title: Addressable Surface, Host Metadata, and Ignored-Value Discipline +created: 2026-03-30 +tags: [compiler, pbs, asset-surface, lowering, diagnostics, runtime, host-metadata, ergonomics] +--- + +## Context + +PBS needed to close two related gaps at the boundary between ergonomic game code and executable lowering. +Asset references needed an author-facing symbolic surface that did not fall back to unstable `asset_name` lookup or couple the frontend directly to packer internals. +At the same time, expression statements that produce values needed an explicit discard rule so backend stack discipline would not leak into source authoring. + +The resulting implementation spans specs, frontend API models, backend lowering metadata, stdlib host surfaces, and compiler diagnostics. + +## Key Decisions + +### Keep Asset Authoring Symbolic But Backend-Owned + +**What:** +PBS now treats `assets...` as a hierarchical compile-time namespace whose terminal leaves are `Addressable` values supplied through a backend-owned `FESurfaceContext`. +The v1 surface carries `List`. + +**Why:** +This preserves natural source authoring while keeping the backend as the owner of operational asset identity and final `address -> asset_id` lowering. +The frontend gets enough structure for semantics, typing, and tooling without querying packer services directly. + +**Trade-offs:** +Rename or move operations now change the canonical symbolic address and can break compile-time references. +That is stricter than a loose name-based model, but the breakage is explicit and deterministic instead of becoming late runtime ambiguity. + +### Put Asset-Aware Lowering On Host Metadata, Not Service Bodies + +**What:** +Asset-aware host calls now declare `[AssetLowering(param = N)]`, and backend lowering uses that metadata to rewrite the selected `Addressable` argument into runtime-facing `asset_id`. + +**Why:** +This keeps lowering ownership on the host-backed contract surface instead of burying special behavior in wrapper services or generic expression shortcuts. +The lowering path stays aligned with `LowAssets`, and the compiler knows exactly which parameter is asset-facing. + +**Trade-offs:** +Host-backed signatures must be validated more strictly, and metadata propagation has to remain consistent across extraction, indexing, and lowering. +That adds infrastructure, but it prevents the normative path from becoming implicit or drifting between layers. + +### Treat Ignored Materialized Values As A General Language Rule + +**What:** +Any PBS expression statement that produces a materialized value now triggers two things: a warning diagnostic and explicit discard lowering. + +**Why:** +This keeps authoring simple without silently relying on backend stack behavior. +The language remains honest about ignored results while still allowing expression statements to execute. + +**Trade-offs:** +The compiler now distinguishes unit-like results from materialized values in both semantics and lowering. +That is more work than silently discarding everything, but it yields a stable, testable language rule instead of API-specific exceptions. + +## Patterns and Algorithms + +- Use a backend-to-frontend surface contract when the frontend needs semantic visibility but must not own operational truth. `FESurfaceContext` is intentionally small and deduplicated by canonical address. +- Model symbolic assets as a namespace tree with terminal leaves only. Intermediate namespaces are not values, and terminal paths cannot also behave as namespace prefixes. +- Carry executable special cases as reserved host metadata. `[AssetLowering(param = N)]` is the authoritative marker for backend callsite rewriting. +- Make lowering side effects explicit when a source form hides operational cost. Ignored expression results are not silently tolerated; they lower to discard behavior and emit a warning. +- Pin cross-layer contracts in specs, stdlib surfaces, and compiler tests together. That prevents the PBS surface, host metadata, and runtime lowering path from drifting apart. + +## Pitfalls + +- Do not reintroduce `asset_name` as the operational compile-time identity. The symbolic surface is the canonical address derived from the asset root. +- Do not let the frontend query packer services directly for visible assets. It must consume the backend-owned surface contract. +- Do not bypass host metadata with generic expression rewriting for asset-aware calls. The normative path is host-backed `AssetLowering`. +- Do not treat intermediate `assets...` namespaces as terminal values, and do not allow terminal-vs-namespace collisions in asset roots. +- Do not silently drop ignored materialized values. If the compiler materializes a value in statement position, the discard path and warning are both part of the language contract. + +## Takeaways + +- PBS asset authoring is symbolic and hierarchical, but operational asset identity remains backend-owned and runtime-aligned through `asset_id`. +- Asset-aware lowering belongs to the host contract through reserved metadata, not to ad hoc wrapper logic. +- Ignored values are now a general PBS language rule: warn in semantics, discard explicitly in lowering. +- The durable pattern is consistent boundary ownership: frontend surfaces stay ergonomic, backend lowering stays authoritative, and the runtime contract remains explicit. diff --git a/discussion/workflow/agendas/AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md b/discussion/workflow/agendas/AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md deleted file mode 100644 index ed1421a1..00000000 --- a/discussion/workflow/agendas/AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md +++ /dev/null @@ -1,373 +0,0 @@ ---- -id: AGD-0006 -ticket: pbs-game-facing-asset-refs-and-call-result-discard -title: PBS Game-Facing Asset References and Ignored Call Result Lowering -status: accepted -created: 2026-03-27 -resolved: 2026-03-27 -decision: DEC-0005, DEC-0006 -tags: [compiler, pbs, ergonomics, lowering, runtime, asset-identity, expression-statements] ---- - -## Pain - -PBS ainda tem dois atritos abertos na fronteira entre ergonomia de código de jogo e lowering executável: - -1. referências a assets continuam centradas em `asset_name` no código-fonte, enquanto packer/runtime já convergiram para identidade estável por `asset_id`; -2. `expression statements` com retorno materializado ainda precisam de política explícita de descarte, para não vazar regra de stack do backend para o código de usuário. - -Os dois temas pertencem à mesma discussão porque tratam da mesma pergunta arquitetural: - -Como PBS deve preservar uma superfície de autoria natural sem sacrificar determinismo no lowering e no runtime? - -## Context - -Esta agenda consolida dois tópicos legados do domínio PBS: - -- `18.4. Asset References in Game Code - Names vs Compile-Time Lowering` -- `18.5. Ignored Call Results in Executable Lowering` - -Os pontos estáveis já conhecidos são: - -- packer/runtime tratam `asset_id` como identidade estável; -- `asset_name` ainda é a superfície mais natural para autoria e tooling; -- o packer já mantém um `PackerRuntimeSnapshot` coerente em memória como projeção operacional do workspace ativo; -- Studio já consome leituras normais a partir desse snapshot operacional em vez de reconstituir a verdade diretamente do filesystem a cada interação; -- o pipeline executável hoje já exige disciplina explícita de stack; -- a família `19` reforçou a direção de compiler-owned lowering e publication protocol, reduzindo espaço para ambiguidades “aceitas pelo frontend, rejeitadas mais tarde”. - -Isso sugere um princípio comum: - -- a linguagem pode continuar amigável na superfície, -- mas o compiler precisa assumir explicitamente o trabalho de normalizar essa superfície para um contrato executável estável. - -O novo ponto importante é que, para referências a asset, essa “superfície amigável” não precisa nascer de nomes soltos escritos manualmente nem de arquivos tipados gerados sem owner claro. - -Ela pode ser tratada como uma projeção simbólica derivada da autoridade operacional já existente no packer: - -- `PackerRuntimeSnapshot` como fonte operacional coerente do conjunto de assets visíveis; -- backend/compiler como owner de uma `FESurfaceContext` derivada desse snapshot, sem expor o snapshot bruto ao frontend; -- Studio como IDE que consome e exibe essa superfície, mas não a possui normativamente; -- PBS como consumidor frontend dessa superfície tipada; -- backend/compiler como responsável final por validar e lowerar essa superfície para identidade estável de runtime. - -O entendimento atual desta discussão mudou um ponto importante do modelo anterior: - -- `asset_name` não parece justificar existência como campo operacional separado; -- o dado estrutural realmente útil já está no root do asset dentro de `assets/`; -- portanto a superfície simbólica candidata pode ser o próprio address normatizado derivado do diretório, e não um nome livre fornecido pelo autor. - -Exemplo de direção: - -- asset root em disco: `assets/some/dir/maluco/asset/asset.json` -- superfície simbólica projetada para código/tooling: `assets.some.dir.maluco.asset` - -Na direção atual, essa superfície não deve ser tratada como enum flat simples. - -O modelo preferido é: - -- `assets` como árvore hierárquica sintetizada de compile; -- nós intermediários como namespaces de compile; -- apenas folhas correspondentes a asset roots reais como valores terminais do tipo `Addressable`. - -Exemplo: - -- `assets.ui` pode ser apenas namespace; -- `assets.ui.borders` pode ser apenas namespace; -- `assets.ui.borders.panel` pode ser uma folha `Addressable`. - -Isso implica uma regra estrutural importante: - -- um asset terminal não pode ocupar um prefixo que também precise funcionar como namespace para outros assets. - -Exemplo inválido: - -- existir asset terminal em `assets/ui` -- e também existir asset terminal em `assets/ui/borders/panel` - -porque `assets.ui` não pode ser simultaneamente `Addressable` terminal e namespace. - -Operational note: - -- Studio should prevent creation of a new asset root when that path would collide with an existing asset terminal/namespace boundary. -- In practice, if an asset already exists at a path, Studio should not allow creating descendant assets under that same terminal path. -- Likewise, if descendants already exist, Studio should not allow creating a new asset at their prefix path. -- This must become an explicit Studio-side creation and move constraint, not just a compiler-side validation concern. - -Nesse modelo: - -- Studio mostra o address normatizado do asset, não um `asset_name` livre; -- packer não precisa mais ler nem escrever `asset_name` como variável operacional em `asset.json`; -- packer apenas reconhece, normaliza e publica o address derivado do root do asset sem persistir esse address como estado redundante em disco; -- `asset_id` permanece como primary key operacional estável do asset dentro do packer/runtime; -- o `address` passa a ser a identidade simbólica usada pelos compiladores para referenciar o asset em superfícies de autoria/compile; -- renomear ou mover diretório muda o address e quebra referências em compile time; -- tooling de rename/move pode existir para amortecer esse custo, mas a quebra deixa de ser ambígua e passa a ser explícita. - -Com esse contexto, o coração real da discussão de asset references não é mais “nome versus `asset_id`”. - -O ponto central passa a ser: - -- como PBS/SDK transforma um `address` autoral em `asset_id` operacional. - -Exemplo de shape ainda ilustrativo: - -```pbs -fn load(addressable: Addressable, bankRef: BankRef) -> LoadError -``` - -A dúvida principal não é o nome exato da API, mas o lugar da resolução: - -- a função do SDK recebe um símbolo/valor addressable e resolve internamente para `asset_id`; -- ou o próprio `Addressable` já é uma declaração/superfície sintetizada a partir do modelo vindo do backend, carregando a resolução necessária antes mesmo de entrar na função; -- ou ainda existe uma terceira forma híbrida em que a superfície autoral é simbólica, mas o lowering do compiler reescreve a chamada para a variante já normalizada em `asset_id`. - -Essa decisão é o núcleo arquitetural da agenda porque define: - -- o quanto a API pública do SDK continua “asset-address-first”; -- o quanto o compiler participa do lowering antes da chamada; -- e qual parte do sistema é owner da ponte entre identidade simbólica de compile e identidade operacional de runtime. - -O modelo que hoje parece mais coerente com PBS não é colocar essa resolução no corpo de um `declare service`. - -O desenho mais alinhado com a linguagem atual é: - -- `declare service` público continua sendo wrapper ergonômico normal; -- a metadata reservada de lowering fica no `declare host`, junto do próprio contrato host-backed; -- o compiler consome essa metadata ao baixar a chamada host-backed; -- o parâmetro marcado como asset-facing é resolvido de `Addressable` para `asset_id` durante o lowering. - -Exemplo ilustrativo: - -```pbs -declare host low_assets { - [Host(module = "assets", name = "preload", version = 1)] - [AssetLowering(param = 0)] - fn preload(addressable: Addressable, bank_id: int) -> LoadError; -} - -declare service Assets { - fn load(addressable: Addressable, bank: BankRef) -> LoadError { - return low_assets.preload(addressable, bank.id()); - } -} -``` - -Neste desenho: - -- o `service` não contém lógica especial de resolução; -- ele só encaminha a chamada de forma autoral/ergonômica; -- a assinatura host-backed explicita qual parâmetro sofre asset-lowering; -- o compiler sabe exatamente onde injetar o `asset_id` porque a própria assinatura `declare host` carrega o contrato; -- o lowering ocorre antes da forma final host/syscall, sem exigir placeholder artificial no corpo do `service`. - -Outro limite arquitetural precisa ficar explícito: - -- `asset` não é a superfície correta para endereçamento de recursos internos; -- o `asset` entra como unidade de instalação/publicação/carregamento; -- o acesso a internos só faz sentido depois que o conteúdo foi instalado em um `bank` de runtime; -- portanto, members internos pertencem à superfície do `bank` e não à superfície do `asset`. - -Isso impede uma confusão comum: - -- `assets.foo.bar` parece sugerir que `bar` é membro estável do asset em si; -- mas, neste modelo, `bar` só deve existir como símbolo depois que um `bank` específico expõe esse espaço de endereçamento. - -Como diferentes bancos têm semânticas distintas (`tile bank`, `sound bank`, e futuros bancos), o endereçamento de internos é family-specific e provavelmente pertence a uma spec transversal de runtime/banks, não à política básica de asset references. - -Tambem surge uma separação importante entre pipeline de compile e runtime packer: - -- o frontend PBS não deveria consultar o packer diretamente para descobrir a superfície de assets; -- o backend deve expor ao frontend uma `FESurfaceContext` mínima, derivada da autoridade operacional já existente no packer; -- essa `FESurfaceContext` não é o `PackerRuntimeSnapshot` nem transfere ownership da resolução para o frontend; -- o frontend usa a superfície para semântica e tooling locais, enquanto o backend continua responsável por validar o valor concreto e realizar o lowering final; -- essa mesma porta abre precedente para outras estruturas futuras entrarem no frontend por um contrato estável de surface, sem acoplá-lo diretamente a serviços externos. - -For the current agenda scope, the initial `FESurfaceContext` asset payload is intentionally small: - -- `List` - - `address` - - `asset_id` - -No richer asset payload is required yet for this policy discussion. -For PBS specifically, the frontend-facing fake/public type may also be named `Addressable`, as a homonymous language surface over the backend-owned `FESurfaceContext` payload. - -Outro recorte importante: - -- preload já existe e não é o objeto principal desta agenda; -- ele pode ser citado como contexto de integração; -- mas a discussão aqui não é “como preload funciona”; -- a discussão é “como asset references em PBS/SDK se resolvem até o ponto em que o caminho low-level já opera com `asset_id`”. - -## Open Questions - -- [ ] Quais outras estruturas além de assets podem, no futuro, seguir esse mesmo padrão de `FESurfaceContext` BE -> FE? - -## Options - -### Option A - Keep Surface Simple, Keep Runtime Rules Visible -- **Approach:** manter `asset_name` como referência de longo prazo e exigir consumo explícito de retornos quando houver valor materializado. -- **Pro:** modelo simples e pouco invasivo. -- **Con:** vaza custo operacional e detalhe de lowering para código-fonte; mantém fragilidade de rename e lookup tardio. -- **Maintainability:** baixa a média, porque o autor continua negociando diretamente com limites do backend/runtime. - -### Option B - Preserve Surface Ergonomics, Normalize in the Compiler -- **Approach:** manter superfície amigável (`asset_name`, `foo();`) e explicitar no compiler as normalizações necessárias, como lowering para identidade estável quando possível e descarte automático de resultados ignorados em `expression statement`. -- **Pro:** separa melhor autoria de protocolo executável; fica alinhado com a direção já adotada na família `19`. -- **Con:** aumenta responsabilidade do compiler e exige regras claras de quando a normalização pode ou não ocorrer. -- **Maintainability:** alta, porque o contrato passa a ficar onde ele deveria estar: no compiler e nas specs de lowering. - -### Option C - Introduce Rich Resource and Effect Surfaces -- **Approach:** criar abstrações mais fortes para recursos e resultados descartáveis, com novos tipos/superfícies na linguagem. -- **Pro:** potencialmente o modelo mais explícito e expressivo no longo prazo. -- **Con:** escopo bem maior; mistura redesign de linguagem com problemas que talvez possam ser resolvidos por lowering. -- **Maintainability:** incerta no curto prazo; só compensa se PBS quiser investir em abstrações novas, não apenas fechar lacunas atuais. - -## Discussion - -As duas agendas legadas apontam para a mesma direção recomendada: - -- preservar ergonomia de autoria; -- e mover o peso de normalização para o compiler. - -Isso não significa “magia implícita sem limite”. -Significa assumir, de forma normativa, que a superfície PBS pode ser mais estável e legível do que o protocolo executável final. - -O ponto central desta discussão é definir o limite dessa política: - -- quando PBS só normaliza lowering, -- e quando precisa criar uma abstração nova de linguagem. - -Com o contexto atual do packer, a pergunta fica mais precisa: - -- a autoria PBS deve continuar apontando para identificadores “humanos” sem owner operacional claro; -- ou deve consumir uma superfície simbólica derivada do snapshot coerente que o packer já mantém para o projeto? - -Se a segunda direção for adotada, o enum sintético de assets não é só ergonomia de editor. -Ele passa a ser a projeção tipada, em domínio PBS, de uma autoridade operacional já existente no packer. - -Isso desloca a discussão de “nome versus `asset_id`” para uma formulação melhor: - -- qual é a superfície simbólica correta para o jogo autorar; -- quem é owner dessa superfície; -- e como essa superfície é lowered para a identidade estável final. - -Também desloca uma segunda discussão para fora do escopo imediato: - -- a agenda atual pode fechar como o jogo referencia o `asset` enquanto unidade instalável/publicável; -- mas não deve colapsar isso com o addressing dos internos expostos por `banks`. - -O modelo mais correto parece ser: - -1. o jogo referencia um asset por uma superfície simbólica derivada da autoridade operacional do packer; -2. esse asset é instalado/publicado em um `bank` de runtime; -3. somente o `bank` passa a expor o espaço de endereçamento de recursos internos; -4. esse espaço de endereçamento é específico da família do banco e merece contrato próprio. - -Ao mesmo tempo, a discussão de root references passa a ter três frentes explícitas: - -1. `Studio` - - como o asset é exibido e selecionado na UI; - - se o address derivado do root substitui o `asset_name` como identidade visível; - - como impedir criação/move que faça um path atuar ao mesmo tempo como asset terminal e namespace; -2. `packer` - - como o snapshot operacional publica o address normatizado; - - se `asset.json` deixa de carregar `asset_name` como dado relevante; - - como moves/renames impactam o address e a invalidade de referências; -3. `compiler/pbs` - - como a projeção de assets entra no compile; - - como o frontend PBS consome essa projeção sem consultar o packer diretamente; - - como o lowering converte `assets.foo.bar` para identidade estável de runtime; - - em que ponto da superfície SDK/PBS a ponte `address -> asset_id` realmente acontece. - -No momento, a direção técnica mais forte para essa ponte é: - -- `Addressable` permanece como a surface simbólica de autoria do PBS; -- a `FESurfaceContext` mínima de assets carrega uma `List`, cujas entradas são compostas por `address` e `asset_id`; -- o frontend PBS usa um tipo fake homônimo `Addressable` para consumir essa surface de forma editorial e tipada; -- `declare host` asset-backed recebe metadata reservada como `[AssetLowering(param = N)]`; -- o backend continua validando o valor concreto e resolve esse parâmetro durante o lowering da chamada host-backed; -- `declare service` público permanece apenas como wrapper ergonômico sobre esse contrato. - -Additional convergence already accepted in this discussion: - -1. the v1 `FESurfaceContext` asset shape is limited to `List`; -2. ignored call results in `expression statement` follow a general lowering rule in v1 and SHOULD also emit a warning in the first version; -3. asset-facing references should be resolved at compile time whenever possible; no runtime-dynamic exception is currently required for this policy; -4. future editorial refinement may tune warning policy severity or suppression rules, but the baseline v1 direction already includes an `ignored values` warning. - -## Resolution - -Accepted on 2026-03-27. - -This agenda now resolves into two sibling decisions: - -1. `DEC-0005` for PBS asset address surface, `FESurfaceContext`, and backend-owned `Addressable` lowering. -2. `DEC-0006` for ignored values general lowering and warning policy. - -What is now locked: - -1. PBS asset-facing authoring is symbolic and based on `Addressable`. -2. The backend exposes a minimal `FESurfaceContext` with `List`. -3. The backend remains owner of final validation and lowering to runtime-facing `asset_id`. -4. Ignored values in `expression statement` follow a general lowering rule and emit a warning in v1. - -Direção recomendada por enquanto: - -1. tratar os dois temas como uma única discussão de política de surface-versus-lowering em PBS; -2. preferir a direção **Option B** como baseline; -3. tratar a política de asset references como discussão entre três camadas explícitas: - - `PackerRuntimeSnapshot` como autoridade operacional do conjunto de assets; - - superfície simbólica sintetizada para consumo em PBS; - - lowering compiler-owned para identidade estável de runtime; -4. explorar explicitamente a remoção de `asset_name` como variável operacional em favor do address derivado do root relativo em `assets/`; -5. tratar como requisito arquitetural que a projeção de assets chegue ao frontend PBS pelo backend/orquestração do compile, não por consulta direta do frontend ao packer; -6. tratar como questão central da agenda o ponto exato em que a superfície PBS/SDK converte `address` em `asset_id`; -7. fechar depois duas decisões derivadas: - - política de asset references para código de jogo, agora incluindo owner, forma do address canônico e contrato de entrada BE -> FE da projeção de assets; - - política de descarte de retorno ignorado em `expression statement`; -8. registrar explicitamente que addressing de recursos internos instalados em `banks` não pertence ao contrato básico de `asset references` e deve seguir discussão/spec própria, provavelmente em superfície transversal de runtime/banks; -9. evitar introduzir nova abstração de linguagem antes de esgotar a via de normalização no compiler e a via de superfície simbólica derivada da autoridade operacional já existente no packer. - -### Current preferred technical shape - -Sem fechar ainda a decision final, a forma técnica hoje preferida nesta agenda é: - -1. `declare host` asset-backed carrega `[AssetLowering(param = ...)]`; -2. o parâmetro marcado usa `Addressable` como surface autoral; -3. `declare service` público chama normalmente esse host wrapper; -4. o compiler resolve `address -> asset_id` ao baixar a chamada host-backed; -5. o runtime final continua vendo apenas o contrato operacional por `asset_id`. - -Related shape for the synthetic asset surface: - -1. `assets` is a hierarchical compile-time tree, not a flat enum; -2. intermediate nodes are namespaces only; -3. terminal asset leaves are typed as `Addressable`; -4. compile-time projection currently needs only `address` and `asset_id`; -5. Studio/runtime-tooling must reject terminal/namespace path collisions; -6. Studio should not allow creating or moving assets in ways that would make the same path act as both terminal asset and namespace prefix. - -Example: - -```pbs -declare host low_assets { - [Host(module = "assets", name = "preload", version = 1)] - [AssetLowering(param = 0)] - fn preload(addressable: Addressable, bank_id: int) -> LoadError; -} - -declare service Assets { - fn load(addressable: Addressable, bank: BankRef) -> LoadError { - return low_assets.preload(addressable, bank.id()); - } -} -``` - -In this example: - -- the author-facing API remains `Assets.load(addressable, bank)`; -- `low_assets.preload(...)` is the host-backed contract surface; -- `[AssetLowering(param = 0)]` tells the compiler that parameter `0` must be resolved from symbolic `Addressable` to operational `asset_id`; -- the service body remains ordinary PBS code; -- the special behavior lives in reserved lowering metadata on the `declare host` signature. diff --git a/discussion/workflow/decisions/DEC-0005-pbs-asset-address-surface-and-be-lowering.md b/discussion/workflow/decisions/DEC-0005-pbs-asset-address-surface-and-be-lowering.md deleted file mode 100644 index bd0241c2..00000000 --- a/discussion/workflow/decisions/DEC-0005-pbs-asset-address-surface-and-be-lowering.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -id: DEC-0005 -ticket: pbs-game-facing-asset-refs-and-call-result-discard -title: PBS Asset Address Surface and Backend-Lowered Addressable Resolution -status: accepted -created: 2026-03-27 -accepted: 2026-03-27 -agenda: AGD-0006 -plans: [PLN-0005, PLN-0006] -tags: [compiler, pbs, ergonomics, lowering, runtime, asset-identity, asset-surface, be-fe-contract] ---- - -## Context - -PBS precisava fechar a superfície author-facing de referência a assets depois que `DSC-0008` fixou a base low-level em `LowAssets` e no contrato runtime `asset_id + slot`. - -O ponto restante já não era o ABI low-level. -O ponto restante era como a autoria em PBS referencia assets de forma ergonômica sem reintroduzir lookup tardio por `asset_name`, sem acoplar o frontend diretamente ao packer, e sem mover para o frontend a ownership do lowering final. - -O estado aceito desta discussão também reconhece que: - -- o packer continua sendo a autoridade operacional do conjunto de assets; -- o backend do compiler expõe ao frontend apenas uma surface derivada, não o `PackerRuntimeSnapshot` bruto; -- o backend permanece owner da validação final do valor concreto e do lowering `address -> asset_id`. - -## Decision - -PBS SHALL adotar uma superfície author-facing baseada em `Addressable` e em addresses canônicos derivados do path relativo do asset root dentro de `assets/`. - -O shape canônico da autoria PBS SHALL seguir uma árvore hierárquica: - -- `assets` como namespace raiz; -- namespaces intermediários para prefixos estruturais; -- folhas terminais representando assets reais como valores `Addressable`. - -O address simbólico SHALL ser derivado do path relativo do asset root e SHALL substituir `asset_name` como identidade operacional de referência para compile-time asset lookup. - -O compiler backend SHALL expor ao frontend uma `FESurfaceContext` derivada da surface operacional do backend. -Para v1, essa `FESurfaceContext` SHALL carregar apenas: - -- `List` - -em que cada entrada `Addressable` contém: - -- `address` -- `asset_id` - -O frontend PBS MAY usar um tipo fake/public homônimo `Addressable` como surface editorial e de semântica local. -Esse tipo frontend-owned MUST NOT transferir ao frontend a responsabilidade de validação final ou de lowering operacional. - -O backend SHALL continuar responsável por: - -- validar o valor concreto referenciado no programa; -- resolver `address -> asset_id`; -- realizar o lowering final para o contrato low-level já fixado em `LowAssets`. - -PBS asset-facing APIs SHOULD permanecer simbólicas na surface pública. -Quando uma chamada exigir lowering asset-aware, o contrato host-backed SHALL carregar metadata reservada de lowering, e o backend SHALL usar essa metadata para reescrever a chamada para a forma operacional em `asset_id`. - -PBS MUST NOT consultar o packer diretamente a partir do frontend para descobrir assets visíveis. - -PBS MUST NOT tratar `asset` como superfície de addressing de membros internos carregados em runtime. -O contrato de members expostos por `bank` SHALL permanecer separado da política de asset references. - -Asset-facing references SHOULD be resolved at compile time whenever possible. -For the current policy, no runtime-dynamic exception is required. - -## Rationale - -Essa decisão preserva três fronteiras importantes ao mesmo tempo: - -1. ergonomia de autoria no source; -2. autoridade operacional no backend; -3. lowering final alinhado ao runtime já consolidado. - -Ela evita o pior dos dois extremos: - -- um frontend cego que não consegue oferecer semântica/tooling razoáveis; -- ou um frontend acoplado ao packer e responsável por decisões que pertencem ao backend. - -O uso de `Addressable` como nome em ambos os lados é aceitável porque: - -- no backend, ele representa a entrada da `FESurfaceContext`; -- no PBS, ele representa a surface editorial/fake type consumida pelo frontend. - -O nome é homônimo, mas a ownership continua explícita: - -- a surface chega do backend; -- a validação final e o lowering permanecem no backend. - -## Technical Specification - -### 1. Canonical Authoring Surface - -- PBS SHALL treat `assets` as a compile-time hierarchical namespace root. -- A terminal asset root SHALL map to a terminal `Addressable` leaf. -- Intermediate namespace nodes MUST NOT be treated as terminal assets. -- A terminal asset path MUST NOT also act as a namespace prefix for descendant assets. - -### 2. Canonical Address Identity - -- The canonical symbolic identity SHALL be the normalized address derived from the asset root path under `assets/`. -- `asset_name` MUST NOT remain the operational compile-time identity for asset lookup. -- Rename or move operations MAY change the canonical address and thereby invalidate compile-time references. - -### 3. Backend-To-Frontend Surface Contract - -- The backend SHALL expose a `FESurfaceContext` to the frontend. -- The v1 asset slice of that context SHALL be `List`. -- The frontend MAY use this surface for parsing-adjacent semantics, typing, diagnostics, and tooling. -- The frontend MUST NOT be treated as the canonical resolver of operational asset identity. - -### 4. Lowering Ownership - -- Asset-aware lowering metadata SHALL be carried on the host-backed declaration surface. -- The backend SHALL validate the referenced `Addressable` value against the backend-owned surface. -- The backend SHALL lower the symbolic asset reference to the runtime-facing `asset_id`. -- The resulting low-level call SHALL target the `LowAssets` contract already fixed by `DEC-0004`. - -### 5. Scope Boundary - -This decision covers: - -- symbolic asset references in PBS source; -- the minimal backend-to-frontend surface contract for assets; -- backend ownership of final validation and lowering. - -This decision does NOT cover: - -- bank-internal member addressing; -- richer future `FESurfaceContext` structures beyond assets; -- suppression or editorial warning policy for rename fragility; -- the low-level `LowAssets` ABI itself, already fixed elsewhere. - -## Constraints - -- The frontend MUST NOT query packer services directly for asset discovery. -- The backend MUST NOT expose the raw `PackerRuntimeSnapshot` as the frontend contract. -- The backend-to-frontend contract MUST remain small and explicitly extensible. -- The source-level `Addressable` surface MUST preserve the backend as owner of executable semantics. -- Any future richer asset APIs MUST still lower into backend-resolved `asset_id` before the final `LowAssets` host call. - -## Revision Log - -- 2026-03-27: Initial accepted decision from AGD-0006. -- 2026-03-27: Locked `FESurfaceContext` v1 asset shape to `List`. -- 2026-03-27: Locked backend ownership of final `Addressable` validation and lowering. diff --git a/discussion/workflow/decisions/DEC-0006-pbs-ignored-values-lowering-and-warning.md b/discussion/workflow/decisions/DEC-0006-pbs-ignored-values-lowering-and-warning.md deleted file mode 100644 index a1986aa7..00000000 --- a/discussion/workflow/decisions/DEC-0006-pbs-ignored-values-lowering-and-warning.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -id: DEC-0006 -ticket: pbs-game-facing-asset-refs-and-call-result-discard -title: PBS Ignored Values Lowering and Warning Policy -status: accepted -created: 2026-03-27 -accepted: 2026-03-27 -agenda: AGD-0006 -plans: [PLN-0007] -tags: [compiler, pbs, ergonomics, lowering, diagnostics, expression-statements, warnings] ---- - -## Context - -PBS ainda precisava fixar o comportamento de `expression statements` cujo valor produzido não é consumido. - -Sem essa decisão, a disciplina de stack do backend continua vazando para a surface do autor: - -- alguns callsites com retorno materializado ficam semanticamente ambíguos; -- a política de descarte pode ficar implícita demais ou inconsistente entre passes; -- o usuário não recebe feedback claro quando ignora um valor que a linguagem materializou. - -Essa discussão não exige uma exceção por API específica. -Ela exige uma regra geral de linguagem com lowering e diagnóstico previsíveis. - -## Decision - -PBS SHALL adotar uma regra geral para ignored values em `expression statement`. - -Quando uma expressão usada como statement produzir um valor materializado que não seja consumido, o compiler SHALL: - -1. lowerar explicitamente o descarte desse valor; -2. emitir um warning na v1. - -Essa política SHALL ser geral, e não uma exceção localizada para certos callsites ou certas superfícies de API. - -O warning inicial SHALL existir como baseline diagnóstica da linguagem. -Refinamentos futuros de severidade, suppressions ou subcategorias MAY acontecer depois, mas não bloqueiam esta decisão. - -## Rationale - -Essa regra resolve a tensão principal da agenda: - -- a autoria continua simples, porque o usuário pode escrever uma expressão como statement; -- o protocolo executável continua explícito, porque o compiler assume o descarte; -- a linguagem continua honesta, porque o usuário recebe um warning quando ignora um valor material. - -Isso é superior a duas alternativas piores: - -- exigir consumo explícito de todo valor sempre, empurrando ruído operacional para o source; -- ou descartar silenciosamente tudo, removendo feedback útil em situações potencialmente equivocadas. - -## Technical Specification - -### 1. General Rule - -- Any PBS `expression statement` that produces a materialized value and does not consume it SHALL trigger ignored-value handling. -- Ignored-value handling SHALL consist of: - - explicit lowering for value discard; - - a warning diagnostic. - -### 2. Scope - -- The rule SHALL apply generally across expression statements. -- The rule MUST NOT be restricted to asset-facing APIs, host-backed calls, or any single subsystem. -- The rule MAY apply equally to pure or impure expressions if the language surface materializes a value that is then ignored. - -### 3. Lowering Ownership - -- The compiler backend SHALL remain responsible for the executable lowering that discards the value. -- Frontend diagnostics MAY identify the situation earlier if architecture permits, but the normative executable behavior remains compiler-owned. - -### 4. Diagnostic Policy - -- The baseline v1 diagnostic level SHALL be warning. -- Future work MAY define suppression mechanisms, lint categories, escalation rules, or context-sensitive exemptions. -- No such refinement is required to consider this decision accepted. - -## Constraints - -- PBS MUST keep the rule general and easy to explain. -- PBS MUST NOT depend on backend stack discipline leaking into source-level author decisions. -- PBS MUST NOT require API-by-API bespoke ignored-value semantics as the baseline language policy. - -## Revision Log - -- 2026-03-27: Initial accepted decision from AGD-0006. -- 2026-03-27: Locked ignored values as a general lowering rule with warning severity in v1. diff --git a/discussion/workflow/plans/PLN-0005-pbs-asset-address-surface-spec-propagation.md b/discussion/workflow/plans/PLN-0005-pbs-asset-address-surface-spec-propagation.md deleted file mode 100644 index 110d9767..00000000 --- a/discussion/workflow/plans/PLN-0005-pbs-asset-address-surface-spec-propagation.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -id: PLN-0005 -ticket: pbs-game-facing-asset-refs-and-call-result-discard -title: Propagate DEC-0005 Asset Address Surface into Compiler, Packer, and Studio Specs -status: done -created: 2026-03-27 -completed: 2026-03-27 -tags: [compiler, pbs, packer, studio, specs, addressable, asset-identity, be-fe-contract] ---- - -## Objective - -Propagate `DEC-0005` into the normative documentation so PBS asset authoring, backend-owned `FESurfaceContext`, and the separation between `asset` and `bank` become explicit, cross-domain, and implementation-ready. - -## Background - -`DEC-0005` locks the symbolic authoring surface for assets around: - -- hierarchical `assets...` addressing; -- `Addressable` as the public/editorial PBS type shape; -- `FESurfaceContext` as a backend-owned contract delivered to the frontend; -- `List` as the v1 asset slice; -- backend-owned validation and lowering from symbolic address to runtime-facing `asset_id`; -- explicit separation between asset references and bank-internal addressing. - -The repository already documents: - -- packer ownership of `asset_id`; -- Studio ownership of asset workspace UX; -- PBS low-level runtime asset access through `LowAssets`. - -What is still missing is the normative bridge between these surfaces. - -## Scope - -### Included -- Update PBS language specs to define the symbolic asset address model and the backend-to-frontend contract. -- Update packer specs to state how the operational snapshot projects canonical asset addresses without turning `asset_name` into a first-class operational identity. -- Update Studio specs to state that UI-facing asset identity aligns with the canonical address surface and namespace collision rules. -- Add or update compiler-level specs so backend-owned asset lowering and `FESurfaceContext` ownership are normatively visible. - -### Excluded -- Implementing parser, semantic, lowering, or diagnostics code. -- Designing bank-internal member addressing. -- Defining richer future `FESurfaceContext` slices beyond assets. -- Introducing rename-fragility warnings or LSP-only UX refinements. - -## Execution Steps - -### Step 1 - Update PBS Normative Surface Documents - -**What:** -Document the symbolic PBS surface for asset references and the `Addressable` model. - -**How:** -Revise the PBS specs so they state: - -- `assets` is a compile-time namespace root; -- leaves correspond to terminal `Addressable` values; -- the canonical symbolic identity is the normalized asset-root-derived address; -- `asset_name` is not the operational compile-time identity; -- the PBS frontend may use a fake/editorial `Addressable` type while the backend remains the owner of executable semantics. - -**File(s):** -- `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md` -- `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md` -- `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md` -- `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md` - -### Step 2 - Update Backend Contract and Lowering Specs - -**What:** -Make the backend-owned `FESurfaceContext` and asset-lowering ownership explicit in compiler-wide specs. - -**How:** -Add or revise sections that state: - -- the frontend receives a minimal backend-derived surface, not the raw packer snapshot; -- v1 assets arrive as `List`; -- backend validation and final lowering ownership remain backend-only; -- symbolic asset references lower into the already-accepted `LowAssets` contract before runtime execution. - -**File(s):** -- `docs/specs/compiler/18. Standard Library Surface Specification.md` -- `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md` -- optional conformance/matrix sync if needed: `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md` - -### Step 3 - Update Packer And Studio Domain Specs - -**What:** -Align packer and Studio domain specs with the symbolic address model and namespace rules. - -**How:** -Revise the specs so they state: - -- packer remains owner of operational asset identity and derives canonical addresses from asset roots; -- `asset_name` is not required as an operational registry field; -- Studio should expose canonical address identity in UX where appropriate; -- Studio must prevent terminal-vs-namespace collisions on asset root creation and moves. - -**File(s):** -- `docs/specs/packer/2. Workspace, Registry, and Asset Identity Specification.md` -- `docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md` -- `docs/specs/studio/4. Assets Workspace Specification.md` - -### Step 4 - Cross-Check Decision Boundaries - -**What:** -Verify that the edited specs preserve the intended scope split between `DEC-0004`, `DEC-0005`, and bank-specific addressing. - -**How:** -Check that: - -- `DEC-0004` still owns only the low-level `LowAssets` ABI; -- `DEC-0005` owns the symbolic authoring and backend-owned surface contract; -- no updated document accidentally defines bank-internal member addressing or future richer `FESurfaceContext` slices. - -**File(s):** -- `discussion/workflow/decisions/DEC-0004-pbs-low-level-asset-manager-surface.md` if restored for reference, otherwise use `discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md` -- `discussion/workflow/decisions/DEC-0005-pbs-asset-address-surface-and-be-lowering.md` - -## Test Requirements - -### Unit Tests -- None required for the editorial plan itself. - -### Integration Tests -- None required for the editorial plan itself. - -### Manual Verification -- Read updated specs together and verify the same terminology is used for `Addressable`, canonical address, `asset_id`, and `FESurfaceContext`. -- Verify no document reintroduces `asset_name` as the normative compile-time identity. -- Verify no document collapses `asset` references with bank-internal addressing. - -## Acceptance Criteria - -- [ ] PBS specs describe hierarchical asset addressing and `Addressable` as the symbolic authoring surface. -- [ ] Compiler specs state that the backend exposes a minimal `FESurfaceContext` and retains final validation/lowering ownership. -- [ ] Packer specs state that canonical asset addresses are derived operationally without promoting `asset_name` back to first-class identity. -- [ ] Studio specs state the namespace-collision rule for asset root creation and moves. -- [ ] Updated docs preserve the scope boundary between low-level `LowAssets` ABI and symbolic asset references. - -## Dependencies - -- `DEC-0005-pbs-asset-address-surface-and-be-lowering` -- Existing `DEC-0004` low-level `LowAssets` contract - -## Risks - -- Cross-domain wording may drift if compiler, packer, and Studio specs are updated independently. -- Over-documenting future `FESurfaceContext` expansion now would make the contract harder to keep stable. -- It is easy to accidentally reintroduce `asset_name` as an editorial convenience unless the operational/authoring distinction stays explicit. diff --git a/discussion/workflow/plans/PLN-0006-pbs-asset-address-surface-implementation.md b/discussion/workflow/plans/PLN-0006-pbs-asset-address-surface-implementation.md deleted file mode 100644 index a6c56c80..00000000 --- a/discussion/workflow/plans/PLN-0006-pbs-asset-address-surface-implementation.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -id: PLN-0006 -ticket: pbs-game-facing-asset-refs-and-call-result-discard -title: Implement DEC-0005 Addressable Surface, FESurfaceContext, and Backend Asset Lowering -status: done -created: 2026-03-27 -completed: 2026-03-27 -tags: [compiler, pbs, implementation, addressable, lowering, be-fe-contract, asset-identity] ---- - -## Objective - -Implement the executable and semantic infrastructure required by `DEC-0005` so PBS can consume a backend-owned asset surface, type symbolic asset references as `Addressable`, and lower them to runtime-facing `asset_id` before the final `LowAssets` call path. - -## Background - -`DEC-0005` locks: - -- `assets...` as the symbolic compile-time surface; -- `Addressable` as the PBS editorial/public type shape; -- `FESurfaceContext` as a backend-owned contract delivered to the frontend; -- `List` as the v1 asset payload; -- backend-owned validation and final lowering to `asset_id`. - -The repository already has: - -- `LowAssets` in stdlib and tests; -- `FrontendPhaseContext` as the frontend request surface; -- `PBSFrontendPhaseService` as the main orchestration point for PBS frontend compilation; -- executable lowering infrastructure that can already carry host-binding metadata. - -What is missing is the symbolic asset surface and the backend-owned path from frontend-visible `Addressable` to low-level `asset_id`. - -## Scope - -### Included -- Extend frontend API models to carry a minimal asset `FESurfaceContext`. -- Thread the new surface through PBS frontend compilation entrypoints. -- Introduce or adapt PBS semantic handling for `Addressable` and asset namespace resolution. -- Add backend-owned validation and lowering hooks for asset-aware callsites. -- Add or update tests for compile surface ingestion, semantic acceptance, and lowering behavior. - -### Excluded -- Designing richer future `FESurfaceContext` slices beyond assets. -- Implementing bank-internal member addressing. -- Designing rename/move tooling or LSP UX beyond what is needed for compile surface wiring. -- Changing the already accepted low-level `LowAssets` ABI. - -## Execution Steps - -### Step 1 - Add Frontend API Surface Models For Assets - -**What:** -Introduce the minimal backend-to-frontend asset surface contract. - -**How:** -Add new API models so the frontend request context can carry: - -- a `FESurfaceContext`; -- an asset slice represented as `List`; -- `Addressable(address, asset_id)` entries. - -Keep the contract intentionally small and backend-owned. -Avoid leaking raw packer snapshot structures into the frontend API. - -**File(s):** -- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/messages/FrontendPhaseContext.java` -- new companion model files under `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/messages/` -- tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/services/` - -### Step 2 - Thread FESurfaceContext Through PBS Frontend Orchestration - -**What:** -Make `PBSFrontendPhaseService` and related assembly services consume the backend-provided asset surface. - -**How:** -Propagate the new context data through the PBS frontend pipeline so semantic and lowering phases can read the v1 asset list without querying packer services directly. -Keep ownership clear: the frontend consumes the surface, but the backend still owns final validation and lowering. - -**File(s):** -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/PBSFrontendPhaseService.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/PbsModuleAssemblyService.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/PbsImportedSemanticContextService.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/services/PBSFrontendPhaseServiceTest.java` - -### Step 3 - Implement PBS Symbolic Addressable Semantics - -**What:** -Teach PBS semantics and binding layers how to recognize the symbolic asset surface and treat terminal asset leaves as `Addressable`. - -**How:** -Add semantic support for: - -- hierarchical `assets...` namespace resolution; -- terminal asset leaves typed as `Addressable`; -- rejection of unresolved or structurally invalid asset references; -- preventing intermediate namespace nodes from being treated as terminal addressable values. - -Do not move operational validation ownership out of the backend; semantic handling should remain a frontend-facing interpretation of backend-provided surface data. - -**File(s):** -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsNamespaceBinder.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowExpressionAnalyzer.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowStructuralExpressionAnalyzer.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsSemanticsErrors.java` -- parser/AST files only if the current source form requires parser changes -- tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/` - -### Step 4 - Add Backend-Owned Asset Lowering Hooks - -**What:** -Implement final backend validation and lowering from symbolic `Addressable` references to runtime-facing `asset_id`. - -**How:** -Extend lowering metadata and executable lowering so asset-aware callsites can: - -- identify which argument is asset-facing; -- validate that the referenced value maps to a backend-owned `Addressable`; -- lower the symbolic reference to the numeric `asset_id`; -- continue into the already-existing `LowAssets` low-level host path. - -Keep this logic backend-owned rather than embedding operational resolution inside frontend-only semantics or service wrapper bodies. - -**File(s):** -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsReservedMetadataExtractor.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableLoweringContext.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableBodyLowerer.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableCallsiteEmitter.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableMetadataIndexFactory.java` -- tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/` - -### Step 5 - Add Conformance And Regression Coverage - -**What:** -Pin the new contract with tests that cover both frontend surface consumption and backend lowering behavior. - -**How:** -Add tests that prove: - -- `FESurfaceContext` asset data is visible to the PBS frontend; -- symbolic asset references resolve only when present in the backend-provided list; -- invalid namespace collisions or unresolved terminal references are rejected deterministically; -- valid asset-facing callsites lower to the same low-level `asset_id` path expected by `LowAssets`. - -**File(s):** -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/services/PBSFrontendPhaseServiceTest.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsFrontendCompilerTest.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsGateUStdlibCompileTest.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsGateUSdkInterfaceConformanceTest.java` - -## Test Requirements - -### Unit Tests -- Semantics tests for `Addressable` terminals, intermediate namespace rejection, and unresolved symbolic asset references. -- Metadata/lowering tests for asset-aware callsites and `asset_id` substitution. - -### Integration Tests -- `PBSFrontendPhaseService` tests that compile a project with a supplied `FESurfaceContext`. -- End-to-end frontend compilation tests that import the low-level `@sdk:asset` surface and confirm the final lowering path stays aligned with `LowAssets`. - -### Manual Verification -- Inspect the new frontend API types and verify they expose only `List` for v1. -- Verify no frontend code path queries packer services directly. -- Re-run targeted PBS frontend test suites after implementation. - -## Acceptance Criteria - -- [ ] `FrontendPhaseContext` or equivalent frontend API entrypoints can carry a backend-owned asset `FESurfaceContext`. -- [ ] PBS can interpret terminal symbolic asset references as `Addressable` values using backend-provided surface data. -- [ ] Backend lowering validates symbolic asset references and resolves them to runtime-facing `asset_id`. -- [ ] Valid asset-facing calls still lower into the `LowAssets` contract from `DEC-0004`. -- [ ] Missing or structurally invalid symbolic asset references fail deterministically with stable diagnostics. - -## Dependencies - -- `DEC-0005-pbs-asset-address-surface-and-be-lowering` -- Existing `DEC-0004` low-level asset surface -- Existing frontend request and lowering infrastructure in `prometeu-compiler` - -## Risks - -- The current frontend API may need more structural changes than expected to pass backend-owned surface data cleanly. -- If `Addressable` is introduced inconsistently across semantics and lowering, the frontend may accept states the backend cannot lower. -- Mixing frontend convenience with backend ownership could accidentally reintroduce direct packer coupling unless boundaries are enforced carefully. diff --git a/discussion/workflow/plans/PLN-0007-pbs-ignored-values-warning-implementation.md b/discussion/workflow/plans/PLN-0007-pbs-ignored-values-warning-implementation.md deleted file mode 100644 index d8735526..00000000 --- a/discussion/workflow/plans/PLN-0007-pbs-ignored-values-warning-implementation.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -id: PLN-0007 -ticket: pbs-game-facing-asset-refs-and-call-result-discard -title: Implement DEC-0006 Ignored Values Lowering and Warning -status: done -created: 2026-03-27 -completed: 2026-03-27 -tags: [compiler, pbs, implementation, diagnostics, lowering, expression-statements, warnings] ---- - -## Objective - -Implement `DEC-0006` so ignored materialized values in PBS `expression statement` positions are always explicitly discarded during lowering and also emit a warning in v1. - -## Background - -`DEC-0006` locks a general language rule: - -- `expression statement` forms that produce a materialized value must not silently leak backend stack discipline into source semantics; -- the compiler must lower explicit discard behavior; -- the compiler must also emit a warning in v1. - -The current lowering path already lowers expression statements as plain expression evaluation. -The existing executable stack analyzer already understands `POP`, but expression-statement lowering does not yet make discard behavior explicit. - -## Scope - -### Included -- Update PBS specs and diagnostics docs for ignored-value behavior. -- Add a warning diagnostic contract for ignored materialized values. -- Implement explicit discard lowering for expression statements that leave a materialized value. -- Add frontend and lowering tests covering both the warning and the discard behavior. - -### Excluded -- Suppression syntax, lint categories, or configurable severity policy. -- API-specific special cases for ignored values. -- Non-PBS frontend work. - -## Execution Steps - -### Step 1 - Propagate The Rule Into PBS Specs - -**What:** -Make the ignored-values rule explicit in PBS normative docs. - -**How:** -Update the specs so they state: - -- `expression statement` may produce a value; -- if that value is materialized and not consumed, the compiler must lower an explicit discard; -- the v1 diagnostic policy is warning. - -**File(s):** -- `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md` -- `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md` -- `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md` -- optional compiler-wide sync if needed: `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md` - -### Step 2 - Add A Stable Warning Diagnostic Contract - -**What:** -Define the PBS diagnostic identity for ignored values. - -**How:** -Add a stable warning code and wire it through the diagnostics contract so tests can assert identity, phase, severity, and attribution. - -**File(s):** -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsSemanticsErrors.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsDiagnosticsContractTest.java` -- semantics tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/` - -### Step 3 - Emit Ignored-Value Warnings During Semantics - -**What:** -Detect ignored materialized values at the statement-analysis boundary and emit the new warning. - -**How:** -Use the existing flow/statement analyzers to identify expression statements whose resulting type is materialized rather than unit-like, and emit the warning without blocking lowering. - -**File(s):** -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowBodyAnalyzer.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowStatementAnalyzer.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowExpressionAnalyzer.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/PbsSemanticsOptionalResultTest.java` -- new focused test file if needed for ignored-value warnings - -### Step 4 - Lower Explicit Discard Operations - -**What:** -Make expression-statement lowering explicitly discard ignored values rather than implicitly leaving them to backend behavior. - -**How:** -Update executable lowering so expression statements that produce materialized values emit the appropriate discard instruction sequence, then verify stack accounting remains correct. - -**File(s):** -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableBodyLowerer.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableStackAnalyzer.java` -- lowering tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/` - -### Step 5 - Add Regression And Contract Coverage - -**What:** -Pin both the warning and the executable discard behavior with tests. - -**How:** -Add tests that cover: - -- pure expression statements returning a value; -- call expressions returning a value that is ignored; -- unit-returning expression statements that must not warn; -- executable lowering shape and stack behavior after explicit discard insertion. - -**File(s):** -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsFrontendCompilerTest.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/services/PBSFrontendPhaseServiceTest.java` - -## Test Requirements - -### Unit Tests -- Semantics tests for warning emission on ignored non-unit values. -- Negative tests ensuring unit-valued expression statements do not warn. -- Lowering tests verifying discard instruction emission and stack balance. - -### Integration Tests -- End-to-end frontend compilation tests showing warning emission without turning the program into an error. -- Targeted pipeline tests proving explicit discard lowering survives later executable lowering phases. - -### Manual Verification -- Inspect diagnostics and confirm ignored-value reports are warnings, not errors. -- Inspect lowered instruction streams for representative ignored-value cases and confirm explicit discard behavior. -- Re-run targeted PBS frontend and lowering test suites. - -## Acceptance Criteria - -- [ ] PBS emits a stable warning diagnostic for ignored materialized values in expression statements. -- [ ] Unit-like expression statements do not emit the ignored-value warning. -- [ ] Executable lowering emits explicit discard behavior for ignored materialized values. -- [ ] Stack analysis remains valid after the discard instruction path is added. -- [ ] The rule applies generally and is not limited to one API family. - -## Dependencies - -- `DEC-0006-pbs-ignored-values-lowering-and-warning` -- Existing PBS flow semantics and executable lowering infrastructure - -## Risks - -- The current semantics/lowering split may make it easy to warn in one place but forget to lower explicit discard in another. -- If the implementation does not distinguish unit-like from materialized values carefully, it may over-warn or under-warn. -- Later severity/suppression refinements may require reshaping the diagnostics API, so the first version should keep the contract minimal and stable. diff --git a/discussion/workflow/plans/PLN-0008-pbs-assetlowering-host-metadata-and-callsite-rewrite.md b/discussion/workflow/plans/PLN-0008-pbs-assetlowering-host-metadata-and-callsite-rewrite.md deleted file mode 100644 index 477eefd1..00000000 --- a/discussion/workflow/plans/PLN-0008-pbs-assetlowering-host-metadata-and-callsite-rewrite.md +++ /dev/null @@ -1,196 +0,0 @@ ---- -id: PLN-0008 -ticket: pbs-game-facing-asset-refs-and-call-result-discard -title: Implement Mandatory AssetLowering Host Metadata and Backend Callsite Rewrite -status: done -created: 2026-03-27 -completed: 2026-03-27 -tags: [compiler, pbs, implementation, assetlowering, host-metadata, backend-lowering, correction] ---- - -## Objective - -Complete the missing normative part of `DEC-0005` by implementing mandatory host-backed `AssetLowering` metadata and using it to rewrite `Addressable` arguments into runtime-facing `asset_id` at backend callsite lowering time. - -## Background - -`DEC-0005` did not only require: - -- `FESurfaceContext = List`, -- symbolic `assets...` semantics, -- and backend ownership of final validation. - -It also normatively locked a second requirement: - -- asset-aware lowering metadata must live on the host-backed declaration surface; -- the backend must use that metadata to identify which host parameter is asset-facing; -- and host-backed lowering must rewrite the `Addressable` argument to operational `asset_id` before the final `LowAssets` path. - -`PLN-0006` implemented the symbolic surface and direct symbolic-to-`asset_id` expression lowering, but it did not implement: - -- reserved attribute `[AssetLowering(param = N)]`, -- reserved-metadata propagation for host bindings, -- host-signature validation for asset-lowered parameters, -- or host-callsite rewriting driven by parameter metadata. - -This plan exists to correct that gap without reinterpreting `DEC-0005`. - -## Scope - -### Included -- Add `AssetLowering(param = N)` as a PBS reserved attribute on host-backed signatures. -- Validate the attribute shape and its admissible target surface. -- Extend backend host-binding metadata to carry asset-lowering parameter information. -- Rewrite host call lowering so asset-facing parameters consume symbolic `Addressable` values and lower them to `asset_id` according to host metadata. -- Align tests and specs so the normative path is explicit and covered. -- Correct any now-misleading tests or implementation shortcuts introduced by `PLN-0006`. - -### Excluded -- Redesign of `DEC-0005`. -- Changes to the `LowAssets` ABI already fixed by `DEC-0004`. -- Generalization to non-asset metadata families beyond the exact `AssetLowering` rule. -- Runtime-dynamic asset lookup exceptions. - -## Execution Steps - -### Step 1 - Add Reserved Attribute Surface For AssetLowering - -**What:** -Introduce `[AssetLowering(param = N)]` as a normative reserved attribute on host-backed callable surfaces. - -**How:** -Extend the PBS reserved attribute extractor and declaration validation so: - -- `AssetLowering` is recognized as reserved metadata; -- it is admitted only on supported host-backed callable declarations; -- `param` is mandatory and must be a valid zero-based parameter index; -- the targeted parameter must match the `Addressable` author-facing contract required by `DEC-0005`; -- duplicate or malformed declarations fail deterministically. - -**File(s):** -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsReservedMetadataExtractor.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsDeclarationSemanticsValidator.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsSemanticsErrors.java` -- tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/` - -### Step 2 - Propagate AssetLowering Through Reserved Metadata - -**What:** -Make host binding metadata carry the asset-lowering contract instead of relying on implicit expression-level lowering. - -**How:** -Extend `IRReservedMetadata.HostMethodBinding` or the equivalent host-binding metadata shape so each binding can expose: - -- whether asset lowering is required; -- which parameter index is asset-facing. - -Update metadata construction, merging, indexing, and any downstream readers so the information survives all backend-facing frontend phases. - -**File(s):** -- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRReservedMetadata.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsReservedMetadataExtractor.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableLoweringModels.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableMetadataIndexFactory.java` -- metadata conformance tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/` - -### Step 3 - Rewrite Host Calls Using AssetLowering Metadata - -**What:** -Move final `Addressable -> asset_id` host-argument rewriting into the backend-owned host call path mandated by `DEC-0005`. - -**How:** -Update executable lowering so: - -- host callsites inspect `AssetLowering(param = N)` metadata from the resolved host binding; -- the backend validates that the selected argument is a terminal backend-known `Addressable`; -- the selected argument is lowered to operational `asset_id`; -- non-asset-facing arguments are lowered normally; -- the final emitted host call matches the already accepted `LowAssets` runtime path. - -This step must remove reliance on the current shortcut where symbolic asset references are lowered generically without host-parameter ownership. - -**File(s):** -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableBodyLowerer.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableCallsiteEmitter.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableLoweringContext.java` -- related lowering metadata/index files -- targeted lowering tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/` - -### Step 4 - Realign Symbolic Expression Lowering With The Host-Metadata Contract - -**What:** -Correct the partial implementation from `PLN-0006` so symbolic asset expressions support the normative host-metadata path instead of bypassing it. - -**How:** -Review the current direct lowering of `assets...` expressions and keep only the behavior that remains valid under `DEC-0005`. - -At minimum: - -- standalone symbolic `Addressable` semantics must remain correct; -- host-backed `AssetLowering` callsites must no longer depend on an implicit generic shortcut; -- tests that previously “passed” through direct expression lowering must be updated to assert the host-metadata path explicitly. - -If any `PLN-0006` behavior contradicts `DEC-0005`, correct the code and the tests rather than preserving the shortcut. - -**File(s):** -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsFrontendCompilerTest.java` -- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/services/PBSFrontendPhaseServiceTest.java` - -### Step 5 - Propagate And Pin The Contract In Specs And Tests - -**What:** -Ensure the normative wording and regression coverage now match the corrected implementation. - -**How:** -Update specs and tests so they explicitly cover: - -- `AssetLowering(param = N)` as mandatory host-backed metadata for asset-aware lowering; -- the backend-owned rewrite from symbolic `Addressable` to operational `asset_id`; -- rejection of malformed attribute usage and invalid parameter targeting; -- a representative `LowAssets`-aligned host call path using the metadata-bearing surface. - -**File(s):** -- `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md` -- `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md` -- `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md` -- `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md` -- targeted PBS frontend/compiler tests - -## Test Requirements - -### Unit Tests -- Reserved-attribute tests for valid and invalid `AssetLowering(param = N)` usage. -- Metadata tests proving host bindings preserve the asset-lowering parameter index. -- Negative tests for duplicate, malformed, or out-of-range `AssetLowering` declarations. - -### Integration Tests -- End-to-end PBS frontend compilation tests where a host-backed asset API uses `Addressable` plus `[AssetLowering(param = N)]`. -- Lowering tests proving the backend rewrites the marked argument to `asset_id` before the final host call. -- Regression tests proving `LowAssets`-aligned callsites still lower correctly after removing the shortcut path. - -### Manual Verification -- Inspect extracted reserved metadata and verify `AssetLowering` is carried on the host binding. -- Inspect lowered instruction streams for an asset-aware host call and verify the asset-facing argument becomes `asset_id`. -- Confirm malformed host metadata fails with deterministic source-facing diagnostics. - -## Acceptance Criteria - -- [ ] PBS supports `[AssetLowering(param = N)]` as a validated reserved attribute on the correct host-backed surface. -- [ ] Host binding metadata preserves the asset-lowering parameter contract through backend lowering preparation. -- [ ] Backend host-call lowering uses the metadata to rewrite the selected `Addressable` argument into runtime-facing `asset_id`. -- [ ] The final asset-aware host path remains aligned with `LowAssets` and no longer depends on a generic shortcut that bypasses host metadata. -- [ ] Tests and specs explicitly cover the normative `AssetLowering` path from `DEC-0005`. - -## Dependencies - -- `DEC-0005-pbs-asset-address-surface-and-be-lowering` -- `DEC-0004` low-level `LowAssets` contract -- existing `PLN-0006` implementation as the correction baseline - -## Risks - -- The current direct symbolic lowering path may overlap with the normative host-metadata path and require careful removal or restriction. -- Extending host metadata may require synchronized updates across multiple compiler layers, increasing the chance of partial propagation if done carelessly. -- If tests keep asserting the shortcut path instead of the normative path, the repository may regress into the same discrepancy again.