discussion framework migration
This commit is contained in:
+53
@@ -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.
|
||||
+52
@@ -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.
|
||||
+57
@@ -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.
|
||||
+51
@@ -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.
|
||||
+52
@@ -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.
|
||||
Reference in New Issue
Block a user