@an5/adapters 0.2.11 → 0.2.14

package/kotlin/src/test/kotlin/an5/adapters/An5Smoke.kt

@@ -0,0 +1,329 @@
+package an5.adapters
+
+/**
+ * End-to-end exercise of the Kotlin runtime against a real in-memory SQLite database.
+ *
+ * Covers what a Java-only check cannot: that Kotlin's read-only maps reach the JDBC layer,
+ * that the query block builds the filter the other adapters build, and that a column read
+ * as `Long` from SQLite comes out of the typed accessors as `Int` without a cast at the
+ * call site.
+ */
+object An5Smoke {
+
+    private var failures = 0
+
+    @JvmStatic
+    fun main(args: Array<String>) {
+        crud()
+        filters()
+        aggregates()
+        relations()
+        transactions()
+        vectorFallback()
+        sqliteVectorSearch()
+
+        if (failures > 0) {
+            println("kotlin smoke: $failures check(s) failed")
+            kotlin.system.exitProcess(1)
+        }
+        println("kotlin smoke: all checks passed")
+    }
+
+    private fun crud() {
+        val db = open()
+        db.use {
+            val users = it.table("User")
+            val created = users.create(mapOf("name" to "Ada", "score" to 10))
+            check("generated primary key") { created.string("id") != null }
+            check("create returns the stored row") { created.string("name") == "Ada" }
+            check("row accessors read a column") { created.int("score") == 10 }
+            check("row accessors widen a number") { created.long("score") == 10L }
+            check("missing column reads as the fallback") { created.int("nope", -1) == -1 }
+            check("null column reads as the fallback") { created.string("nope") == null }
+
+            users.create(mapOf("name" to "Grace", "score" to 20))
+            users.create(mapOf("name" to "Alan", "score" to 30))
+
+            check("count") { users.count() == 3L }
+            check("ordered results") { users.findMany { orderBy("score", Sort.DESC) }.first().string("name") == "Alan" }
+            check("paged results") {
+                users.findMany { orderBy("score"); skip(1); take(1) }.single().string("name") == "Grace"
+            }
+            check("select projects columns") {
+                users.findMany { select("name") }.all { it.keys == setOf("name") }
+            }
+            check("update") {
+                users.update(mapOf("id" to created.string("id")), mapOf("score" to 99))?.int("score") == 99
+            }
+            check("updateMany") {
+                users.updateMany(null, mapOf("score" to mapOf("increment" to 1))) == 3
+            }
+            check("upsert updates") {
+                users.upsert(mapOf("id" to created.string("id")), mapOf("name" to "x"), mapOf("name" to "Ada L"))
+                    .string("name") == "Ada L"
+            }
+            check("upsert creates") {
+                users.upsert(mapOf("name" to "Katherine"), mapOf("name" to "Katherine"), mapOf("name" to "K"))
+                    .string("name") == "Katherine"
+            }
+            check("delete") { users.delete(mapOf("id" to created.string("id"))) != null }
+            check("deleteMany") { users.deleteMany(null) == 3 }
+        }
+    }
+
+    private fun filters() {
+        val db = open()
+        db.use {
+            val users = it.table("User")
+            users.createMany(
+                listOf(
+                    mapOf("name" to "Ada", "score" to 10),
+                    mapOf("name" to "Grace", "score" to 20),
+                    mapOf("name" to "Alan", "score" to 30),
+                )
+            )
+            check("gte") { users.findMany { where("score" gte 20) }.size == 2 }
+            check("lt") { users.findMany { where("score" lt 20) }.size == 1 }
+            check("eq") { users.findMany { where("name" eq "Ada") }.size == 1 }
+            check("neq") { users.findMany { where("name" neq "Ada") }.size == 2 }
+            check("contains") { users.findMany { where("name" contains "da") }.size == 1 }
+            check("endsWith") { users.findMany { where("name" endsWith "ce") }.size == 1 }
+            check("inList") { users.findMany { where("name" inList listOf("Ada", "Alan")) }.size == 2 }
+            check("empty inList matches nothing") {
+                users.findMany { where("name" inList emptyList<String>()) }.isEmpty()
+            }
+            check("empty notInList matches everything") {
+                users.findMany { where("name" notInList emptyList<String>()) }.size == 3
+            }
+            check("orOf") { users.findMany { where(orOf("name" eq "Ada", "name" eq "Alan")) }.size == 2 }
+            check("andOf") { users.findMany { where(andOf("score" gte 10, "score" lt 30)) }.size == 2 }
+            check("notOf") { users.findMany { where(notOf("name" eq "Ada", "name" eq "Grace")) }.size == 1 }
+            check("empty orOf matches nothing") { users.findMany { where(orOf()) }.isEmpty() }
+            check("two where calls combine with AND") {
+                users.findMany { where("score" gte 10); where("score" lte 20) }.size == 2
+            }
+            check("isNull") { users.findMany { where("nickname".isNull()) }.size == 3 }
+            check("isNotNull") { users.findMany { where("name".isNotNull()) }.size == 3 }
+            check("findFirst") { users.findFirst(mapOf("name" to "Ada"))?.int("score") == 10 }
+            check("findFirst misses") { users.findFirst(mapOf("name" to "Nobody")) == null }
+        }
+    }
+
+    private fun aggregates() {
+        val db = open()
+        db.use {
+            val users = it.table("User")
+            users.createMany(
+                listOf(
+                    mapOf("name" to "Ada", "score" to 10),
+                    mapOf("name" to "Grace", "score" to 20),
+                    mapOf("name" to "Alan", "score" to 30),
+                )
+            )
+            val totals = users.aggregate { count(); sum("score"); avg("score"); max("score") }
+            check("aggregate count") { (totals["_count"] as Number).toLong() == 3L }
+            check("aggregate sum") { (totals["_sum_score"] as Number).toDouble() == 60.0 }
+            check("aggregate avg") { (totals["_avg_score"] as Number).toDouble() == 20.0 }
+            check("aggregate max") { (totals["_max_score"] as Number).toDouble() == 30.0 }
+
+            val filtered = users.aggregate { count(); where("score" gte 20) }
+            check("aggregate where") { (filtered["_count"] as Number).toLong() == 2L }
+
+            val groups = users.groupBy("name") { sum("score") }
+            check("groupBy rows") { groups.size == 3 }
+            check("groupBy counts") { groups.all { (it["_count"] as Number).toLong() == 1L } }
+        }
+    }
+
+    private fun relations() {
+        val db = open()
+        db.use {
+            val ada = it.table("User").create(mapOf("name" to "Ada", "score" to 1))
+            it.table("Post").create(mapOf("title" to "first", "userId" to ada.string("id")))
+            it.table("Post").create(mapOf("title" to "second", "userId" to ada.string("id")))
+
+            val rows = it.table("User").findMany {
+                include(mapOf("posts" to true, "_count" to true))
+            }
+            check("many relation eager-loaded") { rows.single().related("posts").size == 2 }
+            check("relation count eager-loaded") { rows.single().relationCount("posts") == 2 }
+            check("related rows are readable") {
+                rows.single().related("posts").first().string("title") == "first"
+            }
+            check("missing relation reads as empty") { rows.single().related("comments").isEmpty() }
+            check("missing relation count reads as zero") { rows.single().relationCount("comments") == 0 }
+        }
+    }
+
+    private fun transactions() {
+        val db = open()
+        db.use {
+            it.table("User").create(mapOf("name" to "outside"))
+            val failed = runCatching {
+                it.transaction { scoped ->
+                    scoped.table("User").create(mapOf("name" to "inside"))
+                    error("rollback")
+                }
+            }
+            check("transaction rethrows") { failed.isFailure && failed.exceptionOrNull()?.message == "rollback" }
+            check("rollback discarded the inner insert") { it.table("User").count() == 1L }
+
+            it.transaction { scoped -> scoped.table("User").create(mapOf("name" to "committed")) }
+            check("commit kept the insert") { it.table("User").count() == 2L }
+        }
+    }
+
+    private fun vectorFallback() {
+        val db = open()
+        db.use {
+            val docs = it.table("Document")
+            docs.create(mapOf("title" to "far", "embedding" to "[0.0, 1.0]"))
+            docs.create(mapOf("title" to "near", "embedding" to "[1.0, 0.1]"))
+            docs.create(mapOf("title" to "no vector", "embedding" to null))
+
+            val hits = docs.vectorSearch(doubleArrayOf(1.0, 0.0), take = 2)
+            check("rows without a vector are skipped") { hits.size == 2 }
+            check("nearest first") { hits.first().string("title") == "near" }
+            check("distance reported") { hits.first().containsKey("distance") }
+        }
+    }
+
+    /**
+     * SQLite ranks a `VECTOR(n)` column inside the database, and a `DoubleArray` written
+     * to one comes back as numbers.
+     *
+     * The docstring in the JVM adapter's `SqliteVectors` is the shared specification every
+     * runtime implements; test/sqlite-vector.test.js (TypeScript) is the mirror.
+     */
+    private fun sqliteVectorSearch() {
+        an5.adapters.base.Metadata.setAdapterMetadata(blobMetadata())
+        val db = An5(":memory:")
+        db.use {
+            it.executeRaw("CREATE TABLE documents (id TEXT PRIMARY KEY, title TEXT, embedding BLOB)")
+            val vectors = listOf(
+                "d1" to doubleArrayOf(1.0, 0.0, 0.0),
+                "d2" to doubleArrayOf(0.8, 0.2, 0.0),
+                "d3" to doubleArrayOf(0.0, 1.0, 0.0),
+            )
+            for ((id, vector) in vectors) {
+                it.executeRaw(
+                    "INSERT INTO documents (id, title, embedding) VALUES (?, ?, ?)",
+                    id, id, an5.adapters.base.SqliteVectors.encodeVector(vector),
+                )
+            }
+            // A row with another dimension must never rank against a 3-dimension query.
+            it.executeRaw(
+                "INSERT INTO documents (id, title, embedding) VALUES ('d4', 'd4', ?)",
+                an5.adapters.base.SqliteVectors.encodeVector(doubleArrayOf(1.0, 0.0, 0.0, 1.0)),
+            )
+
+            val docs = it.table("Document")
+            for (metric in DistanceMetric.entries) {
+                val hits = docs.vectorSearch(doubleArrayOf(1.0, 0.0, 0.0), take = 9, metric = metric)
+                check("${metric.sql}: row order") { hits.joinToString(",") { row -> row.string("title").orEmpty() } == "d1,d2,d3" }
+                check("${metric.sql}: the distance is a number") { hits.first()["distance"] is Double }
+                check("${metric.sql}: the vector decodes to numbers") { hits.first()["embedding"] is DoubleArray }
+            }
+
+            // `memory` pins the client-side fallback, which ranks the same rows.
+            it.vectorStrategy("memory")
+            val pinned = docs.vectorSearch(doubleArrayOf(1.0, 0.0, 0.0), take = 9)
+            check("the memory fallback ranks correctly") {
+                pinned.joinToString(",") { row -> row.string("title").orEmpty() } == "d1,d2,d3"
+            }
+
+            it.vectorStrategy(null)
+            val written = docs.create(
+                mapOf("id" to "d9", "title" to "written", "embedding" to doubleArrayOf(0.25, 0.5, 1.0)),
+            )
+            check("create writes a float32 BLOB") {
+                it.queryRaw("SELECT typeof(embedding) AS t FROM documents WHERE id = 'd9'")
+                    .first().string("t") == "blob"
+            }
+            check("create returns numbers") { written["embedding"] is DoubleArray }
+            check("findMany returns numbers") {
+                docs.findMany(where = mapOf("id" to "d9")).first()["embedding"] is DoubleArray
+            }
+            docs.update(mapOf("id" to "d1"), mapOf("embedding" to doubleArrayOf(0.5, 0.5, 0.0)))
+            check("update encodes") {
+                docs.findMany(where = mapOf("id" to "d1")).first()["embedding"] is DoubleArray
+            }
+            docs.updateMany(mapOf("id" to "d2"), mapOf("embedding" to doubleArrayOf(0.0, 0.0, 1.0)))
+            check("updateMany encodes") {
+                docs.findMany(where = mapOf("id" to "d2")).first()["embedding"] is DoubleArray
+            }
+        }
+    }
+
+    private fun blobMetadata(): MutableMap<String, Any?> {
+        val metadata = metadata()
+        @Suppress("UNCHECKED_CAST")
+        val fields = metadata["modelFields"] as MutableMap<String, Any?>
+        fields["Document"] = listOf(
+            field("id", true),
+            field("title", false),
+            mutableMapOf<String, Any?>(
+                "name" to "embedding",
+                "type" to "number[] | string",
+                "sql" to "VECTOR(3)",
+                "isOptional" to true,
+                "hasDefault" to false,
+                "isId" to false,
+            ),
+        )
+        return metadata
+    }
+
+    // ─── Harness ──────────────────────────────────────────────────────────────────
+
+    private fun open(): An5 {
+        an5.adapters.base.Metadata.setAdapterMetadata(metadata())
+        val db = An5(":memory:")
+        db.executeRaw("CREATE TABLE users (id TEXT PRIMARY KEY, name TEXT, score INTEGER, nickname TEXT)")
+        db.executeRaw("CREATE TABLE documents (id TEXT PRIMARY KEY, title TEXT, embedding TEXT)")
+        db.executeRaw("CREATE TABLE posts (id TEXT PRIMARY KEY, title TEXT, userId TEXT)")
+        return db
+    }
+
+    private fun metadata(): MutableMap<String, Any?> {
+        val posts = mutableMapOf<String, Any?>(
+            "modelName" to "Post",
+            "relationType" to "many",
+            "foreignKey" to "userId",
+            "localKey" to "id",
+        )
+        return mutableMapOf(
+            "modelToTable" to mutableMapOf(
+                "User" to "users",
+                "Post" to "posts",
+                "Document" to "documents",
+            ),
+            "modelFields" to mutableMapOf(
+                "User" to listOf(field("id", true), field("name", false), field("score", false)),
+                "Post" to listOf(field("id", true), field("title", false), field("userId", false)),
+                "Document" to listOf(field("id", true), field("title", false), field("embedding", false)),
+            ),
+            "relationMap" to mutableMapOf("User" to mutableMapOf("posts" to posts)),
+        )
+    }
+
+    private fun field(name: String, id: Boolean): MutableMap<String, Any?> = mutableMapOf(
+        "name" to name,
+        "type" to "string",
+        "sql" to "NVARCHAR(255)",
+        "isOptional" to false,
+        "hasDefault" to false,
+        "isId" to id,
+    )
+
+    private fun check(what: String, assertion: () -> Boolean) {
+        val outcome = runCatching(assertion)
+        when {
+            outcome.isSuccess && outcome.getOrNull() == true -> println("ok   $what")
+            else -> {
+                failures++
+                println("FAIL $what: ${outcome.exceptionOrNull()?.message ?: "assertion returned false"}")
+            }
+        }
+    }
+}

package/native/sqlite/CMakeLists.txt

@@ -0,0 +1,12 @@
+cmake_minimum_required(VERSION 3.16)
+project(an5_vector LANGUAGES C)
+find_path(SQLITE_INCLUDE_DIR sqlite3ext.h REQUIRED)
+add_library(an5_vector MODULE an5_vector.c)
+target_include_directories(an5_vector PRIVATE "${SQLITE_INCLUDE_DIR}")
+set_target_properties(an5_vector PROPERTIES PREFIX "" C_STANDARD 99)
+if(MSVC)
+  target_compile_options(an5_vector PRIVATE /O2 /W4)
+else()
+  target_compile_options(an5_vector PRIVATE -O3 -Wall -Wextra -Werror)
+  target_link_libraries(an5_vector PRIVATE m)
+endif()

package/native/sqlite/README.md

@@ -0,0 +1,117 @@
+# AN5 native SQLite vectors
+
+`an5_vector.c` is a loadable SQLite extension, not a language-driver callback.
+It implements all three AN5 metrics in C:
+
+| SQL function | Result (smaller is closer) |
+|---|---|
+| `an5_vec_cosine(left, right)` | `1 - cosine_similarity` |
+| `an5_vec_l2(left, right)` | Euclidean distance |
+| `an5_vec_ip(left, right)` | Negative dot product |
+| `an5_vector_version()` | Extension identifier |
+
+BLOB inputs are little-endian float32. JSON text arrays are also accepted and
+converted to float32, so native results have single-precision input values even
+for legacy text columns. Empty, malformed, non-finite and dimension-mismatched
+inputs return SQL NULL. Zero vectors have cosine distance 1.
+
+The BLOB path reads the stored bytes directly without allocating a row vector.
+The query operand is cached using SQLite auxdata for the statement. x86-64 uses
+SSE2 with double-precision accumulators; other architectures use the portable C
+loop. No `-march=native`, AVX dependency or fast-math flags are required.
+
+This is **exact scanning**, not an ANN index. A normal relational index on a
+filter column can narrow the candidates before distance calculation. Only the
+top results are returned to the language runtime.
+
+## Build
+
+In this workspace:
+
+```sh
+npm run build:sqlite:native -w an5Adapters
+```
+
+The command prints the absolute library path under `native/sqlite/build`.
+Linux/macOS need a C compiler and `sqlite3ext.h`; on Debian/Ubuntu install
+`build-essential` and `libsqlite3-dev`. `CC` and `SQLITE_INCLUDE_DIR` may be set
+when using a different compiler or header directory.
+
+For an installed npm package:
+
+```sh
+node node_modules/@an5/adapters/scripts/sqlite-native-build.js ./native-build
+```
+
+Windows builds through CMake and an installed C toolchain. The CMake project can
+also be used directly on other platforms:
+
+```sh
+cmake -S native/sqlite -B native/sqlite/build -DCMAKE_BUILD_TYPE=Release
+cmake --build native/sqlite/build --config Release
+```
+
+Build for the target OS and architecture. No precompiled binary is downloaded
+or compiled during the package's ordinary install.
+
+## Load
+
+The existing extension-path option accepts either sqlite-vec or this library:
+
+```typescript
+const db = createAn5Adapter({
+  connectionString: 'sqlite:///app.db',
+  sqliteVec: '/absolute/path/an5_vector.so', // .dylib / .dll on other platforms
+});
+await db.document.vectorSearch({ vector: query, take: 10 });
+```
+
+```python
+db = create_an5_adapter('sqlite:///app.db', sqlite_vec='/absolute/path/an5_vector.so')
+```
+
+```csharp
+var db = new An5Adapter(new An5AdapterOptions {
+    ConnectionString = "app.db",
+    SqliteVec = "/absolute/path/an5_vector.so"
+});
+```
+
+TypeScript, Python, .NET and Swift recognize `an5_vector_version()` before
+registering callbacks, preserving the native functions. In the existing strategy
+API this uses `udf`; **the functions execute in C**, not in the host language.
+On runtimes that take an existing connection/pool, load the extension on every
+SQLite connection through the driver's extension-loading API. Go, Rust and JDBC
+then discover the `an5_vec_*` functions through their existing probes. Swift's
+loading hook is desktop-only; mobile platforms need a statically linked SQLite
+extension/build supplied by the application.
+
+Each gate builds the extension itself and checks that the native functions are
+still the ones answering: `test:sqlite:native` covers TypeScript, Python and
+(optionally) .NET, while `test:swift` builds the extension and runs the same
+check through the Swift driver.
+
+## Verify and benchmark
+
+```sh
+npm run test:sqlite:native -w an5Adapters
+node an5Adapters/scripts/sqlite-native-test.js --dotnet
+AN5_NATIVE_SANITIZE=1 npm run test:sqlite:native -w an5Adapters
+npm run bench:sqlite:native -w an5Adapters
+```
+
+The native test compiles into a disposable directory, tests the extension with
+real SQLite, checks all metrics against the reference implementation, and verifies
+that TypeScript and Python keep the C functions. `--dotnet` additionally tests
+.NET. The sanitizer option enables UBSan on supporting Unix compilers.
+
+`npm run test:swift -w an5Adapters` builds the extension too and asserts the
+Swift driver keeps it; that case is skipped when `AN5_NATIVE_VECTOR_PATH` is
+unset, as on a machine without a C compiler.
+
+The benchmark compares the public adapter's native and JavaScript-UDF paths with
+identical BLOB data and verifies equal top-10 IDs. It reports the median of seven
+warmed runs over 4,000 vectors of 256 dimensions. On the development Linux x86-64
+machine the native path measured about 4 ms per search versus 15–18 ms for the
+JavaScript callback (roughly 4x faster). Timings are illustrative, not pass/fail
+thresholds or a performance guarantee.

package/native/sqlite/an5_vector.c

@@ -0,0 +1,209 @@
+/* Portable SQLite extension for float32 vector distances. No driver callbacks.
+ * BLOB inputs are little-endian float32; JSON arrays remain readable.
+ * Query vectors use SQLite auxdata so parsing/copying happens once per statement.
+ */
+#include <sqlite3ext.h>
+SQLITE_EXTENSION_INIT1
+#include <math.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+#if defined(__SSE2__)
+#include <emmintrin.h>
+#endif
+
+typedef struct {
+  const unsigned char *bytes;
+  float *owned;
+  int count;
+} Vector;
+
+static void release_vector(void *ptr) {
+  Vector *v = (Vector *)ptr;
+  if (v) { sqlite3_free(v->owned); sqlite3_free(v); }
+}
+
+static int whitespace(unsigned char c) {
+  return c == ' ' || c == '\t' || c == '\r' || c == '\n';
+}
+
+/* Validate JSON number grammar before using strtod, which otherwise accepts
+ * non-JSON spellings such as NaN, Infinity and hexadecimal numbers. */
+static const unsigned char *number_end(const unsigned char *p, const unsigned char *end) {
+  if (p < end && *p == '-') ++p;
+  if (p == end) return NULL;
+  if (*p == '0') ++p;
+  else {
+    if (*p < '1' || *p > '9') return NULL;
+    do { ++p; } while (p < end && *p >= '0' && *p <= '9');
+  }
+  if (p < end && *p == '.') {
+    ++p;
+    if (p == end || *p < '0' || *p > '9') return NULL;
+    do { ++p; } while (p < end && *p >= '0' && *p <= '9');
+  }
+  if (p < end && (*p == 'e' || *p == 'E')) {
+    ++p;
+    if (p < end && (*p == '+' || *p == '-')) ++p;
+    if (p == end || *p < '0' || *p > '9') return NULL;
+    do { ++p; } while (p < end && *p >= '0' && *p <= '9');
+  }
+  return p;
+}
+
+/* 1 = vector, 0 = invalid input, -1 = allocation failure. */
+static int read_vector(sqlite3_value *arg, Vector *v, int copy_blob) {
+  memset(v, 0, sizeof(*v));
+  if (sqlite3_value_type(arg) == SQLITE_BLOB) {
+    int size = sqlite3_value_bytes(arg);
+    if (!size || size % 4) return 0;
+    v->count = size / 4;
+    v->bytes = sqlite3_value_blob(arg);
+    if (!v->bytes) return -1;
+    if (copy_blob) {
+      v->owned = sqlite3_malloc64((sqlite3_uint64)size);
+      if (!v->owned) return -1;
+      memcpy(v->owned, v->bytes, (size_t)size);
+      v->bytes = (const unsigned char *)v->owned;
+    }
+    return 1;
+  }
+  if (sqlite3_value_type(arg) != SQLITE_TEXT) return 0;
+  const unsigned char *p = sqlite3_value_text(arg);
+  if (!p) return -1;
+  const unsigned char *end = p + sqlite3_value_bytes(arg);
+  while (p < end && whitespace(*p)) ++p;
+  if (p == end || *p++ != '[') return 0;
+  int capacity = 0;
+  for (;;) {
+    while (p < end && whitespace(*p)) ++p;
+    const unsigned char *next = number_end(p, end);
+    if (!next) goto invalid;
+    char *parsed;
+    double n = strtod((const char *)p, &parsed);
+    if ((const unsigned char *)parsed != next || !isfinite(n) || !isfinite((float)n)) goto invalid;
+    if (v->count == capacity) {
+      if (capacity > 0x3fffffff) goto invalid;
+      capacity = capacity ? capacity * 2 : 32;
+      float *grown = sqlite3_realloc64(v->owned, (sqlite3_uint64)capacity * sizeof(float));
+      if (!grown) { sqlite3_free(v->owned); v->owned = NULL; return -1; }
+      v->owned = grown;
+    }
+    v->owned[v->count++] = (float)n;
+    p = next;
+    while (p < end && whitespace(*p)) ++p;
+    if (p == end) goto invalid;
+    if (*p == ']') { ++p; break; }
+    if (*p++ != ',') goto invalid;
+  }
+  while (p < end && whitespace(*p)) ++p;
+  if (p != end) goto invalid;
+  return 1;
+invalid:
+  sqlite3_free(v->owned);
+  v->owned = NULL;
+  return 0;
+}
+
+static float element(const Vector *v, int i) {
+  if (!v->bytes) return v->owned[i];
+  const unsigned char *p = v->bytes + (size_t)i * 4;
+  uint32_t bits = (uint32_t)p[0] | ((uint32_t)p[1] << 8) |
+      ((uint32_t)p[2] << 16) | ((uint32_t)p[3] << 24);
+  float value;
+  memcpy(&value, &bits, sizeof(value));
+  return value;
+}
+
+static int score(const Vector *a, const Vector *b, int metric, double *out) {
+  if (!a->count || a->count != b->count) return 0;
+  double dot = 0, norm_a = 0, norm_b = 0, squared = 0;
+  int i = 0;
+#if defined(__SSE2__)
+  /* SSE2 is baseline on x86-64. Accumulate pairs in double precision; element()
+   * handles unaligned BLOB bytes and little-endian decoding before packing. */
+  if (a->bytes && b->bytes) {
+    __m128d d = _mm_setzero_pd(), na = d, nb = d, sq = d;
+    for (; i + 1 < a->count; i += 2) {
+      float af[2] = { element(a, i), element(a, i + 1) };
+      float bf[2] = { element(b, i), element(b, i + 1) };
+      if (!isfinite(af[0]) || !isfinite(af[1]) || !isfinite(bf[0]) || !isfinite(bf[1])) return 0;
+      __m128d av = _mm_set_pd(af[1], af[0]), bv = _mm_set_pd(bf[1], bf[0]);
+      if (metric == 1) {
+        __m128d delta = _mm_sub_pd(av, bv);
+        sq = _mm_add_pd(sq, _mm_mul_pd(delta, delta));
+      } else {
+        d = _mm_add_pd(d, _mm_mul_pd(av, bv));
+        if (metric == 0) {
+          na = _mm_add_pd(na, _mm_mul_pd(av, av));
+          nb = _mm_add_pd(nb, _mm_mul_pd(bv, bv));
+        }
+      }
+    }
+    double lanes[2];
+    _mm_storeu_pd(lanes, d); dot = lanes[0] + lanes[1];
+    _mm_storeu_pd(lanes, na); norm_a = lanes[0] + lanes[1];
+    _mm_storeu_pd(lanes, nb); norm_b = lanes[0] + lanes[1];
+    _mm_storeu_pd(lanes, sq); squared = lanes[0] + lanes[1];
+  }
+#endif
+  for (; i < a->count; ++i) {
+    double av = element(a, i), bv = element(b, i);
+    if (!isfinite(av) || !isfinite(bv)) return 0;
+    if (metric == 1) { double delta = av - bv; squared += delta * delta; }
+    else {
+      dot += av * bv;
+      if (metric == 0) { norm_a += av * av; norm_b += bv * bv; }
+    }
+  }
+  *out = metric == 1 ? sqrt(squared) : metric == 2 ? -dot :
+      norm_a && norm_b ? 1.0 - dot / (sqrt(norm_a) * sqrt(norm_b)) : 1.0;
+  return 1;
+}
+
+static void distance(sqlite3_context *ctx, int argc, sqlite3_value **argv) {
+  (void)argc;
+  Vector left;
+  int status = read_vector(argv[0], &left, 0);
+  if (status != 1) { if (status < 0) sqlite3_result_error_nomem(ctx); return; }
+  Vector *right = sqlite3_get_auxdata(ctx, 1);
+  int fresh = !right;
+  if (fresh) {
+    right = sqlite3_malloc64(sizeof(*right));
+    if (!right) { sqlite3_free(left.owned); sqlite3_result_error_nomem(ctx); return; }
+    status = read_vector(argv[1], right, 1);
+    if (status != 1) {
+      release_vector(right); sqlite3_free(left.owned);
+      if (status < 0) sqlite3_result_error_nomem(ctx);
+      return;
+    }
+  }
+  double value;
+  if (score(&left, right, (int)(intptr_t)sqlite3_user_data(ctx), &value)) sqlite3_result_double(ctx, value);
+  sqlite3_free(left.owned);
+  /* set_auxdata may immediately destroy the value: nothing accesses it after this. */
+  if (fresh) sqlite3_set_auxdata(ctx, 1, right, release_vector);
+}
+
+static void version(sqlite3_context *ctx, int argc, sqlite3_value **argv) {
+  (void)argc; (void)argv;
+  sqlite3_result_text(ctx, "an5-vector/1", -1, SQLITE_STATIC);
+}
+
+#ifdef _WIN32
+__declspec(dllexport)
+#endif
+int sqlite3_extension_init(sqlite3 *db, char **error, const sqlite3_api_routines *api) {
+  (void)error;
+  SQLITE_EXTENSION_INIT2(api);
+  const char *names[] = { "an5_vec_cosine", "an5_vec_l2", "an5_vec_ip" };
+  int flags = SQLITE_UTF8 | SQLITE_DETERMINISTIC;
+#ifdef SQLITE_INNOCUOUS
+  flags |= SQLITE_INNOCUOUS;
+#endif
+  for (int i = 0; i < 3; ++i) {
+    int rc = sqlite3_create_function_v2(db, names[i], 2, flags, (void *)(intptr_t)i, distance, NULL, NULL, NULL);
+    if (rc != SQLITE_OK) return rc;
+  }
+  return sqlite3_create_function_v2(db, "an5_vector_version", 0, flags, NULL, version, NULL, NULL, NULL);
+}