@harperfast/harper 5.0.25 → 5.1.0-beta.1

package/resources/databases.ts

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'node:events';
-import { initSync, getHdbBasePath, get as envGet } from '../utility/environment/environmentManager.js';
-import { INTERNAL_DBIS_NAME } from '../utility/lmdb/terms.js';
+import { initSync, getHdbBasePath, get as envGet } from '../utility/environment/environmentManager.ts';
+import { INTERNAL_DBIS_NAME } from '../utility/lmdb/terms.ts';
 import { open, compareKeys, type Database, type RootDatabase } from 'lmdb';
 import { join, extname, basename } from 'path';
 import { existsSync, readdirSync, readFileSync, mkdirSync } from 'node:fs';
@@ -10,22 +10,22 @@ import {
 	getTransactionAuditStoreBasePath,
 } from '../dataLayer/harperBridge/lmdbBridge/lmdbUtility/initializePaths.js';
 import { makeTable } from './Table.ts';
-import OpenEnvironmentObject from '../utility/lmdb/OpenEnvironmentObject.js';
+import OpenEnvironmentObject from '../utility/lmdb/OpenEnvironmentObject.ts';
 import { CONFIG_PARAMS, LEGACY_DATABASES_DIR_NAME, DATABASES_DIR_NAME } from '../utility/hdbTerms.ts';
 import { getConfigPath } from '../config/configUtils.js';
 import { _assignPackageExport } from '../globals.js';
-import { getIndexedValues } from '../utility/lmdb/commonUtility.js';
-import * as signalling from '../utility/signalling.js';
+import { getIndexedValues } from '../utility/lmdb/commonUtility.ts';
+import * as signalling from '../utility/signalling.ts';
 import { SchemaEventMsg } from '../server/threads/itc.js';
 import { workerData } from 'worker_threads';
-import harperLogger from '../utility/logging/harper_logger.js';
+import harperLogger from '../utility/logging/harper_logger.ts';
 const { forComponent } = harperLogger;
 import * as manageThreads from '../server/threads/manageThreads.js';
 import { openAuditStore, readAuditEntry, createAuditEntry, type AuditRecord } from './auditStore.ts';
 import { handleLocalTimeForGets } from './RecordEncoder.ts';
 import { deleteRootBlobPathsForDB } from './blob.ts';
 import { CUSTOM_INDEXES } from './indexes/customIndexes.ts';
-import { OpenDBIObject } from '../utility/lmdb/OpenDBIObject.js';
+import { OpenDBIObject } from '../utility/lmdb/OpenDBIObject.ts';
 import { RocksDatabase, type RocksDatabaseOptions } from '@harperfast/rocksdb-js';
 import { replayLogs } from './replayLogs.ts';
 import { totalmem } from 'node:os';
@@ -33,6 +33,36 @@ import { RocksIndexStore } from './RocksIndexStore.ts';
 import { when } from '../utility/when.ts';
 import { isProcessRunning } from '../utility/processManagement/processManagement.js';
 
+/**
+ * Check if Harper is running in read-only mode.
+ * Read-only mode can be enabled via:
+ * - HARPER_READONLY environment variable (truthy value)
+ * - --readonly CLI flag
+ * - storage.readOnly config setting
+ */
+let _isReadOnlyMode: boolean | undefined;
+export function isReadOnlyMode(): boolean {
+	if (_isReadOnlyMode !== undefined) return _isReadOnlyMode;
+	// Check environment variable
+	const envReadOnly = process.env.HARPER_READONLY;
+	if (envReadOnly && envReadOnly !== '0' && envReadOnly !== 'false') {
+		_isReadOnlyMode = true;
+		return true;
+	}
+	// Check CLI flag (simple argv check)
+	if (process.argv.includes('--readonly') || process.argv.includes('--read-only')) {
+		_isReadOnlyMode = true;
+		return true;
+	}
+	// Check config setting
+	if (envGet(CONFIG_PARAMS.STORAGE_READONLY)) {
+		_isReadOnlyMode = true;
+		return true;
+	}
+	_isReadOnlyMode = false;
+	return false;
+}
+
 function createOpenDBIObject(dupSort = false, isPrimary = false) {
 	return new OpenDBIObject(dupSort, isPrimary);
 }
@@ -48,9 +78,11 @@ export const NON_REPLICATING_SYSTEM_TABLES = [
 	'hdb_temp',
 	'hdb_certificate',
 	'hdb_raw_analytics',
+	'hdb_model_calls',
 	'hdb_session_will',
 	'hdb_job',
 	'hdb_info',
+	'mcp_session',
 ];
 
 export type Table = ReturnType<typeof makeTable> & {
@@ -80,6 +112,10 @@ interface LMDBRootDatabase extends RootDatabase {
 	needsDeletion?: boolean;
 	path?: string;
 	status?: 'open' | 'closed';
+	store: any;
+	retryRisk?: number;
+	flushed: Promise<boolean>;
+	rootStore?: LMDBRootDatabase;
 }
 
 interface RocksDatabaseEx extends RocksDatabase {
@@ -95,6 +131,10 @@ interface RocksRootDatabase extends RocksDatabaseEx {
 	auditStore?: RocksDatabaseEx;
 	databaseName?: string;
 	dbisDb?: RocksDatabaseEx;
+	store: any;
+	retryRisk?: number;
+	flushed: Promise<boolean>;
+	rootStore?: RocksRootDatabase;
 }
 
 export type RootDatabaseKind = LMDBRootDatabase | RocksRootDatabase;
@@ -110,31 +150,62 @@ export const databaseEventsEmitter = new EventEmitter<DatabaseWatcherEventMap>()
 export const tables: Tables = Object.create(null);
 export const databases: Databases = Object.create(null);
 
-const MEMORY_FOR_ROCKS_DB = Math.min(process.constrainedMemory?.() ?? Infinity, totalmem()) * 0.25; // 25% of available memory
-
 function openRocksDatabase(path: string, options: RocksDatabaseOptions & { dupSort?: boolean }) {
 	options.disableWAL ??= true;
-	RocksDatabase.config({ blockCacheSize: MEMORY_FOR_ROCKS_DB });
+	// Apply read-only mode if enabled
+	if (isReadOnlyMode()) {
+		options.readOnly = true;
+	}
+	// Read RocksDB memory config lazily so env/CLI overrides applied after module load are
+	// respected. The block cache falls back to 25% of constrained (cgroup) memory when not
+	// configured; the WriteBufferManager is opt-in (0 disables).
+	//
+	// We enforce types rather than coerce — values from YAML config and env vars flow
+	// through configUtils.castConfigValue which produces proper numbers/booleans/null,
+	// so anything else is misconfiguration and should fall through to the default.
+	//
+	// Note: writeBufferManagerCostToCache and writeBufferManagerAllowStall are fixed at WBM
+	// creation time inside rocksdb-js (the underlying RocksDB API doesn't support changing
+	// costToCache on a live manager, and allowStall is only re-applied when explicitly changed).
+	// In practice that's fine — these come from process-level config that doesn't change.
+	const configuredBlockCacheSize = envGet(CONFIG_PARAMS.STORAGE_ROCKS_BLOCKCACHESIZE);
+	const blockCacheSize =
+		typeof configuredBlockCacheSize === 'number' && configuredBlockCacheSize > 0
+			? configuredBlockCacheSize
+			: Math.min(process.constrainedMemory?.() ?? Infinity, totalmem()) * 0.25;
+	const writeBufferManagerSize = envGet(CONFIG_PARAMS.STORAGE_ROCKS_WRITEBUFFERMANAGERSIZE);
+	const writeBufferManagerCostToCache = envGet(CONFIG_PARAMS.STORAGE_ROCKS_WRITEBUFFERMANAGERCOSTTOCACHE);
+	const writeBufferManagerAllowStall = envGet(CONFIG_PARAMS.STORAGE_ROCKS_WRITEBUFFERMANAGERALLOWSTALL);
+	RocksDatabase.config({
+		blockCacheSize,
+		...(typeof writeBufferManagerSize === 'number' && writeBufferManagerSize > 0 ? { writeBufferManagerSize } : {}),
+		...(typeof writeBufferManagerCostToCache === 'boolean' ? { writeBufferManagerCostToCache } : {}),
+		...(typeof writeBufferManagerAllowStall === 'boolean' ? { writeBufferManagerAllowStall } : {}),
+	});
 	if (!existsSync(path)) {
+		// Don't create directories in read-only mode
+		if (isReadOnlyMode()) {
+			throw new Error(`Database cannot be created in read-only mode: ${path}`);
+		}
 		mkdirSync(path, { recursive: true });
 	}
 	let db: RocksRootDatabase;
 	if (options.dupSort) {
-		db = new RocksIndexStore(path, options).open() as RocksDatabaseEx;
+		db = new RocksIndexStore(path, options).open() as any;
 	} else {
-		db = RocksDatabase.open(path, options) as RocksDatabaseEx;
+		db = RocksDatabase.open(path, options) as any;
 		// the RocksDB put and remove return promises, which masks thrown errors in non-awaiting calls to put/remove,
 		// making them unsafe to replace LMDB methods, which will synchronously throw errors if there is a problem
-		db.put = db.putSync;
-		db.remove = db.removeSync;
-		db.encoder.name = options.name;
+		db.put = db.putSync as any;
+		db.remove = db.removeSync as any;
+		(db.encoder as any).name = options.name;
 	}
 	db.env = {};
 	return db;
 }
 
 const lmdbDatabaseEnvs = new Map<string, LMDBRootDatabase>();
-const rocksdbDatabaseEnvs = new Map<string, RocksDatabaseEx>();
+const rocksdbDatabaseEnvs = new Map<string, RocksRootDatabase>();
 
 // set the following in both global and exports
 _assignPackageExport('databases', databases);
@@ -183,9 +254,7 @@ export function getDatabases(): Databases {
 		process.env.STORAGE_PATH ||
 		getConfigPath(CONFIG_PARAMS.STORAGE_PATH) ||
 		(databasePath && (existsSync(databasePath) ? databasePath : join(getHdbBasePath(), LEGACY_DATABASES_DIR_NAME)));
-	if (!databasePath) return;
-
-	if (existsSync(databasePath)) {
+	if (databasePath && existsSync(databasePath)) {
 		// First load all the databases from our main database folder
 		// TODO: Load any databases defined with explicit storage paths from the config
 		for (const databaseEntry of readdirSync(databasePath, { withFileTypes: true })) {
@@ -336,13 +405,13 @@ export function readMetaDb(
 	auditPath?: string,
 	isLegacy?: boolean
 ) {
-	const envInit = new OpenEnvironmentObject(path, false);
+	const envInit = new OpenEnvironmentObject(path, isReadOnlyMode());
 	try {
 		let rootStore = lmdbDatabaseEnvs.get(path);
 		if (rootStore) {
 			rootStore.needsDeletion = false;
 		} else {
-			rootStore = open(envInit);
+			rootStore = open(envInit) as any;
 			lmdbDatabaseEnvs.set(path, rootStore);
 		}
 
@@ -364,14 +433,17 @@ function readRocksMetaDb(path: string, defaultTable?: string, databaseName: stri
 			}
 		}
 
-		let rootStore: RocksDatabaseEx | undefined = rocksdbDatabaseEnvs.get(path);
+		let rootStore: RocksRootDatabase | undefined = rocksdbDatabaseEnvs.get(path);
 		if (rootStore) {
 			initStores(path, rootStore, databaseName, defaultTable);
 		} else {
-			rootStore = openRocksDatabase(path, { disableWAL: false, enableStats: true }) as RocksDatabaseEx;
+			rootStore = openRocksDatabase(path, { disableWAL: false, enableStats: true }) as any;
 			rocksdbDatabaseEnvs.set(path, rootStore);
 			initStores(path, rootStore, databaseName, defaultTable);
-			replayLogs(rootStore, databases[databaseName]);
+			// Skip transaction log replay in read-only mode
+			if (!isReadOnlyMode()) {
+				replayLogs(rootStore, databases[databaseName]);
+			}
 		}
 		return rootStore;
 	} catch (error) {
@@ -388,7 +460,7 @@ function initStores(
 	auditPath?: string,
 	isLegacy?: boolean
 ) {
-	const envInit = new OpenEnvironmentObject(path, false);
+	const envInit = new OpenEnvironmentObject(path, isReadOnlyMode());
 	const internalDbiInit = createOpenDBIObject(false);
 	let attributesDbi = rootStore.dbisDb;
 	if (!attributesDbi) {
@@ -397,9 +469,9 @@ function initStores(
 				...internalDbiInit,
 				disableWAL: false,
 				name: INTERNAL_DBIS_NAME,
-			}) as RocksDatabaseEx;
+			} as any) as RocksDatabaseEx;
 		} else {
-			attributesDbi = rootStore.openDB(INTERNAL_DBIS_NAME, internalDbiInit);
+			attributesDbi = rootStore.openDB(INTERNAL_DBIS_NAME, internalDbiInit as any);
 		}
 		rootStore.dbisDb = attributesDbi;
 	}
@@ -418,7 +490,7 @@ function initStores(
 							encode: (auditRecord: AuditRecord) => createAuditEntry(auditRecord),
 							decode: (encoding: Buffer) => readAuditEntry(encoding),
 						},
-					});
+					}) as any;
 				}
 				auditStore.isLegacy = true;
 			}
@@ -429,7 +501,7 @@ function initStores(
 
 	const tables = ensureDB(databaseName);
 	const definedTables = tables[DEFINED_TABLES];
-	definedTables.rootStore = rootStore;
+	(definedTables as any).rootStore = rootStore;
 	const tablesToLoad = new Map<string, any>();
 
 	for (const result of attributesDbi.getRange({ start: false })) {
@@ -496,16 +568,16 @@ function initStores(
 		} else {
 			tableId = primaryAttribute.tableId;
 			if (tableId) {
-				if (tableId >= (attributesDbi.getSync(NEXT_TABLE_ID) || 0)) {
-					attributesDbi.putSync(NEXT_TABLE_ID, tableId + 1);
+				if (tableId >= ((attributesDbi as any).getSync(NEXT_TABLE_ID) || 0)) {
+					(attributesDbi as any).putSync(NEXT_TABLE_ID, tableId + 1);
 					logger.info(`Updating next table id (it was out of sync) to ${tableId + 1} for ${tableName}`);
 				}
 			} else {
-				primaryAttribute.tableId = tableId = attributesDbi.getSync(NEXT_TABLE_ID);
+				primaryAttribute.tableId = tableId = (attributesDbi as any).getSync(NEXT_TABLE_ID);
 				if (!tableId) tableId = 1;
 				logger.debug(`Table {tableName} missing an id, assigning {tableId}`);
-				attributesDbi.putSync(NEXT_TABLE_ID, tableId + 1);
-				attributesDbi.putSync(primaryAttribute.key, primaryAttribute);
+				(attributesDbi as any).putSync(NEXT_TABLE_ID, tableId + 1);
+				(attributesDbi as any).putSync(primaryAttribute.key, primaryAttribute);
 			}
 			const dbiInit = createOpenDBIObject(!primaryAttribute.isPrimaryKey, primaryAttribute.isPrimaryKey);
 			dbiInit.compression = primaryAttribute.compression;
@@ -516,11 +588,14 @@ function initStores(
 			}
 			if (rootStore instanceof RocksDatabase) {
 				primaryStore = handleLocalTimeForGets(
-					openRocksDatabase(rootStore.path, { ...dbiInit, name: primaryAttribute.key }),
+					openRocksDatabase(rootStore.path, { ...dbiInit, name: primaryAttribute.key } as any),
 					rootStore
 				);
 			} else {
-				primaryStore = handleLocalTimeForGets(rootStore.openDB(primaryAttribute.key, dbiInit), rootStore);
+				primaryStore = handleLocalTimeForGets(
+					(rootStore as any).openDB(primaryAttribute.key, dbiInit as any),
+					rootStore
+				);
 			}
 			rootStore.databaseName = databaseName;
 			primaryStore.tableId = tableId;
@@ -689,8 +764,8 @@ export function database({ database: databaseName, table: tableName }) {
 	getDatabases();
 	ensureDB(databaseName);
 	const definedDatabase = definedDatabases.get(databaseName);
-	if (definedDatabase?.rootStore) {
-		return definedDatabase.rootStore;
+	if ((definedDatabase as any)?.rootStore) {
+		return (definedDatabase as any).rootStore;
 	}
 	const databaseConfig = envGet(CONFIG_PARAMS.DATABASES) || {};
 	if (process.env.SCHEMAS_DATA_PATH) {
@@ -705,9 +780,17 @@ export function database({ database: databaseName, table: tableName }) {
 		databaseConfig[databaseName]?.path ||
 		process.env.STORAGE_PATH ||
 		getConfigPath(CONFIG_PARAMS.STORAGE_PATH) ||
-		(existsSync(join(hdbBasePath, DATABASES_DIR_NAME))
+		(hdbBasePath && existsSync(join(hdbBasePath, DATABASES_DIR_NAME))
 			? join(hdbBasePath, DATABASES_DIR_NAME)
-			: join(hdbBasePath, LEGACY_DATABASES_DIR_NAME));
+			: hdbBasePath
+				? join(hdbBasePath, LEGACY_DATABASES_DIR_NAME)
+				: undefined);
+
+	if (!databasePath) {
+		throw new Error(
+			`Unable to determine database storage path. Ensure STORAGE_PATH, HDB_ROOT, or a valid config path is set.`
+		);
+	}
 
 	let rootStore: RootDatabaseKind;
 	const useRocksdb = (process.env.HARPER_STORAGE_ENGINE || envGet(CONFIG_PARAMS.STORAGE_ENGINE)) !== 'lmdb';
@@ -718,23 +801,23 @@ export function database({ database: databaseName, table: tableName }) {
 			rootStore = openRocksDatabase(path, {
 				disableWAL: false,
 				enableStats: true,
-			});
-			rocksdbDatabaseEnvs.set(path, rootStore);
+			}) as any;
+			rocksdbDatabaseEnvs.set(path, rootStore as any);
 		}
 	} else {
 		const path = join(databasePath, `${tablePath ? tableName : databaseName}.mdb`);
 		rootStore = lmdbDatabaseEnvs.get(path);
 		if (!rootStore || rootStore.status === 'closed') {
 			// TODO: validate database name
-			const envInit = new OpenEnvironmentObject(path, false);
-			rootStore = open(envInit);
-			lmdbDatabaseEnvs.set(path, rootStore);
+			const envInit = new OpenEnvironmentObject(path, isReadOnlyMode());
+			rootStore = open(envInit) as any;
+			lmdbDatabaseEnvs.set(path, rootStore as any);
 		}
 	}
 	if (!rootStore.auditStore) {
-		rootStore.auditStore = openAuditStore(rootStore);
+		rootStore.auditStore = openAuditStore(rootStore as any);
 	}
-	if (definedDatabase) definedDatabase.rootStore = rootStore;
+	if (definedDatabase) (definedDatabase as any).rootStore = rootStore;
 	return rootStore;
 }
 /**
@@ -804,10 +887,10 @@ function openIndex(dbiKey: string, rootStore: RootDatabaseKind, attribute: any)
 				rootStore?: RocksRootDatabase;
 		  });
 	if (rootStore instanceof RocksDatabase) {
-		dbi = openRocksDatabase(rootStore.path, { ...dbiInit, name: dbiKey });
-		dbi.rootStore = rootStore;
+		dbi = openRocksDatabase(rootStore.path, { ...dbiInit, name: dbiKey } as any) as any;
+		(dbi as any).rootStore = rootStore;
 	} else {
-		dbi = rootStore.openDB(dbiKey, dbiInit);
+		dbi = (rootStore as any).openDB(dbiKey, dbiInit as any);
 	}
 	if (attribute.indexed.type) {
 		const CustomIndex = CUSTOM_INDEXES[attribute.indexed.type];
@@ -908,17 +991,17 @@ export function table<TableResourceType>(tableDefinition: TableDefinition): Tabl
 		const dbiName = tableName + '/';
 
 		if (rootStore instanceof RocksDatabase) {
-			attributesDbi = rootStore.dbisDb = openRocksDatabase(rootStore.path, {
+			attributesDbi = (rootStore as any).dbisDb = openRocksDatabase(rootStore.path, {
 				...internalDbiInit,
 				disableWAL: false,
 				name: INTERNAL_DBIS_NAME,
-			});
+			} as any);
 		} else {
-			attributesDbi = rootStore.dbisDb = rootStore.openDB(INTERNAL_DBIS_NAME, internalDbiInit);
+			attributesDbi = (rootStore as any).dbisDb = (rootStore as any).openDB(INTERNAL_DBIS_NAME, internalDbiInit as any);
 		}
 
 		exclusiveLock(); // get an exclusive lock on the database so we can verify that we are the only thread creating the table (and assigning the table id)
-		if (attributesDbi.getSync(dbiName)) {
+		if ((attributesDbi as any).getSync(dbiName)) {
 			// table was created while we were setting up
 			if (releaseExclusiveLock) releaseExclusiveLock();
 			resetDatabases();
@@ -927,9 +1010,9 @@ export function table<TableResourceType>(tableDefinition: TableDefinition): Tabl
 
 		let primaryStore;
 		if (rootStore instanceof RocksDatabase) {
-			primaryStore = openRocksDatabase(rootStore.path, { ...dbiInit, name: dbiName });
+			primaryStore = openRocksDatabase(rootStore.path, { ...dbiInit, name: dbiName } as any);
 		} else {
-			primaryStore = rootStore.openDB(dbiName, dbiInit);
+			primaryStore = (rootStore as any).openDB(dbiName, dbiInit as any);
 		}
 		primaryStore = handleLocalTimeForGets(primaryStore, rootStore);
 		rootStore.databaseName = databaseName;
@@ -971,15 +1054,15 @@ export function table<TableResourceType>(tableDefinition: TableDefinition): Tabl
 	const indices = Table.indices;
 	if (!attributesDbi) {
 		if (rootStore instanceof RocksDatabase) {
-			rootStore.dbisDb = openRocksDatabase(rootStore.path, {
+			(rootStore as any).dbisDb = openRocksDatabase(rootStore.path, {
 				...internalDbiInit,
 				disableWAL: false,
 				name: INTERNAL_DBIS_NAME,
-			});
+			} as any);
 		} else {
-			rootStore.dbisDb = rootStore.openDB(INTERNAL_DBIS_NAME, internalDbiInit);
+			(rootStore as any).dbisDb = (rootStore as any).openDB(INTERNAL_DBIS_NAME, internalDbiInit as any);
 		}
-		attributesDbi = rootStore.dbisDb;
+		attributesDbi = (rootStore as any).dbisDb;
 	}
 	Table.dbisDB = attributesDbi;
 	const indicesToRemove = [];
@@ -1029,7 +1112,7 @@ export function table<TableResourceType>(tableDefinition: TableDefinition): Tabl
 				) {
 					const updatedPrimaryAttribute = { ...attributeDescriptor };
 					if (typeof audit === 'boolean') {
-						if (audit) Table.enableAuditing(audit);
+						if (audit) Table.enableAuditing();
 						updatedPrimaryAttribute.audit = audit;
 					}
 					if (expiration) updatedPrimaryAttribute.expiration = +expiration;
@@ -1047,31 +1130,51 @@ export function table<TableResourceType>(tableDefinition: TableDefinition): Tabl
 
 			// note that non-indexed attributes do not need a dbi
 			if (attributeDescriptor?.attribute && !attributeDescriptor.name) attributeDescriptor.indexed = true; // legacy descriptor
-			const changed =
+			// Some index options affect only search, not the stored structure (e.g. HNSW's
+			// efConstructionSearch). Changing those should persist the new metadata but NOT trigger a
+			// reindex. A custom index declares such keys via a static `searchOnlyOptions`.
+			const indexType = attribute.indexed && typeof attribute.indexed === 'object' ? attribute.indexed.type : undefined;
+			const searchOnlyOptions: string[] = (indexType && CUSTOM_INDEXES[indexType]?.searchOnlyOptions) || [];
+			const stripSearchOnly = (indexed: any): any => {
+				if (!indexed || typeof indexed !== 'object' || searchOnlyOptions.length === 0) return indexed;
+				const copy = { ...indexed };
+				for (const key of searchOnlyOptions) delete copy[key];
+				return copy;
+			};
+			const commonChanged =
 				!attributeDescriptor ||
 				attributeDescriptor.type !== attribute.type ||
-				JSON.stringify(attributeDescriptor.indexed) !== JSON.stringify(attribute.indexed) ||
 				attributeDescriptor.nullable !== attribute.nullable ||
 				attributeDescriptor.version !== attribute.version ||
 				attributeDescriptor.enumerable !== attribute.enumerable ||
 				JSON.stringify(attributeDescriptor.properties) !== JSON.stringify(attribute.properties) ||
-				JSON.stringify(attributeDescriptor.elements) !== JSON.stringify(attribute.elements);
+				JSON.stringify(attributeDescriptor.elements) !== JSON.stringify(attribute.elements) ||
+				// Include `embed` so a source/model change refreshes the embed registry.
+				JSON.stringify(attributeDescriptor.embed) !== JSON.stringify(attribute.embed);
+			// any metadata difference (drives persistence)
+			const changed =
+				commonChanged || JSON.stringify(attributeDescriptor?.indexed) !== JSON.stringify(attribute.indexed);
+			// structure-affecting difference (drives reindex) — ignores search-only option changes
+			const structurallyChanged =
+				commonChanged ||
+				JSON.stringify(stripSearchOnly(attributeDescriptor?.indexed)) !==
+					JSON.stringify(stripSearchOnly(attribute.indexed));
 			if (attribute.indexed) {
 				const dbi = openIndex(dbiKey, rootStore, attribute);
 				if (
 					changed ||
-					attributeDescriptor.indexingFailed ||
-					(attributeDescriptor.indexingPID && attributeDescriptor.indexingPID !== process.pid) ||
-					attributeDescriptor.restartNumber < workerData?.restartNumber
+					attributeDescriptor?.indexingFailed ||
+					(attributeDescriptor?.indexingPID && attributeDescriptor?.indexingPID !== process.pid) ||
+					attributeDescriptor?.restartNumber < workerData?.restartNumber
 				) {
 					hasChanges = true;
 					exclusiveLock();
 					attributeDescriptor = attributesDbi.getSync(dbiKey);
 					if (
-						changed ||
-						attributeDescriptor.indexingFailed ||
-						(attributeDescriptor.indexingPID && attributeDescriptor.indexingPID !== process.pid) ||
-						attributeDescriptor.restartNumber < workerData?.restartNumber
+						structurallyChanged ||
+						attributeDescriptor?.indexingFailed ||
+						(attributeDescriptor?.indexingPID && attributeDescriptor?.indexingPID !== process.pid) ||
+						attributeDescriptor?.restartNumber < workerData?.restartNumber
 					) {
 						hasChanges = true;
 						if (attribute.indexNulls === undefined) attribute.indexNulls = true;
@@ -1089,6 +1192,14 @@ export function table<TableResourceType>(tableDefinition: TableDefinition): Tabl
 							// we only set indexing nulls to true if new or reindexing, we can't have partial indexing of null
 							attributesToIndex.push(attribute);
 						}
+					} else if (attributeDescriptor.indexingPID) {
+						// Metadata-only change (e.g. a search-only option like efConstructionSearch) while a
+						// backfill is in progress: we did NOT re-trigger indexing, so carry over the in-progress
+						// indexing state instead of persisting a descriptor that looks complete — otherwise other
+						// workers / a reload would treat the still-partial index as ready and return incomplete results.
+						attribute.indexingPID = attributeDescriptor.indexingPID;
+						attribute.lastIndexedKey = attributeDescriptor.lastIndexedKey;
+						if (attributeDescriptor.indexingFailed) attribute.indexingFailed = attributeDescriptor.indexingFailed;
 					}
 					attributesDbi.put(dbiKey, attribute);
 				}
@@ -1385,3 +1496,11 @@ export function getDefaultCompression() {
 	if (STORAGE_COMPRESSION_THRESHOLD) LMDB_COMPRESSION_OPTS['threshold'] = STORAGE_COMPRESSION_THRESHOLD;
 	return LMDB_COMPRESSION && LMDB_COMPRESSION_OPTS;
 }
+
+/**
+ * Force all RocksDB databases to flush to disk.
+ */
+export async function flushDatabases() {
+	// flush all RocksDB databases
+	return Promise.all(Array.from(rocksdbDatabaseEnvs.values()).map((db) => db.flush()));
+}