@serve.zone/interfaces 11.2.0 → 11.4.0

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';
@@ -11,6 +12,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 +31,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,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxVQUFVLENBQUM7QUFDekIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsY0FBYyxDQUFDIn0=

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/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/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,19 @@
 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';
+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: {
@@ -32,11 +44,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 +99,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.2.0",
+  "version": "11.4.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.2.0',
+  version: '11.4.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/deploymentpreflight.ts

@@ -0,0 +1,297 @@
+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'
+  | 'VERSION_NOT_RESERVED'
+  | 'VERSION_COLLISION'
+  | 'NAMESPACE_NOT_RESERVED'
+  | 'NAMESPACE_COLLISION'
+  | 'NAMESPACE_NOT_PROVEN_BLANK'
+  | 'CONFIGURATION_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 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;
+  version: string;
+  configurationDigest: string;
+  proposedNamespace: string;
+  ociIndexDigest?: string;
+  releaseTag?: string;
+  releaseEvidence?: IDeploymentReleaseEvidence;
+  greenfield: true;
+}
+
+export interface IDeploymentPreflightReport {
+  schemaVersion: 1;
+  decision: TDeploymentPreflightDecision;
+  mutationPerformed: false;
+  generatedAt: number;
+  service: {
+    serviceId: string;
+    serviceName: string;
+    workspaceIdentity: string;
+    registryRepository: string;
+    deployOnPush: boolean;
+  };
+  source: {
+    revision: string;
+    version: string;
+    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[];
+  platformBindings: IDeploymentPreflightPlatformBinding[];
+  corestoreResources: IDeploymentPreflightCorestoreResource[];
+  proposed: {
+    namespace: string;
+    namespaceReserved: boolean;
+    namespaceBlank: boolean;
+    versionReserved: boolean;
+    wouldReplaceExistingState: boolean;
+  };
+  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 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.version !== 'string' || !requestArg.version.trim() || requestArg.version.length > 100) {
+    blockers.push({ code: 'VERSION_NOT_RESERVED', message: 'A bounded 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.configurationDigest !== 'string' || !normalizeSha256Digest(requestArg.configurationDigest)) {
+    blockers.push({ code: 'CONFIGURATION_DIGEST_INVALID', message: 'Configuration digest must be a canonical sha256 digest.' });
+  }
+  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/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;
   };
 }