review: tighten comments, fix stale claims-journal docs#17
Merged
Conversation
docs/performance.md's "Claims-journal write path" stated a decision (keep the in-mutex write) that F1/F1-part-2 reversed; rewrite it for the snapshot()/commit() split. claimStore's doc likewise still said the marshal runs under the manager mutex — F1-part-2 moved it off. Drop restate-of-code and scenario narrative from a few WHY comments; no behavior change.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Whole-repo
/code /code-rs /code-pycomment-budget pass plus a docs-staleness check against the recently merged #12–#16. Comment-only + docs; no behavior change. A 5-agent scan flagged ~50 candidates; most were already-tight, load-bearing WHY comments (#7 tightened them) and were deliberately left alone — this PR applies only genuine reductions and two real staleness fixes.Staleness fixes (the substantive part)
docs/performance.md— "Claims-journal write path": the section stated "keep the simple in-mutex write; do not move to a store-owned sequential writer." F1 (perf(pool): move the claims-journal write off the manager mutex (F1) #6) and F1-part-2 (perf(pool): marshal the claims journal off the manager mutex (F1 part 2) #14) did exactly that. Rewritten for thesnapshot()(field-copy under the manager mutex) /commit()(marshal + write off it) split, with the staleBenchmarkStoreSaveScalingtable replaced by aBenchmarkStorePersistContentiondescription (kept to the robust ~6× ratio; absolute ns not re-cited without a fresh hardware run).sandboxd/pool/claims.go—claimStoredoc: still said "the manager mutex covers only the marshal". perf(pool): marshal the claims journal off the manager mutex (F1 part 2) #14 moved the marshal off the mutex (snapshot now takes a cheap field-copy). Corrected + tightened.Comment reductions (restate / narrative only)
sandboxd/server/server.goredirectClaim: dropped scenario-painting, kept the redirect targets + no_redirect ping-pong WHY.sandboxd/engine/portconn.goguestPortConn: dropped the{op:data}/{type:data}restate-of-code, kept the wire format + purpose.boot/init/src/cfg.rs: removed three test sub-case labels the asserts already state.sdk/openai/.../adapter.py: removed one restate comment (kept the load-bearing# 404-safe in the SDK).Deliberately NOT changed
refill.go,claim.go,pool.go,hibernate.go,mesh.go,relay.go, silkdexec.rs/session.rs/lsp.rs— accurate and load-bearing; re-compressing review: tighten comments + unsafe SAFETY note #7-approved prose would be churn.docs/benchmarks.mdfs_pull row is stale post-perf(sdk): fast-path bulk frame decode (2.15x exec throughput) #13 (~2× faster) but the log is append-only; a fresh row needs a bare-metal re-bench (.79 currently off), so no fabricated number was added.Gates
go build✓,go vetdarwin+linux ✓,golangci-lint rundarwin+linux → 0 issues,golangci-lint fmt --diffclean,go test -racepool/engine/server → ok.cargo fmt --check✓,cargo clippy --all-targets -D warnings✓,cargo test parse_ip_param→ ok.ruff check→ all passed,py_compile✓;pytestblocked by the externalagents(openai-agents) SDK absent in this env (comment-only change).