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

package/dist/db-backup/testing/index.js

@@ -0,0 +1,102 @@
+"use strict";
+// `@marinoscar/platform-api/db-backup/testing`: the db-backup slice's test
+// seams (issue #740): the conformance suite (importing this entry registers it
+// with `runPlatformConformance`) and the engine's internals the reference
+// app's integration and real-database suites drive directly (the services,
+// the handlers, the cluster utilities and the deliberately UNBOUND seams).
+// Never import it from production code: binding a seam in production is the
+// danger `db-backup.module.ts`'s header describes. Documented in ../README.md.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withAdminConnection = exports.resolveAdminConnection = exports.renameDatabase = exports.quoteLiteral = exports.quoteIdentifier = exports.dropDatabase = exports.databaseExists = exports.createDatabase = exports.buildScratchDatabaseName = exports.UpdateDatabaseBackupConfigDto = exports.BackupRunListQueryDto = exports.StartRestoreRequestDto = exports.RollbackRestoreRequestDto = exports.startRestoreRequestSchema = exports.BACKUP_KEY_PREFIX = exports.BACKUP_ARCHIVE_FORMAT = exports.jobRolePattern = exports.generateRolePassword = exports.PgJobRoleBroker = exports.PG_JOB_ROLE_SEAM = exports.PG_JOB_ROLE_KIND = exports.NODE_JOB_SECRETS_RUNBOOK_PATH = exports.DatabaseRestoreRunHandler = exports.DatabaseBackupRunHandler = exports.defaultRestorePreflightSeam = exports.RESTORE_SCHEMA_OVERRIDE_FIELD = exports.RESTORE_PREFLIGHT_SEAM = exports.DatabaseRestorePreflightService = exports.defaultDatabaseRestoreSeam = exports.DatabaseRestoreService = exports.DATABASE_RESTORE_SEAM = exports.systemDatabaseBackupEngine = exports.systemBackupTimers = exports.DB_BACKUP_TIMERS = exports.DB_BACKUP_ENGINE = exports.ACTIVE_RUN_INDEX_NAME = exports.DatabaseBackupController = exports.BACKUP_DOWNLOAD_URL_EXPIRY_SECONDS = exports.DatabaseBackupAdminService = exports.decideBackupMirrors = exports.BackupMirrorsDoctorCheck = exports.describeRestoreGateConformance = exports.buildRestoreGateContext = exports.describeBackupTargetConformance = exports.dbBackupConformanceSuite = exports.checkSystemScopePermissions = exports.checkRlsPair = exports.checkJobTypes = exports.checkCarryOvers = exports.checkBackupKeyPrefix = void 0;
+exports.readServerVersionNumWithPgClient = exports.checkPgClientVersion = exports.MIN_PG_CLIENT_MAJOR = exports.spawnPgRestore = exports.readTocEntryCount = exports.PgProcessError = exports.spawnPgProcess = exports.spawnPgDump = exports.resolvePgConnection = exports.pgClientEnv = exports.buildPgDumpArgs = exports.PG_DUMP_COMMAND = exports.InvalidSqlLiteralError = void 0;
+// ---- the conformance suite ---------------------------------------------------------------
+var conformance_1 = require("./conformance");
+Object.defineProperty(exports, "checkBackupKeyPrefix", { enumerable: true, get: function () { return conformance_1.checkBackupKeyPrefix; } });
+Object.defineProperty(exports, "checkCarryOvers", { enumerable: true, get: function () { return conformance_1.checkCarryOvers; } });
+Object.defineProperty(exports, "checkJobTypes", { enumerable: true, get: function () { return conformance_1.checkJobTypes; } });
+Object.defineProperty(exports, "checkRlsPair", { enumerable: true, get: function () { return conformance_1.checkRlsPair; } });
+Object.defineProperty(exports, "checkSystemScopePermissions", { enumerable: true, get: function () { return conformance_1.checkSystemScopePermissions; } });
+Object.defineProperty(exports, "dbBackupConformanceSuite", { enumerable: true, get: function () { return conformance_1.dbBackupConformanceSuite; } });
+// ---- the extension-author kits (PP-14.12) -----------------------------------------------------
+var backup_target_conformance_1 = require("./backup-target-conformance");
+Object.defineProperty(exports, "describeBackupTargetConformance", { enumerable: true, get: function () { return backup_target_conformance_1.describeBackupTargetConformance; } });
+var restore_gate_conformance_1 = require("./restore-gate-conformance");
+Object.defineProperty(exports, "buildRestoreGateContext", { enumerable: true, get: function () { return restore_gate_conformance_1.buildRestoreGateContext; } });
+Object.defineProperty(exports, "describeRestoreGateConformance", { enumerable: true, get: function () { return restore_gate_conformance_1.describeRestoreGateConformance; } });
+// ---- the Doctor checks --------------------------------------------------------------------
+var backup_mirrors_doctor_check_1 = require("../doctor/backup-mirrors.doctor-check");
+Object.defineProperty(exports, "BackupMirrorsDoctorCheck", { enumerable: true, get: function () { return backup_mirrors_doctor_check_1.BackupMirrorsDoctorCheck; } });
+Object.defineProperty(exports, "decideBackupMirrors", { enumerable: true, get: function () { return backup_mirrors_doctor_check_1.decideBackupMirrors; } });
+// ---- services, handlers and the controller ------------------------------------------------
+var db_backup_admin_service_1 = require("../db-backup-admin.service");
+Object.defineProperty(exports, "DatabaseBackupAdminService", { enumerable: true, get: function () { return db_backup_admin_service_1.DatabaseBackupAdminService; } });
+Object.defineProperty(exports, "BACKUP_DOWNLOAD_URL_EXPIRY_SECONDS", { enumerable: true, get: function () { return db_backup_admin_service_1.BACKUP_DOWNLOAD_URL_EXPIRY_SECONDS; } });
+var db_backup_controller_1 = require("../db-backup.controller");
+Object.defineProperty(exports, "DatabaseBackupController", { enumerable: true, get: function () { return db_backup_controller_1.DatabaseBackupController; } });
+var db_backup_runner_service_1 = require("../db-backup-runner.service");
+Object.defineProperty(exports, "ACTIVE_RUN_INDEX_NAME", { enumerable: true, get: function () { return db_backup_runner_service_1.ACTIVE_RUN_INDEX_NAME; } });
+Object.defineProperty(exports, "DB_BACKUP_ENGINE", { enumerable: true, get: function () { return db_backup_runner_service_1.DB_BACKUP_ENGINE; } });
+Object.defineProperty(exports, "DB_BACKUP_TIMERS", { enumerable: true, get: function () { return db_backup_runner_service_1.DB_BACKUP_TIMERS; } });
+Object.defineProperty(exports, "systemBackupTimers", { enumerable: true, get: function () { return db_backup_runner_service_1.systemBackupTimers; } });
+Object.defineProperty(exports, "systemDatabaseBackupEngine", { enumerable: true, get: function () { return db_backup_runner_service_1.systemDatabaseBackupEngine; } });
+var database_restore_service_1 = require("../database-restore.service");
+Object.defineProperty(exports, "DATABASE_RESTORE_SEAM", { enumerable: true, get: function () { return database_restore_service_1.DATABASE_RESTORE_SEAM; } });
+Object.defineProperty(exports, "DatabaseRestoreService", { enumerable: true, get: function () { return database_restore_service_1.DatabaseRestoreService; } });
+Object.defineProperty(exports, "defaultDatabaseRestoreSeam", { enumerable: true, get: function () { return database_restore_service_1.defaultDatabaseRestoreSeam; } });
+var restore_preflight_service_1 = require("../restore-preflight.service");
+Object.defineProperty(exports, "DatabaseRestorePreflightService", { enumerable: true, get: function () { return restore_preflight_service_1.DatabaseRestorePreflightService; } });
+Object.defineProperty(exports, "RESTORE_PREFLIGHT_SEAM", { enumerable: true, get: function () { return restore_preflight_service_1.RESTORE_PREFLIGHT_SEAM; } });
+Object.defineProperty(exports, "RESTORE_SCHEMA_OVERRIDE_FIELD", { enumerable: true, get: function () { return restore_preflight_service_1.RESTORE_SCHEMA_OVERRIDE_FIELD; } });
+Object.defineProperty(exports, "defaultRestorePreflightSeam", { enumerable: true, get: function () { return restore_preflight_service_1.defaultRestorePreflightSeam; } });
+var db_backup_run_handler_1 = require("../handlers/db-backup-run.handler");
+Object.defineProperty(exports, "DatabaseBackupRunHandler", { enumerable: true, get: function () { return db_backup_run_handler_1.DatabaseBackupRunHandler; } });
+var db_restore_run_handler_1 = require("../handlers/db-restore-run.handler");
+Object.defineProperty(exports, "DatabaseRestoreRunHandler", { enumerable: true, get: function () { return db_restore_run_handler_1.DatabaseRestoreRunHandler; } });
+var pg_job_role_broker_1 = require("../pg-job-role.broker");
+Object.defineProperty(exports, "NODE_JOB_SECRETS_RUNBOOK_PATH", { enumerable: true, get: function () { return pg_job_role_broker_1.NODE_JOB_SECRETS_RUNBOOK_PATH; } });
+Object.defineProperty(exports, "PG_JOB_ROLE_KIND", { enumerable: true, get: function () { return pg_job_role_broker_1.PG_JOB_ROLE_KIND; } });
+Object.defineProperty(exports, "PG_JOB_ROLE_SEAM", { enumerable: true, get: function () { return pg_job_role_broker_1.PG_JOB_ROLE_SEAM; } });
+Object.defineProperty(exports, "PgJobRoleBroker", { enumerable: true, get: function () { return pg_job_role_broker_1.PgJobRoleBroker; } });
+Object.defineProperty(exports, "generateRolePassword", { enumerable: true, get: function () { return pg_job_role_broker_1.generateRolePassword; } });
+Object.defineProperty(exports, "jobRolePattern", { enumerable: true, get: function () { return pg_job_role_broker_1.jobRolePattern; } });
+var db_backup_storage_1 = require("../db-backup-storage");
+Object.defineProperty(exports, "BACKUP_ARCHIVE_FORMAT", { enumerable: true, get: function () { return db_backup_storage_1.BACKUP_ARCHIVE_FORMAT; } });
+Object.defineProperty(exports, "BACKUP_KEY_PREFIX", { enumerable: true, get: function () { return db_backup_storage_1.BACKUP_KEY_PREFIX; } });
+var db_backup_restore_dto_1 = require("../dto/db-backup-restore.dto");
+Object.defineProperty(exports, "startRestoreRequestSchema", { enumerable: true, get: function () { return db_backup_restore_dto_1.startRestoreRequestSchema; } });
+Object.defineProperty(exports, "RollbackRestoreRequestDto", { enumerable: true, get: function () { return db_backup_restore_dto_1.RollbackRestoreRequestDto; } });
+Object.defineProperty(exports, "StartRestoreRequestDto", { enumerable: true, get: function () { return db_backup_restore_dto_1.StartRestoreRequestDto; } });
+var db_backup_list_query_dto_1 = require("../dto/db-backup-list-query.dto");
+Object.defineProperty(exports, "BackupRunListQueryDto", { enumerable: true, get: function () { return db_backup_list_query_dto_1.BackupRunListQueryDto; } });
+var db_backup_config_dto_1 = require("../dto/db-backup-config.dto");
+Object.defineProperty(exports, "UpdateDatabaseBackupConfigDto", { enumerable: true, get: function () { return db_backup_config_dto_1.UpdateDatabaseBackupConfigDto; } });
+// ---- the cluster utilities (outside the Prisma pool, on the maintenance database) ----------
+var admin_connection_util_1 = require("../admin-connection.util");
+Object.defineProperty(exports, "buildScratchDatabaseName", { enumerable: true, get: function () { return admin_connection_util_1.buildScratchDatabaseName; } });
+Object.defineProperty(exports, "createDatabase", { enumerable: true, get: function () { return admin_connection_util_1.createDatabase; } });
+Object.defineProperty(exports, "databaseExists", { enumerable: true, get: function () { return admin_connection_util_1.databaseExists; } });
+Object.defineProperty(exports, "dropDatabase", { enumerable: true, get: function () { return admin_connection_util_1.dropDatabase; } });
+Object.defineProperty(exports, "quoteIdentifier", { enumerable: true, get: function () { return admin_connection_util_1.quoteIdentifier; } });
+Object.defineProperty(exports, "quoteLiteral", { enumerable: true, get: function () { return admin_connection_util_1.quoteLiteral; } });
+Object.defineProperty(exports, "renameDatabase", { enumerable: true, get: function () { return admin_connection_util_1.renameDatabase; } });
+Object.defineProperty(exports, "resolveAdminConnection", { enumerable: true, get: function () { return admin_connection_util_1.resolveAdminConnection; } });
+Object.defineProperty(exports, "withAdminConnection", { enumerable: true, get: function () { return admin_connection_util_1.withAdminConnection; } });
+var admin_connection_util_2 = require("../admin-connection.util");
+Object.defineProperty(exports, "InvalidSqlLiteralError", { enumerable: true, get: function () { return admin_connection_util_2.InvalidSqlLiteralError; } });
+var pg_dump_util_1 = require("../pg-dump.util");
+Object.defineProperty(exports, "PG_DUMP_COMMAND", { enumerable: true, get: function () { return pg_dump_util_1.PG_DUMP_COMMAND; } });
+Object.defineProperty(exports, "buildPgDumpArgs", { enumerable: true, get: function () { return pg_dump_util_1.buildPgDumpArgs; } });
+Object.defineProperty(exports, "pgClientEnv", { enumerable: true, get: function () { return pg_dump_util_1.pgClientEnv; } });
+Object.defineProperty(exports, "resolvePgConnection", { enumerable: true, get: function () { return pg_dump_util_1.resolvePgConnection; } });
+Object.defineProperty(exports, "spawnPgDump", { enumerable: true, get: function () { return pg_dump_util_1.spawnPgDump; } });
+Object.defineProperty(exports, "spawnPgProcess", { enumerable: true, get: function () { return pg_dump_util_1.spawnPgProcess; } });
+var pg_dump_util_2 = require("../pg-dump.util");
+Object.defineProperty(exports, "PgProcessError", { enumerable: true, get: function () { return pg_dump_util_2.PgProcessError; } });
+var pg_restore_util_1 = require("../pg-restore.util");
+Object.defineProperty(exports, "readTocEntryCount", { enumerable: true, get: function () { return pg_restore_util_1.readTocEntryCount; } });
+Object.defineProperty(exports, "spawnPgRestore", { enumerable: true, get: function () { return pg_restore_util_1.spawnPgRestore; } });
+var pg_version_util_1 = require("../pg-version.util");
+Object.defineProperty(exports, "MIN_PG_CLIENT_MAJOR", { enumerable: true, get: function () { return pg_version_util_1.MIN_PG_CLIENT_MAJOR; } });
+Object.defineProperty(exports, "checkPgClientVersion", { enumerable: true, get: function () { return pg_version_util_1.checkPgClientVersion; } });
+Object.defineProperty(exports, "readServerVersionNumWithPgClient", { enumerable: true, get: function () { return pg_version_util_1.readServerVersionNumWithPgClient; } });
+//# sourceMappingURL=index.js.map

package/dist/db-backup/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/db-backup/testing/index.ts"],"names":[],"mappings":";AAAA,2EAA2E;AAC3E,+EAA+E;AAC/E,0EAA0E;AAC1E,2EAA2E;AAC3E,2EAA2E;AAC3E,4EAA4E;AAC5E,+EAA+E;;;;AAE/E,6FAA6F;AAC7F,6CAOuB;AANrB,mHAAA,oBAAoB,OAAA;AACpB,8GAAA,eAAe,OAAA;AACf,4GAAA,aAAa,OAAA;AACb,2GAAA,YAAY,OAAA;AACZ,0HAAA,2BAA2B,OAAA;AAC3B,uHAAA,wBAAwB,OAAA;AAK1B,kGAAkG;AAClG,yEAA8E;AAArE,4IAAA,+BAA+B,OAAA;AAOxC,uEAAqG;AAA5F,mIAAA,uBAAuB,OAAA;AAAE,0IAAA,8BAA8B,OAAA;AAShE,8FAA8F;AAC9F,qFAAsG;AAA7F,uIAAA,wBAAwB,OAAA;AAAE,kIAAA,mBAAmB,OAAA;AAItD,8FAA8F;AAC9F,sEAA4G;AAAnG,qIAAA,0BAA0B,OAAA;AAAE,6IAAA,kCAAkC,OAAA;AAGvE,gEAAmE;AAA1D,gIAAA,wBAAwB,OAAA;AACjC,wEAMqC;AALnC,iIAAA,qBAAqB,OAAA;AACrB,4HAAA,gBAAgB,OAAA;AAChB,4HAAA,gBAAgB,OAAA;AAChB,8HAAA,kBAAkB,OAAA;AAClB,sIAAA,0BAA0B,OAAA;AAI5B,wEAIqC;AAHnC,iIAAA,qBAAqB,OAAA;AACrB,kIAAA,sBAAsB,OAAA;AACtB,sIAAA,0BAA0B,OAAA;AAI5B,0EAKsC;AAJpC,4IAAA,+BAA+B,OAAA;AAC/B,mIAAA,sBAAsB,OAAA;AACtB,0IAAA,6BAA6B,OAAA;AAC7B,wIAAA,2BAA2B,OAAA;AAgB7B,2EAA6E;AAApE,iIAAA,wBAAwB,OAAA;AACjC,6EAA+E;AAAtE,mIAAA,yBAAyB,OAAA;AAClC,4DAO+B;AAN7B,mIAAA,6BAA6B,OAAA;AAC7B,sHAAA,gBAAgB,OAAA;AAChB,sHAAA,gBAAgB,OAAA;AAChB,qHAAA,eAAe,OAAA;AACf,0HAAA,oBAAoB,OAAA;AACpB,oHAAA,cAAc,OAAA;AAIhB,0DAAgF;AAAvE,0HAAA,qBAAqB,OAAA;AAAE,sHAAA,iBAAiB,OAAA;AACjD,sEAA4H;AAAnH,kIAAA,yBAAyB,OAAA;AAAE,kIAAA,yBAAyB,OAAA;AAAE,+HAAA,sBAAsB,OAAA;AACrF,4EAAwE;AAA/D,iIAAA,qBAAqB,OAAA;AAC9B,oEAA4E;AAAnE,qIAAA,6BAA6B,OAAA;AAEtC,+FAA+F;AAC/F,kEAUkC;AAThC,iIAAA,wBAAwB,OAAA;AACxB,uHAAA,cAAc,OAAA;AACd,uHAAA,cAAc,OAAA;AACd,qHAAA,YAAY,OAAA;AACZ,wHAAA,eAAe,OAAA;AACf,qHAAA,YAAY,OAAA;AACZ,uHAAA,cAAc,OAAA;AACd,+HAAA,sBAAsB,OAAA;AACtB,4HAAA,mBAAmB,OAAA;AAErB,kEAAkE;AAAzD,+HAAA,sBAAsB,OAAA;AAG/B,gDAOyB;AANvB,+GAAA,eAAe,OAAA;AACf,+GAAA,eAAe,OAAA;AACf,2GAAA,WAAW,OAAA;AACX,mHAAA,mBAAmB,OAAA;AACnB,2GAAA,WAAW,OAAA;AACX,8GAAA,cAAc,OAAA;AAEhB,gDAAiD;AAAxC,8GAAA,cAAc,OAAA;AAGvB,sDAAuE;AAA9D,oHAAA,iBAAiB,OAAA;AAAE,iHAAA,cAAc,OAAA;AAG1C,sDAAiH;AAAxG,sHAAA,mBAAmB,OAAA;AAAE,uHAAA,oBAAoB,OAAA;AAAE,mIAAA,gCAAgC,OAAA"}

package/dist/db-backup/testing/restore-gate-conformance.d.ts

@@ -0,0 +1,82 @@
+import { type RestoreGateContext, type RestoreGateDefinition, type RestoreGateOutcome } from '../restore-gate.registry';
+/**
+ * The test runner's own globals, passed in.
+ *
+ * @stability experimental
+ */
+export interface RestoreGateConformanceHarness {
+    /** The runner's `describe`. */
+    describe: (name: string, fn: () => void) => unknown;
+    /** The runner's `it`. Every case body the kit passes is an asynchronous function. */
+    it: (name: string, fn: () => Promise<void>) => unknown;
+    /** The runner's `expect`. */
+    expect: (actual: unknown) => any;
+}
+/**
+ * One case: the context to ask the gate under, and what it should answer.
+ *
+ * @stability experimental
+ */
+export interface RestoreGateScenario {
+    /** Names the case. */
+    name: string;
+    /** System settings namespaces the gate may read, by namespace key (`ctx.settings.get`). Default none. */
+    settings?: Record<string, Record<string, unknown>>;
+    /** Fields of the context to override (`run`, `policy`, `facts`, ...). */
+    context?: Partial<Omit<RestoreGateContext, 'settings'>>;
+    /** The status the gate must answer. Omit to assert only that it answers. */
+    expectStatus?: RestoreGateOutcome['status'];
+}
+/**
+ * A counter of one side-effecting dependency of a gate.
+ *
+ * @stability experimental
+ */
+export interface RestoreGateWatch {
+    /** Names the dependency in a failure message. */
+    name: string;
+    /** How many times the dependency was used so far. */
+    calls(): number;
+}
+/**
+ * Options of {@link describeRestoreGateConformance}.
+ *
+ * @stability experimental
+ */
+export interface RestoreGateConformanceOptions extends RestoreGateConformanceHarness {
+    /** The cases. At least one. */
+    scenarios: readonly RestoreGateScenario[];
+    /**
+     * Counters of the gate's own side-effecting dependencies (`calls()` reads how
+     * many times each was used). Each must be zero after every case.
+     */
+    watch?: ReadonlyArray<RestoreGateWatch>;
+}
+/**
+ * A complete {@link RestoreGateContext} for a test: a completed archive, a
+ * healthy cluster, the stock `databaseBackup` policy and a settings reader over
+ * `settings` (an unknown namespace reads as `undefined`, like an unregistered one).
+ *
+ * @param overrides - fields to replace.
+ * @param settings - system settings namespaces by key.
+ * @returns the context (not frozen; the kit freezes its own).
+ *
+ * @stability experimental
+ */
+export declare function buildRestoreGateContext(overrides?: Partial<Omit<RestoreGateContext, 'settings'>>, settings?: Record<string, Record<string, unknown>>): RestoreGateContext;
+/**
+ * Registers the restore gate conformance suite.
+ *
+ * @param gate - the gate definition (the object passed to `registerRestoreGate`).
+ * @param options - the runner and the cases.
+ *
+ * @example
+ * ```ts
+ * describeRestoreGateConformance(cdnQuiescedGate, { describe, it, expect, scenarios: [{ name: 'quiesced', settings: { cdn: { quiesced: true } }, expectStatus: 'pass' }] });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare function describeRestoreGateConformance(gate: RestoreGateDefinition, options: RestoreGateConformanceOptions): void;
+//# sourceMappingURL=restore-gate-conformance.d.ts.map

package/dist/db-backup/testing/restore-gate-conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore-gate-conformance.d.ts","sourceRoot":"","sources":["../../../src/db-backup/testing/restore-gate-conformance.ts"],"names":[],"mappings":"AA8CA,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAE1B,KAAK,kBAAkB,EAExB,MAAM,0BAA0B,CAAC;AAElC;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,+BAA+B;IAC/B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,IAAI,KAAK,OAAO,CAAC;IACpD,qFAAqF;IACrF,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC;IACvD,6BAA6B;IAC7B,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,GAAG,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC,CAAC,CAAC;IACxD,4EAA4E;IAC5E,YAAY,CAAC,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;CAC7C;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,KAAK,IAAI,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,6BAA8B,SAAQ,6BAA6B;IAClF,+BAA+B;IAC/B,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC1C;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;CACzC;AAuCD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,GAAE,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC,CAAM,EAC7D,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM,GACrD,kBAAkB,CAmBpB;AAoCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,qBAAqB,EAC3B,OAAO,EAAE,6BAA6B,GACrC,IAAI,CA+DN"}

package/dist/db-backup/testing/restore-gate-conformance.js

@@ -0,0 +1,217 @@
+"use strict";
+// =============================================================================
+// Restore gate conformance kit (PP-14.12)
+// =============================================================================
+//
+// ONE suite every restore pre-flight gate runs, so "is a well-behaved gate"
+// means the same thing for the platform's eight and for an app's own:
+//
+//   import { describeRestoreGateConformance } from '@marinoscar/platform-api/db-backup/testing';
+//
+//   describeRestoreGateConformance(cdnQuiescedGate, {
+//     describe, it, expect,
+//     scenarios: [
+//       { name: 'quiesced', settings: { cdn: { quiesced: true } }, expectStatus: 'pass' },
+//       { name: 'not quiesced', settings: { cdn: { quiesced: false } }, expectStatus: 'fail' },
+//       { name: 'not configured', settings: {}, expectStatus: 'pass' },
+//     ],
+//   });
+//
+// It is runner-agnostic: it receives `describe`, `it` and `expect`.
+//
+// WHAT IT CHECKS
+//
+//   - the definition: a valid id, a label, a known kind, a `check` function;
+//   - it ANSWERS: every scenario returns `{ status: 'pass' | 'warn' | 'fail',
+//     message }` with a non-empty message, within `RESTORE_GATE_TIMEOUT_MS`, and
+//     the status the scenario expects;
+//   - it is READ-ONLY, which is the rule a restore pre-flight cannot bend (it
+//     "creates, drops and renames nothing"): the gate runs against a context
+//     whose every member is frozen behind a recording proxy, and any attempt to
+//     assign, define or delete a property on it fails the case; the only
+//     handle it may call is `settings.get`. The author can also pass `watch`
+//     counters for the side-effecting dependencies of their own (an HTTP
+//     client's POST, a filesystem write): each must stay at zero;
+//   - it is REPEATABLE: asking twice with the same context answers the same, so
+//     the gate is a function of its inputs, not a counter or a cache that
+//     changes what the second pre-flight says;
+//   - it FAILS CLOSED through the registry: `evaluateRestoreGate` turns the
+//     gate's answer into a pre-flight row with the gate's label and id.
+//
+// `buildRestoreGateContext` makes a complete context for a case (healthy
+// facts, an empty settings reader) that a scenario overrides.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRestoreGateContext = buildRestoreGateContext;
+exports.describeRestoreGateConformance = describeRestoreGateConformance;
+const restore_gate_registry_1 = require("../restore-gate.registry");
+const KINDS = ['capability', 'disk', 'replicas', 'overridable', 'app'];
+/** A healthy cluster: every built-in gate would pass on it. */
+const HEALTHY_FACTS = Object.freeze({
+    version: Object.freeze({ status: 'ok', clientMajor: 17, serverMajor: 17, message: 'The client and server majors match (17).' }),
+    cluster: Object.freeze({
+        reachable: true,
+        error: null,
+        canCreateDatabase: true,
+        missingExtensions: Object.freeze([]),
+        checkedExtensions: 0,
+        databaseSizeBytes: 1000000n,
+        dataDirectory: '/var/lib/postgresql/data',
+        distinctClientAddresses: 1,
+        rlsBypass: Object.freeze({ superuser: false, bypassRls: false, optionApplied: true }),
+    }),
+    connection: Object.freeze({ host: 'db', port: '5432', user: 'app', database: 'postgres', liveDatabase: 'app' }),
+    freeDiskBytes: 1000000000n,
+    migrationComparison: 'match',
+});
+const POLICY = Object.freeze({
+    enabled: true,
+    frequency: 'daily',
+    dayOfWeek: 0,
+    dayOfMonth: 1,
+    timeOfDay: '02:00',
+    timezone: 'UTC',
+    retentionCount: 7,
+    storageProvider: '',
+    runStaleMinutes: 120,
+    compressionLevel: 6,
+    restoreRollbackMode: 'retain_database',
+    oldDatabaseRetentionHours: 48,
+    nodeOffloadEnabled: false,
+});
+/**
+ * A complete {@link RestoreGateContext} for a test: a completed archive, a
+ * healthy cluster, the stock `databaseBackup` policy and a settings reader over
+ * `settings` (an unknown namespace reads as `undefined`, like an unregistered one).
+ *
+ * @param overrides - fields to replace.
+ * @param settings - system settings namespaces by key.
+ * @returns the context (not frozen; the kit freezes its own).
+ *
+ * @stability experimental
+ */
+function buildRestoreGateContext(overrides = {}, settings = {}) {
+    return {
+        run: {
+            id: '11111111-1111-4111-8111-111111111111',
+            storageKey: 'database-backups/app/2026/10/app-20261001T020000Z-1111.dump',
+            storageProvider: 's3',
+            sizeBytes: '1000000',
+            migrationName: '0033_add_android_app',
+            createdAt: new Date('2026-10-01T02:00:00.000Z'),
+        },
+        policy: POLICY,
+        now: new Date('2026-10-02T12:00:00.000Z'),
+        targetDatabase: 'app',
+        liveMigration: '0033_add_android_app',
+        overrideSchemaMismatch: false,
+        settings: { get: async (namespace) => settings[namespace] },
+        facts: HEALTHY_FACTS,
+        ...overrides,
+    };
+}
+/**
+ * Wraps a context in a recording proxy: reading is free, any write is recorded.
+ * Nested objects are wrapped on the way out, so `ctx.facts.cluster.x = 1` is
+ * caught as well.
+ */
+function guarded(value, violations, path) {
+    // A shallow COPY is the proxy target: a frozen object's read-only properties
+    // would otherwise force the proxy to return the original values unwrapped.
+    const copy = (Array.isArray(value) ? [...value] : { ...value });
+    return new Proxy(copy, {
+        get(target, property, receiver) {
+            const inner = Reflect.get(target, property, receiver);
+            if (typeof property === 'symbol')
+                return inner;
+            if (inner !== null && typeof inner === 'object' && !(inner instanceof Date)) {
+                return guarded(inner, violations, `${path}.${property}`);
+            }
+            return inner;
+        },
+        set(_target, property) {
+            violations.push(`assigned ${path}.${String(property)}`);
+            return true;
+        },
+        defineProperty(_target, property) {
+            violations.push(`defined ${path}.${String(property)}`);
+            return true;
+        },
+        deleteProperty(_target, property) {
+            violations.push(`deleted ${path}.${String(property)}`);
+            return true;
+        },
+    });
+}
+/**
+ * Registers the restore gate conformance suite.
+ *
+ * @param gate - the gate definition (the object passed to `registerRestoreGate`).
+ * @param options - the runner and the cases.
+ *
+ * @example
+ * ```ts
+ * describeRestoreGateConformance(cdnQuiescedGate, { describe, it, expect, scenarios: [{ name: 'quiesced', settings: { cdn: { quiesced: true } }, expectStatus: 'pass' }] });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+function describeRestoreGateConformance(gate, options) {
+    const { describe, it, expect } = options;
+    describe(`restore gate conformance: ${gate.id}`, () => {
+        it('[definition] declares a valid id, label, kind and check', async () => {
+            expect(gate.id).toMatch(/^[a-z][a-z0-9_-]{1,63}$/);
+            expect(typeof gate.label).toBe('string');
+            expect(gate.label.trim().length).toBeGreaterThan(0);
+            if (gate.kind !== undefined)
+                expect(KINDS).toContain(gate.kind);
+            expect(typeof gate.check).toBe('function');
+            expect(options.scenarios.length).toBeGreaterThan(0);
+        });
+        for (const scenario of options.scenarios) {
+            const contextFor = (violations) => {
+                const base = buildRestoreGateContext(scenario.context ?? {}, scenario.settings ?? {});
+                return guarded(base, violations, 'ctx');
+            };
+            it(`[answers] ${scenario.name}: answers { status, message } within the time bound`, async () => {
+                const violations = [];
+                const started = Date.now();
+                const outcome = await gate.check(contextFor(violations));
+                expect(Date.now() - started).toBeLessThan(restore_gate_registry_1.RESTORE_GATE_TIMEOUT_MS);
+                expect(['pass', 'warn', 'fail']).toContain(outcome.status);
+                expect(typeof outcome.message).toBe('string');
+                expect(outcome.message.trim().length).toBeGreaterThan(0);
+                if (outcome.action !== undefined && outcome.action !== null)
+                    expect(typeof outcome.action).toBe('string');
+                if (scenario.expectStatus !== undefined)
+                    expect(outcome.status).toBe(scenario.expectStatus);
+            });
+            it(`[read-only] ${scenario.name}: writes nothing to its context and triggers no watched side effect`, async () => {
+                const violations = [];
+                await gate.check(contextFor(violations));
+                expect(violations).toEqual([]);
+                for (const watched of options.watch ?? []) {
+                    expect(`${watched.name}: ${watched.calls()} call(s)`).toBe(`${watched.name}: 0 call(s)`);
+                }
+            });
+            it(`[repeatable] ${scenario.name}: the same context answers the same twice`, async () => {
+                const first = await gate.check(contextFor([]));
+                const second = await gate.check(contextFor([]));
+                expect(second.status).toBe(first.status);
+                expect(second.message).toBe(first.message);
+            });
+            it(`[registry] ${scenario.name}: evaluates to a pre-flight row carrying the gate's id and label`, async () => {
+                const row = await (0, restore_gate_registry_1.evaluateRestoreGate)(gate, buildRestoreGateContext(scenario.context ?? {}, scenario.settings ?? {}));
+                expect(row.id).toBe(gate.id);
+                expect(row.title).toBe(gate.label);
+                expect(['pass', 'warning', 'block']).toContain(row.verdict);
+                if (scenario.expectStatus !== undefined) {
+                    const verdict = { pass: 'pass', warn: 'warning', fail: 'block' }[scenario.expectStatus];
+                    expect(row.verdict).toBe(verdict);
+                }
+            });
+        }
+    });
+}
+//# sourceMappingURL=restore-gate-conformance.js.map

package/dist/db-backup/testing/restore-gate-conformance.js.map

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

package/dist/doctor/doctor-check.interface.d.ts

@@ -0,0 +1,100 @@
+import type { DoctorStatus } from '@marinoscar/platform-contract/doctor';
+export { DOCTOR_STATUSES, DOCTOR_STATUS_RANK } from '@marinoscar/platform-contract/doctor';
+export type { DoctorStatus } from '@marinoscar/platform-contract/doctor';
+/**
+ * The categories the platform ships, in display order. The default of
+ * `DoctorModuleOptions.categoryOrder`; an app adds its own simply by using a
+ * new string (or reorders them with that option), never by editing this list.
+ *
+ * @stability stable
+ */
+export declare const PLATFORM_DOCTOR_CATEGORIES: readonly ["core", "auth", "maintenance", "storage", "email", "push", "ai", "jobs", "nodes", "backup", "telemetry", "network"];
+/**
+ * The shipped categories under their pre-package name.
+ *
+ * @deprecated Use {@link PLATFORM_DOCTOR_CATEGORIES}; same values, same order.
+ * @stability stable
+ */
+export declare const DOCTOR_CATEGORIES: readonly ["core", "auth", "maintenance", "storage", "email", "push", "ai", "jobs", "nodes", "backup", "telemetry", "network"];
+/**
+ * One of the shipped categories.
+ *
+ * @stability stable
+ */
+export type CoreDoctorCategory = (typeof PLATFORM_DOCTOR_CATEGORIES)[number];
+/**
+ * A check's category. The shipped ones autocomplete; an app adds its own simply
+ * by using a new string (it sorts after the configured ones, in registration
+ * order) — no edit to this package needed.
+ *
+ * @stability stable
+ */
+export type DoctorCategory = CoreDoctorCategory | (string & {});
+/**
+ * A scalar fact a check wants to show beside its detail. Never secret material.
+ *
+ * @stability stable
+ */
+export type DoctorDataValue = string | number | boolean | null;
+/**
+ * What one run of a check found.
+ *
+ * @stability stable
+ */
+export interface DoctorCheckOutcome {
+    /** The verdict. */
+    status: DoctorStatus;
+    /** One line: what was found. "Connected in 12 ms", "No provider is enabled". */
+    detail: string;
+    /** Expected on warn/fail: a settings page, a command or a variable to set. */
+    remedy?: string;
+    /** The underlying error message, when a probe failed. Never secret material. */
+    error?: string;
+    /** Small scalar facts (counts, versions, latencies). Never secret material. */
+    data?: Record<string, DoctorDataValue>;
+}
+/**
+ * One read-only check of the running deployment, contributed by the app's
+ * feature module that owns the capability: an `@Injectable()` that injects
+ * `DoctorCheckRegistry` and calls `register(this)` in its `onModuleInit`.
+ *
+ * The five rules: it never throws; it gives a `remedy` on `warn`/`fail`; it is
+ * READ-ONLY (no write, no audit event, no job, no model call, no "test" service);
+ * its results never carry secret material; `skip` means "not evaluated".
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * export class DbConnectionDoctorCheck implements DoctorCheck, OnModuleInit {
+ *   readonly id = 'core.database';
+ *   readonly category = 'core';
+ *   readonly label = 'Database connection';
+ *   constructor(private readonly registry: DoctorCheckRegistry, private readonly prisma: PrismaService) {}
+ *   onModuleInit() { this.registry.register(this); }
+ *   async run(): Promise<DoctorCheckOutcome> { ... }
+ * }
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability stable
+ */
+export interface DoctorCheck {
+    /** Stable, dotted, unique across the application: `storage.bucket`. */
+    readonly id: string;
+    /** Where the report groups it. */
+    readonly category: DoctorCategory;
+    /** Short human label: "Object storage bucket". */
+    readonly label: string;
+    /** The web route that fixes this, e.g. `/admin/settings/storage`. */
+    readonly settingsPath?: string;
+    /** Per-check ceiling; the module's `defaultTimeoutMs` (5000 ms) otherwise. */
+    readonly timeoutMs?: number;
+    /**
+     * Ids of checks that must not `fail` or `skip` for this one to run. When one
+     * does, this check is reported as `skip` and `run()` is never called.
+     */
+    readonly dependsOn?: readonly string[];
+    /** Read-only. See rules 1, 3 and 4 in this file's header. */
+    run(): Promise<DoctorCheckOutcome>;
+}
+//# sourceMappingURL=doctor-check.interface.d.ts.map

package/dist/doctor/doctor-check.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-check.interface.d.ts","sourceRoot":"","sources":["../../src/doctor/doctor-check.interface.ts"],"names":[],"mappings":"AAgEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEzE,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC3F,YAAY,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,+HAa7B,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,+HAA6B,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,kBAAkB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEhE;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAE/D;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,mBAAmB;IACnB,MAAM,EAAE,YAAY,CAAC;IACrB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,WAAW;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,6DAA6D;IAC7D,GAAG,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACpC"}

package/dist/doctor/doctor-check.interface.js

@@ -0,0 +1,95 @@
+"use strict";
+// =============================================================================
+// The admin doctor check contract (issue #634; packaged by #696)
+// =============================================================================
+//
+// `GET /api/admin/doctor` answers one question for an administrator: "is every
+// capability of this deployment configured, reachable and healthy?" It does so
+// by running a set of small, independent checks — one per fact worth knowing —
+// that each capability's own module contributes.
+//
+// The contract deliberately mirrors the CLI's pre-install doctor
+// (`apps/cli/src/deploy/checks/types.ts`): the same four statuses, the same
+// one-line `detail`, the same `remedy`. An operator who has read one report
+// can read the other. The API doctor answers "is the RUNNING deployment
+// healthy?", where the CLI doctor answers "is this SERVER ready to install?".
+//
+// FIVE RULES THAT MAKE THIS WORTH HAVING:
+//
+//   1. A CHECK NEVER THROWS. A crashed probe is a `fail` carrying the error's
+//      message. `DoctorService` guards every call as well (a throw becomes a
+//      `fail`, a hang becomes a `fail` after `timeoutMs`), but a check that
+//      relies on that guard reports a worse `detail` than one that catches
+//      its own failure and says what it was doing.
+//
+//   2. `remedy` IS EXPECTED ON `warn` AND `fail`, and should name a settings
+//      page, a command or an environment variable — "fix storage" is not a
+//      remedy. The service fills a generic one ("Open <settingsPath> to
+//      review.") when a check omits it, so the report never shows a problem
+//      with no next step; each check's own spec asserts it supplies a real one.
+//
+//   3. ⚠ CHECKS ARE READ-ONLY. A doctor run must be safe against a production
+//      deployment at any time, by anyone holding `system_settings:read`, as
+//      often as they like. Concretely, a check:
+//        - NEVER calls the side-effecting "test" services:
+//          `StorageConnectionTestService`, `AiProviderTestService`,
+//          `EmailTestSendService`, `PushTestService`,
+//          `TelemetryConnectionTestService`. Those write probe objects, spend
+//          model tokens, send mail and pushes, or audit the attempt;
+//        - never writes an object, a row or an audit event;
+//        - never enqueues a job or calls a model.
+//      Reading (a `SELECT`, a `HEAD`, a settings read) is the whole budget.
+//
+//   4. RESULTS NEVER CONTAIN SECRET MATERIAL. Not in `detail`, not in
+//      `error`, not in `data`. A check that reads a secret to validate it
+//      (the VAPID private key, say) reports only the verdict. Lengths and
+//      counts are fine; values, hints and fingerprints are not.
+//
+//   5. `skip` MEANS "NOT EVALUATED", for one of two reasons:
+//        - a check it `dependsOn` did not pass (the service decides this; the
+//          check does not run at all), or
+//        - the capability is INTENTIONALLY OFF — AI switched off, telemetry
+//          collection off. That is an operator's choice, not a problem, so it
+//          is neither `warn` (nothing to fix) nor `pass` (nothing was proven).
+//          A `skip` needs no remedy.
+//
+// Registration: see `doctor-check.registry.ts`. Each check is an
+// `@Injectable()` in its OWNING feature module of the app, under
+// `<module>/doctor/`, that calls `registry.register(this)` from its own
+// `onModuleInit`. Checks never live in this package: they are registry
+// entries the app contributes (the Extension Contract, rung 2).
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOCTOR_CATEGORIES = exports.PLATFORM_DOCTOR_CATEGORIES = exports.DOCTOR_STATUS_RANK = exports.DOCTOR_STATUSES = void 0;
+var doctor_1 = require("@marinoscar/platform-contract/doctor");
+Object.defineProperty(exports, "DOCTOR_STATUSES", { enumerable: true, get: function () { return doctor_1.DOCTOR_STATUSES; } });
+Object.defineProperty(exports, "DOCTOR_STATUS_RANK", { enumerable: true, get: function () { return doctor_1.DOCTOR_STATUS_RANK; } });
+/**
+ * The categories the platform ships, in display order. The default of
+ * `DoctorModuleOptions.categoryOrder`; an app adds its own simply by using a
+ * new string (or reorders them with that option), never by editing this list.
+ *
+ * @stability stable
+ */
+exports.PLATFORM_DOCTOR_CATEGORIES = [
+    'core',
+    'auth',
+    'maintenance',
+    'storage',
+    'email',
+    'push',
+    'ai',
+    'jobs',
+    'nodes',
+    'backup',
+    'telemetry',
+    'network',
+];
+/**
+ * The shipped categories under their pre-package name.
+ *
+ * @deprecated Use {@link PLATFORM_DOCTOR_CATEGORIES}; same values, same order.
+ * @stability stable
+ */
+exports.DOCTOR_CATEGORIES = exports.PLATFORM_DOCTOR_CATEGORIES;
+//# sourceMappingURL=doctor-check.interface.js.map