@serve.zone/interfaces 32.14.0 → 32.16.0

package/ts/data/fleetcutover.ts

@@ -6,9 +6,20 @@ import type {
   IRuntimeAuthorityReference,
 } from './runtimeassignment.js';
 import type { IRuntimeSessionBinding } from './runtimesession.js';
+import type { IRuntimeStorageClaim, IRuntimeStorageClaimIntent } from './runtimestorageclaim.js';
+import {
+  bindRuntimeStorageClaimToIntent,
+  snapshotRuntimeStorageClaim,
+  snapshotRuntimeStorageClaimIntent,
+  validateRuntimeStorageClaim,
+  validateRuntimeStorageClaimIntent,
+} from './runtimestorageclaim.js';
+import type { IAppStoreFilesystemStorageRequest } from '../appstore/types.js';
+import { normalizeStorageRequest } from '../platform/storage.js';
 import type { ISecretVersionReference } from './secret.js';
 import {
   canonicalizeStrictJson,
+  compareWireTokens,
   createCanonicalJsonSha256Hex,
 } from '../private/canonicaljson.js';
 import {
@@ -72,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'
@@ -138,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 {
@@ -281,6 +328,101 @@ export interface IFleetCutoverVolumeHandoffIntent {
   digest: TSha256Digest;
 }
 
+export interface IFleetCutoverPersistentVolumeMountDescriptor
+extends IFleetCutoverMountDescriptor {
+  type: 'volume';
+  classification: 'persistent-volume';
+  readOnly: false;
+}
+
+/**
+ * Cloudly-owned desired handoff prepared from authenticated legacy observations. Observed Docker
+ * source identity is not physical storage lineage; Corestore proves lineage later under the held
+ * native attachment fence.
+ */
+export interface IFleetCutoverPreparedVolumeHandoffIntent {
+  id: string;
+  generation: number;
+  clusterId: string;
+  nodeId: string;
+  serviceId: string;
+  volumeId: string;
+  observedMount: IFleetCutoverPersistentVolumeMountDescriptor;
+  claimIntent: IRuntimeStorageClaimIntent;
+  runtime: IClusterRuntimeReference & { phase: 'draining' };
+  scope: IFleetCutoverAcceptedEvidenceReference;
+  targetSet: IFleetCutoverTargetSetReference;
+  legacyStorageEvidence: IFleetCutoverAcceptedEvidenceReference;
+  sourceNodeObservation: IFleetCutoverAcceptedEvidenceReference;
+  acceptedAt: number;
+  digest: TSha256Digest;
+}
+
+export interface IFleetCutoverPreparedVolumeHandoffUpsert {
+  nodeId: string;
+  serviceId: string;
+  mountIdentityDigest: TSha256Digest;
+  request: IAppStoreFilesystemStorageRequest & {
+    accessMode: 'ReadWriteOnce';
+    reclaimPolicy: 'retain';
+  };
+}
+
+/** One bounded CAS mutation; the durable aggregate may contain many such 32-entry batches. */
+export interface IFleetCutoverPreparedVolumeHandoffMutation {
+  mutationId: string;
+  clusterId: string;
+  currentRuntime: IClusterRuntimeReference & { phase: 'draining' };
+  scope: IFleetCutoverAcceptedEvidenceReference;
+  targetSet: IFleetCutoverTargetSetReference;
+  expectedAggregate: IFleetCutoverAcceptedEvidenceReference | null;
+  upserts: IFleetCutoverPreparedVolumeHandoffUpsert[];
+  removals: IFleetCutoverAcceptedEvidenceReference[];
+}
+
+/**
+ * Revisioned header for one complete expected set. It intentionally contains no page references:
+ * immutable pages bind back to this exact revision, avoiding an aggregate/page digest cycle.
+ */
+export interface IFleetCutoverPreparedVolumeHandoffAggregate {
+  id: string;
+  generation: number;
+  previous: IFleetCutoverAcceptedEvidenceReference | null;
+  clusterId: string;
+  runtime: IClusterRuntimeReference & { phase: 'draining' };
+  scope: IFleetCutoverAcceptedEvidenceReference;
+  targetSet: IFleetCutoverTargetSetReference;
+  state: 'incomplete' | 'complete';
+  requiredHandoffCount: number;
+  handoffCount: number;
+  pageCount: number;
+  handoffSetDigest: TSha256Digest;
+  acceptedAt: number;
+  digest: TSha256Digest;
+}
+
+/** One immutable 1..32-entry page pinned to one aggregate revision. */
+export interface IFleetCutoverPreparedVolumeHandoffPage {
+  id: string;
+  generation: 1;
+  aggregate: IFleetCutoverAcceptedEvidenceReference;
+  pageIndex: number;
+  handoffs: IFleetCutoverPreparedVolumeHandoffPageReference[];
+  handoffSetPageDigest: TSha256Digest;
+  digest: TSha256Digest;
+}
+
+/** Immutable page membership commits both the handoff revision and its owning physical node. */
+export interface IFleetCutoverPreparedVolumeHandoffPageReference
+extends IFleetCutoverAcceptedEvidenceReference {
+  nodeId: string;
+}
+
+export interface IFleetCutoverPreparedVolumeHandoffPageSetEntry {
+  pageIndex: number;
+  handoffSetPageDigest: TSha256Digest;
+}
+
 interface IFleetCutoverVolumeFenceBase {
   id: string;
   generation: number;
@@ -328,6 +470,40 @@ export interface IFleetCutoverCorestoreAdoptionReceipt {
   digest: TSha256Digest;
 }
 
+/** Current-session Cloudly grant for one post-Pallet adoption attempt. */
+export interface IFleetCutoverStorageAdoptionGrant {
+  id: string;
+  generation: number;
+  previous: IFleetCutoverAcceptedEvidenceReference | null;
+  clusterId: string;
+  nodeId: string;
+  serviceId: string;
+  volumeId: string;
+  observedMount: IFleetCutoverPersistentVolumeMountDescriptor;
+  runtime: IClusterRuntimeReference & { phase: 'pallet' };
+  session: IRuntimeSessionBinding;
+  handoffIntent: IFleetCutoverAcceptedEvidenceReference;
+  palletFence: IFleetCutoverAcceptedEvidenceReference;
+  acceptedAt: number;
+  digest: TSha256Digest;
+}
+
+/** Exact result Pallet persists only after revalidating the current grant following adoption. */
+export interface IFleetCutoverStorageAdoptionBundle {
+  grant: IFleetCutoverStorageAdoptionGrant;
+  fence: Extract<TFleetCutoverVolumeFence, { state: 'consumed' }>;
+  adoption: IFleetCutoverCorestoreAdoptionReceipt;
+  claim: IRuntimeStorageClaim;
+}
+
+/** One authenticated Spark reporter's complete bounded subset of a full immutable aggregate page. */
+export interface IFleetCutoverHeldVolumeFenceEvidencePage {
+  aggregate: IFleetCutoverAcceptedEvidenceReference;
+  page: IFleetCutoverPreparedVolumeHandoffPage;
+  nodeId: string;
+  fences: Extract<TFleetCutoverVolumeFence, { state: 'held' }>[];
+}
+
 export interface IFleetCutoverCoreflowRetirementEvidence {
   id: string;
   generation: number;
@@ -497,19 +673,38 @@ 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,
+  maximumPreparedVolumeHandoffPages: (4096 * 32) / 32,
+  maximumHeldVolumeFenceEvidenceBytes: 131_072,
   maximumClassifications: 512,
   observationFreshnessMs: 300_000,
   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',
   censusDigestDomain: 'serve.zone/fleet-cutover-census',
   scopeDigestDomain: 'serve.zone/fleet-cutover-scope',
   volumeHandoffDigestDomain: 'serve.zone/fleet-cutover-volume-handoff',
+  preparedVolumeHandoffDigestDomain: 'serve.zone/fleet-cutover-prepared-volume-handoff',
+  preparedVolumeHandoffAggregateDigestDomain:
+    'serve.zone/fleet-cutover-prepared-volume-handoff-aggregate',
+  preparedVolumeHandoffPageContentDigestDomain:
+    'serve.zone/fleet-cutover-prepared-volume-handoff-page-content',
+  preparedVolumeHandoffPageDigestDomain: 'serve.zone/fleet-cutover-prepared-volume-handoff-page',
+  preparedVolumeHandoffSetDigestDomain: 'serve.zone/fleet-cutover-prepared-volume-handoff-set',
   volumeFenceDigestDomain: 'serve.zone/fleet-cutover-volume-fence',
   corestoreAdoptionDigestDomain: 'serve.zone/fleet-cutover-corestore-adoption',
+  storageAdoptionGrantDigestDomain: 'serve.zone/fleet-cutover-storage-adoption-grant',
   coreflowRetirementDigestDomain: 'serve.zone/fleet-cutover-coreflow-retirement',
   ingressDesignationDigestDomain: 'serve.zone/fleet-cutover-ingress-designation',
   ingressAuthorityDigestDomain: 'serve.zone/fleet-cutover-ingress-authority',
@@ -521,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(); }
@@ -612,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;
@@ -636,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),
@@ -644,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),
@@ -681,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),
@@ -690,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, [
@@ -773,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,
@@ -786,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 () => {
@@ -821,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> => {
@@ -830,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 () => {
@@ -894,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 {
@@ -1053,6 +1514,13 @@ export const fleetCutoverEvidenceReferenceOf = (
   digest: valueArg.digest,
 });
 
+export const fleetCutoverPreparedVolumeHandoffPageReferenceOf = (
+  valueArg: { id: string; generation: number; digest: TSha256Digest; nodeId: string },
+): IFleetCutoverPreparedVolumeHandoffPageReference => ({
+  ...fleetCutoverEvidenceReferenceOf(valueArg),
+  nodeId: networkNodeId(valueArg.nodeId),
+});
+
 export const snapshotFleetCutoverAcceptedEvidenceReference = (
   valueArg: unknown,
 ): IFleetCutoverAcceptedEvidenceReference => safe(() => reference(captureNetwork(valueArg)));
@@ -1209,6 +1677,383 @@ export const computeFleetCutoverVolumeHandoffDigest = async (
   snapshotFleetCutoverVolumeHandoffIntent(valueArg),
 );
 
+const persistentVolumeMountDescriptor = (
+  valueArg: unknown,
+): IFleetCutoverPersistentVolumeMountDescriptor => {
+  const value = mountDescriptor(valueArg);
+  requireNetwork(value.type === 'volume'
+    && value.classification === 'persistent-volume'
+    && value.readOnly === false);
+  return value as IFleetCutoverPersistentVolumeMountDescriptor;
+};
+
+const preparedVolumeHandoff = (
+  valueArg: unknown,
+): IFleetCutoverPreparedVolumeHandoffIntent => {
+  const value = networkRecord(valueArg, [
+    'id', 'generation', 'clusterId', 'nodeId', 'serviceId', 'volumeId', 'observedMount',
+    'claimIntent', 'runtime', 'scope', 'targetSet', 'legacyStorageEvidence',
+    'sourceNodeObservation', 'acceptedAt', 'digest',
+  ]);
+  const clusterId = networkId(value.clusterId);
+  const nodeId = networkNodeId(value.nodeId);
+  const serviceId = networkId(value.serviceId);
+  const observedMount = persistentVolumeMountDescriptor(value.observedMount);
+  const claimIntent = snapshotRuntimeStorageClaimIntent(value.claimIntent);
+  const runtime = runtimeReference(value.runtime);
+  const targetSet = targetSetReference(value.targetSet);
+  requireNetwork(runtime.id === clusterId && runtime.phase === 'draining'
+    && targetSet.cloudlyClusterId === clusterId
+    && claimIntent.clusterId === clusterId
+    && claimIntent.nodeId === nodeId
+    && claimIntent.serviceId === serviceId);
+  return {
+    id: networkId(value.id),
+    generation: networkCounter(value.generation),
+    clusterId,
+    nodeId,
+    serviceId,
+    volumeId: networkId(value.volumeId),
+    observedMount,
+    claimIntent,
+    runtime: runtime as IFleetCutoverPreparedVolumeHandoffIntent['runtime'],
+    scope: reference(value.scope),
+    targetSet,
+    legacyStorageEvidence: reference(value.legacyStorageEvidence),
+    sourceNodeObservation: reference(value.sourceNodeObservation),
+    acceptedAt: networkCounter(value.acceptedAt),
+    digest: networkDigest(value.digest),
+  };
+};
+
+export const snapshotFleetCutoverPreparedVolumeHandoffIntent = (
+  valueArg: unknown,
+): IFleetCutoverPreparedVolumeHandoffIntent => safe(
+  () => preparedVolumeHandoff(captureNetwork(valueArg)),
+);
+
+export const computeFleetCutoverPreparedVolumeHandoffDigest = async (
+  valueArg: unknown,
+): Promise<TSha256Digest> => canonicalDigest(
+  fleetCutoverContract.preparedVolumeHandoffDigestDomain,
+  snapshotFleetCutoverPreparedVolumeHandoffIntent(valueArg),
+);
+
+export const validateFleetCutoverPreparedVolumeHandoffIntent = async (
+  valueArg: unknown,
+): Promise<string[]> => {
+  try {
+    const value = snapshotFleetCutoverPreparedVolumeHandoffIntent(valueArg);
+    if ((await validateRuntimeStorageClaimIntent(value.claimIntent)).length) {
+      return ['fleet cutover prepared volume handoff claim intent is invalid'];
+    }
+    return value.digest === await computeFleetCutoverPreparedVolumeHandoffDigest(value)
+      ? [] : ['fleet cutover prepared volume handoff digest does not match'];
+  } catch {
+    return ['fleet cutover prepared volume handoff must use its exact canonical schema'];
+  }
+};
+
+export const snapshotFleetCutoverPreparedVolumeHandoffMutation = (
+  valueArg: unknown,
+): IFleetCutoverPreparedVolumeHandoffMutation => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), [
+    'mutationId', 'clusterId', 'currentRuntime', 'scope', 'targetSet', 'expectedAggregate',
+    'upserts', 'removals',
+  ]);
+  const clusterId = networkId(value.clusterId);
+  const currentRuntime = runtimeReference(value.currentRuntime);
+  const targetSet = targetSetReference(value.targetSet);
+  requireNetwork(currentRuntime.id === clusterId && currentRuntime.phase === 'draining'
+    && targetSet.cloudlyClusterId === clusterId);
+  const requestKeys = new Set<string>();
+  const placementKeys = new Set<string>();
+  const upserts = networkSorted(networkList(
+    value.upserts,
+    fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries,
+    itemArg => {
+      const item = networkRecord(itemArg, [
+        'nodeId', 'serviceId', 'mountIdentityDigest', 'request',
+      ]);
+      const nodeId = networkNodeId(item.nodeId);
+      const serviceId = networkId(item.serviceId);
+      const mountIdentityDigest = networkDigest(item.mountIdentityDigest);
+      const request = normalizeStorageRequest(item.request);
+      requireNetwork(request.kind === 'filesystem'
+        && request.accessMode === 'ReadWriteOnce'
+        && request.reclaimPolicy === 'retain');
+      const requestKey = `${nodeId}\u0000${serviceId}\u0000${request.id}`;
+      const placementKey = `${nodeId}\u0000${serviceId}\u0000${mountIdentityDigest}`;
+      requireNetwork(!requestKeys.has(requestKey) && !placementKeys.has(placementKey));
+      requestKeys.add(requestKey);
+      placementKeys.add(placementKey);
+      return {
+        nodeId,
+        serviceId,
+        mountIdentityDigest,
+        request: request as IFleetCutoverPreparedVolumeHandoffUpsert['request'],
+      };
+    },
+  ), itemArg => `${itemArg.nodeId}\u0000${itemArg.serviceId}\u0000${itemArg.mountIdentityDigest}`);
+  const removals = networkSorted(networkList(
+    value.removals,
+    fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries,
+    reference,
+  ), itemArg => `${itemArg.id}\u0000${String(itemArg.generation).padStart(16, '0')}\u0000${itemArg.digest}`);
+  requireNetwork(upserts.length + removals.length > 0
+    && upserts.length + removals.length
+      <= fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries);
+  return {
+    mutationId: networkId(value.mutationId),
+    clusterId,
+    currentRuntime: currentRuntime as IFleetCutoverPreparedVolumeHandoffMutation['currentRuntime'],
+    scope: reference(value.scope),
+    targetSet,
+    expectedAggregate: value.expectedAggregate === null ? null : reference(value.expectedAggregate),
+    upserts,
+    removals,
+  };
+});
+
+const preparedVolumeHandoffAggregate = (
+  valueArg: unknown,
+): IFleetCutoverPreparedVolumeHandoffAggregate => {
+  const value = networkRecord(valueArg, [
+    'id', 'generation', 'previous', 'clusterId', 'runtime', 'scope', 'targetSet', 'state',
+    'requiredHandoffCount', 'handoffCount', 'pageCount', 'handoffSetDigest', 'acceptedAt',
+    'digest',
+  ]);
+  const id = networkId(value.id);
+  const generation = networkCounter(value.generation);
+  const previous = value.previous === null ? null : reference(value.previous);
+  requireNetwork(generation === 1
+    ? previous === null
+    : previous?.id === id && previous.generation === generation - 1);
+  const clusterId = networkId(value.clusterId);
+  const runtime = runtimeReference(value.runtime);
+  const targetSet = targetSetReference(value.targetSet);
+  const state = literal(['incomplete', 'complete'] as const, value.state);
+  const requiredHandoffCount = nonNegative(value.requiredHandoffCount);
+  const handoffCount = nonNegative(value.handoffCount);
+  const pageCount = nonNegative(value.pageCount);
+  requireNetwork(runtime.id === clusterId && runtime.phase === 'draining'
+    && targetSet.cloudlyClusterId === clusterId
+    && requiredHandoffCount <= fleetCutoverContract.maximumPreparedVolumeHandoffs
+    && handoffCount <= fleetCutoverContract.maximumPreparedVolumeHandoffs
+    && pageCount <= fleetCutoverContract.maximumPreparedVolumeHandoffPages
+    && pageCount === Math.ceil(handoffCount
+      / fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries)
+    && (state === 'complete') === (requiredHandoffCount === handoffCount));
+  return {
+    id,
+    generation,
+    previous,
+    clusterId,
+    runtime: runtime as IFleetCutoverPreparedVolumeHandoffAggregate['runtime'],
+    scope: reference(value.scope),
+    targetSet,
+    state,
+    requiredHandoffCount,
+    handoffCount,
+    pageCount,
+    handoffSetDigest: networkDigest(value.handoffSetDigest),
+    acceptedAt: networkCounter(value.acceptedAt),
+    digest: networkDigest(value.digest),
+  };
+};
+
+export const snapshotFleetCutoverPreparedVolumeHandoffAggregate = (
+  valueArg: unknown,
+): IFleetCutoverPreparedVolumeHandoffAggregate => safe(
+  () => preparedVolumeHandoffAggregate(captureNetwork(valueArg)),
+);
+
+export const computeFleetCutoverPreparedVolumeHandoffAggregateDigest = async (
+  valueArg: unknown,
+): Promise<TSha256Digest> => canonicalDigest(
+  fleetCutoverContract.preparedVolumeHandoffAggregateDigestDomain,
+  snapshotFleetCutoverPreparedVolumeHandoffAggregate(valueArg),
+);
+
+export const validateFleetCutoverPreparedVolumeHandoffAggregate = async (
+  valueArg: unknown,
+): Promise<string[]> => {
+  try {
+    const value = snapshotFleetCutoverPreparedVolumeHandoffAggregate(valueArg);
+    return value.digest === await computeFleetCutoverPreparedVolumeHandoffAggregateDigest(value)
+      ? [] : ['fleet cutover prepared volume handoff aggregate digest does not match'];
+  } catch {
+    return ['fleet cutover prepared volume handoff aggregate must use its exact canonical schema'];
+  }
+};
+
+const preparedVolumeHandoffPage = (
+  valueArg: unknown,
+): IFleetCutoverPreparedVolumeHandoffPage => {
+  const value = networkRecord(valueArg, [
+    'id', 'generation', 'aggregate', 'pageIndex', 'handoffs', 'handoffSetPageDigest', 'digest',
+  ]);
+  requireNetwork(value.generation === 1);
+  const handoffs = networkSorted(networkList(
+    value.handoffs,
+    fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries,
+    itemArg => {
+      const item = networkRecord(itemArg, ['id', 'generation', 'digest', 'nodeId']);
+      return fleetCutoverPreparedVolumeHandoffPageReferenceOf({
+        ...reference({ id: item.id, generation: item.generation, digest: item.digest }),
+        nodeId: networkNodeId(item.nodeId),
+      });
+    },
+  ), itemArg => `${itemArg.id}\u0000${String(itemArg.generation).padStart(16, '0')}\u0000${itemArg.digest}`);
+  const pageIndex = nonNegative(value.pageIndex);
+  requireNetwork(handoffs.length > 0
+    && pageIndex < fleetCutoverContract.maximumPreparedVolumeHandoffPages);
+  return {
+    id: networkId(value.id),
+    generation: 1,
+    aggregate: reference(value.aggregate),
+    pageIndex,
+    handoffs,
+    handoffSetPageDigest: networkDigest(value.handoffSetPageDigest),
+    digest: networkDigest(value.digest),
+  };
+};
+
+export const snapshotFleetCutoverPreparedVolumeHandoffPage = (
+  valueArg: unknown,
+): IFleetCutoverPreparedVolumeHandoffPage => safe(
+  () => preparedVolumeHandoffPage(captureNetwork(valueArg)),
+);
+
+export const computeFleetCutoverPreparedVolumeHandoffPageContentDigest = async (
+  pageIndexArg: unknown,
+  handoffsArg: unknown,
+): Promise<TSha256Digest> => {
+  const page = preparedVolumeHandoffPage({
+    id: 'FleetCutoverPreparedVolumeHandoffPage:content',
+    generation: 1,
+    aggregate: { id: 'FleetCutoverPreparedVolumeHandoffAggregate:content', generation: 1,
+      digest: `sha256:${'0'.repeat(64)}` },
+    pageIndex: pageIndexArg,
+    handoffs: handoffsArg,
+    handoffSetPageDigest: `sha256:${'0'.repeat(64)}`,
+    digest: `sha256:${'0'.repeat(64)}`,
+  });
+  return canonicalDigest(fleetCutoverContract.preparedVolumeHandoffPageContentDigestDomain, {
+    pageIndex: page.pageIndex,
+    handoffs: page.handoffs,
+    digest: `sha256:${'0'.repeat(64)}`,
+  });
+};
+
+export const computeFleetCutoverPreparedVolumeHandoffPageDigest = async (
+  valueArg: unknown,
+): Promise<TSha256Digest> => canonicalDigest(
+  fleetCutoverContract.preparedVolumeHandoffPageDigestDomain,
+  snapshotFleetCutoverPreparedVolumeHandoffPage(valueArg),
+);
+
+export const validateFleetCutoverPreparedVolumeHandoffPage = async (
+  valueArg: unknown,
+): Promise<string[]> => {
+  try {
+    const value = snapshotFleetCutoverPreparedVolumeHandoffPage(valueArg);
+    if (value.handoffSetPageDigest
+      !== await computeFleetCutoverPreparedVolumeHandoffPageContentDigest(
+        value.pageIndex,
+        value.handoffs,
+      )) {
+      return ['fleet cutover prepared volume handoff page content digest does not match'];
+    }
+    return value.digest === await computeFleetCutoverPreparedVolumeHandoffPageDigest(value)
+      ? [] : ['fleet cutover prepared volume handoff page digest does not match'];
+  } catch {
+    return ['fleet cutover prepared volume handoff page must use its exact canonical schema'];
+  }
+};
+
+export const computeFleetCutoverPreparedVolumeHandoffSetDigest = async (
+  entriesArg: unknown,
+): Promise<TSha256Digest> => safe(async () => {
+  const entries = networkSorted(networkList(
+    captureNetwork(entriesArg),
+    fleetCutoverContract.maximumPreparedVolumeHandoffPages,
+    itemArg => {
+      const item = networkRecord(itemArg, ['pageIndex', 'handoffSetPageDigest']);
+      return {
+        pageIndex: nonNegative(item.pageIndex),
+        handoffSetPageDigest: networkDigest(item.handoffSetPageDigest),
+      };
+    },
+  ), itemArg => String(itemArg.pageIndex).padStart(8, '0'));
+  requireNetwork(entries.every((entryArg, indexArg) => entryArg.pageIndex === indexArg));
+  return canonicalDigest(fleetCutoverContract.preparedVolumeHandoffSetDigestDomain, {
+    entries,
+    digest: `sha256:${'0'.repeat(64)}`,
+  });
+});
+
+/**
+ * Full pinned-set proof. The caller must supply every page for the exact aggregate revision; a
+ * node-local subset or a mixed revision can never satisfy this binder.
+ */
+export const bindFleetCutoverPreparedVolumeHandoffPages = async (
+  aggregateArg: unknown,
+  pagesArg: unknown,
+): Promise<{
+  aggregate: IFleetCutoverPreparedVolumeHandoffAggregate;
+  pages: IFleetCutoverPreparedVolumeHandoffPage[];
+}> => {
+  const aggregate = snapshotFleetCutoverPreparedVolumeHandoffAggregate(aggregateArg);
+  if ((await validateFleetCutoverPreparedVolumeHandoffAggregate(aggregate)).length) fail();
+  const pages = safe(() => {
+    requireNetwork(Array.isArray(pagesArg)
+      && Object.getPrototypeOf(pagesArg) === Array.prototype
+      && pagesArg.length <= fleetCutoverContract.maximumPreparedVolumeHandoffPages);
+    const keys = Reflect.ownKeys(pagesArg);
+    requireNetwork(keys.length === pagesArg.length + 1);
+    const result: IFleetCutoverPreparedVolumeHandoffPage[] = [];
+    for (let index = 0; index < pagesArg.length; index++) {
+      const descriptor = Object.getOwnPropertyDescriptor(pagesArg, String(index));
+      requireNetwork(descriptor?.enumerable && Object.hasOwn(descriptor, 'value'));
+      result.push(snapshotFleetCutoverPreparedVolumeHandoffPage(descriptor.value));
+    }
+    return networkSorted(result, itemArg => String(itemArg.pageIndex).padStart(8, '0'));
+  });
+  requireNetwork(pages.length === aggregate.pageCount);
+  let handoffCount = 0;
+  const seen = new Set<string>();
+  let previousHandoffKey: string | null = null;
+  for (const [index, page] of pages.entries()) {
+    requireNetwork(page.pageIndex === index
+      && page.aggregate.id === aggregate.id
+      && page.aggregate.generation === aggregate.generation
+      && page.aggregate.digest === aggregate.digest
+      && !(await validateFleetCutoverPreparedVolumeHandoffPage(page)).length);
+    const expectedLength = index < pages.length - 1
+      ? fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries
+      : aggregate.handoffCount
+        % fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries
+          || fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries;
+    requireNetwork(page.handoffs.length === expectedLength);
+    handoffCount += page.handoffs.length;
+    for (const handoff of page.handoffs) {
+      const key = `${handoff.id}\u0000${handoff.generation}\u0000${handoff.digest}`;
+      requireNetwork(!seen.has(key) && (previousHandoffKey === null || previousHandoffKey < key));
+      seen.add(key);
+      previousHandoffKey = key;
+    }
+  }
+  const entries = pages.map(page => ({
+    pageIndex: page.pageIndex,
+    handoffSetPageDigest: page.handoffSetPageDigest,
+  }));
+  requireNetwork(handoffCount === aggregate.handoffCount
+    && aggregate.handoffSetDigest
+      === await computeFleetCutoverPreparedVolumeHandoffSetDigest(entries));
+  return { aggregate, pages };
+};
+
 const volumeFence = (valueArg: unknown): TFleetCutoverVolumeFence => {
   requireNetwork(valueArg !== null && typeof valueArg === 'object');
   const state = (valueArg as Record<string, unknown>).state;
@@ -1324,6 +2169,45 @@ export const bindFleetCutoverAdoptionToVolumeFence = (
   return { adoption, fence };
 });
 
+/**
+ * Joins the accepted adoption result to the full handoff and provider-ready claim content.
+ * Native attachment fencing and accepted-record dereferencing remain owner checks.
+ */
+export const bindFleetCutoverAdoptionToStorageClaim = async (
+  adoptionArg: unknown,
+  handoffArg: unknown,
+  claimArg: unknown,
+): Promise<{
+  adoption: IFleetCutoverCorestoreAdoptionReceipt;
+  handoff: IFleetCutoverPreparedVolumeHandoffIntent;
+  claim: IRuntimeStorageClaim;
+}> => {
+  try {
+    const adoption = snapshotFleetCutoverCorestoreAdoptionReceipt(adoptionArg);
+    const handoff = snapshotFleetCutoverPreparedVolumeHandoffIntent(handoffArg);
+    const claim = snapshotRuntimeStorageClaim(claimArg);
+    if ((await validateFleetCutoverCorestoreAdoptionReceipt(adoption)).length
+      || (await validateFleetCutoverPreparedVolumeHandoffIntent(handoff)).length
+      || (await validateRuntimeStorageClaim(claim)).length) fail();
+    await bindRuntimeStorageClaimToIntent(claim, handoff.claimIntent);
+    requireNetwork(adoption.clusterId === handoff.clusterId
+      && adoption.nodeId === handoff.nodeId
+      && adoption.serviceId === handoff.serviceId
+      && adoption.volumeId === handoff.volumeId
+      && adoption.mountIdentityDigest === handoff.observedMount.mountIdentityDigest
+      && adoption.handoffIntent.id === handoff.id
+      && adoption.handoffIntent.generation === handoff.generation
+      && adoption.handoffIntent.digest === handoff.digest
+      && adoption.claim.id === claim.id
+      && adoption.claim.generation === claim.generation
+      && adoption.claim.digest === claim.digest
+      && adoption.acceptedAt >= handoff.acceptedAt);
+    return { adoption, handoff, claim };
+  } catch {
+    return fail();
+  }
+};
+
 export const validateFleetCutoverVolumeHandoffIntent = async (valueArg: unknown): Promise<string[]> => {
   try {
     const value = snapshotFleetCutoverVolumeHandoffIntent(valueArg);
@@ -1373,6 +2257,273 @@ const runtimeSession = (valueArg: unknown): IRuntimeSessionBinding => {
   };
 };
 
+const storageAdoptionGrant = (valueArg: unknown): IFleetCutoverStorageAdoptionGrant => {
+  const value = networkRecord(valueArg, [
+    'id', 'generation', 'previous', 'clusterId', 'nodeId', 'serviceId', 'volumeId',
+    'observedMount', 'runtime', 'session', 'handoffIntent', 'palletFence', 'acceptedAt',
+    'digest',
+  ]);
+  const id = networkId(value.id);
+  const generation = networkCounter(value.generation);
+  const previous = value.previous === null ? null : reference(value.previous);
+  requireNetwork(generation === 1
+    ? previous === null
+    : previous?.id === id && previous.generation === generation - 1);
+  const clusterId = networkId(value.clusterId);
+  const nodeId = networkNodeId(value.nodeId);
+  const runtime = runtimeReference(value.runtime);
+  const session = runtimeSession(value.session);
+  requireNetwork(runtime.id === clusterId && runtime.phase === 'pallet'
+    && session.clusterId === clusterId
+    && session.nodeId === nodeId
+    && session.controller.kind === 'cloudly');
+  return {
+    id,
+    generation,
+    previous,
+    clusterId,
+    nodeId,
+    serviceId: networkId(value.serviceId),
+    volumeId: networkId(value.volumeId),
+    observedMount: persistentVolumeMountDescriptor(value.observedMount),
+    runtime: runtime as IFleetCutoverStorageAdoptionGrant['runtime'],
+    session,
+    handoffIntent: reference(value.handoffIntent),
+    palletFence: reference(value.palletFence),
+    acceptedAt: networkCounter(value.acceptedAt),
+    digest: networkDigest(value.digest),
+  };
+};
+
+export const snapshotFleetCutoverStorageAdoptionGrant = (
+  valueArg: unknown,
+): IFleetCutoverStorageAdoptionGrant => safe(
+  () => storageAdoptionGrant(captureNetwork(valueArg)),
+);
+
+export const computeFleetCutoverStorageAdoptionGrantDigest = async (
+  valueArg: unknown,
+): Promise<TSha256Digest> => canonicalDigest(
+  fleetCutoverContract.storageAdoptionGrantDigestDomain,
+  snapshotFleetCutoverStorageAdoptionGrant(valueArg),
+);
+
+export const validateFleetCutoverStorageAdoptionGrant = async (
+  valueArg: unknown,
+): Promise<string[]> => {
+  try {
+    const value = snapshotFleetCutoverStorageAdoptionGrant(valueArg);
+    return value.digest === await computeFleetCutoverStorageAdoptionGrantDigest(value)
+      ? [] : ['fleet cutover storage adoption grant digest does not match'];
+  } catch {
+    return ['fleet cutover storage adoption grant must use its exact canonical schema'];
+  }
+};
+
+/** Content join only; the controller must still prove this is the live current session and phase. */
+export const bindFleetCutoverStorageAdoptionGrant = async (
+  grantArg: unknown,
+  handoffArg: unknown,
+  heldFenceArg: unknown,
+): Promise<{
+  grant: IFleetCutoverStorageAdoptionGrant;
+  handoff: IFleetCutoverPreparedVolumeHandoffIntent;
+  fence: Extract<TFleetCutoverVolumeFence, { state: 'held' }>;
+}> => {
+  try {
+    const grant = snapshotFleetCutoverStorageAdoptionGrant(grantArg);
+    const handoff = snapshotFleetCutoverPreparedVolumeHandoffIntent(handoffArg);
+    const fence = snapshotFleetCutoverVolumeFence(heldFenceArg);
+    if ((await validateFleetCutoverStorageAdoptionGrant(grant)).length
+      || (await validateFleetCutoverPreparedVolumeHandoffIntent(handoff)).length
+      || (await validateFleetCutoverVolumeFence(fence)).length) fail();
+    requireNetwork(fence.state === 'held'
+      && grant.clusterId === handoff.clusterId
+      && grant.nodeId === handoff.nodeId
+      && grant.serviceId === handoff.serviceId
+      && grant.volumeId === handoff.volumeId
+      && grant.observedMount.type === handoff.observedMount.type
+      && grant.observedMount.classification === handoff.observedMount.classification
+      && grant.observedMount.sourceIdentityDigest === handoff.observedMount.sourceIdentityDigest
+      && grant.observedMount.targetIdentityDigest === handoff.observedMount.targetIdentityDigest
+      && grant.observedMount.readOnly === handoff.observedMount.readOnly
+      && grant.observedMount.mountIdentityDigest === handoff.observedMount.mountIdentityDigest
+      && grant.handoffIntent.id === handoff.id
+      && grant.handoffIntent.generation === handoff.generation
+      && grant.handoffIntent.digest === handoff.digest
+      && grant.palletFence.id === fence.id
+      && grant.palletFence.generation === fence.generation
+      && grant.palletFence.digest === fence.digest
+      && fence.clusterId === handoff.clusterId
+      && fence.nodeId === handoff.nodeId
+      && fence.serviceId === handoff.serviceId
+      && fence.volumeId === handoff.volumeId
+      && fence.mountIdentityDigest === handoff.observedMount.mountIdentityDigest
+      && fence.handoffIntent.id === handoff.id
+      && fence.handoffIntent.generation === handoff.generation
+      && fence.handoffIntent.digest === handoff.digest
+      && fence.heldRuntime.id === handoff.runtime.id
+      && fence.heldRuntime.phase === handoff.runtime.phase
+      && fence.heldRuntime.generation === handoff.runtime.generation
+      && grant.session.controller.id === handoff.claimIntent.controller.id
+      && grant.session.controller.epoch === handoff.claimIntent.controller.epoch
+      && grant.session.runtimeNamespace === handoff.claimIntent.runtimeNamespace
+      && grant.acceptedAt >= fence.heldAt);
+    return { grant, handoff, fence };
+  } catch {
+    return fail();
+  }
+};
+
+export const snapshotFleetCutoverStorageAdoptionBundle = (
+  valueArg: unknown,
+): IFleetCutoverStorageAdoptionBundle => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), [
+    'grant', 'fence', 'adoption', 'claim',
+  ]);
+  const fence = snapshotFleetCutoverVolumeFence(value.fence);
+  requireNetwork(fence.state === 'consumed');
+  return {
+    grant: snapshotFleetCutoverStorageAdoptionGrant(value.grant),
+    fence,
+    adoption: snapshotFleetCutoverCorestoreAdoptionReceipt(value.adoption),
+    claim: snapshotRuntimeStorageClaim(value.claim),
+  };
+});
+
+/**
+ * Binds the complete post-adoption content. Physical lineage remains the provider-produced
+ * adoption digest and is deliberately never equated to the observed Docker source identity.
+ */
+export const bindFleetCutoverStorageAdoptionBundle = async (
+  valueArg: unknown,
+  handoffArg: unknown,
+): Promise<{
+  bundle: IFleetCutoverStorageAdoptionBundle;
+  handoff: IFleetCutoverPreparedVolumeHandoffIntent;
+}> => {
+  try {
+    const bundle = snapshotFleetCutoverStorageAdoptionBundle(valueArg);
+    const handoff = snapshotFleetCutoverPreparedVolumeHandoffIntent(handoffArg);
+    const { grant, fence, adoption, claim } = bundle;
+    if ((await validateFleetCutoverStorageAdoptionGrant(grant)).length
+      || (await validateFleetCutoverPreparedVolumeHandoffIntent(handoff)).length
+      || (await validateFleetCutoverVolumeFence(fence)).length
+      || (await validateFleetCutoverCorestoreAdoptionReceipt(adoption)).length
+      || (await validateRuntimeStorageClaim(claim)).length) fail();
+    await bindRuntimeStorageClaimToIntent(claim, handoff.claimIntent);
+    requireNetwork(grant.clusterId === handoff.clusterId
+      && grant.nodeId === handoff.nodeId
+      && grant.serviceId === handoff.serviceId
+      && grant.volumeId === handoff.volumeId
+      && grant.observedMount.type === handoff.observedMount.type
+      && grant.observedMount.classification === handoff.observedMount.classification
+      && grant.observedMount.sourceIdentityDigest === handoff.observedMount.sourceIdentityDigest
+      && grant.observedMount.targetIdentityDigest === handoff.observedMount.targetIdentityDigest
+      && grant.observedMount.readOnly === handoff.observedMount.readOnly
+      && grant.observedMount.mountIdentityDigest === handoff.observedMount.mountIdentityDigest
+      && grant.session.controller.id === handoff.claimIntent.controller.id
+      && grant.session.controller.epoch === handoff.claimIntent.controller.epoch
+      && grant.session.runtimeNamespace === handoff.claimIntent.runtimeNamespace
+      && grant.handoffIntent.id === handoff.id
+      && grant.handoffIntent.generation === handoff.generation
+      && grant.handoffIntent.digest === handoff.digest
+      && fence.clusterId === grant.clusterId
+      && fence.nodeId === grant.nodeId
+      && fence.serviceId === grant.serviceId
+      && fence.volumeId === grant.volumeId
+      && fence.mountIdentityDigest === grant.observedMount.mountIdentityDigest
+      && fence.handoffIntent.id === handoff.id
+      && fence.handoffIntent.generation === handoff.generation
+      && fence.handoffIntent.digest === handoff.digest
+      && fence.previous !== null
+      && fence.previous.id === grant.palletFence.id
+      && fence.previous.generation === grant.palletFence.generation
+      && fence.previous.digest === grant.palletFence.digest
+      && fence.consumedRuntime.id === grant.runtime.id
+      && fence.consumedRuntime.phase === grant.runtime.phase
+      && fence.consumedRuntime.generation === grant.runtime.generation
+      && adoption.clusterId === handoff.clusterId
+      && adoption.nodeId === handoff.nodeId
+      && adoption.serviceId === handoff.serviceId
+      && adoption.volumeId === handoff.volumeId
+      && adoption.mountIdentityDigest === handoff.observedMount.mountIdentityDigest
+      && adoption.handoffIntent.id === handoff.id
+      && adoption.handoffIntent.generation === handoff.generation
+      && adoption.handoffIntent.digest === handoff.digest
+      && adoption.palletFence.id === grant.palletFence.id
+      && adoption.palletFence.generation === grant.palletFence.generation
+      && adoption.palletFence.digest === grant.palletFence.digest
+      && adoption.claim.id === claim.id
+      && adoption.claim.generation === claim.generation
+      && adoption.claim.digest === claim.digest
+      && fence.adoptionReceipt.id === adoption.id
+      && fence.adoptionReceipt.generation === adoption.generation
+      && fence.adoptionReceipt.digest === adoption.digest
+      && fence.claim.id === claim.id
+      && fence.claim.generation === claim.generation
+      && fence.claim.digest === claim.digest
+      && adoption.acceptedAt >= grant.acceptedAt
+      && fence.consumedAt >= adoption.acceptedAt);
+    return { bundle, handoff };
+  } catch {
+    return fail();
+  }
+};
+
+export const snapshotFleetCutoverHeldVolumeFenceEvidencePage = (
+  valueArg: unknown,
+): IFleetCutoverHeldVolumeFenceEvidencePage => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['aggregate', 'page', 'nodeId', 'fences']);
+  const aggregate = reference(value.aggregate);
+  const page = preparedVolumeHandoffPage(value.page);
+  const nodeId = networkNodeId(value.nodeId);
+  requireNetwork(page.aggregate.id === aggregate.id
+    && page.aggregate.generation === aggregate.generation
+    && page.aggregate.digest === aggregate.digest);
+  const pageHandoffs = page.handoffs.filter(itemArg => itemArg.nodeId === nodeId);
+  const fences = networkSorted(networkList(
+    value.fences,
+    fleetCutoverContract.maximumPreparedVolumeHandoffMutationEntries,
+    itemArg => {
+      const fence = volumeFence(itemArg);
+      requireNetwork(fence.state === 'held' && fence.nodeId === nodeId);
+      return fence;
+    },
+  ), itemArg => `${itemArg.handoffIntent.id}\u0000${itemArg.handoffIntent.generation}\u0000${itemArg.handoffIntent.digest}`);
+  requireNetwork(fences.length === pageHandoffs.length
+    && fences.every((fenceArg, indexArg) => {
+      const handoff = pageHandoffs[indexArg];
+      return fenceArg.handoffIntent.id === handoff.id
+        && fenceArg.handoffIntent.generation === handoff.generation
+        && fenceArg.handoffIntent.digest === handoff.digest;
+    }));
+  return { aggregate, page, nodeId, fences };
+});
+
+export const validateFleetCutoverHeldVolumeFenceEvidencePage = async (
+  valueArg: unknown,
+): Promise<string[]> => {
+  try {
+    const value = snapshotFleetCutoverHeldVolumeFenceEvidencePage(valueArg);
+    if (new TextEncoder().encode(canonicalizeStrictJson(value, fail)).byteLength
+      > fleetCutoverContract.maximumHeldVolumeFenceEvidenceBytes) {
+      return ['fleet cutover held volume fence evidence page exceeds its encoded byte bound'];
+    }
+    if ((await validateFleetCutoverPreparedVolumeHandoffPage(value.page)).length) {
+      return ['fleet cutover held volume fence evidence page is not a valid immutable page'];
+    }
+    for (const fence of value.fences) {
+      if ((await validateFleetCutoverVolumeFence(fence)).length) {
+        return ['fleet cutover held volume fence evidence contains an invalid held fence'];
+      }
+    }
+    return [];
+  } catch {
+    return ['fleet cutover held volume fence evidence page must use its exact canonical schema'];
+  }
+};
+
 export const snapshotFleetCutoverCoreflowRetirementEvidence = (
   valueArg: unknown,
 ): IFleetCutoverCoreflowRetirementEvidence => safe(() => {