texlite 0.8.4 → 0.9.1

package/dist/server/harper.js

@@ -11,12 +11,26 @@ const maxCachedSourceBytes = 512 * 1024;
 const maxCachedResults = 24;
 const cacheTtlMs = 15_000;
 const unavailableRetryMs = 15_000;
+// A browser can send an older request after a newer one when HTTP requests
+// race. Keep the latest sequence briefly so that late arrivals cannot replace
+// a newer queued revision. The bound is intentionally generous for a small
+// collaborative installation while keeping abandoned browser-page lanes from
+// accumulating forever.
+const laneSequenceRetentionMs = 10 * 60_000;
+const maxTrackedLaneSequences = 512;
 export class HarperUnavailableError extends Error {
     constructor(message) {
         super(message);
         this.name = "HarperUnavailableError";
     }
 }
+/** A newer source revision made a waiting writing check irrelevant. */
+export class HarperLintSupersededError extends Error {
+    constructor() {
+        super("A newer writing check replaced this request.");
+        this.name = "HarperLintSupersededError";
+    }
+}
 function lintCacheKey(source, filePath) {
     // Harper selects its parser from the input suffix, so equivalent text in a
     // .tex and a .sty file must not share a diagnostic result.
@@ -78,8 +92,20 @@ export class HarperService {
     availability = "unknown";
     lastUnavailableAt = 0;
     probePromise = null;
-    queue = Promise.resolve();
+    /** One harper-cli process at a time; Harper itself is comparatively heavy. */
+    queueRunner = null;
+    // Set preserves insertion order, giving the scheduler FIFO behaviour while
+    // allowing a superseded waiting item to be removed immediately. An array
+    // would otherwise retain its complete source string until the active check
+    // finishes.
+    queued = new Set();
+    /** Only waiting work belongs here; a running process must finish safely. */
+    waitingByLane = new Map();
+    /** Latest accepted browser revision for each project/user/page/file lane. */
+    latestSequenceByLane = new Map();
     inFlight = new Map();
+    /** Lets coalesced browser lanes share one queued operation safely. */
+    scheduledByKey = new Map();
     cache = new Map();
     activeChild = null;
     disposed = false;
@@ -89,35 +115,206 @@ export class HarperService {
     async preload() {
         await this.ensureAvailable();
     }
-    async lint(source, filePath = "main.tex") {
+    /**
+     * Schedule one host-side check. A lane represents one browser page's
+     * current file, so an edit can replace only its own stale waiting request
+     * without cancelling checks requested by collaborators.
+     */
+    async lint(source, filePath = "main.tex", lane, sequence) {
         if (this.disposed)
             throw new HarperUnavailableError("Harper service stopped.");
         const key = lintCacheKey(source, filePath);
+        const laneKey = lane || null;
+        if (laneKey && sequence !== undefined)
+            this.acceptLaneSequence(laneKey, sequence, key);
+        const waiting = laneKey ? this.waitingByLane.get(laneKey) : undefined;
+        // Repeated requests for the same queued revision share it. A newer
+        // revision replaces only work that has not started yet.
+        if (waiting?.key === key)
+            return waiting.promise;
+        if (laneKey && waiting)
+            this.releaseWaitingLane(laneKey, waiting);
         const cacheable = Buffer.byteLength(source, "utf8") <= maxCachedSourceBytes;
         const cached = cacheable ? this.cachedResult(key) : null;
         if (cached)
             return cached;
-        const existing = cacheable ? this.inFlight.get(key) : undefined;
-        if (existing)
+        // Result caching is deliberately size-bounded, but duplicate active work
+        // is still coalesced for large files. The latter is transient and avoids
+        // starting multiple expensive CLI processes for identical content.
+        const existing = this.inFlight.get(key);
+        if (existing) {
+            const scheduled = this.scheduledByKey.get(key);
+            if (laneKey && scheduled)
+                this.addWaitingLane(scheduled, laneKey);
+            else if (scheduled && !scheduled.started)
+                scheduled.hasUnscopedWaiter = true;
             return existing;
-        const operation = this.queue.then(() => this.lintOnce(source, filePath));
-        this.queue = operation.then(() => undefined, () => undefined);
+        }
+        let resolve;
+        let reject;
+        const operation = new Promise((resolveOperation, rejectOperation) => {
+            resolve = resolveOperation;
+            reject = rejectOperation;
+        });
+        const scheduled = {
+            key,
+            source,
+            filePath,
+            started: false,
+            cancelled: false,
+            lanes: laneKey ? new Set([laneKey]) : new Set(),
+            hasUnscopedWaiter: laneKey === null,
+            promise: operation,
+            resolve,
+            reject
+        };
+        this.inFlight.set(key, operation);
+        this.scheduledByKey.set(key, scheduled);
+        if (laneKey)
+            this.waitingByLane.set(laneKey, scheduled);
+        this.queued.add(scheduled);
+        this.startQueue();
         if (cacheable) {
-            this.inFlight.set(key, operation);
             void operation.then((lints) => this.cacheResult(key, lints), () => undefined).finally(() => {
                 if (this.inFlight.get(key) === operation)
                     this.inFlight.delete(key);
+                if (this.scheduledByKey.get(key) === scheduled)
+                    this.scheduledByKey.delete(key);
+            });
+        }
+        else {
+            // Attach a rejection handler even for uncached results. This keeps a
+            // superseded request from becoming an unhandled rejection when a client
+            // disconnects before it awaits the response.
+            void operation.catch(() => undefined).finally(() => {
+                if (this.inFlight.get(key) === operation)
+                    this.inFlight.delete(key);
+                if (this.scheduledByKey.get(key) === scheduled)
+                    this.scheduledByKey.delete(key);
             });
         }
         return operation;
     }
     async dispose() {
         this.disposed = true;
+        const stopped = new HarperUnavailableError("Harper service stopped.");
+        for (const scheduled of [...this.queued]) {
+            if (!scheduled.cancelled && !scheduled.started) {
+                scheduled.cancelled = true;
+                this.discardQueuedLint(scheduled);
+                scheduled.reject(stopped);
+            }
+        }
+        this.waitingByLane.clear();
+        this.latestSequenceByLane.clear();
         this.activeChild?.kill("SIGTERM");
-        await this.queue.catch(() => undefined);
+        await this.queueRunner?.catch(() => undefined);
         this.inFlight.clear();
+        this.scheduledByKey.clear();
         this.cache.clear();
     }
+    addWaitingLane(scheduled, lane) {
+        if (scheduled.started || scheduled.cancelled)
+            return;
+        scheduled.lanes.add(lane);
+        this.waitingByLane.set(lane, scheduled);
+    }
+    releaseWaitingLane(lane, scheduled) {
+        if (this.waitingByLane.get(lane) === scheduled)
+            this.waitingByLane.delete(lane);
+        scheduled.lanes.delete(lane);
+        // The exact same queued source can be requested by multiple sessions.
+        // Discard it only after every interested lane has moved on.
+        if (scheduled.started || scheduled.cancelled || scheduled.hasUnscopedWaiter || scheduled.lanes.size > 0)
+            return;
+        this.cancelScheduledLint(scheduled);
+    }
+    cancelScheduledLint(scheduled) {
+        if (scheduled.started || scheduled.cancelled)
+            return;
+        scheduled.cancelled = true;
+        for (const lane of scheduled.lanes) {
+            if (this.waitingByLane.get(lane) === scheduled)
+                this.waitingByLane.delete(lane);
+        }
+        scheduled.lanes.clear();
+        // Remove this rejected promise immediately so a later return to the same
+        // text can enqueue fresh work instead of inheriting a stale rejection.
+        if (this.inFlight.get(scheduled.key) === scheduled.promise) {
+            this.inFlight.delete(scheduled.key);
+        }
+        if (this.scheduledByKey.get(scheduled.key) === scheduled) {
+            this.scheduledByKey.delete(scheduled.key);
+        }
+        this.discardQueuedLint(scheduled);
+        scheduled.reject(new HarperLintSupersededError());
+    }
+    /** Remove a waiting task and promptly release its potentially large text. */
+    discardQueuedLint(scheduled) {
+        this.queued.delete(scheduled);
+        scheduled.source = "";
+        scheduled.filePath = "";
+    }
+    /** Reject an out-of-order request before it can alter queued work. */
+    acceptLaneSequence(lane, sequence, key) {
+        if (!Number.isSafeInteger(sequence) || sequence <= 0) {
+            throw new HarperLintSupersededError();
+        }
+        const now = Date.now();
+        this.pruneLaneSequences(now);
+        const previous = this.latestSequenceByLane.get(lane);
+        if (previous && (sequence < previous.sequence || (sequence === previous.sequence && previous.key !== key))) {
+            throw new HarperLintSupersededError();
+        }
+        // Refresh insertion order so the bounded map evicts the least recently
+        // used abandoned page lane first.
+        this.latestSequenceByLane.delete(lane);
+        this.latestSequenceByLane.set(lane, { sequence, key, seenAt: now });
+        while (this.latestSequenceByLane.size > maxTrackedLaneSequences) {
+            const oldest = this.latestSequenceByLane.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.latestSequenceByLane.delete(oldest);
+        }
+    }
+    pruneLaneSequences(now) {
+        for (const [lane, state] of this.latestSequenceByLane) {
+            if (now - state.seenAt <= laneSequenceRetentionMs)
+                continue;
+            this.latestSequenceByLane.delete(lane);
+        }
+    }
+    startQueue() {
+        if (this.queueRunner)
+            return;
+        this.queueRunner = (async () => {
+            while (!this.disposed) {
+                const scheduled = this.queued.values().next().value;
+                if (!scheduled)
+                    return;
+                this.queued.delete(scheduled);
+                if (scheduled.cancelled)
+                    continue;
+                scheduled.started = true;
+                for (const lane of scheduled.lanes) {
+                    if (this.waitingByLane.get(lane) === scheduled)
+                        this.waitingByLane.delete(lane);
+                }
+                scheduled.lanes.clear();
+                try {
+                    scheduled.resolve(await this.lintOnce(scheduled.source, scheduled.filePath));
+                }
+                catch (error) {
+                    scheduled.reject(error);
+                }
+            }
+        })().finally(() => {
+            this.queueRunner = null;
+            // A request can arrive just after the loop observes an empty queue.
+            if (!this.disposed && this.queued.size)
+                this.startQueue();
+        });
+    }
     async ensureAvailable() {
         if (this.availability === "available")
             return;

package/dist/server/history.js

@@ -5,6 +5,12 @@ import { assertNoSourceSymlinks, listProjectFiles, outputRoot, projectRoot, reso
 import { httpError } from "./http.js";
 import { MAX_TEXT_PREVIEW_BYTES } from "./limits.js";
 const AUTOSAVE_COALESCE_MS = 2 * 60_000;
+// Logical stored payload; SQLite pages, indexes and WAL are shared database overhead.
+function historyMetadataBytes(row) {
+    return Object.values(row).reduce((sum, value) => sum + (typeof value === "string" ? Buffer.byteLength(value, "utf8") : 0), 0);
+}
+const DEFAULT_HISTORY_PAGE_SIZE = 100;
+const MAX_HISTORY_PAGE_SIZE = 100;
 export class ProjectHistoryService {
     config;
     db;
@@ -12,7 +18,7 @@ export class ProjectHistoryService {
         this.config = config;
         this.db = db;
     }
-    record(projectId, authorId, reason, changedRoots) {
+    record(projectId, authorId, reason, changedRoots, options = {}) {
         const project = this.project(projectId);
         const previous = this.latestRow(projectId);
         const previousManifest = this.baseline(projectId) ?? (previous ? parseManifest(previous.manifest_json) : null);
@@ -38,17 +44,19 @@ export class ProjectHistoryService {
             return null;
         }
         const createdAt = new Date().toISOString();
-        if (reason === "autosave" && previous?.reason === "autosave" && !previous.label && previous.author_id === authorId
+        if (reason === "autosave" && previous?.reason === "autosave" && !previous.label
             && Date.parse(createdAt) - Date.parse(previous.created_at) < AUTOSAVE_COALESCE_MS) {
             const merged = [...new Set([...parseStringArray(previous.changed_paths_json), ...changedPaths])].sort();
             this.db.prepare(`UPDATE project_history_versions
-        SET manifest_json = ?, changed_paths_json = ? WHERE id = ?`)
-                .run(JSON.stringify(manifest), JSON.stringify(merged), previous.id);
+        SET manifest_json = ?, changed_paths_json = ?, author_id = ? WHERE id = ?`)
+                .run(JSON.stringify(manifest), JSON.stringify(merged), previous.author_id === authorId ? authorId : null, previous.id);
             this.saveBaseline(projectId, manifest);
-            this.removeUnreferencedObjects(projectId, new Set(previousManifest
-                ? Object.values(previousManifest.files).map((file) => file.digest)
-                : []));
-            this.pruneVersions(projectId);
+            if (!options.deferRetention) {
+                this.removeUnreferencedObjects(projectId, new Set(previousManifest
+                    ? Object.values(previousManifest.files).map((file) => file.digest)
+                    : []));
+                this.pruneVersions(projectId);
+            }
             return this.version(previous.id);
         }
         const id = randomUUID();
@@ -57,7 +65,8 @@ export class ProjectHistoryService {
       VALUES (?, ?, ?, ?, ?, ?, ?)`)
             .run(id, projectId, authorId, reason, JSON.stringify(manifest), JSON.stringify(changedPaths), createdAt);
         this.saveBaseline(projectId, manifest);
-        this.pruneVersions(projectId);
+        if (!options.deferRetention)
+            this.pruneVersions(projectId);
         return this.version(id);
     }
     list(projectId, limit = 100) {
@@ -67,13 +76,50 @@ export class ProjectHistoryService {
             .all(projectId, Math.min(200, Math.max(1, limit)));
         return rows.map((row) => versionJson(row));
     }
+    /**
+     * List immutable recovery snapshots from newest to oldest. Cursor pagination
+     * is preferable to offsets here: concurrent saves/deletions cannot shift an
+     * already loaded page or make the next request repeat a snapshot.
+    */
+    listPage(projectId, limit = DEFAULT_HISTORY_PAGE_SIZE, cursorInput) {
+        const requestedLimit = Number.isFinite(limit) ? Math.floor(limit) : DEFAULT_HISTORY_PAGE_SIZE;
+        const limitValue = Math.min(MAX_HISTORY_PAGE_SIZE, Math.max(1, requestedLimit));
+        const cursor = cursorInput === undefined ? null : decodeHistoryCursor(cursorInput);
+        if (cursorInput !== undefined && !cursor)
+            throw httpError(400, "REQUEST_INVALID");
+        const values = [projectId];
+        let cursorFilter = "";
+        if (cursor) {
+            cursorFilter = "AND (history.created_at < ? OR (history.created_at = ? AND history.rowid < ?))";
+            values.push(cursor.createdAt, cursor.createdAt, cursor.rowId);
+        }
+        values.push(limitValue + 1);
+        const rows = this.db.prepare(`SELECT history.*, history.rowid AS history_rowid,
+      user.username AS author_username, user.display_name AS author_name
+      FROM project_history_versions history LEFT JOIN users user ON user.id = history.author_id
+      WHERE history.project_id = ? ${cursorFilter}
+      ORDER BY history.created_at DESC, history.rowid DESC LIMIT ?`)
+            .all(...values);
+        const pageRows = rows.slice(0, limitValue);
+        return {
+            versions: pageRows.map((row) => versionJson(row)),
+            nextCursor: rows.length > limitValue && pageRows.length > 0 ? encodeHistoryCursor(pageRows.at(-1)) : null
+        };
+    }
     stats(projectId) {
-        const rows = this.db.prepare(`SELECT reason, label, manifest_json FROM project_history_versions
-      WHERE project_id = ?`).all(projectId);
+        const rows = this.db.prepare(`SELECT * FROM project_history_versions
+      WHERE project_id = ? ORDER BY created_at DESC, rowid DESC`).all(projectId);
         const objects = new Map();
+        const protectedObjects = new Map();
+        let metadataBytes = 0;
+        let protectedMetadataBytes = 0;
         let ordinaryVersionCount = 0;
         let labeledVersionCount = 0;
         for (const row of rows) {
+            const protectedVersion = row === rows[0] || row.reason === "initial" || Boolean(row.label);
+            metadataBytes += historyMetadataBytes(row);
+            if (protectedVersion)
+                protectedMetadataBytes += historyMetadataBytes(row);
             if (row.label)
                 labeledVersionCount += 1;
             else if (row.reason !== "initial")
@@ -81,13 +127,19 @@ export class ProjectHistoryService {
             for (const file of Object.values(parseManifest(row.manifest_json).files)) {
                 if (!objects.has(file.digest))
                     objects.set(file.digest, file.size);
+                if (protectedVersion)
+                    protectedObjects.set(file.digest, file.size);
             }
         }
         const baseline = this.baseline(projectId);
         if (baseline) {
+            const baselineBytes = Buffer.byteLength(JSON.stringify(baseline), "utf8");
+            metadataBytes += baselineBytes;
+            protectedMetadataBytes += baselineBytes;
             for (const file of Object.values(baseline.files)) {
                 if (!objects.has(file.digest))
                     objects.set(file.digest, file.size);
+                protectedObjects.set(file.digest, file.size);
             }
         }
         const objectBytes = [...objects.values()].reduce((sum, size) => sum + size, 0);
@@ -97,13 +149,21 @@ export class ProjectHistoryService {
             labeledVersionCount,
             objectCount: objects.size,
             objectBytes,
+            metadataBytes,
+            totalBytes: objectBytes + metadataBytes,
+            protectedBytes: [...protectedObjects.values()].reduce((sum, size) => sum + size, protectedMetadataBytes),
             maxVersions: this.config.historyMaxVersions,
             maxStorageBytes: this.config.historyMaxStorageBytes,
-            storageLimitExceeded: objectBytes > this.config.historyMaxStorageBytes
+            storageLimitExceeded: objectBytes + metadataBytes > this.config.historyMaxStorageBytes
         };
     }
     enforceRetention(projectId) {
         this.pruneVersions(projectId);
+        // Deferred autosave maintenance can leave an object from a coalesced
+        // version without any manifest referring to it. Scan the small
+        // content-addressed object store here (never in the save path) so a
+        // restart also recovers objects left behind before a timer could run.
+        this.removeUnreferencedObjects(projectId, this.storedObjectDigests(projectId));
     }
     deleteVersion(projectId, versionId) {
         const row = this.db.prepare("SELECT id, manifest_json FROM project_history_versions WHERE id = ? AND project_id = ?")
@@ -133,6 +193,23 @@ export class ProjectHistoryService {
             .get(versionId, projectId);
         return row ? parseManifest(row.manifest_json) : null;
     }
+    /**
+     * A short autosave window deliberately coalesces updates into one row. A
+     * client that has been inspecting that row must not restore newer contents
+     * it has not reviewed, so verify the manifest fingerprint immediately
+     * before a restore mutates the project.
+     */
+    assertSnapshotHash(projectId, versionId, expectedHash) {
+        if (!expectedHash)
+            return;
+        const row = this.db.prepare("SELECT manifest_json FROM project_history_versions WHERE id = ? AND project_id = ?")
+            .get(versionId, projectId);
+        if (!row)
+            throw httpError(404, "HISTORY_VERSION_NOT_FOUND");
+        if (historySnapshotHash(row.manifest_json) !== expectedHash) {
+            throw httpError(409, "HISTORY_VERSION_CHANGED");
+        }
+    }
     /**
      * Validate a single-file restore before the project enters maintenance.
      * restore() repeats the target check while the exclusive operation is held
@@ -151,6 +228,14 @@ export class ProjectHistoryService {
         }
         this.assertRestoreTargetIsFile(projectId, filePath);
     }
+    previousVersion(projectId, versionId) {
+        const row = this.db.prepare(`SELECT older.id FROM project_history_versions older
+      JOIN project_history_versions selected ON selected.id = ? AND selected.project_id = older.project_id
+      WHERE older.project_id = ? AND (older.created_at < selected.created_at
+        OR (older.created_at = selected.created_at AND older.rowid < selected.rowid))
+      ORDER BY older.created_at DESC, older.rowid DESC LIMIT 1`).get(versionId, projectId);
+        return row ? this.version(row.id, projectId) : null;
+    }
     setLabel(projectId, versionId, label) {
         const result = this.db.prepare("UPDATE project_history_versions SET label = ? WHERE id = ? AND project_id = ?")
             .run(label, versionId, projectId);
@@ -161,7 +246,7 @@ export class ProjectHistoryService {
         const entry = this.manifest(projectId, versionId)?.files[filePath];
         if (!entry || entry.size > MAX_TEXT_PREVIEW_BYTES)
             return null;
-        return fs.readFileSync(this.objectPath(projectId, entry.digest), "utf8");
+        return this.readStoredObject(projectId, entry.digest, filePath);
     }
     restore(projectId, versionId, filePathInput) {
         const manifest = this.manifest(projectId, versionId);
@@ -177,7 +262,7 @@ export class ProjectHistoryService {
             fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
             const temporary = `${target}.history-${randomUUID()}.tmp`;
             try {
-                fs.copyFileSync(this.objectPath(projectId, entry.digest), temporary);
+                this.copyStoredObject(projectId, entry.digest, filePath, temporary);
                 fs.chmodSync(temporary, 0o600);
                 fs.renameSync(temporary, target);
             }
@@ -272,8 +357,54 @@ export class ProjectHistoryService {
             throw new Error("Invalid history object digest");
         return path.join(outputRoot(this.config, projectId), ".texlite", "history", "objects", digest.slice(0, 2), digest);
     }
+    /**
+     * A history manifest can outlive a damaged or manually removed object. Keep
+     * that operational failure distinct from an absent path in the snapshot so
+     * the UI can tell the user why viewing or restoring it is impossible.
+     */
+    readStoredObject(projectId, digest, filePath) {
+        try {
+            return fs.readFileSync(this.objectPath(projectId, digest), "utf8");
+        }
+        catch (error) {
+            this.rethrowHistoryObjectError(error, filePath);
+        }
+    }
+    copyStoredObject(projectId, digest, filePath, target) {
+        try {
+            fs.copyFileSync(this.objectPath(projectId, digest), target);
+        }
+        catch (error) {
+            this.rethrowHistoryObjectError(error, filePath);
+        }
+    }
+    rethrowHistoryObjectError(error, filePath) {
+        const code = typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
+            ? error.code : "";
+        if (code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR") {
+            throw httpError(410, "HISTORY_OBJECT_MISSING", { path: filePath });
+        }
+        throw error;
+    }
+    storedObjectDigests(projectId) {
+        const objectsRoot = path.join(outputRoot(this.config, projectId), ".texlite", "history", "objects");
+        if (!fs.existsSync(objectsRoot))
+            return new Set();
+        const digests = new Set();
+        for (const prefix of fs.readdirSync(objectsRoot, { withFileTypes: true })) {
+            if (!prefix.isDirectory() || !/^[a-f0-9]{2}$/.test(prefix.name))
+                continue;
+            const prefixPath = path.join(objectsRoot, prefix.name);
+            for (const entry of fs.readdirSync(prefixPath, { withFileTypes: true })) {
+                if (entry.isFile() && /^[a-f0-9]{64}$/.test(entry.name) && entry.name.startsWith(prefix.name)) {
+                    digests.add(entry.name);
+                }
+            }
+        }
+        return digests;
+    }
     pruneVersions(projectId) {
-        const rows = this.db.prepare(`SELECT id, reason, label, manifest_json, created_at
+        const rows = this.db.prepare(`SELECT *
       FROM project_history_versions WHERE project_id = ?
       ORDER BY created_at DESC, rowid DESC`).all(projectId);
         if (!rows.length)
@@ -299,19 +430,22 @@ export class ProjectHistoryService {
                     sizeMap.set(file.digest, file.size);
             }
         }
-        let currentObjectBytes = 0;
+        let retainedBytes = rows.reduce((sum, row) => sum + historyMetadataBytes(row), 0)
+            + (baseline ? Buffer.byteLength(JSON.stringify(baseline), "utf8") : 0);
         for (const [digest, count] of refCounts.entries()) {
             if (count > 0)
-                currentObjectBytes += sizeMap.get(digest) ?? 0;
+                retainedBytes += sizeMap.get(digest) ?? 0;
         }
         const latestId = rows[0]?.id;
         // Ordinary versions eligible for version count capping (ordered newest to oldest)
         const ordinaryDesc = rows.filter((row) => row.label === null && row.reason !== "initial");
         const toDeleteIds = new Set();
+        const rowsById = new Map(rows.map((row) => [row.id, row]));
         const removeVersionRefs = (versionId) => {
             if (toDeleteIds.has(versionId))
                 return;
             toDeleteIds.add(versionId);
+            retainedBytes -= historyMetadataBytes(rowsById.get(versionId));
             const manifest = manifests.get(versionId);
             if (!manifest)
                 return;
@@ -320,7 +454,7 @@ export class ProjectHistoryService {
                 if (count !== undefined) {
                     if (count === 1) {
                         refCounts.set(file.digest, 0);
-                        currentObjectBytes -= sizeMap.get(file.digest) ?? 0;
+                        retainedBytes -= sizeMap.get(file.digest) ?? 0;
                     }
                     else if (count > 1) {
                         refCounts.set(file.digest, count - 1);
@@ -328,19 +462,19 @@ export class ProjectHistoryService {
                 }
             }
         };
-        // 1. Cap by historyMaxVersions (prune excess ordinary versions from newest to oldest offset)
-        if (ordinaryDesc.length > this.config.historyMaxVersions) {
+        // 1. Cap by historyMaxVersions (prune excess ordinary versions when configured; 0 = unlimited)
+        if (this.config.historyMaxVersions > 0 && ordinaryDesc.length > this.config.historyMaxVersions) {
             const obsolete = ordinaryDesc.slice(this.config.historyMaxVersions);
             for (const row of obsolete)
                 removeVersionRefs(row.id);
         }
         // 2. Cap by historyMaxStorageBytes (prune remaining eligible versions from oldest to newest)
-        if (currentObjectBytes > this.config.historyMaxStorageBytes) {
+        if (retainedBytes > this.config.historyMaxStorageBytes) {
             const remainingEligibleAsc = ordinaryDesc
                 .filter((row) => row.id !== latestId && !toDeleteIds.has(row.id))
                 .reverse();
             for (const row of remainingEligibleAsc) {
-                if (currentObjectBytes <= this.config.historyMaxStorageBytes)
+                if (retainedBytes <= this.config.historyMaxStorageBytes)
                     break;
                 removeVersionRefs(row.id);
             }
@@ -405,7 +539,7 @@ export class ProjectHistoryService {
             for (const [filePath, entry] of Object.entries(manifest.files)) {
                 const target = path.join(temporary, safeRelativePath(filePath));
                 fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
-                fs.copyFileSync(this.objectPath(projectId, entry.digest), target);
+                this.copyStoredObject(projectId, entry.digest, filePath, target);
                 fs.chmodSync(target, 0o600);
             }
             fs.renameSync(live, backup);
@@ -456,6 +590,34 @@ function parseStringArray(value) {
         return [];
     }
 }
+/**
+ * Keep cursors opaque so the public API is free to change its physical
+ * ordering later.  `rowid` breaks ties for snapshots written in the same
+ * millisecond, which is common for file operations touching multiple paths.
+ */
+function encodeHistoryCursor(row) {
+    return Buffer.from(JSON.stringify({ createdAt: row.created_at, rowId: row.history_rowid }), "utf8").toString("base64url");
+}
+function decodeHistoryCursor(value) {
+    // Cursors are generated by this service and normally only a few dozen
+    // characters long.  Bound input before decoding to keep malformed query
+    // strings cheap to reject.
+    if (value.length === 0 || value.length > 256)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+        const { createdAt, rowId } = parsed;
+        if (typeof createdAt !== "string" || typeof rowId !== "number" || !Number.isSafeInteger(rowId) || rowId <= 0)
+            return null;
+        const timestamp = Date.parse(createdAt);
+        return Number.isFinite(timestamp) && new Date(timestamp).toISOString() === createdAt
+            ? { createdAt, rowId }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
 function changedManifestPaths(previous, next) {
     const paths = new Set([...Object.keys(previous.files), ...Object.keys(next.files)]);
     return [...paths].filter((filePath) => previous.files[filePath]?.digest !== next.files[filePath]?.digest).sort();
@@ -465,6 +627,7 @@ function versionJson(row) {
     const files = Object.values(manifest.files);
     return {
         id: row.id,
+        snapshotHash: historySnapshotHash(row.manifest_json),
         reason: row.reason,
         label: row.label,
         createdAt: row.created_at,
@@ -478,3 +641,6 @@ function versionJson(row) {
         totalSize: files.reduce((sum, file) => sum + file.size, 0)
     };
 }
+function historySnapshotHash(manifestJson) {
+    return createHash("sha256").update(manifestJson, "utf8").digest("hex");
+}

package/dist/server/historyRetention.js

@@ -0,0 +1,37 @@
+/**
+ * Coalesces non-critical history retention work. A history version is already
+ * durable before this scheduler runs; delaying maintenance can only leave
+ * extra old versions/objects temporarily, never lose a recoverable version.
+ */
+export const HISTORY_RETENTION_DELAY_MS = 30_000;
+export class HistoryRetentionScheduler {
+    history;
+    timers = new Map();
+    delayMs;
+    onError;
+    constructor(history, options = {}) {
+        this.history = history;
+        this.delayMs = options.delayMs ?? HISTORY_RETENTION_DELAY_MS;
+        this.onError = options.onError;
+    }
+    schedule(projectId) {
+        if (this.timers.has(projectId))
+            return;
+        const timer = setTimeout(() => {
+            this.timers.delete(projectId);
+            try {
+                this.history.enforceRetention(projectId);
+            }
+            catch (error) {
+                this.onError?.(error, projectId);
+            }
+        }, this.delayMs);
+        timer.unref?.();
+        this.timers.set(projectId, timer);
+    }
+    dispose() {
+        for (const timer of this.timers.values())
+            clearTimeout(timer);
+        this.timers.clear();
+    }
+}