@adhd/sox-embedding-provider 0.5.0 → 0.5.2

package/dist/funnelClient.js

@@ -0,0 +1,311 @@
+/**
+ * funnelClient.ts — the host-aware `SharedFastembedClient` (SPEC-EMBEDDING-FUNNEL.md §D).
+ *
+ * A drop-in `SharedFastembedClient` that transparently dials — and, when absent,
+ * peer-spawns — the ONE machine-wide embedding host for `(model, ep, cacheDir)`.
+ * It is the consumer half of the funnel: N processes each hold a
+ * `FunneledFastembedClient`, but `ensureBackend()`'s O_EXCL spawn-lock collapses
+ * their concurrent spawn attempts to a single detached host, and the host
+ * reaps itself once the last client leaves (see `embedHostMain.ts`).
+ *
+ * ── Honest failure, never a silent private re-fork ─────────────────────────────
+ *
+ * Under the default `host: 'shared'`, a failure to bring the host up throws a
+ * typed `TransientEmbeddingError` naming the socket — it does NOT fall back to
+ * forking a private host. A silent fallback would defeat the entire funnel
+ * (each of 535 short-lived CLIs/day would quietly become its own ONNX host) and
+ * is exactly the behaviour this design removes. `host: 'private'` is the
+ * explicit, typed CI/diagnostics selection (ADR-0013 closed union).
+ *
+ * ── Circuit breaker ────────────────────────────────────────────────────────────
+ *
+ * After `ENSURE_FAILURE_THRESHOLD` consecutive failed ensures, the client fails
+ * fast with a typed error for `ENSURE_CIRCUIT_COOLDOWN_MS` rather than paying
+ * the full `ensureBackend` ready-timeout on every call. The breaker is
+ * per-process (a short-lived CLI cannot share it) — it bounds a retrying
+ * consumer, not the fleet; that is stated here rather than implied.
+ *
+ * Leaf module — `@adhd/sox-service-proxy` + node builtins.
+ */
+import { dialBackend, ensureBackend, probeSocketLive } from '@adhd/sox-service-proxy';
+import { TransientEmbeddingError, PermanentEmbeddingError } from './errors.js';
+import { embedHostSingletonKey, embedHostSocketPath, resolveEmbedHostConfig, resolveEmbedHostMainPath, resolveEmbedHostStderrLogPath, } from './embedHostConfig.js';
+/** Consecutive failed ensures before the breaker opens. */
+export const ENSURE_FAILURE_THRESHOLD = 3;
+/** How long the breaker stays open (fail-fast window) once tripped. */
+export const ENSURE_CIRCUIT_COOLDOWN_MS = 10_000;
+/** Bound on bringing the host up (`ensureBackend`'s readyTimeoutMs). */
+export const HOST_READY_TIMEOUT_MS = 10_000;
+/** Per-probe connect timeout. */
+const PROBE_TIMEOUT_MS = 250;
+/** Bound on a control call (reset/health) — never hang the caller. */
+const CONTROL_TIMEOUT_MS = 5_000;
+/**
+ * The last-constructed funnel client. `resetSharedFastembedHost()` targets it.
+ * Production constructs exactly one (via `getSharedFastembedProcess()`); tests
+ * that construct extras simply re-point it, which is why the reset helper is
+ * explicitly documented as operating on the current accessor client.
+ */
+let _activeClient = null;
+/** TEST-ONLY: clear the active-client reference. */
+export function __resetActiveFunnelClientForTests() {
+    _activeClient = null;
+}
+/** Extract a host/model/error message safely. */
+function msg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export class FunneledFastembedClient {
+    conn = null;
+    socketPath = null;
+    initContext = null;
+    ensurePromise = null;
+    _started = false;
+    _pending = 0;
+    nextId = 1;
+    consecutiveEnsureFailures = 0;
+    circuitOpenUntil = 0;
+    constructor() {
+        _activeClient = this;
+    }
+    /** True once the host has been resolved and the dial connection established. */
+    get started() {
+        return this._started;
+    }
+    /** In-flight request count on THIS consumer (not the host's). */
+    get pendingCount() {
+        return this._pending;
+    }
+    /** The resolved host socket path, or `null` before the first successful ensure. */
+    get hostSocketPath() {
+        return this.socketPath;
+    }
+    async request(payload, timeoutMs, signal) {
+        const type = typeof payload['type'] === 'string' ? payload['type'] : '';
+        if (type === 'init') {
+            // The host's identity is keyed on (model, ep, cacheDir), all carried by
+            // the init payload. Record it so `ensureHost()` can compute the key; a
+            // non-init first request is a programming error, reported honestly below.
+            if (!this.initContext) {
+                this.initContext = {
+                    model: String(payload['model'] ?? ''),
+                    cacheDir: String(payload['cacheDir'] ?? ''),
+                };
+            }
+        }
+        await this.ensureHost();
+        const conn = this.conn;
+        if (!conn) {
+            // ensureHost() guarantees a connection or throws; this is unreachable but
+            // keeps the type honest rather than asserting.
+            throw new TransientEmbeddingError(`embedding funnel: no connection to host at ${this.socketPath ?? '(unresolved)'}`);
+        }
+        const id = `embed-funnel-${this.nextId++}`;
+        const request = { jsonrpc: '2.0', id, method: `embedding.${type}`, params: payload };
+        this._pending++;
+        try {
+            const resp = await this.awaitResponse(conn.send(request), id, timeoutMs, signal);
+            const error = resp.error;
+            if (error)
+                throw this.mapError(error);
+            return resp.result;
+        }
+        finally {
+            this._pending--;
+        }
+    }
+    /**
+     * NO-OP by design: under `host: 'shared'` the host is shared with every other
+     * consumer on the machine — a consumer must never kill it. Its lifetime is
+     * governed solely by its own debounced, ref-counted teardown
+     * (`embedHostMain.ts`). Kept to satisfy `SharedFastembedClient`.
+     */
+    async terminate() {
+        // Intentionally empty — see the method doc.
+    }
+    // ── internals ───────────────────────────────────────────────────────────────
+    mapError(error) {
+        const where = this.socketPath ?? '(unresolved socket)';
+        if (error.code === -32001) {
+            return new TransientEmbeddingError(`embedding host unavailable at ${where}: ${error.message}`, 1_000);
+        }
+        if (error.code === -32601) {
+            return new PermanentEmbeddingError(`embedding host does not implement the method: ${error.message}`);
+        }
+        // Application error from the private ONNX host (e.g. "Model not
+        // initialized") — preserve the pre-funnel `new Error(message)` shape so
+        // `FastembedProvider.initModel()`'s catch/retry logic is unchanged.
+        return new Error(error.message);
+    }
+    awaitResponse(pending, id, timeoutMs, signal) {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timer = null;
+            const onAbort = () => {
+                if (settled)
+                    return;
+                settle();
+                reject(signal?.reason instanceof Error
+                    ? signal.reason
+                    : new TransientEmbeddingError(`embedding funnel request ${id} aborted`));
+            };
+            const settle = () => {
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                if (signal)
+                    signal.removeEventListener('abort', onAbort);
+            };
+            if (timeoutMs !== undefined && timeoutMs > 0) {
+                timer = setTimeout(() => {
+                    if (settled)
+                        return;
+                    settle();
+                    reject(new TransientEmbeddingError(`embedding funnel request timed out after ${timeoutMs}ms`, timeoutMs));
+                }, timeoutMs);
+            }
+            if (signal) {
+                if (signal.aborted) {
+                    onAbort();
+                    return;
+                }
+                signal.addEventListener('abort', onAbort, { once: true });
+            }
+            pending.then((resp) => {
+                if (settled)
+                    return;
+                settle();
+                resolve(resp);
+            }, (err) => {
+                if (settled)
+                    return;
+                settle();
+                reject(new TransientEmbeddingError(`embedding funnel transport error: ${msg(err)}`, 1_000));
+            });
+        });
+    }
+    /** Idempotent: resolves once a host is live and dialed, or throws typed. */
+    ensureHost() {
+        if (this._started && this.conn?.isConnected())
+            return Promise.resolve();
+        if (this.ensurePromise)
+            return this.ensurePromise;
+        this.ensurePromise = this.doEnsure().finally(() => {
+            this.ensurePromise = null;
+        });
+        return this.ensurePromise;
+    }
+    async doEnsure() {
+        if (Date.now() < this.circuitOpenUntil) {
+            throw new TransientEmbeddingError(`embedding funnel circuit open for ${this.circuitOpenUntil - Date.now()}ms more after ` +
+                `${this.consecutiveEnsureFailures} consecutive ensure failures`, this.circuitOpenUntil - Date.now());
+        }
+        const cfg = resolveEmbedHostConfig();
+        const ctx = this.initContext;
+        if (!ctx) {
+            throw new TransientEmbeddingError('embedding funnel requires an {type:"init"} request before any other request ' +
+                '(the host is keyed on model + cacheDir, which only init carries)');
+        }
+        const ep = process.env['SOX_EMBED_EXECUTION_PROVIDER'] ?? 'auto';
+        const key = embedHostSingletonKey(ctx.model, ep, ctx.cacheDir);
+        const socketPath = embedHostSocketPath(cfg, key);
+        if (this.socketPath !== socketPath) {
+            // The identity changed (a different model/ep/cacheDir). Drop the old dial
+            // and re-point. The old host is NOT killed — it self-reaps.
+            this.conn?.close();
+            this.conn = null;
+            this._started = false;
+            this.socketPath = socketPath;
+        }
+        const live = await probeSocketLive(socketPath, PROBE_TIMEOUT_MS);
+        if (!live) {
+            const result = await ensureBackend({
+                socketPath,
+                singletonKey: key,
+                command: process.execPath,
+                args: [resolveEmbedHostMainPath()],
+                env: { ...process.env, SOX_EMBED_HOST_SOCKET: socketPath, SOX_EMBED_HOST_KEY: key },
+                stderrLogPath: resolveEmbedHostStderrLogPath(cfg),
+                readyTimeoutMs: HOST_READY_TIMEOUT_MS,
+            });
+            if (result.disposition === 'failed') {
+                this.noteEnsureFailure();
+                throw new TransientEmbeddingError(`embedding funnel could not bring up a host at ${socketPath}: ${result.detail}`, 1_000);
+            }
+        }
+        this.consecutiveEnsureFailures = 0;
+        if (!this.conn) {
+            this.conn = dialBackend({
+                socketPath,
+                onDisconnect: () => {
+                    // The host may have self-reaped (idle) or crashed. The next request's
+                    // `send()` re-dials and, on failure, re-ensures. Mark unstarted so
+                    // `ensureHost()` runs the full probe/spawn path again.
+                    this._started = false;
+                },
+            });
+        }
+        this._started = true;
+    }
+    noteEnsureFailure() {
+        this.consecutiveEnsureFailures++;
+        if (this.consecutiveEnsureFailures >= ENSURE_FAILURE_THRESHOLD) {
+            this.circuitOpenUntil = Date.now() + ENSURE_CIRCUIT_COOLDOWN_MS;
+        }
+    }
+    /**
+     * Ask the live host to tear down and re-fork its PRIVATE pool, then drop this
+     * consumer's connection so the next request re-dials the (still-live) host.
+     * No-op when no host has been resolved. Public so the module-level
+     * `resetSharedFastembedHost()` can target the accessor client.
+     */
+    async resetHost() {
+        if (!this.socketPath)
+            return;
+        try {
+            await this.control('embedding.reset');
+        }
+        catch {
+            // Best-effort: an unreachable host has either reaped (fine) or is wedged;
+            // dropping the connection lets the next request re-ensure.
+        }
+        finally {
+            this.dropConnection();
+        }
+    }
+    /**
+     * Send a control method (`embedding.reset` / `embedding.health`) to the live
+     * host, bounded. Returns the result, or `null` when no host is resolved.
+     */
+    async control(method) {
+        if (!this.conn || !this.socketPath)
+            return null;
+        const id = `embed-funnel-ctl-${this.nextId++}`;
+        const resp = await this.awaitResponse(this.conn.send({ jsonrpc: '2.0', id, method }), id, CONTROL_TIMEOUT_MS, undefined);
+        const error = resp.error;
+        if (error)
+            throw this.mapError(error);
+        return (resp.result ?? {});
+    }
+    /**
+     * Drop this consumer's dial connection. The host stays alive.
+     */
+    dropConnection() {
+        this.conn?.close();
+        this.conn = null;
+        this._started = false;
+    }
+}
+/**
+ * Ask the peer-shared host to tear down and re-fork its PRIVATE pool, then drop
+ * this consumer's connection so the next request re-dials the (still-live) host.
+ *
+ * This is memory-core's heal entry point: under `host: 'shared'`,
+ * `terminate()` is a no-op (a consumer must never kill a shared host), so a
+ * wedged private child is recovered by asking the host to reset its own pool.
+ * A no-op when no host has been resolved yet — nothing to reset.
+ */
+export async function resetSharedFastembedHost() {
+    await _activeClient?.resetHost();
+}
+//# sourceMappingURL=funnelClient.js.map

package/dist/funnelClient.js.map

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

package/dist/index.d.ts

@@ -14,6 +14,13 @@ export interface EmbeddingHealth {
     dimensions: number | null;
     last_error: string | null;
     execution_provider?: string;
+    /**
+     * The resolved host-selection posture (SPEC-EMBEDDING-FUNNEL.md): `'shared'`
+     * funnels through the peer-spawned host, `'private'` is the pre-funnel
+     * per-process fork. Reported so an operator can see the active mode from one
+     * call (ADR-0013 D2) — never inferred, never a placeholder.
+     */
+    host?: 'shared' | 'private';
 }
 export interface EmbeddingProvider {
     readonly metadata: EmbeddingProviderMetadata;
@@ -30,17 +37,15 @@ export interface EmbeddingProviderConfig {
     type: string;
     model: string;
     options?: Record<string, unknown>;
+    /**
+     * Host-selection posture (SPEC-EMBEDDING-FUNNEL.md; ADR-0013). Defaults to
+     * `'shared'` — funnel through the one peer-spawned, self-reaping host.
+     * `'private'` is the explicit pre-funnel per-process fork (CI/diagnostics);
+     * it is a closed union, never an env toggle, and is reported in `health()`.
+     */
+    host?: 'shared' | 'private';
 }
-export declare class TransientEmbeddingError extends Error {
-    readonly retryAfterMs: number | undefined;
-    constructor(message: string, retryAfterMs?: number);
-}
-export declare class PermanentEmbeddingError extends Error {
-    constructor(message: string);
-}
-export declare class ResolutionError extends Error {
-    constructor(message: string);
-}
+export { TransientEmbeddingError, PermanentEmbeddingError, ResolutionError } from './errors.js';
 /**
  * Static registration for a fastembed ONNX model.
  * Each model has a known HF repo, dimension, context window, and description.
@@ -145,8 +150,18 @@ export { getSharedFastembedProcess, SharedFastembedProcessClient, resetSharedFas
  * `resolveFastembedPoolSize` (kept for backward compatibility) used to
  * compute as one value — see their doc comments for why the split exists.
  */
-export type { SharedFastembedClient } from './sharedFastembedProcess.js';
-export { FastembedProcessPool, AdaptiveFastembedProcessPool, type AdaptiveFastembedPoolOptions, FastembedBusyError, resolveFastembedPoolSize, resolveFastembedPoolPin, resolveFastembedPoolCeiling, resolveFastembedAdmissionLimit, } from './sharedFastembedProcess.js';
+export type { SharedFastembedClient, PrivateFastembedProcess } from './sharedFastembedProcess.js';
+export { getPrivateFastembedProcess, FastembedProcessPool, AdaptiveFastembedProcessPool, type AdaptiveFastembedPoolOptions, FastembedBusyError, resolveFastembedPoolSize, resolveFastembedPoolPin, resolveFastembedPoolCeiling, resolveFastembedAdmissionLimit, } from './sharedFastembedProcess.js';
+/**
+ * The host-aware client and its heal entry point. `FunneledFastembedClient` is
+ * what `getSharedFastembedProcess()` returns by default (`host: 'shared'`):
+ * N processes share ONE peer-spawned, self-reaping ONNX host, and a consumer's
+ * `terminate()` is a no-op (it must never kill a shared host).
+ * `resetSharedFastembedHost()` is the heal path — it asks the live host to
+ * re-fork its private pool (memory-core's `reinitEmbedProvider` routes here).
+ */
+export { FunneledFastembedClient, resetSharedFastembedHost } from './funnelClient.js';
+export { resolveEmbedHostConfig, configureEmbedHostHost, resolveEmbedHostSocketDir, embedHostSingletonKey, embedHostSocketPath, resolveEmbedHostMainPath, resolveEmbedHostIdleGraceMs, EMBED_HOST_PROTOCOL_VERSION, type EmbedHostConfig, type EmbedHostMode, } from './embedHostConfig.js';
 export declare function createEmbeddingProvider(config: EmbeddingProviderConfig): Promise<EmbeddingProvider>;
 /**
  * Single source of truth for the fastembed warmup/init timeout budget.

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -3,27 +3,15 @@
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+// Local binding so this module's own throws/type-guards use the SAME classes the
+// barrel re-exports (one home — see `errors.ts`).
+import { ResolutionError } from './errors.js';
+import { configureEmbedHostHost } from './embedHostConfig.js';
 // ── Error taxonomy — three tiers, no silent degradation ──────────────────────
-export class TransientEmbeddingError extends Error {
-    retryAfterMs;
-    constructor(message, retryAfterMs) {
-        super(message);
-        this.name = 'TransientEmbeddingError';
-        this.retryAfterMs = retryAfterMs;
-    }
-}
-export class PermanentEmbeddingError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'PermanentEmbeddingError';
-    }
-}
-export class ResolutionError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'ResolutionError';
-    }
-}
+// Defined in `errors.ts` so `funnelClient.ts` can throw them without importing
+// this barrel (which re-exports the funnel client) — re-exported here so the
+// public surface and `instanceof` identity are unchanged.
+export { TransientEmbeddingError, PermanentEmbeddingError, ResolutionError } from './errors.js';
 // ── Re-exports ────────────────────────────────────────────────────────────────
 /**
  * @deprecated SOX-BUG-002: dead API, not used by `createEmbeddingProvider` or
@@ -52,12 +40,34 @@ export { getSharedOnnxWorker, SharedOnnxWorkerClient, resetSharedOnnxWorker } fr
  * root-cause writeup and rationale.
  */
 export { getSharedFastembedProcess, SharedFastembedProcessClient, resetSharedFastembedProcess, } from './sharedFastembedProcess.js';
-export { FastembedProcessPool, AdaptiveFastembedProcessPool, FastembedBusyError, resolveFastembedPoolSize, resolveFastembedPoolPin, resolveFastembedPoolCeiling, resolveFastembedAdmissionLimit, } from './sharedFastembedProcess.js';
+export { getPrivateFastembedProcess, FastembedProcessPool, AdaptiveFastembedProcessPool, FastembedBusyError, resolveFastembedPoolSize, resolveFastembedPoolPin, resolveFastembedPoolCeiling, resolveFastembedAdmissionLimit, } from './sharedFastembedProcess.js';
+// ── The embedding funnel (SPEC-EMBEDDING-FUNNEL.md) ────────────────────────────
+/**
+ * The host-aware client and its heal entry point. `FunneledFastembedClient` is
+ * what `getSharedFastembedProcess()` returns by default (`host: 'shared'`):
+ * N processes share ONE peer-spawned, self-reaping ONNX host, and a consumer's
+ * `terminate()` is a no-op (it must never kill a shared host).
+ * `resetSharedFastembedHost()` is the heal path — it asks the live host to
+ * re-fork its private pool (memory-core's `reinitEmbedProvider` routes here).
+ */
+export { FunneledFastembedClient, resetSharedFastembedHost } from './funnelClient.js';
+export { resolveEmbedHostConfig, configureEmbedHostHost, resolveEmbedHostSocketDir, embedHostSingletonKey, embedHostSocketPath, resolveEmbedHostMainPath, resolveEmbedHostIdleGraceMs, EMBED_HOST_PROTOCOL_VERSION, } from './embedHostConfig.js';
 // ── Factory ───────────────────────────────────────────────────────────────────
 export async function createEmbeddingProvider(config) {
     if (!config.type || typeof config.type !== 'string') {
         throw new ResolutionError(`Invalid provider type: ${String(config.type)}`);
     }
+    // SPEC-EMBEDDING-FUNNEL.md / ADR-0013: apply the typed host-selection posture
+    // BEFORE the accessor singleton is first constructed. Process-wide (the host
+    // is shared by every provider in the process); reported in `health()`.
+    if (config.host !== undefined) {
+        try {
+            configureEmbedHostHost(config.host);
+        }
+        catch (err) {
+            throw new ResolutionError(`Invalid embedding host mode: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     switch (config.type) {
         case 'fastembed':
             return createFastembedProvider(config);
@@ -79,9 +89,19 @@ async function createFastembedProvider(config) {
         process.env['SOX_EMBED_CACHE_DIR'] ??
         joinDefaultCacheDir();
     try {
+        // SPEC-EMBEDDING-FUNNEL.md §E: NO eager warmup. Construction is deliberately
+        // INERT — it resolves the model's static metadata but does NOT load the ONNX
+        // model, and therefore does NOT spawn the shared embedding host. A host that
+        // constructs a provider but never embeds (e.g. `backlog query` on a read-only
+        // view) spawns zero hosts. The model loads — and the host spawns — on the
+        // first real `embedSingle`/`embedBatch`, via `FastembedProvider.ensureReady()`.
+        //
+        // Contract note (was: "throws ResolutionError at factory time if the model
+        // cannot load"): CONFIG errors (unknown model/type) still fail here at
+        // factory time. A MODEL-LOAD failure now surfaces on first use — still a
+        // loud, typed throw, never a silent downgrade — which is the cost of not
+        // paying a model load (and a host spawn) for a verb that never embeds.
         const provider = new FastembedProvider(modelId, cfg.dim, cacheDir);
-        const cacheHit = isModelCached(cacheDir, cfg.hfRepoId);
-        await withTimeout(provider.embedSingle('warmup'), warmupOuterBudgetMs(cacheHit), 'fastembed warmup');
         return provider;
     }
     catch (err) {
@@ -178,22 +198,6 @@ export function warmupOuterBudgetMs(cacheHit) {
 export function isModelCached(cacheDir, hfRepoId) {
     return existsSync(join(cacheDir, hfRepoId, 'model_optimized.onnx'));
 }
-function withTimeout(p, ms, label) {
-    return new Promise((resolve, reject) => {
-        const to = setTimeout(() => {
-            reject(new Error(`${label} timed out after ${ms}ms`));
-        }, ms);
-        if (typeof to.unref === 'function')
-            to.unref();
-        p.then((v) => {
-            clearTimeout(to);
-            resolve(v);
-        }, (e) => {
-            clearTimeout(to);
-            reject(e instanceof Error ? e : new Error(String(e)));
-        });
-    });
-}
 function joinDefaultCacheDir() {
     const xdg = process.env['XDG_CACHE_HOME'];
     return join(xdg ?? join(homedir(), '.cache'), 'sox', 'models');

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,iFAAiF;AAEjF,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA0CjC,gFAAgF;AAEhF,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACvC,YAAY,CAAqB;IAC1C,YAAY,OAAe,EAAE,YAAqB;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAmED,iFAAiF;AAEjF;;;;;GAKG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;GAOG;AACH,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAE3G;;;;;;;;;GASG;AACH,OAAO,EACL,yBAAyB,EACzB,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,6BAA6B,CAAC;AAkBrC,OAAO,EACL,oBAAoB,EACpB,4BAA4B,EAE5B,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,6BAA6B,CAAC;AAErC,iFAAiF;AAEjF,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,MAA+B;IAE/B,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACpD,MAAM,IAAI,eAAe,CAAC,0BAA0B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7E,CAAC;IAED,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,WAAW;YACd,OAAO,uBAAuB,CAAC,MAAM,CAAC,CAAC;QACzC,KAAK,QAAQ;YACX,OAAO,oBAAoB,CAAC,MAAM,CAAC,CAAC;QACtC;YACE,MAAM,IAAI,eAAe,CACvB,qCAAqC,MAAM,CAAC,IAAI,sCAAsC,CACvF,CAAC;IACN,CAAC;AACH,CAAC;AAED,iFAAiF;AAEjF,KAAK,UAAU,uBAAuB,CACpC,MAA+B;IAE/B,MAAM,EAAE,iBAAiB,EAAE,aAAa,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAC3F,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,IAAI,aAAa,CAAC;IAC9C,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IAEnC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,eAAe,CACvB,6BAA6B,OAAO,iBAAiB,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC7F,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GACX,MAAM,CAAC,OAAO,EAAE,CAAC,UAAU,CAAY;QACxC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;QAClC,mBAAmB,EAAE,CAAC;IAExB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,IAAI,iBAAiB,CAAC,OAAO,EAAE,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACnE,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;QACvD,MAAM,WAAW,CACf,QAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,EAC9B,mBAAmB,CAAC,QAAQ,CAAC,EAC7B,kBAAkB,CACnB,CAAC;QACF,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,eAAe;YAAE,MAAM,GAAG,CAAC;QAC9C,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,IAAI,eAAe,CACvB,uBAAuB,OAAO,2BAA2B,OAAO,EAAE,CACnE,CAAC;IACJ,CAAC;AACH,CAAC;AAED,KAAK,UAAU,oBAAoB,CACjC,MAA+B;IAE/B,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,IAAI,YAAY,CAAC;IAC7C,MAAM,UAAU,GAAI,MAAM,CAAC,OAAO,EAAE,CAAC,YAAY,CAAY,IAAI,GAAG,CAAC;IACrE,MAAM,QAAQ,GAAI,MAAM,CAAC,OAAO,EAAE,CAAC,UAAU,CAAY,IAAI,EAAE,CAAC;IAChE,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAuB,CAAC;IAEhE,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,eAAe,CACvB,qEAAqE,CACtE,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AACnE,CAAC;AAED,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,eAAe,CAAC,QAAiB;IAC/C,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC,CAAC;QACtE,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;IACvD,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC,CAAC;IAC/D,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAiB;IACnD,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,OAAO,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,QAAgB;IAC9D,OAAO,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,sBAAsB,CAAC,CAAC,CAAC;AACtE,CAAC;AAED,SAAS,WAAW,CAAI,CAAa,EAAE,EAAU,EAAE,KAAa;IAC9D,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxC,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE;YACzB,MAAM,CAAC,IAAI,KAAK,CAAC,GAAG,KAAK,oBAAoB,EAAE,IAAI,CAAC,CAAC,CAAC;QACxD,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,IAAI,OAAO,EAAE,CAAC,KAAK,KAAK,UAAU;YAAE,EAAE,CAAC,KAAK,EAAE,CAAC;QAC/C,CAAC,CAAC,IAAI,CACJ,CAAC,CAAC,EAAE,EAAE;YACJ,YAAY,CAAC,EAAE,CAAC,CAAC;YACjB,OAAO,CAAC,CAAC,CAAC,CAAC;QACb,CAAC,EACD,CAAC,CAAC,EAAE,EAAE;YACJ,YAAY,CAAC,EAAE,CAAC,CAAC;YACjB,MAAM,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxD,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,mBAAmB;IAC1B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC1C,OAAO,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;AACjE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/onnxStderrFilter.d.ts

@@ -0,0 +1,79 @@
+/**
+ * (BUG-EMBED-ONNX-COREML-STDERR-NOISE-001) Filters the ONNX Runtime CoreML
+ * graph-partitioning warning out of the fastembed child's inherited stderr,
+ * while forwarding every other byte through verbatim, unbuffered, and in
+ * order.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────
+ *
+ * `sharedFastembedProcess.ts` forks `fastembedProcessHost.ts` with
+ * `resolveExecutionProviders()` returning `['coreml', 'cpu']` on darwin
+ * (`fastembedProcessHost.ts`). bge-base's `word_embeddings` tensor is shaped
+ * `{30522,768}`, and CoreML's execution provider cannot host any input
+ * dimension over 16384 — so onnxruntime's native CoreML EP logs, at EVERY
+ * model load:
+ *
+ *   [W:onnxruntime:, helper.cc:83 IsInputSupported] CoreML does not support
+ *   input dim > 16384. Input:embeddings.word_embeddings.weight,
+ *   shape: {30522,768}
+ *
+ * This is emitted by the native onnxruntime addon straight to the process's
+ * real stderr fd (not through any JS logger this package controls), and
+ * `sharedFastembedProcess.ts` forks the child with
+ * `stdio: ['ignore', 'inherit', 'inherit', 'ipc']` — so it lands on every
+ * `adhd-backlog` (or any other consumer) invocation's terminal, on every
+ * single command, even though the node in question simply falls back to CPU
+ * silently and nothing is actually wrong.
+ *
+ * ── Why this is a stderr *filter*, not a log-severity option ────────────────
+ *
+ * onnxruntime-node's `InferenceSession.SessionOptions` DOES expose a
+ * `logSeverityLevel` (0=Verbose…4=Fatal) that would suppress Warning-level
+ * messages at the source — a cleaner fix, if it were reachable. It is not:
+ * `fastembed@2.1.0`'s `FlagEmbedding.init()` (`fastembed.js`'s
+ * `ort.InferenceSession.create(modelPath, { executionProviders,
+ * graphOptimizationLevel: "all" })`) hardcodes its own `SessionOptions`
+ * literal with no passthrough for caller options, and `fastembed`'s public
+ * `InitOptions` type has no `sessionOptions`/`logSeverityLevel` field either
+ * (verified against the installed `fastembed@2.1.0` and
+ * `onnxruntime-node@1.21.0` packages — not assumed). Filtering the child's
+ * stderr byte stream is therefore the only lever this package can pull.
+ *
+ * ── Why this must NOT become "throw away all child stderr" ──────────────────
+ *
+ * `fastembedProcessHost.ts`'s BL-331 lock check intentionally
+ * `console.error`s a loud, greppable line when a competing fastembed host is
+ * detected (so an otherwise-unattributable embed-latency regression has a
+ * visible correlate), and
+ * `resolveExecutionProviders()` intentionally `console.error`s when
+ * `SOX_EMBED_EXECUTION_PROVIDER` forces a non-default provider. A blanket
+ * "pipe stderr, discard everything" fix would silently destroy both of those
+ * — reintroducing exactly the silent-failure class BL-331 exists to prevent.
+ * So this filter matches ONLY the known-benign CoreML dim-limit warning text
+ * and passes every other line — including genuine errors and both lines
+ * above — straight through unmodified.
+ */
+/**
+ * True if `line` is the known-benign ONNX Runtime CoreML dim-limit warning
+ * (see module doc comment). This is a plain substring match — deliberately
+ * narrow (not a broad `onnxruntime`/`[W:` pattern) so this filter can never
+ * swallow an unrelated onnxruntime warning or error that happens to share the
+ * `[W:onnxruntime:...]` prefix format.
+ */
+export declare function isBenignOnnxCoreMlWarning(line: string): boolean;
+/**
+ * Attach a line-buffering filter to a child process's stderr `Readable`,
+ * dropping only lines matching {@link isBenignOnnxCoreMlWarning} and writing
+ * every other line through to `dest` (defaults to `process.stderr`)
+ * unbuffered, verbatim (original line content, `\n`-terminated), and in the
+ * order it was received.
+ *
+ * Chunk boundaries never line up with `\n` boundaries in a real pipe, so
+ * this buffers a trailing partial line across `data` events instead of
+ * filtering mid-line: `source` is split on `\n` as chunks arrive, each
+ * complete line is tested and (if not benign) written immediately, and any
+ * remaining partial line is flushed on `end` (also filtered, so a benign
+ * warning that happens to be the final unterminated write is still caught).
+ */
+export declare function attachOnnxStderrFilter(source: NodeJS.ReadableStream, dest?: NodeJS.WritableStream): void;
+//# sourceMappingURL=onnxStderrFilter.d.ts.map

package/dist/onnxStderrFilter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onnxStderrFilter.d.ts","sourceRoot":"","sources":["../src/onnxStderrFilter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAIH;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,CAAC,cAAc,EAC7B,IAAI,GAAE,MAAM,CAAC,cAA+B,GAC3C,IAAI,CAmBN"}