This feature hub defines the normative contract for **syntax domain model generation** and links detailed articles.

## Language alignment
`Collector` contracts depend on immutable syntax snapshots and **stable node identities** produced here. `Generator` and `Rewriter` must not retain stale references across invalidation rounds.

## Implementation anchors
- `compiler/crates/beskid_analysis/src/syntax/` — syntax item builders and node shapes.
- `compiler/crates/beskid_analysis/src/beskid.pest` — grammar surface feeding parse output.
- `compiler/crates/beskid_analysis/src/syntax/items/` — item-level parsers and metadata.

## Decisions
<!-- spec:generate:adr-index -->
No open decisions. Closed choices are normative ADRs under **`adr/`** (`D-COMP-MODS-0013` … `D-COMP-MODS-0015`); use the reader **ADRs** tab for expandable detail.
<!-- /spec:generate:adr-index -->
## Articles
<!-- spec:generate:article-index -->
- [Syntax domain model generation - Contracts and edge cases](./articles/contracts-and-edge-cases/)
- [Syntax domain model generation - Design model](./articles/design-model/)
- [Syntax domain model generation - Examples](./articles/examples/)
- [Syntax domain model generation - FAQ and troubleshooting](./articles/faq-and-troubleshooting/)
- [Syntax domain model generation - Flow and algorithm](./articles/flow-and-algorithm/)
- [Syntax domain model generation - 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/compiler-mods/syntax-domain-model-generation/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/syntax/`
- `compiler/crates/beskid_analysis/src/beskid.pest`
- `compiler/crates/beskid_analysis/src/syntax/items/`

## Context

Hand-maintained parallel syntax trees diverged from the host parser.

## Decision

Canonical syntax model is generated via `beskid_ast_reflect_gen` into `Beskid.Compiler.*` SDK sources from the Rust AST—aligned with D-INC-0006.

## Consequences

Mods consume generated facades; internal `beskid_analysis::syntax` remains host-only.

## Verification anchors

- `beskid_ast_reflect_gen`
- `compiler/crates/beskid_analysis/src/syntax/`.

This article states **contracts and edge cases** for **Syntax domain model generation**.

## Hard requirements
- **Deterministic ordering** — discovery and execution order must be reproducible from equal inputs (path-normalized roots, sorted files, stable tie-breaks).
- **Bounded work** — host enforces step limits, allocation caps, and recursion depth across nested meta calls.
- **Versioned facades** — `Beskid.Compiler` surface is tied to compiler language version tokens exposed on the compilation instance.

## Edge cases
- **Partial programs** — facades must tolerate incomplete syntax where the language permits; diagnostics are preferred over host panics.
- **Conflicting edits** — multiple meta contributors touching the same declaration identity produce a deterministic merge failure surfaced as structured diagnostics.

This article documents the **design model** for **SyntaxMirror domain model generation**.

## Language alignment

`Collector` predicates compile to keys over syntax identities from this model. The host regenerates or diffs snapshots so `Generator` and `Rewriter` never observe torn trees.

## Persistent entities

- **Compilation instance** — active host compilation under transformation.
- **Syntax snapshot** — immutable tree with stable node identities for incremental keys.
- **SyntaxMirror projection** — Beskid-facing typed mirror of syntax nodes with query/AST operation contracts.

## Boundaries

- Rust AST in `beskid_analysis` is authoritative; SyntaxMirror is generated/mirrored for mod packages.
- Legacy `MetaDefinition` nodes are removed from the mirror inventory.
- The Rust inner item enum (`syntax::Node`) is **host-only** and is **not** emitted into the Mod SDK. Mod packages see **`Node` contract** + **`NodeRef`** instead.

## Generated artifacts

`beskid_ast_reflect_gen` emits, under `Beskid.Syntax.Nodes`:

| Artifact | Role |
| --- | --- |
| Per-type shape `.bd` | Struct/enum mirrors for typed emit and rewrite (`FunctionDefinition`, …) |
| **`Node.bd`** | `pub contract Node` — kind, ref, child push |
| **`NodeRef.bd`** | Opaque stable handle |
| **`NodeSpan.bd`** | Span DTO for one node in one generation |
| **`NodeKind.bd`** | Classification tokens (mirrors `query::NodeKind`) |
| **`NodeList.bd`** | `Vec<Node>` as cons-list of **`NodeRef`** |
| **`TraversalManifest.bd`** | Child-slot table derived from Rust `#[ast(child\|children\|skip)]` |

Traversal metadata **must** stay aligned with `beskid_ast_derive::AstNode` wiring in `beskid_analysis`.

## Stable identities

Each node **must** have a stable identity within a `syntax_generation_id` window. Identities **must** survive trivia-only edits where language law marks them stable and **must** change on structural edits that affect collection predicates.

**Torn tree prohibition** — Hosts **must not** expose partial syntax trees to mod contracts. Parse failures abort the current generation round with diagnostics, leaving the previous committed generation untouched.

**Multi-root workspaces** — Identities **must** be qualified by normalized root path + in-root span so different projects cannot collide in caches.

## Transformation model

- Query-pipeline transforms run against one immutable `SyntaxSnapshot` generation and produce one new committed generation on success.
- Pipeline application **must** be transactional: validation completes before any mutation becomes visible to mod code.
- Span propagation is explicit:
  - untouched nodes preserve original spans;
  - replaced nodes receive source spans from replacement payloads when available;
  - synthetic nodes may use host-synthetic spans but must remain diagnosable.

This article collects **examples** for **Syntax domain model generation** (informative sketches aligned with contracts).

## Example A — Minimal query
A compile-time module reads a syntax attribute using the query API, then emits a diagnostic without mutating syntax.

## Example B — Emitter sketch
A contributor constructs a new method declaration through `Beskid.Compiler.Emit`, attaches trivia, and registers it with the incremental graph.

> Executable snippets will track the reference implementation as mod host execution lands in the compiler; until then, treat these as specification fixtures.

This article collects **FAQ** entries for **Syntax domain model generation**.

## Why separate language-meta and compiler pages?
Language-meta defines Beskid-side mod contracts; this compiler area defines how the Rust host executes them safely and incrementally.

## Can meta call arbitrary FFI?
No — unless explicitly granted by platform policy and declared in compilation capabilities. Default contracts deny ambient FFI.

## Where do Roslyn/KSP parallels apply?
Only as rationale for incremental caches and typed models; Beskid contracts are authoritative here, not foreign tool behavior.

This article documents **flow and algorithms** for **Syntax domain model generation**.

## Primary flow
1. Materialize or refresh the syntax snapshot for the active compilation generation.
2. Classify meta contributors vs read-only inspectors (language-meta classification carries through here).
3. Execute host policy checks before surfacing Mod SDK calls.
4. Commit outputs atomically per scheduling round (see incremental scheduling feature).

## Ordering constraints
- No meta body runs before a parseable syntax model exists for its lexical scope.
- Semantic queries that depend on staged rules must declare the minimal snapshot version they require; the host may defer or rerun automatically.

This article documents **verification and traceability** for **Syntax domain model generation**.

## Traceability matrix
- Anchor: `compiler/crates/beskid_analysis/src/syntax/` — syntax item builders and node shapes.
- Anchor: `compiler/crates/beskid_analysis/src/beskid.pest` — grammar surface feeding parse output.
- Anchor: `compiler/crates/beskid_analysis/src/syntax/items/` — item-level parsers and metadata.

## Verification expectations
- Contract tests in `compiler/crates/beskid_tests` assert ordering, diagnostic codes, and merge behavior once implemented.
- Golden incremental traces (optional) validate invalidation when syntax edits move spans tied to meta registrations.

## Review cadence
- Update this bundle whenever public `Beskid.Compiler.*` shapes or host policies change.