discussion framework migration
This commit is contained in:
parent
3e04cf6f2e
commit
abdb28aa68
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -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.
|
||||
@ -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`
|
||||
@ -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
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user