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
-28
View File
@@ -1,28 +0,0 @@
# PBS Documentation
This directory now contains durable PBS domain knowledge.
## Tree
```text
docs/compiler/pbs/
└── learn/
```
Normative PBS specifications live in:
- `docs/specs/compiler-languages/pbs/`
- `docs/specs/compiler/`
## Purpose
`docs/compiler/pbs/learn/` is the long-term didactic layer for PBS.
Use it to:
- explain the final architectural model,
- preserve implementation-relevant lessons,
- summarize the reasoning that survived workflow closure,
- and accelerate onboarding for future PBS work.
Transient workflow artifacts such as agendas, decision records, and execution plans are intentionally pruned from this directory once their knowledge has been consolidated here or into the normative specs.
@@ -1,115 +0,0 @@
# Asset References in Game Code - Names vs Compile-Time Lowering Agenda
## Status
Open
## Purpose
Define how game code should reference assets over time:
- by logical `asset_name`,
- by compile-time lowering to stable `asset_id`,
- or through a more structured resource model inspired by engines that expose named resources while compiling them to stable internal handles.
## Domain Owner
`docs/compiler/pbs`
This is primarily a language/frontend and game-facing API question.
It depends on packer and runtime contracts, but it should be owned here because it affects source authoring, compile-time semantics, and generated runtime calls.
## Context
The current runtime still exposes game-facing asset operations by name.
Examples in `../runtime` today:
- graphics/runtime calls receive `asset_name`;
- audio/runtime calls receive `asset_name`;
- the runtime internally maps `asset_name -> asset_id` for normal asset use;
- preload/bootstrap was recently tightened around stable `asset_id`.
At the same time, the packer model already distinguishes:
- `asset_id` as stable artifact identity;
- `asset_name` as logical code-facing reference label.
This leaves an open architectural question:
Should game code continue to use strings/names directly forever, or should the compiler eventually lower asset references to more stable runtime-facing identifiers?
## Upstream Inputs
From packer decisions:
- [`001-asset-workspace-registry-and-stable-identity-decision.md`](../../../packer/decisions/001-asset-workspace-registry-and-stable-identity-decision.md)
- [`002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md`](../../../packer/decisions/002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md)
From runtime:
- `preload` now resolves by `asset_id`;
- asset APIs used by game/runtime code still resolve by `asset_name`;
- `asset_table` carries both `asset_id` and `asset_name`.
## Core Questions
1. Should source code asset references remain name-based in the long term?
2. Should the compiler resolve known asset references at compile time and lower them to `asset_id`?
3. If compile-time lowering exists, what happens for dynamic/late-bound asset names?
4. Should PBS expose a first-class resource handle abstraction instead of raw string references?
5. What compatibility and tooling story do we want for rename of `asset_name`?
6. How much runtime lookup by name is acceptable once asset identity is already stable in packer/runtime artifacts?
## Options
### Option A
Keep source and runtime calls name-based.
### Option B
Keep source authoring name-based, but lower resolvable references to `asset_id` at compile time.
### Option C
Introduce a richer resource abstraction in the language/toolchain, with compile-time or build-time resolution to stable handles under the hood.
## Tradeoffs
- Option A is simple and close to the current runtime, but keeps rename fragility and runtime lookup cost.
- Option B preserves authoring ergonomics while improving runtime determinism for static references.
- Option C could be the strongest long-term model, but it is also the most invasive and requires coordinated language, compiler, packer, and runtime work.
## Recommendation
Do not change the language surface blindly.
Recommended sequence:
1. preserve `asset_name` as the current source-level reference model;
2. evaluate compile-time lowering for statically known references as a separate capability;
3. only introduce a richer resource abstraction if the language ergonomics and tooling story justify the additional complexity.
This keeps current code understandable while leaving room to remove fragile runtime string lookup from hot paths later.
## Expected Decisions to Produce
1. Source-level asset reference model for PBS.
2. Whether compile-time lowering to `asset_id` should exist.
3. Boundaries between static references and dynamic references.
4. Rename/refactor expectations in Studio and compiler diagnostics.
5. Relationship between source references, packer outputs, and runtime lookup.
## Expected Spec Material
- PBS asset reference model spec or section.
- Compiler lowering rules for asset references.
- Diagnostics/refactoring behavior for asset rename.
- Cross-reference to packer/runtime asset identity contracts.
## Non-Goals
- Defining every asset-related syscall in detail.
- Redesigning the entire runtime asset manager.
- Solving preload layout or `assets.pa` packing rules here.
@@ -1,127 +0,0 @@
# Ignored Call Results in Executable Lowering Agenda
## Status
Open
## Domain Owner
`docs/compiler/pbs`
Este tema pertence ao domínio PBS do compiler porque afeta:
- semântica prática de `expression statement`;
- lowering executável para `IRBackend`/`IRVM`;
- ergonomia de uso de SDKs e hosts que retornam status;
- compatibilidade entre o que o código-fonte parece permitir e o que o pipeline realmente aceita.
## Problema
Hoje uma chamada com retorno usada como statement isolado pode deixar valor sobrando na stack no lowering executável.
Exemplo real:
```pbs
Gfx.set_sprite(...);
```
No estado atual, isso compila no frontend, mas pode falhar no pipeline backend com erro de validação de stack no `RET` da função, porque o resultado da call não foi consumido explicitamente.
Isso cria uma inconsistência operacional:
1. o código parece válido para o autor;
2. o frontend aceita a forma;
3. o backend exige, na prática, um consumo manual do retorno, por exemplo:
```pbs
let sprite_status = Gfx.set_sprite(...);
```
## Contexto
O problema apareceu ao migrar o consumo de sprite em PBS para o contrato novo de `Gfx.set_sprite`, que retorna um status inteiro.
Os pontos observados no código atual são:
- `ExpressionStatement` faz lowering apenas da expressão;
- o lowering de `CallExpr` emite `CALL_HOST`, `CALL_FUNC` ou `CALL_INTRINSIC` com `retSlots`;
- não há descarte automático do valor quando a expressão é usada apenas como statement;
- o validador de `IRVM` exige que funções `void` retornem com stack height `0`.
Na prática, isso transforma "ignorar retorno" em comportamento parcialmente suportado pela linguagem, mas não suportado pelo pipeline executável.
## Opções
### Opção A
Manter o comportamento atual e exigir consumo explícito de todo retorno em PBS.
### Opção B
Permitir que `expression statements` descartem automaticamente o resultado quando a expressão produzir valor.
### Opção C
Permitir descarte automático apenas para um subconjunto de calls, como hosts/SDKs anotados como status descartável.
## Tradeoffs
### Opção A
- Prós:
- regra simples no backend;
- evita descarte implícito sem intenção.
- Contras:
- ergonomia ruim para APIs baseadas em status;
- surpresa para autores, porque `foo();` parece natural mas falha mais tarde;
- expõe detalhe de stack do backend ao código-fonte.
### Opção B
- Prós:
- comportamento esperado para statement de expressão;
- reduz ruído em código de jogo e SDK;
- alinha parsing, semântica prática e lowering executável.
- Contras:
- introduz descarte implícito;
- exige regra clara para saber quando emitir `POP`.
### Opção C
- Prós:
- mais controle semântico;
- evita descarte implícito amplo.
- Contras:
- adiciona complexidade de contrato e metadata;
- mistura política de produto/API dentro do lowering;
- não resolve a expectativa geral sobre `expression statement`.
## Recomendação
Seguir com a **Opção B**.
Direção recomendada:
1. `expression statement` deve ser permitido mesmo quando a expressão produzir valor;
2. o lowering executável deve emitir descarte explícito do resultado não usado;
3. a regra deve ser geral para expressões com resultado materializado em stack, não especial para `Gfx.set_sprite`;
4. testes de regressão devem cobrir host calls, callable calls e intrinsics com retorno ignorado.
Essa direção preserva a ergonomia esperada da linguagem e remove um vazamento indevido do modelo de stack do backend para o código PBS.
## Perguntas em Aberto
1. O descarte automático deve valer para qualquer `expression statement` com valor ou apenas para formas lowerables em v1?
2. O frontend semântico deve emitir algum warning opcional para retorno ignorado, ou isso fica fora do escopo atual?
3. O descarte deve acontecer somente no lowering executável ou também virar regra explícita de spec para statements?
4. Existe algum caso em que o descarte automático possa mascarar bug real de usuário que hoje seria detectado mais cedo?
## Próximo Passo Sugerido
Converter esta agenda em uma `decision` do domínio `compiler/pbs` fechando a política para `expression statement` com resultado ignorado.
Depois disso, abrir um `pull-request/plan` curto para:
1. ajustar o lowering de `ExpressionStatement`;
2. adicionar fixtures e testes de regressão no frontend/backend pipeline;
3. propagar a regra para specs relevantes de statements e lowering.
@@ -1,72 +0,0 @@
# AST and Parser Contract
## Original Problem
PBS needed a stable AST contract that downstream phases could rely on without freezing one implementation language, one parser architecture, or one exact in-memory tree layout.
The earlier decision set also needed to close:
- which declaration families are mandatory,
- how statement and expression structure is represented,
- how precedence and associativity become observable,
- and how recovery and diagnostics stay deterministic.
## Consolidated Decision
PBS adopts an obligations-first AST contract.
The language standardizes observable AST behavior rather than one mandatory runtime representation.
The durable rules are:
1. One AST root exists per source file.
2. Child ordering is deterministic and follows source order.
3. Nodes consumed by diagnostics or lowering carry stable source attribution.
4. Declaration, statement, and expression families are explicit and structurally distinguishable.
5. Unsupported syntax is rejected deterministically instead of being hidden behind permissive synthetic nodes.
6. Recovery is allowed only when the recovered tree remains structurally coherent and attribution-safe.
7. Diagnostic identity is token-based and locale-agnostic; wording is not the conformance key.
## Final Model
The AST is not a semantic layer.
It preserves:
- source structure,
- declaration identity,
- precedence/associativity outcomes,
- and enough metadata for diagnostics and lowering.
It does not own:
- type checking,
- overload resolution,
- backend lowering policy,
- or runtime behavior.
That split matters because it keeps parser work honest: the parser records what the user wrote, and later phases decide what that structure means.
## Practical Consequences
When implementing or reviewing PBS parser work:
1. Reject malformed forms early and deterministically.
2. Do not collapse overload sets at AST boundary.
3. Do not use recovery to invent a valid semantic shape for invalid syntax.
4. Preserve spans on every node that diagnostics or lowering may consume.
5. Treat precedence and associativity as part of the observable contract, not an implementation detail.
## Common Pitfalls
- Treating localized message text as a conformance identity key.
- Rewriting AST shape after parse in a way that changes the observable parse result.
- Allowing recovery to mask a required rejection.
- Emitting nodes without enough attribution for diagnostics or lowering.
## Source Decisions
- `AST Contract and Root Model Decision.md`
- `AST Declarations and Type Surfaces Decision.md`
- `AST Statements and Expressions Decision.md`
- `AST Diagnostics, Recovery, and Gate Evidence Decision.md`
@@ -1,63 +0,0 @@
# Name Resolution and Linking
## Original Problem
PBS needed a deterministic model for:
- how module scope is formed,
- what imports actually make visible,
- how callable sets cross module boundaries,
- how builtin shells and host owners participate in lookup,
- and which failures belong to syntax, import resolution, linking, or static semantics.
## Consolidated Decision
PBS resolves names by explicit namespace and explicit phase ownership.
The stable baseline is:
1. A module is assembled from all `.pbs` files before visibility filtering.
2. `mod.barrel` is a visibility filter over existing declarations, not the source of declaration existence.
3. Imports target modules, not files.
4. Only exported names become importable across modules.
5. Aliases change only the local visible spelling, never canonical identity.
6. Local-versus-import collisions are deterministic errors instead of silent shadowing.
7. Duplicate imports are tolerated only when they denote the same canonical origin.
8. Different-origin same-name imports are rejected in linking, before callsite analysis.
9. Builtin shells and host owners participate through ordinary imported surfaces plus reserved metadata, not through a parallel hidden namespace.
10. Member lookup on an already-typed builtin receiver belongs to static semantics, not linking.
## Final Model
The phase boundary is now clear:
- syntax owns malformed source forms,
- manifest/import resolution owns locating module sources,
- linking owns visible declaration assembly across modules,
- static semantics owns meaning once the visible declaration space is already unambiguous.
This is the important operational closure: linking decides what can be seen; static semantics decides what that visible thing means.
## Practical Consequences
When implementing PBS frontend resolution:
1. Build module scope before applying barrel visibility.
2. Resolve imported callable sets from exported overload sets only.
3. Reject origin conflicts before overload resolution.
4. Keep builtin simple types separate from imported builtin shells.
5. Never let textual spelling outrank canonical owner identity.
## Common Pitfalls
- Treating `mod.barrel` as if it created 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 simple builtin types.
## Source Decisions
- `Name Resolution - Scope, Lookup, and Imports Decision.md`
- `Name Resolution - Callable Sets and Cross-Module Linking Decision.md`
- `Name Resolution - Builtin Shells and Host Owners Decision.md`
- `Name Resolution - Linking Phase Boundary Decision.md`
@@ -1,76 +0,0 @@
# Runtime Values, Identity, and Memory Boundaries
## Original Problem
PBS needed a consistent user-visible runtime model for:
- which values carry identity,
- which values are copied payload,
- where ownership changes at host boundaries,
- what the collector is allowed to assume,
- and which cost facts matter semantically.
Without that closure, later lowering and diagnostics would have to guess whether a construct implied allocation, aliasing, retention, or host-owned state.
## Consolidated Decision
PBS keeps the runtime model intentionally small and explicit.
The stable rules are:
1. Scalars are copied values without user-visible identity.
2. Structs are identity-bearing reference values.
3. Services are canonical singleton identity-bearing values.
4. Host-backed resources are identity-bearing on the PBS side even when authority remains host-owned.
5. `optional`, `result`, and tuples are carriers; they do not create identity of their own.
6. Contract values do not create a second identity separate from the underlying value.
7. Host interaction is stack-only across the boundary.
8. The GC and reachability model must preserve identity-bearing values and retained callback contexts.
9. Cost visibility is semantic only where it changes reasoning:
- allocation-bearing versus non-allocation-bearing,
- retention-bearing versus non-retention-bearing,
- copy versus aliasing,
- host-boundary crossing,
- and trap possibility.
## Final Model
The runtime contract is qualitative, not byte-accounting-driven.
PBS does not promise:
- exact byte counts,
- one exact heap layout,
- or one exact collector schedule.
It does promise the semantic facts that maintenance tooling and humans need:
- whether aliasing is preserved,
- whether retention exists,
- whether a construct may allocate,
- and whether a boundary crossing is happening.
## Practical Consequences
1. `bind(context, fn_name)` is the main retention-bearing primitive in the current surface.
2. Carrier constructs are not allocation-bearing by themselves.
3. Host memory authority remains on the host side even when PBS models the value as identity-bearing.
4. Lifetime-control surfaces beyond the current line remain future-profile work, not silently implied support.
## Common Pitfalls
- Treating carriers like `optional` or `result` as if they created fresh identity.
- Assuming stack-only host crossing means host ownership disappears.
- Confusing qualitative cost guarantees with exact runtime budgeting.
- Treating future lifetime-control or concurrency surfaces as part of `core-v1` by implication.
## Source Decisions
- `Value Representation and Identity Decision.md`
- `Host Memory Boundary Decision.md`
- `GC and Reachability Decision.md`
- `Allocation and Cost Visibility Decision.md`
- `Lifetime Control and Future Profiles Decision.md`
- `Dynamic Semantics - Execution Model Decision.md`
- `Dynamic Semantics - Branch Selection Decision.md`
- `Dynamic Semantics - Effect Surfaces Decision.md`
@@ -1,68 +0,0 @@
# Diagnostics and Conformance Governance
## Original Problem
PBS accumulated several governance decisions around:
- diagnostic identity,
- artifact-facing conformance,
- claim publication,
- compatibility matrices,
- runtime-backed gates,
- optimization-stage obligations,
- and late closure of diagnostics and conformance evidence.
Much of that work later moved into general compiler specs, which made the local PBS decisions useful as history but redundant as active workflow artifacts.
## Consolidated Decision
The durable PBS lesson is:
1. Diagnostics must be stable by identity, not by prose wording.
2. Evidence must be executable, not rhetorical.
3. Published support claims require maintained proof.
4. Artifact-level obligations matter only where the selected claim level requires them.
5. Once a cross-language general spec becomes the normative owner, local PBS decision records should stop acting as the live policy surface.
## Final Model
Today the normative owner for most of this policy is outside `docs/compiler/pbs/`:
- conformance baselines,
- compatibility publication,
- verification and safety checks,
- and broad backend claim policy
now live in general compiler specs.
PBS still keeps domain-specific learnings:
- diagnostics identity must remain deterministic,
- evidence must track the actual claim scope,
- and claim rescoping must be explicit rather than silently drifting.
That is especially important for `SPAWN` and `YIELD`: the honest policy was to rescope them out of `core-v1`, not to leave ambiguous “deferred” support language hanging around.
## Practical Consequences
1. Prefer the general compiler specs when updating policy.
2. Use PBS-local docs only for PBS-specific deltas or examples.
3. Keep conformance rows, tests, and published claims aligned.
4. Treat superseded local decisions as historical input, not as live normative authority.
## Common Pitfalls
- Keeping superseded local policy docs as if they still owned the contract.
- Publishing claims without executable evidence.
- Letting matrix/support language drift away from what the backend actually implements.
- Leaving rescope decisions implicit instead of explicit.
## Source Decisions
- `Diagnostics Contract Decision.md`
- `Diagnostics, Manifest Propagation, and Conformance Coverage Decision.md`
- `IRVM Optimization Stage Placement Decision.md`
- `SPAWN-YIELD v1 Claim Rescope Decision.md`
- `Artifact-Level Conformance and Fixture Model Decision.md` (superseded)
- `Compatibility Matrix and Published Claims Decision.md` (superseded)
- `Conformance Claim Levels Decision.md` (superseded)
@@ -1,68 +0,0 @@
# Globals, Lifecycle, and Published Entrypoint
## Original Problem
Topic 19 closed the biggest remaining executable-model gap in PBS:
- explicit globals,
- lifecycle markers,
- program initialization,
- published wrapper ownership,
- `FRAME_RET` placement,
- hidden boot state,
- and the compiler-to-backend handoff contract.
## Consolidated Decision
PBS now has one coherent lifecycle model.
The durable rules are:
1. Globals are explicit source-level declarations with stable identity and module ownership.
2. Lifecycle is source-driven through `[Init]`, `[Frame]`, and related static rules.
3. The user `[Frame]` function is the logical frame root.
4. The published physical entrypoint is a synthetic compiler-owned wrapper.
5. The wrapper owns final `FRAME_RET`.
6. Boot is one-shot and enforced through a hidden compiler-owned boot guard.
7. Hidden lifecycle artifacts must be structurally distinguishable from userland globals and userland callables.
8. Backend handoff must preserve wrapper identity, hidden global identity, origin metadata, and physical entrypoint index `0`.
## Final Model
The executable model is now:
1. per-file init fragments,
2. per-module synthetic init,
3. project init,
4. a published wrapper at physical entrypoint `0`,
5. a hidden `BOOT_GUARD`,
6. and user `frame()` as the logical callable invoked by the wrapper.
This is the key conceptual split:
- userland owns the logical frame root,
- the compiler owns the physical boot protocol.
That separation keeps the language surface clean while still giving the backend and runtime a deterministic boot contract.
## Practical Consequences
1. Executable PBS projects must declare an explicit `[Frame]`.
2. Entrypoint authority no longer belongs to manifest metadata or nominal export lookup.
3. Hidden compiler lifecycle state must not be modeled as ordinary user globals.
4. Lowering and tests should prove wrapper publication, wrapper ordering, guard presence, and guard semantics.
## Common Pitfalls
- Treating `frame()` itself as the physical entrypoint.
- Reintroducing manifest-driven entrypoint authority.
- Recognizing hidden lifecycle artifacts only by naming convention.
- Forgetting that boot must be one-shot across frames, not merely “present in the graph”.
## Source Decisions
- `Globals Surface, Identity, and Module Boundaries Decision.md`
- `Lifecycle Markers, Program Init, and Frame Root Semantics Decision.md`
- `Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Decision.md`
- `Globals and Lifecycle Lowering to IRBackend and IRVM Decision.md`
- `Diagnostics, Manifest Propagation, and Conformance Coverage Decision.md`
-29
View File
@@ -1,29 +0,0 @@
# PBS Learn
This directory consolidates the durable operational knowledge of the PBS domain.
It exists to replace transient workflow artifacts that already served their purpose:
- open agendas,
- closed decisions,
- execution PR/plans.
The normative contract for PBS lives primarily in:
- `docs/specs/compiler-languages/pbs/`
- `docs/specs/compiler/`
`learn/` is the didactic layer:
- it explains the final model,
- highlights the tradeoffs that matter in maintenance,
- summarizes common pitfalls,
- and points back to the normative specs that should be updated or consulted first.
## Learn Set
- `01. AST and Parser Contract.md`
- `02. Name Resolution and Linking.md`
- `03. Runtime Values, Identity, and Memory Boundaries.md`
- `04. Diagnostics and Conformance Governance.md`
- `05. Globals, Lifecycle, and Published Entrypoint.md`
@@ -60,7 +60,7 @@ This document depends on, at minimum:
This document integrates the following accepted decisions:
- `docs/compiler/pbs/learn/03. Runtime Values, Identity, and Memory Boundaries.md`
- `.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md`
## 5. Already-Settled Inputs
@@ -59,8 +59,8 @@ This document depends on, at minimum:
This document integrates the following accepted decisions:
- `docs/compiler/pbs/learn/03. Runtime Values, Identity, and Memory Boundaries.md`
- `docs/compiler/pbs/learn/05. Globals, Lifecycle, and Published Entrypoint.md`
- `.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md`
- `.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md`
## 5. Already-Settled Inputs
@@ -44,7 +44,7 @@ This document depends on:
- `20. IRBackend to IRVM Lowering Specification.md`
- `15. Bytecode and PBX Mapping Specification.md`
- `19. Verification and Safety Checks Specification.md`
- `docs/compiler/pbs/learn/04. Diagnostics and Conformance Governance.md`
- `.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md`
## 5. Canonical Backend Pipeline Order