ledger: cheaper closed-trade history reads and fewer scratch writes per closed trade - #648

A script that scans closedtrades.entry_id(i) over every closed trade each
bar, and a streaming run that publishes and retires rows, paid for four
things in v1.9.0 that v1.6.3 never did:

• two calls into the engine and a library comparison per visit: add
  TradeLedger::{entry_id,exit_id,entry_comment,exit_comment}matches (range
  check and compare in one call; the old symbols stay), route the four
  BacktestEngine::closed_trade*_equals wrappers through them, compare texts
  of up to eight bytes as two words, keep the entry-id length in the cache
  entry's generation word so that compare never reads the record line, and
  prefetch the next cache slots of a sequential scan;
• a read cache that doubled with the population and discarded every entry at
  each doubling, so a script reading the whole history reloaded every row from
  disk after each growth (about 195,000 preads for 35,000 trades): keep the
  slot mapping fixed (global modulo cache_rows) and allocate the storage in
  256-slot pages behind a page table; the last page is clipped to the cap,
  retirement frees pages outside the retained window, and the cache holds one page, about 62 KB more, for a non-retiring run
  of 64 rows or fewer, and up to three pages, about 240 KB, while a
  retiring run's retained window crosses page boundaries (a fixed amount,
  independent of the number of trades);
• duplicate descriptor writes: the host close-cause pass wrote every row back
  even when the cause did not change, and the stored record was rewritten when
  it equalled the new one byte for byte; write back only on a change (a row
  below the sealed base still goes through replace for its refusal), skip the
  identical descriptor store, and fill the cache slot of an appended or
  replaced row from the Trade in memory when a reader already created the
  cache;
• per-text payload writes: the texts of one appended row go out as one
  contiguous write (same bytes, extents and resident tail), and retirement no
  longer zeroes on disk the part of a retired text that the same operation's
  head release zeroes or truncates again.

resident_cache_bytes(rows) now includes the page table (ceil(rows / 256)
pointers, 2,048 bytes at the default cap); the actual allocation never
exceeds it. Skipping duplicate writes also lowers the byte-keyed fdatasync
count (the write budget syncs every 64 KiB of successful bytes); durability
per byte is unchanged. Reports are byte-identical.

Source gate: one new named site, the page allocation in
State::ensure_cache_entry (manifest entry U1623, ceilings.unreviewed
1338 -> 1339, the OPEN pin in test_cr150_source_gate 1522 -> 1523); the page
table allocation re-uses the reviewed cache entry with its identity refreshed.
Three doc anchors that cite engine_orders.cpp lines are re-pinned.

docs: memory page: the ledger read cache is paged, not doubled

The read-cache row of the memory page described the doubling cache. Rewrite
it for the paged cache with a fixed slot mapping and the charge that includes
the page table. This removes three sentences of the old row on purpose:

• "Direct-mapped, allocated at the first read at the smaller of the cap and
  the next power of two" (introduced by a991b4e): the cache is now allocated
  in 256-slot pages behind a page table and never discards entries on growth;
• "The declared bound is resident_cache_bytes(kSinkCacheRows): 65,536 x 312 =
  20,447,232 B" (introduced by 1654497): the charge now adds the page table,
  ceil(cap / 256) pointers, 2,048 bytes at the default cap;
• "Chosen by the engine, not settable from the C API; cache allocation grows
  lazily up to the declared constant cap" (introduced by 1654497): the first
  read creates the page table and each first-touched page allocates its
  slots; the cap is unchanged and still not settable from the C API.

tests: the new test rows are registered through the repository's lane files and fences, and the
selected-metrics expectations for the ledger cache bytes are derived from the accounting formula
(the page table term included) instead of the old constant.

🤖 Generated with Claude Code