@harperfast/harper 5.2.13 → 5.3.0-beta.1

package/dataLayer/blobBackup.ts

@@ -5,6 +5,12 @@ import { copyFile, link, mkdir, readdir, rename, rm, unlink, writeFile } from 'n
 import { dirname, join, relative } from 'node:path';
 import { ClientError } from '../utility/errors/hdbError.ts';
 import logger from '../utility/logging/harper_logger.ts';
+import {
+	type BlobCaptureDisposition,
+	classifyBlobFileForCapture,
+	createCaptureMarker,
+	isSystemicIoError,
+} from '../resources/blob.ts';
 
 /**
  * Managed-backup snapshotting of a database's file-backed blobs.
@@ -21,17 +27,17 @@ import logger from '../utility/logging/harper_logger.ts';
  * 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.
+ * Harper does not freeze blob writes for a backup, and a blob is written in place at its final path,
+ * so the walk can meet one that is still growing. Hard-linking that inode would put bytes in the
+ * snapshot that keep changing after it was taken. Every entry returned by the walk is therefore
+ * classified (`captureBlobFile`): a complete blob is linked, and one that becomes unavailable or is
+ * not yet complete is replaced by a marker rather than dropped. This closes the classify-to-capture
+ * race and keeps that file id reserved; a file reclaimed before its parent directory is read remains
+ * outside the snapshot.
  *
- * 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.
+ * Past that gate, hard-linking is safe against later mutation: each write takes a fresh monotonic
+ * file id, and an update, delete, or in-place repair replaces or unlinks the path rather than
+ * rewriting the inode.
  */
 
 /** Directory holding all blob snapshots for a backup repository. */
@@ -46,17 +52,17 @@ export function blobSnapshotDir(backupDir: string, backupId: number): string {
 
 /**
  * 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.
+ * the filesystem does not support additional hard links). Never creates a symlink. Returns false
+ * when the source vanishes so the caller can substitute a marker for it. `counts.copied` is what a
+ * caller on a latency budget needs: the fallback turns a constant-time clone into an O(bytes) one.
  */
-async function linkOrCopy(src: string, dest: string): Promise<void> {
+async function linkOrCopy(src: string, dest: string, counts?: { copied: number }): Promise<boolean> {
 	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;
+			if (!existsSync(src)) return false; // vanished since it was classified
 			throw error;
 		}
 		if (
@@ -66,24 +72,86 @@ async function linkOrCopy(src: string, dest: string): Promise<void> {
 			error.code === 'ENOTSUP' ||
 			error.code === 'EOPNOTSUPP'
 		) {
-			await copyFile(src, dest);
-			return;
+			try {
+				await copyFile(src, dest);
+			} catch (copyError: any) {
+				if (copyError.code === 'ENOENT') return false;
+				throw copyError;
+			}
+			if (counts) counts.copied++;
+			return true;
 		}
 		if (error.code === 'EEXIST') {
 			await unlink(dest);
-			await linkOrCopy(src, dest);
-			return;
+			return linkOrCopy(src, dest, counts);
 		}
 		throw error;
 	}
+	return true;
+}
+
+/** What a substituted marker says happened, so a branch clone doesn't report itself as a backup. */
+export interface CaptureMarkerReasons {
+	gone: string;
+	pending: string;
+}
+
+const BACKUP_MARKER_REASONS: CaptureMarkerReasons = {
+	gone: 'blob was deleted while this backup was being taken',
+	pending: 'blob was not yet complete when this backup was taken',
+};
+
+/** Put one blob file into the destination, returning how the entry was captured. */
+async function captureBlobFile(
+	srcPath: string,
+	destPath: string,
+	reasons: CaptureMarkerReasons = BACKUP_MARKER_REASONS,
+	counts?: { copied: number }
+): Promise<BlobCaptureDisposition> {
+	let disposition: BlobCaptureDisposition;
+	try {
+		disposition = await classifyBlobFileForCapture(srcPath);
+	} catch (error) {
+		// This rethrow is unverified: only the membership of SYSTEMIC_IO_ERRORS is tested, because
+		// reaching it needs a real host-level fault no test here can produce.
+		if (isSystemicIoError(error)) throw error;
+		// Fall back to what this walk did before it classified anything. `link()` needs no read permission
+		// on the source, so a blob this failed to *read* may still be perfectly capturable; substituting
+		// here would turn an unreadable-but-valid root into a backup of nothing but stubs.
+		logger.warn(`Could not verify blob ${srcPath} for snapshot; capturing it unverified`, error);
+		disposition = 'capture';
+	}
+	if (disposition === 'skip') return disposition;
+	if (disposition === 'capture') {
+		if (await linkOrCopy(srcPath, destPath, counts)) return disposition;
+		disposition = 'gone';
+	}
+	await mkdir(dirname(destPath), { recursive: true });
+	await writeFile(destPath, createCaptureMarker(disposition, disposition === 'gone' ? reasons.gone : reasons.pending));
+	return disposition;
 }
 
 /**
  * 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).
+ *
+ * `classify` substitutes a marker for a file that is mid-write or already gone, so the destination
+ * fails loudly on that blob rather than carrying a truncated one. It belongs to the capture direction
+ * only; restore must replace exactly what the snapshot holds.
+ *
+ * Also used by branch materialization (harper#644), which clones a base's blob roots into the
+ * branch's own so the OS inode refcount does the reference counting. Its walk runs inside a window
+ * other threads wait on, which is what `onProgress` is for.
  */
-async function copyTree(srcRoot: string, destRoot: string): Promise<void> {
-	if (!existsSync(srcRoot)) return;
+export async function copyTree(
+	srcRoot: string,
+	destRoot: string,
+	classify = false,
+	reasons?: CaptureMarkerReasons,
+	onProgress?: () => void
+): Promise<{ substituted: number; captured: number; copied: number }> {
+	const counts = { substituted: 0, captured: 0, copied: 0 };
+	if (!existsSync(srcRoot)) return counts;
 	const stack: string[] = [srcRoot];
 	while (stack.length > 0) {
 		const dir = stack.pop() as string;
@@ -99,63 +167,103 @@ async function copyTree(srcRoot: string, destRoot: string): Promise<void> {
 			if (entry.isDirectory()) {
 				stack.push(srcPath);
 			} else if (entry.isFile()) {
-				await linkOrCopy(srcPath, join(destRoot, relative(srcRoot, srcPath)));
+				const destPath = join(destRoot, relative(srcRoot, srcPath));
+				if (classify) {
+					const disposition = await captureBlobFile(srcPath, destPath, reasons, counts);
+					if (disposition === 'pending' || disposition === 'gone') counts.substituted++;
+					else if (disposition === 'capture') counts.captured++;
+				} else {
+					await linkOrCopy(srcPath, destPath, counts);
+				}
+				onProgress?.();
 			}
 			// symlinks/other node types in a blob root are not expected and are intentionally skipped
 		}
 	}
+	return counts;
 }
 
 /**
- * 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).
+ * Copy every blob root into `destDir` as `<rootIndex>/<relpath>`, hard-linking where possible.
+ * Writes to a temporary sibling and atomically renames into place so a run that fails mid-copy never
+ * leaves a partial directory a later restore would trust, and replaces any pre-existing `destDir`.
+ * Shared by managed-backup snapshots and `copy-db`'s standalone blob copy (harper#2048).
  */
-export async function snapshotBlobs(backupDir: string, backupId: number, blobRoots: string[]): Promise<void> {
-	const finalDir = blobSnapshotDir(backupDir, backupId);
-	const tempDir = join(blobsRootDir(backupDir), `.tmp-${backupId}`);
+export async function copyBlobRootsByIndex(destDir: string, blobRoots: string[]): Promise<void> {
+	const tempDir = destDir + '.tmp';
 	await rm(tempDir, { recursive: true, force: true });
 	await mkdir(tempDir, { recursive: true });
 	try {
+		let substituted = 0;
+		let captured = 0;
 		for (let index = 0; index < blobRoots.length; index++) {
-			await copyTree(blobRoots[index], join(tempDir, String(index)));
+			const counts = await copyTree(blobRoots[index], join(tempDir, String(index)), true);
+			substituted += counts.substituted;
+			captured += counts.captured;
 		}
-		await rm(finalDir, { recursive: true, force: true });
-		await rename(tempDir, finalDir);
+		if (substituted > 0) {
+			logger.warn(
+				`Blob copy into ${destDir} substituted ${substituted} of ${substituted + captured} blob ` +
+					`file(s) with PENDING or ERROR markers because they were not capturable whole.`
+			);
+		}
+		await rm(destDir, { recursive: true, force: true });
+		await rename(tempDir, destDir);
 	} catch (error) {
 		await rm(tempDir, { recursive: true, force: true }).catch(() => {});
 		throw error;
 	}
+}
+
+/**
+ * Snapshot a database's blob roots into a backup's blob directory. 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> {
+	await copyBlobRootsByIndex(blobSnapshotDir(backupDir, backupId), blobRoots);
 	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
+ * hand-recovering a backup can decode the numeric directories. Three 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.
+ * - `archive`: 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.
+ * - `copy`: the companion directory `copy-db` writes beside a database copy, restored by hand.
  */
-export function blobsReadmeContent(blobRoots: string[], { archive = false }: { archive?: boolean } = {}): string {
+export function blobsReadmeContent(
+	blobRoots: string[],
+	{ variant = 'managed' }: { variant?: 'managed' | 'archive' | 'copy' } = {}
+): 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.
+	const layout =
+		variant === 'managed'
+			? '<backupId>/<rootIndex>/<shard1>/<shard2>/<fileId>'
+			: '<rootIndex>/<shard1>/<shard2>/<fileId>';
+	const intro =
+		variant === 'copy'
+			? `This directory holds the file-backed blobs of a \`copy-db\` database copy; the database file itself
+is the sibling \`.mdb\` this directory is named after. Blobs are addressed by database NAME and the
+configured blob roots — never by the database file's path — so a copy is only restorable with these
+files: put each \`<rootIndex>/\` tree into the matching blob root of whatever database name you
+restore the copy as (mapping below).`
+			: variant === '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
+				: `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,
+	const backupIdBullet =
+		variant === 'managed'
+			? `- **<backupId>** matches the RocksDB backup id (\`harper list_backups\`). Each id is a full,
   independent snapshot (not incremental).
-`;
+`
+			: '';
 	return `# Harper blob snapshots
 
 ${intro}
@@ -166,7 +274,7 @@ ${intro}
 
 ${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:
+  (\`<rootPath>/blobs/<db>\`) at index 0. Current mapping:
 
 ${rootMapping}
 
@@ -175,8 +283,10 @@ ${rootMapping}
   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.
+Complete blobs are hard links to the live blobs when the destination is on the same filesystem, and
+copies otherwise. A blob that was not capturable whole is stored as a marker instead: header type
+\`0xfe\` is retryable (PENDING), while \`0xff\` is terminal (ERROR). The marker preserves the file id
+but does not contain the original blob bytes.
 `;
 }
 

package/dataLayer/delete.ts

@@ -110,7 +110,12 @@ export async function deleteAuditLogsBefore(deleteObj: any) {
 	harperLogger.info(`Finished deleting audit logs before ${deleteObj.timestamp}`);
 
 	// `deleteTransactionLogsBefore` returns `entries_deleted`; the legacy result exposes it as `transactions_deleted`.
-	return new DeleteAuditLogsBeforeResults(results.start_timestamp, results.end_timestamp, results.entries_deleted);
+	return new DeleteAuditLogsBeforeResults(
+		results.start_timestamp,
+		results.end_timestamp,
+		results.entries_deleted,
+		results.log_files_deleted
+	);
 }
 
 /**

package/dataLayer/harperBridge/ResourceBridge.ts

@@ -25,6 +25,7 @@ import type {
 import { collapseData } from '../../resources/tracked.ts';
 import { errorToString } from '../../utility/logging/harper_logger.ts';
 import { RocksDatabase } from '@harperfast/rocksdb-js';
+import { boundedAuditPruneEnd, raiseAuditFloor } from '../../resources/auditStore.ts';
 import { BridgeMethods } from './BridgeMethods.ts';
 import lmdbGetBackup from './lmdbBridge/lmdbMethods/lmdbGetBackup.js';
 import { createBackupStream, resolveSingleRootStore } from '../rocksdbBackup.ts';
@@ -199,10 +200,35 @@ export class ResourceBridge extends BridgeMethods {
 		return this.upsertRecords(updateObj);
 	}
 
-	async upsertRecords(upsertObj) {
+	/**
+	 * Create-or-replace: the stored record becomes exactly the submitted one, so an attribute the
+	 * request omits is REMOVED rather than kept. `update`/`upsert` merge (`Table.patch`), which is the
+	 * v4-compatible behaviour every existing client depends on and is why this is a separate operation
+	 * rather than a flag on those. Equivalent to REST `PUT /Table/id` — same `Table.put`, so the same
+	 * audit type, replication shape, and retained `__createdtime__`.
+	 */
+	async putRecords(putObj) {
+		return this.upsertRecords(putObj, true);
+	}
+
+	async upsertRecords(upsertObj, fullRecord = false) {
 		const { attributes } = insertUpdateValidate(upsertObj);
 
 		let new_attributes;
+		// `fullRecord` arrives as an ARGUMENT, never as a field on the request. Reading it off
+		// `upsertObj` would let a client send `full_record: true` with an `update` and get a replace —
+		// which makes the operation name stop describing the write, and bypasses the attribute-scoped
+		// `put` denial in `verifyPerms`, since that is keyed on the operation.
+		//
+		// Without it a write over an existing record merges (`Table.patch`), so an attribute the caller
+		// omitted keeps its stored value and `null` stores a null. That merge is the v4-compatible
+		// behaviour `update`/`upsert` must keep; HarperFast/studio#1643 is the removal case it cannot
+		// serve, and `put` is the operation that can.
+		//
+		// A put is also one operation where a client emulating removal needs two: the record is never
+		// absent between them, subscribers see a single write rather than a delete followed by an
+		// insert, and `__createdtime__` survives (`Table._writeUpdate` retains the stored created time
+		// on a full update and only stamps a new one for a new entry).
 		const Table = getDatabases()[upsertObj.schema][upsertObj.table];
 		const context: Context = {
 			user: upsertObj.hdb_user,
@@ -259,9 +285,14 @@ export class ResourceBridge extends BridgeMethods {
 						}
 					}
 				}
+				// Keyed on whether there IS a record to remove from, not on which operation asked. Guarding
+				// the insert flag alone left `upsert` with no primary key reaching the same silent partial
+				// write one branch over: `insertUpdateValidate` requires a hash attribute only for
+				// `update`, so such a record takes the `id == undefined → Table.create` path and stored an
+				// auto-keyed record with the named attributes stripped, returning 200.
 				await (id == undefined
 					? Table.create(record, context)
-					: existingRecord
+					: existingRecord && !fullRecord
 						? Table.patch(record, context)
 						: Table.put(record, context));
 				keys.push(record[Table.primaryKey]);
@@ -490,8 +521,26 @@ export class ResourceBridge extends BridgeMethods {
 			deleteObj.timestamp instanceof Date
 				? deleteObj.timestamp.getTime()
 				: typeof deleteObj.timestamp === 'string'
-					? Number.parseInt(deleteObj.timestamp)
+					? // Number, not Number.parseInt: parseInt takes a numeric PREFIX ('9999999999999oops' is a
+						// year-2286 bound to it, '1e3' is 1) where Number rejects both as NaN. Empty/whitespace is
+						// explicit because Number('') and Number('   ') are 0.
+						deleteObj.timestamp.trim() === ''
+						? Number.NaN
+						: Number(deleteObj.timestamp)
 					: deleteObj.timestamp;
+		// Audit keys are raw float64: NaN and negatives sort above every real timestamp (a range ending
+		// there spans the whole log), and Infinity records the unknown sentinel raiseAuditFloor never lifts.
+		// Reject anything but a finite non-negative number here, as the 400 it is rather than a server
+		// fault. `Number.isFinite` never coerces, so it is the type check too.
+		if (!Number.isFinite(before) || before < 0 || Object.is(before, -0))
+			throw handleHDBError(
+				new Error(),
+				`'timestamp' must be a non-negative epoch time or Date, received: ${String(deleteObj.timestamp)}`,
+				400,
+				undefined,
+				undefined,
+				true
+			);
 		const databaseName = deleteObj.database || deleteObj.schema || DEFAULT_DATABASE;
 		const table = getTable(deleteObj);
 		// A nonexistent table must not fall through to the no-table branch below — on RocksDB that
@@ -514,7 +563,14 @@ export class ResourceBridge extends BridgeMethods {
 			if (tables) {
 				for (const table of Object.values(tables)) {
 					if (table.primaryStore instanceof RocksDatabase) {
-						const deleted = table.primaryStore.purgeLogs({ before, includeEntryCounts: true });
+						// Clamp before recording: an operator-supplied bound has no ceiling of its own, and a
+						// floor above everything reachable never comes down (`raiseAuditFloor` only raises and
+						// `establishAuditFloor` skips a store that has a record), so a far-future bound would
+						// retire the floor for every table in this database. The purge takes the same clamped
+						// bound, so it cannot remove an entry the floor does not cover.
+						const pruneEnd = boundedAuditPruneEnd(table.auditStore, before);
+						raiseAuditFloor(table.auditStore, pruneEnd);
+						const deleted = table.primaryStore.purgeLogs({ before: pruneEnd, includeEntryCounts: true });
 						totalResults.log_files_deleted += deleted.length;
 						totalResults.entries_deleted += deleted.reduce((acc, file) => acc + file.entries, 0);
 						break;
@@ -546,11 +602,12 @@ export class ResourceBridge extends BridgeMethods {
 				// get the history of each record
 				for (const id of readAuditLogObj.search_values) {
 					histories[id] = (await table.getHistoryOfRecord(id)).map((auditRecord) => {
-						let operation = auditRecord.operation ?? auditRecord.type;
-						if (operation === 'put') operation = 'upsert';
+						let operation = normalizeHistoryOperation(auditRecord.operation, auditRecord.type);
 						return {
 							operation,
-							timestamp: auditRecord.version,
+							// the transaction's position in the log, which is what this field has always
+							// reported on RocksDB and what groups an atomic transaction (harper#2412)
+							timestamp: auditRecord.localTime,
 							user_name: auditRecord.user,
 							ids: [id],
 							records: [auditRecord.value],
@@ -745,9 +802,8 @@ async function* groupRecordsInHistory(table, start?, end?, limit?) {
 	let enqueued;
 	let count = 0;
 	for await (const entry of table.getHistory(start, end)) {
-		let operation = entry.operation ?? entry.type;
-		if (operation === 'put') operation = 'upsert';
-		const { id, version: timestamp, value } = entry;
+		let operation = normalizeHistoryOperation(entry.operation, entry.type);
+		const { id, localTime: timestamp, value } = entry;
 		if (enqueued?.timestamp === timestamp) {
 			enqueued.ids.push(id);
 			enqueued.records.push(value);
@@ -771,3 +827,17 @@ async function* groupRecordsInHistory(table, start?, end?, limit?) {
 	}
 	if (enqueued) yield enqueued;
 }
+
+/**
+ * Which operation a history entry should report: the originating operation when one was recorded,
+ * otherwise the physical write type.
+ *
+ * A recorded `put` is reported as `put`, so replication catch-up replays it as a replace. Only a
+ * LEGACY physical put — one with no originating operation, written before `put` existed — is still
+ * normalized to `upsert`, which is what produced a physical put back then. Normalizing both would
+ * make catch-up patch the replica and retain attributes the source removed.
+ */
+function normalizeHistoryOperation(originatingOperation, physicalType) {
+	if (originatingOperation !== undefined) return originatingOperation;
+	return physicalType === 'put' ? 'upsert' : physicalType;
+}

package/dataLayer/harperBridge/lmdbBridge/lmdbMethods/DeleteAuditLogsBeforeResults.js

@@ -8,11 +8,13 @@ class DeleteAuditLogsBeforeResults {
 	 * @param {number} startTimestamp
 	 * @param {number} endTimestamp
 	 * @param {number} transactionsDeleted
+	 * @param {number} logFilesDeleted
 	 */
-	constructor(startTimestamp = undefined, endTimestamp = undefined, transactionsDeleted = 0) {
+	constructor(startTimestamp = undefined, endTimestamp = undefined, transactionsDeleted = 0, logFilesDeleted = 0) {
 		this.start_timestamp = startTimestamp;
 		this.end_timestamp = endTimestamp;
 		this.transactions_deleted = transactionsDeleted;
+		this.log_files_deleted = logFilesDeleted;
 		this.deprecated = 'Please use delete_transaction_logs_before instead';
 	}
 }

package/dataLayer/hdbInfoController.ts

@@ -37,6 +37,37 @@ const DEFAULT_DATA_VERSION_NUM = '2.9.9';
 // This value should change as supported versions change.
 const MINIMUM_SUPPORTED_VERSION_NUM = '3.0.0';
 
+export class VersionStampNotRecordedError extends Error {
+	statusCode: number;
+	constructor(message: string) {
+		super(message);
+		this.name = 'VersionStampNotRecordedError';
+		this.statusCode = 500;
+	}
+}
+
+/**
+ * `insert.insert` reports a key that already exists as skipped, not as a failure, so a resolved
+ * insert is not evidence that the version was recorded. Ids compare as strings: the guard is
+ * against a write that did not happen, not against a hash returned in a different type.
+ */
+export function assertVersionRecorded(insertResult: any, expectedId: number, newVersionString: string) {
+	const insertedHashes = insertResult?.inserted_hashes;
+	if (
+		Array.isArray(insertedHashes) &&
+		insertedHashes.length === 1 &&
+		String(insertedHashes[0]) === String(expectedId)
+	) {
+		return;
+	}
+
+	throw new VersionStampNotRecordedError(
+		`Could not record data version ${newVersionString} in '${hdbTerms.SYSTEM_SCHEMA_NAME}.${hdbTerms.SYSTEM_TABLE_NAMES.INFO_TABLE_NAME}': ` +
+			`the insert of ${HDB_INFO_SEARCH_ATTRIBUTE} ${expectedId} reported inserted ${JSON.stringify(insertedHashes ?? null)} ` +
+			`and skipped ${JSON.stringify(insertResult?.skipped_hashes ?? null)}`
+	);
+}
+
 /**
  * * Insert a row into hdbInfo with the initial version data at install.
  *
@@ -91,7 +122,9 @@ export async function insertHdbUpgradeInfo(newVersionString: string) {
 	);
 
 	await pSetSchemaDataToGlobal();
-	return insert.insert(insertObject);
+	const insertResult = await insert.insert(insertObject);
+	assertVersionRecorded(insertResult, newId, newVersionString);
+	return insertResult;
 }
 
 /**

package/dataLayer/insert.ts

@@ -21,6 +21,7 @@ const pGlobalSchema = util.promisify(globalSchema.getTableSchema);
 const UPDATE_ACTION = 'updated';
 const INSERT_ACTION = 'inserted';
 const UPSERT_ACTION = 'upserted';
+const PUT_ACTION = 'put';
 
 //IMPORTANT - This validation function is the async version of the code in harperBridge/bridgeUtility/insertUpdateValidate.js
 // make sure any changes below are also made there. This is to resolve a circular dependency.
@@ -218,6 +219,42 @@ async function upsertData(upsertObject: any) {
 	);
 }
 
+/**
+ * Create-or-replace the records in the putObject parameter: the stored record becomes exactly the
+ * submitted one, so an attribute the request omits is removed. `update`/`upsert` merge instead, and
+ * must keep doing so for v4 compatibility — hence a distinct operation rather than a flag on those.
+ * Equivalent to REST `PUT /Table/id`.
+ * @param putObject - Represents the data that will be written
+ */
+async function putData(putObject: any) {
+	if (putObject.operation !== 'put') {
+		throw handleHDBError(new Error(), 'invalid operation, must be put', HTTP_STATUS_CODES.INTERNAL_SERVER_ERROR);
+	}
+
+	let validator = insertValidator(putObject);
+	if (validator) {
+		throw handleHDBError(new Error(), validator.message, HTTP_STATUS_CODES.BAD_REQUEST);
+	}
+
+	hdbUtils.transformReq(putObject);
+
+	let invalidSchemaTableMsg = hdbUtils.checkSchemaTableExist(putObject.schema, putObject.table);
+	if (invalidSchemaTableMsg) {
+		throw handleHDBError(new Error(), invalidSchemaTableMsg, HTTP_STATUS_CODES.BAD_REQUEST);
+	}
+
+	let bridgePutResult = await harperBridge.putRecords(putObject);
+
+	return returnObject(
+		PUT_ACTION,
+		bridgePutResult.written_hashes,
+		putObject,
+		[],
+		bridgePutResult.new_attributes,
+		bridgePutResult.txn_time
+	);
+}
+
 /**
  * Constructs return object for insert, update, and upsert.
  * @param action
@@ -254,6 +291,12 @@ function returnObject(
 		return return_object;
 	}
 
+	if (action === PUT_ACTION) {
+		// `put` never skips: every submitted record is written, created or replaced.
+		return_object.put_hashes = written_hashes;
+		return return_object;
+	}
+
 	return_object.update_hashes = written_hashes;
 	return_object.skipped_hashes = skipped;
 	return return_object;
@@ -263,4 +306,4 @@ export function flush(object: any) {
 	hdbUtils.transformReq(object);
 	return harperBridge.flush(object.schema, object.table);
 }
-export { insertData as insert, updateData as update, upsertData as upsert };
+export { insertData as insert, updateData as update, upsertData as upsert, putData as put };