diff --git a/.discussion/index.ndjson b/.discussion/index.ndjson index 0d7bab5d..75dffd0f 100644 --- a/.discussion/index.ndjson +++ b/.discussion/index.ndjson @@ -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"}]} diff --git a/.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md b/.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md new file mode 100644 index 00000000..9e3c2766 --- /dev/null +++ b/.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md @@ -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. diff --git a/.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md b/.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md new file mode 100644 index 00000000..6552c81c --- /dev/null +++ b/.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md @@ -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. diff --git a/.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md b/.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md new file mode 100644 index 00000000..64ffc3d0 --- /dev/null +++ b/.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md @@ -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. diff --git a/.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md b/.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md new file mode 100644 index 00000000..98ff8624 --- /dev/null +++ b/.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md @@ -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. diff --git a/.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md b/.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md new file mode 100644 index 00000000..9390a5c8 --- /dev/null +++ b/.discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md @@ -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. diff --git a/.discussion/workflow/agendas/AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md b/.discussion/workflow/agendas/AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md new file mode 100644 index 00000000..9bce4809 --- /dev/null +++ b/.discussion/workflow/agendas/AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md @@ -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. diff --git a/docs/compiler/pbs/README.md b/docs/compiler/pbs/README.md deleted file mode 100644 index ed70c013..00000000 --- a/docs/compiler/pbs/README.md +++ /dev/null @@ -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. diff --git a/docs/compiler/pbs/agendas/18.4. Asset References in Game Code - Names vs Compile-Time Lowering Agenda.md b/docs/compiler/pbs/agendas/18.4. Asset References in Game Code - Names vs Compile-Time Lowering Agenda.md deleted file mode 100644 index 2445f2f3..00000000 --- a/docs/compiler/pbs/agendas/18.4. Asset References in Game Code - Names vs Compile-Time Lowering Agenda.md +++ /dev/null @@ -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. diff --git a/docs/compiler/pbs/agendas/18.5. Ignored Call Results in Executable Lowering Agenda.md b/docs/compiler/pbs/agendas/18.5. Ignored Call Results in Executable Lowering Agenda.md deleted file mode 100644 index fae03003..00000000 --- a/docs/compiler/pbs/agendas/18.5. Ignored Call Results in Executable Lowering Agenda.md +++ /dev/null @@ -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. diff --git a/docs/compiler/pbs/learn/01. AST and Parser Contract.md b/docs/compiler/pbs/learn/01. AST and Parser Contract.md deleted file mode 100644 index b0f75754..00000000 --- a/docs/compiler/pbs/learn/01. AST and Parser Contract.md +++ /dev/null @@ -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` diff --git a/docs/compiler/pbs/learn/02. Name Resolution and Linking.md b/docs/compiler/pbs/learn/02. Name Resolution and Linking.md deleted file mode 100644 index a876f3a7..00000000 --- a/docs/compiler/pbs/learn/02. Name Resolution and Linking.md +++ /dev/null @@ -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` diff --git a/docs/compiler/pbs/learn/03. Runtime Values, Identity, and Memory Boundaries.md b/docs/compiler/pbs/learn/03. Runtime Values, Identity, and Memory Boundaries.md deleted file mode 100644 index d4b4e671..00000000 --- a/docs/compiler/pbs/learn/03. Runtime Values, Identity, and Memory Boundaries.md +++ /dev/null @@ -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` diff --git a/docs/compiler/pbs/learn/04. Diagnostics and Conformance Governance.md b/docs/compiler/pbs/learn/04. Diagnostics and Conformance Governance.md deleted file mode 100644 index b502b666..00000000 --- a/docs/compiler/pbs/learn/04. Diagnostics and Conformance Governance.md +++ /dev/null @@ -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) diff --git a/docs/compiler/pbs/learn/05. Globals, Lifecycle, and Published Entrypoint.md b/docs/compiler/pbs/learn/05. Globals, Lifecycle, and Published Entrypoint.md deleted file mode 100644 index aa3ac1f6..00000000 --- a/docs/compiler/pbs/learn/05. Globals, Lifecycle, and Published Entrypoint.md +++ /dev/null @@ -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` diff --git a/docs/compiler/pbs/learn/README.md b/docs/compiler/pbs/learn/README.md deleted file mode 100644 index fc35c918..00000000 --- a/docs/compiler/pbs/learn/README.md +++ /dev/null @@ -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` diff --git a/docs/specs/compiler-languages/pbs/10. Memory and Lifetime Specification.md b/docs/specs/compiler-languages/pbs/10. Memory and Lifetime Specification.md index fa82645e..bbe59b1b 100644 --- a/docs/specs/compiler-languages/pbs/10. Memory and Lifetime Specification.md +++ b/docs/specs/compiler-languages/pbs/10. Memory and Lifetime Specification.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 diff --git a/docs/specs/compiler-languages/pbs/9. Dynamic Semantics Specification.md b/docs/specs/compiler-languages/pbs/9. Dynamic Semantics Specification.md index ad4c4121..b5583f2b 100644 --- a/docs/specs/compiler-languages/pbs/9. Dynamic Semantics Specification.md +++ b/docs/specs/compiler-languages/pbs/9. Dynamic Semantics Specification.md @@ -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 diff --git a/docs/specs/compiler/21. IRVM Optimization Pipeline Specification.md b/docs/specs/compiler/21. IRVM Optimization Pipeline Specification.md index e3cba57b..8a77be25 100644 --- a/docs/specs/compiler/21. IRVM Optimization Pipeline Specification.md +++ b/docs/specs/compiler/21. IRVM Optimization Pipeline Specification.md @@ -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