@studious-lms/server 1.4.7 → 1.5.0

package/dist/workers/processors/pdfToWorksheet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdfToWorksheet.js","sources":["workers/processors/pdfToWorksheet.ts"],"sourceRoot":"/","sourcesContent":["import { Worker, type Job } from 'bullmq';\nimport { Prisma } from '@prisma/client';\nimport { bullConnection } from '../connection.js';\nimport { prisma } from '../../lib/prisma.js';\nimport { logger } from '../../utils/logger.js';\nimport { pdfToWorksheet } from '../../pipelines/pdfToWorksheet.js';\n\ninterface PdfToWorksheetJobData {\n  runJobId: string;\n  gcsUrl: string;\n  classId: string;\n}\n\nasync function process(job: Job<PdfToWorksheetJobData>) {\n  const { runJobId, gcsUrl, classId } = job.data;\n\n  // If a previous attempt already succeeded for this RunJob (rare race after a\n  // crash that lost the BullMQ ack), return the prior result instead of\n  // re-running the AI call and creating a duplicate worksheet.\n  const existing = await prisma.runJob.findUnique({\n    where: { id: runJobId },\n    select: { status: true, result: true },\n  });\n  if (existing?.status === 'SUCCEEDED') {\n    logger.info('pdfToWorksheet RunJob already succeeded; skipping re-run', {\n      runJobId,\n      bullJobId: job.id,\n    });\n    return existing.result;\n  }\n\n  await prisma.runJob.update({\n    where: { id: runJobId },\n    data: {\n      status: 'RUNNING',\n      startedAt: existing?.status === 'RUNNING' ? undefined : new Date(),\n      attempts: { increment: 1 },\n    },\n  });\n\n  const worksheet = await pdfToWorksheet(gcsUrl, classId);\n\n  const result = worksheet ? { worksheetId: worksheet.id, name: worksheet.name } : null;\n\n  await prisma.runJob.update({\n    where: { id: runJobId },\n    data: {\n      status: 'SUCCEEDED',\n      finishedAt: new Date(),\n      error: null,\n      result: result === null ? Prisma.JsonNull : (result as Prisma.InputJsonValue),\n    },\n  });\n\n  return result;\n}\n\nexport const pdfToWorksheetWorker = new Worker<PdfToWorksheetJobData>(\n  'pdfToWorksheet',\n  process,\n  {\n    connection: bullConnection,\n    // Conservative defaults — tune once we have real-world numbers.\n    concurrency: 2,\n    limiter: {\n      max: 5,\n      duration: 60_000, // 5 jobs / minute, e.g. to stay under OpenAI rate limits\n    },\n  },\n);\n\npdfToWorksheetWorker.on('error', (err) => {\n  logger.error('pdfToWorksheet worker error', {\n    error: err.message,\n    stack: err.stack,\n  });\n});\n\npdfToWorksheetWorker.on('failed', async (job, err) => {\n  if (!job) return;\n\n  const runJobId = job.data?.runJobId;\n  const isFinalAttempt = job.attemptsMade >= (job.opts.attempts ?? 1);\n\n  logger.error('pdfToWorksheet job failed', {\n    bullJobId: job.id,\n    runJobId,\n    attempt: job.attemptsMade,\n    finalAttempt: isFinalAttempt,\n    error: err.message,\n  });\n\n  if (!runJobId) return;\n\n  // Always record the latest error message on the RunJob row.\n  // Only flip to FAILED on the final attempt — earlier failures are still\n  // \"RUNNING\" because BullMQ is going to retry.\n  await prisma.runJob.update({\n    where: { id: runJobId },\n    data: {\n      error: err.message,\n      ...(isFinalAttempt\n        ? { status: 'FAILED', finishedAt: new Date() }\n        : {}),\n    },\n  }).catch((updateError) => {\n    logger.error('Failed to record pdfToWorksheet failure on RunJob', {\n      runJobId,\n      error: updateError instanceof Error ? updateError.message : String(updateError),\n    });\n  });\n});\n\npdfToWorksheetWorker.on('completed', (job) => {\n  logger.info('pdfToWorksheet job completed', {\n    bullJobId: job.id,\n    runJobId: job.data?.runJobId,\n  });\n});\n"],"names":[],"mappings":"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","debug_id":"1b13378b-3952-5f91-b138-a69c3693a56d"}

package/dist/workers/queues.d.ts

@@ -0,0 +1,69 @@
+/**
+ * BullMQ queue producers and the `enqueueRunJob` helper.
+ *
+ * Producer side only — safe to import from HTTP routes / services running on
+ * Vercel. Importing this file does NOT start any workers; workers live in
+ * `src/workers/processors/*` and are wired up by `src/workers/index.ts`,
+ * which is the entrypoint of the separate long-running worker process.
+ */
+import { type JobsOptions } from 'bullmq';
+import { type RunJobType } from '@prisma/client';
+/**
+ * Map RunJobType → (queue name, input payload shape).
+ *
+ * Add a new entry here whenever you introduce a new background job type.
+ * The queue name string must match what the corresponding processor passes
+ * to `new Worker(<name>, ...)`.
+ */
+type JobInputs = {
+    PDF_TO_WORKSHEET: {
+        gcsUrl: string;
+        classId: string;
+    };
+    GRADE_WORKSHEET: {
+        worksheetResponseId: string;
+    };
+    AI_LAB_CHAT: {
+        conversationId: string;
+        messageId: string;
+    };
+    AI_NEWTON_CHAT: {
+        conversationId: string;
+        messageId: string;
+    };
+    STUDENT_PROGRESS_CHAT: {
+        classId: string;
+        studentId: string;
+        message: string;
+    };
+};
+export interface EnqueueOptions {
+    classId?: string | null;
+    userId?: string | null;
+    /** Override BullMQ job options (attempts, delay, priority, etc.). */
+    jobOptions?: JobsOptions;
+}
+export interface EnqueueResult {
+    runJobId: string;
+    bullJobId: string | null;
+}
+/**
+ * Create a `RunJob` audit row, enqueue the BullMQ job, and link the two.
+ *
+ * Returns immediately — the actual work happens on the worker process. The
+ * caller can return `runJobId` to the client and have them poll `getRunJob`
+ * (or subscribe over Pusher) to track progress.
+ *
+ * IMPORTANT: do not call this inside a Prisma `$transaction`. If the outer
+ * transaction rolls back after the BullMQ job is added, the worker will pick
+ * up an orphaned job pointing at a non-existent RunJob row. Enqueue *after*
+ * the transaction commits.
+ */
+export declare function enqueueRunJob<T extends RunJobType>(type: T, input: JobInputs[T], options?: EnqueueOptions): Promise<EnqueueResult>;
+/**
+ * Close every cached queue. Call from the HTTP server's shutdown handler so
+ * the producer side disconnects from Redis cleanly.
+ */
+export declare function closeAllQueues(): Promise<void>;
+export {};
+//# sourceMappingURL=queues.d.ts.map

package/dist/workers/queues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queues.d.ts","sourceRoot":"/","sources":["workers/queues.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAS,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAU,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAYzD;;;;;;GAMG;AACH,KAAK,SAAS,GAAG;IACf,gBAAgB,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,eAAe,EAAE;QAAE,mBAAmB,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,WAAW,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,cAAc,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,qBAAqB,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAChF,CAAC;AA4BF,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,qEAAqE;IACrE,UAAU,CAAC,EAAE,WAAW,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,UAAU,EACtD,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,EACnB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CA2DxB;AAED;;;GAGG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAGpD"}

package/dist/workers/queues.js

@@ -0,0 +1,119 @@
+/**
+ * BullMQ queue producers and the `enqueueRunJob` helper.
+ *
+ * Producer side only — safe to import from HTTP routes / services running on
+ * Vercel. Importing this file does NOT start any workers; workers live in
+ * `src/workers/processors/*` and are wired up by `src/workers/index.ts`,
+ * which is the entrypoint of the separate long-running worker process.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f8634186-ae9e-551f-96ec-058802ec2c99")}catch(e){}}();
+import { Queue } from 'bullmq';
+import { bullConnection } from './connection.js';
+import { prisma } from '../lib/prisma.js';
+import { logger } from '../utils/logger.js';
+const DEFAULT_JOB_OPTIONS = {
+    attempts: 3,
+    backoff: { type: 'exponential', delay: 5000 },
+    removeOnComplete: { age: 60 * 60 }, // keep completed jobs in Redis for 1h, then drop
+    removeOnFail: { age: 24 * 60 * 60 }, // keep failed jobs for 24h for inspection
+};
+const QUEUE_NAMES = {
+    PDF_TO_WORKSHEET: 'pdfToWorksheet',
+    GRADE_WORKSHEET: 'gradeWorksheet',
+    AI_LAB_CHAT: 'aiLabChat',
+    AI_NEWTON_CHAT: 'aiNewtonChat',
+    STUDENT_PROGRESS_CHAT: 'studentProgressChat',
+};
+/**
+ * One Queue instance per type. Created lazily so that importing this module
+ * does not eagerly open queues you may never use in a given runtime.
+ */
+const queueCache = new Map();
+function getQueue(type) {
+    let queue = queueCache.get(type);
+    if (!queue) {
+        queue = new Queue(QUEUE_NAMES[type], {
+            connection: bullConnection,
+            defaultJobOptions: DEFAULT_JOB_OPTIONS,
+        });
+        queueCache.set(type, queue);
+    }
+    return queue;
+}
+/**
+ * Create a `RunJob` audit row, enqueue the BullMQ job, and link the two.
+ *
+ * Returns immediately — the actual work happens on the worker process. The
+ * caller can return `runJobId` to the client and have them poll `getRunJob`
+ * (or subscribe over Pusher) to track progress.
+ *
+ * IMPORTANT: do not call this inside a Prisma `$transaction`. If the outer
+ * transaction rolls back after the BullMQ job is added, the worker will pick
+ * up an orphaned job pointing at a non-existent RunJob row. Enqueue *after*
+ * the transaction commits.
+ */
+export async function enqueueRunJob(type, input, options = {}) {
+    const runJob = await prisma.runJob.create({
+        data: {
+            type,
+            status: 'PENDING',
+            classId: options.classId ?? null,
+            userId: options.userId ?? null,
+            input: input,
+        },
+    });
+    try {
+        const queue = getQueue(type);
+        const job = await queue.add(QUEUE_NAMES[type], { runJobId: runJob.id, ...input }, options.jobOptions);
+        try {
+            await prisma.runJob.update({
+                where: { id: runJob.id },
+                data: { bullJobId: job.id ?? null },
+            });
+        }
+        catch (linkError) {
+            logger.error('RunJob enqueued but bullJobId linkage failed', {
+                runJobId: runJob.id,
+                bullJobId: job.id ?? null,
+                type,
+                error: linkError instanceof Error ? linkError.message : String(linkError),
+            });
+        }
+        return { runJobId: runJob.id, bullJobId: job.id ?? null };
+    }
+    catch (error) {
+        logger.error('Failed to enqueue RunJob; marking FAILED', {
+            runJobId: runJob.id,
+            type,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        try {
+            await prisma.runJob.update({
+                where: { id: runJob.id },
+                data: {
+                    status: 'FAILED',
+                    error: error instanceof Error ? error.message : String(error),
+                    finishedAt: new Date(),
+                },
+            });
+        }
+        catch (updateError) {
+            logger.error('Failed to mark RunJob as FAILED after enqueue error', {
+                runJobId: runJob.id,
+                error: updateError instanceof Error ? updateError.message : String(updateError),
+            });
+        }
+        throw error;
+    }
+}
+/**
+ * Close every cached queue. Call from the HTTP server's shutdown handler so
+ * the producer side disconnects from Redis cleanly.
+ */
+export async function closeAllQueues() {
+    await Promise.all(Array.from(queueCache.values()).map((q) => q.close()));
+    queueCache.clear();
+}
+//# sourceMappingURL=queues.js.map
+//# debugId=f8634186-ae9e-551f-96ec-058802ec2c99

package/dist/workers/queues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queues.js","sources":["workers/queues.ts"],"sourceRoot":"/","sourcesContent":["/**\n * BullMQ queue producers and the `enqueueRunJob` helper.\n *\n * Producer side only — safe to import from HTTP routes / services running on\n * Vercel. Importing this file does NOT start any workers; workers live in\n * `src/workers/processors/*` and are wired up by `src/workers/index.ts`,\n * which is the entrypoint of the separate long-running worker process.\n */\nimport { Queue, type JobsOptions } from 'bullmq';\nimport { Prisma, type RunJobType } from '@prisma/client';\nimport { bullConnection } from './connection.js';\nimport { prisma } from '../lib/prisma.js';\nimport { logger } from '../utils/logger.js';\n\nconst DEFAULT_JOB_OPTIONS: JobsOptions = {\n  attempts: 3,\n  backoff: { type: 'exponential', delay: 5_000 },\n  removeOnComplete: { age: 60 * 60 }, // keep completed jobs in Redis for 1h, then drop\n  removeOnFail: { age: 24 * 60 * 60 }, // keep failed jobs for 24h for inspection\n};\n\n/**\n * Map RunJobType → (queue name, input payload shape).\n *\n * Add a new entry here whenever you introduce a new background job type.\n * The queue name string must match what the corresponding processor passes\n * to `new Worker(<name>, ...)`.\n */\ntype JobInputs = {\n  PDF_TO_WORKSHEET: { gcsUrl: string; classId: string };\n  GRADE_WORKSHEET: { worksheetResponseId: string };\n  AI_LAB_CHAT: { conversationId: string; messageId: string };\n  AI_NEWTON_CHAT: { conversationId: string; messageId: string };\n  STUDENT_PROGRESS_CHAT: { classId: string; studentId: string; message: string };\n};\n\nconst QUEUE_NAMES: Record<RunJobType, string> = {\n  PDF_TO_WORKSHEET: 'pdfToWorksheet',\n  GRADE_WORKSHEET: 'gradeWorksheet',\n  AI_LAB_CHAT: 'aiLabChat',\n  AI_NEWTON_CHAT: 'aiNewtonChat',\n  STUDENT_PROGRESS_CHAT: 'studentProgressChat',\n};\n\n/**\n * One Queue instance per type. Created lazily so that importing this module\n * does not eagerly open queues you may never use in a given runtime.\n */\nconst queueCache = new Map<RunJobType, Queue>();\n\nfunction getQueue(type: RunJobType): Queue {\n  let queue = queueCache.get(type);\n  if (!queue) {\n    queue = new Queue(QUEUE_NAMES[type], {\n      connection: bullConnection,\n      defaultJobOptions: DEFAULT_JOB_OPTIONS,\n    });\n    queueCache.set(type, queue);\n  }\n  return queue;\n}\n\nexport interface EnqueueOptions {\n  classId?: string | null;\n  userId?: string | null;\n  /** Override BullMQ job options (attempts, delay, priority, etc.). */\n  jobOptions?: JobsOptions;\n}\n\nexport interface EnqueueResult {\n  runJobId: string;\n  bullJobId: string | null;\n}\n\n/**\n * Create a `RunJob` audit row, enqueue the BullMQ job, and link the two.\n *\n * Returns immediately — the actual work happens on the worker process. The\n * caller can return `runJobId` to the client and have them poll `getRunJob`\n * (or subscribe over Pusher) to track progress.\n *\n * IMPORTANT: do not call this inside a Prisma `$transaction`. If the outer\n * transaction rolls back after the BullMQ job is added, the worker will pick\n * up an orphaned job pointing at a non-existent RunJob row. Enqueue *after*\n * the transaction commits.\n */\nexport async function enqueueRunJob<T extends RunJobType>(\n  type: T,\n  input: JobInputs[T],\n  options: EnqueueOptions = {},\n): Promise<EnqueueResult> {\n  const runJob = await prisma.runJob.create({\n    data: {\n      type,\n      status: 'PENDING',\n      classId: options.classId ?? null,\n      userId: options.userId ?? null,\n      input: input as unknown as Prisma.InputJsonValue,\n    },\n  });\n\n  try {\n    const queue = getQueue(type);\n    const job = await queue.add(\n      QUEUE_NAMES[type],\n      { runJobId: runJob.id, ...input },\n      options.jobOptions,\n    );\n\n    try {\n      await prisma.runJob.update({\n        where: { id: runJob.id },\n        data: { bullJobId: job.id ?? null },\n      });\n    } catch (linkError) {\n      logger.error('RunJob enqueued but bullJobId linkage failed', {\n        runJobId: runJob.id,\n        bullJobId: job.id ?? null,\n        type,\n        error: linkError instanceof Error ? linkError.message : String(linkError),\n      });\n    }\n\n    return { runJobId: runJob.id, bullJobId: job.id ?? null };\n  } catch (error) {\n    logger.error('Failed to enqueue RunJob; marking FAILED', {\n      runJobId: runJob.id,\n      type,\n      error: error instanceof Error ? error.message : String(error),\n    });\n\n    try {\n      await prisma.runJob.update({\n        where: { id: runJob.id },\n        data: {\n          status: 'FAILED',\n          error: error instanceof Error ? error.message : String(error),\n          finishedAt: new Date(),\n        },\n      });\n    } catch (updateError) {\n      logger.error('Failed to mark RunJob as FAILED after enqueue error', {\n        runJobId: runJob.id,\n        error: updateError instanceof Error ? updateError.message : String(updateError),\n      });\n    }\n\n    throw error;\n  }\n}\n\n/**\n * Close every cached queue. Call from the HTTP server's shutdown handler so\n * the producer side disconnects from Redis cleanly.\n */\nexport async function closeAllQueues(): Promise<void> {\n  await Promise.all(Array.from(queueCache.values()).map((q) => q.close()));\n  queueCache.clear();\n}\n"],"names":[],"mappings":"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","debug_id":"f8634186-ae9e-551f-96ec-058802ec2c99"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studious-lms/server",
-  "version": "1.4.7",
+  "version": "1.5.0",
   "description": "Backend server for Studious application",
   "main": "dist/exportType.js",
   "types": "dist/exportType.d.ts",
@@ -13,8 +13,10 @@
   },
   "scripts": {
     "dev": "tsx watch src/index.ts",
+    "dev:worker": "tsx watch src/workers/index.ts",
     "build": "tsc && npm run sentry:sourcemaps",
     "start": "node dist/index.js",
+    "start:worker": "node dist/workers/index.js",
     "generate": "npx prisma generate",
     "prepublishOnly": "npm run generate && npm run build",
     "test:pre": "NODE_ENV=test tsx scripts/test-pre-push.ts",
@@ -35,6 +37,7 @@
     "@trpc/server": "^11.4.3",
     "@unkey/ratelimit": "^2.1.3",
     "bcryptjs": "^3.0.2",
+    "bullmq": "^5.76.6",
     "compression": "^1.8.1",
     "cors": "^2.8.5",
     "date-fns": "^4.1.0",

package/prisma/migrations/20260504071500_school_memberships/migration.sql

@@ -40,7 +40,7 @@ CREATE TABLE "SchoolInvite" (
 
 INSERT INTO "SchoolMembership" ("id", "schoolId", "userId", "role", "status", "createdAt", "updatedAt")
 SELECT
-  "id",
+  gen_random_uuid()::text,
   "schoolId",
   "id",
   CASE

package/prisma/migrations/20260506162500_consolidate_run_job_and_unify_job_status/migration.sql

@@ -0,0 +1,166 @@
+-- Consolidate background-job tracking onto RunJob and unify domain status.
+--
+-- 1. Replace the bare-bones RunJob table with a fully-typed audit row that
+--    carries job type, status, input/result, error, attempts, timestamps.
+-- 2. Replace the catch-all GenerationStatus enum with a single shared
+--    JobStatus enum used by every domain row that has a user-observable
+--    async lifecycle (Message, StudentQuestionProgress).
+-- 3. Add a nullable runJobId FK on Message and StudentQuestionProgress so we
+--    can trace a domain row back to the job that produced it. Operational
+--    state (retries, errors, attempts) lives on RunJob, not on the row.
+-- 4. Drop the unused Comment.status column.
+
+-- ---------------------------------------------------------------------------
+-- 1. New enum types
+-- ---------------------------------------------------------------------------
+
+CREATE TYPE "RunJobType" AS ENUM (
+  'PDF_TO_WORKSHEET',
+  'GRADE_WORKSHEET',
+  'AI_LAB_CHAT',
+  'AI_NEWTON_CHAT',
+  'STUDENT_PROGRESS_CHAT'
+);
+
+-- Queue-internal lifecycle. Distinct from JobStatus because PENDING (queued
+-- but not picked up) vs RUNNING (worker actively executing) is a real
+-- operational distinction we want when debugging.
+CREATE TYPE "RunJobStatus" AS ENUM (
+  'PENDING',
+  'RUNNING',
+  'SUCCEEDED',
+  'FAILED',
+  'CANCELLED'
+);
+
+-- Shared UI-shaped status for domain rows. Not every row uses every value
+-- (e.g. Message never gets NOT_STARTED) but we keep one enum to avoid an
+-- explosion of near-duplicate types.
+CREATE TYPE "JobStatus" AS ENUM (
+  'NOT_STARTED',
+  'PENDING',
+  'COMPLETED',
+  'FAILED',
+  'CANCELLED'
+);
+
+-- ---------------------------------------------------------------------------
+-- 2. Replace the legacy RunJob table.
+--
+-- The previous schema only had `id` and `createdAt`, and was applied via
+-- `prisma db push` (no migration history) — so any rows in it are throwaway.
+-- We DROP IF EXISTS to handle both fresh production DBs and dev DBs that have
+-- the old shape.
+-- ---------------------------------------------------------------------------
+
+DROP TABLE IF EXISTS "RunJob" CASCADE;
+
+CREATE TABLE "RunJob" (
+  "id"         TEXT NOT NULL,
+  "type"       "RunJobType" NOT NULL,
+  "status"     "RunJobStatus" NOT NULL DEFAULT 'PENDING',
+  "classId"    TEXT,
+  "userId"     TEXT,
+  "bullJobId"  TEXT,
+  "input"      JSONB NOT NULL,
+  "result"     JSONB,
+  "error"      TEXT,
+  "attempts"   INTEGER NOT NULL DEFAULT 0,
+  "startedAt"  TIMESTAMP(3),
+  "finishedAt" TIMESTAMP(3),
+  "createdAt"  TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  "updatedAt"  TIMESTAMP(3) NOT NULL,
+
+  CONSTRAINT "RunJob_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX "RunJob_userId_type_status_idx" ON "RunJob"("userId", "type", "status");
+CREATE INDEX "RunJob_classId_status_idx"     ON "RunJob"("classId", "status");
+CREATE INDEX "RunJob_status_createdAt_idx"   ON "RunJob"("status", "createdAt");
+
+-- ---------------------------------------------------------------------------
+-- 2b. Track PDF source URLs on worksheets for idempotent PDF conversion.
+-- ---------------------------------------------------------------------------
+
+ALTER TABLE "Worksheet" ADD COLUMN "sourceUrl" TEXT;
+
+CREATE UNIQUE INDEX "Worksheet_classId_sourceUrl_key"
+  ON "Worksheet"("classId", "sourceUrl");
+
+-- ---------------------------------------------------------------------------
+-- 3. Message.status: GenerationStatus -> JobStatus.
+--
+-- Old enum had NOT_STARTED / PENDING / GENERATING / COMPLETED / FAILED /
+-- CANCELLED. New JobStatus drops GENERATING (never written). The old default
+-- of NOT_STARTED is dropped: a row without an AI lifecycle now has NULL.
+-- GENERATING is mapped to PENDING defensively in case any row carries it.
+-- ---------------------------------------------------------------------------
+
+ALTER TABLE "Message" ALTER COLUMN "status" DROP DEFAULT;
+
+ALTER TABLE "Message"
+  ALTER COLUMN "status" TYPE "JobStatus"
+  USING (
+    CASE "status"::text
+      WHEN 'NOT_STARTED' THEN NULL
+      WHEN 'GENERATING'  THEN 'PENDING'::"JobStatus"
+      WHEN 'PENDING'     THEN 'PENDING'::"JobStatus"
+      WHEN 'COMPLETED'   THEN 'COMPLETED'::"JobStatus"
+      WHEN 'FAILED'      THEN 'FAILED'::"JobStatus"
+      WHEN 'CANCELLED'   THEN 'CANCELLED'::"JobStatus"
+      ELSE NULL
+    END
+  );
+
+-- ---------------------------------------------------------------------------
+-- 4. StudentQuestionProgress.status: GenerationStatus -> JobStatus.
+--
+-- Default kept at NOT_STARTED. GENERATING -> PENDING defensively.
+-- ---------------------------------------------------------------------------
+
+ALTER TABLE "StudentQuestionProgress" ALTER COLUMN "status" DROP DEFAULT;
+
+ALTER TABLE "StudentQuestionProgress"
+  ALTER COLUMN "status" TYPE "JobStatus"
+  USING (
+    CASE "status"::text
+      WHEN 'NOT_STARTED' THEN 'NOT_STARTED'::"JobStatus"
+      WHEN 'PENDING'     THEN 'PENDING'::"JobStatus"
+      WHEN 'GENERATING'  THEN 'PENDING'::"JobStatus"
+      WHEN 'COMPLETED'   THEN 'COMPLETED'::"JobStatus"
+      WHEN 'FAILED'      THEN 'FAILED'::"JobStatus"
+      WHEN 'CANCELLED'   THEN 'CANCELLED'::"JobStatus"
+      ELSE NULL
+    END
+  );
+
+ALTER TABLE "StudentQuestionProgress"
+  ALTER COLUMN "status" SET DEFAULT 'NOT_STARTED';
+
+-- ---------------------------------------------------------------------------
+-- 5. Drop the unused Comment.status column and the legacy enum.
+-- ---------------------------------------------------------------------------
+
+ALTER TABLE "Comment" DROP COLUMN "status";
+
+DROP TYPE "GenerationStatus";
+
+-- ---------------------------------------------------------------------------
+-- 6. Add runJobId FKs and supporting indexes.
+-- ---------------------------------------------------------------------------
+
+ALTER TABLE "Message"
+  ADD COLUMN "runJobId" TEXT,
+  ADD CONSTRAINT "Message_runJobId_fkey"
+    FOREIGN KEY ("runJobId") REFERENCES "RunJob"("id")
+    ON DELETE SET NULL ON UPDATE CASCADE;
+
+CREATE INDEX "Message_runJobId_idx" ON "Message"("runJobId");
+
+ALTER TABLE "StudentQuestionProgress"
+  ADD COLUMN "runJobId" TEXT,
+  ADD CONSTRAINT "StudentQuestionProgress_runJobId_fkey"
+    FOREIGN KEY ("runJobId") REFERENCES "RunJob"("id")
+    ON DELETE SET NULL ON UPDATE CASCADE;
+
+CREATE INDEX "StudentQuestionProgress_runJobId_idx" ON "StudentQuestionProgress"("runJobId");