170 lines
7.7 KiB
Markdown
170 lines
7.7 KiB
Markdown
# 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. TODO
|
|
|
|
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 `TODO` 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.
|