Module device_budget 

How many bytes the selected backend will let this process hold – the right-hand side of crate::kv_budget’s inequality.

One rule throughout: ask the device, do not model the operating system. Each backend has exactly one query and it is the vendor’s own answer:

backend	query	crate
Metal	MTLDevice.recommendedMaxWorkingSetSize	ferrox_metal::MetalProfile
CUDA	cuMemGetInfo free bytes	ferrox_cuda::HardwareProfile
CPU	total physical RAM, minus a reserve	ferrox_cuda::HardwareProfile

The serving plan explicitly rules out the alternative – process phys_footprint sampling, wired-memory limits, jetsam avoidance, a free + inactive + active * ratio dynamic ceiling. None of it is here and none of it should be added: a conservative, explainable number beats a clever one, and every one of those mechanisms is an Apple-specific workaround for an allocator ferrox does not have.

What this number is not

It is a ceiling to plan against, not a reservation. Nothing here allocates, nothing holds the memory, and every source is a snapshot: another process can take the VRAM a moment later, and macOS can shrink a recommended working set under pressure.

It is also approximate for ferrox specifically, for a reason that has nothing to do with the probe: ferrox mmaps its quantized weights. Their pages are owned by the kernel’s page cache, not by ferrox, so a check that charges the full checkpoint against this budget is charging an upper bound. A model that overruns the budget may still run, page-faulting; a model that fits may still be evicted by pressure from elsewhere on the machine. Every path that prints this number says so.

Structs

DeviceBudget

A probed byte ceiling plus the sentence explaining where it came from. The sentence is not decoration: a budget a user cannot trace back to a query is a budget they will disable.

Enums

BudgetBackend

Which pool a budget was drawn from.

Constants

BUDGET_ENV

Overrides the probe entirely (FERROX_DEVICE_BUDGET_BYTES). The escape hatch for a host whose real ceiling is something ferrox cannot see – a container memory limit, a shared GPU, an operator who simply knows better.

CPU_RESERVE_FRACTION

Fraction of a host RAM budget held back for the OS and everything else running on the machine. Deliberately blunt: the alternative is modelling the OS, which the plan rules out.

DEVICE_RESERVE_FRACTION

Fraction of a device budget (Metal working set, free VRAM) held back for driver allocations, command buffers and the activation scratch this module does not itemise.