@serve.zone/interfaces 31.9.0 → 32.0.1

package/ts/data/clusternode.ts

@@ -1,10 +1,12 @@
 import * as plugins from '../plugins.js';
 import type { TSha256Digest, TImmutableContainerPlatform } from './immutableimage.js';
-import type { ISparkNodeReportRecordV2 } from './sparknodereport.js';
+import type { ISparkNodeReportRecord } from './sparknodereport.js';
+import { protocolRefusalHttpStatus, validateProtocolOfferOn, type IProtocolOffer } from '../protocol.js';
 import {
   canonicalizeStrictJson,
   createCanonicalJsonSha256Hex,
 } from '../private/canonicaljson.js';
+import { hasExactKeys } from '../private/dataproperties.js';
 
 export interface IClusterNodeMetrics {
   cpuUsagePercent: number;
@@ -69,10 +71,85 @@ export interface IServeZoneServiceRuntimeInfo {
   error?: string;
 }
 
-/** Spark -> Cloudly HTTP body for POST /spark/v1/nodes/metrics-sample */
+/**
+ * The Swarm-era Spark runtime's own routes.
+ *
+ * A separate runtime, not an older version of the node runtime: a worker in `coreflow-node` mode
+ * posts these four bodies, while a pallet node posts `sparkNodeHeartbeatContract.endpoint`. They
+ * retire together with coreflow, not with this release.
+ *
+ * Each route states its endpoint beside the bytes it reads and writes, in the same three members
+ * as `sparkNodeHeartbeatContract`, so one bounded-read helper serves every Spark route. The four
+ * bounds differ because the bodies do: a bound is the largest body its own shape can carry here,
+ * rounded up, and nothing larger is read before it is refused. Every route is judged in the one
+ * server order `protocol.readProtocolOffer` states, against this server's `sparkSwarmNode` offer;
+ * none of them carries a typed error, so a refusal is answered with `protocolRefusalStatus` and an
+ * `IProtocolRefusal` body before the node is authenticated and before the body is acted on. Every
+ * answer states this server's own offer, exactly as the request states the reporter's, so each
+ * side judges the other from the bodies they exchanged.
+ */
+export const sparkSwarmNodeContracts = Object.freeze({
+  /** The full runtime description on every beat; each described service costs some 600 bytes. */
+  heartbeat: Object.freeze({
+    endpoint: '/spark/swarm-nodes/heartbeat',
+    maxRequestBytes: 32_768,
+    maxResponseBytes: 2048,
+  } as const),
+  /** One sample up, every action the server holds for this node back down. */
+  metricsSample: Object.freeze({
+    endpoint: '/spark/swarm-nodes/metrics-sample',
+    maxRequestBytes: 4096,
+    maxResponseBytes: 32_768,
+  } as const),
+  /** `resultText` is the body here, and a server keeps at most 4000 characters of it. */
+  actionResult: Object.freeze({
+    endpoint: '/spark/swarm-nodes/action-result',
+    maxRequestBytes: 8192,
+    maxResponseBytes: 2048,
+  } as const),
+  /**
+   * By far the largest of the four: a manager snapshot carries up to the 1024 observed nodes
+   * `validateSparkSwarmObservationRequest` admits, each with two identifiers of up to 200
+   * characters, which is close to 600 KiB of body this route must still be able to read.
+   */
+  swarmObservation: Object.freeze({
+    endpoint: '/spark/swarm-nodes/swarm-observation',
+    maxRequestBytes: 786_432,
+    maxResponseBytes: 2048,
+  } as const),
+  protocolRefusalStatus: protocolRefusalHttpStatus,
+} as const);
+
+/**
+ * Spark -> Cloudly body for `sparkSwarmNodeContracts.heartbeat.endpoint`.
+ *
+ * The host presentation of a Swarm-era worker: its metrics and its runtime description, both
+ * stated in full on every beat. This is the one owner of the shape — Cloudly and Spark each
+ * carried a private copy until 32.0.0, which is how the two drifted apart.
+ */
+export interface ISparkSwarmNodeHeartbeatRequest {
+  nodeId: string;
+  nodeToken: string;
+  /** Read and negotiated before the node is authenticated; see `sparkSwarmNodeContracts`. */
+  protocol: IProtocolOffer;
+  metrics: IClusterNodeMetrics;
+  runtimeInfo: ISparkNodeRuntimeInfo;
+}
+
+/** What Cloudly answers a Swarm-era heartbeat with; `message` explains a refusal to an operator. */
+export interface ISparkSwarmNodeHeartbeatResponse {
+  accepted: boolean;
+  message?: string;
+  /** The answering server's offer; see `sparkSwarmNodeContracts`. */
+  protocol: IProtocolOffer;
+}
+
+/** Spark -> Cloudly body for `sparkSwarmNodeContracts.metricsSample.endpoint`. */
 export interface ISparkMetricsSampleRequest {
   nodeId: string;
   nodeToken: string;
+  /** Read and negotiated before the node is authenticated; see `sparkSwarmNodeContracts`. */
+  protocol: IProtocolOffer;
   sample: INodeMetricsSample;
 }
 
@@ -81,12 +158,16 @@ export interface ISparkMetricsSampleResponse {
   message?: string;
   /** Actions queued for this node; spark executes them and posts results. */
   pendingActions?: INodeAction[];
+  /** The answering server's offer; see `sparkSwarmNodeContracts`. */
+  protocol: IProtocolOffer;
 }
 
-/** Spark -> Cloudly HTTP body for POST /spark/v1/nodes/action-result */
+/** Spark -> Cloudly body for `sparkSwarmNodeContracts.actionResult.endpoint`. */
 export interface ISparkActionResultRequest {
   nodeId: string;
   nodeToken: string;
+  /** Read and negotiated before the node is authenticated; see `sparkSwarmNodeContracts`. */
+  protocol: IProtocolOffer;
   actionId: string;
   status: Extract<TNodeActionStatus, 'running' | 'succeeded' | 'failed'>;
   resultText?: string;
@@ -95,9 +176,11 @@ export interface ISparkActionResultRequest {
 export interface ISparkActionResultResponse {
   accepted: boolean;
   message?: string;
+  /** The answering server's offer; see `sparkSwarmNodeContracts`. */
+  protocol: IProtocolOffer;
 }
 
-export interface ISwarmManagerObservedNodeV1 {
+export interface ISwarmManagerObservedNode {
   swarmNodeId: string;
   nodeName: string;
   platform: TImmutableContainerPlatform;
@@ -110,66 +193,41 @@ export interface ISwarmManagerObservedNodeV1 {
   };
 }
 
-export interface ISwarmManagerSnapshotV1 {
-  snapshotVersion: 1;
+export interface ISwarmManagerSnapshot {
   snapshotDigest: TSha256Digest;
   nodeCount: number;
   managerCount: number;
-  nodes: ISwarmManagerObservedNodeV1[];
+  nodes: ISwarmManagerObservedNode[];
 }
 
-interface ISparkSwarmObservationBaseV1 {
-  schemaVersion: 1;
+interface ISparkSwarmObservationBase {
   reporterSessionId: string;
   observationSequence: number;
   observedAt: number;
 }
 
-export type TSparkSwarmObservationV1 =
-  | (ISparkSwarmObservationBaseV1 & {
+export type TSparkSwarmObservation =
+  | (ISparkSwarmObservationBase & {
       state: 'unknown';
       reason: 'docker-unavailable' | 'query-failed' | 'not-initialized';
     })
-  | (ISparkSwarmObservationBaseV1 & {
+  | (ISparkSwarmObservationBase & {
       state: 'not-member';
     })
-  | (ISparkSwarmObservationBaseV1 & {
-      state: 'member';
-      swarmClusterId: string;
-      localSwarmNodeId: string;
-      controlAvailable: boolean;
-      managerSnapshot?: ISwarmManagerSnapshotV1;
-    });
-
-interface ISparkSwarmObservationBaseV2 {
-  schemaVersion: 2;
-  reporterSessionId: string;
-  observationSequence: number;
-  observedAt: number;
-}
-
-export type TSparkSwarmObservationV2 =
-  | (ISparkSwarmObservationBaseV2 & {
-      state: 'unknown';
-      reason: 'docker-unavailable' | 'query-failed' | 'not-initialized';
-    })
-  | (ISparkSwarmObservationBaseV2 & {
-      state: 'not-member';
-    })
-  | (ISparkSwarmObservationBaseV2 & {
+  | (ISparkSwarmObservationBase & {
       state: 'member';
       localSwarmNodeId: string;
       controlAvailable: false;
     })
-  | (ISparkSwarmObservationBaseV2 & {
+  | (ISparkSwarmObservationBase & {
       state: 'member';
       swarmClusterId: string;
       localSwarmNodeId: string;
       controlAvailable: true;
-      managerSnapshot?: ISwarmManagerSnapshotV1;
+      managerSnapshot?: ISwarmManagerSnapshot;
     });
 
-export type TSparkSwarmObservationV2RejectionCode =
+export type TSparkSwarmObservationRejectionCode =
   | 'sequence-conflict'
   | 'sequence-stale'
   | 'sequence-gap'
@@ -180,9 +238,8 @@ export type TSparkSwarmObservationV2RejectionCode =
   | 'observation-time-not-advancing'
   | 'acceptance-race';
 
-export const sparkSwarmObservationV2Contract = Object.freeze({
-  endpoint: '/spark/v2/nodes/swarm-observation',
-  digestDomain: 'serve.zone/spark-swarm-observation-v2',
+export const sparkSwarmObservationContract = Object.freeze({
+  digestDomain: 'serve.zone/spark-swarm-observation',
   maximumPastAgeMs: 300_000,
   maximumFutureSkewMs: 30_000,
   retainedRetiredSessionIds: 32,
@@ -196,18 +253,19 @@ export const sparkSwarmObservationV2Contract = Object.freeze({
     'observation-from-future': false,
     'observation-time-not-advancing': false,
     'acceptance-race': true,
-  } satisfies Record<TSparkSwarmObservationV2RejectionCode, boolean>),
+  } satisfies Record<TSparkSwarmObservationRejectionCode, boolean>),
 } as const);
 
 /** Cloudly derives node and cluster scope from this authenticated Spark request. */
-export interface ISparkSwarmObservationV2Request {
+export interface ISparkSwarmObservationRequest {
   nodeId: string;
   nodeToken: string;
-  observation: TSparkSwarmObservationV2;
+  /** Read and negotiated before the node is authenticated; see `sparkSwarmNodeContracts`. */
+  protocol: IProtocolOffer;
+  observation: TSparkSwarmObservation;
 }
 
-export interface ISparkSwarmObservationV2AcceptedReceipt {
-  schemaVersion: 2;
+export interface ISparkSwarmObservationAcceptedReceipt {
   state: 'accepted';
   nodeId: string;
   reporterSessionId: string;
@@ -216,18 +274,21 @@ export interface ISparkSwarmObservationV2AcceptedReceipt {
   acceptedAt: number;
   /** Runtime target generation observed immediately after this acceptance. */
   targetGenerationAtAcceptance: number;
+  /** The answering server's offer; see `sparkSwarmNodeContracts`. */
+  protocol: IProtocolOffer;
 }
 
-export interface ISparkSwarmObservationV2RejectedReceipt {
-  schemaVersion: 2;
+export interface ISparkSwarmObservationRejectedReceipt {
   state: 'rejected';
   nodeId: string;
   reporterSessionId: string;
   observationSequence: number;
   observationDigest: TSha256Digest;
   rejectedAt: number;
-  code: TSparkSwarmObservationV2RejectionCode;
+  code: TSparkSwarmObservationRejectionCode;
   retryable: boolean;
+  /** The answering server's offer; see `sparkSwarmNodeContracts`. */
+  protocol: IProtocolOffer;
 }
 
 /**
@@ -235,25 +296,11 @@ export interface ISparkSwarmObservationV2RejectedReceipt {
  * authentication. Malformed and authentication failures use generic HTTP
  * errors so they cannot expose credential or persisted replay state.
  */
-export type TSparkSwarmObservationV2Response =
-  | ISparkSwarmObservationV2AcceptedReceipt
-  | ISparkSwarmObservationV2RejectedReceipt;
-
-/** Cloudly derives node and cluster scope from this authenticated Spark request. */
-export interface ISparkSwarmObservationRequest {
-  nodeId: string;
-  nodeToken: string;
-  observation: TSparkSwarmObservationV1;
-}
+export type TSparkSwarmObservationResponse =
+  | ISparkSwarmObservationAcceptedReceipt
+  | ISparkSwarmObservationRejectedReceipt;
 
-export interface ISparkSwarmObservationResponse {
-  accepted: boolean;
-  acceptedSequence?: number;
-  targetGeneration?: number;
-  message?: string;
-}
-
-export interface IClusterRuntimeTargetV1 {
+export interface IClusterRuntimeTarget {
   cloudlyNodeId: string;
   swarmClusterId: string;
   swarmNodeId: string;
@@ -261,8 +308,7 @@ export interface IClusterRuntimeTargetV1 {
   platform: TImmutableContainerPlatform;
 }
 
-export interface IClusterRuntimeTargetSetReadyV1 {
-  schemaVersion: 1;
+export interface IClusterRuntimeTargetSetReady {
   state: 'ready';
   cloudlyClusterId: string;
   swarmClusterId: string;
@@ -270,11 +316,10 @@ export interface IClusterRuntimeTargetSetReadyV1 {
   targetSetDigest: TSha256Digest;
   acceptedAt: number;
   freshUntil: number;
-  targets: IClusterRuntimeTargetV1[];
+  targets: IClusterRuntimeTarget[];
 }
 
-export interface IClusterRuntimeTargetSetUnavailableV1 {
-  schemaVersion: 1;
+export interface IClusterRuntimeTargetSetUnavailable {
   state: 'unavailable';
   cloudlyClusterId: string;
   generation: number;
@@ -287,9 +332,9 @@ export interface IClusterRuntimeTargetSetUnavailableV1 {
     | 'no-schedulable-targets';
 }
 
-export type TClusterRuntimeTargetSetV1 =
-  | IClusterRuntimeTargetSetReadyV1
-  | IClusterRuntimeTargetSetUnavailableV1;
+export type TClusterRuntimeTargetSet =
+  | IClusterRuntimeTargetSetReady
+  | IClusterRuntimeTargetSetUnavailable;
 
 const runtimeIdentifierRegex = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
 const runtimeDigestRegex = /^sha256:[a-f0-9]{64}$/;
@@ -303,11 +348,6 @@ 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)
 );
@@ -326,32 +366,32 @@ const computeSha256 = async (inputArg: string): Promise<TSha256Digest> => {
     .join('')}` as TSha256Digest;
 };
 
-const failSparkSwarmObservationV2Canonicalization = (reasonArg: string): never => {
-  throw new Error(`Spark Swarm observation v2 cannot be canonicalized: ${reasonArg}`);
+const failSparkSwarmObservationCanonicalization = (reasonArg: string): never => {
+  throw new Error(`Spark Swarm observation cannot be canonicalized: ${reasonArg}`);
 };
 
-export const createSparkSwarmObservationV2DigestInput = (
-  observationArg: TSparkSwarmObservationV2,
+export const createSparkSwarmObservationDigestInput = (
+  observationArg: TSparkSwarmObservation,
 ): string => canonicalizeStrictJson(
   {
-    domain: sparkSwarmObservationV2Contract.digestDomain,
+    domain: sparkSwarmObservationContract.digestDomain,
     observation: observationArg,
   },
-  failSparkSwarmObservationV2Canonicalization,
-  'Spark Swarm observation v2 digest input',
+  failSparkSwarmObservationCanonicalization,
+  'Spark Swarm observation digest input',
 );
 
-export const computeSparkSwarmObservationV2Digest = async (
-  observationArg: TSparkSwarmObservationV2,
+export const computeSparkSwarmObservationDigest = async (
+  observationArg: TSparkSwarmObservation,
 ): Promise<TSha256Digest> => (
   `sha256:${await createCanonicalJsonSha256Hex(
-    createSparkSwarmObservationV2DigestInput(observationArg),
-    failSparkSwarmObservationV2Canonicalization,
+    createSparkSwarmObservationDigestInput(observationArg),
+    failSparkSwarmObservationCanonicalization,
   )}` as TSha256Digest
 );
 
 const canonicalSwarmNode = (
-  nodeArg: ISwarmManagerObservedNodeV1,
+  nodeArg: ISwarmManagerObservedNode,
 ): Record<string, unknown> => ({
   swarmNodeId: nodeArg.swarmNodeId,
   nodeName: nodeArg.nodeName,
@@ -369,12 +409,10 @@ const canonicalSwarmNode = (
 
 export const createSwarmManagerSnapshotDigestInput = (
   swarmClusterIdArg: string,
-  snapshotArg: ISwarmManagerSnapshotV1,
+  snapshotArg: ISwarmManagerSnapshot,
 ): 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),
@@ -382,7 +420,7 @@ export const createSwarmManagerSnapshotDigestInput = (
 
 export const computeSwarmManagerSnapshotDigest = async (
   swarmClusterIdArg: string,
-  snapshotArg: ISwarmManagerSnapshotV1,
+  snapshotArg: ISwarmManagerSnapshot,
 ): Promise<TSha256Digest> => computeSha256(
   createSwarmManagerSnapshotDigestInput(swarmClusterIdArg, snapshotArg),
 );
@@ -393,8 +431,7 @@ const validateSwarmManagerSnapshot = async (
   snapshotArg: unknown,
 ): Promise<string[]> => {
   if (!isRuntimeRecord(snapshotArg)
-    || !hasExactRuntimeKeys(snapshotArg, [
-      'snapshotVersion',
+    || !hasExactKeys(snapshotArg, [
       'snapshotDigest',
       'nodeCount',
       'managerCount',
@@ -403,9 +440,6 @@ const validateSwarmManagerSnapshot = async (
     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');
@@ -440,7 +474,7 @@ const validateSwarmManagerSnapshot = async (
       'state',
       ...(isManager ? ['managerStatus'] : []),
     ];
-    if (!hasExactRuntimeKeys(nodeArg, expectedKeys)) {
+    if (!hasExactKeys(nodeArg, expectedKeys)) {
       errors.push(`Spark Swarm manager snapshot nodes[${index}] must use its exact role schema`);
     }
     if (!isRuntimeIdentifier(nodeArg.swarmNodeId) || !isRuntimeIdentifier(nodeArg.nodeName)) {
@@ -457,7 +491,7 @@ const validateSwarmManagerSnapshot = async (
     if (isManager) {
       managerCount++;
       if (!isRuntimeRecord(nodeArg.managerStatus)
-        || !hasExactRuntimeKeys(nodeArg.managerStatus, ['leader', 'reachability'])
+        || !hasExactKeys(nodeArg.managerStatus, ['leader', 'reachability'])
         || typeof nodeArg.managerStatus.leader !== 'boolean'
         || !['unknown', 'unreachable', 'reachable']
           .includes(nodeArg.managerStatus.reachability as string)) {
@@ -504,7 +538,7 @@ const validateSwarmManagerSnapshot = async (
   if (errors.length === 0
     && snapshotArg.snapshotDigest !== await computeSwarmManagerSnapshotDigest(
       swarmClusterIdArg,
-      snapshotArg as unknown as ISwarmManagerSnapshotV1,
+      snapshotArg as unknown as ISwarmManagerSnapshot,
     )) {
     errors.push('Spark Swarm manager snapshot digest does not match');
   }
@@ -518,73 +552,6 @@ export const validateSparkSwarmObservation = async (
     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'];
-  }
-};
-
-export const validateSparkSwarmObservationV2 = async (
-  observationArg: unknown,
-): Promise<string[]> => {
-  try {
-    if (!isRuntimeRecord(observationArg)) return ['Spark Swarm observation v2 must be an object'];
-    const observation = observationArg as Record<string, unknown>;
-    const commonKeys = [
-      'schemaVersion',
       'reporterSessionId',
       'observationSequence',
       'observedAt',
@@ -605,31 +572,28 @@ export const validateSparkSwarmObservationV2 = async (
                 ...(observation.managerSnapshot === undefined ? [] : ['managerSnapshot']),
               ]
             : [];
-    if (expectedKeys.length === 0 || !hasExactRuntimeKeys(observation, expectedKeys)) {
-      return ['Spark Swarm observation v2 must use its exact state schema'];
+    if (expectedKeys.length === 0 || !hasExactKeys(observation, expectedKeys)) {
+      return ['Spark Swarm observation must use its exact state schema'];
     }
     const errors: string[] = [];
-    if (observation.schemaVersion !== 2) {
-      errors.push('Spark Swarm observation v2 schemaVersion must be 2');
-    }
     if (!isRuntimeIdentifier(observation.reporterSessionId)
       || !isPositiveSafeInteger(observation.observationSequence)
       || !isPositiveSafeInteger(observation.observedAt)) {
-      errors.push('Spark Swarm observation v2 identity, sequence, and timestamp must be canonical');
+      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 v2 unknown reason must be canonical');
+      errors.push('Spark Swarm observation unknown reason must be canonical');
     }
     if (observation.state === 'member') {
       if (!isRuntimeIdentifier(observation.localSwarmNodeId)
         || typeof observation.controlAvailable !== 'boolean') {
-        errors.push('Spark Swarm member observation v2 must have canonical local authority');
+        errors.push('Spark Swarm member observation must have canonical local authority');
       }
       if (observation.controlAvailable === true) {
         if (!isRuntimeIdentifier(observation.swarmClusterId)) {
-          errors.push('Spark Swarm manager observation v2 must have canonical cluster authority');
+          errors.push('Spark Swarm manager observation must have canonical cluster authority');
         } else if (observation.managerSnapshot !== undefined
           && isRuntimeIdentifier(observation.localSwarmNodeId)) {
           errors.push(...await validateSwarmManagerSnapshot(
@@ -642,59 +606,62 @@ export const validateSparkSwarmObservationV2 = async (
     }
     return errors;
   } catch {
-    return ['Spark Swarm observation v2 must be safely inspectable'];
+    return ['Spark Swarm observation must be safely inspectable'];
   }
 };
 
-export const validateSparkSwarmObservationV2Request = async (
+export const validateSparkSwarmObservationRequest = async (
   requestArg: unknown,
 ): Promise<string[]> => {
   try {
     if (!isRuntimeRecord(requestArg)
-      || !hasExactRuntimeKeys(requestArg, ['nodeId', 'nodeToken', 'observation'])) {
-      return ['Spark Swarm observation v2 request must use its exact schema'];
+      || !hasExactKeys(requestArg, ['nodeId', 'nodeToken', 'protocol', 'observation'])) {
+      return ['Spark Swarm observation request must use its exact schema'];
     }
     try {
       canonicalizeStrictJson(
         requestArg,
-        failSparkSwarmObservationV2Canonicalization,
-        'Spark Swarm observation v2 request',
+        failSparkSwarmObservationCanonicalization,
+        'Spark Swarm observation request',
       );
     } catch {
-      return ['Spark Swarm observation v2 request must contain strict canonical JSON data'];
+      return ['Spark Swarm observation request must contain strict canonical JSON data'];
     }
-    const errors = await validateSparkSwarmObservationV2(requestArg.observation);
+    const errors = validateProtocolOfferOn(
+      requestArg,
+      'Spark Swarm observation request protocol',
+    );
+    errors.push(...await validateSparkSwarmObservation(requestArg.observation));
     if (!isRuntimeIdentifier(requestArg.nodeId)) {
-      errors.push('Spark Swarm observation v2 request nodeId must be canonical');
+      errors.push('Spark Swarm observation request nodeId must be canonical');
     }
     if (typeof requestArg.nodeToken !== 'string'
       || requestArg.nodeToken.length < 1
       || requestArg.nodeToken.length > 512
       || requestArg.nodeToken.trim() !== requestArg.nodeToken) {
-      errors.push('Spark Swarm observation v2 request nodeToken must be a bounded opaque token');
+      errors.push('Spark Swarm observation request nodeToken must be a bounded opaque token');
     }
     return errors;
   } catch {
-    return ['Spark Swarm observation v2 request must be safely inspectable'];
+    return ['Spark Swarm observation request must be safely inspectable'];
   }
 };
 
-export const validateSparkSwarmObservationV2Response = async (
+export const validateSparkSwarmObservationResponse = async (
   responseArg: unknown,
-  expectedRequestArg: ISparkSwarmObservationV2Request,
+  expectedRequestArg: ISparkSwarmObservationRequest,
 ): Promise<string[]> => {
   try {
-    const requestErrors = await validateSparkSwarmObservationV2Request(
+    const requestErrors = await validateSparkSwarmObservationRequest(
       expectedRequestArg,
     );
     if (requestErrors.length > 0) {
-      return ['expected Spark Swarm observation v2 request must be valid'];
+      return ['expected Spark Swarm observation request must be valid'];
     }
     if (!isRuntimeRecord(responseArg)) {
-      return ['Spark Swarm observation v2 response must be an object'];
+      return ['Spark Swarm observation response must be an object'];
     }
     const acceptedKeys = [
-      'schemaVersion',
       'state',
       'nodeId',
       'reporterSessionId',
@@ -702,9 +669,9 @@ export const validateSparkSwarmObservationV2Response = async (
       'observationDigest',
       'acceptedAt',
       'targetGenerationAtAcceptance',
+      'protocol',
     ];
     const rejectedKeys = [
-      'schemaVersion',
       'state',
       'nodeId',
       'reporterSessionId',
@@ -713,61 +680,71 @@ export const validateSparkSwarmObservationV2Response = async (
       'rejectedAt',
       'code',
       'retryable',
+      'protocol',
     ];
     const expectedKeys = responseArg.state === 'accepted'
       ? acceptedKeys
       : responseArg.state === 'rejected'
         ? rejectedKeys
         : [];
-    if (expectedKeys.length === 0 || !hasExactRuntimeKeys(responseArg, expectedKeys)) {
-      return ['Spark Swarm observation v2 response must use its exact state schema'];
+    if (expectedKeys.length === 0 || !hasExactKeys(responseArg, expectedKeys)) {
+      return ['Spark Swarm observation response must use its exact state schema'];
     }
     try {
       canonicalizeStrictJson(
         responseArg,
-        failSparkSwarmObservationV2Canonicalization,
-        'Spark Swarm observation v2 response',
+        failSparkSwarmObservationCanonicalization,
+        'Spark Swarm observation response',
       );
     } catch {
-      return ['Spark Swarm observation v2 response must contain strict canonical JSON data'];
+      return ['Spark Swarm observation response must contain strict canonical JSON data'];
     }
-    const errors: string[] = [];
-    const observationDigest = await computeSparkSwarmObservationV2Digest(
+    const errors = validateProtocolOfferOn(
+      responseArg,
+      'Spark Swarm observation response protocol',
+    );
+    const observationDigest = await computeSparkSwarmObservationDigest(
       expectedRequestArg.observation,
     );
-    if (responseArg.schemaVersion !== 2
-      || responseArg.nodeId !== expectedRequestArg.nodeId
+    if (responseArg.nodeId !== expectedRequestArg.nodeId
       || responseArg.reporterSessionId !== expectedRequestArg.observation.reporterSessionId
       || responseArg.observationSequence !== expectedRequestArg.observation.observationSequence
       || responseArg.observationDigest !== observationDigest) {
-      errors.push('Spark Swarm observation v2 response must bind the expected request');
+      errors.push('Spark Swarm observation response must bind the expected request');
     }
     if (responseArg.state === 'accepted') {
       if (!isPositiveSafeInteger(responseArg.acceptedAt)
         || !Number.isSafeInteger(responseArg.targetGenerationAtAcceptance)
         || (responseArg.targetGenerationAtAcceptance as number) < 0) {
-        errors.push('Spark Swarm observation v2 accepted receipt fields must be canonical');
+        errors.push('Spark Swarm observation accepted receipt fields must be canonical');
       }
     } else {
-      const retryability = sparkSwarmObservationV2Contract.rejectionRetryability;
+      const retryability = sparkSwarmObservationContract.rejectionRetryability;
       if (!isPositiveSafeInteger(responseArg.rejectedAt)
         || typeof responseArg.code !== 'string'
         || !Object.hasOwn(retryability, responseArg.code)
         || responseArg.retryable !== retryability[
-          responseArg.code as TSparkSwarmObservationV2RejectionCode
+          responseArg.code as TSparkSwarmObservationRejectionCode
         ]) {
-        errors.push('Spark Swarm observation v2 rejected receipt fields must be canonical');
+        errors.push('Spark Swarm observation rejected receipt fields must be canonical');
       }
     }
     return errors;
   } catch {
-    return ['Spark Swarm observation v2 response must be safely inspectable'];
+    return ['Spark Swarm observation response must be safely inspectable'];
   }
 };
 
+/**
+ * The exact five members of a target that the set digest is taken over.
+ *
+ * A projection, not the canonical-JSON rule: it drops anything else a caller's target carries, so
+ * the digest cannot move with a member no peer agreed on. Canonicalizing the target instead would
+ * hash whatever it happens to hold.
+ */
 const canonicalRuntimeTarget = (
-  targetArg: IClusterRuntimeTargetV1,
-): IClusterRuntimeTargetV1 => ({
+  targetArg: IClusterRuntimeTarget,
+): IClusterRuntimeTarget => ({
   cloudlyNodeId: targetArg.cloudlyNodeId,
   swarmClusterId: targetArg.swarmClusterId,
   swarmNodeId: targetArg.swarmNodeId,
@@ -776,9 +753,8 @@ const canonicalRuntimeTarget = (
 });
 
 export const createClusterRuntimeTargetSetDigestInput = (
-  targetSetArg: IClusterRuntimeTargetSetReadyV1,
+  targetSetArg: IClusterRuntimeTargetSetReady,
 ): string => JSON.stringify({
-  schemaVersion: targetSetArg.schemaVersion,
   purpose: 'serve.zone/cluster-runtime-target-set',
   cloudlyClusterId: targetSetArg.cloudlyClusterId,
   swarmClusterId: targetSetArg.swarmClusterId,
@@ -787,7 +763,7 @@ export const createClusterRuntimeTargetSetDigestInput = (
 });
 
 export const computeClusterRuntimeTargetSetDigest = async (
-  targetSetArg: IClusterRuntimeTargetSetReadyV1,
+  targetSetArg: IClusterRuntimeTargetSetReady,
 ): Promise<TSha256Digest> => computeSha256(createClusterRuntimeTargetSetDigestInput(targetSetArg));
 
 export const validateClusterRuntimeTargetSet = async (
@@ -796,8 +772,7 @@ export const validateClusterRuntimeTargetSet = async (
   try {
     if (!isRuntimeRecord(targetSetArg)) return ['cluster runtime target set must be an object'];
     if (targetSetArg.state === 'unavailable') {
-      if (!hasExactRuntimeKeys(targetSetArg, [
-        'schemaVersion',
+      if (!hasExactKeys(targetSetArg, [
         'state',
         'cloudlyClusterId',
         'generation',
@@ -807,8 +782,7 @@ export const validateClusterRuntimeTargetSet = async (
         return ['unavailable cluster runtime target set must use its exact schema'];
       }
       const errors: string[] = [];
-      if (targetSetArg.schemaVersion !== 1
-        || !isRuntimeIdentifier(targetSetArg.cloudlyClusterId)
+      if (!isRuntimeIdentifier(targetSetArg.cloudlyClusterId)
         || !Number.isSafeInteger(targetSetArg.generation)
         || (targetSetArg.generation as number) < 0
         || !isPositiveSafeInteger(targetSetArg.changedAt)
@@ -827,8 +801,7 @@ export const validateClusterRuntimeTargetSet = async (
       return errors;
     }
     if (targetSetArg.state !== 'ready'
-      || !hasExactRuntimeKeys(targetSetArg, [
-        'schemaVersion',
+      || !hasExactKeys(targetSetArg, [
         'state',
         'cloudlyClusterId',
         'swarmClusterId',
@@ -841,8 +814,7 @@ export const validateClusterRuntimeTargetSet = async (
       return ['ready cluster runtime target set must use its exact schema'];
     }
     const errors: string[] = [];
-    if (targetSetArg.schemaVersion !== 1
-      || !isRuntimeIdentifier(targetSetArg.cloudlyClusterId)
+    if (!isRuntimeIdentifier(targetSetArg.cloudlyClusterId)
       || !isRuntimeIdentifier(targetSetArg.swarmClusterId)
       || !isPositiveSafeInteger(targetSetArg.generation)
       || !isPositiveSafeInteger(targetSetArg.acceptedAt)
@@ -864,7 +836,7 @@ export const validateClusterRuntimeTargetSet = async (
     let previousSortKey: string | undefined;
     for (const [index, targetArg] of targetSetArg.targets.entries()) {
       if (!isRuntimeRecord(targetArg)
-        || !hasExactRuntimeKeys(targetArg, [
+        || !hasExactKeys(targetArg, [
           'cloudlyNodeId',
           'swarmClusterId',
           'swarmNodeId',
@@ -899,7 +871,7 @@ export const validateClusterRuntimeTargetSet = async (
     }
     if (errors.length === 0
       && targetSetArg.targetSetDigest !== await computeClusterRuntimeTargetSetDigest(
-        targetSetArg as unknown as IClusterRuntimeTargetSetReadyV1,
+        targetSetArg as unknown as IClusterRuntimeTargetSetReady,
       )) {
       errors.push('cluster runtime target set digest does not match');
     }
@@ -910,9 +882,9 @@ export const validateClusterRuntimeTargetSet = async (
 };
 
 export const isClusterRuntimeTargetSetFresh = (
-  targetSetArg: TClusterRuntimeTargetSetV1,
+  targetSetArg: TClusterRuntimeTargetSet,
   nowArg: number,
-): targetSetArg is IClusterRuntimeTargetSetReadyV1 => (
+): targetSetArg is IClusterRuntimeTargetSetReady => (
   targetSetArg.state === 'ready'
   && Number.isSafeInteger(nowArg)
   && nowArg >= targetSetArg.acceptedAt
@@ -994,7 +966,7 @@ export interface IClusterNode {
     sparkRuntimeInfo?: ISparkNodeRuntimeInfo;
 
     /** Separately accepted Pallet-era host report; never grants workload readiness. */
-    sparkNodeReport?: ISparkNodeReportRecordV2;
+    sparkNodeReport?: ISparkNodeReportRecord;
     
     /**
      * Docker swarm node ID if part of swarm