@adhd/sox-embedding-provider 0.2.0 → 0.4.0

package/dist/sharedFastembedProcess.d.ts

@@ -15,12 +15,91 @@
  * process alive) but forks a child **process** instead of constructing a
  * `worker_threads.Worker`.
  */
-export declare class SharedFastembedProcessClient {
+/** TEST-ONLY: clear the TTL cache so a test can force a fresh fs read. */
+export declare function __resetCompetingHostCacheForTests(): void;
+/**
+ * Exported for direct unit testing (DEBT-EPIC-HOTPATH-REDUNDANT-IO-001) — see the
+ * TTL-cache doc comment above for why this used to be a per-call sync fs read.
+ *
+ * (BUG-MEMORY-EMBED-HEAD-OF-LINE-BLOCKING-001) `ownPoolGroup`, when supplied,
+ * suppresses a "competing host" result whose lock entry carries the SAME
+ * `poolGroup` — i.e. another member of this client's own `FastembedProcessPool`,
+ * not a genuinely unrelated fastembed host. Without this, the BL-432
+ * `competing_host_pid` telemetry field would read as permanently "contended"
+ * for every pooled request, which is exactly the false-positive noise BL-331's
+ * own postmortem warns against trusting.
+ */
+export declare function detectCompetingFastembedHost(ownPid: number | undefined, ownPoolGroup?: string): {
+    pid: number;
+    startedAt: string;
+} | null;
+/**
+ * (BUG-MEMORY-EMBED-HEAD-OF-LINE-BLOCKING-001) The structural shape both
+ * `SharedFastembedProcessClient` (one child) and `FastembedProcessPool`
+ * (N independent children) satisfy. `FastembedProvider` (fastembed.ts)
+ * depends on this interface, not the concrete single-child class, so
+ * `getSharedFastembedProcess()` can return either without callers caring —
+ * every existing `.request()`/`.terminate()`/`.started` call site keeps
+ * working unchanged.
+ */
+export interface SharedFastembedClient {
+    request<T = Record<string, unknown>>(payload: Record<string, unknown>, timeoutMs?: number, signal?: AbortSignal): Promise<T>;
+    terminate(): Promise<void>;
+    readonly started: boolean;
+}
+/**
+ * (BUG-MEMORY-EMBED-HEAD-OF-LINE-BLOCKING-001) Thrown by `FastembedProcessPool
+ * .request()` when every pool member already has `admissionLimit` or more
+ * requests in flight — the "a queue that never refuses hides its own
+ * failure" backstop the bug item asked for. This is NOT the primary fix (the
+ * pool itself is — see the class below); it exists purely so a burst that
+ * genuinely exceeds total pool capacity gets a fast, typed, retryable
+ * rejection instead of silently joining a multi-minute queue. Named
+ * `TransientEmbeddingError`-shaped (has `retryAfterMs`) but defined locally
+ * rather than importing from `./index.js`, to keep this module free of a
+ * dependency on the public interface skeleton — callers can duck-type on
+ * `.name === 'FastembedBusyError'` or `instanceof FastembedBusyError`.
+ */
+export declare class FastembedBusyError extends Error {
+    readonly retryAfterMs: number;
+    constructor(message: string, retryAfterMs: number);
+}
+export declare class SharedFastembedProcessClient implements SharedFastembedClient {
     private child;
     private startingPromise;
     private nextId;
     private pending;
     private readonly hostPath;
+    private readonly poolGroup;
+    private poolSize;
+    private memberIndex;
+    /**
+     * (BUG-021) The last `{ type: 'init', model, cacheDir }` payload this
+     * member has ever been asked to load — kept independently of any pool
+     * wrapper above it so a LONE (non-pooled) client is self-healing too.
+     * `null` until the first successful `init`.
+     */
+    private lastInitPayload;
+    /**
+     * (BUG-021 root cause) True once the CURRENT `this.child` has actually
+     * loaded the model named by `lastInitPayload`. Reset to `false` every time
+     * `ensureProcess()` forks a NEW child — including a transparent respawn
+     * after the previous child died (crash, OOM-kill, the BL-426/std::bad_alloc
+     * native-teardown hazards documented on `fastembedProcessHost.ts`, etc).
+     *
+     * Before this fix, `ensureProcess()`'s `c.on('exit')`/`c.on('error')`
+     * handlers nulled out `this.child`/`this.startingPromise` on an unexpected
+     * death, but nothing told the NEXT `request()` call that the freshly
+     * (re)forked replacement child has an empty `_embedder` — every real
+     * `embed`/`embedBatch` request sent to it failed with "Model not
+     * initialized" forever, because the higher-level `FastembedProvider.ready`
+     * flag was already latched `true` from the original (pre-crash) init and
+     * `ensureReady()` never re-sends `init` once `ready` is true. Live incident
+     * BUG-021: the lock file showed a child forked mere SECONDS before every
+     * request against it failed — exactly this respawn-without-reinit gap, not
+     * a stale/orphaned lock as first suspected.
+     */
+    private childInitialized;
     /**
      * @param hostPathOverride Test-only injection point (BL-410): points the
      * fork target at a lightweight fixture host instead of the real
@@ -28,10 +107,47 @@ export declare class SharedFastembedProcessClient {
      * contract without loading fastembed or downloading a model. Production
      * code (`getSharedFastembedProcess()`) never passes this — it always
      * resolves the real host path.
+     * @param poolGroup (BUG-MEMORY-EMBED-HEAD-OF-LINE-BLOCKING-001) Set by
+     * `FastembedProcessPool` to a group id shared by every member of that pool.
+     * Forwarded to the forked child via `SOX_FASTEMBED_POOL_GROUP` so the
+     * BL-331 advisory lock can tell "another member of my own pool" apart from
+     * "a genuinely unrelated fastembed host" — see `fastembedLock.ts`'s
+     * `poolGroup` doc comment. `undefined` for a lone (non-pooled) client,
+     * which preserves today's exact single-host lock behaviour there.
+     * @param poolSize / @param memberIndex (BUG-EMBED-POOL-SIZE-DARWIN-FREEMEM-001,
+     * observability addendum) Set by `FastembedProcessPool` so every
+     * `fastembed_process.request.*` telemetry record this client emits carries
+     * the pool's actual size and this member's index alongside `queue_depth`/
+     * `response_ms`. Diagnosing THIS incident required an agent to read source
+     * and reconstruct `resolveFastembedPoolSize()`'s arithmetic by hand,
+     * because no telemetry field ever recorded what size the pool actually
+     * resolved to at runtime — `queue_depth` alone cannot distinguish
+     * "contention on an inert 1-member pool" from "genuine over-capacity on a
+     * 4-member pool". `undefined` for a lone (non-pooled) client, which omits
+     * both fields from telemetry exactly as before this addendum.
      */
-    constructor(hostPathOverride?: string);
+    constructor(hostPathOverride?: string, poolGroup?: string, poolSize?: number, memberIndex?: number);
     /** True once the underlying child process has been forked. */
     get started(): boolean;
+    /**
+     * (BUG-MEMORY-EMBED-HEAD-OF-LINE-BLOCKING-001) Number of requests already
+     * admitted-and-unsettled on this specific child, i.e. how many are ahead
+     * of a hypothetical next request. Exposed read-only so `FastembedProcessPool`
+     * (below) can route a new request to whichever pool member is least loaded
+     * — the exact `this.pending.size` value `request()` already measures
+     * internally for the `queue_depth` telemetry field, just made visible to a
+     * caller one level up instead of re-derived.
+     */
+    get pendingCount(): number;
+    /**
+     * (BL-575) Update the `pool_size`/`member_index` telemetry fields this
+     * client stamps on every `fastembed_process.request.*` record. Package-
+     * private (no `readonly`) specifically so `AdaptiveFastembedProcessPool`
+     * can keep them truthful as the pool grows/shrinks at runtime — a FIXED
+     * `FastembedProcessPool` never calls this (its size is constant for the
+     * member's whole lifetime, set once at construction).
+     */
+    setPoolMeta(poolSize: number, memberIndex: number): void;
     /** Lazily fork (exactly once) and return the single shared child process. */
     private ensureProcess;
     /**
@@ -76,8 +192,24 @@ export declare class SharedFastembedProcessClient {
      *   3. `competing_host_pid` — present only when a second, still-live
      *      `fastembedProcessHost` process is detected (BL-331's advisory lock),
      *      since that changes embed latency 25-50x independent of queueing.
+     *
+     * BL-576: `signal`, when supplied, is an external cancellation source —
+     * e.g. `operation-guard.ts`'s `withOperationDeadline` abort controller, so
+     * a deadline that fires while an embed is queued behind an unrelated slow
+     * request stops WAITING on it immediately rather than riding the deadline
+     * out via its own separate mechanism. This does NOT kill the underlying
+     * fastembed child mid-inference (the same "no native cancellation
+     * primitive" constraint `operation-guard.ts` documents applies here too —
+     * the child process is shared across other pending requests, so killing
+     * it on one caller's abort would collaterally fail every other in-flight
+     * request on that member) — it settles the CALLER's promise immediately
+     * with an `AbortError` and removes the pending entry so a late reply from
+     * the child (once the real work finishes) is silently dropped instead of
+     * resolving/rejecting a promise nobody is awaiting anymore. If `signal`
+     * is already aborted when `request()` is called, it rejects immediately
+     * without ever sending to the child.
      */
-    request<T = Record<string, unknown>>(payload: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+    request<T = Record<string, unknown>>(payload: Record<string, unknown>, timeoutMs?: number, signal?: AbortSignal): Promise<T>;
     /**
      * Terminate the shared fastembed process. Intended ONLY for full process
      * shutdown or test teardown that genuinely owns the whole process's
@@ -95,14 +227,277 @@ export declare class SharedFastembedProcessClient {
      */
     terminate(): Promise<void>;
 }
+/**
+ * (BUG-EMBED-POOL-SIZE-DARWIN-FREEMEM-001) Estimate REAL available memory
+ * (MB), platform-aware — the input `resolveFastembedPoolSize()`'s
+ * memory-cap arithmetic below actually needs, as opposed to what
+ * `os.freemem()` alone reports.
+ *
+ * `os.freemem()` is not a usable proxy for "memory this process could
+ * actually claim" on macOS: it maps to Mach's raw "free" page count only,
+ * which deliberately EXCLUDES "inactive"/"speculative"/"purgeable" pages —
+ * pages the kernel is using as disk cache but will hand back instantly
+ * (zero swap-in cost) under real pressure. Measured via `vm_stat` on the
+ * exact box this defect was diagnosed on (32GB physical, page size 16384):
+ * `os.freemem()` reported ~299MB while `Pages inactive` ALONE was 345,579
+ * pages (~5.4GB) — the overwhelming majority of genuinely-available memory
+ * was invisible to the metric `resolveFastembedPoolSize()` used to
+ * compute `memoryCap`. Because `MEMORY_SAFETY_MARGIN_MB` (1024) routinely
+ * exceeds `os.freemem()`'s ~300MB-ish reading on macOS regardless of real
+ * load, `memoryCap` collapsed to `Math.max(1, negative) === 1` on every
+ * macOS box, unconditionally — the pool was permanently INERT (silently
+ * behaving exactly like the pre-fix single-child topology) unless an
+ * operator manually overrode `SOX_EMBED_POOL_SIZE`. `hol-pool-sizing.spec.ts`
+ * even self-documents "this suite was itself first run on a box with only
+ * ~128MB free" — the sizing design was validated against the very macOS
+ * quirk that made it universally wrong, not a genuinely memory-constrained
+ * machine.
+ *
+ * Fix: compute "available" as free + inactive + speculative + purgeable
+ * pages (the standard macOS "reclaimable without swapping" heuristic —
+ * matches what `htop`-family tools approximate; NOT Apple's undocumented
+ * memory-pressure internals, which have no public API). On Linux,
+ * `/proc/meminfo`'s `MemAvailable` is already the kernel's own equivalent
+ * estimate and is used directly. Any other platform, or any parse/exec
+ * failure, falls back to `os.freemem()` unchanged — this must never throw
+ * or block pool sizing on a shell-out failing; it runs once per process
+ * (at `getSharedFastembedProcess()` construction), never per-request.
+ */
+export declare function estimateAvailableMemMb(): number;
+/**
+ * (BL-575) The explicit `SOX_EMBED_POOL_SIZE` override, if set — a HARD PIN.
+ * Split out of `resolveFastembedPoolSize()` so `getSharedFastembedProcess()`
+ * can tell "operator pinned an exact size" (disables ALL adaptation —
+ * `AdaptiveFastembedProcessPool` is never constructed) apart from "no
+ * override, compute a ceiling for adaptive sizing to grow toward" — the two
+ * cases used to be indistinguishable from the return value of a single
+ * function that already folded the CPU/memory-cap arithmetic into the
+ * "no override" branch.
+ */
+export declare function resolveFastembedPoolPin(): number | null;
+/**
+ * (BL-575) The maximum pool size the memory/CPU budget allows — i.e. what
+ * `resolveFastembedPoolSize()` used to compute unconditionally in its
+ * "no override" branch. Now used two ways: (a) unchanged, as
+ * `resolveFastembedPoolSize()`'s own fallback when no pin is set, so every
+ * existing caller of that function keeps its exact prior behavior; (b) as
+ * `AdaptiveFastembedProcessPool`'s `maxSize` — the ceiling it is allowed to
+ * grow toward under sustained load, never exceeded regardless of how
+ * sustained the demand is.
+ *
+ * Auto-sized from BOTH real available memory (`estimateAvailableMemMb()` —
+ * see its doc comment for why this is NOT simply `os.freemem()`, and
+ * BUG-EMBED-POOL-SIZE-DARWIN-FREEMEM-001 for the incident this fixes —
+ * against `DEFAULT_PER_MEMBER_MB`, less `MEMORY_SAFETY_MARGIN_MB` headroom —
+ * override the per-member budget via `SOX_EMBED_POOL_PER_CHILD_MB` for a
+ * non-default model) AND CPU count (half the logical CPUs, cap 4 — fastembed
+ * inference is CPU/ANE-bound per request, not embarrassingly parallel across
+ * all cores), taking the SMALLER of the two so a memory-constrained box
+ * never gets sized past what's actually free. See the module doc comment
+ * above for the measurement (footprint/vmmap on 1 vs 4 real children) that
+ * justifies this.
+ *
+ * @param getAvailableMemMb Test-only injection point — production always
+ * uses the default `estimateAvailableMemMb`. Lets tests exercise the sizing
+ * arithmetic against deterministic MB values instead of the real, inherently
+ * machine/moment-dependent OS memory state.
+ */
+export declare function resolveFastembedPoolCeiling(getAvailableMemMb?: () => number): number;
+/**
+ * Number of independent fastembed child processes a FIXED (non-adaptive)
+ * pool should use. Preserved unchanged for backward compatibility (existing
+ * callers/tests) — `SOX_EMBED_POOL_SIZE` honored exactly if set
+ * (`resolveFastembedPoolPin()`), else the memory/CPU ceiling
+ * (`resolveFastembedPoolCeiling()`). `getSharedFastembedProcess()` itself no
+ * longer calls this for its default (adaptive) path as of BL-575 — see
+ * `resolveFastembedPoolPin`/`resolveFastembedPoolCeiling`'s doc comments.
+ *
+ * @param getAvailableMemMb Test-only injection point, forwarded to
+ * `resolveFastembedPoolCeiling`.
+ */
+export declare function resolveFastembedPoolSize(getAvailableMemMb?: () => number): number;
+/** Per-member in-flight cap above which `FastembedProcessPool.request()` fast-rejects
+ *  a non-init request with `FastembedBusyError` instead of enqueuing. Disabled
+ *  (`Infinity`) by default — see the pool doc comment above for why. Override
+ *  via `SOX_EMBED_POOL_ADMISSION_LIMIT` (a finite number opts in). */
+export declare function resolveFastembedAdmissionLimit(): number;
+/**
+ * A pool of `size` independent `SharedFastembedProcessClient`s — i.e. `size`
+ * independent fastembed-hosting OS child processes, each fully isolated from
+ * the others (preserving BL-238's process-isolation requirement) — routing
+ * each request to whichever member currently has the fewest requests in
+ * flight. See the module-level doc comment above for the full rationale and
+ * the production measurements this fixes.
+ */
+export declare class FastembedProcessPool implements SharedFastembedClient {
+    readonly members: SharedFastembedProcessClient[];
+    private readonly admissionLimit;
+    /**
+     * (BUG-MEMORY-EMBED-HEAD-OF-LINE-BLOCKING-001) Routing/admission MUST NOT
+     * read `member.pendingCount` for the decision — that counter is only
+     * incremented deep inside `SharedFastembedProcessClient.request()`, AFTER
+     * its own `await this.ensureProcess()`, i.e. at least one microtask tick
+     * after the call starts. Several callers issued in the same synchronous
+     * burst (`Promise.all(callers.map(() => pool.request(...)))`, the exact
+     * shape a real caller under load produces) all run their OWN synchronous
+     * prefix — including this pool's `leastLoaded()`/admission check — before
+     * ANY of them reaches that tick, so every one of them would read
+     * `pendingCount === 0` for every member and pile onto `members[0]`,
+     * silently defeating both load-balancing and admission control for
+     * exactly the bursty-arrival case this fix exists for. `inFlight` is
+     * incremented SYNCHRONOUSLY the instant a member is chosen (before any
+     * `await`), so the very next synchronous call in the same burst already
+     * sees it.
+     */
+    private readonly inFlight;
+    /** Cached so a member added to routing after the first `init` (there is
+     *  none today — pool size is fixed at construction — but kept so a future
+     *  dynamic-resize doesn't silently skip initializing a new member) can be
+     *  brought up to date. Also lets `request()` short-circuit a redundant
+     *  broadcast if the model/cacheDir haven't changed. */
+    private lastInitPayload;
+    constructor(size: number, hostPathOverride?: string, admissionLimit?: number);
+    /** True once at least one member has forked its child process. */
+    get started(): boolean;
+    /** The last `{ type: 'init', model, cacheDir }` payload broadcast to every
+     *  member, or `null` before the first init. Exposed for introspection/tests
+     *  only — `request()` itself doesn't need to read this back today (pool
+     *  size is fixed at construction, so every member is always initialized by
+     *  the broadcast), it's retained purely so a future dynamic-resize path has
+     *  the payload on hand to bring a newly-added member up to date. */
+    get lastInit(): Record<string, unknown> | null;
+    /** Sum of in-flight requests across every member — the pool-wide
+     *  head-of-line depth an arriving caller would experience. */
+    get pendingCount(): number;
+    /** Index of the least-loaded member by the SYNCHRONOUS `inFlight` counter
+     *  — see that field's doc comment for why `member.pendingCount` itself is
+     *  unsafe to read here. */
+    private leastLoadedIndex;
+    request<T = Record<string, unknown>>(payload: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+    terminate(): Promise<void>;
+}
+export interface AdaptiveFastembedPoolOptions {
+    /** Starting (and floor) pool size. Default 1 — the topology real
+     *  measurement shows wins at concurrency <20. */
+    minSize?: number;
+    /** Ceiling the pool may grow to — pass `resolveFastembedPoolCeiling()`'s
+     *  result in production; never exceeded regardless of how sustained
+     *  demand is. */
+    maxSize: number;
+    hostPathOverride?: string;
+    admissionLimit?: number;
+    /** Test-only clock injection — production uses `Date.now`. */
+    now?: () => number;
+    /** Hysteresis knobs — all optional, defaulting to the values documented
+     *  above. Exposed so a test can use tiny thresholds/intervals instead of
+     *  waiting out real minutes-scale windows, and so an operator can tune
+     *  the policy without a rebuild if the defaults prove wrong for their
+     *  traffic shape. Production (`getSharedFastembedProcess()`) never
+     *  overrides any of these — it relies on the documented defaults. */
+    growQueueRatioThreshold?: number;
+    growSustainCount?: number;
+    /** (BL-575 hysteresis fix, post-ship) Minimum WALL-CLOCK span the
+     *  over-threshold streak must cover before a grow is allowed to fire —
+     *  see `growSustainWindowMs`'s own doc comment on the field below for why
+     *  `growSustainCount` alone was not sufficient. */
+    growSustainWindowMs?: number;
+    growCooldownMs?: number;
+    shrinkIdleMs?: number;
+    shrinkCheckIntervalMs?: number;
+}
+export declare class AdaptiveFastembedProcessPool implements SharedFastembedClient {
+    private members;
+    private inFlight;
+    private readonly minSize;
+    private readonly maxSize;
+    private readonly hostPathOverride;
+    private readonly admissionLimit;
+    private readonly poolGroup;
+    private readonly clock;
+    private readonly shrinkTimer;
+    private readonly growQueueRatioThreshold;
+    private readonly growSustainCount;
+    private readonly growSustainWindowMs;
+    private readonly growCooldownMs;
+    private readonly shrinkIdleMs;
+    private lastInitPayload;
+    private growConsecutiveOverThreshold;
+    /** Wall-clock timestamp the CURRENT over-threshold streak began — `null`
+     *  when not currently in a streak. See `GROW_SUSTAIN_WINDOW_MS`'s doc
+     *  comment for why a count alone is insufficient. */
+    private growStreakStartedAt;
+    private lastGrowAt;
+    private idleSinceMs;
+    /** Serializes concurrent grow attempts — `request()` can observe the
+     *  over-threshold condition from several concurrent callers in the same
+     *  burst; only one grow should actually happen. */
+    private growInFlight;
+    private terminated;
+    /** Counts of grow/shrink actions taken — exposed for tests/observability,
+     *  not consumed by any routing logic. */
+    growCount: number;
+    shrinkCount: number;
+    constructor(opts: AdaptiveFastembedPoolOptions);
+    get started(): boolean;
+    get lastInit(): Record<string, unknown> | null;
+    get pendingCount(): number;
+    /** Current pool size — exposed for tests/observability. */
+    get size(): number;
+    private leastLoadedIndex;
+    /** Renumber every member's `pool_size`/`member_index` telemetry fields to
+     *  match current pool composition — called after every grow/shrink so
+     *  `fastembed_process.request.*` records stay truthful. */
+    private renumberMembers;
+    /**
+     * Attempt to add one member, up to `maxSize`. Best-effort and internally
+     * serialized (`growInFlight`) — safe to call from multiple concurrent
+     * `request()` admissions without double-growing. If a `lastInitPayload`
+     * exists (the pool has already been initialized with a model), the new
+     * member is sent the SAME init payload before being added to routing —
+     * an un-initialized member would fail every real embed request it was
+     * routed to.
+     */
+    private grow;
+    /** Periodic shrink check — terminates exactly ONE idle member if the
+     *  entire pool has been continuously idle for `SHRINK_IDLE_MS`. Never
+     *  shrinks below `minSize`. Resets the idle clock after shrinking so a
+     *  demand spike right after only costs one re-grow step, not a full
+     *  rebuild, and so consecutive shrinks are still spaced `SHRINK_IDLE_MS`
+     *  apart (the same conservative cadence, not a rapid drain to `minSize`). */
+    private maybeShrink;
+    request<T = Record<string, unknown>>(payload: Record<string, unknown>, timeoutMs?: number, signal?: AbortSignal): Promise<T>;
+    terminate(): Promise<void>;
+}
 /**
  * Process-wide singleton accessor — the ONLY sanctioned place a fastembed
  * child process is forked anywhere in `@adhd/sox-embedding-provider`
  * (BL-238/BL-171). Every `FastembedProvider` obtains its handle through this
  * function instead of constructing its own `worker_threads.Worker` or
  * `child_process`.
+ *
+ * (BL-575) Two shapes, chosen by whether `SOX_EMBED_POOL_SIZE` is set:
+ *
+ *   - PINNED (`resolveFastembedPoolPin()` returns non-null): a FIXED
+ *     `FastembedProcessPool` at exactly that size, no adaptation — an
+ *     operator who set this has already judged their model's footprint and
+ *     the box's headroom; adaptive sizing would second-guess that judgement.
+ *   - DEFAULT (no override): an `AdaptiveFastembedProcessPool` starting at
+ *     `minSize: 1` (the topology real measurement shows wins below ~20
+ *     concurrency) and growing toward `resolveFastembedPoolCeiling()` (the
+ *     SAME ceiling `FastembedProcessPool` used to apply unconditionally)
+ *     only under sustained demand — see that class's doc comment for the
+ *     full measurement and hysteresis policy (BUG-MEMORY-EMBED-HEAD-OF-LINE-
+ *     BLOCKING-001's original qdepth-11+ production regime is exactly the
+ *     sustained-demand case this still grows to meet; the difference is it
+ *     no longer pays that pool's cost on every LOWER-concurrency request
+ *     too).
+ *
+ * Every existing caller keeps working unchanged either way — both classes
+ * implement the same `SharedFastembedClient` shape (`request()`/
+ * `terminate()`/`started`). Setting `SOX_EMBED_POOL_SIZE=1` recovers the
+ * exact pre-BL-575 (and pre-pool) single-child topology.
  */
-export declare function getSharedFastembedProcess(): SharedFastembedProcessClient;
+export declare function getSharedFastembedProcess(): SharedFastembedClient;
 /**
  * Test-only: reset the module-level singleton so a test can exercise a
  * fresh shared-process lifecycle (e.g. after deliberately crashing/

package/dist/sharedFastembedProcess.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sharedFastembedProcess.d.ts","sourceRoot":"","sources":["../src/sharedFastembedProcess.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAsFH,qBAAa,4BAA4B;IACvC,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,eAAe,CAAsC;IAC7D,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAE9C;;;;;;;OAOG;gBACS,gBAAgB,CAAC,EAAE,MAAM;IAIrC,8DAA8D;IAC9D,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,6EAA6E;IAC7E,OAAO,CAAC,aAAa;IAyErB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,aAAa;IAKrB,gFAAgF;IAChF,OAAO,CAAC,WAAW;IAOnB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC;IA6Db;;;;;;;;;;;;;;OAcG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CA2BjC;AAOD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,IAAI,4BAA4B,CAGxE;AAED;;;;;;GAMG;AACH,wBAAgB,qCAAqC,IAAI,IAAI,CAE5D"}
+{"version":3,"file":"sharedFastembedProcess.d.ts","sourceRoot":"","sources":["../src/sharedFastembedProcess.ts"],"names":[],"mappings":"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"}