@adhd/sox-embedding-provider 0.5.1 → 0.5.2

package/dist/embedHostConfig.d.ts

@@ -0,0 +1,120 @@
+/**
+ * embedHostConfig.ts — config + stable socket/singleton-key resolution for the
+ * embedding funnel (SPEC-EMBEDDING-FUNNEL.md §B).
+ *
+ * The funnel collapses N consumer processes onto ONE peer-spawned, self-reaping
+ * ONNX host per `(model, execution-provider, cacheDir)`. That requires a
+ * deterministic, machine-wide identity for "the one host for this workload":
+ *
+ *   - {@link embedHostSingletonKey} — the [def:singleton-key] every consumer
+ *     computes identically, so `ensureBackend()`'s O_EXCL spawn-lock collapses a
+ *     thundering herd to one spawn.
+ *   - {@link embedHostSocketPath} — the UDS path derived from that key via
+ *     `backendSocketPath()` (the SAME derivation the service-proxy uses, so
+ *     there is never a port-selection problem and never a clash).
+ *
+ * ── Host selection is typed config, never an env toggle (ADR-0013) ─────────────
+ *
+ * `host` is a closed union (`'shared' | 'private'`) carried on
+ * `EmbeddingProviderConfig.host` and reported in `health()`. There is
+ * deliberately NO `SOX_EMBED_HOST=shared|private` variable: a behavior switch
+ * must be visible, validated, and auditable, not an ambient string. The only
+ * env reads here are ADR-0013 D3/D5 shapes:
+ *
+ *   - `SOX_EMBED_HOST_IDLE_GRACE_MS` — a numeric tuning constant (D3): how long
+ *     the host lingers after its last client leaves. Additive/numeric only.
+ *   - `SOX_ECOSYSTEM_HOME` — host config (D5): where the socket lives.
+ *   - `SOX_EMBED_HOST_MAIN` / `SOX_EMBED_HOST_SOCKET` — host-injected transport
+ *     config (D5) / test seams; they select a path, they never enable a feature.
+ *
+ * Leaf module — node builtins only (fs, os, path, url, crypto, module) plus
+ * `backendSocketPath` from `@adhd/sox-service-proxy`.
+ */
+/** The host-selection closed union (ADR-0013). `'shared'` is the default. */
+export type EmbedHostMode = 'shared' | 'private';
+/** Resolved funnel configuration. */
+export interface EmbedHostConfig {
+    /** `'shared'` (default): funnel through the peer-spawned host. `'private'`: the pre-funnel per-process fork (CI/diagnostics). */
+    host: EmbedHostMode;
+    /** The directory the host UDS is created under (ADR-0004: `$SOX_ECOSYSTEM_HOME/run`). */
+    socketDir: string;
+    /** How long the host lingers with zero clients and zero in-flight work before it reaps itself. */
+    idleGraceMs: number;
+}
+/**
+ * Bumped whenever the host's wire protocol or behavior changes incompatibly.
+ *
+ * Open question #4 in SPEC-EMBEDDING-FUNNEL.md ("a running host is an old
+ * build") is resolved with this constant rather than the npm package version.
+ * Rationale: the real hazard is a host whose `embedding.*` contract the new
+ * consumer cannot speak — a *protocol* change — not every cosmetic patch. Keying
+ * on the npm version would spawn a brand-new host on every patch bump (briefly
+ * two hosts, defeating the funnel across an upgrade window) while the explicit
+ * protocol version forces a new socket exactly when compatibility actually
+ * breaks. Bump this with any change to the `embedding.*` method set, the payload
+ * shape, or the response shape in `embedHostMain.ts`.
+ */
+export declare const EMBED_HOST_PROTOCOL_VERSION = 1;
+/** Default grace before a zero-client host reaps itself. Sized to the short-lived-CLI arrival cadence. */
+export declare const DEFAULT_EMBED_HOST_IDLE_GRACE_MS = 30000;
+/**
+ * Apply the typed `host` field from an `EmbeddingProviderConfig`. Passing
+ * `undefined` leaves the current posture unchanged (so a `remote` provider
+ * without a `host` field never resets a deliberate `'private'` selection).
+ */
+export declare function configureEmbedHostHost(host: EmbedHostMode | undefined): void;
+/** TEST-ONLY: clear the process-wide host override back to the `'shared'` default. */
+export declare function __resetEmbedHostConfigForTests(): void;
+/**
+ * Resolve the funnel configuration. `host` defaults to `'shared'`; `idleGraceMs`
+ * is a numeric tuning constant (ADR-0013 D3) with a hard default.
+ */
+export declare function resolveEmbedHostConfig(): EmbedHostConfig;
+/**
+ * ADR-0013 D3 tuning constant: `SOX_EMBED_HOST_IDLE_GRACE_MS`. A non-positive or
+ * non-numeric value is rejected loudly (never silently treated as "off").
+ */
+export declare function resolveEmbedHostIdleGraceMs(): number;
+/**
+ * ADR-0004 D5: the host socket lives under `$SOX_ECOSYSTEM_HOME/run` (the user
+ * data root's `run/` dir). Mirrors `@adhd/sox-host-runtime`'s `runDir()` without
+ * importing it — this package is a low-tier leaf and must not gain a
+ * host-runtime dependency. `SOX_ECOSYSTEM_HOME` defaults to `~/.adhd/sox-ecosystem`
+ * exactly as `data-paths.ts`'s `DATA_SUBDIR` does.
+ */
+export declare function resolveEmbedHostSocketDir(): string;
+/**
+ * The machine-wide [def:singleton-key] for the host serving `(modelId, ep,
+ * cacheDir)`. Identical inputs ⇒ identical key ⇒ identical socket ⇒ one host,
+ * across every consumer process on the box.
+ *
+ * `cacheDirDigest` is a short sha256 of the ABSOLUTE cache dir, so two stores
+ * pointed at different model caches never collide onto one host. The protocol
+ * version is appended (see {@link EMBED_HOST_PROTOCOL_VERSION}).
+ */
+export declare function embedHostSingletonKey(modelId: string, ep: string, cacheDir: string): string;
+/** Derive the host UDS path from the resolved config and singleton key. */
+export declare function embedHostSocketPath(cfg: EmbedHostConfig, key: string): string;
+/**
+ * Resolve the runnable host entrypoint to spawn.
+ *
+ * Order:
+ *   1. `SOX_EMBED_HOST_MAIN` (D5/test seam) — a path injection, never a feature
+ *      toggle. Used by the funnel teeth suite to run the host from source via a
+ *      tsx shim without a prior build.
+ *   2. A `__dirname` sibling (`dist/embedHostMain.js`) — the npm AND bundled
+ *      case. The literal `join(__dirname, 'embedHostMain.js')` is load-bearing:
+ *      `bundle-extension.cjs`'s `verifySidecarReferences()` scans emitted files
+ *      for exactly this shape, so the sidecar can never ship missing (BL-259).
+ *   3. `src/../dist/embedHostMain.js` — vitest's `src/`-resident `__dirname`.
+ *   4. `require.resolve('@adhd/sox-embedding-provider/embed-host')` — the
+ *      package `exports` subpath, when self-reference is available.
+ */
+export declare function resolveEmbedHostMainPath(): string;
+/**
+ * Where the detached host's stderr is redirected (its stdout/stdin are severed).
+ * Kept beside the socket so a wedged host's startup diagnostics are greppable
+ * without inheriting any caller fd ([inv:no-fd-inherit], BL-67).
+ */
+export declare function resolveEmbedHostStderrLogPath(cfg: EmbedHostConfig): string;
+//# sourceMappingURL=embedHostConfig.d.ts.map

package/dist/embedHostConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedHostConfig.d.ts","sourceRoot":"","sources":["../src/embedHostConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAYH,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEjD,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC9B,iIAAiI;IACjI,IAAI,EAAE,aAAa,CAAC;IACpB,yFAAyF;IACzF,SAAS,EAAE,MAAM,CAAC;IAClB,kGAAkG;IAClG,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,0GAA0G;AAC1G,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAcvD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI,CAM5E;AAED,sFAAsF;AACtF,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,CAMxD;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,CAUpD;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAIlD;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG3F;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAgBjD;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAE1E"}

package/dist/embedHostConfig.js

@@ -0,0 +1,180 @@
+/**
+ * embedHostConfig.ts — config + stable socket/singleton-key resolution for the
+ * embedding funnel (SPEC-EMBEDDING-FUNNEL.md §B).
+ *
+ * The funnel collapses N consumer processes onto ONE peer-spawned, self-reaping
+ * ONNX host per `(model, execution-provider, cacheDir)`. That requires a
+ * deterministic, machine-wide identity for "the one host for this workload":
+ *
+ *   - {@link embedHostSingletonKey} — the [def:singleton-key] every consumer
+ *     computes identically, so `ensureBackend()`'s O_EXCL spawn-lock collapses a
+ *     thundering herd to one spawn.
+ *   - {@link embedHostSocketPath} — the UDS path derived from that key via
+ *     `backendSocketPath()` (the SAME derivation the service-proxy uses, so
+ *     there is never a port-selection problem and never a clash).
+ *
+ * ── Host selection is typed config, never an env toggle (ADR-0013) ─────────────
+ *
+ * `host` is a closed union (`'shared' | 'private'`) carried on
+ * `EmbeddingProviderConfig.host` and reported in `health()`. There is
+ * deliberately NO `SOX_EMBED_HOST=shared|private` variable: a behavior switch
+ * must be visible, validated, and auditable, not an ambient string. The only
+ * env reads here are ADR-0013 D3/D5 shapes:
+ *
+ *   - `SOX_EMBED_HOST_IDLE_GRACE_MS` — a numeric tuning constant (D3): how long
+ *     the host lingers after its last client leaves. Additive/numeric only.
+ *   - `SOX_ECOSYSTEM_HOME` — host config (D5): where the socket lives.
+ *   - `SOX_EMBED_HOST_MAIN` / `SOX_EMBED_HOST_SOCKET` — host-injected transport
+ *     config (D5) / test seams; they select a path, they never enable a feature.
+ *
+ * Leaf module — node builtins only (fs, os, path, url, crypto, module) plus
+ * `backendSocketPath` from `@adhd/sox-service-proxy`.
+ */
+import { existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { backendSocketPath } from '@adhd/sox-service-proxy';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Bumped whenever the host's wire protocol or behavior changes incompatibly.
+ *
+ * Open question #4 in SPEC-EMBEDDING-FUNNEL.md ("a running host is an old
+ * build") is resolved with this constant rather than the npm package version.
+ * Rationale: the real hazard is a host whose `embedding.*` contract the new
+ * consumer cannot speak — a *protocol* change — not every cosmetic patch. Keying
+ * on the npm version would spawn a brand-new host on every patch bump (briefly
+ * two hosts, defeating the funnel across an upgrade window) while the explicit
+ * protocol version forces a new socket exactly when compatibility actually
+ * breaks. Bump this with any change to the `embedding.*` method set, the payload
+ * shape, or the response shape in `embedHostMain.ts`.
+ */
+export const EMBED_HOST_PROTOCOL_VERSION = 1;
+/** Default grace before a zero-client host reaps itself. Sized to the short-lived-CLI arrival cadence. */
+export const DEFAULT_EMBED_HOST_IDLE_GRACE_MS = 30_000;
+/**
+ * Process-wide host-selection override. `null` ⇒ `'shared'`.
+ *
+ * Deliberately NOT an env var (ADR-0013): the typed
+ * `EmbeddingProviderConfig.host` field is applied here by
+ * `createEmbeddingProvider()` before the accessor singleton is constructed.
+ * Host selection is a process-wide posture — once a consumer has resolved its
+ * accessor, changing this does not retroactively re-point it (documented, not
+ * hidden).
+ */
+let _hostOverride = null;
+/**
+ * Apply the typed `host` field from an `EmbeddingProviderConfig`. Passing
+ * `undefined` leaves the current posture unchanged (so a `remote` provider
+ * without a `host` field never resets a deliberate `'private'` selection).
+ */
+export function configureEmbedHostHost(host) {
+    if (host === undefined)
+        return;
+    if (host !== 'shared' && host !== 'private') {
+        throw new TypeError(`EmbedHostMode must be 'shared' or 'private', got ${String(host)}`);
+    }
+    _hostOverride = host;
+}
+/** TEST-ONLY: clear the process-wide host override back to the `'shared'` default. */
+export function __resetEmbedHostConfigForTests() {
+    _hostOverride = null;
+}
+/**
+ * Resolve the funnel configuration. `host` defaults to `'shared'`; `idleGraceMs`
+ * is a numeric tuning constant (ADR-0013 D3) with a hard default.
+ */
+export function resolveEmbedHostConfig() {
+    return {
+        host: _hostOverride ?? 'shared',
+        socketDir: resolveEmbedHostSocketDir(),
+        idleGraceMs: resolveEmbedHostIdleGraceMs(),
+    };
+}
+/**
+ * ADR-0013 D3 tuning constant: `SOX_EMBED_HOST_IDLE_GRACE_MS`. A non-positive or
+ * non-numeric value is rejected loudly (never silently treated as "off").
+ */
+export function resolveEmbedHostIdleGraceMs() {
+    const raw = process.env['SOX_EMBED_HOST_IDLE_GRACE_MS'];
+    if (raw === undefined || raw === '')
+        return DEFAULT_EMBED_HOST_IDLE_GRACE_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new TypeError(`SOX_EMBED_HOST_IDLE_GRACE_MS must be a positive number, got ${JSON.stringify(raw)}`);
+    }
+    return parsed;
+}
+/**
+ * ADR-0004 D5: the host socket lives under `$SOX_ECOSYSTEM_HOME/run` (the user
+ * data root's `run/` dir). Mirrors `@adhd/sox-host-runtime`'s `runDir()` without
+ * importing it — this package is a low-tier leaf and must not gain a
+ * host-runtime dependency. `SOX_ECOSYSTEM_HOME` defaults to `~/.adhd/sox-ecosystem`
+ * exactly as `data-paths.ts`'s `DATA_SUBDIR` does.
+ */
+export function resolveEmbedHostSocketDir() {
+    const home = process.env['SOX_ECOSYSTEM_HOME'];
+    const root = home !== undefined && home !== '' ? home : join(homedir(), '.adhd', 'sox-ecosystem');
+    return join(root, 'run');
+}
+/**
+ * The machine-wide [def:singleton-key] for the host serving `(modelId, ep,
+ * cacheDir)`. Identical inputs ⇒ identical key ⇒ identical socket ⇒ one host,
+ * across every consumer process on the box.
+ *
+ * `cacheDirDigest` is a short sha256 of the ABSOLUTE cache dir, so two stores
+ * pointed at different model caches never collide onto one host. The protocol
+ * version is appended (see {@link EMBED_HOST_PROTOCOL_VERSION}).
+ */
+export function embedHostSingletonKey(modelId, ep, cacheDir) {
+    const digest = createHash('sha256').update(cacheDir, 'utf8').digest('hex').slice(0, 12);
+    return `embedding-host:v${EMBED_HOST_PROTOCOL_VERSION}:${modelId}:${ep}:${digest}`;
+}
+/** Derive the host UDS path from the resolved config and singleton key. */
+export function embedHostSocketPath(cfg, key) {
+    return backendSocketPath(cfg.socketDir, key);
+}
+/**
+ * Resolve the runnable host entrypoint to spawn.
+ *
+ * Order:
+ *   1. `SOX_EMBED_HOST_MAIN` (D5/test seam) — a path injection, never a feature
+ *      toggle. Used by the funnel teeth suite to run the host from source via a
+ *      tsx shim without a prior build.
+ *   2. A `__dirname` sibling (`dist/embedHostMain.js`) — the npm AND bundled
+ *      case. The literal `join(__dirname, 'embedHostMain.js')` is load-bearing:
+ *      `bundle-extension.cjs`'s `verifySidecarReferences()` scans emitted files
+ *      for exactly this shape, so the sidecar can never ship missing (BL-259).
+ *   3. `src/../dist/embedHostMain.js` — vitest's `src/`-resident `__dirname`.
+ *   4. `require.resolve('@adhd/sox-embedding-provider/embed-host')` — the
+ *      package `exports` subpath, when self-reference is available.
+ */
+export function resolveEmbedHostMainPath() {
+    const override = process.env['SOX_EMBED_HOST_MAIN'];
+    if (override !== undefined && override !== '')
+        return override;
+    const sibling = join(__dirname, 'embedHostMain.js');
+    if (existsSync(sibling))
+        return sibling;
+    const distSibling = join(__dirname, '..', 'dist', 'embedHostMain.js');
+    if (existsSync(distSibling))
+        return distSibling;
+    try {
+        return createRequire(import.meta.url).resolve('@adhd/sox-embedding-provider/embed-host');
+    }
+    catch {
+        // Last resort: name the path that was actually attempted in any later error.
+        return sibling;
+    }
+}
+/**
+ * Where the detached host's stderr is redirected (its stdout/stdin are severed).
+ * Kept beside the socket so a wedged host's startup diagnostics are greppable
+ * without inheriting any caller fd ([inv:no-fd-inherit], BL-67).
+ */
+export function resolveEmbedHostStderrLogPath(cfg) {
+    return join(cfg.socketDir, 'logs', 'embed-host.stderr.log');
+}
+//# sourceMappingURL=embedHostConfig.js.map

package/dist/embedHostConfig.js.map

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

package/dist/embedHostMain.d.ts

@@ -0,0 +1,46 @@
+/**
+ * embedHostMain.ts — the peer-spawned, self-reaping embedding host process
+ * (SPEC-EMBEDDING-FUNNEL.md §C).
+ *
+ * This is the compute backend of the funnel: a plain, DETACHED Node process,
+ * spawned on demand by the first consumer through `ensureBackend()`'s O_EXCL
+ * singleton spawn-lock. It is **never supervised** (no launchd/KeepAlive) and it
+ * **reaps itself** — a debounced, ref-counted teardown retires it
+ * `idleGraceMs` after the last cross-process client disconnects and in-flight
+ * work drains.
+ *
+ * ── Compute-only (ADR-0012) ────────────────────────────────────────────────────
+ *
+ * The host holds NO store connection. It forwards `embedding.*` payloads 1:1 to
+ * its private ONNX pool and never opens a database. It therefore cannot
+ * serialize store access and must never be described as single-writer or as a
+ * store serialization point; concurrent store writers are unaffected.
+ *
+ * ── No recursion ───────────────────────────────────────────────────────────────
+ *
+ * The handler forwards to `getPrivateFastembedProcess()` — the PRIVATE pool — and
+ * NEVER to `getSharedFastembedProcess()`, which under `host: 'shared'` would
+ * return a `FunneledFastembedClient` and dial this very host (infinite
+ * recursion). The import graph is arranged so that mistake is a type error, not
+ * a runtime hang.
+ *
+ * ── Teardown inputs are CROSS-PROCESS ─────────────────────────────────────────
+ *
+ *   - `activeClients` — live UDS client connections, from `serveBackend`'s
+ *     `onClientCountChange` hook (the cross-process half);
+ *   - `privateClient.pendingCount` — this host's own in-flight requests (the
+ *     in-process half).
+ *
+ * `activeClients === 0 && pendingCount === 0` arms the grace timer; a new client
+ * or request cancels it. On expiry the private pool is terminated, the listener
+ * closed (which unlinks the socket), and the process exits 0. The private pool's
+ * ONNX child is forked `detached: false`, so it dies with the host — no orphans.
+ */
+/**
+ * Start the host: bind the UDS, serve `embedding.*`, and arm the debounced
+ * self-reap. Resolves once the listener is up (so a caller/test can await
+ * readiness); the process stays alive until the teardown fires or a signal
+ * arrives.
+ */
+export declare function runEmbedHost(): Promise<void>;
+//# sourceMappingURL=embedHostMain.d.ts.map

package/dist/embedHostMain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedHostMain.d.ts","sourceRoot":"","sources":["../src/embedHostMain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAyBH;;;;;GAKG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CA2GlD"}

package/dist/embedHostMain.js

@@ -0,0 +1,192 @@
+/**
+ * embedHostMain.ts — the peer-spawned, self-reaping embedding host process
+ * (SPEC-EMBEDDING-FUNNEL.md §C).
+ *
+ * This is the compute backend of the funnel: a plain, DETACHED Node process,
+ * spawned on demand by the first consumer through `ensureBackend()`'s O_EXCL
+ * singleton spawn-lock. It is **never supervised** (no launchd/KeepAlive) and it
+ * **reaps itself** — a debounced, ref-counted teardown retires it
+ * `idleGraceMs` after the last cross-process client disconnects and in-flight
+ * work drains.
+ *
+ * ── Compute-only (ADR-0012) ────────────────────────────────────────────────────
+ *
+ * The host holds NO store connection. It forwards `embedding.*` payloads 1:1 to
+ * its private ONNX pool and never opens a database. It therefore cannot
+ * serialize store access and must never be described as single-writer or as a
+ * store serialization point; concurrent store writers are unaffected.
+ *
+ * ── No recursion ───────────────────────────────────────────────────────────────
+ *
+ * The handler forwards to `getPrivateFastembedProcess()` — the PRIVATE pool — and
+ * NEVER to `getSharedFastembedProcess()`, which under `host: 'shared'` would
+ * return a `FunneledFastembedClient` and dial this very host (infinite
+ * recursion). The import graph is arranged so that mistake is a type error, not
+ * a runtime hang.
+ *
+ * ── Teardown inputs are CROSS-PROCESS ─────────────────────────────────────────
+ *
+ *   - `activeClients` — live UDS client connections, from `serveBackend`'s
+ *     `onClientCountChange` hook (the cross-process half);
+ *   - `privateClient.pendingCount` — this host's own in-flight requests (the
+ *     in-process half).
+ *
+ * `activeClients === 0 && pendingCount === 0` arms the grace timer; a new client
+ * or request cancels it. On expiry the private pool is terminated, the listener
+ * closed (which unlinks the socket), and the process exits 0. The private pool's
+ * ONNX child is forked `detached: false`, so it dies with the host — no orphans.
+ */
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { serveBackend } from '@adhd/sox-service-proxy';
+import { resolveEmbedHostIdleGraceMs } from './embedHostConfig.js';
+import { getPrivateFastembedProcess, resetPrivateFastembedProcess } from './sharedFastembedProcess.js';
+/** The `embedding.*` methods the host serves. */
+const HOST_METHODS = new Set([
+    'embedding.init',
+    'embedding.embed',
+    'embedding.embedBatch',
+    'embedding.reset',
+    'embedding.health',
+]);
+function ok(id, result) {
+    return { jsonrpc: '2.0', id: id ?? null, result };
+}
+function fail(id, code, message) {
+    return { jsonrpc: '2.0', id: id ?? null, error: { code, message } };
+}
+/**
+ * Start the host: bind the UDS, serve `embedding.*`, and arm the debounced
+ * self-reap. Resolves once the listener is up (so a caller/test can await
+ * readiness); the process stays alive until the teardown fires or a signal
+ * arrives.
+ */
+export async function runEmbedHost() {
+    const socketPath = process.env['SOX_EMBED_HOST_SOCKET'];
+    if (!socketPath) {
+        process.stderr.write('[embed-host] SOX_EMBED_HOST_SOCKET is not set — the host is spawned by the funnel client, not run directly.\n');
+        process.exit(2);
+    }
+    const idleGraceMs = resolveEmbedHostIdleGraceMs();
+    const privateClient = getPrivateFastembedProcess();
+    let activeClients = 0;
+    let idleTimer = null;
+    let shuttingDown = false;
+    let handle = null;
+    const cancelIdle = () => {
+        if (idleTimer) {
+            clearTimeout(idleTimer);
+            idleTimer = null;
+        }
+    };
+    const teardown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        cancelIdle();
+        try {
+            await privateClient.terminate();
+        }
+        catch {
+            /* best-effort — the ONNX child dies with us regardless (detached:false) */
+        }
+        try {
+            await handle?.close();
+        }
+        catch {
+            /* best-effort — the socket unlink happens inside close() */
+        }
+        process.exit(0);
+    };
+    const armIfIdle = () => {
+        if (shuttingDown || idleTimer)
+            return;
+        if (activeClients !== 0 || privateClient.pendingCount !== 0)
+            return;
+        idleTimer = setTimeout(() => {
+            idleTimer = null;
+            void teardown();
+        }, idleGraceMs);
+        // The listener keeps the loop alive; the timer itself must not.
+        idleTimer.unref?.();
+    };
+    const handler = async (req) => {
+        // Any inbound request is demand — cancel a pending reap.
+        cancelIdle();
+        const id = req.id;
+        const method = req.method;
+        if (!HOST_METHODS.has(method)) {
+            return fail(id, -32601, `method not found: ${method}`);
+        }
+        try {
+            if (method === 'embedding.health') {
+                return ok(id, {
+                    started: privateClient.started,
+                    pendingCount: privateClient.pendingCount,
+                    activeClients,
+                    idleGraceMs,
+                });
+            }
+            if (method === 'embedding.reset') {
+                await resetPrivateFastembedProcess();
+                return ok(id, { reset: true });
+            }
+            // embedding.init | embedding.embed | embedding.embedBatch — forward the
+            // payload 1:1 to the PRIVATE pool (never the funnel accessor).
+            const params = (req.params ?? {});
+            const result = await privateClient.request(params);
+            return ok(id, result);
+        }
+        catch (e) {
+            return fail(id, -32603, e instanceof Error ? e.message : String(e));
+        }
+        finally {
+            // A request may have drained the last in-flight work with no clients
+            // attached (e.g. a one-shot embed) — re-arm the reap.
+            if (activeClients === 0)
+                armIfIdle();
+        }
+    };
+    handle = await serveBackend({
+        socketPath,
+        handler,
+        onDiagnostic: (line) => process.stderr.write(line + '\n'),
+        onClientCountChange: (active) => {
+            activeClients = active;
+            if (active > 0)
+                cancelIdle();
+            else
+                armIfIdle();
+        },
+    });
+    // Arm immediately: if no client ever connects (e.g. the spawner died between
+    // spawn and dial), the host must still reap rather than linger forever.
+    armIfIdle();
+    // A detached host can still be signalled directly (kill, OS teardown).
+    process.on('SIGTERM', () => void teardown());
+    process.on('SIGINT', () => void teardown());
+}
+/**
+ * True when this module is the process entrypoint (`node dist/embedHostMain.js`).
+ * `ensureBackend` spawns exactly that. A test shim that imports this module and
+ * calls `runEmbedHost()` explicitly is NOT the entrypoint, so it does not
+ * double-start.
+ */
+function isEntrypoint() {
+    const argv1 = process.argv[1];
+    if (!argv1)
+        return false;
+    try {
+        return resolve(fileURLToPath(import.meta.url)) === resolve(argv1);
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntrypoint()) {
+    runEmbedHost().catch((err) => {
+        process.stderr.write(`[embed-host] fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=embedHostMain.js.map

package/dist/embedHostMain.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * errors.ts — the embedding error taxonomy, extracted so internal modules
+ * (notably `funnelClient.ts`) can throw typed errors without importing the
+ * public `index.ts` barrel and creating an import cycle.
+ *
+ * The classes are re-exported verbatim from `index.ts`, so the public surface is
+ * unchanged: `import { TransientEmbeddingError } from '@adhd/sox-embedding-provider'`
+ * keeps working, and `instanceof` identity is preserved (one class, one home).
+ *
+ * Three tiers, no silent degradation:
+ *   - TransientEmbeddingError — the caller may retry (has `retryAfterMs`).
+ *   - PermanentEmbeddingError — the caller must not retry.
+ *   - ResolutionError — factory-time only (bad config / unknown model), never mid-call.
+ */
+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);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;gBAC9B,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM;CAKnD;AAED,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B"}

package/dist/errors.js

@@ -0,0 +1,35 @@
+/**
+ * errors.ts — the embedding error taxonomy, extracted so internal modules
+ * (notably `funnelClient.ts`) can throw typed errors without importing the
+ * public `index.ts` barrel and creating an import cycle.
+ *
+ * The classes are re-exported verbatim from `index.ts`, so the public surface is
+ * unchanged: `import { TransientEmbeddingError } from '@adhd/sox-embedding-provider'`
+ * keeps working, and `instanceof` identity is preserved (one class, one home).
+ *
+ * Three tiers, no silent degradation:
+ *   - TransientEmbeddingError — the caller may retry (has `retryAfterMs`).
+ *   - PermanentEmbeddingError — the caller must not retry.
+ *   - ResolutionError — factory-time only (bad config / unknown model), never mid-call.
+ */
+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';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/fastembed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fastembed.d.ts","sourceRoot":"","sources":["../src/fastembed.ts"],"names":[],"mappings":"AACA,OAAO,EAA6B,KAAK,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACpG,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAO3G,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAgBrD,0DAA0D;AAC1D,QAAA,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAEtC,CAAC;AAEF,gEAAgE;AAChE,QAAA,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAE5C,CAAC;AAEF,QAAA,MAAM,aAAa,qBAAqB,CAAC;AACzC,QAAA,MAAM,kBAAkB,MAAM,CAAC;AAE/B;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,YAAW,iBAAiB;IACzD,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,CAAC;IAC7C,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAS;IASzB,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,YAAY,CAAO;IAC3B,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,kBAAkB,CAAiB;IAE3C;;;;;OAKG;gBAED,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,YAAY,GAAE,qBAAmD;IAkBnE,MAAM,IAAI,eAAe;IAmBnB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC;IAkBlE,UAAU,CACf,KAAK,EAAE,MAAM,EAAE,EACf,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,SAAS,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC9C,aAAa,CAAC,YAAY,CAAC;IAuBxB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5C;;;OAGG;IACH,OAAO,CAAC,cAAc;IAItB;;;OAGG;IACH,OAAO,CAAC,SAAS;IAmBjB;;;OAGG;IACH,OAAO,CAAC,QAAQ;IA0BhB;;;OAGG;IACH,OAAO,CAAC,WAAW;YAQL,SAAS;YA2CT,SAAS;IAKvB,OAAO,CAAC,mBAAmB;CAc5B;AAED,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,kBAAkB,EAAE,CAAC"}
+{"version":3,"file":"fastembed.d.ts","sourceRoot":"","sources":["../src/fastembed.ts"],"names":[],"mappings":"AACA,OAAO,EAA6B,KAAK,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAEpG,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAO3G,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAgBrD,0DAA0D;AAC1D,QAAA,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAEtC,CAAC;AAEF,gEAAgE;AAChE,QAAA,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAE5C,CAAC;AAEF,QAAA,MAAM,aAAa,qBAAqB,CAAC;AACzC,QAAA,MAAM,kBAAkB,MAAM,CAAC;AAE/B;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,YAAW,iBAAiB;IACzD,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,CAAC;IAC7C,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAS;IASzB,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,YAAY,CAAO;IAC3B,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,kBAAkB,CAAiB;IAE3C;;;;;OAKG;gBAED,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,YAAY,GAAE,qBAAmD;IAkBnE,MAAM,IAAI,eAAe;IAqBnB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC;IAkBlE,UAAU,CACf,KAAK,EAAE,MAAM,EAAE,EACf,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,SAAS,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC9C,aAAa,CAAC,YAAY,CAAC;IAuBxB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5C;;;OAGG;IACH,OAAO,CAAC,cAAc;IAItB;;;OAGG;IACH,OAAO,CAAC,SAAS;IAmBjB;;;OAGG;IACH,OAAO,CAAC,QAAQ;IA0BhB;;;OAGG;IACH,OAAO,CAAC,WAAW;YAQL,SAAS;YA2CT,SAAS;IAKvB,OAAO,CAAC,mBAAmB;CAc5B;AAED,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,kBAAkB,EAAE,CAAC"}