integrated 14 into specs
This commit is contained in:
@@ -0,0 +1,168 @@
|
||||
# Name Resolution - Builtin Shells and Host Owners Decision
|
||||
|
||||
Status: Proposed
|
||||
Cycle: Initial name-resolution closure pass
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 needs a deterministic rule for how reserved stdlib shells participate in source-level name resolution.
|
||||
|
||||
The open questions were:
|
||||
|
||||
- whether builtin shells and host owners enter lookup as ordinary imported declarations or as special compiler-only names,
|
||||
- whether builtin intrinsic methods participate in free callable lookup,
|
||||
- whether reserved shells receive special collision priority,
|
||||
- whether builtin shells belong under `@core:*` or `@sdk:*` by policy,
|
||||
- and which phase owns failures related to builtin member lookup and canonical identity duplication.
|
||||
|
||||
Important fixed inputs already existed:
|
||||
|
||||
- reserved stdlib project spaces are resolved from the selected stdlib environment,
|
||||
- source-visible builtin names resolve through imported builtin shell declarations,
|
||||
- canonical builtin and host identities come from metadata rather than local spelling,
|
||||
- builtin intrinsic methods are not imported as free functions,
|
||||
- and host-owner namespace remains distinct from type, value, and callable namespaces.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following baseline for builtin shells and host-owner resolution:
|
||||
|
||||
1. Source-visible declarations exposed by reserved builtin shells are imported into their ordinary corresponding namespaces.
|
||||
2. This means builtin-exposed types enter type lookup as imported type declarations, builtin-exposed constants enter value lookup as imported values, and host owners enter host-owner lookup as imported host-owner declarations.
|
||||
3. `declare builtin type` itself remains a reserved stdlib/toolchain declaration form rather than ordinary user-authored source syntax.
|
||||
4. Reserved-shell metadata exists to drive canonical identity and later lowering, not to create special source-level lookup priority.
|
||||
5. Builtin simple types `int`, `float`, `bool`, and `str` remain separate always-available reserved type names and are not treated as ordinary imported builtin shells.
|
||||
6. Builtin intrinsic methods never participate in free lookup.
|
||||
7. Builtin intrinsic methods are resolved only through member lookup on a receiver already known to have the corresponding builtin type.
|
||||
8. Reserved builtin shells and host owners follow the same collision policy as ordinary imported declarations: same visible name in the same namespace is an error unless another already-closed rule explicitly permits otherwise.
|
||||
9. By policy, builtin shells are preferred under `@core:*`.
|
||||
10. Member lookup failure on an already-typed builtin receiver belongs to static semantics.
|
||||
11. Duplicate canonical builtin identities or duplicate canonical host identities in one resolved environment belong normatively to linking rather than to syntax or ordinary static semantics.
|
||||
|
||||
## 3. Reserved Shells As Imported Declarations
|
||||
|
||||
Reserved shells are source-visible through ordinary import and visibility rules.
|
||||
|
||||
This means:
|
||||
|
||||
- the user imports the shell from a reserved stdlib module,
|
||||
- the imported shell becomes visible in the matching namespace,
|
||||
- and source-level lookup treats that visible declaration like other imported declarations of the same namespace.
|
||||
|
||||
The compiler still recognizes the reserved metadata attached to those declarations, but that metadata does not create a parallel hidden namespace.
|
||||
|
||||
## 4. Builtin Simple Types Versus Imported Builtin Shells
|
||||
|
||||
PBS distinguishes:
|
||||
|
||||
- the tiny predeclared builtin simple-type set: `int`, `float`, `bool`, `str`,
|
||||
- and imported builtin shells such as `Vec2`, `Color`, or similar stdlib-exposed types.
|
||||
|
||||
Rules:
|
||||
|
||||
- builtin simple types remain always available without import,
|
||||
- imported builtin shells are not promoted to that same status,
|
||||
- and the two categories must not be conflated in source-level lookup.
|
||||
|
||||
## 5. Intrinsic Member Lookup
|
||||
|
||||
Builtin intrinsic members are resolved only through receiver-member lookup.
|
||||
|
||||
Rules:
|
||||
|
||||
- they do not appear in top-level callable lookup,
|
||||
- they are not introduced by import as free functions,
|
||||
- and aliasing the owner builtin type changes only the local visible owner spelling, not the intrinsic's canonical identity.
|
||||
|
||||
This keeps member semantics uniform and avoids special free-function treatment for reserved surfaces.
|
||||
|
||||
## 6. Collision Policy
|
||||
|
||||
Reserved shells receive no special collision privilege.
|
||||
|
||||
Rules:
|
||||
|
||||
- if an imported builtin shell declaration and another visible declaration produce the same visible name in the same namespace, the program is rejected under the ordinary collision rules already chosen,
|
||||
- if a host owner shares a spelling with a type or value, that alone is not a conflict because host-owner namespace remains distinct,
|
||||
- and reserved-shell status does not authorize silent shadowing.
|
||||
|
||||
## 7. Reserved Project-Space Policy
|
||||
|
||||
For source-level policy:
|
||||
|
||||
- builtin shells are preferred under `@core:*`,
|
||||
- host-facing capability surfaces remain the natural fit for `@sdk:*`.
|
||||
|
||||
This is a policy direction for clarity and separation of concerns.
|
||||
It does not change the underlying ownership model governed by other specs.
|
||||
|
||||
## 8. Failure Ownership Baseline
|
||||
|
||||
The current baseline is:
|
||||
|
||||
- failure to resolve a reserved stdlib module remains manifest/import resolution,
|
||||
- import of a non-exported reserved shell remains linking,
|
||||
- member lookup failure on an already-typed builtin receiver remains static semantics,
|
||||
- duplicate canonical builtin or host identities in one resolved environment remain linking failures.
|
||||
|
||||
Implementations may internally perform some of these checks during environment validation, but the normative external phase ownership is linking where the linking-phase decision assigns it.
|
||||
|
||||
## 9. Invariants
|
||||
|
||||
- Reserved-shell metadata does not create special source-level lookup priority.
|
||||
- Builtin intrinsic methods are never free functions in source-level lookup.
|
||||
- Builtin simple types remain separate from stdlib-delivered builtin shells.
|
||||
- Host owners remain in the host-owner namespace only.
|
||||
- Ordinary collision rules apply to reserved-shell imports unless a later explicit rule says otherwise.
|
||||
- Canonical identity conflicts are linking problems, not syntax problems.
|
||||
|
||||
## 10. Explicit Non-Decisions
|
||||
|
||||
This decision record does not yet close:
|
||||
|
||||
- the full stdlib-surface policy of `18. Standard Library Surface Specification.md`,
|
||||
- and the final lowering consequences in `12. IR and Lowering Specification.md`.
|
||||
|
||||
## 11. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md`
|
||||
- `docs/pbs/specs/18. Standard Library Surface Specification.md`
|
||||
- `docs/pbs/specs/11. Diagnostics Specification.md`
|
||||
|
||||
It should also constrain future work in:
|
||||
|
||||
- `docs/pbs/specs/12. IR and Lowering Specification.md`
|
||||
|
||||
## 12. Validation Notes
|
||||
|
||||
The intended baseline is:
|
||||
|
||||
- reserved builtin shells are imported like ordinary declarations into the matching namespace,
|
||||
- builtin methods are found only through receiver-member lookup,
|
||||
- builtin simple types remain always available without import,
|
||||
- `@core:*` is the preferred home for builtin shells,
|
||||
- and duplicate canonical builtin or host identities are rejected at linking time.
|
||||
|
||||
Illustrative examples:
|
||||
|
||||
```pbs
|
||||
import { Vec2 } from @core:math;
|
||||
```
|
||||
|
||||
`Vec2` becomes an imported visible type declaration with builtin metadata.
|
||||
|
||||
```pbs
|
||||
import { Vec2 } from @core:math;
|
||||
Vec2.zero()
|
||||
```
|
||||
|
||||
If `zero` is a builtin intrinsic member, it resolves through builtin member lookup on `Vec2`-typed receiver use and not through free callable lookup by the name `zero`.
|
||||
|
||||
```pbs
|
||||
import { Vec2 } from @core:math;
|
||||
declare const Vec2: int = 1;
|
||||
```
|
||||
|
||||
This is rejected as an ordinary same-namespace collision rather than resolved by reserved-shell priority.
|
||||
+173
@@ -0,0 +1,173 @@
|
||||
# Name Resolution - Callable Sets and Cross-Module Linking Decision
|
||||
|
||||
Status: Proposed
|
||||
Cycle: Initial name-resolution closure pass
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 needs a deterministic rule for how callable names cross module boundaries.
|
||||
|
||||
The open questions were:
|
||||
|
||||
- what exactly `import { f } from @project:path;` imports when `f` has multiple exported signatures,
|
||||
- whether callable sets from different origins may merge,
|
||||
- whether same-name imported callables from different origins are tolerated until callsite analysis,
|
||||
- whether local and imported callable names may coexist under one visible function name,
|
||||
- and how `mod.barrel` bounds the callable set that becomes importable.
|
||||
|
||||
Earlier closure already fixed important inputs:
|
||||
|
||||
- `mod.barrel` is the single source of module visibility,
|
||||
- only `pub` names may be imported from another module,
|
||||
- local function names and imported function names with the same visible name are already being treated as collisions in this closure pass,
|
||||
- and callable identity is determined by callable shape rather than parameter-label spelling alone.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following baseline for callable sets and cross-module linking:
|
||||
|
||||
1. `import { f } from @project:path;` imports the exported callable set named `f` from the target module.
|
||||
2. The imported callable set for `f` consists only of those overload signatures of `f` that are exported through that module's `mod.barrel`.
|
||||
3. Non-exported overloads in the target module do not participate in the imported callable set.
|
||||
4. Two imports of the same visible callable name are tolerated when they resolve to the same canonical underlying callable-set origin after module resolution.
|
||||
5. Such same-origin duplicate imports are redundant but not errors.
|
||||
6. Two imports of the same visible callable name from different canonical origins are rejected immediately.
|
||||
7. The program must not wait until a callsite to reject different-origin callable-name collisions.
|
||||
8. A module-local function name and an imported function name with the same visible name are rejected immediately.
|
||||
9. Automatic merging of callable sets across different origins is not permitted in this closure pass.
|
||||
10. Ordinary overload resolution occurs only after one unambiguous visible callable set has already been formed.
|
||||
|
||||
## 3. Imported Callable Set
|
||||
|
||||
The meaning of:
|
||||
|
||||
```pbs
|
||||
import { f } from @project:path;
|
||||
```
|
||||
|
||||
is:
|
||||
|
||||
- resolve the target module,
|
||||
- collect the exported callable entries named `f` from that module,
|
||||
- form the callable set consisting only of those exported overloads,
|
||||
- and make that callable set visible locally under the imported visible name.
|
||||
|
||||
This import does not:
|
||||
|
||||
- reach non-exported overloads,
|
||||
- merge with hidden module-internal overloads,
|
||||
- or import one overload at a time independently from the exported callable name.
|
||||
|
||||
## 4. Same-Origin Versus Different-Origin Imports
|
||||
|
||||
### 4.1 Same origin
|
||||
|
||||
If the same visible callable name is imported more than once and both imports resolve to the same canonical underlying callable-set origin:
|
||||
|
||||
- the duplicate import is tolerated,
|
||||
- but it remains redundant.
|
||||
|
||||
### 4.2 Different origin
|
||||
|
||||
If the same visible callable name is imported from different canonical origins:
|
||||
|
||||
- the program is rejected immediately,
|
||||
- and one of the imports must be removed or aliased.
|
||||
|
||||
The implementation must not:
|
||||
|
||||
- merge the callable sets,
|
||||
- defer the conflict to overload resolution,
|
||||
- or allow callsite context to decide which imported origin wins.
|
||||
|
||||
## 5. Local Versus Imported Callable Names
|
||||
|
||||
If a module-local function name and an imported function name are the same visible callable name:
|
||||
|
||||
- the program is rejected immediately,
|
||||
- and the implementation must not merge the local and imported callable sets.
|
||||
|
||||
This preserves deterministic visibility and keeps callable origin traceable.
|
||||
|
||||
## 6. Barrel Boundary
|
||||
|
||||
`mod.barrel` defines the exact boundary of the callable set that may cross module boundaries.
|
||||
|
||||
Rules:
|
||||
|
||||
- only overloads exported through `mod.barrel` are part of the importable callable set,
|
||||
- overloads with the same source-level function name but not exported through `mod.barrel` are invisible to importing modules,
|
||||
- and imported callable-set visibility is therefore a direct consequence of the source module's barrel contract.
|
||||
|
||||
## 7. Overload Resolution Boundary
|
||||
|
||||
This decision deliberately separates:
|
||||
|
||||
- callable-set formation,
|
||||
- and overload resolution at a callsite.
|
||||
|
||||
The implementation must first form one unambiguous visible callable set.
|
||||
Only then may ordinary overload resolution operate on the candidate signatures of that set.
|
||||
|
||||
Callsite context must not be used to resolve ambiguity between different imported callable origins.
|
||||
|
||||
## 8. Invariants
|
||||
|
||||
- Imported callable visibility is bounded by barrel export.
|
||||
- Different callable origins must not merge automatically.
|
||||
- Same-origin duplicate imports may be tolerated as redundancy, not as new callable contributions.
|
||||
- Local and imported function names do not coexist under one merged visible callable name in this closure pass.
|
||||
- Overload resolution happens after visible callable-set formation, not instead of it.
|
||||
|
||||
## 9. Explicit Non-Decisions
|
||||
|
||||
This decision record does not yet close:
|
||||
|
||||
- per-overload import syntax,
|
||||
- aliasing policy for callable imports beyond the already-closed generic alias rules,
|
||||
- and any lowering consequences in `12. IR and Lowering Specification.md`.
|
||||
|
||||
## 10. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md`
|
||||
- `docs/pbs/specs/11. Diagnostics Specification.md`
|
||||
- `docs/pbs/specs/13. Conformance Test Specification.md`
|
||||
|
||||
It should also constrain future work in:
|
||||
|
||||
- `docs/pbs/specs/12. IR and Lowering Specification.md`
|
||||
|
||||
## 11. Validation Notes
|
||||
|
||||
The intended baseline is:
|
||||
|
||||
- callable imports operate on exported callable names,
|
||||
- all exported overloads of that name come together from one module,
|
||||
- same-origin duplicate imports are tolerated,
|
||||
- different-origin same-name imports are rejected immediately,
|
||||
- and local/import callable collisions are also rejected immediately.
|
||||
|
||||
Illustrative examples:
|
||||
|
||||
```pbs
|
||||
import { f } from @a:m;
|
||||
import { f } from @a:m;
|
||||
```
|
||||
|
||||
This is tolerated as redundant same-origin duplication.
|
||||
|
||||
```pbs
|
||||
import { f } from @a:m;
|
||||
import { f } from @b:n;
|
||||
```
|
||||
|
||||
This is rejected immediately because the visible callable names match but the canonical origins differ.
|
||||
|
||||
```pbs
|
||||
fn f(a: int) -> int { ... }
|
||||
import { f } from @a:m;
|
||||
```
|
||||
|
||||
This is rejected as a local-versus-import callable collision.
|
||||
@@ -0,0 +1,200 @@
|
||||
# Name Resolution - Linking Phase Boundary Decision
|
||||
|
||||
Status: Proposed
|
||||
Cycle: Initial name-resolution closure pass
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 needs an explicit phase boundary around source-level name resolution so that:
|
||||
|
||||
- frontend implementation does not invent phase ownership,
|
||||
- diagnostics can attribute failures consistently,
|
||||
- conformance can test rejection classes coherently,
|
||||
- and later lowering work does not have to guess whether a failure belongs to syntax, linking, or typing.
|
||||
|
||||
Earlier closure already established rules for:
|
||||
|
||||
- module scope construction,
|
||||
- import naming and aliasing,
|
||||
- builtin shell visibility,
|
||||
- callable-set visibility across modules.
|
||||
|
||||
The remaining open question was how to classify the failure classes that arise while assembling visible declarations across files and modules.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following normative phase baseline for name resolution and related frontend failures:
|
||||
|
||||
1. `syntax` is a distinct normative phase.
|
||||
2. `manifest/import resolution` is a distinct normative phase.
|
||||
3. `linking` is a distinct normative phase.
|
||||
4. `static semantics` is a distinct normative phase.
|
||||
5. `syntax` owns malformed import grammar and other token-shape or grammar-shape failures.
|
||||
6. `manifest/import resolution` owns failures to resolve project space, reserved stdlib space, dependency graph, module path, or environment source.
|
||||
7. `linking` owns assembly of visible declarations across files and modules.
|
||||
8. `linking` therefore owns:
|
||||
- import of non-exported names,
|
||||
- unresolved barrel entries against module declarations,
|
||||
- collisions between visible imported names from different canonical origins,
|
||||
- local-versus-import visibility collisions,
|
||||
- callable-origin conflicts across module boundaries,
|
||||
- and duplicate canonical builtin or host identities in one resolved environment.
|
||||
9. `static semantics` owns declaration validity, type checking, member lookup once the receiver type is known, and overload resolution within an already-formed visible callable set.
|
||||
10. Member lookup failure on an already-typed builtin receiver belongs to `static semantics`.
|
||||
11. Ambiguity between different imported origins must be rejected in `linking` before any callsite analysis.
|
||||
|
||||
## 3. Phase Roles
|
||||
|
||||
### 3.1 Syntax
|
||||
|
||||
`syntax` owns failures that arise before module or declaration assembly.
|
||||
|
||||
Examples:
|
||||
|
||||
- malformed import declaration shape,
|
||||
- malformed alias syntax,
|
||||
- malformed declaration grammar,
|
||||
- unexpected tokens.
|
||||
|
||||
### 3.2 Manifest and Import Resolution
|
||||
|
||||
`manifest/import resolution` owns failures of locating and loading the source of a module or reserved environment.
|
||||
|
||||
Examples:
|
||||
|
||||
- unresolved `@project:*` dependency target,
|
||||
- unresolved reserved stdlib module,
|
||||
- invalid project-space selection,
|
||||
- failure to load the module source from the selected environment.
|
||||
|
||||
### 3.3 Linking
|
||||
|
||||
`linking` owns the assembly of the visible declaration space after modules have been found and loaded.
|
||||
|
||||
Examples:
|
||||
|
||||
- imported name is not exported by the target module,
|
||||
- `mod.barrel` entry does not resolve against declarations of the module,
|
||||
- two imports expose the same visible name from different canonical origins,
|
||||
- a local visible declaration collides with an imported visible declaration,
|
||||
- callable-origin conflicts across module boundaries,
|
||||
- duplicate canonical builtin identities in one resolved environment,
|
||||
- duplicate canonical host identities in one resolved environment.
|
||||
|
||||
### 3.4 Static Semantics
|
||||
|
||||
`static semantics` owns validation and typing of the already-linked visible program.
|
||||
|
||||
Examples:
|
||||
|
||||
- duplicate local declarations,
|
||||
- invalid declaration validity conditions,
|
||||
- type mismatch,
|
||||
- member lookup on a known receiver type,
|
||||
- overload resolution inside one already-visible callable set.
|
||||
|
||||
## 4. Linking As A Real Normative Phase
|
||||
|
||||
PBS keeps `linking` as a distinct normative phase rather than collapsing it fully into `static semantics`.
|
||||
|
||||
Reasoning:
|
||||
|
||||
- some failures arise only when assembling visible declarations across files and modules,
|
||||
- those failures are neither pure grammar failures nor ordinary local typing failures,
|
||||
- and naming `linking` gives diagnostics and conformance a stable vocabulary for them.
|
||||
|
||||
This does not require every implementation to expose one identical internal compiler pass graph.
|
||||
It only requires the externally visible failure ownership to map back to this normative phase model.
|
||||
|
||||
## 5. Barrel Matching And Visible Assembly
|
||||
|
||||
`mod.barrel` matching belongs to `linking`.
|
||||
|
||||
This means:
|
||||
|
||||
- failure of a barrel item to resolve to a declaration of the module is not merely a syntax issue,
|
||||
- and it is not deferred until later typing or lowering.
|
||||
|
||||
Barrel matching is part of assembling the module's visible declaration contract.
|
||||
|
||||
## 6. Imported-Origin Conflicts
|
||||
|
||||
Conflicts between different imported origins are rejected in `linking` immediately.
|
||||
|
||||
This means:
|
||||
|
||||
- the implementation must not wait for a specific callsite or use-site,
|
||||
- overload resolution is not allowed to rescue ambiguity between different imported origins,
|
||||
- and visible declaration conflicts are resolved structurally before later typing work proceeds.
|
||||
|
||||
## 7. Builtin Receiver Lookup
|
||||
|
||||
Member lookup on a builtin receiver whose type is already known remains `static semantics`.
|
||||
|
||||
The reason is:
|
||||
|
||||
- by that point the relevant shell visibility work has already completed,
|
||||
- and the remaining question is ordinary typed member validity rather than module assembly.
|
||||
|
||||
## 8. Invariants
|
||||
|
||||
- The phase model exposed to users and conformance must remain deterministic.
|
||||
- `linking` remains the phase for visible declaration assembly across module boundaries.
|
||||
- Callsite analysis must not be used to resolve imported-origin conflicts.
|
||||
- `static semantics` operates on an already-linked visible declaration space.
|
||||
- Syntax and manifest/import resolution remain narrower than linking and do not absorb visible-name conflicts that arise only after module loading.
|
||||
|
||||
## 9. Explicit Non-Decisions
|
||||
|
||||
This decision record does not yet close:
|
||||
|
||||
- the full diagnostics-code taxonomy,
|
||||
- whether implementations expose one explicit user-facing `linking` label or a mapped equivalent wording class,
|
||||
- the final artifact-facing phase vocabulary after lowering and verification specs close,
|
||||
- and the exact implementation architecture of one compiler pipeline.
|
||||
|
||||
## 10. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md`
|
||||
- `docs/pbs/specs/11. Diagnostics Specification.md`
|
||||
- `docs/pbs/specs/13. Conformance Test Specification.md`
|
||||
|
||||
It should also constrain future work in:
|
||||
|
||||
- `docs/pbs/specs/12. IR and Lowering Specification.md`
|
||||
- `docs/pbs/decisions/Name Resolution - Scope, Lookup, and Imports Decision.md`
|
||||
- `docs/pbs/decisions/Name Resolution - Builtin Shells and Host Owners Decision.md`
|
||||
- `docs/pbs/decisions/Name Resolution - Callable Sets and Cross-Module Linking Decision.md`
|
||||
|
||||
## 11. Validation Notes
|
||||
|
||||
The intended phase split is:
|
||||
|
||||
- `syntax` parses declaration and import shape,
|
||||
- `manifest/import resolution` finds and loads modules,
|
||||
- `linking` assembles visible names across modules and barrels,
|
||||
- `static semantics` validates and types the already-linked visible program.
|
||||
|
||||
Illustrative examples:
|
||||
|
||||
```pbs
|
||||
import { Missing } from @a:m;
|
||||
```
|
||||
|
||||
If `@a:m` resolves successfully but does not export `Missing`, this is a `linking` failure.
|
||||
|
||||
```pbs
|
||||
import { f } from @a:m;
|
||||
import { f } from @b:n;
|
||||
```
|
||||
|
||||
If the canonical origins differ, this is a `linking` failure and is rejected before any callsite analysis.
|
||||
|
||||
```pbs
|
||||
import { Vec2 } from @core:math;
|
||||
value.zero()
|
||||
```
|
||||
|
||||
If `value` is already known to have builtin type `Vec2` and `.zero` is not a valid member on that receiver type, the failure is `static semantics`.
|
||||
@@ -0,0 +1,270 @@
|
||||
# Name Resolution - Scope, Lookup, and Imports Decision
|
||||
|
||||
Status: Proposed
|
||||
Cycle: Initial name-resolution closure pass
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 needs a deterministic frontend-visible rule for:
|
||||
|
||||
- how module scope is formed,
|
||||
- how lookup works by namespace,
|
||||
- what imports actually introduce into local scope,
|
||||
- how collisions between local and imported names are handled,
|
||||
- and which failures belong to syntax, manifest/import resolution, static semantics, or linking.
|
||||
|
||||
Existing specs already fix important inputs:
|
||||
|
||||
- `mod.barrel` is the single source of module visibility,
|
||||
- imports target modules, not files,
|
||||
- only `pub` names may be imported from another module,
|
||||
- PBS has distinct type, value, callable, and host-owner namespaces,
|
||||
- builtin simple types `int`, `float`, `bool`, and `str` are always available in type position,
|
||||
- and reserved stdlib project spaces resolve only from the selected stdlib environment.
|
||||
|
||||
The remaining goal of this decision is to close the minimum name-resolution baseline needed for normative frontend work around ordinary scope construction, ordinary lookup, and import naming.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following baseline for scope construction, lookup, and imports:
|
||||
|
||||
1. Top-level declarations of a module are collected across all `.pbs` files in the module before visibility filtering is applied.
|
||||
2. `mod.barrel` is a visibility filter over existing module declarations, not the source of declaration existence.
|
||||
3. Module-internal top-level availability does not depend on source-file order.
|
||||
4. Local block scopes nest normally over module scope.
|
||||
5. In value position, lookup prefers the nearest lexical value binding before any module-level or imported value.
|
||||
6. Parameters and local `let` bindings participate in the same nearest lexical value-scope layer for lookup purposes.
|
||||
7. In type position, visible module-local type declarations are considered before imported type declarations, and builtin simple types remain always-available reserved type names outside ordinary import competition.
|
||||
8. In callable position, visible module-local callable declarations are considered before imported callable declarations.
|
||||
9. In host-owner position, visible module-local host owners are considered before imported host owners.
|
||||
10. The local visible name introduced by an import is always the post-alias name when an alias is present.
|
||||
11. `import { X } from @project:path;` introduces the imported exported name `X` into the matching namespace.
|
||||
12. `import { X as Y } from @project:path;` introduces only the local visible name `Y` into the matching namespace.
|
||||
13. Alias spelling changes only the local visible name, never canonical builtin identity or canonical host identity.
|
||||
14. `import { * } from @project:path;` is the whole-module import form for bringing the target module's exported names into local visibility under their exported names.
|
||||
15. A collision between a module-local declaration and an imported visible name in the same namespace is a deterministic error rather than silent shadowing.
|
||||
16. A collision between two imported visible names in the same namespace is not an error only when both imports denote the same canonical underlying declaration after module resolution.
|
||||
17. If two imported visible names in the same namespace come from different canonical underlying declarations, the program is rejected and one of the imports must be aliased or removed.
|
||||
18. `import { * } from @project:path;` does not create a first-class module object, module namespace value, or other source-visible binding by itself; it only introduces the exported names of the target module.
|
||||
19. A module-local function and an imported function with the same visible name produce a deterministic error in this closure pass.
|
||||
20. Non-callable namespaces do not merge by name.
|
||||
|
||||
## 3. Scope Construction
|
||||
|
||||
### 3.1 Module collection
|
||||
|
||||
For one module:
|
||||
|
||||
- the compiler collects top-level declarations from all `.pbs` files in that module,
|
||||
- forms one module-level declaration space,
|
||||
- then applies `mod.barrel` to determine `mod` and `pub` visibility.
|
||||
|
||||
This means:
|
||||
|
||||
- declaration existence is not derived from barrel entries,
|
||||
- and module-internal declaration availability is not ordered by file traversal.
|
||||
|
||||
### 3.2 Lexical scope
|
||||
|
||||
Inside executable bodies:
|
||||
|
||||
- lexical block scope is nested normally,
|
||||
- nearest local bindings win within value lookup,
|
||||
- and lexical nesting remains independent from cross-module visibility.
|
||||
|
||||
## 4. Lookup By Namespace
|
||||
|
||||
### 4.1 Value position
|
||||
|
||||
Value-position lookup follows this order:
|
||||
|
||||
1. nearest local lexical bindings,
|
||||
2. parameters in the current lexical function scope,
|
||||
3. visible module-local values,
|
||||
4. visible imported values.
|
||||
|
||||
For lookup purposes, parameters and local `let` bindings are one nearest lexical value layer.
|
||||
The distinction between them may still matter for diagnostics wording.
|
||||
|
||||
### 4.2 Type position
|
||||
|
||||
Type-position lookup follows this order:
|
||||
|
||||
1. visible module-local type declarations,
|
||||
2. visible imported type declarations,
|
||||
3. builtin simple types `int`, `float`, `bool`, and `str` as always-available reserved type names.
|
||||
|
||||
Builtin simple types are not treated as ordinary imported declarations and do not participate in ordinary import competition.
|
||||
|
||||
### 4.3 Callable position
|
||||
|
||||
Callable-position lookup follows this order:
|
||||
|
||||
1. visible module-local callables,
|
||||
2. visible imported callables.
|
||||
|
||||
If a visible module-local function name and a visible imported function name are the same, the program is rejected in this closure pass rather than merged.
|
||||
|
||||
### 4.4 Host-owner position
|
||||
|
||||
Host-owner lookup follows this order:
|
||||
|
||||
1. visible module-local host owners,
|
||||
2. visible imported host owners.
|
||||
|
||||
Host-owner lookup remains separate from type, value, and callable lookup.
|
||||
|
||||
## 5. Import Surface
|
||||
|
||||
### 5.1 Named import
|
||||
|
||||
`import { X } from @project:path;`:
|
||||
|
||||
- resolves the target module,
|
||||
- checks that `X` is exported and importable from that module,
|
||||
- and introduces `X` into the corresponding namespace locally.
|
||||
|
||||
### 5.2 Aliased import
|
||||
|
||||
`import { X as Y } from @project:path;`:
|
||||
|
||||
- resolves the same exported declaration as the non-aliased form,
|
||||
- but introduces only `Y` as the local visible name.
|
||||
|
||||
Alias spelling does not change canonical identity governed elsewhere.
|
||||
|
||||
### 5.3 Whole-module import
|
||||
|
||||
`import { * } from @project:path;`:
|
||||
|
||||
- validates and resolves the target module,
|
||||
- introduces the target module's exported visible names under their exported spellings,
|
||||
- but does not create a module-valued binding,
|
||||
- does not create a namespace object,
|
||||
- and does not authorize qualified member access by itself.
|
||||
|
||||
If PBS later wants module-object or namespace-qualified source semantics, that must be added explicitly rather than inferred from this form.
|
||||
|
||||
## 6. Collision Policy
|
||||
|
||||
### 6.1 Local versus imported
|
||||
|
||||
If a module-local declaration and an imported declaration produce the same visible name in the same namespace:
|
||||
|
||||
- the program is rejected,
|
||||
- and the implementation must not silently shadow the imported declaration or the local declaration.
|
||||
|
||||
This includes function names.
|
||||
In this closure pass, a local function and an imported function with the same visible name are rejected rather than merged.
|
||||
|
||||
### 6.2 Imported versus imported
|
||||
|
||||
If two imports produce the same visible name in the same namespace:
|
||||
|
||||
- the program is not rejected if both imports resolve to the same canonical underlying declaration after module resolution,
|
||||
- but the duplicate import is still redundant,
|
||||
- and the program is rejected if the imports resolve to different canonical underlying declarations.
|
||||
|
||||
### 6.3 Namespace separation
|
||||
|
||||
Names in different namespaces do not collide merely by spelling.
|
||||
|
||||
For example:
|
||||
|
||||
- a host owner and a type declaration do not collide by spelling alone,
|
||||
- because host-owner namespace remains distinct from type namespace.
|
||||
|
||||
## 7. Relationship To Later Name-Resolution Decisions
|
||||
|
||||
This decision is intentionally limited to:
|
||||
|
||||
- ordinary scope construction,
|
||||
- ordinary namespace lookup,
|
||||
- import naming,
|
||||
- and ordinary collision policy.
|
||||
|
||||
Later name-resolution decisions close:
|
||||
|
||||
- reserved builtin shells and host owners,
|
||||
- callable-set visibility across modules,
|
||||
- and the final phase boundary between syntax, manifest/import resolution, linking, and static semantics.
|
||||
|
||||
## 8. Invariants
|
||||
|
||||
- Name lookup must be deterministic.
|
||||
- Module-internal top-level declaration availability must not depend on file order.
|
||||
- `mod.barrel` remains a visibility mechanism rather than a declaration source.
|
||||
- Imports must not invent first-class module-object semantics accidentally.
|
||||
- The effective visible name of an import is always the post-alias name when an alias is present.
|
||||
- Builtin simple types remain a reserved always-available core type set, distinct from ordinary imported declarations.
|
||||
- Implementations must not assume silent local-over-import shadowing.
|
||||
- Implementations must not merge local and imported function names automatically.
|
||||
|
||||
## 9. Explicit Non-Decisions
|
||||
|
||||
This decision record does not yet close:
|
||||
|
||||
- reserved-shell-specific lookup and collision details,
|
||||
- callable-set import behavior across module boundaries beyond the local-versus-import collision baseline,
|
||||
- and backend-facing lowering consequences of the resolved lookup model.
|
||||
|
||||
## 10. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md`
|
||||
- `docs/pbs/specs/11. Diagnostics Specification.md`
|
||||
- `docs/pbs/specs/13. Conformance Test Specification.md`
|
||||
|
||||
It should also constrain future work in:
|
||||
|
||||
- `docs/pbs/specs/12. IR and Lowering Specification.md`
|
||||
- `docs/pbs/decisions/Name Resolution - Builtin Shells and Host Owners Decision.md`
|
||||
- `docs/pbs/decisions/Name Resolution - Callable Sets and Cross-Module Linking Decision.md`
|
||||
- `docs/pbs/decisions/Name Resolution - Linking Phase Boundary Decision.md`
|
||||
|
||||
## 11. Validation Notes
|
||||
|
||||
The intended baseline is:
|
||||
|
||||
- all top-level declarations in a module exist before barrel filtering,
|
||||
- lookup is namespace-specific and deterministic,
|
||||
- the effective visible import name is the alias name when an alias is present,
|
||||
- whole-module import through `import { * } from @project:path;` introduces exported names rather than a module object,
|
||||
- local/import collisions are rejected rather than shadowed,
|
||||
- and builtin simple types remain reserved always-available names outside ordinary import competition.
|
||||
|
||||
Illustrative examples:
|
||||
|
||||
```pbs
|
||||
import { Foo } from @a:m;
|
||||
declare const Foo: int = 1;
|
||||
```
|
||||
|
||||
This is rejected as a local-versus-import collision in the value namespace.
|
||||
|
||||
```pbs
|
||||
import { f } from @a:m;
|
||||
import { f } from @b:n;
|
||||
```
|
||||
|
||||
This is rejected because the visible imported names match but the canonical origins differ.
|
||||
|
||||
```pbs
|
||||
fn f(a: int) -> int { ... }
|
||||
import { f } from @a:m;
|
||||
```
|
||||
|
||||
This is rejected as a local-versus-import collision in callable position.
|
||||
|
||||
```pbs
|
||||
import { * } from @a:m;
|
||||
```
|
||||
|
||||
This introduces the exported visible names of `@a:m`, but does not introduce a source-visible module object in v1.
|
||||
|
||||
```pbs
|
||||
import { A as aaa } from @a:m;
|
||||
```
|
||||
|
||||
The visible local declaration name is `aaa`, not `A`.
|
||||
Reference in New Issue
Block a user