@dbx-tools/falkor-db 0.0.0-stage → 0.9.43

package/lib/src/persistence/redis-info.js

@@ -0,0 +1,58 @@
+/**
+ * Redis persistence metadata parsing and completed-RDB detection.
+ *
+ * Reuse this module whenever FalkorDB persistence decisions depend on `INFO
+ * persistence`; do not infer snapshot completion from filesystem timestamps
+ * alone or trigger `BGSAVE` merely to discover whether the graph changed.
+ *
+ * @module
+ */
+import { asyncUtils } from "@dbx-tools/shared-core";
+/** Parse the fields used by the backup manager from `INFO persistence`. */
+export function parsePersistenceInfo(raw) {
+    const values = new Map();
+    for (const line of raw.split(/\r?\n/)) {
+        if (!line || line.startsWith("#"))
+            continue;
+        const separator = line.indexOf(":");
+        if (separator < 0)
+            continue;
+        values.set(line.slice(0, separator), line.slice(separator + 1));
+    }
+    return {
+        rdbBgSaveInProgress: integer(values, "rdb_bgsave_in_progress") !== 0,
+        rdbLastSaveTime: integer(values, "rdb_last_save_time"),
+        rdbLastBgSaveStatus: values.get("rdb_last_bgsave_status") ?? "unknown",
+        rdbChangesSinceLastSave: integer(values, "rdb_changes_since_last_save"),
+    };
+}
+/** Read and parse the current Redis persistence state. */
+export async function getPersistenceInfo(redis) {
+    return parsePersistenceInfo(await redis.info("persistence"));
+}
+/** Wait until a requested background save finishes successfully. */
+export async function waitForBackgroundSave(redis, previousSaveTime, options = {}) {
+    let completed;
+    for await (const info of asyncUtils.poll(() => getPersistenceInfo(redis), {
+        intervalMs: options.intervalMs ?? 250,
+        timeoutMs: options.timeoutMs ?? 30_000,
+        predicate: (value) => {
+            if (!value.rdbBgSaveInProgress && value.rdbLastBgSaveStatus !== "ok") {
+                throw new Error(`Redis background save failed: ${value.rdbLastBgSaveStatus}`);
+            }
+            completed = value;
+            return value.rdbBgSaveInProgress || value.rdbLastSaveTime <= previousSaveTime;
+        },
+    })) {
+        completed = info;
+    }
+    if (!completed || completed.rdbLastSaveTime <= previousSaveTime) {
+        throw new Error("Redis background save completed without a newer RDB timestamp");
+    }
+    return completed;
+}
+function integer(values, key) {
+    const value = Number.parseInt(values.get(key) ?? "0", 10);
+    return Number.isFinite(value) ? value : 0;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVkaXMtaW5mby5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9wZXJzaXN0ZW5jZS9yZWRpcy1pbmZvLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7OztHQVFHO0FBRUgsT0FBTyxFQUFFLFVBQVUsRUFBRSxNQUFNLHdCQUF3QixDQUFDO0FBZ0JwRCwyRUFBMkU7QUFDM0UsTUFBTSxVQUFVLG9CQUFvQixDQUFDLEdBQVc7SUFDOUMsTUFBTSxNQUFNLEdBQUcsSUFBSSxHQUFHLEVBQWtCLENBQUM7SUFDekMsS0FBSyxNQUFNLElBQUksSUFBSSxHQUFHLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxFQUFFLENBQUM7UUFDdEMsSUFBSSxDQUFDLElBQUksSUFBSSxJQUFJLENBQUMsVUFBVSxDQUFDLEdBQUcsQ0FBQztZQUFFLFNBQVM7UUFDNUMsTUFBTSxTQUFTLEdBQUcsSUFBSSxDQUFDLE9BQU8sQ0FBQyxHQUFHLENBQUMsQ0FBQztRQUNwQyxJQUFJLFNBQVMsR0FBRyxDQUFDO1lBQUUsU0FBUztRQUM1QixNQUFNLENBQUMsR0FBRyxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMsQ0FBQyxFQUFFLFNBQVMsQ0FBQyxFQUFFLElBQUksQ0FBQyxLQUFLLENBQUMsU0FBUyxHQUFHLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDbEUsQ0FBQztJQUNELE9BQU87UUFDTCxtQkFBbUIsRUFBRSxPQUFPLENBQUMsTUFBTSxFQUFFLHdCQUF3QixDQUFDLEtBQUssQ0FBQztRQUNwRSxlQUFlLEVBQUUsT0FBTyxDQUFDLE1BQU0sRUFBRSxvQkFBb0IsQ0FBQztRQUN0RCxtQkFBbUIsRUFBRSxNQUFNLENBQUMsR0FBRyxDQUFDLHdCQUF3QixDQUFDLElBQUksU0FBUztRQUN0RSx1QkFBdUIsRUFBRSxPQUFPLENBQUMsTUFBTSxFQUFFLDZCQUE2QixDQUFDO0tBQ3hFLENBQUM7QUFDSixDQUFDO0FBRUQsMERBQTBEO0FBQzFELE1BQU0sQ0FBQyxLQUFLLFVBQVUsa0JBQWtCLENBQ3RDLEtBQTZCO0lBRTdCLE9BQU8sb0JBQW9CLENBQUMsTUFBTSxLQUFLLENBQUMsSUFBSSxDQUFDLGFBQWEsQ0FBQyxDQUFDLENBQUM7QUFDL0QsQ0FBQztBQUVELG9FQUFvRTtBQUNwRSxNQUFNLENBQUMsS0FBSyxVQUFVLHFCQUFxQixDQUN6QyxLQUE2QixFQUM3QixnQkFBd0IsRUFDeEIsVUFBdUQsRUFBRTtJQUV6RCxJQUFJLFNBQTJDLENBQUM7SUFDaEQsSUFBSSxLQUFLLEVBQUUsTUFBTSxJQUFJLElBQUksVUFBVSxDQUFDLElBQUksQ0FBQyxHQUFHLEVBQUUsQ0FBQyxrQkFBa0IsQ0FBQyxLQUFLLENBQUMsRUFBRTtRQUN4RSxVQUFVLEVBQUUsT0FBTyxDQUFDLFVBQVUsSUFBSSxHQUFHO1FBQ3JDLFNBQVMsRUFBRSxPQUFPLENBQUMsU0FBUyxJQUFJLE1BQU07UUFDdEMsU0FBUyxFQUFFLENBQUMsS0FBSyxFQUFFLEVBQUU7WUFDbkIsSUFBSSxDQUFDLEtBQUssQ0FBQyxtQkFBbUIsSUFBSSxLQUFLLENBQUMsbUJBQW1CLEtBQUssSUFBSSxFQUFFLENBQUM7Z0JBQ3JFLE1BQU0sSUFBSSxLQUFLLENBQUMsaUNBQWlDLEtBQUssQ0FBQyxtQkFBbUIsRUFBRSxDQUFDLENBQUM7WUFDaEYsQ0FBQztZQUNELFNBQVMsR0FBRyxLQUFLLENBQUM7WUFDbEIsT0FBTyxLQUFLLENBQUMsbUJBQW1CLElBQUksS0FBSyxDQUFDLGVBQWUsSUFBSSxnQkFBZ0IsQ0FBQztRQUNoRixDQUFDO0tBQ0YsQ0FBQyxFQUFFLENBQUM7UUFDSCxTQUFTLEdBQUcsSUFBSSxDQUFDO0lBQ25CLENBQUM7SUFDRCxJQUFJLENBQUMsU0FBUyxJQUFJLFNBQVMsQ0FBQyxlQUFlLElBQUksZ0JBQWdCLEVBQUUsQ0FBQztRQUNoRSxNQUFNLElBQUksS0FBSyxDQUFDLCtEQUErRCxDQUFDLENBQUM7SUFDbkYsQ0FBQztJQUNELE9BQU8sU0FBUyxDQUFDO0FBQ25CLENBQUM7QUFFRCxTQUFTLE9BQU8sQ0FBQyxNQUFtQyxFQUFFLEdBQVc7SUFDL0QsTUFBTSxLQUFLLEdBQUcsTUFBTSxDQUFDLFFBQVEsQ0FBQyxNQUFNLENBQUMsR0FBRyxDQUFDLEdBQUcsQ0FBQyxJQUFJLEdBQUcsRUFBRSxFQUFFLENBQUMsQ0FBQztJQUMxRCxPQUFPLE1BQU0sQ0FBQyxRQUFRLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQyxDQUFDLEtBQUssQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDO0FBQzVDLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIFJlZGlzIHBlcnNpc3RlbmNlIG1ldGFkYXRhIHBhcnNpbmcgYW5kIGNvbXBsZXRlZC1SREIgZGV0ZWN0aW9uLlxuICpcbiAqIFJldXNlIHRoaXMgbW9kdWxlIHdoZW5ldmVyIEZhbGtvckRCIHBlcnNpc3RlbmNlIGRlY2lzaW9ucyBkZXBlbmQgb24gYElORk9cbiAqIHBlcnNpc3RlbmNlYDsgZG8gbm90IGluZmVyIHNuYXBzaG90IGNvbXBsZXRpb24gZnJvbSBmaWxlc3lzdGVtIHRpbWVzdGFtcHNcbiAqIGFsb25lIG9yIHRyaWdnZXIgYEJHU0FWRWAgbWVyZWx5IHRvIGRpc2NvdmVyIHdoZXRoZXIgdGhlIGdyYXBoIGNoYW5nZWQuXG4gKlxuICogQG1vZHVsZVxuICovXG5cbmltcG9ydCB7IGFzeW5jVXRpbHMgfSBmcm9tIFwiQGRieC10b29scy9zaGFyZWQtY29yZVwiO1xuXG4vKiogUmVkaXMgcGVyc2lzdGVuY2UgZmllbGRzIHJlcXVpcmVkIGJ5IGR1cmFibGUgc25hcHNob3Qgb3JjaGVzdHJhdGlvbi4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgUmVkaXNQZXJzaXN0ZW5jZUluZm8ge1xuICByZGJCZ1NhdmVJblByb2dyZXNzOiBib29sZWFuO1xuICByZGJMYXN0U2F2ZVRpbWU6IG51bWJlcjtcbiAgcmRiTGFzdEJnU2F2ZVN0YXR1czogc3RyaW5nO1xuICByZGJDaGFuZ2VzU2luY2VMYXN0U2F2ZTogbnVtYmVyO1xufVxuXG4vKiogTWluaW1hbCBSZWRpcyBjbGllbnQgc3VyZmFjZSB1c2VkIGJ5IHRoZSBwZXJzaXN0ZW5jZSBtYW5hZ2VyLiAqL1xuZXhwb3J0IGludGVyZmFjZSBSZWRpc1BlcnNpc3RlbmNlQ2xpZW50IHtcbiAgaW5mbyhzZWN0aW9uOiBcInBlcnNpc3RlbmNlXCIpOiBQcm9taXNlPHN0cmluZz47XG4gIGJnU2F2ZSgpOiBQcm9taXNlPHVua25vd24+O1xufVxuXG4vKiogUGFyc2UgdGhlIGZpZWxkcyB1c2VkIGJ5IHRoZSBiYWNrdXAgbWFuYWdlciBmcm9tIGBJTkZPIHBlcnNpc3RlbmNlYC4gKi9cbmV4cG9ydCBmdW5jdGlvbiBwYXJzZVBlcnNpc3RlbmNlSW5mbyhyYXc6IHN0cmluZyk6IFJlZGlzUGVyc2lzdGVuY2VJbmZvIHtcbiAgY29uc3QgdmFsdWVzID0gbmV3IE1hcDxzdHJpbmcsIHN0cmluZz4oKTtcbiAgZm9yIChjb25zdCBsaW5lIG9mIHJhdy5zcGxpdCgvXFxyP1xcbi8pKSB7XG4gICAgaWYgKCFsaW5lIHx8IGxpbmUuc3RhcnRzV2l0aChcIiNcIikpIGNvbnRpbnVlO1xuICAgIGNvbnN0IHNlcGFyYXRvciA9IGxpbmUuaW5kZXhPZihcIjpcIik7XG4gICAgaWYgKHNlcGFyYXRvciA8IDApIGNvbnRpbnVlO1xuICAgIHZhbHVlcy5zZXQobGluZS5zbGljZSgwLCBzZXBhcmF0b3IpLCBsaW5lLnNsaWNlKHNlcGFyYXRvciArIDEpKTtcbiAgfVxuICByZXR1cm4ge1xuICAgIHJkYkJnU2F2ZUluUHJvZ3Jlc3M6IGludGVnZXIodmFsdWVzLCBcInJkYl9iZ3NhdmVfaW5fcHJvZ3Jlc3NcIikgIT09IDAsXG4gICAgcmRiTGFzdFNhdmVUaW1lOiBpbnRlZ2VyKHZhbHVlcywgXCJyZGJfbGFzdF9zYXZlX3RpbWVcIiksXG4gICAgcmRiTGFzdEJnU2F2ZVN0YXR1czogdmFsdWVzLmdldChcInJkYl9sYXN0X2Jnc2F2ZV9zdGF0dXNcIikgPz8gXCJ1bmtub3duXCIsXG4gICAgcmRiQ2hhbmdlc1NpbmNlTGFzdFNhdmU6IGludGVnZXIodmFsdWVzLCBcInJkYl9jaGFuZ2VzX3NpbmNlX2xhc3Rfc2F2ZVwiKSxcbiAgfTtcbn1cblxuLyoqIFJlYWQgYW5kIHBhcnNlIHRoZSBjdXJyZW50IFJlZGlzIHBlcnNpc3RlbmNlIHN0YXRlLiAqL1xuZXhwb3J0IGFzeW5jIGZ1bmN0aW9uIGdldFBlcnNpc3RlbmNlSW5mbyhcbiAgcmVkaXM6IFJlZGlzUGVyc2lzdGVuY2VDbGllbnQsXG4pOiBQcm9taXNlPFJlZGlzUGVyc2lzdGVuY2VJbmZvPiB7XG4gIHJldHVybiBwYXJzZVBlcnNpc3RlbmNlSW5mbyhhd2FpdCByZWRpcy5pbmZvKFwicGVyc2lzdGVuY2VcIikpO1xufVxuXG4vKiogV2FpdCB1bnRpbCBhIHJlcXVlc3RlZCBiYWNrZ3JvdW5kIHNhdmUgZmluaXNoZXMgc3VjY2Vzc2Z1bGx5LiAqL1xuZXhwb3J0IGFzeW5jIGZ1bmN0aW9uIHdhaXRGb3JCYWNrZ3JvdW5kU2F2ZShcbiAgcmVkaXM6IFJlZGlzUGVyc2lzdGVuY2VDbGllbnQsXG4gIHByZXZpb3VzU2F2ZVRpbWU6IG51bWJlcixcbiAgb3B0aW9uczogeyBpbnRlcnZhbE1zPzogbnVtYmVyOyB0aW1lb3V0TXM/OiBudW1iZXIgfSA9IHt9LFxuKTogUHJvbWlzZTxSZWRpc1BlcnNpc3RlbmNlSW5mbz4ge1xuICBsZXQgY29tcGxldGVkOiBSZWRpc1BlcnNpc3RlbmNlSW5mbyB8IHVuZGVmaW5lZDtcbiAgZm9yIGF3YWl0IChjb25zdCBpbmZvIG9mIGFzeW5jVXRpbHMucG9sbCgoKSA9PiBnZXRQZXJzaXN0ZW5jZUluZm8ocmVkaXMpLCB7XG4gICAgaW50ZXJ2YWxNczogb3B0aW9ucy5pbnRlcnZhbE1zID8/IDI1MCxcbiAgICB0aW1lb3V0TXM6IG9wdGlvbnMudGltZW91dE1zID8/IDMwXzAwMCxcbiAgICBwcmVkaWNhdGU6ICh2YWx1ZSkgPT4ge1xuICAgICAgaWYgKCF2YWx1ZS5yZGJCZ1NhdmVJblByb2dyZXNzICYmIHZhbHVlLnJkYkxhc3RCZ1NhdmVTdGF0dXMgIT09IFwib2tcIikge1xuICAgICAgICB0aHJvdyBuZXcgRXJyb3IoYFJlZGlzIGJhY2tncm91bmQgc2F2ZSBmYWlsZWQ6ICR7dmFsdWUucmRiTGFzdEJnU2F2ZVN0YXR1c31gKTtcbiAgICAgIH1cbiAgICAgIGNvbXBsZXRlZCA9IHZhbHVlO1xuICAgICAgcmV0dXJuIHZhbHVlLnJkYkJnU2F2ZUluUHJvZ3Jlc3MgfHwgdmFsdWUucmRiTGFzdFNhdmVUaW1lIDw9IHByZXZpb3VzU2F2ZVRpbWU7XG4gICAgfSxcbiAgfSkpIHtcbiAgICBjb21wbGV0ZWQgPSBpbmZvO1xuICB9XG4gIGlmICghY29tcGxldGVkIHx8IGNvbXBsZXRlZC5yZGJMYXN0U2F2ZVRpbWUgPD0gcHJldmlvdXNTYXZlVGltZSkge1xuICAgIHRocm93IG5ldyBFcnJvcihcIlJlZGlzIGJhY2tncm91bmQgc2F2ZSBjb21wbGV0ZWQgd2l0aG91dCBhIG5ld2VyIFJEQiB0aW1lc3RhbXBcIik7XG4gIH1cbiAgcmV0dXJuIGNvbXBsZXRlZDtcbn1cblxuZnVuY3Rpb24gaW50ZWdlcih2YWx1ZXM6IFJlYWRvbmx5TWFwPHN0cmluZywgc3RyaW5nPiwga2V5OiBzdHJpbmcpOiBudW1iZXIge1xuICBjb25zdCB2YWx1ZSA9IE51bWJlci5wYXJzZUludCh2YWx1ZXMuZ2V0KGtleSkgPz8gXCIwXCIsIDEwKTtcbiAgcmV0dXJuIE51bWJlci5pc0Zpbml0ZSh2YWx1ZSkgPyB2YWx1ZSA6IDA7XG59XG4iXX0=

package/lib/src/persistence/snapshot.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Immutable local RDB staging, hashing, and restore verification.
+ *
+ * The live `dump.rdb` is always copied before upload so a later Redis rename
+ * cannot change the bytes being transferred. Reuse these helpers instead of
+ * hashing or uploading the live database file directly.
+ *
+ * @module
+ */
+/** Local immutable snapshot metadata. */
+export interface LocalSnapshot {
+    path: string;
+    size: number;
+    sha256: string;
+}
+/** Copy a live RDB into an immutable staging path and hash the copied bytes. */
+export declare function stageSnapshot(source: string, destination: string): Promise<LocalSnapshot>;
+/** Compute a file's lowercase SHA-256 digest without buffering it in memory. */
+export declare function sha256File(path: string): Promise<string>;
+/** Fail when a restored snapshot does not match the durable manifest. */
+export declare function verifySnapshot(path: string, expectedSha256: string): Promise<void>;

package/lib/src/persistence/snapshot.js

@@ -0,0 +1,35 @@
+/**
+ * Immutable local RDB staging, hashing, and restore verification.
+ *
+ * The live `dump.rdb` is always copied before upload so a later Redis rename
+ * cannot change the bytes being transferred. Reuse these helpers instead of
+ * hashing or uploading the live database file directly.
+ *
+ * @module
+ */
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { copyFile, mkdir, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+/** Copy a live RDB into an immutable staging path and hash the copied bytes. */
+export async function stageSnapshot(source, destination) {
+    await mkdir(dirname(destination), { recursive: true });
+    await copyFile(source, destination);
+    const [details, sha256] = await Promise.all([stat(destination), sha256File(destination)]);
+    return { path: destination, size: details.size, sha256 };
+}
+/** Compute a file's lowercase SHA-256 digest without buffering it in memory. */
+export async function sha256File(path) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest("hex");
+}
+/** Fail when a restored snapshot does not match the durable manifest. */
+export async function verifySnapshot(path, expectedSha256) {
+    const actual = await sha256File(path);
+    if (actual !== expectedSha256.toLowerCase()) {
+        throw new Error(`FalkorDB snapshot checksum mismatch: expected ${expectedSha256}, got ${actual}`);
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic25hcHNob3QuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvcGVyc2lzdGVuY2Uvc25hcHNob3QudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7O0dBUUc7QUFFSCxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sYUFBYSxDQUFDO0FBQ3pDLE9BQU8sRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLFNBQVMsQ0FBQztBQUMzQyxPQUFPLEVBQUUsUUFBUSxFQUFFLEtBQUssRUFBRSxJQUFJLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUN6RCxPQUFPLEVBQUUsT0FBTyxFQUFFLE1BQU0sV0FBVyxDQUFDO0FBU3BDLGdGQUFnRjtBQUNoRixNQUFNLENBQUMsS0FBSyxVQUFVLGFBQWEsQ0FBQyxNQUFjLEVBQUUsV0FBbUI7SUFDckUsTUFBTSxLQUFLLENBQUMsT0FBTyxDQUFDLFdBQVcsQ0FBQyxFQUFFLEVBQUUsU0FBUyxFQUFFLElBQUksRUFBRSxDQUFDLENBQUM7SUFDdkQsTUFBTSxRQUFRLENBQUMsTUFBTSxFQUFFLFdBQVcsQ0FBQyxDQUFDO0lBQ3BDLE1BQU0sQ0FBQyxPQUFPLEVBQUUsTUFBTSxDQUFDLEdBQUcsTUFBTSxPQUFPLENBQUMsR0FBRyxDQUFDLENBQUMsSUFBSSxDQUFDLFdBQVcsQ0FBQyxFQUFFLFVBQVUsQ0FBQyxXQUFXLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDMUYsT0FBTyxFQUFFLElBQUksRUFBRSxXQUFXLEVBQUUsSUFBSSxFQUFFLE9BQU8sQ0FBQyxJQUFJLEVBQUUsTUFBTSxFQUFFLENBQUM7QUFDM0QsQ0FBQztBQUVELGdGQUFnRjtBQUNoRixNQUFNLENBQUMsS0FBSyxVQUFVLFVBQVUsQ0FBQyxJQUFZO0lBQzNDLE1BQU0sSUFBSSxHQUFHLFVBQVUsQ0FBQyxRQUFRLENBQUMsQ0FBQztJQUNsQyxJQUFJLEtBQUssRUFBRSxNQUFNLEtBQUssSUFBSSxnQkFBZ0IsQ0FBQyxJQUFJLENBQUM7UUFBRSxJQUFJLENBQUMsTUFBTSxDQUFDLEtBQUssQ0FBQyxDQUFDO0lBQ3JFLE9BQU8sSUFBSSxDQUFDLE1BQU0sQ0FBQyxLQUFLLENBQUMsQ0FBQztBQUM1QixDQUFDO0FBRUQseUVBQXlFO0FBQ3pFLE1BQU0sQ0FBQyxLQUFLLFVBQVUsY0FBYyxDQUFDLElBQVksRUFBRSxjQUFzQjtJQUN2RSxNQUFNLE1BQU0sR0FBRyxNQUFNLFVBQVUsQ0FBQyxJQUFJLENBQUMsQ0FBQztJQUN0QyxJQUFJLE1BQU0sS0FBSyxjQUFjLENBQUMsV0FBVyxFQUFFLEVBQUUsQ0FBQztRQUM1QyxNQUFNLElBQUksS0FBSyxDQUNiLGlEQUFpRCxjQUFjLFNBQVMsTUFBTSxFQUFFLENBQ2pGLENBQUM7SUFDSixDQUFDO0FBQ0gsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogSW1tdXRhYmxlIGxvY2FsIFJEQiBzdGFnaW5nLCBoYXNoaW5nLCBhbmQgcmVzdG9yZSB2ZXJpZmljYXRpb24uXG4gKlxuICogVGhlIGxpdmUgYGR1bXAucmRiYCBpcyBhbHdheXMgY29waWVkIGJlZm9yZSB1cGxvYWQgc28gYSBsYXRlciBSZWRpcyByZW5hbWVcbiAqIGNhbm5vdCBjaGFuZ2UgdGhlIGJ5dGVzIGJlaW5nIHRyYW5zZmVycmVkLiBSZXVzZSB0aGVzZSBoZWxwZXJzIGluc3RlYWQgb2ZcbiAqIGhhc2hpbmcgb3IgdXBsb2FkaW5nIHRoZSBsaXZlIGRhdGFiYXNlIGZpbGUgZGlyZWN0bHkuXG4gKlxuICogQG1vZHVsZVxuICovXG5cbmltcG9ydCB7IGNyZWF0ZUhhc2ggfSBmcm9tIFwibm9kZTpjcnlwdG9cIjtcbmltcG9ydCB7IGNyZWF0ZVJlYWRTdHJlYW0gfSBmcm9tIFwibm9kZTpmc1wiO1xuaW1wb3J0IHsgY29weUZpbGUsIG1rZGlyLCBzdGF0IH0gZnJvbSBcIm5vZGU6ZnMvcHJvbWlzZXNcIjtcbmltcG9ydCB7IGRpcm5hbWUgfSBmcm9tIFwibm9kZTpwYXRoXCI7XG5cbi8qKiBMb2NhbCBpbW11dGFibGUgc25hcHNob3QgbWV0YWRhdGEuICovXG5leHBvcnQgaW50ZXJmYWNlIExvY2FsU25hcHNob3Qge1xuICBwYXRoOiBzdHJpbmc7XG4gIHNpemU6IG51bWJlcjtcbiAgc2hhMjU2OiBzdHJpbmc7XG59XG5cbi8qKiBDb3B5IGEgbGl2ZSBSREIgaW50byBhbiBpbW11dGFibGUgc3RhZ2luZyBwYXRoIGFuZCBoYXNoIHRoZSBjb3BpZWQgYnl0ZXMuICovXG5leHBvcnQgYXN5bmMgZnVuY3Rpb24gc3RhZ2VTbmFwc2hvdChzb3VyY2U6IHN0cmluZywgZGVzdGluYXRpb246IHN0cmluZyk6IFByb21pc2U8TG9jYWxTbmFwc2hvdD4ge1xuICBhd2FpdCBta2RpcihkaXJuYW1lKGRlc3RpbmF0aW9uKSwgeyByZWN1cnNpdmU6IHRydWUgfSk7XG4gIGF3YWl0IGNvcHlGaWxlKHNvdXJjZSwgZGVzdGluYXRpb24pO1xuICBjb25zdCBbZGV0YWlscywgc2hhMjU2XSA9IGF3YWl0IFByb21pc2UuYWxsKFtzdGF0KGRlc3RpbmF0aW9uKSwgc2hhMjU2RmlsZShkZXN0aW5hdGlvbildKTtcbiAgcmV0dXJuIHsgcGF0aDogZGVzdGluYXRpb24sIHNpemU6IGRldGFpbHMuc2l6ZSwgc2hhMjU2IH07XG59XG5cbi8qKiBDb21wdXRlIGEgZmlsZSdzIGxvd2VyY2FzZSBTSEEtMjU2IGRpZ2VzdCB3aXRob3V0IGJ1ZmZlcmluZyBpdCBpbiBtZW1vcnkuICovXG5leHBvcnQgYXN5bmMgZnVuY3Rpb24gc2hhMjU2RmlsZShwYXRoOiBzdHJpbmcpOiBQcm9taXNlPHN0cmluZz4ge1xuICBjb25zdCBoYXNoID0gY3JlYXRlSGFzaChcInNoYTI1NlwiKTtcbiAgZm9yIGF3YWl0IChjb25zdCBjaHVuayBvZiBjcmVhdGVSZWFkU3RyZWFtKHBhdGgpKSBoYXNoLnVwZGF0ZShjaHVuayk7XG4gIHJldHVybiBoYXNoLmRpZ2VzdChcImhleFwiKTtcbn1cblxuLyoqIEZhaWwgd2hlbiBhIHJlc3RvcmVkIHNuYXBzaG90IGRvZXMgbm90IG1hdGNoIHRoZSBkdXJhYmxlIG1hbmlmZXN0LiAqL1xuZXhwb3J0IGFzeW5jIGZ1bmN0aW9uIHZlcmlmeVNuYXBzaG90KHBhdGg6IHN0cmluZywgZXhwZWN0ZWRTaGEyNTY6IHN0cmluZyk6IFByb21pc2U8dm9pZD4ge1xuICBjb25zdCBhY3R1YWwgPSBhd2FpdCBzaGEyNTZGaWxlKHBhdGgpO1xuICBpZiAoYWN0dWFsICE9PSBleHBlY3RlZFNoYTI1Ni50b0xvd2VyQ2FzZSgpKSB7XG4gICAgdGhyb3cgbmV3IEVycm9yKFxuICAgICAgYEZhbGtvckRCIHNuYXBzaG90IGNoZWNrc3VtIG1pc21hdGNoOiBleHBlY3RlZCAke2V4cGVjdGVkU2hhMjU2fSwgZ290ICR7YWN0dWFsfWAsXG4gICAgKTtcbiAgfVxufVxuIl19

package/lib/src/persistence/volume.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Durable snapshot storage abstraction and Databricks Volume adapter.
+ *
+ * Backup policy depends only on {@link VolumeStorage}. The Databricks adapter
+ * receives an initialized {@link DatabricksFileSystem}, keeping profile and
+ * application authentication in `@dbx-tools/databricks` rather than this
+ * package. Other durable stores can implement the same narrow contract.
+ *
+ * @module
+ */
+import { DatabricksFileSystem } from "@dbx-tools/databricks/databricks-fs";
+/** One entry in durable snapshot storage. */
+export interface VolumeEntry {
+    name: string;
+    path: string;
+    size?: number;
+}
+/** Storage contract used by restore, upload, manifest, and retention policy. */
+export interface VolumeStorage {
+    exists(path: string): Promise<boolean>;
+    download(remote: string, local: string): Promise<void>;
+    upload(local: string, remote: string, options?: {
+        overwrite?: boolean;
+    }): Promise<void>;
+    readJson<T>(path: string): Promise<T | null>;
+    writeJson(path: string, value: unknown): Promise<void>;
+    list(path: string): Promise<VolumeEntry[]>;
+    delete(path: string): Promise<void>;
+}
+/** Stream local snapshots to and from a rooted Unity Catalog Volume filesystem. */
+export declare class DatabricksVolumeStorage implements VolumeStorage {
+    private readonly fileSystem;
+    constructor(fileSystem: DatabricksFileSystem);
+    exists(path: string): Promise<boolean>;
+    download(remote: string, local: string): Promise<void>;
+    upload(local: string, remote: string, options?: {
+        overwrite?: boolean;
+    }): Promise<void>;
+    readJson<T>(path: string): Promise<T | null>;
+    writeJson(path: string, value: unknown): Promise<void>;
+    list(path: string): Promise<VolumeEntry[]>;
+    delete(path: string): Promise<void>;
+}

package/lib/src/persistence/volume.js

@@ -0,0 +1,58 @@
+/**
+ * Durable snapshot storage abstraction and Databricks Volume adapter.
+ *
+ * Backup policy depends only on {@link VolumeStorage}. The Databricks adapter
+ * receives an initialized {@link DatabricksFileSystem}, keeping profile and
+ * application authentication in `@dbx-tools/databricks` rather than this
+ * package. Other durable stores can implement the same narrow contract.
+ *
+ * @module
+ */
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+/** Stream local snapshots to and from a rooted Unity Catalog Volume filesystem. */
+export class DatabricksVolumeStorage {
+    fileSystem;
+    constructor(fileSystem) {
+        this.fileSystem = fileSystem;
+    }
+    async exists(path) {
+        return this.fileSystem.exists(path);
+    }
+    async download(remote, local) {
+        await mkdir(dirname(local), { recursive: true });
+        const source = await this.fileSystem.readStream(remote);
+        await pipeline(Readable.fromWeb(source), createWriteStream(local));
+    }
+    async upload(local, remote, options = {}) {
+        const source = Readable.toWeb(createReadStream(local));
+        await this.fileSystem.writeStream(remote, source, options);
+    }
+    async readJson(path) {
+        if (!(await this.fileSystem.exists(path)))
+            return null;
+        const text = await this.fileSystem.readFile(path, { encoding: "utf-8" });
+        return JSON.parse(text);
+    }
+    async writeJson(path, value) {
+        await this.fileSystem.writeFile(path, `${JSON.stringify(value, null, 2)}\n`, {
+            overwrite: true,
+        });
+    }
+    async list(path) {
+        if (!(await this.fileSystem.exists(path)))
+            return [];
+        return (await this.fileSystem.readdir(path)).map((entry) => ({
+            name: entry.name,
+            path: `${path.replace(/\/$/, "")}/${entry.name}`,
+            size: entry.size,
+        }));
+    }
+    async delete(path) {
+        await this.fileSystem.deleteFile(path, { force: true });
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidm9sdW1lLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3BlcnNpc3RlbmNlL3ZvbHVtZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7Ozs7Ozs7O0dBU0c7QUFFSCxPQUFPLEVBQUUsZ0JBQWdCLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSxTQUFTLENBQUM7QUFDOUQsT0FBTyxFQUFFLEtBQUssRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBQ3pDLE9BQU8sRUFBRSxPQUFPLEVBQUUsTUFBTSxXQUFXLENBQUM7QUFDcEMsT0FBTyxFQUFFLFFBQVEsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUN2QyxPQUFPLEVBQUUsUUFBUSxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFxQmhELG1GQUFtRjtBQUNuRixNQUFNLE9BQU8sdUJBQXVCO0lBQ0w7SUFBN0IsWUFBNkIsVUFBZ0M7UUFBaEMsZUFBVSxHQUFWLFVBQVUsQ0FBc0I7SUFBRyxDQUFDO0lBRWpFLEtBQUssQ0FBQyxNQUFNLENBQUMsSUFBWTtRQUN2QixPQUFPLElBQUksQ0FBQyxVQUFVLENBQUMsTUFBTSxDQUFDLElBQUksQ0FBQyxDQUFDO0lBQ3RDLENBQUM7SUFFRCxLQUFLLENBQUMsUUFBUSxDQUFDLE1BQWMsRUFBRSxLQUFhO1FBQzFDLE1BQU0sS0FBSyxDQUFDLE9BQU8sQ0FBQyxLQUFLLENBQUMsRUFBRSxFQUFFLFNBQVMsRUFBRSxJQUFJLEVBQUUsQ0FBQyxDQUFDO1FBQ2pELE1BQU0sTUFBTSxHQUFHLE1BQU0sSUFBSSxDQUFDLFVBQVUsQ0FBQyxVQUFVLENBQUMsTUFBTSxDQUFDLENBQUM7UUFDeEQsTUFBTSxRQUFRLENBQUMsUUFBUSxDQUFDLE9BQU8sQ0FBQyxNQUFNLENBQUMsRUFBRSxpQkFBaUIsQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDO0lBQ3JFLENBQUM7SUFFRCxLQUFLLENBQUMsTUFBTSxDQUNWLEtBQWEsRUFDYixNQUFjLEVBQ2QsVUFBbUMsRUFBRTtRQUVyQyxNQUFNLE1BQU0sR0FBRyxRQUFRLENBQUMsS0FBSyxDQUFDLGdCQUFnQixDQUFDLEtBQUssQ0FBQyxDQUEwQyxDQUFDO1FBQ2hHLE1BQU0sSUFBSSxDQUFDLFVBQVUsQ0FBQyxXQUFXLENBQUMsTUFBTSxFQUFFLE1BQU0sRUFBRSxPQUFPLENBQUMsQ0FBQztJQUM3RCxDQUFDO0lBRUQsS0FBSyxDQUFDLFFBQVEsQ0FBSSxJQUFZO1FBQzVCLElBQUksQ0FBQyxDQUFDLE1BQU0sSUFBSSxDQUFDLFVBQVUsQ0FBQyxNQUFNLENBQUMsSUFBSSxDQUFDLENBQUM7WUFBRSxPQUFPLElBQUksQ0FBQztRQUN2RCxNQUFNLElBQUksR0FBRyxNQUFNLElBQUksQ0FBQyxVQUFVLENBQUMsUUFBUSxDQUFDLElBQUksRUFBRSxFQUFFLFFBQVEsRUFBRSxPQUFPLEVBQUUsQ0FBQyxDQUFDO1FBQ3pFLE9BQU8sSUFBSSxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQU0sQ0FBQztJQUMvQixDQUFDO0lBRUQsS0FBSyxDQUFDLFNBQVMsQ0FBQyxJQUFZLEVBQUUsS0FBYztRQUMxQyxNQUFNLElBQUksQ0FBQyxVQUFVLENBQUMsU0FBUyxDQUFDLElBQUksRUFBRSxHQUFHLElBQUksQ0FBQyxTQUFTLENBQUMsS0FBSyxFQUFFLElBQUksRUFBRSxDQUFDLENBQUMsSUFBSSxFQUFFO1lBQzNFLFNBQVMsRUFBRSxJQUFJO1NBQ2hCLENBQUMsQ0FBQztJQUNMLENBQUM7SUFFRCxLQUFLLENBQUMsSUFBSSxDQUFDLElBQVk7UUFDckIsSUFBSSxDQUFDLENBQUMsTUFBTSxJQUFJLENBQUMsVUFBVSxDQUFDLE1BQU0sQ0FBQyxJQUFJLENBQUMsQ0FBQztZQUFFLE9BQU8sRUFBRSxDQUFDO1FBQ3JELE9BQU8sQ0FBQyxNQUFNLElBQUksQ0FBQyxVQUFVLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUFDLENBQUMsR0FBRyxDQUFDLENBQUMsS0FBSyxFQUFFLEVBQUUsQ0FBQyxDQUFDO1lBQzNELElBQUksRUFBRSxLQUFLLENBQUMsSUFBSTtZQUNoQixJQUFJLEVBQUUsR0FBRyxJQUFJLENBQUMsT0FBTyxDQUFDLEtBQUssRUFBRSxFQUFFLENBQUMsSUFBSSxLQUFLLENBQUMsSUFBSSxFQUFFO1lBQ2hELElBQUksRUFBRSxLQUFLLENBQUMsSUFBSTtTQUNqQixDQUFDLENBQUMsQ0FBQztJQUNOLENBQUM7SUFFRCxLQUFLLENBQUMsTUFBTSxDQUFDLElBQVk7UUFDdkIsTUFBTSxJQUFJLENBQUMsVUFBVSxDQUFDLFVBQVUsQ0FBQyxJQUFJLEVBQUUsRUFBRSxLQUFLLEVBQUUsSUFBSSxFQUFFLENBQUMsQ0FBQztJQUMxRCxDQUFDO0NBQ0YiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIER1cmFibGUgc25hcHNob3Qgc3RvcmFnZSBhYnN0cmFjdGlvbiBhbmQgRGF0YWJyaWNrcyBWb2x1bWUgYWRhcHRlci5cbiAqXG4gKiBCYWNrdXAgcG9saWN5IGRlcGVuZHMgb25seSBvbiB7QGxpbmsgVm9sdW1lU3RvcmFnZX0uIFRoZSBEYXRhYnJpY2tzIGFkYXB0ZXJcbiAqIHJlY2VpdmVzIGFuIGluaXRpYWxpemVkIHtAbGluayBEYXRhYnJpY2tzRmlsZVN5c3RlbX0sIGtlZXBpbmcgcHJvZmlsZSBhbmRcbiAqIGFwcGxpY2F0aW9uIGF1dGhlbnRpY2F0aW9uIGluIGBAZGJ4LXRvb2xzL2RhdGFicmlja3NgIHJhdGhlciB0aGFuIHRoaXNcbiAqIHBhY2thZ2UuIE90aGVyIGR1cmFibGUgc3RvcmVzIGNhbiBpbXBsZW1lbnQgdGhlIHNhbWUgbmFycm93IGNvbnRyYWN0LlxuICpcbiAqIEBtb2R1bGVcbiAqL1xuXG5pbXBvcnQgeyBjcmVhdGVSZWFkU3RyZWFtLCBjcmVhdGVXcml0ZVN0cmVhbSB9IGZyb20gXCJub2RlOmZzXCI7XG5pbXBvcnQgeyBta2RpciB9IGZyb20gXCJub2RlOmZzL3Byb21pc2VzXCI7XG5pbXBvcnQgeyBkaXJuYW1lIH0gZnJvbSBcIm5vZGU6cGF0aFwiO1xuaW1wb3J0IHsgUmVhZGFibGUgfSBmcm9tIFwibm9kZTpzdHJlYW1cIjtcbmltcG9ydCB7IHBpcGVsaW5lIH0gZnJvbSBcIm5vZGU6c3RyZWFtL3Byb21pc2VzXCI7XG5pbXBvcnQgeyBEYXRhYnJpY2tzRmlsZVN5c3RlbSB9IGZyb20gXCJAZGJ4LXRvb2xzL2RhdGFicmlja3MvZGF0YWJyaWNrcy1mc1wiO1xuXG4vKiogT25lIGVudHJ5IGluIGR1cmFibGUgc25hcHNob3Qgc3RvcmFnZS4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgVm9sdW1lRW50cnkge1xuICBuYW1lOiBzdHJpbmc7XG4gIHBhdGg6IHN0cmluZztcbiAgc2l6ZT86IG51bWJlcjtcbn1cblxuLyoqIFN0b3JhZ2UgY29udHJhY3QgdXNlZCBieSByZXN0b3JlLCB1cGxvYWQsIG1hbmlmZXN0LCBhbmQgcmV0ZW50aW9uIHBvbGljeS4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgVm9sdW1lU3RvcmFnZSB7XG4gIGV4aXN0cyhwYXRoOiBzdHJpbmcpOiBQcm9taXNlPGJvb2xlYW4+O1xuICBkb3dubG9hZChyZW1vdGU6IHN0cmluZywgbG9jYWw6IHN0cmluZyk6IFByb21pc2U8dm9pZD47XG4gIHVwbG9hZChsb2NhbDogc3RyaW5nLCByZW1vdGU6IHN0cmluZywgb3B0aW9ucz86IHsgb3ZlcndyaXRlPzogYm9vbGVhbiB9KTogUHJvbWlzZTx2b2lkPjtcbiAgcmVhZEpzb248VD4ocGF0aDogc3RyaW5nKTogUHJvbWlzZTxUIHwgbnVsbD47XG4gIHdyaXRlSnNvbihwYXRoOiBzdHJpbmcsIHZhbHVlOiB1bmtub3duKTogUHJvbWlzZTx2b2lkPjtcbiAgbGlzdChwYXRoOiBzdHJpbmcpOiBQcm9taXNlPFZvbHVtZUVudHJ5W10+O1xuICBkZWxldGUocGF0aDogc3RyaW5nKTogUHJvbWlzZTx2b2lkPjtcbn1cblxuLyoqIFN0cmVhbSBsb2NhbCBzbmFwc2hvdHMgdG8gYW5kIGZyb20gYSByb290ZWQgVW5pdHkgQ2F0YWxvZyBWb2x1bWUgZmlsZXN5c3RlbS4gKi9cbmV4cG9ydCBjbGFzcyBEYXRhYnJpY2tzVm9sdW1lU3RvcmFnZSBpbXBsZW1lbnRzIFZvbHVtZVN0b3JhZ2Uge1xuICBjb25zdHJ1Y3Rvcihwcml2YXRlIHJlYWRvbmx5IGZpbGVTeXN0ZW06IERhdGFicmlja3NGaWxlU3lzdGVtKSB7fVxuXG4gIGFzeW5jIGV4aXN0cyhwYXRoOiBzdHJpbmcpOiBQcm9taXNlPGJvb2xlYW4+IHtcbiAgICByZXR1cm4gdGhpcy5maWxlU3lzdGVtLmV4aXN0cyhwYXRoKTtcbiAgfVxuXG4gIGFzeW5jIGRvd25sb2FkKHJlbW90ZTogc3RyaW5nLCBsb2NhbDogc3RyaW5nKTogUHJvbWlzZTx2b2lkPiB7XG4gICAgYXdhaXQgbWtkaXIoZGlybmFtZShsb2NhbCksIHsgcmVjdXJzaXZlOiB0cnVlIH0pO1xuICAgIGNvbnN0IHNvdXJjZSA9IGF3YWl0IHRoaXMuZmlsZVN5c3RlbS5yZWFkU3RyZWFtKHJlbW90ZSk7XG4gICAgYXdhaXQgcGlwZWxpbmUoUmVhZGFibGUuZnJvbVdlYihzb3VyY2UpLCBjcmVhdGVXcml0ZVN0cmVhbShsb2NhbCkpO1xuICB9XG5cbiAgYXN5bmMgdXBsb2FkKFxuICAgIGxvY2FsOiBzdHJpbmcsXG4gICAgcmVtb3RlOiBzdHJpbmcsXG4gICAgb3B0aW9uczogeyBvdmVyd3JpdGU/OiBib29sZWFuIH0gPSB7fSxcbiAgKTogUHJvbWlzZTx2b2lkPiB7XG4gICAgY29uc3Qgc291cmNlID0gUmVhZGFibGUudG9XZWIoY3JlYXRlUmVhZFN0cmVhbShsb2NhbCkpIGFzIGdsb2JhbFRoaXMuUmVhZGFibGVTdHJlYW08VWludDhBcnJheT47XG4gICAgYXdhaXQgdGhpcy5maWxlU3lzdGVtLndyaXRlU3RyZWFtKHJlbW90ZSwgc291cmNlLCBvcHRpb25zKTtcbiAgfVxuXG4gIGFzeW5jIHJlYWRKc29uPFQ+KHBhdGg6IHN0cmluZyk6IFByb21pc2U8VCB8IG51bGw+IHtcbiAgICBpZiAoIShhd2FpdCB0aGlzLmZpbGVTeXN0ZW0uZXhpc3RzKHBhdGgpKSkgcmV0dXJuIG51bGw7XG4gICAgY29uc3QgdGV4dCA9IGF3YWl0IHRoaXMuZmlsZVN5c3RlbS5yZWFkRmlsZShwYXRoLCB7IGVuY29kaW5nOiBcInV0Zi04XCIgfSk7XG4gICAgcmV0dXJuIEpTT04ucGFyc2UodGV4dCkgYXMgVDtcbiAgfVxuXG4gIGFzeW5jIHdyaXRlSnNvbihwYXRoOiBzdHJpbmcsIHZhbHVlOiB1bmtub3duKTogUHJvbWlzZTx2b2lkPiB7XG4gICAgYXdhaXQgdGhpcy5maWxlU3lzdGVtLndyaXRlRmlsZShwYXRoLCBgJHtKU09OLnN0cmluZ2lmeSh2YWx1ZSwgbnVsbCwgMil9XFxuYCwge1xuICAgICAgb3ZlcndyaXRlOiB0cnVlLFxuICAgIH0pO1xuICB9XG5cbiAgYXN5bmMgbGlzdChwYXRoOiBzdHJpbmcpOiBQcm9taXNlPFZvbHVtZUVudHJ5W10+IHtcbiAgICBpZiAoIShhd2FpdCB0aGlzLmZpbGVTeXN0ZW0uZXhpc3RzKHBhdGgpKSkgcmV0dXJuIFtdO1xuICAgIHJldHVybiAoYXdhaXQgdGhpcy5maWxlU3lzdGVtLnJlYWRkaXIocGF0aCkpLm1hcCgoZW50cnkpID0+ICh7XG4gICAgICBuYW1lOiBlbnRyeS5uYW1lLFxuICAgICAgcGF0aDogYCR7cGF0aC5yZXBsYWNlKC9cXC8kLywgXCJcIil9LyR7ZW50cnkubmFtZX1gLFxuICAgICAgc2l6ZTogZW50cnkuc2l6ZSxcbiAgICB9KSk7XG4gIH1cblxuICBhc3luYyBkZWxldGUocGF0aDogc3RyaW5nKTogUHJvbWlzZTx2b2lkPiB7XG4gICAgYXdhaXQgdGhpcy5maWxlU3lzdGVtLmRlbGV0ZUZpbGUocGF0aCwgeyBmb3JjZTogdHJ1ZSB9KTtcbiAgfVxufVxuIl19

package/lib/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/falkor.ts","../src/persistence/manager.ts","../src/persistence/manifest.ts","../src/persistence/redis-info.ts","../src/persistence/snapshot.ts","../src/persistence/volume.ts","../index.ts"],"version":"5.9.3"}

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@dbx-tools/falkor-db",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Embedded FalkorDBLite with change-aware durable backups to Databricks Volumes",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "packages/js/node/falkor-db"
+  },
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "prepack": "projen prepack",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@dbx-tools/databricks": "^0.9.43",
+    "@dbx-tools/shared-core": "^0.9.43",
+    "falkordb": "^6.6.0",
+    "falkordblite": "0.3.0",
+    "redis": "6.3.0"
+  },
+  "main": "./lib/index.js",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "main": "./lib/index.js",
+    "types": "./lib/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      },
+      "./falkor": {
+        "types": "./lib/src/falkor.d.ts",
+        "default": "./lib/src/falkor.js"
+      },
+      "./package.json": "./package.json"
+    }
+  },
+  "version": "0.9.43",
+  "types": "./lib/index.d.ts",
+  "dbxToolsConfig": {
+    "tags": [
+      "node"
+    ]
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./falkor": {
+      "types": "./lib/src/falkor.d.ts",
+      "default": "./lib/src/falkor.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "lib"
+  ],
+  "optionalDependencies": {
+    "@falkordblite/darwin-arm64": "8.2.3-falkordb.4.16.3",
+    "@falkordblite/linux-x64": "8.2.3-falkordb.4.16.3"
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"bunx projen\"."
+}

package/src/falkor.ts

@@ -0,0 +1,236 @@
+/**
+ * Embedded local FalkorDB with optional durable Volume recovery.
+ *
+ * This module owns the reusable lifecycle: restore before process start, a
+ * private Unix socket, Redis change-aware RDB policy, completed-snapshot
+ * observation, and `NOSAVE` shutdown. Applications should reuse
+ * {@link DurableFalkorDB} rather than spawning Redis, exposing a TCP port, or
+ * attaching backup logic around FalkorDBLite themselves.
+ *
+ * @module
+ */
+
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { log } from "@dbx-tools/shared-core";
+import { FalkorDB as FalkorClient, type Graph } from "falkordb";
+import {
+  BinaryManager,
+  ConfigGenerator,
+  ServerManager,
+  unregisterServer,
+  type FalkorDBLiteOptions,
+} from "falkordblite";
+import { createClient } from "redis";
+import {
+  FalkorPersistenceManager,
+  type FalkorPersistenceOptions,
+  type FalkorPersistenceStatus,
+} from "./persistence/manager.ts";
+import type { VolumeStorage } from "./persistence/volume.ts";
+
+const require = createRequire(import.meta.url);
+const logger = log.logger("falkor-db");
+
+/** Configuration for {@link DurableFalkorDB.open}. */
+export interface DurableFalkorDBOptions extends Pick<
+  FalkorDBLiteOptions,
+  | "redisServerPath"
+  | "modulePath"
+  | "maxMemory"
+  | "logLevel"
+  | "logFile"
+  | "timeout"
+  | "inheritStdio"
+> {
+  /** Local active-database directory. Defaults to `FALKORDB_DATA_DIR`. */
+  dataDir?: string;
+  /** Redis snapshot interval. Defaults to `FALKORDB_SNAPSHOT_SECONDS` or 300. */
+  snapshotSeconds?: number;
+  /** Minimum writes in an interval. Defaults to `FALKORDB_SNAPSHOT_MIN_CHANGES` or 1. */
+  snapshotMinChanges?: number;
+  /** Extra redis.conf settings. `save`, TCP, module, and data paths remain owned here. */
+  redisConfig?: Readonly<Record<string, string>>;
+  /** Optional durable snapshot destination, typically a Databricks Volume. */
+  storage?: VolumeStorage;
+  /** Durable-backup and shutdown policy. */
+  persistence?: Omit<FalkorPersistenceOptions, "dataDir" | "storage">;
+  /** Install SIGINT/SIGTERM handlers. Defaults to true. */
+  handleSignals?: boolean;
+}
+
+/** Embedded FalkorDB graph client plus durable persistence lifecycle. */
+export class DurableFalkorDB {
+  private closing: Promise<void> | undefined;
+  private readonly signalHandlers = new Map<NodeJS.Signals, () => void>();
+
+  private constructor(
+    private readonly graphClient: FalkorClient,
+    private readonly adminClient: ReturnType<typeof createClient>,
+    private readonly server: ServerManager,
+    private readonly persistence: FalkorPersistenceManager,
+  ) {}
+
+  /** Restore durable state, start FalkorDBLite, and connect through its Unix socket. */
+  static async open(options: DurableFalkorDBOptions = {}): Promise<DurableFalkorDB> {
+    const dataDir = options.dataDir ?? process.env.FALKORDB_DATA_DIR ?? defaultDataDirectory();
+    const snapshotSeconds = positiveInteger(
+      options.snapshotSeconds ?? process.env.FALKORDB_SNAPSHOT_SECONDS ?? 300,
+      "snapshotSeconds",
+    );
+    const snapshotMinChanges = positiveInteger(
+      options.snapshotMinChanges ?? process.env.FALKORDB_SNAPSHOT_MIN_CHANGES ?? 1,
+      "snapshotMinChanges",
+    );
+    const persistence = new FalkorPersistenceManager({
+      ...options.persistence,
+      dataDir,
+      storage: options.storage,
+    });
+    await persistence.restore();
+
+    const binaries = resolveBinaries(options);
+    const config = new ConfigGenerator({
+      dbDir: dataDir,
+      falkordbModulePath: binaries.modulePath,
+      maxMemory: options.maxMemory,
+      logLevel: options.logLevel,
+      logFile: options.logFile,
+      additionalConfig: {
+        ...options.redisConfig,
+        port: "0",
+        save: `${snapshotSeconds} ${snapshotMinChanges}`,
+      },
+    });
+    const server = new ServerManager({
+      redisServerPath: binaries.redisServerPath,
+      config: config.generate(),
+      socketPath: config.getSocketPath(),
+      startupTimeoutMs: options.timeout,
+      inheritStdio: options.inheritStdio,
+    });
+    await server.start();
+    unregisterServer(server);
+
+    let graphClient: FalkorClient | undefined;
+    let adminClient: ReturnType<typeof createClient> | undefined;
+    try {
+      graphClient = await FalkorClient.connect({ socket: { path: server.socketPath } });
+      adminClient = createClient({
+        socket: { path: server.socketPath, tls: false, reconnectStrategy: false },
+      });
+      adminClient.on("error", (error) => {
+        logger.debug("Redis administration connection error", { error });
+      });
+      await adminClient.connect();
+      await persistence.start(adminClient);
+      const database = new DurableFalkorDB(graphClient, adminClient, server, persistence);
+      if (options.handleSignals ?? true) database.installSignalHandlers();
+      return database;
+    } catch (error) {
+      persistence.stop();
+      adminClient?.destroy();
+      await graphClient?.close().catch(() => undefined);
+      await server.stop(false);
+      throw error;
+    }
+  }
+
+  /** Select a graph using the exact `falkordb` package {@link Graph} type. */
+  selectGraph(graphId: string): Graph {
+    return this.graphClient.selectGraph(graphId);
+  }
+
+  /** List graphs in the embedded database. */
+  list(): Promise<string[]> {
+    return this.graphClient.list();
+  }
+
+  /** Current local/durable persistence health fields. */
+  get persistenceStatus(): Readonly<FalkorPersistenceStatus> {
+    return this.persistence.status;
+  }
+
+  /** Unix socket used by the embedded Redis/FalkorDB process. */
+  get socketPath(): string {
+    return this.server.socketPath;
+  }
+
+  /** Embedded Redis process id, when running. */
+  get pid(): number | undefined {
+    return this.server.getPid();
+  }
+
+  /** Stop polling and terminate with `SHUTDOWN NOSAVE`. */
+  close(): Promise<void> {
+    this.closing ??= this.closeOnce();
+    return this.closing;
+  }
+
+  private async closeOnce(): Promise<void> {
+    this.removeSignalHandlers();
+    await this.persistence.prepareShutdown();
+    await this.graphClient.close().catch(() => undefined);
+    await this.adminClient.close().catch(() => this.adminClient.destroy());
+    await this.server.stop(false);
+  }
+
+  private installSignalHandlers(): void {
+    for (const signal of ["SIGINT", "SIGTERM"] as const) {
+      const handler = () => {
+        void this.close().finally(() => process.kill(process.pid, signal));
+      };
+      this.signalHandlers.set(signal, handler);
+      process.once(signal, handler);
+    }
+  }
+
+  private removeSignalHandlers(): void {
+    for (const [signal, handler] of this.signalHandlers) process.off(signal, handler);
+    this.signalHandlers.clear();
+  }
+}
+
+interface ResolvedBinaries {
+  redisServerPath: string;
+  modulePath: string;
+}
+
+function resolveBinaries(options: DurableFalkorDBOptions): ResolvedBinaries {
+  if (options.redisServerPath && options.modulePath) {
+    return { redisServerPath: options.redisServerPath, modulePath: options.modulePath };
+  }
+  const platform = BinaryManager.detectPlatform();
+  const packageName = `@falkordblite/${platform}`;
+  let packageDirectory: string;
+  try {
+    packageDirectory = dirname(require.resolve(`${packageName}/package.json`));
+  } catch (error) {
+    throw new Error(
+      `Missing ${packageName}; install the platform package or provide redisServerPath and modulePath`,
+      { cause: error },
+    );
+  }
+  const redisServerPath = options.redisServerPath ?? join(packageDirectory, "bin", "redis-server");
+  const modulePath = options.modulePath ?? join(packageDirectory, "bin", "falkordb.so");
+  if (!existsSync(redisServerPath) || !existsSync(modulePath)) {
+    throw new Error(`FalkorDBLite platform package ${packageName} is missing its bundled binaries`);
+  }
+  return { redisServerPath, modulePath };
+}
+
+function defaultDataDirectory(): string {
+  return join(tmpdir(), process.env.DATABRICKS_APP_NAME ?? "dbx-tools", "falkordb");
+}
+
+function positiveInteger(value: number | string, name: string): number {
+  const parsed = typeof value === "number" ? value : Number.parseInt(value, 10);
+  if (!Number.isSafeInteger(parsed) || parsed < 1) {
+    throw new TypeError(`${name} must be a positive integer`);
+  }
+  return parsed;
+}
+
+export type { Graph } from "falkordb";