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/release-notes/.FSharp.Compiler.Service/11.0.100.md

@@ -132,7 +132,9 @@
 
 ### Added
 
+* 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))
 * Added internal synthesized-name replay infrastructure for compiler-generated names, preserving normal compilation output while enabling future hot reload name stability work.
+* 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))
 * Added `FSharpMemberOrFunctionOrValue.IsPropertyAccessor` convenience property that returns true for compiler-generated property accessors (`get_X` / `set_X`). ([Issue #18157](https://github.com/dotnet/fsharp/issues/18157), [PR #19883](https://github.com/dotnet/fsharp/pull/19883))
 * Added warning FS3884 when a function or delegate value is used as an interpolated string argument. ([PR #19289](https://github.com/dotnet/fsharp/pull/19289))
 * Symbols: add ObsoleteDiagnosticInfo ([PR #19359](https://github.com/dotnet/fsharp/pull/19359))
@@ -150,6 +152,8 @@
 * Add internal `ResetCompilerGeneratedNameState` to `CompilerGlobalState` name generators so warm-checker re-compilation can produce fresh-process-identical generated names. ([PR #20017](https://github.com/dotnet/fsharp/pull/20017))
 * Add internal ECMA-335 Edit-and-Continue metadata delta writer to AbstractIL. ([PR #20019](https://github.com/dotnet/fsharp/pull/20019))
 * Add Roslyn-format EnC CustomDebugInformation codec and portable PDB method CDI emission support to AbstractIL. ([PR #20018](https://github.com/dotnet/fsharp/pull/20018))
+* Add an experimental `FSharpChecker` hot reload session API with per-project baselines, capability-gated delta emission, and `Commit`/`Discard` transaction semantics. Off by default behind `--test:HotReloadDeltas`. ([Issue #11636](https://github.com/dotnet/fsharp/issues/11636), [PR #20030](https://github.com/dotnet/fsharp/pull/20030))
+* Add internal hot reload baseline reading for recorded EnC state and synthesized-name snapshot PDB data. ([PR #20026](https://github.com/dotnet/fsharp/pull/20026))
 * Support for the `<include>` XML documentation tag: at compile time, documentation is copied from an external XML file selected by an XPath query and emitted into the generated documentation file. `<inheritdoc>` remains unsupported. ([Issue #19175](https://github.com/dotnet/fsharp/issues/19175), [PR #19186](https://github.com/dotnet/fsharp/pull/19186))
 * Expand `<inheritdoc/>` at tooling time. In IDE tooltips, completion, and signature help, documentation is inherited from base classes, interfaces, overridden members, and constructors (matched by parameter signature). The FCS Symbols API (`FSharpSymbol.XmlDoc`) additionally resolves explicit `cref` targets, but does not expand constructor inheritance. The compiler emits the tag verbatim into generated XML documentation files, matching C#; `<include>` is not implemented. ([Issue #19175](https://github.com/dotnet/fsharp/issues/19175), [PR #19188](https://github.com/dotnet/fsharp/pull/19188))
 

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/EncMethodDebugInformation.fs

@@ -31,8 +31,11 @@ open System.IO
 open System.Reflection.Metadata
 open System.Reflection.Metadata.Ecma335
 open System.Runtime.InteropServices
+open System.Text
 open Microsoft.FSharp.NativeInterop
 
+open FSharp.Compiler.AbstractIL.ILPdbWriter
+
 /// Portable-PDB CustomDebugInformation kind GUIDs for the EnC blobs, copied verbatim
 /// from roslyn/src/Dependencies/CodeAnalysis.Debugging/PortableCustomDebugInfoKinds.cs.
 [<RequireQualifiedAccess>]
@@ -47,6 +50,10 @@ module PortableCustomDebugInfoKinds =
     /// EnC State Machine State Map CDI kind.
     let encStateMachineStateMap = Guid("8B78CD68-2EDE-420B-980B-E15884B8AAA3")
 
+    /// F#-owned hot reload synthesized-name snapshot CDI kind. The blob records
+    /// FSharpSynthesizedTypeMaps.Snapshot bucket arrays in allocation-slot order.
+    let fsharpSynthesizedNameSnapshot = Guid("49DDB47E-9C74-46EC-8626-0350676571EB")
+
 /// Closure ordinal of a lambda that is lowered to a static (non-capturing) method.
 /// Mirrors Roslyn's LambdaDebugInfo.StaticClosureOrdinal.
 [<Literal>]
@@ -167,7 +174,7 @@ let private MaxOccurrenceKey = 0x1FFFFFFD
 /// 16-bit segments, least-significant segment = the innermost ordinal; an enclosing
 /// ordinal p is stored as (p + 1) shifted left 16 so that depth-1 keys (< 0x10000) and
 /// depth-2 keys (>= 0x10000) never collide. Fails closed (None) past the limits: chains
-/// deeper than 2, ordinals > 0xFFFF, or keys exceeding the compressed-integer budget —
+/// deeper than 2, ordinals > 0xFFFF, or keys exceeding the compressed-integer budget,
 /// callers must then treat the chain as unmappable, never truncate.
 let tryEncodeOccurrenceKey (ordinalChain: int list) : int option =
     match ordinalChain with
@@ -209,6 +216,134 @@ let private invalidData (blobName: string) (offset: int) =
 // nullness model, so guard with box (FS3261-safe) rather than dropping the check.
 let private isEmpty (blob: byte[]) = isNull (box blob) || blob.Length = 0
 
+// ---------------------------------------------------------------------------
+// F# hot reload module CDI: synthesized-name allocation snapshot
+// Format:
+// compressed(version = 1), compressed(bucket count),
+// then buckets sorted by key for deterministic PDB bytes:
+//   string key, compressed(name count), string name in allocation-slot order.
+// Strings are compressed(byte length) followed by UTF-8 bytes.
+// ---------------------------------------------------------------------------
+
+[<Literal>]
+let private SynthesizedNameSnapshotBlobVersion = 1
+
+let private writeUtf8String (builder: BlobBuilder) (value: string) =
+    if isNull (box value) then
+        invalidArg (nameof value) "snapshot strings must be non-null"
+
+    let bytes = Encoding.UTF8.GetBytes value
+    builder.WriteCompressedInteger bytes.Length
+    builder.WriteBytes bytes
+
+let private readUtf8String (blobName: string) (reader: byref<BlobReader>) =
+    let length = reader.ReadCompressedInteger()
+
+    if length < 0 || length > reader.RemainingBytes then
+        invalidData blobName reader.Offset
+
+    let bytes = reader.ReadBytes length
+    Encoding.UTF8.GetString(bytes, 0, bytes.Length)
+
+let private materializeSynthesizedNameSnapshot (snapshot: seq<struct (string * string[])>) =
+    snapshot
+    |> Seq.map (fun struct (key, names) ->
+        if isNull (box key) then
+            invalidArg (nameof snapshot) "snapshot keys must be non-null"
+
+        if isNull (box names) then
+            invalidArg (nameof snapshot) $"snapshot bucket '{key}' must be non-null"
+
+        key, Array.copy names)
+    |> Seq.sortBy fst
+    |> Seq.toArray
+
+/// Serializes an allocation-ordered synthesized-name snapshot into the F#-owned module
+/// CDI blob. An empty snapshot returns an empty blob so no CDI row needs to be emitted.
+let serializeSynthesizedNameSnapshot (snapshot: seq<struct (string * string[])>) : byte[] =
+    let buckets = materializeSynthesizedNameSnapshot snapshot
+
+    if buckets.Length = 0 then
+        Array.empty
+    else
+        let builder = BlobBuilder()
+        builder.WriteCompressedInteger SynthesizedNameSnapshotBlobVersion
+        builder.WriteCompressedInteger buckets.Length
+
+        for key, names in buckets do
+            writeUtf8String builder key
+            builder.WriteCompressedInteger names.Length
+
+            for name in names do
+                writeUtf8String builder name
+
+        builder.ToArray()
+
+/// Deserializes the F#-owned synthesized-name snapshot CDI blob. Bucket order in the
+/// blob is deterministic only; each bucket array is returned exactly in recorded slot order.
+let deserializeSynthesizedNameSnapshot (blob: byte[]) : Map<string, string[]> =
+    if isEmpty blob then
+        Map.empty
+    else
+        let handle = GCHandle.Alloc(blob, GCHandleType.Pinned)
+
+        try
+            let mutable reader =
+                BlobReader(NativePtr.ofNativeInt<byte> (handle.AddrOfPinnedObject()), blob.Length)
+
+            try
+                let version = reader.ReadCompressedInteger()
+
+                if version <> SynthesizedNameSnapshotBlobVersion then
+                    invalidData "synthesized name snapshot" reader.Offset
+
+                let bucketCount = reader.ReadCompressedInteger()
+
+                if bucketCount <= 0 || bucketCount > reader.RemainingBytes / 2 then
+                    invalidData "synthesized name snapshot" reader.Offset
+
+                let buckets = ResizeArray<string * string[]>()
+
+                for _ in 1..bucketCount do
+                    let key = readUtf8String "synthesized name snapshot" &reader
+                    let nameCount = reader.ReadCompressedInteger()
+
+                    // Every serialized name consumes at least one byte for its UTF-8
+                    // length, so this check bounds allocation before Array.zeroCreate.
+                    if nameCount < 0 || nameCount > reader.RemainingBytes then
+                        invalidData "synthesized name snapshot" reader.Offset
+
+                    let names = Array.zeroCreate nameCount
+
+                    for i in 0 .. nameCount - 1 do
+                        names[i] <- readUtf8String "synthesized name snapshot" &reader
+
+                    buckets.Add(key, names)
+
+                if reader.RemainingBytes <> 0 then
+                    invalidData "synthesized name snapshot" reader.Offset
+
+                buckets |> Seq.map id |> Map.ofSeq
+            with :? BadImageFormatException ->
+                invalidData "synthesized name snapshot" reader.Offset
+        finally
+            handle.Free()
+
+/// Creates the module-level CustomDebugInformation row for the allocation-ordered
+/// synthesized-name snapshot. Empty snapshots emit no row.
+let computeSynthesizedNameSnapshotCustomDebugInfoRows (snapshot: seq<struct (string * string[])>) : PdbModuleCustomDebugInfo list =
+    let blob = serializeSynthesizedNameSnapshot snapshot
+
+    if blob.Length = 0 then
+        []
+    else
+        [
+            {
+                KindGuid = PortableCustomDebugInfoKinds.fsharpSynthesizedNameSnapshot
+                Blob = blob
+            }
+        ]
+
 // ---------------------------------------------------------------------------
 // EnC Local Slot Map
 // Format (EditAndContinueMethodDebugInformation.cs, SerializeLocalSlots lines 145-191,
@@ -555,3 +690,35 @@ let readEncMethodDebugInfoFromPortablePdb (pdbBytes: byte[]) : Map<int, EncMetho
             // Not a portable PDB image (or a corrupted one): callers still get an empty
             // map instead of a crash.
             Map.empty
+
+/// Reads the F#-owned allocation-ordered synthesized-name snapshot from a portable PDB.
+/// None means either the record is absent or invalid; callers must fall back to IL
+/// reconstruction rather than trusting a partial layout.
+let readSynthesizedNameSnapshotFromPortablePdb (pdbBytes: byte[]) : Map<string, string[]> option =
+    if isEmpty pdbBytes then
+        None
+    else
+        try
+            use provider =
+                MetadataReaderProvider.FromPortablePdbImage(ImmutableArray.CreateRange pdbBytes)
+
+            let reader = provider.GetMetadataReader()
+
+            let blobs =
+                [
+                    for cdiHandle in reader.CustomDebugInformation do
+                        let cdi = reader.GetCustomDebugInformation cdiHandle
+
+                        if cdi.Parent.Kind = HandleKind.ModuleDefinition then
+                            let kind = reader.GetGuid cdi.Kind
+
+                            if kind = PortableCustomDebugInfoKinds.fsharpSynthesizedNameSnapshot then
+                                reader.GetBlobBytes cdi.Value
+                ]
+
+            match blobs with
+            | [ blob ] -> Some(deserializeSynthesizedNameSnapshot blob)
+            | _ -> None
+        with
+        | :? BadImageFormatException
+        | :? InvalidDataException -> None

src/Compiler/AbstractIL/EncMethodDebugInformation.fsi

@@ -36,6 +36,9 @@ module PortableCustomDebugInfoKinds =
     /// EnC State Machine State Map CDI kind.
     val encStateMachineStateMap: System.Guid
 
+    /// F#-owned hot reload synthesized-name snapshot CDI kind.
+    val fsharpSynthesizedNameSnapshot: System.Guid
+
 /// Closure ordinal of a lambda that is lowered to a static (non-capturing) method.
 /// Mirrors Roslyn's LambdaDebugInfo.StaticClosureOrdinal.
 [<Literal>]
@@ -135,6 +138,19 @@ val tryEncodeOccurrenceKey: ordinalChain: int list -> int option
 /// root-first ordinal chain.
 val decodeOccurrenceKey: key: int -> int list
 
+/// Serializes an allocation-ordered synthesized-name snapshot into the F#-owned module
+/// CDI blob. An empty snapshot returns an empty blob so no CDI row needs to be emitted.
+val serializeSynthesizedNameSnapshot: snapshot: seq<struct (string * string[])> -> byte[]
+
+/// Deserializes the F#-owned synthesized-name snapshot CDI blob. Bucket order in the
+/// blob is deterministic only; each bucket array is returned exactly in recorded slot order.
+val deserializeSynthesizedNameSnapshot: blob: byte[] -> Map<string, string[]>
+
+/// Creates the module-level CustomDebugInformation row for the allocation-ordered
+/// synthesized-name snapshot. Empty snapshots emit no row.
+val computeSynthesizedNameSnapshotCustomDebugInfoRows:
+    snapshot: seq<struct (string * string[])> -> FSharp.Compiler.AbstractIL.ILPdbWriter.PdbModuleCustomDebugInfo list
+
 /// Serializes the EnC Local Slot Map blob for 'info', byte-for-byte as Roslyn's
 /// SerializeLocalSlots. Returns the empty array when there are no slots (no CDI row
 /// should be emitted then).
@@ -176,3 +192,8 @@ val deserialize:
 /// Fail safe: a null/empty or non-PDB image yields the empty map, and a method whose
 /// blobs do not decode is omitted rather than guessed.
 val readEncMethodDebugInfoFromPortablePdb: pdbBytes: byte[] -> Map<int, EncMethodDebugInformation>
+
+/// Reads the F#-owned allocation-ordered synthesized-name snapshot from a portable PDB.
+/// None means either the record is absent or invalid; callers must fall back to IL
+/// reconstruction rather than trusting a partial layout.
+val readSynthesizedNameSnapshotFromPortablePdb: pdbBytes: byte[] -> Map<string, string[]> option

src/Compiler/AbstractIL/FSharpDeltaMetadataWriter.fs

@@ -3,7 +3,7 @@ module internal FSharp.Compiler.AbstractIL.FSharpDeltaMetadataWriter
 open System
 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