@harperfast/harper 5.2.13 → 5.3.0-beta.1

package/dist/resources/databases.js

@@ -36,14 +36,24 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ABANDONED_MARK_LOCK_TIMEOUT = exports.CHECKPOINT_ALGORITHM = exports.databases = exports.tables = exports.databaseEventsEmitter = exports.NON_REPLICATING_SYSTEM_TABLES = void 0;
+exports.CHECKPOINT_ALGORITHM = exports.BRANCH_REMOVING_SUFFIX = exports.BRANCH_ROOT_DIR = exports.databases = exports.tables = exports.databaseEventsEmitter = exports.NON_REPLICATING_SYSTEM_TABLES = void 0;
 exports.isReadOnlyMode = isReadOnlyMode;
 exports.getRocksCompression = getRocksCompression;
 exports.resetRocksCompression = resetRocksCompression;
 exports.toRocksCompression = toRocksCompression;
 exports.getTables = getTables;
 exports.getDatabases = getDatabases;
+exports.hydrateBranchRelationships = hydrateBranchRelationships;
 exports.readMetaDb = readMetaDb;
+exports.resolveBranchPath = resolveBranchPath;
+exports.quarantineBranchIdentity = quarantineBranchIdentity;
+exports.assertBranchIdentityAvailable = assertBranchIdentityAvailable;
+exports.reserveBranchIdentity = reserveBranchIdentity;
+exports.retakeBranchIdentity = retakeBranchIdentity;
+exports.releaseBranchIdentity = releaseBranchIdentity;
+exports.isBranchIdentity = isBranchIdentity;
+exports.openBranchDatabase = openBranchDatabase;
+exports.closeBranchDatabases = closeBranchDatabases;
 exports.resetDatabases = resetDatabases;
 exports.resolveDatabaseStorageRoot = resolveDatabaseStorageRoot;
 exports.resolveDatabasePath = resolveDatabasePath;
@@ -52,10 +62,11 @@ exports.dropDatabase = dropDatabase;
 exports.closeDatabase = closeDatabase;
 exports.closeLoadedDatabases = closeLoadedDatabases;
 exports.table = table;
+exports.scopedTableFactory = scopedTableFactory;
+exports.reloadBranchAt = reloadBranchAt;
 exports.canonicalizeIndexOptions = canonicalizeIndexOptions;
 exports.setIndexingCheckpointPeriod = setIndexingCheckpointPeriod;
 exports.resumeStartKey = resumeStartKey;
-exports.tryAcquireUpdateAttributesLock = tryAcquireUpdateAttributesLock;
 exports.dropTableMeta = dropTableMeta;
 exports.onUpdatedTable = onUpdatedTable;
 exports.onRemovedTable = onRemovedTable;
@@ -67,7 +78,7 @@ const node_crypto_1 = require("node:crypto");
 const environmentManager_ts_1 = require("../utility/environment/environmentManager.js");
 const terms_ts_1 = require("../utility/lmdb/terms.js");
 const lmdb_1 = require("lmdb");
-const path_1 = require("path");
+const node_path_1 = require("node:path");
 const node_fs_1 = require("node:fs");
 const promises_1 = require("node:fs/promises");
 const initializePaths_js_1 = require("../dataLayer/harperBridge/lmdbBridge/lmdbUtility/initializePaths.js");
@@ -85,14 +96,17 @@ const harper_logger_ts_1 = __importDefault(require("../utility/logging/harper_lo
 const { forComponent } = harper_logger_ts_1.default;
 const manageThreads = __importStar(require("../server/threads/manageThreads.js"));
 const auditStore_ts_1 = require("./auditStore.js");
-const storageReclamation_ts_1 = require("../server/storageReclamation.js");
 const RecordEncoder_ts_1 = require("./RecordEncoder.js");
 const blob_ts_1 = require("./blob.js");
+const storageReclamation_ts_1 = require("../server/storageReclamation.js");
+const common_validators_ts_1 = require("../validation/common_validators.js");
 const customIndexes_ts_1 = require("./indexes/customIndexes.js");
+const hnswPlaneBinding_ts_1 = require("./indexes/hnswPlaneBinding.js");
 const OpenDBIObject_ts_1 = require("../utility/lmdb/OpenDBIObject.js");
 const rocksdb_js_1 = require("@harperfast/rocksdb-js");
 const PrimaryRocksDatabase_ts_1 = require("./PrimaryRocksDatabase.js");
 const replayLogs_ts_1 = require("./replayLogs.js");
+const hnswDerivedIndex_ts_1 = require("./indexes/hnswDerivedIndex.js");
 const node_os_1 = require("node:os");
 const RocksIndexStore_ts_1 = require("./RocksIndexStore.js");
 const rocksMemoryConfig_ts_1 = require("../utility/rocksMemoryConfig.js");
@@ -143,8 +157,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).
@@ -311,9 +377,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 = {};
@@ -325,6 +394,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];
+    }
+}
 /**
  * True when a descriptor claims an index build no live operation in this process can own. The PID and
  * worker generation cannot answer that alone: a container reuses PID 1 and starts the in-memory
@@ -415,8 +511,9 @@ 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);
+    let databasePath = hdbBasePath && (0, node_path_1.join)(hdbBasePath, hdbTerms_ts_1.DATABASES_DIR_NAME);
     const schemaConfigs = (0, environmentManager_ts_1.get)(hdbTerms_ts_1.CONFIG_PARAMS.DATABASES) || {};
     // not sure why this doesn't work with the environmemt manager
     if (process.env.SCHEMAS_DATA_PATH)
@@ -424,7 +521,7 @@ function getDatabases() {
     databasePath =
         process.env.STORAGE_PATH ||
             (0, configUtils_ts_1.getConfigPath)(hdbTerms_ts_1.CONFIG_PARAMS.STORAGE_PATH) ||
-            (databasePath && ((0, node_fs_1.existsSync)(databasePath) ? databasePath : (0, path_1.join)((0, environmentManager_ts_1.getHdbBasePath)(), hdbTerms_ts_1.LEGACY_DATABASES_DIR_NAME)));
+            (databasePath && ((0, node_fs_1.existsSync)(databasePath) ? databasePath : (0, node_path_1.join)((0, environmentManager_ts_1.getHdbBasePath)(), hdbTerms_ts_1.LEGACY_DATABASES_DIR_NAME)));
     if (databasePath && (0, node_fs_1.existsSync)(databasePath)) {
         // First load all the databases from our main database folder
         // TODO: Load any databases defined with explicit storage paths from the config
@@ -439,12 +536,17 @@ 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;
-            const dbName = (0, path_1.basename)(databaseEntry.name, '.mdb');
-            const dbPath = (0, path_1.join)(databasePath, databaseEntry.name);
+            // branch directories are process-local derivatives, never databases in their own right
+            if (databaseEntry.name === exports.BRANCH_ROOT_DIR)
+                continue;
+            const dbName = (0, node_path_1.basename)(databaseEntry.name, '.mdb');
+            const dbPath = (0, node_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' &&
+                (0, node_path_1.extname)(databaseEntry.name).toLowerCase() === '.mdb' &&
                 !schemaConfigs[dbName]?.path) {
                 logger.trace(`loading lmdb database: ${dbPath}`);
                 readMetaDb(dbPath, null, dbName);
@@ -471,12 +573,12 @@ function getDatabases() {
     if ((0, node_fs_1.existsSync)(baseSchemaPath)) {
         for (const schemaEntry of (0, node_fs_1.readdirSync)(baseSchemaPath, { withFileTypes: true })) {
             if (!schemaEntry.isFile()) {
-                const schemaPath = (0, path_1.join)(baseSchemaPath, schemaEntry.name);
-                const schemaAuditPath = (0, path_1.join)((0, initializePaths_js_1.getTransactionAuditStoreBasePath)(), schemaEntry.name);
+                const schemaPath = (0, node_path_1.join)(baseSchemaPath, schemaEntry.name);
+                const schemaAuditPath = (0, node_path_1.join)((0, initializePaths_js_1.getTransactionAuditStoreBasePath)(), schemaEntry.name);
                 for (const tableEntry of (0, node_fs_1.readdirSync)(schemaPath, { withFileTypes: true })) {
-                    if (tableEntry.isFile() && (0, path_1.extname)(tableEntry.name).toLowerCase() === '.mdb') {
-                        const auditPath = (0, path_1.join)(schemaAuditPath, tableEntry.name);
-                        readMetaDb((0, path_1.join)(schemaPath, tableEntry.name), (0, path_1.basename)(tableEntry.name, '.mdb'), schemaEntry.name, auditPath, true);
+                    if (tableEntry.isFile() && (0, node_path_1.extname)(tableEntry.name).toLowerCase() === '.mdb') {
+                        const auditPath = (0, node_path_1.join)(schemaAuditPath, tableEntry.name);
+                        readMetaDb((0, node_path_1.join)(schemaPath, tableEntry.name), (0, node_path_1.basename)(tableEntry.name, '.mdb'), schemaEntry.name, auditPath, true);
                     }
                 }
             }
@@ -494,14 +596,18 @@ function getDatabases() {
                         continue; // migration staging dir
                     if (databaseEntry.name === restoreMarker_ts_1.RESTORE_META_DIR)
                         continue; // reserved restore-metadata dir
-                    if (blockedByRestore.has((0, path_1.basename)(databaseEntry.name, '.mdb')))
+                    if (databaseEntry.name === exports.BRANCH_ROOT_DIR)
+                        continue; // reserved branch root
+                    if (blockedByRestore.has((0, node_path_1.basename)(databaseEntry.name, '.mdb')))
                         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);
+                    if (isOpenBranchPath((0, node_path_1.join)(databasePath, databaseEntry.name)))
+                        continue;
+                    if (databaseEntry.isFile() && (0, node_path_1.extname)(databaseEntry.name).toLowerCase() === '.mdb') {
+                        readMetaDb((0, node_path_1.join)(databasePath, databaseEntry.name), (0, node_path_1.basename)(databaseEntry.name, '.mdb'), dbName);
                     }
                     else {
                         try {
-                            const dbPath = (0, path_1.join)(databasePath, databaseEntry.name);
+                            const dbPath = (0, node_path_1.join)(databasePath, databaseEntry.name);
                             const files = (0, node_fs_1.readdirSync)(dbPath, { withFileTypes: true });
                             if (files.find((file) => file.name === 'CURRENT')?.isFile() &&
                                 files.some((file) => file.name.startsWith('MANIFEST-'))) {
@@ -521,7 +627,7 @@ function getDatabases() {
             if (tableConfigs) {
                 for (const tableName in tableConfigs) {
                     const tableConfig = tableConfigs[tableName];
-                    const tablePath = (0, path_1.join)(tableConfig.path, (0, path_1.basename)(tableName + '.mdb'));
+                    const tablePath = (0, node_path_1.join)(tableConfig.path, (0, node_path_1.basename)(tableName + '.mdb'));
                     if ((0, node_fs_1.existsSync)(tablePath)) {
                         readMetaDb(tablePath, tableName, dbName, null, true);
                     }
@@ -540,11 +646,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) {
@@ -554,6 +664,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');
@@ -572,6 +683,148 @@ function getDatabases() {
     }
     return exports.databases;
 }
+/**
+ * Hydrate one branch's relationships, resolving each target against the application's own branches
+ * first and only then against the real databases: a target the application also branched must be its
+ * branch's table, and a target it did not branch is legitimately the shared one.
+ */
+function hydrateBranchRelationships(branch, branches) {
+    const resolveTarget = (target) => {
+        const targetBranch = branches.get(target.database);
+        // A branched target resolves ONLY within that branch. A durable branch is a checkpoint frozen
+        // at creation while the base keeps evolving, so falling through to the base for a table the
+        // branch's own copy lacks would point a branched application's relationship reads at live base
+        // data -- the fallback belongs to a database the application did not branch, never to one it did.
+        return targetBranch ? targetBranch.tables?.[target.table] : exports.databases[target.database]?.[target.table];
+    };
+    // Kept, not drained, like the global list: a target declared later (on this or another thread) is
+    // picked up by the next pass, and `hydrateTableRelationships` is a no-op once everything resolves.
+    for (const hydration of branch.pendingRelationships) {
+        try {
+            hydrateTableRelationships(hydration, resolveTarget, false);
+        }
+        catch (error) {
+            logger.error(`Unable to hydrate persisted relationships for branch table ${hydration.databaseName}.${hydration.tableName}`, error);
+        }
+    }
+}
+function hydrateCatalogRelationships() {
+    for (const hydration of relationshipsToHydrate) {
+        try {
+            hydrateTableRelationships(hydration);
+        }
+        catch (error) {
+            const key = `${hydration.databaseName}.${hydration.tableName}:hydrate`;
+            if (!reportedRelationshipErrors.has(key)) {
+                reportedRelationshipErrors.add(key);
+                logger.error(`Unable to hydrate persisted relationships for ${hydration.databaseName}.${hydration.tableName}`, error);
+            }
+        }
+    }
+}
+const resolveTargetGlobally = (target) => exports.databases[target.database]?.[target.table];
+function hydrateTableRelationships({ table, databaseName, tableName, definitions }, resolveTarget = resolveTargetGlobally, announce = true) {
+    const hydratable = [];
+    for (let index = 0; index < definitions.length; index++) {
+        const definition = definitions[index];
+        // Keyed by name rather than list position, so a reordered list cannot inherit the previous
+        // occupant's reported state and swallow a different relationship's failure — and by reason, so
+        // hydrating one entry does not clear the report of a same-named invalid duplicate.
+        const errorKey = `${databaseName}.${tableName}:${definition?.name || `#${index}`}`;
+        if (!validRelationshipDefinition(definition, definitions, index)) {
+            reportRelationshipError(`${errorKey}:invalid`, `Ignoring invalid persisted relationship ${databaseName}.${tableName}[${index}]`);
+            continue;
+        }
+        // a live schema attribute of the same name owns the name; the catalog copy is only a stand-in
+        // for threads that never loaded the schema
+        if (table.attributes.some((attribute) => attribute.name === definition.name && !attribute[CATALOG_RELATIONSHIP]))
+            continue;
+        const targetTable = resolveTarget(definition.target);
+        if (!targetTable || !relationshipFieldsExist(table, targetTable, definition)) {
+            reportRelationshipError(`${errorKey}:unavailable`, `Unable to hydrate persisted relationship ${databaseName}.${tableName}.${definition.name}: target or foreign key is unavailable`);
+            continue;
+        }
+        reportedRelationshipErrors.delete(`${errorKey}:unavailable`);
+        hydratable.push({ definition, targetTable });
+    }
+    const installed = table.attributes.filter((attribute) => attribute[CATALOG_RELATIONSHIP]);
+    if (installed.length === hydratable.length &&
+        hydratable.every(({ definition, targetTable }, index) => relationshipEquals(installed[index], definition) &&
+            (installed[index].definition || installed[index].elements?.definition)?.tableClass === targetTable))
+        return;
+    const attributes = table.attributes.filter((attribute) => !attribute[CATALOG_RELATIONSHIP]);
+    for (const { definition, targetTable } of hydratable)
+        attributes.push(createCatalogRelationship(definition, targetTable));
+    table.attributes.splice(0, table.attributes.length, ...attributes);
+    table.schemaVersion++;
+    table.updatedAttributes();
+    if (announce)
+        exports.databaseEventsEmitter.emit('updateTable', table);
+}
+function validRelationshipDefinition(definition, definitions, index) {
+    if (!definition || typeof definition !== 'object')
+        return false;
+    const validName = (value) => typeof value === 'string' && value.length > 0 && !/[`/]/.test(value);
+    if (!validName(definition.name) || !validName(definition.type))
+        return false;
+    if (!validName(definition.target?.database) || !validName(definition.target?.table))
+        return false;
+    if (!definition.relationship || typeof definition.relationship !== 'object')
+        return false;
+    const { from, to, filterMissing } = definition.relationship;
+    if (from !== undefined && !validName(from))
+        return false;
+    if (to !== undefined && !validName(to))
+        return false;
+    if (!from && !to)
+        return false;
+    if (filterMissing !== undefined && typeof filterMissing !== 'boolean')
+        return false;
+    if (definition.type === 'array' ? !validName(definition.elements?.type) : definition.elements !== undefined)
+        return false;
+    for (let earlier = 0; earlier < index; earlier++)
+        if (definitions[earlier]?.name === definition.name)
+            return false;
+    return true;
+}
+function relationshipFieldsExist(sourceTable, targetTable, definition) {
+    if (definition.relationship.from &&
+        !sourceTable.attributes.some((attribute) => attribute.name === definition.relationship.from))
+        return false;
+    if (definition.relationship.to &&
+        !targetTable.attributes.some((attribute) => attribute.name === definition.relationship.to))
+        return false;
+    return true;
+}
+function createCatalogRelationship(definition, targetTable) {
+    const attribute = {
+        name: definition.name,
+        attribute: definition.name,
+        type: definition.type,
+        relationship: { ...definition.relationship },
+        target: { ...definition.target },
+    };
+    const targetDefinition = {
+        tableClass: targetTable,
+        type: targetTable.tableName,
+        attributes: targetTable.attributes,
+    };
+    if (definition.elements) {
+        attribute.elements = { type: definition.elements.type };
+        Object.defineProperty(attribute.elements, 'definition', { value: targetDefinition, configurable: true });
+    }
+    else {
+        Object.defineProperty(attribute, 'definition', { value: targetDefinition, configurable: true });
+    }
+    Object.defineProperty(attribute, CATALOG_RELATIONSHIP, { value: true });
+    return attribute;
+}
+function reportRelationshipError(key, message) {
+    if (reportedRelationshipErrors.has(key))
+        return;
+    reportedRelationshipErrors.add(key);
+    logger.error(message);
+}
 /**
  * Scan a databases directory's entries for restore lock/marker files and return the names of
  * databases that must not be loaded: a held restore lock means a restore is in progress in some
@@ -612,14 +865,14 @@ function readMetaDb(path, defaultTable, databaseName = DEFAULT_DATABASE_NAME, au
             lmdbDatabaseEnvs.set(path, rootStore);
         }
         rootStore.dbisDb?.resetReadTxn();
-        return initStores(path, rootStore, databaseName, defaultTable, auditPath, isLegacy);
+        return initStores(path, rootStore, databaseName, { defaultTable, auditPath, isLegacy });
     }
     catch (error) {
         error.message += ` opening database ${path}`;
         throw error;
     }
 }
-function readRocksMetaDb(path, defaultTable, databaseName = DEFAULT_DATABASE_NAME) {
+function readRocksMetaDb(path, defaultTable, databaseName = DEFAULT_DATABASE_NAME, { destination, storeName, openedStores } = {}) {
     try {
         logger.trace(`loading rocksdb database: ${path}`);
         if (process.env.HARPER_PARENT_PROCESS_PID) {
@@ -630,14 +883,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]);
             }
         }
@@ -648,7 +905,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;
@@ -663,6 +922,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;
@@ -683,13 +943,18 @@ function initStores(path, rootStore, databaseName, defaultTable, auditPath, isLe
                     });
                 }
                 auditStore.isLegacy = true;
+                // A legacy standalone audit root skips openAuditStore, so give it a floor here or it
+                // reports its retention horizon as permanently unknown.
+                (0, auditStore_ts_1.establishAuditFloor)(auditStore);
             }
         }
         else {
             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();
@@ -788,14 +1053,26 @@ 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)
         const recreateForEngineChange = !!table && table.primaryStore?.rootStore instanceof rocksdb_js_1.RocksDatabase !== rootStore instanceof rocksdb_js_1.RocksDatabase;
+        const recreateForTableIdChange = !!table && primaryAttribute.tableId != null && table.tableId !== primaryAttribute.tableId;
+        const recreateTable = recreateForEngineChange || recreateForTableIdChange;
         let indices = {}, existingAttributes = [];
         let tableId;
         let primaryStore;
@@ -807,7 +1084,9 @@ function initStores(path, rootStore, databaseName, defaultTable, auditPath, isLe
         const cacheControl = primaryAttribute.cacheControl;
         const splitSegments = primaryAttribute.splitSegments;
         const replicate = primaryAttribute.replicate;
-        if (table && !recreateForEngineChange) {
+        if (table && !recreateTable) {
+            if (primaryAttribute.audit === true && table.audit !== true)
+                table.enableAuditing();
             indices = table.indices;
             existingAttributes = table.attributes;
             table.schemaVersion++;
@@ -837,13 +1116,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;
@@ -854,6 +1133,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;
                     }
@@ -918,14 +1198,18 @@ function initStores(path, rootStore, databaseName, defaultTable, auditPath, isLe
             existingAttributes.splice(existingAttributes.indexOf(existingAttribute), 1);
             attributesUpdated = true;
         }
-        if (table && !recreateForEngineChange) {
+        if (table && !recreateTable) {
             if (attributesUpdated) {
                 table.schemaVersion++;
                 table.updatedAttributes();
             }
         }
         else {
+            if (recreateForTableIdChange)
+                table.cleanup();
             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,
@@ -947,11 +1231,391 @@ 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);
+        }
+        void table.derivedIndexRuntime?.close();
+        table.derivedIndexRuntime = (0, hnswDerivedIndex_ts_1.attachDerivedIndexes)(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, node_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 {
+        // before the open: table load schedules TTL, eviction and audit cleanup, which ask who owns this store
+        manageThreads.markBranchStorePath(path);
+        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);
+        manageThreads.markBranchStorePath(path, false);
+        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);
+            manageThreads.markBranchStorePath(path, false);
+            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)) {
@@ -1022,10 +1686,10 @@ function resolveDatabaseStorageRoot(databaseName, tableName) {
         databaseConfig[databaseName]?.path ||
         process.env.STORAGE_PATH ||
         (0, configUtils_ts_1.getConfigPath)(hdbTerms_ts_1.CONFIG_PARAMS.STORAGE_PATH) ||
-        (hdbBasePath && (0, node_fs_1.existsSync)((0, path_1.join)(hdbBasePath, hdbTerms_ts_1.DATABASES_DIR_NAME))
-            ? (0, path_1.join)(hdbBasePath, hdbTerms_ts_1.DATABASES_DIR_NAME)
+        (hdbBasePath && (0, node_fs_1.existsSync)((0, node_path_1.join)(hdbBasePath, hdbTerms_ts_1.DATABASES_DIR_NAME))
+            ? (0, node_path_1.join)(hdbBasePath, hdbTerms_ts_1.DATABASES_DIR_NAME)
             : hdbBasePath
-                ? (0, path_1.join)(hdbBasePath, hdbTerms_ts_1.LEGACY_DATABASES_DIR_NAME)
+                ? (0, node_path_1.join)(hdbBasePath, hdbTerms_ts_1.LEGACY_DATABASES_DIR_NAME)
                 : undefined);
     if (!databasePath) {
         throw new Error(`Unable to determine database storage path. Ensure STORAGE_PATH, HDB_ROOT, or a valid config path is set.`);
@@ -1036,7 +1700,7 @@ function resolveDatabaseStorageRoot(databaseName, tableName) {
  * Resolve the directory path of a RocksDB database (whether or not it exists or is loaded).
  */
 function resolveDatabasePath(databaseName) {
-    return (0, path_1.join)(resolveDatabaseStorageRoot(databaseName), databaseName);
+    return (0, node_path_1.join)(resolveDatabaseStorageRoot(databaseName), databaseName);
 }
 /**
  * Get root store for a database
@@ -1061,7 +1725,15 @@ function database({ database: databaseName, table: tableName }) {
     let rootStore;
     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);
+        const path = (0, node_path_1.join)(databasePath, tablePath ? tableName : databaseName);
+        // the scan is not the only way to reach a branch's directory: a branch leaves its store in
+        // `rocksdbDatabaseEnvs`, so without this an on-demand open would staple it onto
+        // `definedDatabases` and the next `closeDatabase` would close it under the live handle
+        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
@@ -1076,7 +1748,7 @@ function database({ database: databaseName, table: tableName }) {
         }
     }
     else {
-        const path = (0, path_1.join)(databasePath, `${tablePath ? tableName : databaseName}.mdb`);
+        const path = (0, node_path_1.join)(databasePath, `${tablePath ? tableName : databaseName}.mdb`);
         rootStore = lmdbDatabaseEnvs.get(path);
         if (!rootStore || rootStore.status === 'closed') {
             // TODO: validate database name
@@ -1289,8 +1961,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];
@@ -1393,24 +2069,41 @@ 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);
+            // derived state whose maintaining option is now off must not linger to be adopted
+            // stale on a later re-enable
+            indexStore.customIndex.cleanupDisabledPlane?.();
         }
         else {
             logger.error(`The indexing type '${attribute.indexed.type}' is unknown`);
@@ -1433,7 +2126,88 @@ 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, shared application gets `table` by identity. An isolated application still gets a
+ * wrapper so its own declarations can claim their single-threaded maintenance work.
+ */
+function scopedTableFactory(branches, isolatedApplicationOwner = false) {
+    if (!branches?.size && !isolatedApplicationOwner)
+        return table;
+    return function scopedTable(tableDefinition) {
+        if (isolatedApplicationOwner)
+            tableDefinition = { ...tableDefinition, isolatedApplicationOwner: true };
+        // `||`, 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, isolatedApplicationOwner, } = tableDefinition;
+    const auditExplicitlyEnabled = audit === true;
+    const auditExplicitlyDisabled = audit === false;
     if (!databaseName)
         databaseName = DEFAULT_DATABASE_NAME;
     // Reject reserved names here too, not only at the operations API: a database
@@ -1446,8 +2220,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') {
@@ -1462,137 +2242,296 @@ 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) {
-            // there is some legacy code that calls the attribute's name the attribute's attribute
-            attribute.name = attribute.attribute;
-            attribute.indexed = true;
+    let releaseExclusiveLock;
+    const hasHnswAtEntry = attributes.some((attribute) => attribute.indexed?.type === 'HNSW');
+    const persistedPrimaryDescriptor = (catalog) => {
+        const declaredPrimaryKey = attributes.find((attribute) => attribute.isPrimaryKey)?.name ?? Table?.primaryKey;
+        if (declaredPrimaryKey) {
+            const key = `${tableName}/${declaredPrimaryKey}`;
+            const descriptor = catalog?.getSync(key);
+            if (descriptor?.isPrimaryKey)
+                return { key, descriptor };
+        }
+        const key = `${tableName}/`;
+        return { key, descriptor: catalog?.getSync(key) };
+    };
+    const hasLegacyHnswStateAtEntry = Table &&
+        origin !== 'cluster' &&
+        attributes.some((attribute) => {
+            if (attribute.indexed?.type !== 'HNSW')
+                return false;
+            const persisted = Table.dbisDB?.getSync(`${tableName}/${attribute.name || attribute.attribute || ''}`)?.indexed;
+            if (persisted?.type !== 'HNSW')
+                return false;
+            if (Object.hasOwn(persisted, 'nativePlane') && typeof persisted.nativePlane !== 'boolean')
+                return true;
+            for (const name of customIndexes_ts_1.CUSTOM_INDEXES.HNSW.numericOptions)
+                if (Object.hasOwn(persisted, name) && typeof persisted[name] !== 'number')
+                    return true;
+            return false;
+        });
+    try {
+        if (Table &&
+            hasHnswAtEntry &&
+            origin !== 'cluster' &&
+            (rootStore instanceof rocksdb_js_1.RocksDatabase || hasLegacyHnswStateAtEntry))
+            exclusiveLock();
+        const persistedAuditAtEntry = hasHnswAtEntry || (Table && Table.audit !== true)
+            ? persistedPrimaryDescriptor(Table?.dbisDB).descriptor?.audit
+            : undefined;
+        if (!auditExplicitlyDisabled && persistedAuditAtEntry === true && Table?.audit !== true)
+            Table.enableAuditing();
+        for (const attribute of attributes) {
+            if (attribute.attribute && !attribute.name) {
+                // there is some legacy code that calls the attribute's name the attribute's attribute
+                attribute.name = attribute.attribute;
+                attribute.indexed = true;
+            }
+            else
+                attribute.attribute = attribute.name;
+            if (attribute.expiresAt)
+                attribute.indexed = true;
+            if (attribute.indexed?.type === 'HNSW' && origin !== 'cluster') {
+                const existingAttribute = Table?.attributes.find((existing) => existing.name === attribute.name);
+                const persistedIndexed = Table?.dbisDB?.getSync(`${tableName}/${attribute.name || ''}`)?.indexed ?? existingAttribute?.indexed;
+                customIndexes_ts_1.CUSTOM_INDEXES.HNSW.normalizeDeclarationOptions(attribute.indexed, persistedIndexed);
+                if (attribute.indexed.nativePlane != null) {
+                    const persistedNativePlane = persistedIndexed?.nativePlane;
+                    const matchesPersistedLegacySpelling = persistedIndexed?.type === 'HNSW' &&
+                        Object.hasOwn(persistedIndexed, 'nativePlane') &&
+                        typeof persistedNativePlane !== 'boolean' &&
+                        (Object.is(persistedNativePlane, attribute.indexed.nativePlane) ||
+                            (typeof persistedNativePlane === 'string' &&
+                                typeof attribute.indexed.nativePlane === 'number' &&
+                                persistedNativePlane.trim() !== '' &&
+                                Number(persistedNativePlane) === attribute.indexed.nativePlane));
+                    if (matchesPersistedLegacySpelling) {
+                        attribute.indexed.nativePlane = persistedNativePlane;
+                    }
+                    else {
+                        attribute.indexed.nativePlane = customIndexes_ts_1.CUSTOM_INDEXES.HNSW.normalizeNativePlaneDeclaration(attribute.indexed.nativePlane);
+                    }
+                }
+            }
         }
-        else
-            attribute.attribute = attribute.name;
-        if (attribute.expiresAt)
-            attribute.indexed = true;
+        const auditEnabledAtEntry = auditExplicitlyEnabled ||
+            (!auditExplicitlyDisabled &&
+                (persistedAuditAtEntry === true || (persistedAuditAtEntry == null && Table?.audit === true)));
+        if (origin !== 'cluster' &&
+            attributes.some((attribute) => {
+                if (attribute.indexed?.type !== 'HNSW')
+                    return false;
+                if (attribute.indexed.nativePlane != null)
+                    return Boolean(attribute.indexed.nativePlane);
+                const existingAttribute = Table?.attributes.find((existing) => existing.name === attribute.name && existing.indexed?.type === 'HNSW');
+                return Boolean(existingAttribute?.indexed.nativePlane);
+            }) &&
+            !auditEnabledAtEntry) {
+            throw new hdbError_ts_1.ClientError(`Table '${databaseName}.${tableName}' must enable audit logging before using nativePlane because its transaction log is the derived-index recovery source; set nativePlane: false to use the JS index`);
+        }
+    }
+    catch (error) {
+        releaseLock();
+        throw error;
     }
+    const validateHnswOptions = (catalog, auditQualifiesDefault) => {
+        for (const attribute of attributes) {
+            const indexed = attribute.indexed;
+            if (indexed?.type !== 'HNSW')
+                continue;
+            const persistedIndexed = catalog?.getSync(`${tableName}/${attribute.name || ''}`)?.indexed;
+            if (indexed.nativePlane) {
+                customIndexes_ts_1.CUSTOM_INDEXES.HNSW.validateNativePlaneOptions(rootStore, indexed);
+                continue;
+            }
+            if (indexed.nativePlane != null)
+                continue;
+            if (persistedIndexed?.type === 'HNSW' && Object.hasOwn(persistedIndexed, 'nativePlane')) {
+                if (persistedIndexed.nativePlane)
+                    customIndexes_ts_1.CUSTOM_INDEXES.HNSW.validateNativePlaneOptions(rootStore, {
+                        ...indexed,
+                        nativePlane: persistedIndexed.nativePlane,
+                    });
+                continue;
+            }
+            if (!auditQualifiesDefault)
+                continue;
+            if (persistedIndexed?.type !== 'HNSW')
+                customIndexes_ts_1.CUSTOM_INDEXES.HNSW.canDefaultToNativePlane(rootStore, indexed);
+        }
+    };
+    if (!Table && origin !== 'cluster')
+        validateHnswOptions(undefined, auditExplicitlyEnabled);
     let hasChanges;
-    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;
+    let refreshRelationshipAttributes = false;
+    let refreshedLiveAttributes = false;
+    let deferredPrimaryRow;
+    let unpublishedPrimaryStore;
+    let published = false;
+    const attributesToIndex = [];
+    const indicesToRemove = [];
+    try {
+        if (Table) {
+            refreshedLiveAttributes = true;
+            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;
+            // ordinary LMDB declarations stay lazy, while legacy HNSW normalization locks at entry.
+            if (rootStore instanceof rocksdb_js_1.RocksDatabase)
+                exclusiveLock();
+            if (origin !== 'cluster') {
+                const lockedAttributesDbi = Table.dbisDB;
+                const persistedAuditUnderLock = persistedPrimaryDescriptor(lockedAttributesDbi).descriptor?.audit;
+                validateHnswOptions(lockedAttributesDbi, auditExplicitlyEnabled || (!auditExplicitlyDisabled && persistedAuditUnderLock === true));
+            }
+            // 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;
+            }
+            else if (!attributes.some((attribute) => attribute.isPrimaryKey)) {
+                const existingPrimary = Table.attributes.find((attribute) => attribute.isPrimaryKey);
+                if (existingPrimary && attributes.some((attribute) => attribute.name === existingPrimary.name))
+                    throw new hdbError_ts_1.ClientError(`Cannot remove the primary key designation from '${databaseName}.${tableName}.${existingPrimary.name}'`);
+                if (existingPrimary)
+                    attributes = [existingPrimary, ...attributes];
+            }
+            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
@@ -1620,15 +2559,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,
@@ -1651,96 +2595,165 @@ function table(tableDefinition) {
                 properties,
                 hidden,
                 cacheControl,
-            }));
+            });
             Table.schemaVersion = 1;
             hasChanges = true;
-            attributesDbi.put(dbiName, primaryKeyAttribute);
-        }
-        catch (error) {
-            // A failure while opening/creating the column family or writing the
-            // table id / catalog entry (e.g. into an env poisoned by a prior
-            // dangling column family) must NOT leak the exclusive
-            // 'update-attributes' spin lock. If it leaks, every subsequent
-            // create_table / attribute update on this database spins forever
-            // (a hard wedge that pins a worker at 100% CPU). Release before rethrow.
-            if (releaseExclusiveLock)
-                releaseExclusiveLock();
-            throw error;
-        }
-    }
-    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,
-            });
+            deferredPrimaryRow = primaryKeyAttribute;
         }
-        else {
-            rootStore.dbisDb = rootStore.openDB(terms_ts_1.INTERNAL_DBIS_NAME, internalDbiInit);
+        const indices = Table.indices;
+        if (!attributesDbi) {
+            if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
+                rootStore.dbisDb = openRocksDatabase(rootStore.path, {
+                    ...internalDbiInit,
+                    disableWAL: false,
+                    name: terms_ts_1.INTERNAL_DBIS_NAME,
+                });
+            }
+            else {
+                rootStore.dbisDb = rootStore.openDB(terms_ts_1.INTERNAL_DBIS_NAME, internalDbiInit);
+            }
+            target.adopt(rootStore.dbisDb);
+            attributesDbi = markInternalDbiNonVersioned(rootStore.dbisDb);
+        }
+        Table.dbisDB = attributesDbi;
+        // A cluster-origin list can miss a descriptor another thread committed moments ago, so removal
+        // reconciliation is reserved for local schema authoring; on a create the rows can only be aborted state.
+        const reconcileRemovals = origin !== 'cluster' || Boolean(deferredPrimaryRow);
+        for (const { key, value } of reconcileRemovals
+            ? attributesDbi.getRange({ start: tableName + '/', end: tableName + '0' })
+            : []) {
+            if (value == null)
+                continue;
+            let [attributeTableName, attribute_name] = key.toString().split('/');
+            if (attribute_name === '')
+                attribute_name = value.name; // primary key
+            if (attribute_name) {
+                if (attributeTableName !== tableName)
+                    continue;
+            }
+            else {
+                // table attribute for a table with no primary key, we don't want to remove this, so continue on
+                continue;
+            }
+            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 && !value.isPrimaryKey) || 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);
+                }
+            }
         }
-        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 hasHnswDeclaration = attributes.some((attribute) => attribute.indexed?.type === 'HNSW');
+        const persistedAudit = hasHnswDeclaration ? persistedPrimaryDescriptor(attributesDbi).descriptor?.audit : undefined;
+        // A cluster declaration can apply audit on a create, but deliberately cannot rewrite an existing
+        // table's primary row. Do not let an incoming audit value qualify a replicated native descriptor
+        // that this node would then persist beside its durable audit:false row.
+        const explicitAuditCanBeApplied = origin !== 'cluster' || Boolean(deferredPrimaryRow);
+        const auditEnabledForNativeDefault = (auditExplicitlyEnabled && explicitAuditCanBeApplied) || (!auditExplicitlyDisabled && persistedAudit === true);
+        const auditEnabledForNativePlane = !auditExplicitlyDisabled && (auditEnabledForNativeDefault || (persistedAudit == null && Table.audit === true));
+        for (const attribute of attributes) {
+            const indexed = attribute.indexed;
+            if (!indexed || typeof indexed !== 'object' || indexed.type !== 'HNSW')
                 continue;
+            const descriptor = attributesDbi.getSync(tableName + '/' + (attribute.name || ''));
+            const existingHnsw = descriptor?.indexed?.type === 'HNSW';
+            if (indexed.nativePlane == null) {
+                if (existingHnsw) {
+                    if (Object.hasOwn(descriptor.indexed, 'nativePlane')) {
+                        indexed.nativePlane = descriptor.indexed.nativePlane;
+                    }
+                }
+                else if (origin !== 'cluster' &&
+                    auditEnabledForNativeDefault &&
+                    customIndexes_ts_1.CUSTOM_INDEXES.HNSW.canDefaultToNativePlane(rootStore, indexed)) {
+                    indexed.nativePlane = true;
+                }
+            }
+            else if (origin === 'cluster' && !existingHnsw && indexed.nativePlane) {
+                let canRunNative = false;
+                try {
+                    canRunNative = auditEnabledForNativeDefault && customIndexes_ts_1.CUSTOM_INDEXES.HNSW.canRunNativePlane(rootStore, indexed);
+                }
+                catch { }
+                if (!canRunNative) {
+                    logger.warn(`Using the JS HNSW index for replicated attribute ${databaseName}.${tableName}.${attribute.name} because this node does not satisfy the nativePlane requirements`);
+                    indexed.nativePlane = false;
+                }
+            }
         }
-        else {
-            // table attribute for a table with no primary key, we don't want to remove this, so continue on
-            continue;
+        const nativePlaneEnabled = origin !== 'cluster' &&
+            attributes.some((attribute) => attribute.indexed?.type === 'HNSW' && attribute.indexed.nativePlane);
+        if (nativePlaneEnabled && !auditEnabledForNativePlane) {
+            throw new hdbError_ts_1.ClientError(`Table '${databaseName}.${tableName}' must enable audit logging before using nativePlane because its transaction log is the derived-index recovery source; set nativePlane: false to use the JS index`);
         }
-        const attribute = attributes.find((attribute) => attribute.name === attribute_name);
-        const removeIndex = !attribute?.indexed && value.indexed && !value.isPrimaryKey;
-        if (!attribute || removeIndex) {
+        if (nativePlaneEnabled && persistedAudit !== true)
+            audit = true;
+        if (nativePlaneEnabled && persistedAudit !== true && !attributes.some((attribute) => attribute.isPrimaryKey)) {
             exclusiveLock();
-            hasChanges = true;
-            if (!attribute)
-                attributesDbi.remove(key);
-            if (removeIndex) {
-                const indexDbi = Table.indices[attributeTableName];
-                if (indexDbi)
-                    indicesToRemove.push(indexDbi);
+            const primaryKey = primaryDescriptorKey();
+            const primaryDescriptor = attributesDbi.getSync(primaryKey);
+            if (primaryDescriptor && !tableIsDropping(primaryDescriptor, primaryKey)) {
+                Table.enableAuditing();
+                attributesDbi.put(primaryKey, { ...primaryDescriptor, audit: true });
+                hasChanges = true;
             }
         }
-    }
-    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;
+        const attributesInPersistenceOrder = nativePlaneEnabled
+            ? [
+                ...attributes.filter((attribute) => attribute.isPrimaryKey),
+                ...attributes.filter((attribute) => !attribute.isPrimaryKey),
+            ]
+            : auditExplicitlyDisabled
+                ? [
+                    ...attributes.filter((attribute) => !attribute.isPrimaryKey),
+                    ...attributes.filter((attribute) => attribute.isPrimaryKey),
+                ]
+                : attributes;
+        for (const attribute of attributesInPersistenceOrder) {
+            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 ||
+                        (typeof audit === 'boolean' && audit !== attributeDescriptor.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();
@@ -1759,14 +2772,51 @@ 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 ||
+                        isAbandonedIndexBuild(attributeDescriptor, 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`.
@@ -1809,6 +2859,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
@@ -1951,45 +3004,134 @@ 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++;
+    if (hasChanges || refreshRelationshipAttributes || refreshedLiveAttributes)
         Table.updatedAttributes();
-    }
     logger.trace(`${tableName} table loading, running index`);
+    const branchPath = target.branch?.path;
     if (attributesToIndex.length > 0 || indicesToRemove.length > 0) {
         // captured before the backfill can rewrite the attributes
         const buildIds = new Map(attributesToIndex.map((attribute) => [attribute, attribute.indexingBuildId]));
         const markSettled = () => markAbandonedIndexBuild(Table, rootStore, buildIds);
-        Table.indexingOperation = runIndexing(Table, attributesToIndex, indicesToRemove).then(markSettled, markSettled);
+        Table.indexingOperation = runIndexing(Table, attributesToIndex, indicesToRemove, branchPath).then(markSettled, markSettled);
     }
     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));
+    void Table.derivedIndexRuntime?.close();
+    Table.derivedIndexRuntime = (0, hnswDerivedIndex_ts_1.attachDerivedIndexes)(Table);
     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)
+    if (expiration || eviction || scanInterval || attributes.some((attribute) => attribute.expiresAt))
         Table.setTTLExpiration({
             expiration,
             eviction,
             scanInterval,
+            fromSchema: true,
+            isolatedApplicationOwner,
         });
     logger.trace(`${tableName} table loaded`);
     return Table;
+    // A migrated catalog can retain a named primary descriptor beside a bare table tombstone, so a
+    // drop in flight has to be checked on both representations.
+    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() {
+        return persistedPrimaryDescriptor(attributesDbi).key;
+    }
+    // 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
@@ -2002,37 +3144,41 @@ 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.
- * `@indexed(...)` records options in source-argument order and as strings, while the operations API
- * and config objects can supply them reordered or as numbers; without canonicalizing, such a
- * representation-only difference flips the structural comparison and forces a needless full rebuild
- * (clearing + rebuilding the index, 503-ing the attribute throughout) for a semantically identical
- * index. Sorts object keys and coerces numeric-looking (non-zero) string scalars to numbers.
- * Conservative by design: boolean-vs-object, absent-vs-present, and string-"0"-vs-number-0
- * differences are all preserved, so a genuine change (`true` vs `{ type: 'HNSW' }`, an added/removed
- * option, a changed value) still triggers a rebuild. Persistence keys off the raw form, so the stored
- * descriptor self-heals toward this shape over time. harper#1357
+ * Stable structural form for deciding whether an index must be rebuilt. `coerceZero` extends numeric
+ * coercion to zero; a truthiness-sensitive numeric option must normalize its value before using it.
  */
-function canonicalizeIndexOptions(value) {
+function canonicalizeIndexOptions(value, coerceZero = false) {
     if (Array.isArray(value))
-        return value.map(canonicalizeIndexOptions);
+        return value.map((item) => canonicalizeIndexOptions(item, coerceZero));
     if (value && typeof value === 'object') {
         const canonical = {};
-        for (const key of Object.keys(value).sort())
-            canonical[key] = canonicalizeIndexOptions(value[key]);
+        const customIndex = value.type && customIndexes_ts_1.CUSTOM_INDEXES[value.type];
+        for (const key of Object.keys(value).sort()) {
+            if (customIndex?.truthyStructuralOptions?.has(key)) {
+                if (value[key])
+                    canonical[key] = true;
+                continue;
+            }
+            const optionValue = customIndex?.normalizeOptionValue
+                ? customIndex.normalizeOptionValue(key, value[key])
+                : value[key];
+            canonical[key] = canonicalizeIndexOptions(optionValue, coerceZero || Boolean(customIndex?.numericOptions?.has(key)));
+        }
         return canonical;
     }
-    // Coerce numeric-looking strings ("16" -> 16) so string-vs-number representations of the same
-    // option compare equal — EXCEPT zero: the string "0" is truthy while the number 0 is falsy, and
-    // index code may branch on truthiness (e.g. HNSW `if (this.optimizeRouting)` doubles maxConnections),
-    // so "0" and 0 build structurally different indexes and must still trigger a rebuild. Zero is the
-    // only finite number whose string and numeric forms diverge in truthiness, so excluding it fully
-    // closes that gap. Leave non-numeric strings, booleans, null, etc. intact.
     if (typeof value === 'string' && value.trim() !== '') {
         const numeric = Number(value);
-        if (numeric !== 0 && Number.isFinite(numeric))
+        if ((numeric !== 0 || coerceZero) && Number.isFinite(numeric))
             return numeric;
     }
     return value;
@@ -2092,33 +3238,6 @@ function resumeStartKey(attributes) {
     }
     return start;
 }
-// Bounded, unlike the exclusiveLock() spin above: that one runs on the declaring path, where the
-// caller is waiting on the result and there is nothing useful to do without the lock. This one runs
-// after a backfill has already settled, so a holder that never releases would wedge the worker's
-// event loop for nothing. Giving up costs only the marker, and the next load of the table
-// re-triggers the build regardless.
-exports.ABANDONED_MARK_LOCK_TIMEOUT = 10000;
-const abandonedMarkLockWait = new Int32Array(new SharedArrayBuffer(4));
-// `timeout` is the test seam; production callers take the default.
-function tryAcquireUpdateAttributesLock(rootStore, timeout = exports.ABANDONED_MARK_LOCK_TIMEOUT) {
-    if (rootStore.tryLock('update-attributes'))
-        return true;
-    const startTime = performance.now();
-    let waitTime = 1;
-    while (!rootStore.tryLock('update-attributes')) {
-        const elapsed = performance.now() - startTime;
-        if (elapsed >= timeout)
-            return false;
-        // Atomics.wait rather than a busy spin: the section this guards is synchronous, so the wait
-        // blocks this thread either way, but sleeping does not burn a core while it does.
-        if (elapsed >= 2) {
-            Atomics.wait(abandonedMarkLockWait, 0, 0, Math.min(waitTime, timeout - elapsed));
-            if (waitTime < 16)
-                waitTime *= 2;
-        }
-    }
-    return true;
-}
 /**
  * Persists the failure marker for a build that ended without running one of runIndexing's own exit
  * paths, so something re-triggers it. Fenced on `indexingBuildId` inside the storage engine's catalog
@@ -2141,17 +3260,12 @@ async function markAbandonedIndexBuild(Table, rootStore, buildIds) {
                 }
             };
             if (rootStore instanceof rocksdb_js_1.RocksDatabase) {
-                if (!tryAcquireUpdateAttributesLock(rootStore)) {
-                    logger.warn(`Could not mark the abandoned index build of ${Table.databaseName}.${Table.tableName}.${attribute.name}: ` +
-                        `timed out after ${exports.ABANDONED_MARK_LOCK_TIMEOUT}ms waiting for the exclusive 'update-attributes' lock. ` +
-                        `The index stays incomplete and the next load of the table re-triggers the backfill.`);
-                    continue;
-                }
+                (0, Table_ts_1.acquireUpdateAttributesLock)(rootStore, `abandoned index build '${Table.tableName}.${attribute.name}'`);
                 try {
                     markIfOwned();
                 }
                 finally {
-                    rootStore.unlock('update-attributes');
+                    (0, Table_ts_1.releaseUpdateAttributesLock)(rootStore);
                 }
             }
             else {
@@ -2171,7 +3285,7 @@ async function markAbandonedIndexBuild(Table, rootStore, buildIds) {
         }
     }
 }
-async function runIndexing(Table, attributes, indicesToRemove) {
+async function runIndexing(Table, attributes, indicesToRemove, branchPath) {
     let checkpointing;
     let hadIndexingErrors = false;
     const attributeErrorReported = {};
@@ -2185,7 +3299,7 @@ async function runIndexing(Table, attributes, indicesToRemove) {
     const putRejectionHandlers = attributes.map((attribute) => (error) => onIndexPutRejected(attribute.name, error));
     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;
         // The checkpoint and completion barriers have to cover every mutation still in flight: any of them
         // may reject after those barriers read hadIndexingErrors.
@@ -2221,6 +3335,7 @@ async function runIndexing(Table, attributes, indicesToRemove) {
             };
         });
         for (const index of indicesToRemove) {
+            index.customIndex?.resetDerivedStorage?.();
             track(index.drop(), (error) => onIndexPutRejected(index.name, error));
         }
         let interrupted;
@@ -2231,6 +3346,8 @@ async function runIndexing(Table, attributes, indicesToRemove) {
             const start = resumeStartKey(attributes);
             if (start === undefined) {
                 for (const attribute of attributes) {
+                    // if we are starting from the beginning, clear out any previous index entries since we are rewriting
+                    attribute.dbi.customIndex?.resetDerivedStorage?.();
                     if (attribute.dbi.clearAsync) {
                         // LMDB enqueues this ahead of the index writes, so the scan need not wait for it — but the
                         // barriers must, or a rejected clear certifies a checkpoint over stale entries.
@@ -2408,7 +3525,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);
         }
     }
@@ -2477,6 +3594,26 @@ function completeInterruptedDrop(rootStore, attributesDbi, databaseName, tableNa
                 finally {
                     columnStore.close();
                 }
+                // derived HNSW plane files live next to the store; the normal drop path removes
+                // them through the custom index, but this recovery path drops raw column stores,
+                // and a same-name recreate must never open a stale plane over a fresh CF
+                try {
+                    (0, node_fs_1.unlinkSync)((0, hnswPlaneBinding_ts_1.planeFilePathFor)(rootStore.path, columnName));
+                }
+                catch (error) {
+                    // a stale plane left behind (e.g. Windows EBUSY while still mapped) would be
+                    // opened over a fresh same-name CF, resolving another graph's node ids
+                    // against it — tombstone it so no attach ever adopts it
+                    if (error?.code !== 'ENOENT') {
+                        logger.warn(`could not delete the HNSW plane file for ${columnName}; tombstoning it as stale`, error);
+                        try {
+                            (0, node_fs_1.closeSync)((0, node_fs_1.openSync)((0, hnswPlaneBinding_ts_1.planeStalePathFor)((0, hnswPlaneBinding_ts_1.planeFilePathFor)(rootStore.path, columnName)), 'w'));
+                        }
+                        catch (tombstoneError) {
+                            logger.warn(`could not tombstone the stale HNSW plane file for ${columnName}`, tombstoneError);
+                        }
+                    }
+                }
             }
         }
     }