@harperfast/harper 5.2.0-beta.4 → 5.2.0

package/components/componentLoader.ts

@@ -29,6 +29,7 @@ import * as scheduler from '../resources/scheduler/scheduler.ts';
 import { restartWorkers, getWorkerIndex } from '../server/threads/manageThreads.js';
 import { resetRestartNeeded, subscribeToRestartRequests } from './requestRestart.ts';
 import { trackScopeClose } from './scopeShutdown.ts';
+import { toScopeMount, nestScopeMount, type ScopeMount } from './scopeMount.ts';
 import { scopedImport } from '../security/jsLoader.ts';
 import { server } from '../server/Server.ts';
 import { Resources } from '../resources/Resources.ts';
@@ -63,6 +64,51 @@ let resources;
  * @param loadedPluginModules
  * @param loadedResources
  */
+/**
+ * The application mount an operator declared for `appName` in the root config.
+ *
+ * Applications in the components root are loaded by directory scan, not from a root-config
+ * entry, so this is what makes a root-config entry authoritative for where an app is served:
+ *
+ * ```yaml
+ * my-app:
+ *   host: api.example.com
+ *   urlPath: /v1
+ * ```
+ *
+ * Works whether or not the entry also carries `package` — a payload-deployed app is mounted the
+ * same way as an installed one. A built-in plugin's config block is never an application mount;
+ * those keys (`http`, `mqtt`, …) configure the plugin itself.
+ */
+function rootConfigMount(appName: string): ScopeMount | undefined {
+	if (Object.hasOwn(TRUSTED_RESOURCE_PLUGINS, appName)) return undefined;
+	return toScopeMount(getConfigObj()?.[appName]);
+}
+
+/**
+ * Resolves the mount for `appName`, or reports the failure and returns `undefined` if the
+ * configured `host`/`urlPath` is invalid. The caller must skip loading the application in that
+ * case rather than loading it anyway: an invalid mount is a request to CONSTRAIN where the app is
+ * served, so loading it unconstrained would silently drop the isolation the operator configured
+ * (review finding) — worse than not loading it at all. Isolated per-app so one bad mount doesn't
+ * take down every other application's load.
+ */
+function tryRootConfigMount(appName: string): { ok: true; mount: ScopeMount | undefined } | { ok: false } {
+	try {
+		return { ok: true, mount: rootConfigMount(appName) };
+	} catch (error) {
+		(error as Error).message = `Not loading '${appName}': invalid routing configured: ${(error as Error).message}`;
+		errorReporter?.(error);
+		(getWorkerIndex() === 0 ? console : harperLogger).error(errorForLog(error as Error));
+		componentLifecycle.failed(
+			appName,
+			error as Error,
+			`Component '${appName}' failed to load due to invalid routing configuration`
+		);
+		return { ok: false };
+	}
+}
+
 export async function loadComponentDirectories(loadedPluginModules?: Map<any, any>, loadedResources?: Resources) {
 	if (loadedResources) resources = loadedResources;
 	if (loadedPluginModules) loadedComponents = loadedPluginModules;
@@ -81,21 +127,32 @@ export async function loadComponentDirectories(loadedPluginModules?: Map<any, an
 			if (appEntry.name.startsWith('.')) continue;
 			const appName = appEntry.name;
 			const appFolder = join(CF_ROUTES_DIR, appName);
+			const mountResult = tryRootConfigMount(appName);
+			if (!mountResult.ok) continue;
 			cfsLoaded.push(
-				loadComponent(appFolder, resources, HDB_ROOT_DIR_NAME, { isRoot: false, autoReload: false, appName })
+				loadComponent(appFolder, resources, HDB_ROOT_DIR_NAME, {
+					isRoot: false,
+					autoReload: false,
+					appName,
+					mount: mountResult.mount,
+				})
 			);
 		}
 	}
 	const hdbAppFolder = process.env.RUN_HDB_APP;
 	if (hdbAppFolder) {
 		if (getWorkerIndex() === 0) harperLogger.info?.('Loading application from ' + hdbAppFolder);
-		cfsLoaded.push(
-			loadComponent(hdbAppFolder, resources, hdbAppFolder, {
-				isRoot: false,
-				autoReload: Boolean(process.env.DEV_MODE),
-				appName: hdbAppFolder,
-			})
-		);
+		const mountResult = tryRootConfigMount(basename(hdbAppFolder));
+		if (mountResult.ok) {
+			cfsLoaded.push(
+				loadComponent(hdbAppFolder, resources, hdbAppFolder, {
+					isRoot: false,
+					autoReload: Boolean(process.env.DEV_MODE),
+					appName: hdbAppFolder,
+					mount: mountResult.mount,
+				})
+			);
+		}
 	}
 	return Promise.all(cfsLoaded).then(() => {
 		watchesSetup = true;
@@ -316,6 +373,10 @@ export interface LoadComponentOptions {
 	// (e.g. the deploy pre-flight validation) so their deploy-lifecycle listeners don't accumulate
 	// across deploys (#1462).
 	collectScopes?: Set<Scope>;
+	// Routing the operator declared for this application in the root config (`host`/`urlPath` on
+	// the application's entry). Applied to every plugin scope this load creates, and inherited by
+	// components the application itself declares, so the whole subtree moves together.
+	mount?: ScopeMount;
 }
 
 /**
@@ -342,6 +403,7 @@ export async function loadComponent(
 		isRoot,
 		autoReload,
 		appName,
+		mount,
 	} = options;
 	applicationScope.allowedPath ??= realpathSync(componentDirectory);
 	if (providedLoadedComponents) loadedComponents = providedLoadedComponents;
@@ -485,6 +547,13 @@ export async function loadComponent(
 								autoReload: false,
 								appName: appName || componentName,
 								collectScopes: options.collectScopes,
+								// `host`/`urlPath` on this entry route the component being loaded. For an
+								// application (no plugin module of its own) that entry is the only place an
+								// operator can say where the app is served — its own config.yaml declares the
+								// plugins, not the deployment. A nested component's own mount nests inside
+								// the parent's rather than replacing it, and the parent keeps hostname
+								// authority, so a child can't escape the host it is served on.
+								mount: nestScopeMount(mount, toScopeMount(componentConfig)),
 							});
 							componentFunctionality[componentName] = true;
 						}
@@ -554,7 +623,10 @@ export async function loadComponent(
 						// authoritative root-ness: only root-load scopes watch THE root config and
 						// get the runtime env-config overlay (#1618) — an app component that happens
 						// to ship a root-named config file does not
-						isRoot
+						isRoot,
+						// A root-declared plugin reads its own `host`/`urlPath` straight from this
+						// config, so only an inherited application mount applies here.
+						mount
 					);
 
 					if (options.collectScopes) {
@@ -597,6 +669,32 @@ export async function loadComponent(
 					);
 				}
 
+				// `start`/`startOnMainThread` hand the plugin the raw, unmounted `server` directly —
+				// unlike the new Plugin API's `handleApplication(scope)`, which receives the mount-aware
+				// scope — so routes registered there would silently escape a configured host/urlPath
+				// mount and stay reachable unconstrained (review finding). Same isolation gap
+				// fastifyRoutes.ts already closes for its own legacy fallback (host-only there, since
+				// urlPath composes into its route prefix; here neither composes, so both are rejected).
+				// Refuse rather than imply an isolation the hook can't honor; contained to this
+				// component by the loader's per-component try/catch.
+				if (
+					mount &&
+					(typeof extensionModule.start === 'function' || typeof extensionModule.startOnMainThread === 'function')
+				) {
+					const error = new Error(
+						`Component '${componentName}' is mounted (${[
+							mount.host && `host '${mount.host}'`,
+							mount.urlPath && `urlPath '${mount.urlPath}'`,
+						]
+							.filter(Boolean)
+							.join(
+								', '
+							)}), but its deprecated 'start'/'startOnMainThread' extension API receives the bare, unmounted server — routes registered there would stay reachable unconstrained. Upgrade to the new Plugin API (handleApplication(scope)) or drop the mount.`
+					);
+					componentLifecycle.failed(componentStatusName, error, `Component '${componentStatusName}' failed to load`);
+					throw error;
+				}
+
 				if (isMainThread) {
 					// `startOnMainThread` is one-time main-thread init: run it at most once per component
 					// for the life of the process (first load / first deploy). On a reload of an

package/components/mcp/toolRegistry.ts

@@ -362,6 +362,16 @@ export function isSuperUser(user: AuthedUser | undefined): boolean {
 	return user?.role?.permission?.super_user === true;
 }
 
+/**
+ * True if the request carries an authenticated principal. Anonymous MCP sessions are a supported
+ * deployment (the public-docs case, #1609) — the adapter hands them through as `{ username: '' }`
+ * rather than rejecting them — so a listing filter that means "any real user" has to test for this
+ * explicitly. `user?.role` is not a proxy: an authenticated user may legitimately carry no role.
+ */
+export function isAuthenticated(user: AuthedUser | undefined): boolean {
+	return typeof user?.username === 'string' && user.username.length > 0;
+}
+
 /**
  * Class-level verb introspection. Mirrors `resources/openApi.ts:149-153` so
  * a class is considered to "have" a verb only if its prototype overrides the

package/components/mcp/tools/application.ts

@@ -27,6 +27,7 @@ import harperLogger from '../../../utility/logging/harper_logger.ts';
 import {
 	addTool,
 	clearProfileTools,
+	isAuthenticated,
 	snapshotProfileTools,
 	type AuthedUser,
 	type ToolCallContext,
@@ -708,11 +709,17 @@ function makeVisibleTo(
 	return function visibleTo(user: AuthedUser): boolean {
 		// Super-user sees everything.
 		if (user?.role?.permission?.super_user === true) return true;
-		// Non-table Resources have no static permission gate — runtime allow*
-		// predicates enforce. Conservative default: don't list them for
-		// non-super users; they can still call via tools/call if they know
-		// the tool name (pass-through is documented behavior).
-		if (!databaseName || !tableName) return false;
+		// A Resource with no backing table has no static permission gate to consult, so listing is
+		// open to any authenticated caller and the Resource's own `allow*` predicates enforce at call
+		// time — hiding these while still accepting `tools/call` on them bought no security, only
+		// undiscoverable tools (#1940).
+		//
+		// Anonymous sessions stay excluded. They are a supported deployment (#1609) and reach here as
+		// `{ username: '' }`, so this must be tested explicitly. Custom `mcpTools` DO list to them, but
+		// that is an author opt-in — declaring `static mcpTools` is a deliberate act of publishing.
+		// Verb tools are generated for every exported Resource with no author action, so publishing an
+		// app's field names and docstrings to unauthenticated callers by default is not equivalent.
+		if (!databaseName || !tableName) return isAuthenticated(user);
 		const perm = getUserTablePermissions(user, databaseName, tableName);
 		if (!perm) return false;
 		if (mode === 'read') return perm.read === true || perm.describe === true;

package/components/mcp/tools/operations.ts

@@ -176,6 +176,9 @@ const DESTRUCTIVE_OPERATIONS: ReadonlySet<string> = new Set([
 	'restart_service',
 	'set_configuration',
 	'remove_node',
+	'restore_backup',
+	'delete_backup',
+	'purge_backups',
 	'delete_deployment_payload',
 ]);
 

package/components/mcp/tools/schemas/operationDescriptions.ts

@@ -60,6 +60,9 @@ export const OPERATION_DESCRIPTIONS: Record<string, string> = {
 	// list_deployments: components/deploymentOperations.ts:50 — Deployment history with filtering and pagination.
 	list_deployments:
 		'Lists deployments from system.hdb_deployment with optional filtering by project, status, and date range, plus pagination.',
+	// list_backups: dataLayer/rocksdbBackup.ts (listBackups) — Managed RocksDB backup metadata for a database.
+	list_backups:
+		'Lists the managed RocksDB directory backups for a database (id, timestamp, size, file count). Requires super_user; RocksDB databases only.',
 
 	// ─── DEFAULT_ALLOW: search_* ──────────────────────────────────────────
 	// search_by_conditions: dataLayer/search.ts:6 — Multi-condition search with comparators.

package/components/mcp/tools/schemas/operations.ts

@@ -101,6 +101,15 @@ export const OPERATION_INPUT_SCHEMAS: Record<string, object> = {
 		properties: {},
 		description: 'Lists deployed component versions in this Harper instance.',
 	},
+	list_backups: {
+		type: 'object',
+		properties: {
+			database: {
+				type: 'string',
+				description: 'Database name whose managed RocksDB backups to list. Defaults to `data`.',
+			},
+		},
+	},
 
 	// ─── search_* ─────────────────────────────────────────────────────────
 	search_by_hash: {

package/components/operations.js

@@ -410,6 +410,7 @@ async function deployComponent(req) {
 			};
 		}
 		if (req.urlPath !== undefined) applicationConfig.urlPath = req.urlPath;
+		if (req.host !== undefined) applicationConfig.host = req.host;
 		// Persist credential references (never tokens) so every cold install of this component —
 		// reboot, new peer, rollback — re-resolves the credential from the store.
 		if (credentialReferences.length) applicationConfig.credentials = credentialReferences;

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-root.schema.json

@@ -486,6 +486,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;
+}