@serve.zone/interfaces 32.16.0 → 32.18.0

package/readme.md

@@ -1198,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,
@@ -1462,6 +1466,11 @@ untouched.
 
 Versions are `MAJOR.MINOR.PATCH` and nothing else — no prerelease, no build metadata, no `v`
 prefix, no leading zeros — and are compared per numeric component, so `32.10.0` is above `32.9.0`.
+That grammar is public as `data.IReleaseVersion`, `data.parseReleaseVersion`,
+`data.isReleaseVersion`, `data.compareReleaseVersions` and `data.maximumReleaseVersionLength`: any
+policy that has to order two released versions — a minimum bundle a server believes, a supported
+floor — reads them here instead of splitting strings of its own, which is how a comparison ends up
+saying `32.9.0` is above `32.10.0`.
 `minimumPeerVersion` is in the same major as `interfacesVersion` and never above it. Each
 deployable owns its minimums, one per session kind it serves, and raises one only in the commit
 that starts depending on a later interfaces minor, for that session kind alone.
@@ -1553,7 +1562,12 @@ Coreflow connection:
   exact next sequence with a strictly advancing `observedAt`, while an exact
   same-sequence/same-digest retry returns the byte-equivalent persisted receipt
   before age checks. It must reject conflicting, stale, skipped,
-  retired-session, old, future, or non-advancing reports. A reused session ID
+  retired-session, old, future, or non-advancing reports. `evidence-refused` is the
+  one rejection about content rather than sequencing: it names an evidence member
+  this server refuses for this body and every resend of it, so the node must change
+  the body instead of retrying it, while a server-side condition a later attempt
+  could pass stays `acceptance-race` — telling those two apart while it accepts
+  evidence is the consumer's own work. A reused session ID
   may be treated as new only after it leaves the bounded retired window, and its
   sequence-one observation must still advance the permanent timestamp
   high-water mark. The consumer must persist acceptance state and its receipt
@@ -2027,12 +2041,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 = {
@@ -2109,6 +2124,162 @@ 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. Accepting it is
+state-independent; completing the evidence is not. `IFleetCutoverCoreflowRetirementEvidence`
+completes only from a `member` observation of the relay host, because `relay.nodeObservation` and
+`spark.observation` must be the identical accepted reference and that reference has to carry the
+relay host's local Docker snapshot, which no other observation state can state. 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` — the two of
+`data.sparkLegacyConfigurationDispositions`, with `data.TSparkLegacyConfigurationDisposition` as
+their union; 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.
+
+The answer travels on the observation's own accepted receipt, as
+`ISparkSwarmObservationAcceptedReceipt.fleetCutoverLegacyRetirement`, a
+`data.TSparkLegacyRetirementOutcome`: `{ state: 'accepted', generation }` for the revision this
+observation advanced both records to, `{ state: 'restated', generation }` for the replay that
+renewed nothing, and `{ state: 'refused', refusal, retryable: false }` naming one of the refusals
+above. A refused statement does not reject the observation. The statement is judged against
+records rather than against the message — a malformed one is already refused by
+`validateSparkLegacyRuntimeRetirement` — so everything left is a fact about this node's history,
+while the observation's liveness and census are true either way and the cluster's target set
+depends on their freshness. A refusal is never retryable: it answers one exact statement, so
+resending it cannot change the answer, and a genuine server-side race is the observation's own
+`acceptance-race` one level up. The flag is carried anyway, so a node meeting a refusal name a
+later minor added still learns it must stop.
+`validateSparkSwarmObservationResponse` binds the answer to the statement in both directions: an
+accepted receipt that answers a statement the observation never made, or leaves one it did make
+unanswered, is refused. A rejected receipt carries no outcome at all, because an observation that
+was not accepted never reached the statement.
+`data.snapshotSparkLegacyRetirementOutcome` and `data.validateSparkLegacyRetirementOutcome` read
+it exact-key per state, like every other shape here.
+
+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. The duty runs both ways: a receipt is read exact-key too,
+so a Cloudly that begins answering with `fleetCutoverLegacyRetirement` raises its own
+`sparkSwarmNode` minimum in the same commit, or an older Spark refuses the receipt for a member it
+does not know.
+
 ### 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.16.0',
+  version: '32.18.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,12 @@ import {
   type IFleetCutoverPreparedVolumeHandoffIntent,
   type IFleetCutoverPreparedVolumeHandoffPage,
 } from './fleetcutover.js';
+import {
+  validateSparkLegacyRetirementOutcome,
+  validateSparkLegacyRuntimeRetirement,
+  type ISparkLegacyRuntimeRetirement,
+  type TSparkLegacyRetirementOutcome,
+} from './sparklegacyretirement.js';
 import { protocolRefusalHttpStatus, validateProtocolOfferOn, type IProtocolOffer } from '../protocol.js';
 import {
   canonicalizeStrictJson,
@@ -242,6 +248,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 =
@@ -280,7 +288,17 @@ export type TSparkSwarmObservationRejectionCode =
   | 'observation-too-old'
   | 'observation-from-future'
   | 'observation-time-not-advancing'
-  | 'acceptance-race';
+  | 'acceptance-race'
+  /**
+   * An evidence member of this observation is refused, for this body and every resend of it.
+   *
+   * The whole observation is rejected because the refused content is what the body states, and a
+   * node that keeps resending it would never be recorded. It is the answer for a member whose
+   * content this server has decided against; a server-side condition that a later attempt could
+   * pass is `acceptance-race` instead, and telling the two apart while accepting evidence is the
+   * server's own work.
+   */
+  | 'evidence-refused';
 
 export const sparkSwarmObservationContract = Object.freeze({
   digestDomain: 'serve.zone/spark-swarm-observation',
@@ -297,6 +315,7 @@ export const sparkSwarmObservationContract = Object.freeze({
     'observation-from-future': false,
     'observation-time-not-advancing': false,
     'acceptance-race': true,
+    'evidence-refused': false,
   } satisfies Record<TSparkSwarmObservationRejectionCode, boolean>),
 } as const);
 
@@ -344,6 +363,15 @@ export interface ISparkSwarmObservationAcceptedReceipt {
   acceptedAt: number;
   /** Runtime target generation observed immediately after this acceptance. */
   targetGenerationAtAcceptance: number;
+  /**
+   * What the server did with `fleetCutoverLegacyRetirement`, present exactly when it was stated.
+   *
+   * A statement about the node's own released runtime is judged against records rather than
+   * against this message, so its refusal is answered here instead of rejecting an observation
+   * whose liveness and census are true either way. Absent on the rejected receipt: an observation
+   * that was not accepted never reached the statement.
+   */
+  fleetCutoverLegacyRetirement?: TSparkLegacyRetirementOutcome;
   /** The answering server's offer; see `sparkSwarmNodeContracts`. */
   protocol: IProtocolOffer;
 }
@@ -628,6 +656,8 @@ export const validateSparkSwarmObservation = async (
       'state',
       ...(observation.fleetCutoverHeldVolumeFences === undefined
         ? [] : ['fleetCutoverHeldVolumeFences']),
+      ...(observation.fleetCutoverLegacyRetirement === undefined
+        ? [] : ['fleetCutoverLegacyRetirement']),
     ];
     const expectedKeys = observation.state === 'unknown'
       ? [...commonKeys, 'reason']
@@ -676,6 +706,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') {
@@ -955,6 +990,8 @@ export const validateSparkSwarmObservationResponse = async (
       'observationDigest',
       'acceptedAt',
       'targetGenerationAtAcceptance',
+      ...(responseArg.fleetCutoverLegacyRetirement === undefined
+        ? [] : ['fleetCutoverLegacyRetirement']),
       'protocol',
     ];
     const rejectedKeys = [
@@ -1004,6 +1041,18 @@ export const validateSparkSwarmObservationResponse = async (
         || (responseArg.targetGenerationAtAcceptance as number) < 0) {
         errors.push('Spark Swarm observation accepted receipt fields must be canonical');
       }
+      // Stated and unanswered, or answered and never stated: both are a server that judged
+      // something other than the observation this receipt binds.
+      if ((responseArg.fleetCutoverLegacyRetirement !== undefined)
+        !== (expectedRequestArg.observation.fleetCutoverLegacyRetirement !== undefined)) {
+        errors.push(
+          'Spark Swarm observation accepted receipt must answer the legacy retirement it was sent',
+        );
+      } else if (responseArg.fleetCutoverLegacyRetirement !== undefined) {
+        errors.push(...validateSparkLegacyRetirementOutcome(
+          responseArg.fleetCutoverLegacyRetirement,
+        ).map(errorArg => `Spark Swarm observation response ${errorArg}`));
+      }
     } else {
       const retryability = sparkSwarmObservationContract.rejectionRetryability;
       if (!isPositiveSafeInteger(responseArg.rejectedAt)