fix(analysis): score C major acceptance from decoded WAV bytes

AGENTS.md

@@ -63,6 +63,7 @@ This section applies to any agent (Claude, Codex, Cursor, opencode, ...) working
 ## Architecture references
 - `ARCHITECTURE.md`
 - `docs/engineering/acceptance-criteria.md`
+- `docs/doctoring/real-audio-accuracy-acceptance.md`
 - `docs/engineering/harness-engineering.md`
 - `docs/workflow/one-day-delivery-plan.md`
 - `docs/workflow/pr-continuity.md`
@@ -85,6 +86,7 @@ This section applies to any agent (Claude, Codex, Cursor, opencode, ...) working
 - Prefer practical, friendly, rehearsal-first wording over academic or authority-heavy language.
 - Do not reduce the product to a chord analyzer when form, timing, player coordination, simplification, and setup cues are the real rehearsal blockers.
 - Do not frame usability as a reason to accept weak analysis quality; BandScope should aim for both easy use and high accuracy.
+- Do not claim harmony or tempo accuracy from mocked feature matrices. Tier 1 decoded-PCM fixtures and metrics live in `docs/doctoring/real-audio-accuracy-acceptance.md`.
 
 ## Safety
 - Do not add network-dependent runtime paths for local analysis.

ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # ARCHITECTURE.md
 
-Last updated: 2026-03-11
+Last updated: 2026-08-16
 
 ## Brand source
 
@@ -127,3 +127,4 @@ Last updated: 2026-03-11
 - Supply-chain docs, workflow pinning, and lockfile verification are part of the default quickcheck path so dependency drift is caught early.
 - Quickcheck and CI are expected to verify dependency review, audit, supplemental inventory, and SBOM baseline presence as part of bootstrap.
 - Cross-platform build workflow presence and trigger coverage are part of the default supply-chain verification path.
+- Real-audio accuracy acceptance is a separate buyer-facing gate from unit coverage. Tier 1 decoded-PCM fixtures, duration-weighted chord recall, and tempo Acc1 live in `docs/doctoring/real-audio-accuracy-acceptance.md` and `bandscope_analysis.accuracy`.

CHANGELOG.md

@@ -4,6 +4,24 @@
 
 ### Added
 
+- Add Tier 1 real-audio accuracy acceptance: a decoded C major WAV must recover `C`, and a 120 BPM click WAV must pass tempo Acc1, with checksum-fail-closed reports.
+
+### Fixed
+
+- Reject click-track accuracy fixtures whose beat interval or click pulse cannot be represented by at least one sample, preventing aliased or all-zero tempo evidence from entering acceptance runs.
+- Reject fixture timings whose derived sample count overflows or quantizes below one sample, and reject finite BPM inputs whose derived beat interval becomes non-finite, before they can drive real-audio accuracy allocation or loop authority.
+- Reject malformed decoded-PCM accuracy evidence before chord recognition: the C-major acceptance buffer must be a non-empty, finite, floating-point, one-dimensional mono array and sample rates must be finite, positive, and non-Boolean.
+- Reject accuracy-report metric integers whose conversion overflows floating-point evidence instead of letting an `OverflowError` escape the manifest validation boundary.
+- Reject Boolean fixture duration, tempo, and sample-rate inputs so Python `True`/`False` values cannot become numeric real-audio acceptance authority or a 1 Hz WAV contract.
+- Reject Boolean chord timing and tempo metric inputs so `True`/`False` cannot masquerade as numeric MIR acceptance evidence through Python's `bool`-as-`int` semantics.
+- Reject blank or edge-whitespace-padded accuracy-report case IDs, metric names, and truth labels so portable acceptance evidence preserves exact registered identities.
+- Reject empty or reversed chord-estimate intervals before duration-weighted recall so malformed timing evidence cannot be silently ignored by an accuracy acceptance score.
+- Fail closed when accuracy-report provenance cannot resolve a non-empty product `VERSION`, instead of publishing an `unknown` engine version as valid evidence.
+- Reject non-finite chord annotation and estimate timings before duration-weighted recall so NaN/Inf evidence cannot fabricate covered duration.
+- Reject non-finite tempo estimates, ground-truth BPM values, and Acc1 tolerances as invalid accuracy evidence instead of recording them as ordinary misses.
+- Union overlapping matching chord-estimate intervals before duration-weighted recall so acceptance scores cannot double-count annotated time or exceed 100%.
+- Reject malformed accuracy-report provenance, including non-hex SHA-256 text and non-finite metric values, before acceptance evidence is consumed.
+- Score the C major acceptance case from checksummed on-disk WAV bytes instead of the pre-write in-memory triad.
 - Display the analyzed song tempo (BPM) as a badge in the rehearsal workspace.
 - 각 합주 역할(Role)별 개인 연습 진행도를 0~100% 범위로 기록 및 시각화할 수 있는 연습 진척도(`practiceProgress`) 트래커 기능 추가. UI 컨트롤(슬라이더 및 +/- 버튼)과 한/영 다국어 지원 포함.
 

CLAUDE.md

@@ -73,3 +73,4 @@ Supporting packages:
 - Lockfiles (`package-lock.json`, `uv.lock`, `Cargo.lock`) are committed and must stay in sync; GitHub Actions are SHA-pinned. Adding a direct dependency requires the admission rationale defined in `AGENTS.md` and `docs/security/dependency-policy.md`.
 - CI beyond quickcheck: `gate / ci / rust-check` (Tauri cargo check on macOS) and `build-baseline` Windows/macOS amd64+arm64 native builds are merge gates, alongside CodeQL, dependency-review, sbom, bandit, trivy, secret-scan, and security-audit workflows. Do not weaken or skip them.
 - Version metadata lives in `VERSION`, the root `package.json`, and `CHANGELOG.md`; release flow is tag-driven (see `docs/operations/deploy-runbook.md`).
+- Real-audio accuracy acceptance (decoded PCM, not mocked chroma) lives in `docs/doctoring/real-audio-accuracy-acceptance.md` and `bandscope_analysis.accuracy`.

docs/doctoring/real-audio-accuracy-acceptance.md

@@ -0,0 +1,140 @@
+# Real-audio accuracy acceptance
+
+Next action: before claiming a rehearsal result is accurate, run the Tier 1
+decoded-PCM cases. A green unit suite that never opens a WAV is not buyer
+evidence.
+
+```bash
+uv run --project services/analysis-engine pytest \
+  services/analysis-engine/tests/test_accuracy_acceptance.py \
+  services/analysis-engine/tests/test_accuracy_boolean_fixture_inputs.py \
+  services/analysis-engine/tests/test_accuracy_pcm_input_contract.py \
+  services/analysis-engine/tests/test_accuracy_manifest_version.py \
+  services/analysis-engine/tests/test_accuracy_metric_interval_contract.py \
+  services/analysis-engine/tests/test_accuracy_metric_overflow_contract.py
+```
+
+## Why this lock exists
+
+BandScope sells rehearsal guidance. A buyer cannot distinguish “the job
+succeeded” from “the engine heard the chord and tempo that are in the file”
+until decoded PCM is scored against a known label (Raffel et al., 2014).
+
+This layer is Tier 1 of issue #770: tiny, license-clean, deterministic WAV
+fixtures generated in process. It does not claim genre coverage, perceptual
+stem quality, or private-corpus readiness.
+
+## Held cases
+
+- `c-major-triad`: three seconds of C4+E4+G4 written to WAV, checksummed,
+  decoded from those bytes, and scored with duration-weighted chord recall.
+  Pass when recall of `C` is at least `0.70`. That floor is a BandScope Tier 1
+  tolerance. Matching estimate intervals are clipped to the annotation window
+  and unioned before duration is accumulated, so overlapping or duplicate
+  estimates cannot count the same annotated time twice or produce recall above
+  `1.0`. Annotation and estimate times must be finite non-Boolean numbers before
+  clipping, and each estimate interval must have a strictly increasing
+  start/end pair; Boolean, NaN, infinite, empty, or reversed timing is invalid
+  acceptance evidence and fails closed instead of being silently ignored or
+  allowed to fabricate covered duration. File-backed WAV evaluation accepts an
+  ordinary mono or multichannel WAV and deterministically downmixes decoded
+  multichannel samples to mono before the production recognizer runs. The direct
+  `evaluate_c_major_pcm` boundary is narrower: callers must provide a non-empty,
+  one-dimensional, finite floating-point mono PCM array and a finite positive
+  non-Boolean sample rate. Unresolved multichannel arrays passed directly,
+  integer arrays, NaN/infinite samples, or invalid rate evidence are rejected
+  rather than coerced at that direct evaluator boundary. The metric family is
+  WCSR/CSR (Odekerken et al., 2021; Raffel et al., 2014).
+- `click-120-bpm`: eight seconds of 120 BPM clicks decoded by
+  `TemporalAnalyzer`. Pass when estimated tempo satisfies Acc1 at 4%
+  (Schreiber & Müller, 2020). Acc1 does not credit half-time or double-time.
+  Estimated BPM, true BPM, and the tolerance must all be finite non-Boolean
+  numbers; Boolean or non-finite metric inputs are invalid acceptance evidence
+  and fail closed rather than being recorded as an ordinary miss. This matters
+  in Python because `bool` is an integer subtype and would otherwise satisfy
+  ordinary numeric comparisons.
+- Fixture generation and WAV serialization accept only finite positive
+  non-Boolean duration, BPM, and sample-rate evidence. In Python, `True` would
+  otherwise act as numeric `1`, which could create a one-second fixture, a
+  one-BPM click contract, or a one-Hz WAV while still looking type-compatible at
+  runtime. Derived fixture timing must also remain representable: the computed
+  fixture sample count, beat interval, and click-pulse width must each be finite
+  and must resolve to at least one sample at the requested rate. This prevents a
+  nominally valid high BPM from placing multiple beats onto the same sample and
+  prevents a low sample rate from producing an all-zero “click” fixture. Inputs
+  that overflow or undersample those derived quantities fail closed before
+  allocation, loop construction, or file serialization.
+- Checksum mismatch fails closed on both file evaluators. Do not score a
+  tampered file as a pass.
+- Machine-readable case reports are accepted only when the registered
+  provenance fields are present and typed, `audio_sha256` is exactly 64
+  hexadecimal characters, and `metric_value` is a finite numeric value.
+  Boolean, NaN, infinity, overflow-to-float, malformed digest, or missing-field
+  evidence fails closed rather than becoming a portable acceptance record.
+- When a caller does not provide an explicit engine version, report creation
+  resolves the repository product `VERSION`. Missing or empty `VERSION`
+  provenance fails closed; `unknown` is not accepted as a substitute for the
+  exact engine version required by the accuracy evidence contract.
+
+## Claim boundary
+
+A passing case supports only the registered fixture, metric, engine version,
+and tolerance. It does not establish universal musical correctness.
+
+Keys-left, keys-right, and acoustic-guitar roles still carry arrangement
+defaults (`C#`, `Emaj7`, `Eb`). Lead vocal harmony is the role that currently
+reflects the `other` stem recognizer. Do not treat those defaults as
+measured accuracy.
+
+## References
+
+Odekerken, D., Koops, H. V., & Volk, A. (2021). Improving audio chord
+estimation by alignment and integration of crowd-sourced symbolic music.
+*Transactions of the International Society for Music Information Retrieval,
+4*(1), 141–155. https://doi.org/10.5334/tismir.81
+
+Raffel, C., McFee, B., Humphrey, E. J., Salamon, J., Nieto, O., Liang, D., &
+Ellis, D. P. W. (2014). MIR_EVAL: A transparent implementation of common MIR
+metrics. In *Proceedings of the 15th International Society for Music
+Information Retrieval Conference* (pp. 367–372).
+
+Schreiber, H., & Müller, M. (2020). Music tempo estimation: Are we done yet?
+*Transactions of the International Society for Music Information Retrieval,
+3*(1), 111–125. https://doi.org/10.5334/tismir.43
+
+## Security Notes
+
+- Attack surface: generated WAV bytes, fixture duration/BPM/sample-rate inputs,
+  decoded PCM shape/dtype/finiteness/sample-rate evidence, SHA-256 digests,
+  recognizer segment timings, tempo estimates, product-version provenance, and
+  parsed case-report mappings passed into the accuracy acceptance path.
+- Trust boundary: untrusted audio, runtime numeric evidence, decoded buffer
+  structure, recognizer output, and manifests; trusted repo-controlled fixture
+  definitions, true labels, metric definitions, registered floors, and the
+  repository product `VERSION`.
+- Mitigations: no network, no shell, checksum fail-closed before C-major
+  decode and before tempo scoring, deterministic file-decoder downmix for
+  ordinary multichannel WAV input, non-empty finite floating-point
+  one-dimensional mono PCM admission at the direct C-major evaluator boundary,
+  finite positive non-Boolean decoded sample-rate evidence, overlap-safe chord
+  duration, finite non-Boolean annotation/estimate timing, strictly increasing
+  estimate intervals, finite non-Boolean tempo metric inputs, finite positive
+  non-Boolean fixture duration/BPM/sample-rate inputs, finite derived fixture
+  sample count, beat interval, and click-pulse width with a one-sample minimum,
+  strict SHA-256 syntax, finite-only report metric values including overflow
+  rejection, exact non-empty product-version provenance, bounded fixture
+  durations, and no copyrighted commercial recordings. Fixture paths are pytest
+  temp files; reports store SHA-256 and labels, not waveform bytes.
+- Test points: deterministic digest, C major recall after file decode, ordinary
+  stereo WAV downmix at the file-decoder boundary, direct decoded-PCM
+  empty/non-floating/non-finite/non-mono rejection and invalid sample-rate
+  rejection, overlapping matching intervals do not double-count annotation
+  duration, non-finite and Boolean chord annotation/estimate timing rejection,
+  empty/reversed estimate interval rejection, silence-on-disk vs in-memory
+  triad, 120 BPM Acc1, non-finite and Boolean tempo estimate / truth / tolerance
+  rejection, non-finite and Boolean fixture generation/WAV sample-rate
+  rejection, derived sample-count overflow and zero-sample rejection, beat-
+  interval overflow and sub-one-sample rejection, sub-one-sample click-pulse
+  rejection, checksum mismatch through both file evaluators, malformed/non-hex
+  manifest provenance, NaN/infinity/overflow report rejection, missing/empty
+  product `VERSION` rejection, and silence must not pass as C major.

docs/plans/2026-08-16-real-audio-accuracy-acceptance.md

@@ -0,0 +1,57 @@
+# Real-audio accuracy acceptance (Tier 1)
+
+**Goal:** Give BandScope a buyer-readable accuracy gate: decoded PCM from a
+known WAV must recover the expected chord or tempo, with a versioned report.
+
+**Architecture:** A new `bandscope_analysis.accuracy` package generates
+license-clean fixtures, scores them with documented MIR metrics, and emits a
+strict case-report schema. Tests write real WAV files and call production
+`ChordRecognizer` and `TemporalAnalyzer` helpers. Stem separation stays out
+of this slice.
+
+**Tech Stack:** NumPy, soundfile, librosa beat tracking, pytest.
+
+## Security Notes
+
+### Attack surface
+
+Generated WAV files, SHA-256 digests, decoded PCM arrays, and JSON-shaped
+accuracy reports.
+
+### Trust boundary
+
+Untrusted: any on-disk fixture bytes and any parsed report mapping.
+Trusted: in-repo generators, metric definitions, and registered floors.
+
+### Mitigations
+
+- No network and no shell interpolation.
+- Checksum mismatch raises before C-major decode and before tempo scoring.
+- Manifest parsing fails closed on missing or mistyped fields.
+- Fixtures are short, synthetic, and license-clean.
+
+### Test points
+
+- Deterministic C major digest
+- Duration-weighted C recall after file decode
+- Silence on disk fails even when a C major array exists in memory
+- 120 BPM Acc1 after file decode
+- Checksum mismatch through both file evaluators
+- Malformed report rejection
+- Silence must not pass as C major
+
+### Realistic threats
+
+A tampered fixture or a missing digest could be scored as a pass and then
+cited as release evidence.
+
+### Logging and privacy
+
+`TemporalAnalyzer` may log the fixture path. Tests use pytest `tmp_path`
+names only. Case reports keep SHA-256, metric, and labels; they do not store
+PCM.
+
+### Remaining risk
+
+Tier 1 does not cover Demucs stems, private commercial recordings, or
+CPU/GPU numeric parity. Those remain later #770 tiers.

services/analysis-engine/src/bandscope_analysis/accuracy/__init__.py

@@ -0,0 +1,45 @@
+"""Real-audio accuracy acceptance helpers for BandScope rehearsal analysis.
+
+Next action: run the Tier 1 fixture tests before claiming a harmony or tempo
+result is accurate. These helpers score decoded PCM against known labels. They
+do not replace Demucs stem separation or private-corpus benchmarks.
+"""
+
+from .evaluate import evaluate_c_major_file, evaluate_c_major_pcm, evaluate_click_tempo_file
+from .fixtures import (
+    C_MAJOR_LABEL,
+    DEFAULT_CLICK_BPM,
+    DEFAULT_SAMPLE_RATE,
+    assert_fixture_checksum,
+    read_pcm_wav,
+    render_c_major_triad,
+    render_click_track,
+    write_pcm_wav,
+)
+from .manifest import (
+    AccuracyCaseReport,
+    build_case_report,
+    parse_case_report,
+    read_product_version,
+)
+from .metrics import duration_weighted_chord_recall, tempo_acc1
+
+__all__ = [
+    "AccuracyCaseReport",
+    "C_MAJOR_LABEL",
+    "DEFAULT_CLICK_BPM",
+    "DEFAULT_SAMPLE_RATE",
+    "assert_fixture_checksum",
+    "build_case_report",
+    "duration_weighted_chord_recall",
+    "evaluate_c_major_file",
+    "evaluate_c_major_pcm",
+    "evaluate_click_tempo_file",
+    "parse_case_report",
+    "read_pcm_wav",
+    "read_product_version",
+    "render_c_major_triad",
+    "render_click_track",
+    "tempo_acc1",
+    "write_pcm_wav",
+]