Distillation

Date: Sep 16, 2026

• 🔴 (13:47) User stated cgroup membership and mount discovery must be re-read from /proc/self/cgroup and /proc/self/mountinfo so a worker is never admitted from a stale cgroup directory or a cached discovery miss.
• 🔴 (13:47) User stated every descendant cgroup boundary must remain readable so sibling usage is never subtracted from the wrong scope; the cgroup v2 root is the sole exception because it cannot itself be resource-controlled and may omit memory.current, memory.high, and memory.max.
• 🔴 (13:47) packages/core/src/cgroup-memory.ts supports cgroup v1 and v2 memory discovery. On hybrid hosts it prefers the explicit v1 memory controller over the unified v2 hierarchy; direct mount matches are sorted by longest root, while a namespaced interpretation is accepted only when exactly one candidate exists.
• 🔴 (13:47) decodeProcPath() in packages/core/src/cgroup-memory.ts decodes octal procfs escapes, rejects paths that are not absolute, contain a NUL byte, or include a .. segment, then normalizes with posix.normalize().
• 🔴 (13:47) readLinuxCgroupMemoryHeadroomBytes() reads cgroup v2 usage from memory.current and limits from both memory.high and memory.max; for cgroup v1 it reads memory.usage_in_bytes and memory.limit_in_bytes. It walks from the process cgroup directory toward the mount point and returns the tightest finite nonnegative limit - usage headroom, or undefined when discovery or required reads are unsafe.
• 🔴 (13:47) packages/core/src/embedding/local.ts resolves available memory using process.constrainedMemory(), Linux cgroup headroom from readLinuxCgroupMemoryHeadroomBytes(), and—where supported—process.availableMemory(). Bun does not trust its runtime available-memory value because it currently aliases host freemem() inside constrained cgroups; Node’s libuv implementation is treated as process-limit-aware.
• 🔴 (13:47) Embedding-cap persistence uses key lore:embedding_cap in kv_meta, storing cap, freeMemBytes, and optional positive knownBadCap; persistence is best-effort, and failures cause the cap to be re-derived on the next start.
• 🔴 (13:47) User stated legacy embedding-pool configuration resolution must preserve invalid-value fall-through: invalid environment configuration resolves to undefined, never NaN, and this must be testable without spinning up workers.
• 🔴 (13:47) User stated the embedding pool’s primary worker is always present; its own OOM backoff, rather than pool sizing, governs its lifecycle.
• 🔴 (13:47) During transient embedding-worker failure debt, new work is routed only to proven sibling workers.
• 🔴 (13:47) The embedding pool limits MAX_WAITERS_PER_EMBED_OPERATION to 64.
• 🔴 (13:48) User stated the adaptive embedding token cap never exceeds the Nomic v1.5 maximum sequence length.
• 🔴 (13:48) reconcileEmbedCap() must bound every return path by EMBED_TOKEN_CEILING, not only the model-derived path; knownBadCap is a hard persisted bound representing a cap that previously OOMed, and reprobe logic must never yield a cap above it even when given an above-ceiling input cap.
• 🔴 (13:48) Embedding memory modeling uses EMBED_POOL_BUDGET_REF_TOKENS = 2048; comments identify an npm/WASM fixed 4 GiB heap constraint and a practical cap of at most 4962 tokens for that path.