@fgv/ts-agent-memory-sqlite-vec 5.1.0-42

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

@@ -0,0 +1,182 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+import { load as loadSqliteVec } from 'sqlite-vec';
+import { captureResult, fail, succeed } from '@fgv/ts-utils';
+import { edgeTargetKey } from '@fgv/ts-agent-memory';
+/** Default name for the `vec0` virtual table. */
+const DEFAULT_TABLE_NAME = 'memory_vectors';
+/** 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_]*$/;
+/**
+ * A persistent, `sqlite-vec`-backed `IVectorIndex` for `@fgv/ts-agent-memory`.
+ *
+ * @remarks
+ * This is the **durable** counterpart to the in-memory `InMemoryCosineIndex`:
+ * embeddings live in a `sqlite-vec` `vec0` virtual table inside a `better-sqlite3`
+ * database, so they survive a process restart. A consumer that wires this index
+ * into `FileTreeMemoryStore` (instead of the in-memory index) opens an existing
+ * vault **without re-embedding it** — the vectors are already on disk. New writes
+ * still flow through the store's incremental embed-on-write path; there is no core
+ * store change.
+ *
+ * The index is keyed by the canonical `edgeTargetKey` of each record's
+ * scope-qualified `(scope, id)` address (a `TEXT PRIMARY KEY` on the `vec0` table),
+ * so two records that share a filename stem across scopes never collide. The
+ * dimension is established by the first `add` (the `vec0` column is fixed-width) and
+ * recovered from the table schema when a persistent file is reopened; every later
+ * `add`/`query` must match it or fail loudly, exactly as the in-memory index does.
+ * Similarity is cosine (`distance_metric=cosine`): the returned `score` is
+ * `1 - cosineDistance`, i.e. cosine similarity in `[-1, 1]`, higher = more similar —
+ * byte-for-byte the same scoring contract as `InMemoryCosineIndex`.
+ *
+ * Query is a brute-force `vec0` KNN scan (not an ANN structure): correct and
+ * 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.
+ * @public
+ */
+export class SqliteVecVectorIndex {
+    constructor(db, table, dimension) {
+        this._db = db;
+        this._table = table;
+        this._dimension = dimension;
+        this._stmts = dimension === undefined ? undefined : this._prepare();
+    }
+    /** The number of vectors currently held. Zero before the first `add`. */
+    get size() {
+        if (this._stmts === undefined) {
+            return 0;
+        }
+        return this._stmts.count.get().c;
+    }
+    /**
+     * Family-convention factory. Loads the `sqlite-vec` extension onto the supplied
+     * `better-sqlite3` connection and, if the vector table already exists (a reopened
+     * persistent file), recovers its established dimension so no re-embedding is
+     * needed on open.
+     *
+     * @param params - See {@link ISqliteVecVectorIndexCreateParams}.
+     * @returns `Success` with the index, or `Failure` if the table name is not a
+     * simple identifier or the extension fails to load.
+     */
+    static create(params) {
+        var _a;
+        const table = (_a = params.tableName) !== null && _a !== void 0 ? _a : DEFAULT_TABLE_NAME;
+        if (!IDENTIFIER_RE.test(table)) {
+            return Promise.resolve(fail(`sqlite-vec index: table name '${table}' is not a simple SQL identifier`));
+        }
+        return Promise.resolve(captureResult(() => {
+            loadSqliteVec(params.database);
+            const dimension = SqliteVecVectorIndex._readExistingDimension(params.database, table);
+            return new SqliteVecVectorIndex(params.database, table, dimension);
+        }).withErrorFormat((e) => `sqlite-vec index: failed to initialize: ${e}`));
+    }
+    /** {@inheritDoc IVectorIndex.add} */
+    add(target, vector) {
+        const key = edgeTargetKey(target);
+        if (vector.length === 0) {
+            return Promise.resolve(fail(`vector index: cannot add '${key}': empty vector`));
+        }
+        if (this._dimension !== undefined && vector.length !== this._dimension) {
+            return Promise.resolve(fail(`vector index: cannot add '${key}': dimension ${vector.length} does not match index dimension ${this._dimension}`));
+        }
+        return Promise.resolve(captureResult(() => {
+            if (this._stmts === undefined) {
+                this._createTable(vector.length);
+                this._dimension = vector.length;
+                this._stmts = this._prepare();
+            }
+            this._stmts.replace(key, SqliteVecVectorIndex._toBlob(vector));
+            return key;
+        }).withErrorFormat((e) => `vector index: cannot add '${key}': ${e}`));
+    }
+    /** {@inheritDoc IVectorIndex.remove} */
+    remove(target) {
+        return Promise.resolve(captureResult(() => {
+            // Idempotent: removing a target with no embedding (or before any `add`
+            // created the table) still succeeds.
+            if (this._stmts !== undefined) {
+                this._stmts.delete.run(edgeTargetKey(target));
+            }
+            return target;
+        }).withErrorFormat((e) => `vector index: cannot remove '${edgeTargetKey(target)}': ${e}`));
+    }
+    /** {@inheritDoc IVectorIndex.query} */
+    query(vector, topK) {
+        if (topK <= 0 || this._stmts === undefined) {
+            return Promise.resolve(succeed([]));
+        }
+        if (vector.length !== this._dimension) {
+            return Promise.resolve(fail(`vector index: query dimension ${vector.length} does not match index dimension ${this._dimension}`));
+        }
+        return Promise.resolve(captureResult(() => {
+            const rows = this._stmts.query.all(SqliteVecVectorIndex._toBlob(vector), topK);
+            // sqlite-vec returns rows in ascending distance (nearest first); score is
+            // `1 - cosineDistance` = cosine similarity, so descending score is preserved.
+            return rows.map((row) => ({
+                target: SqliteVecVectorIndex._parseKey(row.target_key),
+                score: 1 - row.distance
+            }));
+        }).withErrorFormat((e) => `vector index: query failed: ${e}`));
+    }
+    /** Create the `vec0` virtual table with the established dimension. */
+    _createTable(dimension) {
+        this._db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS "${this._table}" USING vec0(` +
+            `target_key TEXT PRIMARY KEY, embedding float[${dimension}] distance_metric=cosine)`);
+    }
+    /** Prepare the statements the index reuses. Requires the table to exist. */
+    _prepare() {
+        const del = this._db.prepare(`DELETE FROM "${this._table}" WHERE target_key = ?`);
+        const ins = this._db.prepare(`INSERT INTO "${this._table}"(target_key, embedding) VALUES (?, ?)`);
+        // vec0 rejects INSERT OR REPLACE on a TEXT primary key, so replace is a
+        // delete-then-insert inside a single transaction.
+        const replaceTxn = this._db.transaction((key, blob) => {
+            del.run(key);
+            ins.run(key, blob);
+        });
+        return {
+            delete: del,
+            replace: (key, blob) => {
+                replaceTxn(key, blob);
+            },
+            query: this._db.prepare(`SELECT target_key, distance FROM "${this._table}" WHERE embedding MATCH ? AND k = ?`),
+            count: this._db.prepare(`SELECT count(*) AS c FROM "${this._table}"`)
+        };
+    }
+    /**
+     * Recover the established dimension of an existing `vec0` table from its stored
+     * `CREATE VIRTUAL TABLE` SQL (`float[<n>]`). Returns `undefined` when the table
+     * does not exist yet (a fresh database — dimension is set by the first `add`).
+     */
+    static _readExistingDimension(db, table) {
+        const row = db
+            .prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?")
+            .get(table);
+        if (row === undefined) {
+            return undefined;
+        }
+        const match = row.sql.match(/float\[(\d+)\]/);
+        return match === null ? undefined : Number(match[1]);
+    }
+    /** Pack a `Float32Array` as the little-endian byte blob `vec0` stores. Copies, so the caller may reuse its buffer. */
+    static _toBlob(vector) {
+        return new Uint8Array(Float32Array.from(vector).buffer);
+    }
+    /**
+     * Reverse `edgeTargetKey` — the canonical key is `scope\0id` with NUL
+     * excluded from both components, so the first NUL splits it unambiguously.
+     */
+    static _parseKey(key) {
+        const nul = key.indexOf('\0');
+        return {
+            scope: key.slice(0, nul),
+            id: key.slice(nul + 1)
+        };
+    }
+}
+//# sourceMappingURL=sqliteVecVectorIndex.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sqliteVecVectorIndex.js","sourceRoot":"","sources":["../../../src/packlets/sqlite-vec-index/sqliteVecVectorIndex.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport type BetterSqlite3 from 'better-sqlite3';\nimport { load as loadSqliteVec } from 'sqlite-vec';\nimport { Result, captureResult, fail, succeed } from '@fgv/ts-utils';\nimport {\n  IEdgeTarget,\n  IVectorIndex,\n  IVectorQueryHit,\n  MemoryId,\n  MemoryScopeKey,\n  edgeTargetKey\n} from '@fgv/ts-agent-memory';\nimport { ISqliteVecVectorIndexCreateParams } from './model';\n\n/** Default name for the `vec0` virtual table. */\nconst DEFAULT_TABLE_NAME: string = 'memory_vectors';\n\n/** A simple SQL identifier — the only shape allowed for the table name (it is interpolated into DDL). */\nconst IDENTIFIER_RE: RegExp = /^[A-Za-z_][A-Za-z0-9_]*$/;\n\n/** One KNN row as returned by the `vec0` MATCH query. */\ninterface IKnnRow {\n  readonly target_key: string;\n  readonly distance: number;\n}\n\n/**\n * A persistent, `sqlite-vec`-backed `IVectorIndex` for `@fgv/ts-agent-memory`.\n *\n * @remarks\n * This is the **durable** counterpart to the in-memory `InMemoryCosineIndex`:\n * embeddings live in a `sqlite-vec` `vec0` virtual table inside a `better-sqlite3`\n * database, so they survive a process restart. A consumer that wires this index\n * into `FileTreeMemoryStore` (instead of the in-memory index) opens an existing\n * vault **without re-embedding it** — the vectors are already on disk. New writes\n * still flow through the store's incremental embed-on-write path; there is no core\n * store change.\n *\n * The index is keyed by the canonical `edgeTargetKey` of each record's\n * scope-qualified `(scope, id)` address (a `TEXT PRIMARY KEY` on the `vec0` table),\n * so two records that share a filename stem across scopes never collide. The\n * dimension is established by the first `add` (the `vec0` column is fixed-width) and\n * recovered from the table schema when a persistent file is reopened; every later\n * `add`/`query` must match it or fail loudly, exactly as the in-memory index does.\n * Similarity is cosine (`distance_metric=cosine`): the returned `score` is\n * `1 - cosineDistance`, i.e. cosine similarity in `[-1, 1]`, higher = more similar —\n * byte-for-byte the same scoring contract as `InMemoryCosineIndex`.\n *\n * Query is a brute-force `vec0` KNN scan (not an ANN structure): correct and\n * durable, appropriate for the same \"thousands of records\" regime the in-memory\n * index targets. Large-N ANN indexing is explicitly out of scope — see the README.\n *\n * The `better-sqlite3` `Database` is consumer-owned (bring-your-own): this index\n * loads the `sqlite-vec` extension onto it and reads/writes the table, but never\n * opens or closes the connection.\n * @public\n */\nexport class SqliteVecVectorIndex implements IVectorIndex {\n  private readonly _db: BetterSqlite3.Database;\n  private readonly _table: string;\n  /** The dimension of every stored vector; `undefined` until the table exists (first `add` or a reopened non-empty file). */\n  private _dimension: number | undefined;\n  /** Prepared statements; created once the table exists (established or recovered). */\n  private _stmts: ISqliteVecStatements | undefined;\n\n  private constructor(db: BetterSqlite3.Database, table: string, dimension: number | undefined) {\n    this._db = db;\n    this._table = table;\n    this._dimension = dimension;\n    this._stmts = dimension === undefined ? undefined : this._prepare();\n  }\n\n  /** The number of vectors currently held. Zero before the first `add`. */\n  public get size(): number {\n    if (this._stmts === undefined) {\n      return 0;\n    }\n    return (this._stmts.count.get() as { c: number }).c;\n  }\n\n  /**\n   * Family-convention factory. Loads the `sqlite-vec` extension onto the supplied\n   * `better-sqlite3` connection and, if the vector table already exists (a reopened\n   * persistent file), recovers its established dimension so no re-embedding is\n   * needed on open.\n   *\n   * @param params - See {@link ISqliteVecVectorIndexCreateParams}.\n   * @returns `Success` with the index, or `Failure` if the table name is not a\n   * simple identifier or the extension fails to load.\n   */\n  public static create(params: ISqliteVecVectorIndexCreateParams): Promise<Result<SqliteVecVectorIndex>> {\n    const table: string = params.tableName ?? DEFAULT_TABLE_NAME;\n    if (!IDENTIFIER_RE.test(table)) {\n      return Promise.resolve(fail(`sqlite-vec index: table name '${table}' is not a simple SQL identifier`));\n    }\n    return Promise.resolve(\n      captureResult(() => {\n        loadSqliteVec(params.database);\n        const dimension: number | undefined = SqliteVecVectorIndex._readExistingDimension(\n          params.database,\n          table\n        );\n        return new SqliteVecVectorIndex(params.database, table, dimension);\n      }).withErrorFormat((e) => `sqlite-vec index: failed to initialize: ${e}`)\n    );\n  }\n\n  /** {@inheritDoc IVectorIndex.add} */\n  public add(target: IEdgeTarget, vector: Float32Array): Promise<Result<string>> {\n    const key: string = edgeTargetKey(target);\n    if (vector.length === 0) {\n      return Promise.resolve(fail(`vector index: cannot add '${key}': empty vector`));\n    }\n    if (this._dimension !== undefined && vector.length !== this._dimension) {\n      return Promise.resolve(\n        fail(\n          `vector index: cannot add '${key}': dimension ${vector.length} does not match index dimension ${this._dimension}`\n        )\n      );\n    }\n    return Promise.resolve(\n      captureResult(() => {\n        if (this._stmts === undefined) {\n          this._createTable(vector.length);\n          this._dimension = vector.length;\n          this._stmts = this._prepare();\n        }\n        this._stmts.replace(key, SqliteVecVectorIndex._toBlob(vector));\n        return key;\n      }).withErrorFormat((e) => `vector index: cannot add '${key}': ${e}`)\n    );\n  }\n\n  /** {@inheritDoc IVectorIndex.remove} */\n  public remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>> {\n    return Promise.resolve(\n      captureResult(() => {\n        // Idempotent: removing a target with no embedding (or before any `add`\n        // created the table) still succeeds.\n        if (this._stmts !== undefined) {\n          this._stmts.delete.run(edgeTargetKey(target));\n        }\n        return target;\n      }).withErrorFormat((e) => `vector index: cannot remove '${edgeTargetKey(target)}': ${e}`)\n    );\n  }\n\n  /** {@inheritDoc IVectorIndex.query} */\n  public query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>> {\n    if (topK <= 0 || this._stmts === undefined) {\n      return Promise.resolve(succeed([]));\n    }\n    if (vector.length !== this._dimension) {\n      return Promise.resolve(\n        fail(\n          `vector index: query dimension ${vector.length} does not match index dimension ${this._dimension}`\n        )\n      );\n    }\n    return Promise.resolve(\n      captureResult<ReadonlyArray<IVectorQueryHit>>(() => {\n        const rows: ReadonlyArray<IKnnRow> = this._stmts!.query.all(\n          SqliteVecVectorIndex._toBlob(vector),\n          topK\n        ) as ReadonlyArray<IKnnRow>;\n        // sqlite-vec returns rows in ascending distance (nearest first); score is\n        // `1 - cosineDistance` = cosine similarity, so descending score is preserved.\n        return rows.map((row) => ({\n          target: SqliteVecVectorIndex._parseKey(row.target_key),\n          score: 1 - row.distance\n        }));\n      }).withErrorFormat((e) => `vector index: query failed: ${e}`)\n    );\n  }\n\n  /** Create the `vec0` virtual table with the established dimension. */\n  private _createTable(dimension: number): void {\n    this._db.exec(\n      `CREATE VIRTUAL TABLE IF NOT EXISTS \"${this._table}\" USING vec0(` +\n        `target_key TEXT PRIMARY KEY, embedding float[${dimension}] distance_metric=cosine)`\n    );\n  }\n\n  /** Prepare the statements the index reuses. Requires the table to exist. */\n  private _prepare(): ISqliteVecStatements {\n    const del: BetterSqlite3.Statement = this._db.prepare(\n      `DELETE FROM \"${this._table}\" WHERE target_key = ?`\n    );\n    const ins: BetterSqlite3.Statement = this._db.prepare(\n      `INSERT INTO \"${this._table}\"(target_key, embedding) VALUES (?, ?)`\n    );\n    // vec0 rejects INSERT OR REPLACE on a TEXT primary key, so replace is a\n    // delete-then-insert inside a single transaction.\n    const replaceTxn: BetterSqlite3.Transaction<(key: string, blob: Uint8Array) => void> =\n      this._db.transaction((key: string, blob: Uint8Array) => {\n        del.run(key);\n        ins.run(key, blob);\n      });\n    return {\n      delete: del,\n      replace: (key: string, blob: Uint8Array): void => {\n        replaceTxn(key, blob);\n      },\n      query: this._db.prepare(\n        `SELECT target_key, distance FROM \"${this._table}\" WHERE embedding MATCH ? AND k = ?`\n      ),\n      count: this._db.prepare(`SELECT count(*) AS c FROM \"${this._table}\"`)\n    };\n  }\n\n  /**\n   * Recover the established dimension of an existing `vec0` table from its stored\n   * `CREATE VIRTUAL TABLE` SQL (`float[<n>]`). Returns `undefined` when the table\n   * does not exist yet (a fresh database — dimension is set by the first `add`).\n   */\n  private static _readExistingDimension(db: BetterSqlite3.Database, table: string): number | undefined {\n    const row: { sql: string } | undefined = db\n      .prepare(\"SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?\")\n      .get(table) as { sql: string } | undefined;\n    if (row === undefined) {\n      return undefined;\n    }\n    const match: RegExpMatchArray | null = row.sql.match(/float\\[(\\d+)\\]/);\n    return match === null ? undefined : Number(match[1]);\n  }\n\n  /** Pack a `Float32Array` as the little-endian byte blob `vec0` stores. Copies, so the caller may reuse its buffer. */\n  private static _toBlob(vector: Float32Array): Uint8Array {\n    return new Uint8Array(Float32Array.from(vector).buffer);\n  }\n\n  /**\n   * Reverse `edgeTargetKey` — the canonical key is `scope\\0id` with NUL\n   * excluded from both components, so the first NUL splits it unambiguously.\n   */\n  private static _parseKey(key: string): IEdgeTarget {\n    const nul: number = key.indexOf('\\0');\n    return {\n      scope: key.slice(0, nul) as unknown as MemoryScopeKey,\n      id: key.slice(nul + 1) as unknown as MemoryId\n    };\n  }\n}\n\n/** The prepared statements / helpers the index reuses once its table exists. */\ninterface ISqliteVecStatements {\n  readonly delete: BetterSqlite3.Statement;\n  readonly replace: (key: string, blob: Uint8Array) => void;\n  readonly query: BetterSqlite3.Statement;\n  readonly count: BetterSqlite3.Statement;\n}\n"]}

package/dist/test/unit/sqliteVecFragmentIndex.test.js

@@ -0,0 +1,352 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+import '@fgv/ts-utils-jest';
+import BetterSqlite3 from 'better-sqlite3';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { SqliteVecFragmentIndex } from '../../index';
+function target(scope, id) {
+    return { scope: scope, id: id };
+}
+function loc(start, end) {
+    return { start, end };
+}
+function frag(start, end, ...values) {
+    return { locator: loc(start, end), vector: Float32Array.from(values) };
+}
+describe('SqliteVecFragmentIndex', () => {
+    let db;
+    beforeEach(() => {
+        db = new BetterSqlite3(':memory:');
+    });
+    afterEach(() => {
+        // Some tests close `db` themselves to exercise error paths; guard double-close.
+        if (db.open) {
+            db.close();
+        }
+    });
+    async function makeIndex() {
+        return (await SqliteVecFragmentIndex.create({ database: db })).orThrow();
+    }
+    describe('create', () => {
+        test('succeeds over a fresh database with an empty index', async () => {
+            expect(await SqliteVecFragmentIndex.create({ database: db })).toSucceedAndSatisfy((index) => {
+                expect(index.recordCount).toBe(0);
+                expect(index.fragmentCount).toBe(0);
+            });
+        });
+        test('rejects a table name that is not a simple identifier', async () => {
+            expect(await SqliteVecFragmentIndex.create({ database: db, tableName: 'bad name; DROP TABLE x' })).toFailWith(/not a simple SQL identifier/i);
+        });
+        test('fails loudly when the sqlite-vec extension cannot load (closed database)', async () => {
+            const closed = new BetterSqlite3(':memory:');
+            closed.close();
+            expect(await SqliteVecFragmentIndex.create({ database: closed })).toFailWith(/failed to initialize/i);
+        });
+        test('recovers no dimension from a pre-existing non-vec0 table of the same name', async () => {
+            db.exec('CREATE TABLE memory_fragments (foo TEXT)');
+            expect(await SqliteVecFragmentIndex.create({ database: db })).toSucceedAndSatisfy((index) => {
+                expect(index.recordCount).toBe(0);
+            });
+        });
+    });
+    describe('addFragments', () => {
+        test('stores every fragment and reports the count; tracks record/fragment counts', async () => {
+            const index = await makeIndex();
+            expect(await index.addFragments(target('knowledge', 'doc-a'), [frag(0, 5, 1, 0), frag(5, 10, 0, 1)])).toSucceedWith(2);
+            expect(index.recordCount).toBe(1);
+            expect(index.fragmentCount).toBe(2);
+        });
+        test('whole-record replace — a second addFragments drops the prior fragments', async () => {
+            const index = await makeIndex();
+            const t = target('knowledge', 'doc-a');
+            (await index.addFragments(t, [frag(0, 5, 1, 0), frag(5, 10, 0, 1)])).orThrow();
+            expect(await index.addFragments(t, [frag(0, 3, 1, 1)])).toSucceedWith(1);
+            expect(index.recordCount).toBe(1);
+            expect(index.fragmentCount).toBe(1);
+            expect(await index.query(Float32Array.from([1, 1]), 5)).toSucceedAndSatisfy((hits) => {
+                expect(hits).toHaveLength(1);
+                expect(hits[0].locator).toEqual(loc(0, 3));
+            });
+        });
+        test('an empty fragments array drops an existing record', async () => {
+            const index = await makeIndex();
+            const t = target('knowledge', 'doc-a');
+            (await index.addFragments(t, [frag(0, 5, 1, 0)])).orThrow();
+            expect(await index.addFragments(t, [])).toSucceedWith(0);
+            expect(index.recordCount).toBe(0);
+            expect(index.fragmentCount).toBe(0);
+        });
+        test('an empty fragments array on a fresh index is a no-op (no table created)', async () => {
+            const index = await makeIndex();
+            expect(await index.addFragments(target('knowledge', 'doc-a'), [])).toSucceedWith(0);
+            expect(index.recordCount).toBe(0);
+            // A later real add still establishes the dimension cleanly.
+            expect(await index.addFragments(target('knowledge', 'doc-b'), [frag(0, 5, 1, 0)])).toSucceedWith(1);
+        });
+        test('same stem in different scopes are distinct entries', async () => {
+            const index = await makeIndex();
+            (await index.addFragments(target('conversations/a', 'turn-3'), [frag(0, 5, 1, 0)])).orThrow();
+            (await index.addFragments(target('conversations/b', 'turn-3'), [frag(0, 5, 0, 1)])).orThrow();
+            expect(index.recordCount).toBe(2);
+            expect(index.fragmentCount).toBe(2);
+        });
+        test('fails loudly on an empty fragment vector — and stores nothing', async () => {
+            const index = await makeIndex();
+            expect(await index.addFragments(target('knowledge', 'doc-a'), [frag(0, 5, 1, 0), frag(5, 10)])).toFailWith(/cannot add 'knowledge\0doc-a': empty fragment vector/i);
+            expect(index.recordCount).toBe(0);
+        });
+        test('fails loudly on a fragment-dimension mismatch against the established dimension', async () => {
+            const index = await makeIndex();
+            (await index.addFragments(target('knowledge', 'a'), [frag(0, 5, 1, 0)])).orThrow();
+            expect(await index.addFragments(target('knowledge', 'b'), [frag(0, 5, 1, 0, 0)])).toFailWith(/fragment dimension 3 does not match index dimension 2/i);
+        });
+        test('rejects a non-safe-integer locator offset up front (never persists an unreadable locator)', async () => {
+            const index = await makeIndex();
+            // A non-integer offset: reject before the write, with a clear message.
+            expect(await index.addFragments(target('knowledge', 'doc-a'), [frag(0.5, 5, 1, 0)])).toFailWith(/locator \[0\.5, 5\) offsets must be safe integers/i);
+            // A too-large (non-safe) integer offset is likewise rejected.
+            expect(await index.addFragments(target('knowledge', 'doc-b'), [frag(0, Number.MAX_SAFE_INTEGER + 1, 1, 0)])).toFailWith(/offsets must be safe integers/i);
+            expect(index.recordCount).toBe(0);
+        });
+        test('a failed multi-fragment add on a fresh index does not establish a dimension (all-or-nothing)', async () => {
+            const index = await makeIndex();
+            // dim 2 then dim 3 in the same batch: fails, and must NOT commit dim 2.
+            expect(await index.addFragments(target('knowledge', 'doc-1'), [frag(0, 5, 1, 0), frag(5, 10, 1, 0, 0)])).toFailWith(/fragment dimension 3 does not match index dimension 2/i);
+            expect(index.recordCount).toBe(0);
+            // A fresh dim-3 record now indexes cleanly (the index was never poisoned to dim 2).
+            expect(await index.addFragments(target('knowledge', 'doc-2'), [frag(0, 5, 1, 0, 0)])).toSucceedWith(1);
+        });
+        test('fails loudly (best-effort caller unaffected) when the underlying add throws', async () => {
+            const index = await makeIndex();
+            (await index.addFragments(target('knowledge', 'doc-a'), [frag(0, 5, 1, 0)])).orThrow();
+            db.close();
+            expect(await index.addFragments(target('knowledge', 'doc-b'), [frag(0, 5, 0, 1)])).toFailWith(/cannot add 'knowledge\0doc-b'/i);
+        });
+        test('fails loudly (never silently corrupts) when the table name collides with a non-vec0 table', async () => {
+            // A plain table already occupies the default name. `CREATE VIRTUAL TABLE IF NOT
+            // EXISTS` no-ops against it, so preparing the vector INSERT against the missing
+            // columns must fail loudly rather than corrupt state.
+            db.exec('CREATE TABLE memory_fragments (foo TEXT)');
+            const index = (await SqliteVecFragmentIndex.create({ database: db })).orThrow();
+            expect(await index.addFragments(target('knowledge', 'doc-a'), [frag(0, 5, 1, 0)])).toFailWith(/cannot add 'knowledge\0doc-a'/i);
+        });
+    });
+    describe('query', () => {
+        async function seeded() {
+            const index = await makeIndex();
+            (await index.addFragments(target('knowledge', 'doc-a'), [frag(0, 5, 1, 0), frag(5, 10, 0, 1)])).orThrow();
+            (await index.addFragments(target('knowledge', 'doc-b'), [frag(0, 5, 1, 1)])).orThrow();
+            return index;
+        }
+        test('returns fragment hits in descending score order, each carrying its locator', async () => {
+            const index = await seeded();
+            expect(await index.query(Float32Array.from([1, 0]), 3)).toSucceedAndSatisfy((hits) => {
+                expect(hits[0].target.id).toBe('doc-a');
+                expect(hits[0].locator).toEqual(loc(0, 5));
+                expect(hits[0].score).toBeCloseTo(1, 5);
+                expect(hits[1].target.id).toBe('doc-b');
+                expect(hits[1].score).toBeCloseTo(1 / Math.sqrt(2), 5);
+                expect(hits[2].target.id).toBe('doc-a');
+                expect(hits[2].locator).toEqual(loc(5, 10));
+                expect(hits[2].score).toBeCloseTo(0, 5);
+            });
+        });
+        test('truncates to topK', async () => {
+            const index = await seeded();
+            expect(await index.query(Float32Array.from([1, 0]), 2)).toSucceedAndSatisfy((hits) => {
+                expect(hits).toHaveLength(2);
+                expect(hits.map((h) => h.target.id)).toEqual(['doc-a', 'doc-b']);
+            });
+        });
+        test('maxPerRecord caps fragments per record during selection (before the topK cut)', async () => {
+            const index = await makeIndex();
+            (await index.addFragments(target('knowledge', 'doc-a'), [
+                frag(0, 5, 1, 0),
+                frag(5, 10, 0.9, 0.1),
+                frag(10, 15, 0.8, 0.2)
+            ])).orThrow();
+            (await index.addFragments(target('knowledge', 'doc-b'), [frag(0, 5, 0.7, 0.3)])).orThrow();
+            // Without a cap the top-2 would be doc-a twice; maxPerRecord=1 surfaces doc-b.
+            expect(await index.query(Float32Array.from([1, 0]), 2, 1)).toSucceedAndSatisfy((hits) => {
+                expect(hits).toHaveLength(2);
+                expect(hits.map((h) => h.target.id)).toEqual(['doc-a', 'doc-b']);
+                expect(hits[0].locator).toEqual(loc(0, 5));
+            });
+        });
+        test('maxPerRecord=0 yields no hits', async () => {
+            const index = await seeded();
+            expect(await index.query(Float32Array.from([1, 0]), 5, 0)).toSucceedWith([]);
+        });
+        test('maxPerRecord larger than any record leaves the ranking unchanged', async () => {
+            const index = await seeded();
+            expect(await index.query(Float32Array.from([1, 0]), 5, 10)).toSucceedAndSatisfy((hits) => {
+                expect(hits).toHaveLength(3);
+                expect(hits[0].target.id).toBe('doc-a');
+            });
+        });
+        test('returns empty for a non-positive topK', async () => {
+            const index = await seeded();
+            expect(await index.query(Float32Array.from([1, 0]), 0)).toSucceedWith([]);
+            expect(await index.query(Float32Array.from([1, 0]), -5)).toSucceedWith([]);
+        });
+        test('returns empty before any add (no established dimension)', async () => {
+            const index = await makeIndex();
+            expect(await index.query(Float32Array.from([1, 0, 0]), 5)).toSucceedWith([]);
+        });
+        test('returns empty when a capped query runs against an emptied (but existing) table', async () => {
+            const index = await makeIndex();
+            const t = target('knowledge', 'doc-a');
+            (await index.addFragments(t, [frag(0, 5, 1, 0)])).orThrow();
+            (await index.addFragments(t, [])).orThrow(); // table now exists but holds 0 rows
+            // fetchK derives from the (zero) fragment count under a cap → short-circuits to [].
+            expect(await index.query(Float32Array.from([1, 0]), 5, 2)).toSucceedWith([]);
+        });
+        test('rejects a query vector of the wrong dimension', async () => {
+            const index = await seeded();
+            expect(await index.query(Float32Array.from([1, 0, 0]), 3)).toFailWith(/query dimension 3 does not match index dimension 2/i);
+        });
+        test('a capped query stops at topK even when more ranked rows remain', async () => {
+            // maxPerRecord makes the fetch span the full ranked set (3 fragments), but
+            // topK=1 must return exactly one hit — the top row — and stop.
+            const index = await seeded();
+            expect(await index.query(Float32Array.from([1, 0]), 1, 5)).toSucceedAndSatisfy((hits) => {
+                expect(hits).toHaveLength(1);
+                expect(hits[0].target.id).toBe('doc-a');
+                expect(hits[0].locator).toEqual(loc(0, 5));
+            });
+        });
+        test('fails loudly when the underlying query throws', async () => {
+            const index = await seeded();
+            db.close();
+            expect(await index.query(Float32Array.from([1, 0]), 3)).toFailWith(/query failed/i);
+        });
+    });
+    describe('remove', () => {
+        test('removes every fragment of a record and is reflected in subsequent queries', async () => {
+            const index = await makeIndex();
+            const a = target('knowledge', 'doc-a');
+            const b = target('knowledge', 'doc-b');
+            (await index.addFragments(a, [frag(0, 5, 1, 0), frag(5, 10, 1, 0)])).orThrow();
+            (await index.addFragments(b, [frag(0, 5, 0, 1)])).orThrow();
+            expect(await index.remove(a)).toSucceedWith(a);
+            expect(index.recordCount).toBe(1);
+            expect(index.fragmentCount).toBe(1);
+            expect(await index.query(Float32Array.from([1, 0]), 5)).toSucceedAndSatisfy((hits) => {
+                expect(hits.map((h) => h.target.id)).toEqual(['doc-b']);
+            });
+        });
+        test('is idempotent — removing a missing target succeeds', async () => {
+            const index = await makeIndex();
+            (await index.addFragments(target('knowledge', 'doc-a'), [frag(0, 5, 1, 0)])).orThrow();
+            expect(await index.remove(target('knowledge', 'missing'))).toSucceedWith(target('knowledge', 'missing'));
+            expect(index.recordCount).toBe(1);
+        });
+        test('succeeds before any add (no table yet)', async () => {
+            const index = await makeIndex();
+            expect(await index.remove(target('knowledge', 'doc-a'))).toSucceedWith(target('knowledge', 'doc-a'));
+            expect(index.recordCount).toBe(0);
+        });
+        test('fails loudly when the underlying remove throws', async () => {
+            const index = await makeIndex();
+            (await index.addFragments(target('knowledge', 'doc-a'), [frag(0, 5, 1, 0)])).orThrow();
+            db.close();
+            expect(await index.remove(target('knowledge', 'doc-a'))).toFailWith(/cannot remove 'knowledge\0doc-a'/i);
+        });
+    });
+    describe('safe-integer mode and corrupt persisted data', () => {
+        const toBlob = (...v) => new Uint8Array(Float32Array.from(v).buffer);
+        async function seededWithRow() {
+            // A valid add creates the table and establishes dim 2; corrupt rows are then
+            // inserted directly to model externally-edited / safe-integer-mode data.
+            const index = await makeIndex();
+            (await index.addFragments(target('knowledge', 'doc-a'), [frag(0, 5, 1, 0)])).orThrow();
+            return index;
+        }
+        function insertRaw(key, start, end, ...vec) {
+            db.prepare('INSERT INTO memory_fragments(target_key, embedding, start_off, end_off) VALUES (?, ?, ?, ?)').run(key, toBlob(...vec), start, end);
+        }
+        test('coerces bigint offsets (better-sqlite3 safe-integer mode) to number locators', async () => {
+            const index = await seededWithRow();
+            // Under safe-integer mode every integer column comes back as a bigint.
+            db.defaultSafeIntegers(true);
+            expect(await index.query(Float32Array.from([1, 0]), 1)).toSucceedAndSatisfy((hits) => {
+                const locator = hits[0].locator;
+                expect(locator).toEqual(loc(0, 5));
+                expect(typeof (locator === null || locator === void 0 ? void 0 : locator.start)).toBe('number');
+                expect(typeof (locator === null || locator === void 0 ? void 0 : locator.end)).toBe('number');
+            });
+        });
+        test('fails loudly when a stored offset is outside the safe-integer range', async () => {
+            const index = await seededWithRow();
+            // Safe-integer mode returns the huge offset as a bigint (no read-time throw),
+            // so the _toOffset guard is what must fire.
+            db.defaultSafeIntegers(true);
+            insertRaw('knowledge\0doc-b', BigInt(2) ** BigInt(60), BigInt(0), 0, 1);
+            expect(await index.query(Float32Array.from([0, 1]), 5)).toFailWith(/locator offset .* is not a safe integer/i);
+        });
+        test('fails loudly when a stored key is missing the NUL separator', async () => {
+            const index = await seededWithRow();
+            insertRaw('nonulkey', BigInt(0), BigInt(5), 0, 1);
+            expect(await index.query(Float32Array.from([0, 1]), 5)).toFailWith(/missing scope\/id separator/i);
+        });
+    });
+    describe('custom table name', () => {
+        test('two fragment indexes on distinct tables in one database are independent', async () => {
+            const a = (await SqliteVecFragmentIndex.create({ database: db, tableName: 'frag_a' })).orThrow();
+            const b = (await SqliteVecFragmentIndex.create({ database: db, tableName: 'frag_b' })).orThrow();
+            (await a.addFragments(target('s', 'one'), [frag(0, 5, 1, 0)])).orThrow();
+            expect(a.fragmentCount).toBe(1);
+            expect(b.fragmentCount).toBe(0);
+        });
+    });
+    describe('persistence across reopen (the durability guarantee)', () => {
+        let dir;
+        let dbPath;
+        beforeEach(() => {
+            dir = fs.mkdtempSync(path.join(os.tmpdir(), 'svfrag-'));
+            dbPath = path.join(dir, 'fragments.db');
+        });
+        afterEach(() => {
+            fs.rmSync(dir, { recursive: true, force: true });
+        });
+        test('fragments written to a file survive a close + reopen with no re-embed, dimension + locators recovered', async () => {
+            const first = new BetterSqlite3(dbPath);
+            const writeIndex = (await SqliteVecFragmentIndex.create({ database: first })).orThrow();
+            (await writeIndex.addFragments(target('knowledge', 'doc-a'), [
+                frag(0, 5, 1, 0, 0),
+                frag(5, 12, 0, 1, 0)
+            ])).orThrow();
+            (await writeIndex.addFragments(target('conversations/c', 'turn-1'), [frag(0, 8, 0.9, 0.1, 0)])).orThrow();
+            first.close();
+            // Second session: a brand-new connection + index over the same file. No adds
+            // (no re-embedding) — fragments, dimension, and locators come straight off disk.
+            const second = new BetterSqlite3(dbPath);
+            const reopened = (await SqliteVecFragmentIndex.create({ database: second })).orThrow();
+            try {
+                expect(reopened.recordCount).toBe(2);
+                expect(reopened.fragmentCount).toBe(3);
+                expect(await reopened.query(Float32Array.from([1, 0, 0]), 3)).toSucceedAndSatisfy((hits) => {
+                    expect(hits[0].target).toEqual(target('knowledge', 'doc-a'));
+                    expect(hits[0].locator).toEqual(loc(0, 5));
+                    expect(hits[0].score).toBeCloseTo(1, 5);
+                    // the cross-scope target round-trips its full (scope, id) and locator
+                    expect(hits[1].target).toEqual(target('conversations/c', 'turn-1'));
+                    expect(hits[1].locator).toEqual(loc(0, 8));
+                });
+                // The recovered dimension is enforced on a post-reopen add.
+                expect(await reopened.addFragments(target('knowledge', 'w'), [frag(0, 4, 1, 0)])).toFailWith(/fragment dimension 2 does not match index dimension 3/i);
+                // A matching-dimension add still works and persists incrementally.
+                (await reopened.addFragments(target('knowledge', 'w'), [frag(0, 4, 0, 0, 1)])).orThrow();
+                expect(reopened.recordCount).toBe(3);
+            }
+            finally {
+                second.close();
+            }
+        });
+    });
+});
+//# sourceMappingURL=sqliteVecFragmentIndex.test.js.map