@serve.zone/interfaces 32.61.0 → 32.62.0

package/dist_ts/data/workloadreplicaidentity.js

@@ -0,0 +1,159 @@
+import { isSha256Digest } from './immutableimage.js';
+import { isRuntimeReplicaId, snapshotRuntimeAssignment } from './runtimeassignment.js';
+import { runtimeConfigContract } from './runtimeconfig.js';
+import { hasExactKeys, readDataProperties } from '../private/dataproperties.js';
+/**
+ * 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',
+});
+const identityKeys = Object.freeze(Object.keys(workloadReplicaIdentityEnvironmentNames));
+const identityEnvironmentNames = 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) => 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 = 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) => typeof valueArg === 'string' && isSha256Digest(valueArg),
+        requirement: 'a sha256 digest',
+    },
+});
+const judgeIdentity = (valueArg) => {
+    const record = readDataProperties(valueArg);
+    if (record === null) {
+        return { record, errors: ['workload replica identity must be a plain record of data properties'] };
+    }
+    const errors = [];
+    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) => judgeIdentity(valueArg).errors;
+/** A detached, frozen copy of exactly a workload replica identity; throws naming every violation. */
+export const snapshotWorkloadReplicaIdentity = (valueArg) => {
+    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,
+        replicaId: record.replicaId,
+        attemptId: record.attemptId,
+        imageDigest: record.imageDigest,
+    });
+};
+/**
+ * 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) => {
+    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) => identityEnvironmentNames
+    .filter((nameArg) => namesArg.includes(nameArg))
+    .sort();
+/**
+ * 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, identityArg) => {
+    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 = {};
+    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) => {
+    const missing = [];
+    const invalid = [];
+    const identity = {};
+    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);
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoid29ya2xvYWRyZXBsaWNhaWRlbnRpdHkuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL3dvcmtsb2FkcmVwbGljYWlkZW50aXR5LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUNBLE9BQU8sRUFBRSxjQUFjLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUVyRCxPQUFPLEVBQUUsa0JBQWtCLEVBQUUseUJBQXlCLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQUN2RixPQUFPLEVBQUUscUJBQXFCLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQztBQUUzRCxPQUFPLEVBQUUsWUFBWSxFQUFFLGtCQUFrQixFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFxQmhGOzs7O0dBSUc7QUFDSCxNQUFNLENBQUMsTUFBTSx1Q0FBdUMsR0FBRyxNQUFNLENBQUMsTUFBTSxDQUFDO0lBQ25FLFNBQVMsRUFBRSwrQkFBK0I7SUFDMUMsU0FBUyxFQUFFLCtCQUErQjtJQUMxQyxTQUFTLEVBQUUsK0JBQStCO0lBQzFDLFdBQVcsRUFBRSxpQ0FBaUM7Q0FDNkIsQ0FBQyxDQUFDO0FBSy9FLE1BQU0sWUFBWSxHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQ2hDLE1BQU0sQ0FBQyxJQUFJLENBQUMsdUNBQXVDLENBQXVDLENBQzNGLENBQUM7QUFDRixNQUFNLHdCQUF3QixHQUFzQixNQUFNLENBQUMsTUFBTSxDQUMvRCxNQUFNLENBQUMsTUFBTSxDQUFDLHVDQUF1QyxDQUFDLENBQ3ZELENBQUM7QUFFRjs7Ozs7OztHQU9HO0FBQ0gsTUFBTSxDQUFDLE1BQU0sK0JBQStCLEdBQUcsTUFBTSxDQUFDLE1BQU0sQ0FBQztJQUMzRCwwQkFBMEIsRUFBRSxZQUFZLENBQUMsTUFBTTtJQUMvQyxpQ0FBaUMsRUFBRSxxQkFBcUIsQ0FBQyx5QkFBeUIsR0FBRyxZQUFZLENBQUMsTUFBTTtDQUN6RyxDQUFDLENBQUM7QUFFSCxNQUFNLFlBQVksR0FBRyxDQUFDLFFBQWlCLEVBQXNC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

package/dist_ts/requests/coremail.d.ts

@@ -1,6 +1,7 @@
 import type * as plugins from '../plugins.js';
 import type { ICoreMailEnvelope, ICoreMailInboundDeliveryPage, ICoreMailDownloadGrant, ICoreMailGatewayMessageDescriptor, ICoreMailGatewayOutboundStatus, ICoreMailInboundDelivery, ICoreMailOutboundMessageDescriptor, ICoreMailRecipientResolution, ICoreMailReconciliationStatus, ICoreMailReplicaIdentity, ICoreMailServiceMailStatistics, ICoreMailSubmission, ICoreMailUploadGrant, TCoreMailInboundAckOutcome, TCoreMailSha256, 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, IReq_CoreMailAuthenticateWorkload> {
     method: 'coreMailAuthenticateWorkload';
     request: {
@@ -125,7 +126,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;
     };
 }
 export interface IReq_CoreMailPrepareDesiredStateUpload extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CoreMailPrepareDesiredStateUpload> {

package/package.json

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

package/readme.md

@@ -1370,6 +1370,60 @@ Version 29 widens these numeric TypeScript fields to include those explicit null
 policies; consumers must handle them before accepting configurations from v29.
 Existing numeric configurations retain their exact meaning and digest.
 
+### Workload Replica Identity
+
+Every runtime (Pallet, Onebox) injects the identity of the replica it runs into every workload,
+whether the workload reads it or not. `data.IWorkloadReplicaIdentity` is exactly
+`{ serviceId, replicaId, attemptId, imageDigest }`, the runtime assignment's own values:
+`data.buildWorkloadReplicaIdentity(assignment)` reads them from the admitted assignment through its
+exact schema, so the answer always validates. `attemptId` is the one execution attempt; a rollout or
+a replacement is a new attempt, and the controller's `attemptId` already binds the admitting
+rollout, so no rollout name or generation travels. `data.validateWorkloadReplicaIdentity` names
+every violation and `data.snapshotWorkloadReplicaIdentity` answers a detached frozen copy or throws.
+
+`data.workloadReplicaIdentityEnvironmentNames` is the one spelling of the injected names:
+`SERVEZONE_WORKLOAD_SERVICE_ID`, `SERVEZONE_WORKLOAD_REPLICA_ID`, `SERVEZONE_WORKLOAD_ATTEMPT_ID` and
+`SERVEZONE_WORKLOAD_IMAGE_DIGEST`. They sit under the platform-reserved `SERVEZONE_` prefix
+(`platformReservedSecretKeyPrefixes`). A runtime composes what a replica runs with through
+`data.composeWorkloadReplicaEnvironment(configEnvironment, identity)`: the config's environment
+with the four names added, or `refused` with `workload-identity-environment-conflict` and a message
+naming every colliding key and no value (`TWorkloadReplicaEnvironmentComposition`). An identity that
+is not exactly one is thrown. A workload reads its identity with
+`data.readWorkloadReplicaIdentityEnvironment(process.env)`, which reads the four names only and
+throws naming every missing or invalid variable, never a value, so a workload refuses to start
+naming the variable its runtime did not inject.
+
+Cloudly refuses a service whose effective environment (image and service values) or one of whose
+launcher-environment secrets states an injected name, before any runtime sees it:
+`data.findWorkloadReplicaIdentityEnvironmentConflicts(names)` answers the colliding names among
+the environment's keys and the secrets' variable names, and the service's status reads
+`workload-identity-environment-conflict`. Secrets count because WorkloadInit sets a secret over a
+plain variable of the same name.
+
+Only Cloudly states `workload-identity-environment-conflict` on the wire, in the service status it
+stores and answers on `getServiceRuntimeSpec`, `getServiceRuntimeSpecForCluster` and
+`getServiceRuntimeSpecs`. Those requests carry no protocol offer, so the reason cannot be gated on
+a reader's version, and no other refusal names this check. A reader built before the interfaces
+release that introduced this contract refuses such a status whole, so every client that reads
+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 the reason: a Pallet whose composition refuses (only a Cloudly
+before this contract places such a run) reports the 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.
+
+`IRuntimeConfig.environment` keeps its bound, `runtimeConfigContract.maximumEnvironmentEntries`
+(128). A runtime's executor admits the config's entries plus the injected ones:
+`data.workloadReplicaIdentityContract.maximumExecutorEnvironmentEntries`, computed as that bound
+plus `injectedEnvironmentEntries` (4), never a literal of the runtime's own. Pallet's native
+invocation check (`rust/src/execution.rs`, today a literal 128) admits exactly this value, and its
+TypeScript execution owner hands the composed environment to it in place of `config.environment`.
+
+Injection is gated by the release, not per peer: a Pallet moves to the interfaces release that
+introduced this contract together with the injection, so a Pallet speaking it injects. Cloudly
+raises the `minimumPeerVersion` of its Pallet runtime sessions to that release (peers first, see
+`IProtocolOffer`) in the commit that first deploys a workload requiring its identity, such as
+CoreMail 34. No controller or runtime keeps a per-version send branch.
+
 ### Authenticated Runtime Sessions
 
 `requests.runtimesession` defines `registerPalletRuntimeSession`,
@@ -2106,7 +2160,8 @@ evidence has not arrived). `refused` carries a `TServiceRuntimeRefusal`:
 `volume-initialization-unknown`, `volume-ownership-unknown`, `launcher-secret-ownership-unknown`,
 `objectstorage-endpoint-missing`, `objectstorage-binding-invalid`, `objectstorage-environment-conflict`,
 `objectstorage-endpoint-unselected`, `database-endpoint-missing`, `database-endpoint-unselected`,
-`cluster-relay-missing` or `cluster-ingress-environment-conflict`.
+`cluster-relay-missing`, `cluster-ingress-environment-conflict` or
+`workload-identity-environment-conflict`.
 The first four volume
 refusals name what a local storage claim cannot express: a volume driver other than a node-local
 directory, driver or mount options, one volume mounted by more than one replica or service, and a
@@ -2123,7 +2178,10 @@ designated ingress service, whose environment `composeClusterIngressEnvironment`
 [Cluster Ingress](#cluster-ingress): `cluster-relay-missing` is a cluster that states no valid
 relay, which an administrator enables with `enableClusterRelay`, and
 `cluster-ingress-environment-conflict` an ingress service whose own environment already sets one of
-`clusterIngressEnvironmentNames`. `ports-too-many` is a service declaring more target ports than the
+`clusterIngressEnvironmentNames`. `workload-identity-environment-conflict` is a service whose
+effective environment, or one of whose launcher-environment secrets, states one of the names every
+runtime injects, see [Workload Replica Identity](#workload-replica-identity), which also states why
+every reader of statuses moves to its release before Cloudly does. `ports-too-many` is a service declaring more target ports than the
 `runtimeConfigContract.maximumTargetPorts` (64) a config carries, where `port-protocol-unsupported`
 is about one port's protocol; `node-authority-unsupported` is a node whose session resolved fewer
 workload authorities than the spec needs, refused at the admit step rather than handed to a node
@@ -4158,11 +4216,70 @@ per-task authentication and readiness, then mark the previous verifier
 `retiring` with `acceptUntil`. Remove the previous verifier and secret only
 after its acceptance window has elapsed and no session uses that composite
 credential identity.
-Reconciliation status carries the exact CoreMail task, rollout generation, and
-image digest so Coreflow can correlate every response with its authoritative
-current task roster. Apply `data.normalizeCoreMailReconciliationStatus` before
-using pending-inbound or composite active-session counts for drain and rotation
-decisions.
+Reconciliation status and the `coreMailAuthenticateControl` response carry the
+reporting replica so Coreflow can correlate every response with its
+authoritative current roster. CoreMail 34 and later report
+`data.IWorkloadReplicaIdentity` (`serviceId`, `replicaId`, `attemptId`,
+`imageDigest`), the identity its runtime injects; the attempt is what the roster
+correlates by. A CoreMail before 34 reports the deprecated
+`data.ICoreMailReplicaIdentity` (`taskId`, `serviceId`, `rolloutId`,
+`rolloutGeneration`, `imageDigest`), whose `taskId` is that attempt. Both types
+accept either shape, and `data.normalizeCoreMailReplicaIdentity` reads each
+exactly: a record stating `taskId` is the deprecated shape, any other the
+workload identity, and neither admits a member of the other. The deprecated
+shape is removed in the next major. Apply
+`data.normalizeCoreMailReconciliationStatus` before using pending-inbound or
+composite active-session counts for drain and rotation decisions.
+
+#### CoreMail runtime environment (CoreMail 34 and later)
+
+CoreMail 34 reads:
+
+- its replica identity from `data.workloadReplicaIdentityEnvironmentNames`
+  (`SERVEZONE_WORKLOAD_SERVICE_ID`, `SERVEZONE_WORKLOAD_REPLICA_ID`,
+  `SERVEZONE_WORKLOAD_ATTEMPT_ID`, `SERVEZONE_WORKLOAD_IMAGE_DIGEST`) through
+  `data.readWorkloadReplicaIdentityEnvironment`, and refuses to start naming a
+  missing variable;
+- its database and object storage under the names its platform bindings deliver,
+  `data.coreMailStorageEnvironmentNames`: `MONGODB_URL` and `MONGODB_DATABASE`
+  (the Corestore database binding), `S3_ENDPOINT`, `S3_REGION` and `S3_BUCKET`
+  (the object-storage binding) and `S3_ACCESS_KEY` and `S3_SECRET_KEY` (that
+  binding's credential secrets);
+- `COREMAIL_CONTROL_BOOTSTRAP` (`data.coreMailRuntimeKeys.controlBootstrap`), and
+  optionally `COREMAIL_PORT`, `COREMAIL_HOSTNAMES` and
+  `COREMAIL_MONGODB_MAX_POOL_SIZE` (`port`, `hostnames`, `mongoDbMaxPoolSize`);
+- the secrets its desired state references by name, as before.
+
+It no longer reads `COREMAIL_SERVICE_ID`, `COREMAIL_TASK_ID`,
+`COREMAIL_ROLLOUT_ID`, `COREMAIL_ROLLOUT_GENERATION`, `COREMAIL_IMAGE_DIGEST`,
+`COREMAIL_MONGODB_URL`, `COREMAIL_MONGODB_NAME`, `COREMAIL_STORAGE_DESCRIPTOR`
+or `COREMAIL_BUCKET_NAME`, and a provisioner stops writing them. CoreMail 34
+runs only on a runtime that injects its identity, see
+[Workload Replica Identity](#workload-replica-identity).
+
+Readers first. A reader built before the interfaces release that introduced
+`data.IWorkloadReplicaIdentity` refuses CoreMail 34's replica whole, in the
+`coreMailAuthenticateControl` response and in reconciliation status alike: its
+`normalizeCoreMailReplicaIdentity` requires `taskId`, `rolloutId` and
+`rolloutGeneration`. The `minimumPeerVersion` of Pallet runtime sessions does not
+reach these readers, so the order is fixed: `@serve.zone/api`'s
+`CoreMailControlClient`, and with it Cloudly's CoreMail manager and Onebox's
+CoreMail provider, move to that interfaces release before any CoreMail 34 runs.
+Cloudly deploys CoreMail 34 only once its own reader is on that release, and
+Onebox moves its CoreMail pin to 34 only in the release that carries the
+upgraded reader. A CoreMail before 34 keeps writing the deprecated shape, which
+every reader reads as before.
+
+In source, both carrying types and the normalizer's return value are
+`data.IWorkloadReplicaIdentity | data.ICoreMailReplicaIdentity`, a type-level
+change shipped in a 32.x minor. The consumers that read the replica,
+`@serve.zone/api` (`CoreMailControlClient`), Cloudly (CoreMail manager), Onebox
+(CoreMail provider) and CoreMail, narrow by `taskId`:
+
+```typescript
+const replica = data.normalizeCoreMailReplicaIdentity(response.replica);
+const attemptId = 'taskId' in replica ? replica.taskId : replica.attemptId;
+```
 
 #### CoreMail control-plane settings and operator RPCs
 
@@ -4276,6 +4393,35 @@ request fence, and the trusted local organization/cluster expectation. It never
 decrypts. Organization and cluster are derived from the verified cluster JWT
 and cannot be selected by request fields.
 
+### Service Mail Environment
+
+`data.serviceMailEnvironmentNames` spells the environment a service's default
+sender is delivered under, once for the provisioners (Cloudly, Onebox) and the
+reader (`@serve.zone/platformclient`). It has three groups, each delivered
+whole: the typed dcrouter-direct binding (`MAIL_FROM`, `MAIL_TYPED_URL`,
+`MAIL_API_CREDENTIAL_ID`, `MAIL_API_CREDENTIAL_SECRET`), its SMTP compatibility
+surface (`SMTP_HOST`, `SMTP_PORT`, `SMTP_TLS_MODE`, `SMTP_USERNAME`,
+`SMTP_PASSWORD`) and a CoreMail binding (`MAIL_COREMAIL_URL`,
+`MAIL_COREMAIL_BINDING_ID`, `MAIL_COREMAIL_CREDENTIAL_ID`,
+`MAIL_COREMAIL_CREDENTIAL_VERSION`, `MAIL_COREMAIL_CREDENTIAL_SECRET`, with
+`MAIL_FROM`). The credential secrets and passwords are delivered as secrets.
+`data.createServiceMailAddressEnvironmentNames(token)` answers the same names
+for a further sender address, scoped to its upper-case address token
+(`MAIL_<TOKEN>_FROM`, `MAIL_<TOKEN>_TYPED_URL`, `MAIL_<TOKEN>_SMTP_HOST`,
+`MAIL_<TOKEN>_COREMAIL_URL`, …); any other token is thrown.
+
+`MAIL_TYPED_URL` and every `MAIL_<TOKEN>_TYPED_URL` carry
+`ICloudlySettings.dcrouterMailEndpointUrl`, the canonical HTTPS URL of
+dcrouter's tenant mail listener, and nothing else: never `dcrouterGatewayUrl`,
+which is Cloudly's own gateway-client endpoint, and never a CoreMail endpoint,
+which travels as `MAIL_COREMAIL_URL`. `data.validateDcrouterMailEndpointUrl`
+accepts an `https:` URL without credentials, query or fragment, at most
+`data.dcrouterMailEndpointUrlMaximumLength` (2,048) characters, written exactly
+as `new URL(value).href` spells it, and names every violation without quoting
+the value. When the setting is absent, Cloudly refuses to provision a typed
+dcrouter-direct mail binding and names `dcrouterMailEndpointUrl` in the refusal;
+it falls back to no other endpoint.
+
 ### Corestore Runtime Credentials
 
 The Node-only `/runtime` export defines

package/ts/00_commitinfo_data.ts

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

package/ts/data/coremail.runtime.ts

@@ -48,6 +48,10 @@ import {
   type TCoreMailWorkloadOperation,
 } from './coremail.js';
 import type { IMailConnectionInfo } from './mail.js';
+import {
+  validateWorkloadReplicaIdentity,
+  type IWorkloadReplicaIdentity,
+} from './workloadreplicaidentity.js';
 
 export const coreMailCanonicalJsonRules = strictCanonicalJsonRules;
 
@@ -1889,11 +1893,32 @@ export const normalizeCoreMailDesiredState = (
   return deepFreezeValue(normalized);
 };
 
+/**
+ * The replica a CoreMail reports, read exactly as one of two closed shapes.
+ *
+ * CoreMail 34 and later report `IWorkloadReplicaIdentity`, the identity its runtime injects, and
+ * it is read by that contract's own rules (`validateWorkloadReplicaIdentity`). A CoreMail before
+ * 34 reports the deprecated `ICoreMailReplicaIdentity`, recognised by its `taskId`, and it is read
+ * as before. Neither shape admits a member of the other.
+ */
 export const normalizeCoreMailReplicaIdentity = (
   valueArg: unknown,
   pathArg = 'replica',
-): ICoreMailReplicaIdentity => {
+): IWorkloadReplicaIdentity | ICoreMailReplicaIdentity => {
   const record = readRecord(valueArg, pathArg);
+  if (!Object.hasOwn(record, 'taskId')) {
+    assertKeys(record, pathArg, ['serviceId', 'replicaId', 'attemptId', 'imageDigest']);
+    const errors = validateWorkloadReplicaIdentity(record);
+    if (errors.length > 0) {
+      fail(`${pathArg}.${errors[0]}`);
+    }
+    return deepFreezeValue({
+      serviceId: record.serviceId as string,
+      replicaId: record.replicaId as string,
+      attemptId: record.attemptId as string,
+      imageDigest: record.imageDigest as IWorkloadReplicaIdentity['imageDigest'],
+    });
+  }
   assertKeys(
     record,
     pathArg,

package/ts/data/coremail.ts

@@ -7,6 +7,10 @@
  * binding authority.
  */
 
+import type { IWorkloadReplicaIdentity } from './workloadreplicaidentity.js';
+import type { TCorestoreDatabaseCredentialKey, TCorestoreObjectStorageCredentialSecretKey } from '../runtime.corestore.js';
+import type { TObjectStorageEndpointEnvironmentKey } from '../platform/objectstorage.js';
+
 export type TCoreMailSha256 = `sha256:${string}`;
 
 export type TCoreMailCapability = 'outbound' | 'inbound';
@@ -293,6 +297,15 @@ export interface ICoreMailDesiredState {
   cursorKeys: ICoreMailRuntimeKeyReference[];
 }
 
+/**
+ * The replica identity CoreMail before 34 reports, read from the `COREMAIL_*` variables its
+ * provisioner fabricated.
+ *
+ * @deprecated CoreMail 34 and later report `IWorkloadReplicaIdentity`, which its runtime injects
+ * (`workloadReplicaIdentityEnvironmentNames`); `taskId` is that identity's `attemptId`.
+ * `normalizeCoreMailReplicaIdentity` still reads this shape, exactly, from a CoreMail before 34;
+ * removed in the next major.
+ */
 export interface ICoreMailReplicaIdentity {
   taskId: string;
   serviceId: string;
@@ -314,7 +327,11 @@ export interface ICoreMailBindingReconciliationStatus {
 }
 
 export interface ICoreMailReconciliationStatus {
-  replica: ICoreMailReplicaIdentity;
+  /**
+   * The reporting replica: `IWorkloadReplicaIdentity` from CoreMail 34 on, the deprecated
+   * `ICoreMailReplicaIdentity` from an earlier CoreMail. Each is read exactly.
+   */
+  replica: IWorkloadReplicaIdentity | ICoreMailReplicaIdentity;
   state: TCoreMailReconciliationState;
   appliedConfigEpoch: number;
   appliedDesiredStateDigest: TCoreMailSha256;
@@ -495,4 +512,28 @@ export const coreMailRuntimeKeys = Object.freeze({
   controlBootstrap: 'COREMAIL_CONTROL_BOOTSTRAP',
   controlCredentialSecret: 'COREMAIL_CONTROL_CREDENTIAL_SECRET',
   gatewayCredentialSecret: 'COREMAIL_GATEWAY_CREDENTIAL',
+  /** Optional listener port inside the workload. */
+  port: 'COREMAIL_PORT',
+  /** Optional comma-separated canonical hostname list. */
+  hostnames: 'COREMAIL_HOSTNAMES',
+  /** Optional MongoDB connection pool bound. */
+  mongoDbMaxPoolSize: 'COREMAIL_MONGODB_MAX_POOL_SIZE',
 } as const);
+
+/**
+ * The storage CoreMail 34 and later read, under the names its platform bindings deliver: the
+ * Corestore database binding's `MONGODB_URL` and `MONGODB_DATABASE`, the object-storage binding's
+ * `S3_ENDPOINT`, `S3_REGION` and `S3_BUCKET`, and that binding's `S3_ACCESS_KEY` and
+ * `S3_SECRET_KEY` secrets. They replace `COREMAIL_MONGODB_URL`, `COREMAIL_MONGODB_NAME`,
+ * `COREMAIL_STORAGE_DESCRIPTOR` and `COREMAIL_BUCKET_NAME`.
+ */
+export const coreMailStorageEnvironmentNames = Object.freeze({
+  databaseUrl: 'MONGODB_URL',
+  databaseName: 'MONGODB_DATABASE',
+  objectStorageEndpoint: 'S3_ENDPOINT',
+  objectStorageRegion: 'S3_REGION',
+  objectStorageBucket: 'S3_BUCKET',
+  objectStorageAccessKey: 'S3_ACCESS_KEY',
+  objectStorageSecretKey: 'S3_SECRET_KEY',
+} as const satisfies Readonly<Record<string,
+  TCorestoreDatabaseCredentialKey | TObjectStorageEndpointEnvironmentKey | TCorestoreObjectStorageCredentialSecretKey>>);

package/ts/data/index.ts

@@ -91,3 +91,4 @@ export * from './traffic.js';
 export * from './user.js';
 export * from './version.js';
 export * from './webpush.js';
+export * from './workloadreplicaidentity.js';

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

@@ -168,7 +168,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];

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];