BACPAC loader — SqlTableType dispatcher entry (+ cascade unblock of 3 procedures). WideWorldImporters now lands all 4 table types in sys.table_types and the previously-failing procedures that took TVP parameters of those types parse cleanly.

RyanLamansky · RyanLamansky · commit bb1bb84bccd5 · 2026-05-15T14:34:46.000-05:00
**`EmitTableType`** (`SqlServerSimulator/Storage/Bacpac/ModelXmlReader.cs`, phase 1 alongside schemas / UDDTs / sequences / roles). Translates `&lt;Element Type="SqlTableType" Name="[schema].[name]"&gt;` → `CREATE TYPE [schema].[name] AS TABLE (col_list [, PRIMARY KEY (cols)])`. Column children are `SqlTableTypeSimpleColumn` entries with the same `TypeSpecifier` + `IsNullable` / `IsIdentity` shape as regular `SqlSimpleColumn`, so `TranslateSimpleColumn` reuses cleanly. The optional `SqlTableTypePrimaryKeyConstraint` translates to a table-level anonymous `PRIMARY KEY (col1, col2, …)` clause; per [`docs/claude/table-valued-parameters.md`](docs/claude/table-valued-parameters.md), named constraints + UNIQUE/CHECK/FK are grammar-rejected inside table types, so the loader sticks to the anonymous PK form. The `IsClustered` annotation is dropped because table-variable storage is linear-scan regardless of the property. The dispatcher + `IsHandledByAnotherPhase` both gain `SqlTableType`.

**Cascade unblock**: dispatching table types in phase 1 (before procedures in phase 7) lets `CREATE PROCEDURE … @param TVPType READONLY` parse — the TVP parameter type resolution requires the table type to already exist in the schema's `TableTypes` dict at procedure-creation time. 3 of WWI's previously-failing procedures (`Website.SearchForCustomers`, `Website.SearchForStockItems`, `Website.SearchForPeople` — the ones taking `@OrderList` / `@StockItemList` / etc.) now parse cleanly, dropping `SqlProcedure` failures from 6 → 3. The remaining 3 are unrelated parse failures around `sp_addrolemember` modeling and similar.

**Test updates**:
- New `Load_WWI_Table_Types_Land_In_sys_table_types` — verifies the 4 WWI table types (Website.OrderIDList / OrderLineList / OrderList / SensorDataList) appear in `sys.table_types` after load.
- `Load_WWI_Known_Gaps_Recorded_In_Skipped` — `SqlTableType` removed from the expected-grouped list (now asserted *absent* via `IsFalse(grouped.ContainsKey("SqlTableType"))`); `SqlProcedure` expected count drops 6 → 3; the "extended properties on computed columns / table types" comment trims to just "computed columns" since the table-type ones now actually land.

**Doc updates**: `CLAUDE.md`'s BACPAC pointer adds "table types" to the phase-1 dispatch list and refreshes the WWI gap census. `docs/claude/bacpac-prerequisites.md` step 3 (the bundle history entry) gains the `EmitTableType` detail + cascade-unblock note; step 6's gap inventory drops `SqlTableType` and adjusts `SqlProcedure` (6 → 3), and the Status section's WWI summary picks up the 4/4 table-types count.

WWI now loads 48/48 tables + 26/26 sequences + 9/9 roles + **4/4 table types** + 4.7M rows. AW2025 unaffected (still 100% row coverage, every existing assertion green).
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -164,7 +164,7 @@ Per-feature deep-dives live under `docs/claude/`. Each entry below is a trigger:
 - **Touching `XmlSqlType` (singleton in `Storage/XmlType.cs`, SystemTypeId=241, IsLob=true), `XmlSchemaCollection` storage class + `Schema.XmlSchemaCollections` dict + `Database.AllocateXmlCollectionId` (seeds at 65536 per probe), `HeapColumn.XmlSchemaCollection` per-column binding, the `xml`-recognizing arms of `SqlType.ResolveSimpleKeyword` / `Precedence` / `SystemTypeId`, the `xml(name)` / `xml(CONTENT name)` / `xml(DOCUMENT name)` column-type parsing in `ParseOneColumnIntoLists` (via `PeekIsXmlSchemaArgument` / `ParseXmlSchemaCollectionArgument`), `Simulation.Xml.cs` partial (CREATE XML SCHEMA COLLECTION / DROP XML SCHEMA COLLECTION / CREATE [PRIMARY] XML INDEX / FOR PATH|VALUE|PROPERTY secondary form), the `Xml` contextual keyword + `Keyword.Primary` dispatch in `TryParseCreate`, `XmlIndex` / `XmlSecondaryIndexType` storage on `HeapTable.XmlIndexes`, the `XmlMethodCall` expression in `Parser/Expressions/XmlMethodCall.cs` (closed accept-list of `value` / `nodes` / `query` / `exist` / `modify`, parses cleanly, throws `NotSupportedException` at `Run`), or the `sys.xml_schema_collections` / `sys.xml_indexes` catalog views** → [`docs/claude/bacpac-prerequisites.md`](docs/claude/bacpac-prerequisites.md) (the "`xml` data type + XML schema collections + XML methods + XML indexes" section carries the implementation detail).
 - **Touching `GeographySqlType` / `GeometrySqlType` (singletons in `Storage/SpatialType.cs`, both inherit `SpatialSqlType : SqlType(SqlTypeCategory.String)`, SystemTypeId=240, UserTypeId=130/129, IsLob=true), `SqlValue.FromGeography` / `FromGeometry` factories + the spatial branches in `FromString`, the `geography` / `geometry`-recognizing arms of `SqlType.ResolveSimpleKeyword` / `Precedence` / `SystemTypeId` / `UserTypeId`, the `SpatialMethodCall` expression in `Parser/Expressions/SpatialMethodCall.cs` (broad ~70-name accept-list of OGC + Microsoft-extension methods; parses cleanly + throws `NotSupportedException` at `Run` except `.ToString()` returns the stored WKT), the `SpatialStaticCall` expression in `Parser/Expressions/SpatialStaticCall.cs` (`geography::Parse(wkt)` / `geography::STGeomFromText(wkt, srid)` / `geometry::Point(x, y, srid)` work; other static methods throw), the `::` dispatch for `geography`/`geometry` in `Expression.cs` alongside `hierarchyid::`, the `.ToString()` polymorphic delegation in `HierarchyIdMethodCall.Run` (spatial receivers return WKT through the spatial path), the `SpatialIndex` storage class + `SpatialIndexKind` enum on `HeapTable.SpatialIndexes`, the `Simulation.Spatial.cs` partial (CREATE SPATIAL INDEX with USING / BOUNDING_BOX / GRIDS / CELLS_PER_OBJECT parsing + default tessellation_scheme), the `Spatial` contextual keyword routing in `TryParseCreate`, or the `sys.spatial_indexes` (23-col probe-confirmed) / `sys.spatial_index_tessellations` (16-col probe-confirmed) / `sys.spatial_reference_systems` (6-col, empty seed) catalog views** → [`docs/claude/bacpac-prerequisites.md`](docs/claude/bacpac-prerequisites.md) (the "`geography` / `geometry` data types" section carries the implementation detail).
 - **Adding a new top-level statement parser or changing the dispatch loop's statement-separator rules** → [`docs/claude/grammar.md`](docs/claude/grammar.md) + [`docs/claude/control-flow.md`](docs/claude/control-flow.md).
-- **Working on BACPAC import (`Simulation.FromBacpac(string, out BacpacLoadResult)` + Stream overload, internal until externally consumed) — the model.xml dispatcher in `SqlServerSimulator/Storage/Bacpac/ModelXmlReader.cs` (8 phases: DB options + schemas + UDDTs + **sequences + roles** → tables → constraints → FKs → indexes → views → programmable objects → extended properties → BCP data), the `BacpacReader` + `BcpRowReader` + `HierarchyIdWireDecoder` data path, the `BacpacLoadResult.Skipped` + `ElementCounts` + `Warnings` + `TableColumnIsAlias` diagnostics carriers, the resilient-loader contract (per-element exceptions land on Skipped with `"Load failed: …"` prefix and don't abort the load), the wire-format matrix (fixed-raw / 1-byte-prefix / 2-byte-prefix / 8-byte-prefix tiers — see [`docs/claude/bacpac-prerequisites.md`](docs/claude/bacpac-prerequisites.md) "BCP wire format" section)** → [`docs/claude/bacpac-prerequisites.md`](docs/claude/bacpac-prerequisites.md). Loader baseline ships (2026-05-15) with AdventureWorks2025 at **100% row coverage** (760,167 / 760,167; zero BCP-file failures); WideWorldImporters-Standard loads end-to-end with **48/48 tables + 26/26 sequences + 9/9 roles + 4.7M rows**, remaining Skipped categories cataloged in `Load_WWI_Known_Gaps_Recorded_In_Skipped` (89 SqlExtendedProperty, 8 SqlComputedColumn, 6 SqlProcedure, 4 SqlTableType, 3 SqlIndex, 2 SqlCheckConstraint, 2 SqlPermissionStatement, 1 each SqlView / SqlScalarFunction / SqlFilegroup / SqlDatabaseOptions-Collation). MAX types (varchar(MAX) / nvarchar(MAX) / varbinary(MAX)) + xml + CLR-UDT family all use the simple inline 8-byte-prefix wire shape (NOT TDS-PLP chunked form); plain `bit` uses 1-byte length prefix regardless of nullability (probe-confirmed via Production.Document.FolderFlag, the sole non-UDDT bit column in AW). Hierarchyid wire decoder covers AW's [0..79] positive-ordinal envelope via a 4-prefix order-preserving prefix code (`01` / `100` / `101` / `110`); negative ordinals + ordinals ≥ 80 + dotted sub-ordinals raise `NotSupportedException` for a follow-up bundle to extend. Geography rows load with `SpatialLocation = NULL` (WKB→WKT decoding deferred).
+- **Working on BACPAC import (`Simulation.FromBacpac(string, out BacpacLoadResult)` + Stream overload, internal until externally consumed) — the model.xml dispatcher in `SqlServerSimulator/Storage/Bacpac/ModelXmlReader.cs` (8 phases: DB options + schemas + UDDTs + **sequences + roles + table types** → tables → constraints → FKs → indexes → views → programmable objects → extended properties → BCP data), the `BacpacReader` + `BcpRowReader` + `HierarchyIdWireDecoder` data path, the `BacpacLoadResult.Skipped` + `ElementCounts` + `Warnings` + `TableColumnIsAlias` diagnostics carriers, the resilient-loader contract (per-element exceptions land on Skipped with `"Load failed: …"` prefix and don't abort the load), the wire-format matrix (fixed-raw / 1-byte-prefix / 2-byte-prefix / 8-byte-prefix tiers — see [`docs/claude/bacpac-prerequisites.md`](docs/claude/bacpac-prerequisites.md) "BCP wire format" section)** → [`docs/claude/bacpac-prerequisites.md`](docs/claude/bacpac-prerequisites.md). Loader baseline ships (2026-05-15) with AdventureWorks2025 at **100% row coverage** (760,167 / 760,167; zero BCP-file failures); WideWorldImporters-Standard loads end-to-end with **48/48 tables + 26/26 sequences + 9/9 roles + 4/4 table types + 4.7M rows**, remaining Skipped categories cataloged in `Load_WWI_Known_Gaps_Recorded_In_Skipped` (89 SqlExtendedProperty, 8 SqlComputedColumn, 3 SqlProcedure, 3 SqlIndex, 2 SqlCheckConstraint, 2 SqlPermissionStatement, 1 each SqlView / SqlScalarFunction / SqlFilegroup / SqlDatabaseOptions-Collation). MAX types (varchar(MAX) / nvarchar(MAX) / varbinary(MAX)) + xml + CLR-UDT family all use the simple inline 8-byte-prefix wire shape (NOT TDS-PLP chunked form); plain `bit` uses 1-byte length prefix regardless of nullability (probe-confirmed via Production.Document.FolderFlag, the sole non-UDDT bit column in AW). Hierarchyid wire decoder covers AW's [0..79] positive-ordinal envelope via a 4-prefix order-preserving prefix code (`01` / `100` / `101` / `110`); negative ordinals + ordinals ≥ 80 + dotted sub-ordinals raise `NotSupportedException` for a follow-up bundle to extend. Geography rows load with `SpatialLocation = NULL` (WKB→WKT decoding deferred).
 
 ## Not modeled
 
diff --git a/SqlServerSimulator.Tests.Internal/Storage/BacpacLoaderTests.cs b/SqlServerSimulator.Tests.Internal/Storage/BacpacLoaderTests.cs
@@ -598,10 +598,10 @@ public void Load_WWI_Known_Gaps_Recorded_In_Skipped()
         _ = LoadWideWorldImporters(out var diagnostics);
         var grouped = diagnostics.Skipped.GroupBy(s => s.ElementType)
             .ToDictionary(g => g.Key, g => g.Count());
-        AreEqual(89, grouped["SqlExtendedProperty"], "Extended properties (mostly on computed columns / table types) deferred.");
+        IsFalse(grouped.ContainsKey("SqlTableType"), "SqlTableType is dispatched; should not appear in Skipped.");
+        AreEqual(89, grouped["SqlExtendedProperty"], "Extended properties (mostly on computed columns) deferred.");
         AreEqual(8, grouped["SqlComputedColumn"], "Computed columns deferred (same as AW).");
-        AreEqual(6, grouped["SqlProcedure"], "6 WWI procedures parse-fail; need investigation.");
-        AreEqual(4, grouped["SqlTableType"], "SqlTableType not yet in dispatcher.");
+        AreEqual(3, grouped["SqlProcedure"], "3 WWI procedures parse-fail; need investigation.");
         AreEqual(3, grouped["SqlIndex"], "3 WWI indexes fail (likely filtered indexes on bit columns).");
         AreEqual(2, grouped["SqlCheckConstraint"], "2 JSON check constraints deferred.");
         AreEqual(2, grouped["SqlPermissionStatement"], "GRANT/REVOKE wire-up deferred (same as AW).");
@@ -611,6 +611,27 @@ public void Load_WWI_Known_Gaps_Recorded_In_Skipped()
         AreEqual(1, grouped["SqlFilegroup"], "Filegroup not in dispatcher.");
     }
 
+    [TestMethod]
+    public void Load_WWI_Table_Types_Land_In_sys_table_types()
+    {
+        var simulation = LoadWideWorldImporters(out _);
+        using var connection = (SimulatedDbConnection)simulation.CreateDbConnection();
+        connection.Open();
+        using var command = connection.CreateCommand();
+        command.CommandText = "SELECT name FROM sys.table_types ORDER BY name;";
+        using var reader = command.ExecuteReader();
+        var names = new List<string>();
+        while (reader.Read())
+            names.Add(reader.GetString(0));
+        // WWI emits 4 SqlTableType elements, all under the Website schema:
+        // OrderIDList, OrderLineList, OrderList, SensorDataList.
+        HasCount(4, names);
+        AreEqual("OrderIDList", names[0]);
+        AreEqual("OrderLineList", names[1]);
+        AreEqual("OrderList", names[2]);
+        AreEqual("SensorDataList", names[3]);
+    }
+
     [TestMethod]
     public void Load_WWI_Most_Tables_Loaded()
     {
diff --git a/SqlServerSimulator/Storage/Bacpac/ModelXmlReader.cs b/SqlServerSimulator/Storage/Bacpac/ModelXmlReader.cs
@@ -99,6 +99,7 @@ private static void RunPhase(List<XElement> elements, DbConnection connection, B
                     ("SqlUserDefinedDataType", 1) => Run(() => EmitUserDefinedDataType(element, name, connection)),
                     ("SqlSequence", 1) => Run(() => EmitSequence(element, name, connection)),
                     ("SqlRole", 1) => Run(() => EmitRole(element, name, connection)),
+                    ("SqlTableType", 1) => Run(() => EmitTableType(element, name, connection, result)),
                     ("SqlTable", 2) => Run(() => EmitTable(element, name, connection, result)),
                     ("SqlPrimaryKeyConstraint", 3) => Run(() => EmitKeyConstraint(element, name, connection, isPrimary: true)),
                     ("SqlUniqueConstraint", 3) => Run(() => EmitKeyConstraint(element, name, connection, isPrimary: false)),
@@ -144,7 +145,7 @@ private static bool Run(Action action)
     /// </summary>
     private static bool IsHandledByAnotherPhase(string type) => type
         is "SqlDatabaseOptions" or "SqlSchema" or "SqlUserDefinedDataType"
-        or "SqlSequence" or "SqlRole"
+        or "SqlSequence" or "SqlRole" or "SqlTableType"
         or "SqlTable"
         or "SqlPrimaryKeyConstraint" or "SqlUniqueConstraint"
         or "SqlCheckConstraint" or "SqlDefaultConstraint"
@@ -340,6 +341,79 @@ private static void EmitSequence(XElement element, string? qualifiedName, DbConn
         _ = command.ExecuteNonQuery();
     }
 
+    /// <summary>
+    /// Emits <c>CREATE TYPE [schema].[name] AS TABLE (col_list [, PRIMARY KEY (cols)])</c>
+    /// for a <c>SqlTableType</c> element. Columns are <c>SqlTableTypeSimpleColumn</c>
+    /// entries with the same TypeSpecifier shape as regular columns — so
+    /// <see cref="TranslateSimpleColumn"/> reuses cleanly. The optional
+    /// <c>SqlTableTypePrimaryKeyConstraint</c> arrives under a
+    /// <c>Constraints</c> relationship; the PK is anonymous (named constraints
+    /// are grammar-rejected inside table types, see Msg 156 in
+    /// <c>docs/claude/table-valued-parameters.md</c>) and the
+    /// <c>IsClustered</c> annotation is dropped (table-variable storage is
+    /// linear-scan regardless). UNIQUE / CHECK / FK on table types aren't
+    /// exercised by WWI and aren't translated here.
+    /// </summary>
+    private static void EmitTableType(XElement element, string? qualifiedName, DbConnection connection, BacpacLoadResult result)
+    {
+        if (string.IsNullOrEmpty(qualifiedName))
+            throw new InvalidDataException("bacpac: SqlTableType element missing Name attribute.");
+
+        var columnsRel = element.Elements(Ns + "Relationship")
+            .FirstOrDefault(r => r.Attribute("Name")?.Value == "Columns")
+            ?? throw new InvalidDataException($"bacpac: SqlTableType '{qualifiedName}' has no Columns relationship.");
+
+        var columnDdls = new List<string>();
+        foreach (var col in columnsRel.Elements(Ns + "Entry").Elements(Ns + "Element"))
+        {
+            var colType = col.Attribute("Type")?.Value;
+            var colName = col.Attribute("Name")?.Value;
+            if (colType == "SqlTableTypeSimpleColumn")
+            {
+                columnDdls.Add(TranslateSimpleColumn(col, colName, result));
+            }
+            else
+            {
+                result.Skipped.Add(new BacpacSkipped(colType ?? "<unknown>", colName, $"Table-type column kind not handled inside '{qualifiedName}'."));
+            }
+        }
+
+        var pkClauses = new List<string>();
+        var constraintsRel = element.Elements(Ns + "Relationship")
+            .FirstOrDefault(r => r.Attribute("Name")?.Value == "Constraints");
+        if (constraintsRel is not null)
+        {
+            foreach (var constraint in constraintsRel.Elements(Ns + "Entry").Elements(Ns + "Element"))
+            {
+                if (constraint.Attribute("Type")?.Value != "SqlTableTypePrimaryKeyConstraint")
+                    continue;
+                var cols = new List<string>();
+                var specs = constraint.Elements(Ns + "Relationship")
+                    .FirstOrDefault(r => r.Attribute("Name")?.Value == "ColumnSpecifications")
+                    ?.Elements(Ns + "Entry").Elements(Ns + "Element");
+                foreach (var spec in specs ?? [])
+                {
+                    var colRef = spec.Elements(Ns + "Relationship")
+                        .FirstOrDefault(r => r.Attribute("Name")?.Value == "Column")
+                        ?.Elements(Ns + "Entry").Elements(Ns + "References")
+                        .FirstOrDefault()?.Attribute("Name")?.Value;
+                    if (string.IsNullOrEmpty(colRef))
+                        continue;
+                    cols.Add(colRef[(colRef.LastIndexOf('.') + 1)..]);
+                }
+                if (cols.Count > 0)
+                    pkClauses.Add($"PRIMARY KEY ({string.Join(", ", cols)})");
+            }
+        }
+
+        var body = string.Join(", ", columnDdls.Concat(pkClauses));
+        using var command = connection.CreateCommand();
+#pragma warning disable CA2100 // bacpac content is caller-trusted; the loader is a translator, not an end-user input handler
+        command.CommandText = $"CREATE TYPE {qualifiedName} AS TABLE ({body});";
+#pragma warning restore CA2100
+        _ = command.ExecuteNonQuery();
+    }
+
     /// <summary>
     /// Emits <c>CREATE ROLE [name] [AUTHORIZATION owner]</c> for a
     /// <c>SqlRole</c> element. The <c>Authorizer</c> relationship points at
diff --git a/docs/claude/bacpac-prerequisites.md b/docs/claude/bacpac-prerequisites.md
