discussion framework migration

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`

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`

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`

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)

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`

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`