Resolver contract - Examples

Platform spec article

Resolver contract - Examples

Back to Resolver contract ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (5)

1. 0001-feature-hub-authority Feature hub authority Accepted

   This feature hub owns normative MUST/SHOULD contract text for Resolver contract.

   Context

   Sibling articles under this feature previously restated requirements in inconsistent forms.

   Decision

   This feature hub owns normative MUST/SHOULD contract text. Sibling articles must not redefine hub requirements and should link here for authority.

   Consequences

   Contract changes start on the hub or in linked ADRs, then propagate to articles and implementation anchors.

   Verification anchors

   • site/website/src/content/docs/platform-spec/compiler/semantic-pipeline/resolver-contract/index.mdx
   • article bundle under the same feature directory.

   Open full ADR page

2. 0002-spec-over-implementation-notes Specification over implementation notes Accepted

   Platform-spec text supersedes informal crate comments for Resolver contract.

   Context

   Implementation crates accumulated informal notes that diverged from published contracts.

   Decision

   Normative platform-spec prose and ADRs under this feature supersede informal comments in implementation crates until explicitly migrated into spec text.

   Consequences

   Engineers file spec/ADR updates when behavior changes; crate comments are non-authoritative for conformance arguments.

   Verification anchors

   • compiler/crates/beskid_analysis/src/resolve/resolver.rs
   • compiler/crates/beskid_analysis/src/resolve/items.rs
   • compiler/crates/beskid_tests/src/analysis/resolve.rs

   Open full ADR page

3. 0003-primary-contract-choice Primary contract for Resolver contract Accepted

   This feature hub defines the normative contract for **resolver contract** and links newcomer-oriented reference articles

   Context

   This feature hub defines the normative contract for resolver contract and links newcomer-oriented reference articles.

   Decision

   The reference compiler must implement Resolver contract as documented in this feature hub and its article bundle.

   Consequences

   Changes require hub/ADR updates and verification anchor extensions.

   Verification anchors

   • compiler/crates/beskid_analysis/src/resolve/resolver.rs
   • compiler/crates/beskid_analysis/src/resolve/items.rs
   • compiler/crates/beskid_tests/src/analysis/resolve.rs

   Open full ADR page

4. 0004-use-imports-public-types Use imports public types Accepted

   use Module.Path brings public types and enum constructors into unqualified scope.

   Context

   use Core.Results registered module aliases for member completion (IO.PrintLine) but did not import public types or enum constructors into unqualified value/type scope—breaking patterns such as Result::Ok after use Core.Results.

   Decision

   When resolving use Logical.Module.Path (with optional as Alias):

   Binding	Rule
   Module alias	Existing module_imports behavior for qualified member access remains
   Public types	Each public type exported from the target module must bind in type scope under its simple name (or alias)
   Enum constructors	Each public enum constructor must bind in value scope as Type::Variant and, when the type name is in scope, as unqualified constructor names per language-meta visibility rules
   Non-public items	Must not be introduced into scope via use

   Consequences

   Resolver and items.rs grow use-import registration beyond alias tables. Analysis fixtures cover Core.Results / Result::Ok patterns.

   Verification anchors

   • compiler/crates/beskid_analysis/src/resolve/resolver.rs
   • compiler/crates/beskid_analysis/src/resolve/items.rs
   • compiler/crates/beskid_tests/src/analysis/resolve.rs
   • compiler/corelib/beskid_corelib/tests/corelib_tests/src/core/ResultsTests.bd

   Open full ADR page

5. 0005-package-prefixed-symbol-identity Package-prefixed symbol identity Accepted

   SymbolQualifier and SymbolRegistry as stable cross-unit definition identity alongside dense ItemId.

   Context

   ItemId(usize) is a dense, phase-local index into Resolution.items. It works for span tables and type maps inside one merged resolution, but cross-unit tooling (LSP workspace references, link-plan discovery, registry docs) needs a stable definition key that survives per-unit re-resolve and prefetch/entry merge.

   Qualified names were previously recomputed post-hoc in doc emission (qualified_names.rs) without a single authoritative registry. Duplicate export names could last-win silently in helper scans.

   Decision

   Introduce package-prefixed canonical symbol identity parallel to ItemId:

   Type	Role
   SymbolQualifier	{ package, shape } — package is CompilePlan.project_name for the entry/host unit or the dependency project_name for prefetched units; builtins use fixed package beskid
   SymbolShape	Encodes module items, members, methods, and builtins into one ::-separated string
   SymbolId	Interned key into SymbolRegistry
   Resolution.by_symbol	Maps SymbolId → authoritative ItemId after collect

   Hot paths keep ItemId. Type maps, scoped span tables, and LocalId stay unchanged. Symbol identity is authoritative for:

   • cross-unit definition identity (IDE references, link-plan callee discovery),
   • api.json symbolKey when the row is registry-backed,
   • @ref / type-ref lookup by full package-prefixed path.

   Collection assigns ItemInfo.symbol for exportable rows; duplicate SymbolQualifier values must surface as structured resolve errors instead of silent last-wins in name scans.

   Canonical lookup helpers live in resolve/symbol_lookup.rs (symbol_for_item, item_id_for_symbol, canonical_item_id, qualified_name).

   Encoding (normative examples)

   Shape	Example key
   Module export	corelib::Std::Console::Capabilities::ShouldEmitAnsi
   Member	corelib::Std::Console::Capabilities::colorDisabled
   Method	corelib::Capabilities::ShouldEmitAnsi (receiver string + method name)
   Builtin	beskid::range

   qualifiedName on api.json rows may retain legacy module-relative strings for display; symbolKey carries the registry string when present (D-TOOL-CLI-0003).

   Consequences

   • ModuleIndex prefetch clones one shared registry into entry and per-unit resolve paths.
   • IDE references_at_offset_workspace matches references by SymbolId when both sides have registry symbols, not raw ItemId equality across unit re-resolve.
   • Codegen FunctionDefIndex and link-plan visitation use by_symbol as the primary callee index; span scans are fallback only.
   • Tests and golden api.json fixtures gain symbolKey on exportable symbols when re-emitted with a current CLI.

   Verification anchors

   • compiler/crates/beskid_analysis/src/resolve/symbol.rs
   • compiler/crates/beskid_analysis/src/resolve/symbol_lookup.rs
   • compiler/crates/beskid_analysis/src/resolve/collect.rs
   • compiler/crates/beskid_analysis/src/projects/assembly/module_index.rs
   • compiler/crates/beskid_analysis/src/services/document.rs (symbol-aware references)
   • compiler/crates/beskid_codegen/src/linking/def_index.rs

   Open full ADR page

Articles

• Resolver contract - Contracts and edge cases Normative resolver guarantees including SymbolRegistry invariants and cross-unit reference matching. article Standard Reviewed Fri Jun 05
• Resolver contract - Design model Persistent resolver entities including SymbolRegistry, ItemId, and cross-unit identity. article Standard Reviewed Fri Jun 05
• Resolver contract - Examples Concrete symbol identity and cross-unit reference scenarios. article Standard Reviewed Fri Jun 05
• Resolver contract - FAQ and troubleshooting Answers common operator and contributor questions with practical next checks. article Standard
• Resolver contract - Flow and algorithm Walks through runtime/order-of-operations behavior in the implementation. article Standard
• Resolver contract - Verification and traceability Tests and code anchors proving SymbolRegistry and cross-unit reference behavior. article Standard Reviewed Fri Jun 05

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 0 SpecSection(s) · 2 H2 heading(s)

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Feature
  Resolver contract

  Parent feature hub

Prefetch dependency symbol

Main.bd calls Output.WriteLine from a dependency unit collected into ModuleIndex:

Identity	Example
ItemId	Dense index into merged items (stable for prefetch rows)
SymbolId	Interned key for export
symbolKey (api.json)	corelib_mvp::Std::System::IO::Output::WriteLine (exact package prefix from materialized project)
qualifiedName	May use module-relative display; prefer symbolKey for cross-package links

Workspace find-references on the WriteLine use site must include references in Output.bd when assembly is available.

Entry-defined symbol referenced elsewhere

helper() declared in the entry unit and called from a dependency file:

• Entry merged resolution assigns helper a registry symbol under the host project_name.
• Per-unit resolve of the dependency file may assign a different dense ItemId to the same logical import target.
• IDE reference matching must still succeed via equal SymbolId, not ItemId equality.

@ref by full symbol key

Documentation comment:

/// See also @ref(corelib::Std::Console::Esc)

Resolution must locate the target item by exact registry string before falling back to qualifiedName suffix heuristics (doc/refs.rs).

Non-exportable rows

Parameters and other synthetics have ItemInfo.symbol: None. They omit symbolKey in api.json and use ItemId / local identity in IDE queries.

Anchored fixtures

• compiler/crates/beskid_e2e_tests/fixtures/corelib_mvp/ — assembly-backed document tests
• compiler/corelib/beskid_corelib/tests/corelib_tests/ — corelib integration surfaces