Distillation

Date: Sep 17, 2026

• 🔴 (09:49) User requires embedding telemetry to never break the embedding path; fireEmbeddingFailure() in packages/core/src/embedding/local.ts invokes the optional hook inside try/catch, swallowing telemetry-hook failures.
• 🔴 (09:49) User specified worker-entrypoint runtime behavior in packages/core/src/embedding/local.ts: CJS uses __filename (always defined), while ESM uses import.meta.url.
• 🔴 (09:49) User stated the gateway CJS bundle’s __filename is always defined; its build shim in packages/gateway/script/bundle.ts keeps the source natural.
• 🔴 (09:49) User stated the deterministic fake-worker test seam in packages/core/src/embedding/local.ts is never set in production.
• 🔴 (09:49) User requires stale worker events—such as asynchronous exit(1) from terminating the native worker during WASM fallback—to never clobber the fresh replacement worker; handlers are bound to their own spawned worker and must early-return after this.worker advances to a new generation.
• 🟡 (09:49) respawnForWasm() in packages/core/src/embedding/local.ts explicitly resets this.workerReady = false before ensureWorker() so the fresh WASM worker actually spawns and pending requests are not lost; retired native workers remain owned through shutdown via trackRetiredWorkerTermination().
• 🟡 (09:49) WASM fallback does not wait for slow native teardown, but final shutdown must join retired workers and fail closed if exit cannot be confirmed. settleRetiredWorkers() uses timeout message "retired embedding worker did not settle before shutdown deadline" and failure message "embedding worker termination was not confirmed".
• 🟡 (09:49) respawnForWasm() rejects all pending requests with LocalProviderUnavailableError("embedding worker respawn failed after WASM fallback") if synchronous respawn fails; after successful respawn it refreshes every pending payload’s maxTokens via effectiveMaxTokens() before resubmission.
• 🟡 (09:49) packages/core/src/embedding/local.ts persists adaptive-cap state under EMBED_CAP_KV_KEY = "lore:embedding_cap" in kv_meta; malformed or inaccessible persisted data returns null, and persistence failures are best-effort because the cap can be re-derived at next startup.
• 🟡 (09:49) Local input handling uses LOCAL_MAX_CHARS = MODEL_MAX_TOKENS * 4, truncates without splitting a UTF-16 surrogate pair, then prefixes text with "search_document: " or "search_query: "; single query-type recall embeddings receive "high" priority and other work receives "normal" priority.
• 🟡 (09:49) Each embed request recomputes maxTokens with effectiveMaxTokens() using current memory conditions because sibling workers and live sessions can reduce free memory, and native over-allocation can cause an uncatchable SIGKILL rather than a recoverable worker OOM.
• 🟡 (09:49) availableMemoryHeadroom() in packages/core/src/embedding/local.ts treats Bun specially because Bun currently aliases host freemem() inside constrained cgroups; Node’s libuv implementation is process-limit-aware. Linux cgroup headroom is read with readLinuxCgroupMemoryHeadroomBytes(), and process.availableMemory() failures fall back through resolveMemoryHeadroom().
• 🟡 (09:49) Transient local-worker initialization failures increment initFailures and initFailureGeneration, retry a fresh worker after computeInitRetryDelayMs(), and leave recall FTS-only during cooldown; reaching LOCAL_INIT_MAX_ATTEMPTS latches "transient-init-exhausted" and recommends configuring search.embeddings.provider in .lore.json.
• 🟡 (09:49) shutdown() in packages/core/src/embedding/local.ts is idempotent through shutdownPromise, rejects in-flight requests with LocalProviderUnavailableError("embedding worker shut down"), awaits both the active worker and retired workers with Promise.allSettled(), and throws an AggregateError when multiple termination confirmations fail.
• 🟡 (09:49) packages/core/test/embedding-cap.test.ts constrains EMBED_TOKEN_CEILING to be below MODEL_MAX_TOKENS, greater than 4000, and at most 5200, with commentary identifying observed safe convergence as ≤4962; memoryModelEmbedCap() must return that ceiling for free-memory inputs of 16, 32, 64, and 256 GiB.
• 🟡 (09:49) shouldReprobeEmbedCap() boundary tests require true at 1.3× and 2× learn-time memory, false at 1.29× and 1×, and always false for non-positive learn-time baselines (0 and -1).
• 🟡 (09:49) reprobeEmbedCap() tests require an upward step of Math.round(cap / 0.7) when memory permits, no downward step when the current cap exceeds the current memory-model result, and self-bounding to EMBED_TOKEN_CEILING when passed stale MODEL_MAX_TOKENS.
• 🟡 (09:49) desiredEmbedPoolSize() tests require: minimum 1; default maximum DEFAULT_MAX_EMBED_POOL (2) once two PER_WORKER_MEM_BUDGET_BYTES budgets fit; explicit configured limits such as 4; flooring fractional configuration 3.9 to 3; absolute bounding by EMBED_POOL_ABS_MAX; and memory-gating configured limits to the number of complete worker budgets that fit.