fix: expose physical aliasing and delayed arrivals

docs/data-contracts.md

@@ -127,9 +127,8 @@ sidelobe false positive도 늘 수 있다.
 
 ## Result 평가 정보
 
-새 Result는 최상위 `algorithm`에 실제 실행한 `das`, `das-phat` 또는 `gcc-phat`를 기록하며
-Experiment의 선택값과 같아야 한다. 이 필드는 이전 `1.0.0` Result를 읽기 위해 schema상 선택적으로
-남아 있지만 현재 export에는 항상 들어간다. `backend`는 요청값 `auto`가 아니라 실제 사용한
+Result 1.1은 최상위 필수 `algorithm`에 실제 실행한 `das`, `das-phat` 또는 `gcc-phat`를
+기록하며 Experiment의 선택값과 같아야 한다. `backend`는 요청값 `auto`가 아니라 실제 사용한
 `cpu` 또는 `webgpu`다.
 
 관계 검증은 `das → power`, `das-phat/gcc-phat → score`를 강제한다. Peak에 `beamSpread`가
@@ -137,8 +136,8 @@ Experiment의 선택값과 같아야 한다. 이 필드는 이전 `1.0.0` Result
 구조상 유효하지만 의미가 모순된 외부 Result도 import 시 거절된다.
 
 `timingMs.localization`은 선택한 위치 추정 알고리즘의 wall time이다. 현재 export는 기존 DAS 전용
-소비자를 위해 같은 값을 `timingMs.beamforming`에도 호환 alias로 기록한다. `1.0.0` schema는 이전
-문서를 위해 `beamforming`을 여전히 필수로 두므로, 새 writer는 `localization`과 `beamforming`을
+소비자를 위해 같은 값을 `timingMs.beamforming`에도 호환 alias로 기록한다. `1.1.0` schema는
+`beamforming`을 여전히 필수로 두므로, 새 writer는 `localization`과 `beamforming`을
 함께 저장해야 한다. `timingMs.total`은 전체 시간이고 선택적 `signalGeneration`은 합성 시간이다.
 
 각 band의 `peaks`는 위치와 해당 `rawMap.scale`의 값, 선택적 `sourceId`, `localizationErrorM`,
@@ -168,14 +167,29 @@ threshold와 최소 거리, sidelobe 제외 반경, half-power 비율, dynamic r
 버전과 함께 저장한다. `environment`에는 실제 backend, microphone/grid 수, scan bounds와 z,
 가능한 경우 GPU adapter 및 fallback 정보를 기록한다.
 
-`signalStats`는 정규화 전 peak, scale과 clipping 수 외에 선택적으로
+`signalStats`는 정규화 전 peak, scale과 clipping 수 외에 필수 `sampling` provenance와 선택적
 `acousticModel`, 실제 전체 `acousticPathCount`와 `acousticPathCounts`를
 기록한다. 종류별 key는 `direct`, `reflection`, `scattering`,
 `diffraction`과 `diffuse`다.
 
-대역별 ground truth는 tone의 주파수가 band 안에 있을 때 그 tone source를 포함한다. noise와
-asset source는 현재 모든 band의 truth로 간주한다. 즉 녹음 asset의 실제 spectrum energy를
-대역별로 판정하는 계약은 아직 없으며, 이 가정은 실제 데이터 결과를 해석할 때 고려해야 한다.
+각 band의 필수 `frequencyObservation`은 연속 analog fold와 이산 FFT 계산 선택을 구분한다.
+`foldSegments`는 1-based Nyquist zone·반전·alias order를,
+`adcBins`/`adcBinCenterRanges`는
+`selectionModel: fft-bin-center-membership`으로 선택된 bin center를 뜻한다.
+요청 `minHz`와 `maxHz`에 정확히 놓인 FFT bin center도 선택한다. 정확한 Nyquist
+경계의 `+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`다.
+`equivalentBandIds`가 있으면 그 band들은 같은 ADC bin 집합을 공유하므로 독립
+관측으로 세면 안 된다.
+
+대역별 ground truth의 실제 정책은 evaluation의
+`truthSelection: tone-analog-interval-or-nearest-adc-bin-and-all-nontone-sources`에
+기록한다. Tone은 원 주파수가 요청 analog interval 안에 있거나, 접힌 주파수의 nearest ADC
+bin이 선택됐을 때 포함한다. noise와 asset source는 모든 band에 포함한다. 녹음 asset의
+spectrum을 임의 threshold로 분류하는 미검증 multiband 알고리즘은 사용하지 않는다.
 
 ## 재현성 hash
 
@@ -186,7 +200,10 @@ SHA-256을 계산해 scene의 해당 asset `sha256` 필드를 채운 상태로 c
 
 ## 버전과 검증
 
-현재 계약 버전은 `1.0.0`이다. 브라우저는 `packages/contracts/schema-validator.js`로 저장소의
+Array·Scene·Experiment 계약 버전은 `1.0.0`, Result 계약 버전은 `1.1.0`이다. Result
+`1.1.0`은 sampling provenance와 band별 fold/localization metadata를 필수화하므로 이전
+`1.0.0` Result와 구조적으로 호환되지 않는다. 브라우저는
+`packages/contracts/schema-validator.js`로 저장소의
 실제 schema를 실행한 뒤 `validation.js`에서 다음 관계를 추가 검사한다.
 
 Acoustic Camera에서 Experiment를 가져올 때는 문서 자체를 먼저 검증한 뒤 `sceneId`와
@@ -196,7 +213,7 @@ Acoustic Camera에서 Experiment를 가져올 때는 문서 자체를 먼저 검
 
 - 중복 id와 array/scene/experiment/result 참조
 - asset 종류와 안전한 상대 경로
-- Nyquist 및 시간·scan 범위
+- ideal sampler의 Nyquist alias mapping 및 시간·scan 범위
 - 마이크 주파수 응답점의 범위·정렬과 shoebox room/occluder 포함 관계
 - map shape와 source peak 매칭
 - band별 evaluation 파라미터와 허용 metric
@@ -204,6 +221,16 @@ Acoustic Camera에서 Experiment를 가져올 때는 문서 자체를 먼저 검
 
 지원하지 않는 schemaVersion은 묵시적으로 변환하지 않고 오류로 알린다.
 
+Scene tone과 Experiment band는 0–1 MHz 검증 범위 안에서 Nyquist를 넘어도 유효하다. 1 MHz는
+Nyquist 제한이 아니라 수치 위상 정밀도·마이크 응답·희소 음향 모델의 현재 검증 상한이다.
+이는 원 신호를 복원한다는 뜻이 아니라
+anti-alias filter가 없는 이상적 real ADC에서 접힌 bin을 관찰한다는 뜻이다. Result는
+`signalStats.sampling`과 band별 `frequencyObservation`에 원 주파수, signed ADC 주파수,
+spectral inversion, fold segment와 선택 bin center를 기록한다. 동일 ADC bin에 접힌 analog
+후보는 단일 channel의 시간 sample만으로 식별할 수 없다. 다채널 공간 위상에는 원 파장 정보가
+남을 수 있지만 현재 conventional localizer는 carrier hypothesis를 시도하지 않으며,
+validation이나 평가도 임의의 후보를 정답으로 선택하지 않는다.
+
 실측 channel을 받는 portable API는 저장 JSON 계약과 별도로 입력 Array를 같은 규칙으로 검사한다.
 CPU 분석 계획은 기본 512 MiB, 반복 steering cache는 64 MiB, streaming ring과 분석창은 기본
 256 MiB hard cap을 할당 전에 적용한다. 채널 순서와 streaming 상태 계약은