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
@@ -2,10 +2,10 @@
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: open
status: accepted
created: 2026-03-27
resolved:
decision:
resolved: 2026-03-27
decision: DEC-0005, DEC-0006
tags: [compiler, pbs, ergonomics, lowering, runtime, asset-identity, expression-statements]
---
@@ -46,9 +46,10 @@ O novo ponto importante é que, para referências a asset, essa “superfície a
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;
- Studio como host capaz de sintetizar uma superfície tipada a partir desse snapshot;
- PBS como consumidor dessa superfície simbólica;
- compiler como responsável por lowerar essa superfície para identidade estável de runtime.
- 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:
@@ -174,19 +175,22 @@ Isso impede uma confusão comum:
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.
Também surge uma separação importante entre pipeline de compile e runtime packer:
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;
- a estrutura simbólica de assets deve chegar ao compile como dado já preparado na borda backend/orquestradora;
- isso significa que o backend de compile precisa transportar para o frontend PBS uma projeção dos assets visíveis;
- essa mesma porta abre precedente para outras estruturas futuras entrarem no frontend via request de compile, em vez de acoplá-lo a serviços externos em tempo de frontend.
- 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 minimum compile projection is intentionally small:
For the current agenda scope, the initial `FESurfaceContext` asset payload is intentionally small:
- `address`
- `asset_id`
- `List<Addressable>`
- `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:
@@ -197,33 +201,7 @@ Outro recorte importante:
## Open Questions
- [ ] Referências a asset devem permanecer nomeadas na superfície PBS, mesmo se o lowering resolver parte delas para identidade estável?
- [ ] A superfície simbólica de asset em PBS deve ser derivada explicitamente do `PackerRuntimeSnapshot` mantido pelo packer para o projeto ativo?
- [ ] O enum ou namespace sintético derivado de assets pertence ao Studio como host/tooling, ao packer como serviço, ou a uma fronteira compartilhada formalizada entre ambos?
- [ ] `asset_name` deve ser removido como variável operacional e substituído pelo address normatizado derivado do root do asset?
- [ ] Studio deve adotar esse address como identidade primária visível ao usuário em vez de exibir um nome livre fornecido pelo autor?
- [ ] O address simbólico canônico deve ser derivado do path relativo em `assets/` segmentado como namespace (`assets.foo.bar.baz`)?
- [ ] A superfície `assets...` deve ser normatizada como árvore hierárquica com namespaces intermediários e folhas terminais `Addressable`, em vez de enum flat?
- [ ] A plataforma deve proibir colisões onde um asset terminal também precisaria atuar como namespace-prefixo de outros assets?
- [ ] A projeção de assets consumida pelo frontend PBS deve entrar pelo backend no request de compile, em vez de o frontend consultar diretamente o packer?
- [ ] Quais outras estruturas além de assets podem, no futuro, seguir esse mesmo padrão de entrada BE -> FE no compile?
- [ ] A resolução de `address` para `asset_id` acontece dentro da função pública do SDK, no tipo/símbolo sintetizado (`Addressable` ou equivalente), ou no lowering do compiler antes da chamada?
- [ ] Se existir um tipo público como `Addressable`, ele representa só a superfície simbólica autoral ou já embute a identidade operacional necessária para a chamada low-level?
- [ ] A API pública do SDK deve permanecer centrada em argumentos simbólicos (`address`, `Addressable`) mesmo quando o backend final consome `asset_id`?
- [ ] O compiler deve reescrever chamadas de SDK asset-facing para formas normalizadas por `asset_id`, mantendo a superfície autoral intacta?
- [ ] Como separar, normativamente, a superfície de referência ao `asset` da futura superfície de endereçamento dos members expostos por um `bank` após instalação?
- [ ] Esse contrato de members expostos por `bank` deve viver em spec transversal (`vm-arch`/runtime surface) em vez de ficar embutido na política de asset references do PBS?
- [ ] O descarte de retorno ignorado deve ser uma regra geral de `expression statement`, ou uma exceção localizada para certos callsites?
- [ ] Até onde PBS quer empurrar “surface ergonomics, compiler normalization” como princípio geral para APIs de jogo?
- [ ] Quais casos precisam continuar dinâmicos em runtime e portanto não podem ser lowered agressivamente em compile time?
- [ ] Devemos publicar warnings opcionais para retorno ignorado ou rename-fragile asset references, ou isso fica fora do escopo inicial?
Open questions still considered active after the current discussion:
- [ ] Qual é o shape mínimo e normativo do modelo de assets entregue ao compile/LSP além de `address` e `asset_id`, se algum enriquecimento futuro se mostrar necessário?
- [ ] Quais outras estruturas além de assets podem, no futuro, seguir esse mesmo padrão de entrada BE -> FE no compile?
- [ ] O descarte de retorno ignorado deve virar warning geral de `expression statement` com valor, ou warning apenas para superfícies específicas?
- [ ] Quais casos, além de disponibilidade em runtime, realmente precisam permanecer dinâmicos e fora da resolução estática baseada no snapshot?
- [ ] Quais outras estruturas além de assets podem, no futuro, seguir esse mesmo padrão de `FESurfaceContext` BE -> FE?
## Options
@@ -304,13 +282,36 @@ Ao mesmo tempo, a discussão de root references passa a ter três frentes explí
No momento, a direção técnica mais forte para essa ponte é:
- `Addressable` permanece como superfície simbólica de autoria;
- `Addressable` permanece como a surface simbólica de autoria do PBS;
- a `FESurfaceContext` mínima de assets carrega uma `List<Addressable>`, 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 compiler resolve esse parâmetro durante o lowering da chamada host-backed;
- 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<Addressable(address, asset_id)>`;
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<Addressable(address, asset_id)>`.
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;