# src/compiler/ — Package Compilation Pipeline
Compiles resolved packages into target state. 11 submodules, ~2100 lines in compiler
core (`mod.rs`, `native_agents.rs`) plus per-lane modules (agents, skills, config
entries, hooks, MCP, variants, visibility).
## Mental Model
```
ReaderIr (source-level facts)
↓
build_target() ← assign dest paths, handle collisions, rewrite frontmatter refs
↓
create_plan() ← diff + plan
↓
apply_plan() ← persist config, write to .mars/ canonical store
↓
dual_surface_compile() ← emit native harness artifacts (.claude/agents/, etc.)
config_entries_compile() ← MCP servers, hooks
↓
sync_targets() ← copy to managed target directories
↓
finalize() ← write lock, build report
```
The compiler is the second half of the sync pipeline. It consumes `ReaderIr` and produces `SyncReport`.
## Module Map
- `mod.rs` (304 lines) — orchestration: `compile()` entry point, stages, lock finalization
- `native_agents.rs` (814 lines) — native harness surface lifecycle: scan, reconcile, compile,
emit, link-materialize. Extracted from `mod.rs` (was 1522 lines).
- `agent_copy.rs` — selective emission when `settings.agent_copy` is configured;
`agent_qualifies_for_harness()`, `model_resolves_to_harness()`, `QualifiedEmission` enum
- `agents/` — `AgentProfile` schema parser + per-harness lowering with model alias resolution
- `skills/` — universal skill schema + native lowering with variant layouts
- `config_entries/` — MCP servers and hooks from packages → target config files
- `mcp/` — MCP server item discovery, env-ref validation, collision detection
- `hooks/` — hook item discovery, event validation, ordering, lossiness classification
- `variants/` — skill variant layout validation, indexing, projection
- `visibility/` — D1/D10 propagation rules
## Dual-Surface Compilation
Under `EmitAll` policy (standalone mars), harness-bound agents are compiled to both:
1. `.mars/agents/` — canonical universal format
2. `<target>/agents/` — harness-native format (e.g., `.claude/agents/coder.md`)
Under `SuppressAll` (Meridian-managed), native artifacts are removed.
### Model Alias Resolution at Compile Time
When lowering a universal agent profile to a native harness format, model aliases like
`opus46` are resolved to pinned model IDs (e.g., `claude-opus-4-6`) at compile time.
This is necessary because native harnesses (Claude Code, Codex) don't understand the
alias system. Resolution happens in `native_model_override_for_harness()` in
`native_agents.rs` — it consults the merged alias registry and supplies a
`model_override` to the lowerer. `AutoResolve` tokens (containing `[`) and unpinned
aliases pass through verbatim with a warning.
### Agent Surface Policy
| unset (auto) | false | EmitAll |
| unset (auto) | true | SuppressAll |
| always | any | EmitAll |
| never | any | SuppressAll |
## Agent Compilation (`agents/`)
- `mod.rs` — schema parser, `AgentProfile` from YAML frontmatter + markdown body
- `lower.rs` — per-harness lowering with lossiness tracking. All lowerers accept an
optional `model_override: Option<&str>` parameter. `lower_for_harness_with_model()`
dispatches to the correct lowerer with the resolved model override, ensuring
emitted native artifacts carry pinned model IDs rather than aliases.
- `HarnessKind` — Claude, Codex, OpenCode, Cursor, Pi
### Non-Overridable Fields
These fields cannot appear inside `harness-overrides` blocks: `name`, `description`, `model`, `harness`, `mode`, `model-invocable`, `model-overrides`, `harness-overrides`.
## Skill Compilation (`skills/`)
Universal schema parsing and native lowering. Skills support variant layouts per harness target.
## Config Entries (`config_entries/`)
MCP servers and hooks discovered from packages, validated, and written to target config files via adapters.
## MCP Compilation (`mcp/`)
Discovers MCP server items, validates env refs, detects collisions.
## Hooks Compilation (`hooks/`)
Discovers hook items, validates events, orders bindings, classifies lossiness.
## Variants (`variants/`)
Skill variant layout validation, indexing, and projection per harness target.
## Visibility (`visibility/`)
Propagation rules for passive vs effectful items (D1/D10).
## Patterns
**Test dual-surface:**
```rust
let policy = agent_surface_policy(None, false); // standalone → EmitAll
reconcile_native_agent_surfaces(policy, project_root, mars_dir, &outcomes, false, &mut diag);
```
**Test suppression:**
```rust
let policy = agent_surface_policy(Some(&AgentEmission::Auto), true); // meridian → SuppressAll
```
## Linked-target writes
Native reconcile and dual-surface compile gate deletes and copies through `surface_ownership` (same rules as `target_sync`). See `src/target_sync/.context/CONTEXT.md`.
## See Also
- `src/sync/AGENTS.md` — orchestrates the compiler
- `src/target/AGENTS.md` — per-target adapters the compiler uses
- `src/target_sync/.context/CONTEXT.md` — per-target lock ownership and collision semantics
- `src/compiler/agents/mod.rs` — AgentProfile schema details