Tier metadata travels via `api.json`, not a parallel manifest

Platform spec ADR

Tier metadata travels via `api.json`, not a parallel manifest

Back to Corelib API shape ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

Articles

• Contracts and edge cases Normative MUST/SHOULD/MAY rules for corelib API tiering and the edge cases authors and tools must handle deterministically. article Standard Reviewed Sat May 23
• Design model Conceptual model for the corelib three-tier API-shape classification and how it propagates from sources to consumers. article Standard Reviewed Sat May 23
• Examples Canonical Tier 1 / Tier 2 / Tier 3 annotations on `Collections.Array.Len`, `Collections.Map.Count`, and `Collections.List.Get`, plus the resulting `api.json` rows. article Standard Reviewed Sat May 23
• FAQ and troubleshooting Common questions about `@tier(...)` directives, prelude exposure, and how to debug tier drift between sources and `api.json`. article Standard Reviewed Sat May 23
• Flow and algorithm How a `@tier(...)` doc directive becomes a `tier` field on every `api.json` row consumed by IDEs, lints, and the registry. article Standard Reviewed Sat May 23
• Verification and traceability Matrix mapping each API-shape contract to the Rust tests, Beskid test targets, and CLI commands that pin it down. article Standard Reviewed Sat May 23

History

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

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 11 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
  Corelib API shape

  Parent feature hub

• Feature
  api.json contract

  Field-level container for the tier metadata

Context

Tier classification needs to flow from corelib sources to consumers (pckg dashboard, IDE tooling, conformance fixtures). Two paths were considered: (a) emit a sibling tiers.json next to api.json, or (b) attach the tier directly to each item row in api.json. Path (a) creates a second source of truth and risks drift when items rename or move; path (b) keeps the contract in one place but requires a api.json schema bump.

Decision

Rule	Detail
Field placement	tier: Option<String> on ApiDocItem in compiler/crates/beskid_analysis/src/doc/api_snapshot.rs
Serialization	camelCase tier; lowercase value; omitted when unresolved
Schema version	API_JSON_SCHEMA_VERSION stays at 4; the tier field is additive and consumers that ignore unknown fields are unaffected
Anti-pattern	Tooling must not consult a parallel manifest file (tiers.json, Tier.toml, …) for tier classification

Consequences

• One source of truth: every tooling consumer reads from api.json and gets tier alongside signature, doc markdown, and module path.
• Future schema changes (e.g., adding tierReason or since) can layer onto the same row without splitting the contract.
• Authors discover tier drift the moment beskid doc runs locally; there is no second file to forget to update.

Verification anchors

• compiler/crates/beskid_analysis/src/doc/api_snapshot.rs::ApiDocItem
• compiler/crates/beskid_analysis/src/doc/api_tier.rs
• compiler/crates/beskid_cli/src/commands/doc.rs::execute
• compiler/crates/beskid_tests/src/projects/corelib/layout.rs::api_doc_root_advertises_v4_schema_for_tier_metadata