Contracts and edge cases

Platform spec article

Contracts and edge cases

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 (compiler)

  implements — normative lock band diagnostics

Contracts

• Lock header version — Only # Project.lock v1 is accepted; unknown headers must error.
• Required lock fields — Each dependency entry must include materialized and source roots for replay.
• Registry alias resolution — Unknown aliases must fail at fetch time with actionable messages.
• Workspace member integrity — Every member path must resolve to a Project.proj under the workspace root.
• Reproducible materialization — materialized_root paths must be stable for a given lock file on the same machine class (OS-specific subtrees allowed when documented in compiler feature).

Edge cases

Case	Behavior
Missing lock under strict CLI policy	build/run fail before compile
Stale lock after manifest edit	lock/update rewrite; LSP invalidates compilation cache
Partial fetch failure	Unresolved dependency policy (Warn vs Error) controls whether graph proceeds
Duplicate dependency names	Validation error during graph build
Corelib-only path fallback	Implicit Std edge omitted for corelib workspace shards to avoid cycles

pckg integration

Published workspace bundles on the registry use server-side validation in pckg/src/Server/Services/Workspace/ (WorkspacePublishService, WorkspacePackageManifest). Client-side beskid pckg commands must emit manifests compatible with those validators before upload.