@graphorin/embedder-ollama 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @graphorin/embedder-ollama
 
+## 0.7.0
+
+### Minor Changes
+
+- [#154](https://github.com/o-stepper/graphorin/pull/154) [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04) Thanks [@o-stepper](https://github.com/o-stepper)! - W-072: every export map's `import` condition becomes `default`, and the Node floor rises to `>=22.12.0`.
+
+  CJS consumers previously hit a bewildering `ERR_PACKAGE_PATH_NOT_EXPORTED` instead of a clear ESM-only signal. With the `default` condition, plain `require('@graphorin/core')` works via Node's stable `require(esm)` - which shipped in 22.12, hence the engines bump across every workspace manifest (packages, examples, benchmarks, docs; enforced by the widened mvp-readiness sweep). No dual-instance hazard: there is no CJS build, `require()` returns the same ESM module instance. ESM consumers are unaffected (`default` serves both paths; `types` stays first). The pack gate now runs attw under the full `node16` profile (was `esm-only`) and adds a runtime `require(esm)` smoke against the packed tarballs. Installs on Node 22.0-22.11 with `engine-strict` will refuse - upgrade Node (see the migration guide).
+
+### Patch Changes
+
+- [#164](https://github.com/o-stepper/graphorin/pull/164) [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00) Thanks [@o-stepper](https://github.com/o-stepper)! - Tarballs now ship `src/` so the published `dist/**/*.d.ts.map` files actually work (W-136): the maps referenced `../src/*.ts` that the `files` whitelist excluded, so go-to-definition fell back into `.d.ts` and the shipped maps were dead weight. The pack gate gains a `map-integrity` leg: every source referenced by a shipped map must resolve inside the tarball (or be embedded via `sourcesContent`), with an anti-vacuous guard - a package whose tsdown config emits declaration maps must contain a non-zero number of `.d.ts.map` files, so a cache-restored dist that silently dropped maps fails the gate instead of passing vacuously. `mvp-readiness` now requires `src` in every publishable `files` array.
+
+- [#164](https://github.com/o-stepper/graphorin/pull/164) [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00) Thanks [@o-stepper](https://github.com/o-stepper)! - Every published package now declares its tree-shaking contract via `sideEffects` (W-137): 18 packages audited to a pure module scope get `false`, the CLI declares its bin entry (`["./dist/bin/*"]`), and `@graphorin/security` gets an explicit `true` - its secrets subsystem registers built-in resolvers and the SecretValue caller-context provider at import time, so marking it pure would let bundlers drop those registrations. `mvp-readiness` now fails any publishable manifest without a declared `sideEffects`, closing the drift for future packages.
+
+- Updated dependencies [[`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`832f22e`](https://github.com/o-stepper/graphorin/commit/832f22e570b8c3175c1adeb4c150070cbd131534), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04)]:
+  - @graphorin/core@0.7.0
+
 ## 0.6.1
 
 ### Patch Changes

package/README.md

@@ -75,4 +75,4 @@ MIT © 2026 Oleksiy Stepurenko.
 
 ---
 
-**Project Graphorin** · v0.6.1 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>
+**Project Graphorin** · v0.7.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.6.1";
+var version = "0.7.0";
 
 //#endregion
 export { version };

package/dist/package.js.map

@@ -1 +1 @@
-{"version":3,"file":"package.js","names":[],"sources":["../package.json"],"sourcesContent":["{\n  \"name\": \"@graphorin/embedder-ollama\",\n  \"version\": \"0.6.1\",\n  \"description\": \"First-class opt-in alternative to @graphorin/embedder-transformersjs for the Graphorin framework. Wraps the local Ollama HTTP API to produce dense embeddings via models such as `nomic-embed-text` (768-dim, multilingual default), `mxbai-embed-large` (1024-dim), `snowflake-arctic-embed` (1024-dim), and `bge-m3` (1024-dim). Implements the `EmbedderProvider` contract with a deterministic configHash that includes the model digest reported by `POST /api/show`, so a model upgrade in the same Ollama instance produces a different embedder_id and the multi-table per-embedder vec0 layout in `@graphorin/store-sqlite` triggers a clean migration path.\",\n  \"license\": \"MIT\",\n  \"author\": \"Oleksiy Stepurenko\",\n  \"homepage\": \"https://github.com/o-stepper/graphorin/tree/main/packages/embedder-ollama\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/o-stepper/graphorin.git\",\n    \"directory\": \"packages/embedder-ollama\"\n  },\n  \"bugs\": {\n    \"url\": \"https://github.com/o-stepper/graphorin/issues\"\n  },\n  \"keywords\": [\n    \"graphorin\",\n    \"ai\",\n    \"agents\",\n    \"framework\",\n    \"embeddings\",\n    \"ollama\",\n    \"nomic-embed-text\",\n    \"bge-m3\",\n    \"local-first\"\n  ],\n  \"type\": \"module\",\n  \"engines\": {\n    \"node\": \">=22.0.0\"\n  },\n  \"main\": \"./dist/index.js\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"import\": \"./dist/index.js\"\n    },\n    \"./package.json\": \"./package.json\"\n  },\n  \"files\": [\n    \"dist\",\n    \"README.md\",\n    \"CHANGELOG.md\",\n    \"LICENSE\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsdown\",\n    \"typecheck\": \"tsc --noEmit && tsc -p tsconfig.tests.json\",\n    \"test\": \"vitest run\",\n    \"lint\": \"biome check .\",\n    \"clean\": \"rimraf dist .turbo *.tsbuildinfo\"\n  },\n  \"dependencies\": {\n    \"@graphorin/core\": \"workspace:*\"\n  },\n  \"publishConfig\": {\n    \"access\": \"public\",\n    \"provenance\": true\n  },\n  \"devDependencies\": {\n    \"@graphorin/store-sqlite\": \"workspace:*\"\n  }\n}\n"],"mappings":";cAEa"}
+{"version":3,"file":"package.js","names":[],"sources":["../package.json"],"sourcesContent":["{\n  \"name\": \"@graphorin/embedder-ollama\",\n  \"version\": \"0.7.0\",\n  \"description\": \"First-class opt-in alternative to @graphorin/embedder-transformersjs for the Graphorin framework. Wraps the local Ollama HTTP API to produce dense embeddings via models such as `nomic-embed-text` (768-dim, multilingual default), `mxbai-embed-large` (1024-dim), `snowflake-arctic-embed` (1024-dim), and `bge-m3` (1024-dim). Implements the `EmbedderProvider` contract with a deterministic configHash that includes the model digest reported by `POST /api/show`, so a model upgrade in the same Ollama instance produces a different embedder_id and the multi-table per-embedder vec0 layout in `@graphorin/store-sqlite` triggers a clean migration path.\",\n  \"license\": \"MIT\",\n  \"author\": \"Oleksiy Stepurenko\",\n  \"homepage\": \"https://github.com/o-stepper/graphorin/tree/main/packages/embedder-ollama\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/o-stepper/graphorin.git\",\n    \"directory\": \"packages/embedder-ollama\"\n  },\n  \"bugs\": {\n    \"url\": \"https://github.com/o-stepper/graphorin/issues\"\n  },\n  \"keywords\": [\n    \"graphorin\",\n    \"ai\",\n    \"agents\",\n    \"framework\",\n    \"embeddings\",\n    \"ollama\",\n    \"nomic-embed-text\",\n    \"bge-m3\",\n    \"local-first\"\n  ],\n  \"type\": \"module\",\n  \"sideEffects\": false,\n  \"engines\": {\n    \"node\": \">=22.12.0\"\n  },\n  \"main\": \"./dist/index.js\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"default\": \"./dist/index.js\"\n    },\n    \"./package.json\": \"./package.json\"\n  },\n  \"files\": [\n    \"dist\",\n    \"src\",\n    \"README.md\",\n    \"CHANGELOG.md\",\n    \"LICENSE\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsdown\",\n    \"typecheck\": \"tsc --noEmit && tsc -p tsconfig.tests.json\",\n    \"test\": \"vitest run\",\n    \"lint\": \"biome check .\",\n    \"clean\": \"rimraf dist .turbo *.tsbuildinfo\"\n  },\n  \"dependencies\": {\n    \"@graphorin/core\": \"workspace:*\"\n  },\n  \"publishConfig\": {\n    \"access\": \"public\",\n    \"provenance\": true\n  },\n  \"devDependencies\": {\n    \"@graphorin/store-sqlite\": \"workspace:*\"\n  }\n}\n"],"mappings":";cAEa"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphorin/embedder-ollama",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "First-class opt-in alternative to @graphorin/embedder-transformersjs for the Graphorin framework. Wraps the local Ollama HTTP API to produce dense embeddings via models such as `nomic-embed-text` (768-dim, multilingual default), `mxbai-embed-large` (1024-dim), `snowflake-arctic-embed` (1024-dim), and `bge-m3` (1024-dim). Implements the `EmbedderProvider` contract with a deterministic configHash that includes the model digest reported by `POST /api/show`, so a model upgrade in the same Ollama instance produces a different embedder_id and the multi-table per-embedder vec0 layout in `@graphorin/store-sqlite` triggers a clean migration path.",
   "license": "MIT",
   "author": "Oleksiy Stepurenko",
@@ -25,8 +25,9 @@
     "local-first"
   ],
   "type": "module",
+  "sideEffects": false,
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -34,25 +35,26 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "default": "./dist/index.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@graphorin/core": "0.6.1"
+    "@graphorin/core": "0.7.0"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "devDependencies": {
-    "@graphorin/store-sqlite": "0.6.1"
+    "@graphorin/store-sqlite": "0.7.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/index.ts

@@ -0,0 +1,404 @@
+/**
+ * @graphorin/embedder-ollama - first-class opt-in alternative embedder
+ * for the Graphorin framework. Wraps the local Ollama HTTP API.
+ *
+ * @packageDocumentation
+ */
+
+import { createHash } from 'node:crypto';
+import type { EmbedderProvider, EmbedOptions } from '@graphorin/core/contracts';
+
+/** Canonical version constant, derived from `package.json` at build time. */
+import pkg from '../package.json' with { type: 'json' };
+
+export const VERSION: string = pkg.version;
+
+/**
+ * Default Ollama base URL. Operators that run Ollama on a non-default
+ * port pass an explicit `baseUrl`.
+ *
+ * @stable
+ */
+export const DEFAULT_OLLAMA_BASE_URL = 'http://127.0.0.1:11434';
+
+/**
+ * Default Ollama model. Matches the de-facto choice in the Ollama
+ * community for general-purpose multilingual embeddings.
+ *
+ * @stable
+ */
+export const DEFAULT_OLLAMA_MODEL = 'nomic-embed-text';
+
+/**
+ * Options accepted by {@link createOllamaEmbedder}.
+ *
+ * @stable
+ */
+export interface OllamaEmbedderOptions {
+  /** Default `'nomic-embed-text'`. */
+  readonly model?: string;
+  /** Default `'http://127.0.0.1:11434'`. */
+  readonly baseUrl?: string;
+  /**
+   * Optional dimensionality hint. When known up-front, the canonical
+   * id is stable from the first `embed()` call instead of being
+   * resolved from the response.
+   */
+  readonly dim?: number;
+  /**
+   * Override `fetch`. Used by the test suite to inject a mock HTTP
+   * fixture. Production callers should leave this unset so the
+   * embedder uses the platform's `globalThis.fetch`.
+   */
+  readonly fetchImpl?: typeof fetch;
+  /**
+   * If `true`, skip the `POST /api/show` model-digest probe at
+   * construction. Used in test fixtures where the digest is
+   * pre-populated.
+   */
+  readonly skipDigestProbe?: boolean;
+  /**
+   * Optional pre-resolved digest (e.g. from a probe done elsewhere).
+   * When set, the embedder uses this value instead of issuing a
+   * `POST /api/show` request.
+   */
+  readonly digest?: string;
+  /** Optional API path override (default `'/api/embed'`). */
+  readonly embedPath?: string;
+  /** Optional API path override (default `'/api/embeddings'`). */
+  readonly legacyEmbedPath?: string;
+  /** Optional API path override (default `'/api/show'`). */
+  readonly showPath?: string;
+  /**
+   * Per-request hard timeout in milliseconds. Default `30000`. Each
+   * HTTP call (`/api/show`, `/api/embed`, legacy `/api/embeddings`) is
+   * aborted if the Ollama daemon does not respond in time, so a hung
+   * daemon never stalls the caller. A per-call {@link EmbedOptions.signal}
+   * is combined with this timeout. Set to `0` to disable.
+   */
+  readonly timeoutMs?: number;
+}
+
+/**
+ * Raised when the Ollama HTTP API returns a non-2xx response.
+ *
+ * @stable
+ */
+export class OllamaEmbedderError extends Error {
+  override readonly name = 'OllamaEmbedderError';
+  constructor(
+    message: string,
+    public readonly statusCode?: number,
+    options?: { cause?: unknown },
+  ) {
+    super(message, options);
+  }
+}
+
+/**
+ * Model -> output-dimension hints used to seed the canonical id before the
+ * first `embed()` resolves the real width from a response. Only single-width
+ * families are listed; size-variant families (e.g. `qwen3-embedding`, whose
+ * dim depends on the `:0.6b` / `:4b` / `:8b` tag) are deliberately omitted so
+ * an ambiguous bind fails loudly rather than baking a wrong width (PS-11).
+ */
+export const KNOWN_OLLAMA_MODEL_DIMS: ReadonlyMap<string, number> = new Map([
+  ['nomic-embed-text', 768],
+  ['mxbai-embed-large', 1024],
+  ['snowflake-arctic-embed', 1024],
+  ['snowflake-arctic-embed2', 1024],
+  ['bge-m3', 1024],
+  ['bge-large', 1024],
+  ['embeddinggemma', 768],
+  ['all-minilm', 384],
+  ['granite-embedding', 384],
+  ['paraphrase-multilingual', 768],
+]);
+
+/**
+ * Build an Ollama-backed embedder. The first `embed()` call issues a
+ * `POST /api/show` to capture the model digest; subsequent calls hit
+ * the embedding endpoint directly.
+ *
+ * @stable
+ */
+export function createOllamaEmbedder(options: OllamaEmbedderOptions = {}): OllamaEmbedder {
+  return new OllamaEmbedder(options);
+}
+
+/**
+ * `EmbedderProvider` implementation that talks to the Ollama HTTP API.
+ *
+ * @stable
+ */
+export class OllamaEmbedder implements EmbedderProvider {
+  readonly #model: string;
+  readonly #baseUrl: string;
+  readonly #fetchImpl: typeof fetch;
+  readonly #skipDigestProbe: boolean;
+  readonly #embedPath: string;
+  readonly #legacyEmbedPath: string;
+  readonly #showPath: string;
+  readonly #timeoutMs: number;
+  #digest: string | null;
+  #resolvedDim: number | null;
+  #initialized = false;
+  #initializing: Promise<void> | null = null;
+
+  constructor(options: OllamaEmbedderOptions) {
+    this.#model = options.model ?? DEFAULT_OLLAMA_MODEL;
+    this.#baseUrl = stripTrailingSlashesLocal(options.baseUrl ?? DEFAULT_OLLAMA_BASE_URL);
+    this.#fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.#skipDigestProbe = options.skipDigestProbe ?? false;
+    this.#embedPath = options.embedPath ?? '/api/embed';
+    this.#legacyEmbedPath = options.legacyEmbedPath ?? '/api/embeddings';
+    this.#showPath = options.showPath ?? '/api/show';
+    this.#timeoutMs = options.timeoutMs ?? 30_000;
+    this.#digest = options.digest ?? null;
+    this.#resolvedDim = options.dim ?? KNOWN_OLLAMA_MODEL_DIMS.get(this.#model) ?? null;
+  }
+
+  /**
+   * Build the `{ signal }` fetch-init fragment, combining the caller's
+   * abort signal (if any) with the per-request timeout so a hung Ollama
+   * daemon cannot stall the embed call. Returns `{}` when neither
+   * applies. Call once per fetch - each call mints a fresh timeout.
+   */
+  #signalInit(opts: EmbedOptions): { signal?: AbortSignal } {
+    const timeoutSignal = this.#timeoutMs > 0 ? AbortSignal.timeout(this.#timeoutMs) : undefined;
+    const signal =
+      opts.signal !== undefined && timeoutSignal !== undefined
+        ? AbortSignal.any([opts.signal, timeoutSignal])
+        : (opts.signal ?? timeoutSignal);
+    return signal === undefined ? {} : { signal };
+  }
+
+  /** The canonical embedder id - `'ollama:<model>@<dim-or-digest>'`. */
+  id(): string {
+    const dim = this.dim();
+    const digest = this.#digest !== null ? `:${this.#digest.slice(0, 12)}` : '';
+    return `ollama:${this.#model}@${dim}${digest}`;
+  }
+
+  /**
+   * Output dimension - the explicit `dim` option, the resolved width from the
+   * first `embed()`, or a known-family default. PS-11: throws for an unknown
+   * model with no `dim` hint instead of returning `0` (which the store would
+   * persist and use to create a `float[0]` vec0 table, silently breaking
+   * vector search). Pass `dim` for any model not in {@link
+   * KNOWN_OLLAMA_MODEL_DIMS}, or call `embed()` once first to resolve it.
+   */
+  dim(): number {
+    if (this.#resolvedDim !== null) return this.#resolvedDim;
+    const known = KNOWN_OLLAMA_MODEL_DIMS.get(this.#model);
+    if (known !== undefined) return known;
+    throw new OllamaEmbedderError(
+      `[graphorin/embedder-ollama] unknown output dimension for model '${this.#model}'. ` +
+        'Pass `dim` to ollamaEmbedder({ model, dim }), or call embed() once to resolve it ' +
+        'from a response, before registering the embedder.',
+    );
+  }
+
+  /**
+   * Deterministic hash over the embedder's full configuration -
+   * including the discovered digest. A model upgrade in the same
+   * Ollama instance changes the digest (and therefore the hash), so
+   * `lock-on-first` correctly fires a migration path instead of
+   * silently reusing the same `embedder_id`.
+   */
+  configHash(): string {
+    return canonicalConfigHash({
+      adapter: 'ollama',
+      model: this.#model,
+      baseUrl: this.#baseUrl,
+      digest: this.#digest ?? null,
+      dim: this.#resolvedDim ?? null,
+    });
+  }
+
+  async embed(
+    texts: ReadonlyArray<string>,
+    opts: EmbedOptions = {},
+  ): Promise<ReadonlyArray<Float32Array>> {
+    if (texts.length === 0) return [];
+    await this.#ensureInitialized(opts);
+    return this.#callEmbed(texts, opts);
+  }
+
+  async #ensureInitialized(opts: EmbedOptions): Promise<void> {
+    if (this.#initialized) return;
+    if (this.#initializing !== null) return this.#initializing;
+    const inflight = (async () => {
+      try {
+        if (!this.#skipDigestProbe && this.#digest === null) {
+          await this.#probeDigest(opts);
+        }
+        this.#initialized = true;
+      } finally {
+        // Always clear the in-flight slot so a transient failure does
+        // not poison every subsequent call with the same rejection.
+        this.#initializing = null;
+      }
+    })();
+    this.#initializing = inflight;
+    return inflight;
+  }
+
+  async #probeDigest(opts: EmbedOptions): Promise<void> {
+    const url = `${this.#baseUrl}${this.#showPath}`;
+    let resp: Response;
+    try {
+      resp = await this.#fetchImpl(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ name: this.#model }),
+        ...this.#signalInit(opts),
+      });
+    } catch (err) {
+      throw new OllamaEmbedderError(
+        `[graphorin/embedder-ollama] failed to reach Ollama at ${url}`,
+        undefined,
+        { cause: err },
+      );
+    }
+    if (!resp.ok) {
+      throw new OllamaEmbedderError(
+        `[graphorin/embedder-ollama] /api/show returned ${resp.status} for model '${this.#model}'`,
+        resp.status,
+      );
+    }
+    const json = (await resp.json()) as { digest?: string };
+    if (typeof json.digest === 'string' && json.digest.length > 0) {
+      this.#digest = json.digest;
+    }
+  }
+
+  async #callEmbed(
+    texts: ReadonlyArray<string>,
+    opts: EmbedOptions,
+  ): Promise<ReadonlyArray<Float32Array>> {
+    const batchUrl = `${this.#baseUrl}${this.#embedPath}`;
+    const batchBody = JSON.stringify({ model: this.#model, input: [...texts] });
+    let resp: Response;
+    try {
+      resp = await this.#fetchImpl(batchUrl, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: batchBody,
+        ...this.#signalInit(opts),
+      });
+    } catch (err) {
+      throw new OllamaEmbedderError(
+        `[graphorin/embedder-ollama] failed to reach Ollama at ${batchUrl}`,
+        undefined,
+        { cause: err },
+      );
+    }
+    if (resp.status === 404) {
+      // Older Ollama versions only expose the legacy single-input path.
+      return this.#legacyEmbedPerText(texts, opts);
+    }
+    if (!resp.ok) {
+      throw new OllamaEmbedderError(
+        `[graphorin/embedder-ollama] /api/embed returned ${resp.status}`,
+        resp.status,
+      );
+    }
+    const json = (await resp.json()) as { embeddings?: number[][] };
+    const list = json.embeddings;
+    if (!Array.isArray(list) || list.length !== texts.length) {
+      throw new OllamaEmbedderError(
+        `[graphorin/embedder-ollama] /api/embed response had unexpected shape`,
+      );
+    }
+    const out: Float32Array[] = [];
+    for (let i = 0; i < list.length; i++) {
+      const row = list[i];
+      if (!Array.isArray(row)) {
+        throw new OllamaEmbedderError(
+          `[graphorin/embedder-ollama] embedding row ${i} is not an array`,
+        );
+      }
+      const f32 = Float32Array.from(row);
+      if (this.#resolvedDim === null) {
+        this.#resolvedDim = f32.length;
+      } else if (this.#resolvedDim !== f32.length) {
+        throw new OllamaEmbedderError(
+          `[graphorin/embedder-ollama] embedding dim drifted: expected ${this.#resolvedDim}, got ${f32.length}`,
+        );
+      }
+      out.push(f32);
+    }
+    return out;
+  }
+
+  async #legacyEmbedPerText(
+    texts: ReadonlyArray<string>,
+    opts: EmbedOptions,
+  ): Promise<ReadonlyArray<Float32Array>> {
+    const url = `${this.#baseUrl}${this.#legacyEmbedPath}`;
+    const out: Float32Array[] = [];
+    for (const text of texts) {
+      const resp = await this.#fetchImpl(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ model: this.#model, prompt: text }),
+        ...this.#signalInit(opts),
+      });
+      if (!resp.ok) {
+        throw new OllamaEmbedderError(
+          `[graphorin/embedder-ollama] /api/embeddings returned ${resp.status}`,
+          resp.status,
+        );
+      }
+      const json = (await resp.json()) as { embedding?: number[] };
+      if (!Array.isArray(json.embedding)) {
+        throw new OllamaEmbedderError(
+          `[graphorin/embedder-ollama] /api/embeddings response has no 'embedding' array`,
+        );
+      }
+      const f32 = Float32Array.from(json.embedding);
+      if (this.#resolvedDim === null) this.#resolvedDim = f32.length;
+      out.push(f32);
+    }
+    return out;
+  }
+}
+
+/**
+ * Canonical-JSON deterministic hash over an embedder configuration.
+ * Object keys are sorted lexicographically so the resulting hash is
+ * stable across `JSON.stringify` reorderings.
+ *
+ * @stable
+ */
+export function canonicalConfigHash(config: unknown): string {
+  return createHash('sha256').update(canonicalize(config), 'utf8').digest('hex');
+}
+
+function canonicalize(value: unknown): string {
+  if (value === null) return 'null';
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'number') return Number.isFinite(value) ? value.toString() : 'null';
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalize).join(',')}]`;
+  }
+  if (typeof value === 'object') {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(obj[k])}`).join(',')}}`;
+  }
+  return 'null';
+}
+
+/**
+ * Strip every trailing `/` from a URL string in `O(n)`. Kept regex-free
+ * so CodeQL does not flag the (otherwise harmless) `/+` anchored
+ * quantifier as a polynomial-redos vector.
+ */
+function stripTrailingSlashesLocal(url: string): string {
+  let end = url.length;
+  while (end > 0 && url.charCodeAt(end - 1) === 0x2f) end -= 1;
+  return end === url.length ? url : url.slice(0, end);
+}