148 lines
6.6 KiB
Markdown
148 lines
6.6 KiB
Markdown
---
|
|
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<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.
|