optic-k-rebuild

OPTIC-K Index Rebuild Procedure

Operational runbook for rebuilding ga/state/voicings/optick.index. The index holds 313k guitar/bass/ukulele voicings as 112-dim OPTK v4-pp vectors. Rebuild is needed whenever:

• Schema hash changes (EmbeddingSchema.BuildCompactLayoutV4 layout string edit → CRC32 bump → old index hard-rejected by reader).
• Writer normalization semantics change (e.g. v4 global-L2 → v4-pp per-partition).
• Tag-enrichment logic changes (VoicingTagEnricher, VoicingAnalyzer, SymbolicTagRegistry).
• Chord-quality enumeration expands (new ChordPitchClasses entries that the corpus generator also uses).
• A leak-test or invariant-coverage run flags that corpus-encoded vectors drifted from the generator's intent.

Total wall-clock expectation

~140 seconds for 313k voicings on a modern dev machine. Breakdown:

• Guitar: ~136 s (667k raw → 298k unique via structural dedup → OPTIC-K embedding).
• Bass: ~2.5 s (12k raw → 7.8k unique).
• Ukulele: ~2.3 s (8.6k raw → 7.3k unique).
• Write step: seconds.

Always run in background (run_in_background: true) so the session isn't blocked. Poll the output file for progress.

⚠ Preflight — MANDATORY file-lock check

optick.index is memory-mapped by every running OptickSearchStrategy consumer. On Windows, any open mmap handle locks the file for writing. The rebuild's embedding phase succeeds normally, then the 5-second write step crashes with IOException if anything's still holding the file.

Known holders:

• GaApi.exe — the web service. Started manually or via launch profile.
• GaMcpServer.exe — spawned by Claude Code on demand via dotnet run --no-build.
• Any ad-hoc CLI or test runner that called OptickSearchStrategy and didn't dispose it.

Stop them first:

Get-Process -Name GaApi, GaMcpServer -ErrorAction SilentlyContinue | Stop-Process -Force
# verify
Get-Process -Name GaApi, GaMcpServer -ErrorAction SilentlyContinue

Or in bash:

tasklist | grep -iE "GaApi|GaMcpServer"
# then taskkill each PID
taskkill -F -PID <pid>