Graphus v0.0.9

Graphus v0.0.9

Version: 0.0.9
Date: 2026-07-08

Summary

Graphus v0.0.9 is a feature release for Graphus, the Label Property Graph (LPG) database
server written in Rust for extreme load and concurrency. It makes the server fit the hardware it
runs on out of the box and interoperate with strict or legacy Neo4j drivers, while keeping the
honest defaults, the conformance guarantees, and the drop-in upgrade path intact.

Two capabilities are added and one defect is fixed:

• Hardware-aware startup auto-tuning. At startup the server probes the host — logical CPUs,
  physical and available RAM, and the store filesystem's capacity, free space, and an
  SSD-versus-rotational hint — and sizes its resource-hungry parameters to the real hardware. The
  buffer pool, previously a fixed 32 MiB regardless of RAM, now auto-sizes to roughly one eighth of
  available RAM (clamped to a safe range); the reader and morsel pools resolve to the number of
  cores, capped. Any value set in the TOML file or a GRAPHUS_* environment variable overrides the
  auto-detection — operator configuration always wins.
• Configurable Bolt server agent. Graphus keeps announcing the honest, fully conformant
  Graphus/<version> in the Bolt HELLO reply by default, but a new opt-in option lets operators
  advertise a Neo4j-compatible agent string for strict or legacy drivers that verify it. This changes
  only the advertised string; it never alters Bolt or PackStream behaviour.
• Fixed a tiny buffer-pool re-entrancy abort. A pathologically small buffer pool could abort the
  process with a RefCell already borrowed panic during a re-entrant eviction. It now fails closed
  with a clean, recoverable error, and an explicit sub-minimum pool size is rejected at startup.

This is a drop-in upgrade from v0.0.8: no public Cypher, Bolt, or REST
contract changed, the two new capabilities are opt-in and default to the previous behaviour, and no
existing configuration needs to change.

Throughout, the four inviolable guarantees held:

• 100% ACID — full transactional reliability under power loss, faults, and crashes.
• 100% openCypher TCK — 3914 / 3914 scenarios passing.
• 100% Bolt protocol — byte-for-byte interoperability with the Neo4j driver ecosystem.
• 100% PackStream — exact wire-level serialization.

Highlights

• The server fits its hardware automatically. On first start Graphus detects the host's CPUs,
  RAM, and store filesystem, then sizes the buffer pool, reader pool, and morsel parallelism to what
  it finds — instead of shipping a fixed 32 MiB buffer pool on every machine from a Raspberry Pi to a
  many-core server.
• Operator configuration always wins. Auto-tuning is driven by a 0 = auto sentinel: any value
  set in the TOML file or a GRAPHUS_* environment variable (including the new
  GRAPHUS_BUFFER_POOL_PAGES) overrides the detected default verbatim.
• Never worse than before. The auto-sized buffer pool floor equals the previous fixed default and
  its ceiling bounds worst-case resident memory, so the change can only match or improve on prior
  behaviour.
• Interoperability with strict or legacy Neo4j drivers. A new opt-in startup option advertises a
  vetted Neo4j/5.13.0 (or any value you choose) in the Bolt HELLO reply, so drivers and tooling
  that verify the server agent string accept Graphus — without changing Bolt or PackStream
  behaviour.
• Safety kept #![forbid(unsafe_code)]. Hardware detection lives in a new, separately-audited
  leaf crate, graphus-sysres, which isolates the single platform-specific unsafe system call so
  the graphus-server crate remains free of unsafe code. Every probe degrades gracefully and never
  panics or blocks startup.
• A tiny buffer pool no longer aborts the process. A re-entrancy hazard that could panic under a
  pathologically small pool now fails closed with a clean, recoverable error while preserving
  write-ahead-log-before-data ordering.

Added

• Hardware-aware startup auto-tuning (rmp #617, decision D-hw-autotune). At startup the server
  probes the host — logical CPUs, physical/available RAM, and the store filesystem's capacity/free
  space plus an SSD-vs-rotational hint — and sizes its resource parameters to the real hardware, while
  any value set in the TOML file or a GRAPHUS_* environment variable overrides the auto-detection.
  The buffer pool (previously a fixed 32 MiB regardless of RAM) auto-sizes to roughly one eighth of
  available RAM, clamped to [32 MiB, 2 GiB]; the reader and morsel pools resolve to min(cpus, 16).
  Auto-tuning is driven by a 0 = auto sentinel (including the new GRAPHUS_BUFFER_POOL_PAGES), so
  operator configuration always wins. The auto-size is computed by a pure, deterministic step
  (apply_hardware_defaults) run before validation and before any store opens. Detection lives in a
  new, separately-audited leaf crate, graphus-sysres, that isolates the single macOS unsafe
sysctl call, keeping graphus-server #![forbid(unsafe_code)]. A single structured startup log
  line reports what was detected and how each parameter resolved (auto vs config). See
  docs/configuration.md for the full parameter table and the
  auto-tuning rules.
• Configurable Bolt server agent for legacy/strict Neo4j-driver interoperability
  (bolt_server_agent / GRAPHUS_BOLT_SERVER_AGENT, rmp #614). By default Graphus keeps
  announcing Graphus/<version> in the Bolt HELLO SUCCESS — 100% Bolt-conformant and accepted by
  every modern Neo4j driver. Some strict or legacy clients (1.x-era drivers and tooling derived from
  them) instead verify this string and reject any product that is not the case-sensitive literal
  Neo4j. The new opt-in startup option controls the advertised agent: unset or blank → the
  Graphus/<version> default; the neo4j-compat shortcut → the vetted Neo4j/5.13.0; any other
  value → announced verbatim (for example Neo4j/5.13.0-graphus-<version>). Neo4j/5.13.0 is the
  floor of the Neo4j version window whose native Bolt maximum matches Graphus's negotiated Bolt 5.4
  (Bolt 5.4 ⇒ Neo4j 5.13–5.22, per the official compatibility matrix), so no version-keyed client
  assumes Bolt features Graphus does not serve; a regression test couples this compatibility constant
  to the handshake's MAX_MINOR so a future Bolt bump fails loudly. Announcing Neo4j/… does not
  change Bolt/PackStream conformance nor unlock capabilities — drivers gate features on the negotiated
  Bolt version, never on this string. A startup warning fires (warning only, never a rejection) when
  the configured value claims Neo4j identity in a shape a strict or legacy parser would reject. See
  docs/bolt.md and docs/configuration.md.

Fixed

• Tiny buffer-pool re-entrancy abort (rmp #302). Building a buffer pool with a pathologically
  small capacity could abort the process with a RefCell already borrowed panic during a re-entrant
  eviction. This was root-caused (proven empirically) to the index SharedWal::ensure_durable, which
  performed a re-entrant borrow_mut when a caller held the WAL latch across an evicting page
  write-back — the classic ARIES "don't nest the buffer-pool flush under the log latch" hazard. It now
  fails closed with a clean, recoverable error instead of aborting, preserving
  write-ahead-log-before-data ordering: the error short-circuits before the home write, so no page is
  written home ahead of its log record and the page stays resident and dirty. As defence in depth,
  an explicit buffer_pool_pages below the documented minimum (64) is now rejected at startup with a
  clear message rather than reaching the pool, and an internal safety net ensures an unresolved config
  can never reach store-open with a zero-page pool. Regression tests were added at pool sizes 1, 2, 3,
  and 4 across the buffer-pool and index-recovery paths.

Verification

This release was validated empirically; no functional test reported an error. The four inviolable
guarantees are unchanged — the openCypher TCK remains at 3914 / 3914 (100%), and the ACID, Bolt,
and PackStream guarantees hold.

• Hardware-aware auto-tuning. The new graphus-sysres crate is covered by 9 unit tests and 2
  documentation tests, and the graphus-server configuration layer adds a deterministic auto-tuning
  battery (clamp arithmetic, floor and ceiling, override precedence, and idempotence) alongside
  dedicated hardware-detection tests. It was verified end to end on the real binary in three modes:
  auto-detection (a 2 GiB buffer pool selected on a 27 GiB host), an environment-variable override
  (operator config wins over the detected default), and a sub-minimum value (a clean fail-fast error,
  with no panic). The graphus-sysres crate — which isolates the single platform unsafe sysctl
  call — received a clean security review (SECURE).
• Configurable Bolt server agent. Unit tests cover the agent resolver (default, the neo4j-compat
  shortcut, and verbatim values), input normalization, and the warning heuristic (including
  case-variant and truncated-version inputs). Core Bolt tests assert the custom agent is reflected in
  the HELLO SUCCESS and that the compatibility constant is coupled to the handshake's MAX_MINOR.
  An end-to-end test drives a real Bolt client that reads Neo4j/5.13.0 back from a live server's
  HELLO. The change was certified GO by the Bolt-protocol specialist: no HELLO/PackStream
  regression, a spec-legal value safe for the widest driver ecosystem, and a warning heuristic with
  zero false positives.
• Tiny buffer-pool re-entrancy fix. RED→GREEN regression tests were added at buffer-pool sizes 1,
  2, 3, and 4 across the buffer-pool and index-recovery paths, asserting a clean recoverable error in
  place of the former abort.
• Conformance and hygiene gates intact. The broader suites remained green — including the
  graphus-server library, server integration, buffer pool, index, and storage tests — and
  clippy --all-targets -D warnings is clean on every touched crate. The openCypher TCK stays at
  3914 / 3914.

Compatibility

v0.0.9 is a drop-in upgrade from v0.0.8. The transaction and isolation model is exactly as in
v0.0.8 (MySQL-style autocommit reads at Snapshot Isolation, fully Serializable
writes and explicit BEGIN … COMMIT transactions; see
docs/transactions.md), and no public Cypher, Bolt, or REST contract
changed.

Both new capabilities are opt-in and default to the previous behaviour:

• Auto-tuning activates only where a parameter is left at its 0 = auto sentinel. Any value
  already set in the TOML file or a GRAPHUS_* environment variable is honoured verbatim, so an
  existing configuration behaves exactly as before. The auto-sized buffer pool floor equals the old
  fixed default, so an unconfigured server can only match or improve on its previous memory footprint.
• The Bolt server agent stays Graphus/<version> unless you explicitly set bolt_server_agent
  (or GRAPHUS_BOLT_SERVER_AGENT). Setting it changes only the advertised agent string and never the
  Bolt or PackStream wire behaviour.

No action is required to upgrade. Operators who want the server to size itself to the host can
simply leave the relevant parameters unset; operators who need strict-driver compatibility can set
bolt_server_agent = "neo4j-compat".

Upgrading

# Docker Hub (multi-arch: linux/amd64 + linux/arm64)
docker pull flaviocfo/graphus:v0.0.9             # or :latest

See docs/getting-started.md for first-run instructions,
docs/configuration.md for the full configuration reference — including
hardware-aware auto-tuning and the bolt_server_agent option — and docs/bolt.md
for the Bolt-over-TCP and Bolt-over-UDS interfaces and Neo4j-driver interoperability.