symbolKey stable identity field

Platform spec ADR

symbolKey stable identity field

Back to api.json contract ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

Articles

• Design model Schema v4 for api.json — full resolved API surface, signatures, and navigable type references. article Standard Reviewed Fri Jun 05
• Registry API reference UI Normative layout and navigation for pckg package API documentation driven by api.json. article Standard

History

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

Open full history on GitHub

No commits recorded for this path.

Completeness

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

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

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

Related spec docs

• Feature
  api.json contract

  Parent feature hub

• Feature
  Package-prefixed symbol identity

  Registry authority

• Feature
  pckg client contract

  Pack-time validation

Context

Schema v4 already carries qualifiedName, refItemId, and compiler-derived signatures. Cross-package workspace doc runs and registry consumers still need a stable, package-qualified string that does not depend on recomputing module paths or splitting display names—especially when the same logical symbol can appear under different dense ItemId values during per-unit resolve.

Decision

Add optional field symbolKey on each ApiDocItem (JSON camelCase) for schema v4 emitters:

Rule	Requirement
Presence	Emit only when qualified_name(resolution, item.id) succeeds (registry-backed exportable symbol)
Omission	Non-exportable rows (parameter, synthetic rows, unresolved collect) must omit the field
Value	Same encoding as SymbolRegistry / symbol_to_string (package prefix + :: segments)
qualifiedName	Unchanged; legacy recompute + fallback remains for display and tree labels
Graph edges	refItemId stays the primary type-link and parent graph edge; symbolKey is parallel stable identity

Emitters must not copy qualifiedName into symbolKey when the registry has no symbol for the row.

Consumers may index and resolve @ref targets by exact symbolKey before suffix heuristics on qualifiedName.

Packed library artifacts: pckg must validate symbolKey when present (D-TOOL-PCKG-0005).

Consequences

• Rust type: ApiSymbolKey newtype in api_snapshot.rs (transparent JSON string).
• CLI: beskid doc sets symbolKey from registry lookup only.
• Older artifacts without symbolKey remain valid; field is additive on v4.

Verification anchors

• compiler/crates/beskid_analysis/src/doc/api_snapshot.rs
• compiler/crates/beskid_cli/src/commands/doc.rs
• compiler/crates/beskid_analysis/src/doc/refs.rs
• compiler/crates/beskid_pckg/src/api_doc.rs