@serve.zone/interfaces 11.1.1 → 11.3.0

package/changelog.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 2026-07-18 - 11.3.0
+
+### Features
+
+- define fail-closed immutable image deployment and runtime evidence contracts (deployment)
+  - Separate observed registry releases, accepted digest rollouts, and exact-digest rollback plans.
+  - Require task-derived Docker runtime evidence and complete healthy replica reports before rollout success.
+  - Add idempotent promotion, compare-and-swap rollback, capability, ordering, and mismatch contracts.
+
+## 2026-07-15 - 11.2.0
+
+### Features
+
+- Support priority and managed-kind metadata on gateway routes.
+  - Allow combined `hostname` plus `routeRef` ownership so multiple managed routes for one hostname reconcile independently.
+  - Define the canonical `letsencrypt-http01-forward` managed route kind.
+
+### Maintenance
+
+- Update the release toolchain to pnpm 11.13.0 and Node.js types 26.1.1.
+
 ## 2026-07-13 - 11.1.1
 
 ### Fixes

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/data/deployment.d.ts

@@ -1,3 +1,4 @@
+import type { IRuntimeImageEvidence } from './immutableimage.js';
 /**
  * a deployment happens when a service is deployed
  * tracks the status of a deployment
@@ -28,6 +29,11 @@ export interface IDeployment {
     slot?: number;
     /** Docker desired state for this task/deployment. */
     desiredState?: string;
+    /** Immutable rollout generation represented by this task, when applicable. */
+    rolloutId?: string;
+    rolloutGeneration?: number;
+    /** Evidence derived from Docker runtime state rather than service intent metadata. */
+    runtimeImageEvidence?: IRuntimeImageEvidence;
     /**
      * Image used for this deployment
      */

package/dist_ts/data/gateway.d.ts

@@ -3,6 +3,10 @@ import type { TDnsRecordType } from './dns.js';
  * Type of platform acting as a gateway client against a gateway (dcrouter).
  */
 export type TGatewayClientType = 'onebox' | 'cloudly' | 'custom';
+/**
+ * Canonical managed route purposes understood by gateways.
+ */
+export type TManagedRouteKind = 'letsencrypt-http01-forward';
 /**
  * Identity attached to gateway requests. Gateways run their own user/auth
  * domain (e.g. dcrouter operator accounts), so role/type stay open strings;
@@ -175,7 +179,11 @@ export interface IGatewayClientOwnership {
     appId: string;
     /** Hostname ownership for domain routes. Preserved for existing route keys. */
     hostname?: string;
-    /** Stable non-domain route key, for example public-port mapping exposure refs. */
+    /**
+     * Stable route key. Without hostname it identifies a non-domain route such as
+     * a public-port mapping. Together with hostname it distinguishes multiple
+     * managed routes for the same hostname.
+     */
     routeRef?: string;
 }
 /**
@@ -224,6 +232,10 @@ export interface IGatewayRouteConfig {
     name: string;
     match: IGatewayRouteMatch;
     action: IGatewayRouteAction;
+    /** Higher values are matched first by the gateway. */
+    priority?: number;
+    /** Declares a canonical gateway-managed route purpose. */
+    managedRouteKind?: TManagedRouteKind;
     remoteIngress?: {
         enabled: boolean;
         edgeFilter?: string[];

package/dist_ts/data/image.d.ts

@@ -1,4 +1,4 @@
-import type { IRegistryPushEvent } from './registry.js';
+import type { IImmutableRegistryPushEvent, IRegistryPushEvent } from './registry.js';
 export interface IImage {
     id: string;
     data: {
@@ -13,6 +13,8 @@ export interface IImage {
         versions: Array<{
             versionString: string;
             digest?: string;
+            releaseId?: string;
+            manifestMediaType?: string;
             registryRepository?: string;
             registryTag?: string;
             source?: 'upload' | 'registry';
@@ -20,6 +22,6 @@ export interface IImage {
             size: number;
             createdAt: number;
         }>;
-        lastPushEvent?: IRegistryPushEvent;
+        lastPushEvent?: IRegistryPushEvent | IImmutableRegistryPushEvent;
     };
 }

package/dist_ts/data/immutableimage.d.ts

@@ -0,0 +1,145 @@
+/** Canonical lower-case OCI sha256 digest. */
+export type TSha256Digest = `sha256:${string}`;
+export type TImageDeploymentPolicy = 'legacy-tag' | 'immutable-digest';
+export type TOciManifestMediaType = 'application/vnd.oci.image.index.v1+json' | 'application/vnd.oci.image.manifest.v1+json' | 'application/vnd.docker.distribution.manifest.list.v2+json' | 'application/vnd.docker.distribution.manifest.v2+json';
+export type TImmutableImageRolloutMode = 'promotion' | 'automatic' | 'rollback';
+export type TImmutableImageMismatchReason = 'immutable-plan-missing' | 'requested-digest-missing' | 'requested-digest-malformed' | 'registry-digest-inconsistent' | 'runtime-capability-missing' | 'pull-failed' | 'pulled-digest-missing' | 'pulled-digest-mismatch' | 'service-image-not-digest-pinned' | 'service-image-digest-mismatch' | 'task-image-not-digest-pinned' | 'task-image-digest-mismatch' | 'container-inspection-unavailable' | 'container-image-id-missing' | 'container-repodigest-missing' | 'container-repodigest-mismatch' | 'runtime-attestation-missing' | 'required-replica-missing' | 'replica-unhealthy' | 'replica-failed' | 'stale-rollout-report' | 'rollback-target-not-accepted';
+export type TRuntimeImageVerificationStatus = 'not-required' | 'pending' | 'verified' | 'missing' | 'mismatched';
+export type TImmutableImageRolloutStatus = 'pending' | 'deploying' | 'verifying' | 'succeeded' | 'failed' | 'mismatched' | 'rolling-back' | 'rolled-back';
+export interface ICoreflowRuntimeCapabilities {
+    immutableImageDeploymentVersion: 1;
+}
+/**
+ * A registry manifest observed by Cloudly. Observation alone does not make the
+ * release deployable: acceptedAt is set only by an explicit promotion or a
+ * configured automatic promotion.
+ */
+export interface IImageRelease {
+    id: string;
+    data: {
+        serviceId: string;
+        imageId: string;
+        registryHost: string;
+        repository: string;
+        /** Digest of the registry root descriptor, preserving an index/list when submitted. */
+        registryRootDigest: TSha256Digest;
+        digestPinnedImageReference: string;
+        manifestMediaType: TOciManifestMediaType;
+        observedTags: string[];
+        firstObservedAt: number;
+        lastObservedAt: number;
+        observationCount: number;
+        acceptedAt?: number;
+        lastPromotedAt?: number;
+        promotionCount?: number;
+    };
+}
+export interface IImmutableImageTargetScope {
+    targetClusterIds: string[];
+    targetNodeNames: string[];
+    replicasPerNode: number;
+    requiredReplicaCount: number;
+}
+/** Immutable desired state issued by Cloudly and consumed by Coreflow. */
+export interface IImmutableImageDeploymentPlan {
+    policy: 'immutable-digest';
+    rolloutId: string;
+    rolloutGeneration: number;
+    releaseId: string;
+    registryHost: string;
+    repository: string;
+    requestedDigest: TSha256Digest;
+    digestPinnedImageReference: string;
+    manifestMediaType: TOciManifestMediaType;
+    createdAt: number;
+    mode: TImmutableImageRolloutMode;
+    rollbackOfRolloutId?: string;
+    targetScope: IImmutableImageTargetScope;
+}
+/** Runtime evidence collected from Docker service, task, container and image state. */
+interface IRuntimeImageEvidenceBase {
+    rolloutId?: string;
+    rolloutGeneration?: number;
+    expectedDigest?: TSha256Digest;
+    serviceImageReference?: string;
+    taskImageReference?: string;
+    taskReportedDigest?: TSha256Digest;
+    containerImageId?: string;
+    containerConfigImageReference?: string;
+    resolvedDigest?: TSha256Digest;
+    platformManifestDigest?: TSha256Digest;
+    repoDigests?: string[];
+    evidenceSource?: 'task-spec' | 'local-container-inspect';
+    observedAt: number;
+}
+export interface IVerifiedRuntimeImageEvidence extends IRuntimeImageEvidenceBase {
+    verificationStatus: 'verified';
+    rolloutId: string;
+    rolloutGeneration: number;
+    expectedDigest: TSha256Digest;
+    serviceImageReference: string;
+    taskImageReference: string;
+    taskReportedDigest: TSha256Digest;
+    containerImageId: string;
+    containerConfigImageReference: string;
+    resolvedDigest: TSha256Digest;
+    repoDigests: string[];
+    evidenceSource: 'local-container-inspect';
+    mismatchReason?: never;
+}
+export interface IUnverifiedRuntimeImageEvidence extends IRuntimeImageEvidenceBase {
+    verificationStatus: 'missing' | 'mismatched';
+    mismatchReason: TImmutableImageMismatchReason;
+}
+export interface IPendingRuntimeImageEvidence extends IRuntimeImageEvidenceBase {
+    verificationStatus: 'pending' | 'not-required';
+    mismatchReason?: never;
+}
+export type IRuntimeImageEvidence = IVerifiedRuntimeImageEvidence | IUnverifiedRuntimeImageEvidence | IPendingRuntimeImageEvidence;
+/** Mandatory security envelope when reporting an immutable rollout. */
+export interface IImmutableRolloutReportEnvelope {
+    rolloutId: string;
+    rolloutGeneration: number;
+    reporterSessionId: string;
+    reportSequence: number;
+    reporterCapabilities: ICoreflowRuntimeCapabilities;
+    reporterNodeIds: string[];
+    reporterNodeNames: string[];
+}
+export interface IImageRolloutReporterStatus {
+    reporterId: string;
+    reporterSessionId: string;
+    clusterId: string;
+    reporterNodeNames: string[];
+    rolloutId: string;
+    rolloutGeneration: number;
+    reportSequence: number;
+    reportedAt: number;
+    requiredReplicaCount: number;
+    observedReplicaCount: number;
+    healthyReplicaCount: number;
+    verifiedReplicaCount: number;
+    failedReplicaCount: number;
+    mismatchReason?: TImmutableImageMismatchReason;
+}
+export interface IImageRolloutStatus {
+    rolloutId: string;
+    rolloutGeneration: number;
+    expectedDigest: TSha256Digest;
+    status: TImmutableImageRolloutStatus;
+    requiredReplicaCount: number;
+    observedReplicaCount: number;
+    healthyReplicaCount: number;
+    verifiedReplicaCount: number;
+    failedReplicaCount: number;
+    mismatchReason?: TImmutableImageMismatchReason;
+    updatedAt: number;
+    reporters: IImageRolloutReporterStatus[];
+}
+export declare const normalizeSha256Digest: (digest: string) => TSha256Digest | undefined;
+export declare const isSha256Digest: (digest: string) => digest is TSha256Digest;
+export declare const buildDigestPinnedImageReference: (registryHost: string, repository: string, digest: TSha256Digest) => string;
+export declare const getDigestFromPinnedImageReference: (imageReference: string) => TSha256Digest | undefined;
+export declare const validateImmutableImageDeploymentPlan: (planArg: IImmutableImageDeploymentPlan) => string[];
+export declare const validateImageRolloutStatus: (statusArg: IImageRolloutStatus) => string[];
+export {};

package/dist_ts/data/immutableimage.js

@@ -0,0 +1,146 @@
+const sha256DigestRegex = /^sha256:[a-f0-9]{64}$/;
+export const normalizeSha256Digest = (digest) => {
+    const normalizedDigest = digest.trim().toLowerCase();
+    return sha256DigestRegex.test(normalizedDigest)
+        ? normalizedDigest
+        : undefined;
+};
+export const isSha256Digest = (digest) => sha256DigestRegex.test(digest);
+const registryHostRegex = /^(?:localhost|[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?)(?::[1-9][0-9]{0,4})?$/;
+const repositoryRegex = /^[a-z0-9]+(?:[._-][a-z0-9]+)*(?:\/[a-z0-9]+(?:[._-][a-z0-9]+)*)*$/;
+export const buildDigestPinnedImageReference = (registryHost, repository, digest) => {
+    if (!registryHostRegex.test(registryHost) || !repositoryRegex.test(repository)) {
+        throw new Error('registry host and repository must be canonical OCI names');
+    }
+    if (!isSha256Digest(digest)) {
+        throw new Error('digest must be a canonical sha256 digest');
+    }
+    return `${registryHost}/${repository}@${digest}`;
+};
+export const getDigestFromPinnedImageReference = (imageReference) => {
+    const separatorIndex = imageReference.lastIndexOf('@');
+    if (separatorIndex < 0) {
+        return undefined;
+    }
+    return normalizeSha256Digest(imageReference.slice(separatorIndex + 1));
+};
+export const validateImmutableImageDeploymentPlan = (planArg) => {
+    const errors = [];
+    if (!Number.isSafeInteger(planArg.rolloutGeneration) || planArg.rolloutGeneration < 1) {
+        errors.push('rolloutGeneration must be a positive safe integer');
+    }
+    if (!Number.isSafeInteger(planArg.createdAt) || planArg.createdAt < 1) {
+        errors.push('createdAt must be a positive safe integer');
+    }
+    let expectedReference;
+    try {
+        expectedReference = buildDigestPinnedImageReference(planArg.registryHost, planArg.repository, planArg.requestedDigest);
+    }
+    catch (error) {
+        errors.push(error.message);
+    }
+    if (expectedReference && planArg.digestPinnedImageReference !== expectedReference) {
+        errors.push('digestPinnedImageReference does not match registry, repository and digest');
+    }
+    const scope = planArg.targetScope;
+    if (!Number.isSafeInteger(scope.replicasPerNode) || scope.replicasPerNode < 1) {
+        errors.push('replicasPerNode must be a positive safe integer');
+    }
+    if (scope.targetClusterIds.length < 1 || scope.targetNodeNames.length < 1) {
+        errors.push('immutable rollout target scope must contain clusters and nodes');
+    }
+    if (new Set(scope.targetClusterIds).size !== scope.targetClusterIds.length
+        || new Set(scope.targetNodeNames).size !== scope.targetNodeNames.length) {
+        errors.push('immutable rollout target scope must not contain duplicates');
+    }
+    if (scope.requiredReplicaCount !== scope.targetNodeNames.length * scope.replicasPerNode) {
+        errors.push('requiredReplicaCount does not match target nodes and replicasPerNode');
+    }
+    if (planArg.mode === 'rollback' && !planArg.rollbackOfRolloutId) {
+        errors.push('rollback rollout must identify the rollout it replaces');
+    }
+    if (planArg.mode !== 'rollback' && planArg.rollbackOfRolloutId) {
+        errors.push('only rollback rollouts may set rollbackOfRolloutId');
+    }
+    return errors;
+};
+export const validateImageRolloutStatus = (statusArg) => {
+    const errors = [];
+    const counts = [
+        statusArg.requiredReplicaCount,
+        statusArg.observedReplicaCount,
+        statusArg.healthyReplicaCount,
+        statusArg.verifiedReplicaCount,
+        statusArg.failedReplicaCount,
+    ];
+    if (counts.some((countArg) => !Number.isSafeInteger(countArg) || countArg < 0)) {
+        errors.push('rollout replica counts must be non-negative safe integers');
+    }
+    const reporterIds = statusArg.reporters.map((reporterArg) => reporterArg.reporterId);
+    const reporterSessionIds = statusArg.reporters.map((reporterArg) => reporterArg.reporterSessionId);
+    const reporterNodeNames = statusArg.reporters.flatMap((reporterArg) => reporterArg.reporterNodeNames);
+    if (new Set(reporterIds).size !== reporterIds.length
+        || new Set(reporterSessionIds).size !== reporterSessionIds.length) {
+        errors.push('rollout status must contain one latest report per reporter and session');
+    }
+    for (const reporter of statusArg.reporters) {
+        const reporterCounts = [
+            reporter.requiredReplicaCount,
+            reporter.observedReplicaCount,
+            reporter.healthyReplicaCount,
+            reporter.verifiedReplicaCount,
+            reporter.failedReplicaCount,
+        ];
+        if (reporterCounts.some((countArg) => !Number.isSafeInteger(countArg) || countArg < 0)) {
+            errors.push('reporter replica counts must be non-negative safe integers');
+        }
+        if (reporter.rolloutId !== statusArg.rolloutId
+            || reporter.rolloutGeneration !== statusArg.rolloutGeneration) {
+            errors.push('reporter rollout identity does not match aggregate rollout identity');
+        }
+        if (reporter.observedReplicaCount > reporter.requiredReplicaCount
+            || reporter.healthyReplicaCount > reporter.observedReplicaCount
+            || reporter.verifiedReplicaCount > reporter.observedReplicaCount) {
+            errors.push('reporter replica counts are contradictory');
+        }
+    }
+    if (statusArg.status === 'succeeded' || statusArg.status === 'rolled-back') {
+        if (statusArg.requiredReplicaCount < 1
+            || statusArg.observedReplicaCount !== statusArg.requiredReplicaCount
+            || statusArg.healthyReplicaCount !== statusArg.requiredReplicaCount
+            || statusArg.verifiedReplicaCount !== statusArg.requiredReplicaCount
+            || statusArg.failedReplicaCount !== 0) {
+            errors.push('successful rollout status requires every replica to be observed, healthy and verified');
+        }
+        if (statusArg.mismatchReason || statusArg.reporters.length < 1) {
+            errors.push('successful rollout status requires reporters without mismatch reasons');
+        }
+        if (new Set(reporterNodeNames).size !== reporterNodeNames.length) {
+            errors.push('successful rollout status must not count a node in multiple reporters');
+        }
+        if (statusArg.reporters.some((reporterArg) => (reporterArg.requiredReplicaCount < 1
+            || reporterArg.observedReplicaCount !== reporterArg.requiredReplicaCount
+            || reporterArg.healthyReplicaCount !== reporterArg.requiredReplicaCount
+            || reporterArg.verifiedReplicaCount !== reporterArg.requiredReplicaCount
+            || reporterArg.failedReplicaCount !== 0
+            || Boolean(reporterArg.mismatchReason)))) {
+            errors.push('successful rollout requires every reporter replica to be healthy and verified');
+        }
+        const reporterTotals = statusArg.reporters.reduce((totalsArg, reporterArg) => ({
+            required: totalsArg.required + reporterArg.requiredReplicaCount,
+            observed: totalsArg.observed + reporterArg.observedReplicaCount,
+            healthy: totalsArg.healthy + reporterArg.healthyReplicaCount,
+            verified: totalsArg.verified + reporterArg.verifiedReplicaCount,
+            failed: totalsArg.failed + reporterArg.failedReplicaCount,
+        }), { required: 0, observed: 0, healthy: 0, verified: 0, failed: 0 });
+        if (reporterTotals.required !== statusArg.requiredReplicaCount
+            || reporterTotals.observed !== statusArg.observedReplicaCount
+            || reporterTotals.healthy !== statusArg.healthyReplicaCount
+            || reporterTotals.verified !== statusArg.verifiedReplicaCount
+            || reporterTotals.failed !== statusArg.failedReplicaCount) {
+            errors.push('successful rollout aggregate must exactly match successful reporter evidence');
+        }
+    }
+    return errors;
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW1tdXRhYmxlaW1hZ2UuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2ltbXV0YWJsZWltYWdlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQXVNQSxNQUFNLGlCQUFpQixHQUFHLHVCQUF1QixDQUFDO0FBRWxELE1BQU0sQ0FBQyxNQUFNLHFCQUFxQixHQUFHLENBQUMsTUFBYyxFQUE2QixFQUFFO0lBQ2pGLE1BQU0sZ0JBQWdCLEdBQUcsTUFBTSxDQUFDLElBQUksRUFBRSxDQUFDLFdBQVcsRUFBRSxDQUFDO0lBQ3JELE9BQU8saUJBQWlCLENBQUMsSUFBSSxDQUFDLGdCQUFnQixDQUFDO1FBQzdDLENBQUMsQ0FBRSxnQkFBa0M7UUFDckMsQ0FBQyxDQUFDLFNBQVMsQ0FBQztBQUNoQixDQUFDLENBQUM7QUFFRixNQUFNLENBQUMsTUFBTSxjQUFjLEdBQUcsQ0FBQyxNQUFjLEVBQTJCLEVBQUUsQ0FDeEUsaUJBQWlCLENBQUMsSUFBSSxDQUFDLE1BQU0sQ0FBQyxDQUFDO0FBRWpDLE1BQU0saUJBQWlCLEdBQUcsdUVBQXVFLENBQUM7QUFDbEcsTUFBTSxlQUFlLEdBQUcsbUVBQW1FLENBQUM7QUFFNUYsTUFBTSxDQUFDLE1BQU0sK0JBQStCLEdBQUcsQ0FDN0MsWUFBb0IsRUFDcEIsVUFBa0IsRUFDbEIsTUFBcUIsRUFDYixFQUFFO0lBQ1YsSUFBSSxDQUFDLGlCQUFpQixDQUFDLElBQUksQ0FBQyxZQUFZLENBQUMsSUFBSSxDQUFDLGVBQWUsQ0FBQyxJQUFJLENBQUMsVUFBVSxDQUFDLEVBQUUsQ0FBQztRQUMvRSxNQUFNLElBQUksS0FBSyxDQUFDLDBEQUEwRCxDQUFDLENBQUM7SUFDOUUsQ0FBQztJQUNELElBQUksQ0FBQyxjQUFjLENBQUMsTUFBTSxDQUFDLEVBQUUsQ0FBQztRQUM1QixNQUFNLElBQUksS0FBSyxDQUFDLDBDQUEwQyxDQUFDLENBQUM7SUFDOUQsQ0FBQztJQUNELE9BQU8sR0FBRyxZQUFZLElB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

package/dist_ts/data/index.d.ts

@@ -11,6 +11,7 @@ export * from './externalregistry.js';
 export * from './gateway.js';
 export * from './hostedapp.js';
 export * from './image.js';
+export * from './immutableimage.js';
 export * from './isolatedrestore.js';
 export * from './isolatedrestore.golden.js';
 export * from './mail.js';

package/dist_ts/data/index.js

@@ -11,6 +11,7 @@ export * from './externalregistry.js';
 export * from './gateway.js';
 export * from './hostedapp.js';
 export * from './image.js';
+export * from './immutableimage.js';
 export * from './isolatedrestore.js';
 export * from './isolatedrestore.golden.js';
 export * from './mail.js';
@@ -29,4 +30,4 @@ export * from './taskexecution.js';
 export * from './traffic.js';
 export * from './user.js';
 export * from './version.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsNkJBQTZCLENBQUM7QUFDNUMsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxjQUFjLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyw2QkFBNkIsQ0FBQztBQUM1QyxjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGNBQWMsQ0FBQyJ9

package/dist_ts/data/registry.d.ts

@@ -1,4 +1,5 @@
 export type TRegistryProtocol = 'oci';
+import type { TOciManifestMediaType, TSha256Digest } from './immutableimage.js';
 export interface IRegistryTarget {
     protocol: TRegistryProtocol;
     registryHost: string;
@@ -9,6 +10,8 @@ export interface IRegistryTarget {
     imageId?: string;
 }
 export interface IRegistryPushEvent {
+    eventId?: string;
+    releaseId?: string;
     protocol: TRegistryProtocol;
     registryHost: string;
     repository: string;
@@ -16,8 +19,27 @@ export interface IRegistryPushEvent {
     digest: string;
     imageUrl: string;
     pushedAt: number;
+    observedAt?: number;
     serviceId?: string;
     imageId?: string;
     actorUserId?: string;
     manifestMediaType?: string;
 }
+/** Fully verified registry observation used by immutable release processing. */
+export interface IImmutableRegistryPushEvent {
+    deploymentPolicy: 'immutable-digest';
+    eventId: string;
+    releaseId: string;
+    protocol: TRegistryProtocol;
+    registryHost: string;
+    repository: string;
+    tag: string;
+    registryRootDigest: TSha256Digest;
+    digestPinnedImageReference: string;
+    imageUrl: string;
+    observedAt: number;
+    serviceId: string;
+    imageId: string;
+    manifestMediaType: TOciManifestMediaType;
+    actorUserId?: string;
+}

package/dist_ts/data/service.d.ts

@@ -3,6 +3,7 @@ import type { IRegistryTarget } from './registry.js';
 import type { IAppStorePublishedPort } from '../appstore/index.js';
 import type { IHostedAppLifecycleState } from './hostedapp.js';
 import type { IServiceMailConfig } from './mail.js';
+import type { IImageRolloutStatus, IImmutableImageDeploymentPlan } from './immutableimage.js';
 import type { IServiceDomainRoute, IServicePublicPortMapping, IServiceTargetPort } from './serviceports.js';
 export interface IServiceVolume {
     /** Stable Docker volume name. If omitted, Coreflow derives one from service id and mount path. */
@@ -60,6 +61,12 @@ export interface IService {
         imageVersion: string;
         registryTarget?: IRegistryTarget;
         deployOnPush?: boolean;
+        /** Fail closed unless Cloudly supplies and Coreflow verifies a digest-pinned rollout. */
+        immutableImageRequired?: boolean;
+        /** Server-managed immutable desired state. Use the promotion/rollback APIs to change it. */
+        imageDeployment?: IImmutableImageDeploymentPlan;
+        /** Server-managed aggregate of task-derived runtime evidence. */
+        imageRolloutStatus?: IImageRolloutStatus;
         /**
          * When true the service tolerates overlapping deployments during
          * updates (rolling). Default false: the previous deployment is stopped
@@ -139,3 +146,5 @@ export interface IService {
         deploymentIds: string[];
     };
 }
+/** Caller-writable service data. Immutable policy and rollout fields are server-managed. */
+export type TServiceWritableData = Omit<IService['data'], 'immutableImageRequired' | 'imageDeployment' | 'imageRolloutStatus'>;

package/dist_ts/requests/deployment.d.ts

@@ -2,6 +2,7 @@ import * as plugins from '../plugins.js';
 import type { IDeployment } from '../data/deployment.js';
 import type { IService } from '../data/service.js';
 import type { IIdentity } from '../data/user.js';
+import type { IImmutableRolloutReportEnvelope } from '../data/immutableimage.js';
 export interface IDeploymentWorkspaceFileEntry {
     type: 'file' | 'directory';
     name: string;
@@ -311,6 +312,8 @@ export interface IReq_Coreflow_Cloudly_ReportDeploymentSnapshots extends plugins
          * When absent, the snapshot replaces all persisted deployments of the service.
          */
         reporterNodeNames?: string[];
+        /** Mandatory when the referenced service requires immutable deployment. */
+        immutableReport?: IImmutableRolloutReportEnvelope;
         reportedAt: number;
     };
     response: Record<string, never>;

package/dist_ts/requests/service.d.ts

@@ -1,7 +1,9 @@
 import * as plugins from '../plugins.js';
 import type { IService } from '../data/service.js';
+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';
 export interface IRequest_Any_Cloudly_GetServiceById extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_GetServiceById> {
     method: 'getServiceById';
     request: {
@@ -32,11 +34,51 @@ export interface IRequest_Any_Cloudly_GetServiceRegistryTarget extends plugins.t
         registryTarget: IRegistryTarget;
     };
 }
+export interface IRequest_Any_Cloudly_GetServiceImageReleases extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_GetServiceImageReleases> {
+    method: 'getServiceImageReleases';
+    request: {
+        identity: IIdentity;
+        serviceId: string;
+    };
+    response: {
+        releases: IImageRelease[];
+    };
+}
+export interface IRequest_Any_Cloudly_PromoteServiceImageRelease extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_PromoteServiceImageRelease> {
+    method: 'promoteServiceImageRelease';
+    request: {
+        identity: IIdentity;
+        serviceId: string;
+        releaseId: string;
+        idempotencyKey: string;
+        expectedRolloutGeneration: number;
+        expectedCurrentRolloutId?: string;
+        /** Explicitly opts the service into fail-closed immutable deployment. */
+        enableImmutableImage: true;
+    };
+    response: {
+        service: IService;
+    };
+}
+export interface IRequest_Any_Cloudly_RollbackServiceImageRelease extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_RollbackServiceImageRelease> {
+    method: 'rollbackServiceImageRelease';
+    request: {
+        identity: IIdentity;
+        serviceId: string;
+        releaseId: string;
+        idempotencyKey: string;
+        expectedCurrentRolloutId: string;
+        expectedRolloutGeneration: number;
+    };
+    response: {
+        service: IService;
+    };
+}
 export interface IRequest_Any_Cloudly_CreateService extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_CreateService> {
     method: 'createService';
     request: {
         identity: IIdentity;
-        serviceData: IService['data'];
+        serviceData: TServiceWritableData;
     };
     response: {
         service: IService;
@@ -47,7 +89,7 @@ export interface IRequest_Any_Cloudly_UpdateService extends plugins.typedrequest
     request: {
         identity: IIdentity;
         serviceId: string;
-        serviceData: IService['data'];
+        serviceData: TServiceWritableData;
     };
     response: {
         service: IService;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "11.1.1",
+  "version": "11.3.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {
@@ -19,7 +19,7 @@
     "@git.zone/tsdoc": "^2.1.1",
     "@git.zone/tsrun": "^2.0.5",
     "@git.zone/tstest": "^3.6.6",
-    "@types/node": "^26.1.0"
+    "@types/node": "^26.1.1"
   },
   "files": [
     "ts/**/*",

package/readme.md

@@ -95,7 +95,7 @@ Common data contracts include:
 - `IService`, `IDeployment`, `IImage`, `IRegistryTarget`, and `IExternalRegistry` for workload delivery.
 - Service port contracts including `IServiceTargetPort`, `IServiceDomainRoute`, and `IServicePublicPortMapping` for canonical backend targets, domain target references, and edge/Coretraffic TCP/UDP public exposure.
 - `IDomain`, `IDnsEntry`, and traffic contracts for routing and DNS management.
-- Traffic and gateway route contracts including `ICoretrafficPortRouteConfig`, routing `portRoutes`, `IGatewayClientRoute` client-owned route views, gateway route `routeRef` ownership, optional match `domains`, `transport`, and `remoteIngress` route intent.
+- Traffic and gateway route contracts including `ICoretrafficPortRouteConfig`, routing `portRoutes`, and `IGatewayClientRoute` client-owned route views. Gateway route intent supports optional match `domains`, `transport`, and `remoteIngress`, plus explicit route `priority` and `managedRouteKind`. Ownership can combine `hostname` with `routeRef` so a normal route and a path-specific managed route for the same hostname reconcile independently.
 - `ISecretBundle` and `ISecretGroup` for secret ownership and shared secret groups.
 - Mail gateway contracts for domain authorities, address bindings, WorkApp bindings, managed SMTP/API credentials, spool items, delivery journals, and inbound/outbound message payloads.
 - Service-level mail configuration through `IService.data.mail`, including per-address inbound `smtpForward` settings and outbound credential metadata. Cloudly settings include dcrouter gateway, SMTP submission, and inbound forward-target keys for reconciling those bindings.
@@ -140,7 +140,7 @@ interface IExampleRequest {
 
 `requests.config.IRequest_Any_Cloudly_GetClusterConfig` accepts `data.IIdentityCredential`, which contains only the JWT needed for server-side identity resolution. Username/password login and machine-token exchange responses continue to return the full `data.IIdentity`.
 
-Gateway request contracts include `getGatewayClientRoutes` (`requests.gateway.IReq_GetGatewayClientRoutes`) for listing owned `IGatewayClientRoute[]` route views, and `syncGatewayClientRoute` for idempotently syncing or deleting hostname-owned and routeRef-owned routes. Mail request contracts include `syncMailAddressBinding`, `deleteMailAddressBinding`, `rotateMailCredential`, and `getMailDeliveryStatus`. `IReq_GetMailDeliveryStatus` looks up a delivery spool item by `spoolItemId`, returns `data.IMailDeliveryStatus`, and accepts `IMailSubmissionRequestAuth` so service-mail credentials can query their own accepted, queued, deferred, delivered, or failed status. `TMailAddressBindingSync.outboundEnabled` explicitly controls whether a gateway should maintain a managed outbound SMTP credential for an address binding. Binding credential metadata is public; `rotateMailCredential` returns the new secret only in its one-time `IMailCredentialOneTimeSecret` response.
+Gateway request contracts include `getGatewayClientRoutes` (`requests.gateway.IReq_GetGatewayClientRoutes`) for listing owned `IGatewayClientRoute[]` route views, and `syncGatewayClientRoute` for idempotently syncing or deleting hostname-owned, routeRef-owned, and combined hostname-plus-routeRef routes. A client can label canonical intent with `managedRouteKind: 'letsencrypt-http01-forward'` and set a higher `priority` for a path-specific HTTP-01 route while retaining a separate normal route for the same hostname. Mail request contracts include `syncMailAddressBinding`, `deleteMailAddressBinding`, `rotateMailCredential`, and `getMailDeliveryStatus`. `IReq_GetMailDeliveryStatus` looks up a delivery spool item by `spoolItemId`, returns `data.IMailDeliveryStatus`, and accepts `IMailSubmissionRequestAuth` so service-mail credentials can query their own accepted, queued, deferred, delivered, or failed status. `TMailAddressBindingSync.outboundEnabled` explicitly controls whether a gateway should maintain a managed outbound SMTP credential for an address binding. Binding credential metadata is public; `rotateMailCredential` returns the new secret only in its one-time `IMailCredentialOneTimeSecret` response.
 
 Request groups are exported by product area:
 

package/ts/00_commitinfo_data.ts

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

package/ts/data/deployment.ts

@@ -1,4 +1,5 @@
 import * as plugins from '../plugins.js';
+import type { IRuntimeImageEvidence } from './immutableimage.js';
 
 /**
  * a deployment happens when a service is deployed
@@ -39,6 +40,13 @@ export interface IDeployment {
 
   /** Docker desired state for this task/deployment. */
   desiredState?: string;
+
+  /** Immutable rollout generation represented by this task, when applicable. */
+  rolloutId?: string;
+  rolloutGeneration?: number;
+
+  /** Evidence derived from Docker runtime state rather than service intent metadata. */
+  runtimeImageEvidence?: IRuntimeImageEvidence;
   
   /**
    * Image used for this deployment

package/ts/data/gateway.ts

@@ -5,6 +5,11 @@ import type { TDnsRecordType } from './dns.js';
  */
 export type TGatewayClientType = 'onebox' | 'cloudly' | 'custom';
 
+/**
+ * Canonical managed route purposes understood by gateways.
+ */
+export type TManagedRouteKind = 'letsencrypt-http01-forward';
+
 /**
  * Identity attached to gateway requests. Gateways run their own user/auth
  * domain (e.g. dcrouter operator accounts), so role/type stay open strings;
@@ -187,7 +192,11 @@ export interface IGatewayClientOwnership {
   appId: string;
   /** Hostname ownership for domain routes. Preserved for existing route keys. */
   hostname?: string;
-  /** Stable non-domain route key, for example public-port mapping exposure refs. */
+  /**
+   * Stable route key. Without hostname it identifies a non-domain route such as
+   * a public-port mapping. Together with hostname it distinguishes multiple
+   * managed routes for the same hostname.
+   */
   routeRef?: string;
 }
 
@@ -241,6 +250,10 @@ export interface IGatewayRouteConfig {
   name: string;
   match: IGatewayRouteMatch;
   action: IGatewayRouteAction;
+  /** Higher values are matched first by the gateway. */
+  priority?: number;
+  /** Declares a canonical gateway-managed route purpose. */
+  managedRouteKind?: TManagedRouteKind;
   remoteIngress?: {
     enabled: boolean;
     edgeFilter?: string[];

package/ts/data/image.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../plugins.js';
-import type { IRegistryPushEvent } from './registry.js';
+import type { IImmutableRegistryPushEvent, IRegistryPushEvent } from './registry.js';
 
 export interface IImage {
   id: string;
@@ -15,6 +15,8 @@ export interface IImage {
     versions: Array<{
       versionString: string;
       digest?: string;
+      releaseId?: string;
+      manifestMediaType?: string;
       registryRepository?: string;
       registryTag?: string;
       source?: 'upload' | 'registry';
@@ -22,6 +24,6 @@ export interface IImage {
       size: number;
       createdAt: number;
     }>;
-    lastPushEvent?: IRegistryPushEvent;
+    lastPushEvent?: IRegistryPushEvent | IImmutableRegistryPushEvent;
   };
 }

package/ts/data/immutableimage.ts

@@ -0,0 +1,373 @@
+/** Canonical lower-case OCI sha256 digest. */
+export type TSha256Digest = `sha256:${string}`;
+
+export type TImageDeploymentPolicy = 'legacy-tag' | 'immutable-digest';
+
+export type TOciManifestMediaType =
+  | 'application/vnd.oci.image.index.v1+json'
+  | 'application/vnd.oci.image.manifest.v1+json'
+  | 'application/vnd.docker.distribution.manifest.list.v2+json'
+  | 'application/vnd.docker.distribution.manifest.v2+json';
+
+export type TImmutableImageRolloutMode = 'promotion' | 'automatic' | 'rollback';
+
+export type TImmutableImageMismatchReason =
+  | 'immutable-plan-missing'
+  | 'requested-digest-missing'
+  | 'requested-digest-malformed'
+  | 'registry-digest-inconsistent'
+  | 'runtime-capability-missing'
+  | 'pull-failed'
+  | 'pulled-digest-missing'
+  | 'pulled-digest-mismatch'
+  | 'service-image-not-digest-pinned'
+  | 'service-image-digest-mismatch'
+  | 'task-image-not-digest-pinned'
+  | 'task-image-digest-mismatch'
+  | 'container-inspection-unavailable'
+  | 'container-image-id-missing'
+  | 'container-repodigest-missing'
+  | 'container-repodigest-mismatch'
+  | 'runtime-attestation-missing'
+  | 'required-replica-missing'
+  | 'replica-unhealthy'
+  | 'replica-failed'
+  | 'stale-rollout-report'
+  | 'rollback-target-not-accepted';
+
+export type TRuntimeImageVerificationStatus =
+  | 'not-required'
+  | 'pending'
+  | 'verified'
+  | 'missing'
+  | 'mismatched';
+
+export type TImmutableImageRolloutStatus =
+  | 'pending'
+  | 'deploying'
+  | 'verifying'
+  | 'succeeded'
+  | 'failed'
+  | 'mismatched'
+  | 'rolling-back'
+  | 'rolled-back';
+
+export interface ICoreflowRuntimeCapabilities {
+  immutableImageDeploymentVersion: 1;
+}
+
+/**
+ * A registry manifest observed by Cloudly. Observation alone does not make the
+ * release deployable: acceptedAt is set only by an explicit promotion or a
+ * configured automatic promotion.
+ */
+export interface IImageRelease {
+  id: string;
+  data: {
+    serviceId: string;
+    imageId: string;
+    registryHost: string;
+    repository: string;
+    /** Digest of the registry root descriptor, preserving an index/list when submitted. */
+    registryRootDigest: TSha256Digest;
+    digestPinnedImageReference: string;
+    manifestMediaType: TOciManifestMediaType;
+    observedTags: string[];
+    firstObservedAt: number;
+    lastObservedAt: number;
+    observationCount: number;
+    acceptedAt?: number;
+    lastPromotedAt?: number;
+    promotionCount?: number;
+  };
+}
+
+export interface IImmutableImageTargetScope {
+  targetClusterIds: string[];
+  targetNodeNames: string[];
+  replicasPerNode: number;
+  requiredReplicaCount: number;
+}
+
+/** Immutable desired state issued by Cloudly and consumed by Coreflow. */
+export interface IImmutableImageDeploymentPlan {
+  policy: 'immutable-digest';
+  rolloutId: string;
+  rolloutGeneration: number;
+  releaseId: string;
+  registryHost: string;
+  repository: string;
+  requestedDigest: TSha256Digest;
+  digestPinnedImageReference: string;
+  manifestMediaType: TOciManifestMediaType;
+  createdAt: number;
+  mode: TImmutableImageRolloutMode;
+  rollbackOfRolloutId?: string;
+  targetScope: IImmutableImageTargetScope;
+}
+
+/** Runtime evidence collected from Docker service, task, container and image state. */
+interface IRuntimeImageEvidenceBase {
+  rolloutId?: string;
+  rolloutGeneration?: number;
+  expectedDigest?: TSha256Digest;
+  serviceImageReference?: string;
+  taskImageReference?: string;
+  taskReportedDigest?: TSha256Digest;
+  containerImageId?: string;
+  containerConfigImageReference?: string;
+  resolvedDigest?: TSha256Digest;
+  platformManifestDigest?: TSha256Digest;
+  repoDigests?: string[];
+  evidenceSource?: 'task-spec' | 'local-container-inspect';
+  observedAt: number;
+}
+
+export interface IVerifiedRuntimeImageEvidence extends IRuntimeImageEvidenceBase {
+  verificationStatus: 'verified';
+  rolloutId: string;
+  rolloutGeneration: number;
+  expectedDigest: TSha256Digest;
+  serviceImageReference: string;
+  taskImageReference: string;
+  taskReportedDigest: TSha256Digest;
+  containerImageId: string;
+  containerConfigImageReference: string;
+  resolvedDigest: TSha256Digest;
+  repoDigests: string[];
+  evidenceSource: 'local-container-inspect';
+  mismatchReason?: never;
+}
+
+export interface IUnverifiedRuntimeImageEvidence extends IRuntimeImageEvidenceBase {
+  verificationStatus: 'missing' | 'mismatched';
+  mismatchReason: TImmutableImageMismatchReason;
+}
+
+export interface IPendingRuntimeImageEvidence extends IRuntimeImageEvidenceBase {
+  verificationStatus: 'pending' | 'not-required';
+  mismatchReason?: never;
+}
+
+export type IRuntimeImageEvidence =
+  | IVerifiedRuntimeImageEvidence
+  | IUnverifiedRuntimeImageEvidence
+  | IPendingRuntimeImageEvidence;
+
+/** Mandatory security envelope when reporting an immutable rollout. */
+export interface IImmutableRolloutReportEnvelope {
+  rolloutId: string;
+  rolloutGeneration: number;
+  reporterSessionId: string;
+  reportSequence: number;
+  reporterCapabilities: ICoreflowRuntimeCapabilities;
+  reporterNodeIds: string[];
+  reporterNodeNames: string[];
+}
+
+export interface IImageRolloutReporterStatus {
+  reporterId: string;
+  reporterSessionId: string;
+  clusterId: string;
+  reporterNodeNames: string[];
+  rolloutId: string;
+  rolloutGeneration: number;
+  reportSequence: number;
+  reportedAt: number;
+  requiredReplicaCount: number;
+  observedReplicaCount: number;
+  healthyReplicaCount: number;
+  verifiedReplicaCount: number;
+  failedReplicaCount: number;
+  mismatchReason?: TImmutableImageMismatchReason;
+}
+
+export interface IImageRolloutStatus {
+  rolloutId: string;
+  rolloutGeneration: number;
+  expectedDigest: TSha256Digest;
+  status: TImmutableImageRolloutStatus;
+  requiredReplicaCount: number;
+  observedReplicaCount: number;
+  healthyReplicaCount: number;
+  verifiedReplicaCount: number;
+  failedReplicaCount: number;
+  mismatchReason?: TImmutableImageMismatchReason;
+  updatedAt: number;
+  reporters: IImageRolloutReporterStatus[];
+}
+
+const sha256DigestRegex = /^sha256:[a-f0-9]{64}$/;
+
+export const normalizeSha256Digest = (digest: string): TSha256Digest | undefined => {
+  const normalizedDigest = digest.trim().toLowerCase();
+  return sha256DigestRegex.test(normalizedDigest)
+    ? (normalizedDigest as TSha256Digest)
+    : undefined;
+};
+
+export const isSha256Digest = (digest: string): digest is TSha256Digest =>
+  sha256DigestRegex.test(digest);
+
+const registryHostRegex = /^(?:localhost|[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?)(?::[1-9][0-9]{0,4})?$/;
+const repositoryRegex = /^[a-z0-9]+(?:[._-][a-z0-9]+)*(?:\/[a-z0-9]+(?:[._-][a-z0-9]+)*)*$/;
+
+export const buildDigestPinnedImageReference = (
+  registryHost: string,
+  repository: string,
+  digest: TSha256Digest
+): string => {
+  if (!registryHostRegex.test(registryHost) || !repositoryRegex.test(repository)) {
+    throw new Error('registry host and repository must be canonical OCI names');
+  }
+  if (!isSha256Digest(digest)) {
+    throw new Error('digest must be a canonical sha256 digest');
+  }
+  return `${registryHost}/${repository}@${digest}`;
+};
+
+export const getDigestFromPinnedImageReference = (
+  imageReference: string
+): TSha256Digest | undefined => {
+  const separatorIndex = imageReference.lastIndexOf('@');
+  if (separatorIndex < 0) {
+    return undefined;
+  }
+  return normalizeSha256Digest(imageReference.slice(separatorIndex + 1));
+};
+
+export const validateImmutableImageDeploymentPlan = (
+  planArg: IImmutableImageDeploymentPlan
+): string[] => {
+  const errors: string[] = [];
+  if (!Number.isSafeInteger(planArg.rolloutGeneration) || planArg.rolloutGeneration < 1) {
+    errors.push('rolloutGeneration must be a positive safe integer');
+  }
+  if (!Number.isSafeInteger(planArg.createdAt) || planArg.createdAt < 1) {
+    errors.push('createdAt must be a positive safe integer');
+  }
+  let expectedReference: string | undefined;
+  try {
+    expectedReference = buildDigestPinnedImageReference(
+      planArg.registryHost,
+      planArg.repository,
+      planArg.requestedDigest
+    );
+  } catch (error) {
+    errors.push((error as Error).message);
+  }
+  if (expectedReference && planArg.digestPinnedImageReference !== expectedReference) {
+    errors.push('digestPinnedImageReference does not match registry, repository and digest');
+  }
+  const scope = planArg.targetScope;
+  if (!Number.isSafeInteger(scope.replicasPerNode) || scope.replicasPerNode < 1) {
+    errors.push('replicasPerNode must be a positive safe integer');
+  }
+  if (scope.targetClusterIds.length < 1 || scope.targetNodeNames.length < 1) {
+    errors.push('immutable rollout target scope must contain clusters and nodes');
+  }
+  if (new Set(scope.targetClusterIds).size !== scope.targetClusterIds.length
+    || new Set(scope.targetNodeNames).size !== scope.targetNodeNames.length) {
+    errors.push('immutable rollout target scope must not contain duplicates');
+  }
+  if (scope.requiredReplicaCount !== scope.targetNodeNames.length * scope.replicasPerNode) {
+    errors.push('requiredReplicaCount does not match target nodes and replicasPerNode');
+  }
+  if (planArg.mode === 'rollback' && !planArg.rollbackOfRolloutId) {
+    errors.push('rollback rollout must identify the rollout it replaces');
+  }
+  if (planArg.mode !== 'rollback' && planArg.rollbackOfRolloutId) {
+    errors.push('only rollback rollouts may set rollbackOfRolloutId');
+  }
+  return errors;
+};
+
+export const validateImageRolloutStatus = (statusArg: IImageRolloutStatus): string[] => {
+  const errors: string[] = [];
+  const counts = [
+    statusArg.requiredReplicaCount,
+    statusArg.observedReplicaCount,
+    statusArg.healthyReplicaCount,
+    statusArg.verifiedReplicaCount,
+    statusArg.failedReplicaCount,
+  ];
+  if (counts.some((countArg) => !Number.isSafeInteger(countArg) || countArg < 0)) {
+    errors.push('rollout replica counts must be non-negative safe integers');
+  }
+  const reporterIds = statusArg.reporters.map((reporterArg) => reporterArg.reporterId);
+  const reporterSessionIds = statusArg.reporters.map((reporterArg) => reporterArg.reporterSessionId);
+  const reporterNodeNames = statusArg.reporters.flatMap(
+    (reporterArg) => reporterArg.reporterNodeNames
+  );
+  if (new Set(reporterIds).size !== reporterIds.length
+    || new Set(reporterSessionIds).size !== reporterSessionIds.length) {
+    errors.push('rollout status must contain one latest report per reporter and session');
+  }
+  for (const reporter of statusArg.reporters) {
+    const reporterCounts = [
+      reporter.requiredReplicaCount,
+      reporter.observedReplicaCount,
+      reporter.healthyReplicaCount,
+      reporter.verifiedReplicaCount,
+      reporter.failedReplicaCount,
+    ];
+    if (reporterCounts.some((countArg) => !Number.isSafeInteger(countArg) || countArg < 0)) {
+      errors.push('reporter replica counts must be non-negative safe integers');
+    }
+    if (reporter.rolloutId !== statusArg.rolloutId
+      || reporter.rolloutGeneration !== statusArg.rolloutGeneration) {
+      errors.push('reporter rollout identity does not match aggregate rollout identity');
+    }
+    if (
+      reporter.observedReplicaCount > reporter.requiredReplicaCount
+      || reporter.healthyReplicaCount > reporter.observedReplicaCount
+      || reporter.verifiedReplicaCount > reporter.observedReplicaCount
+    ) {
+      errors.push('reporter replica counts are contradictory');
+    }
+  }
+  if (statusArg.status === 'succeeded' || statusArg.status === 'rolled-back') {
+    if (
+      statusArg.requiredReplicaCount < 1
+      || statusArg.observedReplicaCount !== statusArg.requiredReplicaCount
+      || statusArg.healthyReplicaCount !== statusArg.requiredReplicaCount
+      || statusArg.verifiedReplicaCount !== statusArg.requiredReplicaCount
+      || statusArg.failedReplicaCount !== 0
+    ) {
+      errors.push('successful rollout status requires every replica to be observed, healthy and verified');
+    }
+    if (statusArg.mismatchReason || statusArg.reporters.length < 1) {
+      errors.push('successful rollout status requires reporters without mismatch reasons');
+    }
+    if (new Set(reporterNodeNames).size !== reporterNodeNames.length) {
+      errors.push('successful rollout status must not count a node in multiple reporters');
+    }
+    if (statusArg.reporters.some((reporterArg) => (
+      reporterArg.requiredReplicaCount < 1
+      || reporterArg.observedReplicaCount !== reporterArg.requiredReplicaCount
+      || reporterArg.healthyReplicaCount !== reporterArg.requiredReplicaCount
+      || reporterArg.verifiedReplicaCount !== reporterArg.requiredReplicaCount
+      || reporterArg.failedReplicaCount !== 0
+      || Boolean(reporterArg.mismatchReason)
+    ))) {
+      errors.push('successful rollout requires every reporter replica to be healthy and verified');
+    }
+    const reporterTotals = statusArg.reporters.reduce((totalsArg, reporterArg) => ({
+      required: totalsArg.required + reporterArg.requiredReplicaCount,
+      observed: totalsArg.observed + reporterArg.observedReplicaCount,
+      healthy: totalsArg.healthy + reporterArg.healthyReplicaCount,
+      verified: totalsArg.verified + reporterArg.verifiedReplicaCount,
+      failed: totalsArg.failed + reporterArg.failedReplicaCount,
+    }), { required: 0, observed: 0, healthy: 0, verified: 0, failed: 0 });
+    if (
+      reporterTotals.required !== statusArg.requiredReplicaCount
+      || reporterTotals.observed !== statusArg.observedReplicaCount
+      || reporterTotals.healthy !== statusArg.healthyReplicaCount
+      || reporterTotals.verified !== statusArg.verifiedReplicaCount
+      || reporterTotals.failed !== statusArg.failedReplicaCount
+    ) {
+      errors.push('successful rollout aggregate must exactly match successful reporter evidence');
+    }
+  }
+  return errors;
+};

package/ts/data/index.ts

@@ -11,6 +11,7 @@ export * from './externalregistry.js';
 export * from './gateway.js';
 export * from './hostedapp.js';
 export * from './image.js';
+export * from './immutableimage.js';
 export * from './isolatedrestore.js';
 export * from './isolatedrestore.golden.js';
 export * from './mail.js';

package/ts/data/registry.ts

@@ -1,5 +1,10 @@
 export type TRegistryProtocol = 'oci';
 
+import type {
+  TOciManifestMediaType,
+  TSha256Digest,
+} from './immutableimage.js';
+
 export interface IRegistryTarget {
   protocol: TRegistryProtocol;
   registryHost: string;
@@ -11,6 +16,8 @@ export interface IRegistryTarget {
 }
 
 export interface IRegistryPushEvent {
+  eventId?: string;
+  releaseId?: string;
   protocol: TRegistryProtocol;
   registryHost: string;
   repository: string;
@@ -18,8 +25,28 @@ export interface IRegistryPushEvent {
   digest: string;
   imageUrl: string;
   pushedAt: number;
+  observedAt?: number;
   serviceId?: string;
   imageId?: string;
   actorUserId?: string;
   manifestMediaType?: string;
 }
+
+/** Fully verified registry observation used by immutable release processing. */
+export interface IImmutableRegistryPushEvent {
+  deploymentPolicy: 'immutable-digest';
+  eventId: string;
+  releaseId: string;
+  protocol: TRegistryProtocol;
+  registryHost: string;
+  repository: string;
+  tag: string;
+  registryRootDigest: TSha256Digest;
+  digestPinnedImageReference: string;
+  imageUrl: string;
+  observedAt: number;
+  serviceId: string;
+  imageId: string;
+  manifestMediaType: TOciManifestMediaType;
+  actorUserId?: string;
+}

package/ts/data/service.ts

@@ -3,6 +3,10 @@ import type { IRegistryTarget } from './registry.js';
 import type { IAppStorePublishedPort } from '../appstore/index.js';
 import type { IHostedAppLifecycleState } from './hostedapp.js';
 import type { IServiceMailConfig } from './mail.js';
+import type {
+  IImageRolloutStatus,
+  IImmutableImageDeploymentPlan,
+} from './immutableimage.js';
 import type {
   IServiceDomainRoute,
   IServicePublicPortMapping,
@@ -70,6 +74,12 @@ export interface IService {
     imageVersion: string;
     registryTarget?: IRegistryTarget;
     deployOnPush?: boolean;
+    /** Fail closed unless Cloudly supplies and Coreflow verifies a digest-pinned rollout. */
+    immutableImageRequired?: boolean;
+    /** Server-managed immutable desired state. Use the promotion/rollback APIs to change it. */
+    imageDeployment?: IImmutableImageDeploymentPlan;
+    /** Server-managed aggregate of task-derived runtime evidence. */
+    imageRolloutStatus?: IImageRolloutStatus;
 
     /**
      * When true the service tolerates overlapping deployments during
@@ -151,3 +161,9 @@ export interface IService {
     deploymentIds: string[];
   };
 }
+
+/** Caller-writable service data. Immutable policy and rollout fields are server-managed. */
+export type TServiceWritableData = Omit<
+  IService['data'],
+  'immutableImageRequired' | 'imageDeployment' | 'imageRolloutStatus'
+>;

package/ts/requests/deployment.ts

@@ -2,6 +2,7 @@ import * as plugins from '../plugins.js';
 import type { IDeployment } from '../data/deployment.js';
 import type { IService } from '../data/service.js';
 import type { IIdentity } from '../data/user.js';
+import type { IImmutableRolloutReportEnvelope } from '../data/immutableimage.js';
 
 export interface IDeploymentWorkspaceFileEntry {
   type: 'file' | 'directory';
@@ -452,6 +453,8 @@ extends plugins.typedrequestInterfaces.implementsTR<
      * When absent, the snapshot replaces all persisted deployments of the service.
      */
     reporterNodeNames?: string[];
+    /** Mandatory when the referenced service requires immutable deployment. */
+    immutableReport?: IImmutableRolloutReportEnvelope;
     reportedAt: number;
   };
   response: Record<string, never>;

package/ts/requests/service.ts

@@ -1,8 +1,10 @@
 import * as plugins from '../plugins.js';
 import type { IService } from '../data/service.js';
+import type { TServiceWritableData } from '../data/service.js';
 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';
 
 export interface IRequest_Any_Cloudly_GetServiceById 
 extends plugins.typedrequestInterfaces.implementsTR<
@@ -49,6 +51,61 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+export interface IRequest_Any_Cloudly_GetServiceImageReleases
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_GetServiceImageReleases
+> {
+  method: 'getServiceImageReleases';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+  };
+  response: {
+    releases: IImageRelease[];
+  };
+}
+
+export interface IRequest_Any_Cloudly_PromoteServiceImageRelease
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_PromoteServiceImageRelease
+> {
+  method: 'promoteServiceImageRelease';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+    releaseId: string;
+    idempotencyKey: string;
+    expectedRolloutGeneration: number;
+    expectedCurrentRolloutId?: string;
+    /** Explicitly opts the service into fail-closed immutable deployment. */
+    enableImmutableImage: true;
+  };
+  response: {
+    service: IService;
+  };
+}
+
+export interface IRequest_Any_Cloudly_RollbackServiceImageRelease
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_RollbackServiceImageRelease
+> {
+  method: 'rollbackServiceImageRelease';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+    releaseId: string;
+    idempotencyKey: string;
+    expectedCurrentRolloutId: string;
+    expectedRolloutGeneration: number;
+  };
+  response: {
+    service: IService;
+  };
+}
+
 export interface IRequest_Any_Cloudly_CreateService
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -57,7 +114,7 @@ extends plugins.typedrequestInterfaces.implementsTR<
   method: 'createService';
   request: {
     identity: IIdentity;
-    serviceData: IService['data'];
+    serviceData: TServiceWritableData;
   };
   response: {
     service: IService;
@@ -73,7 +130,7 @@ extends plugins.typedrequestInterfaces.implementsTR<
   request: {
     identity: IIdentity;
     serviceId: string;
-    serviceData: IService['data'];
+    serviceData: TServiceWritableData;
   };
   response: {
     service: IService;