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

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

@@ -0,0 +1,81 @@
+"use strict";
+// `@marinoscar/platform-contract/db-backup`: the database backup and restore
+// slice's wire shapes, shared by `@marinoscar/platform-api/db-backup` (its DTOs
+// wrap these schemas) and `@marinoscar/platform-web/db-backup` (types) (issue
+// #740, PP-8.7): the admin routes under `/api/admin/db-backup`, the
+// `databaseBackup` system-settings namespace and the `db.backup.run` node
+// result. Documented in ./README.md. Explicit named exports only.
+// constants.ts is zod-free.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.guidedJobRoleInstructionsSchema = exports.startRestoreRunningSchema = exports.startRestoreResponseSchema = exports.startRestoreRequestSchema = exports.startRestoreGuidedSchema = exports.startRestoreBlockedSchema = exports.rollbackUnavailableSchema = exports.rollbackRestoreStartedSchema = exports.rollbackRestoreResponseSchema = exports.rollbackRestoreRequestSchema = exports.rollbackRenamedSchema = exports.restoreRollbackPlanSchema = exports.restorePreflightSchema = exports.restoreGateSchema = exports.restoreGateIdSchema = exports.deleteBackupResultSchema = exports.cancelBackupResultSchema = exports.backupDownloadUrlSchema = exports.backupRunListQuerySchema = exports.backupRunSchema = exports.updateDatabaseBackupConfigSchema = exports.databaseBackupConfigSchema = exports.systemDatabaseBackupSchema = exports.systemDatabaseBackupPatchSchema = exports.databaseBackupSettingsSchema = exports.databaseBackupSettingsPatchSchema = exports.databaseBackupResponseSchema = exports.backupRetentionSchema = exports.ROLLBACK_MODES = exports.ROLLBACK_CONFIRMATION = exports.RESTORE_UNAVAILABLE_REASONS = exports.RESTORE_STATUSES = exports.RESTORE_SCHEMA_OVERRIDE_FIELD = exports.RESTORE_ROLLBACK_MODES = exports.RESTORE_MODES = exports.RESTORE_GATE_IDS = exports.RESTORE_GATE_ID_PATTERN = exports.RESTORE_CONFIRMATION = exports.NODE_CREDENTIAL_PREFLIGHT_OUTCOMES = exports.DB_BACKUP_RUN_COMPLETED_EVENT = exports.DB_BACKUP_RESTORE_COMPLETED_EVENT = exports.CANCEL_OUTCOMES = exports.BUILTIN_RESTORE_GATE_IDS = exports.BACKUP_TRIGGERS = exports.BACKUP_TIME_OF_DAY_PATTERN = exports.BACKUP_STATUSES = exports.BACKUP_FREQUENCIES = exports.BACKUP_CRON_PATTERN = exports.BACKUP_CRON_MIN_INTERVAL_MINUTES = exports.ACTIVE_BACKUP_STATUSES = void 0;
+exports.dbBackupRunResultSchema = exports.nodeCredentialPreflightSchema = void 0;
+var constants_js_1 = require("./constants.js");
+Object.defineProperty(exports, "ACTIVE_BACKUP_STATUSES", { enumerable: true, get: function () { return constants_js_1.ACTIVE_BACKUP_STATUSES; } });
+Object.defineProperty(exports, "BACKUP_CRON_MIN_INTERVAL_MINUTES", { enumerable: true, get: function () { return constants_js_1.BACKUP_CRON_MIN_INTERVAL_MINUTES; } });
+Object.defineProperty(exports, "BACKUP_CRON_PATTERN", { enumerable: true, get: function () { return constants_js_1.BACKUP_CRON_PATTERN; } });
+Object.defineProperty(exports, "BACKUP_FREQUENCIES", { enumerable: true, get: function () { return constants_js_1.BACKUP_FREQUENCIES; } });
+Object.defineProperty(exports, "BACKUP_STATUSES", { enumerable: true, get: function () { return constants_js_1.BACKUP_STATUSES; } });
+Object.defineProperty(exports, "BACKUP_TIME_OF_DAY_PATTERN", { enumerable: true, get: function () { return constants_js_1.BACKUP_TIME_OF_DAY_PATTERN; } });
+Object.defineProperty(exports, "BACKUP_TRIGGERS", { enumerable: true, get: function () { return constants_js_1.BACKUP_TRIGGERS; } });
+Object.defineProperty(exports, "BUILTIN_RESTORE_GATE_IDS", { enumerable: true, get: function () { return constants_js_1.BUILTIN_RESTORE_GATE_IDS; } });
+Object.defineProperty(exports, "CANCEL_OUTCOMES", { enumerable: true, get: function () { return constants_js_1.CANCEL_OUTCOMES; } });
+Object.defineProperty(exports, "DB_BACKUP_RESTORE_COMPLETED_EVENT", { enumerable: true, get: function () { return constants_js_1.DB_BACKUP_RESTORE_COMPLETED_EVENT; } });
+Object.defineProperty(exports, "DB_BACKUP_RUN_COMPLETED_EVENT", { enumerable: true, get: function () { return constants_js_1.DB_BACKUP_RUN_COMPLETED_EVENT; } });
+Object.defineProperty(exports, "NODE_CREDENTIAL_PREFLIGHT_OUTCOMES", { enumerable: true, get: function () { return constants_js_1.NODE_CREDENTIAL_PREFLIGHT_OUTCOMES; } });
+Object.defineProperty(exports, "RESTORE_CONFIRMATION", { enumerable: true, get: function () { return constants_js_1.RESTORE_CONFIRMATION; } });
+Object.defineProperty(exports, "RESTORE_GATE_ID_PATTERN", { enumerable: true, get: function () { return constants_js_1.RESTORE_GATE_ID_PATTERN; } });
+Object.defineProperty(exports, "RESTORE_GATE_IDS", { enumerable: true, get: function () { return constants_js_1.RESTORE_GATE_IDS; } });
+Object.defineProperty(exports, "RESTORE_MODES", { enumerable: true, get: function () { return constants_js_1.RESTORE_MODES; } });
+Object.defineProperty(exports, "RESTORE_ROLLBACK_MODES", { enumerable: true, get: function () { return constants_js_1.RESTORE_ROLLBACK_MODES; } });
+Object.defineProperty(exports, "RESTORE_SCHEMA_OVERRIDE_FIELD", { enumerable: true, get: function () { return constants_js_1.RESTORE_SCHEMA_OVERRIDE_FIELD; } });
+Object.defineProperty(exports, "RESTORE_STATUSES", { enumerable: true, get: function () { return constants_js_1.RESTORE_STATUSES; } });
+Object.defineProperty(exports, "RESTORE_UNAVAILABLE_REASONS", { enumerable: true, get: function () { return constants_js_1.RESTORE_UNAVAILABLE_REASONS; } });
+Object.defineProperty(exports, "ROLLBACK_CONFIRMATION", { enumerable: true, get: function () { return constants_js_1.ROLLBACK_CONFIRMATION; } });
+Object.defineProperty(exports, "ROLLBACK_MODES", { enumerable: true, get: function () { return constants_js_1.ROLLBACK_MODES; } });
+// ---- ./settings-schemas.ts
+var schemas_js_1 = require("./schemas.js");
+Object.defineProperty(exports, "backupRetentionSchema", { enumerable: true, get: function () { return schemas_js_1.backupRetentionSchema; } });
+Object.defineProperty(exports, "databaseBackupResponseSchema", { enumerable: true, get: function () { return schemas_js_1.databaseBackupResponseSchema; } });
+Object.defineProperty(exports, "databaseBackupSettingsPatchSchema", { enumerable: true, get: function () { return schemas_js_1.databaseBackupSettingsPatchSchema; } });
+Object.defineProperty(exports, "databaseBackupSettingsSchema", { enumerable: true, get: function () { return schemas_js_1.databaseBackupSettingsSchema; } });
+Object.defineProperty(exports, "systemDatabaseBackupPatchSchema", { enumerable: true, get: function () { return schemas_js_1.systemDatabaseBackupPatchSchema; } });
+Object.defineProperty(exports, "systemDatabaseBackupSchema", { enumerable: true, get: function () { return schemas_js_1.systemDatabaseBackupSchema; } });
+// ---- ./config.ts
+var schemas_js_2 = require("./schemas.js");
+Object.defineProperty(exports, "databaseBackupConfigSchema", { enumerable: true, get: function () { return schemas_js_2.databaseBackupConfigSchema; } });
+Object.defineProperty(exports, "updateDatabaseBackupConfigSchema", { enumerable: true, get: function () { return schemas_js_2.updateDatabaseBackupConfigSchema; } });
+// ---- ./runs.ts
+var schemas_js_3 = require("./schemas.js");
+Object.defineProperty(exports, "backupRunSchema", { enumerable: true, get: function () { return schemas_js_3.backupRunSchema; } });
+// ---- ./runs-list-query.ts
+var schemas_js_4 = require("./schemas.js");
+Object.defineProperty(exports, "backupRunListQuerySchema", { enumerable: true, get: function () { return schemas_js_4.backupRunListQuerySchema; } });
+// ---- ./run-actions.ts
+var schemas_js_5 = require("./schemas.js");
+Object.defineProperty(exports, "backupDownloadUrlSchema", { enumerable: true, get: function () { return schemas_js_5.backupDownloadUrlSchema; } });
+Object.defineProperty(exports, "cancelBackupResultSchema", { enumerable: true, get: function () { return schemas_js_5.cancelBackupResultSchema; } });
+Object.defineProperty(exports, "deleteBackupResultSchema", { enumerable: true, get: function () { return schemas_js_5.deleteBackupResultSchema; } });
+// ---- ./restore.ts
+var schemas_js_6 = require("./schemas.js");
+Object.defineProperty(exports, "restoreGateIdSchema", { enumerable: true, get: function () { return schemas_js_6.restoreGateIdSchema; } });
+Object.defineProperty(exports, "restoreGateSchema", { enumerable: true, get: function () { return schemas_js_6.restoreGateSchema; } });
+Object.defineProperty(exports, "restorePreflightSchema", { enumerable: true, get: function () { return schemas_js_6.restorePreflightSchema; } });
+Object.defineProperty(exports, "restoreRollbackPlanSchema", { enumerable: true, get: function () { return schemas_js_6.restoreRollbackPlanSchema; } });
+Object.defineProperty(exports, "rollbackRenamedSchema", { enumerable: true, get: function () { return schemas_js_6.rollbackRenamedSchema; } });
+Object.defineProperty(exports, "rollbackRestoreRequestSchema", { enumerable: true, get: function () { return schemas_js_6.rollbackRestoreRequestSchema; } });
+Object.defineProperty(exports, "rollbackRestoreResponseSchema", { enumerable: true, get: function () { return schemas_js_6.rollbackRestoreResponseSchema; } });
+Object.defineProperty(exports, "rollbackRestoreStartedSchema", { enumerable: true, get: function () { return schemas_js_6.rollbackRestoreStartedSchema; } });
+Object.defineProperty(exports, "rollbackUnavailableSchema", { enumerable: true, get: function () { return schemas_js_6.rollbackUnavailableSchema; } });
+Object.defineProperty(exports, "startRestoreBlockedSchema", { enumerable: true, get: function () { return schemas_js_6.startRestoreBlockedSchema; } });
+Object.defineProperty(exports, "startRestoreGuidedSchema", { enumerable: true, get: function () { return schemas_js_6.startRestoreGuidedSchema; } });
+Object.defineProperty(exports, "startRestoreRequestSchema", { enumerable: true, get: function () { return schemas_js_6.startRestoreRequestSchema; } });
+Object.defineProperty(exports, "startRestoreResponseSchema", { enumerable: true, get: function () { return schemas_js_6.startRestoreResponseSchema; } });
+Object.defineProperty(exports, "startRestoreRunningSchema", { enumerable: true, get: function () { return schemas_js_6.startRestoreRunningSchema; } });
+// ---- ./node-credential.ts
+var schemas_js_7 = require("./schemas.js");
+Object.defineProperty(exports, "guidedJobRoleInstructionsSchema", { enumerable: true, get: function () { return schemas_js_7.guidedJobRoleInstructionsSchema; } });
+Object.defineProperty(exports, "nodeCredentialPreflightSchema", { enumerable: true, get: function () { return schemas_js_7.nodeCredentialPreflightSchema; } });
+// ---- ./node-result.ts
+var schemas_js_8 = require("./schemas.js");
+Object.defineProperty(exports, "dbBackupRunResultSchema", { enumerable: true, get: function () { return schemas_js_8.dbBackupRunResultSchema; } });
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/db-backup/index.ts"],"names":[],"mappings":";AAAA,6EAA6E;AAC7E,gFAAgF;AAChF,8EAA8E;AAC9E,oEAAoE;AACpE,0EAA0E;AAC1E,kEAAkE;AAClE,4BAA4B;;;;AAE5B,+CAuBwB;AAtBtB,sHAAA,sBAAsB,OAAA;AACtB,gIAAA,gCAAgC,OAAA;AAChC,mHAAA,mBAAmB,OAAA;AACnB,kHAAA,kBAAkB,OAAA;AAClB,+GAAA,eAAe,OAAA;AACf,0HAAA,0BAA0B,OAAA;AAC1B,+GAAA,eAAe,OAAA;AACf,wHAAA,wBAAwB,OAAA;AACxB,+GAAA,eAAe,OAAA;AACf,iIAAA,iCAAiC,OAAA;AACjC,6HAAA,6BAA6B,OAAA;AAC7B,kIAAA,kCAAkC,OAAA;AAClC,oHAAA,oBAAoB,OAAA;AACpB,uHAAA,uBAAuB,OAAA;AACvB,gHAAA,gBAAgB,OAAA;AAChB,6GAAA,aAAa,OAAA;AACb,sHAAA,sBAAsB,OAAA;AACtB,6HAAA,6BAA6B,OAAA;AAC7B,gHAAA,gBAAgB,OAAA;AAChB,2HAAA,2BAA2B,OAAA;AAC3B,qHAAA,qBAAqB,OAAA;AACrB,8GAAA,cAAc,OAAA;AAgBhB,6BAA6B;AAC7B,2CAAiN;AAAxM,mHAAA,qBAAqB,OAAA;AAAE,0HAAA,4BAA4B,OAAA;AAAE,+HAAA,iCAAiC,OAAA;AAAE,0HAAA,4BAA4B,OAAA;AAAE,6HAAA,+BAA+B,OAAA;AAAE,wHAAA,0BAA0B,OAAA;AAG1L,mBAAmB;AACnB,2CAA4F;AAAnF,wHAAA,0BAA0B,OAAA;AAAE,8HAAA,gCAAgC,OAAA;AAGrE,iBAAiB;AACjB,2CAA+C;AAAtC,6GAAA,eAAe,OAAA;AAGxB,4BAA4B;AAC5B,2CAAwD;AAA/C,sHAAA,wBAAwB,OAAA;AAGjC,wBAAwB;AACxB,2CAA2G;AAAlG,qHAAA,uBAAuB,OAAA;AAAE,sHAAA,wBAAwB,OAAA;AAAE,sHAAA,wBAAwB,OAAA;AAGpF,oBAAoB;AACpB,2CAA6Y;AAApY,iHAAA,mBAAmB,OAAA;AAAE,+GAAA,iBAAiB,OAAA;AAAE,oHAAA,sBAAsB,OAAA;AAAE,uHAAA,yBAAyB,OAAA;AAAE,mHAAA,qBAAqB,OAAA;AAAE,0HAAA,4BAA4B,OAAA;AAAE,2HAAA,6BAA6B,OAAA;AAAE,0HAAA,4BAA4B,OAAA;AAAE,uHAAA,yBAAyB,OAAA;AAAE,uHAAA,yBAAyB,OAAA;AAAE,sHAAA,wBAAwB,OAAA;AAAE,uHAAA,yBAAyB,OAAA;AAAE,wHAAA,0BAA0B,OAAA;AAAE,uHAAA,yBAAyB,OAAA;AAGtX,4BAA4B;AAC5B,2CAA8F;AAArF,6HAAA,+BAA+B,OAAA;AAAE,2HAAA,6BAA6B,OAAA;AAGvE,wBAAwB;AACxB,2CAAuD;AAA9C,qHAAA,uBAAuB,OAAA"}

package/dist/cjs/db-backup/node-credential.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { type DbBackupEnum } from './constants.js';
+/**
+ * The SQL block (and runbook) that makes a node credential mintable.
+ *
+ * @stability stable
+ */
+export declare const guidedJobRoleInstructionsSchema: z.ZodObject<{
+    reason: z.ZodString;
+    commands: z.ZodString;
+    runbook: z.ZodString;
+}, z.core.$strip>;
+/**
+ * `GET /api/admin/db-backup/node-credential-preflight` response.
+ *
+ * @stability stable
+ */
+export declare const nodeCredentialPreflightSchema: z.ZodObject<{
+    outcome: z.ZodEnum<DbBackupEnum<readonly ["ok", "guided"]>>;
+    kind: z.ZodString;
+    databaseRole: z.ZodString;
+    targetDatabase: z.ZodString;
+    brokerEnabled: z.ZodBoolean;
+    detail: z.ZodString;
+    guidance: z.ZodNullable<z.ZodObject<{
+        reason: z.ZodString;
+        commands: z.ZodString;
+        runbook: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * The parsed {@link nodeCredentialPreflightSchema}.
+ *
+ * @stability stable
+ */
+export type NodeCredentialPreflight = z.infer<typeof nodeCredentialPreflightSchema>;
+//# sourceMappingURL=node-credential.d.ts.map

package/dist/cjs/db-backup/node-credential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-credential.d.ts","sourceRoot":"","sources":["../../../src/db-backup/node-credential.ts"],"names":[],"mappings":"AA2CA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAsC,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEvF;;;;GAIG;AACH,eAAO,MAAM,+BAA+B;;;;iBAgB1C,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;iBAuCxC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC"}

package/dist/cjs/db-backup/node-credential.js

@@ -0,0 +1,107 @@
+"use strict";
+// =============================================================================
+// What `GET admin/db-backup/node-credential-preflight` answers with
+// (issue #350, epic #345)
+// =============================================================================
+//
+// ONE QUESTION: can this deployment hand a worker node a short-lived,
+// SELECT-only credential to its own database, so that a `db.backup.run` job can
+// be executed somewhere other than the API process?
+//
+// -----------------------------------------------------------------------------
+// ⚠ `guided` IS A 200, AND INVENTING A STATUS CODE FOR IT WOULD BE THE BUG
+// -----------------------------------------------------------------------------
+//
+// This is the third place in this subsystem to make the same argument, and it
+// is the same argument every time (`db-backup.controller.ts`'s header for the
+// restore pair; `docs/specs/database-restore.md` for the `CREATEDB` gate):
+// managed PostgreSQL withholding `CREATEROLE` from an application role is the
+// ORDINARY configuration, not a fault. A 4xx here would tell an administrator
+// their platform is unsupported when it is not, and a 5xx would tell them
+// something is broken when nothing is. What is true is smaller and more useful:
+// node offload needs two lines of SQL they have not run, and if they choose not
+// to run them the API keeps taking its own backups exactly as before.
+//
+// So the STATUS is always 200 and the ANSWER is `outcome`, with the SQL in
+// `guidance.commands` — real role names, ready to paste. A block with a
+// placeholder in it is not a deliverable, it is homework.
+//
+// -----------------------------------------------------------------------------
+// WHY `brokerEnabled` IS A SEPARATE FIELD FROM `outcome`
+// -----------------------------------------------------------------------------
+//
+// They are different facts and conflating them would be actively misleading.
+// `outcome` is a CAPABILITY — whether this deployment's database role CAN mint.
+// `brokerEnabled` is a POLICY — whether an administrator has decided its fleet
+// is inside the trust boundary (`nodes.jobSecretBrokerEnabled`, default OFF).
+//
+// An operator can face any combination, and each needs a different next step: a
+// capable deployment with the policy off is one toggle away; an enabled policy
+// on a role without `CREATEROLE` needs the `GRANT` below and nothing else; both
+// off need both. Folding them into one verdict would send half of those people
+// to the wrong screen.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeCredentialPreflightSchema = exports.guidedJobRoleInstructionsSchema = void 0;
+const zod_1 = require("zod");
+const constants_js_1 = require("./constants.js");
+/**
+ * The SQL block (and runbook) that makes a node credential mintable.
+ *
+ * @stability stable
+ */
+exports.guidedJobRoleInstructionsSchema = zod_1.z.object({
+    /** What sent the operator here, in one sentence. Matches `detail`. */
+    reason: zod_1.z.string(),
+    /**
+     * A complete SQL block with this deployment's real role name in it.
+     *
+     * Two options rather than one, because they are different trades and not a
+     * preference: `ALTER ROLE ... CREATEROLE` is one statement, and a dedicated
+     * `NOINHERIT CREATEROLE` minter role is the least-privilege answer. See
+     * `buildCreateRoleGrantCommands` in `pg-job-role.broker.ts`.
+     */
+    commands: zod_1.z.string(),
+    /** Repository-relative path to the runbook that explains the block. */
+    runbook: zod_1.z.string(),
+});
+/**
+ * `GET /api/admin/db-backup/node-credential-preflight` response.
+ *
+ * @stability stable
+ */
+exports.nodeCredentialPreflightSchema = zod_1.z.object({
+    /**
+     * `ok` — a credential can be minted right now.
+     * `guided` — it cannot, and `guidance.commands` is what fixes that.
+     *
+     * ⚠ NEITHER IS AN ERROR. See this file's header.
+     */
+    outcome: zod_1.z.enum(constants_js_1.NODE_CREDENTIAL_PREFLIGHT_OUTCOMES),
+    /**
+     * The credential kind this deployment would issue, e.g. `postgres.readonly`.
+     *
+     * The same string recorded on every `job_node_secrets` row, so an operator
+     * reading a grant and an operator reading this page are looking at one name.
+     */
+    kind: zod_1.z.string(),
+    /** The role this API connects to PostgreSQL as — the one that would mint. */
+    databaseRole: zod_1.z.string(),
+    /** The database a node would be given read access to. */
+    targetDatabase: zod_1.z.string(),
+    /**
+     * Whether an administrator has switched brokering on
+     * (`nodes.jobSecretBrokerEnabled`).
+     *
+     * A POLICY, not a capability — see this file's header for why it is not
+     * folded into `outcome`. `false` is the shipped default and means no node is
+     * offered a job of a type that needs a credential, whatever this deployment
+     * is capable of.
+     */
+    brokerEnabled: zod_1.z.boolean(),
+    /** One or two sentences an operator can act on, matched to `outcome`. */
+    detail: zod_1.z.string(),
+    /** Present exactly when `outcome` is `guided`. */
+    guidance: exports.guidedJobRoleInstructionsSchema.nullable(),
+});
+//# sourceMappingURL=node-credential.js.map

package/dist/cjs/db-backup/node-credential.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-credential.js","sourceRoot":"","sources":["../../../src/db-backup/node-credential.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,oEAAoE;AACpE,0BAA0B;AAC1B,gFAAgF;AAChF,EAAE;AACF,sEAAsE;AACtE,gFAAgF;AAChF,oDAAoD;AACpD,EAAE;AACF,gFAAgF;AAChF,2EAA2E;AAC3E,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,2EAA2E;AAC3E,8EAA8E;AAC9E,8EAA8E;AAC9E,0EAA0E;AAC1E,gFAAgF;AAChF,gFAAgF;AAChF,sEAAsE;AACtE,EAAE;AACF,2EAA2E;AAC3E,wEAAwE;AACxE,0DAA0D;AAC1D,EAAE;AACF,gFAAgF;AAChF,yDAAyD;AACzD,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,+EAA+E;AAC/E,8EAA8E;AAC9E,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,uBAAuB;AACvB,gFAAgF;;;AAEhF,6BAAwB;AAExB,iDAAuF;AAEvF;;;;GAIG;AACU,QAAA,+BAA+B,GAAG,OAAC,CAAC,MAAM,CAAC;IACtD,sEAAsE;IACtE,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE;IAElB;;;;;;;OAOG;IACH,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE;IAEpB,uEAAuE;IACvE,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE;CACpB,CAAC,CAAC;AAEH;;;;GAIG;AACU,QAAA,6BAA6B,GAAG,OAAC,CAAC,MAAM,CAAC;IACpD;;;;;OAKG;IACH,OAAO,EAAG,OAAC,CAAC,IAAI,CAAC,iDAAkC,CAAwE;IAE3H;;;;;OAKG;IACH,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;IAEhB,6EAA6E;IAC7E,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE;IAExB,yDAAyD;IACzD,cAAc,EAAE,OAAC,CAAC,MAAM,EAAE;IAE1B;;;;;;;;OAQG;IACH,aAAa,EAAE,OAAC,CAAC,OAAO,EAAE;IAE1B,yEAAyE;IACzE,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE;IAElB,kDAAkD;IAClD,QAAQ,EAAE,uCAA+B,CAAC,QAAQ,EAAE;CACrD,CAAC,CAAC"}

package/dist/cjs/db-backup/node-result.d.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+/**
+ * What a worker node reports after taking a `pg_dump` and uploading it.
+ *
+ * The eight fields are three different KINDS of fact and it is worth keeping
+ * them apart when reading this:
+ *
+ *   - `storageKey` — the server's own key, echoed back so a mismatch can be
+ *     refused. Not information; a checksum on the conversation.
+ *   - `bytes` / `sha256` — what the node observed about the archive it wrote.
+ *   - `pgDumpVersion` / `dbVersion` / `migrationName` — provenance the node is
+ *     the ONLY party that can report, because it is the only party that ran
+ *     the client and held the connection.
+ *   - `startedAt` / `finishedAt` — the dump's own window on the node's clock.
+ *
+ * @stability stable
+ */
+export declare const dbBackupRunResultSchema: z.ZodObject<{
+    storageKey: z.ZodString;
+    bytes: z.ZodString;
+    sha256: z.ZodString;
+    pgDumpVersion: z.ZodNullable<z.ZodString>;
+    dbVersion: z.ZodNullable<z.ZodString>;
+    migrationName: z.ZodNullable<z.ZodString>;
+    startedAt: z.ZodISODateTime;
+    finishedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+/**
+ * The parsed, trusted result — the only shape `persistNodeResult` may write.
+ *
+ * @stability stable
+ */
+export type DbBackupRunResult = z.infer<typeof dbBackupRunResultSchema>;
+//# sourceMappingURL=node-result.d.ts.map

package/dist/cjs/db-backup/node-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-result.d.ts","sourceRoot":"","sources":["../../../src/db-backup/node-result.ts"],"names":[],"mappings":"AAiEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgBxB;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;iBA4ElC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/cjs/db-backup/node-result.js

@@ -0,0 +1,168 @@
+"use strict";
+// =============================================================================
+// `db.backup.run` — the result a node posts back (issue #352, epic #345)
+// =============================================================================
+//
+// THE TRUST BOUNDARY FOR THE FIRST JOB TYPE THAT LEAVES THE API SERVER WITH A
+// CREDENTIAL. Every field below arrives from a machine this deployment may not
+// own, over HTTP, from a `pg_dump` this process never saw run. Nothing here is
+// a formality: `NodesService.submitResult` parses against this schema and
+// `DatabaseBackupRunHandler.persistNodeResult` writes whatever survives onto a
+// `database_backup_runs` row — the row a restore later reads to find the
+// archive.
+//
+// -----------------------------------------------------------------------------
+// ⚠ `bytes` IS A DECIMAL STRING, AND THAT IS LOAD-BEARING
+// -----------------------------------------------------------------------------
+//
+// `database_backup_runs.bytes_written` and `.size_bytes` are `BigInt` columns
+// for a stated reason (see the model's own comment): a PostgreSQL dump past
+// 2 GiB is ordinary. JSON has no integers — it has doubles — so a size sent as
+// a JSON NUMBER is exact only below 2^53 and silently rounds above it. The
+// corruption would therefore land on the LARGEST backups: precisely the
+// deployments node offload exists for, and precisely the rows an operator is
+// least able to sanity-check by eye.
+//
+// So the wire type is a decimal string, validated by shape (`^\d{1,20}$` — 20
+// digits covers the whole unsigned 64-bit range with room to spare) and
+// converted with `BigInt()` exactly once, in the handler. This is the same
+// direction `db-backup-run.dto.ts` already travels on the way OUT (it
+// stringifies both `BigInt` columns because `JSON.stringify` refuses them);
+// this is that rule applied on the way IN, and the two together mean the byte
+// count that reaches the database is the byte count the dumping process
+// counted, digit for digit.
+//
+// CONTRAST `example-checksum.contract.ts`, which deliberately makes its
+// `bytes` a plain bounded `number`. That is not an inconsistency: it hashes a
+// stored object whose size cannot exceed `Number.MAX_SAFE_INTEGER` in any
+// realistic deployment, and it writes to a JSONB blob rather than to a
+// `BigInt` column. The two contracts differ because the two destinations
+// differ — copy whichever one matches the column you are writing.
+//
+// -----------------------------------------------------------------------------
+// WHAT IS *NOT* IN THIS CONTRACT, AND WHY
+// -----------------------------------------------------------------------------
+//
+// NO `verified` FLAG, and no field a node could set to assert that its own
+// archive is good. `docs/specs/database-backup.md`, "Read-back verification",
+// already settled what verification means here — "read back what the BUCKET
+// holds and parse its table of contents" — and `persistNodeResult` does exactly
+// that, server-side, before it writes `verified_at`. A node vouching for its
+// own upload is not evidence; it is the machine with the least reason to be
+// trusted attesting to the one fact the whole subsystem rests on.
+//
+// `sha256` is therefore recorded as THE NODE'S CLAIM about the bytes it
+// streamed, not as proof. It is worth having — it is what an operator compares
+// against a `sha256sum` of a downloaded archive when a restore looks wrong —
+// but it is not what makes the run `completed`.
+//
+// NO `bucket`, NO `storageProvider`, NO `format`. All three are the SERVER's
+// choice, already on the run row, and a node repeating them would create a
+// second place for them to disagree. `storageKey` is in the contract for the
+// opposite reason: it is not the node telling us where it wrote, it is the
+// node NAMING BACK the key the server handed it (`deriveOutputKey`), so the
+// handler can refuse a result that is about some other key.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dbBackupRunResultSchema = void 0;
+const zod_1 = require("zod");
+/** Canonical spelling of a SHA-256 digest: 64 lower-case hex characters. */
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+/**
+ * A non-negative integer as a decimal string, up to 20 digits.
+ *
+ * Anchored, digits only, no sign, no exponent, no leading `+`: `BigInt()`
+ * accepts a good deal more than this (whitespace, `0x` forms, `-0`) and every
+ * extra spelling it accepts is a value two implementations could round-trip
+ * differently. 20 digits is the width of `18446744073709551615`, so nothing a
+ * 64-bit counter can produce is refused, and nothing wider can be smuggled in.
+ */
+const DECIMAL_UINT = /^\d{1,20}$/;
+/**
+ * What a worker node reports after taking a `pg_dump` and uploading it.
+ *
+ * The eight fields are three different KINDS of fact and it is worth keeping
+ * them apart when reading this:
+ *
+ *   - `storageKey` — the server's own key, echoed back so a mismatch can be
+ *     refused. Not information; a checksum on the conversation.
+ *   - `bytes` / `sha256` — what the node observed about the archive it wrote.
+ *   - `pgDumpVersion` / `dbVersion` / `migrationName` — provenance the node is
+ *     the ONLY party that can report, because it is the only party that ran
+ *     the client and held the connection.
+ *   - `startedAt` / `finishedAt` — the dump's own window on the node's clock.
+ *
+ * @stability stable
+ */
+exports.dbBackupRunResultSchema = zod_1.z.object({
+    /**
+     * The key the SERVER handed this job through `deriveOutputKey`, repeated.
+     *
+     * ⚠ THE HANDLER REFUSES ANYTHING ELSE. A node may only report the key it was
+     * given: it does not choose where a backup lands (`worker-nodes.md`,
+     * "Data plane", and `job-handler.interface.ts`), and a result naming a
+     * different key is either a confused executor or an attempt to point this
+     * deployment's restore path at bytes of somebody else's choosing. Both are
+     * refusals, not corrections.
+     */
+    storageKey: zod_1.z.string().min(1).max(1024),
+    /**
+     * The archive's size in bytes, as a DECIMAL STRING. See the file header —
+     * this is the field that must not be a JSON number.
+     */
+    bytes: zod_1.z
+        .string()
+        .regex(DECIMAL_UINT, 'bytes must be a decimal string of up to 20 digits'),
+    /**
+     * Lower-case hex SHA-256 of the archive as the node streamed it.
+     *
+     * Recorded as the node's claim (see the file header). The pattern is
+     * enforced for the reason `example-checksum.contract.ts` spells out at
+     * length: a digest is only useful if everybody spells it the same way, and
+     * `"E3B0…"`, `"sha256:e3b0…"` and a truncated digest all store perfectly
+     * well while breaking the single operation anybody performs on one.
+     */
+    sha256: zod_1.z
+        .string()
+        .regex(SHA256_HEX, 'sha256 must be 64 lower-case hexadecimal characters'),
+    /**
+     * The `pg_dump --version` banner on the machine that produced the archive.
+     *
+     * NULLABLE, because an unreadable version string must never be the reason a
+     * backup is refused — the same "warn and proceed" rule `pg-version.util.ts`
+     * states for the server's own client check. It is worth carrying because on
+     * the node path it is the ONLY record of which client wrote the archive, and
+     * a `pg_restore` older than the `pg_dump` that produced a file cannot read
+     * it. The server path records its own image's client in the same column, so
+     * the row means the same thing whichever executor produced it.
+     */
+    pgDumpVersion: zod_1.z.string().max(128).nullable(),
+    /** The PostgreSQL server version the node dumped FROM. Same nullability rule. */
+    dbVersion: zod_1.z.string().max(128).nullable(),
+    /**
+     * The newest applied `_prisma_migrations` row the node could see.
+     *
+     * The most important of the three for a restore: it says which SCHEMA the
+     * archive contains. The node can read it because its minted role has
+     * `SELECT` (see `pg-job-role.broker.ts`); it is nullable because a role
+     * without that visibility, or a database mid-migration, must still be able
+     * to produce a backup.
+     */
+    migrationName: zod_1.z.string().max(255).nullable(),
+    /**
+     * When the dump started and finished, on the NODE's clock.
+     *
+     * ⚠ NOT WRITTEN TO `started_at`/`finished_at`. Those two columns are the
+     * SERVER's record of the run's lifetime and stay on the server's clock — see
+     * `DatabaseBackupRunnerService.completeNodeRun`, which uses these two to log
+     * the executor-reported dump window and to warn when a node's clock is far
+     * enough out that its future lease arithmetic is worth looking at. They are
+     * in the contract because the node is the only party that knows how long the
+     * dump itself took: the server sees the claim and the settle, and everything
+     * interesting happens in between.
+     */
+    startedAt: zod_1.z.iso.datetime(),
+    /** Finished at. */
+    finishedAt: zod_1.z.iso.datetime(),
+});
+//# sourceMappingURL=node-result.js.map

package/dist/cjs/db-backup/node-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-result.js","sourceRoot":"","sources":["../../../src/db-backup/node-result.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,yEAAyE;AACzE,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,+EAA+E;AAC/E,0EAA0E;AAC1E,+EAA+E;AAC/E,yEAAyE;AACzE,WAAW;AACX,EAAE;AACF,gFAAgF;AAChF,0DAA0D;AAC1D,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,+EAA+E;AAC/E,2EAA2E;AAC3E,wEAAwE;AACxE,6EAA6E;AAC7E,qCAAqC;AACrC,EAAE;AACF,8EAA8E;AAC9E,wEAAwE;AACxE,2EAA2E;AAC3E,sEAAsE;AACtE,4EAA4E;AAC5E,8EAA8E;AAC9E,wEAAwE;AACxE,4BAA4B;AAC5B,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,0EAA0E;AAC1E,uEAAuE;AACvE,yEAAyE;AACzE,kEAAkE;AAClE,EAAE;AACF,gFAAgF;AAChF,0CAA0C;AAC1C,gFAAgF;AAChF,EAAE;AACF,2EAA2E;AAC3E,8EAA8E;AAC9E,4EAA4E;AAC5E,gFAAgF;AAChF,6EAA6E;AAC7E,4EAA4E;AAC5E,kEAAkE;AAClE,EAAE;AACF,wEAAwE;AACxE,+EAA+E;AAC/E,6EAA6E;AAC7E,gDAAgD;AAChD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,6EAA6E;AAC7E,2EAA2E;AAC3E,4EAA4E;AAC5E,4DAA4D;AAC5D,gFAAgF;;;AAEhF,6BAAwB;AAExB,4EAA4E;AAC5E,MAAM,UAAU,GAAG,gBAAgB,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,YAAY,GAAG,YAAY,CAAC;AAElC;;;;;;;;;;;;;;;GAeG;AACU,QAAA,uBAAuB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC9C;;;;;;;;;OASG;IACH,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;IAEvC;;;OAGG;IACH,KAAK,EAAE,OAAC;SACL,MAAM,EAAE;SACR,KAAK,CAAC,YAAY,EAAE,mDAAmD,CAAC;IAE3E;;;;;;;;OAQG;IACH,MAAM,EAAE,OAAC;SACN,MAAM,EAAE;SACR,KAAK,CAAC,UAAU,EAAE,qDAAqD,CAAC;IAE3E;;;;;;;;;;OAUG;IACH,aAAa,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAE7C,iFAAiF;IACjF,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAEzC;;;;;;;;OAQG;IACH,aAAa,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAE7C;;;;;;;;;;;OAWG;IACH,SAAS,EAAE,OAAC,CAAC,GAAG,CAAC,QAAQ,EAAE;IAC3B,mBAAmB;IACnB,UAAU,EAAE,OAAC,CAAC,GAAG,CAAC,QAAQ,EAAE;CAC7B,CAAC,CAAC"}