53 lines
2.2 KiB
Markdown
53 lines
2.2 KiB
Markdown
---
|
|
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.
|