Verification and traceability

Platform spec article

Verification and traceability

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

Verification matrix

Contract	Rust test	Beskid test target	CLI command
API-SHAPE-001 (every public item resolves through cascade)	beskid_tests::projects::corelib::layout::corelib_collections_sources_carry_api_shape_tier_directives	—	cargo test -p beskid_tests projects::corelib::layout
API-SHAPE-002 (only known tier values)	beskid_analysis::doc::api_tier::tests::rejects_unknown_directive_value	—	cargo test -p beskid_analysis doc::api_tier
API-SHAPE-003 (cascade resolution)	beskid_analysis::doc::api_tier::tests::cascade_item_then_parent_then_default	—	cargo test -p beskid_analysis doc::api_tier
API-SHAPE-004 (prelude only re-exports Tier 1)	beskid_tests::projects::corelib::layout::corelib_system_streams_carry_api_shape_tier_directives (Input/Output/Error are Tier 1)	—	cargo test -p beskid_tests projects::corelib::layout
API-SHAPE-005 (camelCase + omit when None)	beskid_tests::projects::corelib::layout::checked_in_corelib_tier_metadata_round_trips_through_api_json	—	cargo test -p beskid_tests projects::corelib::layout
API-SHAPE-006 (api.json schema ≥ v4 when tier is set)	beskid_tests::projects::corelib::layout::api_doc_root_advertises_v4_schema_for_tier_metadata	—	cargo test -p beskid_tests projects::corelib::layout
API-SHAPE-007 (Tier 1 stability)	beskid_tests::projects::corelib::layout::corelib_collections_sources_carry_api_shape_tier_directives plus snapshot reviews	CollectionsTier1Tests (tests/corelib_tests/src/collections/CollectionsTier1Tests.bd)	beskid test --project tests/corelib_tests --target CollectionsTier1Tests
API-SHAPE-008 (Tier 2 stability)	beskid_tests::projects::corelib::layout::corelib_collections_sources_carry_api_shape_tier_directives	CollectionsListTests, CollectionsMapTests, CollectionsSetTests, CollectionsQueueTests, CollectionsStackTests, SystemFsTests, SystemPathTests	beskid test --project tests/corelib_tests --target CollectionsMapTests (repeat per target)
API-SHAPE-009 (Tier 3 not in prelude / completions)	Prelude reader checks in beskid_tests::projects::corelib::compile::checked_in_corelib_prelude_exports_mvp_modules plus the layout tier directives test	—	cargo test -p beskid_tests projects::corelib::compile::checked_in_corelib_prelude_exports_mvp_modules
API-SHAPE-010 (consumer badges)	trudoc verify:platform-spec-content checks ADRs and ## Decisions table on the hub	—	bun run --cwd site/website verify:trudoc -- --preset ci

Conformance commands

Run from the workspace root:

# Rust-side conformance (resolver + cascade + api.json round-trip + tier directive enforcement)
cd compiler && cargo test -p beskid_tests projects::corelib::layout

# Resolver unit tests (parser, cascade levels, alias normalization)
cd compiler && cargo test -p beskid_analysis doc::api_tier

# Beskid-side Tier 1 / Tier 2 suites (drop-in once CLI's beskid test resolves cross-package symbols)
cd compiler/corelib/beskid_corelib/tests/corelib_tests && beskid test --target CollectionsTier1Tests
cd compiler/corelib/beskid_corelib/tests/corelib_tests && beskid test --target CollectionsListTests
cd compiler/corelib/beskid_corelib/tests/corelib_tests && beskid test --target CollectionsMapTests
cd compiler/corelib/beskid_corelib/tests/corelib_tests && beskid test --target CollectionsSetTests
cd compiler/corelib/beskid_corelib/tests/corelib_tests && beskid test --target CollectionsQueueTests
cd compiler/corelib/beskid_corelib/tests/corelib_tests && beskid test --target CollectionsStackTests
cd compiler/corelib/beskid_corelib/tests/corelib_tests && beskid test --target SystemFsTests
cd compiler/corelib/beskid_corelib/tests/corelib_tests && beskid test --target SystemPathTests

# Spec contract (no Proposed pages under api-shape, no scaffold stubs, decisions present)
cd site/website && bun run verify:trudoc -- --preset ci

Traceability map

• Spec requirement source: /platform-spec/core-library/stability-and-api-shape/corelib-api-shape/.
• Tier resolver: compiler/crates/beskid_analysis/src/doc/api_tier.rs.
• Tier field on ApiDocItem: compiler/crates/beskid_analysis/src/doc/api_snapshot.rs.
• Beskid sources tagged with @tier(...):
  • compiler/corelib/packages/foundation/src/Collections/Array.bd (Tier 1)
  • compiler/corelib/packages/foundation/src/Collections/List.bd (Tier 2 with Get at Tier 3)
  • compiler/corelib/packages/foundation/src/Collections/Map.bd (Tier 2 with ContainsKey and Get at Tier 3)
  • compiler/corelib/packages/foundation/src/Collections/Set.bd (Tier 2 with Contains at Tier 3)
  • compiler/corelib/packages/foundation/src/Collections/Queue.bd (Tier 2 with Peek at Tier 3)
  • compiler/corelib/packages/foundation/src/Collections/Stack.bd (Tier 2 with Peek at Tier 3)
  • compiler/corelib/packages/runtime/src/System/Input.bd, Output.bd, Error.bd, Syscall.bd (Tier 1)
  • compiler/corelib/packages/runtime/src/System/FS.bd (Tier 2)
  • compiler/corelib/packages/runtime/src/System/Path.bd (Tier 2 with FileName, Extension, IsAbsolute at Tier 3)
• Conformance anchor: compiler/crates/beskid_tests/src/projects/corelib/layout.rs.

Review checklist

• Every public corelib module carries at least one @tier(...) directive (module-level or per-item).
• api.json round-trip preserves tier for tier-tagged items and omits it cleanly for items left as None.
• The prelude validator passes after any module promotion.
• cargo test -p beskid_tests projects::corelib::layout is green.
• bun run verify:trudoc -- --preset ci reports zero Proposed pages under core-library/stability-and-api-shape/corelib-api-shape/.