perf: Hot reload's source snapshot capture after a compile rewrites only the changed sources, and is skipped when hot reload and pause point are both disabled

[hatayama]

Summary

• This collects the four pull requests of the first phase of Source snapshot capture blocks the main thread for ~2 s after each script compile in a large project #3222 (hot reload's source snapshot capture holds the main thread after every compile): the capture now rewrites only the sources that changed since the previous capture (perf: Hot reload's source snapshot capture rewrites only the sources that changed since the last compile #3277), it is skipped when the hot-reload and pause-point tools are both disabled (perf: Skip the hot reload source snapshot capture when the hot-reload and pause-point tools are both disabled #3276), its phases are logged in a debug breakdown (chore: Log where the hot reload source snapshot capture spends its time #3274), and a reader for an assembly's source list out of its PDB document table is added for the next phase (chore: Read the sources a compiled assembly was built from out of its PDB document table #3275, not called from production yet).
• On the trial project (a large multi-assembly project), the median time the capture held the main thread went from 1517 ms to 975 ms after a method-body edit (one assembly with about 1,300 sources recompiled), and from 5354 ms to 1435 ms after adding or removing a file (about 70 dependent assemblies with about 10,000 sources recompiled). With both tools disabled the capture does not run.
• Source snapshot capture blocks the main thread for ~2 s after each script compile in a large project #3222 stays open, because the rest is not short enough yet. After a body edit, about 80% of the remaining time is CompilationPipeline.GetAssemblies() (450–850 ms). Unity answers it only on the main thread, and the capture is its first caller after a domain reload, so the capture also fills the per-domain list that later hot reload steps reuse. After a file add or remove, most of the remaining time is per-source work over about 10,000 sources: two stats per source, reading the previous manifests, and string handling. Taking both off the main thread is the next phase and is not part of this pull request.

Merge status

• Each pull request was reviewed and merged into the integration branch perf/hot-reload-snapshot-capture. The reporting agent measured the trial project twice: on head c8137355 (the breakdown only, as the baseline) and on head 974a2b56 (this pull request's head). Each measurement had five body edits and three file adds or removes, with ULOOP_DEBUG set and the Editor in the background.
• On 974a2b56, every body edit copied 1 file and kept 1,292, every file add or remove copied 0 or 1 file and kept 10,054, and read/write time was 0–1 ms. One hot reload after a body edit reported Applied with one method patched, and the default file selection picked only the edited file. No reason about a missing snapshot or a PDB checksum mismatch appeared. No Console error or exception appeared during either measurement window.
• The repository squash-merges, so these four changes become one commit and one release-note line in the changelog of the Unity package. The title can be reworded at merge time.

User Impact

Before	After	PR
After each compile, the capture copied every source of each recompiled assembly into a new snapshot directory while the Editor waited on the main thread: on the trial project 1.5 s after a body edit and 5.4 s after a file add or remove (medians of the capture's own totalMs)	The capture moves the previous build's snapshot directory to the new build's name and rewrites only the sources whose length or write time changed, or that were written after the compile started. Every copy is still a byte-exact copy of the source the compiler read. The same edits take 0.98 s and 1.4 s	#3277
The capture ran after every domain reload, and the warm-up started, even when no tool that reads the snapshot was enabled	With both the hot-reload and pause-point tools disabled, the capture is skipped; with the hot-reload tool disabled, the warm-up does not start. The first hot reload run or pause point after either tool is enabled takes the capture	#3276
A pause point read the snapshot without passing the capture gate	A pause point captures through the same gate as a hot reload run before it reads	#3276
The only figure was captureMs	One hot_reload_source_snapshot_breakdown debug entry per capture gives each phase's time and counts, including filesReused (ULOOP_DEBUG builds only)	#3274, #3277
—	A reader that builds an assembly's source list from its dll and portable PDB, with a test that cross-checks it against CompilationPipeline.GetAssemblies() on every compiled assembly of the development project. Not called from production yet	#3275

Verification

• CI on 974a2b56: Unity EditMode Tests (2022.3.62f3, 6000.3.15f1, 6000.5.8f1, latest 6000.7, and the Release code optimization leg) and Unity Compile Check (2022.3.62f1, 6000.5.4f1) passed. In the root GameCI container, the two perf: Hot reload's source snapshot capture rewrites only the sources that changed since the last compile #3277 tests that need a user who can be denied file access are reported as Skipped, by design.
• Trial project medians of totalMs (ms):

Edit	Baseline c8137355	This head 974a2b56
Method-body edit (5 runs)	1517	975
File add or remove (3 runs)	5354	1435

Refs #3222

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: hatayama/unity-cli-loop/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 2319b7f8-9ba1-4088-ba1a-902e53cde4fd

---

📥 Commits

Reviewing files that changed from the base of the PR and between 2230f8e and 974a2b5.

---

⛔ Files ignored due to path filters (14)

• Assets/Tests/Editor/HotReload/Fixtures.meta is excluded by none and included by none
• Assets/Tests/Editor/HotReload/Fixtures/PdbDocumentTable.meta is excluded by none and included by none
• Assets/Tests/Editor/HotReload/Fixtures/PdbDocumentTable/CommentOnlySourceFixture.cs.meta is excluded by none and included by none
• Assets/Tests/Editor/HotReload/Fixtures/PdbDocumentTable/EmptySourceFixture.cs.meta is excluded by none and included by none
• Assets/Tests/Editor/HotReload/Fixtures/PdbDocumentTable/InterfaceOnlySourceFixture.cs.meta is excluded by none and included by none
• Assets/Tests/Editor/HotReload/HotReloadCompiledSourceCrossCheckTests.cs.meta is excluded by none and included by none
• Assets/Tests/Editor/HotReload/HotReloadCompiledSourceMapTests.cs.meta is excluded by none and included by none
• Assets/Tests/Editor/HotReload/HotReloadIncrementalSnapshotCaptureTests.cs.meta is excluded by none and included by none
• Assets/Tests/Editor/HotReload/HotReloadPdbDocumentTableTests.cs.meta is excluded by none and included by none
• Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadCompiledSourceMap.cs.meta is excluded by none and included by none
• Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadPdbDocumentTable.cs.meta is excluded by none and included by none
• Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadSnapshotCaptureStats.cs.meta is excluded by none and included by none
• Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadSnapshotPackageRoots.cs.meta is excluded by none and included by none
• Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadSourceSnapshotCopier.Incremental.cs.meta is excluded by none and included by none

---

📒 Files selected for processing (31)

• Assets/Tests/Editor/HotReload/Fixtures/PdbDocumentTable/CommentOnlySourceFixture.cs
• Assets/Tests/Editor/HotReload/Fixtures/PdbDocumentTable/EmptySourceFixture.cs
• Assets/Tests/Editor/HotReload/Fixtures/PdbDocumentTable/InterfaceOnlySourceFixture.cs
• Assets/Tests/Editor/HotReload/HotReloadCompiledSourceCrossCheckTests.cs
• Assets/Tests/Editor/HotReload/HotReloadCompiledSourceMapTests.cs
• Assets/Tests/Editor/HotReload/HotReloadCompositionRootTests.cs
• Assets/Tests/Editor/HotReload/HotReloadDomainTests.cs
• Assets/Tests/Editor/HotReload/HotReloadEditorStartupTests.cs
• Assets/Tests/Editor/HotReload/HotReloadIncrementalSnapshotCaptureTests.cs
• Assets/Tests/Editor/HotReload/HotReloadPdbDocumentTableTests.cs
• Assets/Tests/Editor/HotReload/HotReloadSnapshotAssemblyEnumerationTests.cs
• Assets/Tests/Editor/HotReload/HotReloadSnapshotEditedDuringCompileTests.cs
• Assets/Tests/Editor/HotReload/HotReloadSourceSnapshotTests.cs
• Assets/Tests/Editor/HotReload/HotReloadSourceSnapshotterTests.cs
• Packages/src/Editor/CompositionRoot/UnityCliLoopEditorBootstrapper.cs
• Packages/src/Editor/FirstPartyTools/FirstPartyToolsEditorStartup.cs
• Packages/src/Editor/FirstPartyTools/HotReload/HotReloadCompositionRoot.cs
• Packages/src/Editor/FirstPartyTools/HotReload/HotReloadEditorStartup.cs
• Packages/src/Editor/FirstPartyTools/HotReload/Patching/HotReloadPausePointPort.cs
• Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadCompiledSourceMap.cs
• Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadConstants.cs
• Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadPdbDocumentIndex.cs
• Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadPdbDocumentTable.cs
• Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadSnapshotCaptureStats.cs
• Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadSnapshotPackageRoots.cs
• Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadSourceSnapshotCopier.Incremental.cs
• Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadSourceSnapshotCopier.cs
• Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadSourceSnapshotter.Stamp.cs
• Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadSourceSnapshotter.cs
• docs/hot-reload.md
• docs/vibe-logs.md

---

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

---

📝 Walkthrough

Walkthrough

This change adds PDB document-table reading and source-path mapping, incremental source snapshot capture, capture metrics, and tool-setting gates for startup and pause-point capture.

Changes

Hot-reload source snapshots

Layer / File(s)	Summary
Read and map PDB source documents Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadPdbDocument*, Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadCompiledSourceMap.cs, Assets/Tests/Editor/HotReload/HotReloadPdbDocumentTableTests.cs, Assets/Tests/Editor/HotReload/HotReloadCompiledSourceMapTests.cs, Assets/Tests/Editor/HotReload/HotReloadCompiledSourceCrossCheckTests.cs, Assets/Tests/Editor/HotReload/Fixtures/PdbDocumentTable/*	The PDB reader returns document-table entries after checking that the PDB and DLL identifiers match. The source map converts supported URLs to Unity asset paths. Tests cover mappings, bodyless documents, and comparisons with Unity source-file lists.
Reuse and publish source snapshots Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadSourceSnapshotCopier*, Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadSourceSnapshotter*, Assets/Tests/Editor/HotReload/HotReloadIncrementalSnapshotCaptureTests.cs	The snapshotter selects incremental capture when a reusable prior snapshot is available. Incremental capture reuses eligible copies, recopies other listed sources, removes stale copies, and publishes the updated snapshot. Tests cover reuse conditions, fallback, and publication.
Measure and report snapshot capture Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadSnapshotCaptureStats.cs, Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadSourceSnapshotCopier.cs, Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadSourceSnapshotter.cs, Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadConstants.cs, Assets/Tests/Editor/HotReload/HotReloadSnapshot*Tests.cs, docs/vibe-logs.md	Capture records phase durations and assembly, file, and byte counts. Domain-reload capture emits a breakdown log. Tests check the metrics and capture counts; the log documentation describes the fields.
Gate startup and pause-point capture Packages/src/Editor/CompositionRoot/UnityCliLoopEditorBootstrapper.cs, Packages/src/Editor/FirstPartyTools/FirstPartyToolsEditorStartup.cs, Packages/src/Editor/FirstPartyTools/HotReload/HotReloadEditorStartup.cs, Packages/src/Editor/FirstPartyTools/HotReload/Patching/HotReloadPausePointPort.cs, Packages/src/Editor/FirstPartyTools/HotReload/HotReloadCompositionRoot.cs, Assets/Tests/Editor/HotReload/HotReload*Tests.cs, docs/hot-reload.md	Startup gates snapshot capture on hot-reload or pause-point settings and gates warm-up on hot-reload settings. The pause-point port requests capture before loading a verified snapshot. Tests and documentation cover these paths.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant PausePointPort
  participant SnapshotCaptureCallback
  participant HotReloadSnapshotter
  PausePointPort->>SnapshotCaptureCallback: Request snapshot capture
  SnapshotCaptureCallback->>HotReloadSnapshotter: EnsureCaptured with pause_point trigger
  PausePointPort->>PausePointPort: Load verified snapshot after capture

Loading

---

Merge Risk | ⚪ Minimal · up to 974a2

Merge Risk: ⚪ Minimal · up to 974a2

No confirmed issue blocks merging after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 974a2

The change reduces redundant copying while preserving checksum verification before snapshot text is used. Interrupted captures can still leave snapshots unavailable. No introduced security weakness was established, but coverage of all affected paths remains incomplete.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The inspected exposure is project-local source and snapshot storage used by the Editor’s hot-reload and pause-point readers. Capture can affect multiple project assemblies and embedded or local packages, but the changed paths do not establish new remote reachability or elevated authority.

Trust Boundaries and Controls

• observed — Tool settings gate eager preparation, not snapshot verification. A skipped startup capture leaves the gate untouched, and the inspected hot-reload apply and pause-point reader paths demand capture before snapshot consumption. Cached filesystem metadata does not authorize verified baseline text.

Resilience and Maintainability Implications

• observed — A checksum mismatch during copying is recorded as edited-after-compile rather than treated as a publication exception. Conversely, interrupted publication leaves no final snapshot for that MVID, and verified loading returns no source rather than consuming the incomplete directory.

---

Pre-merge checks | 4 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 59.28% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 167 functions across 28 files. (2 skipped…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check		The title accurately summarizes the primary changes: incremental source rewriting and skipping capture when both tools are disabled. It is long but clear and directly related to the changeset.
Description check		The description directly explains the incremental capture, tool-disabled behavior, logging, PDB reader, performance results, and verification described by the changeset.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

---

Full details: Docstring Coverage

Explanation

Docstring coverage is 59.28% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 167 functions across 28 files. (2 skipped: 2 unsupported.)

---

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

---

---

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}