fix: unloadDocument only deletes matching document instance

[whoalin1]

Summary

unloadDocument previously checked and deleted by document name only. A late call for an already-unloaded instance could remove a newer instance registered under the same name (e.g. after reconnect), breaking sync and storage.

This change requires instance identity: unload only proceeds when this.documents.get(documentName) === document, checked at the start and again immediately before delete.

Closes #1169

Test plan

• Reproduce scenario from unloadDocument() checks only the name, so a late call for an already unloaded instance unloads a newer instance of the same document #1169 (slow disconnect + reload same name) and confirm the newer instance stays in documents
• Normal unload still removes the document when it is the registered instance and has no connections / pending store work
• Concurrent disconnects for the same instance still unload once via unloadingDocuments

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository YAML (base), Organization UI (inherited)
• Review profile: CHILL
• Plan: Advanced
• Run ID: 02a5a8cf-1c01-42d7-a35d-9cea1913db76

📥 Commits

Reviewing files that changed from the base of the PR and between acddf68 and c3c17d8.

📒 Files selected for processing (1)

• packages/server/src/Hocuspocus.ts

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

---

📝 Summary

unloadDocument now checks that the document instance is still registered before unloading it and again before deleting it. This prevents a late call for an old instance from removing a newer instance with the same name.

Walkthrough

unloadDocument now checks that the document registered under a name is the same instance passed to the method. It checks this before the unloadability check and again after beforeUnloadDocument, before deletion.

Changes

Document unload guard

Layer / File(s)	Summary
Check document identity during unloading packages/server/src/Hocuspocus.ts	unloadDocument returns if the registered document is not the supplied instance. It checks identity again before deleting the document after beforeUnloadDocument completes.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested labels: complexity: easy, impact: low

Suggested reviewers: janthurau

Merge Risk: 🔵 Low · up to c3c17

A replacement installed while its predecessor’s unload hook is pending can miss its own unload and remain registered. This is a bounded cleanup risk; merge is reasonable with follow-up.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: unloadDocument only unloads the matching document instance.
Description check	✅ Passed	The description explains the stale-instance bug, the identity checks, and the planned tests. It is directly related to the changeset.
Linked Issues check	✅ Passed	Issue #1169 requires unloadDocument to ignore a stale document instance. The change checks that the registered instance matches at entry and again before deletion, including after beforeUnloadDocument…
Out of Scope Changes check	✅ Passed	The reported change is limited to document-instance checks in unloadDocument. These checks directly address issue #1169. No unrelated changes are reported.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…

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