Design model

Platform spec article

Design model

Back to Corelib discovery and packaging ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (4)

1. 0001-canonical-corelib-identity Canonical corelib package identity Accepted

   Published and resolved identity is corelib, not ad-hoc forks.

   Context

   Registry, CLI, and analysis must agree on one package name.

   Decision

   Rule	Detail
   Identity	Package name corelib; sources under beskid_corelib
   Legacy	standard_library paths may alias; identity remains corelib

   Consequences

   pckg publish, resolver, and docs use the same identity string.

   Verification anchors

   resolver.rs; beskid_tests corelib project fixtures.

   Open full ADR page

2. 0002-multi-path-discovery Multi-path corelib discovery Accepted

   Env, repo walk, and bundled CLI materialize the same tree.

   Context

   Developers run from superrepo, installed CLI, or CI without divergent roots.

   Decision

   Rule	Detail
   BESKID_CORELIB_ROOT	Points at root containing beskid_corelib/Project.proj
   Walk	Ancestor search for compiler/corelib/beskid_corelib
   Bundle	beskid_cli ensure_corelib_ready materializes embedded tree

   Consequences

   Missing roots fail fast with resolver diagnostics.

   Verification anchors

   corelib_runtime.rs; resolver.rs tests.

   Open full ADR page

3. 0003-readme-packaging-for-pckg Readme packaging for pckg artifacts Accepted

   Pack copies declared readme into README.md for registry docs.

   Context

   Registry consumers expect root README.md in .bpk artifacts.

   Decision

   Rule	Detail
   Declare	Optional readme = "path.md" in Project.proj
   Default	readme.md at package root when present
   Pack	beskid pckg pack places resolved file as README.md

   Consequences

   pckg documentation ingest uses consistent entry filename.

   Verification anchors

   PackagePublishDocumentation.cs; pack integration tests.

   Open full ADR page

4. 0004-workspace-includes-console-shard Workspace includes console shard Accepted

   corelib_console is a workspace member depended on by beskid_corelib.

   Context

   Console/ANSI must ship with the aggregate package, not as an orphan.

   Decision

   Rule	Detail
   Workspace	compiler/corelib/Workspace.proj lists packages/console
   Aggregate	beskid_corelib depends on corelib_console

   Consequences

   Publish CI packs the full workspace graph for registry corelib.

   Verification anchors

   Workspace.proj; corelib CI publish job.

   Open full ADR page

Articles

• Contracts and edge cases Normative guarantees and known edge cases for `Corelib discovery and packaging`. article Standard
• Design model Conceptual model for `Corelib discovery and packaging` and its subsystem boundaries. article Standard
• Examples Practical examples that demonstrate `Corelib discovery and packaging` behavior. article Standard
• FAQ and troubleshooting Common questions and debugging guidance for `Corelib discovery and packaging`. article Standard
• Flow and algorithm End-to-end control flow for corelib discovery, materialization, and packaging. article Standard
• Verification and traceability How `Corelib discovery and packaging` requirements map to tests and implementation anchors. article Standard

History

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

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 2 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
  Compiler integration

  Parent area

• Area
  Resolution and projects

  Project graph logic resolves and injects corelib

• Area
  Stability and API shape

  API stability expectations depend on canonical packaging

• Feature
  Corelib discovery and packaging

  Parent feature hub

• Feature
  Corelib injection and resolution

  Graph attachment after roots are found

Purpose

One canonical corelib package identity (corelib, sources under compiler/corelib/beskid_corelib) must be discoverable by CLI, LSP, CI publish, and local superrepo layouts. This feature covers where that tree lives on disk and how it is packed for pckg—not symbol injection (see Corelib injection and resolution).

Discovery and packaging topology

flowchart TB
  subgraph sources [Source tree]
    WS[compiler/corelib/Workspace.proj]
    Agg[beskid_corelib Project.proj]
    Pkgs[packages: foundation, runtime, console, compiler-sdk]
    WS --> Agg --> Pkgs
  end
  subgraph discovery [Discovery]
    Env[BESKID_CORELIB_ROOT]
    Walk[Repo ancestor walk]
    Bundle[CLI bundled corelib]
  end
  subgraph publish [Publish]
    Doc[beskid doc → .beskid/docs]
    Pack[beskid pckg pack → .bpk]
    Reg[pckg registry corelib identity]
  end
  Env --> Agg
  Walk --> Agg
  Bundle --> Agg
  Agg --> Doc --> Pack --> Reg

Primary actors

Actor	Role
Aggregate package	beskid_corelib — declares dependencies on workspace member packages
Workspace	compiler/corelib/Workspace.proj lists shards including corelib_console
Toolchain	resolver.rs + beskid_cli corelib_runtime locate roots
Registry	CI publishes corelib via beskid pckg + BESKID_PCKG_KEY

Package readme

Published .bpk artifacts should expose registry documentation through root README.md. Producers declare the on-disk source in Project.proj or Workspace.proj:

• Optional readme = "relative/path.md" (POSIX-style path relative to the package or workspace root).
• When omitted, tooling uses readme.md at that root when the file exists.
• beskid pckg pack copies the resolved file into the artifact as README.md when it is not already a root readme entry.

Workspace members

compiler/corelib/Workspace.proj includes packages/console (corelib_console) alongside foundation, runtime, and compiler-sdk. The aggregate beskid_corelib project depends on corelib_console for console/ANSI surfaces.

Implementation anchors

• Canonical package root: compiler/corelib/beskid_corelib
• Console package: compiler/corelib/packages/console
• Discovery: compiler/crates/beskid_analysis/src/projects/graph/resolver.rs
• CLI embedding: compiler/crates/beskid_cli/build.rs, corelib_runtime.rs
• Tests: compiler/crates/beskid_tests/src/projects/corelib
• Server ingest: pckg/src/Server/Services/PackagePublishDocumentation.cs