@harperfast/harper 5.2.9 → 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.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,6 +62,8 @@ exports.dropDatabase = dropDatabase;
 exports.closeDatabase = closeDatabase;
 exports.closeLoadedDatabases = closeLoadedDatabases;
 exports.table = table;
+exports.scopedTableFactory = scopedTableFactory;
+exports.reloadBranchAt = reloadBranchAt;
 exports.canonicalizeIndexOptions = canonicalizeIndexOptions;
 exports.dropTableMeta = dropTableMeta;
 exports.onUpdatedTable = onUpdatedTable;
@@ -83,6 +95,8 @@ const manageThreads = __importStar(require("../server/threads/manageThreads.js")
 const auditStore_ts_1 = require("./auditStore.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");
@@ -139,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).
@@ -307,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 = {};
@@ -321,6 +390,33 @@ 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');
+// 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
 // almost always fails identically forever - the usual cause is a RocksDB
@@ -394,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) || {};
@@ -418,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) {
@@ -473,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);
                     }
@@ -519,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) {
@@ -533,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');
@@ -551,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
@@ -590,14 +843,14 @@ function readMetaDb(path, defaultTable, databaseName = DEFAULT_DATABASE_NAME, au
             rootStore = (0, lmdb_1.open)(envInit);
             lmdbDatabaseEnvs.set(path, rootStore);
         }
-        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) {
@@ -608,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]);
             }
         }
@@ -626,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;
@@ -641,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;
@@ -667,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();
@@ -766,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)
@@ -815,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;
@@ -832,6 +1104,7 @@ 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;
                     }
@@ -902,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,
@@ -923,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)) {
@@ -1038,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
@@ -1147,6 +1804,10 @@ async function dropDatabase(databaseName) {
         delete exports.databases[databaseName];
         exports.databaseEventsEmitter.emit('dropDatabase', databaseName);
         if (rootStore) {
+            // awaited: retirement stops the loop admitting work, the barrier is what says the pass that was
+            // already running has released the stores this is about to close and unlink
+            await rootStore.auditStore?.stopAuditCleanup?.();
+            (0, storageReclamation_ts_1.removeStorageReclamation)(rootStore.path);
             if (rootStore.status === 'open') {
                 if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
                     rootStore.close();
@@ -1164,6 +1825,8 @@ async function dropDatabase(databaseName) {
             // the drop lock now (still before any destructive step)
             if (rootStore instanceof rocksdb_js_1.RocksDatabase)
                 lockDatabaseForDrop(rootStore.path, databaseName, restoreLocks);
+            await rootStore.auditStore?.stopAuditCleanup?.();
+            (0, storageReclamation_ts_1.removeStorageReclamation)(rootStore.path);
             if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
                 rootStore.close();
                 rootStore.destroy();
@@ -1206,10 +1869,6 @@ function closeDatabase(databaseName) {
             continue;
         if (table.primaryStore.rootStore)
             rootStores.add(table.primaryStore.rootStore);
-        for (const indexName in table.indices || {}) {
-            closeStore(table.indices[indexName], `index ${tableName}.${indexName}`);
-        }
-        closeStore(table.primaryStore, `table ${tableName}`);
     }
     // a database with no tables (an empty schema, or one whose tables were all dropped) still holds
     // an open root store, tracked only on the defined-database entry rather than any table — include
@@ -1217,7 +1876,23 @@ function closeDatabase(databaseName) {
     const definedRoot = definedDatabases?.get(databaseName)?.rootStore;
     if (definedRoot)
         rootStores.add(definedRoot);
+    // before any table store closes, so no further pass is admitted. This is synchronous, so it cannot
+    // await the drain barrier stopAuditCleanup() returns; what covers it is the in-pass status checks,
+    // plus the fact that its production callers reach it only for RocksDB databases, whose pass is one
+    // synchronous purgeLogs() call with nothing suspended mid-removal.
+    for (const rootStore of rootStores)
+        rootStore.auditStore?.stopAuditCleanup?.();
+    for (const tableName in dbTables) {
+        const table = dbTables[tableName];
+        if (!table?.primaryStore)
+            continue;
+        for (const indexName in table.indices || {}) {
+            closeStore(table.indices[indexName], `index ${tableName}.${indexName}`);
+        }
+        closeStore(table.primaryStore, `table ${tableName}`);
+    }
     for (const rootStore of rootStores) {
+        (0, storageReclamation_ts_1.removeStorageReclamation)(rootStore.path);
         closeStore(rootStore.dbisDb, 'attributes store');
         closeStore(rootStore, 'root store');
         lmdbDatabaseEnvs.delete(rootStore.path);
@@ -1247,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];
@@ -1351,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`);
@@ -1391,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
@@ -1404,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') {
@@ -1420,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) {
@@ -1433,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
@@ -1578,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,
@@ -1609,96 +2427,99 @@ function table(tableDefinition) {
                 properties,
                 hidden,
                 cacheControl,
-            }));
+            });
             Table.schemaVersion = 1;
             hasChanges = true;
-            attributesDbi.put(dbiName, primaryKeyAttribute);
+            deferredPrimaryRow = 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;
-        }
-    }
-    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;
-        }
-        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);
+            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;
+            }
+            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();
@@ -1717,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`.
@@ -1767,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
@@ -1881,23 +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) {
-        Table.indexingOperation = runIndexing(Table, attributesToIndex, indicesToRemove);
+        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)
@@ -1908,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
@@ -1929,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.
@@ -1966,10 +2927,10 @@ function canonicalizeIndexOptions(value) {
 }
 const MAX_OUTSTANDING_INDEXING = 1000;
 const MIN_OUTSTANDING_INDEXING = 10;
-async function runIndexing(Table, attributes, indicesToRemove) {
+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();
@@ -2137,7 +3098,7 @@ 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);
         }
     }