@untangle-code/embeddings-ollama 0.0.0-stage → 0.1.1

package/dist/truncation.js

@@ -0,0 +1,39 @@
+/**
+ * Truncation guard (spec.md §9.3).
+ *
+ * Ollama's `/api/embed` truncates silently to the model's context window by
+ * default (`truncate: true`) and does not report, per input, whether
+ * truncation actually happened. The chunker (a separate package) is already
+ * responsible for keeping prepared text within budget in the normal case;
+ * this guard exists purely to catch the exceptional case where it did not
+ * and flag the resulting point honestly rather than silently accepting a
+ * vector computed from a truncated text (vision.md 8.4 "no silent data
+ * loss").
+ *
+ * Detection is a conservative, offline token estimate compared against the
+ * configured `contextLength` — the same trade-off `@untangle-code/chunker`
+ * makes for its own budget checks (over-estimating real BPE token counts is
+ * far safer than under-estimating, which would hide a real truncation).
+ * The estimator is intentionally duplicated rather than imported: chunker
+ * uses it to fit a budget ahead of time, this module uses it to flag a
+ * budget miss after the fact, and importing chunker here would add a
+ * runtime dependency between packages that otherwise have no reason to
+ * know about each other (rule 3 spirit).
+ */
+/** Conservative average characters per token — deliberately lower than the ~4 real average. */
+const CHARS_PER_TOKEN = 3;
+/** Estimates a conservative (over-)approximation of `text`'s token count. */
+export function estimateTokenCount(text) {
+    if (text.length === 0) {
+        return 0;
+    }
+    return Math.max(1, Math.ceil(text.length / CHARS_PER_TOKEN));
+}
+/**
+ * True when `text`'s estimated token count exceeds `contextLength` — the
+ * point at which Ollama's provider-side truncation actually applies.
+ */
+export function wouldProviderTruncate(text, contextLength) {
+    return estimateTokenCount(text) > contextLength;
+}
+//# sourceMappingURL=truncation.js.map

package/dist/truncation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncation.js","sourceRoot":"","sources":["../src/truncation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,+FAA+F;AAC/F,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B,6EAA6E;AAC7E,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY,EAAE,aAAqB;IACvE,OAAO,kBAAkB,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC;AAClD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Local types for the Ollama `EmbeddingProvider` adapter (spec.md §9, §4.5;
+ * architecture.md §6.8).
+ */
+import type { EmbeddingProfile } from "@untangle-code/domain";
+/** Endpoint resolution mode (spec.md §4.5 `EmbeddingConfig.mode`). */
+export type OllamaEndpointMode = "auto" | "managed" | "external";
+/**
+ * Operational settings for one {@link OllamaEmbeddingProvider} instance.
+ *
+ * `profile` carries exactly the eight `EmbeddingProfile` fields that feed
+ * `embedding_profile_id` (spec.md §5.7) — everything else here is
+ * operational (endpoints, batching, timeouts) and deliberately NOT part of
+ * the profile, matching domain's `EmbeddingProfile` doc comment. Callers
+ * (typically `@untangle-code/config`'s `deriveEmbeddingProfile`) are
+ * responsible for assembling `profile` from the user's `EmbeddingConfig`;
+ * this package only consumes the result, keeping it decoupled from the
+ * config package (rule 3: no dependency on a package built in the same
+ * wave).
+ */
+export interface OllamaEmbeddingProviderConfig {
+    profile: EmbeddingProfile;
+    mode: OllamaEndpointMode;
+    /**
+     * Explicit endpoint override. Required when `mode` is `"external"`.
+     * When `mode` is `"managed"`, overrides {@link managedUrl}. Ignored in
+     * `"auto"` mode's native-probe step, but used as the managed fallback
+     * there too when set.
+     */
+    url?: string | undefined;
+    /** Name of the env var holding a bearer token; the token itself is never logged (spec.md §24). */
+    apiKeyEnv?: string | undefined;
+    /** Model context window in tokens, used only for the truncation guard (spec.md §9.3). */
+    contextLength: number;
+    /** Number of prepared texts sent per Ollama `/api/embed` request. */
+    batchSize: number;
+    /** Upper bound on concurrently in-flight HTTP requests to Ollama. */
+    maxConnections: number;
+    /** Per-request timeout in milliseconds. */
+    requestTimeoutMs: number;
+    /** Native Ollama probe URL for `"auto"` mode (spec.md §3.1 default). */
+    nativeProbeUrl?: string | undefined;
+    /** Managed-container endpoint default (spec.md §3.1 default port 11435). */
+    managedUrl?: string | undefined;
+    /** Maximum retry attempts per request before a transient error is treated as permanent. */
+    maxRetries?: number | undefined;
+    /** Base delay for exponential backoff (spec.md §9.2). */
+    baseBackoffMs?: number | undefined;
+    /** Backoff delay cap. */
+    maxBackoffMs?: number | undefined;
+}
+/** spec.md §3.1 defaults. */
+export declare const DEFAULT_NATIVE_PROBE_URL = "http://127.0.0.1:11434";
+export declare const DEFAULT_MANAGED_URL = "http://127.0.0.1:11435";
+export declare const DEFAULT_MAX_RETRIES = 5;
+export declare const DEFAULT_BASE_BACKOFF_MS = 250;
+export declare const DEFAULT_MAX_BACKOFF_MS = 8000;
+/**
+ * Cache key per spec.md §9.4: `embedding_profile_id + SHA256(prepared_text)`.
+ * Kept as a structured object (rather than a pre-joined string) so a
+ * persistent implementation is free to choose its own storage shape.
+ */
+export interface EmbeddingCacheKey {
+    embeddingProfileId: string;
+    /** `SHA256(prepared_text)`, hex-encoded. */
+    preparedTextHash: string;
+}
+export interface EmbeddingCacheEntry {
+    vector: number[];
+    /** Whether provider-side truncation applied when this vector was produced (spec.md §9.3). */
+    truncated: boolean;
+}
+/**
+ * Narrow, storage-agnostic embedding cache port.
+ *
+ * NOT a `@untangle-code/domain` port — the task that produced this adapter
+ * defines it here deliberately so it can be exercised immediately, but this
+ * interface conceptually belongs in domain's `ports.ts` next to
+ * `EmbeddingProvider` so that `storage-local` (or any other persistent
+ * implementation) can implement a shared, versioned contract instead of a
+ * package-local one. Flagged in the WP-10 report's `openIssues` for a
+ * follow-up move.
+ */
+export interface EmbeddingCachePort {
+    get(key: EmbeddingCacheKey, options?: {
+        signal?: AbortSignal | undefined;
+    }): Promise<EmbeddingCacheEntry | null>;
+    set(key: EmbeddingCacheKey, entry: EmbeddingCacheEntry, options?: {
+        signal?: AbortSignal | undefined;
+    }): Promise<void>;
+}
+/**
+ * Injectable delay primitive for backoff waits (spec.md §9.2). Not a
+ * `@untangle-code/domain` port (domain has no scheduling port, only `Clock`
+ * for reading "now") — tests inject a fake that resolves instantly while
+ * still recording the requested delays, so the exponential-backoff schedule
+ * is asserted without the test suite actually waiting.
+ */
+export type SleepFn = (ms: number, signal?: AbortSignal) => Promise<void>;
+/** Progress reported once per network batch (spec.md §9.2 "Fortschritt MUSS pro Batch aktualisiert werden"). */
+export interface EmbeddingBatchProgressV1 {
+    batchIndex: number;
+    batchCount: number;
+    /** Texts embedded so far across all batches of this call, including cache hits. */
+    embeddedCount: number;
+    totalCount: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,sEAAsE;AACtE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;AAEjE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,gBAAgB,CAAC;IAC1B,IAAI,EAAE,kBAAkB,CAAC;IACzB;;;;;OAKG;IAMH,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,kGAAkG;IAClG,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,yFAAyF;IACzF,aAAa,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,cAAc,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,gBAAgB,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,yBAAyB;IACzB,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,6BAA6B;AAC7B,eAAO,MAAM,wBAAwB,2BAA2B,CAAC;AACjE,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAE5D,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAC3C,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAM3C;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,6FAA6F;IAC7F,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,CACD,GAAG,EAAE,iBAAiB,EACtB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;KAAE,GAC7C,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;IACvC,GAAG,CACD,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,mBAAmB,EAC1B,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;KAAE,GAC7C,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAMD;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1E,gHAAgH;AAChH,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/** spec.md §3.1 defaults. */
+export const DEFAULT_NATIVE_PROBE_URL = "http://127.0.0.1:11434";
+export const DEFAULT_MANAGED_URL = "http://127.0.0.1:11435";
+export const DEFAULT_MAX_RETRIES = 5;
+export const DEFAULT_BASE_BACKOFF_MS = 250;
+export const DEFAULT_MAX_BACKOFF_MS = 8000;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA2DA,6BAA6B;AAC7B,MAAM,CAAC,MAAM,wBAAwB,GAAG,wBAAwB,CAAC;AACjE,MAAM,CAAC,MAAM,mBAAmB,GAAG,wBAAwB,CAAC;AAE5D,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AACrC,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAC3C,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC"}

package/dist/validation.d.ts

@@ -0,0 +1,2 @@
+export declare function assertVectorDimension(vector: number[], expectedDimensions: number, context: Record<string, unknown>): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAQA,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EAAE,EAChB,kBAAkB,EAAE,MAAM,EAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAUN"}

package/dist/validation.js

@@ -0,0 +1,16 @@
+/**
+ * Vector-dimension validation (spec.md §9.1 step 6, §4.8 "Falsch
+ * konfigurierte Dimensionen MÜSSEN vor dem ersten Index-Upsert erkannt
+ * werden"). Applied both to the readiness probe vector and to every
+ * subsequent batch result — defense in depth, not just a one-time check.
+ */
+import { embeddingDimensionMismatchError } from "@untangle-code/observability";
+export function assertVectorDimension(vector, expectedDimensions, context) {
+    if (vector.length !== expectedDimensions) {
+        throw embeddingDimensionMismatchError(`Ollama returned a ${vector.length}-dimensional vector but the embedding profile expects ${expectedDimensions} dimensions.`, {
+            retryable: false,
+            context: { ...context, actualDimensions: vector.length, expectedDimensions },
+        });
+    }
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,+BAA+B,EAAE,MAAM,8BAA8B,CAAC;AAE/E,MAAM,UAAU,qBAAqB,CACnC,MAAgB,EAChB,kBAA0B,EAC1B,OAAgC;IAEhC,IAAI,MAAM,CAAC,MAAM,KAAK,kBAAkB,EAAE,CAAC;QACzC,MAAM,+BAA+B,CACnC,qBAAqB,MAAM,CAAC,MAAM,yDAAyD,kBAAkB,cAAc,EAC3H;YACE,SAAS,EAAE,KAAK;YAChB,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,EAAE;SAC7E,CACF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@untangle-code/embeddings-ollama",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "description": "Untangle EmbeddingProvider adapter for Ollama: endpoint auto-detection, readiness, batching with backoff, truncation guard and embedding cache (spec.md §9, architecture.md §6.8).",
+  "license": "AGPL-3.0-only",
+  "homepage": "https://github.com/lboel/untangle",
+  "bugs": {
+    "url": "https://github.com/lboel/untangle/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lboel/untangle.git",
+    "directory": "packages/embeddings-ollama"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": "^22.13.0 || >=24.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/test-helpers.*",
+    "!dist/**/test-support.*",
+    "!dist/**/test-support/**",
+    "!dist/**/testing/**",
+    "!dist/**/__tests__/**",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/test-helpers.ts",
+    "!src/**/test-support.ts",
+    "!src/**/test-support/**",
+    "!src/**/testing/**",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "THIRD_PARTY_LICENSES.md"
+  ],
+  "dependencies": {
+    "@untangle-code/domain": "0.1.1",
+    "@untangle-code/observability": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.7",
+    "typescript": "5.9.3",
+    "vitest": "3.2.7",
+    "@untangle-code/testkit": "0.1.1"
+  },
+  "scripts": {
+    "build": "node ../../scripts/tsc-build.mjs tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
 }

package/src/backoff.ts

@@ -0,0 +1,73 @@
+/**
+ * Exponential backoff with full jitter (spec.md §9.2).
+ *
+ * Jitter is drawn from the injected `Random` port, never `Math.random()`
+ * (BUILD_PLAN global rule, enforced repo-wide by `eslint.config.js`'s
+ * `no-restricted-syntax`). Delays are executed via an injected {@link
+ * SleepFn} so tests can assert the retry schedule without a real wait.
+ */
+import type { Random } from "@untangle-code/domain";
+
+import type { SleepFn } from "./types.js";
+
+export interface BackoffConfig {
+  /** Maximum number of retries after the first attempt. */
+  maxRetries: number;
+  baseDelayMs: number;
+  maxDelayMs: number;
+}
+
+/**
+ * "Full jitter" delay for retry attempt `attempt` (0-based, i.e. the first
+ * retry after the initial attempt is `attempt === 0`): uniform random in
+ * `[0, min(maxDelayMs, baseDelayMs * 2^attempt)]`.
+ */
+export function computeBackoffDelayMs(
+  attempt: number,
+  config: BackoffConfig,
+  random: Random,
+): number {
+  const cap = Math.min(config.maxDelayMs, config.baseDelayMs * 2 ** attempt);
+  return Math.round(random.nextFloat() * cap);
+}
+
+export interface RetryOptions {
+  // `| undefined` spelled out: callers forward an already-optional signal
+  // under exactOptionalPropertyTypes.
+  signal?: AbortSignal | undefined;
+  /** Whether `error` is worth retrying at all; a `false` result stops immediately. */
+  isRetryable: (error: unknown) => boolean;
+}
+
+/**
+ * Runs `fn`, retrying on retryable errors up to `config.maxRetries` times
+ * with exponential backoff and jitter (spec.md §9.2). A non-retryable error,
+ * or a retryable error that has exhausted its retries, propagates as-is —
+ * the caller (the `EmbeddingProvider`) is responsible for turning that into
+ * the right `UntangleError` ("repeated permanent errors MUST stop the job in
+ * a controlled way", spec.md §9.2).
+ *
+ * Checks `signal` before every attempt and every sleep so an abort mid-retry
+ * surfaces immediately rather than after the next attempt completes.
+ */
+export async function withRetry<T>(
+  fn: (attempt: number) => Promise<T>,
+  config: BackoffConfig,
+  deps: { random: Random; sleep: SleepFn },
+  options: RetryOptions,
+): Promise<T> {
+  let attempt = 0;
+  for (;;) {
+    options.signal?.throwIfAborted();
+    try {
+      return await fn(attempt);
+    } catch (error) {
+      if (attempt >= config.maxRetries || !options.isRetryable(error)) {
+        throw error;
+      }
+      const delayMs = computeBackoffDelayMs(attempt, config, deps.random);
+      await deps.sleep(delayMs, options.signal);
+      attempt += 1;
+    }
+  }
+}

package/src/cache.ts

@@ -0,0 +1,30 @@
+/**
+ * Default in-memory {@link EmbeddingCachePort} (spec.md §9.4).
+ *
+ * Process-local only — a fresh process starts with an empty cache. This is
+ * the right default for a library that must work without any storage
+ * adapter configured; `storage-local` (or another persistent adapter) can
+ * inject a durable implementation of the same port instead.
+ */
+import type { EmbeddingCacheEntry, EmbeddingCacheKey, EmbeddingCachePort } from "./types.js";
+
+function cacheKeyString(key: EmbeddingCacheKey): string {
+  return `${key.embeddingProfileId}:${key.preparedTextHash}`;
+}
+
+export class InMemoryEmbeddingCache implements EmbeddingCachePort {
+  private readonly entries = new Map<string, EmbeddingCacheEntry>();
+
+  public async get(key: EmbeddingCacheKey): Promise<EmbeddingCacheEntry | null> {
+    return this.entries.get(cacheKeyString(key)) ?? null;
+  }
+
+  public async set(key: EmbeddingCacheKey, entry: EmbeddingCacheEntry): Promise<void> {
+    this.entries.set(cacheKeyString(key), entry);
+  }
+
+  /** Test/debug helper: number of cached entries. */
+  public get size(): number {
+    return this.entries.size;
+  }
+}

package/src/concurrency.ts

@@ -0,0 +1,37 @@
+/**
+ * Bounded-concurrency map (spec.md §9.2 "Requests MÜSSEN nach
+ * Verbindungslimit begrenzt werden").
+ *
+ * A small counting semaphore rather than a dependency on an external queue
+ * library — the whole need here is "run at most N of these concurrently,
+ * preserve output order", which is a handful of lines.
+ */
+
+/** Runs `fn` over `items` with at most `limit` concurrent calls, preserving output order. */
+export async function mapWithConcurrency<T, R>(
+  items: readonly T[],
+  limit: number,
+  fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  if (items.length === 0) {
+    return [];
+  }
+  const boundedLimit = Math.max(1, Math.min(limit, items.length));
+  const results = new Array<R>(items.length);
+  let nextIndex = 0;
+
+  async function worker(): Promise<void> {
+    for (;;) {
+      const index = nextIndex;
+      nextIndex += 1;
+      if (index >= items.length) {
+        return;
+      }
+      const item = items[index] as T;
+      results[index] = await fn(item, index);
+    }
+  }
+
+  await Promise.all(Array.from({ length: boundedLimit }, () => worker()));
+  return results;
+}

package/src/endpoint.ts

@@ -0,0 +1,31 @@
+/**
+ * Endpoint redaction helper (spec.md §3.2 "Health-Ausgaben MÜSSEN die
+ * tatsächlich verwendeten Endpunkte anzeigen, wobei Secrets redigiert
+ * werden").
+ *
+ * `@untangle-code/observability`'s `redact()` redacts object fields by key
+ * name; it has no notion of a URL's own embedded-credentials syntax
+ * (`https://user:pass@host/...`). This is the narrow, URL-specific
+ * complement: it never touches the bearer token sent via the
+ * `Authorization` header (that never becomes part of the URL to begin
+ * with) — it only strips userinfo that a misconfigured `url` might carry.
+ */
+export function redactEndpointUrl(rawUrl: string): string {
+  try {
+    const url = new URL(rawUrl);
+    if (url.username || url.password) {
+      url.username = "";
+      url.password = "";
+      return url.toString();
+    }
+    return rawUrl;
+  } catch {
+    // Not a parseable absolute URL — nothing structured to redact.
+    return rawUrl;
+  }
+}
+
+/** Joins a base endpoint URL with a request path, tolerating a trailing slash on the base. */
+export function joinUrl(baseUrl: string, path: string): string {
+  return new URL(path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`).toString();
+}

package/src/http.ts

@@ -0,0 +1,168 @@
+/**
+ * Minimal Ollama HTTP client on Node 22's built-in `fetch` (no HTTP client
+ * dependency, per the WP-10 task). Every request carries a timeout and
+ * respects an external `AbortSignal`; a bounded semaphore caps concurrently
+ * in-flight requests (spec.md §9.2 "Verbindungslimit").
+ */
+import { joinUrl } from "./endpoint.js";
+
+/** Thrown by {@link OllamaHttpClient.requestJson} for any failed request. */
+export class OllamaHttpError extends Error {
+  public readonly status: number | undefined;
+  public readonly retryable: boolean;
+
+  public constructor(
+    message: string,
+    options: { status?: number; retryable: boolean; cause?: unknown },
+  ) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = "OllamaHttpError";
+    this.status = options.status;
+    this.retryable = options.retryable;
+  }
+}
+
+/** Thrown when a request is aborted by the CALLER's own signal (never retried). */
+export class OllamaRequestCancelledError extends Error {
+  public constructor(cause?: unknown) {
+    super("Ollama request cancelled", cause === undefined ? undefined : { cause });
+    this.name = "OllamaRequestCancelledError";
+  }
+}
+
+/**
+ * True for anything that represents the CALLER's own cancellation rather
+ * than a transport failure: an {@link OllamaRequestCancelledError}, a raw
+ * `AbortError` (e.g. from `backoff.ts`'s own `signal.throwIfAborted()`
+ * pre-check, which runs before this client gets a chance to wrap it), or
+ * simply `signal.aborted` already being true by the time the error is
+ * observed. Used everywhere this adapter must tell "the caller cancelled"
+ * apart from "the endpoint is unreachable" (rule 9: cancellation surfaces as
+ * `JOB_CANCELLED`, never as a swallowed/misclassified failure).
+ */
+export function isRequestCancellation(error: unknown, signal: AbortSignal | undefined): boolean {
+  return (
+    error instanceof OllamaRequestCancelledError ||
+    (error instanceof DOMException && error.name === "AbortError") ||
+    signal?.aborted === true
+  );
+}
+
+function isRetryableStatus(status: number): boolean {
+  return status === 429 || status >= 500;
+}
+
+/** Counting semaphore bounding concurrent HTTP requests to one Ollama endpoint. */
+class Semaphore {
+  private available: number;
+  private readonly waiters: (() => void)[] = [];
+
+  public constructor(limit: number) {
+    this.available = Math.max(1, limit);
+  }
+
+  public async acquire(): Promise<() => void> {
+    if (this.available > 0) {
+      this.available -= 1;
+      return () => this.release();
+    }
+    await new Promise<void>((resolve) => this.waiters.push(resolve));
+    this.available -= 1;
+    return () => this.release();
+  }
+
+  private release(): void {
+    this.available += 1;
+    const next = this.waiters.shift();
+    if (next) {
+      next();
+    }
+  }
+}
+
+export interface OllamaHttpClientOptions {
+  requestTimeoutMs: number;
+  maxConnections: number;
+  // `| undefined` spelled out because callers (provider.ts) forward an
+  // already-optional config/deps field here under exactOptionalPropertyTypes.
+  apiKeyEnv?: string | undefined;
+  /** Injectable for tests; defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch | undefined;
+}
+
+export class OllamaHttpClient {
+  private readonly semaphore: Semaphore;
+  private readonly fetchImpl: typeof fetch;
+  private readonly requestTimeoutMs: number;
+  private readonly apiKeyEnv: string | undefined;
+
+  public constructor(options: OllamaHttpClientOptions) {
+    this.semaphore = new Semaphore(options.maxConnections);
+    this.fetchImpl = options.fetchImpl ?? fetch;
+    this.requestTimeoutMs = options.requestTimeoutMs;
+    this.apiKeyEnv = options.apiKeyEnv;
+  }
+
+  /**
+   * Sends one JSON request and parses a JSON response. Never retries by
+   * itself — callers wrap this in `backoff.ts`'s `withRetry`.
+   *
+   * Throws {@link OllamaRequestCancelledError} when `signal` (the caller's
+   * own signal, not the internal timeout) is the reason for the abort, and
+   * {@link OllamaHttpError} for every other failure (network error, timeout,
+   * non-2xx status), with `retryable` set per spec.md §9.2's transient/
+   * permanent split.
+   */
+  public async requestJson<T>(
+    baseUrl: string,
+    path: string,
+    init: { method: "GET" | "POST"; body?: unknown },
+    signal?: AbortSignal,
+  ): Promise<T> {
+    if (signal?.aborted) {
+      throw new OllamaRequestCancelledError(signal.reason);
+    }
+    const release = await this.semaphore.acquire();
+    try {
+      const timeoutSignal = AbortSignal.timeout(this.requestTimeoutMs);
+      const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+      const headers: Record<string, string> = { "content-type": "application/json" };
+      const token = this.apiKeyEnv ? process.env[this.apiKeyEnv] : undefined;
+      if (token) {
+        headers["authorization"] = `Bearer ${token}`;
+      }
+      let response: Response;
+      try {
+        response = await this.fetchImpl(joinUrl(baseUrl, path), {
+          method: init.method,
+          headers,
+          signal: combinedSignal,
+          // Conditionally spread rather than `body: undefined` — RequestInit's
+          // `body` has no `| undefined` arm, so exactOptionalPropertyTypes
+          // forbids assigning it explicitly (a GET request has no body).
+          ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+        });
+      } catch (error) {
+        if (signal?.aborted) {
+          throw new OllamaRequestCancelledError(error);
+        }
+        // Network failure (connection refused, DNS, our own timeout) — transient.
+        throw new OllamaHttpError(`Ollama request to ${path} failed: ${String(error)}`, {
+          retryable: true,
+          cause: error,
+        });
+      }
+      if (!response.ok) {
+        const bodyText = await response.text().catch(() => "");
+        throw new OllamaHttpError(
+          `Ollama request to ${path} returned HTTP ${response.status}: ${bodyText.slice(0, 500)}`,
+          { status: response.status, retryable: isRetryableStatus(response.status) },
+        );
+      }
+      const text = await response.text();
+      return text.length === 0 ? (undefined as T) : (JSON.parse(text) as T);
+    } finally {
+      release();
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @untangle-code/embeddings-ollama — `EmbeddingProvider` adapter for Ollama
+ * (spec.md §9, architecture.md §6.8). This module is the only public export
+ * of the package (rule 11); everything else (`http.ts`, `ollama-api.ts`,
+ * `readiness.ts`, `backoff.ts`, `concurrency.ts`, `truncation.ts`,
+ * `endpoint.ts`, `validation.ts`) is an internal implementation detail,
+ * imported directly only by this package's own co-located tests.
+ */
+
+// The adapter itself.
+export * from "./provider.js";
+
+// Public configuration and port types.
+export * from "./types.js";
+
+// Default in-memory embedding cache (spec.md §9.4) — the port itself lives in types.ts.
+export * from "./cache.js";
+
+// Real (non-fake) sleep implementation, exported so callers assembling
+// `OllamaEmbeddingProviderDeps` outside tests don't need to reimplement it.
+export * from "./sleep.js";