<SpecSection title="What this feature specifies" id="what-this-feature-specifies">
This feature explains how the project proves that implemented behavior remains stable release over release. It is organized into newcomer-friendly articles that move from model, to flow, to contracts, then practical verification and debugging guidance.
</SpecSection>

<SpecSection title="Implementation anchors" id="implementation-anchors">
- `compiler/crates/beskid_tests/src/analysis` fixture-driven semantic assertions
- `compiler/crates/beskid_tests/src/runtime` runtime behavior checks
- `compiler/crates/beskid_e2e_tests/src/tests/runtime_cases.rs` source-to-runtime outcomes
- `compiler/crates/beskid_tests/src/doc_tests.rs` docs-driven verification
- `compiler/crates/beskid_tests/src/mods` compiler-mod tests (manifest goldens, pipeline ordering, incremental replay, analyzer coverage)
- `compiler/crates/beskid_tests/src/spine` spine parity and diagnostics round-trip tests
- `compiler/crates/beskid_tests/src/lsp` LSP integration tests (completion, hover, references, semantic tokens)
</SpecSection>

## Decisions
<!-- spec:generate:adr-index -->
No open decisions. Closed choices are normative ADRs under **`adr/`** (`D-COMP-CONF-0004` … `D-COMP-CONF-0007`); use the reader **ADRs** tab for expandable detail.
<!-- /spec:generate:adr-index -->
## Articles
<!-- spec:generate:article-index -->
- [Contracts and edge cases](./articles/contracts-and-edge-cases/)
- [Design model](./articles/design-model/)
- [Examples](./articles/examples/)
- [FAQ and troubleshooting](./articles/faq-and-troubleshooting/)
- [Flow and algorithm](./articles/flow-and-algorithm/)
- [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/conformance/test-harnesses-and-fixtures/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_tests/src/analysis`
- `compiler/crates/beskid_tests/src/runtime`
- `compiler/crates/beskid_e2e_tests/src/tests/runtime_cases.rs`

## Context

This feature explains how the project proves that implemented behavior remains stable release over release. It is organized into newcomer-friendly articles that move from model, to flow, to contracts, then practical verification and debugging guidance.

## Decision

The reference compiler **must** implement Test harnesses and fixtures 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_tests/src/analysis`
- `compiler/crates/beskid_tests/src/runtime`
- `compiler/crates/beskid_e2e_tests/src/tests/runtime_cases.rs`

## Context

Regressions in parallel analyze vs execute paths and incomplete codegen linking were not gated by a single conformance suite tied to the unified spine ADRs.

## Decision

The reference compiler **must** maintain:

| Fixture class | Requirement |
| --- | --- |
| Diagnostics parity | For a fixed corpus (≥20 project fixtures), CLI analyze / semantic gate diagnostics **must** equal `prepare_compilation(DiagnosticsOnly)` diagnostics (codes and presence; path labels may differ per D-COMP-BUILD-0012) |
| Link completeness | Project-backed run/test/build fixtures **must** pass `validate_artifact` with no undefined callees |
| Corelib matrix | Every `corelib_tests` target in `beskid_corelib/tests/corelib_tests` **must** pass under `beskid test` using the workspace-built CLI in CI |

New spine regressions **must** add a fixture in `beskid_tests` before closing related ADRs.

## Consequences

`compiler/crates/beskid_tests/src/spine/` hosts parity tests. Engine and codegen integration tests migrate off raw `lower_source` per D-COMP-IR-0011.

## Verification anchors

- `compiler/crates/beskid_tests/src/spine/`
- `compiler/crates/beskid_codegen/tests/array_tests_linking.rs`
- `compiler/corelib/ci/run_corelib_tests.py`
- `compiler/crates/beskid_tests/src/runtime/jit.rs`

## Normative contracts

- Producer crates must emit data in a shape accepted by downstream consumers.
- Consumer crates must not silently reinterpret the contract surface.
- Contract regressions must be captured as compile-time or test-time failures, not hidden runtime drift.

## Edge cases to monitor

- Partial refactors that update only one side of a crate boundary.
- Symbol/name changes that compile locally but break cross-crate integration.
- Fixtures that pass in isolation but fail in end-to-end harnesses.

## Failure handling expectations

When contract checks fail, diagnostics should point contributors to the responsible boundary crate and to the corresponding conformance fixture.

## Harness layers

Conformance is split so failures localize quickly:

| Layer | Crate path | Pins |
| --- | --- | --- |
| **Analysis fixtures** | `beskid_tests/src/analysis` | Diagnostic codes, resolver graphs, staged rules |
| **Runtime JIT** | `beskid_tests/src/runtime` | Builtin dispatch, GC, fibers |
| **E2E sources** | `beskid_e2e_tests` | Full `.bd` programs through CLI backends |
| **Doc tests** | `beskid_tests/src/doc_tests.rs` | Spec snippets compile and match asserted output |

```mermaid
flowchart LR
  fixture[.bd / .json fixtures]
  analysis[analysis harness]
  runtime[runtime harness]
  e2e[e2e harness]
  fixture --> analysis
  fixture --> runtime
  fixture --> e2e
  analysis --> diag[Diagnostic snapshot]
  runtime --> jit[JIT smoke]
  e2e --> exit[Process exit + IO]
```

## Fixture conventions

- Prefer **minimal** `.bd` files per diagnostic or rule; share `Project.proj` layouts via `beskid_tests/src/projects` builders.
- Golden diagnostics **must** cite stable codes from [diagnostic code registry](/platform-spec/compiler/semantic-pipeline/diagnostic-code-registry/).
- Runtime tests **must** negotiate the same ABI version as production `beskid run`.

## Code anchors

- `compiler/crates/beskid_tests/src/analysis`
- `compiler/crates/beskid_tests/src/runtime`
- `compiler/crates/beskid_e2e_tests/src/tests/runtime_cases.rs`
- `compiler/crates/beskid_tests/src/doc_tests.rs`

## Example 1: Happy path

A standard project exercises the expected producer -> consumer handoff with no contract violations. Trace this via:

- `compiler/crates/beskid_tests/src/analysis` for fixture-driven semantic assertions
- `compiler/crates/beskid_e2e_tests/src/tests/runtime_cases.rs` for source-to-runtime outcomes

## Example 2: Contract mismatch

Intentionally alter a boundary definition (for example, a symbol or structure shape), then run the related conformance suite. The expected result is a deterministic failure that identifies the mismatched boundary.

## Example 3: Regression-proofing a fix

After applying a fix, add or update a focused fixture in the nearest test crate and rerun wider suites so the behavior remains locked for future refactors.

## Why did a change pass locally but fail in CI?

Most often, one crate boundary changed but the corresponding fixture or downstream consumer was not updated. Re-run the nearest conformance suite and inspect cross-crate handoff points.

## Where should I start debugging?

1. Confirm the target requirement in this feature hub.
2. Step through `compiler/crates/beskid_tests/src/analysis` and `compiler/crates/beskid_tests/src/runtime`.
3. Validate consumer behavior at `compiler/crates/beskid_e2e_tests/src/tests/runtime_cases.rs`.
4. Reproduce with `compiler/crates/beskid_tests/src/doc_tests.rs`.

## How do I add a new rule safely?

Document the new contract in the relevant article, update implementation in the owning crate, and add a fixture proving both happy-path and failure-path behavior.

## End-to-end flow

1. Input enters compiler/runtime boundary at a stable entrypoint.
2. The responsible crate enforces the expected shape and emits stable structures.
3. Downstream crates consume those structures without redefining semantics.
4. Conformance tests assert behavior at integration boundaries.

## Algorithm notes for newcomers

- Prefer tracing one fixture end-to-end before reading all modules.
- Verify where shape conversion happens; avoid assuming all crates mutate data.
- Keep an eye on handoff points where diagnostics or ABI constraints are locked.

## Where to step through code

- Start with `compiler/crates/beskid_tests/src/analysis` for fixture-driven semantic assertions.
- Then inspect `compiler/crates/beskid_tests/src/runtime` for runtime behavior checks.
- Follow consumption at `compiler/crates/beskid_e2e_tests/src/tests/runtime_cases.rs` for source-to-runtime outcomes.
- Validate expectations using `compiler/crates/beskid_tests/src/doc_tests.rs` for docs-driven verification.

## Verification strategy

- Unit-level checks validate local transformations.
- Integration tests validate crate-to-crate contracts.
- End-to-end fixtures validate user-visible behavior.

## Traceability map

- Spec requirement source: `/platform-spec/compiler/conformance/test-harnesses-and-fixtures/`.
- Core implementation anchors:
  - `compiler/crates/beskid_tests/src/analysis` fixture-driven semantic assertions
  - `compiler/crates/beskid_tests/src/runtime` runtime behavior checks
  - `compiler/crates/beskid_e2e_tests/src/tests/runtime_cases.rs` source-to-runtime outcomes
- Conformance anchor:
  - `compiler/crates/beskid_tests/src/doc_tests.rs` docs-driven verification

## Review checklist

- Requirement text and test expectation describe the same boundary.
- Crate ownership updates are reflected in spec links.
- Newly introduced edge cases include at least one reproducible fixture.