Add the F# hot reload session and FCS service surface

docs/hot-reload-rude-edits.md

@@ -0,0 +1,27 @@
+# F# hot reload rude-edit diagnostics
+
+F# hot reload reports an `FSHRDL` diagnostic when an edit cannot be applied safely to the running process. The application is rebuilt and restarted instead of applying a delta that could leave it in an invalid state.
+
+The diagnostic message identifies the affected declaration and the reason for the restart. These codes are owned by the F# compiler and are separate from Roslyn's `ENC` diagnostic namespace.
+
+| Code | Meaning | What to do |
+| --- | --- | --- |
+| `FSHRDL001` | A member signature changed. | Undo the signature change to apply in place, or allow the rebuild and restart. |
+| `FSHRDL002` | An `inline` annotation changed. | Allow the rebuild and restart. |
+| `FSHRDL003` | A type representation or layout changed. | Allow the rebuild and restart. |
+| `FSHRDL004` | A declaration was added in a shape the runtime cannot add. | Allow the rebuild and restart. |
+| `FSHRDL005` | A declaration was removed. | Allow the rebuild and restart. |
+| `FSHRDL006` | A virtual, abstract, or override member was added. | Allow the rebuild and restart. |
+| `FSHRDL007` | A constructor was added. | Allow the rebuild and restart. |
+| `FSHRDL008` | A user-defined operator was added. | Allow the rebuild and restart. |
+| `FSHRDL009` | An explicit interface implementation was added. | Allow the rebuild and restart. |
+| `FSHRDL010` | A member was added to an interface. | Allow the rebuild and restart. |
+| `FSHRDL011` | A field was added in a shape the runtime cannot add. | Allow the rebuild and restart. |
+| `FSHRDL012` | A lambda's lowered shape changed incompatibly. | Allow the rebuild and restart. |
+| `FSHRDL013` | A state machine's resumable or hoisted layout changed incompatibly. | Keep the existing resume-point and captured-value layout, or allow the rebuild and restart. |
+| `FSHRDL014` | A query expression's lowered shape changed incompatibly. | Allow the rebuild and restart. |
+| `FSHRDL015` | A synthesized compiler declaration changed incompatibly. | Allow the rebuild and restart. |
+| `FSHRDL016` | The runtime did not advertise a capability required by the edit. | Update the runtime if a newer version supports the capability, or allow the rebuild and restart. |
+| `FSHRDL099` | The edit is unsupported for another fail-closed reason. | Follow the detailed message and allow the rebuild and restart. |
+
+These diagnostics are intentionally fail closed. If the compiler cannot prove that an edit is safe, it requests a restart and leaves the running application unchanged.

docs/hot-reload-runtime-async.md

@@ -0,0 +1,26 @@
+# Runtime async edits
+
+Hot reload rejects changes to the runtime-async implementation flag on an existing method. Such an edit requires an application restart.
+
+The method signature alone does not identify this change. Both implementations return `Task<int>` in metadata, but their IL return conventions differ. Normal IL returns a task. Runtime-async IL returns its integer result and requires the `0x2000` implementation flag.
+
+The delta writer preserves implementation flags from the baseline. It compares the async bit before it emits an updated method row. A mismatch raises `HotReloadUnsupportedEditException` instead of an invalid delta.
+
+## Reference contract
+
+The comparison uses Roslyn commit `eb789e2741f6f22d9e283e2049dc1378871323e0`, inspected on September 25, 2026.
+
+- `MetadataWriter.PopulateMethodTableRows` writes the current method implementation flags.
+- `AbstractEditAndContinueAnalyzer` rejects changes to the non-custom `MethodImplAttribute`.
+- [Roslyn issue #77954](https://github.com/dotnet/roslyn/issues/77954) remains open for runtime-async edit support.
+- The [runtime specification](https://github.com/dotnet/runtime/blob/25bd04c79542dfaaab5c5cd42670bcfc20b7d57a/docs/design/specs/runtime-async.md) defines the distinct return conventions.
+
+The F# rejection is a temporary limit. It does not claim complete parity with future runtime-async edit support in Roslyn.
+
+## Verification
+
+Six regressions cover both transition directions, methods added by an earlier delta, unchanged flags, and runtime application. The .NET 11 run passed all 39 hot reload component tests with no skips. The runtime test called the same method before and after `MetadataUpdater.ApplyUpdate`. Its task result changed from 42 to 43.
+
+A full `mdv` review covered the baseline and the unchanged-flag delta. Both method rows retained `0x2000`. The delta reused the baseline signature and emitted only the module and method update entries in `EncLog` and `EncMap`.
+
+Metadata tests do not require runtime-async execution support. The execution test requires CoreCLR, the runtime's `Async` implementation flag, and enabled metadata updates.

docs/release-notes/.FSharp.Compiler.Service/11.0.200.md

@@ -1,5 +1,10 @@
 ### Added
 
+* Add the experimental `FSharpChecker.CreateHotReloadSession` API with per-project baselines, capability checks, and commit or discard operations. Distinct `--out:` paths retain independent baselines. Requests preserve cancellation through file waits and metadata recovery. ([Issue #11636](https://github.com/dotnet/fsharp/issues/11636), [PR #20030](https://github.com/dotnet/fsharp/pull/20030))
+* Added internal F# hot reload delta emitter and symbol matcher infrastructure with direct emitter test coverage. ([PR #20027](https://github.com/dotnet/fsharp/pull/20027))
+
+* Add an internal typed-tree diff utility for future F# hot reload edit classification. It is not called by normal compilation. ([PR #20025](https://github.com/dotnet/fsharp/pull/20025))
+
 * Add a read-only repository review agent for performance-improvement PRs to assess measurement quality, behavior preservation, and implementation risk using source-attributed review precedents. ([PR #20619](https://github.com/dotnet/fsharp/pull/20619))
 * Completion: respect EditorBrowsableAttribute ([PR #20729](https://github.com/dotnet/fsharp/pull/20729))
 * Runtime-async sequences allow awaits inside `try/with` bodies, filters and handlers, and reject overlapping `MoveNextAsync` calls. ([PR #20655](https://github.com/dotnet/fsharp/pull/20655))

src/Compiler/AbstractIL/DeltaIndexSizing.fs

@@ -11,9 +11,10 @@ module internal FSharp.Compiler.AbstractIL.DeltaIndexSizing
 
 open FSharp.Compiler.AbstractIL.BinaryConstants
 open FSharp.Compiler.AbstractIL.ILDeltaHandles
-open FSharp.Compiler.AbstractIL.ILMetadataHeaps
 open FSharp.Compiler.AbstractIL.DeltaMetadataEncoding
 
+type MetadataHeapSizes = FSharp.Compiler.AbstractIL.ILBinaryWriter.MetadataHeapSizes
+
 /// Holds computed "bigness" flags for all coded index types.
 /// When true, the index requires 4 bytes; when false, 2 bytes suffice.
 type CodedIndexSizes =

src/Compiler/AbstractIL/DeltaMetadataSerializer.fs

@@ -4,7 +4,7 @@ open System
 open System.Collections.Generic
 open System.IO
 open System.Text
-open FSharp.Compiler.AbstractIL.ILMetadataHeaps
+open FSharp.Compiler.AbstractIL.ILBinaryWriter
 open FSharp.Compiler.AbstractIL.BinaryConstants
 open FSharp.Compiler.AbstractIL.ILDeltaHandles
 open FSharp.Compiler.AbstractIL.DeltaMetadataTables

src/Compiler/AbstractIL/DeltaMetadataTables.fs

@@ -1,5 +1,6 @@
 module internal FSharp.Compiler.AbstractIL.DeltaMetadataTables
 
+open FSharp.Compiler.EnvironmentHelpers
 open System
 open System.Collections.Generic
 open System.IO
@@ -15,11 +16,7 @@ open FSharp.Compiler.AbstractIL.DeltaMetadataTypes
 module Encoding = FSharp.Compiler.AbstractIL.DeltaMetadataEncoding
 
 let traceHeapOffsets =
-    lazy
-        (match Environment.GetEnvironmentVariable("FSHARP_HOTRELOAD_TRACE_HEAP_OFFSETS") with
-         | null
-         | "" -> false
-         | value -> value = "1" || String.Equals(value, "true", StringComparison.OrdinalIgnoreCase))
+    lazy (isEnvVarTruthy EnvironmentVariableNames.HotReloadTraceHeapOffsets)
 
 /// Mirrors the AbstractIL metadata tables for the subset of rows emitted by
 /// hot reload deltas. The tables are populated alongside the SRM metadata
@@ -494,7 +491,7 @@ type DeltaMetadataTables(?heapOffsets: MetadataHeapOffsets) =
             else
                 invalidArg "entry" "GUID entries must be 16 bytes."
 
-        if Environment.GetEnvironmentVariable("FSHARP_HOTRELOAD_TRACE_METADATA") = "1" then
+        if isEnvVarSetToOne EnvironmentVariableNames.HotReloadTraceMetadata then
             let dumpGuid (bytes: byte[]) =
                 if bytes.Length >= 16 then
                     BitConverter.ToString(bytes, 0, 16)
@@ -645,7 +642,8 @@ type DeltaMetadataTables(?heapOffsets: MetadataHeapOffsets) =
                 rowElementUShort (uint16 row.Attributes)
                 stringElement nameToken
                 blobElement signatureToken
-                rowElementSimpleIndex TableNames.Param (row.FirstParameterRowId |> Option.defaultValue 0)
+                // Roslyn suppresses ParamList in deltas. EncLog owns parameter associations.
+                rowElementSimpleIndex TableNames.Param 0
             |]
 
         methodRows.Add rowElements

src/Compiler/AbstractIL/FSharpDeltaMetadataWriter.fs

@@ -1,9 +1,10 @@
 module internal FSharp.Compiler.AbstractIL.FSharpDeltaMetadataWriter
 
 open System
+open FSharp.Compiler.EnvironmentHelpers
 open System.Collections.Generic
 open Microsoft.FSharp.Collections
-open FSharp.Compiler.AbstractIL.ILMetadataHeaps
+open FSharp.Compiler.AbstractIL.ILBinaryWriter
 open FSharp.Compiler.AbstractIL.BinaryConstants
 open FSharp.Compiler.AbstractIL.ILDeltaHandles
 open FSharp.Compiler.AbstractIL.IlxDeltaStreams
@@ -13,25 +14,13 @@ open FSharp.Compiler.AbstractIL.DeltaTableLayout
 open FSharp.Compiler.AbstractIL.DeltaMetadataSerializer
 
 [<Literal>]
-let private TraceMetadataFlagName = "FSHARP_HOTRELOAD_TRACE_METADATA"
+let private TraceMetadataFlagName = EnvironmentVariableNames.HotReloadTraceMetadata
 
 [<Literal>]
-let private TraceHeapsFlagName = "FSHARP_HOTRELOAD_TRACE_HEAPS"
+let private TraceHeapsFlagName = EnvironmentVariableNames.HotReloadTraceHeaps
 
 [<Literal>]
-let private TraceMethodsFlagName = "FSHARP_HOTRELOAD_TRACE_METHODS"
-
-/// Local copy of FSharp.Compiler.EnvironmentHelpers.isEnvVarTruthy. That module is a new
-/// utility file added by the hot-reload feature branch and isn't part of this extraction's
-/// scope, so the writer's trace-flag checks carry their own tiny copy instead of pulling in
-/// an extra out-of-scope file.
-let private isEnvVarTruthy (name: string) =
-    match Environment.GetEnvironmentVariable(name) with
-    | null
-    | "" -> false
-    | value when String.Equals(value, "1", StringComparison.OrdinalIgnoreCase) -> true
-    | value when String.Equals(value, "true", StringComparison.OrdinalIgnoreCase) -> true
-    | _ -> false
+let private TraceMethodsFlagName = EnvironmentVariableNames.HotReloadTraceMethods
 
 let private shouldTraceMetadata () = isEnvVarTruthy TraceMetadataFlagName