--- 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.