This feature hub explains how the compiler discovers `Project.proj`, builds a project graph, and hands resolved workspace inputs to compile and dependency commands. **`Mod`** projects are included in the graph like other project kinds; after resolution, the **mod host** registers them for **event-driven** orchestration per **[Project manifest contract](/platform-spec/tooling/manifests-and-lockfiles/project-manifest-contract/)** and **[Compiler Mods](/platform-spec/compiler/compiler-mods/)**.

## Implementation anchors
- `compiler/crates/beskid_analysis/src/projects/` — project graph discovery and manifest loading
- `compiler/crates/beskid_analysis/src/resolve/` — resolution pipeline and module graph construction
- `compiler/crates/beskid_analysis/src/mod_host/` — Mod project registration after resolution

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

## Context

This feature hub explains how the compiler discovers `Project.proj`, builds a project graph, and hands resolved workspace inputs to compile and dependency commands. **`Mod`** projects are included in the graph like other project kinds; after resolution, the **mod host** registers them for **event-driven** orchestration per **[Project manifest contract](/platform-spec/tooling/manifests-and-lockfiles/project-manifest-contract/)** and **[Compiler Mods](/platform-spec/compiler/compiler-mods/)**.

## Decision

The reference compiler **must** implement Workspace resolution contract as documented in this feature hub and its article bundle.

## Consequences

Changes require hub/ADR updates and verification anchor extensions.

## Verification anchors

- `compiler/crates/beskid_analysis/`

- Missing or malformed project manifests must produce stable project diagnostics, not parser panics.
- Unresolved dependencies must follow the selected policy and remain observable in command output.
- Explicit source-file input takes precedence over workspace target inference.
- Resolution must preserve deterministic target selection for identical manifests and lockfiles.

The resolution model has four core objects: `CompilePlan` (target + dependency plan), `PreparedProjectWorkspace` (materialized source roots and lockfile state), resolved source input (`source_path`, `source`) used by compile commands, and **`ProgramAssembly`** (multi-module units + `ModuleIndex` built from effective roots — see **[Program assembly](/platform-spec/compiler/build-pipeline/program-assembly/)**).

`beskid_analysis::projects` owns graph building and manifest semantics; CLI commands and LSP integrations consume this model and should not reimplement manifest traversal rules.

## `Mod` projects in the graph

**`Mod` projects** appear as graph nodes with **`type = Mod`**. Resolution **must**:

1. **Include all transitive `Mod` dependencies** of the active host compilation in the resolved dependency graph.
2. **Never treat `Mod` as the default compile target** for `beskid build` / `beskid run`; host builds resolve App/Lib/Test targets while still loading mod artifacts from dependencies.
3. **Expose the same graph slice to LSP and CLI** so mod scheduling decisions match across surfaces.

Scope narrowing for which host compilation units a mod affects is owned by **`Collector`** contracts at execution time, not by manifest attach metadata.

## Mod artifact resolution

When a `Mod` node is discovered:

1. Resolve package source (workspace path or registry materialization).
2. Check artifact hash against cached AOT output.
3. Rebuild when hash changes (eager incremental check) or when `beskid mod rebuild` is invoked.

Errors in mod artifact load/bootstrap use the **E1821–E1835** band (**[Diagnostic code registry](/platform-spec/compiler/semantic-pipeline/diagnostic-code-registry/)**, **[AOT artifact contract](/platform-spec/compiler/compiler-mods/mod-host-bridge/aot-artifact-contract/)**).

- **Single project:** `Project.proj` with one target yields one-entry `CompilePlan`; `resolve_input` points directly to that entry file.
- **Workspace with deps:** root target depends on local and registry packages; graph includes both, unresolved optional packages are reported according to policy.
- **Explicit file compile:** `beskid run Src/Main.bd` bypasses target inference and resolves directly from the provided file path.

## Why does the compiler ignore my workspace target?
Explicit file input overrides target inference; remove the explicit path to use manifest target resolution.

## Why did a dependency warning not fail the command?
The command may be using a warning-oriented unresolved dependency policy. Use a strict mode command or policy where available.

## Why does lockfile behavior differ between commands?
`--frozen` and `--locked` are command-level options propagated into workspace preparation options.

## Resolution pipeline

```mermaid
flowchart TD
  root[Discover project root]
  manifest[Load Project.proj]
  graph[Build dependency graph]
  policy[Apply cycle / missing dep policy]
  plan[Create CompilePlan]
  lock[Optional lockfile sync]
  entry[Source root + entry path]
  mods[Mod host event setup]
  root --> manifest --> graph --> policy --> plan
  plan --> lock --> entry
  plan --> mods
```

## Steps

1. Resolve project root and load `Project.proj` manifest.
2. Build dependency graph with policy (`error`, `warn`, or permissive) for unresolved dependencies.
3. Classify each node’s **project type** (including **`Mod`**) and retain manifest fragments needed for mod host registration.
4. Select compilation target and create `CompilePlan`.
5. Optionally materialize workspace and lockfile synchronization.
6. Return final source root and entry path for parsing/lowering.
7. If the workspace includes **`Mod`** projects, pass the resolved graph slice to the **mod host** for **event subscription** setup (see **[Compiler Mods](/platform-spec/compiler/compiler-mods/)**).

Implementations should use `build_compile_plan_with_policy` and `prepare_project_workspace_with_options` to keep command behavior aligned.

Primary implementation anchors:

- `compiler/crates/beskid_analysis/src/projects/compile_plan.rs`
- `compiler/crates/beskid_analysis/src/projects/manifest_resolve.rs` (workspace member selection aligned with CLI)
- `compiler/crates/beskid_analysis/src/compilation_context.rs` (analysis / LSP compile slice)
- `compiler/crates/beskid_analysis/src/projects/graph/builder.rs` (`discover_workspace_resolution_rules`, registry URLs)
- `compiler/crates/beskid_analysis/src/projects/workflow.rs` (registry materialization base URL)
- `compiler/crates/beskid_analysis/src/services/` (`resolve_input`, `analyze_source_with_compilation_context`)
- `compiler/crates/beskid_lsp/src/session/project_context.rs` (cached `CompilationContext`)
- `compiler/crates/beskid_cli/src/commands/fetch.rs`, `lock.rs`, `tree.rs`

Regression coverage should include fixed-fixture project graphs and lockfile policy permutations. Workspace member selection and `CompilationContext` are covered in `compiler/crates/beskid_tests/src/projects/resolution.rs`.