fix(documents): hydrate session before RPC reads and edits

[urjitc]

Problem

The AI reads and edits collaborative documents by calling DocumentSession over native Durable Object RPC (getByName(...).readMarkdownChunk(...) / .applyMarkdownEdits(...)).

Native DO RPC bypasses partyserver's onStart/onLoad. DocumentSession sets hibernate: true and keeps its canonical content as an in-memory Yjs document that only onLoad hydrates. So against a hibernated session:

• readMarkdownChunk serialized a fresh, empty document → the AI saw the document as empty until the user opened it in a browser (the WebSocket connects over fetch, which runs onLoad and hydrates).
• applyMarkdownEdits could edit that empty document and checkpoint it back to the kernel — overwriting real content. (data-loss risk)

Only documents are affected. PDFs/images/folders read from durable SQL + R2 directly, with no in-memory hydration step, so a cold DO returns real data.

Fix

• New CollaborativeContentSession base for session DOs whose content is a hydrated in-memory Yjs document. It exposes ensureLoaded() around partyserver's sanctioned init escape hatch, with the reasoning documented once.
• DocumentSession awaits ensureLoaded() before every RPC method that touches the document. purgeForDeletion deliberately does not (it only wipes storage).
• Future editable item types (flashcards, etc.) extend the same base, so the guarantee is inherited rather than rediscovered per type.

Testing

• tsc, lint, full unit suite (195) green.
• A faithful cold-RPC regression test is non-trivial here: onLoad is coupled to the kernel checkpoint and reproducing "cold RPC skips onStart" in the workers test pool has no existing precedent. Flagging as a follow-up rather than shipping a fragile/falsely-green test.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Summary by CodeRabbit

• Bug Fixes
  • Improved collaborative document reliability by ensuring document content is loaded before reading or applying edits.
  • Streamlined document deletion so storage can be cleared without unnecessarily loading document content.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[capy-ai]

Capy auto-review is paused for this organization because the usage-cycle auto-review limit has been reached. Increase the limit or turn it off in billing settings to resume automatic reviews.

[github-actions]

React Doctor found no new issues. 🎉

_{Reviewed by React Doctor for commit 5ccccf0.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a shared CollaborativeContentSession base with explicit Durable Object hydration, then updates DocumentSession to hydrate before markdown reads and edits while leaving storage-only deletion unhydrated.

Changes

Collaborative content hydration

Layer / File(s)	Summary
Session hydration contract src/features/workspaces/collaborative-content-session.ts	Defines CollaborativeContentSession over YServer with a protected ensureLoaded() initializer.
Document content integration src/features/workspaces/documents/document-session.ts	Uses the new base class, hydrates markdown edits and reads, and documents that deletion only clears durable storage.

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

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main fix: hydrating document sessions before RPC reads and edits.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-document-session-cold-rpc

---

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

[coderabbitai]

🧹 Nitpick comments (1)

src/features/workspaces/documents/document-session.ts (1)

134-134: 📐 Maintainability & Code Quality | 🔵 Trivial | 🏗️ Heavy lift

Add cold native-RPC regression coverage.

These hydration calls fix the specific path where onStart is bypassed, but the PR notes that the current suite does not reproduce it. Please add focused coverage for a cold readMarkdownChunk and applyMarkdownEdits call to ensure persisted content is loaded before either operation.

Also applies to: 180-180

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/features/workspaces/documents/document-session.ts` at line 134, Add
focused regression tests for cold readMarkdownChunk and applyMarkdownEdits
calls, starting with a fresh document-session instance whose onStart path is
bypassed and persisted content is not yet hydrated. Verify each operation loads
the persisted content before proceeding, covering the ensureLoaded calls in the
corresponding methods.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/features/workspaces/documents/document-session.ts`:
- Line 134: Add focused regression tests for cold readMarkdownChunk and
applyMarkdownEdits calls, starting with a fresh document-session instance whose
onStart path is bypassed and persisted content is not yet hydrated. Verify each
operation loads the persisted content before proceeding, covering the
ensureLoaded calls in the corresponding methods.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 780133bc-84c3-4d7d-931b-037cc0b2f889

📥 Commits

Reviewing files that changed from the base of the PR and between 701797d and 5ccccf0.

📒 Files selected for processing (2)

• src/features/workspaces/collaborative-content-session.ts
• src/features/workspaces/documents/document-session.ts

[cubic-dev-ai]

No issues found across 2 files

<sub>Auto-approved: Fixes a data-loss bug where native DO RPC to a hibernated session would read/write an empty document. The fix is a small, bounded hydration call before each RPC method, with deliberate exclusion for deletion.

Re-trigger cubic</sub>