Output-direction sql_variant and CLR-UDT RPC parameters write back over TDS: end-of-batch write-back stamps the engine-typed SqlValue on an internal SimulatedDbParameter side-channel and the RETURNVALUE writer reuses the column TYPE_INFO/value writers.

Author: RyanLamansky

docs/claude/backlog.md

@@ -42,7 +42,8 @@ Remaining phases, roughly in value order:
   **`text`/`ntext`/`image` ship fully** (2026-07-19) — result columns, `image` (0x22) input parameters, and **`SqlBulkCopy` into a legacy-LOB column** (2026-07-19: the BCP LONGLEN COLMETADATA + in-band text-pointer ROW value now decode); see [`tds-endpoint.md`](tds-endpoint.md#legacy-text--ntext--image-wire-forms).
   **`sql_variant` and UDT (`geography`/`geometry`/`hierarchyid`) ship as RPC *input* parameters AND as *columns inside a TVP*** (2026-07-19 — the shared decoder made the TVP columns near-free; see [`tds-endpoint.md`](tds-endpoint.md#tvp-parameters-sqldbtypestructured)).
   **TVP parameters (0xF3, `SqlDbType.Structured`) ship** — `DataTable` / `IEnumerable<SqlDataRecord>` / `DbDataReader` sources over proc-RPC + sp_executesql, error parity for arity / type / NOT NULL / CHECK / PK / UNIQUE / unknown-type.
-  Residuals: **output-direction** UDT / `sql_variant` params; **`SET TEXTSIZE`** doesn't truncate returned LOB data (parse-and-discard).
+  Residuals: **`SET TEXTSIZE`** doesn't truncate returned LOB data (parse-and-discard).
+  (Output-direction UDT / `sql_variant` params shipped 2026-07-19 — probed RETURNVALUE wire forms in [`tds-endpoint.md`](tds-endpoint.md#clr-udt--sql_variant-parameters).)
   (The LOB-backed TVP column → stored-proc READONLY parameter dangling-pointer bug was fixed 2026-07-19: the proc-parameter copy re-homes off-row values into the parameter's heap; see [`table-valued-parameters.md`](table-valued-parameters.md).)
 - **Smaller fidelity items**: TDS 8.0 / `Encrypt=Strict` (ALPN via `SslApplicationProtocol`); user-supplied `X509Certificate2` — an add-on-demand public-surface expansion.
   (Off-loopback binding shipped 2026-07-19 as `ListenNetworkAsync`, gated on a registered login; per-interface bind-address selection remains add-on-demand.)

docs/claude/tds-endpoint.md

@@ -276,10 +276,13 @@ Probed against SQL Server 2025 + SqlClient 7.0.2 (2026-07-19).
 - **`sql_variant` (`0x62`)** — TYPE_INFO is a 4-byte max length (ignored); the value is a 4-byte total length (**0 = NULL**) then the MS-TDS §2.2.5.5.3 body (base-type token + property-byte count + property bytes + inner value), the read mirror of `TdsTypeCodec.BuildVariantBody`, decoded into the inner `SqlValue` and wrapped by `SqlValue.FromVariant` so `SQL_VARIANT_PROPERTY(@p,'BaseType')` reports the sent type.
   SqlClient's per-CLR-type base-type choices (probe-confirmed): `int`/`bigint`/`smallint`/`tinyint`/`bit` direct; `decimal` → `numeric(38, 2)` (base token `0x6C`); `float`/`real` direct; **both `string` and `SqlString` → `nvarchar`** (varchar is not sent as a variant); `DateTime` → `datetime`; `Guid` → `uniqueidentifier`; `SqlMoney` → `money`; `byte[]` → `varbinary`; `TimeSpan` → `time(7)`.
   (SqlClient 7.0.2 mis-serializes a `DateOnly` variant — the stream truncates client-side before the server sees it; not a server concern.)
-- **Residuals**: **output-direction** UDT / `sql_variant` parameters (real supports both) are unmodeled — the RETURNVALUE writeback for these types is rejected up front (`TdsTypeCodec.WriteReturnValue`, keyed off the `DbType.Object` marker) with a clear ERROR rather than a malformed RETURNVALUE token that desyncs the client.
-  (**TVP columns** of UDT / `sql_variant` type now decode — the RPC decoders and the column decoder share `TdsWireValue`; see [TVP parameters](#tvp-parameters-sqldbtypestructured).)
+- **Output direction ships** (probe-captured RETURNVALUE shapes, SQL Server 2025 + SqlClient 7.0.2, 2026-07-19): a `sql_variant` output parameter's RETURNVALUE TYPE_INFO is `0x62` + ULONG max length (8009) with the same 4-byte-total-length + self-describing-body value a variant result column carries; a CLR-UDT output parameter's TYPE_INFO is the **COLMETADATA-shaped** UDT_INFO (USHORT max byte size — 892 for `hierarchyid`, `0xFFFF` for spatial — then db / schema / type B_VARCHARs and the US_VARCHAR assembly-qualified name; richer than the three-B_VARCHAR client request form) with a PLP value, PLP NULL for NULL.
+  Real fills the db segment with the current database; the simulator reuses the column writers verbatim (empty db segment — SqlClient reads both).
+  The engine value reaches the writer via `SimulatedDbParameter.OutputSqlValue`, an internal side-channel stamped at end-of-batch write-back alongside the CLR `Value` conversion, because the CLR object alone no longer carries the variant inner type / UDT kind; `TdsSession.Rpc.WriteOutputReturnValues` routes `DbType.Object`-marked outputs through the `SqlValue` overload of `TdsTypeCodec.WriteReturnValue`.
+  **Variant decimal bodies are always 1 sign byte + a 16-byte magnitude** regardless of precision (probe-captured in both a result column and a RETURNVALUE): SqlClient's row-value reader tolerates a narrower magnitude but its RETURNVALUE reader reads the fixed 17 data bytes and desyncs on anything shorter — `BuildVariantDecimal` writes the fixed form.
+  (**TVP columns** of UDT / `sql_variant` type also decode — the RPC decoders and the column decoder share `TdsWireValue`; see [TVP parameters](#tvp-parameters-sqldbtypestructured).)
   A `sql_variant` carrying an inner value implicitly converted to a narrower sink (e.g. `insert … (int_col) values (@variant_int)`) is accepted by the simulator's engine-level variant coercion where **real raises Msg 257** — a pre-existing in-process `sql_variant` divergence surfaced (not introduced) by wire parameters.
-  Oracles: `UdtRpcParameterTests`, `SqlVariantRpcParameterTests` (Tests.SqlClient), using the real `Microsoft.SqlServer.Types` package for typed `SqlGeography` / `SqlHierarchyId` construction (works headless on Linux; `SqlGeometry.STGeomFromText` does **not** — geometry is built from raw WKB bytes).
+  Oracles: `UdtRpcParameterTests`, `SqlVariantRpcParameterTests`, `SqlVariantWireTests` (Tests.SqlClient), using the real `Microsoft.SqlServer.Types` package for typed `SqlGeography` / `SqlHierarchyId` construction (works headless on Linux; `SqlGeometry.STGeomFromText` does **not** — geometry is built from raw WKB bytes).
 
 ## Transaction Manager requests
 
@@ -385,8 +388,7 @@ A real build number is load-bearing for SSMS's per-build client feature gates (A
 - Login INFO states are approximations.
 - MARS ships (see [MARS](#mars-multiple-active-result-sets) below); no TDS 8.0 / `Encrypt=Strict`, no plaintext sessions, no integrated auth (an SSPI/FedAuth login presents an empty SQL username, which under a non-empty registry fails as Msg 18456 rather than negotiating).
 - Credential-enforcement edges not modeled: `ALTER LOGIN … DISABLE` parses but doesn't block login; password policy (`CHECK_POLICY` / expiration / lockout) never enforced; no login auditing.
-- RPC parameter gaps: **output-direction** UDT / `sql_variant` parameters rejected (input decode ships — see [CLR-UDT / sql_variant parameters](#clr-udt--sql_variant-parameters)).
-  Every input-parameter TYPE_INFO is accepted — TVP / UDT / `sql_variant` / `text` / `ntext` / `image` — and every client value-stream column type (bulk / TVP) now decodes through the shared `TdsWireValue` / `TdsColumnDecoder`, including `sql_variant` / CLR-UDT columns and legacy-LOB bulk destinations.
+- RPC parameters are gap-free in both directions: every input TYPE_INFO is accepted — TVP / UDT / `sql_variant` / `text` / `ntext` / `image` — every client value-stream column type (bulk / TVP) decodes through the shared `TdsWireValue` / `TdsColumnDecoder`, and output-direction UDT / `sql_variant` parameters write back as RETURNVALUE tokens (see [CLR-UDT / sql_variant parameters](#clr-udt--sql_variant-parameters)).
   Non-cursor well-known ProcIDs beyond the sp_execute/sp_prepare family are rejected with ERROR 50000 naming the id.
 - Mid-stream attention (cancel) ships — see below.
   Residual: cancel reaction is bounded by the current statement's *materialization*, not just its streaming, because a statement's rows are materialized in one synchronous step before they stream (a cancel mid-way through a compute-heavy `SELECT`/sort waits for that materialization to finish, then discards the result at the outcome boundary; real streams-as-it-computes and stops sooner).

src/SqlServerSimulator/Network/CLAUDE.md

@@ -58,7 +58,8 @@ These notes are the local implementation contracts.
   COLMETADATA = type byte + 4-byte max length (8009).
   Each value = 4-byte total length then the MS-TDS 2.2.5.5.3 body (base-type token + cbProps + props + data).
   **NULL is total-length 0, not 0xFFFFFFFF** — a non-NULL variant is always ≥2 bytes, so SqlClient reads 0 as NULL (the one non-obvious wire rule; got this wrong first and it desynced the stream).
-  `sql_variant` **input** *parameters* decode (RPC read side, `TdsRpc.DecodeSqlVariant` → `TdsWireValue.ReadVariantBody` — the read mirror of `BuildVariantBody`, into `SqlValue.FromVariant`; **output** direction stays rejected), and **`sql_variant` columns inside a TVP** decode through the same body reader (`TdsColumnDecoder`: 0x62 + 4-byte max length, value = 4-byte total length `0`=NULL + body).
+  `sql_variant` **input** *parameters* decode (RPC read side, `TdsRpc.DecodeSqlVariant` → `TdsWireValue.ReadVariantBody` — the read mirror of `BuildVariantBody`, into `SqlValue.FromVariant`), **output** direction writes back as a RETURNVALUE (`0x62` + ULONG maxlen 8009 + the column-form value; the engine value rides `SimulatedDbParameter.OutputSqlValue`, stamped at write-back, since the CLR `Value` loses the inner type), and **`sql_variant` columns inside a TVP** decode through the same body reader (`TdsColumnDecoder`: 0x62 + 4-byte max length, value = 4-byte total length `0`=NULL + body).
+  Variant decimal bodies are always sign + 16-byte magnitude regardless of precision (probed in column and RETURNVALUE positions; SqlClient's RETURNVALUE reader hard-reads 17 data bytes).
   Oracles: `SqlVariantWireTests`, `SqlVariantRpcParameterTests`, `TvpVariantUdtColumnTests`.
 - **`geography` / `geometry` (UDTTYPE `0xF0`)**: result-column-only.
   COLMETADATA = ushort max-byte-size (`0xFFFF`) + three B_VARCHAR names (db empty — the static codec can't reach the session db; schema `sys`; type name) + US_VARCHAR assembly-qualified name (`SpatialAssemblyQualifiedName`, probe-matched).
@@ -69,7 +70,7 @@ These notes are the local implementation contracts.
   Oracle: `HierarchyIdWireTests`, `HierarchyIdOrdPathTests`.
   UDT **input** *parameters* decode (`TdsRpc.DecodeClrUdt` → `TdsWireValue.BuildUdtValue`): the client UDT_INFO is three B_VARCHARs (db/schema/type, no max-size, no AQN — shorter than COLMETADATA) + PLP value; hierarchyid OrdPath bytes bind verbatim, spatial WKB decodes via `SpatialWkbDecoder.TryDecode`, resolved case-insensitively into a pre-built `SqlValue` (unknown type → Msg 8064, invalid spatial bytes → Msg 8023).
   **UDT columns inside a TVP** decode through the same builder (`TdsColumnDecoder`: 0xF0 + three B_VARCHARs + PLP value).
-  **Output** direction stays rejected.
+  **Output** direction writes back as a RETURNVALUE carrying the **COLMETADATA-shaped** UDT_INFO (max byte size + db/schema/type + AQN — richer than the client request form) + PLP value, from `SimulatedDbParameter.OutputSqlValue`.
   A LOB-backed UDT TVP column (`geography`/`geometry`) round-trips via both the `sp_executesql` text path and a stored-proc READONLY parameter (the proc-parameter copy re-homes off-row values — docs/claude/table-valued-parameters.md).
   Oracles: `UdtRpcParameterTests`, `TvpVariantUdtColumnTests`.
 - **Length-prefix trap**: most strings are char-counted (B_VARCHAR / US_VARCHAR), but TM-request transaction names are byte-counted — misreading them as char-counted overruns the payload on every `SqlTransaction.Save`.

src/SqlServerSimulator/Network/TdsSession.Rpc.cs

@@ -1,5 +1,6 @@
 using System.Data;
 using System.Globalization;
+using SqlServerSimulator.Storage;
 
 namespace SqlServerSimulator.Network;
 
@@ -201,8 +202,7 @@ private async ValueTask ExecuteStatementRpcAsync(
         if (handleReturn is { } handleValue)
             TdsTypeCodec.WriteReturnValue(writer, 0, handleValue.Name, DbType.Int32, handleValue.Handle);
 
-        foreach (var (ordinal, wire, bound) in outputs)
-            TdsTypeCodec.WriteReturnValue(writer, checked((ushort)ordinal), wire.Name, wire.DbType, bound.Value);
+        WriteOutputReturnValues(writer, outputs);
 
         if (!moreRequests)
             this.WriteDatabaseChangeIfAny(writer);
@@ -238,8 +238,7 @@ private async ValueTask ExecuteProcedureRpcAsync(TdsRpcRequest request, TdsToken
             return;
 
         writer.WriteReturnStatus(returnParameter.Value is int returnCode ? returnCode : 0);
-        foreach (var (ordinal, wire, bound) in outputs)
-            TdsTypeCodec.WriteReturnValue(writer, checked((ushort)ordinal), wire.Name, wire.DbType, bound.Value);
+        WriteOutputReturnValues(writer, outputs);
 
         if (!moreRequests)
             this.WriteDatabaseChangeIfAny(writer);
@@ -269,6 +268,26 @@ private static ushort WellKnownProcId(string procName) =>
         ["sp_cursorclose"] = Tds.ProcIdCursorClose,
     };
 
+    /// <summary>
+    /// RETURNVALUE tokens for a request's output-direction parameters.
+    /// <see cref="DbType.Object"/> marks a <c>sql_variant</c> / CLR-UDT
+    /// parameter (its wire value rode a pre-built <see cref="SqlValue"/>, not
+    /// a <see cref="DbType"/>): those write from the engine-typed
+    /// <see cref="SimulatedDbParameter.OutputSqlValue"/> stamped at
+    /// end-of-batch write-back, falling back to echoing the decoded input
+    /// value when the batch never reached write-back.
+    /// </summary>
+    private static void WriteOutputReturnValues(TdsTokenWriter writer, List<(int Ordinal, TdsRpcParameter Wire, SimulatedDbParameter Bound)> outputs)
+    {
+        foreach (var (ordinal, wire, bound) in outputs)
+        {
+            if (wire.DbType == DbType.Object)
+                TdsTypeCodec.WriteReturnValue(writer, checked((ushort)ordinal), wire.Name, bound.OutputSqlValue ?? (SqlValue)wire.Value!);
+            else
+                TdsTypeCodec.WriteReturnValue(writer, checked((ushort)ordinal), wire.Name, wire.DbType, bound.Value);
+        }
+    }
+
     private static SimulatedDbParameter AddParameter(SimulatedDbCommand command, TdsRpcParameter wire)
     {
         var parameter = command.CreateParameter();

src/SqlServerSimulator/Network/TdsTypeCodec.cs

@@ -162,14 +162,26 @@ private static void WriteRawFixedValue(TdsTokenWriter writer, SqlType type, SqlV
     /// </summary>
     public static void WriteReturnValue(TdsTokenWriter writer, ushort ordinal, string name, DbType dbType, object? value)
     {
-        // DbType.Object is the RPC read side's marker for a CLR-UDT / sql_variant
-        // parameter (its value rode a pre-built SqlValue, not a DbType). Writing
-        // one back as a RETURNVALUE is unmodeled; reject up front — before any
-        // token bytes — rather than emit a malformed RETURNVALUE that desyncs the
-        // client (SqlClient surfaces the half-token as ArgumentOutOfRangeException).
-        if (dbType == DbType.Object)
-            throw new NotSupportedException("output CLR UDT / sql_variant RPC parameters");
+        var declared = SqlType.GetByDbType(dbType);
+        var sqlValue = value is null or DBNull ? SqlValue.Null(declared) : declared.ConvertParameter(value);
+        WriteReturnValue(writer, ordinal, name, sqlValue.IsNull ? declared : sqlValue.Type, sqlValue);
+    }
+
+    /// <summary>
+    /// RETURNVALUE token from an engine-typed <see cref="SqlValue"/> — the
+    /// path for <c>sql_variant</c> and CLR-UDT (<c>hierarchyid</c> /
+    /// <c>geography</c> / <c>geometry</c>) output parameters, whose wire form
+    /// (self-describing variant body; UDT_INFO + PLP value) needs the value's
+    /// own type identity rather than a <see cref="DbType"/> mapping.
+    /// Probe-captured against SQL Server 2025 (2026-07-19): the RETURNVALUE
+    /// TYPE_INFO and value bytes are the same forms the matching result
+    /// columns carry, so the column writers are reused as-is.
+    /// </summary>
+    public static void WriteReturnValue(TdsTokenWriter writer, ushort ordinal, string name, SqlValue value)
+        => WriteReturnValue(writer, ordinal, name, value.Type, value);
 
+    private static void WriteReturnValue(TdsTokenWriter writer, ushort ordinal, string name, SqlType wireType, SqlValue sqlValue)
+    {
         writer.EnterComposite();
         writer.WriteByte(Tds.TokenReturnValue);
         writer.WriteUInt16(ordinal);
@@ -179,9 +191,6 @@ public static void WriteReturnValue(TdsTokenWriter writer, ushort ordinal, strin
         writer.WriteByte(0x09);
         writer.WriteByte(0);
 
-        var declared = SqlType.GetByDbType(dbType);
-        var sqlValue = value is null or DBNull ? SqlValue.Null(declared) : declared.ConvertParameter(value);
-        var wireType = sqlValue.IsNull ? declared : sqlValue.Type;
         WriteTypeInfo(writer, wireType);
         WriteValue(writer, wireType, sqlValue);
         writer.LeaveComposite();
@@ -829,7 +838,13 @@ private static byte[] BuildVariantBinary(byte typeToken, SqlValue inner)
 
     private static byte[] BuildVariantDecimal(DecimalSqlType type, SqlValue inner)
     {
-        var magnitudeBytes = MagnitudeBytes(type.precision);
+        // Server-sent variant decimal data is always 1 sign byte + a 16-byte
+        // magnitude regardless of precision (probe-captured 2026-07-19 in both
+        // a result column and a RETURNVALUE; RPC *request* decimals are the
+        // precision-width exception, on the decode side). SqlClient's row
+        // reader tolerates a narrower magnitude but its RETURNVALUE reader
+        // reads the fixed 17 and desyncs on anything shorter.
+        const int magnitudeBytes = 16;
         // 2 prop bytes (precision, scale); data = 1 sign byte + magnitude.
         var body = new byte[2 + 2 + 1 + magnitudeBytes];
         body[0] = 0x6A;

src/SqlServerSimulator/SimulatedDbParameter.cs

@@ -1,6 +1,7 @@
 using System.Data;
 using System.Data.Common;
 using System.Diagnostics.CodeAnalysis;
+using SqlServerSimulator.Storage;
 
 [module: SuppressMessage("Microsoft.Design", "CA1065:DoNotRaiseExceptionsInUnexpectedLocations", Scope = "member", Target = "~P:SqlServerSimulator.SimulatedDbParameter.DbType", Justification = "Mirrors SqlParameter inference: a CLR Value with no DbType mapping is surfaced as ArgumentException at property read, not later at command execution.")]
 
@@ -37,6 +38,16 @@ public sealed class SimulatedDbParameter : DbParameter
 {
     private DbType? dbType;
 
+    /// <summary>
+    /// The typed engine value written back to an output-direction parameter
+    /// at end of batch, alongside the CLR conversion stored in
+    /// <see cref="Value"/>. The TDS listener's RETURNVALUE writer reads it
+    /// for <c>sql_variant</c> / CLR-UDT parameters, whose wire form needs
+    /// the inner type identity (variant base type, UDT kind) that the CLR
+    /// object no longer carries.
+    /// </summary>
+    internal SqlValue? OutputSqlValue;
+
     /// <inheritdoc/>
     public override DbType DbType
     {

src/SqlServerSimulator/Simulation/Simulation.cs

@@ -994,7 +994,11 @@ private IEnumerable<SimulatedStatementOutcome> InvokeFromCommandTypeStoredProced
             {
                 var pname = parameter.ParameterName.StartsWith('@') ? parameter.ParameterName[1..] : parameter.ParameterName;
                 if (batch.Variables.TryGetValue(pname, out var slot))
+                {
+                    if (parameter is SimulatedDbParameter simulated)
+                        simulated.OutputSqlValue = slot.Value;
                     parameter.Value = slot.Value.IsNull ? DBNull.Value : slot.Value.ToObject();
+                }
             }
         }
 
@@ -1896,9 +1900,10 @@ private static void WriteBackOutputParameters(BatchContext batch)
     {
         foreach (var slot in batch.Variables.Values)
         {
-            if (slot.Parameter is { } parameter
+            if (slot.Parameter is SimulatedDbParameter parameter
                 && parameter.Direction is ParameterDirection.InputOutput or ParameterDirection.Output)
             {
+                parameter.OutputSqlValue = slot.Value;
                 parameter.Value = slot.Value.IsNull ? DBNull.Value : slot.Value.ToObject();
             }
         }