discussion framework migration

This commit is contained in:
2026-03-27 04:31:30 +00:00
parent 3e04cf6f2e
commit abdb28aa68
19 changed files with 366 additions and 651 deletions
+3 -1
View File
@@ -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"}]}
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.