IS [NOT] DISTINCT FROM (SQL Server 2022 NULL-safe equality): new DistinctFromExpression : BooleanExpression — tuple-switch on (l.IsNull, r.IsNull) returns false when both NULL (not distinct), true when exactly one NULL (distinct), and routes through CompareValuesPromoted for the two-non-null case. Result XOR'd with the negated flag; always definitive (never UNKNOWN) since the per-side null check absorbs what would otherwise be the UNKNOWN-producing comparison. Parser refactor: ParseIsNullSuffix → ParseIsSuffix dispatches on the post-IS-[NOT] token — Null routes to the existing IsNullExpression (no behavior change), Distinct consumes the required From keyword (Msg 102 if missing) and reads the RHS via Expression.Parse. Probe-confirmed semantics: predicate-only at the grammar level (bare-SELECT-list select 5 is distinct from nullraises Msg 156 in real SQL Server because IS isn't a value operator); reachable in any boolean context (WHERE / HAVING / ON / CASE-WHEN / CHECK). Type promotion follows the regular comparison path — numerically-equal int vs decimal collapses to "not distinct"; genuinely-uncoercible operand pairs (e.g. 'hello' is distinct from 5) surface Msg 245 from the comparator unchanged. 18 new DistinctFromTests via DataRow + multi-row scenarios cover every NULL × value combination × negation, type promotion across int/decimal and varchar/nvarchar, CASE-WHEN context, multi-row WHERE for both DISTINCT and NOT DISTINCT (validating the (NULL, NULL) match and the (NULL, value) distinction), NULL-safe INNER JOIN ON (the canonical app-side use — regular= excludes NULL=NULL pairs, NOT DISTINCT FROM includes them), Msg 245 type-mismatch surfacing, Msg 102 missing-From, and an IS NULL / IS NOT NULL regression smoke test against the parser refactor. docs/claude/query.md Boolean section extended with the IS-family always-definitive note plus a dedicated paragraph on the type-promotion + bare-SELECT-list rejection.

Author: RyanLamansky

SqlServerSimulator.Tests/DistinctFromTests.cs

@@ -0,0 +1,149 @@
+using System.Data.Common;
+using static Microsoft.VisualStudio.TestTools.UnitTesting.Assert;
+
+namespace SqlServerSimulator;
+
+/// <summary>
+/// Tests for <c>a IS [NOT] DISTINCT FROM b</c> — SQL Server 2022 NULL-safe
+/// comparison. Unlike <c>=</c>/<c>&lt;&gt;</c> (which return UNKNOWN when
+/// either operand is NULL), the DISTINCT-FROM family treats NULL as a
+/// comparable value: two NULLs are not distinct, one NULL plus a non-NULL is
+/// distinct. Probed against SQL Server 2025 (2026-05-13).
+/// </summary>
+[TestClass]
+public sealed class DistinctFromTests
+{
+    [TestMethod]
+    [DataRow("5 is distinct from 5", 0)]
+    [DataRow("5 is distinct from 6", 1)]
+    [DataRow("cast(null as int) is distinct from 5", 1)]
+    [DataRow("5 is distinct from cast(null as int)", 1)]
+    [DataRow("cast(null as int) is distinct from cast(null as int)", 0)]
+    [DataRow("5 is not distinct from 5", 1)]
+    [DataRow("5 is not distinct from 6", 0)]
+    [DataRow("cast(null as int) is not distinct from 5", 0)]
+    [DataRow("cast(null as int) is not distinct from cast(null as int)", 1)]
+    public void Basic(string predicate, int expectedCount) =>
+        AreEqual(expectedCount,
+            new Simulation().ExecuteReader($"select 1 where {predicate}").EnumerateRecords().Count());
+
+    [TestMethod]
+    public void TypePromotion_IntVsDecimal_NumericallyEqual()
+    {
+        // 5 (int) vs 5.0 (decimal) — values numerically equal; not distinct.
+        AreEqual(0,
+            new Simulation().ExecuteReader(
+                "select 1 where 5 is distinct from cast(5.0 as decimal(5,2))").EnumerateRecords().Count());
+        AreEqual(1,
+            new Simulation().ExecuteReader(
+                "select 1 where 5 is distinct from cast(5.5 as decimal(5,2))").EnumerateRecords().Count());
+    }
+
+    [TestMethod]
+    public void TypePromotion_VarcharVsNvarchar_Equal()
+    {
+        AreEqual(0,
+            new Simulation().ExecuteReader(
+                "select 1 where 'hello' is distinct from cast('hello' as nvarchar(10))").EnumerateRecords().Count());
+    }
+
+    [TestMethod]
+    public void CaseWhenContext()
+    {
+        // Probe-confirmed: works in CASE-WHEN predicate position.
+        AreEqual("yes",
+            new Simulation().ExecuteScalar(
+                "select case when 5 is distinct from null then 'yes' else 'no' end"));
+    }
+
+    [TestMethod]
+    public void MultiRowWhere_DistinctFromPicksUpNullEdges()
+    {
+        using var conn = new Simulation().CreateOpenConnection();
+        _ = conn.CreateCommand("""
+            create table dt (id int, a int, b int);
+            insert dt values (1, 5, 5), (2, 5, null), (3, null, 5), (4, null, null), (5, 5, 6)
+            """).ExecuteNonQuery();
+        using var reader = conn.CreateCommand(
+            "select id from dt where a is distinct from b order by id").ExecuteReader();
+        var ids = new List<int>();
+        while (reader.Read())
+            ids.Add(reader.GetInt32(0));
+        // Distinct rows: (5,null), (null,5), (5,6). Not-distinct: (5,5), (null,null).
+        CollectionAssert.AreEqual(new int[] { 2, 3, 5 }, ids);
+    }
+
+    [TestMethod]
+    public void MultiRowWhere_NotDistinctFromIncludesBothNullRow()
+    {
+        using var conn = new Simulation().CreateOpenConnection();
+        _ = conn.CreateCommand("""
+            create table dt (id int, a int, b int);
+            insert dt values (1, 5, 5), (2, 5, null), (3, null, 5), (4, null, null), (5, 5, 6)
+            """).ExecuteNonQuery();
+        using var reader = conn.CreateCommand(
+            "select id from dt where a is not distinct from b order by id").ExecuteReader();
+        var ids = new List<int>();
+        while (reader.Read())
+            ids.Add(reader.GetInt32(0));
+        // Probe-confirmed: NULL=NULL counts as a match here (the key
+        // difference from regular `=`).
+        CollectionAssert.AreEqual(new int[] { 1, 4 }, ids);
+    }
+
+    [TestMethod]
+    public void JoinOn_NullSafeJoin()
+    {
+        using var conn = new Simulation().CreateOpenConnection();
+        _ = conn.CreateCommand("""
+            create table j1 (id int, v int);
+            create table j2 (id int, v int);
+            insert j1 values (1, 5), (2, null), (3, 10);
+            insert j2 values (1, 5), (2, null), (3, 11)
+            """).ExecuteNonQuery();
+        using var reader = conn.CreateCommand(
+            "select j1.id from j1 inner join j2 on j1.v is not distinct from j2.v order by j1.id").ExecuteReader();
+        var ids = new List<int>();
+        while (reader.Read())
+            ids.Add(reader.GetInt32(0));
+        // Probe-confirmed: NULL-safe join matches rows where both v are NULL;
+        // regular `=` would exclude that pair.
+        CollectionAssert.AreEqual(new int[] { 1, 2 }, ids);
+    }
+
+    [TestMethod]
+    public void TypeMismatch_SurfacesUnderlyingConversionError()
+    {
+        // Promotion routes through CompareValuesPromoted; string→int conversion
+        // fails with Msg 245 (same as regular `=` would).
+        var ex = Throws<DbException>(() =>
+            new Simulation().ExecuteScalar("select 1 where 'hello' is distinct from 5"));
+        AreEqual("245", ex.Data["HelpLink.EvtID"]);
+    }
+
+    [TestMethod]
+    public void MissingFromKeyword_SyntaxError()
+    {
+        // `IS DISTINCT rhs` without FROM → syntax error at rhs.
+        var ex = Throws<DbException>(() =>
+            new Simulation().ExecuteScalar("select 1 where 5 is distinct 5"));
+        AreEqual("102", ex.Data["HelpLink.EvtID"]);
+    }
+
+    [TestMethod]
+    public void RegressionIsNullStillWorks()
+    {
+        // ParseIsSuffix took over from ParseIsNullSuffix; verify the IS NULL /
+        // IS NOT NULL branches still route correctly. Existing IsNullExpression
+        // tests in other suites cover broader semantics — this is a smoke
+        // test for the refactor.
+        AreEqual(1, new Simulation().ExecuteReader(
+            "select 1 where cast(null as int) is null").EnumerateRecords().Count());
+        AreEqual(0, new Simulation().ExecuteReader(
+            "select 1 where 5 is null").EnumerateRecords().Count());
+        AreEqual(1, new Simulation().ExecuteReader(
+            "select 1 where 5 is not null").EnumerateRecords().Count());
+        AreEqual(0, new Simulation().ExecuteReader(
+            "select 1 where cast(null as int) is not null").EnumerateRecords().Count());
+    }
+}

SqlServerSimulator/Parser/BooleanExpression.cs

@@ -134,7 +134,7 @@ private static BooleanExpression ParseComparison(Expression left, ParserContext
             case ReservedKeyword { Keyword: Keyword.Like }:
                 return ParseLike(left, context, negated: false);
             case ReservedKeyword { Keyword: Keyword.Is }:
-                return ParseIsNullSuffix(left, context);
+                return ParseIsSuffix(left, context);
             case ReservedKeyword { Keyword: Keyword.In }:
                 return ParseInList(left, context, negated: false);
             case ReservedKeyword { Keyword: Keyword.Between }:
@@ -285,13 +285,14 @@ private static LikeExpression ParseLike(Expression left, ParserContext context,
     }
 
     /// <summary>
-    /// Parses the <c>IS [NOT] NULL</c> suffix after an expression. Entered
-    /// with <see cref="ParserContext.Token"/> on the <c>IS</c> keyword;
-    /// consumes <c>IS</c>, optional <c>NOT</c>, and the required <c>NULL</c>.
-    /// Leaves the token on the next un-consumed token (typically a boolean
-    /// combinator, comma, or end-of-input).
+    /// Parses an <c>IS</c> suffix after an expression — either <c>IS [NOT] NULL</c>
+    /// (returns <see cref="IsNullExpression"/>) or <c>IS [NOT] DISTINCT FROM rhs</c>
+    /// (returns <see cref="DistinctFromExpression"/>, SQL Server 2022+ NULL-safe
+    /// equality). Entered with <see cref="ParserContext.Token"/> on the <c>IS</c>
+    /// keyword; consumes <c>IS</c>, optional <c>NOT</c>, then dispatches by the
+    /// next token. Leaves the token on the next un-consumed token.
     /// </summary>
-    private static IsNullExpression ParseIsNullSuffix(Expression left, ParserContext context)
+    private static BooleanExpression ParseIsSuffix(Expression left, ParserContext context)
     {
         var negated = false;
         var next = context.GetNextRequired();
@@ -300,10 +301,19 @@ private static IsNullExpression ParseIsNullSuffix(Expression left, ParserContext
             negated = true;
             next = context.GetNextRequired();
         }
-        if (next is not ReservedKeyword { Keyword: Keyword.Null })
-            throw SimulatedSqlException.SyntaxErrorNear(context);
-        context.MoveNextOptional();
-        return new IsNullExpression(left, negated);
+        switch (next)
+        {
+            case ReservedKeyword { Keyword: Keyword.Null }:
+                context.MoveNextOptional();
+                return new IsNullExpression(left, negated);
+            case ReservedKeyword { Keyword: Keyword.Distinct }:
+                if (context.GetNextRequired() is not ReservedKeyword { Keyword: Keyword.From })
+                    throw SimulatedSqlException.SyntaxErrorNear(context);
+                context.MoveNextRequired();
+                return new DistinctFromExpression(left, Expression.Parse(context), negated);
+            default:
+                throw SimulatedSqlException.SyntaxErrorNear(context);
+        }
     }
 
     /// <summary>
@@ -472,6 +482,41 @@ private sealed class IsNullExpression(Expression source, bool negated) : Boolean
         internal override void VisitOperandExpressions(Action<Expression> visitor) => visitor(source);
     }
 
+    /// <summary>
+    /// <c>expr IS [NOT] DISTINCT FROM rhs</c> — SQL Server 2022 NULL-safe
+    /// comparison. Like <see cref="IsNullExpression"/>, never returns UNKNOWN:
+    /// <c>both NULL → not distinct</c>, <c>exactly one NULL → distinct</c>,
+    /// <c>both non-null → distinct iff unequal</c>. Type promotion follows the
+    /// regular comparison path via <see cref="CompareValuesPromoted"/>; a
+    /// genuinely uncoercible operand pair (e.g. <c>'hello' is distinct from 5</c>)
+    /// still surfaces the underlying Msg 245 / Msg 402 from the comparator,
+    /// matching real SQL Server's behavior.
+    /// </summary>
+    private sealed class DistinctFromExpression(Expression left, Expression right, bool negated) : BooleanExpression
+    {
+        public override bool? Run(RuntimeContext runtime)
+        {
+            var l = left.Run(runtime);
+            var r = right.Run(runtime);
+            var distinct = (l.IsNull, r.IsNull) switch
+            {
+                (true, true) => false,
+                (true, false) or (false, true) => true,
+                _ => CompareValuesPromoted(l, r, "not equal to", static (a, b) => !a.Equals(b)) == true,
+            };
+            return distinct ^ negated;
+        }
+
+        internal override string DebugDisplay() =>
+            $"{left.DebugDisplay()} IS {(negated ? "NOT " : "")}DISTINCT FROM {right.DebugDisplay()}";
+
+        internal override void VisitOperandExpressions(Action<Expression> visitor)
+        {
+            visitor(left);
+            visitor(right);
+        }
+    }
+
     /// <summary>
     /// <c>expr [NOT] IN (v1, v2, ...)</c>: equivalent to a chain of
     /// promote-and-equal comparisons OR-combined (or AND-of-not for

docs/claude/query.md

@@ -1,7 +1,8 @@
 # Query semantics — set ops, CASE, pagination, aggregates, windows
 
 ## Boolean / set ops / projection / CASE
-- Boolean combinators (WHERE / MERGE-ON / CHECK): `AND` / `OR` / `NOT`, parens, `IS [NOT] NULL`, `[NOT] IN (literal,...)`, `[NOT] IN (SELECT ...)`, `EXISTS (SELECT ...)`, `expr <op> {ANY|SOME|ALL} (SELECT col FROM ...)` quantified comparison, `value [NOT] BETWEEN lower AND upper`. Tri-valued.
+- Boolean combinators (WHERE / MERGE-ON / CHECK): `AND` / `OR` / `NOT`, parens, `IS [NOT] NULL`, `IS [NOT] DISTINCT FROM` (SQL Server 2022 NULL-safe equality — never UNKNOWN), `[NOT] IN (literal,...)`, `[NOT] IN (SELECT ...)`, `EXISTS (SELECT ...)`, `expr <op> {ANY|SOME|ALL} (SELECT col FROM ...)` quantified comparison, `value [NOT] BETWEEN lower AND upper`. Tri-valued except for the two `IS`-family forms (always definitive).
+- `IS [NOT] DISTINCT FROM` (`BooleanExpression.DistinctFromExpression`): two NULLs are *not* distinct (match), exactly one NULL *is* distinct (no match), two non-NULLs distinct iff unequal under the regular promote-and-compare. Type-mismatch operand pairs still surface the underlying Msg 245 / Msg 402 — the NULL-safety lives in the per-side null check, the value-side coerces normally. Reachable in any boolean context (WHERE / HAVING / ON / CASE-WHEN / CHECK); bare SELECT-list use raises Msg 156 in real SQL Server because `IS` isn't a value operator.
 - `[NOT] BETWEEN` desugars to `value >= lower AND value <= upper` (inclusive on both ends, probe-confirmed). Reversed bounds (low > high) collapse to a definite false; NULL in any operand position propagates through three-valued AND. `value` is evaluated once per row by `BetweenExpression.Run` (the desugaring is per-row semantics, not duplicated evaluation). BETWEEN binds tighter than the surrounding AND/OR, so `value between a and b and other` parses as `(value between a and b) AND (other)`; bounds may be arbitrary value expressions (Expression.Parse stops at the trailing AND keyword).
 - Quantified comparison (`Parser/BooleanExpression.cs` — `QuantifiedComparisonExpression`): all six operators (`=`, `<>`, `<`, `<=`, `>`, `>=`) plus T-SQL synonyms (`!=` → `<>`, `!<` → `>=`, `!>` → `<=`) fold at parse time into a `ComparisonOp` enum. `SOME` is a pure alias of `ANY`. Inner SELECT must project exactly one column (Msg 116, shared factory with IN-subquery). **Predicate-only**: probe-confirmed (2026-05-13) that real SQL Server raises Msg 102 when the form appears in a SELECT-list expression slot — the simulator inherits the same restriction because parsing lives in `BooleanExpression.ParseComparison`, reachable only from the boolean-atom path. Empty inner: `ALL` is vacuously true, `ANY` vacuously false (LHS NULL irrelevant — the inner is consumed first). Non-empty inner runs three-valued fold: any comparison evaluating to `true` short-circuits `ANY` to `true`; any `false` short-circuits `ALL` to `false`; otherwise `null`-tainted comparisons turn the overall result UNKNOWN, fall-through is `false` for `ANY` / `true` for `ALL`. `<op> ANY` cannot be negated directly (`NOT <op> ANY` isn't grammar — apps must flip the operator: `NOT (x > ALL y)` ≡ `x <= ANY y`).
 - Set ops (UNION / UNION ALL / INTERSECT / EXCEPT): standard precedence (INTERSECT > UNION/EXCEPT). **NULLs are equal during set-op dedup/matching** (opposite of `=`'s tri-state). Per-branch ORDER BY in non-final branch → Msg 156. Top-level ORDER BY references first-branch column names only.