Distillation

Date: Sep 17, 2026

• 🔴 (09:50) User requires promise rejections triggered while deterministically driving fake embedding workers to be handled immediately and never flagged as "unhandled"; settle<T>() in packages/core/test/embedding-oom-recovery.test.ts attaches success and rejection handlers as soon as the promise is created.
• 🟡 (09:50) packages/core/test/embedding-oom-recovery.test.ts defines FakeWorker extends EventEmitter, snapshots posted EmbedMsg payloads to prevent later in-place maxTokens mutations from retroactively changing captured messages, and exposes deterministic "message", "error", and "exit" events through _setTestWorkerFactory.
• 🟡 (09:50) OOM-recovery tests force the local provider by deleting VOYAGE_API_KEY and OPENAI_API_KEY, set _setConstrainedMemoryForTest(0) and _setContainerFreeForTest(16 * 1024 * 1024 * 1024), and restore provider state, environment variables, worker factory, memory seams, and local-provider probe state after each test.
• 🟡 (09:50) Live OOM-backoff test in packages/core/test/embedding-oom-recovery.test.ts persists stale cap 8192 with freeMemBytes=0, verifies the initial request uses EMBED_TOKEN_CEILING, emits EMBED_OOM_EXIT_CODE, and verifies a fresh worker receives the same request ID at backoffEmbedCap(EMBED_TOKEN_CEILING); the lowered cap is persisted through _readPersistedEmbedCap(), and the original promise resolves after the replacement worker returns one vector.
• 🟡 (09:50) OOM-at-floor test persists MIN_EMBED_TOKENS, verifies an OOM does not spawn another worker, rejects the pending request with LocalProviderUnavailableError, and makes isAvailable() return false, degrading recall to FTS-only.
• 🟡 (09:50) Synchronous-respawn-failure test makes the second _setTestWorkerFactory() invocation throw Error("synthetic spawn failure"); it verifies exactly 2 spawn calls and rejection of the pending request with LocalProviderUnavailableError.
• 🟡 (09:50) Full OOM-ladder test repeatedly emits EMBED_OOM_EXIT_CODE for at most 30 iterations, requires caps to be monotonically non-increasing, bottoms out at MIN_EMBED_TOKENS, then latches without respawning, rejects with LocalProviderUnavailableError, and leaves isAvailable() false.
• 🟡 (09:50) Worker stderr-silence test verifies every spawn snapshots the live host isStderrSilenced() state into workerData.stderrSilenced; after silenceStderr(true), the worker factory must observe true so worker [lore] OOM output cannot corrupt the host TUI.
• 🟡 (09:50) packages/core/test/embedding-cap-persistence.test.ts verifies lore:embedding_cap persistence: absent rows return null; cap 1234 round-trips with positive freeMemBytes; cap 500 overwrites 1000 through ON CONFLICT; corrupt JSON and JSON missing required fields return null; { cap: 1000, freeMemBytes: 4 GiB, knownBadCap: 3000 } round-trips; knownBadCap is omitted for 0/undefined and ignored when non-positive or non-numeric.
• 🔴 (09:50) User requires withSavepoint() names in packages/core/src/db.ts to be bare SQL identifiers because the name is interpolated into SQL and is never a bind parameter; /^[A-Za-z_][A-Za-z0-9_]*$/ rejects non-identifiers to prevent injection.
• 🟡 (09:50) withSavepoint<T>(name, fn) in packages/core/src/db.ts executes SAVEPOINT ${name}, releases on success, and on failure executes ROLLBACK TO ${name} followed by RELEASE ${name} before rethrowing. It is safe both standalone and nested, unlike withTransaction() using BEGIN IMMEDIATE, because SQLite permits nested savepoints but not nested BEGINs.
• 🟡 (09:50) checkConfigChange() in packages/core/src/embedding/backfill.ts re-reads the stored embedding fingerprint after write serialization to prevent a late process from clearing vectors another process rebuilt; it uses withSavepoint("embedding_config_reconcile", reconcile) when databaseInTransaction(db()) is true and withTransaction(reconcile) otherwise.
• 🟡 (09:50) Embedding-config reconciliation leaves the stored fingerprint unchanged when storage mode is "vec0" but the vec extension is unavailable, clears stale embeddings after a provider/model/dimension change, recreates vec0 storage when needed, calls resetTemporalRechunkProgress(), and stores the new ${provider}:${model}:${dimensions} fingerprint under lore:embedding_config.
• 🔴 (09:51) User requires embedding-cap reconciliation on a memory-rich reboot to never re-probe up to or past a persisted known-bad cap.
• 🔴 (09:51) User requires reprobeEmbedCap() to never re-probe up to or past a known-bad cap; knownBadCap - 1 acts as a hard upper boundary while gentler upward steps below that boundary remain unaffected.
• 🟡 (09:51) packages/core/src/embedding/local.ts seeds lastOomCap from persisted knownBadCap and persists the known-bad cap alongside the backed-off cap so the next process retains the OOM safety boundary.
• 🔴 (09:51) User requires resolveMemoryHeadroom() to always accept finite Node runtime headroom when no hard memory limit exists, including resolveMemoryHeadroom(Number.NaN, Number.NaN, 7 * GB) === 7 * GB.
• 🟡 (09:51) packages/core/src/embedding/local.ts adds _setAvailableMemoryForTest(bytes) and availableMemoryHeadroom(). The latter uses Linux readLinuxCgroupMemoryHeadroomBytes(), avoids Bun’s host-wide process.availableMemory() alias by calling resolveMemoryHeadroom(constrained, linuxHeadroom), uses Node’s process.availableMemory() when available, and falls back to resolveMemoryHeadroom(constrained, linuxHeadroom) if the API is absent or throws.
• 🟡 (09:51) containerFreeBytes() now calls clampFreeToContainerLimit(raw, constrainedMemoryLimit(), availableMemoryHeadroom()), incorporating current cgroup/runtime headroom rather than only the hard constrained-memory limit.
• 🟡 (09:51) Memory-headroom precedence tests include resolveMemoryHeadroom(12 * GB, 23 * MB, 7 * GB) === 23 * MB, requiring Linux cgroup headroom to take precedence over the broader Node runtime value when a constrained environment is detected.