@serve.zone/interfaces 32.14.0 → 32.15.0

package/ts/data/clusternode.ts

@@ -1,11 +1,24 @@
 import * as plugins from '../plugins.js';
-import type { TSha256Digest, TImmutableContainerPlatform } from './immutableimage.js';
+import { isSha256Digest, type TSha256Digest, type TImmutableContainerPlatform } from './immutableimage.js';
 import type { ISparkNodeReportRecord } from './sparknodereport.js';
 import {
+  fleetCutoverContract,
+  snapshotFleetCutoverPreparedVolumeHandoffAggregate,
+  snapshotFleetCutoverPreparedVolumeHandoffPage,
+  snapshotFleetCutoverPreparedVolumeHandoffIntent,
+  validateFleetCutoverHeldVolumeFenceEvidencePage,
+  validateFleetCutoverPreparedVolumeHandoffAggregate,
+  validateFleetCutoverPreparedVolumeHandoffPage,
+  validateFleetCutoverPreparedVolumeHandoffIntent,
   validateFleetCutoverLocalNodeSnapshot,
   validateFleetCutoverManagerSnapshot,
+  type IFleetCutoverAcceptedEvidenceReference,
+  type IFleetCutoverHeldVolumeFenceEvidencePage,
   type IFleetCutoverLocalNodeSnapshot,
   type IFleetCutoverManagerSnapshot,
+  type IFleetCutoverPreparedVolumeHandoffAggregate,
+  type IFleetCutoverPreparedVolumeHandoffIntent,
+  type IFleetCutoverPreparedVolumeHandoffPage,
 } from './fleetcutover.js';
 import { protocolRefusalHttpStatus, validateProtocolOfferOn, type IProtocolOffer } from '../protocol.js';
 import {
@@ -131,9 +144,15 @@ export const sparkSwarmNodeContracts = Object.freeze({
    */
   swarmObservation: Object.freeze({
     endpoint: '/spark/swarm-nodes/swarm-observation',
-    maxRequestBytes: 4_194_304,
+    maxRequestBytes: 4_325_376,
     maxResponseBytes: 2048,
   } as const),
+  /** Pinned immutable aggregate page plus at most 32 full handoffs for this authenticated node. */
+  fleetCutoverPreparedVolumeHandoffs: Object.freeze({
+    endpoint: '/spark/swarm-nodes/fleet-cutover-prepared-volume-handoffs',
+    maxRequestBytes: 4096,
+    maxResponseBytes: 262_144,
+  } as const),
   protocolRefusalStatus: protocolRefusalHttpStatus,
 } as const);
 
@@ -221,6 +240,8 @@ interface ISparkSwarmObservationBase {
   reporterSessionId: string;
   observationSequence: number;
   observedAt: number;
+  /** Available in every observation state; exact page membership proves an empty node subset. */
+  fleetCutoverHeldVolumeFences?: IFleetCutoverHeldVolumeFenceEvidencePage;
 }
 
 export type TSparkSwarmObservation =
@@ -288,6 +309,32 @@ export interface ISparkSwarmObservationRequest {
   observation: TSparkSwarmObservation;
 }
 
+/** First read may select current with null; all following page reads pin the exact aggregate. */
+export interface ISparkGetFleetCutoverPreparedVolumeHandoffsRequest {
+  nodeId: string;
+  nodeToken: string;
+  protocol: IProtocolOffer;
+  aggregate: IFleetCutoverAcceptedEvidenceReference | null;
+  pageIndex: number;
+}
+
+export type TSparkGetFleetCutoverPreparedVolumeHandoffsResponse =
+  | {
+      aggregate: null;
+      page: null;
+      nodeId: string;
+      nodeHandoffs: [];
+      protocol: IProtocolOffer;
+    }
+  | {
+      aggregate: IFleetCutoverPreparedVolumeHandoffAggregate;
+      page: IFleetCutoverPreparedVolumeHandoffPage;
+      nodeId: string;
+      /** Exact complete authenticated-node subset committed by this page; may be empty. */
+      nodeHandoffs: IFleetCutoverPreparedVolumeHandoffIntent[];
+      protocol: IProtocolOffer;
+    };
+
 export interface ISparkSwarmObservationAcceptedReceipt {
   state: 'accepted';
   nodeId: string;
@@ -579,6 +626,8 @@ export const validateSparkSwarmObservation = async (
       'observationSequence',
       'observedAt',
       'state',
+      ...(observation.fleetCutoverHeldVolumeFences === undefined
+        ? [] : ['fleetCutoverHeldVolumeFences']),
     ];
     const expectedKeys = observation.state === 'unknown'
       ? [...commonKeys, 'reason']
@@ -619,6 +668,14 @@ export const validateSparkSwarmObservation = async (
         .includes(observation.reason as string)) {
       errors.push('Spark Swarm observation unknown reason must be canonical');
     }
+    if (observation.fleetCutoverHeldVolumeFences !== undefined) {
+      const evidenceErrors = await validateFleetCutoverHeldVolumeFenceEvidencePage(
+        observation.fleetCutoverHeldVolumeFences,
+      );
+      errors.push(...evidenceErrors.map(
+        errorArg => `Spark Swarm observation ${errorArg}`,
+      ));
+    }
     if (observation.state === 'member') {
       if (!isRuntimeIdentifier(observation.localSwarmNodeId)
         || typeof observation.controlAvailable !== 'boolean') {
@@ -694,6 +751,151 @@ const validateSparkReporterIdentity = (
   return errors;
 };
 
+const readFleetCutoverEvidenceReference = (
+  valueArg: unknown,
+): IFleetCutoverAcceptedEvidenceReference | null => {
+  if (valueArg === null) return null;
+  if (!isRuntimeRecord(valueArg)
+    || !hasExactKeys(valueArg, ['id', 'generation', 'digest'])
+    || !isRuntimeIdentifier(valueArg.id)
+    || !isPositiveSafeInteger(valueArg.generation)
+    || typeof valueArg.digest !== 'string'
+    || !isSha256Digest(valueArg.digest)) return null;
+  return {
+    id: valueArg.id,
+    generation: valueArg.generation,
+    digest: valueArg.digest,
+  };
+};
+
+export const validateSparkGetFleetCutoverPreparedVolumeHandoffsRequest = (
+  requestArg: unknown,
+): string[] => {
+  try {
+    if (!isRuntimeRecord(requestArg)
+      || !hasExactKeys(requestArg, [
+        'nodeId', 'nodeToken', 'protocol', 'aggregate', 'pageIndex',
+      ])) {
+      return ['Spark prepared volume handoff request must use its exact schema'];
+    }
+    canonicalizeStrictJson(
+      requestArg,
+      failSparkSwarmObservationCanonicalization,
+      'Spark prepared volume handoff request',
+    );
+    const errors = validateProtocolOfferOn(
+      requestArg,
+      'Spark prepared volume handoff request protocol',
+    );
+    errors.push(...validateSparkReporterIdentity(
+      requestArg,
+      'Spark prepared volume handoff request',
+    ));
+    if ((requestArg.aggregate !== null
+      && readFleetCutoverEvidenceReference(requestArg.aggregate) === null)
+      || typeof requestArg.pageIndex !== 'number'
+      || !Number.isSafeInteger(requestArg.pageIndex)
+      || requestArg.pageIndex < 0
+      || requestArg.pageIndex >= fleetCutoverContract.maximumPreparedVolumeHandoffPages) {
+      errors.push('Spark prepared volume handoff request pin must be canonical');
+    }
+    return errors;
+  } catch {
+    return ['Spark prepared volume handoff request must be safely inspectable'];
+  }
+};
+
+export const validateSparkGetFleetCutoverPreparedVolumeHandoffsResponse = async (
+  responseArg: unknown,
+  requestArg: ISparkGetFleetCutoverPreparedVolumeHandoffsRequest,
+): Promise<string[]> => {
+  try {
+    if (validateSparkGetFleetCutoverPreparedVolumeHandoffsRequest(requestArg).length) {
+      return ['expected Spark prepared volume handoff request must be valid'];
+    }
+    if (!isRuntimeRecord(responseArg)
+      || !hasExactKeys(responseArg, [
+        'aggregate', 'page', 'nodeId', 'nodeHandoffs', 'protocol',
+      ])) {
+      return ['Spark prepared volume handoff response must use its exact schema'];
+    }
+    const canonical = canonicalizeStrictJson(
+      responseArg,
+      failSparkSwarmObservationCanonicalization,
+      'Spark prepared volume handoff response',
+    );
+    const errors = validateProtocolOfferOn(
+      responseArg,
+      'Spark prepared volume handoff response protocol',
+    );
+    if (new TextEncoder().encode(canonical).byteLength
+      > sparkSwarmNodeContracts.fleetCutoverPreparedVolumeHandoffs.maxResponseBytes) {
+      errors.push('Spark prepared volume handoff response exceeds its encoded byte bound');
+    }
+    if (responseArg.nodeId !== requestArg.nodeId) {
+      errors.push('Spark prepared volume handoff response must name the authenticated node');
+    }
+    if (responseArg.aggregate === null) {
+      if (requestArg.aggregate !== null || responseArg.page !== null
+        || !Array.isArray(responseArg.nodeHandoffs)
+        || responseArg.nodeHandoffs.length !== 0) {
+        errors.push('Spark empty prepared volume handoff response must be canonical');
+      }
+      return errors;
+    }
+    const aggregate = snapshotFleetCutoverPreparedVolumeHandoffAggregate(responseArg.aggregate);
+    const page = snapshotFleetCutoverPreparedVolumeHandoffPage(responseArg.page);
+    if ((await validateFleetCutoverPreparedVolumeHandoffAggregate(aggregate)).length
+      || aggregate.state !== 'complete') {
+      errors.push('Spark prepared volume handoff response aggregate must be complete and valid');
+    }
+    if ((await validateFleetCutoverPreparedVolumeHandoffPage(page)).length) {
+      errors.push('Spark prepared volume handoff response page must be valid');
+    }
+    if (requestArg.aggregate !== null
+      && (requestArg.aggregate.id !== aggregate.id
+        || requestArg.aggregate.generation !== aggregate.generation
+        || requestArg.aggregate.digest !== aggregate.digest)) {
+      errors.push('Spark prepared volume handoff response must preserve the aggregate pin');
+    }
+    if (page.aggregate.id !== aggregate.id
+      || page.aggregate.generation !== aggregate.generation
+      || page.aggregate.digest !== aggregate.digest
+      || page.pageIndex !== requestArg.pageIndex
+      || page.pageIndex >= aggregate.pageCount) {
+      errors.push('Spark prepared volume handoff response page must bind the requested aggregate page');
+    }
+    if (!Array.isArray(responseArg.nodeHandoffs)
+      || responseArg.nodeHandoffs.length
+        > fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries) {
+      errors.push('Spark prepared volume handoff response node subset must be bounded');
+      return errors;
+    }
+    const expectedNodeHandoffs = page.handoffs.filter(
+      referenceArg => referenceArg.nodeId === requestArg.nodeId,
+    );
+    if (responseArg.nodeHandoffs.length !== expectedNodeHandoffs.length) {
+      errors.push('Spark prepared volume handoff response must include the complete node subset');
+      return errors;
+    }
+    for (const [index, handoffArg] of responseArg.nodeHandoffs.entries()) {
+      const handoff = snapshotFleetCutoverPreparedVolumeHandoffIntent(handoffArg);
+      const expected = expectedNodeHandoffs[index];
+      if ((await validateFleetCutoverPreparedVolumeHandoffIntent(handoff)).length
+        || handoff.nodeId !== requestArg.nodeId
+        || handoff.id !== expected.id
+        || handoff.generation !== expected.generation
+        || handoff.digest !== expected.digest) {
+        errors.push('Spark prepared volume handoff response node subset must exactly match page order and authority');
+        break;
+      }
+    }
+    return errors;
+  } catch {
+    return ['Spark prepared volume handoff response must be safely inspectable'];
+  }
+};
+
 export const validateSparkSwarmObservationRequest = async (
   requestArg: unknown,
 ): Promise<string[]> => {
@@ -720,6 +922,11 @@ export const validateSparkSwarmObservationRequest = async (
       requestArg,
       'Spark Swarm observation request',
     ));
+    if (isRuntimeRecord(requestArg.observation)
+      && isRuntimeRecord(requestArg.observation.fleetCutoverHeldVolumeFences)
+      && requestArg.observation.fleetCutoverHeldVolumeFences.nodeId !== requestArg.nodeId) {
+      errors.push('Spark Swarm held volume fence evidence must name the authenticated node');
+    }
     return errors;
   } catch {
     return ['Spark Swarm observation request must be safely inspectable'];