Design model

Platform spec article

Design model

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

• Area
  Manifests and lockfiles

  Parent area

• Feature
  Workspace and lock contracts

  Parent feature hub

• Feature
  Workspace and lock contracts (compiler)

  implements — lock parsing, layout invariants, resolution diagnostics

• Feature
  Project manifest contract

  Per-project `Project.proj` shape

Purpose

Tooling-facing contract for Workspace.proj, per-member Project.proj graphs, and Project.lock v1 files that pin materialized dependency roots. The compiler realizes graph resolution and lock sync in beskid_analysis::projects; this article defines what operators and CLI commands may assume without restating full manifest key tables.

Artifacts

flowchart TB
  WS[Workspace.proj]
  PM[Member Project.proj]
  Lock[Project.lock v1]
  Mat[Materialized package roots]
  WS --> PM
  PM --> Lock
  Lock --> Mat
  Mat --> Graph[Project DAG + CompilePlan]

Artifact	Role
Workspace.proj	Declares member projects, registry URL aliases, optional dependency overrides
Project.proj	Declares dependencies, targets, project kind (Host, Mod, Template) — see Project manifest contract
Project.lock	Records root_manifest, resolved dependency names, manifest paths, source_root, materialized_root
workspace.package.json	Optional npm-style metadata for editor hints; not a compiler graph input

Resolution rules surface

WorkspaceResolutionRules (in resolver.rs) carries:

• workspace_root and workspace_members
• overrides_by_dependency (version pins)
• registry_aliases and registry_urls for beskid fetch / registry client

Registry dependencies resolve through beskid_pckg HTTP flows; path dependencies normalize under the consumer project root.

Lockfile semantics (tooling view)

• Header must be # Project.lock v1.
• Each dependency line must include name, manifest, project, source_root, materialized_root.
• beskid lock synchronizes lock content from the current CompilePlan (sync_project_lockfile in workflow.rs).
• LSP may replay effective_roots_from_lockfile when a prepared workspace cache is absent.

Workspace readme

The workspace block may include readme = "relative/path.md" with the same publishing behavior as project readmes (pack → root README.md in .bpk). Details live under Project manifest contract — design model.

Implementation anchors

• Lock format + sync: compiler/crates/beskid_analysis/src/projects/workflow.rs
• Graph resolver: compiler/crates/beskid_analysis/src/projects/graph/resolver.rs
• CLI: compiler/crates/beskid_cli/src/commands/lock.rs, fetch.rs, update.rs
• Lock replay: compiler/crates/beskid_analysis/src/projects/assembly/roots.rs