prometeu-studio/docs/compiler/pbs/learn/02. Name Resolution and Linking.md

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