@serve.zone/interfaces 32.15.0 → 32.17.0

package/ts/data/fleetcutover.ts

@@ -19,6 +19,7 @@ import { normalizeStorageRequest } from '../platform/storage.js';
 import type { ISecretVersionReference } from './secret.js';
 import {
   canonicalizeStrictJson,
+  compareWireTokens,
   createCanonicalJsonSha256Hex,
 } from '../private/canonicaljson.js';
 import {
@@ -82,6 +83,37 @@ export interface IFleetCutoverMountTargetIdentityInput {
   target: string;
 }
 
+export interface IFleetCutoverDockerMountInput {
+  /** Raw Docker mount type. Unsupported values produce an explicit unknown descriptor. */
+  type: string;
+  /** Exact source bytes from the Docker object being described; never substitute another field. */
+  source: string;
+  /** Exact container target bytes from the Docker object being described. */
+  target: string;
+  readOnly: boolean;
+}
+
+/**
+ * Value-free correlation between one local physical mount and its service-spec mount identity.
+ * The two identities stay distinct: a Docker volume's local Source is a host path while its
+ * service Source and local Name are the logical volume name.
+ */
+export interface IFleetCutoverPhysicalMountCorrelation {
+  physicalMountIdentityDigest: TSha256Digest;
+  serviceMountIdentityDigest: TSha256Digest;
+  correlationIdentityDigest: TSha256Digest;
+}
+
+export interface IFleetCutoverPhysicalMountEvidence {
+  mount: IFleetCutoverMountDescriptor;
+  correlation: IFleetCutoverPhysicalMountCorrelation;
+}
+
+export interface IFleetCutoverDockerConstraintSetIdentity {
+  constraintCount: number;
+  constraintSetDigest: TSha256Digest;
+}
+
 export type TFleetCutoverDockerTaskState =
   | 'new'
   | 'allocated'
@@ -148,6 +180,11 @@ export interface IFleetCutoverPhysicalContainer {
   imageId: TSha256Digest;
   serviceIdLabel: string | null;
   mounts: IFleetCutoverMountDescriptor[];
+  /**
+   * Optional only for compatibility with observations predating correlation evidence. When
+   * present it is a complete one-to-one mapping of mounts. Absence establishes no mount join.
+   */
+  mountCorrelations?: IFleetCutoverPhysicalMountCorrelation[];
 }
 
 export interface IFleetCutoverContainerSetIdentity {
@@ -636,6 +673,9 @@ export const fleetCutoverContract = Object.freeze({
   maximumNodes: 1024,
   maximumContainersPerNode: 512,
   maximumMountsPerOwner: 32,
+  maximumConstraintsPerService: 256,
+  maximumDockerTextBytes: 4096,
+  maximumDockerServiceSpecCanonicalBytes: 1_048_576,
   maximumPreparedVolumeHandoffMutationEntries: 32,
   /** Every admitted task has one node placement and at most 32 mounts: 4096 * 32. */
   maximumPreparedVolumeHandoffs: 4096 * 32,
@@ -646,6 +686,9 @@ export const fleetCutoverContract = Object.freeze({
   mountSourceIdentityDigestDomain: 'serve.zone/fleet-cutover-mount-source-identity',
   mountTargetIdentityDigestDomain: 'serve.zone/fleet-cutover-mount-target-identity',
   mountIdentityDigestDomain: 'serve.zone/fleet-cutover-mount-identity',
+  mountCorrelationIdentityDigestDomain: 'serve.zone/fleet-cutover-mount-correlation-identity',
+  dockerServiceSpecDigestDomain: 'serve.zone/fleet-cutover-docker-service-spec',
+  dockerConstraintSetDigestDomain: 'serve.zone/fleet-cutover-docker-constraint-set',
   containerSetIdentityDigestDomain: 'serve.zone/fleet-cutover-container-set-identity',
   localNodeSnapshotDigestDomain: 'serve.zone/fleet-cutover-local-node-snapshot',
   managerSnapshotDigestDomain: 'serve.zone/fleet-cutover-manager-snapshot',
@@ -673,6 +716,11 @@ export const fleetCutoverContract = Object.freeze({
   } satisfies Record<TClusterRuntimePhase, TClusterRuntimePhase | null>),
 } as const);
 
+/** Docker labels with established historical producer semantics. */
+export const fleetCutoverDockerLabelNames = Object.freeze({
+  serviceId: 'serve.zone.serviceId',
+} as const);
+
 const fail = (): never => { throw new Error('Fleet cutover contract rejected.'); };
 const safe = <T>(operationArg: () => T): T => {
   try { return operationArg(); } catch { return fail(); }
@@ -764,6 +812,28 @@ const sortedMountDescriptors = (valueArg: unknown): IFleetCutoverMountDescriptor
   networkList(valueArg, fleetCutoverContract.maximumMountsPerOwner, mountDescriptor),
   itemArg => itemArg.mountIdentityDigest,
 );
+const physicalMountCorrelation = (
+  valueArg: unknown,
+): IFleetCutoverPhysicalMountCorrelation => {
+  const value = networkRecord(valueArg, [
+    'physicalMountIdentityDigest', 'serviceMountIdentityDigest', 'correlationIdentityDigest',
+  ]);
+  return {
+    physicalMountIdentityDigest: networkDigest(value.physicalMountIdentityDigest),
+    serviceMountIdentityDigest: networkDigest(value.serviceMountIdentityDigest),
+    correlationIdentityDigest: networkDigest(value.correlationIdentityDigest),
+  };
+};
+const sortedPhysicalMountCorrelations = (
+  valueArg: unknown,
+): IFleetCutoverPhysicalMountCorrelation[] => networkSorted(
+  networkList(
+    valueArg,
+    fleetCutoverContract.maximumMountsPerOwner,
+    physicalMountCorrelation,
+  ),
+  itemArg => itemArg.physicalMountIdentityDigest,
+);
 const dockerMode = (valueArg: unknown): TFleetCutoverDockerServiceMode => {
   requireNetwork(valueArg !== null && typeof valueArg === 'object');
   const kind = (valueArg as Record<string, unknown>).kind;
@@ -788,6 +858,8 @@ const dockerService = (valueArg: unknown): IFleetCutoverDockerService => {
     'dockerServiceId', 'dockerServiceName', 'specVersion', 'specDigest', 'imageDigest', 'mode',
     'desiredTaskCount', 'constraintCount', 'constraintSetDigest', 'mounts', 'ownershipLabels',
   ]);
+  const constraintCount = nonNegative(value.constraintCount);
+  requireNetwork(constraintCount <= fleetCutoverContract.maximumConstraintsPerService);
   return {
     dockerServiceId: networkId(value.dockerServiceId),
     dockerServiceName: networkId(value.dockerServiceName),
@@ -796,7 +868,7 @@ const dockerService = (valueArg: unknown): IFleetCutoverDockerService => {
     imageDigest: networkDigest(value.imageDigest),
     mode: dockerMode(value.mode),
     desiredTaskCount: nonNegative(value.desiredTaskCount),
-    constraintCount: nonNegative(value.constraintCount),
+    constraintCount,
     constraintSetDigest: networkDigest(value.constraintSetDigest),
     mounts: sortedMountDescriptors(value.mounts),
     ownershipLabels: ownershipLabels(value.ownershipLabels),
@@ -833,8 +905,8 @@ const dockerTask = (valueArg: unknown): IFleetCutoverDockerTask => {
 const physicalContainer = (valueArg: unknown): IFleetCutoverPhysicalContainer => {
   const value = networkRecord(valueArg, [
     'dockerContainerId', 'dockerServiceId', 'dockerTaskId', 'imageId', 'serviceIdLabel', 'mounts',
-  ]);
-  return {
+  ], ['mountCorrelations']);
+  const result: IFleetCutoverPhysicalContainer = {
     dockerContainerId: networkId(value.dockerContainerId),
     dockerServiceId: value.dockerServiceId === null ? null : networkId(value.dockerServiceId),
     dockerTaskId: value.dockerTaskId === null ? null : networkId(value.dockerTaskId),
@@ -842,6 +914,10 @@ const physicalContainer = (valueArg: unknown): IFleetCutoverPhysicalContainer =>
     serviceIdLabel: value.serviceIdLabel === null ? null : networkId(value.serviceIdLabel),
     mounts: sortedMountDescriptors(value.mounts),
   };
+  if (Object.hasOwn(value, 'mountCorrelations')) {
+    result.mountCorrelations = sortedPhysicalMountCorrelations(value.mountCorrelations);
+  }
+  return result;
 };
 const inventory = (valueArg: unknown): IFleetCutoverDockerInventory => {
   const value = networkRecord(valueArg, [
@@ -925,11 +1001,17 @@ const canonicalDigest = async (domainArg: string, valueArg: object): Promise<TSh
 
 const exactDockerText = (valueArg: unknown, allowEmptyArg: boolean): string => {
   requireNetwork(typeof valueArg === 'string'
-    && new TextEncoder().encode(valueArg).length <= 4096
+    && new TextEncoder().encode(valueArg).length <= fleetCutoverContract.maximumDockerTextBytes
     && (allowEmptyArg || valueArg.length > 0));
   return valueArg;
 };
 
+const openDockerRecord = (valueArg: unknown): Record<string, unknown> => {
+  const value = captureNetwork(valueArg);
+  requireNetwork(value !== null && typeof value === 'object' && !Array.isArray(value));
+  return value as Record<string, unknown>;
+};
+
 const computeExactIdentityDigest = async (
   domainArg: string,
   inputArg: object,
@@ -938,6 +1020,160 @@ const computeExactIdentityDigest = async (
   input: inputArg,
 }, fail), fail)}`;
 
+/**
+ * Hash the complete open-schema Docker Service.Spec object. Unknown response properties are
+ * intentionally included: this helper returns only the digest and never a retained projection.
+ */
+export const computeFleetCutoverDockerServiceSpecDigest = async (
+  valueArg: unknown,
+): Promise<TSha256Digest> => {
+  try {
+    const spec = openDockerRecord(valueArg);
+    const canonicalSpec = canonicalizeStrictJson(spec, fail, 'Docker Service.Spec');
+    requireNetwork(new TextEncoder().encode(canonicalSpec).byteLength
+      <= fleetCutoverContract.maximumDockerServiceSpecCanonicalBytes);
+    return await computeExactIdentityDigest(
+      fleetCutoverContract.dockerServiceSpecDigestDomain,
+      { spec },
+    );
+  } catch {
+    return fail();
+  }
+};
+
+/** Sort exact constraint strings while preserving duplicate entries, then return value-free identity. */
+export const computeFleetCutoverDockerConstraintSetIdentity = async (
+  valueArg: unknown,
+): Promise<IFleetCutoverDockerConstraintSetIdentity> => {
+  try {
+    const captured = captureNetwork(valueArg);
+    requireNetwork(Array.isArray(captured)
+      && captured.length <= fleetCutoverContract.maximumConstraintsPerService);
+    const constraints = captured.map(itemArg => exactDockerText(itemArg, false))
+      .sort(compareWireTokens);
+    return {
+      constraintCount: constraints.length,
+      constraintSetDigest: await computeExactIdentityDigest(
+        fleetCutoverContract.dockerConstraintSetDigestDomain,
+        { constraints },
+      ),
+    };
+  } catch {
+    return fail();
+  }
+};
+
+export const snapshotFleetCutoverDockerDesiredTaskCount = (valueArg: unknown): number =>
+  safe(() => nonNegative(valueArg));
+
+export const validateFleetCutoverDockerDesiredTaskCount = (valueArg: unknown): string[] => (
+  typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg >= 0
+    ? []
+    : ['Docker ServiceStatus.DesiredTasks must be a non-negative safe integer']
+);
+
+/** Apply only the documented exact cutover mount classifications; no path normalization occurs. */
+export const classifyFleetCutoverDockerMount = (
+  valueArg: IFleetCutoverDockerMountInput,
+): Pick<IFleetCutoverMountDescriptor, 'type' | 'classification'> => safe(() => {
+  const value = networkRecord(valueArg, ['type', 'source', 'target', 'readOnly']);
+  const rawType = exactDockerText(value.type, false);
+  const source = exactDockerText(value.source, true);
+  const target = exactDockerText(value.target, false);
+  requireNetwork(typeof value.readOnly === 'boolean');
+  if (rawType === 'volume') return { type: 'volume', classification: 'persistent-volume' };
+  if (rawType === 'tmpfs') return { type: 'tmpfs', classification: 'tmpfs' };
+  if (rawType !== 'bind') return { type: 'unknown', classification: 'unknown' };
+  if (source === '/var/run/docker.sock'
+    && target === '/var/run/docker.sock'
+    && value.readOnly === false) {
+    return { type: 'bind', classification: 'docker-socket' };
+  }
+  if (source === '/sys/fs/cgroup'
+    && target === '/host/cgroup'
+    && value.readOnly === true) {
+    return { type: 'bind', classification: 'cgroup' };
+  }
+  return { type: 'bind', classification: 'bind' };
+});
+
+export const createFleetCutoverMountDescriptor = async (
+  valueArg: IFleetCutoverDockerMountInput,
+): Promise<IFleetCutoverMountDescriptor> => {
+  try {
+    const value = networkRecord(valueArg, ['type', 'source', 'target', 'readOnly']);
+    const source = exactDockerText(value.source, true);
+    const target = exactDockerText(value.target, false);
+    requireNetwork(typeof value.readOnly === 'boolean');
+    const shape = classifyFleetCutoverDockerMount({
+      type: exactDockerText(value.type, false),
+      source,
+      target,
+      readOnly: value.readOnly,
+    });
+    requireNetwork(shape.type === 'tmpfs' ? source.length === 0 : source.length > 0);
+    const identityInput: Omit<IFleetCutoverMountDescriptor, 'mountIdentityDigest'> = {
+      ...shape,
+      sourceIdentityDigest: await computeFleetCutoverMountSourceIdentityDigest({
+        type: shape.type,
+        source,
+      }),
+      targetIdentityDigest: await computeFleetCutoverMountTargetIdentityDigest({ target }),
+      readOnly: value.readOnly,
+    };
+    return {
+      ...identityInput,
+      mountIdentityDigest: await computeFleetCutoverMountIdentityDigest(identityInput),
+    };
+  } catch {
+    return fail();
+  }
+};
+
+const dockerServiceMountInput = (valueArg: unknown): IFleetCutoverDockerMountInput => {
+  const value = openDockerRecord(valueArg);
+  const type = exactDockerText(value.Type, false);
+  const source = value.Source === undefined ? '' : exactDockerText(value.Source, true);
+  const target = exactDockerText(value.Target, false);
+  const readOnly = value.ReadOnly === undefined ? false : value.ReadOnly;
+  requireNetwork(typeof readOnly === 'boolean');
+  return { type, source, target, readOnly };
+};
+
+interface IFleetCutoverDockerLocalMountInput {
+  descriptorInput: IFleetCutoverDockerMountInput;
+  logicalSource: string;
+}
+
+const dockerLocalMountInput = (valueArg: unknown): IFleetCutoverDockerLocalMountInput => {
+  const value = openDockerRecord(valueArg);
+  const type = exactDockerText(value.Type, false);
+  const source = exactDockerText(value.Source, true);
+  const target = exactDockerText(value.Destination, false);
+  requireNetwork(typeof value.RW === 'boolean');
+  const logicalSource = type === 'volume'
+    ? exactDockerText(value.Name, false)
+    : source;
+  return {
+    descriptorInput: { type, source, target, readOnly: !value.RW },
+    logicalSource,
+  };
+};
+
+/** Read only consumed Service.Spec Mount fields; future Docker response properties are ignored. */
+export const createFleetCutoverDockerServiceMountDescriptor = async (
+  valueArg: unknown,
+): Promise<IFleetCutoverMountDescriptor> => createFleetCutoverMountDescriptor(
+  dockerServiceMountInput(valueArg),
+);
+
+/** Read only consumed local MountPoint fields and retain the exact physical Source identity. */
+export const createFleetCutoverDockerLocalMountDescriptor = async (
+  valueArg: unknown,
+): Promise<IFleetCutoverMountDescriptor> => createFleetCutoverMountDescriptor(
+  dockerLocalMountInput(valueArg).descriptorInput,
+);
+
 export const computeFleetCutoverMountSourceIdentityDigest = async (
   valueArg: IFleetCutoverMountSourceIdentityInput,
 ): Promise<TSha256Digest> => safe(async () => {
@@ -973,6 +1209,54 @@ export const computeFleetCutoverMountIdentityDigest = async (
   });
 });
 
+export const computeFleetCutoverMountCorrelationIdentityDigest = async (
+  valueArg: Omit<IFleetCutoverPhysicalMountCorrelation, 'correlationIdentityDigest'>,
+): Promise<TSha256Digest> => safe(async () => {
+  const value = networkRecord(valueArg, [
+    'physicalMountIdentityDigest', 'serviceMountIdentityDigest',
+  ]);
+  return computeExactIdentityDigest(fleetCutoverContract.mountCorrelationIdentityDigestDomain, {
+    physicalMountIdentityDigest: networkDigest(value.physicalMountIdentityDigest),
+    serviceMountIdentityDigest: networkDigest(value.serviceMountIdentityDigest),
+  });
+});
+
+/**
+ * Produce both the exact local physical descriptor and its logical service-mount correlation.
+ * For a volume only MountPoint.Name supplies the logical source. Unknown types and a missing or
+ * empty volume Name are refused because they cannot establish a truthful service join.
+ */
+export const createFleetCutoverDockerPhysicalMountEvidence = async (
+  valueArg: unknown,
+): Promise<IFleetCutoverPhysicalMountEvidence> => {
+  try {
+    const value = dockerLocalMountInput(valueArg);
+    requireNetwork(['volume', 'bind', 'tmpfs'].includes(value.descriptorInput.type));
+    const mount = await createFleetCutoverMountDescriptor(value.descriptorInput);
+    const serviceMount = await createFleetCutoverMountDescriptor({
+      ...value.descriptorInput,
+      source: value.logicalSource,
+    });
+    const correlationInput: Omit<
+      IFleetCutoverPhysicalMountCorrelation,
+      'correlationIdentityDigest'
+    > = {
+      physicalMountIdentityDigest: mount.mountIdentityDigest,
+      serviceMountIdentityDigest: serviceMount.mountIdentityDigest,
+    };
+    return {
+      mount,
+      correlation: {
+        ...correlationInput,
+        correlationIdentityDigest:
+          await computeFleetCutoverMountCorrelationIdentityDigest(correlationInput),
+      },
+    };
+  } catch {
+    return fail();
+  }
+};
+
 const validateMountDescriptors = async (
   mountsArg: IFleetCutoverMountDescriptor[],
 ): Promise<void> => {
@@ -982,6 +1266,28 @@ const validateMountDescriptors = async (
   }
 };
 
+const validatePhysicalMountCorrelations = async (
+  containerArg: IFleetCutoverPhysicalContainer,
+): Promise<void> => {
+  if (containerArg.mountCorrelations === undefined) return;
+  requireNetwork(containerArg.mountCorrelations.length === containerArg.mounts.length);
+  const physicalMountIdentities = new Set(
+    containerArg.mounts.map(itemArg => itemArg.mountIdentityDigest),
+  );
+  const serviceMountIdentities = new Set(
+    containerArg.mountCorrelations.map(itemArg => itemArg.serviceMountIdentityDigest),
+  );
+  requireNetwork(physicalMountIdentities.size === containerArg.mounts.length
+    && serviceMountIdentities.size === containerArg.mountCorrelations.length
+    && containerArg.mountCorrelations.every(itemArg =>
+      physicalMountIdentities.has(itemArg.physicalMountIdentityDigest)));
+  for (const correlation of containerArg.mountCorrelations) {
+    const { correlationIdentityDigest, ...input } = correlation;
+    requireNetwork(correlationIdentityDigest
+      === await computeFleetCutoverMountCorrelationIdentityDigest(input));
+  }
+};
+
 export const computeFleetCutoverContainerSetIdentityDigest = async (
   containerIdsArg: string[],
 ): Promise<TSha256Digest> => safe(async () => {
@@ -1046,7 +1352,10 @@ export const validateFleetCutoverLocalNodeSnapshot = async (
     );
     requireNetwork(value.before.containerIdsDigest === containerIdsDigest
       && value.after.containerIdsDigest === containerIdsDigest);
-    for (const container of value.containers) await validateMountDescriptors(container.mounts);
+    for (const container of value.containers) {
+      await validateMountDescriptors(container.mounts);
+      await validatePhysicalMountCorrelations(container);
+    }
     return value.snapshotDigest === await computeFleetCutoverLocalNodeSnapshotDigest(value)
       ? [] : ['fleet cutover local node snapshot digest does not match'];
   } catch {

package/ts/data/index.ts

@@ -3,6 +3,7 @@ export * from './cluster.js';
 export * from './clusterruntime.js';
 export * from './clustervpn.js';
 export * from './clusteringress.js';
+export * from './clusterrelaycredential.js';
 export * from './config.js';
 export * from './corestore.js';
 export * from './coremail.js';
@@ -52,6 +53,7 @@ export * from './baseos.js';
 export * from './backup.js';
 export * from './clusternode.js';
 export * from './settings.js';
+export * from './sparklegacyretirement.js';
 export * from './sparknodereport.js';
 export * from './service.js';
 export * from './servicecredential.js';