@serve.zone/appstore 32.27.0 → 33.1.0

package/ts_client/storage.ts

@@ -1,289 +1,124 @@
-import * as interfaces from '@serve.zone/interfaces';
+import * as plugins from './plugins.js';
 import type {
   IAppStoreStorageNormalizationOptions,
   INormalizedAppStoreStorageConfig,
-  TAppStoreStorageFeatureId,
   TAppStoreStorageRequestOrigin,
-  TAppStoreVersionConfig,
 } from './types.js';
 
-const storageFeatureIds = interfaces.appstore.appStoreStorageFeatureIds;
-const knownStorageFeatureIds = new Set<string>(Object.values(storageFeatureIds));
-const storageClassKeyPattern = /^[A-Za-z][A-Za-z0-9-]{0,62}$/;
-const storageRequestIdPattern = /^[a-z][a-z0-9-]{0,62}$/;
-const environmentKeyPattern = /^[A-Z_][A-Z0-9_]{0,252}$/;
-const capacityPattern = /^([1-9][0-9]*)(KiB|MiB|GiB|TiB)$/;
-const capacityMultipliers = {
-  KiB: 1024n,
-  MiB: 1024n ** 2n,
-  GiB: 1024n ** 3n,
-  TiB: 1024n ** 4n,
-} as const;
+type TCatalogVersionConfig = plugins.servezoneInterfaces.appstore.TAppStoreCatalogVersionConfig;
+type TStorageFeatureId = plugins.servezoneInterfaces.appstore.TAppStoreStorageFeatureId;
+type TStorageRequest = plugins.servezoneInterfaces.appstore.TAppStoreStorageRequest;
+type TVolume = plugins.servezoneInterfaces.appstore.IAppStoreVolume;
+
+const storageFeatureIds = plugins.servezoneInterfaces.appstore.appStoreStorageFeatureIds;
 const legacyFilesystemClassKey = 'legacyFilesystem';
 const legacyObjectStorageClassKey = 'legacyObjectStorage';
 const legacyObjectStorageRequestId = 'legacy-s3';
-const appStoreVersionConfigKeys = [
-  'image',
-  'port',
-  'containerArgs',
-  'targetPorts',
-  'domains',
-  'publicPortMappings',
-  'envVars',
-  'volumes',
-  'storageClasses',
-  'storageRequests',
-  'publishedPorts',
-  'platformRequirements',
-  'platformOidc',
-  'minOneboxVersion',
-  'minCloudlyVersion',
-  'appStoreVersion',
-  'upgradeStrategy',
-  'source',
-  'resolvedSource',
-  'resolvedImageDigest',
-  'changelog',
-  'breaking',
-  'requiresManualReview',
-  'migrationRequired',
-  'backupBeforeUpgrade',
-  'requiresFeatures',
-  'healthCheck',
-] as const;
-
-type TPlainRecord = Record<string, unknown>;
+const storageRequestIdPattern = /^[a-z][a-z0-9-]{0,62}$/;
+const defaultLabel = 'appstore config';
 
-interface IAppInputDestinations {
-  declaredEnvironmentKeys: Set<string>;
-  runtimeEnvironmentKeys: Set<string>;
-  declaredSecretPaths: Set<string>;
-}
+/**
+ * Throws the first storage violation of a version config, judged by the interfaces contract
+ * (`appstore.validateAppStoreVersionStorage`), which owns every storage rule.
+ */
+const assertValidStorage = (configArg: TCatalogVersionConfig, labelArg: string): void => {
+  const errors = plugins.servezoneInterfaces.appstore.validateAppStoreVersionStorage(configArg, labelArg);
+  if (errors.length > 0) throw new Error(errors.join('; '));
+};
+
+const normalizeVolumes = (volumesArg: TCatalogVersionConfig['volumes']): TVolume[] =>
+  (volumesArg ?? []).map((volumeArg): TVolume => {
+    const volume = typeof volumeArg === 'string' ? { mountPath: volumeArg } : volumeArg;
+    return {
+      ...(volume.name === undefined ? {} : { name: volume.name }),
+      mountPath: volume.mountPath,
+      ...(volume.readOnly === undefined ? {} : { readOnly: volume.readOnly }),
+      ...(volume.backup === undefined ? {} : { backup: volume.backup }),
+    };
+  });
 
-export function parseStorageCapacityQuantity(
-  quantityArg: unknown,
-  labelArg = 'storage capacity',
-): bigint {
-  if (typeof quantityArg !== 'string' || quantityArg.length > 64) {
+/** The stable request id a legacy volume becomes: its name, or its mount path flattened. */
+const createLegacyVolumeRequestId = (volumeArg: TVolume, indexArg: number, labelArg: string): string => {
+  const stablePart = volumeArg.name || volumeArg.mountPath
+    .toLowerCase()
+    .split('/')
+    .filter(Boolean)
+    .join('-')
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  const requestId = `legacy-volume-${stablePart}`;
+  if (!stablePart || !storageRequestIdPattern.test(requestId)) {
     throw new Error(
-      `Invalid ${labelArg}: expected a positive integer followed by KiB, MiB, GiB, or TiB`,
+      `Invalid ${labelArg} volumes[${indexArg}]: cannot derive a stable request id; declare a shorter lowercase name`,
     );
   }
-  const match = quantityArg.match(capacityPattern);
-  if (!match) {
-    throw new Error(
-      `Invalid ${labelArg} '${quantityArg}': expected a positive integer followed by KiB, MiB, GiB, or TiB`,
-    );
+  return requestId;
+};
+
+const deriveRequiredFeatureIds = (explicitRequestsArg: TStorageRequest[]): TStorageFeatureId[] => {
+  const required: TStorageFeatureId[] = [];
+  if (explicitRequestsArg.length > 0) required.push(storageFeatureIds.bindings);
+  if (explicitRequestsArg.some((requestArg) => requestArg.kind === 'filesystem')) {
+    required.push(storageFeatureIds.filesystem);
   }
-  // The storage contract reads a capacity quantity as a safe integer amount of its unit, so a
-  // larger quantity names a request no adapter can be handed. This parser is the one place the
-  // App Store reads a quantity, so the same bound is applied here rather than after a request has
-  // already been assembled from it.
-  if (!Number.isSafeInteger(Number(match[1]))) {
-    throw new Error(
-      `Invalid ${labelArg} '${quantityArg}': the quantity exceeds the safe integer range`,
-    );
+  if (explicitRequestsArg.some((requestArg) => requestArg.kind === 'objectStorage')) {
+    required.push(storageFeatureIds.objectStorage);
   }
-  return BigInt(match[1]) * capacityMultipliers[match[2] as keyof typeof capacityMultipliers];
-}
+  if (explicitRequestsArg.some((requestArg) => (
+    requestArg.kind === 'objectStorage' && requestArg.delivery.type === 'file'
+  ))) {
+    required.push(storageFeatureIds.objectStorageFile);
+  }
+  return required;
+};
 
 /**
- * Strict structural validation plus deterministic legacy normalization. This
- * does not claim that a runtime can fulfill explicit requests; installers must
- * call normalizeAppStoreStorageConfig with an advertised feature set.
+ * The legacy `volumes` of a version config in their object form (`{ name?, mountPath, readOnly?,
+ * backup? }`), after the config's storage passed the interfaces contract.
  */
-export function validateAppStoreStorageConfig(
-  configArg: TAppStoreVersionConfig,
-  labelArg = 'appstore config',
-): INormalizedAppStoreStorageConfig {
-  return validateAndNormalizeStorageConfig(configArg, labelArg);
+export function normalizeAppStoreVolumes(
+  configArg: TCatalogVersionConfig,
+  labelArg = defaultLabel,
+): TVolume[] {
+  assertValidStorage(configArg, labelArg);
+  return normalizeVolumes(configArg.volumes);
 }
 
 /**
- * Canonical pre-fulfillment handoff. Explicit storage contracts fail closed
- * unless every derived storage feature is advertised by the target runtime.
+ * The canonical pre-fulfillment storage handoff of a version config.
+ *
+ * The config's storage is judged by the interfaces contract first. Legacy `volumes` become
+ * filesystem requests of the reserved `legacyFilesystem` class, `platformRequirements.s3` becomes
+ * the `legacy-s3` object-storage request, and explicit requests fail closed unless every storage
+ * feature they need is advertised by the target runtime.
  */
 export function normalizeAppStoreStorageConfig(
-  configArg: TAppStoreVersionConfig,
+  configArg: TCatalogVersionConfig,
   optionsArg: IAppStoreStorageNormalizationOptions,
-  labelArg = 'appstore config',
+  labelArg = defaultLabel,
 ): INormalizedAppStoreStorageConfig {
-  const normalized = validateAndNormalizeStorageConfig(configArg, labelArg);
-  if (!optionsArg || optionsArg.supportedFeatures === undefined) {
-    throw new Error(`Invalid ${labelArg}: supportedFeatures is required for storage feature negotiation`);
-  }
+  assertValidStorage(configArg, labelArg);
 
-  let supportedFeatures: Set<string>;
-  try {
-    supportedFeatures = new Set(optionsArg.supportedFeatures);
-  } catch {
-    throw new Error(`Invalid ${labelArg}: supportedFeatures must be iterable`);
-  }
-  const unsupportedFeatures = normalized.requiredFeatureIds.filter(
-    (featureIdArg) => !supportedFeatures.has(featureIdArg),
-  );
-  if (unsupportedFeatures.length > 0) {
-    throw new Error(
-      `Unsupported ${labelArg} storage features: ${unsupportedFeatures.join(', ')}`,
-    );
-  }
-  return normalized;
-}
-
-function collectAppInputDestinations(
-  configArg: TAppStoreVersionConfig,
-  labelArg: string,
-): IAppInputDestinations {
-  const declaredEnvironmentKeys = new Set<string>();
-  const runtimeEnvironmentOwners = new Map<string, string>();
-  const secretFileOwners = new Map<string, string>();
-
-  const addDestination = (
-    ownersArg: Map<string, string>,
-    destinationArg: string,
-    ownerArg: string,
-    kindArg: 'environment' | 'secret file',
-  ): void => {
-    const existingOwner = ownersArg.get(destinationArg);
-    if (existingOwner) {
-      throw new Error(
-        `Invalid ${labelArg}: ${kindArg} destination '${destinationArg}' is used by both ${existingOwner} and ${ownerArg}`,
-      );
-    }
-    ownersArg.set(destinationArg, ownerArg);
-  };
-
-  for (const declaration of configArg.envVars || []) {
-    declaredEnvironmentKeys.add(declaration.key);
-    const owner = `envVars.${declaration.key}`;
-    if (declaration.secret === true) {
-      if (declaration.delivery.type === 'launcher-environment') {
-        addDestination(
-          runtimeEnvironmentOwners,
-          declaration.delivery.variableName,
-          owner,
-          'environment',
-        );
-      } else {
-        addDestination(
-          secretFileOwners,
-          declaration.delivery.targetPath,
-          owner,
-          'secret file',
-        );
-      }
-    } else {
-      addDestination(runtimeEnvironmentOwners, declaration.key, owner, 'environment');
-    }
-  }
+  const storageClasses = structuredClone(configArg.storageClasses ?? {});
+  const explicitRequests = structuredClone(configArg.storageRequests ?? []);
+  const storageRequests: TStorageRequest[] = [...explicitRequests];
+  const requestOrigins: Record<string, TAppStoreStorageRequestOrigin> = {};
+  for (const request of explicitRequests) requestOrigins[request.id] = 'explicit';
+  const requiredFeatureIds = deriveRequiredFeatureIds(explicitRequests);
 
-  const platformOidc = configArg.platformOidc as unknown;
-  if (platformOidc && typeof platformOidc === 'object' && !Array.isArray(platformOidc)) {
-    const environmentVariables = (platformOidc as TPlainRecord).environmentVariables;
-    if (environmentVariables && typeof environmentVariables === 'object'
-      && !Array.isArray(environmentVariables)) {
-      for (const [field, destination] of Object.entries(environmentVariables)) {
-        if (typeof destination === 'string') {
-          addDestination(
-            runtimeEnvironmentOwners,
-            destination,
-            `platformOidc.${field}`,
-            'environment',
-          );
-        }
-      }
-    }
-  }
-
-  return {
-    declaredEnvironmentKeys,
-    runtimeEnvironmentKeys: new Set(runtimeEnvironmentOwners.keys()),
-    declaredSecretPaths: new Set(secretFileOwners.keys()),
-  };
-}
-
-function validateAndNormalizeStorageConfig(
-  configArg: TAppStoreVersionConfig,
-  labelArg: string,
-): INormalizedAppStoreStorageConfig {
-  assertExactKeys(
-    assertPlainRecord(configArg, labelArg),
-    appStoreVersionConfigKeys,
-    labelArg,
-  );
-  const environmentErrors = interfaces.appstore.validateAppStoreEnvironmentDeclarations(
-    configArg.envVars,
-  );
-  if (environmentErrors.length > 0) {
-    throw new Error(`Invalid ${labelArg}: ${environmentErrors.join('; ')}`);
-  }
-  const appInputDestinations = collectAppInputDestinations(configArg, labelArg);
-  validatePlatformRequirements(configArg.platformRequirements, labelArg);
-  const explicitClassInput = configArg.storageClasses;
-  const explicitRequestInput = configArg.storageRequests;
-  const hasExplicitClasses = explicitClassInput !== undefined;
-  const hasExplicitRequests = explicitRequestInput !== undefined;
-  if (hasExplicitClasses !== hasExplicitRequests) {
-    throw new Error(
-      `Invalid ${labelArg}: storageClasses and storageRequests must be declared together`,
-    );
-  }
-
-  const storageClasses = validateStorageClasses(explicitClassInput, labelArg);
-  const explicitRequests = validateExplicitStorageRequests(
-    explicitRequestInput,
-    storageClasses,
-    appInputDestinations,
-    labelArg,
-  );
-  const requiredFeatureIds = validateFeatureDeclaration(configArg, explicitRequests, labelArg);
-
-  if (configArg.platformRequirements?.s3 && explicitRequests.some(
-    (requestArg) => requestArg.kind === 'objectStorage',
-  )) {
-    throw new Error(
-      `Invalid ${labelArg}: platformRequirements.s3 cannot coexist with explicit objectStorage requests`,
-    );
-  }
-
-  const storageRequests = [...explicitRequests];
-  const requestOriginEntries: Array<[string, TAppStoreStorageRequestOrigin]> = explicitRequests.map(
-    (requestArg) => [requestArg.id, 'explicit'],
-  );
-  const requestIds = new Set(explicitRequests.map((requestArg) => requestArg.id));
-  const mountPaths = explicitRequests
-    .filter((requestArg): requestArg is interfaces.appstore.IAppStoreFilesystemStorageRequest => (
-      requestArg.kind === 'filesystem'
-    ))
-    .map((requestArg) => requestArg.mountPath);
-
-  const legacyVolumes = normalizeLegacyVolumes(configArg.volumes, labelArg);
+  const legacyVolumes = normalizeVolumes(configArg.volumes);
   if (legacyVolumes.length > 0) {
-    if (Object.hasOwn(storageClasses, legacyFilesystemClassKey)) {
-      throw new Error(
-        `Invalid ${labelArg}: storageClasses key '${legacyFilesystemClassKey}' is reserved for legacy volume normalization`,
-      );
-    }
     storageClasses[legacyFilesystemClassKey] = {
       kind: 'filesystem',
       purpose: 'runtime',
       required: {
         durability: 'persistent',
-        ...(legacyVolumes.some((volumeArg) => volumeArg.backup !== false)
-          ? { backup: true as const }
-          : {}),
+        ...(legacyVolumes.some((volumeArg) => volumeArg.backup !== false) ? { backup: true } : {}),
       },
     };
   }
-
-  for (const [indexArg, volumeArg] of legacyVolumes.entries()) {
+  legacyVolumes.forEach((volumeArg, indexArg) => {
     const requestId = createLegacyVolumeRequestId(volumeArg, indexArg, labelArg);
-    if (requestIds.has(requestId)) {
-      throw new Error(`Invalid ${labelArg}: storage request id '${requestId}' is duplicated`);
-    }
-    assertNoPathCollision(volumeArg.mountPath, mountPaths, `${labelArg} legacy volume ${indexArg + 1}`);
-    requestIds.add(requestId);
-    mountPaths.push(volumeArg.mountPath);
     storageRequests.push({
       id: requestId,
       kind: 'filesystem',
@@ -291,23 +126,13 @@ function validateAndNormalizeStorageConfig(
       mountPath: volumeArg.mountPath,
       accessMode: volumeArg.readOnly ? 'ReadOnlyMany' : 'ReadWriteOnce',
       reclaimPolicy: 'retain',
-      ...(volumeArg.backup === false ? {} : { protection: { backup: 'required' as const } }),
+      ...(volumeArg.backup === false ? {} : { protection: { backup: 'required' } }),
     });
-    requestOriginEntries.push([requestId, 'legacyVolume']);
-  }
+    requestOrigins[requestId] = 'legacyVolume';
+  });
 
   let legacyCompatibility: INormalizedAppStoreStorageConfig['legacyCompatibility'];
   if (configArg.platformRequirements?.s3) {
-    if (Object.hasOwn(storageClasses, legacyObjectStorageClassKey)) {
-      throw new Error(
-        `Invalid ${labelArg}: storageClasses key '${legacyObjectStorageClassKey}' is reserved for legacy S3 normalization`,
-      );
-    }
-    if (requestIds.has(legacyObjectStorageRequestId)) {
-      throw new Error(
-        `Invalid ${labelArg}: storage request id '${legacyObjectStorageRequestId}' is reserved for legacy S3 normalization`,
-      );
-    }
     storageClasses[legacyObjectStorageClassKey] = {
       kind: 'objectStorage',
       purpose: 'runtime',
@@ -330,7 +155,7 @@ function validateAndNormalizeStorageConfig(
         },
       },
     });
-    requestOriginEntries.push([legacyObjectStorageRequestId, 'legacyS3']);
+    requestOrigins[legacyObjectStorageRequestId] = 'legacyS3';
     legacyCompatibility = {
       objectStorage: {
         requestId: legacyObjectStorageRequestId,
@@ -340,631 +165,17 @@ function validateAndNormalizeStorageConfig(
     };
   }
 
-  validateAllFilesystemMountsAndSecretTargets(
-    storageRequests,
-    appInputDestinations.declaredSecretPaths,
-    labelArg,
-  );
+  const supportedFeatures = new Set(optionsArg.supportedFeatures);
+  const unsupportedFeatures = requiredFeatureIds.filter((featureIdArg) => !supportedFeatures.has(featureIdArg));
+  if (unsupportedFeatures.length > 0) {
+    throw new Error(`Unsupported ${labelArg} storage features: ${unsupportedFeatures.join(', ')}`);
+  }
 
   return {
     storageClasses,
     storageRequests,
-    requestOrigins: Object.fromEntries(requestOriginEntries),
+    requestOrigins,
     requiredFeatureIds,
     ...(legacyCompatibility ? { legacyCompatibility } : {}),
   };
 }
-
-function validateStorageClasses(
-  classesArg: TAppStoreVersionConfig['storageClasses'],
-  labelArg: string,
-): Record<string, interfaces.appstore.IAppStoreStorageClass> {
-  if (classesArg === undefined) return {};
-  const classesRecord = assertPlainRecord(classesArg, `${labelArg} storageClasses`);
-  const entries = Object.entries(classesRecord);
-  if (entries.length === 0 || entries.length > 64) {
-    throw new Error(`Invalid ${labelArg}: storageClasses must contain between 1 and 64 entries`);
-  }
-
-  const normalizedEntries = entries.map(([classKeyArg, candidateArg]) => {
-    if (!storageClassKeyPattern.test(classKeyArg)) {
-      throw new Error(`Invalid ${labelArg}: storage class key '${classKeyArg}' is not stable`);
-    }
-    const classLabel = `${labelArg} storageClasses.${classKeyArg}`;
-    const candidate = assertPlainRecord(candidateArg, classLabel);
-    assertExactKeys(candidate, ['kind', 'purpose', 'required', 'preferred'], classLabel);
-    if (!['filesystem', 'objectStorage'].includes(candidate.kind as string)) {
-      throw new Error(`Invalid ${classLabel}: kind must be filesystem or objectStorage`);
-    }
-    if (!['runtime', 'database', 'registry', 'backup'].includes(candidate.purpose as string)) {
-      throw new Error(`Invalid ${classLabel}: purpose is not supported`);
-    }
-    const required = validateClassRequirement(candidate.required, `${classLabel}.required`);
-    const preferred = validateClassRequirement(candidate.preferred, `${classLabel}.preferred`);
-    if (required && preferred) {
-      for (const requirementKey of Object.keys(required) as Array<keyof typeof required>) {
-        if (preferred[requirementKey] !== undefined
-          && preferred[requirementKey] !== required[requirementKey]) {
-          throw new Error(
-            `Invalid ${classLabel}: preferred.${String(requirementKey)} conflicts with required.${String(requirementKey)}`,
-          );
-        }
-      }
-    }
-    const normalized: interfaces.appstore.IAppStoreStorageClass = {
-      kind: candidate.kind as interfaces.platform.TStorageResourceKind,
-      purpose: candidate.purpose as interfaces.appstore.TAppStoreStoragePurpose,
-      ...(required ? { required } : {}),
-      ...(preferred ? { preferred } : {}),
-    };
-    return [classKeyArg, normalized] as const;
-  });
-
-  return Object.fromEntries(normalizedEntries);
-}
-
-function validateClassRequirement(
-  requirementArg: unknown,
-  labelArg: string,
-): interfaces.platform.IStorageClassRequirement | undefined {
-  if (requirementArg === undefined) return undefined;
-  const requirement = assertPlainRecord(requirementArg, labelArg);
-  assertExactKeys(requirement, [
-    'performanceTier',
-    'durability',
-    'topology',
-    'hardQuota',
-    'snapshots',
-    'backup',
-    'encryptedInTransit',
-  ], labelArg);
-  assertOptionalMember(
-    requirement.performanceTier,
-    ['standard', 'highIops', 'capacity'],
-    `${labelArg}.performanceTier`,
-  );
-  assertOptionalMember(
-    requirement.durability,
-    ['ephemeral', 'persistent'],
-    `${labelArg}.durability`,
-  );
-  assertOptionalMember(
-    requirement.topology,
-    ['singleNode', 'multiNode'],
-    `${labelArg}.topology`,
-  );
-  assertOptionalMember(requirement.snapshots, ['portable', 'native'], `${labelArg}.snapshots`);
-  for (const booleanKey of ['hardQuota', 'backup', 'encryptedInTransit'] as const) {
-    if (requirement[booleanKey] !== undefined && requirement[booleanKey] !== true) {
-      throw new Error(`Invalid ${labelArg}.${booleanKey}: only true may be declared`);
-    }
-  }
-  return { ...requirement } as interfaces.platform.IStorageClassRequirement;
-}
-
-function validateExplicitStorageRequests(
-  requestsArg: TAppStoreVersionConfig['storageRequests'],
-  classesArg: Record<string, interfaces.appstore.IAppStoreStorageClass>,
-  appInputDestinationsArg: IAppInputDestinations,
-  labelArg: string,
-): interfaces.appstore.TAppStoreStorageRequest[] {
-  if (requestsArg === undefined) return [];
-  if (!Array.isArray(requestsArg) || requestsArg.length === 0 || requestsArg.length > 64) {
-    throw new Error(`Invalid ${labelArg}: storageRequests must contain between 1 and 64 entries`);
-  }
-
-  const requestIds = new Set<string>();
-  const usedClassKeys = new Set<string>();
-  const deliveryEnvironmentKeys = new Set<string>();
-  const {
-    declaredEnvironmentKeys,
-    runtimeEnvironmentKeys,
-    declaredSecretPaths,
-  } = appInputDestinationsArg;
-  const deliverySecretPaths = new Set<string>();
-
-  const requests = requestsArg.map((candidateArg, indexArg) => {
-    const requestLabel = `${labelArg} storageRequests[${indexArg}]`;
-    const candidate = assertPlainRecord(candidateArg, requestLabel);
-    if (candidate.kind === 'filesystem') {
-      assertExactKeys(candidate, [
-        'id', 'kind', 'storageClass', 'capacity', 'reclaimPolicy',
-        'mountPath', 'accessMode', 'protection',
-      ], requestLabel);
-    } else if (candidate.kind === 'objectStorage') {
-      assertExactKeys(candidate, [
-        'id', 'kind', 'storageClass', 'capacity', 'reclaimPolicy',
-        'accessMode', 'delivery', 'protection',
-      ], requestLabel);
-    } else {
-      throw new Error(`Invalid ${requestLabel}: kind must be filesystem or objectStorage`);
-    }
-    if (typeof candidate.id !== 'string' || !storageRequestIdPattern.test(candidate.id)) {
-      throw new Error(`Invalid ${requestLabel}: id must be a stable lowercase identifier`);
-    }
-    if (requestIds.has(candidate.id)) {
-      throw new Error(`Invalid ${labelArg}: storage request id '${candidate.id}' is duplicated`);
-    }
-    requestIds.add(candidate.id);
-    if (typeof candidate.storageClass !== 'string'
-      || !Object.hasOwn(classesArg, candidate.storageClass)) {
-      throw new Error(`Invalid ${requestLabel}: storageClass '${candidate.storageClass}' is not declared`);
-    }
-    const storageClass = classesArg[candidate.storageClass];
-    if (storageClass.kind !== candidate.kind) {
-      throw new Error(`Invalid ${requestLabel}: storageClass kind does not match request kind`);
-    }
-    usedClassKeys.add(candidate.storageClass);
-    if (!['retain', 'delete'].includes(candidate.reclaimPolicy as string)) {
-      throw new Error(`Invalid ${requestLabel}: reclaimPolicy must be retain or delete`);
-    }
-    const capacity = validateCapacity(candidate.capacity, `${requestLabel}.capacity`);
-    if (capacity?.limit && storageClass.required?.hardQuota !== true) {
-      throw new Error(`Invalid ${requestLabel}: capacity.limit requires storageClass.required.hardQuota`);
-    }
-
-    if (candidate.kind === 'filesystem') {
-      if (typeof candidate.mountPath !== 'string'
-        || interfaces.data.normalizeServiceAbsolutePath(candidate.mountPath) !== candidate.mountPath
-        || candidate.mountPath === '/'
-        || pathsOverlap(candidate.mountPath, '/run/secrets')) {
-        throw new Error(`Invalid ${requestLabel}: mountPath must be a canonical non-root path outside /run/secrets`);
-      }
-      assertOptionalMember(
-        candidate.accessMode,
-        ['ReadWriteOnce', 'ReadOnlyMany', 'ReadWriteMany'],
-        `${requestLabel}.accessMode`,
-        false,
-      );
-      const protection = validateFilesystemProtection(
-        candidate.protection,
-        `${requestLabel}.protection`,
-      );
-      if (protection?.backup === 'required' && storageClass.required?.backup !== true) {
-        throw new Error(`Invalid ${requestLabel}: required backup must be declared by the storage class`);
-      }
-      if (protection?.snapshots && storageClass.required?.snapshots !== protection.snapshots) {
-        throw new Error(`Invalid ${requestLabel}: required snapshots must be declared by the storage class`);
-      }
-      return {
-        id: candidate.id,
-        kind: 'filesystem',
-        storageClass: candidate.storageClass,
-        ...(capacity ? { capacity } : {}),
-        reclaimPolicy: candidate.reclaimPolicy as interfaces.platform.TStorageReclaimPolicy,
-        mountPath: candidate.mountPath,
-        accessMode: candidate.accessMode as interfaces.platform.TFilesystemStorageAccessMode,
-        ...(protection ? { protection } : {}),
-      } satisfies interfaces.appstore.IAppStoreFilesystemStorageRequest;
-    }
-
-    assertOptionalMember(
-      candidate.accessMode,
-      ['readOnly', 'readWrite'],
-      `${requestLabel}.accessMode`,
-      false,
-    );
-    const delivery = validateObjectStorageDelivery(
-      candidate.delivery,
-      requestLabel,
-      declaredEnvironmentKeys,
-      runtimeEnvironmentKeys,
-      deliveryEnvironmentKeys,
-      declaredSecretPaths,
-      deliverySecretPaths,
-    );
-    const protection = validateObjectStorageProtection(
-      candidate.protection,
-      `${requestLabel}.protection`,
-    );
-    if (protection?.backup === 'required' && storageClass.required?.backup !== true) {
-      throw new Error(`Invalid ${requestLabel}: required backup must be declared by the storage class`);
-    }
-    return {
-      id: candidate.id,
-      kind: 'objectStorage',
-      storageClass: candidate.storageClass,
-      ...(capacity ? { capacity } : {}),
-      reclaimPolicy: candidate.reclaimPolicy as interfaces.platform.TStorageReclaimPolicy,
-      accessMode: candidate.accessMode as interfaces.platform.TObjectStorageAccessMode,
-      delivery,
-      ...(protection ? { protection } : {}),
-    } satisfies interfaces.appstore.IAppStoreObjectStorageRequest;
-  });
-
-  for (const classKeyArg of Object.keys(classesArg)) {
-    if (!usedClassKeys.has(classKeyArg)) {
-      throw new Error(`Invalid ${labelArg}: storage class '${classKeyArg}' is not used by a request`);
-    }
-  }
-  return requests;
-}
-
-function validateCapacity(
-  capacityArg: unknown,
-  labelArg: string,
-): interfaces.platform.IStorageCapacityRequest | undefined {
-  if (capacityArg === undefined) return undefined;
-  const capacity = assertPlainRecord(capacityArg, labelArg);
-  assertExactKeys(capacity, ['request', 'limit'], labelArg);
-  const requestedBytes = parseStorageCapacityQuantity(capacity.request, `${labelArg}.request`);
-  const limitBytes = capacity.limit === undefined
-    ? undefined
-    : parseStorageCapacityQuantity(capacity.limit, `${labelArg}.limit`);
-  if (limitBytes !== undefined && limitBytes < requestedBytes) {
-    throw new Error(`Invalid ${labelArg}: limit must be greater than or equal to request`);
-  }
-  return {
-    request: capacity.request as string,
-    ...(capacity.limit === undefined ? {} : { limit: capacity.limit as string }),
-  };
-}
-
-/**
- * An absent `protection` member already states that the request asks for no protection, so an
- * empty one states nothing a fulfillment adapter could act on. The storage contract refuses it by
- * name (`protection must not be empty`), and this package is the producer of those requests: the
- * manifest author is told here instead of a control plane refusing the request later. Members are
- * copied one by one rather than spread, so a member declared as an explicit `undefined` — which
- * the member checks treat as absent, and which the contract refuses as a non-JSON data property —
- * can never reach the emitted request.
- */
-function assertProtectionDeclaresRequirement<TProtection extends object>(
-  protectionArg: TProtection,
-  labelArg: string,
-): TProtection {
-  if (Object.keys(protectionArg).length === 0) {
-    throw new Error(
-      `Invalid ${labelArg}: declare at least one protection requirement or omit protection`,
-    );
-  }
-  return protectionArg;
-}
-
-function validateFilesystemProtection(
-  protectionArg: unknown,
-  labelArg: string,
-): interfaces.appstore.IAppStoreFilesystemProtection | undefined {
-  if (protectionArg === undefined) return undefined;
-  const protection = assertPlainRecord(protectionArg, labelArg);
-  assertExactKeys(protection, ['backup', 'snapshots', 'consistency'], labelArg);
-  assertOptionalMember(protection.backup, ['required'], `${labelArg}.backup`);
-  assertOptionalMember(protection.snapshots, ['portable', 'native'], `${labelArg}.snapshots`);
-  assertOptionalMember(
-    protection.consistency,
-    ['crashConsistent', 'applicationConsistent'],
-    `${labelArg}.consistency`,
-  );
-  return assertProtectionDeclaresRequirement({
-    ...(protection.backup === undefined
-      ? {}
-      : { backup: protection.backup as 'required' }),
-    ...(protection.snapshots === undefined
-      ? {}
-      : { snapshots: protection.snapshots as Exclude<interfaces.platform.TStorageSnapshotMode, 'none'> }),
-    ...(protection.consistency === undefined
-      ? {}
-      : { consistency: protection.consistency as 'crashConsistent' | 'applicationConsistent' }),
-  }, labelArg);
-}
-
-function validateObjectStorageProtection(
-  protectionArg: unknown,
-  labelArg: string,
-): interfaces.appstore.IAppStoreObjectStorageProtection | undefined {
-  if (protectionArg === undefined) return undefined;
-  const protection = assertPlainRecord(protectionArg, labelArg);
-  assertExactKeys(protection, ['backup', 'versioning', 'retentionDays'], labelArg);
-  assertOptionalMember(protection.backup, ['required'], `${labelArg}.backup`);
-  assertOptionalMember(protection.versioning, ['required'], `${labelArg}.versioning`);
-  if (protection.retentionDays !== undefined
-    && (!Number.isInteger(protection.retentionDays)
-      || (protection.retentionDays as number) < 1
-      || (protection.retentionDays as number) > 36500)) {
-    throw new Error(`Invalid ${labelArg}.retentionDays: expected an integer between 1 and 36500`);
-  }
-  return assertProtectionDeclaresRequirement({
-    ...(protection.backup === undefined
-      ? {}
-      : { backup: protection.backup as 'required' }),
-    ...(protection.versioning === undefined
-      ? {}
-      : { versioning: protection.versioning as 'required' }),
-    ...(protection.retentionDays === undefined
-      ? {}
-      : { retentionDays: protection.retentionDays as number }),
-  }, labelArg);
-}
-
-function validateObjectStorageDelivery(
-  deliveryArg: unknown,
-  requestLabelArg: string,
-  declaredEnvironmentKeysArg: Set<string>,
-  runtimeEnvironmentKeysArg: Set<string>,
-  deliveryEnvironmentKeysArg: Set<string>,
-  declaredSecretPathsArg: Set<string>,
-  deliverySecretPathsArg: Set<string>,
-): interfaces.platform.TObjectStorageDelivery {
-  const deliveryLabel = `${requestLabelArg}.delivery`;
-  const delivery = assertPlainRecord(deliveryArg, deliveryLabel);
-  if (delivery.type === 'launcher-environment') {
-    assertExactKeys(delivery, ['type', 'keys'], deliveryLabel);
-    const keys = assertPlainRecord(delivery.keys, `${deliveryLabel}.keys`);
-    assertExactKeys(keys, [
-      'endpoint', 'bucket', 'region', 'accessKeyId', 'secretAccessKey', 'sessionToken',
-    ], `${deliveryLabel}.keys`);
-    for (const requiredKey of ['endpoint', 'bucket', 'region', 'accessKeyId', 'secretAccessKey']) {
-      if (typeof keys[requiredKey] !== 'string') {
-        throw new Error(`Invalid ${deliveryLabel}.keys: '${requiredKey}' is required`);
-      }
-    }
-    const targetKeys = Object.values(keys);
-    const localKeys = new Set<string>();
-    for (const targetKeyArg of targetKeys) {
-      if (typeof targetKeyArg !== 'string' || !environmentKeyPattern.test(targetKeyArg)) {
-        throw new Error(`Invalid ${deliveryLabel}: environment delivery keys must be canonical`);
-      }
-      if (localKeys.has(targetKeyArg)) {
-        throw new Error(`Invalid ${deliveryLabel}: environment key '${targetKeyArg}' is duplicated`);
-      }
-      if (declaredEnvironmentKeysArg.has(targetKeyArg)
-        || runtimeEnvironmentKeysArg.has(targetKeyArg)) {
-        throw new Error(
-          `Invalid ${deliveryLabel}: environment key '${targetKeyArg}' collides with an app runtime input`,
-        );
-      }
-      if (deliveryEnvironmentKeysArg.has(targetKeyArg)) {
-        throw new Error(`Invalid ${deliveryLabel}: environment key '${targetKeyArg}' is used by another storage request`);
-      }
-      localKeys.add(targetKeyArg);
-      deliveryEnvironmentKeysArg.add(targetKeyArg);
-    }
-    return {
-      type: 'launcher-environment',
-      keys: { ...keys },
-    } as interfaces.platform.IObjectStorageLauncherEnvironmentDelivery;
-  }
-
-  if (delivery.type === 'file') {
-    assertExactKeys(delivery, ['type', 'targetPath', 'format', 'uid', 'gid', 'mode'], deliveryLabel);
-    if (delivery.format !== 'servezone-object-storage') {
-      throw new Error(`Invalid ${deliveryLabel}: secret file format is not supported`);
-    }
-    if (typeof delivery.targetPath !== 'string'
-      || interfaces.data.normalizeServiceAbsolutePath(delivery.targetPath) !== delivery.targetPath
-      || !/^\/run\/secrets\/[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(delivery.targetPath)) {
-      throw new Error(`Invalid ${deliveryLabel}: targetPath must be a unique canonical file below /run/secrets`);
-    }
-    if (declaredSecretPathsArg.has(delivery.targetPath)) {
-      throw new Error(`Invalid ${deliveryLabel}: targetPath collides with an app secret delivery`);
-    }
-    if (deliverySecretPathsArg.has(delivery.targetPath)) {
-      throw new Error(`Invalid ${deliveryLabel}: targetPath is used by another storage request`);
-    }
-    // `-0` survives JSON.parse and passes both the safe-integer and the range check, but the
-    // storage contract refuses it because it is a second spelling of the same identity and would
-    // give one request two canonical digests.
-    for (const identityField of ['uid', 'gid'] as const) {
-      if (!Number.isSafeInteger(delivery[identityField])
-        || Object.is(delivery[identityField], -0)
-        || (delivery[identityField] as number) < 0
-        || (delivery[identityField] as number) > 2_147_483_647) {
-        throw new Error(`Invalid ${deliveryLabel}: ${identityField} must be a bounded numeric identity`);
-      }
-    }
-    if (delivery.mode !== 0o400 && delivery.mode !== 0o440) {
-      throw new Error(`Invalid ${deliveryLabel}: mode must be 0400 or 0440`);
-    }
-    deliverySecretPathsArg.add(delivery.targetPath);
-    return {
-      type: 'file',
-      targetPath: delivery.targetPath,
-      format: 'servezone-object-storage',
-      uid: delivery.uid as number,
-      gid: delivery.gid as number,
-      mode: delivery.mode as 0o400 | 0o440,
-    };
-  }
-
-  throw new Error(`Invalid ${deliveryLabel}: type must be launcher-environment or file`);
-}
-
-function validateFeatureDeclaration(
-  configArg: TAppStoreVersionConfig,
-  explicitRequestsArg: interfaces.appstore.TAppStoreStorageRequest[],
-  labelArg: string,
-): TAppStoreStorageFeatureId[] {
-  const requiredFeatures = new Set<TAppStoreStorageFeatureId>();
-  if (explicitRequestsArg.length > 0) {
-    requiredFeatures.add(storageFeatureIds.bindings);
-  }
-  if (explicitRequestsArg.some((requestArg) => requestArg.kind === 'filesystem')) {
-    requiredFeatures.add(storageFeatureIds.filesystem);
-  }
-  if (explicitRequestsArg.some((requestArg) => requestArg.kind === 'objectStorage')) {
-    requiredFeatures.add(storageFeatureIds.objectStorage);
-  }
-  if (explicitRequestsArg.some((requestArg) => (
-    requestArg.kind === 'objectStorage' && requestArg.delivery.type === 'file'
-  ))) {
-    requiredFeatures.add(storageFeatureIds.objectStorageFile);
-  }
-
-  const declaredFeatures = configArg.requiresFeatures || [];
-  if (!Array.isArray(declaredFeatures)
-    || declaredFeatures.some((entryArg) => typeof entryArg !== 'string')) {
-    throw new Error(`Invalid ${labelArg}: requiresFeatures must be an array of strings`);
-  }
-  if (new Set(declaredFeatures).size !== declaredFeatures.length) {
-    throw new Error(`Invalid ${labelArg}: requiresFeatures must not contain duplicates`);
-  }
-  for (const requiredFeature of requiredFeatures) {
-    if (!declaredFeatures.includes(requiredFeature)) {
-      throw new Error(`Invalid ${labelArg}: requiresFeatures is missing '${requiredFeature}'`);
-    }
-  }
-  for (const declaredFeature of declaredFeatures) {
-    if (declaredFeature.startsWith('storage.') && !knownStorageFeatureIds.has(declaredFeature)) {
-      throw new Error(`Invalid ${labelArg}: unknown storage feature '${declaredFeature}'`);
-    }
-    if (knownStorageFeatureIds.has(declaredFeature)
-      && !requiredFeatures.has(declaredFeature as TAppStoreStorageFeatureId)) {
-      throw new Error(`Invalid ${labelArg}: storage feature '${declaredFeature}' is not used`);
-    }
-  }
-  return Array.from(requiredFeatures);
-}
-
-function validatePlatformRequirements(
-  requirementsArg: TAppStoreVersionConfig['platformRequirements'],
-  labelArg: string,
-): void {
-  if (requirementsArg === undefined) return;
-  const requirements = assertPlainRecord(requirementsArg, `${labelArg} platformRequirements`);
-  assertExactKeys(
-    requirements,
-    ['mongodb', 's3', 'clickhouse', 'valkey', 'mariadb', 'mail'],
-    `${labelArg} platformRequirements`,
-  );
-  for (const [keyArg, valueArg] of Object.entries(requirements)) {
-    if (typeof valueArg !== 'boolean') {
-      throw new Error(`Invalid ${labelArg} platformRequirements.${keyArg}: expected a boolean`);
-    }
-  }
-}
-
-function normalizeLegacyVolumes(
-  volumesArg: TAppStoreVersionConfig['volumes'],
-  labelArg: string,
-): interfaces.appstore.IAppStoreVolume[] {
-  if (volumesArg === undefined) return [];
-  if (!Array.isArray(volumesArg) || volumesArg.length > 64) {
-    throw new Error(`Invalid ${labelArg}: volumes must be an array with at most 64 entries`);
-  }
-  return volumesArg.map((volumeArg, indexArg) => {
-    const volumeLabel = `${labelArg} volumes[${indexArg}]`;
-    const normalized = typeof volumeArg === 'string'
-      ? { mountPath: volumeArg }
-      : assertPlainRecord(volumeArg, volumeLabel);
-    assertExactKeys(
-      normalized,
-      ['name', 'source', 'mountPath', 'driver', 'readOnly', 'backup', 'options'],
-      volumeLabel,
-    );
-    for (const forbiddenKey of ['source', 'driver', 'options']) {
-      if (normalized[forbiddenKey] !== undefined) {
-        throw new Error(`Invalid ${volumeLabel}: physical field '${forbiddenKey}' cannot be normalized portably`);
-      }
-    }
-    if (typeof normalized.mountPath !== 'string'
-      || interfaces.data.normalizeServiceAbsolutePath(normalized.mountPath) !== normalized.mountPath
-      || normalized.mountPath === '/'
-      || pathsOverlap(normalized.mountPath, '/run/secrets')) {
-      throw new Error(`Invalid ${volumeLabel}: mountPath must be a canonical non-root path outside /run/secrets`);
-    }
-    if (normalized.name !== undefined
-      && (typeof normalized.name !== 'string' || !storageRequestIdPattern.test(normalized.name))) {
-      throw new Error(`Invalid ${volumeLabel}: name must be a stable lowercase identifier`);
-    }
-    for (const booleanKey of ['readOnly', 'backup']) {
-      if (normalized[booleanKey] !== undefined && typeof normalized[booleanKey] !== 'boolean') {
-        throw new Error(`Invalid ${volumeLabel}.${booleanKey}: expected a boolean`);
-      }
-    }
-    return {
-      ...(normalized.name === undefined ? {} : { name: normalized.name as string }),
-      mountPath: normalized.mountPath,
-      ...(normalized.readOnly === undefined ? {} : { readOnly: normalized.readOnly as boolean }),
-      ...(normalized.backup === undefined ? {} : { backup: normalized.backup as boolean }),
-    };
-  });
-}
-
-function createLegacyVolumeRequestId(
-  volumeArg: interfaces.appstore.IAppStoreVolume,
-  indexArg: number,
-  labelArg: string,
-): string {
-  const stablePart = volumeArg.name || volumeArg.mountPath
-    .toLowerCase()
-    .split('/')
-    .filter(Boolean)
-    .join('-')
-    .replace(/[^a-z0-9-]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-  const requestId = `legacy-volume-${stablePart}`;
-  if (!stablePart || !storageRequestIdPattern.test(requestId)) {
-    throw new Error(
-      `Invalid ${labelArg} volumes[${indexArg}]: cannot derive a stable request id; declare a shorter lowercase name`,
-    );
-  }
-  return requestId;
-}
-
-function validateAllFilesystemMountsAndSecretTargets(
-  requestsArg: interfaces.appstore.TAppStoreStorageRequest[],
-  declaredSecretPathsArg: Set<string>,
-  labelArg: string,
-): void {
-  const mountPaths: string[] = [];
-  const objectSecretPaths: string[] = [];
-  for (const requestArg of requestsArg) {
-    if (requestArg.kind === 'filesystem') {
-      assertNoPathCollision(requestArg.mountPath, mountPaths, `${labelArg} request '${requestArg.id}'`);
-      mountPaths.push(requestArg.mountPath);
-    } else if (requestArg.delivery.type === 'file') {
-      objectSecretPaths.push(requestArg.delivery.targetPath);
-    }
-  }
-  for (const secretPathArg of [...declaredSecretPathsArg, ...objectSecretPaths]) {
-    if (mountPaths.some((mountPathArg) => pathsOverlap(secretPathArg, mountPathArg))) {
-      throw new Error(`Invalid ${labelArg}: secret target '${secretPathArg}' overlaps a filesystem mount`);
-    }
-  }
-}
-
-function assertNoPathCollision(pathArg: string, pathsArg: string[], labelArg: string): void {
-  const collision = pathsArg.find((existingPathArg) => pathsOverlap(pathArg, existingPathArg));
-  if (collision) {
-    throw new Error(`Invalid ${labelArg}: path '${pathArg}' overlaps '${collision}'`);
-  }
-}
-
-function pathsOverlap(leftArg: string, rightArg: string): boolean {
-  const left = interfaces.data.normalizeServiceAbsolutePath(leftArg);
-  const right = interfaces.data.normalizeServiceAbsolutePath(rightArg);
-  if (!left || !right) return false;
-  if (left === '/' || right === '/') return true;
-  return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
-}
-
-function assertPlainRecord(valueArg: unknown, labelArg: string): TPlainRecord {
-  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
-    throw new Error(`Invalid ${labelArg}: expected an object`);
-  }
-  return valueArg as TPlainRecord;
-}
-
-function assertExactKeys(
-  recordArg: TPlainRecord,
-  allowedKeysArg: readonly string[],
-  labelArg: string,
-): void {
-  const allowedKeys = new Set(allowedKeysArg);
-  const unknownKeys = Object.keys(recordArg).filter((keyArg) => !allowedKeys.has(keyArg));
-  if (unknownKeys.length > 0) {
-    throw new Error(`Invalid ${labelArg}: unknown field(s) ${unknownKeys.sort().join(', ')}`);
-  }
-}
-
-function assertOptionalMember(
-  valueArg: unknown,
-  allowedValuesArg: readonly string[],
-  labelArg: string,
-  optionalArg = true,
-): void {
-  if (valueArg === undefined && optionalArg) return;
-  if (typeof valueArg !== 'string' || !allowedValuesArg.includes(valueArg)) {
-    throw new Error(`Invalid ${labelArg}: expected one of ${allowedValuesArg.join(', ')}`);
-  }
-}