Contracts and edge cases

Platform spec article

Contracts and edge cases

Back to Build, analyze, and run contract ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (2)

1. 0001-hub-authority Hub authority Accepted

   Hub authority

   Context

   Drift risk.

   Decision

   Hub owns MUST/SHOULD.

   Consequences

   Articles defer.

   Verification anchors

   trudoc.

   Open full ADR page

2. 0002-shared-analysis-pipeline Shared pipeline Accepted

   Shared pipeline

   Context

   CLI/LSP divergence.

   Decision

   Use beskid_analysis aligned with LSP.

   Consequences

   Parity.

   Verification anchors

   pipeline tests.

   Open full ADR page

Articles

• Contracts and edge cases Strict guarantees and failure modes for build, analyze, and run CLI behavior. article Standard
• Design model Conceptual model for `Build, analyze, and run contract` and its subsystem boundaries. article Standard
• Examples Concrete CLI invocations for build, analyze, and run workflows. article Standard
• FAQ and troubleshooting Common questions and fixes for build, analyze, and run CLI behavior. article Standard
• Flow and algorithm Lifecycle and execution flow for `Build, analyze, and run contract`. article Standard
• Verification and traceability Tests and traceability for the build, analyze, and run CLI contract. 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 · 3 SpecSection(s) · 0 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
  Build, analyze, and run contract

  Parent feature hub

• Feature
  Diagnostics parity

  Shared diagnostic shaping with LSP

Normative contracts

• Single analysis entry — Project-scoped commands must not fork ad-hoc parsers that skip CompilationContext when a Project.proj is in scope.
• Corelib always on — Host projects must resolve implicit Std / corelib; manifests must not opt out (noCorelib, useCorelib: false are parse errors in beskid_analysis projects/parser.rs).
• Exit codes — Semantic errors on analyze must yield non-zero process exit; build/run must propagate linker/JIT failures without masking as warnings.
• Pipeline truthfulness — Reported phase IDs must correspond to real beskid_pipeline stages; silent no-ops are forbidden for declared progress events.
• Mod parity — Capability denial and generator round exhaustion must match LSP diagnostics (same codes, same severity).

Edge cases

Situation	Expected behavior
Input is a .bd file outside any project root	File-scoped commands work; project commands error with manifest discovery diagnostics
Missing Project.lock under strict policy	build/run fail with lock policy message before lowering
Mod artifact cache miss	build triggers AOT compile or reports cache policy failure; no partial host compile
Multiple workspace members	--project / focused member selection must match LSP BESKID_WORKSPACE_MEMBER_FOR_META_DEFAULT semantics when set
--entrypoint on non-app target	Rejected with stable CLI error (no silent default to main)
Corelib root only via env	BESKID_CORELIB_ROOT and install layout fallbacks in resolver.rs apply before graph build

Foreign libraries and link metadata

FFI link lines come from project.link on host manifests (see Project link libraries). build must pass resolved native libraries to the AOT linker when present; missing symbols fail at link time, not at runtime silently.