discussion framework migration
This commit is contained in:
@@ -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.
|
||||
-115
@@ -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.
|
||||
-127
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user