Distillation

Date: Sep 16, 2026

• 🔴 (12:31) User stated Jujutsu (jj) operations never fail on merge conflict; rebase, new, and squash record conflicts in the resulting commit for later manual resolution.
• 🔴 (12:31) User stated the repository workflow must use jj rather than git for mutations when .jj/ exists; interactive flags and jj resolve must not be used, commit/description operations require -m "msg", and mutations must be verified with jj st and jj log.
• 🟡 (12:32) Work plan status: 1. “Add deterministic regressions and fixes for cgroup discovery, constrained primary sizing, and pool growth reservations” was in_progress/high priority; 2. “Harden native addon validation and WASM fallback without leaking loader diagnostics” was pending/high; 3. “Prove critical fixes fail on the parent and under guard-removal mutations” was pending/high; 4. “Run full formatting, typecheck, lint, bundle, and affected/full test validation” was pending/high; 5. “Freeze the exact candidate and obtain independent correctness and security reviews” was pending/high; 6. “Finalize the Jujutsu change and report runtime guidance” was pending/medium.
• 🟡 (12:32) Assistant stated the admission review found concrete defects rather than stylistic concerns and planned to check each regression against the implementation, retain only tests exercising the real production boundary, remove duplicated scaffolding, then proceed to native fallback.
• 🟡 (12:32) packages/core/src/cgroup-memory.ts:31-53 parses cgroup memberships and prefers an explicit cgroup v1 memory controller over a unified cgroup v2 hierarchy on hybrid hosts.
• 🟡 (12:32) packages/core/src/cgroup-memory.ts:75-123 resolves cgroup memory files from /proc/self/cgroup and /proc/self/mountinfo, decodes procfs octal escapes, rejects nulls and .., selects the deepest direct mount root, and accepts a namespaced interpretation only when exactly one candidate exists.
• 🔴 (12:33) User stated cgroup membership and mount discovery must be reread so a worker is never admitted from a stale cgroup directory or a cached discovery miss.
• 🟡 (12:33) memoryFiles() in packages/core/src/cgroup-memory.ts:126-133 rereads /proc/self/cgroup and /proc/self/mountinfo on each call rather than caching discovery.
• 🔴 (12:33) User stated every descendant cgroup boundary must remain readable so sibling usage is never subtracted from the wrong scope.
• 🟡 (12:33) readLinuxCgroupMemoryHeadroomBytes() in packages/core/src/cgroup-memory.ts:152-204 walks from the process cgroup directory to the mount point, reads memory.current with memory.high and memory.max for v2 or memory.usage_in_bytes with memory.limit_in_bytes for v1, and returns the minimum finite limit - usage headroom. It fails closed with undefined on malformed/unreadable descendant boundaries, while allowing the unresource-controlled cgroup v2 root to omit memory files when directory === files.mountPoint and files.root === "/".
• 🟡 (12:33) Existing cgroup regressions in packages/core/test/cgroup-memory.test.ts include “prefers an explicit v1 memory controller on a hybrid host” at line 55, “uses the tightest inherited v2 memory limit” at line 105, and “fails closed when a constrained mount root is unreadable” at line 226.
• 🔴 (12:34) User stated the embedding pool’s primary worker is always present; constrained-host protection for that worker comes from its own OOM backoff rather than pool sizing, preserving the existing single-worker behavior.
• 🟡 (12:34) packages/core/src/embedding/pool.ts:193-215 computes the pool ceiling as follows: explicit testEmbedPoolSize is clamped to [1, EMBED_POOL_ABS_MAX]; under NODE_ENV === "test", configured size is similarly clamped or defaults to 1; production uses min(configuredEmbedPoolSize() ?? DEFAULT_MAX_EMBED_POOL, EMBED_POOL_ABS_MAX).
• 🟡 (12:34) pickSlot() in packages/core/src/embedding/pool.ts:218-280 always admits an initial primary slot after respecting initRetryAt; during transient failure debt it routes new work only to healthy slots; growth requires at least 1 healthy slot, all eligible capacity busy, room below the ceiling including retiredWorkers, and enough live memory for every unhealthy slot plus 1 additional worker.
• 🟡 (12:34) Pool growth reservation formula in packages/core/src/embedding/pool.ts:262-268 is liveFreemem() >= (this.slots.filter((slot) => !slot.healthy).length + 1) * PER_WORKER_MEM_BUDGET_BYTES, preventing the same headroom from being spent repeatedly while admitted workers are still starting.
• 🟡 (12:34) liveFreemem() in packages/core/src/embedding/pool.ts:282-288 uses _setPoolFreememForTest when set, otherwise freemem(), then reads constrainedMemoryLimit() and availableMemoryHeadroom(); if a positive constrained limit lacks trustworthy headroom it returns 0, otherwise it calls clampFreeToContainerLimit(raw, constrained, headroom).
• 🟡 (12:34) spawnSlot() in packages/core/src/embedding/pool.ts:290-315 passes the pool ceiling to LocalProvider as the memory divisor, so each worker derives its token cap from free / ceiling; the intended aggregate bound is one EMBED_MEM_FRACTION share rather than each worker independently claiming half of free memory.
• 🟡 (12:35) Container-aware regression in packages/core/test/embedding-pool.test.ts:766-790 sets pool ceiling 2, host free memory 64 * GB, and constrained memory 256 * 1024 * 1024; it expects only 1 worker because a second native ONNX worker would exceed the container’s memory.max and risk SIGKILL.
• 🟡 (12:35) Current-headroom regression in packages/core/test/embedding-pool.test.ts:792-813 sets pool ceiling 2, host free memory 64 * GB, constrained memory 12 * GB, and available memory 23 * 1024 * 1024; it expects the pool to remain at 1 worker and serialize 2 embedding requests.
• 🟡 (12:35) Starting-worker reservation regression in packages/core/test/embedding-pool.test.ts:815-840 sets pool ceiling 4, host free memory 64 * GB, constrained memory 12 * GB, and available memory 1600 * 1024 * 1024; after warming the pool and submitting 3 requests, it expects exactly 2 workers because one observed worker budget may admit one starting worker but cannot be spent again before initialization completes.
• 🟡 (12:35) constrainedMemoryLimit() in packages/core/src/embedding/local.ts:91-97 uses the test override when present, otherwise process.constrainedMemory(), and returns a positive finite value or 0 for unconstrained/unknown cases.
• 🟡 (12:35) availableMemoryHeadroom() in packages/core/src/embedding/local.ts:99-128 combines Linux cgroup headroom with runtime values through resolveMemoryHeadroom(). Bun omits its host-wide availableMemory() result; Node uses process.availableMemory() when available and falls back safely if it is absent or throws.
• 🟡 (12:35) containerFreeBytes() in packages/core/src/embedding/local.ts:130-137 clamps host freemem() against constrainedMemoryLimit() and availableMemoryHeadroom(). computeInitialEmbedCap() at lines 160-170 divides this clamped free memory by Math.max(1, memDivisor) before applying memoryModelEmbedCap() and reconcileEmbedCap().
• 🔴 (12:36) User stated that when native ONNX is oversized in a cgroup, the cgroup OOM killer can SIGKILL the process, so the ×0.7 OOM backoff never fires; the WASM path instead self-limits against its fixed 4 GiB heap, while native has no equivalent wall.
• 🟡 (12:36) clampFreeToContainerLimit() in packages/core/src/embedding-cap.ts:160-174 computes Math.min(hostFree, finite positive constrained limit, finite nonnegative available headroom). If a finite constrained limit exists without trustworthy headroom, it returns 0; discovered headroom remains authoritative even when the hard limit is unknown, covering cgroup v2 memory.high with unlimited memory.max.
• 🟡 (12:36) resolveMemoryHeadroom() in packages/core/src/embedding-cap.ts:180-206 chooses the minimum of valid Linux headroom, runtime-available memory, and a finite process limit when Linux data exists; without Linux data, it returns undefined unless both a finite process limit and valid runtime-available value exist.