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

package/etc/ts-agent-memory-sqlite-vec.api.md

@@ -0,0 +1,66 @@
+## API Report File for "@fgv/ts-agent-memory-sqlite-vec"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import type BetterSqlite3 from 'better-sqlite3';
+import { IEdgeTarget } from '@fgv/ts-agent-memory';
+import { IEmbeddedFragment } from '@fgv/ts-agent-memory';
+import { IFragmentVectorIndex } from '@fgv/ts-agent-memory';
+import { IVectorIndex } from '@fgv/ts-agent-memory';
+import { IVectorQueryHit } from '@fgv/ts-agent-memory';
+import { Result } from '@fgv/ts-utils';
+
+// @public
+export interface ISqliteVecFragmentIndexCreateParams {
+    readonly database: BetterSqlite3.Database;
+    readonly tableName?: string;
+}
+
+// @public
+export interface ISqliteVecVectorIndexCreateParams {
+    readonly database: BetterSqlite3.Database;
+    readonly tableName?: string;
+}
+
+// @public
+export class SqliteVecFragmentIndex implements IFragmentVectorIndex {
+    // Warning: (ae-unresolved-inheritdoc-reference) The @inheritDoc reference could not be resolved: The package "@fgv/ts-agent-memory-sqlite-vec" does not have an export "IFragmentVectorIndex"
+    //
+    // (undocumented)
+    addFragments(target: IEdgeTarget, fragments: ReadonlyArray<IEmbeddedFragment>): Promise<Result<number>>;
+    static create(params: ISqliteVecFragmentIndexCreateParams): Promise<Result<SqliteVecFragmentIndex>>;
+    get fragmentCount(): number;
+    // Warning: (ae-unresolved-inheritdoc-reference) The @inheritDoc reference could not be resolved: The package "@fgv/ts-agent-memory-sqlite-vec" does not have an export "IFragmentVectorIndex"
+    //
+    // (undocumented)
+    query(vector: Float32Array, topK: number, maxPerRecord?: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    get recordCount(): number;
+    // Warning: (ae-unresolved-inheritdoc-reference) The @inheritDoc reference could not be resolved: The package "@fgv/ts-agent-memory-sqlite-vec" does not have an export "IFragmentVectorIndex"
+    //
+    // (undocumented)
+    remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
+}
+
+// @public
+export class SqliteVecVectorIndex implements IVectorIndex {
+    // Warning: (ae-unresolved-inheritdoc-reference) The @inheritDoc reference could not be resolved: The package "@fgv/ts-agent-memory-sqlite-vec" does not have an export "IVectorIndex"
+    //
+    // (undocumented)
+    add(target: IEdgeTarget, vector: Float32Array): Promise<Result<string>>;
+    static create(params: ISqliteVecVectorIndexCreateParams): Promise<Result<SqliteVecVectorIndex>>;
+    // Warning: (ae-unresolved-inheritdoc-reference) The @inheritDoc reference could not be resolved: The package "@fgv/ts-agent-memory-sqlite-vec" does not have an export "IVectorIndex"
+    //
+    // (undocumented)
+    query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    // Warning: (ae-unresolved-inheritdoc-reference) The @inheritDoc reference could not be resolved: The package "@fgv/ts-agent-memory-sqlite-vec" does not have an export "IVectorIndex"
+    //
+    // (undocumented)
+    remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
+    get size(): number;
+}
+
+// (No @packageDocumentation comment for this package)
+
+```

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './packlets/sqlite-vec-index';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,6BAA6B,CAAC"}

package/lib/index.js

@@ -0,0 +1,22 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./packlets/sqlite-vec-index"), exports);
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAEH,8DAA4C","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './packlets/sqlite-vec-index';\n"]}

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

@@ -0,0 +1,4 @@
+export * from './model';
+export * from './sqliteVecVectorIndex';
+export * from './sqliteVecFragmentIndex';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/sqlite-vec-index/index.ts"],"names":[],"mappings":"AAKA,cAAc,SAAS,CAAC;AACxB,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC"}

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

@@ -0,0 +1,24 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./model"), exports);
+__exportStar(require("./sqliteVecVectorIndex"), exports);
+__exportStar(require("./sqliteVecFragmentIndex"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/sqlite-vec-index/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAEH,0CAAwB;AACxB,yDAAuC;AACvC,2DAAyC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './model';\nexport * from './sqliteVecVectorIndex';\nexport * from './sqliteVecFragmentIndex';\n"]}

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

@@ -0,0 +1,48 @@
+import type BetterSqlite3 from 'better-sqlite3';
+/**
+ * Parameters for {@link SqliteVecVectorIndex.create}.
+ * @public
+ */
+export interface ISqliteVecVectorIndexCreateParams {
+    /**
+     * A `better-sqlite3` `Database` the consumer owns (bring-your-own, mirroring
+     * the boundary-package convention). The consumer opens it (`new Database(path)`
+     * for a persistent file, or `new Database(':memory:')` for an ephemeral index)
+     * and owns its lifecycle — this index never closes it. `create` loads the
+     * `sqlite-vec` extension onto the connection and, if the vector table already
+     * exists (a reopened persistent file), recovers its established dimension so no
+     * re-embedding is required on open.
+     */
+    readonly database: BetterSqlite3.Database;
+    /**
+     * 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;
+}
+/**
+ * Parameters for {@link SqliteVecFragmentIndex.create}.
+ * @public
+ */
+export interface ISqliteVecFragmentIndexCreateParams {
+    /**
+     * A `better-sqlite3` `Database` the consumer owns (bring-your-own, mirroring
+     * {@link ISqliteVecVectorIndexCreateParams.database}). The consumer opens it and
+     * owns its lifecycle — this index never closes it. `create` loads the
+     * `sqlite-vec` extension onto the connection and, if the fragment table already
+     * exists (a reopened persistent file), recovers its established dimension so no
+     * re-embedding is required on open.
+     */
+    readonly database: BetterSqlite3.Database;
+    /**
+     * 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'`. Supply a distinct name (distinct from any record-level
+     * {@link SqliteVecVectorIndex} table) to hold more than one independent index in
+     * a single database file.
+     */
+    readonly tableName?: string;
+}
+//# sourceMappingURL=model.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,7 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=model.js.map

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

@@ -0,0 +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"]}

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

@@ -0,0 +1,94 @@
+import { Result } from '@fgv/ts-utils';
+import { IEdgeTarget, IEmbeddedFragment, IFragmentVectorIndex, IVectorQueryHit } from '@fgv/ts-agent-memory';
+import { ISqliteVecFragmentIndexCreateParams } from './model';
+/**
+ * A persistent, `sqlite-vec`-backed `IFragmentVectorIndex` (from
+ * `@fgv/ts-agent-memory`) — the fragment-granular sibling of
+ * {@link SqliteVecVectorIndex}, and the **durable** counterpart to the in-memory
+ * `InMemoryFragmentCosineIndex`.
+ *
+ * @remarks
+ * Where {@link SqliteVecVectorIndex} keys one vector per record on a
+ * `target_key` primary key, this index holds **many** vectors per record — one per
+ * in-record `[start, end)` span — so it keys the `vec0` table on `target_key` as a
+ * **`PARTITION KEY`** (many rows may share it) and stores each fragment's locator
+ * offsets in two auxiliary columns (`+start_off`, `+end_off`) that ride alongside
+ * the vector and are returned on query but never filtered. A query is a brute-force
+ * `vec0` KNN scan across all partitions returning per-fragment hits, each carrying
+ * its record `target` and the matched `locator`.
+ *
+ * Semantics match `InMemoryFragmentCosineIndex` exactly: `addFragments` is
+ * whole-record-replace (a single transaction deletes every prior fragment of the
+ * target, then inserts the new set), `remove` drops every fragment of a target,
+ * and `query` applies the optional `maxPerRecord` cap **during selection, before
+ * the topK cut** — so one long document cannot crowd others out. The dimension is
+ * established by the first `addFragments` (the `vec0` column is fixed-width) and
+ * recovered from the table schema when a persistent file is reopened; similarity is
+ * 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.
+ * @public
+ */
+export declare class SqliteVecFragmentIndex implements IFragmentVectorIndex {
+    private readonly _db;
+    private readonly _table;
+    /** The dimension of every stored fragment vector; `undefined` until the table exists. */
+    private _dimension;
+    /** Prepared statements; created once the table exists (established or recovered). */
+    private _stmts;
+    private constructor();
+    /** The number of records that currently have at least one stored fragment. Zero before the first add. */
+    get recordCount(): number;
+    /** The total number of fragments currently held across all records. Zero before the first add. */
+    get fragmentCount(): number;
+    /**
+     * Family-convention factory. Loads the `sqlite-vec` extension onto the supplied
+     * `better-sqlite3` connection and, if the fragment table already exists (a
+     * reopened persistent file), recovers its established dimension so no
+     * re-embedding is needed on open.
+     *
+     * @param params - See {@link ISqliteVecFragmentIndexCreateParams}.
+     * @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: ISqliteVecFragmentIndexCreateParams): Promise<Result<SqliteVecFragmentIndex>>;
+    /** {@inheritDoc IFragmentVectorIndex.addFragments} */
+    addFragments(target: IEdgeTarget, fragments: ReadonlyArray<IEmbeddedFragment>): Promise<Result<number>>;
+    /** {@inheritDoc IFragmentVectorIndex.remove} */
+    remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
+    /** {@inheritDoc IFragmentVectorIndex.query} */
+    query(vector: Float32Array, topK: number, maxPerRecord?: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    /** Create the fragment `vec0` virtual table with the established dimension. */
+    private _createTable;
+    /** Prepare the statements the index reuses. Requires the table to exist. */
+    private _prepare;
+    /**
+     * Recover the established dimension of an existing fragment `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).
+     */
+    private static _readExistingDimension;
+    /** Pack a `Float32Array` as the little-endian byte blob `vec0` stores. Copies, so the caller may reuse its buffer. */
+    private static _toBlob;
+    /**
+     * Reverse `edgeTargetKey` — the canonical key is `scope\0id` with NUL excluded
+     * from both components, so the first NUL splits it unambiguously. A key with no
+     * NUL cannot have been written by `edgeTargetKey`; rather than fabricate a wrong
+     * `(scope, id)` from corrupt / externally-edited table data, throw so the query
+     * surfaces it as a loud `Failure`.
+     */
+    private static _parseKey;
+    /**
+     * Coerce a persisted locator offset to a plain `number`. `better-sqlite3` returns
+     * integer columns as `bigint` under safe-integer mode, so an offset can arrive as
+     * either; both narrow to `number` here. A value outside the safe-integer range
+     * (only reachable via corrupt / externally-edited data — the index only ever
+     * writes in-document offsets) throws rather than silently losing precision, so the
+     * query surfaces it as a loud `Failure`.
+     */
+    private static _toOffset;
+}
+//# sourceMappingURL=sqliteVecFragmentIndex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sqliteVecFragmentIndex.d.ts","sourceRoot":"","sources":["../../../src/packlets/sqlite-vec-index/sqliteVecFragmentIndex.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,MAAM,EAAgC,MAAM,eAAe,CAAC;AACrE,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EAIhB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,mCAAmC,EAAE,MAAM,SAAS,CAAC;AAsB9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;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;;;;;;;;;OASG;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;IAyD1B,gDAAgD;IACzC,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAahE,+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;IAyDlD,+EAA+E;IAC/E,OAAO,CAAC,YAAY;IAQpB,4EAA4E;IAC5E,OAAO,CAAC,QAAQ;IAoChB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAWrC,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

@@ -0,0 +1,281 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqliteVecFragmentIndex = void 0;
+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");
+/** Default name for the fragment `vec0` virtual table. */
+const DEFAULT_TABLE_NAME = 'memory_fragments';
+/** 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 `IFragmentVectorIndex` (from
+ * `@fgv/ts-agent-memory`) — the fragment-granular sibling of
+ * {@link SqliteVecVectorIndex}, and the **durable** counterpart to the in-memory
+ * `InMemoryFragmentCosineIndex`.
+ *
+ * @remarks
+ * Where {@link SqliteVecVectorIndex} keys one vector per record on a
+ * `target_key` primary key, this index holds **many** vectors per record — one per
+ * in-record `[start, end)` span — so it keys the `vec0` table on `target_key` as a
+ * **`PARTITION KEY`** (many rows may share it) and stores each fragment's locator
+ * offsets in two auxiliary columns (`+start_off`, `+end_off`) that ride alongside
+ * the vector and are returned on query but never filtered. A query is a brute-force
+ * `vec0` KNN scan across all partitions returning per-fragment hits, each carrying
+ * its record `target` and the matched `locator`.
+ *
+ * Semantics match `InMemoryFragmentCosineIndex` exactly: `addFragments` is
+ * whole-record-replace (a single transaction deletes every prior fragment of the
+ * target, then inserts the new set), `remove` drops every fragment of a target,
+ * and `query` applies the optional `maxPerRecord` cap **during selection, before
+ * the topK cut** — so one long document cannot crowd others out. The dimension is
+ * established by the first `addFragments` (the `vec0` column is fixed-width) and
+ * recovered from the table schema when a persistent file is reopened; similarity is
+ * 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.
+ * @public
+ */
+class SqliteVecFragmentIndex {
+    constructor(db, table, dimension) {
+        this._db = db;
+        this._table = table;
+        this._dimension = dimension;
+        this._stmts = dimension === undefined ? undefined : this._prepare();
+    }
+    /** The number of records that currently have at least one stored fragment. Zero before the first add. */
+    get recordCount() {
+        if (this._stmts === undefined) {
+            return 0;
+        }
+        // `Number(...)` narrows the count in case the consumer enabled better-sqlite3
+        // 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. */
+    get fragmentCount() {
+        if (this._stmts === undefined) {
+            return 0;
+        }
+        return Number(this._stmts.fragmentCount.get().c);
+    }
+    /**
+     * Family-convention factory. Loads the `sqlite-vec` extension onto the supplied
+     * `better-sqlite3` connection and, if the fragment table already exists (a
+     * reopened persistent file), recovers its established dimension so no
+     * re-embedding is needed on open.
+     *
+     * @param params - See {@link ISqliteVecFragmentIndexCreateParams}.
+     * @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((0, ts_utils_1.fail)(`sqlite-vec fragment index: table name '${table}' is not a simple SQL identifier`));
+        }
+        return Promise.resolve((0, ts_utils_1.captureResult)(() => {
+            (0, sqlite_vec_1.load)(params.database);
+            const dimension = SqliteVecFragmentIndex._readExistingDimension(params.database, table);
+            return new SqliteVecFragmentIndex(params.database, table, dimension);
+        }).withErrorFormat((e) => `sqlite-vec fragment index: failed to initialize: ${e}`));
+    }
+    /** {@inheritDoc IFragmentVectorIndex.addFragments} */
+    addFragments(target, fragments) {
+        const key = (0, ts_agent_memory_1.edgeTargetKey)(target);
+        // 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 —
+        // on a still-dimensionless index — the first fragment's length; it is committed
+        // (via table creation) only once the whole batch validates.
+        let dimension = this._dimension;
+        for (const fragment of fragments) {
+            if (fragment.vector.length === 0) {
+                return Promise.resolve((0, ts_utils_1.fail)(`fragment index: cannot add '${key}': empty fragment vector`));
+            }
+            // Locator offsets are persisted as SQLite integers (bound via BigInt). Reject a
+            // non-safe-integer offset up front with a clear message, rather than letting
+            // `BigInt(nonInteger)` throw cryptically inside the write transaction OR storing
+            // a value the read-side `_toOffset` guard would later reject on every query.
+            if (!Number.isSafeInteger(fragment.locator.start) || !Number.isSafeInteger(fragment.locator.end)) {
+                return Promise.resolve((0, ts_utils_1.fail)(`fragment index: cannot add '${key}': locator [${fragment.locator.start}, ${fragment.locator.end}) offsets must be safe integers`));
+            }
+            if (dimension === undefined) {
+                dimension = fragment.vector.length;
+            }
+            else if (fragment.vector.length !== dimension) {
+                return Promise.resolve((0, ts_utils_1.fail)(`fragment index: cannot add '${key}': fragment dimension ${fragment.vector.length} does not match index dimension ${dimension}`));
+            }
+        }
+        return Promise.resolve((0, ts_utils_1.captureResult)(() => {
+            // A same-target re-author (or an empty batch) still needs the table to exist
+            // to delete prior fragments; create it lazily on the first non-empty add.
+            if (this._stmts === undefined) {
+                if (fragments.length === 0) {
+                    // Nothing stored yet and nothing to store: no table, no work.
+                    return 0;
+                }
+                // `fragments` is non-empty here (the empty case returned above), so the
+                // validation loop proved every fragment shares `fragments[0]`'s length —
+                // which IS the dimension to establish. Read it straight from the first
+                // fragment: no cast, no invariant-dependent narrowing.
+                const established = fragments[0].vector.length;
+                this._createTable(established);
+                this._dimension = established;
+                this._stmts = this._prepare();
+            }
+            this._stmts.replace(key, fragments);
+            return fragments.length;
+        }).withErrorFormat((e) => `fragment index: cannot add '${key}': ${e}`));
+    }
+    /** {@inheritDoc IFragmentVectorIndex.remove} */
+    remove(target) {
+        return Promise.resolve((0, ts_utils_1.captureResult)(() => {
+            // Idempotent: removing a target with no fragments (or before any add created
+            // the table) still succeeds.
+            if (this._stmts !== undefined) {
+                this._stmts.deleteByTarget.run((0, ts_agent_memory_1.edgeTargetKey)(target));
+            }
+            return target;
+        }).withErrorFormat((e) => `fragment index: cannot remove '${(0, ts_agent_memory_1.edgeTargetKey)(target)}': ${e}`));
+    }
+    /** {@inheritDoc IFragmentVectorIndex.query} */
+    query(vector, topK, maxPerRecord) {
+        if (topK <= 0 || this._stmts === undefined) {
+            return Promise.resolve((0, ts_utils_1.succeed)([]));
+        }
+        if (vector.length !== this._dimension) {
+            return Promise.resolve((0, ts_utils_1.fail)(`fragment index: query dimension ${vector.length} does not match index dimension ${this._dimension}`));
+        }
+        const stmts = this._stmts;
+        return Promise.resolve((0, ts_utils_1.captureResult)(() => {
+            var _a;
+            // With a per-record cap the topK winners may lie past the first topK rows (a
+            // 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);
+            if (fetchK <= 0) {
+                return [];
+            }
+            const rows = stmts.query.all(SqliteVecFragmentIndex._toBlob(vector), fetchK);
+            // sqlite-vec returns rows ascending by distance (nearest first); score is
+            // `1 - cosineDistance`, so this order is already descending score.
+            const hits = [];
+            const perRecord = new Map();
+            for (const row of rows) {
+                if (hits.length >= topK) {
+                    break;
+                }
+                if (maxPerRecord !== undefined) {
+                    const used = (_a = perRecord.get(row.target_key)) !== null && _a !== void 0 ? _a : 0;
+                    if (used >= maxPerRecord) {
+                        continue;
+                    }
+                    perRecord.set(row.target_key, used + 1);
+                }
+                const key = row.target_key;
+                hits.push({
+                    target: SqliteVecFragmentIndex._parseKey(key),
+                    score: 1 - row.distance,
+                    locator: {
+                        start: SqliteVecFragmentIndex._toOffset(row.start_off, key),
+                        end: SqliteVecFragmentIndex._toOffset(row.end_off, key)
+                    }
+                });
+            }
+            return hits;
+        }).withErrorFormat((e) => `fragment index: query failed: ${e}`));
+    }
+    /** Create the fragment `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 PARTITION KEY, embedding float[${dimension}] distance_metric=cosine, ` +
+            `+start_off integer, +end_off integer)`);
+    }
+    /** 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, start_off, end_off) VALUES (?, ?, ?, ?)`);
+        // Whole-record replace: drop every prior fragment of the target, then insert the
+        // new set, atomically. An empty set collapses to a pure delete.
+        const replaceTxn = this._db.transaction((key, fragments) => {
+            del.run(key);
+            for (const fragment of fragments) {
+                ins.run(key, SqliteVecFragmentIndex._toBlob(fragment.vector), 
+                // vec0 typed columns reject a JS float; bind the offsets as integers.
+                BigInt(fragment.locator.start), BigInt(fragment.locator.end));
+            }
+        });
+        return {
+            deleteByTarget: del,
+            replace: (key, fragments) => {
+                replaceTxn(key, fragments);
+            },
+            query: this._db.prepare(`SELECT target_key, start_off, end_off, distance FROM "${this._table}" WHERE embedding MATCH ? AND k = ?`),
+            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}"`)
+        };
+    }
+    /**
+     * Recover the established dimension of an existing fragment `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. A key with no
+     * NUL cannot have been written by `edgeTargetKey`; rather than fabricate a wrong
+     * `(scope, id)` from corrupt / externally-edited table data, throw so the query
+     * surfaces it as a loud `Failure`.
+     */
+    static _parseKey(key) {
+        const nul = key.indexOf('\0');
+        if (nul < 0) {
+            throw new Error(`malformed target key '${key}': missing scope/id separator (corrupt persisted data)`);
+        }
+        return {
+            scope: key.slice(0, nul),
+            id: key.slice(nul + 1)
+        };
+    }
+    /**
+     * Coerce a persisted locator offset to a plain `number`. `better-sqlite3` returns
+     * integer columns as `bigint` under safe-integer mode, so an offset can arrive as
+     * either; both narrow to `number` here. A value outside the safe-integer range
+     * (only reachable via corrupt / externally-edited data — the index only ever
+     * writes in-document offsets) throws rather than silently losing precision, so the
+     * query surfaces it as a loud `Failure`.
+     */
+    static _toOffset(value, key) {
+        const n = Number(value);
+        if (!Number.isSafeInteger(n)) {
+            throw new Error(`fragment '${key}': locator offset ${String(value)} is not a safe integer (corrupt persisted data)`);
+        }
+        return n;
+    }
+}
+exports.SqliteVecFragmentIndex = SqliteVecFragmentIndex;
+//# sourceMappingURL=sqliteVecFragmentIndex.js.map