chore: Prepare compile status and pause points for a background source snapshot capture

[hatayama]

Summary

• Groundwork for moving hot reload's source snapshot capture off the main thread (Source snapshot capture blocks the main thread for ~2 s after each script compile in a large project #3222). Nothing changes for users yet: the new hold is never set, and the new pause point path is never taken.
• get-compile-status can now hold back the compile completion while a capture runs.
• A pause point can read a source file on disk while a capture runs, but only when the compiled assembly's PDB confirms it holds the bytes the compiler read.

User Impact

• None in this PR. The next PR moves the capture to a pool thread and wires both pieces. With them, uloop compile still returns only after the capture finishes, and a pause point re-armed on the first update tick after a reload does not wait for the whole capture.

Changes

• ToolContracts/HotReloadSnapshotCaptureCoordination.IsHoldingCompileCompletion: a static delegate the hot-reload startup will set. Null means not holding. It has the same shape as HotReloadRuntimeChangeCoordination, because the server assembly may not reference the tool.
• CompileStatusBridgeCommand:
  • Reads the delegate.
  • BuildResponse takes isSnapshotCaptureHolding, and Ready is false while it is true. A pending compile request is then not recovered, because recovery only runs when ready.
  • The query VibeLog entry gains is_snapshot_capture_holding.
• HotReloadSourceBaseline.LoadVerifiedLiveSourceOrNull: returns the file on disk when its bytes match the PDB document checksum. It returns null when the file is missing or unreadable, when the PDB has no document for it, or when the checksums differ. It reads the same path the capture copies from. It decodes with the same function as the snapshot, so a byte order mark is handled the same way.
• HotReloadPausePointPort takes Func<bool> isCaptureInFlight. While a capture is in flight, it returns a confirmed live file without ensuring the capture. Otherwise it ensures the capture and reads the snapshot exactly as before. The composition root passes () => false for now.

Verification

• uloop compile: 0 errors. The warnings are all pre-existing ones in test fixtures.
• uloop run-tests --filter-type regex --filter-value "CompileStatusBridgeCommandTests|HotReloadDomainTests|HotReloadCompositionRootTests|HotReloadSourceSnapshotTests|OnionAssemblyDependencyTests|HotReloadLiveSourceVerificationTests": 173 passed, 0 failed.
• New tests:
  • CompileStatusBridgeCommandTests.BuildResponse_WhileTheSnapshotCaptureHolds_IsNotReadyAndDoesNotRecoverAPendingResult. The pending request has its reload observed, so it would be recovered if ready.
  • HotReloadDomainTests:
    • GetVerifiedSnapshotSource_WhileCaptureRuns_ReturnsTheLiveFileWhenItMatchesThePdbWithoutWaiting
    • ..._WhileCaptureRuns_WaitsWhenTheLiveFileDiffersFromThePdb. This uses a source the PDB has no document for, since a real project file cannot be edited in a test. A checksum mismatch is covered at the baseline level below.
    • ..._WhenNoCaptureRuns_EnsuresTheCaptureEvenIfTheLiveFileMatches
  • HotReloadLiveSourceVerificationTests:
    • the same text as the snapshot for the same bytes, with a new fixture saved with a UTF-8 byte order mark
    • checksum mismatch
    • missing file
    • no PDB document
• Mutations, each reverted after the run:

Mutation	Failing tests
Try the live file even when no capture runs	..._WhenNoCaptureRuns_EnsuresTheCaptureEvenIfTheLiveFileMatches
Never try the live file	..._ReturnsTheLiveFileWhenItMatchesThePdbWithoutWaiting
Return the live file without the checksum verdict	..._WaitsWhenTheLiveFileDiffersFromThePdb, LoadVerifiedLiveSourceAt_WhenTheLiveBytesDifferFromThePdb_ReturnsNull, ..._WhenThePdbHasNoDocument_ReturnsNull
Decode with Encoding.UTF8.GetString (keeps the byte order mark)	..._ReturnsTheLiveFileWhenItMatchesThePdbWithoutWaiting, LoadVerifiedLiveSourceOrNull_ReturnsTheSameTextAsTheSnapshotForTheSameBytes
Ignore the hold in Ready	BuildResponse_WhileTheSnapshotCaptureHolds_IsNotReadyAndDoesNotRecoverAPendingResult

[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: 8327de4c-65dd-4c33-92da-49496a52f966

---

📥 Commits

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

---

⛔ Files ignored due to path filters (3)

• Assets/Tests/Editor/HotReload/HotReloadLiveSourceBomFixture.cs.meta is excluded by none and included by none
• Assets/Tests/Editor/HotReload/HotReloadLiveSourceVerificationTests.cs.meta is excluded by none and included by none
• Packages/src/Editor/ToolContracts/HotReloadSnapshotCaptureCoordination.cs.meta is excluded by none and included by none

---

📒 Files selected for processing (9)

• Assets/Tests/Editor/CompileStatusBridgeCommandTests.cs
• Assets/Tests/Editor/HotReload/HotReloadDomainTests.cs
• Assets/Tests/Editor/HotReload/HotReloadLiveSourceBomFixture.cs
• Assets/Tests/Editor/HotReload/HotReloadLiveSourceVerificationTests.cs
• Packages/src/Editor/FirstPartyTools/HotReload/HotReloadCompositionRoot.cs
• Packages/src/Editor/FirstPartyTools/HotReload/Patching/HotReloadPausePointPort.cs
• Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadSourceBaseline.cs
• Packages/src/Editor/Infrastructure/Api/CompileStatusBridgeCommand.cs
• Packages/src/Editor/ToolContracts/HotReloadSnapshotCaptureCoordination.cs

---

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

---

---

📝 Walkthrough

Walkthrough

The hot-reload pause point can use PDB-verified live source while snapshot capture is in progress. Compile readiness now accounts for snapshot capture holding compile completion, and status-query logs record that state.

Changes

Hot-reload snapshot coordination

Layer / File(s)	Summary
PDB-verified source loading Packages/src/Editor/FirstPartyTools/HotReload/Shared/HotReloadSourceBaseline.cs, Assets/Tests/Editor/HotReload/HotReloadLiveSourceBomFixture.cs, Assets/Tests/Editor/HotReload/HotReloadLiveSourceVerificationTests.cs	The shared decoder handles verified source bytes with UTF-8 BOM detection. The live-source loader returns null when source bytes cannot be read or do not match the PDB checksum. Tests cover matching, mismatching, missing, and BOM-prefixed source files.
Pause-point source selection Packages/src/Editor/FirstPartyTools/HotReload/Patching/HotReloadPausePointPort.cs, Packages/src/Editor/FirstPartyTools/HotReload/HotReloadCompositionRoot.cs, Assets/Tests/Editor/HotReload/HotReloadDomainTests.cs	When capture is in flight, the pause point tries verified live source first. Otherwise, or when live-source verification fails, it ensures snapshot capture and loads the verified snapshot. Tests cover these capture states.
Compile readiness during capture Packages/src/Editor/ToolContracts/HotReloadSnapshotCaptureCoordination.cs, Packages/src/Editor/Infrastructure/Api/CompileStatusBridgeCommand.cs, Assets/Tests/Editor/CompileStatusBridgeCommandTests.cs	A coordination property reports whether snapshot capture holds compile completion. Compile readiness now uses that state, and status-query logs record it. A test verifies that a pending request remains pending while capture holds completion.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Other

Sequence Diagram(s)

sequenceDiagram
  participant HotReloadPausePointPort
  participant HotReloadSourceBaseline
  participant ensureSnapshotCaptured
  HotReloadPausePointPort->>HotReloadSourceBaseline: LoadVerifiedLiveSourceOrNull
  alt verified live source is available during capture
    HotReloadSourceBaseline-->>HotReloadPausePointPort: verified live source
  else capture is not in flight or live source is unavailable
    HotReloadPausePointPort->>ensureSnapshotCaptured: ensure snapshot capture
    HotReloadPausePointPort->>HotReloadSourceBaseline: load verified snapshot
  end

Loading

---

Merge Risk | ⚪ Minimal · up to e3b2b

Merge Risk: ⚪ Minimal · up to e3b2b

This is groundwork with no user-visible change yet. No concrete merge-blocking risk was identified.

Security Architecture Review

Security architecture risk: 🔵 Low · up to e3b2b

The new behavior is not enabled in normal use, and source-content verification is preserved. Risk is low, with no substantiated new security issue; future background activation still needs completion, recovery, and cleanup guarantees.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The assessed authority is the Unity editor process's source-file access and compile-session state. The live loader and pause-point port belong to internal classes, and production wiring keeps the new branch inactive. Public-method routing signals do not by themselves demonstrate a new externally callable file-read capability.

Trust Boundaries and Controls

• inferred — An edited live file must pass the compiled-document checksum control before its text reaches the compiled-line consumer. Verification and decoding use the same captured byte array, avoiding a second disk read after verification. This establishes consistency with trusted compiled metadata, not authenticity against an actor able to replace both compiled metadata and source.

Resilience and Maintainability Implications

• observed — A hold prevents premature pending-result recovery without changing request identity. After release, recovery still requires the matching pending request and a reload observation, stores the result under that ID, and clears only the matching pending record. Existing expiry cleanup still runs while holding; future long-running capture behavior is not established.

Hardening Proposals

• proposed — When background capture is activated, explicitly define ownership and ordering of capture-state publication and hold release across success, partial failure, interruption, service replacement, and domain reload. Validate repeated requests and retention expiry without releasing completion before the required source snapshot is usable.

---

Pre-merge checks | 4 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 35.90% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 39 functions across 9 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check		The title clearly summarizes the groundwork for compile-status coordination and pause points during background source snapshot capture.
Description check		The description directly explains the snapshot-capture coordination, verified live-source handling, pause-point behavior, tests, and expected user impact.
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.

---

• 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.}