docsgov 0.1.0

package/dist/dedup/embedder/constants.js

@@ -0,0 +1,10 @@
+/**
+ * Model is the HuggingFace model identifier used for embedding.
+ * The sentence-transformers/ prefix is load-bearing for parity against the
+ * Python POC (fastembed wraps this same ONNX model). Changing this constant
+ * invalidates the stored index — indexdb detects the mismatch and purges the
+ * sections table automatically.
+ */
+export const Model = "sentence-transformers/paraphrase-multilingual-mpnet-base-v2";
+/** Dimension is the output embedding dimension for the above model. */
+export const Dimension = 768;

package/dist/dedup/embedder/embedder.js

@@ -0,0 +1,76 @@
+// Package embedder wraps a transformers.js feature-extraction pipeline to
+// provide mean-pooled, L2-normalized embeddings from the
+// sentence-transformers/paraphrase-multilingual-mpnet-base-v2 model.
+//
+// The embedder model is auto-downloaded on first use to a configurable cache
+// directory (see NewOptions.cacheDir, the DOCGOV_MODEL_CACHE env var, or the
+// default ~/.cache/docgov/models/<sanitized-model-name>/).
+import { cacheDir } from "./cache.js";
+import { Dimension, Model } from "./constants.js";
+import { InferenceError } from "./errors.js";
+import { Session } from "./session.js";
+/**
+ * Embedder wraps a transformers.js feature-extraction pipeline.
+ *
+ * It is NOT safe for concurrent use; callers should serialize embed calls (the
+ * indexer does this by design).
+ */
+export class Embedder {
+    sess;
+    constructor(sess) {
+        this.sess = sess;
+    }
+    /**
+     * newEmbedder creates a new Embedder. It fully initialises the pipeline and
+     * tokenizer before returning — no lazy initialization. Callers must call
+     * {@link close} when done.
+     *
+     * If the model is not cached, this downloads it from Hugging Face Hub, which
+     * can take 30+ seconds on first run.
+     */
+    static async newEmbedder(opts = {}) {
+        const dir = cacheDir(opts.cacheDir ?? "");
+        const sess = await Session.newSession(dir);
+        return new Embedder(sess);
+    }
+    /**
+     * embed encodes texts into mean-pooled, L2-normalized float vectors of length
+     * {@link Dimension}. Returns an empty array for empty input.
+     *
+     * Inference failures are wrapped as {@link InferenceError}.
+     */
+    async embed(texts) {
+        if (texts.length === 0) {
+            return [];
+        }
+        if (this.sess === null) {
+            throw new Error("embedder.embed: embedder is closed");
+        }
+        try {
+            return await this.sess.embed(texts);
+        }
+        catch (cause) {
+            throw new InferenceError(undefined, { cause });
+        }
+    }
+    /** name returns the model identifier ({@link Model}). */
+    name() {
+        return Model;
+    }
+    /** dimension returns the output embedding dimension ({@link Dimension}). */
+    dimension() {
+        return Dimension;
+    }
+    /**
+     * close releases resources held by the embedder. Idempotent: a second close
+     * is a no-op. After close, embed throws.
+     */
+    async close() {
+        if (this.sess === null) {
+            return;
+        }
+        const sess = this.sess;
+        this.sess = null;
+        await sess.destroy();
+    }
+}

package/dist/dedup/embedder/embedder.mock.test.js

@@ -0,0 +1,128 @@
+// Behavior tests for Embedder, the public facade over Session, with the model
+// mocked so no ~1GB download happens. The real-model parity/golden gate stays
+// in embedder.test.ts (DOCGOV_EMBED_E2E) and is intentionally untouched.
+//
+// vi.mock is hoisted above the imports and intercepts the dynamic
+// `await import("@huggingface/transformers")` inside session.ts, so
+// Embedder.newEmbedder runs against the fake pipeline below.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Dimension, Model } from "./constants.js";
+import { Embedder } from "./embedder.js";
+import { InferenceError } from "./errors.js";
+const mockState = vi.hoisted(() => {
+    return {
+        // inferThrows: when set, the pipe rejects at inference time, which
+        // Embedder.embed must wrap as InferenceError.
+        inferThrows: null,
+        env: { cacheDir: "" },
+    };
+});
+function l2row(i, dim) {
+    const v = new Array(dim).fill(0);
+    v[i % dim] = 1.0;
+    return v;
+}
+vi.mock("@huggingface/transformers", () => {
+    const env = mockState.env;
+    const pipeline = async (_task, _model) => {
+        return async (texts, _opts) => {
+            if (mockState.inferThrows)
+                throw mockState.inferThrows;
+            const rows = texts.map((_, i) => l2row(i, Dimension));
+            return {
+                data: new Float32Array(rows.flat()),
+                dims: [texts.length, Dimension],
+                tolist: () => rows,
+            };
+        };
+    };
+    return { pipeline, env };
+});
+const tmpDirs = [];
+function newCacheDir() {
+    const d = mkdtempSync(join(tmpdir(), "embedder-cache-"));
+    tmpDirs.push(d);
+    return d;
+}
+beforeEach(() => {
+    mockState.inferThrows = null;
+    mockState.env.cacheDir = "";
+});
+afterEach(() => {
+    for (const d of tmpDirs.splice(0))
+        rmSync(d, { recursive: true, force: true });
+});
+describe("Embedder", () => {
+    // WHY: newEmbedder must fully initialise (no lazy init) and expose a usable
+    // embedder; the dedup Index path depends on this returning a ready object.
+    it("newEmbedder returns a ready embedder reporting the pinned name/dimension", async () => {
+        const emb = await Embedder.newEmbedder({ cacheDir: newCacheDir() });
+        try {
+            // WHY: indexdb keys the stored index on name()+dimension(); they must echo
+            // the pinned constants exactly or a stored index is silently invalidated.
+            expect(emb.name()).toBe(Model);
+            expect(emb.dimension()).toBe(Dimension);
+        }
+        finally {
+            await emb.close();
+        }
+    });
+    // WHY: an empty batch must short-circuit to [] without touching the session —
+    // the indexer relies on this to skip work for empty inputs.
+    it("embed returns [] for an empty batch", async () => {
+        const emb = await Embedder.newEmbedder({ cacheDir: newCacheDir() });
+        try {
+            expect(await emb.embed([])).toEqual([]);
+        }
+        finally {
+            await emb.close();
+        }
+    });
+    // WHY: the success path must yield one Dimension-vector per input, in order —
+    // the shape the indexer persists and the analyzer compares.
+    it("embed returns one Dimension-vector per input", async () => {
+        const emb = await Embedder.newEmbedder({ cacheDir: newCacheDir() });
+        try {
+            const vecs = await emb.embed(["a", "b"]);
+            expect(vecs).toHaveLength(2);
+            for (const v of vecs)
+                expect(v).toHaveLength(Dimension);
+        }
+        finally {
+            await emb.close();
+        }
+    });
+    // WHY: inference failures must be wrapped as the matchable InferenceError
+    // sentinel (with the original cause attached), not leak a raw transformers
+    // error — the CLI distinguishes inference failures from other errors by type.
+    it("embed wraps an inference failure as InferenceError", async () => {
+        const emb = await Embedder.newEmbedder({ cacheDir: newCacheDir() });
+        try {
+            const cause = new Error("onnx runtime exploded");
+            mockState.inferThrows = cause;
+            await expect(emb.embed(["a"])).rejects.toBeInstanceOf(InferenceError);
+            mockState.inferThrows = cause;
+            await expect(emb.embed(["a"])).rejects.toMatchObject({ cause });
+        }
+        finally {
+            await emb.close();
+        }
+    });
+    // WHY: after close, embed must throw loudly — reusing a closed embedder is a
+    // lifecycle bug; silently returning nothing would corrupt the index.
+    it("embed throws after close", async () => {
+        const emb = await Embedder.newEmbedder({ cacheDir: newCacheDir() });
+        await emb.close();
+        await expect(emb.embed(["a"])).rejects.toThrow(/embedder is closed/);
+    });
+    // WHY: the indexer's defer/cleanup may close twice; a second close must be a
+    // no-op so cleanup never throws.
+    it("close is idempotent", async () => {
+        const emb = await Embedder.newEmbedder({ cacheDir: newCacheDir() });
+        await emb.close();
+        await expect(emb.close()).resolves.toBeUndefined();
+    });
+});

package/dist/dedup/embedder/embedder.test.js

@@ -0,0 +1,96 @@
+import { readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it, test } from "vitest";
+import { Dimension, Embedder, Model } from "./index.js";
+// WHY (Go embedder_test.go: TestConstants): the sentence-transformers/ prefix
+// and 768 dimension are load-bearing for cross-POC parity. A drift here
+// silently invalidates every stored index.
+test("Model and Dimension constants are pinned for parity", () => {
+    expect(Model).not.toBe("");
+    expect(Model.startsWith("sentence-transformers/")).toBe(true);
+    expect(Dimension).toBe(768);
+});
+function l2norm(v) {
+    let sum = 0;
+    for (const x of v)
+        sum += x * x;
+    return Math.sqrt(sum);
+}
+function cosine(a, b) {
+    if (a.length !== b.length)
+        return 0;
+    let dot = 0;
+    for (let i = 0; i < a.length; i++)
+        dot += (a[i] ?? 0) * (b[i] ?? 0);
+    return dot;
+}
+// E2E inference is gated by DOCGOV_EMBED_E2E because it downloads the model
+// (~1GB). Bit-parity vs Go is already proven (maxAbsDiff 3.6e-8 in the spike),
+// so default CI runs only the fast unit suites above and below.
+const e2e = process.env.DOCGOV_EMBED_E2E ? describe : describe.skip;
+e2e("real inference (DOCGOV_EMBED_E2E)", () => {
+    let emb;
+    let dir;
+    beforeEach(async () => {
+        dir = join(tmpdir(), `docgov-embed-${process.pid}-${Date.now()}`);
+        emb = await Embedder.newEmbedder({ cacheDir: dir });
+    });
+    afterEach(async () => {
+        if (emb)
+            await emb.close();
+    });
+    // WHY (TestNew_NameAndDimension): callers (indexdb) key the stored index on
+    // name()+dimension(); they must echo the pinned constants exactly.
+    it("reports the pinned name and dimension", () => {
+        expect(emb.name()).toBe(Model);
+        expect(emb.dimension()).toBe(Dimension);
+    });
+    // WHY (TestEmbed_OutputShape): downstream cosine math assumes one 768-vec per
+    // input, in order. A batch reshape bug would scramble section identity.
+    it("returns one 768-vector per input, in order", async () => {
+        const texts = ["hello world", "test sentence"];
+        const vecs = await emb.embed(texts);
+        expect(vecs).toHaveLength(texts.length);
+        for (const v of vecs)
+            expect(v).toHaveLength(Dimension);
+    });
+    // WHY (TestEmbed_L2Normalized): the index compares vectors by dot product as
+    // a stand-in for cosine; that identity only holds if vectors are unit-norm.
+    // Includes a CJK string to lock multilingual normalization.
+    it("produces L2-normalized vectors (incl. CJK input)", async () => {
+        const vecs = await emb.embed([
+            "The quick brown fox jumps over the lazy dog",
+            "補貨單流程",
+        ]);
+        for (const v of vecs) {
+            expect(Math.abs(l2norm(v) - 1)).toBeLessThan(1e-4);
+        }
+    });
+    // WHY (TestEmbed_EmptyBatch): the indexer may pass an empty batch; it must
+    // get an empty result, not an error or a stray vector.
+    it("returns an empty result for an empty batch", async () => {
+        expect(await emb.embed([])).toEqual([]);
+    });
+    // WHY (TestEmbed_SentinelStability): asserts the embedder reproduces the
+    // committed golden vectors (cosine >= 0.9999). This is the parity anchor —
+    // the goldens come from the Go embedder, so this is the cross-port check.
+    it("matches the committed golden vectors (cosine >= 0.9999)", async () => {
+        const goldenPath = join(fileURLToPath(new URL(".", import.meta.url)), "..", "..", "..", "..", "internal", "dedup", "embedder", "testdata", "sentinel_vectors.json");
+        const entries = JSON.parse(await readFile(goldenPath, "utf8"));
+        expect(entries.length).toBeGreaterThan(0);
+        const vecs = await emb.embed(entries.map((e) => e.text));
+        entries.forEach((e, i) => {
+            const got = vecs[i];
+            expect(got).toBeDefined();
+            expect(cosine(got, e.vector)).toBeGreaterThanOrEqual(0.9999);
+        });
+    });
+    // WHY (TestClose_Idempotent): the indexer's defer/cleanup may close twice; a
+    // second close must not throw.
+    it("close is idempotent", async () => {
+        await emb.close();
+        await expect(emb.close()).resolves.toBeUndefined();
+    });
+});

package/dist/dedup/embedder/errors.js

@@ -0,0 +1,20 @@
+// Sentinel errors for the embedder package.
+//
+// In Go these are `var ErrModelDownload = errors.New(...)` sentinels matched
+// with errors.Is. In TS they are Error subclasses so callers can match with
+// `instanceof`. The underlying cause is attached via the standard Error
+// `cause` option (mirroring Go's %v inner message in the formatted string).
+/** ErrModelDownload is returned when the embedding model cannot be downloaded. */
+export class ModelDownloadError extends Error {
+    constructor(message = "embedder: model download failed", options) {
+        super(message, options);
+        this.name = "ModelDownloadError";
+    }
+}
+/** ErrInference is returned when inference fails. */
+export class InferenceError extends Error {
+    constructor(message = "embedder: inference failed", options) {
+        super(message, options);
+        this.name = "InferenceError";
+    }
+}

package/dist/dedup/embedder/errors.test.js

@@ -0,0 +1,35 @@
+import { expect, test } from "vitest";
+import { InferenceError, ModelDownloadError } from "./errors.js";
+// WHY (Go sentinel_test.go: TestSentinels_NonNil): a nil/undefined sentinel
+// would break every error match silently. The TS analogue: the error classes
+// must be constructible and instanceof-matchable.
+test("sentinel error classes are constructible and instanceof-matchable", () => {
+    const dl = new ModelDownloadError();
+    const inf = new InferenceError();
+    expect(dl).toBeInstanceOf(ModelDownloadError);
+    expect(dl).toBeInstanceOf(Error);
+    expect(inf).toBeInstanceOf(InferenceError);
+    expect(inf).toBeInstanceOf(Error);
+});
+// WHY (Go embedder.go default messages): the message text mirrors Go's
+// errors.New strings so log output reads the same across the two ports.
+test("sentinel errors carry their Go-equivalent default messages", () => {
+    expect(new ModelDownloadError().message).toBe("embedder: model download failed");
+    expect(new InferenceError().message).toBe("embedder: inference failed");
+});
+// WHY (Go sentinel_test.go: TestEmbed_ErrInferenceIsReachable): the Go code
+// wraps with "%w: %v" so errors.Is(err, ErrInference) is true while the inner
+// cause is NOT separately errors.Is-comparable (it lives only in the message).
+// The faithful TS contract: the thrown error is `instanceof InferenceError`
+// (the sentinel stays matchable) AND the underlying cause is preserved on
+// `.cause` for diagnostics — distinct from the sentinel identity.
+test("InferenceError stays matchable while preserving the wrapped cause", () => {
+    const cause = new Error("ort runtime: session failed");
+    const err = new InferenceError(undefined, { cause });
+    // Sentinel remains matchable (Go: errors.Is(err, ErrInference) == true).
+    expect(err).toBeInstanceOf(InferenceError);
+    // The cause is NOT the sentinel itself (Go: errors.Is(err, cause) == false),
+    // but is retained for diagnostics on the standard .cause slot.
+    expect(err.cause).toBe(cause);
+    expect(err).not.toBe(cause);
+});

package/dist/dedup/embedder/index.js

@@ -0,0 +1,4 @@
+export { Model, Dimension } from "./constants.js";
+export { Embedder } from "./embedder.js";
+export { ModelDownloadError, InferenceError } from "./errors.js";
+export { cacheDir } from "./cache.js";

package/dist/dedup/embedder/session.js

@@ -0,0 +1,78 @@
+import { mkdir } from "node:fs/promises";
+import { Dimension, Model } from "./constants.js";
+import { ModelDownloadError } from "./errors.js";
+/**
+ * Session wraps a transformers.js feature-extraction pipeline.
+ *
+ * It is the TS analogue of Go's hugotSession: it owns the loaded model and
+ * exposes embed/destroy. Isolated here so the public Embedder type stays thin.
+ */
+export class Session {
+    pipe;
+    constructor(pipe) {
+        this.pipe = pipe;
+    }
+    /**
+     * newSession downloads (if needed) and initialises the pipeline.
+     *
+     * The model is auto-downloaded on first use into modelCacheDir. This can take
+     * 30+ seconds on first run. Mirrors Go's newHugotSession including the
+     * cache-dir creation and a dry-run inference to verify initialisation.
+     */
+    static async newSession(modelCacheDir) {
+        // Ensure cache dir exists (Go: os.MkdirAll, 0o755).
+        await mkdir(modelCacheDir, { recursive: true });
+        // Point transformers.js at our cache dir before loading. Setting it on the
+        // shared `env` is how transformers.js controls where HF models land.
+        const { pipeline, env } = await import("@huggingface/transformers");
+        env.cacheDir = modelCacheDir;
+        let pipe;
+        try {
+            pipe = (await pipeline("feature-extraction", Model));
+        }
+        catch (cause) {
+            throw new ModelDownloadError(undefined, { cause });
+        }
+        // Dry-run inference to verify the pipeline is fully initialized.
+        await pipe(["init"], { pooling: "mean", normalize: true });
+        return new Session(pipe);
+    }
+    /** embed runs inference and returns mean-pooled, L2-normalized vectors. */
+    async embed(texts) {
+        if (texts.length === 0) {
+            return [];
+        }
+        if (this.pipe === null) {
+            throw new Error("embedder.Session.embed: session is closed");
+        }
+        const out = await this.pipe(texts, { pooling: "mean", normalize: true });
+        return reshape(out, texts.length);
+    }
+    /** destroy releases the pipeline reference. */
+    async destroy() {
+        const pipe = this.pipe;
+        this.pipe = null;
+        if (pipe?.dispose) {
+            await pipe.dispose();
+        }
+    }
+}
+/**
+ * reshape converts the [batch, Dimension] feature-extraction tensor into a
+ * number[][]. tolist() yields the nested array directly; we validate the batch
+ * count and per-row dimension so a model/pooling mismatch fails loudly rather
+ * than silently producing the wrong shape.
+ */
+function reshape(out, want) {
+    const rows = out.tolist();
+    if (rows.length !== want) {
+        throw new Error(`embedder: expected ${want} vectors, got ${rows.length}`);
+    }
+    for (let i = 0; i < rows.length; i++) {
+        const row = rows[i];
+        if (row === undefined || row.length !== Dimension) {
+            throw new Error(`embedder: vector ${i} has length ${row?.length ?? 0}, want ${Dimension}`);
+        }
+    }
+    return rows;
+}

package/dist/dedup/embedder/session.test.js

@@ -0,0 +1,172 @@
+// Behavior tests for Session, the transformers.js pipeline wrapper, with the
+// model mocked so no ~1GB download happens. The real-model parity gate lives in
+// embedder.test.ts (DOCGOV_EMBED_E2E) and is intentionally untouched.
+//
+// vi.mock is hoisted above the imports and intercepts BOTH the static and the
+// dynamic `await import("@huggingface/transformers")` that session.ts performs,
+// so Session.newSession runs entirely against the fake pipeline below.
+import { existsSync } from "node:fs";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Dimension } from "./constants.js";
+import { ModelDownloadError } from "./errors.js";
+import { Session } from "./session.js";
+// --- mock state ------------------------------------------------------------
+// mockState is shared, mutable hoisted state so each test can steer the fake
+// pipeline (rows it returns, whether it throws, whether it has dispose()).
+const mockState = vi.hoisted(() => {
+    return {
+        // pipelineThrows: when set, the mocked `pipeline()` factory rejects, which
+        // is how session.ts surfaces a ModelDownloadError.
+        pipelineThrows: null,
+        // rowCount/rowDim override the shape the pipe returns, to drive reshape's
+        // batch-count and per-row dimension guards. null = match the request.
+        rowCount: null,
+        rowDim: null,
+        // dispose is attached to the returned pipe when set, to exercise destroy().
+        dispose: null,
+        // capturedCacheDir records env.cacheDir at pipeline() time so we can assert
+        // newSession pointed transformers.js at our temp dir before loading.
+        capturedCacheDir: "",
+        env: { cacheDir: "" },
+    };
+});
+// l2row returns a deterministic, L2-normalized vector of length `dim`. The
+// single non-zero entry keeps it unit-norm for free and varies by `i` so
+// distinct inputs get distinct vectors (matters for the dedup Index drive-through).
+function l2row(i, dim) {
+    const v = new Array(dim).fill(0);
+    v[i % dim] = 1.0;
+    return v;
+}
+vi.mock("@huggingface/transformers", () => {
+    const env = mockState.env;
+    const pipeline = async (_task, _model) => {
+        if (mockState.pipelineThrows) {
+            throw mockState.pipelineThrows;
+        }
+        // Record the cache dir as configured by newSession (env.cacheDir is set
+        // between import and the pipeline() call).
+        mockState.capturedCacheDir = env.cacheDir;
+        const pipe = async (texts, _opts) => {
+            const n = mockState.rowCount ?? texts.length;
+            const dim = mockState.rowDim ?? Dimension;
+            const rows = [];
+            for (let i = 0; i < n; i++)
+                rows.push(l2row(i, dim));
+            const flat = new Float32Array(rows.flat());
+            return {
+                data: flat,
+                dims: [n, dim],
+                tolist: () => rows,
+            };
+        };
+        if (mockState.dispose) {
+            pipe.dispose =
+                mockState.dispose;
+        }
+        return pipe;
+    };
+    return { pipeline, env };
+});
+// --- temp dirs -------------------------------------------------------------
+const tmpDirs = [];
+function newCacheDir() {
+    const d = mkdtempSync(join(tmpdir(), "session-cache-"));
+    tmpDirs.push(d);
+    return d;
+}
+beforeEach(() => {
+    mockState.pipelineThrows = null;
+    mockState.rowCount = null;
+    mockState.rowDim = null;
+    mockState.dispose = null;
+    mockState.capturedCacheDir = "";
+    mockState.env.cacheDir = "";
+});
+afterEach(() => {
+    for (const d of tmpDirs.splice(0))
+        rmSync(d, { recursive: true, force: true });
+});
+describe("Session.newSession", () => {
+    // WHY: newSession must create the cache dir AND point transformers.js at it
+    // before loading, so models land in the caller's chosen dir (not the host
+    // cache). A regression that skipped env.cacheDir would race CI on a shared
+    // cache; we assert both the dir exists and the pipeline saw it.
+    it("creates the cache dir and sets env.cacheDir before loading", async () => {
+        const dir = join(newCacheDir(), "nested", "models");
+        const sess = await Session.newSession(dir);
+        expect(existsSync(dir)).toBe(true);
+        expect(mockState.capturedCacheDir).toBe(dir);
+        // A usable session can embed (the dry-run inference already proved init).
+        expect(await sess.embed(["x"])).toHaveLength(1);
+    });
+    // WHY: a download/init failure must be surfaced as the matchable
+    // ModelDownloadError sentinel, not a raw transformers error — the CLI keys
+    // its "could not download the model" guidance on this type.
+    it("throws ModelDownloadError when the pipeline factory fails", async () => {
+        mockState.pipelineThrows = new Error("network down");
+        const dir = newCacheDir();
+        await expect(Session.newSession(dir)).rejects.toBeInstanceOf(ModelDownloadError);
+    });
+});
+describe("Session.embed", () => {
+    // WHY: the indexer may hand an empty batch; it must get [] back with no call
+    // into the pipeline — a stray vector or an error would corrupt the index.
+    it("returns [] for an empty batch", async () => {
+        const sess = await Session.newSession(newCacheDir());
+        expect(await sess.embed([])).toEqual([]);
+    });
+    // WHY: the core contract — one Dimension-length vector per input, in order.
+    // Downstream cosine math assumes this exact shape and ordering.
+    it("returns one Dimension-vector per input", async () => {
+        const sess = await Session.newSession(newCacheDir());
+        const vecs = await sess.embed(["a", "b", "c"]);
+        expect(vecs).toHaveLength(3);
+        for (const v of vecs)
+            expect(v).toHaveLength(Dimension);
+    });
+    // WHY: embedding after destroy must fail loudly rather than silently
+    // returning nothing — a closed session reused by mistake is a bug to surface.
+    it("throws when the session is closed", async () => {
+        const sess = await Session.newSession(newCacheDir());
+        await sess.destroy();
+        await expect(sess.embed(["a"])).rejects.toThrow(/session is closed/);
+    });
+    // WHY: a pooling/model mismatch that yields the wrong number of rows must
+    // fail loudly — silently returning the wrong count would scramble section
+    // identity in the index.
+    it("throws when the pipeline returns the wrong batch count", async () => {
+        const sess = await Session.newSession(newCacheDir());
+        mockState.rowCount = 1; // request 2, get 1
+        await expect(sess.embed(["a", "b"])).rejects.toThrow(/expected 2 vectors, got 1/);
+    });
+    // WHY: a per-row dimension mismatch (wrong model / no mean-pooling) must also
+    // fail loudly; a 767- or 769-dim row would silently break the index schema.
+    it("throws when a row has the wrong dimension", async () => {
+        const sess = await Session.newSession(newCacheDir());
+        mockState.rowDim = Dimension - 1;
+        await expect(sess.embed(["a"])).rejects.toThrow(new RegExp(`length ${Dimension - 1}, want ${Dimension}`));
+    });
+});
+describe("Session.destroy", () => {
+    // WHY: destroy must call dispose() on backends that expose it (releasing the
+    // ONNX session), so long-lived processes don't leak native memory.
+    it("invokes dispose() when the pipeline exposes it", async () => {
+        const dispose = vi.fn(async () => { });
+        mockState.dispose = dispose;
+        const sess = await Session.newSession(newCacheDir());
+        await sess.destroy();
+        expect(dispose).toHaveBeenCalledTimes(1);
+    });
+    // WHY: destroy must be safe on a pipeline without dispose() — not every
+    // backend exposes it; a hard requirement would crash cleanup.
+    it("is a no-op-safe when the pipeline has no dispose()", async () => {
+        const sess = await Session.newSession(newCacheDir());
+        await expect(sess.destroy()).resolves.toBeUndefined();
+        // A second destroy after the reference is cleared must also not throw.
+        await expect(sess.destroy()).resolves.toBeUndefined();
+    });
+});