@serve.zone/interfaces 11.3.0 → 12.0.0

package/changelog.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 2026-07-19 - 12.0.0
+
+### Fixes
+
+- make greenfield deployment preflight evidence fail closed (deployment)
+  - Distinguish the client intent digest from Cloudly's server-computed configuration digest.
+  - Report dirty source, registry host, complete replica counts, explicit proposed storage resources, and unknown namespace safety.
+  - Define an admin-only, idempotent machine-user grant normalization request without returning token material.
+
+## 2026-07-19 - 11.4.0
+
+### Features
+
+- define least-privilege greenfield deployment preflight contracts (deployment)
+  - Add server-persisted, service-scoped machine capabilities without broad cluster authority.
+  - Define sanitized GO/NO-GO inventory for OCI indexes, runtime digests, Corestore bindings, and namespace collisions.
+  - Bind release evidence and future durable operations to source, version, image, configuration, and namespace digests.
+
+### Maintenance
+
+- replace the broken pnpm 11.13.0 executable pin with pnpm 11.15.0.
+
 ## 2026-07-18 - 11.3.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '11.3.0',
+    version: '12.0.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/data/deploymentpreflight.d.ts

@@ -0,0 +1,160 @@
+import type { TOciManifestMediaType, TSha256Digest } from './immutableimage.js';
+import type { TServiceDeploymentCapability } from './user.js';
+export type TDeploymentPreflightDecision = 'GO' | 'NO-GO';
+export type TDeploymentPreflightBlockerCode = 'INVALID_REQUEST' | 'AUTHORIZATION_MISSING' | 'SOURCE_REVISION_INVALID' | 'SOURCE_WORKTREE_DIRTY' | 'VERSION_NOT_RESERVED' | 'VERSION_COLLISION' | 'NAMESPACE_NOT_RESERVED' | 'NAMESPACE_COLLISION' | 'NAMESPACE_NOT_PROVEN_BLANK' | 'CONFIGURATION_DIGEST_INVALID' | 'INTENT_DIGEST_INVALID' | 'CURRENT_REFERENCE_MUTABLE' | 'CURRENT_RUNTIME_DIGEST_MISSING' | 'OCI_INDEX_DIGEST_REQUIRED' | 'OCI_INDEX_NOT_FOUND' | 'OCI_INDEX_MEDIA_TYPE_REQUIRED' | 'OCI_PLATFORM_MISSING' | 'OCI_PLATFORM_MANIFEST_MISSING' | 'IMMUTABLE_RELEASE_TAG_REQUIRED' | 'IMMUTABLE_RELEASE_TAG_NOT_RESERVED' | 'RELEASE_EVIDENCE_MISSING' | 'RELEASE_EVIDENCE_INVALID' | 'RELEASE_NOT_AUTHORIZED' | 'GREENFIELD_EXECUTION_UNAVAILABLE' | 'ROUTE_PROMOTION_FENCE_UNAVAILABLE' | 'POST_DEPLOYMENT_VERIFICATION_UNAVAILABLE' | 'WOULD_REPLACE_EXISTING_STATE' | 'CORESTORE_INVENTORY_UNAVAILABLE' | 'RUNTIME_ATTESTATION_MISMATCH';
+export interface IDeploymentPreflightBlocker {
+    code: TDeploymentPreflightBlockerCode;
+    message: string;
+}
+export interface IDeploymentPreflightAuthorizationCheck {
+    capability: TServiceDeploymentCapability;
+    granted: boolean;
+}
+export interface IOciPlatformDescriptorSummary {
+    os: string;
+    architecture: string;
+    digest?: TSha256Digest;
+    mediaType?: string;
+    runnable: boolean;
+    manifestPresent: boolean;
+}
+export interface IDeploymentPreflightRuntimeTask {
+    deploymentId: string;
+    nodeName?: string;
+    status: string;
+    healthStatus?: string;
+    imageReference?: string;
+    reportedDigest?: TSha256Digest;
+    verificationStatus?: 'not-required' | 'pending' | 'verified' | 'missing' | 'mismatched';
+}
+export interface IDeploymentPreflightPlatformBinding {
+    capability: 'database' | 'objectstorage';
+    desiredState: 'enabled' | 'disabled';
+    status: 'requested' | 'provisioning' | 'ready' | 'degraded' | 'failed' | 'disabled';
+}
+export interface IDeploymentPreflightCorestoreResource {
+    capability: 'database' | 'objectstorage';
+    provider: string;
+    resourceName: string;
+}
+export interface IDeploymentPreflightProposedCorestoreResource {
+    capability: 'database' | 'objectstorage';
+    resourceName: string;
+}
+export interface IDeploymentReleaseEvidenceReference {
+    kind: 'provenance' | 'sbom' | 'signature' | 'vulnerability-policy' | 'release-authorization';
+    statementDigest: TSha256Digest;
+    subjectDigest: TSha256Digest;
+    verifier: string;
+    verifiedAt: number;
+}
+/** Evidence is descriptive input until a trusted Cloudly verifier validates it. */
+export interface IDeploymentReleaseEvidence {
+    sourceRevision: string;
+    version: string;
+    configurationDigest: TSha256Digest;
+    ociIndexDigest: TSha256Digest;
+    releaseAuthorized: boolean;
+    attestations: IDeploymentReleaseEvidenceReference[];
+}
+export interface IDeploymentPreflightRequestData {
+    requestId: string;
+    serviceId: string;
+    sourceRevision: string;
+    sourceDirty: boolean;
+    version: string;
+    intentDigest: string;
+    proposedNamespace: string;
+    proposedCorestoreResources: IDeploymentPreflightProposedCorestoreResource[];
+    ociIndexDigest?: string;
+    releaseTag?: string;
+    releaseEvidence?: IDeploymentReleaseEvidence;
+    greenfield: true;
+}
+export interface IDeploymentPreflightReport {
+    schemaVersion: 2;
+    decision: TDeploymentPreflightDecision;
+    mutationPerformed: false;
+    generatedAt: number;
+    service: {
+        serviceId: string;
+        serviceName: string;
+        workspaceIdentity: string;
+        registryHost: string;
+        registryRepository: string;
+        deployOnPush: boolean;
+    };
+    source: {
+        revision: string;
+        dirty: boolean;
+        version: string;
+        intentDigest: TSha256Digest;
+        configurationDigest: TSha256Digest;
+    };
+    currentImage: {
+        tag?: string;
+        digest?: TSha256Digest;
+        imageReference?: string;
+        mutableReference: boolean;
+        mediaType?: TOciManifestMediaType;
+        platforms: IOciPlatformDescriptorSummary[];
+    };
+    requestedImage: {
+        digest?: TSha256Digest;
+        releaseTag?: string;
+        tagReserved: boolean;
+        mediaType?: TOciManifestMediaType;
+        platforms: IOciPlatformDescriptorSummary[];
+    };
+    runtimeTasks: IDeploymentPreflightRuntimeTask[];
+    runtimeAttestation: {
+        requiredReplicaCount: number;
+        observedReplicaCount: number;
+        healthyReplicaCount: number;
+        verifiedReplicaCount: number;
+        consistentDigest: boolean;
+    };
+    platformBindings: IDeploymentPreflightPlatformBinding[];
+    corestoreResources: IDeploymentPreflightCorestoreResource[];
+    proposed: {
+        namespace: string;
+        corestoreResources: IDeploymentPreflightProposedCorestoreResource[];
+        namespaceReserved: boolean;
+        inventoryComplete: boolean;
+        namespaceBlank: boolean | 'unknown';
+        versionReserved: boolean;
+        wouldReplaceExistingState: boolean | 'unknown';
+    };
+    authorizationChecks: IDeploymentPreflightAuthorizationCheck[];
+    compatibilityBlockers: IDeploymentPreflightBlocker[];
+}
+export interface IGreenfieldDeploymentFence {
+    sourceServiceId: string;
+    sourceRevision: string;
+    version: string;
+    ociIndexDigest: TSha256Digest;
+    configurationDigest: TSha256Digest;
+    targetNamespace: string;
+}
+export interface IGreenfieldDeploymentOperation {
+    id: string;
+    data: {
+        idempotencyKey: string;
+        requestDigest: TSha256Digest;
+        fence: IGreenfieldDeploymentFence;
+        candidateServiceId?: string;
+        state: 'reserved' | 'provisioning' | 'deploying' | 'verifying' | 'ready-for-promotion' | 'promoting' | 'promoted' | 'rolling-back' | 'rolled-back' | 'failed';
+        routeGeneration?: number;
+        createdAt: number;
+        updatedAt: number;
+        failureCode?: string;
+    };
+}
+export declare const validateDeploymentPreflightRequest: (requestArg: unknown) => IDeploymentPreflightBlocker[];
+export declare const validateDeploymentReleaseEvidence: (argsArg: {
+    evidence: unknown;
+    sourceRevision: string;
+    version: string;
+    configurationDigest: TSha256Digest;
+    ociIndexDigest: TSha256Digest;
+}) => IDeploymentPreflightBlocker[];

package/dist_ts/data/deploymentpreflight.js

@@ -0,0 +1,119 @@
+import { normalizeSha256Digest } from './immutableimage.js';
+const fullGitRevisionRegex = /^[a-f0-9]{40}$/;
+const namespaceRegex = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const semanticVersionRegex = /^(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const requiredEvidenceKinds = new Set([
+    'provenance',
+    'sbom',
+    'signature',
+    'vulnerability-policy',
+    'release-authorization',
+]);
+const isRecord = (valueArg) => Boolean(valueArg) && typeof valueArg === 'object' && !Array.isArray(valueArg);
+export const validateDeploymentPreflightRequest = (requestArg) => {
+    const blockers = [];
+    if (!isRecord(requestArg)) {
+        return [{ code: 'INVALID_REQUEST', message: 'Deployment preflight request must be an object.' }];
+    }
+    if (typeof requestArg.requestId !== 'string' || !requestArg.requestId.trim() || requestArg.requestId.length > 200) {
+        blockers.push({ code: 'INVALID_REQUEST', message: 'A bounded request identifier is required.' });
+    }
+    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.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
+        || !semanticVersionRegex.test(requestArg.version)) {
+        blockers.push({ code: 'VERSION_NOT_RESERVED', message: 'A canonical semantic release version is required.' });
+    }
+    if (typeof requestArg.proposedNamespace !== 'string' || !namespaceRegex.test(requestArg.proposedNamespace)) {
+        blockers.push({ code: 'NAMESPACE_NOT_RESERVED', message: 'The proposed namespace is missing or malformed.' });
+    }
+    if (typeof requestArg.intentDigest !== 'string' || !normalizeSha256Digest(requestArg.intentDigest)) {
+        blockers.push({ code: 'INTENT_DIGEST_INVALID', message: 'Deployment intent digest must be a canonical sha256 digest.' });
+    }
+    const proposedResources = Array.isArray(requestArg.proposedCorestoreResources)
+        ? requestArg.proposedCorestoreResources
+        : [];
+    if (!Array.isArray(requestArg.proposedCorestoreResources)
+        || proposedResources.length > 8
+        || proposedResources.some((resourceArg) => (!isRecord(resourceArg)
+            || (resourceArg.capability !== 'database' && resourceArg.capability !== 'objectstorage')
+            || typeof resourceArg.resourceName !== 'string'
+            || !namespaceRegex.test(resourceArg.resourceName)))) {
+        blockers.push({ code: 'INVALID_REQUEST', message: 'Proposed Corestore resources are malformed.' });
+    }
+    const proposedResourceKeys = proposedResources
+        .filter(isRecord)
+        .map((resourceArg) => `${String(resourceArg.capability)}:${String(resourceArg.resourceName)}`);
+    if (new Set(proposedResourceKeys).size !== proposedResourceKeys.length) {
+        blockers.push({ code: 'INVALID_REQUEST', message: 'Proposed Corestore resources must be unique.' });
+    }
+    if (requestArg.ociIndexDigest !== undefined
+        && (typeof requestArg.ociIndexDigest !== 'string' || !normalizeSha256Digest(requestArg.ociIndexDigest))) {
+        blockers.push({ code: 'OCI_INDEX_DIGEST_REQUIRED', message: 'OCI index digest must be a canonical sha256 digest.' });
+    }
+    if (requestArg.greenfield !== true) {
+        blockers.push({ code: 'WOULD_REPLACE_EXISTING_STATE', message: 'Only greenfield deployment preflight is supported.' });
+    }
+    return blockers;
+};
+export const validateDeploymentReleaseEvidence = (argsArg) => {
+    const blockers = [];
+    if (!isRecord(argsArg.evidence)) {
+        return [{ code: 'RELEASE_EVIDENCE_INVALID', message: 'Release evidence must be an object.' }];
+    }
+    const evidence = argsArg.evidence;
+    if (evidence.releaseAuthorized !== true) {
+        blockers.push({ code: 'RELEASE_NOT_AUTHORIZED', message: 'Release authorization evidence is explicitly false.' });
+    }
+    if (evidence.sourceRevision !== argsArg.sourceRevision
+        || evidence.version !== argsArg.version
+        || evidence.configurationDigest !== argsArg.configurationDigest
+        || evidence.ociIndexDigest !== argsArg.ociIndexDigest) {
+        blockers.push({ code: 'RELEASE_EVIDENCE_INVALID', message: 'Release evidence is not bound to the requested deployment fence.' });
+    }
+    const seenKinds = new Set();
+    const attestations = Array.isArray(evidence.attestations) ? evidence.attestations : [];
+    if (!Array.isArray(evidence.attestations)) {
+        blockers.push({ code: 'RELEASE_EVIDENCE_INVALID', message: 'Release attestations must be an array.' });
+    }
+    for (const attestation of attestations) {
+        if (!isRecord(attestation)) {
+            blockers.push({ code: 'RELEASE_EVIDENCE_INVALID', message: 'Release attestation must be an object.' });
+            continue;
+        }
+        const kind = attestation.kind;
+        if (typeof kind !== 'string' || !requiredEvidenceKinds.has(kind)) {
+            blockers.push({ code: 'RELEASE_EVIDENCE_INVALID', message: 'Release attestation kind is invalid.' });
+            continue;
+        }
+        seenKinds.add(kind);
+        if (attestation.subjectDigest !== argsArg.ociIndexDigest
+            || typeof attestation.statementDigest !== 'string'
+            || !normalizeSha256Digest(attestation.statementDigest)
+            || typeof attestation.verifier !== 'string'
+            || !attestation.verifier.trim()
+            || typeof attestation.verifiedAt !== 'number'
+            || !Number.isSafeInteger(attestation.verifiedAt)
+            || attestation.verifiedAt < 1) {
+            blockers.push({ code: 'RELEASE_EVIDENCE_INVALID', message: `Invalid ${kind} evidence.` });
+        }
+    }
+    for (const requiredKind of requiredEvidenceKinds) {
+        if (!seenKinds.has(requiredKind)) {
+            blockers.push({ code: 'RELEASE_EVIDENCE_MISSING', message: `Missing ${requiredKind} evidence.` });
+        }
+    }
+    return blockers;
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVwbG95bWVudHByZWZsaWdodC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvZGVwbG95bWVudHByZWZsaWdodC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFJQSxPQUFPLEVBQUUscUJBQXFCLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQStNNUQsTUFBTSxvQkFBb0IsR0FBRyxnQkFBZ0IsQ0FBQztBQUM5QyxNQUFNLGNBQWMsR0FBRyx3Q0FBd0MsQ0FBQztBQUNoRSxNQUFNLG9CQUFvQixHQUFHLDRNQUE0TSxDQUFDO0FBQzFPLE1BQU0scUJBQXFCLEdBQUcsSUFBSSxHQUFHLENBQThDO0lBQ2pGLFlBQVk7SUFDWixNQUFNO0lBQ04sV0FBVztJQUNYLHNCQUFzQjtJQUN0Qix1QkFBdUI7Q0FDeEIsQ0FBQyxDQUFDO0FBRUgsTUFBTSxRQUFRLEdBQUcsQ0FBQyxRQUFpQixFQUF1QyxFQUFFLENBQzFFLE9BQU8sQ0FBQyxRQUFRLENBQUMsSUFBSSxPQUFPLFFBQVEsS0FBSyxRQUFRLElBQUksQ0FBQyxLQUFLLENBQUMsT0FBTyxDQUFDLFFBQVEsQ0FBQyxDQUFDO0FBRWhGLE1BQU0sQ0FBQyxNQUFNLGtDQUFrQyxHQUFHLENBQ2hELFVBQW1CLEVBQ1ksRUFBRTtJQUNqQyxNQUFNLFFBQVEsR0FBa0MsRUFBRSxDQUFDO0lBQ25ELElBQUksQ0FBQyxRQUFRLENBQUMsVUFBVSxDQUFDLEVBQUUsQ0FBQztRQUMxQixPQUFPLENBQUMsRUFBRSxJQUFJLEVBQUUsaUJBQWlCLEVBQUUsT0FBTyxFQUFFLGlEQUFpRCxFQUFFLENBQUMsQ0FBQztJQUNuRyxDQUFDO0lBQ0QsSUFBSSxPQUFPLFVBQVUsQ0FBQyxTQUFTLEtBQUssUUFBUSxJQUFJLENBQUMsVUFBVSxDQUFDLFNBQVMsQ0FBQyxJQUFJLEVBQUUsSUFBSSxVQUFVLENBQUMsU0FBUyxDQUFDLE1BQU0sR0FBRyxHQUFHLEVBQUUsQ0FBQztRQUNsSCxRQUFRLENBQUMsSUFB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

package/dist_ts/data/index.d.ts

@@ -2,6 +2,7 @@ export * from './cloudlyconfig.js';
 export * from './cluster.js';
 export * from './config.js';
 export * from './deployment.js';
+export * from './deploymentpreflight.js';
 export * from './migration.js';
 export * from './dns.js';
 export * from './docker.js';

package/dist_ts/data/index.js

@@ -2,6 +2,7 @@ export * from './cloudlyconfig.js';
 export * from './cluster.js';
 export * from './config.js';
 export * from './deployment.js';
+export * from './deploymentpreflight.js';
 export * from './migration.js';
 export * from './dns.js';
 export * from './docker.js';
@@ -30,4 +31,4 @@ export * from './taskexecution.js';
 export * from './traffic.js';
 export * from './user.js';
 export * from './version.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyw2QkFBNkIsQ0FBQztBQUM1QyxjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGNBQWMsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxVQUFVLENBQUM7QUFDekIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsY0FBYyxDQUFDIn0=

package/dist_ts/data/user.d.ts

@@ -3,6 +3,16 @@ export interface IToken {
     expiresAt: number;
     assignedRoles: string[];
 }
+export type TServiceDeploymentCapability = 'deployment:preflight' | 'deployment:create-greenfield' | 'deployment:promote-route' | 'deployment:rollback-route';
+/**
+ * Server-persisted authority for one logical service. These grants are never
+ * accepted from the identity payload supplied by a caller; Cloudly reloads
+ * the owning user from the verified JWT before evaluating them.
+ */
+export interface IServiceDeploymentGrant {
+    serviceId: string;
+    capabilities: TServiceDeploymentCapability[];
+}
 export interface IIdentityCredential {
     jwt: string;
 }
@@ -25,5 +35,6 @@ export interface IUser {
         username?: string;
         password?: string;
         tokens?: IToken[];
+        serviceDeploymentGrants?: IServiceDeploymentGrant[];
     };
 }

package/dist_ts/requests/admin.d.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../plugins.js';
-import type { IIdentity } from '../data/user.js';
+import type { IIdentity, TServiceDeploymentCapability } from '../data/user.js';
 export interface IReq_Admin_LoginWithUsernameAndPassword extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_LoginWithUsernameAndPassword> {
     method: 'adminLoginWithUsernameAndPassword';
     request: {
@@ -10,6 +10,21 @@ export interface IReq_Admin_LoginWithUsernameAndPassword extends plugins.typedre
         identity: IIdentity;
     };
 }
+export interface IReq_Admin_ConfigureServiceDeploymentMachineUser extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_ConfigureServiceDeploymentMachineUser> {
+    method: 'configureServiceDeploymentMachineUser';
+    request: {
+        identity: IIdentity;
+        userId: string;
+        serviceId: string;
+        capabilities: TServiceDeploymentCapability[];
+    };
+    response: {
+        userId: string;
+        serviceId: string;
+        capabilities: TServiceDeploymentCapability[];
+        tokenRolesNormalized: true;
+    };
+}
 export interface ICoreflowBaseServiceReconciliationResult {
     status: 'fulfilled' | 'rejected';
     nodeNames: string[];

package/dist_ts/requests/service.d.ts

@@ -4,6 +4,16 @@ import type { TServiceWritableData } from '../data/service.js';
 import type { IRegistryTarget } from '../data/registry.js';
 import type { IIdentity } from '../data/user.js';
 import type { IImageRelease } from '../data/immutableimage.js';
+import type { IDeploymentPreflightReport, IDeploymentPreflightRequestData } from '../data/deploymentpreflight.js';
+export interface IRequest_Any_Cloudly_GetDeploymentPreflight extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_GetDeploymentPreflight> {
+    method: 'getDeploymentPreflight';
+    request: IDeploymentPreflightRequestData & {
+        identity: IIdentity;
+    };
+    response: {
+        report: IDeploymentPreflightReport;
+    };
+}
 export interface IRequest_Any_Cloudly_GetServiceById extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_GetServiceById> {
     method: 'getServiceById';
     request: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "11.3.0",
+  "version": "12.0.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/ts/00_commitinfo_data.ts

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

package/ts/data/deploymentpreflight.ts

@@ -0,0 +1,345 @@
+import type {
+  TOciManifestMediaType,
+  TSha256Digest,
+} from './immutableimage.js';
+import { normalizeSha256Digest } from './immutableimage.js';
+import type { TServiceDeploymentCapability } from './user.js';
+
+export type TDeploymentPreflightDecision = 'GO' | 'NO-GO';
+
+export type TDeploymentPreflightBlockerCode =
+  | 'INVALID_REQUEST'
+  | 'AUTHORIZATION_MISSING'
+  | 'SOURCE_REVISION_INVALID'
+  | 'SOURCE_WORKTREE_DIRTY'
+  | 'VERSION_NOT_RESERVED'
+  | 'VERSION_COLLISION'
+  | 'NAMESPACE_NOT_RESERVED'
+  | 'NAMESPACE_COLLISION'
+  | 'NAMESPACE_NOT_PROVEN_BLANK'
+  | 'CONFIGURATION_DIGEST_INVALID'
+  | 'INTENT_DIGEST_INVALID'
+  | 'CURRENT_REFERENCE_MUTABLE'
+  | 'CURRENT_RUNTIME_DIGEST_MISSING'
+  | 'OCI_INDEX_DIGEST_REQUIRED'
+  | 'OCI_INDEX_NOT_FOUND'
+  | 'OCI_INDEX_MEDIA_TYPE_REQUIRED'
+  | 'OCI_PLATFORM_MISSING'
+  | 'OCI_PLATFORM_MANIFEST_MISSING'
+  | 'IMMUTABLE_RELEASE_TAG_REQUIRED'
+  | 'IMMUTABLE_RELEASE_TAG_NOT_RESERVED'
+  | 'RELEASE_EVIDENCE_MISSING'
+  | 'RELEASE_EVIDENCE_INVALID'
+  | 'RELEASE_NOT_AUTHORIZED'
+  | 'GREENFIELD_EXECUTION_UNAVAILABLE'
+  | 'ROUTE_PROMOTION_FENCE_UNAVAILABLE'
+  | 'POST_DEPLOYMENT_VERIFICATION_UNAVAILABLE'
+  | 'WOULD_REPLACE_EXISTING_STATE'
+  | 'CORESTORE_INVENTORY_UNAVAILABLE'
+  | 'RUNTIME_ATTESTATION_MISMATCH';
+
+export interface IDeploymentPreflightBlocker {
+  code: TDeploymentPreflightBlockerCode;
+  message: string;
+}
+
+export interface IDeploymentPreflightAuthorizationCheck {
+  capability: TServiceDeploymentCapability;
+  granted: boolean;
+}
+
+export interface IOciPlatformDescriptorSummary {
+  os: string;
+  architecture: string;
+  digest?: TSha256Digest;
+  mediaType?: string;
+  runnable: boolean;
+  manifestPresent: boolean;
+}
+
+export interface IDeploymentPreflightRuntimeTask {
+  deploymentId: string;
+  nodeName?: string;
+  status: string;
+  healthStatus?: string;
+  imageReference?: string;
+  reportedDigest?: TSha256Digest;
+  verificationStatus?: 'not-required' | 'pending' | 'verified' | 'missing' | 'mismatched';
+}
+
+export interface IDeploymentPreflightPlatformBinding {
+  capability: 'database' | 'objectstorage';
+  desiredState: 'enabled' | 'disabled';
+  status: 'requested' | 'provisioning' | 'ready' | 'degraded' | 'failed' | 'disabled';
+}
+
+export interface IDeploymentPreflightCorestoreResource {
+  capability: 'database' | 'objectstorage';
+  provider: string;
+  resourceName: string;
+}
+
+export interface IDeploymentPreflightProposedCorestoreResource {
+  capability: 'database' | 'objectstorage';
+  resourceName: string;
+}
+
+export interface IDeploymentReleaseEvidenceReference {
+  kind: 'provenance' | 'sbom' | 'signature' | 'vulnerability-policy' | 'release-authorization';
+  statementDigest: TSha256Digest;
+  subjectDigest: TSha256Digest;
+  verifier: string;
+  verifiedAt: number;
+}
+
+/** Evidence is descriptive input until a trusted Cloudly verifier validates it. */
+export interface IDeploymentReleaseEvidence {
+  sourceRevision: string;
+  version: string;
+  configurationDigest: TSha256Digest;
+  ociIndexDigest: TSha256Digest;
+  releaseAuthorized: boolean;
+  attestations: IDeploymentReleaseEvidenceReference[];
+}
+
+export interface IDeploymentPreflightRequestData {
+  requestId: string;
+  serviceId: string;
+  sourceRevision: string;
+  sourceDirty: boolean;
+  version: string;
+  intentDigest: string;
+  proposedNamespace: string;
+  proposedCorestoreResources: IDeploymentPreflightProposedCorestoreResource[];
+  ociIndexDigest?: string;
+  releaseTag?: string;
+  releaseEvidence?: IDeploymentReleaseEvidence;
+  greenfield: true;
+}
+
+export interface IDeploymentPreflightReport {
+  schemaVersion: 2;
+  decision: TDeploymentPreflightDecision;
+  mutationPerformed: false;
+  generatedAt: number;
+  service: {
+    serviceId: string;
+    serviceName: string;
+    workspaceIdentity: string;
+    registryHost: string;
+    registryRepository: string;
+    deployOnPush: boolean;
+  };
+  source: {
+    revision: string;
+    dirty: boolean;
+    version: string;
+    intentDigest: TSha256Digest;
+    configurationDigest: TSha256Digest;
+  };
+  currentImage: {
+    tag?: string;
+    digest?: TSha256Digest;
+    imageReference?: string;
+    mutableReference: boolean;
+    mediaType?: TOciManifestMediaType;
+    platforms: IOciPlatformDescriptorSummary[];
+  };
+  requestedImage: {
+    digest?: TSha256Digest;
+    releaseTag?: string;
+    tagReserved: boolean;
+    mediaType?: TOciManifestMediaType;
+    platforms: IOciPlatformDescriptorSummary[];
+  };
+  runtimeTasks: IDeploymentPreflightRuntimeTask[];
+  runtimeAttestation: {
+    requiredReplicaCount: number;
+    observedReplicaCount: number;
+    healthyReplicaCount: number;
+    verifiedReplicaCount: number;
+    consistentDigest: boolean;
+  };
+  platformBindings: IDeploymentPreflightPlatformBinding[];
+  corestoreResources: IDeploymentPreflightCorestoreResource[];
+  proposed: {
+    namespace: string;
+    corestoreResources: IDeploymentPreflightProposedCorestoreResource[];
+    namespaceReserved: boolean;
+    inventoryComplete: boolean;
+    namespaceBlank: boolean | 'unknown';
+    versionReserved: boolean;
+    wouldReplaceExistingState: boolean | 'unknown';
+  };
+  authorizationChecks: IDeploymentPreflightAuthorizationCheck[];
+  compatibilityBlockers: IDeploymentPreflightBlocker[];
+}
+
+export interface IGreenfieldDeploymentFence {
+  sourceServiceId: string;
+  sourceRevision: string;
+  version: string;
+  ociIndexDigest: TSha256Digest;
+  configurationDigest: TSha256Digest;
+  targetNamespace: string;
+}
+
+export interface IGreenfieldDeploymentOperation {
+  id: string;
+  data: {
+    idempotencyKey: string;
+    requestDigest: TSha256Digest;
+    fence: IGreenfieldDeploymentFence;
+    candidateServiceId?: string;
+    state:
+      | 'reserved'
+      | 'provisioning'
+      | 'deploying'
+      | 'verifying'
+      | 'ready-for-promotion'
+      | 'promoting'
+      | 'promoted'
+      | 'rolling-back'
+      | 'rolled-back'
+      | 'failed';
+    routeGeneration?: number;
+    createdAt: number;
+    updatedAt: number;
+    failureCode?: string;
+  };
+}
+
+const fullGitRevisionRegex = /^[a-f0-9]{40}$/;
+const namespaceRegex = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const semanticVersionRegex = /^(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const requiredEvidenceKinds = new Set<IDeploymentReleaseEvidenceReference['kind']>([
+  'provenance',
+  'sbom',
+  'signature',
+  'vulnerability-policy',
+  'release-authorization',
+]);
+
+const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  Boolean(valueArg) && typeof valueArg === 'object' && !Array.isArray(valueArg);
+
+export const validateDeploymentPreflightRequest = (
+  requestArg: unknown,
+): IDeploymentPreflightBlocker[] => {
+  const blockers: IDeploymentPreflightBlocker[] = [];
+  if (!isRecord(requestArg)) {
+    return [{ code: 'INVALID_REQUEST', message: 'Deployment preflight request must be an object.' }];
+  }
+  if (typeof requestArg.requestId !== 'string' || !requestArg.requestId.trim() || requestArg.requestId.length > 200) {
+    blockers.push({ code: 'INVALID_REQUEST', message: 'A bounded request identifier is required.' });
+  }
+  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.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
+    || !semanticVersionRegex.test(requestArg.version)) {
+    blockers.push({ code: 'VERSION_NOT_RESERVED', message: 'A canonical semantic release version is required.' });
+  }
+  if (typeof requestArg.proposedNamespace !== 'string' || !namespaceRegex.test(requestArg.proposedNamespace)) {
+    blockers.push({ code: 'NAMESPACE_NOT_RESERVED', message: 'The proposed namespace is missing or malformed.' });
+  }
+  if (typeof requestArg.intentDigest !== 'string' || !normalizeSha256Digest(requestArg.intentDigest)) {
+    blockers.push({ code: 'INTENT_DIGEST_INVALID', message: 'Deployment intent digest must be a canonical sha256 digest.' });
+  }
+  const proposedResources = Array.isArray(requestArg.proposedCorestoreResources)
+    ? requestArg.proposedCorestoreResources
+    : [];
+  if (!Array.isArray(requestArg.proposedCorestoreResources)
+    || proposedResources.length > 8
+    || proposedResources.some((resourceArg) => (
+      !isRecord(resourceArg)
+      || (resourceArg.capability !== 'database' && resourceArg.capability !== 'objectstorage')
+      || typeof resourceArg.resourceName !== 'string'
+      || !namespaceRegex.test(resourceArg.resourceName)
+    ))) {
+    blockers.push({ code: 'INVALID_REQUEST', message: 'Proposed Corestore resources are malformed.' });
+  }
+  const proposedResourceKeys = proposedResources
+    .filter(isRecord)
+    .map((resourceArg) => `${String(resourceArg.capability)}:${String(resourceArg.resourceName)}`);
+  if (new Set(proposedResourceKeys).size !== proposedResourceKeys.length) {
+    blockers.push({ code: 'INVALID_REQUEST', message: 'Proposed Corestore resources must be unique.' });
+  }
+  if (requestArg.ociIndexDigest !== undefined
+    && (typeof requestArg.ociIndexDigest !== 'string' || !normalizeSha256Digest(requestArg.ociIndexDigest))) {
+    blockers.push({ code: 'OCI_INDEX_DIGEST_REQUIRED', message: 'OCI index digest must be a canonical sha256 digest.' });
+  }
+  if (requestArg.greenfield !== true) {
+    blockers.push({ code: 'WOULD_REPLACE_EXISTING_STATE', message: 'Only greenfield deployment preflight is supported.' });
+  }
+  return blockers;
+};
+
+export const validateDeploymentReleaseEvidence = (argsArg: {
+  evidence: unknown;
+  sourceRevision: string;
+  version: string;
+  configurationDigest: TSha256Digest;
+  ociIndexDigest: TSha256Digest;
+}): IDeploymentPreflightBlocker[] => {
+  const blockers: IDeploymentPreflightBlocker[] = [];
+  if (!isRecord(argsArg.evidence)) {
+    return [{ code: 'RELEASE_EVIDENCE_INVALID', message: 'Release evidence must be an object.' }];
+  }
+  const evidence = argsArg.evidence;
+  if (evidence.releaseAuthorized !== true) {
+    blockers.push({ code: 'RELEASE_NOT_AUTHORIZED', message: 'Release authorization evidence is explicitly false.' });
+  }
+  if (
+    evidence.sourceRevision !== argsArg.sourceRevision
+    || evidence.version !== argsArg.version
+    || evidence.configurationDigest !== argsArg.configurationDigest
+    || evidence.ociIndexDigest !== argsArg.ociIndexDigest
+  ) {
+    blockers.push({ code: 'RELEASE_EVIDENCE_INVALID', message: 'Release evidence is not bound to the requested deployment fence.' });
+  }
+  const seenKinds = new Set<IDeploymentReleaseEvidenceReference['kind']>();
+  const attestations = Array.isArray(evidence.attestations) ? evidence.attestations : [];
+  if (!Array.isArray(evidence.attestations)) {
+    blockers.push({ code: 'RELEASE_EVIDENCE_INVALID', message: 'Release attestations must be an array.' });
+  }
+  for (const attestation of attestations) {
+    if (!isRecord(attestation)) {
+      blockers.push({ code: 'RELEASE_EVIDENCE_INVALID', message: 'Release attestation must be an object.' });
+      continue;
+    }
+    const kind = attestation.kind;
+    if (typeof kind !== 'string' || !requiredEvidenceKinds.has(kind as IDeploymentReleaseEvidenceReference['kind'])) {
+      blockers.push({ code: 'RELEASE_EVIDENCE_INVALID', message: 'Release attestation kind is invalid.' });
+      continue;
+    }
+    seenKinds.add(kind as IDeploymentReleaseEvidenceReference['kind']);
+    if (
+      attestation.subjectDigest !== argsArg.ociIndexDigest
+      || typeof attestation.statementDigest !== 'string'
+      || !normalizeSha256Digest(attestation.statementDigest)
+      || typeof attestation.verifier !== 'string'
+      || !attestation.verifier.trim()
+      || typeof attestation.verifiedAt !== 'number'
+      || !Number.isSafeInteger(attestation.verifiedAt)
+      || attestation.verifiedAt < 1
+    ) {
+      blockers.push({ code: 'RELEASE_EVIDENCE_INVALID', message: `Invalid ${kind} evidence.` });
+    }
+  }
+  for (const requiredKind of requiredEvidenceKinds) {
+    if (!seenKinds.has(requiredKind)) {
+      blockers.push({ code: 'RELEASE_EVIDENCE_MISSING', message: `Missing ${requiredKind} evidence.` });
+    }
+  }
+  return blockers;
+};

package/ts/data/index.ts

@@ -2,6 +2,7 @@ export * from './cloudlyconfig.js';
 export * from './cluster.js';
 export * from './config.js';
 export * from './deployment.js';
+export * from './deploymentpreflight.js';
 export * from './migration.js';
 export * from './dns.js';
 export * from './docker.js';

package/ts/data/user.ts

@@ -4,6 +4,22 @@ export interface IToken {
   assignedRoles: string[];
 }
 
+export type TServiceDeploymentCapability =
+  | 'deployment:preflight'
+  | 'deployment:create-greenfield'
+  | 'deployment:promote-route'
+  | 'deployment:rollback-route';
+
+/**
+ * Server-persisted authority for one logical service. These grants are never
+ * accepted from the identity payload supplied by a caller; Cloudly reloads
+ * the owning user from the verified JWT before evaluating them.
+ */
+export interface IServiceDeploymentGrant {
+  serviceId: string;
+  capabilities: TServiceDeploymentCapability[];
+}
+
 export interface IIdentityCredential {
   jwt: string;
 }
@@ -28,5 +44,6 @@ export interface IUser {
     username?: string;
     password?: string;
     tokens?: IToken[];
+    serviceDeploymentGrants?: IServiceDeploymentGrant[];
   }
 }

package/ts/requests/admin.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../plugins.js';
-import type { IIdentity } from '../data/user.js';
+import type { IIdentity, TServiceDeploymentCapability } from '../data/user.js';
 
 export interface IReq_Admin_LoginWithUsernameAndPassword extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -15,6 +15,26 @@ export interface IReq_Admin_LoginWithUsernameAndPassword extends plugins.typedre
   }
 }
 
+export interface IReq_Admin_ConfigureServiceDeploymentMachineUser
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_ConfigureServiceDeploymentMachineUser
+> {
+  method: 'configureServiceDeploymentMachineUser';
+  request: {
+    identity: IIdentity;
+    userId: string;
+    serviceId: string;
+    capabilities: TServiceDeploymentCapability[];
+  };
+  response: {
+    userId: string;
+    serviceId: string;
+    capabilities: TServiceDeploymentCapability[];
+    tokenRolesNormalized: true;
+  };
+}
+
 export interface ICoreflowBaseServiceReconciliationResult {
   status: 'fulfilled' | 'rejected';
   nodeNames: string[];

package/ts/requests/service.ts

@@ -5,6 +5,24 @@ import type { IRegistryTarget } from '../data/registry.js';
 import type { IIdentity } from '../data/user.js';
 import type { IServiceRessources } from '../data/docker.js';
 import type { IImageRelease } from '../data/immutableimage.js';
+import type {
+  IDeploymentPreflightReport,
+  IDeploymentPreflightRequestData,
+} from '../data/deploymentpreflight.js';
+
+export interface IRequest_Any_Cloudly_GetDeploymentPreflight
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_GetDeploymentPreflight
+> {
+  method: 'getDeploymentPreflight';
+  request: IDeploymentPreflightRequestData & {
+    identity: IIdentity;
+  };
+  response: {
+    report: IDeploymentPreflightReport;
+  };
+}
 
 export interface IRequest_Any_Cloudly_GetServiceById 
 extends plugins.typedrequestInterfaces.implementsTR<