texlite 0.5.5 → 0.6.5

package/dist/server/routes/compile.js

@@ -4,16 +4,28 @@ import { randomUUID } from "node:crypto";
 import { performance } from "node:perf_hooks";
 import { requireUser } from "../auth.js";
 import { accessibleProject, canEdit } from "../projects.js";
-import { resolveSourcePath, safeRelativePath } from "../files.js";
+import { resolveSourcePath, safeRelativePath, texFileStem } from "../files.js";
 import { captureCompileSnapshot, cleanCompileArtifacts, cleanCompileCache, compileProject, discardCompileSnapshot, hasCompileCache, publishCompileArtifacts, publishedCompileArtifacts } from "../compiler.js";
 import { parseCompileDiagnostics } from "../compileDiagnostics.js";
 import { pdfToSource, sourceToPdf } from "../synctex.js";
-import { availablePdf, compileMainFile, compilePdfUrl, isTextCompileArtifact, listCompileArtifacts, syncArtifacts } from "../compileArtifacts.js";
+import { availablePdf, compileRunPdf, compileMainFile, compilePdfUrl, isTextCompileArtifact, listCompileArtifacts, syncArtifacts } from "../compileArtifacts.js";
 import { apiError, contentDisposition } from "../http.js";
 const now = () => new Date().toISOString();
 const timingDuration = (milliseconds) => Math.round(milliseconds * 10) / 10;
+const MAX_SNAPSHOT_ATTEMPTS = 3;
+const SNAPSHOT_RETRY_AFTER_SECONDS = 1;
+function mainDocumentChangedError() {
+    return Object.assign(new Error("项目主文档在编译排队期间发生变化，请重新发起编译"), { statusCode: 409, code: "MAIN_DOCUMENT_CHANGED" });
+}
+class CompileSnapshotBusyError extends Error {
+    code = "COMPILE_SNAPSHOT_BUSY";
+    constructor() {
+        super("项目源码尚未完成稳定保存，暂时无法编译，请稍后重试");
+        this.name = "CompileSnapshotBusyError";
+    }
+}
 export function registerCompileRoutes(app, context) {
-    const { config, db, collaboration, compileCoordinator, metrics, pruneCompileRuns } = context;
+    const { config, db, collaboration, projectMutations, compileCoordinator, metrics, pruneCompileRuns } = context;
     app.get("/api/projects/:id/compile/latest", async (request, reply) => {
         const user = requireUser(request, reply, db);
         if (!user)
@@ -37,7 +49,9 @@ export function registerCompileRoutes(app, context) {
         const published = publishedCompileArtifacts(config, id, mainFile, mainFile === project.main_file);
         const publishedRun = published ? db.prepare(`SELECT id, finished_at FROM compile_runs
       WHERE id = ? AND project_id = ? AND status = 'succeeded'`).get(published.runId, id) : undefined;
-        const pdfVersion = published?.runId ?? latestSuccess?.id ?? pdf?.version;
+        // A retained legacy PDF has no run bundle, so its file version (mtime) is
+        // the only stable token that can be resolved back to those bytes.
+        const pdfVersion = published?.runId ?? pdf?.version;
         return {
             mainFile,
             latestRun: latest ? {
@@ -68,29 +82,74 @@ export function registerCompileRoutes(app, context) {
         if (!mainFile)
             return apiError(reply, 400, "MAIN_DOCUMENT_INVALID", "所选文件不是有效的 LaTeX 主文档");
         const published = publishedCompileArtifacts(config, id, mainFile, mainFile === project.main_file);
-        if (!query.path)
-            return { mainFile, runId: published?.runId ?? null, artifacts: published ? listCompileArtifacts(published.output) : [] };
+        if (!query.path) {
+            if (!published)
+                return { mainFile, runId: null, artifacts: [] };
+            try {
+                return { mainFile, runId: published.runId, artifacts: listCompileArtifacts(published.output) };
+            }
+            catch (error) {
+                // Cleanup can remove a retained run after the manifest has been read.
+                // Treat that narrow race as an empty artifact list instead of leaking
+                // an internal ENOENT/ENOTDIR as a 500 response.
+                if (isMissingFileError(error))
+                    return { mainFile, runId: null, artifacts: [] };
+                throw error;
+            }
+        }
         if (!published)
             return apiError(reply, 404, "COMPILE_ARTIFACTS_NOT_FOUND", "尚无可用的编译产物");
         const relative = safeRelativePath(query.path);
         const absolute = path.join(published.output, relative);
         const outputDirectory = path.resolve(published.output);
         const resolved = path.resolve(absolute);
-        if (!resolved.startsWith(`${outputDirectory}${path.sep}`)
-            || !fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
+        if (!resolved.startsWith(`${outputDirectory}${path.sep}`)) {
             return apiError(reply, 404, "COMPILE_ARTIFACT_NOT_FOUND", "编译产物不存在");
         }
-        const stat = fs.statSync(resolved);
+        let stat;
+        try {
+            stat = fs.statSync(resolved);
+            if (!stat.isFile())
+                return apiError(reply, 404, "COMPILE_ARTIFACT_NOT_FOUND", "编译产物不存在");
+        }
+        catch (error) {
+            if (isMissingFileError(error))
+                return apiError(reply, 404, "COMPILE_ARTIFACT_NOT_FOUND", "编译产物不存在");
+            throw error;
+        }
         if (query.download === "1") {
+            const temporaryDirectory = path.join(config.dataDir, "tmp");
+            const temporaryFile = path.join(temporaryDirectory, `artifact-${id}-${randomUUID()}`);
+            await fs.promises.mkdir(temporaryDirectory, { recursive: true, mode: 0o700 });
+            try {
+                await fs.promises.copyFile(resolved, temporaryFile);
+            }
+            catch (error) {
+                await fs.promises.rm(temporaryFile, { force: true }).catch(() => undefined);
+                if (isMissingFileError(error))
+                    return apiError(reply, 404, "COMPILE_ARTIFACT_NOT_FOUND", "编译产物不存在");
+                throw error;
+            }
             reply.header("Content-Type", "application/octet-stream");
             reply.header("Content-Disposition", contentDisposition(path.basename(relative), "attachment"));
             reply.header("Content-Length", stat.size);
-            return reply.send(fs.createReadStream(resolved));
+            const stream = fs.createReadStream(temporaryFile);
+            const cleanup = () => { void fs.promises.rm(temporaryFile, { force: true }).catch(() => undefined); };
+            stream.once("close", cleanup);
+            stream.once("error", cleanup);
+            return reply.send(stream);
         }
         if (stat.size > 2 * 1024 * 1024 || !isTextCompileArtifact(relative)) {
             return apiError(reply, 415, "ARTIFACT_PREVIEW_UNSUPPORTED", "该产物不能作为文本预览，请下载后查看");
         }
-        return { path: relative, content: fs.readFileSync(resolved, "utf8") };
+        try {
+            return { path: relative, content: fs.readFileSync(resolved, "utf8") };
+        }
+        catch (error) {
+            if (isMissingFileError(error))
+                return apiError(reply, 404, "COMPILE_ARTIFACT_NOT_FOUND", "编译产物不存在");
+            throw error;
+        }
     });
     app.post("/api/projects/:id/compile/clean", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -107,37 +166,49 @@ export function registerCompileRoutes(app, context) {
         if (body.mode !== "cache" && body.mode !== "artifacts") {
             return apiError(reply, 400, "REQUEST_INVALID", "清理模式无效");
         }
-        const activeRun = db.prepare(`SELECT 1 AS active FROM compile_runs
-      WHERE project_id = ? AND main_file = ? AND status IN ('queued', 'running') LIMIT 1`).get(id, mainFile);
-        if (activeRun)
-            return apiError(reply, 409, "COMPILE_CLEAN_BUSY", "当前主文档正在编译，请稍后再清理");
-        const requestedBy = { id: user.id, username: user.username, name: user.display_name };
-        if (body.mode === "cache") {
-            cleanCompileCache(config, id, mainFile);
+        return await projectMutations.runCompileExclusive(id, () => {
+            const activeRun = db.prepare(`SELECT 1 AS active FROM compile_runs
+        WHERE project_id = ? AND main_file = ? AND status IN ('queued', 'running') LIMIT 1`).get(id, mainFile);
+            if (activeRun)
+                return apiError(reply, 409, "COMPILE_CLEAN_BUSY", "当前主文档正在编译，请稍后再清理");
+            const requestedBy = { id: user.id, username: user.username, name: user.display_name };
+            if (body.mode === "cache") {
+                cleanCompileCache(config, id, mainFile);
+                collaboration.signalCompileState(id, {
+                    mainFile,
+                    runId: `clean-${randomUUID()}`,
+                    status: "cleaned",
+                    cleanMode: "cache",
+                    requestedBy,
+                    updatedAt: now()
+                });
+                return { ok: true, mode: "cache", mainFile, retainedPdf: true };
+            }
+            const currentProject = accessibleProject(db, id, user);
+            if (!currentProject || !canEdit(currentProject))
+                return apiError(reply, 403, "COMPILE_FORBIDDEN", "没有清理编译产物的权限");
+            const runs = db.prepare(`SELECT id FROM compile_runs
+        WHERE project_id = ? AND main_file = ? AND status NOT IN ('queued', 'running')`).all(id, mainFile);
+            cleanCompileArtifacts(config, id, mainFile, currentProject.main_file, runs.map((run) => run.id));
+            db.prepare("DELETE FROM compile_runs WHERE project_id = ? AND main_file = ? AND status NOT IN ('queued', 'running')").run(id, mainFile);
+            pruneCompileRuns(id);
             collaboration.signalCompileState(id, {
                 mainFile,
                 runId: `clean-${randomUUID()}`,
                 status: "cleaned",
-                cleanMode: "cache",
+                cleanMode: "artifacts",
                 requestedBy,
                 updatedAt: now()
             });
-            return { ok: true, mode: "cache", mainFile, retainedPdf: true };
-        }
-        const runs = db.prepare(`SELECT id FROM compile_runs
-      WHERE project_id = ? AND main_file = ? AND status NOT IN ('queued', 'running')`).all(id, mainFile);
-        cleanCompileArtifacts(config, id, mainFile, project.main_file, runs.map((run) => run.id));
-        db.prepare("DELETE FROM compile_runs WHERE project_id = ? AND main_file = ? AND status NOT IN ('queued', 'running')").run(id, mainFile);
-        pruneCompileRuns(id);
-        collaboration.signalCompileState(id, {
-            mainFile,
-            runId: `clean-${randomUUID()}`,
-            status: "cleaned",
-            cleanMode: "artifacts",
-            requestedBy,
-            updatedAt: now()
-        });
-        return { ok: true, mode: "artifacts", mainFile, retainedPdf: false };
+            return { ok: true, mode: "artifacts", mainFile, retainedPdf: false };
+        }, { preflight: () => {
+                const current = accessibleProject(db, id, user);
+                if (!current || !canEdit(current))
+                    throw Object.assign(new Error("没有清理编译产物的权限"), { statusCode: 403, code: "COMPILE_FORBIDDEN" });
+                const selected = compileMainFile(config, id, current.main_file, body.mainFile);
+                if (!selected || selected !== mainFile)
+                    throw Object.assign(new Error("所选文件不是有效的 LaTeX 主文档"), { statusCode: 400, code: "MAIN_DOCUMENT_INVALID" });
+            } });
     });
     app.get("/api/projects/:id/sync/pdf", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -157,13 +228,18 @@ export function registerCompileRoutes(app, context) {
         if (!Number.isInteger(line) || line < 1 || !Number.isInteger(column) || column < 1) {
             return apiError(reply, 400, "SYNC_SOURCE_INVALID", "源码位置无效");
         }
-        if (!fs.existsSync(resolveSourcePath(config, id, sourcePath))) {
-            return apiError(reply, 404, "SOURCE_FILE_NOT_FOUND", "源码文件不存在");
-        }
-        const artifacts = syncArtifacts(config, id, mainFile, project.main_file);
-        if (!artifacts)
-            return apiError(reply, 409, "SYNCTEX_NOT_AVAILABLE", "项目尚无可用的 SyncTeX 数据，请重新编译");
-        return await sourceToPdf(artifacts.source, artifacts.pdf, sourcePath, line, column);
+        return await projectMutations.runConsistentRead(id, async () => {
+            if (!fs.existsSync(resolveSourcePath(config, id, sourcePath))) {
+                return apiError(reply, 404, "SOURCE_FILE_NOT_FOUND", "源码文件不存在");
+            }
+            const artifacts = syncArtifacts(config, id, mainFile, project.main_file);
+            if (!artifacts)
+                return apiError(reply, 409, "SYNCTEX_NOT_AVAILABLE", "项目尚无可用的 SyncTeX 数据，请重新编译");
+            return await sourceToPdf(artifacts.source, artifacts.pdf, sourcePath, line, column);
+        }, { preflight: () => {
+                if (!accessibleProject(db, id, user))
+                    throw Object.assign(new Error("项目不存在"), { statusCode: 404, code: "PROJECT_NOT_FOUND" });
+            } });
     });
     app.get("/api/projects/:id/sync/source", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -183,16 +259,21 @@ export function registerCompileRoutes(app, context) {
         if (!Number.isInteger(page) || page < 1 || !Number.isFinite(x) || x < 0 || !Number.isFinite(y) || y < 0) {
             return apiError(reply, 400, "SYNC_PDF_INVALID", "PDF 位置无效");
         }
-        const artifacts = syncArtifacts(config, id, mainFile, project.main_file);
-        if (!artifacts)
-            return apiError(reply, 409, "SYNCTEX_NOT_AVAILABLE", "项目尚无可用的 SyncTeX 数据，请重新编译");
-        const location = await pdfToSource(artifacts.source, artifacts.pdf, page, x, y);
-        const sourceDirectory = path.resolve(artifacts.source);
-        const relative = path.relative(sourceDirectory, path.resolve(location.input));
-        if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
-            return apiError(reply, 400, "SYNCTEX_EXTERNAL_PATH", "SyncTeX 返回了项目外部的源码路径");
-        }
-        return { path: safeRelativePath(relative.replaceAll(path.sep, "/")), line: location.line, column: location.column };
+        return await projectMutations.runConsistentRead(id, async () => {
+            const artifacts = syncArtifacts(config, id, mainFile, project.main_file);
+            if (!artifacts)
+                return apiError(reply, 409, "SYNCTEX_NOT_AVAILABLE", "项目尚无可用的 SyncTeX 数据，请重新编译");
+            const location = await pdfToSource(artifacts.source, artifacts.pdf, page, x, y);
+            const sourceDirectory = path.resolve(artifacts.source);
+            const relative = path.relative(sourceDirectory, path.resolve(location.input));
+            if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+                return apiError(reply, 400, "SYNCTEX_EXTERNAL_PATH", "SyncTeX 返回了项目外部的源码路径");
+            }
+            return { path: safeRelativePath(relative.replaceAll(path.sep, "/")), line: location.line, column: location.column };
+        }, { preflight: () => {
+                if (!accessibleProject(db, id, user))
+                    throw Object.assign(new Error("项目不存在"), { statusCode: 404, code: "PROJECT_NOT_FOUND" });
+            } });
     });
     app.post("/api/projects/:id/compile", async (request, reply) => {
         const requestStartedAt = performance.now();
@@ -200,116 +281,358 @@ export function registerCompileRoutes(app, context) {
         if (!user)
             return;
         const { id } = request.params;
-        const project = accessibleProject(db, id, user);
-        if (!project || !canEdit(project))
+        const initialProject = accessibleProject(db, id, user);
+        if (!initialProject || !canEdit(initialProject))
             return apiError(reply, 403, "COMPILE_FORBIDDEN", "没有编译权限");
         const body = (request.body ?? {});
-        const mainFile = compileMainFile(config, id, project.main_file, body.mainFile);
-        if (!mainFile)
+        const requestedMainFile = typeof body.mainFile === "string" && body.mainFile ? body.mainFile : null;
+        const initialMainFile = compileMainFile(config, id, initialProject.main_file, body.mainFile);
+        if (!initialMainFile)
             return apiError(reply, 400, "MAIN_DOCUMENT_INVALID", "所选文件不是有效的 LaTeX 主文档");
-        collaboration.flushProject(id);
         const runId = randomUUID();
-        const snapshotStartedAt = performance.now();
-        const snapshot = await captureCompileSnapshot(config, id, runId, {
-            mainFile,
-            engine: project.engine,
-            latexmkrc: project.latexmkrc,
-            extraArgs: config.extraArgs
-        });
-        const snapshotMs = performance.now() - snapshotStartedAt;
-        metrics.record("compile.snapshot", snapshotMs);
-        const published = publishedCompileArtifacts(config, id, mainFile, mainFile === project.main_file);
-        const publishedRun = published ? db.prepare(`SELECT id, status, log, finished_at
-      FROM compile_runs WHERE id = ? AND project_id = ?`).get(published.runId, id) : undefined;
-        const latestRun = db.prepare(`SELECT id, status FROM compile_runs
-      WHERE project_id = ? AND main_file = ? ORDER BY created_at DESC LIMIT 1`).get(id, mainFile);
-        const activeRun = db.prepare(`SELECT 1 AS active FROM compile_runs
-      WHERE project_id = ? AND main_file = ? AND status IN ('queued', 'running') LIMIT 1`).get(id, mainFile);
-        if (!activeRun && published && publishedRun?.status === "succeeded"
-            && latestRun?.id === publishedRun.id && snapshot.revision === published.revision
-            && hasCompileCache(config, id, mainFile)) {
-            discardCompileSnapshot(snapshot);
-            const requestMs = performance.now() - requestStartedAt;
-            metrics.record("compile.request", requestMs);
-            reply.header("Server-Timing", `snapshot;dur=${timingDuration(snapshotMs)}, total;dur=${timingDuration(requestMs)}`);
-            return {
-                runId: published.runId,
-                ok: true,
-                skipped: true,
-                log: publishedRun.log ?? "",
-                diagnostics: parseCompileDiagnostics(publishedRun.log ?? "", "succeeded"),
-                mainFile,
-                pdfUrl: compilePdfUrl(id, mainFile, published.runId),
-                pdfCompiledAt: publishedRun.finished_at,
-                timings: { snapshotMs, requestMs }
+        // Admission must stay cheap. In particular, do not call
+        // captureCompileSnapshot here: several collaborators can reach this
+        // endpoint at the same time, and the coordinator needs to coalesce them
+        // before any project files are copied or hashed.
+        const admission = await projectMutations.runSnapshot(id, () => {
+            const currentProject = accessibleProject(db, id, user);
+            if (!currentProject || !canEdit(currentProject))
+                throw new Error("Project access changed while waiting for a source snapshot");
+            const currentMainFile = compileMainFile(config, id, currentProject.main_file, body.mainFile);
+            if (!currentMainFile)
+                throw new Error("Selected main document is no longer available");
+            if (!requestedMainFile && currentMainFile !== initialMainFile) {
+                throw mainDocumentChangedError();
+            }
+            // flushProject() is also the final durability barrier for collaborative
+            // edits. Its revision is stable for a no-op flush, so concurrent
+            // admissions observe the same generation without reading file contents.
+            const revisionBeforeFlush = collaboration.currentRevision(id);
+            const receipt = collaboration.hasPendingChanges(id) ? projectMutations.flushProject(id) : null;
+            const refreshedProject = accessibleProject(db, id, user);
+            if (!refreshedProject || !canEdit(refreshedProject)) {
+                throw new Error("Project access changed while preparing a compile request");
+            }
+            const generationRevision = receipt?.revision ?? revisionBeforeFlush;
+            const admissionResult = {
+                project: refreshedProject,
+                mainFile: currentMainFile,
+                generation: compileRequestGeneration(refreshedProject, generationRevision, collaboration.currentGeneration(id), config.extraArgs)
             };
-        }
-        db.prepare("INSERT INTO compile_runs (id, project_id, requested_by, main_file, status, created_at) VALUES (?, ?, ?, ?, 'queued', ?)")
-            .run(runId, id, user.id, mainFile, now());
+            // Insert the queued probe while the project lock is still held. A
+            // concurrent clean request must observe this row before the compile
+            // coordinator starts copying a snapshot.
+            db.prepare("INSERT INTO compile_runs (id, project_id, requested_by, main_file, status, created_at) VALUES (?, ?, ?, ?, 'queued', ?)")
+                .run(runId, id, user.id, currentMainFile, now());
+            return admissionResult;
+        });
+        let project = admission.project;
+        let mainFile = admission.mainFile;
         const requestedBy = { id: user.id, username: user.username, name: user.display_name };
         let phase = "queued";
-        const broadcast = () => collaboration.signalCompileState(id, { mainFile, runId, status: phase, requestedBy, updatedAt: now() });
+        let snapshotStale = false;
+        let snapshotGeneration = null;
+        const refreshSnapshotStale = () => {
+            if (!snapshotGeneration)
+                return;
+            if (collaboration.hasPendingChanges(id)) {
+                snapshotStale = true;
+                return;
+            }
+            const currentProject = accessibleProject(db, id, user);
+            if (!currentProject)
+                return;
+            const currentGeneration = compileRequestGeneration(currentProject, collaboration.currentRevision(id), collaboration.currentGeneration(id), config.extraArgs);
+            if (currentGeneration !== snapshotGeneration)
+                snapshotStale = true;
+        };
+        const broadcast = () => collaboration.signalCompileState(id, {
+            mainFile, runId, status: phase, requestedBy, updatedAt: now(),
+            ...(phase === "succeeded" && snapshotStale ? { stale: true } : {})
+        });
         const result = await compileCoordinator.request({
             projectId: id,
             target: mainFile,
             runId,
-            revision: snapshot.revision,
+            // This key is computed before snapshot creation. The content digest
+            // returned by captureCompileSnapshot is only the result revision.
+            generation: admission.generation,
+            revision: admission.generation,
             onQueued: broadcast,
             onSelected: broadcast,
             onDiscarded: () => {
                 db.prepare("DELETE FROM compile_runs WHERE id = ? AND status = 'queued'").run(runId);
-                discardCompileSnapshot(snapshot);
             },
-            execute: async () => {
-                phase = "running";
-                db.prepare("UPDATE compile_runs SET status = 'running' WHERE id = ?").run(runId);
-                broadcast();
-                let compiled;
+            // The compile reservation protects the shared compiler cache and
+            // prevents Git/cleanup/deletion from replacing the project while
+            // latexmk is running, but it deliberately does not occupy the ordinary
+            // project queue for the duration of the subprocess.
+            execute: async () => projectMutations.runCompile(id, async () => {
+                let snapshot = null;
+                let snapshotMs = 0;
+                const snapshotStartedAt = performance.now();
                 try {
-                    compiled = await compileProject(config, snapshot, mainFile, project.engine, project.latexmkrc);
-                    if (compiled.ok && compiled.pdfPath) {
-                        if (!db.prepare("SELECT 1 FROM projects WHERE id = ?").get(id))
-                            throw new Error("项目已被删除");
-                        const publishStartedAt = performance.now();
-                        publishCompileArtifacts(config, id, snapshot, compiled);
-                        if (compiled.timings) {
-                            compiled.timings.publishMs = performance.now() - publishStartedAt;
-                            compiled.timings.totalMs += compiled.timings.publishMs;
+                    // Refresh the cheap generation after waiting for any queued source
+                    // operation. This makes the no-op check safe when a Git/HTTP write
+                    // completed after admission but before this compile got a worker.
+                    const refreshed = await projectMutations.runSerialized(id, () => {
+                        const currentProject = accessibleProject(db, id, user);
+                        if (!currentProject || !canEdit(currentProject)) {
+                            throw new Error("Project access changed while waiting for a source snapshot");
                         }
+                        const currentMainFile = compileMainFile(config, id, currentProject.main_file, body.mainFile);
+                        if (!currentMainFile)
+                            throw new Error("Selected main document is no longer available");
+                        if (!requestedMainFile && currentMainFile !== mainFile)
+                            throw mainDocumentChangedError();
+                        project = currentProject;
+                        mainFile = currentMainFile;
+                        return {
+                            generation: compileRequestGeneration(currentProject, collaboration.currentRevision(id), collaboration.currentGeneration(id), config.extraArgs)
+                        };
+                    });
+                    const currentGeneration = refreshed.generation;
+                    const publishedBeforeSnapshot = publishedCompileArtifacts(config, id, mainFile, mainFile === project.main_file);
+                    const publishedRunBeforeSnapshot = publishedBeforeSnapshot ? db.prepare(`SELECT id, status, log, finished_at
+            FROM compile_runs WHERE id = ? AND project_id = ?`).get(publishedBeforeSnapshot.runId, id) : undefined;
+                    const latestRunBeforeSnapshot = db.prepare(`SELECT id, status FROM compile_runs
+            WHERE project_id = ? AND main_file = ? AND id <> ? ORDER BY created_at DESC LIMIT 1`).get(id, mainFile, runId);
+                    const activeRunBeforeSnapshot = db.prepare(`SELECT 1 AS active FROM compile_runs
+            WHERE project_id = ? AND main_file = ? AND id <> ? AND status IN ('queued', 'running') LIMIT 1`).get(id, mainFile, runId);
+                    if (!activeRunBeforeSnapshot && publishedBeforeSnapshot?.generation === currentGeneration
+                        && publishedRunBeforeSnapshot?.status === "succeeded"
+                        && latestRunBeforeSnapshot?.id === publishedRunBeforeSnapshot.id
+                        && hasCompileCache(config, id, mainFile)) {
+                        db.prepare("DELETE FROM compile_runs WHERE id = ? AND status = 'queued'").run(runId);
+                        phase = "succeeded";
+                        broadcast();
+                        return {
+                            runId: publishedBeforeSnapshot.runId,
+                            ok: true,
+                            skipped: true,
+                            log: publishedRunBeforeSnapshot.log ?? "",
+                            diagnostics: parseCompileDiagnostics(publishedRunBeforeSnapshot.log ?? "", "succeeded"),
+                            pdfPath: null,
+                            synctexPath: publishedBeforeSnapshot.synctex,
+                            revision: publishedBeforeSnapshot.revision,
+                            snapshotMs: 0
+                        };
                     }
-                    else {
+                    const captured = await projectMutations.runSerialized(id, async () => {
+                        const currentProject = accessibleProject(db, id, user);
+                        if (!currentProject || !canEdit(currentProject)) {
+                            throw new Error("Project access changed while waiting for a source snapshot");
+                        }
+                        const currentMainFile = compileMainFile(config, id, currentProject.main_file, body.mainFile);
+                        if (!currentMainFile)
+                            throw new Error("Selected main document is no longer available");
+                        if (!requestedMainFile && currentMainFile !== mainFile)
+                            throw mainDocumentChangedError();
+                        project = currentProject;
+                        mainFile = currentMainFile;
+                        // Capture only after all exclusive source-tree operations queued
+                        // before this request have completed. A collaboration barrier
+                        // keeps autosave and explicit flushes from changing the source
+                        // directory while the asynchronous copy is in progress.
+                        for (let attempt = 0; attempt < MAX_SNAPSHOT_ATTEMPTS; attempt += 1) {
+                            const revisionBeforeFlush = collaboration.currentRevision(id);
+                            const receipt = collaboration.hasPendingChanges(id) ? projectMutations.flushProject(id) : null;
+                            const expectedRevision = receipt?.revision ?? revisionBeforeFlush;
+                            const generationKey = compileRequestGeneration(project, expectedRevision, collaboration.currentGeneration(id), config.extraArgs);
+                            let candidate = null;
+                            let captureError = null;
+                            let releaseError = null;
+                            let afterBarrierRevision = null;
+                            collaboration.beginSnapshotBarrier(id);
+                            try {
+                                candidate = await captureCompileSnapshot(config, id, runId, {
+                                    mainFile,
+                                    engine: project.engine,
+                                    latexmkrc: project.latexmkrc,
+                                    extraArgs: config.extraArgs,
+                                    generation: generationKey
+                                });
+                            }
+                            catch (error) {
+                                captureError = error;
+                            }
+                            try {
+                                const afterBarrier = collaboration.endSnapshotBarrier(id);
+                                afterBarrierRevision = afterBarrier?.revision ?? collaboration.currentRevision(id);
+                            }
+                            catch (error) {
+                                releaseError = error;
+                            }
+                            if (captureError) {
+                                if (candidate)
+                                    discardCompileSnapshot(candidate);
+                                throw captureError;
+                            }
+                            if (releaseError) {
+                                if (candidate)
+                                    discardCompileSnapshot(candidate);
+                                throw releaseError;
+                            }
+                            if (!candidate)
+                                throw new Error("Unable to create a compile snapshot");
+                            // The barrier makes the candidate internally consistent. Edits
+                            // that arrive while files are being copied stay in Yjs memory
+                            // and are flushed only after the barrier is released; they do
+                            // not make the candidate a mixed or unsafe snapshot. Keep the
+                            // snapshot and surface that it predates those newer edits.
+                            const stable = collaboration.isStable(id, afterBarrierRevision);
+                            if (stable) {
+                                snapshotStale = afterBarrierRevision !== expectedRevision;
+                                snapshotGeneration = candidate.generation ?? null;
+                                return candidate;
+                            }
+                            discardCompileSnapshot(candidate);
+                        }
+                        throw new CompileSnapshotBusyError();
+                    }, { flush: false });
+                    snapshot = captured;
+                    snapshotMs = performance.now() - snapshotStartedAt;
+                    metrics.record("compile.snapshot", snapshotMs);
+                    const published = publishedCompileArtifacts(config, id, mainFile, mainFile === project.main_file);
+                    const publishedRun = published ? db.prepare(`SELECT id, status, log, finished_at
+            FROM compile_runs WHERE id = ? AND project_id = ?`).get(published.runId, id) : undefined;
+                    // The current queued row is intentionally excluded. It is a request
+                    // probe, not evidence that the last successful compile is stale.
+                    const latestRun = db.prepare(`SELECT id, status FROM compile_runs
+            WHERE project_id = ? AND main_file = ? AND id <> ? ORDER BY created_at DESC LIMIT 1`).get(id, mainFile, runId);
+                    const activeRun = db.prepare(`SELECT 1 AS active FROM compile_runs
+            WHERE project_id = ? AND main_file = ? AND id <> ? AND status IN ('queued', 'running') LIMIT 1`).get(id, mainFile, runId);
+                    if (!activeRun && published && publishedRun?.status === "succeeded"
+                        && latestRun?.id === publishedRun.id && snapshot.revision === published.revision
+                        && hasCompileCache(config, id, mainFile)) {
                         discardCompileSnapshot(snapshot);
+                        snapshot = null;
+                        db.prepare("DELETE FROM compile_runs WHERE id = ? AND status = 'queued'").run(runId);
+                        phase = "succeeded";
+                        broadcast();
+                        return {
+                            runId: published.runId,
+                            ok: true,
+                            skipped: true,
+                            stale: snapshotStale,
+                            log: publishedRun.log ?? "",
+                            diagnostics: parseCompileDiagnostics(publishedRun.log ?? "", "succeeded"),
+                            pdfPath: null,
+                            synctexPath: published.synctex,
+                            revision: published.revision,
+                            snapshotMs
+                        };
+                    }
+                    phase = "running";
+                    db.prepare("UPDATE compile_runs SET status = 'running' WHERE id = ?").run(runId);
+                    broadcast();
+                    let compiled;
+                    try {
+                        compiled = await compileProject(config, snapshot, mainFile, project.engine, project.latexmkrc);
+                        refreshSnapshotStale();
+                        if (compiled.ok && compiled.pdfPath) {
+                            const publishStartedAt = performance.now();
+                            // Publishing is short and atomic, but still goes through the
+                            // ordinary project queue so it cannot overlap a source-tree
+                            // archive/read or another output mutation. The long latexmk
+                            // process above remains outside that queue.
+                            await projectMutations.runSerialized(id, () => {
+                                if (!db.prepare("SELECT 1 FROM projects WHERE id = ?").get(id))
+                                    throw new Error("项目已被删除");
+                                publishCompileArtifacts(config, id, snapshot, compiled);
+                            }, { flush: false });
+                            refreshSnapshotStale();
+                            if (compiled.timings) {
+                                compiled.timings.publishMs = performance.now() - publishStartedAt;
+                                compiled.timings.totalMs += compiled.timings.publishMs;
+                            }
+                        }
+                        else {
+                            discardCompileSnapshot(snapshot);
+                            snapshot = null;
+                        }
+                    }
+                    catch (error) {
+                        if (snapshot)
+                            discardCompileSnapshot(snapshot);
+                        snapshot = null;
+                        compiled = {
+                            ok: false,
+                            log: error instanceof Error ? error.message : String(error),
+                            diagnostics: parseCompileDiagnostics(error instanceof Error ? error.message : String(error), "failed"),
+                            pdfPath: null,
+                            synctexPath: null
+                        };
                     }
+                    phase = compiled.ok ? "succeeded" : "failed";
+                    db.prepare("UPDATE compile_runs SET status = ?, log = ?, finished_at = ? WHERE id = ?")
+                        .run(phase, compiled.log, now(), runId);
+                    broadcast();
+                    return { ...compiled, runId, revision: snapshot?.revision ?? admission.generation, stale: snapshotStale, snapshotMs };
                 }
                 catch (error) {
-                    discardCompileSnapshot(snapshot);
-                    compiled = {
+                    if (snapshot)
+                        discardCompileSnapshot(snapshot);
+                    if (error instanceof CompileSnapshotBusyError) {
+                        snapshotMs = performance.now() - snapshotStartedAt;
+                        metrics.record("compile.snapshot", snapshotMs);
+                        phase = "failed";
+                        db.prepare("DELETE FROM compile_runs WHERE id = ? AND status = 'queued'").run(runId);
+                        broadcast();
+                        return {
+                            ok: false,
+                            retryable: true,
+                            errorCode: error.code,
+                            log: error.message,
+                            diagnostics: { warnings: [], errors: [] },
+                            pdfPath: null,
+                            synctexPath: null,
+                            runId,
+                            revision: admission.generation,
+                            snapshotMs
+                        };
+                    }
+                    const log = error instanceof Error ? error.message : String(error);
+                    phase = "failed";
+                    db.prepare("UPDATE compile_runs SET status = 'failed', log = ?, finished_at = ? WHERE id = ?")
+                        .run(log, now(), runId);
+                    broadcast();
+                    return {
                         ok: false,
-                        log: error instanceof Error ? error.message : String(error),
-                        diagnostics: parseCompileDiagnostics(error instanceof Error ? error.message : String(error), "failed"),
+                        log,
+                        diagnostics: parseCompileDiagnostics(log, "failed"),
                         pdfPath: null,
-                        synctexPath: null
+                        synctexPath: null,
+                        runId,
+                        revision: admission.generation,
+                        snapshotMs
                     };
                 }
-                phase = compiled.ok ? "succeeded" : "failed";
-                db.prepare("UPDATE compile_runs SET status = ?, log = ?, finished_at = ? WHERE id = ?")
-                    .run(phase, compiled.log, now(), runId);
-                broadcast();
-                return { ...compiled, runId, revision: snapshot.revision };
-            }
+            }),
         });
         const completed = db.prepare("SELECT finished_at FROM compile_runs WHERE id = ?").get(result.runId);
         const requestMs = performance.now() - requestStartedAt;
         metrics.record("compile.request", requestMs);
+        if (result.retryable) {
+            await projectMutations.runSerialized(id, () => { pruneCompileRuns(id); }, { flush: false });
+            reply.header("Retry-After", String(SNAPSHOT_RETRY_AFTER_SECONDS));
+            reply.header("Server-Timing", [
+                `snapshot;dur=${timingDuration(result.snapshotMs ?? 0)}`,
+                `total;dur=${timingDuration(requestMs)}`
+            ].join(", "));
+            return apiError(reply, 409, result.errorCode ?? "COMPILE_SNAPSHOT_BUSY", result.log, { retryable: true, retryAfterSeconds: SNAPSHOT_RETRY_AFTER_SECONDS });
+        }
         if (result.timings) {
             metrics.record("compile.cacheSync", result.timings.cacheSyncMs);
             metrics.record("compile.latexmk", result.timings.latexmkMs);
             metrics.record("compile.artifactCopy", result.timings.artifactCopyMs);
         }
-        pruneCompileRuns(id);
-        const timings = result.timings ? { snapshotMs, ...result.timings, requestMs } : { snapshotMs, requestMs };
+        await projectMutations.runSerialized(id, () => { pruneCompileRuns(id); }, { flush: false });
+        const timings = result.timings
+            ? { snapshotMs: result.snapshotMs ?? 0, ...result.timings, requestMs }
+            : { snapshotMs: result.snapshotMs ?? 0, requestMs };
         reply.header("Server-Timing", [
-            `snapshot;dur=${timingDuration(snapshotMs)}`,
+            `snapshot;dur=${timingDuration(result.snapshotMs ?? 0)}`,
             result.timings ? `cache;dur=${timingDuration(result.timings.cacheSyncMs)}` : "",
             result.timings ? `latexmk;dur=${timingDuration(result.timings.latexmkMs)}` : "",
             result.timings ? `artifacts;dur=${timingDuration(result.timings.artifactCopyMs)}` : "",
@@ -317,12 +640,17 @@ export function registerCompileRoutes(app, context) {
             `total;dur=${timingDuration(requestMs)}`
         ].filter(Boolean).join(", "));
         return {
-            mainFile, runId: result.runId, ok: result.ok, skipped: false, log: result.log, diagnostics: result.diagnostics,
+            mainFile, runId: result.runId, ok: result.ok, skipped: result.skipped === true, log: result.log, diagnostics: result.diagnostics,
             pdfUrl: result.ok ? compilePdfUrl(id, mainFile, result.runId) : null,
             pdfCompiledAt: result.ok ? completed?.finished_at ?? null : null,
             timings
         };
     });
+    // Published PDFs are retained, immutable artifacts. Keep this read outside
+    // projectMutations: runSerialized/runConsistentRead wait for a cold Yjs room
+    // to finish initializing, which would delay the first PDF paint after a
+    // server restart. The manifest and per-run bundle are swapped atomically,
+    // so a concurrent cleanup can safely result in a normal 404 instead.
     app.get("/api/projects/:id/pdf", async (request, reply) => {
         const user = requireUser(request, reply, db);
         if (!user)
@@ -336,17 +664,43 @@ export function registerCompileRoutes(app, context) {
         if (!mainFile)
             return apiError(reply, 400, "MAIN_DOCUMENT_INVALID", "所选文件不是有效的 LaTeX 主文档");
         const downloading = query.download === "1";
-        const artifact = availablePdf(config, id, mainFile, project.main_file);
+        let artifact = availablePdf(config, id, mainFile, project.main_file);
         if (!artifact)
             return apiError(reply, 404, "PDF_NOT_FOUND", "尚未生成 PDF");
+        let versioned = false;
+        if (query.run) {
+            if (/^[a-f0-9-]{36}$/i.test(query.run)) {
+                const run = db.prepare(`SELECT main_file, status FROM compile_runs
+          WHERE id = ? AND project_id = ?`).get(query.run, id);
+                if (!run || run.status !== "succeeded" || run.main_file !== mainFile) {
+                    return apiError(reply, 404, "PDF_NOT_FOUND", "指定的编译 PDF 不存在");
+                }
+                artifact = compileRunPdf(config, id, mainFile, query.run);
+                if (!artifact)
+                    return apiError(reply, 404, "PDF_NOT_FOUND", "指定的编译 PDF 已被清理");
+                versioned = true;
+            }
+            else if (artifact.version !== query.run) {
+                return apiError(reply, 404, "PDF_NOT_FOUND", "指定的编译 PDF 不存在");
+            }
+        }
         const pdf = artifact.path;
-        const stat = fs.statSync(pdf);
+        const stat = regularFileStat(pdf);
+        if (!stat)
+            return apiError(reply, 404, "PDF_NOT_FOUND", "尚未生成 PDF");
         const etag = `"${stat.size.toString(16)}-${Math.trunc(stat.mtimeMs).toString(16)}"`;
         reply.header("Content-Type", "application/pdf");
-        const targetSuffix = mainFile === project.main_file ? "" : `-${path.basename(mainFile, ".tex")}`;
+        const targetSuffix = mainFile === project.main_file ? "" : `-${texFileStem(mainFile)}`;
         const filename = downloading ? `${project.name}${targetSuffix}-${pdfDownloadTimestamp()}.pdf` : `${project.name}${targetSuffix}.pdf`;
         reply.header("Content-Disposition", contentDisposition(filename, downloading ? "attachment" : "inline"));
-        reply.header("Cache-Control", "private, no-cache");
+        // The run query identifies an immutable successful compile. Keep it in the
+        // browser's private cache so reopening a project does not re-download the
+        // same PDF; a new successful compile receives a new run URL.
+        reply.header("Cache-Control", downloading
+            ? "private, no-store"
+            : versioned
+                ? "private, max-age=31536000, immutable"
+                : "private, max-age=60, must-revalidate");
         reply.header("Accept-Ranges", "bytes");
         reply.header("ETag", etag);
         reply.header("Last-Modified", stat.mtime.toUTCString());
@@ -361,10 +715,59 @@ export function registerCompileRoutes(app, context) {
         if (range) {
             reply.header("Content-Range", `bytes ${range.start}-${range.end}/${stat.size}`);
             reply.header("Content-Length", range.end - range.start + 1);
-            return reply.code(206).send(fs.createReadStream(pdf, range));
+            let stream;
+            try {
+                stream = await openReadStream(fs.createReadStream(pdf, range));
+            }
+            catch (error) {
+                if (isMissingFileError(error))
+                    return apiError(reply, 404, "PDF_NOT_FOUND", "尚未生成 PDF");
+                throw error;
+            }
+            return reply.code(206).send(stream);
         }
         reply.header("Content-Length", stat.size);
-        return reply.send(fs.createReadStream(pdf));
+        let stream;
+        try {
+            stream = await openReadStream(fs.createReadStream(pdf));
+        }
+        catch (error) {
+            if (isMissingFileError(error))
+                return apiError(reply, 404, "PDF_NOT_FOUND", "尚未生成 PDF");
+            throw error;
+        }
+        return reply.code(200).send(stream);
+    });
+}
+function regularFileStat(filePath) {
+    try {
+        const stat = fs.statSync(filePath);
+        return stat.isFile() ? stat : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isMissingFileError(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        && (error.code === "ENOENT" || error.code === "ENOTDIR");
+}
+async function openReadStream(stream) {
+    const opened = new Promise((resolve, reject) => {
+        stream.once("open", () => resolve());
+        stream.once("error", reject);
+    });
+    await opened;
+    return stream;
+}
+function compileRequestGeneration(project, persistedRevision, sourceGeneration, extraArgs) {
+    return JSON.stringify({
+        mainFile: project.main_file,
+        engine: project.engine,
+        latexmkrc: project.latexmkrc,
+        persistedRevision,
+        sourceGeneration,
+        extraArgs
     });
 }
 function pdfDownloadTimestamp(date = new Date()) {