@serve.zone/interfaces 32.55.1 → 32.57.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.55.1",
+  "version": "32.57.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

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,9 +3669,25 @@ 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), 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`, 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:
+
+```typescript
+const cloudlyVersion: Partial<appstore.IAppStoreVersionConfig> = {
+  platformRequirements: { s3: true },
+  backupExclusions: [{
+    storageRequest: 'legacy-s3',
+    keyPrefixes: ['runtime-logs/'],
+    reason: 'Workload logs; a restore brings back state, not past logs.',
+  }],
+  requiresFeatures: [appstore.appStoreStorageFeatureIds.objectStorageBackupExclusions],
+};
+```
+
+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.
+
 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.55.1',
+  version: '32.57.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/appstore/catalog.ts

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

package/ts/appstore/types.ts

@@ -62,6 +62,8 @@ export const appStoreStorageFeatureIds = {
   filesystem: 'storage.filesystem',
   objectStorage: 'storage.object-storage',
   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',
 } as const;
 
 export type TAppStoreStorageFeatureId =
@@ -127,6 +129,35 @@ export type TAppStoreStorageRequest =
   | IAppStoreFilesystemStorageRequest
   | IAppStoreObjectStorageRequest;
 
+/** The bounds of `IAppStoreVersionConfig.backupExclusions`. */
+export const appStoreBackupExclusionLimits = Object.freeze({
+  /** At most one entry per object-storage request; a version config holds at most 64 requests. */
+  maximumEntries: 64,
+  maximumKeyPrefixes: 16,
+  maximumKeyPrefixBytes: 512,
+  maximumReasonLength: 512,
+} as const);
+
+/**
+ * Keys of one object-storage request that the app keeps only for observability, such as its
+ * workload logs. A backup leaves them out; a restore neither brings them back nor removes them.
+ */
+export interface IAppStoreBackupExclusion {
+  /**
+   * An objectStorage request of this version: an explicit request id, or `legacy-s3` when the
+   * version declares `platformRequirements.s3`. A filesystem request cannot declare exclusions.
+   */
+  storageRequest: string;
+  /**
+   * 1 to 16 object key prefixes in strictly increasing UTF-16 code-unit order, none a prefix of
+   * another. Each is 1 to 512 UTF-8 bytes, ends in `/`, does not start with `/`, has no empty,
+   * `.` or `..` segment and no control character or unpaired surrogate.
+   */
+  keyPrefixes: string[];
+  /** One operator-readable line, e.g. "Workload logs; a restore brings back state, not past logs." */
+  reason: string;
+}
+
 export interface IAppStoreInlineSource {
   type: 'inline';
 }
@@ -402,6 +433,13 @@ export interface IAppStoreVersionConfig {
   storageClasses?: Record<string, IAppStoreStorageClass>;
   /** Stable named filesystem and managed object-storage requests. */
   storageRequests?: TAppStoreStorageRequest[];
+  /**
+   * Data the app keeps only for observability, in strictly increasing `storageRequest` order with
+   * each request at most once. A backup leaves it out; a restore neither brings it back nor
+   * removes it. A version declaring any entry names
+   * `appStoreStorageFeatureIds.objectStorageBackupExclusions` in `requiresFeatures`.
+   */
+  backupExclusions?: IAppStoreBackupExclusion[];
   publishedPorts?: IAppStorePublishedPort[];
   platformRequirements?: IAppStorePlatformRequirements;
   /**

package/ts/appstore/versionconfig.ts

@@ -15,7 +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, and the storage feature ids are named.
+ * legacy names stay reserved, a backup exclusion names an object-storage request, and the storage
+ * feature ids are named.
  */
 import { normalizeServiceAbsolutePath, validateServiceContainerArgs } from '../data/service.js';
 import { normalizeServicePortConfig } from '../data/serviceports.js';
@@ -26,16 +27,22 @@ import type {
   TServiceTargetPortRef,
   TServiceTargetProtocol,
 } from '../data/serviceports.js';
+import { compareWireTokens } from '../private/canonicaljson.js';
 import { readDataElements, readDataProperties } from '../private/dataproperties.js';
 import type { TCompleteKeyList } from '../private/keylist.js';
 import { createStorageContractReaders } from '../private/storagecontract.js';
 import type { TObjectStorageDelivery } from '../platform/storage.js';
 import {
+  appStoreBackupExclusionLimits,
   appStoreStorageFeatureIds,
   validateAppStoreEnvironmentDeclarations,
   validateAppStoreVersionPlatformOidc,
 } from './types.js';
-import type { IAppStoreVersionConfig, TAppStoreStorageRequest } from './types.js';
+import type {
+  IAppStoreBackupExclusion,
+  IAppStoreVersionConfig,
+  TAppStoreStorageRequest,
+} from './types.js';
 
 const versionConfigMemberList = [
   'image',
@@ -48,6 +55,7 @@ const versionConfigMemberList = [
   'volumes',
   'storageClasses',
   'storageRequests',
+  'backupExclusions',
   'publishedPorts',
   'platformRequirements',
   'platformOidc',
@@ -92,6 +100,8 @@ const legacyObjectStorageClassKey = 'legacyObjectStorage';
 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]/;
+const utf8Encoder = new TextEncoder();
 
 /** Thrown inside this module only; every exported validator answers it as its result. */
 class AppStoreVersionConfigRejection extends Error {}
@@ -601,6 +611,7 @@ function checkExplicitStorageRequests(
 function checkFeatureDeclaration(
   requiresFeaturesArg: unknown,
   explicitRequestsArg: readonly TAppStoreStorageRequest[],
+  backupExclusionsArg: readonly IAppStoreBackupExclusion[],
   labelArg: string,
 ): void {
   const derivedFeatures = new Set<string>();
@@ -614,6 +625,9 @@ function checkFeatureDeclaration(
   if (explicitRequestsArg.some((requestArg) => requestArg.kind === 'objectStorage' && requestArg.delivery.type === 'file')) {
     derivedFeatures.add(appStoreStorageFeatureIds.objectStorageFile);
   }
+  if (backupExclusionsArg.length > 0) {
+    derivedFeatures.add(appStoreStorageFeatureIds.objectStorageBackupExclusions);
+  }
 
   const declaredEntries = requiresFeaturesArg === undefined
     ? []
@@ -641,6 +655,123 @@ function checkFeatureDeclaration(
   }
 }
 
+const hasUnpairedSurrogate = (valueArg: string): boolean => {
+  for (let index = 0; index < valueArg.length; index++) {
+    const codeUnit = valueArg.charCodeAt(index);
+    if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+      const following = valueArg.charCodeAt(index + 1);
+      if (!(following >= 0xdc00 && following <= 0xdfff)) return true;
+      index++;
+    } else if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+      return true;
+    }
+  }
+  return false;
+};
+
+/** 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`);
+  if (controlCharacterPattern.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 > appStoreBackupExclusionLimits.maximumKeyPrefixBytes) {
+    reject(`Invalid ${labelArg}: must be 1 to ${appStoreBackupExclusionLimits.maximumKeyPrefixBytes} UTF-8 bytes`);
+  }
+  if (valueArg.startsWith('/')) reject(`Invalid ${labelArg}: must not start with '/'`);
+  if (!valueArg.endsWith('/')) reject(`Invalid ${labelArg}: must end with '/'`);
+  if (valueArg.slice(0, -1).split('/').some((segmentArg) => segmentArg === '' || segmentArg === '.' || segmentArg === '..')) {
+    reject(`Invalid ${labelArg}: must not contain an empty, '.' or '..' segment`);
+  }
+  return valueArg;
+}
+
+/**
+ * One exclusion's key prefix list: 1 to 16 prefixes, strictly increasing, none inside another.
+ * `validateAppStoreBackupExclusionKeyPrefixes` exports it, so every reader of a prefix list judges
+ * it by this one rule.
+ */
+function checkBackupExclusionKeyPrefixes(valueArg: unknown, labelArg: string): string[] {
+  const { maximumKeyPrefixes } = appStoreBackupExclusionLimits;
+  const prefixEntries = readDataElements(valueArg, maximumKeyPrefixes);
+  if (prefixEntries === null || prefixEntries.length === 0) {
+    return reject(`Invalid ${labelArg}: expected an array of 1 to ${maximumKeyPrefixes} key prefixes`);
+  }
+  const keyPrefixes: string[] = [];
+  prefixEntries.forEach((prefixArg, indexArg) => {
+    const prefixLabel = `${labelArg}[${indexArg}]`;
+    const prefix = checkBackupExclusionKeyPrefix(prefixArg, prefixLabel);
+    const previousPrefix = keyPrefixes[keyPrefixes.length - 1];
+    if (previousPrefix !== undefined && compareWireTokens(previousPrefix, prefix) >= 0) {
+      reject(`Invalid ${labelArg}: must be strictly increasing`);
+    }
+    const covering = keyPrefixes.find((existingArg) => prefix.startsWith(existingArg));
+    if (covering !== undefined) {
+      reject(`Invalid ${prefixLabel}: '${prefix}' lies inside '${covering}'`);
+    }
+    keyPrefixes.push(prefix);
+  });
+  return keyPrefixes;
+}
+
+/**
+ * The members of each backup exclusion, its key prefixes and the entry order. Which request an
+ * entry names is judged once the config's requests are known (`checkBackupExclusionTargets`).
+ */
+function checkBackupExclusions(valueArg: unknown, labelArg: string): IAppStoreBackupExclusion[] {
+  if (valueArg === undefined) return [];
+  const { maximumEntries, maximumReasonLength } = appStoreBackupExclusionLimits;
+  const entries = readDataElements(valueArg, maximumEntries);
+  if (entries === null || entries.length === 0) {
+    return reject(`Invalid ${labelArg}: backupExclusions must contain between 1 and ${maximumEntries} entries`);
+  }
+  let previousRequest: string | null = null;
+  return entries.map((entryArg, indexArg): IAppStoreBackupExclusion => {
+    const entryLabel = `${labelArg} backupExclusions[${indexArg}]`;
+    const entry = readRecord(entryArg, entryLabel);
+    assertExactKeys(entry, ['storageRequest', 'keyPrefixes', 'reason'], entryLabel);
+    const { storageRequest, reason } = entry;
+    if (typeof storageRequest !== 'string') return reject(`Invalid ${entryLabel}.storageRequest: expected a string`);
+    if (previousRequest !== null && compareWireTokens(previousRequest, storageRequest) >= 0) {
+      reject(previousRequest === storageRequest
+        ? `Invalid ${labelArg}: backupExclusions name storage request '${storageRequest}' more than once`
+        : `Invalid ${labelArg}: backupExclusions must be in strictly increasing storageRequest order`);
+    }
+    previousRequest = storageRequest;
+
+    const keyPrefixes = checkBackupExclusionKeyPrefixes(entry.keyPrefixes, `${entryLabel}.keyPrefixes`);
+
+    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`);
+    }
+    return { storageRequest, keyPrefixes, reason };
+  });
+}
+
+/** Each backup exclusion names an object-storage request of the normalized config. */
+function checkBackupExclusionTargets(
+  exclusionsArg: readonly IAppStoreBackupExclusion[],
+  objectStorageRequestIdsArg: ReadonlySet<string>,
+  filesystemRequestIdsArg: ReadonlySet<string>,
+  labelArg: string,
+): void {
+  exclusionsArg.forEach((exclusionArg, indexArg) => {
+    const { storageRequest } = exclusionArg;
+    if (objectStorageRequestIdsArg.has(storageRequest)) return;
+    const requestLabel = `${labelArg} backupExclusions[${indexArg}].storageRequest`;
+    if (filesystemRequestIdsArg.has(storageRequest)) {
+      reject(`Invalid ${requestLabel}: '${storageRequest}' is a filesystem request; only an objectStorage request declares backup exclusions`);
+    }
+    reject(`Invalid ${requestLabel}: '${storageRequest}' does not name an objectStorage request of this version`);
+  });
+}
+
 interface ILegacyVolumeFacts {
   name?: string;
   mountPath: string;
@@ -710,7 +841,8 @@ function checkStorage(configArg: Record<string, unknown>, labelArg: string): voi
     destinations,
     labelArg,
   );
-  checkFeatureDeclaration(configArg.requiresFeatures, explicitRequests, labelArg);
+  const backupExclusions = checkBackupExclusions(configArg.backupExclusions, labelArg);
+  checkFeatureDeclaration(configArg.requiresFeatures, explicitRequests, backupExclusions, 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`);
@@ -727,6 +859,7 @@ function checkStorage(configArg: Record<string, unknown>, labelArg: string): voi
   const allMounts: Array<{ id: string; mountPath: string }> = explicitRequests.flatMap((requestArg) => (
     requestArg.kind === 'filesystem' ? [{ id: requestArg.id, mountPath: requestArg.mountPath }] : []
   ));
+  const legacyVolumeRequestIds: string[] = [];
   legacyVolumes.forEach((volumeArg, indexArg) => {
     const requestId = legacyVolumeRequestId(volumeArg, indexArg, labelArg);
     if (requestIds.has(requestId)) reject(`Invalid ${labelArg}: storage request id '${requestId}' is duplicated`);
@@ -734,6 +867,7 @@ function checkStorage(configArg: Record<string, unknown>, labelArg: string): voi
     requestIds.add(requestId);
     mountPaths.push(volumeArg.mountPath);
     allMounts.push({ id: requestId, mountPath: volumeArg.mountPath });
+    legacyVolumeRequestIds.push(requestId);
   });
 
   if (legacyS3) {
@@ -744,6 +878,18 @@ function checkStorage(configArg: Record<string, unknown>, labelArg: string): voi
       reject(`Invalid ${labelArg}: storage request id '${legacyObjectStorageRequestId}' is reserved for legacy S3 normalization`);
     }
   }
+  checkBackupExclusionTargets(
+    backupExclusions,
+    new Set([
+      ...explicitRequests.flatMap((requestArg) => (requestArg.kind === 'objectStorage' ? [requestArg.id] : [])),
+      ...(legacyS3 ? [legacyObjectStorageRequestId] : []),
+    ]),
+    new Set([
+      ...explicitRequests.flatMap((requestArg) => (requestArg.kind === 'filesystem' ? [requestArg.id] : [])),
+      ...legacyVolumeRequestIds,
+    ]),
+    labelArg,
+  );
 
   const checkedMounts: string[] = [];
   for (const mount of allMounts) {
@@ -777,12 +923,24 @@ export const validateAppStorePublishedPorts = (publishedPortsArg: unknown, label
 
 /**
  * The config's member set and its storage: legacy `volumes`, `storageClasses`, `storageRequests`,
- * `platformRequirements`, the storage feature ids `requiresFeatures` must name, and every
- * environment, secret-file and mount destination being used once.
+ * `platformRequirements`, `backupExclusions`, 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));
 
+/**
+ * One backup exclusion's `keyPrefixes`, the rule `validateAppStoreVersionStorage` applies to each
+ * `IAppStoreBackupExclusion`: 1 to 16 prefixes in strictly increasing UTF-16 code-unit order, none
+ * inside another, each 1 to 512 UTF-8 bytes ending in `/`, without a leading `/`, an empty, `.` or
+ * `..` segment, a control character or an unpaired surrogate. A reader of a list that carries such
+ * prefixes elsewhere, such as a backup manifest, judges it here.
+ */
+export const validateAppStoreBackupExclusionKeyPrefixes = (
+  valueArg: unknown,
+  labelArg = 'keyPrefixes',
+): string[] => firstRejection(() => checkBackupExclusionKeyPrefixes(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';