@harperfast/harper 5.2.13 → 5.3.0-beta.1

package/dist/resources/branchDatabase.js

@@ -0,0 +1,892 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reportClaimProgress = reportClaimProgress;
+exports.claimDeadlineFor = claimDeadlineFor;
+exports.getOrCreateBranch = getOrCreateBranch;
+exports.closeBranchAt = closeBranchAt;
+exports.removeBranches = removeBranches;
+exports.applicationHasBranchStorage = applicationHasBranchStorage;
+exports.removeBranchesForApplication = removeBranchesForApplication;
+exports.prepareBranches = prepareBranches;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const harper_logger_ts_1 = __importDefault(require("../utility/logging/harper_logger.js"));
+const hdbTerms_ts_1 = require("../utility/hdbTerms.js");
+const common_validators_ts_1 = require("../validation/common_validators.js");
+const env = __importStar(require("../utility/environment/environmentManager.js"));
+const blobBackup_ts_1 = require("../dataLayer/blobBackup.js");
+const blob_ts_1 = require("./blob.js");
+const rocksdb_js_1 = require("@harperfast/rocksdb-js");
+const databases_ts_1 = require("./databases.js");
+const replayLogs_ts_1 = require("./replayLogs.js");
+/**
+ * Private per-application forks of a database, for running several variants of an application against
+ * isolated copies of the same data (harper#642).
+ *
+ * A fork is durable and its location is derived only from the application and database names, so it
+ * survives restarts and every node in a cluster names it identically — the identity the data needs
+ * to be addressed, and eventually replicated, cluster-wide.
+ *
+ * Every worker thread loads the same applications, so all of them ask for the same branch at once.
+ * Only one may take the checkpoint — a second `createCheckpoint` against a populated directory fails,
+ * and worse, two checkpoints would give two threads divergent private data for one application. The
+ * claim is settled through a state word in a buffer the base store shares across threads, which is
+ * the same mechanism the blob id allocator and the HNSW node counter already use.
+ */
+const UNCLAIMED = 0n;
+const CREATING = 1n;
+const READY = 2n;
+const CLAIM_STATE = 0;
+const CLAIM_PROGRESS = 1;
+const MAX_NAME_LENGTH = common_validators_ts_1.commonValidators.schema_length.maximum;
+/** How long a loser waits on a winner that reports NO progress before giving up on the branch; the
+ *  winner's replay budget is added on top where the deadline is built (`openOrCreate`). Progress is
+ *  reported per checkpoint and per cloned file, so that is the granularity this bounds: a single
+ *  unit that takes longer than the budget still expires it, which needs a byte copy (no hard links)
+ *  of one blob tens of gigabytes large. */
+const CLAIM_TIMEOUT_MS = 10 * 60 * 1000;
+// Keyed on the in-flight open, not the finished one: within a thread the losers of the claim wake on
+// READY at the same moment and would otherwise each try to open the directory the winner just opened.
+const branchesByPath = new Map();
+/**
+ * The claim word is process-local shared memory (in-process only, seeded UNCLAIMED each boot) and
+ * must stay that way: the winner's tail replay runs exactly once per boot because every boot starts
+ * from UNCLAIMED. A durable or cross-process claim would read READY on restart and silently skip
+ * recovery.
+ */
+function claimStateFor(baseName, branchPath) {
+    const baseStore = (0, databases_ts_1.database)({ database: baseName, table: undefined });
+    const seed = new BigInt64Array([UNCLAIMED, 0n]);
+    return new BigInt64Array(baseStore.getUserSharedBuffer(`branch-claim:${branchPath}`, seed.buffer));
+}
+function reportClaimProgress(state) {
+    Atomics.add(state, CLAIM_PROGRESS, 1n);
+}
+/**
+ * A deadline that follows the winner's progress rather than the clock alone. The claim window covers a
+ * hard-link clone of the base's entire blob tree, so any fixed budget is wrong for a large enough base:
+ * every waiting thread's load fails while the winner is healthily copying, the winner then publishes,
+ * and the next deploy succeeds -- so a real outage reads as a flap. Restarting the budget on each unit
+ * of reported work bounds a winner that has STOPPED rather than one that is merely slow.
+ */
+function claimDeadlineFor(state, budget) {
+    let seen = Atomics.load(state, CLAIM_PROGRESS);
+    let at = Date.now() + budget;
+    return () => {
+        const progress = Atomics.load(state, CLAIM_PROGRESS);
+        if (progress !== seen) {
+            seen = progress;
+            at = Date.now() + budget;
+        }
+        return at;
+    };
+}
+/**
+ * Reproduce the base's blob roots as the branch's own, hard-linking each file so the OS inode
+ * refcount does the reference counting: the branch and base share the bytes, each holds its own
+ * directory entry, and the data is freed only when the last link to it goes. That is what lets the
+ * branch keep its own ID allocator -- `getNextFileId` seeds from the highest filename already in its
+ * directory, and the clone carries the base's filenames -- with no shared allocator, no high-water
+ * mark, and no gated deletion (harper#644).
+ *
+ * A blob that is mid-write or already reclaimed is substituted with a marker rather than linked. A
+ * partially-written blob would otherwise be linked as a whole one, and worse, the abort that follows
+ * stamps PENDING onto that inode IN PLACE -- through the branch's link as well, since it is the same
+ * inode. The marker makes that blob fail loudly in the branch instead.
+ */
+async function cloneBlobRoots(baseName, baseRoots, branchRoots, progress) {
+    let substituted = 0;
+    let copied = 0;
+    // A row's `storageIndex` is a position in the branch's own list, and its marker records every entry.
+    for (let index = 0; index < branchRoots.length; index++) {
+        const staging = `${branchRoots[index]}.staging`;
+        await (0, promises_1.rm)(staging, { recursive: true, force: true });
+        // Created up front rather than left to the walk: a base with no blobs at all copies nothing, and
+        // the branch still needs its own (empty) root to exist so its allocator starts where the base's
+        // would have.
+        await (0, promises_1.mkdir)(staging, { recursive: true });
+        const source = baseRoots[index];
+        if (source) {
+            const counts = await (0, blobBackup_ts_1.copyTree)(source, staging, true, {
+                gone: 'blob was already reclaimed from the base when this branch was created',
+                pending: 'blob was still being written to the base when this branch was created',
+            }, progress);
+            substituted += counts.substituted;
+            copied += counts.copied;
+        }
+        await (0, promises_1.rm)(branchRoots[index], { recursive: true, force: true });
+        await (0, promises_1.mkdir)((0, node_path_1.dirname)(branchRoots[index]), { recursive: true });
+        await (0, promises_1.rename)(staging, branchRoots[index]);
+        progress();
+    }
+    if (substituted > 0) {
+        harper_logger_ts_1.default.warn?.(`Branch of '${baseName}' substituted ${substituted} blob file(s) with markers because they were ` +
+            `mid-write or already reclaimed when it was created; reads of those blobs in the branch will fail`);
+    }
+    if (copied > 0) {
+        // The hard link is the whole design: without it the branch is a second full copy of the base's
+        // blobs, taken while the application is loading, and nothing else in the log would say so.
+        harper_logger_ts_1.default.warn?.(`Branch of '${baseName}' could not hard-link ${copied} blob file(s) and copied their bytes instead; ` +
+            `on a filesystem without hard links a branch costs a full copy of the base's blobs, in disk and ` +
+            `in the time every application load that creates one takes`);
+    }
+}
+/**
+ * Remove the given blob roots and any staging siblings left by an interrupted clone. The roots are
+ * passed in rather than re-derived, because a published branch owns exactly what its completion
+ * marker recorded: deriving them from current configuration would let a `storage.blobPaths` entry
+ * added since -- one that may already hold a `<storeName>` directory restored from elsewhere --
+ * be deleted by a branch that never wrote it.
+ *
+ * Reports whether every removal succeeded, because a root left behind still belongs to this
+ * identity and the caller must not hand the name back while it does.
+ */
+async function removeBlobRoots(roots) {
+    let removed = true;
+    for (const root of roots) {
+        for (const target of [root, `${root}.staging`]) {
+            await (0, promises_1.rm)(target, { recursive: true, force: true }).catch((error) => {
+                removed = false;
+                harper_logger_ts_1.default.warn?.(`Could not remove branch blob root ${target}`, error);
+            });
+        }
+    }
+    return removed;
+}
+const COMPLETION_MARKER = '.branch-complete';
+/**
+ * Does this directory hold database data? Not "does CURRENT exist" -- a store that lost CURRENT still
+ * has its MANIFEST and SSTs, and a single missing file cannot stand for "there is nothing here to
+ * lose". Anything that answers yes is never deleted, only refused.
+ */
+function holdsStoreData(branchPath) {
+    let entries;
+    try {
+        entries = (0, node_fs_1.readdirSync)(branchPath);
+    }
+    catch {
+        return false;
+    }
+    return entries.some((name) => name === 'CURRENT' || /^(MANIFEST|OPTIONS)-/.test(name) || name.endsWith('.sst') || name.endsWith('.log'));
+}
+/**
+ * What a branch directory on disk actually is, and in particular whether it may be destroyed.
+ *
+ * A branch's blob roots live on the volumes named by `storage.blobPaths`, not inside the branch
+ * directory, so the two cannot be published by one atomic rename and nothing fsyncs either parent. A
+ * directory alone therefore proves nothing: trusting it would adopt a branch whose allocator restarts
+ * from an empty root and mints file ids its own checkpointed rows already reference. The marker,
+ * written inside staging before the single rename that publishes it, is what proves both halves
+ * landed -- and recording the roots keeps an operator adding a `blobPaths` entry from reading as
+ * damage, since the new root was never this branch's.
+ *
+ * Materialization cannot leave a marker-less branch directory, so anything marker-less that still
+ * looks like a store came from elsewhere -- a branch older than the marker, or one whose marker was
+ * lost -- and is carrying data. It is refused, never deleted.
+ */
+function readBranchState(branchPath, storeName) {
+    if (!(0, node_fs_1.existsSync)(branchPath))
+        return { state: 'absent' };
+    const looksLikeAStore = holdsStoreData(branchPath);
+    let recorded;
+    try {
+        recorded = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(branchPath, COMPLETION_MARKER), 'utf8'));
+    }
+    catch {
+        return looksLikeAStore ? { state: 'unmarked', why: 'it has no readable completion marker' } : { state: 'debris' };
+    }
+    // `JSON.parse('null')` succeeds and yields null, so this cannot go straight to a property access.
+    // An empty list would pass the prefix check below and pin the branch to no roots at all, so the
+    // first blob write would fail on an undefined path instead of here, where it can say why.
+    if (recorded == null ||
+        !Array.isArray(recorded.blobRoots) ||
+        recorded.blobRoots.length === 0 ||
+        recorded.blobRoots.some((r) => typeof r !== 'string')) {
+        // Same split as an unreadable marker above: refuse anything carrying store data, but a directory
+        // holding nothing but a bad marker has nothing to lose and must stay clearable.
+        return looksLikeAStore ? { state: 'unmarked', why: 'its completion marker is malformed' } : { state: 'debris' };
+    }
+    const configured = (0, blob_ts_1.getBlobPathsForDatabaseName)(storeName);
+    // By index, not by set: `storageIndex` on a row is a position in this list, so a reordered
+    // `storage.blobPaths` would silently resolve every row through the wrong root. A configured list
+    // that only GREW leaves every recorded index exactly where it was, which is why an appended volume
+    // is compatible where a removed, reordered or replaced one is not -- the branch goes on resolving
+    // through what it recorded, so the appended root is simply never its.
+    if (recorded.blobRoots.length > configured.length || recorded.blobRoots.some((root, i) => root !== configured[i])) {
+        return {
+            state: 'damaged',
+            problem: `its blob roots no longer match the configured storage.blobPaths ` +
+                `(recorded ${JSON.stringify(recorded.blobRoots)}, configured ${JSON.stringify(configured)})`,
+            blobRoots: recorded.blobRoots,
+        };
+    }
+    const missing = recorded.blobRoots.filter((root) => !(0, node_fs_1.existsSync)(root));
+    return missing.length
+        ? { state: 'damaged', problem: `blob root(s) are missing: ${missing.join(', ')}`, blobRoots: recorded.blobRoots }
+        : { state: 'complete', blobRoots: recorded.blobRoots };
+}
+function warnAboutUnusedBlobRoots(branchPath, storeName, blobRoots) {
+    const configured = (0, blob_ts_1.getBlobPathsForDatabaseName)(storeName);
+    if (blobRoots.length < configured.length) {
+        harper_logger_ts_1.default.warn?.(`Branch database at ${branchPath} keeps the ${blobRoots.length} blob root(s) it was published ` +
+            `with; the ${configured.length - blobRoots.length} storage.blobPaths entry(ies) added since are ` +
+            `not used by it. Its rows address roots by position, so only a branch rebuilt from the base ` +
+            `can take the added capacity.`);
+    }
+}
+/**
+ * Take the checkpoint into a temporary sibling and rename it into place, so a crash mid-copy leaves
+ * debris rather than a half-populated directory that RocksDB would then refuse to open. Reports the
+ * blob roots the marker records, which is what the branch is then pinned to.
+ */
+async function materializeBranch(baseName, branchPath, storeName, report) {
+    const staging = `${branchPath}.staging`;
+    const blobRoots = (0, blob_ts_1.getBlobPathsForDatabaseName)(storeName);
+    // Publishing an empty root list would record a marker no later load can accept, bricking the branch
+    // on every subsequent boot instead of failing here, where the configuration is the visible problem.
+    if (blobRoots.length === 0) {
+        throw new Error(`Cannot create the branch at ${branchPath}: storage.blobPaths is configured with no entries, so ` +
+            `the branch has nowhere of its own to keep blobs`);
+    }
+    const base = (0, databases_ts_1.database)({ database: baseName, table: undefined });
+    // What the base's own rows resolve through, which is not the configured list if `storage.blobPaths`
+    // changed while its store was open. Refuse before taking a checkpoint: the configuration already
+    // proves that publishing this clone would leave rows on an omitted volume unreadable.
+    const baseRoots = (0, blob_ts_1.getRootBlobPathsForDB)(base);
+    if (baseRoots.length > blobRoots.length) {
+        throw new Error(`Cannot create a branch of '${baseName}': the open base resolves through ${baseRoots.length} blob ` +
+            `root(s), but storage.blobPaths now provides ${blobRoots.length}; publishing the branch would ` +
+            `make rows on the omitted volume(s) unreadable`);
+    }
+    await (0, promises_1.rm)(staging, { recursive: true, force: true });
+    await (0, promises_1.mkdir)((0, node_path_1.dirname)(branchPath), { recursive: true });
+    try {
+        await base.createCheckpoint(staging);
+        report.progress();
+        await cloneBlobRoots(baseName, baseRoots, blobRoots, report.progress);
+        await (0, promises_1.writeFile)((0, node_path_1.join)(staging, COMPLETION_MARKER), JSON.stringify({ blobRoots }));
+        await (0, promises_1.rename)(staging, branchPath);
+        return blobRoots;
+    }
+    catch (error) {
+        await (0, promises_1.rm)(staging, { recursive: true, force: true }).catch(() => { });
+        // The blob roots too, staging siblings included: a clone that failed partway leaves the roots it
+        // already published and nothing owns them once this attempt is abandoned. Only safe because this
+        // branch never became complete -- one that did is never rebuilt, so this cannot remove the last
+        // copy of anything.
+        // Surviving roots still hold this identity's files, so the caller must not release the name.
+        if (!(await removeBlobRoots(blobRoots)))
+            report.strandedRoots();
+        throw error;
+    }
+}
+/**
+ * `Atomics.wait`/`notify` need shared memory, and `getUserSharedBuffer` hands back a plain
+ * `ArrayBuffer` when nothing else has asked for the key yet — a single-threaded process, or the
+ * first caller in. The state word still works there (load/store/compareExchange do not require
+ * sharing) and concurrent async callers within one thread still contend, so waiting falls back to
+ * polling rather than throwing.
+ */
+function isShared(state) {
+    return typeof SharedArrayBuffer !== 'undefined' && state.buffer instanceof SharedArrayBuffer;
+}
+function wakeWaiters(state) {
+    if (isShared(state))
+        Atomics.notify(state, CLAIM_STATE);
+}
+/** Wait until the claim leaves CREATING, and report the state it settled on. */
+async function awaitClaim(state, branchPath, deadline) {
+    // A progress-extended deadline has no ceiling, so a wait past the original budget must say why it is
+    // still waiting rather than reading as a hang with no thread to point at.
+    const patience = deadline();
+    let announced = false;
+    for (;;) {
+        const current = Atomics.load(state, CLAIM_STATE);
+        if (current !== CREATING)
+            return current;
+        const remaining = deadline() - Date.now();
+        if (remaining <= 0)
+            throw new Error(`Timed out waiting for another thread to create the branch at ${branchPath}`);
+        // After the timeout check, and only once the deadline itself has moved: on the clock alone this
+        // would claim the winner is alive on the very turn the wait gives up on it.
+        if (!announced && Date.now() > patience && deadline() > patience) {
+            announced = true;
+            harper_logger_ts_1.default.warn?.(`Still waiting for another thread to create the branch at ${branchPath}; it is reporting ` +
+                `progress, so this wait is extended for as long as it keeps doing so`);
+        }
+        const slice = Math.min(remaining, 1000);
+        if (isShared(state)) {
+            const wait = Atomics.waitAsync(state, CLAIM_STATE, CREATING, slice);
+            if (wait.async)
+                await wait.value;
+        }
+        else {
+            await new Promise((resolve) => setTimeout(resolve, Math.min(slice, 5)));
+        }
+    }
+}
+/**
+ * Get this process's branch of `baseName` for `appName`, creating it on first call. Concurrent
+ * callers across worker threads all receive the same branch.
+ */
+async function getOrCreateBranch(baseName, appName) {
+    const branchPath = (0, databases_ts_1.resolveBranchPath)(baseName, appName);
+    let pending = branchesByPath.get(branchPath);
+    if (!pending) {
+        pending = openOrCreate(baseName, appName, branchPath);
+        branchesByPath.set(branchPath, pending);
+        // A failed attempt must not be cached, or the application can never load on a later retry.
+        pending.catch(() => branchesByPath.delete(branchPath));
+    }
+    return (await pending).branch;
+}
+/**
+ * Two (application, database) pairs must never name one store: blob file ids restart from each
+ * store's own counter, so a shared identity means two branches minting identical file paths. Joining
+ * with a separator is not injective -- ('a__b', 'c') and ('a', 'b__c') both give 'a__b__c' -- so the
+ * application name's length goes in front, the way the directory layout keeps them separate.
+ */
+function branchStoreName(appName, baseName) {
+    return `${appName.length}_${appName}__${baseName}`;
+}
+async function openOrCreate(baseName, appName, branchPath) {
+    const claimState = claimStateFor(baseName, branchPath);
+    const storeName = branchStoreName(appName, baseName);
+    // Reserved before the claim, and so before materialization: cloning the blob tree REMOVES and
+    // replaces the root this identity resolves to, while `openBranchDatabase`'s own copy of this check
+    // runs only after that has happened. A database created while the checkpoint is still copying
+    // cannot take the same name.
+    (0, databases_ts_1.reserveBranchIdentity)(storeName);
+    let handedOver = false;
+    // An abandoned attempt whose roots could not be removed does not hand the name back to a DATABASE:
+    // those roots still hold this identity's files, and a database created under the name would resolve
+    // its own new ids onto them. The branch may still retake it, which is what repairs the condition.
+    let blobRootsStranded = false;
+    try {
+        // The claim's CREATING window now covers the winner's replay as well as its checkpoint, so
+        // waiters must outlast the replay budget too, or a merely slow (but live) recovery would time
+        // out every other thread's application load minutes before the winner publishes READY. The
+        // clone in between is unbounded in the base's size, which is why the budget follows progress.
+        const deadline = claimDeadlineFor(claimState, CLAIM_TIMEOUT_MS + (0, replayLogs_ts_1.replayTimeBudgetMs)());
+        for (;;) {
+            // The deadline bounds the whole protocol, not just a single wait: an unexpected state word --
+            // a future state, a buffer another version wrote -- must fail this load, never spin forever.
+            if (Date.now() > deadline())
+                throw new Error(`Timed out claiming the branch at ${branchPath}`);
+            const previous = Atomics.compareExchange(claimState, CLAIM_STATE, UNCLAIMED, CREATING);
+            if (previous === READY)
+                break;
+            if (previous === UNCLAIMED) {
+                let branch;
+                let blobRoots = [];
+                try {
+                    // Adopt rather than recreate: the branch outlives the process that first made it, so on
+                    // every restart after the first the directory is already here. What it is, though, is a
+                    // question -- the blob roots are published separately from the directory, so existence
+                    // alone proves nothing and the marker is what has to be read.
+                    await finishInterruptedRemoval(branchPath, storeName, { identityHeld: true });
+                    const existing = readBranchState(branchPath, storeName);
+                    if (existing.state === 'damaged' || existing.state === 'unmarked') {
+                        const problem = existing.state === 'damaged' ? existing.problem : existing.why;
+                        throw new Error(`Branch database at ${branchPath} cannot be trusted: ${problem}. Refusing to serve or rebuild ` +
+                            `it, because rebuilding re-forks from the base and would discard anything written to this ` +
+                            `branch. If this branch's data is not needed, delete the directory (and its blob roots) to ` +
+                            `have it recreated from the base on the next load.`);
+                    }
+                    if (existing.state === 'complete') {
+                        blobRoots = existing.blobRoots;
+                        warnAboutUnusedBlobRoots(branchPath, storeName, blobRoots);
+                    }
+                    else {
+                        // Absent, or leftovers that are not a store: nothing here can be lost.
+                        await (0, promises_1.rm)(branchPath, { recursive: true, force: true });
+                        blobRoots = await materializeBranch(baseName, branchPath, storeName, {
+                            progress: () => reportClaimProgress(claimState),
+                            strandedRoots: () => (blobRootsStranded = true),
+                        });
+                    }
+                    (0, databases_ts_1.releaseBranchIdentity)(storeName);
+                    branch = (0, databases_ts_1.openBranchDatabase)(branchPath, baseName, storeName, blobRoots);
+                    // The branch's column families write with the WAL disabled, so writes since its last
+                    // memtable flush exist only in its own transaction log — which a process that died
+                    // without the exit-time flush (a crash, a Windows hard kill) always leaves behind.
+                    // Replay must finish before READY, because READY is what releases the other threads to
+                    // serve reads. A fresh checkpoint carries no transaction_logs (verified: the native
+                    // checkpoint copies only RocksDB files), so replay after materialize is a no-op; the
+                    // read-only skip mirrors the base's boot replay.
+                    if (!(0, databases_ts_1.isReadOnlyMode)())
+                        await (0, replayLogs_ts_1.replayLogs)(branch.rootStore, branch.tables, true);
+                    Atomics.store(claimState, CLAIM_STATE, READY);
+                }
+                catch (error) {
+                    // Release rather than record the failure. A claim that stays un-releasable turns one
+                    // transient error -- a full disk, a rename losing a race -- into a branch that can never
+                    // be created again for the life of the process, because the buffer outlives every retry.
+                    // The branch is closed first — it holds the path and store identity a retry needs — and
+                    // a close failure must not leave the claim wedged in CREATING for the whole deadline.
+                    try {
+                        branch?.close();
+                    }
+                    catch (closeError) {
+                        harper_logger_ts_1.default.warn(`Error closing branch at ${branchPath} after a failed open`, closeError);
+                    }
+                    Atomics.store(claimState, CLAIM_STATE, UNCLAIMED);
+                    throw error;
+                }
+                finally {
+                    wakeWaiters(claimState);
+                }
+                handedOver = true;
+                return { branch, claimState, blobRoots };
+            }
+            // Someone else holds it. A wait that settles on UNCLAIMED means they failed and released, so
+            // take another turn at being the one who creates it.
+            if ((await awaitClaim(claimState, branchPath, deadline)) === READY)
+                break;
+        }
+        // This thread never read the branch it is adopting, and a branch resolves blob ids through the
+        // roots its marker names, so the marker has to be read here too rather than pinned only on the
+        // thread that won the claim.
+        const published = readBranchState(branchPath, storeName);
+        if (published.state !== 'complete') {
+            throw new Error(`Branch database at ${branchPath} was published by another thread but no longer reads as ` +
+                `complete: ${published.state === 'damaged' ? published.problem : published.state === 'unmarked' ? published.why : published.state}`);
+        }
+        warnAboutUnusedBlobRoots(branchPath, storeName, published.blobRoots);
+        // Released immediately before the open, with no `await` in between, so nothing can slip into the
+        // gap -- and so `openBranchDatabase`'s check stays strict rather than being taught to ignore a
+        // reservation, which would also make it ignore a DIFFERENT branch holding the same name.
+        (0, databases_ts_1.releaseBranchIdentity)(storeName);
+        const adopted = (0, databases_ts_1.openBranchDatabase)(branchPath, baseName, storeName, published.blobRoots);
+        handedOver = true;
+        return { branch: adopted, claimState, blobRoots: published.blobRoots };
+    }
+    finally {
+        // `openBranchDatabase` takes the identity over for the life of the handle; anything short of
+        // that has to hand it back, or the application can never load again in this process.
+        if (!handedOver) {
+            if (blobRootsStranded)
+                (0, databases_ts_1.quarantineBranchIdentity)(storeName);
+            else
+                (0, databases_ts_1.releaseBranchIdentity)(storeName);
+        }
+    }
+}
+/** Remove the now-empty `<app>` directory a removed branch leaves behind. */
+async function pruneEmptyParents(root, branchPath) {
+    let dir = (0, node_path_1.dirname)(branchPath);
+    // Stop at the branch root itself: it is shared, and `relative` going outside it means we walked past.
+    while (dir !== root && !(0, node_path_1.relative)(root, dir).startsWith('..')) {
+        try {
+            await (0, promises_1.rmdir)(dir);
+        }
+        catch {
+            return;
+        }
+        dir = (0, node_path_1.dirname)(dir);
+    }
+}
+function branchRootOf(branchPath) {
+    return (0, node_path_1.dirname)((0, node_path_1.dirname)(branchPath));
+}
+/**
+ * Release this thread's handle on a branch WITHOUT touching the directory. One branch directory is
+ * shared by every worker thread that loaded the application, so a thread that gives up its handle --
+ * a failed load, most often -- must not delete storage another thread is serving queries from.
+ */
+async function closeBranchAt(branchPath) {
+    const pending = branchesByPath.get(branchPath);
+    branchesByPath.delete(branchPath);
+    const opened = await pending?.catch(() => null);
+    opened?.branch.close();
+}
+/**
+ * Open references to this branch's store anywhere in the process (rocksdb-js's registry spans worker
+ * threads). A registry read that fails propagates and refuses the removal rather than reading as zero.
+ */
+function branchReferenceCount(branchPath) {
+    let resolved = branchPath;
+    try {
+        resolved = (0, node_fs_1.realpathSync)(branchPath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return 0;
+        throw error;
+    }
+    return ((0, rocksdb_js_1.registryStatus)().find((entry) => entry.path === resolved || canonicalOrSelf(entry.path) === resolved)
+        ?.refCount ?? 0);
+}
+function canonicalOrSelf(path) {
+    try {
+        return (0, node_fs_1.realpathSync)(path);
+    }
+    catch {
+        return path;
+    }
+}
+/**
+ * Destroy a branch's storage: checkpoint, blob roots and claim, the way `dropDatabase` does for a real
+ * database. Only safe as the last step of the undeploy sequence -- component dropped, workers
+ * restarted -- and it does not take that on trust: any remaining open reference to the store refuses
+ * the removal before anything is unlinked.
+ *
+ * The branch is first renamed to its `removing` sibling so a removal cut short by a crash is finished
+ * later instead of being read as damage. `opened` is the handle this thread held, if any, already closed.
+ */
+async function destroyBranchStorage(branchPath, opened) {
+    const held = branchReferenceCount(branchPath);
+    if (held > 0) {
+        throw new Error(`Cannot remove the branch at ${branchPath}: ${held} open reference(s) to its store remain in this ` +
+            `process. Restart the workers that loaded the application first; removing it now would unlink ` +
+            `storage out from under a live reader.`);
+    }
+    const storeName = branchStoreNameFor(branchPath);
+    const blobRoots = opened?.blobRoots ?? recordedBlobRootsAt(branchPath, storeName);
+    let holdsIdentity = true;
+    let blobRootsStranded = false;
+    if (opened) {
+        (0, databases_ts_1.retakeBranchIdentity)(storeName);
+        releaseClaim(opened.claimState);
+    }
+    else {
+        try {
+            (0, databases_ts_1.reserveBranchIdentity)(storeName);
+        }
+        catch (error) {
+            holdsIdentity = false;
+            harper_logger_ts_1.default.warn?.(`Leaving the blob roots of the branch at ${branchPath} in place: its identity is in use`, error);
+        }
+    }
+    branchesByPath.delete(branchPath);
+    const removing = `${branchPath}${databases_ts_1.BRANCH_REMOVING_SUFFIX}`;
+    try {
+        await (0, promises_1.rm)(removing, { recursive: true, force: true });
+        if ((0, node_fs_1.existsSync)(branchPath))
+            await (0, promises_1.rename)(branchPath, removing);
+        if (holdsIdentity && !(0, node_fs_1.existsSync)(branchPath)) {
+            if (!(await removeBlobRoots(blobRoots))) {
+                blobRootsStranded = true;
+                harper_logger_ts_1.default.warn?.(`Refusing '${storeName}' to new databases on this worker for the life of the process: the ` +
+                    `branch at ${branchPath} left blob files behind and a database under that name would ` +
+                    `resolve onto them`);
+            }
+        }
+        // only while the base exists: `claimStateFor` goes through `database()`, which recreates a dropped one
+        if (!opened && databases_ts_1.databases[(0, node_path_1.basename)(branchPath)]) {
+            try {
+                releaseClaim(claimStateFor((0, node_path_1.basename)(branchPath), branchPath));
+            }
+            catch (error) {
+                harper_logger_ts_1.default.warn?.(`Could not release the branch claim for ${branchPath}`, error);
+            }
+        }
+        if (blobRootsStranded) {
+            throw new Error(`The branch at ${branchPath} was not fully removed: one or more of its blob roots could not be ` +
+                `deleted. Its \`removing\` tombstone was kept; retry the removal once the cause is fixed.`);
+        }
+        await (0, promises_1.rm)(removing, { recursive: true, force: true });
+        await pruneEmptyParents(branchRootOf(branchPath), branchPath);
+    }
+    finally {
+        if (holdsIdentity) {
+            if (blobRootsStranded)
+                (0, databases_ts_1.quarantineBranchIdentity)(storeName);
+            else
+                (0, databases_ts_1.releaseBranchIdentity)(storeName);
+        }
+    }
+}
+/**
+ * Finish a removal that was interrupted; a `removing` sibling can only mean that.
+ *
+ * `identityHeld`: the caller already reserved the store identity (the load path does). Otherwise it is
+ * reserved here, and a database that already took the name owns the root it resolves to.
+ */
+async function finishInterruptedRemoval(branchPath, storeName, { identityHeld }) {
+    const removing = `${branchPath}${databases_ts_1.BRANCH_REMOVING_SUFFIX}`;
+    if (!(0, node_fs_1.existsSync)(removing))
+        return;
+    harper_logger_ts_1.default.warn?.(`Finishing an interrupted removal of the branch at ${branchPath}`);
+    if (!identityHeld)
+        (0, databases_ts_1.reserveBranchIdentity)(storeName);
+    let stranded = false;
+    try {
+        // Only what the tombstone's own marker names. The marker goes with the final delete, after the
+        // roots have; a tombstone without one had its roots removed already, or lost the record of them
+        // -- and guessing from configuration would take a same-named directory on a volume this branch
+        // never wrote.
+        const published = readBranchState(removing, storeName);
+        if (published.state === 'complete' || published.state === 'damaged') {
+            const configured = (0, blob_ts_1.getBlobPathsForDatabaseName)(storeName);
+            if (!(await removeBlobRoots(published.blobRoots.filter((root) => configured.includes(root))))) {
+                stranded = true;
+                throw new Error(`Could not finish removing the branch at ${branchPath}: its blob roots could not be deleted; ` +
+                    `the \`removing\` tombstone was kept`);
+            }
+        }
+        else {
+            stranded = true;
+            harper_logger_ts_1.default.warn?.(`The removal tombstone of the branch at ${branchPath} no longer names its blob roots; leaving any ` +
+                `that remain in place and refusing '${storeName}' to new databases`);
+        }
+        await (0, promises_1.rm)(removing, { recursive: true, force: true });
+    }
+    finally {
+        if (stranded)
+            (0, databases_ts_1.quarantineBranchIdentity)(storeName);
+        else if (!identityHeld)
+            (0, databases_ts_1.releaseBranchIdentity)(storeName);
+    }
+}
+/**
+ * Hand a branch's claim back, but only from READY: a CREATING word belongs to a loader that won the
+ * claim since, and must not be clobbered into making a second waiter the creator.
+ */
+function releaseClaim(claimState) {
+    if (Atomics.compareExchange(claimState, CLAIM_STATE, READY, UNCLAIMED) === READY)
+        wakeWaiters(claimState);
+}
+/**
+ * Release this thread's handle, then destroy the storage. Deliberate removal only.
+ */
+async function removeBranchAt(branchPath) {
+    const pending = branchesByPath.get(branchPath);
+    branchesByPath.delete(branchPath);
+    const opened = (await pending?.catch(() => null)) ?? null;
+    opened?.branch.close();
+    await destroyBranchStorage(branchPath, opened);
+}
+/**
+ * The roots a branch on disk recorded, falling back to configuration only for one that never
+ * published a usable marker -- an abandoned materialization, whose roots ARE the configured ones.
+ */
+function recordedBlobRootsAt(branchPath, storeName) {
+    const published = readBranchState(branchPath, storeName);
+    const configured = (0, blob_ts_1.getBlobPathsForDatabaseName)(storeName);
+    // A marker that reads as damaged still names what this branch published, and only a branch with no
+    // usable marker at all leaves configuration as the best answer. Nothing outside this node's
+    // configured volumes is deleted either way: a branch directory carried over from a host configured
+    // differently names paths this node never wrote.
+    return published.state === 'complete' || published.state === 'damaged'
+        ? published.blobRoots.filter((root) => configured.includes(root))
+        : configured;
+}
+/** `<storage>/`branches`/<app>/<db>` — the same identity `branchStoreName` composed on the way in. */
+function branchStoreNameFor(branchPath) {
+    return branchStoreName((0, node_path_1.basename)((0, node_path_1.dirname)(branchPath)), (0, node_path_1.basename)(branchPath));
+}
+/**
+ * Discard every branch this process has open, storage included. Deliberate removal only: a branch is
+ * durable and is meant to survive restarts, so no shutdown path calls this.
+ */
+async function removeBranches() {
+    for (const branchPath of [...branchesByPath.keys()])
+        await removeBranchAt(branchPath);
+}
+/** Every branch directory and removal tombstone an application owns, under every storage root a database could have. */
+function branchDirectoriesFor(appName) {
+    if (!appName || appName.includes('/') || appName.includes('\\') || appName === '.' || appName === '..') {
+        throw new Error(`Invalid application name for branch removal: ${JSON.stringify(appName)}`);
+    }
+    (0, databases_ts_1.getDatabases)();
+    const branches = [];
+    const tombstones = [];
+    const failures = [];
+    const fail = (what, error) => failures.push(`${what} (${error.message})`);
+    const baseNames = new Set([
+        ...Object.keys(databases_ts_1.databases),
+        hdbTerms_ts_1.DEFAULT_DATABASE_NAME,
+        // a dropped base with a dedicated path has left `databases`, not its branches
+        ...Object.keys(env.get(hdbTerms_ts_1.CONFIG_PARAMS.DATABASES) ?? {}),
+    ]);
+    const branchRoots = new Set();
+    for (const baseName of baseNames) {
+        try {
+            branchRoots.add((0, node_path_1.join)((0, databases_ts_1.resolveDatabaseStorageRoot)(baseName), databases_ts_1.BRANCH_ROOT_DIR));
+        }
+        catch (error) {
+            fail(`the storage root of database '${baseName}'`, error);
+        }
+    }
+    for (const root of branchRoots) {
+        const appDirectory = (0, node_path_1.join)(root, appName);
+        let entries;
+        try {
+            entries = (0, node_fs_1.readdirSync)(appDirectory, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                fail(appDirectory, error);
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const entryPath = (0, node_path_1.join)(appDirectory, entry.name);
+            if (entry.name.endsWith(databases_ts_1.BRANCH_REMOVING_SUFFIX))
+                tombstones.push(entryPath.slice(0, -databases_ts_1.BRANCH_REMOVING_SUFFIX.length));
+            else if (entry.name.includes('`'))
+                fail(entryPath, new Error('not a branch directory and not a known control path'));
+            else
+                branches.push(entryPath);
+        }
+    }
+    return { branches, tombstones, failures };
+}
+/** Whether undeploying this application would leave branched database storage behind. */
+function applicationHasBranchStorage(appName) {
+    const { branches, tombstones, failures } = branchDirectoriesFor(appName);
+    return branches.length > 0 || tombstones.length > 0 || failures.length > 0;
+}
+/**
+ * Discard every branch an application owns: what undeploying it means for its private data. A branch is
+ * durable, so if this does not happen nothing else ever will, and a redeploy under the same name would
+ * adopt the previous tenant's rows.
+ *
+ * Runs on the thread that saw the worker restart through, after it completed. Own handles are closed
+ * first; any reference held elsewhere refuses. Every failure is collected and thrown: an undeploy must
+ * not answer "dropped" with private data still on disk.
+ */
+async function removeBranchesForApplication(appName) {
+    const { branches, tombstones, failures } = branchDirectoriesFor(appName);
+    const fail = (what, error) => failures.push(`${what} (${error.message})`);
+    for (const branchPath of tombstones) {
+        try {
+            await finishInterruptedRemoval(branchPath, branchStoreNameFor(branchPath), { identityHeld: false });
+        }
+        catch (error) {
+            fail(`${branchPath}${databases_ts_1.BRANCH_REMOVING_SUFFIX}`, error);
+        }
+    }
+    for (const branchPath of branches) {
+        try {
+            await removeBranchAt(branchPath);
+        }
+        catch (error) {
+            fail(branchPath, error);
+        }
+    }
+    if (failures.length) {
+        throw new Error(`Could not remove branch storage for application '${appName}': ${failures.join('; ')}`);
+    }
+}
+/**
+ * Create every branch an application declared, or fail its load. These checks need the live
+ * environment, so they cannot live in the static config validator: whether the database exists,
+ * which storage engine is in effect, and whether the application's loader mode can carry a scoped
+ * `databases` binding at all.
+ *
+ * Failing is always right here. Falling back to the base would hand the application the shared
+ * database it explicitly asked not to have, and nothing downstream could tell the difference.
+ */
+async function prepareBranches(appName, branchedDatabases, loaderMode) {
+    const branches = new Map();
+    if (branchedDatabases === undefined)
+        return branches;
+    // The scoped `databases` binding is delivered through the module loader. Under `native` the
+    // loader hands back the process-wide exports, so a branch would be created and then never
+    // reached — the application would silently write the base.
+    if (loaderMode === 'native') {
+        throw new Error(`Application '${appName}' declares branchedDatabases but runs under the 'native' module loader, ` +
+            `which cannot carry a scoped databases binding; use the default loader or remove branchedDatabases`);
+    }
+    // An explicitly empty list branches nothing, so it needs no engine capability.
+    if (branchedDatabases !== true && !branchedDatabases.length)
+        return branches;
+    if ((process.env.HARPER_STORAGE_ENGINE || env.get(hdbTerms_ts_1.CONFIG_PARAMS.STORAGE_ENGINE)) === 'lmdb') {
+        throw new Error(`Application '${appName}' declares branchedDatabases, which requires the RocksDB storage engine`);
+    }
+    (0, databases_ts_1.getDatabases)();
+    if (branchedDatabases === true) {
+        // A snapshot, not a subscription: every database that exists at THIS load. One created afterward
+        // is not retroactively branched, and this application's own declarations into an unbranched
+        // database land in the base. `system` is excluded the same way an explicit declaration of it is
+        // refused (assertBranchedDatabases): it carries the instance's catalog, users and jobs.
+        branchedDatabases = Object.keys(databases_ts_1.databases).filter((name) => name !== 'system');
+    }
+    if (!branchedDatabases.length)
+        return branches;
+    for (const baseName of branchedDatabases) {
+        if (!databases_ts_1.databases[baseName]) {
+            throw new Error(`Application '${appName}' declares a branch of database '${baseName}', which does not exist`);
+        }
+        // Up front, not inside the open: two individually legal names can compose a store identity past
+        // the 250-character limit, and `openBranchDatabase` only checks it after the claim is taken and
+        // a potentially full-copy checkpoint is already on disk.
+        const storeName = branchStoreName(appName, baseName);
+        if (storeName.length > MAX_NAME_LENGTH) {
+            throw new Error(`Application '${appName}' cannot branch '${baseName}': the branch store identity would be ` +
+                `${storeName.length} characters, over the ${MAX_NAME_LENGTH} allowed`);
+        }
+    }
+    // Only the branches this call actually opened are this call's to give up. A branch handle is
+    // cached per path for the whole thread, so a later load of the same application -- a component
+    // reload, or a second component with the same appName -- must not close the branch the load
+    // already running is serving from.
+    const opened = [];
+    try {
+        for (const baseName of branchedDatabases) {
+            const branchPath = (0, databases_ts_1.resolveBranchPath)(baseName, appName);
+            const isNew = !branchesByPath.has(branchPath);
+            branches.set(baseName, await getOrCreateBranch(baseName, appName));
+            if (isNew)
+                opened.push(branchPath);
+        }
+        // Only now: a relationship whose target this application also branched has to resolve to that
+        // branch, and the whole set has to exist before any of them can resolve that way. The set stays
+        // on each branch for the reloads its own schema declarations trigger later.
+        for (const branch of branches.values()) {
+            branch.relatedBranches = branches;
+            (0, databases_ts_1.hydrateBranchRelationships)(branch, branches);
+        }
+    }
+    catch (error) {
+        // A partially branched application is worse than one that failed to load: some of its names
+        // would resolve to a branch and the rest to the base. Only this application's handles go, and
+        // only handles: another worker thread may have loaded the same application successfully and be
+        // serving queries out of the very directories this thread is giving up.
+        for (const branchPath of opened)
+            await closeBranchAt(branchPath).catch(() => { });
+        throw error;
+    }
+    return branches;
+}
+//# sourceMappingURL=branchDatabase.js.map