clockworklabs · rekhoff · Apr 28, 2026 · Mar 2, 2026 · Mar 12, 2026 · Mar 13, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -102,6 +102,10 @@ jobs:
           cd $env:USERPROFILE\emsdk
           .\emsdk install 4.0.21
           .\emsdk activate 4.0.21
+          # Add emscripten to PATH for subsequent steps and subprocesses
+          $emsdkPath = "$env:USERPROFILE\emsdk\upstream\emscripten"
+          Add-Content -Path $env:GITHUB_PATH -Value $emsdkPath
+          Write-Host "Added $emsdkPath to PATH"
 
       - name: Install psql (Windows)
         if: runner.os == 'Windows'

diff --git a/crates/bindings-csharp/NATIVEAOT-LLVM.md b/crates/bindings-csharp/NATIVEAOT-LLVM.md
@@ -0,0 +1,174 @@
+# Using NativeAOT-LLVM with SpacetimeDB C# Modules
+
+This guide provides instructions for enabling NativeAOT-LLVM compilation for C# SpacetimeDB modules, which can provide performance improvements.
+
+## Overview
+
+NativeAOT-LLVM compiles C# modules to native WebAssembly (WASM) instead of using the Mono runtime.
+
+> [!WARNING]
+> This is currently only supported for Windows server modules and is experimental.
+
+## Prerequisites
+
+- **.NET SDK 8.x** (same version used by SpacetimeDB)
+- **Emscripten SDK (EMSDK)** installed (must contain `upstream/emscripten/emcc.bat`)
+- **(Optional) Binaryen (wasm-opt)** installed and on `PATH` (recommended: `version_116`)
+- **Windows** - NativeAOT-LLVM is currently only supported for Windows server modules
+
+## Prerequisites Installation
+
+### Install Emscripten SDK (EMSDK)
+
+The Emscripten SDK is required for NativeAOT-LLVM compilation:
+
+1. **Download and extract** the Emscripten SDK from `https://github.com/emscripten-core/emsdk`
+   - Example path: `D:\Tools\emsdk`
+
+2. **Set environment variable** (optional - the CLI will detect it automatically):
+   ```
+   $env:EMSDK="D:\Tools\emsdk"
+   ```
+
+### Install Binaryen (Optional)
+
+Binaryen provides `wasm-opt` for WASM optimization (recommended for performance):
+
+1. Download Binaryen https://github.com/WebAssembly/binaryen/releases/tag/version_116 for Windows
+2. Extract to e.g. `D:\Tools\binaryen`
+3. Add `D:\Tools\binaryen\bin` to `PATH`
+
+   To temporarily add to your current PowerShell session:
+   ```
+   $env:PATH += ";D:\Tools\binaryen\bin"
+   ```
+4. Verify:
+   ```
+   wasm-opt --version
+   ```
+
+## Creating a New NativeAOT Project
+
+When creating a new C# project, use the `--native-aot` flag:
+
+```
+spacetime init --lang csharp --native-aot my-native-aot-project
+```
+
+This automatically:
+- Creates a C# project with the required package references
+- Generates a `spacetime.json` with `"native-aot": true`
+- Configures the project for NativeAOT-LLVM compilation
+
+## Converting an Existing Project
+
+1. **Update spacetime.json**
+   Add `"native-aot": true` to your `spacetime.json`:
+   ```json
+   {
+     "module": "your-module-name",
+     "native-aot": true
+   }
+   ```
+
+   **Note:** Once `spacetime.json` has `"native-aot": true`, you can simply run `spacetime publish` without the `--native-aot` flag. The CLI will automatically detect the configuration and use NativeAOT compilation.
+
+2. **Ensure NuGet feed is configured**
+   NativeAOT-LLVM packages come from **dotnet-experimental**. Add to `NuGet.Config`:
+   ```xml
+   <?xml version="1.0" encoding="utf-8"?>
+   <configuration>
+     <packageSources>
+       <clear />
+       <add key="dotnet-experimental" value="https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-experimental/nuget/v3/index.json" />
+       <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
+     </packageSources>
+   </configuration>
+   ```
+
+3. **Add NativeAOT package references**
+   Add this `ItemGroup` to your `.csproj`:
+   ```xml
+   <ItemGroup Condition="'$(EXPERIMENTAL_WASM_AOT)' == '1'">
+     <PackageReference Include="Microsoft.NET.ILLink.Tasks" Version="8.0.0-*" Condition="'$(ILLinkTargetsPath)' == ''" />
+     <PackageReference Include="Microsoft.DotNet.ILCompiler.LLVM" Version="8.0.0-*" />
+     <PackageReference Include="runtime.$(NETCoreSdkPortableRuntimeIdentifier).Microsoft.DotNet.ILCompiler.LLVM" Version="8.0.0-*" />
+   </ItemGroup>
+   ```
+
+   Your complete `.csproj` should look like:
+   ```xml
+   <Project Sdk="Microsoft.NET.Sdk">
+     <PropertyGroup>
+       <TargetFramework>net8.0</TargetFramework>
+       <RuntimeIdentifier>wasi-wasm</RuntimeIdentifier>
+       <ImplicitUsings>enable</ImplicitUsings>
+       <Nullable>enable</Nullable>
+     </PropertyGroup>
+     <ItemGroup>
+       <PackageReference Include="SpacetimeDB.Runtime" Version="2.0.*" />
+     </ItemGroup>
+     <ItemGroup Condition="'$(EXPERIMENTAL_WASM_AOT)' == '1'">
+       <PackageReference Include="Microsoft.NET.ILLink.Tasks" Version="8.0.0-*" Condition="'$(ILLinkTargetsPath)' == ''" />
+       <PackageReference Include="Microsoft.DotNet.ILCompiler.LLVM" Version="8.0.0-*" />
+       <PackageReference Include="runtime.$(NETCoreSdkPortableRuntimeIdentifier).Microsoft.DotNet.ILCompiler.LLVM" Version="8.0.0-*" />
+     </ItemGroup>
+   </Project>
+   ```
+
+## Publishing Your NativeAOT Module
+
+After completing either the **Creating a New NativeAOT Project** or **Converting an Existing Project** steps above, you can publish your module normally:
+
+```
+# From your project directory
+spacetime publish your-database-name
+```
+
+If you have `"native-aot": true` in your `spacetime.json`, the CLI will automatically detect this and use NativeAOT compilation. Alternatively, you can use:
+
+```
+spacetime publish --native-aot your-database-name
+```
+
+The CLI will display "Using NativeAOT-LLVM compilation (experimental)" when NativeAOT is enabled.
+
+## Troubleshooting
+
+### Package source mapping enabled
+If you have **package source mapping** enabled in `NuGet.Config`, add mappings for the LLVM packages:
+
+```xml
+<packageSourceMapping>
+    <packageSource key="bsatn-runtime">
+        <package pattern="SpacetimeDB.BSATN.Runtime" />
+    </packageSource>
+    <packageSource key="SpacetimeDB.Runtime">
+        <package pattern="SpacetimeDB.Runtime" />
+    </packageSource>
+    <packageSource key="dotnet-experimental">
+        <package pattern="Microsoft.DotNet.ILCompiler.LLVM" />
+        <package pattern="runtime.*" />
+    </packageSource>
+    <packageSource key="nuget.org">
+        <package pattern="*" />
+    </packageSource>
+</packageSourceMapping>
+```
+
+### wasi-experimental workload install fails
+If the CLI cannot install the `wasi-experimental` workload automatically, install it manually:
+
+```
+dotnet workload install wasi-experimental
+```
+
+### Duplicate PackageReference warning
+You may see a `NU1504` warning about duplicate `PackageReference` items. This is expected and non-blocking.
+
+### Code generation failed
+If you see errors like "Code generation failed for method", ensure:
+1. You're using `SpacetimeDB.Runtime` version 2.0.4 or newer
+2. All required package references are in your `.csproj`
+3. The `dotnet-experimental` feed is configured in `NuGet.Config`
+
diff --git a/crates/bindings-csharp/Runtime/Internal/Module.cs b/crates/bindings-csharp/Runtime/Internal/Module.cs
@@ -206,6 +206,36 @@
 
 public static class Module
 {
+    // Workaround for NativeAOT-LLVM IL scanner bug:
+    // The scanner fails to compute vtables for TaggedEnum<T> base types when
+    // concrete subtypes are only encountered indirectly (e.g., through Equals
+    // calls on types containing TaggedEnum fields). This occurs when no user
+    // table has indexes/primary keys, so RawIndexAlgorithm is never directly
+    // constructed in user code.
+    // By referencing concrete TaggedEnum subtypes here, we ensure the IL scanner
+    // always processes their vtables. One variant per TaggedEnum is sufficient.
+    [System.Runtime.CompilerServices.MethodImpl(
+        System.Runtime.CompilerServices.MethodImplOptions.NoInlining
+    )]
+    private static void EnsureNativeAotTypeRoots()
+    {
+        // These constructions are never executed at runtime — they exist solely
+        // to make the IL scanner compute vtables for TaggedEnum subtypes.
+        // The condition is always false but the scanner must assume it could be true.
+        if (Environment.TickCount < 0 && Environment.TickCount > 0)
+        {
+            _ = new RawIndexAlgorithm.BTree(null!);
+            _ = new RawConstraintDataV9.Unique(null!);
+            _ = new RawModuleDef.V10(null!);
+            _ = new RawModuleDefV10Section.Typespace(null!);
+            _ = new ExplicitNameEntry.Table(null!);
+            _ = new MiscModuleExport.TypeAlias(null!);
+            _ = new RawMiscModuleExportV9.ColumnDefaultValue(null!);
+            _ = new SpacetimeDB.Filter.Sql(null!);
+            _ = new ViewResultHeader.RowData(default);
+        }
+    }
+
     private static readonly RawModuleDefV10 moduleDef = new();
 
     private static readonly List<IReducer> reducers = [];
@@ -419,6 +449,7 @@
 
     public static void __describe_module__(BytesSink description)
     {
+        EnsureNativeAotTypeRoots();
         try
         {
             var module = moduleDef.BuildModuleDefinition();
@@ -470,7 +501,7 @@
        catch (Exception e)
        {
            var error_str = e.Message ?? e.GetType().FullName;
            var error_bytes = System.Text.Encoding.UTF8.GetBytes(error_str);
            error.Write(error_bytes);
            return Errno.HOST_CALL_FAILURE;
        }

diff --git a/crates/bindings-csharp/Runtime/Runtime.csproj b/crates/bindings-csharp/Runtime/Runtime.csproj
@@ -12,6 +12,7 @@
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <RootNamespace>SpacetimeDB</RootNamespace>
     <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
+    <RestoreAdditionalProjectSources Condition="'$(EXPERIMENTAL_WASM_AOT)' == '1'">https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-experimental/nuget/v3/index.json;$(RestoreAdditionalProjectSources)</RestoreAdditionalProjectSources>
   </PropertyGroup>
 
   <ItemGroup>
@@ -25,6 +26,13 @@
     <ProjectReference Include="../Codegen/Codegen.csproj" ReferenceOutputAssembly="false" />
   </ItemGroup>
 
+  <!-- These must be explicit package dependencies so NuGet consumers can resolve the LLVM toolchain. -->
+  <ItemGroup Condition="'$(EXPERIMENTAL_WASM_AOT)' == '1'">
+    <PackageReference Include="Microsoft.DotNet.ILCompiler.LLVM" Version="8.0.0-*" IncludeAssets="All" />
+    <PackageReference Include="runtime.$(NETCoreSdkPortableRuntimeIdentifier).Microsoft.DotNet.ILCompiler.LLVM" Version="8.0.0-*" IncludeAssets="All" />
+    <PackageReference Include="Microsoft.NET.ILLink.Tasks" Version="8.0.0-*" Condition="'$(ILLinkTargetsPath)' == ''" IncludeAssets="All" />
+  </ItemGroup>
+
   <ItemGroup>
     <None Include="README.md" Pack="true" PackagePath="" />
     <None Include="build/*" Pack="true" PackagePath="build" />

diff --git a/crates/bindings-csharp/Runtime/build/SpacetimeDB.Runtime.targets b/crates/bindings-csharp/Runtime/build/SpacetimeDB.Runtime.targets
@@ -1,32 +1,50 @@
 <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
 
+  <Import
+      Project="$(PkgMicrosoft_DotNet_ILCompiler_LLVM)\build\Microsoft.DotNet.ILCompiler.LLVM.targets"
+      Condition="'$(EXPERIMENTAL_WASM_AOT)' == '1' and '$(ILCompilerTargetsPath)' == '' and '$(PkgMicrosoft_DotNet_ILCompiler_LLVM)' != '' and Exists('$(PkgMicrosoft_DotNet_ILCompiler_LLVM)\build\Microsoft.DotNet.ILCompiler.LLVM.targets')" />
+
   <ItemGroup Condition="'$(EXPERIMENTAL_WASM_AOT)' == '1'">
     <NativeLibrary Include="$(MSBuildThisFileDirectory)..\bindings.c" />
     <UnmanagedEntryPointsAssembly Include="SpacetimeDB.Runtime" />
 
-    <WasmImport Include="$(SpacetimeNamespace)!table_id_from_name" />
-    <WasmImport Include="$(SpacetimeNamespace)!index_id_from_name" />
-    <WasmImport Include="$(SpacetimeNamespace)!datastore_table_row_count" />
-    <WasmImport Include="$(SpacetimeNamespace)!datastore_table_scan_bsatn" />
-    <WasmImport Include="$(SpacetimeNamespace)!datastore_index_scan_range_bsatn" />
-    <WasmImport Include="$(SpacetimeNamespace)!datastore_btree_scan_bsatn" />
-    <WasmImport Include="$(SpacetimeNamespace)!row_iter_bsatn_advance" />
-    <WasmImport Include="$(SpacetimeNamespace)!row_iter_bsatn_close" />
-    <WasmImport Include="$(SpacetimeNamespace)!datastore_insert_bsatn" />
-    <WasmImport Include="$(SpacetimeNamespace)!datastore_delete_by_index_scan_range_bsatn" />
-    <WasmImport Include="$(SpacetimeNamespace)!datastore_delete_by_btree_scan_bsatn" />
-    <WasmImport Include="$(SpacetimeNamespace)!datastore_delete_all_by_eq_bsatn" />
-    <WasmImport Include="$(SpacetimeNamespace)!bytes_source_read" />
-    <WasmImport Include="$(SpacetimeNamespace)!bytes_sink_write" />
-    <WasmImport Include="$(SpacetimeNamespace)!console_log" />
-    <WasmImport Include="$(SpacetimeNamespace)!console_timer_start" />
-    <WasmImport Include="$(SpacetimeNamespace)!console_timer_end" />
-    <WasmImport Include="$(SpacetimeNamespace)!volatile_nonatomic_schedule_immediate" />
-    <WasmImport Include="$(SpacetimeNamespace)!datastore_clear" />
-
-    <PackageReference Include="Microsoft.DotNet.ILCompiler.LLVM" Version="8.0.0-*" />
-    <PackageReference Include="runtime.win-x64.Microsoft.DotNet.ILCompiler.LLVM" Version="8.0.0-*" />
-    <PackageReference Include="Microsoft.NET.ILLink.Tasks" Version="8.0.0-*" Condition="'$(ILLinkTargetsPath)' == ''" />
+    <!-- spacetime_10.0 imports -->
+    <WasmImport Include="spacetime_10.0!table_id_from_name" />
+    <WasmImport Include="spacetime_10.0!index_id_from_name" />
+    <WasmImport Include="spacetime_10.0!datastore_table_row_count" />
+    <WasmImport Include="spacetime_10.0!datastore_table_scan_bsatn" />
+    <WasmImport Include="spacetime_10.0!datastore_index_scan_range_bsatn" />
+    <WasmImport Include="spacetime_10.0!datastore_btree_scan_bsatn" />
+    <WasmImport Include="spacetime_10.0!row_iter_bsatn_advance" />
+    <WasmImport Include="spacetime_10.0!row_iter_bsatn_close" />
+    <WasmImport Include="spacetime_10.0!datastore_insert_bsatn" />
+    <WasmImport Include="spacetime_10.0!datastore_update_bsatn" />
+    <WasmImport Include="spacetime_10.0!datastore_delete_by_index_scan_range_bsatn" />
+    <WasmImport Include="spacetime_10.0!datastore_delete_by_btree_scan_bsatn" />
+    <WasmImport Include="spacetime_10.0!datastore_delete_all_by_eq_bsatn" />
+    <WasmImport Include="spacetime_10.0!bytes_source_read" />
+    <WasmImport Include="spacetime_10.0!bytes_sink_write" />
+    <WasmImport Include="spacetime_10.0!console_log" />
+    <WasmImport Include="spacetime_10.0!console_timer_start" />
+    <WasmImport Include="spacetime_10.0!console_timer_end" />
+    <WasmImport Include="spacetime_10.0!volatile_nonatomic_schedule_immediate" />
+    <WasmImport Include="spacetime_10.0!identity" />
+
+    <!-- spacetime_10.1 imports -->
+    <WasmImport Include="spacetime_10.1!bytes_source_remaining_length" />
+
+    <!-- spacetime_10.2 imports -->
+    <WasmImport Include="spacetime_10.2!get_jwt" />
+
+    <!-- spacetime_10.3 imports -->
+    <WasmImport Include="spacetime_10.3!procedure_start_mut_tx" />
+    <WasmImport Include="spacetime_10.3!procedure_commit_mut_tx" />
+    <WasmImport Include="spacetime_10.3!procedure_abort_mut_tx" />
+    <WasmImport Include="spacetime_10.3!procedure_http_request" />
+
+    <!-- spacetime_10.4 imports -->
+    <WasmImport Include="spacetime_10.4!datastore_index_scan_point_bsatn" />
+    <WasmImport Include="spacetime_10.4!datastore_delete_by_index_scan_point_bsatn" />
 
     <CustomLinkerArg Include="-DEXPERIMENTAL_WASM_AOT" />
   </ItemGroup>