Rust Performance Loop

0. 規律

1. 計測なき最適化は禁止。着手前にベースラインを取る。
2. 1 変更 = 1 計測。同時に複数を混ぜない。
3. 効かなければ revert。±5% はノイズ。
4. プロファイル上位 5 関数に入らないコードは触らない。
5. 毎周 cargo test --release。正しさ > 速さ。
6. 最適化後に読みにくくなったらアプローチを疑う。

1. ループ

baseline → profile → 仮説（N% 効くはず、を明文化）→ 1 変更 → test → 同条件で再計測
  → 改善: commit / 改善なし: revert + perf log に 1 行

止めどき: 上位 5 関数を触り目標の 80% 達成 / 残るホット関数が <5% / 次案が可読性を壊して期待 <5% / 3 周で 1% も動かない。

2. 計測ツール

3. ビルド設定（Cargo.toml に定義済み）

RUSTFLAGS="-C force-frame-pointers=yes" cargo build --profile profiling -p rsvelte_devtools --bin profiler

PGO: scripts/perf/pgo.sh が pgo/rsvelte.profdata を再生成、scripts/perf/assert-pgo-profile.sh が magic を検査（壊れた profile は warning のみでビルドが通る）。scripts/bench/pgo-env.mjs が cargo spawn に適用。

4. プレイブック（効く順）

アンチパターン: LLVM 既済みの手最適化 / マイクロ勝ちマクロ負け / コールド最適化 / 数値なしコミット。

5. 計測ハザード（この箱・このリポ固有）

• 静かな箱: ps -Ao %cpu=,comm= | sort -rn | head の先頭を読む。cargo==0 でも mds_stores/mediaanalysisd がビルド直後に 90% 超。陽性対照 yes > /dev/null が最上位に出ること。
• 比は時間で対にする: official/rsvelte を同一ラウンド内で back-to-back、ABBA で順序交互。別々に測った比は drift。
• 壁時計でなく CPU 時間: perf_bench の CPU median を読む。壁時計は負荷で 2 倍動く。
• アームの同一性: ファイル名・パス・ブランチは信用しない。Compiling <crate> (<path>) 行、2 成果物の sha256、出力での判別プローブ（含むべきもの／欠くべきもの両方）を読む。
• worktree: 毎回 cd <worktree> && CARGO_TARGET_DIR=<worktree>/target cargo …。cwd は黙ってリセットされる。
• ディスク: df -g /System/Volumes/Data が 20 GiB 未満なら cargo を起動しない。debug の target/debug/deps は 1 バイナリ ~140 MB × ls crates/rsvelte_core/tests/*.rs | wc -l 本（積を持ち歩かない — AGENTS.md 参照）。
• 分母: 共有型（JsNode 等）を触ったら --workspace。| tail/2>/dev/null 越しに verdict を読まない。
• call count を先に読む: 決定的。時間は 1 回ではノイズ。
• 同居エージェント: 計測窓の開始／終了は宣言で伝える。他人の窓の中で cargo を叩かない。
• 未測定は未測定と書く: 未確定のまま入れた変更は全て戻された。

6. $ARGUMENTS

1. continue → 直近 perf log を読み次ループ。
2. 関数名／モジュール名 → そこに絞る。
3. 空 → samply で全体を測り上位 5 を提示（§7.1 の --profile 内訳は使わない）。
4. 順序厳守: baseline → profile → 仮説（ユーザー確認）→ 変更 → test → 再計測 → keep/revert。
5. 1 イテレーション 1 報告、3 周ごとに要約。

7. rsvelte 固有

7.1 計測コマンド

./scripts/bench/bench.sh --quick        # JS vs Rust 単線比較
./scripts/bench/bench.sh --criterion    # criterion
cargo build --release -p rsvelte_devtools --bin perf_bench
target/release/perf_bench --target client --runs 9 [--threads N] [--skip S --limit L]   # A/B の主計器
cargo build --profile profiling -p rsvelte_devtools --bin profiler
samply record target/profiling/profiler --file big.svelte --iterations 100
cargo build --profile profiling -p rsvelte_devtools --bin corpus_share_profile --features mimalloc-alloc
samply record --save-only -o prof.json.gz -r 1000 -- target/profiling/corpus_share_profile --iters 4
node scripts/bench/profile-shares.mjs prof.json.gz 30   # self/inclusive share 表
cargo run --release -p rsvelte_devtools --bin compile_profile -- --target server [--dev]  # フェーズ内訳
pnpm benchmark:reproduce                # サイト報告（scripts/reports/run-performance.mjs）

profiler / bench.sh --profile のフェーズ配分は本番経路と違う（retained script なし、TS 除去なし）。「parse:analyze:transform = X:Y:Z」の根拠に使わない。samply の相対ホットスポットには使える。

7.2 既知ボトルネック

現状の数値と alloc 分析は docs/phase3-ast-refactor-plan.md を読む。

7.3 OXC 対応

ソース: ls ~/.cargo/registry/src/*/oxc_<crate>-*/src/

7.4 NAPI 経由 E2E

cargo build --release -p rsvelte_napi --lib
node scripts/compat-corpus/binding.mjs --stage      # .corpus-cache/rsvelte.node
pnpm corpus:verify && pnpm corpus:matrix           # 出力バイト同一ゲート
cargo test --release                                # runtime/ssr/hydration

Vite 経路は apps/npm/vite-plugin-svelte。最終確認は必ず NAPI 経由。

8. References

• https://nnethercote.github.io/perf-book/
• https://oxc.rs/docs/learn/performance
• docs/perf-baseline.md（20x 目標の現状と計測記録）