@serve.zone/interfaces 32.56.0 → 32.58.0

package/dist_ts/data/runtimesessionrefusal.js

@@ -0,0 +1,127 @@
+import { readExactDataRecord } from '../private/dataproperties.js';
+/**
+ * The refusal a controller states when it does not take a node's runtime session request.
+ *
+ * It travels as `TypedResponseError.errorData` on `registerPalletRuntimeSession` and on every
+ * session-scoped read and report a node sends its controller. `code` is a frozen wire value.
+ * `momentaryReasons` are the controller's own momentary state, not a judgement of the node: a
+ * registering node waits and offers the same registration again, keeping everything it runs.
+ * Every other reason, and an error that carries no such payload, is a verdict — on a registration
+ * it ends the node's session. Momentary against verdict governs only whether a node defers a
+ * registration: a node retries its session reads and reports regardless of the reason, so the
+ * reasons a report is refused with (`state-conflict`, `*-write-conflict`, a capacity limit such as
+ * `log-intake-saturated`) are unchanged by this contract.
+ *
+ * Who states which reason today, on a registration (Cloudly ≥33.19.1, `isBudgetRefusal`):
+ * - Cloudly states `controller-deadline` when the request ran out of
+ *   `runtimeSessionRequestBounds.controllerBudgetMs`, and `controller-unavailable` when it is
+ *   stopping. Every other failure, a transient one of its own included, is answered without a
+ *   payload and so reads as a verdict.
+ * - No relay states a refusal of its own yet.
+ *
+ * The rule producers adopt:
+ * - Cloudly states `controller-unavailable` on a registration for every transient failure of its
+ *   own: its database connection lost or unavailable, a registration write conflict, a race with a
+ *   credential being applied.
+ * - A relay states only `controller-unavailable`, and only when it cannot carry the request or its
+ *   answer: no Cloudly link, or its own bound (`runtimeSessionRequestBounds`) ran out. Every
+ *   answer Cloudly gave it forwards untouched; it never states a verdict or `controller-deadline`.
+ * - A verdict names the check that refused: a revoked or inactive credential, a deleted, retiring
+ *   or foreign node, an invalid body. It never carries a momentary reason.
+ *
+ * The payload is exactly `{ code, reason }`. Pallet 36.3.14 reads the two members and tolerates
+ * others, but every reader built on `readRuntimeSessionRefusal` refuses a payload with any other
+ * member, and a refused payload reads as no refusal — a momentary refusal would turn into a
+ * verdict. A producer therefore never adds a member without gating it on the peer's spoken
+ * interfaces version.
+ */
+export const runtimeSessionRefusalContract = Object.freeze({
+    code: 'runtime-session-report-refused',
+    momentaryReasons: Object.freeze(['controller-deadline', 'controller-unavailable']),
+    /**
+     * A reason is one or more words of lowercase ASCII letters joined by single hyphens, at most
+     * this many characters. It names a check, never a value: no digit, case, dot, colon or other
+     * separator can carry an identifier, address, digest, count or credential across.
+     */
+    maximumReasonLength: 64,
+});
+const isRefusalReason = (valueArg) => (typeof valueArg === 'string'
+    && valueArg.length <= runtimeSessionRefusalContract.maximumReasonLength
+    && /^[a-z]+(?:-[a-z]+)*$/.test(valueArg));
+const reasonRule = 'must be lowercase letter words joined by single hyphens, at most '
+    + `${runtimeSessionRefusalContract.maximumReasonLength} characters`;
+/** Validates one runtime session refusal and names every reason it is refused. */
+export const validateRuntimeSessionRefusal = (valueArg, pathArg = 'runtime session refusal') => {
+    const refusal = readExactDataRecord(valueArg, ['code', 'reason']);
+    if (refusal === null) {
+        return [`${pathArg} must use its exact schema`];
+    }
+    const errors = [];
+    if (refusal.code !== runtimeSessionRefusalContract.code) {
+        errors.push(`${pathArg} code must be ${runtimeSessionRefusalContract.code}`);
+    }
+    if (!isRefusalReason(refusal.reason)) {
+        errors.push(`${pathArg} reason ${reasonRule}`);
+    }
+    return errors;
+};
+/** The payload a controller or relay answers a refused request with; throws on a non-word reason. */
+export const buildRuntimeSessionRefusal = (reasonArg) => {
+    if (!isRefusalReason(reasonArg)) {
+        throw new Error(`runtime session refusal reason ${reasonRule}`);
+    }
+    return Object.freeze({ code: runtimeSessionRefusalContract.code, reason: reasonArg });
+};
+/**
+ * The refusal inside an error payload, or `null` when the value is not exactly one.
+ *
+ * It reads a value that survived serialization, the way `protocol.readProtocolRefusal` does: own
+ * data properties only, exactly `code` and `reason`, nothing that runs.
+ */
+export const readRuntimeSessionRefusal = (valueArg) => {
+    const refusal = readExactDataRecord(valueArg, ['code', 'reason']);
+    if (refusal === null || validateRuntimeSessionRefusal(refusal).length > 0) {
+        return null;
+    }
+    return Object.freeze({ code: runtimeSessionRefusalContract.code, reason: refusal.reason });
+};
+/**
+ * The momentary reason an error payload states, or `null` when it is a verdict: any other reason,
+ * a payload that is not exactly a refusal, or no payload at all.
+ */
+export const readMomentaryRuntimeSessionRefusal = (valueArg) => {
+    const refusal = readRuntimeSessionRefusal(valueArg);
+    if (refusal === null) {
+        return null;
+    }
+    const momentary = runtimeSessionRefusalContract.momentaryReasons
+        .find((reasonArg) => reasonArg === refusal.reason);
+    return momentary ?? null;
+};
+/**
+ * How long each hop may hold a node's runtime session request, so the hop nearest the decision
+ * answers first and the node always reads a stated refusal rather than its own timeout.
+ */
+export const runtimeSessionRequestBounds = Object.freeze({
+    /**
+     * Cloudly's budget for every node request, registration included. When it runs out Cloudly
+     * answers `controller-deadline`.
+     */
+    controllerBudgetMs: 6_000,
+    /**
+     * A relay's bound on a registration, from its arrival at the relay to the answer, including any
+     * wait for the relay's own Cloudly link. It exceeds `controllerBudgetMs` by more than a second so
+     * Cloudly's own `controller-deadline` reaches the node through the relay, and stays below
+     * TypedSocket's 10 s connection-restore deadline (`TYPEDSOCKET_MAX_CONNECTION_RESTORE_TIMEOUT_MS`,
+     * which a client can only lower) so the node reads an answer before its restore hook times out.
+     * When it runs out the relay answers `controller-unavailable`.
+     */
+    relayRegistrationBudgetMs: 9_000,
+    /**
+     * A relay's bound on forwarding a session read or report over its established Cloudly link.
+     * It exceeds `controllerBudgetMs` so Cloudly's answer arrives first; when it runs out the relay
+     * answers `controller-unavailable`.
+     */
+    relaySessionForwardMs: 8_000,
+});
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicnVudGltZXNlc3Npb25yZWZ1c2FsLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9ydW50aW1lc2Vzc2lvbnJlZnVzYWwudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLG1CQUFtQixFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFFbkU7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBbUNHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sNkJBQTZCLEdBQUcsTUFBTSxDQUFDLE1BQU0sQ0FBQztJQUN6RCxJQUFJLEVBQUUsZ0NBQWdDO0lBQ3RDLGdCQUFnQixFQUFFLE1BQU0sQ0FBQyxNQUFNLENBQUMsQ0FBQyxxQkFBcUIsRUFBRSx3QkFBd0IsQ0FBVSxDQUFDO0lBQzNGOzs7O09BSUc7SUFDSCxtQkFBbUIsRUFBRSxFQUFFO0NBQ2YsQ0FBQyxDQUFDO0FBY1osTUFBTSxlQUFlLEdBQUcsQ0FBQyxRQUFpQixFQUFzQixFQUFFLENBQUMsQ0FDakUsT0FBTyxRQUFRLEtBQUssUUFBUTtPQUN6QixRQUFRLENBQUMsTUFBTSxJQUFJLDZCQUE2QixDQUFDLG1CQUFtQjtPQUNwRSxzQkFBc0IsQ0FBQyxJQUFJLENBQUMsUUFBUSxDQUFDLENBQ3pDLENBQUM7QUFFRixNQUFNLFVBQVUsR0FBRyxtRUFBbUU7TUFDbEYsR0FBRyw2QkFBNkIsQ0FBQyxtQkFBbUIsYUFBYSxDQUFDO0FBRXRFLGtGQUFrRjtBQUNsRixNQUFNLENBQUMsTUFBTSw2QkFBNkIsR0FBRyxDQUMzQyxRQUFpQixFQUNqQixPQUFPLEdBQUcseUJBQXlCLEVBQ3pCLEVBQUU7SUFDWixNQUFNLE9BQU8sR0FBRyxtQkFBbUIsQ0FBQyxRQUFRLEVBQUUsQ0FBQyxNQUFNLEVBQUUsUUFBUSxDQUFDLENBQUMsQ0FBQztJQUNsRSxJQUFJLE9BQU8sS0FBSyxJQUFJLEVBQUUsQ0FBQztRQUNyQixPQUFPLENBQUMsR0FBRyxPQUFPLDRCQUE0QixD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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "32.56.0",
+  "version": "32.58.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {
@@ -30,8 +30,8 @@
     "@git.zone/tsbuild": "^6.0.2",
     "@git.zone/tsdoc": "^3.0.2",
     "@git.zone/tsrun": "^3.0.3",
-    "@git.zone/tstest": "^7.2.1",
-    "@types/node": "26.6.4",
+    "@git.zone/tstest": "^8.0.0",
+    "@types/node": "26.6.5",
     "typescript": "^6.0.3"
   },
   "files": [

package/readme.md

@@ -1452,6 +1452,64 @@ carries the same offer, judged in the same order before the JWT, and answers wit
 the server's own offer. Both registration methods reject HTTP transport. Sensitive requests and registry
 responses must be excluded from hooks, logs, diagnostics and durable journals.
 
+### Runtime Session Refusals
+
+A controller that does not take a node's registration, session read or report
+answers `TypedResponseError` with `data.IRuntimeSessionRefusal` as its
+`errorData`: exactly `{ code: 'runtime-session-report-refused', reason }`
+(`data.runtimeSessionRefusalContract.code`, a frozen wire value). The reason is a
+word naming the check that refused, never a value: lowercase ASCII letter words
+joined by single hyphens, at most 64 characters
+(`runtimeSessionRefusalContract.maximumReasonLength`), so no identifier, address,
+digest, count or credential can cross in it.
+
+Two reasons are the controller's own momentary state
+(`runtimeSessionRefusalContract.momentaryReasons`): a registering node waits and
+offers the same registration again, keeping what it runs. Every other reason,
+and an error without this payload, is a verdict; on a registration it ends the
+node's session. Momentary against verdict governs only whether a node defers a
+registration: a node retries its session reads and reports regardless of the
+reason, so the reasons a report is refused with (`state-conflict`,
+`*-write-conflict`, a capacity limit such as `log-intake-saturated`) are
+unchanged by this contract.
+
+On a registration today (Cloudly ≥33.19.1), Cloudly attaches the payload only
+when the refusal is no judgement of the node: its budget ran out
+(`controller-deadline`) or it is stopping (`controller-unavailable`). Every
+other failure, a transient one of its own included, is answered without a
+payload and so reads as a verdict. No relay states a refusal of its own yet.
+
+The rule producers adopt:
+
+| Reason | Stated by | When |
+| --- | --- | --- |
+| `controller-deadline` | Cloudly | the request ran out of `controllerBudgetMs` (stated today) |
+| `controller-unavailable` | Cloudly | it is stopping (stated today); any other transient failure of its own on a registration: database connection lost or unavailable, a registration write conflict, a race with a credential being applied |
+| `controller-unavailable` | relay | only when it cannot carry the request or its answer: no Cloudly link, or its own bound ran out |
+| any other word | Cloudly | a verdict: revoked or inactive credential, deleted, retiring or foreign node, invalid body |
+
+A relay forwards every answer Cloudly gave untouched and states nothing but
+`controller-unavailable` itself. `data.buildRuntimeSessionRefusal(reason)` builds
+the payload and throws on a reason that is not a word;
+`data.validateRuntimeSessionRefusal` names every violation;
+`data.readRuntimeSessionRefusal(errorData)` answers the refusal or `null`, and
+`data.readMomentaryRuntimeSessionRefusal(errorData)` answers the momentary reason
+or `null` for a verdict.
+
+The readers are exact-key. Pallet 36.3.14 reads `code` and `reason` and tolerates
+other members, but a reader built on this contract refuses a payload carrying
+any other member, and a refused payload reads as no refusal, which turns a
+momentary refusal into a verdict. A producer never adds a member without gating
+it on the peer's spoken interfaces version.
+
+`data.runtimeSessionRequestBounds` orders the hops so the one nearest the
+decision answers first and a node always reads a stated refusal rather than its
+own timeout: Cloudly's `controllerBudgetMs` (6 s, every node request including
+registration); a relay's `relayRegistrationBudgetMs` (9 s from arrival to
+answer, more than a second beyond Cloudly's budget and below TypedSocket's 10 s
+connection-restore deadline); and a relay's `relaySessionForwardMs` (8 s) for a
+session read or report forwarded over its established Cloudly link.
+
 ### Assignment-Bound Runtime Secrets
 
 `@serve.zone/interfaces/runtime` exports the Pallet assignment-secret contract.
@@ -3611,7 +3669,7 @@ The catalog validator judges every supported version config in full; no consumer
 
 - `image`, then the port model (`appstore.validateAppStoreVersionPortModel`): `port` or `targetPorts` is required, and `targetPorts`, `domains` and `publicPortMappings` are read as exactly their types and resolved through `data.normalizeServicePortConfig`.
 - `containerArgs` and the environment declarations.
-- Storage (`appstore.validateAppStoreVersionStorage`): the exact config member set (`appstore.appStoreVersionConfigKeys`), `platformRequirements`, `storageClasses` and `storageRequests` (declared together, every class used), `backupExclusions`, the storage feature ids `requiresFeatures` must name, portable legacy `volumes`, and every environment, secret-file and mount destination used once.
+- Storage (`appstore.validateAppStoreVersionStorage`): the exact config member set (`appstore.appStoreVersionConfigKeys`), `platformRequirements`, `storageClasses` and `storageRequests` (declared together, every class used), `backupExclusions`, `databaseBackupExclusions`, the storage feature ids `requiresFeatures` must name, portable legacy `volumes`, and every environment, secret-file and mount destination used once.
 - Platform OIDC, then Docker `publishedPorts` (`appstore.validateAppStorePublishedPorts`).
 
 A version declares data it keeps only for observability, such as workload logs, as `backupExclusions` (`IAppStoreBackupExclusion[]`): a backup leaves those object keys out, and a restore neither brings them back nor removes them. Each entry names one objectStorage request of the version (`storageRequest`: an explicit request id, or `legacy-s3` when the version declares `platformRequirements.s3`; a filesystem request is refused), 1 to 16 `keyPrefixes` and a one-line `reason` an operator reads:
@@ -3630,6 +3688,29 @@ const cloudlyVersion: Partial<appstore.IAppStoreVersionConfig> = {
 
 Entries are in strictly increasing `storageRequest` order with each request at most once. A key prefix is 1 to 512 UTF-8 bytes, ends in `/`, does not start with `/`, has no empty, `.` or `..` segment and no control character; the prefixes of an entry are strictly increasing and none lies inside another. `appstore.appStoreBackupExclusionLimits` states the bounds, and `appstore.validateAppStoreBackupExclusionKeyPrefixes(value, label?)` is the one prefix-list rule: the version-config check applies it to each entry, and a reader of a list carrying such prefixes elsewhere, such as a backup manifest, judges it there too (an empty list means valid, otherwise one `Invalid <label>` reason). A version declaring any entry names `storage.object-storage.backup-exclusions` (`appStoreStorageFeatureIds.objectStorageBackupExclusions`) in `requiresFeatures`, so a host that does not leave the keys out of its backups lists the version without installing it, and an older host never reads the member.
 
+Database collections of the same kind, such as a workload log ledger, are declared as `databaseBackupExclusions` (`IAppStoreDatabaseBackupExclusion[]`): a backup exports those collections with their indexes and without their documents, so a restore brings them back empty. Each entry names one database the version provisions (`database`: `mongodb`, which requires `platformRequirements.mongodb: true`, the Corestore `database` resource), 1 to 64 `collections` and a one-line `reason`:
+
+```typescript
+const cloudlyVersion: Partial<appstore.IAppStoreVersionConfig> = {
+  platformRequirements: { mongodb: true, s3: true },
+  databaseBackupExclusions: [{
+    database: 'mongodb',
+    collections: [
+      'cloudly_runtime_log_attempts',
+      'cloudly_runtime_log_batches',
+      'cloudly_runtime_log_captures',
+      'cloudly_runtime_log_inline_payloads',
+      'cloudly_runtime_log_node_discards',
+      'cloudly_runtime_log_queue',
+    ],
+    reason: 'Workload log ledger; a restore brings back state, not past logs.',
+  }],
+  requiresFeatures: [appstore.appStoreStorageFeatureIds.databaseBackupExclusions],
+};
+```
+
+Entries are in strictly increasing `database` order with each database at most once. A collection name is 1 to 128 UTF-8 bytes, does not start with `.` or `system.` (a system collection is never excluded), and has no `/`, `\`, `$`, control character (C0, DEL or C1) or unpaired surrogate; the names of an entry are strictly increasing. `appstore.appStoreDatabaseBackupExclusionLimits` states the bounds, and `appstore.validateAppStoreDatabaseBackupExclusionCollections(value, label?)` is the one collection-list rule: the version-config check applies it to each entry, and a reader of such a list elsewhere, such as Corestore's export request, judges it there too. A version declaring any entry names `storage.database.backup-exclusions` (`appStoreStorageFeatureIds.databaseBackupExclusions`) in `requiresFeatures`, so a host whose database backups cannot leave documents out lists the version without installing it, and an older host never reads the member.
+
 Each storage request is judged on its own by the storage contract behind `platform.normalizeStorageRequest`: members, capacity quantities and limits, protection, delivery and mount path, with that contract's messages and bounds, and a legacy volume's mount path as the request it becomes. The version config adds what only holds between requests: each request's class is declared, of its kind and backs a declared limit (`hardQuota`), backup or snapshots; ids, environment keys, secret files and mounts are used once; the legacy names `legacyFilesystem`, `legacyObjectStorage` and `legacy-s3` stay reserved. Two App Store narrowings apply on top: a request id is a stable lowercase identifier (it shares a namespace with the derived `legacy-volume-*` ids), and a file delivery targets one file directly below `/run/secrets`.
 
 Each of these validators stops at the first violation and answers it as a one-element list starting `Invalid <label>`, so a config is refused for the same reason everywhere.

package/ts/00_commitinfo_data.ts

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

package/ts/appstore/catalog.ts

@@ -87,6 +87,7 @@ const versionConfigKeyList = [
   'storageClasses',
   'storageRequests',
   'backupExclusions',
+  'databaseBackupExclusions',
   'publishedPorts',
   'platformRequirements',
   'platformOidc',

package/ts/appstore/types.ts

@@ -64,6 +64,11 @@ export const appStoreStorageFeatureIds = {
   objectStorageFile: 'storage.object-storage.file',
   /** The version declares `backupExclusions`; a consumer naming it leaves those keys out of backups. */
   objectStorageBackupExclusions: 'storage.object-storage.backup-exclusions',
+  /**
+   * The version declares `databaseBackupExclusions`; a consumer naming it exports those collections
+   * without their documents.
+   */
+  databaseBackupExclusions: 'storage.database.backup-exclusions',
 } as const;
 
 export type TAppStoreStorageFeatureId =
@@ -158,6 +163,40 @@ export interface IAppStoreBackupExclusion {
   reason: string;
 }
 
+/**
+ * A database a version can declare backup exclusions for: `mongodb`, the document database
+ * `platformRequirements.mongodb` provisions (a Corestore `database` resource).
+ */
+export type TAppStoreBackupExclusionDatabase = 'mongodb';
+
+/** The bounds of `IAppStoreVersionConfig.databaseBackupExclusions`. */
+export const appStoreDatabaseBackupExclusionLimits = Object.freeze({
+  /** At most one entry per database; a version provisions at most one (`mongodb`). */
+  maximumEntries: 1,
+  maximumCollections: 64,
+  /** Keeps a whole collection list inside one 16 KiB control document. */
+  maximumCollectionNameBytes: 128,
+  maximumReasonLength: 512,
+} as const);
+
+/**
+ * Collections of one database that the app keeps only for observability, such as its workload
+ * log ledger. A backup exports them with their indexes and without their documents; a restore
+ * therefore brings them back empty.
+ */
+export interface IAppStoreDatabaseBackupExclusion {
+  /** The database: `mongodb`, which the version provisions through `platformRequirements.mongodb`. */
+  database: TAppStoreBackupExclusionDatabase;
+  /**
+   * 1 to 64 collection names in strictly increasing UTF-16 code-unit order. Each is 1 to 128 UTF-8
+   * bytes, does not start with `.` or `system.`, and has no `/`, `\`, `$`, control character or
+   * unpaired surrogate.
+   */
+  collections: string[];
+  /** One operator-readable line, e.g. "Workload log ledger; a restore brings back state, not past logs." */
+  reason: string;
+}
+
 export interface IAppStoreInlineSource {
   type: 'inline';
 }
@@ -440,6 +479,13 @@ export interface IAppStoreVersionConfig {
    * `appStoreStorageFeatureIds.objectStorageBackupExclusions` in `requiresFeatures`.
    */
   backupExclusions?: IAppStoreBackupExclusion[];
+  /**
+   * Database collections the app keeps only for observability, in strictly increasing `database`
+   * order with each database at most once. A backup exports them without their documents; a
+   * restore brings them back empty. A version declaring any entry names
+   * `appStoreStorageFeatureIds.databaseBackupExclusions` in `requiresFeatures`.
+   */
+  databaseBackupExclusions?: IAppStoreDatabaseBackupExclusion[];
   publishedPorts?: IAppStorePublishedPort[];
   platformRequirements?: IAppStorePlatformRequirements;
   /**

package/ts/appstore/versionconfig.ts

@@ -15,8 +15,8 @@
  * `platform.normalizeStorageRequest`), reporting through this module's rejection. What this module
  * adds are the rules a request can only break inside a version config: its class is declared and of
  * its kind, the class backs a declared limit or protection, ids and destinations are used once, the
- * legacy names stay reserved, a backup exclusion names an object-storage request, and the storage
- * feature ids are named.
+ * legacy names stay reserved, a backup exclusion names an object-storage request, a database backup
+ * exclusion names a provisioned database, and the storage feature ids are named.
  */
 import { normalizeServiceAbsolutePath, validateServiceContainerArgs } from '../data/service.js';
 import { normalizeServicePortConfig } from '../data/serviceports.js';
@@ -34,13 +34,16 @@ import { createStorageContractReaders } from '../private/storagecontract.js';
 import type { TObjectStorageDelivery } from '../platform/storage.js';
 import {
   appStoreBackupExclusionLimits,
+  appStoreDatabaseBackupExclusionLimits,
   appStoreStorageFeatureIds,
   validateAppStoreEnvironmentDeclarations,
   validateAppStoreVersionPlatformOidc,
 } from './types.js';
 import type {
   IAppStoreBackupExclusion,
+  IAppStoreDatabaseBackupExclusion,
   IAppStoreVersionConfig,
+  TAppStoreBackupExclusionDatabase,
   TAppStoreStorageRequest,
 } from './types.js';
 
@@ -56,6 +59,7 @@ const versionConfigMemberList = [
   'storageClasses',
   'storageRequests',
   'backupExclusions',
+  'databaseBackupExclusions',
   'publishedPorts',
   'platformRequirements',
   'platformOidc',
@@ -101,6 +105,12 @@ const legacyObjectStorageRequestId = 'legacy-s3';
 const knownStorageFeatureIds: readonly string[] = Object.values(appStoreStorageFeatureIds);
 const platformRequirementKeys = ['mongodb', 's3', 'clickhouse', 'valkey', 'mariadb', 'mail'] as const;
 const controlCharacterPattern = /[\u0000-\u001f\u007f]/;
+/** The C0 and C1 controls and DEL: what the database engine refuses in a namespace component. */
+const collectionNameControlPattern = /[\u0000-\u001f\u007f-\u009f]/;
+/** Each database a version can declare exclusions for, with the platform requirement provisioning it. */
+const backupExclusionDatabaseRequirements: Readonly<Record<TAppStoreBackupExclusionDatabase, 'mongodb'>> = {
+  mongodb: 'mongodb',
+};
 const utf8Encoder = new TextEncoder();
 
 /** Thrown inside this module only; every exported validator answers it as its result. */
@@ -612,6 +622,7 @@ function checkFeatureDeclaration(
   requiresFeaturesArg: unknown,
   explicitRequestsArg: readonly TAppStoreStorageRequest[],
   backupExclusionsArg: readonly IAppStoreBackupExclusion[],
+  databaseBackupExclusionsArg: readonly IAppStoreDatabaseBackupExclusion[],
   labelArg: string,
 ): void {
   const derivedFeatures = new Set<string>();
@@ -628,6 +639,9 @@ function checkFeatureDeclaration(
   if (backupExclusionsArg.length > 0) {
     derivedFeatures.add(appStoreStorageFeatureIds.objectStorageBackupExclusions);
   }
+  if (databaseBackupExclusionsArg.length > 0) {
+    derivedFeatures.add(appStoreStorageFeatureIds.databaseBackupExclusions);
+  }
 
   const declaredEntries = requiresFeaturesArg === undefined
     ? []
@@ -669,6 +683,19 @@ const hasUnpairedSurrogate = (valueArg: string): boolean => {
   return false;
 };
 
+/** An exclusion's `reason`: one trimmed line an operator reads. */
+function checkBackupExclusionReason(valueArg: unknown, maximumLengthArg: number, entryLabelArg: string): string {
+  if (typeof valueArg !== 'string'
+    || valueArg.length === 0
+    || valueArg.length > maximumLengthArg
+    || valueArg.trim() !== valueArg
+    || controlCharacterPattern.test(valueArg)
+    || hasUnpairedSurrogate(valueArg)) {
+    return reject(`Invalid ${entryLabelArg}.reason: must be one trimmed line of 1 to ${maximumLengthArg} characters`);
+  }
+  return valueArg;
+}
+
 /** One object key prefix: a relative key path that names a whole subtree. */
 function checkBackupExclusionKeyPrefix(valueArg: unknown, labelArg: string): string {
   if (typeof valueArg !== 'string') return reject(`Invalid ${labelArg}: expected a string`);
@@ -741,16 +768,99 @@ function checkBackupExclusions(valueArg: unknown, labelArg: string): IAppStoreBa
     previousRequest = storageRequest;
 
     const keyPrefixes = checkBackupExclusionKeyPrefixes(entry.keyPrefixes, `${entryLabel}.keyPrefixes`);
+    return { storageRequest, keyPrefixes, reason: checkBackupExclusionReason(reason, maximumReasonLength, entryLabel) };
+  });
+}
+
+/**
+ * One collection name a database backup exclusion carries: a name the database engine stores
+ * (`database` resources run on NoSQLDB, a MongoDB-compatible engine) that is not a system collection.
+ */
+function checkDatabaseBackupExclusionCollection(valueArg: unknown, labelArg: string): string {
+  const { maximumCollectionNameBytes } = appStoreDatabaseBackupExclusionLimits;
+  if (typeof valueArg !== 'string') return reject(`Invalid ${labelArg}: expected a string`);
+  if (collectionNameControlPattern.test(valueArg) || hasUnpairedSurrogate(valueArg)) {
+    reject(`Invalid ${labelArg}: must not contain a control character or an unpaired surrogate`);
+  }
+  const byteLength = utf8Encoder.encode(valueArg).byteLength;
+  if (byteLength < 1 || byteLength > maximumCollectionNameBytes) {
+    reject(`Invalid ${labelArg}: must be 1 to ${maximumCollectionNameBytes} UTF-8 bytes`);
+  }
+  if (valueArg.startsWith('.')) reject(`Invalid ${labelArg}: must not start with '.'`);
+  if (valueArg.startsWith('system.')) reject(`Invalid ${labelArg}: must not name a 'system.' collection`);
+  if (/[/\\$]/.test(valueArg)) reject(`Invalid ${labelArg}: must not contain '/', '\\' or '$'`);
+  return valueArg;
+}
+
+/**
+ * One exclusion's collection list: 1 to 64 names, strictly increasing.
+ * `validateAppStoreDatabaseBackupExclusionCollections` exports it, so every reader of a collection
+ * list judges it by this one rule.
+ */
+function checkDatabaseBackupExclusionCollections(valueArg: unknown, labelArg: string): string[] {
+  const { maximumCollections } = appStoreDatabaseBackupExclusionLimits;
+  const collectionEntries = readDataElements(valueArg, maximumCollections);
+  if (collectionEntries === null || collectionEntries.length === 0) {
+    return reject(`Invalid ${labelArg}: expected an array of 1 to ${maximumCollections} collection names`);
+  }
+  const collections: string[] = [];
+  collectionEntries.forEach((collectionArg, indexArg) => {
+    const collection = checkDatabaseBackupExclusionCollection(collectionArg, `${labelArg}[${indexArg}]`);
+    const previousCollection = collections[collections.length - 1];
+    if (previousCollection !== undefined && compareWireTokens(previousCollection, collection) >= 0) {
+      reject(`Invalid ${labelArg}: must be strictly increasing`);
+    }
+    collections.push(collection);
+  });
+  return collections;
+}
 
-    if (typeof reason !== 'string'
-      || reason.length === 0
-      || reason.length > maximumReasonLength
-      || reason.trim() !== reason
-      || controlCharacterPattern.test(reason)
-      || hasUnpairedSurrogate(reason)) {
-      reject(`Invalid ${entryLabel}.reason: must be one trimmed line of 1 to ${maximumReasonLength} characters`);
+/**
+ * The members of each database backup exclusion, its collections and the entry order. Whether the
+ * version provisions the database an entry names is judged with its platform requirements
+ * (`checkDatabaseBackupExclusionTargets`).
+ */
+function checkDatabaseBackupExclusions(valueArg: unknown, labelArg: string): IAppStoreDatabaseBackupExclusion[] {
+  if (valueArg === undefined) return [];
+  const { maximumEntries, maximumReasonLength } = appStoreDatabaseBackupExclusionLimits;
+  const entries = readDataElements(valueArg, maximumEntries);
+  if (entries === null || entries.length === 0) {
+    return reject(`Invalid ${labelArg}: databaseBackupExclusions must contain between 1 and ${maximumEntries} entries`);
+  }
+  let previousDatabase: string | null = null;
+  return entries.map((entryArg, indexArg): IAppStoreDatabaseBackupExclusion => {
+    const entryLabel = `${labelArg} databaseBackupExclusions[${indexArg}]`;
+    const entry = readRecord(entryArg, entryLabel);
+    assertExactKeys(entry, ['database', 'collections', 'reason'], entryLabel);
+    const { database } = entry;
+    if (typeof database !== 'string' || !Object.hasOwn(backupExclusionDatabaseRequirements, database)) {
+      return reject(`Invalid ${entryLabel}.database: expected one of ${Object.keys(backupExclusionDatabaseRequirements).join(', ')}`);
+    }
+    if (previousDatabase !== null && compareWireTokens(previousDatabase, database) >= 0) {
+      reject(previousDatabase === database
+        ? `Invalid ${labelArg}: databaseBackupExclusions name database '${database}' more than once`
+        : `Invalid ${labelArg}: databaseBackupExclusions must be in strictly increasing database order`);
+    }
+    previousDatabase = database;
+    return {
+      database: database as TAppStoreBackupExclusionDatabase,
+      collections: checkDatabaseBackupExclusionCollections(entry.collections, `${entryLabel}.collections`),
+      reason: checkBackupExclusionReason(entry.reason, maximumReasonLength, entryLabel),
+    };
+  });
+}
+
+/** Each database backup exclusion names a database the version provisions. */
+function checkDatabaseBackupExclusionTargets(
+  exclusionsArg: readonly IAppStoreDatabaseBackupExclusion[],
+  platformRequirementsArg: Record<string, unknown>,
+  labelArg: string,
+): void {
+  exclusionsArg.forEach((exclusionArg, indexArg) => {
+    const requirement = backupExclusionDatabaseRequirements[exclusionArg.database];
+    if (platformRequirementsArg[requirement] !== true) {
+      reject(`Invalid ${labelArg} databaseBackupExclusions[${indexArg}].database: '${exclusionArg.database}' requires platformRequirements.${requirement}`);
     }
-    return { storageRequest, keyPrefixes, reason };
   });
 }
 
@@ -842,7 +952,15 @@ function checkStorage(configArg: Record<string, unknown>, labelArg: string): voi
     labelArg,
   );
   const backupExclusions = checkBackupExclusions(configArg.backupExclusions, labelArg);
-  checkFeatureDeclaration(configArg.requiresFeatures, explicitRequests, backupExclusions, labelArg);
+  const databaseBackupExclusions = checkDatabaseBackupExclusions(configArg.databaseBackupExclusions, labelArg);
+  checkFeatureDeclaration(
+    configArg.requiresFeatures,
+    explicitRequests,
+    backupExclusions,
+    databaseBackupExclusions,
+    labelArg,
+  );
+  checkDatabaseBackupExclusionTargets(databaseBackupExclusions, platformRequirements, labelArg);
   const legacyS3 = platformRequirements.s3 === true;
   if (legacyS3 && explicitRequests.some((requestArg) => requestArg.kind === 'objectStorage')) {
     reject(`Invalid ${labelArg}: platformRequirements.s3 cannot coexist with explicit objectStorage requests`);
@@ -923,8 +1041,9 @@ export const validateAppStorePublishedPorts = (publishedPortsArg: unknown, label
 
 /**
  * The config's member set and its storage: legacy `volumes`, `storageClasses`, `storageRequests`,
- * `platformRequirements`, `backupExclusions`, the storage feature ids `requiresFeatures` must name,
- * and every environment, secret-file and mount destination being used once.
+ * `platformRequirements`, `backupExclusions`, `databaseBackupExclusions`, the storage feature ids
+ * `requiresFeatures` must name, and every environment, secret-file and mount destination being used
+ * once.
  */
 export const validateAppStoreVersionStorage = (configArg: unknown, labelArg = defaultLabel): string[] =>
   firstRejection(() => checkStorage(readConfig(configArg, labelArg), labelArg));
@@ -941,6 +1060,18 @@ export const validateAppStoreBackupExclusionKeyPrefixes = (
   labelArg = 'keyPrefixes',
 ): string[] => firstRejection(() => checkBackupExclusionKeyPrefixes(valueArg, labelArg));
 
+/**
+ * One database backup exclusion's `collections`, the rule `validateAppStoreVersionStorage` applies
+ * to each `IAppStoreDatabaseBackupExclusion`: 1 to 64 names in strictly increasing UTF-16
+ * code-unit order, each 1 to 128 UTF-8 bytes, not starting with `.` or `system.`, without `/`,
+ * `\`, `$`, a control character or an unpaired surrogate. A reader of a list that carries such
+ * names elsewhere, such as Corestore's export request or a backup's provenance, judges it here.
+ */
+export const validateAppStoreDatabaseBackupExclusionCollections = (
+  valueArg: unknown,
+  labelArg = 'collections',
+): string[] => firstRejection(() => checkDatabaseBackupExclusionCollections(valueArg, labelArg));
+
 /**
  * Every member rule of a version config, in the order a host applies them: image, port model,
  * container arguments, environment declarations, storage, platform OIDC, published ports.

package/ts/data/index.ts

@@ -66,6 +66,7 @@ export * from './runtimestorageclaim.js';
 export * from './runtimelocalstorageclaim.js';
 export * from './runtimelocalvolumearchive.js';
 export * from './runtimesession.js';
+export * from './runtimesessionrefusal.js';
 export * from './runtimeterminalreceipt.js';
 export * from './secret.js';
 export * from './baremetal.js';