Cache reference timestamps behind an IVsAsyncFileChangeEx2 watcher for snapshot reuse

[xperiandri]

Description

The transparent compiler's snapshot-reuse guard (WorkspaceExtensions.createProjectSnapshot) decided whether an old snapshot could be reused by stat'ing every -r: reference of the project (getOnDiskReferences) — on every new Roslyn Project instance, i.e. on every workspace fork, and before the cheap same-version fast path. For a project with a few hundred references that is a few hundred GetLastWriteTimeUtc calls per keystroke-driven typecheck.

This PR replaces that stat with a cached stamp that an IVsAsyncFileChangeEx2 watcher keeps fresh.

• FileChangeWatcher.fs — the watcher, the F# counterpart of Roslyn's FileChangeWatcher / ReferenceFileChangeTracker (internal to Microsoft.VisualStudio.LanguageServices, not reachable through ExternalAccess.FSharp): advise/unadvise batched on a single-consumer queue with a 500 ms window, coalesced per kind and per sink; recursive .dll directory watches over the reference roots (DOTNET_ROOT/packs, machine dotnet/packs, .NET Framework reference assemblies, the NuGet cache honouring NUGET_PACKAGES); ref-counted per-file watches for everything else; free-threaded sink; batch application as a cancellableTask under a token the watcher owns.
• FSharpReferenceChangeTracker keeps each watched path's last-write stamp inside its watch entry and drops it on the raw change notification. IReferenceStamps.GetLastWriteTimeUtc serves the cached value only while the path is watched — a stamp is only ever served while a notification can still reach it — and stats unwatched paths directly. The 2 s debounce stays for consumers that do expensive work per change.
• FSharpProjectOptionsReactor watches the -r: set of each project it computes options for, diffed on recompute so an unchanged set touches nothing, and exposes the stamps as FSharpProjectOptionsManager.ReferenceStamps. It does not invalidate anything on a change — see below.
• The ReferencesOnDisk guard in createProjectSnapshot reads the stamps. On a mismatch with the snapshot's own stamps (FCS stats when it builds one) it drops the project's stamps, so a missed notification costs one re-stat pass rather than a rebuild on every future Project instance.

Why the reactor does not call InvalidateConfiguration

An earlier revision of this PR did. Checked in VS with breakpoints on both paths and a referenced project rebuilt from the command line: for a -r: the workspace holds as a MetadataReference, Roslyn already advises the file (ProjectSystemProjectFactory), swaps the reference when it changes and bumps Project.Version; the reactor sees that through isProjectInvalidated, recomputes and calls InvalidateConfiguration itself — and it gets there first (Roslyn batches over 500 ms; this tracker adds a 2 s debounce on top of the same window). So the watch here exists for the stamps, not for invalidation. c15f47bd52 in the history is that removal; the subscription that returns in 744355228a serves a different purpose.

Not in this PR

1. FSharpProjectSnapshot.FromOptions stats every -r: when a snapshot is built from scratch (FCS side); Let FSharpProjectSnapshot.FromOptions take reference stamps from the host #20459 adds the getReferenceStamp parameter that lets it read the same cache, and the one-line VS consumer follows once it merges.
2. IsReferencesInvalidated on the incremental builder (legacy path) stats every reference per request; that needs the reference analogue of useChangeNotifications on the FCS side.
3. Scripts: #load sources are invisible to the workspace; watching them drops the script's cached options.

docs/ide/file-watching.md records what the workspace already covers, what it does not, and the shape of the watcher.

Checklist

• Test cases added — FileChangeWatcherTests.fs: WatchedDirectory coverage; tracker ref-counting, debounce and dispose against an in-memory watcher; applyBatch against a recording IVsAsyncFileChangeEx2; and the stamp cache — served while watched until a notification, stat'd when unwatched, dropped by Invalidate, stat'd again once the last watch stops.
• Performance benchmarks added in case of performance changes — measured in VS instead (transparent compiler + snapshot reuse on, breakpoint in referencesOnDiskChanged): on repeat passes the reuse guard for projects with 187 and 349 -r: read every stamp from the tracker — 0 GetLastWriteTimeUtc, the tracker's stamp count was identical before and after getOnDiskReferences. Touching a referenced dll dropped its stamp; the next guard re-stat'd that one file and rebuilt the snapshot (References on disk changed in the trace), after which passes were cached again.
• Release notes entry updated — docs/release-notes/.VisualStudio/18.vNext.md; docs/release-notes/.FSharp.Compiler.Service/11.0.100.md for the illib helper.

[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:

Change path	Release notes path	Description
`src/Compiler`	docs/release-notes/.FSharp.Compiler.Service/11.0.100.md
`vsintegration/src`	docs/release-notes/.VisualStudio/18.vNext.md

[xperiandri]

We have a helper extension method that can be used here

[xperiandri]

There is no equality helper in illib (only StartsWithOrdinal/EndsWithOrdinal/EndsWithOrdinalIgnoreCase/IndexOfOrdinal), so instead of comparing I changed the data: per-project watches are now a HashSet<string>(StringComparer.OrdinalIgnoreCase) and the notification does paths.Contains path. Done in 57f2bb0.

[xperiandri]

Why not voption in new tests code?

[xperiandri]

Switched to voption in 57f2bb0.

[xperiandri]

Can it ever be none? I would make it mandatory

[xperiandri]

Made mandatory in 57f2bb0; LanguageService.fs is the only caller and always passes one.

[xperiandri]

I think fileChangeWatcher must be mandatory.
If we need to pass it as null in tests, let's do

let fileChangeWatcher =
	withNull fileChangeWatcher |> ValueOption.ofObj

[xperiandri]

Done in 57f2bb0 — IFSharpFileChangeWatcher is a plain required parameter now on both the reactor and the manager, and the Option.map/Option.iter plumbing around the tracker is gone. No null path is needed: the tests exercise FSharpReferenceChangeTracker with an in-memory mock watcher and never construct the manager.

[xperiandri]

use string intepolation

[xperiandri]

Done in 57f2bb0.

[xperiandri]

why not?

Suggested change

	member val Cookie: uint32 option = None with get, set
	member val Cookie: uint32 voption = ValueNone with get, set

[xperiandri]

Done in 57f2bb0, plus the two use sites (ValueSome cookie on advise, a match on unadvise).

[xperiandri]

Suggested change

	[
	if not (String.IsNullOrEmpty dotnetRoot) then
	IO.Path.Combine(dotnetRoot, "packs")
	IO.Path.Combine(Environment.GetFolderPath Environment.SpecialFolder.ProgramFiles, "dotnet", "packs")
	IO.Path.Combine(
	Environment.GetFolderPath Environment.SpecialFolder.ProgramFilesX86,
	"Reference Assemblies",
	"Microsoft",
	"Framework"
	)
	IO.Path.Combine(Environment.GetFolderPath Environment.SpecialFolder.UserProfile, ".nuget", "packages")
	]
	|> List.distinct
	|> List.map (fun d -> WatchedDirectory(d, [ ".dll" ]))
	seq {
	if not (String.IsNullOrEmpty dotnetRoot) then
	IO.Path.Combine(dotnetRoot, "packs")
	IO.Path.Combine(Environment.GetFolderPath Environment.SpecialFolder.ProgramFiles, "dotnet", "packs")
	IO.Path.Combine(
	Environment.GetFolderPath Environment.SpecialFolder.ProgramFilesX86,
	"Reference Assemblies",
	"Microsoft",
	"Framework"
	)
	IO.Path.Combine(Environment.GetFolderPath Environment.SpecialFolder.UserProfile, ".nuget", "packages")
	}
	|> Seq.distinct
	|> Seq.map (fun d -> WatchedDirectory(d, [ ".dll" ]))

[xperiandri]

Applied in 57f2bb0 with one addition: |> List.ofSeq at the end. FileChangeContext iterates the watched directories on every EnqueueWatchingFile, so a lazy seq would re-run Environment.GetFolderPath and Seq.distinct per watched file; materializing once here keeps the single Seq chain but evaluates it one time.

[github-actions]

🔍 Tooling Safety Check — Affects-Design-Time
Affects-Design-Time: adds FileChangeWatcher + FSharpReferenceChangeTracker to VS integration that execute at design time

Generated by PR Tooling Safety Check · opus46 4.5M · ◷

[xperiandri]

Suggested change

	|> List.ofSeq
	|> Seq.toList

[xperiandri]

Done in 4b20482.

[xperiandri]

Why no cancellation? why not cancellableTask CE for enclosing function?

[xperiandri]

Done in 439e7ce: applyBatch is a cancellableTask, takes the token with CancellableTask.getCancellationToken () and passes it to every IVsAsyncFileChangeEx2 call.

[xperiandri]

and then propagate cancellation to CancellableTask here

[xperiandri]

Done in 439e7ce. The agent is started with a token from a CancellationTokenSource the watcher owns (FSharpFileChangeWatcher is IDisposable now: cancel, dispose, dispose the mailbox), the loop reads it via Async.CancellationToken and runs the batch with CancellableTask.startAsTask ct. The catch-all that kept the loop alive on failed advises became with ex when not (ex :? OperationCanceledException), so cancellation is no longer swallowed. LanguageService.fs constructs the watcher with new accordingly; nothing disposes it there on purpose — it lives as long as the workspace service, same as the checker.

[xperiandri]

@T-Gro what do we prefer? Interface or function type?

Suggested change

	type internal CreateIFSharpFileChangeContext = ImmutableArray<WatchedDirectory> -> IFSharpFileChangeContext

[smoothdeveloper]

IMO, since you started with interface, unless there is a big win with function (which I don't see), I'd leave it as is.

In general, for a single method, and no design foresight on what it could evolve into later on, function is fine.

The bonus of interface, even for one method is the named arguments.

[xperiandri]

Fresh-eyes pass over the whole PR against the current Roslyn FileChangeWatcher / ReferenceFileChangeTracker and against what FCS actually does with references. The shape is right: batched advise/unadvise with the 500 ms window, directory watches for the reference roots, ref-counted per-file watches, free-threaded sink. Three things need fixing, and one framing point matters for the description.

Must fix (inline, with suggestions):

1. WatchFiles runs are coalesced across sinks and advised with the first one. Latent today, breaks as soon as a second context exists.
2. FSharpReferenceChangeTracker races Timer.Change against Timer.Dispose and can throw inside the VS file change callback; it also allocates a timer per unwatched path before checking whether anyone watches it.
3. cache.TryRemove in onWatchedReferenceChanged never reaches consumers (they go through ProjectCache.Projects) and causes a second InvalidateConfiguration at the next recompute, discarding a builder that may already be rebuilt. InvalidateConfiguration alone is the right call.

Framing. As it stands the PR does not change observable latency. On the legacy path getOrCreateBuilder (BackgroundCompiler.fs L492) evaluates IsReferencesInvalidated on every request, and that stats every reference with a fresh TimeStampCache (IncrementalBuild.fs L1245). On the transparent-compiler path the snapshot reuse compares ReferencesOnDisk by stat (WorkspaceExtensions.fs L250) and FromOptions stats on creation. Both notice a rebuilt dll at the next request anyway, and InvalidateConfiguration only swaps in a lazy builder node without computing anything. So "keeps serving options and snapshots computed against the old assembly" is not what happens today. The value of the watcher arrives when it replaces those stat loops: a reference-change notification for the incremental builder on the FCS side (the analogue of useChangeNotifications for sources) and a watcher-invalidated stamp cache for snapshots. Worth presenting this PR as that infrastructure and listing both follow-ups explicitly.

Also inline: diff-based watch updates instead of stop-all/start-all on every options recompute, NUGET_PACKAGES and whether the NuGet cache should be a directory watch at all (Roslyn does not do that), a shared no-op token, the drain loop, logging of swallowed exceptions, the design-review doc, and applyBatch test coverage. The Fixes # (issue, if applicable) placeholder is still in the description.

All suggestions were applied together on the branch and pass dotnet fantomas --check; the changed regions were type-checked and smoke-tested with stand-ins for the VS interop types (sink grouping, drain, debounce and the timer race under 8 concurrent producers, watch diffing).

[xperiandri]

Bug (latent): WatchFiles runs are coalesced across sinks. The whole run of consecutive WatchFiles operations is advised with the sink of the first one. With a single context this cannot bite, but CreateContext allows several, and the moment a second one exists (the script #r/#load watcher from the follow-ups) its files get subscribed with the wrong sink and its notifications are silently lost. Roslyn's CanCombineWith only merges operations with the same sink.

Suggested change

	| WatchFiles(_, _, sink) :: _ ->
	let batch =
	pending
	|> Seq.takeWhile (function
	| WatchFiles _ -> true
	| _ -> false)
	|> Seq.toArray
	| WatchFiles(_, _, sink) :: _ ->
	let batch =
	pending
	|> Seq.takeWhile (function
	| WatchFiles(_, _, s) -> obj.ReferenceEquals(s, sink)
	| _ -> false)
	|> Seq.toArray

[xperiandri]

Applied in d8dce7a: the run stops at the first WatchFiles whose sink is not ReferenceEquals to the head one. Covered by A run of file watches is split when the sink changes.

[xperiandri]

Bug: Timer.Change races Timer.Dispose. The handler takes the timer out of pendingTimers without the lock; fire (and the tracker's Dispose) remove and dispose it. If an event lands between TryRemove and Change, Change throws ObjectDisposedException straight out of the free-threaded FilesChanged/DirectoryChangedEx2 callback, i.e. inside the VS file change service. Narrow window, but a rebuild is exactly the burst that hits it.

Second problem in the same block: the watchedFiles.ContainsKey check only runs in fire, so every .dll event under the watched directories allocates a Timer first. With ~/.nuget/packages watched recursively, any restore on the machine creates thousands of timers for files nobody watches.

Doing the bookkeeping under gate and checking first fixes both. With everything under the lock pendingTimers can become a plain Dictionary; left out here so the suggestion applies on its own. (Roslyn's current ReferenceFileChangeTracker has no per-path timers at all: one 5 s batching queue with string dedupe.)

Suggested change

	ctx.FileChanged.Add(fun path ->
	let fire (_: obj) =
	pendingTimers.TryRemove path
	|> function
	| true, timer -> timer.Dispose()
	| _ -> ()
	// Only notify for paths someone is actually watching; directory watches
	// cover whole trees.
	let isWatched = lock gate (fun () -> watchedFiles.ContainsKey path)
	if isWatched then
	onChanged path
	let timer =
	pendingTimers.GetOrAdd(path, fun _ -> new Timer(fire, null, Timeout.Infinite, Timeout.Infinite))
	timer.Change(notificationDelay, Timeout.InfiniteTimeSpan) |> ignore)
	ctx.FileChanged.Add(fun path ->
	let fire (_: obj) =
	let isWatched =
	lock gate (fun () ->
	match pendingTimers.TryRemove path with
	| true, timer -> timer.Dispose()
	| _ -> ()
	watchedFiles.ContainsKey path)
	if isWatched then
	onChanged path
	lock gate (fun () ->
	// Directory watches cover whole trees; only debounce paths someone watches.
	if not disposed && watchedFiles.ContainsKey path then
	let timer =
	pendingTimers.GetOrAdd(path, fun _ -> new Timer(fire, null, Timeout.Infinite, Timeout.Infinite))
	timer.Change(notificationDelay, Timeout.InfiniteTimeSpan) |> ignore))

[xperiandri]

Applied in d8dce7a, including the step you left out: with all bookkeeping under gate, pendingTimers is a plain Dictionary now. The handler checks watchedFiles before it allocates or arms a timer, and fire removes and disposes under the same lock, so Change can no longer meet a disposed timer inside the VS callback.

[xperiandri]

cache.TryRemove here does more harm than good. Consumers resolve options through ProjectCache.Projects (WorkspaceExtensions.fs L177), a ConditionalWeakTable keyed by the Roslyn Project instance, so removing the reactor entry does not reach them. When the reactor is next consulted (any new Project instance) the miss forces a recompute, whose success path calls InvalidateConfiguration again (L464) and throws away a builder that may already have been rebuilt against the new dll. Meanwhile GetCompilationDefinesAndLangVersionForEditingDocument and TryGetQuickParsingOptionsForEditingDocumentOrProject fall back to default defines until that recompute.

The options themselves are still correct (same paths); only the FCS build behind them is stale, and InvalidateConfiguration on the cached options is all that is needed.

Suggested change

	// Push invalidation for on-disk '-r:' reference assemblies (not tracked by the Roslyn
	// workspace): when one changes after an external rebuild, drop the cached options of every
	// project referencing it instead of waiting for a timestamp poll to notice.
	let referenceWatches = ConcurrentDictionary<ProjectId, HashSet<string>>()
	let onWatchedReferenceChanged (path: string) =
	for KeyValue(projectId, paths) in referenceWatches do
	if paths.Contains path then
	match cache.TryRemove projectId with
	| true, (_, _, projectOptions) -> checker.InvalidateConfiguration(projectOptions, userOpName = "onWatchedReferenceChanged")
	| _ -> ()
	// Push invalidation for on-disk '-r:' reference assemblies, which the Roslyn workspace does not
	// track. The cached options stay valid (same paths); only the FCS build behind them goes stale.
	let referenceWatches = ConcurrentDictionary<ProjectId, HashSet<string>>()
	let onWatchedReferenceChanged (path: string) =
	for KeyValue(projectId, paths) in referenceWatches do
	if paths.Contains path then
	match cache.TryGetValue projectId with
	| true, (_, _, projectOptions) -> checker.InvalidateConfiguration(projectOptions, userOpName = "onWatchedReferenceChanged")
	| _ -> ()

[xperiandri]

Done in d8dce7a: cache.TryGetValue + InvalidateConfiguration, with the comment rewritten to say what actually goes stale.

[xperiandri]

Stop-all/start-all on every recompute defeats the ref-counting. tryComputeOptions reruns on every structural change and, through hasDependentVersionChanged, on every edit of a C# project the F# project references. Each time this drops every -r: to refcount 0 (disposing the token) and re-adds it: for paths outside the default directories that is an Unadvise plus an Advise on the service per reference per recompute, for an unchanged set. Roslyn only touches watches when a reference is actually added or removed. Diffing against the previous set keeps the common case free.

Suggested change

	let watchReferenceFiles (projectId: ProjectId) (projectOptions: FSharpProjectOptions) =
	clearReferenceWatches projectId
	let paths = HashSet<string>(StringComparer.OrdinalIgnoreCase)
	for option in projectOptions.OtherOptions do
	if option.StartsWithOrdinal "-r:" then
	paths.Add(option.Substring "-r:".Length) |> ignore
	if paths.Count > 0 then
	for path in paths do
	referenceChangeTracker.StartWatchingReference path
	referenceWatches[projectId] <- paths
	let watchReferenceFiles (projectId: ProjectId) (projectOptions: FSharpProjectOptions) =
	let paths = HashSet<string>(StringComparer.OrdinalIgnoreCase)
	for option in projectOptions.OtherOptions do
	if option.StartsWithOrdinal "-r:" then
	paths.Add(option.Substring "-r:".Length) |> ignore
	match referenceWatches.TryGetValue projectId with
	| true, previous ->
	for path in previous do
	if not (paths.Contains path) then
	referenceChangeTracker.StopWatchingReference path
	for path in paths do
	if not (previous.Contains path) then
	referenceChangeTracker.StartWatchingReference path
	| _ ->
	for path in paths do
	referenceChangeTracker.StartWatchingReference path
	if paths.Count > 0 then
	referenceWatches[projectId] <- paths
	else
	referenceWatches.TryRemove projectId |> ignore

[xperiandri]

Applied verbatim in d8dce7a. clearReferenceWatches stays for ClearOptions and ClearAllCaches, which are the two places a project really goes away.

[xperiandri]

NuGet cache. Two things to decide consciously here. Roslyn's ReferenceFileChangeTracker deliberately does not watch the NuGet cache as a directory (only packs and Reference Assemblies) and lets package dlls get per-file advises; a recursive watch over ~/.nuget/packages sees every restore on the machine. If it stays, it should at least honour NUGET_PACKAGES, otherwise a relocated cache silently degrades to per-file watches for everything.

Suggested change

	let dotnetRoot = Environment.GetEnvironmentVariable "DOTNET_ROOT"
	let directories =
	seq {
	if not (String.IsNullOrEmpty dotnetRoot) then
	IO.Path.Combine(dotnetRoot, "packs")
	IO.Path.Combine(Environment.GetFolderPath Environment.SpecialFolder.ProgramFiles, "dotnet", "packs")
	IO.Path.Combine(
	Environment.GetFolderPath Environment.SpecialFolder.ProgramFilesX86,
	"Reference Assemblies",
	"Microsoft",
	"Framework"
	)
	IO.Path.Combine(Environment.GetFolderPath Environment.SpecialFolder.UserProfile, ".nuget", "packages")
	let dotnetRoot = Environment.GetEnvironmentVariable "DOTNET_ROOT"
	let nugetPackages = Environment.GetEnvironmentVariable "NUGET_PACKAGES"
	let directories =
	seq {
	if not (String.IsNullOrEmpty dotnetRoot) then
	IO.Path.Combine(dotnetRoot, "packs")
	IO.Path.Combine(Environment.GetFolderPath Environment.SpecialFolder.ProgramFiles, "dotnet", "packs")
	IO.Path.Combine(
	Environment.GetFolderPath Environment.SpecialFolder.ProgramFilesX86,
	"Reference Assemblies",
	"Microsoft",
	"Framework"
	)
	if String.IsNullOrEmpty nugetPackages then
	IO.Path.Combine(Environment.GetFolderPath Environment.SpecialFolder.UserProfile, ".nuget", "packages")
	else
	nugetPackages

[xperiandri]

d8dce7a honours NUGET_PACKAGES. I kept the directory watch on purpose: here every -r: is watched uniformly and package assemblies are the bulk of them, so dropping it means one advise per package dll for every project. The cost of an unrelated restore is now one lock plus one dictionary lookup per event, since the tracker checks watchedFiles before it allocates a timer (your other comment). The reasoning is in docs/ide/file-watching.md so the next reader does not have to rediscover the Roslyn difference.

[xperiandri]

Swallowing silently hides the one failure mode that matters: if CreateDefaultServiceTask faults (the :?> IVsAsyncFileChangeEx2 cast on an unexpected service object), every batch throws here and file watching never works, with nothing in the output pane. The existing helper is enough.

Suggested change

	with ex when not (ex :? OperationCanceledException) ->
	// Never let a failed advise/unadvise (e.g. non-existent path) kill the
	// subscription loop; we simply won't get events for that path.
	()
	with ex when not (ex :? OperationCanceledException) ->
	// Never let a failed advise/unadvise (e.g. non-existent path) kill the
	// subscription loop; we simply won't get events for that path.
	DebugHelpers.FSharpOutputPane.logExceptionWithContext (ex, nameof FSharpFileChangeWatcher)

[xperiandri]

Done in d8dce7a — FSharpOutputPane.logExceptionWithContext (ex, nameof FSharpFileChangeWatcher), with the DebugHelpers namespace opened the way RoslynHelpers.fs does.

[xperiandri]

Nit: this is the hot path (most references are covered by the directory watches) and every call allocates a fresh object expression. One shared instance, like Roslyn's NoOpWatchedFile.Instance. Apply together with the suggestion at line 82 that declares noOpWatchedFile.

Suggested change

	if WatchedDirectory.FilePathCoveredByWatchedDirectories(watchedDirectories, filePath) then
	// Covered by a directory watch; nothing extra to subscribe.
	{ new IFSharpWatchedFile with
	member _.Dispose() = ()
	}
	if WatchedDirectory.FilePathCoveredByWatchedDirectories(watchedDirectories, filePath) then
	noOpWatchedFile

[xperiandri]

Done in d8dce7a, together with the declaration in FileChangeWatcherImpl.

[xperiandri]

Declaration for the shared no-op token used at line 279 (apply together with that suggestion).

Suggested change

	let batchingDelay = TimeSpan.FromMilliseconds 500.
	let batchingDelay = TimeSpan.FromMilliseconds 500.
	let noOpWatchedFile =
	{ new IFSharpWatchedFile with
	member _.Dispose() = ()
	}

[xperiandri]

This reads as a working note rather than repository documentation: it refers to stash@{7}, a local branch name, commit ids that exist only on one machine, and a suggested PR split. Reviewers will ask for it to go. Either a short design note (what is watched and why exactly those directories, the debounce, and the planned follow-up that replaces the stat polling) or move the rationale into the PR description.

[xperiandri]

Replaced in d8dce7a by docs/ide/file-watching.md: why a watcher, what is watched and why those directories (including where this deliberately differs from Roslyn on the NuGet cache), batching and debounce, the consumer, and the three follow-ups. No stash, branch or commit references.

[xperiandri]

applyBatch is the most intricate piece of the PR and has no coverage. FSharpFileChangeWatcher takes a Task<IVsAsyncFileChangeEx2>, so Task.FromResult of a recording fake that hands out sequential cookies is enough to check: consecutive WatchFiles land in one AdviseFileChangesAsync call; a run is split when the sink changes; a watch followed by an unwatch in the same batch unadvises the cookie the watch received; unwatching a token that was never advised is a no-op; Dispose of a context unadvises its directory cookies and its remaining file cookies.

[xperiandri]

Added in d8dce7a against a RecordingFileChangeService (Task.FromResult, sequential cookies): consecutive WatchFiles land in one AdviseFileChangesAsync; a run is split when the sink changes; watch + unwatch in one batch unadvises the cookie the watch received; unwatching a token without a cookie is a no-op (unwatching now also clears the token cookie, so a second dispose does not unadvise twice); Dispose of a context unadvises its directory cookies and its remaining file cookies. The batching window became a constructor argument — 704a0ad keeps a second constructor with the 500 ms default for production — so the tests run at 100 ms.

[xperiandri]

Addressed the fresh-eyes review in d8dce7a / 704a0ad; each inline thread has a reply. The description is reframed as you suggested: the watcher is infrastructure, the current stat loops (IsReferencesInvalidated, ReferencesOnDisk) still notice a rebuilt dll on the next request, and the latency win arrives with the two follow-ups now listed explicitly (an FCS-side reference-change notification for the incremental builder, and a watcher-invalidated stamp cache for snapshots), plus script #r/#load watching. The Fixes # placeholder is gone.

[xperiandri]

Reworked in c15f47b after checking the premise in VS instead of assuming it.

Breakpoints on both invalidation paths — onWatchedReferenceChanged in the reactor and the isProjectInvalidated branch of tryComputeOptions — with a referenced project rebuilt from the command line: Roslyn's path fires first. ProjectSystemProjectFactory already advises every MetadataReference path, swaps the reference when the file changes and bumps Project.Version, and the reactor recomputes and calls InvalidateConfiguration off the back of that. The tracker gets there later by construction: Roslyn batches over 500 ms, this adds a 2 s debounce on top of the same window.

So the reference subscription is gone and FSharpProjectOptionsReactor is untouched by this PR. What remains is the transport plus its tests, and the description now says plainly that it has no consumer yet and lists the three the workspace genuinely does not cover: script #load sources, the ReferencesOnDisk stamp cache, and an FCS-side notification replacing IsReferencesInvalidated.

Happy to fold the first of those into this PR instead, if you would rather not take a transport on its own.

[xperiandri]

The transport now has its consumer, and it is the one that actually removes a stat loop: the snapshot-reuse guard in createProjectSnapshot no longer stats every -r: per new Project instance; it reads stamps that the watcher keeps inside its watch entries (dadf230f5a, 744355228a, 7153224f14, 15bd8ce03e).

The reactor subscription is back, but not for the reason it was removed in c15f47bd52: it registers the -r: set so the stamps exist, and passes no change handler. Invalidating the FCS build stays Roslyn's job, as measured earlier.

Soundness rule, since it is the one thing worth reading closely: a cached stamp lives in the watch entry and is dropped on the raw notification, so it can only be served while a notification can still reach it; anything unwatched is stat'd directly; a mismatch against the snapshot's own stamps drops the project's stamps, so a missed notification costs one re-stat pass, not a rebuild per Project instance.

Description and docs/ide/file-watching.md are updated accordingly; the three remaining stat sites (FromOptions, IsReferencesInvalidated, script #load) are listed as follow-ups.

[xperiandri]

CI: every Windows leg failed with FS1116/FS1118 at FileChangeWatcher.fs(31,12) (EndsWithOrdinal), and CheckCodeFormatting flagged WorkspaceExtensions.fs.

Cause: inline members of the internal module Internal.Utilities.Library cannot be inlined into another assembly, InternalsVisibleTo or not — the optimizer drops their optimization data at the assembly boundary, so a consumer compiled with --optimize+ (Release) fails with FS1118, while --optimize- (Debug) compiles and calls the compiled method instead. Reproduced with a two-file library: module internal Lib + [<InternalsVisibleTo>] + let inline f … gives FS1116/FS1118 in the consumer under --optimize+ with both the SDK and the bootstrap compiler; a public module works; --realsig and a signature file make no difference. FSharp.Editor on main uses none of those helpers, which is why it only surfaced here.

Fix: call String.StartsWith/EndsWith with an explicit StringComparison directly in FSharp.Editor (plus the fantomas fix); the illib StartsWithOrdinalIgnoreCase helper stays. Verified locally: FSharp.Editor builds in Release with that change.