@serve.zone/interfaces 32.35.0 → 32.36.1

package/ts/data/deploymentoperation.ts

@@ -2,6 +2,8 @@ import type { IDeploymentPreflightProposedConfiguration, IDeploymentPreflightRun
 import type { IGatewayRouteDnsResult } from './gateway.js';
 import type { IImageRolloutStatus, IImmutableImageDeploymentPlan, TSha256Digest } from './immutableimage.js';
 import { normalizeImmutableReleaseTag, normalizeSha256Digest } from './immutableimage.js';
+import type { ILegacyImageImportReference } from './deploymentlegacyimport.js';
+import { validateLegacyImageImportReference } from './deploymentlegacyimport.js';
 import type { IRegistryTarget } from './registry.js';
 import { hasExactKeys } from '../private/dataproperties.js';
 import { normalizeServiceAbsolutePath, validateServiceContainerArgs } from './service.js';
@@ -14,7 +16,6 @@ interface IDeploymentReservationInputBase {
   organizationId: string;
   serviceId: string;
   idempotencyKey: string;
-  sourceRevision: string;
   version: string;
   intentDigest: TSha256Digest;
   proposedConfiguration: IDeploymentPreflightProposedConfiguration;
@@ -22,15 +23,38 @@ interface IDeploymentReservationInputBase {
   routes: IDeploymentRouteRequest[];
 }
 
+/** A deployment whose image its deployer builds and pushes from one source revision. */
+interface ISourceDeploymentOrigin {
+  sourceRevision: string;
+  legacyImport?: never;
+}
+
+/**
+ * A greenfield deployment whose image Cloudly imports from an attested legacy service instead:
+ * there is no source revision, so none is stated.
+ */
+interface ILegacyImportDeploymentOrigin {
+  legacyImport: ILegacyImageImportReference;
+  sourceRevision?: never;
+}
+
 export interface IExistingServiceDeploymentReservationInput
-extends IDeploymentReservationInputBase {
+extends IDeploymentReservationInputBase, ISourceDeploymentOrigin {
   mode: 'existing-service';
   expectedRolloutGeneration: number;
   expectedCurrentRolloutId?: string;
 }
 
 export interface IGreenfieldServiceDeploymentReservationInput
-extends IDeploymentReservationInputBase {
+extends IDeploymentReservationInputBase, ISourceDeploymentOrigin {
+  mode: 'greenfield';
+  expectedRolloutGeneration?: never;
+  expectedCurrentRolloutId?: never;
+}
+
+/** A greenfield successor slot whose image is a legacy service's attested image. */
+export interface ILegacyImportServiceDeploymentReservationInput
+extends IDeploymentReservationInputBase, ILegacyImportDeploymentOrigin {
   mode: 'greenfield';
   expectedRolloutGeneration?: never;
   expectedCurrentRolloutId?: never;
@@ -38,7 +62,8 @@ extends IDeploymentReservationInputBase {
 
 export type IDeploymentReservationInput =
   | IExistingServiceDeploymentReservationInput
-  | IGreenfieldServiceDeploymentReservationInput;
+  | IGreenfieldServiceDeploymentReservationInput
+  | ILegacyImportServiceDeploymentReservationInput;
 
 export type TDeploymentOperationState =
   | 'reserving'
@@ -240,7 +265,15 @@ export const validateDeploymentReservationInput = (inputArg: unknown): string[]
       errors.push(`${field} must be a bounded canonical identifier`);
     }
   }
-  if (typeof inputArg.sourceRevision !== 'string'
+  if (inputArg.legacyImport !== undefined) {
+    errors.push(...validateLegacyImageImportReference(inputArg.legacyImport));
+    if (inputArg.mode !== 'greenfield') {
+      errors.push('a legacy import reserves a greenfield successor');
+    }
+    if (inputArg.sourceRevision !== undefined) {
+      errors.push('a legacy import has no source revision');
+    }
+  } else if (typeof inputArg.sourceRevision !== 'string'
     || !fullGitRevisionRegex.test(inputArg.sourceRevision)) {
     errors.push('sourceRevision must be a full lowercase git revision');
   }
@@ -394,40 +427,51 @@ export interface IDeploymentOperationFailure {
 export interface IServiceDeploymentOperation {
   id: string;
   revision: number;
-  data: {
-    mode: TDeploymentOperationMode;
-    organizationId: string;
-    serviceId: string;
-    actorUserId: string;
-    idempotencyKey: string;
-    requestDigest: TSha256Digest;
-    sourceRevision: string;
-    version: string;
-    intentDigest: TSha256Digest;
-    configurationDigest: TSha256Digest;
-    proposedConfiguration: IDeploymentPreflightProposedConfiguration;
-    namespace: string;
-    registryTarget: IRegistryTarget;
-    releaseTag: string;
-    routes: IDeploymentRouteRequest[];
-    claimKeys: string[];
-    state: TDeploymentOperationState;
-    releaseId?: string;
-    registryRootDigest?: TSha256Digest;
-    rolloutId?: string;
-    rolloutGeneration?: number;
-    routeGeneration?: number;
-    routeVerification?: IDeploymentRouteVerificationEvidence[];
-    /**
-     * Most recent failure record. Set when the operation fails and retained
-     * as audit history through 'cleaning' and 'cleaned'; cleared only by a
-     * forward transition such as a successful retry. A populated failure does
-     * therefore NOT imply state === 'failed'.
-     */
-    failure?: IDeploymentOperationFailure;
-    createdAt: number;
-    updatedAt: number;
-  };
+  data: IServiceDeploymentOperationData;
+}
+
+/**
+ * An operation's durable state. It states where its image comes from exactly as its reservation
+ * did: a `sourceRevision` for an image its deployer builds, or a `legacyImport` (greenfield only)
+ * for a legacy service's attested image Cloudly imports.
+ */
+export type IServiceDeploymentOperationData = IServiceDeploymentOperationStateData & (
+  | ISourceDeploymentOrigin
+  | ILegacyImportDeploymentOrigin
+);
+
+interface IServiceDeploymentOperationStateData {
+  mode: TDeploymentOperationMode;
+  organizationId: string;
+  serviceId: string;
+  actorUserId: string;
+  idempotencyKey: string;
+  requestDigest: TSha256Digest;
+  version: string;
+  intentDigest: TSha256Digest;
+  configurationDigest: TSha256Digest;
+  proposedConfiguration: IDeploymentPreflightProposedConfiguration;
+  namespace: string;
+  registryTarget: IRegistryTarget;
+  releaseTag: string;
+  routes: IDeploymentRouteRequest[];
+  claimKeys: string[];
+  state: TDeploymentOperationState;
+  releaseId?: string;
+  registryRootDigest?: TSha256Digest;
+  rolloutId?: string;
+  rolloutGeneration?: number;
+  routeGeneration?: number;
+  routeVerification?: IDeploymentRouteVerificationEvidence[];
+  /**
+   * Most recent failure record. Set when the operation fails and retained
+   * as audit history through 'cleaning' and 'cleaned'; cleared only by a
+   * forward transition such as a successful retry. A populated failure does
+   * therefore NOT imply state === 'failed'.
+   */
+  failure?: IDeploymentOperationFailure;
+  createdAt: number;
+  updatedAt: number;
 }
 
 export interface IServiceDeploymentStatus {

package/ts/data/deploymentpreflight.ts

@@ -5,6 +5,8 @@ import type {
 } from './immutableimage.js';
 import { normalizeImmutableReleaseTag, normalizeSha256Digest } from './immutableimage.js';
 import type { TServiceDeploymentCapability } from './user.js';
+import type { ILegacyImageImportReference } from './deploymentlegacyimport.js';
+import { validateLegacyImageImportReference } from './deploymentlegacyimport.js';
 import { validateProtocolOfferOn, type IProtocolOffer } from '../protocol.js';
 import type {
   IDeploymentRouteRequest,
@@ -84,6 +86,19 @@ export const deploymentPreflightBlockerCodes = [
   'RELAY_NAME_RESERVED',
   'ROUTE_VERIFICATION_FAILED',
   'TLS_VERIFICATION_FAILED',
+  /**
+   * A legacy import names no attestation Cloudly holds for that legacy service in the requested
+   * organization. Evidence is captured only while the legacy runtime runs, so there is no later
+   * substitute for a missing one.
+   */
+  'LEGACY_IMPORT_ATTESTATION_MISSING',
+  /**
+   * The attested legacy image is no longer what the request or the registry states: the asserted
+   * root digest differs, the legacy tag moved, or a manifest the attestation names is gone.
+   */
+  'LEGACY_IMPORT_SOURCE_MISMATCH',
+  /** The declared target platforms are not exactly the platforms the attested image carries. */
+  'LEGACY_IMPORT_PLATFORM_MISMATCH',
 ] as const;
 
 export type TDeploymentPreflightBlockerCode = typeof deploymentPreflightBlockerCodes[number];
@@ -93,7 +108,9 @@ export interface IDeploymentPreflightBlocker {
   message: string;
 }
 
-export type TDeploymentPreflightWarningCode = 'RECOVERY_REDEPLOY_OVER_FAILED_RUNTIME';
+export type TDeploymentPreflightWarningCode =
+  | 'RECOVERY_REDEPLOY_OVER_FAILED_RUNTIME'
+  | 'PLATFORM_BINDING_READINESS_DEFERRED';
 
 /**
  * Auditable non-blocking preflight finding. Warnings never veto a decision.
@@ -102,7 +119,16 @@ export type TDeploymentPreflightWarningCode = 'RECOVERY_REDEPLOY_OVER_FAILED_RUN
  * RUNTIME_ATTESTATION_MISMATCH blockers because the current runtime provides
  * no consistent attested digest and the service's most recent deployment
  * operation ended 'failed' or 'cleaned' (a recovery redeploy over a known-bad
- * runtime). No other blocker is ever relaxed.
+ * runtime).
+ * `PLATFORM_BINDING_READINESS_DEFERRED` documents that the promote preflight
+ * of a held greenfield service that was never promoted accepted a Corestore
+ * `database` or `objectstorage` binding that is enabled but not yet `ready`.
+ * A held service receives no credential material, so its binding can become
+ * ready only after promotion releases the hold; for a binding that adopts a
+ * legacy resource the Corestore inventory proved the resource authorized for
+ * exactly that binding. The route preflight still requires the binding
+ * `ready`, so no traffic reaches the service before its binding is.
+ * No other blocker is ever relaxed.
  */
 export interface IDeploymentPreflightWarning {
   code: TDeploymentPreflightWarningCode;
@@ -193,21 +219,39 @@ export interface IDeploymentReleaseEvidence {
   attestations: IDeploymentReleaseEvidenceReference[];
 }
 
-export interface IDeploymentPreflightRequestData {
+/**
+ * A preflight states where the deployment's image comes from, exactly as its reservation will:
+ * a clean source revision with its release evidence, or — for a greenfield successor only — a
+ * legacy import naming an attested legacy image, which has no revision, worktree or build
+ * evidence to state.
+ */
+export type IDeploymentPreflightRequestData = IDeploymentPreflightRequestDataBase & (
+  | {
+    sourceRevision: string;
+    sourceDirty: boolean;
+    releaseEvidence?: IDeploymentReleaseEvidence;
+    legacyImport?: never;
+  }
+  | {
+    legacyImport: ILegacyImageImportReference;
+    sourceRevision?: never;
+    sourceDirty?: never;
+    releaseEvidence?: never;
+  }
+);
+
+interface IDeploymentPreflightRequestDataBase {
   requestId: string;
   serviceId: string;
   organizationId?: string;
   mode?: TDeploymentOperationMode;
   phase?: TDeploymentOperationPhase;
   operationId?: string;
-  sourceRevision: string;
-  sourceDirty: boolean;
   version: string;
   intentDigest: string;
   proposedConfiguration: IDeploymentPreflightProposedConfiguration;
   ociIndexDigest?: string;
   releaseTag?: string;
-  releaseEvidence?: IDeploymentReleaseEvidence;
   routes?: IDeploymentRouteRequest[];
   /** Legacy v14 discriminator. Equivalent to mode: 'greenfield'. */
   greenfield?: true;
@@ -249,13 +293,15 @@ export interface IDeploymentPreflightReport {
   mode?: TDeploymentOperationMode;
   phase?: TDeploymentOperationPhase;
   operation?: IServiceDeploymentOperation;
+  /** The request's image origin as judged: a source revision, or a legacy import. */
   source: {
-    revision: string;
-    dirty: boolean;
     version: string;
     intentDigest: TSha256Digest;
     configurationDigest: TSha256Digest;
-  };
+  } & (
+    | { revision: string; dirty: boolean; legacyImport?: never }
+    | { legacyImport: ILegacyImageImportReference; revision?: never; dirty?: never }
+  );
   currentImage: {
     tag?: string;
     digest?: TSha256Digest;
@@ -339,16 +385,35 @@ export const validateDeploymentPreflightRequest = (
   if (typeof requestArg.serviceId !== 'string' || !requestArg.serviceId.trim() || requestArg.serviceId.length > 200) {
     blockers.push({ code: 'INVALID_REQUEST', message: 'A bounded service identifier is required.' });
   }
-  if (typeof requestArg.sourceRevision !== 'string' || !fullGitRevisionRegex.test(requestArg.sourceRevision)) {
-    blockers.push({ code: 'SOURCE_REVISION_INVALID', message: 'Source revision must be a full lower-case Git commit SHA.' });
-    if (typeof requestArg.sourceRevision !== 'string') {
-      blockers.push({ code: 'INVALID_REQUEST', message: 'Source revision is malformed.' });
+  const legacyImport = requestArg.legacyImport !== undefined;
+  if (legacyImport) {
+    const referenceErrors = validateLegacyImageImportReference(requestArg.legacyImport);
+    if (referenceErrors.length > 0) {
+      blockers.push({
+        code: 'INVALID_REQUEST',
+        message: `The legacy import reference is malformed: ${referenceErrors.join('; ')}.`,
+      });
+    }
+    if (requestArg.sourceRevision !== undefined
+      || requestArg.sourceDirty !== undefined
+      || requestArg.releaseEvidence !== undefined) {
+      blockers.push({
+        code: 'INVALID_REQUEST',
+        message: 'A legacy import states no source revision, worktree state or release evidence.',
+      });
+    }
+  } else {
+    if (typeof requestArg.sourceRevision !== 'string' || !fullGitRevisionRegex.test(requestArg.sourceRevision)) {
+      blockers.push({ code: 'SOURCE_REVISION_INVALID', message: 'Source revision must be a full lower-case Git commit SHA.' });
+      if (typeof requestArg.sourceRevision !== 'string') {
+        blockers.push({ code: 'INVALID_REQUEST', message: 'Source revision is malformed.' });
+      }
+    }
+    if (typeof requestArg.sourceDirty !== 'boolean') {
+      blockers.push({ code: 'INVALID_REQUEST', message: 'Source worktree state must be reported.' });
+    } else if (requestArg.sourceDirty) {
+      blockers.push({ code: 'SOURCE_WORKTREE_DIRTY', message: 'The source worktree contains uncommitted changes.' });
     }
-  }
-  if (typeof requestArg.sourceDirty !== 'boolean') {
-    blockers.push({ code: 'INVALID_REQUEST', message: 'Source worktree state must be reported.' });
-  } else if (requestArg.sourceDirty) {
-    blockers.push({ code: 'SOURCE_WORKTREE_DIRTY', message: 'The source worktree contains uncommitted changes.' });
   }
   if (typeof requestArg.version !== 'string'
     || requestArg.version.length > 100
@@ -397,6 +462,9 @@ export const validateDeploymentPreflightRequest = (
     && (requestArg.greenfield !== true || mode !== 'greenfield')) {
     blockers.push({ code: 'INVALID_REQUEST', message: 'Legacy greenfield mode is contradictory.' });
   }
+  if (legacyImport && mode !== 'greenfield') {
+    blockers.push({ code: 'INVALID_REQUEST', message: 'A legacy import reserves a greenfield successor.' });
+  }
   if (requestArg.phase !== undefined
     && requestArg.phase !== 'reserve'
     && requestArg.phase !== 'promote'

package/ts/data/immutableimage.ts

@@ -173,8 +173,7 @@ export interface IImageRelease {
   };
 }
 
-export interface IImageReleaseTrustedEvidence {
-  source: 'cloudly-registry';
+interface IImageReleaseTrustedEvidenceBase {
   /** Deterministic ID for an authenticated registry acceptance event/retry. */
   evidenceId: string;
   operationId: string;
@@ -187,6 +186,30 @@ export interface IImageReleaseTrustedEvidence {
   recordedAt: number;
 }
 
+/** The deployment machine user's own authenticated registry push to its operation's tag. */
+export interface IImageReleaseRegistryPushEvidence extends IImageReleaseTrustedEvidenceBase {
+  source: 'cloudly-registry';
+}
+
+/**
+ * Cloudly's own import of an attested legacy image into a legacy-import operation's tag.
+ *
+ * Nothing was built or pushed: the source fields name the legacy registry root the attestation
+ * proved ran, and `registryRootDigest` is that root or the index Cloudly wrapped around it.
+ */
+export interface IImageReleaseLegacyImportEvidence extends IImageReleaseTrustedEvidenceBase {
+  source: 'cloudly-legacy-import';
+  legacyServiceId: string;
+  attestationId: string;
+  sourceRepository: string;
+  sourceTag: string;
+  sourceRootDigest: TSha256Digest;
+}
+
+export type IImageReleaseTrustedEvidence =
+  | IImageReleaseRegistryPushEvidence
+  | IImageReleaseLegacyImportEvidence;
+
 export const selectTrustedImageReleaseEvidence = (argsArg: {
   release: IImageRelease;
   operationId: string;
@@ -197,7 +220,14 @@ export const selectTrustedImageReleaseEvidence = (argsArg: {
   repository: string;
   tag: string;
   digest: TSha256Digest;
+  /**
+   * The one evidence source the operation's image may have come from: a legacy-import operation
+   * accepts only Cloudly's import, every other operation only its actor's registry push. Omitted,
+   * it is the registry push, the only source an operation without a legacy import has.
+   */
+  evidenceSource?: IImageReleaseTrustedEvidence['source'];
 }): { evidence?: IImageReleaseTrustedEvidence; errors: string[] } => {
+  const evidenceSource = argsArg.evidenceSource ?? 'cloudly-registry';
   const evidenceFingerprint = (evidenceArg: IImageReleaseTrustedEvidence) => [
     evidenceArg.source,
     evidenceArg.evidenceId,
@@ -209,6 +239,15 @@ export const selectTrustedImageReleaseEvidence = (argsArg: {
     evidenceArg.registryRootDigest,
     evidenceArg.manifestMediaType,
     evidenceArg.recordedAt,
+    ...(evidenceArg.source === 'cloudly-legacy-import'
+      ? [
+        evidenceArg.legacyServiceId,
+        evidenceArg.attestationId,
+        evidenceArg.sourceRepository,
+        evidenceArg.sourceTag,
+        evidenceArg.sourceRootDigest,
+      ]
+      : []),
   ].join('\u0000');
   const uniqueEvidence = new Map<string, IImageReleaseTrustedEvidence>();
   const errors: string[] = [];
@@ -221,7 +260,7 @@ export const selectTrustedImageReleaseEvidence = (argsArg: {
     }
   }
   const evidenceMatches = [...uniqueEvidence.values()].filter((evidenceArg) => (
-    evidenceArg.source === 'cloudly-registry'
+    evidenceArg.source === evidenceSource
     && evidenceArg.operationId === argsArg.operationId
     && evidenceArg.actorUserId === argsArg.actorUserId
     && evidenceArg.registryHost === argsArg.registryHost

package/ts/data/index.ts

@@ -12,6 +12,7 @@ export * from './coremail.js';
 export * from './coremail.runtime.js';
 export * from './deployment.js';
 export * from './deploymentadoption.js';
+export * from './deploymentlegacyimport.js';
 export * from './deploymentmachineuser.js';
 export * from './deploymentoperation.js';
 export * from './deploymentpreflight.js';
@@ -52,9 +53,13 @@ export * from './privatenetwork.js';
 export * from './registry.js';
 export * from './releaseversion.js';
 export * from './runtimeassignment.js';
+export * from './runtimeassignmentexec.js';
+export * from './runtimeassignmentlogs.js';
+export * from './runtimeassignmentstats.js';
 export * from './runtimeconfig.js';
 export * from './runtimestorageclaim.js';
 export * from './runtimelocalstorageclaim.js';
+export * from './runtimelocalvolumearchive.js';
 export * from './runtimesession.js';
 export * from './runtimeterminalreceipt.js';
 export * from './secret.js';