@harperfast/harper 5.2.10 → 5.3.0-alpha.1

package/dist/resources/databases.js

@@ -36,14 +36,24 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ABANDONED_MARK_LOCK_TIMEOUT = exports.databases = exports.tables = exports.databaseEventsEmitter = exports.NON_REPLICATING_SYSTEM_TABLES = void 0;
+exports.BRANCH_REMOVING_SUFFIX = exports.BRANCH_ROOT_DIR = exports.databases = exports.tables = exports.databaseEventsEmitter = exports.NON_REPLICATING_SYSTEM_TABLES = void 0;
 exports.isReadOnlyMode = isReadOnlyMode;
 exports.getRocksCompression = getRocksCompression;
 exports.resetRocksCompression = resetRocksCompression;
 exports.toRocksCompression = toRocksCompression;
 exports.getTables = getTables;
 exports.getDatabases = getDatabases;
+exports.hydrateBranchRelationships = hydrateBranchRelationships;
 exports.readMetaDb = readMetaDb;
+exports.resolveBranchPath = resolveBranchPath;
+exports.quarantineBranchIdentity = quarantineBranchIdentity;
+exports.assertBranchIdentityAvailable = assertBranchIdentityAvailable;
+exports.reserveBranchIdentity = reserveBranchIdentity;
+exports.retakeBranchIdentity = retakeBranchIdentity;
+exports.releaseBranchIdentity = releaseBranchIdentity;
+exports.isBranchIdentity = isBranchIdentity;
+exports.openBranchDatabase = openBranchDatabase;
+exports.closeBranchDatabases = closeBranchDatabases;
 exports.resetDatabases = resetDatabases;
 exports.resolveDatabaseStorageRoot = resolveDatabaseStorageRoot;
 exports.resolveDatabasePath = resolveDatabasePath;
@@ -52,10 +62,9 @@ exports.dropDatabase = dropDatabase;
 exports.closeDatabase = closeDatabase;
 exports.closeLoadedDatabases = closeLoadedDatabases;
 exports.table = table;
+exports.scopedTableFactory = scopedTableFactory;
+exports.reloadBranchAt = reloadBranchAt;
 exports.canonicalizeIndexOptions = canonicalizeIndexOptions;
-exports.setIndexingCheckpointPeriod = setIndexingCheckpointPeriod;
-exports.resumeStartKey = resumeStartKey;
-exports.tryAcquireUpdateAttributesLock = tryAcquireUpdateAttributesLock;
 exports.dropTableMeta = dropTableMeta;
 exports.onUpdatedTable = onUpdatedTable;
 exports.onRemovedTable = onRemovedTable;
@@ -63,7 +72,6 @@ exports.onRemovedDB = onRemovedDB;
 exports.getDefaultCompression = getDefaultCompression;
 exports.flushDatabases = flushDatabases;
 const node_events_1 = require("node:events");
-const node_crypto_1 = require("node:crypto");
 const environmentManager_ts_1 = require("../utility/environment/environmentManager.js");
 const terms_ts_1 = require("../utility/lmdb/terms.js");
 const lmdb_1 = require("lmdb");
@@ -85,9 +93,10 @@ const harper_logger_ts_1 = __importDefault(require("../utility/logging/harper_lo
 const { forComponent } = harper_logger_ts_1.default;
 const manageThreads = __importStar(require("../server/threads/manageThreads.js"));
 const auditStore_ts_1 = require("./auditStore.js");
-const storageReclamation_ts_1 = require("../server/storageReclamation.js");
 const RecordEncoder_ts_1 = require("./RecordEncoder.js");
 const blob_ts_1 = require("./blob.js");
+const storageReclamation_ts_1 = require("../server/storageReclamation.js");
+const common_validators_ts_1 = require("../validation/common_validators.js");
 const customIndexes_ts_1 = require("./indexes/customIndexes.js");
 const OpenDBIObject_ts_1 = require("../utility/lmdb/OpenDBIObject.js");
 const rocksdb_js_1 = require("@harperfast/rocksdb-js");
@@ -144,8 +153,60 @@ function markInternalDbiNonVersioned(dbisDb) {
 const logger = forComponent('storage');
 const DEFAULT_DATABASE_NAME = 'data';
 const DEFINED_TABLES = Symbol('defined-tables');
+const CATALOG_RELATIONSHIP = Symbol('catalog-relationship');
 const DEFAULT_COMPRESSION_THRESHOLD = ((0, environmentManager_ts_1.get)(hdbTerms_ts_1.CONFIG_PARAMS.STORAGE_PAGESIZE) || 4096) - 60; // larger than this requires multiple pages
 (0, environmentManager_ts_1.initSync)();
+let relationshipsToHydrate = [];
+const reportedRelationshipErrors = new Set();
+// an interrupted create is reported once per table and thread, not on every rescan
+const reportedIncompleteCatalogs = new Set();
+function normalizeRelationships(attributes) {
+    const relationships = [];
+    for (const attribute of attributes) {
+        const target = attribute.relationshipReference;
+        if (!attribute.relationship || !target)
+            continue;
+        const relationship = {};
+        if (typeof attribute.relationship.from === 'string')
+            relationship.from = attribute.relationship.from;
+        if (typeof attribute.relationship.to === 'string')
+            relationship.to = attribute.relationship.to;
+        // the GraphQL parser hands every directive argument over as a string, and the resolver reads
+        // filterMissing for truthiness, so persist what the resolver would see rather than the literal
+        if (attribute.relationship.filterMissing !== undefined)
+            relationship.filterMissing = Boolean(attribute.relationship.filterMissing);
+        if (!relationship.from && !relationship.to)
+            continue;
+        const definition = {
+            name: attribute.name,
+            type: attribute.type,
+            relationship,
+            target: { database: target.database, table: target.table },
+        };
+        if (attribute.type === 'array')
+            definition.elements = { type: attribute.elements?.type };
+        relationships.push(definition);
+    }
+    return relationships;
+}
+function relationshipEquals(left, right) {
+    return (left?.name === right?.name &&
+        left?.type === right?.type &&
+        left?.elements?.type === right?.elements?.type &&
+        left?.relationship?.from === right?.relationship?.from &&
+        left?.relationship?.to === right?.relationship?.to &&
+        left?.relationship?.filterMissing === right?.relationship?.filterMissing &&
+        left?.target?.database === right?.target?.database &&
+        left?.target?.table === right?.target?.table);
+}
+function relationshipListsEqual(left, right) {
+    if (!Array.isArray(left) || left.length !== right.length)
+        return false;
+    for (let index = 0; index < right.length; index++)
+        if (!relationshipEquals(left[index], right[index]))
+            return false;
+    return true;
+}
 /**
  * The RocksDB block/blob codec for every column family this process opens (`storage.rocks.compression`),
  * or `undefined` to leave rocksdb-js on its own default (lz4 wherever the native build has it).
@@ -312,9 +373,12 @@ function openRocksDatabase(path, options) {
     else {
         db = new PrimaryRocksDatabase_ts_1.PrimaryRocksDatabase(path, options).open();
         // the RocksDB put and remove return promises, which masks thrown errors in non-awaiting calls to put/remove,
-        // making them unsafe to replace LMDB methods, which will synchronously throw errors if there is a problem
+        // making them unsafe to replace LMDB methods, which will synchronously throw errors if there is a problem.
+        // The versioned remove is necessarily async and its callers must await or otherwise track its promise.
         db.put = db.putSync;
-        db.remove = db.removeSync;
+        db.remove = ((id, removeOptions) => typeof removeOptions === 'number'
+            ? db.removeIfVersion(id, removeOptions)
+            : db.removeSync(id, removeOptions));
         db.encoder.name = options.name;
     }
     db.env = {};
@@ -326,22 +390,32 @@ const rocksdbDatabaseEnvs = new Map();
 (0, globals_js_1._assignPackageExport)('databases', exports.databases);
 (0, globals_js_1._assignPackageExport)('tables', exports.tables);
 const NEXT_TABLE_ID = Symbol.for('next-table-id');
-/**
- * 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
- * generation back at 1 while the persisted one is higher. A descriptor with no incarnation was written
- * before the field existed, so it belongs to an earlier process; a thread started without one of its
- * own cannot judge, and falls back rather than declaring a live build dead.
- */
-function isAbandonedIndexBuild(descriptor, currentRestartGeneration) {
-    if (!descriptor)
-        return false;
-    if (descriptor.indexingPID && descriptor.indexingPID !== process.pid)
-        return true;
-    if (descriptor.restartNumber < currentRestartGeneration)
-        return true;
-    const incarnation = manageThreads.processIncarnation;
-    return !!descriptor.indexingPID && incarnation != null && descriptor.indexingIncarnation !== incarnation;
+// Restore every field used by `commonChanged`, plus `indexed` and `indexNulls`,
+// from the durable descriptor. In particular, preserve `indexNulls: false` so
+// an index that excludes nulls is not reopened as though it contains them.
+const PEER_REDEFINABLE_FIELDS = [
+    'type',
+    'indexed',
+    'indexNulls',
+    'nullable',
+    'enumerable',
+    'version',
+    'elements',
+    'properties',
+    'embed',
+];
+// `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.
+const PEER_DECLARABLE_FIELDS = PEER_REDEFINABLE_FIELDS.filter((field) => field !== 'indexNulls');
+// A cluster-origin caller's list can predate a declaration another thread has already committed, so on
+// that path the descriptor — not the caller — decides what the attribute is, in both directions.
+function applyDurableDeclaration(attribute, descriptor) {
+    for (const field of PEER_REDEFINABLE_FIELDS) {
+        if (field in descriptor)
+            attribute[field] = descriptor[field];
+        else
+            delete attribute[field];
+    }
 }
 // How many times the schema load will try to finish a tombstoned drop before
 // giving up for the rest of this process's lifetime. A drop that fails once
@@ -416,6 +490,7 @@ function getDatabases() {
     }
     loadedDatabases = true;
     definedDatabases = new Map();
+    relationshipsToHydrate = [];
     const hdbBasePath = (0, environmentManager_ts_1.getHdbBasePath)();
     let databasePath = hdbBasePath && (0, path_1.join)(hdbBasePath, hdbTerms_ts_1.DATABASES_DIR_NAME);
     const schemaConfigs = (0, environmentManager_ts_1.get)(hdbTerms_ts_1.CONFIG_PARAMS.DATABASES) || {};
@@ -440,10 +515,15 @@ function getDatabases() {
             // create it (schemaRegex forbids the backtick), but the scan opens any CURRENT+MANIFEST dir
             if (databaseEntry.name === restoreMarker_ts_1.RESTORE_META_DIR)
                 continue;
+            // branch directories are process-local derivatives, never databases in their own right
+            if (databaseEntry.name === exports.BRANCH_ROOT_DIR)
+                continue;
             const dbName = (0, path_1.basename)(databaseEntry.name, '.mdb');
             const dbPath = (0, path_1.join)(databasePath, databaseEntry.name);
             if (blockedByRestore.has(dbName))
                 continue;
+            if (isOpenBranchPath(dbPath))
+                continue;
             if (databaseEntry.isFile() &&
                 (0, path_1.extname)(databaseEntry.name).toLowerCase() === '.mdb' &&
                 !schemaConfigs[dbName]?.path) {
@@ -495,8 +575,12 @@ function getDatabases() {
                         continue; // migration staging dir
                     if (databaseEntry.name === restoreMarker_ts_1.RESTORE_META_DIR)
                         continue; // reserved restore-metadata dir
+                    if (databaseEntry.name === exports.BRANCH_ROOT_DIR)
+                        continue; // reserved branch root
                     if (blockedByRestore.has((0, path_1.basename)(databaseEntry.name, '.mdb')))
                         continue;
+                    if (isOpenBranchPath((0, path_1.join)(databasePath, databaseEntry.name)))
+                        continue;
                     if (databaseEntry.isFile() && (0, path_1.extname)(databaseEntry.name).toLowerCase() === '.mdb') {
                         readMetaDb((0, path_1.join)(databasePath, databaseEntry.name), (0, path_1.basename)(databaseEntry.name, '.mdb'), dbName);
                     }
@@ -541,11 +625,15 @@ function getDatabases() {
             for (const tableName in tables) {
                 if (!definedTables.has(tableName)) {
                     logger.trace(`delete table class ${tableName}`);
+                    tables[tableName]?.cleanup?.();
                     delete tables[tableName];
                 }
             }
         }
         else {
+            const removedTables = exports.databases[dbName];
+            for (const tableName in removedTables)
+                removedTables[tableName]?.cleanup?.();
             delete exports.databases[dbName];
             if (dbName === 'data') {
                 for (const tableName in exports.tables) {
@@ -555,6 +643,7 @@ function getDatabases() {
             }
         }
     }
+    hydrateCatalogRelationships();
     if ((0, environmentManager_ts_1.get)(hdbTerms_ts_1.CONFIG_PARAMS.ANALYTICS_REPLICATE) === false) {
         if (!exports.NON_REPLICATING_SYSTEM_TABLES.includes('hdb_analytics'))
             exports.NON_REPLICATING_SYSTEM_TABLES.push('hdb_analytics');
@@ -573,6 +662,148 @@ function getDatabases() {
     }
     return exports.databases;
 }
+/**
+ * Hydrate one branch's relationships, resolving each target against the application's own branches
+ * first and only then against the real databases: a target the application also branched must be its
+ * branch's table, and a target it did not branch is legitimately the shared one.
+ */
+function hydrateBranchRelationships(branch, branches) {
+    const resolveTarget = (target) => {
+        const targetBranch = branches.get(target.database);
+        // A branched target resolves ONLY within that branch. A durable branch is a checkpoint frozen
+        // at creation while the base keeps evolving, so falling through to the base for a table the
+        // branch's own copy lacks would point a branched application's relationship reads at live base
+        // data -- the fallback belongs to a database the application did not branch, never to one it did.
+        return targetBranch ? targetBranch.tables?.[target.table] : exports.databases[target.database]?.[target.table];
+    };
+    // Kept, not drained, like the global list: a target declared later (on this or another thread) is
+    // picked up by the next pass, and `hydrateTableRelationships` is a no-op once everything resolves.
+    for (const hydration of branch.pendingRelationships) {
+        try {
+            hydrateTableRelationships(hydration, resolveTarget, false);
+        }
+        catch (error) {
+            logger.error(`Unable to hydrate persisted relationships for branch table ${hydration.databaseName}.${hydration.tableName}`, error);
+        }
+    }
+}
+function hydrateCatalogRelationships() {
+    for (const hydration of relationshipsToHydrate) {
+        try {
+            hydrateTableRelationships(hydration);
+        }
+        catch (error) {
+            const key = `${hydration.databaseName}.${hydration.tableName}:hydrate`;
+            if (!reportedRelationshipErrors.has(key)) {
+                reportedRelationshipErrors.add(key);
+                logger.error(`Unable to hydrate persisted relationships for ${hydration.databaseName}.${hydration.tableName}`, error);
+            }
+        }
+    }
+}
+const resolveTargetGlobally = (target) => exports.databases[target.database]?.[target.table];
+function hydrateTableRelationships({ table, databaseName, tableName, definitions }, resolveTarget = resolveTargetGlobally, announce = true) {
+    const hydratable = [];
+    for (let index = 0; index < definitions.length; index++) {
+        const definition = definitions[index];
+        // Keyed by name rather than list position, so a reordered list cannot inherit the previous
+        // occupant's reported state and swallow a different relationship's failure — and by reason, so
+        // hydrating one entry does not clear the report of a same-named invalid duplicate.
+        const errorKey = `${databaseName}.${tableName}:${definition?.name || `#${index}`}`;
+        if (!validRelationshipDefinition(definition, definitions, index)) {
+            reportRelationshipError(`${errorKey}:invalid`, `Ignoring invalid persisted relationship ${databaseName}.${tableName}[${index}]`);
+            continue;
+        }
+        // a live schema attribute of the same name owns the name; the catalog copy is only a stand-in
+        // for threads that never loaded the schema
+        if (table.attributes.some((attribute) => attribute.name === definition.name && !attribute[CATALOG_RELATIONSHIP]))
+            continue;
+        const targetTable = resolveTarget(definition.target);
+        if (!targetTable || !relationshipFieldsExist(table, targetTable, definition)) {
+            reportRelationshipError(`${errorKey}:unavailable`, `Unable to hydrate persisted relationship ${databaseName}.${tableName}.${definition.name}: target or foreign key is unavailable`);
+            continue;
+        }
+        reportedRelationshipErrors.delete(`${errorKey}:unavailable`);
+        hydratable.push({ definition, targetTable });
+    }
+    const installed = table.attributes.filter((attribute) => attribute[CATALOG_RELATIONSHIP]);
+    if (installed.length === hydratable.length &&
+        hydratable.every(({ definition, targetTable }, index) => relationshipEquals(installed[index], definition) &&
+            (installed[index].definition || installed[index].elements?.definition)?.tableClass === targetTable))
+        return;
+    const attributes = table.attributes.filter((attribute) => !attribute[CATALOG_RELATIONSHIP]);
+    for (const { definition, targetTable } of hydratable)
+        attributes.push(createCatalogRelationship(definition, targetTable));
+    table.attributes.splice(0, table.attributes.length, ...attributes);
+    table.schemaVersion++;
+    table.updatedAttributes();
+    if (announce)
+        exports.databaseEventsEmitter.emit('updateTable', table);
+}
+function validRelationshipDefinition(definition, definitions, index) {
+    if (!definition || typeof definition !== 'object')
+        return false;
+    const validName = (value) => typeof value === 'string' && value.length > 0 && !/[`/]/.test(value);
+    if (!validName(definition.name) || !validName(definition.type))
+        return false;
+    if (!validName(definition.target?.database) || !validName(definition.target?.table))
+        return false;
+    if (!definition.relationship || typeof definition.relationship !== 'object')
+        return false;
+    const { from, to, filterMissing } = definition.relationship;
+    if (from !== undefined && !validName(from))
+        return false;
+    if (to !== undefined && !validName(to))
+        return false;
+    if (!from && !to)
+        return false;
+    if (filterMissing !== undefined && typeof filterMissing !== 'boolean')
+        return false;
+    if (definition.type === 'array' ? !validName(definition.elements?.type) : definition.elements !== undefined)
+        return false;
+    for (let earlier = 0; earlier < index; earlier++)
+        if (definitions[earlier]?.name === definition.name)
+            return false;
+    return true;
+}
+function relationshipFieldsExist(sourceTable, targetTable, definition) {
+    if (definition.relationship.from &&
+        !sourceTable.attributes.some((attribute) => attribute.name === definition.relationship.from))
+        return false;
+    if (definition.relationship.to &&
+        !targetTable.attributes.some((attribute) => attribute.name === definition.relationship.to))
+        return false;
+    return true;
+}
+function createCatalogRelationship(definition, targetTable) {
+    const attribute = {
+        name: definition.name,
+        attribute: definition.name,
+        type: definition.type,
+        relationship: { ...definition.relationship },
+        target: { ...definition.target },
+    };
+    const targetDefinition = {
+        tableClass: targetTable,
+        type: targetTable.tableName,
+        attributes: targetTable.attributes,
+    };
+    if (definition.elements) {
+        attribute.elements = { type: definition.elements.type };
+        Object.defineProperty(attribute.elements, 'definition', { value: targetDefinition, configurable: true });
+    }
+    else {
+        Object.defineProperty(attribute, 'definition', { value: targetDefinition, configurable: true });
+    }
+    Object.defineProperty(attribute, CATALOG_RELATIONSHIP, { value: true });
+    return attribute;
+}
+function reportRelationshipError(key, message) {
+    if (reportedRelationshipErrors.has(key))
+        return;
+    reportedRelationshipErrors.add(key);
+    logger.error(message);
+}
 /**
  * Scan a databases directory's entries for restore lock/marker files and return the names of
  * databases that must not be loaded: a held restore lock means a restore is in progress in some
@@ -612,15 +843,14 @@ function readMetaDb(path, defaultTable, databaseName = DEFAULT_DATABASE_NAME, au
             rootStore = (0, lmdb_1.open)(envInit);
             lmdbDatabaseEnvs.set(path, rootStore);
         }
-        rootStore.dbisDb?.resetReadTxn();
-        return initStores(path, rootStore, databaseName, defaultTable, auditPath, isLegacy);
+        return initStores(path, rootStore, databaseName, { defaultTable, auditPath, isLegacy });
     }
     catch (error) {
         error.message += ` opening database ${path}`;
         throw error;
     }
 }
-function readRocksMetaDb(path, defaultTable, databaseName = DEFAULT_DATABASE_NAME) {
+function readRocksMetaDb(path, defaultTable, databaseName = DEFAULT_DATABASE_NAME, { destination, storeName, openedStores } = {}) {
     try {
         logger.trace(`loading rocksdb database: ${path}`);
         if (process.env.HARPER_PARENT_PROCESS_PID) {
@@ -631,14 +861,18 @@ function readRocksMetaDb(path, defaultTable, databaseName = DEFAULT_DATABASE_NAM
         }
         let rootStore = rocksdbDatabaseEnvs.get(path);
         if (rootStore) {
-            initStores(path, rootStore, databaseName, defaultTable);
+            initStores(path, rootStore, databaseName, { defaultTable, destination, storeName, openedStores });
         }
         else {
             rootStore = openRocksDatabase(path, { disableWAL: false, enableStats: true });
             rocksdbDatabaseEnvs.set(path, rootStore);
-            initStores(path, rootStore, databaseName, defaultTable);
-            // Skip transaction log replay in read-only mode
-            if (!isReadOnlyMode()) {
+            initStores(path, rootStore, databaseName, { defaultTable, destination, storeName, openedStores });
+            // A branch (`destination`) recovers its transaction-log tail in `openOrCreate`
+            // (branchDatabase.ts), not here: the branch claim elects exactly one replaying thread —
+            // applications load on workers, where this call would be a no-op — and awaits the replay
+            // before the branch is published to any reader. See the contract note on
+            // `openBranchDatabase` (harper#643).
+            if (!isReadOnlyMode() && !destination) {
                 (0, replayLogs_ts_1.replayLogs)(rootStore, exports.databases[databaseName]);
             }
         }
@@ -649,7 +883,9 @@ function readRocksMetaDb(path, defaultTable, databaseName = DEFAULT_DATABASE_NAM
         throw error;
     }
 }
-function initStores(path, rootStore, databaseName, defaultTable, auditPath, isLegacy) {
+function initStores(path, rootStore, databaseName, { defaultTable, auditPath, isLegacy, destination, storeName, openedStores } = {}) {
+    // a store with no tables never reaches the per-table loop below, and blob roots resolve from this
+    rootStore.databaseName = storeName ?? databaseName;
     const envInit = new OpenEnvironmentObject_ts_1.default(path, isReadOnlyMode());
     const internalDbiInit = createOpenDBIObject(false);
     let attributesDbi = rootStore.dbisDb;
@@ -664,6 +900,7 @@ function initStores(path, rootStore, databaseName, defaultTable, auditPath, isLe
         else {
             attributesDbi = rootStore.openDB(terms_ts_1.INTERNAL_DBIS_NAME, internalDbiInit);
         }
+        openedStores?.push(attributesDbi);
         rootStore.dbisDb = markInternalDbiNonVersioned(attributesDbi);
     }
     let auditStore = rootStore.auditStore;
@@ -690,7 +927,9 @@ function initStores(path, rootStore, databaseName, defaultTable, auditPath, isLe
             auditStore = (0, auditStore_ts_1.openAuditStore)(rootStore);
         }
     }
-    const tables = ensureDB(databaseName);
+    const tables = destination ?? ensureDB(databaseName);
+    if (destination && !destination[DEFINED_TABLES])
+        destination[DEFINED_TABLES] = new Set();
     const definedTables = tables[DEFINED_TABLES];
     definedTables.rootStore = rootStore;
     const tablesToLoad = new Map();
@@ -789,10 +1028,20 @@ function initStores(path, rootStore, databaseName, defaultTable, auditPath, isLe
                 }
             }
             if (!primaryAttribute) {
-                logger.warn(`Unable to find a primary key attribute on table ${tableName}, with attributes: ${JSON.stringify(attributes)}`);
+                const tableKey = `${databaseName}/${tableName}`;
+                if (reportedIncompleteCatalogs.has(tableKey))
+                    logger.debug(`Skipping table ${databaseName}.${tableName}: still no primary key row`);
+                else {
+                    reportedIncompleteCatalogs.add(tableKey);
+                    logger.warn(`Skipping table ${databaseName}.${tableName}: its catalog has attribute rows (${attributes.map((attribute) => attribute.name).join(', ')}) but no primary key row - a create in progress on another thread, or an interrupted one that re-running create_table repairs`);
+                }
+                // not defined until it loads, so the cleanup pass evicts a class left from a dropped same-name table
+                definedTables?.delete(tableName);
                 continue;
             }
         }
+        if (reportedIncompleteCatalogs.size)
+            reportedIncompleteCatalogs.delete(`${databaseName}/${tableName}`);
         // if the table has already been defined, use that class, don't create a new one
         let table = tables[tableName];
         // unless its store was migrated to a different engine (e.g. LMDB to RocksDB on startup)
@@ -838,13 +1087,13 @@ function initStores(path, rootStore, databaseName, defaultTable, auditPath, isLe
             // per-table override of the storage.randomAccessFields default (see OpenDBIObject)
             if (typeof primaryAttribute.randomAccessFields === 'boolean')
                 dbiInit.randomAccessStructure = primaryAttribute.randomAccessFields;
-            if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
-                primaryStore = (0, RecordEncoder_ts_1.handleLocalTimeForGets)(openRocksDatabase(rootStore.path, { ...dbiInit, name: primaryAttribute.key, cache: true }), rootStore);
-            }
-            else {
-                primaryStore = (0, RecordEncoder_ts_1.handleLocalTimeForGets)(rootStore.openDB(primaryAttribute.key, dbiInit), rootStore);
-            }
-            rootStore.databaseName = databaseName;
+            // recorded before the wrapper below, which is the only thing between the native open and
+            // the only list a failed open can release it from
+            const opened = rootStore instanceof rocksdb_js_1.RocksDatabase
+                ? openRocksDatabase(rootStore.path, { ...dbiInit, name: primaryAttribute.key, cache: true })
+                : rootStore.openDB(primaryAttribute.key, dbiInit);
+            openedStores?.push(opened);
+            primaryStore = (0, RecordEncoder_ts_1.handleLocalTimeForGets)(opened, rootStore);
             primaryStore.tableId = tableId;
         }
         let attributesUpdated;
@@ -855,11 +1104,10 @@ function initStores(path, rootStore, databaseName, defaultTable, auditPath, isLe
                 if (!attribute.isPrimaryKey && (attribute.indexed || (attribute.attribute && !attribute.name))) {
                     if (!indices[attribute.name]) {
                         const dbi = openIndex(attribute.key, rootStore, attribute);
+                        openedStores?.push(dbi);
                         indices[attribute.name] = dbi;
                         indices[attribute.name].indexNulls = attribute.indexNulls;
                     }
-                    // the only way a thread that never declares the schema reaches Table.indices
-                    indices[attribute.name].isIndexing = !!attribute.indexingPID;
                     const existingAttribute = existingAttributes.find((existingAttribute) => existingAttribute.name === attribute.name);
                     if (existingAttribute)
                         existingAttributes.splice(existingAttributes.indexOf(existingAttribute), 1, attribute);
@@ -927,6 +1175,8 @@ function initStores(path, rootStore, databaseName, defaultTable, auditPath, isLe
         }
         else {
             table = setTable(tables, tableName, (0, Table_ts_1.makeTable)({
+                // A branch builds into a caller-owned destination; its tables must refuse DDL.
+                isBranch: Boolean(destination),
                 primaryStore,
                 auditStore,
                 audit,
@@ -948,11 +1198,385 @@ function initStores(path, rootStore, databaseName, defaultTable, auditPath, isLe
                 dbisDB: attributesDbi,
             }));
             table.schemaVersion = 1;
-            exports.databaseEventsEmitter.emit('updateTable', table);
+            if (!destination)
+                exports.databaseEventsEmitter.emit('updateTable', table);
+        }
+        if (Array.isArray(primaryAttribute.relationships)) {
+            relationshipsToHydrate.push({ table, databaseName, tableName, definitions: primaryAttribute.relationships });
+        }
+        else if (primaryAttribute.relationships !== undefined) {
+            reportRelationshipError(`${databaseName}.${tableName}:list`, `Ignoring invalid persisted relationship list for ${databaseName}.${tableName}`);
+            relationshipsToHydrate.push({ table, databaseName, tableName, definitions: [] });
         }
     }
     return rootStore;
 }
+/**
+ * Branch directories live beside the base database's own storage root, never under the HDB root: a
+ * database can be placed on its own volume, and `createCheckpoint` only hardlinks when source and
+ * target share a filesystem — off-volume it degrades to a full byte copy, which is the property the
+ * whole feature rests on.
+ *
+ * The backticks are what make the name reserved rather than merely conventional: `schemaRegex`
+ * (validation/common_validators.ts) excludes 0x60, so no database can ever be created under this
+ * name and shadow the branch root -- the same protection RESTORE_META_DIR uses.
+ */
+exports.BRANCH_ROOT_DIR = '`branches`';
+/**
+ * Where the branch of `baseName` belonging to `appName` lives. Derived only from those two names, so
+ * every node in a cluster resolves the same application's branch to the same place — the identity an
+ * application's data needs if it is to be addressed, and eventually replicated, cluster-wide.
+ *
+ * App and database are separate path segments: joining them (`<app>__<db>`) is not injective —
+ * `(a__b, c)` and `(a, b__c)` collide — so two declarations could otherwise open one directory.
+ */
+function resolveBranchPath(baseName, appName) {
+    for (const [label, segment] of [
+        ['application', appName],
+        ['database', baseName],
+    ]) {
+        if (!segment || segment.includes('/') || segment.includes('\\') || segment === '.' || segment === '..') {
+            throw new Error(`Invalid ${label} name for a branch path: ${JSON.stringify(segment)}`);
+        }
+    }
+    return (0, path_1.join)(resolveDatabaseStorageRoot(baseName), exports.BRANCH_ROOT_DIR, appName, baseName);
+}
+/** `undefined` marks a path reserved by an open still in flight, which owns it just as firmly. */
+const openBranches = new Map();
+/** Store identities in use, so two branches cannot resolve one set of blob roots. */
+const openBranchIdentities = new Set();
+/**
+ * Materialization renames its clone in from `<blobRoot>.staging`, so a branch owns two database
+ * names rather than one: a database legally called `<storeName>.staging` resolves its own blob root
+ * to exactly the path the clone removes and renames over. Every check, reservation and release
+ * covers the pair, so the name cannot be claimed at any point where a branch operation may still
+ * delete what it resolves to.
+ */
+const BRANCH_STAGING_SUFFIX = '.staging';
+/**
+ * Suffix of the sibling a branch is renamed to while being removed. A backtick, not a dot:
+ * `schemaRegex` excludes 0x60, so no database can be named such that `<db>` + this suffix is another
+ * branch's directory (with `.removing`, an application branching both `data` and `data.removing`, both
+ * legal names, would destroy one by opening the other).
+ */
+exports.BRANCH_REMOVING_SUFFIX = '`removing`';
+function branchIdentityPair(storeName) {
+    return [storeName, storeName + BRANCH_STAGING_SUFFIX];
+}
+/**
+ * Identities whose blob roots outlived the branch that owned them, because a removal or an abandoned
+ * materialization could not delete them. A database created under such a name would resolve its own
+ * fresh file ids onto files it never wrote, so the name stays refused -- but only against DATABASES.
+ * The branch itself may take it back: materializing it replaces those roots wholesale, which is the
+ * only route that clears the condition without an operator.
+ */
+const quarantinedBranchIdentities = new Set();
+function quarantineBranchIdentity(storeName) {
+    for (const name of branchIdentityPair(storeName)) {
+        quarantinedBranchIdentities.add(name);
+        openBranchIdentities.delete(name);
+    }
+}
+/**
+ * True when `dbPath` is a directory an open branch owns. The database scan opens any directory that
+ * holds CURRENT + MANIFEST-*, and harper#643 places a branch inside the directory it walks, so
+ * without this a rescan would rebuild the branch's tables into the global map, overwrite the store
+ * identity its blob roots resolve from, and hand its store to `closeLoadedDatabases`.
+ */
+function isOpenBranchPath(dbPath) {
+    if (openBranches.size === 0)
+        return false;
+    // the literal path first: `rocksdbDatabaseEnvs` is keyed by it too, so a directory unlinked under
+    // a live branch handle (realpathSync then throws) must not read as unowned
+    if (openBranches.has(dbPath))
+        return true;
+    try {
+        return openBranches.has((0, node_fs_1.realpathSync)(dbPath));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A branch identity resolves its blob roots through `join(…, 'blobs', storeName)`, so it must be a
+ * single path segment: `schemaRegex`, which every other database name is validated against, plus the
+ * dot segments and backslash that regex permits but a path component must not be.
+ */
+function assertLegalBranchName(name, description) {
+    if (!name ||
+        name.length > common_validators_ts_1.commonValidators.schema_length.maximum ||
+        !common_validators_ts_1.schemaRegex.test(name) ||
+        name.includes('\\') ||
+        name === '.' ||
+        name === '..') {
+        throw new Error(`Cannot use '${name}' as a branch ${description}: it is not a legal database name`);
+    }
+}
+/**
+ * Refuse a branch store identity that something else already answers to.
+ *
+ * `storeName` picks the branch's blob roots, and blob file ids restart from each store's own counter,
+ * so two holders of one identity write the same file paths and truncate each other. It must be
+ * checked BEFORE anything destructive runs: materialization removes and replaces the blob root that
+ * this name resolves to, and a real database may legally be called `5_myapp__data` -- `schemaRegex`
+ * permits digits, `_` and `.`. The `.staging` sibling materialization writes is covered too, since a
+ * database may legally carry that name as well.
+ */
+function assertBranchIdentityAvailable(storeName) {
+    // The on-disk scan, not just the in-memory maps: a database that exists on disk but has not been
+    // loaded is absent from both, and it owns the blob root this identity would destroy.
+    getDatabases();
+    for (const name of branchIdentityPair(storeName)) {
+        // The directory as well as the maps. `getDatabases` skips a database blocked by restore, so an
+        // in-memory check alone reports its name as free while its blob root is very much real -- and
+        // materialization would then remove and replace it.
+        if (exports.databases[name] ||
+            definedDatabases?.has(name) ||
+            openBranchIdentities.has(name) ||
+            (0, node_fs_1.existsSync)(resolveDatabasePath(name)) ||
+            anotherBranchOwns(name, storeName)) {
+            throw new Error(`Cannot use '${storeName}' as a branch store identity: '${name}' is already in use`);
+        }
+    }
+}
+/**
+ * Does a branch OTHER than the one being opened already answer to this name on disk? `.staging` is
+ * what makes the question two-sided: `<identity>.staging` is both the path a clone renames over and
+ * a legal identity for a branch of a database literally named `<base>.staging`, so each of the pair
+ * can belong to somebody else. Only the primary name read as itself is excluded -- that directory is
+ * the very branch this call is opening.
+ */
+function anotherBranchOwns(name, storeName) {
+    if (name !== storeName)
+        return branchDirectoryExistsFor(name);
+    return name.endsWith(BRANCH_STAGING_SUFFIX)
+        ? branchDirectoryExistsFor(name.slice(0, -BRANCH_STAGING_SUFFIX.length))
+        : false;
+}
+/**
+ * Claim the identity as well as checking it, so the window between the check and the branch actually
+ * opening cannot be filled by a concurrent create or a second branch. `releaseBranchIdentity` hands
+ * it back if materialization never gets as far as opening.
+ */
+function reserveBranchIdentity(storeName) {
+    assertBranchIdentityAvailable(storeName);
+    retakeBranchIdentity(storeName);
+}
+/**
+ * Take the pair back for an operation that owned it a statement ago -- cleanup, which has to keep
+ * holding the names through the deletions its `close()` just released them for. Deliberately without
+ * the availability check: nothing can have taken a name the caller held until now, and the check runs
+ * the database scan, which at that exact moment would find the branch directory unowned.
+ */
+function retakeBranchIdentity(storeName) {
+    for (const name of branchIdentityPair(storeName)) {
+        openBranchIdentities.add(name);
+        quarantinedBranchIdentities.delete(name);
+    }
+}
+function releaseBranchIdentity(storeName) {
+    for (const name of branchIdentityPair(storeName))
+        openBranchIdentities.delete(name);
+}
+/** Is this name spoken for by a branch? Database creation has to refuse it -- they share a blob root. */
+function isBranchIdentity(name) {
+    if (openBranchIdentities.has(name) || quarantinedBranchIdentities.has(name))
+        return true;
+    // The in-memory set covers only branches open in THIS process, so after a restart -- or for an
+    // application that is simply not loaded -- a database could take the name of an on-disk branch and
+    // share its blob root. The staging sibling goes through the same route, because it names the path
+    // materialization renames over -- but BOTH readings of a name ending in `.staging` have to be
+    // tried: `schemaRegex` permits `.`, so `4_myapp__data.staging` is either the sibling of a branch of
+    // `data` or a branch of a database actually called `data.staging`.
+    if (branchDirectoryExistsFor(name))
+        return true;
+    return name.endsWith(BRANCH_STAGING_SUFFIX)
+        ? branchDirectoryExistsFor(name.slice(0, -BRANCH_STAGING_SUFFIX.length))
+        : false;
+}
+/**
+ * Is there a branch directory answering to this store identity? The identity carries the application
+ * name's length precisely so it can be taken apart again without guessing where the name ends.
+ */
+function branchDirectoryExistsFor(storeName) {
+    const prefix = /^(\d+)_/.exec(storeName);
+    if (!prefix)
+        return false;
+    const appLength = Number(prefix[1]);
+    const appName = storeName.slice(prefix[0].length, prefix[0].length + appLength);
+    if (appName.length !== appLength ||
+        storeName.slice(prefix[0].length + appLength, prefix[0].length + appLength + 2) !== '__')
+        return false;
+    const baseName = storeName.slice(prefix[0].length + appLength + 2);
+    if (!baseName)
+        return false;
+    try {
+        const branchPath = resolveBranchPath(baseName, appName);
+        return (0, node_fs_1.existsSync)(branchPath) || (0, node_fs_1.existsSync)(branchPath + exports.BRANCH_REMOVING_SUFFIX);
+    }
+    catch {
+        // Not a name a branch path could hold, so no branch owns it.
+        return false;
+    }
+}
+/**
+ * Open a RocksDB directory as a **scope-private** database: its Table classes are built into an
+ * object the caller owns and nothing is registered in the global `databases` map, so no enumerator
+ * of that map — analytics, `describe_all`, worker teardown, replication — can observe it.
+ *
+ * `databaseName` is the *logical* name the application knows (`data`), so its schema and code need
+ * no changes. `storeName` is the branch's own identity and is what `getRootBlobPathsForDB` resolves
+ * blob directories from, which is how a branch gets its own blob roots rather than writing into the
+ * base's.
+ *
+ * The caller owns the returned handle; the only thing that closes it on the caller's behalf is
+ * `closeBranchDatabases`, run by an exiting job worker (via `closeLoadedDatabases`) and by an HTTP
+ * worker's shutdown path, so a branch left open on an exiting worker does not linger in the
+ * process-global RocksDB registry.
+ *
+ * Schema changes reach a branch only through its own bound factory (`scopedTableFactory`): a
+ * declaration re-asserted against the branch's store. A branch's Table classes carry the base's
+ * logical name, so the Table statics (`dropTable()`, `addAttributes()`) — which resolve the global
+ * schema by that name and would act on the live base table — stay refused (`assertSchemaMutable`).
+ *
+ * A branch's blob roots are a hard-link clone of the base's, taken with the checkpoint, so a row
+ * whose blob predates the branch reads back normally and the branch allocates new file ids in its own
+ * directory (harper#644).
+ *
+ * A branch is the checkpoint's SST content plus its own transaction-log tail. This function opens
+ * only the stores; replaying the tail is `openOrCreate`'s job (branchDatabase.ts), where the
+ * cross-thread claim elects exactly one replayer and awaits it before any thread may open the
+ * branch — the same recovery contract a base database gets at boot, without which a process that
+ * died unflushed silently rewinds the branch to its last memtable flush (harper#643).
+ *
+ * Pass `blobRoots` to pin the handle to the roots the branch was published with; without it the
+ * store resolves them from current configuration, which is only right for a branch being created.
+ */
+function openBranchDatabase(path, databaseName, storeName, blobRoots) {
+    assertLegalBranchName(databaseName, 'logical database name');
+    assertLegalBranchName(storeName, 'store identity');
+    if (!(0, node_fs_1.existsSync)(path))
+        throw new Error(`Cannot open branch database: no directory at ${path}`);
+    // the guards compare against env-map keys, so two spellings of one directory must not read as two
+    path = (0, node_fs_1.realpathSync)(path);
+    // FIRST: the guards below read the registry, and loading is itself what populates
+    // `rocksdbDatabaseEnvs`. Claiming the path ahead of this scan would make the scan skip it, which
+    // also means a directory that IS a real database no longer reads as one — so the pre-open window
+    // where the scan can adopt a branch directory stays open, by choice (harper#643).
+    getDatabases();
+    // a rival graph over one shared root store; the two callers would disagree about who may close it
+    if (openBranches.has(path))
+        throw new Error(`Branch database at ${path} is already open`);
+    // a loaded database's store is closed by `closeLoadedDatabases`, so adopting it would mean this
+    // handle's `close()` tears down a live database
+    if (rocksdbDatabaseEnvs.has(path))
+        throw new Error(`Cannot branch ${path}: it is already open as a database`);
+    assertBranchIdentityAvailable(storeName);
+    const tables = Object.create(null);
+    // initStores opens a table's column families well before `setTable` publishes it into `tables`,
+    // so the graph is not a complete record of what a failed open must release
+    const openedStores = [];
+    // The boot-time hydration pass has already run by the time a branch opens, so anything this open
+    // queues would never be drained. It is handed to the caller instead, which is the only place that
+    // knows the application's other branches and can therefore resolve targets without leaking to base.
+    const queuedRelationshipsAt = relationshipsToHydrate.length;
+    let rootStore;
+    // claim the path before the open, not after: readRocksMetaDb registers the store in
+    // `rocksdbDatabaseEnvs` partway through, so anything re-entering `database()` during initStores
+    // would otherwise find the branch's store on an unowned path
+    openBranches.set(path, undefined);
+    retakeBranchIdentity(storeName);
+    try {
+        rootStore = readRocksMetaDb(path, null, databaseName, { destination: tables, storeName, openedStores });
+        // Pin the handle to the roots the caller proved this branch was published with, before it is
+        // handed out. A row's `storageIndex` is a position in that list, so resolving through current
+        // configuration instead would let an appended volume take writes at an index the branch's own
+        // completion marker never recorded -- and a later change at that index would then silently
+        // re-address them. `closeBranchHandles` clears the entry with the rest of the handle.
+        if (blobRoots)
+            blob_ts_1.databasePaths.set(rootStore, blobRoots);
+    }
+    catch (error) {
+        openBranches.delete(path);
+        releaseBranchIdentity(storeName);
+        const stranded = rocksdbDatabaseEnvs.get(path);
+        rocksdbDatabaseEnvs.delete(path);
+        closeBranchHandles(path, stranded, openedStores, tables);
+        throw error;
+    }
+    let closed = false;
+    const branch = {
+        tables,
+        rootStore,
+        path,
+        databaseName,
+        storeName,
+        openedStores,
+        pendingRelationships: relationshipsToHydrate.splice(queuedRelationshipsAt),
+        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);
+            closeBranchHandles(path, rootStore, openedStores, tables);
+        },
+    };
+    openBranches.set(path, branch);
+    return branch;
+}
+/**
+ * Release everything a branch open created. Each table's primary store and each index is its own
+ * column family, on top of the internal-dbis and audit families, so closing the root alone leaves
+ * all of them behind — which is why `closeDatabase` walks them individually for a real database.
+ * Two process-global registrations outlive the stores as well, neither with a lifetime of its own:
+ * a storage-reclamation handler per store path, whose closure pins the now-closed store, and the
+ * memoized blob roots in `databasePaths`. A real database is opened once per thread; harper#643
+ * makes branch open/close routine, so both would grow with branch churn.
+ */
+function closeBranchHandles(path, rootStore, openedStores = [], tables = {}) {
+    const reclamationPaths = new Set([path]);
+    rootStore?.auditStore?.stopAuditCleanup?.();
+    const closeStore = (store, description) => {
+        if (!store || store.status === 'closed')
+            return;
+        if (store.path)
+            reclamationPaths.add(store.path);
+        try {
+            store.close?.();
+        }
+        catch (error) {
+            logger.warn(`Error closing ${description} for branch database at ${path}`, error);
+        }
+    };
+    // the class, before its stores: an expiration timer or a reclamation handler on a closed store
+    // would otherwise keep firing against it for the life of the process
+    for (const tableName in tables) {
+        try {
+            tables[tableName]?.cleanup?.();
+        }
+        catch (error) {
+            logger.warn(`Error releasing table ${tableName} of branch database at ${path}`, error);
+        }
+    }
+    for (const store of openedStores)
+        closeStore(store, 'column family');
+    closeStore(rootStore?.dbisDb, 'attributes store');
+    closeStore(rootStore?.auditStore, 'audit store');
+    closeStore(rootStore, 'root store');
+    if (rootStore)
+        blob_ts_1.databasePaths.delete(rootStore);
+    for (const reclamationPath of reclamationPaths)
+        (0, storageReclamation_ts_1.removeStorageReclamation)(reclamationPath);
+}
+/** Branches are process-local, so this is shutdown, not a data operation. */
+function closeBranchDatabases() {
+    for (const branch of [...openBranches.values()])
+        branch?.close();
+}
 function resetDatabases() {
     loadedDatabases = false;
     for (const store of Object.values(lmdbDatabaseEnvs)) {
@@ -1063,6 +1687,14 @@ function database({ database: databaseName, table: tableName }) {
     const useRocksdb = (process.env.HARPER_STORAGE_ENGINE || (0, environmentManager_ts_1.get)(hdbTerms_ts_1.CONFIG_PARAMS.STORAGE_ENGINE)) !== 'lmdb';
     if (useRocksdb) {
         const path = (0, 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
+        if (isOpenBranchPath(path)) {
+            const error = new Error(`Database '${databaseName}' is open as a scope-private branch`);
+            error.statusCode = 409;
+            throw error;
+        }
         rootStore = rocksdbDatabaseEnvs.get(path);
         if (!rootStore || rootStore.status === 'closed') {
             // this on-demand open (create_table/create_database and friends) must not resurrect a
@@ -1290,8 +1922,12 @@ function closeDatabase(databaseName) {
  * database is closed). 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();
     // snapshot the names first: closeDatabase() deletes from `databases` as it goes
     for (const databaseName of Object.keys(exports.databases)) {
         const dbTables = exports.databases[databaseName];
@@ -1394,24 +2030,38 @@ function openIndex(dbiKey, rootStore, attribute) {
             cache: isCustomObjectIndex,
         });
         dbi.rootStore = rootStore;
-        // Custom-index object stores (e.g. HNSW) write graph nodes via plain put() with no staged
-        // transaction timestamp, so their values carry no version and the PrimaryRocksDatabase
-        // Verification-Table cache can't track them. A versioned index initialises its encoder as a
-        // versioned RocksDB store (isRocksDB → metadata-prefix encode/decode) and marks it
-        // self-versioning, so each node gets a monotonic version the VT can extract — enabling cached,
-        // decode-free graph traversal. The format is resolved from the persisted attribute descriptor
-        // (decided once at create — see resolveIndexFormat) so every worker and reload agree on it.
-        if (isCustomObjectIndex && resolveIndexFormat(dbiKey, rootStore, dbi, attribute) === 'versioned') {
-            armVersionedIndexEncoder(dbi, rootStore);
+        try {
+            // Custom-index object stores (e.g. HNSW) write graph nodes via plain put() with no staged
+            // transaction timestamp, so their values carry no version and the PrimaryRocksDatabase
+            // Verification-Table cache can't track them. A versioned index initialises its encoder as a
+            // versioned RocksDB store (isRocksDB → metadata-prefix encode/decode) and marks it
+            // self-versioning, so each node gets a monotonic version the VT can extract — enabling cached,
+            // decode-free graph traversal. The format is resolved from the persisted attribute descriptor
+            // (decided once at create — see resolveIndexFormat) so every worker and reload agree on it.
+            if (isCustomObjectIndex && resolveIndexFormat(dbiKey, rootStore, dbi, attribute) === 'versioned') {
+                armVersionedIndexEncoder(dbi, rootStore);
+            }
+            installCustomIndex(dbi);
+        }
+        catch (error) {
+            // the handle is not yet owned by any table, so nobody else can close it
+            try {
+                dbi.close();
+            }
+            catch { }
+            throw error;
         }
     }
     else {
         dbi = rootStore.openDB(dbiKey, dbiInit);
+        installCustomIndex(dbi);
     }
-    if (attribute.indexed.type) {
+    function installCustomIndex(indexStore) {
+        if (!attribute.indexed.type)
+            return;
         const CustomIndex = customIndexes_ts_1.CUSTOM_INDEXES[attribute.indexed.type];
         if (CustomIndex) {
-            dbi.customIndex = new CustomIndex(dbi, attribute.indexed);
+            indexStore.customIndex = new CustomIndex(indexStore, attribute.indexed);
         }
         else {
             logger.error(`The indexing type '${attribute.indexed.type}' is unknown`);
@@ -1434,7 +2084,83 @@ function openIndex(dbiKey, rootStore, attribute) {
  * @param replicate
  */
 function table(tableDefinition) {
-    let { table: tableName, database: databaseName, expiration, eviction, scanInterval, attributes, audit, sealed, splitSegments, replicate, randomAccessFields, trackDeletes, schemaDefined, origin, description, properties, hidden, cacheControl, } = tableDefinition;
+    return declareTable(GLOBAL_TARGET, tableDefinition);
+}
+const GLOBAL_TARGET = {
+    rootStore: (databaseName, tableName) => database({ database: databaseName, table: tableName }),
+    tables: (databaseName) => exports.databases[databaseName],
+    reload: () => resetDatabases(),
+    // a real database's stores live until the process (or `closeDatabase`, which walks the graph) ends
+    adopt: () => { },
+};
+/**
+ * The factory a branched application declares tables through: each declaration goes to the branch
+ * of the database it names, or to `table()` itself for a database the application did not branch.
+ * An unbranched application gets `table` by identity -- no wrapper, no per-call routing.
+ */
+function scopedTableFactory(branches) {
+    if (!branches?.size)
+        return table;
+    return function scopedTable(tableDefinition) {
+        // `||`, not `??`: `table()` resolves every falsy name to the default database
+        const branch = branches.get(tableDefinition.database || DEFAULT_DATABASE_NAME);
+        return branch ? declareTable(branchTarget(branch), tableDefinition) : table(tableDefinition);
+    };
+}
+function branchTarget(branch) {
+    return {
+        rootStore: () => branch.rootStore,
+        tables: () => branch.tables,
+        reload: () => reloadBranch(branch),
+        adopt: (store) => branch.openedStores.push(store),
+        branch,
+    };
+}
+/**
+ * Re-read a branch's catalog into its `tables`: tables and indexes another thread declared since the
+ * open (or since the last reload) are opened here, the same way a schema-change rescan does for a
+ * real database. Existing classes are kept and their attribute lists refreshed.
+ */
+function reloadBranch(branch) {
+    const { rootStore, tables, databaseName, storeName, openedStores } = branch;
+    const queuedRelationshipsAt = relationshipsToHydrate.length;
+    try {
+        initStores(rootStore.path, rootStore, databaseName, { destination: tables, storeName, openedStores });
+    }
+    finally {
+        for (const hydration of relationshipsToHydrate.splice(queuedRelationshipsAt))
+            queueBranchHydration(branch, hydration);
+    }
+    // Until `prepareBranches` has the whole set, a cross-database target cannot be resolved without
+    // falling through to the base; it hydrates the complete set once. After that, every sibling is
+    // re-hydrated: the table this reload brought in may be the target a sibling's relationship waited for.
+    if (!branch.relatedBranches)
+        return;
+    for (const sibling of branch.relatedBranches.values())
+        hydrateBranchRelationships(sibling, branch.relatedBranches);
+}
+/** One pending hydration per table: a re-declaration replaces the entry the earlier declaration queued. */
+function queueBranchHydration(branch, hydration) {
+    const existing = branch.pendingRelationships.findIndex((pending) => pending.databaseName === hydration.databaseName && pending.tableName === hydration.tableName);
+    if (existing >= 0)
+        branch.pendingRelationships[existing] = hydration;
+    else
+        branch.pendingRelationships.push(hydration);
+}
+/**
+ * The receiving side of a branch's schema-change signal: a thread that holds this branch open reloads
+ * it, any other thread has nothing to do. Returns the branch's tables so the caller can address the
+ * table the signal named.
+ */
+function reloadBranchAt(path) {
+    const branch = openBranches.get(path);
+    if (!branch)
+        return undefined;
+    reloadBranch(branch);
+    return branch.tables;
+}
+function declareTable(target, tableDefinition) {
+    let { table: tableName, database: databaseName, expiration, eviction, scanInterval, attributes, audit, sealed, splitSegments, replicate, randomAccessFields, trackDeletes, schemaDefined, schemaRelationshipsDefined, origin, description, properties, hidden, cacheControl, } = tableDefinition;
     if (!databaseName)
         databaseName = DEFAULT_DATABASE_NAME;
     // Reject reserved names here too, not only at the operations API: a database
@@ -1447,8 +2173,14 @@ function table(tableDefinition) {
     if (hdbTerms_ts_1.RESERVED_DATABASE_NAMES.includes(databaseName)) {
         throw new hdbError_ts_1.ClientError(`'${databaseName}' is a reserved name and cannot be used as a database name`);
     }
-    const rootStore = database({ database: databaseName, table: tableName });
-    const tables = exports.databases[databaseName];
+    // A branch resolves its blob root from its store identity, so a database created under that same
+    // name would share the root: two allocators minting the same file paths and truncating each other,
+    // and the branch's teardown removing the database's blobs.
+    if (isBranchIdentity(databaseName)) {
+        throw new hdbError_ts_1.ClientError(`'${databaseName}' is in use as a branch store identity and cannot be a database name`);
+    }
+    const rootStore = target.rootStore(databaseName, tableName);
+    const tables = target.tables(databaseName);
     logger.trace(`Defining ${tableName} in ${databaseName}`);
     let Table = tables?.[tableName];
     if (rootStore.status === 'closed') {
@@ -1463,6 +2195,7 @@ function table(tableDefinition) {
     const schemaDefinedExplicit = tableDefinition.schemaDefined !== undefined;
     if (schemaDefined == undefined)
         schemaDefined = true;
+    const relationshipDefinitions = schemaRelationshipsDefined ? normalizeRelationships(attributes) : undefined;
     const internalDbiInit = createOpenDBIObject(false);
     for (const attribute of attributes) {
         if (attribute.attribute && !attribute.name) {
@@ -1476,124 +2209,161 @@ function table(tableDefinition) {
             attribute.indexed = true;
     }
     let hasChanges;
+    let refreshRelationshipAttributes = false;
+    let deferredPrimaryRow;
+    let unpublishedPrimaryStore;
+    let published = false;
     let releaseExclusiveLock;
-    if (Table) {
-        primaryKey = Table.primaryKey;
-        if (Table.primaryStore.rootStore.status === 'closed') {
-            throw new Error(`Can not use a closed data store from ${tableName} class`);
-        }
-        // Reject moving the primary key to a different attribute on a table that already has records.
-        // The storage key (Table.primaryKey) is never re-pointed here, so honoring the change would
-        // leave describe reporting the new attribute while every record — old and newly inserted — stays
-        // keyed by the original one; search_by_id/update/delete by the declared key then all miss. Only
-        // schema-authored callers (@table / defineTable / create_table) reassert the declaration, so
-        // gate on schemaDefinedExplicit to leave cluster schema-replication / data-loader callers alone.
-        // See HarperFast/studio#1199.
-        const declaredPrimaryKey = attributes.find((attribute) => attribute.isPrimaryKey)?.name;
-        if (schemaDefinedExplicit && declaredPrimaryKey && declaredPrimaryKey !== Table.primaryKey) {
-            let hasRecords = false;
-            for (const _entry of Table.primaryStore.getRange({ start: true })) {
-                hasRecords = true;
-                break;
+    const attributesToIndex = [];
+    const indicesToRemove = [];
+    try {
+        if (Table) {
+            primaryKey = Table.primaryKey;
+            if (Table.primaryStore.rootStore.status === 'closed') {
+                throw new Error(`Can not use a closed data store from ${tableName} class`);
             }
-            if (hasRecords) {
-                throw new hdbError_ts_1.ClientError(`Cannot change the primary key of table '${databaseName}.${tableName}' from '${Table.primaryKey}' to ` +
-                    `'${declaredPrimaryKey}' because it already contains records. Recreate the table with the new primary ` +
-                    `key, or migrate the existing records.`, 400);
-            }
-        }
-        // it table already exists, get the split segments setting
-        if (splitSegments == undefined)
-            splitSegments = Table.splitSegments;
-        Table.attributes.splice(0, Table.attributes.length, ...attributes);
-        // Re-assert from the live declaration so a stale value on disk (replicated event,
-        // v4-era backfill) is corrected on every reload. Gated on `schemaDefinedExplicit` so
-        // callers that omit the flag (cluster schema-replication, data loader) don't flip a
-        // dynamic table to true via the default at the top of table().
-        if (schemaDefinedExplicit)
-            Table.schemaDefined = schemaDefined;
-        // Refresh class-level schema metadata to track docstring/directive changes across reloads.
-        Table.description = description;
-        Table.properties = properties;
-        Table.hidden = hidden;
-        // undefined means a non-schema caller (add_attribute, cluster schema events) — don't clobber
-        if (cacheControl !== undefined)
-            Table.cacheControl = cacheControl;
-    }
-    else {
-        const auditStore = rootStore.auditStore;
-        primaryKeyAttribute = attributes.find((attribute) => attribute.isPrimaryKey) || {};
-        primaryKey = primaryKeyAttribute.name;
-        primaryKeyAttribute.isPrimaryKey = true;
-        primaryKeyAttribute.is_hash_attribute = true; // backward-compat: harperdb@4.x reads this field to open the DBI with correct flags
-        primaryKeyAttribute.schemaDefined = schemaDefined;
-        // can't change compression after the fact (except threshold), so save only when we create the table
-        primaryKeyAttribute.compression = getDefaultCompression();
-        if (trackDeletes)
-            primaryKeyAttribute.trackDeletes = true;
-        audit = primaryKeyAttribute.audit = typeof audit === 'boolean' ? audit : (0, environmentManager_ts_1.get)(hdbTerms_ts_1.CONFIG_PARAMS.LOGGING_AUDITLOG);
-        if (expiration)
-            primaryKeyAttribute.expiration = expiration;
-        if (eviction)
-            primaryKeyAttribute.eviction = eviction;
-        // persist cacheControl so all threads (and future boots) see it; undefined callers inherit
-        // a descriptor value carried by cluster schema events; null (schema has no directive)
-        // clears a stale value the carried descriptor may hold
-        if (cacheControl === undefined)
-            cacheControl = primaryKeyAttribute.cacheControl;
-        else if (cacheControl === null)
-            delete primaryKeyAttribute.cacheControl;
-        else
-            primaryKeyAttribute.cacheControl = cacheControl;
-        splitSegments ??= false;
-        primaryKeyAttribute.splitSegments = splitSegments; // always default to not splitting segments going forward
-        if (typeof sealed === 'boolean')
-            primaryKeyAttribute.sealed = sealed;
-        if (typeof replicate === 'boolean')
-            primaryKeyAttribute.replicate = replicate;
-        // An explicit directive PINS this table's encoding: we persist the boolean, so later changes
-        // to the global storage.randomAccessFields default never affect this table. Tables WITHOUT the
-        // directive are intentionally not persisted here — they follow the current global default on
-        // each open (a runtime lever to flip encoding fleet-wide). Switching either way is safe: the
-        // struct READ hook always stays on and struct (0x20-0x3f) vs classic-record (0x40-0x7f) bytes
-        // are disjoint, so already-written records still decode; only the encoding of NEW writes changes.
-        if (typeof randomAccessFields === 'boolean')
-            primaryKeyAttribute.randomAccessFields = randomAccessFields;
-        if (origin) {
-            if (!primaryKeyAttribute.origins)
-                primaryKeyAttribute.origins = [origin];
-            else if (!primaryKeyAttribute.origins.includes(origin))
-                primaryKeyAttribute.origins.push(origin);
-        }
-        logger.trace(`${tableName} table loading, opening primary store`);
-        const dbiInit = createOpenDBIObject(false, true);
-        dbiInit.compression = primaryKeyAttribute.compression;
-        // per-table override of the storage.randomAccessFields default (see OpenDBIObject)
-        if (typeof primaryKeyAttribute.randomAccessFields === 'boolean')
-            dbiInit.randomAccessStructure = primaryKeyAttribute.randomAccessFields;
-        const dbiName = tableName + '/';
-        if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
-            attributesDbi = rootStore.dbisDb = openRocksDatabase(rootStore.path, {
-                ...internalDbiInit,
-                disableWAL: false,
-                name: terms_ts_1.INTERNAL_DBIS_NAME,
-            });
+            // Reject moving the primary key to a different attribute on a table that already has records.
+            // The storage key (Table.primaryKey) is never re-pointed here, so honoring the change would
+            // leave describe reporting the new attribute while every record — old and newly inserted — stays
+            // keyed by the original one; search_by_id/update/delete by the declared key then all miss. Only
+            // schema-authored callers (@table / defineTable / create_table) reassert the declaration, so
+            // gate on schemaDefinedExplicit to leave cluster schema-replication / data-loader callers alone.
+            // See HarperFast/studio#1199.
+            const declaredPrimaryKey = attributes.find((attribute) => attribute.isPrimaryKey)?.name;
+            if (schemaDefinedExplicit && declaredPrimaryKey && declaredPrimaryKey !== Table.primaryKey) {
+                let hasRecords = false;
+                for (const _entry of Table.primaryStore.getRange({ start: true })) {
+                    hasRecords = true;
+                    break;
+                }
+                if (hasRecords) {
+                    throw new hdbError_ts_1.ClientError(`Cannot change the primary key of table '${databaseName}.${tableName}' from '${Table.primaryKey}' to ` +
+                        `'${declaredPrimaryKey}' because it already contains records. Recreate the table with the new primary ` +
+                        `key, or migrate the existing records.`, 400);
+                }
+            }
+            // Acquire before the first mutation of the live Table below, so a lost race leaves no
+            // attributes this worker describes but never persisted. Only the RocksDB acquire is bounded
+            // and can throw, and only it is cheap when uncontended: LMDB's exclusiveLock() opens an
+            // environment-wide write transaction that cannot time out, so it stays lazy.
+            if (rootStore instanceof rocksdb_js_1.RocksDatabase)
+                exclusiveLock();
+            // it table already exists, get the split segments setting
+            if (splitSegments == undefined)
+                splitSegments = Table.splitSegments;
+            if (origin === 'cluster') {
+                const merged = Table.attributes.slice();
+                for (const attribute of attributes) {
+                    const existing = merged.find((existingAttribute) => existingAttribute.name === attribute.name);
+                    if (!existing) {
+                        merged.push(attribute);
+                        continue;
+                    }
+                    // Nodes that apply the same peer definitions in a different order keep different index sets, and
+                    // this warn is the only signal of it. An absent field and an explicit falsy one declare the same
+                    // thing, so neither direction of that pair is a difference.
+                    const discarded = PEER_DECLARABLE_FIELDS.filter((field) => (attribute[field] || existing[field]) &&
+                        JSON.stringify(attribute[field]) !== JSON.stringify(existing[field]));
+                    if (discarded.length > 0)
+                        logger.warn(`Ignoring peer redefinition of ${databaseName}.${tableName}.${attribute.name} (${discarded
+                            .map((field) => `${field}: local ${JSON.stringify(existing[field])}, peer ${JSON.stringify(attribute[field])}`)
+                            .join('; ')}); the local schema is authoritative`);
+                }
+                attributes = merged;
+            }
+            Table.attributes.splice(0, Table.attributes.length, ...attributes);
+            // Re-assert from the live declaration so a stale value on disk (replicated event,
+            // v4-era backfill) is corrected on every reload. Gated on `schemaDefinedExplicit` so
+            // callers that omit the flag (cluster schema-replication, data loader) don't flip a
+            // dynamic table to true via the default at the top of table(), and on origin so a
+            // peer-derived definition never overrides the local declaration.
+            if (schemaDefinedExplicit && origin !== 'cluster')
+                Table.schemaDefined = schemaDefined;
+            // Refresh class-level schema metadata to track docstring/directive changes across reloads.
+            Table.description = description;
+            Table.properties = properties;
+            Table.hidden = hidden;
+            // undefined means a non-schema caller (add_attribute, cluster schema events) — don't clobber
+            if (cacheControl !== undefined)
+                Table.cacheControl = cacheControl;
         }
         else {
-            attributesDbi = rootStore.dbisDb = rootStore.openDB(terms_ts_1.INTERNAL_DBIS_NAME, internalDbiInit);
-        }
-        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)
-        const existingTableMeta = attributesDbi.getSync(dbiName);
-        if (existingTableMeta && !existingTableMeta.dropping) {
-            // table was created while we were setting up
-            if (releaseExclusiveLock)
-                releaseExclusiveLock();
-            resetDatabases();
-            return table(tableDefinition);
-        }
-        let primaryStore;
-        try {
+            const auditStore = rootStore.auditStore;
+            primaryKeyAttribute = attributes.find((attribute) => attribute.isPrimaryKey) || {};
+            primaryKey = primaryKeyAttribute.name;
+            primaryKeyAttribute.isPrimaryKey = true;
+            primaryKeyAttribute.is_hash_attribute = true; // backward-compat: harperdb@4.x reads this field to open the DBI with correct flags
+            primaryKeyAttribute.schemaDefined = schemaDefined;
+            // Old readers treat every attribute row as live schema, so relationships stay on the ignored primary descriptor.
+            if (relationshipDefinitions)
+                primaryKeyAttribute.relationships = relationshipDefinitions;
+            // can't change compression after the fact (except threshold), so save only when we create the table
+            primaryKeyAttribute.compression = getDefaultCompression();
+            if (trackDeletes)
+                primaryKeyAttribute.trackDeletes = true;
+            audit = primaryKeyAttribute.audit = typeof audit === 'boolean' ? audit : (0, environmentManager_ts_1.get)(hdbTerms_ts_1.CONFIG_PARAMS.LOGGING_AUDITLOG);
+            if (expiration)
+                primaryKeyAttribute.expiration = expiration;
+            if (eviction)
+                primaryKeyAttribute.eviction = eviction;
+            // persist cacheControl so all threads (and future boots) see it; undefined callers inherit
+            // a descriptor value carried by cluster schema events; null (schema has no directive)
+            // clears a stale value the carried descriptor may hold
+            if (cacheControl === undefined)
+                cacheControl = primaryKeyAttribute.cacheControl;
+            else if (cacheControl === null)
+                delete primaryKeyAttribute.cacheControl;
+            else
+                primaryKeyAttribute.cacheControl = cacheControl;
+            splitSegments ??= false;
+            primaryKeyAttribute.splitSegments = splitSegments; // always default to not splitting segments going forward
+            if (typeof sealed === 'boolean')
+                primaryKeyAttribute.sealed = sealed;
+            if (typeof replicate === 'boolean')
+                primaryKeyAttribute.replicate = replicate;
+            // An explicit directive PINS this table's encoding: we persist the boolean, so later changes
+            // to the global storage.randomAccessFields default never affect this table. Tables WITHOUT the
+            // directive are intentionally not persisted here — they follow the current global default on
+            // each open (a runtime lever to flip encoding fleet-wide). Switching either way is safe: the
+            // struct READ hook always stays on and struct (0x20-0x3f) vs classic-record (0x40-0x7f) bytes
+            // are disjoint, so already-written records still decode; only the encoding of NEW writes changes.
+            if (typeof randomAccessFields === 'boolean')
+                primaryKeyAttribute.randomAccessFields = randomAccessFields;
+            if (origin) {
+                if (!primaryKeyAttribute.origins)
+                    primaryKeyAttribute.origins = [origin];
+                else if (!primaryKeyAttribute.origins.includes(origin))
+                    primaryKeyAttribute.origins.push(origin);
+            }
+            logger.trace(`${tableName} table loading, opening primary store`);
+            const dbiInit = createOpenDBIObject(false, true);
+            dbiInit.compression = primaryKeyAttribute.compression;
+            // per-table override of the storage.randomAccessFields default (see OpenDBIObject)
+            if (typeof primaryKeyAttribute.randomAccessFields === 'boolean')
+                dbiInit.randomAccessStructure = primaryKeyAttribute.randomAccessFields;
+            const dbiName = tableName + '/';
+            if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
+                attributesDbi = rootStore.dbisDb = openRocksDatabase(rootStore.path, {
+                    ...internalDbiInit,
+                    disableWAL: false,
+                    name: terms_ts_1.INTERNAL_DBIS_NAME,
+                });
+            }
+            else {
+                attributesDbi = rootStore.dbisDb = rootStore.openDB(terms_ts_1.INTERNAL_DBIS_NAME, internalDbiInit);
+            }
+            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)
+            const existingTableMeta = attributesDbi.getSync(dbiName);
+            if (existingTableMeta && !existingTableMeta.dropping) {
+                // table was created while we were setting up; the lock is not reentrant, so release
+                // before the recursive reload
+                releaseLock();
+                target.reload(databaseName);
+                return declareTable(target, tableDefinition);
+            }
+            let primaryStore;
             if (existingTableMeta?.dropping) {
                 // A previous drop of this table was interrupted after its tombstone
                 // was written. Complete it now (under the exclusive lock) so the
@@ -1621,15 +2391,20 @@ function table(tableDefinition) {
             else {
                 primaryStore = rootStore.openDB(dbiName, dbiInit);
             }
+            target.adopt(primaryStore);
+            unpublishedPrimaryStore = primaryStore;
             primaryStore = (0, RecordEncoder_ts_1.handleLocalTimeForGets)(primaryStore, rootStore);
-            rootStore.databaseName = databaseName;
+            // only a store no table has loaded yet is unnamed; a branch's store carries its own store
+            // identity here, which its blob roots resolve from, and must not take the logical name
+            rootStore.databaseName ??= databaseName;
             primaryStore.tableId = attributesDbi.getSync(NEXT_TABLE_ID);
             logger.trace(`Assigning new table id ${primaryStore.tableId} for ${tableName}`);
             if (!primaryStore.tableId)
                 primaryStore.tableId = 1;
             attributesDbi.put(NEXT_TABLE_ID, primaryStore.tableId + 1);
             primaryKeyAttribute.tableId = primaryStore.tableId;
-            Table = setTable(tables, tableName, (0, Table_ts_1.makeTable)({
+            Table = (0, Table_ts_1.makeTable)({
+                isBranch: Boolean(target.branch),
                 primaryStore,
                 auditStore,
                 audit,
@@ -1652,96 +2427,99 @@ function table(tableDefinition) {
                 properties,
                 hidden,
                 cacheControl,
-            }));
+            });
             Table.schemaVersion = 1;
             hasChanges = true;
-            attributesDbi.put(dbiName, primaryKeyAttribute);
-        }
-        catch (error) {
-            // A failure while opening/creating the column family or writing the
-            // table id / catalog entry (e.g. into an env poisoned by a prior
-            // dangling column family) must NOT leak the exclusive
-            // 'update-attributes' spin lock. If it leaks, every subsequent
-            // create_table / attribute update on this database spins forever
-            // (a hard wedge that pins a worker at 100% CPU). Release before rethrow.
-            if (releaseExclusiveLock)
-                releaseExclusiveLock();
-            throw error;
+            deferredPrimaryRow = primaryKeyAttribute;
         }
-    }
-    const indices = Table.indices;
-    if (!attributesDbi) {
-        if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
-            rootStore.dbisDb = openRocksDatabase(rootStore.path, {
-                ...internalDbiInit,
-                disableWAL: false,
-                name: terms_ts_1.INTERNAL_DBIS_NAME,
-            });
-        }
-        else {
-            rootStore.dbisDb = rootStore.openDB(terms_ts_1.INTERNAL_DBIS_NAME, internalDbiInit);
-        }
-        attributesDbi = markInternalDbiNonVersioned(rootStore.dbisDb);
-    }
-    Table.dbisDB = attributesDbi;
-    const indicesToRemove = [];
-    for (const { key, value } of attributesDbi.getRange({ start: true })) {
-        if (value == null)
-            continue;
-        let [attributeTableName, attribute_name] = key.toString().split('/');
-        if (attribute_name === '')
-            attribute_name = value.name; // primary key
-        if (attribute_name) {
-            if (attributeTableName !== tableName)
+        const indices = Table.indices;
+        if (!attributesDbi) {
+            if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
+                rootStore.dbisDb = openRocksDatabase(rootStore.path, {
+                    ...internalDbiInit,
+                    disableWAL: false,
+                    name: terms_ts_1.INTERNAL_DBIS_NAME,
+                });
+            }
+            else {
+                rootStore.dbisDb = rootStore.openDB(terms_ts_1.INTERNAL_DBIS_NAME, internalDbiInit);
+            }
+            target.adopt(rootStore.dbisDb);
+            attributesDbi = markInternalDbiNonVersioned(rootStore.dbisDb);
+        }
+        Table.dbisDB = attributesDbi;
+        // A cluster-origin list can miss a descriptor another thread committed moments ago, so removal
+        // reconciliation is reserved for local schema authoring; on a create the rows can only be aborted state.
+        const reconcileRemovals = origin !== 'cluster' || Boolean(deferredPrimaryRow);
+        for (const { key, value } of reconcileRemovals
+            ? attributesDbi.getRange({ start: tableName + '/', end: tableName + '0' })
+            : []) {
+            if (value == null)
+                continue;
+            let [attributeTableName, attribute_name] = key.toString().split('/');
+            if (attribute_name === '')
+                attribute_name = value.name; // primary key
+            if (attribute_name) {
+                if (attributeTableName !== tableName)
+                    continue;
+            }
+            else {
+                // table attribute for a table with no primary key, we don't want to remove this, so continue on
                 continue;
-        }
-        else {
-            // table attribute for a table with no primary key, we don't want to remove this, so continue on
-            continue;
-        }
-        const attribute = attributes.find((attribute) => attribute.name === attribute_name);
-        const removeIndex = !attribute?.indexed && value.indexed && !value.isPrimaryKey;
-        if (!attribute || removeIndex) {
-            exclusiveLock();
-            hasChanges = true;
-            if (!attribute)
-                attributesDbi.remove(key);
-            if (removeIndex) {
-                const indexDbi = Table.indices[attributeTableName];
-                if (indexDbi)
-                    indicesToRemove.push(indexDbi);
+            }
+            const attribute = attributes.find((attribute) => attribute.name === attribute_name);
+            const removeIndex = !attribute?.indexed && value.indexed && !value.isPrimaryKey;
+            // rows already present under a create are aborted state
+            const staleRow = !attribute || Boolean(deferredPrimaryRow);
+            if (staleRow || removeIndex) {
+                exclusiveLock();
+                hasChanges = true;
+                if (staleRow)
+                    attributesDbi.remove(key);
+                if (removeIndex) {
+                    const indexDbi = Table.indices[attributeTableName];
+                    if (indexDbi)
+                        indicesToRemove.push(indexDbi);
+                }
             }
         }
-    }
-    const attributesToIndex = [];
-    try {
         // TODO: If we have attributes and the schemaDefined flag is not set, turn it on
         // iterate through the attributes to ensure that we have all the dbis created and indexed
         for (const attribute of attributes || []) {
-            if (attribute.relationship || attribute.computed) {
-                hasChanges = true; // need to update the table so the computed properties are translated to property resolvers
-                if (attribute.relationship)
-                    continue;
+            if (attribute.relationship) {
+                refreshRelationshipAttributes = true;
+                continue;
             }
+            if (attribute.computed)
+                hasChanges = true;
             let dbiKey = tableName + '/' + (attribute.name || '');
             Object.defineProperty(attribute, 'key', { value: dbiKey, configurable: true });
             let attributeDescriptor = attributesDbi.getSync(dbiKey);
             if (attribute.isPrimaryKey) {
+                if (deferredPrimaryRow)
+                    continue;
                 attributeDescriptor = attributeDescriptor || attributesDbi.getSync((dbiKey = tableName + '/')) || {};
                 // Persist schemaDefined when the explicit live value disagrees with disk. Without this,
                 // a stale `false` (from a v4-era write or replicated event) survives every reload: the
                 // in-memory re-assert in the existing-Table branch only fixes the worker that ran @table,
-                // but other workers' next disk-load re-reads the stale value.
+                // but other workers' next disk-load re-reads the stale value. The whole settings update is
+                // gated off for cluster-origin callers: their values come from this worker's (possibly
+                // stale) snapshot, so a rewrite could revert a newer local declaration already on disk.
                 const schemaDefinedMismatch = schemaDefinedExplicit && attributeDescriptor.schemaDefined !== schemaDefined;
                 // primary key can't change indexing, but settings can change
-                if (schemaDefinedMismatch ||
-                    (audit !== undefined && audit !== Table.audit) ||
-                    (sealed !== undefined && sealed !== Table.sealed) ||
-                    (replicate !== undefined && replicate !== Table.replicate) ||
-                    (+expiration || undefined) !== (+attributeDescriptor.expiration || undefined) ||
-                    (+eviction || undefined) !== (+attributeDescriptor.eviction || undefined) ||
-                    attribute.type !== attributeDescriptor.type) {
-                    const updatedPrimaryAttribute = { ...attributeDescriptor };
+                if (origin !== 'cluster' &&
+                    (schemaDefinedMismatch ||
+                        (audit !== undefined && audit !== Table.audit) ||
+                        (sealed !== undefined && sealed !== Table.sealed) ||
+                        (replicate !== undefined && replicate !== Table.replicate) ||
+                        (+expiration || undefined) !== (+attributeDescriptor.expiration || undefined) ||
+                        (+eviction || undefined) !== (+attributeDescriptor.eviction || undefined) ||
+                        attribute.type !== attributeDescriptor.type)) {
+                    exclusiveLock();
+                    const currentPrimaryAttribute = attributesDbi.getSync(dbiKey);
+                    if (!currentPrimaryAttribute || tableIsDropping(currentPrimaryAttribute, dbiKey))
+                        continue;
+                    const updatedPrimaryAttribute = { ...currentPrimaryAttribute };
                     if (typeof audit === 'boolean') {
                         if (audit)
                             Table.enableAuditing();
@@ -1760,14 +2538,52 @@ function table(tableDefinition) {
                     if (schemaDefinedMismatch)
                         updatedPrimaryAttribute.schemaDefined = schemaDefined;
                     hasChanges = true; // send out notification of the change
-                    exclusiveLock();
                     attributesDbi.put(dbiKey, updatedPrimaryAttribute);
                 }
                 continue;
             }
-            // note that non-indexed attributes do not need a dbi
             if (attributeDescriptor?.attribute && !attributeDescriptor.name)
                 attributeDescriptor.indexed = true; // legacy descriptor
+            if (origin === 'cluster' && attributeDescriptor) {
+                // An existing descriptor is a local declaration this caller may not have seen yet, so it wins
+                // over the incoming definition and is never written back from it.
+                applyDurableDeclaration(attribute, attributeDescriptor);
+                const abandonedIndexBuild = attribute.indexed &&
+                    (attributeDescriptor.indexingFailed ||
+                        (attributeDescriptor.indexingPID && attributeDescriptor.indexingPID !== process.pid) ||
+                        attributeDescriptor.restartNumber < (worker_threads_1.workerData?.restartNumber ?? manageThreads.restartNumber));
+                if (abandonedIndexBuild) {
+                    // Recovery is the exception to skipping the handling below, because without it `isIndexing`
+                    // stays pinned on with nothing left to clear it and every query on the attribute fails with
+                    // IndexRebuildingError for the life of the worker. It persists the attribute (here and again
+                    // from runIndexing), so restate the declaration from a descriptor read under the lock.
+                    exclusiveLock();
+                    applyDurableDeclaration(attribute, attributesDbi.getSync(dbiKey) ?? attributeDescriptor);
+                }
+                else {
+                    if (attribute.indexed) {
+                        const dbi = openIndex(dbiKey, rootStore, attribute);
+                        target.adopt(dbi);
+                        // Persisting the indexFormat openIndex just resolved adds a field the descriptor lacks
+                        // rather than rewriting one it has. Without it an empty index resolves 'versioned', writes
+                        // versioned nodes, then re-derives 'legacy' on the next load — see indexFormatNeedsPersist.
+                        if (attribute.indexFormat != null && attributeDescriptor.indexFormat == null) {
+                            exclusiveLock();
+                            const durableDescriptor = attributesDbi.getSync(dbiKey);
+                            if (durableDescriptor && durableDescriptor.indexFormat == null) {
+                                hasChanges = true;
+                                attributesDbi.put(dbiKey, { ...durableDescriptor, indexFormat: attribute.indexFormat });
+                            }
+                        }
+                        if (attributeDescriptor.indexingPID)
+                            dbi.isIndexing = true;
+                        dbi.indexNulls = attribute.indexNulls;
+                        indices[attribute.name] = dbi;
+                    }
+                    continue;
+                }
+            }
+            // note that non-indexed attributes do not need a dbi
             // Some index options affect only search, not the stored structure (e.g. HNSW's
             // efConstructionSearch). Changing those should persist the new metadata but NOT trigger a
             // reindex. A custom index declares such keys via a static `searchOnlyOptions`.
@@ -1810,6 +2626,9 @@ function table(tableDefinition) {
                 // on the main thread, where workerData is undefined (and it is initialized to 1).
                 const currentRestartGeneration = worker_threads_1.workerData?.restartNumber ?? manageThreads.restartNumber;
                 const dbi = openIndex(dbiKey, rootStore, attribute);
+                target.adopt(dbi);
+                if (deferredPrimaryRow)
+                    indices[attribute.name] = dbi; // private until published; lets the rollback close it
                 // openIndex resolves and stamps attribute.indexFormat for a versioned-capable (RocksDB
                 // custom-object) index. An index created before this field existed has no indexFormat on
                 // disk; persist the resolved value now — even when nothing else changed — so the format is
@@ -1821,13 +2640,15 @@ function table(tableDefinition) {
                 if (changed ||
                     indexFormatNeedsPersist ||
                     attributeDescriptor?.indexingFailed ||
-                    isAbandonedIndexBuild(attributeDescriptor, currentRestartGeneration)) {
+                    (attributeDescriptor?.indexingPID && attributeDescriptor?.indexingPID !== process.pid) ||
+                    attributeDescriptor?.restartNumber < currentRestartGeneration) {
                     hasChanges = true;
                     exclusiveLock();
                     attributeDescriptor = attributesDbi.getSync(dbiKey);
                     if (structurallyChanged ||
                         attributeDescriptor?.indexingFailed ||
-                        isAbandonedIndexBuild(attributeDescriptor, currentRestartGeneration)) {
+                        (attributeDescriptor?.indexingPID && attributeDescriptor?.indexingPID !== process.pid) ||
+                        attributeDescriptor?.restartNumber < currentRestartGeneration) {
                         hasChanges = true;
                         if (attribute.indexNulls === undefined)
                             attribute.indexNulls = true;
@@ -1846,17 +2667,9 @@ function table(tableDefinition) {
                             // representation-only option difference — preserve the checkpoint so the backfill
                             // resumes rather than restarts. Canonicalized to match structurallyChanged above.
                             const indexOptionsChanged = canonicalIndexKey(attributeDescriptor?.indexed) !== canonicalIndexKey(attribute.indexed);
-                            // Only a checkpoint runIndexing stamped with its own key resumes: earlier releases advanced
-                            // lastIndexedKey past failed and unflushed index writes, so any other is a full rebuild.
-                            const uncertifiedCheckpoint = attributeDescriptor?.lastIndexedKey !== undefined &&
-                                (attributeDescriptor.checkpointCertified === undefined ||
-                                    (0, lmdb_1.compareKeys)(attributeDescriptor.checkpointCertified, attributeDescriptor.lastIndexedKey) !== 0);
-                            attribute.lastIndexedKey =
-                                indexOptionsChanged || uncertifiedCheckpoint
-                                    ? undefined
-                                    : (attributeDescriptor?.lastIndexedKey ?? undefined);
-                            if (attribute.lastIndexedKey !== undefined)
-                                attribute.checkpointCertified = attribute.lastIndexedKey;
+                            attribute.lastIndexedKey = indexOptionsChanged
+                                ? undefined
+                                : (attributeDescriptor?.lastIndexedKey ?? undefined);
                             // Explicit reindex is the upgrade path from a legacy (un-versioned) custom-index
                             // object store to the versioned, VT-cacheable format. A full rebuild from scratch
                             // (lastIndexedKey === undefined) clears the store and rewrites every node, so the
@@ -1878,9 +2691,6 @@ function table(tableDefinition) {
                             // the new process reuses the old PID. Cleared on clean completion; left in place
                             // on failure/crash so the next, higher-numbered restart re-triggers the backfill.
                             attribute.restartNumber = currentRestartGeneration;
-                            if (manageThreads.processIncarnation != null)
-                                attribute.indexingIncarnation = manageThreads.processIncarnation;
-                            attribute.indexingBuildId = (0, node_crypto_1.randomBytes)(8).toString('hex');
                             delete attribute.indexingFailed; // clear failure flag for the new run
                             dbi.isIndexing = true;
                             Object.defineProperty(attribute, 'dbi', { value: dbi, configurable: true, enumerable: false });
@@ -1896,12 +2706,6 @@ function table(tableDefinition) {
                                 reindexReasons.push(`crash-recovery(pid=${attributeDescriptor.indexingPID})`);
                             if (attributeDescriptor?.restartNumber < currentRestartGeneration)
                                 reindexReasons.push('restart-number');
-                            if (uncertifiedCheckpoint)
-                                reindexReasons.push('uncertified-checkpoint');
-                            if (attributeDescriptor?.indexingPID === process.pid &&
-                                manageThreads.processIncarnation != null &&
-                                attributeDescriptor.indexingIncarnation !== manageThreads.processIncarnation)
-                                reindexReasons.push('abandoned-build(previous process incarnation)');
                             logger.info(`reindex ${databaseName}.${tableName}.${attribute.name}: reason=${reindexReasons.join(',') || 'unknown'}`);
                             // we only set indexing nulls to true if new or reindexing, we can't have partial indexing of null
                             attributesToIndex.push(attribute);
@@ -1914,13 +2718,9 @@ function table(tableDefinition) {
                         // workers / a reload would treat the still-partial index as ready and return incomplete results.
                         attribute.indexingPID = attributeDescriptor.indexingPID;
                         attribute.lastIndexedKey = attributeDescriptor.lastIndexedKey;
-                        if (attributeDescriptor.checkpointCertified !== undefined)
-                            attribute.checkpointCertified = attributeDescriptor.checkpointCertified;
                         // Carry the in-progress restart generation too, so persisting this metadata-only
                         // change doesn't drop it and break the crash-recovery trigger for the running backfill.
                         attribute.restartNumber = attributeDescriptor.restartNumber;
-                        attribute.indexingIncarnation = attributeDescriptor.indexingIncarnation;
-                        attribute.indexingBuildId = attributeDescriptor.indexingBuildId;
                         if (attributeDescriptor.indexingFailed)
                             attribute.indexingFailed = attributeDescriptor.indexingFailed;
                     }
@@ -1943,26 +2743,61 @@ function table(tableDefinition) {
                 attributesDbi.put(dbiKey, attribute);
             }
         }
+        // The primary row is what makes a table loadable, so it lands last: a scan on another thread that
+        // runs mid-create skips the table instead of building (and announcing) a partial one. It already
+        // carries this table's relationships (set on primaryKeyAttribute above), so the persistence block
+        // below is a no-op for a create — a table is never published with an incomplete relationship list.
+        if (deferredPrimaryRow) {
+            attributesDbi.put(tableName + '/', deferredPrimaryRow);
+            // That write, not the registration below, is the publish point: it is durable from here
+            // (on LMDB releaseLock()'s finally commits this create's write transaction even while an
+            // error unwinds), so any later throw must leave the catalog alone. Rolling back past it
+            // would delete the attribute rows out from under a live primary row and leave every
+            // thread loading the primary-only schema this change exists to prevent.
+            published = true;
+            setTable(tables, tableName, Table);
+        }
+        // a table with no declared primary key has no attribute row to carry relationships, and the
+        // loop above never visits its descriptor
+        if (relationshipDefinitions) {
+            const relationshipsKey = primaryDescriptorKey();
+            if (!relationshipListsEqual(attributesDbi.getSync(relationshipsKey)?.relationships, relationshipDefinitions)) {
+                exclusiveLock();
+                const currentPrimaryAttribute = attributesDbi.getSync(relationshipsKey);
+                // a missing row means a concurrent drop completed; writing one back would resurrect the table
+                if (currentPrimaryAttribute &&
+                    !tableIsDropping(currentPrimaryAttribute, relationshipsKey) &&
+                    !relationshipListsEqual(currentPrimaryAttribute.relationships, relationshipDefinitions)) {
+                    attributesDbi.put(relationshipsKey, { ...currentPrimaryAttribute, relationships: relationshipDefinitions });
+                    hasChanges = true;
+                }
+            }
+        }
+    }
+    catch (error) {
+        if (unpublishedPrimaryStore && !published)
+            discardUnpublishedTable();
+        else if (published && tables[tableName] !== Table)
+            discardUnregisteredClass();
+        throw error;
     }
     finally {
-        if (releaseExclusiveLock)
-            releaseExclusiveLock();
+        releaseLock();
     }
-    if (hasChanges) {
+    if (hasChanges || refreshRelationshipAttributes) {
         Table.schemaVersion++;
         Table.updatedAttributes();
     }
     logger.trace(`${tableName} table loading, running index`);
+    const branchPath = target.branch?.path;
     if (attributesToIndex.length > 0 || indicesToRemove.length > 0) {
-        // captured before the backfill can rewrite the attributes
-        const buildIds = new Map(attributesToIndex.map((attribute) => [attribute, attribute.indexingBuildId]));
-        const markSettled = () => markAbandonedIndexBuild(Table, rootStore, buildIds);
-        Table.indexingOperation = runIndexing(Table, attributesToIndex, indicesToRemove).then(markSettled, markSettled);
+        Table.indexingOperation = runIndexing(Table, attributesToIndex, indicesToRemove, branchPath);
     }
     else if (hasChanges)
-        signalling.signalSchemaChange(new itc_js_1.SchemaEventMsg(process.pid, 'schema-change', Table.databaseName, Table.tableName));
+        signalling.signalSchemaChange(new itc_js_1.SchemaEventMsg(process.pid, 'schema-change', Table.databaseName, Table.tableName, undefined, branchPath));
     Table.origin = origin;
-    if (hasChanges) {
+    // scope-private: replication and other global subscribers must not learn of a branch class
+    if ((hasChanges || refreshRelationshipAttributes) && !target.branch) {
         exports.databaseEventsEmitter.emit('updateTable', Table, origin !== 'cluster');
     }
     if (expiration || eviction || scanInterval)
@@ -1973,15 +2808,68 @@ function table(tableDefinition) {
         });
     logger.trace(`${tableName} table loaded`);
     return Table;
+    // dropTable() tombstones the bare table row, which is not the row a legacy catalog keeps the
+    // table's settings in, so a drop in flight has to be checked on both.
+    function tableIsDropping(descriptor, descriptorKey) {
+        if (descriptor?.dropping)
+            return true;
+        return descriptorKey !== tableName + '/' && attributesDbi.getSync(tableName + '/')?.dropping;
+    }
+    // The catalog row initStores() reads a table's settings from: the primary key's own row when it
+    // has one, and the bare table row otherwise.
+    function primaryDescriptorKey() {
+        const declaredPrimaryKey = attributes?.find((attribute) => attribute.isPrimaryKey)?.name;
+        if (declaredPrimaryKey) {
+            const attributeKey = tableName + '/' + declaredPrimaryKey;
+            if (attributesDbi.getSync(attributeKey))
+                return attributeKey;
+        }
+        return tableName + '/';
+    }
+    // The catalog of a published table stays, but a class the registration never accepted is
+    // unreachable, so release what makeTable() registered process-wide instead of leaving its timers
+    // and reclamation handler live for the process. The stores stay open: the table is durable, and
+    // whichever scan reloads it opens its own handles.
+    function discardUnregisteredClass() {
+        try {
+            Table.cleanup();
+        }
+        catch (discardError) {
+            logger.warn(`Error releasing the unregistered class of ${databaseName}.${tableName}`, discardError);
+        }
+    }
+    function discardUnpublishedTable() {
+        const discard = (description, action) => {
+            try {
+                action();
+            }
+            catch (discardError) {
+                logger.warn(`Error discarding ${description} of the failed create of ${databaseName}.${tableName}`, discardError);
+            }
+        };
+        discard('catalog rows', () => {
+            for (const attribute of attributes) {
+                if (!attribute.isPrimaryKey && !attribute.relationship)
+                    attributesDbi.remove(tableName + '/' + attribute.name);
+            }
+        });
+        if (Table)
+            discard('callbacks', () => Table.cleanup());
+        // an LMDB store is a per-environment handle slot shared with every thread and still inside this
+        // create's write transaction; only RocksDB column-family handles hold native state to release
+        if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
+            for (const indexName in Table?.indices ?? {})
+                discard(`index ${indexName}`, () => Table.indices[indexName].close());
+            discard('primary store', () => unpublishedPrimaryStore.close());
+        }
+    }
     // Acquire an exclusive lock for attribute updates
     function exclusiveLock() {
         if (releaseExclusiveLock)
             return;
         if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
-            while (!rootStore.tryLock('update-attributes')) { } // use a spin lock, we really need an synchronous exclusive lock here
-            releaseExclusiveLock = () => {
-                rootStore.unlock('update-attributes');
-            };
+            (0, Table_ts_1.acquireUpdateAttributesLock)(rootStore, `table '${databaseName}.${tableName}'`);
+            releaseExclusiveLock = () => (0, Table_ts_1.releaseUpdateAttributesLock)(rootStore);
         }
         else {
             // we only need an exclusive transaction lock in lmdb
@@ -1994,6 +2882,14 @@ function table(tableDefinition) {
             });
         }
     }
+    // idempotent: the early release before the recursive reload and the finally both run, and a
+    // second unlock could release another thread's lock
+    function releaseLock() {
+        const release = releaseExclusiveLock;
+        releaseExclusiveLock = undefined;
+        if (release)
+            release();
+    }
 }
 /**
  * Canonical form used ONLY for the structural (reindex-triggering) comparison of index options.
@@ -2031,163 +2927,28 @@ function canonicalizeIndexOptions(value) {
 }
 const MAX_OUTSTANDING_INDEXING = 1000;
 const MIN_OUTSTANDING_INDEXING = 10;
-const INDEXING_YIELD_INTERVAL = 100;
-// A resumable checkpoint is written only after a flush (see flushIndexStores), at most once per period
-// and never before this many more records: the flush seals every column family in the database, so a
-// slow backfill must not impose the period's flush rate on unrelated tables.
-let indexingCheckpointPeriodMs = 5000;
-let indexingCheckpointMinRecords = 10000;
-function setIndexingCheckpointPeriod(ms, minRecords = indexingCheckpointMinRecords) {
-    const previous = { ms: indexingCheckpointPeriodMs, minRecords: indexingCheckpointMinRecords };
-    indexingCheckpointPeriodMs = ms;
-    indexingCheckpointMinRecords = minRecords;
-    return previous;
-}
-const yieldEventTurn = () => new Promise((resolve) => setImmediate(resolve));
-// RocksDB index stores have no WAL (openRocksDatabase defaults disableWAL), so a flush is what makes the
-// entries a checkpoint certifies durable. A flush only covers writes issued before it started, so a caller
-// never joins one in flight: it joins the next one, which every backfill on that database asking meanwhile
-// shares — at most one in flight and one queued.
-const indexingFlushes = new WeakMap();
-function flushIndexStores(rootStore) {
-    if (!(rootStore instanceof rocksdb_js_1.RocksDatabase))
-        return;
-    let flushes = indexingFlushes.get(rootStore);
-    if (!flushes)
-        indexingFlushes.set(rootStore, (flushes = {}));
-    if (flushes.queued)
-        return flushes.queued;
-    const start = () => {
-        flushes.queued = undefined;
-        const flush = rootStore.flush().finally(() => {
-            if (flushes.inFlight === flush)
-                flushes.inFlight = undefined;
-        });
-        flushes.inFlight = flush;
-        return flush;
-    };
-    if (!flushes.inFlight)
-        return start();
-    return (flushes.queued = flushes.inFlight.then(start, start));
-}
-function resumeStartKey(attributes) {
-    let start;
-    for (const attribute of attributes) {
-        if (attribute.lastIndexedKey == undefined)
-            return undefined;
-        if (start === undefined || (0, lmdb_1.compareKeys)(attribute.lastIndexedKey, start) < 0)
-            start = attribute.lastIndexedKey;
-    }
-    return start;
-}
-// Bounded, unlike the exclusiveLock() spin above: that one runs on the declaring path, where the
-// caller is waiting on the result and there is nothing useful to do without the lock. This one runs
-// after a backfill has already settled, so a holder that never releases would wedge the worker's
-// event loop for nothing. Giving up costs only the marker, and the next load of the table
-// re-triggers the build regardless.
-exports.ABANDONED_MARK_LOCK_TIMEOUT = 10000;
-const abandonedMarkLockWait = new Int32Array(new SharedArrayBuffer(4));
-// `timeout` is the test seam; production callers take the default.
-function tryAcquireUpdateAttributesLock(rootStore, timeout = exports.ABANDONED_MARK_LOCK_TIMEOUT) {
-    if (rootStore.tryLock('update-attributes'))
-        return true;
-    const startTime = performance.now();
-    let waitTime = 1;
-    while (!rootStore.tryLock('update-attributes')) {
-        const elapsed = performance.now() - startTime;
-        if (elapsed >= timeout)
-            return false;
-        // Atomics.wait rather than a busy spin: the section this guards is synchronous, so the wait
-        // blocks this thread either way, but sleeping does not burn a core while it does.
-        if (elapsed >= 2) {
-            Atomics.wait(abandonedMarkLockWait, 0, 0, Math.min(waitTime, timeout - elapsed));
-            if (waitTime < 16)
-                waitTime *= 2;
-        }
-    }
-    return true;
-}
-/**
- * Persists the failure marker for a build that ended without running one of runIndexing's own exit
- * paths, so something re-triggers it. Fenced on `indexingBuildId` inside the storage engine's catalog
- * serialization boundary, because a replacement generation (or another thread declaring different index
- * options) can claim the attribute before an outgoing build's promise settles, and marking that would fail
- * a live build. The fence read and write stay synchronous, and nothing here may throw because
- * `Table.indexingOperation` reaches operations-API callers.
- */
-async function markAbandonedIndexBuild(Table, rootStore, buildIds) {
-    for (const [attribute, buildId] of buildIds) {
-        try {
-            let marked;
-            if (buildId == null || Table.dbisDB.getSync(attribute.key)?.indexingBuildId !== buildId)
-                continue;
-            const markIfOwned = () => {
-                const descriptor = Table.dbisDB.getSync(attribute.key);
-                if (descriptor?.indexingBuildId === buildId && !descriptor.indexingFailed) {
-                    Table.dbisDB.putSync(attribute.key, { ...descriptor, indexingFailed: true });
-                    marked = true;
-                }
-            };
-            if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
-                if (!tryAcquireUpdateAttributesLock(rootStore)) {
-                    logger.warn(`Could not mark the abandoned index build of ${Table.databaseName}.${Table.tableName}.${attribute.name}: ` +
-                        `timed out after ${exports.ABANDONED_MARK_LOCK_TIMEOUT}ms waiting for the exclusive 'update-attributes' lock. ` +
-                        `The index stays incomplete and the next load of the table re-triggers the backfill.`);
-                    continue;
-                }
-                try {
-                    markIfOwned();
-                }
-                finally {
-                    rootStore.unlock('update-attributes');
-                }
-            }
-            else {
-                rootStore.transactionSync(markIfOwned);
-            }
-            if (marked)
-                logger.warn(`Indexing of ${Table.databaseName}.${Table.tableName}.${attribute.name} ended without completing. ` +
-                    `The index stays incomplete and every query on the attribute reports it as not indexed yet; ` +
-                    `the next load of the table retries the backfill from the last checkpoint (indexingFailed=true).`);
-        }
-        catch (error) {
-            // A store closed by shutdown is the common case, and it cannot be written to at all.
-            try {
-                logger.debug(`Could not mark the abandoned index build of ${Table.tableName}.${attribute.name}`, error);
-            }
-            catch { }
-        }
-    }
-}
-async function runIndexing(Table, attributes, indicesToRemove) {
-    let checkpointing;
-    let hadIndexingErrors = false;
-    const attributeErrorReported = {};
-    const onIndexPutRejected = (property, error) => {
-        hadIndexingErrors = true;
-        if (attributeErrorReported[property])
-            return;
-        attributeErrorReported[property] = true;
-        logger.error(`Error indexing attribute ${property}`, error);
-    };
-    const putRejectionHandlers = attributes.map((attribute) => (error) => onIndexPutRejected(attribute.name, error));
+async function runIndexing(Table, attributes, indicesToRemove, branchPath) {
     try {
         logger.info(`Indexing ${Table.tableName} attributes`, attributes);
-        await signalling.signalSchemaChange(new itc_js_1.SchemaEventMsg(process.pid, 'schema-change', Table.databaseName, Table.tableName));
+        await signalling.signalSchemaChange(new itc_js_1.SchemaEventMsg(process.pid, 'schema-change', Table.databaseName, Table.tableName, undefined, branchPath));
         let lastResolution;
         for (const index of indicesToRemove) {
             lastResolution = index.drop();
-            if (lastResolution?.then)
-                lastResolution.then(undefined, (error) => onIndexPutRejected(index.name, error));
         }
         let interrupted;
+        let hadIndexingErrors = false;
+        const attributeErrorReported = {};
         let indexed = 0;
         const attributesLength = attributes.length;
         await new Promise((resolve) => setImmediate(resolve)); // yield event turn, indexing should consistently take at least one event turn
         if (attributesLength > 0) {
-            const start = resumeStartKey(attributes);
-            if (start === undefined) {
-                for (const attribute of attributes) {
+            let start;
+            for (const attribute of attributes) {
+                // if we are resuming, we need to start from the last key we indexed by all attributes
+                if ((0, lmdb_1.compareKeys)(attribute.lastIndexedKey, start) < 0)
+                    start = attribute.lastIndexedKey;
+                if (attribute.lastIndexedKey == undefined) {
+                    // if we are starting from the beginning, clear out any previous index entries since we are rewriting
                     if (attribute.dbi.clearAsync) {
                         // LMDB, note that we don't need to wait for this to complete, just gets enqueued in front of the other writes
                         attribute.dbi.clearAsync();
@@ -2198,28 +2959,6 @@ async function runIndexing(Table, attributes, indicesToRemove) {
                 }
             }
             let outstanding = 0;
-            // A resumed scan starts at the checkpoint, so it must only name a key whose every predecessor is
-            // durably indexed: persisted once the writes it covers have settled and flushed, frozen after any
-            // record fails so the retry re-covers it, and stamped with its own key (see the trigger in table()).
-            const persistCheckpoint = async (key) => {
-                if (hadIndexingErrors)
-                    return;
-                try {
-                    await flushIndexStores(Table.primaryStore.rootStore);
-                    const puts = [];
-                    for (const attribute of attributes) {
-                        attribute.lastIndexedKey = key;
-                        attribute.checkpointCertified = key;
-                        puts.push(Table.dbisDB.put(attribute.key, attribute));
-                    }
-                    await Promise.all(puts);
-                }
-                catch (error) {
-                    logger.warn(`Could not persist the indexing checkpoint for ${Table.tableName}`, error);
-                }
-            };
-            let nextCheckpointAt = performance.now() + indexingCheckpointPeriodMs;
-            let nextCheckpointRecord = indexingCheckpointMinRecords;
             // this means that a new attribute has been introduced that needs to be indexed
             for (const { key, value: record } of Table.primaryStore.getRange({
                 start,
@@ -2227,7 +2966,8 @@ async function runIndexing(Table, attributes, indicesToRemove) {
                 versions: true,
                 snapshot: false, // don't hold a read transaction this whole time
             })) {
-                const atInterval = ++indexed % INDEXING_YIELD_INTERVAL === 0;
+                if (!record)
+                    continue; // deletion entry
                 // TODO: Do we ever need to interrupt due to a schema change that was not a restart?
                 //if (Table.schemaVersion !== schemaVersion) return; // break out if there are any schema changes and let someone else pick it up
                 outstanding++;
@@ -2239,75 +2979,72 @@ async function runIndexing(Table, attributes, indicesToRemove) {
                 // we index, that's fine because indexing is idempotent, we can just put the same values again. If it changes
                 // during the indexing, the indexing here will fail. This is also fine because it means the other thread will have
                 // performed indexing and we don't need to do anything further
-                if (record) {
-                    for (let i = 0; i < attributesLength; i++) {
-                        const attribute = attributes[i];
-                        const property = attribute.name;
-                        const index = attribute.dbi;
-                        const onPutRejected = putRejectionHandlers[i];
-                        try {
-                            const resolver = attribute.resolve;
-                            const value = record && (resolver ? resolver(record) : record[property]);
-                            if (index.customIndex) {
-                                index.customIndex.index(key, value);
-                                didSynchronousIndexing = true;
-                                continue;
-                            }
-                            const values = (0, commonUtility_ts_1.getIndexedValues)(value, index.indexNulls);
-                            if (values) {
-                                for (let i = 0, l = values.length; i < l; i++) {
-                                    lastResolution = index.put(values[i], key);
-                                    if (lastResolution?.then)
-                                        lastResolution.then(undefined, onPutRejected);
-                                }
-                            }
+                for (let i = 0; i < attributesLength; i++) {
+                    const attribute = attributes[i];
+                    const property = attribute.name;
+                    const index = attribute.dbi;
+                    try {
+                        const resolver = attribute.resolve;
+                        const value = record && (resolver ? resolver(record) : record[property]);
+                        if (index.customIndex) {
+                            index.customIndex.index(key, value);
+                            didSynchronousIndexing = true;
+                            continue;
                         }
-                        catch (error) {
-                            hadIndexingErrors = true;
-                            if (!attributeErrorReported[property]) {
-                                // just report an indexing error once per attribute so we don't spam the logs.
-                                // A store closed by worker shutdown surfaces here as "Database not open"; that is
-                                // a benign interruption (the next generation re-runs the backfill), so don't log
-                                // it as an error — the outer catch returns quietly once the iterator also throws.
-                                attributeErrorReported[property] = true;
-                                if (Table.primaryStore?.rootStore?.status === 'closed')
-                                    logger.debug(`Indexing attribute ${property} interrupted by store shutdown`, error);
-                                else
-                                    logger.error(`Error indexing attribute ${property}`, error);
+                        const values = (0, commonUtility_ts_1.getIndexedValues)(value, index.indexNulls);
+                        if (values) {
+                            for (let i = 0, l = values.length; i < l; i++) {
+                                lastResolution = index.put(values[i], key);
                             }
                         }
                     }
+                    catch (error) {
+                        hadIndexingErrors = true;
+                        if (!attributeErrorReported[property]) {
+                            // just report an indexing error once per attribute so we don't spam the logs.
+                            // A store closed by worker shutdown surfaces here as "Database not open"; that is
+                            // a benign interruption (the next generation re-runs the backfill), so don't log
+                            // it as an error — the outer catch returns quietly once the iterator also throws.
+                            attributeErrorReported[property] = true;
+                            if (Table.primaryStore?.rootStore?.status === 'closed')
+                                logger.debug(`Indexing attribute ${property} interrupted by store shutdown`, error);
+                            else
+                                logger.error(`Error indexing attribute ${property}`, error);
+                        }
+                    }
                 }
-                (0, when_ts_1.when)(lastResolution, () => outstanding--, () => outstanding--);
+                (0, when_ts_1.when)(lastResolution, () => outstanding--, (error) => {
+                    outstanding--;
+                    hadIndexingErrors = true;
+                    logger.error(error);
+                });
                 if (worker_threads_1.workerData && worker_threads_1.workerData.restartNumber !== manageThreads.restartNumber) {
                     interrupted = true;
                 }
-                if (interrupted) {
-                    try {
-                        await lastResolution;
-                    }
-                    catch {
-                        // already counted and logged by the rejection handler above
+                if (++indexed % 100 === 0 || interrupted) {
+                    // occasionally update our progress so if we crash, we can resume
+                    for (const attribute of attributes) {
+                        attribute.lastIndexedKey = key;
+                        Table.dbisDB.put(attribute.key, attribute);
                     }
-                    await checkpointing;
-                    await persistCheckpoint(key);
-                    return;
-                }
-                if (atInterval && indexed >= nextCheckpointRecord && performance.now() >= nextCheckpointAt) {
-                    nextCheckpointAt = performance.now() + indexingCheckpointPeriodMs;
-                    nextCheckpointRecord = indexed + indexingCheckpointMinRecords;
-                    await checkpointing;
-                    checkpointing = (0, when_ts_1.when)(lastResolution, () => persistCheckpoint(key), () => { });
+                    if (interrupted)
+                        return;
                 }
                 if (outstanding > MAX_OUTSTANDING_INDEXING)
                     await lastResolution;
-                if (atInterval || didSynchronousIndexing || outstanding > MIN_OUTSTANDING_INDEXING)
-                    await yieldEventTurn();
+                else if (outstanding > MIN_OUTSTANDING_INDEXING)
+                    await new Promise((resolve) => setImmediate(resolve)); // yield event turn, don't want to use all computation
+                else if (didSynchronousIndexing)
+                    await new Promise((resolve) => setImmediate(resolve)); // custom indexes (e.g. HNSW) index synchronously and never raise `outstanding`; without this yield a large backfill runs in a single event-loop turn, starving keepalive/replication and queries and never letting the isIndexing flag be observed
             }
         }
-        await checkpointing;
-        // Await the last pending put. If it rejects, that is also an indexing error (already counted by
-        // onIndexPutRejected); catching it here keeps it from escaping to the outer catch.
+        // Await the last pending put. If it rejects, that is also an indexing error.
+        // Note: the when() calls above already attach rejection handlers to each record's
+        // last-put promise; this try-catch specifically handles the case where lastResolution
+        // itself rejects (i.e. the very last put in the loop failed) which would otherwise
+        // throw past the hadIndexingErrors check to the outer catch. The broader issue of
+        // unhandled rejections from non-last puts in multi-value attributes is pre-existing
+        // and out of scope for this fix.
         try {
             await lastResolution;
         }
@@ -2319,17 +3056,6 @@ async function runIndexing(Table, attributes, indicesToRemove) {
         // microtasks when their tracked promise settles) have a chance to set hadIndexingErrors
         // before we decide whether to mark indexing as complete.
         await new Promise((resolve) => setImmediate(resolve));
-        // the tail since the last checkpoint is not durable until flushed; announcing the index complete
-        // before that would outlive a crash that loses it
-        if (!hadIndexingErrors) {
-            try {
-                await flushIndexStores(Table.primaryStore.rootStore);
-            }
-            catch (error) {
-                hadIndexingErrors = true;
-                logger.error(`Could not flush the indexes of ${Table.tableName} before marking them complete`, error);
-            }
-        }
         if (hadIndexingErrors) {
             // Some records failed to index. Persist the failure marker in the descriptor so
             // the next call to table() (including after a restart with a fresh PID) re-triggers
@@ -2358,12 +3084,9 @@ async function runIndexing(Table, attributes, indicesToRemove) {
             // update the attributes to indicate that we are finished
             for (const attribute of attributes) {
                 delete attribute.lastIndexedKey;
-                delete attribute.checkpointCertified;
                 delete attribute.indexingPID;
                 delete attribute.indexingFailed;
                 delete attribute.restartNumber;
-                delete attribute.indexingIncarnation;
-                delete attribute.indexingBuildId;
                 attribute.dbi.isIndexing = false;
                 // Also clear isIndexing on the currently-active dbi in Table.indices, which may
                 // differ from attribute.dbi if a resetDatabases() call during this migration
@@ -2375,12 +3098,11 @@ async function runIndexing(Table, attributes, indicesToRemove) {
             }
             await lastResolution;
             // now notify all the threads that we are done and the index is ready to use
-            await signalling.signalSchemaChange(new itc_js_1.SchemaEventMsg(process.pid, 'indexing-finished', Table.databaseName, Table.tableName));
+            await signalling.signalSchemaChange(new itc_js_1.SchemaEventMsg(process.pid, 'indexing-finished', Table.databaseName, Table.tableName, undefined, branchPath));
             logger.info(`Finished indexing ${Table.tableName} attributes`, attributes);
         }
     }
     catch (error) {
-        await checkpointing;
         // A worker shutting down closes its stores mid-backfill, so the range iterator or a
         // put throws (e.g. "Database not open" / "Iterator not initialized"). This is an
         // interruption, not a data error: the next worker generation re-runs the backfill via