@serve.zone/interfaces 32.70.0 → 32.71.0

package/changelog.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026-11-05 - 32.71.0
+
+### Features
+
+- All-or-nothing backup restore refusals (AGL-1501, Linus 2026-11-05 ruling): `data.backupRestoreRefusalNames` freezes the three reasons an in-place restore is refused before it writes anything: `restore-snapshot-unavailable` (`missing`, a non-empty list of `data.IBackupRestoreMissingSnapshot`: `snapshotId`, `capability` (`data.TBackupResourceType`) and an optional `resourceName`), `restore-preflight-unsupported` (the node's Corestore offers no restore check) and `restore-relay-contract-behind` (`relayInterfacesVersion`, a release version or `null`, below `minimumInterfacesVersion`). `data.TBackupRestoreRefusal` is discriminated by `name`; `data.validateBackupRestoreRefusal`, `data.isBackupRestoreRefusal` and `data.readBackupRestoreRefusal` judge untrusted `errorData` against each exact schema, and `data.buildBackupRestoreSnapshotUnavailableRefusal`, `data.buildBackupRestorePreflightUnsupportedRefusal` and `data.buildBackupRestoreRelayContractBehindRefusal` build them; bounds are `data.backupRestoreRefusalContract`. A restore event (`data.IBackupRestoreEvent`) adds the status `refused`, meaning nothing was written, with its `refusal`; `data.validateBackupRestoreEvent` judges only `status` and `refusal`, requiring `refusal` exactly when the status is `refused`. Additive: every existing restore event stays valid, including the unjudged `resourceTypes` and null `errorText` Cloudly already stores. Spec: `test.backuprestorerefusal`.
+
 ## 2026-11-05 - 32.70.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '32.70.0',
+    version: '32.71.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLFNBQVM7SUFDbEIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/data/backup.d.ts

@@ -1,3 +1,4 @@
+import type { TBackupRestoreRefusal } from './backuprestorerefusal.js';
 import type { ICorestoreDatabaseAllocationReference } from './corestore.js';
 export type TBackupStatus = 'pending' | 'running' | 'replicating' | 'replicated' | 'ready' | 'failed' | 'restoring' | 'restored';
 export type TBackupTrigger = 'manual' | 'scheduled';
@@ -83,9 +84,17 @@ export type TBackupFailure = {
 } | {
     kind: 'archive-unreadable';
 };
+/**
+ * One restore of a backup, appended to its `restoreHistory`; `validateBackupRestoreEvent` judges its
+ * `status` and `refusal`.
+ *
+ * `refused`: the restore was refused before it wrote anything (`refusal` says why), so the service
+ * keeps the data it had. `failed`: it failed after it began writing.
+ */
 export interface IBackupRestoreEvent {
+    /** When the restore ended, or when it was refused. */
     restoredAt: number;
-    status: 'restored' | 'failed';
+    status: 'restored' | 'failed' | 'refused';
     errorText?: string;
     /** The resource types the restore was limited to; absent when it restored every snapshot. */
     resourceTypes?: TBackupResourceType[];
@@ -94,6 +103,8 @@ export interface IBackupRestoreEvent {
      * none of the backup's `failure.uncaptured`.
      */
     partial?: true;
+    /** Why a `refused` restore wrote nothing; present exactly when `status` is `refused`. */
+    refusal?: TBackupRestoreRefusal;
 }
 /**
  * Durable retention hold owned by one isolated restore. An entry is active

package/dist_ts/data/backup.js

@@ -13,4 +13,4 @@ export const readPartialRestoreResourceTypes = (backupArg) => {
     const uncapturedTypes = new Set(failure.uncaptured.map((resourceArg) => resourceArg.type));
     return ['database', 'objectstorage'].filter((typeArg) => (!uncapturedTypes.has(typeArg) && backupArg.snapshots.some((snapshotArg) => snapshotArg.type === typeArg)));
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYmFja3VwLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9iYWNrdXAudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBb0tBOzs7Ozs7O0dBT0c7QUFDSCxNQUFNLENBQUMsTUFBTSwrQkFBK0IsR0FBRyxDQUM3QyxTQUFrSCxFQUNuRSxFQUFFO0lBQ2pELE1BQU0sT0FBTyxHQUFHLFNBQVMsQ0FBQyxPQUFPLENBQUM7SUFDbEMsSUFBSSxTQUFTLENBQUMsTUFBTSxLQUFLLFFBQVEsSUFBSSxPQUFPLEVBQUUsSUFBSSxLQUFLLFlBQVk7UUFBRSxPQUFPLEVBQUUsQ0FBQztJQUMvRSxNQUFNLGVBQWUsR0FBRyxJQUFJLEdBQUcsQ0FBc0IsT0FBTyxDQUFDLFVBQVUsQ0FBQyxHQUFHLENBQUMsQ0FBQyxXQUFXLEVBQUUsRUFBRSxDQUFDLFdBQVcsQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDO0lBQ2hILE9BQVEsQ0FBQyxVQUFVLEVBQUUsZUFBZSxDQUFXLENBQUMsTUFBTSxDQUFDLENBQUMsT0FBTyxFQUFFLEVBQUUsQ0FBQyxDQUNsRSxDQUFDLGVBQWUsQ0FBQyxHQUFHLENBQUMsT0FBTyxDQUFDLElBQUksU0FBUyxDQUFDLFNBQVMsQ0FBQyxJQUFJLENBQUMsQ0FBQyxXQUFXLEVBQUUsRUFBRSxDQUFDLFdBQVcsQ0FBQyxJQUFJLEtBQUssT0FBTyxDQUFDLENBQ3pHLENBQUMsQ0FBQztBQUNMLENBQUMsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYmFja3VwLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9iYWNrdXAudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBK0tBOzs7Ozs7O0dBT0c7QUFDSCxNQUFNLENBQUMsTUFBTSwrQkFBK0IsR0FBRyxDQUM3QyxTQUFrSCxFQUNuRSxFQUFFO0lBQ2pELE1BQU0sT0FBTyxHQUFHLFNBQVMsQ0FBQyxPQUFPLENBQUM7SUFDbEMsSUFBSSxTQUFTLENBQUMsTUFBTSxLQUFLLFFBQVEsSUFBSSxPQUFPLEVBQUUsSUFBSSxLQUFLLFlBQVk7UUFBRSxPQUFPLEVBQUUsQ0FBQztJQUMvRSxNQUFNLGVBQWUsR0FBRyxJQUFJLEdBQUcsQ0FBc0IsT0FBTyxDQUFDLFVBQVUsQ0FBQyxHQUFHLENBQUMsQ0FBQyxXQUFXLEVBQUUsRUFBRSxDQUFDLFdBQVcsQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDO0lBQ2hILE9BQVEsQ0FBQyxVQUFVLEVBQUUsZUFBZSxDQUFXLENBQUMsTUFBTSxDQUFDLENBQUMsT0FBTyxFQUFFLEVBQUUsQ0FBQyxDQUNsRSxDQUFDLGVBQWUsQ0FBQyxHQUFHLENBQUMsT0FBTyxDQUFDLElBQUksU0FBUyxDQUFDLFNBQVMsQ0FBQyxJQUFJLENBQUMsQ0FBQyxXQUFXLEVBQUUsRUFBRSxDQUFDLFdBQVcsQ0FBQyxJQUFJLEtBQUssT0FBTyxDQUFDLENBQ3pHLENBQUMsQ0FBQztBQUNMLENBQUMsQ0FBQyJ9

package/dist_ts/data/backuprestorerefusal.d.ts

@@ -0,0 +1,85 @@
+import type { TBackupResourceType } from './backup.js';
+/**
+ * Why an in-place restore of a backup (`IReq_Any_Cloudly_RestoreServiceBackup`) was refused before
+ * it wrote anything. A restore is all-or-nothing: Corestore checks that it can read every snapshot
+ * the restore names before it replaces any data, and Cloudly dispatches the restore only to a relay
+ * whose contract carries that check. A refusal therefore always means nothing was written; the
+ * service keeps the data it had.
+ *
+ * - `restore-snapshot-unavailable`: the node's Corestore cannot read one or more snapshots the
+ *   restore names; `missing` names each of them.
+ * - `restore-preflight-unsupported`: the node's Corestore does not offer the restore check (a
+ *   Corestore built before it answers the check route with HTTP 404), so it cannot prove the
+ *   restore would be whole and nothing is restored.
+ * - `restore-relay-contract-behind`: the cluster relay speaks an interfaces release below the one
+ *   that carries the restore check, so Cloudly does not dispatch the restore; the relay states
+ *   `relayInterfacesVersion` (`null` when it stated none) and the restore needs
+ *   `minimumInterfacesVersion`.
+ *
+ * It travels as `TypedResponseError.errorData` of a refused restore and is recorded as the
+ * `refusal` of the backup's `refused` restore event (`IBackupRestoreEvent`). Each refusal is
+ * exactly its schema: `readBackupRestoreRefusal` refuses any other member, so a producer never adds
+ * one without gating it on the reader's interfaces version.
+ */
+export declare const backupRestoreRefusalNames: readonly ["restore-snapshot-unavailable", "restore-preflight-unsupported", "restore-relay-contract-behind"];
+export type TBackupRestoreRefusalName = typeof backupRestoreRefusalNames[number];
+export declare const backupRestoreRefusalContract: Readonly<{
+    /** At most this many snapshots are named in one `restore-snapshot-unavailable`. */
+    readonly maximumMissingSnapshots: 256;
+    /** A snapshot id or resource name is printable ASCII without spaces, at most this long. */
+    readonly maximumNameLength: 255;
+}>;
+/** One snapshot a restore names that the node's Corestore cannot read. */
+export interface IBackupRestoreMissingSnapshot {
+    snapshotId: string;
+    /** The snapshot's resource type (`TBackupSnapshot['type']`). */
+    capability: TBackupResourceType;
+    /** The Corestore resource of a database or object-storage snapshot, when it is known. */
+    resourceName?: string;
+}
+export interface IBackupRestoreSnapshotUnavailableRefusal {
+    name: 'restore-snapshot-unavailable';
+    /** Non-empty; each snapshot once. */
+    missing: IBackupRestoreMissingSnapshot[];
+}
+export interface IBackupRestorePreflightUnsupportedRefusal {
+    name: 'restore-preflight-unsupported';
+}
+export interface IBackupRestoreRelayContractBehindRefusal {
+    name: 'restore-relay-contract-behind';
+    /** The interfaces release the relay speaks, or `null` when it stated none. */
+    relayInterfacesVersion: string | null;
+    /** The lowest interfaces release a relay must speak to carry a restore. */
+    minimumInterfacesVersion: string;
+}
+/** A refused restore, discriminated by `name` (`backupRestoreRefusalNames`). */
+export type TBackupRestoreRefusal = IBackupRestoreSnapshotUnavailableRefusal | IBackupRestorePreflightUnsupportedRefusal | IBackupRestoreRelayContractBehindRefusal;
+/** Validates one restore refusal against its exact schema and names every reason it is refused. */
+export declare const validateBackupRestoreRefusal: (valueArg: unknown, pathArg?: string) => string[];
+/** Whether a value is exactly one restore refusal. */
+export declare const isBackupRestoreRefusal: (valueArg: unknown) => valueArg is TBackupRestoreRefusal;
+/**
+ * The restore refusal inside an error payload or a stored restore event, as an inert frozen copy,
+ * or `null` when the value is not exactly one. It reads own data properties only, so a refusal
+ * read here carries nothing that runs.
+ */
+export declare const readBackupRestoreRefusal: (valueArg: unknown) => TBackupRestoreRefusal | null;
+/** `restore-snapshot-unavailable` naming each snapshot the node's Corestore cannot read. */
+export declare const buildBackupRestoreSnapshotUnavailableRefusal: (missingArg: IBackupRestoreMissingSnapshot[]) => IBackupRestoreSnapshotUnavailableRefusal;
+/** `restore-preflight-unsupported`: the node's Corestore offers no restore check. */
+export declare const buildBackupRestorePreflightUnsupportedRefusal: () => IBackupRestorePreflightUnsupportedRefusal;
+/**
+ * `restore-relay-contract-behind`: the relay speaks an interfaces release below the minimum.
+ *
+ * Throws when a stated version is not a release version or is not below the minimum, so a caller
+ * passes `null` for a relay whose stated version it cannot read.
+ */
+export declare const buildBackupRestoreRelayContractBehindRefusal: (relayInterfacesVersionArg: string | null, minimumInterfacesVersionArg: string) => IBackupRestoreRelayContractBehindRefusal;
+/**
+ * Validates what this contract adds to a restore event of a backup's `restoreHistory` and names
+ * every reason it is refused: `status` is `restored`, `failed` or `refused`, and `refusal` is
+ * present exactly when `status` is `refused`, as one restore refusal. Every other member is left as
+ * it was written (records Cloudly already stores keep any `restoredAt`, `errorText`, `partial` and
+ * `resourceTypes` they hold), so every stored event stays valid.
+ */
+export declare const validateBackupRestoreEvent: (valueArg: unknown, pathArg?: string) => string[];

package/dist_ts/data/backuprestorerefusal.js

@@ -0,0 +1,228 @@
+import { hasExactKeys, readDataElements, readDataProperties, readExactDataRecord, } from '../private/dataproperties.js';
+import { compareReleaseVersions, parseReleaseVersion } from './releaseversion.js';
+/**
+ * Why an in-place restore of a backup (`IReq_Any_Cloudly_RestoreServiceBackup`) was refused before
+ * it wrote anything. A restore is all-or-nothing: Corestore checks that it can read every snapshot
+ * the restore names before it replaces any data, and Cloudly dispatches the restore only to a relay
+ * whose contract carries that check. A refusal therefore always means nothing was written; the
+ * service keeps the data it had.
+ *
+ * - `restore-snapshot-unavailable`: the node's Corestore cannot read one or more snapshots the
+ *   restore names; `missing` names each of them.
+ * - `restore-preflight-unsupported`: the node's Corestore does not offer the restore check (a
+ *   Corestore built before it answers the check route with HTTP 404), so it cannot prove the
+ *   restore would be whole and nothing is restored.
+ * - `restore-relay-contract-behind`: the cluster relay speaks an interfaces release below the one
+ *   that carries the restore check, so Cloudly does not dispatch the restore; the relay states
+ *   `relayInterfacesVersion` (`null` when it stated none) and the restore needs
+ *   `minimumInterfacesVersion`.
+ *
+ * It travels as `TypedResponseError.errorData` of a refused restore and is recorded as the
+ * `refusal` of the backup's `refused` restore event (`IBackupRestoreEvent`). Each refusal is
+ * exactly its schema: `readBackupRestoreRefusal` refuses any other member, so a producer never adds
+ * one without gating it on the reader's interfaces version.
+ */
+export const backupRestoreRefusalNames = Object.freeze([
+    'restore-snapshot-unavailable',
+    'restore-preflight-unsupported',
+    'restore-relay-contract-behind',
+]);
+export const backupRestoreRefusalContract = Object.freeze({
+    /** At most this many snapshots are named in one `restore-snapshot-unavailable`. */
+    maximumMissingSnapshots: 256,
+    /** A snapshot id or resource name is printable ASCII without spaces, at most this long. */
+    maximumNameLength: 255,
+});
+/** Every resource type, keyed so a new `TBackupResourceType` member fails to compile here. */
+const backupResourceTypeKeys = Object.freeze({
+    volume: true,
+    database: true,
+    objectstorage: true,
+});
+const isBackupResourceType = (valueArg) => (typeof valueArg === 'string' && Object.hasOwn(backupResourceTypeKeys, valueArg));
+const printableNamePattern = /^[\x21-\x7e]+$/;
+const isRestoreName = (valueArg) => (typeof valueArg === 'string'
+    && valueArg.length <= backupRestoreRefusalContract.maximumNameLength
+    && printableNamePattern.test(valueArg));
+const nameRule = 'must be printable ASCII without spaces, at most '
+    + `${backupRestoreRefusalContract.maximumNameLength} characters`;
+const isRefusalName = (valueArg) => (typeof valueArg === 'string'
+    && backupRestoreRefusalNames.includes(valueArg));
+const validateMissingSnapshot = (valueArg, pathArg) => {
+    const snapshot = readDataProperties(valueArg);
+    if (snapshot === null || !hasExactKeys(snapshot, ['snapshotId', 'capability'], ['resourceName'])) {
+        return [`${pathArg} must use its exact schema`];
+    }
+    const errors = [];
+    if (!isRestoreName(snapshot.snapshotId)) {
+        errors.push(`${pathArg}.snapshotId ${nameRule}`);
+    }
+    if (!isBackupResourceType(snapshot.capability)) {
+        errors.push(`${pathArg}.capability must be volume, database or objectstorage`);
+    }
+    if (Object.hasOwn(snapshot, 'resourceName') && !isRestoreName(snapshot.resourceName)) {
+        errors.push(`${pathArg}.resourceName ${nameRule}`);
+    }
+    return errors;
+};
+const validateMissingSnapshots = (valueArg, pathArg) => {
+    const elements = readDataElements(valueArg, backupRestoreRefusalContract.maximumMissingSnapshots);
+    if (elements === null) {
+        return [`${pathArg} must be a list of at most `
+                + `${backupRestoreRefusalContract.maximumMissingSnapshots} snapshots`];
+    }
+    if (elements.length === 0) {
+        return [`${pathArg} must name at least one snapshot`];
+    }
+    const errors = elements.flatMap((elementArg, indexArg) => (validateMissingSnapshot(elementArg, `${pathArg}[${indexArg}]`)));
+    if (errors.length > 0) {
+        return errors;
+    }
+    const snapshotIds = elements.map((elementArg) => elementArg.snapshotId);
+    if (new Set(snapshotIds).size !== snapshotIds.length) {
+        errors.push(`${pathArg} must name each snapshot once`);
+    }
+    return errors;
+};
+const validateRelayContractBehind = (refusalArg, pathArg) => {
+    const relay = refusalArg.relayInterfacesVersion === null
+        ? null
+        : parseReleaseVersion(refusalArg.relayInterfacesVersion);
+    const minimum = parseReleaseVersion(refusalArg.minimumInterfacesVersion);
+    const errors = [];
+    if (refusalArg.relayInterfacesVersion !== null && relay === null) {
+        errors.push(`${pathArg} relayInterfacesVersion must be a release version or null`);
+    }
+    if (minimum === null) {
+        errors.push(`${pathArg} minimumInterfacesVersion must be a release version`);
+    }
+    if (relay !== null && minimum !== null && compareReleaseVersions(relay, minimum) >= 0) {
+        errors.push(`${pathArg} relayInterfacesVersion must be below minimumInterfacesVersion`);
+    }
+    return errors;
+};
+/** The exact keys of each refusal. */
+const refusalKeys = Object.freeze({
+    'restore-snapshot-unavailable': Object.freeze(['name', 'missing']),
+    'restore-preflight-unsupported': Object.freeze(['name']),
+    'restore-relay-contract-behind': Object.freeze([
+        'name', 'relayInterfacesVersion', 'minimumInterfacesVersion',
+    ]),
+});
+/** Validates one restore refusal against its exact schema and names every reason it is refused. */
+export const validateBackupRestoreRefusal = (valueArg, pathArg = 'backup restore refusal') => {
+    const properties = readDataProperties(valueArg);
+    if (properties === null || !isRefusalName(properties.name)) {
+        return [`${pathArg} name must be one of ${backupRestoreRefusalNames.join(', ')}`];
+    }
+    const refusal = readExactDataRecord(valueArg, refusalKeys[properties.name]);
+    if (refusal === null) {
+        return [`${pathArg} must use the exact schema of ${properties.name}`];
+    }
+    switch (properties.name) {
+        case 'restore-snapshot-unavailable':
+            return validateMissingSnapshots(refusal.missing, `${pathArg} missing`);
+        case 'restore-preflight-unsupported':
+            return [];
+        case 'restore-relay-contract-behind':
+            return validateRelayContractBehind(refusal, pathArg);
+    }
+};
+/** Whether a value is exactly one restore refusal. */
+export const isBackupRestoreRefusal = (valueArg) => (validateBackupRestoreRefusal(valueArg).length === 0);
+const freezeMissingSnapshot = (snapshotArg) => Object.freeze({
+    snapshotId: snapshotArg.snapshotId,
+    capability: snapshotArg.capability,
+    ...(snapshotArg.resourceName === undefined ? {} : { resourceName: snapshotArg.resourceName }),
+});
+const copySnapshotUnavailableRefusal = (refusalArg) => {
+    const missing = refusalArg.missing.map(freezeMissingSnapshot);
+    Object.freeze(missing);
+    return Object.freeze({ name: refusalArg.name, missing });
+};
+const copyPreflightUnsupportedRefusal = (refusalArg) => Object.freeze({ name: refusalArg.name });
+const copyRelayContractBehindRefusal = (refusalArg) => Object.freeze({
+    name: refusalArg.name,
+    relayInterfacesVersion: refusalArg.relayInterfacesVersion,
+    minimumInterfacesVersion: refusalArg.minimumInterfacesVersion,
+});
+/** An inert frozen copy of a refusal that passed `validateBackupRestoreRefusal`. */
+const copyRefusal = (refusalArg) => {
+    switch (refusalArg.name) {
+        case 'restore-snapshot-unavailable':
+            return copySnapshotUnavailableRefusal(refusalArg);
+        case 'restore-preflight-unsupported':
+            return copyPreflightUnsupportedRefusal(refusalArg);
+        case 'restore-relay-contract-behind':
+            return copyRelayContractBehindRefusal(refusalArg);
+    }
+};
+/**
+ * The restore refusal inside an error payload or a stored restore event, as an inert frozen copy,
+ * or `null` when the value is not exactly one. It reads own data properties only, so a refusal
+ * read here carries nothing that runs.
+ */
+export const readBackupRestoreRefusal = (valueArg) => (
+// A value that passed holds own data properties of exactly the refusal's schema at every level,
+// so the copy reads the same data the validation judged.
+isBackupRestoreRefusal(valueArg) ? copyRefusal(valueArg) : null);
+/** The refusal a builder composed, unchanged, or an error naming every reason it is refused. */
+const requireRefusal = (refusalArg) => {
+    const errors = validateBackupRestoreRefusal(refusalArg);
+    if (errors.length > 0) {
+        throw new Error(errors.join('; '));
+    }
+    return refusalArg;
+};
+/** `restore-snapshot-unavailable` naming each snapshot the node's Corestore cannot read. */
+export const buildBackupRestoreSnapshotUnavailableRefusal = (missingArg) => copySnapshotUnavailableRefusal(requireRefusal({
+    name: 'restore-snapshot-unavailable',
+    missing: missingArg.map((snapshotArg) => ({ ...snapshotArg })),
+}));
+/** `restore-preflight-unsupported`: the node's Corestore offers no restore check. */
+export const buildBackupRestorePreflightUnsupportedRefusal = () => (copyPreflightUnsupportedRefusal(requireRefusal({ name: 'restore-preflight-unsupported' })));
+/**
+ * `restore-relay-contract-behind`: the relay speaks an interfaces release below the minimum.
+ *
+ * Throws when a stated version is not a release version or is not below the minimum, so a caller
+ * passes `null` for a relay whose stated version it cannot read.
+ */
+export const buildBackupRestoreRelayContractBehindRefusal = (relayInterfacesVersionArg, minimumInterfacesVersionArg) => copyRelayContractBehindRefusal(requireRefusal({
+    name: 'restore-relay-contract-behind',
+    relayInterfacesVersion: relayInterfacesVersionArg,
+    minimumInterfacesVersion: minimumInterfacesVersionArg,
+}));
+const restoreEventStatuses = Object.freeze([
+    'restored', 'failed', 'refused',
+]);
+/**
+ * Validates what this contract adds to a restore event of a backup's `restoreHistory` and names
+ * every reason it is refused: `status` is `restored`, `failed` or `refused`, and `refusal` is
+ * present exactly when `status` is `refused`, as one restore refusal. Every other member is left as
+ * it was written (records Cloudly already stores keep any `restoredAt`, `errorText`, `partial` and
+ * `resourceTypes` they hold), so every stored event stays valid.
+ */
+export const validateBackupRestoreEvent = (valueArg, pathArg = 'backup restore event') => {
+    const event = readDataProperties(valueArg);
+    if (event === null) {
+        return [`${pathArg} must be a plain record of data properties`];
+    }
+    const errors = [];
+    if (!restoreEventStatuses.includes(event.status)) {
+        errors.push(`${pathArg} status must be one of ${restoreEventStatuses.join(', ')}`);
+    }
+    const hasRefusal = Object.hasOwn(event, 'refusal');
+    if (event.status === 'refused') {
+        if (!hasRefusal) {
+            errors.push(`${pathArg} refusal is required when status is refused`);
+        }
+        else {
+            errors.push(...validateBackupRestoreRefusal(event.refusal, `${pathArg} refusal`));
+        }
+    }
+    else if (hasRefusal) {
+        errors.push(`${pathArg} refusal is allowed only when status is refused`);
+    }
+    return errors;
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYmFja3VwcmVzdG9yZXJlZnVzYWwuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2JhY2t1cHJlc3RvcmVyZWZ1c2FsLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUNBLE9BQU8sRUFDTCxZQUFZLEVBQUUsZ0JBQWdCLEVBQUUsa0JBQWtCLEVBQUUsbUJBQW1CLEdBQ3hFLE1BQU0sOEJBQThCLENBQUM7QUFDdEMsT0FBTyxFQUFFLHNCQUFzQixFQUFFLG1CQUFtQixFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFFbEY7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXFCRztBQUNILE1BQU0sQ0FBQyxNQUFNLHlCQUF5QixHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQUM7SUFDckQsOEJBQThCO0lBQzlCLCtCQUErQjtJQUMvQiwrQkFBK0I7Q0FDdkIsQ0FBQyxDQUFDO0FBSVosTUFBTSxDQUFDLE1BQU0sNEJBQTRCLEdBQUcsTUFBTSxDQUFDLE1BQU0sQ0FBQztJQUN4RCxtRkFBbUY7SUFDbkYsdUJBQXVCLEVBQUUsR0FBRztJQUM1QiwyRkFBMkY7SUFDM0YsaUJBQWlCLEVBQUUsR0FBRztDQUNkLENBQUMsQ0FBQztBQW1DWiw4RkFBOEY7QUFDOUYsTUFBTSxzQkFBc0IsR0FBZ0QsTUFBTSxDQUFDLE1BQU0sQ0FBQztJQUN4RixNQUFNLEVBQUUsSUFBSTtJQUNaLFFBQVEsRUFBRSxJQUFJO0lBQ2QsYUFBYSxFQUFFLElBQUk7Q0FDcEIsQ0FBQyxDQUFDO0FBRUgsTUFBTSxvQkFBb0IsR0FBRyxDQUFDLFFBQWlCLEVBQW1DLEVBQUUsQ0FBQyxDQUNuRixPQUFPLFFBQVEsS0FBSyxRQUFRLElBQUksTUFBTSxDQUFDLE1BQU0sQ0FBQyxzQkFBc0IsRUFBRSxRQUFRLENBQUMsQ0FDaEYsQ0FBQztBQUVGLE1BQU0sb0JBQW9CLEdBQUcsZ0JBQWdCLENBQUM7QUFFOUMsTUFBTSxhQUFhLEdBQUcsQ0FBQyxRQUFpQixFQUFzQixFQUFFLENBQUMs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

package/dist_ts/data/index.d.ts

@@ -75,6 +75,7 @@ export * from './secret.js';
 export * from './baremetal.js';
 export * from './baseos.js';
 export * from './backup.js';
+export * from './backuprestorerefusal.js';
 export * from './clusternode.js';
 export * from './clusternodehostname.js';
 export * from './settings.js';

package/dist_ts/data/index.js

@@ -70,6 +70,7 @@ export * from './secret.js';
 export * from './baremetal.js';
 export * from './baseos.js';
 export * from './backup.js';
+export * from './backuprestorerefusal.js';
 export * from './clusternode.js';
 export * from './clusternodehostname.js';
 export * from './settings.js';
@@ -91,4 +92,4 @@ export * from './user.js';
 export * from './version.js';
 export * from './webpush.js';
 export * from './workloadreplicaidentity.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxnQ0FBZ0MsQ0FBQztBQUMvQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyw0QkFBNEIsQ0FBQztBQUMzQyxjQUFjLDhCQUE4QixDQUFDO0FBQzdDLGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYyw2QkFBNkIsQ0FBQztBQUM1QyxjQUFjLDRCQUE0QixDQUFDO0FBQzNDLGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYywwQkFBMEIsQ0FBQztBQUN6QyxjQUFjLGdDQUFnQyxDQUFDO0FBQy9DLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxVQUFVLENBQUM7QUFDekIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsNkJBQTZCLENBQUM7QUFDNUMsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLHlCQUF5QixDQUFDO0FBQ3hDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLHdCQUF3QixDQUFDO0FBQ3ZDLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyw4QkFBOEIsQ0FBQztBQUM3QyxjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyx3QkFBd0IsQ0FBQztBQUl2QyxPQUFPLEVBQUUsMEJBQTBCLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUc5RCxPQUFPLEVBQUUscUNBQXFDLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUVwRixPQUFPLEVBQUUsMENBQTBDLEVBQUUsMENBQTBDLEVBQUUsTUFBTSxrQ0FBa0MsQ0FBQztBQUMxSSxjQUFjLHdCQUF3QixDQUFDO0FBQ3ZDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsd0JBQXdCLENBQUM7QUFDdkMsY0FBYyw0QkFBNEIsQ0FBQztBQUMzQyxjQUFjLDRCQUE0QixDQUFDO0FBQzNDLGNBQWMsNkJBQTZCLENBQUM7QUFDNUMsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMsK0JBQStCLENBQUM7QUFDOUMsY0FBYyxnQ0FBZ0MsQ0FBQztBQUMvQyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYyw0QkFBNEIsQ0FBQztBQUMzQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsNEJBQTRCLENBQUM7QUFDM0MsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyx3QkFBd0IsQ0FBQztBQUN2QyxjQUFjLCtCQUErQixDQUFDO0FBQzlDLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMsa0NBQWtDLENBQUM7QUFDakQsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLDhCQUE4QixDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxnQ0FBZ0MsQ0FBQztBQUMvQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyw0QkFBNEIsQ0FBQztBQUMzQyxjQUFjLDhCQUE4QixDQUFDO0FBQzdDLGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYyw2QkFBNkIsQ0FBQztBQUM1QyxjQUFjLDRCQUE0QixDQUFDO0FBQzNDLGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYywwQkFBMEIsQ0FBQztBQUN6QyxjQUFjLGdDQUFnQyxDQUFDO0FBQy9DLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxVQUFVLENBQUM7QUFDekIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsNkJBQTZCLENBQUM7QUFDNUMsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLHlCQUF5QixDQUFDO0FBQ3hDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLHdCQUF3QixDQUFDO0FBQ3ZDLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyw4QkFBOEIsQ0FBQztBQUM3QyxjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyx3QkFBd0IsQ0FBQztBQUl2QyxPQUFPLEVBQUUsMEJBQTBCLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUc5RCxPQUFPLEVBQUUscUNBQXFDLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUVwRixPQUFPLEVBQUUsMENBQTBDLEVBQUUsMENBQTBDLEVBQUUsTUFBTSxrQ0FBa0MsQ0FBQztBQUMxSSxjQUFjLHdCQUF3QixDQUFDO0FBQ3ZDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsd0JBQXdCLENBQUM7QUFDdkMsY0FBYyw0QkFBNEIsQ0FBQztBQUMzQyxjQUFjLDRCQUE0QixDQUFDO0FBQzNDLGNBQWMsNkJBQTZCLENBQUM7QUFDNUMsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMsK0JBQStCLENBQUM7QUFDOUMsY0FBYyxnQ0FBZ0MsQ0FBQztBQUMvQyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYyw0QkFBNEIsQ0FBQztBQUMzQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYywyQkFBMkIsQ0FBQztBQUMxQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyw0QkFBNEIsQ0FBQztBQUMzQyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsaUJBQWlCLENBQUM7QUFDaEMsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLHdCQUF3QixDQUFDO0FBQ3ZDLGNBQWMsK0JBQStCLENBQUM7QUFDOUMsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYyxrQ0FBa0MsQ0FBQztBQUNqRCxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsOEJBQThCLENBQUMifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "32.70.0",
+  "version": "32.71.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '32.70.0',
+  version: '32.71.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/data/backup.ts

@@ -1,3 +1,4 @@
+import type { TBackupRestoreRefusal } from './backuprestorerefusal.js';
 import type { ICorestoreDatabaseAllocationReference } from './corestore.js';
 
 export type TBackupStatus =
@@ -101,9 +102,17 @@ export type TBackupFailure =
   | { kind: 'incomplete'; uncaptured: TBackupUncapturedResource[] }
   | { kind: 'archive-unreadable' };
 
+/**
+ * One restore of a backup, appended to its `restoreHistory`; `validateBackupRestoreEvent` judges its
+ * `status` and `refusal`.
+ *
+ * `refused`: the restore was refused before it wrote anything (`refusal` says why), so the service
+ * keeps the data it had. `failed`: it failed after it began writing.
+ */
 export interface IBackupRestoreEvent {
+  /** When the restore ended, or when it was refused. */
   restoredAt: number;
-  status: 'restored' | 'failed';
+  status: 'restored' | 'failed' | 'refused';
   errorText?: string;
   /** The resource types the restore was limited to; absent when it restored every snapshot. */
   resourceTypes?: TBackupResourceType[];
@@ -112,6 +121,8 @@ export interface IBackupRestoreEvent {
    * none of the backup's `failure.uncaptured`.
    */
   partial?: true;
+  /** Why a `refused` restore wrote nothing; present exactly when `status` is `refused`. */
+  refusal?: TBackupRestoreRefusal;
 }
 
 /**

package/ts/data/backuprestorerefusal.ts

@@ -0,0 +1,324 @@
+import type { IBackupRestoreEvent, TBackupResourceType } from './backup.js';
+import {
+  hasExactKeys, readDataElements, readDataProperties, readExactDataRecord,
+} from '../private/dataproperties.js';
+import { compareReleaseVersions, parseReleaseVersion } from './releaseversion.js';
+
+/**
+ * Why an in-place restore of a backup (`IReq_Any_Cloudly_RestoreServiceBackup`) was refused before
+ * it wrote anything. A restore is all-or-nothing: Corestore checks that it can read every snapshot
+ * the restore names before it replaces any data, and Cloudly dispatches the restore only to a relay
+ * whose contract carries that check. A refusal therefore always means nothing was written; the
+ * service keeps the data it had.
+ *
+ * - `restore-snapshot-unavailable`: the node's Corestore cannot read one or more snapshots the
+ *   restore names; `missing` names each of them.
+ * - `restore-preflight-unsupported`: the node's Corestore does not offer the restore check (a
+ *   Corestore built before it answers the check route with HTTP 404), so it cannot prove the
+ *   restore would be whole and nothing is restored.
+ * - `restore-relay-contract-behind`: the cluster relay speaks an interfaces release below the one
+ *   that carries the restore check, so Cloudly does not dispatch the restore; the relay states
+ *   `relayInterfacesVersion` (`null` when it stated none) and the restore needs
+ *   `minimumInterfacesVersion`.
+ *
+ * It travels as `TypedResponseError.errorData` of a refused restore and is recorded as the
+ * `refusal` of the backup's `refused` restore event (`IBackupRestoreEvent`). Each refusal is
+ * exactly its schema: `readBackupRestoreRefusal` refuses any other member, so a producer never adds
+ * one without gating it on the reader's interfaces version.
+ */
+export const backupRestoreRefusalNames = Object.freeze([
+  'restore-snapshot-unavailable',
+  'restore-preflight-unsupported',
+  'restore-relay-contract-behind',
+] as const);
+
+export type TBackupRestoreRefusalName = typeof backupRestoreRefusalNames[number];
+
+export const backupRestoreRefusalContract = Object.freeze({
+  /** At most this many snapshots are named in one `restore-snapshot-unavailable`. */
+  maximumMissingSnapshots: 256,
+  /** A snapshot id or resource name is printable ASCII without spaces, at most this long. */
+  maximumNameLength: 255,
+} as const);
+
+/** One snapshot a restore names that the node's Corestore cannot read. */
+export interface IBackupRestoreMissingSnapshot {
+  snapshotId: string;
+  /** The snapshot's resource type (`TBackupSnapshot['type']`). */
+  capability: TBackupResourceType;
+  /** The Corestore resource of a database or object-storage snapshot, when it is known. */
+  resourceName?: string;
+}
+
+export interface IBackupRestoreSnapshotUnavailableRefusal {
+  name: 'restore-snapshot-unavailable';
+  /** Non-empty; each snapshot once. */
+  missing: IBackupRestoreMissingSnapshot[];
+}
+
+export interface IBackupRestorePreflightUnsupportedRefusal {
+  name: 'restore-preflight-unsupported';
+}
+
+export interface IBackupRestoreRelayContractBehindRefusal {
+  name: 'restore-relay-contract-behind';
+  /** The interfaces release the relay speaks, or `null` when it stated none. */
+  relayInterfacesVersion: string | null;
+  /** The lowest interfaces release a relay must speak to carry a restore. */
+  minimumInterfacesVersion: string;
+}
+
+/** A refused restore, discriminated by `name` (`backupRestoreRefusalNames`). */
+export type TBackupRestoreRefusal =
+  | IBackupRestoreSnapshotUnavailableRefusal
+  | IBackupRestorePreflightUnsupportedRefusal
+  | IBackupRestoreRelayContractBehindRefusal;
+
+/** Every resource type, keyed so a new `TBackupResourceType` member fails to compile here. */
+const backupResourceTypeKeys: Readonly<Record<TBackupResourceType, true>> = Object.freeze({
+  volume: true,
+  database: true,
+  objectstorage: true,
+});
+
+const isBackupResourceType = (valueArg: unknown): valueArg is TBackupResourceType => (
+  typeof valueArg === 'string' && Object.hasOwn(backupResourceTypeKeys, valueArg)
+);
+
+const printableNamePattern = /^[\x21-\x7e]+$/;
+
+const isRestoreName = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string'
+  && valueArg.length <= backupRestoreRefusalContract.maximumNameLength
+  && printableNamePattern.test(valueArg)
+);
+
+const nameRule = 'must be printable ASCII without spaces, at most '
+  + `${backupRestoreRefusalContract.maximumNameLength} characters`;
+
+const isRefusalName = (valueArg: unknown): valueArg is TBackupRestoreRefusalName => (
+  typeof valueArg === 'string'
+  && (backupRestoreRefusalNames as readonly string[]).includes(valueArg)
+);
+
+const validateMissingSnapshot = (valueArg: unknown, pathArg: string): string[] => {
+  const snapshot = readDataProperties(valueArg);
+  if (snapshot === null || !hasExactKeys(snapshot, ['snapshotId', 'capability'], ['resourceName'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  if (!isRestoreName(snapshot.snapshotId)) {
+    errors.push(`${pathArg}.snapshotId ${nameRule}`);
+  }
+  if (!isBackupResourceType(snapshot.capability)) {
+    errors.push(`${pathArg}.capability must be volume, database or objectstorage`);
+  }
+  if (Object.hasOwn(snapshot, 'resourceName') && !isRestoreName(snapshot.resourceName)) {
+    errors.push(`${pathArg}.resourceName ${nameRule}`);
+  }
+  return errors;
+};
+
+const validateMissingSnapshots = (valueArg: unknown, pathArg: string): string[] => {
+  const elements = readDataElements(valueArg, backupRestoreRefusalContract.maximumMissingSnapshots);
+  if (elements === null) {
+    return [`${pathArg} must be a list of at most `
+      + `${backupRestoreRefusalContract.maximumMissingSnapshots} snapshots`];
+  }
+  if (elements.length === 0) {
+    return [`${pathArg} must name at least one snapshot`];
+  }
+  const errors = elements.flatMap((elementArg, indexArg) => (
+    validateMissingSnapshot(elementArg, `${pathArg}[${indexArg}]`)
+  ));
+  if (errors.length > 0) {
+    return errors;
+  }
+  const snapshotIds = elements.map((elementArg) => (elementArg as IBackupRestoreMissingSnapshot).snapshotId);
+  if (new Set(snapshotIds).size !== snapshotIds.length) {
+    errors.push(`${pathArg} must name each snapshot once`);
+  }
+  return errors;
+};
+
+const validateRelayContractBehind = (
+  refusalArg: Record<string, unknown>,
+  pathArg: string,
+): string[] => {
+  const relay = refusalArg.relayInterfacesVersion === null
+    ? null
+    : parseReleaseVersion(refusalArg.relayInterfacesVersion);
+  const minimum = parseReleaseVersion(refusalArg.minimumInterfacesVersion);
+  const errors: string[] = [];
+  if (refusalArg.relayInterfacesVersion !== null && relay === null) {
+    errors.push(`${pathArg} relayInterfacesVersion must be a release version or null`);
+  }
+  if (minimum === null) {
+    errors.push(`${pathArg} minimumInterfacesVersion must be a release version`);
+  }
+  if (relay !== null && minimum !== null && compareReleaseVersions(relay, minimum) >= 0) {
+    errors.push(`${pathArg} relayInterfacesVersion must be below minimumInterfacesVersion`);
+  }
+  return errors;
+};
+
+/** The exact keys of each refusal. */
+const refusalKeys: Readonly<Record<TBackupRestoreRefusalName, readonly string[]>> = Object.freeze({
+  'restore-snapshot-unavailable': Object.freeze(['name', 'missing']),
+  'restore-preflight-unsupported': Object.freeze(['name']),
+  'restore-relay-contract-behind': Object.freeze([
+    'name', 'relayInterfacesVersion', 'minimumInterfacesVersion',
+  ]),
+});
+
+/** Validates one restore refusal against its exact schema and names every reason it is refused. */
+export const validateBackupRestoreRefusal = (
+  valueArg: unknown,
+  pathArg = 'backup restore refusal',
+): string[] => {
+  const properties = readDataProperties(valueArg);
+  if (properties === null || !isRefusalName(properties.name)) {
+    return [`${pathArg} name must be one of ${backupRestoreRefusalNames.join(', ')}`];
+  }
+  const refusal = readExactDataRecord(valueArg, refusalKeys[properties.name]);
+  if (refusal === null) {
+    return [`${pathArg} must use the exact schema of ${properties.name}`];
+  }
+  switch (properties.name) {
+    case 'restore-snapshot-unavailable':
+      return validateMissingSnapshots(refusal.missing, `${pathArg} missing`);
+    case 'restore-preflight-unsupported':
+      return [];
+    case 'restore-relay-contract-behind':
+      return validateRelayContractBehind(refusal, pathArg);
+  }
+};
+
+/** Whether a value is exactly one restore refusal. */
+export const isBackupRestoreRefusal = (valueArg: unknown): valueArg is TBackupRestoreRefusal => (
+  validateBackupRestoreRefusal(valueArg).length === 0
+);
+
+const freezeMissingSnapshot = (
+  snapshotArg: IBackupRestoreMissingSnapshot,
+): IBackupRestoreMissingSnapshot => Object.freeze({
+  snapshotId: snapshotArg.snapshotId,
+  capability: snapshotArg.capability,
+  ...(snapshotArg.resourceName === undefined ? {} : { resourceName: snapshotArg.resourceName }),
+});
+
+const copySnapshotUnavailableRefusal = (
+  refusalArg: IBackupRestoreSnapshotUnavailableRefusal,
+): IBackupRestoreSnapshotUnavailableRefusal => {
+  const missing = refusalArg.missing.map(freezeMissingSnapshot);
+  Object.freeze(missing);
+  return Object.freeze({ name: refusalArg.name, missing });
+};
+
+const copyPreflightUnsupportedRefusal = (
+  refusalArg: IBackupRestorePreflightUnsupportedRefusal,
+): IBackupRestorePreflightUnsupportedRefusal => Object.freeze({ name: refusalArg.name });
+
+const copyRelayContractBehindRefusal = (
+  refusalArg: IBackupRestoreRelayContractBehindRefusal,
+): IBackupRestoreRelayContractBehindRefusal => Object.freeze({
+  name: refusalArg.name,
+  relayInterfacesVersion: refusalArg.relayInterfacesVersion,
+  minimumInterfacesVersion: refusalArg.minimumInterfacesVersion,
+});
+
+/** An inert frozen copy of a refusal that passed `validateBackupRestoreRefusal`. */
+const copyRefusal = (refusalArg: TBackupRestoreRefusal): TBackupRestoreRefusal => {
+  switch (refusalArg.name) {
+    case 'restore-snapshot-unavailable':
+      return copySnapshotUnavailableRefusal(refusalArg);
+    case 'restore-preflight-unsupported':
+      return copyPreflightUnsupportedRefusal(refusalArg);
+    case 'restore-relay-contract-behind':
+      return copyRelayContractBehindRefusal(refusalArg);
+  }
+};
+
+/**
+ * The restore refusal inside an error payload or a stored restore event, as an inert frozen copy,
+ * or `null` when the value is not exactly one. It reads own data properties only, so a refusal
+ * read here carries nothing that runs.
+ */
+export const readBackupRestoreRefusal = (valueArg: unknown): TBackupRestoreRefusal | null => (
+  // A value that passed holds own data properties of exactly the refusal's schema at every level,
+  // so the copy reads the same data the validation judged.
+  isBackupRestoreRefusal(valueArg) ? copyRefusal(valueArg) : null
+);
+
+/** The refusal a builder composed, unchanged, or an error naming every reason it is refused. */
+const requireRefusal = <T extends TBackupRestoreRefusal>(refusalArg: T): T => {
+  const errors = validateBackupRestoreRefusal(refusalArg);
+  if (errors.length > 0) {
+    throw new Error(errors.join('; '));
+  }
+  return refusalArg;
+};
+
+/** `restore-snapshot-unavailable` naming each snapshot the node's Corestore cannot read. */
+export const buildBackupRestoreSnapshotUnavailableRefusal = (
+  missingArg: IBackupRestoreMissingSnapshot[],
+): IBackupRestoreSnapshotUnavailableRefusal => copySnapshotUnavailableRefusal(requireRefusal({
+  name: 'restore-snapshot-unavailable',
+  missing: missingArg.map((snapshotArg) => ({ ...snapshotArg })),
+}));
+
+/** `restore-preflight-unsupported`: the node's Corestore offers no restore check. */
+export const buildBackupRestorePreflightUnsupportedRefusal = (): IBackupRestorePreflightUnsupportedRefusal => (
+  copyPreflightUnsupportedRefusal(requireRefusal({ name: 'restore-preflight-unsupported' }))
+);
+
+/**
+ * `restore-relay-contract-behind`: the relay speaks an interfaces release below the minimum.
+ *
+ * Throws when a stated version is not a release version or is not below the minimum, so a caller
+ * passes `null` for a relay whose stated version it cannot read.
+ */
+export const buildBackupRestoreRelayContractBehindRefusal = (
+  relayInterfacesVersionArg: string | null,
+  minimumInterfacesVersionArg: string,
+): IBackupRestoreRelayContractBehindRefusal => copyRelayContractBehindRefusal(requireRefusal({
+  name: 'restore-relay-contract-behind',
+  relayInterfacesVersion: relayInterfacesVersionArg,
+  minimumInterfacesVersion: minimumInterfacesVersionArg,
+}));
+
+const restoreEventStatuses: readonly IBackupRestoreEvent['status'][] = Object.freeze([
+  'restored', 'failed', 'refused',
+]);
+
+/**
+ * Validates what this contract adds to a restore event of a backup's `restoreHistory` and names
+ * every reason it is refused: `status` is `restored`, `failed` or `refused`, and `refusal` is
+ * present exactly when `status` is `refused`, as one restore refusal. Every other member is left as
+ * it was written (records Cloudly already stores keep any `restoredAt`, `errorText`, `partial` and
+ * `resourceTypes` they hold), so every stored event stays valid.
+ */
+export const validateBackupRestoreEvent = (
+  valueArg: unknown,
+  pathArg = 'backup restore event',
+): string[] => {
+  const event = readDataProperties(valueArg);
+  if (event === null) {
+    return [`${pathArg} must be a plain record of data properties`];
+  }
+  const errors: string[] = [];
+  if (!(restoreEventStatuses as readonly unknown[]).includes(event.status)) {
+    errors.push(`${pathArg} status must be one of ${restoreEventStatuses.join(', ')}`);
+  }
+  const hasRefusal = Object.hasOwn(event, 'refusal');
+  if (event.status === 'refused') {
+    if (!hasRefusal) {
+      errors.push(`${pathArg} refusal is required when status is refused`);
+    } else {
+      errors.push(...validateBackupRestoreRefusal(event.refusal, `${pathArg} refusal`));
+    }
+  } else if (hasRefusal) {
+    errors.push(`${pathArg} refusal is allowed only when status is refused`);
+  }
+  return errors;
+};

package/ts/data/index.ts

@@ -76,6 +76,7 @@ export * from './secret.js';
 export * from './baremetal.js';
 export * from './baseos.js';
 export * from './backup.js';
+export * from './backuprestorerefusal.js';
 export * from './clusternode.js';
 export * from './clusternodehostname.js';
 export * from './settings.js';