Corelib prelude is Tier 1 only
Platform spec ADR
Corelib prelude is Tier 1 only
Spec standingStandard
- Contracts and edge cases Normative MUST/SHOULD/MAY rules for corelib API tiering and the edge cases authors and tools must handle deterministically.
- Design model Conceptual model for the corelib three-tier API-shape classification and how it propagates from sources to consumers.
- 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.
- FAQ and troubleshooting Common questions about `@tier(...)` directives, prelude exposure, and how to debug tier drift between sources and `api.json`.
- Flow and algorithm How a `@tier(...)` doc directive becomes a `tier` field on every `api.json` row consumed by IDEs, lints, and the registry.
- Verification and traceability Matrix mapping each API-shape contract to the Rust tests, Beskid test targets, and CLI commands that pin it down.
0 revisions (git unavailable at build; counts may be empty)
No commits recorded for this path.
| 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).
Context
Section titled “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
Section titled “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
Section titled “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
Section titled “Verification anchors”compiler/corelib/beskid_corelib/src/Prelude.bdcompiler/crates/beskid_tests/src/projects/corelib/layout.rs::corelib_prelude_only_re_exports_tier1_modulescompiler/crates/beskid_tests/src/projects/corelib/compile.rs::checked_in_corelib_prelude_exports_mvp_modules