v2.2 part 1 — parameterized TOP / OFFSET / FETCH NEXT

The v2.1 parser required integer literals in paging slots; v2.2 admits
any scalar expression. Primary unlock: consumers can supply the page
size as a parameter rather than string-interpolating it into the SQL.
This was blocking 8 paging stored procs in CosmoMailServer's Phase C
migration plus the UPDATE TOP(n) claim-pending rewrites.

Surface:
  SELECT TOP @n          … ORDER BY id
  SELECT TOP (@A + @b)   … ORDER BY id           -- arithmetic via parens
  SELECT … ORDER BY id OFFSET @offset ROWS FETCH NEXT @limit ROWS ONLY
  UPDATE TOP(@Batch) …
  DELETE TOP(@n)   …

AST: SelectStatement.Top/Offset/Fetch, UpdateStatement.Top, and
DeleteStatement.Top change from `long?` to `Expression?`. Literal TOPs
now wrap to LiteralExpression(SqlValue.From(n)).

Parser: SELECT's bare-form `TOP n` keeps a tight `ParseUnary()`-only
grammar to avoid the `SELECT TOP 10 * FROM t` wildcard-vs-multiplication
ambiguity. The paren form `TOP (n)` opens up to full ParseExpression,
matching T-SQL's spec — for non-trivial paging expressions you must
parenthesise. OFFSET / FETCH and UPDATE/DELETE TOP(n) all accept full
expressions (no wildcard ambiguity in those positions).

Executor: a shared EvaluatePagingExpression helper resolves the
Expression to a non-negative long using a dummy empty-row RowContext
(same pattern as the no-FROM SELECT path). Called once per statement
outside the scan loop so the cost is constant regardless of row count.

Phase 9 tests (9 cases): parameter-driven TOP/OFFSET/FETCH, arithmetic
in TOP-parens, UPDATE TOP(@Batch) for claim-pending, DELETE TOP(@n),
negative-parameter rejection, string-parameter rejection, and the
literal-TOP regression path. Full suite stable: 240/240 across 3 runs
(231 v2.1 + 9 new).

Unblocks: 8 of the 16 procs that throw NotSupportedException in
CosmoMailServer's CosmoKvCompatibilitySqlDatabase. Phase C resumes
once 2.2.0 ships.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: vkuttyp

src/CosmoSQLClient.CosmoKv/Ast/Statement.cs

@@ -40,9 +40,9 @@ internal sealed record SelectStatement(
     IReadOnlyList<Expression>? GroupBy,
     Expression? Having,
     IReadOnlyList<OrderByItem>? OrderBy,
-    long? Top,
-    long? Offset,
-    long? Fetch) : Statement
+    Expression? Top,
+    Expression? Offset,
+    Expression? Fetch) : Statement
 {
     /// <summary>
     /// Convenience accessor: the base table's identifier (no alias). Used by
@@ -85,15 +85,15 @@ internal sealed record UpdateStatement(
     string TableName,
     IReadOnlyList<UpdateAssignment> Assignments,
     Expression? Where,
-    long? Top,
+    Expression? Top,
     OutputClause? Output) : Statement;
 
 internal sealed record UpdateAssignment(string ColumnName, Expression Value);
 
 internal sealed record DeleteStatement(
     string TableName,
     Expression? Where,
-    long? Top,
+    Expression? Top,
     OutputClause? Output) : Statement;
 
 // ── OUTPUT clause (v2.1) ─────────────────────────────────────────────────────

src/CosmoSQLClient.CosmoKv/Execution/Executor.cs

@@ -495,8 +495,10 @@ private async Task<long> NextIdentityAsync(string tableName, long seed, long inc
         }
 
         // TOP / OFFSET-FETCH paging.
-        int skip = (int)(s.Offset ?? 0);
-        int? take = (int?)(s.Fetch ?? s.Top);
+        int skip = (int)(EvaluatePagingExpression(s.Offset, bound, "OFFSET") ?? 0);
+        long? takeLong = EvaluatePagingExpression(s.Fetch ?? s.Top, bound,
+                                                 s.Fetch is not null ? "FETCH NEXT" : "TOP");
+        int? take = takeLong is null ? null : (int)takeLong.Value;
         if (skip < 0) skip = 0;
         if (skip > matched.Count) skip = matched.Count;
 
@@ -513,6 +515,35 @@ private async Task<long> NextIdentityAsync(string tableName, long seed, long inc
         return (resultCols, rows);
     }
 
+    /// <summary>
+    /// Evaluate a paging expression (TOP, OFFSET, FETCH NEXT) to a long.
+    /// v2.2 admitted any scalar expression in these slots — typically a
+    /// parameter (<c>TOP @limit</c>) but literals and arithmetic also work.
+    /// Returns null when the expression is null. Throws if the resolved
+    /// value is negative or not an integer.
+    /// </summary>
+    private static long? EvaluatePagingExpression(
+        Expression? expr, IReadOnlyDictionary<string, SqlValue> bound, string clauseName)
+    {
+        if (expr is null) return null;
+        var dummyTable = new TableSchema(
+            Name: "(paging)",
+            Columns: Array.Empty<ColumnSchema>(),
+            PrimaryKeyColumnIndex: null,
+            IdentityColumnIndex: null);
+        var ctx = new ExpressionEvaluator.RowContext(
+            dummyTable, ReadOnlySpan<SqlValue>.Empty, bound);
+        var v = ExpressionEvaluator.Evaluate(expr, ctx);
+        long? n = v.AsInt();
+        if (n is null)
+            throw new InvalidOperationException(
+                $"{clauseName} value must be an integer; got {v.Kind}.");
+        if (n < 0)
+            throw new InvalidOperationException(
+                $"{clauseName} value must be non-negative; got {n}.");
+        return n;
+    }
+
     /// <summary>
     /// SELECT path for FROM clauses with JOINs. v2.1 ships INNER JOIN with
     /// 2-3 table chains; the executor materialises each table, then runs a
@@ -640,8 +671,10 @@ private async Task<long> NextIdentityAsync(string tableName, long seed, long inc
         }
 
         // TOP / OFFSET / FETCH paging.
-        int skip = (int)(s.Offset ?? 0);
-        int? take = (int?)(s.Fetch ?? s.Top);
+        int skip = (int)(EvaluatePagingExpression(s.Offset, bound, "OFFSET") ?? 0);
+        long? takeLong = EvaluatePagingExpression(s.Fetch ?? s.Top, bound,
+                                                 s.Fetch is not null ? "FETCH NEXT" : "TOP");
+        int? take = takeLong is null ? null : (int)takeLong.Value;
         if (skip < 0) skip = 0;
         if (skip > matched.Count) skip = matched.Count;
 
@@ -869,8 +902,10 @@ private readonly record struct JoinProjectedColumn(
         }
 
         // Paging.
-        int skip = (int)(s.Offset ?? 0);
-        int? take = (int?)(s.Fetch ?? s.Top);
+        int skip = (int)(EvaluatePagingExpression(s.Offset, bound, "OFFSET") ?? 0);
+        long? takeLong = EvaluatePagingExpression(s.Fetch ?? s.Top, bound,
+                                                 s.Fetch is not null ? "FETCH NEXT" : "TOP");
+        int? take = takeLong is null ? null : (int)takeLong.Value;
         if (skip < 0) skip = 0;
         if (skip > keptGroups.Count) skip = keptGroups.Count;
         int end = take is null ? keptGroups.Count : Math.Min(keptGroups.Count, skip + take.Value);
@@ -1176,6 +1211,11 @@ private async Task<UpdateResult> ExecuteUpdateCore(
         var plan = QueryPlanner.Plan(
             table, _catalog.IndexesFor(table.Name), s.Where, orderBy: null, bound);
 
+        // Resolve TOP(n) once up-front — the expression may reference bound
+        // parameters but doesn't depend on the row being scanned, so a single
+        // evaluation outside the loop suffices.
+        long? topLimit = EvaluatePagingExpression(s.Top, bound, "TOP");
+
         var pending = new List<(long RowId, SqlValue[] Old, SqlValue[] New)>();
         await foreach (var (row, rowId) in EnumerateAsync(plan, ct))
         {
@@ -1200,7 +1240,7 @@ private async Task<UpdateResult> ExecuteUpdateCore(
             // TOP(n) — once we've accumulated n matches, stop the scan.
             // Note: T-SQL UPDATE TOP(n) without ORDER BY is intentionally
             // non-deterministic about WHICH n rows; we follow that.
-            if (s.Top is long topN && pending.Count >= topN) break;
+            if (topLimit is long topN && pending.Count >= topN) break;
         }
         foreach (var (rowId, oldRow, newRow) in pending)
         {
@@ -1267,7 +1307,8 @@ private async Task<DeleteResult> ExecuteDeleteCore(
             table, _catalog.IndexesFor(table.Name), s.Where, orderBy: null, bound);
 
         // Collect (rowid, full row) for victims so we can clean up indexes
-        // too. TOP(n) caps the victim count.
+        // too. TOP(n) caps the victim count; evaluated once outside the loop.
+        long? topLimit = EvaluatePagingExpression(s.Top, bound, "TOP");
         var victims = new List<(long RowId, SqlValue[] Row)>();
         await foreach (var (row, rowId) in EnumerateAsync(plan, ct))
         {
@@ -1277,7 +1318,7 @@ private async Task<DeleteResult> ExecuteDeleteCore(
                 if (!ExpressionEvaluator.EvaluatePredicate(s.Where, ctx)) continue;
             }
             victims.Add((rowId, row));
-            if (s.Top is long topN && victims.Count >= topN) break;
+            if (topLimit is long topN && victims.Count >= topN) break;
         }
         foreach (var (rowId, row) in victims)
         {

src/CosmoSQLClient.CosmoKv/Parsing/TSqlParser.cs

@@ -413,11 +413,13 @@ private SelectStatement ParseSelect()
     {
         Expect(TokenKind.Select);
 
-        long? top = null;
+        Expression? top = null;
         if (Current().Kind == TokenKind.Top)
         {
             Advance();
-            top = ParseIntegerLiteral();
+            // v2.2: TOP accepts any expression (parameter, literal, arithmetic).
+            // T-SQL also allows `TOP (expr)` with parens; both forms work here.
+            top = ParseTopExpression();
         }
 
         var items = new List<SelectItem>();
@@ -503,17 +505,20 @@ private SelectStatement ParseSelect()
             orderBy = list;
         }
 
-        long? offset = null, fetch = null;
+        Expression? offset = null, fetch = null;
         if (Current().Kind == TokenKind.Offset)
         {
             Advance();
-            offset = ParseIntegerLiteral();
+            // v2.2: OFFSET / FETCH accept arbitrary expressions, not just
+            // integer literals — primarily so callers can parameterise
+            // page size (@offset / @limit).
+            offset = ParseExpression();
             Expect(TokenKind.Rows);
             if (Current().Kind == TokenKind.Fetch)
             {
                 Advance();
                 Expect(TokenKind.Next);
-                fetch = ParseIntegerLiteral();
+                fetch = ParseExpression();
                 Expect(TokenKind.Rows);
                 Expect(TokenKind.Only);
             }
@@ -609,7 +614,7 @@ or TokenKind.Offset or TokenKind.EndOfInput or TokenKind.Semicolon
     private UpdateStatement ParseUpdate()
     {
         Expect(TokenKind.Update);
-        long? top = ParseOptionalTopWithParens();
+        Expression? top = ParseOptionalTopWithParens();
         string table = ParseDottedName();
         Expect(TokenKind.Set);
         var assigns = new List<UpdateAssignment>();
@@ -641,7 +646,7 @@ private UpdateStatement ParseUpdate()
     private DeleteStatement ParseDelete()
     {
         Expect(TokenKind.Delete);
-        long? top = ParseOptionalTopWithParens();
+        Expression? top = ParseOptionalTopWithParens();
         // FROM is optional in T-SQL DELETE.
         ConsumeOptional(TokenKind.From);
         string table = ParseDottedName();
@@ -662,18 +667,42 @@ private DeleteStatement ParseDelete()
     // ── OUTPUT clause + TOP(n) helpers ──────────────────────────────────────
 
     /// <summary>
-    /// Parse <c>TOP ( integer-literal )</c> if present. UPDATE/DELETE require
+    /// Parse <c>TOP ( expression )</c> if present. UPDATE/DELETE require
     /// parens per T-SQL grammar; SELECT's bare-form TOP is parsed inline in
-    /// <see cref="ParseSelect"/> and is unaffected.
+    /// <see cref="ParseSelect"/>. v2.2: accepts any expression (parameter,
+    /// literal, arithmetic) rather than just an integer literal so callers
+    /// can supply <c>TOP(@batch_size)</c>.
     /// </summary>
-    private long? ParseOptionalTopWithParens()
+    private Expression? ParseOptionalTopWithParens()
     {
         if (Current().Kind != TokenKind.Top) return null;
         Advance();
         Expect(TokenKind.LParen);
-        long n = ParseIntegerLiteral();
+        var e = ParseExpression();
         Expect(TokenKind.RParen);
-        return n;
+        return e;
+    }
+
+    /// <summary>
+    /// Parse the SELECT-form <c>TOP n</c> or <c>TOP (expr)</c>.
+    /// T-SQL distinguishes the two: bare-form TOP only accepts a single
+    /// atom (literal, parameter, function call) because the SELECT-list's
+    /// <c>*</c> wildcard would otherwise be ambiguous with multiplication
+    /// (<c>SELECT TOP 10 * FROM t</c> — the <c>*</c> is the wildcard).
+    /// Non-trivial expressions must be parenthesised: <c>TOP (10 * 2)</c>.
+    /// </summary>
+    private Expression ParseTopExpression()
+    {
+        if (Current().Kind == TokenKind.LParen)
+        {
+            Advance();
+            var e = ParseExpression();
+            Expect(TokenKind.RParen);
+            return e;
+        }
+        // Bare form: parse only a single atom + unary minus to keep `*`
+        // unambiguous with the SELECT-list wildcard.
+        return ParseUnary();
     }
 
     /// <summary>

tests/CosmoSQLClient.CosmoKv.Tests/Phase2ParserTests.cs

@@ -62,16 +62,20 @@ public void Select_OrderBy_MultiColumn_WithDesc()
     public void Select_Top()
     {
         var s = (SelectStatement)TSqlParser.Parse("SELECT TOP 10 * FROM t");
-        Assert.Equal(10, s.Top);
+        // v2.2: Top is now Expression; literal TOPs parse as LiteralExpression.
+        var lit = Assert.IsType<LiteralExpression>(s.Top);
+        Assert.Equal(10L, lit.Value.AsInt());
     }
 
     [Fact]
     public void Select_OffsetFetch()
     {
         var s = (SelectStatement)TSqlParser.Parse(
             "SELECT * FROM t ORDER BY id OFFSET 20 ROWS FETCH NEXT 10 ROWS ONLY");
-        Assert.Equal(20, s.Offset);
-        Assert.Equal(10, s.Fetch);
+        var offsetLit = Assert.IsType<LiteralExpression>(s.Offset);
+        Assert.Equal(20L, offsetLit.Value.AsInt());
+        var fetchLit = Assert.IsType<LiteralExpression>(s.Fetch);
+        Assert.Equal(10L, fetchLit.Value.AsInt());
     }
 
     [Fact]