refactor(shard): delete CoalescedReadBatch, and let the #416 harness toggle the fast path

[TinDang97]

CoalescedReadBatch (src/shard/dispatch.rs) was the xshard-read-fastpath C3
type: N single-key foreign reads from different connections batched into one
SPSC message to one owner shard. It was defined with the C1 types in PR #177,
deferred at C3, and never wired: no ShardMessage arm, no spsc_handler arm,
no config, no metric. Its only references were its own definition and a
type-existence test. In the type index it read as a shipped cross-shard
optimisation; it was not one.

It is deleted rather than built because the measurement no longer supports
building it. Its premise — "a foreign lock-free read is storage-impossible in
place, so SPSC is the only door" — ended when L4 made Database Send + Sync
and try_foreign_db_read began serving foreign reads on the calling thread
(#777, default auto since #785). Re-measured at HEAD on moon#773's own
fixture (GET p=1 c200, --shards 8, keyspace populated to DBSIZE 100,000,
keyspace_misses 0) from a dedicated load generator: 99.0% of foreign reads
served in place, cross_spsc 0.90% of commands, 0.0089 parks/cmd, against
87.5% / 0.866 parks/cmd with the flag off. Coalescing reduces msgs/cmd, the
term the cost model fits at ~0, and would leave every remaining park in place
(dead end #1); the wake-batching variant D1 was retired by measurement in #778.

The re-take also found two things the docs now record (cost model §6, §8.3):
the residual is the owner's exclusive guard on its own read paths (the inline
GET at blocking.rs:2515 and every SPSC execute arm take databases.write()),
and a same-host redis-benchmark --threads 4 inflates that residual 15x
(13.5-15.1% vs 0.90%) through lock-holder preemption on the oversubscribed
box. §8's "100% in place / 0.0003 parks/cmd" is the c50 light-client number
and is now stated as such.

scripts/gcloud-xshard-absolute.sh (moon#416) passed a fixed server-argument
list, so its s4-c1-GET cell silently stopped measuring the SPSC hop it is
named for once the default flipped to auto. start_moon/cell now take
extra server args (--extra-args / MOON_EXTRA_ARGS), read cells populate
the keyspace and report DBSIZE, the default cell set measures the hop
(--cross-shard-fast-path off) and the fast path as two cells of one A/B plus
the write hop (s4-c1-SET), and --self-test fails closed if the passthrough
stops reaching the server argv (mutation-tested: dropping "$@" fails gate 12).

No behaviour changes: nothing constructed, sent or matched on the deleted type.
Both runtimes checked with --all-targets; clippy clean.

Refs: moon#773, moon#416, moon#777, moon#785, moon#778
author: Tin Dang

Summary by CodeRabbit

• Documentation

  • Updated cross-shard performance guidance with new measurements, recommendations for reliable benchmarking, and clarification of the current foreign-read fast path.
  • Recorded the retirement of an unimplemented read-coalescing design and preserved the associated ordering and performance rationale.

• Chores

  • Enhanced benchmarking tools with configurable server options, additional read and write comparison scenarios, database-size reporting, and validation checks for benchmark configuration.

[qodo-code-review]

ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 699a2599-6233-4692-8955-c94d1eb525e9

📥 Commits

Reviewing files that changed from the base of the PR and between a60ff7b and 63595a3.

📒 Files selected for processing (6)

• .add/tasks/xshard-read-fastpath/TASK.md
• CHANGELOG.md
• docs/internal/cross-shard-cost-model.md
• scripts/gcloud-xshard-absolute.sh
• src/shard/dispatch.rs
• tests/xshard_fastpath_api.rs

---

📝 Walkthrough

Walkthrough

The benchmark harness now separates the cross-shard SPSC hop from the default foreign-read fast path. It preloads read keys and reports database size. The unused CoalescedReadBatch type and API pin test are removed, with measurement findings and retirement rationale documented.

Changes

Cross-shard fast-path measurement and retirement

Layer / File(s)	Summary
Benchmark harness and measurement cells scripts/gcloud-xshard-absolute.sh, CHANGELOG.md	The harness accepts extra server arguments, reuses them across launches, populates read keys, validates passthrough, reports dbsize, and runs separate fast-path-off GET, default GET, and cross-shard SET cells.
Measurement findings and scoring guidance docs/internal/cross-shard-cost-model.md	The cost model documents same-host oversubscription effects and records dedicated-client measurements for the foreign-read fast path.
Coalescing type retirement and records src/shard/dispatch.rs, tests/xshard_fastpath_api.rs, docs/internal/cross-shard-cost-model.md, .add/tasks/xshard-read-fastpath/TASK.md, CHANGELOG.md	The unused CoalescedReadBatch type and its type-pin test are removed. The task record, changelog, and cost model document the retirement and preserved ordering rationale.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Suggested reviewers: tindangtts

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant moon_argv
  participant MoonServer
  participant BenchmarkCell
  CLI->>moon_argv: pass extra server arguments
  moon_argv->>MoonServer: build initial or retry argv
  BenchmarkCell->>MoonServer: start selected fast-path mode
  BenchmarkCell->>MoonServer: populate keyspace
  BenchmarkCell->>MoonServer: run GET or SET measurement
  MoonServer-->>BenchmarkCell: return results and dbsize

Loading

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch g2/delete-coalesced-read-batch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}