Verify genuine Google music constraints and separate metadata cache revisions

docs/MEDIA-CONSTRAINTS.md

@@ -0,0 +1,56 @@
+# Exact music identity filters
+
+The current source supports exact `media_artist` and `media_title` constraints
+in the desktop filter panel, CLI and read-only MCP. They compare genuine probed
+full tag fields using Unicode lowercase and trimmed outer whitespace. Both
+constraints combine with existing filters before lexical and ANN candidate
+limits; comment text cannot impersonate an artist or title.
+
+A metadata-only request can omit query text. It returns a bounded stable list
+without query inference. Missing tags yield no match, including in semantic
+search. This is a narrow, explicit constraint, not general natural-language
+no-answer detection. Blank or over-1024-byte request fields fail explicitly;
+oversized genuine tags remain keyword-searchable but have no exact identity key.
+
+SQLite schema 14 preserves legacy keyword tags without guessing structured
+identities from flattened text. Existing music needs a media indexing pass to
+populate the new fields. A separate durable metadata epoch refreshes filtered eligibility without changing
+the source-corpus snapshot during indexing. Metadata revision guards, same-stat event invalidation,
+deletions and eligibility-cache invalidation retain source freshness.
+
+CLI examples:
+
+```sh
+searchi search --db /path/to/index.db --media-artist "Nina Simone"
+searchi search --db /path/to/index.db --media-title "Feeling Good"
+searchi search --db /path/to/index.db "live recording" --media-artist "Nina Simone"
+```
+
+Replace `/path/to/index.db` with your existing media-indexed database. The desktop controls are **Artist (exact)** and
+**Track title (exact)**. v0.1.4 downloads predate these additions.
+
+Windows CPU checks: the full ordinary workspace suite passed (asset-dependent
+checks remain explicitly ignored). Shared migration/lifecycle/eligibility tests, five CLI unit
+tests including real MCP response, 48 native desktop tests and 61 frontend tests
+passed. Strict workspace/CLI/native Clippy and formatting passed; frontend build
+passed. Native visual interaction remains unexecuted. Actual Google CPU integration also passed in 58.59 seconds (whole test, not
+search latency): two owned two-second 16 kHz mono PCM WAVs carried real
+artist/title tags and identical audio. The initial generation made two actual
+audio encodes. Query-role semantic and hybrid searches with limit one returned
+the eligible file, absent artist/field-collision constraints returned empty,
+metadata-only traces contained no query embedding, and same-stat invalidation,
+actual media refresh and deletion remained correct with warmed readers.
+
+The normal auto worker was forced to CPU with one thread. Its SHA-256 was
+`c01cb3ec13cfca722ee768e8350e1399a8b9a4d14a24a35adc3473a5cfc82a73`.
+The first integration run failed because metadata publication advanced the
+source-corpus revision; the separate metadata epoch corrected this, and the
+rerun passed. Service tests and strict workspace Clippy passed after the fix.
+This tiny identity-contract test does not measure music understanding or general
+no-answer quality.
+
+Reproduce with verified assets/helpers and `SEARCHI_FORCE_CPU=1`:
+
+```sh
+cargo test -p searchi-service --test media_constraints_google_cpu --locked -- --ignored --nocapture --test-threads=1
+```