@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.11

package/dist/db-backup/database-restore.service.d.ts

@@ -0,0 +1,760 @@
+import { Readable } from 'node:stream';
+import { ConfigService } from '@nestjs/config';
+import type { Job } from '../jobs/index';
+import { DbBackupRestoreGate } from './restore-gate';
+import type { SystemDatabaseBackupValue } from '@marinoscar/platform-contract/db-backup';
+import { JobsService } from '../jobs/index';
+import type { DatabaseBackupRun, DbBackupPrisma } from './data/db-backup-db';
+import { type DbBackupNotifier, type DbBackupMaintenance } from './ports';
+import { SystemSettingsService } from '../settings/index';
+import { type StorageProvider } from '../storage/index';
+import { type AdminConnection, type AdminQueryClient } from './admin-connection.util';
+import { type BackupTarget } from './backup-target';
+import { DbBackupEvents } from './db-backup-events';
+import { DatabaseBackupRunnerService } from './db-backup-runner.service';
+import type { PgConnection } from './pg-dump.util';
+import { DatabaseRestorePreflightService, type RestorePreflightResult } from './restore-preflight.service';
+/**
+ * The states written to `database_backup_runs.restore_status`.
+ *
+ * `restoring` covers everything from the download to the last byte
+ * `pg_restore` writes — the phase that takes hours — because splitting it
+ * further would imply a progress signal this design does not have: a
+ * `pg_restore` in flight reports nothing a caller could poll, and inventing
+ * finer states that all mean "still restoring" would be dishonest precision.
+ *
+ * A plain string column rather than an enum, exactly as `schema.prisma` says:
+ * adding `rolled_back` below cost no migration, which is the whole argument.
+ *
+ * @stability experimental
+ */
+export declare const RESTORE_STATUSES: readonly ["restoring", "verifying", "swapping", "completed", "failed", "rolled_back"];
+/** @stability experimental */
+export type RestoreStatus = (typeof RESTORE_STATUSES)[number];
+/**
+ * Audit actions. `<area>:<verb>`, matching `maintenance:enable` and `users:update`.
+ *
+ * @stability experimental
+ */
+export declare const RESTORE_AUDIT_START = "db_restore:start";
+/** @stability experimental */
+export declare const RESTORE_AUDIT_SWAP = "db_restore:swap";
+/** @stability experimental */
+export declare const RESTORE_AUDIT_COMPLETE = "db_restore:complete";
+/**
+ * Not one of the three the issue names, and it earns its place: a restore that
+ * FAILED is the one an operator greps `audit_events` for, and without this row
+ * the only trace of it in that table is a `db_restore:start` with nothing after
+ * it — indistinguishable from a restore that is still running.
+ *
+ * @stability experimental
+ */
+export declare const RESTORE_AUDIT_FAILED = "db_restore:failed";
+/**
+ * Written into the database the rollback promoted, after the renames.
+ *
+ * @stability experimental
+ */
+export declare const RESTORE_AUDIT_ROLLBACK = "db_restore:rollback";
+/**
+ * `target_type` on every row above; `target_id` is the backup run's id.
+ *
+ * @stability experimental
+ */
+export declare const RESTORE_AUDIT_TARGET_TYPE = "database_backup_run";
+/**
+ * Parallel `pg_restore` jobs.
+ *
+ * THE SAME NUMBER THE GUIDED COMMAND BLOCK PRINTS, and deliberately imported
+ * rather than restated: an operator who pasted #284's block and an operator who
+ * pressed the button must not get restores with different performance
+ * characteristics, or the two paths become impossible to compare when one of
+ * them is slow.
+ *
+ * @stability experimental
+ */
+export declare const RESTORE_JOBS = 4;
+/**
+ * How often the `pre_restore` safety backup's row is re-read while waiting for
+ * it.
+ *
+ * `startBackup` is DETACHED by contract (it returns as soon as the row is
+ * claimed, because a multi-gigabyte dump outlives every HTTP timeout in the
+ * stack), so the only way to know it finished is to watch the row it writes.
+ * Five seconds against a dump measured in minutes to hours is free.
+ *
+ * @stability experimental
+ */
+export declare const PRE_RESTORE_POLL_INTERVAL_MS = 5000;
+/**
+ * Extra grace on top of `databaseBackup.runStaleMinutes` before giving up on
+ * the safety backup.
+ *
+ * The dump's own budget IS the stale window (see the runner), so a run that has
+ * outlived the window plus this margin is one the stale sweep is about to
+ * settle. Waiting longer would mean a restore that hangs forever because a
+ * container disappeared.
+ *
+ * @stability experimental
+ */
+export declare const PRE_RESTORE_SETTLE_GRACE_MS = 60000;
+/**
+ * How long the rollback waits before exiting, so its HTTP response can be
+ * flushed first.
+ *
+ * ⚠ THE RESTORE'S OWN SWAP NEEDS NO SUCH DELAY and does not take one: it runs
+ * detached, and the request that started it was answered hours earlier. A
+ * rollback is different — it is fast enough that an operator is still holding
+ * the connection when the process decides to exit, and killing the process
+ * mid-response would show them a network error for an operation that succeeded.
+ *
+ * @stability experimental
+ */
+export declare const ROLLBACK_EXIT_DELAY_MS = 500;
+/**
+ * What a blocked caller is shown during the swap.
+ *
+ * ⚠ NO APPLICATION, PRODUCT OR REPOSITORY NAME. This is a template; every
+ * user-visible string in it describes what is happening, not whose it is.
+ *
+ * @stability experimental
+ */
+export declare const RESTORE_MAINTENANCE_MESSAGE: string;
+/**
+ * The `Job.type` every restore row carries.
+ *
+ * DEFINED HERE, NOT IN THE HANDLER, for the reason `BACKUP_JOB_TYPE` is defined
+ * in the runner: the enqueueing side and the executing side must agree on this
+ * string exactly, and only one of the two can own the definition. This service
+ * enqueues, so it owns it and `handlers/db-restore-run.handler.ts` imports it.
+ *
+ * PERMANENT once rows of this type exist — `jobs` rows outlive the handler that
+ * produced them, so renaming this orphans every historical restore.
+ *
+ * @stability experimental
+ */
+export declare const DB_RESTORE_RUN_TYPE = "db.restore.run";
+/**
+ * What `startRestore` writes into the job's payload, and what the handler reads
+ * back out.
+ *
+ * ⚠ THE FOUR DERIVED VALUES ARE CARRIED, NOT RECOMPUTED, and that is the one
+ * decision in this interface. `scratchDatabase`, `oldDatabase` and `startedAt`
+ * come from the PRE-FLIGHT this restore was gated by, and they have already
+ * been handed to the caller in the `started` result. Deriving them again in the
+ * handler — from a different `now`, minutes later — would produce different
+ * names, and the API response, the run row and the DDL would then name three
+ * databases. `startRestore`'s own comment already makes this argument about the
+ * pre-flight's names versus freshly derived ones; the queue simply widens the
+ * gap between the two clocks from microseconds to however long the job waits.
+ *
+ * `rollbackMode` is carried for the same reason: it is the pre-flight's
+ * EFFECTIVE mode, which disk pressure may have downgraded, and re-deciding it
+ * later could take a restore the operator was told would be reversible by
+ * rename and quietly make it reversible only by a multi-hour replay.
+ *
+ * Identifiers only, per `EnqueueJobInput.payload` — `runId` is re-read at run
+ * time so the handler works from the row's current state.
+ *
+ * @stability experimental
+ */
+export interface RestoreJobPayload {
+    /** Run id. */
+    runId: string;
+    /** Actor user id. */
+    actorUserId: string | null;
+    /** Scratch database. */
+    scratchDatabase: string;
+    /** Old database. */
+    oldDatabase: string;
+    /** Rollback mode. */
+    rollbackMode: 'retain_database' | 'pre_restore_dump';
+    /** ISO-8601. The instant the restore was accepted, not the instant it ran. */
+    startedAt: string;
+}
+/**
+ * Narrows a job's opaque payload to {@link RestoreJobPayload}, or throws.
+ *
+ * THROWS RATHER THAN DEFAULTING, and this is the one place in this file where
+ * that is obviously right: every field is a database NAME or an identity, and a
+ * defaulted one would be a `CREATE DATABASE`/`ALTER DATABASE ... RENAME`
+ * against a name nobody chose. A malformed payload is a bug, and a `failed` job
+ * carrying "malformed payload" is the correct outcome — with `maxAttempts: 1`
+ * it is also a final one, so nothing retries a restore whose plan cannot be
+ * read.
+ *
+ * @stability experimental
+ */
+export declare function parseRestoreJobPayload(payload: unknown): RestoreJobPayload;
+/**
+ * What `startRestore` decided. #286 turns each case into a status code.
+ *
+ * @stability experimental
+ */
+export type StartRestoreResult = 
+/** Accepted. The work is detached; poll `restore_status` on the run. */
+{
+    /** Outcome. */
+    outcome: 'started';
+    /** Run id. */
+    runId: string;
+    /** Scratch database. */
+    scratchDatabase: string;
+    /** Old database. */
+    oldDatabase: string;
+    /** Preflight. */
+    preflight: RestorePreflightResult;
+}
+/**
+ * The pre-flight did not come back `ok`, so NOTHING was started and nothing
+ * was created. The whole verdict is returned rather than an error message:
+ * a `guided` outcome carries a command block the operator needs.
+ */
+ | {
+    /** Outcome. */
+    outcome: 'refused';
+    /** Preflight. */
+    preflight: RestorePreflightResult;
+}
+/**
+ * A restore is already in flight IN THIS PROCESS.
+ *
+ * ⚠ A RESULT, NOT AN EXCEPTION, and PROCESS-LOCAL, and both are honest rather
+ * than convenient. Nothing has gone wrong — #286 turns this into a 409 the
+ * same way `CancelBackupResult` turns `not_running_here` into a truthful
+ * answer. And there is no database constraint that could do better: a
+ * restore's state lives on the row of the BACKUP it replays, so two restores
+ * of two different archives are two different rows and no unique index over
+ * them can conflict. What actually makes concurrent restores impossible is the
+ * SINGLE-REPLICA prerequisite the `replicas` gate warns about and the runbook
+ * states; this guard is the in-process half of it, for the case that
+ * prerequisite is met and an operator double-clicks.
+ */
+ | {
+    /** Outcome. */
+    outcome: 'already_running';
+    /** Run id. */
+    runId: string;
+};
+/**
+ * What `rollback` managed. All three are honest answers, including the last.
+ *
+ * @stability experimental
+ */
+export type RestoreRollbackResult = 
+/**
+ * `retain_database` mode: the displaced database was renamed back into place.
+ * SECONDS — this is the entire justification for paying roughly double the
+ * PostgreSQL volume during the retention window.
+ */
+{
+    /** Outcome. */
+    outcome: 'renamed';
+    /** Run id. */
+    runId: string;
+    /** Promoted. */
+    promoted: string;
+    /** Parked. */
+    parked: string;
+}
+/**
+ * `pre_restore_dump` mode: there is no database to rename, so this delegates
+ * back into the restore path against the safety backup. HOURS.
+ */
+ | {
+    /** Outcome. */
+    outcome: 'restore_started';
+    /** Run id. */
+    runId: string;
+    /** Pre restore run id. */
+    preRestoreRunId: string;
+}
+/**
+ * Neither exists. REPORTED HONESTLY RATHER THAN AS A FAILURE: nothing went
+ * wrong just now, the rollback window simply closed, and an operator needs to
+ * know that as a fact rather than as an error to retry.
+ */
+ | {
+    /** Outcome. */
+    outcome: 'unavailable';
+    /** Run id. */
+    runId: string;
+    /** Reason. */
+    reason: string;
+};
+/** @stability experimental */
+export interface StartRestoreOptions {
+    /** The administrator who asked. `null` only for an internal delegation. */
+    actorUserId?: string | null;
+    /** Passed straight through to the pre-flight; unblocks the schema gate alone. */
+    overrideSchemaMismatch?: boolean;
+    /** Injected so a test can pin the derived database names. */
+    now?: Date;
+}
+/**
+ * Everything this service does that touches a cluster, a disk, a child process
+ * or the process's own lifetime.
+ *
+ * ONE OBJECT, INJECTED AS A WHOLE, following `RestorePreflightSeam` and
+ * `DatabaseBackupEngine`: a suite that needs a live PostgreSQL, a `pg_restore`
+ * binary and permission to call `process.exit` is a suite CI skips, and a
+ * skipped test guards nothing — which for THIS file would mean the swap
+ * sequence is not tested at all.
+ *
+ * @stability experimental
+ */
+export interface DatabaseRestoreSeam {
+    /** Where the admin session goes, and which database it is about. */
+    resolveConnection(): AdminConnection;
+    /**
+     * One unit of work on a maintenance-database session.
+     *
+     * ⚠ UNBOUNDED, unlike pre-flight's. `admin-connection.util.ts` §
+     * `statement_timeout` explains why: a wall-clock bound that fires part-way
+     * through `CREATE DATABASE` or `ALTER DATABASE ... RENAME` buys ambiguity
+     * about the state of the database the application is about to be pointed at,
+     * and there is no safe automated response to "maybe".
+     */
+    withAdminConnection<T>(
+    /** Config. */
+    config: AdminConnection, 
+    /** Fn. */
+    fn: (client: AdminQueryClient) => Promise<T>): Promise<T>;
+    /** An absolute path carrying the janitor-swept prefix. Creates nothing. */
+    tempFilePath(): string;
+    /** Streams `source` to `path`, hashing and counting in the SAME single pass. */
+    writeArchiveToFile(
+    /** Source. */
+    source: Readable, 
+    /** Path. */
+    path: string): Promise<{
+        /** The bytes written. */
+        bytes: bigint;
+        /** Lower-case hex SHA-256 of them. */
+        sha256: string;
+    }>;
+    /** `pg_restore --list` over a local file. Zero means "restores nothing". */
+    readTocEntryCount(file: string): Promise<number>;
+    /** `pg_restore --exit-on-error -j N` into an existing database. */
+    runPgRestore(options: {
+        connection: PgConnection;
+        file: string;
+        jobs: number;
+    }): Promise<void>;
+    /** Best-effort removal; a missing file is not an error. */
+    removeFile(path: string): Promise<void>;
+    /** Waits `ms` milliseconds. */
+    sleep(ms: number): Promise<void>;
+    /** The current instant. */
+    now(): Date;
+    /**
+     * Ends this process so a supervisor can start one with a fresh pool.
+     *
+     * A SEAM, not a direct call, for one reason: a test that exercised the swap
+     * would otherwise kill its own Jest worker, so the most dangerous sequence in
+     * the repository would be the one sequence with no test.
+     */
+    exitProcess(code: number, delayMs?: number): void;
+}
+/**
+ * DI token for {@link DatabaseRestoreSeam}.
+ *
+ * OPTIONAL AND LEFT UNBOUND in `DbBackupModule`, the same discipline
+ * `DB_BACKUP_ENGINE`, `JOB_CLOCK` and `RESTORE_PREFLIGHT_SEAM` follow. A stubbed
+ * seam in production would be a restore that reports success having renamed
+ * nothing — or, worse, an `exitProcess` that does not exit, leaving a process
+ * serving from a pool pointed at a database that no longer exists.
+ *
+ * @stability experimental
+ */
+export declare const DATABASE_RESTORE_SEAM = "DATABASE_RESTORE_SEAM";
+/**
+ * The real seam. Every member is a thin binding to the utility that owns it.
+ *
+ * @stability experimental
+ */
+export declare const defaultDatabaseRestoreSeam: DatabaseRestoreSeam;
+/**
+ * The restore: replays an archive into a scratch database, verifies it, swaps it in by renaming, carries the backup catalog and the registered `RestoreCarryOver` tables across, and exits the process. Also the rollback. Server-only, permanently.
+ *
+ * @stability experimental
+ */
+export declare class DatabaseRestoreService {
+    private readonly prisma;
+    private readonly settings;
+    private readonly preflight;
+    private readonly runner;
+    private readonly maintenance;
+    private readonly notifications;
+    private readonly config;
+    private readonly jobs;
+    private readonly deployment;
+    private readonly events?;
+    private readonly logger;
+    private readonly seam;
+    /**
+     * The restore this process is executing, or `null`.
+     *
+     * PROCESS-LOCAL AND HONESTLY SO — see {@link StartRestoreResult}'s
+     * `already_running` variant. There is no database constraint that could
+     * express "one restore at a time", because a restore's state lives on the row
+     * of the BACKUP it replays and two restores are two different rows. The real
+     * exclusion is the single-replica prerequisite; this is the guard for the case
+     * that prerequisite is met and an operator double-clicks.
+     */
+    private activeRestoreRunId;
+    constructor(prisma: DbBackupPrisma, settings: SystemSettingsService, storage: StorageProvider, preflight: DatabaseRestorePreflightService, runner: DatabaseBackupRunnerService, maintenance: DbBackupMaintenance, notifications: DbBackupNotifier, config: ConfigService, jobs: JobsService, deployment: DbBackupRestoreGate, seam?: DatabaseRestoreSeam, target?: BackupTarget, events?: DbBackupEvents | undefined);
+    /** Where the archive is read from. */
+    private readonly target;
+    /**
+     * Runs the pre-flight and, if it comes back `ok`, starts the restore in the
+     * background.
+     *
+     * ⚠ THE PRE-FLIGHT RUNS HERE, not only in #286's endpoint, and the duplication
+     * is deliberate. The gates are the difference between "a restore that fails"
+     * and "a restore that destroys a database", and a service that trusted its
+     * caller to have run them would be one refactor — or one new caller, such as
+     * this file's own rollback path — away from a restore with no gates at all.
+     * The cost is a handful of catalog reads.
+     *
+     * @param run - the archive to replay. Looked up, permission-checked and
+     * `completed`-filtered by #286, exactly as pre-flight's own contract says.
+     */
+    startRestore(run: DatabaseBackupRun, options?: StartRestoreOptions): Promise<StartRestoreResult>;
+    /**
+     * Runs a queued restore. THE HANDLER'S ONLY ENTRY POINT (#353, epic #345).
+     *
+     * ⚠ IT DOES NOT RE-RUN THE PRE-FLIGHT, and that is deliberate. The gates ran
+     * in `startRestore`, seconds ago, and their VERDICT — including the two
+     * database names and the effective rollback mode — is what the payload
+     * carries; re-running them here would derive different names from a different
+     * clock and quietly disagree with the answer the operator was already given.
+     * What this method does re-read is the RUN ROW, by id, because the payload
+     * carries identifiers rather than copies (`EnqueueJobInput.payload`) and the
+     * row's storage key and checksum must be the current ones.
+     *
+     * THROWS TO FAIL, like every handler. `executeRestore` records the failure on
+     * the run's restore columns first — that is still its contract, and it is
+     * still the only account an operator has — and then rethrows so the queue can
+     * write `lastError` and mark the row `failed`. Before #353 it swallowed,
+     * because there was no caller left to tell; now there is one.
+     */
+    executeRestoreJob(job: Job): Promise<void>;
+    /**
+     * The six phases.
+     *
+     * ⚠ IT RECORDS THE FAILURE AND THEN RETHROWS (#353, epic #345). Until the
+     * restore became a queue job this method NEVER REJECTED: it wrote the failure
+     * onto the run's restore columns and returned, because it was launched
+     * detached and there was no caller left to tell. There is one now — the
+     * worker running `db.restore.run` — and a handler that returned normally after
+     * a failed restore would be settled `succeeded`, which is exactly the "job row
+     * that lies" this conversion exists to avoid. The row-first ordering is
+     * unchanged and still matters: the run's `restore_status` and `restore_error`
+     * are the operator's account of what happened, and they are written before
+     * anything is rethrown, so they survive whatever the queue then decides.
+     */
+    private executeRestore;
+    /**
+     * Phase 1: pull the object to a seekable file and prove it is still the
+     * archive it was.
+     *
+     * Two checks, and they catch different things:
+     *
+     *   - THE CHECKSUM proves the bytes are unchanged since the dump was hashed
+     *     on its way into storage. It cannot tell you they are a valid archive —
+     *     a correctly-checksummed zero-byte object is still zero bytes.
+     *   - THE TABLE OF CONTENTS proves `pg_restore` can read them and that there
+     *     is something in there to restore. It cannot tell you they are the RIGHT
+     *     bytes.
+     *
+     * @throws {@link DatabaseRestoreArchiveError} before anything has been created.
+     */
+    private downloadAndVerifyArchive;
+    /**
+     * Phase 2: the `pre_restore` safety dump — the way back when the displaced
+     * database will not be kept.
+     *
+     * ⚠ ONLY IN `pre_restore_dump` MODE. Under `retain_database` the way back is
+     * the displaced database itself, and taking a full dump as well would add
+     * hours to a restore to duplicate a guarantee it already has.
+     *
+     * ⚠ IT IS AWAITED TO COMPLETION, and that is why this method exists at all.
+     * `startBackup` is detached by contract: it returns the moment the row is
+     * claimed, with `pg_dump` still streaming. Swapping while that dump was in
+     * flight would rename the database out from under it and leave a truncated
+     * "safety" archive — a way back that does not work, discovered at the only
+     * moment it is ever used.
+     */
+    private takePreRestoreBackupIfNeeded;
+    /**
+     * Watches a backup's row until it leaves `pending`/`running`.
+     *
+     * Bounded by the dump's own budget — `runStaleMinutes`, which is what the
+     * runner passes as the child's timeout — plus a grace margin, after which the
+     * stale sweep is about to settle the row anyway and waiting longer would mean
+     * a restore that hangs forever because a container vanished.
+     */
+    private awaitBackupSettled;
+    /**
+     * Phase 3: `CREATE DATABASE <live>_restore_<ts>`.
+     *
+     * ⚠ THE EXISTENCE CHECK IS HERE AND NOT IN PRE-FLIGHT, deliberately: the
+     * timestamp in the name is generated when the name is built, so a pre-flight
+     * check would have proved something about a different name. `databaseExists`
+     * is exported precisely for this call site.
+     *
+     * A collision is refused rather than reused. A scratch database that already
+     * exists holds another restore's half-replayed contents, and `pg_restore`
+     * would happily add to them.
+     */
+    private createScratchDatabase;
+    /**
+     * Phase 5: is what came out of the archive a database this application could
+     * run on?
+     *
+     * `--exit-on-error` already proved that no statement failed. It cannot prove
+     * the archive contained statements worth running, which is the same gap
+     * `DatabaseBackupVerificationError` closes on the other side of the round
+     * trip. Two checks, deliberately cheap, deliberately not clever:
+     *
+     *   - AT LEAST ONE ORDINARY TABLE outside the system schemas. Zero means the
+     *     replay produced an empty database.
+     *   - A NON-EMPTY `_prisma_migrations`. A database with tables but no
+     *     migration ledger is not one this application can boot against, and it
+     *     is what a restore of somebody else's archive looks like.
+     *
+     * ⚠ IT DELIBERATELY DOES NOT RE-READ "the newest applied migration".
+     * `migration-state.util.ts` is emphatic that exactly one query answers that
+     * question, because the pre-flight's schema gate compares its two callers'
+     * answers; a third reader here would be a third chance for the rule to drift.
+     * The archive's migration is already on the run row and was already gated.
+     */
+    private verifyRestoredDatabase;
+    /**
+     * Phase 6. Seconds, and the only destructive window in the whole design.
+     *
+     * Read this together with the file header. The ordering below is not
+     * incidental — every line before the first rename is there so that the two
+     * renames have nothing left to fail on:
+     *
+     *   1. `swapping` on the row, so a poll sees the window open.
+     *   2. The swap audit row, written into the database that is ABOUT TO BE
+     *      DISPLACED — it survives in `<live>_old_<ts>`, and the completion row
+     *      written after the renames is the one that lands in the promoted
+     *      database with the whole timeline in its `meta`.
+     *   3. The catalog export, WITH THE POST-SWAP AUDIT VALUES ALREADY APPLIED.
+     *   4. The maintenance window, in memory, `allowAdmins: false`.
+     */
+    private swap;
+    /**
+     * Raise `db_backup.restore_completed`, AWAITED, from inside the promoted
+     * database (#288, epic #254).
+     *
+     * See the block comment at the call site for why this sits exactly where it
+     * does. What is worth saying HERE is the two things this method does that
+     * the other three operational notifiers do not:
+     *
+     * 1. IT RESOLVES THE ACTOR'S ADDRESS FROM THE RESTORED DATABASE, AND MAY
+     *    LEGITIMATELY FIND NOTHING. The account that triggered the restore is
+     *    looked up AFTER the swap, so it is looked up in the archive's copy of
+     *    `users` — and an operator whose account was created after the backup was
+     *    taken genuinely does not exist there. That is not an error to log
+     *    loudly; it is a true and rather important fact about the state the
+     *    deployment is now in, and it renders as "Not recorded" rather than as a
+     *    failure.
+     *
+     * 2. IT ADDS THE ACTOR TO THE AUDIENCE RATHER THAN SENDING THEM A SECOND
+     *    MESSAGE. `alsoNotifyUserIds` is unioned with the permission holders and
+     *    de-duplicated by user id inside the dispatcher, so an actor who also
+     *    holds `db_backup:read` gets exactly one email and one bell row. See
+     *    `NotifyPermissionHoldersOptions`.
+     *
+     * NEVER THROWS. `notifyPermissionHoldersNow` cannot reject by construction,
+     * and the try/catch covers the address lookup and the payload build — because
+     * a throw here would land in `executeRestore`'s `catch`, which would then
+     * record a COMPLETED restore as a failure and, worse, try to drop a scratch
+     * database that has already been promoted to live.
+     */
+    private announceRestoreCompleted;
+    /**
+     * The actor's email address as recorded IN THE RESTORED DATABASE, or `null`.
+     *
+     * `null` for three different and equally ordinary reasons: there was no actor
+     * (a restore triggered without one), the actor's account does not exist in
+     * the archive, or the read failed. None of them justifies holding up an exit
+     * or failing a completed restore, so all three collapse to `null` and the
+     * template gives it words.
+     */
+    private resolveActorEmail;
+    /**
+     * The application root, trailing slashes trimmed, or `undefined`.
+     *
+     * Same shape as `UsersService.appUrl()`; `undefined` makes the template omit
+     * its CTA rather than render a button that goes nowhere.
+     */
+    private appUrl;
+    /**
+     * THE TWO RENAMES, and the inner recovery between them.
+     *
+     * ⚠ ONE IMPLEMENTATION, USED BY BOTH DIRECTIONS. The restore parks the live
+     * database as `<live>_old_<ts>` and promotes the scratch database; the
+     * rollback parks the bad restore as a fresh `<live>_restore_<ts>` and promotes
+     * the retained original. They are the same three statements with the names
+     * exchanged, and writing them twice would mean the recovery `catch` — the one
+     * genuinely dangerous moment in this design — existed in two places, one of
+     * which would eventually be wrong.
+     *
+     * ⚠ THE MAINTENANCE WINDOW IS OPENED WITH `allowAdmins: false`, IN MEMORY.
+     * See the file header: the persisted flag lives inside the database being
+     * renamed, and an admin request during the window would reach a database that
+     * momentarily does not exist.
+     *
+     * ⚠ THE WINDOW IS NOT CLOSED ON THE SUCCESS PATH. `process.exit(0)` is the
+     * release: closing it here would open a gap in which this process served
+     * requests through a connection pool it is about to tear down. It IS closed
+     * when the swap failed and the original was renamed back, because then there
+     * is a working database to serve from and the deployment must not be left in
+     * a window nothing will ever close. It is deliberately LEFT OPEN when the
+     * recovery also failed — an orderly 503 beats five hundred stack traces
+     * against a database that is not there.
+     */
+    private renameSwap;
+    /**
+     * Reads `database_backup_runs` out of the database that is about to be
+     * displaced, applying this restore's POST-SWAP audit values on the way past.
+     *
+     * ⚠ THE AUDIT VALUES ARE APPLIED HERE, NOT WRITTEN TO THE LIVE ROW. Writing
+     * "restore completed" to the database this restore is about to rename away
+     * would put the record of the operation in the one database nobody will ever
+     * open again. The row the operator eventually reads is the one this function
+     * builds.
+     *
+     * ⚠ THE SELF-FK IS STRIPPED INTO {@link CarriedCatalog.selfLinks} and applied
+     * in a second pass. See {@link CARRY_SELF_LINK_SQL}.
+     */
+    private exportCatalog;
+    /**
+     * Reads every registered `RestoreCarryOver` from the LIVE database, before
+     * the swap (#740). Ascending `order`; one transaction per carry with
+     * `app.rls_bypass` set transaction-locally.
+     *
+     * ⚠ A FAILING EXPORT ABORTS NOTHING. It is logged and the carry is skipped:
+     * refusing a restore because an app's own carry cannot be read would turn a
+     * fork's mistake into a database that cannot be restored at all.
+     */
+    private exportExtraCarries;
+    /**
+     * Writes the carried catalog into the database that has just been promoted.
+     *
+     * ⚠ IT NEVER THROWS, AND THAT IS A SAFETY PROPERTY RATHER THAN LAZINESS. By
+     * the time this runs, both renames have succeeded: the restored database IS
+     * the live one and the swap is irreversible. A throw here would travel to
+     * `executeRestore`'s `catch`, which would try to drop a scratch database that
+     * no longer exists under that name and then write a `failed` restore status
+     * into a database that no longer holds that row — and it would tempt a future
+     * change to "roll the swap back", which at this point would mean discarding a
+     * database the deployment is already serving from. Losing the backup catalog
+     * is bad. Undoing a successful restore to avoid losing it would be worse.
+     *
+     * A separate session on the LIVE name, not the maintenance one: the rows go
+     * into the promoted database, and the outer session is attached elsewhere
+     * precisely so it could do the renaming.
+     */
+    private reinsertCatalog;
+    /**
+     * Undoes a restore, by whichever of the two routes this deployment still has.
+     *
+     * The two costs are not comparable, and reporting which one happened is the
+     * whole reason this returns a discriminated result rather than a boolean:
+     *
+     *   - `retain_database` → ONE RENAME. Seconds. This is the entire
+     *     justification for paying roughly double the PostgreSQL volume for
+     *     `oldDatabaseRetentionHours`.
+     *   - `pre_restore_dump` → a full restore of the safety archive. HOURS,
+     *     and it goes back through `startRestore`, gates and all.
+     *   - Neither → `unavailable`, honestly. Nothing failed; the window closed.
+     *
+     * ⚠ THE DELEGATED RESTORE OVERRIDES THE SCHEMA GATE. The `pre_restore` dump
+     * was taken from the schema this code was running moments before the restore,
+     * so the live migration it would be compared against is the ARCHIVE's — the
+     * gate would block on a mismatch that exists only because the thing being
+     * undone happened. That block would be spurious, and it would fire at the
+     * exact moment an operator needs the way back.
+     */
+    rollback(run: DatabaseBackupRun, actorUserId: string | null): Promise<RestoreRollbackResult>;
+    /**
+     * The fast rollback: park the current live database, promote the retained one.
+     *
+     * ⚠ THE CATALOG IS CARRIED OVER HERE TOO, and it matters more than it looks.
+     * The retained database's `database_backup_runs` is as of the moment BEFORE
+     * the restore — so without a carry-over the rollback would delete every
+     * backup record created since, INCLUDING the `pre_restore` dump's, which under
+     * some configurations is the only remaining way back from the thing being
+     * undone. Reusing {@link exportCatalog} rather than writing a second, smaller
+     * version is the point: one carry-over, one set of FK rules.
+     */
+    private rollbackByRename;
+    /**
+     * Drops `<live>_old_<ts>` databases whose `oldDatabaseRetentionHours` window
+     * has passed.
+     *
+     * ⚠ ROW-DRIVEN, NOT NAME-DRIVEN, and that is a deliberate refusal. Sweeping
+     * `pg_database` for anything matching the `<live>_old_` prefix would be
+     * self-healing and would also DROP DATABASES THIS APPLICATION NEVER CREATED —
+     * specifically the one an operator makes by hand when they follow #284's
+     * guided command block, which uses exactly that name and which the runbook
+     * tells them to keep until they have verified the restore. An unattended cron
+     * that deletes a full copy of a production database nobody in this system
+     * recorded creating is not a trade worth making for tidiness.
+     *
+     * The cost is honest: if the catalog carry-over failed, the row naming the
+     * displaced database is gone and nothing here will ever drop it. That case
+     * logs CRITICAL at the time and is in the runbook.
+     *
+     * Called from `DatabaseBackupScheduleTask`'s ten-minute tick rather than from
+     * a `@Cron` of its own, for the reason `DbBackupModule` already gives about
+     * retention: a second timer is a second unsynchronised thing acting on the
+     * same subsystem, and a window measured in hours does not need a schedule
+     * finer than the one that already exists.
+     *
+     * @returns how many databases were actually dropped.
+     */
+    dropExpiredOldDatabases(policy: SystemDatabaseBackupValue, now: Date): Promise<number>;
+    /**
+     * One progress write. SWALLOWS ITS OWN FAILURES.
+     *
+     * The same call the backup heartbeat makes, for the same reason: a transient
+     * write failure — a recycled connection, a brief failover, a lock wait — is
+     * not evidence that a restore which is otherwise going perfectly should be
+     * abandoned. Abandoning a two-hour replay because one status UPDATE failed
+     * would be a self-inflicted outage, and the phase this is reporting on is the
+     * one where nothing has been touched yet anyway.
+     */
+    private writeRestoreState;
+    /** The terminal `failed` write, plus the audit row an operator greps for. */
+    private recordFailure;
+    /**
+     * One `audit_events` row, in the repository's existing shape
+     * (`UsersService.createAuditEvent`, `MaintenanceModeService.writeAuditEvent`).
+     *
+     * BEST-EFFORT. An audit write that threw inside `executeRestore`'s `try` would
+     * be a logging failure that failed a restore, and inside its `catch` it would
+     * be a logging failure that replaced the real diagnosis.
+     *
+     * ⚠ ROWS WRITTEN BEFORE THE SWAP LAND IN THE DATABASE THAT IS ABOUT TO BE
+     * DISPLACED. That is unavoidable — they are written while it is still the live
+     * database — and it is why the completion row is written afterwards, into the
+     * promoted database, carrying the whole timeline in its `meta`.
+     */
+    private writeAudit;
+    /**
+     * Gives the scratch database back after a failure before the swap.
+     *
+     * BEST-EFFORT AND IT NEVER MASKS THE ORIGINAL ERROR — the same contract the
+     * backup engine's partial-object delete has. Whatever broke the restore is
+     * what belongs on the row; "and the cleanup also failed" is a log line.
+     */
+    private dropScratchDatabase;
+}
+//# sourceMappingURL=database-restore.service.d.ts.map