Route foreign-key enforcement through the seek cache: extract the per-Heap index out of Selection into a shared HeapSeekCache (with SqlValueKey promoted to a top-level type), and seek parent-existence and cascade child-lookups instead of scanning.

Author: RyanLamansky

CLAUDE.md

@@ -108,7 +108,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.
-- `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`. Referential-action, cascade-cycle, PK/UNIQUE-target, and NULL-skip rules + Msg numbers in [`foreign-keys.md`](docs/claude/foreign-keys.md).
+- `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
 Three entry points share one per-connection undo log: implicit (statement-level atomicity), SqlClient API (`BeginTransaction()`/`Commit()`/`Rollback()`), SQL-text (`BEGIN`/`COMMIT`/`ROLLBACK`/`SAVE TRANSACTION`).

SqlServerSimulator.Tests.Internal/IndexSeekTests.cs

@@ -1517,4 +1517,100 @@ public void RangeCorrectUnderManyMutations_MatchesIndependentBaseline()
         actual.Sort();
         AreEqual(string.Join(",", expected), string.Join(",", actual));
     }
+
+    // ---- foreign-key enforcement rides the same per-Heap seek cache (shared via
+    // HeapSeekCache.For). An INSERT … VALUES does no query-path seek, so any
+    // CacheBuild / CacheReplay during a child insert is the parent-existence
+    // seek; a no-WHERE parent delete does no query-path seek either, isolating
+    // the cascade's child-lookup seek. ----
+
+    [TestMethod]
+    public void ForeignKeyChildInsert_SeeksParentExistence()
+    {
+        var c = new Simulation().CreateDbConnection();
+        c.Open();
+        Exec(c, """
+            create table p (id int not null primary key);
+            create table ch (id int not null primary key, pid int not null references p(id));
+            insert p values (1), (2), (3)
+            """);
+        IndexSeekDiagnostics.Sink = [];
+        try
+        {
+            Exec(c, "insert ch values (10, 2)");
+            // INSERT VALUES has no SELECT/WHERE to seek, so this is the FK
+            // parent-existence seek building the parent's id index.
+            Contains("CacheBuild", IndexSeekDiagnostics.Sink);
+        }
+        finally
+        {
+            IndexSeekDiagnostics.Sink = null;
+        }
+    }
+
+    [TestMethod]
+    public void ForeignKeyChildInsert_ReplaysParentDelta_NoWarmup()
+    {
+        var c = new Simulation().CreateDbConnection();
+        c.Open();
+        Exec(c, """
+            create table p (id int not null primary key);
+            create table ch (id int not null primary key, pid int not null references p(id));
+            insert p values (1), (2)
+            """);
+        Exec(c, "insert ch values (10, 1)"); // builds the parent seek cache
+        IndexSeekDiagnostics.Sink = [];
+        try
+        {
+            Exec(c, "insert p values (3)");      // moves the parent's mutation generation
+            Exec(c, "insert ch values (11, 3)"); // parent-existence seek replays the delta
+            Contains("CacheReplay", IndexSeekDiagnostics.Sink);
+            DoesNotContain("CacheBuild", IndexSeekDiagnostics.Sink);
+        }
+        finally
+        {
+            IndexSeekDiagnostics.Sink = null;
+        }
+    }
+
+    [TestMethod]
+    public void ForeignKeyCascadeDelete_SeeksChildren()
+    {
+        var c = new Simulation().CreateDbConnection();
+        c.Open();
+        Exec(c, """
+            create table p (id int not null primary key);
+            create table ch (id int not null primary key, pid int not null references p(id) on delete cascade);
+            insert p values (1), (2);
+            insert ch values (10, 1), (11, 1), (12, 2)
+            """);
+        IndexSeekDiagnostics.Sink = [];
+        try
+        {
+            // No WHERE → the parent delete itself doesn't seek, so the cache
+            // activity is the cascade seeking children by their pid.
+            Exec(c, "delete from p");
+            Contains("CacheBuild", IndexSeekDiagnostics.Sink);
+        }
+        finally
+        {
+            IndexSeekDiagnostics.Sink = null;
+        }
+        AreEqual(0, Convert.ToInt32(ReadVal(c, "select count(*) from ch")));
+    }
+
+    [TestMethod]
+    public void ForeignKeyCascadeDelete_SelectiveParent_CorrectChildrenRemain()
+    {
+        var c = new Simulation().CreateDbConnection();
+        c.Open();
+        Exec(c, """
+            create table p (id int not null primary key);
+            create table ch (id int not null primary key, pid int not null references p(id) on delete cascade);
+            insert p values (1), (2), (3);
+            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")));
+    }
 }