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

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/testing/describe-doctor-check-conformance.d.ts

@@ -0,0 +1,80 @@
+import type { ConformanceTestApi } from '../../testing/index';
+import type { DoctorCheck } from '../doctor-check.interface';
+import type { DoctorStatus } from '../doctor-check.interface';
+import type { RecordingPrisma, RecordingPrismaOptions } from './recording-prisma';
+import type { WriteFailingStorage, WriteFailingStorageOptions } from './write-failing-storage';
+/**
+ * The two doubles a check is built over for one test.
+ *
+ * @stability experimental
+ */
+export interface DoctorCheckDoubles {
+    /** A recording Prisma client; bind it where the check takes `PLATFORM_PRISMA` or its slice's client. */
+    readonly prisma: RecordingPrisma;
+    /** A write-failing storage provider; bind it where the check takes `STORAGE_PROVIDER`. */
+    readonly storage: WriteFailingStorage;
+}
+/**
+ * Builds the check under test over the doubles. Called once per test, so state
+ * never leaks between cases.
+ *
+ * @stability experimental
+ */
+export type DoctorCheckFactory = (doubles: DoctorCheckDoubles) => DoctorCheck | Promise<DoctorCheck>;
+/**
+ * One world to run the check in.
+ *
+ * @stability experimental
+ */
+export interface DoctorCheckScenario {
+    /** The scenario's name, shown in every test title (`configured`, `provider down`). */
+    readonly name: string;
+    /** Scripted reads for the Prisma double (`{ 'job.count': 12 }`) and the storage double. */
+    readonly prisma?: RecordingPrismaOptions;
+    /** Options for the storage double. */
+    readonly storage?: WriteFailingStorageOptions;
+    /** Builds the check for this scenario when it differs from the suite's factory. */
+    readonly build?: DoctorCheckFactory;
+    /** The statuses the scenario may return (default: any valid status). */
+    readonly expectStatus?: DoctorStatus | readonly DoctorStatus[];
+    /** Strings that are secret in this scenario; none may appear in the result. */
+    readonly secrets?: readonly string[];
+}
+/**
+ * What {@link describeDoctorCheckConformance} accepts.
+ *
+ * @example
+ * ```ts
+ * describeDoctorCheckConformance('example.capability', ({ prisma }) => new MyCheck(registry, prisma.client), {
+ *   scenarios: [
+ *     { name: 'enabled and configured', prisma: { results: { 'setting.findFirst': { value: 'on' } } }, expectStatus: 'pass' },
+ *     { name: 'switched off', expectStatus: 'skip' },
+ *   ],
+ * });
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export interface DoctorCheckConformanceOptions {
+    /** The worlds to run in; one default scenario when omitted. */
+    readonly scenarios?: readonly DoctorCheckScenario[];
+    /** The ceiling for a check that declares no `timeoutMs` (default 5000, the service's). */
+    readonly defaultTimeoutMs?: number;
+    /** A test API to register on; defaults to the runner's globals. */
+    readonly testApi?: ConformanceTestApi;
+}
+/**
+ * Registers the Doctor check conformance cases for one check: identity, a
+ * guarded run, a valid outcome, read-only against both doubles, and no secret
+ * material, once per scenario.
+ *
+ * @param name - the check's id or a title for the `describe` block.
+ * @param factory - builds the check over the doubles, once per test.
+ * @param options - scenarios, the default timeout and the test API.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function describeDoctorCheckConformance(name: string, factory: DoctorCheckFactory, options?: DoctorCheckConformanceOptions): void;
+//# sourceMappingURL=describe-doctor-check-conformance.d.ts.map

package/dist/doctor/testing/describe-doctor-check-conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-doctor-check-conformance.d.ts","sourceRoot":"","sources":["../../../src/doctor/testing/describe-doctor-check-conformance.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D,OAAO,KAAK,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAGlF,OAAO,KAAK,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAE/F;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,wGAAwG;IACxG,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,0FAA0F;IAC1F,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,kBAAkB,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;AAErG;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC;IACzC,sCAAsC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,0BAA0B,CAAC;IAC9C,mFAAmF;IACnF,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;IACpC,wEAAwE;IACxE,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,SAAS,YAAY,EAAE,CAAC;IAC/D,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,6BAA6B;IAC5C,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACpD,0FAA0F;IAC1F,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;CACvC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,6BAAkC,GAC1C,IAAI,CA2CN"}

package/dist/doctor/testing/describe-doctor-check-conformance.js

@@ -0,0 +1,85 @@
+"use strict";
+// =============================================================================
+// The Doctor check conformance kit (PP-14.26)
+// =============================================================================
+//
+// Rule 3 of the check contract says a check is read-only, and until this kit the
+// rule was convention: an extension author had nothing to run. `describeDoctorCheckConformance`
+// is what an app (or a package that ships checks) calls from its own spec, once
+// per check, to prove the whole contract for that check:
+//
+//   - it describes itself well (a dotted id, a category, a label, a root-relative
+//     settings path, a sane timeout);
+//   - it completes within its timeout and never throws;
+//   - it returns a valid outcome: a status, a one-line detail, a remedy on warn
+//     and fail, scalar data;
+//   - it is READ-ONLY: it ran against a recording Prisma client and a write-failing
+//     storage provider, and wrote to neither;
+//   - it leaks no secret material.
+//
+// The check is built per test by the caller's factory, which receives the two
+// doubles, so a check that takes `PLATFORM_PRISMA` or `STORAGE_PROVIDER` is
+// constructed over them and a check that takes neither still gets the same grading.
+// A scenario is one world to run the check in (configured, unconfigured, the
+// dependency down); each scenario re-runs every case.
+//
+// Runner-agnostic: the kit registers on a `ConformanceTestApi`, defaulting to the
+// runner's globals, and uses only `toEqual` of the matcher subset.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeDoctorCheckConformance = describeDoctorCheckConformance;
+const index_1 = require("../../testing/index");
+const recording_prisma_1 = require("./recording-prisma");
+const run_doctor_check_1 = require("./run-doctor-check");
+const write_failing_storage_1 = require("./write-failing-storage");
+/**
+ * Registers the Doctor check conformance cases for one check: identity, a
+ * guarded run, a valid outcome, read-only against both doubles, and no secret
+ * material, once per scenario.
+ *
+ * @param name - the check's id or a title for the `describe` block.
+ * @param factory - builds the check over the doubles, once per test.
+ * @param options - scenarios, the default timeout and the test API.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+function describeDoctorCheckConformance(name, factory, options = {}) {
+    const api = (0, index_1.resolveConformanceTestApi)('describeDoctorCheckConformance', options.testApi);
+    const scenarios = options.scenarios?.length ? options.scenarios : [{ name: 'default' }];
+    api.describe(`Doctor check conformance: ${name}`, () => {
+        const prepare = async (scenario) => {
+            const doubles = {
+                prisma: (0, recording_prisma_1.createRecordingPrisma)(scenario.prisma),
+                storage: (0, write_failing_storage_1.createWriteFailingStorage)(scenario.storage),
+            };
+            return { check: await (scenario.build ?? factory)(doubles), doubles };
+        };
+        for (const scenario of scenarios) {
+            const title = (text) => (scenarios.length > 1 || scenario.name !== 'default' ? `[${scenario.name}] ${text}` : text);
+            api.it(title('describes itself: a dotted id, a category, a label, a root-relative settings path, a sane timeout'), async () => {
+                const { check } = await prepare(scenario);
+                api.expect((0, run_doctor_check_1.findIdentityProblems)(check)).toEqual([]);
+            });
+            api.it(title('completes within its timeout, never throws and returns a valid outcome with a remedy on warn and fail'), async () => {
+                const { check } = await prepare(scenario);
+                const run = await (0, run_doctor_check_1.runDoctorCheck)(check, { defaultTimeoutMs: options.defaultTimeoutMs });
+                api.expect((0, run_doctor_check_1.findOutcomeProblems)(check, run, { secrets: scenario.secrets })).toEqual([]);
+            });
+            api.it(title('answers one of the statuses the scenario expects'), async () => {
+                const { check } = await prepare(scenario);
+                const run = await (0, run_doctor_check_1.runDoctorCheck)(check, { defaultTimeoutMs: options.defaultTimeoutMs });
+                const allowed = scenario.expectStatus === undefined ? undefined : [].concat(scenario.expectStatus);
+                const got = run.outcome?.status;
+                api.expect(allowed === undefined || (got !== undefined && allowed.includes(got)) ? [] : [`expected ${allowed?.join(' or ')}, got ${String(got)}`]).toEqual([]);
+            });
+            api.it(title('is read-only: it writes nothing through Prisma and nothing to object storage'), async () => {
+                const { check, doubles } = await prepare(scenario);
+                await (0, run_doctor_check_1.runDoctorCheck)(check, { defaultTimeoutMs: options.defaultTimeoutMs });
+                api.expect(doubles.prisma.violations().map((operation) => operation.path)).toEqual([]);
+                api.expect(doubles.storage.violations().map((operation) => operation.method)).toEqual([]);
+            });
+        }
+    });
+}
+//# sourceMappingURL=describe-doctor-check-conformance.js.map

package/dist/doctor/testing/describe-doctor-check-conformance.js.map

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