# PBS Name Resolution and Module Linking Agenda

Status: Active

## Purpose

Drive the closure of `14. Name Resolution and Module Linking Specification.md` so frontend implementation can proceed without inventing lookup or linking rules.

## Context

This is the main unresolved frontend-facing spec. The current skeleton still leaves open:

- exact lookup order across locals, top-level declarations, imports, builtin shells, and reserved surfaces,
- shadowing and duplicate rules by namespace,
- import alias and barrel-export matching behavior,
- cross-module callable and overload visibility,
- and the resolution model for builtin and host-backed stdlib shells.

Without this closure, parser and AST work can proceed only as exploratory implementation rather than normative frontend work.

## Decisions To Produce

1. Decide deterministic lookup order for every relevant namespace.
2. Decide shadowing, duplicate, and ambiguity rules for local, module, and imported names.
3. Decide import alias resolution and barrel matching rules in enough detail for implementation.
4. Decide the resolution model for builtin shells, builtin constants, intrinsic members, and host owners.
5. Decide which rejections belong to static semantics and which belong to a distinct linking phase.

## Core Questions

1. What is the exact lookup order in value position, type position, callable position, and host-owner position?
2. Do shadowing rules differ between locals, imports, top-level declarations, and builtin surfaces?
3. How are callable overload sets formed across local module declarations and imports?
4. When two imported modules make the same name visible, what is the exact ambiguity and rejection rule?
5. Are reserved stdlib shells resolved as ordinary visible declarations with metadata, or do they have any special priority?

## Expected Spec Material

The resulting spec work should be able to add or close sections for:

- scope construction,
- namespace-specific lookup order,
- import and alias resolution,
- barrel export matching,
- overload-set visibility across modules,
- builtin and host-shell resolution,
- linking-phase versus static-phase rejection boundaries,
- and deterministic cross-module failure cases.

## Non-Goals

- Redefining grammar already fixed in core syntax.
- Designing runtime loader behavior.
- Freezing one symbol-table implementation.
- Designing IDE auto-import behavior.

## Inputs

- `docs/pbs/specs/3. Core Syntax Specification.md`
- `docs/pbs/specs/4. Static Semantics Specification.md`
- `docs/pbs/specs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
- `docs/pbs/specs/8. Stdlib Environment Packaging and Loading Specification.md`
- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/pbs/specs/18. Standard Library Surface Specification.md`