From 3e04cf6f2e06103326b13abf4476b72b9ede13ef Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Thu, 26 Mar 2026 20:17:23 +0000 Subject: [PATCH] discussion framework migration --- .../pbs/learn/01. AST and Parser Contract.md | 72 ++++++++++++++++++ .../learn/02. Name Resolution and Linking.md | 63 +++++++++++++++ ...Values, Identity, and Memory Boundaries.md | 76 +++++++++++++++++++ ... Diagnostics and Conformance Governance.md | 68 +++++++++++++++++ ...ls, Lifecycle, and Published Entrypoint.md | 68 +++++++++++++++++ docs/compiler/pbs/learn/README.md | 29 +++++++ 6 files changed, 376 insertions(+) create mode 100644 docs/compiler/pbs/learn/01. AST and Parser Contract.md create mode 100644 docs/compiler/pbs/learn/02. Name Resolution and Linking.md create mode 100644 docs/compiler/pbs/learn/03. Runtime Values, Identity, and Memory Boundaries.md create mode 100644 docs/compiler/pbs/learn/04. Diagnostics and Conformance Governance.md create mode 100644 docs/compiler/pbs/learn/05. Globals, Lifecycle, and Published Entrypoint.md create mode 100644 docs/compiler/pbs/learn/README.md diff --git a/docs/compiler/pbs/learn/01. AST and Parser Contract.md b/docs/compiler/pbs/learn/01. AST and Parser Contract.md new file mode 100644 index 00000000..b0f75754 --- /dev/null +++ b/docs/compiler/pbs/learn/01. AST and Parser Contract.md @@ -0,0 +1,72 @@ +# 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 new file mode 100644 index 00000000..a876f3a7 --- /dev/null +++ b/docs/compiler/pbs/learn/02. Name Resolution and Linking.md @@ -0,0 +1,63 @@ +# 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 new file mode 100644 index 00000000..d4b4e671 --- /dev/null +++ b/docs/compiler/pbs/learn/03. Runtime Values, Identity, and Memory Boundaries.md @@ -0,0 +1,76 @@ +# 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 new file mode 100644 index 00000000..b502b666 --- /dev/null +++ b/docs/compiler/pbs/learn/04. Diagnostics and Conformance Governance.md @@ -0,0 +1,68 @@ +# 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 new file mode 100644 index 00000000..aa3ac1f6 --- /dev/null +++ b/docs/compiler/pbs/learn/05. Globals, Lifecycle, and Published Entrypoint.md @@ -0,0 +1,68 @@ +# 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 new file mode 100644 index 00000000..fc35c918 --- /dev/null +++ b/docs/compiler/pbs/learn/README.md @@ -0,0 +1,29 @@ +# 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`