Three-tier classification with default `supported`

Platform spec ADR

Three-tier classification with default `supported`

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

Context

The corelib workspace exposes hundreds of public items across packages/foundation, packages/runtime, packages/console, packages/concurrency, and packages/compiler-sdk. Some items (Collections.Array.Len, System.Output.Write) are battle-tested and already part of the prelude; others (Collections.List.Get, System.FS.WriteAllText) ship as shape-only stubs while the runtime catches up. Without a tier classification, downstream consumers cannot tell which APIs are safe to depend on and which may break in the next minor release.

Decision

Rule	Detail
Tier vocabulary	Tier 1 — standard, Tier 2 — supported, Tier 3 — unstable
Authoring directive	/// @tier(<value>) on the declaring doc comment of any public item
Aliases	Tier1/Standard/standard, Tier2/Supported/supported, Tier3/Unstable/unstable (case-insensitive)
Default	Public items without a directive resolve to supported
Cascade	Item-site → parent → package default → workspace default
Serialization	Lowercase string under camelCase tier field in ApiDocItem; omitted when unresolved

Consequences

• Downstream tooling can badge every documented item by tier without consulting an external manifest.
• Authors get a one-line annotation surface; existing items default to a meaningful tier (supported) without a sweeping refactor.
• The default of supported is the safest “no commitment, no claim of unstable” choice. Future tightening to require explicit directives is possible without a compatibility break.

Verification anchors

• compiler/crates/beskid_analysis/src/doc/api_tier.rs (resolver + tests)
• compiler/crates/beskid_analysis/src/doc/api_snapshot.rs (tier field)
• compiler/crates/beskid_cli/src/commands/doc.rs::execute (CLI emission)
• compiler/crates/beskid_tests/src/projects/corelib/layout.rs::checked_in_corelib_tier_metadata_round_trips_through_api_json