Map DATEADD's out-of-int-range count to its Msg 517 date-overflow error instead of leaking a raw OverflowException, and document the same int-narrowing gap in the sibling string/char-code scalars as a deliberate known limitation.

Author: RyanLamansky

SqlServerSimulator.Tests/BuiltInFunctionTests.cs

@@ -170,6 +170,17 @@ public void DecimalLiteralBeyondMaxPrecision_RaisesMsg1007()
     public void ReplaceWithEmptySearch_ReturnsInputUnchanged()
         => AreEqual("abc", ExecuteScalar("select replace('abc', '', 'X')"));
 
+    [TestMethod]
+    [DataRow("dateadd(second, 9223372036854775807, getdate())")]
+    [DataRow("dateadd(year, 2147483648, getdate())")]
+    [DataRow("dateadd(day, 9999999999, getdate())")]
+    public void DateAddCountOutOfIntRange_RaisesMsg517(string expression)
+    {
+        var ex = Throws<SimulatedSqlException>(() => ExecuteScalar($"select {expression}"));
+        AreEqual(517, ex.Number);
+        Assert.Contains("caused an overflow", ex.Message);
+    }
+
     [TestMethod]
     public void FunctionOfColumn_FromTable()
     {

SqlServerSimulator/Parser/Expressions/DateAdd.cs

@@ -37,7 +37,7 @@ public override SqlValue Run(RuntimeContext runtime)
         if (value.IsNull || n.IsNull)
             return SqlValue.Null(value.Type);
         DatePartKinds.RequireCompatible(this.kind, this.keywordText, value.Type, "dateadd");
-        var nInt = n.CoerceTo(SqlType.Int32).AsInt32;
+        var nInt = DatePartKinds.CoerceCount(n, value.Type);
         return DatePartKinds.Add(this.kind, value, nInt);
     }
 

SqlServerSimulator/Parser/Expressions/DatePartKind.cs

@@ -350,6 +350,26 @@ public static int Extract(DatePartKind kind, SqlValue value)
         };
     }
 
+    /// <summary>
+    /// Coerces a DATEADD count to <c>int</c>. A value outside int range can
+    /// only push the result past the date type's representable range, which
+    /// SQL Server reports as the same Msg 517 date overflow <see cref="Add"/>
+    /// raises — not an int-conversion error (probe-confirmed across second /
+    /// day / year). Without this, the bigint-to-int narrowing would leak a
+    /// raw <see cref="OverflowException"/>.
+    /// </summary>
+    public static int CoerceCount(SqlValue number, SqlType targetType)
+    {
+        try
+        {
+            return number.CoerceTo(SqlType.Int32).AsInt32;
+        }
+        catch (OverflowException)
+        {
+            throw SimulatedSqlException.DateAddOverflow(FamilyRootName(targetType));
+        }
+    }
+
     /// <summary>
     /// Returns the result of <paramref name="value"/> + <paramref name="n"/>
     /// units of <paramref name="kind"/>, preserving the input's SQL type.

docs/claude/scalars.md

@@ -93,6 +93,10 @@ Bundle that fills out the raw-SQL string surface that EF's `FromSqlInterpolated`
 - **`SPACE(count)`** always returns `varchar` (never nvarchar), truncated to 8000 chars. NULL / negative count → NULL.
 - **`FORMAT(value, format [, culture])`** returns `nvarchar`. Implementation routes through .NET's `IFormattable.ToString(format, culture)` on the underlying CLR value, matching SQL Server's CLR-passthrough shape. Accepted value types: numeric (integer / decimal / float / real / money / smallmoney) and date-time family (date / datetime / smalldatetime / datetime2 / datetimeoffset / time). Strings, bit, binary, uniqueidentifier, rowversion → Msg 8116 at runtime. NULL value → NULL; NULL format → Msg 8116 (probed: ordering doesn't matter — the format-NULL check fires first). Culture defaults to en-US; invalid culture name silently falls back to en-US. .NET `FormatException` (e.g. `decimal.ToString("D5")`) → NULL; unrecognized custom-format tokens that .NET passes through (e.g. `int.ToString("qq qq")`) are echoed verbatim.
 
+## Known gap: out-of-`int`-range integer arguments
+
+A length / position / count / code-point argument that exceeds `int` range surfaces a raw .NET `OverflowException` from the `int` narrowing instead of the function's normal result. Affected: `SUBSTRING` (length), `CHARINDEX` (start), `STUFF` (start / length — preempts the documented out-of-range-returns-NULL handling above), `REPLICATE` (count), `SPACE` (count), `CHOOSE` (index), `CHAR` / `NCHAR` (code point). `LEFT` / `RIGHT` (Msg 8115) and `DATEADD` (Msg 517) harden this argument; the rest don't. Left point-local deliberately: real SQL Server's response is per-function (clamp, compute as bigint, or a value-class error), so a single shared error wouldn't be faithful, and the trigger is pathological — no realistic query or EF emission passes a count / position outside `int` range. A value held in a variable could reach it; the failure is a clean abort, just not the SQL-Server-shaped one.
+
 ## EF.Functions-driven type-check / random scalars: `ISNUMERIC` / `ISDATE` / `RAND`
 - **`ISNUMERIC(expression)`** returns `int` (1 / 0); NULL → 0 (not NULL). Famously lossy on real SQL Server: a bare sign / decimal point / comma / currency symbol returns 1, hex prefixes return 0, internal whitespace breaks the match. The simulator's hand-rolled scanner consumes (in order: optional sign and currency in either order; digit / decimal / comma run; optional `e`/`E`/`d`/`D` exponent requiring a leading digit AND a trailing digit after optional sign). At least one of {digit, decimal/comma, sign, currency} must have been consumed for the result to be true. Bit-typed input returns 0 even though bit lives in the Integer category (probe-confirmed). Anything that doesn't fully consume after trimming whitespace returns 0.
 - **`ISDATE(expression)`** returns `int` (1 / 0) and validates against the legacy `datetime` range (1753-9999). Empty string short-circuits to 0 (the shared `TryParseLegacyDateTime` treats `""` as datetime base-date for CAST support, but ISDATE specifically rejects). Modern `date` / `time` / `datetimeoffset` raise Msg 8116 — ISDATE intentionally lives in the legacy datetime domain. Integer input is implicitly stringified and re-parsed (so `ISDATE(20260512)` = 1 via `'20260512'` matching `yyyyMMdd`; `ISDATE(1)` = 0 because `'1'` parses to year 1 < 1753). Float / decimal / non-integer-non-string types always return 0.