Contracts and edge cases

Platform spec article

Contracts and edge cases

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 discovery and packaging

  Canonical roots and publishing

Contracts

• No opt-out — Host manifests must not disable corelib; parser rejects forbidden keys.
• Single aggregate identity — Implicit attachment targets beskid_corelib / package name corelib, not arbitrary forks, unless explicitly overridden by a declared Std path dependency in advanced layouts.
• Transitive closure — Host compilations must see the full corelib workspace member packages required by the aggregate manifest.
• Mod projects — Mod packages do not receive implicit host injection rules; they compile as mod carriers, not application hosts.
• Template output — Instantiated host projects from templates follow host rules (implicit corelib).

Edge cases

Case	Behavior
Explicit Std dependency	Used instead of fallback path when path provided
beskid_corelib building itself	is_std_project / manifest path checks avoid self-cycle
Shard under packages/runtime	No implicit back-link to aggregate
Missing BESKID_CORELIB_ROOT in CI	Repo discovery or bundled CLI corelib materialization
Legacy standard_library paths	Tooling may accept aliases; canonical identity remains corelib

Relationship to discovery feature

Packaging, readme, and pckg publish rules live under Corelib discovery and packaging; injection assumes those roots exist on disk or in cache.