@serve.zone/interfaces 32.15.0 → 32.17.0

package/readme.md

@@ -1056,6 +1056,24 @@ sequence, observation time and fixed `freshUntil`; assembling a later census can
 observation. It never transports environment, arbitrary labels, mount paths, volume names,
 registry credentials or secret values.
 
+`data.computeFleetCutoverDockerServiceSpecDigest` hashes the complete open-schema Docker
+`Service.Spec`, including response properties unknown to this Interfaces version, under
+`serve.zone/fleet-cutover-docker-service-spec`. The helper returns only the digest: the full spec,
+including any environment values or secret references it contains, never belongs in the
+observation or logs. `data.computeFleetCutoverDockerConstraintSetIdentity` sorts exact constraint
+strings in UTF-16 code-unit order, preserves duplicates, and binds both the resulting list and its
+count. `data.snapshotFleetCutoverDockerDesiredTaskCount` admits only the non-negative safe integer
+from `ServiceStatus.DesiredTasks`; the producer must request service status and must not derive a
+replacement from task state. These helpers consume only the Docker response fields they name, so
+additional response properties do not make a newer daemon unreadable.
+
+The only established historical service-identity ownership label is
+`data.fleetCutoverDockerLabelNames.serviceId`, whose exact value is `serve.zone.serviceId`.
+`ownershipLabels.platformOwner: null` means there is no known Docker-label evidence of a platform
+owner. It does not classify the service as an application, and neither a service name nor an
+unrecognized label supplies that classification. Cloudly's accepted administrator classification
+remains the authority for unlabeled legacy platform services.
+
 Mount identity has three explicit canonical domains. `serve.zone/fleet-cutover-mount-source-identity`
 hashes `{ type, source }`, where `source` is the exact UTF-8 `Mount.Source` returned by Docker,
 including an empty string. `serve.zone/fleet-cutover-mount-target-identity` hashes `{ target }`,
@@ -1068,6 +1086,26 @@ ownership also prevents completion rather than omitting the container. Structura
 not establish freshness, authentication, manager consensus, ownership or Docker truth; Cloudly
 establishes those policy facts while dereferencing the accepted observations.
 
+Docker exposes two different volume sources. A service-spec `Mount.Source` is the logical volume
+name, while a local container `MountPoint.Source` is its physical host path and `MountPoint.Name`
+is the logical name. `data.createFleetCutoverDockerServiceMountDescriptor` and
+`data.createFleetCutoverDockerLocalMountDescriptor` therefore keep their exact raw-source mount
+identities distinct. They never substitute `Name` for `Source`. The local-only
+`data.createFleetCutoverDockerPhysicalMountEvidence` adds a value-free correlation from the
+physical `mountIdentityDigest` to the service-spec identity derived from exact `MountPoint.Name`
+for volumes, or exact `Source` for bind and tmpfs mounts. Its independently domain-separated
+correlation digest binds that pair. When a physical container states `mountCorrelations`, the list
+must be sorted, unique, bounded, and a complete one-to-one mapping of its mounts. The property is
+optional only so observations created before this evidence existed still parse; absence proves no
+join, and a cutover consumer requiring a physical/service match must refuse it. Unsupported local
+mount types and volume mounts without a non-empty `Name` cannot produce correlation evidence.
+
+The shared exact classifier recognizes only a writable
+`/var/run/docker.sock` to `/var/run/docker.sock` bind as `docker-socket`, a read-only
+`/sys/fs/cgroup` to `/host/cgroup` bind as `cgroup`, every volume as `persistent-volume`, other
+binds as `bind`, and tmpfs as `tmpfs`. Other Docker types remain `unknown`; no path normalization
+or service-name inference is performed.
+
 `data.IFleetCutoverScope` is the server-owned authoritative service set. It starts `incomplete`;
 every `complete` entry binds an exact Docker service id to the current service authority and an
 accepted classification authority. `unknown` cannot appear in a complete structural snapshot.
@@ -1160,6 +1198,10 @@ source is identified by SHA-256 and may be `retained-inert` or `removed`; deleti
 erasure are not cutover requirements. Its exact owner generation is retained with that disposition.
 Retained recovery evidence is valid only while the released
 owner cannot consume it into live mode and the old credential remains revoked.
+`relay.credential`, `relay.acceptedRegistration`, `legacy.credential` and `legacy.invalidation`
+reference the records of [Cluster Relay Credential](#cluster-relay-credential). The old-mode
+refusal, the configuration CAS and the Spark bundle and unit identity are Spark-owned and come
+from [Spark Legacy Runtime Retirement](#spark-legacy-runtime-retirement).
 
 Before any post-pallet assignment exists, an administrator calls
 `requests.fleetcutover.prepareFleetCutoverIngress` with the exact server-created service ID,
@@ -1989,12 +2031,13 @@ with `clusterRelayCertificateDomainName(relay)`, which returns the origin's host
 Cloudly issues the certificate for and owns the A record for. An origin naming an address literal
 therefore has no issuable certificate.
 
-`data.clusterRelayUndispatchedRefusals` names the three registration refusals that end a relay's
-custody — `relay-cluster-not-enabled`, `relay-node-foreign` and `relay-sequence-not-advancing` —
-with `data.TClusterRelayUndispatchedRefusal` as their union. Each is Cloudly reading its own
-records and stating that it does not dispatch to this relay, so a relay that hears one drops what
-it holds for its nodes instead of waiting. A refusal that only says Cloudly could not verify the
-relay states nothing about dispatch and is deliberately not in the list.
+`data.clusterRelayUndispatchedRefusals` names the four registration refusals that end a relay's
+custody — `relay-cluster-not-enabled`, `relay-node-foreign`, `relay-sequence-not-advancing` and
+`relay-credential-generation-stale` — with `data.TClusterRelayUndispatchedRefusal` as their union.
+Each is Cloudly reading its own records and stating that it does not dispatch to this relay, so a
+relay that hears one drops what it holds for its nodes instead of waiting. A refusal that only
+says Cloudly could not verify the relay states nothing about dispatch and is deliberately not in
+the list.
 
 ```typescript
 const relay: data.IClusterRelay = {
@@ -2071,6 +2114,133 @@ const registrationReasons = data.validateRegisterClusterRelayRequest(registratio
 How the relay reaches each node's Corestore is part of the same document: see
 [Corestore Through The Relay](#corestore-through-the-relay).
 
+### Cluster Relay Credential
+
+A cluster's relay authenticates with its own generation-bearing credential instead of the shared
+cluster authority every cluster-side component used before it. `IClusterRelayCredential` is public
+metadata: the cluster, a `generation` that advances by one per accepted mint or rotation, the
+machine `userId` it authenticates as, and `delivery`, the `ISecretVersionReference` of the
+immutable encrypted version the bearer was delivered as. No record, receipt, request or response
+of this contract carries a bearer, a hash or key material, and every reader is exact-keyed, so a
+peer that adds a secret-looking member is refused rather than copied.
+
+The credential authenticates the cluster's whole control-plane session, exactly what the shared
+authority authenticated, so a relay changes one credential and keeps every call it makes. The gain
+is a generation Cloudly fences each socket against and an authority it can rotate and retire on
+its own; the scope is not narrower. One cluster has one relay and therefore one credential record,
+and it never expires by itself: rotation is its lifecycle.
+
+`mutateClusterRelayCredential { identity, mutation }` takes `TClusterRelayCredentialMutation`.
+`ensure` requires `expectedGeneration: null` and an absent record; `rotate` requires the exact
+current generation, never a minimum. The caller retains the complete request and its `mutationId`
+across retries: the identical body answers with the original result and `replayed: true` without
+renewing delivery, generation or authority, and a changed body fails closed. The first mint also
+records the shared authority the cluster still carries as `IClusterLegacyRelayCredential`, so a
+replacement never exists without a named predecessor. Rotation has no overlap: the previous
+generation stops authenticating at commit, and a relay still holding it hears
+`relay-credential-generation-stale`, drops what it holds for its nodes, reads the delivered version
+and reconnects. There is no revocation of the relay credential, because a rotation already covers
+a compromised one without a state in which the cluster has no relay authority at all.
+
+An accepted `registerClusterRelay` answers with two references beside the origin and the offer:
+`credential`, the generation Cloudly authenticated the socket as, and `acceptedRegistration`, the
+record that acceptance wrote. The relay states no generation of its own — the registration request
+is unchanged — because a relay naming its own generation would be asserting its own rank.
+`IClusterRelayAcceptedRegistration` is that record: the registration facts the served read shape
+also carries, its own `id`, a `generation` that advances once per acceptance, the `credential`
+reference and a `digest`. Liveness is not part of it. `IClusterRelayRegistration` keeps exactly its
+published members, the facts plus `live`.
+
+`retireLegacyClusterRelayCredential { identity, retirement }` revokes the shared authority, and is
+the last step of replacing it. `IClusterLegacyRelayCredentialRetirementRequest` carries
+compare-and-swap inputs only: the exact `expectedLegacyGeneration`, the `replacement` credential
+reference and the `acceptedRegistration` reference the caller observed. Cloudly dereferences both
+against its own current records, requires the registration to have been made under that
+replacement, and requires a verified live socket carrying it; a caller can state no liveness or
+proof of its own. Acceptance writes the one-shot `IClusterLegacyRelayCredentialInvalidation`
+(`generation: 1`) and advances the legacy record to `state: 'revoked'` naming it. The invalidation
+names the legacy record at the generation before the revocation and the record names the
+invalidation after it, so neither digest covers the other's.
+`data.clusterRelayCredentialRefusals` names every other answer, with
+`data.TClusterRelayCredentialRefusal` as their union. `getClusterRelayCredential { identity,
+clusterId }` reads the chain: the credential, the legacy record and the current accepted
+registration, each `null` while no record exists.
+
+Each digest-bearing record has a `snapshot…`, `compute…Digest` and `validate…` function under its
+own digest domain in `data.clusterRelayCredentialContract` and `data.clusterRelayContract`.
+`bindClusterLegacyRelayCredentialInvalidation(invalidation, legacyCredential,
+acceptedRegistration)` joins an invalidation to the legacy record it revoked — the active record
+it names or that record's revoked successor — and to a registration whose `credential` equals the
+invalidation's `replacement`. It is a content check; dereferencing each record as current and
+requiring the live socket remain Cloudly's.
+
+All three requests read only the verified `IIdentityCredential`, never an identity member a caller
+states about itself.
+
+### Spark Legacy Runtime Retirement
+
+The Spark-owned half of `IFleetCutoverCoreflowRetirementEvidence` — the refused old mode, the
+configuration compare-and-swap, and the bundle and unit identity — is transported on the Swarm
+observation a node already posts. There is no route, request or endpoint for it. That is forced
+rather than preferred: the evidence requires `relay.nodeObservation` and `spark.observation` to be
+the identical accepted reference, so these facts must reach Cloudly on the very observation that
+carries the node's Docker census.
+
+`data.ISparkLegacyRuntimeRetirement` is the optional observation member, available in every
+observation state because it describes the host and not its Docker daemon. It is
+`{ refusedMode, bundle, configuration }` and nothing else. It names no node: Cloudly binds it to
+the reporter it already authenticated, so there is no node identity on it to disagree with. It
+carries no digest of its own either — `computeSparkSwarmObservationDigest` canonicalizes the whole
+observation, so a second domain here would only be a second thing to keep in step.
+
+`refusedMode` is one of `data.sparkLegacyRuntimeModes`, the two runtimes a released Spark could be
+put into by its `mode` configuration key. `data.sparkLegacyRuntimeModeServices` is the record over
+that union naming the Docker services each mode owns, so a refusal states a mode and a reader
+derives the set. `data.ISparkNodeBundleIdentity { version, sourceCommit, manifestSha256, unitName,
+unitDigest }` is read back from the installed tree and the installed unit file, never from the
+running process's own build constants: a build can state its own version, it cannot state that the
+host will start that same code again. `data.ISparkLegacyConfigurationState { ownerGeneration,
+sourceSha256, disposition }` names the released key-value source by digest alone. No decoded member
+of that file is representable in any shape here, because it carries the node's released bearer and
+its jump code; `sourceSha256` covers the whole file, whose smallest unguessable part is a 256-bit
+token. `disposition` is `retained-inert` or `removed`; erasure is not a cutover requirement.
+
+Cloudly accepts an observation first and then advances two of its own records, which is what the
+evidence's two references point at. `data.ISparkLegacyModeRefusal` and
+`data.ISparkLegacyConfigurationRetirement` are revisions, not one-shot receipts: a node restates
+both on every observation, a bundle upgrade changes what the boot path is, and a disposition
+changes once. Both carry the accepted observation they were derived from, its reporter session and
+its sequence, and both obey the revision rule every record of this package obeys — a first
+generation has no predecessor and a later one names exactly the generation before it. The
+configuration record carries two counters on purpose: its own `generation` is contiguous because it
+is this record's revision, while `configuration.ownerGeneration` is the node's own and may skip,
+since an observation that never arrived must not look like a skipped revision.
+
+`advancesSparkLegacyConfigurationState(current, next)` is the compare-and-swap rule, `null` for a
+node's first accepted state: the same `sourceSha256`, a strictly higher `ownerGeneration`, and no
+return from `removed` to `retained-inert`. Restating the accepted generation is a replay and
+therefore not an advance, which is what keeps `acceptedAt` and the named observation from aging
+forward on a node that has stopped changing. `data.sparkLegacyRetirementRefusals` names every other
+answer, with `data.TSparkLegacyRetirementRefusal` as their union.
+`bindSparkLegacyRetirement(modeRefusal, configurationRetirement)` joins the two receipts a
+retirement cites, requiring the same cluster, node, reporter session, sequence and accepted
+observation. It is a content check; whether each receipt is its node's current revision remains
+Cloudly's.
+
+An omitted member is not a refusal and advances nothing, so the existence of these records is not
+what makes a retirement honest — the freshness of the observation they name is. Assembly must
+require that observation to still be inside `fleetCutoverContract.observationFreshnessMs`, exactly
+as `IFleetCutoverSparkObservationReference` already does, or a node that stopped refusing would go
+on looking retired.
+
+Cloudly reads this member before Spark writes it. Every observation validator in this package is
+exact-key, so a server built against an earlier minor refuses the whole observation rather than
+ignoring a member it does not know — the peers of a session kind are upgraded before the side that
+starts depending on the later minor, and the `minimumPeerVersion` of that session kind is raised in
+the same commit that starts depending on it. A Spark that begins stating this member therefore
+raises its `sparkSwarmNode` minimum alone, which requires one minimum per session kind rather than
+one shared across a deployable's offers.
+
 ### Cluster VPN Hub And Network
 
 A cluster's relay is also that cluster's managed VPN hub: every node of the cluster dials it, and

package/ts/00_commitinfo_data.ts

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

package/ts/data/cluster.ts

@@ -2,11 +2,23 @@ import * as plugins from '../plugins.js';
 
 import { type IDockerRegistryInfo } from '../data/docker.js';
 import type { IClusterNode } from './clusternode.js';
+import type { IFleetCutoverAcceptedEvidenceReference } from './fleetcutover.js';
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
 import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
 import { validateProtocolOfferOn, type IProtocolOffer } from '../protocol.js';
 import { hasExactKeys } from '../private/dataproperties.js';
 import { isClusterNodeId } from '../private/nodeidentifier.js';
-import { networkNoiseKey } from '../private/networkcontract.js';
+import {
+  captureNetwork,
+  networkCounter,
+  networkDigest,
+  networkHash,
+  networkId,
+  networkNoiseKey,
+  networkRecord,
+  networkReference,
+} from '../private/networkcontract.js';
 
 export interface ICluster {
   id: string;
@@ -137,6 +149,16 @@ export interface IRegisterClusterRelayResponse {
   origin: string;
   /** Cloudly's own offer, so an accepted relay judges the session it just registered into. */
   protocol: IProtocolOffer;
+  /**
+   * The relay credential generation Cloudly authenticated this socket as.
+   *
+   * Read from Cloudly's own record and never from the registration: a relay that stated its own
+   * generation would be asserting its own rank. It is how a relay learns the exact generation its
+   * readiness is bound to.
+   */
+  credential: IRuntimeAuthorityReference;
+  /** The accepted registration record this answer wrote, as a retirement record later cites it. */
+  acceptedRegistration: IFleetCutoverAcceptedEvidenceReference;
 }
 
 /**
@@ -155,6 +177,13 @@ export const clusterRelayUndispatchedRefusals = Object.freeze([
   'relay-node-foreign',
   /** A registration of this relay identity at the same or a higher sequence is already recorded. */
   'relay-sequence-not-advancing',
+  /**
+   * The credential this socket authenticated with is no longer the cluster's current generation.
+   *
+   * Rotation has no overlap, so another relay may already hold the current one: this relay is not
+   * the one Cloudly dispatches to, which `relay-identity-unverified` never states.
+   */
+  'relay-credential-generation-stale',
 ] as const);
 
 /** One of the reasons Cloudly states that it does not dispatch to a relay. */
@@ -342,14 +371,12 @@ export const validateRegisterClusterRelayRequest = (
 };
 
 /**
- * One cluster's relay as Cloudly serves it to an administrator.
+ * What one accepted relay registration states about the relay that sent it.
  *
- * This is the read shape, not the registration a relay sends: `IRegisterClusterRelayRequest` is
- * what the relay puts on the wire, and this is what Cloudly answers with after it accepted one.
- * `clusterId` names the cluster the relay serves, and `acceptedAt` is Cloudly's own acceptance
- * time, which is what orders two registrations of one cluster.
+ * The part the served read shape and the accepted record share: no record identity, no digest and
+ * no liveness, so neither shape restates the other's fields.
  */
-export interface IClusterRelayRegistration {
+export interface IClusterRelayRegistrationFacts {
   clusterId: string;
   nodeId: string;
   listenAddress: string;
@@ -357,6 +384,17 @@ export interface IClusterRelayRegistration {
   version: string;
   registrationSequence: number;
   acceptedAt: number;
+}
+
+/**
+ * One cluster's relay as Cloudly serves it to an administrator.
+ *
+ * This is the read shape, not the registration a relay sends: `IRegisterClusterRelayRequest` is
+ * what the relay puts on the wire, and this is what Cloudly answers with after it accepted one.
+ * `clusterId` names the cluster the relay serves, and `acceptedAt` is Cloudly's own acceptance
+ * time, which is what orders two registrations of one cluster.
+ */
+export interface IClusterRelayRegistration extends IClusterRelayRegistrationFacts {
   /**
    * Whether a verified socket carries this relay at this instant.
    *
@@ -367,6 +405,26 @@ export interface IClusterRelayRegistration {
   live: boolean;
 }
 
+const clusterRelayRegistrationFactKeys = [
+  'clusterId', 'nodeId', 'listenAddress', 'listenPort', 'version', 'registrationSequence',
+  'acceptedAt',
+] as const;
+
+/** The one format rule of every registration fact, whichever shape carries it. */
+const validateClusterRelayRegistrationFacts = (
+  valueArg: Record<string, unknown>,
+  pathArg: string,
+): string[] => [
+  ...validateClusterRelayIdentifier(valueArg.clusterId, `${pathArg} clusterId`),
+  ...validateClusterRelayIdentifier(valueArg.nodeId, `${pathArg} nodeId`),
+  ...validateClusterRelayListenAddress(valueArg.listenAddress, `${pathArg} listenAddress`),
+  ...validateClusterRelayListenPort(valueArg.listenPort, `${pathArg} listenPort`),
+  ...validateClusterRelayVersion(valueArg.version, `${pathArg} version`),
+  ...validateClusterRelayNonNegativeInteger(valueArg.registrationSequence,
+    `${pathArg} registrationSequence`),
+  ...validateClusterRelayNonNegativeInteger(valueArg.acceptedAt, `${pathArg} acceptedAt`),
+];
+
 /**
  * Validates one served relay registration and names every reason it is refused.
  *
@@ -378,23 +436,95 @@ export const validateClusterRelayRegistration = (
   valueArg: unknown,
   pathArg = 'cluster relay registration',
 ): string[] => {
-  if (!isRecord(valueArg) || !hasExactKeys(valueArg, ['clusterId', 'nodeId', 'listenAddress',
-    'listenPort', 'version', 'registrationSequence', 'acceptedAt', 'live'])) {
+  if (!isRecord(valueArg)
+    || !hasExactKeys(valueArg, [...clusterRelayRegistrationFactKeys, 'live'])) {
     return [`${pathArg} must use its exact schema`];
   }
   return [
-    ...validateClusterRelayIdentifier(valueArg.clusterId, `${pathArg} clusterId`),
-    ...validateClusterRelayIdentifier(valueArg.nodeId, `${pathArg} nodeId`),
-    ...validateClusterRelayListenAddress(valueArg.listenAddress, `${pathArg} listenAddress`),
-    ...validateClusterRelayListenPort(valueArg.listenPort, `${pathArg} listenPort`),
-    ...validateClusterRelayVersion(valueArg.version, `${pathArg} version`),
-    ...validateClusterRelayNonNegativeInteger(valueArg.registrationSequence,
-      `${pathArg} registrationSequence`),
-    ...validateClusterRelayNonNegativeInteger(valueArg.acceptedAt, `${pathArg} acceptedAt`),
+    ...validateClusterRelayRegistrationFacts(valueArg, pathArg),
     ...(typeof valueArg.live === 'boolean' ? [] : [`${pathArg} live must be a boolean`]),
   ];
 };
 
+/**
+ * Cloudly's accepted registration record: the thing an evidence reference names.
+ *
+ * `credential` is the exact relay credential generation the registering socket authenticated as,
+ * so a reader can tell a registration made under the current credential from one made under a
+ * superseded one. Liveness is deliberately absent: a live socket is not a fact a record can hold,
+ * and a digest that covered it would change without anything having been registered.
+ */
+export interface IClusterRelayAcceptedRegistration extends IClusterRelayRegistrationFacts {
+  id: string;
+  /** Advances by one per accepted registration, so a reference to a superseded one fails closed. */
+  generation: number;
+  credential: IRuntimeAuthorityReference;
+  digest: TSha256Digest;
+}
+
+export const clusterRelayContract = Object.freeze({
+  acceptedRegistrationDigestDomain: 'serve.zone/cluster-relay-accepted-registration',
+} as const);
+
+const failClusterRelayRecord = (): never => {
+  throw new Error('Cluster relay contract rejected.');
+};
+
+/** The facts of an already exact-keyed record, refused unless each passes its one format rule. */
+const readClusterRelayRegistrationFacts = (
+  valueArg: Record<string, unknown>,
+): IClusterRelayRegistrationFacts => {
+  if (validateClusterRelayRegistrationFacts(valueArg, 'cluster relay registration').length > 0) {
+    failClusterRelayRecord();
+  }
+  const {
+    clusterId, nodeId, listenAddress, listenPort, version, registrationSequence, acceptedAt,
+  } = valueArg;
+  // Each member passed its format rule above, which is what the assertion states.
+  return {
+    clusterId, nodeId, listenAddress, listenPort, version, registrationSequence, acceptedAt,
+  } as IClusterRelayRegistrationFacts;
+};
+
+/** Structural copy only; whether the record is the cluster's current one is Cloudly's to decide. */
+export const snapshotClusterRelayAcceptedRegistration = (
+  valueArg: unknown,
+): IClusterRelayAcceptedRegistration => {
+  try {
+    const value = networkRecord(captureNetwork(valueArg), [
+      ...clusterRelayRegistrationFactKeys, 'id', 'generation', 'credential', 'digest',
+    ]);
+    return {
+      ...readClusterRelayRegistrationFacts(value),
+      id: networkId(value.id),
+      generation: networkCounter(value.generation),
+      credential: networkReference(value.credential),
+      digest: networkDigest(value.digest),
+    };
+  } catch {
+    return failClusterRelayRecord();
+  }
+};
+
+export const computeClusterRelayAcceptedRegistrationDigest = async (
+  valueArg: unknown,
+): Promise<TSha256Digest> => networkHash(
+  clusterRelayContract.acceptedRegistrationDigestDomain,
+  snapshotClusterRelayAcceptedRegistration(valueArg),
+);
+
+export const validateClusterRelayAcceptedRegistration = async (
+  valueArg: unknown,
+): Promise<string[]> => {
+  try {
+    const value = snapshotClusterRelayAcceptedRegistration(valueArg);
+    return value.digest === await computeClusterRelayAcceptedRegistrationDigest(value)
+      ? [] : ['cluster relay accepted registration digest does not match'];
+  } catch {
+    return ['cluster relay accepted registration must use its exact canonical schema'];
+  }
+};
+
 /**
  * The name the relay's certificate is issued for, and the A record Cloudly
  * owns for it. Derived from the origin so every consumer derives it

package/ts/data/clusternode.ts

@@ -20,6 +20,10 @@ import {
   type IFleetCutoverPreparedVolumeHandoffIntent,
   type IFleetCutoverPreparedVolumeHandoffPage,
 } from './fleetcutover.js';
+import {
+  validateSparkLegacyRuntimeRetirement,
+  type ISparkLegacyRuntimeRetirement,
+} from './sparklegacyretirement.js';
 import { protocolRefusalHttpStatus, validateProtocolOfferOn, type IProtocolOffer } from '../protocol.js';
 import {
   canonicalizeStrictJson,
@@ -242,6 +246,8 @@ interface ISparkSwarmObservationBase {
   observedAt: number;
   /** Available in every observation state; exact page membership proves an empty node subset. */
   fleetCutoverHeldVolumeFences?: IFleetCutoverHeldVolumeFenceEvidencePage;
+  /** Available in every observation state too: this describes the host, not its Docker daemon. */
+  fleetCutoverLegacyRetirement?: ISparkLegacyRuntimeRetirement;
 }
 
 export type TSparkSwarmObservation =
@@ -628,6 +634,8 @@ export const validateSparkSwarmObservation = async (
       'state',
       ...(observation.fleetCutoverHeldVolumeFences === undefined
         ? [] : ['fleetCutoverHeldVolumeFences']),
+      ...(observation.fleetCutoverLegacyRetirement === undefined
+        ? [] : ['fleetCutoverLegacyRetirement']),
     ];
     const expectedKeys = observation.state === 'unknown'
       ? [...commonKeys, 'reason']
@@ -676,6 +684,11 @@ export const validateSparkSwarmObservation = async (
         errorArg => `Spark Swarm observation ${errorArg}`,
       ));
     }
+    if (observation.fleetCutoverLegacyRetirement !== undefined) {
+      errors.push(...validateSparkLegacyRuntimeRetirement(
+        observation.fleetCutoverLegacyRetirement,
+      ).map(errorArg => `Spark Swarm observation ${errorArg}`));
+    }
     if (observation.state === 'member') {
       if (!isRuntimeIdentifier(observation.localSwarmNodeId)
         || typeof observation.controlAvailable !== 'boolean') {