MERGE WHEN MATCHED expansion: full branch-family parser + executor — WHEN MATCHED [AND <cond>] THEN UPDATE SET … / DELETE, WHEN NOT MATCHED [BY TARGET] [AND <cond>] THEN INSERT … VALUES …, WHEN NOT MATCHED BY SOURCE [AND <cond>] THEN UPDATE / DELETE. Source lifted from VALUES-only to any Selection (SELECT / set-op chain), gated by a parse-time materializer that picks VALUES-tuple-eval vs Selection.Execute. Single-pass executor: target × source scan collects per-target match lists, dispatches first-AND-satisfied WHEN clause; queued inserts/updates/deletes apply atomically (PK/UNIQUE validation runs on the union via sentinel-address EnforceKeyConstraintsForUpdate so a constraint violation rolls back the entire MERGE). $action pseudo-column tokenized as a single $action UnquotedString (replaces the default $-as-money + action-as-name split), recognized in OUTPUT through any AS-alias wrapper via IsMergeActionRef drilling past NamedExpression; projects uppercase 'INSERT' / 'UPDATE' / 'DELETE' as nvarchar(10). New MergeOutputProjection handles the 4-way INSERTED / DELETED / source-alias / $action surface that the existing OutputProjection (INSERT-shape) and MutationOutputProjection (UPDATE/DELETE-shape) don't compose. Multi-match guard: target row matched by >1 source row + chosen action UPDATE → Msg 8672; DELETE is forgiving (probe-confirmed). Action-kind rejection: Msg 10711 for INSERT in MATCHED / NOT MATCHED BY SOURCE; Msg 10710 for UPDATE/DELETE in NOT MATCHED BY TARGET; Msg 10714 for multiple NOT MATCHED BY TARGET clauses; Msg 5324 for AND-after-no-AND in MATCHED / NOT MATCHED BY SOURCE; Msg 10713 for missing trailing ;. Triggers fire INSERT → UPDATE → DELETE, each kind once with combined affected rows (probe-confirmed). New contextual keywords (Source, Target) for the BY SOURCE / BY TARGET grammar. 22 new MergeTests cover every branch combination, all error paths, source-subquery + set-op shapes, $action across branches, multi-match guard (UPDATE raises, DELETE doesn't), AND first-match-wins, trigger order, and atomic rollback. CLAUDE.md "Not modeled" rewritten (MERGE WHEN MATCHED branches + $action + source subqueries shipped; CTE-headed sources / MERGE-into-view / $action-into-@t deferred); docs/claude/dml.md expanded with the MERGE deep-dive (grammar table, per-phase execution model, $action + trigger + EF reach notes).

Author: RyanLamansky

CLAUDE.md

@@ -116,10 +116,9 @@ Three entry points share one per-connection undo log: implicit (statement-level
 - **Temp-table CREATE/DROP participates in the log** via `TempTableCreation` / `TempTableRemoval` `UndoEntry` subtypes (rollback removes from / restores into the connection's `TempTables` dict). Regular CREATE/DROP TABLE is NOT logged — see the corresponding quirk.
 - No isolation: uncommitted writes immediately visible to all readers (single-Simulation, single-thread-at-a-time).
 
-### MERGE / OUTPUT (EF SaveChanges shape only)
+### MERGE / OUTPUT
 - `INSERT ... OUTPUT INSERTED.<col>` (single-row).
-- `MERGE INTO target USING (VALUES ...) AS alias (cols) ON predicate WHEN NOT MATCHED THEN INSERT ... [OUTPUT ...]` (multi-row batch).
-- `WHEN MATCHED` parses but throws `NotSupportedException` if its predicate ever evaluates true.
+- `MERGE INTO target [AS alias] USING (<source>) AS alias [(cols)] ON predicate <when-clause>+ [OUTPUT …]` — source can be `VALUES`, `SELECT`, or a set-op chain. WHEN clauses: `WHEN MATCHED [AND <cond>] THEN UPDATE SET …` / `DELETE`, `WHEN NOT MATCHED [BY TARGET] [AND <cond>] THEN INSERT (…) VALUES (…)`, `WHEN NOT MATCHED BY SOURCE [AND <cond>] THEN UPDATE SET …` / `DELETE`. Multiple AND-conditioned clauses per family allowed; unconditional must be last (Msg 5324). `WHEN NOT MATCHED [BY TARGET]` admits at most one clause (Msg 10714). Trailing `;` required (Msg 10713). `$action` in OUTPUT projects uppercase `INSERT` / `UPDATE` / `DELETE` per affected row. Multi-match: a target row matched by more than one source row raises Msg 8672 only when the chosen action is UPDATE (DELETE is forgiving — multiple matches collapse to one delete). Triggers fire INSERT → UPDATE → DELETE, each kind once with its combined affected rows. See [`docs/claude/dml.md`](docs/claude/dml.md).
 
 ### EF Core adapter coverage
 `UseSqlServerSimulator(...)` covers seven SqlParameter-downcast pairs: `DateOnly→date`, `DateTime→date`, `DateTime→smalldatetime`, `TimeOnly→time(N)`, `TimeSpan→time(N)`, `decimal→money`, `decimal→smallmoney`. Without the adapter those mappings throw at SaveChanges. MAX-string family flows through plain `UseSqlServer`.
@@ -165,7 +164,7 @@ Per-feature deep-dives live under `docs/claude/`. Each entry below is a trigger:
 - `CONVERT` / `TRY_CONVERT` style codes other than `0` / `120` / `121`.
 - `LEN(ntext)` raising Msg 8116; legacy `READTEXT` / `WRITETEXT` / `UPDATETEXT`.
 - `OUTPUT DELETED.*` / `INSERTED.*` star expansion. (`OUTPUT INTO <target>` ships for both `@t` and regular tables — see Table variables below.)
-- MERGE source subqueries; MERGE target column refs in `ON`; `WHEN MATCHED` UPDATE/DELETE branches; `$action`.
+- MERGE source as a CTE-headed SELECT (`USING (WITH cte AS … SELECT …)`) — Selection.Parse's CTE entry doesn't reach the USING-clause grammar; wrap the CTE inside a regular SELECT instead. MERGE inside a CTE body, multi-statement MERGE WHEN-clause bodies, and `MERGE INTO <view>` (real SQL Server's updatable-view MERGE) are also deferred.
 - `PRIMARY KEY` / `UNIQUE` on a computed column (`NotSupportedException`).
 - Heap allocation tracking (flat page list, no IAM/PFS).
 - **Table-variable named constraints / foreign keys** — `DECLARE @t TABLE (...)` shares its column-list parser with CREATE TABLE (see `docs/claude/table-variables.md`); column features (IDENTITY / UNIQUE / inline + table-level CHECK / computed columns / rowversion) all ship, alongside per-statement-atomic mutations and `OUTPUT … INTO <target>` for both `@t` and regular tables. Named constraints (`CONSTRAINT pk1 PRIMARY KEY`) and `FOREIGN KEY` raise Msg 102 (matches probe — real SQL Server's grammar disallows both shapes inside `DECLARE @t TABLE`). Multi-variable DECLARE with a table variable (`DECLARE @t1 TABLE (...), @t2 TABLE (...)`) and mixed scalar+table DECLARE also raise Msg 102/156. `SET IDENTITY_INSERT @t ON` likewise raises Msg 102 (probe-confirmed: there's no way to force a specific value into a table-variable identity column).

SqlServerSimulator.Tests/MergeTests.cs

@@ -206,16 +206,6 @@ public void Merge_ExplicitRowVersionInColumnList_RaisesMsg273()
             when not matched then insert (id, rv) values (s.id, s.rv);
             """, 273);
 
-    // Simulator parses WHEN MATCHED but throws if the ON predicate ever steers a source row there.
-    [TestMethod]
-    public void Merge_WhenMatchedFires_RaisesNotSupported()
-        => _ = Assert.Throws<NotSupportedException>(() => new Simulation().ExecuteNonQuery("""
-            create table t ( id int, v int );
-            merge t using (values (1, 99)) as i (id, v) on 1 = 1
-            when matched then update set v = i.v
-            when not matched then insert (id, v) values (i.id, i.v);
-            """));
-
     [TestMethod]
     public void Merge_FirstSourceTuple_DeterminesAliasSchema()
     {

SqlServerSimulator.Tests/OutputClauseTests.cs

@@ -105,7 +105,7 @@ insert t values (5, 500)
         _ = Throws<DbException>(() =>
             _ = connection.CreateCommand(
                 "merge into t using (values (1, 10), (5, 50), (3, 30)) as src(id, val) " +
-                "on t.id = src.id " +
+                "on 1 = 0 " +
                 "when not matched then insert (id, val) values (src.id, src.val);").ExecuteNonQuery());
 
         // The PK collision on (5, 50) should roll back the (1, 10) insert too.

SqlServerSimulator.Tests/StatementAtomicityTests.cs

@@ -72,6 +72,65 @@ internal static SimulatedSqlException NoCorrespondingBeginRollback() =>
     internal static SimulatedSqlException CteRequiresPrecedingSemicolon() =>
         new("Incorrect syntax near the keyword 'with'. If this statement is a common table expression, an xmlnamespaces clause or a change tracking context clause, the previous statement must be terminated with a semicolon.", 319, 15, 1);
 
+    /// <summary>
+    /// Mimics SQL Server error 5324: a <c>MERGE</c> statement had a
+    /// <c>WHEN MATCHED</c> (or <c>WHEN NOT MATCHED BY SOURCE</c>) clause
+    /// carrying a search condition appear <em>after</em> a clause of the
+    /// same family with no search condition. Real SQL Server requires the
+    /// unconditional fallback to be last in the family. Probe-confirmed
+    /// against SQL Server 2025 (2026-05-13): Class 16, State 1, exact
+    /// wording verbatim. The <paramref name="clauseFamily"/> is either
+    /// <c>"WHEN MATCHED"</c> or <c>"WHEN NOT MATCHED BY SOURCE"</c> —
+    /// <c>WHEN NOT MATCHED [BY TARGET]</c> has at most one clause total
+    /// (Msg 10714) and so doesn't share this path.
+    /// </summary>
+    internal static SimulatedSqlException MergeUnconditionalMustBeLast(string clauseFamily) =>
+        new($"In a MERGE statement, a '{clauseFamily}' clause with a search condition cannot appear after a '{clauseFamily}' clause with no search condition.", 5324, 16, 1);
+
+    /// <summary>
+    /// Mimics SQL Server error 8672: a <c>MERGE</c> statement's
+    /// <c>WHEN MATCHED ... THEN UPDATE</c> branch attempted to update the
+    /// same target row from multiple source rows. SQL Server's <c>DELETE</c>
+    /// matched branch is forgiving (multiple matches collapse to one delete),
+    /// but <c>UPDATE</c> raises this. Probe-confirmed against SQL Server 2025
+    /// (2026-05-13): Class 16, State 1, exact wording verbatim.
+    /// </summary>
+    internal static SimulatedSqlException MergeMultiMatch() =>
+        new("The MERGE statement attempted to UPDATE or DELETE the same row more than once. This happens when a target row matches more than one source row. A MERGE statement cannot UPDATE/DELETE the same row of the target table multiple times. Refine the ON clause to ensure a target row matches at most one source row, or use the GROUP BY clause to group the source rows.", 8672, 16, 1);
+
+    /// <summary>
+    /// Mimics SQL Server error 10710: a <c>MERGE</c> statement specified an
+    /// <c>UPDATE</c> or <c>DELETE</c> action in a <c>WHEN NOT MATCHED</c> /
+    /// <c>WHEN NOT MATCHED BY TARGET</c> clause where only <c>INSERT</c> is
+    /// legal. Probe-confirmed against SQL Server 2025 (2026-05-13): Class 15,
+    /// State 1, exact wording verbatim.
+    /// </summary>
+    internal static SimulatedSqlException MergeUpdateNotAllowedInNotMatched() =>
+        new("An action of type 'UPDATE' is not allowed in the 'WHEN NOT MATCHED' clause of a MERGE statement.", 10710, 15, 1);
+
+    /// <summary>
+    /// Mimics SQL Server error 10711: a <c>MERGE</c> statement specified an
+    /// <c>INSERT</c> action in a <c>WHEN MATCHED</c> or <c>WHEN NOT MATCHED
+    /// BY SOURCE</c> clause where only <c>UPDATE</c> / <c>DELETE</c> is
+    /// legal. Probe-confirmed against SQL Server 2025 (2026-05-13): Class
+    /// 15, State 1, exact wording verbatim. The <paramref name="clauseType"/>
+    /// is either <c>"WHEN MATCHED"</c> or <c>"WHEN NOT MATCHED BY SOURCE"</c>.
+    /// </summary>
+    internal static SimulatedSqlException MergeInsertNotAllowedInClause(string clauseType) =>
+        new($"An action of type 'INSERT' is not allowed in the '{clauseType}' clause of a MERGE statement.", 10711, 15, 1);
+
+    /// <summary>
+    /// Mimics SQL Server error 10714: a <c>MERGE</c> statement had more than
+    /// one <c>WHEN NOT MATCHED [BY TARGET]</c> clause. Real SQL Server allows
+    /// at most one INSERT branch (unlike <c>WHEN MATCHED</c> and <c>WHEN
+    /// NOT MATCHED BY SOURCE</c>, both of which can have multiple
+    /// AND-conditioned clauses). Probe-confirmed against SQL Server 2025
+    /// (2026-05-13): Class 15, State 1, exact wording verbatim — note the
+    /// idiosyncratic <c>"a 'INSERT' clause"</c> phrasing.
+    /// </summary>
+    internal static SimulatedSqlException MergeMultipleNotMatchedClauses() =>
+        new("An action of type 'WHEN NOT MATCHED' cannot appear more than once in a 'INSERT' clause of a MERGE statement.", 10714, 15, 1);
+
     /// <summary>
     /// Mimics SQL Server error 10713: a <c>MERGE</c> statement was not
     /// followed by a <c>;</c>. Probe-confirmed verbatim text (note the

SqlServerSimulator/Errors/SimulatedSqlException.SyntaxErrors.cs

@@ -66,7 +66,9 @@ enum ContextualKeyword
     Schemabinding,
     Scoped,
     Sequence,
+    Target,
     SetError,
+    Source,
     Start,
     Throw,
     Time,

SqlServerSimulator/Parser/ContextualKeyword.cs

@@ -47,6 +47,7 @@ static class Tokenizer
             '/' => ParseForwardSlashOrComment(command, ref index),
             '[' => ParseBracketDelimitedString(command, ref index),
             '+' or '*' or '%' or '(' or ')' or ',' or '.' or ';' or '=' or '&' or '|' or '^' or '>' or '<' or '!' => new Operator(command, index++),
+            '$' when IsDollarAction(command, index) => ParseDollarAction(command, ref index),
             '$' or '¢' or '£' or '¥' or '฿' or (>= '₠' and <= '₱') => ParseCurrencyLiteral(command, ref index),
             var c => throw SimulatedSqlException.SyntaxErrorNear(c) // Might throw on valid-but-unsupported syntax.
         };
@@ -280,6 +281,43 @@ private static Literal ParseHexLiteral(string command, ref int index)
     private static bool IsHexDigit(char c) =>
         c is (>= '0' and <= '9') or (>= 'a' and <= 'f') or (>= 'A' and <= 'F');
 
+    /// <summary>
+    /// Returns true when the cursor sits on a <c>$action</c> pseudo-column
+    /// — only recognized in MERGE's OUTPUT clause, but tokenized here so
+    /// it surfaces as a single <see cref="UnquotedString"/> with value
+    /// <c>"$action"</c> rather than tokenizing into a money-literal
+    /// <c>$</c> followed by an unrelated identifier. Word-boundary
+    /// terminated (rejects <c>$action_</c>).
+    /// </summary>
+    private static bool IsDollarAction(string command, int index)
+    {
+        if (index + 6 >= command.Length)
+            return false;
+        var body = command.AsSpan(index + 1, 6);
+        if (!body.Equals("action", StringComparison.OrdinalIgnoreCase))
+            return false;
+        if (index + 7 < command.Length)
+        {
+            var next = command[index + 7];
+            if (char.IsLetterOrDigit(next) || next == '_')
+                return false;
+        }
+        return true;
+    }
+
+    /// <summary>
+    /// Emits the <c>$action</c> pseudo-column as a single
+    /// <see cref="UnquotedString"/>. The MERGE OUTPUT parser detects it
+    /// by string comparison and synthesizes a <c>MergeActionReference</c>
+    /// expression.
+    /// </summary>
+    private static UnquotedString ParseDollarAction(string command, ref int index)
+    {
+        var start = index;
+        index += 7;
+        return (UnquotedString)UnquotedString.CheckReserved(command, start, 7);
+    }
+
     /// <summary>
     /// Parses a money literal: a single currency symbol followed by an
     /// optional sign, optional digits, and an optional fractional part.