Default the RocksDB WriteBufferManager on at 1/3 of block cache

[kriszyp]

Summary

Makes the RocksDB WriteBufferManager (WBM) on by default in core (it was opt-in). Defaults, applied in openRocksDatabase:

• writeBufferManagerSize = blockCacheSize / 3 (floored)
• writeBufferManagerCostToCache = true
• writeBufferManagerAllowStall = true
• An explicit size of 0 still disables the WBM; any explicitly configured value/boolean is honored.

The block-cache + WBM defaulting was extracted out of openRocksDatabase into a pure resolveRocksMemoryConfig helper (utility/rocksMemoryConfig.ts) so the branching is unit-testable without opening a database or hitting the process-global RocksDatabase.config.

Purpose

Bound total memtable memory across column families and apply write backpressure (allowStall) so bulk ingest can't outrun the memtable flush/conflict-check window. This is the throughput/memory half of HarperFast/harper-pro#348 (the data-safety floor — not silently dropping on retry-cap exhaustion — is a separate follow-up PR).

Where to look

• utility/rocksMemoryConfig.ts — the defaulting rules (3-way size logic: unset → default, 0 → disabled, >0 → used).
• resources/databases.ts — now just calls the helper.

Notes for the reviewer

• Fabric/host-manager interaction: host-manager's compose template already sets all four STORAGE_ROCKS_* env vars explicitly (block cache 15%, WBM 5%, costToCache true, allowStall false). Those explicit values are typed and honored over these new defaults, so Fabric keeps its Phase-1 allowStall: false — no regression.
• Deliberate call (open for input): I did not add a hardcoded fallback for availableMemory being Infinity/NaN. availableMemory = min(constrainedMemory ?? Infinity, totalmem()) is always finite because os.totalmem() is, so guarding it would be validating an unreachable state. Negative configured sizes already disable safely via the > 0 gate. Flag if you'd prefer a defensive guard anyway.

Cross-model review (Codex + Gemini/agy) run pre-PR; float-flooring, strict-assert, and edge tests were added in response.

🤖 Generated with Claude Code — model: Claude Sonnet 4.6

[claude]

Reviewed; no blockers found.

[gemini-code-assist]

Code Review

This pull request refactors the RocksDB memory configuration logic by extracting it from resources/databases.ts into a dedicated, pure utility function resolveRocksMemoryConfig in utility/rocksMemoryConfig.ts, accompanied by a comprehensive suite of unit tests. The feedback recommends moving defensive runtime checks for configuration parameters like configuredBlockCacheSize and configuredWriteBufferManagerSize into the Joi validation schema to ensure proper validation and keep the resolver code clean.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Instead of adding defensive runtime checks for configuredBlockCacheSize in the resolver, ensure this configuration parameter is explicitly defined and validated in the Joi validation schema. This prevents invalid values like Infinity or non-numbers from bypassing validation while keeping the implementation free of redundant guards.

References

1. Ensure all new configuration parameters are explicitly defined in the Joi validation schema, as they may otherwise bypass validation if allowUnknown: true is enabled, potentially leading to runtime errors.
2. Avoid adding defensive checks or guards for states, properties, or methods that are guaranteed to exist or cannot occur in practice.

[gemini-code-assist]

Instead of adding inline defensive checks for configuredWriteBufferManagerSize to handle negative, NaN, or Infinity values, ensure that this parameter is explicitly validated in the Joi schema. This avoids redundant runtime guards in the resolver code.

References

1. Ensure all new configuration parameters are explicitly defined in the Joi validation schema, as they may otherwise bypass validation if allowUnknown: true is enabled, potentially leading to runtime errors.
2. Avoid adding defensive checks or guards for states, properties, or methods that are guaranteed to exist or cannot occur in practice.

[kriszyp]

Thanks for the review! On the suggestion to move the configuredBlockCacheSize / writeBufferManagerSize checks into the Joi schema: I'm keeping the type-enforcement in resolveRocksMemoryConfig deliberately. These values already flow through configUtils.castConfigValue (which yields proper numbers/booleans/null), and the resolver's typeof guards are defaulting logic rather than validation — they're what implement the "unset → derive from block cache, explicit 0 → disable" behavior, which is clearer co-located with the defaults it feeds. This also matches the existing block-cache resolution pattern. Open to revisiting if we want stricter rejection of malformed config at the schema layer as a separate change.

— Claude Sonnet 4.6