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

package/lib/packlets/sqlite-vec-index/sqliteVecFragmentIndex.d.ts

@@ -1,6 +1,6 @@
 import { DetailedResult, Result } from '@fgv/ts-utils';
-import { FragmentEmbedder, IEdgeTarget, IEmbeddedFragment, IFragmentVectorIndex, IFragmentVectorRebuildReport, IMemoryRecordSource, IVectorQueryHit, IVectorRebuildOptions } from '@fgv/ts-agent-memory';
-import { ISqliteVecFragmentIndexCreateParams } from './model';
+import { FragmentEmbedder, IEdgeTarget, IEmbeddedFragment, IFragmentVectorIndex, IFragmentVectorRebuildReport, IMemoryRecordSource, IVectorQueryHit, IVectorRebuildOptions, IFragmentQueryOptions } from '@fgv/ts-agent-memory';
+import { ISqliteVecFragmentIndexCreateParams, ISqliteVecFragmentIndexHandle, ISqliteVecFragmentIndexOpenParams } from './model';
 /**
  * A persistent, `sqlite-vec`-backed `IFragmentVectorIndex` (from
  * `@fgv/ts-agent-memory`) — the fragment-granular sibling of
@@ -40,9 +40,13 @@ import { ISqliteVecFragmentIndexCreateParams } from './model';
  * 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 declare class SqliteVecFragmentIndex implements IFragmentVectorIndex {
@@ -52,10 +56,29 @@ export declare class SqliteVecFragmentIndex implements IFragmentVectorIndex {
     private _dimension;
     /** Prepared statements; created once the table exists (established or recovered). */
     private _stmts;
+    /**
+     * Set by {@link SqliteVecFragmentIndex.release}. Distinct from `_stmts === undefined`,
+     * which means *no dimension established yet* — see the remarks on `release`.
+     */
+    private _released;
     private constructor();
-    /** 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(): number;
-    /** 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(): number;
     /**
      * Family-convention factory. Loads the `sqlite-vec` extension onto the supplied
@@ -71,6 +94,64 @@ export declare class SqliteVecFragmentIndex implements IFragmentVectorIndex {
      * drop-and-re-index — `vec0` cannot be altered in place).
      */
     static create(params: ISqliteVecFragmentIndexCreateParams): Promise<Result<SqliteVecFragmentIndex>>;
+    /**
+     * 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 open(params: ISqliteVecFragmentIndexOpenParams): Promise<Result<ISqliteVecFragmentIndexHandle>>;
+    /**
+     * 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(): void;
+    /**
+     * 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`.
+     */
+    private _assertUsable;
     /** {@inheritDoc IFragmentVectorIndex.addFragments} */
     addFragments(target: IEdgeTarget, fragments: ReadonlyArray<IEmbeddedFragment>): Promise<Result<number>>;
     /** {@inheritDoc IFragmentVectorIndex.remove} */
@@ -89,7 +170,7 @@ export declare class SqliteVecFragmentIndex implements IFragmentVectorIndex {
      */
     private _clear;
     /** {@inheritDoc IFragmentVectorIndex.query} */
-    query(vector: Float32Array, topK: number, maxPerRecord?: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    query(vector: Float32Array, topK: number, options?: IFragmentQueryOptions): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
     /**
      * Create the fragment `vec0` virtual table with the established dimension. The
      * auxiliary columns must stay in sync with `AUXILIARY_COLUMNS`, which

package/lib/packlets/sqlite-vec-index/sqliteVecFragmentIndex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqliteVecFragmentIndex.d.ts","sourceRoot":"","sources":["../../../src/packlets/sqlite-vec-index/sqliteVecFragmentIndex.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,cAAc,EACd,MAAM,EAMP,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EAEjB,oBAAoB,EACpB,4BAA4B,EAE5B,mBAAmB,EAEnB,eAAe,EACf,qBAAqB,EAKtB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,mCAAmC,EAAE,MAAM,SAAS,CAAC;AAmD9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,sBAAuB,YAAW,oBAAoB;IACjE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAyB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,yFAAyF;IACzF,OAAO,CAAC,UAAU,CAAqB;IACvC,qFAAqF;IACrF,OAAO,CAAC,MAAM,CAAkC;IAEhD,OAAO;IAOP,yGAAyG;IACzG,IAAW,WAAW,IAAI,MAAM,CAO/B;IAED,kGAAkG;IAClG,IAAW,aAAa,IAAI,MAAM,CAKjC;IAED;;;;;;;;;;;;OAYG;WACW,MAAM,CAAC,MAAM,EAAE,mCAAmC,GAAG,OAAO,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC;IAmB1G,sDAAsD;IAC/C,YAAY,CACjB,MAAM,EAAE,WAAW,EACnB,SAAS,EAAE,aAAa,CAAC,iBAAiB,CAAC,GAC1C,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAuE1B,gDAAgD;IACzC,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAahE,6CAA6C;IACtC,GAAG,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAazD,iDAAiD;IACpC,OAAO,CAClB,MAAM,EAAE,mBAAmB,EAC3B,KAAK,EAAE,gBAAgB,EACvB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,cAAc,CAAC,4BAA4B,EAAE,4BAA4B,CAAC,CAAC;IAqEtF;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM;IAWd,+CAA+C;IACxC,KAAK,CACV,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC;IAsDlD;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAQpB,4EAA4E;IAC5E,OAAO,CAAC,QAAQ;IA4ChB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAsBrC;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAiBtC;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAa1B;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,UAAU;IAiBzB,sHAAsH;IACtH,OAAO,CAAC,MAAM,CAAC,OAAO;IAItB;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;IAWxB;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;CASzB"}
+{"version":3,"file":"sqliteVecFragmentIndex.d.ts","sourceRoot":"","sources":["../../../src/packlets/sqlite-vec-index/sqliteVecFragmentIndex.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,cAAc,EACd,MAAM,EAMP,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EAEjB,oBAAoB,EACpB,4BAA4B,EAE5B,mBAAmB,EAEnB,eAAe,EACf,qBAAqB,EAErB,qBAAqB,EAItB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,mCAAmC,EACnC,6BAA6B,EAC7B,iCAAiC,EAClC,MAAM,SAAS,CAAC;AAsDjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,qBAAa,sBAAuB,YAAW,oBAAoB;IACjE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAyB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,yFAAyF;IACzF,OAAO,CAAC,UAAU,CAAqB;IACvC,qFAAqF;IACrF,OAAO,CAAC,MAAM,CAAkC;IAChD;;;OAGG;IACH,OAAO,CAAC,SAAS,CAAU;IAE3B,OAAO;IAQP;;;;;;;;;;OAUG;IACH,IAAW,WAAW,IAAI,MAAM,CAQ/B;IAED;;;;OAIG;IACH,IAAW,aAAa,IAAI,MAAM,CAMjC;IAED;;;;;;;;;;;;OAYG;WACW,MAAM,CAAC,MAAM,EAAE,mCAAmC,GAAG,OAAO,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC;IAmB1G;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;WACiB,IAAI,CACtB,MAAM,EAAE,iCAAiC,GACxC,OAAO,CAAC,MAAM,CAAC,6BAA6B,CAAC,CAAC;IA2BjD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACI,OAAO,IAAI,IAAI;IAKtB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAMrB,sDAAsD;IAC/C,YAAY,CACjB,MAAM,EAAE,WAAW,EACnB,SAAS,EAAE,aAAa,CAAC,iBAAiB,CAAC,GAC1C,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IA4E1B,gDAAgD;IACzC,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAchE,6CAA6C;IACtC,GAAG,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAczD,iDAAiD;IACpC,OAAO,CAClB,MAAM,EAAE,mBAAmB,EAC3B,KAAK,EAAE,gBAAgB,EACvB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,cAAc,CAAC,4BAA4B,EAAE,4BAA4B,CAAC,CAAC;IAqEtF;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM;IAcd,+CAA+C;IACxC,KAAK,CACV,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC;IAsFlD;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAQpB,4EAA4E;IAC5E,OAAO,CAAC,QAAQ;IAoDhB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAsBrC;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAiBtC;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAa1B;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,UAAU;IAiBzB,sHAAsH;IACtH,OAAO,CAAC,MAAM,CAAC,OAAO;IAItB;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;IAWxB;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;CASzB"}

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

@@ -9,8 +9,11 @@ const sqlite_vec_1 = require("sqlite-vec");
 const ts_utils_1 = require("@fgv/ts-utils");
 const ts_agent_memory_1 = require("@fgv/ts-agent-memory");
 const rebuildHelpers_1 = require("./rebuildHelpers");
+const connection_1 = require("./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_]*$/;
 /**
@@ -65,9 +68,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
  */
 class SqliteVecFragmentIndex {
@@ -75,10 +82,22 @@ 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;
         }
@@ -86,8 +105,13 @@ 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;
         }
@@ -118,9 +142,97 @@ 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 (0, connection_1.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.
+        (0, ts_utils_1.fail)((0, rebuildHelpers_1.withRollbackNote)(message, (0, connection_1.closeOwnedConnection)(database, LABEL))))
+            .onSuccess((index) => (0, ts_utils_1.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 (0, connection_1.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 = (0, ts_agent_memory_1.edgeTargetKey)(target);
+        if (this._released) {
+            return Promise.resolve((0, ts_utils_1.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 —
@@ -177,6 +289,7 @@ class SqliteVecFragmentIndex {
     /** {@inheritDoc IFragmentVectorIndex.remove} */
     remove(target) {
         return Promise.resolve((0, ts_utils_1.captureResult)(() => {
+            this._assertUsable(`remove '${(0, ts_agent_memory_1.edgeTargetKey)(target)}'`);
             // Idempotent: removing a target with no fragments (or before any add created
             // the table) still succeeds.
             if (this._stmts !== undefined) {
@@ -188,6 +301,7 @@ class SqliteVecFragmentIndex {
     /** {@inheritDoc IFragmentVectorIndex.has} */
     has(target) {
         return Promise.resolve((0, ts_utils_1.captureResult)(() => {
+            this._assertUsable(`check '${(0, ts_agent_memory_1.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) {
@@ -273,6 +387,9 @@ class SqliteVecFragmentIndex {
      * note on `IVectorIndex.rebuild`. Tolerates a table that does not exist yet.
      */
     _clear() {
+        if (this._released) {
+            return (0, ts_utils_1.fail)('fragment index: cannot clear: the index has been released');
+        }
         if (this._stmts === undefined) {
             return (0, ts_utils_1.succeed)(true);
         }
@@ -281,7 +398,13 @@ class SqliteVecFragmentIndex {
         return (0, ts_utils_1.captureResult)(() => this._db.prepare(`DELETE FROM "${this._table}"`).run()).onSuccess(() => (0, ts_utils_1.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((0, ts_utils_1.fail)('fragment index: cannot query: the index has been released'));
+        }
         if (topK <= 0 || this._stmts === undefined) {
             return Promise.resolve((0, ts_utils_1.succeed)([]));
         }
@@ -295,11 +418,33 @@ 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 ? (0, ts_agent_memory_1.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 = [];
@@ -308,6 +453,9 @@ 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) {
@@ -358,6 +506,12 @@ 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.