NativeAOT-compatible incremental F# editor-analysis engine

Destination

A platform-agnostic, NativeAOT-compatible, stateful incremental F# Project Mode analysis engine that consumes immutable Project Snapshots and provides diagnostics, hover/type information, definition/declaration navigation, and completion faster than FCS on a representative correctness corpus.

The first deliverable is a standalone library and differential benchmark harness; MrBuild F# Worker integration follows only after the engine's semantics and performance are demonstrated.

Notes

• This map covers a new analysis engine, not an AOT wrapper around FCS.
• Preserve NativeAOT compatibility from the beginning: avoid runtime assumptions that prevent NativeAOT publication.
• Use the repository vocabulary in CONTEXT.md: Project Snapshot, Active Target, Document Authority, F# Source Order, F# Project Mode, and F# Latest-Input-Wins.
• Keep the managed design platform agnostic; do not make the first proof Windows-specific.
• Consult CONTEXT.md and .agents/docs/adr/ before resolving tickets. Use domain modeling when terms or architectural decisions become durable.
• The initial comparison corpus includes MrBuild F# projects, the existing FsToolkit.ErrorHandling proof corpus, and focused fixtures for signatures, project references, generics, computation expressions, patterns, and incomplete code.

Decisions so far

• Measure the FCS baseline for Project Mode editor workloads — direct FCS measurements show a small-project cold project check at about 145 ms and 78,184 KB allocated, versus about 115 us for a warm document edit; the report separates direct FCS costs from full editor-boundary latency.
• Characterize NativeAOT constraints for the analysis-engine design — use a NativeAOT-analyzable managed engine core with no runtime code generation, unconstrained reflection, dynamic loading, or reflection-based serialization; keep FCS/MSBuild/LSP/transport dependencies in adapters and defer a C ABI to a separate export layer.
• Define the initial incremental analysis contract and public API — the host owns authoritative documents, Project Snapshots, Active Target selection, failed-evaluation policy, transport, serialization, and final publication; the engine owns derived analysis state. Inputs commit independently, requests/results carry a Workspace Revision, immutable results expose separate Freshness and Availability, concurrent work uses latest-input-wins revision matching, and unsupported constructs are explicit.

Not yet specified

• Which parsing, syntax-tree, symbol, and type-representation strategy can meet the incremental-editor constraints.
• How much F# language coverage is required for the initial corpus and how unsupported constructs are represented in the differential contract.
• Exact immutable DTO shapes for diagnostics, hover, navigation, and completion, plus the differential-correctness contract against FCS.
• Measure Coordinator-boundary F# editor latency — process startup, snapshot reload, LSP edit latency, dependent refresh, and stale-result counters.
• The JIT-versus-NativeAOT performance comparison and final latency/allocation gates.
• The point at which the engine is strong enough to replace the F# Worker's FCS path.

Out of scope

• F# Script Mode, standalone script restore, and initial .fsx support.
• Simultaneous multi-target analysis; the first milestone uses one extensible Active Target per project.
• MSBuild evaluation inside the engine; Project Worker Design-Time Evaluation remains authoritative.
• C# analysis, MSBuild Document Intelligence, and full IDE feature parity.
• A claim of full FCS compatibility before the supported corpus and semantic contract are established.

Start with CONTEXT.md and .agents/docs/adr/ to learn the project vocabulary and architectural decisions. Review issues 20, 21, and 22, then inspect the comparison corpus named in the issue, including MrBuild F# projects and focused language fixtures. Done means a standalone NativeAOT-compatible library and differential benchmark harness demonstrate the agreed semantics and performance, but the exact contract and gates still need definition.