integrated 14 into specs
This commit is contained in:
@@ -141,5 +141,3 @@ This workshop should produce:
|
||||
- `docs/pbs/specs/13. Conformance Test Specification.md`
|
||||
- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md`
|
||||
- `docs/pbs/agendas/11. Diagnostics Agenda.md`
|
||||
- `docs/pbs/agendas/14.4. Name Resolution Workshop 4 - Linking Phase Boundary.md`
|
||||
|
||||
|
||||
@@ -114,5 +114,3 @@ Rationale:
|
||||
- `docs/pbs/specs/12. IR and Lowering Specification.md`
|
||||
- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md`
|
||||
- `docs/pbs/agendas/12. IR and Lowering Agenda.md`
|
||||
- `docs/pbs/agendas/14.4. Name Resolution Workshop 4 - Linking Phase Boundary.md`
|
||||
|
||||
|
||||
@@ -1,117 +0,0 @@
|
||||
# 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?
|
||||
|
||||
## Proposed Workshop Sequence
|
||||
|
||||
### Workshop 1: Scope, Lookup, and Imports
|
||||
|
||||
Purpose:
|
||||
|
||||
- close module scope construction,
|
||||
- close lookup order by namespace,
|
||||
- and close import alias and ambiguity rules.
|
||||
|
||||
Reference:
|
||||
|
||||
- `docs/pbs/agendas/14.1. Name Resolution Workshop 1 - Scope, Lookup, and Imports.md`
|
||||
|
||||
### Workshop 2: Builtin Shells and Host Owners
|
||||
|
||||
Purpose:
|
||||
|
||||
- close how reserved stdlib shells enter resolution,
|
||||
- and close lookup and collision policy for builtin types, builtin constants, intrinsic members, and host owners.
|
||||
|
||||
Expected decisions:
|
||||
|
||||
- reserved-shell visibility model,
|
||||
- builtin and host-owner lookup interaction,
|
||||
- and canonical identity versus local aliasing boundaries.
|
||||
|
||||
### Workshop 3: Callable Sets and Cross-Module Linking
|
||||
|
||||
Purpose:
|
||||
|
||||
- close overload-set formation across module boundaries,
|
||||
- and decide ambiguity and rejection rules for imported callable sets.
|
||||
|
||||
Expected decisions:
|
||||
|
||||
- callable-set merge rules,
|
||||
- barrel-matching consequences for imported overloads,
|
||||
- and cross-module ambiguity failures.
|
||||
|
||||
### Workshop 4: Linking Phase Boundary
|
||||
|
||||
Purpose:
|
||||
|
||||
- decide which rules belong to static semantics versus a distinct linking phase.
|
||||
|
||||
Expected decisions:
|
||||
|
||||
- phase split or collapse,
|
||||
- rejection ownership by phase,
|
||||
- and inputs needed by `11`, `12`, and frontend conformance.
|
||||
|
||||
## 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`
|
||||
@@ -1,184 +0,0 @@
|
||||
# PBS Name Resolution Workshop 1
|
||||
|
||||
Status: Active
|
||||
|
||||
## Purpose
|
||||
|
||||
Run the first focused discussion for `14. Name Resolution and Module Linking Specification.md` on the smallest set of decisions that unlocks normative frontend work:
|
||||
|
||||
- scope construction,
|
||||
- namespace-specific lookup order,
|
||||
- import visibility,
|
||||
- and ambiguity rejection.
|
||||
|
||||
## Why This Slice First
|
||||
|
||||
This slice is the best first cut because it does not require full lowering closure, but it does unblock:
|
||||
|
||||
- parser and binder architecture,
|
||||
- symbol-table modeling,
|
||||
- deterministic frontend diagnostics,
|
||||
- and the later discussion of overload visibility and reserved stdlib shells.
|
||||
|
||||
It should intentionally avoid trying to close every linking edge case in one meeting.
|
||||
|
||||
## Proposed Meeting Order
|
||||
|
||||
1. Confirm already-settled inputs that are not up for debate.
|
||||
2. Close scope-construction rules inside one module.
|
||||
3. Close lookup order by namespace.
|
||||
4. Close import visibility and alias rules.
|
||||
5. Close ambiguity and duplicate rejection rules.
|
||||
6. Record deferred items for a second workshop.
|
||||
|
||||
## Already-Settled Inputs To Reconfirm
|
||||
|
||||
The meeting should start by explicitly reaffirming:
|
||||
|
||||
- `mod.barrel` is the single source of module visibility.
|
||||
- Imports target modules, not files.
|
||||
- Only `pub` names are importable from another module.
|
||||
- PBS has distinct type, value, callable, and host-owner namespaces.
|
||||
- Builtin simple types `int`, `float`, `bool`, and `str` are always present in type position.
|
||||
- Reserved stdlib spaces resolve from the selected stdlib environment, not from ordinary dependencies.
|
||||
|
||||
These points already come from existing specs and should not be reopened in this workshop.
|
||||
|
||||
## Decisions To Produce
|
||||
|
||||
1. Scope construction inside a module.
|
||||
2. Lookup order in value, type, callable, and host-owner position.
|
||||
3. Import alias behavior and collisions.
|
||||
4. Ambiguity rules when multiple imports expose the same visible name.
|
||||
5. The phase boundary between syntax, static semantics, and linking for these failures.
|
||||
|
||||
## Candidate Decisions
|
||||
|
||||
### 1. Scope Construction Inside One Module
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- File-local top-level declarations are collected first from all `.pbs` files in the module.
|
||||
- `mod.barrel` is then applied as a visibility filter over the already-collected top-level declarations.
|
||||
- Top-level declaration availability inside the same module does not depend on source-file order.
|
||||
- Local block scopes nest normally over module scope.
|
||||
|
||||
Rationale:
|
||||
|
||||
- This matches the existing module model.
|
||||
- It prevents file-order-dependent lookup.
|
||||
- It keeps barrel as a visibility mechanism, not as the source of declaration existence.
|
||||
|
||||
### 2. Lookup Order By Namespace
|
||||
|
||||
Candidate direction:
|
||||
|
||||
Value position:
|
||||
|
||||
- nearest local bindings,
|
||||
- parameters,
|
||||
- visible `declare const`,
|
||||
- visible imported values,
|
||||
- service singleton values introduced by visible service declarations.
|
||||
|
||||
Type position:
|
||||
|
||||
- nearest type declarations visible in module scope,
|
||||
- visible imported type declarations,
|
||||
- builtin simple types.
|
||||
|
||||
Callable position:
|
||||
|
||||
- nearest callable declarations visible in module scope,
|
||||
- then visible imported callable declarations,
|
||||
- with overload sets formed after visibility filtering.
|
||||
|
||||
Host-owner position:
|
||||
|
||||
- visible host owners in module scope,
|
||||
- then visible imported host owners.
|
||||
|
||||
Open point for discussion:
|
||||
|
||||
- whether builtin simple types should be treated as implicit outermost scope or as a final fallback outside ordinary visible declarations.
|
||||
|
||||
### 3. Import Alias Rules
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- `import @project:mod;` imports the module itself as a module-qualified reference surface only if another spec later defines such a surface.
|
||||
- For current v1 name resolution, named imports are the only source of imported visible names.
|
||||
- `import { X } from ...;` introduces `X` in the matching namespace of the exported declaration.
|
||||
- `import { X as Y } from ...;` introduces only `Y` locally.
|
||||
- Alias spelling affects only the local visible name, never canonical builtin or host identity.
|
||||
|
||||
Rationale:
|
||||
|
||||
- Keeps current source behavior conservative.
|
||||
- Avoids inventing module-as-value semantics accidentally.
|
||||
- Matches the existing distinction between source-visible spelling and canonical metadata identity.
|
||||
|
||||
### 4. Collision And Ambiguity Rules
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- Two local declarations in the same namespace that produce the same non-overload identity are duplicates.
|
||||
- A local declaration and an imported declaration with the same visible name in the same namespace are a deterministic conflict unless one rule explicitly allows shadowing.
|
||||
- Two imported declarations with the same visible name in the same namespace are a deterministic ambiguity unless they are the same declaration reached through the same canonical module resolution.
|
||||
- Callable overload sets may merge only when their callable identities remain distinct after tuple-shape identity rules are applied.
|
||||
- Non-callable namespaces do not merge by name.
|
||||
|
||||
Open point for discussion:
|
||||
|
||||
- whether local declarations should fully shadow imports in value, type, callable, and host-owner namespaces, or whether PBS should reject such shadowing to keep lookup simpler for beginners.
|
||||
|
||||
### 5. Diagnostic Phase Boundary
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- malformed import syntax remains syntax-phase.
|
||||
- unresolved module path remains manifest/import-resolution phase.
|
||||
- import of non-exported symbol remains linking-phase or manifest/import-resolution-adjacent phase, but not syntax-phase.
|
||||
- duplicate local declarations remain static-semantics phase.
|
||||
- ambiguous visible names after import resolution remain linking-phase unless the project later collapses linking into static semantics explicitly.
|
||||
|
||||
Rationale:
|
||||
|
||||
- This preserves a clean split between parsing, declaration validity, and cross-module resolution.
|
||||
- It gives `11. Diagnostics Specification.md` a concrete input rather than forcing that spec to invent phases in isolation.
|
||||
|
||||
## Questions To Resolve In The Room
|
||||
|
||||
1. Do local top-level declarations shadow imported names, or is any such collision rejected?
|
||||
2. Are parameters and local `let` bindings one combined nearest-scope value layer, or should parameters be modeled separately for diagnostics only?
|
||||
3. Can imported overloads and local overloads merge into one callable set, or must that be rejected?
|
||||
4. Is `import @project:module;` currently just side-effect-free validation, or should it create any usable source-visible surface in v1?
|
||||
5. Do builtin simple types behave like reserved final fallback names or like ordinary always-visible type declarations?
|
||||
|
||||
## Expected Outputs
|
||||
|
||||
This workshop should produce:
|
||||
|
||||
1. a decision record for scope and lookup order,
|
||||
2. a decision record for import alias and ambiguity policy,
|
||||
3. a concrete update plan for `14. Name Resolution and Module Linking Specification.md`,
|
||||
4. and a list of deferred issues for Workshop 2.
|
||||
|
||||
## Explicit Deferrals For Workshop 2
|
||||
|
||||
The following topics should be deferred unless they become unavoidable:
|
||||
|
||||
- reserved stdlib shell priority versus ordinary imports,
|
||||
- member lookup on builtin receivers,
|
||||
- contract and method dispatch lookup details,
|
||||
- barrel matching of callable overload sets across module boundaries,
|
||||
- and whether linking is its own normative phase or is folded fully into static semantics.
|
||||
|
||||
## 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/14. Name Resolution and Module Linking Specification.md`
|
||||
- `docs/pbs/specs/18. Standard Library Surface Specification.md`
|
||||
- `docs/pbs/agendas/14. Name Resolution and Module Linking Agenda.md`
|
||||
-159
@@ -1,159 +0,0 @@
|
||||
# PBS Name Resolution Workshop 2
|
||||
|
||||
Status: Active
|
||||
|
||||
## Purpose
|
||||
|
||||
Run the second focused discussion for `14. Name Resolution and Module Linking Specification.md` on reserved stdlib shells and host-owner resolution:
|
||||
|
||||
- builtin type shells,
|
||||
- builtin constants,
|
||||
- intrinsic member surfaces,
|
||||
- and `declare host` owners imported from reserved stdlib modules.
|
||||
|
||||
## Why This Slice Second
|
||||
|
||||
This slice should come after Workshop 1 because it builds on already-closed rules for:
|
||||
|
||||
- module scope construction,
|
||||
- ordinary import visibility,
|
||||
- aliasing,
|
||||
- and namespace-specific lookup order.
|
||||
|
||||
It also prepares the ground for later lowering by making the resolution contract explicit without prematurely defining artifact shape.
|
||||
|
||||
## Proposed Meeting Order
|
||||
|
||||
1. Reconfirm already-settled ownership and stdlib-loading rules.
|
||||
2. Close the visibility model for builtin and host shells.
|
||||
3. Close lookup behavior for builtin types, builtin constants, and host owners.
|
||||
4. Close member resolution on builtin receivers.
|
||||
5. Close collision and ambiguity rules involving reserved shells.
|
||||
6. Record deferred callable-linking issues for Workshop 3.
|
||||
|
||||
## Already-Settled Inputs To Reconfirm
|
||||
|
||||
The meeting should explicitly reaffirm:
|
||||
|
||||
- reserved stdlib project spaces include `@core:*` and `@sdk:*`,
|
||||
- reserved stdlib spaces resolve only from the selected stdlib environment,
|
||||
- source-visible builtin names resolve through imported builtin shell declarations,
|
||||
- builtin intrinsic members are not imported as free functions,
|
||||
- canonical builtin and host identities come from metadata rather than local alias spelling,
|
||||
- and host-owner namespace remains distinct from type, value, and callable namespaces.
|
||||
|
||||
These are already fixed elsewhere and should not be reopened here.
|
||||
|
||||
## Decisions To Produce
|
||||
|
||||
1. Visibility rules for builtin shells and host owners imported from reserved stdlib modules.
|
||||
2. Lookup rules for builtin types, builtin constants, intrinsic members, and host owners.
|
||||
3. Collision and ambiguity rules when reserved shells overlap with ordinary user-visible declarations.
|
||||
4. Diagnostic ownership for reserved-shell resolution failures.
|
||||
5. Deferred boundary between source resolution and later lowering.
|
||||
|
||||
## Candidate Decisions
|
||||
|
||||
### 1. Reserved Shells Enter Resolution As Ordinary Visible Declarations
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- Imported builtin type shells become visible in the type namespace like other imported type declarations.
|
||||
- Imported builtin constants become visible in the value namespace like other imported constants.
|
||||
- Imported host owners become visible in the host-owner namespace like other imported host declarations.
|
||||
- Reserved metadata changes canonical lowering identity, not the ordinary namespace they enter.
|
||||
|
||||
Rationale:
|
||||
|
||||
- This keeps the source model uniform.
|
||||
- It avoids a hidden parallel lookup system just for reserved stdlib surfaces.
|
||||
- It matches the current specs that describe shells as imported declarations with metadata.
|
||||
|
||||
### 2. Builtin Simple Types Remain Separate From Imported Builtin Shells
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- `int`, `float`, `bool`, and `str` remain always-available builtin simple types.
|
||||
- Imported builtin shells such as `Vec2` or `Color` are ordinary visible type declarations and do not share special priority with builtin simple types.
|
||||
- User-authored declarations still cannot reuse builtin simple type names.
|
||||
|
||||
Rationale:
|
||||
|
||||
- Separates the small predeclared core from stdlib-delivered builtin shells.
|
||||
- Prevents `@core:*` imports from acting like implicit language keywords.
|
||||
|
||||
### 3. Intrinsic Members Resolve Through Receiver Type, Never Through Free Lookup
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- Builtin intrinsic methods are resolved only during member lookup on a builtin-typed receiver.
|
||||
- They do not appear in top-level callable lookup.
|
||||
- They do not become visible through named import by method name.
|
||||
- Alias changes to the builtin type affect only source spelling of the owner type, not intrinsic canonical identity.
|
||||
|
||||
Rationale:
|
||||
|
||||
- This matches the existing builtin and intrinsics spec.
|
||||
- It prevents accidental confusion between member semantics and free functions.
|
||||
|
||||
### 4. Collision Policy For Reserved Shells
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- Namespace collisions are handled by the same visibility rules used for ordinary declarations.
|
||||
- A user-visible imported builtin type colliding with another visible type name is a deterministic conflict unless an already-closed shadowing rule says otherwise.
|
||||
- A host owner colliding with a type or value name is not a conflict by itself because host-owner namespace is distinct.
|
||||
- Duplicate canonical builtin identities in one resolved environment remain rejection cases even if local aliases differ.
|
||||
|
||||
Open point for discussion:
|
||||
|
||||
- whether conflicts involving reserved shells should be rejected more aggressively than ordinary import conflicts to preserve beginner clarity.
|
||||
|
||||
### 5. Diagnostic Ownership
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- failure to resolve the reserved module remains manifest/import-resolution phase,
|
||||
- import of a non-exported builtin or host shell remains linking or resolution-phase rejection,
|
||||
- member lookup failure on a builtin receiver remains static-semantics or linking-phase depending on the final phase model,
|
||||
- duplicate canonical builtin or host identities in one resolved environment remain deterministic compile-time rejection.
|
||||
|
||||
Rationale:
|
||||
|
||||
- This keeps module loading, visibility, and member resolution separate.
|
||||
- It gives `11` a concrete discussion input later.
|
||||
|
||||
## Questions To Resolve In The Room
|
||||
|
||||
1. Should reserved shells be completely ordinary imported declarations at source level, or do any of them need special lookup priority?
|
||||
2. Can an ordinary user declaration shadow an imported builtin shell, or should that always be rejected?
|
||||
3. Is member lookup on builtin receivers purely a type-driven operation after receiver typing, or does name resolution need a separate reserved-shell step?
|
||||
4. Should `@sdk:*` be allowed to expose builtin shells, or should builtin shells remain policy-preferred under `@core:*` only?
|
||||
5. Which failures around canonical builtin identity belong to resolution, static semantics, or environment validation?
|
||||
|
||||
## Expected Outputs
|
||||
|
||||
This workshop should produce:
|
||||
|
||||
1. a decision record for reserved-shell visibility and lookup,
|
||||
2. a decision record for collision policy involving builtin and host shells,
|
||||
3. a concrete update plan for the reserved-shell sections of `14`,
|
||||
4. and a deferred list for cross-module callable-set discussion in Workshop 3.
|
||||
|
||||
## Explicit Deferrals For Workshop 3
|
||||
|
||||
The following topics should be deferred unless unavoidable:
|
||||
|
||||
- imported callable-set merging across modules,
|
||||
- overload resolution across ordinary and reserved callable surfaces,
|
||||
- contract dispatch lookup,
|
||||
- and whether linking is fully distinct from static semantics.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `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/14. Name Resolution and Module Linking Specification.md`
|
||||
- `docs/pbs/specs/18. Standard Library Surface 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`
|
||||
-160
@@ -1,160 +0,0 @@
|
||||
# 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`
|
||||
|
||||
@@ -1,144 +0,0 @@
|
||||
# PBS Name Resolution Workshop 4
|
||||
|
||||
Status: Active
|
||||
|
||||
## Purpose
|
||||
|
||||
Run the fourth focused discussion for `14. Name Resolution and Module Linking Specification.md` on phase ownership:
|
||||
|
||||
- what belongs to syntax,
|
||||
- what belongs to static semantics,
|
||||
- what belongs to module/linking,
|
||||
- and whether PBS keeps linking as a distinct normative phase at all.
|
||||
|
||||
## Why This Slice Last
|
||||
|
||||
This slice should come last because it is mostly a boundary-setting exercise over decisions already made in Workshops 1 through 3.
|
||||
|
||||
Trying to close it earlier would force abstract phase arguments before the actual failure classes were concrete.
|
||||
|
||||
## Proposed Meeting Order
|
||||
|
||||
1. Reconfirm the concrete failure categories identified in earlier workshops.
|
||||
2. Group those failures by source-only, module-resolution, and cross-module visibility concerns.
|
||||
3. Decide whether PBS names linking as a distinct normative phase.
|
||||
4. Decide how this boundary feeds diagnostics, conformance, and frontend implementation claims.
|
||||
5. Record any residual editorial cleanup for the spec integration pass.
|
||||
|
||||
## Failure Classes To Sort
|
||||
|
||||
This workshop should explicitly sort at least the following classes:
|
||||
|
||||
- malformed import syntax,
|
||||
- unresolved module path,
|
||||
- import of non-exported symbol,
|
||||
- duplicate local declarations,
|
||||
- ambiguous imported names,
|
||||
- callable-set ambiguity across modules,
|
||||
- builtin-receiver member lookup failure,
|
||||
- duplicate canonical builtin or host identities in one resolved environment,
|
||||
- and barrel entries that fail to resolve against module declarations.
|
||||
|
||||
## Decisions To Produce
|
||||
|
||||
1. Whether linking is a distinct normative phase in PBS v1.
|
||||
2. Ownership of the major failure classes already identified.
|
||||
3. The minimum phase vocabulary needed by diagnostics and conformance.
|
||||
4. The frontend implementation consequences of the chosen phase model.
|
||||
|
||||
## Candidate Decisions
|
||||
|
||||
### 1. Keep Linking As A Distinct Normative Phase
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- syntax owns grammar and token-shape failures,
|
||||
- static semantics owns declaration validity, typing, and callsite selection,
|
||||
- linking owns cross-file and cross-module visible-set formation and barrel/import matching.
|
||||
|
||||
Rationale:
|
||||
|
||||
- This gives a clean home to failures that are neither purely syntactic nor ordinary local typing.
|
||||
- It matches the practical compiler architecture implied by module loading and barrel visibility.
|
||||
- It gives `11` and `13` a usable phase vocabulary.
|
||||
|
||||
Alternative to discuss:
|
||||
|
||||
- collapse linking into static semantics and treat "linking" only as an implementation detail.
|
||||
|
||||
### 2. Module-Visibility And Import Failures Belong To Linking
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- unresolved exported-name lookup after the target module is loaded belongs to linking,
|
||||
- ambiguous imported visible names belong to linking,
|
||||
- callable-set ambiguity across modules belongs to linking,
|
||||
- and unresolved barrel entries belong to linking or module-linking rather than to syntax.
|
||||
|
||||
Rationale:
|
||||
|
||||
- These failures arise from assembling visible declarations across files or modules, not from parsing isolated declarations.
|
||||
|
||||
### 3. Callsite Selection Remains Static Semantics
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- once visible callable sets are formed, overload resolution at a callsite remains static semantics,
|
||||
- member lookup driven by the known receiver type also remains static semantics unless it fails earlier due to unresolved imported shell visibility.
|
||||
|
||||
Rationale:
|
||||
|
||||
- This keeps typing and callable selection together.
|
||||
- It prevents linking from becoming a catch-all bucket for any failure that mentions imports.
|
||||
|
||||
### 4. Diagnostics And Conformance Need Only A Small Stable Vocabulary
|
||||
|
||||
Candidate direction:
|
||||
|
||||
- the minimum normative phase vocabulary is:
|
||||
syntax,
|
||||
static semantics,
|
||||
manifest/import resolution,
|
||||
linking,
|
||||
and host-binding/capability admission.
|
||||
- tools may subdivide internally, but they should map back to that stable external vocabulary.
|
||||
|
||||
Rationale:
|
||||
|
||||
- This is enough for source-facing determinism without overfitting to one compiler pipeline.
|
||||
|
||||
## Questions To Resolve In The Room
|
||||
|
||||
1. Is there real value in naming linking as its own normative phase, or does that add conceptual weight without enough payoff?
|
||||
2. Should unresolved barrel entries be considered module-internal static invalidity or linking invalidity?
|
||||
3. Should builtin-receiver member lookup failure always stay in static semantics once receiver type is known?
|
||||
4. Do diagnostics and conformance need the word `linking`, or only a broader `resolution` bucket?
|
||||
5. Does the chosen phase model help or hinder future lowering and verifier specs?
|
||||
|
||||
## Expected Outputs
|
||||
|
||||
This workshop should produce:
|
||||
|
||||
1. a decision record for the PBS phase model around name resolution and linking,
|
||||
2. a sorted matrix of failure classes by phase,
|
||||
3. a concrete update plan for `14`,
|
||||
4. and explicit follow-ups for `11` and `13`.
|
||||
|
||||
## Explicit Deferrals
|
||||
|
||||
The following topics should be deferred unless unavoidable:
|
||||
|
||||
- detailed diagnostic code design,
|
||||
- artifact-level failure surfacing,
|
||||
- verifier and loader phase internals,
|
||||
- and optimizer or backend pipeline naming.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `docs/pbs/specs/11. Diagnostics Specification.md`
|
||||
- `docs/pbs/specs/13. Conformance Test 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`
|
||||
- `docs/pbs/agendas/14.3. Name Resolution Workshop 3 - Callable Sets and Cross-Module Linking.md`
|
||||
@@ -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`.
|
||||
@@ -1,29 +1,37 @@
|
||||
# PBS Name Resolution and Module Linking Specification
|
||||
|
||||
Status: Draft v0 (Skeleton)
|
||||
Status: Draft v1 (Normative)
|
||||
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.
|
||||
This document defines the normative name-resolution and semantic-linking model for PBS v1.
|
||||
|
||||
Its purpose is to make the visible declaration space of a PBS program deterministic enough that:
|
||||
|
||||
- frontend implementations do not invent lookup or collision rules,
|
||||
- diagnostics can classify failures consistently,
|
||||
- conformance can test source-facing rejection classes,
|
||||
- and lowering begins from an already-linked visible program.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document is intended to define:
|
||||
This document defines:
|
||||
|
||||
- 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.
|
||||
- module scope construction,
|
||||
- lookup order by namespace,
|
||||
- import and alias resolution,
|
||||
- barrel-mediated visibility,
|
||||
- reserved stdlib shell resolution for builtin and host-backed surfaces,
|
||||
- callable visibility across modules,
|
||||
- and linking-time rejection conditions before lowering.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- runtime execution behavior,
|
||||
- optimizer or backend internals,
|
||||
- full PBX binary linking.
|
||||
- full PBX binary linking,
|
||||
- or loader/runtime artifact behavior after lowering.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
@@ -34,8 +42,10 @@ Normative precedence:
|
||||
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
|
||||
6. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
7. `8. Stdlib Environment Packaging and Loading Specification.md`
|
||||
8. `18. Standard Library Surface Specification.md`
|
||||
9. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence specs, it is invalid.
|
||||
|
||||
@@ -48,6 +58,7 @@ This document depends on, at minimum:
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6. VM-owned vs Host-backed.md`
|
||||
- `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `8. Stdlib Environment Packaging and Loading Specification.md`
|
||||
- `18. Standard Library Surface Specification.md`
|
||||
|
||||
@@ -63,97 +74,300 @@ The following inputs are already fixed elsewhere and must not be contradicted he
|
||||
- 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.
|
||||
- Canonical host identity is governed by host metadata rather than by imported owner spelling alone.
|
||||
|
||||
## 6. Initial Section Targets
|
||||
## 6. Module Scope Construction
|
||||
|
||||
At minimum, the completed document should contain normative sections for:
|
||||
### 6.1 Module collection
|
||||
|
||||
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.
|
||||
For one module:
|
||||
|
||||
## 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.
|
||||
- the compiler collects top-level declarations from all `.pbs` files in that module,
|
||||
- forms one module-level declaration space,
|
||||
- and only then applies `mod.barrel` to determine `mod` and `pub` visibility.
|
||||
|
||||
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.
|
||||
- declaration existence is not derived from barrel entries,
|
||||
- module-internal top-level declaration availability does not depend on source-file order,
|
||||
- and `mod.barrel` is a visibility filter over existing declarations rather than a declaration source.
|
||||
|
||||
Example:
|
||||
### 6.2 Lexical scope
|
||||
|
||||
- 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)`.
|
||||
Inside executable bodies:
|
||||
|
||||
## 11. Import and Barrel Rules for Builtin Shells
|
||||
- lexical block scope nests normally over module scope,
|
||||
- nearest local bindings win within value lookup,
|
||||
- and lexical nesting remains independent from cross-module visibility.
|
||||
|
||||
Builtin shells follow ordinary module visibility rules at the source level and
|
||||
special metadata rules at lowering time.
|
||||
## 7. Lookup Order By Namespace
|
||||
|
||||
Lookup in PBS remains namespace-based.
|
||||
|
||||
### 7.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 participate in one nearest lexical value layer.
|
||||
|
||||
### 7.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,
|
||||
- do not participate in ordinary import competition,
|
||||
- and remain always available without import.
|
||||
|
||||
### 7.3 Callable position
|
||||
|
||||
Callable-position lookup follows this order:
|
||||
|
||||
1. visible module-local callables,
|
||||
2. visible imported callables.
|
||||
|
||||
Callable lookup operates only on already-formed visible callable sets as defined later in this document.
|
||||
|
||||
### 7.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.
|
||||
|
||||
## 8. Import Surface And Naming
|
||||
|
||||
### 8.1 Effective local imported name
|
||||
|
||||
The local visible name introduced by an import is always the post-alias name when an alias is present.
|
||||
|
||||
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.
|
||||
- `import { X } from @project:path;` introduces the visible local name `X`,
|
||||
- `import { X as Y } from @project:path;` introduces only the visible local name `Y`,
|
||||
- and alias spelling changes only the local visible name, never canonical builtin identity or canonical host identity.
|
||||
|
||||
## 12. Lookup Order for Builtin and Intrinsic Surfaces
|
||||
### 8.2 Named import
|
||||
|
||||
Lookup remains namespace-based.
|
||||
`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.
|
||||
|
||||
### 8.3 Whole-module import
|
||||
|
||||
`import { * } from @project:path;`:
|
||||
|
||||
- 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 import form.
|
||||
|
||||
## 9. Collision And Ambiguity Rules
|
||||
|
||||
### 9.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 either declaration.
|
||||
|
||||
This includes function names.
|
||||
A module-local function and an imported function with the same visible name are rejected rather than merged.
|
||||
|
||||
### 9.2 Imported versus imported
|
||||
|
||||
If two imports produce the same visible name in the same namespace:
|
||||
|
||||
- the program is not rejected only when both imports resolve to the same canonical underlying declaration after module resolution,
|
||||
- such same-origin duplication is redundant but tolerated,
|
||||
- and the program is rejected if the imports resolve to different canonical underlying declarations.
|
||||
|
||||
### 9.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.
|
||||
|
||||
### 9.4 Non-callable names do not merge
|
||||
|
||||
Non-callable namespaces do not merge by name.
|
||||
|
||||
## 10. Callable Sets And Cross-Module Linking
|
||||
|
||||
### 10.1 Imported callable set
|
||||
|
||||
`import { f } from @project:path;` imports the exported callable set named `f` from the target module.
|
||||
|
||||
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.
|
||||
- the imported callable set for `f` consists only of those overload signatures of `f` that are exported through that module's `mod.barrel`,
|
||||
- non-exported overloads in the target module do not participate in the imported callable set,
|
||||
- and import operates on the exported callable name rather than on one overload at a time.
|
||||
|
||||
This preserves the distinction between:
|
||||
### 10.2 Same-origin versus different-origin callable imports
|
||||
|
||||
- imported builtin type shells,
|
||||
- imported host owners,
|
||||
- and compiler-recognized intrinsic method surfaces on existing core forms such as `optional` and enums.
|
||||
If the same visible callable name is imported more than once:
|
||||
|
||||
- same-origin duplicate imports are tolerated as redundancy when they resolve to the same canonical callable-set origin,
|
||||
- different-origin imports are rejected immediately,
|
||||
- and the implementation must not wait until a callsite to reject different-origin callable-name collisions.
|
||||
|
||||
### 10.3 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.
|
||||
|
||||
### 10.4 Overload-resolution boundary
|
||||
|
||||
PBS separates:
|
||||
|
||||
- callable-set formation,
|
||||
- and overload resolution at a callsite.
|
||||
|
||||
Rules:
|
||||
|
||||
- the implementation must first form one unambiguous visible callable set,
|
||||
- only then may ordinary overload resolution operate on the candidate signatures of that set,
|
||||
- and callsite context must not be used to resolve ambiguity between different imported callable origins.
|
||||
|
||||
## 11. Reserved Stdlib Shell Resolution
|
||||
|
||||
### 11.1 Reserved shells as imported declarations
|
||||
|
||||
Source-visible declarations exposed by reserved builtin shells are imported into their ordinary corresponding namespaces.
|
||||
|
||||
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.
|
||||
|
||||
`declare builtin type` itself remains a reserved stdlib/toolchain declaration form rather than ordinary user-authored source syntax.
|
||||
|
||||
### 11.2 Builtin simple types versus imported builtin shells
|
||||
|
||||
PBS distinguishes:
|
||||
|
||||
- the predeclared builtin simple-type set `int`, `float`, `bool`, `str`,
|
||||
- and imported builtin shells such as `Vec2` or `Color`.
|
||||
|
||||
Imported builtin shells are not promoted to the same always-available status as builtin simple types.
|
||||
|
||||
### 11.3 Intrinsic member lookup
|
||||
|
||||
Builtin intrinsic methods:
|
||||
|
||||
- never participate in free lookup,
|
||||
- are not introduced by import as free functions,
|
||||
- and are resolved only through member lookup on a receiver already known to have the corresponding builtin type.
|
||||
|
||||
Alias changes to the imported builtin type affect only the local visible owner spelling, not the canonical builtin or intrinsic identity.
|
||||
|
||||
### 11.4 Collision policy for reserved shells
|
||||
|
||||
Reserved builtin shells and host owners follow the same collision policy as ordinary imported declarations.
|
||||
|
||||
Rules:
|
||||
|
||||
- same visible name in the same namespace is an error unless another already-closed rule explicitly permits otherwise,
|
||||
- reserved-shell status does not authorize silent shadowing,
|
||||
- and host owners do not collide with types or values merely by spelling because host-owner namespace remains separate.
|
||||
|
||||
### 11.5 Reserved project-space policy
|
||||
|
||||
For source-level policy:
|
||||
|
||||
- builtin shells are preferred under `@core:*`,
|
||||
- and host-facing capability surfaces remain the natural fit for `@sdk:*`.
|
||||
|
||||
### 11.6 Canonical identity
|
||||
|
||||
Canonical builtin identity and canonical host identity are not derived from local alias spelling.
|
||||
|
||||
Duplicate canonical builtin identities or duplicate canonical host identities in one resolved environment are rejected as linking failures.
|
||||
|
||||
## 12. Linking Phase Boundary And Deterministic Failures
|
||||
|
||||
### 12.1 Normative phase baseline
|
||||
|
||||
PBS v1 adopts the following normative phase baseline for name resolution and related frontend failures:
|
||||
|
||||
1. `syntax`
|
||||
2. `manifest/import resolution`
|
||||
3. `linking`
|
||||
4. `static semantics`
|
||||
|
||||
### 12.2 Syntax
|
||||
|
||||
`syntax` owns malformed import grammar and other token-shape or grammar-shape failures.
|
||||
|
||||
### 12.3 Manifest and import resolution
|
||||
|
||||
`manifest/import resolution` owns failures to resolve:
|
||||
|
||||
- project space,
|
||||
- reserved stdlib space,
|
||||
- dependency graph target,
|
||||
- module path,
|
||||
- or environment source.
|
||||
|
||||
### 12.4 Linking
|
||||
|
||||
`linking` owns assembly of visible declarations across files and modules.
|
||||
|
||||
At minimum, `linking` owns:
|
||||
|
||||
1. import of non-exported names,
|
||||
2. unresolved barrel entries against module declarations,
|
||||
3. collisions between visible imported names from different canonical origins,
|
||||
4. local-versus-import visibility collisions,
|
||||
5. callable-origin conflicts across module boundaries,
|
||||
6. duplicate canonical builtin identities in one resolved environment,
|
||||
7. duplicate canonical host identities in one resolved environment.
|
||||
|
||||
### 12.5 Static semantics
|
||||
|
||||
`static semantics` owns:
|
||||
|
||||
1. duplicate local declarations,
|
||||
2. declaration validity,
|
||||
3. type checking,
|
||||
4. member lookup once the receiver type is known,
|
||||
5. overload resolution within an already-formed visible callable set.
|
||||
|
||||
Member lookup failure on an already-typed builtin receiver therefore belongs to `static semantics`.
|
||||
|
||||
### 12.6 Imported-origin conflicts are rejected before callsite analysis
|
||||
|
||||
Conflicts between different imported origins are rejected in `linking` immediately.
|
||||
|
||||
The implementation must not:
|
||||
|
||||
- wait for a specific callsite,
|
||||
- use overload resolution to rescue imported-origin ambiguity,
|
||||
- or defer visible declaration conflicts to later typing work.
|
||||
|
||||
## 13. Deterministic Resolution Failures
|
||||
|
||||
@@ -162,8 +376,30 @@ 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.
|
||||
4. import of any non-exported name from a resolved module,
|
||||
5. unresolved barrel entries against module declarations,
|
||||
6. local-versus-import same-namespace collisions,
|
||||
7. imported same-name collisions from different canonical origins,
|
||||
8. local-versus-import function-name collisions,
|
||||
9. duplicate visible builtin type declarations that claim the same canonical builtin identity in one resolved environment,
|
||||
10. duplicate visible builtin constants that claim the same canonical builtin constant identity in one resolved environment,
|
||||
11. duplicate visible host owners that claim the same canonical host identity in one resolved environment,
|
||||
12. member lookup on a builtin receiver where the imported builtin shell does not declare the requested field or intrinsic member,
|
||||
13. any resolution path that attempts to derive host or builtin canonical identity from alias spelling alone.
|
||||
|
||||
## 14. Non-Goals
|
||||
|
||||
- Reopening the already-settled import surface syntax.
|
||||
- Defining runtime loader behavior.
|
||||
- Freezing one compiler symbol-table implementation.
|
||||
- Freezing one internal compiler pass graph.
|
||||
|
||||
## 15. Exit Criteria
|
||||
|
||||
This document is ready to move beyond its current draft 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 callable visibility and ambiguity behavior are normatively defined,
|
||||
5. and the phase ownership of source-facing name-resolution failures is explicit enough for diagnostics and conformance.
|
||||
|
||||
Reference in New Issue
Block a user