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

package/dist/provider.js

@@ -0,0 +1,374 @@
+import { buildEmbeddingProfileId, isUntangleError, sha256Hex } from "@untangle-code/domain";
+import { embeddingUnavailableError, jobCancelledError } from "@untangle-code/observability";
+import { withRetry } from "./backoff.js";
+import { InMemoryEmbeddingCache } from "./cache.js";
+import { mapWithConcurrency } from "./concurrency.js";
+import { isRequestCancellation, OllamaHttpClient, OllamaHttpError } from "./http.js";
+import { createDeferred, InFlightRegistry, raceWithSignal } from "./inflight.js";
+import { embed } from "./ollama-api.js";
+import { runReadinessSequence } from "./readiness.js";
+import { realSleep } from "./sleep.js";
+import { wouldProviderTruncate } from "./truncation.js";
+import { DEFAULT_BASE_BACKOFF_MS, DEFAULT_MAX_BACKOFF_MS, DEFAULT_MAX_RETRIES } from "./types.js";
+import { assertVectorDimension } from "./validation.js";
+function isRetryableEmbedError(error) {
+    return error instanceof OllamaHttpError && error.retryable;
+}
+/** Same shape as `cache.ts`'s internal key string — local to this module, used only for in-flight bookkeeping. */
+function cacheKeyString(key) {
+    return `${key.embeddingProfileId}:${key.preparedTextHash}`;
+}
+/** Splits `items` into consecutive slices of at most `size` (the last one possibly shorter). */
+function chunkIntoSlices(items, size) {
+    if (items.length === 0) {
+        return [];
+    }
+    const slices = [];
+    for (let start = 0; start < items.length; start += size) {
+        slices.push(items.slice(start, start + size));
+    }
+    return slices;
+}
+/** Normalizes any thrown value into the `UntangleError` this package's public API promises (rule 8). */
+function normalizeError(error, signal) {
+    if (isUntangleError(error)) {
+        return error;
+    }
+    if (isRequestCancellation(error, signal)) {
+        return jobCancelledError("Ollama embedding operation was cancelled.", {
+            cause: error,
+            retryable: false,
+        });
+    }
+    if (error instanceof OllamaHttpError) {
+        return embeddingUnavailableError(error.message, {
+            cause: error,
+            retryable: false,
+            context: error.status === undefined ? {} : { status: error.status },
+        });
+    }
+    return embeddingUnavailableError(`Unexpected Ollama embedding provider error: ${String(error)}`, {
+        cause: error,
+        retryable: false,
+    });
+}
+async function guarded(signal, fn) {
+    try {
+        signal?.throwIfAborted();
+        return await fn();
+    }
+    catch (error) {
+        throw normalizeError(error, signal);
+    }
+}
+export class OllamaEmbeddingProvider {
+    profile;
+    profileId;
+    config;
+    clock;
+    random;
+    cache;
+    sleep;
+    httpClient;
+    backoffConfig;
+    cachedReadiness;
+    resolvedEndpointUrl;
+    readyPromise;
+    /**
+     * One shared fetch-and-cache operation per still-uncached cache key
+     * (spec.md §9.4, WP-78): concurrent `embedDocuments`/`embedQuery` calls
+     * that race for the same not-yet-cached text join the SAME `/api/embed`
+     * request instead of each starting their own.
+     */
+    inFlightEmbeds = new InFlightRegistry();
+    constructor(config, deps) {
+        this.config = config;
+        this.profile = config.profile;
+        this.profileId = buildEmbeddingProfileId(config.profile);
+        this.clock = deps.clock;
+        this.random = deps.random;
+        this.cache = deps.cache ?? new InMemoryEmbeddingCache();
+        this.sleep = deps.sleep ?? realSleep;
+        this.httpClient = new OllamaHttpClient({
+            requestTimeoutMs: config.requestTimeoutMs,
+            maxConnections: config.maxConnections,
+            apiKeyEnv: config.apiKeyEnv,
+            fetchImpl: deps.fetchImpl,
+        });
+        this.backoffConfig = {
+            maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+            baseDelayMs: config.baseBackoffMs ?? DEFAULT_BASE_BACKOFF_MS,
+            maxDelayMs: config.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS,
+        };
+    }
+    async ensureReady(options) {
+        return guarded(options?.signal, async () => {
+            await this.ensureReadyOnce(options?.signal);
+            // Non-null: ensureReadyOnce either already resolved it or just did.
+            return this.cachedReadiness;
+        });
+    }
+    async embedDocuments(preparedTexts, options) {
+        return guarded(options?.signal, async () => {
+            if (preparedTexts.length === 0) {
+                return { vectors: [], truncated: [] };
+            }
+            await this.ensureReadyOnce(options?.signal);
+            return this.embedTexts(preparedTexts, options?.signal, options?.onBatchProgress);
+        });
+    }
+    async embedQuery(preparedText, options) {
+        return guarded(options?.signal, async () => {
+            await this.ensureReadyOnce(options?.signal);
+            const { vectors } = await this.embedTexts([preparedText], options?.signal);
+            return vectors[0];
+        });
+    }
+    /**
+     * Runs the readiness sequence exactly once per instance; concurrent
+     * callers (including through model-pull, spec.md §9.1 step 4) await the
+     * SAME run rather than each starting their own (WP-78 fehlerklasse: the
+     * same in-flight-dedup requirement applies here, not just to `/api/embed`).
+     *
+     * The shared run itself is started with NO caller's `signal` (it is
+     * intentionally not tied to whichever caller happened to trigger it) —
+     * `raceWithSignal` below still lets THIS caller's own signal reject its
+     * own wait promptly, without cancelling the readiness sequence still
+     * running for other, still-waiting callers.
+     */
+    async ensureReadyOnce(signal) {
+        if (this.cachedReadiness) {
+            return;
+        }
+        if (!this.readyPromise) {
+            this.readyPromise = this.runReadiness().catch((error) => {
+                // A failed attempt must not be cached — the next call retries from scratch.
+                this.readyPromise = undefined;
+                throw error;
+            });
+        }
+        await raceWithSignal(this.readyPromise, signal);
+    }
+    async runReadiness() {
+        const outcome = await runReadinessSequence(this.config, {
+            httpClient: this.httpClient,
+            clock: this.clock,
+            random: this.random,
+            sleep: this.sleep,
+            backoffConfig: this.backoffConfig,
+        }, undefined);
+        this.cachedReadiness = outcome.readiness;
+        this.resolvedEndpointUrl = outcome.endpointUrl;
+    }
+    async embedTexts(texts, signal, onBatchProgress) {
+        const endpointUrl = this.resolvedEndpointUrl;
+        if (!endpointUrl) {
+            throw embeddingUnavailableError("Ollama embedding provider is not ready (no resolved endpoint).", {
+                retryable: false,
+            });
+        }
+        const slices = chunkIntoSlices(texts, Math.max(1, this.config.batchSize));
+        const batchCount = slices.length;
+        let embeddedCount = 0;
+        const sliceResults = await mapWithConcurrency(slices, this.config.maxConnections, async (slice, sliceIndex) => {
+            signal?.throwIfAborted();
+            const result = await this.embedSlice(slice, endpointUrl, signal);
+            embeddedCount += slice.length;
+            onBatchProgress?.({
+                batchIndex: sliceIndex,
+                batchCount,
+                embeddedCount,
+                totalCount: texts.length,
+            });
+            return result;
+        });
+        const vectors = sliceResults.flatMap((result) => result.vectors);
+        const truncated = sliceResults.flatMap((result) => result.truncated);
+        return { vectors, truncated };
+    }
+    async embedSlice(texts, endpointUrl, signal) {
+        const keys = texts.map((text) => ({
+            embeddingProfileId: this.profileId,
+            preparedTextHash: sha256Hex(text),
+        }));
+        const keyStrings = keys.map(cacheKeyString);
+        const cached = await Promise.all(keys.map((key) => this.cache.get(key, { signal })));
+        const vectors = new Array(texts.length);
+        const truncated = new Array(texts.length);
+        // Group the still-missing positions by cache key: (a) the SAME prepared
+        // text appearing more than once in this slice must be embedded only
+        // once (spec.md §9.4, WP-78 "Batch-interne Deduplizierung"), and (b) a
+        // key already being fetched by ANOTHER concurrent call is joined below
+        // instead of triggering a second `/api/embed` request.
+        const missGroups = new Map();
+        for (let index = 0; index < texts.length; index += 1) {
+            const hit = cached[index];
+            if (hit) {
+                vectors[index] = hit.vector;
+                truncated[index] = hit.truncated;
+                continue;
+            }
+            const keyString = keyStrings[index];
+            const group = missGroups.get(keyString);
+            if (group) {
+                group.push(index);
+            }
+            else {
+                missGroups.set(keyString, [index]);
+            }
+        }
+        if (missGroups.size === 0) {
+            return { vectors, truncated };
+        }
+        signal?.throwIfAborted();
+        // Claim/join in-flight fetches. This loop MUST NOT `await` anything: two
+        // concurrent `embedSlice` calls that both read a cache miss for the same
+        // key resume as two separate, atomically-run continuations (JS never
+        // interleaves them mid-loop), so whichever runs this claiming loop first
+        // wins the key and the other necessarily observes and joins it instead
+        // of starting its own fetch (WP-78 "Nebenläufigkeit").
+        const toFetch = [];
+        const pending = [];
+        for (const [keyString, indexes] of missGroups) {
+            const existing = this.inFlightEmbeds.get(keyString);
+            if (existing) {
+                pending.push({ indexes, promise: existing });
+                continue;
+            }
+            const deferred = createDeferred();
+            this.inFlightEmbeds.register(keyString, deferred.promise);
+            const firstIndex = indexes[0];
+            toFetch.push({
+                keyString,
+                key: keys[firstIndex],
+                text: texts[firstIndex],
+                deferred,
+            });
+            pending.push({ indexes, promise: deferred.promise });
+        }
+        if (toFetch.length > 0) {
+            // Deliberately not awaited here: the underlying request must survive
+            // (and keep serving every joined caller) even if THIS caller — the
+            // one that happened to claim the keys — is the one whose own signal
+            // aborts. Errors are routed to each `deferred` inside the method, so
+            // this can never become an unhandled rejection.
+            void this.fetchAndSettle(toFetch, endpointUrl);
+        }
+        await Promise.all(pending.map(async ({ indexes, promise }) => {
+            // `raceWithSignal`, not `promise` directly: THIS call's own signal
+            // must be able to reject THIS call without cancelling the shared
+            // fetch for any other caller still awaiting the same key.
+            const entry = await raceWithSignal(promise, signal);
+            for (const index of indexes) {
+                vectors[index] = entry.vector;
+                truncated[index] = entry.truncated;
+            }
+        }));
+        return { vectors, truncated };
+    }
+    /**
+     * Fetches every text in `items` in a SINGLE `/api/embed` request and
+     * settles each item's `deferred` with its own resulting cache entry, or
+     * rejects all of them on failure — which also frees their in-flight slots
+     * (`InFlightRegistry.register`'s cleanup), so the next call retries from
+     * scratch rather than being stuck on a broken promise (WP-78).
+     *
+     * Vor dem Absetzen des Requests wird der Cache ein ZWEITES Mal gelesen
+     * (WP-117, siehe {@link revalidateBeforeFetch}): die Miss-Entscheidung in
+     * `embedSlice` kann veraltet sein, sobald `cache.get()` verzögert auflöst.
+     *
+     * Intentionally takes no `AbortSignal`: this operation is shared by
+     * however many callers joined it, so it is not tied to any single one of
+     * their lifecycles (see `embedSlice`/`raceWithSignal`).
+     */
+    async fetchAndSettle(items, endpointUrl) {
+        try {
+            // WP-117: erst jetzt, mit den bereits beanspruchten In-flight-Plätzen
+            // in der Hand, steht fest, was wirklich über die Leitung muss.
+            const outstanding = await this.revalidateBeforeFetch(items);
+            if (outstanding.length === 0) {
+                return;
+            }
+            const texts = outstanding.map((item) => item.text);
+            const response = await withRetry(() => embed(this.httpClient, endpointUrl, this.profile.model, texts), this.backoffConfig, { random: this.random, sleep: this.sleep }, { isRetryable: isRetryableEmbedError });
+            if (response.embeddings.length !== outstanding.length) {
+                throw embeddingUnavailableError(`Ollama /api/embed returned ${response.embeddings.length} vectors for ${outstanding.length} inputs.`, { retryable: false });
+            }
+            for (let j = 0; j < outstanding.length; j += 1) {
+                const item = outstanding[j];
+                const vector = response.embeddings[j];
+                assertVectorDimension(vector, this.profile.dimensions, {
+                    endpoint: endpointUrl,
+                    model: this.profile.model,
+                    stage: "embed",
+                });
+                const isTruncated = wouldProviderTruncate(item.text, this.config.contextLength);
+                const entry = { vector, truncated: isTruncated };
+                await this.cache.set(item.key, entry);
+                item.deferred.resolve(entry);
+            }
+        }
+        catch (error) {
+            // Bewusst über `items` und nicht über `outstanding`: schlägt schon die
+            // Revalidierung fehl, ist `outstanding` gar nicht bestimmt. Ein bereits
+            // aus dem Cache aufgelöstes Deferred ignoriert das spätere `reject`
+            // (die erste Festlegung gewinnt), ein noch offenes wird sicher
+            // abgewiesen — kein Aufrufer bleibt hängen.
+            for (const item of items) {
+                item.deferred.reject(error);
+            }
+        }
+    }
+    /**
+     * Zweite Cache-Prüfung unmittelbar vor dem Request (WP-117).
+     *
+     * `embedSlice` trifft die Miss-/Join-Entscheidung EINMAL, aus einem
+     * einzigen `Promise.all` über `cache.get()`. Ein Cache, dessen `get()` den
+     * Zustand zum Aufrufzeitpunkt liest, aber erst später auflöst — also jeder
+     * netzgebundene Cache und damit genau der vorgesehene Erweiterungspunkt
+     * für einen persistenten Adapter —, öffnet ein Fenster: Aufrufer A kann
+     * zwischen der Anfrage und dem Auflösen von B's `get()` vollständig fertig
+     * werden, seinen Eintrag schreiben und seinen In-flight-Platz wieder
+     * freigeben. B fände dann weder Cache-Treffer noch In-flight-Eintrag und
+     * würde denselben Text ein zweites Mal einbetten.
+     *
+     * Diese Prüfung schließt das Fenster, weil sie STRIKT NACH der Beanspruchung
+     * des In-flight-Platzes liegt: der Platz wird erst freigegeben, nachdem
+     * `cache.set()` aufgelöst hat (siehe unten), also sieht ein `get()`, das
+     * danach abgesetzt wird, den geschriebenen Eintrag.
+     *
+     * Kein Deadlock und keine Wiederholungsschleife: genau EIN zusätzliches
+     * `cache.get()` je beanspruchtem Schlüssel, kein Warten auf fremde
+     * Deferreds (die eigenen Plätze hält dieser Aufruf selbst, ein anderer
+     * Aufrufer kann sie also nicht beanspruchen), und jedes Deferred wird auf
+     * jedem Pfad festgelegt — aus dem Cache, aus der Antwort oder per
+     * `reject` im `catch`.
+     *
+     * Kein `AbortSignal`: dieser Lauf gehört keinem einzelnen Aufrufer
+     * (dieselbe Begründung wie bei {@link fetchAndSettle}).
+     *
+     * Ein Fehler des Caches wird NICHT verschluckt (E4), sondern nach oben
+     * gereicht und weist damit die beteiligten Deferreds ab — dasselbe
+     * sichtbare Verhalten wie bei einem Fehlschlag der ERSTEN Cache-Lesung in
+     * `embedSlice`. Preis dieser Prüfung: eine zusätzliche Cache-Lesung je
+     * echtem Miss (dokumentiert in der README).
+     */
+    async revalidateBeforeFetch(items) {
+        // Erst alle Lesungen abschließen, dann festlegen: so ist bei einem Fehler
+        // noch kein Deferred aufgelöst und der `catch` in `fetchAndSettle` weist
+        // wirklich alle ab.
+        const lateHits = await Promise.all(items.map(async (item) => this.cache.get(item.key)));
+        const outstanding = [];
+        for (let index = 0; index < items.length; index += 1) {
+            const item = items[index];
+            const hit = lateHits[index];
+            if (hit) {
+                item.deferred.resolve(hit);
+                continue;
+            }
+            outstanding.push(item);
+        }
+        return outstanding;
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}

package/dist/readiness.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Readiness sequence (spec.md §9.1), run exactly in the spec's order:
+ *
+ * 1. determine the effective endpoint;
+ * 2. check reachability;
+ * 3. check model availability;
+ * 4. pull the model in managed mode if needed;
+ * 5. produce a probe embedding;
+ * 6. validate the vector dimension;
+ * 7. cache profile and probe timestamp (done by the caller, `provider.ts`,
+ *    which owns the cached `EmbeddingReadinessV1`).
+ */
+import type { Clock, EmbeddingReadinessV1, Random } from "@untangle-code/domain";
+import type { BackoffConfig } from "./backoff.js";
+import { type OllamaHttpClient } from "./http.js";
+import type { SleepFn, OllamaEmbeddingProviderConfig } from "./types.js";
+export declare const READINESS_PROBE_TEXT = "untangle embedding readiness probe";
+export interface ReadinessDeps {
+    httpClient: OllamaHttpClient;
+    clock: Clock;
+    random: Random;
+    sleep: SleepFn;
+    backoffConfig: BackoffConfig;
+}
+export interface ReadinessOutcome {
+    readiness: EmbeddingReadinessV1;
+    /** The resolved, non-redacted endpoint — used internally for subsequent embed calls. */
+    endpointUrl: string;
+}
+export declare function runReadinessSequence(config: OllamaEmbeddingProviderConfig, deps: ReadinessDeps, signal?: AbortSignal): Promise<ReadinessOutcome>;
+//# sourceMappingURL=readiness.d.ts.map

package/dist/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../src/readiness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAGjF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAGlD,OAAO,EAA0C,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAQ1F,OAAO,KAAK,EAAE,OAAO,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAIzE,eAAO,MAAM,oBAAoB,uCAAuC,CAAC;AAEzE,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,oBAAoB,CAAC;IAChC,wFAAwF;IACxF,WAAW,EAAE,MAAM,CAAC;CACrB;AA6FD,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,6BAA6B,EACrC,IAAI,EAAE,aAAa,EACnB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,gBAAgB,CAAC,CA6D3B"}

package/dist/readiness.js

@@ -0,0 +1,105 @@
+import { configInvalidError, embeddingUnavailableError } from "@untangle-code/observability";
+import { withRetry } from "./backoff.js";
+import { redactEndpointUrl } from "./endpoint.js";
+import { isRequestCancellation, OllamaHttpError } from "./http.js";
+import { embed, listTags, pullModel, tagsContainModel, } from "./ollama-api.js";
+import { DEFAULT_MANAGED_URL, DEFAULT_NATIVE_PROBE_URL } from "./types.js";
+import { assertVectorDimension } from "./validation.js";
+export const READINESS_PROBE_TEXT = "untangle embedding readiness probe";
+function isRetryableOllamaError(error) {
+    return error instanceof OllamaHttpError && error.retryable;
+}
+async function requestWithRetry(fn, deps, signal) {
+    return withRetry(fn, deps.backoffConfig, { random: deps.random, sleep: deps.sleep }, {
+        signal,
+        isRetryable: isRetryableOllamaError,
+    });
+}
+/** `GET /api/tags`, treating any failure as "not reachable" — EXCEPT cancellation, which propagates. */
+async function tryListTags(url, deps, signal) {
+    try {
+        return await requestWithRetry(() => listTags(deps.httpClient, url, signal), deps, signal);
+    }
+    catch (error) {
+        if (isRequestCancellation(error, signal)) {
+            throw error;
+        }
+        return null;
+    }
+}
+async function checkReachable(url, deps, signal) {
+    const tags = await tryListTags(url, deps, signal);
+    if (!tags) {
+        throw embeddingUnavailableError(`Ollama endpoint ${redactEndpointUrl(url)} is not reachable.`, {
+            retryable: true,
+            context: { endpoint: redactEndpointUrl(url) },
+        });
+    }
+    return tags;
+}
+/** spec.md §9.1 steps 1-2: determine the effective endpoint and confirm it is reachable. */
+async function resolveEndpoint(config, deps, signal) {
+    if (config.mode === "external") {
+        if (!config.url) {
+            throw configInvalidError('EmbeddingConfig.url is required when embeddings.mode is "external" (spec.md §4.5).', { retryable: false });
+        }
+        return {
+            url: config.url,
+            managed: false,
+            tags: await checkReachable(config.url, deps, signal),
+        };
+    }
+    if (config.mode === "managed") {
+        const url = config.url ?? config.managedUrl ?? DEFAULT_MANAGED_URL;
+        return { url, managed: true, tags: await checkReachable(url, deps, signal) };
+    }
+    // "auto" (spec.md §3.1): native probe first, managed endpoint as fallback.
+    const nativeUrl = config.nativeProbeUrl ?? DEFAULT_NATIVE_PROBE_URL;
+    const nativeTags = await tryListTags(nativeUrl, deps, signal);
+    if (nativeTags) {
+        return { url: nativeUrl, managed: false, tags: nativeTags };
+    }
+    const managedUrl = config.url ?? config.managedUrl ?? DEFAULT_MANAGED_URL;
+    return { url: managedUrl, managed: true, tags: await checkReachable(managedUrl, deps, signal) };
+}
+export async function runReadinessSequence(config, deps, signal) {
+    const { url, managed, tags } = await resolveEndpoint(config, deps, signal);
+    const modelName = config.profile.model;
+    // Step 3: model availability.
+    let available = tagsContainModel(tags.models, modelName);
+    // Step 4: pull in managed mode if needed (spec.md §3.2 forbids touching an external endpoint).
+    if (!available) {
+        if (!managed) {
+            throw embeddingUnavailableError(`Ollama model "${modelName}" is not available at ${redactEndpointUrl(url)}, and this endpoint is not managed by Untangle — pull it manually (spec.md §3.2).`, { retryable: false, context: { endpoint: redactEndpointUrl(url), model: modelName } });
+        }
+        await requestWithRetry(() => pullModel(deps.httpClient, url, modelName, signal), deps, signal);
+        const refreshed = await requestWithRetry(() => listTags(deps.httpClient, url, signal), deps, signal);
+        available = tagsContainModel(refreshed.models, modelName);
+        if (!available) {
+            throw embeddingUnavailableError(`Ollama model "${modelName}" was still not available after pulling it from ${redactEndpointUrl(url)}.`, { retryable: false, context: { endpoint: redactEndpointUrl(url), model: modelName } });
+        }
+    }
+    // Step 5: probe embedding.
+    const probeResponse = await requestWithRetry(() => embed(deps.httpClient, url, modelName, [READINESS_PROBE_TEXT], signal), deps, signal);
+    const probeVector = probeResponse.embeddings[0];
+    if (!probeVector) {
+        throw embeddingUnavailableError(`Ollama probe embedding returned no vector for model "${modelName}".`, { retryable: false, context: { endpoint: redactEndpointUrl(url), model: modelName } });
+    }
+    // Step 6: dimension validation (must fail BEFORE the first upsert, spec.md §4.8).
+    assertVectorDimension(probeVector, config.profile.dimensions, {
+        endpoint: redactEndpointUrl(url),
+        model: modelName,
+        stage: "readiness_probe",
+    });
+    // Step 7: profile + probe timestamp are cached by the caller from this result.
+    return {
+        readiness: {
+            endpoint: redactEndpointUrl(url),
+            model: modelName,
+            dimensions: probeVector.length,
+            probedAt: deps.clock.nowIso(),
+        },
+        endpointUrl: url,
+    };
+}
+//# sourceMappingURL=readiness.js.map

package/dist/readiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.js","sourceRoot":"","sources":["../src/readiness.ts"],"names":[],"mappings":"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"}

package/dist/sleep.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Real, abortable {@link SleepFn} implementation. The only production
+ * implementation of the port declared in `types.ts`; tests inject a fake
+ * that resolves immediately instead of waiting for real time to pass.
+ */
+import type { SleepFn } from "./types.js";
+export declare const realSleep: SleepFn;
+//# sourceMappingURL=sleep.d.ts.map

package/dist/sleep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.d.ts","sourceRoot":"","sources":["../src/sleep.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,eAAO,MAAM,SAAS,EAAE,OAmBpB,CAAC"}

package/dist/sleep.js

@@ -0,0 +1,20 @@
+export const realSleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(signal.reason);
+        return;
+    }
+    const timer = setTimeout(() => {
+        cleanup();
+        resolve();
+    }, ms);
+    const onAbort = () => {
+        cleanup();
+        reject(signal?.reason);
+    };
+    function cleanup() {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+});
+//# sourceMappingURL=sleep.js.map

package/dist/sleep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.js","sourceRoot":"","sources":["../src/sleep.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,SAAS,GAAY,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAC/C,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;IACpC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;QACpB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACtB,OAAO;IACT,CAAC;IACD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;QAC5B,OAAO,EAAE,CAAC;QACV,OAAO,EAAE,CAAC;IACZ,CAAC,EAAE,EAAE,CAAC,CAAC;IACP,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,OAAO,EAAE,CAAC;QACV,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzB,CAAC,CAAC;IACF,SAAS,OAAO;QACd,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;IACD,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AAC7D,CAAC,CAAC,CAAC"}

package/dist/truncation.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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).
+ */
+/** Estimates a conservative (over-)approximation of `text`'s token count. */
+export declare function estimateTokenCount(text: string): number;
+/**
+ * True when `text`'s estimated token count exceeds `contextLength` — the
+ * point at which Ollama's provider-side truncation actually applies.
+ */
+export declare function wouldProviderTruncate(text: string, contextLength: number): boolean;
+//# sourceMappingURL=truncation.d.ts.map

package/dist/truncation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncation.d.ts","sourceRoot":"","sources":["../src/truncation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKvD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAElF"}