openryoko 2026.10.9 → 2026.10.13

package/dist/src/backup/catalog.js

@@ -0,0 +1,252 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DATABASE_BACKUP_RETENTION, SQLITE_SIDECAR_SUFFIXES } from "../sessions/backup.js";
+const STAMP = String.raw `(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z`;
+const ARCHIVE_NAME = new RegExp(`^(home|pre-restore)-(${STAMP})(?:-(\\d+))?\\.tar\\.gz$`);
+const DAILY_DATABASE_NAME = /^(sessions|workflows)-\d{4}-\d{2}-\d{2}\.db$/;
+const DATABASE_SNAPSHOT_NAME = new RegExp(`^pre-restore-(${STAMP})(?:-(\\d+))?-(sessions|workflows)\\.db$`);
+/**
+ * Temporary names this feature writes under: a leading dot for archives, a bare
+ * suffix for database copies and the state file. A database copy is read back
+ * before it gets its name, which can leave a -wal and a -shm beside the
+ * temporary file; those are temporary too.
+ */
+const TEMPORARY_NAME = /^(\.?(home|pre-restore|sessions|workflows)-.+\.tmp-[0-9a-f-]+(-wal|-shm)?|backup-state\.json\.\d+\.[0-9a-f]+\.tmp)$/;
+const STALE_TEMPORARY_MS = 24 * 60 * 60 * 1000;
+/** `20261012T030000Z`: the moment an archive was taken, in a form that sorts as text. */
+export function archiveStamp(when) {
+    return `${when.toISOString().slice(0, 19).replace(/[-:]/g, "")}Z`;
+}
+function stampToIso(match, offset) {
+    const [year, month, day, hour, minute, second] = match.slice(offset, offset + 6);
+    return `${year}-${month}-${day}T${hour}:${minute}:${second}.000Z`;
+}
+/** Recognises a backup by its file name alone, or returns null for anything else. */
+function classify(name) {
+    const archive = ARCHIVE_NAME.exec(name);
+    if (archive)
+        return { kind: "home", preRestore: archive[1] === "pre-restore", createdAt: stampToIso(archive, 3) };
+    const snapshot = DATABASE_SNAPSHOT_NAME.exec(name);
+    if (snapshot)
+        return { kind: snapshot[9], preRestore: true, createdAt: stampToIso(snapshot, 2) };
+    const daily = DAILY_DATABASE_NAME.exec(name);
+    return daily ? { kind: daily[1], preRestore: false } : null;
+}
+function idOf(name) {
+    return name.replace(/\.tar\.gz$|\.db$/, "");
+}
+/** Describes one file as a backup, or returns null when it is not a regular file with a backup's name. */
+function describe(file) {
+    const classified = classify(path.basename(file));
+    if (!classified)
+        return null;
+    let stat;
+    try {
+        stat = fs.lstatSync(file);
+    }
+    catch {
+        return null;
+    }
+    // A symlink or directory wearing a backup's name is not one, and retention must never act on it.
+    if (!stat.isFile())
+        return null;
+    return {
+        id: idOf(path.basename(file)),
+        kind: classified.kind,
+        preRestore: classified.preRestore,
+        file,
+        bytes: stat.size,
+        createdAt: classified.createdAt ?? stat.mtime.toISOString(),
+    };
+}
+function newestFirst(a, b) {
+    if (a.createdAt !== b.createdAt)
+        return a.createdAt < b.createdAt ? 1 : -1;
+    // Same second: a numeric suffix marks the later one.
+    return b.id.length - a.id.length || (a.id < b.id ? 1 : a.id > b.id ? -1 : 0);
+}
+/**
+ * Far more backups than retention ever leaves behind. Past it the listing stops
+ * taking names in: the directory is being flooded, and the next prune removes
+ * what it has seen.
+ */
+const MAX_LISTED_BACKUPS = 10_000;
+/**
+ * The names in `directory` that `wanted` accepts, read one at a time and at
+ * most `limit` of them. Never `readdirSync`: the gateway lists this directory
+ * after every backup, and a directory somebody has filled with files must not
+ * arrive as one array of every name in it.
+ */
+function matchingNames(directory, wanted, limit) {
+    let listing;
+    try {
+        listing = fs.opendirSync(directory);
+    }
+    catch {
+        return [];
+    }
+    const names = [];
+    try {
+        for (let entry = listing.readSync(); entry && names.length < limit; entry = listing.readSync()) {
+            if (wanted(entry.name))
+                names.push(entry.name);
+        }
+    }
+    catch {
+        // What was read so far is still a true, if partial, picture.
+    }
+    finally {
+        try {
+            listing.closeSync();
+        }
+        catch { /* already closed */ }
+    }
+    return names;
+}
+/** Every backup in `directory`, newest first. */
+export function listBackups(directory, options = {}) {
+    return matchingNames(directory, (name) => classify(name) !== null, options.maxItems ?? MAX_LISTED_BACKUPS)
+        .map((name) => describe(path.join(directory, name)))
+        .filter((item) => item !== null)
+        .sort(newestFirst);
+}
+/**
+ * Resolves what the operator typed - an id from `ryoko backup list`, a file
+ * name, or a path to an archive kept somewhere else - to one backup.
+ */
+export function findBackup(directory, reference) {
+    const looksLikePath = path.isAbsolute(reference) || reference.includes("/") || reference.includes(path.sep);
+    if (looksLikePath) {
+        const file = path.resolve(reference);
+        if (!fs.existsSync(file))
+            throw new Error(`no backup file at ${file}`);
+        const item = describe(file);
+        if (!item)
+            throw new Error(`${file} is not a backup this command wrote (its file name is not one it recognises)`);
+        return item;
+    }
+    const id = idOf(reference);
+    const item = listBackups(directory).find((candidate) => candidate.id === id);
+    if (!item)
+        throw new Error(`no backup with id "${reference}" in ${directory} (list them with: ryoko backup list)`);
+    return item;
+}
+/**
+ * A name no backup of this second holds, numbered one past the highest that is
+ * there. `build("")` is the first of a second, `build("-2")` the second, and
+ * so on; `numbered` matches those names and captures the number.
+ *
+ * Not the first number that is free. Within a second the number is the order,
+ * and one that pruning has freed belonged to a backup older than every one
+ * still there: a new backup given it would be named as the oldest of its
+ * second, and be the next the rule removes.
+ */
+function reserve(directory, numbered, build) {
+    let highest = 0;
+    for (const name of matchingNames(directory, (candidate) => numbered.test(candidate), MAX_LISTED_BACKUPS)) {
+        highest = Math.max(highest, Number(numbered.exec(name)?.[1] ?? 1));
+    }
+    for (let sequence = highest + 1;; sequence += 1) {
+        const name = build(sequence === 1 ? "" : `-${sequence}`);
+        // Still asked of each: a directory flooded past what was listed may hold the name after all.
+        if (!fs.existsSync(path.join(directory, name)))
+            return name;
+    }
+}
+/** A name no archive holds yet, so two taken in the same second sit side by side. */
+export function reserveArchiveName(directory, prefix, when) {
+    const stem = `${prefix}-${archiveStamp(when)}`;
+    const name = reserve(directory, new RegExp(`^${stem}(?:-(\\d+))?\\.tar\\.gz$`), (suffix) => `${stem}${suffix}.tar.gz`);
+    return { id: idOf(name), file: path.join(directory, name) };
+}
+/** A name for the copy of a live database taken before a restore replaces it. */
+export function reserveDatabaseSnapshotName(directory, name, when) {
+    const stem = `pre-restore-${archiveStamp(when)}`;
+    const fileName = reserve(directory, new RegExp(`^${stem}(?:-(\\d+))?-${name}\\.db$`), (suffix) => `${stem}${suffix}-${name}.db`);
+    return { id: idOf(fileName), file: path.join(directory, fileName) };
+}
+function removeWithSidecars(file, removed) {
+    for (const suffix of ["", ...SQLITE_SIDECAR_SUFFIXES])
+        fs.rmSync(`${file}${suffix}`, { force: true });
+    removed.push(file);
+}
+function sweepStaleTemporaries(directory, now, removed) {
+    for (const name of matchingNames(directory, (candidate) => TEMPORARY_NAME.test(candidate), MAX_LISTED_BACKUPS)) {
+        const file = path.join(directory, name);
+        try {
+            const stat = fs.lstatSync(file);
+            if (!stat.isFile() || now.getTime() - stat.mtimeMs < STALE_TEMPORARY_MS)
+                continue;
+            fs.rmSync(file, { force: true });
+            removed.push(file);
+        }
+        catch { /* gone already, or not ours to touch */ }
+    }
+}
+/**
+ * How many backups of one kind are kept from a single day. The newest is the
+ * day's backup; the two before it are for whoever takes one before each risky
+ * change and wants the last few steps back.
+ */
+export const SAME_DAY_BACKUPS_KEPT = 3;
+/**
+ * The members of one pool that have outlived their keep. `members` is newest
+ * first. Kept: the newest `days` days that have a backup at all, and of each of
+ * those days its most recent {@link SAME_DAY_BACKUPS_KEPT}.
+ *
+ * Days, not a count. A count let fourteen backups taken in one afternoon push
+ * out fourteen days of history; here a day's worth of them can only ever
+ * displace each other. And days that have a backup, not days on the calendar:
+ * an instance that was switched off for a month still has its `days` of
+ * history when it comes back, rather than none.
+ */
+function expired(members, days) {
+    const keptPerDay = new Map();
+    return members.filter((item) => {
+        const day = item.createdAt.slice(0, 10);
+        const keptToday = keptPerDay.get(day);
+        if (keptToday === undefined && keptPerDay.size >= Math.max(1, days))
+            return true;
+        if ((keptToday ?? 0) >= SAME_DAY_BACKUPS_KEPT)
+            return true;
+        keptPerDay.set(day, (keptToday ?? 0) + 1);
+        return false;
+    });
+}
+/**
+ * Trims the backup directory to the days it is meant to hold.
+ *
+ * Only files this feature names are ever candidates: the directory may be one
+ * the operator shares with other things. Daily archives and pre-restore
+ * snapshots are counted apart, so a burst of restores cannot push out the
+ * daily history. The daily database copies are not touched here - their writer
+ * keeps its own seven, one a day - and anything unrecognised is left exactly
+ * as it is.
+ *
+ * `keep` is what the run that is pruning has just written, and none of it is
+ * removed whatever the rule says. The rule goes by the time in a file's name.
+ * With a clock that has fallen behind the backups already there, the newest
+ * backup is by its name the oldest, and a run would report it written and
+ * then delete it. It is still judged with the rest, so that on an ordinary
+ * day it takes its place and its day keeps to its share.
+ */
+export function pruneBackups(directory, options) {
+    const removed = [];
+    const kept = new Set((options.keep ?? []).map((file) => path.resolve(file)));
+    const items = listBackups(directory);
+    const pools = [
+        { members: items.filter((item) => item.kind === "home" && !item.preRestore), days: options.retention },
+        { members: items.filter((item) => item.kind === "home" && item.preRestore), days: options.retention },
+        { members: items.filter((item) => item.kind === "sessions" && item.preRestore), days: DATABASE_BACKUP_RETENTION },
+        { members: items.filter((item) => item.kind === "workflows" && item.preRestore), days: DATABASE_BACKUP_RETENTION },
+    ];
+    for (const pool of pools) {
+        for (const item of expired(pool.members, pool.days)) {
+            if (!kept.has(path.resolve(item.file)))
+                removeWithSidecars(item.file, removed);
+        }
+    }
+    sweepStaleTemporaries(directory, options.now, removed);
+    return removed;
+}
+//# sourceMappingURL=catalog.js.map

package/dist/src/backup/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../../src/backup/catalog.ts"],"names":[],"mappings":"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"}

package/dist/src/backup/database-restore.d.ts

@@ -0,0 +1,63 @@
+import { type DatabaseBackupName } from "../sessions/backup.js";
+import { type GatewayLiveness } from "./gateway-liveness.js";
+import { type DiskSpaceProbe } from "./space.js";
+export interface DatabaseRestoreOptions {
+    /** The backup file to restore from. */
+    backup: string;
+    name: DatabaseBackupName;
+    home: string;
+    /** Where the copy of the database being replaced goes. */
+    backupDirectory: string;
+    now: Date;
+    dryRun?: boolean;
+    /**
+     * The operator's own word that no gateway is running on this home. Required
+     * to replace a database, on top of the automatic check - which it never
+     * overrides. A dry run replaces nothing and does not need it.
+     */
+    gatewayStopped?: boolean;
+    /** Replaces the check for a running gateway. `destination` is the database about to be replaced. */
+    detectGateway?: (home: string, destination: string, now: Date) => GatewayLiveness;
+    /** The existing free-space judgement, replaceable in tests. */
+    diskSpace?: DiskSpaceProbe;
+}
+export interface DatabaseRestoreResult {
+    name: DatabaseBackupName;
+    backup: string;
+    destination: string;
+    dryRun: boolean;
+    /** The copy of the database that was replaced. Null on a dry run or when there was none. */
+    preRestore: {
+        id: string;
+        file: string;
+    } | null;
+}
+/** What is wrong with a database backup, or an empty list when SQLite finds it sound. */
+export declare function inspectDatabaseBackup(file: string): string[];
+/** The flag that carries the operator's confirmation. Named here because the refusals quote it. */
+export declare const GATEWAY_STOPPED_FLAG = "--gateway-stopped";
+/**
+ * Replaces a home's session registry or workflows store with a backup of it.
+ *
+ * Refused while a gateway is running on the home: its connection would keep
+ * writing to a file that is no longer there, and a WAL from the old database
+ * would be replayed into the new one.
+ *
+ * What is opened, and when, is the whole design:
+ *
+ * - The live database is never opened, in any mode, at any point: not to see
+ *   whether it is in use, not on a dry run, not to copy it aside (that is a
+ *   plain file copy, sidecars included), not to replace it (a rename).
+ * - The operator's confirmation is checked first, before anything is looked
+ *   at. Then that the two places this writes - beside the database, and the
+ *   backup directory when it is in the home - are reached through real
+ *   directories and not through a symlink leading out of it. Then the signs of
+ *   a running gateway, which are pid files and file timestamps. A refusal at
+ *   any of these points has read no database at all.
+ * - Only then is the backup opened, read-only: once for SQLite's integrity
+ *   check (on a dry run too - it is a file in the backup directory, not the
+ *   one in use), and once as the source of the copy that is written to a new
+ *   file beside the live database and renamed over it.
+ */
+export declare function restoreDatabase(options: DatabaseRestoreOptions): Promise<DatabaseRestoreResult>;
+//# sourceMappingURL=database-restore.d.ts.map

package/dist/src/backup/database-restore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-restore.d.ts","sourceRoot":"","sources":["../../../src/backup/database-restore.ts"],"names":[],"mappings":"AAIA,OAAO,EAA2B,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAGzF,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEnF,OAAO,EAAgD,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAE/F,MAAM,WAAW,sBAAsB;IACrC,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,kBAAkB,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,EAAE,IAAI,CAAC;IACV,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oGAAoG;IACpG,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,KAAK,eAAe,CAAC;IAClF,+DAA+D;IAC/D,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,4FAA4F;IAC5F,UAAU,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACjD;AAoBD,yFAAyF;AACzF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAW5D;AAwHD,mGAAmG;AACnG,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAwBxD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAyBrG"}

package/dist/src/backup/database-restore.js

@@ -0,0 +1,236 @@
+import Database from "better-sqlite3";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { SQLITE_SIDECAR_SUFFIXES } from "../sessions/backup.js";
+import { reserveDatabaseSnapshotName } from "./catalog.js";
+import { errorMessage } from "./format.js";
+import { detectRunningGateway } from "./gateway-liveness.js";
+import { databasePath } from "./layout.js";
+import { fileBytes, insufficientSpace, sameFilesystem } from "./space.js";
+/**
+ * Opens a backup read-only. Reading a WAL-mode file makes SQLite create -wal
+ * and -shm beside it and, for a read-only connection, leave them there; the
+ * ones that were not there before are removed again on close, so checking a
+ * backup does not litter the directory it is kept in.
+ */
+function openBackup(file) {
+    const absent = SQLITE_SIDECAR_SUFFIXES.filter((suffix) => !fs.existsSync(`${file}${suffix}`));
+    const database = new Database(file, { readonly: true, fileMustExist: true });
+    return {
+        database,
+        close: () => {
+            database.close();
+            for (const suffix of absent)
+                fs.rmSync(`${file}${suffix}`, { force: true });
+        },
+    };
+}
+/** What is wrong with a database backup, or an empty list when SQLite finds it sound. */
+export function inspectDatabaseBackup(file) {
+    let opened;
+    try {
+        opened = openBackup(file);
+        const lines = opened.database.pragma("integrity_check").map((row) => row.integrity_check);
+        return lines.length === 1 && lines[0] === "ok" ? [] : lines.length > 0 ? lines : ["the integrity check returned nothing"];
+    }
+    catch (error) {
+        return [`the database could not be read: ${errorMessage(error)}`];
+    }
+    finally {
+        opened?.close();
+    }
+}
+/** The registry, and the database about to be replaced when that is a different one. */
+function findRunningGateway(home, destination, now) {
+    return detectRunningGateway(home, { now, databases: [destination] });
+}
+function lstatOrNull(file) {
+    try {
+        return fs.lstatSync(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+/**
+ * Holds a directory inside the home to being reached through real directories
+ * only, all the way down from the home. One that is not there yet is fine: it
+ * gets made, as a real directory. A place outside the home is not this
+ * function's business - the operator named it, and it is used as it is found.
+ */
+function assertRealDirectories(home, directory, consequence) {
+    const relative = path.relative(home, directory);
+    if (relative === "" || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+        return;
+    let current = home;
+    for (const segment of relative.split(path.sep)) {
+        current = path.join(current, segment);
+        const stat = lstatOrNull(current);
+        if (!stat)
+            return;
+        const shown = path.relative(home, current).split(path.sep).join("/");
+        if (stat.isSymbolicLink())
+            throw new Error(`${shown} is a symlink (to ${fs.readlinkSync(current)}). ${consequence} Nothing was changed.`);
+        if (!stat.isDirectory())
+            throw new Error(`${shown} is not a directory. ${consequence} Nothing was changed.`);
+    }
+}
+/**
+ * Refuses a restore that would write outside the home by way of a symlink in
+ * it. Restoring files never writes through one; this is the same rule for the
+ * two things a database restore writes. The new database goes beside the old
+ * one, so with `sessions/` swapped for a link it would land wherever that
+ * points, and the gateway would go on using it there. And the database being
+ * replaced is copied into the backup directory first, which inside the home
+ * has to be the directory it looks like.
+ */
+function refuseToLeaveTheHome(options, destination) {
+    assertRealDirectories(options.home, path.dirname(destination), "A database is restored in place, and through that it would be written outside the home: put the real directory back and run the restore again.");
+    assertRealDirectories(options.home, options.backupDirectory, "The database being replaced is copied there first, and through that the copy would leave the home: "
+        + "put the real directory back, or name the place itself as backup.directory in config.yaml, and run the restore again.");
+}
+/**
+ * Sets the live database aside before it is replaced. The files are copied as
+ * they are, sidecars included, rather than through SQLite: a registry being
+ * replaced because it is damaged cannot be read that way, and its bytes are
+ * still worth keeping.
+ */
+function keepCurrentDatabase(options, destination) {
+    if (!fs.existsSync(destination))
+        return null;
+    try {
+        fs.mkdirSync(options.backupDirectory, { recursive: true, mode: 0o700 });
+        const { id, file } = reserveDatabaseSnapshotName(options.backupDirectory, options.name, options.now);
+        for (const suffix of ["", ...SQLITE_SIDECAR_SUFFIXES]) {
+            if (!fs.existsSync(`${destination}${suffix}`))
+                continue;
+            fs.copyFileSync(`${destination}${suffix}`, `${file}${suffix}`, fs.constants.COPYFILE_EXCL);
+            try {
+                fs.chmodSync(`${file}${suffix}`, 0o600);
+            }
+            catch { /* Windows has no POSIX modes */ }
+        }
+        return { id, file };
+    }
+    catch (error) {
+        throw new Error(`the current database could not be saved first, so nothing was restored: ${errorMessage(error)}`);
+    }
+}
+async function installDatabase(backup, destination) {
+    const directory = path.dirname(destination);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const temporary = path.join(directory, `.${path.basename(destination)}.restore-${process.pid}-${crypto.randomBytes(4).toString("hex")}`);
+    const source = openBackup(backup);
+    try {
+        // Through SQLite rather than a file copy: a backup that still has a WAL
+        // beside it (a pre-restore copy does) comes out as one complete file.
+        await source.database.backup(temporary);
+        try {
+            fs.chmodSync(temporary, 0o600);
+        }
+        catch { /* Windows has no POSIX modes */ }
+        // A -wal or -shm left beside a replaced database is read as that database's own tail.
+        for (const suffix of SQLITE_SIDECAR_SUFFIXES)
+            fs.rmSync(`${destination}${suffix}`, { force: true });
+        fs.renameSync(temporary, destination);
+    }
+    catch (error) {
+        fs.rmSync(temporary, { force: true });
+        throw error;
+    }
+    finally {
+        source.close();
+    }
+}
+/**
+ * Refuses a restore that would not leave room for the gateway to work once it
+ * is back. Two things get written: the copy of the database being replaced,
+ * into the backup directory, and the new database beside the old one, which
+ * exist together until the rename. Sizes are read from the directory entries;
+ * nothing is opened.
+ */
+function refuseWithoutRoom(options, destination) {
+    const incoming = fileBytes(options.backup) + fileBytes(`${options.backup}-wal`);
+    const outgoing = ["", ...SQLITE_SIDECAR_SUFFIXES].reduce((total, suffix) => total + fileBytes(`${destination}${suffix}`), 0);
+    const beside = fs.existsSync(path.dirname(destination)) ? path.dirname(destination) : options.home;
+    const needs = sameFilesystem(beside, options.backupDirectory)
+        ? [[options.backupDirectory, incoming + outgoing]]
+        : [[beside, incoming], [options.backupDirectory, outgoing]];
+    for (const [directory, bytes] of needs) {
+        const reason = insufficientSpace(directory, bytes, options.diskSpace);
+        if (reason)
+            throw new Error(`${reason}. Nothing was changed.`);
+    }
+}
+/** The flag that carries the operator's confirmation. Named here because the refusals quote it. */
+export const GATEWAY_STOPPED_FLAG = "--gateway-stopped";
+/**
+ * Why a database is not replaced on the strength of "no gateway was detected".
+ *
+ * What the detection can read - a live pid, a recent write - is evidence that
+ * a gateway is there, never that one is not. The usual deployment keeps the
+ * home on the host and bind-mounts it into a container where the gateway runs;
+ * a `ryoko` on the host sees the same files, a pid that means nothing in its
+ * own pid namespace, and, while the gateway has nothing to write, files that
+ * look idle. The one way to know for certain would be to open the database,
+ * and opening a database in use from the wrong side of that boundary is what
+ * destroys it.
+ */
+function confirmationRequired() {
+    return new Error(`restoring a database needs ${GATEWAY_STOPPED_FLAG}, your confirmation that no gateway is running on this home. `
+        + "This command cannot be sure of it by itself: when the home is bind-mounted into a container, a gateway running inside is "
+        + "not reliably visible to a command run on the host, and a database that may be in use is never opened just to find out. "
+        + `Run this where the gateway runs (inside the container), stop the gateway first (ryoko stop), then repeat the command with ${GATEWAY_STOPPED_FLAG}. `
+        + "Nothing was changed.");
+}
+/**
+ * Replaces a home's session registry or workflows store with a backup of it.
+ *
+ * Refused while a gateway is running on the home: its connection would keep
+ * writing to a file that is no longer there, and a WAL from the old database
+ * would be replayed into the new one.
+ *
+ * What is opened, and when, is the whole design:
+ *
+ * - The live database is never opened, in any mode, at any point: not to see
+ *   whether it is in use, not on a dry run, not to copy it aside (that is a
+ *   plain file copy, sidecars included), not to replace it (a rename).
+ * - The operator's confirmation is checked first, before anything is looked
+ *   at. Then that the two places this writes - beside the database, and the
+ *   backup directory when it is in the home - are reached through real
+ *   directories and not through a symlink leading out of it. Then the signs of
+ *   a running gateway, which are pid files and file timestamps. A refusal at
+ *   any of these points has read no database at all.
+ * - Only then is the backup opened, read-only: once for SQLite's integrity
+ *   check (on a dry run too - it is a file in the backup directory, not the
+ *   one in use), and once as the source of the copy that is written to a new
+ *   file beside the live database and renamed over it.
+ */
+export async function restoreDatabase(options) {
+    const destination = databasePath(options.home, options.name);
+    const dryRun = options.dryRun === true;
+    if (!dryRun && options.gatewayStopped !== true)
+        throw confirmationRequired();
+    refuseToLeaveTheHome(options, destination);
+    const liveness = (options.detectGateway ?? findRunningGateway)(options.home, destination, options.now);
+    if (liveness.running) {
+        throw new Error(`a gateway appears to be running on this home (${liveness.reason ?? "it was detected"}). A database cannot be replaced underneath it: `
+            + `stop the gateway (ryoko stop), wait a minute, run this command again with ${GATEWAY_STOPPED_FLAG}, then start the gateway. `
+            + "Nothing was changed.");
+    }
+    const problems = inspectDatabaseBackup(options.backup);
+    if (problems.length > 0) {
+        throw new Error(`refusing to restore a database backup that failed its integrity check - ${problems.slice(0, 3).join("; ")}`);
+    }
+    refuseWithoutRoom(options, destination);
+    const result = { name: options.name, backup: options.backup, destination, dryRun, preRestore: null };
+    if (dryRun)
+        return result;
+    const preRestore = keepCurrentDatabase(options, destination);
+    await installDatabase(options.backup, destination);
+    return { ...result, preRestore };
+}
+//# sourceMappingURL=database-restore.js.map

package/dist/src/backup/database-restore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-restore.js","sourceRoot":"","sources":["../../../src/backup/database-restore.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,uBAAuB,EAA2B,MAAM,uBAAuB,CAAC;AACzF,OAAO,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAwB,MAAM,uBAAuB,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,cAAc,EAAuB,MAAM,YAAY,CAAC;AAgC/F;;;;;GAKG;AACH,SAAS,UAAU,CAAC,IAAY;IAC9B,MAAM,MAAM,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC;IAC9F,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7E,OAAO;QACL,QAAQ;QACR,KAAK,EAAE,GAAG,EAAE;YACV,QAAQ,CAAC,KAAK,EAAE,CAAC;YACjB,KAAK,MAAM,MAAM,IAAI,MAAM;gBAAE,EAAE,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9E,CAAC;KACF,CAAC;AACJ,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,IAAI,MAAiD,CAAC;IACtD,IAAI,CAAC;QACH,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAC1B,MAAM,KAAK,GAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,iBAAiB,CAAmC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;QAC7H,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,sCAAsC,CAAC,CAAC;IAC5H,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,mCAAmC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACpE,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,KAAK,EAAE,CAAC;IAClB,CAAC;AACH,CAAC;AAED,wFAAwF;AACxF,SAAS,kBAAkB,CAAC,IAAY,EAAE,WAAmB,EAAE,GAAS;IACtE,OAAO,oBAAoB,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACpE,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,qBAAqB,CAAC,IAAY,EAAE,SAAiB,EAAE,WAAmB;IACjF,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAChD,IAAI,QAAQ,KAAK,EAAE,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO;IACtH,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACtC,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QAClC,IAAI,CAAC,IAAI;YAAE,OAAO;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrE,IAAI,IAAI,CAAC,cAAc,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,qBAAqB,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,WAAW,uBAAuB,CAAC,CAAC;QAC1I,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,wBAAwB,WAAW,uBAAuB,CAAC,CAAC;IAC/G,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,oBAAoB,CAAC,OAA+B,EAAE,WAAmB;IAChF,qBAAqB,CACnB,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,EACvC,gJAAgJ,CACjJ,CAAC;IACF,qBAAqB,CACnB,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,eAAe,EACrC,qGAAqG;UACnG,sHAAsH,CACzH,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,mBAAmB,CAAC,OAA+B,EAAE,WAAmB;IAC/E,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,IAAI,CAAC;QACH,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACxE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,2BAA2B,CAAC,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QACrG,KAAK,MAAM,MAAM,IAAI,CAAC,EAAE,EAAE,GAAG,uBAAuB,CAAC,EAAE,CAAC;YACtD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,WAAW,GAAG,MAAM,EAAE,CAAC;gBAAE,SAAS;YACxD,EAAE,CAAC,YAAY,CAAC,GAAG,WAAW,GAAG,MAAM,EAAE,EAAE,GAAG,IAAI,GAAG,MAAM,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;YAC3F,IAAI,CAAC;gBAAC,EAAE,CAAC,SAAS,CAAC,GAAG,IAAI,GAAG,MAAM,EAAE,EAAE,KAAK,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,gCAAgC,CAAC,CAAC;QAC7F,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,2EAA2E,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACpH,CAAC;AACH,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,MAAc,EAAE,WAAmB;IAChE,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5C,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,YAAY,OAAO,CAAC,GAAG,IAAI,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACzI,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,CAAC;QACH,wEAAwE;QACxE,sEAAsE;QACtE,MAAM,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACxC,IAAI,CAAC;YAAC,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,gCAAgC,CAAC,CAAC;QAClF,sFAAsF;QACtF,KAAK,MAAM,MAAM,IAAI,uBAAuB;YAAE,EAAE,CAAC,MAAM,CAAC,GAAG,WAAW,GAAG,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACpG,EAAE,CAAC,UAAU,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACtC,MAAM,KAAK,CAAC;IACd,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,KAAK,EAAE,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,iBAAiB,CAAC,OAA+B,EAAE,WAAmB;IAC7E,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,MAAM,MAAM,CAAC,CAAC;IAChF,MAAM,QAAQ,GAAG,CAAC,EAAE,EAAE,GAAG,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,GAAG,SAAS,CAAC,GAAG,WAAW,GAAG,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7H,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;IACnG,MAAM,KAAK,GAAuB,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,CAAC;QAC/E,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,eAAe,EAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC;QAClD,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC9D,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC;QACvC,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QACtE,IAAI,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,wBAAwB,CAAC,CAAC;IACjE,CAAC;AACH,CAAC;AAED,mGAAmG;AACnG,MAAM,CAAC,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,SAAS,oBAAoB;IAC3B,OAAO,IAAI,KAAK,CACd,8BAA8B,oBAAoB,+DAA+D;UAC/G,2HAA2H;UAC3H,yHAAyH;UACzH,6HAA6H,oBAAoB,IAAI;UACrJ,sBAAsB,CACzB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAA+B;IACnE,MAAM,WAAW,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC;IACvC,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,cAAc,KAAK,IAAI;QAAE,MAAM,oBAAoB,EAAE,CAAC;IAC7E,oBAAoB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAE3C,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAC,aAAa,IAAI,kBAAkB,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACvG,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,iDAAiD,QAAQ,CAAC,MAAM,IAAI,iBAAiB,kDAAkD;cACrI,6EAA6E,oBAAoB,4BAA4B;cAC7H,sBAAsB,CACzB,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,qBAAqB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACvD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,2EAA2E,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChI,CAAC;IACD,iBAAiB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACxC,MAAM,MAAM,GAA0B,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC5H,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,UAAU,GAAG,mBAAmB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAC7D,MAAM,eAAe,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACnD,OAAO,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,CAAC;AACnC,CAAC"}

package/dist/src/backup/database-source.d.ts

@@ -0,0 +1,70 @@
+import Database from "better-sqlite3";
+import type { DatabaseBackupName } from "../sessions/backup.js";
+/**
+ * Where a backup run gets a database connection from, and when it gets none.
+ *
+ * A run opens no database on its own. Every connection is handed to it by a
+ * caller that has decided it is safe: the gateway hands over its own, and a
+ * command run by hand hands one over only when asked to and only when nothing
+ * suggests a gateway is running on the home.
+ */
+/** A database to copy, and how to give it back. */
+export interface DatabaseHandle {
+    database: Database.Database;
+    release(): void;
+}
+/**
+ * Why a database was deliberately left unopened.
+ *  - "not-requested": the run was handed no source for it.
+ *  - "gateway-running": it was asked for, and a gateway appears to be running on the home.
+ */
+export type WithheldReason = "not-requested" | "gateway-running";
+/** A source's refusal: the database is there, and it is not going to be opened. */
+export interface DatabaseWithheld {
+    withheld: WithheldReason;
+    detail: string;
+}
+/** Hands over a connection, declines to, or returns null when the home has no such database. */
+export type DatabaseSource = () => DatabaseHandle | DatabaseWithheld | null;
+/** The flag that asks `ryoko backup run` for the databases too. Named here because the reports quote it. */
+export declare const INCLUDE_DATABASES_FLAG = "--include-databases";
+/**
+ * Opens a database read-only for copying.
+ *
+ * Read-only is not the same as harmless, and this is only for a caller that
+ * knows who else has the file open. What a read-only connection does, traced
+ * through the SQLite this ships with and measured:
+ *
+ * - The main file is opened read-only and cannot be written. The -wal is not
+ *   written, truncated or deleted either: all of that needs an exclusive lock
+ *   on the main file, which a read-only descriptor cannot take. So closing it
+ *   never checkpoints the WAL away, which is what a read-write connection does
+ *   the moment it believes itself the last one.
+ * - The -shm (the WAL's index) is opened read-write regardless. Beside other
+ *   connections it can see, this one only records where it is reading. When it
+ *   sees none it takes itself for the first, truncates the -shm to three bytes
+ *   and rebuilds it from the WAL - and creates an empty -wal and a -shm beside
+ *   a database that had neither, and leaves them there.
+ *
+ * On the machine the other connections run on, their locks are seen and this
+ * is ordinary SQLite. From the far side of a bind mount into a container they
+ * may not be, and a gateway whose index was rebuilt underneath it has not been
+ * tested and cannot be from here. Hence the two callers: the gateway, for a
+ * database in its own home, and {@link standaloneDatabaseSources}.
+ */
+export declare function readOnlyDatabaseSource(file: string): DatabaseSource;
+/**
+ * Sources for a command run by hand, outside the gateway.
+ *
+ * Before the first database would be opened, the home is looked at for signs
+ * of a running gateway - pid files and file timestamps, nothing that touches a
+ * database - and if there are any, neither database is opened. The answer is
+ * settled once for both: this command's own reading leaves a freshly written
+ * -shm behind, and asked again it would take that for a gateway.
+ *
+ * No sign is not proof. A gateway behind a pid this process cannot see, with
+ * nothing written for a minute, passes; so this is offered only on request
+ * (`--include-databases`), never by default.
+ */
+export declare function standaloneDatabaseSources(home: string, now: () => Date): Record<DatabaseBackupName, DatabaseSource>;
+//# sourceMappingURL=database-source.d.ts.map