@harperfast/harper 5.2.0-beta.4 → 5.2.1

package/dist/dataLayer/rocksdbBackup.js

@@ -0,0 +1,1039 @@
+'use strict';
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BackupInProgressError = exports.BackupNotFoundError = void 0;
+exports.getBackupsRoot = getBackupsRoot;
+exports.validateDatabaseName = validateDatabaseName;
+exports.backupDirForDatabase = backupDirForDatabase;
+exports.resolveSingleRootStore = resolveSingleRootStore;
+exports.listBackupsInDir = listBackupsInDir;
+exports.listBackups = listBackups;
+exports.deleteBackup = deleteBackup;
+exports.purgeBackups = purgeBackups;
+exports.validateCreateBackup = validateCreateBackup;
+exports.createBackup = createBackup;
+exports.validateVerifyBackup = validateVerifyBackup;
+exports.verifyBackup = verifyBackup;
+exports.validateRestoreBackup = validateRestoreBackup;
+exports.restoreBackup = restoreBackup;
+exports.createBackupStream = createBackupStream;
+exports.createBackupOffline = createBackupOffline;
+exports.restoreBackupOffline = restoreBackupOffline;
+exports.listBackupsOffline = listBackupsOffline;
+exports.verifyBackupOffline = verifyBackupOffline;
+exports.deleteBackupOffline = deleteBackupOffline;
+exports.purgeBackupsOffline = purgeBackupsOffline;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const node_stream_1 = require("node:stream");
+const promises_2 = require("node:stream/promises");
+const node_zlib_1 = require("node:zlib");
+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 blob_ts_1 = require("../resources/blob.js");
+const environmentManager_ts_1 = require("../utility/environment/environmentManager.js");
+const configUtils_ts_1 = require("../config/configUtils.js");
+const configHelpers_ts_1 = require("../config/configHelpers.js");
+const hdbTerms_ts_1 = require("../utility/hdbTerms.js");
+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 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"));
+/**
+ * Shared core for the RocksDB managed-backup operations (`create_backup`, `list_backups`,
+ * `verify_backup`, `delete_backup`, `purge_backups`, `restore_backup`) and the RocksDB path of
+ * `get_backup`. Used by both the operation API (running server) and the CLI (stopped server) so
+ * the two behave identically.
+ *
+ * Directory backups are confined to `<backupsRoot>/<database>/` where the backups root comes
+ * from the `storage.backupPath` config (default `<hdb_root>/backups`); operations never accept
+ * arbitrary filesystem paths.
+ */
+class BackupNotFoundError extends hdbError_ts_1.ClientError {
+    constructor(message) {
+        super(message, 404);
+        this.name = 'BackupNotFoundError';
+    }
+}
+exports.BackupNotFoundError = BackupNotFoundError;
+class BackupInProgressError extends hdbError_ts_1.ClientError {
+    constructor(message) {
+        super(message, 409);
+        this.name = 'BackupInProgressError';
+    }
+}
+exports.BackupInProgressError = BackupInProgressError;
+/**
+ * Enforce super_user for the managed-backup operations. These are whole-database administrative
+ * operations (not table-scoped), so they must never be delegable to a non-super_user role. The
+ * registered permission alone can't guarantee that: operation_authorization gate-2 authorizes any
+ * `requires_su` op placed in a role's `operations` allowlist without evaluating the declared table
+ * CRUD perms, so a non-SU role could otherwise reach these. Enforcing here — mirroring
+ * get_deployment_payload's requireSuperUser — closes that path regardless of the allowlist. For the
+ * job operations (create/verify/restore) this runs in the request-context validator, before any job
+ * record is created.
+ */
+function requireSuperUser(request, operationName) {
+    if (!request?.hdb_user?.role?.permission?.super_user) {
+        throw new hdbError_ts_1.ClientError(`Operation '${operationName}' is restricted to super_user roles`, 403);
+    }
+}
+function getBackupsRoot() {
+    const configured = (0, configUtils_ts_1.getConfigPath)(hdbTerms_ts_1.CONFIG_PARAMS.STORAGE_BACKUPPATH);
+    if (configured && typeof configured === 'string')
+        return configured;
+    // same <hdb_root>/backup directory as config-file backups; databases get subdirectories
+    return (0, configHelpers_ts_1.getBackupDirPath)((0, environmentManager_ts_1.getHdbBasePath)());
+}
+function getDatabaseName(request) {
+    const databaseName = request.database || request.schema || 'data';
+    validateDatabaseName(databaseName);
+    return databaseName;
+}
+/**
+ * The database name becomes a path segment under the backups root and the databases root —
+ * reject anything that could traverse outside them.
+ */
+function validateDatabaseName(databaseName) {
+    if (typeof databaseName !== 'string' || databaseName.length === 0) {
+        throw new hdbError_ts_1.ClientError(`'database' must be a non-empty string`);
+    }
+    if (databaseName.includes('/') ||
+        databaseName.includes('\\') ||
+        databaseName.includes('\0') ||
+        databaseName === '.' ||
+        databaseName === '..') {
+        throw new hdbError_ts_1.ClientError(`Invalid database name '${databaseName}'`);
+    }
+}
+function backupDirForDatabase(databaseName) {
+    validateDatabaseName(databaseName);
+    return (0, node_path_1.join)(getBackupsRoot(), databaseName);
+}
+/**
+ * Resolve the single root store for a database. A database can span multiple root stores when a
+ * table has a per-table `path` config; backing up such a database is not supported and errors
+ * descriptively. Engine gating (RocksDB vs LMDB) is done inline at each call site.
+ */
+function resolveSingleRootStore(databaseName) {
+    const database = (0, databases_ts_1.getDatabases)()[databaseName];
+    if (!database) {
+        throw new BackupNotFoundError(`Database '${databaseName}' does not exist`);
+    }
+    const rootStores = new Set();
+    for (const tableName in database) {
+        const rootStore = database[tableName]?.primaryStore?.rootStore;
+        if (rootStore)
+            rootStores.add(rootStore);
+    }
+    if (rootStores.size > 1) {
+        throw new hdbError_ts_1.ClientError(`Database '${databaseName}' spans multiple root stores (tables with a per-table 'path' config); backup operations only support single-root databases`);
+    }
+    if (rootStores.size === 0) {
+        throw new hdbError_ts_1.ClientError(`Database '${databaseName}' has no tables to back up`);
+    }
+    return rootStores.values().next().value;
+}
+function requireRocksRootStore(databaseName, operation) {
+    const rootStore = resolveSingleRootStore(databaseName);
+    if (!(rootStore instanceof rocksdb_js_1.RocksDatabase)) {
+        throw new hdbError_ts_1.ClientError(`Operation '${operation}' requires a RocksDB database; '${databaseName}' uses the LMDB storage engine (use 'get_backup' to download an LMDB backup)`);
+    }
+    return rootStore;
+}
+function requireBackupId(backupId) {
+    if (!Number.isSafeInteger(backupId) || backupId <= 0) {
+        throw new hdbError_ts_1.ClientError(`'backup_id' must be a positive integer`);
+    }
+    return backupId;
+}
+function requireBooleanOption(value, name) {
+    if (value !== undefined && typeof value !== 'boolean') {
+        throw new hdbError_ts_1.ClientError(`'${name}' must be a boolean`);
+    }
+    return value === true;
+}
+/**
+ * The binding serializes backup-directory writers with an on-disk `.backup.lock`; a concurrent
+ * writer rejects with a "locked" error. Map it to a descriptive 409 — fail fast, no queueing.
+ */
+function mapLockedError(error, databaseName) {
+    if (typeof error?.message === 'string' && error.message.includes('is locked')) {
+        return new BackupInProgressError(`Backup operation already in progress for database '${databaseName}'`);
+    }
+    return error;
+}
+// --- 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))
+        return [];
+    return rocksdb_js_1.backups.list(backupDir);
+}
+async function findBackup(backupDir, backupId, databaseName) {
+    requireBackupId(backupId); // every id-taking path flows through here, including the offline CLI
+    const list = await listBackupsInDir(backupDir);
+    const info = list.find((backup) => backup.backupId === backupId);
+    if (!info) {
+        throw new BackupNotFoundError(`Backup ${backupId} not found for database '${databaseName}'`);
+    }
+    return info;
+}
+/**
+ * Shape a rocksdb-js BackupInfo into the snake_case response the Operations API exposes — the
+ * binding's fields are camelCase, and `appMetadata` is internal, so it is not passed through.
+ * `blobs` reflects the completion manifest's recorded blob-inclusion policy.
+ */
+function toBackupResponse(info, blobs) {
+    return {
+        backup_id: info.backupId,
+        timestamp: info.timestamp,
+        size: info.size,
+        file_count: info.numberFiles,
+        blobs,
+    };
+}
+/**
+ * The engine backups in a directory that have a completion manifest — i.e. whose creation finished
+ * successfully. An engine backup without a manifest is incomplete (still being written, or a failed
+ * create) and is never listed or restored, so a blob snapshot that is mid-copy or absent-after-
+ * failure can't be mistaken for a healthy or intentionally-engine-only backup.
+ */
+async function listCompleteBackups(backupDir) {
+    const [engineBackups, manifests] = await Promise.all([listBackupsInDir(backupDir), (0, backupManifest_ts_1.readAllManifests)(backupDir)]);
+    const complete = [];
+    for (const info of engineBackups) {
+        const manifest = manifests.get(info.backupId);
+        if (manifest)
+            complete.push({ ...info, blobs: manifest.blobs });
+    }
+    return complete;
+}
+/**
+ * Load a specific backup's completion manifest, rejecting it as incomplete (409) when the engine
+ * backup exists but has no manifest — its creation did not finish, or is still in progress.
+ */
+async function requireBackupComplete(backupDir, backupId, databaseName) {
+    const manifest = await (0, backupManifest_ts_1.readBackupManifest)(backupDir, backupId);
+    if (!manifest) {
+        throw new BackupInProgressError(`Backup ${backupId} of database '${databaseName}' is incomplete (its creation did not finish or is still in progress); it cannot be restored or verified`);
+    }
+    return manifest;
+}
+/**
+ * Resolve which backup id a restore/verify should act on and load its completion manifest. A
+ * specific id that exists in the engine but has no manifest is rejected as incomplete; without a
+ * requested id, the latest *complete* backup is chosen.
+ */
+async function resolveCompleteBackup(backupDir, requestedId, databaseName) {
+    if (requestedId !== undefined) {
+        await findBackup(backupDir, requestedId, databaseName); // validates id + engine presence
+        return { backupId: requestedId, manifest: await requireBackupComplete(backupDir, requestedId, databaseName) };
+    }
+    const complete = await listCompleteBackups(backupDir);
+    if (complete.length === 0) {
+        throw new BackupNotFoundError(`No complete backups found for database '${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 } };
+}
+/**
+ * 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
+ * snapshot, and any manifest so an incomplete backup never lingers as usable.
+ */
+async function finalizeBackup(backupDir, backupId, databaseName, blobs) {
+    try {
+        if (blobs)
+            await (0, blobBackup_ts_1.snapshotBlobs)(backupDir, backupId, (0, blob_ts_1.getBlobPathsForDatabaseName)(databaseName));
+        await (0, backupManifest_ts_1.writeBackupManifest)(backupDir, backupId, blobs);
+    }
+    catch (error) {
+        await (0, backupManifest_ts_1.deleteBackupManifest)(backupDir, backupId).catch(() => { });
+        await (0, blobBackup_ts_1.deleteBlobSnapshot)(backupDir, backupId).catch(() => { });
+        await rocksdb_js_1.backups.delete(backupDir, backupId).catch(() => { });
+        throw error;
+    }
+}
+// --- synchronous operations ---
+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));
+}
+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 };
+}
+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 };
+}
+// --- job operations: create_backup / verify_backup / restore_backup ---
+// Each has a synchronous-validation function (run by jobs.addJob before the job record is
+// created) and the job function itself (run in the job worker thread).
+async function validateCreateBackup(request) {
+    requireSuperUser(request, hdbTerms_ts_1.OPERATIONS_ENUM.CREATE_BACKUP);
+    const databaseName = getDatabaseName(request);
+    requireBooleanOption(request.exclude_blobs, 'exclude_blobs');
+    requireRocksRootStore(databaseName, hdbTerms_ts_1.OPERATIONS_ENUM.CREATE_BACKUP);
+}
+async function createBackup(request) {
+    const databaseName = getDatabaseName(request);
+    // blobs are captured by default; exclude_blobs=true produces an engine-only backup
+    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);
+    await writeBackupReadme(backupDir, databaseName);
+    return {
+        database: databaseName,
+        backup_id: backupId,
+        blobs: !excludeBlobs,
+        ...(await describeBackup(backupDir, backupId)),
+    };
+}
+/**
+ * db.backup() returns only the id; size/timestamp come from a list() match. A missing match
+ * (e.g. a concurrent delete/purge between the two calls) is logged rather than silently
+ * reported as undefined fields.
+ */
+async function describeBackup(backupDir, backupId) {
+    const info = (await listBackupsInDir(backupDir)).find((backup) => backup.backupId === backupId);
+    if (!info) {
+        harper_logger_ts_1.default.warn(`Backup ${backupId} was created but is no longer listed in ${backupDir} (deleted concurrently?)`);
+        return {};
+    }
+    return { size: info.size, timestamp: info.timestamp };
+}
+/**
+ * Write a `README.md` into a database's backup directory with the commands to list, verify, and
+ * restore the backup, so the repository is recoverable without reading the source. Best-effort:
+ * a failure to write the doc must not fail an otherwise-successful backup. Overwritten on each
+ * create so it stays current.
+ */
+async function writeBackupReadme(backupDir, databaseName) {
+    const content = `# Harper backup — database "${databaseName}"
+
+This directory is a Harper-managed backup repository for the "${databaseName}" database: one or more
+RocksDB backups (engine data + transaction logs) and, unless created with \`exclude_blobs\`, a
+\`blobs/\` snapshot of the database's file-backed blobs (see blobs/README.md). It lives under
+\`storage.backupPath\` (default \`<rootPath>/backup\`), one directory per database. Do not edit these
+files by hand.
+
+## List / verify
+
+    harper list_backups database=${databaseName}
+    harper verify_backup database=${databaseName} backup_id=<id>
+
+## Restore
+
+Restore is destructive: it purges and rewrites the database directory — and every blob root — from
+the backup (blobs are restored automatically). Restore the latest backup in place:
+
+    harper restore_backup database=${databaseName}
+
+...or a specific id:
+
+    harper restore_backup database=${databaseName} backup_id=<id>
+
+A database held open by a loaded component — and always the \`system\` database — cannot be restored
+while Harper is running; stop the server and run the same command offline. Offline you can also
+restore into a *copy*, leaving the original untouched:
+
+    harper restore_backup database=${databaseName} target_database=${databaseName}-restore
+
+## Prune
+
+    harper delete_backup database=${databaseName} backup_id=<id>
+    harper purge_backups database=${databaseName} keep_count=<n>
+
+Both remove the RocksDB backup and its blob snapshot.
+`;
+    try {
+        await (0, promises_1.writeFile)((0, node_path_1.join)(backupDir, 'README.md'), content);
+    }
+    catch (error) {
+        harper_logger_ts_1.default.warn(`Failed to write backup README in ${backupDir}: ${error.message}`);
+    }
+}
+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);
+    requireBooleanOption(request.verify_checksum, 'verify_checksum');
+    const backupDir = backupDirForDatabase(databaseName);
+    const backupId = requireBackupId(request.backup_id);
+    await findBackup(backupDir, backupId, databaseName);
+    await requireBackupComplete(backupDir, backupId, databaseName);
+}
+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 };
+}
+async function validateRestoreBackup(request) {
+    requireSuperUser(request, hdbTerms_ts_1.OPERATIONS_ENUM.RESTORE_BACKUP);
+    const databaseName = getDatabaseName(request);
+    if (databaseName === 'system') {
+        throw new hdbError_ts_1.ClientError(`The 'system' database cannot be restored while Harper is running; stop the server and run: harper restore_backup database=system`);
+    }
+    if (request.target_database !== undefined) {
+        // silently ignoring this would destructively restore over the source database instead of
+        // the copy the caller asked for
+        throw new hdbError_ts_1.ClientError(`'target_database' is not supported while Harper is running (restore_backup always restores in place); stop the server and run: harper restore_backup database=${databaseName} target_database=<name>`);
+    }
+    const backupDir = backupDirForDatabase(databaseName);
+    if (request.backup_id !== undefined) {
+        const backupId = requireBackupId(request.backup_id);
+        await findBackup(backupDir, backupId, databaseName);
+        await requireBackupComplete(backupDir, backupId, databaseName);
+    }
+    else if ((await listCompleteBackups(backupDir)).length === 0) {
+        throw new BackupNotFoundError(`No complete backups found for database '${databaseName}'`);
+    }
+    // Only a loaded database that actually has tables can be validated as a single-root RocksDB
+    // store here (an empty/tableless database has no table to resolve a root store from, and an
+    // unloaded one recovering an interrupted restore isn't open yet); those cases are validated when
+    // the restore job runs. `Object.keys` skips the DEFINED_TABLES symbol, so an empty database is 0.
+    const loaded = (0, databases_ts_1.getDatabases)()[databaseName];
+    if (loaded != null && Object.keys(loaded).length > 0) {
+        requireRocksRootStore(databaseName, hdbTerms_ts_1.OPERATIONS_ENUM.RESTORE_BACKUP);
+    }
+}
+/**
+ * Online restore of a user database (see the design's restore lock + marker protocol):
+ * take the per-database restore lock, write the restoring marker, close the database across all
+ * worker threads, restore, delete the marker, release the lock, and reload everywhere.
+ */
+async function restoreBackup(request) {
+    const databaseName = getDatabaseName(request);
+    if (databaseName === 'system') {
+        throw new hdbError_ts_1.ClientError(`The 'system' database cannot be restored while Harper is running; stop the server and run: harper restore_backup database=system`);
+    }
+    if (request.target_database !== undefined) {
+        throw new hdbError_ts_1.ClientError(`'target_database' is not supported while Harper is running (restore_backup always restores in place); stop the server and run: harper restore_backup database=${databaseName} target_database=<name>`);
+    }
+    const backupDir = backupDirForDatabase(databaseName);
+    // choose the latest complete backup (or the requested id, rejected if incomplete); the manifest
+    // tells us whether blobs were captured so we restore them only when they were
+    const { backupId, manifest } = await resolveCompleteBackup(backupDir, request.backup_id === undefined ? undefined : requireBackupId(request.backup_id), databaseName);
+    // a loaded database *with tables* knows its real directory via its root store (which can differ
+    // from the computed default, e.g. legacy layouts); fall back to the computed path when the
+    // database is unloaded (recovering an interrupted restore) or empty (no table to resolve a root
+    // store from — Object.keys skips the DEFINED_TABLES symbol)
+    const loaded = (0, databases_ts_1.getDatabases)()[databaseName];
+    const databaseDir = loaded != null && Object.keys(loaded).length > 0
+        ? requireRocksRootStore(databaseName, hdbTerms_ts_1.OPERATIONS_ENUM.RESTORE_BACKUP).path
+        : (0, databases_ts_1.resolveDatabasePath)(databaseName);
+    // reject a backup with more blob roots than the current config *before* anything destructive —
+    // restoring it would mis-address blobs (records persist their root index)
+    await (0, blobBackup_ts_1.assertBlobSnapshotRestorable)(backupDir, backupId, (0, blob_ts_1.getBlobPathsForDatabaseName)(databaseName));
+    const lock = beginRestoreForDatabase(databaseDir, databaseName);
+    let destructionStarted = false;
+    try {
+        // close the database across all worker threads (each thread also rescans, and the
+        // restoring marker keeps the scan from reloading it mid-restore)
+        await signalling.signalSchemaChange(new itc_js_1.SchemaEventMsg(process.pid, hdbTerms_ts_1.OPERATIONS_ENUM.RESTORE_BACKUP, databaseName));
+        // A live component (or the system database) can hold its own handle on the database that
+        // Harper does not track and cannot close, so verify actual process-wide closure before
+        // purging — restoring under an open instance would corrupt it. If handles remain, fail
+        // with a clear pointer to the offline CLI path rather than purging.
+        await verifyDatabaseClosed(databaseDir, databaseName);
+        destructionStarted = true;
+        await rocksdb_js_1.backups.restore(backupDir, databaseDir, { backupId, mode: 'purgeAllFiles' });
+        // restore blobs only for a backup that captured them (an engine-only backup leaves the live
+        // blob roots untouched); the manifest, not the mere presence of a snapshot dir, is the source
+        // of truth so a mid-copy or absent snapshot can't be misread
+        if (manifest.blobs) {
+            await (0, blobBackup_ts_1.restoreBlobSnapshot)(backupDir, backupId, databaseName, (0, blob_ts_1.getBlobPathsForDatabaseName)(databaseName));
+        }
+    }
+    catch (error) {
+        // Leave the marker (so startup/rescan detection reports an incomplete restore until a rerun
+        // succeeds) when either the destructive purge has begun, OR this attempt was itself a recovery
+        // over a pre-existing marker: in that case the directory may already be half-purged from an
+        // earlier failed restore, so clearing the marker and reloading it as healthy would surface
+        // 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) {
+            (0, restoreMarker_ts_1.abandonRestore)(lock);
+            // wrap rather than mutate error.message: a frozen/library error can have a non-writable
+            // message (assigning it throws TypeError under 'use strict')
+            throw new Error(`Restore of database '${databaseName}' from backup ${backupId} failed (rerun restore_backup to recover): ${error.message}`, { cause: error });
+        }
+        // nothing destructive happened and the marker was fresh — clear it and let every thread reload
+        // the intact database
+        (0, restoreMarker_ts_1.completeRestore)(lock);
+        await signalling.signalSchemaChange(new itc_js_1.SchemaEventMsg(process.pid, hdbTerms_ts_1.OPERATIONS_ENUM.RESTORE_BACKUP, databaseName));
+        throw error;
+    }
+    (0, restoreMarker_ts_1.completeRestore)(lock);
+    // signal again: with the marker gone, every thread's rescan reloads the restored database
+    await signalling.signalSchemaChange(new itc_js_1.SchemaEventMsg(process.pid, hdbTerms_ts_1.OPERATIONS_ENUM.RESTORE_BACKUP, databaseName));
+    return { database: databaseName, backup_id: backupId };
+}
+// After the close broadcast is acknowledged, every worker thread has released its Harper-managed
+// handles; a short grace period covers a just-finished job worker still draining its own close.
+// Anything still open past that is a handle Harper neither tracks nor controls (a loaded component
+// holding its own instance, or the system database), which will never close on its own — so fail
+// fast rather than waiting out a long timeout.
+const DATABASE_CLOSE_WAIT_MS = 3000;
+const DATABASE_CLOSE_POLL_INTERVAL_MS = 250;
+/**
+ * Verify no thread in this process still has the database open (rocksdb-js's registry is
+ * process-global across worker threads), polling briefly to let a just-finished job worker's own
+ * close drain. Throws 409 with an actionable message if handles remain — which means a loaded
+ * component is holding the database open (Harper can neither detect which component nor force its
+ * handle closed), so an online in-place restore is not possible and the offline CLI is the path.
+ */
+async function verifyDatabaseClosed(databaseDir, databaseName) {
+    const targetPath = (0, node_path_1.resolve)(databaseDir);
+    const deadline = Date.now() + DATABASE_CLOSE_WAIT_MS;
+    for (;;) {
+        const stillOpen = (0, rocksdb_js_1.registryStatus)().some((instance) => (0, node_path_1.resolve)(instance.path) === targetPath && instance.refCount > 0);
+        if (!stillOpen)
+            return;
+        if (Date.now() >= deadline) {
+            throw new BackupInProgressError(`Cannot restore database '${databaseName}' while Harper is running: it is held open by a loaded component (or is the system database). ` +
+                `Restore it offline instead — stop the server and run: harper restore_backup database=${databaseName}` +
+                (databaseName === 'system' ? '' : ` backup_id=<id>`));
+        }
+        await (0, promises_3.setTimeout)(DATABASE_CLOSE_POLL_INTERVAL_MS);
+    }
+}
+/**
+ * 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) {
+    try {
+        return (0, restoreMarker_ts_1.beginRestore)(databaseDir);
+    }
+    catch (error) {
+        if (error.statusCode === 409) {
+            throw new BackupInProgressError(`Restore already in progress for database '${databaseName}'`);
+        }
+        throw error;
+    }
+}
+/**
+ * Recognize RocksDB's own on-disk `LOCK`-file contention error. The pinned rocksdb-js 2.5.0 binding
+ * surfaces it as a plain `Error` with no `code` and a message like
+ * `IO error: While lock file: <db>/LOCK: Resource temporarily unavailable`, so string-matching is
+ * the only signal available (there is no typed error to key on — a native primitive is a rocksdb-js
+ * follow-on). We match conservatively and fail *closed* on a hit so the offline restore never purges
+ * a database another process still has open.
+ */
+function isRocksDbLockError(error) {
+    const message = typeof error?.message === 'string' ? error.message : '';
+    return (/lock file:/i.test(message) ||
+        message.includes('LOCK:') ||
+        message.includes('Resource temporarily unavailable') ||
+        message.includes('is locked'));
+}
+// --- get_backup (RocksDB path): stream a fresh full-snapshot tar in the HTTP response ---
+/**
+ * Returns a Readable (with `.headers`) streaming a full-snapshot tar (optionally gzipped) of the
+ * database's current state. No scratch disk; a consumer error aborts the native backup cleanly.
+ * `noCompression` opts out of serverHandlers' accept-encoding auto-gzip — this response must never
+ * be compressed by the server.
+ *
+ * With blobs included (the default; `excludeBlobs` opts out), the database's file-backed blob roots
+ * are appended to the same archive under `blobs/<rootIndex>/<relpath>` so a downloaded backup is a
+ * complete Harper database. Blob capture is best-effort point-in-time (the archive contains whatever
+ * files exist while it streams); a blob deleted mid-stream is skipped.
+ */
+function createBackupStream(rootStore, databaseName, gzip, excludeBlobs = false) {
+    const stream = new node_stream_1.PassThrough();
+    // database names may legally contain `"` and `\` (schemaRegex) — sanitize so the quoted
+    // content-disposition filename stays parseable
+    const filename = `${databaseName.replace(/["\\]/g, '_')}.tar${gzip ? '.gz' : ''}`;
+    stream.headers = new Map([
+        ['content-type', gzip ? 'application/gzip' : 'application/x-tar'],
+        ['content-disposition', `attachment; filename="${filename}"`],
+    ]);
+    stream.noCompression = true;
+    if (excludeBlobs) {
+        // engine-only: the binding produces (and gzips) the whole archive directly
+        rootStore
+            .backup(node_stream_1.Writable.toWeb(stream), { gzip, transactionLogs: true })
+            .catch((error) => stream.destroy(error));
+        return stream;
+    }
+    streamBackupWithBlobs(rootStore, databaseName, gzip, stream).catch((error) => {
+        // the consumer aborting (destroying the response) is the common case, not an error to re-raise
+        if (!stream.destroyed)
+            stream.destroy(error);
+    });
+    return stream;
+}
+// The native streaming backup finalizes its tar with exactly two zero-filled 512-byte blocks (the
+// USTAR end-of-archive marker). To append blob entries into the same archive we drop that trailer
+// from the native tar and let tar-stream write the single real end-of-archive marker after the blob
+// entries.
+const TAR_TRAILER_BYTES = 1024;
+/**
+ * Stream a full-snapshot tar of the database followed by its blob roots as one archive. The native
+ * (plain) tar is streamed with its end-of-archive trailer stripped, blob files are appended as
+ * `blobs/<rootIndex>/<relpath>` entries via tar-stream, and the combined plain tar is gzipped here
+ * when requested (the binding is asked for a plain tar so we can append before compressing).
+ */
+async function streamBackupWithBlobs(rootStore, databaseName, gzip, out) {
+    const plain = new node_stream_1.PassThrough(); // the combined, uncompressed tar
+    const nativeTar = new node_stream_1.PassThrough(); // native (plain) tar, before its trailer is stripped
+    // consumer side: gzip the combined archive (or pass it through) into the response stream
+    const consumed = gzip ? (0, promises_2.pipeline)(plain, (0, node_zlib_1.createGzip)(), out) : (0, promises_2.pipeline)(plain, out);
+    // producer side: native plain tar → nativeTar, copied into `plain` minus its trailer
+    const nativeDone = rootStore.backup(node_stream_1.Writable.toWeb(nativeTar), { gzip: false, transactionLogs: true });
+    // A consumer that aborts (destroys `out`) rejects `consumed` before we reach the `await` below, so
+    // attach silent observers now to close the unhandled-rejection window; the awaits/allSettled still
+    // see the rejection and drive the real teardown.
+    consumed.catch(() => { });
+    nativeDone.catch(() => { });
+    try {
+        await copyDroppingTarTrailer(nativeTar, plain);
+        await nativeDone; // surface any native backup error before we append blobs
+        const pack = (0, tar_stream_1.pack)();
+        const packed = (0, promises_2.pipeline)(pack, plain); // ends `plain` once the blob entries + trailer are written
+        const blobRoots = (0, blob_ts_1.getBlobPathsForDatabaseName)(databaseName);
+        await appendBlobEntries(pack, blobRoots);
+        // generate the same self-documenting READMEs a managed backup writes to disk, on the fly
+        await addTextEntry(pack, 'README.md', streamedBackupReadme(databaseName));
+        await addTextEntry(pack, 'blobs/README.md', (0, blobBackup_ts_1.blobsReadmeContent)(blobRoots, { archive: true }));
+        pack.finalize();
+        await packed;
+        await consumed;
+    }
+    catch (error) {
+        // Tear down both pipelines and observe every side promise so a consumer abort (or any mid-
+        // stream failure) can never leave an unhandled rejection from `consumed`/`nativeDone`.
+        if (!nativeTar.destroyed)
+            nativeTar.destroy();
+        if (!plain.destroyed)
+            plain.destroy(error);
+        await Promise.allSettled([consumed, nativeDone]);
+        throw error;
+    }
+}
+/**
+ * Copy `src` into `dest` (without ending `dest`) while withholding the final {@link TAR_TRAILER_BYTES}
+ * bytes — the native tar's end-of-archive marker — so more entries can be appended. Verifies the
+ * withheld bytes are the expected all-zero trailer so a format change in the binding fails loudly
+ * rather than producing a silently-corrupt archive.
+ */
+async function copyDroppingTarTrailer(src, dest) {
+    let tail = Buffer.alloc(0);
+    for await (const chunk of src) {
+        tail = tail.length === 0 ? chunk : Buffer.concat([tail, chunk]);
+        if (tail.length > TAR_TRAILER_BYTES) {
+            const emit = tail.subarray(0, tail.length - TAR_TRAILER_BYTES);
+            tail = Buffer.from(tail.subarray(tail.length - TAR_TRAILER_BYTES));
+            await writeWithBackpressure(dest, emit);
+        }
+    }
+    if (tail.length !== TAR_TRAILER_BYTES || tail.some((byte) => byte !== 0)) {
+        throw new Error(`Unexpected trailer from native backup stream (expected ${TAR_TRAILER_BYTES} zero bytes, got ${tail.length}); cannot append blobs`);
+    }
+}
+/** Write to a stream, awaiting `drain` on backpressure and rejecting (rather than hanging) on error. */
+function writeWithBackpressure(dest, chunk) {
+    return new Promise((resolvePromise, reject) => {
+        if (dest.write(chunk))
+            return resolvePromise();
+        const cleanup = () => {
+            dest.off('drain', onDrain);
+            dest.off('error', onError);
+        };
+        const onDrain = () => {
+            cleanup();
+            resolvePromise();
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        dest.once('drain', onDrain);
+        dest.once('error', onError);
+    });
+}
+/**
+ * Append every blob file under the given blob roots to `pack` as `blobs/<rootIndex>/<relpath>`
+ * entries. Size is captured at open time and exactly that many bytes are streamed; a file that
+ * vanished before it could be opened (a concurrent blob delete) is skipped.
+ */
+async function appendBlobEntries(pack, blobRoots) {
+    for (let index = 0; index < blobRoots.length; index++) {
+        const root = blobRoots[index];
+        if (!(0, node_fs_1.existsSync)(root))
+            continue;
+        const stack = [root];
+        while (stack.length > 0) {
+            const dir = stack.pop();
+            let entries;
+            try {
+                entries = await (0, promises_1.readdir)(dir, { withFileTypes: true });
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                throw error;
+            }
+            for (const entry of entries) {
+                const filePath = (0, node_path_1.join)(dir, entry.name);
+                if (entry.isDirectory()) {
+                    stack.push(filePath);
+                }
+                else if (entry.isFile()) {
+                    // tar entry names are always POSIX-separated; relative() yields `\` on Windows, which
+                    // would otherwise become literal filename characters when extracted on POSIX
+                    const relativePath = (0, node_path_1.relative)(root, filePath).split(node_path_1.sep).join('/');
+                    await appendBlobFile(pack, filePath, `blobs/${index}/${relativePath}`);
+                }
+            }
+        }
+    }
+}
+/** Add a single file to the pack, streaming exactly the byte count captured at open time. */
+async function appendBlobFile(pack, filePath, name) {
+    let handle;
+    try {
+        handle = await (0, promises_1.open)(filePath, 'r');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return; // deleted mid-walk
+        throw error;
+    }
+    try {
+        const { size } = await handle.stat();
+        await new Promise((resolvePromise, reject) => {
+            const entry = pack.entry({ name, size }, (error) => (error ? reject(error) : resolvePromise()));
+            if (size === 0) {
+                entry.end();
+                return;
+            }
+            // stream exactly the bytes present at open time (end is inclusive); pin the fd open
+            // (autoClose:false) since the finally below closes the handle
+            const source = (0, node_fs_1.createReadStream)('', { fd: handle.fd, autoClose: false, start: 0, end: size - 1 });
+            source.on('error', (error) => entry.destroy(error));
+            source.pipe(entry);
+        });
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Add an in-memory string to the pack as a single tar entry (used for the generated READMEs). */
+async function addTextEntry(pack, name, content) {
+    const buffer = Buffer.from(content, 'utf8');
+    await new Promise((resolvePromise, reject) => {
+        const entry = pack.entry({ name, size: buffer.length }, (error) => (error ? reject(error) : resolvePromise()));
+        entry.end(buffer);
+    });
+}
+/**
+ * The top-level `README.md` embedded in a downloaded `get_backup` archive. Unlike a managed backup
+ * repository (which is restored in place via `restore_backup`), this is a raw snapshot tar restored
+ * by extracting its files back into the database directory and blob roots.
+ */
+function streamedBackupReadme(databaseName) {
+    return `# Harper backup archive — database "${databaseName}"
+
+A full point-in-time snapshot of the "${databaseName}" database, produced by \`get_backup\`:
+  - the RocksDB data and manifest at the archive root (CURRENT, MANIFEST-*, *.sst, OPTIONS-*)
+  - transaction_logs/ — the transaction log snapshot
+  - blobs/ — the database's file-backed blobs, unless this archive was created with exclude_blobs
+    (see blobs/README.md for the layout and the root-index mapping)
+
+## Restoring
+
+This is a raw snapshot archive, not a managed backup repository. To restore it, stop Harper and lay
+the files back down in two places:
+  1. The RocksDB files — everything except blobs/ — go into the database's directory
+     (typically <rootPath>/database/${databaseName}).
+  2. Each blobs/<rootIndex>/ tree goes into the matching blob root — the index maps to
+     storage.blobPaths[n], or <rootPath>/blobs/${databaseName} when blobPaths is not configured
+     (see blobs/README.md). Then start Harper.
+
+For a server-managed, in-place restore instead, use the managed backup workflow (create_backup /
+restore_backup): https://docs.harperdb.io/reference/v5/operations-api/operations
+`;
+}
+// --- offline CLI paths (server stopped) ---
+/**
+ * Offline create: open the RocksDatabase directly, run an ordinary incremental directory backup
+ * into the configured backup root, and close. RocksDB is single-writer, so this collides on the
+ * database lock if the server is running — callers guard on the server being stopped.
+ */
+async function createBackupOffline(databaseName, excludeBlobs = false) {
+    validateDatabaseName(databaseName);
+    const databaseDir = (0, databases_ts_1.resolveDatabasePath)(databaseName);
+    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(databaseDir, 'CURRENT'))) {
+        throw new BackupNotFoundError(`No RocksDB database found at ${databaseDir}`);
+    }
+    const restoreState = (0, restoreMarker_ts_1.checkRestoreState)(databaseDir);
+    if (restoreState !== 'clear') {
+        throw new BackupInProgressError(`Database '${databaseName}' has an ${restoreState === 'in-progress' ? 'active' : 'incomplete'} restore; rerun restore_backup before backing up`);
+    }
+    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);
+        await writeBackupReadme(backupDir, databaseName);
+        return {
+            database: databaseName,
+            backup_id: backupId,
+            blobs: !excludeBlobs,
+            ...(await describeBackup(backupDir, backupId)),
+        };
+    }
+    finally {
+        database.close();
+    }
+}
+/**
+ * Offline restore (required for the `system` database; works for any database). Runs the same
+ * lock + marker protocol as the online operation so a crashed CLI restore is detected at next
+ * server start. `targetDatabase` restores into a different database directory (non-destructive
+ * for the source database); the server picks it up on next start via normal engine detection.
+ */
+async function restoreBackupOffline(databaseName, backupId, targetDatabase) {
+    validateDatabaseName(databaseName);
+    const backupDir = backupDirForDatabase(databaseName);
+    // resolve to the latest complete backup (or the requested id, rejected if incomplete)
+    const resolved = await resolveCompleteBackup(backupDir, backupId, databaseName);
+    backupId = resolved.backupId;
+    const manifest = resolved.manifest;
+    if (targetDatabase !== undefined)
+        validateDatabaseName(targetDatabase);
+    const databaseDir = (0, databases_ts_1.resolveDatabasePath)(targetDatabase ?? databaseName);
+    if (targetDatabase !== undefined && targetDatabase !== databaseName && !isMissingOrEmptyDir(databaseDir)) {
+        // target_database is documented as non-destructive: never purge an existing database of
+        // that name out from under the operator
+        throw new hdbError_ts_1.ClientError(`target_database '${targetDatabase}' already exists at ${databaseDir}; restoring into it would destroy it — choose a new name, or restore in place by omitting target_database`);
+    }
+    // reject a backup with more blob roots than the target's current config before anything
+    // destructive (records persist their root index, so collapsing would mis-address blobs)
+    await (0, blobBackup_ts_1.assertBlobSnapshotRestorable)(backupDir, backupId, (0, blob_ts_1.getBlobPathsForDatabaseName)(targetDatabase ?? databaseName));
+    // 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);
+    let destructionStarted = false;
+    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
+        // purgeAllFiles never takes RocksDB's own lock. Probe that lock by opening the database — a live
+        // holder makes open throw its LOCK-file error (isRocksDbLockError) — so we fail closed rather
+        // than purge a database another process still has open. A directory that fails to open for any
+        // *other* reason (corrupt or half-restored) is exactly what restore recovers, so only a lock
+        // conflict aborts.
+        if ((0, node_fs_1.existsSync)((0, node_path_1.join)(databaseDir, 'CURRENT'))) {
+            let handle;
+            try {
+                handle = rocksdb_js_1.RocksDatabase.open(databaseDir);
+            }
+            catch (error) {
+                if (isRocksDbLockError(error)) {
+                    throw new BackupInProgressError(`Cannot restore database '${databaseName}': it is open by a running Harper process — stop Harper before restoring offline`);
+                }
+                // otherwise corrupt/half-restored — fall through and let restore recover it
+            }
+            handle?.close();
+        }
+        destructionStarted = true;
+        await rocksdb_js_1.backups.restore(backupDir, databaseDir, { backupId, mode: 'purgeAllFiles' });
+        // restore blobs only for a backup that captured them (per the manifest, not snapshot presence)
+        if (manifest.blobs) {
+            await (0, blobBackup_ts_1.restoreBlobSnapshot)(backupDir, backupId, databaseName, (0, blob_ts_1.getBlobPathsForDatabaseName)(targetDatabase ?? databaseName));
+        }
+    }
+    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.
+        if (destructionStarted || lock.preexisting)
+            (0, restoreMarker_ts_1.abandonRestore)(lock);
+        else
+            (0, restoreMarker_ts_1.completeRestore)(lock);
+        // 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)) {
+            throw new Error(`Restore of database '${databaseName}' from backup ${backupId} failed (rerun restore_backup to recover): ${error.message}`, { cause: error });
+        }
+        throw error;
+    }
+    (0, restoreMarker_ts_1.completeRestore)(lock);
+    return { database: databaseName, backup_id: backupId, restored_to: databaseDir };
+}
+function isMissingOrEmptyDir(path) {
+    try {
+        return (0, node_fs_1.readdirSync)(path).length === 0;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return true;
+        throw error;
+    }
+}
+// --- offline management wrappers (no engine validation: they operate on the directory only) ---
+async function listBackupsOffline(databaseName) {
+    validateDatabaseName(databaseName);
+    // map to the same snake_case response shape as the online list_backups operation
+    return (await listCompleteBackups(backupDirForDatabase(databaseName))).map((backup) => toBackupResponse(backup, backup.blobs));
+}
+async function verifyBackupOffline(databaseName, backupId, verifyChecksum) {
+    validateDatabaseName(databaseName);
+    const verifyWithChecksum = requireBooleanOption(verifyChecksum, '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 });
+    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 };
+}
+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 };
+}
+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 };
+}
+//# sourceMappingURL=rocksdbBackup.js.map