<SpecSection title="Authority split" id="authority-split">
**Tooling** owns **`Workspace.proj` / lockfile** schema, update commands, and author-facing reserved-key tables. **This feature** owns how the compiler **materializes** the dependency graph from locks, **rejects** inconsistent workspace layouts, and **diagnoses** resolution failures during analysis and CI builds.
</SpecSection>

<SpecSection title="Implementation anchors" id="implementation-anchors">
- `compiler/crates/beskid_analysis/src/resolve/mod.rs` — project and dependency resolution
- `compiler/crates/beskid_cli/src/commands/` — lock policy flags and update entrypoints
- `compiler/crates/beskid_tests/src/projects/corelib/compile.rs` and `layout.rs` — lock-sensitive workspace fixtures
- `compiler/crates/beskid_tests/src/analysis/pipeline/core.rs` — workspace pipeline tests
</SpecSection>

## Decisions
<!-- spec:generate:adr-index -->
No open decisions. Closed choices are normative ADRs under **`adr/`** (`D-COMP-PROJ-0010` … `D-COMP-PROJ-0012`); use the reader **ADRs** tab for expandable detail.
<!-- /spec:generate:adr-index -->
## Articles
<!-- spec:generate:article-index -->
- [Workspace and lock contracts - Contracts and edge cases](./articles/contracts-and-edge-cases/)
- [Workspace and lock contracts - Design model](./articles/design-model/)
- [Workspace and lock contracts - Examples](./articles/examples/)
- [Workspace and lock contracts - FAQ and troubleshooting](./articles/faq-and-troubleshooting/)
- [Workspace and lock contracts - Flow and algorithm](./articles/flow-and-algorithm/)
- [Workspace and lock contracts - Verification and traceability](./articles/verification-and-traceability/)
<!-- /spec:generate:article-index -->

## Context

Sibling articles under this feature previously restated requirements in inconsistent forms.

## Decision

This feature hub **owns** normative MUST/SHOULD contract text. Sibling articles **must not** redefine hub requirements and **should** link here for authority.

## Consequences

Contract changes start on the hub or in linked ADRs, then propagate to articles and implementation anchors.

## Verification anchors

- `site/website/src/content/docs/platform-spec/compiler/resolution-and-projects/workspace-and-lock-contracts/index.mdx`
- `article bundle under the same feature directory.`

## Context

Implementation crates accumulated informal notes that diverged from published contracts.

## Decision

Normative platform-spec prose and ADRs under this feature **supersede** informal comments in implementation crates until explicitly migrated into spec text.

## Consequences

Engineers file spec/ADR updates when behavior changes; crate comments are non-authoritative for conformance arguments.

## Verification anchors

- `compiler/crates/beskid_analysis/src/resolve/mod.rs`
- `compiler/crates/beskid_cli/src/commands/`
- `compiler/crates/beskid_tests/src/projects/corelib/compile.rs`

## Context

Floating registry versions broke reproducible compiles.

## Decision

Workspace resolution **must** honor lockfile pins from `beskid_analysis::resolve` before applying CLI overrides.

## Consequences

Lock update commands are explicit; silent refresh is forbidden in CI modes.

## Verification anchors

- `compiler/crates/beskid_analysis/src/resolve/mod.rs`
- `compiler/crates/beskid_cli/src/commands/`.

## Compiler contracts

- **Deterministic graph** — Given the same lock snapshot and workspace layout, resolution produces the same member DAG.
- **Layout invariants** — Folder layout under workspace members must match what lock materialization expects; violations fail before semantic analysis.
- **No silent lock ignore** — When CI or `--locked` policy is active, missing or stale locks are errors, not warnings-only, unless tooling explicitly defines a warning mode for that command.

## Edge cases (resolution)

- **Stale lock vs registry** — Pin resolution failures surface at materialize time with stable diagnostics.
- **Partial member checkout** — Missing member directories fail graph build with layout-specific codes.
- **Cross-feature manifest errors** — Invalid `Project.proj` nodes still fail in the project-manifest resolution path first.

Workspace key forbiddances and reserved names are specified in **[tooling / design model](/platform-spec/tooling/manifests-and-lockfiles/workspace-and-lock-contracts/design-model/)** and are not duplicated here.

## Code anchors

- `compiler/crates/beskid_tests/src/projects/corelib/compile.rs`
- `compiler/crates/beskid_tests/src/projects/corelib/layout.rs`
- `compiler/crates/beskid_cli/src/commands/`

## Resolution model (compiler)

| Entity | Role |
| --- | --- |
| Workspace root | Anchor for member `Project.proj` discovery |
| Lock snapshot | Pinned dependency versions consumed when building the graph |
| Materialized package root | On-disk layout the resolver uses after lock apply |

The compiler **must** treat lock-backed roots as authoritative for reproducible CI graphs. Ad-hoc workspace toggles that alter Mod policy without a spec bump are rejected at parse time in tooling; the compiler enforces the resulting graph only.

## Schema authority

Reserved and forbidden **`Workspace.proj`** keys, `defaultMember`, and lock update semantics are defined in **[tooling / design model](/platform-spec/tooling/manifests-and-lockfiles/workspace-and-lock-contracts/design-model/)**. This article does not duplicate those tables.

## Code anchors

- `compiler/crates/beskid_analysis/src/resolve/mod.rs`
- `compiler/crates/beskid_cli/src/commands/`
- `compiler/crates/beskid_tests/src/projects/corelib/layout.rs`

This article documents **examples** for **workspace and lock contracts** in the reference compiler.

## What this covers
For newcomers, this page explains where the contract shows up in day-to-day compiler work and which code paths are most useful first reads.

## Anchored code paths
- `compiler/crates/beskid_tests/src/projects/corelib/compile.rs` covers lock-sensitive workspace builds.
- `compiler/crates/beskid_tests/src/projects/corelib/layout.rs` validates workspace folder invariants.
- `compiler/crates/beskid_cli/src/commands/` is the public entrypoint for lock policy flags.

## Practical notes
- Prefer tracing from CLI/test entry points into analysis/codegen crates before changing internals.
- Treat diagnostics and tests as part of the contract, not optional implementation details.
- If behavior changes, update this article and add/adjust tests in `compiler/crates/beskid_tests` or `compiler/crates/beskid_e2e_tests`.

This article documents **faq and troubleshooting** for **workspace and lock contracts** in the reference compiler.

## What this covers
For newcomers, this page explains where the contract shows up in day-to-day compiler work and which code paths are most useful first reads.

## Anchored code paths
- `compiler/crates/beskid_tests/src/projects/corelib/compile.rs` covers lock-sensitive workspace builds.
- `compiler/crates/beskid_tests/src/projects/corelib/layout.rs` validates workspace folder invariants.
- `compiler/crates/beskid_cli/src/commands/` is the public entrypoint for lock policy flags.

## Practical notes
- Prefer tracing from CLI/test entry points into analysis/codegen crates before changing internals.
- Treat diagnostics and tests as part of the contract, not optional implementation details.
- If behavior changes, update this article and add/adjust tests in `compiler/crates/beskid_tests` or `compiler/crates/beskid_e2e_tests`.

## Resolution flow

1. **Locate** workspace root and member projects.
2. **Load** lock snapshot (or fail if policy requires a lock and none is present).
3. **Materialize** dependency roots from lock pins into the resolver cache layout.
4. **Build** the combined workspace/project graph (see [project manifest contract / flow](/platform-spec/compiler/resolution-and-projects/project-manifest-contract/flow-and-algorithm/)).
5. Proceed to analysis only when graph and layout invariants pass.

CLI lock **update** and author workflows are described under **[tooling / flow and algorithm](/platform-spec/tooling/manifests-and-lockfiles/workspace-and-lock-contracts/flow-and-algorithm/)**.

## Code anchors

- `compiler/crates/beskid_analysis/src/resolve/mod.rs`
- `compiler/crates/beskid_cli/src/commands/`
- `compiler/crates/beskid_tests/src/analysis/pipeline/core.rs`

This article documents **verification and traceability** for **workspace and lock contracts** in the reference compiler.

## What this covers
For newcomers, this page explains where the contract shows up in day-to-day compiler work and which code paths are most useful first reads.

## Anchored code paths
- `compiler/crates/beskid_tests/src/projects/corelib/compile.rs` covers lock-sensitive workspace builds.
- `compiler/crates/beskid_tests/src/projects/corelib/layout.rs` validates workspace folder invariants.
- `compiler/crates/beskid_cli/src/commands/` is the public entrypoint for lock policy flags.

## Practical notes
- Prefer tracing from CLI/test entry points into analysis/codegen crates before changing internals.
- Treat diagnostics and tests as part of the contract, not optional implementation details.
- If behavior changes, update this article and add/adjust tests in `compiler/crates/beskid_tests` or `compiler/crates/beskid_e2e_tests`.