gitnexus 1.6.10-rc.21 → 1.6.10-rc.211

package/dist/core/embeddings/http-client.js

@@ -10,26 +10,102 @@
  * fails fast on a flapping endpoint. Per-attempt timeout is enforced
  * via `AbortSignal.timeout` on the underlying fetch.
  */
-import { CircuitOpenError, ResilientFetchExhaustedError, resilientFetch } from '../../_shared/index.js';
-const HTTP_TIMEOUT_MS = 30_000;
+import { chunk } from '../../lib/utils.js';
+import { CircuitOpenError, ResilientFetchExhaustedError, isTerminalNetworkError, resilientFetch, } from '../../_shared/index.js';
+const DEFAULT_HTTP_TIMEOUT_MS = 180_000;
+const MAX_HTTP_TIMEOUT_MS = 300_000;
 const HTTP_MAX_RETRIES = 2;
 const HTTP_RETRY_BACKOFF_MS = 1_000;
+const HTTP_RETRY_CAP_MS = 5_000;
 const HTTP_BATCH_SIZE = 64;
 const DEFAULT_DIMS = 384;
 const HTTP_BREAKER_KEY = 'embeddings-http';
+const HTTP_TIMEOUT_ENV = 'GITNEXUS_EMBEDDING_HTTP_TIMEOUT_MS';
+let lastHttpRequestStartedAt;
+let httpPaceQueue = Promise.resolve();
+const parsePositiveIntegerEnv = (name, fallback, max) => {
+    const raw = process.env[name];
+    if (raw === undefined || raw === '')
+        return fallback;
+    if (!/^\d+$/u.test(raw)) {
+        throw new Error(`${name} must be a positive integer, got "${raw}"`);
+    }
+    const parsed = Number(raw);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0 || parsed > max) {
+        throw new Error(`${name} must be a positive integer <= ${max}, got "${raw}"`);
+    }
+    return parsed;
+};
+const parseNonNegativeIntegerEnv = (name, fallback, max) => {
+    const raw = process.env[name];
+    if (raw === undefined || raw === '')
+        return fallback;
+    if (!/^\d+$/u.test(raw)) {
+        throw new Error(`${name} must be a non-negative integer, got "${raw}"`);
+    }
+    const parsed = Number(raw);
+    if (!Number.isSafeInteger(parsed) || parsed < 0 || parsed > max) {
+        throw new Error(`${name} must be a non-negative integer <= ${max}, got "${raw}"`);
+    }
+    return parsed;
+};
+const cancelledError = () => new DOMException('Embedding request cancelled', 'AbortError');
+const throwIfAborted = (signal) => {
+    if (signal?.aborted)
+        throw cancelledError();
+};
+const abortableSleep = (ms, signal) => {
+    throwIfAborted(signal);
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            reject(cancelledError());
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+};
+const paceHttpRequest = async (minIntervalMs, signal) => {
+    throwIfAborted(signal);
+    if (minIntervalMs <= 0)
+        return;
+    const waitTurn = httpPaceQueue.then(async () => {
+        throwIfAborted(signal);
+        const waitMs = lastHttpRequestStartedAt === undefined
+            ? 0
+            : Math.max(0, lastHttpRequestStartedAt + minIntervalMs - Date.now());
+        await abortableSleep(waitMs, signal);
+        throwIfAborted(signal);
+        lastHttpRequestStartedAt = Date.now();
+    });
+    httpPaceQueue = waitTurn.catch(() => undefined);
+    await waitTurn;
+};
 /**
- * Stable lead of the {@link readConfig} malformed-`GITNEXUS_EMBEDDING_DIMS`
- * error. `readConfig` throws a plain `Error` (not an {@link HttpEmbeddingError})
- * because this is a *config* mistake, not an endpoint failure — so the CLI
- * recognizes it by this lead ({@link isHttpEmbeddingDimsError}) and prints a
- * clean config message instead of a raw stack dump. See #2385.
+ * Stable lead of a {@link readConfig} malformed dims-env error. `readConfig`
+ * throws a plain `Error` (not an {@link HttpEmbeddingError}) for a malformed
+ * `GITNEXUS_EMBEDDING_DIMS` or `GITNEXUS_EMBEDDING_REQUEST_DIMS` because it's a
+ * *config* mistake, not an endpoint failure — so the CLI recognizes it by this
+ * lead ({@link isHttpEmbeddingDimsError}) and prints a clean config message
+ * instead of a raw stack dump. Each var names itself so the message points the
+ * operator at the variable they actually set, not a sibling. See #2385.
  */
-const EMBEDDING_DIMS_ENV_ERROR_LEAD = 'GITNEXUS_EMBEDDING_DIMS must be a positive integer';
+const dimsEnvErrorLead = (name) => `${name} must be a positive integer`;
+const EMBEDDING_DIMS_ENV_ERROR_LEAD = dimsEnvErrorLead('GITNEXUS_EMBEDDING_DIMS');
+const EMBEDDING_REQUEST_DIMS_ENV_ERROR_LEAD = dimsEnvErrorLead('GITNEXUS_EMBEDDING_REQUEST_DIMS');
 /**
- * @internal Exported for the CLI analyze error handler. True when `message` is
- * the {@link readConfig} malformed-DIMS config error (a plain `Error`).
+ * @internal Exported for the CLI analyze error handler. True when `message` is a
+ * {@link readConfig} malformed dims-env config error (a plain `Error`) — for
+ * either `GITNEXUS_EMBEDDING_DIMS` or `GITNEXUS_EMBEDDING_REQUEST_DIMS`.
  */
-export const isHttpEmbeddingDimsError = (message) => message.includes(EMBEDDING_DIMS_ENV_ERROR_LEAD);
+export const isHttpEmbeddingDimsError = (message) => message.includes(EMBEDDING_DIMS_ENV_ERROR_LEAD) ||
+    message.includes(EMBEDDING_REQUEST_DIMS_ENV_ERROR_LEAD);
 /**
  * Build config from the current process.env snapshot.
  * Returns null when GITNEXUS_EMBEDDING_URL + GITNEXUS_EMBEDDING_MODEL are unset.
@@ -55,11 +131,33 @@ const readConfig = () => {
         }
         dimensions = parsed;
     }
+    const rawRequestDims = process.env.GITNEXUS_EMBEDDING_REQUEST_DIMS?.trim();
+    let requestDimensions = dimensions;
+    if (rawRequestDims) {
+        if (/^(omit|none|off|false|0)$/i.test(rawRequestDims)) {
+            requestDimensions = undefined;
+        }
+        else {
+            if (!/^\d+$/.test(rawRequestDims)) {
+                throw new Error(`${EMBEDDING_REQUEST_DIMS_ENV_ERROR_LEAD}, got "${rawRequestDims}"`);
+            }
+            const parsed = parseInt(rawRequestDims, 10);
+            if (parsed <= 0) {
+                throw new Error(`${EMBEDDING_REQUEST_DIMS_ENV_ERROR_LEAD}, got "${rawRequestDims}"`);
+            }
+            requestDimensions = parsed;
+        }
+    }
     return {
         baseUrl: baseUrl.replace(/\/+$/, ''),
         model,
         apiKey: process.env.GITNEXUS_EMBEDDING_API_KEY ?? 'unused',
         dimensions,
+        maxAttempts: parsePositiveIntegerEnv('GITNEXUS_EMBEDDING_MAX_ATTEMPTS', HTTP_MAX_RETRIES + 1, 20),
+        retryCapMs: parsePositiveIntegerEnv('GITNEXUS_EMBEDDING_RETRY_CAP_MS', HTTP_RETRY_CAP_MS, 300_000),
+        minIntervalMs: parseNonNegativeIntegerEnv('GITNEXUS_EMBEDDING_MIN_INTERVAL_MS', 0, 300_000),
+        timeoutMs: parsePositiveIntegerEnv(HTTP_TIMEOUT_ENV, DEFAULT_HTTP_TIMEOUT_MS, MAX_HTTP_TIMEOUT_MS),
+        requestDimensions,
     };
 };
 /**
@@ -77,6 +175,11 @@ export const isHttpMode = () => Boolean(process.env.GITNEXUS_EMBEDDING_URL && pr
  * if HTTP mode is not active or no explicit dimensions are set.
  */
 export const getHttpDimensions = () => readConfig()?.dimensions;
+/**
+ * Return the configured per-request HTTP timeout for HTTP mode, or undefined
+ * when HTTP mode is not active.
+ */
+export const getHttpTimeoutMs = () => readConfig()?.timeoutMs;
 /**
  * Return a safe representation of a URL for logs and error messages.
  * Strips query string (may contain tokens) and userinfo (may contain
@@ -102,10 +205,15 @@ export const safeUrl = (url) => {
  * its masked form, then strip any residual `scheme://userinfo@` the transport may
  * have echoed in a normalized (non-exact) form. See #2385.
  */
-const sanitizeReason = (reason, url) => reason
-    .split(url)
-    .join(safeUrl(url))
-    .replace(/([a-z][a-z0-9+.-]*:\/\/)[^/@\s]*@/gi, '$1');
+const sanitizeReason = (reason, url, apiKey) => {
+    const withoutUrlCredentials = reason
+        .split(url)
+        .join(safeUrl(url))
+        .replace(/([a-z][a-z0-9+.-]*:\/\/)[^/@\s]*@/gi, '$1');
+    return apiKey && apiKey !== 'unused'
+        ? withoutUrlCredentials.split(apiKey).join('[redacted]')
+        : withoutUrlCredentials;
+};
 /**
  * Error thrown by this module's HTTP embedding path (`httpEmbedBatch` /
  * `httpEmbed` / `httpEmbedQuery`) for any endpoint failure — a
@@ -149,6 +257,37 @@ export const isHttpEmbeddingError = (err) => err instanceof HttpEmbeddingError |
 const isEmbeddingItem = (item) => typeof item === 'object' &&
     item !== null &&
     Array.isArray(item.embedding);
+/**
+ * Module-private signal that a 2xx response carried a body this client cannot
+ * use (unparseable, or parseable but wrong-shaped). Deliberately not exported:
+ * it never escapes {@link httpEmbedBatch}, which converts it into the
+ * user-facing {@link HttpEmbeddingError} it carries in `terminalMessage`.
+ *
+ * Thrown from inside the `fetchImpl` callback so `resilientFetch` classifies it
+ * as `retryable-network` — a truncated or HTML body is the same class of
+ * endpoint failure as a 503 and deserves the same backoff loop, and routing it
+ * through the retry loop also makes the circuit breaker see it as a failure
+ * instead of erasing the outage signal with `recordSuccess()`. See #2790.
+ */
+class RetryableEmbeddingBodyError extends Error {
+    terminalMessage;
+    constructor(terminalMessage, options) {
+        super(terminalMessage, options?.cause !== undefined ? { cause: options.cause } : undefined);
+        this.terminalMessage = terminalMessage;
+        this.name = 'RetryableEmbeddingBodyError';
+    }
+}
+/**
+ * Build the message for a 2xx body carrying the wrong number of vectors.
+ *
+ * Hoisted to module scope because two layers report this same fault — the
+ * in-loop check inside {@link httpEmbedBatch} and the defensive backstop in
+ * {@link httpEmbed} — and the operator must see one wording regardless of which
+ * one catches it. Names both counts: "0 vectors for 64 texts" is actionable,
+ * "unexpected response shape" is not.
+ */
+const countMismatchMessage = (received, expected, safeEndpoint, batchIndex) => `Embedding endpoint returned ${received} vectors for ${expected} texts ` +
+    `(${safeEndpoint}, batch ${batchIndex})`;
 /**
  * Send a single batch of texts to the embedding endpoint with retry.
  *
@@ -161,11 +300,11 @@ const isEmbeddingItem = (item) => typeof item === 'object' &&
  *   the `dimensions` field in the request body. Endpoints that implement
  *   Matryoshka truncation (OpenAI text-embedding-3-*, Cohere embed-v3,
  *   Voyage) return a truncated vector at that size; endpoints that do not
- *   recognise the field may ignore it or return 400. Leave
- *   `GITNEXUS_EMBEDDING_DIMS` unset for strict backends that reject
- *   unknown fields.
+ *   recognise the field may ignore it or return 400. Set
+ *   `GITNEXUS_EMBEDDING_REQUEST_DIMS=omit` for strict backends while keeping
+ *   `GITNEXUS_EMBEDDING_DIMS` set to the returned vector size.
  */
-const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, dimensions) => {
+const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, dimensions, requestOptions = {}, maxAttempts = HTTP_MAX_RETRIES + 1, retryCapMs = HTTP_RETRY_CAP_MS, minIntervalMs = 0, timeoutMs = DEFAULT_HTTP_TIMEOUT_MS) => {
     const requestBody = {
         input: batch,
         model,
@@ -173,54 +312,132 @@ const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, dimensi
     if (dimensions !== undefined) {
         requestBody.dimensions = dimensions;
     }
+    // Built on demand, not up front. Both describe faults, so in a healthy run —
+    // every call of it — they are garbage, and each `safeUrl` parses a URL. A
+    // 300k-chunk run at subBatchSize 8 makes ~37.5k `httpEmbedBatch` calls, so
+    // eager construction spent two `new URL()` per call describing failures that
+    // never happened. Same shape as `countMismatchMessage` above.
+    const unparseableMessage = () => `Embedding endpoint returned an unparseable response (${safeUrl(url)}, batch ${batchIndex})`;
+    const unexpectedShapeMessage = () => `Embedding endpoint returned an unexpected response shape (${safeUrl(url)}, batch ${batchIndex})`;
     let resp;
+    // Set by `fetchImpl` on the attempt that produced a usable body. Reads back
+    // as `undefined` only on a path that must already have thrown — see the
+    // defensive check after the retry loop.
+    let parsed;
     try {
+        throwIfAborted(requestOptions.signal);
         resp = await resilientFetch(url, {
             method: 'POST',
-            signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
             headers: {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${apiKey}`,
             },
             body: JSON.stringify(requestBody),
         }, {
+            fetchImpl: async (input, init) => {
+                await paceHttpRequest(minIntervalMs, requestOptions.signal);
+                throwIfAborted(requestOptions.signal);
+                const timeoutSignal = AbortSignal.timeout(timeoutMs);
+                const signal = requestOptions.signal
+                    ? AbortSignal.any([requestOptions.signal, timeoutSignal])
+                    : timeoutSignal;
+                const attemptResp = await globalThis.fetch(input, { ...init, signal });
+                // Non-OK bodies are none of our business: hand the response straight
+                // back so `resilientFetch` keeps classifying 4xx/5xx/429 unchanged.
+                if (!attemptResp.ok)
+                    return attemptResp;
+                // The body is read *here*, inside the retried callback, rather than
+                // after `resilientFetch` returns. A reachable-but-wrong endpoint (a
+                // captive portal, a non-embeddings service, a truncated stream) can
+                // answer 200 with HTML or half a JSON document; parsing outside the
+                // loop made that a one-shot terminal failure while a 503 got three
+                // attempts. Throwing from in here gives a bad body the same backoff
+                // and the same breaker accounting as any other endpoint fault (#2790).
+                let payload;
+                try {
+                    payload = (await attemptResp.json());
+                }
+                catch (err) {
+                    // Not every `.json()` rejection is a parse error: the per-attempt
+                    // signal (`AbortSignal.any([caller, AbortSignal.timeout(...)])`) is
+                    // wired to the body stream, so a stalled body rejects with the abort
+                    // reason. Re-raise those untouched — `isTerminalNetworkError` is
+                    // `resilientFetch`'s own predicate, so this test agrees with
+                    // `classifyOutcome` by construction. Wrapping one would flip its
+                    // verdict from `terminal-network` (returned without retry AND
+                    // without touching the breaker, via `recordNeutral()`) to
+                    // `retryable-network` (retried, then `breaker.recordFailure()`): the
+                    // same timeout would take 3 attempts instead of 1, count toward the
+                    // process-global `embeddings-http` breaker, and reach the operator as
+                    // "unparseable response" so they never reach for the timeout knob.
+                    if (isTerminalNetworkError(err))
+                        throw err;
+                    throw new RetryableEmbeddingBodyError(unparseableMessage(), { cause: err });
+                }
+                if (!Array.isArray(payload?.data) || !payload.data.every(isEmbeddingItem)) {
+                    throw new RetryableEmbeddingBodyError(unexpectedShapeMessage());
+                }
+                // Cardinality belongs *inside* the retry loop. `every(isEmbeddingItem)`
+                // is vacuously true for `[]` and true for any array shorter than the
+                // request, so a 200 carrying `{"data": []}` — or half the vectors —
+                // used to be classified `success`, call `breaker.recordSuccess()`
+                // (erasing the outage signal), and only then fail terminally after a
+                // single attempt. A short body is a truncated body: same backoff, same
+                // breaker accounting as any other endpoint fault (#2790).
+                if (payload.data.length !== batch.length) {
+                    throw new RetryableEmbeddingBodyError(countMismatchMessage(payload.data.length, batch.length, safeUrl(url), batchIndex));
+                }
+                parsed = payload.data;
+                return attemptResp;
+            },
             breakerKey: HTTP_BREAKER_KEY,
-            retry: { maxAttempts: HTTP_MAX_RETRIES + 1, baseDelayMs: HTTP_RETRY_BACKOFF_MS },
+            retry: {
+                maxAttempts,
+                baseDelayMs: HTTP_RETRY_BACKOFF_MS,
+                capDelayMs: retryCapMs,
+                retryAfterCapMs: retryCapMs,
+                sleep: (ms) => abortableSleep(ms, requestOptions.signal),
+            },
         });
     }
     catch (err) {
+        if (requestOptions.signal?.aborted ||
+            (err instanceof DOMException && err.name === 'AbortError')) {
+            throw new HttpEmbeddingError(`Embedding request cancelled (${safeUrl(url)}, batch ${batchIndex})`, { cause: err });
+        }
+        // Retries are exhausted on a bad 2xx body. Surface the message the sentinel
+        // carried, keeping the underlying parse error in `cause` only — the body
+        // text must never reach the `sanitizeReason` fallback and leak to stderr.
+        if (err instanceof RetryableEmbeddingBodyError) {
+            throw new HttpEmbeddingError(err.terminalMessage, { cause: err.cause });
+        }
         if (err instanceof CircuitOpenError) {
             throw new HttpEmbeddingError(`Embedding endpoint circuit open (${safeUrl(url)}, batch ${batchIndex}): retry in ${Math.ceil(err.retryAfterMs / 1000)}s`, { cause: err });
         }
         if (err instanceof DOMException && err.name === 'TimeoutError') {
-            throw new HttpEmbeddingError(`Embedding request timed out after ${HTTP_TIMEOUT_MS}ms (${safeUrl(url)}, batch ${batchIndex})`, { cause: err });
+            throw new HttpEmbeddingError(`Embedding request timed out after ${timeoutMs}ms (${safeUrl(url)}, batch ${batchIndex})`, { cause: err });
         }
         if (err instanceof ResilientFetchExhaustedError) {
             throw new HttpEmbeddingError(`Embedding endpoint returned ${err.response.status} (${safeUrl(url)}, batch ${batchIndex})`, { cause: err });
         }
-        const reason = sanitizeReason(err instanceof Error ? err.message : String(err), url);
-        throw new HttpEmbeddingError(`Embedding request failed (${safeUrl(url)}, batch ${batchIndex}): ${reason}`, { cause: err });
+        const reason = sanitizeReason(err instanceof Error ? err.message : String(err), url, apiKey);
+        const safeCause = new Error(reason);
+        safeCause.name = err instanceof Error ? err.name : 'EmbeddingTransportError';
+        throw new HttpEmbeddingError(`Embedding request failed (${safeUrl(url)}, batch ${batchIndex}): ${reason}`, { cause: safeCause });
     }
     if (!resp.ok) {
         // resilientFetch already retried 5xx/429; any non-OK response here is
         // a terminal client error (4xx other than 429).
         throw new HttpEmbeddingError(`Embedding endpoint returned ${resp.status} (${safeUrl(url)}, batch ${batchIndex})`);
     }
-    // A reachable-but-wrong endpoint (e.g. a captive portal or a non-embeddings
-    // service) can answer 200 with an HTML/truncated body. Parse inside the
-    // typed-error boundary so that lands as an endpoint failure the CLI can
-    // classify, not a raw SyntaxError/TypeError on the generic stack-dump path.
-    let data;
-    try {
-        data = (await resp.json());
-    }
-    catch (err) {
-        throw new HttpEmbeddingError(`Embedding endpoint returned an unparseable response (${safeUrl(url)}, batch ${batchIndex})`, { cause: err });
-    }
-    if (!Array.isArray(data?.data) || !data.data.every(isEmbeddingItem)) {
-        throw new HttpEmbeddingError(`Embedding endpoint returned an unexpected response shape (${safeUrl(url)}, batch ${batchIndex})`);
+    if (parsed === undefined) {
+        // Defensively unreachable: an OK response either sets `parsed` or throws
+        // out of `fetchImpl`. Kept so the narrowing holds without a non-null
+        // assertion, and so a future `resilientFetch` change can't return an
+        // unvalidated body silently.
+        throw new HttpEmbeddingError(unparseableMessage());
     }
-    return data.data;
+    return parsed;
 };
 /**
  * Embed texts via the HTTP backend, splitting into batches.
@@ -229,7 +446,7 @@ const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, dimensi
  * @param texts - Array of texts to embed
  * @returns Array of Float32Array embedding vectors
  */
-export const httpEmbed = async (texts) => {
+export const httpEmbed = async (texts, requestOptions = {}) => {
     if (texts.length === 0)
         return [];
     const config = readConfig();
@@ -237,18 +454,33 @@ export const httpEmbed = async (texts) => {
         throw new Error('HTTP embedding not configured');
     const url = `${config.baseUrl}/embeddings`;
     const allVectors = [];
-    for (let i = 0; i < texts.length; i += HTTP_BATCH_SIZE) {
-        const batch = texts.slice(i, i + HTTP_BATCH_SIZE);
-        const batchIndex = Math.floor(i / HTTP_BATCH_SIZE);
-        const items = await httpEmbedBatch(url, batch, config.model, config.apiKey, batchIndex, config.dimensions);
+    for (const [batchIndex, batch] of chunk(texts, HTTP_BATCH_SIZE).entries()) {
+        const items = await httpEmbedBatch(url, batch, config.model, config.apiKey, batchIndex, config.requestDimensions, requestOptions, config.maxAttempts, config.retryCapMs, config.minIntervalMs, config.timeoutMs);
+        // Defensive backstop, deliberately kept: `httpEmbedBatch` now rejects a
+        // short body from *inside* the retry loop (through the same
+        // `countMismatchMessage`), so in practice this branch is unreachable. It
+        // stays so a future change to the in-loop check can't silently hand a short
+        // vector list to the caller — that failure would land as a Kuzu/FLOAT[N]
+        // error far from its cause.
         if (items.length !== batch.length) {
-            throw new HttpEmbeddingError(`Embedding endpoint returned ${items.length} vectors for ${batch.length} texts ` +
-                `(${safeUrl(url)}, batch ${batchIndex})`);
+            throw new HttpEmbeddingError(countMismatchMessage(items.length, batch.length, safeUrl(url), batchIndex));
         }
         for (const item of items) {
             const vec = new Float32Array(item.embedding);
             // Fail fast on dimension mismatch rather than inserting bad vectors
             // into the FLOAT[N] column which would cause a cryptic Kuzu error.
+            //
+            // Unlike the cardinality check this one stays *outside* the retry loop,
+            // deliberately. The expected width is `config.dimensions ?? DEFAULT_DIMS`
+            // (GITNEXUS_EMBEDDING_DIMS), which is NOT the `dimensions` value
+            // `httpEmbedBatch` receives — that is `config.requestDimensions`, which
+            // `GITNEXUS_EMBEDDING_REQUEST_DIMS` can set to a different number or to
+            // `undefined` (`omit`). More importantly a width mismatch is an operator
+            // *configuration* error, not an endpoint fault: retrying it three times
+            // can never change the answer, and routing it through the retry loop
+            // would count a healthy endpoint's responses toward the shared circuit
+            // breaker. The message is an actionable config hint, so it is terminal
+            // on the first attempt by design (#2790).
             const expected = config.dimensions ?? DEFAULT_DIMS;
             if (vec.length !== expected) {
                 const hint = config.dimensions
@@ -269,12 +501,15 @@ export const httpEmbed = async (texts) => {
  * @param text - Query text to embed
  * @returns Embedding vector as number array
  */
-export const httpEmbedQuery = async (text) => {
+export const httpEmbedQuery = async (text, requestOptions = {}) => {
     const config = readConfig();
     if (!config)
         throw new Error('HTTP embedding not configured');
     const url = `${config.baseUrl}/embeddings`;
-    const items = await httpEmbedBatch(url, [text], config.model, config.apiKey, 0, config.dimensions);
+    const items = await httpEmbedBatch(url, [text], config.model, config.apiKey, 0, config.requestDimensions, requestOptions, config.maxAttempts, config.retryCapMs, config.minIntervalMs, config.timeoutMs);
+    // Defensive backstop like the `httpEmbed` one above: an empty `data` array is
+    // now a cardinality mismatch (0 vectors for 1 text) rejected and retried
+    // inside `httpEmbedBatch`, so this branch is unreachable in practice.
     if (!items.length) {
         throw new HttpEmbeddingError(`Embedding endpoint returned empty response (${safeUrl(url)})`);
     }

package/dist/core/embeddings/node-module-compat.d.ts

@@ -3,8 +3,10 @@
  *
  * `module.registerHooks` — the synchronous ESM/CJS resolution-hook API the
  * embedding-stack resolvers rely on — was added in Node 22.15.0 (and 23.5.0 on
- * the 23.x line). The gitnexus engines floor is `>=22.0.0`, which admits Node
- * 22.0–22.14 AND 23.0–23.4, where the export is absent.
+ * the 23.x line). The gitnexus engines floor is `^22.18.0 || >=24.11.0`, so
+ * every supported runtime exposes it — but `engines` is advisory (not
+ * engine-strict), so a below-floor Node (22.0–22.14, or the unsupported
+ * 23.0–23.4 line) can still run, where the export is absent.
  *
  * In this `"type": "module"` package, a *static named* import of a missing
  * builtin export (`import { registerHooks } from 'node:module'`) is a

package/dist/core/embeddings/node-module-compat.js

@@ -3,8 +3,10 @@
  *
  * `module.registerHooks` — the synchronous ESM/CJS resolution-hook API the
  * embedding-stack resolvers rely on — was added in Node 22.15.0 (and 23.5.0 on
- * the 23.x line). The gitnexus engines floor is `>=22.0.0`, which admits Node
- * 22.0–22.14 AND 23.0–23.4, where the export is absent.
+ * the 23.x line). The gitnexus engines floor is `^22.18.0 || >=24.11.0`, so
+ * every supported runtime exposes it — but `engines` is advisory (not
+ * engine-strict), so a below-floor Node (22.0–22.14, or the unsupported
+ * 23.0–23.4 line) can still run, where the export is absent.
  *
  * In this `"type": "module"` package, a *static named* import of a missing
  * builtin export (`import { registerHooks } from 'node:module'`) is a

package/dist/core/embeddings/onnxruntime-common-resolver.js

@@ -52,8 +52,8 @@
  * per-resolution cost is a single string comparison.
  *
  * `module.registerHooks` is marked `@experimental` and requires Node >= 22.15
- * (the gitnexus engines floor is >= 22.0.0). On older runtimes it is absent and
- * this is a graceful no-op: embeddings then resolve onnxruntime-common exactly
+ * (below the gitnexus engines floor of `^22.18.0 || >=24.11.0`). On below-floor
+ * runtimes it is absent and this is a graceful no-op: embeddings then resolve onnxruntime-common exactly
  * as before — fine on hoisted layouts. Any failure during installation is
  * swallowed.
  */
@@ -99,9 +99,9 @@ export const ensureOnnxRuntimeCommonResolvable = () => {
     // initEmbedder() call, and the hook is process-global — once is enough.
     attempted = true;
     try {
-        // Node < 22.15 / < 23.5 (the gitnexus engines floor is >= 22.0.0): no
-        // synchronous hooks API. Degrade gracefully — the import still works on
-        // hoisted layouts.
+        // Node < 22.15 / < 23.5 (below the gitnexus engines floor of
+        // ^22.18.0 || >=24.11.0): no synchronous hooks API. Degrade gracefully —
+        // the import still works on hoisted layouts.
         const registerHooks = getRegisterHooks();
         if (typeof registerHooks !== 'function')
             return;

package/dist/core/embeddings/onnxruntime-node-resolver.js

@@ -36,8 +36,8 @@
  * So CUDA-12 hosts, Windows (DirectML), macOS, and CPU-only hosts are
  * untouched. Idempotent; any failure is swallowed and leaves the default
  * resolution exactly as before. `module.registerHooks` requires Node >= 22.15
- * (the gitnexus engines floor is >= 22.0.0); on older runtimes the redirect is
- * a no-op, but the default copy's CUDA major is still probed so an
+ * (below the gitnexus engines floor of `^22.18.0 || >=24.11.0`); on below-floor
+ * runtimes the redirect is a no-op, but the default copy's CUDA major is still probed so an
  * already-matching host (e.g. CUDA 12 + transformers' CUDA-12 build) keeps
  * auto-selecting the GPU.
  * `npm link` / symlinked local-dev checkouts are a known caveat: `resolveOurOrtNodeDir`/

package/dist/core/embeddings/runtime-install.js

@@ -170,7 +170,7 @@ export const ensureEmbeddingStackResolvable = () => {
         return;
     hookAttempted = true;
     try {
-        // Node < 22.15 / < 23.5 (engines floor is >= 22.0.0): no synchronous hooks
+        // Node < 22.15 / < 23.5 (below the engines floor of ^22.18.0 || >=24.11.0): no synchronous hooks
         // API. Degrade gracefully — normally-installed stacks still resolve; only
         // the runtime-prefix fallback is unavailable. Reachable now that the import
         // is a namespace access (see node-module-compat.ts) rather than a static

package/dist/core/git-staleness.js

@@ -113,7 +113,7 @@ export async function checkCwdMatch(cwd) {
     let bestLen = -1;
     for (const e of entries) {
         const p = norm(e.path);
-        if (cwdNorm === p || cwdNorm.startsWith(p + sep)) {
+        if (cwdNorm === p || cwdNorm.startsWith(p.endsWith(sep) ? p : p + sep)) {
             if (p.length > bestLen) {
                 bestPath = e;
                 bestLen = p.length;

package/dist/core/graph/graph.js

@@ -156,6 +156,9 @@ export const createKnowledgeGraph = () => {
         forEachRelationship(fn) {
             relationshipMap.forEach(fn);
         },
+        forEachRelationshipFields(fn) {
+            relationshipMap.forEach((rel) => fn(rel.sourceId, rel.targetId, rel.type, rel.confidence));
+        },
         getNode: (id) => nodeMap.get(id),
         // O(1) count getters - avoid creating arrays just for length
         get nodeCount() {