From 22a480930ea1b1fb0ac9f0024558d373b2ae0ab5 Mon Sep 17 00:00:00 2001
From: Steve Ebersole <steve@hibernate.org>
Date: Wed, 23 Apr 2025 11:07:27 -0500
Subject: [PATCH] HHH-19382 - Drop incubating SelectionQuery#setOrder methods

---
 .../procedure/internal/ProcedureCallImpl.java |  11 -
 .../main/java/org/hibernate/query/Order.java  |   8 +-
 .../main/java/org/hibernate/query/Query.java  |   5 -
 .../org/hibernate/query/SelectionQuery.java   |  26 --
 .../query/programmatic/package-info.java      |  12 -
 .../query/restriction/Restriction.java        |  10 +-
 .../MutationSpecification.java                |   4 +-
 .../QuerySpecification.java                   |   2 +-
 .../SelectionSpecification.java               |   4 +-
 .../internal/MutationSpecificationImpl.java   |   4 +-
 .../internal/SelectionSpecificationImpl.java  |  84 +++-
 .../query/specification/package-info.java     |  13 +
 .../hibernate/query/spi/AbstractQuery.java    |  13 -
 .../query/sql/internal/NativeQueryImpl.java   |  10 -
 .../internal/AbstractSqmSelectionQuery.java   |  40 --
 .../query/sqm/internal/QuerySqmImpl.java      |  13 -
 ...elegatingSqmSelectionQueryImplementor.java |  15 -
 ...ndFetchWithCriteriaSelectionQueryTest.java |  13 +-
 .../SimpleQuerySpecificationTests.java        |   4 +-
 .../orm/test/query/order/OrderTest.java       | 373 +++++++++---------
 .../query/restriction/RestrictionTest.java    |  20 +-
 migration-guide.adoc                          |   7 +
 .../annotation/AbstractCriteriaMethod.java    |   2 +-
 .../annotation/CriteriaDeleteMethod.java      |   2 +-
 .../processor/annotation/QueryMethod.java     |   4 +-
 25 files changed, 319 insertions(+), 380 deletions(-)
 delete mode 100644 hibernate-core/src/main/java/org/hibernate/query/programmatic/package-info.java
 rename hibernate-core/src/main/java/org/hibernate/query/{programmatic => specification}/MutationSpecification.java (97%)
 rename hibernate-core/src/main/java/org/hibernate/query/{programmatic => specification}/QuerySpecification.java (98%)
 rename hibernate-core/src/main/java/org/hibernate/query/{programmatic => specification}/SelectionSpecification.java (98%)
 rename hibernate-core/src/main/java/org/hibernate/query/{programmatic => specification}/internal/MutationSpecificationImpl.java (98%)
 rename hibernate-core/src/main/java/org/hibernate/query/{programmatic => specification}/internal/SelectionSpecificationImpl.java (77%)
 create mode 100644 hibernate-core/src/main/java/org/hibernate/query/specification/package-info.java

diff --git a/hibernate-core/src/main/java/org/hibernate/procedure/internal/ProcedureCallImpl.java b/hibernate-core/src/main/java/org/hibernate/procedure/internal/ProcedureCallImpl.java
index 2264fb09ca5a..30f2072285e3 100644
--- a/hibernate-core/src/main/java/org/hibernate/procedure/internal/ProcedureCallImpl.java
+++ b/hibernate-core/src/main/java/org/hibernate/procedure/internal/ProcedureCallImpl.java
@@ -44,7 +44,6 @@
 import org.hibernate.query.BindableType;
 import org.hibernate.query.KeyedPage;
 import org.hibernate.query.KeyedResultList;
-import org.hibernate.query.Order;
 import org.hibernate.query.OutputableType;
 import org.hibernate.query.Query;
 import org.hibernate.query.QueryParameter;
@@ -411,16 +410,6 @@ public QueryParameterBindings getParameterBindings() {
 		return parameterBindings;
 	}
 
-	@Override
-	public Query<R> setOrder(List<? extends Order<? super R>> orderList) {
-		throw new UnsupportedOperationException("Ordering not supported for stored procedure calls");
-	}
-
-	@Override
-	public Query<R> setOrder(Order<? super R> order) {
-		throw new UnsupportedOperationException("Ordering not supported for stored procedure calls");
-	}
-
 
 	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 	// Parameter registrations
diff --git a/hibernate-core/src/main/java/org/hibernate/query/Order.java b/hibernate-core/src/main/java/org/hibernate/query/Order.java
index 7e343bfcffdf..918547ed4e61 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/Order.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/Order.java
@@ -20,7 +20,7 @@
  * <p>
  * This is a convenience class which allows query result ordering rules to be
  * passed around the system before being applied to a {@link Query} by calling
- * {@link org.hibernate.query.programmatic.SelectionSpecification#sort(Order)}.
+ * {@link org.hibernate.query.specification.SelectionSpecification#sort(Order)}.
  * <pre>
  * SelectionSpecification.create(Book.class,
  *             "from Book b join b.authors a where a.name = :name")
@@ -31,7 +31,7 @@
  * </pre>
  * <p>
  * {@code Order}s may be stacked using {@link List#of} and
- * {@link org.hibernate.query.programmatic.SelectionSpecification#resort(List)}.
+ * {@link org.hibernate.query.specification.SelectionSpecification#resort(List)}.
  * <pre>
  * SelectionSpecification.create(Book.class,
  *             "from Book b join b.authors a where a.name = :name")
@@ -52,8 +52,8 @@
  *          used by Hibernate Data Repositories to implement Jakarta Data
  *          query methods.
  *
- * @see org.hibernate.query.programmatic.SelectionSpecification#sort(Order)
- * @see org.hibernate.query.programmatic.SelectionSpecification#resort(List)
+ * @see org.hibernate.query.specification.SelectionSpecification#sort(Order)
+ * @see org.hibernate.query.specification.SelectionSpecification#resort(List)
  * @see org.hibernate.query.restriction.Restriction
  *
  * @author Gavin King
diff --git a/hibernate-core/src/main/java/org/hibernate/query/Query.java b/hibernate-core/src/main/java/org/hibernate/query/Query.java
index c31c0a0a7fe5..4d4926ffcb50 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/Query.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/Query.java
@@ -928,11 +928,6 @@ default Query<R> setPage(Page page) {
 	@Override
 	Query<R> setLockMode(LockModeType lockMode);
 
-	@Override @Incubating
-	Query<R> setOrder(List<? extends Order<? super R>> orderList);
-
-	@Override @Incubating
-	Query<R> setOrder(Order<? super R> order);
 
 	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 	// deprecated methods
diff --git a/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java b/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java
index b1a89eb88855..7670a8ebad6a 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java
@@ -596,32 +596,6 @@ default Stream<R> stream() {
 	 */
 	SelectionQuery<R> setLockMode(String alias, LockMode lockMode);
 
-	/**
-	 * If the result type of this query is an entity class, add one or more
-	 * {@linkplain Order rules} for ordering the query results.
-	 *
-	 * @param orderList one or more instances of {@link Order}
-	 *
-	 * @see Order
-	 *
-	 * @since 6.3
-	 */
-	@Incubating
-	SelectionQuery<R> setOrder(List<? extends Order<? super R>> orderList);
-
-	/**
-	 * If the result type of this query is an entity class, add a
-	 * {@linkplain Order rule} for ordering the query results.
-	 *
-	 * @param order an instance of {@link Order}
-	 *
-	 * @see Order
-	 *
-	 * @since 6.3
-	 */
-	@Incubating
-	SelectionQuery<R> setOrder(Order<? super R> order);
-
 	/**
 	 * Specifies whether follow-on locking should be applied
 	 */
diff --git a/hibernate-core/src/main/java/org/hibernate/query/programmatic/package-info.java b/hibernate-core/src/main/java/org/hibernate/query/programmatic/package-info.java
deleted file mode 100644
index 46d6d4a84f62..000000000000
--- a/hibernate-core/src/main/java/org/hibernate/query/programmatic/package-info.java
+++ /dev/null
@@ -1,12 +0,0 @@
-/*
- * SPDX-License-Identifier: Apache-2.0
- * Copyright Red Hat Inc. and Hibernate Authors
- */
-
-/**
- * Support for {@linkplain org.hibernate.query.programmatic.SelectionSpecification}
- * and {@linkplain org.hibernate.query.programmatic.MutationSpecification}.
- *
- * @author Steve Ebersole
- */
-package org.hibernate.query.programmatic;
diff --git a/hibernate-core/src/main/java/org/hibernate/query/restriction/Restriction.java b/hibernate-core/src/main/java/org/hibernate/query/restriction/Restriction.java
index 9b83f4c88a80..1e07abc0b27d 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/restriction/Restriction.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/restriction/Restriction.java
@@ -19,8 +19,8 @@
 
 /**
  * A rule for restricting query results. This allows restrictions to be added to
- * a {@link org.hibernate.query.programmatic.SelectionSpecification} by calling
- * {@link org.hibernate.query.programmatic.SelectionSpecification#restrict(Restriction)}.
+ * a {@link org.hibernate.query.specification.SelectionSpecification} by calling
+ * {@link org.hibernate.query.specification.SelectionSpecification#restrict(Restriction)}.
  * <pre>
  * SelectionSpecification.create(Book.class)
  *         .restrict(Restriction.like(Book_.title, "%Hibernate%", false))
@@ -47,9 +47,9 @@
  *          is used by Hibernate Data Repositories to implement Jakarta Data
  *          query methods.
  *
- * @see org.hibernate.query.programmatic.SelectionSpecification
- * @see org.hibernate.query.programmatic.MutationSpecification
- * @see org.hibernate.query.programmatic.QuerySpecification#restrict(Restriction)
+ * @see org.hibernate.query.specification.SelectionSpecification
+ * @see org.hibernate.query.specification.MutationSpecification
+ * @see org.hibernate.query.specification.QuerySpecification#restrict(Restriction)
  *
  * @see Path
  * @see Order
diff --git a/hibernate-core/src/main/java/org/hibernate/query/programmatic/MutationSpecification.java b/hibernate-core/src/main/java/org/hibernate/query/specification/MutationSpecification.java
similarity index 97%
rename from hibernate-core/src/main/java/org/hibernate/query/programmatic/MutationSpecification.java
rename to hibernate-core/src/main/java/org/hibernate/query/specification/MutationSpecification.java
index 040bf802b4b2..8a97451f812e 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/programmatic/MutationSpecification.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/specification/MutationSpecification.java
@@ -2,7 +2,7 @@
  * SPDX-License-Identifier: Apache-2.0
  * Copyright Red Hat Inc. and Hibernate Authors
  */
-package org.hibernate.query.programmatic;
+package org.hibernate.query.specification;
 
 import jakarta.persistence.criteria.CommonAbstractCriteria;
 import jakarta.persistence.criteria.CriteriaUpdate;
@@ -14,7 +14,7 @@
 import org.hibernate.StatelessSession;
 import org.hibernate.query.IllegalMutationQueryException;
 import org.hibernate.query.MutationQuery;
-import org.hibernate.query.programmatic.internal.MutationSpecificationImpl;
+import org.hibernate.query.specification.internal.MutationSpecificationImpl;
 import org.hibernate.query.restriction.Restriction;
 
 /**
diff --git a/hibernate-core/src/main/java/org/hibernate/query/programmatic/QuerySpecification.java b/hibernate-core/src/main/java/org/hibernate/query/specification/QuerySpecification.java
similarity index 98%
rename from hibernate-core/src/main/java/org/hibernate/query/programmatic/QuerySpecification.java
rename to hibernate-core/src/main/java/org/hibernate/query/specification/QuerySpecification.java
index 98237021a80b..ff14ad197370 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/programmatic/QuerySpecification.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/specification/QuerySpecification.java
@@ -2,7 +2,7 @@
  * SPDX-License-Identifier: Apache-2.0
  * Copyright Red Hat Inc. and Hibernate Authors
  */
-package org.hibernate.query.programmatic;
+package org.hibernate.query.specification;
 
 import jakarta.persistence.EntityManager;
 import jakarta.persistence.criteria.CriteriaBuilder;
diff --git a/hibernate-core/src/main/java/org/hibernate/query/programmatic/SelectionSpecification.java b/hibernate-core/src/main/java/org/hibernate/query/specification/SelectionSpecification.java
similarity index 98%
rename from hibernate-core/src/main/java/org/hibernate/query/programmatic/SelectionSpecification.java
rename to hibernate-core/src/main/java/org/hibernate/query/specification/SelectionSpecification.java
index 7c9136c8512a..199ff2bf6d0f 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/programmatic/SelectionSpecification.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/specification/SelectionSpecification.java
@@ -2,7 +2,7 @@
  * SPDX-License-Identifier: Apache-2.0
  * Copyright Red Hat Inc. and Hibernate Authors
  */
-package org.hibernate.query.programmatic;
+package org.hibernate.query.specification;
 
 import jakarta.persistence.EntityManager;
 import jakarta.persistence.criteria.CriteriaQuery;
@@ -15,7 +15,7 @@
 import org.hibernate.query.IllegalSelectQueryException;
 import org.hibernate.query.Order;
 import org.hibernate.query.SelectionQuery;
-import org.hibernate.query.programmatic.internal.SelectionSpecificationImpl;
+import org.hibernate.query.specification.internal.SelectionSpecificationImpl;
 import org.hibernate.query.restriction.Path;
 import org.hibernate.query.restriction.Restriction;
 
diff --git a/hibernate-core/src/main/java/org/hibernate/query/programmatic/internal/MutationSpecificationImpl.java b/hibernate-core/src/main/java/org/hibernate/query/specification/internal/MutationSpecificationImpl.java
similarity index 98%
rename from hibernate-core/src/main/java/org/hibernate/query/programmatic/internal/MutationSpecificationImpl.java
rename to hibernate-core/src/main/java/org/hibernate/query/specification/internal/MutationSpecificationImpl.java
index 887f6790d72d..0d8eda40528a 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/programmatic/internal/MutationSpecificationImpl.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/specification/internal/MutationSpecificationImpl.java
@@ -2,7 +2,7 @@
  * SPDX-License-Identifier: Apache-2.0
  * Copyright Red Hat Inc. and Hibernate Authors
  */
-package org.hibernate.query.programmatic.internal;
+package org.hibernate.query.specification.internal;
 
 import jakarta.persistence.EntityManager;
 import jakarta.persistence.criteria.CriteriaBuilder;
@@ -15,7 +15,7 @@
 import org.hibernate.SharedSessionContract;
 import org.hibernate.StatelessSession;
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
-import org.hibernate.query.programmatic.MutationSpecification;
+import org.hibernate.query.specification.MutationSpecification;
 import org.hibernate.query.IllegalMutationQueryException;
 import org.hibernate.query.MutationQuery;
 import org.hibernate.query.restriction.Restriction;
diff --git a/hibernate-core/src/main/java/org/hibernate/query/programmatic/internal/SelectionSpecificationImpl.java b/hibernate-core/src/main/java/org/hibernate/query/specification/internal/SelectionSpecificationImpl.java
similarity index 77%
rename from hibernate-core/src/main/java/org/hibernate/query/programmatic/internal/SelectionSpecificationImpl.java
rename to hibernate-core/src/main/java/org/hibernate/query/specification/internal/SelectionSpecificationImpl.java
index 81a43203c30a..56d388150eb6 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/programmatic/internal/SelectionSpecificationImpl.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/specification/internal/SelectionSpecificationImpl.java
@@ -2,7 +2,7 @@
  * SPDX-License-Identifier: Apache-2.0
  * Copyright Red Hat Inc. and Hibernate Authors
  */
-package org.hibernate.query.programmatic.internal;
+package org.hibernate.query.specification.internal;
 
 import jakarta.persistence.EntityManager;
 import jakarta.persistence.criteria.CriteriaQuery;
@@ -13,10 +13,11 @@
 import org.hibernate.SharedSessionContract;
 import org.hibernate.StatelessSession;
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
+import org.hibernate.internal.util.collections.CollectionHelper;
 import org.hibernate.query.IllegalSelectQueryException;
 import org.hibernate.query.Order;
 import org.hibernate.query.SelectionQuery;
-import org.hibernate.query.programmatic.SelectionSpecification;
+import org.hibernate.query.specification.SelectionSpecification;
 import org.hibernate.query.restriction.Path;
 import org.hibernate.query.restriction.Restriction;
 import org.hibernate.query.spi.HqlInterpretation;
@@ -28,8 +29,11 @@
 import org.hibernate.query.sqm.tree.from.SqmRoot;
 import org.hibernate.query.sqm.tree.predicate.SqmPredicate;
 import org.hibernate.query.sqm.tree.select.SqmOrderByClause;
+import org.hibernate.query.sqm.tree.select.SqmSelectClause;
 import org.hibernate.query.sqm.tree.select.SqmSelectStatement;
+import org.hibernate.query.sqm.tree.select.SqmSelection;
 import org.hibernate.query.sqm.tree.select.SqmSortSpecification;
+import org.hibernate.type.descriptor.java.JavaType;
 
 import java.util.ArrayList;
 import java.util.List;
@@ -159,8 +163,8 @@ else if ( criteriaQuery != null ) {
 			var query = builder.createQuery( resultType );
 			var root = query.from( resultType );
 			query.select( root );
-			sqmRoot = (SqmRoot<T>) root;
-			sqmStatement = (SqmSelectStatement<T>) query;
+			sqmRoot = root;
+			sqmStatement = query;
 		}
 		specifications.forEach( consumer -> consumer.accept( sqmStatement, sqmRoot ) );
 		return sqmStatement;
@@ -222,7 +226,17 @@ private SqmRoot<T> extractRoot(SqmSelectStatement<T> sqmStatement, Class<T> resu
 		if ( sqmRoots.size() > 1 ) {
 			throw new QueryException( "Query defined multiple roots", hql );
 		}
+
 		final SqmRoot<?> sqmRoot = sqmRoots.iterator().next();
+		validateRoot( sqmRoot, resultType, hql );
+		// for later, to support select lists
+		//validateResultType( sqmStatement, sqmRoot, resultType, hql );
+
+		//noinspection unchecked
+		return (SqmRoot<T>) sqmRoot;
+	}
+
+	private void validateRoot(SqmRoot<?> sqmRoot, Class<T> resultType, String hql) {
 		if ( sqmRoot.getJavaType() != null
 			&& !Map.class.isAssignableFrom( sqmRoot.getJavaType() )
 			&& !resultType.isAssignableFrom( sqmRoot.getJavaType() ) ) {
@@ -236,7 +250,65 @@ private SqmRoot<T> extractRoot(SqmSelectStatement<T> sqmStatement, Class<T> resu
 					hql
 			);
 		}
-		//noinspection unchecked
-		return (SqmRoot<T>) sqmRoot;
+	}
+
+	/**
+	 * For future, allowing explicit select list.
+	 */
+	private void validateResultType(
+			SqmSelectStatement<T> sqmStatement,
+			SqmRoot<?> sqmRoot,
+			Class<T> resultType,
+			String hql) {
+		if ( resultType == null || Object.class.equals( resultType ) || resultType.isArray() ) {
+			// Nothing to validate in these cases
+			return;
+		}
+
+		final Class<?> rootJavaType = sqmRoot.getJavaType();
+		assert rootJavaType != null;
+
+		if ( Map.class.isAssignableFrom( rootJavaType ) ) {
+			if ( Map.class.isAssignableFrom( resultType ) ) {
+				// dynamic model and Map was requested, totally fine
+				return;
+			}
+		}
+
+		final SqmSelectClause sqmSelectClause = sqmStatement.getQuerySpec().getSelectClause();
+		final List<SqmSelection<?>> sqmSelections = sqmSelectClause.getSelections();
+		if ( CollectionHelper.isEmpty( sqmSelections ) ) {
+			// implicit select clause, verify that resultType matches the root type
+			if ( resultType.isAssignableFrom( rootJavaType ) ) {
+				// it does, we are fine
+				return;
+			}
+		}
+		else if ( sqmSelections.size() > 1 ) {
+			// we have to assume we can.
+			// the Query will ultimately complain if not, but this is the most we can do here
+			return;
+		}
+		else {
+			assert sqmSelections.size() == 1;
+			final JavaType<?> nodeJavaType = sqmSelections.get( 0 ).getNodeJavaType();
+			if ( nodeJavaType == null ) {
+				// again, we have to assume we can
+				return;
+			}
+			else if ( resultType.isAssignableFrom( nodeJavaType.getJavaTypeClass() ) ) {
+				// it matches the selection type, we are fine
+				return;
+			}
+		}
+
+		throw new QueryException(
+				String.format(
+						Locale.ROOT,
+						"Specified result-type [%s] is not valid for this SelectionSpecification",
+						resultType.getName()
+				),
+				hql
+		);
 	}
 }
diff --git a/hibernate-core/src/main/java/org/hibernate/query/specification/package-info.java b/hibernate-core/src/main/java/org/hibernate/query/specification/package-info.java
new file mode 100644
index 000000000000..1614a42fc125
--- /dev/null
+++ b/hibernate-core/src/main/java/org/hibernate/query/specification/package-info.java
@@ -0,0 +1,13 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+
+/**
+ * Support for {@linkplain org.hibernate.query.specification.SelectionSpecification}
+ * and {@linkplain org.hibernate.query.specification.MutationSpecification} which
+ * is similar in concept to criteria queries, but focused on ease-of-use and less verbosity.
+ *
+ * @author Steve Ebersole
+ */
+package org.hibernate.query.specification;
diff --git a/hibernate-core/src/main/java/org/hibernate/query/spi/AbstractQuery.java b/hibernate-core/src/main/java/org/hibernate/query/spi/AbstractQuery.java
index 51cd37f39cfa..09b8b2b7fb64 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/spi/AbstractQuery.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/spi/AbstractQuery.java
@@ -9,7 +9,6 @@
 import java.util.Collection;
 import java.util.Date;
 import java.util.HashSet;
-import java.util.List;
 import java.util.Map;
 import java.util.Set;
 
@@ -36,8 +35,6 @@
 import org.hibernate.query.IllegalQueryOperationException;
 import org.hibernate.query.KeyedPage;
 import org.hibernate.query.KeyedResultList;
-import org.hibernate.query.Order;
-import org.hibernate.query.Query;
 import org.hibernate.query.QueryParameter;
 import org.hibernate.query.ResultListTransformer;
 import org.hibernate.query.TupleTransformer;
@@ -290,16 +287,6 @@ public QueryImplementor<R> setLockMode(LockModeType lockModeType) {
 		return this;
 	}
 
-	@Override
-	public Query<R> setOrder(List<? extends Order<? super R>> orders) {
-		throw new UnsupportedOperationException( "Should be implemented by " + this.getClass().getName() );
-	}
-
-	@Override
-	public Query<R> setOrder(Order<? super R> order) {
-		throw new UnsupportedOperationException( "Should be implemented by " + this.getClass().getName() );
-	}
-
 	@Override
 	public String getComment() {
 		return super.getComment();
diff --git a/hibernate-core/src/main/java/org/hibernate/query/sql/internal/NativeQueryImpl.java b/hibernate-core/src/main/java/org/hibernate/query/sql/internal/NativeQueryImpl.java
index 21e96b8a95a6..51ebd4aff58f 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/sql/internal/NativeQueryImpl.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/sql/internal/NativeQueryImpl.java
@@ -51,7 +51,6 @@
 import org.hibernate.query.KeyedPage;
 import org.hibernate.query.KeyedResultList;
 import org.hibernate.query.NativeQuery;
-import org.hibernate.query.Order;
 import org.hibernate.query.PathException;
 import org.hibernate.query.Query;
 import org.hibernate.query.QueryParameter;
@@ -1651,15 +1650,6 @@ public NativeQueryImplementor<R> setFirstResult(int startPosition) {
 		return this;
 	}
 
-	@Override
-	public Query<R> setOrder(List<? extends Order<? super R>> orderList) {
-		throw new UnsupportedOperationException("Ordering not currently supported for native queries");
-	}
-
-	@Override
-	public Query<R> setOrder(Order<? super R> order) {
-		throw new UnsupportedOperationException("Ordering not currently supported for native queries");
-	}
 
 	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 	// Hints
diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/AbstractSqmSelectionQuery.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/AbstractSqmSelectionQuery.java
index db696069406b..748f570d6bd8 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/AbstractSqmSelectionQuery.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/AbstractSqmSelectionQuery.java
@@ -12,7 +12,6 @@
 import org.hibernate.query.IllegalSelectQueryException;
 import org.hibernate.query.KeyedPage;
 import org.hibernate.query.KeyedResultList;
-import org.hibernate.query.Order;
 import org.hibernate.query.Page;
 import org.hibernate.query.QueryLogging;
 import org.hibernate.query.SelectionQuery;
@@ -27,7 +26,6 @@
 import org.hibernate.query.spi.QueryParameterBinding;
 import org.hibernate.query.spi.QueryParameterBindings;
 import org.hibernate.query.spi.SelectQueryPlan;
-import org.hibernate.query.sqm.SqmQuerySource;
 import org.hibernate.query.sqm.spi.NamedSqmQueryMemento;
 import org.hibernate.query.sqm.tree.SqmStatement;
 import org.hibernate.query.sqm.tree.expression.JpaCriteriaParameter;
@@ -44,15 +42,12 @@
 import jakarta.persistence.TupleElement;
 import jakarta.persistence.criteria.CompoundSelection;
 
-import static java.util.stream.Collectors.toList;
 import static org.hibernate.cfg.QuerySettings.FAIL_ON_PAGINATION_OVER_COLLECTION_FETCH;
 import static org.hibernate.query.KeyedPage.KeyInterpretation.KEY_OF_FIRST_ON_NEXT_PAGE;
 import static org.hibernate.query.sqm.internal.KeyedResult.collectKeys;
 import static org.hibernate.query.sqm.internal.KeyedResult.collectResults;
 import static org.hibernate.query.sqm.internal.SqmUtil.isHqlTuple;
 import static org.hibernate.query.sqm.internal.SqmUtil.isSelectionAssignableToResultType;
-import static org.hibernate.query.sqm.internal.SqmUtil.sortSpecification;
-import static org.hibernate.query.sqm.tree.SqmCopyContext.noParamCopyContext;
 
 /**
  * @author Gavin King
@@ -176,41 +171,6 @@ protected <T> void bindCriteriaParameter(SqmJpaCriteriaParameterWrapper<T> sqmPa
 		}
 	}
 
-	@Override
-	public SelectionQuery<R> setOrder(List<? extends Order<? super R>> orderList) {
-		final SqmSelectStatement<R> selectStatement = getSqmSelectStatement().copy( noParamCopyContext( SqmQuerySource.CRITERIA ) );
-		selectStatement.orderBy( orderList.stream().map( order -> sortSpecification( selectStatement, order ) )
-				.collect( toList() ) );
-		// TODO: when the QueryInterpretationCache can handle caching criteria queries,
-		//       simply cache the new SQM as if it were a criteria query, and remove this:
-		getQueryOptions().setQueryPlanCachingEnabled( false );
-		setSqmStatement( selectStatement );
-		return this;
-	}
-
-
-	@Override
-	public SelectionQuery<R> setOrder(Order<? super R> order) {
-		final SqmSelectStatement<R> selectStatement = getSqmSelectStatement().copy( noParamCopyContext( SqmQuerySource.CRITERIA ) );
-		selectStatement.orderBy( sortSpecification( selectStatement, order ) );
-		// TODO: when the QueryInterpretationCache can handle caching criteria queries,
-		//       simply cache the new SQM as if it were a criteria query, and remove this:
-		getQueryOptions().setQueryPlanCachingEnabled( false );
-		setSqmStatement( selectStatement );
-		return this;
-	}
-
-//	@Override
-//	public SelectionQuery<R> addRestriction(Restriction<? super R> restriction) {
-//		final SqmSelectStatement<R> selectStatement = getSqmSelectStatement().copy( noParamCopyContext( SqmQuerySource.CRITERIA ) );
-//		restriction.apply( selectStatement, selectStatement.<R>getRoot( 0, getExpectedResultType() ) );
-//		// TODO: when the QueryInterpretationCache can handle caching criteria queries,
-//		//       simply cache the new SQM as if it were a criteria query, and remove this:
-//		getQueryOptions().setQueryPlanCachingEnabled( false );
-//		setSqmStatement( selectStatement );
-//		return this;
-//	}
-
 	@Override
 	public SelectionQuery<R> setPage(Page page) {
 		setMaxResults( page.getMaxResults() );
diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/QuerySqmImpl.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/QuerySqmImpl.java
index 46f061420889..3c7a4fadc014 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/QuerySqmImpl.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/QuerySqmImpl.java
@@ -34,7 +34,6 @@
 import org.hibernate.persister.entity.EntityPersister;
 import org.hibernate.query.BindableType;
 import org.hibernate.query.IllegalQueryOperationException;
-import org.hibernate.query.Order;
 import org.hibernate.query.Page;
 import org.hibernate.query.Query;
 import org.hibernate.query.QueryFlushMode;
@@ -780,18 +779,6 @@ public LockModeType getLockMode() {
 		return getLockOptions().getLockMode().toJpaLockMode();
 	}
 
-	@Override
-	public Query<R> setOrder(Order<? super R> order) {
-		super.setOrder(order);
-		return this;
-	}
-
-	@Override
-	public Query<R> setOrder(List<? extends Order<? super R>> orders) {
-		super.setOrder(orders);
-		return this;
-	}
-
 	@Override
 	public Query<R> setPage(Page page) {
 		super.setPage(page);
diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/spi/DelegatingSqmSelectionQueryImplementor.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/spi/DelegatingSqmSelectionQueryImplementor.java
index 0930c184f9a5..1c706d3413ee 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/sqm/spi/DelegatingSqmSelectionQueryImplementor.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/sqm/spi/DelegatingSqmSelectionQueryImplementor.java
@@ -24,7 +24,6 @@
 import org.hibernate.query.BindableType;
 import org.hibernate.query.KeyedPage;
 import org.hibernate.query.KeyedResultList;
-import org.hibernate.query.Order;
 import org.hibernate.query.Page;
 import org.hibernate.query.ParameterMetadata;
 import org.hibernate.query.QueryFlushMode;
@@ -295,20 +294,6 @@ public SqmSelectionQueryImplementor<R> setLockMode(String alias, LockMode lockMo
 		return this;
 	}
 
-	@Override
-	@Incubating
-	public SqmSelectionQueryImplementor<R> setOrder(List<? extends Order<? super R>> orders) {
-		getDelegate().setOrder( orders );
-		return this;
-	}
-
-	@Override
-	@Incubating
-	public SqmSelectionQueryImplementor<R> setOrder(Order<? super R> order) {
-		getDelegate().setOrder( order );
-		return this;
-	}
-
 	@Override
 	public SqmSelectionQueryImplementor<R> setFollowOnLocking(boolean enable) {
 		getDelegate().setFollowOnLocking( enable );
diff --git a/hibernate-core/src/test/java/org/hibernate/orm/test/join/JoinAndFetchWithCriteriaSelectionQueryTest.java b/hibernate-core/src/test/java/org/hibernate/orm/test/join/JoinAndFetchWithCriteriaSelectionQueryTest.java
index 683b83515a17..582b1df3ee63 100644
--- a/hibernate-core/src/test/java/org/hibernate/orm/test/join/JoinAndFetchWithCriteriaSelectionQueryTest.java
+++ b/hibernate-core/src/test/java/org/hibernate/orm/test/join/JoinAndFetchWithCriteriaSelectionQueryTest.java
@@ -12,6 +12,7 @@
 import org.hibernate.metamodel.model.domain.EntityDomainType;
 import org.hibernate.query.Order;
 
+import org.hibernate.query.specification.SelectionSpecification;
 import org.hibernate.testing.jdbc.SQLStatementInspector;
 import org.hibernate.testing.orm.junit.DomainModel;
 import org.hibernate.testing.orm.junit.Jira;
@@ -135,9 +136,9 @@ void fetchAfterJoinWithoutWhereClauseTest(SessionFactoryScope scope) {
 			SingularAttribute<? super Book, ?> title = bookType.findSingularAttribute( "title" );
 			query.select( from ).distinct( true );
 
-			List<Book> books = session
-					.createSelectionQuery( query )
-					.setOrder( Order.asc( title ) )
+			List<Book> books = SelectionSpecification.create( query )
+					.sort( Order.asc( title ) )
+					.createQuery( session )
 					.getResultList();
 			assertThat( books ).containsExactly( leftHand, timeWar );
 			assertThat( Hibernate.isInitialized( books.get( 0 ).getAuthors() ) ).isTrue();
@@ -169,9 +170,9 @@ void fetchBeforeJoinWithoutWhereClauseTest(SessionFactoryScope scope) {
 			SingularAttribute<? super Book, ?> title = bookType.findSingularAttribute( "title" );
 			query.select( from ).distinct( true );
 
-			List<Book> books = session
-					.createSelectionQuery( query )
-					.setOrder( Order.asc( title ) )
+			List<Book> books = SelectionSpecification.create( query )
+					.sort( Order.asc( title ) )
+					.createQuery( session )
 					.getResultList();
 			assertThat( books ).containsExactly( leftHand, timeWar );
 			assertThat( Hibernate.isInitialized( books.get( 0 ).getAuthors() ) ).isTrue();
diff --git a/hibernate-core/src/test/java/org/hibernate/orm/test/query/dynamic/SimpleQuerySpecificationTests.java b/hibernate-core/src/test/java/org/hibernate/orm/test/query/dynamic/SimpleQuerySpecificationTests.java
index 334d759633c7..0c8ddfe5b998 100644
--- a/hibernate-core/src/test/java/org/hibernate/orm/test/query/dynamic/SimpleQuerySpecificationTests.java
+++ b/hibernate-core/src/test/java/org/hibernate/orm/test/query/dynamic/SimpleQuerySpecificationTests.java
@@ -12,8 +12,8 @@
 import org.hibernate.query.IllegalSelectQueryException;
 import org.hibernate.query.Order;
 import org.hibernate.query.criteria.CriteriaDefinition;
-import org.hibernate.query.programmatic.MutationSpecification;
-import org.hibernate.query.programmatic.SelectionSpecification;
+import org.hibernate.query.specification.MutationSpecification;
+import org.hibernate.query.specification.SelectionSpecification;
 import org.hibernate.query.range.Range;
 import org.hibernate.query.restriction.Path;
 import org.hibernate.query.restriction.Restriction;
diff --git a/hibernate-core/src/test/java/org/hibernate/orm/test/query/order/OrderTest.java b/hibernate-core/src/test/java/org/hibernate/orm/test/query/order/OrderTest.java
index 51108f40f731..0787460df034 100644
--- a/hibernate-core/src/test/java/org/hibernate/orm/test/query/order/OrderTest.java
+++ b/hibernate-core/src/test/java/org/hibernate/orm/test/query/order/OrderTest.java
@@ -9,14 +9,17 @@
 import jakarta.persistence.metamodel.SingularAttribute;
 import org.hibernate.metamodel.model.domain.EntityDomainType;
 import org.hibernate.query.Order;
+import org.hibernate.query.specification.SelectionSpecification;
 import org.hibernate.testing.orm.junit.DomainModel;
+import org.hibernate.testing.orm.junit.NotImplementedYet;
 import org.hibernate.testing.orm.junit.SessionFactory;
 import org.hibernate.testing.orm.junit.SessionFactoryScope;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
 import java.util.List;
 
-import static java.util.stream.Collectors.toList;
 import static org.hibernate.query.Order.asc;
 import static org.hibernate.query.Order.by;
 import static org.hibernate.query.Order.desc;
@@ -24,440 +27,428 @@
 import static org.hibernate.query.SortDirection.DESCENDING;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
+@SuppressWarnings("JUnitMalformedDeclaration")
 @SessionFactory
 @DomainModel(annotatedClasses = OrderTest.Book.class)
 public class OrderTest {
 
-	@Test void testAscendingDescending(SessionFactoryScope scope) {
-		scope.inTransaction( session -> session.createMutationQuery("delete Book").executeUpdate() );
+	@BeforeEach
+	void createTestData(SessionFactoryScope scope) {
 		scope.inTransaction( session -> {
 			session.persist(new Book("9781932394153", "Hibernate in Action"));
 			session.persist(new Book("9781617290459", "Java Persistence with Hibernate"));
 		});
+	}
+
+	@AfterEach
+	void tearDown(SessionFactoryScope scope) {
+		scope.dropData();
+	}
+
+	@Test void testAscendingDescending(SessionFactoryScope scope) {
 		EntityDomainType<Book> bookType = scope.getSessionFactory().getJpaMetamodel().findEntityType(Book.class);
 		SingularAttribute<? super Book, ?> title = bookType.findSingularAttribute("title");
 		SingularAttribute<? super Book, ?> isbn = bookType.findSingularAttribute("isbn");
 		scope.inSession(session -> {
-			List<String> titlesAsc = session.createSelectionQuery("from Book", Book.class)
-					.setOrder(asc(title))
+			List<String> titlesAsc = SelectionSpecification.create( Book.class, "from Book" )
+					.sort(asc(title))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesAsc.get(0));
 			assertEquals("Java Persistence with Hibernate", titlesAsc.get(1));
 
-			List<String> titlesDesc = session.createSelectionQuery("from Book", Book.class)
-					.setOrder(desc(title))
+			List<String> titlesDesc = SelectionSpecification.create( Book.class, "from Book" )
+					.sort(desc(title))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesDesc.get(1));
 			assertEquals("Java Persistence with Hibernate", titlesDesc.get(0));
 
-			List<String> isbnAsc = session.createSelectionQuery("from Book", Book.class)
-					.setOrder(List.of(asc(isbn), desc(title)))
+			List<String> isbnAsc = SelectionSpecification.create( Book.class, "from Book" )
+					.sort(asc(isbn))
+					.sort(desc(title))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", isbnAsc.get(1));
 			assertEquals("Java Persistence with Hibernate", isbnAsc.get(0));
 
-			List<String> isbnDesc = session.createSelectionQuery("from Book", Book.class)
-					.setOrder(List.of(desc(isbn), desc(title)))
+			List<String> isbnDesc = SelectionSpecification.create( Book.class, "from Book" )
+					.sort(desc(isbn))
+					.sort(desc(title))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", isbnDesc.get(0));
 			assertEquals("Java Persistence with Hibernate", isbnDesc.get(1));
 
-//            titlesAsc = session.createSelectionQuery("from Book order by isbn asc", Book.class)
-//                    .setOrder(asc(title))
-//                    .getResultList()
-//                    .stream().map(book -> book.title)
-//                    .collect(toList());
-//            assertEquals("Hibernate in Action", titlesAsc.get(1));
-//            assertEquals("Java Persistence with Hibernate", titlesAsc.get(0));
-			titlesAsc = session.createSelectionQuery("from Book order by isbn asc", Book.class)
-//                    .setOrder(emptyList())
-					.setOrder(asc(title))
+			titlesAsc = SelectionSpecification.create( Book.class, "from Book order by isbn asc" )
+					.resort(asc(title))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesAsc.get(0));
 			assertEquals("Java Persistence with Hibernate", titlesAsc.get(1));
 		});
 	}
 
 	@Test void testAscendingDescendingWithPositionalParam(SessionFactoryScope scope) {
-		scope.inTransaction( session -> session.createMutationQuery("delete Book").executeUpdate() );
-		scope.inTransaction( session -> {
-			session.persist(new Book("9781932394153", "Hibernate in Action"));
-			session.persist(new Book("9781617290459", "Java Persistence with Hibernate"));
-		});
 		EntityDomainType<Book> bookType = scope.getSessionFactory().getJpaMetamodel().findEntityType(Book.class);
 		SingularAttribute<? super Book, ?> title = bookType.findSingularAttribute("title");
 		SingularAttribute<? super Book, ?> isbn = bookType.findSingularAttribute("isbn");
 		scope.inSession(session -> {
-			List<String> titlesAsc = session.createSelectionQuery("from Book where title like ?1", Book.class)
+			List<String> titlesAsc = SelectionSpecification.create( Book.class, "from Book where title like ?1" )
+					.sort(asc(title))
+					.createQuery( session )
 					.setParameter(1, "%Hibernate%")
-					.setOrder(asc(title))
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesAsc.get(0));
 			assertEquals("Java Persistence with Hibernate", titlesAsc.get(1));
 
-			List<String> titlesDesc = session.createSelectionQuery("from Book where title like ?1", Book.class)
+			List<String> titlesDesc = SelectionSpecification.create(Book.class, "from Book where title like ?1")
+					.sort(Order.desc(title))
+					.createQuery( session )
 					.setParameter(1, "%Hibernate%")
-					.setOrder(Order.desc(title))
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesDesc.get(1));
 			assertEquals("Java Persistence with Hibernate", titlesDesc.get(0));
 
-			List<String> isbnAsc = session.createSelectionQuery("from Book where title like ?1", Book.class)
+			List<String> isbnAsc = SelectionSpecification.create(Book.class, "from Book where title like ?1")
+					.sort(asc(isbn))
+					.sort(desc(title))
+					.createQuery( session )
 					.setParameter(1, "%Hibernate%")
-					.setOrder(List.of(asc(isbn), desc(title)))
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", isbnAsc.get(1));
 			assertEquals("Java Persistence with Hibernate", isbnAsc.get(0));
 
-			List<String> isbnDesc = session.createSelectionQuery("from Book where title like ?1", Book.class)
+			List<String> isbnDesc = SelectionSpecification.create(Book.class, "from Book where title like ?1")
+					.sort(desc(isbn))
+					.sort(desc(title))
+					.createQuery( session )
 					.setParameter(1, "%Hibernate%")
-					.setOrder(List.of(desc(isbn), desc(title)))
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", isbnDesc.get(0));
 			assertEquals("Java Persistence with Hibernate", isbnDesc.get(1));
 
-//            titlesAsc = session.createSelectionQuery("from Book where title like ?1 order by isbn asc", Book.class)
-//                    .setParameter(1, "%Hibernate%")
-//                    .setOrder(asc(title))
-//                    .getResultList()
-//                    .stream().map(book -> book.title)
-//                    .collect(toList());
-//            assertEquals("Hibernate in Action", titlesAsc.get(1));
-//            assertEquals("Java Persistence with Hibernate", titlesAsc.get(0));
-			titlesAsc = session.createSelectionQuery("from Book where title like ?1 order by isbn asc", Book.class)
+			titlesAsc = SelectionSpecification.create(Book.class, "from Book where title like ?1 order by isbn asc")
+					.resort(asc(title))
+					.createQuery( session )
 					.setParameter(1, "%Hibernate%")
-//                    .setOrder(emptyList())
-					.setOrder(asc(title))
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesAsc.get(0));
 			assertEquals("Java Persistence with Hibernate", titlesAsc.get(1));
 		});
 	}
 
 	@Test void testAscendingDescendingWithNamedParam(SessionFactoryScope scope) {
-		scope.inTransaction( session -> session.createMutationQuery("delete Book").executeUpdate() );
-		scope.inTransaction( session -> {
-			session.persist(new Book("9781932394153", "Hibernate in Action"));
-			session.persist(new Book("9781617290459", "Java Persistence with Hibernate"));
-		});
 		EntityDomainType<Book> bookType = scope.getSessionFactory().getJpaMetamodel().findEntityType(Book.class);
 		SingularAttribute<? super Book, ?> title = bookType.findSingularAttribute("title");
 		SingularAttribute<? super Book, ?> isbn = bookType.findSingularAttribute("isbn");
 		scope.inSession(session -> {
-			List<String> titlesAsc = session.createSelectionQuery("from Book where title like :title", Book.class)
+			List<String> titlesAsc = SelectionSpecification.create(Book.class, "from Book where title like :title")
+					.sort(asc(title))
+					.createQuery( session )
 					.setParameter("title", "%Hibernate%")
-					.setOrder(asc(title))
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesAsc.get(0));
 			assertEquals("Java Persistence with Hibernate", titlesAsc.get(1));
 
-			List<String> titlesDesc = session.createSelectionQuery("from Book where title like :title", Book.class)
+			List<String> titlesDesc = SelectionSpecification.create(Book.class,"from Book where title like :title")
+					.sort(desc(title))
+					.createQuery( session )
 					.setParameter("title", "%Hibernate%")
-					.setOrder(desc(title))
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesDesc.get(1));
 			assertEquals("Java Persistence with Hibernate", titlesDesc.get(0));
 
-			List<String> isbnAsc = session.createSelectionQuery("from Book where title like :title", Book.class)
+			List<String> isbnAsc = SelectionSpecification.create(Book.class, "from Book where title like :title")
+					.sort(asc(isbn))
+					.sort(desc(title))
+					.createQuery( session )
 					.setParameter("title", "%Hibernate%")
-					.setOrder(List.of(asc(isbn), desc(title)))
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", isbnAsc.get(1));
 			assertEquals("Java Persistence with Hibernate", isbnAsc.get(0));
 
-			List<String> isbnDesc = session.createSelectionQuery("from Book where title like :title", Book.class)
+			List<String> isbnDesc = SelectionSpecification.create(Book.class, "from Book where title like :title")
+					.sort(desc(isbn))
+					.sort(desc(title))
+					.createQuery( session )
 					.setParameter("title", "%Hibernate%")
-					.setOrder(List.of(desc(isbn), desc(title)))
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", isbnDesc.get(0));
 			assertEquals("Java Persistence with Hibernate", isbnDesc.get(1));
 
-//            titlesAsc = session.createSelectionQuery("from Book where title like :title order by isbn asc", Book.class)
-//                    .setParameter("title", "%Hibernate%")
-//                    .setOrder(asc(title))
-//                    .getResultList()
-//                    .stream().map(book -> book.title)
-//                    .collect(toList());
-//            assertEquals("Hibernate in Action", titlesAsc.get(1));
-//            assertEquals("Java Persistence with Hibernate", titlesAsc.get(0));
-			titlesAsc = session.createSelectionQuery("from Book where title like :title order by isbn asc", Book.class)
+			titlesAsc = SelectionSpecification.create(Book.class, "from Book where title like :title order by isbn asc")
+					.resort(asc(title))
+					.createQuery( session )
 					.setParameter("title", "%Hibernate%")
-//                    .setOrder(emptyList())
-					.setOrder(asc(title))
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesAsc.get(0));
 			assertEquals("Java Persistence with Hibernate", titlesAsc.get(1));
 		});
 	}
 
+	@NotImplementedYet(reason = "Support for explicit select lists not implemented yet for SelectionSpecification")
 	@Test void testAscendingDescendingBySelectElement(SessionFactoryScope scope) {
-		scope.inTransaction( session -> session.createMutationQuery("delete Book").executeUpdate() );
-		scope.inTransaction( session -> {
-			session.persist(new Book("9781932394153", "Hibernate in Action"));
-			session.persist(new Book("9781617290459", "Java Persistence with Hibernate"));
-		});
 		scope.inSession(session -> {
-			List<?> titlesAsc = session.createSelectionQuery("select isbn, title from Book", Object[].class)
-					.setOrder(asc(2))
+			List<?> titlesAsc = SelectionSpecification.create(Object[].class, "select isbn, title from Book")
+					.sort(asc(2))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book[1])
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesAsc.get(0));
 			assertEquals("Java Persistence with Hibernate", titlesAsc.get(1));
 
-			List<?> titlesDesc = session.createSelectionQuery("select isbn, title from Book", Object[].class)
-					.setOrder(desc(2))
+			List<?> titlesDesc = SelectionSpecification.create(Object[].class, "select isbn, title from Book")
+					.sort(desc(2))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book[1])
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesDesc.get(1));
 			assertEquals("Java Persistence with Hibernate", titlesDesc.get(0));
 
-			List<?> isbnAsc = session.createSelectionQuery("select isbn, title from Book", Object[].class)
-					.setOrder(List.of(asc(1), desc(2)))
+			List<?> isbnAsc = SelectionSpecification.create(Object[].class, "select isbn, title from Book")
+					.sort(asc(1))
+					.sort(desc(2))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book[1])
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", isbnAsc.get(1));
 			assertEquals("Java Persistence with Hibernate", isbnAsc.get(0));
 
-			List<?> isbnDesc = session.createSelectionQuery("select isbn, title from Book", Object[].class)
-					.setOrder(List.of(desc(1), desc(2)))
+			List<?> isbnDesc = SelectionSpecification.create(Object[].class, "select isbn, title from Book")
+					.sort(desc(1))
+					.sort(desc(2))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book[1])
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", isbnDesc.get(0));
 			assertEquals("Java Persistence with Hibernate", isbnDesc.get(1));
 		});
 	}
 
 	@Test void testAscendingDescendingCaseInsensitive(SessionFactoryScope scope) {
-		scope.inTransaction( session -> session.createMutationQuery("delete Book").executeUpdate() );
-		scope.inTransaction( session -> {
-			session.persist(new Book("9781932394153", "Hibernate in Action"));
-			session.persist(new Book("9781617290459", "Java Persistence with Hibernate"));
-		});
 		EntityDomainType<Book> bookType = scope.getSessionFactory().getJpaMetamodel().findEntityType(Book.class);
 		SingularAttribute<? super Book, ?> title = bookType.findSingularAttribute("title");
 		SingularAttribute<? super Book, ?> isbn = bookType.findSingularAttribute("isbn");
 		scope.inSession(session -> {
-			List<String> titlesAsc = session.createSelectionQuery("from Book", Book.class)
-					.setOrder(asc(title).ignoringCase())
+			List<String> titlesAsc = SelectionSpecification.create(Book.class, "from Book")
+					.sort(asc(title).ignoringCase())
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesAsc.get(0));
 			assertEquals("Java Persistence with Hibernate", titlesAsc.get(1));
 
-			List<String> titlesDesc = session.createSelectionQuery("from Book", Book.class)
-					.setOrder(desc(title).ignoringCase())
+			List<String> titlesDesc = SelectionSpecification.create(Book.class, "from Book")
+					.sort(desc(title).ignoringCase())
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesDesc.get(1));
 			assertEquals("Java Persistence with Hibernate", titlesDesc.get(0));
 
-			List<String> isbnAsc = session.createSelectionQuery("from Book", Book.class)
-					.setOrder(List.of(asc(isbn).ignoringCase(), desc(title).ignoringCase()))
+			List<String> isbnAsc = SelectionSpecification.create(Book.class, "from Book")
+					.sort(asc(isbn).ignoringCase())
+					.sort(desc(title).ignoringCase())
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", isbnAsc.get(1));
 			assertEquals("Java Persistence with Hibernate", isbnAsc.get(0));
 
-			List<String> isbnDesc = session.createSelectionQuery("from Book", Book.class)
-					.setOrder(List.of(desc(isbn).ignoringCase(), desc(title).ignoringCase()))
+			List<String> isbnDesc = SelectionSpecification.create(Book.class, "from Book")
+					.sort(desc(isbn).ignoringCase())
+					.sort(desc(title).ignoringCase())
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", isbnDesc.get(0));
 			assertEquals("Java Persistence with Hibernate", isbnDesc.get(1));
 
-//            titlesAsc = session.createSelectionQuery("from Book order by isbn asc", Book.class)
-//                    .setOrder(asc(title))
-//                    .getResultList()
-//                    .stream().map(book -> book.title)
-//                    .collect(toList());
-//            assertEquals("Hibernate in Action", titlesAsc.get(1));
-//            assertEquals("Java Persistence with Hibernate", titlesAsc.get(0));
-			titlesAsc = session.createSelectionQuery("from Book order by isbn asc", Book.class)
-//                    .setOrder(emptyList())
-					.setOrder(asc(title).ignoringCase())
+			titlesAsc = SelectionSpecification.create(Book.class, "from Book order by isbn asc")
+					.resort(asc(title).ignoringCase())
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesAsc.get(0));
 			assertEquals("Java Persistence with Hibernate", titlesAsc.get(1));
 		});
 	}
 
 	@Test void testAscendingDescendingCaseInsensitiveLongForm(SessionFactoryScope scope) {
-		scope.inTransaction( session -> session.createMutationQuery("delete Book").executeUpdate() );
-		scope.inTransaction( session -> {
-			session.persist(new Book("9781932394153", "Hibernate in Action"));
-			session.persist(new Book("9781617290459", "Java Persistence with Hibernate"));
-		});
 		EntityDomainType<Book> bookType = scope.getSessionFactory().getJpaMetamodel().findEntityType(Book.class);
 		SingularAttribute<? super Book, ?> title = bookType.findSingularAttribute("title");
 		SingularAttribute<? super Book, ?> isbn = bookType.findSingularAttribute("isbn");
 		scope.inSession(session -> {
-			List<String> titlesAsc = session.createSelectionQuery("from Book", Book.class)
-					.setOrder(by(title, ASCENDING, true))
+			List<String> titlesAsc = SelectionSpecification.create(Book.class, "from Book")
+					.sort(by(title, ASCENDING, true))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesAsc.get(0));
 			assertEquals("Java Persistence with Hibernate", titlesAsc.get(1));
 
-			List<String> titlesDesc = session.createSelectionQuery("from Book", Book.class)
-					.setOrder(by(title, DESCENDING, true))
+			List<String> titlesDesc = SelectionSpecification.create(Book.class, "from Book")
+					.sort(by(title, DESCENDING, true))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesDesc.get(1));
 			assertEquals("Java Persistence with Hibernate", titlesDesc.get(0));
 
-			List<String> isbnAsc = session.createSelectionQuery("from Book", Book.class)
-					.setOrder(List.of(by(isbn, ASCENDING, true), by(title, DESCENDING, true)))
+			List<String> isbnAsc = SelectionSpecification.create(Book.class, "from Book")
+					.sort(by(isbn, ASCENDING, true))
+					.sort(by(title, DESCENDING, true))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", isbnAsc.get(1));
 			assertEquals("Java Persistence with Hibernate", isbnAsc.get(0));
 
-			List<String> isbnDesc = session.createSelectionQuery("from Book", Book.class)
-					.setOrder(List.of(by(isbn, DESCENDING, true), by(title, DESCENDING, true)))
+			List<String> isbnDesc = SelectionSpecification.create(Book.class, "from Book")
+					.sort(by(isbn, DESCENDING, true))
+					.sort(by(title, DESCENDING, true))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", isbnDesc.get(0));
 			assertEquals("Java Persistence with Hibernate", isbnDesc.get(1));
 
-//            titlesAsc = session.createSelectionQuery("from Book order by isbn asc", Book.class)
-//                    .setOrder(asc(title))
-//                    .getResultList()
-//                    .stream().map(book -> book.title)
-//                    .collect(toList());
-//            assertEquals("Hibernate in Action", titlesAsc.get(1));
-//            assertEquals("Java Persistence with Hibernate", titlesAsc.get(0));
-			titlesAsc = session.createSelectionQuery("from Book order by isbn asc", Book.class)
-//                    .setOrder(emptyList())
-					.setOrder(by(title, ASCENDING, true))
+			titlesAsc = SelectionSpecification.create(Book.class, "from Book order by isbn asc")
+					.resort(by(title, ASCENDING, true))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book.title)
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesAsc.get(0));
 			assertEquals("Java Persistence with Hibernate", titlesAsc.get(1));
 		});
 	}
 
+	@NotImplementedYet(reason = "Support for explicit select lists not implemented yet for SelectionSpecification")
 	@Test void testAscendingDescendingBySelectElementCaseInsensitive(SessionFactoryScope scope) {
-		scope.inTransaction( session -> session.createMutationQuery("delete Book").executeUpdate() );
-		scope.inTransaction( session -> {
-			session.persist(new Book("9781932394153", "Hibernate in Action"));
-			session.persist(new Book("9781617290459", "Java Persistence with Hibernate"));
-		});
 		scope.inSession(session -> {
-			List<?> titlesAsc = session.createSelectionQuery("select isbn, title from Book", Object[].class)
-					.setOrder(asc(2).ignoringCase())
+			List<?> titlesAsc = SelectionSpecification.create(Object[].class, "select isbn, title from Book")
+					.sort(asc(2).ignoringCase())
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book[1])
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesAsc.get(0));
 			assertEquals("Java Persistence with Hibernate", titlesAsc.get(1));
 
-			List<?> titlesDesc = session.createSelectionQuery("select isbn, title from Book", Object[].class)
-					.setOrder(desc(2).ignoringCase())
+			List<?> titlesDesc = SelectionSpecification.create(Object[].class, "select isbn, title from Book")
+					.sort(desc(2).ignoringCase())
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book[1])
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesDesc.get(1));
 			assertEquals("Java Persistence with Hibernate", titlesDesc.get(0));
 
-			List<?> isbnAsc = session.createSelectionQuery("select isbn, title from Book", Object[].class)
-					.setOrder(List.of(asc(1).ignoringCase(), desc(2).ignoringCase()))
+			List<?> isbnAsc = SelectionSpecification.create(Object[].class, "select isbn, title from Book")
+					.sort(asc(1).ignoringCase())
+					.sort(desc(2).ignoringCase())
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book[1])
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", isbnAsc.get(1));
 			assertEquals("Java Persistence with Hibernate", isbnAsc.get(0));
 
-			List<?> isbnDesc = session.createSelectionQuery("select isbn, title from Book", Object[].class)
-					.setOrder(List.of(desc(1).ignoringCase(), desc(2).ignoringCase()))
+			List<?> isbnDesc = SelectionSpecification.create(Object[].class, "select isbn, title from Book")
+					.sort(desc(1).ignoringCase())
+					.sort(desc(2).ignoringCase())
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book[1])
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", isbnDesc.get(0));
 			assertEquals("Java Persistence with Hibernate", isbnDesc.get(1));
 		});
 	}
 
+	@NotImplementedYet(reason = "Support for explicit select lists not implemented yet for SelectionSpecification")
 	@Test void testAscendingDescendingBySelectElementCaseInsensitiveLongForm(SessionFactoryScope scope) {
-		scope.inTransaction( session -> session.createMutationQuery("delete Book").executeUpdate() );
-		scope.inTransaction( session -> {
-			session.persist(new Book("9781932394153", "Hibernate in Action"));
-			session.persist(new Book("9781617290459", "Java Persistence with Hibernate"));
-		});
 		scope.inSession(session -> {
-			List<?> titlesAsc = session.createSelectionQuery("select isbn, title from Book", Object[].class)
-					.setOrder(by(2, ASCENDING, true))
+			List<?> titlesAsc = SelectionSpecification.create(Object[].class, "select isbn, title from Book")
+					.sort(by(2, ASCENDING, true))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book[1])
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesAsc.get(0));
 			assertEquals("Java Persistence with Hibernate", titlesAsc.get(1));
 
-			List<?> titlesDesc = session.createSelectionQuery("select isbn, title from Book", Object[].class)
-					.setOrder(by(2, DESCENDING, true))
+			List<?> titlesDesc = SelectionSpecification.create(Object[].class, "select isbn, title from Book")
+					.sort(by(2, DESCENDING, true))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book[1])
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", titlesDesc.get(1));
 			assertEquals("Java Persistence with Hibernate", titlesDesc.get(0));
 
-			List<?> isbnAsc = session.createSelectionQuery("select isbn, title from Book", Object[].class)
-					.setOrder(List.of(by(1, ASCENDING, true), by(2, DESCENDING, true)))
+			List<?> isbnAsc = SelectionSpecification.create(Object[].class, "select isbn, title from Book")
+					.sort(by(1, ASCENDING, true))
+					.sort(by(2, DESCENDING, true))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book[1])
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", isbnAsc.get(1));
 			assertEquals("Java Persistence with Hibernate", isbnAsc.get(0));
 
-			List<?> isbnDesc = session.createSelectionQuery("select isbn, title from Book", Object[].class)
-					.setOrder(List.of(by(1, DESCENDING, true), by(2, DESCENDING, true)))
+			List<?> isbnDesc = SelectionSpecification.create(Object[].class, "select isbn, title from Book")
+					.sort(by(1, DESCENDING, true))
+					.sort(by(2, DESCENDING, true))
+					.createQuery( session )
 					.getResultList()
 					.stream().map(book -> book[1])
-					.collect(toList());
+					.toList();
 			assertEquals("Hibernate in Action", isbnDesc.get(0));
 			assertEquals("Java Persistence with Hibernate", isbnDesc.get(1));
 		});
diff --git a/hibernate-core/src/test/java/org/hibernate/orm/test/query/restriction/RestrictionTest.java b/hibernate-core/src/test/java/org/hibernate/orm/test/query/restriction/RestrictionTest.java
index df2bcb5a9f65..984a407675f9 100644
--- a/hibernate-core/src/test/java/org/hibernate/orm/test/query/restriction/RestrictionTest.java
+++ b/hibernate-core/src/test/java/org/hibernate/orm/test/query/restriction/RestrictionTest.java
@@ -9,6 +9,7 @@
 import jakarta.persistence.ManyToOne;
 import jakarta.persistence.Version;
 import jakarta.persistence.metamodel.SingularAttribute;
+import org.hibernate.query.specification.SelectionSpecification;
 import org.hibernate.testing.orm.junit.DomainModel;
 import org.hibernate.testing.orm.junit.SessionFactory;
 import org.hibernate.testing.orm.junit.SessionFactoryScope;
@@ -16,9 +17,11 @@
 
 import java.util.List;
 
-import org.hibernate.query.programmatic.SelectionSpecification;
 import static org.hibernate.query.Order.asc;
 import static org.hibernate.query.Order.desc;
+import static org.hibernate.query.range.Range.containing;
+import static org.hibernate.query.range.Range.greaterThan;
+import static org.hibernate.query.range.Range.singleCaseInsensitiveValue;
 import static org.hibernate.query.restriction.Path.from;
 import static org.hibernate.query.restriction.Restriction.all;
 import static org.hibernate.query.restriction.Restriction.any;
@@ -32,9 +35,6 @@
 import static org.hibernate.query.restriction.Restriction.like;
 import static org.hibernate.query.restriction.Restriction.restrict;
 import static org.hibernate.query.restriction.Restriction.unrestricted;
-import static org.hibernate.query.range.Range.containing;
-import static org.hibernate.query.range.Range.greaterThan;
-import static org.hibernate.query.range.Range.singleCaseInsensitiveValue;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
 @SessionFactory
@@ -66,8 +66,8 @@ void test(SessionFactoryScope scope) {
 		List<Book> books = scope.fromSession( session ->
 				SelectionSpecification.create( Book.class, "from Book" )
 						.restrict( like( title, "%Hibernate%" ) )
+						.sort( desc( title ) )
 						.createQuery( session )
-						.setOrder( desc( title ) )
 						.getResultList() );
 		assertEquals( 2, books.size() );
 		assertEquals( "Java Persistence with Hibernate", books.get(0).title );
@@ -75,8 +75,8 @@ void test(SessionFactoryScope scope) {
 		List<Book> booksByIsbn = scope.fromSession( session ->
 				SelectionSpecification.create( Book.class, "from Book" )
 						.restrict( in( isbn, List.of("9781932394153", "9781617290459") ) )
+						.sort( asc( title ) )
 						.createQuery( session )
-						.setOrder( asc( title ) )
 						.getResultList() );
 		assertEquals( 2, booksByIsbn.size() );
 		assertEquals( "Hibernate in Action", booksByIsbn.get(0).title );
@@ -199,29 +199,29 @@ void testPath(SessionFactoryScope scope) {
 		List<Book> booksInIsbn = scope.fromSession( session ->
 				SelectionSpecification.create( Book.class, "from Book" )
 						.restrict( from(Book.class).to(isbn).in( List.of("9781932394153", "9781617290459") ) )
+						.sort( desc( isbn ) )
 						.createQuery( session )
-						.setOrder( desc( isbn ) )
 						.getResultList() );
 		assertEquals( 2, booksInIsbn.size() );
 		List<Book> booksWithPub = scope.fromSession( session ->
 				SelectionSpecification.create( Book.class, "from Book" )
 						.restrict( from(Book.class).to(publisher).to(name).equalTo("Manning") )
+						.sort( desc( title ) )
 						.createQuery( session )
-						.setOrder( desc( title ) )
 						.getResultList() );
 		assertEquals( 2, booksWithPub.size() );
 		List<Book> noBookWithPub = scope.fromSession( session ->
 				SelectionSpecification.create( Book.class, "from Book" )
 						.restrict( from(Book.class).to(publisher).to(name).notEqualTo("Manning") )
+						.sort( desc( title ) )
 						.createQuery( session )
-						.setOrder( desc( title ) )
 						.getResultList() );
 		assertEquals( 0, noBookWithPub.size() );
 		List<Book> books = scope.fromSession( session ->
 				SelectionSpecification.create( Book.class, "from Book" )
 						.restrict( from(Book.class).to(title).restrict( containing("hibernate", false) ) )
+						.sort( desc( title ) )
 						.createQuery( session )
-						.setOrder( desc( title ) )
 						.getResultList() );
 		assertEquals( 2, books.size() );
 		List<Book> booksWithPubVersion = scope.fromSession( session ->
diff --git a/migration-guide.adoc b/migration-guide.adoc
index 8069216c982e..11c87f6ff677 100644
--- a/migration-guide.adoc
+++ b/migration-guide.adoc
@@ -4,6 +4,7 @@
 :docsBase: https://docs.jboss.org/hibernate/orm
 :versionDocBase: {docsBase}/7.0
 :userGuideBase: {versionDocBase}/userguide/html_single/Hibernate_User_Guide.html
+:whatsNewBase: {versionDocBase}/whats-new/whats-new.html
 :javadocsBase: {versionDocBase}/javadocs
 :releaseSeriesBase: https://hibernate.org/orm/releases/7.0/
 :fn-cascase-type: footnote:cascade-type[`org.hibernate.annotations.Cascade` and `org.hibernate.annotations.CascadeType` are both fully deprecated as of 7.0]
@@ -252,6 +253,12 @@ In particular, interpretation of integrity constraint violations was improved si
 
 Also, `LockAcquisitionException` now extends `PessimisticLockException`.
 
+[[Query-setOrder]]
+=== Removed Query#setOrder
+
+`Query#setOrder` was an incubating API added in support of Hibernate's Jakarta Data and Repositories implementations.
+It was never a great solution and has been replaced with a better alternative - link:{whatsNewBase}#QuerySpecification[QuerySpecification].
+
 
 [[misc-api]]
 === Miscellaneous
diff --git a/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/AbstractCriteriaMethod.java b/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/AbstractCriteriaMethod.java
index 798e0fc6fa3a..9e89859b1188 100644
--- a/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/AbstractCriteriaMethod.java
+++ b/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/AbstractCriteriaMethod.java
@@ -75,7 +75,7 @@ public String getAttributeDeclarationString() {
 	abstract String createQueryMethod();
 
 	String specificationType() {
-		return "org.hibernate.query.programmatic.SelectionSpecification";
+		return "org.hibernate.query.specification.SelectionSpecification";
 	}
 
 	@Override
diff --git a/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/CriteriaDeleteMethod.java b/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/CriteriaDeleteMethod.java
index 5b15bbcb998c..02fa0836fa71 100644
--- a/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/CriteriaDeleteMethod.java
+++ b/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/CriteriaDeleteMethod.java
@@ -79,7 +79,7 @@ String createQueryMethod() {
 
 	@Override
 	String specificationType() {
-		return "org.hibernate.query.programmatic.MutationSpecification";
+		return "org.hibernate.query.specification.MutationSpecification";
 	}
 
 	private void execute(StringBuilder declaration) {
diff --git a/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/QueryMethod.java b/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/QueryMethod.java
index 708283a216eb..7bc388daacf7 100644
--- a/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/QueryMethod.java
+++ b/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/QueryMethod.java
@@ -110,8 +110,8 @@ public String getAttributeDeclarationString() {
 
 	String specificationType() {
 		return isUpdate
-				? "org.hibernate.query.programmatic.MutationSpecification"
-				: "org.hibernate.query.programmatic.SelectionSpecification";
+				? "org.hibernate.query.specification.MutationSpecification"
+				: "org.hibernate.query.specification.SelectionSpecification";
 	}
 
 	@Override