Distillation

Date: Sep 16, 2026

• 🔴 (23:52) User stated stale events from a retired embedding worker, including during a WASM fallback respawn, must never clobber the fresh worker state.
• 🔴 (23:52) User stated embedding-worker recovery must never loop unbounded or create an event storm; the relevant recovery path is FTS-only.
• 🔴 (23:52) User stated upward embedding-cap re-probing must account for memory across workers so that N workers can never sum past the host’s RAM.
• 🔴 (23:52) User stated an embedding cap that caused an OOM must be remembered so upward re-probing never climbs back to that failed cap.
• 🔴 (23:53) User stated the primary embedding worker is always present; its own OOM backoff, rather than pool sizing, governs its recovery.
• 🟡 (23:53) packages/core/src/embedding/pool.ts defines MAX_NORMAL_QUEUED_EMBED_OPERATIONS = 240 and maxBatchSize = 256.
• 🟡 (23:53) packages/core/src/embedding/pool.ts worker admission behavior: deterministic test overrides bypass the memory gate; the primary worker is retained; exactly one recovery probe is admitted after cooldown; after bootstrap succeeds, additional pool growth remains lazy and memory-gated; free memory is constrained through clampFreeToContainerLimit(raw, constrained, headroom).
• 🟡 (23:53) runOperation() in packages/core/src/embedding/pool.ts deliberately omits every caller’s AbortSignal when invoking slot.provider.embed(...): the operation owns the worker slot until native inference settles, while callers own only their waiters. It races inference against a watchdog, arms separate "init" and "execution" watchdog phases, records slot success, optionally clones and retains vectors for an operation with no remaining waiters, and retires the slot after LocalProviderUnavailableError or EmbeddingWorkerWatchdogError.
• 🟡 (23:53) dispatch() in packages/core/src/embedding/pool.ts will not replace the last active worker or grow the pool while a retired worker still owns its native model/heap; specifically, dispatch pauses when this.slots.length === 0 && this.retiredWorkers.size > 0, and retirement completion re-enters dispatch.
• 🟡 (23:53) dispatch() drops queued operations with no waiters, schedules retry dispatch on EmbeddingWorkerRetryCooldownError, rejects other slot-selection failures with the owned error or LocalProviderUnavailableError, and only runs a selected slot when slot.inflight === 0.
• 🟡 (23:53) embed() in packages/core/src/embedding/pool.ts rejects already-aborted calls with EmbeddingRequestAbortedError, rejects calls after closing with LocalProviderUnavailableError("embedding pool is unavailable"), copies input via texts.slice(), deduplicates operations using embeddingOperationKey(ownedTexts, inputType), assigns recall embeds "high" priority and others "normal" priority, measures queued input using Buffer.byteLength(text), and rejects capacity overflow with EmbeddingQueueCapacityError.
• 🟡 (23:53) shutdown(timeoutMs = WORKER_SHUTDOWN_TIMEOUT_MS) in packages/core/src/embedding/pool.ts is idempotent via shutdownPromise; it closes the pool, clears retry dispatch, rejects all waiters with LocalProviderUnavailableError("embedding pool shut down"), clears queued text/vector/checkpoint state, shuts down active providers with Promise.allSettled, waits for retired workers through retiredWorkers.settle(), and throws AggregateError(..., "embedding worker termination was not confirmed") if any termination cannot be confirmed.