feat(migrations): Unify schema and data journals

[dcramer]

Summary

• add the publishable @sentry/junior-migrations package for mixed SQL and TypeScript Drizzle journals
• generate 0001_name.ts data migrations through the same Drizzle Kit numbering workflow used for schema migrations
• run core and enabled-plugin migrations through one ordered, resumable journal runner
• expose the exact host database adapter as context.database
• keep one-off transformations in migration files while allowing append-only infrastructure helpers from @sentry/junior/migration-helpers/v1
• move every existing hardcoded core and scheduler data migration, including conversation usage repair from current main, into the journal
• remove plugin migrationTasks, context.tasks, duplicate host migration implementations, and unchanged Drizzle snapshots for data-only entries
• include the new package in Craft, CI, release alignment, package validation, and documentation

Migration contract

Each journal entry resolves to exactly one immutable <tag>.sql or <tag>.ts file. TypeScript entries target MigrationV1, receive the host database/state adapters, and own their one-off record transformations. They may import only external packages and the versioned @sentry/junior/migration-helpers/v1 infrastructure surface; unversioned Junior runtime imports, relative imports, dynamic imports, and runtime re-exports are rejected.

Drizzle Kit still owns schema snapshots and journal numbering. The data-migration generator removes the unchanged custom snapshot after creating a TypeScript entry; a verified follow-up schema generation continues from the latest real schema snapshot and preserves journal order.

Existing installations adopt their legacy core/plugin migration ledgers once, then all pending SQL and TypeScript entries execute through runMigrationJournal. TypeScript progress and results are persisted in the Drizzle ledger and failed entries resume with the same source hash.

Adversarial cleanup

After rebasing onto current main, the PR initially measured 7,447 additions. The dominant bloat was a 3,575-line whole-app bundle for legacy history plus 1,292 lines of unchanged custom snapshots. The final diff is 3,889 additions: the history migration is now 1,128 lines of conversion/storage code, data snapshots are removed, and main's usage repair is journaled rather than left as a separate upgrade path.

Test Plan

• pnpm --filter @sentry/junior-migrations typecheck
• pnpm --filter @sentry/junior typecheck
• pnpm --filter @sentry/junior-migrations test — 9 tests
• integrated core/plugin/scheduler/history and real-database migration suite — 107 tests
• pnpm lint
• pnpm release:check
• pnpm docs:check
• git diff --check

Garfield adversarial review

Three review cycles addressed strict historical scheduler decoding, malformed existing-row repair, safe migration paths, symlink rejection, final source hash verification, finite JSON progress/result validation, original error preservation, runner-only lock capabilities, dead helper APIs, shared state projection, package version alignment, and stale docs. Independent verification confirmed the validated fixes are committed in this PR.

Final framework guarantees

• migration-helpers/v1 is a permanent compatibility path; breaking helper changes require a new versioned path, and shipped migration source hashes remain immutable.
• Plugin TypeScript migrations receive plugin-scoped state by default while historical junior:<plugin>: keys remain available for legacy conversion.
• Schema bootstrap is explicit (mode: "schema-bootstrap" or bootstrapPluginSchemas) and cannot be selected by omission.
• Real PostgreSQL contracts cover failed progress persistence, resume-to-completion, and concurrent journal serialization.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
junior-docs	Ready	Preview	Jul 16, 2026 11:55pm

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 360518a. Configure here.}