@harperfast/harper 5.2.0-beta.4 → 5.2.1

package/components/operationsValidation.js

@@ -18,6 +18,11 @@ const PROJECT_FILE_NAME_REGEX = /^[a-zA-Z0-9-_]+$/;
 // containing `=` or a newline) from injecting extra assignments into a .env file.
 const ENV_KEY_REGEX = /^[\w.-]+$/;
 
+// Compiled once and reused: a routing `host` is either a DNS hostname or a bare IPv6 literal, and
+// re-compiling these per validation call would allocate on every deploy_component.
+const HOSTNAME_SCHEMA = Joi.string().hostname();
+const IPV6_SCHEMA = Joi.string().ip({ version: 'ipv6' });
+
 module.exports = {
 	getDropCustomFunctionValidator,
 	setCustomFunctionValidator,
@@ -457,10 +462,33 @@ function deployComponentValidator(req) {
 			.min(1)
 			.custom((value, helpers) => {
 				if (value.includes('..')) return helpers.error('any.invalid');
+				// A component mount has no relative base and WHATWG clients strip '.' segments before
+				// sending the request, so a dot-segment mount would simply be unreachable.
+				if (value.split('/').includes('.')) return helpers.error('string.dotSegment');
+				return value;
+			})
+			.optional()
+			.messages({
+				'any.invalid': '{#label} must not contain ".."',
+				'string.dotSegment': '{#label} must not contain "." path segments',
+			}),
+		// Virtual hostname the component is served on. Like `urlPath`, this is deployment routing and
+		// belongs on the root-config entry, not in the component's own config.yaml. `hostname()`
+		// rejects a value carrying a port or path, which would never match the router's host compare.
+		// IPv6 literals are accepted in their bare form only — the router unwraps the brackets it
+		// finds in a Host header, so a bracketed value here would never match.
+		host: Joi.string()
+			.custom((value, helpers) => {
+				if (value.startsWith('[') || value.endsWith(']')) return helpers.error('string.bracketedHost');
 				return value;
 			})
+			.custom((value, helpers) => {
+				if (!HOSTNAME_SCHEMA.validate(value).error) return value;
+				// Accept a bare IPv6 literal, which `hostname()` rejects but the router can match.
+				return IPV6_SCHEMA.validate(value).error ? helpers.error('string.hostname') : value;
+			})
 			.optional()
-			.messages({ 'any.invalid': 'urlPath must not contain ".."' }),
+			.messages({ 'string.bracketedHost': '{#label} must not be bracketed; use the bare IPv6 literal' }),
 		// Deploy credentials. The array is kind-heterogeneous: an entry's kind is implied by its
 		// identifying key rather than a separate discriminator field, so a new kind is added as
 		// another item alternative here without reshaping the field. Today: npm registry auth
@@ -490,7 +518,9 @@ function deployComponentValidator(req) {
 		registryAuth: Joi.any().forbidden().messages({
 			'any.unknown': `'registryAuth' has been renamed to 'credentials'`,
 		}),
-	}).with('urlPath', 'package');
+	})
+		.with('urlPath', 'package')
+		.with('host', 'package');
 
 	return validator.validateBySchema(req, deployProjSchema);
 }

package/components/scopeMount.ts

@@ -0,0 +1,150 @@
+import Joi from 'joi';
+import { InvalidBaseURLPathError, resolveBaseURLPath } from './resolveBaseURLPath.ts';
+import harperLogger from '../utility/logging/harper_logger.ts';
+
+/**
+ * The routing an operator declared for an application in the *root* config, e.g.
+ *
+ * ```yaml
+ * my-app:
+ *   package: '@my/app'
+ *   host: api.example.com
+ *   urlPath: /v1
+ * ```
+ *
+ * Where an application is served is a deployment concern, not an application concern, so
+ * the root config is authoritative: a checked-in `config.yaml` cannot pin the hostname or
+ * mount point an operator has chosen. The mount reaches every plugin scope loaded for that
+ * application (and, transitively, plugins the application itself declares).
+ *
+ * The mount is applied at exactly one place: the routing boundary, where `Scope`'s `server`
+ * proxy registers a handler. The router strips it before the handler runs, so everything
+ * inside the application — entry URL paths, and the resource paths `graphqlSchema` and
+ * `jsResource` derive from them — stays mount-relative. Only code that emits an absolute URL
+ * back to the client (`Scope.externalBasePath`) or bypasses the routed chain (legacy fastify
+ * routes) needs to know the mount exists.
+ */
+export interface ScopeMount {
+	host?: string;
+	urlPath?: string;
+}
+
+export class InvalidMountPathError extends Error {
+	constructor(urlPath: string) {
+		super(`An application mount urlPath must be an absolute path without '.' or '..' segments. Received: '${urlPath}'`);
+	}
+}
+
+export class InvalidMountHostError extends Error {
+	constructor(host: string) {
+		super(
+			`An application mount host must be a bare hostname or IPv6 literal, with no scheme, port, or path. Received: '${host}'`
+		);
+	}
+}
+
+// Compiled once and reused, mirroring operationsValidation.js's deploy_component 'host' schema:
+// a routing host is either a DNS hostname or a bare IPv6 literal.
+const HOSTNAME_SCHEMA = Joi.string().hostname();
+const IPV6_SCHEMA = Joi.string().ip({ version: 'ipv6' });
+
+/**
+ * Normalizes a mount prefix to a leading-slash, no-trailing-slash form ('/v1'), or
+ * undefined when it constrains nothing ('', '/', undefined) — matching
+ * `middlewareChain.normalizeUrlPath`, so a mount that means "the root" composes to
+ * exactly the plugin's own path rather than rewriting it.
+ *
+ * Dot segments are rejected rather than resolved. A plugin's `urlPath` may be plugin-name
+ * relative ('./x'), but a mount has no such base, and WHATWG clients strip '.' segments
+ * before sending the request — a '/.'-prefixed route would simply be unreachable.
+ */
+export function normalizeMountPath(urlPath: string | undefined): string | undefined {
+	if (!urlPath) return undefined;
+	if (urlPath.includes('..')) throw new InvalidBaseURLPathError(urlPath);
+	let normalized = urlPath.startsWith('/') ? urlPath : `/${urlPath}`;
+	normalized = normalized.replace(/\/+$/, '');
+	if (normalized.split('/').includes('.')) throw new InvalidMountPathError(urlPath);
+	return normalized.length <= 1 ? undefined : normalized;
+}
+
+/**
+ * Hostnames are case-insensitive (RFC 4343) and clients send them lowercased, so a mount is
+ * held lowercased and compared that way. The bracket form of an IPv6 literal is unwrapped to
+ * match what the router extracts from the Host header.
+ *
+ * Validated against the same grammar as the `deploy_component` operation's `host` field (a bare
+ * DNS hostname or IPv6 literal) — the root config is hand-edited YAML with no equivalent gate,
+ * so a value that would never match a Host header (a port, a scheme, a path suffix, malformed
+ * IDN) must be rejected here rather than silently mounting the application unreachably.
+ */
+export function normalizeMountHost(host: string | undefined): string | undefined {
+	if (!host) return undefined;
+	const unbracketed = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+	const normalized = unbracketed.toLowerCase();
+	if (HOSTNAME_SCHEMA.validate(normalized).error && IPV6_SCHEMA.validate(normalized).error) {
+		throw new InvalidMountHostError(host);
+	}
+	return normalized;
+}
+
+/**
+ * Reads a mount off a root-config entry, or undefined when the entry declares no routing at
+ * all — so an unmounted application takes exactly the code path it did before mounts existed.
+ *
+ * `host`/`urlPath` present but not a string (e.g. `host: 9926`, a likely typo for a quoted
+ * value) is rejected rather than silently treated as absent: this fail-closed behavior only
+ * works if a wrong-typed value fails the same way a wrong-format one does (review finding) —
+ * `null`/`undefined` are still "not declared", since that's how YAML represents an omitted key.
+ */
+export function toScopeMount(config: unknown): ScopeMount | undefined {
+	if (!config || typeof config !== 'object') return undefined;
+	const { host, urlPath } = config as ScopeMount;
+	if (host !== undefined && host !== null && typeof host !== 'string') throw new InvalidMountHostError(String(host));
+	if (urlPath !== undefined && urlPath !== null && typeof urlPath !== 'string')
+		throw new InvalidMountPathError(String(urlPath));
+	const mountHost = normalizeMountHost(typeof host === 'string' ? host : undefined);
+	const mountPath = normalizeMountPath(typeof urlPath === 'string' ? urlPath : undefined);
+	if (!mountHost && !mountPath) return undefined;
+	return { host: mountHost, urlPath: mountPath };
+}
+
+/**
+ * Composes an application mount with a plugin's own `urlPath`.
+ *
+ * The plugin part is resolved first (`resolveBaseURLPath` semantics: `'.'`/`'./x'` namespace
+ * under the plugin name) and the mount is then prefixed, so app-internal structure survives
+ * relocation: mount `/v1` + `static: { urlPath: assets }` → `/v1/assets/`. Composing rather
+ * than replacing matters because a plugin's `urlPath` doubles as its app-internal base path;
+ * replacing it would silently relocate app-internal URLs and collapse distinct plugins onto
+ * one path. The result is already absolute and slash-terminated, making it a fixed point of
+ * `resolveBaseURLPath` — a consumer that resolves it again cannot compound the prefix.
+ */
+export function composeMountedUrlPath(
+	mountPath: string | undefined,
+	pluginName: string,
+	pluginUrlPath: string | undefined
+): string | undefined {
+	if (!mountPath) return pluginUrlPath;
+	return `${mountPath}${resolveBaseURLPath(pluginName, pluginUrlPath)}`;
+}
+
+/**
+ * Nests a child component's own mount inside the mount its parent application was given.
+ *
+ * The parent keeps hostname authority — a child cannot escape the host it is served on — while
+ * paths compose, so a parent at `/v1` containing a child mounted at `/child` puts the child at
+ * `/v1/child`. Returns whichever side is defined when only one is. A child `host` that differs
+ * from the parent's is silently discarded by that authority rule; logged so the operator who
+ * wrote it isn't left guessing why it had no effect.
+ */
+export function nestScopeMount(parent: ScopeMount | undefined, child: ScopeMount | undefined): ScopeMount | undefined {
+	if (!parent) return child;
+	if (!child) return parent;
+	if (parent.host && child.host && parent.host !== child.host) {
+		harperLogger.warn(
+			`Component mount host '${child.host}' is ignored because it is nested under an application mounted on host '${parent.host}' — a child's host cannot override its parent's.`
+		);
+	}
+	const urlPath = child.urlPath ? `${parent.urlPath ?? ''}${child.urlPath}` : parent.urlPath;
+	return { host: parent.host ?? child.host, urlPath: urlPath || undefined };
+}

package/config/configUtils.ts

@@ -7,7 +7,6 @@ import YAML from 'yaml';
 import path from 'path';
 import { threadId } from 'node:worker_threads';
 import { randomBytes } from 'node:crypto';
-import { performance } from 'node:perf_hooks';
 import isNumber from 'is-number';
 import propertiesReaderModule from 'properties-reader';
 import _ from 'lodash';
@@ -87,10 +86,15 @@ export function getConfigPath(param: string) {
 // Every worker thread runs its own RootConfigWatcher (chokidar), so a write on one thread
 // routinely races a hot-reload read on another; Windows Defender / AV real-time scanning can
 // hold a similar transient handle. Retry with exponential backoff to ride out the race -
-// callers are synchronous, so the wait is a synchronous busy-loop rather than a real sleep.
-const RENAME_RETRY_MAX_ATTEMPTS = 8;
+// callers are synchronous, so the wait is a synchronous sleep rather than an async one.
+// The budget must outlast a single AV real-time scan pass (seconds, not hundreds of ms):
+// the previous ~910ms budget was exhausted twice in a row by the same test on a CI runner
+// (harper#2036), so the worst case is now ~3.6s.
+const RENAME_RETRY_MAX_ATTEMPTS = 12;
 const RENAME_RETRY_INITIAL_DELAY_MS = 10;
-const RENAME_RETRY_MAX_DELAY_MS = 200;
+const RENAME_RETRY_MAX_DELAY_MS = 500;
+// Never notified; exists only so Atomics.wait can time out (a synchronous, CPU-idle sleep).
+const renameRetrySleepBuffer = new Int32Array(new SharedArrayBuffer(4));
 
 function atomicWriteFile(
 	filePath,
@@ -112,11 +116,10 @@ function atomicWriteFile(
 		} catch (err) {
 			if (retries > 0 && (err.code === 'EPERM' || err.code === 'EACCES')) {
 				retries--;
-				// Sleep synchronously (all call sites are sync) to allow the reader to close the
-				// file. Uses performance.now() rather than Date.now(): the latter tracks wall-clock
-				// time and can jump backward (NTP sync), which would turn this into an unbounded spin.
-				const start = performance.now();
-				while (performance.now() - start < delayMs) {}
+				// Sleep synchronously (all call sites are sync) to allow the holder to close the
+				// file. Atomics.wait yields the thread to the OS instead of spinning the CPU,
+				// which is what makes a multi-second worst-case budget affordable.
+				if (delayMs > 0) Atomics.wait(renameRetrySleepBuffer, 0, 0, delayMs);
 				delayMs = Math.min(delayMs * 2, maxDelayMs);
 				continue;
 			}

package/config-root.schema.json

@@ -470,6 +470,16 @@
 					],
 					"description": "Enable/Configure compression (LZ4). Default: true"
 				},
+				"rocks": {
+					"type": "object",
+					"additionalProperties": true,
+					"properties": {
+						"compression": {
+							"type": ["string", "null"],
+							"description": "RocksDB block and blob compression codec for every column family. Default: null (derive from storage.compression)."
+						}
+					}
+				},
 				"compactOnStart": { "type": "boolean", "description": "Compact non-system databases on start. Default: false" },
 				"compactOnStartKeepBackup": {
 					"type": "boolean",
@@ -486,6 +496,10 @@
 				},
 				"prefetchWrites": { "type": "boolean", "description": "Load data prior to write transactions. Default: true" },
 				"path": { "type": "string", "description": "Directory for all database files. Default: <rootPath>/database" },
+				"backupPath": {
+					"type": "string",
+					"description": "Directory for managed database backups (RocksDB directory backups created by create_backup), one subdirectory per database. Default: <rootPath>/backup"
+				},
 				"blobPaths": {
 					"oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }],
 					"description": "Path or array of paths for blob storage. Default: <rootPath>/blobs"

package/dataLayer/backupManifest.ts

@@ -0,0 +1,102 @@
+'use strict';
+
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Per-backup completion manifest for RocksDB managed backups.
+ *
+ * `create_backup` is two-phase: the engine backup (`rootStore.backup()`) resolves — and becomes
+ * visible to `list_backups`/`verify_backup`/`restore_backup` — before the blob snapshot is copied.
+ * Without a completion record, a blob-snapshot failure (or a crash between the two phases) leaves an
+ * engine backup on disk that lists and verifies as healthy while silently missing its blobs, and a
+ * concurrent restore could select a backup id whose blob snapshot is still being written and treat
+ * it as an intentional engine-only backup.
+ *
+ * A manifest at `<backupDir>/manifests/<backupId>.json` is written (atomically, temp + rename) only
+ * after *both* phases are durably in place, and records whether blobs were captured. Consumers treat
+ * a backup id with no manifest as incomplete — not usable for restore, and hidden from the listing.
+ * The `manifests/` directory is Harper-managed and ignored by the rocksdb-js binding (same as the
+ * sibling `blobs/` and `transaction_logs/` directories).
+ */
+
+const MANIFEST_DIR = 'manifests';
+
+export type BackupManifest = {
+	/** The RocksDB backup id this manifest completes. */
+	backupId: number;
+	/** Whether the backup captured the database's file-backed blobs (false = engine-only). */
+	blobs: boolean;
+	/** Epoch-ms timestamp when both phases completed. */
+	completedAt: number;
+};
+
+function manifestDir(backupDir: string): string {
+	return join(backupDir, MANIFEST_DIR);
+}
+
+function manifestPath(backupDir: string, backupId: number): string {
+	return join(manifestDir(backupDir), `${backupId}.json`);
+}
+
+/**
+ * Write a backup's completion manifest atomically. Call only after the engine backup and (when
+ * included) the blob snapshot are both durable — its presence is what marks the backup usable.
+ */
+export async function writeBackupManifest(backupDir: string, backupId: number, blobs: boolean): Promise<void> {
+	const dir = manifestDir(backupDir);
+	await mkdir(dir, { recursive: true });
+	const manifest: BackupManifest = { backupId, blobs, completedAt: Date.now() };
+	const tempPath = join(dir, `.tmp-${backupId}.json`);
+	await writeFile(tempPath, JSON.stringify(manifest));
+	await rename(tempPath, manifestPath(backupDir, backupId)); // atomic publish
+}
+
+/** Read a backup's completion manifest, or null when it has none (incomplete / not yet written). */
+export async function readBackupManifest(backupDir: string, backupId: number): Promise<BackupManifest | null> {
+	try {
+		return JSON.parse(await readFile(manifestPath(backupDir, backupId), 'utf8')) as BackupManifest;
+	} catch (error: any) {
+		if (error.code === 'ENOENT') return null;
+		throw error;
+	}
+}
+
+/** Whether a backup id has a completion manifest (i.e. its creation finished). */
+export function isBackupComplete(backupDir: string, backupId: number): boolean {
+	return existsSync(manifestPath(backupDir, backupId));
+}
+
+/** Remove a backup's manifest (paired with deleting the backup); best-effort. */
+export async function deleteBackupManifest(backupDir: string, backupId: number): Promise<void> {
+	await rm(manifestPath(backupDir, backupId), { force: true });
+}
+
+/** Remove manifests for every backup id not in `keepIds` (paired with `backups.purge`). */
+export async function purgeBackupManifests(backupDir: string, keepIds: Set<number>): Promise<void> {
+	const dir = manifestDir(backupDir);
+	if (!existsSync(dir)) return;
+	for (const name of await readdir(dir)) {
+		const match = /^(\d+)\.json$/.exec(name);
+		if (match && !keepIds.has(Number(match[1]))) await rm(join(dir, name), { force: true });
+	}
+}
+
+/**
+ * Read every completion manifest in a backup directory, keyed by backup id. Backup ids without a
+ * manifest (incomplete) are absent from the map. A manifest that fails to parse is skipped.
+ */
+export async function readAllManifests(backupDir: string): Promise<Map<number, BackupManifest>> {
+	const dir = manifestDir(backupDir);
+	const manifests = new Map<number, BackupManifest>();
+	if (!existsSync(dir)) return manifests;
+	for (const name of await readdir(dir)) {
+		const match = /^(\d+)\.json$/.exec(name);
+		if (!match) continue;
+		const backupId = Number(match[1]);
+		const manifest = await readBackupManifest(backupDir, backupId).catch(() => null);
+		if (manifest) manifests.set(backupId, manifest);
+	}
+	return manifests;
+}

package/dataLayer/blobBackup.ts

@@ -0,0 +1,286 @@
+'use strict';
+
+import { existsSync } from 'node:fs';
+import { copyFile, link, mkdir, readdir, rename, rm, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { ClientError } from '../utility/errors/hdbError.ts';
+import logger from '../utility/logging/harper_logger.ts';
+
+/**
+ * Managed-backup snapshotting of a database's file-backed blobs.
+ *
+ * A database's blobs live in one or more root directories *outside* the RocksDB directory (see
+ * `resources/blob.ts` `getBlobPathsForDatabaseName`), so the engine's own backup does not capture
+ * them. These helpers snapshot the blob roots alongside a RocksDB managed backup and restore them
+ * with it, so a restored database's records still resolve their file-backed blobs.
+ *
+ * Layout mirrors the binding's transaction-log snapshots (`<backupDir>/transaction_logs/<id>/`): a
+ * full, non-incremental copy per backup at `<backupDir>/blobs/<backupId>/<rootIndex>/<relpath>`,
+ * where `rootIndex` is the position of the source root in the database's blob-root list (preserved
+ * so a multi-root database restores each root back to its original slot). Files are hard-linked when
+ * possible (cheap, no extra space on the same filesystem) and copied otherwise (never symlinked, so
+ * a snapshot is a standalone set of files that survives independent of the live blob).
+ *
+ * Consistency is best-effort and point-in-time-ish, matching how the engine treats the transaction
+ * log: the walk captures whatever files exist at snapshot time. A blob deleted mid-walk is skipped;
+ * a blob being written mid-walk is captured as-is (a hard link shares the inode, so it reflects the
+ * writer's final bytes; a cross-filesystem copy captures the bytes present at copy time). Harper
+ * does not freeze blob writes for the duration of a backup.
+ *
+ * Hard-linking is safe against later mutation because Harper blobs are content-addressed and
+ * write-once: each write allocates a fresh monotonic file id (a new path), and an update or delete
+ * unlinks the old path rather than rewriting it in place — so a snapshot's hard link keeps the exact
+ * bytes alive even after the live blob is deleted, and no in-place overwrite can retroactively alter
+ * a snapshot.
+ */
+
+/** Directory holding all blob snapshots for a backup repository. */
+export function blobsRootDir(backupDir: string): string {
+	return join(backupDir, 'blobs');
+}
+
+/** Directory holding a single backup id's blob snapshot. */
+export function blobSnapshotDir(backupDir: string, backupId: number): string {
+	return join(blobsRootDir(backupDir), String(backupId));
+}
+
+/**
+ * Hard-link `src` to `dest`, falling back to a copy when the two are on different filesystems (or
+ * the filesystem does not support additional hard links). Never creates a symlink. A source that
+ * vanished mid-walk (a concurrent blob delete) is skipped rather than failing the whole snapshot.
+ */
+async function linkOrCopy(src: string, dest: string): Promise<void> {
+	await mkdir(dirname(dest), { recursive: true });
+	try {
+		await link(src, dest);
+	} catch (error: any) {
+		if (error.code === 'ENOENT') {
+			// src disappeared (concurrent delete) — nothing to snapshot
+			if (!existsSync(src)) return;
+			throw error;
+		}
+		if (
+			error.code === 'EXDEV' || // cross-device link
+			error.code === 'EMLINK' || // link count exhausted
+			error.code === 'EPERM' || // filesystem forbids hard links
+			error.code === 'ENOTSUP' ||
+			error.code === 'EOPNOTSUPP'
+		) {
+			await copyFile(src, dest);
+			return;
+		}
+		if (error.code === 'EEXIST') {
+			await unlink(dest);
+			await linkOrCopy(src, dest);
+			return;
+		}
+		throw error;
+	}
+}
+
+/**
+ * Recursively copy every file under `srcRoot` into `destRoot` (hard-link-else-copy), preserving the
+ * relative directory structure. Missing `srcRoot` is a no-op (a database with no blobs yet).
+ */
+async function copyTree(srcRoot: string, destRoot: string): Promise<void> {
+	if (!existsSync(srcRoot)) return;
+	const stack: string[] = [srcRoot];
+	while (stack.length > 0) {
+		const dir = stack.pop() as string;
+		let entries;
+		try {
+			entries = await readdir(dir, { withFileTypes: true });
+		} catch (error: any) {
+			if (error.code === 'ENOENT') continue; // directory removed mid-walk
+			throw error;
+		}
+		for (const entry of entries) {
+			const srcPath = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				stack.push(srcPath);
+			} else if (entry.isFile()) {
+				await linkOrCopy(srcPath, join(destRoot, relative(srcRoot, srcPath)));
+			}
+			// symlinks/other node types in a blob root are not expected and are intentionally skipped
+		}
+	}
+}
+
+/**
+ * Snapshot a database's blob roots into a backup's blob directory. Writes to a temporary sibling
+ * and atomically renames into place so a create_backup that fails mid-copy never leaves a partial
+ * `blobs/<backupId>/` that a later restore would trust. Overwrites any pre-existing snapshot for the
+ * same id (create_backup always produces a fresh id, so this only matters on a retried offline run).
+ */
+export async function snapshotBlobs(backupDir: string, backupId: number, blobRoots: string[]): Promise<void> {
+	const finalDir = blobSnapshotDir(backupDir, backupId);
+	const tempDir = join(blobsRootDir(backupDir), `.tmp-${backupId}`);
+	await rm(tempDir, { recursive: true, force: true });
+	await mkdir(tempDir, { recursive: true });
+	try {
+		for (let index = 0; index < blobRoots.length; index++) {
+			await copyTree(blobRoots[index], join(tempDir, String(index)));
+		}
+		await rm(finalDir, { recursive: true, force: true });
+		await rename(tempDir, finalDir);
+	} catch (error) {
+		await rm(tempDir, { recursive: true, force: true }).catch(() => {});
+		throw error;
+	}
+	await writeBlobsReadme(backupDir, blobRoots);
+}
+
+/**
+ * Build the `blobs/README.md` documenting the blob snapshot layout, so an operator inspecting or
+ * hand-recovering a backup can decode the numeric directories. Two variants:
+ * - managed (default): a create_backup repository, where snapshots are keyed by backup id
+ *   (`<backupId>/<rootIndex>/…`) and restore is automatic via `restore_backup`.
+ * - archive (`archive: true`): a downloaded `get_backup` tar, which holds a single snapshot with no
+ *   backup-id level (`<rootIndex>/…`) and is restored by extracting the files back into the roots.
+ */
+export function blobsReadmeContent(blobRoots: string[], { archive = false }: { archive?: boolean } = {}): string {
+	const rootMapping =
+		blobRoots.length > 0 ? blobRoots.map((root, index) => `      ${index} -> ${root}`).join('\n') : '      (none)';
+	const layout = archive
+		? '<rootIndex>/<shard1>/<shard2>/<fileId>'
+		: '<backupId>/<rootIndex>/<shard1>/<shard2>/<fileId>';
+	const intro = archive
+		? `This directory holds this database's file-backed blobs within a downloaded \`get_backup\` archive.
+To restore them, extract each \`<rootIndex>/\` tree back into the matching blob root (see the mapping
+below and ../README.md).`
+		: `This directory holds point-in-time snapshots of this database's file-backed blobs, captured
+alongside each RocksDB managed backup. You do not restore these by hand — \`restore_backup\` puts
+them back automatically (see ../README.md); this file just documents the layout.`;
+	const backupIdBullet = archive
+		? ''
+		: `- **<backupId>** matches the RocksDB backup id (\`harper list_backups\`). Each id is a full,
+  independent snapshot (not incremental).
+`;
+	return `# Harper blob snapshots
+
+${intro}
+
+## Directory layout
+
+    ${layout}
+
+${backupIdBullet}- **<rootIndex>** is which of the database's blob roots the file came from — the index into
+  \`storage.blobPaths[n]\`. When \`storage.blobPaths\` is not configured there is a single default root
+  (\`<rootPath>/blobs/<db>\`) at index 0. Current mapping for this backup:
+
+${rootMapping}
+
+- **<shard1>/<shard2>/<fileId>** is Harper's on-disk blob layout, copied verbatim from the live
+  root: the hex blob file id split into two directory levels plus the file itself (keeping roughly
+  4096 entries per directory). E.g. a blob with id \`0x12345678\` lives at \`12/345/678\`; a short id
+  like \`0xc1a\` lives at \`0/0/c1a\`.
+
+Files are hard links to the live blobs when the backup is on the same filesystem, and copies
+otherwise.
+`;
+}
+
+/**
+ * Write the `blobs/README.md` into a managed backup's `blobs/` directory. Best-effort: a failure to
+ * write the doc must not fail an otherwise-successful backup.
+ */
+export async function writeBlobsReadme(backupDir: string, blobRoots: string[]): Promise<void> {
+	try {
+		await writeFile(join(blobsRootDir(backupDir), 'README.md'), blobsReadmeContent(blobRoots));
+	} catch (error) {
+		logger.warn(`Failed to write blob snapshot README in ${backupDir}: ${(error as Error).message}`);
+	}
+}
+
+/** The blob-root indices present in a snapshot (sorted); [] when the backup has no blob snapshot. */
+async function snapshotRootIndices(snapshotDir: string): Promise<number[]> {
+	if (!existsSync(snapshotDir)) return [];
+	return (await readdir(snapshotDir, { withFileTypes: true }))
+		.filter((entry) => entry.isDirectory() && /^\d+$/.test(entry.name))
+		.map((entry) => Number(entry.name))
+		.sort((a, b) => a - b);
+}
+
+/**
+ * Reject (before any destructive step) a restore whose snapshot has more blob roots than the
+ * database is currently configured with. File-backed blob references persist their `storageIndex`,
+ * so a record written under root index 1 keeps resolving through `blobRoots[1]`; collapsing the
+ * out-of-range index onto another root would preserve the bytes at the wrong address and the restore
+ * would "succeed" while reads of those blobs fail. The operator must reconcile `storage.blobPaths`
+ * to at least as many roots as the backup before restoring. Callers invoke this ahead of the engine
+ * restore so a mismatch never purges the database.
+ */
+export async function assertBlobSnapshotRestorable(
+	backupDir: string,
+	backupId: number,
+	blobRoots: string[]
+): Promise<void> {
+	const indices = await snapshotRootIndices(blobSnapshotDir(backupDir, backupId));
+	const maxIndex = indices.length > 0 ? indices[indices.length - 1] : -1;
+	if (maxIndex >= blobRoots.length) {
+		throw new ClientError(
+			`Cannot restore backup ${backupId}: it captured ${maxIndex + 1} blob root(s) but the database is now configured with ${blobRoots.length}. ` +
+				`Blob references persist their root index, so restoring would mis-address blobs — set 'storage.blobPaths' to at least ${maxIndex + 1} root(s) before restoring.`
+		);
+	}
+}
+
+/**
+ * Restore a backup's blob snapshot back into the database's blob roots. Each root is purged and
+ * rewritten from `blobs/<backupId>/<rootIndex>/` so the restored blob set matches the backup exactly
+ * (a newer blob written after the backup is removed, mirroring the engine's `purgeAllFiles` restore).
+ *
+ * A backup created with blobs excluded (or an older backup that predates blob snapshots) has no
+ * snapshot directory: in that case the live blob roots are left untouched and a warning is logged,
+ * since purging them would strip blobs the restored records may still reference. Roots are restored
+ * by index into the *same* configured root; an incompatible root count is rejected up front (see
+ * `assertBlobSnapshotRestorable`) rather than collapsed, so blobs are never mis-addressed.
+ */
+export async function restoreBlobSnapshot(
+	backupDir: string,
+	backupId: number,
+	databaseName: string,
+	blobRoots: string[]
+): Promise<void> {
+	const snapshotDir = blobSnapshotDir(backupDir, backupId);
+	if (!existsSync(snapshotDir)) {
+		logger.warn(
+			`Backup ${backupId} of database '${databaseName}' has no blob snapshot; leaving existing blob files in place (this backup did not include blobs)`
+		);
+		return;
+	}
+	// defense in depth: the restore flow pre-checks before the engine restore, but re-validate here
+	// so this function never mis-addresses blobs regardless of caller
+	await assertBlobSnapshotRestorable(backupDir, backupId, blobRoots);
+	const indexDirs = await snapshotRootIndices(snapshotDir);
+	// purge every current blob root first so nothing newer than the backup survives the restore
+	for (const root of blobRoots) {
+		await rm(root, { recursive: true, force: true });
+	}
+	for (const index of indexDirs) {
+		await copyTree(join(snapshotDir, String(index)), blobRoots[index]);
+	}
+}
+
+/**
+ * Remove the blob snapshot for a single backup id (paired with `backups.delete`). Best-effort:
+ * a missing snapshot directory is fine.
+ */
+export async function deleteBlobSnapshot(backupDir: string, backupId: number): Promise<void> {
+	await rm(blobSnapshotDir(backupDir, backupId), { recursive: true, force: true });
+}
+
+/**
+ * Remove blob snapshots for every backup id not in `keepIds` (paired with `backups.purge`, which
+ * reference-counts and removes the engine files; blob snapshots are full per-id copies, so they are
+ * simply deleted). Given the ids that survive the purge, this deletes the rest.
+ */
+export async function purgeBlobSnapshots(backupDir: string, keepIds: Set<number>): Promise<void> {
+	const root = blobsRootDir(backupDir);
+	if (!existsSync(root)) return;
+	for (const entry of await readdir(root, { withFileTypes: true })) {
+		if (!entry.isDirectory() || !/^\d+$/.test(entry.name)) continue;
+		if (keepIds.has(Number(entry.name))) continue;
+		await rm(join(root, entry.name), { recursive: true, force: true });
+	}
+}