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

package/NOTICE

@@ -0,0 +1,90 @@
+# NOTICE
+
+Copyright (C) 2026 Luke Bölling and contributors.
+
+This attribution covers original Untangle work. Contributors retain copyright in
+their contributions. Third-party packages, grammars and other materials retain
+their own copyright holders, licenses and notices; this line does not replace them.
+
+## License — binding decision
+
+Untangle is licensed under the **GNU Affero General Public License, Version 3
+(AGPL-3.0-only)**. See [`LICENSE`](./LICENSE).
+
+This decision is **final, not provisional**, and was explicitly instructed by
+the project owner. No contributor, agent or tool may change it without a new
+explicit instruction.
+
+The repository-wide license covers Untangle's first-party source code, scripts,
+tests, fixtures, configuration, documentation, website and brand artwork, including
+the logo and 3D yarn illustrations. Every workspace `package.json` declares
+`"license": "AGPL-3.0-only"`. There is no separately licensed enterprise component
+or separate permissive license for documentation or brand assets.
+
+Third-party code, embedded grammars, dependency assets and their notices retain
+their original licenses. Their inclusion does not relicense those works. The
+repository license does not grant trademark rights or change the license of a
+repository analyzed with Untangle. See the repository's `docs/LICENSING.md` for
+scope and verification details.
+
+This resolves the license question left open in `vision.md` §14 and completes
+`product.md` §16, item 2.
+
+## Rationale
+
+- **Network copyleft fits the intended product model.** AGPL §13 sets source
+  availability requirements for modified versions used through a computer network.
+  The current local CLI/stdio-MCP entry and future shared-server modes share the
+  same license.
+- **Local-first analysis has a clear boundary.** Running Untangle against a codebase
+  does not replace that codebase's own license with Untangle's license.
+- **First-party components share one license.** Implemented components and future
+  official plugins use this repository's licensing policy. Planned integrations do
+  not establish implemented or published products.
+
+## Deliberately accepted consequence
+
+The project deliberately chooses AGPL rather than a permissive embedding license.
+Redistribution, modifications and combined works must be assessed against the
+actual terms in `LICENSE`, including applicable Corresponding Source requirements.
+No permissive exception, commercial dual license or special contract-only package
+license is granted or promised by this notice.
+
+## Dependencies
+
+Third-party runtime dependencies are checked against the allowlist in
+`scripts/check-licenses.mjs`. Their licenses and copyright notices remain unchanged
+and traceable through package `THIRD_PARTY_LICENSES.md` files, grammar provenance,
+the lockfile and release SBOM. The allowlist includes MIT / Apache-2.0 / BSD / ISC
+and other explicitly listed licenses; it is not a license grant for dependencies.
+
+The allowlist in `scripts/check-licenses.mjs` applies to **dependencies**, not
+workspace packages. Untangle's own packages carry AGPL-3.0-only and are excluded
+from that check.
+
+## Clean room
+
+Untangle is an independent implementation with its own data models, APIs, tool
+names, tests and sources. Feature ideas may be derived from publicly observable
+behavior and generally known techniques. Third-party source code is not copied,
+including from AGPL projects even where the license would permit it.
+
+## Contribution terms
+
+Pull requests are welcome under the repository's existing AGPL-3.0-only license.
+No separate CLA, copyright assignment or DCO sign-off is required. Contributors
+must have the right to submit their work under those terms. See CONTRIBUTING.md.
+
+## Release decisions
+
+- [x] Copyright attribution: Luke Bölling, with contributors retaining their rights.
+- [x] Contributions use AGPL-3.0-only without an additional CLA or DCO gate.
+
+## Open legal items before public beta
+
+- [ ] Trademark search for the product name `Untangle`.
+- [ ] Registration and legal review of the npm scope `@untangle-code`.
+- [ ] Verify source availability and notices for each released network daemon/server
+  mode (WP-59). The current stdio MCP `untangle_about` already reports the license,
+  source repository and build commit when supplied; metadata alone does not prove
+  that a concrete deployed version's source is available.

package/README.md

@@ -1,3 +1,188 @@
-# Temporary Holding Version
+# @untangle-code/embeddings-ollama
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Ollama `EmbeddingProvider` adapter (WP-10). An internal private package, not published to npm.
+It implements domain's `EmbeddingProvider` port against real or managed Ollama: automatic endpoint
+detection, seven-step readiness, connection-limited batching with exponential backoff/jitter,
+a truncation guard and embedding cache.
+
+Normative sources: [`spec.md`](../../spec.md) §9 (takes precedence; all of 9.1 readiness,
+9.2 batching, 9.3 truncation, 9.4 cache), §5.7 (embedding profile ID), §4.5 (configuration),
+§3.1–3.2 (modes/endpoints), and [`architecture.md`](../../architecture.md) §6.8.
+
+<a id="was-dieses-package-tut"></a>
+
+## Responsibilities
+
+`OllamaEmbeddingProvider` (`src/provider.ts`) is the only exported class implementing
+`EmbeddingProvider`. Its first `ensureReady()`/`embedDocuments()`/`embedQuery()` performs exactly
+one readiness sequence from spec.md §9.1 and caches its result for the instance's lifetime:
+
+```text
+1. Determine effective endpoint — "auto": native (127.0.0.1:11434) first, otherwise managed (11435)
+2. Check reachability           — GET /api/tags
+3. Check model availability     — tag match (":latest" suffix tolerated)
+4. Pull in managed mode         — POST /api/pull, ONLY for Untangle-managed endpoints
+5. Generate probe embedding     — POST /api/embed with fixed probe text
+6. Validate vector dimensions   — EMBEDDING_DIMENSION_MISMATCH on mismatch
+7. Cache profile/probe time     — EmbeddingReadinessV1, valid for the instance lifetime
+```
+
+A dimension mismatch is therefore detected no later than the first
+`embedDocuments()`/`embedQuery()` call: both invoke `ensureReady()` before any batch is processed
+(spec.md §4.8, before the first index upsert).
+
+<a id="modulübersicht"></a>
+
+## Modules
+
+| Module | Contents |
+|---|---|
+| `provider.ts` | `OllamaEmbeddingProvider`, the sole `EmbeddingProvider` implementation; readiness cache, batching, cache/retry/truncation orchestration |
+| `readiness.ts` | `runReadinessSequence()`, the seven steps in spec.md §9.1 in exactly that order |
+| `http.ts` | `OllamaHttpClient`, a `fetch` wrapper with timeout, `AbortSignal`, bounded connection semaphore; `OllamaHttpError` (transient/permanent), `OllamaRequestCancelledError` |
+| `ollama-api.ts` | Typed subset of Ollama HTTP API: `/api/tags`, `/api/pull`, `/api/embed` |
+| `backoff.ts` | `withRetry()`, exponential backoff with full jitter through injected `Random` |
+| `concurrency.ts` | `mapWithConcurrency()`, a small counting semaphore for bounded parallelism and preserved output order |
+| `truncation.ts` | `estimateTokenCount()`/`wouldProviderTruncate()`, conservative offline truncation-guard estimates (spec.md §9.3) |
+| `cache.ts` | `InMemoryEmbeddingCache`, default `EmbeddingCachePort` implementation |
+| `endpoint.ts` | `redactEndpointUrl()`/`joinUrl()` |
+| `validation.ts` | `assertVectorDimension()`, shared by readiness probes and regular batches |
+| `sleep.ts` | `realSleep`, the only production `SleepFn` implementation |
+| `types.ts` | `OllamaEmbeddingProviderConfig`, `EmbeddingCachePort`/`EmbeddingCacheKey`/`EmbeddingCacheEntry`, `SleepFn`, `EmbeddingBatchProgressV1` |
+
+`src/index.ts` is the only public export (rule 10). `http.ts`, `ollama-api.ts`, `readiness.ts`,
+`backoff.ts`, `concurrency.ts`, `truncation.ts`, `endpoint.ts` and `validation.ts` are internal
+implementation details imported directly only by co-located tests.
+
+<a id="verwendung"></a>
+
+## Usage
+
+```ts
+import { OllamaEmbeddingProvider } from "@untangle-code/embeddings-ollama";
+
+const provider = new OllamaEmbeddingProvider(
+  {
+    profile: { provider: "ollama", model: "nomic-embed-text", dimensions: 768, /* … */ },
+    mode: "auto",
+    contextLength: 2048,
+    batchSize: 32,
+    maxConnections: 4,
+    requestTimeoutMs: 120000,
+  },
+  { clock, random }, // from @untangle-code/domain; cache/sleep/fetchImpl optional
+);
+
+await provider.ensureReady();
+const { vectors, truncated } = await provider.embedDocuments(preparedDocumentTexts);
+```
+
+`profile` contains exactly domain's eight `EmbeddingProfile` fields contributing to
+`embedding_profile_id` (spec.md §5.7); other fields are operational and deliberately NOT part of
+profile identity. The caller, typically config's `deriveEmbeddingProfile`, builds it from user
+configuration. This package has no runtime dependency on `config` (rule 3: no dependency on a
+package being developed in parallel in the same wave).
+
+<a id="entscheidungen"></a>
+
+## Decisions
+
+Choices left open by spec.md/architecture.md:
+
+- **HTTP API:** `/api/embed` (batch-capable, `input: string[]`) rather than old `/api/embeddings`
+  (one text per request), for both `embedDocuments()` and `embedQuery()` (a one-entry array),
+  keeping exactly one code path.
+- **`/api/pull` with `stream: false`:** Ollama waits for the completed pull and returns one JSON
+  response rather than NDJSON, symmetrical with every other client request and requiring no
+  streaming parser.
+- **Truncation detection is an offline estimate, not a server signal.** `/api/embed` does not
+  report actual truncation per input. The adapter compares a conservative token estimate—more
+  likely high than low—to `contextLength`, the same trade-off `@untangle-code/chunker` uses for
+  budgeting. It is deliberately duplicated rather than imported: chunker estimates beforehand
+  to respect budgets; this package estimates afterward to detect overruns. A runtime dependency
+  between them would not be justified.
+- **Endpoint selection in `"auto"`:** native (`http://127.0.0.1:11434` by default) first, then
+  managed (`http://127.0.0.1:11435`) as fallback (spec.md §3.1). Only the latter is treated as
+  Untangle-managed; model pull (step 4) happens exclusively there, never at native or
+  `"external"` endpoints (spec.md §3.2 forbids modifying other processes).
+- **Readiness is cached exactly once per instance** (spec.md §9.1 step 7), without TTL expiration.
+  A failed attempt is NOT cached; the next call restarts the sequence. A hard reset, for example
+  after an endpoint change, requires a new instance; deliberately simple for the MVP.
+- **Bounded connection pool:** a counting semaphore around each `fetch` (`http.ts`), not an
+  implementation setting of `fetch` itself. Node 22's `fetch`/`undici` exposes no directly
+  injectable connection limit here.
+- **Batching versus connection pool:** `batchSize` controls prepared texts in ONE `/api/embed`
+  request; `maxConnections` controls simultaneous requests (`concurrency.ts`). Progress is
+  reported per completed network batch through `onBatchProgress`, an extension of
+  `PortCallOptions` because the port itself has no progress callback.
+- **Error classification** (spec.md §9.2): HTTP 429/5xx and network errors are transient/retryable;
+  other 4xx responses are permanent and NOT retried. Permanent errors stop the batch explicitly
+  with `EMBEDDING_UNAVAILABLE`, `retryable: false`, rather than continuing silently or indefinitely.
+- **Cache is NOT persistent by default.** `InMemoryEmbeddingCache` loses state with the process.
+  The narrow `EmbeddingCachePort` (`get`/`set` over `{ embeddingProfileId, preparedTextHash }`)
+  allows `storage-local` or another adapter to inject persistence without changing this package.
+- **Cache is read a second time BEFORE requesting** (WP-117). `embedSlice` makes its miss/join
+  decision once, from one `Promise.all` over `cache.get()`. A cache whose `get()` observes state at
+  invocation but resolves later—any network/disk cache, precisely the extension point above—would
+  otherwise open a race: caller A can finish, write the entry and release its in-flight slot
+  between B's read invocation and resolution; B would find neither cache hit nor in-flight entry
+  and embed the same text again. `fetchAndSettle` therefore rereads cache immediately before
+  requesting, strictly AFTER claiming the in-flight slot, which is released only after
+  `cache.set()` resolves. Exactly ONE additional read per claimed key: no waiting on another
+  caller's deferred work, so no deadlock, and no retry loop. **Cost:** a second `get()` on a real
+  miss, far cheaper than duplicate GPU-bound embedding. Read failures propagate rather than being
+  swallowed (E4), with the same visible behavior as failure of the first read.
+- **Second-read boundary:** it protects against duplicate work WITHIN one provider instance.
+  Caches without read-your-writes guarantees, such as replicated distributed caches, or separate
+  process instances can still embed twice; preventing that requires locking in the cache backend,
+  not this adapter.
+
+<a id="offene-punkte-openissues"></a>
+
+## Open issues (`openIssues`)
+
+- **`EmbeddingCachePort` conceptually belongs beside `EmbeddingProvider` in domain's `ports.ts`.**
+  It is local here because the original task required a local interface plus an open issue,
+  allowing immediate adapter testing without parallel edits to domain in the same wave. A
+  follow-up work package should move `EmbeddingCacheKey`/`EmbeddingCacheEntry`/`EmbeddingCachePort`
+  to domain and switch this adapter—and `storage-local` once it supplies persistence—to that import.
+- **`SleepFn` is also not a domain port.** Domain has `Clock` to read time, but no scheduling port
+  for an abortable wait of N milliseconds. A local type meets this package's determinism needs;
+  moving it to domain would be natural if another adapter needs it.
+- **Truncation detection is heuristic, not exact** (see Decisions). Without the model's real
+  tokenizer, which Ollama does not expose, exact prediction of server truncation is impossible.
+  The estimate is intentionally conservative, preferring excess `embedding_truncated=true` flags
+  over missing them, consistent with vision.md §8.4 (no silent data loss).
+
+## Tests
+
+- `src/*.test.ts`: network-free tests against injected fake `fetch`
+  (`test-helpers.ts`: `createFakeOllamaFetch`). Core coverage runs
+  `runEmbeddingProviderContract()` from `@untangle-code/testkit` against `OllamaEmbeddingProvider`
+  (`provider.test.ts`), plus dimension mismatch, backoff schedule (`backoff.test.ts`, deterministic
+  `Random` and recording `SleepFn`), cache hits without a second request, mid-batch `AbortSignal`
+  cancellation and truncation guards.
+- `src/provider.inflight.test.ts`: cache concurrency, in-flight deduplication (WP-78) and the
+  late-resolving-cache duplicate-embedding window (WP-117). `GatedLateEmbeddingCache` in
+  `test-helpers.ts` can hold a read beyond another call's completion without timing delays.
+- `src/ollama.integration.test.ts`: real Ollama at `127.0.0.1:11434` with `qwen3-embedding:0.6b`
+  (1024 dimensions). It self-skips (`describe.skipIf`) when the service/model is unavailable.
+  Run separately with `pnpm --filter @untangle-code/embeddings-ollama run test:integration`, never
+  as part of `pnpm test`/`vitest run` (see `vitest.config.ts` excludes and `vitest.integration.config.ts`).
+
+<a id="lizenz"></a>
+
+## License
+
+
+**AGPL-3.0-only.** This package includes the complete license in [`LICENSE`](./LICENSE), the
+license-choice rationale in [`NOTICE`](./NOTICE), and licenses for all third-party production
+dependencies in [`THIRD_PARTY_LICENSES.md`](./THIRD_PARTY_LICENSES.md). All three ship in the npm
+tarball: AGPL-3.0-only §4 and §5 require recipients to receive the license; a README alone is not
+a copy of the license.
+
+Local use alone does not trigger an obligation. Copyleft obligations apply to redistribution and
+providing a network service (AGPL §13).
+
+Corresponding TypeScript source ships under `src/` in the same tarball; the complete repository
+is available at <https://github.com/lboel/untangle>.

package/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,24 @@
+# Third-party licenses — @untangle-code/embeddings-ollama
+
+Generated by `pnpm third-party-licenses` from this package's installed
+production dependency tree: transitive `dependencies`, across
+workspace edges, with no `devDependencies` included. The generator reads
+each resolved package's `package.json` in `node_modules`; nothing is maintained by hand
+or estimated.
+
+Do not edit manually: `pnpm third-party-licenses --check` fails on drift,
+and `pnpm check-publishable` rejects packages without a current file.
+
+This file exists because `docs/BUILD_PLAN.md`, risk R6, makes
+per-package `THIRD_PARTY_LICENSES.md` a release gate for npm publication.
+
+Untangle itself is **AGPL-3.0-only** (see `LICENSE` and `NOTICE` in
+this package). The packages below are third-party works; their own
+licenses and copyright notices continue to apply unchanged. Workspace
+packages (`@untangle-code/*`) are not listed here; they belong to the same
+work and use the same AGPL-3.0-only license.
+
+## Result: no third-party dependencies
+
+This package has no production dependencies outside the workspace.
+The list is empty because none exist, not because they were not checked.

package/dist/backoff.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 declare function computeBackoffDelayMs(attempt: number, config: BackoffConfig, random: Random): number;
+export interface RetryOptions {
+    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 declare function withRetry<T>(fn: (attempt: number) => Promise<T>, config: BackoffConfig, deps: {
+    random: Random;
+    sleep: SleepFn;
+}, options: RetryOptions): Promise<T>;
+//# sourceMappingURL=backoff.d.ts.map

package/dist/backoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,GACb,MAAM,CAGR;AAED,MAAM,WAAW,YAAY;IAG3B,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACjC,oFAAoF;IACpF,WAAW,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACnC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EACxC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,CAAC,CAAC,CAeZ"}

package/dist/backoff.js

@@ -0,0 +1,38 @@
+/**
+ * "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, config, random) {
+    const cap = Math.min(config.maxDelayMs, config.baseDelayMs * 2 ** attempt);
+    return Math.round(random.nextFloat() * cap);
+}
+/**
+ * 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(fn, config, deps, options) {
+    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;
+        }
+    }
+}
+//# sourceMappingURL=backoff.js.map

package/dist/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAe,EACf,MAAqB,EACrB,MAAc;IAEd,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,WAAW,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC;IAC3E,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE,GAAG,GAAG,CAAC,CAAC;AAC9C,CAAC;AAUD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAmC,EACnC,MAAqB,EACrB,IAAwC,EACxC,OAAqB;IAErB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,SAAS,CAAC;QACR,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,OAAO,IAAI,MAAM,CAAC,UAAU,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;gBAChE,MAAM,KAAK,CAAC;YACd,CAAC;YACD,MAAM,OAAO,GAAG,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YACpE,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YAC1C,OAAO,IAAI,CAAC,CAAC;QACf,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/cache.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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";
+export declare class InMemoryEmbeddingCache implements EmbeddingCachePort {
+    private readonly entries;
+    get(key: EmbeddingCacheKey): Promise<EmbeddingCacheEntry | null>;
+    set(key: EmbeddingCacheKey, entry: EmbeddingCacheEntry): Promise<void>;
+    /** Test/debug helper: number of cached entries. */
+    get size(): number;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAM7F,qBAAa,sBAAuB,YAAW,kBAAkB;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0C;IAErD,GAAG,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAIhE,GAAG,CAAC,GAAG,EAAE,iBAAiB,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAInF,mDAAmD;IACnD,IAAW,IAAI,IAAI,MAAM,CAExB;CACF"}

package/dist/cache.js

@@ -0,0 +1,17 @@
+function cacheKeyString(key) {
+    return `${key.embeddingProfileId}:${key.preparedTextHash}`;
+}
+export class InMemoryEmbeddingCache {
+    entries = new Map();
+    async get(key) {
+        return this.entries.get(cacheKeyString(key)) ?? null;
+    }
+    async set(key, entry) {
+        this.entries.set(cacheKeyString(key), entry);
+    }
+    /** Test/debug helper: number of cached entries. */
+    get size() {
+        return this.entries.size;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAUA,SAAS,cAAc,CAAC,GAAsB;IAC5C,OAAO,GAAG,GAAG,CAAC,kBAAkB,IAAI,GAAG,CAAC,gBAAgB,EAAE,CAAC;AAC7D,CAAC;AAED,MAAM,OAAO,sBAAsB;IAChB,OAAO,GAAG,IAAI,GAAG,EAA+B,CAAC;IAE3D,KAAK,CAAC,GAAG,CAAC,GAAsB;QACrC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC;IACvD,CAAC;IAEM,KAAK,CAAC,GAAG,CAAC,GAAsB,EAAE,KAA0B;QACjE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC;IAED,mDAAmD;IACnD,IAAW,IAAI;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF"}

package/dist/concurrency.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../src/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6FAA6F;AAC7F,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAC3C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GACzC,OAAO,CAAC,CAAC,EAAE,CAAC,CAsBd"}

package/dist/concurrency.js

@@ -0,0 +1,31 @@
+/**
+ * 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(items, limit, fn) {
+    if (items.length === 0) {
+        return [];
+    }
+    const boundedLimit = Math.max(1, Math.min(limit, items.length));
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function worker() {
+        for (;;) {
+            const index = nextIndex;
+            nextIndex += 1;
+            if (index >= items.length) {
+                return;
+            }
+            const item = items[index];
+            results[index] = await fn(item, index);
+        }
+    }
+    await Promise.all(Array.from({ length: boundedLimit }, () => worker()));
+    return results;
+}
+//# sourceMappingURL=concurrency.js.map

package/dist/concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../src/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6FAA6F;AAC7F,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAmB,EACnB,KAAa,EACb,EAA0C;IAE1C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAChE,MAAM,OAAO,GAAG,IAAI,KAAK,CAAI,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,KAAK,UAAU,MAAM;QACnB,SAAS,CAAC;YACR,MAAM,KAAK,GAAG,SAAS,CAAC;YACxB,SAAS,IAAI,CAAC,CAAC;YACf,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;gBAC1B,OAAO;YACT,CAAC;YACD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAM,CAAC;YAC/B,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACxE,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/endpoint.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function redactEndpointUrl(rawUrl: string): string;
+/** Joins a base endpoint URL with a request path, tolerating a trailing slash on the base. */
+export declare function joinUrl(baseUrl: string, path: string): string;
+//# sourceMappingURL=endpoint.d.ts.map

package/dist/endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["../src/endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAaxD;AAED,8FAA8F;AAC9F,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7D"}

package/dist/endpoint.js

@@ -0,0 +1,32 @@
+/**
+ * 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) {
+    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, path) {
+    return new URL(path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`).toString();
+}
+//# sourceMappingURL=endpoint.js.map

package/dist/endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.js","sourceRoot":"","sources":["../src/endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;YACjC,GAAG,CAAC,QAAQ,GAAG,EAAE,CAAC;YAClB,GAAG,CAAC,QAAQ,GAAG,EAAE,CAAC;YAClB,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;QACxB,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;QAC/D,OAAO,MAAM,CAAC;IAChB,CAAC;AACH,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,OAAO,CAAC,OAAe,EAAE,IAAY;IACnD,OAAO,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;AACnF,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,54 @@
+/** Thrown by {@link OllamaHttpClient.requestJson} for any failed request. */
+export declare class OllamaHttpError extends Error {
+    readonly status: number | undefined;
+    readonly retryable: boolean;
+    constructor(message: string, options: {
+        status?: number;
+        retryable: boolean;
+        cause?: unknown;
+    });
+}
+/** Thrown when a request is aborted by the CALLER's own signal (never retried). */
+export declare class OllamaRequestCancelledError extends Error {
+    constructor(cause?: unknown);
+}
+/**
+ * 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 declare function isRequestCancellation(error: unknown, signal: AbortSignal | undefined): boolean;
+export interface OllamaHttpClientOptions {
+    requestTimeoutMs: number;
+    maxConnections: number;
+    apiKeyEnv?: string | undefined;
+    /** Injectable for tests; defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch | undefined;
+}
+export declare class OllamaHttpClient {
+    private readonly semaphore;
+    private readonly fetchImpl;
+    private readonly requestTimeoutMs;
+    private readonly apiKeyEnv;
+    constructor(options: OllamaHttpClientOptions);
+    /**
+     * 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.
+     */
+    requestJson<T>(baseUrl: string, path: string, init: {
+        method: "GET" | "POST";
+        body?: unknown;
+    }, signal?: AbortSignal): Promise<T>;
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAQA,6EAA6E;AAC7E,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAgB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,SAAgB,SAAS,EAAE,OAAO,CAAC;gBAGjC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAOpE;AAED,mFAAmF;AACnF,qBAAa,2BAA4B,SAAQ,KAAK;gBACjC,KAAK,CAAC,EAAE,OAAO;CAInC;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAM9F;AAkCD,MAAM,WAAW,uBAAuB;IACtC,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IAGvB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,OAAO,KAAK,GAAG,SAAS,CAAC;CACtC;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;gBAE5B,OAAO,EAAE,uBAAuB;IAOnD;;;;;;;;;OASG;IACU,WAAW,CAAC,CAAC,EACxB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;QAAE,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,EAChD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,CAAC,CAAC;CA+Cd"}