Fixed BCP datetime decode truncation (0.3–0.9s value error). Mimicked datetime SqlClient rounding. Nested-loop join optimized as hash join, protected against regression with new observability mechanics visible from internal tests.

Author: RyanLamansky

CLAUDE.md

@@ -103,9 +103,7 @@ Six scopes, one home each. **Add new state to whichever class matches its true s
 The `*.Tests` and `*.Tests.EFCore` suites are the authoritative behavior contract. Notes below cover only probe-confirmed quirks, deviations from SQL Server, and non-obvious implementation rules. Per-feature deep-dives live under `docs/claude/` (see [Feature reference](#feature-reference) for the trigger-phrased index); short cross-cutting sections stay inline below.
 
 ### JOINs / APPLY
-INNER / bare JOIN / LEFT [OUTER] / RIGHT [OUTER] / FULL [OUTER] / CROSS / CROSS APPLY / OUTER APPLY. Multi-table chains compose left-to-right. ON-predicate UNKNOWN excludes. APPLY = lateral form (right side re-executed per outer row, no ON clause). Comma-separated FROM (ANSI-89 syntax — `FROM a, b WHERE a.id = b.id`) parses as a sequence of explicit-join chains spliced with `JoinKind.Cross` joins; each comma starts a fresh chain via the same `ParseExplicitJoinChain` helper the JOIN-keyword loop calls, so any explicit JOINs *within* a chain bind before the cross-splice.
-
-`JoinDriver` is a fold over `joins[]`: leftmost rowset → wrap with each join's operator → final enumerator (`Selection.Execution.Joins.cs`). INNER / CROSS / LEFT / CROSS APPLY / OUTER APPLY stream one upstream tuple at a time; RIGHT / FULL materialize `sources[level].Rows` into a list and track a `matched[]` bitmap across the entire upstream iteration so unmatched right rows can be emitted (with all prior slots NULL-filled) after upstream is exhausted. **RIGHT / FULL with a derived-table right side** materialize the lateral plan once via the enclosing-scope `outerResolver` (not the joined-tuple resolver), so non-correlated and outer-correlated derived tables work; lateral correlation to the left side is rejected because the derived-table parse doesn't wire the left-source snapshot resolver — left-side references raise Msg 207 ("Invalid column name") at runtime when `Reference.Run` hits the null outer resolver. Real SQL Server raises Msg 4104 at bind time for the same shape; different code, same end state. EF Core 10's LINQ `LeftJoin` / `RightJoin` operators translate to LEFT / RIGHT JOIN respectively and route through this pipeline; .NET 10 LINQ doesn't expose a `FullJoin` operator, so FULL OUTER JOIN is reachable only via raw SQL.
+INNER / bare JOIN / LEFT [OUTER] / RIGHT [OUTER] / FULL [OUTER] / CROSS / CROSS APPLY / OUTER APPLY, multi-table chains (compose left-to-right), and ANSI-89 comma-FROM. ON-predicate UNKNOWN excludes. Equi-joins (`a.col = b.col`) take an O(L+R) hash path; non-equi / CROSS / APPLY / lateral-right fall back to streaming nested loops. EF Core's LINQ `LeftJoin` / `RightJoin` route through this pipeline (no LINQ `FullJoin`, so FULL is raw-SQL-only). See [`docs/claude/joins.md`](docs/claude/joins.md).
 
 ### Subqueries
 `EXISTS` / `NOT EXISTS` (multi-column inner allowed); `expr [NOT] IN (SELECT ...)` (single inner column, Msg 116); scalar `(SELECT col FROM ...)` (single column, single-row Msg 512 per outer row, empty → typed NULL); `expr <op> {ANY|SOME|ALL} (SELECT col FROM ...)` quantified comparison with all six operators (`=` `<>` `<` `<=` `>` `>=`) plus T-SQL synonyms `!=` `!<` `!>`, predicate-only (SELECT-list usage raises Msg 102 at the operator, matching real SQL Server's grammar restriction); SOME aliases ANY. Empty inner: ALL vacuously true, ANY vacuously false (both independent of LHS NULL); non-empty inner with NULL on either side of any per-row compare taints to UNKNOWN per three-valued logic. All forms work correlated and non-correlated, arbitrary nesting depth. `UNION` / `UNION ALL` / `INTERSECT` / `EXCEPT` are legal inside every subquery context — derived tables in FROM, EXISTS, IN, ANY/ALL inners, scalar `(SELECT ...)`, CTE bodies — because subquery parsers route through `Selection.Parse` → `ParseQueryExpression`, which already drives the set-op chain. EF Core 7+'s TPC inheritance emit shape (UNION ALL of selects from each concrete table wrapped in a derived table) ships end-to-end through this path.
@@ -139,7 +137,7 @@ Session-scoped T-SQL cursors: `DECLARE <name> [INSENSITIVE][SCROLL] CURSOR [LOCA
 Comparison (Msg 402), ORDER BY/DISTINCT (Msg 306), and aggregates (Msg 8117 from MAX/MIN) all enforced.
 
 ### `SimulatedDbDataReader`
-Full `DbDataReader` contract. Typed accessors read `SqlValue` directly via the cursor's indexer and unwrap via `As*` (no boxing); NULL on a typed accessor → `SqlNullValueException` matching SqlClient. `GetDateTime` covers Date/DateTime/SmallDateTime/DateTime2 (Date surfaces at midnight, `Kind=Unspecified`); `GetDecimal` covers Decimal/Numeric/Money/SmallMoney; `GetFieldValue<T>` short-circuits EF's `DateOnly`-over-`Date` and `TimeOnly`-over-`Time`. `GetOrdinal(name)` is two-pass linear scan (case-sensitive then case-insensitive — SqlClient's documented precedence). `HasRows` is a sticky bit. `GetChar(int)` always raises `InvalidCastException` (matches SqlClient).
+Full `DbDataReader` contract. Typed accessors read `SqlValue` directly via the cursor's indexer and unwrap via `As*` (no boxing); NULL on a typed accessor → `SqlNullValueException` matching SqlClient. `GetDateTime` covers Date/DateTime/SmallDateTime/DateTime2 (Date surfaces at midnight, `Kind=Unspecified`). A **`datetime` value rounds to whole milliseconds at the ADO.NET boundary** (`DateTimeSqlType.RoundToClientMilliseconds`, applied in `GetDateTime` and `SqlValue.ToObject` — the latter also covers `GetValue` / `GetFieldValue` / output-parameter writeback) to match SqlClient's `.000`/`.003`/`.007` materialization; the value stays at full 1/300-second resolution for engine-internal comparison / arithmetic / re-encode, so only the client-facing surface rounds. `GetDecimal` covers Decimal/Numeric/Money/SmallMoney; `GetFieldValue<T>` short-circuits EF's `DateOnly`-over-`Date` and `TimeOnly`-over-`Time`. `GetOrdinal(name)` is two-pass linear scan (case-sensitive then case-insensitive — SqlClient's documented precedence). `HasRows` is a sticky bit. `GetChar(int)` always raises `InvalidCastException` (matches SqlClient).
 
 ### Feature reference
 
@@ -149,6 +147,7 @@ Per-feature deep-dives live under `docs/claude/`. Each entry below is a trigger:
 - **`SqlType.Promote` / `PromoteForArithmetic` / decimal precision-scale / int↔string promotion** → [`arithmetic.md`](docs/claude/arithmetic.md).
 - **`Cast` / coercion error paths** (CAST/CONVERT narrow targets, TRY_CAST/TRY_CONVERT swallow set, PARSE/TRY_PARSE culture-aware parsing) → [`casting.md`](docs/claude/casting.md).
 - **`Selection`, aggregates, window functions, set ops, CASE, OFFSET/FETCH** → [`query.md`](docs/claude/query.md).
+- **JOIN / APPLY execution** (`JoinDriver`, equi-join hash fast path + `SqlValueKey` keying, nested-loop fallback, RIGHT/FULL materialization + derived-table-right, comma-FROM splicing, `JoinDiagnostics` strategy guard) → [`joins.md`](docs/claude/joins.md).
 - **UPDATE / DELETE / INSERT…SELECT / SELECT…INTO / rowversion (incl. `@@DBTS` / `MIN_ACTIVE_ROWVERSION`) / identity helpers (`@@IDENTITY` / `SCOPE_IDENTITY` / `IDENT_CURRENT` / `IDENT_INCR` / `IDENT_SEED`) / `@@ROWCOUNT` / `ROWCOUNT_BIG` / OUTPUT / MERGE** → [`dml.md`](docs/claude/dml.md).
 - **Variables, control flow (IF/WHILE/BREAK/CONTINUE/RETURN), TRY/CATCH+THROW+ERROR_*, `@@ERROR` / `@@TRANCOUNT` / `XACT_STATE`, PRINT, WAITFOR** → [`control-flow.md`](docs/claude/control-flow.md).
 - **Cursors (`DECLARE … CURSOR` / `OPEN` / `FETCH` / `CLOSE` / `DEALLOCATE`, STATIC / KEYSET / DYNAMIC sensitivity, scroll fetches, `@@FETCH_STATUS` / `@@CURSOR_ROWS` / `CURSOR_STATUS`, `WHERE CURRENT OF`)** → [`cursors.md`](docs/claude/cursors.md).

SqlServerSimulator.Tests.EFCore/EFCoreDateTime.cs

@@ -161,7 +161,9 @@ public void Where_FiltersByDateTimeOffsetEquality_CrossOffset()
     [TestMethod]
     public void Insert_LegacyDateTime_RoundTripsAtTickGranularity()
     {
-        // Legacy datetime stores 1/300-second ticks; .997 input → tick 299 = 9_966_666 100-ns ticks past second.
+        // Legacy datetime stores 1/300-second ticks (.997 input → tick 299, the
+        // raw .9966666); SqlClient rounds that to whole ms on read, so EF surfaces
+        // .997 — a lossless round-trip for a millisecond-precision input.
         using var context = new TestDbContext(TestDbContext.CreateEventsSimulation());
 
         var started = new DateTime(2026, 5, 4, 13, 45, 30, 997);
@@ -174,7 +176,7 @@ public void Insert_LegacyDateTime_RoundTripsAtTickGranularity()
         Assert.AreEqual(started.Hour, read.Value.Hour);
         Assert.AreEqual(started.Minute, read.Value.Minute);
         Assert.AreEqual(started.Second, read.Value.Second);
-        Assert.AreEqual(9_966_666, read.Value.Ticks % TimeSpan.TicksPerSecond);
+        Assert.AreEqual(9_970_000, read.Value.Ticks % TimeSpan.TicksPerSecond);
     }
 
     [TestMethod]

SqlServerSimulator.Tests.Internal/JoinStrategyTests.cs

@@ -0,0 +1,74 @@
+using SqlServerSimulator.Parser;
+using static Microsoft.VisualStudio.TestTools.UnitTesting.Assert;
+
+namespace SqlServerSimulator;
+
+/// <summary>
+/// Perf-regression guard for the join executor's strategy choice
+/// (<c>Selection.Execution.Joins.cs</c>): an equi-join <c>a.col = b.col</c> must
+/// take the O(L+R) hash path, while a non-equi / CROSS predicate must fall back
+/// to the nested loop. The correctness suite passes under either strategy, so a
+/// silent revert to the O(L×R) loop would otherwise go unnoticed until a real
+/// workload hung. Reads the opt-in <see cref="JoinDiagnostics"/> trace (recorded
+/// at the single dispatch point) rather than timing, so the guard is exact and
+/// non-flaky.
+/// </summary>
+[TestClass]
+public sealed class JoinStrategyTests
+{
+    private static List<string> CaptureStrategies(string joinQuery)
+    {
+        var sim = new Simulation();
+        var connection = sim.CreateDbConnection();
+        connection.Open();
+        using (var setup = connection.CreateCommand())
+        {
+            setup.CommandText = """
+                create table a (id int, name varchar(20));
+                create table b (id int, a_id int);
+                insert a values (1, 'one'), (2, 'two');
+                insert b values (10, 1), (11, 2)
+                """;
+            _ = setup.ExecuteNonQuery();
+        }
+
+        JoinDiagnostics.Sink = [];
+        try
+        {
+            using var command = connection.CreateCommand();
+            command.CommandText = joinQuery;
+            using var reader = command.ExecuteReader();
+            while (reader.Read()) { }
+            return JoinDiagnostics.Sink;
+        }
+        finally
+        {
+            JoinDiagnostics.Sink = null;
+        }
+    }
+
+    [TestMethod]
+    public void EquiJoin_TakesHashPath()
+        => Contains("Inner:HashMatch(keys=1,residual=0)",
+            CaptureStrategies("select a.id from a join b on a.id = b.a_id"));
+
+    [TestMethod]
+    public void EquiJoinWithExtraPredicate_HashesKeyKeepsRestAsResidual()
+        => Contains("Inner:HashMatch(keys=1,residual=1)",
+            CaptureStrategies("select a.id from a join b on a.id = b.a_id and b.id > 10"));
+
+    [TestMethod]
+    public void LeftJoin_TakesHashPath()
+        => Contains("Left:HashMatch(keys=1,residual=0)",
+            CaptureStrategies("select a.id from a left join b on a.id = b.a_id"));
+
+    [TestMethod]
+    public void NonEquiJoin_FallsBackToNestedLoops()
+        => Contains("Inner:NestedLoops",
+            CaptureStrategies("select a.id from a join b on a.id <> b.a_id"));
+
+    [TestMethod]
+    public void CrossJoin_UsesNestedLoops()
+        => Contains("Cross:NestedLoops",
+            CaptureStrategies("select a.id from a cross join b"));
+}

SqlServerSimulator.Tests/Bacpac/BacpacBuilder.cs

@@ -800,7 +800,8 @@ private static void WriteDateTime(Span<byte> buf, DateTime dt)
         var epoch = new DateTime(1900, 1, 1, 0, 0, 0, DateTimeKind.Unspecified);
         var diff = dt - epoch;
         var days = diff.Days;
-        var ticks300 = (uint)((diff.Ticks - (TimeSpan.TicksPerDay * days)) / (TimeSpan.TicksPerSecond / 300L));
+        var timeTicks = diff.Ticks - (TimeSpan.TicksPerDay * days);
+        var ticks300 = (uint)(((timeTicks * 300) + (TimeSpan.TicksPerSecond / 2)) / TimeSpan.TicksPerSecond);
         BinaryPrimitives.WriteInt32LittleEndian(buf[..4], days);
         BinaryPrimitives.WriteUInt32LittleEndian(buf[4..8], ticks300);
     }

SqlServerSimulator.Tests/Bacpac/BacpacLoaderTests.cs

@@ -308,6 +308,24 @@ public void BcpDataRoundTrips_AcrossCommonTypes()
         IsFalse(reader.Read());
     }
 
+    [TestMethod]
+    public void DateTimeColumn_LateDaySubSecond_RoundTripsThroughBcp()
+    {
+        // datetime decode converts 1/300-second ticks back to .NET ticks. Doing
+        // the divide before the multiply (TicksPerSecond / 300 = 33333, truncating
+        // the real 33333.333) under-counts every tick — an error that compounds
+        // with the tick-count-since-midnight, reaching ~0.4-0.9s late in the day.
+        // 23:47:16.030 sits on the 1/300 grid (30ms = 9 ticks) so it must survive
+        // exactly; the old truncation shifted it back to ~23:47:15.6.
+        var stamp = new DateTime(2024, 11, 8, 23, 47, 16, 30, DateTimeKind.Unspecified);
+        using var bacpac = BacpacBuilder.Create()
+            .Table("dbo", "Stamps", t => t.Column("When", "datetime").Row(stamp))
+            .Build();
+        var sim = new Simulation();
+        sim.ImportBacpac(bacpac, out _);
+        AreEqual(stamp, sim.ExecuteScalar("SELECT [When] FROM Stamps"));
+    }
+
     [TestMethod]
     public void DecimalColumn_RoundTripsThroughBcp_AcrossPrecisionBuckets()
     {

SqlServerSimulator.Tests/CurrentTimeFunctionTests.cs

@@ -208,6 +208,8 @@ private static DateTime RoundToLegacyTick(DateTime utcDt)
             timeUnits = 0;
         }
         var roundedTicks = timeUnits * TimeSpan.TicksPerSecond / 300;
-        return new DateTime(1900, 1, 1).AddDays(dayCount).AddTicks(roundedTicks);
+        // SqlClient rounds the stored 1/300 tick to whole milliseconds on retrieval.
+        var clientTicks = (roundedTicks + (TimeSpan.TicksPerMillisecond / 2)) / TimeSpan.TicksPerMillisecond * TimeSpan.TicksPerMillisecond;
+        return new DateTime(1900, 1, 1).AddDays(dayCount).AddTicks(clientTicks);
     }
 }

SqlServerSimulator.Tests/JoinTests.cs

@@ -504,4 +504,107 @@ public void CommaFrom_LeadingComma_RaisesSyntaxError()
             create table a (id int);
             select * from , a
             """, 102);
+
+    // --- Equi-join hash path edge cases (Selection.Execution.Joins.cs). ---
+    // The `a.col = b.col` fast path replaces the nested loop; these pin the
+    // semantics that differ from a naive hash: NULL keys, type promotion,
+    // composite keys, residual non-equi conjuncts, and collation folding.
+
+    private static Simulation SeededNullKeys()
+    {
+        var sim = new Simulation();
+        _ = sim.ExecuteNonQuery("""
+            create table l (id int, k int);
+            create table r (k int, v int);
+            insert l values (1, 10), (2, null);
+            insert r values (10, 100), (null, 999)
+            """);
+        return sim;
+    }
+
+    /// <summary>
+    /// l.id=2 (NULL k) and r's NULL-k row must not pair — NULL = NULL is UNKNOWN.
+    /// </summary>
+    [TestMethod]
+    public void HashEquiJoin_NullKey_ExcludedFromInnerMatch()
+        => AreEqual(1, SeededNullKeys().ExecuteScalar("select count(*) from l join r on l.k = r.k"));
+
+    [TestMethod]
+    public void HashEquiJoin_NullKey_LeftJoinEmitsNullFilledRight()
+    {
+        var sim = SeededNullKeys();
+        // Both left rows survive; the NULL-key one is NULL-filled, not matched to r's NULL row.
+        AreEqual(2, sim.ExecuteScalar("select count(*) from l left join r on l.k = r.k"));
+        AreEqual(1, sim.ExecuteScalar("select count(*) from l left join r on l.k = r.k where r.v is null"));
+    }
+
+    /// <summary>
+    /// r's NULL-key row never matches, so RIGHT JOIN emits it with left NULL-filled (2 rows total).
+    /// </summary>
+    [TestMethod]
+    public void HashEquiJoin_NullKey_RightJoinEmitsUnmatchedRightRow()
+        => AreEqual(2, SeededNullKeys().ExecuteScalar("select count(*) from l right join r on l.k = r.k"));
+
+    /// <summary>
+    /// bigint = int must hash under the promoted common type, not by raw SqlValue.Type.
+    /// </summary>
+    [TestMethod]
+    public void HashEquiJoin_CrossTypeKey_PromotesAndMatches()
+        => AreEqual(1L, new Simulation().ExecuteScalar("""
+            create table l (k bigint);
+            create table r (k int);
+            insert l values (5);
+            insert r values (5);
+            select count_big(*) from l join r on l.k = r.k
+            """));
+
+    [TestMethod]
+    public void HashEquiJoin_CompositeKey_AllColumnsMustMatch()
+        => AreEqual(1, new Simulation().ExecuteScalar("""
+            create table l (a int, b int);
+            create table r (a int, b int);
+            insert l values (1, 2), (1, 3);
+            insert r values (1, 2), (9, 9);
+            select count(*) from l join r on l.a = r.a and l.b = r.b
+            """));
+
+    /// <summary>
+    /// The `r.v > 150` conjunct isn't an equi-key; it's re-checked per probed candidate.
+    /// </summary>
+    [TestMethod]
+    public void HashEquiJoin_ResidualNonEquiConjunct_FiltersCandidates()
+        => AreEqual(1, new Simulation().ExecuteScalar("""
+            create table l (k int);
+            create table r (k int, v int);
+            insert l values (10);
+            insert r values (10, 100), (10, 200);
+            select count(*) from l join r on l.k = r.k and r.v > 150
+            """));
+
+    /// <summary>
+    /// Default SQL_Latin1_General_CP1_CI_AS is case-insensitive — the hash key
+    /// must fold case (GetHashCode agreeing with collation-aware Equals).
+    /// </summary>
+    [TestMethod]
+    public void HashEquiJoin_StringKey_FoldsCaseUnderDefaultCollation()
+        => AreEqual(1, new Simulation().ExecuteScalar("""
+            create table l (name varchar(20));
+            create table r (name varchar(20));
+            insert l values ('One');
+            insert r values ('one');
+            select count(*) from l join r on l.name = r.name
+            """));
+
+    /// <summary>
+    /// 1 match + 1 unmatched-left + 1 unmatched-right = 3 rows.
+    /// </summary>
+    [TestMethod]
+    public void HashEquiJoin_FullJoin_EmitsUnmatchedFromBothSides()
+        => AreEqual(3, new Simulation().ExecuteScalar("""
+            create table l (k int);
+            create table r (k int);
+            insert l values (1), (2);
+            insert r values (1), (3);
+            select count(*) from l full outer join r on l.k = r.k
+            """));
 }