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

package/dist/esm/db-backup/index.d.ts

@@ -0,0 +1,19 @@
+export { ACTIVE_BACKUP_STATUSES, BACKUP_CRON_MIN_INTERVAL_MINUTES, BACKUP_CRON_PATTERN, BACKUP_FREQUENCIES, BACKUP_STATUSES, BACKUP_TIME_OF_DAY_PATTERN, BACKUP_TRIGGERS, BUILTIN_RESTORE_GATE_IDS, CANCEL_OUTCOMES, DB_BACKUP_RESTORE_COMPLETED_EVENT, DB_BACKUP_RUN_COMPLETED_EVENT, NODE_CREDENTIAL_PREFLIGHT_OUTCOMES, RESTORE_CONFIRMATION, RESTORE_GATE_ID_PATTERN, RESTORE_GATE_IDS, RESTORE_MODES, RESTORE_ROLLBACK_MODES, RESTORE_SCHEMA_OVERRIDE_FIELD, RESTORE_STATUSES, RESTORE_UNAVAILABLE_REASONS, ROLLBACK_CONFIRMATION, ROLLBACK_MODES, } from './constants.js';
+export type { BackupMirrorResult, BackupStatusName, BackupTriggerName, BuiltinRestoreGateId, DbBackupEnum, DbBackupRestoreCompletedEvent, DbBackupRunCompletedEvent, RestoreGateId, RestoreMode, RestoreStatusName, RollbackMode, } from './constants.js';
+export { backupRetentionSchema, databaseBackupResponseSchema, databaseBackupSettingsPatchSchema, databaseBackupSettingsSchema, systemDatabaseBackupPatchSchema, systemDatabaseBackupSchema } from './schemas.js';
+export type { BackupRetention, DatabaseBackupSettingsPatchInput, SystemDatabaseBackupValue } from './schemas.js';
+export { databaseBackupConfigSchema, updateDatabaseBackupConfigSchema } from './schemas.js';
+export type { DatabaseBackupConfigResponse, UpdateDatabaseBackupConfig } from './schemas.js';
+export { backupRunSchema } from './schemas.js';
+export type { BackupRunResponse } from './schemas.js';
+export { backupRunListQuerySchema } from './schemas.js';
+export type { BackupRunListQuery } from './schemas.js';
+export { backupDownloadUrlSchema, cancelBackupResultSchema, deleteBackupResultSchema } from './schemas.js';
+export type { BackupDownloadUrl, CancelBackupResult, DeleteBackupResult } from './schemas.js';
+export { restoreGateIdSchema, restoreGateSchema, restorePreflightSchema, restoreRollbackPlanSchema, rollbackRenamedSchema, rollbackRestoreRequestSchema, rollbackRestoreResponseSchema, rollbackRestoreStartedSchema, rollbackUnavailableSchema, startRestoreBlockedSchema, startRestoreGuidedSchema, startRestoreRequestSchema, startRestoreResponseSchema, startRestoreRunningSchema } from './schemas.js';
+export type { RestorePreflightView, RollbackRestoreRequest, RollbackRestoreResponse, StartRestoreRequest, StartRestoreResponse } from './schemas.js';
+export { guidedJobRoleInstructionsSchema, nodeCredentialPreflightSchema } from './schemas.js';
+export type { NodeCredentialPreflight } from './schemas.js';
+export { dbBackupRunResultSchema } from './schemas.js';
+export type { DbBackupRunResult } from './schemas.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/db-backup/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/db-backup/index.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,sBAAsB,EACtB,gCAAgC,EAChC,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,0BAA0B,EAC1B,eAAe,EACf,wBAAwB,EACxB,eAAe,EACf,iCAAiC,EACjC,6BAA6B,EAC7B,kCAAkC,EAClC,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,aAAa,EACb,sBAAsB,EACtB,6BAA6B,EAC7B,gBAAgB,EAChB,2BAA2B,EAC3B,qBAAqB,EACrB,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,YAAY,EACZ,6BAA6B,EAC7B,yBAAyB,EACzB,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,YAAY,GACb,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,iCAAiC,EAAE,4BAA4B,EAAE,+BAA+B,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AACjN,YAAY,EAAE,eAAe,EAAE,gCAAgC,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAGjH,OAAO,EAAE,0BAA0B,EAAE,gCAAgC,EAAE,MAAM,cAAc,CAAC;AAC5F,YAAY,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAG7F,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGtD,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGvD,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAC3G,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAG9F,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,6BAA6B,EAAE,4BAA4B,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAC7Y,YAAY,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAGrJ,OAAO,EAAE,+BAA+B,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAC9F,YAAY,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAG5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

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

@@ -0,0 +1,25 @@
+// `@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.
+export { ACTIVE_BACKUP_STATUSES, BACKUP_CRON_MIN_INTERVAL_MINUTES, BACKUP_CRON_PATTERN, BACKUP_FREQUENCIES, BACKUP_STATUSES, BACKUP_TIME_OF_DAY_PATTERN, BACKUP_TRIGGERS, BUILTIN_RESTORE_GATE_IDS, CANCEL_OUTCOMES, DB_BACKUP_RESTORE_COMPLETED_EVENT, DB_BACKUP_RUN_COMPLETED_EVENT, NODE_CREDENTIAL_PREFLIGHT_OUTCOMES, RESTORE_CONFIRMATION, RESTORE_GATE_ID_PATTERN, RESTORE_GATE_IDS, RESTORE_MODES, RESTORE_ROLLBACK_MODES, RESTORE_SCHEMA_OVERRIDE_FIELD, RESTORE_STATUSES, RESTORE_UNAVAILABLE_REASONS, ROLLBACK_CONFIRMATION, ROLLBACK_MODES, } from './constants.js';
+// ---- ./settings-schemas.ts
+export { backupRetentionSchema, databaseBackupResponseSchema, databaseBackupSettingsPatchSchema, databaseBackupSettingsSchema, systemDatabaseBackupPatchSchema, systemDatabaseBackupSchema } from './schemas.js';
+// ---- ./config.ts
+export { databaseBackupConfigSchema, updateDatabaseBackupConfigSchema } from './schemas.js';
+// ---- ./runs.ts
+export { backupRunSchema } from './schemas.js';
+// ---- ./runs-list-query.ts
+export { backupRunListQuerySchema } from './schemas.js';
+// ---- ./run-actions.ts
+export { backupDownloadUrlSchema, cancelBackupResultSchema, deleteBackupResultSchema } from './schemas.js';
+// ---- ./restore.ts
+export { restoreGateIdSchema, restoreGateSchema, restorePreflightSchema, restoreRollbackPlanSchema, rollbackRenamedSchema, rollbackRestoreRequestSchema, rollbackRestoreResponseSchema, rollbackRestoreStartedSchema, rollbackUnavailableSchema, startRestoreBlockedSchema, startRestoreGuidedSchema, startRestoreRequestSchema, startRestoreResponseSchema, startRestoreRunningSchema } from './schemas.js';
+// ---- ./node-credential.ts
+export { guidedJobRoleInstructionsSchema, nodeCredentialPreflightSchema } from './schemas.js';
+// ---- ./node-result.ts
+export { dbBackupRunResultSchema } from './schemas.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/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,OAAO,EACL,sBAAsB,EACtB,gCAAgC,EAChC,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,0BAA0B,EAC1B,eAAe,EACf,wBAAwB,EACxB,eAAe,EACf,iCAAiC,EACjC,6BAA6B,EAC7B,kCAAkC,EAClC,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,aAAa,EACb,sBAAsB,EACtB,6BAA6B,EAC7B,gBAAgB,EAChB,2BAA2B,EAC3B,qBAAqB,EACrB,cAAc,GACf,MAAM,gBAAgB,CAAC;AAexB,6BAA6B;AAC7B,OAAO,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,iCAAiC,EAAE,4BAA4B,EAAE,+BAA+B,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAGjN,mBAAmB;AACnB,OAAO,EAAE,0BAA0B,EAAE,gCAAgC,EAAE,MAAM,cAAc,CAAC;AAG5F,iBAAiB;AACjB,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/C,4BAA4B;AAC5B,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAGxD,wBAAwB;AACxB,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAG3G,oBAAoB;AACpB,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,6BAA6B,EAAE,4BAA4B,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAG7Y,4BAA4B;AAC5B,OAAO,EAAE,+BAA+B,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAG9F,wBAAwB;AACxB,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC"}

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

@@ -0,0 +1,104 @@
+// =============================================================================
+// 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.
+// =============================================================================
+import { z } from 'zod';
+import { NODE_CREDENTIAL_PREFLIGHT_OUTCOMES } from './constants.js';
+/**
+ * The SQL block (and runbook) that makes a node credential mintable.
+ *
+ * @stability stable
+ */
+export const guidedJobRoleInstructionsSchema = z.object({
+    /** What sent the operator here, in one sentence. Matches `detail`. */
+    reason: 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: z.string(),
+    /** Repository-relative path to the runbook that explains the block. */
+    runbook: z.string(),
+});
+/**
+ * `GET /api/admin/db-backup/node-credential-preflight` response.
+ *
+ * @stability stable
+ */
+export const nodeCredentialPreflightSchema = 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: z.enum(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: z.string(),
+    /** The role this API connects to PostgreSQL as — the one that would mint. */
+    databaseRole: z.string(),
+    /** The database a node would be given read access to. */
+    targetDatabase: 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: z.boolean(),
+    /** One or two sentences an operator can act on, matched to `outcome`. */
+    detail: z.string(),
+    /** Present exactly when `outcome` is `guided`. */
+    guidance: guidedJobRoleInstructionsSchema.nullable(),
+});
+//# sourceMappingURL=node-credential.js.map

package/dist/esm/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,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,kCAAkC,EAAqB,MAAM,gBAAgB,CAAC;AAEvF;;;;GAIG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IACtD,sEAAsE;IACtE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAElB;;;;;;;OAOG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IAEpB,uEAAuE;IACvE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;CACpB,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC;IACpD;;;;;OAKG;IACH,OAAO,EAAG,CAAC,CAAC,IAAI,CAAC,kCAAkC,CAAwE;IAE3H;;;;;OAKG;IACH,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAEhB,6EAA6E;IAC7E,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IAExB,yDAAyD;IACzD,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;IAE1B;;;;;;;;OAQG;IACH,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE;IAE1B,yEAAyE;IACzE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAElB,kDAAkD;IAClD,QAAQ,EAAE,+BAA+B,CAAC,QAAQ,EAAE;CACrD,CAAC,CAAC"}

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

@@ -0,0 +1,165 @@
+// =============================================================================
+// `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.
+// =============================================================================
+import { z } from '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
+ */
+export const dbBackupRunResultSchema = 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: 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: 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: 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: z.string().max(128).nullable(),
+    /** The PostgreSQL server version the node dumped FROM. Same nullability rule. */
+    dbVersion: 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: 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: z.iso.datetime(),
+    /** Finished at. */
+    finishedAt: z.iso.datetime(),
+});
+//# sourceMappingURL=node-result.js.map

package/dist/esm/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,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,4EAA4E;AAC5E,MAAM,UAAU,GAAG,gBAAgB,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,YAAY,GAAG,YAAY,CAAC;AAElC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C;;;;;;;;;OASG;IACH,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;IAEvC;;;OAGG;IACH,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,KAAK,CAAC,YAAY,EAAE,mDAAmD,CAAC;IAE3E;;;;;;;;OAQG;IACH,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,KAAK,CAAC,UAAU,EAAE,qDAAqD,CAAC;IAE3E;;;;;;;;;;OAUG;IACH,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAE7C,iFAAiF;IACjF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAEzC;;;;;;;;OAQG;IACH,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAE7C;;;;;;;;;;;OAWG;IACH,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE;IAC3B,mBAAmB;IACnB,UAAU,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE;CAC7B,CAAC,CAAC"}