Commit b94ff5c

Only rows measured under `BENCH_INSTRUMENT=2026-11` carry these fields; a 2026-10 row has none of them and is byte-identical to what it was. The code is `memory_probe.py`, and `bench_common.instrument_at_least("2026-11")` gates it.

- **What is read, and when.** At the end of each phase, between two timed sections, never inside one: `load` (the lane's build phase is done), `index_build` (its post-build wait for the index is done, for lanes that have one), `warmup` (an untimed warm-up is done), `queries` (all timed work is done, the engine still open), and `idle` (the same readings again after the engine has been left untouched for `BENCH_MEMPROBE_IDLE_S`, five seconds by default). A lane reaches the phases it has; a reading it does not take is absent, never a copy of the one before. A lane that builds and indexes in one timed phase has `load` as the end of both and no `index_build`.

- **How.** The lane prints its `PHASE` marker; at a marker that ends a phase it writes a request file into a directory the runner mounted into the client container and waits for the answer. The runner, on the host, reads the cgroup files of the cell at that moment and answers. There is no sampler thread inside the cell for this: the cost near a timed section is a 20 ms directory poll on the runner's own cores. The time spent, the full GCs included, is on the row (`phase_probe_s`, `mem_probe_gc_s`) and sits between phases, so no timed number includes it.

- **The headline, the same for every engine: owned memory at the end of the phase, `mem_<phase>_owned_mib`.** It is cgroup `memory.stat` `anon` plus `shmem`, summed over every container of the cell: the server container for a served engine plus the client's, the client process's container alone for an embedded one. Every engine has it whatever it is written in, it needs nothing from the engine, and it counts the shared-memory buffer pool of the PostgreSQL family as it counts a heap. The parts stay on the row (`mem_<phase>_anon_mib`, `_shmem_mib`, and the page cache `_file_mib`, which is context and never part of the headline), and so does the split per container (`mem_<phase>_server_owned_mib`, `_client_owned_mib`).

- **Peak per phase: `mem_<phase>_peak_mib`.** The largest total (`memory.current`, so it includes page cache) of each container during the phase, summed over the containers. When the kernel is 6.12 or newer and the runner may write the cgroup files, `memory.peak` is reset at every boundary through a descriptor the runner keeps open (a reset applies to reads through the same descriptor, so the whole-cell `peak_mib_sum` is unchanged) and the peak is exact (`mem_probe_peak_kind` is `kernel-reset`). Otherwise it is the largest `memory.current` the 0.25 s sampler saw in the phase (`sampled-0.25s`): a shorter spike is missed, and the field says so. `mem_probe_peak_reset` records which.

- **Added per runtime. Context only: these are not compared across engines.** JVM engines (ArcadeDB, Neo4j, Elasticsearch, the composed stack's Neo4j, QuestDB) get the heap at the end of the phase: `jvm_<phase>_used_after_gc_mib` where a full GC was forced first (the working set the engine needs) and `jvm_<phase>_used_mib` where it was not (garbage included, so never read as a working set), and in both cases `jvm_<phase>_committed_mib` (what the JVM holds from the kernel for its heap) and, where the JVM exposes it, `jvm_<phase>_direct_mib` (direct buffers: in-process through the buffer-pool MXBean for an embedded engine, from `jcmd VM.native_memory` for a server that runs with native memory tracking, otherwise absent). `jvm_probe_source` says `jpype` (the embedded JVM is asked in process) or `jcmd` (run in the server container). `jvm_forced_gc_phases` lists the phases that were measured after a forced GC. **A full GC is never forced right before a timed phase.** A collection at the end of a warm-up would hand a JVM engine a freshly collected heap for the timed queries that a native engine does not get, and would move the queries' own GC timing. The lane cannot see the next phase from a marker, so the rule is by phase: a GC is forced only at the end of the last timed phase (`queries`, read when the lane closes) and in `idle`; `load`, `index_build` and `warmup` are read without a GC, from `jcmd GC.heap_info` for a server or the runtime's memory counters for an embedded engine. The `owned` reading of a JVM engine is taken after the GC at `queries` and `idle`, and as the heap stands at the other phases, so compare owned memory across engines at `queries`, the page's column. Embedded engines also get `proc_<phase>_anon_mib` and `proc_<phase>_rss_mib` from `/proc/self/smaps_rollup` (the process's anonymous pages, and its resident set, whose difference is the file-backed pages): these are the closest per-process equivalents, comparable between embedded engines of any language. Non-JVM served engines (PostgreSQL, MongoDB, SurrealDB, Qdrant, Memgraph, ArangoDB and the rest) have no runtime to ask, and their extras are the cgroup parts above: `anon` against `shmem` against `file`.

- **What compares across engines and what does not.** `mem_<phase>_owned_mib` and its parts, and `mem_<phase>_peak_mib`, compare across every engine: they come from the same kernel counters of the same kind of container, and the page prints one headline column from them. `jvm_*` compares across JVM engines only and says nothing about a native engine; `proc_*` compares across embedded engines only. A JVM engine's `owned` and its `jvm_used_after_gc` differ by the JVM's slack (committed but free heap, metaspace, code cache, thread stacks, native memory): the first is what the container held, the second is what the engine needed, and neither replaces the other.

- **A pinned heap makes the kernel's numbers show the cap.** With `-Xms` equal to `-Xmx` the JVM commits the whole heap at start and touches it as it grows, so anon and RSS read near the cap whatever the engine needs, and a larger cap reads larger with the same workload. The 2026-10 instrument pinned the heap of the JVM arms that have a pinned tier heap, so its memory column reads the pin for them. The 2026-11 instrument stops pinning the embedded ArcadeDB arms (a separate change); served engines keep following their vendors' documentation for the heap they start with. An unpinned heap is no cure for the headline: a JVM that has grown stays grown unless the collector returns the pages, which is why `jvm_used_after_gc_mib` sits beside it, and why a row records `jvm_<phase>_committed_mib` next to the heap the engine needed.

- **Disk per phase, the same way for every engine.** At the same boundaries the runner reads, for the container that holds the engine's data (the server container for a served engine, the client's for an embedded one), the bytes it is responsible for: the writable layer plus every declared volume, the reading `container_disk` already takes, here as one sample after a flush rather than the settled pair. `disk_<phase>_mib` is that reading, `disk_<phase>_data_mib` is the headline: it less the same container's empty-start reading (`server_disk_baseline_mb` or `client_disk_baseline_mb`), so it is what the workload left, comparable with `disk_data_mb`. `disk_<phase>_wal_mib` is the write-ahead log or journal alone, found inside the container by name (`*.wal`, `pg_wal`, `journal`, `translog`, `neostore.transaction.db.*`); an engine with another layout reads 0.0, which means none was found, and it is context, not a comparison. `disk_close_mib` and `disk_close_data_mib` are the runner's existing settled reading taken after the lane has closed the database; a phase reading of the same bytes can be lower or higher than it by what background compaction and checkpointing do in between, which is the point of reading both.

- **IO per phase: `io_<phase>_read_mib`, `io_<phase>_write_mib`.** The bytes the cell's containers read from and wrote to disk since the previous boundary (the cgroup `io.stat` counters are cumulative, so a phase is a difference; the first phase starts when the client container does), summed over the containers. The server's startup is not in `load`. The disk and IO readings are taken before the peak restarts, so the helper processes they start inside the container never land in the next phase's peak.

- **Where this stops.** A forced GC changes the heap for the phase that follows (a full collection empties young generations and caches the next phase would have found warm), which is why it runs only after the last timed phase and in `idle`, never before a timed phase, and is recorded in `jvm_forced_gc_phases`; and the lane waits for the answer, so the phases that follow a probe start a few hundred milliseconds later than they would have. A lane that prints no `PHASE` marker of the ones above (the lifecycle and restart lanes) takes no per-phase reading and keeps only the whole-cell fields.

if os.environ.get("BENCH_MEMPROBE_DIR"): # set by the runner only under instrument 2026-11

import memory_probe

memory_probe.lane_on_mark(name)

"mem_queries_owned_mib": 1024.0,

# THE 2026-11 MEMORY COLUMN (issue #352, PROTOCOL "Memory per phase"): owned memory (anonymous plus shared) of every

# container of the cell at the end of the timed queries. Every engine has it, and it is the only memory column added;

# the other phases, the peaks and the per-runtime JVM and process readings stay on the rows. Only a lane whose rows

# all carry instrument 2026-11 gets it, so a 2026-10 payload is unchanged.

MEM_PHASE_COLUMN = ("mem_queries_owned_mib", "owned memory after queries GiB")

cols = _metrics_for_instrument(table_id, spec, src_lane)

if _instrument_of(src_lane or table_id) == "2026-11":

cols = cols + [MEM_PHASE_COLUMN]

return cols

def _metrics_for_instrument(table_id, spec, src_lane=None):

oct_ = _instrument_of(src_lane) in ("2026-10", "2026-11")

MEM_FIELDS = {MEM_PEAK_FIELD, MEM_PEAK_FALLBACK, "end_anon_mib_sum", MEM_PHASE_COLUMN[0]}