Distillation

Date: Sep 16, 2026

• 🔴 (13:20) User-provided embedding-pool contract states the primary worker is always present; its own OOM backoff, rather than pool sizing, protects a constrained host, preserving the existing single-worker behavior.
• 🟡 (13:20) packages/core/src/embedding/pool.ts admission logic: liveFreemem() reads test override or freemem(), then obtains constrainedMemoryLimit() and availableMemoryHeadroom(); if the process is constrained but headroom is unknown, it returns 0, otherwise it calls clampFreeToContainerLimit(raw, constrained, headroom).
• 🟡 (13:20) packages/core/src/embedding/pool.ts burst-growth reservation requires liveFreemem() to cover (unhealthy slot count + 1) * PER_WORKER_MEM_BUDGET_BYTES, thereby charging memory for admitted workers that have not yet become healthy.
• 🟡 (13:20) packages/core/src/embedding/pool.ts passes the pool ceiling to each LocalProvider as its memory divisor, so each worker sizes its token cap from free / ceiling; the stated goal is keeping all provisioned workers collectively within one EMBED_MEM_FRACTION share rather than each independently claiming half of free memory.
• 🟡 (13:20) Candidate working copy tmzmtlss / commit e6d0f1ed was described as fix(core): correct embedding runtime selection and admission, based on parent pxrvwsvv / 2cbf4006 (main, feat(cch): add seeds for Claude Code up to 2.1.272 (#1780)).
• 🟡 (13:20) Candidate files were conflict-free, while the unrelated bookmark fix/responses-private-references had conflicts outside the candidate’s ancestry.
• 🟡 (13:20) Candidate changed 18 files: added packages/core/src/cgroup-memory.ts and packages/core/test/cgroup-memory.test.ts; modified packages/core/src/embedding/local.ts, packages/core/src/embedding/pool.ts, packages/core/src/embedding-cap.ts, packages/core/src/embedding-worker-types.ts, packages/core/src/embedding-worker.ts, packages/core/src/embedding.ts, packages/core/src/ort-native.ts, packages/core/test/embedding-cap.test.ts, packages/core/test/embedding-pool-memory.test.ts, packages/core/test/embedding-pool.test.ts, packages/core/test/embedding-worker-types.test.ts, packages/core/test/ort-native.test.ts, packages/gateway/script/bundle.ts, packages/gateway/script/ort-platform-package.ts, packages/gateway/test/bundle-exports.test.ts, and packages/gateway/test/ort-platform-package.test.ts.
• 🟡 (13:21) Candidate diff size was exactly 1818 insertions(+), 90 deletions(-) across 18 files; notable per-file additions included 205 lines in packages/core/src/cgroup-memory.ts, 297 in packages/core/test/cgroup-memory.test.ts, 256 in packages/core/src/ort-native.ts, 478 in packages/core/test/ort-native.test.ts, and 246 in packages/gateway/test/bundle-exports.test.ts.
• 🟡 (13:21) Assistant launched two independent read-only reviews against the unchanged candidate: 1. cgroup/admission correctness; 2. native resolver/fallback security. In parallel, the assistant planned mutation-workspace proofs that regressions fail on the parent and when each load-bearing guard is removed.
• 🟡 (13:22) The separate mutation workspace was /home/byk/Code/opencode-lore-embedding-runtime-mutation; its initial operation failed because the working copy was stale since operation b2ff52c0245e, with the prescribed recovery jj workspace update-stale.
• 🟡 (13:23) After stale-workspace recovery, mutation working copy tsxwlvkw / b892e0385ba0 was an empty commit with no changes, parented directly on candidate tmzmtlss / e6d0f1edc850; update reported Added 2 files, modified 14 files, removed 0 files.
• 🔴 (13:23) User-provided cgroup-discovery invariant states membership and mount information must be reread so a worker is never admitted from a stale cgroup directory or a cached discovery miss.
• 🔴 (13:23) User-provided inherited-boundary invariant states every descendant cgroup boundary must remain readable so sibling usage is never subtracted from the wrong scope.
• 🔴 (13:23) User-provided embedding-cap contract states the adaptive cap never exceeds the Nomic v1.5 maximum sequence length.
• 🔴 (13:23) User-provided reprobe rationale states a persisted low cap must not become permanent when free memory never improves; under that condition the system must never re-probe. EMBED_REPROBE_RATIO is 1.3.
• 🟡 (13:23) packages/core/src/cgroup-memory.ts implements Linux cgroup v1/v2 discovery from /proc/self/cgroup and /proc/self/mountinfo; on hybrid hosts it prefers the explicit v1 memory controller over the unified v2 hierarchy.
• 🟡 (13:23) packages/core/src/cgroup-memory.ts decodes octal procfs path escapes, rejects non-absolute paths, NULs, and .. path components, normalizes with node:path posix, and chooses the deepest directly matching mount root; namespaced interpretation is accepted only when exactly one candidate is unambiguous.
• 🟡 (13:23) readLinuxCgroupMemoryHeadroomBytes() walks from the process cgroup directory to the cgroup mount point and computes the minimum finite limit - usage across inherited boundaries. For cgroup v2 it reads memory.current, memory.high, and memory.max; for v1 it reads memory.usage_in_bytes and memory.limit_in_bytes.
• 🟡 (13:23) Cgroup accounting fails closed with undefined for malformed numeric data, unreadable descendant boundaries, unsafe traversal, discovery errors, or ambiguous mounts. A special cgroup-v2 exception allows the true root mount (files.root === "/") to omit memory.current/high/max, because that root cannot itself be resource-controlled.
• 🟡 (13:24) packages/core/src/embedding/local.ts defines test overrides _setConstrainedMemoryForTest(), _setContainerFreeForTest(), and _setAvailableMemoryForTest(). constrainedMemoryLimit() uses process.constrainedMemory() and returns 0 for unknown, unsupported, unconstrained, non-finite, or non-positive values.
• 🟡 (13:24) availableMemoryHeadroom() combines Linux procfs-derived headroom with runtime information through resolveMemoryHeadroom(). Bun is treated specially because its implementation currently aliases host freemem() inside constrained cgroups; Node’s libuv implementation is treated as process-limit-aware. If process.availableMemory() is absent or throws, the Linux result is used.
• 🟡 (13:24) packages/core/test/embedding-pool.test.ts contains three admission regressions: 1. with pool size 2 and pool free memory 0, concurrency remains on one worker; 2. with host free memory 64 * GB, constrained limit 256 MiB, and ceiling 2, the pool must not load a second worker; 3. with host free memory 64 * GB, constrained limit 12 * GB, and available headroom 23 MiB, a warmed pool remains at one worker.
• 🟡 (13:24) packages/core/test/embedding-pool.test.ts tests unreflected-memory reservation with pool size 4, host free memory 64 * GB, constrained limit 12 * GB, and available headroom 1600 MiB: after warming and submitting three embeds, only two fake workers may exist because one admitted-but-unhealthy worker’s budget must be reserved.
• 🟡 (13:24) The container-aware regression documents the production failure: cgroup-blind os.freemem() reported large host memory, the old gate spawned a second native ONNX worker, and the process exceeded memory.max, causing an OOM-killer SIGKILL.
• 🟡 (13:24) packages/core/test/embedding-pool-memory.test.ts pins two guards: each worker sizes from free / ceiling rather than full free memory, and a constrained primary worker with unknown current headroom uses the token floor.