ref(migrations): Add a versioned helper boundary

Allow migrations to import append-only infrastructure helpers from @sentry/junior/migration-helpers/v1 while continuing to reject unversioned Junior runtime imports.

Keep one-off Redis transformations and backfill decisions in their journal entries, replace generated capsules for migrations 0004 through 0006 with readable source, and publish explicit helper types without private module references.

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

Author: dcramer

packages/junior-migrations/README.md

@@ -35,7 +35,8 @@ same database adapter drives the journal ledger and is exposed as
 `context.database`, so migration files never own connection or driver setup.
 
 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.
+and unversioned `@sentry/junior` modules. Migrations may import the append-only
+`@sentry/junior/migration-helpers/v1` surface for parsing primitives, adapters,
+stores, and key resolution. One-off migration decisions and data transforms
+must still remain in the journal entry. Add a new helper or capability version
+rather than changing an existing contract.

packages/junior-migrations/src/journal.ts

@@ -51,6 +51,9 @@ async function optionalFile(path: string): Promise<string | undefined> {
 }
 
 function validateTypeScriptSource(tag: string, source: string): void {
+  const allowedRuntimeImports = new Set([
+    "@sentry/junior/migration-helpers/v1",
+  ]);
   const imports = source.matchAll(
     /^\s*import\s+([^;]+?)\s+from\s+["']([^"']+)["'];?/gm,
   );
@@ -65,8 +68,9 @@ function validateTypeScriptSource(tag: string, source: string): void {
       specifier.startsWith(".") ||
       specifier.startsWith("/") ||
       specifier.startsWith("@/") ||
-      specifier === "@sentry/junior" ||
-      specifier.startsWith("@sentry/junior/")
+      ((specifier === "@sentry/junior" ||
+        specifier.startsWith("@sentry/junior/")) &&
+        !allowedRuntimeImports.has(specifier))
     ) {
       throw new Error(
         `TypeScript migration ${tag} cannot import application runtime code`,

packages/junior-migrations/src/types.ts

@@ -31,8 +31,8 @@ export interface MigrationStateV1 {
   ): Promise<void>;
   connect(): Promise<void>;
   delete(key: string): Promise<void>;
-  get(key: string): Promise<unknown | undefined>;
-  getList(key: string): Promise<unknown[]>;
+  get<T = unknown>(key: string): Promise<T | null | undefined>;
+  getList<T = unknown>(key: string): Promise<T[]>;
   releaseLock(lock: MigrationLockV1): Promise<void>;
   set(key: string, value: unknown, ttlMs?: number): Promise<void>;
   setIfNotExists(key: string, value: unknown, ttlMs?: number): Promise<boolean>;

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

@@ -62,6 +62,18 @@ describe("resolveMigrations", () => {
     );
   });
 
+  it("allows versioned Junior migration helpers", async () => {
+    const folder = await migrationFolder(["0000_helpers"]);
+    await writeFile(
+      join(folder, "0000_helpers.ts"),
+      'import { isRecord } from "@sentry/junior/migration-helpers/v1";\nexport default { apiVersion: 1, async up() { isRecord({}); } };\n',
+    );
+
+    await expect(resolveMigrations(folder)).resolves.toMatchObject([
+      { kind: "typescript", tag: "0000_helpers" },
+    ]);
+  });
+
   it("rejects ambiguous migration files", async () => {
     const folder = await migrationFolder(["0000_ambiguous"]);
     await writeFile(join(folder, "0000_ambiguous.sql"), "SELECT 1;");

packages/junior/migrations/0004_agent_turn_session_actor.ts

@@ -1,78 +1,81 @@
-// @ts-nocheck -- frozen migration capsule; do not refactor against current Junior internals.
-/* eslint-disable no-unused-vars */
-
-// packages/junior/src/cli/upgrade/migrations/agent-turn-session-actor.ts
 import { THREAD_STATE_TTL_MS } from "chat";
+import type {
+  MigrationRedisV1,
+  MigrationStateV1,
+  MigrationV1,
+} from "@sentry/junior-migrations";
+import {
+  isRecord,
+  migrationRedisKey,
+  toOptionalString,
+} from "@sentry/junior/migration-helpers/v1";
 
-// packages/junior/src/chat/coerce.ts
-function toOptionalString(value) {
-  return typeof value === "string" && value.trim() ? value : void 0;
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null;
-}
+type StateAdapter = MigrationStateV1;
+type RedisStateAdapter = { getClient(): MigrationRedisV1 };
+type MigrationContext = {
+  io?: { info(message: string): void };
+  redisStateAdapter?: RedisStateAdapter;
+  stateAdapter: StateAdapter;
+};
+type MigrationResult = {
+  existing: number;
+  migrated: number;
+  missing: number;
+  scanned: number;
+};
 
-// migration:config
-function getChatConfig() {
-  const databaseUrl = process.env.DATABASE_URL;
-  if (!databaseUrl) throw new Error("DATABASE_URL is required");
-  const configured = process.env.JUNIOR_DATABASE_DRIVER;
-  const url = new URL(databaseUrl);
-  const driver =
-    configured === "postgres" || configured === "neon"
-      ? configured
-      : url.hostname === "localhost" || url.hostname === "127.0.0.1"
-        ? "postgres"
-        : "neon";
-  return {
-    bot: { modelContextWindowTokens: void 0 },
-    sql: { databaseUrl, driver },
-    state: {
-      keyPrefix: process.env.JUNIOR_STATE_KEY_PREFIX?.trim() || void 0,
-      adapter: process.env.REDIS_URL ? "redis" : "memory",
-      redisUrl: process.env.REDIS_URL,
-    },
-  };
+const AGENT_TURN_SESSION_PREFIX = "junior:agent_turn_session";
+const AGENT_TURN_SESSION_INDEX_KEY = `${AGENT_TURN_SESSION_PREFIX}:index`;
+const AGENT_TURN_SESSION_INDEX_MAX_LENGTH = 5_000;
+const REDIS_SCAN_COUNT = 500;
+
+type RedisCommandClient = {
+  sendCommand<T = unknown>(args: readonly string[]): Promise<T>;
+};
+
+interface MigratedValue {
+  changed: boolean;
+  value: unknown;
 }
 
-// packages/junior/src/cli/upgrade/migrations/agent-turn-session-actor.ts
-var AGENT_TURN_SESSION_PREFIX = "junior:agent_turn_session";
-var AGENT_TURN_SESSION_INDEX_KEY = `${AGENT_TURN_SESSION_PREFIX}:index`;
-var AGENT_TURN_SESSION_INDEX_MAX_LENGTH = 5e3;
-var REDIS_SCAN_COUNT = 500;
-function conversationIndexKey(conversationId) {
+function conversationIndexKey(conversationId: string): string {
   return `${AGENT_TURN_SESSION_PREFIX}:conversation:${conversationId}:index`;
 }
-function sessionRecordKey(conversationId, sessionId) {
+
+function sessionRecordKey(conversationId: string, sessionId: string): string {
   return `${AGENT_TURN_SESSION_PREFIX}:${conversationId}:${sessionId}`;
 }
-function logicalConversationIndexPrefix() {
-  const prefix = getChatConfig().state.keyPrefix;
-  return [
-    ...(prefix ? [prefix] : []),
-    `${AGENT_TURN_SESSION_PREFIX}:conversation:`,
-  ].join(":");
+
+function logicalConversationIndexPrefix(): string {
+  return migrationRedisKey(`${AGENT_TURN_SESSION_PREFIX}:conversation:`);
 }
-function conversationIdFromRedisListKey(key) {
+
+function conversationIdFromRedisListKey(key: string): string | undefined {
   const marker = `:list:${logicalConversationIndexPrefix()}`;
   const markerIndex = key.indexOf(marker);
   if (markerIndex < 0 || !key.endsWith(":index")) {
-    return void 0;
+    return undefined;
   }
   return toOptionalString(
     key.slice(markerIndex + marker.length, -":index".length),
   );
 }
-async function discoverRedisConversationIds(redisStateAdapter) {
-  const client = redisStateAdapter?.getClient();
+
+async function discoverRedisConversationIds(
+  redisStateAdapter: RedisStateAdapter | undefined,
+): Promise<string[]> {
+  const client = redisStateAdapter?.getClient() as
+    | RedisCommandClient
+    | undefined;
   if (!client) {
     return [];
   }
-  const conversationIds = /* @__PURE__ */ new Set();
+
+  const conversationIds = new Set<string>();
   const match = `*:list:${logicalConversationIndexPrefix()}*:index`;
   let cursor = "0";
   do {
-    const reply = await client.sendCommand([
+    const reply = await client.sendCommand<unknown>([
       "SCAN",
       cursor,
       "MATCH",
@@ -101,41 +104,55 @@ async function discoverRedisConversationIds(redisStateAdapter) {
       }
     }
   } while (cursor !== "0");
+
   return [...conversationIds];
 }
-function migrateRequesterToActor(value) {
-  if (!isRecord(value) || value.requester === void 0) {
+
+function migrateRequesterToActor(value: unknown): MigratedValue {
+  if (!isRecord(value) || value.requester === undefined) {
     return { changed: false, value };
   }
+
   const { requester, ...record } = value;
   return {
     changed: true,
     value: {
       ...record,
-      ...(record.actor === void 0 ? { actor: requester } : {}),
+      ...(record.actor === undefined ? { actor: requester } : {}),
     },
   };
 }
-async function rewriteList(args) {
+
+async function rewriteList(args: {
+  key: string;
+  maxLength?: number;
+  stateAdapter: StateAdapter;
+}): Promise<{ migrated: number; values: unknown[] }> {
   const values = await args.stateAdapter.getList(args.key);
   const migrated = values.map(migrateRequesterToActor);
   const changed = migrated.filter((entry) => entry.changed).length;
   if (changed === 0) {
     return { migrated: 0, values };
   }
+
   await args.stateAdapter.delete(args.key);
   for (const entry of migrated) {
     await args.stateAdapter.appendToList(args.key, entry.value, {
-      ...(args.maxLength !== void 0 ? { maxLength: args.maxLength } : {}),
+      ...(args.maxLength !== undefined ? { maxLength: args.maxLength } : {}),
       ttlMs: THREAD_STATE_TTL_MS,
     });
   }
   return { migrated: changed, values: migrated.map((entry) => entry.value) };
 }
-async function migrateSessionRecord(args) {
+
+async function migrateSessionRecord(args: {
+  conversationId: string;
+  sessionId: string;
+  stateAdapter: StateAdapter;
+}): Promise<"existing" | "migrated" | "missing"> {
   const key = sessionRecordKey(args.conversationId, args.sessionId);
-  const existing = await args.stateAdapter.get(key);
-  if (existing === void 0) {
+  const existing = await args.stateAdapter.get<unknown>(key);
+  if (existing === undefined) {
     return "missing";
   }
   const migrated = migrateRequesterToActor(existing);
@@ -145,8 +162,12 @@ async function migrateSessionRecord(args) {
   await args.stateAdapter.set(key, migrated.value, THREAD_STATE_TTL_MS);
   return "migrated";
 }
-async function migrateAgentTurnSessionActor(context) {
-  const result = {
+
+/** Rewrite retained turn-session requester fields to actor fields. */
+export async function migrateAgentTurnSessionActor(
+  context: MigrationContext,
+): Promise<MigrationResult> {
+  const result: MigrationResult = {
     existing: 0,
     migrated: 0,
     missing: 0,
@@ -159,8 +180,9 @@ async function migrateAgentTurnSessionActor(context) {
   });
   result.scanned += global.values.length;
   result.migrated += global.migrated;
-  const conversations = /* @__PURE__ */ new Set();
-  const sessions = /* @__PURE__ */ new Set();
+
+  const conversations = new Set<string>();
+  const sessions = new Set<string>();
   for (const conversationId of await discoverRedisConversationIds(
     context.redisStateAdapter,
   )) {
@@ -177,9 +199,10 @@ async function migrateAgentTurnSessionActor(context) {
     }
     conversations.add(conversationId);
     if (sessionId) {
-      sessions.add(`${conversationId}\0${sessionId}`);
+      sessions.add(`${conversationId}\u0000${sessionId}`);
     }
   }
+
   for (const conversationId of conversations) {
     const conversation = await rewriteList({
       key: conversationIndexKey(conversationId),
@@ -193,12 +216,13 @@ async function migrateAgentTurnSessionActor(context) {
       }
       const sessionId = toOptionalString(value.sessionId);
       if (sessionId) {
-        sessions.add(`${conversationId}\0${sessionId}`);
+        sessions.add(`${conversationId}\u0000${sessionId}`);
       }
     }
   }
+
   for (const session of sessions) {
-    const separator = session.indexOf("\0");
+    const separator = session.indexOf("\u0000");
     const conversationId = session.slice(0, separator);
     const sessionId = session.slice(separator + 1);
     result.scanned += 1;
@@ -215,24 +239,20 @@ async function migrateAgentTurnSessionActor(context) {
       result.missing += 1;
     }
   }
+
   return result;
 }
 
-// ../../../../../../private/tmp/0004_agent_turn_session_actor-entry.ts
-var migration = {
+const migration = {
   apiVersion: 1,
   async up(context) {
     return await migrateAgentTurnSessionActor({
       stateAdapter: context.state,
-      redisStateAdapter: context.redis
-        ? { getClient: () => ({ sendCommand: context.redis.sendCommand }) }
-        : void 0,
-      io: { info: context.log },
+      ...(context.redis
+        ? { redisStateAdapter: { getClient: () => context.redis! } }
+        : {}),
     });
   },
-};
-var agent_turn_session_actor_entry_default = migration;
-export {
-  agent_turn_session_actor_entry_default as default,
-  migrateAgentTurnSessionActor,
-};
+} satisfies MigrationV1;
+
+export default migration;