Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

fix(mem): size the budget from free memory, and relieve on real scarcity

Martin Vogelc3714f11339e
diff --git a/internal/cbm/result_spill.c b/internal/cbm/result_spill.c
index 89716398a..852421632 100644
--- a/internal/cbm/result_spill.c
+++ b/internal/cbm/result_spill.c
@@ -20,6 +20,7 @@
#include "foundation/constants.h"
#include "foundation/log.h"
#include "foundation/mem_core.h"
+#include "foundation/platform.h" /* cbm_fs_free_bytes: the disk ceiling below */
/* The park writes a result as an opaque image: the record header (a struct
* copy) and the compacted arena block. Both carry padding bytes no code ever
@@ -64,13 +65,22 @@ typedef struct {
FILE *fp;
cbm_mutex_t mu; /* reads seek; writes append -- one lock per file */
char path[CBM_SZ_1K];
- uint64_t end; /* bytes written so far (append offset) */
+ uint64_t end; /* bytes written so far (append offset) */
+ bool unlinked; /* already removed while open (POSIX); close must not retry */
} spill_file_t;
typedef struct {
int writer; /* -1 = empty */
uint64_t offset; /* record start in that writer's file */
uint64_t rec_len; /* header + block */
+ /* The file's namespace/package, kept in MEMORY while the result itself is
+ * on disk. The namespace map that import resolution is built on is
+ * assembled from every file at once, before any of them is reloaded: a
+ * parked file used to contribute nothing to it, so spilling silently
+ * changed how imports resolved (see cbm_result_spill_namespace). One short
+ * string per parked file is a rounding error against the result it
+ * replaces. */
+ char *namespace_name;
} spill_slot_t;
struct cbm_result_spill {
@@ -81,8 +91,57 @@ struct cbm_result_spill {
_Atomic int64_t parked;
_Atomic int64_t bytes;
_Atomic int64_t loads;
+ int64_t byte_cap; /* 0 = uncapped (the platform could not say) */
+ _Atomic int cap_reported; /* reaching the cap is logged once, not per park */
};
+/* Spilling trades a memory problem for a disk problem, so the disk gets a say.
+ *
+ * FLOOR: below this much free space, do not start spilling at all — filling the
+ * user's disk is a worse failure than the memory pressure being relieved, since
+ * it breaks everything else on the machine and not just this index.
+ * SHARE: of what IS free, never take more than this fraction, so a runaway
+ * index cannot consume the rest either.
+ * Free space is read once, at open: it is this run's budget, not a moving
+ * target to race against, and a failed write stays handled underneath. */
+enum { SPILL_FREE_FLOOR_GB = 10, SPILL_FREE_SHARE_DIV = 2 };
+
+/* Remove spill files left by runs that are no longer here. Only files this
+ * module names (spill-<pid>-<writer>.bin) are touched, and on Windows an open
+ * file refuses deletion, which is exactly the liveness check we want: a running
+ * index keeps its own spill. POSIX runs unlink at open, so this only ever finds
+ * files from before that behaviour, or from another platform's cache. */
+static void spill_sweep_orphans(const char *spill_dir) {
+ cbm_dir_t *dir = cbm_opendir(spill_dir);
+ if (!dir) {
+ return;
+ }
+ int removed = 0;
+ cbm_dirent_t *entry;
+ while ((entry = cbm_readdir(dir)) != NULL) {
+ if (strncmp(entry->name, "spill-", 6) != 0) {
+ continue;
+ }
+ size_t len = strlen(entry->name);
+ if (len < 5 || strcmp(entry->name + len - 4, ".bin") != 0) {
+ continue;
+ }
+ char path[CBM_SZ_1K];
+ if (snprintf(path, sizeof(path), "%s/%s", spill_dir, entry->name) >= (int)sizeof(path)) {
+ continue;
+ }
+ if (cbm_unlink(path) == 0) {
+ removed++;
+ }
+ }
+ cbm_closedir(dir);
+ if (removed > 0) {
+ char removed_text[CBM_SZ_16];
+ snprintf(removed_text, sizeof(removed_text), "%d", removed);
+ cbm_log_info("mem.spill.orphans_removed", "count", removed_text, "dir", spill_dir);
+ }
+}
+
cbm_result_spill_t *cbm_result_spill_open(const char *dir, int writers, int slots) {
if (!dir || !dir[0] || writers <= 0 || slots <= 0) {
return NULL;
@@ -95,6 +154,30 @@ cbm_result_spill_t *cbm_result_spill_open(const char *dir, int writers, int slot
cbm_log_warn("mem.spill.open_failed", "dir", spill_dir, "reason", "mkdir");
return NULL;
}
+ /* Reclaim what earlier runs could not. A run killed outright (OOM killer,
+ * SIGKILL, power loss) runs no cleanup, and on Windows its spill files
+ * survive; POSIX runs unlink-at-open below and leaves nothing. Deleting is
+ * the liveness test: an open file cannot be removed on Windows, so a
+ * concurrent run's spill refuses and is left alone. */
+ spill_sweep_orphans(spill_dir);
+ /* Ask the disk BEFORE trading memory for it. Refusing here leaves the
+ * caller in the memory path it was already in (back-pressure, then its own
+ * budget decision) — the same outcome as a disk that fills mid-run, minus
+ * the filled disk. */
+ size_t free_bytes = cbm_fs_free_bytes(spill_dir);
+ int64_t byte_cap = 0;
+ if (free_bytes > 0) {
+ size_t floor_bytes = (size_t)SPILL_FREE_FLOOR_GB * 1024 * 1024 * 1024;
+ if (free_bytes < floor_bytes) {
+ char free_mb[CBM_SZ_32];
+ snprintf(free_mb, sizeof(free_mb), "%zu", free_bytes / (1024 * 1024));
+ cbm_log_warn("mem.spill.refused", "reason", "low_disk", "free_mb", free_mb, "detail",
+ "not spilling onto a nearly full disk; memory relief continues through "
+ "back-pressure instead");
+ return NULL;
+ }
+ byte_cap = (int64_t)(free_bytes / SPILL_FREE_SHARE_DIV);
+ }
cbm_result_spill_t *sp = cbm_calloc(CBM_MEM_CLASS_OTHER, sizeof(*sp));
if (!sp) {
return NULL;
@@ -107,6 +190,7 @@ cbm_result_spill_t *cbm_result_spill_open(const char *dir, int writers, int slot
}
sp->writers = writers;
sp->slot_count = slots;
+ sp->byte_cap = byte_cap;
for (int i = 0; i < slots; i++) {
sp->slots[i].writer = -1;
}
@@ -120,6 +204,17 @@ cbm_result_spill_t *cbm_result_spill_open(const char *dir, int writers, int slot
return NULL;
}
cbm_mutex_init(&f->mu);
+#ifndef _WIN32
+ /* Unlink while we hold it open: the data stays reachable through this
+ * handle, and the space comes back the moment the process ends — a
+ * clean exit, an abort, or a SIGKILL from the OOM killer alike. A
+ * killed run cannot leave gigabytes of spill behind because there is no
+ * name left to leave it under. Windows refuses to unlink an open file,
+ * so it keeps the close-path unlink and the sweep below. */
+ if (cbm_unlink(f->path) == 0) {
+ f->unlinked = true;
+ }
+#endif
}
cbm_log_info("mem.spill.open", "dir", spill_dir, "writers", writers > 0 ? "yes" : "no");
return sp;
@@ -141,6 +236,23 @@ bool cbm_result_spill_park(cbm_result_spill_t *sp, int writer, int slot, CBMFile
if (result->arena.nblocks != 1 || result->owned_result_count != 0) {
return false;
}
+ /* The disk ceiling. Refusing a park leaves the result in memory, which is
+ * exactly where it would be without spill at all — the caller's
+ * back-pressure and budget keep deciding from there. What this prevents is
+ * an index quietly consuming the rest of the user's free space. */
+ if (sp->byte_cap > 0) {
+ int64_t want = (int64_t)(sizeof(spill_rec_hdr_t) + result->arena.used);
+ if (atomic_load_explicit(&sp->bytes, memory_order_relaxed) + want > sp->byte_cap) {
+ if (atomic_exchange_explicit(&sp->cap_reported, 1, memory_order_relaxed) == 0) {
+ char cap_mb[CBM_SZ_32];
+ snprintf(cap_mb, sizeof(cap_mb), "%lld", (long long)(sp->byte_cap / (1024 * 1024)));
+ cbm_log_warn("mem.spill.cap_reached", "cap_mb", cap_mb, "detail",
+ "spill is at its share of free disk; results stay in memory and "
+ "back-pressure takes over");
+ }
+ return false;
+ }
+ }
spill_file_t *f = &sp->files[writer];
spill_rec_hdr_t hdr;
memset(&hdr, 0, sizeof(hdr));
@@ -166,6 +278,12 @@ bool cbm_result_spill_park(cbm_result_spill_t *sp, int writer, int slot, CBMFile
sp->slots[slot].writer = writer;
sp->slots[slot].offset = offset;
sp->slots[slot].rec_len = sizeof(hdr) + hdr.block_len;
+ /* Copied BEFORE the result is freed below: the namespace map is built from
+ * all files at once, long before this slot is loaded back. */
+ if (result->namespace_name && result->namespace_name[0]) {
+ sp->slots[slot].namespace_name =
+ cbm_mem_strdup(CBM_MEM_CLASS_OTHER, result->namespace_name);
+ }
atomic_fetch_add_explicit(&sp->parked, 1, memory_order_relaxed);
atomic_fetch_add_explicit(&sp->bytes, (int64_t)(sizeof(hdr) + hdr.block_len),
memory_order_relaxed);
@@ -258,6 +376,13 @@ void cbm_result_spill_stats(const cbm_result_spill_t *sp, int64_t *parked, int64
}
}
+const char *cbm_result_spill_namespace(const cbm_result_spill_t *sp, int slot) {
+ if (!sp || !sp->slots || slot < 0 || slot >= sp->slot_count) {
+ return NULL;
+ }
+ return sp->slots[slot].namespace_name;
+}
+
void cbm_result_spill_close(cbm_result_spill_t *sp) {
if (!sp) {
return;
@@ -267,12 +392,19 @@ void cbm_result_spill_close(cbm_result_spill_t *sp) {
spill_file_t *f = &sp->files[w];
if (f->fp) {
(void)fclose(f->fp);
- (void)cbm_unlink(f->path);
+ if (!f->unlinked) { /* POSIX already removed it at open */
+ (void)cbm_unlink(f->path);
+ }
cbm_mutex_destroy(&f->mu);
}
}
cbm_free(CBM_MEM_CLASS_OTHER, sp->files);
}
+ if (sp->slots) {
+ for (int i = 0; i < sp->slot_count; i++) {
+ cbm_free(CBM_MEM_CLASS_OTHER, sp->slots[i].namespace_name);
+ }
+ }
cbm_free(CBM_MEM_CLASS_OTHER, sp->slots);
cbm_free(CBM_MEM_CLASS_OTHER, sp);
}
diff --git a/internal/cbm/result_spill.h b/internal/cbm/result_spill.h
index 8738870aa..75b7a3231 100644
--- a/internal/cbm/result_spill.h
+++ b/internal/cbm/result_spill.h
@@ -50,6 +50,14 @@ bool cbm_result_spill_peek_header(const cbm_result_spill_t *sp, int slot, CBMFil
* relations it holds (the collector sizes its array before loading). */
void cbm_result_spill_peek_counts(const cbm_result_spill_t *sp, int slot, int *defs, int *impls);
+/* The namespace/package a parked file declares, or NULL. Kept in MEMORY while
+ * the result itself is on disk, because import resolution builds its namespace
+ * map from EVERY file before any parked one is read back. Without it a spilled
+ * file contributed nothing to that map, so imports resolved differently
+ * depending on memory pressure -- php measured 57,182 edges in memory against
+ * 59,379 while spilling, the same binary, 2026-09-18. */
+const char *cbm_result_spill_namespace(const cbm_result_spill_t *sp, int slot);
+
/* Counters for the log: results parked, bytes on disk, loads served. */
void cbm_result_spill_stats(const cbm_result_spill_t *sp, int64_t *parked, int64_t *bytes,
int64_t *loads);
diff --git a/src/foundation/mem.c b/src/foundation/mem.c
index c6ea4f225..4c5b60ae7 100644
--- a/src/foundation/mem.c
+++ b/src/foundation/mem.c
@@ -188,6 +188,11 @@ static void mem_option_set_verified(mi_option_t option, long value, const char *
#define RAM_FRACTION_32GB 0.35
#define RAM_BYTES_PER_GB (1024ULL * 1024 * 1024)
+/* Bounds for the free-memory clamp (cbm_mem_clamp_to_available). */
+#define CBM_MEM_AVAIL_HEADROOM_MIN ((size_t)RAM_BYTES_PER_GB)
+#define CBM_MEM_AVAIL_HEADROOM_MAX ((size_t)(8ULL * RAM_BYTES_PER_GB))
+#define CBM_MEM_BUDGET_FLOOR ((size_t)(RAM_BYTES_PER_GB / 2)) /* 512 MB */
+
double cbm_mem_ram_fraction_for_total(size_t total_ram_bytes) {
if (total_ram_bytes <= 16ULL * RAM_BYTES_PER_GB) {
return RAM_FRACTION_16GB;
@@ -248,6 +253,36 @@ cbm_mem_budget_t cbm_mem_resolve_budget(size_t total_ram, double ram_fraction,
return result;
}
+/* A budget derived from TOTAL ram plans to use memory that may already belong
+ * to something else. Measured 2026-09-18 on a 48 GB host: the default budget
+ * (50% = 24 GB) was sized while a 12 GiB VM and a second VM were running, the
+ * kernel index took its full 24.5 GB RSS, and the machine ran out — the same
+ * run completed at the same budget once the VM was stopped. Total RAM is the
+ * CEILING; what is free right now is the CONSTRAINT.
+ *
+ * Headroom is a quarter of what is free, held between 1 and 8 GB: enough that
+ * the OS, its file cache and the user's editor are not squeezed out, without
+ * making a large-memory machine behave like a small one. A budget is never
+ * clamped below CBM_MEM_BUDGET_FLOOR — below that nothing indexes at all, and
+ * refusing to start is worse than trying and spilling. available == 0 means
+ * the platform could not answer, and a guess is not better than the ceiling. */
+size_t cbm_mem_clamp_to_available(size_t budget, size_t available) {
+ if (available == 0) {
+ return budget;
+ }
+ size_t headroom = available / 4;
+ if (headroom < CBM_MEM_AVAIL_HEADROOM_MIN) {
+ headroom = CBM_MEM_AVAIL_HEADROOM_MIN;
+ } else if (headroom > CBM_MEM_AVAIL_HEADROOM_MAX) {
+ headroom = CBM_MEM_AVAIL_HEADROOM_MAX;
+ }
+ size_t cap = available > headroom ? available - headroom : 0;
+ if (cap < CBM_MEM_BUDGET_FLOOR) {
+ cap = CBM_MEM_BUDGET_FLOOR;
+ }
+ return budget < cap ? budget : cap;
+}
+
cbm_mem_budget_t cbm_mem_resolve_budget_capped(size_t total_ram, double ram_fraction,
const char *budget_mb, size_t hard_cap_bytes) {
cbm_mem_budget_t result = cbm_mem_resolve_budget(total_ram, ram_fraction, budget_mb);
@@ -418,6 +453,38 @@ void cbm_mem_init_with_cap(double ram_fraction, size_t hard_cap_bytes) {
const char *env = cbm_safe_getenv("CBM_MEM_BUDGET_MB", env_buf, sizeof(env_buf), NULL);
cbm_mem_budget_t resolved =
cbm_mem_resolve_budget_capped(info.total_ram, ram_fraction, env, hard_cap_bytes);
+
+ /* A budget derived from total RAM is a plan made in ignorance of what the
+ * machine is already doing. Clamp the DERIVED budget to what is actually
+ * free; an explicit CBM_MEM_BUDGET_MB is the user's deliberate choice and
+ * still wins, but it is warned about when it exceeds what is free, because
+ * the failure it buys (the OS killing the worker) reads like a product bug
+ * rather than a setting. */
+ size_t available = cbm_system_available_ram();
+ bool explicit_budget =
+ resolved.source != NULL && strcmp(resolved.source, "CBM_MEM_BUDGET_MB") == 0;
+ if (!explicit_budget) {
+ size_t clamped = cbm_mem_clamp_to_available(resolved.budget, available);
+ if (clamped < resolved.budget) {
+ char want_mb[CBM_SZ_32];
+ char avail_mb[CBM_SZ_32];
+ snprintf(want_mb, sizeof(want_mb), "%zu", resolved.budget / MB_DIVISOR);
+ snprintf(avail_mb, sizeof(avail_mb), "%zu", available / MB_DIVISOR);
+ cbm_log_info("mem.budget.available_clamp", "from_mb", want_mb, "available_mb", avail_mb,
+ "detail", "budget reduced to fit memory that is actually free");
+ resolved.budget = clamped;
+ resolved.source = "available_ram";
+ }
+ } else if (available > 0 && resolved.budget > available) {
+ char want_mb[CBM_SZ_32];
+ char avail_mb[CBM_SZ_32];
+ snprintf(want_mb, sizeof(want_mb), "%zu", resolved.budget / MB_DIVISOR);
+ snprintf(avail_mb, sizeof(avail_mb), "%zu", available / MB_DIVISOR);
+ cbm_log_warn("mem.budget.over_available", "budget_mb", want_mb, "available_mb", avail_mb,
+ "detail",
+ "explicit budget exceeds free memory: the OS may kill this process before "
+ "the budget is ever reached");
+ }
g_budget = resolved.budget;
/* The resolver is the single source of truth for the parse + clamp; this
@@ -574,6 +641,24 @@ bool cbm_mem_over_budget(void) {
return charged > g_budget;
}
+/* "Give memory back now" — true when our own budget is exceeded OR the MACHINE
+ * is short, whichever comes first.
+ *
+ * Deliberately separate from cbm_mem_over_budget(): the budget decides whether
+ * the run may CONTINUE (and, as a last resort, aborts it), while this decides
+ * whether to spill and reclaim. System pressure must never abort a run — it is
+ * someone else's allocation spike as often as ours, and the honest response is
+ * to hand memory back, not to fail. Keeping the two apart is what lets the
+ * relief path be aggressive without making the failure path trigger-happy.
+ *
+ * Why it is needed at all: the budget is charged against OUR accounting, which
+ * on 2026-09-18 read 22 GB against a 24 GB budget while the host had nothing
+ * left and killed the worker. Our own number can be comfortably under budget
+ * while the machine is dying. */
+bool cbm_mem_should_relieve(void) {
+ return cbm_mem_over_budget() || cbm_mem_system_under_pressure();
+}
+
/* Reclaimable memory below this share of total RAM is where paging starts to
* hurt, so it is the point at which pressing on stops being reasonable. */
enum { MEM_PRESSURE_AVAIL_DIVISOR = 8 }; /* 12.5% of total RAM */
diff --git a/src/foundation/mem.h b/src/foundation/mem.h
index 4f7a22567..22cf0b47a 100644
--- a/src/foundation/mem.h
+++ b/src/foundation/mem.h
@@ -50,6 +50,12 @@ cbm_mem_budget_t cbm_mem_resolve_budget(size_t total_ram, double ram_fraction,
cbm_mem_budget_t cbm_mem_resolve_budget_capped(size_t total_ram, double ram_fraction,
const char *budget_mb, size_t hard_cap_bytes);
+/* Reduce a budget derived from TOTAL ram to something the machine can actually
+ * spare right now, keeping a headroom reserve for the OS and other processes.
+ * `available` of 0 means the platform could not answer and the budget stands.
+ * Pure, so the policy is testable without a machine in a particular state. */
+size_t cbm_mem_clamp_to_available(size_t budget, size_t available);
+
/* Current RSS in bytes via mi_process_info().
* Falls back to OS-specific queries when MI_OVERRIDE=0 (ASan builds). */
size_t cbm_mem_rss(void);
@@ -90,6 +96,12 @@ void cbm_mem_set_budget_for_tests(size_t bytes);
/* Returns true if current RSS exceeds the budget. */
bool cbm_mem_over_budget(void);
+/* True when memory should be handed back NOW: our budget is exceeded, or the
+ * machine itself is short. Use this for spill/reclaim decisions; use
+ * cbm_mem_over_budget() for the decision to stop a run. System pressure must
+ * relieve, never abort — the spike may not even be ours. */
+bool cbm_mem_should_relieve(void);
+
/* Per-worker budget hint: budget / num_workers. */
size_t cbm_mem_worker_budget(int num_workers);
diff --git a/src/foundation/platform.h b/src/foundation/platform.h
index 7e9d3ff29..43738f621 100644
--- a/src/foundation/platform.h
+++ b/src/foundation/platform.h
@@ -120,6 +120,12 @@ cbm_system_info_t cbm_system_info(void);
* cannot answer. NOT cached - it changes during a run, which is the point. */
size_t cbm_system_available_ram(void);
+/* Free bytes on the filesystem holding `path`, or 0 when the platform cannot
+ * answer. Spilling trades a memory problem for a disk problem, so the disk has
+ * to be ASKED before that trade, not discovered through a failed write halfway
+ * through. Not cached: free space changes while we spill into it. */
+size_t cbm_fs_free_bytes(const char *path);
+
/* Recommended worker count for parallel indexing.
* initial=true: all cores (user is waiting for initial index)
* initial=false: max(1, perf_cores-1) (leave headroom for user apps) */
diff --git a/src/foundation/system_info.c b/src/foundation/system_info.c
index 489a7dc65..ad182f150 100644
--- a/src/foundation/system_info.c
+++ b/src/foundation/system_info.c
@@ -14,12 +14,17 @@
enum { DEFAULT_CORES = 1, MIN_WORKERS = 1, CBM_WORKERS_MAX = 256 };
#include "foundation/log.h"
+#include "foundation/mem_core.h" /* cbm_alloc: one accounted allocation path */
#include "foundation/platform.h"
#include "foundation/system_info_internal.h"
#include <stdint.h> // uint64_t
#include <stdlib.h> // strtol
#include <string.h>
+#ifndef _WIN32
+#include <sys/statvfs.h> /* cbm_fs_free_bytes: free space before we spill into it */
+#endif
+
#ifdef _WIN32
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
@@ -366,3 +371,41 @@ size_t cbm_system_available_ram(void) {
return 0; /* BSD: unknown rather than guessed */
#endif
}
+
+size_t cbm_fs_free_bytes(const char *path) {
+ if (!path || !path[0]) {
+ return 0;
+ }
+#ifdef _WIN32
+ /* The QUOTA figure, not the volume's: on a disk with per-user quotas the
+ * volume's free space is not what this process may actually write. */
+ ULARGE_INTEGER avail = {0};
+ /* Widened through the memory core rather than cbm_utf8_to_wide(), which
+ * allocates with raw malloc: every allocation in this binary goes through
+ * one accounted path (src/foundation/mem_core.h). */
+ int wide_len = MultiByteToWideChar(CP_UTF8, MB_ERR_INVALID_CHARS, path, -1, NULL, 0);
+ if (wide_len <= 0) {
+ return 0;
+ }
+ wchar_t *wide = cbm_alloc(CBM_MEM_CLASS_OTHER, (size_t)wide_len * sizeof(wchar_t));
+ if (!wide) {
+ return 0;
+ }
+ size_t free_bytes = 0;
+ if (MultiByteToWideChar(CP_UTF8, MB_ERR_INVALID_CHARS, path, -1, wide, wide_len) == wide_len &&
+ GetDiskFreeSpaceExW(wide, &avail, NULL, NULL)) {
+ free_bytes = (size_t)avail.QuadPart;
+ }
+ cbm_free(CBM_MEM_CLASS_OTHER, wide);
+ return free_bytes;
+#else
+ struct statvfs st;
+ if (statvfs(path, &st) != 0) {
+ return 0;
+ }
+ /* f_bavail, not f_bfree: blocks free for an UNPRIVILEGED writer, which is
+ * what this process is. f_frsize is the fragment size the counts are in. */
+ uint64_t unit = st.f_frsize ? (uint64_t)st.f_frsize : (uint64_t)st.f_bsize;
+ return (size_t)((uint64_t)st.f_bavail * unit);
+#endif
+}
diff --git a/src/graph_buffer/graph_buffer.c b/src/graph_buffer/graph_buffer.c
index 3ef86bcdd..24553657d 100644
--- a/src/graph_buffer/graph_buffer.c
+++ b/src/graph_buffer/graph_buffer.c
@@ -1945,7 +1945,12 @@ int cbm_gbuf_dump_to_sqlite(cbm_gbuf_t *gb, const char *path) {
if (rc != 0) {
break;
}
- free_heavy = free_heavy || (cbm_mem_budget() > 0 && cbm_mem_over_budget());
+ /* cbm_mem_should_relieve, not cbm_mem_over_budget: the dump is where
+ * the run died on 2026-09-18 with our charge UNDER budget and the host
+ * out of memory, so the only signal that would have fired here is the
+ * machine's. Dropping the property strings we have already written is
+ * pure relief — the rows are in the file by now. */
+ free_heavy = free_heavy || (cbm_mem_budget() > 0 && cbm_mem_should_relieve());
if (free_heavy && src_nodes) {
for (int j = off; j < off + chunk; j++) {
cbm_free(CBM_MEM_CLASS_GBUF_STRING, src_nodes[j]->properties_json);
diff --git a/tests/test_mem.c b/tests/test_mem.c
index a2643a963..11b3e2c2c 100644
--- a/tests/test_mem.c
+++ b/tests/test_mem.c
@@ -478,6 +478,33 @@ TEST(resolve_budget_no_override_uses_fraction) {
PASS();
}
+/* A budget derived from TOTAL ram plans to use memory that may already belong
+ * to another process. Measured 2026-09-18 on a 48 GB host: the 24 GB default
+ * was sized while a 12 GiB VM ran, the kernel index took its full 24.5 GB, and
+ * the machine ran out — the same run completed once the VM was stopped. */
+TEST(clamp_to_available_leaves_headroom_for_the_rest_of_the_machine) {
+ size_t budget = 24576 * CBM_TEST_MB; /* 24 GB, the 50%-of-48 GB default */
+
+ /* Plenty free: the fraction-derived budget stands. */
+ ASSERT_EQ(cbm_mem_clamp_to_available(budget, 40960 * CBM_TEST_MB), budget);
+
+ /* Only 8 GB free: headroom is a quarter of it, so the budget becomes 6 GB
+ * instead of planning to use three times what the machine has. */
+ ASSERT_EQ(cbm_mem_clamp_to_available(budget, 8192 * CBM_TEST_MB), 6144 * CBM_TEST_MB);
+
+ /* Headroom is capped so a big machine does not behave like a small one:
+ * 64 GB free reserves 8 GB, not 16 GB, and 24 GB still fits under that. */
+ ASSERT_EQ(cbm_mem_clamp_to_available(budget, 65536 * CBM_TEST_MB), budget);
+
+ /* Nearly nothing free: clamped to the floor rather than to zero — refusing
+ * to index at all is worse than trying and spilling. */
+ ASSERT_EQ(cbm_mem_clamp_to_available(budget, 256 * CBM_TEST_MB), 512 * CBM_TEST_MB);
+
+ /* The platform could not answer: the ceiling stands, no guessing. */
+ ASSERT_EQ(cbm_mem_clamp_to_available(budget, 0), budget);
+ PASS();
+}
+
TEST(resolve_budget_invalid_fraction_defaults) {
/* Out-of-range fractions fall back to the 0.5 default. */
size_t total = 8192 * CBM_TEST_MB;
@@ -1349,7 +1376,7 @@ static TSTree *parse_for_test(TSParser *parser, CBMLanguage lang, const char *sr
* name in another grammar. The real function is reached with parentheses, which
* suppress the macro. */
TEST(field_id_cache_answers_exactly_what_tree_sitter_answers) {
- static const char *const names[] = {"name", "body", "type", "parameters",
+ static const char *const names[] = {"name", "body", "type", "parameters",
"result", "receiver", "value", "not_a_field"};
const char *go_src = "package p\n"
"type T struct { A int }\n"
@@ -1417,8 +1444,8 @@ TEST(field_id_cache_answers_exactly_what_tree_sitter_answers) {
TEST(cursor_pool_hands_each_depth_its_own_cursor) {
TSParser *parser = ts_parser_new();
ASSERT_NOT_NULL(parser);
- TSTree *tree = parse_for_test(parser, CBM_LANG_GO,
- "package p\nfunc A() {}\nfunc B() {}\nvar C = 1\n");
+ TSTree *tree =
+ parse_for_test(parser, CBM_LANG_GO, "package p\nfunc A() {}\nfunc B() {}\nvar C = 1\n");
ASSERT_NOT_NULL(tree);
TSNode root = ts_tree_root_node(tree);
@@ -1439,7 +1466,8 @@ TEST(cursor_pool_hands_each_depth_its_own_cursor) {
bool fresh_ok = ts_tree_cursor_goto_first_child(&fresh);
int siblings = 0;
while (pooled_ok && fresh_ok) {
- ASSERT_TRUE(ts_node_eq(ts_tree_cursor_current_node(c0), ts_tree_cursor_current_node(&fresh)));
+ ASSERT_TRUE(
+ ts_node_eq(ts_tree_cursor_current_node(c0), ts_tree_cursor_current_node(&fresh)));
siblings++;
pooled_ok = ts_tree_cursor_goto_next_sibling(c0);
fresh_ok = ts_tree_cursor_goto_next_sibling(&fresh);
@@ -1727,6 +1755,7 @@ SUITE(mem) {
RUN_TEST(mem_init_second_call_noop);
/* CBM_MEM_BUDGET_MB budget override */
RUN_TEST(resolve_budget_no_override_uses_fraction);
+ RUN_TEST(clamp_to_available_leaves_headroom_for_the_rest_of_the_machine);
RUN_TEST(resolve_budget_invalid_fraction_defaults);
RUN_TEST(resolve_budget_override_wins);
RUN_TEST(resolve_budget_override_clamped_to_total);