@serve.zone/interfaces 21.1.0 → 23.0.0

package/ts/data/coremail.runtime.ts

@@ -6,18 +6,58 @@ import {
 } from '../private/canonicaljson.js';
 import {
   coreMailCredentialVerifierPolicy,
+  coreMailLimits,
+  coreMailTransferProtocol,
+  coreMailTransferTokenPolicy,
+  coreMailWorkloadOperationPolicy,
+  type ICoreMailBindingReconciliationStatus,
   type ICoreMailBindingCredentialVerifier,
   type ICoreMailBindingDesiredState,
+  type ICoreMailContentDescriptor,
   type ICoreMailControlBootstrap,
   type ICoreMailDesiredState,
+  type ICoreMailDownloadGrant,
+  type ICoreMailEnvelope,
+  type ICoreMailErrorData,
   type ICoreMailGatewayDesiredState,
+  type ICoreMailGatewayOutboundStatus,
   type ICoreMailGatewayPeerDesiredState,
+  type ICoreMailInboundDelivery,
+  type ICoreMailInboundDeliveryPage,
+  type ICoreMailMailbox,
+  type ICoreMailOutboundMessageDescriptor,
+  type ICoreMailPartStatus,
+  type ICoreMailRuntimeKeyReference,
+  type ICoreMailReconciliationStatus,
+  type ICoreMailReplicaIdentity,
+  type ICoreMailSubmission,
+  type ICoreMailTransferGrant,
+  type ICoreMailUploadGrant,
   type TCoreMailCapability,
+  type TCoreMailBindingState,
+  type TCoreMailErrorCode,
   type TCoreMailSha256,
+  type TCoreMailWorkloadOperation,
 } from './coremail.js';
 
 export const coreMailCanonicalJsonRules = strictCanonicalJsonRules;
 
+export const resolveCoreMailWorkloadOperations = (
+  stateArg: TCoreMailBindingState,
+  capabilitiesArg: readonly TCoreMailCapability[],
+): readonly TCoreMailWorkloadOperation[] => {
+  const operations = new Set<TCoreMailWorkloadOperation>();
+  for (const capability of ['outbound', 'inbound'] as const) {
+    if (!capabilitiesArg.includes(capability)) {
+      continue;
+    }
+    for (const operation of coreMailWorkloadOperationPolicy[stateArg][capability]) {
+      operations.add(operation);
+    }
+  }
+  return Object.freeze([...operations]);
+};
+
 export const coreMailContractLimits = Object.freeze({
   maximumIdentifierBytes: 128,
   maximumEnvironmentKeyBytes: 128,
@@ -27,6 +67,16 @@ export const coreMailContractLimits = Object.freeze({
   maximumCredentialsPerAuthority: 16,
   maximumAllowedSendersPerBinding: 1_000,
   maximumInboundRecipientsPerBinding: 10_000,
+  maximumMessagesPerMinute: 100_000,
+  maximumMessagesPerDay: 10_000_000,
+  maximumPendingInbound: 1_000_000,
+  maximumDisplayNameBytes: 256,
+  maximumSubjectBytes: 768,
+  maximumHeaderCount: 32,
+  maximumHeaderValueBytes: 768,
+  maximumFilenameBytes: 512,
+  maximumContentIdBytes: 256,
+  maximumBearerTokenBytes: 1_024,
 } as const);
 
 export class CoreMailContractError extends Error {
@@ -145,6 +195,10 @@ const requireString = (
 };
 
 const identifierRegex = /^[A-Za-z0-9](?:[A-Za-z0-9._:-]{0,126}[A-Za-z0-9])?$/;
+const uuidRegex =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const contentTypeRegex =
+  /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+(?:; ?[a-z0-9!#$&^_.+-]+=(?:"[^"\r\n]{1,100}"|[a-z0-9!#$&^_.+-]+))*$/i;
 
 const requireIdentifier = (valueArg: unknown, pathArg: string): string => {
   const value = requireString(
@@ -158,13 +212,51 @@ const requireIdentifier = (valueArg: unknown, pathArg: string): string => {
   return value;
 };
 
+const requireUuid = (valueArg: unknown, pathArg: string): string => {
+  if (typeof valueArg !== 'string' || !uuidRegex.test(valueArg)) {
+    return fail(`${pathArg} must be a canonical UUID`);
+  }
+  return valueArg;
+};
+
+const requireContentType = (valueArg: unknown, pathArg: string): string => {
+  if (typeof valueArg !== 'string' || !contentTypeRegex.test(valueArg)) {
+    return fail(`${pathArg} must be a canonical content type`);
+  }
+  return valueArg;
+};
+
+const requireDisplayText = (
+  valueArg: unknown,
+  pathArg: string,
+  maximumBytesArg: number,
+  allowEmptyArg = false,
+): string => {
+  if (
+    typeof valueArg !== 'string'
+    || (!allowEmptyArg && valueArg.length === 0)
+    || /[\u0000-\u001f\u007f]/.test(valueArg)
+    || new TextEncoder().encode(valueArg).byteLength > maximumBytesArg
+  ) {
+    return fail(`${pathArg} must be bounded display text`);
+  }
+  return valueArg;
+};
+
 const requireSafeInteger = (
   valueArg: unknown,
   pathArg: string,
   minimumArg: number,
+  maximumArg = Number.MAX_SAFE_INTEGER,
 ): number => {
-  if (!Number.isSafeInteger(valueArg) || (valueArg as number) < minimumArg) {
-    return fail(`${pathArg} must be a safe integer greater than or equal to ${minimumArg}`);
+  if (
+    !Number.isSafeInteger(valueArg)
+    || (valueArg as number) < minimumArg
+    || (valueArg as number) > maximumArg
+  ) {
+    return fail(
+      `${pathArg} must be a safe integer between ${minimumArg} and ${maximumArg}`,
+    );
   }
   return valueArg as number;
 };
@@ -311,6 +403,94 @@ const normalizeCredentialSet = (
   );
 };
 
+const requireEnvironmentKey = (valueArg: unknown, pathArg: string): string => {
+  const value = requireString(
+    valueArg,
+    pathArg,
+    coreMailContractLimits.maximumEnvironmentKeyBytes,
+  );
+  if (!/^[A-Z][A-Z0-9_]{0,127}$/.test(value)) {
+    fail(`${pathArg} must be a canonical environment key`);
+  }
+  return value;
+};
+
+export const normalizeCoreMailRuntimeKeyReference = (
+  valueArg: unknown,
+  pathArg = 'runtimeKey',
+): ICoreMailRuntimeKeyReference => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    ['keyId', 'version', 'state', 'secretKey'],
+    ['acceptUntil'],
+  );
+  const state = record.state === 'current' || record.state === 'retiring'
+    ? record.state
+    : fail(`${pathArg}.state must be current or retiring`);
+  if (state === 'current' && Object.hasOwn(record, 'acceptUntil')) {
+    fail(`${pathArg}.acceptUntil is forbidden for a current key`);
+  }
+  if (state === 'retiring' && !Object.hasOwn(record, 'acceptUntil')) {
+    fail(`${pathArg}.acceptUntil is required for a retiring key`);
+  }
+  const normalized: ICoreMailRuntimeKeyReference = {
+    keyId: requireIdentifier(record.keyId, `${pathArg}.keyId`),
+    version: requireSafeInteger(record.version, `${pathArg}.version`, 1),
+    state,
+    secretKey: requireEnvironmentKey(record.secretKey, `${pathArg}.secretKey`),
+  };
+  if (state === 'retiring') {
+    normalized.acceptUntil = requireSafeInteger(
+      record.acceptUntil,
+      `${pathArg}.acceptUntil`,
+      1,
+    );
+  }
+  return deepFreezeValue(normalized);
+};
+
+const normalizeRuntimeKeySet = (
+  valueArg: unknown,
+  pathArg: string,
+): ICoreMailRuntimeKeyReference[] => {
+  const keys = readArray(
+    valueArg,
+    pathArg,
+    coreMailContractLimits.maximumCredentialsPerAuthority,
+  ).map((entryArg, indexArg) =>
+    normalizeCoreMailRuntimeKeyReference(entryArg, `${pathArg}[${indexArg}]`),
+  );
+  if (keys.length === 0 || keys.filter((entryArg) => entryArg.state === 'current').length !== 1) {
+    fail(`${pathArg} must contain exactly one current key`);
+  }
+  const keyIds = new Set<string>();
+  const versions = new Set<number>();
+  const secretKeys = new Set<string>();
+  for (const key of keys) {
+    if (
+      keyIds.has(key.keyId)
+      || versions.has(key.version)
+      || secretKeys.has(key.secretKey)
+    ) {
+      fail(`${pathArg} contains a duplicate keyId, version, or secretKey`);
+    }
+    keyIds.add(key.keyId);
+    versions.add(key.version);
+    secretKeys.add(key.secretKey);
+  }
+  const current = keys.find((entryArg) => entryArg.state === 'current')!;
+  if (keys.some((entryArg) =>
+    entryArg.state === 'retiring' && entryArg.version >= current.version
+  )) {
+    fail(`${pathArg} current key must have the greatest version`);
+  }
+  return keys.sort((leftArg, rightArg) =>
+    leftArg.version - rightArg.version || compareStrings(leftArg.keyId, rightArg.keyId),
+  );
+};
+
 const mailboxLocalPartRegex = /^[a-z0-9!#$%&'*+/=?^_`{|}~.-]+$/;
 const mailboxDomainLabelRegex = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 
@@ -342,6 +522,839 @@ const requireCanonicalMailbox = (valueArg: unknown, pathArg: string): string =>
   return value;
 };
 
+const normalizeMailbox = (valueArg: unknown, pathArg: string): ICoreMailMailbox => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(record, pathArg, ['address'], ['displayName']);
+  const normalized: ICoreMailMailbox = {
+    address: requireCanonicalMailbox(record.address, `${pathArg}.address`),
+  };
+  if (Object.hasOwn(record, 'displayName')) {
+    normalized.displayName = requireDisplayText(
+      record.displayName,
+      `${pathArg}.displayName`,
+      coreMailContractLimits.maximumDisplayNameBytes,
+    );
+  }
+  return normalized;
+};
+
+const normalizeMailboxArray = (
+  valueArg: unknown,
+  pathArg: string,
+  allowEmptyArg: boolean,
+): ICoreMailMailbox[] => {
+  const values = readArray(valueArg, pathArg, coreMailLimits.recipientCount);
+  if (!allowEmptyArg && values.length === 0) {
+    fail(`${pathArg} must not be empty`);
+  }
+  const normalized = values.map((entryArg, indexArg) =>
+    normalizeMailbox(entryArg, `${pathArg}[${indexArg}]`),
+  );
+  if (new Set(normalized.map((entryArg) => entryArg.address)).size !== normalized.length) {
+    fail(`${pathArg} must contain unique mailbox addresses`);
+  }
+  return normalized;
+};
+
+export const normalizeCoreMailEnvelope = (
+  valueArg: unknown,
+  pathArg = 'envelope',
+): ICoreMailEnvelope => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(record, pathArg, ['mailFrom', 'rcptTo']);
+  const mailFrom = record.mailFrom === ''
+    ? ''
+    : requireCanonicalMailbox(record.mailFrom, `${pathArg}.mailFrom`);
+  const rcptTo = readArray(
+    record.rcptTo,
+    `${pathArg}.rcptTo`,
+    coreMailLimits.recipientCount,
+  ).map((entryArg, indexArg) =>
+    requireCanonicalMailbox(entryArg, `${pathArg}.rcptTo[${indexArg}]`),
+  );
+  if (rcptTo.length === 0 || new Set(rcptTo).size !== rcptTo.length) {
+    fail(`${pathArg}.rcptTo must contain unique recipients`);
+  }
+  return deepFreezeValue({ mailFrom, rcptTo });
+};
+
+const forbiddenHeaderNames = new Set([
+  'bcc',
+  'cc',
+  'content-transfer-encoding',
+  'content-type',
+  'date',
+  'delivered-to',
+  'dkim-signature',
+  'domainkey-signature',
+  'from',
+  'message-id',
+  'mime-version',
+  'received',
+  'received-spf',
+  'reply-to',
+  'return-path',
+  'sender',
+  'subject',
+  'to',
+  'x-original-to',
+]);
+
+const isTransportOwnedHeader = (nameArg: string): boolean =>
+  forbiddenHeaderNames.has(nameArg)
+  || nameArg === 'authentication-results'
+  || nameArg.startsWith('arc-')
+  || nameArg.startsWith('resent-')
+  || nameArg.startsWith('x-coremail-');
+
+const normalizeContentDescriptor = (
+  valueArg: unknown,
+  pathArg: string,
+): ICoreMailContentDescriptor => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    ['partId', 'kind', 'contentType', 'sha256', 'lengthBytes'],
+    ['filename', 'contentId'],
+  );
+  const kind = record.kind === 'text'
+    || record.kind === 'html'
+    || record.kind === 'attachment'
+    ? record.kind
+    : fail(`${pathArg}.kind is invalid`);
+  const maximumBytes = kind === 'text'
+    ? coreMailLimits.textPartBytes
+    : kind === 'html'
+      ? coreMailLimits.htmlPartBytes
+      : coreMailLimits.attachmentBytes;
+  const normalized: ICoreMailContentDescriptor = {
+    partId: requireIdentifier(record.partId, `${pathArg}.partId`),
+    kind,
+    contentType: requireContentType(record.contentType, `${pathArg}.contentType`),
+    sha256: normalizeCoreMailSha256(record.sha256, `${pathArg}.sha256`),
+    lengthBytes: requireSafeInteger(
+      record.lengthBytes,
+      `${pathArg}.lengthBytes`,
+      0,
+      maximumBytes,
+    ),
+  };
+  if (Object.hasOwn(record, 'filename')) {
+    normalized.filename = requireDisplayText(
+      record.filename,
+      `${pathArg}.filename`,
+      coreMailContractLimits.maximumFilenameBytes,
+    );
+  }
+  if (Object.hasOwn(record, 'contentId')) {
+    normalized.contentId = requireDisplayText(
+      record.contentId,
+      `${pathArg}.contentId`,
+      coreMailContractLimits.maximumContentIdBytes,
+    );
+  }
+  return normalized;
+};
+
+export const normalizeCoreMailOutboundMessageDescriptor = (
+  valueArg: unknown,
+  pathArg = 'message',
+): ICoreMailOutboundMessageDescriptor => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    ['sender', 'recipients', 'subject', 'parts'],
+    ['replyTo', 'headers'],
+  );
+  const recipientsRecord = readRecord(record.recipients, `${pathArg}.recipients`);
+  assertKeys(recipientsRecord, `${pathArg}.recipients`, ['to'], ['cc', 'bcc']);
+  const to = normalizeMailboxArray(recipientsRecord.to, `${pathArg}.recipients.to`, false);
+  const cc = Object.hasOwn(recipientsRecord, 'cc')
+    ? normalizeMailboxArray(recipientsRecord.cc, `${pathArg}.recipients.cc`, true)
+    : undefined;
+  const bcc = Object.hasOwn(recipientsRecord, 'bcc')
+    ? normalizeMailboxArray(recipientsRecord.bcc, `${pathArg}.recipients.bcc`, true)
+    : undefined;
+  const recipientAddresses = [...to, ...(cc || []), ...(bcc || [])]
+    .map((entryArg) => entryArg.address);
+  if (
+    recipientAddresses.length > coreMailLimits.recipientCount
+    || new Set(recipientAddresses).size !== recipientAddresses.length
+  ) {
+    fail(`${pathArg}.recipients must contain at most ${coreMailLimits.recipientCount} unique addresses`);
+  }
+  const parts = readArray(
+    record.parts,
+    `${pathArg}.parts`,
+    coreMailLimits.attachmentCount + 2,
+  ).map((entryArg, indexArg) =>
+    normalizeContentDescriptor(entryArg, `${pathArg}.parts[${indexArg}]`),
+  );
+  if (
+    parts.length === 0
+    || new Set(parts.map((entryArg) => entryArg.partId)).size !== parts.length
+    || parts.filter((entryArg) => entryArg.kind === 'text').length > 1
+    || parts.filter((entryArg) => entryArg.kind === 'html').length > 1
+    || parts.filter((entryArg) => entryArg.kind === 'attachment').length > coreMailLimits.attachmentCount
+    || parts.filter((entryArg) => entryArg.kind === 'attachment')
+      .reduce((totalArg, entryArg) => totalArg + entryArg.lengthBytes, 0)
+      > coreMailLimits.aggregateAttachmentBytes
+  ) {
+    fail(`${pathArg}.parts is invalid`);
+  }
+  let headers: ICoreMailOutboundMessageDescriptor['headers'];
+  if (Object.hasOwn(record, 'headers')) {
+    const seenHeaderNames = new Set<string>();
+    headers = readArray(
+      record.headers,
+      `${pathArg}.headers`,
+      coreMailContractLimits.maximumHeaderCount,
+    ).map((entryArg, indexArg) => {
+      const headerPath = `${pathArg}.headers[${indexArg}]`;
+      const headerRecord = readRecord(entryArg, headerPath);
+      assertKeys(headerRecord, headerPath, ['name', 'value']);
+      if (
+        typeof headerRecord.name !== 'string'
+        || !/^[A-Za-z][A-Za-z0-9-]{0,62}$/.test(headerRecord.name)
+      ) {
+        return fail(`${headerPath}.name is invalid`);
+      }
+      const lowerName = headerRecord.name.toLowerCase();
+      if (isTransportOwnedHeader(lowerName) || seenHeaderNames.has(lowerName)) {
+        return fail(`${headerPath}.name is transport-owned or duplicated`);
+      }
+      seenHeaderNames.add(lowerName);
+      return {
+        name: headerRecord.name,
+        value: requireDisplayText(
+          headerRecord.value,
+          `${headerPath}.value`,
+          coreMailContractLimits.maximumHeaderValueBytes,
+          true,
+        ),
+      };
+    });
+  }
+  const normalized: ICoreMailOutboundMessageDescriptor = {
+    sender: normalizeMailbox(record.sender, `${pathArg}.sender`),
+    recipients: {
+      to,
+      ...(cc ? { cc } : {}),
+      ...(bcc ? { bcc } : {}),
+    },
+    subject: requireDisplayText(
+      record.subject,
+      `${pathArg}.subject`,
+      coreMailContractLimits.maximumSubjectBytes,
+      true,
+    ),
+    parts,
+  };
+  if (Object.hasOwn(record, 'replyTo')) {
+    normalized.replyTo = normalizeMailbox(record.replyTo, `${pathArg}.replyTo`);
+  }
+  if (headers) {
+    normalized.headers = headers;
+  }
+  return deepFreezeValue(normalized);
+};
+
+export const normalizeCoreMailInboundPageLimit = (valueArg: unknown): number =>
+  requireSafeInteger(valueArg, 'inboundPageLimit', 1, coreMailLimits.inboundPageSize);
+
+const coreMailErrorCodes = new Set<TCoreMailErrorCode>([
+  'AUTHENTICATION_FAILED',
+  'AUTHENTICATION_EXPIRED',
+  'AUTHORITY_REVOKED',
+  'CAPABILITY_DENIED',
+  'NOT_FOUND',
+  'INVALID_REQUEST',
+  'INVALID_MAILBOX',
+  'INVALID_SENDER',
+  'INVALID_RECIPIENT',
+  'INVALID_HEADER',
+  'PAYLOAD_LIMIT_EXCEEDED',
+  'QUOTA_EXCEEDED',
+  'IDEMPOTENCY_CONFLICT',
+  'STATE_CONFLICT',
+  'TRANSFER_GRANT_EXPIRED',
+  'TRANSFER_GRANT_REPLAYED',
+  'TRANSFER_LENGTH_MISMATCH',
+  'TRANSFER_DIGEST_MISMATCH',
+  'TRANSFER_ENCODING_UNSUPPORTED',
+  'OBJECT_INTEGRITY_CONFLICT',
+  'DELIVERY_NOT_FETCHED',
+  'DELIVERY_DEFERRED',
+  'DELIVERY_FAILED',
+  'DELIVERY_DEAD_LETTERED',
+  'GATEWAY_UNAVAILABLE',
+  'RECONCILIATION_FENCE_MISMATCH',
+]);
+
+export const normalizeCoreMailErrorData = (
+  valueArg: unknown,
+  pathArg = 'error',
+): ICoreMailErrorData => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(record, pathArg, ['code', 'retryable'], ['retryAfterMs']);
+  if (typeof record.code !== 'string' || !coreMailErrorCodes.has(record.code as TCoreMailErrorCode)) {
+    fail(`${pathArg}.code is invalid`);
+  }
+  if (typeof record.retryable !== 'boolean') {
+    fail(`${pathArg}.retryable must be boolean`);
+  }
+  const normalized: ICoreMailErrorData = {
+    code: record.code as TCoreMailErrorCode,
+    retryable: record.retryable as boolean,
+  };
+  if (Object.hasOwn(record, 'retryAfterMs')) {
+    if (!record.retryable) {
+      fail(`${pathArg}.retryAfterMs requires retryable to be true`);
+    }
+    normalized.retryAfterMs = requireSafeInteger(
+      record.retryAfterMs,
+      `${pathArg}.retryAfterMs`,
+      1,
+    );
+  }
+  return deepFreezeValue(normalized);
+};
+
+export const normalizeCoreMailTransferGrant = (
+  valueArg: unknown,
+  pathArg = 'transferGrant',
+): ICoreMailTransferGrant => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    [
+      'grantId',
+      'method',
+      'path',
+      'bearerToken',
+      'sha256',
+      'lengthBytes',
+      'contentType',
+      'issuedAt',
+      'expiresAt',
+    ],
+  );
+  const grantId = requireUuid(record.grantId, `${pathArg}.grantId`);
+  const method = record.method === 'PUT' || record.method === 'GET'
+    ? record.method
+    : fail(`${pathArg}.method must be PUT or GET`);
+  const path = requireString(record.path, `${pathArg}.path`, 128);
+  if (path !== `${coreMailTransferProtocol.pathPrefix}${grantId}`) {
+    fail(`${pathArg}.path must match its grantId`);
+  }
+  const bearerToken = requireString(
+    record.bearerToken,
+    `${pathArg}.bearerToken`,
+    coreMailContractLimits.maximumBearerTokenBytes,
+  );
+  let decodedToken: string;
+  try {
+    decodedToken = globalThis.atob(
+      `${bearerToken.replace(/-/g, '+').replace(/_/g, '/')}${'='.repeat((4 - (bearerToken.length % 4)) % 4)}`,
+    );
+  } catch {
+    return fail(`${pathArg}.bearerToken must use ${coreMailTransferTokenPolicy.format}`);
+  }
+  const canonicalToken = globalThis.btoa(decodedToken)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/u, '');
+  if (
+    decodedToken.length !== coreMailTransferTokenPolicy.decodedBytes
+    || bearerToken.length !== coreMailTransferTokenPolicy.encodedCharacters
+    || canonicalToken !== bearerToken
+  ) {
+    fail(`${pathArg}.bearerToken must use ${coreMailTransferTokenPolicy.format}`);
+  }
+  const issuedAt = requireSafeInteger(record.issuedAt, `${pathArg}.issuedAt`, 1);
+  const expiresAt = requireSafeInteger(record.expiresAt, `${pathArg}.expiresAt`, 1);
+  if (expiresAt - issuedAt !== coreMailLimits.transferGrantTtlMs) {
+    fail(`${pathArg} must use the fixed transfer grant lifetime`);
+  }
+  return deepFreezeValue({
+    grantId,
+    method,
+    path,
+    bearerToken,
+    sha256: normalizeCoreMailSha256(record.sha256, `${pathArg}.sha256`),
+    lengthBytes: requireSafeInteger(
+      record.lengthBytes,
+      `${pathArg}.lengthBytes`,
+      0,
+      coreMailLimits.serializedMimeBytes,
+    ),
+    contentType: requireContentType(record.contentType, `${pathArg}.contentType`),
+    issuedAt,
+    expiresAt,
+  });
+};
+
+export const normalizeCoreMailUploadGrant = (
+  valueArg: unknown,
+  pathArg = 'uploadGrant',
+): ICoreMailUploadGrant => {
+  const grant = normalizeCoreMailTransferGrant(valueArg, pathArg);
+  if (grant.method !== 'PUT') {
+    fail(`${pathArg}.method must be PUT`);
+  }
+  return grant as ICoreMailUploadGrant;
+};
+
+export const normalizeCoreMailDownloadGrant = (
+  valueArg: unknown,
+  pathArg = 'downloadGrant',
+): ICoreMailDownloadGrant => {
+  const grant = normalizeCoreMailTransferGrant(valueArg, pathArg);
+  if (grant.method !== 'GET') {
+    fail(`${pathArg}.method must be GET`);
+  }
+  return grant as ICoreMailDownloadGrant;
+};
+
+const normalizePartStatus = (valueArg: unknown, pathArg: string): ICoreMailPartStatus => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(record, pathArg, ['partId', 'state', 'sha256', 'lengthBytes']);
+  const state = record.state === 'missing'
+    || record.state === 'uploading'
+    || record.state === 'complete'
+    || record.state === 'failed'
+    ? record.state
+    : fail(`${pathArg}.state is invalid`);
+  return {
+    partId: requireIdentifier(record.partId, `${pathArg}.partId`),
+    state,
+    sha256: normalizeCoreMailSha256(record.sha256, `${pathArg}.sha256`),
+    lengthBytes: requireSafeInteger(
+      record.lengthBytes,
+      `${pathArg}.lengthBytes`,
+      0,
+      coreMailLimits.attachmentBytes,
+    ),
+  };
+};
+
+const assertOutboundStateFields = (
+  stateArg: ICoreMailSubmission['state'],
+  valueArg: {
+    nextAttemptAt?: number;
+    error?: ICoreMailErrorData;
+    deliveredAt?: number;
+    terminalAt?: number;
+  },
+  pathArg: string,
+): void => {
+  if (stateArg === 'deferred') {
+    if (
+      valueArg.nextAttemptAt === undefined
+      || !valueArg.error?.retryable
+      || valueArg.terminalAt !== undefined
+      || valueArg.deliveredAt !== undefined
+    ) {
+      fail(`${pathArg} deferred state fields are inconsistent`);
+    }
+    return;
+  }
+  if (stateArg === 'failed' || stateArg === 'deadLettered') {
+    if (
+      valueArg.terminalAt === undefined
+      || !valueArg.error
+      || valueArg.error.retryable
+      || valueArg.nextAttemptAt !== undefined
+      || valueArg.deliveredAt !== undefined
+    ) {
+      fail(`${pathArg} terminal failure fields are inconsistent`);
+    }
+    return;
+  }
+  if (stateArg === 'delivered') {
+    if (
+      valueArg.terminalAt === undefined
+      || valueArg.deliveredAt !== valueArg.terminalAt
+      || valueArg.error !== undefined
+      || valueArg.nextAttemptAt !== undefined
+    ) {
+      fail(`${pathArg} delivered state fields are inconsistent`);
+    }
+    return;
+  }
+  if (
+    valueArg.error !== undefined
+    || valueArg.terminalAt !== undefined
+    || valueArg.deliveredAt !== undefined
+    || valueArg.nextAttemptAt !== undefined
+  ) {
+    fail(`${pathArg} state contains fields reserved for deferred or terminal outcomes`);
+  }
+};
+
+const submissionStates = new Set<ICoreMailSubmission['state']>([
+  'preparing',
+  'uploading',
+  'ready',
+  'accepted',
+  'queued',
+  'delivering',
+  'delivered',
+  'deferred',
+  'failed',
+  'deadLettered',
+]);
+
+export const normalizeCoreMailSubmission = (
+  valueArg: unknown,
+  pathArg = 'submission',
+): ICoreMailSubmission => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    [
+      'submissionId',
+      'idempotencyKey',
+      'submissionDigest',
+      'state',
+      'parts',
+      'attempts',
+      'createdAt',
+      'updatedAt',
+    ],
+    [
+      'transportMessageId',
+      'nextAttemptAt',
+      'error',
+      'acceptedAt',
+      'deliveredAt',
+      'terminalAt',
+    ],
+  );
+  if (typeof record.state !== 'string' || !submissionStates.has(record.state as ICoreMailSubmission['state'])) {
+    fail(`${pathArg}.state is invalid`);
+  }
+  const parts = readArray(
+    record.parts,
+    `${pathArg}.parts`,
+    coreMailLimits.attachmentCount + 2,
+  ).map((entryArg, indexArg) =>
+    normalizePartStatus(entryArg, `${pathArg}.parts[${indexArg}]`),
+  );
+  if (
+    parts.length === 0
+    || new Set(parts.map((entryArg) => entryArg.partId)).size !== parts.length
+  ) {
+    fail(`${pathArg}.parts must contain unique part identities`);
+  }
+  const normalized: ICoreMailSubmission = {
+    submissionId: requireIdentifier(record.submissionId, `${pathArg}.submissionId`),
+    idempotencyKey: requireString(record.idempotencyKey, `${pathArg}.idempotencyKey`, 256),
+    submissionDigest: normalizeCoreMailSha256(
+      record.submissionDigest,
+      `${pathArg}.submissionDigest`,
+    ),
+    state: record.state as ICoreMailSubmission['state'],
+    parts,
+    attempts: requireSafeInteger(record.attempts, `${pathArg}.attempts`, 0),
+    createdAt: requireSafeInteger(record.createdAt, `${pathArg}.createdAt`, 1),
+    updatedAt: requireSafeInteger(record.updatedAt, `${pathArg}.updatedAt`, 1),
+  };
+  for (const key of [
+    'nextAttemptAt',
+    'acceptedAt',
+    'deliveredAt',
+    'terminalAt',
+  ] as const) {
+    if (Object.hasOwn(record, key)) {
+      normalized[key] = requireSafeInteger(record[key], `${pathArg}.${key}`, 1);
+    }
+  }
+  if (Object.hasOwn(record, 'transportMessageId')) {
+    normalized.transportMessageId = requireIdentifier(
+      record.transportMessageId,
+      `${pathArg}.transportMessageId`,
+    );
+  }
+  if (Object.hasOwn(record, 'error')) {
+    normalized.error = normalizeCoreMailErrorData(record.error, `${pathArg}.error`);
+  }
+  assertOutboundStateFields(normalized.state, normalized, pathArg);
+  const hasTransportIdentity = normalized.transportMessageId !== undefined;
+  const hasAcceptedAt = normalized.acceptedAt !== undefined;
+  if (hasTransportIdentity !== hasAcceptedAt) {
+    fail(`${pathArg}.transportMessageId and acceptedAt must appear together`);
+  }
+  if (
+    normalized.state === 'accepted'
+    || normalized.state === 'queued'
+    || normalized.state === 'delivering'
+    || normalized.state === 'delivered'
+    || normalized.state === 'deferred'
+    || normalized.state === 'deadLettered'
+  ) {
+    if (!hasTransportIdentity) {
+      fail(`${pathArg} state requires transport acceptance fields`);
+    }
+  } else if (
+    (normalized.state === 'preparing'
+      || normalized.state === 'uploading'
+      || normalized.state === 'ready')
+    && hasTransportIdentity
+  ) {
+    fail(`${pathArg} state must not contain transport acceptance fields`);
+  }
+  if (
+    normalized.updatedAt < normalized.createdAt
+    || (
+      normalized.acceptedAt !== undefined
+      && (
+        normalized.acceptedAt < normalized.createdAt
+        || normalized.acceptedAt > normalized.updatedAt
+      )
+    )
+    || (
+      normalized.terminalAt !== undefined
+      && (
+        normalized.terminalAt < (normalized.acceptedAt || normalized.createdAt)
+        || normalized.terminalAt > normalized.updatedAt
+      )
+    )
+    || (
+      normalized.nextAttemptAt !== undefined
+      && normalized.nextAttemptAt < normalized.updatedAt
+    )
+  ) {
+    fail(`${pathArg} timestamps are not chronologically ordered`);
+  }
+  if (
+    (normalized.state === 'ready'
+      || normalized.state === 'accepted'
+      || normalized.state === 'queued'
+      || normalized.state === 'delivering'
+      || normalized.state === 'delivered'
+      || normalized.state === 'deferred'
+      || normalized.state === 'deadLettered'
+      || (normalized.state === 'failed' && hasTransportIdentity))
+    && normalized.parts.some((entryArg) => entryArg.state !== 'complete')
+  ) {
+    fail(`${pathArg} state requires every part to be complete`);
+  }
+  return deepFreezeValue(normalized);
+};
+
+export const normalizeCoreMailGatewayOutboundStatus = (
+  valueArg: unknown,
+  pathArg = 'gatewayStatus',
+): ICoreMailGatewayOutboundStatus => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    ['transportMessageId', 'state', 'attempts', 'updatedAt'],
+    ['nextAttemptAt', 'error', 'smtpCode', 'deliveredAt', 'terminalAt'],
+  );
+  if (
+    record.state !== 'accepted'
+    && record.state !== 'queued'
+    && record.state !== 'delivering'
+    && record.state !== 'delivered'
+    && record.state !== 'deferred'
+    && record.state !== 'failed'
+    && record.state !== 'deadLettered'
+  ) {
+    fail(`${pathArg}.state is invalid`);
+  }
+  const normalized: ICoreMailGatewayOutboundStatus = {
+    transportMessageId: requireIdentifier(
+      record.transportMessageId,
+      `${pathArg}.transportMessageId`,
+    ),
+    state: record.state as ICoreMailGatewayOutboundStatus['state'],
+    attempts: requireSafeInteger(record.attempts, `${pathArg}.attempts`, 0),
+    updatedAt: requireSafeInteger(record.updatedAt, `${pathArg}.updatedAt`, 1),
+  };
+  for (const key of ['nextAttemptAt', 'deliveredAt', 'terminalAt'] as const) {
+    if (Object.hasOwn(record, key)) {
+      normalized[key] = requireSafeInteger(record[key], `${pathArg}.${key}`, 1);
+    }
+  }
+  if (Object.hasOwn(record, 'smtpCode')) {
+    normalized.smtpCode = requireSafeInteger(record.smtpCode, `${pathArg}.smtpCode`, 100, 599);
+  }
+  if (Object.hasOwn(record, 'error')) {
+    normalized.error = normalizeCoreMailErrorData(record.error, `${pathArg}.error`);
+  }
+  assertOutboundStateFields(normalized.state, normalized, pathArg);
+  if (
+    (normalized.deliveredAt !== undefined && normalized.deliveredAt > normalized.updatedAt)
+    || (normalized.terminalAt !== undefined && normalized.terminalAt > normalized.updatedAt)
+    || (normalized.nextAttemptAt !== undefined && normalized.nextAttemptAt < normalized.updatedAt)
+  ) {
+    fail(`${pathArg} timestamps are not chronologically ordered`);
+  }
+  return deepFreezeValue(normalized);
+};
+
+export const normalizeCoreMailInboundDelivery = (
+  valueArg: unknown,
+  pathArg = 'inboundDelivery',
+): ICoreMailInboundDelivery => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    [
+      'deliveryId',
+      'transportDeliveryId',
+      'state',
+      'envelope',
+      'rawMime',
+      'receivedAt',
+      'updatedAt',
+    ],
+    ['messageId', 'subject', 'acknowledgedAt', 'acknowledgedOutcome'],
+  );
+  const state = record.state === 'pending'
+    || record.state === 'fetching'
+    || record.state === 'fetched'
+    || record.state === 'acknowledged'
+    ? record.state
+    : fail(`${pathArg}.state is invalid`);
+  const rawMime = readRecord(record.rawMime, `${pathArg}.rawMime`);
+  assertKeys(rawMime, `${pathArg}.rawMime`, ['sha256', 'lengthBytes', 'contentType']);
+  if (rawMime.contentType !== 'message/rfc822') {
+    fail(`${pathArg}.rawMime.contentType must be message/rfc822`);
+  }
+  const normalized: ICoreMailInboundDelivery = {
+    deliveryId: requireIdentifier(record.deliveryId, `${pathArg}.deliveryId`),
+    transportDeliveryId: requireIdentifier(
+      record.transportDeliveryId,
+      `${pathArg}.transportDeliveryId`,
+    ),
+    state,
+    envelope: normalizeCoreMailEnvelope(record.envelope, `${pathArg}.envelope`),
+    rawMime: {
+      sha256: normalizeCoreMailSha256(rawMime.sha256, `${pathArg}.rawMime.sha256`),
+      lengthBytes: requireSafeInteger(
+        rawMime.lengthBytes,
+        `${pathArg}.rawMime.lengthBytes`,
+        1,
+        coreMailLimits.serializedMimeBytes,
+      ),
+      contentType: 'message/rfc822',
+    },
+    receivedAt: requireSafeInteger(record.receivedAt, `${pathArg}.receivedAt`, 1),
+    updatedAt: requireSafeInteger(record.updatedAt, `${pathArg}.updatedAt`, 1),
+  };
+  if (Object.hasOwn(record, 'messageId')) {
+    normalized.messageId = requireDisplayText(record.messageId, `${pathArg}.messageId`, 998);
+  }
+  if (Object.hasOwn(record, 'subject')) {
+    normalized.subject = requireDisplayText(
+      record.subject,
+      `${pathArg}.subject`,
+      coreMailContractLimits.maximumSubjectBytes,
+      true,
+    );
+  }
+  if (state === 'acknowledged') {
+    if (
+      !Object.hasOwn(record, 'acknowledgedAt')
+      || (record.acknowledgedOutcome !== 'processed' && record.acknowledgedOutcome !== 'discarded')
+    ) {
+      fail(`${pathArg} acknowledged state fields are incomplete`);
+    }
+    normalized.acknowledgedAt = requireSafeInteger(
+      record.acknowledgedAt,
+      `${pathArg}.acknowledgedAt`,
+      1,
+    );
+    normalized.acknowledgedOutcome = record.acknowledgedOutcome as
+      ICoreMailInboundDelivery['acknowledgedOutcome'];
+  } else if (
+    Object.hasOwn(record, 'acknowledgedAt')
+    || Object.hasOwn(record, 'acknowledgedOutcome')
+  ) {
+    fail(`${pathArg} nonacknowledged state contains acknowledgement fields`);
+  }
+  if (
+    normalized.updatedAt < normalized.receivedAt
+    || (
+      normalized.acknowledgedAt !== undefined
+      && (
+        normalized.acknowledgedAt < normalized.receivedAt
+        || normalized.acknowledgedAt > normalized.updatedAt
+      )
+    )
+  ) {
+    fail(`${pathArg} timestamps are not chronologically ordered`);
+  }
+  return deepFreezeValue(normalized);
+};
+
+export const normalizeCoreMailInboundCursor = (
+  valueArg: unknown,
+  pathArg = 'inboundCursor',
+): string => {
+  const cursor = requireString(valueArg, pathArg, coreMailLimits.cursorBytes);
+  let decodedCursor: string;
+  try {
+    decodedCursor = globalThis.atob(
+      `${cursor.replace(/-/g, '+').replace(/_/g, '/')}${'='.repeat((4 - (cursor.length % 4)) % 4)}`,
+    );
+  } catch {
+    return fail(`${pathArg} must be a canonical opaque base64url value`);
+  }
+  const canonicalCursor = globalThis.btoa(decodedCursor)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/u, '');
+  if (
+    decodedCursor.length < coreMailLimits.cursorMinimumDecodedBytes
+    || canonicalCursor !== cursor
+  ) {
+    fail(`${pathArg} must be a canonical opaque base64url value`);
+  }
+  return cursor;
+};
+
+export const normalizeCoreMailInboundDeliveryPage = (
+  valueArg: unknown,
+  pathArg = 'inboundDeliveryPage',
+): ICoreMailInboundDeliveryPage => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(record, pathArg, ['deliveries'], ['nextCursor']);
+  const deliveries = readArray(
+    record.deliveries,
+    `${pathArg}.deliveries`,
+    coreMailLimits.inboundPageSize,
+  ).map((entryArg, indexArg) =>
+    normalizeCoreMailInboundDelivery(entryArg, `${pathArg}.deliveries[${indexArg}]`),
+  );
+  if (new Set(deliveries.map((entryArg) => entryArg.deliveryId)).size !== deliveries.length) {
+    fail(`${pathArg}.deliveries must contain unique delivery identities`);
+  }
+  const normalized: ICoreMailInboundDeliveryPage = { deliveries };
+  if (Object.hasOwn(record, 'nextCursor')) {
+    normalized.nextCursor = normalizeCoreMailInboundCursor(
+      record.nextCursor,
+      `${pathArg}.nextCursor`,
+    );
+  }
+  if (
+    new TextEncoder().encode(JSON.stringify(normalized)).byteLength
+    > coreMailLimits.inboundPageBytes
+  ) {
+    fail(`${pathArg} exceeds the inbound page byte budget`);
+  }
+  return deepFreezeValue(normalized);
+};
+
 const normalizeUniqueSortedStrings = (
   valueArg: unknown,
   pathArg: string,
@@ -381,21 +1394,21 @@ const normalizeLimits = (
   assertKeys(
     record,
     pathArg,
-    [],
     ['messagesPerMinute', 'messagesPerDay', 'maxPendingInbound'],
   );
-  if (Object.keys(record).length === 0) {
-    fail(`${pathArg} must not be empty`);
-  }
-  const normalized: NonNullable<ICoreMailBindingDesiredState['limits']> = {};
-  for (const key of [
-    'messagesPerMinute',
-    'messagesPerDay',
-    'maxPendingInbound',
-  ] as const) {
-    if (Object.hasOwn(record, key)) {
-      normalized[key] = requireSafeInteger(record[key], `${pathArg}.${key}`, 1);
-    }
+  const maxima = {
+    messagesPerMinute: coreMailContractLimits.maximumMessagesPerMinute,
+    messagesPerDay: coreMailContractLimits.maximumMessagesPerDay,
+    maxPendingInbound: coreMailContractLimits.maximumPendingInbound,
+  } as const;
+  const normalized = {} as ICoreMailBindingDesiredState['limits'];
+  for (const key of Object.keys(maxima) as Array<keyof typeof maxima>) {
+    normalized[key] = requireSafeInteger(
+      record[key],
+      `${pathArg}.${key}`,
+      1,
+      maxima[key],
+    );
   }
   return normalized;
 };
@@ -419,15 +1432,18 @@ const normalizeBinding = (
       'credentials',
       'allowedSenders',
       'inboundRecipients',
+      'limits',
     ],
-    ['defaultSender', 'limits'],
+    ['defaultSender'],
   );
-  if (record.schemaVersion !== 1) {
-    fail(`${pathArg}.schemaVersion must be 1`);
+  if (record.schemaVersion !== 2) {
+    fail(`${pathArg}.schemaVersion must be 2`);
   }
-  const state = record.state === 'active' || record.state === 'disabled'
+  const state = record.state === 'active'
+    || record.state === 'draining'
+    || record.state === 'disabled'
     ? record.state
-    : fail(`${pathArg}.state must be active or disabled`);
+    : fail(`${pathArg}.state must be active, draining, or disabled`);
   const capabilities = normalizeCapabilities(record.capabilities, `${pathArg}.capabilities`);
   const allowedSenders = normalizeUniqueSortedStrings(
     record.allowedSenders,
@@ -449,7 +1465,7 @@ const normalizeBinding = (
   }
 
   const normalized: ICoreMailBindingDesiredState = {
-    schemaVersion: 1,
+    schemaVersion: 2,
     bindingId: requireIdentifier(record.bindingId, `${pathArg}.bindingId`),
     serviceId: requireIdentifier(record.serviceId, `${pathArg}.serviceId`),
     tenantId: requireIdentifier(record.tenantId, `${pathArg}.tenantId`),
@@ -459,6 +1475,7 @@ const normalizeBinding = (
     credentials: normalizeCredentialSet(record.credentials, `${pathArg}.credentials`),
     allowedSenders,
     inboundRecipients,
+    limits: normalizeLimits(record.limits, `${pathArg}.limits`),
   };
   if (Object.hasOwn(record, 'defaultSender')) {
     normalized.defaultSender = requireCanonicalMailbox(
@@ -469,9 +1486,6 @@ const normalizeBinding = (
       fail(`${pathArg}.defaultSender must be present in allowedSenders`);
     }
   }
-  if (Object.hasOwn(record, 'limits')) {
-    normalized.limits = normalizeLimits(record.limits, `${pathArg}.limits`);
-  }
   return normalized;
 };
 
@@ -521,16 +1535,14 @@ const normalizeGateway = (
   assertKeys(
     record,
     pathArg,
-    ['endpointUrl', 'credentialId', 'credentialVersion', 'credentialSecretKey'],
-  );
-  const credentialSecretKey = requireString(
-    record.credentialSecretKey,
-    `${pathArg}.credentialSecretKey`,
-    coreMailContractLimits.maximumEnvironmentKeyBytes,
+    [
+      'endpointUrl',
+      'coreMailTransferOrigin',
+      'credentialId',
+      'credentialVersion',
+      'credentialSecretKey',
+    ],
   );
-  if (!/^[A-Z][A-Z0-9_]{0,127}$/.test(credentialSecretKey)) {
-    fail(`${pathArg}.credentialSecretKey must be a canonical environment key`);
-  }
   return {
     endpointUrl: requireCanonicalUrl(
       record.endpointUrl,
@@ -538,13 +1550,22 @@ const normalizeGateway = (
       'wss:',
       false,
     ),
+    coreMailTransferOrigin: requireCanonicalUrl(
+      record.coreMailTransferOrigin,
+      `${pathArg}.coreMailTransferOrigin`,
+      'https:',
+      true,
+    ),
     credentialId: requireIdentifier(record.credentialId, `${pathArg}.credentialId`),
     credentialVersion: requireSafeInteger(
       record.credentialVersion,
       `${pathArg}.credentialVersion`,
       1,
     ),
-    credentialSecretKey,
+    credentialSecretKey: requireEnvironmentKey(
+      record.credentialSecretKey,
+      `${pathArg}.credentialSecretKey`,
+    ),
   };
 };
 
@@ -552,9 +1573,13 @@ export const normalizeCoreMailDesiredState = (
   valueArg: unknown,
 ): ICoreMailDesiredState => {
   const record = readRecord(valueArg, 'desiredState');
-  assertKeys(record, 'desiredState', ['schemaVersion', 'configEpoch', 'bindings', 'gateway']);
-  if (record.schemaVersion !== 1) {
-    fail('desiredState.schemaVersion must be 1');
+  assertKeys(
+    record,
+    'desiredState',
+    ['schemaVersion', 'configEpoch', 'bindings', 'gateway', 'cursorKeys'],
+  );
+  if (record.schemaVersion !== 2) {
+    fail('desiredState.schemaVersion must be 2');
   }
   const bindings = readArray(
     record.bindings,
@@ -583,11 +1608,160 @@ export const normalizeCoreMailDesiredState = (
     compareStrings(leftArg.bindingId, rightArg.bindingId),
   );
   return deepFreezeValue({
-    schemaVersion: 1,
+    schemaVersion: 2,
     configEpoch: requireSafeInteger(record.configEpoch, 'desiredState.configEpoch', 1),
     bindings,
     gateway: normalizeGateway(record.gateway, 'desiredState.gateway'),
+    cursorKeys: normalizeRuntimeKeySet(record.cursorKeys, 'desiredState.cursorKeys'),
+  });
+};
+
+export const normalizeCoreMailReplicaIdentity = (
+  valueArg: unknown,
+  pathArg = 'replica',
+): ICoreMailReplicaIdentity => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    ['taskId', 'serviceId', 'rolloutId', 'rolloutGeneration', 'imageDigest'],
+  );
+  return deepFreezeValue({
+    taskId: requireIdentifier(record.taskId, `${pathArg}.taskId`),
+    serviceId: requireIdentifier(record.serviceId, `${pathArg}.serviceId`),
+    rolloutId: requireIdentifier(record.rolloutId, `${pathArg}.rolloutId`),
+    rolloutGeneration: requireSafeInteger(
+      record.rolloutGeneration,
+      `${pathArg}.rolloutGeneration`,
+      1,
+    ),
+    imageDigest: normalizeCoreMailSha256(record.imageDigest, `${pathArg}.imageDigest`),
+  });
+};
+
+const normalizeBindingReconciliationStatus = (
+  valueArg: unknown,
+  pathArg: string,
+): ICoreMailBindingReconciliationStatus => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    [
+      'bindingId',
+      'revision',
+      'state',
+      'pendingInboundCount',
+      'activeSessionsByCredential',
+    ],
+  );
+  const state = record.state === 'active'
+    || record.state === 'draining'
+    || record.state === 'disabled'
+    ? record.state
+    : fail(`${pathArg}.state must be active, draining, or disabled`);
+  const activeSessionsByCredential = readArray(
+    record.activeSessionsByCredential,
+    `${pathArg}.activeSessionsByCredential`,
+    coreMailContractLimits.maximumCredentialsPerAuthority,
+  ).map((entryArg, indexArg) => {
+    const entryPath = `${pathArg}.activeSessionsByCredential[${indexArg}]`;
+    const entry = readRecord(entryArg, entryPath);
+    assertKeys(entry, entryPath, ['credentialId', 'version', 'count']);
+    return {
+      credentialId: requireIdentifier(entry.credentialId, `${entryPath}.credentialId`),
+      version: requireSafeInteger(entry.version, `${entryPath}.version`, 1),
+      count: requireSafeInteger(entry.count, `${entryPath}.count`, 1),
+    };
   });
+  if (
+    new Set(activeSessionsByCredential.map((entryArg) =>
+      `${entryArg.credentialId}:${entryArg.version}`
+    )).size !== activeSessionsByCredential.length
+  ) {
+    fail(`${pathArg}.activeSessionsByCredential contains duplicate identities`);
+  }
+  activeSessionsByCredential.sort((leftArg, rightArg) =>
+    leftArg.version - rightArg.version
+    || compareStrings(leftArg.credentialId, rightArg.credentialId),
+  );
+  return {
+    bindingId: requireIdentifier(record.bindingId, `${pathArg}.bindingId`),
+    revision: requireSafeInteger(record.revision, `${pathArg}.revision`, 1),
+    state,
+    pendingInboundCount: requireSafeInteger(
+      record.pendingInboundCount,
+      `${pathArg}.pendingInboundCount`,
+      0,
+      coreMailContractLimits.maximumPendingInbound,
+    ),
+    activeSessionsByCredential,
+  };
+};
+
+export const normalizeCoreMailReconciliationStatus = (
+  valueArg: unknown,
+  pathArg = 'reconciliationStatus',
+): ICoreMailReconciliationStatus => {
+  const record = readRecord(valueArg, pathArg);
+  assertKeys(
+    record,
+    pathArg,
+    [
+      'replica',
+      'state',
+      'appliedConfigEpoch',
+      'appliedDesiredStateDigest',
+      'bindings',
+      'updatedAt',
+    ],
+    ['errorCode'],
+  );
+  const state = record.state === 'applying'
+    || record.state === 'ready'
+    || record.state === 'failed'
+    ? record.state
+    : fail(`${pathArg}.state must be applying, ready, or failed`);
+  const bindings = readArray(
+    record.bindings,
+    `${pathArg}.bindings`,
+    coreMailContractLimits.maximumBindings,
+  ).map((entryArg, indexArg) =>
+    normalizeBindingReconciliationStatus(entryArg, `${pathArg}.bindings[${indexArg}]`),
+  );
+  if (new Set(bindings.map((entryArg) => entryArg.bindingId)).size !== bindings.length) {
+    fail(`${pathArg}.bindings contains duplicate binding identities`);
+  }
+  bindings.sort((leftArg, rightArg) => compareStrings(leftArg.bindingId, rightArg.bindingId));
+  const hasErrorCode = Object.hasOwn(record, 'errorCode');
+  if ((state === 'failed') !== hasErrorCode) {
+    fail(`${pathArg}.errorCode must appear exactly for failed state`);
+  }
+  const normalized: ICoreMailReconciliationStatus = {
+    replica: normalizeCoreMailReplicaIdentity(record.replica, `${pathArg}.replica`),
+    state,
+    appliedConfigEpoch: requireSafeInteger(
+      record.appliedConfigEpoch,
+      `${pathArg}.appliedConfigEpoch`,
+      1,
+    ),
+    appliedDesiredStateDigest: normalizeCoreMailSha256(
+      record.appliedDesiredStateDigest,
+      `${pathArg}.appliedDesiredStateDigest`,
+    ),
+    bindings,
+    updatedAt: requireSafeInteger(record.updatedAt, `${pathArg}.updatedAt`, 1),
+  };
+  if (hasErrorCode) {
+    if (
+      typeof record.errorCode !== 'string'
+      || !coreMailErrorCodes.has(record.errorCode as TCoreMailErrorCode)
+    ) {
+      fail(`${pathArg}.errorCode is invalid`);
+    }
+    normalized.errorCode = record.errorCode as TCoreMailErrorCode;
+  }
+  return deepFreezeValue(normalized);
 };
 
 export const canonicalizeCoreMailDesiredState = (