<SpecSection title="Authority split" id="authority-split">
**Tooling** owns the normative **`Project.proj` schema** (keys, types, Mod blocks, link metadata, and CLI/LSP examples). **This feature** owns how the reference compiler **loads**, **validates in the resolution graph**, and **diagnoses** manifest-driven project graphs—without duplicating key tables.

When editing manifest keys, update [tooling / design model](/platform-spec/tooling/manifests-and-lockfiles/project-manifest-contract/design-model/) first; adjust compiler resolution text here only when graph behavior or diagnostic bands change.
</SpecSection>

<SpecSection title="Implementation anchors" id="implementation-anchors">
- `compiler/crates/beskid_analysis/src/bsol.pest` — Bsol surface grammar for manifests
- `compiler/crates/beskid_analysis/src/projects/bsol/` — AST builder (`parse_bsol_document`)
- `compiler/crates/beskid_analysis/src/projects/manifest_resolve.rs` — discovery and parse into workspace graph
- `compiler/crates/beskid_analysis/src/projects/graph/` — DAG insertion, Mod topology
- `compiler/crates/beskid_cli/src/commands/` — manifest-driven compile inputs
- `compiler/crates/beskid_tests/src/projects/corelib/mod.rs` and `compile.rs` — manifest fixtures
</SpecSection>

## Decisions
<!-- spec:generate:adr-index -->
No open decisions. Closed choices are normative ADRs under **`adr/`** (`D-COMP-PROJ-0004` … `D-COMP-PROJ-0006`); use the reader **ADRs** tab for expandable detail.
<!-- /spec:generate:adr-index -->
## Articles
<!-- spec:generate:article-index -->
- [Project manifest contract - Contracts and edge cases](./articles/contracts-and-edge-cases/)
- [Project manifest contract - Design model](./articles/design-model/)
- [Project manifest contract - Examples](./articles/examples/)
- [Project manifest contract - FAQ and troubleshooting](./articles/faq-and-troubleshooting/)
- [Project manifest contract - Flow and algorithm](./articles/flow-and-algorithm/)
- [Project manifest 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/project-manifest-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/src/projects/manifest_resolve.rs`
- `compiler/crates/beskid_analysis/src/projects/graph/`
- `compiler/crates/beskid_cli/src/commands/`

## Context

Manifest key tables were duplicated between tooling and compiler specs.

## Decision

Author-facing `Project.proj` key tables live only under tooling; this compiler feature documents resolution graph behavior and defers schema prose via `relatedTopics`.

## Consequences

Compiler changes manifest parsing only when graph or diagnostic bands change; tooling spec leads schema edits.

## Verification anchors

- `compiler/crates/beskid_analysis/src/projects/manifest_resolve.rs`
- `tooling project-manifest-contract hub.`

## Compiler resolution contracts

- **Graph before compile** — No host `CompilePlan` runs until workspace/project DAG validation succeeds.
- **Mod carriers only in graph** — Compiler-mod contracts are reachable only through resolved `type: Mod` nodes (see tooling for manifest-level rules).
- **Stable diagnostics** — Graph and resolution failures use assigned codes in **E1801–E1899**; changing codes requires registry and test updates.
- **Transitive Mod closure** — Host builds must resolve the full transitive Mod set before `mod.load`; partial graphs are errors.

## Edge cases (resolution)

- **Dependency cycles** — Any cycle in the workspace/project graph is a hard error at graph build time.
- **Missing materialized package** — Unresolved registry or lock roots fail before analysis, with distinct codes from parse errors.
- **Lock/workspace drift** — Mismatches between lockfile pins and on-disk layout are diagnosed in the workspace feature; see [workspace and lock contracts](/platform-spec/compiler/resolution-and-projects/workspace-and-lock-contracts/).

Mod-specific manifest shape rules (`capabilities`, `maxGeneratorRounds`, host targets on Mod projects) are **not** duplicated here; see **[tooling / contracts and edge cases](/platform-spec/tooling/manifests-and-lockfiles/project-manifest-contract/contracts-and-edge-cases/)**.

## Code anchors

- `compiler/crates/beskid_analysis/src/projects/graph/`
- `compiler/crates/beskid_tests/src/projects/corelib/mod.rs`
- `compiler/crates/beskid_tests/src/projects/corelib/compile.rs`

## Resolution model (compiler)

After structural parse (owned by tooling schema), the compiler materializes:

| Entity | Role |
| --- | --- |
| `ProjectManifest` | Typed view of one `Project.proj` node |
| Workspace/project graph node | Member in the resolved DAG with dependency edges |
| `Mod` package node | Compiler-mod carrier; validated for topology, not re-documented key-by-key here |
| `Template` package node | Template authoring root; **excluded** from host compile plans until scaffold output exists |

**Graph validation** runs after parse: invalid Mod dependency cycles, incompatible capability requirements, and missing materialized roots **must** emit stable diagnostics in the mod/manifest band (**E1801–E1899**); see [Diagnostic code registry](/platform-spec/compiler/semantic-pipeline/diagnostic-code-registry/).

## Schema authority

All normative **`project`**, **`project.mod`**, **`project.template`**, **`type`** (`Host`, `Mod`, `Template`), readme, and **`project.link`** key definitions live in **[tooling / design model](/platform-spec/tooling/manifests-and-lockfiles/project-manifest-contract/design-model/)**. This article intentionally omits duplicate key tables.

**`Template`** nodes **must not** be selected for `beskid build` / `run` on the authoring tree; the template engine consumes **`.beskid/template.json`** instead. Scaffold instantiation diagnostics use **E1901–E1999** (see **[Project templates](/platform-spec/tooling/project-scaffolding/project-templates/)**).

## Code anchors

- `compiler/crates/beskid_analysis/src/projects/manifest_resolve.rs`
- `compiler/crates/beskid_analysis/src/projects/graph/`
- `compiler/crates/beskid_analysis/src/services/` — session orchestration after graph is known

This article documents **examples** for **project manifest contract** 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_cli/src/commands/` reads manifest-driven compile inputs.
- `compiler/crates/beskid_tests/src/projects/corelib/mod.rs` uses manifest-aware project fixtures.
- `compiler/crates/beskid_tests/src/projects/corelib/compile.rs` verifies manifest-based compile execution.

## 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 **project manifest contract** 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_cli/src/commands/` reads manifest-driven compile inputs.
- `compiler/crates/beskid_tests/src/projects/corelib/mod.rs` uses manifest-aware project fixtures.
- `compiler/crates/beskid_tests/src/projects/corelib/compile.rs` verifies manifest-based compile execution.

## 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. **Discover** `Project.proj` paths from workspace roots (`manifest_resolve`).
2. **Parse** into `ProjectManifest` (structural errors surface before graph insertion).
3. **Insert** node; run **graph validation** (cycles, Mod-only contract carriers, incompatible edges).
4. For host targets, **materialize transitive `Mod` dependencies** and ensure AOT artifacts exist (cache hit or build).
5. Hand off to **`CompilePlan`** and [stage ordering](/platform-spec/compiler/build-pipeline/stage-ordering/) for semantic and mod pipelines.

Author-oriented step-by-step validation (including optional `project.mod` keys) is specified in **[tooling / flow and algorithm](/platform-spec/tooling/manifests-and-lockfiles/project-manifest-contract/flow-and-algorithm/)** without repeating that prose here.

## Code anchors

- `compiler/crates/beskid_analysis/src/projects/manifest_resolve.rs`
- `compiler/crates/beskid_analysis/src/projects/compile_plan.rs`
- `compiler/crates/beskid_cli/src/commands/`

This article documents **verification and traceability** for **project manifest contract** 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_cli/src/commands/` reads manifest-driven compile inputs.
- `compiler/crates/beskid_tests/src/projects/corelib/mod.rs` uses manifest-aware project fixtures.
- `compiler/crates/beskid_tests/src/projects/corelib/compile.rs` verifies manifest-based compile execution.

## 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`.