asset addressable PBS surface
This commit is contained in:
+43
-42
@@ -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;
|
||||
|
||||
Reference in New Issue
Block a user