@harperfast/harper 5.3.0 → 5.3.1

package/dist/dataLayer/rocksdbBackup.js

@@ -62,6 +62,7 @@ exports.purgeBackupsOffline = purgeBackupsOffline;
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const promises_1 = require("node:fs/promises");
+const node_crypto_2 = require("node:crypto");
 const node_path_1 = require("node:path");
 const node_stream_1 = require("node:stream");
 const promises_2 = require("node:stream/promises");
@@ -70,6 +71,7 @@ const promises_3 = require("node:timers/promises");
 const tar_stream_1 = require("tar-stream");
 const rocksdb_js_1 = require("@harperfast/rocksdb-js");
 const databases_ts_1 = require("../resources/databases.js");
+const auditStore_ts_1 = require("../resources/auditStore.js");
 const blob_ts_1 = require("../resources/blob.js");
 const environmentManager_ts_1 = require("../utility/environment/environmentManager.js");
 const configUtils_ts_1 = require("../config/configUtils.js");
@@ -79,6 +81,8 @@ const hdbError_ts_1 = require("../utility/errors/hdbError.js");
 const signalling = __importStar(require("../utility/signalling.js"));
 const itc_js_1 = require("../server/threads/itc.js");
 const restoreMarker_ts_1 = require("./restoreMarker.js");
+const backupRepository_ts_1 = require("./backupRepository.js");
+const durableFile_ts_1 = require("../utility/durableFile.js");
 const blobBackup_ts_1 = require("./blobBackup.js");
 const backupManifest_ts_1 = require("./backupManifest.js");
 const harper_logger_ts_1 = __importDefault(require("../utility/logging/harper_logger.js"));
@@ -184,6 +188,31 @@ function requireRocksRootStore(databaseName, operation) {
     }
     return rootStore;
 }
+/**
+ * Apply the engine gate only when there is a loaded database to gate.
+ *
+ * A repository outlives its database. A restore that failed leaves the database blocked by its
+ * restoring marker with the repository intact, and a backup can be imported for a name that does not
+ * exist yet — both are exactly the states an operator needs list/verify/delete/purge for. Refusing
+ * them because no root store is loaded turns a recoverable situation into a filesystem intervention,
+ * which on Fabric the operator cannot perform at all. A name that is neither a loaded database nor a
+ * repository is still a 404, so a typo does not silently answer with an empty list.
+ */
+function requireBackupRepositoryAccess(databaseName, operation) {
+    const loaded = (0, databases_ts_1.getDatabases)()[databaseName];
+    if (loaded != null && Object.keys(loaded).length > 0) {
+        requireRocksRootStore(databaseName, operation);
+        return;
+    }
+    requireBackupRepositoryDirectory(databaseName);
+}
+function requireBackupRepositoryDirectory(databaseName) {
+    const backupDir = backupDirForDatabase(databaseName);
+    if (!(0, node_fs_1.existsSync)(backupDir)) {
+        throw new BackupNotFoundError(`Database '${databaseName}' is not loaded and has no backup repository at ${backupDir}`);
+    }
+    return backupDir;
+}
 function requireBackupId(backupId) {
     if (!Number.isSafeInteger(backupId) || backupId <= 0) {
         throw new hdbError_ts_1.ClientError(`'backup_id' must be a positive integer`);
@@ -208,10 +237,24 @@ function mapLockedError(error, databaseName) {
 }
 // --- directory helpers (operate on a backup directory only; no open database, usable offline) ---
 async function listBackupsInDir(backupDir) {
-    // the backup dir doesn't exist until the first create_backup
-    if (!(0, node_fs_1.existsSync)(backupDir))
+    // the backup dir doesn't exist until the first create_backup. pathPresent, not existsSync: an
+    // empty listing is what reconcileHarperManagedBackupFiles reads as "keep nothing", so a
+    // permission or I/O fault answering "absent" would license deleting every manifest and blob
+    // snapshot in a repository that is merely unreadable.
+    if (!(0, durableFile_ts_1.pathPresent)(backupDir))
         return [];
-    return rocksdb_js_1.backups.list(backupDir);
+    try {
+        return await rocksdb_js_1.backups.list(backupDir);
+    }
+    catch (error) {
+        // Taking the management lock creates the repository directory before anything has written
+        // engine metadata into it, so a directory with no metadata is an empty repository, not a
+        // failure — otherwise a purge on a database that never had a backup reports the binding's
+        // "meta is missing" instead of "no backups found".
+        if (!(0, durableFile_ts_1.pathPresent)((0, node_path_1.join)(backupDir, 'meta')))
+            return [];
+        throw error;
+    }
 }
 async function findBackup(backupDir, backupId, databaseName) {
     requireBackupId(backupId); // every id-taking path flows through here, including the offline CLI
@@ -280,6 +323,16 @@ async function resolveCompleteBackup(backupDir, requestedId, databaseName) {
     const latest = complete.reduce((a, b) => (b.backupId > a.backupId ? b : a));
     return { backupId: latest.backupId, manifest: { backupId: latest.backupId, blobs: latest.blobs, completedAt: 0 } };
 }
+/**
+ * Drop the Harper-managed files — blob snapshots and completion manifests — of every backup the
+ * engine no longer has. Derived from what survives rather than from what a caller believes it
+ * removed, so a delete or purge that failed partway through still leaves no orphans behind.
+ */
+async function reconcileHarperManagedBackupFiles(backupDir) {
+    const keepIds = new Set((await listBackupsInDir(backupDir)).map((backup) => backup.backupId));
+    await (0, blobBackup_ts_1.purgeBlobSnapshots)(backupDir, keepIds);
+    await (0, backupManifest_ts_1.purgeBackupManifests)(backupDir, keepIds);
+}
 /**
  * Publish a backup's completion manifest after the engine backup and (when included) blob snapshot
  * are durable. On failure, best-effort roll back the just-created engine backup, its partial blob
@@ -289,6 +342,13 @@ async function finalizeBackup(backupDir, backupId, databaseName, blobs) {
     try {
         if (blobs)
             await (0, blobBackup_ts_1.snapshotBlobs)(backupDir, backupId, (0, blob_ts_1.getBlobPathsForDatabaseName)(databaseName));
+        // Guards writers that do not take Harper's lock — an older binary, or a direct binding call.
+        // Harper's own purge cannot reach here: the whole create is one critical section.
+        // The manifest is what publishes a backup as usable, so writing one for engine files that are
+        // gone is the #2031 false-green shape: a backup that lists and verifies with nothing to restore.
+        if (!(await listBackupsInDir(backupDir)).some((backup) => backup.backupId === backupId)) {
+            throw new BackupNotFoundError(`Backup ${backupId} of database '${databaseName}' was removed while it was being finalized; rerun create_backup`);
+        }
         await (0, backupManifest_ts_1.writeBackupManifest)(backupDir, backupId, blobs);
     }
     catch (error) {
@@ -303,53 +363,20 @@ async function listBackups(request) {
     requireSuperUser(request, hdbTerms_ts_1.OPERATIONS_ENUM.LIST_BACKUPS);
     const databaseName = getDatabaseName(request);
     harper_logger_ts_1.default.info(`Listing backups for database '${databaseName}'`);
-    requireRocksRootStore(databaseName, hdbTerms_ts_1.OPERATIONS_ENUM.LIST_BACKUPS);
-    return (await listCompleteBackups(backupDirForDatabase(databaseName))).map((backup) => toBackupResponse(backup, backup.blobs));
+    requireBackupRepositoryAccess(databaseName, hdbTerms_ts_1.OPERATIONS_ENUM.LIST_BACKUPS);
+    return listBackupsOffline(databaseName);
 }
 async function deleteBackup(request) {
     requireSuperUser(request, hdbTerms_ts_1.OPERATIONS_ENUM.DELETE_BACKUP);
     const databaseName = getDatabaseName(request);
-    requireRocksRootStore(databaseName, hdbTerms_ts_1.OPERATIONS_ENUM.DELETE_BACKUP);
-    const backupId = requireBackupId(request.backup_id);
-    const backupDir = backupDirForDatabase(databaseName);
-    await findBackup(backupDir, backupId, databaseName);
-    try {
-        await rocksdb_js_1.backups.delete(backupDir, backupId);
-    }
-    catch (error) {
-        throw mapLockedError(error, databaseName);
-    }
-    // the engine's delete leaves the (Harper-managed) blob snapshot + manifest behind — remove them too
-    await (0, blobBackup_ts_1.deleteBlobSnapshot)(backupDir, backupId);
-    await (0, backupManifest_ts_1.deleteBackupManifest)(backupDir, backupId);
-    return { ok: true };
+    requireBackupRepositoryAccess(databaseName, hdbTerms_ts_1.OPERATIONS_ENUM.DELETE_BACKUP);
+    return deleteBackupOffline(databaseName, requireBackupId(request.backup_id));
 }
 async function purgeBackups(request) {
     requireSuperUser(request, hdbTerms_ts_1.OPERATIONS_ENUM.PURGE_BACKUPS);
     const databaseName = getDatabaseName(request);
-    requireRocksRootStore(databaseName, hdbTerms_ts_1.OPERATIONS_ENUM.PURGE_BACKUPS);
-    const keepCount = request.keep_count;
-    if (!Number.isSafeInteger(keepCount) || keepCount < 0) {
-        throw new hdbError_ts_1.ClientError(`'keep_count' must be a non-negative integer`);
-    }
-    const backupDir = backupDirForDatabase(databaseName);
-    const before = await listBackupsInDir(backupDir);
-    if (before.length === 0) {
-        throw new BackupNotFoundError(`No backups found for database '${databaseName}'`);
-    }
-    try {
-        await rocksdb_js_1.backups.purge(backupDir, keepCount);
-    }
-    catch (error) {
-        throw mapLockedError(error, databaseName);
-    }
-    const remainingBackups = await listBackupsInDir(backupDir);
-    // drop blob snapshots + manifests for every id the engine purged (keep only the survivors')
-    const keepIds = new Set(remainingBackups.map((backup) => backup.backupId));
-    await (0, blobBackup_ts_1.purgeBlobSnapshots)(backupDir, keepIds);
-    await (0, backupManifest_ts_1.purgeBackupManifests)(backupDir, keepIds);
-    // clamp: a concurrent create between the two lists can otherwise make this negative
-    return { deleted: Math.max(0, before.length - remainingBackups.length), remaining: remainingBackups.length };
+    requireBackupRepositoryAccess(databaseName, hdbTerms_ts_1.OPERATIONS_ENUM.PURGE_BACKUPS);
+    return purgeBackupsOffline(databaseName, request.keep_count);
 }
 // --- job operations: create_backup / verify_backup / restore_backup ---
 // Each has a synchronous-validation function (run by jobs.addJob before the job record is
@@ -366,15 +393,19 @@ async function createBackup(request) {
     const excludeBlobs = requireBooleanOption(request.exclude_blobs, 'exclude_blobs');
     const rootStore = requireRocksRootStore(databaseName, hdbTerms_ts_1.OPERATIONS_ENUM.CREATE_BACKUP);
     const backupDir = backupDirForDatabase(databaseName);
-    let backupId;
-    try {
-        backupId = await rootStore.backup(backupDir, { transactionLogs: true });
-    }
-    catch (error) {
-        throw mapLockedError(error, databaseName);
-    }
-    // snapshot blobs (unless excluded) then publish the completion manifest; rolls back on failure
-    await finalizeBackup(backupDir, backupId, databaseName, !excludeBlobs);
+    // One critical section, management lock before the engine call: a purge can neither remove the
+    // engine backup before the manifest publishes it nor shift which ids it would remove.
+    const backupId = await (0, backupRepository_ts_1.withBackupRepositoryLock)(backupDir, databaseName, async () => {
+        let id;
+        try {
+            id = await rootStore.backup(backupDir, { transactionLogs: true });
+        }
+        catch (error) {
+            throw mapLockedError(error, databaseName);
+        }
+        await finalizeBackup(backupDir, id, databaseName, !excludeBlobs);
+        return id;
+    }, true);
     await writeBackupReadme(backupDir, databaseName);
     return {
         database: databaseName,
@@ -457,7 +488,7 @@ Both remove the RocksDB backup and its blob snapshot.
 async function validateVerifyBackup(request) {
     requireSuperUser(request, hdbTerms_ts_1.OPERATIONS_ENUM.VERIFY_BACKUP);
     const databaseName = getDatabaseName(request);
-    requireRocksRootStore(databaseName, hdbTerms_ts_1.OPERATIONS_ENUM.VERIFY_BACKUP);
+    requireBackupRepositoryAccess(databaseName, hdbTerms_ts_1.OPERATIONS_ENUM.VERIFY_BACKUP);
     requireBooleanOption(request.verify_checksum, 'verify_checksum');
     const backupDir = backupDirForDatabase(databaseName);
     const backupId = requireBackupId(request.backup_id);
@@ -466,19 +497,8 @@ async function validateVerifyBackup(request) {
 }
 async function verifyBackup(request) {
     const databaseName = getDatabaseName(request);
-    requireRocksRootStore(databaseName, hdbTerms_ts_1.OPERATIONS_ENUM.VERIFY_BACKUP);
-    const backupId = requireBackupId(request.backup_id);
-    const verifyWithChecksum = requireBooleanOption(request.verify_checksum, 'verify_checksum');
-    const backupDir = backupDirForDatabase(databaseName);
-    await findBackup(backupDir, backupId, databaseName);
-    const manifest = await requireBackupComplete(backupDir, backupId, databaseName);
-    await rocksdb_js_1.backups.verify(backupDir, backupId, { verifyWithChecksum });
-    // verification covers the declared blob snapshot: a backup that recorded blobs must still have its
-    // snapshot directory (a manifest without its blobs is a corrupt backup)
-    if (manifest.blobs && !(0, node_fs_1.existsSync)((0, blobBackup_ts_1.blobSnapshotDir)(backupDir, backupId))) {
-        throw new hdbError_ts_1.ClientError(`Backup ${backupId} of database '${databaseName}' declares captured blobs but its blob snapshot is missing (corrupt backup)`);
-    }
-    return { database: databaseName, backup_id: backupId, ok: true, blobs: manifest.blobs };
+    requireBackupRepositoryAccess(databaseName, hdbTerms_ts_1.OPERATIONS_ENUM.VERIFY_BACKUP);
+    return verifyBackupOffline(databaseName, requireBackupId(request.backup_id), request.verify_checksum);
 }
 async function validateRestoreBackup(request) {
     requireSuperUser(request, hdbTerms_ts_1.OPERATIONS_ENUM.RESTORE_BACKUP);
@@ -543,9 +563,15 @@ async function restoreBackup(request) {
     // Once is enough: the decision reads the manifest and the opt-in, never the destination, so no
     // concurrent writer can change the answer between here and the purge.
     (0, blobBackup_ts_1.assertEngineOnlyRestoreAllowed)(databaseName, { backupHasBlobs: manifest.blobs, allowEngineOnly });
-    const lock = beginRestoreForDatabase(databaseDir, databaseName);
+    const pinId = restorePinId(databaseDir);
     const restoreToken = (0, node_crypto_1.randomUUID)();
     let destructionStarted = false;
+    // Re-check before replacing a previous attempt's claim; publish the new claim before the marker
+    // under both locks, so a crash cannot leave a marked database with an unprotected source.
+    const lock = await (0, backupRepository_ts_1.withBackupRepositoryLock)(backupDir, databaseName, async () => {
+        await findBackup(backupDir, backupId, databaseName);
+        return beginRestoreForDatabase(databaseDir, databaseName, () => (0, backupRepository_ts_1.pinBackup)(backupDir, pinId, backupId, `restore of database '${databaseName}'`, databaseDir));
+    });
     try {
         // Block new blob saves, drain in-flight saves, and close the database across all worker threads.
         // Each thread also rescans, and the restoring marker keeps it from reloading mid-restore.
@@ -568,6 +594,7 @@ async function restoreBackup(request) {
         if (manifest.blobs) {
             await (0, blobBackup_ts_1.restoreBlobSnapshot)(backupDir, backupId, databaseName, (0, blob_ts_1.getBlobPathsForDatabaseName)(databaseName));
         }
+        await (0, auditStore_ts_1.stampDatabaseDirectory)(databaseDir, { carriesLog: true });
     }
     catch (error) {
         // Leave the marker (so startup/rescan detection reports an incomplete restore until a rerun
@@ -577,6 +604,8 @@ async function restoreBackup(request) {
         // partial/corrupt data. Only a *fresh* marker on a *previously healthy* database that failed
         // before any destruction is safe to clear.
         if (destructionStarted || lock.preexisting) {
+            // The marker stays, so the database is unloadable until a rerun — and the rerun needs this
+            // backup. The pin stays with it, and lapses on its own once the marker is gone.
             (0, restoreMarker_ts_1.abandonRestore)(lock);
             // The restore is over even though it failed, so release the workers' blob fence. Without this
             // the fence outlives the attempt: the marker keeps the database from loading, but an operator
@@ -598,15 +627,36 @@ async function restoreBackup(request) {
         }
         // nothing destructive happened and the marker was fresh — clear it and let every thread reload
         // the intact database
-        (0, restoreMarker_ts_1.completeRestore)(lock);
+        releaseRestoreClaim(backupDir, pinId, lock, databaseName);
         await signalling.signalSchemaChange(restoreSchemaEvent(databaseName, 'reload', restoreToken, false));
         throw error;
     }
-    (0, restoreMarker_ts_1.completeRestore)(lock);
+    releaseRestoreClaim(backupDir, pinId, lock, databaseName);
     // signal again: with the marker gone, every thread's rescan reloads the restored database
     await signalling.signalSchemaChange(restoreSchemaEvent(databaseName, 'reload', restoreToken));
     return { database: databaseName, backup_id: backupId, ...(allowEngineOnly ? { allow_engine_only: true } : {}) };
 }
+/**
+ * Retire a finished restore: marker, then claim, then the destination lock. While the database is
+ * still marked a rerun is required and the rerun needs this backup, so the claim has to outlive the
+ * marker — a crash the other way round leaves an unloadable database whose source a purge may
+ * delete. Both happen under the restore lock, so no later attempt can have written a claim at this
+ * same id yet; one stranded after the marker is gone simply lapses and is swept.
+ */
+function releaseRestoreClaim(backupDir, pinId, lock, databaseName) {
+    try {
+        (0, restoreMarker_ts_1.clearRestoringMarker)(lock);
+        try {
+            (0, backupRepository_ts_1.unpinBackup)(backupDir, pinId);
+        }
+        catch (error) {
+            harper_logger_ts_1.default.error(`Could not release the backup claim after restoring '${databaseName}'; it lapses with the marker`, error);
+        }
+    }
+    finally {
+        (0, restoreMarker_ts_1.releaseRestoreLock)(lock);
+    }
+}
 /**
  * `restoreToken` identifies the restore that owns the blob fence. Two restores of the same database
  * can overlap, so a worker releases the fence only for the token that established it -- see
@@ -654,9 +704,16 @@ async function verifyDatabaseClosed(databaseDir, databaseName) {
  * beginRestore's own error message carries the filesystem path (useful in CLI/server logs);
  * client-facing operations report by database name instead.
  */
-function beginRestoreForDatabase(databaseDir, databaseName) {
+/**
+ * One pin per target database, not per attempt: two attempts can never collide on it, and a rerun
+ * after a failed restore reuses the claim the failed attempt left protecting its source.
+ */
+function restorePinId(databaseDir) {
+    return `restore-${(0, node_crypto_2.createHash)('sha256').update((0, node_path_1.resolve)(databaseDir)).digest('hex').slice(0, 32)}`;
+}
+function beginRestoreForDatabase(databaseDir, databaseName, beforePublishMarker) {
     try {
-        return (0, restoreMarker_ts_1.beginRestore)(databaseDir);
+        return (0, restoreMarker_ts_1.beginRestore)(databaseDir, beforePublishMarker);
     }
     catch (error) {
         if (error.statusCode === 409) {
@@ -943,14 +1000,17 @@ async function createBackupOffline(databaseName, excludeBlobs = false) {
     const database = rocksdb_js_1.RocksDatabase.open(databaseDir);
     try {
         const backupDir = backupDirForDatabase(databaseName);
-        let backupId;
-        try {
-            backupId = await database.backup(backupDir, { transactionLogs: true });
-        }
-        catch (error) {
-            throw mapLockedError(error, databaseName);
-        }
-        await finalizeBackup(backupDir, backupId, databaseName, !excludeBlobs);
+        const backupId = await (0, backupRepository_ts_1.withBackupRepositoryLock)(backupDir, databaseName, async () => {
+            let id;
+            try {
+                id = await database.backup(backupDir, { transactionLogs: true });
+            }
+            catch (error) {
+                throw mapLockedError(error, databaseName);
+            }
+            await finalizeBackup(backupDir, id, databaseName, !excludeBlobs);
+            return id;
+        }, true);
         await writeBackupReadme(backupDir, databaseName);
         return {
             database: databaseName,
@@ -992,10 +1052,13 @@ async function restoreBackupOffline(databaseName, backupId, targetDatabase, allo
     const blobRoots = (0, blob_ts_1.getBlobPathsForDatabaseName)(targetDatabase ?? databaseName);
     await (0, blobBackup_ts_1.assertBlobSnapshotRestorable)(backupDir, backupId, blobRoots);
     (0, blobBackup_ts_1.assertEngineOnlyRestoreAllowed)(targetDatabase ?? databaseName, { backupHasBlobs: manifest.blobs, allowEngineOnly });
-    // Take the restore lock + marker BEFORE probing so a server that starts after this point sees the
-    // marker and refuses to load the database (closing the window between the probe and the purge).
-    const lock = beginRestoreForDatabase(databaseDir, targetDatabase ?? databaseName);
+    const pinId = restorePinId(databaseDir);
     let destructionStarted = false;
+    // As online, claim before marking under both locks, and mark before probing the destination.
+    const lock = await (0, backupRepository_ts_1.withBackupRepositoryLock)(backupDir, databaseName, async () => {
+        await findBackup(backupDir, backupId, databaseName);
+        return beginRestoreForDatabase(databaseDir, targetDatabase ?? databaseName, () => (0, backupRepository_ts_1.pinBackup)(backupDir, pinId, backupId, `restore of database '${targetDatabase ?? databaseName}'`, databaseDir));
+    });
     try {
         // The offline path is entered only when the CLI sees no running server (getHdbPid), but that is
         // a heuristic: the PID file is briefly absent mid-`harper restart`, and backups.restore's
@@ -1023,15 +1086,19 @@ async function restoreBackupOffline(databaseName, backupId, targetDatabase, allo
         if (manifest.blobs) {
             await (0, blobBackup_ts_1.restoreBlobSnapshot)(backupDir, backupId, databaseName, (0, blob_ts_1.getBlobPathsForDatabaseName)(targetDatabase ?? databaseName));
         }
+        await (0, auditStore_ts_1.stampDatabaseDirectory)(databaseDir, { carriesLog: true });
     }
     catch (error) {
         // Preserve the marker on a destructive failure or a recovery over a pre-existing marker (see
         // the online restoreBackup for the rationale); otherwise clear the fresh marker so an intact,
         // merely-locked database is not left flagged as an incomplete restore.
+        // The pin stays exactly as long as the marker does: a retained marker means a rerun is required,
+        // and the rerun needs this backup to still be there.
         if (destructionStarted || lock.preexisting)
             (0, restoreMarker_ts_1.abandonRestore)(lock);
-        else
-            (0, restoreMarker_ts_1.completeRestore)(lock);
+        else {
+            releaseRestoreClaim(backupDir, pinId, lock, databaseName);
+        }
         // preserve typed client errors (e.g. the 409 lock probe) unwrapped; only wrap an opaque restore
         // failure after destruction has begun
         if (destructionStarted && !(error instanceof hdbError_ts_1.ClientError)) {
@@ -1039,7 +1106,7 @@ async function restoreBackupOffline(databaseName, backupId, targetDatabase, allo
         }
         throw error;
     }
-    (0, restoreMarker_ts_1.completeRestore)(lock);
+    releaseRestoreClaim(backupDir, pinId, lock, databaseName);
     return {
         database: databaseName,
         backup_id: backupId,
@@ -1057,7 +1124,10 @@ function isMissingOrEmptyDir(path) {
         throw error;
     }
 }
-// --- offline management wrappers (no engine validation: they operate on the directory only) ---
+// --- directory-only management implementations ---
+// What the CLI runs when the local server is stopped, and what the online operations delegate to
+// once their engine gate has passed. One implementation, so the two paths cannot drift, and so a
+// repository whose database is absent or blocked by a restore stays manageable.
 async function listBackupsOffline(databaseName) {
     validateDatabaseName(databaseName);
     // map to the same snake_case response shape as the online list_backups operation
@@ -1077,38 +1147,77 @@ async function verifyBackupOffline(databaseName, backupId, verifyChecksum) {
 }
 async function deleteBackupOffline(databaseName, backupId) {
     validateDatabaseName(databaseName);
-    const backupDir = backupDirForDatabase(databaseName);
-    await findBackup(backupDir, backupId, databaseName);
-    try {
-        await rocksdb_js_1.backups.delete(backupDir, backupId);
-    }
-    catch (error) {
-        throw mapLockedError(error, databaseName);
-    }
-    await (0, blobBackup_ts_1.deleteBlobSnapshot)(backupDir, backupId);
-    await (0, backupManifest_ts_1.deleteBackupManifest)(backupDir, backupId);
-    return { ok: true };
+    requireBackupId(backupId);
+    const backupDir = requireBackupRepositoryDirectory(databaseName);
+    return (0, backupRepository_ts_1.withBackupRepositoryLock)(backupDir, databaseName, async () => {
+        await findBackup(backupDir, backupId, databaseName);
+        (0, backupRepository_ts_1.assertBackupsUnpinned)(backupDir, [backupId], databaseName);
+        let engineSucceeded = false;
+        try {
+            await rocksdb_js_1.backups.delete(backupDir, backupId);
+            engineSucceeded = true;
+        }
+        catch (error) {
+            throw mapLockedError(error, databaseName);
+        }
+        finally {
+            // The engine's delete leaves the Harper-managed blob snapshot + manifest behind, and it can
+            // fail after removing engine files — so reconcile against what survives rather than assuming
+            // this id was the only thing that changed.
+            // Preserve a primary engine error, but never report success when cleanup failed.
+            await reconcileHarperManagedBackupFiles(backupDir).catch((error) => {
+                if (engineSucceeded)
+                    throw error;
+                harper_logger_ts_1.default.warn(`Could not reconcile Harper-managed backup files in ${backupDir}`, error);
+            });
+        }
+        return { ok: true };
+    });
 }
 async function purgeBackupsOffline(databaseName, keepCount) {
     validateDatabaseName(databaseName);
     if (!Number.isSafeInteger(keepCount) || keepCount < 0) {
         throw new hdbError_ts_1.ClientError(`'keep_count' must be a non-negative integer`);
     }
-    const backupDir = backupDirForDatabase(databaseName);
-    const before = await listBackupsInDir(backupDir);
-    if (before.length === 0) {
-        throw new BackupNotFoundError(`No backups found for database '${databaseName}'`);
-    }
-    try {
-        await rocksdb_js_1.backups.purge(backupDir, keepCount);
-    }
-    catch (error) {
-        throw mapLockedError(error, databaseName);
-    }
-    const remainingBackups = await listBackupsInDir(backupDir);
-    const keepIds = new Set(remainingBackups.map((backup) => backup.backupId));
-    await (0, blobBackup_ts_1.purgeBlobSnapshots)(backupDir, keepIds);
-    await (0, backupManifest_ts_1.purgeBackupManifests)(backupDir, keepIds);
-    return { deleted: Math.max(0, before.length - remainingBackups.length), remaining: remainingBackups.length };
+    const backupDir = requireBackupRepositoryDirectory(databaseName);
+    return (0, backupRepository_ts_1.withBackupRepositoryLock)(backupDir, databaseName, async () => {
+        const before = await listBackupsInDir(backupDir);
+        if (before.length === 0) {
+            throw new BackupNotFoundError(`No backups found for database '${databaseName}'`);
+        }
+        // Every Harper writer is excluded by this lock, so `before` is exactly what the binding will
+        // see, and `purge` keeps the newest `keepCount` by id — so the ids it will remove can be named
+        // here and checked against the claims before it runs. One bulk call then does the removal.
+        // Sorted rather than sliced off the listing as returned: this set gates claim protection, so it
+        // does not rest on the documented list order holding, matching resolveCompleteBackup below.
+        const removing = [...before]
+            .sort((first, second) => first.backupId - second.backupId)
+            .slice(0, Math.max(0, before.length - keepCount))
+            .map((backup) => backup.backupId);
+        (0, backupRepository_ts_1.assertBackupsUnpinned)(backupDir, removing, databaseName);
+        let engineSucceeded = false;
+        try {
+            await rocksdb_js_1.backups.purge(backupDir, keepCount);
+            engineSucceeded = true;
+        }
+        catch (error) {
+            throw mapLockedError(error, databaseName);
+        }
+        finally {
+            // Reconciled from what actually survives, in a finally: a purge that failed partway through
+            // still removed engine backups, and their blob snapshots would otherwise be orphaned on disk
+            // — invisible to list_backups and still charged to the tenant's quota.
+            // Preserve a primary engine error, but never report success when cleanup failed.
+            await reconcileHarperManagedBackupFiles(backupDir).catch((error) => {
+                if (engineSucceeded)
+                    throw error;
+                harper_logger_ts_1.default.warn(`Could not reconcile Harper-managed backup files in ${backupDir}`, error);
+            });
+        }
+        // Counted from what actually survives rather than from `removing`: no create can land inside
+        // this lock, so the difference is exactly what the purge removed.
+        const remaining = (await listBackupsInDir(backupDir)).length;
+        return { deleted: before.length - remaining, remaining };
+    });
 }
 //# sourceMappingURL=rocksdbBackup.js.map