libsql-search 0.9.0 → 0.9.1

package/README.md

@@ -26,11 +26,21 @@ npm install libsql-search @libsql/client
 ```
 
 ```bash
-deno add jsr:@logan/libsql-search npm:@libsql/client
+deno add jsr:@logan/libsql-search npm:@libsql/client@^0.17.0
 ```
 
 For npm usage, the package requires Node `>=22.12.0`.
 
+**On npm/pnpm**, the peer range is `@libsql/client ^0.15.0 || ^0.17.0`. Both lines are supported: every behavior this package depends on — `vector_top_k()`'s result shape, the vector index error wording that `search()` matches on, and transactional `batch()` rollback — is identical across them, so an existing `0.15.x` install does not have to move. There is no `0.16.x` line upstream, which is why the range is a disjunction rather than a span. The packaged build is smoke-tested against both arms on every release, at the newest release each arm admits (currently `0.15.15` and `0.17.4`).
+
+**On JSR/Deno the range does not apply to you.** `deno.json` declares no dependency on `@libsql/client` — this package imports only its *types* — so the client you `deno add` separately is constrained by nothing on our side, and a plain `deno add npm:@libsql/client` will silently take whatever is newest, including a future major we have never tested. Deno also cannot express our range: `npm:@libsql/client@^0.15.0 || ^0.17.0` is a parse error, as is any `>=`/`<` span. Pin an arm yourself instead:
+
+```bash
+deno add jsr:@logan/libsql-search npm:@libsql/client@^0.17.0
+```
+
+Note for `0.17.x`: the client no longer exports `./package.json`, so `require("@libsql/client/package.json")` throws `ERR_PACKAGE_PATH_NOT_EXPORTED`. Nothing in this package reads it, but tooling of yours that inspected the client manifest by specifier needs a direct `node_modules` path instead. See [`@libsql/client` version differences](./docs/TROUBLESHOOTING.md#libsqlclient-version-differences) for the other upgrade-visible change.
+
 ## Quick Start
 
 This example uses the default local provider. Local embeddings run in-process after the initial model download and cache warmup; they are not automatically air-gapped.
@@ -99,7 +109,7 @@ await search({ client, query, exact: true });
 
 `exact: true` is the only way to guarantee exactness. Use it for small corpora, for correctness checks against the index path, and for tables that have no vector index.
 
-Requirements: `vector_top_k()` and `libsql_vector_idx()` need a libSQL build with native vector support. The peer dependency is `@libsql/client ^0.15.0`, verified against `0.15.15`; remote Turso/libSQL servers must support vector indexes as well. See the [API reference](./docs/API.md#searchoptions) for full semantics, and [Indexing and operations](./docs/INDEXING.md) for tables created before the index existed.
+Requirements: `vector_top_k()` and `libsql_vector_idx()` need a libSQL build with native vector support. The peer dependency is `@libsql/client ^0.15.0 || ^0.17.0`, verified against `0.15.15` and `0.17.4`; remote Turso/libSQL servers must support vector indexes as well. See the [API reference](./docs/API.md#searchoptions) for full semantics, and [Indexing and operations](./docs/INDEXING.md) for tables created before the index existed.
 
 ## Providers
 

package/docs/API.md

@@ -256,7 +256,9 @@ Search never falls back to the exact scan on its own. A silent fallback would tu
 
 ### Requirements
 
-`vector_top_k()` and `libsql_vector_idx()` require a libSQL build with native vector support. The peer dependency is `@libsql/client ^0.15.0`; this behavior is verified against `@libsql/client` `0.15.15` with a local `:memory:` database. Remote Turso/libSQL servers must also support vector indexes — that is a property of the server, not the client, and no minimum server version is claimed here beyond that requirement. A deployment without it fails the default path with an error saying so and naming `exact: true` as the remedy. Use `exact: true` against any deployment where vector index support is unavailable or unverified.
+`vector_top_k()` and `libsql_vector_idx()` require a libSQL build with native vector support. The peer dependency is `@libsql/client ^0.15.0 || ^0.17.0`; this behavior is verified against `@libsql/client` `0.15.15` and `0.17.4` with a local `:memory:` database. On both, `vector_top_k()` returns the matched rowids in an `id` column, libSQL's missing-index wording ("failed to parse vector index parameters") is byte-identical, and so is the dimension-mismatch wording that is passed through unchanged — so the index path and the diagnostics above behave the same on either line. The two lines share one embedded engine (`libsql` `0.5.29`), which is why the on-disk format and index semantics do not differ between them.
+
+Coverage differs by layer, and is worth stating plainly: the packaged build is smoke-tested against **both** peer arms on every release, which covers table and vector-index creation. The full test suite — including the byte-exact assertions on the messages above — runs against the dev-pinned client, currently `0.17.4`. The no-vector-support case is the one message not reproducible against a local build on either version; it is asserted from a synthesized error rather than a measured one. Remote Turso/libSQL servers must also support vector indexes — that is a property of the server, not the client, and no minimum server version is claimed here beyond that requirement. A deployment without it fails the default path with an error saying so and naming `exact: true` as the remedy. Use `exact: true` against any deployment where vector index support is unavailable or unverified.
 
 Result shape:
 

package/docs/INDEXING.md

@@ -174,6 +174,6 @@ Many projects wire indexing into a dedicated script and call it before their sit
 ## Runtime Notes
 
 - local embeddings may download and cache a model on the first run
-- Node users need `@libsql/client` installed alongside the package
+- Node users need `@libsql/client` installed alongside the package, at `^0.15.0 || ^0.17.0`; the packaged build is smoke-tested against both arms (`0.15.15` and `0.17.4`), which covers table and vector-index creation. `batch()` rollback behaves identically on both at the contract level, though its error text differs — see [Version differences](./TROUBLESHOOTING.md#libsqlclient-version-differences). Upgrading the client is not a prerequisite for upgrading this package. Deno/JSR users are not covered by that range and should pin the client themselves — see [Install](../README.md#install)
 - hosted providers send indexed or queried text to external services
 - the repository validates package build and `deno check`, but indexing still depends on filesystem access

package/docs/MIGRATIONS.md

@@ -23,6 +23,7 @@ References:
 - if dimensions stay the same but provider, model, endpoint, model revision, pooling, normalization, or input formatting changes, fully reindex anyway
 - never mix two embedding spaces in one table
 - prefer a parallel table migration because `indexContent()` replaces the whole target table, so an in-place rebuild leaves no way back to the old vectors
+- upgrading `@libsql/client` is not one of these migrations. The client moves bytes; it does not define the embedding space. Moving between the supported `^0.15.0` and `^0.17.0` lines leaves stored vectors, table widths, and the embedding index untouched and needs no reindex. This is checkable rather than merely inferred: `libsql`, the embedded native engine that owns the on-disk `F32_BLOB` format and the vector index, resolves to `0.5.29` under both client lines — the client bump does not move it. See [`@libsql/client` version differences](./TROUBLESHOOTING.md#libsqlclient-version-differences) for the two client-side behaviors that do change.
 
 In practice, this means:
 

package/docs/TROUBLESHOOTING.md

@@ -38,3 +38,41 @@ Common operational checks:
   `createTable()`, `indexContent()`, and `search()`, and re-index if the stored
   vectors are in the wrong space; see the
   [Migration and reindexing guide](./MIGRATIONS.md)
+
+## `@libsql/client` Version Differences
+
+The peer range is `^0.15.0 || ^0.17.0`, verified against `0.15.15` and `0.17.4`.
+There is no `0.16.x` line upstream. Everything this package depends on behaves
+the same on both — `vector_top_k()` returns rowids in an `id` column, the
+missing-index message this library rewrites ("failed to parse vector index
+parameters") and the dimension-mismatch message it passes through unchanged are
+both byte-identical, and `batch(..., "write")` still rolls the whole rebuild back
+on failure — so upgrading the client is optional and neither direction requires
+re-indexing. (The third message, the no-vector-support case, is not reproducible
+against a local build on either version; see
+[Requirements](./API.md#requirements).)
+
+Two client-side differences are visible to callers on `0.17.x`:
+
+- the client no longer exports `./package.json`. Reading it by specifier, as in
+  `require("@libsql/client/package.json")`, throws
+  `ERR_PACKAGE_PATH_NOT_EXPORTED`. Nothing in this package does that; if your own
+  tooling did, read the file through a direct `node_modules` path instead
+- **constraint error codes lost the `_UNIQUE` suffix.** A duplicate slug that
+  reported `SQLITE_CONSTRAINT_UNIQUE` on `0.15.x` reports the broader
+  `SQLITE_CONSTRAINT` on `0.17.x`. This affects every caller on both query paths:
+
+  | | `0.15.15` | `0.17.4` |
+  | --- | --- | --- |
+  | `execute()` | `SQLITE_CONSTRAINT_UNIQUE: UNIQUE constraint failed: …` | `SQLITE_CONSTRAINT: UNIQUE constraint failed: …` |
+  | `batch(…, "write")` | `SQLITE_CONSTRAINT_UNIQUE: UNIQUE constraint failed: …` | `SQLITE_CONSTRAINT: SQLITE_CONSTRAINT: UNIQUE constraint failed: …` |
+
+  Note that the prefix is additionally **doubled on the `batch()` path only** —
+  that is the path `indexContent()` uses, so it is what surfaces as the `cause`
+  of an `IndexingError` with `phase: "replace"`. Your own `execute()` calls show
+  the single prefix. Both are cosmetic: the rollback and the `IndexingError`
+  contract are unchanged.
+
+  A log matcher or alert rule keyed on `SQLITE_CONSTRAINT_UNIQUE` will stop
+  matching after the upgrade, on either path. Match on `UNIQUE constraint failed`
+  instead — it is the one substring stable across all four cells above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libsql-search",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Semantic search for static sites using libSQL/Turso with multi-provider embeddings",
   "type": "module",
   "packageManager": "pnpm@10.34.5",
@@ -60,14 +60,14 @@
     "node": ">=22.12.0"
   },
   "peerDependencies": {
-    "@libsql/client": "^0.15.0"
+    "@libsql/client": "^0.15.0 || ^0.17.0"
   },
   "dependencies": {
     "@huggingface/transformers": "4.2.0",
     "gray-matter": "^4.0.3"
   },
   "devDependencies": {
-    "@libsql/client": "^0.15.15",
+    "@libsql/client": "^0.17.4",
     "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@types/node": "^24.13.3",