fix(migrations): Embed durable migration implementations

Remove the migration task registry and keep historical data migration code in each journal entry. This prevents future runtime refactors or deletions from breaking pending upgrades.

Expose versioned migration capabilities, move scheduler and core backfills into their migration files, and update migration tests and documentation.

Co-Authored-By: GPT-5.6 Codex <noreply@openai.com>

Author: dcramer

packages/junior-migrations/README.md

@@ -6,11 +6,9 @@ migrations. Every journal entry resolves to exactly one `<tag>.sql` or
 the Junior migration runner owns execution and exact per-entry tracking.
 
 TypeScript migrations target a versioned capability API and must not import
-Junior runtime internals. New parsers and transforms belong in the migration
-file so application refactors cannot break pending upgrades. A journal can
-also invoke a versioned host task when adopting legacy migration code that
-already shipped before the mixed journal existed; the task name then becomes
-part of the permanent migration ABI.
+Junior runtime internals. Every parser, transform, and migration-specific
+helper belongs permanently in the migration file so application refactors or
+deletions cannot break pending upgrades.
 
 ## Authoring
 
@@ -34,6 +32,8 @@ Drizzle Kit remains the supported authoring tool. Drizzle ORM's stock
 requires every entry to have a SQL file. Call `runMigrationJournal` instead and
 provide the SQL, state, loader, and locking capabilities owned by the host.
 
-The runner validates that each TypeScript migration has no runtime imports.
-Only a type-only import from `@sentry/junior-migrations` is accepted. Add a new
-API version rather than changing an existing migration capability contract.
+The runner rejects runtime imports of application source, relative modules,
+and `@sentry/junior`. External package imports are allowed when the migration
+needs a stable library dependency; migration-specific implementation must
+still remain in the migration file. Add a new API version rather than changing
+an existing migration capability contract.

packages/junior-migrations/src/index.ts

@@ -7,11 +7,12 @@ export type {
   MigrationContextV1,
   MigrationJsonValue,
   MigrationJournalEntry,
+  MigrationLockV1,
   MigrationProgressV1,
+  MigrationRedisV1,
   MigrationRunResult,
   MigrationSqlExecutor,
   MigrationStateV1,
-  MigrationTasksV1,
   MigrationV1,
   ResolvedMigration,
   TypeScriptMigrationLoader,

packages/junior-migrations/src/journal.ts

@@ -57,18 +57,25 @@ function validateTypeScriptSource(tag: string, source: string): void {
   for (const match of imports) {
     const clause = match[1]?.trim();
     const specifier = match[2];
+    if (clause?.startsWith("type ")) {
+      continue;
+    }
     if (
-      !clause?.startsWith("type ") ||
-      specifier !== "@sentry/junior-migrations"
+      !specifier ||
+      specifier.startsWith(".") ||
+      specifier.startsWith("/") ||
+      specifier.startsWith("@/") ||
+      specifier === "@sentry/junior" ||
+      specifier.startsWith("@sentry/junior/")
     ) {
       throw new Error(
-        `TypeScript migration ${tag} may only import migration types`,
+        `TypeScript migration ${tag} cannot import application runtime code`,
       );
     }
   }
   if (
     /^\s*import\s*["']/m.test(source) ||
-    /^\s*export\s+.+\s+from\s+["']/m.test(source) ||
+    /^\s*export\s+.+\s+from\s+["'][./]/m.test(source) ||
     /\b(?:import\s*\(|require\s*\()/.test(source)
   ) {
     throw new Error(`TypeScript migration ${tag} cannot load runtime modules`);

packages/junior-migrations/src/types.ts

@@ -12,17 +12,33 @@ export interface MigrationSqlExecutor {
   ): Promise<T>;
 }
 
+/** Stable state-store capabilities exposed to v1 TypeScript migrations. */
+export interface MigrationLockV1 {
+  expiresAt: number;
+  threadId: string;
+  token: string;
+}
+
 /** Stable state-store capabilities exposed to v1 TypeScript migrations. */
 export interface MigrationStateV1 {
+  acquireLock(threadId: string, ttlMs: number): Promise<MigrationLockV1 | null>;
   appendToList(
     key: string,
     value: unknown,
     options?: { maxLength?: number; ttlMs?: number },
   ): Promise<void>;
+  connect(): Promise<void>;
   delete(key: string): Promise<void>;
   get(key: string): Promise<unknown | undefined>;
   getList(key: string): Promise<unknown[]>;
+  releaseLock(lock: MigrationLockV1): Promise<void>;
   set(key: string, value: unknown, ttlMs?: number): Promise<void>;
+  setIfNotExists(key: string, value: unknown, ttlMs?: number): Promise<boolean>;
+}
+
+/** Optional raw Redis capability for migrations preserving Redis indexes. */
+export interface MigrationRedisV1 {
+  sendCommand<T = unknown>(args: readonly string[]): Promise<T>;
 }
 
 /** Resumable progress storage scoped to one TypeScript migration. */
@@ -31,11 +47,6 @@ export interface MigrationProgressV1 {
   save(value: MigrationJsonValue): Promise<void>;
 }
 
-/** Versioned host tasks available to migrations that predate the public ABI. */
-export interface MigrationTasksV1 {
-  run(name: string): Promise<MigrationJsonValue | undefined>;
-}
-
 /** JSON-compatible value persisted in migration progress and result columns. */
 export type MigrationJsonValue =
   | boolean
@@ -49,9 +60,11 @@ export type MigrationJsonValue =
 export interface MigrationContextV1 {
   log(message: string): void;
   progress: MigrationProgressV1;
-  sql: Pick<MigrationSqlExecutor, "execute" | "query" | "transaction">;
+  redis?: MigrationRedisV1;
+  sql: Pick<MigrationSqlExecutor, "execute" | "query" | "transaction"> & {
+    db(): unknown;
+  };
   state: MigrationStateV1;
-  tasks: MigrationTasksV1;
 }
 
 /** Isolated TypeScript data migration targeting the v1 ABI. */

packages/junior-migrations/tests/journal.test.ts

@@ -58,7 +58,7 @@ describe("resolveMigrations", () => {
     );
 
     await expect(resolveMigrations(folder)).rejects.toThrow(
-      "may only import migration types",
+      "cannot import application runtime code",
     );
   });
 

packages/junior-migrations/tests/runner.test.ts

@@ -20,6 +20,10 @@ class FakeExecutor implements MigrationSqlExecutor {
   readonly rows = new Map<number, StoredRow>();
   readonly statements: string[] = [];
 
+  db(): undefined {
+    return undefined;
+  }
+
   async execute(statement: string, parameters: readonly unknown[] = []) {
     const normalized = statement.trim();
     if (
@@ -87,6 +91,20 @@ class FakeExecutor implements MigrationSqlExecutor {
   }
 }
 
+function fakeMigrationState(): MigrationContextV1["state"] {
+  return {
+    acquireLock: async () => null,
+    appendToList: async () => {},
+    connect: async () => {},
+    delete: async () => {},
+    get: async () => undefined,
+    getList: async () => [],
+    releaseLock: async () => {},
+    set: async () => {},
+    setIfNotExists: async () => true,
+  };
+}
+
 const temporaryDirectories: string[] = [];
 
 async function mixedFolder(): Promise<string> {
@@ -149,16 +167,7 @@ describe("runMigrationJournal", () => {
           log: () => {},
           progress,
           sql: executor,
-          state: {
-            appendToList: async () => {},
-            delete: async () => {},
-            get: async () => undefined,
-            getList: async () => [],
-            set: async () => {},
-          },
-          tasks: {
-            run: async () => undefined,
-          },
+          state: fakeMigrationState(),
         }),
       }),
     ).resolves.toEqual({ existing: 0, migrated: 3, scanned: 3, skipped: 0 });
@@ -178,16 +187,7 @@ describe("runMigrationJournal", () => {
           log: () => {},
           progress,
           sql: executor,
-          state: {
-            appendToList: async () => {},
-            delete: async () => {},
-            get: async () => undefined,
-            getList: async () => [],
-            set: async () => {},
-          },
-          tasks: {
-            run: async () => undefined,
-          },
+          state: fakeMigrationState(),
         }),
       }),
     ).resolves.toEqual({ existing: 3, migrated: 0, scanned: 3, skipped: 0 });
@@ -237,16 +237,7 @@ describe("runMigrationJournal", () => {
         log: () => {},
         progress,
         sql: executor,
-        state: {
-          appendToList: async () => {},
-          delete: async () => {},
-          get: async () => undefined,
-          getList: async () => [],
-          set: async () => {},
-        },
-        tasks: {
-          run: async () => undefined,
-        },
+        state: fakeMigrationState(),
       }),
     };
 

packages/junior-plugin-api/README.md

@@ -5,14 +5,13 @@ exported TypeScript types and runtime validators are authoritative.
 
 ## Registration
 
-Use `defineJuniorPlugin({ manifest, hooks, tasks, migrationTasks, cli, model })`.
+Use `defineJuniorPlugin({ manifest, hooks, tasks, cli, model })`.
 A plugin name is a lowercase identifier and is unique within the enabled app
 plugin set.
 
 A plugin may instead be a declarative `plugin.yaml` package when it has no
-host-executed hooks, tasks, migration tasks, CLI, or model implementation. Do
-not combine an inline manifest with a second YAML definition for the same
-plugin.
+host-executed hooks, tasks, CLI, or model implementation. Do not combine an
+inline manifest with a second YAML definition for the same plugin.
 
 ## Manifest
 
@@ -60,8 +59,8 @@ reports, and other typed hook surfaces exported by this package.
 
 - Packaged migrations create plugin-owned tables through the host migration
   runner.
-- TypeScript journal entries may invoke explicitly versioned `migrationTasks`;
-  tasks run only when their owning journal entry is pending.
+- TypeScript journal entries contain their complete durable implementation and
+  execute through the versioned migration capability API.
 - Generate migration artifacts from the package schema; do not hand-maintain a
   second schema contract.
 - Runtime hooks and CLI actions use host-provided `ctx.db`.

packages/junior-plugin-api/src/operations.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { PluginContext, PluginLogger } from "./context";
+import type { PluginContext } from "./context";
 import type { Dispatch, DispatchOptions, DispatchResult } from "./dispatch";
 import { nonBlankStringSchema } from "./schemas";
 import type { PluginReadState, PluginState } from "./state";
@@ -47,32 +47,6 @@ export interface HeartbeatResult {
   dispatchCount?: number;
 }
 
-/** Per-record outcome reported by one versioned plugin migration task. */
-export type PluginMigrationResult = {
-  existing: number;
-  migrated: number;
-  missing: number;
-  scanned: number;
-  skipped?: number;
-};
-
-/** Stable host capabilities available to a plugin migration task. */
-export interface PluginMigrationContext {
-  db: unknown;
-  log: PluginLogger;
-  state: PluginState;
-}
-
-/** Idempotent task invoked only by its owning pending journal entry. */
-export interface PluginMigrationTask {
-  (
-    context: PluginMigrationContext,
-  ):
-    | Promise<PluginMigrationResult | undefined>
-    | PluginMigrationResult
-    | undefined;
-}
-
 export type PluginOperationalTone = "danger" | "good" | "neutral" | "warning";
 
 export interface PluginOperationalMetric {

packages/junior-plugin-api/src/registration.ts

@@ -1,7 +1,6 @@
 import type { PluginCliDefinition } from "./cli";
 import type { PluginHooks } from "./hooks";
 import type { PluginManifest } from "./manifest";
-import type { PluginMigrationTask } from "./operations";
 import type { PluginTasks } from "./tasks";
 
 export interface PluginModelConfig {
@@ -15,8 +14,6 @@ export type PluginRegistrationInput = {
   cli?: PluginCliDefinition;
   hooks?: PluginHooks;
   manifest: PluginManifest;
-  /** Permanently versioned data tasks referenced by this plugin's migration journal. */
-  migrationTasks?: Record<string, PluginMigrationTask>;
   model?: PluginModelConfig;
   packageName?: string;
   tasks?: PluginTasks;

packages/junior-scheduler/README.md

@@ -48,8 +48,8 @@ operational reporting. Generate schema changes with
 `pnpm --filter @sentry/junior-scheduler db:generate`.
 Use `pnpm --filter @sentry/junior-scheduler db:generate:data --name <name>`
 for a TypeScript data migration in the same journal. New migrations should use
-the stable migration capabilities directly; the existing scheduler backfill
-uses a versioned task to preserve its pre-journal implementation.
+the stable migration capabilities directly and keep their complete
+implementation in the migration file.
 
 Follow `../../policies/serverless-background-work.md`,
 `../../policies/context-bound-systems.md`, and