Build FSharp2: a NativeAOT, incremental, drop-in F# compiler

Destination

FSharp2 replaces the compiler target for .NET 10 F# projects with an independently authored compiler that parses, typechecks, optimizes, and emits behaviorally compatible DLL/PDB artifacts. The compiler host and its output pass NativeAOT gates, IcedTasks is the first real-world vertical milestone, Cold Compilation stays at or below the three-second Performance Tripwire in normal projects, and Warm Compilation is sub-second.

Notes

• This map carries the effort through implementation, not only planning. Decision tickets should clear uncertainty before tracer-bullet implementation tickets are added.
• Read CONTEXT.md and applicable ADRs under .agents/docs/adr/ before working a ticket; their vocabulary and decisions are binding.
• The official .NET 10 compiler is the Compatibility Oracle and test infrastructure only. Production fallback to it or to FSharp.Compiler.Service is forbidden.
• Use research, prototype, tdd, implement, dotnet-inspect, and code-review skills where their trigger conditions apply.
• IcedTasks (TheAngryByrd/IcedTasks) is the first real-world baseline. Measure Compiler Target Invocations, not unrelated MSBuild or restore work.
• Never resolve more than one Wayfinder ticket per session.

Decisions so far

• Inventory the .NET 10 F# compiler and MSBuild contract — The compatibility boundary is the observable .NET 10 MSBuild compiler-target contract; every declared envelope must traverse it end to end while preserving invariant target semantics.

• Measure the official compiler target on IcedTasks — The first real-world baseline is a pinned IcedTasks tree and Compatibility Oracle with per-TFM physical inputs, outputs, and 15-sample compiler-target timings; Cold Compilation and unchanged target skipping remain distinct evidence classes.

• Establish the NativeAOT constraints for the compiler host — FSharp2 uses a closed NativeAOT production graph, metadata-only target references, strict publish gates, a proved FSharp.Core subset, eight build-host RID payloads, and separate native-host and emitted-output NativeAOT matrices.

• Define the differential compatibility and performance harness — The versioned harness uses isolated Oracle/FSharp2 lanes, four explicit verdicts, comparator-specific semantics, no-fallback proof, separate NativeAOT gates, and valid Cold/Warm Compiler Target Invocation measurements.

• Select the first IcedTasks vertical slice — The first milestone is the full pinned 17-file library across four producer TFMs, with unchanged Oracle-built test drivers, harness-owned family and interoperability probes, exact initial diagnostics, fail-closed no fallback, and controlled cold/warm gates.

• Select the metadata, IL, and PDB emitter architecture — FSharp2 owns versioned, immutable symbolic declaration and method fragments and uses a fresh deterministic public-SRM linker as the correctness baseline; #8 and #12 retain representative throughput proof, and the final encoder stays replaceable behind that boundary.

• Decide whether the harness needs an independent F# metadata decoder — The harness adds an independently authored SRM/Deflate envelope inspector for exact F# resource structure; four-way Oracle/FSharp2 consumption remains semantic authority, private-pickle decoding stays diagnostic-only, and production importer/fingerprint schemas stay separate.

• Choose the cross-platform debugger automation driver — Use pinned DAP with netcoredbg as the first redistributable candidate behind a fail-closed per-cell conformance gate; the locked Windows x64 focused smoke passes, while full corpus, attach, both-producer, and missing-platform coverage remain mandatory.

• Define the warm-edit corpus and cache-evidence contract — Warm Compilation uses exact implementation-only and public-inline IcedTasks edits on one retained service lineage, with cache-layout-independent per-node evidence and reconciled reuse, invalidation, and actual-work counters; family-wide FSxxxx compatibility remains a final gate.

• Define compiler performance runner and regression governance — perf-governance-v1 uses characterized dedicated runners, fixed balanced samples, exact rational and paired-bootstrap statistics, fail-closed state/evidence controls, and governed raw/shareable traces; hosted CI remains correctness smoke.

• Choose the type-provider compatibility boundary — Final legacy-provider compatibility uses an optional managed Provider Broker outside the NativeAOT compiler; provider inputs remain unsupported until their declared broker gate passes, and cache, diagnostic, and performance behavior stays Oracle- and evidence-driven.

• Establish Linux runtime and deployment compatibility floors — FSharp2 ships separate glibc and musl x64/Arm64 hosts: GLIBC_2.27 with native RHEL 8 floor execution and a musl 1.2.3 sysroot with native Alpine 3.21 floor execution, under exact loader, closed native-dependency, real-hardware, persistent-service/cache, and separate host/output NativeAOT gates.

• Define localization, signing, and native-resource compatibility policy — Full-globalization hosts preserve neutral English plus every oracle satellite culture; the final gate is family-wide across every reachable FSxxxx diagnostic, all key-file signing modes, and the complete Win32 resource surface, with strict key redaction, deterministic link boundaries, and independent NativeAOT host/output gates.

• Define secure harness evidence retention and redaction — evidence-governance-v1 keeps raw source-bearing evidence encrypted in a restricted store, reconstructs shareable evidence from a closed allowlist, bounds full-sign secret evidence to one declassified aggregate outcome on disposable workers, and reconciles access, copies, retention, and deletion.

• Define the corpus-neutral compiler request, result, and phase contracts — Compiler Core v1 now accepts immutable source, reference, semantic-option, and artifact snapshots through one corpus-neutral Compiler.Compile boundary, with versioned phases, cancelable value transport, transactional publication, and strict NativeAOT validation.

Not yet specified

• Lexer, parser, name-resolution, inference, constraint-solving, and diagnostic architecture beyond the first supported vertical slice.
• Typed and lowered intermediate representations, optimization passes, and closure/state-machine lowering beyond the selected symbolic emission-fragment boundary.
• Compiler-service protocol, process ownership, concurrency, cache storage/eviction, and stale-daemon recovery.
• Compatibility expansion from IcedTasks to the full .NET 10 language-version, diagnostics, and compiler-option matrix.
• RID packaging, supply-chain verification, cache security, and remaining release engineering across Windows, Linux, and macOS on x64 and ARM64.

Out of scope

• Reproducing the public FSharp.Compiler.Service API and type identities.
• F# Interactive, REPL behavior, .fsx execution, and script dependency resolution.
• Byte-for-byte reproduction of official compiler artifacts where behavior does not require it.

Start with CONTEXT.md and the applicable ADRs under .agents/docs/adr/, then read the closed decision tickets linked in this issue, especially #2-#7 and #25. The issue defines broad compatibility, NativeAOT, IcedTasks, and performance goals but names no implementation entry point, file, test, or bounded first task, so completion cannot be determined from it alone.