@fgv/ts-agent-memory 5.1.0-36

package/lib/packlets/vector/inMemoryCosineIndex.js

@@ -0,0 +1,154 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryCosineIndex = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * The brute-force, in-memory cosine {@link IVectorIndex}. Stores one
+ * `Float32Array` per record and answers a query by computing cosine similarity
+ * against every stored vector, returning the top-k by descending score.
+ *
+ * @remarks
+ * This is the **complete** vector implementation for the fgv regime — large-N is
+ * explicitly out of scope (the seam stays open for a consumer to swap an external
+ * ANN backend once N grows beyond "thousands of records"). No external dependency
+ * and no ANN structure: a linear scan over a few thousand vectors is well within
+ * an interactive budget.
+ *
+ * The index has a single dimension established by the first vector added; every
+ * subsequent `add` and every `query` vector must match that dimension or fail
+ * loudly — a mismatched dimension is an embedder-wiring bug, never a silent
+ * zero-similarity result. {@link InMemoryCosineIndex.rebuild | rebuild} clears
+ * the index, so a re-embed with a different model (hence dimension) is supported.
+ *
+ * Persistence (a JSON sidecar) is deliberately out of scope for this layer — the
+ * index is in-memory and rebuilt from the store via `rebuild`; a sidecar is a
+ * future nicety.
+ * @public
+ */
+class InMemoryCosineIndex {
+    constructor() {
+        this._vectors = new Map();
+        this._dimension = undefined;
+    }
+    /** The number of vectors currently held. */
+    get size() {
+        return this._vectors.size;
+    }
+    /** Family-convention factory. */
+    static create() {
+        return (0, ts_utils_1.succeed)(new InMemoryCosineIndex());
+    }
+    /** {@inheritDoc IVectorIndex.add} */
+    add(id, vector) {
+        if (vector.length === 0) {
+            return Promise.resolve((0, ts_utils_1.fail)(`vector index: cannot add '${id}': empty vector`));
+        }
+        if (this._dimension === undefined) {
+            this._dimension = vector.length;
+        }
+        else if (vector.length !== this._dimension) {
+            return Promise.resolve((0, ts_utils_1.fail)(`vector index: cannot add '${id}': dimension ${vector.length} does not match index dimension ${this._dimension}`));
+        }
+        // Defensive copy: the caller may reuse or mutate the buffer after `add`, and
+        // the index must keep serving the embedding it was given.
+        this._vectors.set(id, Float32Array.from(vector));
+        // The in-memory index keys entries by id, so the id IS the entry reference.
+        return Promise.resolve((0, ts_utils_1.succeed)(id));
+    }
+    /** {@inheritDoc IVectorIndex.remove} */
+    remove(id) {
+        this._vectors.delete(id);
+        return Promise.resolve((0, ts_utils_1.succeed)(id));
+    }
+    /** {@inheritDoc IVectorIndex.query} */
+    query(vector, topK) {
+        if (topK <= 0 || this._vectors.size === 0) {
+            return Promise.resolve((0, ts_utils_1.succeed)([]));
+        }
+        if (vector.length !== this._dimension) {
+            return Promise.resolve((0, ts_utils_1.fail)(`vector index: query dimension ${vector.length} does not match index dimension ${this._dimension}`));
+        }
+        const queryMagnitude = InMemoryCosineIndex._magnitude(vector);
+        const hits = [];
+        for (const [id, stored] of this._vectors) {
+            hits.push({ id, score: InMemoryCosineIndex._cosine(vector, queryMagnitude, stored) });
+        }
+        // Descending by score; a `seq`-free tiebreak is unnecessary here because the
+        // caller (SemanticRetriever) re-resolves hits against the record index.
+        hits.sort((a, b) => b.score - a.score);
+        return Promise.resolve((0, ts_utils_1.succeed)(hits.length > topK ? hits.slice(0, topK) : hits));
+    }
+    /**
+     * Re-embed every record from `source` and rebuild the index from scratch.
+     * Clears the current contents (and the established dimension) first, so a
+     * re-embed with a different model is supported. Returns the number of vectors
+     * indexed.
+     *
+     * On any failure (list, embed, or add) the index is rolled back to empty
+     * rather than left in a partially-rebuilt state — a caller that retries a query
+     * after a failed rebuild sees a clean empty index, never a half-populated one.
+     *
+     * @param source - The record source to re-embed (an {@link IMemoryStore}
+     * satisfies this structurally).
+     * @param embed - The embedder applied to each record.
+     */
+    async rebuild(source, embed) {
+        // Reset up front so the "any failure leaves the index empty" contract holds
+        // even when the listing itself fails (no stale vectors survive a failed
+        // rebuild).
+        this._reset();
+        const listed = await source.list();
+        if (listed.isFailure()) {
+            return (0, ts_utils_1.fail)(`vector index rebuild: failed to list records: ${listed.message}`);
+        }
+        for (const record of listed.value) {
+            const embedded = await embed(record);
+            if (embedded.isFailure()) {
+                this._reset();
+                return (0, ts_utils_1.fail)(`vector index rebuild: embedding '${record.envelope.id}' failed: ${embedded.message}`);
+            }
+            const added = await this.add(record.envelope.id, embedded.value);
+            if (added.isFailure()) {
+                this._reset();
+                return (0, ts_utils_1.fail)(`vector index rebuild: ${added.message}`);
+            }
+        }
+        return (0, ts_utils_1.succeed)(this._vectors.size);
+    }
+    /** Empty the index and forget the established dimension. */
+    _reset() {
+        this._vectors.clear();
+        this._dimension = undefined;
+    }
+    /** The Euclidean magnitude (L2 norm) of a vector. */
+    static _magnitude(vector) {
+        let sum = 0;
+        for (let i = 0; i < vector.length; i++) {
+            sum += vector[i] * vector[i];
+        }
+        return Math.sqrt(sum);
+    }
+    /**
+     * Cosine similarity between the query (whose magnitude is precomputed once and
+     * reused across the scan) and a stored vector. A zero-magnitude vector on
+     * either side yields `0` rather than `NaN` — a degenerate vector is simply
+     * maximally dissimilar, not an error.
+     */
+    static _cosine(query, queryMagnitude, stored) {
+        const storedMagnitude = InMemoryCosineIndex._magnitude(stored);
+        if (queryMagnitude === 0 || storedMagnitude === 0) {
+            return 0;
+        }
+        let dot = 0;
+        for (let i = 0; i < query.length; i++) {
+            dot += query[i] * stored[i];
+        }
+        return dot / (queryMagnitude * storedMagnitude);
+    }
+}
+exports.InMemoryCosineIndex = InMemoryCosineIndex;
+//# sourceMappingURL=inMemoryCosineIndex.js.map

package/lib/packlets/vector/inMemoryCosineIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inMemoryCosineIndex.js","sourceRoot":"","sources":["../../../src/packlets/vector/inMemoryCosineIndex.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, fail, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord, MemoryId } from '../types';\nimport { IMemoryRecordSource, IVectorIndex, IVectorQueryHit, MemoryEmbedder } from './vectorIndex';\n\n/**\n * The brute-force, in-memory cosine {@link IVectorIndex}. Stores one\n * `Float32Array` per record and answers a query by computing cosine similarity\n * against every stored vector, returning the top-k by descending score.\n *\n * @remarks\n * This is the **complete** vector implementation for the fgv regime — large-N is\n * explicitly out of scope (the seam stays open for a consumer to swap an external\n * ANN backend once N grows beyond \"thousands of records\"). No external dependency\n * and no ANN structure: a linear scan over a few thousand vectors is well within\n * an interactive budget.\n *\n * The index has a single dimension established by the first vector added; every\n * subsequent `add` and every `query` vector must match that dimension or fail\n * loudly — a mismatched dimension is an embedder-wiring bug, never a silent\n * zero-similarity result. {@link InMemoryCosineIndex.rebuild | rebuild} clears\n * the index, so a re-embed with a different model (hence dimension) is supported.\n *\n * Persistence (a JSON sidecar) is deliberately out of scope for this layer — the\n * index is in-memory and rebuilt from the store via `rebuild`; a sidecar is a\n * future nicety.\n * @public\n */\nexport class InMemoryCosineIndex implements IVectorIndex {\n  private readonly _vectors: Map<MemoryId, Float32Array>;\n  /** The dimension of every stored vector; `undefined` until the first `add`. */\n  private _dimension: number | undefined;\n\n  private constructor() {\n    this._vectors = new Map<MemoryId, Float32Array>();\n    this._dimension = undefined;\n  }\n\n  /** The number of vectors currently held. */\n  public get size(): number {\n    return this._vectors.size;\n  }\n\n  /** Family-convention factory. */\n  public static create(): Result<InMemoryCosineIndex> {\n    return succeed(new InMemoryCosineIndex());\n  }\n\n  /** {@inheritDoc IVectorIndex.add} */\n  public add(id: MemoryId, vector: Float32Array): Promise<Result<string>> {\n    if (vector.length === 0) {\n      return Promise.resolve(fail(`vector index: cannot add '${id}': empty vector`));\n    }\n    if (this._dimension === undefined) {\n      this._dimension = vector.length;\n    } else if (vector.length !== this._dimension) {\n      return Promise.resolve(\n        fail(\n          `vector index: cannot add '${id}': dimension ${vector.length} does not match index dimension ${this._dimension}`\n        )\n      );\n    }\n    // Defensive copy: the caller may reuse or mutate the buffer after `add`, and\n    // the index must keep serving the embedding it was given.\n    this._vectors.set(id, Float32Array.from(vector));\n    // The in-memory index keys entries by id, so the id IS the entry reference.\n    return Promise.resolve(succeed(id as string));\n  }\n\n  /** {@inheritDoc IVectorIndex.remove} */\n  public remove(id: MemoryId): Promise<Result<MemoryId>> {\n    this._vectors.delete(id);\n    return Promise.resolve(succeed(id));\n  }\n\n  /** {@inheritDoc IVectorIndex.query} */\n  public query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>> {\n    if (topK <= 0 || this._vectors.size === 0) {\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    const queryMagnitude: number = InMemoryCosineIndex._magnitude(vector);\n    const hits: IVectorQueryHit[] = [];\n    for (const [id, stored] of this._vectors) {\n      hits.push({ id, score: InMemoryCosineIndex._cosine(vector, queryMagnitude, stored) });\n    }\n    // Descending by score; a `seq`-free tiebreak is unnecessary here because the\n    // caller (SemanticRetriever) re-resolves hits against the record index.\n    hits.sort((a, b) => b.score - a.score);\n    return Promise.resolve(succeed(hits.length > topK ? hits.slice(0, topK) : hits));\n  }\n\n  /**\n   * Re-embed every record from `source` and rebuild the index from scratch.\n   * Clears the current contents (and the established dimension) first, so a\n   * re-embed with a different model is supported. Returns the number of vectors\n   * indexed.\n   *\n   * On any failure (list, embed, or add) the index is rolled back to empty\n   * rather than left in a partially-rebuilt state — a caller that retries a query\n   * after a failed rebuild sees a clean empty index, never a half-populated one.\n   *\n   * @param source - The record source to re-embed (an {@link IMemoryStore}\n   * satisfies this structurally).\n   * @param embed - The embedder applied to each record.\n   */\n  public async rebuild(source: IMemoryRecordSource, embed: MemoryEmbedder): Promise<Result<number>> {\n    // Reset up front so the \"any failure leaves the index empty\" contract holds\n    // even when the listing itself fails (no stale vectors survive a failed\n    // rebuild).\n    this._reset();\n    const listed: Result<ReadonlyArray<IMemoryRecord<unknown>>> = await source.list();\n    if (listed.isFailure()) {\n      return fail(`vector index rebuild: failed to list records: ${listed.message}`);\n    }\n    for (const record of listed.value) {\n      const embedded: Result<Float32Array> = await embed(record);\n      if (embedded.isFailure()) {\n        this._reset();\n        return fail(`vector index rebuild: embedding '${record.envelope.id}' failed: ${embedded.message}`);\n      }\n      const added: Result<string> = await this.add(record.envelope.id, embedded.value);\n      if (added.isFailure()) {\n        this._reset();\n        return fail(`vector index rebuild: ${added.message}`);\n      }\n    }\n    return succeed(this._vectors.size);\n  }\n\n  /** Empty the index and forget the established dimension. */\n  private _reset(): void {\n    this._vectors.clear();\n    this._dimension = undefined;\n  }\n\n  /** The Euclidean magnitude (L2 norm) of a vector. */\n  private static _magnitude(vector: Float32Array): number {\n    let sum: number = 0;\n    for (let i: number = 0; i < vector.length; i++) {\n      sum += vector[i] * vector[i];\n    }\n    return Math.sqrt(sum);\n  }\n\n  /**\n   * Cosine similarity between the query (whose magnitude is precomputed once and\n   * reused across the scan) and a stored vector. A zero-magnitude vector on\n   * either side yields `0` rather than `NaN` — a degenerate vector is simply\n   * maximally dissimilar, not an error.\n   */\n  private static _cosine(query: Float32Array, queryMagnitude: number, stored: Float32Array): number {\n    const storedMagnitude: number = InMemoryCosineIndex._magnitude(stored);\n    if (queryMagnitude === 0 || storedMagnitude === 0) {\n      return 0;\n    }\n    let dot: number = 0;\n    for (let i: number = 0; i < query.length; i++) {\n      dot += query[i] * stored[i];\n    }\n    return dot / (queryMagnitude * storedMagnitude);\n  }\n}\n"]}

package/lib/packlets/vector/index.d.ts

@@ -0,0 +1,3 @@
+export * from './vectorIndex';
+export * from './inMemoryCosineIndex';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/vector/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/vector/index.ts"],"names":[],"mappings":"AAKA,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC"}

package/lib/packlets/vector/index.js

@@ -0,0 +1,23 @@
+"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("./vectorIndex"), exports);
+__exportStar(require("./inMemoryCosineIndex"), exports);
+//# sourceMappingURL=index.js.map

package/lib/packlets/vector/index.js.map

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

package/lib/packlets/vector/vectorIndex.d.ts

@@ -0,0 +1,68 @@
+import { Result } from '@fgv/ts-utils';
+import { IMemoryRecord, MemoryId } from '../types';
+/**
+ * A single hit returned by {@link IVectorIndex.query}: the matched record id and
+ * the backend's similarity score (higher = more similar; the exact scale is
+ * backend-defined). Hits are returned in descending score order.
+ * @public
+ */
+export interface IVectorQueryHit {
+    /** The id of the matched record. */
+    readonly id: MemoryId;
+    /** Backend similarity score; higher is more similar. */
+    readonly score: number;
+}
+/**
+ * The vector-index seam an embedding backend implements to make
+ * {@link SemanticRetriever | semantic recall} operational.
+ *
+ * @remarks
+ * Vectors cross this seam as `Float32Array` (the in-memory representation an
+ * embedding model produces); `number[]` is reserved for the JSON-wire edges
+ * (e.g. a provider's embedding response). The in-package brute-force cosine
+ * implementation is {@link InMemoryCosineIndex}; a consumer can swap an external
+ * ANN backend behind the same seam once N grows beyond the in-memory regime.
+ *
+ * Every operation returns a `Result` (async, since a real backend does I/O) so
+ * failure is explicit and never throws across the seam.
+ * @public
+ */
+export interface IVectorIndex {
+    /**
+     * Add (or replace) the embedding for `id`. Returns the opaque
+     * {@link IMemoryEnvelope.embeddingRef | embeddingRef} the store stamps onto
+     * the envelope so a later read knows the record is embedded.
+     */
+    add(id: MemoryId, vector: Float32Array): Promise<Result<string>>;
+    /**
+     * Remove the embedding for `id`. Returns the removed id. Idempotent — removing
+     * an id with no embedding still succeeds (returns the id).
+     */
+    remove(id: MemoryId): Promise<Result<MemoryId>>;
+    /**
+     * Return the `topK` nearest records to `vector`, in descending score order.
+     */
+    query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+}
+/**
+ * Embeds a complete record into a vector for the store's embed-on-write hook.
+ * Async and `Result`-returning, since a real embedder does a network call (cloud
+ * provider) or in-process model inference. The consumer wires this — the core
+ * package never calls an embedding provider directly, staying embedder-agnostic.
+ * @public
+ */
+export type MemoryEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<Float32Array>>;
+/**
+ * The minimal record-source surface {@link InMemoryCosineIndex.rebuild} reads to
+ * re-embed an entire vault. {@link IMemoryStore} satisfies it structurally (its
+ * `list` accepts an optional filter, which is assignable to this no-argument
+ * shape), so a consumer passes the store directly — without the vector packlet
+ * taking a dependency on the store packlet (which depends on the vector packlet
+ * for {@link IVectorIndex}, so the reverse import would be a cycle).
+ * @public
+ */
+export interface IMemoryRecordSource {
+    /** List every record in the vault. */
+    list(): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+}
+//# sourceMappingURL=vectorIndex.d.ts.map

package/lib/packlets/vector/vectorIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vectorIndex.d.ts","sourceRoot":"","sources":["../../../src/packlets/vector/vectorIndex.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,oCAAoC;IACpC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,GAAG,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAEjE;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEhD;;OAEG;IACH,KAAK,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;CAC5F;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;AAE/F;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,sCAAsC;IACtC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;CAChE"}

package/lib/packlets/vector/vectorIndex.js

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

package/lib/packlets/vector/vectorIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vectorIndex.js","sourceRoot":"","sources":["../../../src/packlets/vector/vectorIndex.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result } from '@fgv/ts-utils';\nimport { IMemoryRecord, MemoryId } from '../types';\n\n/**\n * A single hit returned by {@link IVectorIndex.query}: the matched record id and\n * the backend's similarity score (higher = more similar; the exact scale is\n * backend-defined). Hits are returned in descending score order.\n * @public\n */\nexport interface IVectorQueryHit {\n  /** The id of the matched record. */\n  readonly id: MemoryId;\n  /** Backend similarity score; higher is more similar. */\n  readonly score: number;\n}\n\n/**\n * The vector-index seam an embedding backend implements to make\n * {@link SemanticRetriever | semantic recall} operational.\n *\n * @remarks\n * Vectors cross this seam as `Float32Array` (the in-memory representation an\n * embedding model produces); `number[]` is reserved for the JSON-wire edges\n * (e.g. a provider's embedding response). The in-package brute-force cosine\n * implementation is {@link InMemoryCosineIndex}; a consumer can swap an external\n * ANN backend behind the same seam once N grows beyond the in-memory regime.\n *\n * Every operation returns a `Result` (async, since a real backend does I/O) so\n * failure is explicit and never throws across the seam.\n * @public\n */\nexport interface IVectorIndex {\n  /**\n   * Add (or replace) the embedding for `id`. Returns the opaque\n   * {@link IMemoryEnvelope.embeddingRef | embeddingRef} the store stamps onto\n   * the envelope so a later read knows the record is embedded.\n   */\n  add(id: MemoryId, vector: Float32Array): Promise<Result<string>>;\n\n  /**\n   * Remove the embedding for `id`. Returns the removed id. Idempotent — removing\n   * an id with no embedding still succeeds (returns the id).\n   */\n  remove(id: MemoryId): Promise<Result<MemoryId>>;\n\n  /**\n   * Return the `topK` nearest records to `vector`, in descending score order.\n   */\n  query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;\n}\n\n/**\n * Embeds a complete record into a vector for the store's embed-on-write hook.\n * Async and `Result`-returning, since a real embedder does a network call (cloud\n * provider) or in-process model inference. The consumer wires this — the core\n * package never calls an embedding provider directly, staying embedder-agnostic.\n * @public\n */\nexport type MemoryEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<Float32Array>>;\n\n/**\n * The minimal record-source surface {@link InMemoryCosineIndex.rebuild} reads to\n * re-embed an entire vault. {@link IMemoryStore} satisfies it structurally (its\n * `list` accepts an optional filter, which is assignable to this no-argument\n * shape), so a consumer passes the store directly — without the vector packlet\n * taking a dependency on the store packlet (which depends on the vector packlet\n * for {@link IVectorIndex}, so the reverse import would be a cycle).\n * @public\n */\nexport interface IMemoryRecordSource {\n  /** List every record in the vault. */\n  list(): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;\n}\n"]}

package/lib/test/unit/converters/bodyConverterRegistry.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=bodyConverterRegistry.test.d.ts.map

package/lib/test/unit/converters/bodyConverterRegistry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bodyConverterRegistry.test.d.ts","sourceRoot":"","sources":["../../../../src/test/unit/converters/bodyConverterRegistry.test.ts"],"names":[],"mappings":"AAKA,OAAO,oBAAoB,CAAC"}

package/lib/test/unit/converters/bodyConverterRegistry.test.js

@@ -0,0 +1,74 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+require("@fgv/ts-utils-jest");
+const ts_utils_1 = require("@fgv/ts-utils");
+const ts_json_base_1 = require("@fgv/ts-json-base");
+const converters_1 = require("../../../packlets/converters");
+const knowledgeKind = 'knowledge';
+const profileKind = 'profile';
+describe('BodyConverterRegistry', () => {
+    let registry;
+    beforeEach(() => {
+        registry = converters_1.BodyConverterRegistry.create().orThrow();
+    });
+    test('create succeeds', () => {
+        expect(converters_1.BodyConverterRegistry.create()).toSucceed();
+    });
+    describe('register / has / convert', () => {
+        test('registers a Converter and converts a matching body', () => {
+            registry.register(knowledgeKind, ts_utils_1.Converters.string);
+            expect(registry.has(knowledgeKind)).toBe(true);
+            expect(registry.convert(knowledgeKind, 'a knowledge doc')).toSucceedWith('a knowledge doc');
+        });
+        test('a registered Converter rejects an invalid body', () => {
+            registry.register(knowledgeKind, ts_utils_1.Converters.string);
+            expect(registry.convert(knowledgeKind, 42)).toFail();
+        });
+        test('has returns false for an unregistered kind', () => {
+            expect(registry.has(knowledgeKind)).toBe(false);
+        });
+        test('convert fails for an unregistered kind', () => {
+            expect(registry.convert(knowledgeKind, 'x')).toFailWith(/no converter registered for kind 'knowledge'/i);
+        });
+        test('register replaces a prior registration for the same kind', () => {
+            registry.register(knowledgeKind, ts_utils_1.Converters.string);
+            registry.register(knowledgeKind, ts_utils_1.Converters.number);
+            expect(registry.convert(knowledgeKind, 7)).toSucceedWith(7);
+            expect(registry.convert(knowledgeKind, 'x')).toFail();
+        });
+    });
+    describe('getConverter', () => {
+        test('returns the registered converter', () => {
+            registry.register(knowledgeKind, ts_utils_1.Converters.string);
+            expect(registry.getConverter(knowledgeKind)).toSucceedAndSatisfy((converter) => {
+                expect(converter.convert('hello')).toSucceedWith('hello');
+            });
+        });
+        test('fails for an unregistered kind', () => {
+            expect(registry.getConverter(knowledgeKind)).toFailWith(/no converter registered for kind/i);
+        });
+    });
+    describe('registerSchema', () => {
+        const profileSchema = ts_json_base_1.JsonSchema.object({
+            name: ts_json_base_1.JsonSchema.string(),
+            age: ts_json_base_1.JsonSchema.integer()
+        });
+        test('registers a JsonSchema validator and validates a matching body', () => {
+            registry.registerSchema(profileKind, profileSchema);
+            expect(registry.has(profileKind)).toBe(true);
+            expect(registry.convert(profileKind, { name: 'Ada', age: 36 })).toSucceedWith({
+                name: 'Ada',
+                age: 36
+            });
+        });
+        test('a registered schema rejects an invalid body', () => {
+            registry.registerSchema(profileKind, profileSchema);
+            expect(registry.convert(profileKind, { name: 'Ada' })).toFail();
+        });
+    });
+});
+//# sourceMappingURL=bodyConverterRegistry.test.js.map

package/lib/test/unit/converters/bodyConverterRegistry.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bodyConverterRegistry.test.js","sourceRoot":"","sources":["../../../../src/test/unit/converters/bodyConverterRegistry.test.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport '@fgv/ts-utils-jest';\nimport { Converters } from '@fgv/ts-utils';\nimport { JsonSchema } from '@fgv/ts-json-base';\nimport { BodyConverterRegistry } from '../../../packlets/converters';\nimport { Kind } from '../../../packlets/types';\n\nconst knowledgeKind: Kind = 'knowledge' as Kind;\nconst profileKind: Kind = 'profile' as Kind;\n\ndescribe('BodyConverterRegistry', () => {\n  let registry: BodyConverterRegistry;\n\n  beforeEach(() => {\n    registry = BodyConverterRegistry.create().orThrow();\n  });\n\n  test('create succeeds', () => {\n    expect(BodyConverterRegistry.create()).toSucceed();\n  });\n\n  describe('register / has / convert', () => {\n    test('registers a Converter and converts a matching body', () => {\n      registry.register(knowledgeKind, Converters.string);\n      expect(registry.has(knowledgeKind)).toBe(true);\n      expect(registry.convert(knowledgeKind, 'a knowledge doc')).toSucceedWith('a knowledge doc');\n    });\n\n    test('a registered Converter rejects an invalid body', () => {\n      registry.register(knowledgeKind, Converters.string);\n      expect(registry.convert(knowledgeKind, 42)).toFail();\n    });\n\n    test('has returns false for an unregistered kind', () => {\n      expect(registry.has(knowledgeKind)).toBe(false);\n    });\n\n    test('convert fails for an unregistered kind', () => {\n      expect(registry.convert(knowledgeKind, 'x')).toFailWith(\n        /no converter registered for kind 'knowledge'/i\n      );\n    });\n\n    test('register replaces a prior registration for the same kind', () => {\n      registry.register(knowledgeKind, Converters.string);\n      registry.register(knowledgeKind, Converters.number);\n      expect(registry.convert(knowledgeKind, 7)).toSucceedWith(7);\n      expect(registry.convert(knowledgeKind, 'x')).toFail();\n    });\n  });\n\n  describe('getConverter', () => {\n    test('returns the registered converter', () => {\n      registry.register(knowledgeKind, Converters.string);\n      expect(registry.getConverter(knowledgeKind)).toSucceedAndSatisfy((converter) => {\n        expect(converter.convert('hello')).toSucceedWith('hello');\n      });\n    });\n\n    test('fails for an unregistered kind', () => {\n      expect(registry.getConverter(knowledgeKind)).toFailWith(/no converter registered for kind/i);\n    });\n  });\n\n  describe('registerSchema', () => {\n    const profileSchema = JsonSchema.object({\n      name: JsonSchema.string(),\n      age: JsonSchema.integer()\n    });\n\n    test('registers a JsonSchema validator and validates a matching body', () => {\n      registry.registerSchema(profileKind, profileSchema);\n      expect(registry.has(profileKind)).toBe(true);\n      expect(registry.convert(profileKind, { name: 'Ada', age: 36 })).toSucceedWith({\n        name: 'Ada',\n        age: 36\n      });\n    });\n\n    test('a registered schema rejects an invalid body', () => {\n      registry.registerSchema(profileKind, profileSchema);\n      expect(registry.convert(profileKind, { name: 'Ada' })).toFail();\n    });\n  });\n});\n"]}

package/lib/test/unit/converters/envelopeConverter.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=envelopeConverter.test.d.ts.map

package/lib/test/unit/converters/envelopeConverter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelopeConverter.test.d.ts","sourceRoot":"","sources":["../../../../src/test/unit/converters/envelopeConverter.test.ts"],"names":[],"mappings":"AAKA,OAAO,oBAAoB,CAAC"}

package/lib/test/unit/converters/envelopeConverter.test.js

@@ -0,0 +1,198 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+require("@fgv/ts-utils-jest");
+const ts_utils_1 = require("@fgv/ts-utils");
+const converters_1 = require("../../../packlets/converters");
+const validEnvelopeObject = {
+    id: 'intro-to-rust',
+    entityId: 'intro-to-rust',
+    kind: 'knowledge',
+    tags: ['rust', 'systems'],
+    links: [{ type: 'related', target: 'ownership' }],
+    created: 1000,
+    updated: 2000,
+    seq: 5,
+    contentHash: 'crc-abc',
+    provenance: { source: 'agent', by: 'curator' }
+};
+describe('provenanceConverter', () => {
+    test('validates the known fields', () => {
+        expect(converters_1.provenanceConverter.convert({ source: 'human', by: 'erik', model: 'gpt', confidence: 0.9 })).toSucceedWith({ source: 'human', by: 'erik', model: 'gpt', confidence: 0.9 });
+    });
+    test('preserves opaque extension keys verbatim', () => {
+        expect(converters_1.provenanceConverter.convert({ source: 'agent', sentiment: { score: 0.5 }, epistemic: 'belief' })).toSucceedAndSatisfy((p) => {
+            expect(p.source).toBe('agent');
+            expect(p.sentiment).toEqual({ score: 0.5 });
+            expect(p.epistemic).toBe('belief');
+        });
+    });
+    test('accepts an arbitrary source string (open vocabulary)', () => {
+        expect(converters_1.provenanceConverter.convert({ source: 'host-ingest' })).toSucceedWith({ source: 'host-ingest' });
+    });
+    test('fails when source is missing', () => {
+        expect(converters_1.provenanceConverter.convert({ by: 'erik' })).toFail();
+    });
+    test('fails on a non-object', () => {
+        expect(converters_1.provenanceConverter.convert('nope')).toFail();
+    });
+});
+describe('edgeConverter', () => {
+    test('validates a full attributed edge', () => {
+        expect(converters_1.edgeConverter.convert({
+            type: 'mtm-ref',
+            target: 'turn-3',
+            confidence: 0.8,
+            provenance: { source: 'agent' },
+            valid_at: 100,
+            invalid_at: 200
+        })).toSucceedAndSatisfy((edge) => {
+            expect(edge.type).toBe('mtm-ref');
+            expect(edge.target).toBe('turn-3');
+            expect(edge.confidence).toBe(0.8);
+            expect(edge.provenance).toEqual({ source: 'agent' });
+            expect(edge.valid_at).toBe(100);
+            expect(edge.invalid_at).toBe(200);
+        });
+    });
+    test('validates a minimal edge', () => {
+        expect(converters_1.edgeConverter.convert({ type: 'related', target: 'ownership' })).toSucceedAndSatisfy((edge) => {
+            expect(edge.type).toBe('related');
+            expect(edge.target).toBe('ownership');
+            expect(edge.confidence).toBeUndefined();
+        });
+    });
+    test('accepts a null invalid_at (still valid)', () => {
+        expect(converters_1.edgeConverter.convert({ type: 'related', target: 'x', invalid_at: null })).toSucceedAndSatisfy((edge) => {
+            expect(edge.invalid_at).toBeNull();
+        });
+    });
+    test('fails when invalid_at is neither a number nor null', () => {
+        expect(converters_1.edgeConverter.convert({ type: 'related', target: 'x', invalid_at: 'soon' })).toFail();
+    });
+    test('fails when target is missing', () => {
+        expect(converters_1.edgeConverter.convert({ type: 'related' })).toFail();
+    });
+});
+describe('temporalConverter', () => {
+    test('validates a temporal block', () => {
+        expect(converters_1.temporalConverter.convert({ valid_at: 1, invalid_at: null })).toSucceedWith({
+            valid_at: 1,
+            invalid_at: null
+        });
+    });
+    test('validates an empty temporal block', () => {
+        expect(converters_1.temporalConverter.convert({})).toSucceedWith({});
+    });
+});
+describe('envelopeConverter', () => {
+    test('validates a full envelope without optional blocks', () => {
+        expect(converters_1.envelopeConverter.convert(validEnvelopeObject)).toSucceedAndSatisfy((envelope) => {
+            expect(envelope.id).toBe('intro-to-rust');
+            expect(envelope.tags).toEqual(['rust', 'systems']);
+            expect(envelope.links).toHaveLength(1);
+            expect(envelope.temporal).toBeUndefined();
+            expect(envelope.embeddingRef).toBeUndefined();
+        });
+    });
+    test('validates a temporal envelope with a string embeddingRef', () => {
+        expect(converters_1.envelopeConverter.convert(Object.assign(Object.assign({}, validEnvelopeObject), { temporal: { valid_at: 10 }, embeddingRef: 'vec-1' }))).toSucceedAndSatisfy((envelope) => {
+            expect(envelope.temporal).toEqual({ valid_at: 10 });
+            expect(envelope.embeddingRef).toBe('vec-1');
+        });
+    });
+    test('accepts a null embeddingRef (not embedded)', () => {
+        expect(converters_1.envelopeConverter.convert(Object.assign(Object.assign({}, validEnvelopeObject), { embeddingRef: null }))).toSucceedAndSatisfy((envelope) => {
+            expect(envelope.embeddingRef).toBeNull();
+        });
+    });
+    test('fails when embeddingRef is neither a string nor null', () => {
+        expect(converters_1.envelopeConverter.convert(Object.assign(Object.assign({}, validEnvelopeObject), { embeddingRef: 42 }))).toFail();
+    });
+    test('fails when a required field is missing', () => {
+        const missing = Object.assign({}, validEnvelopeObject);
+        delete missing.contentHash;
+        expect(converters_1.envelopeConverter.convert(missing)).toFail();
+    });
+});
+describe('envelopeYamlConverter', () => {
+    test('parses an envelope from a YAML string', () => {
+        const yaml = (0, converters_1.serializeMemoryFile)(converters_1.envelopeConverter.convert(validEnvelopeObject).orThrow(), 'body text').orThrow();
+        const frontmatter = (0, converters_1.splitFrontmatter)(yaml).orThrow().frontmatter;
+        expect(converters_1.envelopeYamlConverter.convert(frontmatter)).toSucceedAndSatisfy((envelope) => {
+            expect(envelope.id).toBe('intro-to-rust');
+        });
+    });
+    test('fails on a YAML string that is not an object', () => {
+        expect(converters_1.envelopeYamlConverter.convert('just a scalar')).toFail();
+    });
+});
+describe('splitFrontmatter / joinFrontmatter', () => {
+    test('splits a well-formed memory file', () => {
+        const raw = '---\nid: x\nkind: knowledge\n---\nThe body.\nSecond line.';
+        expect((0, converters_1.splitFrontmatter)(raw)).toSucceedWith({
+            frontmatter: 'id: x\nkind: knowledge',
+            body: 'The body.\nSecond line.'
+        });
+    });
+    test('strips trailing CR so CRLF-authored files parse identically to LF', () => {
+        const raw = '---\r\nid: x\r\nkind: knowledge\r\n---\r\nThe body.\r\nSecond line.';
+        expect((0, converters_1.splitFrontmatter)(raw)).toSucceedWith({
+            frontmatter: 'id: x\nkind: knowledge',
+            body: 'The body.\nSecond line.'
+        });
+    });
+    test('fails when the opening delimiter is missing', () => {
+        expect((0, converters_1.splitFrontmatter)('no frontmatter here')).toFailWith(/missing opening frontmatter delimiter/i);
+    });
+    test('fails when the closing delimiter is missing', () => {
+        expect((0, converters_1.splitFrontmatter)('---\nid: x\nstill going')).toFailWith(/missing closing frontmatter delimiter/i);
+    });
+    test('join adds a trailing newline to the frontmatter when absent', () => {
+        expect((0, converters_1.joinFrontmatter)('id: x', 'body')).toBe('---\nid: x\n---\nbody');
+    });
+    test('join does not double the trailing newline when present', () => {
+        expect((0, converters_1.joinFrontmatter)('id: x\n', 'body')).toBe('---\nid: x\n---\nbody');
+    });
+    test('split and join round-trip', () => {
+        const raw = '---\nid: x\n---\nbody content';
+        const parts = (0, converters_1.splitFrontmatter)(raw).orThrow();
+        expect((0, converters_1.joinFrontmatter)(parts.frontmatter, parts.body)).toBe(raw);
+    });
+});
+describe('parseMemoryFile / serializeMemoryFile', () => {
+    let registry;
+    const knowledgeKind = 'knowledge';
+    beforeEach(() => {
+        registry = converters_1.BodyConverterRegistry.create().orThrow();
+        registry.register(knowledgeKind, ts_utils_1.Converters.string);
+    });
+    test('serializes then parses a record round-trip', () => {
+        const envelope = converters_1.envelopeConverter.convert(validEnvelopeObject).orThrow();
+        const file = (0, converters_1.serializeMemoryFile)(envelope, 'The knowledge body.').orThrow();
+        expect((0, converters_1.parseMemoryFile)(file, registry)).toSucceedAndSatisfy((record) => {
+            expect(record.envelope.id).toBe('intro-to-rust');
+            expect(record.body).toBe('The knowledge body.');
+        });
+    });
+    test('fails when the frontmatter cannot be split', () => {
+        expect((0, converters_1.parseMemoryFile)('no delimiters', registry)).toFailWith(/missing opening frontmatter delimiter/i);
+    });
+    test('fails with envelope context when the envelope is invalid', () => {
+        const file = '---\nid: x\n---\nbody';
+        expect((0, converters_1.parseMemoryFile)(file, registry)).toFailWith(/invalid envelope/i);
+    });
+    test('fails with body context when the body fails the registered converter', () => {
+        const envelope = converters_1.envelopeConverter.convert(Object.assign(Object.assign({}, validEnvelopeObject), { kind: 'unregistered' })).orThrow();
+        const file = (0, converters_1.serializeMemoryFile)(envelope, 'body').orThrow();
+        expect((0, converters_1.parseMemoryFile)(file, registry)).toFailWith(/invalid body.*no converter registered/i);
+    });
+    test('serialize fails (with id context) when the envelope cannot be dumped to YAML', () => {
+        const unserializable = Object.assign(Object.assign({}, validEnvelopeObject), { weird: BigInt(10) });
+        expect((0, converters_1.serializeMemoryFile)(unserializable, 'body')).toFailWith(/failed to serialize envelope/i);
+    });
+});
+//# sourceMappingURL=envelopeConverter.test.js.map