Seek-narrow single-table UPDATE / DELETE target scans through the shared per-Heap seek cache (Selection.SeekMutationTarget, reusing the query path's equality/range candidate cores) instead of full-scanning.

RyanLamansky · RyanLamansky · commit c98b8f8f9d50 · 2026-05-29T18:21:40.000-05:00
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -107,7 +107,7 @@ The `*.Tests` and `*.Tests.EFCore` suites are the authoritative behavior contrac
 
 ### Constraints
 - `CHECK`: inline single-column and table-level forms; Msg 547 per row on definitely-false predicate. Inline column-level CHECK predicates may only reference their owning column — peer references raise **Msg 8141** at CREATE TABLE (probe-confirmed verbatim wording). The walker is structural via `Expression.VisitColumnReferences` + `BooleanExpression.VisitOperandExpressions`; coverage is currently limited to common container subclasses (`Reference`, `Parenthesized`, `TwoSidedExpression`, `Cast`, `Length`) — peer refs buried in less-common containers (`DATEPART`, `SUBSTRING`, nested `CASE`, etc.) silently escape the CREATE-TABLE check and surface at INSERT instead. Table-level CHECK has no peer restriction.
-- `PRIMARY KEY` / `UNIQUE` / secondary `CREATE INDEX`: linear scan (O(N) per insert); no B-tree. Reads get **incrementally-maintained** per-`Heap` seek acceleration (no per-mutation warm-up), identical across keys and non-clustered indexes (built from heap-row bytes keyed by the index's ordinals): equality / IN on the longest leading prefix, range (`>`/`<`/`BETWEEN`) on a leading key column, ORDER BY elimination — single or multi-column leading-prefix sort (all NOT NULL, all one direction), including an equality-prefix continued by the order columns (`WHERE a = @x ORDER BY b`) — and keyset (seek-method) pagination (`WHERE a > @x OR (a = @x AND b > @y) ORDER BY a, b` seeks past the cursor). See [`indexes.md`](docs/claude/indexes.md) for the journal mechanics, decline rules, and the residual-WHERE correctness invariant.
+- `PRIMARY KEY` / `UNIQUE` / secondary `CREATE INDEX`: linear scan (O(N) per insert); no B-tree. Reads get **incrementally-maintained** per-`Heap` seek acceleration (no per-mutation warm-up), identical across keys and non-clustered indexes (built from heap-row bytes keyed by the index's ordinals): equality / IN on the longest leading prefix, range (`>`/`<`/`BETWEEN`) on a leading key column, ORDER BY elimination — single or multi-column leading-prefix sort (all NOT NULL, all one direction), including an equality-prefix continued by the order columns (`WHERE a = @x ORDER BY b`) — and keyset (seek-method) pagination (`WHERE a > @x OR (a = @x AND b > @y) ORDER BY a, b` seeks past the cursor). The same equality / range narrowing accelerates **single-table `UPDATE` / `DELETE` target scans** (`Selection.SeekMutationTarget`; the mutation loop's full-predicate re-check is the residual filter, and it X-locks only the rows it commits so the lock footprint is unchanged) — `MERGE` still full-scans (its `ON` correlates target to source, so it needs loop inversion). See [`indexes.md`](docs/claude/indexes.md) for the journal mechanics, decline rules, and the residual-WHERE correctness invariant.
 - `FOREIGN KEY`: inline / table-level / named forms; all four referential actions on `ON DELETE` / `ON UPDATE`; enforced at INSERT / UPDATE / DELETE / MERGE; full `sys.foreign_keys` / `sys.foreign_key_columns`. Enforcement **seeks the shared `HeapSeekCache`** (the same per-`Heap` index the query path uses): child-insert parent-existence probes the parent's PK/UNIQUE; parent-delete/update cascades seek the child's FK columns — both verifying candidates against live bytes (no residual WHERE), with a full-scan fallback only for non-stored key columns. Referential-action, cascade-cycle, PK/UNIQUE-target, and NULL-skip rules + Msg numbers in [`foreign-keys.md`](docs/claude/foreign-keys.md).
 
 ### Transactions
diff --git a/SqlServerSimulator.Tests.Internal/IndexSeekTests.cs b/SqlServerSimulator.Tests.Internal/IndexSeekTests.cs
@@ -1613,4 +1613,105 @@ insert ch values (10, 1), (11, 1), (12, 2), (13, 3)
         Exec(c, "delete from p where id = 1");
         AreEqual("12,13", Seq(ReadRows(c, "select id from ch order by id")));
     }
+
+    // ---- UPDATE / DELETE target scans ride the same per-Heap seek cache
+    // (Selection.SeekMutationTarget). A single-table UPDATE / DELETE does no
+    // query-path seek of its own, so any CacheBuild / CacheReplay during one is
+    // the mutation target seek; a full scan touches the cache not at all. The
+    // mutation loop re-runs the full WHERE per row, so the seek only narrows. ----
+
+    private static List<string> ExecTraced(SimulatedDbConnection c, string sql)
+    {
+        IndexSeekDiagnostics.Sink = [];
+        try
+        {
+            Exec(c, sql);
+            return IndexSeekDiagnostics.Sink;
+        }
+        finally
+        {
+            IndexSeekDiagnostics.Sink = null;
+        }
+    }
+
+    private static SimulatedDbConnection FreshT()
+    {
+        var c = new Simulation().CreateDbConnection();
+        c.Open();
+        Exec(c, TableT);
+        return c;
+    }
+
+    [TestMethod]
+    public void UpdateByPrimaryKey_SeeksTarget()
+    {
+        var c = FreshT();
+        Contains("CacheBuild", ExecTraced(c, "update t set val = 999 where id = 2"));
+        AreEqual(999, Convert.ToInt32(ReadVal(c, "select val from t where id = 2")));
+        AreEqual("5,500", Seq(ReadRows(c, "select val from t where id <> 2 order by id")));
+    }
+
+    [TestMethod]
+    public void DeleteByPrimaryKey_SeeksTarget()
+    {
+        var c = FreshT();
+        Contains("CacheBuild", ExecTraced(c, "delete from t where id = 2"));
+        AreEqual("1,3", Seq(ReadRows(c, "select id from t order by id")));
+    }
+
+    [TestMethod]
+    public void DeleteByRange_RangeSeeksTarget()
+    {
+        var c = FreshT();
+        Contains("CacheBuild", ExecTraced(c, "delete from t where id >= 2"));
+        AreEqual("1", Seq(ReadRows(c, "select id from t order by id")));
+    }
+
+    [TestMethod]
+    public void DeleteByInList_SeeksTarget()
+    {
+        var c = FreshT();
+        Contains("CacheBuild", ExecTraced(c, "delete from t where id in (1, 3)"));
+        AreEqual("2", Seq(ReadRows(c, "select id from t order by id")));
+    }
+
+    [TestMethod]
+    public void UpdateOnUnindexedColumn_FullScans()
+    {
+        var c = FreshT();
+        // val carries no key / index, so nothing seekable — the mutation keeps
+        // its full scan and never touches the seek cache.
+        DoesNotContain("CacheBuild", ExecTraced(c, "update t set val = 0 where val = 50"));
+        AreEqual(0, Convert.ToInt32(ReadVal(c, "select val from t where id = 2")));
+    }
+
+    [TestMethod]
+    public void UpdateSeek_ResidualWhereStillExcludes()
+    {
+        var c = FreshT();
+        // id = 2 seeks the single row, but the residual val > 1000 conjunct
+        // (re-checked in the mutation loop) excludes it: zero rows updated.
+        Exec(c, "update t set val = 7 where id = 2 and val > 1000");
+        AreEqual(50, Convert.ToInt32(ReadVal(c, "select val from t where id = 2")));
+    }
+
+    [TestMethod]
+    public void UpdateSeek_ReplaysDelta_NoWarmup()
+    {
+        var c = FreshT();
+        Exec(c, "update t set val = val where id = 1"); // warms the seek cache
+        Exec(c, "insert t values (4, 40)");             // moves the mutation generation
+        var trace = ExecTraced(c, "update t set val = 111 where id = 4");
+        Contains("CacheReplay", trace);
+        DoesNotContain("CacheBuild", trace);
+        AreEqual(111, Convert.ToInt32(ReadVal(c, "select val from t where id = 4")));
+    }
+
+    [TestMethod]
+    public void DeleteSeek_NoMatch_LeavesTableIntact()
+    {
+        var c = FreshT();
+        Exec(c, "delete from t where id = 99");
+        AreEqual("1,2,3", Seq(ReadRows(c, "select id from t order by id")));
+    }
 }
diff --git a/SqlServerSimulator/Parser/Selection.Execution.IndexSeek.cs b/SqlServerSimulator/Parser/Selection.Execution.IndexSeek.cs
@@ -155,7 +155,32 @@ private static bool TrySeekByRange(
         bool allowCorrelatedColumnValue,
         out IEnumerable<byte[]> seekRows)
     {
-        seekRows = [];
+        if (!TryComputeRangeCandidates(source, table, batch, outerResolver, conjuncts, allowCorrelatedColumnValue, out var candidates))
+        {
+            seekRows = [];
+            return false;
+        }
+
+        seekRows = snapshotXid is { } sx
+            ? MaterializeSnapshotCandidates(table, batch, sx, candidates)
+            : MaterializeWithLockChecks(table, batch, plan, candidates);
+        return true;
+    }
+
+    // Address-only core of the single-column leading range seek, shared by the
+    // query path (TrySeekByRange) and the mutation path. Returns true with the
+    // in-range (page, slot) candidates (possibly empty — a NULL bound seeks to
+    // nothing), or false when no range bound lands on a leading key column.
+    private static bool TryComputeRangeCandidates(
+        FromSource source,
+        HeapTable table,
+        BatchContext batch,
+        Func<MultiPartName, SqlValue>? outerResolver,
+        List<BooleanExpression> conjuncts,
+        bool allowCorrelatedColumnValue,
+        out List<(int Page, int Slot)> candidates)
+    {
+        candidates = [];
 
         var bounds = new Dictionary<int, RangeBoundExprs>();
         foreach (var conjunct in conjuncts)
@@ -221,13 +246,9 @@ private static bool TrySeekByRange(
             upperValue = upperValue.CoerceTo(common);
 
         var cache = HeapSeekCache.For(table.Heap);
-        var candidates = cache.RangeScan(
+        candidates = cache.RangeScan(
             table.Heap, source.StoredSchema, source.LobStore, ordinal, common,
             hasLower, lowerValue, bound.LowerInclusive, hasUpper, upperValue, bound.UpperInclusive);
-
-        seekRows = snapshotXid is { } sx
-            ? MaterializeSnapshotCandidates(table, batch, sx, candidates)
-            : MaterializeWithLockChecks(table, batch, plan, candidates);
         return true;
     }
 
@@ -1053,7 +1074,35 @@ private static bool TrySeekByLongestPrefix(
         out IEnumerable<byte[]> seekRows,
         out int width)
     {
-        seekRows = [];
+        if (!TryComputeEqualityCandidates(source, table, batch, outerResolver, equalities, out var candidates, out width))
+        {
+            seekRows = [];
+            return false;
+        }
+
+        seekRows = snapshotXid is { } sx
+            ? MaterializeSnapshotCandidates(table, batch, sx, candidates)
+            : MaterializeWithLockChecks(table, batch, plan, candidates);
+        return true;
+    }
+
+    // Computes the seek-narrowed (page, slot) candidate addresses for the longest
+    // usable equality prefix across this table's keys / indexes — the address-only
+    // core shared by the query path (TrySeekByLongestPrefix wraps it in the lock /
+    // snapshot read materializer) and the mutation path (which materializes them as
+    // live rewrite targets). Probe components evaluate at most once per column; see
+    // TrySeekByLongestPrefix's doc for the prefix / cartesian rules. Returns false
+    // (prefix length 0) when no column carries a usable probe.
+    private static bool TryComputeEqualityCandidates(
+        FromSource source,
+        HeapTable table,
+        BatchContext batch,
+        Func<MultiPartName, SqlValue>? outerResolver,
+        Dictionary<int, Expression[]> equalities,
+        out List<(int Page, int Slot)> candidates,
+        out int width)
+    {
+        candidates = [];
         width = 0;
 
         var resolved = new Dictionary<int, (SqlType Common, SqlValue[] Probes)?>();
@@ -1105,17 +1154,13 @@ private static bool TrySeekByLongestPrefix(
         }
 
         var cache = HeapSeekCache.For(table.Heap);
-        var candidates = new List<(int Page, int Slot)>();
         foreach (var tuple in CartesianProduct(probesPerColumn))
         {
             var bucket = cache.Seek(table.Heap, source.StoredSchema, source.LobStore, prefix, commons, new SqlValueKey(tuple));
             if (bucket.Count != 0)
                 candidates.AddRange(bucket);
         }
 
-        seekRows = snapshotXid is { } sx
-            ? MaterializeSnapshotCandidates(table, batch, sx, candidates)
-            : MaterializeWithLockChecks(table, batch, plan, candidates);
         width = bestLen;
         return true;
 
@@ -1265,6 +1310,94 @@ private static IEnumerable<byte[]> MaterializeWithLockChecks(
         }
     }
 
+    /// <summary>
+    /// Seek-narrowed live <c>(page, slot, bytes)</c> rows for a single-table
+    /// UPDATE / DELETE target whose WHERE carries an indexable equality (literal /
+    /// variable / arithmetic value — never a correlated column, since a single-
+    /// table mutation has no outer row), IN-list / OR family, composite leading
+    /// prefix, or single leading-column range. Returns <c>null</c> when nothing
+    /// seekable is present, so the caller keeps its full
+    /// <see cref="Heap.EnumerateRowsWithAddress"/> scan. The result is an exact
+    /// match set for the seekable conjuncts only; the mutation loop re-runs the
+    /// full predicate per row (its residual filter), so a partly-seekable WHERE
+    /// stays correct and a stale cache entry is discarded there — the same
+    /// residual-filter contract as the query path. No lock / snapshot wrapper: the
+    /// mutation reads live addresses (exactly what the scan it replaces does) and
+    /// X-locks only the rows it commits, so narrowing the candidate set never
+    /// changes the lock footprint.
+    /// </summary>
+    internal static IEnumerable<(int Page, int Slot, byte[] Bytes)>? SeekMutationTarget(
+        HeapTable table, BooleanExpression where, BatchContext batch)
+    {
+        var source = BuildBaseTableSeekSource(table);
+
+        var conjuncts = new List<BooleanExpression>();
+        where.CollectConjuncts(conjuncts);
+
+        var equalities = new Dictionary<int, Expression[]>();
+        foreach (var conjunct in conjuncts)
+        {
+            if (conjunct.TryGetEqualityOperands(out var left, out var right))
+            {
+                _ = TryRecordColumnEquality(source, left, right, equalities, allowCorrelatedColumnValue: false)
+                    || TryRecordColumnEquality(source, right, left, equalities, allowCorrelatedColumnValue: false);
+                continue;
+            }
+            if (conjunct.TryGetEqualityFamily(out var family))
+                _ = TryRecordEqualityFamily(source, family, equalities, allowCorrelatedColumnValue: false);
+        }
+
+        if (equalities.Count != 0
+            && TryComputeEqualityCandidates(source, table, batch, outerResolver: null, equalities, out var eqCandidates, out _))
+        {
+            return MaterializeMutationCandidates(table, eqCandidates);
+        }
+
+        if (TryComputeRangeCandidates(source, table, batch, outerResolver: null, conjuncts, allowCorrelatedColumnValue: false, out var rangeCandidates))
+            return MaterializeMutationCandidates(table, rangeCandidates);
+
+        // No seekable equality or range conjunct: caller keeps its full scan.
+        return null;
+    }
+
+    // Minimal single-source view of a base table for the mutation seek: real
+    // column names + storage metadata so TryIdentifyIndexableColumn resolves the
+    // WHERE's column references, qualified by the table's own name (the only
+    // qualifier a single-table UPDATE / DELETE WHERE can use). The Rows stream is
+    // unused — the seek reads addresses straight from the heap's cache.
+    private static FromSource BuildBaseTableSeekSource(HeapTable table)
+    {
+        var columnNames = new string[table.Columns.Length];
+        for (var i = 0; i < columnNames.Length; i++)
+            columnNames[i] = table.Columns[i].Name;
+        return new FromSource(
+            qualifier: table.Name,
+            columnNames: columnNames,
+            columns: table.Columns,
+            storedSchema: table.StoredColumns,
+            storageOrdinals: table.StorageOrdinals,
+            lobStore: table.Heap,
+            rows: []);
+    }
+
+    // The mutation analogue of MaterializeWithLockChecks: dedup + tombstone-skip
+    // over the seeked candidates, yielding each live row's address and bytes. No
+    // per-row lock touch (the mutation path X-locks only what it commits) and no
+    // live-key verify (the mutation loop's full-predicate re-check is the residual
+    // filter, exactly as the query path leans on its residual WHERE).
+    private static IEnumerable<(int Page, int Slot, byte[] Bytes)> MaterializeMutationCandidates(
+        HeapTable table, IReadOnlyList<(int Page, int Slot)> candidates)
+    {
+        var seen = new HashSet<(int, int)>();
+        foreach (var (page, slot) in candidates)
+        {
+            if (!seen.Add((page, slot)) || table.Heap.IsSlotTombstoned(page, slot))
+                continue;
+            if (table.Heap.ReadSlotBytes(page, slot) is { } bytes)
+                yield return (page, slot, bytes);
+        }
+    }
+
     // Snapshot / RCSI candidate materialization. Mirrors the snapshot branch of
     // BatchContext.WrapWithRowConflictChecks, but over the seeked candidate set
     // rather than the whole heap. Two sources, deduplicated by slot:
diff --git a/SqlServerSimulator/Simulation/Simulation.Delete.cs b/SqlServerSimulator/Simulation/Simulation.Delete.cs
@@ -121,7 +121,15 @@ private static SimulatedStatementOutcome ExecuteDeleteAgainstTable(
         var needsFullForTriggers = hasDeleteTriggers || insteadOfActive;
         var needsFullForHistory = table.SystemVersioning is not null;
         var needsFullForFk = table.IncomingForeignKeys.Count > 0;
-        foreach (var (pageIndex, slotIndex, rowBytes) in table.Heap.EnumerateRowsWithAddress())
+
+        // Seek the target when WHERE carries an indexable equality / range
+        // (positioned DELETE leaves where null, so it keeps the full scan — the
+        // cursor already fixed one row). The loop re-runs WHERE below, so the
+        // seek only narrows the rows considered.
+        var rowSource = where is not null
+            ? Selection.SeekMutationTarget(table, where, context.Batch) ?? table.Heap.EnumerateRowsWithAddress()
+            : table.Heap.EnumerateRowsWithAddress();
+        foreach (var (pageIndex, slotIndex, rowBytes) in rowSource)
         {
             // Positioned DELETE (WHERE CURRENT OF): only the cursor's row.
             if (positionedCursor is not null && !CursorRowMatches(positionedCursor, (pageIndex, slotIndex)))
diff --git a/SqlServerSimulator/Simulation/Simulation.Update.cs b/SqlServerSimulator/Simulation/Simulation.Update.cs
@@ -206,7 +206,13 @@ private static SimulatedStatementOutcome ExecuteUpdateAgainstTable(
         var storedColumns = table.StoredColumns;
         var lobStore = table.Heap;
 
-        foreach (var (pageIndex, slotIndex, rowBytes) in table.Heap.EnumerateRowsWithAddress())
+        // Seek the target when WHERE carries an indexable equality / range
+        // (positioned UPDATE leaves where null, so it keeps the full scan). The
+        // loop re-runs WHERE below, so the seek only narrows the rows considered.
+        var rowSource = where is not null
+            ? Selection.SeekMutationTarget(table, where, context.Batch) ?? table.Heap.EnumerateRowsWithAddress()
+            : table.Heap.EnumerateRowsWithAddress();
+        foreach (var (pageIndex, slotIndex, rowBytes) in rowSource)
         {
             // Positioned UPDATE (WHERE CURRENT OF): target only the row the
             // cursor is sitting on, identified by its stable heap address.
diff --git a/docs/claude/dml.md b/docs/claude/dml.md
diff --git a/docs/claude/indexes.md b/docs/claude/indexes.md
