fix: expose physical aliasing and delayed arrivals

docs/acoustic-model.md

@@ -82,6 +82,38 @@ Scene JSON의 사용자 설정 예는 다음과 같다.
 하며 occluder id는 중복될 수 없다. 사용자 설정에서도 마이크 좌표가 room 안에 놓이도록 구성해야
 1차 반사가 생성된다.
 
+## 라이브 창의 전파 지연과 이동 근사
+
+라이브 frame의 출력 sample 구간을 `[S, E)`, 현재 quasi-static geometry에서 모든
+source–microphone 희소 경로의 최대 지연을 `Dmax`라 하자. 합성기는 다음 순서로 frame을 만든다.
+
+1. source trajectory를 출력 창 중앙 시각에서 한 번 샘플링한다.
+2. `R = max(0, S - ceil(Dmax × sampleRate))`부터 `E`까지의 tone, noise와 asset 방사 신호를
+   원래 Scene 절대 sample index로 생성한다.
+3. 이 pre-roll buffer에 direct, reflection, scattering, diffraction과 diffuse 경로를 적용한다.
+4. 전파가 끝난 뒤 `[S, E)`만 crop하여 localizer에 넘긴다.
+
+따라서 source가 `S` 전에 멈췄더라도 그 직접음·반사음·diffuse tail이 창 안에 도착하면 보존된다.
+analytic tone뿐 아니라 deterministic noise index와 asset 재생 위치도 원래 절대 시간축을 유지한다.
+`synthesis.windowing`과 live frame의 `signalStats.windowing`은 render/output sample, pre-roll,
+최대 지연, geometry와 Doppler 정책을 기록한다.
+source별 `sourceArrivals`는 각 midpoint path의 half-open 도착 sample 구간이 출력과 겹치는지와
+겹친 path kind를 기록한다. live ground-truth 평가는 emission midpoint가 아니라
+`arrivingSourceIds`를 사용하므로, 이미 멈춘 source의 tail을 false positive로 잘못 세지 않는다.
+이 ID 집합은 위치 추정이 끝난 뒤 평가에만 쓰며 raw channel, STFT, steering이나 peak 검출에는
+입력하지 않는다.
+
+다만 이는 moving wave equation 해법이 아니다. pre-roll 방사 시각의 retarded source 위치를 다시
+구하지 않고 전체 render buffer에서 창 중앙 위치와 그 위치의 경로를 고정한다. 창 안의 연속 이동,
+Doppler, 시간에 따라 변하는 reflection geometry도 모델링하지 않는다. 움직임이 경로 지연에 비해
+크다면 frame 길이를 줄여 quasi-static 오차를 드러내고 수렴성을 확인해야 한다.
+
+sampled asset/noise의 fractional delay와 microphone response는 zero-padded block FFT 전달함수다.
+pre-roll은 현재 희소 **전파 경로**의 최대 지연을 보존하지만, 측정된 주파수 응답에서 무한하거나
+임의 길이의 causal analog impulse response state를 복원하지 않는다. 또한 Scene이
+`mix.normalization: peak`이면 live 합성은 각 출력 crop의 peak로 scale을 계산하므로 frame 간
+절대 진폭 비교에는 `normalization: none`을 사용해야 한다.
+
 ## Camera 환경 preset과 비용
 
 Camera의 **고급 설정 → 음향 환경**은 현재 geometry 전체가 들어가도록 room을 자동 추론하고 다음
@@ -184,6 +216,66 @@ band는 주기적으로 같은 phase를 만드는 lag가 많아 여러 위치가
 해결하지는 않는다. 단일 reference 방식은 모든 마이크 쌍을 쓰는 GCC보다 계산량이 작지만 pair
 중복성과 고장 마이크에 대한 강건성도 작다.
 
+## 샘플링, Nyquist와 alias
+
+Scene의 `sampleRate`는 모든 마이크가 동시에 동작하는 이상적 real-valued ADC의 sampling rate다.
+현재 모델에는 analog anti-alias filter가 없다. 따라서 tone 주파수는 Nyquist를 넘어도 허용되며,
+관측 주파수는 다음 signed baseband 주파수로 접힌다. 정확한 Nyquist tie는 `+Fs/2`로
+표준화하지만 `+Fs/2`와 `-Fs/2`는 같은 real sample sequence다.
+
+```text
+f_wrapped = f_analog mod Fs,  0 <= f_wrapped < Fs
+f_signed  = f_wrapped              if f_wrapped <= Fs/2
+            f_wrapped - Fs         otherwise
+f_adc    = |f_signed|
+```
+
+`f_signed < 0`이면 one-sided positive spectrum이 반전된다. 정확히 DC나 Nyquist에 접힌 tone은
+quadrature 정보가 소실되는 퇴화점이다. Camera는 이를 오류로 숨기지 않고 source 요약, band legend와
+Result `signalStats.sampling`에 원 주파수·signed ADC 주파수·반전 여부와 DC/Nyquist
+위상 퇴화 여부를 기록한다.
+
+공간 전파는 alias 주파수로 바꾸지 않는다. 합성기는 각 path의 원래 analog 주파수
+`2π f_analog τ`로 지연 위상과 해당 주파수의 microphone response를 적용한 뒤 ADC 시각에서
+sampling한다. 이 순서를 뒤집으면 fractional path delay의 센서 간 위상이 틀리므로, tone은
+mic/path별 analytic phasor와 시작·종료 event로 합성한다.
+
+Experiment band도 Nyquist 위 값을 허용한다. 요청 주파수 구간의 모든 등가 one-sided real-FFT
+bin **center**를 접어 선택하며, 일부 alias 후보를 골라 버리지 않는다. 이 선택은 brick-wall
+대역 필터가 아니다. 유한 Hann window의 off-grid leakage는 인접 bin에도 남는다. 현재
+DAS·DAS-PHAT는 양의 ADC bin 주파수로 구면 steering하고, GCC-PHAT는 선택 bin으로 제한한
+기하 lag correlation을 수행한다. 어느 쪽도 원래 alias order를 이용해 결과가 좋아지도록
+보정하지 않는다.
+따라서 초과 주파수에서 peak가 틀어지거나 grating lobe·동률 peak가 나타나는 것이 정상적인 설계
+결과일 수 있다. Result의 band별 `frequencyObservation`은 1-based Nyquist zone별 연속 fold
+segment, 반전·alias order, 실제 ADC bin center, 연속/FFT-grid many-to-one 여부와
+alias-equivalent band ID를 보존한다. 같은 `adcBinSetKey`를 가진 band는 독립 관측이 아니다.
+
+정확한 Nyquist 경계에서 `+Fs/2`와 `-Fs/2`는 실수 sampling sequence가 동일하다.
+단일 주파수 provenance는 이를 `+Fs/2`로 canonicalize하지만, `foldSegments`의
+`signedAdcStartHz`/`signedAdcEndHz`는 각 zone을 따라가는 방향을 보존하므로 반전 zone
+시작점이 `-Fs/2`로 나타날 수 있다. 경계를 가로지르는 두 segment의 `+Fs/2`와
+`-Fs/2` endpoint는 두 관측이나 두 FFT bin이 아니라 같은 phase-degenerate Nyquist
+sample을 양쪽 zone에서 표현한 것이다.
+
+같은 이유로 위치 추정기의 선택적 microphone-response 역보정도 관측 ADC bin에서 평가한다. Forward
+tone 합성은 원 analog 주파수의 응답을 사용하므로, Nyquist 위 carrier를 알고 보정하는 별도
+alias-aware 알고리즘처럼 동작하지 않는다. 이 차이 역시 감추지 않는 현재 알고리즘의 결과다.
+
+서로 다른 analog tone이 같은 ADC bin으로 접히면 **단일 channel의 시간 sample만으로는**
+원 주파수를 구별할 수 없다. 그러나 이 합성기는 원 analog 파장의 센서 간 위상을 보존하므로,
+충분히 촘촘하고 보정된 다채널 array에는 carrier order를 판별할 공간 위상 증거가 남을 수 있다.
+현재 DAS·DAS-PHAT·GCC-PHAT는 carrier hypothesis를 열거하는 알고리즘이 아니므로 이를 복원하지
+않고 Result에 `aliasOrderResolution: not-attempted`로 기록한다. 이 기능을 추가하려면 검증된
+array-processing 방법과 별도 alias-order 평가가 필요하며, 임의 규칙으로 peak를 고르지 않는다.
+audio asset과 noise는 이미 sampling된 baseband 신호로 취급하므로 파일에 없는 Nyquist 위 analog
+spectrum을 만들어 내지 않는다.
+
+Tone과 band의 현재 검증 범위는 0–1 MHz다. 이는 Nyquist 제한이 아니라 JavaScript
+IEEE-754 위상 정밀도, 마이크 응답 계약과 현재 희소 경로 모델을 함께 검증한 수치 범위다.
+더 높은 carrier가 필요하면 단순히 상한을 제거하지 말고 phase reduction과 microphone model을
+그 범위에서 다시 검증해야 한다.
+
 ## 마이크 주파수 응답
 
 각 마이크에는 2–64개의 측정점을 지정할 수 있다. `frequencyHz`는 0–1,000,000 Hz에서
@@ -212,6 +304,11 @@ band는 주기적으로 같은 phase를 만드는 lag가 많아 여러 위치가
 합성기는 알고리즘과 무관하게 sensitivity, 정적 phase offset과 frequency-response curve를 수신
 channel에 적용한다. 위치 추정에서의 역보정은 알고리즘별로 다르다.
 
+Tone에는 원 analog carrier에서 보간한 하나의 complex response를 정상상태 phasor로 적용한다.
+따라서 지속 sinusoid의 gain/phase 비교에는 맞지만, hard-gated 시작·종료에서 실제 analog
+마이크 필터가 만드는 ringing이나 frequency-dependent transient까지 계산하는 full LTI filter
+모델은 아니다. 이 근사를 ADC를 포함한 완전한 하드웨어 시뮬레이션으로 해석하지 않는다.
+
 - DAS는 sensitivity 역 gain과 정적 phase를 항상 보정한다. `compensateFrequencyResponse`를
   생략하거나 `true`로 두면 response의 역 gain과 phase도 보정한다. 응답 notch의 무제한 gain
   boost는 noise까지 키울 수 있으므로 `maxCompensationDb`로 제한하며 기본값은 24 dB, 허용 범위는

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 상태 계약은

docs/execution-plan.md

@@ -113,9 +113,15 @@ Scene·Array·Experiment·Assets 준비 상태와 실행 가능 여부를 가까
 일상적으로 바꾸는 backend, grid, 대역과 peak 감도는 설정 단계에 유지한다. 음속, seed, scan
 범위, STFT, 음향 환경 preset과 마이크 응답 보상은 **고급 설정**에 묶는다. 장문의 개발 요구나
 미구현 기능 홍보는 작업 화면에서 제거하고, 물리 모델·데이터 계약·포팅 설명은 문서로 연결한다.
-잘못된 단위, Nyquist 초과 대역, room 포함 관계와 CPU/GPU·신호 working-set 한도는 실행 전에
+잘못된 단위, room 포함 관계와 CPU/GPU·신호 working-set 한도는 실행 전에
 검증한다.
 
+Nyquist 초과 tone/band는 배열 설계 실패 양상을 관찰할 수 있도록 허용한다. tone은 analog path
+phase와 microphone response를 먼저 적용한 뒤 ideal ADC에서 sampling하고, band는 모든 등가 ADC
+bin center로 접는다. 원 carrier를 이용한 숨은 steering이나 결과 선택은 하지 않으며, 연속
+Nyquist-zone fold·이산 bin 선택·알고리즘별 localization model·동일 ADC band를 Result 1.1에
+기록한다. 0–1 MHz는 Nyquist cutoff가 아니라 현재 수치/마이크 모델의 검증 범위다.
+
 ## 6. 평가 방법
 
 점 음원 위치를 image plane으로 투영해 ground-truth heatmap과 위치 목록을 함께 저장한다. 최소
@@ -217,8 +223,9 @@ hardware deadline과 정확도는 장치 adapter가 정해진 뒤 별도 측정
   한도의 fixed ring streaming core에서 처리하고 overload의 `droppedSamples`를 감시한다.
 - 데이터셋 부적합/라이선스: 로컬 asset 계약을 유지하고 synthetic fixture를 기본 test 입력으로
   쓴다. 실제 데이터 adapter는 단계 5의 라이선스 검토 뒤 추가한다.
-- 실제 AC와 simulation gap: gain·phase·주파수 응답과 희소 실내 환경을 비교 조건으로 제공하되,
-  위치 공차·self-noise·ADC·clock은 실측 adapter와 현장 검증으로 다룬다.
+- 실제 AC와 simulation gap: gain·phase·주파수 응답, ideal real ADC sampling/alias와 희소 실내
+  환경을 비교 조건으로 제공하되, 위치 공차·self-noise·ADC quantization/nonlinearity와
+  channel clock jitter/drift는 실측 adapter와 현장 검증으로 다룬다.
 - post-processing이 기본 결과를 가림: 알고리즘별 raw power/score map과 후처리 map을 별도로 보존한다.
 
 ## 10. 구현 결과와 다음 백로그

docs/index.html

@@ -269,7 +269,7 @@
           </details>
           <details>
             <summary>Experiment를 가져왔는데 검증 오류가 남습니다.</summary>
-            <p>참조 ID는 현재 Scene·Array에 자동으로 연결됩니다. 실행할 수 없다면 검증 카드에서 Nyquist, scan 범위, asset처럼 재연결 뒤 확인된 실제 입력 오류를 확인하세요.</p>
+            <p>참조 ID는 현재 Scene·Array에 자동으로 연결됩니다. Nyquist 위 tone·band는 ideal ADC alias로 실행되며 원/관측 주파수가 함께 표시됩니다. 실행할 수 없다면 검증 카드에서 scan 범위, asset처럼 재연결 뒤 확인된 실제 입력 오류를 확인하세요.</p>
           </details>
           <details>
             <summary>Assets가 준비되지 않습니다.</summary>

docs/realtime-porting.md

@@ -167,7 +167,10 @@ const plan = createLocalizationPlan({
 주요 검증 조건은 다음과 같다.
 
 - `fftSize`는 2 이상의 2의 거듭제곱이고 `hopSize <= fftSize`
-- band는 하나 이상이며 `0 <= minHz < maxHz < sampleRate / 2`
+- band는 하나 이상이며 `0 <= minHz < maxHz`. Nyquist 위 구간은 anti-alias filter 없는 ideal
+  real ADC의 등가 baseband bin으로 접힌다. 단일 channel 시간 sample은 원 alias order를
+  복원하지 못하지만 다채널 공간 위상에는 원 파장의 증거가 남을 수 있다. 현재 portable
+  localizer는 carrier hypothesis를 열거하지 않는다.
 - scan의 `columns`와 `rows`는 양의 정수
 - `speedOfSound`는 양수
 - `normalization`은 `peak` 또는 `none`