wax-performance-audit

name	wax-performance-audit
description	Benchmarking and performance auditing for the Wax repo. Use when running or interpreting Wax benchmarks, diagnosing CPU, memory, or I/O bottlenecks, or investigating Swift 6.2 concurrency issues such as Sendable, actor isolation, `@unchecked Sendable`, task-group fan-out, and data races.

Wax Performance Audit

Overview

Use this skill to benchmark Wax changes, isolate the hottest code path, and separate real regressions from noisy samples.

The repo builds with Swift 6.1 and StrictConcurrency enabled, so audit for Swift 6.2 concurrency risks without assuming 6.2-only language mode.

Workflow

1. Name the symptom precisely: latency regression, memory growth, file bloat, or Swift concurrency diagnostics.
2. Pick the narrowest benchmark or test file that exercises the path.
3. Run a baseline and candidate with the same environment and scale.
4. Collect wall time plus memory or file-growth metrics when the issue is not purely CPU-bound.
5. Inspect the smallest relevant actor boundary, task group, cache, or I/O path.
6. Report the evidence, the bottleneck, and the smallest safe fix.

Benchmark Selection

Use references/benchmark-workflow.md for the command matrix, environment flags, and benchmark map.

Prefer these repo entry points when they match the symptom:

• Tests/WaxIntegrationTests/RAGBenchmarkSupport.swift
• Tests/WaxIntegrationTests/RememberDedupBenchmarks.swift
• Tests/WaxIntegrationTests/StoreBloatBenchmarks.swift
• Tests/WaxIntegrationTests/RAGBenchmarks.swift
• Tests/WaxIntegrationTests/RAGBenchmarksMiniLM.swift
• Tests/WaxIntegrationTests/BatchEmbeddingBenchmark.swift