Package-prefixed symbol identity

Platform spec ADR

Package-prefixed symbol identity

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

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

• Feature
  Program assembly

  Prefetch + entry merge share one registry

• Feature
  api.json contract

  symbolKey emission from registry

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