fix(persistence): fail fast when the shared migration ledger diverges

[yordis]

• Sharing one T3 home across branches is normal in this fork, but the migrator decides what to run purely by id and never compares names, so a database migrated by a branch with different numbering makes this build silently skip migrations while the ledger still reads as fully migrated.
• The consequence surfaced far away from its cause: the schema looked current, then an unrelated read-model query failed and the desktop backend went into a restart loop, which is an expensive way to learn that the home directory belongs to another branch.
• Failing at startup with the list of migrations that would be skipped points at the actual decision the developer has to make, which is where the home directory should live.
• The check lives in the fork's own migration chain so the shared migration files stay byte-identical to upstream.

[cursor]

PR Summary

Medium Risk
Changes database startup order and can block server boot on shared T3 homes with divergent migration history, but avoids silent schema drift and confusing runtime query failures.

Overview
Adds verifySharedMigrationLedger, which runs after legacy realignSharedMigrationLedger and before shared migrations apply. It compares effect_sql_migrations to this build’s migrationManifest by id and name; when a ledger from another branch would make the migrator skip migrations (id-only “already applied”), startup fails with SharedMigrationLedgerMismatchError listing expected vs recorded names, gaps, and unknown ids, plus guidance to use a separate T3CODE_HOME or reset the DB.

SQLite persistence setup now calls this check on every open. Tests cover fresh/partial/future ids, divergent branch chains, missing ledger rows, and legacy realign paths. Fork docs add 0006 (separate fork ledger + startup check) and index it in the fork README.

^{Reviewed by Cursor Bugbot for commit 8814a80. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Warning

Review limit reached

@yordis, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 40 minutes

Limit details: You’ve used all 1 included review currently available under your plan.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3167eb9a-697b-4930-b771-e0520c2587d3

📥 Commits

Reviewing files that changed from the base of the PR and between b2463b2 and 8814a80.

📒 Files selected for processing (5)

• apps/server/src/persistence/ForkMigrations.test.ts
• apps/server/src/persistence/ForkMigrations.ts
• apps/server/src/persistence/Layers/Sqlite.ts
• docs/fork/0006-fork-migration-ledger.md
• docs/fork/README.md

---

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