Flow and algorithm

Platform spec article

Flow and algorithm

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

• Feature
  Corelib discovery and packaging

  Parent feature hub

• Feature
  pckg client contract

  Pack and publish HTTP flow

Local discovery flow

sequenceDiagram
  participant Tool as CLI or LSP
  participant Res as default_corelib_dependency_path
  participant Root as beskid_corelib
  Tool->>Res: env BESKID_CORELIB_ROOT or repo walk
  Res->>Root: normalize Project.proj path
  Root-->>Tool: graph node for Std / corelib

1. Tool starts project resolution.
2. default_corelib_dependency_path checks BESKID_CORELIB_ROOT, then discover_repo_corelib_root walking ancestors for compiler/corelib/beskid_corelib.
3. If CLI startup runs ensure_corelib_ready, bundled template materialization may populate install dir before step 2.
4. Aggregate manifest pulls workspace members into the compile plan.

CI publish flow

1. Build / verify corelib workspace in compiler CI.
2. beskid doc (when enabled) writes .beskid/docs/api.json + markdown.
3. beskid pckg pack on beskid_corelib/Project.proj with publisher credentials.
4. pckg server validates artifact (PackageArtifactValidator) and ingests docs for the package browser.
5. Consumers beskid fetch pinned versions into .beskid/packages/ recorded in Project.lock.

Shard cycle avoidance

When resolving manifests under compiler/corelib/packages/*, is_corelib_workspace_shard_manifest suppresses implicit Std back-edges to the aggregate package to prevent beskid_corelib → shard → beskid_corelib cycles.

Algorithm notes

• Trace one beskid_corelib compile in tests before editing resolver edge cases.
• Pack and discovery share parse_manifest — manifest errors surface identically in CLI and pack.
• Registry listing uses structured api.json as the docs UI contract when published.

Tests

compiler/crates/beskid_tests/src/projects/corelib/ (compile, layout, mod helpers).