@marinoscar/platform-contract 0.1.0-next.3 → 0.1.0-next.4

package/dist/cjs/db-backup/run-actions.js

@@ -0,0 +1,121 @@
+"use strict";
+// =============================================================================
+// What the three action routes answer with (issue #283, epic #254)
+// =============================================================================
+//
+// Delete, cancel and download. Each returns a body rather than a bare `204`,
+// and in each case the reason is the same: THE HONEST ANSWER HAS MORE THAN ONE
+// SHAPE, and a status code cannot carry the difference.
+//
+// -----------------------------------------------------------------------------
+// DELETE RETURNS `objectDeleted`, SO A MISSING OBJECT CANNOT STRAND A ROW
+// -----------------------------------------------------------------------------
+//
+// The archive is deleted first and the row second — the reverse order would
+// leave a multi-gigabyte object in the bucket that nothing points at, billed
+// forever, because the row is the only index of what exists there. The same
+// ordering, for the same reason, is in `db-backup-retention.service.ts`.
+//
+// But the object delete is BEST-EFFORT, and that is what this field reports. An
+// object that is already gone — pruned by a bucket lifecycle rule, removed by
+// hand, deleted by a previous attempt that failed after the object and before
+// the row — must not make the row undeletable. Failing the request would leave
+// an administrator staring at a row they cannot remove for a reason that is not
+// their fault and that no retry will change. So the row goes, and
+// `objectDeleted: false` says plainly that there was nothing in storage to
+// remove (or that removing it did not work), which is exactly the fact an
+// operator needs if they are reconciling a bucket against this table.
+//
+// -----------------------------------------------------------------------------
+// CANCEL RETURNS AN OUTCOME, BECAUSE CANCELLATION IS PROCESS-LOCAL
+// -----------------------------------------------------------------------------
+//
+// A dump is stopped by signalling a CHILD PROCESS, and only the API replica
+// that spawned it holds that handle. A run started on another replica genuinely
+// cannot be stopped from here. `DatabaseBackupRunnerService.cancel` already
+// says so — it returns a discriminated result rather than a `boolean` — and
+// this DTO's whole job is to carry that distinction to the client instead of
+// flattening it into a 200 that means "cancelled" when it does not.
+//
+// See `DatabaseBackupAdminService.cancelRun` for why `not_running_here` is a
+// 200 with an honest body rather than a 409 or a 500.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backupDownloadUrlSchema = exports.cancelBackupResultSchema = exports.deleteBackupResultSchema = void 0;
+const zod_1 = require("zod");
+const constants_js_1 = require("./constants.js");
+// ---------------------------------------------------------------------------
+// DELETE runs/:id
+// ---------------------------------------------------------------------------
+/**
+ * `DELETE /api/admin/db-backup/runs/:id` response.
+ *
+ * @stability stable
+ */
+exports.deleteBackupResultSchema = zod_1.z.object({
+    /** The run that was removed. Echoed so a client need not remember what it asked. */
+    id: zod_1.z.uuid(),
+    /**
+     * Whether the archive was removed from object storage.
+     *
+     * `false` is NOT an error and NOT a partial failure the caller should retry:
+     * the row is gone either way. It means storage had nothing to remove, or
+     * refused — see this file's header. An operator reconciling a bucket against
+     * this table is the reader this field exists for.
+     */
+    objectDeleted: zod_1.z.boolean(),
+});
+// ---------------------------------------------------------------------------
+// POST runs/:id/cancel
+// ---------------------------------------------------------------------------
+/**
+ * `POST /api/admin/db-backup/runs/:id/cancel` response.
+ *
+ * @stability stable
+ */
+exports.cancelBackupResultSchema = zod_1.z.object({
+    /** The run the cancel was aimed at. */
+    runId: zod_1.z.uuid(),
+    /**
+     * What actually happened.
+     *
+     *  - `signalled` — the dump process was killed and its upload torn down. The
+     *    run travels the ORDINARY failure path from there (partial object
+     *    deleted, row marked `failed`), so poll the run to watch it settle;
+     *    cancellation is deliberately not a second teardown mechanism.
+     *  - `not_running_here` — this replica holds no handle for that run. Either
+     *    another replica is executing it, or it settled between the read and the
+     *    cancel. Nothing was stopped, and the response says so.
+     */
+    outcome: zod_1.z.enum(constants_js_1.CANCEL_OUTCOMES),
+    /**
+     * One sentence an operator can act on, matched to `outcome`.
+     *
+     * Present so a UI can render the `not_running_here` case without hard-coding
+     * an explanation of process-local cancellation — the explanation belongs with
+     * the code that knows why, not in every client.
+     */
+    detail: zod_1.z.string(),
+});
+// ---------------------------------------------------------------------------
+// GET runs/:id/download
+// ---------------------------------------------------------------------------
+/**
+ * `GET /api/admin/db-backup/runs/:id/download-url` response.
+ *
+ * @stability stable
+ */
+exports.backupDownloadUrlSchema = zod_1.z.object({
+    /**
+     * A pre-signed URL that downloads the archive DIRECTLY FROM OBJECT STORAGE.
+     *
+     * Treat it as a credential: anyone holding it can fetch a complete copy of
+     * this deployment's database until it expires, with no bearer token of any
+     * kind. That is why `expiresIn` below is short — see
+     * `BACKUP_DOWNLOAD_URL_EXPIRY_SECONDS` in `db-backup-admin.service.ts`.
+     */
+    url: zod_1.z.url(),
+    /** Seconds the URL stays valid, counted from when it was issued. */
+    expiresIn: zod_1.z.number().int().positive(),
+});
+//# sourceMappingURL=run-actions.js.map

package/dist/cjs/db-backup/run-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-actions.js","sourceRoot":"","sources":["../../../src/db-backup/run-actions.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,mEAAmE;AACnE,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,wDAAwD;AACxD,EAAE;AACF,gFAAgF;AAChF,0EAA0E;AAC1E,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,6EAA6E;AAC7E,4EAA4E;AAC5E,yEAAyE;AACzE,EAAE;AACF,gFAAgF;AAChF,8EAA8E;AAC9E,8EAA8E;AAC9E,+EAA+E;AAC/E,gFAAgF;AAChF,kEAAkE;AAClE,2EAA2E;AAC3E,0EAA0E;AAC1E,sEAAsE;AACtE,EAAE;AACF,gFAAgF;AAChF,mEAAmE;AACnE,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,gFAAgF;AAChF,4EAA4E;AAC5E,4EAA4E;AAC5E,6EAA6E;AAC7E,oEAAoE;AACpE,EAAE;AACF,6EAA6E;AAC7E,sDAAsD;AACtD,gFAAgF;;;AAEhF,6BAAwB;AAExB,iDAAoE;AAEpE,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;;;GAIG;AACU,QAAA,wBAAwB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC/C,oFAAoF;IACpF,EAAE,EAAE,OAAC,CAAC,IAAI,EAAE;IAEZ;;;;;;;OAOG;IACH,aAAa,EAAE,OAAC,CAAC,OAAO,EAAE;CAC3B,CAAC,CAAC;AASH,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;GAIG;AACU,QAAA,wBAAwB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC/C,uCAAuC;IACvC,KAAK,EAAE,OAAC,CAAC,IAAI,EAAE;IAEf;;;;;;;;;;OAUG;IACH,OAAO,EAAG,OAAC,CAAC,IAAI,CAAC,8BAAe,CAAqD;IAErF;;;;;;OAMG;IACH,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE;CACnB,CAAC,CAAC;AASH,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;GAIG;AACU,QAAA,uBAAuB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC9C;;;;;;;OAOG;IACH,GAAG,EAAE,OAAC,CAAC,GAAG,EAAE;IAEZ,oEAAoE;IACpE,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAC"}

package/dist/cjs/db-backup/runs-list-query.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { type DbBackupEnum } from './constants.js';
+/**
+ * `GET /api/admin/db-backup/runs` query.
+ *
+ * @stability stable
+ */
+export declare const backupRunListQuerySchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    pageSize: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    status: z.ZodOptional<z.ZodEnum<DbBackupEnum<readonly ["pending", "running", "completed", "failed", "stale"]>>>;
+    trigger: z.ZodOptional<z.ZodEnum<DbBackupEnum<readonly ["manual", "scheduled", "pre_restore"]>>>;
+}, z.core.$strip>;
+/**
+ * The parsed, defaulted shape `DatabaseBackupAdminService.listRuns` consumes.
+ *
+ * @stability stable
+ */
+export type BackupRunListQuery = z.output<typeof backupRunListQuerySchema>;
+//# sourceMappingURL=runs-list-query.d.ts.map

package/dist/cjs/db-backup/runs-list-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runs-list-query.d.ts","sourceRoot":"","sources":["../../../src/db-backup/runs-list-query.ts"],"names":[],"mappings":"AAiCA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGrF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;;iBAWnC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/cjs/db-backup/runs-list-query.js

@@ -0,0 +1,53 @@
+"use strict";
+// =============================================================================
+// The backup-run list's filters (issue #283, epic #254)
+// =============================================================================
+//
+// Four query parameters and no more. `page`/`pageSize` are copied field for
+// field from `jobs/dto/job-list-query.dto.ts` — which copied them from
+// `users/dto/user-list-query.dto.ts` — so that every paginated list in this API
+// takes the same names and enforces the same 100-row ceiling. A client that has
+// learned one of these lists has learned all of them.
+//
+// `status` and `trigger` are plain equality matches on the two enums the row
+// carries, and they are the two questions an operator actually asks of this
+// table: "show me the failures" and "which of these did a person start".
+//
+// -----------------------------------------------------------------------------
+// WHAT IS DELIBERATELY NOT OFFERED
+// -----------------------------------------------------------------------------
+//
+// NO DATE WINDOW, and no `processedWithin` equivalent. The jobs list needs one
+// because a queue accumulates thousands of rows an hour; this table gains ONE
+// ROW PER BACKUP — a nightly schedule with the default retention of 7 keeps a
+// handful, and even a deployment that has been failing for a year has a few
+// hundred. Newest-first pagination answers every question a window would, and a
+// filter nobody needs is still a filter that has to be documented, tested and
+// kept correct.
+//
+// NO SORT PARAMETER. The ordering is `createdAt DESC`, always, and it is served
+// by the `[status, createdAt DESC]` index the retention sweep already uses. A
+// sortable column set would need an index per column to stay usable, which is a
+// real cost for a table whose only interesting order is "what happened most
+// recently".
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backupRunListQuerySchema = void 0;
+const zod_1 = require("zod");
+const constants_js_1 = require("./constants.js");
+/**
+ * `GET /api/admin/db-backup/runs` query.
+ *
+ * @stability stable
+ */
+exports.backupRunListQuerySchema = zod_1.z.object({
+    /** Page. */
+    page: zod_1.z.coerce.number().int().min(1).default(1),
+    /** Page size. */
+    pageSize: zod_1.z.coerce.number().int().min(1).max(100).default(20),
+    /** Exactly one status, matched for equality. Omitted, every run is listed. */
+    status: zod_1.z.enum(constants_js_1.BACKUP_STATUSES).optional(),
+    /** Exactly one trigger, matched for equality. Omitted, every run is listed. */
+    trigger: zod_1.z.enum(constants_js_1.BACKUP_TRIGGERS).optional(),
+});
+//# sourceMappingURL=runs-list-query.js.map

package/dist/cjs/db-backup/runs-list-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runs-list-query.js","sourceRoot":"","sources":["../../../src/db-backup/runs-list-query.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,wDAAwD;AACxD,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,uEAAuE;AACvE,gFAAgF;AAChF,gFAAgF;AAChF,sDAAsD;AACtD,EAAE;AACF,6EAA6E;AAC7E,4EAA4E;AAC5E,yEAAyE;AACzE,EAAE;AACF,gFAAgF;AAChF,mCAAmC;AACnC,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,8EAA8E;AAC9E,4EAA4E;AAC5E,gFAAgF;AAChF,8EAA8E;AAC9E,gBAAgB;AAChB,EAAE;AACF,gFAAgF;AAChF,8EAA8E;AAC9E,gFAAgF;AAChF,4EAA4E;AAC5E,aAAa;AACb,gFAAgF;;;AAEhF,6BAAwB;AAExB,iDAAqF;AAGrF;;;;GAIG;AACU,QAAA,wBAAwB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC/C,YAAY;IACZ,IAAI,EAAE,OAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/C,iBAAiB;IACjB,QAAQ,EAAE,OAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAE7D,8EAA8E;IAC9E,MAAM,EAAG,OAAC,CAAC,IAAI,CAAC,8BAAe,CAAqD,CAAC,QAAQ,EAAE;IAE/F,+EAA+E;IAC/E,OAAO,EAAG,OAAC,CAAC,IAAI,CAAC,8BAAe,CAAqD,CAAC,QAAQ,EAAE;CACjG,CAAC,CAAC"}

package/dist/cjs/db-backup/runs.d.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { type DbBackupEnum } from './constants.js';
+/**
+ * One `database_backup_runs` row as the admin API publishes it (both `BigInt` columns as decimal strings).
+ *
+ * @stability stable
+ */
+export declare const backupRunSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    status: z.ZodEnum<DbBackupEnum<readonly ["pending", "running", "completed", "failed", "stale"]>>;
+    trigger: z.ZodEnum<DbBackupEnum<readonly ["manual", "scheduled", "pre_restore"]>>;
+    bytesWritten: z.ZodString;
+    sizeBytes: z.ZodString;
+    storageProvider: z.ZodString;
+    storageKey: z.ZodString;
+    bucket: z.ZodString;
+    format: z.ZodString;
+    checksumSha256: z.ZodNullable<z.ZodString>;
+    verifiedAt: z.ZodNullable<z.ZodISODateTime>;
+    dbVersion: z.ZodNullable<z.ZodString>;
+    appVersion: z.ZodNullable<z.ZodString>;
+    migrationName: z.ZodNullable<z.ZodString>;
+    pgDumpVersion: z.ZodNullable<z.ZodString>;
+    lastError: z.ZodNullable<z.ZodString>;
+    startedAt: z.ZodNullable<z.ZodISODateTime>;
+    finishedAt: z.ZodNullable<z.ZodISODateTime>;
+    lastHeartbeatAt: z.ZodNullable<z.ZodISODateTime>;
+    createdById: z.ZodNullable<z.ZodUUID>;
+    restoreStatus: z.ZodNullable<z.ZodEnum<DbBackupEnum<readonly ["restoring", "verifying", "swapping", "completed", "failed", "rolled_back"]>>>;
+    restoreError: z.ZodNullable<z.ZodString>;
+    restoredAt: z.ZodNullable<z.ZodISODateTime>;
+    restoredById: z.ZodNullable<z.ZodUUID>;
+    restoreScratchDb: z.ZodNullable<z.ZodString>;
+    restoreOldDb: z.ZodNullable<z.ZodString>;
+    swappedAt: z.ZodNullable<z.ZodISODateTime>;
+    preRestoreBackupId: z.ZodNullable<z.ZodUUID>;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+/**
+ * The exact object shape the API's `toRunDto` produces, and therefore the wire shape.
+ *
+ * @stability stable
+ */
+export type BackupRunResponse = z.infer<typeof backupRunSchema>;
+//# sourceMappingURL=runs.d.ts.map

package/dist/cjs/db-backup/runs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runs.d.ts","sourceRoot":"","sources":["../../../src/db-backup/runs.ts"],"names":[],"mappings":"AA4EA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAsD,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEvG;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwK1B,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/cjs/db-backup/runs.js

@@ -0,0 +1,232 @@
+"use strict";
+// =============================================================================
+// One `database_backup_runs` row, as the admin API publishes it
+// =============================================================================
+// (issue #283, epic #254)
+//
+// This schema describes the JSON an administrator receives, NOT the Prisma
+// model, and the gap between the two is the whole reason this file exists.
+//
+// -----------------------------------------------------------------------------
+// ⚠ `bytesWritten` AND `sizeBytes` ARE `BigInt` COLUMNS, AND `JSON.stringify`
+// REFUSES `bigint` OUTRIGHT
+// -----------------------------------------------------------------------------
+//
+// `JSON.stringify(1n)` does not produce `1`, does not produce `"1"`, and does
+// not produce `null`: it throws `TypeError: Do not know how to serialize a
+// BigInt`. So a handler that returns a raw Prisma row from this table is a
+// handler that throws AT SEND TIME — after the query ran, after the status code
+// was chosen, inside the framework's serializer — which is the single most
+// confusing place for an error to come from.
+//
+// The failure mode that makes this worth a header rather than a line comment is
+// that IT IS INVISIBLE TO AN ORDINARY UNIT TEST. A spec that calls the service
+// and object-compares the result passes happily: `expect(run.sizeBytes).toBe(
+// 12n)` is true, `toEqual` on the whole row is true, and nothing in the
+// assertion path ever serialises anything. The defect only appears when a real
+// response is turned into bytes. That is why {@link toRunDto} exists as ONE
+// function that every path returning a run goes through — the list, the single
+// get, the manual trigger — and why `test/db-backup/db-backup-admin.integration
+// .spec.ts` drives a run with genuinely large `BigInt` values through the real
+// router and asserts on the SERIALISED body.
+//
+// The columns are `BigInt` for a good reason and are not going to stop being
+// one: a dump crossing 2 GiB is ordinary, and a signed 32-bit column overflows
+// at 2147483647 — on the largest backups, which are exactly the deployments
+// this feature exists for. See `docs/specs/database-backup.md`,
+// "Model: `database_backup_runs`".
+//
+// THEY ARE PUBLISHED AS DECIMAL STRINGS, not as numbers. `Number(9_007_199_254
+// _740_993n)` is silently wrong — JSON's number type is a double, and a byte
+// count above 2^53 rounds. A string is exact, is what every JSON API that
+// carries 64-bit integers does, and forces a client to make its own decision
+// about precision rather than having one made for it invisibly.
+//
+// -----------------------------------------------------------------------------
+// TIMESTAMPS ARE CONVERTED EXPLICITLY TOO
+// -----------------------------------------------------------------------------
+//
+// The serializer would turn a `Date` into an ISO string on its own, exactly as
+// it does for `jobs/dto/job-response.dto.ts`. They are converted here anyway,
+// because the point of {@link toRunDto} is that WHAT IT RETURNS IS WHAT GOES ON
+// THE WIRE — a projection with no framework magic left in it. That property is
+// what lets a spec `JSON.stringify` its output directly and have proved
+// something about the response.
+//
+// -----------------------------------------------------------------------------
+// THE RESTORE COLUMNS ARE PUBLISHED BY #286, AND NOT BEFORE
+// -----------------------------------------------------------------------------
+//
+// `restoreStatus`, `restoreError`, `restoredAt`, `restoredById`,
+// `restoreScratchDb`, `restoreOldDb`, `swappedAt` and `preRestoreBackupId` sat
+// in `schema.prisma` unpublished through #283 and #285 for a stated reason:
+// eight fields whose only possible value was `null` would have been a
+// documented contract a client could not distinguish from "this build does not
+// implement restore".
+//
+// #286 IS THE ISSUE THAT MAKES THEM MEAN SOMETHING, and it does so by
+// necessity rather than by choice: `POST runs/:id/restore` returns as soon as
+// the cheap pre-flight gates have run and the restore then takes HOURS, so the
+// contract it publishes is "poll `GET runs/{id}`". That promise is unkeepable
+// while the polling endpoint does not carry `restoreStatus` — the caller would
+// be told to watch a field that is not in the response. So they are published
+// here, in the ONE projection every run path already goes through, rather than
+// hand-rolled into the restore routes' own bodies where the list and the single
+// get could not see them.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backupRunSchema = void 0;
+const zod_1 = require("zod");
+const constants_js_1 = require("./constants.js");
+/**
+ * One `database_backup_runs` row as the admin API publishes it (both `BigInt` columns as decimal strings).
+ *
+ * @stability stable
+ */
+exports.backupRunSchema = zod_1.z.object({
+    /** Id. */
+    id: zod_1.z.uuid(),
+    /** Status. */
+    status: zod_1.z.enum(constants_js_1.BACKUP_STATUSES),
+    /** Why this run exists. `pre_restore` runs are taken by #285, not by a person. */
+    trigger: zod_1.z.enum(constants_js_1.BACKUP_TRIGGERS),
+    /**
+     * Live progress, rewritten by the heartbeat roughly every 20 seconds while a
+     * dump streams; the final byte count once the run settles. Kept on a FAILED
+     * run rather than reset, because how far a dump got is the difference between
+     * "the database refused the connection" and "it died at 40 GB".
+     *
+     * A DECIMAL STRING — see this file's header.
+     */
+    bytesWritten: zod_1.z.string().regex(/^\d+$/),
+    /**
+     * The archive's final size, written once at completion. `"0"` on any run that
+     * has not completed: it is the answer to "how big is the object that exists",
+     * and until verification passes there is no object worth naming a size for.
+     *
+     * A DECIMAL STRING — see this file's header.
+     */
+    sizeBytes: zod_1.z.string().regex(/^\d+$/),
+    /**
+     * Where the archive is. The whole triple is recorded on the row rather than
+     * derived on read, so a bucket rename or a provider swap cannot make an old
+     * archive unlocatable.
+     */
+    storageProvider: zod_1.z.string(),
+    /** Storage key. */
+    storageKey: zod_1.z.string(),
+    /** Bucket. */
+    bucket: zod_1.z.string(),
+    /** Always `custom` today: `pg_dump -Fc`, the only format `pg_restore` can list and filter. */
+    format: zod_1.z.string(),
+    /** SHA-256 of the bytes that were streamed to storage. `null` until the run completes. */
+    checksumSha256: zod_1.z.string().nullable(),
+    /**
+     * When the uploaded object was streamed back and `pg_restore --list` read a
+     * non-empty table of contents from it.
+     *
+     * THE FIELD WORTH READING FIRST. A `completed` run with a `verifiedAt` is a
+     * backup that has been proven restorable-shaped at least once; nothing else
+     * on this row makes that claim.
+     */
+    verifiedAt: zod_1.z.iso.datetime().nullable(),
+    /** Provenance, all best-effort: none of the four may fail a backup. */
+    dbVersion: zod_1.z.string().nullable(),
+    /** App version. */
+    appVersion: zod_1.z.string().nullable(),
+    /**
+     * The newest applied migration — which SCHEMA this archive contains, and so
+     * whether the code that is running will understand what comes back.
+     */
+    migrationName: zod_1.z.string().nullable(),
+    /**
+     * The `pg_dump` client that wrote the archive (#352).
+     *
+     * `null` for every run taken before the column existed, and for any run
+     * whose `--version` could not be read. It earns its place on the node path:
+     * there the binary lives on a machine this API cannot inspect, and
+     * `pg_restore` cannot read an archive written by a NEWER `pg_dump` — so this
+     * is the field that answers "can the machine I am restoring on read this
+     * file" before the restore rather than during it.
+     */
+    pgDumpVersion: zod_1.z.string().nullable(),
+    /** Why the run failed, verbatim. `null` on a run that has not failed. */
+    lastError: zod_1.z.string().nullable(),
+    /** Started at. */
+    startedAt: zod_1.z.iso.datetime().nullable(),
+    /** Finished at. */
+    finishedAt: zod_1.z.iso.datetime().nullable(),
+    /**
+     * The last progress write. A `running` row whose heartbeat has stopped
+     * advancing is what #282's sweep marks `stale`.
+     */
+    lastHeartbeatAt: zod_1.z.iso.datetime().nullable(),
+    /**
+     * The administrator who asked, when a person did.
+     *
+     * `null` for a `scheduled` run — a timer has no user, and inventing one would
+     * put a name on an action nobody took.
+     */
+    createdById: zod_1.z.uuid().nullable(),
+    // -------------------------------------------------------------------------
+    // The restore columns (#285's work, published by #286's endpoints)
+    // -------------------------------------------------------------------------
+    /**
+     * ⚠ THE PROGRESS FIELD FOR A RESTORE, and the one `POST runs/:id/restore`
+     * tells its caller to poll.
+     *
+     * `null` on every run nobody has ever restored, which is almost all of them.
+     * Once a restore starts it walks `restoring` → `verifying` → `swapping` →
+     * `completed`, or stops at `failed`; `rolled_back` is a restore that was
+     * swapped in and then undone.
+     *
+     * `restoring` covers everything from the archive download to the last byte
+     * `pg_restore` writes — the phase measured in hours — because a `pg_restore`
+     * in flight reports nothing a caller could poll and inventing finer states
+     * that all mean "still restoring" would be dishonest precision.
+     *
+     * ⚠ THE SWAP ENDS IN `process.exit(0)`. A poller will therefore usually see
+     * `swapping` and then a connection error, and read `completed` only after the
+     * supervisor has restarted the process. That is success, not failure — see
+     * `docs/specs/database-restore.md`, "Migration roll-forward and exit".
+     */
+    restoreStatus: zod_1.z.enum(constants_js_1.RESTORE_STATUSES).nullable(),
+    /** Why a restore failed, verbatim. `null` on a restore that has not failed. */
+    restoreError: zod_1.z.string().nullable(),
+    /** When the restore finished. `null` while it is still running. */
+    restoredAt: zod_1.z.iso.datetime().nullable(),
+    /** The administrator who asked for the restore. `null` for an internal delegation. */
+    restoredById: zod_1.z.uuid().nullable(),
+    /**
+     * The database the archive was replayed into, before the swap renamed it into
+     * place. Recorded so a failed restore leaves a name a human can drop.
+     */
+    restoreScratchDb: zod_1.z.string().nullable(),
+    /**
+     * What the live database was renamed to at the swap.
+     *
+     * ⚠ IN `retain_database` MODE THIS IS THE WAY BACK. `POST runs/:id/rollback`
+     * renames exactly this database back into place — in seconds — for as long as
+     * it survives `databaseBackup.oldDatabaseRetentionHours`. `null` once the
+     * retention sweep has dropped it, which is precisely when a rollback answers
+     * `unavailable`.
+     */
+    restoreOldDb: zod_1.z.string().nullable(),
+    /** When the two renames completed. The moment the deployment changed databases. */
+    swappedAt: zod_1.z.iso.datetime().nullable(),
+    /**
+     * The `pre_restore` safety backup taken immediately before this restore's
+     * swap, when one was taken.
+     *
+     * ⚠ IN `pre_restore_dump` MODE THIS IS THE WAY BACK, and it is the run a
+     * rollback's `restore_started` mode tells you to poll — not this one. `null`
+     * in `retain_database` mode, where the retained database serves that purpose
+     * far more cheaply.
+     */
+    preRestoreBackupId: zod_1.z.uuid().nullable(),
+    /** Created at. */
+    createdAt: zod_1.z.iso.datetime(),
+    /** Updated at. */
+    updatedAt: zod_1.z.iso.datetime(),
+});
+//# sourceMappingURL=runs.js.map

package/dist/cjs/db-backup/runs.js.map

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

package/dist/cjs/db-backup/schemas.d.ts

@@ -0,0 +1,9 @@
+export * from './settings-schemas.js';
+export * from './config.js';
+export * from './runs.js';
+export * from './runs-list-query.js';
+export * from './run-actions.js';
+export * from './restore.js';
+export * from './node-credential.js';
+export * from './node-result.js';
+//# sourceMappingURL=schemas.d.ts.map

package/dist/cjs/db-backup/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/db-backup/schemas.ts"],"names":[],"mappings":"AAMA,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC"}

package/dist/cjs/db-backup/schemas.js

@@ -0,0 +1,31 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// The db-backup schemas, by route group (issue #740, PP-8.7): the
+// `databaseBackup` system-settings namespace (./settings-schemas.ts), the
+// admin routes under `/api/admin/db-backup` (./config.ts, ./runs.ts,
+// ./runs-list-query.ts, ./run-actions.ts, ./restore.ts,
+// ./node-credential.ts) and the `db.backup.run` node result
+// (./node-result.ts). The zod-free value lists live in ./constants.ts.
+__exportStar(require("./settings-schemas.js"), exports);
+__exportStar(require("./config.js"), exports);
+__exportStar(require("./runs.js"), exports);
+__exportStar(require("./runs-list-query.js"), exports);
+__exportStar(require("./run-actions.js"), exports);
+__exportStar(require("./restore.js"), exports);
+__exportStar(require("./node-credential.js"), exports);
+__exportStar(require("./node-result.js"), exports);
+//# sourceMappingURL=schemas.js.map

package/dist/cjs/db-backup/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/db-backup/schemas.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kEAAkE;AAClE,0EAA0E;AAC1E,qEAAqE;AACrE,wDAAwD;AACxD,4DAA4D;AAC5D,uEAAuE;AACvE,wDAAsC;AACtC,8CAA4B;AAC5B,4CAA0B;AAC1B,uDAAqC;AACrC,mDAAiC;AACjC,+CAA6B;AAC7B,uDAAqC;AACrC,mDAAiC"}