Glossary and conformance
Platform spec node
Glossary and conformance
Spec standingStandard
No architecture decision records under adr/ for this feature yet. Standard features must
publish at least one ADR or keep a ## Decisions summary on the hub.
0 revisions (git unavailable at build; counts may be empty)
No commits recorded for this path.
| Section id | Required | Found |
|---|---|---|
scope | yes | yes |
features | yes | yes |
Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).
Normative specification
Section titled “Normative specification”This chapter is the normative vocabulary for all Beskid platform specifications. Other language-meta articles, compiler features, execution contracts, and core-library packages must use these terms and requirement keywords consistently. Informative material (book, guides, workshop notes) must not override text marked Standard here.
- In scope: requirement keywords (RFC 2119 profile), Beskid conformance levels, maturity of spec pages, diagnostic severity vocabulary, and cross-domain authority boundaries.
- Out of scope: compiler pipeline ordering, manifest schema keys, and runtime ABI details (owned by sibling domains; they must defer to
language-metafor user-visible semantics).
Requirement keywords (RFC 2119)
Section titled “Requirement keywords (RFC 2119)”The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in normative sections are to be interpreted as described in RFC 2119 and RFC 8174 (BCP 14).
| Keyword | Meaning in Beskid specs |
|---|---|
| MUST / REQUIRED / SHALL | Absolute requirement for conformance at the stated level |
| MUST NOT / SHALL NOT | Absolute prohibition |
| SHOULD / RECOMMENDED | Strong default; deviation requires explicit rationale in ## Decisions |
| SHOULD NOT | Strong discouragement; allowed only with documented exception |
| MAY / OPTIONAL | Truly optional behavior or surface |
Normative sections must use uppercase keywords. Lowercase must in running prose is informative unless the sentence is inside a quoted normative rule.
Beskid conformance levels
Section titled “Beskid conformance levels”Implementations are evaluated against language-meta (Standard articles) plus explicitly linked domain contracts.
| Level | Definition | Verification |
|---|---|---|
| L0 — Parse | Accepts all programs in the v0.1 grammar without internal compiler failure | Parser + beskid.pest fixture suite |
| L1 — Name and module | Resolves modules, imports, and visibility per Modules and visibility and Name resolution | Resolver tests; E11xx band |
| L2 — Type | Assigns types and rejects ill-typed programs per Types and related chapters | beskid_analysis type tests; E12xx–E13xx |
| L3 — Semantic | Enforces contracts, control flow, events, memory rules, and composition/DI where applicable | Semantic + composition tests; E14xx–E17xx |
| L4 — Executable | Lowered program behavior matches execution + core-library contracts for the chosen target triple | Runtime tests, ABI checks |
A conforming reference compiler must reach L3 for all Standard language-meta chapters in this repository snapshot. L4 is claimed per target profile (native, WASM, etc.) in execution and core-library specs.
Specification maturity (status)
Section titled “Specification maturity (status)”status | Meaning |
|---|---|
| Standard | Enforceable MUST/SHOULD text; implementation and diagnostics must align or the page must be downgraded |
| Proposed | Design in flux; implementations may diverge with tracked gaps |
A page marked Standard must not consist solely of navigation boilerplate or self-referential “canonical chapter” links. It must include a Normative specification section with testable rules.
Diagnostic vocabulary
Section titled “Diagnostic vocabulary”| Term | Rule |
|---|---|
Error (E####) | Denotes ill-formed or ill-typed program; compilation must fail |
Warning (W####) | Denotes suspicious but legal program; compilation may succeed |
| Note | Informative attachment; never alone changes exit code |
Stable codes live in the Diagnostic code registry. Language-meta chapters cite bands (for example E11xx resolution); exact messages may evolve while codes remain stable.
Authority boundaries
Section titled “Authority boundaries”| Domain | Owns | Must not redefine |
|---|---|---|
| language-meta | User-visible syntax, types, evaluation, contracts, memory, testing surface | — |
| compiler | Phases, IR, lowering, diagnostic emission mechanics | Language semantics |
| execution | Schedulers, stacks, channels, runtime services | Type rules, spawn typing contract |
| core-library | Host bases, concurrency types, console I/O packages | Grammar and name lookup |
| tooling | CLI, LSP, manifest authoring UX | Resolution graph semantics (defer to compiler) |
Cross-domain pages must link to the owning language-meta chapter with relation: defers-to or implements in relatedTopics.
Definitions (selected)
Section titled “Definitions (selected)”| Term | Definition |
|---|---|
| Program | A finite sequence of ItemWithDocs forming a compilation unit per Lexical and syntax |
| Module | A named namespace boundary introduced by mod or file-scoped mod path; |
| Type | A static description of values; see Types |
| Contract | A surface of required members checked structurally; see Contracts |
| Fiber | Cooperative task handle produced by spawn; see Fibers and spawn |
| Channel | Cross-fiber communication primitive; memory sharing must go through channels per Memory and references |
Option<T> | The sole optional-value surface in v0.1 (corelib Query.Contracts.Option); must not be spelled optional or ?T |
null | Must not exist as a type, literal, or implicit default; absence uses Option<T>::None or explicit enums |
ref T | By-reference parameter or signature form; distinct from nullable or pointer types (see Memory and references) |
| GC heap | Traced object store with concurrent mark-sweep; runtime details in execution specs; /execution/ tree is a non-normative legacy bridge only |
Conformance of specifications themselves
Section titled “Conformance of specifications themselves”Editors must update lastReviewed when normative text changes. Tier-1 language-meta chapters must include ## Decisions for non-obvious choices. Verification anchors should name crate paths or test directories where the reference compiler enforces the rule.
Decisions
Section titled “Decisions”- D-LM-CONF-001 — RFC 2119 profile: Beskid adopts BCP 14 keywords in all
Standardplatform-spec normative sections; the book remains informative. - D-LM-CONF-002 — L0–L4 ladder: Conformance levels are cumulative; claiming L4 without L3 is non-conformant marketing, not a partial compiler.
- D-LM-CONF-003 — Standard without body: Any
Standardpage failing substantive content gates must be downgraded toProposeduntil restored (Track A removes circular stubs). - D-LM-CONF-004 — Diagnostic bands: Language chapters reference code bands; per-message wording is implementation detail owned by the registry feature.
Platform view
Section titled “Platform view”Defines MUST / SHOULD / MAY usage across all Beskid specifications. Every diagnostic and platform RFC should reference this vocabulary consistently. Use this page before authoring or reviewing any other language-meta chapter.