@harperfast/harper 5.2.9 → 5.3.0-alpha.1

package/resources/databases.ts

@@ -3,13 +3,13 @@ import { initSync, getHdbBasePath, get as envGet } from '../utility/environment/
 import { INTERNAL_DBIS_NAME } from '../utility/lmdb/terms.ts';
 import { open, compareKeys, type Database, type RootDatabase } from 'lmdb';
 import { join, extname, basename } from 'path';
-import { existsSync, readdirSync, readFileSync, mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import { unlink } from 'node:fs/promises';
 import {
 	getBaseSchemaPath,
 	getTransactionAuditStoreBasePath,
 } from '../dataLayer/harperBridge/lmdbBridge/lmdbUtility/initializePaths.js';
-import { makeTable, ignoreAlreadyDropped } from './Table.ts';
+import { makeTable, ignoreAlreadyDropped, acquireUpdateAttributesLock, releaseUpdateAttributesLock } from './Table.ts';
 import OpenEnvironmentObject from '../utility/lmdb/OpenEnvironmentObject.ts';
 import {
 	CONFIG_PARAMS,
@@ -30,7 +30,9 @@ const { forComponent } = harperLogger;
 import * as manageThreads from '../server/threads/manageThreads.js';
 import { openAuditStore, readAuditEntry, createAuditEntry, type AuditRecord } from './auditStore.ts';
 import { handleLocalTimeForGets } from './RecordEncoder.ts';
-import { deleteRootBlobPathsForDB } from './blob.ts';
+import { databasePaths, deleteRootBlobPathsForDB } from './blob.ts';
+import { removeStorageReclamation } from '../server/storageReclamation.ts';
+import { commonValidators, schemaRegex } from '../validation/common_validators.ts';
 import { CUSTOM_INDEXES } from './indexes/customIndexes.ts';
 import { OpenDBIObject } from '../utility/lmdb/OpenDBIObject.ts';
 import { RocksDatabase, supportedCompression, type RocksDatabaseOptions } from '@harperfast/rocksdb-js';
@@ -96,8 +98,74 @@ 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 = (envGet(CONFIG_PARAMS.STORAGE_PAGESIZE) || 4096) - 60; // larger than this requires multiple pages
 initSync();
+
+type RelationshipTarget = { database: string; table: string };
+type PersistedRelationship = {
+	name: string;
+	type: string;
+	elements?: { type: string };
+	relationship: { from?: string; to?: string; filterMissing?: boolean };
+	target: RelationshipTarget;
+};
+
+type RelationshipHydration = {
+	table: any;
+	databaseName: string;
+	tableName: string;
+	definitions: unknown[];
+};
+
+let relationshipsToHydrate: RelationshipHydration[] = [];
+const reportedRelationshipErrors = new Set<string>();
+// an interrupted create is reported once per table and thread, not on every rescan
+const reportedIncompleteCatalogs = new Set<string>();
+
+function normalizeRelationships(attributes: any[]): PersistedRelationship[] {
+	const relationships: PersistedRelationship[] = [];
+	for (const attribute of attributes) {
+		const target = attribute.relationshipReference;
+		if (!attribute.relationship || !target) continue;
+		const relationship: PersistedRelationship['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: PersistedRelationship = {
+			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: any, right: any): boolean {
+	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: any, right: PersistedRelationship[]): boolean {
+	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).
@@ -331,9 +399,13 @@ function openRocksDatabase(path: string, options: RocksDatabaseOptions & { dupSo
 	} else {
 		db = new PrimaryRocksDatabase(path, options).open() as unknown as RocksRootDatabase;
 		// 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 as any;
-		db.remove = db.removeSync as any;
+		db.remove = ((id: any, removeOptions?: any) =>
+			typeof removeOptions === 'number'
+				? (db as unknown as PrimaryRocksDatabase).removeIfVersion(id, removeOptions)
+				: db.removeSync(id, removeOptions)) as any;
 		(db.encoder as any).name = options.name;
 	}
 	db.env = {};
@@ -348,6 +420,32 @@ _assignPackageExport('databases', databases);
 _assignPackageExport('tables', 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: any, descriptor: any) {
+	for (const field of PEER_REDEFINABLE_FIELDS) {
+		if (field in descriptor) attribute[field] = descriptor[field];
+		else delete attribute[field];
+	}
+}
 // How many times the schema load will try to finish a tombstoned drop before
 // giving up for the rest of this process's lifetime. A drop that fails once
 // almost always fails identically forever - the usual cause is a RocksDB
@@ -429,6 +527,7 @@ export function getDatabases(): Databases {
 	loadedDatabases = true;
 
 	definedDatabases = new Map();
+	relationshipsToHydrate = [];
 	const hdbBasePath = getHdbBasePath();
 	let databasePath = hdbBasePath && join(hdbBasePath, DATABASES_DIR_NAME);
 	const schemaConfigs = envGet(CONFIG_PARAMS.DATABASES) || {};
@@ -451,9 +550,12 @@ export function getDatabases(): Databases {
 			// (out-of-band) RocksDB directory happens to occupy that reserved name — the API can't
 			// create it (schemaRegex forbids the backtick), but the scan opens any CURRENT+MANIFEST dir
 			if (databaseEntry.name === RESTORE_META_DIR) continue;
+			// branch directories are process-local derivatives, never databases in their own right
+			if (databaseEntry.name === BRANCH_ROOT_DIR) continue;
 			const dbName = basename(databaseEntry.name, '.mdb');
 			const dbPath = join(databasePath, databaseEntry.name);
 			if (blockedByRestore.has(dbName)) continue;
+			if (isOpenBranchPath(dbPath)) continue;
 
 			if (
 				databaseEntry.isFile() &&
@@ -515,7 +617,9 @@ export function getDatabases(): Databases {
 				for (const databaseEntry of entries) {
 					if (databaseEntry.name.endsWith(MIGRATING_DIR_SUFFIX)) continue; // migration staging dir
 					if (databaseEntry.name === RESTORE_META_DIR) continue; // reserved restore-metadata dir
+					if (databaseEntry.name === BRANCH_ROOT_DIR) continue; // reserved branch root
 					if (blockedByRestore.has(basename(databaseEntry.name, '.mdb'))) continue;
+					if (isOpenBranchPath(join(databasePath, databaseEntry.name))) continue;
 					if (databaseEntry.isFile() && extname(databaseEntry.name).toLowerCase() === '.mdb') {
 						readMetaDb(join(databasePath, databaseEntry.name), basename(databaseEntry.name, '.mdb'), dbName);
 					} else {
@@ -560,10 +664,13 @@ export function getDatabases(): Databases {
 			for (const tableName in tables) {
 				if (!definedTables.has(tableName)) {
 					logger.trace(`delete table class ${tableName}`);
+					tables[tableName]?.cleanup?.();
 					delete tables[tableName];
 				}
 			}
 		} else {
+			const removedTables = databases[dbName];
+			for (const tableName in removedTables) removedTables[tableName]?.cleanup?.();
 			delete databases[dbName];
 			if (dbName === 'data') {
 				for (const tableName in tables) {
@@ -573,6 +680,7 @@ export function getDatabases(): Databases {
 			}
 		}
 	}
+	hydrateCatalogRelationships();
 	if (envGet(CONFIG_PARAMS.ANALYTICS_REPLICATE) === false) {
 		if (!NON_REPLICATING_SYSTEM_TABLES.includes('hdb_analytics')) NON_REPLICATING_SYSTEM_TABLES.push('hdb_analytics');
 	} else {
@@ -590,6 +698,171 @@ export function getDatabases(): Databases {
 	return 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.
+ */
+export function hydrateBranchRelationships(branch: BranchDatabase, branches: Map<string, BranchDatabase>): void {
+	const resolveTarget: ResolveRelationshipTarget = (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] : 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(): void {
+	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
+				);
+			}
+		}
+	}
+}
+
+type ResolveRelationshipTarget = (target: RelationshipTarget) => any;
+
+const resolveTargetGlobally: ResolveRelationshipTarget = (target) => databases[target.database]?.[target.table];
+
+function hydrateTableRelationships(
+	{ table, databaseName, tableName, definitions }: RelationshipHydration,
+	resolveTarget: ResolveRelationshipTarget = resolveTargetGlobally,
+	announce = true
+): void {
+	const hydratable: { definition: PersistedRelationship; targetTable: any }[] = [];
+	for (let index = 0; index < definitions.length; index++) {
+		const definition = definitions[index] as PersistedRelationship;
+		// 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 as any)?.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) databaseEventsEmitter.emit('updateTable', table);
+}
+
+function validRelationshipDefinition(definition: any, definitions: unknown[], index: number): boolean {
+	if (!definition || typeof definition !== 'object') return false;
+	const validName = (value: any) => 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] as any)?.name === definition.name) return false;
+	return true;
+}
+
+function relationshipFieldsExist(sourceTable: any, targetTable: any, definition: PersistedRelationship): boolean {
+	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: PersistedRelationship, targetTable: any): any {
+	const attribute: any = {
+		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: string, message: string): void {
+	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
@@ -637,14 +910,19 @@ export function readMetaDb(
 			lmdbDatabaseEnvs.set(path, rootStore);
 		}
 
-		return initStores(path, rootStore, databaseName, defaultTable, auditPath, isLegacy);
+		return initStores(path, rootStore, databaseName, { defaultTable, auditPath, isLegacy });
 	} catch (error) {
 		error.message += ` opening database ${path}`;
 		throw error;
 	}
 }
 
-function readRocksMetaDb(path: string, defaultTable?: string, databaseName: string = DEFAULT_DATABASE_NAME) {
+function readRocksMetaDb(
+	path: string,
+	defaultTable?: string,
+	databaseName: string = DEFAULT_DATABASE_NAME,
+	{ destination, storeName, openedStores }: Pick<InitStoresOptions, 'destination' | 'storeName' | 'openedStores'> = {}
+) {
 	try {
 		logger.trace(`loading rocksdb database: ${path}`);
 
@@ -657,13 +935,17 @@ function readRocksMetaDb(path: string, defaultTable?: string, databaseName: stri
 
 		let rootStore: RocksRootDatabase | undefined = 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 }) as any;
 			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) {
 				replayLogs(rootStore, databases[databaseName]);
 			}
 		}
@@ -674,14 +956,32 @@ function readRocksMetaDb(path: string, defaultTable?: string, databaseName: stri
 	}
 }
 
+interface InitStoresOptions {
+	defaultTable?: string;
+	auditPath?: string;
+	isLegacy?: boolean;
+	/** Build the Table classes here instead of the global `databases` map, and emit no global event. */
+	destination?: Tables;
+	/**
+	 * Identity stamped on the root store, when it must differ from the logical `databaseName` the
+	 * Table classes carry. `getRootBlobPathsForDB` resolves blob directories from it.
+	 */
+	storeName?: string;
+	/**
+	 * Every column family opened here is appended, so a caller can release the ones a failure left
+	 * unreachable — a table's stores are opened well before `setTable` publishes it into the graph.
+	 */
+	openedStores?: any[];
+}
+
 function initStores(
 	path: string,
 	rootStore: RootDatabaseKind,
 	databaseName: string,
-	defaultTable?: string,
-	auditPath?: string,
-	isLegacy?: boolean
+	{ defaultTable, auditPath, isLegacy, destination, storeName, openedStores }: InitStoresOptions = {}
 ) {
+	// 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(path, isReadOnlyMode());
 	const internalDbiInit = createOpenDBIObject(false);
 	let attributesDbi = rootStore.dbisDb;
@@ -695,6 +995,7 @@ function initStores(
 		} else {
 			attributesDbi = rootStore.openDB(INTERNAL_DBIS_NAME, internalDbiInit as any);
 		}
+		openedStores?.push(attributesDbi);
 		rootStore.dbisDb = markInternalDbiNonVersioned(attributesDbi);
 	}
 
@@ -721,7 +1022,8 @@ function initStores(
 		}
 	}
 
-	const tables = ensureDB(databaseName);
+	const tables = destination ?? ensureDB(databaseName);
+	if (destination && !destination[DEFINED_TABLES]) destination[DEFINED_TABLES] = new Set<string>();
 	const definedTables = tables[DEFINED_TABLES];
 	(definedTables as any).rootStore = rootStore;
 	const tablesToLoad = new Map<string, any>();
@@ -819,12 +1121,21 @@ function initStores(
 				}
 			}
 			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)
@@ -871,18 +1182,14 @@ function initStores(
 			// per-table override of the storage.randomAccessFields default (see OpenDBIObject)
 			if (typeof primaryAttribute.randomAccessFields === 'boolean')
 				dbiInit.randomAccessStructure = primaryAttribute.randomAccessFields;
-			if (rootStore instanceof RocksDatabase) {
-				primaryStore = handleLocalTimeForGets(
-					openRocksDatabase(rootStore.path, { ...dbiInit, name: primaryAttribute.key, cache: true } as any),
-					rootStore
-				);
-			} else {
-				primaryStore = handleLocalTimeForGets(
-					(rootStore as any).openDB(primaryAttribute.key, dbiInit as any),
-					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 RocksDatabase
+					? openRocksDatabase(rootStore.path, { ...dbiInit, name: primaryAttribute.key, cache: true } as any)
+					: (rootStore as any).openDB(primaryAttribute.key, dbiInit as any);
+			openedStores?.push(opened);
+			primaryStore = handleLocalTimeForGets(opened, rootStore);
 			primaryStore.tableId = tableId;
 		}
 		let attributesUpdated: boolean;
@@ -893,6 +1200,7 @@ function initStores(
 				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;
 					}
@@ -971,6 +1279,8 @@ function initStores(
 				tables,
 				tableName,
 				makeTable({
+					// A branch builds into a caller-owned destination; its tables must refuse DDL.
+					isBranch: Boolean(destination),
 					primaryStore,
 					auditStore,
 					audit,
@@ -993,12 +1303,430 @@ function initStores(
 				})
 			);
 			table.schemaVersion = 1;
-			databaseEventsEmitter.emit('updateTable', table);
+			if (!destination) databaseEventsEmitter.emit('updateTable', table);
+		}
+		if (Array.isArray(primaryAttribute.relationships)) {
+			relationshipsToHydrate.push({ table, databaseName, tableName, definitions: primaryAttribute.relationships });
+		} else if (primaryAttribute.relationships !== undefined) {
+			reportRelationshipError(
+				`${databaseName}.${tableName}:list`,
+				`Ignoring invalid persisted relationship list for ${databaseName}.${tableName}`
+			);
+			relationshipsToHydrate.push({ table, databaseName, tableName, definitions: [] });
 		}
 	}
 	return rootStore;
 }
 
+/**
+ * Branch directories live beside the base database's own storage root, never under the HDB root: a
+ * database can be placed on its own volume, and `createCheckpoint` only hardlinks when source and
+ * target share a filesystem — off-volume it degrades to a full byte copy, which is the property the
+ * whole feature rests on.
+ *
+ * The backticks are what make the name reserved rather than merely conventional: `schemaRegex`
+ * (validation/common_validators.ts) excludes 0x60, so no database can ever be created under this
+ * name and shadow the branch root -- the same protection RESTORE_META_DIR uses.
+ */
+export const 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.
+ */
+export function resolveBranchPath(baseName: string, appName: string): string {
+	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 join(resolveDatabaseStorageRoot(baseName), BRANCH_ROOT_DIR, appName, baseName);
+}
+
+/** A branch's private table graph plus the handle needed to tear it down. */
+export interface BranchDatabase {
+	tables: Tables;
+	rootStore: RootDatabaseKind;
+	/** The realpath of the branch directory; what a schema-change signal names to address this branch. */
+	path: string;
+	/** The logical name the application uses (`data`); every Table class in `tables` carries it. */
+	databaseName: string;
+	/** The branch's own store identity, which its blob roots resolve from. */
+	storeName: string;
+	/**
+	 * Every column-family wrapper opened on this store -- by the open, by a reload, or by a table
+	 * declaration -- so `close()` can release them all. Recorded at acquisition rather than
+	 * reconstructed from `tables` at close: a re-declaration displaces the index and catalog wrappers it
+	 * replaces, and a failed declaration can leave one that no class ever held.
+	 */
+	openedStores: any[];
+	/**
+	 * Relationships this branch's tables declared, still un-hydrated. They cannot be resolved at open
+	 * time: a branch's definitions name the BASE database (its tables carry the base's logical names),
+	 * so resolving them through the global map would point the application's relationship reads at the
+	 * base. `hydrateBranchRelationships` finishes the job once the whole branch set is known.
+	 */
+	pendingRelationships: RelationshipHydration[];
+	/**
+	 * The application's whole branch set, once `prepareBranches` has opened it, so a reload can hydrate
+	 * a relationship whose target the application also branched against that branch.
+	 */
+	relatedBranches?: Map<string, BranchDatabase>;
+	close(): void;
+}
+
+/** `undefined` marks a path reserved by an open still in flight, which owns it just as firmly. */
+const openBranches = new Map<string, BranchDatabase | undefined>();
+/** Store identities in use, so two branches cannot resolve one set of blob roots. */
+const openBranchIdentities = new Set<string>();
+
+/**
+ * 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).
+ */
+export const BRANCH_REMOVING_SUFFIX = '`removing`';
+function branchIdentityPair(storeName: string): string[] {
+	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<string>();
+
+export function quarantineBranchIdentity(storeName: string): void {
+	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: string): boolean {
+	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(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: string, description: string): void {
+	if (
+		!name ||
+		name.length > commonValidators.schema_length.maximum ||
+		!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.
+ */
+export function assertBranchIdentityAvailable(storeName: string): void {
+	// 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 (
+			databases[name] ||
+			definedDatabases?.has(name) ||
+			openBranchIdentities.has(name) ||
+			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: string, storeName: string): boolean {
+	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.
+ */
+export function reserveBranchIdentity(storeName: string): void {
+	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.
+ */
+export function retakeBranchIdentity(storeName: string): void {
+	for (const name of branchIdentityPair(storeName)) {
+		openBranchIdentities.add(name);
+		quarantinedBranchIdentities.delete(name);
+	}
+}
+
+export function releaseBranchIdentity(storeName: string): void {
+	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. */
+export function isBranchIdentity(name: string): boolean {
+	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: string): boolean {
+	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 existsSync(branchPath) || existsSync(branchPath + 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.
+ */
+export function openBranchDatabase(
+	path: string,
+	databaseName: string,
+	storeName: string,
+	blobRoots?: string[]
+): BranchDatabase {
+	assertLegalBranchName(databaseName, 'logical database name');
+	assertLegalBranchName(storeName, 'store identity');
+	if (!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 = 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: 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: any[] = [];
+	// 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: RootDatabaseKind;
+	// claim the path before the open, not after: readRocksMetaDb registers the store in
+	// `rocksdbDatabaseEnvs` partway through, so anything re-entering `database()` during initStores
+	// would otherwise find the branch's store on an unowned path
+	openBranches.set(path, undefined);
+	retakeBranchIdentity(storeName);
+	try {
+		rootStore = readRocksMetaDb(path, null, databaseName, { destination: tables, storeName, openedStores });
+		// Pin the handle to the roots the caller proved this branch was published with, before it is
+		// handed out. A row's `storageIndex` is a position in that list, so resolving through current
+		// configuration instead would let an appended volume take writes at an index the branch's own
+		// completion marker never recorded -- and a later change at that index would then silently
+		// re-address them. `closeBranchHandles` clears the entry with the rest of the handle.
+		if (blobRoots) databasePaths.set(rootStore as unknown as RootDatabase, blobRoots);
+	} catch (error) {
+		openBranches.delete(path);
+		releaseBranchIdentity(storeName);
+		const stranded = rocksdbDatabaseEnvs.get(path);
+		rocksdbDatabaseEnvs.delete(path);
+		closeBranchHandles(path, stranded, openedStores, tables);
+		throw error;
+	}
+	let closed = false;
+	const branch: BranchDatabase = {
+		tables,
+		rootStore,
+		path,
+		databaseName,
+		storeName,
+		openedStores,
+		pendingRelationships: relationshipsToHydrate.splice(queuedRelationshipsAt),
+		close() {
+			// guard on the handle, not on the registrations: those are keyed by path, and a closed
+			// branch frees its path, so a stale handle would otherwise tear down its successor
+			if (closed) return;
+			closed = true;
+			openBranches.delete(path);
+			releaseBranchIdentity(storeName);
+			rocksdbDatabaseEnvs.delete(path);
+			closeBranchHandles(path, rootStore, openedStores, tables);
+		},
+	};
+	openBranches.set(path, branch);
+	return branch;
+}
+
+/**
+ * Release everything a branch open created. Each table's primary store and each index is its own
+ * column family, on top of the internal-dbis and audit families, so closing the root alone leaves
+ * all of them behind — which is why `closeDatabase` walks them individually for a real database.
+ * Two process-global registrations outlive the stores as well, neither with a lifetime of its own:
+ * a storage-reclamation handler per store path, whose closure pins the now-closed store, and the
+ * memoized blob roots in `databasePaths`. A real database is opened once per thread; harper#643
+ * makes branch open/close routine, so both would grow with branch churn.
+ */
+function closeBranchHandles(
+	path: string,
+	rootStore?: RootDatabaseKind,
+	openedStores: any[] = [],
+	tables: Tables = {}
+): void {
+	const reclamationPaths = new Set<string>([path]);
+	(rootStore as any)?.auditStore?.stopAuditCleanup?.();
+	const closeStore = (store: any, description: string) => {
+		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 as any)?.dbisDb, 'attributes store');
+	closeStore((rootStore as any)?.auditStore, 'audit store');
+	closeStore(rootStore, 'root store');
+	if (rootStore) databasePaths.delete(rootStore as RootDatabase);
+	for (const reclamationPath of reclamationPaths) removeStorageReclamation(reclamationPath);
+}
+
+/** Branches are process-local, so this is shutdown, not a data operation. */
+export function closeBranchDatabases(): void {
+	for (const branch of [...openBranches.values()]) branch?.close();
+}
+
 export function resetDatabases() {
 	loadedDatabases = false;
 	for (const store of Object.values(lmdbDatabaseEnvs)) {
@@ -1029,6 +1757,7 @@ interface TableDefinition {
 	trackDeletes?: boolean;
 	attributes: any[];
 	schemaDefined?: boolean;
+	schemaRelationshipsDefined?: boolean;
 	origin?: string;
 	description?: string;
 	properties?: Record<string, any>;
@@ -1141,6 +1870,14 @@ export function database({ database: databaseName, table: tableName }) {
 	const useRocksdb = (process.env.HARPER_STORAGE_ENGINE || envGet(CONFIG_PARAMS.STORAGE_ENGINE)) !== 'lmdb';
 	if (useRocksdb) {
 		const path = 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: any = 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
@@ -1253,6 +1990,10 @@ export async function dropDatabase(databaseName) {
 		databaseEventsEmitter.emit('dropDatabase', databaseName);
 
 		if (rootStore) {
+			// awaited: retirement stops the loop admitting work, the barrier is what says the pass that was
+			// already running has released the stores this is about to close and unlink
+			await rootStore.auditStore?.stopAuditCleanup?.();
+			removeStorageReclamation(rootStore.path);
 			if (rootStore.status === 'open') {
 				if (rootStore instanceof RocksDatabase) {
 					rootStore.close();
@@ -1267,6 +2008,8 @@ export async function dropDatabase(databaseName) {
 			// a tableless database resolves its root store here rather than in the loop above, so take
 			// the drop lock now (still before any destructive step)
 			if (rootStore instanceof RocksDatabase) lockDatabaseForDrop(rootStore.path, databaseName, restoreLocks);
+			await rootStore.auditStore?.stopAuditCleanup?.();
+			removeStorageReclamation(rootStore.path);
 			if (rootStore instanceof RocksDatabase) {
 				rootStore.close();
 				rootStore.destroy();
@@ -1304,17 +2047,27 @@ export function closeDatabase(databaseName: string): boolean {
 		const table: any = dbTables[tableName];
 		if (!table?.primaryStore) continue;
 		if (table.primaryStore.rootStore) rootStores.add(table.primaryStore.rootStore);
-		for (const indexName in table.indices || {}) {
-			closeStore(table.indices[indexName], `index ${tableName}.${indexName}`);
-		}
-		closeStore(table.primaryStore, `table ${tableName}`);
 	}
 	// a database with no tables (an empty schema, or one whose tables were all dropped) still holds
 	// an open root store, tracked only on the defined-database entry rather than any table — include
 	// it so its handles are released too (the Set dedupes it against the per-table root stores above)
 	const definedRoot = (definedDatabases?.get(databaseName) as any)?.rootStore;
 	if (definedRoot) rootStores.add(definedRoot);
+	// before any table store closes, so no further pass is admitted. This is synchronous, so it cannot
+	// await the drain barrier stopAuditCleanup() returns; what covers it is the in-pass status checks,
+	// plus the fact that its production callers reach it only for RocksDB databases, whose pass is one
+	// synchronous purgeLogs() call with nothing suspended mid-removal.
+	for (const rootStore of rootStores) rootStore.auditStore?.stopAuditCleanup?.();
+	for (const tableName in dbTables) {
+		const table: any = dbTables[tableName];
+		if (!table?.primaryStore) continue;
+		for (const indexName in table.indices || {}) {
+			closeStore(table.indices[indexName], `index ${tableName}.${indexName}`);
+		}
+		closeStore(table.primaryStore, `table ${tableName}`);
+	}
 	for (const rootStore of rootStores) {
+		removeStorageReclamation(rootStore.path);
 		closeStore(rootStore.dbisDb, 'attributes store');
 		closeStore(rootStore, 'root store');
 		lmdbDatabaseEnvs.delete(rootStore.path);
@@ -1344,8 +2097,12 @@ export function closeDatabase(databaseName: string): boolean {
  * 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.
  */
 export function closeLoadedDatabases(): void {
+	closeBranchDatabases();
 	// snapshot the names first: closeDatabase() deletes from `databases` as it goes
 	for (const databaseName of Object.keys(databases)) {
 		const dbTables = databases[databaseName];
@@ -1459,23 +2216,34 @@ function openIndex(dbiKey: string, rootStore: RootDatabaseKind, attribute: any)
 			cache: isCustomObjectIndex,
 		} as any) as any;
 		(dbi as any).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 as any).openDB(dbiKey, dbiInit as any);
+		installCustomIndex(dbi);
 	}
-	if (attribute.indexed.type) {
+	function installCustomIndex(indexStore: any) {
+		if (!attribute.indexed.type) return;
 		const CustomIndex = CUSTOM_INDEXES[attribute.indexed.type];
 		if (CustomIndex) {
-			dbi.customIndex = new CustomIndex(dbi, attribute.indexed);
+			indexStore.customIndex = new CustomIndex(indexStore, attribute.indexed);
 		} else {
 			logger.error(`The indexing type '${attribute.indexed.type}' is unknown`);
 		}
@@ -1498,6 +2266,102 @@ function openIndex(dbiKey: string, rootStore: RootDatabaseKind, attribute: any)
  * @param replicate
  */
 export function table<TableResourceType>(tableDefinition: TableDefinition): TableResourceType {
+	return declareTable(GLOBAL_TARGET, tableDefinition);
+}
+
+/**
+ * Where a declaration lands. `table()` is bound to the global catalog; a branched application's
+ * declarations are bound to its branch (`scopedTableFactory`). Everything in `declareTable` that is
+ * global by construction -- the root store, the `tables` graph a class is published into, the reload
+ * after a lost create race, who owns the handles it opens -- goes through this, and nothing else does,
+ * so the unbranched path is the same code with the same objects behind it.
+ */
+interface TableTarget {
+	rootStore(databaseName: string, tableName: string): RootDatabaseKind;
+	tables(databaseName: string): Tables;
+	/** Another thread created the table this declaration was about to; make `tables` reflect it. */
+	reload(databaseName: string): void;
+	/** Records a column-family wrapper the declaration opened, for whoever closes the store. */
+	adopt(store: any): void;
+	/** Set for a branch: its Table classes refuse DDL, and its schema signals address it by path. */
+	branch?: BranchDatabase;
+}
+
+const GLOBAL_TARGET: TableTarget = {
+	rootStore: (databaseName, tableName) => database({ database: databaseName, table: tableName }),
+	tables: (databaseName) => databases[databaseName],
+	reload: () => resetDatabases(),
+	// a real database's stores live until the process (or `closeDatabase`, which walks the graph) ends
+	adopt: () => {},
+};
+
+/**
+ * The factory a branched application declares tables through: each declaration goes to the branch
+ * of the database it names, or to `table()` itself for a database the application did not branch.
+ * An unbranched application gets `table` by identity -- no wrapper, no per-call routing.
+ */
+export function scopedTableFactory(branches?: Map<string, BranchDatabase>): typeof table {
+	if (!branches?.size) return table;
+	return function scopedTable<TableResourceType>(tableDefinition: TableDefinition): TableResourceType {
+		// `||`, 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: BranchDatabase): TableTarget {
+	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: BranchDatabase): void {
+	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: BranchDatabase, hydration: RelationshipHydration): void {
+	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.
+ */
+export function reloadBranchAt(path: string): Tables | undefined {
+	const branch = openBranches.get(path);
+	if (!branch) return undefined;
+	reloadBranch(branch);
+	return branch.tables;
+}
+
+function declareTable<TableResourceType>(target: TableTarget, tableDefinition: TableDefinition): TableResourceType {
 	let {
 		table: tableName,
 		database: databaseName,
@@ -1512,6 +2376,7 @@ export function table<TableResourceType>(tableDefinition: TableDefinition): Tabl
 		randomAccessFields,
 		trackDeletes,
 		schemaDefined,
+		schemaRelationshipsDefined,
 		origin,
 		description,
 		properties,
@@ -1529,8 +2394,14 @@ export function table<TableResourceType>(tableDefinition: TableDefinition): Tabl
 	if ((RESERVED_DATABASE_NAMES as readonly string[]).includes(databaseName)) {
 		throw new ClientError(`'${databaseName}' is a reserved name and cannot be used as a database name`);
 	}
-	const rootStore = database({ database: databaseName, table: tableName });
-	const tables = 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 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') {
@@ -1544,6 +2415,7 @@ export function table<TableResourceType>(tableDefinition: TableDefinition): Tabl
 	// flag must be left as-is. Only an explicit value can re-assert on the existing-Table branch.
 	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) {
@@ -1555,113 +2427,160 @@ export function table<TableResourceType>(tableDefinition: TableDefinition): Tabl
 		if (attribute.expiresAt) attribute.indexed = true;
 	}
 	let hasChanges;
-	let releaseExclusiveLock: () => void;
-	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 deferredPrimaryRow: any;
+	let unpublishedPrimaryStore: any;
+	let published = false;
+	let releaseExclusiveLock: (() => void) | undefined;
+	const attributesToIndex = [];
+	const indicesToRemove = [];
+	try {
+		if (Table) {
+			primaryKey = Table.primaryKey;
+			if (Table.primaryStore.rootStore.status === 'closed') {
+				throw new Error(`Can not use a closed data store from ${tableName} class`);
 			}
-			if (hasRecords) {
-				throw new 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
-				);
+			// 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 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 : envGet(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 RocksDatabase) {
-			attributesDbi = (rootStore as any).dbisDb = openRocksDatabase(rootStore.path, {
-				...internalDbiInit,
-				disableWAL: false,
-				name: INTERNAL_DBIS_NAME,
-			} as any);
+			// Acquire before the first mutation of the live Table below, so a lost race leaves no
+			// attributes this worker describes but never persisted. Only the RocksDB acquire is bounded
+			// and can throw, and only it is cheap when uncontended: LMDB's exclusiveLock() opens an
+			// environment-wide write transaction that cannot time out, so it stays lazy.
+			if (rootStore instanceof RocksDatabase) exclusiveLock();
+			// it table already exists, get the split segments setting
+			if (splitSegments == undefined) splitSegments = Table.splitSegments;
+			if (origin === 'cluster') {
+				const merged = Table.attributes.slice();
+				for (const attribute of attributes) {
+					const existing = merged.find((existingAttribute) => existingAttribute.name === attribute.name);
+					if (!existing) {
+						merged.push(attribute);
+						continue;
+					}
+					// Nodes that apply the same peer definitions in a different order keep different index sets, and
+					// this warn is the only signal of it. An absent field and an explicit falsy one declare the same
+					// thing, so neither direction of that pair is a difference.
+					const discarded = PEER_DECLARABLE_FIELDS.filter(
+						(field) =>
+							(attribute[field] || existing[field]) &&
+							JSON.stringify(attribute[field]) !== JSON.stringify(existing[field])
+					);
+					if (discarded.length > 0)
+						logger.warn(
+							`Ignoring peer redefinition of ${databaseName}.${tableName}.${attribute.name} (${discarded
+								.map(
+									(field) =>
+										`${field}: local ${JSON.stringify(existing[field])}, peer ${JSON.stringify(attribute[field])}`
+								)
+								.join('; ')}); the local schema is authoritative`
+						);
+				}
+				attributes = merged;
+			}
+			Table.attributes.splice(0, Table.attributes.length, ...attributes);
+			// Re-assert from the live declaration so a stale value on disk (replicated event,
+			// v4-era backfill) is corrected on every reload. Gated on `schemaDefinedExplicit` so
+			// callers that omit the flag (cluster schema-replication, data loader) don't flip a
+			// dynamic table to true via the default at the top of table(), and on origin so a
+			// peer-derived definition never overrides the local declaration.
+			if (schemaDefinedExplicit && origin !== 'cluster') Table.schemaDefined = schemaDefined;
+			// Refresh class-level schema metadata to track docstring/directive changes across reloads.
+			Table.description = description;
+			Table.properties = properties;
+			Table.hidden = hidden;
+			// undefined means a non-schema caller (add_attribute, cluster schema events) — don't clobber
+			if (cacheControl !== undefined) Table.cacheControl = cacheControl;
 		} else {
-			attributesDbi = (rootStore as any).dbisDb = (rootStore as any).openDB(INTERNAL_DBIS_NAME, internalDbiInit as any);
-		}
-		markInternalDbiNonVersioned(attributesDbi);
+			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 : envGet(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 + '/';
 
-		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 as any).getSync(dbiName);
-		if (existingTableMeta && !existingTableMeta.dropping) {
-			// table was created while we were setting up
-			if (releaseExclusiveLock) releaseExclusiveLock();
-			resetDatabases();
-			return table(tableDefinition);
-		}
+			if (rootStore instanceof RocksDatabase) {
+				attributesDbi = (rootStore as any).dbisDb = openRocksDatabase(rootStore.path, {
+					...internalDbiInit,
+					disableWAL: false,
+					name: INTERNAL_DBIS_NAME,
+				} as any);
+			} else {
+				attributesDbi = (rootStore as any).dbisDb = (rootStore as any).openDB(
+					INTERNAL_DBIS_NAME,
+					internalDbiInit as any
+				);
+			}
+			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 as any).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;
-		try {
+			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
@@ -1688,124 +2607,127 @@ export function table<TableResourceType>(tableDefinition: TableDefinition): Tabl
 			} else {
 				primaryStore = (rootStore as any).openDB(dbiName, dbiInit as any);
 			}
+			target.adopt(primaryStore);
+			unpublishedPrimaryStore = primaryStore;
 			primaryStore = 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,
+			Table = makeTable({
+				isBranch: Boolean(target.branch),
+				primaryStore,
+				auditStore,
+				audit,
+				sealed,
+				splitSegments,
+				replicate,
+				trackDeletes,
+				expirationMS: expiration && expiration * 1000,
+				evictionMS: eviction && eviction * 1000,
+				primaryKey,
 				tableName,
-				makeTable({
-					primaryStore,
-					auditStore,
-					audit,
-					sealed,
-					splitSegments,
-					replicate,
-					trackDeletes,
-					expirationMS: expiration && expiration * 1000,
-					evictionMS: eviction && eviction * 1000,
-					primaryKey,
-					tableName,
-					tableId: primaryStore.tableId,
-					databasePath: databaseName,
-					databaseName,
-					indices: {},
-					attributes,
-					schemaDefined,
-					dbisDB: attributesDbi,
-					description,
-					properties,
-					hidden,
-					cacheControl,
-				})
-			);
+				tableId: primaryStore.tableId,
+				databasePath: databaseName,
+				databaseName,
+				indices: {},
+				attributes,
+				schemaDefined,
+				dbisDB: attributesDbi,
+				description,
+				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 RocksDatabase) {
-			(rootStore as any).dbisDb = openRocksDatabase(rootStore.path, {
-				...internalDbiInit,
-				disableWAL: false,
-				name: INTERNAL_DBIS_NAME,
-			} as any);
-		} else {
-			(rootStore as any).dbisDb = (rootStore as any).openDB(INTERNAL_DBIS_NAME, internalDbiInit as any);
+			deferredPrimaryRow = primaryKeyAttribute;
 		}
-		attributesDbi = markInternalDbiNonVersioned((rootStore as any).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) continue;
-		} else {
-			// table attribute for a table with no primary key, we don't want to remove this, so continue on
-			continue;
+		const indices = Table.indices;
+		if (!attributesDbi) {
+			if (rootStore instanceof RocksDatabase) {
+				(rootStore as any).dbisDb = openRocksDatabase(rootStore.path, {
+					...internalDbiInit,
+					disableWAL: false,
+					name: INTERNAL_DBIS_NAME,
+				} as any);
+			} else {
+				(rootStore as any).dbisDb = (rootStore as any).openDB(INTERNAL_DBIS_NAME, internalDbiInit as any);
+			}
+			target.adopt((rootStore as any).dbisDb);
+			attributesDbi = markInternalDbiNonVersioned((rootStore as any).dbisDb);
 		}
-		const attribute = attributes.find((attribute) => attribute.name === attribute_name);
-		const removeIndex = !attribute?.indexed && value.indexed && !value.isPrimaryKey;
-		if (!attribute || removeIndex) {
-			exclusiveLock();
-			hasChanges = true;
-			if (!attribute) attributesDbi.remove(key);
-			if (removeIndex) {
-				const indexDbi = Table.indices[attributeTableName];
-				if (indexDbi) indicesToRemove.push(indexDbi);
+		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 || Boolean(deferredPrimaryRow);
+			if (staleRow || removeIndex) {
+				exclusiveLock();
+				hasChanges = true;
+				if (staleRow) attributesDbi.remove(key);
+				if (removeIndex) {
+					const indexDbi = Table.indices[attributeTableName];
+					if (indexDbi) indicesToRemove.push(indexDbi);
+				}
 			}
 		}
-	}
-	const attributesToIndex = [];
-	try {
 		// TODO: If we have attributes and the schemaDefined flag is not set, turn it on
 		// iterate through the attributes to ensure that we have all the dbis created and indexed
 		for (const attribute of attributes || []) {
-			if (attribute.relationship || attribute.computed) {
-				hasChanges = true; // need to update the table so the computed properties are translated to property resolvers
-				if (attribute.relationship) continue;
+			if (attribute.relationship) {
+				refreshRelationshipAttributes = true;
+				continue;
 			}
+			if (attribute.computed) hasChanges = true;
 			let dbiKey = tableName + '/' + (attribute.name || '');
 			Object.defineProperty(attribute, 'key', { value: dbiKey, configurable: true });
 			let attributeDescriptor = attributesDbi.getSync(dbiKey);
 			if (attribute.isPrimaryKey) {
+				if (deferredPrimaryRow) continue;
 				attributeDescriptor = attributeDescriptor || attributesDbi.getSync((dbiKey = tableName + '/')) || {};
 				// Persist schemaDefined when the explicit live value disagrees with disk. Without this,
 				// a stale `false` (from a v4-era write or replicated event) survives every reload: the
 				// in-memory re-assert in the existing-Table branch only fixes the worker that ran @table,
-				// but other workers' next disk-load re-reads the stale value.
+				// but other workers' next disk-load re-reads the stale value. The whole settings update is
+				// gated off for cluster-origin callers: their values come from this worker's (possibly
+				// stale) snapshot, so a rewrite could revert a newer local declaration already on disk.
 				const schemaDefinedMismatch = schemaDefinedExplicit && attributeDescriptor.schemaDefined !== schemaDefined;
 				// primary key can't change indexing, but settings can change
 				if (
-					schemaDefinedMismatch ||
-					(audit !== undefined && audit !== Table.audit) ||
-					(sealed !== undefined && sealed !== Table.sealed) ||
-					(replicate !== undefined && replicate !== Table.replicate) ||
-					(+expiration || undefined) !== (+attributeDescriptor.expiration || undefined) ||
-					(+eviction || undefined) !== (+attributeDescriptor.eviction || undefined) ||
-					attribute.type !== attributeDescriptor.type
+					origin !== 'cluster' &&
+					(schemaDefinedMismatch ||
+						(audit !== undefined && audit !== Table.audit) ||
+						(sealed !== undefined && sealed !== Table.sealed) ||
+						(replicate !== undefined && replicate !== Table.replicate) ||
+						(+expiration || undefined) !== (+attributeDescriptor.expiration || undefined) ||
+						(+eviction || undefined) !== (+attributeDescriptor.eviction || undefined) ||
+						attribute.type !== attributeDescriptor.type)
 				) {
-					const updatedPrimaryAttribute = { ...attributeDescriptor };
+					exclusiveLock();
+					const currentPrimaryAttribute = attributesDbi.getSync(dbiKey);
+					if (!currentPrimaryAttribute || tableIsDropping(currentPrimaryAttribute, dbiKey)) continue;
+					const updatedPrimaryAttribute = { ...currentPrimaryAttribute };
 					if (typeof audit === 'boolean') {
 						if (audit) Table.enableAuditing();
 						updatedPrimaryAttribute.audit = audit;
@@ -1817,15 +2739,54 @@ export function table<TableResourceType>(tableDefinition: TableDefinition): Tabl
 					if (attribute.type) updatedPrimaryAttribute.type = attribute.type;
 					if (schemaDefinedMismatch) updatedPrimaryAttribute.schemaDefined = schemaDefined;
 					hasChanges = true; // send out notification of the change
-					exclusiveLock();
 					attributesDbi.put(dbiKey, updatedPrimaryAttribute);
 				}
 
 				continue;
 			}
 
-			// note that non-indexed attributes do not need a dbi
 			if (attributeDescriptor?.attribute && !attributeDescriptor.name) attributeDescriptor.indexed = true; // legacy descriptor
+
+			if (origin === 'cluster' && attributeDescriptor) {
+				// An existing descriptor is a local declaration this caller may not have seen yet, so it wins
+				// over the incoming definition and is never written back from it.
+				applyDurableDeclaration(attribute, attributeDescriptor);
+				const abandonedIndexBuild =
+					attribute.indexed &&
+					(attributeDescriptor.indexingFailed ||
+						(attributeDescriptor.indexingPID && attributeDescriptor.indexingPID !== process.pid) ||
+						attributeDescriptor.restartNumber < (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`.
@@ -1869,6 +2830,8 @@ export function table<TableResourceType>(tableDefinition: TableDefinition): Tabl
 				// on the main thread, where workerData is undefined (and it is initialized to 1).
 				const currentRestartGeneration = 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
@@ -1985,23 +2948,61 @@ export function table<TableResourceType>(tableDefinition: TableDefinition): Tabl
 				attributesDbi.put(dbiKey, attribute);
 			}
 		}
+		// The primary row is what makes a table loadable, so it lands last: a scan on another thread that
+		// runs mid-create skips the table instead of building (and announcing) a partial one. It already
+		// carries this table's relationships (set on primaryKeyAttribute above), so the persistence block
+		// below is a no-op for a create — a table is never published with an incomplete relationship list.
+		if (deferredPrimaryRow) {
+			attributesDbi.put(tableName + '/', deferredPrimaryRow);
+			// That write, not the registration below, is the publish point: it is durable from here
+			// (on LMDB releaseLock()'s finally commits this create's write transaction even while an
+			// error unwinds), so any later throw must leave the catalog alone. Rolling back past it
+			// would delete the attribute rows out from under a live primary row and leave every
+			// thread loading the primary-only schema this change exists to prevent.
+			published = true;
+			setTable(tables, tableName, Table);
+		}
+		// a table with no declared primary key has no attribute row to carry relationships, and the
+		// loop above never visits its descriptor
+		if (relationshipDefinitions) {
+			const relationshipsKey = primaryDescriptorKey();
+			if (!relationshipListsEqual(attributesDbi.getSync(relationshipsKey)?.relationships, relationshipDefinitions)) {
+				exclusiveLock();
+				const currentPrimaryAttribute = attributesDbi.getSync(relationshipsKey);
+				// a missing row means a concurrent drop completed; writing one back would resurrect the table
+				if (
+					currentPrimaryAttribute &&
+					!tableIsDropping(currentPrimaryAttribute, relationshipsKey) &&
+					!relationshipListsEqual(currentPrimaryAttribute.relationships, relationshipDefinitions)
+				) {
+					attributesDbi.put(relationshipsKey, { ...currentPrimaryAttribute, relationships: relationshipDefinitions });
+					hasChanges = true;
+				}
+			}
+		}
+	} catch (error) {
+		if (unpublishedPrimaryStore && !published) discardUnpublishedTable();
+		else if (published && tables[tableName] !== Table) discardUnregisteredClass();
+		throw error;
 	} finally {
-		if (releaseExclusiveLock) releaseExclusiveLock();
+		releaseLock();
 	}
-	if (hasChanges) {
+	if (hasChanges || refreshRelationshipAttributes) {
 		Table.schemaVersion++;
 		Table.updatedAttributes();
 	}
 	logger.trace(`${tableName} table loading, running index`);
+	const branchPath = target.branch?.path;
 	if (attributesToIndex.length > 0 || indicesToRemove.length > 0) {
-		Table.indexingOperation = runIndexing(Table, attributesToIndex, indicesToRemove);
+		Table.indexingOperation = runIndexing(Table, attributesToIndex, indicesToRemove, branchPath);
 	} else if (hasChanges)
 		signalling.signalSchemaChange(
-			new SchemaEventMsg(process.pid, 'schema-change', Table.databaseName, Table.tableName)
+			new SchemaEventMsg(process.pid, 'schema-change', Table.databaseName, Table.tableName, undefined, branchPath)
 		);
 
 	Table.origin = origin;
-	if (hasChanges) {
+	// scope-private: replication and other global subscribers must not learn of a branch class
+	if ((hasChanges || refreshRelationshipAttributes) && !target.branch) {
 		databaseEventsEmitter.emit('updateTable', Table, origin !== 'cluster');
 	}
 	if (expiration || eviction || scanInterval)
@@ -2013,14 +3014,64 @@ export function table<TableResourceType>(tableDefinition: TableDefinition): Tabl
 	logger.trace(`${tableName} table loaded`);
 
 	return Table as TableResourceType;
+	// dropTable() tombstones the bare table row, which is not the row a legacy catalog keeps the
+	// table's settings in, so a drop in flight has to be checked on both.
+	function tableIsDropping(descriptor: any, descriptorKey: string) {
+		if (descriptor?.dropping) return true;
+		return descriptorKey !== tableName + '/' && attributesDbi.getSync(tableName + '/')?.dropping;
+	}
+	// The catalog row initStores() reads a table's settings from: the primary key's own row when it
+	// has one, and the bare table row otherwise.
+	function primaryDescriptorKey() {
+		const declaredPrimaryKey = attributes?.find((attribute) => attribute.isPrimaryKey)?.name;
+		if (declaredPrimaryKey) {
+			const attributeKey = tableName + '/' + declaredPrimaryKey;
+			if (attributesDbi.getSync(attributeKey)) return attributeKey;
+		}
+		return tableName + '/';
+	}
+	// The catalog of a published table stays, but a class the registration never accepted is
+	// unreachable, so release what makeTable() registered process-wide instead of leaving its timers
+	// and reclamation handler live for the process. The stores stay open: the table is durable, and
+	// whichever scan reloads it opens its own handles.
+	function discardUnregisteredClass() {
+		try {
+			Table.cleanup();
+		} catch (discardError) {
+			logger.warn(`Error releasing the unregistered class of ${databaseName}.${tableName}`, discardError);
+		}
+	}
+	function discardUnpublishedTable() {
+		const discard = (description: string, action: () => unknown) => {
+			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 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 RocksDatabase) {
-			while (!rootStore.tryLock('update-attributes')) {} // use a spin lock, we really need an synchronous exclusive lock here
-			releaseExclusiveLock = () => {
-				rootStore.unlock('update-attributes');
-			};
+			acquireUpdateAttributesLock(rootStore, `table '${databaseName}.${tableName}'`);
+			releaseExclusiveLock = () => releaseUpdateAttributesLock(rootStore);
 		} else {
 			// we only need an exclusive transaction lock in lmdb
 			rootStore.transactionSync(() => {
@@ -2032,6 +3083,13 @@ export function table<TableResourceType>(tableDefinition: TableDefinition): Tabl
 			});
 		}
 	}
+	// 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.
@@ -2066,11 +3124,11 @@ export function canonicalizeIndexOptions(value: any): any {
 }
 const MAX_OUTSTANDING_INDEXING = 1000;
 const MIN_OUTSTANDING_INDEXING = 10;
-async function runIndexing(Table, attributes, indicesToRemove) {
+async function runIndexing(Table, attributes, indicesToRemove, branchPath?: string) {
 	try {
 		logger.info(`Indexing ${Table.tableName} attributes`, attributes);
 		await signalling.signalSchemaChange(
-			new SchemaEventMsg(process.pid, 'schema-change', Table.databaseName, Table.tableName)
+			new SchemaEventMsg(process.pid, 'schema-change', Table.databaseName, Table.tableName, undefined, branchPath)
 		);
 		let lastResolution;
 		for (const index of indicesToRemove) {
@@ -2234,7 +3292,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 SchemaEventMsg(process.pid, 'indexing-finished', Table.databaseName, Table.tableName)
+				new SchemaEventMsg(process.pid, 'indexing-finished', Table.databaseName, Table.tableName, undefined, branchPath)
 			);
 			logger.info(`Finished indexing ${Table.tableName} attributes`, attributes);
 		}