@jwilleke/ngdpbase-types 5.25.0 → 5.26.0

package/lib/src/managers/BackupManager.d.ts

@@ -0,0 +1,779 @@
+import type { Readable } from 'stream';
+import BaseManager, { type BackupData as BaseBackupData, type BackupFolder, type StagedRestoreAtStart, type StagedSwap } from './BaseManager.js';
+import { type ActorContext } from '../context/ActorContext.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import { type Schedule, type ScheduleInput } from '../utils/schedule.js';
+import { type SiteRestoreManifest } from '../utils/siteRestore.js';
+import { type BackupDocument } from '../utils/backupDocument.js';
+import type { JobRunSince } from './BackgroundJobManager.js';
+/**
+ * Backup options
+ */
+export interface BackupOptions {
+    filename?: string;
+    compress?: boolean;
+    /**
+     * Leave retention for the next backup (#1723). The backup a restore takes
+     * of the live data first sets it, so that backup can never prune the very
+     * backup being restored.
+     */
+    skipCleanup?: boolean;
+    /** Throw when any part of the backup failed, after saying so (#1723): a restore stages nothing without a whole copy of the live data. */
+    requireComplete?: boolean;
+    /** This is a restore's backup of the live data (#1892 D2); handed to every manager as `safetyBackup`. */
+    safetyBackup?: boolean;
+}
+/**
+ * Restore options
+ */
+/** What a restore started from Admin → Backup puts back (#1945): the whole site, or the databases only. */
+export type RestoreScope = 'site' | 'databases';
+export interface RestoreOptions {
+    skipValidation?: boolean;
+    managerFilter?: string[];
+    /** Replace a database restore staged earlier and not applied yet (#1723, D5); refused without it. */
+    replaceStaged?: boolean;
+}
+/** A backup in the backup directory, as Admin → Backup lists it for download and restore (#1723). */
+export interface StoredBackup extends BackupFileInfo {
+    /** The database files beside the document, by name (`application`, `addon-<owner>`). */
+    databases: string[];
+    /** The file archives beside the document, by part (`attachments`, `roles`, …) (#1876). */
+    parts: string[];
+    /** Every file beside the document, by filename: what a download carries with it. */
+    files: string[];
+    /** Whether the document is encrypted under the backup key (#1561): its name ends `.enc`. */
+    encrypted: boolean;
+    /** The document and every file beside it together, in bytes. */
+    totalSize: number;
+}
+/** Backup data structure: the document (`src/utils/backupDocument.ts`). */
+export type BackupData = BackupDocument;
+/**
+ * Restore results
+ */
+export interface RestoreResults {
+    success: string[];
+    failed: Array<{
+        manager: string;
+        error: string;
+    }>;
+    skipped: string[];
+}
+/**
+ * Backup file information
+ */
+export interface BackupFileInfo {
+    filename: string;
+    path: string;
+    size: number;
+    created: Date;
+    modified: Date;
+}
+/**
+ * BackupManager - Coordinates backup and restore operations across all managers
+ *
+ * Orchestrates system-wide backup and restore by calling backup()/restore()
+ * on all registered managers and aggregating their data into compressed archives.
+ *
+ * Responsibilities:
+ * - Call backup() on all registered managers
+ * - Aggregate backup data into a single .gz file
+ * - Restore from .gz backup file
+ * - Call restore() on all registered managers
+ *
+ * Architecture:
+ * - Each manager implements backup() to return its state
+ * - BackupManager collects all states into one object
+ * - Serializes to JSON and compresses with gzip
+ * - Stores as single .gz file
+ *
+ * @class BackupManager
+ * @extends BaseManager
+ *
+ * @property {string|null} backupDirectory - Directory for backup files
+ * @property {number} maxBackups - Maximum number of backups to retain
+ *
+ * @see {@link BaseManager} for base functionality and backup() pattern
+ *
+ * @example
+ * const backupManager = engine.getManager('BackupManager');
+ * const backupPath = await backupManager.createBackup(wikiContext.userContext);
+ * console.log('Backup created:', backupPath);
+ */
+/** Auto-backup schedule configuration */
+export interface AutoBackupConfig {
+    enabled: boolean;
+    time: string;
+    days: string;
+    maxBackups: number;
+    directory: string;
+}
+/**
+ * A backup document's filename without `.json.gz` / `.json` (#1723). A
+ * manager's own files beside the document are named `<stem>.<name>.db` (a
+ * database, #1723) or `<stem>.<part>.tar` (a folder of files, #1876), and are
+ * pruned and downloaded with it.
+ */
+export declare function backupStem(filename: string): string;
+/** Whether `filename` is one of the files a manager wrote beside the document named `documentFilename` (#1723); a file archive may be encrypted, `.tar.enc` (#1561). */
+export declare function isCompanionOf(filename: string, documentFilename: string): boolean;
+/**
+ * What no backup holds, so no restore brings back (#1876), in the words
+ * admins read: these stay as they are on the site. The backup-restore guide
+ * and the Backup help page list the same.
+ */
+export declare const NEVER_IN_A_BACKUP: readonly string[];
+/** The backup document entry, and the site restore part, an add-on's files are recorded under (#1985). */
+export declare function addonEntryName(slug: string): string;
+/**
+ * Put a staged restore of a manager's declared folders and files in place,
+ * at start, before it reads them (#1985). BackupManager's step: a manager
+ * reaches it through `BaseManager.initialize()`, an add-on's folders through
+ * AddonsManager before the add-on's `register()`. A module function, not a
+ * method, because most managers start before BackupManager does; it needs
+ * only the configuration, for the site restore manifest.
+ */
+export declare function applyStagedPartsAtStart(engine: WikiEngine, manager: string, declared: BackupFolder[]): StagedRestoreAtStart | null;
+/** How a manager whose restore is staged (`restoreIsStaged()`) puts its part in place at start (#1986). */
+export interface StagedPartAtStartOptions {
+    /** Whether this manager may replace that live path: a manifest naming any other is refused, whatever it says. */
+    allowed: (swap: StagedSwap) => boolean;
+    /** The live paths of this manager's that may have a staged copy beside them: one no committed restore names (an interrupted staging) is set aside. */
+    mayBeStaged?: () => string[];
+    /**
+     * Put one swap in place yourself, instead of the rename: for a part whose
+     * live path is not a file or folder of its own (the audit files share the
+     * log folder). Move the live content to `kept` and the staged one in;
+     * throw to refuse.
+     */
+    put?: (swap: StagedSwap, kept: string) => void;
+}
+/**
+ * Put `manager`'s part of a staged site restore in place, at start, before
+ * it reads its data (#1876, #1986): when the whole restore is there to
+ * apply, each live path steps aside as `<live>.pre-restore` and the staged
+ * copy takes its name; otherwise its staged files are set aside as
+ * `*.incomplete`. The part is marked in BackupManager's record either way.
+ * For a manager whose restore is staged by its own `restore()` (the
+ * attachments, the audit log); declared folders and files go through
+ * `applyStagedPartsAtStart`. A module function: most managers start before
+ * BackupManager. Null when there was nothing to do.
+ */
+export declare function applyStagedPartAtStart(engine: WikiEngine, manager: string, options: StagedPartAtStartOptions): StagedRestoreAtStart | null;
+/**
+ * BackupManager's answer, at start, for a manager that applies a staged
+ * restore of its own kind (the databases, #1723): whether its part of a
+ * staged site restore is to go in now (#1876, #1986).
+ *
+ * - `none` — no site restore names it: the manager does as it would alone.
+ * - `apply` — the whole restore is there: put it in, then `settle` it.
+ * - `set-aside` — it isn't (`reason`): set the staged files aside, then `settle` it.
+ */
+export interface SiteRestorePartAtStart {
+    decision: 'none' | 'apply' | 'set-aside';
+    reason?: string;
+    /** Record what became of the part. Nothing to record for `none`, or a set-aside with no part of this manager's. */
+    settle(status: 'applied' | 'set-aside', note?: string): void;
+}
+/** BackupManager's start-time gate on `manager`'s part of a staged site restore (#1986): see {@link SiteRestorePartAtStart}. */
+export declare function siteRestorePartAtStart(engine: WikiEngine, manager: string): SiteRestorePartAtStart;
+/** A manager's data as the "not restored" notification names it. */
+export declare function restoreLabel(manager: string): string;
+/**
+ * What a staged restore will not bring back, written when it is staged (#1876)
+ * and read once it has been applied, for the critical notification: kept by
+ * BackupManager beside the site restore manifest, as `<manifest>.report.json`.
+ */
+export interface RestoreReport {
+    version: 1;
+    source: string;
+    /** When the backup was taken. */
+    backup: string;
+    /** The backup's parts that were not staged, by manager. */
+    notRestored: string[];
+    /** The job runs since the backup, read from the live job state when the restore was staged. */
+    jobRuns: JobRunSince[];
+    /** Who started the restore. */
+    stagedBy?: string;
+}
+/** BackupManager's fault, and the dashboard banner, while there is no backup key (#1561, #1912). */
+export declare const BACKUP_KEY_MISSING = "NGDPBASE_BACKUP_KEY is not set, so backups are NOT encrypted: the document (password hashes, settings with their secrets) and the file archives beside it are in the clear, and the credentials store, the databases and the instance .env are left out";
+/** The title of the one notification about it. */
+export declare const BACKUP_KEY_MISSING_TITLE = "Backups are not encrypted";
+/**
+ * The config key that records an admin's confirmation that the backup key is
+ * saved off the server (#1876): the fingerprint of the key they saved. A
+ * different key (a new one made, or one replaced) asks again.
+ */
+export declare const BACKUP_KEY_SAVED_KEY = "ngdpbase.backup.key-saved-fingerprint";
+/** The banner while no admin has confirmed the backup key is saved off the server (#1876). */
+export declare function backupKeyNotSaved(fingerprint: string): string;
+/**
+ * The config key that records the names (never the values) the instance
+ * `.env` set when an admin last confirmed it is saved off the server (#1976),
+ * sorted. Null until the first check records the baseline. The names, not
+ * only their fingerprint, so the reminder can say which keys were added or
+ * removed.
+ */
+export declare const ENV_KEYS_SAVED_KEY = "ngdpbase.backup.env-keys-saved";
+/** The title of the one notification per change of the `.env` key set (#1976). */
+export declare const ENV_KEYS_CHANGED_TITLE = "Save a copy of .env";
+/** The banner while the instance `.env` sets other names than the ones an admin last confirmed saved (#1976): names only, never a value. */
+export declare function envKeysChanged(change: {
+    added: readonly string[];
+    removed: readonly string[];
+}): string;
+/** What Admin → Backup shows about the instance `.env` key set (#1976): names only, never a value. */
+export interface EnvKeysInfo {
+    /** The names the file sets now, sorted. */
+    names: string[];
+    /** Their fingerprint, posted back with the confirmation so a stale page is refused. */
+    fingerprint: string;
+    /** Whether a set has been recorded at all: false only before the first check. */
+    recorded: boolean;
+    /** Names set now that were not when an admin last confirmed. */
+    added: string[];
+    /** Names an admin confirmed that the file no longer sets. */
+    removed: string[];
+    /** The file holds this site's current backup key, so a saved copy is a saved key too. */
+    holdsBackupKey: boolean;
+}
+/** What Admin → Backup shows about the backup key: never the key itself. */
+export interface BackupKeyInfo {
+    set: boolean;
+    fingerprint: string | null;
+    /** An admin confirmed this key is saved off the server. */
+    saved: boolean;
+}
+/** The scheduled job automatic backups run as (#1720). */
+export declare const AUTO_BACKUP_JOB_ID = "backup.auto";
+/** The routine check that backups are still happening (#1563). */
+export declare const BACKUP_HEALTH_JOB_ID = "backup.health";
+/** The title of the notification sent when backups stop working (#1563): a backup failed, or none is recent enough. */
+export declare const BACKUPS_NOT_WORKING_TITLE = "Backups are not working";
+/** A backup that failed (#1563), as kept in the health record until a backup succeeds. */
+export interface BackupFailure {
+    /** When it failed, ISO 8601. */
+    at: string;
+    /** Why, in words an admin can act on. */
+    reason: string;
+    /** The document that was written anyway (a backup with a part missing), so it is not counted as good. */
+    filename?: string;
+}
+/** Whether backups are working, as Admin → Backup and the /admin dashboard show it (#1563). */
+export interface BackupHealth {
+    /** The newest backup in the backup directory that is not a failed one: when, how big (with the files beside it), where. */
+    lastGood: {
+        filename: string;
+        at: string;
+        size: number;
+        location: string;
+    } | null;
+    /** Automatic backups are on and scheduled. */
+    autoBackup: boolean;
+    /** The next automatic backup, ISO 8601, or null. */
+    nextRun: string | null;
+    /** Free bytes at the backup destination, or null when it can't be told. */
+    freeBytes: number | null;
+    /** The backup that failed, until one succeeds. */
+    failure: BackupFailure | null;
+    /** How long the site may go without a good backup before that is an outage, in ms. */
+    staleAfterMs: number;
+    /** No good backup within `staleAfterMs`, or none at all. */
+    stale: boolean;
+    /** The outage, in one line, while backups are not working; null when they are. */
+    fault: string | null;
+}
+/** A number of bytes as admins read it. */
+export declare function formatBytes(bytes: number): string;
+/** Why a backup could not be written, in words an admin can act on: the system's error codes named (#1563). */
+export declare function describeBackupError(err: unknown): string;
+/**
+ * The longest gap between two runs of a schedule (#1563): what "the
+ * auto-backup interval" is for a schedule that is not evenly spaced (Monday,
+ * Wednesday and Friday is three days at its longest; monthly is 31). Counted
+ * over the next year's runs, at most 400 of them.
+ */
+export declare function longestGapMs(schedule: Schedule, from: Date): number;
+/**
+ * The automatic-backup settings as a schedule (#1720): `ngdpbase.backup.auto-backup-time`
+ * (HH:MM) and `ngdpbase.backup.auto-backup-days` — `daily`, `monthly` (the 1st),
+ * `weekdays` (Monday to Friday), or day names such as `Mon,Wed,Fri`.
+ *
+ * In `timeZone`: the server's own, because the timer this replaces compared
+ * the server's local clock, so an existing setting keeps its time.
+ *
+ * Throws, naming the setting, for a time or a day it does not understand. The
+ * timer this replaces matched neither, so such a setting never backed up, and
+ * said nothing.
+ */
+export declare function autoBackupSchedule(time: string, days: string, timeZone: string): ScheduleInput;
+/**
+ * The text of the critical "not restored" notification (#1876): what the
+ * restore put back, what it did not, and per job the runs since the backup —
+ * its name, when it last ran and how that ended — newest first.
+ */
+export declare function describeNotRestored(input: {
+    source: string;
+    backup: string;
+    applied: string[];
+    notRestored: string[];
+    jobRuns: JobRunSince[];
+    nameOf: (jobId: string) => string;
+    missingReport?: boolean;
+}): string;
+declare class BackupManager extends BaseManager {
+    private backupDirectory;
+    private maxBackups;
+    private autoBackupEnabled;
+    private autoBackupTime;
+    private autoBackupDays;
+    private provider;
+    private providerClass;
+    /** A restore started from Admin → Backup, while it runs (#1723). */
+    private restoreRunning;
+    /** The outage this manager set because backups are not working (#1563), so only that one is cleared when they work again. */
+    private healthFault;
+    /**
+     * The end of the queue of work that reads or changes the backup directory
+     * one at a time (#1563): a backup with its pruning, a restore's safety
+     * backup and staging, and the routine health check (`exclusive`).
+     */
+    private exclusiveTail;
+    /**
+     * Creates a new BackupManager instance
+     *
+     * @constructor
+     * @param {any} engine - The wiki engine instance
+     */
+    constructor(engine: WikiEngine);
+    /** Normalize a config provider name to its PascalCase class name. */
+    private normalizeProviderName;
+    /**
+     * Load the configured backup storage provider (#170). Mirrors the
+     * dynamic-import + fallback pattern used by AuditManager / SearchManager.
+     * Falls back to FileBackupProvider on any load error so backups never
+     * silently lose their storage target.
+     */
+    private loadProvider;
+    /**
+     * Initialize BackupManager
+     *
+     * @async
+     * @param {Record<string, unknown>} [config={}] - Configuration object (unused, reads from ConfigurationManager)
+     * @returns {Promise<void>}
+     * @throws {Error} If ConfigurationManager is not available
+     */
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * Backup BackupManager's own state (conforms to BaseManager interface)
+     *
+     * @returns {Promise<BaseBackupData>} Backup data for this manager
+     */
+    backup(): Promise<BaseBackupData>;
+    /**
+     * Restore BackupManager's own state (conforms to BaseManager interface)
+     *
+     * @param {BaseBackupData} backupData - Backup data from backup()
+     * @returns {Promise<void>}
+     */
+    restoreState(backupData: BaseBackupData): Promise<void>;
+    /**
+     * Perform a complete backup of all managers to a file
+     *
+     * Process:
+     * 1. Get all registered managers from engine
+     * 2. Call backup() on each manager
+     * 3. Aggregate all backup data
+     * 4. Compress to .gz file
+     * 5. Save with timestamp
+     * 6. Clean up old backups
+     *
+     * @param {BackupOptions} options - Backup options
+     * @param {string} options.filename - Custom filename (optional)
+     * @param {boolean} options.compress - Whether to compress (default: true)
+     * @param ctx - Who asked (#1179): the request's subject, or the schedule's JobContext. First and mandatory — a full copy of the instance is made on someone's behalf.
+     * @returns {Promise<string>} Path to created backup file
+     */
+    createBackup(ctx: ActorContext, options?: BackupOptions): Promise<string>;
+    /**
+     * One at a time (#1563): `work` starts once everything queued before it
+     * has finished, whether that succeeded or failed, and is never run beside
+     * it. A second backup asked for while one runs waits for it and is then
+     * taken in its own right: its own document, its own options, its own
+     * result. So a backup's pruning never deletes files another backup, a
+     * restore or the health check is reading. In-process only: one server
+     * process owns a backup directory.
+     */
+    private exclusive;
+    /** `createBackup` itself, for a caller already holding the queue (`exclusive`): a restore's safety backup. */
+    private createBackupNow;
+    /**
+     * The instance `.env` beside the document (#1876): `<stem>.env.tar.enc`,
+     * only ever encrypted, and never with the backup key's own line. Without
+     * the key it is left out (`LEFT_OUT_FOR_NO_KEY`). BackupManager owns this
+     * part: the file belongs to no manager, and the backup key is this one's.
+     */
+    private backupInstanceEnv;
+    /** `<FAST_STORAGE>/.env`, or null when the instance data folder is not known. */
+    private instanceEnvFile;
+    /** The files the managers wrote beside one backup document (#1723). */
+    private companionsOf;
+    /** Remove the files the managers wrote beside one backup document (#1723), except those in `keep`. */
+    private removeCompanions;
+    /**
+     * Without `NGDPBASE_BACKUP_KEY` backups are still taken, unencrypted, with
+     * the credentials store and the databases left out (#1561, #1876). That is
+     * said twice, never once per backup (operator, #1912): BackupManager is
+     * degraded for as long as the key is missing — the persistent banner on the
+     * dashboard — and admins get ONE notification the first time. It is
+     * deduplicated the way other one-time notices are (`pageMetadataMissing`):
+     * by its title among the stored notifications, which persist across
+     * restarts and keep a dismissed one. With the key set the fault clears.
+     * Read at start and at each backup.
+     */
+    private checkBackupKey;
+    /**
+     * Whether a notification with this title (and message, when given) is
+     * among the stored ones, which persist across restarts and keep a dismissed
+     * one: how a one-time notice is deduplicated (`pageMetadataMissing`).
+     */
+    private alreadyNotified;
+    /**
+     * The instance `.env` key set against the one an admin last confirmed saved
+     * off the server (#1976): the reminder while they differ, else null. Names
+     * only — a value is never kept, logged or shown.
+     *
+     * The first check on a site with nothing recorded (a new site, or one
+     * upgraded to this release) records the names it finds as the baseline,
+     * silently: an upgraded site's keys are already in every encrypted backup,
+     * and a new site is already asked to save its backup key, so asking again at
+     * that moment would be noise. Every change after it asks. One notification
+     * per change, deduplicated by its title and words among the stored
+     * notifications, so a restart never repeats it.
+     */
+    private checkInstanceEnvKeys;
+    /** The instance `.env` key set as Admin → Backup shows it (#1976), or null when the site has no instance data folder or the file can't be read. Never a value. */
+    envKeysInfo(): EnvKeysInfo | null;
+    /** The backup key as Admin → Backup shows it: set or not, its fingerprint, and whether an admin confirmed it is saved. Never the key. */
+    backupKeyInfo(): BackupKeyInfo;
+    /**
+     * The backup key itself, for the one page that asks an admin to copy it
+     * off the server (#1876). The route asks `config-manage`, with its fresh
+     * sign-in; nothing else shows, logs or returns it.
+     */
+    revealBackupKey(): string | null;
+    /**
+     * The instance `.env` exactly as it is on disk, backup key line included,
+     * for an admin to keep a copy off the server (#1938). The route asks
+     * `config-manage`, with its fresh sign-in. Recorded as `secret-reveal`:
+     * the file, never its contents. Null when the site has no instance `.env`.
+     */
+    revealInstanceEnv(ctx: ActorContext): Promise<Buffer | null>;
+    /**
+     * An admin confirms the backup key with this fingerprint is saved off the
+     * server (#1876). Recorded in the configuration (`ngdpbase.backup.key-saved-fingerprint`,
+     * written through ConfigurationManager, which records the change), so it
+     * survives restarts; a different key asks again. Refused when the
+     * fingerprint is not the current key's: the page they read was stale.
+     *
+     * With `envFingerprint` (#1976) the admin confirms the whole `.env` is
+     * saved, the one confirmation for both reminders: the names it sets are
+     * recorded (`ngdpbase.backup.env-keys-saved`), and so is the backup key
+     * when the file holds it. Refused when the names changed since the page
+     * was loaded.
+     */
+    confirmBackupKeySaved(ctx: ActorContext, fingerprint: string, envFingerprint?: string): Promise<void>;
+    private configManager;
+    private setting;
+    /** `ngdpbase.backup.health-file`: the failure kept across restarts. */
+    private healthFile;
+    private readHealthRecord;
+    private writeHealthRecord;
+    /**
+     * A backup failed (#1563): kept until one succeeds, across restarts, and
+     * said once — admins get one "Backups are not working" notification per
+     * reason, not one per failed attempt. `notify: false` where another
+     * notification already said it ("A backup is incomplete").
+     */
+    private recordBackupFailure;
+    /** A backup succeeded (#1563): the failure kept since the last one is cleared. */
+    private clearBackupFailure;
+    /** The newest backup in the backup directory that is not the failed one: read from the directory, never remembered. */
+    private lastGoodBackup;
+    /** Automatic backups as they run (#1563): on only when scheduled and not paused, with the schedule in force and the next run. */
+    private autoBackupRun;
+    /**
+     * Whether backups are working (#1563), from what is on disk: the newest
+     * good backup in the backup directory, the failure kept in the health
+     * record, the automatic-backup schedule, and free space at the destination.
+     *
+     * No good backup within the window is an outage. The window is
+     * `ngdpbase.backup.stale-interval-multiplier` (default 2) times the longest
+     * gap between automatic backups when they are on, and
+     * `ngdpbase.backup.stale-fallback-days` (default 7) when they are off.
+     */
+    getBackupHealth(): Promise<BackupHealth>;
+    /**
+     * Bring the dashboard in line with whether backups work (#1563): an outage
+     * (`markDegraded`) while a backup has failed or none is recent enough,
+     * cleared — only that one — once they work, then the backup key's reminder
+     * (`checkBackupKey`), which never hides an outage. A stretch with no recent
+     * backup notifies admins once, kept across restarts. Run at start, on the
+     * `backup.health` timer, and after every backup.
+     */
+    refreshBackupHealth(): Promise<BackupHealth | null>;
+    /** `refreshBackupHealth` itself, for a caller already holding the queue: a backup that just ended. */
+    private refreshBackupHealthNow;
+    /** One notification per stretch without a recent good backup (#1563), kept across restarts by the health record. */
+    private notifyStaleOnce;
+    /**
+     * The routine check (#1563): `backup.health`, every
+     * `ngdpbase.backup.health-check-interval` ms (default one hour), as the
+     * system principal (BackgroundJobManager's routine maintenance). It is how
+     * a backup that never comes is noticed.
+     */
+    private registerHealthCheck;
+    /**
+     * Refuse a backup there is no room for (#1563), before anything is
+     * written: free space at the destination against the last backup's size
+     * (the document and every file beside it) times
+     * `ngdpbase.backup.space-margin` (default 1.5). Skipped when there is no
+     * earlier backup or the free space can't be told; a write that then runs
+     * out still fails, and says so.
+     */
+    private checkFreeSpace;
+    /**
+     * Read a backup just written back (#1563): decrypt it (every record's GCM
+     * tag), decompress it, parse it and check its shape, on a worker thread.
+     * A document that does not read back is removed — it is not a backup — and
+     * the backup fails, naming why.
+     */
+    private verifyWrittenBackup;
+    private notifyAdmins;
+    /**
+     * Restore all managers from a backup file
+     *
+     * Process:
+     * 1. Read and decompress backup file
+     * 2. Parse JSON data
+     * 3. Validate backup structure
+     * 4. Call restore() on each manager with its data
+     *
+     * The databases (#1723) go first, and are staged for the next start rather
+     * than restored in place: a fresh backup of the live data is taken, then
+     * DatabaseManager stages every database in the backup. If either fails,
+     * nothing at all is restored.
+     *
+     * @param ctx - Who asked (#1179): a restore takes a backup and replaces the instance's data on someone's behalf.
+     * @param {string} backupPath - Path to backup file
+     * @param {RestoreOptions} options - Restore options
+     * @param {boolean} options.skipValidation - Skip validation (default: false)
+     * @param {string[]} options.managerFilter - Only restore specific managers
+     * @returns {Promise<RestoreResults>} Restore results
+     */
+    restoreFromFile(ctx: ActorContext, backupPath: string, options?: RestoreOptions): Promise<RestoreResults>;
+    private restoreFromFileNow;
+    /** Whether this site's manager of that name stages its restore (#1876), or its entry is declared folders (#1985). */
+    private restoresStaged;
+    /**
+     * Each loaded add-on's folders (#1985): its `dataPath`, which counts for it
+     * whatever it declares, and any further folders its module declares; under
+     * the entry its files have always had (`addonEntryName`). For a backup, a
+     * `dataPath` that does not exist is left out: that add-on keeps no files.
+     */
+    private addonParts;
+    /** What a manager declares, and an add-on's folders recorded under the same entry (#1985). */
+    private declaredFor;
+    /** Every entry with declared folders or files, in registration order, add-ons' after (#1985). */
+    private declaredParts;
+    /**
+     * Put a staged restore of an add-on's folders in place before its
+     * `register()` runs, so before any of its managers reads them (#1985).
+     * AddonsManager calls it as it loads each add-on.
+     */
+    applyAddonPartsAtStart(slug: string, folders: BackupFolder[]): StagedRestoreAtStart | null;
+    /** The site restore manifest, as configured (#1876). */
+    private siteRestorePath;
+    /** The site restore staged and waiting for the next start, or null (#1876). Throws for a record that can't be read. */
+    getStagedSiteRestore(): SiteRestoreManifest | null;
+    /** A databases-only restore is refused while a site restore is staged: it would take the site restore's databases away from it (#1876). */
+    private refuseIfSiteRestoreStaged;
+    /**
+     * Stage a whole-site restore (#1876): every manager in `names` stages its
+     * part for the next start, after a complete backup of the live data, under
+     * one site restore manifest. All or nothing: a part that can't be staged
+     * discards every part staged before it, and the live data is never
+     * touched. The next start applies every part or none
+     * (`src/utils/siteRestore.ts`).
+     */
+    private stageSiteRestore;
+    /**
+     * Throw away a staged site restore before the restart applies it (#1876):
+     * every staged file and the record are removed, the live data is
+     * untouched. Recorded first (`backup-restore-cancel`, refuse).
+     */
+    cancelStagedSiteRestore(ctx: ActorContext): Promise<SiteRestoreManifest>;
+    /** Where this manager keeps the report of a staged restore: beside the site restore manifest (#1876). */
+    private restoreReportPath;
+    private removeRestoreReport;
+    /**
+     * Record, when a restore is staged, what it will not bring back (#1876):
+     * the parts of the backup not in it, and the job runs since the backup,
+     * read from the live job state now, before the restore replaces it.
+     */
+    private writeRestoreReport;
+    /**
+     * Tell admins what this start did with a staged restore (#1876). Called
+     * once every manager and add-on has started (`WikiEngine.initializeAddons`):
+     * each owner applied (or set aside) its part as it started, add-ons last.
+     * After any restore that was applied, a critical notification lists what it
+     * did not bring back, and the job runs between the backup and the restore.
+     */
+    reportRestoreAtBoot(): Promise<void>;
+    /**
+     * The critical notification after a restore was applied (#1876): every
+     * part of the site it did not bring back, and the job runs between the
+     * backup and the restore (name, last run, result), which are not in the
+     * restored job history. Jobs are never run again because of a restore.
+     */
+    private reportNotRestored;
+    /** The report written when the restore was staged, or null. */
+    private readRestoreReport;
+    /**
+     * `backup-restore-applied` (#1876, operator-approved): written at the start
+     * that applied a restore, so into the restored audit log — which otherwise
+     * would not say a restore happened (the `backup-restore` record of the
+     * staging is in the log it replaced). Names the backup, when it was taken,
+     * who started the restore and what was put back. on-failure: continue — the
+     * restore is already in place.
+     */
+    private recordRestoreApplied;
+    /** Tell admins what the start did with a staged site restore (#1876). */
+    private reportSiteRestoreOutcome;
+    /**
+     * The backups in the backup directory with the database files beside each
+     * (#1723): what Admin → Backup offers to download and restore. Read from
+     * the file names, so no document is opened to list them.
+     */
+    listStoredBackups(): Promise<StoredBackup[]>;
+    /** A backup in the backup directory by its bare filename, or null: never a path the caller made up. */
+    findStoredBackup(filename: string): Promise<StoredBackup | null>;
+    /**
+     * One backup as a `.tar` stream (#1723, D2): the document and every file
+     * beside it — the databases, and the archives of attachment files, role
+     * membership, persons, organizations, footnotes and comments (#1876) —
+     * read from disk as the stream is consumed, never built in memory. With
+     * the backup key set every file in it is encrypted under that key, which
+     * is never in the archive (#1723, #1561).
+     */
+    backupArchive(filename: string): Promise<{
+        name: string;
+        stream: Readable;
+    }>;
+    /** Whether a restore started from Admin → Backup is still taking its fresh backup or staging. */
+    isRestoreRunning(): boolean;
+    /** The managers on this site whose restore is staged (#1876), in registration order: what a site restore stages. */
+    private stagedManagerNames;
+    /**
+     * What a whole-site restore on this site puts back and what it does not
+     * (#1945), in the words admins read: the labels of the "not restored"
+     * notification (`restoreLabel`, `NEVER_IN_A_BACKUP`), so the restore card
+     * and the notification after the restart say the same. Read from the
+     * managers on this site, not from any backup: a backup can hold less (the
+     * credentials store of one taken without the backup key), never more.
+     */
+    siteRestoreScope(): {
+        restored: string[];
+        notRestored: string[];
+    };
+    /**
+     * The restore waiting for the next start, whichever it is (#1945): a site
+     * restore, or a databases-only one. A site restore stages the databases
+     * too, so it is the one named while both records are there.
+     */
+    getStagedRestore(): {
+        scope: RestoreScope;
+        source: string;
+        stagedBy: string;
+    } | null;
+    /**
+     * Throw away the restore waiting for the next start, whichever it is
+     * (#1945): a staged site restore through `cancelStagedSiteRestore`, a
+     * databases-only one through `DatabaseManager.cancelStagedRestore`. Each
+     * records `backup-restore-cancel` first (refuse).
+     */
+    cancelStagedRestore(ctx: ActorContext): Promise<{
+        scope: RestoreScope;
+        source: string;
+    }>;
+    /**
+     * Start a restore of a stored backup from Admin → Backup: recorded, then a
+     * fresh backup of the live data and the staging run in the background, and
+     * admins are told when it is staged or why it was not. Nothing changes
+     * until the next restart, which the site never does by itself. Refused
+     * while another is being prepared, and when a restore is already staged
+     * unless `replace` says to replace it.
+     *
+     * - `scope: 'databases'` (the default; #1723, D1): the databases only.
+     *   Refused while a site restore is staged, since that includes them.
+     * - `scope: 'site'` (#1945): a whole-site restore, every manager whose
+     *   restore is staged and the instance .env, all or nothing
+     *   (`stageSiteRestore`), from any stored backup. It replaces a staged
+     *   restore of either kind only with `replace`.
+     *
+     * @returns the running restore, for a caller (a test) that waits on it.
+     */
+    startRestore(ctx: ActorContext, filename: string, options?: {
+        replace?: boolean;
+        scope?: RestoreScope;
+    }): Promise<{
+        done: Promise<RestoreResults | null>;
+    }>;
+    /**
+     * List all available backups
+     * @returns {Promise<BackupFileInfo[]>} List of backup files with metadata
+     */
+    listBackups(): Promise<BackupFileInfo[]>;
+    /**
+     * Clean up old backups, keeping only maxBackups most recent
+     * @private
+     */
+    private cleanupOldBackups;
+    /**
+     * Get the most recent backup file path
+     * @returns {Promise<string | null>} Path to most recent backup, or null if none exist
+     */
+    getLatestBackup(): Promise<string | null>;
+    /**
+     * Return current auto-backup configuration and last backup info for the admin UI.
+     */
+    getAutoBackupStatus(): Promise<{
+        config: AutoBackupConfig;
+        lastBackup: Date | null;
+    }>;
+    /**
+     * Update auto-backup configuration and persist to config store.
+     * Restarts the scheduler with the new settings.
+     */
+    updateAutoBackupConfig(config: Partial<AutoBackupConfig>, ctx: ActorContext): Promise<void>;
+    /**
+     * Automatic backups as a scheduled job (#1720, epic #1611).
+     *
+     * They ran from a timer that checked every minute for an exact match of the
+     * clock, so a server that was down at the backup time — or a tick that
+     * landed a minute late — skipped that backup and left no record that it had
+     * (operator: backups are never silent, #1563). As a scheduled job a backup
+     * missed while the server was down runs once when it is back (`catchUp:
+     * 'latest'`), a failed one is tried again and then reported, and the run
+     * survives a restart. A backup still running when the next one comes due is
+     * not doubled (`overlap: 'skip'`).
+     *
+     * Called at start and whenever the settings change. With automatic backups
+     * off, or a setting that cannot be read, the job is registered without a
+     * schedule: it can still be run by hand, and nothing runs by itself.
+     */
+    private scheduleAutoBackup;
+}
+export default BackupManager;