prometeu-studio/docs/pbs/agendas/14.3. Name Resolution Workshop 3 - Callable Sets and Cross-Module Linking.md

PBS Name Resolution Workshop 3

Status: Active

Purpose

Run the third focused discussion for 14. Name Resolution and Module Linking Specification.md on callable visibility and cross-module linking:

• imported callable sets,
• overload-set formation across module boundaries,
• barrel matching consequences for imported overloads,
• and deterministic ambiguity rejection.

Why This Slice Third

This slice should come after Workshops 1 and 2 because it depends on already-closed rules for:

• scope construction,
• namespace-specific lookup order,
• import aliasing,
• reserved-shell visibility,
• and ordinary collision handling.

It is also the last major source-facing step before deciding whether linking is a separate normative phase.

Proposed Meeting Order

1. Reconfirm callable identity and barrel visibility rules that are already fixed.
2. Close how imported callable declarations become visible.
3. Close overload-set formation across local and imported declarations.
4. Close ambiguity and conflict rules for cross-module callable sets.
5. Close barrel-matching consequences for imported overload visibility.
6. Record phase-boundary questions for Workshop 4.

Already-Settled Inputs To Reconfirm

The meeting should explicitly reaffirm:

• callable identity ignores parameter labels and output labels,
• overloaded functions differ by input/output tuple shape rather than parameter spelling,
• only pub callable entries are importable from another module,
• each exported overload must appear explicitly in mod.barrel,
• and mod.barrel matches callables by callable identity rather than by label spelling alone.

These points are already fixed and should not be reopened here.

Decisions To Produce

1. Visibility rules for imported callable declarations and callable sets.
2. Merge or no-merge policy between local and imported overloads.
3. Ambiguity and rejection rules for callable sets visible from multiple modules.
4. Barrel consequences for callable visibility across modules.
5. Diagnostic ownership for callable-linking failures.

Candidate Decisions

1. Imported Callables Enter Ordinary Callable Lookup

Candidate direction:

• import { f } from @project:mod; introduces the exported callable set named f into local callable lookup.
• If the source module exports multiple overloads of f, the imported surface initially brings in that visible overload set, not only one declaration.
• Alias spelling changes only the local visible callable name, not callable identity.

Rationale:

• This keeps imported callables aligned with existing callable namespace rules.
• It avoids inventing per-overload import syntax before it is needed.

2. Local And Imported Overloads Do Not Merge Implicitly

Candidate direction:

• A local callable set and an imported callable set with the same visible name do not silently merge.
• Such a collision is a deterministic ambiguity unless both sets resolve to the same canonical underlying declarations.
• Overload merging is allowed only within one declaration origin set already sanctioned by module visibility and barrel rules.

Rationale:

• Silent merging across modules makes beginner reasoning harder.
• It also makes diagnostics and compatibility more fragile.
• Rejecting cross-origin merges keeps overload sets traceable.

Open point for discussion:

• whether there is any narrow exception for identical re-exported declarations reached through more than one import path.

3. Cross-Module Callable Ambiguity Is Rejected Before Overload Resolution

Candidate direction:

• If two different imported modules make the same callable name visible locally, and they do not denote the same canonical declarations, the program is rejected before ordinary overload resolution.
• Overload resolution should not be used as a tie-breaker between different imported origin sets.
• Callable ambiguity is resolved structurally by import visibility, not opportunistically by the later callsite.

Rationale:

• This keeps lookup deterministic and simple.
• It avoids context-sensitive import ambiguity that changes across callsites.

4. Barrel Visibility Defines The Imported Callable Set Boundary

Candidate direction:

• Only overloads exported through the source module's mod.barrel are part of the importable callable set.
• Non-exported local overloads in the source module do not participate in imported callable visibility.
• A named import of f from another module is therefore a request for that module's exported f set, filtered by barrel visibility.

Rationale:

• This makes cross-module callable linking a direct consequence of barrel policy rather than an extra ad hoc rule.

5. Diagnostic Ownership

Candidate direction:

• duplicate callable declarations inside one module remain static-semantics rejection,
• failure of a barrel callable entry to resolve inside its own module remains a module-linking or static-semantics-adjacent rejection depending on the final phase split,
• cross-module callable-name ambiguity remains linking-phase rejection,
• and overload-resolution failure at a callsite remains static semantics rather than module linking.

Rationale:

• This preserves a useful distinction between visible-set formation and callsite selection.

Questions To Resolve In The Room

1. Should local and imported callable sets ever merge automatically under the same name?
2. Should two imported callable sets with the same name be rejected immediately, or only when actually referenced?
3. If the same declaration becomes reachable through two import paths, should that still be rejected or canonicalized as one visible origin?
4. Is there any need for per-overload import control in v1, or is barrel-level export enough?
5. Where exactly is the line between callable-set formation and ordinary overload resolution?

Expected Outputs

This workshop should produce:

1. a decision record for imported callable-set visibility,
2. a decision record for callable ambiguity and merge policy,
3. a concrete update plan for the callable-linking sections of 14,
4. and a narrow carry-forward list for phase-boundary cleanup in Workshop 4.

Explicit Deferrals For Workshop 4

The following topics should be deferred unless unavoidable:

• whether linking is a formally distinct phase or folded into static semantics,
• diagnostic naming and code stability,
• source-to-artifact mapping concerns,
• and backend consequences of callable linking.

Inputs

• docs/pbs/specs/3. Core Syntax Specification.md
• docs/pbs/specs/4. Static Semantics Specification.md
• docs/pbs/specs/14. Name Resolution and Module Linking Specification.md
• docs/pbs/agendas/14. Name Resolution and Module Linking Agenda.md
• docs/pbs/agendas/14.1. Name Resolution Workshop 1 - Scope, Lookup, and Imports.md
• docs/pbs/agendas/14.2. Name Resolution Workshop 2 - Builtin Shells and Host Owners.md