agentic-qe 3.9.36 → 3.10.1

package/dist/learning/embedder-endpoint-client.js

@@ -0,0 +1,426 @@
+/**
+ * External Embedder Endpoint Client (ADR-097)
+ *
+ * OpenAI-compatible `/v1/embeddings` client over HTTP and HTTP-over-Unix-socket.
+ * When `EmbeddingConfig.endpoint` is set, AQE skips loading `@huggingface/transformers`
+ * entirely and routes feature-extraction through this client.
+ *
+ * Design choices per ADR-097 (revised after devil's-advocate audit):
+ *   - OpenAI wire format with `encoding_format: 'float'` pinned (interop with TEI /
+ *     vLLM / llama.cpp / Ollama / LocalAI / LM Studio — float pin avoids the
+ *     base64 default some servers ship).
+ *   - HTTP + HTTP-over-Unix (one protocol, two transports — no NDJSON fork).
+ *   - Hard-fail with circuit breaker on errors (no silent hash fallback).
+ *   - L2-renormalize on receive (don't trust server claims).
+ *   - Bearer auth from env only; URL userinfo stripped + warned on construct.
+ *   - Probe + identity fingerprint required before `embed()`; breaker recovery
+ *     invalidates identity so re-probe runs against a fresh endpoint.
+ *   - True TCP connect timeout via socket-level setTimeout (not req.setTimeout).
+ *   - TLS knobs (ca / cert / key / rejectUnauthorized / servername) for self-hosted.
+ */
+import * as http from 'node:http';
+import * as https from 'node:https';
+import { createHash } from 'node:crypto';
+import { URL } from 'node:url';
+import { normalize as l2Normalize } from '../shared/utils/vector-math.js';
+const DEFAULT_OPTIONS = {
+    model: 'Xenova/all-MiniLM-L6-v2',
+    expectedDim: 384,
+    connectTimeoutMs: 5_000,
+    requestTimeoutMs: 30_000,
+    failureThreshold: 3,
+    failureWindowMs: 60_000,
+};
+const CANARY_TEXT = 'AQE embedder endpoint identity canary v1';
+const EMBEDDINGS_PATH = '/v1/embeddings';
+/**
+ * Strip user:password@ from a URL for safe logging.
+ * Returns the original string for non-URL inputs (unix paths).
+ */
+export function redactEndpoint(endpoint) {
+    if (endpoint.startsWith('unix:'))
+        return endpoint;
+    try {
+        const u = new URL(endpoint);
+        if (u.username || u.password) {
+            u.username = '';
+            u.password = '';
+            return u.toString().replace(/\/$/, '');
+        }
+        return endpoint;
+    }
+    catch {
+        return endpoint;
+    }
+}
+export function parseEndpoint(endpoint) {
+    if (endpoint.startsWith('unix:')) {
+        const socketPath = endpoint.slice('unix:'.length);
+        if (!socketPath.startsWith('/')) {
+            throw new Error(`unix endpoint must be an absolute path: ${endpoint}`);
+        }
+        return { transport: 'unix', socketPath, safeUrl: endpoint };
+    }
+    const url = new URL(endpoint);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`unsupported embedder endpoint protocol: ${url.protocol}`);
+    }
+    const hadUserinfo = Boolean(url.username || url.password);
+    if (hadUserinfo) {
+        // Warn loudly — userinfo in the URL bypasses the env-only token convention
+        // and leaks into Node's default error messages.
+        console.warn(`[EmbedderEndpointClient] endpoint URL contained userinfo; stripping. ` +
+            `Use AQE_EMBEDDER_TOKEN env var for credentials.`);
+        url.username = '';
+        url.password = '';
+    }
+    return {
+        transport: url.protocol === 'https:' ? 'https' : 'http',
+        host: url.hostname,
+        port: url.port ? Number(url.port) : url.protocol === 'https:' ? 443 : 80,
+        protocol: url.protocol,
+        safeUrl: url.toString().replace(/\/$/, ''),
+    };
+}
+/**
+ * Circuit breaker state.
+ *
+ * Tracks failure timestamps within `windowMs`. Opens when count reaches `threshold`.
+ * While open, every request fast-fails until the window expires. On recovery
+ * (window elapses), the breaker calls `onRecover` so the client can invalidate
+ * cached endpoint identity — endpoint restarts often coincide with model swaps.
+ */
+class CircuitBreaker {
+    threshold;
+    windowMs;
+    onRecover;
+    failures = [];
+    trippedAt = null;
+    constructor(threshold, windowMs, onRecover = () => { }) {
+        this.threshold = threshold;
+        this.windowMs = windowMs;
+        this.onRecover = onRecover;
+    }
+    recordSuccess() {
+        this.failures = [];
+        this.trippedAt = null;
+    }
+    recordFailure() {
+        const now = Date.now();
+        this.failures = this.failures.filter((t) => now - t < this.windowMs);
+        this.failures.push(now);
+        if (this.failures.length >= this.threshold) {
+            this.trippedAt = now;
+        }
+    }
+    isOpen() {
+        if (this.trippedAt === null)
+            return false;
+        if (Date.now() - this.trippedAt >= this.windowMs) {
+            this.failures = [];
+            this.trippedAt = null;
+            // Endpoint may have restarted with a different model — force re-probe.
+            this.onRecover();
+            return false;
+        }
+        return true;
+    }
+    /** For tests / observability */
+    getState() {
+        return { open: this.isOpen(), failures: this.failures.length, trippedAt: this.trippedAt };
+    }
+}
+/**
+ * OpenAI-compatible embeddings client with keep-alive, circuit breaker, and identity probe.
+ */
+export class EmbedderEndpointClient {
+    parsed;
+    agent;
+    breaker;
+    opts;
+    cachedIdentity = null;
+    /** True while a probe is in flight — prevents the embed() lazy-probe race. */
+    probeInFlight = null;
+    constructor(options) {
+        this.opts = {
+            endpoint: options.endpoint,
+            token: options.token,
+            model: options.model ?? DEFAULT_OPTIONS.model,
+            expectedDim: options.expectedDim ?? DEFAULT_OPTIONS.expectedDim,
+            connectTimeoutMs: options.connectTimeoutMs ?? DEFAULT_OPTIONS.connectTimeoutMs,
+            requestTimeoutMs: options.requestTimeoutMs ?? DEFAULT_OPTIONS.requestTimeoutMs,
+            failureThreshold: options.failureThreshold ?? DEFAULT_OPTIONS.failureThreshold,
+            failureWindowMs: options.failureWindowMs ?? DEFAULT_OPTIONS.failureWindowMs,
+            tlsOptions: options.tlsOptions,
+        };
+        this.parsed = parseEndpoint(options.endpoint);
+        if (this.parsed.transport === 'https') {
+            // rejectUnauthorized defaults to true; explicit knobs allow self-hosted CAs.
+            const tls = options.tlsOptions ?? {};
+            this.agent = new https.Agent({
+                keepAlive: true,
+                ca: tls.ca,
+                cert: tls.cert,
+                key: tls.key,
+                rejectUnauthorized: tls.rejectUnauthorized !== false,
+                servername: tls.servername,
+            });
+        }
+        else {
+            this.agent = new http.Agent({ keepAlive: true });
+        }
+        this.breaker = new CircuitBreaker(this.opts.failureThreshold, this.opts.failureWindowMs, () => {
+            // On breaker recovery, drop identity so the next embed() re-probes.
+            // Endpoint restarts (the common cause of recovery) often change models.
+            this.cachedIdentity = null;
+        });
+    }
+    /** Public, redacted endpoint URL for logs/metrics. */
+    getSafeEndpoint() {
+        return this.parsed.safeUrl;
+    }
+    /**
+     * Embed an array of texts. Returns L2-normalized vectors in input order.
+     *
+     * Gated on `probe()` — if no cached identity exists, probe is run first so the
+     * dim/identity boundary check fires on every cold path. Concurrent embed calls
+     * share a single in-flight probe.
+     *
+     * Throws on error — callers MUST NOT fall back to hash embeddings, which would
+     * poison the HNSW index with non-comparable vectors.
+     */
+    async embed(texts) {
+        if (texts.length === 0)
+            return [];
+        if (this.breaker.isOpen()) {
+            throw new Error(`[EmbedderEndpointClient] circuit breaker open for ${this.parsed.safeUrl} — fast-failing`);
+        }
+        // Identity gate: every embed call must have a verified identity behind it.
+        if (this.cachedIdentity === null) {
+            await this.ensureProbed();
+        }
+        try {
+            const data = await this.postEmbeddings(texts);
+            const vectors = this.decodeAndNormalize(data, texts.length);
+            this.breaker.recordSuccess();
+            return vectors;
+        }
+        catch (err) {
+            this.breaker.recordFailure();
+            throw err;
+        }
+    }
+    /**
+     * Probe the endpoint by embedding a fixed canary. Returns identity fingerprint.
+     * Asserts dim === expectedDim. Throws loud on mismatch.
+     * Public so operators can re-probe on demand; idempotent under concurrency.
+     */
+    async probe() {
+        if (this.probeInFlight)
+            return this.probeInFlight;
+        this.probeInFlight = this.doProbe().finally(() => {
+            this.probeInFlight = null;
+        });
+        return this.probeInFlight;
+    }
+    async ensureProbed() {
+        if (this.cachedIdentity)
+            return this.cachedIdentity;
+        return this.probe();
+    }
+    async doProbe() {
+        // Direct HTTP call (NOT via embed()) so we don't recurse on the identity gate.
+        let vec;
+        try {
+            const data = await this.postEmbeddings([CANARY_TEXT]);
+            const vectors = this.decodeAndNormalize(data, 1);
+            vec = vectors[0];
+            this.breaker.recordSuccess();
+        }
+        catch (err) {
+            this.breaker.recordFailure();
+            throw err;
+        }
+        if (!vec || vec.length !== this.opts.expectedDim) {
+            throw new Error(`[EmbedderEndpointClient] dim mismatch: expected ${this.opts.expectedDim}, got ${vec?.length ?? 0} from ${this.parsed.safeUrl}`);
+        }
+        // Fingerprint = SHA-256 of the canary vector's quantized bytes (16 hex chars).
+        // Quantize to int16 first so trivial fp noise between identical (model, server)
+        // configurations doesn't shift the fingerprint.
+        const buf = Buffer.alloc(vec.length * 2);
+        for (let i = 0; i < vec.length; i++) {
+            const q = Math.max(-32768, Math.min(32767, Math.round(vec[i] * 32767)));
+            buf.writeInt16LE(q, i * 2);
+        }
+        const fingerprint = createHash('sha256').update(buf).digest('hex').slice(0, 16);
+        this.cachedIdentity = {
+            dim: vec.length,
+            fingerprint,
+            endpoint: this.parsed.safeUrl,
+        };
+        return this.cachedIdentity;
+    }
+    getCachedIdentity() {
+        return this.cachedIdentity;
+    }
+    getBreakerState() {
+        return this.breaker.getState();
+    }
+    /**
+     * Close the underlying keep-alive agent. Tests should call this in afterEach.
+     */
+    close() {
+        this.agent.destroy();
+    }
+    decodeAndNormalize(json, expectedCount) {
+        // OpenAI shape: { data: [{ embedding: [...], index: 0 }, ...] }
+        if (!json ||
+            typeof json !== 'object' ||
+            !Array.isArray(json.data)) {
+            throw new Error(`[EmbedderEndpointClient] response missing data array`);
+        }
+        const rawData = json
+            .data;
+        if (rawData.length !== expectedCount) {
+            throw new Error(`[EmbedderEndpointClient] response count mismatch: expected ${expectedCount}, got ${rawData.length}`);
+        }
+        // OpenAI guarantees `index` field but ordering is not guaranteed — sort defensively.
+        // Fall back to array position when index is absent.
+        const indexed = rawData.map((item, i) => ({
+            idx: typeof item.index === 'number' ? item.index : i,
+            embedding: item.embedding,
+        }));
+        indexed.sort((a, b) => a.idx - b.idx);
+        return indexed.map(({ embedding }, i) => {
+            // We pinned encoding_format: 'float' in the request, so a base64 string
+            // back means the server ignored our request. Fail loud rather than guess.
+            if (typeof embedding === 'string') {
+                throw new Error(`[EmbedderEndpointClient] received base64 embedding at position ${i} — ` +
+                    `server ignored encoding_format=float. Configure the server to return float arrays.`);
+            }
+            if (!Array.isArray(embedding)) {
+                throw new Error(`[EmbedderEndpointClient] missing embedding at position ${i}`);
+            }
+            if (embedding.length !== this.opts.expectedDim) {
+                throw new Error(`[EmbedderEndpointClient] dim mismatch at position ${i}: expected ${this.opts.expectedDim}, got ${embedding.length}`);
+            }
+            // Re-normalize regardless of server claim — cheap and correct.
+            return l2Normalize(embedding);
+        });
+    }
+    postEmbeddings(texts) {
+        // Pin encoding_format=float so providers that default to base64 (newer
+        // OpenAI/Azure for dims>100) don't silently return strings we'd have to
+        // guess at. The decoder throws loud on string responses.
+        const body = JSON.stringify({
+            model: this.opts.model,
+            input: texts,
+            encoding_format: 'float',
+        });
+        return this.request(EMBEDDINGS_PATH, body);
+    }
+    request(path, body) {
+        const headers = {
+            'content-type': 'application/json',
+            'content-length': Buffer.byteLength(body),
+            accept: 'application/json',
+        };
+        if (this.opts.token) {
+            headers['authorization'] = `Bearer ${this.opts.token}`;
+        }
+        const baseOptions = {
+            method: 'POST',
+            path,
+            headers,
+            agent: this.agent,
+        };
+        let reqOptions;
+        let requestFn;
+        if (this.parsed.transport === 'unix') {
+            reqOptions = { ...baseOptions, socketPath: this.parsed.socketPath };
+            requestFn = http.request;
+        }
+        else {
+            reqOptions = {
+                ...baseOptions,
+                host: this.parsed.host,
+                port: this.parsed.port,
+                protocol: this.parsed.protocol,
+            };
+            requestFn = this.parsed.transport === 'https' ? https.request : http.request;
+        }
+        const safeUrl = this.parsed.safeUrl;
+        const connectTimeoutMs = this.opts.connectTimeoutMs;
+        const requestTimeoutMs = this.opts.requestTimeoutMs;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const safeResolve = (val) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(val);
+            };
+            const safeReject = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(err);
+            };
+            const req = requestFn(reqOptions, (res) => {
+                const chunks = [];
+                res.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+                res.on('end', () => {
+                    const text = Buffer.concat(chunks).toString('utf-8');
+                    if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
+                        safeReject(new Error(`[EmbedderEndpointClient] HTTP ${res.statusCode} from ${safeUrl}: ${text.slice(0, 200)}`));
+                        return;
+                    }
+                    try {
+                        const parsed = JSON.parse(text);
+                        safeResolve(parsed);
+                    }
+                    catch (err) {
+                        safeReject(new Error(`[EmbedderEndpointClient] invalid JSON from ${safeUrl}: ${err.message}`));
+                    }
+                });
+                res.on('error', (err) => safeReject(err));
+            });
+            // True TCP connect timeout: set on the socket itself, fires before any byte
+            // is exchanged. req.setTimeout is an idle-after-write timeout — wrong tool
+            // for SYN-drop scenarios. Once connected we clear it and let
+            // requestTimeoutMs guard the request/response phase.
+            req.on('socket', (socket) => {
+                // Pre-connect phase: any idle period this long means the SYN handshake
+                // is stuck (DNS, ACL drop, blackhole).
+                socket.setTimeout(connectTimeoutMs);
+                const onConnect = () => {
+                    // Switch to the post-connect (read/write idle) timeout budget.
+                    socket.setTimeout(requestTimeoutMs);
+                };
+                // For brand-new sockets we wait for 'connect'. Pooled (keep-alive)
+                // sockets fire 'connect' synchronously already-connected or not at all —
+                // for those, jump straight to the request timeout.
+                if (socket.connecting) {
+                    socket.once('connect', onConnect);
+                }
+                else {
+                    onConnect();
+                }
+                socket.on('timeout', () => {
+                    // Distinguish phase for the error message.
+                    const phase = socket.connecting ? 'connect' : 'request';
+                    const limit = socket.connecting ? connectTimeoutMs : requestTimeoutMs;
+                    const err = new Error(`[EmbedderEndpointClient] ${phase} timeout after ${limit}ms`);
+                    // Reject FIRST, then destroy. If we destroy first, the 'error' event
+                    // races us and we might lose the timeout-specific message.
+                    safeReject(err);
+                    req.destroy(err);
+                });
+            });
+            req.on('error', (err) => safeReject(err));
+            req.write(body);
+            req.end();
+        });
+    }
+}
+//# sourceMappingURL=embedder-endpoint-client.js.map

package/dist/learning/embedder-identity-store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Persistent store for ADR-097 embedder endpoint identity.
+ *
+ * Identity is written into the unified memory.db `kv_store` table under
+ * namespace `_system`, key `embedder_identity:<safe_endpoint_url>`. This lets
+ * us detect cross-run model drift: if the fingerprint changes between AQE
+ * processes, vectors written before the change may not be comparable to vectors
+ * written after, and the operator should know.
+ *
+ * Conforms to the project's unified-persistence rule (no new .db files).
+ *
+ * Persistence failures are non-fatal — callers wrap us in try/catch and log.
+ * We never throw out of these helpers under expected conditions; failure
+ * reasons are surfaced as thrown errors only for genuine I/O problems.
+ */
+import type { EndpointIdentity } from './embedder-endpoint-client.js';
+/**
+ * Load the last persisted identity for the given endpoint URL.
+ * Returns null when nothing has been stored yet OR when the kv store is unavailable.
+ */
+export declare function loadEmbedderIdentity(endpointUrl: string): EndpointIdentity | null;
+/**
+ * Persist the current identity. Overwrites any prior entry for the same endpoint.
+ */
+export declare function saveEmbedderIdentity(identity: EndpointIdentity): void;
+/**
+ * For tests: close the cached connection so a fresh DB path can be used.
+ */
+export declare function resetEmbedderIdentityStore(): void;
+//# sourceMappingURL=embedder-identity-store.d.ts.map

package/dist/learning/embedder-identity-store.js

@@ -0,0 +1,136 @@
+/**
+ * Persistent store for ADR-097 embedder endpoint identity.
+ *
+ * Identity is written into the unified memory.db `kv_store` table under
+ * namespace `_system`, key `embedder_identity:<safe_endpoint_url>`. This lets
+ * us detect cross-run model drift: if the fingerprint changes between AQE
+ * processes, vectors written before the change may not be comparable to vectors
+ * written after, and the operator should know.
+ *
+ * Conforms to the project's unified-persistence rule (no new .db files).
+ *
+ * Persistence failures are non-fatal — callers wrap us in try/catch and log.
+ * We never throw out of these helpers under expected conditions; failure
+ * reasons are surfaced as thrown errors only for genuine I/O problems.
+ */
+import { join } from 'node:path';
+import { existsSync, mkdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+// `require` is unavailable in pure ESM; createRequire gives us synchronous
+// access to CommonJS modules like better-sqlite3 from the ESM build output.
+const nodeRequire = createRequire(import.meta.url);
+/**
+ * Path to the unified memory.db. Honors AQE_MEMORY_PATH env override (used by
+ * tests and platform installers), otherwise falls back to the project default.
+ */
+function getMemoryDbPath() {
+    const env = process.env.AQE_MEMORY_PATH;
+    if (env && env.length > 0)
+        return env;
+    return join(process.cwd(), '.agentic-qe', 'memory.db');
+}
+const NAMESPACE = '_system';
+const KEY_PREFIX = 'embedder_identity:';
+let cachedDb = null;
+let openFailed = false;
+/**
+ * Lazily open memory.db. We use a dedicated read/write connection (better-sqlite3
+ * supports concurrent connections to the same file under WAL mode, which the
+ * init wizard enables). Failure to open is cached so we don't retry every call.
+ */
+function openDb() {
+    if (cachedDb)
+        return cachedDb;
+    if (openFailed)
+        return null;
+    try {
+        // Dynamic require (via createRequire — `require` is undefined in ESM) so
+        // this module doesn't fail to import when better-sqlite3 is absent in
+        // some test environments. The endpoint feature is optional; identity
+        // persistence is a nice-to-have on top of it.
+        const Database = nodeRequire('better-sqlite3');
+        const path = getMemoryDbPath();
+        const dir = join(path, '..');
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        const db = new Database(path);
+        db.pragma('journal_mode = WAL');
+        db.pragma('busy_timeout = 5000');
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS kv_store (
+        key TEXT NOT NULL,
+        namespace TEXT NOT NULL,
+        value TEXT NOT NULL,
+        expires_at INTEGER,
+        created_at INTEGER DEFAULT (strftime('%s', 'now') * 1000),
+        PRIMARY KEY (namespace, key)
+      );
+      CREATE INDEX IF NOT EXISTS idx_kv_namespace ON kv_store(namespace);
+    `);
+        cachedDb = db;
+        return db;
+    }
+    catch {
+        openFailed = true;
+        return null;
+    }
+}
+/**
+ * Load the last persisted identity for the given endpoint URL.
+ * Returns null when nothing has been stored yet OR when the kv store is unavailable.
+ */
+export function loadEmbedderIdentity(endpointUrl) {
+    const db = openDb();
+    if (!db)
+        return null;
+    try {
+        const row = db
+            .prepare('SELECT value FROM kv_store WHERE namespace = ? AND key = ?')
+            .get(NAMESPACE, KEY_PREFIX + endpointUrl);
+        if (!row)
+            return null;
+        const parsed = JSON.parse(row.value);
+        if (!parsed.fingerprint || typeof parsed.dim !== 'number')
+            return null;
+        return {
+            fingerprint: parsed.fingerprint,
+            dim: parsed.dim,
+            endpoint: parsed.endpoint,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist the current identity. Overwrites any prior entry for the same endpoint.
+ */
+export function saveEmbedderIdentity(identity) {
+    const db = openDb();
+    if (!db)
+        return;
+    const row = {
+        fingerprint: identity.fingerprint,
+        dim: identity.dim,
+        endpoint: identity.endpoint,
+        updatedAt: Date.now(),
+    };
+    db.prepare('INSERT OR REPLACE INTO kv_store (key, namespace, value) VALUES (?, ?, ?)').run(KEY_PREFIX + identity.endpoint, NAMESPACE, JSON.stringify(row));
+}
+/**
+ * For tests: close the cached connection so a fresh DB path can be used.
+ */
+export function resetEmbedderIdentityStore() {
+    if (cachedDb) {
+        try {
+            cachedDb.close();
+        }
+        catch {
+            // ignore
+        }
+    }
+    cachedDb = null;
+    openFailed = false;
+}
+//# sourceMappingURL=embedder-identity-store.js.map

package/dist/learning/qe-reasoning-bank.js

@@ -553,7 +553,7 @@ export class QEReasoningBank {
      * for ARM64 or when transformers module cannot be loaded.
      */
     async embed(text) {
-        // Try ONNX embeddings if enabled
+        // Try ONNX / endpoint embeddings if enabled
         if (this.config.useONNXEmbeddings) {
             try {
                 const { computeRealEmbedding } = await import('./real-embeddings.js');
@@ -565,8 +565,16 @@ export class QEReasoningBank {
                 return embedding;
             }
             catch (error) {
-                // ARM64 ONNX compatibility issue or module not available
-                // Fall through to hash-based embedding silently
+                // ADR-097: if the external embedder endpoint is configured, we MUST NOT
+                // silently fall back to hash embeddings — they would poison the HNSW
+                // index by mixing non-comparable vectors. Propagate the throw so the
+                // caller can decide (retry, skip the write, etc).
+                const { isUsingEndpoint } = await import('./real-embeddings.js');
+                if (isUsingEndpoint()) {
+                    throw error;
+                }
+                // In-process ARM64 ONNX compatibility issue or module not available —
+                // fall through to hash-based embedding (existing pre-ADR-097 behavior).
                 if (process.env.DEBUG) {
                     logger.warn('ONNX embeddings unavailable, using hash fallback', {
                         error: toErrorMessage(error),

package/dist/learning/real-embeddings.d.ts

@@ -6,6 +6,7 @@
  * Model: all-MiniLM-L6-v2 (384-dimensional sentence embeddings)
  */
 export { cosineSimilarity } from '../shared/utils/vector-math.js';
+import { type EndpointIdentity } from './embedder-endpoint-client.js';
 /**
  * Embedding model configuration
  */
@@ -18,6 +19,24 @@ export interface EmbeddingConfig {
     enableCache: boolean;
     /** Maximum cache size */
     maxCacheSize: number;
+    /**
+     * Optional external embedder endpoint (ADR-097).
+     *
+     * When set, AQE routes feature-extraction to an OpenAI-compatible
+     * `/v1/embeddings` service instead of loading `@huggingface/transformers`
+     * in-process. Forms:
+     *   - `http(s)://host:port`  — HTTP transport
+     *   - `unix:/absolute/path`  — HTTP-over-Unix-socket transport
+     *
+     * Defaults to `process.env.AQE_EMBEDDER_ENDPOINT` when unset.
+     * When neither is set, behavior is identical to pre-ADR-097.
+     */
+    endpoint?: string;
+    /**
+     * Bearer token for the embedder endpoint (ADR-097).
+     * Defaults to `process.env.AQE_EMBEDDER_TOKEN`. Env-only — never in config files.
+     */
+    endpointToken?: string;
 }
 export declare const DEFAULT_EMBEDDING_CONFIG: EmbeddingConfig;
 /**
@@ -55,4 +74,13 @@ export declare function getEmbeddingDimension(): number;
  * Reset initialization state (for testing)
  */
 export declare function resetInitialization(): void;
+/**
+ * ADR-097: Returns true when the embedding pipeline is the external endpoint path,
+ * false when it's the in-process transformer (or uninitialized).
+ */
+export declare function isUsingEndpoint(): boolean;
+/**
+ * ADR-097: Returns the endpoint identity fingerprint, or null when not using an endpoint.
+ */
+export declare function getEndpointIdentity(): EndpointIdentity | null;
 //# sourceMappingURL=real-embeddings.d.ts.map