asset addressable PBS surface

This commit is contained in:
2026-03-27 16:58:20 +00:00
parent afd59d04f4
commit 124c6d078e
9 changed files with 785 additions and 44 deletions
@@ -0,0 +1,147 @@
---
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.
@@ -0,0 +1,88 @@
---
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.