fix(shared): sql.number infers INT (not BIGINT) for LIMIT/OFFSET compatibility

Empirical testing against e2-dogfood.staging (from @calvarjorge) showed
that Spark's LIMIT/OFFSET operators require IntegerType specifically —
LongType/BIGINT is rejected with INVALID_LIMIT_LIKE_EXPRESSION.DATA_TYPE:

  The offset expression must be integer type, but got "BIGINT".

So the original PR's "LIMIT now Just Works" claim was false: BIGINT
fails for the exact motivating case. Catalyst auto-widens INT to
BIGINT/DECIMAL/DOUBLE for wider columns, so defaulting to INT is
strictly better than defaulting to BIGINT.

Change sql.number inference:
- JS integer in [-2^31, 2^31 - 1] → INT (was BIGINT)
- JS integer outside INT but within MAX_SAFE_INTEGER → BIGINT
- integer-shaped string in INT range → INT (was BIGINT)
- integer-shaped string outside INT, within BIGINT → BIGINT
- everything else unchanged (DOUBLE for non-integer, NUMERIC for
  decimal strings, throw for out-of-BIGINT and non-numeric)

Update analytics.md to recommend `-- @param limit INT` and explain
the Spark IntegerType requirement. Update unit + integration tests
to pin INT bindings for in-range values, with explicit boundary
coverage at +/- 2^31. Regenerate the API reference page.

Co-authored-by: Isaac
Signed-off-by: James Broadhead <jamesbroadhead@gmail.com>

Author: jamesbroadhead

docs/docs/api/appkit/Variable.sql.md

@@ -294,18 +294,25 @@ number(value: string | number): SQLNumberMarker;
 
 Creates a numeric type parameter. The wire SQL type is inferred from the
 value so the parameter binds correctly in any context, including `LIMIT`
-and `OFFSET` (which require integer types):
+and `OFFSET`:
 
-- JS integer (`10`) → `BIGINT`
+- JS integer in `[-2^31, 2^31 - 1]` → `INT`
+- JS integer outside `INT` but within `Number.MAX_SAFE_INTEGER` → `BIGINT`
 - JS non-integer (`3.14`) → `DOUBLE`
-- integer-shaped string (`"10"`) → `BIGINT` (common HTTP-input case;
-  works with `LIMIT :n` / `OFFSET :m`)
+- integer-shaped string in `INT` range → `INT` (common HTTP-input case)
+- integer-shaped string outside `INT` but within `BIGINT` → `BIGINT`
 - decimal-shaped string (`"123.45"`) → `NUMERIC` (preserves precision)
 
+Why default to `INT`? Spark's `LIMIT` and `OFFSET` operators require
+`IntegerType` specifically — `BIGINT` (`LongType`) is rejected with
+`INVALID_LIMIT_LIKE_EXPRESSION.DATA_TYPE`. Catalyst auto-widens `INT`
+to `BIGINT` / `DECIMAL` / `DOUBLE` for wider columns, so `INT` is a
+strictly better default than `BIGINT`.
+
 Throws on `NaN`, `Infinity`, JS integers outside `Number.MAX_SAFE_INTEGER`,
-or non-numeric strings. Reach for `sql.int()`, `sql.bigint()`,
-`sql.float()`, `sql.double()`, or `sql.numeric()` if you need to override
-the inferred type.
+integer-shaped strings outside the `BIGINT` range, or non-numeric strings.
+Reach for `sql.int()`, `sql.bigint()`, `sql.float()`, `sql.double()`, or
+`sql.numeric()` to override the inferred type.
 
 #### Parameters
 
@@ -322,10 +329,11 @@ Marker for a numeric SQL parameter
 #### Example
 
 ```typescript
-sql.number(123);        // { __sql_type: "BIGINT", value: "123" }
-sql.number(0.5);        // { __sql_type: "DOUBLE", value: "0.5" }
-sql.number("10");       // { __sql_type: "BIGINT", value: "10" }
-sql.number("123.45");   // { __sql_type: "NUMERIC", value: "123.45" }
+sql.number(123);              // { __sql_type: "INT",    value: "123" }
+sql.number(3_000_000_000);    // { __sql_type: "BIGINT", value: "3000000000" }
+sql.number(0.5);              // { __sql_type: "DOUBLE", value: "0.5" }
+sql.number("10");             // { __sql_type: "INT",    value: "10" }
+sql.number("123.45");         // { __sql_type: "NUMERIC", value: "123.45" }
 ```
 
 ### numeric()

docs/docs/plugins/analytics.md

@@ -43,15 +43,17 @@ Use `:paramName` placeholders and optionally annotate parameter types using SQL
 ```sql
 -- @param startDate DATE
 -- @param endDate DATE
--- @param limit BIGINT
+-- @param limit INT
 SELECT ...
 WHERE usage_date BETWEEN :startDate AND :endDate
 LIMIT :limit
 ```
 
-`LIMIT` / `OFFSET` require an integer-typed binding (`INT` or `BIGINT`).
-Annotate accordingly, or use `sql.number()` (auto-infers `BIGINT` for integer
-inputs) / `sql.bigint()` / `sql.int()` at the call site.
+`LIMIT` / `OFFSET` require Spark `IntegerType` specifically — `BIGINT`
+(`LongType`) is rejected with `INVALID_LIMIT_LIKE_EXPRESSION.DATA_TYPE`.
+Annotate with `INT`, or use `sql.number()` (auto-infers `INT` for values in
+`[-2^31, 2^31-1]`, falling back to `BIGINT` for wider values) / `sql.int()`
+at the call site.
 
 **Supported `-- @param` types** (case-insensitive):
 - `STRING`, `BOOLEAN`, `DATE`, `TIMESTAMP`, `BINARY`

packages/appkit/src/plugins/analytics/tests/query.test.ts

@@ -32,7 +32,7 @@ describe("QueryProcessor", () => {
       expect(result.statement).toBe(query);
       expect(result.parameters).toHaveLength(2);
       expect(result.parameters).toEqual([
-        { name: "user_id", value: "123", type: "BIGINT" },
+        { name: "user_id", value: "123", type: "INT" },
         { name: "name", value: "Alice", type: "STRING" },
       ]);
     });
@@ -167,11 +167,12 @@ describe("QueryProcessor", () => {
 
     test("should not override workspace_id if already provided", async () => {
       const query = "SELECT * FROM data WHERE workspace_id = :workspaceId";
+      // 9876543210 exceeds INT_MAX (2^31 - 1) so inference falls through to
+      // BIGINT — appropriate for ID columns.
       const parameters = { workspaceId: sql.number("9876543210") };
 
       const result = await processor.processQueryParams(query, parameters);
 
-      // Integer-shaped strings infer BIGINT (matches LIMIT/OFFSET pattern)
       expect(result.workspaceId).toEqual({
         __sql_type: "BIGINT",
         value: "9876543210",
@@ -180,7 +181,11 @@ describe("QueryProcessor", () => {
   });
 
   describe("LIMIT / OFFSET bindings (regression for #323)", () => {
-    test("sql.number(integer) binds as BIGINT for LIMIT/OFFSET", () => {
+    // Spark requires IntegerType for LIMIT/OFFSET; BIGINT/LongType is
+    // rejected with INVALID_LIMIT_LIKE_EXPRESSION.DATA_TYPE. These tests
+    // pin INT inference so sql.number(req.query.n) works against the
+    // warehouse without explicit casting.
+    test("sql.number(integer) binds as INT for LIMIT/OFFSET", () => {
       const query = "SELECT * FROM events LIMIT :n OFFSET :m";
       const parameters = {
         n: sql.number(10),
@@ -190,12 +195,12 @@ describe("QueryProcessor", () => {
       const result = processor.convertToSQLParameters(query, parameters);
 
       expect(result.parameters).toEqual([
-        { name: "n", value: "10", type: "BIGINT" },
-        { name: "m", value: "20", type: "BIGINT" },
+        { name: "n", value: "10", type: "INT" },
+        { name: "m", value: "20", type: "INT" },
       ]);
     });
 
-    test("sql.number(integer-shaped string) binds as BIGINT for LIMIT/OFFSET", () => {
+    test("sql.number(integer-shaped string) binds as INT for LIMIT/OFFSET", () => {
       // Express/URLSearchParams return strings — this is the common
       // handler pattern: sql.number(req.query.n).
       const query = "SELECT * FROM events LIMIT :n OFFSET :m";
@@ -207,19 +212,19 @@ describe("QueryProcessor", () => {
       const result = processor.convertToSQLParameters(query, parameters);
 
       expect(result.parameters).toEqual([
-        { name: "n", value: "10", type: "BIGINT" },
-        { name: "m", value: "20", type: "BIGINT" },
+        { name: "n", value: "10", type: "INT" },
+        { name: "m", value: "20", type: "INT" },
       ]);
     });
 
-    test("sql.bigint(string) binds as BIGINT for LIMIT/OFFSET", () => {
+    test("sql.int(string) binds as INT for LIMIT/OFFSET (explicit form)", () => {
       const query = "SELECT * FROM events LIMIT :n";
-      const parameters = { n: sql.bigint("10") };
+      const parameters = { n: sql.int("10") };
 
       const result = processor.convertToSQLParameters(query, parameters);
 
       expect(result.parameters).toEqual([
-        { name: "n", value: "10", type: "BIGINT" },
+        { name: "n", value: "10", type: "INT" },
       ]);
     });
   });
@@ -275,7 +280,7 @@ describe("QueryProcessor", () => {
       expect(result.parameters[0]).toEqual({
         name: "age",
         value: "25",
-        type: "BIGINT",
+        type: "INT",
       });
     });
 

packages/shared/src/sql/helpers.ts

@@ -199,35 +199,49 @@ export const sql = {
   /**
    * Creates a numeric type parameter. The wire SQL type is inferred from the
    * value so the parameter binds correctly in any context, including `LIMIT`
-   * and `OFFSET` (which require integer types):
+   * and `OFFSET`:
    *
-   * - JS integer (`10`) → `BIGINT`
+   * - JS integer in `[-2^31, 2^31 - 1]` → `INT`
+   * - JS integer outside `INT` but within `Number.MAX_SAFE_INTEGER` → `BIGINT`
    * - JS non-integer (`3.14`) → `DOUBLE`
-   * - integer-shaped string (`"10"`) → `BIGINT` (common HTTP-input case;
-   *   works with `LIMIT :n` / `OFFSET :m`)
+   * - integer-shaped string in `INT` range → `INT` (common HTTP-input case)
+   * - integer-shaped string outside `INT` but within `BIGINT` → `BIGINT`
    * - decimal-shaped string (`"123.45"`) → `NUMERIC` (preserves precision)
    *
+   * Why default to `INT`? Spark's `LIMIT` and `OFFSET` operators require
+   * `IntegerType` specifically — `BIGINT` (`LongType`) is rejected with
+   * `INVALID_LIMIT_LIKE_EXPRESSION.DATA_TYPE`. Catalyst auto-widens `INT`
+   * to `BIGINT` / `DECIMAL` / `DOUBLE` for wider columns, so `INT` is a
+   * strictly better default than `BIGINT`.
+   *
    * Throws on `NaN`, `Infinity`, JS integers outside `Number.MAX_SAFE_INTEGER`,
-   * or non-numeric strings. Reach for `sql.int()`, `sql.bigint()`,
-   * `sql.float()`, `sql.double()`, or `sql.numeric()` if you need to override
-   * the inferred type.
+   * integer-shaped strings outside the `BIGINT` range, or non-numeric strings.
+   * Reach for `sql.int()`, `sql.bigint()`, `sql.float()`, `sql.double()`, or
+   * `sql.numeric()` to override the inferred type.
    *
    * @param value - Number or numeric string
    * @returns Marker for a numeric SQL parameter
    * @example
    * ```typescript
-   * sql.number(123);        // { __sql_type: "BIGINT", value: "123" }
-   * sql.number(0.5);        // { __sql_type: "DOUBLE", value: "0.5" }
-   * sql.number("10");       // { __sql_type: "BIGINT", value: "10" }
-   * sql.number("123.45");   // { __sql_type: "NUMERIC", value: "123.45" }
+   * sql.number(123);              // { __sql_type: "INT",    value: "123" }
+   * sql.number(3_000_000_000);    // { __sql_type: "BIGINT", value: "3000000000" }
+   * sql.number(0.5);              // { __sql_type: "DOUBLE", value: "0.5" }
+   * sql.number("10");             // { __sql_type: "INT",    value: "10" }
+   * sql.number("123.45");         // { __sql_type: "NUMERIC", value: "123.45" }
    * ```
    */
   number(value: number | string): SQLNumberMarker {
     if (typeof value === "number") {
       ensureFiniteNumber(value, "sql.number");
       if (Number.isInteger(value)) {
         ensureSafeInteger(value, "sql.number");
-        return { __sql_type: "BIGINT", value: BigInt(value).toString() };
+        const asBigInt = BigInt(value);
+        // INT (32-bit) is required by Spark for LIMIT/OFFSET; Catalyst
+        // widens INT → BIGINT/DECIMAL/DOUBLE automatically.
+        if (asBigInt >= INT_MIN && asBigInt <= INT_MAX) {
+          return { __sql_type: "INT", value: asBigInt.toString() };
+        }
+        return { __sql_type: "BIGINT", value: asBigInt.toString() };
       }
       return { __sql_type: "DOUBLE", value: value.toString() };
     }
@@ -237,20 +251,23 @@ export const sql = {
           `sql.number() expects number or numeric string, got: ${value === "" ? "empty string" : value}`,
         );
       }
-      // Integer-shaped strings: emit BIGINT so HTTP-input callers
-      // (`req.query.n` is always a string) work with LIMIT/OFFSET without
-      // having to reach for `sql.bigint("10")` explicitly. Out-of-range
-      // values throw — sql.numeric() is the right helper for
-      // arbitrary-precision integers.
+      // Integer-shaped strings get the same INT-preferring inference, so
+      // `sql.number(req.query.n)` (Express/URLSearchParams strings) works
+      // with LIMIT/OFFSET out of the box. Out-of-BIGINT-range throws —
+      // sql.numeric() is the right helper for arbitrary-precision integers.
       if (INTEGER_LITERAL_RE.test(value)) {
+        const parsed = BigInt(value);
         ensureInBigIntRange(
-          BigInt(value),
+          parsed,
           BIGINT_MIN,
           BIGINT_MAX,
           "BIGINT (64-bit signed)",
           "sql.number",
           "Use sql.numeric() with a string for arbitrary-precision integers.",
         );
+        if (parsed >= INT_MIN && parsed <= INT_MAX) {
+          return { __sql_type: "INT", value };
+        }
         return { __sql_type: "BIGINT", value };
       }
       // Non-integer strings stay NUMERIC: the caller chose to pass a string,

packages/shared/src/sql/tests/sql-helpers.test.ts

@@ -37,14 +37,45 @@ describe("SQL Helpers", () => {
   });
 
   describe("number()", () => {
-    it("should bind a JS integer as BIGINT (works in LIMIT/OFFSET)", () => {
+    it("should bind a JS integer in INT range as INT (works with Spark LIMIT/OFFSET)", () => {
+      // Spark requires IntegerType for LIMIT/OFFSET; BIGINT/LongType is
+      // rejected with INVALID_LIMIT_LIKE_EXPRESSION.DATA_TYPE. INT is
+      // auto-widened to BIGINT/DECIMAL/DOUBLE by Catalyst for wider columns.
       const result = sql.number(1234567890);
       expect(result).toEqual({
-        __sql_type: "BIGINT",
+        __sql_type: "INT",
         value: "1234567890",
       });
     });
 
+    it("should bind a JS integer outside INT range as BIGINT", () => {
+      const result = sql.number(3_000_000_000);
+      expect(result).toEqual({
+        __sql_type: "BIGINT",
+        value: "3000000000",
+      });
+    });
+
+    it("should bind INT boundaries correctly", () => {
+      expect(sql.number(2147483647)).toEqual({
+        __sql_type: "INT",
+        value: "2147483647",
+      });
+      expect(sql.number(-2147483648)).toEqual({
+        __sql_type: "INT",
+        value: "-2147483648",
+      });
+      // Just past INT_MAX → BIGINT
+      expect(sql.number(2147483648)).toEqual({
+        __sql_type: "BIGINT",
+        value: "2147483648",
+      });
+      expect(sql.number(-2147483649)).toEqual({
+        __sql_type: "BIGINT",
+        value: "-2147483649",
+      });
+    });
+
     it("should bind a JS non-integer as DOUBLE", () => {
       const result = sql.number(3.14);
       expect(result).toEqual({
@@ -53,16 +84,24 @@ describe("SQL Helpers", () => {
       });
     });
 
-    it("should bind an integer-shaped string as BIGINT (HTTP-input case)", () => {
+    it("should bind an integer-shaped string in INT range as INT (HTTP-input case)", () => {
       // Express/URLSearchParams return strings; common pattern is
-      // sql.number(req.query.n) which must work with LIMIT/OFFSET.
+      // sql.number(req.query.n) which must work with Spark LIMIT/OFFSET.
       const result = sql.number("1234567890");
       expect(result).toEqual({
-        __sql_type: "BIGINT",
+        __sql_type: "INT",
         value: "1234567890",
       });
     });
 
+    it("should bind an integer-shaped string outside INT range as BIGINT", () => {
+      const result = sql.number("3000000000");
+      expect(result).toEqual({
+        __sql_type: "BIGINT",
+        value: "3000000000",
+      });
+    });
+
     it("should accept BIGINT-boundary integer strings", () => {
       expect(sql.number("9223372036854775807")).toEqual({
         __sql_type: "BIGINT",
@@ -112,10 +151,11 @@ describe("SQL Helpers", () => {
       expect(() => sql.number(Number.NaN)).toThrow(/finite number/);
     });
 
-    it("should emit canonical decimal text (no exponent) for safe integers", () => {
+    it("should emit canonical decimal text (no exponent) for large safe integers", () => {
       // Sanity check: even though Number.prototype.toString could emit
       // exponent form for very large integers, the helper always emits
-      // decimal text via BigInt(value).toString().
+      // decimal text via BigInt(value).toString(). 1e15 is outside INT
+      // range, so the wire type is BIGINT.
       const result = sql.number(1e15);
       expect(result).toEqual({
         __sql_type: "BIGINT",