@serve.zone/interfaces 32.61.0 → 32.63.0

package/ts/data/mail.ts

@@ -338,6 +338,54 @@ export interface IServiceMailConfig {
 /** Caller-writable mail configuration. CoreMail binding metadata is excluded. */
 export type TServiceMailWritableConfig = Omit<IServiceMailConfig, 'coreMail'>;
 
+/**
+ * The environment names a service's default sender is delivered under, one spelling for the
+ * provisioners (Cloudly, Onebox) and the reader (`@serve.zone/platformclient`).
+ *
+ * Three groups, each delivered whole: the typed dcrouter-direct binding (`from`, `typedUrl`,
+ * `apiCredentialId`, `apiCredentialSecret`; `typedUrl` is `ICloudlySettings.dcrouterMailEndpointUrl`),
+ * its SMTP compatibility surface (`smtp*`), and a CoreMail binding (`coreMail*`, with `from`).
+ * `apiCredentialSecret`, `smtpPassword` and `coreMailCredentialSecret` are secrets and are
+ * delivered as secrets. Every further sender address uses the same names scoped to its address
+ * token (`createServiceMailAddressEnvironmentNames`).
+ */
+export const serviceMailEnvironmentNames = Object.freeze({
+  from: 'MAIL_FROM',
+  typedUrl: 'MAIL_TYPED_URL',
+  apiCredentialId: 'MAIL_API_CREDENTIAL_ID',
+  apiCredentialSecret: 'MAIL_API_CREDENTIAL_SECRET',
+  smtpHost: 'SMTP_HOST',
+  smtpPort: 'SMTP_PORT',
+  smtpTlsMode: 'SMTP_TLS_MODE',
+  smtpUsername: 'SMTP_USERNAME',
+  smtpPassword: 'SMTP_PASSWORD',
+  coreMailUrl: 'MAIL_COREMAIL_URL',
+  coreMailBindingId: 'MAIL_COREMAIL_BINDING_ID',
+  coreMailCredentialId: 'MAIL_COREMAIL_CREDENTIAL_ID',
+  coreMailCredentialVersionNumber: 'MAIL_COREMAIL_CREDENTIAL_VERSION',
+  coreMailCredentialSecret: 'MAIL_COREMAIL_CREDENTIAL_SECRET',
+} as const);
+
+export type TServiceMailEnvironmentNames = Readonly<Record<keyof typeof serviceMailEnvironmentNames, string>>;
+
+/**
+ * The names one further sender address is delivered under: each of `serviceMailEnvironmentNames`
+ * with `MAIL_<token>_` in place of its `MAIL_` prefix, or before it where it has none
+ * (`MAIL_<token>_FROM`, `MAIL_<token>_TYPED_URL`, `MAIL_<token>_SMTP_HOST`,
+ * `MAIL_<token>_COREMAIL_URL`). The token is the address's upper-case token
+ * (`^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$`); any other token is the caller's error and is thrown.
+ */
+export const createServiceMailAddressEnvironmentNames = (addressTokenArg: string): TServiceMailEnvironmentNames => {
+  if (typeof addressTokenArg !== 'string' || !/^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$/.test(addressTokenArg)) {
+    throw new Error('service mail address token must be an upper-case address token');
+  }
+  const scoped: Record<string, string> = {};
+  for (const [key, name] of Object.entries(serviceMailEnvironmentNames)) {
+    scoped[key] = `MAIL_${addressTokenArg}_${name.startsWith('MAIL_') ? name.slice('MAIL_'.length) : name}`;
+  }
+  return Object.freeze(scoped) as TServiceMailEnvironmentNames;
+};
+
 export interface IServiceMailTargetAddressSummary {
   address: string;
   inbound: {

package/ts/data/runtimeassignment.ts

@@ -39,6 +39,19 @@ export type TRuntimeAssignmentDisposition =
   | 'stop-preserve'
   | 'remove-runtime-preserve-storage';
 
+/**
+ * What a cluster designates the service of an attempt as, stated by the controller so a node can
+ * order its work by the service's role instead of by the order the deliveries arrived in.
+ *
+ * `cluster-ingress`: the service is its cluster's designated ingress, the service Cloudly lists as
+ * designated (`IClusterIngressDesignation` for a cluster born on Pallet,
+ * `IFleetCutoverIngressDesignation` after a Swarm cutover) and delivers first, because a cluster
+ * serves nothing until its ingress runs. A node begins such a run before every other run it holds.
+ */
+export const runtimeAssignmentDesignations = ['cluster-ingress'] as const;
+
+export type TRuntimeAssignmentDesignation = (typeof runtimeAssignmentDesignations)[number];
+
 export interface IRuntimeAssignment extends IRuntimeAssignmentScope {
   assignmentId: string;
   serviceId: string;
@@ -55,6 +68,19 @@ export interface IRuntimeAssignment extends IRuntimeAssignmentScope {
   disposition: TRuntimeAssignmentDisposition;
   /** No automatic relocation or expiry-based claim of a stopped writer. */
   offlinePolicy: 'continue-node-bound';
+  /**
+   * The cluster's designation of this attempt's service (`runtimeAssignmentDesignations`); absent
+   * for a service the cluster designates nothing. It is part of the attempt, as every member but
+   * `generation`, `previous`, `disposition` and `digest` is: every later revision of the attempt
+   * states the same value, so a designation that moves to another service reaches the nodes with
+   * the services' next attempts. It orders a node's work and grants nothing: no authority,
+   * placement, credential or network access follows from it.
+   *
+   * A reader built before this member refuses an assignment that states it (exact keys), so a
+   * controller states it only on a session whose offer speaks the release that added it or a later
+   * one, and states nothing on any other.
+   */
+  designation?: TRuntimeAssignmentDesignation;
   workload: {
     /**
      * The registry that published this image, which is the publication identity the image release
@@ -168,7 +194,10 @@ export type TRuntimeImagePullRefusalReason = typeof runtimeImagePullRefusalReaso
  * Why a node refused to start a run before any runtime effect of it, as the node names it:
  * `unsupported-readiness` a readiness probe the run's network cannot carry (a TCP or HTTP probe of
  * a run without network authority), `unresolved-authority` a workload authority the node cannot
- * resolve, and `invalid` an assignment or configuration the node cannot read.
+ * resolve, and `invalid` an assignment or configuration the node cannot read or cannot run as stated,
+ * such as a config environment that states a name the runtime injects
+ * (`composeWorkloadReplicaEnvironment` answering `workload-identity-environment-conflict`, a
+ * service-status reason only Cloudly states).
  */
 export const runtimeAssignmentRefusalReasons = ['unsupported-readiness', 'unresolved-authority', 'invalid'] as const;
 export type TRuntimeAssignmentRefusalReason = typeof runtimeAssignmentRefusalReasons[number];
@@ -317,15 +346,21 @@ const assignmentKeys = [
   'assignmentId', 'serviceId', 'replicaId', 'attemptId', 'workerGroupId', 'siteId',
   'generation', 'previous', 'disposition', 'offlinePolicy', 'workload', 'digest',
 ] as const;
+/** Stated only for a service its cluster designates (`runtimeAssignmentDesignations`). */
+const optionalAssignmentKeys = ['designation'] as const;
 
 const assertAssignment = (valueArg: unknown): IRuntimeAssignment => {
-  if (!isExactRecord(valueArg, assignmentKeys)
+  if (!isExactRecord(valueArg, assignmentKeys, optionalAssignmentKeys)
     || !isController(valueArg.controller)
     || !isPositiveInteger(valueArg.generation) || !isDigest(valueArg.digest)
     || valueArg.offlinePolicy !== 'continue-node-bound'
     || !['run', 'stop-preserve', 'remove-runtime-preserve-storage'].includes(
       valueArg.disposition as string,
     )) fail('runtime assignment must use its exact schema');
+  if (Object.hasOwn(valueArg, 'designation')
+    && !runtimeAssignmentDesignations.some((designationArg) => designationArg === valueArg.designation)) {
+    fail('runtime assignment designation must be a stated designation');
+  }
   for (const key of ['organizationId', 'runtimeNamespace', 'assignmentId', 'serviceId', 'attemptId']) {
     if (!isIdentifier(valueArg[key])) fail(`runtime assignment ${key} must be a canonical identifier`);
   }

package/ts/data/runtimesessionpush.ts

@@ -0,0 +1,24 @@
+/**
+ * How many requests a controller holds outstanding on one node's runtime session at once.
+ *
+ * Counted per node, never per lane, method or carrier: every request a controller sends a node over
+ * its runtime session counts — `applyRuntimeAssignment`, `applyRuntimeLocalStorageClaim`,
+ * `applyRuntimeNetworkSigningAuthority`, `applyRuntimeNetworkProjection`,
+ * `applyRuntimeNetworkDnsLeaseRenewal` and `readRuntimeAssignmentStats` together, whatever pass or
+ * lane of the controller sends it — from the moment it is sent until its answer or its failure
+ * arrived. One relay peer carries a whole cluster, so the count is each node's own, not the peer's.
+ * A relay adds no request of its own while the controller's session is up (its DNS lease escrow
+ * offers one renewal per node, and only while that session is down), so it stays within the same
+ * count.
+ *
+ * A node holds this many at once beside the answers to its own requests and the cancellation each
+ * of them may draw, and never closes its session over them; it answers each within the relay's
+ * forward timeout for a push to a node (coreflow's `nodeForwardMs`, 8 s; not
+ * `runtimeSessionRequestBounds.relaySessionForwardMs`, which bounds the node's own requests to the
+ * controller), so a request the controller stopped waiting for is no longer held on the node. A
+ * controller that sends more than this may lose the node's session: the node's transport bounds
+ * what it queues and closes the connection past that bound.
+ */
+export const runtimeSessionPushBounds = Object.freeze({
+  maximumInFlightPerNode: 8,
+} as const);

package/ts/data/serviceruntime.ts

@@ -93,7 +93,7 @@ const serviceRuntimeRefusals = [
   'objectstorage-endpoint-missing', 'objectstorage-binding-invalid', 'objectstorage-environment-conflict',
   'objectstorage-endpoint-unselected', 'database-endpoint-missing', 'database-endpoint-unselected',
   'published-port-reserved', 'published-port-symmetric-without-egress', 'readiness-network-unsupported',
-  'cluster-relay-missing', 'cluster-ingress-environment-conflict',
+  'cluster-relay-missing', 'cluster-ingress-environment-conflict', 'workload-identity-environment-conflict',
 ] as const;
 
 /**
@@ -183,6 +183,19 @@ export type TServiceRuntimeWaitingReason = typeof serviceRuntimeWaitingReasons[n
  * `cluster-ingress-environment-conflict` is an ingress service whose own environment already sets
  * one of `clusterIngressEnvironmentNames`: Cloudly owns those names, and a service value would
  * otherwise silently replace Cloudly's or be replaced by it.
+ *
+ * `workload-identity-environment-conflict` is a service whose effective environment, or one of
+ * whose launcher-environment secrets, states one of `workloadReplicaIdentityEnvironmentNames`
+ * (`findWorkloadReplicaIdentityEnvironmentConflicts`): every runtime injects those names into every
+ * workload (`composeWorkloadReplicaEnvironment`), so a service value would silently replace the
+ * replica's identity or be replaced by it. Cloudly alone states it, and only in this status, which
+ * it stores and answers on `getServiceRuntimeSpec`, `getServiceRuntimeSpecForCluster` and
+ * `getServiceRuntimeSpecs`. Those requests carry no protocol offer, so the reason cannot be gated
+ * on a peer's version, and no other refusal names this check. A reader built before the release
+ * that added it refuses such a status whole, so every reader of statuses moves to that release
+ * before Cloudly does, and a Cloudly that has stored one is not rolled back below it. A node never
+ * states it: a Pallet whose composition refuses reports the run as the existing
+ * `TRuntimeAssignmentFailureCause` `refused` with `invalid`.
  */
 export type TServiceRuntimeRefusal = typeof serviceRuntimeRefusals[number];
 

package/ts/data/settings.ts

@@ -52,6 +52,15 @@ export interface ICloudlySettings {
   dcrouterMailSubmissionHost?: string;
   dcrouterMailSubmissionPort?: number;
   dcrouterMailSubmissionTlsMode?: 'plain' | 'starttls' | 'implicitTls';
+  /**
+   * The canonical HTTPS URL of dcrouter's tenant mail listener, the endpoint a service's typed
+   * dcrouter-direct mail binding connects to. Cloudly writes it, and only it, into the binding's
+   * `MAIL_TYPED_URL` and `MAIL_<TOKEN>_TYPED_URL` (`serviceMailEnvironmentNames`); never
+   * `dcrouterGatewayUrl` and never a CoreMail endpoint. Absent: Cloudly refuses to provision a
+   * typed dcrouter-direct mail binding and names this key, with no fallback. A value is accepted
+   * only when `validateDcrouterMailEndpointUrl` answers no error.
+   */
+  dcrouterMailEndpointUrl?: string;
   dcrouterMailForwardTargetHost?: string;
   dcrouterMailForwardTargetHostsByNode?: Record<string, string>;
   /** Whether this Cloudly reconciles a CoreMail workload at all. */
@@ -81,6 +90,43 @@ export interface ICloudlySettings {
   appStoreCatalogRegistries?: string[];
 }
 
+/** The longest `dcrouterMailEndpointUrl` Cloudly accepts, in characters. */
+export const dcrouterMailEndpointUrlMaximumLength = 2_048;
+
+/**
+ * Every reason a value is not a `dcrouterMailEndpointUrl`; empty when it is one.
+ *
+ * An `https:` URL without credentials, query or fragment, at most
+ * `dcrouterMailEndpointUrlMaximumLength` characters, written exactly as `new URL(value).href`
+ * spells it (`https://mail.example.com/`), so two spellings of one endpoint never compare unequal.
+ * Plain `http:` and `wss:` are refused: the binding's credential travels to this endpoint. No
+ * reason quotes the value.
+ */
+export const validateDcrouterMailEndpointUrl = (valueArg: unknown): string[] => {
+  if (typeof valueArg !== 'string' || valueArg.length === 0
+    || valueArg.length > dcrouterMailEndpointUrlMaximumLength) {
+    return [`dcrouterMailEndpointUrl must be a URL of 1 to ${dcrouterMailEndpointUrlMaximumLength} characters`];
+  }
+  let url: URL;
+  try {
+    url = new URL(valueArg);
+  } catch {
+    return ['dcrouterMailEndpointUrl must be an absolute URL'];
+  }
+  const errors: string[] = [];
+  if (url.protocol !== 'https:') errors.push('dcrouterMailEndpointUrl must use https');
+  if (url.username !== '' || url.password !== '') {
+    errors.push('dcrouterMailEndpointUrl must not carry credentials');
+  }
+  if (valueArg.includes('?') || valueArg.includes('#')) {
+    errors.push('dcrouterMailEndpointUrl must not carry a query or fragment');
+  }
+  if (errors.length === 0 && url.href !== valueArg) {
+    errors.push('dcrouterMailEndpointUrl must be written in its canonical URL form');
+  }
+  return errors;
+};
+
 export const cloudlySystemSecretOwner = Object.freeze({
   kind: 'system',
   systemId: 'cloudly-settings',

package/ts/data/workloadreplicaidentity.ts

@@ -0,0 +1,219 @@
+import type { TSha256Digest } from './immutableimage.js';
+import { isSha256Digest } from './immutableimage.js';
+import type { IRuntimeAssignment } from './runtimeassignment.js';
+import { isRuntimeReplicaId, snapshotRuntimeAssignment } from './runtimeassignment.js';
+import { runtimeConfigContract } from './runtimeconfig.js';
+import type { TServiceRuntimeRefusal } from './serviceruntime.js';
+import { hasExactKeys, readDataProperties } from '../private/dataproperties.js';
+
+/**
+ * Which replica of which workload a process is, as its runtime states it.
+ *
+ * Every member is the runtime assignment's own (`buildWorkloadReplicaIdentity`), so a workload, its
+ * runtime and its controller name a replica with the same four values. `attemptId` is the one
+ * execution attempt: a rollout, a replacement or a restart onto another attempt is a new attempt,
+ * so the attempt is what a workload reports to correlate itself with the controller's roster.
+ */
+export interface IWorkloadReplicaIdentity {
+  /** The service the replica runs (`IRuntimeAssignment.serviceId`). */
+  serviceId: string;
+  /** The stable logical replica (`IRuntimeAssignment.replicaId`), a `isRuntimeReplicaId` name. */
+  replicaId: string;
+  /** The one execution attempt (`IRuntimeAssignment.attemptId`). */
+  attemptId: string;
+  /** The root descriptor digest the replica runs (`IRuntimeAssignment.workload.imageDigest`). */
+  imageDigest: TSha256Digest;
+}
+
+/**
+ * The environment variable names every runtime injects into every workload it runs, one per
+ * identity member. The one spelling Pallet, Onebox, Cloudly's composition refusal and every
+ * workload that reads its identity share.
+ */
+export const workloadReplicaIdentityEnvironmentNames = Object.freeze({
+  serviceId: 'SERVEZONE_WORKLOAD_SERVICE_ID',
+  replicaId: 'SERVEZONE_WORKLOAD_REPLICA_ID',
+  attemptId: 'SERVEZONE_WORKLOAD_ATTEMPT_ID',
+  imageDigest: 'SERVEZONE_WORKLOAD_IMAGE_DIGEST',
+} as const satisfies Readonly<Record<keyof IWorkloadReplicaIdentity, string>>);
+
+export type TWorkloadReplicaIdentityEnvironmentName =
+  typeof workloadReplicaIdentityEnvironmentNames[keyof IWorkloadReplicaIdentity];
+
+const identityKeys = Object.freeze(
+  Object.keys(workloadReplicaIdentityEnvironmentNames) as (keyof IWorkloadReplicaIdentity)[],
+);
+const identityEnvironmentNames: readonly string[] = Object.freeze(
+  Object.values(workloadReplicaIdentityEnvironmentNames),
+);
+
+/**
+ * The bounds the injection adds to a runtime config's own.
+ *
+ * `IRuntimeConfig.environment` keeps its own bound (`runtimeConfigContract.maximumEnvironmentEntries`),
+ * so a service states at most that many entries. A runtime's executor admits the config's entries
+ * plus the injected identity, `maximumExecutorEnvironmentEntries`, computed from both, never a
+ * literal of its own.
+ */
+export const workloadReplicaIdentityContract = Object.freeze({
+  injectedEnvironmentEntries: identityKeys.length,
+  maximumExecutorEnvironmentEntries: runtimeConfigContract.maximumEnvironmentEntries + identityKeys.length,
+});
+
+const isIdentifier = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(valueArg);
+
+/** What each member must hold, in the runtime assignment's own vocabulary. */
+const memberRules: Readonly<Record<keyof IWorkloadReplicaIdentity, {
+  accepts: (valueArg: unknown) => boolean;
+  requirement: string;
+}>> = Object.freeze({
+  serviceId: { accepts: isIdentifier, requirement: 'a canonical identifier' },
+  replicaId: { accepts: isRuntimeReplicaId, requirement: 'a replica id' },
+  attemptId: { accepts: isIdentifier, requirement: 'a canonical identifier' },
+  imageDigest: {
+    accepts: (valueArg: unknown) => typeof valueArg === 'string' && isSha256Digest(valueArg),
+    requirement: 'a sha256 digest',
+  },
+});
+
+const judgeIdentity = (valueArg: unknown): { record: Record<string, unknown> | null; errors: string[] } => {
+  const record = readDataProperties(valueArg);
+  if (record === null) {
+    return { record, errors: ['workload replica identity must be a plain record of data properties'] };
+  }
+  const errors: string[] = [];
+  if (!hasExactKeys(record, identityKeys)) {
+    errors.push(`workload replica identity must state exactly ${identityKeys.join(', ')}`);
+  }
+  for (const key of identityKeys) {
+    if (Object.hasOwn(record, key) && !memberRules[key].accepts(record[key])) {
+      errors.push(`${key} must be ${memberRules[key].requirement}`);
+    }
+  }
+  return { record, errors };
+};
+
+/** Every reason a value is not exactly a workload replica identity; empty when it is one. */
+export const validateWorkloadReplicaIdentity = (valueArg: unknown): string[] => judgeIdentity(valueArg).errors;
+
+/** A detached, frozen copy of exactly a workload replica identity; throws naming every violation. */
+export const snapshotWorkloadReplicaIdentity = (valueArg: unknown): IWorkloadReplicaIdentity => {
+  const { record, errors } = judgeIdentity(valueArg);
+  if (record === null || errors.length > 0) {
+    throw new Error(`workload replica identity refused: ${errors.join('; ')}`);
+  }
+  return Object.freeze({
+    serviceId: record.serviceId as string,
+    replicaId: record.replicaId as string,
+    attemptId: record.attemptId as string,
+    imageDigest: record.imageDigest as TSha256Digest,
+  });
+};
+
+/**
+ * The identity of the replica one runtime assignment runs.
+ *
+ * Read from the assignment the runtime admitted, through its exact schema, so the answer always
+ * satisfies `validateWorkloadReplicaIdentity`. It proves nothing about the assignment's digest or
+ * admission; the runtime has judged those before it runs anything.
+ */
+export const buildWorkloadReplicaIdentity = (assignmentArg: IRuntimeAssignment): IWorkloadReplicaIdentity => {
+  const assignment = snapshotRuntimeAssignment(assignmentArg);
+  return Object.freeze({
+    serviceId: assignment.serviceId,
+    replicaId: assignment.replicaId,
+    attemptId: assignment.attemptId,
+    imageDigest: assignment.workload.imageDigest,
+  });
+};
+
+/**
+ * The injected names among `namesArg`, sorted and unique: empty when none collides.
+ *
+ * Cloudly's composition refusal passes the keys of a replica's effective environment together with
+ * the variable names of its launcher-environment secrets, because WorkloadInit sets a secret over a
+ * plain variable of the same name and so would replace the injected identity just as silently.
+ */
+export const findWorkloadReplicaIdentityEnvironmentConflicts = (
+  namesArg: readonly string[],
+): TWorkloadReplicaIdentityEnvironmentName[] => identityEnvironmentNames
+  .filter((nameArg) => namesArg.includes(nameArg))
+  .sort() as TWorkloadReplicaIdentityEnvironmentName[];
+
+/** The one reason a workload environment cannot carry its replica identity. */
+export type TWorkloadReplicaEnvironmentRefusal = Extract<
+  TServiceRuntimeRefusal,
+  'workload-identity-environment-conflict'
+>;
+
+/** What a replica runs with, or the one reason its identity cannot be injected. */
+export type TWorkloadReplicaEnvironmentComposition =
+  | { status: 'composed'; environment: Record<string, string> }
+  | { status: 'refused'; reason: TWorkloadReplicaEnvironmentRefusal; message: string };
+
+/**
+ * The environment one replica runs with: its runtime config's environment with the replica's
+ * identity added under `workloadReplicaIdentityEnvironmentNames`.
+ *
+ * Every runtime injects the identity into every workload, whether the workload reads it or not. A
+ * config environment that already states one of the names is refused
+ * `workload-identity-environment-conflict`, naming every such key and none of their values, rather
+ * than having one value silently replace the other. The reason stays inside the runtime: only
+ * Cloudly states it on the wire, in a service's status. A Pallet reports the refused run as the
+ * existing `TRuntimeAssignmentFailureCause` `{ kind: 'refused', reason: 'invalid' }`, which every
+ * reader since 32.45.0 reads and a controller never re-places with an identical configuration. An
+ * identity that is not exactly one is the caller's error and is thrown. The inputs are not
+ * changed. A config within
+ * `runtimeConfigContract.maximumEnvironmentEntries` composes to at most
+ * `workloadReplicaIdentityContract.maximumExecutorEnvironmentEntries` entries.
+ */
+export const composeWorkloadReplicaEnvironment = (
+  environmentArg: Readonly<Record<string, string>>,
+  identityArg: IWorkloadReplicaIdentity,
+): TWorkloadReplicaEnvironmentComposition => {
+  const identity = snapshotWorkloadReplicaIdentity(identityArg);
+  const conflicts = findWorkloadReplicaIdentityEnvironmentConflicts(Object.keys(environmentArg));
+  if (conflicts.length > 0) {
+    return { status: 'refused', reason: 'workload-identity-environment-conflict',
+      message: `workload environment already states ${conflicts.join(', ')}, which the runtime injects` };
+  }
+  const injected: Record<string, string> = {};
+  for (const key of identityKeys) {
+    injected[workloadReplicaIdentityEnvironmentNames[key]] = identity[key];
+  }
+  return { status: 'composed', environment: { ...environmentArg, ...injected } };
+};
+
+/**
+ * The replica identity a workload reads from its own environment (`process.env`).
+ *
+ * Reads the four injected names only, as own data properties, and nothing else of the environment.
+ * Throws naming every name that is missing and every name whose value is not a valid member, never
+ * a value, so a workload refuses to start with the exact variable its runtime did not inject.
+ */
+export const readWorkloadReplicaIdentityEnvironment = (
+  environmentArg: Readonly<Record<string, string | undefined>>,
+): IWorkloadReplicaIdentity => {
+  const missing: string[] = [];
+  const invalid: string[] = [];
+  const identity: Record<string, string> = {};
+  for (const key of identityKeys) {
+    const name = workloadReplicaIdentityEnvironmentNames[key];
+    const descriptor = Object.getOwnPropertyDescriptor(environmentArg, name);
+    if (descriptor === undefined || !Object.hasOwn(descriptor, 'value') || typeof descriptor.value !== 'string') {
+      missing.push(name);
+    } else if (!memberRules[key].accepts(descriptor.value)) {
+      invalid.push(name);
+    } else {
+      identity[key] = descriptor.value;
+    }
+  }
+  if (missing.length > 0 || invalid.length > 0) {
+    throw new Error(`workload replica identity environment ${[
+      ...missing.length > 0 ? [`lacks ${missing.join(', ')}`] : [],
+      ...invalid.length > 0 ? [`states an invalid ${invalid.join(', ')}`] : [],
+    ].join('; ')}`);
+  }
+  return snapshotWorkloadReplicaIdentity(identity);
+};

package/ts/requests/coremail.ts

@@ -18,6 +18,7 @@ import type {
   TCoreMailWorkloadOperation,
 } from '../data/coremail.js';
 import type { IMailConnectionInfo } from '../data/mail.js';
+import type { IWorkloadReplicaIdentity } from '../data/workloadreplicaidentity.js';
 
 export interface IReq_CoreMailAuthenticateWorkload extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -186,7 +187,11 @@ export interface IReq_CoreMailAuthenticateControl extends plugins.typedrequestIn
     authenticated: true;
     credentialId: string;
     credentialVersion: number;
-    replica: ICoreMailReplicaIdentity;
+    /**
+     * The authenticated replica: `IWorkloadReplicaIdentity` from CoreMail 34 on, the deprecated
+     * `ICoreMailReplicaIdentity` from an earlier CoreMail (`normalizeCoreMailReplicaIdentity`).
+     */
+    replica: IWorkloadReplicaIdentity | ICoreMailReplicaIdentity;
   };
 }