Cursors gain variables, true scoping, concurrency semantics, and the sp_cursor* API-server-cursor RPC family: DECLARE @c CURSOR / SET-binding shares refcounted cursor objects with position, CURSOR VARYING OUTPUT params survive into the caller, GLOBAL/LOCAL become distinct scopes with LOCAL-first resolution and the scope-aware CURSOR_STATUS matrix, SCROLL_LOCKS holds a U row lock across autocommit until scroll-away/close, OPTIMISTIC positioned DML raises 16947/16934/3621 chain, FOR UPDATE OF enforces Msg 16932 and TYPE_WARNING emits Msg 16956; over TDS, procids 1-9 dispatch to handlers that reuse the engine cursors end-to-end, mirroring the probed wire contract. Trailing ROWSTAT column, metadata-only open, INPUT-only fetch positioning, scrollopt/ccopt downgrade OUT values, rowcount -1 for dynamic, and real's own non-surfacing of optimistic conflicts through sp_cursor.

Author: RyanLamansky

CLAUDE.md

@@ -130,7 +130,7 @@ Per-feature deep-dives live under `docs/claude/`. Each entry below is a trigger:
 - **`PIVOT` / `UNPIVOT`** — PIVOT desugars to grouped conditional aggregation (implicit grouping = inner columns minus FOR + aggregate-arg), UNPIVOT is a NULL-skipping unfold; both attach as a postfix FROM-source wrapper on the derived-table `LateralPlan` seam → [`pivot.md`](docs/claude/pivot.md).
 - **UPDATE / DELETE / INSERT…SELECT / SELECT…INTO / rowversion** (`@@DBTS` / `MIN_ACTIVE_ROWVERSION`) **/ identity helpers** (`@@IDENTITY` / `SCOPE_IDENTITY` / `IDENT_CURRENT`/`_INCR`/`_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).
+- **Cursors** (`DECLARE … CURSOR` / `OPEN` / `FETCH` / `CLOSE` / `DEALLOCATE`, STATIC / KEYSET / DYNAMIC sensitivity, scroll fetches, `@@FETCH_STATUS` / `@@CURSOR_ROWS` / `CURSOR_STATUS`, `WHERE CURRENT OF`; GLOBAL / LOCAL scope + scope-aware resolution, cursor variables (`DECLARE @c CURSOR` / `SET @c = CURSOR …` refcounted, cursor OUTPUT proc params), `FOR UPDATE OF` gating (Msg 16932), SCROLL_LOCKS cursor-scoped U locks + OPTIMISTIC conflict detection (Msg 16947/16934), TYPE_WARNING (Msg 16956)) → [`cursors.md`](docs/claude/cursors.md).
 - **CTE shapes / recursive-CTE error handling** → [`ctes.md`](docs/claude/ctes.md).
 - **JSON** (JSON_VALUE / JSON_QUERY / JSON_MODIFY / JSON_OBJECT / JSON_ARRAY / JSON_OBJECTAGG / JSON_ARRAYAGG / JSON_PATH_EXISTS / ISJSON / OPENJSON) → [`json.md`](docs/claude/json.md).
 - **Name resolution, schema lookup, CREATE / DROP / ALTER SCHEMA TRANSFER, `OBJECT_ID`/`_NAME`/`_SCHEMA_NAME` / `SCHEMA_ID`/`_NAME` / `DB_ID`/`_NAME`, cross-DB reads** → [`schemas.md`](docs/claude/schemas.md).
@@ -164,7 +164,7 @@ Per-feature deep-dives live under `docs/claude/`. Each entry below is a trigger:
 - **New top-level statement parser or dispatch-loop separator rules, double-quoted identifiers / QUOTED_IDENTIFIER** → [`grammar.md`](docs/claude/grammar.md) + [`control-flow.md`](docs/claude/control-flow.md).
 - **BACPAC import** (`Simulation.ImportBacpac` — multi-database via repeated calls, `BacpacImportOptions`, `ModelXmlReader` dispatcher, BCP wire format, `BacpacBuilder` test harness) → [`bacpac-loader.md`](docs/claude/bacpac-loader.md).
 - **Linked servers** (`Simulation.AddRemoteSimulation`, `sp_addlinkedserver` / `sp_dropserver`, four-part FROM routing through the remote's ADO.NET pipeline, `OPENQUERY(server,'query')` ad-hoc pass-through + compile-time schema discovery, `sys.servers`) → [`linked-servers.md`](docs/claude/linked-servers.md).
-- **TDS network endpoint** (`Simulation.ListenAsync` → `SimulatedNetworkListener`; real SqlClient over loopback TCP+TLS; SQLBatch/RPC/TM, no bulk; credential enforcement via the `CREATE LOGIN` registry, Msg 18456 on mismatch; EF via plain `UseSqlServer`; oracles = `*.Tests.SqlClient` + `*.Tests.Smo`, the real-SMO consumer oracle) → [`tds-endpoint.md`](docs/claude/tds-endpoint.md).
+- **TDS network endpoint** (`Simulation.ListenAsync` → `SimulatedNetworkListener`; real SqlClient over loopback TCP+TLS; SQLBatch/RPC/TM, no bulk; `sp_cursor*` API-server-cursor RPC family; credential enforcement via the `CREATE LOGIN` registry, Msg 18456 on mismatch; EF via plain `UseSqlServer`; oracles = `*.Tests.SqlClient` + `*.Tests.Smo`, the real-SMO consumer oracle) → [`tds-endpoint.md`](docs/claude/tds-endpoint.md).
 
 ## Not modeled
 

SqlServerSimulator.Tests.SqlClient/CursorRpcTests.cs

@@ -240,7 +240,7 @@ public void CursorStatus_OpenReturnsOne()
         => AreEqual((short)1, ExecuteScalar<short>(Seed + """
             declare c cursor for select id from t;
             open c;
-            select cursor_status('local', 'c')
+            select cursor_status('global', 'c')
             """));
 
     [TestMethod]
@@ -307,9 +307,13 @@ public void NonUpdatableQuery_ForcedToStaticEvenWhenDynamicRequested()
             select @@cursor_rows
             """));
 
+    /// <summary>
+    /// Cursor variables are modeled — see CursorBreadthTests for the full
+    /// lifecycle. A bare DECLARE registers an unallocated slot.
+    /// </summary>
     [TestMethod]
-    public void CursorVariable_NotSupported()
-        => Throws<NotSupportedException>(() => ExecuteScalar("declare @c cursor"));
+    public void CursorVariable_DeclareRegistersUnallocatedSlot()
+        => AreEqual((short)-2, ExecuteScalar<short>("declare @c cursor; select cursor_status('variable','@c')"));
 
     [TestMethod]
     public void JoinCursor_ForwardLoopOverMultipleSources()

SqlServerSimulator.Tests/CursorBreadthTests.cs

@@ -29,6 +29,28 @@ internal enum CursorSensitivity
 /// forward-only cursor; the rest require a scrollable cursor.</summary>
 internal enum FetchDirection { Next, Prior, First, Last, Absolute, Relative }
 
+/// <summary>
+/// The concurrency-control model of an updatable cursor (the
+/// <c>READ_ONLY</c> / <c>SCROLL_LOCKS</c> / <c>OPTIMISTIC</c> keyword family).
+/// A read-only cursor carries <see cref="Cursor.ReadOnly"/> instead.
+/// </summary>
+internal enum CursorConcurrency
+{
+    /// <summary>Default optimistic-without-detection: positioned DML just
+    /// re-locates the row and rewrites it (the pre-existing behavior).</summary>
+    Default,
+
+    /// <summary><c>SCROLL_LOCKS</c>: a U lock is held on the currently-fetched
+    /// row (cursor-scoped — released when the cursor scrolls off the row,
+    /// closes, or deallocates), and positioned DML upgrades it to X.</summary>
+    ScrollLocks,
+
+    /// <summary><c>OPTIMISTIC</c>: no lock is held; positioned DML re-reads the
+    /// row and raises the optimistic-conflict chain (Msg 16947 / 16934) when it
+    /// was modified out-of-band since the fetch.</summary>
+    Optimistic,
+}
+
 /// <summary>
 /// A session-scoped T-SQL cursor (declared with <c>DECLARE … CURSOR FOR
 /// &lt;select&gt;</c>). Lives in <see cref="SimulatedDbConnection.Cursors"/>.
@@ -44,7 +66,9 @@ internal sealed class Cursor(
     CursorSensitivity sensitivity,
     bool scrollable,
     bool readOnly,
-    HeapTable? baseTable)
+    HeapTable? baseTable,
+    CursorConcurrency concurrency = CursorConcurrency.Default,
+    List<string>? forUpdateColumns = null)
 {
     public readonly string Name = name;
     public readonly Selection Selection = selection;
@@ -55,8 +79,51 @@ internal sealed class Cursor(
     /// <summary>The single base table, non-null for KEYSET / DYNAMIC / positioned DML.</summary>
     public readonly HeapTable? BaseTable = baseTable;
 
+    /// <summary>The concurrency model — <see cref="CursorConcurrency.ScrollLocks"/>
+    /// holds a cursor-scoped U lock on the fetched row, <see cref="CursorConcurrency.Optimistic"/>
+    /// detects out-of-band modification at positioned DML time.</summary>
+    public readonly CursorConcurrency Concurrency = concurrency;
+
+    /// <summary>The <c>FOR UPDATE OF (col, …)</c> column list (surface names),
+    /// or null when the cursor was declared <c>FOR UPDATE</c> without an OF list
+    /// (every column updatable) or without a FOR UPDATE clause. A positioned
+    /// UPDATE of a column absent from a non-null list raises Msg 16932.</summary>
+    public readonly List<string>? ForUpdateColumns = forUpdateColumns;
+
+    /// <summary>
+    /// Reference count of cursor variables (<c>DECLARE @c CURSOR</c>) pointing
+    /// at this object. A named cursor sits at 0; each <c>SET @c = …</c> binding
+    /// increments, each <c>DEALLOCATE @c</c> decrements, and the object is torn
+    /// down only when the count returns to 0 with no name. Matches SQL Server's
+    /// refcounted cursor-variable model (probe-confirmed).
+    /// </summary>
+    public int VariableRefCount;
+
+    /// <summary>True for an unnamed cursor that exists only through cursor
+    /// variables (created by <c>SET @c = CURSOR FOR …</c>); such a cursor is
+    /// destroyed when its last variable reference is deallocated.</summary>
+    public bool IsUnnamed;
+
     public bool IsOpen;
 
+    /// <summary>
+    /// OPTIMISTIC snapshot of the currently-fetched row's full stored bytes,
+    /// captured at each FETCH. Positioned DML compares the live bytes at
+    /// <see cref="CurrentRid"/> against this; any difference (a value change, a
+    /// rowversion bump, or the row's disappearance) is an optimistic conflict.
+    /// A full-row byte compare subsumes both real detection bases — rowversion
+    /// column when present, column checksum otherwise. Null when the cursor
+    /// isn't OPTIMISTIC or isn't on a live row.
+    /// </summary>
+    private byte[]? optimisticSnapshot;
+
+    // SCROLL_LOCKS: cursor-scoped locks held directly (not through the
+    // statement / transaction release lists). The table-IX is held for the
+    // cursor's open lifetime; the row-U follows the current fetch position and
+    // is released when the cursor scrolls off the row, closes, or deallocates.
+    private LockResource? scrollTableLock;
+    private LockResource? scrollRowLock;
+
     /// <summary>
     /// The value <c>CURSOR_STATUS</c> reports for this (existing) cursor:
     /// <c>-1</c> closed, <c>1</c> open DYNAMIC or open with ≥1 row, <c>0</c>
@@ -119,22 +186,115 @@ public void Open(BatchContext batch)
 
         this.CurrentRid = null;
         this.IsOpen = true;
+
+        // SCROLL_LOCKS: take table-IX for the cursor's open lifetime (the
+        // per-row U locks ride the fetch position). Held cursor-scoped, so it
+        // outlives individual statements and any autocommit boundary — matching
+        // real SQL Server, where scroll locks persist while the cursor is
+        // positioned regardless of an enclosing transaction.
+        if (this.Concurrency == CursorConcurrency.ScrollLocks && this.BaseTable is { } table2)
+        {
+            var connection = batch.Connection;
+            connection.Simulation.LockManager.Acquire(table2.TableDataLock, LockMode.IntentExclusive, connection, connection.LockTimeoutMillis);
+            this.scrollTableLock = table2.TableDataLock;
+        }
     }
 
     /// <summary>CLOSE the cursor: release the materialized state and reset
     /// position. The cursor stays declared (re-OPEN-able). Raises Msg 16917
     /// (state 1) if not open.</summary>
-    public void Close()
+    public void Close(BatchContext batch)
     {
         if (!this.IsOpen)
             throw SimulatedSqlException.CursorNotOpen(state: 1);
+        this.ReleaseScrollLocks(batch.Connection);
         this.staticRows = null;
         this.keysetIdentities = null;
         this.dynamicLast = null;
         this.CurrentRid = null;
+        this.optimisticSnapshot = null;
         this.IsOpen = false;
     }
 
+    /// <summary>
+    /// Releases both cursor-scoped SCROLL_LOCKS locks (the position-following
+    /// row-U and the open-lifetime table-IX). Called on CLOSE, on the last
+    /// DEALLOCATE, and at connection dispose. No-op for non-SCROLL_LOCKS
+    /// cursors.
+    /// </summary>
+    internal void ReleaseScrollLocks(SimulatedDbConnection connection)
+    {
+        var lockManager = connection.Simulation.LockManager;
+        if (this.scrollRowLock is { } row)
+        {
+            lockManager.Release(row, LockMode.Update, connection);
+            this.scrollRowLock = null;
+        }
+        if (this.scrollTableLock is { } tbl)
+        {
+            lockManager.Release(tbl, LockMode.IntentExclusive, connection);
+            this.scrollTableLock = null;
+        }
+    }
+
+    /// <summary>
+    /// Moves the SCROLL_LOCKS row-U lock onto the freshly-fetched row: releases
+    /// the row we scrolled off (if any) and acquires U on
+    /// <see cref="CurrentRid"/>. A concurrent writer of the current row then
+    /// blocks (U conflicts with the writer's X); scrolling away frees it.
+    /// </summary>
+    private void MoveScrollLock(BatchContext batch)
+    {
+        if (this.BaseTable is not { } table)
+            return;
+        var connection = batch.Connection;
+        var lockManager = connection.Simulation.LockManager;
+        if (this.scrollRowLock is { } prior)
+        {
+            lockManager.Release(prior, LockMode.Update, connection);
+            this.scrollRowLock = null;
+        }
+        if (this.CurrentRid is { } rid)
+        {
+            var resource = table.GetOrCreateRowLock(rid.Page, rid.Slot);
+            lockManager.Acquire(resource, LockMode.Update, connection, connection.LockTimeoutMillis);
+            this.scrollRowLock = resource;
+        }
+    }
+
+    /// <summary>
+    /// For an <see cref="CursorConcurrency.Optimistic"/> cursor, raises the
+    /// optimistic-conflict chain (Msg 16947 / 16934) when the current row's
+    /// live bytes differ from the snapshot captured at FETCH — a value change,
+    /// a rowversion bump, or the row's deletion out-of-band. No-op for other
+    /// concurrency modes. Called at positioned UPDATE / DELETE time.
+    /// </summary>
+    internal void CheckOptimisticConflict()
+    {
+        if (this.Concurrency != CursorConcurrency.Optimistic || this.BaseTable is not { } table)
+            return;
+        var current = this.CurrentRid is { } rid ? table.Heap.ReadSlotBytes(rid.Page, rid.Slot) : null;
+        if (current is null || this.optimisticSnapshot is null || !current.AsSpan().SequenceEqual(this.optimisticSnapshot))
+            throw SimulatedSqlException.CursorOptimisticConflict();
+    }
+
+    /// <summary>
+    /// True when <paramref name="column"/> may be updated through a positioned
+    /// <c>WHERE CURRENT OF</c>: always true unless the cursor carries a
+    /// <c>FOR UPDATE OF (…)</c> column list that omits it (Msg 16932).
+    /// </summary>
+    internal bool IsColumnUpdatable(string column, BatchContext batch)
+    {
+        if (this.ForUpdateColumns is null)
+            return true;
+        foreach (var allowed in this.ForUpdateColumns)
+        {
+            if (batch.CurrentDatabase.Collation.Equals(allowed, column))
+                return true;
+        }
+        return false;
+    }
+
     /// <summary>
     /// FETCH one row in the requested direction. Returns the SQL Server
     /// <c>@@FETCH_STATUS</c> (0 success, -1 past end / no row, -2 keyset member
@@ -146,12 +306,25 @@ public void Close()
         if (!this.IsOpen)
             throw SimulatedSqlException.CursorNotOpen(state: 2);
         this.EnsureDirectionAllowed(direction);
-        return this.Sensitivity switch
+        var result = this.Sensitivity switch
         {
             CursorSensitivity.Static => this.FetchStatic(direction, offset),
             CursorSensitivity.Keyset => this.FetchKeyset(batch, direction, offset),
             _ => this.FetchDynamic(batch, direction),
         };
+
+        // OPTIMISTIC: snapshot the landed row's live bytes so a later positioned
+        // UPDATE / DELETE can detect out-of-band modification. SCROLL_LOCKS:
+        // move the cursor-scoped U lock onto the newly-fetched row (releasing
+        // the row we scrolled off), so a concurrent writer of the current row
+        // blocks. Both are no-ops when the fetch didn't land on a live row.
+        this.optimisticSnapshot = this.Concurrency == CursorConcurrency.Optimistic && this.CurrentRid is { } orid
+            ? this.BaseTable?.Heap.ReadSlotBytes(orid.Page, orid.Slot)
+            : null;
+        if (this.Concurrency == CursorConcurrency.ScrollLocks)
+            this.MoveScrollLock(batch);
+
+        return result;
     }
 
     /// <summary>

SqlServerSimulator.Tests/CursorTests.cs

@@ -67,4 +67,40 @@ internal static SimulatedSqlException CursorIsReadOnly() =>
     /// </summary>
     internal static SimulatedSqlException CursorNoCurrentRow() =>
         new("There are no rows in the current fetch buffer.", 16931, 16, 1);
+
+    /// <summary>
+    /// Msg 16932: a positioned <c>UPDATE … WHERE CURRENT OF</c> assigns a
+    /// column that isn't in the cursor's <c>FOR UPDATE OF (…)</c> list.
+    /// Probe-confirmed verbatim against SQL Server 2025 (state 1).
+    /// </summary>
+    internal static SimulatedSqlException CursorColumnNotInForUpdateList() =>
+        new("The cursor has a FOR UPDATE list and the requested column to be updated is not in this list.", 16932, 16, 1);
+
+    /// <summary>
+    /// A positioned <c>UPDATE</c> / <c>DELETE WHERE CURRENT OF</c> on an
+    /// <c>OPTIMISTIC</c> cursor found the current row modified (or deleted)
+    /// out-of-band since it was fetched. Real SQL Server surfaces a three-error
+    /// chain (probe-confirmed against SQL Server 2025): the terminating
+    /// <b>Msg 16947</b> (class 16, state 1, <c>"No rows were updated or
+    /// deleted."</c>) — the number a SqlClient consumer catches — followed by
+    /// the descriptive class-0 <b>Msg 16934</b> and the standard <b>Msg
+    /// 3621</b> statement-terminated companion. The full chain is reproduced so
+    /// <c>SqlException.Errors</c> and <c>.Message</c> match.
+    /// </summary>
+    internal static SimulatedSqlException CursorOptimisticConflict() =>
+        new(
+            "No rows were updated or deleted.\nOptimistic concurrency check failed. The row was modified outside of this cursor.\nThe statement has been terminated.",
+            new SimulatedError(@class: 16, lineNumber: 0, "No rows were updated or deleted.", 16947, procedure: "", server: "", source: "Core Microsoft SqlClient Data Provider", state: 1),
+            new SimulatedError(@class: 0, lineNumber: 0, "Optimistic concurrency check failed. The row was modified outside of this cursor.", 16934, procedure: "", server: "", source: "Core Microsoft SqlClient Data Provider", state: 1),
+            new SimulatedError(@class: 0, lineNumber: 0, "The statement has been terminated.", 3621, procedure: "", server: "", source: "Core Microsoft SqlClient Data Provider", state: 0));
+
+    /// <summary>
+    /// Msg 16950: a <c>FETCH</c> (or other cursor operation) named a cursor
+    /// <em>variable</em> that has no cursor allocated to it — declared with
+    /// <c>DECLARE @c CURSOR</c> but never <c>SET</c>, or referencing a
+    /// deallocated cursor. Probe-confirmed verbatim against SQL Server 2025
+    /// (class 16, state 2).
+    /// </summary>
+    internal static SimulatedSqlException CursorVariableNotAllocated(string variableName) =>
+        new($"The variable '@{variableName}' does not currently have a cursor allocated to it.", 16950, 16, 2);
 }