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

package/dist/ts-agent-memory-sqlite-vec.d.ts

@@ -3,6 +3,7 @@ import { DetailedResult } from '@fgv/ts-utils';
 import { FragmentEmbedder } from '@fgv/ts-agent-memory';
 import { IEdgeTarget } from '@fgv/ts-agent-memory';
 import { IEmbeddedFragment } from '@fgv/ts-agent-memory';
+import { IFragmentQueryOptions } from '@fgv/ts-agent-memory';
 import { IFragmentVectorIndex } from '@fgv/ts-agent-memory';
 import { IFragmentVectorRebuildReport } from '@fgv/ts-agent-memory';
 import { IMemoryRecordSource } from '@fgv/ts-agent-memory';
@@ -37,6 +38,47 @@ export declare interface ISqliteVecFragmentIndexCreateParams {
     readonly tableName?: string;
 }
 
+/**
+ * An index plus the connection {@link SqliteVecFragmentIndex.open} opened for it.
+ *
+ * @public
+ */
+export declare interface ISqliteVecFragmentIndexHandle {
+    /** The index, ready to use. */
+    readonly index: SqliteVecFragmentIndex;
+    /**
+     * Closes the connection **this `open` call created**. Idempotent — a second
+     * `close` succeeds rather than failing. See
+     * {@link ISqliteVecVectorIndexHandle.close} for why the disposer lives here
+     * rather than on the index class.
+     */
+    close(): Result<true>;
+}
+
+/**
+ * Parameters for {@link SqliteVecFragmentIndex.open}.
+ * @public
+ */
+export declare interface ISqliteVecFragmentIndexOpenParams {
+    /**
+     * Filesystem path to the database file, opened by this package rather than by
+     * the consumer. Created if it does not exist, exactly as `better-sqlite3` would.
+     * `':memory:'` is accepted and yields an owned ephemeral connection.
+     *
+     * **Two `open` calls on one path produce two independent connections, not a
+     * shared one** — see {@link ISqliteVecVectorIndexOpenParams.path}. To put a
+     * fragment index and a record index on one connection, open it yourself and pass
+     * it to both `create` methods.
+     */
+    readonly path: string;
+    /**
+     * Name of the `vec0` virtual table that holds the fragment embeddings. Must be a
+     * simple SQL identifier (`[A-Za-z_][A-Za-z0-9_]*`). Defaults to
+     * `'memory_fragments'`.
+     */
+    readonly tableName?: string;
+}
+
 /**
  * Parameters for {@link SqliteVecVectorIndex.create}.
  * @public
@@ -61,6 +103,58 @@ export declare interface ISqliteVecVectorIndexCreateParams {
     readonly tableName?: string;
 }
 
+/**
+ * An index plus the connection {@link SqliteVecVectorIndex.open} opened for it.
+ *
+ * @public
+ */
+export declare interface ISqliteVecVectorIndexHandle {
+    /** The index, ready to use. */
+    readonly index: SqliteVecVectorIndex;
+    /**
+     * Closes the connection **this `open` call created**. Idempotent — a second
+     * `close` succeeds rather than failing.
+     *
+     * @remarks
+     * The disposer travels on this handle rather than on the index class because an
+     * index built by `create` holds a connection the **consumer** owns, and must stay
+     * incapable of closing it. A `close()` method meaningful on some instances and
+     * forbidden on others would be a lie in the type; here, only the caller that
+     * caused the connection to exist is handed the means to end it.
+     *
+     * The index is unusable afterwards — every operation on it will fail against a
+     * closed connection.
+     */
+    close(): Result<true>;
+}
+
+/**
+ * Parameters for {@link SqliteVecVectorIndex.open}.
+ * @public
+ */
+export declare interface ISqliteVecVectorIndexOpenParams {
+    /**
+     * Filesystem path to the database file, opened by this package rather than by
+     * the consumer. Created if it does not exist, exactly as `better-sqlite3` would.
+     * `':memory:'` is accepted and yields an owned ephemeral connection.
+     *
+     * **Two `open` calls on one path produce two independent connections, not a
+     * shared one.** That is legal in SQLite and has a different locking story than
+     * the single-connection case — writes contend, and a reader can see a
+     * `SQLITE_BUSY`. To put a record index and a fragment index on one connection
+     * (the intended shared-handle case), open the connection yourself and pass it to
+     * both `create` methods.
+     */
+    readonly path: string;
+    /**
+     * Name of the `vec0` virtual table that holds the embeddings. Must be a simple
+     * SQL identifier (`[A-Za-z_][A-Za-z0-9_]*`). Defaults to `'memory_vectors'`.
+     * Supply a distinct name to hold more than one independent index in a single
+     * database file.
+     */
+    readonly tableName?: string;
+}
+
 /**
  * A persistent, `sqlite-vec`-backed `IFragmentVectorIndex` (from
  * `@fgv/ts-agent-memory`) — the fragment-granular sibling of
@@ -100,9 +194,13 @@ export declare interface ISqliteVecVectorIndexCreateParams {
  * 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 {
@@ -112,10 +210,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
@@ -131,6 +248,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} */
@@ -149,7 +324,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
@@ -248,9 +423,13 @@ export declare class SqliteVecFragmentIndex implements IFragmentVectorIndex {
  * durable, appropriate for the same "thousands of records" regime the in-memory
  * index targets. Large-N ANN indexing is explicitly out of scope — see the README.
  *
- * 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 SqliteVecVectorIndex.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 a record index and a fragment index with one connection.
+ * With {@link SqliteVecVectorIndex.open} this package opens the file itself and
+ * hands back a handle carrying the disposer for the connection it created.
  * @public
  */
 export declare class SqliteVecVectorIndex implements IVectorIndex {
@@ -260,8 +439,23 @@ export declare class SqliteVecVectorIndex implements IVectorIndex {
     private _dimension;
     /** Prepared statements; created once the table exists (established or recovered). */
     private _stmts;
+    /**
+     * Set by {@link SqliteVecVectorIndex.release}. Distinct from `_stmts === undefined`,
+     * which means *no dimension established yet* — see the remarks on `release`.
+     */
+    private _released;
     private constructor();
-    /** The number of vectors currently held. Zero before the first `add`. */
+    /**
+     * The number of vectors currently held. Zero before the first `add`.
+     *
+     * @remarks
+     * **Throws on a released index**, where every other member returns a `Failure` —
+     * because `IVectorIndex` declares this a synchronous `number` and there is no
+     * `Result` to fail into. Throwing preserves the behaviour a released index had
+     * before it had an explicit released state (the underlying statement threw
+     * against the closed connection); the alternative, answering `0`, would be a
+     * confident lie indistinguishable from an empty index.
+     */
     get size(): number;
     /**
      * Family-convention factory. Loads the `sqlite-vec` extension onto the supplied
@@ -274,6 +468,60 @@ export declare class SqliteVecVectorIndex implements IVectorIndex {
      * simple identifier or the extension fails to load.
      */
     static create(params: ISqliteVecVectorIndexCreateParams): Promise<Result<SqliteVecVectorIndex>>;
+    /**
+     * Path-based factory. Opens the database file itself and returns the index
+     * together with a disposer for the connection it created.
+     *
+     * @remarks
+     * The convenience over {@link SqliteVecVectorIndex.create} is that the consumer
+     * neither value-imports `better-sqlite3` nor re-establishes `Result` discipline
+     * around a constructor that throws — this is the one place the package leaked its
+     * own dependency into consumer source.
+     *
+     * **Use `create` instead when one connection must back more than one index** (a
+     * record index and a fragment index in the same file, 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.
+     *
+     * @param params - See {@link ISqliteVecVectorIndexOpenParams}.
+     * @returns `Success` with a {@link ISqliteVecVectorIndexHandle}, or `Failure` if
+     * the driver could not be loaded, the file could not be opened, the table name is
+     * not a simple identifier, or the extension fails to load.
+     */
+    static open(params: ISqliteVecVectorIndexOpenParams): Promise<Result<ISqliteVecVectorIndexHandle>>;
+    /**
+     * Drops this index's prepared statements and marks it unusable. Does **not**
+     * touch the connection.
+     *
+     * @remarks
+     * `better-sqlite3` exposes no public `finalize()`, so releasing the last
+     * reference to a `Statement` does not finalize it — 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
+     * SqliteVecVectorIndex.open}'s handle does it for you. A `create()`-made index
+     * holds a connection it does not own and stays structurally incapable of
+     * closing it — this method drops only what the index itself allocated, which is
+     * why it is safe to expose there.
+     *
+     * Idempotent. After it, every member fails (or, for `size`, throws) rather than
+     * answering: a released index is deliberately distinguishable from one that has
+     * simply never had an `add`, whose `_stmts` are also absent but which answers
+     * `size === 0` truthfully.
+     */
+    release(): void;
+    /**
+     * Throw if this index has been released. The one member that calls it and cannot
+     * return a `Result` is `size`; the rest convert the throw via `captureResult`.
+     */
+    private _assertUsable;
     /** {@inheritDoc IVectorIndex.add} */
     add(target: IEdgeTarget, vector: Float32Array): Promise<Result<string>>;
     /** {@inheritDoc IVectorIndex.has} */

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

@@ -0,0 +1,42 @@
+import type BetterSqlite3 from 'better-sqlite3';
+import { Result } 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 declare function openOwnedConnection(path: string, label: string): Promise<Result<BetterSqlite3.Database>>;
+/**
+ * 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 declare function closeOwnedConnection(db: BetterSqlite3.Database, label: string): Result<true>;
+//# sourceMappingURL=connection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../src/packlets/sqlite-vec-index/connection.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,aAAa,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAqC,MAAM,eAAe,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAMzC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,aAAa,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAK5F"}

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

@@ -0,0 +1,91 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openOwnedConnection = openOwnedConnection;
+exports.closeOwnedConnection = closeOwnedConnection;
+const ts_utils_1 = require("@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
+ */
+async function openOwnedConnection(path, label) {
+    return (await (0, ts_utils_1.captureAsyncResult)(async () => (await Promise.resolve().then(() => __importStar(require('better-sqlite3')))).default))
+        .withErrorFormat((m) => `${label}: failed to load the 'better-sqlite3' driver: ${m}`)
+        .onSuccess((driver) => (0, ts_utils_1.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
+ */
+function closeOwnedConnection(db, label) {
+    return (0, ts_utils_1.captureResult)(() => {
+        db.close();
+        return true;
+    }).withErrorFormat((m) => `${label}: failed to close the connection: ${m}`);
+}
+//# sourceMappingURL=connection.js.map

package/lib/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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BH,kDASC;AAiBD,oDAKC;AAvDD,4CAA0E;AAE1E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACI,KAAK,UAAU,mBAAmB,CACvC,IAAY,EACZ,KAAa;IAEb,OAAO,CAAC,MAAM,IAAA,6BAAkB,EAAC,KAAK,IAAI,EAAE,CAAC,CAAC,wDAAa,gBAAgB,GAAC,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,IAAA,wBAAa,EAAC,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,SAAgB,oBAAoB,CAAC,EAA0B,EAAE,KAAa;IAC5E,OAAO,IAAA,wBAAa,EAAO,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/lib/packlets/sqlite-vec-index/model.d.ts

@@ -1,4 +1,7 @@
 import type BetterSqlite3 from 'better-sqlite3';
+import type { Result } from '@fgv/ts-utils';
+import type { SqliteVecFragmentIndex } from './sqliteVecFragmentIndex';
+import type { SqliteVecVectorIndex } from './sqliteVecVectorIndex';
 /**
  * Parameters for {@link SqliteVecVectorIndex.create}.
  * @public
@@ -22,6 +25,95 @@ export interface ISqliteVecVectorIndexCreateParams {
      */
     readonly tableName?: string;
 }
+/**
+ * Parameters for {@link SqliteVecVectorIndex.open}.
+ * @public
+ */
+export interface ISqliteVecVectorIndexOpenParams {
+    /**
+     * Filesystem path to the database file, opened by this package rather than by
+     * the consumer. Created if it does not exist, exactly as `better-sqlite3` would.
+     * `':memory:'` is accepted and yields an owned ephemeral connection.
+     *
+     * **Two `open` calls on one path produce two independent connections, not a
+     * shared one.** That is legal in SQLite and has a different locking story than
+     * the single-connection case — writes contend, and a reader can see a
+     * `SQLITE_BUSY`. To put a record index and a fragment index on one connection
+     * (the intended shared-handle case), open the connection yourself and pass it to
+     * both `create` methods.
+     */
+    readonly path: string;
+    /**
+     * Name of the `vec0` virtual table that holds the embeddings. Must be a simple
+     * SQL identifier (`[A-Za-z_][A-Za-z0-9_]*`). Defaults to `'memory_vectors'`.
+     * Supply a distinct name to hold more than one independent index in a single
+     * database file.
+     */
+    readonly tableName?: string;
+}
+/**
+ * An index plus the connection {@link SqliteVecVectorIndex.open} opened for it.
+ *
+ * @public
+ */
+export interface ISqliteVecVectorIndexHandle {
+    /** The index, ready to use. */
+    readonly index: SqliteVecVectorIndex;
+    /**
+     * Closes the connection **this `open` call created**. Idempotent — a second
+     * `close` succeeds rather than failing.
+     *
+     * @remarks
+     * The disposer travels on this handle rather than on the index class because an
+     * index built by `create` holds a connection the **consumer** owns, and must stay
+     * incapable of closing it. A `close()` method meaningful on some instances and
+     * forbidden on others would be a lie in the type; here, only the caller that
+     * caused the connection to exist is handed the means to end it.
+     *
+     * The index is unusable afterwards — every operation on it will fail against a
+     * closed connection.
+     */
+    close(): Result<true>;
+}
+/**
+ * Parameters for {@link SqliteVecFragmentIndex.open}.
+ * @public
+ */
+export interface ISqliteVecFragmentIndexOpenParams {
+    /**
+     * Filesystem path to the database file, opened by this package rather than by
+     * the consumer. Created if it does not exist, exactly as `better-sqlite3` would.
+     * `':memory:'` is accepted and yields an owned ephemeral connection.
+     *
+     * **Two `open` calls on one path produce two independent connections, not a
+     * shared one** — see {@link ISqliteVecVectorIndexOpenParams.path}. To put a
+     * fragment index and a record index on one connection, open it yourself and pass
+     * it to both `create` methods.
+     */
+    readonly path: string;
+    /**
+     * Name of the `vec0` virtual table that holds the fragment embeddings. Must be a
+     * simple SQL identifier (`[A-Za-z_][A-Za-z0-9_]*`). Defaults to
+     * `'memory_fragments'`.
+     */
+    readonly tableName?: string;
+}
+/**
+ * An index plus the connection {@link SqliteVecFragmentIndex.open} opened for it.
+ *
+ * @public
+ */
+export interface ISqliteVecFragmentIndexHandle {
+    /** The index, ready to use. */
+    readonly index: SqliteVecFragmentIndex;
+    /**
+     * Closes the connection **this `open` call created**. Idempotent — a second
+     * `close` succeeds rather than failing. See
+     * {@link ISqliteVecVectorIndexHandle.close} for why the disposer lives here
+     * rather than on the index class.
+     */
+    close(): Result<true>;
+}
 /**
  * Parameters for {@link SqliteVecFragmentIndex.create}.
  * @public

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

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/packlets/sqlite-vec-index/model.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,aAAa,MAAM,gBAAgB,CAAC;AAEhD;;;GAGG;AACH,MAAM,WAAW,iCAAiC;IAChD;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,QAAQ,CAAC;IAE1C;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,mCAAmC;IAClD;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,QAAQ,CAAC;IAE1C;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/packlets/sqlite-vec-index/model.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,aAAa,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEnE;;;GAGG;AACH,MAAM,WAAW,iCAAiC;IAChD;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,QAAQ,CAAC;IAE1C;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,+BAA+B;IAC9C;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IAErC;;;;;;;;;;;;;OAaG;IACH,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,iCAAiC;IAChD;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IAEvC;;;;;OAKG;IACH,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,mCAAmC;IAClD;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,QAAQ,CAAC;IAE1C;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B"}

package/lib/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"]}