This feature hub defines the normative contract for **`Beskid.Compiler.Emit`** (typed emitter and transforms) and links detailed articles.

## Language alignment
Only the **`emit`** phase may apply **typed** program contributions through this surface; the host validates merge against language rules.

## Implementation anchors
- `compiler/crates/beskid_analysis/src/syntax/items/` — patterns for well-formed item emission.
- `compiler/crates/beskid_codegen/` — downstream expectations after merge.

## Decisions
<!-- spec:generate:adr-index -->
No open decisions. Closed choices are normative ADRs under **`adr/`** (`D-COMP-MODS-0016` … `D-COMP-MODS-0018`); use the reader **ADRs** tab for expandable detail.
<!-- /spec:generate:adr-index -->
## Articles
<!-- spec:generate:article-index -->
- [Typed emitter and transforms - Contracts and edge cases](./articles/contracts-and-edge-cases/)
- [Typed emitter and transforms - Design model](./articles/design-model/)
- [Typed emitter and transforms - Examples](./articles/examples/)
- [Typed emitter and transforms - FAQ and troubleshooting](./articles/faq-and-troubleshooting/)
- [Typed emitter and transforms - Flow and algorithm](./articles/flow-and-algorithm/)
- [Typed emitter and transforms - 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/typed-emitter-and-transforms/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/items/`
- `compiler/crates/beskid_codegen/`

## Context

This feature hub defines the normative contract for **`Beskid.Compiler.Emit`** (typed emitter and transforms) and links detailed articles.

## Decision

The reference compiler **must** implement Typed emitter and transforms 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/src/syntax/items/`
- `compiler/crates/beskid_codegen/`

This article states **contracts and edge cases** for **Typed emitter and transforms**.

## 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 **Typed emitter and transforms**.

## Language alignment
**Emit** applies only **typed** edits; language-meta forbids raw-text patching as the normative contract.

## Persistent entities
- **Compilation instance** — implicit handle to the compilation under construction (**[Compiler Mod SDK](/platform-spec/language-meta/metaprogramming/compiler-mod-sdk/)** / `Beskid.Compiler.Compilation`).
- **Syntax snapshot** — immutable tree with stable node identities suitable for incremental keys.
- **Capability tokens** — host-granted permissions for I/O, diagnostics, and emit operations during mod execution.

## Boundaries
- Mod SDK facades never bypass the host bridge for effects.
- Generation logic in the reference compiler remains Rust-internal; Beskid sees only the generated `Beskid.Compiler.*` projection.

## Anchored code paths
- `compiler/crates/beskid_analysis/src/syntax/items/` — patterns for well-formed item emission.
- `compiler/crates/beskid_codegen/` — downstream expectations after merge.

## Merge model (surface syntax first)

Typed emit **must** construct or mutate **`Program`**-level syntax nodes (or a documented multi-file aggregate feeding the same parser contract), not ad hoc HIR patches. Contributions **must** pass the same well-formedness checks as user-authored items before merge.

**Ordering** — Multiple contributors touching the same **declaration identity** produce a deterministic merge failure surfaced as structured diagnostics; the host **must not** leave a partially merged tree.

**Handoff to lowering** — After typed emit commits at **`syntax.generation`** and the host emits **`lower.ready`**, the merged syntax **must** be the sole input to `lower_normalize_resolve_type_spanned` / codegen lowering paths documented in **[Stage ordering and lowering](/platform-spec/compiler/build-pipeline/stage-ordering/)**; lowering **must not** begin until emit validation succeeds or emit is skipped for that generation round.

This article collects **examples** for **Typed emitter and transforms** (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 **Typed emitter and transforms**.

## 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 **Typed emitter and transforms**.

## 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 **Typed emitter and transforms**.

## Traceability matrix
- Anchor: `compiler/crates/beskid_analysis/src/syntax/items/` — patterns for well-formed item emission.
- Anchor: `compiler/crates/beskid_codegen/` — downstream expectations after merge.

## Verification expectations

- **Merge conflicts** — Tests assert two generator contributors targeting the same declaration identity emit deterministic **E1836–E1850** diagnostics and leave the syntax tree unchanged (see **[Diagnostic code registry](/platform-spec/compiler/semantic-pipeline/diagnostic-code-registry/)**).
- **Lowering guard** — Tests ensure `lower.ready` (or equivalent sequencing) never fires between partial emit and rollback.
- **Golden traces (optional)** — Same as **[Incremental scheduling / verification](/platform-spec/compiler/compiler-mods/incremental-scheduling-determinism/verification-and-traceability/)** when emit drives invalidation.

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