@adhd/sox-embedding-provider 0.5.1 → 0.5.3

package/README.md

@@ -43,6 +43,8 @@ interface EmbeddingProviderConfig {
   type: string;    // 'fastembed' | 'remote'
   model: string;
   options?: Record<string, unknown>;
+  host?: 'shared' | 'private';  // default 'shared' — see "Host posture" below
+  idleGraceMs?: number;         // how long an idle shared host lingers (default 30000)
 }
 ```
 
@@ -107,9 +109,48 @@ Built-in models (`modelId` → dimensions):
 | `bge-m3` | 1024 | 8192 | 100+ languages, long context, ~570M params |
 | `codexembed-400m` | 1024 | 8192 | code-only, ~1.6GB RAM, long context |
 
-fastembed inference is routed through a single process-wide shared child process rather than a
-worker per provider instance, so multiple `FastembedProvider`s constructed in the same Node process
-(even concurrently) never race each other for the same native ONNX runtime.
+fastembed inference is routed through **one machine-wide, peer-spawned, self-reaping host
+process** per `(model, execution-provider, cacheDir)` — not one ONNX host per consumer process.
+The first consumer to need it peer-spawns the host through the service-proxy's `ensureBackend()`
+singleton spawn-lock; every other consumer on the box dials that same host over a Unix domain
+socket. The host is compute-only (it holds no store connection) and it **reaps itself**: a
+debounced, ref-counted teardown retires it `idleGraceMs` after the last client disconnects and its
+last in-flight request drains. There is no supervised service and no daemon.
+
+#### Host posture
+
+`EmbeddingProviderConfig.host` is a typed closed union (default `'shared'`), applied
+process-wide before the accessor is constructed and reported in `health().host`:
+
+- `'shared'` — funnel through the machine-wide host above. `getSharedFastembedProcess()` returns a
+  `FunneledFastembedClient`; its `terminate()` is a **no-op** (a consumer must never kill a host
+  other consumers are using).
+- `'private'` — the pre-funnel per-process fork (CI/diagnostics). `getSharedFastembedProcess()`
+  returns the private pool directly.
+
+`EmbeddingProviderConfig.idleGraceMs` (typed config, default `DEFAULT_EMBED_HOST_IDLE_GRACE_MS` =
+30 s) sets how long a zero-client host lingers before it reaps itself. A host that fails to come up
+throws a typed `TransientEmbeddingError` naming the socket — it never silently falls back to a
+private host.
+
+#### Lifecycle helpers
+
+```typescript
+import {
+  getPrivateFastembedProcess,   // the PRIVATE (un-funneled) per-process pool
+  resetSharedFastembedHost,     // heal: ask the live shared host to re-fork its private pool
+  getSharedFastembedProcess,    // the host-aware accessor (shared by default)
+  FunneledFastembedClient,      // what getSharedFastembedProcess() returns under 'shared'
+} from '@adhd/sox-embedding-provider';
+
+const client = getSharedFastembedProcess();  // FunneledFastembedClient under the default
+const vec = await client.request({ type: 'embed', text: 'hello' });
+console.log(client.started, client.pendingCount, client.hostSocketPath);
+```
+
+`resetSharedFastembedHost()` is the recovery path for a wedged private child: under `'shared'` it
+asks the live host to tear down and re-fork its private ONNX pool (without killing the host other
+consumers share); under `'private'` the accessor's `terminate()` path is unchanged.
 
 ### remote — call an HTTP embedding endpoint
 

package/dist/embedHostConfig.d.ts

@@ -0,0 +1,161 @@
+/**
+ * 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 AND the idle bound are typed config, never env toggles ──────
+ *
+ * `host` is a closed union (`'shared' | 'private'`) carried on
+ * `EmbeddingProviderConfig.host` and reported in `health()`. `idleGraceMs` is the
+ * same shape: a typed field on `EmbeddingProviderConfig.idleGraceMs` (applied by
+ * `createEmbeddingProvider()`), reported in the host's `embedding.health`, and
+ * carried on the resolved `EmbedHostConfig` the SPAWNER reads and forwards to the
+ * spawned host. There is deliberately NO `SOX_EMBED_HOST=shared|private`
+ * variable: a behavior switch must be visible, validated, and auditable, not an
+ * ambient string.
+ *
+ * `SOX_EMBED_HOST_IDLE_GRACE_MS` still exists, but it is the INTERNAL
+ * cross-process transport between the spawner and the spawned host — the spawner
+ * writes the resolved `EmbedHostConfig.idleGraceMs` into the child's env and the
+ * host consumes it. It is not the public configuration surface; set the typed
+ * `idleGraceMs` (or `configureEmbedHostIdleGraceMs()`) instead. (Owner directive:
+ * "the time bound should be configurable" — typed config, not an ADR-0013 D3 env
+ * tuning constant. This supersedes ADR-0020 D2's env-tuning framing.)
+ *
+ * The remaining env reads are ADR-0013 D5 shapes:
+ *
+ *   - `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. Typed config (owner directive: "the time bound should be
+     * configurable"): the SPAWNER reads this resolved value and forwards it to the
+     * spawned host, which consumes it. Set it via
+     * `EmbeddingProviderConfig.idleGraceMs` / `configureEmbedHostIdleGraceMs()`.
+     */
+    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;
+/**
+ * The internal cross-process transport variable the spawner uses to hand the
+ * resolved `EmbedHostConfig.idleGraceMs` to the spawned host. Not a public knob
+ * — set the typed `idleGraceMs` instead.
+ */
+export declare const EMBED_HOST_IDLE_GRACE_ENV = "SOX_EMBED_HOST_IDLE_GRACE_MS";
+/**
+ * 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;
+/**
+ * Apply the typed `idleGraceMs` field from an `EmbeddingProviderConfig`. Passing
+ * `undefined` leaves the current value unchanged (so a provider without the field
+ * never resets a deliberate selection). A non-positive or non-finite value is
+ * rejected loudly — never silently treated as "off".
+ */
+export declare function configureEmbedHostIdleGraceMs(idleGraceMs: number | undefined): void;
+/** TEST-ONLY: clear the process-wide host + idle-grace overrides back to defaults. */
+export declare function __resetEmbedHostConfigForTests(): void;
+/**
+ * Resolve the funnel configuration. `host` defaults to `'shared'`; `idleGraceMs`
+ * is typed config (with the transport env / hard default as fallbacks). The
+ * SPAWNER reads the resolved `idleGraceMs` and forwards it to the spawned host —
+ * see `funnelClient.ts`'s `doEnsure()` — which is what makes this field the
+ * consumed surface rather than a dead declaration.
+ */
+export declare function resolveEmbedHostConfig(): EmbedHostConfig;
+/**
+ * Resolve the idle grace, in priority order:
+ *
+ *   1. the typed override (`configureEmbedHostIdleGraceMs()` /
+ *      `EmbeddingProviderConfig.idleGraceMs`) — the public surface;
+ *   2. the internal transport env (`SOX_EMBED_HOST_IDLE_GRACE_ENV`) the spawner
+ *      writes for the spawned host;
+ *   3. `DEFAULT_EMBED_HOST_IDLE_GRACE_MS`.
+ *
+ * A non-positive or non-numeric transport 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;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;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,0GAA0G;AAC1G,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAwBvD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,iCAAiC,CAAC;AAExE;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI,CAM5E;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAQnF;AAED,sFAAsF;AACtF,wBAAgB,8BAA8B,IAAI,IAAI,CAGrD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,CAMxD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,CAWpD;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,234 @@
+/**
+ * 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 AND the idle bound are typed config, never env toggles ──────
+ *
+ * `host` is a closed union (`'shared' | 'private'`) carried on
+ * `EmbeddingProviderConfig.host` and reported in `health()`. `idleGraceMs` is the
+ * same shape: a typed field on `EmbeddingProviderConfig.idleGraceMs` (applied by
+ * `createEmbeddingProvider()`), reported in the host's `embedding.health`, and
+ * carried on the resolved `EmbedHostConfig` the SPAWNER reads and forwards to the
+ * spawned host. There is deliberately NO `SOX_EMBED_HOST=shared|private`
+ * variable: a behavior switch must be visible, validated, and auditable, not an
+ * ambient string.
+ *
+ * `SOX_EMBED_HOST_IDLE_GRACE_MS` still exists, but it is the INTERNAL
+ * cross-process transport between the spawner and the spawned host — the spawner
+ * writes the resolved `EmbedHostConfig.idleGraceMs` into the child's env and the
+ * host consumes it. It is not the public configuration surface; set the typed
+ * `idleGraceMs` (or `configureEmbedHostIdleGraceMs()`) instead. (Owner directive:
+ * "the time bound should be configurable" — typed config, not an ADR-0013 D3 env
+ * tuning constant. This supersedes ADR-0020 D2's env-tuning framing.)
+ *
+ * The remaining env reads are ADR-0013 D5 shapes:
+ *
+ *   - `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;
+/**
+ * Process-wide idle-grace override. `null` ⇒ resolve from the transport env (or
+ * the default). This is the TYPED public surface for the time bound: the owner
+ * directive is that the bound be configurable as config, not as an ambient
+ * ADR-0013 D3 env constant. Set via `configureEmbedHostIdleGraceMs()` (which
+ * `createEmbeddingProvider()` calls with `EmbeddingProviderConfig.idleGraceMs`)
+ * before the host is spawned.
+ */
+let _idleGraceOverride = null;
+/**
+ * The internal cross-process transport variable the spawner uses to hand the
+ * resolved `EmbedHostConfig.idleGraceMs` to the spawned host. Not a public knob
+ * — set the typed `idleGraceMs` instead.
+ */
+export const EMBED_HOST_IDLE_GRACE_ENV = 'SOX_EMBED_HOST_IDLE_GRACE_MS';
+/**
+ * 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;
+}
+/**
+ * Apply the typed `idleGraceMs` field from an `EmbeddingProviderConfig`. Passing
+ * `undefined` leaves the current value unchanged (so a provider without the field
+ * never resets a deliberate selection). A non-positive or non-finite value is
+ * rejected loudly — never silently treated as "off".
+ */
+export function configureEmbedHostIdleGraceMs(idleGraceMs) {
+    if (idleGraceMs === undefined)
+        return;
+    if (!Number.isFinite(idleGraceMs) || idleGraceMs <= 0) {
+        throw new TypeError(`EmbedHostConfig.idleGraceMs must be a positive number, got ${String(idleGraceMs)}`);
+    }
+    _idleGraceOverride = idleGraceMs;
+}
+/** TEST-ONLY: clear the process-wide host + idle-grace overrides back to defaults. */
+export function __resetEmbedHostConfigForTests() {
+    _hostOverride = null;
+    _idleGraceOverride = null;
+}
+/**
+ * Resolve the funnel configuration. `host` defaults to `'shared'`; `idleGraceMs`
+ * is typed config (with the transport env / hard default as fallbacks). The
+ * SPAWNER reads the resolved `idleGraceMs` and forwards it to the spawned host —
+ * see `funnelClient.ts`'s `doEnsure()` — which is what makes this field the
+ * consumed surface rather than a dead declaration.
+ */
+export function resolveEmbedHostConfig() {
+    return {
+        host: _hostOverride ?? 'shared',
+        socketDir: resolveEmbedHostSocketDir(),
+        idleGraceMs: resolveEmbedHostIdleGraceMs(),
+    };
+}
+/**
+ * Resolve the idle grace, in priority order:
+ *
+ *   1. the typed override (`configureEmbedHostIdleGraceMs()` /
+ *      `EmbeddingProviderConfig.idleGraceMs`) — the public surface;
+ *   2. the internal transport env (`SOX_EMBED_HOST_IDLE_GRACE_ENV`) the spawner
+ *      writes for the spawned host;
+ *   3. `DEFAULT_EMBED_HOST_IDLE_GRACE_MS`.
+ *
+ * A non-positive or non-numeric transport value is rejected loudly (never
+ * silently treated as "off").
+ */
+export function resolveEmbedHostIdleGraceMs() {
+    if (_idleGraceOverride !== null)
+        return _idleGraceOverride;
+    const raw = process.env[EMBED_HOST_IDLE_GRACE_ENV];
+    if (raw === undefined || raw === '')
+        return DEFAULT_EMBED_HOST_IDLE_GRACE_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new TypeError(`${EMBED_HOST_IDLE_GRACE_ENV} 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,59 @@
+/**
+ * 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);
+ *   - `inFlight` — THIS host's own request depth, incremented synchronously at
+ *     the top of every handler invocation and decremented in its `finally` (the
+ *     in-process half). It is deliberately NOT the private pool's
+ *     `pendingCount`: that counter is incremented only AFTER `ensureProcess()`
+ *     (the fork) resolves, so it reads 0 during a cold-start fork and would arm
+ *     a reap over live work. `inFlight` is the synchronous truth.
+ *
+ * `activeClients === 0 && inFlight === 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.
+ *
+ * ── The accessor is resolved at EVERY use, never captured ──────────────────────
+ *
+ * `embedding.reset` terminates AND nulls the private singleton
+ * (`resetPrivateFastembedProcess()`); a host that captured the accessor once
+ * would keep forwarding through the terminated reference and answer every later
+ * request with `shared fastembed process terminated`. Every use
+ * (the request handler, `armIfIdle`, `teardown`, `health`) therefore calls
+ * `getPrivateFastembedProcess()` fresh.
+ */
+/**
+ * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAyBH;;;;;GAKG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CA4HlD"}