@serve.zone/interfaces 32.52.0 → 32.54.0

package/dist_ts/runtime.corestore.d.ts

@@ -5,13 +5,13 @@ import type { IObjectStorageRetentionIntent, IObjectStorageRetentionEvidenceExpe
 import type { IPlatformDatabaseEndpoint } from './platform/database.js';
 export type TCorestoreCredentialCapability = 'database' | 'objectstorage';
 export declare const corestoreProviderConfigIds: Readonly<{
-    readonly database: "cloudly-corestore-database";
-    readonly objectstorage: "cloudly-corestore-objectstorage";
+    readonly database: 'cloudly-corestore-database';
+    readonly objectstorage: 'cloudly-corestore-objectstorage';
 }>;
-export declare const corestoreControlUrl: "http://corestore:3000";
-export declare const corestoreCredentialManagementScope: "platform:cloudly-corestore";
-export declare const corestoreControlCredentialKey: "CORESTORE_API_TOKEN";
-export declare const corestoreCredentialEnvironment: "production";
+export declare const corestoreControlUrl: 'http://corestore:3000';
+export declare const corestoreCredentialManagementScope: 'platform:cloudly-corestore';
+export declare const corestoreControlCredentialKey: 'CORESTORE_API_TOKEN';
+export declare const corestoreCredentialEnvironment: 'production';
 export declare const corestoreCredentialRuntimeLimits: Readonly<{
     maximumIdentifierLength: 200;
     maximumPublicationGrants: 256;
@@ -22,7 +22,7 @@ export declare const corestoreCredentialRuntimeLimits: Readonly<{
     maximumControlTokenBytes: 4096;
     maximumSealedControlCredentialBytes: number;
 }>;
-export declare const getCorestoreProviderConfigId: (capabilityArg: TCorestoreCredentialCapability) => (typeof corestoreProviderConfigIds)[TCorestoreCredentialCapability];
+export declare const getCorestoreProviderConfigId: (capabilityArg: TCorestoreCredentialCapability) => typeof corestoreProviderConfigIds[TCorestoreCredentialCapability];
 export interface ICorestoreControlCredentialPlaintext {
     key: typeof corestoreControlCredentialKey;
     environment: typeof corestoreCredentialEnvironment;
@@ -92,7 +92,7 @@ interface ICorestoreCredentialBindingRequestBase {
     managementScope: typeof corestoreCredentialManagementScope;
     environment: typeof corestoreCredentialEnvironment;
 }
-export type TCorestoreCredentialBindingRequest = ICorestoreCredentialBindingRequestBase & {
+export type TCorestoreCredentialBindingRequest = (ICorestoreCredentialBindingRequestBase & {
     capability: 'database';
     /**
      * Where a workload reaches the database: the `corestoreDatabase` of the node the binding is
@@ -102,11 +102,11 @@ export type TCorestoreCredentialBindingRequest = ICorestoreCredentialBindingRequ
      * is admitted is the provider's decision, never a default this contract supplies.
      */
     endpoint?: IPlatformDatabaseEndpoint;
-} | ICorestoreCredentialBindingRequestBase & {
+}) | (ICorestoreCredentialBindingRequestBase & {
     capability: 'objectstorage';
     bucketName: string;
     objectstorageRetention?: IObjectStorageRetentionIntent;
-};
+});
 export declare const validateCorestoreCredentialBindingRequest: (requestArg: unknown) => string[];
 export declare const createCorestoreCredentialBindingRequestDigestInput: (requestArg: TCorestoreCredentialBindingRequest) => string;
 export declare const computeCorestoreCredentialBindingRequestSha256: (requestArg: TCorestoreCredentialBindingRequest) => Promise<string>;
@@ -209,7 +209,7 @@ export interface IReq_PublishCorestoreCredentialMaterial extends plugins.typedre
         receipt: ICorestoreCredentialPublicationReceipt;
     };
 }
-export declare const createPublishCorestoreCredentialMaterialEnvelopeContext: (requestArg: Omit<IPublishCorestoreCredentialMaterialRequest, "identity" | "envelope">) => Uint8Array;
+export declare const createPublishCorestoreCredentialMaterialEnvelopeContext: (requestArg: Omit<IPublishCorestoreCredentialMaterialRequest, 'identity' | 'envelope'>) => Uint8Array;
 export declare const validatePublishCorestoreCredentialMaterialRequest: (requestArg: unknown, expectedGrantArg: ICorestoreCredentialPublicationGrant, activeRecipientArg: IActiveSecretRecipientMetadata, trustedNowArg: number) => Promise<string[]>;
 export interface ICorestoreCredentialPublicationReceiptExpectation {
     request: IPublishCorestoreCredentialMaterialRequest;
@@ -312,9 +312,9 @@ export interface ICorestoreDatabaseBackupClosureReceipt {
  * is a transfer that fails at the last hop instead of at the first. Every one of them imports this
  * constant rather than writing the bytes again.
  */
-export declare const corestoreDatabaseBackupMediaType: "application/vnd.serve-zone.corestore-database-backup";
+export declare const corestoreDatabaseBackupMediaType: 'application/vnd.serve-zone.corestore-database-backup';
 /** The format a backup receipt states, which is this media type's payload contract. */
-export declare const corestoreDatabaseBackupFormat: "corestore.database.backup";
+export declare const corestoreDatabaseBackupFormat: 'corestore.database.backup';
 export interface ICorestoreDatabaseBackupReceipt {
     format: typeof corestoreDatabaseBackupFormat;
     backupId: string;

package/dist_ts/runtime.d.ts

@@ -144,7 +144,7 @@ export interface ICoreflowSecretRuntimeRegistrationExpectation {
     activeRecipient: IActiveSecretRecipientMetadata;
 }
 /** Dedicated TypedSocket tag carrying ICoreflowSecretRuntimeRegistration. */
-export declare const coreflowSecretRuntimeRegistrationTagId: "coreflowSecretRuntimeRegistration";
+export declare const coreflowSecretRuntimeRegistrationTagId: 'coreflowSecretRuntimeRegistration';
 export type TCoreflowSecretRuntimeRegistrationExpectationResponse = {
     status: 'available';
     expectation: ICoreflowSecretRuntimeRegistrationExpectation;

package/dist_ts/runtime.workloadinit.d.ts

@@ -1,16 +1,16 @@
 import type { TSha256Digest, TImmutableContainerPlatform } from './data/immutableimage.js';
 export declare const workloadInitReleaseContract: Readonly<{
-    readonly packageName: "@serve.zone/workloadinit";
-    readonly sourceRepository: "https://code.foss.global/serve.zone/workloadinit.git";
-    readonly imageRegistry: "code.foss.global";
-    readonly imageRepository: "serve.zone/workloadinit";
-    readonly imageIndexMediaType: "application/vnd.oci.image.index.v1+json";
-    readonly statementType: "https://in-toto.io/Statement/v1";
-    readonly predicateType: "https://slsa.dev/provenance/v1";
-    readonly buildType: "https://serve.zone/buildtypes/workloadinit-gitzone-tsdocker";
-    readonly builderId: "https://serve.zone/builders/workloadinit-manual-release";
-    readonly signatureFormat: "cosign-dsse-bundle-v0.3";
-    readonly signatureAlgorithm: "ecdsa-p256-sha256";
+    readonly packageName: '@serve.zone/workloadinit';
+    readonly sourceRepository: 'https://code.foss.global/serve.zone/workloadinit.git';
+    readonly imageRegistry: 'code.foss.global';
+    readonly imageRepository: 'serve.zone/workloadinit';
+    readonly imageIndexMediaType: 'application/vnd.oci.image.index.v1+json';
+    readonly statementType: 'https://in-toto.io/Statement/v1';
+    readonly predicateType: 'https://slsa.dev/provenance/v1';
+    readonly buildType: 'https://serve.zone/buildtypes/workloadinit-gitzone-tsdocker';
+    readonly builderId: 'https://serve.zone/builders/workloadinit-manual-release';
+    readonly signatureFormat: 'cosign-dsse-bundle-v0.3';
+    readonly signatureAlgorithm: 'ecdsa-p256-sha256';
 }>;
 export interface IWorkloadInitBuildToolVersions {
     dockerBuildx: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "32.52.0",
+  "version": "32.54.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {
@@ -27,11 +27,12 @@
     "@tsclass/tsclass": "^9.5.1"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^5.1.2",
+    "@git.zone/tsbuild": "^6.0.2",
     "@git.zone/tsdoc": "^3.0.2",
-    "@git.zone/tsrun": "^3.0.2",
+    "@git.zone/tsrun": "^3.0.3",
     "@git.zone/tstest": "^7.2.0",
-    "@types/node": "26.6.3"
+    "@types/node": "26.6.4",
+    "typescript": "^6.0.3"
   },
   "files": [
     "ts/**/*",

package/readme.md

@@ -3559,6 +3559,7 @@ Compatibility rules:
 - Every level has exact keys; an unknown member is `schemaInvalid` (`appstore.validateAppStoreCatalog`).
 - `requiresFeatures` gates one version: a consumer passes the feature ids it fulfils (`supportedFeatureIds`, e.g. `appStoreStorageFeatureIds` values). A version naming any other id stays listed, is refused for install and upgrade there, and its config is not interpreted, so a new config capability ships under a feature id without refusing the rest of the catalog (`appstore.getAppStoreCatalogMissingFeatureIds`).
 - A published `app@version` stays in every later catalog and never changes (`appstore.judgeAppStoreCatalogSuccession`): a later catalog that no longer lists it is `publishedVersionRemoved`, one that lists it with another `configDigest` is `publishedVersionMutated`, and a revision that does not increase is `revisionRegressed`.
+- A version names the oldest host releases that run it (`minOneboxVersion`, `minCloudlyVersion`). A host passes itself to `appstore.judgeAppStoreCatalogInstallTarget` as `{ kind: 'onebox' | 'cloudly', version }` (`IAppStoreCatalogConsumer`), which refuses a version needing a newer release of it as `consumerVersionTooOld`; the version stays listed and installs once the host is upgraded.
 - A publisher retires a version by withdrawing it, never by removing it. A withdrawn version keeps its entry, config and digest, so services installed from it keep reading it, and is refused as an install or upgrade target, like a version gated on a feature the consumer lacks (`appstore.judgeAppStoreCatalogInstallTarget`). A withdrawal is final: a later catalog that revokes or rewrites it is `publishedWithdrawalChanged`; a version withdrawn by mistake is republished under a new version.
 
 Digests are SHA-256 over strict canonical JSON (keys in UTF-16 code-unit order, safe integers only) of a domain-separated value: `computeAppStoreCatalogConfigDigest`, `computeAppStoreCatalogDigest` and `computeAppStoreCatalogSigningKeyId`. A signature covers `createAppStoreCatalogSignaturePayload(catalogDigest)`. These helpers use Web Crypto and are safe in the browser entry.
@@ -3583,6 +3584,14 @@ if (!verification.accepted) {
 
 `verifyAppStoreCatalogEnvelope` authenticates before it interprets: envelope shape, `catalogDigest`, one valid signature by a trusted key (a failing signature by a trusted key refuses the envelope), then contract, schema and every `configDigest`. The consumer then judges succession against its active catalog.
 
+A publisher keeps its signing key as a file: `importAppStoreCatalogSigningKeyPem(text)` reads one unencrypted PKCS#8 PEM Ed25519 private key (`openssl genpkey -algorithm ed25519`) into an `IAppStoreCatalogSigningKey` with its public key and key id, and `exportAppStoreCatalogSigningKeyPem(key)` writes one. `getAppStoreCatalogTrustedKey(key)` is the `IAppStoreCatalogTrustedKey` a consumer ships for it. A trusted key also converts from and to an SPKI PEM public key (`openssl pkey -pubout`) with `importAppStoreCatalogTrustedKeyPem` and `exportAppStoreCatalogTrustedKeyPem`. Each refuses another PEM label or key type and a key id that does not match its public key, and no error quotes its input.
+
+A service records the App Store version it runs as `IService.data.appStoreTemplate` (`IAppStoreServiceTemplateSnapshot`: `appId`, `version`, `configDigest`, `config`, `catalogRevision`), taken from a verified catalog by `appstore.createAppStoreServiceTemplateSnapshot`. It is server-managed (`TServiceWritableData` excludes it): the host writes it at install, upgrade and catalog adoption, and runtime paths read it, never the live catalog. While no catalog is active, an `unavailable` status states its `cause` (`loading`, `failed`, `refused`) for programs next to the operator's `reason`, and App Store install, upgrade and upgrade preview are refused with the retryable code `APPSTORE_CATALOG_UNAVAILABLE` (`IAppStoreCatalogUnavailableErrorData`). `IReq_Any_ImportAppStoreCatalog` imports an operator's envelope text (origin `operatorImport`) and answers the status after it, so an air-gapped host needs no registry.
+
+A host loads the catalog from the npm registries `appstore.resolveAppStoreCatalogRegistries(list)` answers: the configured list (Cloudly's `ICloudlySettings.appStoreCatalogRegistries`, an Onebox setting) in canonical form, or `appStoreCatalogDefaultRegistries` (npmjs) when it is empty. `appstore.validateAppStoreCatalogRegistries` is the one rule for a configured list: `https:` base URLs without credentials, query or fragment, each registry once.
+
+A host's App Store views carry the listing as `IAppStoreApp` and `IAppStoreAppMeta`: `versions` names the install targets, and the optional `versionStates` (`IAppStoreAppVersionState`) states every listed version, withdrawn and feature-gated ones included, with its `judgeAppStoreCatalogInstallTarget` answer as `installRefusal`.
+
 `TAppStoreCatalogStatus` is the operator's view, discriminated by `availability`: `ready` (`IAppStoreCatalogReadyStatus`) always carries the `active` catalog's revision, digest, key and origin, including a restored last-known-good catalog; `unavailable` (`IAppStoreCatalogUnavailableStatus`) always carries a `reason` and no active catalog. Both state `supportedContract`, `supportedFeatureIds`, `lastAttempt`, `nextAttemptAt` and the last `refused` catalog. Loading a catalog never gates the boot, readiness or health of anything else; while none is active only App Store install, upgrade and upgrade-preview are refused. `requests.appstore.IReq_Any_GetAppStoreCatalogStatus` reads it, `IReq_Any_RefreshAppStoreCatalog` runs one attempt now and answers the state after it, and `IReq_Any_GetAppStoreTemplates` may answer it as `catalogStatus`.
 
 The catalog validator judges every supported version config in full; no consumer needs a second validator. Besides the catalog's own rules (member set, image pinning, the feature gate, minimum versions, upgrade flags, `healthCheck`) it applies `appstore.validateAppStoreVersionConfig`, the member rules a host applies before it installs a version, in this order:
@@ -3653,7 +3662,7 @@ The immutable deployment workflow is:
 1. Reserve the exact service, namespace, registry repository/tag, and route intent with `reserveServiceDeployment`.
 2. Push the OCI index to the returned exact tag with the authenticated deployer identity.
 3. Promote the authenticated release evidence with `promoteServiceImageRelease`.
-4. Observe exact rollout and runtime-digest evidence with `getServiceDeploymentStatus`.
+4. Observe exact rollout and runtime-digest evidence with `getServiceDeploymentStatus`. That request is for a deployment polling its own rollout: Cloudly transitions a rolling-out operation to success or failure as its evidence proves either. An inspection, such as `tsdeploy deploy-status`, uses `readServiceDeploymentStatus` instead. It takes the same request and answers the same `IServiceDeploymentStatus`, but changes nothing.
 5. For a greenfield service, expose and verify its public route with `promoteServiceDeploymentRoute` only after the immutable rollout succeeds.
 
 A legacy `deployOnPush` service without deployable source moves to a greenfield successor by a legacy import, which replaces step 2:

package/ts/00_commitinfo_data.ts

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

package/ts/appstore/catalog.ts

@@ -12,6 +12,7 @@
  */
 import type { TSha256Digest } from '../data/immutableimage.js';
 import { getDigestFromPinnedImageReference, isSha256Digest } from '../data/immutableimage.js';
+import { compareReleaseVersions, parseReleaseVersion } from '../data/releaseversion.js';
 import {
   canonicalizeStrictJson,
   compareWireTokens,
@@ -268,14 +269,39 @@ export interface IAppStoreCatalogReadyStatus extends IAppStoreCatalogStatusBase
   reason?: never;
 }
 
+/**
+ * Why no verified catalog is active, for programs; `reason` says it for operators.
+ *
+ * - `loading`: no attempt has ended since start and no last-known-good catalog was restored.
+ * - `failed`: the last attempt read no candidate (transport, integrity or packaging failed).
+ * - `refused`: the last attempt read a candidate and refused it (`refused` holds the record).
+ */
+export type TAppStoreCatalogUnavailableCause = 'loading' | 'failed' | 'refused';
+
 /** No verified catalog is active, neither a last-known-good one nor a fetched one. */
 export interface IAppStoreCatalogUnavailableStatus extends IAppStoreCatalogStatusBase {
   availability: 'unavailable';
-  /** Why no catalog is active, e.g. the last attempt's failure. */
+  /** Why no catalog is active, e.g. the last attempt's failure. For operators; never parse it. */
   reason: string;
+  /** Why no catalog is active, for programs. Every host that loads the catalog at runtime states it. */
+  cause?: TAppStoreCatalogUnavailableCause;
   active?: never;
 }
 
+/**
+ * The code a host answers, as `TypedResponseError.errorData` (`IAppStoreCatalogUnavailableErrorData`),
+ * when it refuses an App Store install, upgrade or upgrade preview because no verified catalog is
+ * active. Retryable: the same request succeeds once a catalog is active.
+ */
+export const appStoreCatalogUnavailableErrorCode = 'APPSTORE_CATALOG_UNAVAILABLE' as const;
+
+export interface IAppStoreCatalogUnavailableErrorData {
+  code: typeof appStoreCatalogUnavailableErrorCode;
+  retryable: true;
+  /** The status `cause` when the host states one. */
+  cause?: TAppStoreCatalogUnavailableCause;
+}
+
 /**
  * The App Store domain's state as an operator sees it, discriminated by `availability`.
  *
@@ -768,23 +794,167 @@ export const findAppStoreCatalogConfigDigestMismatch = async (
   return null;
 };
 
+/** The registries a consumer loads the catalog from when it configures none. */
+export const appStoreCatalogDefaultRegistries: readonly string[] = Object.freeze(['https://registry.npmjs.org']);
+
+const maximumRegistries = 16;
+const maximumRegistryUrlLength = 2048;
+
+/** The canonical base URL of one registry entry, or `null` when the entry is not admissible. */
+const readRegistryBaseUrl = (entryArg: unknown): string | null => {
+  if (typeof entryArg !== 'string' || entryArg.length > maximumRegistryUrlLength) return null;
+  let url: URL;
+  try {
+    url = new URL(entryArg);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== 'https:' || url.username !== '' || url.password !== '' || url.search !== ''
+    || url.hash !== '' || entryArg.includes('?') || entryArg.includes('#')) {
+    return null;
+  }
+  return url.toString().replace(/\/+$/, '');
+};
+
+/**
+ * The errors of a configured registry list; empty when a consumer may load from it. Every entry is
+ * an `https:` base URL without credentials, query or fragment, no two name the same registry, and
+ * an empty list means `appStoreCatalogDefaultRegistries`. Errors name entries by index and never
+ * quote them, so a URL carrying credentials does not reach a log.
+ */
+export const validateAppStoreCatalogRegistries = (listArg: unknown): string[] => {
+  const entries = readDataElements(listArg, maximumRegistries);
+  if (entries === null) return [`registries must be a list of at most ${maximumRegistries} URLs`];
+  const errors: string[] = [];
+  const seen = new Set<string>();
+  entries.forEach((entryArg, indexArg) => {
+    const baseUrl = readRegistryBaseUrl(entryArg);
+    if (baseUrl === null) {
+      errors.push(`registries[${indexArg}] must be an https base URL without credentials, query or fragment`);
+    } else if (seen.has(baseUrl)) {
+      errors.push(`registries[${indexArg}] names a registry listed before it`);
+    } else {
+      seen.add(baseUrl);
+    }
+  });
+  return errors;
+};
+
+/**
+ * The registry base URLs a consumer asks, in order: the configured list in canonical form (no
+ * trailing slash), or `appStoreCatalogDefaultRegistries` when it is absent or empty. Throws the
+ * `validateAppStoreCatalogRegistries` errors for a list it refuses.
+ */
+export const resolveAppStoreCatalogRegistries = (listArg: readonly string[] | undefined): string[] => {
+  const errors = validateAppStoreCatalogRegistries(listArg ?? []);
+  if (errors.length > 0) throw new Error(`App Store catalog registries refused: ${errors.join('; ')}`);
+  const configured = (listArg ?? []).map((entryArg) => readRegistryBaseUrl(entryArg))
+    .filter((entryArg): entryArg is string => entryArg !== null);
+  return configured.length > 0 ? configured : [...appStoreCatalogDefaultRegistries];
+};
+
+/**
+ * The App Store version a service runs, as its host took it from a verified catalog.
+ *
+ * Server-managed: a host writes it when it installs or upgrades the service and when it adopts an
+ * existing service on catalog activation, and every runtime path reads this snapshot, never the
+ * live catalog. Published versions never change (`judgeAppStoreCatalogSuccession`), so a snapshot
+ * stays equal to its catalog entry for as long as the entry is listed.
+ */
+export interface IAppStoreServiceTemplateSnapshot {
+  appId: string;
+  version: string;
+  /** The catalog entry's `configDigest`: `computeAppStoreCatalogConfigDigest(config)`. */
+  configDigest: TSha256Digest;
+  config: TAppStoreCatalogVersionConfig;
+  /** The `revision` of the catalog the snapshot was taken from. */
+  catalogRevision: number;
+}
+
+/**
+ * The snapshot of `appId@version` from a verified catalog, or `null` when the catalog does not list
+ * it. Withdrawn versions are listed and snapshot like any other: a host adopting an installed
+ * service records the version it runs; whether a version is an install or upgrade target is
+ * `judgeAppStoreCatalogInstallTarget`. The config is a copy the caller owns.
+ */
+export const createAppStoreServiceTemplateSnapshot = (
+  catalogArg: IAppStoreCatalog,
+  appIdArg: string,
+  versionArg: string,
+): IAppStoreServiceTemplateSnapshot | null => {
+  const entry = catalogArg.apps.find((appArg) => appArg.info.id === appIdArg)
+    ?.versions.find((candidateArg) => candidateArg.version === versionArg);
+  if (entry === undefined) return null;
+  return {
+    appId: appIdArg,
+    version: entry.version,
+    configDigest: entry.configDigest,
+    config: structuredClone(entry.config),
+    catalogRevision: catalogArg.revision,
+  };
+};
+
+/** The hosts that consume the catalog; each version names its minimum release of each. */
+export type TAppStoreCatalogConsumerKind = 'onebox' | 'cloudly';
+
+/** The consumer judging a version: which host it is and the release it runs. */
+export interface IAppStoreCatalogConsumer {
+  kind: TAppStoreCatalogConsumerKind;
+  /** The host's own release, `MAJOR.MINOR.PATCH`. */
+  version: string;
+}
+
+const consumerMinimumVersionKeys = Object.freeze({
+  onebox: 'minOneboxVersion',
+  cloudly: 'minCloudlyVersion',
+} as const);
+
 /** Why a listed version is not an install or upgrade target for this consumer. */
 export type TAppStoreCatalogInstallTargetRefusal =
   | { reason: 'versionWithdrawn'; withdrawal: IAppStoreCatalogWithdrawal }
-  | { reason: 'featuresUnsupported'; missingFeatureIds: string[] };
+  | { reason: 'featuresUnsupported'; missingFeatureIds: string[] }
+  /** The version names a minimum release of this host (`minOneboxVersion`, `minCloudlyVersion`) newer than it runs. */
+  | {
+    reason: 'consumerVersionTooOld';
+    consumerKind: TAppStoreCatalogConsumerKind;
+    consumerVersion: string;
+    minimumVersion: string;
+  };
 
 /**
  * Whether a consumer may install a listed version, or upgrade a service to it; `null` when it may.
- * A withdrawn version and a version requiring a feature the consumer does not fulfil stay listed
- * and are refused here, and nowhere else is a second answer needed.
+ * A withdrawn version, a version requiring a feature the consumer does not fulfil and a version
+ * requiring a newer release of the consumer stay listed and are refused here, in that order, and
+ * nowhere else is a second answer needed.
+ *
+ * A host passes `consumerArg` on every call; without it the minimum release is not judged. A
+ * consumer version that is not `MAJOR.MINOR.PATCH` throws: it is the host's own constant.
  */
 export const judgeAppStoreCatalogInstallTarget = (
   versionArg: IAppStoreCatalogVersion,
   supportedFeatureIdsArg: Iterable<string>,
+  consumerArg?: IAppStoreCatalogConsumer,
 ): TAppStoreCatalogInstallTargetRefusal | null => {
+  const consumerVersion = consumerArg === undefined ? null : parseReleaseVersion(consumerArg.version);
+  if (consumerArg !== undefined && consumerVersion === null) {
+    throw new Error('App Store catalog consumer version must be MAJOR.MINOR.PATCH');
+  }
   if (versionArg.withdrawn !== undefined) return { reason: 'versionWithdrawn', withdrawal: versionArg.withdrawn };
   const missingFeatureIds = getAppStoreCatalogMissingFeatureIds(versionArg.config, supportedFeatureIdsArg);
-  return missingFeatureIds.length > 0 ? { reason: 'featuresUnsupported', missingFeatureIds } : null;
+  if (missingFeatureIds.length > 0) return { reason: 'featuresUnsupported', missingFeatureIds };
+  if (consumerArg === undefined || consumerVersion === null) return null;
+  const minimumVersion = versionArg.config[consumerMinimumVersionKeys[consumerArg.kind]];
+  if (minimumVersion === undefined) return null;
+  const minimum = parseReleaseVersion(minimumVersion);
+  if (minimum === null || compareReleaseVersions(consumerVersion, minimum) < 0) {
+    return {
+      reason: 'consumerVersionTooOld',
+      consumerKind: consumerArg.kind,
+      consumerVersion: consumerArg.version,
+      minimumVersion,
+    };
+  }
+  return null;
 };
 
 export type TAppStoreCatalogSuccession =

package/ts/appstore/types.ts

@@ -27,6 +27,7 @@ import type {
   TStorageResourceKind,
   TStorageSnapshotMode,
 } from '../platform/storage.js';
+import type { TAppStoreCatalogInstallTargetRefusal } from './catalog.js';
 
 export type TAppStorePlatformRequirement =
   | 'mongodb'
@@ -314,6 +315,18 @@ export const validateAppStoreVersionPlatformOidc = (
   return errors;
 };
 
+/** One listed version of an app as a host shows it: an install target, or why it is not one. */
+export interface IAppStoreAppVersionState {
+  version: string;
+  /**
+   * `null` when the host may install the version or upgrade a service to it; otherwise
+   * `versionWithdrawn` with the withdrawal, `featuresUnsupported` with the feature ids the host
+   * does not fulfil or `consumerVersionTooOld` with the host release the version requires, as
+   * `judgeAppStoreCatalogInstallTarget` answers it.
+   */
+  installRefusal: TAppStoreCatalogInstallTargetRefusal | null;
+}
+
 export interface IAppStoreApp {
   id: string;
   name: string;
@@ -323,6 +336,12 @@ export interface IAppStoreApp {
   iconUrl?: string;
   latestVersion: string;
   versions?: string[];
+  /**
+   * Every version the catalog lists, withdrawn and feature-gated ones included, in catalog order,
+   * each with whether this host may install it. `versions` names only the install targets; a view
+   * reads this member to show the others and why they are not offered.
+   */
+  versionStates?: IAppStoreAppVersionState[];
   tags?: string[];
   channel?: string;
   upgradeStrategy?: TAppStoreUpgradeStrategy;
@@ -346,6 +365,12 @@ export interface IAppStoreAppMeta {
   iconName?: string;
   latestVersion: string;
   versions: string[];
+  /**
+   * Every version the catalog lists, withdrawn and feature-gated ones included, in catalog order,
+   * each with whether this host may install it. `versions` names only the install targets; a view
+   * reads this member to show the others and why they are not offered.
+   */
+  versionStates?: IAppStoreAppVersionState[];
   maintainer?: string;
   links?: Record<string, string>;
   tags?: string[];

package/ts/data/clusternodehostname.ts

@@ -6,7 +6,7 @@ import { readExactDataRecord } from '../private/dataproperties.js';
  * Cloudly owns the hostname a node should carry (`IClusterNode.data.hostnameIntent`); Spark applies
  * it on the host and reports the hostname it observes, so a node has converged when its report
  * states the intent's hostname. The default scheme is `cloudly-worker-<name>`: `name` is the
- * operator's short name for the node (`ottilie`, `grasberg`), kept beside the hostname so the node
+ * operator's short name for the node (`alpha`, `bravo`), kept beside the hostname so the node
  * can always be reset to the default however it was renamed.
  *
  * A hostname here is one RFC 1123 label, lowercase: the node's short static hostname, which is
@@ -51,8 +51,8 @@ export const deriveDefaultClusterNodeHostname = (nameArg: string): string => {
  *
  * It reads the first label of the hostname, so a report that states a dotted name proposes its
  * short name. A label already in the default scheme proposes what follows the prefix
- * (`cloudly-worker-ottilie` → `ottilie`); any other valid label proposes itself unchanged
- * (`cloudlyworkergrasberg` stays `cloudlyworkergrasberg`). It never guesses a name out of a
+ * (`cloudly-worker-bravo` → `bravo`); any other valid label proposes itself unchanged
+ * (`cloudlyworkeralpha` stays `cloudlyworkeralpha`). It never guesses a name out of a
  * label in another scheme: an operator states that name when resetting the node to the default.
  */
 export const proposeClusterNodeName = (hostnameArg: string): string | null => {

package/ts/data/service.ts

@@ -1,6 +1,6 @@
 import type { IServiceRessources } from './docker.js';
 import type { IRegistryTarget } from './registry.js';
-import type { IAppStorePublishedPort } from '../appstore/index.js';
+import type { IAppStorePublishedPort, IAppStoreServiceTemplateSnapshot } from '../appstore/index.js';
 import type { IHostedAppLifecycleState } from './hostedapp.js';
 import type { IServiceMailConfig, TServiceMailWritableConfig } from './mail.js';
 import type { IServiceWebPushConfig } from './webpush.js';
@@ -175,6 +175,12 @@ export interface IService {
     appTemplateId?: string;
     appTemplateVersion?: string;
     appStoreUpgradePolicy?: 'manual' | 'notify' | 'auto';
+    /**
+     * Server-managed snapshot of the App Store version the service runs (`appTemplateId`@
+     * `appTemplateVersion`), written at install, upgrade and catalog adoption. Runtime paths read
+     * it instead of the live catalog.
+     */
+    appStoreTemplate?: IAppStoreServiceTemplateSnapshot;
     hostedAppLifecycle?: IHostedAppLifecycleState;
     reconciliationStatus?: IServiceReconciliationStatus;
     environment: { [key: string]: string };
@@ -254,11 +260,13 @@ export interface IService {
 
 /**
  * Caller-writable service data. Immutable rollout state and SecretSet
- * attachments are changed only through their dedicated fenced APIs.
+ * attachments are changed only through their dedicated fenced APIs, and the
+ * App Store template snapshot only by the host's install and upgrade.
  */
 export type TServiceWritableData = Omit<
   IService['data'],
   | 'organizationId'
+  | 'appStoreTemplate'
   | 'immutableImageRequired'
   | 'imageDeployment'
   | 'imageRolloutStatus'

package/ts/data/settings.ts

@@ -63,6 +63,12 @@ export interface ICloudlySettings {
   coreMailDefaultMaxPendingInbound?: number;
   corebuildWorkerUrl?: string;
   corebuildWorkerUrls?: string[];
+  /**
+   * The npm registries Cloudly loads the App Store catalog from, in order. Absent or empty means
+   * `appstore.appStoreCatalogDefaultRegistries`; a value is accepted only when
+   * `appstore.validateAppStoreCatalogRegistries` answers no error.
+   */
+  appStoreCatalogRegistries?: string[];
 }
 
 export const cloudlySystemSecretOwner = Object.freeze({

package/ts/requests/appstore.ts

@@ -112,6 +112,28 @@ export interface IReq_Any_RefreshAppStoreCatalog extends plugins.typedrequestInt
   };
 }
 
+/**
+ * Imports a signed catalog envelope an operator carried in (an air-gapped host, or a catalog the
+ * registries do not serve yet) and answers the state after it. The host judges it exactly as a
+ * fetched one, authentication and succession included, and records it with origin
+ * `operatorImport`; the outcome is `status.lastAttempt`, and a refused envelope keeps the active
+ * catalog in place and is not a request error.
+ */
+export interface IReq_Any_ImportAppStoreCatalog extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_ImportAppStoreCatalog
+> {
+  method: 'importAppStoreCatalog';
+  request: {
+    identity: IIdentity;
+    /** The envelope file's text (`IAppStoreCatalogEnvelope` as JSON), e.g. `catalog.envelope.json`. */
+    envelopeText: string;
+  };
+  response: {
+    status: TAppStoreCatalogStatus;
+  };
+}
+
 export interface IReq_Any_GetAppStoreConfig extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_Any_GetAppStoreConfig

package/ts/requests/hostedapp.ts

@@ -32,6 +32,12 @@ export interface IReq_GetHostedAppAccessConfiguration extends plugins.typedreque
       roles: data.IHostedAppRoleDefinition[];
       platformOidcSupported: boolean;
       platformOidcRegistration?: data.IHostedAppPlatformOidcRegistration;
+      /**
+       * Present when the host cannot read this app's roles and platform OIDC capability, e.g. the
+       * service holds no App Store template snapshot yet; `roles` is then empty and
+       * `platformOidcSupported` false. One such app never fails the whole listing.
+       */
+      unavailableReason?: string;
     }>;
   };
 }

package/ts/requests/node.ts

@@ -369,7 +369,7 @@ export interface IReq_Any_Cloudly_SetClusterNodeCorestoreDatabaseEndpoint extend
  *
  * The node's name stays as it is: the new intent keeps the name of the node's current intent. A
  * node without an intent takes the name `data.proposeClusterNodeName(hostname)` (`foo` names the
- * node `foo`, `cloudly-worker-grasberg` names it `grasberg`), and is refused `name-invalid` when
+ * node `foo`, `cloudly-worker-alpha` names it `alpha`), and is refused `name-invalid` when
  * that is `null`.
  *
  * Cloudly records the intent and answers at once; Spark applies the intent of the latest

package/ts/requests/service.ts

@@ -262,6 +262,11 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+/**
+ * Answers one deployment operation's status and advances it: a rolling-out operation whose runtime
+ * evidence proves success or failure is transitioned before the answer. A deployment that polls
+ * its own rollout uses it; an inspection uses `readServiceDeploymentStatus`.
+ */
 export interface IRequest_Any_Cloudly_GetServiceDeploymentStatus
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -278,6 +283,29 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+/**
+ * Answers one deployment operation's status, as `getServiceDeploymentStatus` projects it, and
+ * changes nothing: no transition, no failure recorded, no recovery scheduled. A rollout failure or
+ * an expired startup grace shows in the returned evidence only, and the persisted operation keeps
+ * its state, revision, timestamps and evidence. It takes the same identity and the
+ * `deployment:status` capability.
+ */
+export interface IRequest_Any_Cloudly_ReadServiceDeploymentStatus
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_ReadServiceDeploymentStatus
+> {
+  method: 'readServiceDeploymentStatus';
+  request: {
+    identity: IIdentityCredential;
+    serviceId: string;
+    operationId: string;
+  };
+  response: {
+    status: IServiceDeploymentStatus;
+  };
+}
+
 export interface IRequest_Any_Cloudly_PromoteServiceDeploymentRoute
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,