Flow and algorithm

Platform spec article

Flow and algorithm

Back to Corelib injection and resolution ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (4)

1. 0005-host-corelib-no-opt-out Host projects cannot opt out of corelib Accepted

   Parser rejects noCorelib and useCorelib false.

   Context

   Every host compilation must see the standard library graph.

   Decision

   Rule	Detail
   Forbidden keys	noCorelib, useCorelib: false rejected at parse
   Templates	Scaffolds must not emit opt-out keys

   Consequences

   Implicit injection in resolve_dependencies always attaches corelib.

   Verification anchors

   projects/parser.rs; template manifest tests.

   Open full ADR page

2. 0006-workspace-shard-cycle-guard Workspace shard cycle guard Accepted

   Corelib member packages must not implicit-back-link to aggregate.

   Context

   Shards under packages/* would create cycles if they gained implicit host edges.

   Decision

   Rule	Detail
   Guard	is_corelib_workspace_shard_manifest skips implicit back-edge
   Host	Only application hosts receive implicit corelib

   Consequences

   Building packages/runtime alone does not pull beskid_corelib as a hidden parent.

   Verification anchors

   resolver.rs; corelib workspace compile tests.

   Open full ADR page

3. 0007-mod-projects-exempt Mod projects exempt from host injection Accepted

   Compiler mods compile as carriers without host corelib rules.

   Context

   Mods are not end-user hosts; injecting corelib would distort mod graphs.

   Decision

   Rule	Detail
   Mod	Does not receive implicit host injection
   Host	Receives implicit corelib per D-CORE-COMP-0005

   Consequences

   Mod SDK projects declare their own dependency closure.

   Verification anchors

   Mod project tests in beskid_tests.

   Open full ADR page

4. 0008-cli-lsp-resolver-parity CLI and LSP resolver parity Accepted

   CLI and LSP share corelib discovery and graph options.

   Context

   IDE analysis must match CLI compilation attachment.

   Decision

   Rule	Detail
   CLI	ensure_corelib_ready before commands
   LSP	CompilationContext::try_for_analysis_path_with_graph_options

   Consequences

   Diagnostic drift between CLI and LSP indicates a resolver bug.

   Verification anchors

   LSP workspace tests; corelib/compile.rs.

   Open full ADR page

Articles

• Contracts and edge cases Corelib injection guarantees and edge cases. article Standard
• Design model How the compiler injects and resolves the corelib package into host compilations. article Standard
• Examples Observable corelib injection scenarios. article Standard
• FAQ and troubleshooting Corelib injection and resolution FAQ. article Standard
• Flow and algorithm End-to-end flow for corelib injection during project graph resolution. article Standard
• Verification and traceability Tests and traceability for corelib injection and resolution. 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 injection and resolution

  Parent feature hub

Graph build sequence

sequenceDiagram
  participant CLI as CLI or LSP
  participant Ctx as CompilationContext
  participant Res as resolve_dependencies
  participant Core as beskid_corelib
  CLI->>Ctx: resolve Project.proj
  Ctx->>Res: walk consumer dependencies
  alt host without explicit Std
    Res->>Core: attach_path_dependency (implicit)
  end
  Res-->>Ctx: DAG + has_std flag
  Ctx->>Ctx: CompilePlan for host target

1. Load consumer ProjectManifest.
2. For each declared dependency, attach path or registry materialization per Workspace and lock contracts.
3. If consumer is a host project, not a corelib shard, and lacks Std, call default_corelib_dependency_path() and attach as path dependency.
4. Recurse into corelib aggregate and its workspace package shards (foundation, runtime, console, compiler-sdk).
5. Build CompilePlan; semantic pipeline resolves symbols across all assemblies.

Environment and install paths

BESKID_CORELIB_ROOT may be the aggregate package directory or the parent workspace root (nested beskid_corelib/Project.proj detection in corelib_aggregate_project_dir).

Failure modes

Failure	Stage
Corelib root not found	Graph validation — manifest band diagnostics
Cycle via shard back-link	Prevented by is_corelib_workspace_shard_manifest guard
Opt-out manifest keys	Structural parse error before graph

Verification

compiler/crates/beskid_tests/src/projects/corelib/compile.rs and mod.rs assert compile success with implicit injection; layout tests ensure workspace shards do not create cycles.