[jiangkoumo]

Tier: P1 (engine/crates/layerfs-nfs) ; risks: risk:kernel ; gate: no (the EINTR loop restarts an interrupted read syscall, as std's read_exact and the base's write_record already do; it does not retry a failed operation) ; de-escalated: none
Docs: docs/architecture/engine/kernel-routes/nfs.md

Summary

The loopback NFS server read every RPC record with two socket reads: one for the 4-byte record mark, one for the body. This PR keeps a small read-ahead buffer per connection so the mark and body usually arrive in one read, and retries reads interrupted by EINTR.

Changes

• engine/crates/layerfs-nfs/src/rpc.rs: buffered record reader with read-ahead; EINTR retry; large records still read directly.
• engine/crates/layerfs-nfs/src/server.rs: connection loop uses the buffered reader.
• tests/protocol.rs, tests/support/client.rs: unit tests for split marks, multi-record buffers, large records and EINTR.
• docs/architecture/engine/kernel-routes/nfs.md: describes the read path.

Results (exploratory diagnostic, native macOS, NFSv3 loopback mount; counted with a tool not in this diff at an earlier head, not reproducible from this PR. The reproducible count is tests/protocol.rs::a_whole_call_costs_one_read)

• Socket reads per request: 2.00 -> 0.89 to 1.00 across five scenarios, 3 runs each; writes per request unchanged at 1.00.
• Total socket calls over the five scenarios: 112,791 -> 73,318 (-35%).
• verify.sh output identical to baseline.
• No wall-clock timing was collected, so this PR claims fewer syscalls, not a measured speedup.

Verification

• macOS: cargo test -p layerfs-nfs 33 passed; clippy --all-targets -D warnings clean.
• Linux: fmt, clippy (layerfs-nfs, layerfs-daemon) clean; layerfs-nfs 32 passed; layerfs-daemon failures identical to baseline 58c548b3e (FUSE/cgroup permission environment).

Base: layerfs_v2_0_0 at 58c548b3e.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

[yifanxuaaa]

Review (static, at c8e6f55). Approve after small fixes. I traced the Records framing in rpc.rs and found no bug:

• a header split across reads;
• several records in one read;
• a large single fragment, read straight from the stream;
• fragment chains, which never over-read into the next record;
• the 2 MiB limit, checked per fragment and as a running total;
• EOF mid-header, which returns UnexpectedEof.

Only Interrupted is restarted, which is a syscall restart, not an operation retry.

To fix

1. The performance numbers don't follow the measurement policy (docs/general/agent-measurement-policy.md §3.1/§3.6).
   • The commit says "two runs each" and the body "3 runs each"; the policy is one sample per arm.
   • The socket-read counter isn't in the diff, so "112,791 -> 73,318" can't be reproduced.
   • There are no receipts, pinned identities or command, and it was measured at e2f131b, not at the head.
   • Please label these as diagnostic counts, or record them properly.
2. docs/architecture/engine/kernel-routes/nfs.md:31: the Records::read diagram line is one character short, so the box border is misaligned.

Nits

• The first commit message says the buffer "is given back after a large record"; the second commit keeps it. Squash or reword.
• No test covers the boundary 4+len == READ_AHEAD (an 8188-byte body). The code handles it.

Merges cleanly on the current base and with #636, #637 and #644.

[jiangkoumo]

更新到 e6e9ac0：

• 合入最新 layerfs_v2_0_0（de1d77e13）。唯一冲突在 docs/architecture/engine/kernel-routes/nfs.md：保留 2.0 docs: delete most docs and reorganize by layer (core, engine, control, api) #671 的新结构，框图里 read_record 改为 Records::read，读路径说明（read-ahead、大记录单独缓冲、EINTR 重试）放在 RPC 一节末尾。代码无冲突、无改动。

验证（Linux，cargo +1.85.1 --locked，head e6e9ac0）：

• layerfs-nfs 34 passed（protocol 15 个），clippy -D warnings 干净
• slow 146/146，mount 二进制 45 过 0 失败
• PG：persistence 25、store-service 6、project 1、api 2、cli 2、control 3，全过
• fast 1904 个里 1903 过、1 个失败：layerfs-cli exit_codes stdin_and_from_feed_the_content_and_json_positionals 报 Broken pipe。本 PR 没改 layerfs-cli；这是 --from 跳过 stdin 后父进程仍写管道的并发竞态，同一 head 单独重跑通过。
• fmt --check 只剩上游基线 api/crates/layerfs-cli/tests/concurrent_reads.rs:16

未跑：macOS 挂载侧计数复测。

[yifanxuaaa]

Review record

• Head reviewed: e6e9ac05f6. It merges into layerfs_v2_0_0 at 836036d2a1 without conflicts.
• Tier: P1, risk:kernel. Gate: no. The EINTR loop restarts an interrupted syscall, as read_exact and the base's write_record do; it is not an operation retry.
• Read: the whole buffered record reader. That covers record marks at offset 0, fragment chains through take, the per-fragment and total limit (checked before allocation), the fixed 8 KiB buffer, the large-record path when part of the body is already buffered, and EOF in a mark or body. No defect found. Behaviour change: a 1–3 byte partial mark at EOF is now UnexpectedEof instead of Ok(None). That is harmless, because the server ends the connection either way. Tests: no assertion was weakened; the moved assertions are carried into Records.
• Re-run at the PR head merged with 836036d2a1, on macOS with Rust 1.85.1:
  • tools/check_product_boundary.py: PASS.
  • cargo test -p layerfs-nfs (--no-run first, 100 s limit): 35/35 pass.
  • cargo clippy -p layerfs-nfs --all-targets -- -D warnings: clean.
• Linux mount proof: the author reports it; no reviewer has re-run it. Waived by the owner for this merge.
• Not checked: the macOS native client with pipelined calls, and the server answer path beyond the reader.
• Nit: commit e2f131b166 says the buffer "is given back after a large record". c8e6f5530e reversed that; the squash replaces the message.

Reviewer: Claude Opus 5.5 (independent-context review, then spot-checked)