Add leading-key-column range seeks (>/>=/</<=/BETWEEN, either operand order, two-sided and correlated bounds) over a lazily-built, incrementally-maintained ordered view of the per-Heap seek cache, so range predicates narrow instead of full-scanning while inheriting the journal's no-warm-up maintenance.

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 equality-seek acceleration via an **incrementally-maintained** per-`Heap` hash index: the first seek builds it from a scan and activates the heap's bounded mutation journal, and later writes append a delta the next seek replays instead of forcing a rebuild (no per-mutation warm-up; rollback / TRUNCATE invalidate it as the safety valve; the write path's locking stays untouched). See indexes.md for leading-prefix matching, MVCC/lock-plan decline rules, the journal mechanics, and the residual-WHERE correctness invariant.
+- `PRIMARY KEY` / `UNIQUE`: linear scan (O(N) per insert); no B-tree. Reads get equality- and range-seek acceleration via an **incrementally-maintained** per-`Heap` index: the first seek builds it from a scan and activates the heap's bounded mutation journal, and later writes append a delta the next seek replays instead of forcing a rebuild (no per-mutation warm-up; rollback / TRUNCATE invalidate it as the safety valve; the write path's locking stays untouched). Equality / IN seek the longest leading prefix; a range bound (`>`/`<`/`BETWEEN`) on a leading key column seeks an ordered view (`SortedSet`) of that column's keys. See indexes.md for leading-prefix matching, range-seek scope, MVCC/lock-plan decline rules, the journal mechanics, 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

@@ -359,15 +359,6 @@ public void NullProbe_Declines()
         IsEmpty(rows);
     }
 
-    [TestMethod]
-    public void RangePredicate_Declines()
-    {
-        var (trace, rows) = Run(TableT, "select id from t where id > 1");
-        Contains("Scan(t)", trace);
-        DoesNotContain("Seek(t)", trace);
-        HasCount(2, rows);
-    }
-
     [TestMethod]
     public void NonIndexedColumn_Declines()
     {
@@ -844,4 +835,211 @@ public void InterleavedInsertSeekLoop_NeverStale()
             AreEqual(i * 100, ReadVal(c, $"select val from t where id = {i}"));
         }
     }
+
+    // ---- range seeks on a leading key column (>, >=, <, <=, BETWEEN). The bound
+    // conjunct stays residual, so the seek only narrows; results match a scan. ----
+
+    [TestMethod]
+    public void GreaterThan_OnPrimaryKey_RangeSeeks()
+    {
+        var (trace, rows) = Run(TableT, "select id from t where id > 1");
+        Contains("RangeSeek(t)", trace);
+        DoesNotContain("Scan(t)", trace);
+        HasCount(2, rows);
+        Contains(2, rows);
+        Contains(3, rows);
+    }
+
+    [TestMethod]
+    public void GreaterOrEqual_OnPrimaryKey_RangeSeeks()
+    {
+        var (trace, rows) = Run(TableT, "select id from t where id >= 2");
+        Contains("RangeSeek(t)", trace);
+        HasCount(2, rows);
+    }
+
+    [TestMethod]
+    public void LessThan_OnPrimaryKey_RangeSeeks()
+    {
+        var (trace, rows) = Run(TableT, "select id from t where id < 3");
+        Contains("RangeSeek(t)", trace);
+        HasCount(2, rows);
+        Contains(1, rows);
+        Contains(2, rows);
+    }
+
+    [TestMethod]
+    public void LessOrEqual_OnPrimaryKey_RangeSeeks()
+    {
+        var (trace, rows) = Run(TableT, "select id from t where id <= 2");
+        Contains("RangeSeek(t)", trace);
+        HasCount(2, rows);
+    }
+
+    [TestMethod]
+    public void Between_OnPrimaryKey_RangeSeeksInclusiveBothEnds()
+    {
+        var (trace, rows) = Run(TableT, "select id from t where id between 2 and 3");
+        Contains("RangeSeek(t)", trace);
+        HasCount(2, rows);
+        Contains(2, rows);
+        Contains(3, rows);
+    }
+
+    [TestMethod]
+    public void TwoSidedRange_OnPrimaryKey_RangeSeeks()
+    {
+        var (trace, rows) = Run(TableT, "select id from t where id > 1 and id < 3");
+        Contains("RangeSeek(t)", trace);
+        HasCount(1, rows);
+        AreEqual(2, rows[0]);
+    }
+
+    [TestMethod]
+    public void ReversedOperandOrder_RangeSeeks()
+    {
+        // `2 < id` is `id > 2` — the planner flips the operator when the column
+        // is on the right.
+        var (trace, rows) = Run(TableT, "select id from t where 2 < id");
+        Contains("RangeSeek(t)", trace);
+        HasCount(1, rows);
+        AreEqual(3, rows[0]);
+    }
+
+    [TestMethod]
+    public void RangeOnSecondaryIndexLeadingColumn_RangeSeeks()
+    {
+        var (trace, rows) = Run("""
+            create table c (id int not null, pid int not null);
+            create index ix_c_pid on c (pid);
+            insert c values (1, 10), (2, 20), (3, 30), (4, 5)
+            """, "select id from c where pid >= 20");
+        Contains("RangeSeek(c)", trace);
+        HasCount(2, rows);
+    }
+
+    [TestMethod]
+    public void RangeOnNonIndexedColumn_Declines()
+    {
+        var (trace, rows) = Run(TableT, "select id from t where val > 100");
+        Contains("Scan(t)", trace);
+        DoesNotContain("RangeSeek(t)", trace);
+        HasCount(1, rows);
+        AreEqual(3, rows[0]);
+    }
+
+    [TestMethod]
+    public void EqualityPrefixThenRange_TakesEqualitySeek_NotRange()
+    {
+        // index (a, b): a = 1 AND b > 10 — the equality path seeks on the leading
+        // column a (width 1) and the range on b stays residual. The single
+        // leading-column range path doesn't fire here.
+        var (trace, rows) = Run("""
+            create table t (a int not null, b int not null, v int not null, primary key (a, b));
+            insert t values (1, 10, 100), (1, 20, 200), (1, 30, 300), (2, 10, 400)
+            """, "select v from t where a = 1 and b > 10");
+        Contains("SeekWidth(t,1)", trace);
+        DoesNotContain("RangeSeek(t)", trace);
+        HasCount(2, rows);
+    }
+
+    [TestMethod]
+    public void NullBound_RangeSeeksToEmpty()
+    {
+        // `id > @null` is UNKNOWN for every row, so the range matches nothing — a
+        // valid (empty) seek rather than a scan.
+        var (trace, rows) = Run(TableT, "declare @v int = null; select id from t where id > @v");
+        Contains("RangeSeek(t)", trace);
+        IsEmpty(rows);
+    }
+
+    [TestMethod]
+    public void OutOfDomainUpperBound_PromotesUp_ReturnsAll()
+    {
+        // bigint bound wider than the int column: promotion is upward, so the
+        // comparison is exact and every row qualifies.
+        var (trace, rows) = Run(TableT, "select id from t where id < 9999999999");
+        Contains("RangeSeek(t)", trace);
+        HasCount(3, rows);
+    }
+
+    [TestMethod]
+    public void EmptyRange_LowerAboveUpper_RangeSeeksToEmpty()
+    {
+        var (trace, rows) = Run(TableT, "select id from t where id > 5 and id < 2");
+        Contains("RangeSeek(t)", trace);
+        IsEmpty(rows);
+    }
+
+    [TestMethod]
+    public void StringRange_CaseInsensitiveCollation_RangeSeeks()
+    {
+        var (trace, rows) = Run("""
+            create table t (code varchar(10) not null primary key);
+            insert t values ('apple'), ('mango'), ('pear')
+            """, "select code from t where code >= 'm'");
+        Contains("RangeSeek(t)", trace);
+        HasCount(2, rows);
+    }
+
+    [TestMethod]
+    public void DateRange_HalfOpenInterval_RangeSeeks()
+    {
+        // The canonical clustered-key range: created >= @from AND created < @to.
+        var (trace, rows) = Run("""
+            create table e (created date not null primary key, label varchar(10) not null);
+            insert e values ('2026-01-01', 'a'), ('2026-02-01', 'b'), ('2026-03-01', 'c')
+            """, "select label from e where created >= '2026-01-15' and created < '2026-03-01'");
+        Contains("RangeSeek(e)", trace);
+        HasCount(1, rows);
+        AreEqual("b", rows[0]);
+    }
+
+    [TestMethod]
+    public void RangeAfterWarmup_ReplaysDelta_SortedViewStaysCurrent()
+    {
+        // The lazily-built sorted view must be maintained incrementally: a row
+        // inserted after the range warm-up must appear in a later range scan via
+        // the journal replay, not a rebuild.
+        var (trace, rows) = WarmMutateProbe(
+            TableT, "select id from t where id > 0", "insert t values (4, 40)", "select id from t where id >= 3");
+        Contains("CacheReplay", trace);
+        DoesNotContain("CacheBuild", trace);
+        Contains("RangeSeek(t)", trace);
+        HasCount(2, rows);
+        Contains(3, rows);
+        Contains(4, rows);
+    }
+
+    [TestMethod]
+    public void RangeCorrectUnderManyMutations_MatchesIndependentBaseline()
+    {
+        // Stress the incrementally-maintained sorted view: interleave inserts,
+        // key-changing updates, and deletes, then confirm a range seek matches a
+        // brute-force filter over a no-WHERE full read (which doesn't seek).
+        var c = new Simulation().CreateDbConnection();
+        c.Open();
+        Exec(c, "create table t (id int not null primary key, val int not null)");
+        Exec(c, "insert t (id, val) select value, value from generate_series(1, 40)");
+        _ = ReadVal(c, "select id from t where id > 0");
+        Exec(c, "delete from t where id between 10 and 20");
+        Exec(c, "update t set id = id + 100 where id between 30 and 35");
+        Exec(c, "insert t values (5000, 0)");
+
+        var expected = new List<int>();
+        foreach (var o in ReadRows(c, "select id from t"))
+        {
+            var x = Convert.ToInt32(o);
+            if (x is > 25 and < 5001)
+                expected.Add(x);
+        }
+
+        var actual = new List<int>();
+        foreach (var o in ReadRows(c, "select id from t where id > 25 and id < 5001"))
+            actual.Add(Convert.ToInt32(o));
+
+        expected.Sort();
+        actual.Sort();
+        AreEqual(string.Join(",", expected), string.Join(",", actual));
+    }
 }

SqlServerSimulator/Parser/BooleanExpression.cs

@@ -5,6 +5,20 @@
 
 namespace SqlServerSimulator.Parser;
 
+/// <summary>
+/// The four ordering comparison operators, exposed by
+/// <see cref="BooleanExpression.TryGetRangeOperands"/> so the index-seek planner
+/// can recognize a range predicate (<c>col &gt; v</c>, <c>col BETWEEN lo AND hi</c>)
+/// on a leading key column without reaching into the private comparison hierarchy.
+/// </summary>
+internal enum RangeComparison
+{
+    Greater,
+    GreaterOrEqual,
+    Less,
+    LessOrEqual,
+}
+
 /// <summary>
 /// A specific type of expression used in WHERE clauses and similar branching scenarios.
 /// </summary>
@@ -515,6 +529,36 @@ internal virtual bool TryGetEqualityFamily([NotNullWhen(true)] out List<(Express
         return false;
     }
 
+    /// <summary>
+    /// Exposes the operands and operator when this predicate is an ordering
+    /// comparison (<c>&gt;</c> / <c>&gt;=</c> / <c>&lt;</c> / <c>&lt;=</c>);
+    /// returns false otherwise. Lets the index-seek planner recognize a range
+    /// bound (<c>col &gt; v</c> or <c>v &lt; col</c>) on a key column. The caller
+    /// normalizes which side is the column and flips the operator accordingly.
+    /// </summary>
+    internal virtual bool TryGetRangeOperands([NotNullWhen(true)] out Expression? left, out RangeComparison op, [NotNullWhen(true)] out Expression? right)
+    {
+        left = null;
+        right = null;
+        op = RangeComparison.Greater;
+        return false;
+    }
+
+    /// <summary>
+    /// Exposes the value and the inclusive lower / upper bounds when this
+    /// predicate is a non-negated <c>value BETWEEN lower AND upper</c>; returns
+    /// false otherwise (<c>NOT BETWEEN</c> is the non-contiguous complement, so
+    /// it declines). Lets the index-seek planner treat BETWEEN as a two-sided
+    /// inclusive range on a key column.
+    /// </summary>
+    internal virtual bool TryGetBetweenOperands([NotNullWhen(true)] out Expression? value, [NotNullWhen(true)] out Expression? lower, [NotNullWhen(true)] out Expression? upper)
+    {
+        value = null;
+        lower = null;
+        upper = null;
+        return false;
+    }
+
     /// <summary>
     /// Three-valued <c>AND</c>: <c>false AND x = false</c> regardless of
     /// <c>x</c>; <c>true AND x = x</c>; <c>NULL AND NULL = NULL</c>. Short-
@@ -782,6 +826,14 @@ internal override void VisitOperandExpressions(Action<Expression> visitor)
             visitor(lower);
             visitor(upper);
         }
+
+        internal override bool TryGetBetweenOperands([NotNullWhen(true)] out Expression? v, [NotNullWhen(true)] out Expression? lo, [NotNullWhen(true)] out Expression? hi)
+        {
+            // NOT BETWEEN is the non-contiguous complement (two open ranges), not
+            // a single seekable range, so only the positive form exposes bounds.
+            (v, lo, hi) = (value, lower, upper);
+            return !negated;
+        }
     }
 
     /// <summary>
@@ -1033,6 +1085,12 @@ private sealed class GreaterThanExpression(Expression left, Expression right) :
             ComparePromoted(left, right, runtime, "greater than", static (l, r) => l.CompareTo(r) > 0);
 
         internal override string DebugDisplay() => $"{left.DebugDisplay()} > {right.DebugDisplay()}";
+
+        internal override bool TryGetRangeOperands([NotNullWhen(true)] out Expression? l, out RangeComparison op, [NotNullWhen(true)] out Expression? r)
+        {
+            (l, op, r) = (left, RangeComparison.Greater, right);
+            return true;
+        }
     }
 
     private sealed class GreaterThanOrEqualExpression(Expression left, Expression right) : CompareExpression(left, right)
@@ -1041,6 +1099,12 @@ private sealed class GreaterThanOrEqualExpression(Expression left, Expression ri
             ComparePromoted(left, right, runtime, "greater than or equal to", static (l, r) => l.CompareTo(r) >= 0);
 
         internal override string DebugDisplay() => $"{left.DebugDisplay()} >= {right.DebugDisplay()}";
+
+        internal override bool TryGetRangeOperands([NotNullWhen(true)] out Expression? l, out RangeComparison op, [NotNullWhen(true)] out Expression? r)
+        {
+            (l, op, r) = (left, RangeComparison.GreaterOrEqual, right);
+            return true;
+        }
     }
 
     private sealed class LessThanExpression(Expression left, Expression right) : CompareExpression(left, right)
@@ -1049,6 +1113,12 @@ private sealed class LessThanExpression(Expression left, Expression right) : Com
             ComparePromoted(left, right, runtime, "less than", static (l, r) => l.CompareTo(r) < 0);
 
         internal override string DebugDisplay() => $"{left.DebugDisplay()} < {right.DebugDisplay()}";
+
+        internal override bool TryGetRangeOperands([NotNullWhen(true)] out Expression? l, out RangeComparison op, [NotNullWhen(true)] out Expression? r)
+        {
+            (l, op, r) = (left, RangeComparison.Less, right);
+            return true;
+        }
     }
 
     private sealed class LessThanOrEqualExpression(Expression left, Expression right) : CompareExpression(left, right)
@@ -1057,6 +1127,12 @@ private sealed class LessThanOrEqualExpression(Expression left, Expression right
             ComparePromoted(left, right, runtime, "less than or equal to", static (l, r) => l.CompareTo(r) <= 0);
 
         internal override string DebugDisplay() => $"{left.DebugDisplay()} <= {right.DebugDisplay()}";
+
+        internal override bool TryGetRangeOperands([NotNullWhen(true)] out Expression? l, out RangeComparison op, [NotNullWhen(true)] out Expression? r)
+        {
+            (l, op, r) = (left, RangeComparison.LessOrEqual, right);
+            return true;
+        }
     }
 
     /// <summary>

SqlServerSimulator/Parser/Selection.Execution.Aggregate.cs

@@ -326,6 +326,12 @@ internal readonly struct SqlValueKey(SqlValue[] values) : IEquatable<SqlValueKey
 
         private readonly SqlValue[] values = values;
 
+        /// <summary>The number of tuple components (key columns) in this key.</summary>
+        internal int ComponentCount => this.values.Length;
+
+        /// <summary>The component at <paramref name="index"/> — used by the range-seek ordered comparer.</summary>
+        internal SqlValue ComponentAt(int index) => this.values[index];
+
         public bool Equals(SqlValueKey other)
         {
             if (this.values.Length != other.values.Length)