feat: add physically explicit narrowband MUSIC

docs/data-contracts.md

@@ -29,7 +29,7 @@ snap과 zoom은 편집기 상태이며 `micarrsim.array` 계약에 포함되지
 `aperture.width/height`와 최종 `microphones` 좌표·순서만 들어간다. 따라서 다른 도구는
 형상 이름을 추론하지 않고 실제 좌표를 배열 geometry의 기준으로 사용해야 한다.
 
-Experiment의 필수 `beamforming.algorithm` enum은 `das`, `das-phat`, `gcc-phat`다. backend와
+Experiment의 필수 `beamforming.algorithm` enum은 `das`, `das-phat`, `gcc-phat`, `music`이다. backend와
 raw map 계약은 다음과 같다.
 
 | algorithm | `rawMap.scale` | 허용 backend |
@@ -37,11 +37,19 @@ raw map 계약은 다음과 같다.
 | `das` | `power` | `cpu`, `webgpu`; `auto` 가능 |
 | `das-phat` | `score` | `cpu`, `webgpu`; `auto` 가능 |
 | `gcc-phat` | `score` | `cpu`; `auto`는 CPU 선택 |
+| `music` | `noise-projection` | `cpu`; `auto`는 CPU 선택 |
 
-`gcc-phat`에 명시적 `webgpu`를 조합하면 검증 오류이며, 마이크가 두 개 이상이어야 한다. 필드
-그룹 이름 `beamforming`은 기존 계약과의 호환을 위해 유지하지만 세 알고리즘을 모두 선택하는 위치
+`gcc-phat` 또는 `music`에 명시적 `webgpu`를 조합하면 검증 오류이며, 마이크가 두 개 이상이어야 한다. 필드
+그룹 이름 `beamforming`은 기존 계약과의 호환을 위해 유지하지만 네 알고리즘을 모두 선택하는 위치
 추정 설정이다.
 
+MUSIC은 `normalization: "none"`만 허용한다. band마다 analog FFT-grid 가설을 정확히 하나
+선택하고, 접힌 양의 ADC bin 하나에서 snapshot covariance를 만든다. Fixed K는 `1..M-1`이다.
+Wax–Kailath `mdl`/`aic`는 complete non-overlapping frame, `T > M`, 엄격히 양수인 noise
+eigenvalue와 IID complex Gaussian snapshot·spatially white noise·고정 source 수를 가정한다.
+non-overlap은 독립성의 증명이 아니다. 조건 불충족은 fixed fallback 없이 typed
+`MUSIC_UNAVAILABLE`이다.
+
 선택적 `beamforming.compensateFrequencyResponse`는 기본 `true`다. 합성 channel에는 curve가
 항상 적용된다. DAS는 sensitivity와 정적 phase를 항상 역보정하고, 값이 `true`이면 선택 bin에서
 curve의 gain과 phase도 역보정한다. DAS-PHAT와 GCC-PHAT는 입력과 calibration의 amplitude gain을
@@ -51,7 +59,8 @@ curve의 gain과 phase도 역보정한다. DAS-PHAT와 GCC-PHAT는 입력과 cal
 선택적 `beamforming.maxCompensationDb`는 DAS가 응답 notch를 역보정할 때 양의 gain boost만
 제한하는 0–120 dB 값이며 생략 시 24 dB다. 응답 peak를 줄이는 attenuation과 phase 보상은 이
 boost 상한의 대상이 아니다. amplitude를 사용하지 않는 DAS-PHAT와 GCC-PHAT에는 이 값이 영향을
-주지 않는다. 세 알고리즘의 계산식과 한계는
+주지 않는다. MUSIC은 analog 가설에서 residual complex response를 일관되게 manifold에 넣는다.
+네 알고리즘의 계산식과 한계는
 [음향 환경과 마이크 응답 모델](acoustic-model.md)에 설명한다.
 
 ## 로컬 asset 재연결
@@ -127,7 +136,7 @@ sidelobe false positive도 늘 수 있다.
 
 ## Result 평가 정보
 
-Result 1.1은 최상위 필수 `algorithm`에 실제 실행한 `das`, `das-phat` 또는 `gcc-phat`를
+Result 1.1은 최상위 필수 `algorithm`에 실제 실행한 `das`, `das-phat`, `gcc-phat` 또는 `music`을
 기록하며 Experiment의 선택값과 같아야 한다. `backend`는 요청값 `auto`가 아니라 실제 사용한
 `cpu` 또는 `webgpu`다.
 
@@ -180,8 +189,10 @@ threshold와 최소 거리, sidelobe 제외 반경, half-power 비율, dynamic r
 경계의 `+Fs/2`와 `-Fs/2`는 같은 실수 sample이며, point provenance는 `+Fs/2`로
 canonicalize하고 fold segment endpoint는 zone 진행 방향에 따라 둘 중 하나를 기록한다.
 `localizationInputModel`은 one-sided real FFT bin만 사용함을 밝히며, `localizationModel`은
-DAS 계열의 구면 steering과 GCC-PHAT의 기하 lag를 구분한다. `originalCarrierUsed`는 항상
-`false`다. Nyquist 위 band의 `aliasOrderResolution`은 현재 `not-attempted`다.
+DAS 계열의 구면 steering, GCC-PHAT의 기하 lag와 MUSIC의 configured-analog-frequency
+near-field manifold를 구분한다. DAS/DAS-PHAT/GCC-PHAT의 `originalCarrierUsed`는 `false`이고
+Nyquist 위 band의 `aliasOrderResolution`은 `not-attempted`다. MUSIC의
+`originalCarrierUsed: true`는 Scene truth가 아니라 사용자가 지정한 analog 가설을 뜻한다.
 `equivalentBandIds`가 있으면 그 band들은 같은 ADC bin 집합을 공유하므로 독립
 관측으로 세면 안 된다.
 
@@ -206,8 +217,26 @@ Array·Scene·Experiment 계약 버전은 `1.0.0`, Result 계약 버전은 `1.1.
 `packages/contracts/schema-validator.js`로 저장소의
 실제 schema를 실행한 뒤 `validation.js`에서 다음 관계를 추가 검사한다.
 
-Acoustic Camera에서 Experiment를 가져올 때는 문서 자체를 먼저 검증한 뒤 `sceneId`와
-`arrayId`를 현재 열린 Scene·Array의 id로 연결하고, 그 context에서 관계 검증을 다시 수행한다.
+Acoustic Camera에서 Experiment를 가져올 때는 문서 자체를 먼저 검증한다. `sceneId`와
+`arrayId`는 provenance label이므로 현재 열린 Scene·Array ID와 비교해 거부하거나 값을
+덮어쓰지 않는다. 실행에는 현재 열린 geometry와 sample data를 사용하고, Result의
+`sceneId`/`arrayId`와 `inputHash`에는 실제 사용한 입력을 기록한다.
+
+## MUSIC Result 의미
+
+MUSIC의 `rawMap.scale`은 `noise-projection`이고
+`q = ||E_n^H a||²/(a^H a)`의 최솟값이 optimum이다. 표시용 `P/Pmax = q_min/q`도 q와 마찬가지로
+확률, likelihood, posterior 또는 신뢰구간이 아니다. `q_min = 0`이면 0인 cell만 1로 표시한다.
+Result의 `musicModel`과 band별 `musicDiagnostics`는 source-count 방법·가정,
+covariance/eigensolver 감사, analog/ADC alias와 CPU workload를 보존한다.
+
+MUSIC의 `originalCarrierUsed: true`는 Scene truth가 아니라 Experiment에 사용자가 지정한 analog
+FFT-grid 가설을 썼다는 뜻이다. analog carrier `f_a`와 관측 alias orientation `η`로
+`exp[-j η 2π f_a (r_m-r_ref)/c]`를 만들며, inversion이면 calibration과 steering을 포함한 전체
+complex manifold를 켤레화한다. Scene source carrier/위치 truth는 읽지 않는다. 정확한 DC/Nyquist
+bin은 quadrature-degenerate라 거절한다. diagonal loading, epsilon/floor, spatial smoothing,
+multibin averaging/association과 wideband fusion은 없다. grating lobe, 동률과 coherent-source
+rank deficiency는 숨기지 않고 map 또는 typed unavailable로 나타낸다.
 이 가져오기 편의 동작은 계약을 완화하지 않는다. 내보내기와 실행에 쓰는 Experiment도 아래 관계를
 모두 만족해야 한다.