---
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.