discussion framework migration
This commit is contained in:
@@ -1,6 +1,8 @@
|
||||
{"type":"meta","next_id":{"DSC":6,"AGD":6,"DEC":3,"PLN":3,"LSN":18,"CLSN":1}}
|
||||
{"type":"meta","next_id":{"DSC":8,"AGD":8,"DEC":4,"PLN":4,"LSN":23,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":".discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":".discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":".discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":".discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":".discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":".discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":".discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":".discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":".discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[{"id":"AGD-0006","file":"AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":".discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":".discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":".discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":".discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":".discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
|
||||
+53
@@ -0,0 +1,53 @@
|
||||
---
|
||||
id: LSN-0018
|
||||
ticket: pbs-learn-to-discussion-lessons-migration
|
||||
title: PBS AST and Parser Contract Legacy Import
|
||||
created: 2026-03-27
|
||||
tags: [compiler, pbs, legacy-import, ast, parser, diagnostics]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/compiler/pbs/learn/01. AST and Parser Contract.md`.
|
||||
|
||||
This lesson preserves the durable parser-facing contract that remained after the PBS workflow prune.
|
||||
It records what later phases are allowed to assume about AST structure without freezing one parser implementation strategy.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Obligations-first AST contract
|
||||
|
||||
**What:** PBS standardizes observable AST obligations rather than one mandatory in-memory representation.
|
||||
|
||||
**Why:** Downstream phases need deterministic structure and attribution, but the repository does not want to lock parser architecture or implementation language.
|
||||
|
||||
**Trade-offs:** The contract is flexible for implementation, but it requires strong conformance discipline around spans, node families, and rejection behavior.
|
||||
|
||||
### Recovery must preserve structural honesty
|
||||
|
||||
**What:** Parser recovery is allowed only when the recovered AST remains structurally coherent and attribution-safe.
|
||||
|
||||
**Why:** Recovery exists to keep diagnostics useful, not to hide invalid syntax behind permissive fake trees.
|
||||
|
||||
**Trade-offs:** This makes parser implementations slightly stricter, but it prevents later phases from operating on misleading AST shapes.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Treat AST as a structural boundary, not a semantic one.
|
||||
- Preserve declaration identity instead of collapsing overloads or rewriting source-observable parse outcomes.
|
||||
- Make precedence and associativity visible in AST shape, because they are part of the user-observable contract.
|
||||
- Require stable source attribution on every node that diagnostics or lowering may consume.
|
||||
- Keep diagnostic identity locale-agnostic; wording is not the conformance key.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Rewriting AST after parse in a way that changes observable parse meaning.
|
||||
- Allowing recovery to downgrade a required rejection into an accepted semantic shape.
|
||||
- Emitting nodes without enough attribution for diagnostics or lowering.
|
||||
- Treating localized message strings as conformance identity.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- PBS AST is standardized by obligations, not by one exact object model.
|
||||
- Parser recovery is acceptable only when it stays structurally honest.
|
||||
- Attribution and deterministic rejection are first-class parser contracts, not secondary details.
|
||||
+52
@@ -0,0 +1,52 @@
|
||||
---
|
||||
id: LSN-0019
|
||||
ticket: pbs-learn-to-discussion-lessons-migration
|
||||
title: PBS Name Resolution and Linking Legacy Import
|
||||
created: 2026-03-27
|
||||
tags: [compiler, pbs, legacy-import, linking, name-resolution, imports]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/compiler/pbs/learn/02. Name Resolution and Linking.md`.
|
||||
|
||||
This lesson preserves the durable namespace and phase-boundary model for PBS frontend resolution after the domain workflow artifacts were pruned.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Module scope is assembled before visibility filtering
|
||||
|
||||
**What:** PBS collects declarations across all `.pbs` files in a module before `mod.barrel` visibility is applied.
|
||||
|
||||
**Why:** `mod.barrel` is a visibility filter, not a declaration factory.
|
||||
|
||||
**Trade-offs:** Module assembly must be explicit and deterministic, but the resulting linking model is much cleaner.
|
||||
|
||||
### Linking owns visible-space conflicts
|
||||
|
||||
**What:** Different-origin imported collisions, local-versus-import clashes, and barrel-driven visibility conflicts are rejected in linking before callsite analysis.
|
||||
|
||||
**Why:** Static semantics should operate only after the visible declaration space is already unambiguous.
|
||||
|
||||
**Trade-offs:** Linking becomes stricter, but overload resolution and typing stop carrying unrelated ambiguity debt.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Build module scope before import visibility decisions.
|
||||
- Resolve callable imports as exported callable sets, not isolated overload fragments.
|
||||
- Reject same-name different-origin conflicts before overload resolution.
|
||||
- Keep builtin simple types separate from imported builtin shells.
|
||||
- Treat aliasing as local spelling only; canonical identity must remain stable.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Treating `mod.barrel` as if it creates declarations.
|
||||
- Deferring imported-origin conflicts until callsite resolution.
|
||||
- Letting local and imported same-name declarations silently coexist.
|
||||
- Promoting imported builtin shells to the same status as always-available builtin simple types.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Linking decides what is visible; static semantics decides what a visible thing means.
|
||||
- `mod.barrel` filters visibility but does not define declaration existence.
|
||||
- Canonical identity must outrank textual spelling during import and linking work.
|
||||
+57
@@ -0,0 +1,57 @@
|
||||
---
|
||||
id: LSN-0020
|
||||
ticket: pbs-learn-to-discussion-lessons-migration
|
||||
title: PBS Runtime Values, Identity, and Memory Boundaries Legacy Import
|
||||
created: 2026-03-27
|
||||
tags: [compiler, pbs, legacy-import, runtime, values, identity, memory]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/compiler/pbs/learn/03. Runtime Values, Identity, and Memory Boundaries.md`.
|
||||
|
||||
This lesson preserves the runtime-facing mental model that keeps PBS lowering, diagnostics, and future optimization work aligned on aliasing, retention, and ownership.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Value categories are explicit
|
||||
|
||||
**What:** PBS distinguishes copied payload values, identity-bearing values, and carrier-only values.
|
||||
|
||||
**Why:** Later lowering and diagnostics need a stable answer to whether a construct preserves aliasing, creates retention, or just transports an existing payload.
|
||||
|
||||
**Trade-offs:** The model is intentionally qualitative rather than layout-specific, which keeps it stable but less byte-accounting-friendly.
|
||||
|
||||
### Host boundary semantics remain explicit
|
||||
|
||||
**What:** Host interaction is stack-only across the boundary, but host-backed resources still count as identity-bearing on the PBS side.
|
||||
|
||||
**Why:** PBS needs a clean boundary without pretending that host ownership disappears once a value crosses into language semantics.
|
||||
|
||||
**Trade-offs:** This is semantically clean, but it requires implementers to avoid naive “stack-only means no ownership complexity” shortcuts.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Treat scalars as copied payload without user-visible identity.
|
||||
- Treat structs, services, and host-backed resources as identity-bearing.
|
||||
- Treat tuples, `optional`, and `result` as carriers that do not create identity of their own.
|
||||
- Interpret cost visibility semantically:
|
||||
- allocation-bearing,
|
||||
- retention-bearing,
|
||||
- copy versus aliasing,
|
||||
- host-boundary crossing,
|
||||
- trap possibility.
|
||||
- Keep future lifetime-control and concurrency surfaces out of `core-v1` unless explicitly claimed.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Assuming carrier types create fresh identity.
|
||||
- Confusing qualitative runtime guarantees with exact allocator or collector promises.
|
||||
- Assuming stack-only host crossing eliminates host ownership concerns.
|
||||
- Silently treating future-profile surfaces as current supported behavior.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- PBS runtime contracts are qualitative on purpose.
|
||||
- Identity, aliasing, and retention are the stable facts that matter most for maintenance.
|
||||
- Host authority and PBS semantic identity can coexist without contradiction.
|
||||
+51
@@ -0,0 +1,51 @@
|
||||
---
|
||||
id: LSN-0021
|
||||
ticket: pbs-learn-to-discussion-lessons-migration
|
||||
title: PBS Diagnostics and Conformance Governance Legacy Import
|
||||
created: 2026-03-27
|
||||
tags: [compiler, pbs, legacy-import, diagnostics, conformance, governance]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/compiler/pbs/learn/04. Diagnostics and Conformance Governance.md`.
|
||||
|
||||
This lesson preserves the durable governance rules that survived the migration of broad policy ownership into general compiler specs.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Diagnostics are stable by identity, not prose
|
||||
|
||||
**What:** Diagnostic correctness is keyed by stable identity fields rather than by localized or rendered wording.
|
||||
|
||||
**Why:** Conformance and regression evidence must survive wording changes and localization.
|
||||
|
||||
**Trade-offs:** Tooling must carry identity fields seriously, but the resulting diagnostic contract is auditable and stable.
|
||||
|
||||
### Published claims require executable evidence
|
||||
|
||||
**What:** Conformance, compatibility, and support claims must be backed by maintained tests or artifact checks appropriate to the claim level.
|
||||
|
||||
**Why:** Published support without executable proof creates documentation debt and ambiguous promises.
|
||||
|
||||
**Trade-offs:** Governance becomes stricter, but support language stops drifting away from the real implementation.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Prefer general compiler specs as the live owner for cross-language governance.
|
||||
- Keep PBS-local guidance only for PBS-specific deltas and lessons.
|
||||
- Align claim scope, tests, and compatibility language together.
|
||||
- Be explicit when a surface is rescope-only rather than partially supported.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Leaving superseded local policy docs around as if they still owned the contract.
|
||||
- Publishing support claims without maintained evidence.
|
||||
- Allowing compatibility matrices and tests to drift apart.
|
||||
- Leaving rescope decisions implicit, especially for deferred execution surfaces.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Diagnostics and conformance must stay executable and auditable.
|
||||
- Once general specs take ownership, PBS-local records should become lesson material rather than live policy.
|
||||
- Honest rescoping is better than ambiguous “deferred” support language.
|
||||
+52
@@ -0,0 +1,52 @@
|
||||
---
|
||||
id: LSN-0022
|
||||
ticket: pbs-learn-to-discussion-lessons-migration
|
||||
title: PBS Globals, Lifecycle, and Published Entrypoint Legacy Import
|
||||
created: 2026-03-27
|
||||
tags: [compiler, pbs, legacy-import, globals, lifecycle, entrypoint, lowering]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/compiler/pbs/learn/05. Globals, Lifecycle, and Published Entrypoint.md`.
|
||||
|
||||
This lesson preserves the final topic-19 executable model after the workflow history was pruned from the PBS domain.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Logical frame root and physical entrypoint are separate
|
||||
|
||||
**What:** The user `[Frame]` callable is the logical frame root, while the compiler-published wrapper is the physical executable entrypoint.
|
||||
|
||||
**Why:** The language surface should stay clean and semantically owned by user code, while the compiler owns the executable boot protocol.
|
||||
|
||||
**Trade-offs:** The model introduces synthetic artifacts, but it makes lifecycle orchestration explicit and deterministic.
|
||||
|
||||
### Boot is one-shot and compiler-owned
|
||||
|
||||
**What:** PBS boot orchestration is enforced through compiler-generated lifecycle artifacts plus a hidden boot guard.
|
||||
|
||||
**Why:** One-shot bootstrap semantics cannot depend on naming convention or informal runtime discipline.
|
||||
|
||||
**Trade-offs:** Lowering must carry more structure and metadata, but backend and runtime contracts become much less ambiguous.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Model globals as explicit source-level declarations with stable module ownership.
|
||||
- Model lifecycle through `[Init]`, `[Frame]`, and compiler-owned synthetic lowering artifacts.
|
||||
- Publish the wrapper at physical entrypoint index `0`.
|
||||
- Keep `FRAME_RET` in the wrapper path, not at the end of userland `frame()`.
|
||||
- Keep hidden lifecycle state structurally distinguishable from ordinary user globals and callables.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Treating `frame()` itself as the physical entrypoint.
|
||||
- Reintroducing manifest-driven entrypoint authority.
|
||||
- Recognizing hidden lifecycle artifacts only by naming convention.
|
||||
- Proving only artifact presence without proving one-shot bootstrap semantics.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Userland owns frame semantics; the compiler owns executable boot protocol.
|
||||
- Hidden lifecycle artifacts must be first-class structure, not naming folklore.
|
||||
- Topic 19 is the closure that made PBS executable publication deterministic end-to-end.
|
||||
+94
@@ -0,0 +1,94 @@
|
||||
---
|
||||
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
|
||||
created: 2026-03-27
|
||||
resolved:
|
||||
decision:
|
||||
tags: [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.
|
||||
Reference in New Issue
Block a user