prometeu-studio/discussion/workflow/decisions/DEC-0005-pbs-asset-address-surface-and-be-lowering.md

id	ticket	title	status	created	accepted	agenda	plans	tags
DEC-0005	pbs-game-facing-asset-refs-and-call-result-discard	PBS Asset Address Surface and Backend-Lowered Addressable Resolution	accepted	2026-03-27	2026-03-27	AGD-0006	PLN-0005 PLN-0006	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<Addressable>

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<Addressable(address, asset_id)>.
• 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<Addressable(address, asset_id)>.
• 2026-03-27: Locked backend ownership of final Addressable validation and lowering.