fix(drive): unordered composite lookups inherit the page's direction

A documents sub-query the caller left unordered on its bound field was
appended ascending, which the direction rule then refused under a
descending page: every feed page (`$createdAt desc`) with default
lookups failed with "outer ordering must match the page's direction".
The appended clause now takes the page's direction, so a minimal
request never conflicts with its page; an explicit ordering that
disagrees is still refused, on every entry point.

Also documents a lookup's limit for what it is: a cap on the rows the
lookup returns in total, in walk order, like an ordinary `IN` query's,
not a per-value bound.

Test: a descending by-ids page with unordered cross-contract profiles,
the viewer's likes and a count merges, proves and verifies with the
lookups walking descending; a limited same-contract lookup does too,
returning its capped rows from the top of the walk; an explicit
ascending ordering under the descending page is refused by all three
entry points.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: QuantumExplorer

packages/rs-drive/src/drive/contract/insert/insert_contract/v0/tests/composite_query_e2e_tests.rs

@@ -1195,3 +1195,165 @@ fn should_check_count_and_document_descents_against_the_actual_bound_values() {
     );
     assert_eq!(verified.sub_results, materialized.sub_results);
 }
+
+/// A minimal request never conflicts with the page's direction: a
+/// documents sub-query the caller left unordered on its bound field walks
+/// the page's way, so a descending page with default lookups merges and
+/// verifies, while an explicit ordering that disagrees is still refused.
+#[test]
+fn should_inherit_the_page_direction_for_unordered_lookups() {
+    let (drive, feed, dashpay) = setup();
+    seed_feed(&drive, &feed, &dashpay);
+    let pv = platform_version();
+    let descending_page = || {
+        let mut page = page_by_hashtag(&feed, "dash", Some(3));
+        page.internal_clauses = InternalClauses::extract_from_clauses(
+            vec![WhereClause {
+                field: "$id".into(),
+                operator: WhereOperator::In,
+                value: Value::Array(vec![
+                    Value::Identifier(POST_A),
+                    Value::Identifier(POST_B),
+                    Value::Identifier(POST_C),
+                ]),
+            }],
+            pv,
+        )
+        .expect("by-id page");
+        page.order_by.insert(
+            "$id".into(),
+            OrderClause {
+                field: "$id".into(),
+                ascending: false,
+            },
+        );
+        page
+    };
+    let like_counts = || {
+        bound(
+            &feed,
+            "like",
+            SubQueryKind::Count,
+            BindingSource::Page,
+            "$id",
+            "postId",
+            None,
+        )
+    };
+    let round_trip = |query: &DriveCompositeDocumentQuery, what: &str| {
+        let materialized = drive
+            .query_composite_documents(query, None, None, pv)
+            .unwrap_or_else(|e| panic!("{what} materializes: {e}"))
+            .result;
+        assert_eq!(
+            ids(&materialized.page_documents),
+            vec![POST_C, POST_B, POST_A]
+        );
+        let (proof, _) = drive
+            .query_composite_documents_with_proof(query, pv)
+            .unwrap_or_else(|e| panic!("{what} proves: {e}"));
+        let (_, verified) = query
+            .verify_composite_documents_proof(&proof, pv)
+            .unwrap_or_else(|e| panic!("{what} verifies: {e}"));
+        assert_eq!(verified.page_documents, materialized.page_documents);
+        assert_eq!(verified.sub_results, materialized.sub_results);
+        materialized
+    };
+
+    // The feed shape: cross-contract profiles, the viewer's marks (both
+    // value-bounded) and a count, none of them ordered by the caller.
+    let mut viewer_likes = bound(
+        &feed,
+        "like",
+        SubQueryKind::Documents,
+        BindingSource::Page,
+        "$id",
+        "postId",
+        None,
+    );
+    viewer_likes.where_clauses = vec![WhereClause {
+        field: "$ownerId".into(),
+        operator: WhereOperator::Equal,
+        value: Value::Identifier(OWNER_1),
+    }];
+    let feed_shape = DriveCompositeDocumentQuery {
+        page: descending_page(),
+        sub_queries: vec![
+            bound(
+                &dashpay,
+                "profile",
+                SubQueryKind::Documents,
+                BindingSource::Page,
+                "$ownerId",
+                "$ownerId",
+                None,
+            ),
+            viewer_likes,
+            like_counts(),
+        ],
+    };
+    let result = round_trip(&feed_shape, "the descending feed shape");
+    // The lookups inherited the page's direction: descending by their
+    // bound field.
+    assert_eq!(
+        owner_ids(result.sub_results[0].documents()),
+        vec![OWNER_3, OWNER_1],
+        "profiles walk owners descending"
+    );
+    assert_eq!(
+        post_ids_of(&result.sub_results[1], "postId"),
+        vec![POST_B, POST_A],
+        "the viewer's likes, posts descending"
+    );
+    assert_eq!(
+        counts(&result.sub_results[2]),
+        BTreeMap::from([(POST_A, 2), (POST_B, 1)])
+    );
+
+    // A limited lookup under the page's own contract. Its limit caps the
+    // rows it returns in total, in walk order, like an ordinary `IN`
+    // query's: walking posts descending, the one row is B's.
+    let limited_lookup = DriveCompositeDocumentQuery {
+        page: descending_page(),
+        sub_queries: vec![
+            bound(
+                &feed,
+                "repost",
+                SubQueryKind::Documents,
+                BindingSource::Page,
+                "$id",
+                "postId",
+                Some(1),
+            ),
+            like_counts(),
+        ],
+    };
+    let result = round_trip(&limited_lookup, "the limited lookup");
+    assert_eq!(
+        post_ids_of(&result.sub_results[0], "postId"),
+        vec![POST_B],
+        "the single repost row comes from the highest post id"
+    );
+
+    // An explicit ordering that disagrees with the page is still refused,
+    // on every entry point.
+    let mut conflicting = limited_lookup.clone();
+    conflicting.sub_queries[0].order_by.push(OrderClause {
+        field: "postId".into(),
+        ascending: true,
+    });
+    for result in [
+        drive
+            .query_composite_documents(&conflicting, None, None, pv)
+            .map(|_| ()),
+        drive
+            .query_composite_documents_with_proof(&conflicting, pv)
+            .map(|_| ()),
+        conflicting
+            .verify_composite_documents_proof(&[], pv)
+            .map(|_| ()),
+    ] {
+        assert!(matches!(result, Err(Error::Query(_))), "{result:?}");
+        assert!(result.unwrap_err().to_string().contains("outer ordering"));
+    }
+}

packages/rs-drive/src/query/drive_composite_document_query/mod.rs

@@ -139,12 +139,18 @@ pub struct DriveSubQuery<'a> {
     /// The fixed clauses (everything but the derived `IN`), typed.
     /// Must be empty for a by-id join, which resolves every derived id.
     pub where_clauses: Vec<WhereClause>,
-    /// Ordering; documents only. The outer query direction must agree
-    /// with the page's direction so merging preserves the requested rows.
+    /// Ordering; documents only. Every component of the merged proof
+    /// walks in the page's direction, so a documents sub-query must agree
+    /// with it: a bound field the caller did not order by is appended in
+    /// the page's direction (a minimal request never conflicts), and an
+    /// explicit ordering that disagrees is refused, because changing it
+    /// for the proof would change the rows its limit selects.
     pub order_by: Vec<OrderClause>,
-    /// Required for a documents lookup on a non-unique index (it bounds
-    /// the walk under each value); forbidden for a value-bounded lookup,
-    /// a by-id join (completeness is set-based) and a count.
+    /// Required for a documents lookup on a non-unique index: it caps the
+    /// rows the lookup returns in total, in walk order, exactly as the
+    /// limit of an ordinary `IN` query does (at most `MAX_BOUND_VALUES`).
+    /// Forbidden for a value-bounded lookup, a by-id join (completeness is
+    /// set-based) and a count.
     pub limit: Option<u16>,
     /// The derived clause, or `None` for a sibling.
     pub binding: Option<SubQueryBinding>,
@@ -887,12 +893,17 @@ impl<'a> DriveCompositeDocumentQuery<'a> {
             // An `IN` on a secondary index orders by the bound field;
             // supply the ordering when the caller did not, so the
             // request stays minimal and both sides build the same query.
+            // It inherits the page's direction: the merged proof walks
+            // every component the page's way, and a documents sub-query
+            // may not be turned around behind the caller's back (see
+            // `sub_query_proof_path_query`), so this default is what
+            // keeps an unordered lookup mergeable under a descending page.
             if !order_by.contains_key(&binding.field) {
                 order_by.insert(
                     binding.field.clone(),
                     OrderClause {
                         field: binding.field.clone(),
-                        ascending: true,
+                        ascending: self.page_direction(platform_version)?,
                     },
                 );
             }
@@ -974,6 +985,16 @@ impl<'a> DriveCompositeDocumentQuery<'a> {
         }
     }
 
+    /// The page's walk direction: what every component of the merged
+    /// proof walks in, and what an unordered documents sub-query inherits.
+    fn page_direction(&self, platform_version: &PlatformVersion) -> Result<bool, Error> {
+        Ok(self
+            .page_path_query(platform_version)?
+            .query
+            .query
+            .left_to_right)
+    }
+
     /// Aligns set-based components for merging without changing a
     /// documents query's ordering or the rows selected by its limit.
     /// Validation, proof generation and bootstrap use the same check,