@harperfast/harper 5.3.0-beta.3 → 5.3.0-beta.4

package/dist/resources/databases.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CHECKPOINT_ALGORITHM = exports.BRANCH_REMOVING_SUFFIX = exports.BRANCH_ROOT_DIR = exports.databases = exports.tables = exports.databaseEventsEmitter = exports.NON_REPLICATING_SYSTEM_TABLES = void 0;
+exports.__setReadOnlyModeForTest = __setReadOnlyModeForTest;
 exports.isReadOnlyMode = isReadOnlyMode;
 exports.getRocksCompression = getRocksCompression;
 exports.resetRocksCompression = resetRocksCompression;
@@ -58,12 +59,17 @@ exports.retakeBranchIdentity = retakeBranchIdentity;
 exports.releaseBranchIdentity = releaseBranchIdentity;
 exports.isBranchIdentity = isBranchIdentity;
 exports.openBranchDatabase = openBranchDatabase;
+exports.branchDatabasesHaveWork = branchDatabasesHaveWork;
 exports.closeBranchDatabases = closeBranchDatabases;
 exports.resetDatabases = resetDatabases;
 exports.resolveDatabaseStorageRoot = resolveDatabaseStorageRoot;
 exports.resolveDatabasePath = resolveDatabasePath;
 exports.database = database;
 exports.dropDatabase = dropDatabase;
+exports.databaseDropRecoveryPending = databaseDropRecoveryPending;
+exports.databaseDropPreparationTargets = databaseDropPreparationTargets;
+exports.prepareDatabaseDrop = prepareDatabaseDrop;
+exports.completeDatabaseDropPreparation = completeDatabaseDropPreparation;
 exports.closeDatabase = closeDatabase;
 exports.closeLoadedDatabases = closeLoadedDatabases;
 exports.table = table;
@@ -113,8 +119,10 @@ const hnswPlaneBinding_ts_1 = require("./indexes/hnswPlaneBinding.js");
 const OpenDBIObject_ts_1 = require("../utility/lmdb/OpenDBIObject.js");
 const rocksdb_js_1 = require("@harperfast/rocksdb-js");
 const PrimaryRocksDatabase_ts_1 = require("./PrimaryRocksDatabase.js");
+const DatabaseTransaction_ts_1 = require("./DatabaseTransaction.js");
 const replayLogs_ts_1 = require("./replayLogs.js");
-const hnswDerivedIndex_ts_1 = require("./indexes/hnswDerivedIndex.js");
+const derivedIndexes_ts_1 = require("./derivedIndexes.js");
+const derivedIndexRegistry_ts_1 = require("./derivedIndexRegistry.js");
 const node_os_1 = require("node:os");
 const RocksIndexStore_ts_1 = require("./RocksIndexStore.js");
 const rocksMemoryConfig_ts_1 = require("../utility/rocksMemoryConfig.js");
@@ -122,7 +130,9 @@ const processManagement_js_1 = require("../utility/processManagement/processMana
 const fullTextSchema_ts_1 = require("./fullTextSchema.js");
 const jsonSchemaTypes_ts_1 = require("./jsonSchemaTypes.js");
 const fullTextSchemaLifecycle_ts_1 = require("./fullTextSchemaLifecycle.js");
+const embedHook_ts_1 = require("./models/embedHook.js");
 const restoreMarker_ts_1 = require("../dataLayer/restoreMarker.js");
+const databaseDropPreparation_ts_1 = require("./databaseDropPreparation.js");
 /**
  * Check if Harper is running in read-only mode.
  * Read-only mode can be enabled via:
@@ -131,6 +141,9 @@ const restoreMarker_ts_1 = require("../dataLayer/restoreMarker.js");
  * - storage.readOnly config setting
  */
 let _isReadOnlyMode;
+function __setReadOnlyModeForTest(value) {
+    _isReadOnlyMode = value;
+}
 function isReadOnlyMode() {
     if (_isReadOnlyMode !== undefined)
         return _isReadOnlyMode;
@@ -401,6 +414,11 @@ function openRocksDatabase(path, options) {
 }
 const lmdbDatabaseEnvs = new Map();
 const rocksdbDatabaseEnvs = new Map();
+const incompleteDatabaseCloses = new Map();
+function databaseRootUnavailable(rootPath) {
+    return ((0, databaseDropPreparation_ts_1.databaseDropPrepared)(rootPath) ||
+        (incompleteDatabaseCloses.size > 0 && incompleteDatabaseCloses.has((0, node_path_1.resolve)(rootPath))));
+}
 // set the following in both global and exports
 (0, globals_js_1._assignPackageExport)('databases', exports.databases);
 (0, globals_js_1._assignPackageExport)('tables', exports.tables);
@@ -419,6 +437,7 @@ const PEER_REDEFINABLE_FIELDS = [
     'elements',
     'properties',
     'embed',
+    'decide',
 ];
 // `indexNulls` is derived from the durable descriptor, never sent by a peer, so naming it in the
 // discard warn would blame the peer for a field it did not write.
@@ -433,6 +452,19 @@ function applyDurableDeclaration(attribute, descriptor) {
             delete attribute[field];
     }
 }
+function persistedFullTextIndexGenerations(value, definitions) {
+    const persisted = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+    const generations = Object.create(null);
+    for (const { name } of definitions) {
+        const generation = persisted[name];
+        if (typeof generation === 'string' && generation.length > 0)
+            generations[name] = generation;
+    }
+    return generations;
+}
+function createFullTextIndexGeneration() {
+    return (0, node_crypto_1.randomBytes)(16).toString('hex');
+}
 /**
  * True when a descriptor claims an index build no live operation in this process can own. The PID and
  * worker generation cannot answer that alone: a container reuses PID 1 and starts the in-memory
@@ -593,6 +625,8 @@ function getDatabases() {
         // TODO: Load any databases defined with explicit storage paths from the config
         const entries = (0, node_fs_1.readdirSync)(databasePath, { withFileTypes: true });
         const blockedByRestore = databasesBlockedByRestore(databasePath);
+        const blockedByDrop = databaseRootsBlockedByDrop(databasePath);
+        const configuredDropCoversDirectory = Object.entries(schemaConfigs).some(([name, config]) => config?.path && (0, node_path_1.resolve)(config.path) === (0, node_path_1.resolve)(databasePath) && blockedByDrop.databaseNames.has(name));
         for (const databaseEntry of entries) {
             // in-progress migration staging dirs are not databases until atomically renamed into place
             if (databaseEntry.name.endsWith(hdbTerms_ts_1.MIGRATING_DIR_SUFFIX))
@@ -607,6 +641,12 @@ function getDatabases() {
                 continue;
             const dbName = (0, node_path_1.basename)(databaseEntry.name, '.mdb');
             const dbPath = (0, node_path_1.join)(databasePath, databaseEntry.name);
+            if (databaseRootUnavailable(dbPath))
+                continue;
+            if (configuredDropCoversDirectory ||
+                blockedByDrop.rootPaths.has(dbPath) ||
+                blockedByDrop.databaseNames.has(dbName))
+                continue;
             if (blockedByRestore.has(dbName))
                 continue;
             if (isOpenBranchPath(dbPath))
@@ -641,10 +681,16 @@ function getDatabases() {
             if (!schemaEntry.isFile()) {
                 const schemaPath = (0, node_path_1.join)(baseSchemaPath, schemaEntry.name);
                 const schemaAuditPath = (0, node_path_1.join)((0, initializePaths_js_1.getTransactionAuditStoreBasePath)(), schemaEntry.name);
+                const blockedByDrop = databaseRootsBlockedByDrop(schemaPath);
                 for (const tableEntry of (0, node_fs_1.readdirSync)(schemaPath, { withFileTypes: true })) {
                     if (tableEntry.isFile() && (0, node_path_1.extname)(tableEntry.name).toLowerCase() === '.mdb') {
+                        const tablePath = (0, node_path_1.join)(schemaPath, tableEntry.name);
+                        if (databaseRootUnavailable(tablePath))
+                            continue;
+                        if (blockedByDrop.rootPaths.has(tablePath) || blockedByDrop.databaseNames.has(schemaEntry.name))
+                            continue;
                         const auditPath = (0, node_path_1.join)(schemaAuditPath, tableEntry.name);
-                        readMetaDb((0, node_path_1.join)(schemaPath, tableEntry.name), (0, node_path_1.basename)(tableEntry.name, '.mdb'), schemaEntry.name, auditPath, true);
+                        readMetaDb(tablePath, (0, node_path_1.basename)(tableEntry.name, '.mdb'), schemaEntry.name, auditPath, true);
                     }
                 }
             }
@@ -653,10 +699,13 @@ function getDatabases() {
     if (schemaConfigs) {
         for (const dbName in schemaConfigs) {
             const schemaConfig = schemaConfigs[dbName];
+            if (databaseDropRecoveryPending(dbName))
+                continue;
             const databasePath = schemaConfig.path;
             if ((0, node_fs_1.existsSync)(databasePath)) {
                 const entries = (0, node_fs_1.readdirSync)(databasePath, { withFileTypes: true });
                 const blockedByRestore = databasesBlockedByRestore(databasePath);
+                const blockedByDrop = databaseRootsBlockedByDrop(databasePath);
                 for (const databaseEntry of entries) {
                     if (databaseEntry.name.endsWith(hdbTerms_ts_1.MIGRATING_DIR_SUFFIX))
                         continue; // migration staging dir
@@ -666,14 +715,18 @@ function getDatabases() {
                         continue; // reserved branch root
                     if (blockedByRestore.has((0, node_path_1.basename)(databaseEntry.name, '.mdb')))
                         continue;
-                    if (isOpenBranchPath((0, node_path_1.join)(databasePath, databaseEntry.name)))
+                    const dbPath = (0, node_path_1.join)(databasePath, databaseEntry.name);
+                    if (databaseRootUnavailable(dbPath))
+                        continue;
+                    if (blockedByDrop.rootPaths.has(dbPath) || blockedByDrop.databaseNames.has(dbName))
+                        continue;
+                    if (isOpenBranchPath(dbPath))
                         continue;
                     if (databaseEntry.isFile() && (0, node_path_1.extname)(databaseEntry.name).toLowerCase() === '.mdb') {
-                        readMetaDb((0, node_path_1.join)(databasePath, databaseEntry.name), (0, node_path_1.basename)(databaseEntry.name, '.mdb'), dbName);
+                        readMetaDb(dbPath, (0, node_path_1.basename)(databaseEntry.name, '.mdb'), dbName);
                     }
                     else {
                         try {
-                            const dbPath = (0, node_path_1.join)(databasePath, databaseEntry.name);
                             const files = (0, node_fs_1.readdirSync)(dbPath, { withFileTypes: true });
                             if (files.find((file) => file.name === 'CURRENT')?.isFile() &&
                                 files.some((file) => file.name.startsWith('MANIFEST-'))) {
@@ -694,7 +747,7 @@ function getDatabases() {
                 for (const tableName in tableConfigs) {
                     const tableConfig = tableConfigs[tableName];
                     const tablePath = (0, node_path_1.join)(tableConfig.path, (0, node_path_1.basename)(tableName + '.mdb'));
-                    if ((0, node_fs_1.existsSync)(tablePath)) {
+                    if (!databaseRootUnavailable(tablePath) && !(0, restoreMarker_ts_1.databaseDropMarkerPresent)(tablePath) && (0, node_fs_1.existsSync)(tablePath)) {
                         readMetaDb(tablePath, tableName, dbName, null, true);
                     }
                 }
@@ -704,6 +757,8 @@ function getDatabases() {
     }
     // now remove any databases or tables that have been removed
     for (const dbName in exports.databases) {
+        if (databaseUsesPreparedRoot(dbName))
+            continue;
         const definedTables = definedDatabases.get(dbName);
         if (definedTables) {
             const tables = exports.databases[dbName];
@@ -912,6 +967,38 @@ function databasesBlockedByRestore(databasePath) {
     }
     return blocked;
 }
+const loggedDropMarkersByDirectory = new Map();
+function databaseRootsBlockedByDrop(databasePath) {
+    const rootPaths = new Set();
+    const databaseNames = new Set();
+    const directoryKey = (0, node_path_1.resolve)(databasePath);
+    const previouslyLogged = loggedDropMarkersByDirectory.get(directoryKey) ?? new Set();
+    const currentMarkers = new Set();
+    for (const drop of (0, restoreMarker_ts_1.scanBlockedDatabaseDrops)(databasePath)) {
+        currentMarkers.add(drop.markerPath);
+        const message = drop.databaseName
+            ? `Incomplete drop of database '${drop.databaseName}' detected; not loading ${drop.rootPath} — retry drop_database to recover (${drop.markerPath})`
+            : `Incomplete database drop with invalid marker metadata detected; not loading ${drop.rootPath} — inspect the root and marker before manual recovery (${drop.markerPath})`;
+        if (previouslyLogged.has(drop.markerPath))
+            logger.trace(message);
+        else
+            logger.error(message);
+        rootPaths.add(drop.rootPath);
+        if (drop.databaseName)
+            databaseNames.add(drop.databaseName);
+    }
+    if (currentMarkers.size > 0)
+        loggedDropMarkersByDirectory.set(directoryKey, currentMarkers);
+    else
+        loggedDropMarkersByDirectory.delete(directoryKey);
+    return { rootPaths, databaseNames };
+}
+function configuredDropPendingWithin(databasePath, schemaConfigs) {
+    const normalizedPath = (0, node_path_1.resolve)(databasePath);
+    return Object.entries(schemaConfigs).some(([name, config]) => config?.path &&
+        (0, node_path_1.resolve)(config.path) === normalizedPath &&
+        (0, restoreMarker_ts_1.scanBlockedDatabaseDrops)(config.path).some((drop) => drop.databaseName === name));
+}
 /**
  * This is responsible for reading the internal dbi of a single database file to get a list of all the tables and
  * their indexed or registered attributes
@@ -1094,14 +1181,15 @@ function initStores(path, rootStore, databaseName, { defaultTable, auditPath, is
         }
         if (failedAttempts < MAX_INTERRUPTED_DROP_ATTEMPTS) {
             try {
-                completeInterruptedDrop(rootStore, attributesDbi, databaseName, tableName);
+                const completed = completeInterruptedDrop(rootStore, attributesDbi, databaseName, tableName);
                 // Sweep every generation this worker has ever tracked for this table, not
                 // just the one just resolved: if a prior generation was exhausted here,
                 // then resolved+recreated+re-dropped by another worker as this generation
                 // without this worker ever observing a live row in between (the only other
                 // place that sweeps), the prior generation's entry would otherwise never
                 // be cleared.
-                clearInterruptedDropEntries(path, tableName);
+                if (completed)
+                    clearInterruptedDropEntries(path, tableName);
                 definedTables?.delete(tableName);
             }
             catch (error) {
@@ -1188,10 +1276,14 @@ function initStores(path, rootStore, databaseName, { defaultTable, auditPath, is
             else if (warnings.length === 0)
                 warnedFullTextStates.delete(warningKey);
         }
+        const fullTextIndexGenerations = persistedFullTextIndexGenerations(primaryAttribute.fullTextIndexGenerations, fullTextIndexes);
+        const fullTextIndexRetirements = (0, fullTextSchema_ts_1.persistedFullTextIndexNames)(primaryAttribute.fullTextIndexRetirements);
         if (table && !recreateTable) {
             if (primaryAttribute.audit === true && table.audit !== true)
                 table.enableAuditing();
             table.fullTextIndexes = fullTextIndexes;
+            table.fullTextIndexGenerations = fullTextIndexGenerations;
+            table.fullTextIndexRetirements = fullTextIndexRetirements;
             indices = table.indices;
             existingAttributes = table.attributes;
             table.schemaVersion++;
@@ -1338,6 +1430,8 @@ function initStores(path, rootStore, databaseName, { defaultTable, auditPath, is
                 indices,
                 attributes,
                 fullTextIndexes,
+                fullTextIndexGenerations,
+                fullTextIndexRetirements,
                 schemaDefined: primaryAttribute.schemaDefined,
                 dbisDB: attributesDbi,
             }));
@@ -1345,8 +1439,7 @@ function initStores(path, rootStore, databaseName, { defaultTable, auditPath, is
             if (!destination)
                 exports.databaseEventsEmitter.emit('updateTable', table);
         }
-        void table.derivedIndexRuntime?.close();
-        table.derivedIndexRuntime = (0, hnswDerivedIndex_ts_1.attachDerivedIndexes)(table);
+        (0, derivedIndexes_ts_1.refreshDerivedIndexes)(table);
         if (Array.isArray(primaryAttribute.relationships)) {
             relationshipsToHydrate.push({ table, databaseName, tableName, definitions: primaryAttribute.relationships });
         }
@@ -1650,10 +1743,27 @@ function openBranchDatabase(path, databaseName, storeName, blobRoots) {
         releaseBranchIdentity(storeName);
         const stranded = rocksdbDatabaseEnvs.get(path);
         rocksdbDatabaseEnvs.delete(path);
+        const auditCleanup = stranded?.auditStore?.stopAuditCleanup?.();
+        auditCleanup?.catch((cleanupError) => logger.warn(`Error retiring audit cleanup for branch database at ${path}`, cleanupError));
         closeBranchHandles(path, stranded, openedStores, tables);
         throw error;
     }
-    let closed = false;
+    let closing;
+    let handleTeardownStarted = false;
+    const unregisterBranch = () => {
+        if (openBranches.get(path) === branch)
+            openBranches.delete(path);
+        releaseBranchIdentity(storeName);
+        rocksdbDatabaseEnvs.delete(path);
+        manageThreads.markBranchStorePath(path, false);
+    };
+    const closeRemainingHandles = () => {
+        const closeFailures = closeBranchHandles(path, rootStore, openedStores, tables);
+        if (closeFailures.length) {
+            throw new AggregateError(closeFailures, `Could not close branch database '${databaseName}'`);
+        }
+        unregisterBranch();
+    };
     const branch = {
         tables,
         rootStore,
@@ -1665,14 +1775,59 @@ function openBranchDatabase(path, databaseName, storeName, blobRoots) {
         close() {
             // guard on the handle, not on the registrations: those are keyed by path, and a closed
             // branch frees its path, so a stale handle would otherwise tear down its successor
-            if (closed)
-                return;
-            closed = true;
-            openBranches.delete(path);
-            releaseBranchIdentity(storeName);
-            rocksdbDatabaseEnvs.delete(path);
-            manageThreads.markBranchStorePath(path, false);
-            closeBranchHandles(path, rootStore, openedStores, tables);
+            if (closing)
+                return closing;
+            if (handleTeardownStarted) {
+                const operation = Promise.resolve().then(closeRemainingHandles);
+                const retryable = operation.catch((error) => {
+                    if (closing === retryable)
+                        closing = undefined;
+                    throw error;
+                });
+                closing = retryable;
+                closing.catch(() => { });
+                return closing;
+            }
+            const releaseActivation = (0, derivedIndexes_ts_1.suspendDerivedIndexActivation)(rootStore);
+            const commitSuspension = (0, DatabaseTransaction_ts_1.suspendDatabaseCommits)([rootStore]);
+            const deadline = Date.now() + (0, DatabaseTransaction_ts_1.getDatabaseCommitDrainTimeoutMilliseconds)();
+            let closed = false;
+            const operation = commitSuspension
+                .waitForDrain({ deadline, databaseName })
+                .then(() => settleTableMaintenance(tables, deadline))
+                .then(() => settleBranchDerivedIndexes(tables))
+                .then(() => rootStore.auditStore?.stopAuditCleanup?.())
+                .then(() => {
+                handleTeardownStarted = true;
+                closeRemainingHandles();
+                commitSuspension.release();
+                releaseActivation();
+                closed = true;
+            })
+                .finally(() => {
+                if (!closed && !handleTeardownStarted) {
+                    commitSuspension.release();
+                    releaseActivation();
+                    resumeTableMaintenance(tables);
+                    for (const table of Object.values(tables))
+                        (0, derivedIndexes_ts_1.refreshDerivedIndexes)(table);
+                }
+                else if (!closed) {
+                    // Native handle teardown started, so this wrapper graph cannot safely return to service.
+                    (0, DatabaseTransaction_ts_1.permanentlySuspendDatabaseCommits)([rootStore]);
+                    (0, derivedIndexes_ts_1.permanentlySuspendDerivedIndexActivation)(rootStore);
+                    commitSuspension.release();
+                    releaseActivation();
+                }
+            });
+            const retryable = operation.catch((error) => {
+                if (closing === retryable)
+                    closing = undefined;
+                throw error;
+            });
+            closing = retryable;
+            closing.catch(() => { });
+            return closing;
         },
     };
     openBranches.set(path, branch);
@@ -1689,7 +1844,7 @@ function openBranchDatabase(path, databaseName, storeName, blobRoots) {
  */
 function closeBranchHandles(path, rootStore, openedStores = [], tables = {}) {
     const reclamationPaths = new Set([path]);
-    rootStore?.auditStore?.stopAuditCleanup?.();
+    const closeFailures = [];
     const closeStore = (store, description) => {
         if (!store || store.status === 'closed')
             return;
@@ -1700,6 +1855,7 @@ function closeBranchHandles(path, rootStore, openedStores = [], tables = {}) {
         }
         catch (error) {
             logger.warn(`Error closing ${description} for branch database at ${path}`, error);
+            closeFailures.push(error);
         }
     };
     // the class, before its stores: an expiration timer or a reclamation handler on a closed store
@@ -1721,11 +1877,32 @@ function closeBranchHandles(path, rootStore, openedStores = [], tables = {}) {
         blob_ts_1.databasePaths.delete(rootStore);
     for (const reclamationPath of reclamationPaths)
         (0, storageReclamation_ts_1.removeStorageReclamation)(reclamationPath);
+    return closeFailures;
+}
+async function settleBranchDerivedIndexes(tables) {
+    const attachments = new Set();
+    for (const tableName in tables) {
+        const attachment = tables[tableName]?.derivedIndexRuntime;
+        if (attachment)
+            attachments.add(attachment);
+    }
+    await Promise.all([...attachments].map((attachment) => attachment.close()));
 }
 /** Branches are process-local, so this is shutdown, not a data operation. */
-function closeBranchDatabases() {
-    for (const branch of [...openBranches.values()])
-        branch?.close();
+function branchDatabasesHaveWork() {
+    return openBranches.size > 0;
+}
+async function closeBranchDatabases(requireClosed = false) {
+    const results = await Promise.allSettled([...openBranches.values()].map((branch) => branch?.close()));
+    const failures = [];
+    for (const result of results) {
+        if (result.status === 'rejected') {
+            logger.warn('Error closing branch database during worker teardown', result.reason);
+            failures.push(result.reason);
+        }
+    }
+    if (requireClosed && failures.length > 0)
+        throw new AggregateError(failures, 'Could not close every branch database during worker teardown');
 }
 function resetDatabases() {
     loadedDatabases = false;
@@ -1819,13 +1996,22 @@ function resolveDatabasePath(databaseName) {
  * @returns
  */
 function database({ database: databaseName, table: tableName }) {
+    return openDatabaseRoot({ database: databaseName, table: tableName });
+}
+/**
+ * Open a database root. Destructive DDL uses the internal bypass only after it owns the database's
+ * drop-preparation fence; public callers must continue to fail while that fence is held.
+ */
+function openDatabaseRoot({ database: databaseName, table: tableName }, { allowPreparedDrop = false } = {}) {
     if (!databaseName)
         databaseName = DEFAULT_DATABASE_NAME;
     getDatabases();
-    ensureDB(databaseName);
-    const definedDatabase = definedDatabases.get(databaseName);
+    let definedDatabase = definedDatabases.get(databaseName);
     if (definedDatabase?.rootStore) {
-        return definedDatabase.rootStore;
+        const rootStore = definedDatabase.rootStore;
+        if (!allowPreparedDrop && databaseRootUnavailable(rootStore.path))
+            throw new hdbError_ts_1.DatabaseClosingError(databaseName);
+        return rootStore;
     }
     const databaseConfig = (0, environmentManager_ts_1.get)(hdbTerms_ts_1.CONFIG_PARAMS.DATABASES) || {};
     if (process.env.SCHEMAS_DATA_PATH) {
@@ -1833,10 +2019,36 @@ function database({ database: databaseName, table: tableName }) {
     }
     const tablePath = tableName && databaseConfig[databaseName]?.tables?.[tableName]?.path;
     const databasePath = resolveDatabaseStorageRoot(databaseName, tableName);
+    if (!allowPreparedDrop && configuredDropPendingWithin(databasePath, databaseConfig))
+        throw new hdbError_ts_1.DatabaseClosingError(databaseName);
+    // A configured path is a scan root, not an exact database path, so an unresolved alias can
+    // target any child store. Keep first-open fenced until the destructive operation completes.
+    if (!allowPreparedDrop && databaseConfig[databaseName]?.path) {
+        const blockedRestores = (0, restoreMarker_ts_1.scanBlockedRestores)(databasePath);
+        if (blockedRestores.length > 0) {
+            const error = new Error(`Database '${databaseName}' shares a configured path with an ${blockedRestores[0][1]} restore of '${blockedRestores[0][0]}'; complete that restore before reopening it`);
+            error.statusCode = 409;
+            throw error;
+        }
+        if ((0, databaseDropPreparation_ts_1.databaseDropPreparedWithin)(databasePath))
+            throw new hdbError_ts_1.DatabaseClosingError(databaseName);
+        if ((0, restoreMarker_ts_1.scanBlockedDatabaseDrops)(databasePath).length > 0) {
+            const error = new Error(`Database '${databaseName}' shares a configured path with an incomplete drop; retry drop_database to recover it`);
+            error.statusCode = 409;
+            throw error;
+        }
+    }
     let rootStore;
     const useRocksdb = (process.env.HARPER_STORAGE_ENGINE || (0, environmentManager_ts_1.get)(hdbTerms_ts_1.CONFIG_PARAMS.STORAGE_ENGINE)) !== 'lmdb';
+    const path = useRocksdb
+        ? (0, node_path_1.join)(databasePath, tablePath ? tableName : databaseName)
+        : (0, node_path_1.join)(databasePath, `${tablePath ? tableName : databaseName}.mdb`);
+    if (!allowPreparedDrop && databaseRootUnavailable(path))
+        throw new hdbError_ts_1.DatabaseClosingError(databaseName);
+    throwIfBlockedByRestore(path, databaseName);
+    ensureDB(databaseName);
+    definedDatabase = definedDatabases.get(databaseName);
     if (useRocksdb) {
-        const path = (0, node_path_1.join)(databasePath, tablePath ? tableName : databaseName);
         // the scan is not the only way to reach a branch's directory: a branch leaves its store in
         // `rocksdbDatabaseEnvs`, so without this an on-demand open would staple it onto
         // `definedDatabases` and the next `closeDatabase` would close it under the live handle
@@ -1850,7 +2062,6 @@ function database({ database: databaseName, table: tableName }) {
             // this on-demand open (create_table/create_database and friends) must not resurrect a
             // database that a restore is rewriting (or left half-purged) — the scan-time restore
             // checks don't cover this path
-            throwIfBlockedByRestore(path, databaseName);
             rootStore = openRocksDatabase(path, {
                 disableWAL: false,
                 enableStats: true,
@@ -1859,7 +2070,6 @@ function database({ database: databaseName, table: tableName }) {
         }
     }
     else {
-        const path = (0, node_path_1.join)(databasePath, `${tablePath ? tableName : databaseName}.mdb`);
         rootStore = lmdbDatabaseEnvs.get(path);
         if (!rootStore || rootStore.status === 'closed') {
             // TODO: validate database name
@@ -1876,6 +2086,11 @@ function database({ database: databaseName, table: tableName }) {
     return rootStore;
 }
 function throwIfBlockedByRestore(dbPath, databaseName) {
+    if ((0, restoreMarker_ts_1.databaseDropMarkerPresent)(dbPath)) {
+        const error = new Error(`Database '${databaseName}' has an incomplete drop; retry drop_database to recover it`);
+        error.statusCode = 409;
+        throw error;
+    }
     const restoreState = (0, restoreMarker_ts_1.checkRestoreState)(dbPath);
     if (restoreState !== 'clear') {
         const error = new Error(restoreState === 'in-progress'
@@ -1885,83 +2100,234 @@ function throwIfBlockedByRestore(dbPath, databaseName) {
         throw error;
     }
 }
-/**
- * Take the per-database restore lock for a drop, refusing (409) if a restore holds it (in-progress)
- * or a crashed restore left a marker (incomplete). Pushes the acquired lock onto `held` so the
- * caller releases it after the drop. On refusal, releases anything already held and throws.
- *
- * The lock is not reentrant within a process, so a path already in `held` must be skipped — every
- * table in a RocksDB database shares one root store (and one lock path), and re-acquiring it in the
- * same drop would spuriously 409 on the second table.
- */
-function lockDatabaseForDrop(dbPath, databaseName, held) {
-    if (held.some((h) => h.dbPath === dbPath))
+function lockDatabaseForDrop(dbPath, databaseName, held, blobDatabaseName = databaseName, blobPaths = (0, blob_ts_1.getBlobPathsForDatabaseName)(blobDatabaseName)) {
+    if (held.some((lock) => lock.dbPath === dbPath))
         return;
-    let lock;
     try {
-        lock = (0, restoreMarker_ts_1.acquireRestoreLock)(dbPath);
+        held.push((0, restoreMarker_ts_1.beginDatabaseDrop)(dbPath, databaseName, blobDatabaseName, blobPaths));
     }
     catch (error) {
-        for (const h of held)
-            (0, restoreMarker_ts_1.releaseRestoreLock)(h);
-        throw error; // 409: a restore is in progress and holds the lock
-    }
-    // We now hold the lock, so no restore is active. A surviving marker is therefore debris from a
-    // crashed restore (incomplete) — refuse rather than delete a directory that still needs recovery.
-    if ((0, restoreMarker_ts_1.restoreMarkerPresent)(dbPath)) {
-        (0, restoreMarker_ts_1.releaseRestoreLock)(lock);
-        for (const h of held)
-            (0, restoreMarker_ts_1.releaseRestoreLock)(h);
-        const error = new Error(`Database '${databaseName}' has an incomplete restore; rerun restore_backup to recover it`);
-        error.statusCode = 409;
+        const cleanupFailures = [];
+        for (const lock of held.splice(0)) {
+            try {
+                (0, restoreMarker_ts_1.cancelDatabaseDrop)(lock);
+            }
+            catch (cleanupError) {
+                cleanupFailures.push(cleanupError);
+            }
+        }
+        if (cleanupFailures.length > 0)
+            throw new AggregateError([error, ...cleanupFailures], `Could not cancel database drop '${databaseName}'`);
         throw error;
     }
-    held.push(lock);
+}
+function releaseDatabaseDropLocks(locks, retainMarkers) {
+    const failures = [];
+    while (locks.length > 0) {
+        try {
+            const lock = locks.shift();
+            if (retainMarkers)
+                (0, restoreMarker_ts_1.abandonDatabaseDrop)(lock);
+            else
+                (0, restoreMarker_ts_1.cancelDatabaseDrop)(lock);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    if (failures.length > 0)
+        throw new AggregateError(failures, 'Could not release database drop locks');
+}
+function inferDropBlobDatabaseName(databaseName, rootPath) {
+    const schemaConfigs = (0, environmentManager_ts_1.get)(hdbTerms_ts_1.CONFIG_PARAMS.DATABASES) || {};
+    const databaseConfig = schemaConfigs[databaseName];
+    const normalizedRootPath = (0, node_path_1.resolve)(rootPath);
+    for (const [tableName, tableConfig] of Object.entries(databaseConfig?.tables || {})) {
+        if (!tableConfig?.path)
+            continue;
+        if ([(0, node_path_1.resolve)(tableConfig.path, tableName), (0, node_path_1.resolve)(tableConfig.path, `${tableName}.mdb`)].includes(normalizedRootPath))
+            return databaseName;
+    }
+    if ((0, node_path_1.resolve)((0, node_path_1.dirname)(rootPath)) === (0, node_path_1.resolve)((0, initializePaths_js_1.getBaseSchemaPath)(), databaseName))
+        return databaseName;
+    const physicalName = (0, node_path_1.basename)(rootPath).replace(/\.mdb$/, '');
+    const rootDirectory = (0, node_path_1.resolve)((0, node_path_1.dirname)(rootPath));
+    if (databaseConfig?.path && (0, node_path_1.resolve)(databaseConfig.path) === rootDirectory) {
+        if (!schemaConfigs[physicalName]?.path)
+            return physicalName;
+        for (const [configuredName, configured] of Object.entries(schemaConfigs)) {
+            if (configured?.path && (0, node_path_1.resolve)(configured.path) === rootDirectory)
+                return configuredName;
+        }
+    }
+    try {
+        const storageRoot = resolveDatabaseStorageRoot(databaseName);
+        if ([(0, node_path_1.resolve)(storageRoot, databaseName), (0, node_path_1.resolve)(storageRoot, `${databaseName}.mdb`)].includes(normalizedRootPath))
+            return databaseName;
+    }
+    catch { }
+    return physicalName;
+}
+const incompleteDatabaseDropStores = new Map();
+function rememberIncompleteDatabaseClose(databaseNames, rootPaths, retry) {
+    const names = new Set(databaseNames);
+    const normalizedPaths = [...new Set([...rootPaths].map((rootPath) => (0, node_path_1.resolve)(rootPath)))];
+    const incompleteClose = { databaseNames: names, rootPaths: normalizedPaths, retry };
+    for (const rootPath of normalizedPaths)
+        incompleteDatabaseCloses.set(rootPath, incompleteClose);
+    logger.warn(`Database '${[...names].join("', '")}' handles remain partially closed on this worker; the affected roots stay unavailable until drop_database is retried or the worker restarts`, normalizedPaths);
+}
+function incompleteDatabaseClosePaths(databaseName) {
+    const rootPaths = new Set();
+    for (const incompleteClose of new Set(incompleteDatabaseCloses.values())) {
+        if (!incompleteClose.databaseNames.has(databaseName))
+            continue;
+        for (const rootPath of incompleteClose.rootPaths)
+            rootPaths.add(rootPath);
+    }
+    return [...rootPaths];
+}
+async function retryIncompleteDatabaseClose(rootPath) {
+    const incompleteClose = incompleteDatabaseCloses.get((0, node_path_1.resolve)(rootPath));
+    if (!incompleteClose)
+        return;
+    if (!incompleteClose.task) {
+        const operation = incompleteClose.retry().then(() => {
+            for (const path of incompleteClose.rootPaths) {
+                if (incompleteDatabaseCloses.get(path) === incompleteClose)
+                    incompleteDatabaseCloses.delete(path);
+            }
+        });
+        let retryable;
+        retryable = operation.catch((error) => {
+            if (incompleteClose.task === retryable)
+                incompleteClose.task = undefined;
+            throw error;
+        });
+        incompleteClose.task = retryable;
+    }
+    await incompleteClose.task;
+}
+async function destroyIncompleteDatabaseRoot(rootPath) {
+    const rootStore = incompleteDatabaseDropStores.get(rootPath);
+    if (!rootStore || !(0, node_fs_1.existsSync)(rootPath)) {
+        incompleteDatabaseDropStores.delete(rootPath);
+        await (0, promises_1.rm)(rootPath, { recursive: true, force: true });
+        return;
+    }
+    if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
+        if (rootStore.status === 'open') {
+            await rootStore.dbisDb?.close?.();
+            await rootStore.close();
+        }
+        await rootStore.destroy();
+    }
+    else {
+        if (rootStore.status === 'open')
+            await rootStore.close();
+        await (0, promises_1.rm)(rootPath, { force: true });
+    }
+    incompleteDatabaseDropStores.delete(rootPath);
+}
+async function resumeIncompleteDatabaseDrop(databaseName, rootPaths) {
+    const dropLocks = [];
+    let destructiveWorkStarted = false;
+    try {
+        const paths = new Set(rootPaths);
+        for (const rootPath of paths)
+            await retryIncompleteDatabaseClose(rootPath);
+        if ((0, rocksdb_js_1.registryStatus)().some((entry) => paths.has(entry.path) && entry.refCount > 0 && !incompleteDatabaseDropStores.has(entry.path)))
+            throw new hdbError_ts_1.DatabaseClosingError(databaseName);
+        for (const rootPath of paths)
+            lockDatabaseForDrop(rootPath, databaseName, dropLocks, inferDropBlobDatabaseName(databaseName, rootPath));
+        destructiveWorkStarted = true;
+        for (const lock of dropLocks)
+            await destroyIncompleteDatabaseRoot(lock.dbPath);
+        await (0, blob_ts_1.deleteBlobPaths)(dropLocks.flatMap((lock) => lock.blobPaths));
+        while (dropLocks.length > 0)
+            (0, restoreMarker_ts_1.completeDatabaseDrop)(dropLocks.shift());
+    }
+    finally {
+        releaseDatabaseDropLocks(dropLocks, destructiveWorkStarted);
+    }
 }
 /**
  * Delete the database
  * @param databaseName
  */
-async function dropDatabase(databaseName) {
-    if (!exports.databases[databaseName])
-        throw new Error('Database does not exist');
-    const dbTables = exports.databases[databaseName];
-    let rootStore;
-    // Hold the per-database restore lock across the entire drop so its file deletion can never
-    // interleave with a restore's purge-and-copy on the same directory — a destroy landing after a
-    // restore's copy would gut a "successful" restore, and vice versa. Restore takes the same lock
-    // (before writing its marker), so both operations serialize on this one primitive rather than on
-    // a check-then-act marker probe. Released in the finally below.
-    const restoreLocks = [];
+async function dropDatabase(databaseName, requestedRootPaths = []) {
+    if (!exports.databases[databaseName]) {
+        const rootPaths = new Set(requestedRootPaths);
+        if (rootPaths.size === 0)
+            throw new Error('Database does not exist');
+        return resumeIncompleteDatabaseDrop(databaseName, rootPaths);
+    }
+    const { databaseNames, dbTables, rootStores } = collectDatabaseGraph(databaseName);
+    const dropLocks = [];
+    let releaseDerivedIndexActivation;
+    let destructiveWorkStarted = false;
+    let dropCompleted = false;
     try {
-        for (const tableName in dbTables) {
-            const table = dbTables[tableName];
-            rootStore = table.primaryStore.rootStore;
-            if (rootStore instanceof rocksdb_js_1.RocksDatabase)
-                lockDatabaseForDrop(rootStore.path, databaseName, restoreLocks);
+        if (rootStores.size === 0) {
+            rootStores.add(openDatabaseRoot({ database: databaseName }, { allowPreparedDrop: true }));
+        }
+        const blobStorageByRootPath = new Map([...rootStores].map((rootStore) => [
+            rootStore.path,
+            {
+                databaseName: rootStore.databaseName ?? databaseName,
+                paths: (0, blob_ts_1.getRootBlobPathsForDB)(rootStore),
+            },
+        ]));
+        for (const rootPath of new Set([...requestedRootPaths, ...blobStorageByRootPath.keys()])) {
+            const blobStorage = blobStorageByRootPath.get(rootPath);
+            const blobDatabaseName = blobStorage?.databaseName ?? inferDropBlobDatabaseName(databaseName, rootPath);
+            lockDatabaseForDrop(rootPath, databaseName, dropLocks, blobDatabaseName, blobStorage?.paths ?? (0, blob_ts_1.getBlobPathsForDatabaseName)(blobDatabaseName));
+        }
+        const openedRootPaths = new Set([...rootStores].map((rootStore) => rootStore.path));
+        const detachedRootPaths = dropLocks.map((lock) => lock.dbPath).filter((rootPath) => !openedRootPaths.has(rootPath));
+        const detachedRootPathSet = new Set(detachedRootPaths);
+        const detachedRootHasForeignHandle = () => (0, rocksdb_js_1.registryStatus)().some((entry) => detachedRootPathSet.has(entry.path) && entry.refCount > 0 && !incompleteDatabaseDropStores.has(entry.path));
+        if (detachedRootHasForeignHandle())
+            throw new hdbError_ts_1.DatabaseClosingError(databaseName);
+        releaseDerivedIndexActivation = await settleDatabaseDerivedIndexes(dbTables, true, rootStores);
+        destructiveWorkStarted = true;
+        for (const rootStore of rootStores) {
             lmdbDatabaseEnvs.delete(rootStore.path);
             rocksdbDatabaseEnvs.delete(rootStore.path);
         }
-        for (const tableName in dbTables) {
-            exports.databaseEventsEmitter.emit('dropTable', tableName, databaseName);
+        for (const [tableName, table] of Object.entries(dbTables)) {
+            exports.databaseEventsEmitter.emit('dropTable', table.tableName ?? tableName, table.databaseName);
         }
-        if (databaseName === 'data') {
-            for (const tableName in exports.tables) {
-                delete exports.tables[tableName];
+        for (const name of databaseNames) {
+            if (name === 'data') {
+                for (const tableName in exports.tables) {
+                    delete exports.tables[tableName];
+                }
+                delete exports.tables[DEFINED_TABLES];
             }
-            delete exports.tables[DEFINED_TABLES];
+            delete exports.databases[name];
+            definedDatabases?.delete(name);
+            exports.databaseEventsEmitter.emit('dropDatabase', name);
         }
-        delete exports.databases[databaseName];
-        exports.databaseEventsEmitter.emit('dropDatabase', databaseName);
-        if (rootStore) {
-            // awaited: retirement stops the loop admitting work, the barrier is what says the pass that was
-            // already running has released the stores this is about to close and unlink
+        const closedStores = new Set();
+        for (const table of Object.values(dbTables)) {
+            if (!(table?.primaryStore?.rootStore instanceof rocksdb_js_1.RocksDatabase))
+                continue;
+            for (const store of [...Object.values(table.indices || {}), table.primaryStore]) {
+                if (!store || closedStores.has(store))
+                    continue;
+                closedStores.add(store);
+                await store.close?.();
+            }
+        }
+        for (const rootStore of rootStores) {
             await rootStore.auditStore?.stopAuditCleanup?.();
             (0, storageReclamation_ts_1.removeStorageReclamation)(rootStore.path);
             if (rootStore.status === 'open') {
                 if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
-                    rootStore.close();
-                    rootStore.destroy();
+                    await rootStore.dbisDb?.close?.();
+                    await rootStore.close();
+                    await rootStore.destroy();
                 }
                 else {
                     await rootStore.close();
@@ -1969,116 +2335,367 @@ async function dropDatabase(databaseName) {
                 }
             }
         }
-        else {
-            rootStore = database({ database: databaseName, table: null });
-            // a tableless database resolves its root store here rather than in the loop above, so take
-            // the drop lock now (still before any destructive step)
-            if (rootStore instanceof rocksdb_js_1.RocksDatabase)
-                lockDatabaseForDrop(rootStore.path, databaseName, restoreLocks);
-            await rootStore.auditStore?.stopAuditCleanup?.();
-            (0, storageReclamation_ts_1.removeStorageReclamation)(rootStore.path);
-            if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
-                rootStore.close();
-                rootStore.destroy();
+        if (detachedRootHasForeignHandle())
+            throw new hdbError_ts_1.DatabaseClosingError(databaseName);
+        for (const rootPath of detachedRootPaths)
+            await (0, promises_1.rm)(rootPath, { recursive: true, force: true });
+        await (0, blob_ts_1.deleteBlobPaths)(dropLocks.flatMap((lock) => lock.blobPaths));
+        while (dropLocks.length > 0)
+            (0, restoreMarker_ts_1.completeDatabaseDrop)(dropLocks.shift());
+        dropCompleted = true;
+    }
+    finally {
+        if (destructiveWorkStarted) {
+            for (const rootStore of rootStores)
+                blob_ts_1.databasePaths.delete(rootStore);
+            for (const rootStore of rootStores) {
+                if ((0, restoreMarker_ts_1.databaseDropMarkerPresent)(rootStore.path))
+                    incompleteDatabaseDropStores.set(rootStore.path, rootStore);
             }
-            else if (rootStore.status === 'open') {
-                await rootStore.close();
-                await (0, promises_1.unlink)(rootStore.path);
+            if (!dropCompleted) {
+                (0, DatabaseTransaction_ts_1.permanentlySuspendDatabaseCommits)(rootStores);
+                for (const rootStore of rootStores)
+                    (0, derivedIndexes_ts_1.permanentlySuspendDerivedIndexActivation)(rootStore);
             }
         }
-        await (0, blob_ts_1.deleteRootBlobPathsForDB)(rootStore);
-    }
-    finally {
-        for (const lock of restoreLocks)
-            (0, restoreMarker_ts_1.releaseRestoreLock)(lock);
+        releaseDerivedIndexActivation?.();
+        releaseDatabaseDropLocks(dropLocks, destructiveWorkStarted);
     }
 }
-/**
- * Close a database's store handles on the current thread and unregister it, without
- * touching its files. Used by the restore_backup flow: every thread must release its handles so
- * `backups.restore()` can purge and rewrite the (fully closed) database directory. A subsequent
- * `resetDatabases()`/`getDatabases()` rescan reloads it (or skips it while a restore is in
- * progress, per the restore marker checks in the scan).
- *
- * An LMDB database is closed by closing its environment, which releases every dbi in it, so every
- * other database alias sharing that environment is closed with it.
- */
-function closeDatabase(databaseName) {
-    const dbTables = exports.databases[databaseName];
-    if (!dbTables)
-        return false;
-    const rootStores = new Set();
-    const closeStore = (store, description) => {
+const databaseDropPreparationTasks = new Map();
+function addPhysicalDatabaseRoots(directory, rootPaths) {
+    if (!(0, node_fs_1.existsSync)(directory))
+        return;
+    for (const entry of (0, node_fs_1.readdirSync)(directory, { withFileTypes: true })) {
+        if (entry.name === restoreMarker_ts_1.RESTORE_META_DIR || entry.name === exports.BRANCH_ROOT_DIR || entry.name.endsWith(hdbTerms_ts_1.MIGRATING_DIR_SUFFIX))
+            continue;
+        const rootPath = (0, node_path_1.join)(directory, entry.name);
+        if (entry.isFile()) {
+            if ((0, node_path_1.extname)(entry.name).toLowerCase() === '.mdb')
+                rootPaths.add(rootPath);
+            continue;
+        }
+        if (!entry.isDirectory())
+            continue;
         try {
-            store?.close?.();
+            const files = (0, node_fs_1.readdirSync)(rootPath, { withFileTypes: true });
+            if (files.find((file) => file.name === 'CURRENT')?.isFile() &&
+                files.some((file) => file.name.startsWith('MANIFEST-')))
+                rootPaths.add(rootPath);
         }
         catch (error) {
-            logger.warn(`Error closing ${description} while closing database ${databaseName}:`, error);
+            if (!('code' in error && error.code === 'ENOENT'))
+                throw error;
+        }
+    }
+}
+function databaseDropRecoveryGraphPaths(databaseName, incompleteRootPaths) {
+    const rootPaths = new Set(incompleteRootPaths);
+    if (incompleteRootPaths.length === 0)
+        return [];
+    const databaseConfig = ((0, environmentManager_ts_1.get)(hdbTerms_ts_1.CONFIG_PARAMS.DATABASES) || {})[databaseName];
+    if (databaseConfig?.path)
+        addPhysicalDatabaseRoots(databaseConfig.path, rootPaths);
+    addPhysicalDatabaseRoots((0, node_path_1.join)((0, initializePaths_js_1.getBaseSchemaPath)(), databaseName), rootPaths);
+    for (const [tableName, tableConfig] of Object.entries(databaseConfig?.tables || {})) {
+        if (!tableConfig?.path)
+            continue;
+        for (const rootPath of [(0, node_path_1.join)(tableConfig.path, tableName), (0, node_path_1.join)(tableConfig.path, `${tableName}.mdb`)]) {
+            if ((0, node_fs_1.existsSync)(rootPath))
+                rootPaths.add(rootPath);
+        }
+    }
+    try {
+        const storageRoot = resolveDatabaseStorageRoot(databaseName);
+        for (const rootPath of [(0, node_path_1.join)(storageRoot, databaseName), (0, node_path_1.join)(storageRoot, `${databaseName}.mdb`)]) {
+            if ((0, node_fs_1.existsSync)(rootPath))
+                rootPaths.add(rootPath);
+        }
+    }
+    catch { }
+    return [...rootPaths];
+}
+function incompleteDatabaseDropPaths(databaseName) {
+    const directories = new Set();
+    try {
+        directories.add(resolveDatabaseStorageRoot(databaseName));
+    }
+    catch { }
+    directories.add((0, node_path_1.join)((0, initializePaths_js_1.getBaseSchemaPath)(), databaseName));
+    const databaseConfig = ((0, environmentManager_ts_1.get)(hdbTerms_ts_1.CONFIG_PARAMS.DATABASES) || {})[databaseName];
+    if (databaseConfig?.path)
+        directories.add(databaseConfig.path);
+    for (const tableConfig of Object.values(databaseConfig?.tables || {})) {
+        if (tableConfig?.path)
+            directories.add(tableConfig.path);
+    }
+    const rootPaths = new Set();
+    for (const directory of directories) {
+        for (const drop of (0, restoreMarker_ts_1.scanBlockedDatabaseDrops)(directory)) {
+            if (drop.databaseName === databaseName)
+                rootPaths.add(drop.rootPath);
         }
+    }
+    return [...rootPaths];
+}
+function databaseDropRecoveryPending(databaseName) {
+    return incompleteDatabaseDropPaths(databaseName).length > 0 || incompleteDatabaseClosePaths(databaseName).length > 0;
+}
+function databaseDropPreparationTargets(databaseName) {
+    getDatabases();
+    const incompleteRootPaths = [
+        ...new Set([...incompleteDatabaseDropPaths(databaseName), ...incompleteDatabaseClosePaths(databaseName)]),
+    ];
+    const recoveryRootPaths = databaseDropRecoveryGraphPaths(databaseName, incompleteRootPaths);
+    if (!exports.databases[databaseName]) {
+        if (recoveryRootPaths.length > 0)
+            return { rootPaths: recoveryRootPaths };
+        throw new Error(`Database '${databaseName}' does not exist`);
+    }
+    const graph = collectDatabaseGraph(databaseName);
+    if (graph.rootStores.size === 0)
+        graph.rootStores.add(openDatabaseRoot({ database: databaseName }));
+    return {
+        rootPaths: [...new Set([...recoveryRootPaths, ...[...graph.rootStores].map((rootStore) => rootStore.path)])],
     };
-    for (const tableName in dbTables) {
-        const table = dbTables[tableName];
-        if (!table?.primaryStore)
+}
+function prepareDatabaseDrop(databaseName, preparationId, ownerThreadId, requestedRootPaths = []) {
+    const existing = databaseDropPreparationTasks.get(databaseName);
+    if (existing?.id === preparationId)
+        return existing.task;
+    const rootPaths = new Set(requestedRootPaths);
+    if (exports.databases[databaseName]) {
+        const graph = collectDatabaseGraph(databaseName);
+        for (const rootStore of graph.rootStores)
+            rootPaths.add(rootStore.path);
+    }
+    const names = [];
+    for (const name of Object.keys(exports.databases)) {
+        const definedRoot = definedDatabases?.get(name)?.rootStore;
+        if (definedRoot && rootPaths.has(definedRoot.path)) {
+            names.push(name);
             continue;
-        if (table.primaryStore.rootStore)
-            rootStores.add(table.primaryStore.rootStore);
+        }
+        const tables = exports.databases[name];
+        if (Object.values(tables).some((table) => {
+            const rootStore = table?.primaryStore?.rootStore;
+            return rootStore && rootPaths.has(rootStore.path);
+        }))
+            names.push(name);
     }
-    // a database with no tables (an empty schema, or one whose tables were all dropped) still holds
-    // an open root store, tracked only on the defined-database entry rather than any table — include
-    // it so its handles are released too (the Set dedupes it against the per-table root stores above)
-    const definedRoot = definedDatabases?.get(databaseName)?.rootStore;
-    if (definedRoot)
-        rootStores.add(definedRoot);
-    // before any table store closes, so no further pass is admitted. This is synchronous, so it cannot
-    // await the drain barrier stopAuditCleanup() returns; what covers it is the in-pass status checks,
-    // plus the fact that its production callers reach it only for RocksDB databases, whose pass is one
-    // synchronous purgeLogs() call with nothing suspended mid-removal.
-    for (const rootStore of rootStores)
-        rootStore.auditStore?.stopAuditCleanup?.();
+    const paths = [...rootPaths];
+    (0, databaseDropPreparation_ts_1.claimDatabaseDropPreparations)(paths, preparationId, ownerThreadId, databaseName);
+    const task = (async () => {
+        const failures = [];
+        for (const rootPath of paths) {
+            try {
+                await retryIncompleteDatabaseClose(rootPath);
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        for (const name of names) {
+            try {
+                await closeDatabase(name, { requireClosed: true });
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        for (const rootPath of paths) {
+            if (!incompleteDatabaseDropStores.has(rootPath))
+                continue;
+            try {
+                await destroyIncompleteDatabaseRoot(rootPath);
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (failures.length > 0)
+            throw new AggregateError(failures, `Could not prepare database '${databaseName}' for drop`);
+    })();
+    databaseDropPreparationTasks.set(databaseName, { id: preparationId, task, rootPaths: paths });
+    for (const rootPath of paths)
+        (0, databaseDropPreparation_ts_1.trackDatabaseDropPreparationTask)(rootPath, preparationId, task);
+    return task;
+}
+async function completeDatabaseDropPreparation(databaseName, preparationId, requestedRootPaths = []) {
+    const existing = databaseDropPreparationTasks.get(databaseName);
+    if (existing?.id === preparationId) {
+        try {
+            await existing.task;
+        }
+        catch {
+            // Preparation already reported this failure to the strict broadcaster.
+        }
+        databaseDropPreparationTasks.delete(databaseName);
+    }
+    (0, databaseDropPreparation_ts_1.releaseDatabaseDropPreparations)(existing?.rootPaths ?? requestedRootPaths, preparationId);
+}
+async function closeDatabaseStores(databaseName, dbTables, rootStores, requireClosed) {
+    const rootStorePaths = [];
+    const closeFailures = [];
+    const closeStore = async (store, description) => {
+        if (!store || store.status === 'closed')
+            return true;
+        try {
+            await store.close?.();
+            return true;
+        }
+        catch (error) {
+            logger.warn(`Error closing ${description} while closing database ${databaseName}:`, error);
+            closeFailures.push(error);
+            return false;
+        }
+    };
     const lmdbRootStores = new Set([...rootStores].filter((rootStore) => !(rootStore instanceof rocksdb_js_1.RocksDatabase)));
     for (const tableName in dbTables) {
         const table = dbTables[tableName];
-        // a dbi closed natively after its environment closed (through another alias sharing it) runs
-        // mdb_dbi_close against the freed environment
         if (!table?.primaryStore || lmdbRootStores.has(table.primaryStore.rootStore))
             continue;
+        const tableIdentity = `${table.databaseName ?? databaseName}.${table.tableName ?? tableName}`;
         for (const indexName in table.indices || {}) {
-            closeStore(table.indices[indexName], `index ${tableName}.${indexName}`);
+            await closeStore(table.indices[indexName], `index ${tableIdentity}.${indexName}`);
         }
-        closeStore(table.primaryStore, `table ${tableName}`);
+        await closeStore(table.primaryStore, `table ${tableIdentity}`);
     }
     for (const rootStore of rootStores) {
         (0, storageReclamation_ts_1.removeStorageReclamation)(rootStore.path);
+        blob_ts_1.databasePaths.delete(rootStore);
+        let rootClosed = rootStore.status !== 'open';
         if (!lmdbRootStores.has(rootStore)) {
-            closeStore(rootStore.dbisDb, 'attributes store');
-            closeStore(rootStore, 'root store');
-        }
-        else if (rootStore.status === 'open')
-            closeStore(rootStore, 'root store');
-        lmdbDatabaseEnvs.delete(rootStore.path);
-        rocksdbDatabaseEnvs.delete(rootStore.path);
-    }
-    unregisterDatabase(databaseName);
-    for (const aliasName of Object.keys(exports.databases)) {
-        for (const rootStore of lmdbRootStores) {
-            if (databaseUsesRootStore(aliasName, rootStore)) {
-                closeDatabase(aliasName);
+            await closeStore(rootStore.dbisDb, 'attributes store');
+            rootClosed = await closeStore(rootStore, 'root store');
+        }
+        else if (!rootClosed)
+            rootClosed = await closeStore(rootStore, 'root store');
+        if (rootClosed || !requireClosed)
+            rootStorePaths.push(rootStore.path);
+    }
+    for (const path of rootStorePaths) {
+        lmdbDatabaseEnvs.delete(path);
+        rocksdbDatabaseEnvs.delete(path);
+    }
+    return closeFailures;
+}
+/**
+ * Close a database's store handles on this thread and unregister every alias sharing those roots,
+ * without touching files. Restore uses this before rewriting the closed directory. With
+ * `requireClosed`, any handle failure rejects and leaves the affected wrappers permanently fenced
+ * for an explicit retry. Closing an LMDB environment closes every DBI and alias that shares it.
+ */
+async function closeDatabase(databaseName, { requireClosed = false } = {}) {
+    if (!exports.databases[databaseName])
+        return false;
+    const { databaseNames, dbTables, rootStores } = collectDatabaseGraph(databaseName);
+    const releaseDerivedIndexActivation = await settleDatabaseDerivedIndexes(dbTables, false, rootStores);
+    let databaseClosed = false;
+    let handleCloseStarted = false;
+    try {
+        await Promise.all([...rootStores].map((rootStore) => rootStore.auditStore?.stopAuditCleanup?.()));
+        handleCloseStarted = true;
+        const closeFailures = await closeDatabaseStores(databaseName, dbTables, rootStores, requireClosed);
+        if (requireClosed && closeFailures.length > 0) {
+            for (const rootStore of rootStores) {
+                lmdbDatabaseEnvs.delete(rootStore.path);
+                rocksdbDatabaseEnvs.delete(rootStore.path);
+            }
+            for (const name of databaseNames)
+                unregisterDatabase(name);
+            rememberIncompleteDatabaseClose(databaseNames, [...rootStores].map((rootStore) => rootStore.path), async () => {
+                const retryFailures = await closeDatabaseStores(databaseName, dbTables, rootStores, true);
+                if (retryFailures.length > 0)
+                    throw new AggregateError(retryFailures, `Could not finish closing database graph '${databaseName}'`);
+            });
+            throw new AggregateError(closeFailures, `Could not close database graph '${[...databaseNames].join("', '")}' for destructive DDL`);
+        }
+        for (const name of databaseNames)
+            unregisterDatabase(name);
+        databaseClosed = true;
+        return true;
+    }
+    finally {
+        if (handleCloseStarted && !databaseClosed) {
+            (0, DatabaseTransaction_ts_1.permanentlySuspendDatabaseCommits)(rootStores);
+            for (const rootStore of rootStores)
+                (0, derivedIndexes_ts_1.permanentlySuspendDerivedIndexActivation)(rootStore);
+        }
+        else if (!databaseClosed && !handleCloseStarted) {
+            resumeTableMaintenance(dbTables);
+            for (const table of Object.values(dbTables))
+                (0, derivedIndexes_ts_1.refreshDerivedIndexes)(table);
+        }
+        releaseDerivedIndexActivation();
+    }
+}
+function collectDatabaseGraph(databaseName) {
+    const databaseNames = new Set([databaseName]);
+    const processedNames = new Set();
+    const rootStores = new Set();
+    const tableSet = new Set();
+    for (;;) {
+        for (const name of databaseNames) {
+            if (processedNames.has(name))
+                continue;
+            processedNames.add(name);
+            const tables = exports.databases[name];
+            for (const tableName in tables) {
+                const table = tables[tableName];
+                tableSet.add(table);
+                if (table?.primaryStore?.rootStore)
+                    rootStores.add(table.primaryStore.rootStore);
+            }
+            const definedRoot = definedDatabases?.get(name)?.rootStore;
+            if (definedRoot)
+                rootStores.add(definedRoot);
+        }
+        let foundAlias = false;
+        for (const aliasName of Object.keys(exports.databases)) {
+            if (databaseNames.has(aliasName))
+                continue;
+            for (const rootStore of rootStores) {
+                if (!databaseUsesRootStore(aliasName, rootStore))
+                    continue;
+                databaseNames.add(aliasName);
+                foundAlias = true;
                 break;
             }
         }
+        if (!foundAlias)
+            break;
     }
-    return true;
+    return {
+        databaseNames,
+        dbTables: Object.fromEntries([...tableSet].map((table, index) => [index, table])),
+        rootStores,
+    };
 }
 function databaseUsesRootStore(databaseName, rootStore) {
     if (definedDatabases?.get(databaseName)?.rootStore === rootStore)
         return true;
     const dbTables = exports.databases[databaseName];
+    if (!dbTables)
+        return false;
     for (const tableName in dbTables) {
         if (dbTables[tableName]?.primaryStore?.rootStore === rootStore)
             return true;
     }
     return false;
 }
+function databaseUsesPreparedRoot(databaseName) {
+    const definedRoot = definedDatabases?.get(databaseName)?.rootStore;
+    if (definedRoot && (0, databaseDropPreparation_ts_1.databaseDropPrepared)(definedRoot.path))
+        return true;
+    const dbTables = exports.databases[databaseName];
+    for (const tableName in dbTables) {
+        const rootStore = dbTables[tableName]?.primaryStore?.rootStore;
+        if (rootStore && (0, databaseDropPreparation_ts_1.databaseDropPrepared)(rootStore.path))
+            return true;
+    }
+    return false;
+}
 function unregisterDatabase(databaseName) {
     const definedDatabase = definedDatabases?.get(databaseName);
     if (definedDatabase)
@@ -2092,43 +2709,115 @@ function unregisterDatabase(databaseName) {
     delete exports.databases[databaseName];
 }
 /**
- * Close every RocksDB (user) database this thread has open, releasing its native handles.
+ * Close every user database this thread has open, releasing its native handles.
  *
- * rocksdb-js's registry is process-global across worker threads, and a thread that exits WITHOUT
- * closing leaks its handles (the process-global refCount never drops), while the only alternative,
- * `shutdown()`, tears down rocksdb for the entire process. So a worker thread that opens databases
- * and then exits — notably a job worker (jobProcess), which opens the whole database graph via
- * `getDatabases()` and exits when the job finishes — must close its handles explicitly, or those
- * handles linger process-wide (and, e.g., block an online `restore_backup` from confirming the
- * database is closed). The `system` database is intentionally left open: it is non-enumerable here
+ * A job worker opens the database graph and must prove every handle is closed before its exit can
+ * satisfy destructive-DDL preparation. RocksDB handles otherwise leak in the process-global
+ * registry; an open LMDB handle can likewise prevent deletion on Windows. The `system` database is
+ * intentionally left open: it is non-enumerable here
  * (skipped by the loop), is never restored online, and the exiting worker may still touch the job
  * table during teardown. Best-effort: closing failures are swallowed inside `closeDatabase`.
  *
  * Branches are invisible to the loop below but hold handles from the same registry, so this — the
  * thread's one teardown entry point — closes them too.
  */
-function closeLoadedDatabases() {
-    closeBranchDatabases();
+async function closeLoadedDatabases({ requireClosed = false } = {}) {
+    const closeFailures = [];
+    try {
+        await closeBranchDatabases(requireClosed);
+    }
+    catch (error) {
+        closeFailures.push(error);
+    }
     // snapshot the names first: closeDatabase() deletes from `databases` as it goes
     for (const databaseName of Object.keys(exports.databases)) {
         const dbTables = exports.databases[databaseName];
         if (!dbTables)
             continue;
-        let isRocks = false;
-        for (const tableName in dbTables) {
-            if (dbTables[tableName]?.primaryStore?.rootStore instanceof rocksdb_js_1.RocksDatabase) {
-                isRocks = true;
-                break;
-            }
+        try {
+            await closeDatabase(databaseName, { requireClosed });
         }
-        // a tableless database exposes no table root store, so also check the defined-database
-        // entry — otherwise its open root store would leak on worker exit
-        if (!isRocks && definedDatabases?.get(databaseName)?.rootStore instanceof rocksdb_js_1.RocksDatabase) {
-            isRocks = true;
+        catch (error) {
+            logger.warn(`Error closing database ${databaseName} during worker teardown`, error);
+            closeFailures.push(error);
         }
-        if (isRocks)
-            closeDatabase(databaseName);
     }
+    if (requireClosed && closeFailures.length > 0)
+        throw new AggregateError(closeFailures, 'Could not close every database during worker teardown');
+}
+async function settleTableMaintenance(dbTables, deadline) {
+    await Promise.all(Object.values(dbTables).map((table) => table?.closeMaintenance?.(deadline)));
+}
+function resumeTableMaintenance(dbTables) {
+    for (const table of Object.values(dbTables))
+        table?.resumeMaintenance?.();
+}
+async function settleDatabaseDerivedIndexes(dbTables, dropping, additionalRootStores = []) {
+    const rootStores = new Set(additionalRootStores);
+    for (const tableName in dbTables) {
+        const rootStore = dbTables[tableName]?.primaryStore?.rootStore;
+        if (rootStore)
+            rootStores.add(rootStore);
+    }
+    const activationReleases = [...rootStores].map(derivedIndexes_ts_1.suspendDerivedIndexActivation);
+    const commitSuspension = (0, DatabaseTransaction_ts_1.suspendDatabaseCommits)(rootStores);
+    const deadline = Date.now() + (0, DatabaseTransaction_ts_1.getDatabaseCommitDrainTimeoutMilliseconds)();
+    const databaseName = [...rootStores][0]?.databaseName ?? 'unknown';
+    let lifecycleReleased = false;
+    const releaseLifecycle = () => {
+        if (lifecycleReleased)
+            return;
+        lifecycleReleased = true;
+        commitSuspension.release();
+        for (const release of activationReleases)
+            release();
+    };
+    const attachments = new Map();
+    for (const tableName in dbTables) {
+        const table = dbTables[tableName];
+        const attachment = table?.derivedIndexRuntime;
+        if (!attachment)
+            continue;
+        let tables = attachments.get(attachment);
+        if (!tables)
+            attachments.set(attachment, (tables = []));
+        tables.push(table);
+    }
+    const entries = [...attachments];
+    try {
+        await commitSuspension.waitForDrain({ deadline, databaseName });
+        await settleInterruptedDropRetirements(rootStores);
+        await settleTableMaintenance(dbTables, deadline);
+        if (attachments.size === 0)
+            return releaseLifecycle;
+        const results = await Promise.allSettled(entries.map(async ([attachment]) => attachment.close(dropping)));
+        const failures = results
+            .filter((result) => result.status === 'rejected')
+            .map((result) => result.reason);
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length)
+            throw new AggregateError(failures, 'Could not settle derived indexes before closing the database');
+    }
+    catch (error) {
+        resumeTableMaintenance(dbTables);
+        releaseLifecycle();
+        for (const [attachment, tables] of entries) {
+            if (dropping)
+                attachment.completeDrop?.(false);
+            for (const table of tables)
+                (0, derivedIndexes_ts_1.refreshDerivedIndexes)(table);
+        }
+        throw error;
+    }
+    for (const [attachment, tables] of entries) {
+        if (dropping)
+            attachment.completeDrop?.();
+        for (const table of tables)
+            if (table.derivedIndexRuntime === attachment)
+                table.derivedIndexRuntime = undefined;
+    }
+    return releaseLifecycle;
 }
 // HNSW_NO_AUTOVERSION kill-switch: when set, a NEW index initializes as legacy rather than
 // versioned. process.env values are strings, so a bare truthiness check would treat "0"/"false"
@@ -2557,6 +3246,8 @@ function declareTable(target, tableDefinition) {
     let fullTextValuesForPersistence;
     let fullTextPersistencePending = false;
     let activeFullTextIndexes;
+    let fullTextIndexGenerationMap = Object.create(null);
+    let fullTextIndexRetirementNames;
     let restoreFullTextLiveState;
     let armFullTextLiveStateRestore;
     const attributesToIndex = [];
@@ -2600,7 +3291,9 @@ function declareTable(target, tableDefinition) {
             let persistedPrimary = persistedPrimaryDescriptor(Table.dbisDB);
             let persistedFullTextValues = persistedPrimary.descriptor?.fullTextIndexes;
             const incomingFullTextValues = fullTextIndexesExplicit ? fullTextIndexes : [];
+            let fullTextValidationAttributes;
             if ((persistedFullTextValues !== undefined && (rootStore instanceof rocksdb_js_1.RocksDatabase || fullTextIndexesExplicit)) ||
+                persistedPrimary.descriptor?.fullTextIndexRetirements !== undefined ||
                 Table.fullTextIndexes?.length > 0 ||
                 (fullTextIndexesExplicit && (!Array.isArray(incomingFullTextValues) || incomingFullTextValues.length > 0))) {
                 if (!(rootStore instanceof rocksdb_js_1.RocksDatabase)) {
@@ -2609,6 +3302,7 @@ function declareTable(target, tableDefinition) {
                     persistedFullTextValues = persistedPrimary.descriptor?.fullTextIndexes;
                 }
                 const originalAttributes = Table.attributes.slice();
+                fullTextIndexRetirementNames = (0, fullTextSchema_ts_1.persistedFullTextIndexNames)(persistedPrimary.descriptor?.fullTextIndexRetirements);
                 const relationshipAttributes = originalAttributes.filter((attribute) => attribute.relationship);
                 const originalMetadata = {
                     description: Table.description,
@@ -2629,14 +3323,15 @@ function declareTable(target, tableDefinition) {
                         Object.assign(Table, originalMetadata);
                         Table.properties = (0, jsonSchemaTypes_ts_1.projectAttributesToProperties)(restored);
                         const restoredPrimary = persistedPrimaryDescriptor(Table.dbisDB).descriptor;
-                        Table.fullTextIndexes =
-                            rootStore instanceof rocksdb_js_1.RocksDatabase && restoredPrimary?.audit === true
-                                ? (0, fullTextSchemaLifecycle_ts_1.readPersistedFullTextDefinitions)(restoredPrimary?.fullTextIndexes, restored, fullTextWarning)
-                                : [];
+                        const restoredFullTextIndexes = rootStore instanceof rocksdb_js_1.RocksDatabase && restoredPrimary?.audit === true
+                            ? (0, fullTextSchemaLifecycle_ts_1.readPersistedFullTextDefinitions)(restoredPrimary?.fullTextIndexes, restored, fullTextWarning)
+                            : [];
+                        Table.fullTextIndexes = restoredFullTextIndexes;
+                        Table.fullTextIndexGenerations = persistedFullTextIndexGenerations(restoredPrimary?.fullTextIndexGenerations, restoredFullTextIndexes);
+                        Table.fullTextIndexRetirements = (0, fullTextSchema_ts_1.persistedFullTextIndexNames)(restoredPrimary?.fullTextIndexRetirements);
                         Table.schemaVersion++;
                         Table.updatedAttributes();
-                        void Table.derivedIndexRuntime?.close();
-                        Table.derivedIndexRuntime = (0, hnswDerivedIndex_ts_1.attachDerivedIndexes)(Table);
+                        (0, derivedIndexes_ts_1.refreshDerivedIndexes)(Table);
                     };
                 };
                 const durableAttributes = catalogAttributes(Table.dbisDB);
@@ -2656,6 +3351,10 @@ function declareTable(target, tableDefinition) {
                             validationAttributes.unshift(durablePrimary);
                     }
                 }
+                fullTextValidationAttributes = validationAttributes;
+                // Before the full-text branches can write an interim descriptor; the check on the merged list
+                // below stays authoritative.
+                (0, embedHook_ts_1.assertDerivedFieldOwnership)(validationAttributes);
                 const persistedAudit = persistedPrimary.descriptor?.audit;
                 const durableAudit = persistedAudit === true;
                 const finalAudit = origin === 'cluster'
@@ -2683,25 +3382,59 @@ function declareTable(target, tableDefinition) {
                         throw new hdbError_ts_1.ClientError(`Table '${databaseName}.${tableName}' cannot use @fullText with the LMDB storage engine`, 400);
                     if (compiled.length > 0 && !finalAudit)
                         throw new hdbError_ts_1.ClientError(`Table '${databaseName}.${tableName}' must enable audit logging before using @fullText because its transaction log is the derived-index recovery source`, 400);
-                    const interim = (0, fullTextSchemaLifecycle_ts_1.safeInterimFullTextDefinitions)(persistedFullTextValues, validationAttributes, compiled);
                     const pinAudit = compiled.length > 0 && persistedPrimary.descriptor?.audit !== true;
-                    if (pinAudit || !(0, fullTextSchemaLifecycle_ts_1.definitionsEqual)(interim, persistedFullTextValues)) {
+                    const requestedNames = new Set(compiled.map(({ name }) => name));
+                    const durableDefinitions = (0, fullTextSchemaLifecycle_ts_1.readPersistedFullTextDefinitions)(persistedFullTextValues, durableAttributes, fullTextWarning);
+                    const removedNames = durableDefinitions.map(({ name }) => name).filter((name) => !requestedNames.has(name));
+                    const invalidatedNames = durableDefinitions
+                        .filter(({ name }) => requestedNames.has(name))
+                        .filter((definition) => {
+                        try {
+                            (0, fullTextSchema_ts_1.compileFullTextDefinitions)([definition], validationAttributes);
+                            return false;
+                        }
+                        catch (error) {
+                            if (error instanceof hdbError_ts_1.ClientError)
+                                return true;
+                            throw error;
+                        }
+                    })
+                        .map(({ name }) => name);
+                    const transitionRetirements = new Set([...removedNames, ...invalidatedNames]);
+                    if (pinAudit || transitionRetirements.size > 0) {
                         const interimPrimary = { ...persistedPrimary.descriptor };
                         if (pinAudit)
                             interimPrimary.audit = true;
-                        if (interim.length > 0)
-                            interimPrimary.fullTextIndexes = interim;
-                        else
-                            delete interimPrimary.fullTextIndexes;
+                        if (transitionRetirements.size > 0) {
+                            const interimDefinitions = durableDefinitions.filter(({ name }) => requestedNames.has(name));
+                            if (interimDefinitions.length > 0) {
+                                interimPrimary.fullTextIndexes = interimDefinitions;
+                                interimPrimary.fullTextIndexGenerations = persistedFullTextIndexGenerations(persistedPrimary.descriptor?.fullTextIndexGenerations, interimDefinitions);
+                            }
+                            else {
+                                delete interimPrimary.fullTextIndexes;
+                                delete interimPrimary.fullTextIndexGenerations;
+                            }
+                            const retirements = new Set((0, fullTextSchema_ts_1.persistedFullTextIndexNames)(persistedPrimary.descriptor?.fullTextIndexRetirements));
+                            for (const name of transitionRetirements)
+                                retirements.add(name);
+                            for (const name of requestedNames)
+                                if (!transitionRetirements.has(name))
+                                    retirements.delete(name);
+                            fullTextIndexRetirementNames = [...retirements].sort();
+                            if (fullTextIndexRetirementNames.length > 0)
+                                interimPrimary.fullTextIndexRetirements = fullTextIndexRetirementNames.map((name) => ({ name }));
+                            else
+                                delete interimPrimary.fullTextIndexRetirements;
+                        }
                         armFullTextLiveStateRestore?.();
                         Table.dbisDB.put(persistedPrimary.key, interimPrimary);
                         if (pinAudit && Table.audit !== true)
                             Table.enableAuditing();
-                        Table.fullTextIndexes = rootStore instanceof rocksdb_js_1.RocksDatabase && finalAudit ? interim : [];
                         hasChanges = true;
                     }
                     fullTextValuesForPersistence = compiled;
-                    fullTextPersistencePending = !(0, fullTextSchemaLifecycle_ts_1.definitionsEqual)(compiled, interim);
+                    fullTextPersistencePending = !(0, fullTextSchemaLifecycle_ts_1.definitionsEqual)(compiled, persistedFullTextValues);
                     activeFullTextIndexes = compiled;
                 }
                 else {
@@ -2712,6 +3445,16 @@ function declareTable(target, tableDefinition) {
                     activeFullTextIndexes = rootStore instanceof rocksdb_js_1.RocksDatabase && finalAudit ? retained : [];
                 }
             }
+            if (activeFullTextIndexes !== undefined) {
+                const durableGenerationDefinitions = (0, fullTextSchemaLifecycle_ts_1.readPersistedFullTextDefinitions)(persistedFullTextValues, fullTextValidationAttributes ?? Table.attributes, fullTextWarning);
+                const finalGenerationDefinitions = (0, fullTextSchemaLifecycle_ts_1.readPersistedFullTextDefinitions)(fullTextValuesForPersistence ?? persistedFullTextValues, fullTextValidationAttributes ?? Table.attributes, fullTextWarning);
+                fullTextIndexGenerationMap = (0, fullTextSchema_ts_1.reconcileFullTextIndexGenerations)(durableGenerationDefinitions, persistedPrimary.descriptor?.fullTextIndexGenerations, finalGenerationDefinitions, createFullTextIndexGeneration);
+                (0, derivedIndexes_ts_1.assertFullTextActivationSupported)(rootStore, databaseName, tableName, activeFullTextIndexes);
+                if (activeFullTextIndexes.length > 0 &&
+                    rootStore instanceof rocksdb_js_1.RocksDatabase &&
+                    (0, derivedIndexRegistry_ts_1.fullTextClearInProgress)(rootStore, Table.tableId))
+                    throw new hdbError_ts_1.ClientError(`Cannot activate @fullText on '${databaseName}.${tableName}' while Table.clear() is in progress`, 409);
+            }
             // it table already exists, get the split segments setting
             if (splitSegments == undefined)
                 splitSegments = Table.splitSegments;
@@ -2742,6 +3485,9 @@ function declareTable(target, tableDefinition) {
                 if (existingPrimary)
                     attributes = [existingPrimary, ...attributes];
             }
+            // On the complete list (a peer's fields merged, an omitted primary key inherited) and before
+            // it replaces the live one or reaches the catalog, so a refused declaration changes nothing.
+            (0, embedHook_ts_1.assertDerivedFieldOwnership)(attributes);
             armFullTextLiveStateRestore?.();
             Table.attributes.splice(0, Table.attributes.length, ...attributes);
             // Re-assert from the live declaration so a stale value on disk (replicated event,
@@ -2760,6 +3506,8 @@ function declareTable(target, tableDefinition) {
                 Table.cacheControl = cacheControl;
         }
         else {
+            if (Array.isArray(attributes))
+                (0, embedHook_ts_1.assertDerivedFieldOwnership)(attributes);
             if (fullTextIndexesExplicit) {
                 if (origin === 'cluster') {
                     const merged = (0, fullTextSchemaLifecycle_ts_1.mergePeerFullTextDefinitions)([], fullTextIndexes, attributes, fullTextWarning);
@@ -2789,8 +3537,12 @@ function declareTable(target, tableDefinition) {
             // 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)
+            if (Array.isArray(fullTextValuesForPersistence) && fullTextValuesForPersistence.length > 0) {
+                const durableFullTextIndexes = (0, fullTextSchemaLifecycle_ts_1.readPersistedFullTextDefinitions)(fullTextValuesForPersistence, attributes, fullTextWarning);
+                fullTextIndexGenerationMap = (0, fullTextSchema_ts_1.reconcileFullTextIndexGenerations)([], undefined, durableFullTextIndexes, createFullTextIndexGeneration);
                 primaryKeyAttribute.fullTextIndexes = fullTextValuesForPersistence;
+                primaryKeyAttribute.fullTextIndexGenerations = fullTextIndexGenerationMap;
+            }
             // can't change compression after the fact (except threshold), so save only when we create the table
             primaryKeyAttribute.compression = getDefaultCompression();
             if (trackDeletes)
@@ -2849,6 +3601,8 @@ function declareTable(target, tableDefinition) {
             target.adopt(attributesDbi);
             markInternalDbiNonVersioned(attributesDbi);
             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 (rootStore instanceof rocksdb_js_1.RocksDatabase && (0, derivedIndexRegistry_ts_1.fullTextRetirementInProgress)(rootStore, tableName))
+                throw new hdbError_ts_1.ClientError(`Cannot create '${databaseName}.${tableName}' while its previous full-text storage is being retired`, 409);
             const existingTableMeta = attributesDbi.getSync(dbiName);
             if (existingTableMeta && !existingTableMeta.dropping) {
                 // table was created while we were setting up; the lock is not reentrant, so release
@@ -2864,7 +3618,8 @@ function declareTable(target, tableDefinition) {
                 // create below starts from a clean slate; treating the tombstoned
                 // entry as an existing table would recurse forever on the stale
                 // catalog row.
-                completeInterruptedDrop(rootStore, attributesDbi, databaseName, tableName);
+                if (!completeInterruptedDrop(rootStore, attributesDbi, databaseName, tableName))
+                    throw new hdbError_ts_1.ClientError(`Cannot create '${databaseName}.${tableName}' while its interrupted full-text drop is being retired`, 409);
                 // This resolves the drop without ever going through the schema-load
                 // reconcile below, which is the only other place that returns a spent
                 // budget. Without clearing it here too, a table that gets dropped again
@@ -2921,6 +3676,8 @@ function declareTable(target, tableDefinition) {
                 indices: {},
                 attributes,
                 fullTextIndexes: activeFullTextIndexes ?? [],
+                fullTextIndexGenerations: fullTextIndexGenerationMap,
+                fullTextIndexRetirements: fullTextIndexRetirementNames ?? [],
                 schemaDefined,
                 dbisDB: attributesDbi,
                 description,
@@ -3176,8 +3933,12 @@ function declareTable(target, tableDefinition) {
                 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);
+            // any metadata difference (drives persistence). `decide` is compared here and not in
+            // `commonChanged`: a changed directive refreshes the decide registry, and a stored decision
+            // does not depend on the model, so an indexed decision attribute must not rebuild its index.
+            const changed = commonChanged ||
+                JSON.stringify(attributeDescriptor?.indexed) !== JSON.stringify(attribute.indexed) ||
+                JSON.stringify(attributeDescriptor?.decide) !== JSON.stringify(attribute.decide);
             // structure-affecting difference (drives reindex) — ignores search-only option changes and
             // representation-only differences (key order, string-vs-number) via canonicalIndexKey
             const indexOptionsStructurallyChanged = canonicalIndexKey(attributeDescriptor?.indexed) !== canonicalIndexKey(attribute.indexed);
@@ -3337,15 +4098,39 @@ function declareTable(target, tableDefinition) {
                 attributesDbi.put(dbiKey, attribute);
             }
         }
-        if (fullTextPersistencePending && !deferredPrimaryRow) {
+        if (!deferredPrimaryRow &&
+            (fullTextPersistencePending ||
+                (rootStore instanceof rocksdb_js_1.RocksDatabase &&
+                    activeFullTextIndexes !== undefined &&
+                    Array.isArray(fullTextValuesForPersistence)))) {
             const { key, descriptor } = persistedPrimaryDescriptor(attributesDbi);
             if (descriptor && !tableIsDropping(descriptor, key)) {
                 const updatedPrimary = { ...descriptor };
-                if (Array.isArray(fullTextValuesForPersistence) && fullTextValuesForPersistence.length > 0)
+                if (Array.isArray(fullTextValuesForPersistence) && fullTextValuesForPersistence.length > 0) {
                     updatedPrimary.fullTextIndexes = fullTextValuesForPersistence;
-                else
+                    updatedPrimary.fullTextIndexGenerations = fullTextIndexGenerationMap;
+                }
+                else {
                     delete updatedPrimary.fullTextIndexes;
-                if (!(0, fullTextSchemaLifecycle_ts_1.definitionsEqual)(descriptor.fullTextIndexes, updatedPrimary.fullTextIndexes)) {
+                    delete updatedPrimary.fullTextIndexGenerations;
+                }
+                const activeNames = new Set((0, fullTextSchema_ts_1.persistedFullTextIndexNames)(updatedPrimary.fullTextIndexes));
+                const retirements = new Set((0, fullTextSchema_ts_1.persistedFullTextIndexNames)(descriptor.fullTextIndexRetirements));
+                for (const name of (0, fullTextSchema_ts_1.persistedFullTextIndexNames)(descriptor.fullTextIndexes))
+                    if (!activeNames.has(name))
+                        retirements.add(name);
+                for (const name of activeNames)
+                    retirements.delete(name);
+                fullTextIndexRetirementNames = [...retirements].sort();
+                if (fullTextIndexRetirementNames.length > 0)
+                    updatedPrimary.fullTextIndexRetirements = fullTextIndexRetirementNames.map((name) => ({ name }));
+                else
+                    delete updatedPrimary.fullTextIndexRetirements;
+                if (!(0, fullTextSchemaLifecycle_ts_1.definitionsEqual)(descriptor.fullTextIndexes, updatedPrimary.fullTextIndexes) ||
+                    JSON.stringify(descriptor.fullTextIndexGenerations ?? {}) !==
+                        JSON.stringify(updatedPrimary.fullTextIndexGenerations ?? {}) ||
+                    JSON.stringify(descriptor.fullTextIndexRetirements ?? []) !==
+                        JSON.stringify(updatedPrimary.fullTextIndexRetirements ?? [])) {
                     exclusiveLock();
                     attributesDbi.put(key, updatedPrimary);
                     hasChanges = true;
@@ -3414,8 +4199,11 @@ function declareTable(target, tableDefinition) {
     finally {
         releaseLock();
     }
-    if (activeFullTextIndexes !== undefined)
+    if (activeFullTextIndexes !== undefined) {
         Table.fullTextIndexes = activeFullTextIndexes;
+        Table.fullTextIndexGenerations = fullTextIndexGenerationMap;
+        Table.fullTextIndexRetirements = fullTextIndexRetirementNames ?? [];
+    }
     if (hasChanges || refreshRelationshipAttributes)
         Table.schemaVersion++;
     if (hasChanges || refreshRelationshipAttributes || refreshedLiveAttributes)
@@ -3430,8 +4218,7 @@ function declareTable(target, tableDefinition) {
     }
     else if (hasChanges)
         signalling.signalSchemaChange(new itc_js_1.SchemaEventMsg(process.pid, 'schema-change', Table.databaseName, Table.tableName, undefined, branchPath));
-    void Table.derivedIndexRuntime?.close();
-    Table.derivedIndexRuntime = (0, hnswDerivedIndex_ts_1.attachDerivedIndexes)(Table);
+    (0, derivedIndexes_ts_1.refreshDerivedIndexes)(Table);
     Table.origin = origin;
     // scope-private: replication and other global subscribers must not learn of a branch class
     if ((hasChanges || refreshRelationshipAttributes) && !target.branch) {
@@ -4273,13 +5060,61 @@ function scheduleGenerationReclaim(rootStore, attributesDbi, databaseName) {
     state.timer.unref?.();
     state.delay = Math.min(state.delay * 2, 60_000);
 }
+const interruptedDropRetirements = new WeakMap();
+function trackInterruptedDropRetirement(rootStore, task) {
+    let tasks = interruptedDropRetirements.get(rootStore);
+    if (!tasks)
+        interruptedDropRetirements.set(rootStore, (tasks = new Set()));
+    tasks.add(task);
+    const remove = () => {
+        tasks.delete(task);
+    };
+    task.then(remove, remove);
+}
+async function settleInterruptedDropRetirements(rootStores) {
+    for (;;) {
+        const tasks = [...rootStores].flatMap((rootStore) => [...(interruptedDropRetirements.get(rootStore) ?? [])]);
+        if (tasks.length === 0)
+            return;
+        await Promise.allSettled(tasks);
+    }
+}
 /** Finishes the durable logical state of a drop that stopped after writing its tombstone. */
-function completeInterruptedDrop(rootStore, attributesDbi, databaseName, tableName) {
+function completeInterruptedDrop(rootStore, attributesDbi, databaseName, tableName, fullTextRetired = false) {
     logger.debug(`Completing interrupted drop of table ${databaseName}.${tableName}`);
     const catalogRows = [...attributesDbi.getRange({ start: tableName + '/', end: tableName + '0' })];
     const bareEntry = catalogRows.find(({ key }) => key === tableName + '/');
     const primaryEntry = (bareEntry?.value?.isPrimaryKey ? bareEntry : undefined) ?? catalogRows.find(({ value }) => value?.isPrimaryKey);
     const tombstoneEntry = bareEntry ?? primaryEntry;
+    if (rootStore instanceof rocksdb_js_1.RocksDatabase && !fullTextRetired) {
+        const names = [
+            ...new Set([
+                ...(0, fullTextSchema_ts_1.persistedFullTextIndexNames)(primaryEntry?.value?.fullTextIndexes),
+                ...(0, fullTextSchema_ts_1.persistedFullTextIndexNames)(primaryEntry?.value?.fullTextIndexRetirements),
+            ]),
+        ];
+        if (names.length > 0) {
+            const releaseRetirement = (0, derivedIndexRegistry_ts_1.acquireFullTextRetirementFence)(rootStore, tableName);
+            if (releaseRetirement) {
+                const retirement = (async () => {
+                    try {
+                        const retired = await (0, derivedIndexes_ts_1.retireFullTextIndexes)({ databaseName, tableName, primaryStore: { rootStore } }, names.map((name) => ({ name })), () => rootStore.status === 'open' && !(0, DatabaseTransaction_ts_1.databaseCommitsSuspended)(rootStore));
+                        if (!retired || rootStore.status === 'closed' || (0, DatabaseTransaction_ts_1.databaseCommitsSuspended)(rootStore))
+                            return;
+                        await (0, Table_ts_1.withUpdateAttributesLockNonBlocking)(rootStore, `complete interrupted drop of '${databaseName}.${tableName}'`, () => completeInterruptedDrop(rootStore, attributesDbi, databaseName, tableName, true));
+                    }
+                    catch (error) {
+                        logger.warn(`Could not retire full-text storage for interrupted drop ${databaseName}.${tableName}`, error);
+                    }
+                    finally {
+                        releaseRetirement();
+                    }
+                })();
+                trackInterruptedDropRetirement(rootStore, retirement);
+            }
+            return false;
+        }
+    }
     if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
         const tombstone = tombstoneEntry?.value;
         const generation = tombstone?.generation ?? primaryEntry?.value?.generation;
@@ -4327,6 +5162,7 @@ function completeInterruptedDrop(rootStore, attributesDbi, databaseName, tableNa
     }
     if (tombstoneEntry)
         attributesDbi.removeSync(tombstoneEntry.key);
+    return true;
 }
 function dropTableMeta({ table: tableName, database: databaseName }) {
     const rootStore = database({ database: databaseName, table: tableName });