Add keyset-pagination seeks to ORDER BY elimination (the a > @x OR (a = @x AND b > @y) staircase seeks past the cursor via a generalized composite-key bound). Fix AdjustForPrecedence to re-adjust recursively so 3+-term arithmetic chains led by a multiplication group correctly.

Author: RyanLamansky

CLAUDE.md

@@ -107,7 +107,7 @@ The `*.Tests` and `*.Tests.EFCore` suites are the authoritative behavior contrac
 
 ### Constraints
 - `CHECK`: inline single-column and table-level forms; Msg 547 per row on definitely-false predicate. Inline column-level CHECK predicates may only reference their owning column — peer references raise **Msg 8141** at CREATE TABLE (probe-confirmed verbatim wording). The walker is structural via `Expression.VisitColumnReferences` + `BooleanExpression.VisitOperandExpressions`; coverage is currently limited to common container subclasses (`Reference`, `Parenthesized`, `TwoSidedExpression`, `Cast`, `Length`) — peer refs buried in less-common containers (`DATEPART`, `SUBSTRING`, nested `CASE`, etc.) silently escape the CREATE-TABLE check and surface at INSERT instead. Table-level CHECK has no peer restriction.
-- `PRIMARY KEY` / `UNIQUE`: linear scan (O(N) per insert); no B-tree. Reads get **incrementally-maintained** per-`Heap` seek acceleration (no per-mutation warm-up): equality / IN on the longest leading prefix, range (`>`/`<`/`BETWEEN`) on a leading key column, and ORDER BY elimination — single or multi-column leading-prefix sort (all NOT NULL, all one direction), including an equality-prefix continued by the order columns (`WHERE a = @x ORDER BY b`). See [`indexes.md`](docs/claude/indexes.md) for the journal mechanics, decline rules, and the residual-WHERE correctness invariant.
+- `PRIMARY KEY` / `UNIQUE` / secondary `CREATE INDEX`: linear scan (O(N) per insert); no B-tree. Reads get **incrementally-maintained** per-`Heap` seek acceleration (no per-mutation warm-up), identical across keys and non-clustered indexes (built from heap-row bytes keyed by the index's ordinals): equality / IN on the longest leading prefix, range (`>`/`<`/`BETWEEN`) on a leading key column, ORDER BY elimination — single or multi-column leading-prefix sort (all NOT NULL, all one direction), including an equality-prefix continued by the order columns (`WHERE a = @x ORDER BY b`) — and keyset (seek-method) pagination (`WHERE a > @x OR (a = @x AND b > @y) ORDER BY a, b` seeks past the cursor). See [`indexes.md`](docs/claude/indexes.md) for the journal mechanics, decline rules, and the residual-WHERE correctness invariant.
 - `FOREIGN KEY`: inline / table-level / named forms; all four referential actions on `ON DELETE` / `ON UPDATE`; enforced at INSERT / UPDATE / DELETE / MERGE; full `sys.foreign_keys` / `sys.foreign_key_columns`. Referential-action, cascade-cycle, PK/UNIQUE-target, and NULL-skip rules + Msg numbers in [`foreign-keys.md`](docs/claude/foreign-keys.md).
 
 ### Transactions

SqlServerSimulator.Tests.Internal/IndexSeekTests.cs

@@ -1213,6 +1213,124 @@ public void MultiColumnOrderByDifferential_MatchesIndependentSort()
         AreEqual(string.Join(",", expected), string.Join(",", actual));
     }
 
+    // ---- keyset pagination: WHERE a > @x OR (a = @x AND b > @y) ORDER BY a, b
+    // seeks past the cursor instead of scanning + sorting + skipping ----
+
+    [TestMethod]
+    public void KeysetForwardTwoColumn_SeeksPastCursor()
+    {
+        var (trace, rows) = Run("""
+            create table t (a int not null, b int not null, primary key (a, b));
+            insert t values (1, 1), (1, 2), (1, 3), (2, 1), (2, 2), (3, 1)
+            """, "select 10 * a + b from t where a > 1 or (a = 1 and b > 2) order by a, b");
+        Contains("OrderedScan(t)", trace);
+        Contains("KeysetSeek(t)", trace);
+        AreEqual("13,21,22,31", Seq(rows));
+    }
+
+    [TestMethod]
+    public void KeysetDescendingTwoColumn_SeeksPastCursor()
+    {
+        // a DESC, b DESC keyset uses the < staircase; the cursor is the exclusive
+        // upper bound, and the ascending in-range list is reversed into the page.
+        var (trace, rows) = Run("""
+            create table t (a int not null, b int not null, primary key (a, b));
+            insert t values (1, 1), (1, 2), (1, 3), (2, 1), (2, 2), (3, 1)
+            """, "select 10 * a + b from t where a < 3 or (a = 3 and b < 1) order by a desc, b desc");
+        Contains("OrderedScan(t)", trace);
+        Contains("KeysetSeek(t)", trace);
+        AreEqual("22,21,13,12,11", Seq(rows));
+    }
+
+    [TestMethod]
+    public void KeysetThreeColumn_SeeksPastCursor()
+    {
+        var (trace, rows) = Run("""
+            create table t (a int not null, b int not null, c int not null, primary key (a, b, c));
+            insert t values (1, 2, 1), (1, 2, 2), (1, 2, 3), (1, 3, 1), (2, 1, 1)
+            """, "select 100 * a + 10 * b + c from t where a > 1 or (a = 1 and b > 2) or (a = 1 and b = 2 and c > 2) order by a, b, c");
+        Contains("KeysetSeek(t)", trace);
+        // Rows (1,2,3),(1,3,1),(2,1,1) in key order → 100*a + 10*b + c.
+        AreEqual("123,131,211", Seq(rows));
+    }
+
+    [TestMethod]
+    public void KeysetOnNonClusteredCompositeIndex_SeeksPastCursor()
+    {
+        // The cursor seek rides a secondary CREATE INDEX, not just the PK —
+        // acceleration is index-source-agnostic.
+        var (trace, rows) = Run("""
+            create table t (id int not null primary key, a int not null, b int not null);
+            create index ix on t (a, b);
+            insert t values (10, 1, 1), (20, 1, 2), (30, 2, 1), (40, 2, 2), (50, 3, 9)
+            """, "select id from t where a > 2 or (a = 2 and b > 1) order by a, b");
+        Contains("OrderedScan(t)", trace);
+        Contains("KeysetSeek(t)", trace);
+        AreEqual("40,50", Seq(rows));
+    }
+
+    [TestMethod]
+    public void KeysetWithResidualFilter_SeeksAndFilters()
+    {
+        // The keyset OR is one conjunct; an unrelated AND filter stays residual.
+        var (trace, rows) = Run("""
+            create table t (a int not null, b int not null, active int not null, primary key (a, b));
+            insert t values (1, 1, 1), (1, 2, 0), (2, 1, 1), (2, 2, 1), (3, 1, 0)
+            """, "select 10 * a + b from t where (a > 1 or (a = 1 and b > 1)) and active = 1 order by a, b");
+        Contains("KeysetSeek(t)", trace);
+        AreEqual("21,22", Seq(rows));
+    }
+
+    [TestMethod]
+    public void KeysetParameterizedCursor_SeeksPastCursor()
+    {
+        // Variables are stable cursor values, the normal pagination shape. The
+        // DECLAREs share the query's batch (Run runs setup separately).
+        var (trace, rows) = Run("""
+            create table t (a int not null, b int not null, primary key (a, b));
+            insert t values (1, 1), (1, 2), (2, 1), (2, 2), (3, 1)
+            """, "declare @a int = 2; declare @b int = 1; select 10 * a + b from t where a > @a or (a = @a and b > @b) order by a, b");
+        Contains("KeysetSeek(t)", trace);
+        AreEqual("22,31", Seq(rows));
+    }
+
+    [TestMethod]
+    public void KeysetDifferential_MatchesIndependentFilterAndSort()
+    {
+        // Cross-check the keyset seek against a C# (a, b) > (cursor) filter + sort
+        // over a scrambled non-clustered composite index.
+        var c = new Simulation().CreateDbConnection();
+        c.Open();
+        Exec(c, "create table t (id int not null primary key, a int not null, b int not null)");
+        Exec(c, "create index ix on t (a, b)");
+        Exec(c, "insert t (id, a, b) select value, (value * 7919) % 23, (value * 104729) % 89 from generate_series(1, 400)");
+
+        var expected = new List<int>();
+        foreach (var (a, b) in ReadPairs(c, "select a, b from t"))
+        {
+            if ((a > 11) || ((a == 11) && (b > 40)))
+                expected.Add((1000 * a) + b);
+        }
+        expected.Sort();
+
+        var actual = new List<int>();
+        foreach (var o in ReadRows(c, "select 1000 * a + b from t where a > 11 or (a = 11 and b > 40) order by a, b"))
+            actual.Add(Convert.ToInt32(o));
+
+        AreEqual(string.Join(",", expected), string.Join(",", actual));
+    }
+
+    private static List<(int A, int B)> ReadPairs(SimulatedDbConnection c, string sql)
+    {
+        using var cmd = c.CreateCommand();
+        cmd.CommandText = sql;
+        using var r = cmd.ExecuteReader();
+        var pairs = new List<(int, int)>();
+        while (r.Read())
+            pairs.Add((Convert.ToInt32(r.GetValue(0)), Convert.ToInt32(r.GetValue(1))));
+        return pairs;
+    }
+
     // ---- declines (keeps the buffered sort), still correct order ----
 
     [TestMethod]
@@ -1285,6 +1403,21 @@ insert t values (1, 30), (1, null), (1, 10)
         AreEqual(",10,30", Seq(rows));
     }
 
+    [TestMethod]
+    public void KeysetInconsistentCursorValues_DeclinesKeyset_StillCorrect()
+    {
+        // a > 1 OR (a = 0 AND b > 5) isn't a clean (a, b) > cursor staircase (the
+        // a-value disagrees: 1 vs 0), so the keyset cursor declines — the ordered
+        // scan still runs and the residual OR filters it to the right rows.
+        var (trace, rows) = Run("""
+            create table t (a int not null, b int not null, primary key (a, b));
+            insert t values (0, 9), (1, 1), (1, 2), (2, 1)
+            """, "select 10 * a + b from t where a > 1 or (a = 0 and b > 5) order by a, b");
+        DoesNotContain("KeysetSeek(t)", trace);
+        Contains("OrderedScan(t)", trace);
+        AreEqual("9,21", Seq(rows));
+    }
+
     [TestMethod]
     public void OrderByColumnsNotMatchingKeyOrder_Declines()
     {

SqlServerSimulator.Tests/OperatorPrecedenceTests.cs

@@ -24,6 +24,16 @@ public sealed class OperatorPrecedenceTests
     [DataRow("10 + 8 / 4", 12)] // Divide on the right of Add (Divide is higher precedence; doesn't swap).
     [DataRow("1 + 5 % 3", 3)]   // Modulus on the right of Add (same precedence): (1+5)%3 = 6%3 = 0... wait, swap means Modulus parent: 1+(5%3) = 1+2 = 3.
     [DataRow("2 * 3 + 4", 10)]  // Add on the right of Multiply (Add lower precedence; swap).
+    // Three-plus additive terms whose FIRST term is a multiplication: one rotation
+    // lifts the top + but leaves the rotated-down Multiply mis-grouped, so these
+    // need AdjustForPrecedence to re-adjust recursively. Before that fix
+    // `100 * 2 + 10 * 3 + 4` parsed as `(100 * (2 + 10 * 3)) + 4`.
+    [DataRow("100 * 2 + 10 * 3 + 4", 234)]
+    [DataRow("100 * 2 + 3 + 4", 207)]
+    [DataRow("2 * 1 + 3 * 2 + 4 * 1", 12)]
+    [DataRow("1 + 2 * 3 + 4", 11)]                    // leading literal already worked; guards against regressing it.
+    [DataRow("2 * 3 + 4 * 5 + 6", 32)]
+    [DataRow("100 * 2 + 10 * 3 + 4 * 1 + 5", 239)]    // four terms.
     public void OperatorChainProducesExpected(string expr, int expected) =>
         AreEqual(expected, ExecuteScalar($"select {expr}"));
 }

SqlServerSimulator/Parser/BooleanExpression.cs

@@ -497,6 +497,15 @@ private static BetweenExpression ParseBetween(Expression left, ParserContext con
     /// </summary>
     internal virtual void CollectConjuncts(List<BooleanExpression> sink) => sink.Add(this);
 
+    /// <summary>
+    /// Flattens a top-level <c>OR</c> chain into its individual disjunct terms,
+    /// appending each to <paramref name="sink"/>. A non-<c>OR</c> predicate
+    /// contributes itself. The mirror of <see cref="CollectConjuncts"/>, used to
+    /// recognize the keyset-pagination staircase
+    /// (<c>a &gt; @x OR (a = @x AND b &gt; @y)</c>).
+    /// </summary>
+    internal virtual void CollectDisjuncts(List<BooleanExpression> sink) => sink.Add(this);
+
     /// <summary>
     /// Exposes the two operands when this predicate is an equality comparison
     /// (<c>=</c>); returns false for every other node. Lets the join planner
@@ -620,6 +629,12 @@ internal override void VisitOperandExpressions(Action<Expression> visitor)
             right.VisitOperandExpressions(visitor);
         }
 
+        internal override void CollectDisjuncts(List<BooleanExpression> sink)
+        {
+            left.CollectDisjuncts(sink);
+            right.CollectDisjuncts(sink);
+        }
+
         // Flatten the OR-tree (any nesting depth) into leaf equality pairs.
         // Succeeds only when EVERY leaf is itself an equality family — a single
         // equality compare (one pair), a nested OR-tree (recursed via the

SqlServerSimulator/Parser/Expressions/TwoSidedExpression.cs

@@ -43,7 +43,14 @@ public TwoSidedExpression AdjustForPrecedence()
         if (this.right is not TwoSidedExpression rightTwo || rightTwo.Precedence < this.Precedence)
             return this;
 
+        // Left-rotate so this operator drops below rightTwo's equal-or-looser-
+        // binding one. The rotated-down node (this, now holding the old
+        // rightTwo.left as its right operand) can itself still be mis-grouped when
+        // that operand is another operator chain, so re-adjust it: a single
+        // rotation only fixes the top of a 3+-term right-leaning parse, leaving
+        // e.g. `100*a + 10*b + c` as `(100 * (a + 10*b)) + c` without this step.
         (rightTwo.left, this.right) = (this, rightTwo.left);
+        rightTwo.left = this.AdjustForPrecedence();
         return rightTwo;
     }
 

SqlServerSimulator/Parser/IndexSeekDiagnostics.cs

@@ -16,7 +16,10 @@ internal static class IndexSeekDiagnostics
     /// <summary>
     /// Per-thread decision log: <c>Seek(table)</c> when a scan narrows to an
     /// index seek, <c>Scan(table)</c> when an eligible single-base-table scan
-    /// keeps its full scan, plus the per-Heap cache's own maintenance trace —
+    /// keeps its full scan, <c>OrderedScan(table)</c> when an ORDER BY streams in
+    /// key order instead of buffering + sorting (with <c>KeysetSeek(table)</c>
+    /// when that ordered scan also positions past a keyset-pagination cursor),
+    /// plus the per-Heap cache's own maintenance trace —
     /// <c>CacheBuild</c> when a seek (re)builds an entry from a full scan and
     /// <c>CacheReplay</c> when it instead applies the incremental journal delta
     /// (the "no warm-up" path). A test assigns a fresh list, drives a query to