@fgv/ts-agent-memory-sqlite-vec 5.1.0-49 → 5.1.0-51

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

@@ -1,7 +1,11 @@
 import type BetterSqlite3 from 'better-sqlite3';
+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';
 import { IVectorIndex } from '@fgv/ts-agent-memory';
 import { IVectorQueryHit } from '@fgv/ts-agent-memory';
@@ -34,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
@@ -58,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
@@ -97,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 {
@@ -128,12 +229,53 @@ 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>>;
     /** {@inheritDoc IFragmentVectorIndex.addFragments} */
     addFragments(target: IEdgeTarget, fragments: ReadonlyArray<IEmbeddedFragment>): Promise<Result<number>>;
     /** {@inheritDoc IFragmentVectorIndex.remove} */
     remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
+    /** {@inheritDoc IFragmentVectorIndex.has} */
+    has(target: IEdgeTarget): Promise<Result<boolean>>;
+    /** {@inheritDoc IFragmentVectorIndex.rebuild} */
+    rebuild(source: IMemoryRecordSource, embed: FragmentEmbedder, options?: IVectorRebuildOptions): Promise<DetailedResult<IFragmentVectorRebuildReport, IFragmentVectorRebuildReport>>;
+    /**
+     * **Empties the rows; does NOT release the table's declared dimension.** That
+     * is a `vec0` constraint rather than a choice — the dimension is schema, and
+     * there is no `ALTER TABLE` for it — so a rebuild at a new dimension fails
+     * here where it would succeed on the in-memory sibling, which forgets its
+     * dimension on reset. Changing dimension needs a drop-and-re-index; see the
+     * note on `IVectorIndex.rebuild`. Tolerates a table that does not exist yet.
+     */
+    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
@@ -232,9 +374,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 {
@@ -258,8 +404,36 @@ 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>>;
     /** {@inheritDoc IVectorIndex.add} */
     add(target: IEdgeTarget, vector: Float32Array): Promise<Result<string>>;
+    /** {@inheritDoc IVectorIndex.has} */
+    has(target: IEdgeTarget): Promise<Result<boolean>>;
     /** {@inheritDoc IVectorIndex.remove} */
     remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
     /**
@@ -275,13 +449,14 @@ export declare class SqliteVecVectorIndex implements IVectorIndex {
      * a process kill mid-rebuild leaves the table holding neither the old index nor
      * the complete new one, and the remedy is to run `rebuild` again.
      */
-    rebuild(source: IMemoryRecordSource, embed: MemoryEmbedder, options?: IVectorRebuildOptions): Promise<Result<IVectorRebuildReport>>;
+    rebuild(source: IMemoryRecordSource, embed: MemoryEmbedder, options?: IVectorRebuildOptions): Promise<DetailedResult<IVectorRebuildReport, IVectorRebuildReport>>;
     /**
-     * Empty the table. Deliberately does NOT drop it or forget the established
-     * dimension: the `vec0` table's dimension is fixed at creation and a re-embed at
-     * a different dimension needs a drop-and-re-index, which is a consumer decision
-     * (see the package README on `vec0` schema changes), not something a rebuild
-     * should do silently.
+     * **Empties the rows; does NOT release the table's declared dimension.** That
+     * is a `vec0` constraint rather than a choice — the dimension is schema, and
+     * there is no `ALTER TABLE` for it — so a rebuild at a new dimension fails
+     * here where it would succeed on the in-memory sibling, which forgets its
+     * dimension on reset. Changing dimension needs a drop-and-re-index; see the
+     * note on `IVectorIndex.rebuild`.
      */
     private _clear;
     /** {@inheritDoc IVectorIndex.query} */

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"]}

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

@@ -0,0 +1,38 @@
+import { Result } from '@fgv/ts-utils';
+import { Kind } from '@fgv/ts-agent-memory';
+/**
+ * Invoke a consumer-supplied hook that already returns a `Result`, converting a
+ * synchronous throw or a promise rejection into a `Failure` rather than letting
+ * it escape.
+ *
+ * @remarks
+ * Package-internal. `@fgv/ts-agent-memory` carries an identical private copy for
+ * its in-memory indexes. Exporting a single `AsyncDeferredResult`-invoking
+ * primitive from `ts-utils` is the right home and is recorded in
+ * `docs/TECH_DEBT.md`; this module exists because *both* index classes in *this*
+ * package now need it, which is the point at which a second in-package copy stops
+ * being the cheaper thing.
+ */
+export declare function invokeHook<T>(hook: () => Promise<Result<T>>): Promise<Result<T>>;
+/**
+ * Compose the failure that aborted a rebuild with the outcome of the rollback
+ * that followed it.
+ *
+ * @remarks
+ * A rollback that ALSO fails is worth saying out loud: the `'fail'` path promises
+ * an empty index, and a caller that retries against a table which is neither the
+ * old index nor empty is working from a state the contract never described. This
+ * matters more here than in the in-memory package — these tables are **durable**,
+ * so a botched rollback survives the process.
+ */
+export declare function withRollbackNote(error: string, rollback: Result<true>): string;
+/**
+ * Increment `kind`'s tally by `by` (default one).
+ *
+ * @remarks
+ * The `by` parameter exists for the fragment lane, whose `fragments` count
+ * accumulates a fan-out rather than a record count — the one place a rebuild adds
+ * more than one per record.
+ */
+export declare function tally(counts: Map<Kind, number>, kind: Kind, by?: number): void;
+//# sourceMappingURL=rebuildHelpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rebuildHelpers.d.ts","sourceRoot":"","sources":["../../../src/packlets/sqlite-vec-index/rebuildHelpers.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAsB,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAE5C;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAEtF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAE9E;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,GAAE,MAAU,GAAG,IAAI,CAEjF"}

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

@@ -0,0 +1,53 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.invokeHook = invokeHook;
+exports.withRollbackNote = withRollbackNote;
+exports.tally = tally;
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * Invoke a consumer-supplied hook that already returns a `Result`, converting a
+ * synchronous throw or a promise rejection into a `Failure` rather than letting
+ * it escape.
+ *
+ * @remarks
+ * Package-internal. `@fgv/ts-agent-memory` carries an identical private copy for
+ * its in-memory indexes. Exporting a single `AsyncDeferredResult`-invoking
+ * primitive from `ts-utils` is the right home and is recorded in
+ * `docs/TECH_DEBT.md`; this module exists because *both* index classes in *this*
+ * package now need it, which is the point at which a second in-package copy stops
+ * being the cheaper thing.
+ */
+async function invokeHook(hook) {
+    return (await (0, ts_utils_1.captureAsyncResult)(hook)).onSuccess((inner) => inner);
+}
+/**
+ * Compose the failure that aborted a rebuild with the outcome of the rollback
+ * that followed it.
+ *
+ * @remarks
+ * A rollback that ALSO fails is worth saying out loud: the `'fail'` path promises
+ * an empty index, and a caller that retries against a table which is neither the
+ * old index nor empty is working from a state the contract never described. This
+ * matters more here than in the in-memory package — these tables are **durable**,
+ * so a botched rollback survives the process.
+ */
+function withRollbackNote(error, rollback) {
+    return rollback.isFailure() ? `${error} (rollback also failed: ${rollback.message})` : error;
+}
+/**
+ * Increment `kind`'s tally by `by` (default one).
+ *
+ * @remarks
+ * The `by` parameter exists for the fragment lane, whose `fragments` count
+ * accumulates a fan-out rather than a record count — the one place a rebuild adds
+ * more than one per record.
+ */
+function tally(counts, kind, by = 1) {
+    var _a;
+    counts.set(kind, ((_a = counts.get(kind)) !== null && _a !== void 0 ? _a : 0) + by);
+}
+//# sourceMappingURL=rebuildHelpers.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rebuildHelpers.js","sourceRoot":"","sources":["../../../src/packlets/sqlite-vec-index/rebuildHelpers.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAkBH,gCAEC;AAaD,4CAEC;AAUD,sBAEC;AA7CD,4CAA2D;AAG3D;;;;;;;;;;;;GAYG;AACI,KAAK,UAAU,UAAU,CAAI,IAA8B;IAChE,OAAO,CAAC,MAAM,IAAA,6BAAkB,EAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,gBAAgB,CAAC,KAAa,EAAE,QAAsB;IACpE,OAAO,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,2BAA2B,QAAQ,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;AAC/F,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,KAAK,CAAC,MAAyB,EAAE,IAAU,EAAE,KAAa,CAAC;;IACzE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAA,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,mCAAI,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;AACjD,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, captureAsyncResult } from '@fgv/ts-utils';\nimport { Kind } from '@fgv/ts-agent-memory';\n\n/**\n * Invoke a consumer-supplied hook that already returns a `Result`, converting a\n * synchronous throw or a promise rejection into a `Failure` rather than letting\n * it escape.\n *\n * @remarks\n * Package-internal. `@fgv/ts-agent-memory` carries an identical private copy for\n * its in-memory indexes. Exporting a single `AsyncDeferredResult`-invoking\n * primitive from `ts-utils` is the right home and is recorded in\n * `docs/TECH_DEBT.md`; this module exists because *both* index classes in *this*\n * package now need it, which is the point at which a second in-package copy stops\n * being the cheaper thing.\n */\nexport async function invokeHook<T>(hook: () => Promise<Result<T>>): Promise<Result<T>> {\n  return (await captureAsyncResult(hook)).onSuccess((inner) => inner);\n}\n\n/**\n * Compose the failure that aborted a rebuild with the outcome of the rollback\n * that followed it.\n *\n * @remarks\n * A rollback that ALSO fails is worth saying out loud: the `'fail'` path promises\n * an empty index, and a caller that retries against a table which is neither the\n * old index nor empty is working from a state the contract never described. This\n * matters more here than in the in-memory package — these tables are **durable**,\n * so a botched rollback survives the process.\n */\nexport function withRollbackNote(error: string, rollback: Result<true>): string {\n  return rollback.isFailure() ? `${error} (rollback also failed: ${rollback.message})` : error;\n}\n\n/**\n * Increment `kind`'s tally by `by` (default one).\n *\n * @remarks\n * The `by` parameter exists for the fragment lane, whose `fragments` count\n * accumulates a fan-out rather than a record count — the one place a rebuild adds\n * more than one per record.\n */\nexport function tally(counts: Map<Kind, number>, kind: Kind, by: number = 1): void {\n  counts.set(kind, (counts.get(kind) ?? 0) + by);\n}\n"]}