F# hot reload: Edit-and-Continue delta emission behind --enable:hotreloaddeltas

[NatElkins]

This draft PR presents the complete F# hot reload implementation as a single branch against current main: dotnet watch (with a companion dotnet-watch change, linked below) patches running F# processes in place via the standard EnC pipeline (MetadataUpdater.ApplyUpdate) — the same runtime contract C# uses. Unsupported edits degrade to the rebuild-and-restart flow watch uses today, so a limited scope still behaves as a complete feature.

It is opened as a single draft per discussion with @T-Gro: one branch to review, build, and launch testing from. A decomposition into independently shippable PRs is laid out below and can begin whenever review reaches that stage. Earlier discussion: #11636.

Try it (30–45 min, two clones, copy-paste steps)

docs/hot-reload-quickstart.md walks from git clone to editing a running F# app — including adding a List.map (fun s -> s.ToUpper()) to a live method and watching it apply in place, state preserved. Short version: build this branch, build NatElkins/sdk fsharp-hotreload-watch-v2 (a complete .NET CLI with an F#-aware dotnet watch), copy the freshly built FSharp.Compiler.Service.dll into the SDK layout, add <OtherFlags>$(OtherFlags) --enable:hotreloaddeltas</OtherFlags> to a console app, and dotnet watch run.

What works

• Method body edits, including bodies containing closures, async, resume-point-stable task, and generics
• Lambdas added / edited / removed across generations (new closure classes synthesized into the running process)
• Member additions: methods, module functions and values, static/instance fields, properties, [<CLIEvent>] events
• New type definitions: classes, records, unions, structs, modules, enums, interfaces, delegates, units of measure
• Attribute add/change/remove on existing members; parameter renames
• Multi-project: one watch session, per-project baselines, interleaved edits across an app and its referenced libraries
• Line-shift edits (comment/whitespace above code) become pure sequence-point line updates — no delta, no restart
• Rude edits (same set as C#: signature changes, captured-variable rename/type/scope changes, mid-sequence await insertion, plus F#-specific inline/SRTP) degrade to the standard rebuild-and-restart flow with a precise diagnostic

Isolation and disabling

The feature is designed so that a compile without the flag is indistinguishable from main, and so that the whole feature can be turned off at one point if something goes wrong:

• Off by default. Everything is behind --enable:hotreloaddeltas (requires --debug+, incompatible with --optimize+). No MSBuild property or SDK behavior changes in this repo.
• Flag-off output is byte-identical to main, pinned by the EmittedIL suite (1212 baseline tests) and by dedicated determinism tests (DLL+PDB byte-equality across recompiles and across graph/sequential checking modes).
• Flag-off cost is zero beyond cheap checks. A dedicated audit pass removed all unconditional work from the flag-off path: no reflection, no eager metadata snapshots, no per-name or per-closure side-channel probes, no extended lifetime of the optimized typed tree, and FSharpProjectSnapshot.fs is byte-identical to main (tracked-input staleness lives in the hot reload session layer instead).
• One seam. The compiler driver integration is a single ICompilerEmitHook interface with a no-op default. Guard scripts under tests/scripts/ (run by the verification gate) enforce that only the intended files consume the hook and that the IlxGen name-generation path and fsi surface stay on their pinned shapes.
• Disabling: drop the flag (compiler side); the companion dotnet-watch side additionally has a one-variable kill switch (DOTNET_WATCH_FSHARP_HOTRELOAD=0) that restores stock restart-on-edit behavior.

Architecture

• Sessions are an explicit entity: FSharpChecker.CreateHotReloadSession returns a FSharpHotReloadSession holding per-project committed snapshots + emit baselines — the DebuggingSession/CommittedSolution shape from Roslyn, built on FSharpProjectSnapshot (the snapshot contract, not the experimental workspace surface), so it composes with the FSharpWorkspace direction without depending on it. Solution-wide commit/discard semantics, runtime-capability updates, active-statement intake.
• A typed-tree semantic diff classifies every edit (Roslyn's SemanticEdit/RudeEdit model), gated on the runtime's advertised EnC capabilities (AddMethodToExistingType, NewTypeDefinition, GenericUpdateMethod, …). Anything unclassifiable fails closed.
• Delta emission produces the standard EnC triplet (metadata/IL/PDB deltas with EncLog/EncMap), validated against recorded Roslyn EmitDifference reference deltas, with mdv, and against CoreCLR ApplyUpdate in runtime tests.
• Closure identity is solved the way Roslyn solves it, adapted to F#'s lowering: lambdas get stable identity from a typed-tree occurrence model (ordinal chains + LCS alignment rather than syntax offsets), persisted in Roslyn's exact portable-PDB EnC CDI blob formats (the encoder round-trips Roslyn's own blobs byte-identically), with deterministic occurrence-derived closure-class names so any process can reconstruct identity from the PDB alone.

Design documentation (rendered, on this branch)

Doc	What it covers
hot-reload-architecture.md	Start here. The entity model: FSharpHotReloadSession, per-project committed snapshots + baselines on FSharpProjectSnapshot, the FSharpWorkspace relationship, determinism pins
hot-reload-closure-mapping.md	The closure problem and its solution: lambda occurrence model, Roslyn-format EnC CDI PDB blobs, occurrence-derived deterministic closure naming, cross-process reconstruction; state-machine handling
hot-reload-member-additions.md	Recorded Roslyn EmitDifference reference templates (EncLog/EncMap shapes per edit kind) and the F# emission matrix incl. every intentional fail-closed case
hot-reload-capabilities.md	Runtime capability negotiation (Roslyn EditAndContinueCapabilities parity) and per-capability gating
hot-reload-active-statements.md	The debugger-contract mirror: active statements, sequence-point updates, remapping; host wiring deferred

Scale and review shape

~85 commits, 154 files, ~60k insertions, of which ~34k are tests and ~2.4k docs. The src/ changes are predominantly new self-contained modules (IlxDeltaEmitter.fs, TypedTreeDiff.fs, HotReloadBaseline.fs, the AbstractIL EnC readers, the delta writer stack). Pre-existing files carry hook callouts plus one behavior-neutral refactor (ilwrite.fs MetadataTable record→class with an IEncLogWriter seam); total deletions across the branch are 394 lines.

Proposed path to merging in pieces

The fail-closed design means scope can grow capability by capability — each unsupported case is already a rude edit with a diagnostic, so every intermediate state is a complete, working feature. The natural sequence:

1. Behavior-neutral AbstractIL/ilwrite foundations (no feature, byte-identity evidence) — already staged separately as a 3-commit branch (refactor: AbstractIL EnC foundations (hot reload stack 1/n) NatElkins/fsharp#2)
2. Session entity + typed-tree classification, with every edit classified rude — end-to-end complete at minimal scope (watch restarts on every edit, but through the proper pipeline). This is the PR where the architecture gets decided with reviewers.
3. Method-body-only deltas (the core)
4. Closure mapping + deterministic naming (the one chunk that touches IlxGen/name-generation paths — reviewed on its own)
5. Member/field/type additions, generics, state machines — each already individually capability-gated
6. Active statements / sequence-point updates

Evidence

• ~630 hot-reload tests: typed-tree classification, writer/EncLog shapes asserted against the recorded C# templates, mdv metadata validation, real ApplyUpdate + invocation, multi-generation chains, cross-process (disk-started) sessions
• EmittedIL byte-neutrality: 1212 emitted-IL baseline tests pass with the flag off
• Determinism: baseline capture pins deterministic sequential codegen; DLL+PDB byte-equal across recompiles and across graph/sequential checking modes (pinned by tests). Context: F# compiler produces non-deterministic metadata #Strings heap layout #19732, Determinism: closure type names differ between --parallelcompilation- and --parallelcompilation+ #19928 (open; flag-on compiles are insulated), $(ParallelCompilation) never reaches the Fsc task — targets pass the item @(ParallelCompilation) instead of the property #19935 (why the pin is compiler-level)
• dotnet-watch e2e (companion branch): in-place applies, multi-project interleaved edits, no-op detection, dependency-file handling, rude-edit restart — all green
• Single-command verification gate: ./tests/scripts/hot-reload-verify.sh

Known limitations / future work

• Per-edit apply is ~2–3s; the bulk is an FCS recheck that composes naturally with WIP : Experiment [this repo only] : Fast and unsafe development time compilation out of FSharpChecker caches #19267 (Fast Build from Cache) — the intent is to converge with that work, not duplicate it
• Debugger (VS) host wiring for active statements is deferred; the compiler-side contract mirror is in place
• The remaining intentional rude edits are documented per case in the design docs above

Companion PRs

• refactor: AbstractIL EnC foundations (hot reload stack 1/n) NatElkins/fsharp#2 — stack 1/n: the behavior-neutral AbstractIL/ilwrite foundations
• NatElkins/sdk#1 — the dotnet-watch integration

[github-actions]

❗ Release notes required

You can open this PR in browser to add release notes: open in github.dev

---

✅ Found changes and release notes in following paths:

Warning

No PR link found in some release notes, please consider adding it.

Change path	Release notes path	Description
src/Compiler	docs/release-notes/.FSharp.Compiler.Service/11.0.100.md	No current pull request URL (#19941) found, please consider adding it

[xperiandri]

Looks like it requires rebase/conficts fix

[T-Gro]

This only pins the capture compile. The replay compile (--enable:hotreloadhook) still runs IlxGen in parallel, and GetOrAddName hands names out in call order, so the replayed names can come out in a different order than the sequential baseline and the delta points at the wrong tokens. No crash, just a silently wrong delta. Pin both:

Suggested change

	if tcConfigB.emitCaptureArtifacts then
	if tcConfigB.compilerEmitHook.IsSome then

compilerEmitHook is Some for capture and hook, None otherwise, so the normal path is untouched.

[T-Gro]

resolvedHolder is a two-field ValueOption, shared by all three generators (one accessor at CompilerGlobalState.fs:70) and read from parallel IlxGen threads with no sync. A torn read can see the tag as ValueSome while the ref is still null, then NRE on .TryGet(). This is on the normal compile path, not just hot reload. volatile won't help a multi-field struct, so resolve it once up front:

let getCompilerGeneratedNameMapAccessor (owner: obj) : unit -> ICompilerGeneratedNameMap option =
    let holder = getHolder owner
    fun () -> holder.TryGet()

[T-Gro]

While here: getHolder uses holders.GetValue(...), which inserts/allocates a NameMapHolder even when nothing was installed — the sibling ClosureNameAllocationState.tryGetHolder uses TryGetValue to avoid exactly that. Reading through TryGetValue (insert only on setCompilerGeneratedNameMap) also lets the accessor drop the cached resolvedHolder entirely, fixing this and the torn read above in one go.

[T-Gro]

encodeCompressedUnsigned is unused, so FS1182, and that's warn-as-error here, so ./build.sh -c Debug fails on it. Same for rowElementGuid / addStringOption / addGuidValue below, and tryGetOutputPathFromProjectOptions in service.fs:921. CI is red on these plus the FS3261 nullness warnings and fantomas.

[T-Gro]

Two metadata writers here: this hand-written one, and the SRM one behind FSHARP_HOTRELOAD_USE_SRM_TABLES (off by default). The SRM path builds from a bare MetadataBuilder() (DeltaMetadataSrmWriter.fs:146) with no baseline heap offsets, so it'd be wrong for any delta that grows a heap, and the parity check skips heap layout so it won't catch that. I'd pick one: finish SRM (heap continuation, real parity, gen2/gen3 tests) and drop the ~1.9k LOC hand-written writer, or drop the SRM shadow.

[T-Gro]

The rule that every generated name goes through the hot-reload wrappers is only checked by tests/scripts/check-ilxgen-name-path.sh, and nothing in CI runs it. If these generators were private and the only way to get a name was a wrapper member (freshIlxName / freshCoreName already exist in IlxGen.fs:52), the compiler would enforce it instead of a grep.

[T-Gro]

Small thing: the files under Generated/ are hand-written, but the folder name reads like codegen output. They'd fit better next to CompilerGlobalState in TypedTree/.

[T-Gro]

Public, but not [<Experimental>] like the session API in service.fsi. The feature is still experimental, so this locks in as-is. Mark it experimental or keep it internal.

[T-Gro]

Latent, and FCS-only (fsc.exe is one project per process, so it can't hit this). currentEmissionContext is one process-wide mutable, set only in FSharpChecker.Compile and read only in the emit hook's driver phases; the primary EmitDelta path doesn't use it. To clash you'd need a host calling FSharpChecker.Compile concurrently for two projects of one session, which I don't think happens today. If it's worth scoping, AsyncLocal is the small option (like buildPhase/diagnosticsLogger), but F# async doesn't flow ExecutionContext exactly like C# await, so I'd confirm with a concurrent-compile test rather than assume. Or thread it through the per-compile tcConfig.compilerEmitHook and skip the question.

[T-Gro]

Nothing checks that the replay compile pins sequential codegen (the wrong-delta thing in fsc.fs:537). If that fix pulls the pin into a small applyHotReloadDeterminismPins, this is a cheap guard, red today and green after:

[<Fact>]
let ``hotreloadhook pins sequential codegen`` () =
    let b = getArbitraryTcConfigBuilder()
    ParseCompilerOptions(ignore, GetCoreFscCompilerOptions b, [ "--enable:hotreloadhook" ])
    applyHotReloadDeterminismPins b
    Assert.False(b.parallelIlxGen)
    Assert.Equal(OptimizationProcessingMode.Sequential, b.optSettings.processingMode)

[T-Gro]

This file hits GetOrAddName but never the name-map accessor. A guard for the torn read in CompilerGeneratedNameMapState.fs:32:

[<Fact>]
let ``accessor is safe under concurrent first use`` () =
    let accessor = getCompilerGeneratedNameMapAccessor (obj ())
    let errors = System.Collections.Concurrent.ConcurrentBag<exn>()
    runConcurrently 1000 (fun _ ->
        try Assert.True((accessor ()).IsNone)
        with e -> errors.Add e)
    Assert.Empty(errors)

[T-Gro]

This hashes a type from its TypeReprInfo (kind + fields) but not its base type or interfaces — tcaug_super / ImmediateInterfaceTypesOfFSharpTycon are never read anywhere in the diff. So a base-class or interface change makes no RepresentationHash change and isn't caught as rude:

• inherit A() → inherit B(): the ctor body changes and goes through as an allowed MethodBody edit, but TypeDef.Extends stays A → invalid delta (InvalidProgram/TypeLoad on apply).
• adding a marker interface (no members): no field/member change at all → zero edits, silently dropped, no rude diagnostic. (The existing test passes only because it adds an interface with a member.)

Fold them into the hash so these become a rude TypeLayoutChange:

sb.Append("|super:").Append(match tycon.TypeContents.tcaug_super with Some t -> tyToString denv t | None -> "") |> ignore
for i in tycon.ImmediateInterfaceTypesOfFSharpTycon |> List.map (tyToString denv) |> List.sort do
    sb.Append("|intf:").Append(i) |> ignore

[T-Gro]

The metadata delta emits updated methods at their baseline row (IlxDeltaEmitter.fs:758), but the PDB delta here takes the fresh row (GetRowNumber sourceHandle) and builds the EncMap from it. When an edit also adds a method (or any generation ≥2 after an add), the rows shift and the two disagree, so ApplyUpdate attaches the new sequence points to the wrong method or rejects the PDB delta — i.e. breakpoints/stepping break after that reload. The gen-1 identity-map PdbTests don't exercise it. Fix: compute methodRow/EncMap from the baseline token, like the metadata writer.

[T-Gro]

This runs in the FSharpChecker primary constructor, so every FSharpChecker.Create locks and wipes the process-global capture store. A host that creates a second checker (IDE, test runs) then silently discards the first's hot-reload capture state. Don't clear process-global state from a per-instance ctor — scope it to the session.