Flow and algorithm

Platform spec article

Flow and algorithm

Back to Workspace and lock contracts ◎ 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

   Lock alignment.

   Decision

   Hub owns workspace and lock rules.

   Consequences

   CLI/IDE defer.

   Verification anchors

   resolution tests.

   Open full ADR page

2. 0002-lock-mutations-via-cli CLI lock mutations Accepted

   CLI lock mutations

   Context

   Resolver bypass risk.

   Decision

   fetch/lock must use CLI resolver.

   Consequences

   Matches VSC-0002.

   Verification anchors

   CLI integration.

   Open full ADR page

Articles

• Contracts and edge cases Workspace and lockfile guarantees for tooling operators. article Standard
• Design model Conceptual model for workspace manifests, lockfiles, and materialized dependency roots. article Standard
• Examples Workspace and lockfile examples for tooling workflows. article Standard
• FAQ and troubleshooting Workspace and lockfile troubleshooting for tooling users. article Standard
• Flow and algorithm Lock synchronization, fetch, and update flows for workspace tooling. article Standard
• Verification and traceability Tests and traceability for workspace and lock tooling contracts. 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
  Workspace and lock contracts

  Parent feature hub

• Feature
  pckg client contract

  Registry fetch HTTP surface

beskid lock flow

sequenceDiagram
  participant User
  participant CLI as beskid lock
  participant Analysis as beskid_analysis
  participant Disk as Project.lock
  User->>CLI: --project / member
  CLI->>Analysis: resolve graph (Warn on unresolved)
  Analysis->>Analysis: build CompilePlan + lock entries
  Analysis->>Disk: sync_project_lockfile
  CLI-->>User: synchronized message

1. Resolve workspace member or standalone Project.proj.
2. Walk dependencies (path + registry), applying workspace overrides.
3. Materialize or verify package roots per policy.
4. Serialize ProjectLockfileV1 beside the root manifest.
5. Skip write when on-disk lock already matches expected content.

beskid fetch / beskid update

• fetch resolves registry aliases to URLs (registry_urls), downloads packages via beskid_pckg, and lays out materialized roots referenced by future lock lines.
• update reapplies resolution with a stricter unresolved policy (typically failing on drift) and refreshes materialized trees.

Both commands must share graph construction with lock so CI and local machines produce comparable materialized_root paths.

LSP lock replay

When the language server lacks an in-memory prepared workspace:

1. Read Project.lock from the project root.
2. effective_roots_from_lockfile seeds dependency manifest paths.
3. Subsequent analysis uses the same roots until invalidation.

Corelib path injection during resolve

While walking the DAG, host projects without explicit Std receive implicit corelib path attachment (default_corelib_dependency_path in resolver.rs). Workspace shards under compiler/corelib/packages/* must not create cyclic back-links to the aggregate beskid_corelib package.

Tests

compiler/crates/beskid_tests/src/analysis/pipeline/core.rs and projects/corelib/layout.rs exercise workspace + lock layouts.