Design model

Platform spec article

Design model

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

ADRs (3)

1. 0001-three-tier-classification Three-tier classification with default `supported` Accepted

   Public corelib items classify as Tier 1 (Standard), Tier 2 (Supported), or Tier 3 (Unstable); missing directives default to `supported`.

   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

   Open full ADR page

2. 0002-prelude-tier1-only Corelib prelude is Tier 1 only Accepted

   The aggregate corelib prelude `Prelude.bd` must re-export Tier-1 modules only; Tier 2 / Tier 3 require explicit `use` imports.

   Context

   Every Beskid project gets the corelib prelude injected by default (see Corelib injection and resolution). Adding a module to the prelude makes it transitively visible to all downstream code. Including Tier 2 / Tier 3 modules in the prelude would expose unstable surfaces by default and violate the tier compatibility table.

   Decision

   Rule	Detail
   Membership rule	compiler/corelib/beskid_corelib/src/Prelude.bd must re-export only modules whose declarations resolve to standard
   Enforcement	compiler/crates/beskid_tests/src/projects/corelib/layout.rs::corelib_prelude_only_re_exports_tier1_modules cross-checks every pub mod ...; line in Prelude.bd against the resolved per-module tier
   Promotion path	Promoting a Tier 2 module to Tier 1 requires (a) updating the directive to @tier(standard) on the module's package source and (b) adding a row to the hub's ## Decisions section pointing at this ADR or a new follow-up ADR
   Demotion path	Demoting a Tier 1 prelude item requires a normative ADR under adr/ and a compatibility alias for at least one minor release

   Consequences

   • The prelude stays small and predictable: only a vetted surface ships transitively.
   • Tier 2 / Tier 3 modules remain reachable via explicit use System.FS; (etc.); no expressivity lost.
   • CI catches accidental prelude growth before merge, keeping the v0.3 → v1.0 compatibility budget intact.

   Verification anchors

   • compiler/corelib/beskid_corelib/src/Prelude.bd
   • compiler/crates/beskid_tests/src/projects/corelib/layout.rs::corelib_prelude_only_re_exports_tier1_modules
   • compiler/crates/beskid_tests/src/projects/corelib/compile.rs::checked_in_corelib_prelude_exports_mvp_modules

   Open full ADR page

3. 0003-tier-via-api-json-not-parallel-manifest Tier metadata travels via `api.json`, not a parallel manifest Accepted

   The corelib API-shape tier classification is serialized as a `tier` field on every `ApiDocItem` row; tooling must not consult a parallel JSON / TOML file for tiers.

   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

   Open full ADR page

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

• Area
  Stability and API shape

  Parent area

• Area
  Compiler integration

  Discovery and packaging guarantee the API shape being consumed

• Feature
  Types

  Corelib signatures rely on language type contracts

• Feature
  Corelib API shape

  Parent feature hub

The three tiers

Tier	Doc directive	Audience	Compatibility
Standard	@tier(standard) (alias Tier1)	Application authors	Signature stable for the full v0.x line; breaking changes require a major bump and a normative ADR
Supported	@tier(supported) (alias Tier2, default when no directive resolves)	Application and library authors	Signature stable within a v0.x minor; behavior may evolve with deprecations
Unstable	@tier(unstable) (alias Tier3)	Compiler, tooling, opt-in experiments	Signature may change between minors without notice

Workspace package layout

flowchart TB
  prelude[beskid_corelib prelude]
  foundation[packages/foundation]
  runtimePkg[packages/runtime]
  consolePkg[packages/console]
  concurrencyPkg[packages/concurrency]
  compilerSdk[packages/compiler-sdk]
  prelude --> foundation
  prelude --> runtimePkg
  prelude --> consolePkg
  prelude --> concurrencyPkg
  prelude -.-> compilerSdk

The prelude only re-exports Tier 1 modules. packages/compiler-sdk is reached through explicit use statements because most of it is Tier 3 by design (the syntax mirror surface is generated and evolves with the compiler).

Resolution cascade

For any public ApiDocItem the resolver walks this ordered cascade and stops at the first match:

1. Item directive — /// doc comment on the item carries @tier(...).
2. Parent module directive — the immediate parent module has a @tier(...) directive (members inherit unless overridden).
3. Package default — the package’s Project.proj declares a default tier (reserved for future use; not required today).
4. Workspace default — currently supported; the resolver leaves tier: None so consumers apply this default without rewriting the field.

Prelude exposure rules

• The aggregate beskid_corelib prelude SHALL only re-export modules whose effective tier (cascade resolution) is Standard.
• Tier 2 / Tier 3 modules MUST be reached through explicit use Pkg.Module; imports.
• The prelude validator inspects the pub mod ...; list and fails the publish job if it discovers a non-Tier-1 re-export.

Primary actors

• Authors — annotate corelib modules with @tier(...) and import explicitly when crossing tier boundaries.
• Compiler — beskid_analysis::doc::api_tier::resolve_item_tiers applies the cascade; beskid doc emits the resolved value into api.json.
• Conformance — beskid_tests::projects::corelib::layout checks every collection and System module carries a @tier(...) directive and that the api.json round-trip preserves the field.
• Consumers — IDE, registry, and lints read the tier field from api.json to badge symbols and warn on Tier 3 usage outside opt-in contexts.

Concrete crate anchors

• Resolver: compiler/crates/beskid_analysis/src/doc/api_tier.rs
• Snapshot field: compiler/crates/beskid_analysis/src/doc/api_snapshot.rs
• CLI integration: compiler/crates/beskid_cli/src/commands/doc.rs
• Tier-tagged sources: compiler/corelib/packages/foundation/src/Collections/, compiler/corelib/packages/runtime/src/System/
• Layout / round-trip tests: compiler/crates/beskid_tests/src/projects/corelib/layout.rs