@harperfast/harper 5.3.0-beta.4 → 5.3.0

package/resources/analytics/write.ts

@@ -355,7 +355,7 @@ function storeTableSizeMetrics(analyticsTable: Table, dbName: string, tables: Ta
 	return dbUsedSize;
 }
 
-function storeDBSizeMetrics(analyticsTable: Table, databases: Databases) {
+export function storeDBSizeMetrics(analyticsTable: Table, databases: Databases) {
 	for (const [db, tables] of Object.entries(databases)) {
 		try {
 			const [firstTable] = Object.values(tables);
@@ -400,7 +400,7 @@ function storeDBSizeMetrics(analyticsTable: Table, databases: Databases) {
 	}
 }
 
-async function storeVolumeMetrics(analyticsTable: Table, databases: Databases) {
+export async function storeVolumeMetrics(analyticsTable: Table, databases: Databases) {
 	await Promise.all(
 		Object.entries(databases).map(async ([db, tables]) => {
 			try {
@@ -669,7 +669,7 @@ export function buildRocksDBTxnLogMetric(
  * @param now - The current time.
  * @param period - The period to store the metrics for.
  */
-function storeRocksDBStatsMetrics(
+export function storeRocksDBStatsMetrics(
 	analyticsTable: Table,
 	databases: Databases,
 	now: number,

package/resources/blob.ts

@@ -1578,6 +1578,8 @@ function runReclamation(): void {
 	let earliest = Infinity;
 	for (const [filePath, pending] of pendingReclamation) {
 		if (pending.unlinking) continue;
+		// Unlinking during a restore would delete bytes it just wrote at this path.
+		if (isBlobRestoreFenced(pending.fileInfo?.store)) continue;
 		if (pending.deadline > now) {
 			earliest = pending.deadline;
 			break; // insertion order is deadline order; nothing behind this entry is due
@@ -1648,7 +1650,9 @@ function runReclamation(): void {
 			const instanceStorageInfo = storageInfoForBlob.get(blob);
 			if (instanceStorageInfo) discardStorage(instanceStorageInfo);
 		}
+		const unlinkDone = beginBlobUnlink(blobSaveDatabaseName(storageInfo?.store));
 		unlink(filePath, (error) => {
+			unlinkDone();
 			pendingReclamation.delete(filePath);
 			if (pendingReclamation.size === 0) queueTailDeadline = 0;
 			// Hand the slot back: it is shared by hash, so leaving it claimed would make every later
@@ -1808,6 +1812,150 @@ export function createBlobFromStoredBody(
 // can be committed referencing fileIds whose blob files were never durably written.
 let pendingMigrationBlobSaves: Promise<void>[] | undefined;
 
+// Database -> the token of the restore that currently owns its fence. Restores of one database can
+// overlap, because a restore releases its lock before awaiting its `reload` broadcast. Ownership, so
+// that a superseded restore's late reload cannot unfence a database another restore is still working
+// on, and a restore that dies without reloading leaves nothing behind that a rerun cannot take over.
+const blobRestoreFences = new Map<string, string>();
+// Bumped every time a restore takes a database's fence. A check for "is it fenced right now" is not
+// enough for work that spans the whole restore: an orphan sweep can read the fence as clear, have an
+// entire restore happen while it awaits an unlink, and then keep deleting on a verdict reached
+// against the generation that restore replaced. Long-running work captures this instead.
+const blobRestoreEpochs = new Map<string, number>();
+const inFlightBlobSaves = new Map<string, Set<Promise<void>>>();
+// Count of blob-root unlinks dispatched per database, with the waiters a fence parks on until that
+// count reaches zero. A counter rather than a set of promises: this sits on the deletion path for
+// every blob, and the overwhelmingly common case has no restore running and nothing to await.
+const inFlightBlobUnlinks = new Map<string, { count: number; waiters: Array<() => void> }>();
+
+function blobSaveDatabaseName(store: any): string | undefined {
+	return typeof store?.databaseName === 'string' ? store.databaseName : undefined;
+}
+
+function assertBlobSaveAllowed(store: any): void {
+	const databaseName = blobSaveDatabaseName(store);
+	if (databaseName && blobRestoreFences.has(databaseName)) {
+		// 503, not a bare Error: the block is lifted by the restore's `reload` phase, so this is a
+		// retry-after condition rather than a fault in the request.
+		throw new BlobReadError(
+			`Cannot save a blob for database '${databaseName}' while it is being restored`,
+			BLOB_UNAVAILABLE_STATUS
+		);
+	}
+}
+
+function trackBlobSave(store: any, saving?: Promise<void>): void {
+	const databaseName = blobSaveDatabaseName(store);
+	if (!databaseName || !saving) return;
+	let saves = inFlightBlobSaves.get(databaseName);
+	if (!saves) inFlightBlobSaves.set(databaseName, (saves = new Set()));
+	saves.add(saving);
+	const remove = () => {
+		saves.delete(saving);
+		if (saves.size === 0) inFlightBlobSaves.delete(databaseName);
+	};
+	saving.then(remove, remove);
+}
+
+/**
+ * Fence blob saves, deferred reclamation and orphan cleanup for a database, and wait out the work
+ * already dispatched, so a restore can purge and rewrite its roots safely.
+ *
+ * Closing the database does not do this: a save is an asynchronous file pipeline that outlives the
+ * handle it started from, a reclamation is a timer that never consults the database, and an orphan
+ * sweep is dispatched fire-and-forget.
+ */
+export async function blockBlobSavesForRestore(databaseName: string, restoreToken: string): Promise<void> {
+	// Takes ownership whether or not another restore held it: the database never unfences in between.
+	blobRestoreFences.set(databaseName, restoreToken);
+	blobRestoreEpochs.set(databaseName, (blobRestoreEpochs.get(databaseName) ?? 0) + 1);
+	const saves = inFlightBlobSaves.get(databaseName);
+	if (saves) await Promise.allSettled([...saves]);
+	await drainBlobUnlinks(databaseName);
+}
+
+/**
+ * Release one restore's fence. Only the current owner's token lifts it, so an earlier restore's late
+ * `reload` cannot unfence a database another restore has since taken over.
+ */
+export function resumeBlobSavesAfterRestore(
+	databaseName: string,
+	restoreToken: string,
+	generationReplaced = true
+): void {
+	// Only the owner may lift the fence; a superseded restore's reload arriving late does nothing.
+	if (blobRestoreFences.get(databaseName) !== restoreToken) return;
+	blobRestoreFences.delete(databaseName);
+	// A drain that ran while the fence was up skipped these entries without recording a next deadline,
+	// so nothing is scheduled to come back for them. Whatever survives below needs a wakeup.
+	if (pendingReclamation.size > 0) scheduleReclamation(Date.now());
+	// A restore that aborted before it destroyed anything leaves the generation intact, so its queued
+	// reclamations still condemn the files they were queued against. Discarding those would strand
+	// every superseded blob the database had pending at the moment an admission check happened to fail.
+	if (!generationReplaced) return;
+	// Every queued reclamation for this database belongs to the generation the restore just replaced:
+	// its file paths were condemned against records that no longer exist. Draining them now would
+	// unlink restored bytes at the same paths, so they are dropped rather than resumed.
+	discardReclamationForDatabase(databaseName);
+}
+
+function isBlobRestoreFenced(store: any): boolean {
+	const databaseName = blobSaveDatabaseName(store);
+	return !!databaseName && blobRestoreFences.has(databaseName);
+}
+
+/**
+ * A token for work that outlives a single check -- an orphan sweep, say -- so it can tell whether any
+ * restore has touched this database since it started, not merely whether one is running right now.
+ */
+export function blobRestoreGeneration(store: any): { database?: string; epoch: number; fenced: boolean } {
+	const database = blobSaveDatabaseName(store);
+	return {
+		database,
+		epoch: database ? (blobRestoreEpochs.get(database) ?? 0) : 0,
+		fenced: !!database && blobRestoreFences.has(database),
+	};
+}
+
+/** True once a restore has fenced this database since `since` was taken, or is fencing it now. */
+export function blobRestoreGenerationChanged(since: { database?: string; epoch: number }): boolean {
+	if (!since.database) return false;
+	if (blobRestoreFences.has(since.database)) return true;
+	return (blobRestoreEpochs.get(since.database) ?? 0) !== since.epoch;
+}
+
+function discardReclamationForDatabase(databaseName: string): void {
+	for (const [filePath, pending] of [...pendingReclamation]) {
+		if (pending.unlinking) continue; // already dispatched; its callback owns the entry
+		if (blobSaveDatabaseName(pending.fileInfo?.store) !== databaseName) continue;
+		pendingReclamation.delete(filePath);
+		settleReclamationWaiters(pending);
+	}
+	if (pendingReclamation.size === 0) resetDrainedQueue();
+}
+
+/** Register a dispatched blob-root unlink so a restore fence can wait for it to land. */
+export function beginBlobUnlink(databaseName: string | undefined): () => void {
+	if (!databaseName) return () => {};
+	let unlinks = inFlightBlobUnlinks.get(databaseName);
+	if (!unlinks) inFlightBlobUnlinks.set(databaseName, (unlinks = { count: 0, waiters: [] }));
+	unlinks.count++;
+	let settled = false;
+	return () => {
+		if (settled) return;
+		settled = true;
+		if (--unlinks.count > 0) return;
+		inFlightBlobUnlinks.delete(databaseName);
+		for (const wake of unlinks.waiters) wake();
+	};
+}
+
+function drainBlobUnlinks(databaseName: string): Promise<void> | undefined {
+	const unlinks = inFlightBlobUnlinks.get(databaseName);
+	if (!unlinks || unlinks.count === 0) return;
+	return new Promise<void>((resolve) => unlinks.waiters.push(resolve));
+}
+
 export function saveBlob(blob: FileBackedBlob, deleteOnFailure = false) {
 	let storageInfo = storageInfoForBlob.get(blob);
 	if (!storageInfo) {
@@ -1826,6 +1974,7 @@ export function saveBlob(blob: FileBackedBlob, deleteOnFailure = false) {
 		if (storageInfo.fileId) return storageInfo; // if there is any file id, we are already saving and can return the info
 		storageInfo.store = currentStore;
 	}
+	assertBlobSaveAllowed(storageInfo.store);
 	storageInfo.deleteOnFailure = deleteOnFailure;
 	if (blob.saveInRecord) {
 		if (!storageInfo.contentBuffer) {
@@ -1848,6 +1997,7 @@ export function saveBlob(blob: FileBackedBlob, deleteOnFailure = false) {
 		// for native blobs, we have to read them from the stream
 		writeBlobWithStream(blob as any, Readable.from(blob.stream()), storageInfo);
 	}
+	trackBlobSave(storageInfo.store, storageInfo.saving);
 	// Track the in-flight save when a migration is collecting them. storageInfo.saving is set
 	// by writeBlobWithStream; writeBlobWithBuffer for small blobs may not produce one. The
 	// wrapping `.then(...)` removes resolved promises from the list so a long migration does not
@@ -2081,7 +2231,9 @@ function writeBlobWithStream(
 				}
 				if (storageInfo.deleteOnFailure) {
 					store.unlock(lockKey);
+					const unlinkDone = beginBlobUnlink(blobSaveDatabaseName(store));
 					unlink(filePath, (error) => {
+						unlinkDone();
 						if (error) logger.debug?.('Error while deleting aborted blob file', error);
 					});
 				} else if (idleTimeoutMs > 0 && !(error as { sourceBlobUnavailable?: boolean }).sourceBlobUnavailable) {
@@ -2343,6 +2495,7 @@ export function repairBlobFile(
 		if (!storageInfo?.fileId || !storageInfo.store) return undefined;
 		if (storageInfo.start !== undefined || storageInfo.end !== undefined) return undefined;
 		store = storageInfo.store;
+		assertBlobSaveAllowed(store);
 		storageInfo.filePath ??= getFilePath(storageInfo);
 		const filePath = storageInfo.filePath;
 		const descriptorSize = (blob as { size?: number }).size;
@@ -2396,6 +2549,7 @@ export function repairBlobFile(
 			repairTargetPath: filePath,
 			repairTempLockKey,
 		});
+		trackBlobSave(store, repairStorageInfo.saving);
 		locksOwnedByWriter = true;
 		const settled = (repairStorageInfo.saving as Promise<void>).then(() => {
 			if (descriptorSize === undefined) (blob as { size?: number }).size = verifiedSize;
@@ -3350,6 +3504,10 @@ export async function cleanupOrphans(database: any, databaseName?: string) {
 		auditStore = table.auditStore;
 		if (auditStore) break;
 	}
+	// Captured before the scan, not before the deletions: the verdict this sweep acts on -- "no record
+	// references this path" -- is formed by the scan below, so a restore that lands while it runs has
+	// already invalidated it.
+	const generation = blobRestoreGeneration(store);
 	const pathsToCheck = new Set<string>();
 	const rootPaths = getRootBlobPathsForDB(store);
 	if (rootPaths) {
@@ -3452,17 +3610,41 @@ export async function cleanupOrphans(database: any, databaseName?: string) {
 		}
 		logger.warn?.('Deleting', pathsToCheck.size, 'orphaned blobs');
 		orphansDeleted += pathsToCheck.size;
+		let deleted = 0;
+		let skipped = 0;
+		let abandonedForRestore = false;
 		for (const path of pathsToCheck) {
+			// This walk is dispatched fire-and-forget and can outlive a restore's close acknowledgement, so
+			// it compares generations rather than asking whether a restore is running right now: one await
+			// here can span a whole restore, leaving the fence clear again by the next iteration.
+			if (!abandonedForRestore && blobRestoreGenerationChanged(generation)) {
+				abandonedForRestore = true;
+				logger.warn?.('Stopping orphaned blob cleanup: the database has been restored since this scan began');
+			}
+			if (abandonedForRestore) {
+				// Keep walking, but only to hand back the locks taken for every candidate up front. Leaving
+				// them held would block the repair path until the process restarts, and collecting the
+				// untouched paths into a second set first would double the footprint of a sweep this
+				// function is explicitly built to run over hours.
+				skipped++;
+				const lockKey = repairTempLocks.get(path);
+				if (lockKey) (store as any).unlock(lockKey);
+				continue;
+			}
+			const unlinkDone = beginBlobUnlink(blobSaveDatabaseName(store));
 			try {
 				await unlinkPromised(path);
+				deleted++;
 			} catch (error) {
 				logger.debug?.('Error deleting file', error);
 			} finally {
+				unlinkDone();
 				const lockKey = repairTempLocks.get(path);
 				if (lockKey) (store as any).unlock(lockKey);
 			}
 		}
-		logger.warn?.('Finished deleting', pathsToCheck.size, 'orphaned blobs');
+		orphansDeleted -= skipped;
+		logger.warn?.('Finished deleting', deleted, 'orphaned blobs');
 		pathsToCheck.clear();
 	}
 	// check each object for any blob references and removes from the paths to check if found

package/resources/databases.ts

@@ -95,6 +95,7 @@ import { resolveRocksMemoryConfig } from '../utility/rocksMemoryConfig.ts';
 import { isProcessRunning } from '../utility/processManagement/processManagement.js';
 import {
 	compileFullTextDefinitions,
+	compileFullTextFields,
 	persistedFullTextIndexNames,
 	reconcileFullTextIndexGenerations,
 	type FullTextDefinition,
@@ -104,7 +105,9 @@ import { projectAttributesToProperties } from './jsonSchemaTypes.ts';
 import {
 	definitionsEqual,
 	mergePeerFullTextDefinitions,
+	mergePeerFullTextFields,
 	readPersistedFullTextDefinitions,
+	readPersistedFullTextFields,
 	retainFullTextDefinitions,
 	serializeFullTextState,
 } from './fullTextSchemaLifecycle.ts';
@@ -1443,6 +1446,12 @@ function initStores(
 				for (const warning of warnings) logger.warn(warning);
 			} else if (warnings.length === 0) warnedFullTextStates.delete(warningKey);
 		}
+		const fullTextFields = readPersistedFullTextFields(
+			primaryAttribute.fullTextFields,
+			primaryAttribute.fullTextIndexes,
+			attributes,
+			(message) => logger.warn(`${databaseName}.${tableName}: ${message}`)
+		);
 		const fullTextIndexGenerations = persistedFullTextIndexGenerations(
 			primaryAttribute.fullTextIndexGenerations,
 			fullTextIndexes
@@ -1451,6 +1460,7 @@ function initStores(
 		if (table && !recreateTable) {
 			if (primaryAttribute.audit === true && table.audit !== true) table.enableAuditing();
 			table.fullTextIndexes = fullTextIndexes;
+			table.fullTextFields = fullTextFields;
 			table.fullTextIndexGenerations = fullTextIndexGenerations;
 			table.fullTextIndexRetirements = fullTextIndexRetirements;
 			indices = table.indices;
@@ -1605,6 +1615,7 @@ function initStores(
 					indices,
 					attributes,
 					fullTextIndexes,
+					fullTextFields,
 					fullTextIndexGenerations,
 					fullTextIndexRetirements,
 					schemaDefined: primaryAttribute.schemaDefined,
@@ -2165,6 +2176,7 @@ interface TableDefinition {
 	/** Internal: this declaration came from the application owned by the current dedicated worker. */
 	isolatedApplicationOwner?: boolean;
 	fullTextIndexes?: FullTextDefinition[];
+	fullTextFields?: string[];
 }
 /**
  * Ensure that we have this database object (that holds a set of tables) set up
@@ -3353,6 +3365,7 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 		cacheControl,
 		isolatedApplicationOwner,
 		fullTextIndexes,
+		fullTextFields,
 	} = tableDefinition;
 	const auditExplicitlyEnabled = audit === true;
 	const auditExplicitlyDisabled = audit === false;
@@ -3555,6 +3568,7 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 	let published = false;
 	let fullTextValuesForPersistence: unknown;
 	let fullTextPersistencePending = false;
+	let fullTextFieldsForPersistence: string[] | undefined;
 	let activeFullTextIndexes: FullTextDefinition[] | undefined;
 	let fullTextIndexGenerationMap: FullTextIndexGenerations = Object.create(null);
 	let fullTextIndexRetirementNames: string[] | undefined;
@@ -3604,23 +3618,43 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 				);
 			}
 			let persistedPrimary = persistedPrimaryDescriptor(Table.dbisDB);
-			let persistedFullTextValues = persistedPrimary.descriptor?.fullTextIndexes;
+			const persistedFullTextState = (name: string, liveValue: unknown) =>
+				persistedPrimary.descriptor === undefined ? liveValue : persistedPrimary.descriptor[name];
+			let persistedFullTextValues = persistedFullTextState('fullTextIndexes', Table.fullTextIndexes);
+			if (origin === 'cluster') {
+				const declaredFields = new Set(
+					readPersistedFullTextFields(
+						persistedFullTextState('fullTextFields', Table.fullTextFields),
+						persistedFullTextValues,
+						catalogAttributes(Table.dbisDB),
+						fullTextWarning
+					)
+				);
+				attributes = attributes.filter((attribute) => {
+					if (!declaredFields.has(attribute.name)) return true;
+					fullTextWarning(`Ignoring peer attribute '${attribute.name}'; the local full-text field is authoritative`);
+					return false;
+				});
+			}
 			const incomingFullTextValues = fullTextIndexesExplicit ? fullTextIndexes : [];
 			let fullTextValidationAttributes: any[] | undefined;
 			if (
 				(persistedFullTextValues !== undefined && (rootStore instanceof RocksDatabase || fullTextIndexesExplicit)) ||
-				persistedPrimary.descriptor?.fullTextIndexRetirements !== undefined ||
+				persistedFullTextState('fullTextIndexRetirements', Table.fullTextIndexRetirements) !== undefined ||
+				(persistedFullTextState('fullTextFields', Table.fullTextFields) !== undefined &&
+					(rootStore instanceof RocksDatabase || fullTextIndexesExplicit || fullTextFields !== undefined)) ||
+				(fullTextFields !== undefined && (!Array.isArray(fullTextFields) || fullTextFields.length > 0)) ||
 				Table.fullTextIndexes?.length > 0 ||
 				(fullTextIndexesExplicit && (!Array.isArray(incomingFullTextValues) || incomingFullTextValues.length > 0))
 			) {
 				if (!(rootStore instanceof RocksDatabase)) {
 					exclusiveLock();
 					persistedPrimary = persistedPrimaryDescriptor(Table.dbisDB);
-					persistedFullTextValues = persistedPrimary.descriptor?.fullTextIndexes;
+					persistedFullTextValues = persistedFullTextState('fullTextIndexes', Table.fullTextIndexes);
 				}
 				const originalAttributes = Table.attributes.slice();
 				fullTextIndexRetirementNames = persistedFullTextIndexNames(
-					persistedPrimary.descriptor?.fullTextIndexRetirements
+					persistedFullTextState('fullTextIndexRetirements', Table.fullTextIndexRetirements)
 				);
 				const relationshipAttributes = originalAttributes.filter((attribute: any) => attribute.relationship);
 				const originalMetadata = {
@@ -3629,6 +3663,12 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 					cacheControl: Table.cacheControl,
 					schemaDefined: Table.schemaDefined,
 				};
+				const originalFullTextState = {
+					indexes: Table.fullTextIndexes.slice(),
+					fields: [...Table.fullTextFields],
+					generations: Object.assign(Object.create(null), Table.fullTextIndexGenerations),
+					retirements: [...Table.fullTextIndexRetirements],
+				};
 				armFullTextLiveStateRestore = () => {
 					if (restoreFullTextLiveState) return;
 					restoreFullTextLiveState = () => {
@@ -3640,16 +3680,32 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 						Object.assign(Table, originalMetadata);
 						Table.properties = projectAttributesToProperties(restored);
 						const restoredPrimary = persistedPrimaryDescriptor(Table.dbisDB).descriptor;
+						if (restoredPrimary === undefined) {
+							Table.fullTextIndexes = originalFullTextState.indexes;
+							Table.fullTextFields = originalFullTextState.fields;
+							Table.fullTextIndexGenerations = originalFullTextState.generations;
+							Table.fullTextIndexRetirements = originalFullTextState.retirements;
+							Table.schemaVersion++;
+							Table.updatedAttributes();
+							refreshDerivedIndexes(Table);
+							return;
+						}
 						const restoredFullTextIndexes =
-							rootStore instanceof RocksDatabase && restoredPrimary?.audit === true
-								? readPersistedFullTextDefinitions(restoredPrimary?.fullTextIndexes, restored, fullTextWarning)
+							rootStore instanceof RocksDatabase && restoredPrimary.audit === true
+								? readPersistedFullTextDefinitions(restoredPrimary.fullTextIndexes, restored, fullTextWarning)
 								: [];
 						Table.fullTextIndexes = restoredFullTextIndexes;
+						Table.fullTextFields = readPersistedFullTextFields(
+							restoredPrimary.fullTextFields,
+							restoredPrimary.fullTextIndexes,
+							restored,
+							fullTextWarning
+						);
 						Table.fullTextIndexGenerations = persistedFullTextIndexGenerations(
-							restoredPrimary?.fullTextIndexGenerations,
+							restoredPrimary.fullTextIndexGenerations,
 							restoredFullTextIndexes
 						);
-						Table.fullTextIndexRetirements = persistedFullTextIndexNames(restoredPrimary?.fullTextIndexRetirements);
+						Table.fullTextIndexRetirements = persistedFullTextIndexNames(restoredPrimary.fullTextIndexRetirements);
 						Table.schemaVersion++;
 						Table.updatedAttributes();
 						refreshDerivedIndexes(Table);
@@ -3672,8 +3728,28 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 				// Before the full-text branches can write an interim descriptor; the check on the merged list
 				// below stays authoritative.
 				assertDerivedFieldOwnership(validationAttributes as any[]);
+				const validateFullTextFields = (definitions: unknown) => {
+					const names = persistedFullTextIndexNames(definitions).map((name) => ({ name }));
+					if (origin === 'cluster')
+						return mergePeerFullTextFields(
+							persistedFullTextState('fullTextFields', Table.fullTextFields),
+							fullTextFields,
+							persistedFullTextValues,
+							definitions,
+							validationAttributes,
+							fullTextWarning
+						);
+					const requestedNames = new Set(names.map(({ name }) => name));
+					return compileFullTextFields(
+						fullTextFields === undefined ? [...requestedNames] : fullTextFields,
+						names,
+						validationAttributes,
+						true
+					);
+				};
 
-				const persistedAudit = persistedPrimary.descriptor?.audit;
+				const persistedAudit =
+					persistedPrimary.descriptor === undefined ? Table.audit : persistedPrimary.descriptor.audit;
 				const durableAudit = persistedAudit === true;
 				const finalAudit =
 					origin === 'cluster'
@@ -3700,6 +3776,7 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 							: [];
 				} else if (fullTextIndexesExplicit) {
 					const compiled = compileFullTextDefinitions(incomingFullTextValues, validationAttributes);
+					fullTextFieldsForPersistence = validateFullTextFields(compiled);
 					if (compiled.length > 0 && !(rootStore instanceof RocksDatabase))
 						throw new ClientError(
 							`Table '${databaseName}.${tableName}' cannot use @fullText with the LMDB storage engine`,
@@ -3710,7 +3787,7 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 							`Table '${databaseName}.${tableName}' must enable audit logging before using @fullText because its transaction log is the derived-index recovery source`,
 							400
 						);
-					const pinAudit = compiled.length > 0 && persistedPrimary.descriptor?.audit !== true;
+					const pinAudit = compiled.length > 0 && persistedAudit !== true;
 					const requestedNames = new Set(compiled.map(({ name }) => name));
 					const durableDefinitions = readPersistedFullTextDefinitions(
 						persistedFullTextValues,
@@ -3739,15 +3816,25 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 							if (interimDefinitions.length > 0) {
 								interimPrimary.fullTextIndexes = interimDefinitions;
 								interimPrimary.fullTextIndexGenerations = persistedFullTextIndexGenerations(
-									persistedPrimary.descriptor?.fullTextIndexGenerations,
+									persistedFullTextState('fullTextIndexGenerations', Table.fullTextIndexGenerations),
 									interimDefinitions
 								);
 							} else {
 								delete interimPrimary.fullTextIndexes;
 								delete interimPrimary.fullTextIndexGenerations;
 							}
+							const interimFullTextFields = readPersistedFullTextFields(
+								persistedFullTextState('fullTextFields', Table.fullTextFields),
+								persistedFullTextValues,
+								durableAttributes,
+								fullTextWarning
+							).filter((name) => requestedNames.has(name));
+							if (interimFullTextFields.length > 0) interimPrimary.fullTextFields = interimFullTextFields;
+							else delete interimPrimary.fullTextFields;
 							const retirements = new Set(
-								persistedFullTextIndexNames(persistedPrimary.descriptor?.fullTextIndexRetirements)
+								persistedFullTextIndexNames(
+									persistedFullTextState('fullTextIndexRetirements', Table.fullTextIndexRetirements)
+								)
 							);
 							for (const name of transitionRetirements) retirements.add(name);
 							for (const name of requestedNames) if (!transitionRetirements.has(name)) retirements.delete(name);
@@ -3779,6 +3866,7 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 					fullTextValuesForPersistence = persistedFullTextValues;
 					activeFullTextIndexes = rootStore instanceof RocksDatabase && finalAudit ? retained : [];
 				}
+				fullTextFieldsForPersistence ??= validateFullTextFields(fullTextValuesForPersistence);
 			}
 			if (activeFullTextIndexes !== undefined) {
 				const durableGenerationDefinitions = readPersistedFullTextDefinitions(
@@ -3793,7 +3881,7 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 				);
 				fullTextIndexGenerationMap = reconcileFullTextIndexGenerations(
 					durableGenerationDefinitions,
-					persistedPrimary.descriptor?.fullTextIndexGenerations,
+					persistedFullTextState('fullTextIndexGenerations', Table.fullTextIndexGenerations),
 					finalGenerationDefinitions,
 					createFullTextIndexGeneration
 				);
@@ -3889,12 +3977,30 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 					activeFullTextIndexes = compiled;
 				}
 			}
+			fullTextFieldsForPersistence =
+				origin === 'cluster'
+					? mergePeerFullTextFields(
+							undefined,
+							fullTextFields,
+							[],
+							fullTextValuesForPersistence,
+							attributes,
+							fullTextWarning
+						)
+					: compileFullTextFields(
+							fullTextFields === undefined ? persistedFullTextIndexNames(fullTextValuesForPersistence) : fullTextFields,
+							persistedFullTextIndexNames(fullTextValuesForPersistence).map((name) => ({ name })),
+							attributes,
+							true
+						);
 			const auditStore = rootStore.auditStore;
 			primaryKeyAttribute = attributes.find((attribute) => attribute.isPrimaryKey) || {};
 			primaryKey = primaryKeyAttribute.name;
 			primaryKeyAttribute.isPrimaryKey = true;
 			primaryKeyAttribute.is_hash_attribute = true; // backward-compat: harperdb@4.x reads this field to open the DBI with correct flags
 			primaryKeyAttribute.schemaDefined = schemaDefined;
+			if (fullTextFieldsForPersistence.length > 0) primaryKeyAttribute.fullTextFields = fullTextFieldsForPersistence;
+			else delete primaryKeyAttribute.fullTextFields;
 			// Old readers treat every attribute row as live schema, so relationships stay on the ignored primary descriptor.
 			if (relationshipDefinitions) primaryKeyAttribute.relationships = relationshipDefinitions;
 			if (Array.isArray(fullTextValuesForPersistence) && fullTextValuesForPersistence.length > 0) {
@@ -4043,6 +4149,7 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 				indices: {},
 				attributes,
 				fullTextIndexes: activeFullTextIndexes ?? [],
+				fullTextFields: fullTextFieldsForPersistence,
 				fullTextIndexGenerations: fullTextIndexGenerationMap,
 				fullTextIndexRetirements: fullTextIndexRetirementNames ?? [],
 				schemaDefined,
@@ -4463,6 +4570,7 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 		if (
 			!deferredPrimaryRow &&
 			(fullTextPersistencePending ||
+				fullTextFieldsForPersistence !== undefined ||
 				(rootStore instanceof RocksDatabase &&
 					activeFullTextIndexes !== undefined &&
 					Array.isArray(fullTextValuesForPersistence)))
@@ -4470,10 +4578,12 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 			const { key, descriptor } = persistedPrimaryDescriptor(attributesDbi);
 			if (descriptor && !tableIsDropping(descriptor, key)) {
 				const updatedPrimary = { ...descriptor };
+				if (fullTextFieldsForPersistence?.length) updatedPrimary.fullTextFields = fullTextFieldsForPersistence;
+				else if (fullTextFieldsForPersistence) delete updatedPrimary.fullTextFields;
 				if (Array.isArray(fullTextValuesForPersistence) && fullTextValuesForPersistence.length > 0) {
 					updatedPrimary.fullTextIndexes = fullTextValuesForPersistence;
 					updatedPrimary.fullTextIndexGenerations = fullTextIndexGenerationMap;
-				} else {
+				} else if (Array.isArray(fullTextValuesForPersistence)) {
 					delete updatedPrimary.fullTextIndexes;
 					delete updatedPrimary.fullTextIndexGenerations;
 				}
@@ -4488,6 +4598,7 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 				else delete updatedPrimary.fullTextIndexRetirements;
 				if (
 					!definitionsEqual(descriptor.fullTextIndexes, updatedPrimary.fullTextIndexes) ||
+					!definitionsEqual(descriptor.fullTextFields, updatedPrimary.fullTextFields) ||
 					JSON.stringify(descriptor.fullTextIndexGenerations ?? {}) !==
 						JSON.stringify(updatedPrimary.fullTextIndexGenerations ?? {}) ||
 					JSON.stringify(descriptor.fullTextIndexRetirements ?? []) !==
@@ -4560,6 +4671,7 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 	} finally {
 		releaseLock();
 	}
+	if (fullTextFieldsForPersistence !== undefined) Table.fullTextFields = fullTextFieldsForPersistence;
 	if (activeFullTextIndexes !== undefined) {
 		Table.fullTextIndexes = activeFullTextIndexes;
 		Table.fullTextIndexGenerations = fullTextIndexGenerationMap;