prometeu-studio/docs/pbs/specs/14. Name Resolution and Module Linking Specification.md

PBS Name Resolution and Module Linking Specification

Status: Draft v0 (Skeleton)
Applies to: scope formation, name lookup, imports, exports, barrel visibility, cross-module resolution, and semantic linking of PBS programs

1. Purpose

This document will define the normative name-resolution and semantic-linking model for PBS.

2. Scope

This document is intended to define:

• scope formation and lookup order,
• namespace separation and collision rules,
• import and export resolution,
• barrel-mediated visibility and module linking,
• cross-file and cross-module symbol resolution,
• resolution of reserved stdlib shells for host-backed and VM-owned surfaces,
• linkage-time rejection conditions before lowering.

This document does not define:

• runtime execution behavior,
• optimizer or backend internals,
• full PBX binary linking.

3. Authority and Precedence

Normative precedence:

1. 3. Core Syntax Specification.md
2. 4. Static Semantics Specification.md
3. 5. Manifest, Stdlib, and SDK Resolution Specification.md
4. 6. VM-owned vs Host-backed.md
5. 6.1. Intrinsics and Builtin Types Specification.md
6. 18. Standard Library Surface Specification.md
7. This document

If a rule here conflicts with higher-precedence specs, it is invalid.

4. Normative Inputs

This document depends on, at minimum:

• 3. Core Syntax Specification.md
• 4. Static Semantics Specification.md
• 5. Manifest, Stdlib, and SDK Resolution Specification.md
• 6. VM-owned vs Host-backed.md
• 6.1. Intrinsics and Builtin Types Specification.md
• 8. Stdlib Environment Packaging and Loading Specification.md
• 18. Standard Library Surface Specification.md

5. Already-Settled Inputs

The following inputs are already fixed elsewhere and must not be contradicted here:

• PBS has distinct type, value, callable, and host-owner namespaces.
• mod.barrel is the single source of module visibility.
• Imports target modules, not files.
• Reserved stdlib project spaces are resolved only from the selected stdlib environment.
• Only pub symbols may be imported from another module.
• Reserved stdlib/interface modules may expose compile-time-only shells for both host-backed and VM-owned surfaces.
• Source-visible builtin names are resolved through imported builtin shell declarations rather than by hardcoded source spelling alone.
• Canonical builtin identity and canonical intrinsic identity are governed by builtin metadata rather than by the imported PBS-visible declaration name alone.

6. Initial Section Targets

At minimum, the completed document should contain normative sections for:

1. scope construction,
2. lookup order by namespace,
3. import and alias resolution,
4. barrel export matching and linking,
5. reserved stdlib shell resolution for builtin and host-backed surfaces,
6. duplicate and shadowing rules,
7. cross-module resolution failures.

7. A Ver

The following items remain to be closed in future agenda discussion.

• Exact lookup order across local bindings, top-level declarations, imports, and reserved intrinsic surfaces.
• Whether shadowing rules differ by namespace or declaration kind.
• Whether semantic linking is fully part of static semantics or split into a distinct phase contract.
• Exact rejection model for ambiguous cross-module overload visibility and barrel-linked callable sets.
• Whether stdlib/interface-module linking imposes extra restrictions beyond ordinary modules.
• Whether builtin shell declarations may be synthesized by the toolchain in addition to being provided by stdlib modules.

8. Non-Goals

• Reopening the already-settled import surface syntax.
• Defining runtime loader behavior.
• Freezing one compiler symbol-table implementation.

9. Exit Criteria

This document is ready to move beyond skeleton status only when:

1. name lookup is deterministic across all relevant scopes,
2. barrel and module linking behavior is explicit,
3. reserved stdlib shell resolution is explicit for host-backed and VM-owned surfaces,
4. cross-module ambiguity and failure cases are normatively defined,
5. the document no longer relies on unresolved A Ver items for ordinary v1 resolution behavior.

10. Reserved Stdlib Shell Resolution

Reserved stdlib modules may expose compile-time-only declarations that do not behave like ordinary user-authored implementation bodies.

Rules:

• declare host surfaces exported from reserved stdlib modules resolve in the host-owner namespace.
• declare builtin type surfaces exported from reserved stdlib modules resolve in the type namespace.
• builtin constants exported from reserved stdlib modules resolve in the value namespace.
• builtin intrinsic methods are not imported as free functions; they are resolved through the imported builtin type declaration of the receiver type.
• canonical host identity is not derived from the imported host owner spelling,
• and canonical builtin/intrinsic identity is not derived solely from the imported builtin type spelling.

Example:

• importing Vec2 from @core:math may introduce the PBS-visible type name Vec2,
• while the declaration's metadata may still lower that type to canonical builtin identity ("vec2", 1).

11. Import and Barrel Rules for Builtin Shells

Builtin shells follow ordinary module visibility rules at the source level and special metadata rules at lowering time.

Rules:

• a builtin type, builtin constant, or host owner may be imported only if it is exported through the target module's mod.barrel,
• aliasing an imported builtin type changes only the source-visible local name, not the canonical builtin identity declared by metadata,
• aliasing an imported builtin constant changes only the local binding name, not the canonical builtin constant identity declared by metadata,
• aliasing an imported host owner changes only the source-visible local name, not the canonical host identity declared by Host(...),
• barrel matching for builtin declarations is declaration-based rather than executable-body based,
• and resolution must complete before lowering begins.

12. Lookup Order for Builtin and Intrinsic Surfaces

Lookup remains namespace-based.

Rules:

• type-position lookup considers visible builtin type declarations alongside other visible type declarations,
• value-position lookup considers visible builtin constants alongside other visible values,
• callable lookup does not treat builtin intrinsic members as top-level callable declarations,
• member lookup on a builtin-typed receiver considers builtin projection fields first as field-like surfaces of that builtin declaration,
• method lookup on a builtin-typed receiver considers builtin intrinsic member signatures declared by that builtin shell,
• and host-owner lookup remains separate from builtin type lookup.

This preserves the distinction between:

• imported builtin type shells,
• imported host owners,
• and compiler-recognized intrinsic method surfaces on existing core forms such as optional and enums.

13. Deterministic Resolution Failures

At minimum, a conforming implementation must reject:

1. import of a non-exported builtin type shell,
2. import of a non-exported builtin constant shell,
3. import of a non-exported host owner shell,
4. ambiguous cross-module visibility of builtin declarations after barrel resolution,
5. duplicate visible builtin type declarations that claim the same canonical builtin identity in one resolved environment,
6. duplicate visible builtin constants that claim the same canonical builtin constant identity in one resolved environment,
7. member lookup on a builtin receiver where the imported builtin shell does not declare the requested field or intrinsic member,
8. any resolution path that attempts to derive host or builtin canonical identity from alias spelling alone.