@serve.zone/interfaces 23.2.0 → 24.0.0

package/readme.md

@@ -30,13 +30,14 @@ import { appstore, data, platform, platformservice, requests } from '@serve.zone
 
 This package intentionally has no service implementation logic. It is a stable vocabulary for services that need to agree on payload shape, method names, and response types.
 
-## Secrets v23 Pre-Cutover Contract
+## Secrets v24 Pre-Cutover Contract
 
-Version 23 removes the old grouped/bundled secret DTOs and plaintext runtime
-material API. Secret values enter Cloudly only as strict SmartCrypto X25519
-envelopes or an explicit bounded server-generation request. Coreflow receives a
-full digest-verified schema-v2 manifest plus one sealed envelope per pinned
-SecretVersion through the Node-only runtime export.
+Version 24 retains the value-free v23 architecture while replacing the remaining
+pre-cutover lifecycle and runtime authority gaps. Secret values enter Cloudly
+only as strict SmartCrypto X25519 envelopes or an explicit bounded
+server-generation request. Coreflow receives a full digest-verified schema-v2
+manifest plus one sealed envelope per pinned SecretVersion through the Node-only
+runtime export.
 
 This is a contract release before consumer cutover. It does **not** claim that
 clean-v2 migration, backup verification, historical secret erasure, or storage
@@ -53,12 +54,24 @@ Breaking removals include:
   credential references.
 - Hosted-app control-token identities and credential-bearing bootstrap actions.
 
-Primary v23 additions include:
+The current secret contract includes:
 
-- `TSecretValueInput`, `TSecretIngressRecipient`, the
+- `TSecretValueInput`, active-only `IActiveSecretRecipientMetadata`, the
   `requests.secret.IReq_GetSecretIngressRecipient` contract with method
   `getSecretIngressRecipient`, and fixed-order create/rotate/App Store context
   builders.
+- `ISecretEnvelopeAdmissionBindingV1` under the Node-only runtime export binds
+  an exact envelope and request context to one recipient generation. The
+  binding is reproducible and does not itself prove admission. Retiring-key
+  retries require a trusted Cloudly mutation receipt created atomically while
+  that recipient was active; caller-supplied admission or issuance timestamps
+  are not part of the contract.
+- `getSecretVersionPurgePreflight` returns bounded advisory reference pages and
+  complete blocker counts. `purgeSecretVersion` identifies one exact version
+  and fences the mutation by secret, version, and target revisions. The
+  non-issuable `purge-pending` lifecycle and revisioned
+  `pending`/`erasing`/`failed`/`succeeded` operation keep external erasure
+  durable across retries without treating preflight as authorization.
 - Schema-v2 `IResolvedSecretManifest` contracts, stable Docker resource naming,
   WorkloadInit map/wrapper helpers, and `ISealedResolvedSecretMaterial` under
   `@serve.zone/interfaces/runtime`.
@@ -67,7 +80,7 @@ Primary v23 additions include:
 - Mandatory `IImmutableContainerInvocationV1` evidence on immutable image
   deployment plans.
 
-### Secrets v23.1 Runtime Registration And Reporting
+### Secrets v24 Runtime Registration And Reporting
 
 The Node-only `@serve.zone/interfaces/runtime` export adds the live contract
 that Cloudly must validate before publishing secret-bearing desired state to a
@@ -76,17 +89,30 @@ Coreflow connection:
 - `getSecretRecipientEnrollmentState` returns either an exact generation-zero
   empty state or the complete valid recipient set for the cluster derived from
   the verified JWT.
-- `getCoreflowSecretRuntimeRegistrationExpectation` returns the authoritative
-  live reporter session, target-node set, active recipient, and approved
-  WorkloadInit artifacts for the cluster derived from the verified JWT.
+- `getCoreflowSecretRuntimeRegistrationExpectation` returns either an
+  `available` v2 expectation or an explicit unavailable reason. The available
+  expectation binds the live reporter session, active recipient, fresh
+  generation-fenced target authority, and active WorkloadInit approval through
+  `expectationDigest`.
+- Spark sends authenticated, sequenced local Swarm membership observations and,
+  on managers, complete manager snapshots. Cloudly derives scope from the Spark
+  credential, reconciles manager consensus privately, and publishes one fresh
+  single-Swarm target authority or a targetless unavailable state. Structural
+  contract validation does not itself establish manager consensus.
+- WorkloadInit approval binds a clean stable release identity, version-tagged
+  OCI index, exact amd64 and arm64 platform/executable digests, policy
+  generation, and a Cloudly summary of detached Cosign DSSE/SLSA verification.
+  Public shape and digest validators do not verify the signature, public-key
+  trust root, or private Cloudly policy.
 - `coreflowSecretRuntimeRegistrationTagId` is the sole dedicated TypedSocket
   tag identifier. Its payload is exactly
-  `ICoreflowSecretRuntimeRegistrationV1`; cluster scope comes from the verified
+  `ICoreflowSecretRuntimeRegistrationV2`; cluster scope comes from the verified
   connection identity rather than the tag.
-- `ICoreflowSecretRuntimeRegistrationV1` binds a reporter session to the exact
-  authoritative schedulable target-node set, required secret capabilities,
-  active recipient, approved WorkloadInit OCI index, and exact per-platform
-  manifest and installed-executable digests.
+- `ICoreflowSecretRuntimeRegistrationV2` references the exact expectation,
+  target generation/digest, and WorkloadInit authority. It must cover every
+  Cloudly-node/Swarm-cluster/Swarm-node identity and approved per-platform
+  manifest and installed-executable digest without self-asserting placement or
+  approval.
 - `validateCoreflowSecretRuntimeRegistration` compares the registration with a
   trusted expectation built by Cloudly, including the live reporter session.
   Missing, extra, duplicate, reordered, or mismatched node evidence fails
@@ -410,6 +436,8 @@ Common data contracts include:
   aggregate owner fence, while
   `setServiceSecretSetAttachments` returns the independent
   `secretConfigurationRevision`. Generic service writes own neither revision.
+  Purge is a separate exact-version mutation with its own version revision and
+  durable operation; it is not a logical-secret lifecycle action.
 - Mail gateway contracts for domain authorities, address bindings, WorkApp bindings, managed SMTP/API credentials, spool items, delivery journals, and inbound/outbound message payloads.
 - Service-level mail configuration through `IService.data.mail`, including per-address inbound `smtpForward` settings and outbound credential metadata. Cloudly settings include dcrouter gateway, SMTP submission, and inbound forward-target keys for reconciling those bindings.
 - Web Push contracts for environment-specific service bindings, public credential state, public VAPID key rotation metadata, privacy-minimal notification signals, and redacted delivery state. Subscription endpoints, browser key material, provider ciphertext, VAPID private keys, and credential secrets are intentionally absent from public binding and status DTOs.

package/ts/00_commitinfo_data.ts

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

package/ts/appstore/types.ts

@@ -5,7 +5,7 @@ import {
   validateSecretValueInputForRecipient,
   type TSecretDelivery,
   type TSecretGeneratedEncoding,
-  type TSecretIngressRecipient,
+  type IActiveSecretRecipientMetadata,
   type TSecretValueInput,
 } from '../data/secret.js';
 import {
@@ -511,7 +511,7 @@ export const validateAppStoreEnvironmentDeclarations = (
 export const validateAppStoreInstallRequest = async (
   requestArg: unknown,
   configArg: IAppStoreVersionConfig,
-  activeIngressRecipientArg: TSecretIngressRecipient,
+  activeIngressRecipientArg: IActiveSecretRecipientMetadata,
 ): Promise<string[]> => {
   if (!requestArg || typeof requestArg !== 'object' || Array.isArray(requestArg)) {
     return ['install request must be an object'];

package/ts/data/clusternode.ts

@@ -1,4 +1,5 @@
 import * as plugins from '../plugins.js';
+import type { TSha256Digest, TImmutableContainerPlatform } from './immutableimage.js';
 
 export interface IClusterNodeMetrics {
   cpuUsagePercent: number;
@@ -91,6 +92,518 @@ export interface ISparkActionResultResponse {
   message?: string;
 }
 
+export interface ISwarmManagerObservedNodeV1 {
+  swarmNodeId: string;
+  nodeName: string;
+  platform: TImmutableContainerPlatform;
+  role: 'manager' | 'worker';
+  availability: 'active' | 'pause' | 'drain';
+  state: 'unknown' | 'down' | 'ready' | 'disconnected';
+  managerStatus?: {
+    leader: boolean;
+    reachability: 'unknown' | 'unreachable' | 'reachable';
+  };
+}
+
+export interface ISwarmManagerSnapshotV1 {
+  snapshotVersion: 1;
+  snapshotDigest: TSha256Digest;
+  nodeCount: number;
+  managerCount: number;
+  nodes: ISwarmManagerObservedNodeV1[];
+}
+
+interface ISparkSwarmObservationBaseV1 {
+  schemaVersion: 1;
+  reporterSessionId: string;
+  observationSequence: number;
+  observedAt: number;
+}
+
+export type TSparkSwarmObservationV1 =
+  | (ISparkSwarmObservationBaseV1 & {
+      state: 'unknown';
+      reason: 'docker-unavailable' | 'query-failed' | 'not-initialized';
+    })
+  | (ISparkSwarmObservationBaseV1 & {
+      state: 'not-member';
+    })
+  | (ISparkSwarmObservationBaseV1 & {
+      state: 'member';
+      swarmClusterId: string;
+      localSwarmNodeId: string;
+      controlAvailable: boolean;
+      managerSnapshot?: ISwarmManagerSnapshotV1;
+    });
+
+/** Cloudly derives node and cluster scope from this authenticated Spark request. */
+export interface ISparkSwarmObservationRequest {
+  nodeId: string;
+  nodeToken: string;
+  observation: TSparkSwarmObservationV1;
+}
+
+export interface ISparkSwarmObservationResponse {
+  accepted: boolean;
+  acceptedSequence?: number;
+  targetGeneration?: number;
+  message?: string;
+}
+
+export interface IClusterRuntimeTargetV1 {
+  cloudlyNodeId: string;
+  swarmClusterId: string;
+  swarmNodeId: string;
+  nodeName: string;
+  platform: TImmutableContainerPlatform;
+}
+
+export interface IClusterRuntimeTargetSetReadyV1 {
+  schemaVersion: 1;
+  state: 'ready';
+  cloudlyClusterId: string;
+  swarmClusterId: string;
+  generation: number;
+  targetSetDigest: TSha256Digest;
+  acceptedAt: number;
+  freshUntil: number;
+  targets: IClusterRuntimeTargetV1[];
+}
+
+export interface IClusterRuntimeTargetSetUnavailableV1 {
+  schemaVersion: 1;
+  state: 'unavailable';
+  cloudlyClusterId: string;
+  generation: number;
+  changedAt: number;
+  reason:
+    | 'never-observed'
+    | 'stale'
+    | 'no-manager-consensus'
+    | 'identity-conflict'
+    | 'no-schedulable-targets';
+}
+
+export type TClusterRuntimeTargetSetV1 =
+  | IClusterRuntimeTargetSetReadyV1
+  | IClusterRuntimeTargetSetUnavailableV1;
+
+const runtimeIdentifierRegex = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
+const runtimeDigestRegex = /^sha256:[a-f0-9]{64}$/;
+const runtimePlatforms = new Set<TImmutableContainerPlatform>([
+  'linux/amd64',
+  'linux/arm64',
+]);
+const maximumSwarmNodes = 1024;
+
+const isRuntimeRecord = (valueArg: unknown): valueArg is Record<string, unknown> => (
+  Boolean(valueArg) && typeof valueArg === 'object' && !Array.isArray(valueArg)
+);
+
+const hasExactRuntimeKeys = (
+  valueArg: Record<string, unknown>,
+  keysArg: string[],
+): boolean => JSON.stringify(Object.keys(valueArg).sort()) === JSON.stringify([...keysArg].sort());
+
+const isRuntimeIdentifier = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string' && runtimeIdentifierRegex.test(valueArg)
+);
+
+const isPositiveSafeInteger = (valueArg: unknown): valueArg is number => (
+  Number.isSafeInteger(valueArg) && (valueArg as number) > 0
+);
+
+const computeSha256 = async (inputArg: string): Promise<TSha256Digest> => {
+  const digest = new Uint8Array(await globalThis.crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(inputArg),
+  ));
+  return `sha256:${[...digest]
+    .map((byteArg) => byteArg.toString(16).padStart(2, '0'))
+    .join('')}` as TSha256Digest;
+};
+
+const canonicalSwarmNode = (
+  nodeArg: ISwarmManagerObservedNodeV1,
+): Record<string, unknown> => ({
+  swarmNodeId: nodeArg.swarmNodeId,
+  nodeName: nodeArg.nodeName,
+  platform: nodeArg.platform,
+  role: nodeArg.role,
+  availability: nodeArg.availability,
+  state: nodeArg.state,
+  managerStatus: nodeArg.managerStatus
+    ? {
+        leader: nodeArg.managerStatus.leader,
+        reachability: nodeArg.managerStatus.reachability,
+      }
+    : null,
+});
+
+export const createSwarmManagerSnapshotDigestInput = (
+  swarmClusterIdArg: string,
+  snapshotArg: ISwarmManagerSnapshotV1,
+): string => JSON.stringify({
+  schemaVersion: 1,
+  purpose: 'serve.zone/swarm-manager-snapshot',
+  swarmClusterId: swarmClusterIdArg,
+  snapshotVersion: snapshotArg.snapshotVersion,
+  nodeCount: snapshotArg.nodeCount,
+  managerCount: snapshotArg.managerCount,
+  nodes: snapshotArg.nodes.map(canonicalSwarmNode),
+});
+
+export const computeSwarmManagerSnapshotDigest = async (
+  swarmClusterIdArg: string,
+  snapshotArg: ISwarmManagerSnapshotV1,
+): Promise<TSha256Digest> => computeSha256(
+  createSwarmManagerSnapshotDigestInput(swarmClusterIdArg, snapshotArg),
+);
+
+const validateSwarmManagerSnapshot = async (
+  swarmClusterIdArg: string,
+  localSwarmNodeIdArg: string,
+  snapshotArg: unknown,
+): Promise<string[]> => {
+  if (!isRuntimeRecord(snapshotArg)
+    || !hasExactRuntimeKeys(snapshotArg, [
+      'snapshotVersion',
+      'snapshotDigest',
+      'nodeCount',
+      'managerCount',
+      'nodes',
+    ])) {
+    return ['Spark Swarm manager snapshot must use its exact schema'];
+  }
+  const errors: string[] = [];
+  if (snapshotArg.snapshotVersion !== 1) {
+    errors.push('Spark Swarm manager snapshotVersion must be 1');
+  }
+  if (typeof snapshotArg.snapshotDigest !== 'string'
+    || !runtimeDigestRegex.test(snapshotArg.snapshotDigest)) {
+    errors.push('Spark Swarm manager snapshot digest must be canonical');
+  }
+  if (!Array.isArray(snapshotArg.nodes)
+    || snapshotArg.nodes.length === 0
+    || snapshotArg.nodes.length > maximumSwarmNodes) {
+    errors.push('Spark Swarm manager snapshot nodes must be a non-empty bounded array');
+    return errors;
+  }
+  if (snapshotArg.nodeCount !== snapshotArg.nodes.length
+    || !isPositiveSafeInteger(snapshotArg.nodeCount)) {
+    errors.push('Spark Swarm manager snapshot nodeCount must match nodes');
+  }
+  const nodeIds = new Set<string>();
+  const nodeNames = new Set<string>();
+  let managerCount = 0;
+  let leaderCount = 0;
+  let previousSortKey: string | undefined;
+  for (const [index, nodeArg] of snapshotArg.nodes.entries()) {
+    if (!isRuntimeRecord(nodeArg)) {
+      errors.push(`Spark Swarm manager snapshot nodes[${index}] must be an object`);
+      continue;
+    }
+    const isManager = nodeArg.role === 'manager';
+    const expectedKeys = [
+      'swarmNodeId',
+      'nodeName',
+      'platform',
+      'role',
+      'availability',
+      'state',
+      ...(isManager ? ['managerStatus'] : []),
+    ];
+    if (!hasExactRuntimeKeys(nodeArg, expectedKeys)) {
+      errors.push(`Spark Swarm manager snapshot nodes[${index}] must use its exact role schema`);
+    }
+    if (!isRuntimeIdentifier(nodeArg.swarmNodeId) || !isRuntimeIdentifier(nodeArg.nodeName)) {
+      errors.push(`Spark Swarm manager snapshot nodes[${index}] identity must be canonical`);
+    }
+    if (!runtimePlatforms.has(nodeArg.platform as TImmutableContainerPlatform)) {
+      errors.push(`Spark Swarm manager snapshot nodes[${index}] platform must be supported`);
+    }
+    if (!['manager', 'worker'].includes(nodeArg.role as string)
+      || !['active', 'pause', 'drain'].includes(nodeArg.availability as string)
+      || !['unknown', 'down', 'ready', 'disconnected'].includes(nodeArg.state as string)) {
+      errors.push(`Spark Swarm manager snapshot nodes[${index}] scheduler state must be canonical`);
+    }
+    if (isManager) {
+      managerCount++;
+      if (!isRuntimeRecord(nodeArg.managerStatus)
+        || !hasExactRuntimeKeys(nodeArg.managerStatus, ['leader', 'reachability'])
+        || typeof nodeArg.managerStatus.leader !== 'boolean'
+        || !['unknown', 'unreachable', 'reachable']
+          .includes(nodeArg.managerStatus.reachability as string)) {
+        errors.push(`Spark Swarm manager snapshot nodes[${index}] managerStatus must be canonical`);
+      } else if (nodeArg.managerStatus.leader) {
+        leaderCount++;
+      }
+    }
+    if (isRuntimeIdentifier(nodeArg.swarmNodeId)) {
+      if (nodeIds.has(nodeArg.swarmNodeId)) {
+        errors.push('Spark Swarm manager snapshot node IDs must be unique');
+      }
+      nodeIds.add(nodeArg.swarmNodeId);
+    }
+    if (isRuntimeIdentifier(nodeArg.nodeName)) {
+      if (nodeNames.has(nodeArg.nodeName)) {
+        errors.push('Spark Swarm manager snapshot node names must be unique');
+      }
+      nodeNames.add(nodeArg.nodeName);
+    }
+    if (isRuntimeIdentifier(nodeArg.swarmNodeId) && isRuntimeIdentifier(nodeArg.nodeName)) {
+      const sortKey = `${nodeArg.swarmNodeId}\0${nodeArg.nodeName}\0${nodeArg.platform}`;
+      if (previousSortKey !== undefined && sortKey <= previousSortKey) {
+        errors.push('Spark Swarm manager snapshot nodes must be uniquely sorted');
+      }
+      previousSortKey = sortKey;
+    }
+  }
+  if (snapshotArg.managerCount !== managerCount || !isPositiveSafeInteger(snapshotArg.managerCount)) {
+    errors.push('Spark Swarm manager snapshot managerCount must match nodes');
+  }
+  if (leaderCount > 1) errors.push('Spark Swarm manager snapshot may contain at most one leader');
+  const sourceNode = snapshotArg.nodes.find((nodeArg) => (
+    isRuntimeRecord(nodeArg) && nodeArg.swarmNodeId === localSwarmNodeIdArg
+  ));
+  if (!isRuntimeRecord(sourceNode)
+    || sourceNode.role !== 'manager'
+    || sourceNode.availability !== 'active'
+    || sourceNode.state !== 'ready'
+    || !isRuntimeRecord(sourceNode.managerStatus)
+    || sourceNode.managerStatus.reachability !== 'reachable') {
+    errors.push('Spark Swarm manager snapshot source must be an active reachable manager');
+  }
+  if (errors.length === 0
+    && snapshotArg.snapshotDigest !== await computeSwarmManagerSnapshotDigest(
+      swarmClusterIdArg,
+      snapshotArg as unknown as ISwarmManagerSnapshotV1,
+    )) {
+    errors.push('Spark Swarm manager snapshot digest does not match');
+  }
+  return errors;
+};
+
+export const validateSparkSwarmObservation = async (
+  observationArg: unknown,
+): Promise<string[]> => {
+  try {
+    if (!isRuntimeRecord(observationArg)) return ['Spark Swarm observation must be an object'];
+    const observation = observationArg as Record<string, unknown>;
+    const commonKeys = [
+      'schemaVersion',
+      'reporterSessionId',
+      'observationSequence',
+      'observedAt',
+      'state',
+    ];
+    const expectedKeys = observation.state === 'unknown'
+      ? [...commonKeys, 'reason']
+      : observation.state === 'not-member'
+        ? commonKeys
+        : observation.state === 'member'
+          ? [
+              ...commonKeys,
+              'swarmClusterId',
+              'localSwarmNodeId',
+              'controlAvailable',
+              ...(observation.managerSnapshot === undefined ? [] : ['managerSnapshot']),
+            ]
+          : [];
+    if (expectedKeys.length === 0 || !hasExactRuntimeKeys(observation, expectedKeys)) {
+      return ['Spark Swarm observation must use its exact state schema'];
+    }
+    const errors: string[] = [];
+    if (observation.schemaVersion !== 1) errors.push('Spark Swarm observation schemaVersion must be 1');
+    if (!isRuntimeIdentifier(observation.reporterSessionId)
+      || !isPositiveSafeInteger(observation.observationSequence)
+      || !isPositiveSafeInteger(observation.observedAt)) {
+      errors.push('Spark Swarm observation identity, sequence, and timestamp must be canonical');
+    }
+    if (observation.state === 'unknown'
+      && !['docker-unavailable', 'query-failed', 'not-initialized']
+        .includes(observation.reason as string)) {
+      errors.push('Spark Swarm observation unknown reason must be canonical');
+    }
+    if (observation.state === 'member') {
+      if (!isRuntimeIdentifier(observation.swarmClusterId)
+        || !isRuntimeIdentifier(observation.localSwarmNodeId)
+        || typeof observation.controlAvailable !== 'boolean') {
+        errors.push('Spark Swarm member observation must have canonical local authority');
+      }
+      if (observation.managerSnapshot !== undefined) {
+        if (observation.controlAvailable !== true) {
+          errors.push('Spark Swarm manager snapshot requires controlAvailable');
+        } else if (isRuntimeIdentifier(observation.swarmClusterId)
+          && isRuntimeIdentifier(observation.localSwarmNodeId)) {
+          errors.push(...await validateSwarmManagerSnapshot(
+            observation.swarmClusterId,
+            observation.localSwarmNodeId,
+            observation.managerSnapshot,
+          ));
+        }
+      }
+    }
+    return errors;
+  } catch {
+    return ['Spark Swarm observation must be safely inspectable'];
+  }
+};
+
+const canonicalRuntimeTarget = (
+  targetArg: IClusterRuntimeTargetV1,
+): IClusterRuntimeTargetV1 => ({
+  cloudlyNodeId: targetArg.cloudlyNodeId,
+  swarmClusterId: targetArg.swarmClusterId,
+  swarmNodeId: targetArg.swarmNodeId,
+  nodeName: targetArg.nodeName,
+  platform: targetArg.platform,
+});
+
+export const createClusterRuntimeTargetSetDigestInput = (
+  targetSetArg: IClusterRuntimeTargetSetReadyV1,
+): string => JSON.stringify({
+  schemaVersion: targetSetArg.schemaVersion,
+  purpose: 'serve.zone/cluster-runtime-target-set',
+  cloudlyClusterId: targetSetArg.cloudlyClusterId,
+  swarmClusterId: targetSetArg.swarmClusterId,
+  generation: targetSetArg.generation,
+  targets: targetSetArg.targets.map(canonicalRuntimeTarget),
+});
+
+export const computeClusterRuntimeTargetSetDigest = async (
+  targetSetArg: IClusterRuntimeTargetSetReadyV1,
+): Promise<TSha256Digest> => computeSha256(createClusterRuntimeTargetSetDigestInput(targetSetArg));
+
+export const validateClusterRuntimeTargetSet = async (
+  targetSetArg: unknown,
+): Promise<string[]> => {
+  try {
+    if (!isRuntimeRecord(targetSetArg)) return ['cluster runtime target set must be an object'];
+    if (targetSetArg.state === 'unavailable') {
+      if (!hasExactRuntimeKeys(targetSetArg, [
+        'schemaVersion',
+        'state',
+        'cloudlyClusterId',
+        'generation',
+        'changedAt',
+        'reason',
+      ])) {
+        return ['unavailable cluster runtime target set must use its exact schema'];
+      }
+      const errors: string[] = [];
+      if (targetSetArg.schemaVersion !== 1
+        || !isRuntimeIdentifier(targetSetArg.cloudlyClusterId)
+        || !Number.isSafeInteger(targetSetArg.generation)
+        || (targetSetArg.generation as number) < 0
+        || !isPositiveSafeInteger(targetSetArg.changedAt)
+        || ![
+          'never-observed',
+          'stale',
+          'no-manager-consensus',
+          'identity-conflict',
+          'no-schedulable-targets',
+        ].includes(targetSetArg.reason as string)) {
+        errors.push('unavailable cluster runtime target set fields must be canonical');
+      }
+      if (targetSetArg.reason === 'never-observed' && targetSetArg.generation !== 0) {
+        errors.push('never-observed target state must use generation zero');
+      }
+      return errors;
+    }
+    if (targetSetArg.state !== 'ready'
+      || !hasExactRuntimeKeys(targetSetArg, [
+        'schemaVersion',
+        'state',
+        'cloudlyClusterId',
+        'swarmClusterId',
+        'generation',
+        'targetSetDigest',
+        'acceptedAt',
+        'freshUntil',
+        'targets',
+      ])) {
+      return ['ready cluster runtime target set must use its exact schema'];
+    }
+    const errors: string[] = [];
+    if (targetSetArg.schemaVersion !== 1
+      || !isRuntimeIdentifier(targetSetArg.cloudlyClusterId)
+      || !isRuntimeIdentifier(targetSetArg.swarmClusterId)
+      || !isPositiveSafeInteger(targetSetArg.generation)
+      || !isPositiveSafeInteger(targetSetArg.acceptedAt)
+      || !isPositiveSafeInteger(targetSetArg.freshUntil)
+      || (targetSetArg.freshUntil as number) <= (targetSetArg.acceptedAt as number)
+      || typeof targetSetArg.targetSetDigest !== 'string'
+      || !runtimeDigestRegex.test(targetSetArg.targetSetDigest)) {
+      errors.push('ready cluster runtime target set authority fields must be canonical');
+    }
+    if (!Array.isArray(targetSetArg.targets)
+      || targetSetArg.targets.length === 0
+      || targetSetArg.targets.length > maximumSwarmNodes) {
+      errors.push('ready cluster runtime target set targets must be a non-empty bounded array');
+      return errors;
+    }
+    const cloudlyNodeIds = new Set<string>();
+    const swarmNodeScopes = new Set<string>();
+    const nodeNames = new Set<string>();
+    let previousSortKey: string | undefined;
+    for (const [index, targetArg] of targetSetArg.targets.entries()) {
+      if (!isRuntimeRecord(targetArg)
+        || !hasExactRuntimeKeys(targetArg, [
+          'cloudlyNodeId',
+          'swarmClusterId',
+          'swarmNodeId',
+          'nodeName',
+          'platform',
+        ])
+        || !isRuntimeIdentifier(targetArg.cloudlyNodeId)
+        || !isRuntimeIdentifier(targetArg.swarmClusterId)
+        || !isRuntimeIdentifier(targetArg.swarmNodeId)
+        || !isRuntimeIdentifier(targetArg.nodeName)
+        || targetArg.swarmClusterId !== targetSetArg.swarmClusterId
+        || !runtimePlatforms.has(targetArg.platform as TImmutableContainerPlatform)) {
+        errors.push(`cluster runtime target set targets[${index}] must be canonical`);
+        continue;
+      }
+      const sortKey = `${targetArg.cloudlyNodeId}\0${targetArg.swarmClusterId}\0${
+        targetArg.swarmNodeId
+      }\0${targetArg.nodeName}\0${targetArg.platform}`;
+      if (previousSortKey !== undefined && sortKey <= previousSortKey) {
+        errors.push('cluster runtime target set targets must be uniquely sorted');
+      }
+      previousSortKey = sortKey;
+      const swarmScope = `${targetArg.swarmClusterId}\0${targetArg.swarmNodeId}`;
+      if (cloudlyNodeIds.has(targetArg.cloudlyNodeId)
+        || swarmNodeScopes.has(swarmScope)
+        || nodeNames.has(targetArg.nodeName)) {
+        errors.push('cluster runtime target identities must be unique');
+      }
+      cloudlyNodeIds.add(targetArg.cloudlyNodeId);
+      swarmNodeScopes.add(swarmScope);
+      nodeNames.add(targetArg.nodeName);
+    }
+    if (errors.length === 0
+      && targetSetArg.targetSetDigest !== await computeClusterRuntimeTargetSetDigest(
+        targetSetArg as unknown as IClusterRuntimeTargetSetReadyV1,
+      )) {
+      errors.push('cluster runtime target set digest does not match');
+    }
+    return errors;
+  } catch {
+    return ['cluster runtime target set must be safely inspectable'];
+  }
+};
+
+export const isClusterRuntimeTargetSetFresh = (
+  targetSetArg: TClusterRuntimeTargetSetV1,
+  nowArg: number,
+): targetSetArg is IClusterRuntimeTargetSetReadyV1 => (
+  targetSetArg.state === 'ready'
+  && Number.isSafeInteger(nowArg)
+  && nowArg >= targetSetArg.acceptedAt
+  && nowArg < targetSetArg.freshUntil
+);
+
 export type TSparkNodeMode = 'cloudly' | 'coreflow-node';
 
 export type TSparkCloudlyConnectionStatus =