F# hot reload: Edit-and-Continue delta emission behind --test:HotReloadDeltas

.fantomasignore

@@ -102,6 +102,10 @@ src/Compiler/Facilities/prim-parsing.fsi
 src/Compiler/Utilities/TaggedCollections.fsi
 src/Compiler/Service/ServiceDeclarationLists.fsi
 
+# Fantomas limitation: reformatting produces invalid F# (script uses constructs fantomas mis-handles)
+
+tools/hot-reload/compare_roslyn.fsx
+
 # Fantomas limitations on signature files in FSharp.Core (to investigate)
 
 src/FSharp.Core/fslib-extra-pervasives.fsi

.gitattributes

@@ -29,6 +29,12 @@ mono/launcher text eol=lf
 mono/config.make text eol=lf
 targets.make text eol=lf
 
+# Hot reload tests embed F# source snippets as string literals and run line-anchored
+# string operations ('\n' Replace/Contains) on them; keep these files LF so the snippets
+# behave identically on Windows checkouts.
+tests/FSharp.Compiler.ComponentTests/HotReload/*.fs text eol=lf
+tests/FSharp.Compiler.Service.Tests/HotReload/*.fs text eol=lf
+
 *.sh text eol=lf
 
 *.bsl linguist-vendored=true

.gitignore

@@ -4,6 +4,9 @@ BenchmarkDotNet.Artifacts/
 
 /tests/scripts/current
 .dotnet/
+# Also ignore .dotnet as a symlink (the trailing-slash pattern above matches directories only,
+# which once let a dev-machine symlink slip into a commit and break every CI checkout).
+.dotnet
 .packages/
 .tools/
 

FSharp.slnx

@@ -43,6 +43,11 @@
       <BuildType Solution="Proto|*" Project="Release" />
     </Project>
   </Folder>
+  <Folder Name="/Tests/HotReloadDemo/">
+    <Project Path="tests/projects/HotReloadDemo/HotReloadDemoApp/HotReloadDemoApp.fsproj">
+      <BuildType Solution="Proto|*" Project="Debug" />
+    </Project>
+  </Folder>
   <Folder Name="/Tests/FSharp.Compiler.Service.Tests support/">
     <Project Path="tests/service/data/CSharp_Analysis/CSharp_Analysis.csproj">
       <BuildType Solution="Proto|*" Project="Debug" />

G1_REPORT.md

@@ -0,0 +1,161 @@
+# G1 report: stale-string hot reload delta decode
+
+## Summary
+
+Verdict on H1: refuted for the minimal session-level shape that emits a delta.
+
+The Giraffe-like handler edit that successfully emitted a session delta did not point its `ldstr`
+operand back into the baseline `#US` heap. The baseline `#US` heap size was 92 bytes, and the
+updated method body used token `0x7000005D`, offset 93. Offset 93 is the first appended delta
+user-string entry after the baseline heap, and it decodes to `"Hello World EDITED"`.
+
+The simple working contrast shows the same fingerprint: baseline `#US` size 36, delta `ldstr`
+token `0x70000025`, offset 37, value `"lib generation 1"`.
+
+## Repro test
+
+Added test:
+
+`FSharp.Compiler.Service.Tests.HotReload.HotReloadSessionTests.G1 same-line Giraffe-shaped handler string edit decodes delta user string operand`
+
+Source shape that emits:
+
+```fsharp
+module Sample.G1
+
+type HttpFunc = string -> string
+
+let handler1 (_: HttpFunc) (ctx: string) = "Hello World"
+
+let endpointA: (HttpFunc -> string -> string) = fun (_: HttpFunc) (ctx: string) -> "Endpoint A"
+let endpointB: (HttpFunc -> string -> string) = fun (_: HttpFunc) (ctx: string) -> "Endpoint B"
+let endpointC: (HttpFunc -> string -> string) = fun (_: HttpFunc) (ctx: string) -> "Endpoint C"
+```
+
+Edit: `"Hello World"` to `"Hello World EDITED"` on the same line.
+
+This emitted `Ok` with exactly one updated method, `0x06000001`, decoded as
+`Sample.G1::handler1`. It does not reproduce the stale-string bug.
+
+I also tried closer shapes with an endpoint container and the requested probe, including the exact
+value-bound handler form from the task (`let handler1: (HttpFunc -> string -> string) = fun ...`).
+Those did not produce a delta, so there was no IL to decode:
+
+- Inline endpoint-list closures after `handler1`: `UnsupportedEdit` / `FSHRDL099`, synthesized type
+  `Sample.G1.endpoints@8` had no baseline counterpart.
+- Named module-level endpoint lambdas plus a list or array container: same `FSHRDL099`, synthesized
+  type `Sample.G1.endpoints@12`.
+- No endpoint container, but `probe () = handler1 id "x"` or a named equivalent argument:
+  `FSHRDL099`, synthesized type `Sample.G1.probe@11` or `probe@13`.
+
+## Giraffe-like decode
+
+Baseline:
+
+- Baseline `#US` heap size: 92
+- Updated method: `Sample.G1::handler1`
+- Baseline method `ldstr`: `il+0x0000 token=0x70000001 offset=1`
+- Baseline offset 1 decodes to: `"Hello World"`
+
+Delta metadata:
+
+- Updated methods: `0x06000001`
+- EncLog: `(0x00000001, op=0), (0x06000001, op=0), (0x08000001, op=0), (0x08000002, op=0)`
+- EncMap: `0x00000001, 0x06000001, 0x08000001, 0x08000002`
+- Delta MethodDef row: `0x06000001`
+
+Delta `#US`:
+
+- Relative offset: 1
+- Absolute offset: 93
+- Value: `"Hello World EDITED"`
+- Encoded bytes:
+  `25 48 00 65 00 6C 00 6C 00 6F 00 20 00 57 00 6F 00 72 00 6C 00 64 00 20 00 45 00 44 00 49 00 54 00 45 00 44 00 00`
+
+Delta IL:
+
+- `ldstr`: `il+0x0000 token=0x7000005D offset=93`
+- `UserStringUpdates`: original `0x70000001`, new `0x7000005D`, value `"Hello World EDITED"`
+
+Interpretation:
+
+- Offset 93 is greater than the baseline heap size 92.
+- The token points into the appended delta `#US` suffix, not into the baseline heap.
+- The appended entry at absolute offset 93 is the edited string.
+
+## Working contrast decode
+
+Test:
+
+`FSharp.Compiler.Service.Tests.HotReload.HotReloadSessionTests.G1 simple module string edit decodes working contrast delta user string operand`
+
+Baseline:
+
+- Source: `let libValue () = "lib generation 0"`
+- Baseline `#US` heap size: 36
+- Updated method: `SessionLib::libValue`
+- Baseline method `ldstr`: `il+0x0000 token=0x70000001 offset=1`
+- Baseline offset 1 decodes to: `"lib generation 0"`
+
+Delta metadata:
+
+- Updated methods: `0x06000001`
+- EncLog: `(0x00000001, op=0), (0x06000001, op=0)`
+- EncMap: `0x00000001, 0x06000001`
+- Delta MethodDef row: `0x06000001`
+
+Delta `#US`:
+
+- Relative offset: 1
+- Absolute offset: 37
+- Value: `"lib generation 1"`
+- Encoded bytes:
+  `21 6C 00 69 00 62 00 20 00 67 00 65 00 6E 00 65 00 72 00 61 00 74 00 69 00 6F 00 6E 00 20 00 31 00 00`
+
+Delta IL:
+
+- `ldstr`: `il+0x0000 token=0x70000025 offset=37`
+- `UserStringUpdates`: original `0x70000001`, new `0x70000025`, value `"lib generation 1"`
+
+This is the same appended-offset pattern as the Giraffe-like handler case.
+
+## Analysis
+
+The observed delta does not support the heap-offset hypothesis. In both cases, the original fresh
+compile token was `0x70000001`, but the emitter remapped it to `baselineUserStringHeapSize + 1` via
+the delta user-string allocator:
+
+- Giraffe-like handler: `92 + 1 = 93`, token `0x7000005D`
+- Simple contrast: `36 + 1 = 37`, token `0x70000025`
+
+That is the expected behavior of `UserStringTokenCalculator` in
+`src/Compiler/CodeGen/IlxDeltaStreams.fs`. The observed `UserStringUpdates` also match the remap
+path in `src/Compiler/CodeGen/IlxDeltaEmitter.fs`: the fresh method body's old-looking token
+`0x70000001` is resolved in the fresh assembly to the new text, then rewritten to an absolute
+delta token.
+
+So if the real Giraffe endpoint still serves the old string after the runtime accepts an update,
+this session-level decode points away from a bad `#US` heap offset in the emitted delta. The next
+place I would look is runtime application or method identity/body selection in the real app
+topology, especially because the endpoint-container and probe variants hit synthesized-type
+alignment failures in this harness before a delta can be emitted.
+
+## Verification
+
+Focused G1 tests:
+
+```text
+./.dotnet/dotnet build tests/FSharp.Compiler.Service.Tests/FSharp.Compiler.Service.Tests.fsproj --framework net10.0 --no-restore
+./.dotnet/dotnet artifacts/bin/FSharp.Compiler.Service.Tests/Debug/net10.0/FSharp.Compiler.Service.Tests.dll --filter-method "*G1*" --show-live-output on --output Detailed
+```
+
+Result: 2 passed, 0 failed.
+
+HotReload service suite:
+
+```text
+./.dotnet/dotnet build tests/FSharp.Compiler.Service.Tests/FSharp.Compiler.Service.Tests.fsproj --framework net10.0 --no-restore
+./.dotnet/dotnet artifacts/bin/FSharp.Compiler.Service.Tests/Debug/net10.0/FSharp.Compiler.Service.Tests.dll --filter-namespace "FSharp.Compiler.Service.Tests.HotReload" --output Normal
+```
+
+Result: 419 passed, 0 failed.

G1_TASK.md

@@ -0,0 +1,58 @@
+# G1: decode the delta for the Giraffe stale-string edit
+
+Worktree: /Users/nat/Projects/hot_reload_poc/fsharp-opt. Build with ./.dotnet/dotnet.
+BUG under investigation: on the real Giraffe sample (module-level `let handler1: HttpHandler = fun
+(_: HttpFunc) (ctx: HttpContext) -> ctx.WriteTextAsync "Hello World"`, eta-expanded to a static
+method), a same-line string-literal edit produces a delta that the runtime applies successfully
+(updatedMethods = the correct Program::handler1 row) but the endpoint keeps serving the OLD string.
+The synthetic test apps show string edits correctly. Prime hypothesis H1: the updated method body's
+ldstr token (0x70xxxxxx) resolves into the BASELINE #US heap (old string) instead of the delta's
+appended #US entry (delta US offsets must be ABSOLUTE, i.e. baseline-heap-length-based, per the
+delta format docs in this repo: HOT_RELOAD_SPEC / notes/delta_format may exist at the workspace root
+one level up - do not rely on them, decode from first principles with SRM).
+
+## Step 1: build a session-level repro test (scratch, in tests/FSharp.Compiler.Service.Tests/HotReload/)
+Follow the existing session tests' shape (HotReloadSessionTests.fs: checker.Compile baseline to
+disk, ResetSessionState, CreateHotReloadSession, AddProject, edit source, checker.Compile again OR
+use the in-process flag - MATCH THE GIRAFFE TOPOLOGY: flag-off baseline compile, then EmitDelta with
+FSHARP_HOTRELOAD_INPROCESS_COMPILE=1 so the fresh compile is in-process). Source shape mimicking
+Giraffe (no ASP.NET dependency needed):
+  module Sample.G1
+  type HttpFunc = string -> string
+  let handler1: (HttpFunc -> string -> string) = fun (_: HttpFunc) (ctx: string) -> "Hello World"
+  let probe () = handler1 id "x"
+Plus 2-3 more module-level closures AFTER handler1 (mimic the endpoints list: a list of closures)
+so the file is closure-dense. Edit ONLY the literal "Hello World" -> "Hello World EDITED" (same
+line, no line count change). EmitDelta must return Ok with exactly 1 updated method.
+
+## Step 2: decode the delta
+From the Ok delta (fields: Metadata: byte[], IL: byte[], Pdb; plus UpdatedMethods tokens):
+1. Read the BASELINE assembly bytes (the on-disk baseline DLL): via System.Reflection.Metadata get
+   the baseline #US heap SIZE and verify reading the old string at its offset.
+2. Parse delta.Metadata with MetadataReaderProvider.FromMetadataImage: enumerate EncLog/EncMap, the
+   MethodDef row(s) updated, and dump the delta #US heap bytes (raw) - what string(s) does it carry
+   and at what ABSOLUTE offsets do they live (delta heap offsets are logically appended after the
+   baseline heap)?
+3. Parse delta.IL: locate the method body (tiny: header + IL). Extract the ldstr operand token(s)
+   (opcode 0x72, little-endian 4-byte token, high byte 0x70). Compute offset = token & 0x00FFFFFF.
+4. VERDICT: offset < baselineUsHeapSize means the ldstr points at the BASELINE heap (H1 CONFIRMED:
+   which string does that offset decode to in the baseline? presumably the OLD "Hello World").
+   offset >= baselineUsHeapSize means it points into the delta's appended US entries (H1 dead:
+   decode which delta string it hits and whether that is the NEW string; then the bug is elsewhere -
+   report what you see).
+5. CONTRAST: run the same decode on the delta from an edit shape that WORKS (the existing session
+   test's simple module function edit, e.g. reuse the flag test's libValue shape) and report its
+   ldstr offset vs baseline heap size. The difference between the two is the bug's fingerprint.
+
+## Step 3: report
+G1_REPORT.md: repro test name + whether it reproduces (if the repro's delta decodes CORRECTLY, say
+so explicitly and describe what you tried; do NOT force a repro), the decoded numbers for both
+cases (baseline US size, delta US contents+offsets, ldstr operands), the verdict on H1, and if
+confirmed, your analysis of WHERE the offset goes wrong (the user-string token calculators live in
+src/Compiler/CodeGen/IlxDeltaStreams.fs UserStringTokenCalculator; the emitter's US remap trace is
+under traceUserStringUpdates in IlxDeltaEmitter.fs - grep '[fsharp-hotreload][userstrings]').
+Suites: run the HotReload service suite once at the end to prove no regressions from your scratch
+test (it may stay in the tree as a regression test if it reproduces; name it for G1).
+
+## Rules
+No commits/pushes/git changes. No em dashes. No AI mentions. Keep the repro minimal.

docs/debug-emit.md

@@ -32,6 +32,22 @@ Some experiences are un-implemented by F# including:
 * **Edit and Continue**
 * **Hot reload**
 
+## Hot reload heap tracing
+
+The hot-reload metadata writer now exposes a lightweight tracing hook so you can capture heap sizes while iterating on Task 2.3. Set the environment variable `FSHARP_HOTRELOAD_TRACE_HEAPS=1` before running a targeted test, for example:
+
+```
+FSHARP_HOTRELOAD_TRACE_HEAPS=1 ./.dotnet/dotnet test tests/FSharp.Compiler.Service.Tests/FSharp.Compiler.Service.Tests.fsproj -c Debug -f net10.0 --filter FullyQualifiedName~FSharpDeltaMetadataWriterTests
+```
+
+Each delta emitted during the run prints a summary such as:
+
+```
+[fsharp-hotreload][heap-summary] baseline:string=1234 blob=2048 guid=256 | delta:string=64 blob=32 guid=0
+```
+
+The new service-level regressions (`property/event/async delta reports baseline heap offsets`) validate that `MetadataDelta.HeapOffsets` mirror the baseline reader before any heap reuse changes are made. Combine those tests with the trace output above to document the current string/blob footprint before adjusting the builders.
+
 ## Emitted information
 
 Emitted debug information includes: