Deploy legacy receipt and recovery update

src/cron/cleanup-reports.ts

@@ -1,6 +1,6 @@
 import { config } from '../config';
 import { logger } from '../utils/logger';
-import { getExpiredReportJobs, updateJobStatus } from '../db/jobs';
+import { getExpiredReportJobs, updateJobFields } from '../db/jobs';
 import { deleteReportPdf } from '../db/storage';
 import { insertJobEvent } from '../db/events';
 
@@ -8,8 +8,8 @@ import { insertJobEvent } from '../db/events';
  * Periodic cleanup of expired PDF reports.
  * Runs every CLEANUP_INTERVAL minutes.
  *
- * Deletes PDFs from Supabase Storage after output_pdf_expires_at has passed.
- * The storage path is preserved in the DB for audit trail.
+ * Deletes report and Digital Receipt PDFs after their independent expiry time.
+ * Deleted paths remain available in job events for the audit trail.
  */
 export async function runCleanupReportsCron(): Promise<void> {
   const cronLog = logger.child({ cron: 'cleanup-reports' });
@@ -29,18 +29,18 @@ export async function runCleanupReportsCron(): Promise<void> {
     let failed = 0;
 
     for (const job of expiredJobs) {
-      try {
-        if (job.output_pdf_path) {
+      const now = Date.now();
+
+      if (
+        job.output_pdf_path &&
+        job.output_pdf_expires_at &&
+        new Date(job.output_pdf_expires_at).getTime() <= now
+      ) {
+        try {
           await deleteReportPdf(job.output_pdf_path);
           deleted++;
+          await updateJobFields(job.id, { output_pdf_path: null });
 
-          // Clear the PDF path so we don't try to delete again,
-          // but keep the path in the audit trail via job_events
-          await updateJobStatus(job.id, job.status as string, {
-            output_pdf_path: null,
-          });
-
-          // Log the cleanup event
           await insertJobEvent({
             job_id: job.id,
             identity_id: null,
@@ -51,13 +51,42 @@ export async function runCleanupReportsCron(): Promise<void> {
           });
 
           cronLog.info(`Deleted expired report for job ${job.id}`);
+        } catch (err) {
+          failed++;
+          cronLog.error(`Failed to delete report for job ${job.id}`, {
+            error: err instanceof Error ? err.message : String(err),
+            path: job.output_pdf_path,
+          });
+        }
+      }
+
+      if (
+        job.receipt_pdf_path &&
+        job.receipt_pdf_expires_at &&
+        new Date(job.receipt_pdf_expires_at).getTime() <= now
+      ) {
+        try {
+          await deleteReportPdf(job.receipt_pdf_path);
+          deleted++;
+          await updateJobFields(job.id, { receipt_pdf_path: null });
+
+          await insertJobEvent({
+            job_id: job.id,
+            identity_id: null,
+            level: 'info',
+            step: 'receipt_expired_deleted',
+            message: `Digital Receipt deleted after expiry: ${job.receipt_pdf_path}`,
+            metadata: { expired_path: job.receipt_pdf_path },
+          });
+
+          cronLog.info(`Deleted expired Digital Receipt for job ${job.id}`);
+        } catch (err) {
+          failed++;
+          cronLog.error(`Failed to delete Digital Receipt for job ${job.id}`, {
+            error: err instanceof Error ? err.message : String(err),
+            path: job.receipt_pdf_path,
+          });
         }
-      } catch (err) {
-        failed++;
-        cronLog.error(`Failed to delete report for job ${job.id}`, {
-          error: err instanceof Error ? err.message : String(err),
-          path: job.output_pdf_path,
-        });
       }
     }
 

src/db/accounts.ts

@@ -182,7 +182,9 @@ export async function claimAvailableAccount(
 /**
  * Claim the exact account that already owns a submitted job.
  * This is used only for post-submit retries where the worker must reopen the
- * same Turnitin report viewer instead of submitting the file again.
+ * same Turnitin report viewer instead of submitting the file again. A
+ * quota_limited account is still valid here because report access does not
+ * consume another submission; explicitly disabled/login_failed rows remain blocked.
  */
 export async function claimSpecificAccountForResume(
   identityId: string,
@@ -200,7 +202,7 @@ export async function claimSpecificAccountForResume(
       updated_at: now,
     })
     .eq('id', identityId)
-    .not('turnitin_status', 'in', '(disabled,login_failed,quota_limited)')
+    .not('turnitin_status', 'in', '(disabled,login_failed)')
     .or(`turnitin_lease_until.is.null,turnitin_lease_until.lte.${now},turnitin_lease_owner.eq.${workerId}`)
     .select('*')
     .maybeSingle();

src/db/jobs.ts

@@ -12,8 +12,11 @@ export interface TurnitinJob {
   input_file_name: string;
   input_file_size: number | null;
   input_file_sha256: string | null;
+  submission_request_id: string | null;
   output_pdf_path: string | null;
   output_pdf_expires_at: string | null;
+  receipt_pdf_path: string | null;
+  receipt_pdf_expires_at: string | null;
   ticket_refunded_at: string | null;
   ticket_refund_reason: string | null;
   viewer_url: string | null;
@@ -78,6 +81,37 @@ export async function updateJobStatus(
   }
 }
 
+/**
+ * Mark a job completed without reviving a job that an administrator or user
+ * already moved to a terminal failed/cancelled state while Playwright was
+ * finishing in the background.
+ */
+export async function completeJobIfActive(
+  jobId: string,
+  fields: Partial<TurnitinJob>,
+): Promise<boolean> {
+  const update: Record<string, unknown> = {
+    ...fields,
+    status: 'completed',
+    updated_at: new Date().toISOString(),
+  };
+
+  const { data, error } = await supabase
+    .from('turnitin_jobs')
+    .update(update)
+    .eq('id', jobId)
+    .not('status', 'in', '(failed,cancelled)')
+    .select('id')
+    .maybeSingle();
+
+  if (error) {
+    logger.error('Failed to complete active job', { jobId, error: error.message });
+    throw error;
+  }
+
+  return Boolean(data);
+}
+
 /**
  * Patch arbitrary job fields without changing status.
  * Used for incremental progress checkpoints so retries can resume safely.
@@ -131,11 +165,14 @@ export async function getJobById(jobId: string): Promise<TurnitinJob | null> {
  * Find jobs whose report PDF has expired and should be cleaned up.
  */
 export async function getExpiredReportJobs(): Promise<TurnitinJob[]> {
+  const now = new Date().toISOString();
   const { data, error } = await supabase
     .from('turnitin_jobs')
     .select('*')
-    .not('output_pdf_path', 'is', null)
-    .lte('output_pdf_expires_at', new Date().toISOString());
+    .or(
+      `and(output_pdf_path.not.is.null,output_pdf_expires_at.lte.${now}),` +
+      `and(receipt_pdf_path.not.is.null,receipt_pdf_expires_at.lte.${now})`,
+    );
 
   if (error) {
     logger.error('Failed to get expired report jobs', { error: error.message });

src/db/storage.ts

@@ -10,18 +10,19 @@ import { logger } from '../utils/logger';
  */
 export async function uploadInputFile(
   userId: string,
-  jobId: string,
+  storageKey: string,
   fileName: string,
   fileBuffer: Buffer,
+  upsert = false,
 ): Promise<string> {
   const ext = path.extname(fileName);
-  const storagePath = `${userId}/${jobId}/input${ext}`;
+  const storagePath = `${userId}/${storageKey}/input${ext}`;
 
   const { error } = await supabase.storage
     .from(config.inputBucket)
     .upload(storagePath, fileBuffer, {
       contentType: getMimeType(ext),
-      upsert: false,
+      upsert,
     });
 
   if (error) {
@@ -84,6 +85,40 @@ export async function uploadReportPdf(
   return { storagePath, expiresAt };
 }
 
+/**
+ * Upload a legacy Turnitin Digital Receipt PDF with the same retention policy
+ * as the similarity report.
+ */
+export async function uploadReceiptPdf(
+  userId: string,
+  jobId: string,
+  localPdfPath: string,
+): Promise<{ storagePath: string; expiresAt: string }> {
+  const storagePath = `${userId}/${jobId}/receipt.pdf`;
+  const fileBuffer = fs.readFileSync(localPdfPath);
+
+  const { error } = await supabase.storage
+    .from(config.reportBucket)
+    .upload(storagePath, fileBuffer, {
+      contentType: 'application/pdf',
+      upsert: true,
+    });
+
+  if (error) {
+    logger.error('Failed to upload Digital Receipt PDF', {
+      storagePath,
+      error: error.message,
+    });
+    throw error;
+  }
+
+  const expiresAt = new Date(
+    Date.now() + config.reportRetentionHours * 60 * 60 * 1000,
+  ).toISOString();
+
+  return { storagePath, expiresAt };
+}
+
 /**
  * Delete a report PDF from Supabase Storage.
  */

src/db/tickets.ts

@@ -1,5 +1,6 @@
 import { supabase } from './client';
 import { logger } from '../utils/logger';
+import type { TurnitinJob } from './jobs';
 
 export interface CreateJobParams {
   userId: string;
@@ -10,6 +11,12 @@ export interface CreateJobParams {
   inputStoragePath: string;
   inputFileSize?: number;
   inputFileSha256?: string;
+  submissionRequestId: string;
+}
+
+export interface CreateJobResult {
+  jobId: string;
+  created: boolean;
 }
 
 export interface UserProfile {
@@ -27,14 +34,17 @@ export interface UserProfile {
  * Uses the database RPC to ensure ticket balance is checked and decremented in one transaction.
  * Returns the new job ID.
  */
-export async function createJobWithTicket(params: CreateJobParams): Promise<string> {
-  const { data, error } = await supabase.rpc('create_job_with_ticket', {
+export async function createJobWithTicket(params: CreateJobParams): Promise<CreateJobResult> {
+  const { data, error } = await supabase.rpc('create_job_with_ticket_idempotent', {
     p_user_id: params.userId,
     p_assignment_target_id: params.assignmentTargetId,
     p_mode: params.mode,
     p_filters: params.filters,
     p_input_file_name: params.inputFileName,
     p_input_file_path: params.inputStoragePath,
+    p_input_file_size: params.inputFileSize ?? null,
+    p_input_file_sha256: params.inputFileSha256 ?? null,
+    p_submission_request_id: params.submissionRequestId,
   });
 
   if (error) {
@@ -42,27 +52,37 @@ export async function createJobWithTicket(params: CreateJobParams): Promise<stri
     throw error;
   }
 
-  const jobId = data as string;
-
-  if (params.inputFileSize != null || params.inputFileSha256) {
-    const { error: updateError } = await supabase
-      .from('turnitin_jobs')
-      .update({
-        input_file_size: params.inputFileSize ?? null,
-        input_file_sha256: params.inputFileSha256 ?? null,
-        updated_at: new Date().toISOString(),
-      })
-      .eq('id', jobId);
-
-    if (updateError) {
-      logger.warn('Created job but could not persist input file fingerprint', {
-        jobId,
-        error: updateError.message,
-      });
-    }
+  const row = Array.isArray(data) ? data[0] : data;
+  if (!row?.job_id) {
+    throw new Error('Idempotent job creation returned no job ID');
+  }
+
+  return {
+    jobId: row.job_id as string,
+    created: row.created === true,
+  };
+}
+
+export async function getJobBySubmissionRequestId(
+  userId: string,
+  submissionRequestId: string,
+): Promise<TurnitinJob | null> {
+  const { data, error } = await supabase
+    .from('turnitin_jobs')
+    .select('*')
+    .eq('user_id', userId)
+    .eq('submission_request_id', submissionRequestId)
+    .maybeSingle();
+
+  if (error) {
+    logger.error('Failed to find job by submission request ID', {
+      userId,
+      error: error.message,
+    });
+    throw error;
   }
 
-  return jobId;
+  return data as TurnitinJob | null;
 }
 
 /**

src/engine/legacy.ts

@@ -1579,12 +1579,45 @@ async function clickLegacyCartaElement(
   return false;
 }
 
+type LegacyDownloadOption = 'current_view' | 'digital_receipt';
+
 async function downloadLegacyPdf(
   page: Page,
   context: BrowserContext,
   outputPath: string,
+  option: LegacyDownloadOption,
 ): Promise<string> {
   let lastError: Error | null = null;
+  const isReceipt = option === 'digital_receipt';
+  const optionLabel = isReceipt ? 'Digital Receipt' : 'Current View';
+  const optionSelectors = isReceipt
+    ? [
+        '[data-px="EVSimReportDownloadDigitalReceipt"]',
+        '[aria-label="Digital Receipt"]',
+        '.print-download-items [role="button"]:has-text("Digital Receipt")',
+        '.print-download-btn:has-text("Digital Receipt")',
+        'button:has-text("Digital Receipt")',
+        'a:has-text("Digital Receipt")',
+        '[role="menuitem"]:has-text("Digital Receipt")',
+      ]
+    : [
+        '[data-px="EVSimReportDownloadCurrentView"]',
+        '[aria-label="Current View"]',
+        '.print-download-items [role="button"]:has-text("Current View")',
+        '.print-download-btn:has-text("Current View")',
+        'button:has-text("Current View")',
+        'a:has-text("Current View")',
+        '[role="menuitem"]:has-text("Current View")',
+      ];
+  const cartaSelectors = isReceipt
+    ? [
+        '[data-px="EVSimReportDownloadDigitalReceipt"]',
+        '[aria-label="Digital Receipt"]',
+      ]
+    : [
+        '[data-px="EVSimReportDownloadCurrentView"]',
+        '[aria-label="Current View"]',
+      ];
 
   for (let attempt = 1; attempt <= 3; attempt++) {
     try {
@@ -1610,24 +1643,17 @@ async function downloadLegacyPdf(
       await page.waitForTimeout(1200);
 
       const downloadPromise = waitForAnyDownload(context, 120000);
-      const selected = await clickFirstVisible(page, [
-        '[data-px="EVSimReportDownloadCurrentView"]',
-        '[aria-label="Current View"]',
-        '.print-download-items [role="button"]:has-text("Current View")',
-        '.print-download-btn:has-text("Current View")',
-        'button:has-text("Current View")',
-        'a:has-text("Current View")',
-        '[role="menuitem"]:has-text("Current View")',
-      ], 8000) || await clickLegacyCartaElement(page, [
-        '[data-px="EVSimReportDownloadCurrentView"]',
-        '[aria-label="Current View"]',
-        '.print-download-items [role="button"]',
-        '.print-download-btn',
-        '.sc-list-item-view',
-      ], ['current view'], 12000);
+      const selected = await clickFirstVisible(page, optionSelectors, 8000) ||
+        await clickLegacyCartaElement(
+          page,
+          cartaSelectors,
+          [optionLabel.toLowerCase()],
+          12000,
+        );
 
       if (!selected) {
-        throw new Error('Legacy Current View download option was not found.');
+        void downloadPromise.catch(() => {});
+        throw new Error(`Legacy ${optionLabel} download option was not found.`);
       }
 
       const download = await downloadPromise;
@@ -1642,6 +1668,7 @@ async function downloadLegacyPdf(
       lastError = error instanceof Error ? error : new Error(String(error));
       logger.warn('Legacy PDF download attempt failed', {
         attempt,
+        option,
         error: lastError.message,
       });
       if (attempt < 3) {
@@ -1651,7 +1678,7 @@ async function downloadLegacyPdf(
     }
   }
 
-  throw lastError || new Error('Legacy PDF download failed.');
+  throw lastError || new Error(`Legacy ${optionLabel} PDF download failed.`);
 }
 
 export async function runLegacyTurnitinJob(
@@ -1698,7 +1725,7 @@ export async function runLegacyTurnitinJob(
 
     const resumeFromViewer =
       resumeAfterStep &&
-      ['viewer', 'filters', 'download'].includes(resumeAfterStep) &&
+      ['viewer', 'filters', 'download', 'receipt'].includes(resumeAfterStep) &&
       resumeViewerUrl;
 
     if (resumeFromViewer) {
@@ -1798,12 +1825,34 @@ export async function runLegacyTurnitinJob(
     await emit(onEvent, 'info', 'download', 'Downloading legacy PDF report');
     fs.mkdirSync(outputDir, { recursive: true });
     const outputPdfPath = path.join(outputDir, `turnitin_legacy_report_${Date.now()}.pdf`);
-    result.outputPdfPath = await downloadLegacyPdf(page, context, outputPdfPath);
+    result.outputPdfPath = await downloadLegacyPdf(
+      page,
+      context,
+      outputPdfPath,
+      'current_view',
+    );
     result.lastCompletedStep = 'download';
     await emit(onEvent, 'info', 'download', 'PDF downloaded successfully', {
       outputPdfPath: result.outputPdfPath,
     });
 
+    // The Carta download modal closes after Current View is selected. Open the
+    // Download panel again and fetch Digital Receipt as a separate PDF.
+    await page.keyboard.press('Escape').catch(() => {});
+    await page.waitForTimeout(500);
+    await emit(onEvent, 'info', 'receipt', 'Downloading legacy Digital Receipt');
+    const receiptPdfPath = path.join(outputDir, `turnitin_legacy_receipt_${Date.now()}.pdf`);
+    result.receiptPdfPath = await downloadLegacyPdf(
+      page,
+      context,
+      receiptPdfPath,
+      'digital_receipt',
+    );
+    result.lastCompletedStep = 'receipt';
+    await emit(onEvent, 'info', 'receipt', 'Digital Receipt downloaded successfully', {
+      receiptPdfPath: result.receiptPdfPath,
+    });
+
     const accountQuotaRemaining =
       typeof input.account.quotaRemaining === 'number'
         ? input.account.quotaRemaining

src/engine/turnitin.ts

@@ -79,6 +79,7 @@ export interface RunTurnitinJobResult {
   viewerUrl?: string;
   similarityPercent?: number;
   outputPdfPath?: string;
+  receiptPdfPath?: string;
   submissionDetails?: SubmissionDetails;
   quotaWarning?: string;
   quotaLimit?: { limit: number; message: string; retryText?: string };

src/server/app.ts

@@ -26,7 +26,7 @@ export function createApp(): Express {
       res.setHeader('Vary', 'Origin');
     }
     res.setHeader('Access-Control-Allow-Methods', 'GET,POST,OPTIONS');
-    res.setHeader('Access-Control-Allow-Headers', 'Authorization,Content-Type,X-Admin-Secret');
+    res.setHeader('Access-Control-Allow-Headers', 'Authorization,Content-Type,Idempotency-Key,X-Admin-Secret');
     res.setHeader('Access-Control-Max-Age', '86400');
     res.setHeader('X-Content-Type-Options', 'nosniff');
     res.setHeader('Referrer-Policy', 'no-referrer');

src/server/routes/reports.ts

@@ -17,6 +17,16 @@ function buildReportDownloadName(inputFileName: string): string {
   return `RelVDev_${base}.pdf`;
 }
 
+function buildReceiptDownloadName(inputFileName: string): string {
+  const base = String(inputFileName || 'receipt')
+    .replace(/\.[^.]+$/, '')
+    .replace(/[\\/:*?"<>|]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 132) || 'receipt';
+  return `RelVDev_Receipt_${base}.pdf`;
+}
+
 /**
  * GET /api/jobs/:jobId/report-url
  *
@@ -83,4 +93,68 @@ router.get(
   },
 );
 
+/**
+ * GET /api/jobs/:jobId/receipt-url
+ *
+ * Creates a short-lived signed URL for a legacy Digital Receipt PDF.
+ */
+router.get(
+  '/api/jobs/:jobId/receipt-url',
+  authenticateUser,
+  async (req, res: Response): Promise<void> => {
+    const authReq = req as AuthenticatedRequest;
+    const jobId = String(authReq.params.jobId || '');
+
+    try {
+      const job = await getJobById(jobId);
+
+      if (!job) {
+        res.status(404).json({ error: 'Job not found' });
+        return;
+      }
+
+      if (job.user_id !== authReq.userId) {
+        res.status(403).json({ error: 'Forbidden' });
+        return;
+      }
+
+      if (!job.receipt_pdf_path) {
+        res.status(404).json({ error: 'Digital Receipt is not available yet' });
+        return;
+      }
+
+      if (
+        job.receipt_pdf_expires_at &&
+        new Date(job.receipt_pdf_expires_at).getTime() < Date.now()
+      ) {
+        res.status(410).json({ error: 'Digital Receipt has expired' });
+        return;
+      }
+
+      const fileName = buildReceiptDownloadName(job.input_file_name);
+      const signedUrl = await createSignedUrl(
+        config.reportBucket,
+        job.receipt_pdf_path,
+        300,
+        fileName,
+      );
+
+      res.json({
+        signedUrl,
+        fileName,
+        expiresIn: 300,
+        expiresAt: new Date(Date.now() + 300 * 1000).toISOString(),
+      });
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.error('Failed to create Digital Receipt signed URL', {
+        jobId,
+        userId: authReq.userId,
+        error: message,
+      });
+      res.status(500).json({ error: 'Failed to create Digital Receipt download URL' });
+    }
+  },
+);
+
 export default router;

src/server/routes/submit.ts

@@ -2,10 +2,13 @@ import { Router, Response } from 'express';
 import multer from 'multer';
 import { authenticateUser, AuthenticatedRequest } from '../middleware/auth';
 import { uploadInputFile } from '../../db/storage';
-import { createJobWithTicket } from '../../db/tickets';
-import { getUserProfile } from '../../db/tickets';
+import {
+  createJobWithTicket,
+  getJobBySubmissionRequestId,
+  getUserProfile,
+} from '../../db/tickets';
 import { logger } from '../../utils/logger';
-import { createHash } from 'crypto';
+import { createHash, randomUUID } from 'crypto';
 
 const router = Router();
 
@@ -29,6 +32,7 @@ const ALLOWED_EXTENSIONS = new Set([
   '.txt',
 ]);
 const ALLOWED_MODES = new Set(['upload', 'resubmit']);
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
 const DEFAULT_FILTERS: Record<string, unknown> = {
   excludeBibliography: false,
@@ -44,6 +48,31 @@ function getFileExtension(filename: string): string {
   return lastDot >= 0 ? filename.slice(lastDot).toLowerCase() : '';
 }
 
+function existingJobMatchesRequest(
+  existingJob: {
+    assignment_target_id: string;
+    mode: string;
+    input_file_name: string;
+    input_file_size: number | null;
+    input_file_sha256: string | null;
+  },
+  request: {
+    assignmentTargetId: string;
+    mode: string;
+    inputFileName: string;
+    inputFileSize: number;
+    inputFileSha256: string;
+  },
+): boolean {
+  return (
+    existingJob.assignment_target_id === request.assignmentTargetId &&
+    existingJob.mode === request.mode &&
+    existingJob.input_file_name === request.inputFileName &&
+    existingJob.input_file_size === request.inputFileSize &&
+    existingJob.input_file_sha256 === request.inputFileSha256
+  );
+}
+
 /**
  * POST /api/submit
  * Accepts a file upload + metadata, validates, stores the file,
@@ -58,7 +87,12 @@ router.post(
 
     try {
       // 1. Validate required fields
-      const { assignment_target_id, mode, filters: filtersRaw } = authReq.body;
+      const {
+        assignment_target_id,
+        mode,
+        filters: filtersRaw,
+        submission_request_id: bodySubmissionRequestId,
+      } = authReq.body;
 
       if (!assignment_target_id || !mode) {
         res.status(400).json({
@@ -74,6 +108,16 @@ router.post(
         return;
       }
 
+      const suppliedRequestId = String(
+        bodySubmissionRequestId || authReq.get('Idempotency-Key') || '',
+      ).trim();
+      const submissionRequestId = suppliedRequestId || randomUUID();
+
+      if (!UUID_PATTERN.test(submissionRequestId)) {
+        res.status(400).json({ error: 'Invalid submission request ID' });
+        return;
+      }
+
       // Parse filters (may come as stringified JSON)
       let filters: Record<string, unknown>;
       try {
@@ -125,22 +169,57 @@ router.post(
         filters.smallMatchThreshold = null;
       }
 
-      // 5. Upload file to Supabase Storage
+      // 5. Fingerprint the payload before any state-changing operation.
       const inputFileSha256 = createHash('sha256')
         .update(authReq.file.buffer)
         .digest('hex');
 
+      const existingJob = await getJobBySubmissionRequestId(
+        authReq.userId,
+        submissionRequestId,
+      );
+
+      if (existingJob) {
+        if (!existingJobMatchesRequest(existingJob, {
+          assignmentTargetId: String(assignment_target_id),
+          mode: String(mode),
+          inputFileName: authReq.file.originalname,
+          inputFileSize: authReq.file.size,
+          inputFileSha256,
+        })) {
+          res.status(409).json({
+            error: 'Submission request ID was already used for a different file or configuration',
+          });
+          return;
+        }
+
+        const profile = await getUserProfile(authReq.userId);
+        logger.info('Idempotent submit replay returned existing job', {
+          jobId: existingJob.id,
+          userId: authReq.userId,
+          submissionRequestId,
+        });
+        res.status(200).json({
+          jobId: existingJob.id,
+          ticketBalance: profile?.ticket_balance ?? 0,
+          idempotentReplay: true,
+        });
+        return;
+      }
+
+      // A deterministic request/hash path makes concurrent retries upload the
+      // same bytes to the same object before the database invariant resolves them.
       const storagePath = await uploadInputFile(
         authReq.userId,
-        // Generate a temp ID for the path — will be replaced with actual job ID
-        // We use a timestamp-based placeholder, then the RPC returns the real job ID
-        Date.now().toString(36),
+        `${submissionRequestId}/${inputFileSha256}`,
         authReq.file.originalname,
         authReq.file.buffer,
+        true,
       );
 
-      // 6. Create job with ticket deduction
-      const jobId = await createJobWithTicket({
+      // 6. Atomically create one job/ticket ledger entry, or return the job
+      // already created by another Space handling this exact request.
+      const creation = await createJobWithTicket({
         userId: authReq.userId,
         assignmentTargetId: assignment_target_id,
         mode,
@@ -149,20 +228,26 @@ router.post(
         inputStoragePath: storagePath,
         inputFileSize: authReq.file.size,
         inputFileSha256,
+        submissionRequestId,
       });
 
       // Fetch updated ticket balance
       const profile = await getUserProfile(authReq.userId);
       const ticketBalance = profile?.ticket_balance ?? 0;
 
-      logger.info('Job submitted successfully', {
-        jobId,
+      logger.info(creation.created ? 'Job submitted successfully' : 'Idempotent submit race resolved', {
+        jobId: creation.jobId,
         userId: authReq.userId,
         fileName: authReq.file.originalname,
+        submissionRequestId,
       });
 
       // 7. Return success
-      res.status(201).json({ jobId, ticketBalance });
+      res.status(creation.created ? 201 : 200).json({
+        jobId: creation.jobId,
+        ticketBalance,
+        idempotentReplay: !creation.created,
+      });
     } catch (err: unknown) {
       const message = err instanceof Error ? err.message : String(err);
 
@@ -172,6 +257,11 @@ router.post(
         return;
       }
 
+      if (message.includes('Idempotency key')) {
+        res.status(409).json({ error: 'Submission request ID conflict' });
+        return;
+      }
+
       logger.error('Submit endpoint error', {
         userId: authReq.userId,
         error: message,

src/worker/manager.ts

@@ -6,18 +6,19 @@ import { getAccountPassword } from '../crypto/password';
 import { supabase } from '../db/client';
 
 // DB imports (will be created by subagent)
-import { claimPendingJob, updateJobStatus, updateJobFields, incrementJobAttempt, getJobById, TurnitinJob } from '../db/jobs';
+import { claimPendingJob, completeJobIfActive, updateJobStatus, updateJobFields, incrementJobAttempt, getJobById, TurnitinJob } from '../db/jobs';
 import {
   claimAvailableAccount,
   claimSpecificAccountForResume,
   countAvailableAccounts,
   getAccountPoolState,
+  getTurnitinAccountById,
   releaseAccount,
   updateAccountQuota,
   type TurnitinAccount,
 } from '../db/accounts';
 import { insertJobEvent } from '../db/events';
-import { downloadInputFile, uploadReportPdf, downloadStorageState, uploadStorageState } from '../db/storage';
+import { downloadInputFile, uploadReceiptPdf, uploadReportPdf, downloadStorageState, uploadStorageState } from '../db/storage';
 import { cancelJob, refundFailedJob } from '../db/tickets';
 import { MODERN_ONE_POOL_KEY, runTurnitinJob, RunTurnitinJobInput, RunTurnitinJobResult } from '../engine/turnitin';
 
@@ -30,7 +31,7 @@ let running = false;
 
 const ACCOUNT_WAIT_POLL_MS = Number(process.env.ACCOUNT_WAIT_POLL_MS || 15000);
 const ACCOUNT_WAIT_MAX_MS = Number(process.env.ACCOUNT_WAIT_MAX_MS || 30 * 60 * 1000);
-const RESUME_PROTECTED_STEPS = ['submitted', 'similarity', 'viewer', 'filters', 'download'];
+const RESUME_PROTECTED_STEPS = ['submitted', 'similarity', 'viewer', 'filters', 'download', 'receipt'];
 const RESUME_ACCOUNT_RETRY_DELAY_MS = Number(process.env.RESUME_ACCOUNT_RETRY_DELAY_MS || 30000);
 const DEFAULT_ACCOUNT_POOL_KEY = 'modern_lti';
 const LEGACY_ACCOUNT_POOL_KEY = 'legacy_carta';
@@ -331,15 +332,6 @@ async function processJob(job: TurnitinJob): Promise<void> {
         RESUME_PROTECTED_STEPS.includes(initialLastCompletedStep) &&
         freshJob.identity_id,
     );
-    const retryShouldPreferPreviousAccount = Boolean(
-      !resumeNeedsSameAccount &&
-        currentAttemptCount > 1 &&
-        freshJob.identity_id &&
-        !isAccountTerminalError(freshJob.error_message),
-    );
-    const shouldClaimPreviousAccount =
-      resumeNeedsSameAccount || retryShouldPreferPreviousAccount;
-
     assignmentTarget = await loadAssignmentTarget(assignmentTargetId, jobLog);
     accountPoolKey =
       assignmentTarget.accountPoolKey ||
@@ -352,15 +344,31 @@ async function processJob(job: TurnitinJob): Promise<void> {
       uiVariant: assignmentTarget.uiVariant,
     });
 
-    const account = shouldClaimPreviousAccount
+    // Before submission, every retry may safely rotate to another account.
+    // Keeping a pre-submit job attached to an account that has since become
+    // quota_limited makes it wait forever even when the pool has free accounts.
+    // Post-submit checkpoints remain pinned to the original account to avoid
+    // uploading the same file again.
+    const account = resumeNeedsSameAccount
       ? await claimSpecificAccountForResume(freshJob.identity_id as string, config.workerId)
       : await claimAccountForJob(job, identityId, jobLog, accountPoolKey);
 
     if (!account) {
-      if (shouldClaimPreviousAccount) {
-        const message = resumeNeedsSameAccount
-          ? 'Previous submission is still locked by its Turnitin account; retrying shortly.'
-          : 'Previous Turnitin account is not ready yet; retrying with the same account before using a new one.';
+      if (resumeNeedsSameAccount) {
+        const previousAccount = await getTurnitinAccountById(
+          freshJob.identity_id as string,
+        ).catch(() => null);
+        if (
+          !previousAccount ||
+          ['disabled', 'login_failed'].includes(previousAccount.turnitin_status)
+        ) {
+          throw new Error(
+            'The Turnitin account that owns the submitted file is no longer available for report recovery.',
+          );
+        }
+
+        const message =
+          'Previous submission is still locked by its Turnitin account; retrying shortly.';
         await updateJobStatus(jobId, 'waiting_account', {
           error_message: message,
           attempt_count: Math.max(0, currentAttemptCount - 1),
@@ -459,7 +467,7 @@ async function processJob(job: TurnitinJob): Promise<void> {
     // again.  The engine's `resumeAfterStep` tells it to skip earlier steps.
     const lastCompletedStep = initialLastCompletedStep;
     const effectiveMode =
-      lastCompletedStep && ['submitted', 'similarity', 'viewer', 'filters', 'download'].includes(lastCompletedStep)
+      lastCompletedStep && ['submitted', 'similarity', 'viewer', 'filters', 'download', 'receipt'].includes(lastCompletedStep)
         ? 'resubmit' as const  // force resubmit because file is already there
         : (job.mode as 'upload' | 'resubmit' | 'quota_check');
 
@@ -563,6 +571,26 @@ async function processJob(job: TurnitinJob): Promise<void> {
       await emitEvent(jobId, identityId, 'info', 'pdf_uploaded', 'PDF report uploaded to storage');
     }
 
+    let receiptPdfPath: string | undefined;
+    let receiptPdfExpiresAt: string | undefined;
+
+    if (result.receiptPdfPath && fs.existsSync(result.receiptPdfPath)) {
+      const uploadResult = await uploadReceiptPdf(
+        job.user_id as string,
+        jobId,
+        result.receiptPdfPath,
+      );
+      receiptPdfPath = uploadResult.storagePath;
+      receiptPdfExpiresAt = uploadResult.expiresAt;
+      await emitEvent(
+        jobId,
+        identityId,
+        'info',
+        'receipt_uploaded',
+        'Digital Receipt uploaded to storage',
+      );
+    }
+
     // Save storage state for session reuse
     try {
       // The engine should have saved the storage state; we read and upload it
@@ -578,15 +606,31 @@ async function processJob(job: TurnitinJob): Promise<void> {
       jobLog.warn('Failed to save storage state');
     }
 
-    // Update job to completed
-    await updateJobStatus(jobId, 'completed', {
+    // An administrator may fail/cancel a job while Playwright is already in
+    // the viewer. Persist completion only if the job is still active so an
+    // in-flight callback cannot revive a terminal job.
+    const completionPersisted = await completeJobIfActive(jobId, {
       viewer_url: result.viewerUrl,
       similarity_percent: result.similarityPercent,
       output_pdf_path: outputPdfPath,
       output_pdf_expires_at: outputPdfExpiresAt,
+      receipt_pdf_path: receiptPdfPath,
+      receipt_pdf_expires_at: receiptPdfExpiresAt,
       error_message: null,
       finished_at: new Date().toISOString(),
     });
+    if (!completionPersisted) {
+      const terminalArtifacts: Partial<TurnitinJob> = {};
+      if (outputPdfPath) terminalArtifacts.output_pdf_path = outputPdfPath;
+      if (outputPdfExpiresAt) terminalArtifacts.output_pdf_expires_at = outputPdfExpiresAt;
+      if (receiptPdfPath) terminalArtifacts.receipt_pdf_path = receiptPdfPath;
+      if (receiptPdfExpiresAt) {
+        terminalArtifacts.receipt_pdf_expires_at = receiptPdfExpiresAt;
+      }
+      if (Object.keys(terminalArtifacts).length > 0) {
+        await safeUpdateJobFields(jobId, terminalArtifacts);
+      }
+    }
     if (result.submissionDetails) {
       await safeUpdateJobFields(jobId, {
         submission_details: result.submissionDetails as Record<string, unknown>,
@@ -610,6 +654,8 @@ async function processJob(job: TurnitinJob): Promise<void> {
         filters_applied: job.filters,
         pdf_path: outputPdfPath,
         pdf_expires_at: outputPdfExpiresAt,
+        receipt_pdf_path: receiptPdfPath,
+        receipt_pdf_expires_at: receiptPdfExpiresAt,
         submitted_at: result.submittedAt,
       });
     } catch (err) {
@@ -699,11 +745,22 @@ async function processJob(job: TurnitinJob): Promise<void> {
       }
     }
 
-    await emitEvent(jobId, identityId, 'info', 'completed', `Job completed. Similarity: ${result.similarityPercent ?? 'N/A'}%`);
-    jobLog.info('Job completed successfully', {
-      similarity: result.similarityPercent,
-      viewerUrl: result.viewerUrl,
-    });
+    if (completionPersisted) {
+      await emitEvent(jobId, identityId, 'info', 'completed', `Job completed. Similarity: ${result.similarityPercent ?? 'N/A'}%`);
+      jobLog.info('Job completed successfully', {
+        similarity: result.similarityPercent,
+        viewerUrl: result.viewerUrl,
+      });
+    } else {
+      await emitEvent(
+        jobId,
+        identityId,
+        'warning',
+        'terminal_status_preserved',
+        'Worker cleanup finished after the job was stopped; terminal status preserved.',
+      );
+      jobLog.warn('Worker finished after job entered a terminal state; completion was not persisted');
+    }
 
     // Cleanup temp directory (moved to finally, see below)
   } catch (err) {
@@ -774,6 +831,15 @@ async function processJob(job: TurnitinJob): Promise<void> {
         : null;
     const remainingAfterConsumedSubmit =
       knownRemaining === null ? null : Math.max(0, knownRemaining - 1);
+    const remainingAfterJob = submissionConsumedThisAttempt
+      ? remainingAfterConsumedSubmit
+      : knownRemaining;
+    const legacyNeedsClassCleanup = Boolean(
+      accountPoolKey === LEGACY_ACCOUNT_POOL_KEY &&
+        isPostSubmitResume &&
+        !shouldRetry &&
+        remainingAfterJob === 0,
+    );
 
     // Release account if claimed
     if (identityId) {
@@ -817,9 +883,11 @@ async function processJob(job: TurnitinJob): Promise<void> {
           if (isPostSubmitResume) {
             if (shouldRetry) {
               nextStatus = 'cooling_down';
-            } else if (submissionConsumedThisAttempt && remainingAfterConsumedSubmit === 0) {
+            } else if (legacyNeedsClassCleanup) {
+              nextStatus = 'cooling_down';
+            } else if (remainingAfterJob === 0) {
               nextStatus = 'quota_limited';
-            } else if (submissionConsumedThisAttempt && remainingAfterConsumedSubmit === null) {
+            } else if (remainingAfterJob === null) {
               nextStatus = 'cooling_down';
             }
           }
@@ -829,11 +897,15 @@ async function processJob(job: TurnitinJob): Promise<void> {
               turnitin_status: nextStatus,
               turnitin_quota_remaining: remainingAfterConsumedSubmit,
               turnitin_quota_message:
-                remainingAfterConsumedSubmit === null
+                legacyNeedsClassCleanup
+                  ? 'Legacy final submission was consumed, but report processing failed. Class cleanup is pending.'
+                  : remainingAfterConsumedSubmit === null
                   ? 'Quota needs refresh after a failed post-submit attempt.'
                   : null,
               turnitin_next_retry_at:
-                nextStatus === 'cooling_down' || nextStatus === 'quota_limited'
+                legacyNeedsClassCleanup
+                  ? new Date().toISOString()
+                  : nextStatus === 'cooling_down' || nextStatus === 'quota_limited'
                   ? new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString()
                   : null,
               turnitin_last_error: errorMessage,
@@ -841,9 +913,26 @@ async function processJob(job: TurnitinJob): Promise<void> {
           } else if (nextStatus === 'cooling_down') {
             await updateAccountQuota(identityId, {
               turnitin_status: 'cooling_down',
+              turnitin_next_retry_at: legacyNeedsClassCleanup
+                ? new Date().toISOString()
+                : claimedAccount?.turnitin_next_retry_at,
               turnitin_last_error: errorMessage,
               turnitin_quota_message:
-                'Reserved for retry after submitted file reached report viewer.',
+                legacyNeedsClassCleanup
+                  ? 'Legacy final submission was consumed, but report processing failed. Class cleanup is pending.'
+                  : 'Reserved for retry after submitted file reached report viewer.',
+            }).catch(() => {});
+          } else if (nextStatus === 'quota_limited') {
+            await updateAccountQuota(identityId, {
+              turnitin_status: 'quota_limited',
+              turnitin_quota_remaining: 0,
+              turnitin_quota_message:
+                'Submitted file consumed the remaining quota before report processing failed.',
+              turnitin_next_retry_at:
+                accountPoolKey === MODERN_ONE_POOL_KEY
+                  ? null
+                  : new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
+              turnitin_last_error: errorMessage,
             }).catch(() => {});
           }
           await releaseAccount(identityId, nextStatus, errorMessage);
@@ -853,6 +942,16 @@ async function processJob(job: TurnitinJob): Promise<void> {
       }
     }
 
+    // A manual failure/cancellation can happen while Playwright is still
+    // unwinding. Preserve that terminal decision after account cleanup.
+    const latestJob = await getJobById(jobId).catch(() => null);
+    if (latestJob && ['failed', 'cancelled'].includes(latestJob.status)) {
+      jobLog.info('Job already terminal after worker failure; retry status not changed', {
+        status: latestJob.status,
+      });
+      return;
+    }
+
     // Check if we should retry
     if (shouldRetry) {
       await updateJobStatus(jobId, 'pending', {
@@ -1069,13 +1168,6 @@ function compactWorkerMessage(message: string): string {
   return firstLine.length > 260 ? `${firstLine.slice(0, 257)}...` : firstLine;
 }
 
-function isAccountTerminalError(message: string | null | undefined): boolean {
-  const value = String(message || '');
-  return /login|reached your limit|submission quota limit|target class|assignment is not available|class.*not found|assignment.*not found/i.test(
-    value,
-  );
-}
-
 /**
  * Helper to emit a job event.
  */
@@ -1160,6 +1252,12 @@ async function persistJobProgressFromEvent(
     /PDF downloaded successfully/i.test(event.message)
   ) {
     fields.last_completed_step = 'download';
+  } else if (
+    event.step === 'receipt' &&
+    event.level === 'info' &&
+    /Digital Receipt downloaded successfully/i.test(event.message)
+  ) {
+    fields.last_completed_step = 'receipt';
   }
 
   if (Object.keys(fields).length > 0) {