docs: performance.md compliance audit (#248)

[abix-]

Summary

Audit of codebase against docs/performance.md (4-round review, issue #248).

Changes

Current Tunings table - stale file/line references fixed:

• COMBAT_BUCKET, CHECK_INTERVAL, HEAL_DRIFT_RADIUS: behavior.rs -> systems/decision/mod.rs (correct file after module split)
• ARCHER_PATROL_WAIT, ENERGY_TIRED_THRESHOLD, ENERGY_WAKE_THRESHOLD: constants.rs -> constants/mod.rs
• ProfilerCache refresh: ui/game_hud.rs -> ui/left_panel/mod.rs
• max_decisions_per_frame: line 110 -> 188
• max_pathfinds_per_frame: 50 -> 200 (value was wrong; PathfindConfig::max_per_frame defaults to 200, confirmed in settings.rs:797 and resources.rs:772)

Bucket-Gated Decision System section - stale time_scale text removed:

• Old text said buckets are "scaled down by time_scale at high game speeds" -- removed after fix: constant 60 UPS at all time_scale speeds #244 (constant 60 UPS). FixedUpdate is now constant 60 Hz; no bucket scaling by time_scale.

Optimization Log - 4 missing entries added:

• sync_sleeping_system O(65K) -> O(dirty) (perf: sync_sleeping_system O(65K) -> O(dirty) event-driven #195)
• mason iter_instances -> for_each_nearby spatial query (fix: Mason decision uses iter_instances+query.get instead of spatial query #169)
• road candidate scoring O(n*m) -> O(n) adjacency check (perf: fix O(n*m) adjacency in road candidate scoring (issue-210) #218)
• damage_system debug sampling removal (fix: health/mod.rs debug sampling uses iter_npcs+query.get in damage_system hot path #170)

Benchmark header updated:

• "Current Benchmark Results" section header said "last run: 2026-03-11b" but bottom section has 2026-03-15 results; updated header to reference the correct date.

Anti-Pattern Violations

None found in FixedUpdate hot paths. All Vec::contains in loops were verified as HashSet::contains (O(1)). The two iter_npcs() calls in remote.rs are BRP cold paths (exempt per Known Exceptions pattern).

Notes

• Benchmarks from 2026-03-15 may be slightly stale: mason (perf: replace mason iter_instances with for_each_nearby spatial query (#169) #227) and constant-60-UPS (fix: constant 60 UPS at all time_scale speeds #244) both landed after that run. Needs local bench to update numbers (k3s cannot run Criterion).

Acceptance Criteria

• Round 1: all hot paths, benchmarks, and recent perf commits inventoried with file:line refs
• Round 2: every hot path checked against anti-patterns, every recent perf PR checked for benchmark docs
• Round 3: performance.md updated with missing results, anti-pattern violations fixed
• Round 4: final verification pass confirms no gaps remain
• Compliance verified against docs/performance.md, docs/k8s.md, docs/authority.md

[abix-]

/review findings

Check	Result
Linked issue	pass (#248)
Issue acceptance checklist	pass (5/5 checked in PR body)
PR checklist coverage	pass
Associated docs	pass (this IS the doc update)
authority.md	pass (docs-only, no code)
k8s.md	pass (docs-only, no code)
performance.md	pass (this PR fixes performance.md)
Build	not required (docs-only)
Automated tests	not required (docs-only)
Regression tests	not required (docs-only)
Benchmarks	not required (docs-only)
BRP launch	not run
Issue-specific verification	pass (spot-checked file/line refs against codebase)

Verdict: ready to merge

Findings

• No findings. All file/line reference corrections verified against codebase.

Acceptance coverage

• Round 1 inventory: covered in issue comments (4 rounds documented)
• Round 2 violation detection: covered, no anti-pattern violations found
• Round 3 fixes: performance.md updated with 4 missing entries, stale refs fixed, max_pathfinds corrected 50->200
• Round 4 verification: final pass confirmed no gaps
• Compliance: all three docs checked

Spot-check verification

• COMBAT_BUCKET -> systems/decision/mod.rs:347 CONFIRMED
• max_decisions_per_frame -> resources.rs:188 CONFIRMED
• max_pathfinds_per_frame = 200 -> resources.rs:772 CONFIRMED (was incorrectly 50)
• time_scale text removal -> correct, constant 60 UPS via fix: constant 60 UPS at all time_scale speeds #244

[abix-]

/review findings

Check	Result
Linked issue	pass (#248)
Issue acceptance checklist	pass (5 items)
PR checklist coverage	pass (all 5 checked)
Associated docs	pass (performance.md IS the deliverable)
authority.md	pass (doc-only)
k8s.md	pass (doc-only)
performance.md	pass (this IS the audit)
Build	pass
Automated tests	pass (380/380)
Regression tests	not required (doc-only)
Benchmarks	not required (doc-only)
BRP launch	not run
Issue-specific verification	not run

Verdict: ready to merge

Findings

No findings. Clean doc audit.

Acceptance coverage

• Round 1: inventory -- stale refs found, missing opt log entries identified
• Round 2: violation detection -- no anti-pattern violations in hot paths
• Round 3: fixes -- 7 stale file refs fixed, 1 wrong value corrected, 4 opt log entries added, stale time_scale text removed
• Round 4: verification -- final pass confirms no gaps
• Compliance -- verified against all three docs

Docs and policy coverage

• performance.md -- this IS the audit target, updated correctly
• authority.md -- compliant (doc-only)
• k8s.md -- compliant (doc-only)

[abix-]

approved -- merging