@fgv/ts-agent-memory-sqlite-vec 5.1.0-50 → 5.1.0-52

package/README.md

@@ -25,6 +25,31 @@ rush add -p @fgv/ts-agent-memory-sqlite-vec   # or npm/pnpm add
 
 ## Quick start
 
+Two factories, differing only in **who owns the connection**. If this index is the only
+thing on the file, `open` is the shorter path and needs no `better-sqlite3` import of
+your own:
+
+```ts
+import { SqliteVecVectorIndex } from '@fgv/ts-agent-memory-sqlite-vec';
+import { FileTreeMemoryStore } from '@fgv/ts-agent-memory';
+
+// We open the file and hand back a disposer for the connection we created.
+const handle = (await SqliteVecVectorIndex.open({ path: '/path/to/vault/vectors.db' })).orThrow();
+
+const store = (
+  await FileTreeMemoryStore.create({ root, registry, vectorIndex: handle.index, embed })
+).orThrow();
+
+// ...use the store; embeddings are written to vectors.db on every put.
+handle.close(); // closes the connection THIS open() created; idempotent.
+```
+
+`SqliteVecFragmentIndex.open({ path })` is the identical shape for the fragment lane.
+
+**Two `open` calls on one path give two independent connections, not a shared one.** To
+back a record index *and* a fragment index with a single connection, own it yourself and
+pass it to both `create` methods:
+
 ```ts
 import Database from 'better-sqlite3';
 import { SqliteVecVectorIndex } from '@fgv/ts-agent-memory-sqlite-vec';
@@ -42,9 +67,32 @@ const store = (
 ).orThrow();
 
 // ...use the store; embeddings are written to vectors.db on every put.
+vectorIndex.release(); // drop this index's prepared statements — see below
 db.close(); // you own the lifecycle — this index never closes your connection.
 ```
 
+### Releasing an index over a connection you own
+
+An index caches prepared `Statement` objects. Those hold a reference to the
+connection, so if you close a connection you own while an index over it is still
+reachable, its statements outlive the connection and their native destructors run
+whenever GC reaches them — potentially during process teardown.
+
+**`release()` drops those statements and marks the index unusable. It never touches
+the connection**, which is why it is safe to expose on a `create()`-made index that
+does not own one. `open()`'s handle calls it for you before closing; with `create()`
+you own the ordering, and it is `release()` then `close()`.
+
+A released index **fails** (or, for the synchronous counts `size` / `recordCount` /
+`fragmentCount`, **throws**) rather than answering. That is deliberate: an index that
+has simply never had an `add` also holds no statements, and answering `0` from a
+released one would be indistinguishable from an empty one.
+
+Note the limit honestly: `better-sqlite3` exposes no public `finalize()`, so dropping
+the last reference does not finalize a statement — it makes it collectable *earlier*,
+while the environment is alive, instead of surviving to teardown. That narrows the
+window; it is not a proof against it.
+
 `SqliteVecVectorIndex` implements the full `IVectorIndex` contract — `add(target, vector)`, `remove(target)`, `query(vector, topK)` — with the **same semantics as `InMemoryCosineIndex`**:
 
 - Keyed by the canonical `edgeTargetKey` (`(scope, id)`), so records that share a filename stem across scopes never collide.
@@ -108,7 +156,7 @@ Known instance: the release that added `IEmbeddedFragment.fragmentId` added a `+
 Deliberately excluded — reach for the upstream libraries (or a different backend) directly if you need these:
 
 - **ANN / large-N indexing.** Query is a brute-force `vec0` KNN scan — correct and durable for the same "thousands of records" regime the in-memory index targets. An approximate-nearest-neighbor structure for very large N is a different backend behind the same `IVectorIndex` / `IFragmentVectorIndex` seam. (This applies to both indexes, including `SqliteVecFragmentIndex`, whose capped query fetches the full ranked set.)
-- **Connection lifecycle.** You open and close the `better-sqlite3` `Database`; this index never does. Pooling, WAL/pragma tuning, backups, and multi-process coordination are yours.
+- **Connection lifecycle beyond plain open/close.** With `create({ database })` you open and close the `better-sqlite3` `Database` and this index never does; with `open({ path })` this package opens the file and the returned handle's `close()` disposes of exactly what it opened. Either way, pooling, WAL/pragma tuning, backups, and multi-process coordination are yours.
 - **Embedding.** This is a vector *index*, not an embedder — the store's consumer-wired `MemoryEmbedder` produces the vectors (`@fgv/ts-extras/ai-assist` `callProviderEmbedding`, `@fgv/ts-extras-transformers`, etc.).
 - **A browser sibling.** `better-sqlite3` is Node-only. A WASM-SQLite browser variant, if ever needed, is a separate package.
 - **Schema migration of any kind.** Re-embedding with a different-dimension model against an existing table fails loudly, and a package release that changes a `vec0` table's columns requires a drop-and-re-index — see [Upgrading](#upgrading-vec0-schema-changes-require-a-drop-and-re-index). Drop the table (or use a new `tableName`) to re-index; `vec0` cannot be altered in place.

package/dist/packlets/sqlite-vec-index/connection.js

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+import { captureAsyncResult, captureResult } from '@fgv/ts-utils';
+/**
+ * Opens a `better-sqlite3` connection this package owns.
+ *
+ * @remarks
+ * **The value import of `better-sqlite3` lives here, and it is deliberately
+ * lazy.** Every other module in this package imports the driver as `import type`
+ * only, so merely importing `@fgv/ts-agent-memory-sqlite-vec` has never loaded the
+ * native binding — a property the path-based factories must not cost consumers who
+ * only ever call `create()`. A static import would move the native load (and its
+ * failure mode) to package-load time for everyone. The dynamic `import()` keeps it
+ * at the one call that actually needs a connection.
+ *
+ * Taking this import is the entire point of the path-based factories: it is the
+ * only place this wrapper leaked its own dependency into consumer source.
+ *
+ * @param path - Filesystem path to the database file. `':memory:'` is accepted and
+ * yields an owned ephemeral connection.
+ * @param label - Package-facing prefix for the failure message.
+ * @returns `Success` with a connection this package owns, or `Failure` if the
+ * driver could not be loaded or the file could not be opened.
+ * @internal
+ */
+export async function openOwnedConnection(path, label) {
+    return (await captureAsyncResult(async () => (await import('better-sqlite3')).default))
+        .withErrorFormat((m) => `${label}: failed to load the 'better-sqlite3' driver: ${m}`)
+        .onSuccess((driver) => captureResult(() => new driver(path)).withErrorFormat((m) => `${label}: failed to open '${path}': ${m}`));
+}
+/**
+ * Closes a connection this package opened.
+ *
+ * @remarks
+ * Only ever called on a connection produced by {@link openOwnedConnection}. A
+ * connection supplied through a `create()` param is the consumer's and is never
+ * closed here — that asymmetry is the reason `close` travels on the handle
+ * returned by `open` rather than sitting on the index class.
+ *
+ * `better-sqlite3`'s own `close()` is safe to call on an already-closed
+ * connection, so a second `close()` on the same handle succeeds rather than
+ * failing.
+ *
+ * @internal
+ */
+export function closeOwnedConnection(db, label) {
+    return captureResult(() => {
+        db.close();
+        return true;
+    }).withErrorFormat((m) => `${label}: failed to close the connection: ${m}`);
+}
+//# sourceMappingURL=connection.js.map

package/dist/packlets/sqlite-vec-index/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../../src/packlets/sqlite-vec-index/connection.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAU,kBAAkB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,IAAY,EACZ,KAAa;IAEb,OAAO,CAAC,MAAM,kBAAkB,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;SACpF,eAAe,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,iDAAiD,CAAC,EAAE,CAAC;SACpF,SAAS,CAAC,CAAC,MAAM,EAAE,EAAE,CACpB,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,qBAAqB,IAAI,MAAM,CAAC,EAAE,CAAC,CACzG,CAAC;AACN,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAAC,EAA0B,EAAE,KAAa;IAC5E,OAAO,aAAa,CAAO,GAAG,EAAE;QAC9B,EAAE,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,qCAAqC,CAAC,EAAE,CAAC,CAAC;AAC9E,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport type BetterSqlite3 from 'better-sqlite3';\nimport { Result, captureAsyncResult, captureResult } from '@fgv/ts-utils';\n\n/**\n * Opens a `better-sqlite3` connection this package owns.\n *\n * @remarks\n * **The value import of `better-sqlite3` lives here, and it is deliberately\n * lazy.** Every other module in this package imports the driver as `import type`\n * only, so merely importing `@fgv/ts-agent-memory-sqlite-vec` has never loaded the\n * native binding — a property the path-based factories must not cost consumers who\n * only ever call `create()`. A static import would move the native load (and its\n * failure mode) to package-load time for everyone. The dynamic `import()` keeps it\n * at the one call that actually needs a connection.\n *\n * Taking this import is the entire point of the path-based factories: it is the\n * only place this wrapper leaked its own dependency into consumer source.\n *\n * @param path - Filesystem path to the database file. `':memory:'` is accepted and\n * yields an owned ephemeral connection.\n * @param label - Package-facing prefix for the failure message.\n * @returns `Success` with a connection this package owns, or `Failure` if the\n * driver could not be loaded or the file could not be opened.\n * @internal\n */\nexport async function openOwnedConnection(\n  path: string,\n  label: string\n): Promise<Result<BetterSqlite3.Database>> {\n  return (await captureAsyncResult(async () => (await import('better-sqlite3')).default))\n    .withErrorFormat((m) => `${label}: failed to load the 'better-sqlite3' driver: ${m}`)\n    .onSuccess((driver) =>\n      captureResult(() => new driver(path)).withErrorFormat((m) => `${label}: failed to open '${path}': ${m}`)\n    );\n}\n\n/**\n * Closes a connection this package opened.\n *\n * @remarks\n * Only ever called on a connection produced by {@link openOwnedConnection}. A\n * connection supplied through a `create()` param is the consumer's and is never\n * closed here — that asymmetry is the reason `close` travels on the handle\n * returned by `open` rather than sitting on the index class.\n *\n * `better-sqlite3`'s own `close()` is safe to call on an already-closed\n * connection, so a second `close()` on the same handle succeeds rather than\n * failing.\n *\n * @internal\n */\nexport function closeOwnedConnection(db: BetterSqlite3.Database, label: string): Result<true> {\n  return captureResult<true>(() => {\n    db.close();\n    return true;\n  }).withErrorFormat((m) => `${label}: failed to close the connection: ${m}`);\n}\n"]}

package/dist/packlets/sqlite-vec-index/model.js.map

@@ -1 +1 @@
-{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../src/packlets/sqlite-vec-index/model.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport type BetterSqlite3 from 'better-sqlite3';\n\n/**\n * Parameters for {@link SqliteVecVectorIndex.create}.\n * @public\n */\nexport interface ISqliteVecVectorIndexCreateParams {\n  /**\n   * A `better-sqlite3` `Database` the consumer owns (bring-your-own, mirroring\n   * the boundary-package convention). The consumer opens it (`new Database(path)`\n   * for a persistent file, or `new Database(':memory:')` for an ephemeral index)\n   * and owns its lifecycle — this index never closes it. `create` loads the\n   * `sqlite-vec` extension onto the connection and, if the vector table already\n   * exists (a reopened persistent file), recovers its established dimension so no\n   * re-embedding is required on open.\n   */\n  readonly database: BetterSqlite3.Database;\n\n  /**\n   * Name of the `vec0` virtual table that holds the embeddings. Must be a simple\n   * SQL identifier (`[A-Za-z_][A-Za-z0-9_]*`). Defaults to `'memory_vectors'`.\n   * Supply a distinct name to hold more than one independent index in a single\n   * database file.\n   */\n  readonly tableName?: string;\n}\n\n/**\n * Parameters for {@link SqliteVecFragmentIndex.create}.\n * @public\n */\nexport interface ISqliteVecFragmentIndexCreateParams {\n  /**\n   * A `better-sqlite3` `Database` the consumer owns (bring-your-own, mirroring\n   * {@link ISqliteVecVectorIndexCreateParams.database}). The consumer opens it and\n   * owns its lifecycle — this index never closes it. `create` loads the\n   * `sqlite-vec` extension onto the connection and, if the fragment table already\n   * exists (a reopened persistent file), recovers its established dimension so no\n   * re-embedding is required on open.\n   */\n  readonly database: BetterSqlite3.Database;\n\n  /**\n   * Name of the `vec0` virtual table that holds the fragment embeddings. Must be a\n   * simple SQL identifier (`[A-Za-z_][A-Za-z0-9_]*`). Defaults to\n   * `'memory_fragments'`. Supply a distinct name (distinct from any record-level\n   * {@link SqliteVecVectorIndex} table) to hold more than one independent index in\n   * a single database file.\n   */\n  readonly tableName?: string;\n}\n"]}
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../src/packlets/sqlite-vec-index/model.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport type BetterSqlite3 from 'better-sqlite3';\nimport type { Result } from '@fgv/ts-utils';\nimport type { SqliteVecFragmentIndex } from './sqliteVecFragmentIndex';\nimport type { SqliteVecVectorIndex } from './sqliteVecVectorIndex';\n\n/**\n * Parameters for {@link SqliteVecVectorIndex.create}.\n * @public\n */\nexport interface ISqliteVecVectorIndexCreateParams {\n  /**\n   * A `better-sqlite3` `Database` the consumer owns (bring-your-own, mirroring\n   * the boundary-package convention). The consumer opens it (`new Database(path)`\n   * for a persistent file, or `new Database(':memory:')` for an ephemeral index)\n   * and owns its lifecycle — this index never closes it. `create` loads the\n   * `sqlite-vec` extension onto the connection and, if the vector table already\n   * exists (a reopened persistent file), recovers its established dimension so no\n   * re-embedding is required on open.\n   */\n  readonly database: BetterSqlite3.Database;\n\n  /**\n   * Name of the `vec0` virtual table that holds the embeddings. Must be a simple\n   * SQL identifier (`[A-Za-z_][A-Za-z0-9_]*`). Defaults to `'memory_vectors'`.\n   * Supply a distinct name to hold more than one independent index in a single\n   * database file.\n   */\n  readonly tableName?: string;\n}\n\n/**\n * Parameters for {@link SqliteVecVectorIndex.open}.\n * @public\n */\nexport interface ISqliteVecVectorIndexOpenParams {\n  /**\n   * Filesystem path to the database file, opened by this package rather than by\n   * the consumer. Created if it does not exist, exactly as `better-sqlite3` would.\n   * `':memory:'` is accepted and yields an owned ephemeral connection.\n   *\n   * **Two `open` calls on one path produce two independent connections, not a\n   * shared one.** That is legal in SQLite and has a different locking story than\n   * the single-connection case — writes contend, and a reader can see a\n   * `SQLITE_BUSY`. To put a record index and a fragment index on one connection\n   * (the intended shared-handle case), open the connection yourself and pass it to\n   * both `create` methods.\n   */\n  readonly path: string;\n\n  /**\n   * Name of the `vec0` virtual table that holds the embeddings. Must be a simple\n   * SQL identifier (`[A-Za-z_][A-Za-z0-9_]*`). Defaults to `'memory_vectors'`.\n   * Supply a distinct name to hold more than one independent index in a single\n   * database file.\n   */\n  readonly tableName?: string;\n}\n\n/**\n * An index plus the connection {@link SqliteVecVectorIndex.open} opened for it.\n *\n * @public\n */\nexport interface ISqliteVecVectorIndexHandle {\n  /** The index, ready to use. */\n  readonly index: SqliteVecVectorIndex;\n\n  /**\n   * Closes the connection **this `open` call created**. Idempotent — a second\n   * `close` succeeds rather than failing.\n   *\n   * @remarks\n   * The disposer travels on this handle rather than on the index class because an\n   * index built by `create` holds a connection the **consumer** owns, and must stay\n   * incapable of closing it. A `close()` method meaningful on some instances and\n   * forbidden on others would be a lie in the type; here, only the caller that\n   * caused the connection to exist is handed the means to end it.\n   *\n   * The index is unusable afterwards — every operation on it will fail against a\n   * closed connection.\n   */\n  close(): Result<true>;\n}\n\n/**\n * Parameters for {@link SqliteVecFragmentIndex.open}.\n * @public\n */\nexport interface ISqliteVecFragmentIndexOpenParams {\n  /**\n   * Filesystem path to the database file, opened by this package rather than by\n   * the consumer. Created if it does not exist, exactly as `better-sqlite3` would.\n   * `':memory:'` is accepted and yields an owned ephemeral connection.\n   *\n   * **Two `open` calls on one path produce two independent connections, not a\n   * shared one** — see {@link ISqliteVecVectorIndexOpenParams.path}. To put a\n   * fragment index and a record index on one connection, open it yourself and pass\n   * it to both `create` methods.\n   */\n  readonly path: string;\n\n  /**\n   * Name of the `vec0` virtual table that holds the fragment embeddings. Must be a\n   * simple SQL identifier (`[A-Za-z_][A-Za-z0-9_]*`). Defaults to\n   * `'memory_fragments'`.\n   */\n  readonly tableName?: string;\n}\n\n/**\n * An index plus the connection {@link SqliteVecFragmentIndex.open} opened for it.\n *\n * @public\n */\nexport interface ISqliteVecFragmentIndexHandle {\n  /** The index, ready to use. */\n  readonly index: SqliteVecFragmentIndex;\n\n  /**\n   * Closes the connection **this `open` call created**. Idempotent — a second\n   * `close` succeeds rather than failing. See\n   * {@link ISqliteVecVectorIndexHandle.close} for why the disposer lives here\n   * rather than on the index class.\n   */\n  close(): Result<true>;\n}\n\n/**\n * Parameters for {@link SqliteVecFragmentIndex.create}.\n * @public\n */\nexport interface ISqliteVecFragmentIndexCreateParams {\n  /**\n   * A `better-sqlite3` `Database` the consumer owns (bring-your-own, mirroring\n   * {@link ISqliteVecVectorIndexCreateParams.database}). The consumer opens it and\n   * owns its lifecycle — this index never closes it. `create` loads the\n   * `sqlite-vec` extension onto the connection and, if the fragment table already\n   * exists (a reopened persistent file), recovers its established dimension so no\n   * re-embedding is required on open.\n   */\n  readonly database: BetterSqlite3.Database;\n\n  /**\n   * Name of the `vec0` virtual table that holds the fragment embeddings. Must be a\n   * simple SQL identifier (`[A-Za-z_][A-Za-z0-9_]*`). Defaults to\n   * `'memory_fragments'`. Supply a distinct name (distinct from any record-level\n   * {@link SqliteVecVectorIndex} table) to hold more than one independent index in\n   * a single database file.\n   */\n  readonly tableName?: string;\n}\n"]}

package/dist/packlets/sqlite-vec-index/sqliteVecFragmentIndex.js

@@ -6,8 +6,11 @@ import { load as loadSqliteVec } from 'sqlite-vec';
 import { captureResult, fail, failWithDetail, succeed, succeedWithDetail } from '@fgv/ts-utils';
 import { edgeTargetKey } from '@fgv/ts-agent-memory';
 import { invokeHook, tally, withRollbackNote } from './rebuildHelpers';
+import { closeOwnedConnection, openOwnedConnection } from './connection';
 /** Default name for the fragment `vec0` virtual table. */
 const DEFAULT_TABLE_NAME = 'memory_fragments';
+/** Package-facing prefix for this class's failure messages. */
+const LABEL = 'sqlite-vec fragment index';
 /** A simple SQL identifier — the only shape allowed for the table name (it is interpolated into DDL). */
 const IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /**
@@ -62,9 +65,13 @@ const AUXILIARY_COLUMN_RE = /\+\s*([A-Za-z_][A-Za-z0-9_]*)/g;
  * cosine (`score = 1 - cosineDistance`), byte-identical to the in-memory index.
  * Large-N ANN indexing is explicitly out of scope, same regime as the record index.
  *
- * The `better-sqlite3` `Database` is consumer-owned (bring-your-own): this index
- * loads the `sqlite-vec` extension onto it and reads/writes the table, but never
- * opens or closes the connection.
+ * **Connection ownership depends on which factory you use.** With
+ * {@link SqliteVecFragmentIndex.create} the `Database` is consumer-owned
+ * (bring-your-own): this index loads the `sqlite-vec` extension onto it and
+ * reads/writes the table, but never opens or closes the connection — and that is
+ * the seam for backing this index and a record index with one connection. With
+ * {@link SqliteVecFragmentIndex.open} this package opens the file itself and hands
+ * back a handle carrying the disposer for the connection it created.
  * @public
  */
 export class SqliteVecFragmentIndex {
@@ -72,10 +79,22 @@ export class SqliteVecFragmentIndex {
         this._db = db;
         this._table = table;
         this._dimension = dimension;
+        this._released = false;
         this._stmts = dimension === undefined ? undefined : this._prepare();
     }
-    /** The number of records that currently have at least one stored fragment. Zero before the first add. */
+    /**
+     * The number of records that currently have at least one stored fragment. Zero
+     * before the first add.
+     *
+     * @remarks
+     * **Throws on a released index**, where every other member returns a `Failure` —
+     * `IFragmentVectorIndex` declares this a synchronous `number`, so there is no
+     * `Result` to fail into, and answering `0` would be a confident lie
+     * indistinguishable from an empty index. Same reasoning as
+     * {@link SqliteVecFragmentIndex.fragmentCount} and `SqliteVecVectorIndex.size`.
+     */
     get recordCount() {
+        this._assertUsable('read recordCount');
         if (this._stmts === undefined) {
             return 0;
         }
@@ -83,8 +102,13 @@ export class SqliteVecFragmentIndex {
         // safe-integer mode (which returns `count(*)` as a `bigint`).
         return Number(this._stmts.recordCount.get().c);
     }
-    /** The total number of fragments currently held across all records. Zero before the first add. */
+    /**
+     * The total number of fragments currently held across all records. Zero before
+     * the first add. **Throws on a released index** — see
+     * {@link SqliteVecFragmentIndex.recordCount}.
+     */
     get fragmentCount() {
+        this._assertUsable('read fragmentCount');
         if (this._stmts === undefined) {
             return 0;
         }
@@ -115,9 +139,97 @@ export class SqliteVecFragmentIndex {
             return new SqliteVecFragmentIndex(params.database, table, dimension);
         }).withErrorFormat((e) => `sqlite-vec fragment index: failed to initialize: ${e}`));
     }
+    /**
+     * Path-based factory. Opens the database file itself and returns the index
+     * together with a disposer for the connection it created.
+     *
+     * @remarks
+     * The fragment-granular sibling of {@link SqliteVecVectorIndex.open}, and present
+     * for the same reason: a consumer doing sub-document retrieval only would
+     * otherwise still value-import `better-sqlite3` and hand-roll a `captureResult`
+     * around a constructor that throws.
+     *
+     * **Use `create` instead when one connection must back both a fragment index and
+     * a record index** — the intended shared-handle case. Two `open` calls on one path
+     * give two independent connections, not a shared one.
+     *
+     * If initialization fails after the file is opened, the connection is closed
+     * before returning, so a failed `open` does not leak the descriptor it created.
+     * Should that close *itself* fail — the connection is then genuinely leaked — the
+     * returned message says so rather than hiding it. That includes the
+     * auxiliary-column mismatch failure, which is reported by `create` only after the
+     * file is open.
+     *
+     * @param params - See {@link ISqliteVecFragmentIndexOpenParams}.
+     * @returns `Success` with a {@link ISqliteVecFragmentIndexHandle}, or `Failure` if
+     * the driver could not be loaded, the file could not be opened, the table name is
+     * not a simple identifier, the extension fails to load, or the existing table was
+     * written by a version with a different auxiliary-column set.
+     */
+    static async open(params) {
+        return (await openOwnedConnection(params.path, LABEL)).thenOnSuccess(async (database) => (await SqliteVecFragmentIndex.create({ database, tableName: params.tableName }))
+            .onFailure((message) => 
+        // This call opened the connection, so a failure to initialize on top of it
+        // must not leave the file handle behind. A close that ALSO fails is said out
+        // loud rather than swallowed — the same reasoning, and the same helper, as
+        // `withRollbackNote`: silently discarding it would make the "a failed open
+        // leaks nothing" guarantee untrue exactly when it stopped holding, with no
+        // way for a caller to detect it.
+        fail(withRollbackNote(message, closeOwnedConnection(database, LABEL))))
+            .onSuccess((index) => succeed({
+            index,
+            close: () => {
+                // Drop the statements BEFORE closing, so there is never a moment where
+                // a closed connection has live `Statement` objects pointing at it —
+                // see `release`.
+                index.release();
+                return closeOwnedConnection(database, LABEL);
+            }
+        })));
+    }
+    /**
+     * Drops this index's prepared statements and marks it unusable. Does **not**
+     * touch the connection.
+     *
+     * @remarks
+     * The fragment-lane counterpart of `SqliteVecVectorIndex.release`, and it
+     * matters here for the same reason plus one more: a shared-connection
+     * deployment — the case `create({ database })` exists for — holds a record index
+     * *and* a fragment index over one connection, so it carries two instances of the
+     * statement-lifetime shape rather than one. Both must be released.
+     *
+     * `better-sqlite3` exposes no public `finalize()`, so dropping the last
+     * reference does not finalize a statement — it makes it collectable *earlier*,
+     * while the environment is alive, rather than surviving to process teardown.
+     * That narrows the window in which `Statement::~Statement()` runs against a
+     * torn-down environment; it is not a proof against it.
+     *
+     * **Call this before closing a connection you own.**
+     * {@link SqliteVecFragmentIndex.open}'s handle does it for you.
+     *
+     * Idempotent. After it, every member fails (or, for the two counts, throws)
+     * rather than answering.
+     */
+    release() {
+        this._released = true;
+        this._stmts = undefined;
+    }
+    /**
+     * Throw if this index has been released. The members that call it and cannot
+     * return a `Result` are the two counts; the rest convert the throw via
+     * `captureResult`.
+     */
+    _assertUsable(what) {
+        if (this._released) {
+            throw new Error(`fragment index: cannot ${what}: the index has been released`);
+        }
+    }
     /** {@inheritDoc IFragmentVectorIndex.addFragments} */
     addFragments(target, fragments) {
         const key = edgeTargetKey(target);
+        if (this._released) {
+            return Promise.resolve(fail(`fragment index: cannot add fragments for '${key}': the index has been released`));
+        }
         // Validate every fragment before touching the database, so a bad fragment never
         // leaves the record half-replaced or the dimension half-established (whole-record
         // replace is all-or-nothing). The effective dimension is the established one, or —
@@ -174,6 +286,7 @@ export class SqliteVecFragmentIndex {
     /** {@inheritDoc IFragmentVectorIndex.remove} */
     remove(target) {
         return Promise.resolve(captureResult(() => {
+            this._assertUsable(`remove '${edgeTargetKey(target)}'`);
             // Idempotent: removing a target with no fragments (or before any add created
             // the table) still succeeds.
             if (this._stmts !== undefined) {
@@ -185,6 +298,7 @@ export class SqliteVecFragmentIndex {
     /** {@inheritDoc IFragmentVectorIndex.has} */
     has(target) {
         return Promise.resolve(captureResult(() => {
+            this._assertUsable(`check '${edgeTargetKey(target)}'`);
             // Before any add has created the table there is nothing held — a truthful
             // `false`, matching `remove`'s idempotence and the zero counts.
             if (this._stmts === undefined) {
@@ -270,6 +384,9 @@ export class SqliteVecFragmentIndex {
      * note on `IVectorIndex.rebuild`. Tolerates a table that does not exist yet.
      */
     _clear() {
+        if (this._released) {
+            return fail('fragment index: cannot clear: the index has been released');
+        }
         if (this._stmts === undefined) {
             return succeed(true);
         }
@@ -278,7 +395,13 @@ export class SqliteVecFragmentIndex {
         return captureResult(() => this._db.prepare(`DELETE FROM "${this._table}"`).run()).onSuccess(() => succeed(true));
     }
     /** {@inheritDoc IFragmentVectorIndex.query} */
-    query(vector, topK, maxPerRecord) {
+    query(vector, topK, options) {
+        const maxPerRecord = options === null || options === void 0 ? void 0 : options.maxPerRecord;
+        const scope = options === null || options === void 0 ? void 0 : options.scope;
+        const id = options === null || options === void 0 ? void 0 : options.id;
+        if (this._released) {
+            return Promise.resolve(fail('fragment index: cannot query: the index has been released'));
+        }
         if (topK <= 0 || this._stmts === undefined) {
             return Promise.resolve(succeed([]));
         }
@@ -292,11 +415,33 @@ export class SqliteVecFragmentIndex {
             // capped record's later fragments are skipped), so fetch the full ranked set
             // and apply the cap + topK cut here — exactly as the in-memory index does.
             // Uncapped, KNN's own `k = topK` is already the answer.
-            const fetchK = maxPerRecord === undefined ? topK : Number(stmts.fragmentCount.get().c);
+            // A scope-only narrowing (a versioned kind's per-entity subtree) spans several
+            // records, and `target_key` equality cannot express a prefix, so it is applied
+            // over the full ranked set below. Correct either way — the caller's `topK` is
+            // applied to the NARROWED set, which is the property that matters — but only
+            // the single-record case gets the partition push-down.
+            const recordKey = scope !== undefined && id !== undefined ? edgeTargetKey({ scope, id }) : undefined;
+            // The cap forces the full ranked set ONLY when other records can fill from
+            // behind a capped one. Under a single-record narrowing every row belongs to
+            // that record, so the result is exactly `min(topK, maxPerRecord, fragments)`
+            // and those are the first rows KNN returns — `k = topK` suffices, and
+            // expanding to the table-wide `fragmentCount` would ask an
+            // already-partition-restricted query for far more rows than it can use.
+            const wholeSet = recordKey === undefined && (maxPerRecord !== undefined || scope !== undefined);
+            const fetchK = wholeSet
+                ? Number(stmts.fragmentCount.get().c)
+                : topK;
             if (fetchK <= 0) {
                 return [];
             }
-            const rows = stmts.query.all(SqliteVecFragmentIndex._toBlob(vector), fetchK);
+            const blob = SqliteVecFragmentIndex._toBlob(vector);
+            const rows = (recordKey !== undefined
+                ? stmts.queryScopedToRecord.all(blob, fetchK, recordKey)
+                : stmts.query.all(blob, fetchK));
+            // The scope prefix every record in `scope` shares. `edgeTargetKey` joins with
+            // a NUL, so this cannot collide with a longer scope that merely starts the
+            // same way.
+            const scopePrefix = scope !== undefined && recordKey === undefined ? `${scope}\0` : undefined;
             // sqlite-vec returns rows ascending by distance (nearest first); score is
             // `1 - cosineDistance`, so this order is already descending score.
             const hits = [];
@@ -305,6 +450,9 @@ export class SqliteVecFragmentIndex {
                 if (hits.length >= topK) {
                     break;
                 }
+                if (scopePrefix !== undefined && !row.target_key.startsWith(scopePrefix)) {
+                    continue;
+                }
                 if (maxPerRecord !== undefined) {
                     const used = (_a = perRecord.get(row.target_key)) !== null && _a !== void 0 ? _a : 0;
                     if (used >= maxPerRecord) {
@@ -355,6 +503,12 @@ export class SqliteVecFragmentIndex {
             },
             query: this._db.prepare(`SELECT target_key, start_off, end_off, fragment_id, distance FROM "${this._table}" ` +
                 `WHERE embedding MATCH ? AND k = ?`),
+            // The single-record narrowing constrains `target_key`, which is the table's
+            // PARTITION KEY — so this is a partition-restricted KNN rather than a scan
+            // plus a filter. That is the performance reason this narrowing belongs in the
+            // library instead of in a bigger over-fetch on the caller's side.
+            queryScopedToRecord: this._db.prepare(`SELECT target_key, start_off, end_off, fragment_id, distance FROM "${this._table}" ` +
+                `WHERE embedding MATCH ? AND k = ? AND target_key = ?`),
             fragmentCount: this._db.prepare(`SELECT count(*) AS c FROM "${this._table}"`),
             recordCount: this._db.prepare(`SELECT count(DISTINCT target_key) AS c FROM "${this._table}"`),
             // `LIMIT 1`: membership needs existence, not cardinality.