prometeu-studio/discussion/workflow/agendas/AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0006	pbs-game-facing-asset-refs-and-call-result-discard	PBS Game-Facing Asset References and Ignored Call Result Lowering	open	2026-03-27			compiler pbs ergonomics lowering runtime asset-identity expression-statements

Pain

PBS ainda tem dois atritos abertos na fronteira entre ergonomia de código de jogo e lowering executável:

1. referências a assets continuam centradas em asset_name no código-fonte, enquanto packer/runtime já convergiram para identidade estável por asset_id;
2. expression statements com retorno materializado ainda precisam de política explícita de descarte, para não vazar regra de stack do backend para o código de usuário.

Os dois temas pertencem à mesma discussão porque tratam da mesma pergunta arquitetural:

Como PBS deve preservar uma superfície de autoria natural sem sacrificar determinismo no lowering e no runtime?

Context

Esta agenda consolida dois tópicos legados do domínio PBS:

• 18.4. Asset References in Game Code - Names vs Compile-Time Lowering
• 18.5. Ignored Call Results in Executable Lowering

Os pontos estáveis já conhecidos são:

• packer/runtime tratam asset_id como identidade estável;
• asset_name ainda é a superfície mais natural para autoria e tooling;
• o pipeline executável hoje já exige disciplina explícita de stack;
• a família 19 reforçou a direção de compiler-owned lowering e publication protocol, reduzindo espaço para ambiguidades “aceitas pelo frontend, rejeitadas mais tarde”.

Isso sugere um princípio comum:

• a linguagem pode continuar amigável na superfície,
• mas o compiler precisa assumir explicitamente o trabalho de normalizar essa superfície para um contrato executável estável.

Open Questions

• Referências a asset devem permanecer nomeadas na superfície PBS, mesmo se o lowering resolver parte delas para identidade estável?
• 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?

Options

Option A - Keep Surface Simple, Keep Runtime Rules Visible

• Approach: manter asset_name como referência de longo prazo e exigir consumo explícito de retornos quando houver valor materializado.
• Pro: modelo simples e pouco invasivo.
• Con: vaza custo operacional e detalhe de lowering para código-fonte; mantém fragilidade de rename e lookup tardio.
• Maintainability: baixa a média, porque o autor continua negociando diretamente com limites do backend/runtime.

Option B - Preserve Surface Ergonomics, Normalize in the Compiler

• Approach: manter superfície amigável (asset_name, foo();) e explicitar no compiler as normalizações necessárias, como lowering para identidade estável quando possível e descarte automático de resultados ignorados em expression statement.
• Pro: separa melhor autoria de protocolo executável; fica alinhado com a direção já adotada na família 19.
• Con: aumenta responsabilidade do compiler e exige regras claras de quando a normalização pode ou não ocorrer.
• Maintainability: alta, porque o contrato passa a ficar onde ele deveria estar: no compiler e nas specs de lowering.

Option C - Introduce Rich Resource and Effect Surfaces

• Approach: criar abstrações mais fortes para recursos e resultados descartáveis, com novos tipos/superfícies na linguagem.
• Pro: potencialmente o modelo mais explícito e expressivo no longo prazo.
• Con: escopo bem maior; mistura redesign de linguagem com problemas que talvez possam ser resolvidos por lowering.
• Maintainability: incerta no curto prazo; só compensa se PBS quiser investir em abstrações novas, não apenas fechar lacunas atuais.

Discussion

As duas agendas legadas apontam para a mesma direção recomendada:

• preservar ergonomia de autoria;
• e mover o peso de normalização para o compiler.

Isso não significa “magia implícita sem limite”. Significa assumir, de forma normativa, que a superfície PBS pode ser mais estável e legível do que o protocolo executável final.

O ponto central desta discussão é definir o limite dessa política:

• quando PBS só normaliza lowering,
• e quando precisa criar uma abstração nova de linguagem.

Resolution

Direção recomendada por enquanto:

1. tratar os dois temas como uma única discussão de política de surface-versus-lowering em PBS;
2. preferir a direção Option B como baseline;
3. fechar depois duas decisões derivadas:
   • política de asset references para código de jogo;
   • política de descarte de retorno ignorado em expression statement;
4. evitar introduzir nova abstração de linguagem antes de esgotar a via de normalização no compiler.