@marinoscar/platform-contract 0.0.0-stage → 0.1.0-next.4

package/dist/esm/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,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,eAAe,EAAqB,MAAM,gBAAgB,CAAC;AAEpE,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,oFAAoF;IACpF,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE;IAEZ;;;;;;;OAOG;IACH,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE;CAC3B,CAAC,CAAC;AASH,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,uCAAuC;IACvC,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE;IAEf;;;;;;;;;;OAUG;IACH,OAAO,EAAG,CAAC,CAAC,IAAI,CAAC,eAAe,CAAqD;IAErF;;;;;;OAMG;IACH,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;CACnB,CAAC,CAAC;AASH,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C;;;;;;;OAOG;IACH,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE;IAEZ,oEAAoE;IACpE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAC"}

package/dist/esm/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/esm/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/esm/db-backup/runs-list-query.js

@@ -0,0 +1,50 @@
+// =============================================================================
+// 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".
+// =============================================================================
+import { z } from 'zod';
+import { BACKUP_STATUSES, BACKUP_TRIGGERS } from './constants.js';
+/**
+ * `GET /api/admin/db-backup/runs` query.
+ *
+ * @stability stable
+ */
+export const backupRunListQuerySchema = z.object({
+    /** Page. */
+    page: z.coerce.number().int().min(1).default(1),
+    /** Page size. */
+    pageSize: z.coerce.number().int().min(1).max(100).default(20),
+    /** Exactly one status, matched for equality. Omitted, every run is listed. */
+    status: z.enum(BACKUP_STATUSES).optional(),
+    /** Exactly one trigger, matched for equality. Omitted, every run is listed. */
+    trigger: z.enum(BACKUP_TRIGGERS).optional(),
+});
+//# sourceMappingURL=runs-list-query.js.map

package/dist/esm/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,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,eAAe,EAAE,eAAe,EAAqB,MAAM,gBAAgB,CAAC;AAGrF;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,YAAY;IACZ,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/C,iBAAiB;IACjB,QAAQ,EAAE,CAAC,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,CAAC,CAAC,IAAI,CAAC,eAAe,CAAqD,CAAC,QAAQ,EAAE;IAE/F,+EAA+E;IAC/E,OAAO,EAAG,CAAC,CAAC,IAAI,CAAC,eAAe,CAAqD,CAAC,QAAQ,EAAE;CACjG,CAAC,CAAC"}

package/dist/esm/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/esm/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/esm/db-backup/runs.js

@@ -0,0 +1,229 @@
+// =============================================================================
+// 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.
+// =============================================================================
+import { z } from 'zod';
+import { BACKUP_STATUSES, BACKUP_TRIGGERS, RESTORE_STATUSES } from './constants.js';
+/**
+ * One `database_backup_runs` row as the admin API publishes it (both `BigInt` columns as decimal strings).
+ *
+ * @stability stable
+ */
+export const backupRunSchema = z.object({
+    /** Id. */
+    id: z.uuid(),
+    /** Status. */
+    status: z.enum(BACKUP_STATUSES),
+    /** Why this run exists. `pre_restore` runs are taken by #285, not by a person. */
+    trigger: z.enum(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: 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: 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: z.string(),
+    /** Storage key. */
+    storageKey: z.string(),
+    /** Bucket. */
+    bucket: z.string(),
+    /** Always `custom` today: `pg_dump -Fc`, the only format `pg_restore` can list and filter. */
+    format: z.string(),
+    /** SHA-256 of the bytes that were streamed to storage. `null` until the run completes. */
+    checksumSha256: 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: z.iso.datetime().nullable(),
+    /** Provenance, all best-effort: none of the four may fail a backup. */
+    dbVersion: z.string().nullable(),
+    /** App version. */
+    appVersion: 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: 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: z.string().nullable(),
+    /** Why the run failed, verbatim. `null` on a run that has not failed. */
+    lastError: z.string().nullable(),
+    /** Started at. */
+    startedAt: z.iso.datetime().nullable(),
+    /** Finished at. */
+    finishedAt: z.iso.datetime().nullable(),
+    /**
+     * The last progress write. A `running` row whose heartbeat has stopped
+     * advancing is what #282's sweep marks `stale`.
+     */
+    lastHeartbeatAt: 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: 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: z.enum(RESTORE_STATUSES).nullable(),
+    /** Why a restore failed, verbatim. `null` on a restore that has not failed. */
+    restoreError: z.string().nullable(),
+    /** When the restore finished. `null` while it is still running. */
+    restoredAt: z.iso.datetime().nullable(),
+    /** The administrator who asked for the restore. `null` for an internal delegation. */
+    restoredById: 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: 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: z.string().nullable(),
+    /** When the two renames completed. The moment the deployment changed databases. */
+    swappedAt: 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: z.uuid().nullable(),
+    /** Created at. */
+    createdAt: z.iso.datetime(),
+    /** Updated at. */
+    updatedAt: z.iso.datetime(),
+});
+//# sourceMappingURL=runs.js.map

package/dist/esm/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/esm/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/esm/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/esm/db-backup/schemas.js

@@ -0,0 +1,15 @@
+// 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.
+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.js.map

package/dist/esm/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,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/esm/db-backup/settings-schemas.d.ts

@@ -0,0 +1,217 @@
+import { z } from 'zod';
+import { type DbBackupEnum } from './constants.js';
+/**
+ * The retention policy of the `databaseBackup` namespace: how many ordinary
+ * `completed` archives to keep (`count`) and how old one may get
+ * (`maxAgeDays`). Both are optional; an archive is pruned when EITHER rule
+ * says so, and the newest completed archive is never pruned. `retentionCount`
+ * stays beside it as the alias of `count` (read and write): see
+ * `mergeDatabaseBackupSettings` for how the two stay in step.
+ *
+ * @stability experimental
+ */
+export declare const backupRetentionSchema: z.ZodObject<{
+    count: z.ZodOptional<z.ZodNumber>;
+    maxAgeDays: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * The retention policy.
+ *
+ * @stability experimental
+ */
+export type BackupRetention = z.infer<typeof backupRetentionSchema>;
+/**
+ * Database backup and restore policy (`databaseBackup`).
+ *
+ * `dayOfWeek` and `dayOfMonth` are BOTH always present and both always valid,
+ * whatever `frequency` says. The alternative — a discriminated union keyed on
+ * `frequency` — would mean switching a schedule from weekly to monthly and
+ * back loses the day the operator had chosen, and would make a PATCH that
+ * changes only `frequency` invalid unless it also carried the other field.
+ * Storing an inert-but-remembered value is the cheaper mistake.
+ *
+ * `dayOfMonth` stops at 28 rather than 31 so that "monthly" means every month:
+ * a schedule pinned to the 30th silently skips February.
+ *
+ * `restoreRollbackMode` decides what happens to the database a restore
+ * displaced — `retain_database` keeps it (renamed, reachable, deleted later by
+ * `oldDatabaseRetentionHours`), `drop_database` does not. The default is to
+ * retain, because the failure mode of retaining is disk and the failure mode
+ * of dropping is a restore from the wrong dump with nothing to go back to.
+ *
+ * `nodeOffloadEnabled` (#352, epic #345) decides whether `db.backup.run` may be
+ * claimed by a WORKER NODE at all. DEFAULT FALSE, and it is deliberately a
+ * SECOND switch rather than a reuse of `nodes.jobSecretBrokerEnabled`, because
+ * the two answer different questions and a deployment can genuinely want one
+ * without the other:
+ *
+ *   - `nodes.jobSecretBrokerEnabled` — MAY THE BROKER ISSUE ANYTHING AT ALL?
+ *     A statement about the fleet: are these machines inside the trust
+ *     boundary for short-lived credentials of any kind?
+ *   - `databaseBackup.nodeOffloadEnabled` — MAY *THIS* TYPE LEAVE THE SERVER?
+ *     A statement about one workload: is dumping the whole database on a
+ *     machine that is not the API server what this deployment wants, given
+ *     that the node needs a network route to PostgreSQL and the archive's
+ *     bytes will cross whatever network sits between them?
+ *
+ * Collapsing them would mean enabling brokering for any future type — a
+ * fork's own `nodeSecretBroker` — silently enables shipping the database
+ * dump off-box too, which is not a decision anybody made. Both must be true,
+ * AND the broker must report itself usable, before the type is offered to a
+ * node; see `NodesService.nodeEligibleTypes`. Off (either one) means the type
+ * is withheld from the claim and the in-process worker takes the backup, which
+ * is exactly what happened before node offload existed.
+ *
+ * `storageProvider` CARRIES NO `.min(1)`, AND ITS DEFAULT IS THE EMPTY STRING
+ * (#373, epic #372). Empty is the one spelling of "unset" — the same decision
+ * the `storage` namespace below makes and for the same reason; it is not
+ * nullable and not optional-in-storage, so no consumer ever has to ask "absent,
+ * or empty?" and get two answers. Empty means "whatever provider is active",
+ * which is the only default a template repository can ship honestly: a literal
+ * would have to be a guess at somebody else's deployment, and
+ * `isUsableStorage Provider` (`db-backup/db-backup-storage.ts`) turns a disagreement with the
+ * live `storage.provider` into a loud 400. Shipping `'s3'` here meant every
+ * deployment that selected R2 failed EVERY backup on a value nobody chose —
+ * a default the operator never typed must not be able to redirect or block
+ * their backups. What did NOT change is the check: a value an operator DID
+ * type must still equal the active provider exactly, because a backup landing
+ * somewhere other than where the settings page says it lands is only ever
+ * discovered during a restore. The bound stays 64 — a provider id, not prose —
+ * and the comparison trims, so stored whitespace is still "unset".
+ *
+ * @stability stable
+ */
+export declare const systemDatabaseBackupSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    frequency: z.ZodEnum<DbBackupEnum<readonly ["daily", "weekly", "monthly", "cron"]>>;
+    dayOfWeek: z.ZodNumber;
+    dayOfMonth: z.ZodNumber;
+    timeOfDay: z.ZodString;
+    timezone: z.ZodString;
+    retentionCount: z.ZodNumber;
+    cron: z.ZodOptional<z.ZodString>;
+    retention: z.ZodOptional<z.ZodObject<{
+        count: z.ZodOptional<z.ZodNumber>;
+        maxAgeDays: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    storageProvider: z.ZodString;
+    runStaleMinutes: z.ZodNumber;
+    compressionLevel: z.ZodNumber;
+    restoreRollbackMode: z.ZodEnum<DbBackupEnum<["retain_database", "drop_database"]>>;
+    oldDatabaseRetentionHours: z.ZodNumber;
+    nodeOffloadEnabled: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * The stored `databaseBackup` value.
+ *
+ * @stability stable
+ */
+export type SystemDatabaseBackupValue = z.infer<typeof systemDatabaseBackupSchema>;
+/**
+ * The stored partial of `databaseBackup`: every field optional, every bound
+ * the stored schema's.
+ *
+ * @stability stable
+ */
+export declare const systemDatabaseBackupPatchSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    frequency: z.ZodOptional<z.ZodEnum<DbBackupEnum<readonly ["daily", "weekly", "monthly", "cron"]>>>;
+    dayOfWeek: z.ZodOptional<z.ZodNumber>;
+    dayOfMonth: z.ZodOptional<z.ZodNumber>;
+    timeOfDay: z.ZodOptional<z.ZodString>;
+    timezone: z.ZodOptional<z.ZodString>;
+    retentionCount: z.ZodOptional<z.ZodNumber>;
+    cron: z.ZodOptional<z.ZodString>;
+    retention: z.ZodOptional<z.ZodObject<{
+        count: z.ZodOptional<z.ZodNumber>;
+        maxAgeDays: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    storageProvider: z.ZodOptional<z.ZodString>;
+    runStaleMinutes: z.ZodOptional<z.ZodNumber>;
+    compressionLevel: z.ZodOptional<z.ZodNumber>;
+    restoreRollbackMode: z.ZodOptional<z.ZodEnum<DbBackupEnum<["retain_database", "drop_database"]>>>;
+    oldDatabaseRetentionHours: z.ZodOptional<z.ZodNumber>;
+    nodeOffloadEnabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * The `databaseBackup` branch of a `PUT /api/system-settings` body.
+ *
+ * @stability stable
+ */
+export declare const databaseBackupSettingsSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    frequency: z.ZodEnum<DbBackupEnum<readonly ["daily", "weekly", "monthly", "cron"]>>;
+    dayOfWeek: z.ZodNumber;
+    dayOfMonth: z.ZodNumber;
+    timeOfDay: z.ZodString;
+    timezone: z.ZodString;
+    retentionCount: z.ZodNumber;
+    cron: z.ZodOptional<z.ZodString>;
+    retention: z.ZodOptional<z.ZodObject<{
+        count: z.ZodOptional<z.ZodNumber>;
+        maxAgeDays: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    storageProvider: z.ZodString;
+    runStaleMinutes: z.ZodNumber;
+    compressionLevel: z.ZodNumber;
+    restoreRollbackMode: z.ZodEnum<DbBackupEnum<["retain_database", "drop_database"]>>;
+    oldDatabaseRetentionHours: z.ZodNumber;
+    nodeOffloadEnabled: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * The `databaseBackup` branch of a `PATCH /api/system-settings` body: field by field optional.
+ *
+ * @stability stable
+ */
+export declare const databaseBackupSettingsPatchSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    frequency: z.ZodOptional<z.ZodEnum<DbBackupEnum<readonly ["daily", "weekly", "monthly", "cron"]>>>;
+    dayOfWeek: z.ZodOptional<z.ZodNumber>;
+    dayOfMonth: z.ZodOptional<z.ZodNumber>;
+    timeOfDay: z.ZodOptional<z.ZodString>;
+    timezone: z.ZodOptional<z.ZodString>;
+    retentionCount: z.ZodOptional<z.ZodNumber>;
+    cron: z.ZodOptional<z.ZodString>;
+    retention: z.ZodOptional<z.ZodObject<{
+        count: z.ZodOptional<z.ZodNumber>;
+        maxAgeDays: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    storageProvider: z.ZodOptional<z.ZodString>;
+    runStaleMinutes: z.ZodOptional<z.ZodNumber>;
+    compressionLevel: z.ZodOptional<z.ZodNumber>;
+    restoreRollbackMode: z.ZodOptional<z.ZodEnum<DbBackupEnum<["retain_database", "drop_database"]>>>;
+    oldDatabaseRetentionHours: z.ZodOptional<z.ZodNumber>;
+    nodeOffloadEnabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * The `databaseBackup` branch of the `GET /api/system-settings` response.
+ *
+ * @stability stable
+ */
+export declare const databaseBackupResponseSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    frequency: z.ZodEnum<DbBackupEnum<readonly ["daily", "weekly", "monthly", "cron"]>>;
+    dayOfWeek: z.ZodNumber;
+    dayOfMonth: z.ZodNumber;
+    timeOfDay: z.ZodString;
+    timezone: z.ZodString;
+    retentionCount: z.ZodNumber;
+    cron: z.ZodOptional<z.ZodString>;
+    retention: z.ZodOptional<z.ZodObject<{
+        count: z.ZodOptional<z.ZodNumber>;
+        maxAgeDays: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    storageProvider: z.ZodString;
+    runStaleMinutes: z.ZodNumber;
+    compressionLevel: z.ZodNumber;
+    restoreRollbackMode: z.ZodEnum<DbBackupEnum<["retain_database", "drop_database"]>>;
+    oldDatabaseRetentionHours: z.ZodNumber;
+    nodeOffloadEnabled: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * The `databaseBackup` PATCH body's branch, parsed.
+ *
+ * @stability stable
+ */
+export type DatabaseBackupSettingsPatchInput = z.infer<typeof databaseBackupSettingsPatchSchema>;
+//# sourceMappingURL=settings-schemas.d.ts.map

package/dist/esm/db-backup/settings-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-schemas.d.ts","sourceRoot":"","sources":["../../../src/db-backup/settings-schemas.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB;;;iBAKhC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAYpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;iBAoCrC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAC7C,OAAO,0BAA0B,CAClC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;iBAwC1C,CAAC;AAGH;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;iBAyCvC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;iBAuC5C,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;iBA+BvC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC"}