Project inception decisions

Platform spec feature

Project inception decisions

Back to Community ◎ Open in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (8)

1. 0001-spec-leads-code Platform specification leads implementation Accepted

   Normative spec text is the authority axis for observable language and platform behavior.

   Context

   Early Beskid work mixed README intent, compiler experiments, and informal design chat without a single enforceable contract surface.

   Decision

   The platform specification on Git main must precede or accompany implementation that changes user-visible semantics. Tests and crates verify drift; they do not replace missing spec text.

   Consequences

   Contributors file spec updates in the same change set as behavioral changes. CI content gates block Standard stubs.

   Verification anchors

   site/website/src/content/docs/platform-spec/; verify:trudoc --preset ci.

   Open full ADR page

2. 0002-compile-time-ioc Compile-time IoC in the compiler host Accepted

   Dependency composition is explicit, verifiable, and compiled—not a runtime DI container.

   Context

   C#-style framework IoC stacks hide wiring behind reflection and service locator patterns the project rejects (see compiler README).

   Decision

   IoC may exist only inside the Rust compiler host as compile-time composition. Beskid programs must not depend on a runtime DI framework or service locator for language features.

   Consequences

   Compiler mods and SDK surface read-only host composition; language-level meta DI blocks are removed.

   Verification anchors

   compiler/README.md; Dependency injection.

   Open full ADR page

3. 0003-metaprogramming-over-reflection Metaprogramming over reflection Accepted

   Prefer compile-time generation and macros over opaque runtime reflection.

   Context

   Reflection-heavy stacks defer errors to runtime and obscure performance and ABI truth.

   Decision

   Language and compiler features should expose compile-time metaprogramming (mods, analyzers, codegen hooks) instead of encouraging runtime reflection as a default extension model.

   Consequences

   Compiler SDK and mods are AOT-oriented; diagnostic parity targets compile-time failure.

   Verification anchors

   Metaprogramming; compiler mod features under compiler/compiler-mods/.

   Open full ADR page

4. 0004-native-codegen-not-il Native codegen without IL as the primary IR Accepted

   Assembly-oriented output without CIL as the central execution contract.

   Context

   CIL-centric VMs lag language features and impose workaround layers the project avoids.

   Decision

   The reference platform must lower through Beskid-owned IR and native/JIT/AOT backends—not treat a portable IL stack as the primary execution contract.

   Consequences

   ABI, builtins, and runtime syscalls are versioned in execution specs; JIT and AOT share beskid_abi revision.

   Verification anchors

   Backends JIT AOT; ABI versioning.

   Open full ADR page

5. 0005-beskid-corelib-sources Core library in Beskid source Accepted

   Standard library implementation stays Beskid packages in the corelib submodule—not a parallel Rust std port.

   Context

   Splitting corelib into ad-hoc Rust crates would fork API truth from author-facing packages and pckg docs.

   Decision

   Canonical corelib sources must live under the beskid_standard / corelib workspace with pckg identity corelib. Tooling treats .beskid/docs/ and api.json as first-class.

   Consequences

   Registry publish authority stays in corelib CI; compiler consumes and validates.

   Verification anchors

   Corelib discovery and packaging.

   Open full ADR page

6. 0006-rust-host-rust-ast Rust compiler host and canonical AST Accepted

   The compiler is implemented in Rust; Beskid does not self-host the compiler implementation.

   Context

   Self-hosting before semantic stability would couple bootstrap pain to language churn.

   Decision

   The reference compiler must remain a Rust workspace. The canonical syntax model is generated into Beskid.Compiler.* SDK sources from Rust AST reflection—not hand-maintained parallel syntax trees.

   Consequences

   Mods extend analysis/codegen via SDK contracts; the host pipeline stays Rust-only.

   Verification anchors

   beskid_ast_reflect_gen; Syntax domain model generation.

   Open full ADR page

7. 0007-git-main-version-axis Git main as the specification version axis Accepted

   No URL version segments; normative truth tracks Git `main` and `lastReviewed`.

   Context

   URL-versioned spec sites drift from the implementation contributors actually ship.

   Decision

   Published platform-spec URLs must not embed version path segments. Maturity uses frontmatter status and lastReviewed; delivery bands (v0.x) describe scope, not alternate spec trees.

   Consequences

   Release policy and site deploy track main.

   Verification anchors

   Release and versioning policy.

   Open full ADR page

8. 0008-fibers-not-async-await Cooperative fibers and channels in v1 Accepted

   v1 concurrency uses `spawn`, fibers, and channels—not `async`/`await` keywords.

   Context

   Async/await state machines would delay shipping a inspectable fiber runtime and channel semantics.

   Decision

   spawn must be the fiber introduction keyword. async and await must be parse errors (reserved) until a future spec adds them. Cross-fiber communication must use Channel (and coordination primitives), not shared stacks.

   Consequences

   Corelib concurrency package and execution scheduler specs realize this ADR.

   Verification anchors

   Fibers and spawn; Concurrency package ADRs.

   Open full ADR page

Articles

• No directly attached article pages for this node.

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKarea · 4 SpecSection(s) · 1 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
  Spec maintenance

  Parent area

• Feature
  Specification authority and embedded decisions

  ADR governance

• Domain
  Platform specification

  Root index

What this feature specifies

Cross-cutting architecture decision records from Beskid project inception—platform authority, compiler host shape, corelib packaging, and language direction that span multiple domains.

Implementation anchors

• Governance: Specification authority and embedded decisions
• Historical intent: compiler/README.md, informative Why Beskid Exists (non-normative; ADRs here are normative)
• ADR files: platform-spec/community/project-inception/adr/*.mdx

Contract statement

This feature records cross-cutting decisions made at or before public Beskid inception. Domain-specific features must defer here for platform-wide direction instead of restating the same rationale.

Verification and traceability

• Each row in adr/ is normative at status: Standard unless marked Proposed or Superseded.
• Implementation domains must link inception adrId values from feature hubs when realizing these choices.

Decisions

No open decisions. Closed inception ADRs are listed under adr/ (reader ADRs tab)—D-INC-0001 through D-INC-0008.