Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
Integrate acoustic episodes as opt-in reports and fix recorded-data regressions
Cinna Davis838cda67cb52
diff --cc .github/workflows/tests.ymlindex 505d90c,b74ac21..6ba7f34--- a/.github/workflows/tests.yml+++ b/.github/workflows/tests.yml@@@ -47,6 -45,6 +45,8 @@@ jobsrun: python scripts/check_country_profiles.py --online --cache-root "$RUNNER_TEMP/dopplergeist-geography"- name: Check terrain seams against observed Copernicus raster footprintsrun: python -m pytest -q tests/test_real_terrain_tile_seams.py++ - name: Check experimental episode artifacts from recorded media++ run: python -m pytest -q tests/test_real_episode_artifact.py tests/test_real_episode_motion.py tests/test_real_episode_cli.py- name: Check progress reporting against recorded empty-tile checkpointsrun: |python - <<'PY'diff --cc README.mdindex df82dd8,f077981..788a6fa--- a/README.md+++ b/README.md@@@ -120,8 -120,8 +120,13 @@@ Automatic discovery scans an entire rec--output results/my-discovery```- Read `results/my-discovery/summary.json` and the schema-2 episode catalog under `discovery/`. Proposal counts refer to canonical episodes; measured child tracks are counted separately. Acoustic episodes do not establish aircraft identity or physical source motion. See [Audio discovery](docs/AUDIO_DISCOVERY.md) for settings, evidence and failure modes.+ Read `results/my-discovery/summary.json` and the diagnostics under `discovery/`. See [Audio discovery](docs/AUDIO_DISCOVERY.md) for settings, evidence and failure modes.+++The [experimental acoustic-episode scanner](docs/AUDIO_DISCOVERY.md#experimental-acoustic-episodes)++requires `--experimental-episodes`. It produces acoustic reports and does not change++the default scanner or upload workflow. Its recorded comparison includes missed++baseline signals and higher runtime.+### Run the local upload applicationStart the browser application:diff --cc benchmarks/acoustic-episodes-349/README.mdindex 9326c8a,0000000..2f24643mode 100644,000000..100644--- a/benchmarks/acoustic-episodes-349/README.md+++ b/benchmarks/acoustic-episodes-349/README.md@@@ -1,40 -1,0 +1,74 @@@+# Real acoustic-episode comparison++See [the engineering report](../../docs/ACOUSTIC_EPISODES_REPORT.md) for the fixed+selection, expectations, measurements, regressions, limits and reproduction.+++## Integration status++++The integrated scanner requires `--experimental-episodes`. Default discovery and++the automatic upload workflow retain the existing version-1 scanner. In these++frozen files, `new`, `default`, and `wide` describe experimental comparison arms.++They do not identify the current product default.++++This package preserves the original results, including missed baseline signals++and higher runtime. Module isolation does not establish new end-to-end results,++aircraft recall, or location accuracy.++++The integration corrects child duration and support diagnostics that a loop flag++overwrote. These frozen artifacts retain the historical incorrect child diagnostics.++Canonical group acceptance computes duration independently. The saved measurements++remain unchanged.++++## Frozen artifacts+++- `manifest.json`: all 32 actual input identities, public sources, rights and+ processing. Restore media to its relative `path` entries before running.+- `comparison.csv`: all cases, with old/new/wider proposal and child counts,+ union observed time, old-point overlap, time, RSS, output volume and code identity.+- `observations.jsonl.gz`: one JSON object per input, retaining complete baseline,+ new and optional wide discovery observations; no audio. `wide=null` is expected+ only for the hour-long reference, outside the wide arm.++The baseline is 451b67f; the frozen new comparison is 05548ed. Per-case content+hashes, settings and runtime are inside the new artifacts. Failed-check counts+can exceed rejected candidates because a candidate may fail several checks.- The final reporting-only patch exposes separate sustained/brief gate diagnostics;++The subsequent reporting-only patch exposes separate sustained/brief gate diagnostics;+accepted events/episodes were checked unchanged on the real rich-family clip.+++For a current experimental replay, run from the repository root after restoring++the real media and checking the manifest hashes:++++```bash++.venv/bin/python scripts/validate_acoustic_episodes.py \++ --manifest benchmarks/acoustic-episodes-349/manifest.json \++ --source-root . --output results/new-episode-comparison \++ --experimental-episodes++```++++This command produces new results from the current source. It does not reproduce++the historical source pin by selecting that pin automatically. The report gives++the baseline, wider-band, and historical replay instructions. The current runner++requires `--experimental-episodes` for experimental arms and omits it for the++baseline. The historical `05548ed` runner predates that switch.+++AeroSonicDB is by Downward and Nordby, CC BY-NC 4.0; DEMAND is by Thiemann, Ito+and Vincent, CC BY-SA 3.0; DLR RECORD139 is CC BY 4.0 (see source record and the+existing extraction report). The reference source's redistribution permission+is unestablished. Media are not included. This package contains factual derived+frequency measurements and diagnostics; it makes no aircraft, source-motion,+source-count or localization-accuracy claim.++Inspect the saved measurements with:++```python+import gzip, json+with gzip.open('benchmarks/acoustic-episodes-349/observations.jsonl.gz', 'rt') as f:+ for line in f:+ row = json.loads(line)+ print(row['case_id'], row['new']['counts'])+```++`family-episodes.png` uses AeroSonicDB measurements (Downward and Nordby,+CC BY-NC 4.0). `vehicle-episodes.png` uses DEMAND measurements (Thiemann, Ito+and Vincent, CC BY-SA 3.0). Both show canonical episode plots from the fixed+comparison, with source identity unresolved.diff --cc docs/ACOUSTIC_EPISODES_REPORT.mdindex 24cd238,0000000..7ae24ecmode 100644,000000..100644--- a/docs/ACOUSTIC_EPISODES_REPORT.md+++ b/docs/ACOUSTIC_EPISODES_REPORT.md@@@ -1,246 -1,0 +1,297 @@@+# Acoustic episodes: implementation and real-recording comparison (#349)+- This changes the acoustic proposal model, fragment ordering, elapsed-time checks- and frequency-coverage contract. It does **not** demonstrate better aircraft++The experiment changes the acoustic proposal model, fragment ordering, elapsed-time++checks and frequency-coverage contract. It does **not** demonstrate better aircraft+recall, physical-source identification or localization. Some real baseline+signals regress, and wider coverage returns additional confusing-source proposals.+++## Integration status++++The integrated implementation is an experimental acoustic-report path in++`dopplergeist.episode_discovery`. The installed `discover` command and checkout++scanner require `--experimental-episodes` to select it. Default discovery retains++the existing version-1 scanner. Automatic analysis and upload jobs retain that++scanner too.++++The frozen results below describe the historical experiment. Labels such as++`new default` mean the experimental implementation with its original settings.++They do not identify the current product default. The integration preserves all++measurements, zeros, misses, and reported runtime regressions. It does not++establish new end-to-end results or location accuracy.++++The matching adapter also corrects indexing after an ineligible group is skipped.++Its regression uses recorded measurements and changes only eligibility metadata.++Generated coordinate-array tests are excluded from the integration and CI.++++The integration also corrects child duration and support diagnostics that a loop++flag overwrote. Canonical group acceptance computes duration independently. The++frozen artifacts retain their historical child diagnostics, including those++incorrect values. Their measurements and results remain unchanged.++++## Historical source revisions+++Starting `origin/main`: `451b67f01dcd1dfe44d47c42407f404706a5a9b7`.+Worktree: `/home/cinna/dopplergeist-acoustic-episodes`, branch- `feat/acoustic-episodes`. Current-main integration is pinned in benchmark commit++`feat/acoustic-episodes`. The historical comparison is pinned in benchmark commit+`05548ed1cb0954db8fac960523e39300dc97308d`; detector code is frozen in a separate+validation checkout. The subsequently merged optional coherent adapter retains+its legacy helpers and passes its own recorded Michigan-trace tests. That+adapter was not used to supplement or improve this comparison.++## Engineering choices++The canonical episode catalog references all measured children. Constant-scale+fits replace a ratio-dictionary/base-ridge grouping decision. They require+resolved shared motion and temporal support; noninteger relationships also need+measured envelope agreement. Multi-component groups need multiple witnesses and+one consistent scale model over every supported pair. This intentionally leaves+some related fragments split when their relationship cannot be resolved without+single-link chaining. An unresolved relation is not evidence of source independence.++Provisional four-observation paths survive through chunk deduplication and+continuation association before duration rejection. Observation cells, gaps,+prediction residuals, uncertainty and episode support determine acceptance.+Brief events have a stronger, separately exposed path. Linking and rejection use+actual seconds in both directions, with a one-turn allowance rather than a+compulsory descending template. Source motion remains unconfirmed.++A bounded higher-rate single-spectrum path avoids band-duplicate accounting and- selects decoding rate before discarding frequencies. Defaults stay 40–1600 Hz;++selects decoding rate before discarding frequencies. Experimental settings default to 40–1600 Hz;+20 Hz lower coverage and 6000 Hz upper coverage were exercised separately.+Coverage, work limits, failures, input/code identities and runtime are explicit.+Normal noise diagnostics aggregate counts and measured/threshold ranges. Group+plots render once, and the matching adapter consumes fitted scales once per+canonical episode, retaining the legacy path for old events. See- [the full contract and thresholds](AUDIO_DISCOVERY.md).++[the experimental command and artifact contract](AUDIO_DISCOVERY.md#experimental-acoustic-episodes).++## Inputs, expectations and inspection++The [32-input manifest](../benchmarks/acoustic-episodes-349/manifest.json) includes+SHA-256, public source, rights, processing, context and predeclared expectations.+No new media is committed. Unique source duration is approximately 157 minutes:++- First two publisher-aircraft and first two publisher-background clips in each+ location stratum of the existing seed-20261103 AeroSonicDB sample: six 60-second+ aircraft-context clips and six 10-second background-context clips. Downward+ and Nordby, [AeroSonicDB v1.1.2](https://zenodo.org/records/10215080), CC BY-NC 4.0.+- The existing seven-second center-microphone DLR RECORD139 excerpt, with the+ documented constant gain: [source and exact extraction](../benchmarks/dlr-record139-scanner-check-20261103.md),+ [publisher record](https://zenodo.org/records/20494053), CC BY 4.0.+- All 18 available full, unpadded, channel-1 DEMAND recordings, about 300 seconds+ each, including home machinery, nature, public spaces and transport. Thiemann,+ Ito and Vincent, [DEMAND](https://zenodo.org/records/1227121), CC BY-SA 3.0.+ Existing extracted 16 kHz media were reused and individually identified by+ checksum; upstream ZIP integrity was not rechecked during this task.+- The existing hour-long public-reference WAV from the source release, identified+ separately from its MP3 representation. Redistribution permission for the+ original source is unestablished; only derived measurements are saved here.++Every fixed case is retained, including zero and unfavorable results. No filename+exceptions, flight data, coordinates or trajectory fits enter discovery. Context+labels do not certify source identity or aircraft absence. The selection is a+small development set, not a sealed holdout or a calibrated false-positive sample.++Before judging final replays, spectra without proposal overlays were reviewed+for the six aircraft-context clips. The clear family in case-0001, the descending+family in case-0033, and the clearly rising structure at about 50–59 seconds in+case-0013 are useful acoustic checks. Cases 0002, 0039 and 0008 have broadband+masking or weak continuity; their ambiguity remains explicit. These visual+judgments are qualitative, not exhaustive event annotations. They did not change+the frozen expectations to match output counts. Detailed views of the reference+proposals and transport/nature controls were also inspected. No audio playback+or physical-source labeling was used.++## Measured behavior+- All 32 default cases and all 31 wider-coverage cases completed. The hour-long++All 32 experimental cases at default settings and all 31 wider-coverage cases completed. The hour-long+input was not run at 6 kHz in the wider arm. The complete+[case table](../benchmarks/acoustic-episodes-349/comparison.csv) and compressed+[measured observations](../benchmarks/acoustic-episodes-349/observations.jsonl.gz)+retain the negatives, child tracks, canonical memberships, diagnostics and code+identities. Counts below are acoustic proposals.+- | Input/context | Old groups / children | New default episodes / children | Wider 40–6000 Hz |++| Input/context | Old groups / children | Experimental 40–1600 Hz episodes / children | Experimental 40–6000 Hz |+| --- | ---: | ---: | ---: |+| Six aircraft-context clips | 2 / 6 | 2 / 9 | 3 / 12 |+| Six background-context clips | 0 / 0 | 0 / 0 | 0 / 0 |+| DLR seven-second flyover | 0 / 0 | 0 / 0 | 0 / 0 |+| Eighteen DEMAND contexts | 2 / 2 | 7 / 10 | 14 / 19 |+| Hour-long reference | 16 / 18 | 30 / 38 | Not run |++The wider arm still proposes in the **same two of six** aircraft-context clips;+its third proposal is additional multiplicity in case-0001, not recovery of a+third clip. The old 12-second gate made its background zeros inevitable on+10-second clips. The new brief path is duration-eligible there, but six zero+results still do not estimate a population false-alarm rate.++Case-0001 has six measured children in one episode, versus three in the old+output. The bounded family model reports orders `[4,3,2,5,6,5]`, compatible with+an unobserved fundamental; no fundamental ridge is invented. Fourteen supported+pair comparisons agree with the joint scale model, worst residual 0.541 of its+limit, and minimum two resolved-motion witnesses. Observed support extends from+36.5 to 50.0 seconds. This is useful component consolidation, not proof of one+physical source. Missing/fragmented order-5 observations remain separate measured+children in that episode.++++The reference has three brief-path proposals: 900–909 s, 2149–2154.5 s and+2163–2169 s. The latter two lack ten total samples and are marked acoustic-review+only. Gaps are preserved. DEMAND car/bus contexts contain retained rising and+turning tonal trajectories; their engine/environment context illustrates why+motion acceptance cannot be called aircraft detection. Near-unison reference+trajectories remain separate when they do not satisfy the common-motion model.++++Regressions are material:+- - Default proposal-positive aircraft clips remain 2/6. The visibly rising++- At the experimental default settings, proposal-positive aircraft clips remain 2/6. The visibly rising+ case-0013 remains missed, including a separate 0.5-second-window / 0.125-second-hop,+ 20–6000 Hz replay. DLR's seven-second excerpt is also still missed. Supporting+ brief events does not guarantee recovery of fast, broadband or weak passages.+- In the reference, only 628/805 old measured points (78.0%) have a coincident+ new observation within `max(1 Hz, 0.006*f)`. This overlap measure uses actual+ timestamps and is **not recall**. Six old groups have no such retained points:+ 293.5–308.5, 314–333.5, 676–690, 1265.5–1282, 3101–3119 and 3454–3469.5 seconds.+ The 1265.5–1282-second ridge is the documented faint-passage regression.+- The old reference groups around 2100–2178.5 and 3060.5–3121 seconds each map+ onto two new groups. Thus partial-family reconciliation remains conservative,+ and the new representation does not solve all fragmentation. Unresolved+ associations and source multiplicity must not be counted as certified+ independent sources.+- The union of reference observed time across all accepted tracks grows from 353.0 to 599.5 seconds, but additional+ accepted tones are unverified. DEMAND gains nature, bus and car proposals and+ loses its old metro proposal. These are confusing-source positives and a lost+ baseline control, not aircraft successes. Wider coverage adds living-room and+ river-context proposals too.++No obviously incompatible trajectory was found within the reviewed case-0001+family, but the data provide no certified simultaneous-source truth. An accidental- physical-source merging rate cannot be estimated here. Mathematical controls- exercise different simultaneous evolution, near-unison retention, failed weak- bridges and later multi-witness reconciliation. They do not establish aircraft- identification or empirical merge accuracy.++physical-source merging rate cannot be estimated here. The historical branch used++generated coordinate-array checks for simultaneous evolution, near-unison retention,++weak bridges, and witness reconciliation. Those checks do not provide real-recording++evidence and are excluded from the integration and CI.++## Coverage, boundaries and operational cost++With identical 40–1600 Hz analysis, case-0001 decoded at 4 and 16 kHz retains one+episode and six children. Across 275 coincident measurements, the 90th-percentile+frequency difference is 4.42e-7 Hz (well below resolution). Its 40/20-second+chunk/overlap replay retains one episode but five children; changing the lower+limit to 20 Hz also retains one episode/five children. Chunk whitening and band+normalization can change marginal components. IDs are stable for fixed measured+content, not promised invariant across different configurations. The high-rate+path has no band seam; overlapping chunk observations have raw provenance and+one canonical catalog. Frequency requests above available decoding/source+coverage, too narrow to form a peak, or on an unsupported sample/hop grid fail+explicitly. Under-window real excerpts are valid zero-observation results;+corrupt media and execution/budget failures are separate failures.++| Replay | Sum wall time (s) | Peak RSS (MiB) | Total discovery output (KiB) |+| --- | ---: | ---: | ---: |+| 31 inputs, old 40–1600 Hz | 120.58 | 173.3 | 1400.0 |+| 31 inputs, new 40–1600 Hz | 247.29 | 146.2 | 1503.9 |+| 31 inputs, new 40–6000 Hz | 421.57 | 267.6 | 1618.1 |+| Hour, old 40–1600 Hz | 39.99 | 172.7 | 321.3 |+| Hour, new 40–1600 Hz | 54.11 | 163.1 | 527.3 |++Times include intake, hashing, discovery and one summary plot, in separate case+processes on a contended host. These are single-arm operational observations,- not causal speedups. The default living-room case is a notable runtime regression++not causal speedups. The experimental 40–1600 Hz living-room case is a notable runtime regression+because retained noise fragments require reconciliation. The reference retained+2,541 provisional paths / 22,966 observations and used about 14.5k association+work units, below configured budgets. Normal output has no file per rejected+fragment. The 6 kHz arm demonstrates the additional FFT/candidate cost; it is not+the default or a calibrated better detector.++## Reproduction and checks++Restore the real media to the manifest paths and verify the supplied hashes.+The original reference WAV can be restored from the repository's source-only+release asset as described in [artifacts](ARTIFACTS.md); no ADS-B archive is+needed. AeroSonicDB filenames, DEMAND archive names and the DLR transformation are- in the manifest. Then use a fresh directory for each actual run:++in the manifest. Use a fresh directory for each run.++++The following commands compare the historical baseline with the current experimental++implementation. They produce new results and leave the frozen comparison intact.++`--source-root` selects the detector checkout. The experimental arms require++`--experimental-episodes` and a checkout that contains `episode_discovery.py`.++```bash+git worktree add --detach /tmp/dg-old 451b67f01dcd1dfe44d47c42407f404706a5a9b7- git worktree add --detach /tmp/dg-new 05548ed1cb0954db8fac960523e39300dc97308d++.venv/bin/python scripts/validate_acoustic_episodes.py \+ --manifest benchmarks/acoustic-episodes-349/manifest.json \+ --source-root /tmp/dg-old --output results/episodes-old+.venv/bin/python scripts/validate_acoustic_episodes.py \+ --manifest benchmarks/acoustic-episodes-349/manifest.json \- --source-root /tmp/dg-new --output results/episodes-new++ --source-root . --output results/episodes-new --experimental-episodes++# Same 31 inputs for the wide arm; the full hour was predeclared outside this arm.+python - <<'PY'+import json+from pathlib import Path+m=json.loads(Path('benchmarks/acoustic-episodes-349/manifest.json').read_text())+m['cases']=[c for c in m['cases'] if c['id']!='whole-reference']+Path('/tmp/episodes-wide-inputs.json').write_text(json.dumps(m))+PY+.venv/bin/python scripts/validate_acoustic_episodes.py \+ --manifest /tmp/episodes-wide-inputs.json --max-frequency-hz 6000 \- --source-root /tmp/dg-new --output results/episodes-wide++ --source-root . --output results/episodes-wide --experimental-episodes+.venv/bin/python scripts/summarize_acoustic_episodes.py \+ --manifest benchmarks/acoustic-episodes-349/manifest.json \+ --baseline results/episodes-old --new results/episodes-new \+ --wide results/episodes-wide --output results/episodes-comparison+- PYTHONPATH=src .venv/bin/python -m pytest -q tests/test_episodes.py \- tests/test_real_discovery_normalization.py tests/test_real_upload_verification.py \- tests/test_contracts.py tests/test_job_resume.py tests/test_real_coherent_discovery.py \- tests/test_real_episode_artifact.py++PYTHONPATH=src .venv/bin/python -m pytest -q tests/test_real_episode_artifact.py \++ tests/test_real_episode_motion.py tests/test_real_episode_cli.py+```+++For the exact historical experiment, use the runner from its pinned checkout.++That runner predates the explicit switch and imports its experimental detector++from `dopplergeist.discovery`. The current runner's explicit switch cannot select++that historical module layout.++++```bash++git worktree add --detach /tmp/dg-frozen 05548ed1cb0954db8fac960523e39300dc97308d++.venv/bin/python /tmp/dg-frozen/scripts/validate_acoustic_episodes.py \++ --manifest benchmarks/acoustic-episodes-349/manifest.json \++ --source-root /tmp/dg-frozen --output results/episodes-frozen++```++++For the historical wide arm, use that same archived runner with the 31-input++manifest and `--max-frequency-hz 6000`. Use a separate output directory. Neither++historical replay supplies location truth or performs trajectory fitting.+++After the frozen comparison, a reporting-only patch replaced the combined+episode-rejection reason with explicit failed gates on both acceptance paths.+The final matching adapter consumes the joint scale model without reimposing a+single-base overlap requirement. All 63 new/default-wide observed outputs adapt+successfully (50 matchable canonical episodes), with no trajectory fitting.- A current-code real replay matched the frozen rich-family clip's complete++A pre-integration real replay matched the frozen rich-family clip's complete+`events` and `episodes` exactly and exposed the new rejection ranges.+- 69 focused checks passed after integrating current main. They cover grouping- order/determinism, witness reconciliation, unsupported bridges, gap accounting,- symmetric motion/turns, modulation/stationary/tone-switch rejection properties,- explicit budget/coverage/execution errors, real measured-child consumer- compatibility, legacy coherent-adapter compatibility, and checkpoint behavior.- No synthetic audio suite was run. Compilation, CLI help, benchmark-instrumentation- checks and an installed wheel's episode module, coherent adapter, high-rate- configuration and web assets passed. All signal-level runs used the genuine- recordings above; coordinate-array tests are mathematical software checks only.++The pre-integration report recorded 69 passing focused checks. That historical++count included generated coordinate-array tests for grouping, motion, and rejection++properties. Those tests are removed and do not support the integrated validation++claim. The count also included real measured-child compatibility, legacy coherent++compatibility, execution errors, and checkpoint checks. It is not the current CI++test total.++++The same historical report recorded successful compilation, CLI help,++benchmark-instrumentation checks, and installed-wheel checks. Its signal recordings++were the genuine inputs above. The current recorded-artifact test uses saved real++children and the eligibility-metadata regression. The motion regression checks++duration and support diagnostics against recorded child measurements. The CLI++check packages each of two recorded four-second PCM excerpts separately, without++changing samples. It checks default and experimental routing, default decode++bytes, and explicit rejection of unsupported source frequency coverage. These++checks do not establish aircraft identity, detection recall, or localization++accuracy.++The remaining limits are measured recall losses, ambiguous source multiplicity,+fragment splits, uncertain peak/contrast models, and uncalibrated confidence and+confusing-source rates. A future detector change needs separate real controls;+this evidence does not establish flight identity, localization accuracy or a+nationwide end-to-end result.diff --cc docs/AUDIO_DISCOVERY.mdindex 3b9c741,f13a2bf..7f7d70f--- a/docs/AUDIO_DISCOVERY.md+++ b/docs/AUDIO_DISCOVERY.md@@@ -1,176 -1,130 +1,193 @@@- # Automatic acoustic episode discovery-- Discovery scans the whole recording without event windows, aircraft IDs, flight- observations, coordinates or a flight-geometry template. Its unit is a **canonical- acoustic episode**, containing measured tonal child tracks. Common frequency- motion does not establish a single physical source, physical source motion, or- aircraft identity. Simultaneous trajectories can remain separate, and physical- source multiplicity is explicitly unresolved, including within an episode.-- The scanner summary is also schema 2: `events_found` and `canonical_proposals`- count episodes, while `measured_child_tracks` counts child records.-- The Python API still returns `list[DetectedEvent]`: one record per measured child- track, with the canonical episode ID in `harmonic_group_id`. Count distinct group- IDs to count proposals. `discovery.json` is now **schema_version 2** and is the- explicit episode catalog. The shared upload/result and DetectedEvent contracts- remain version 1. See [interfaces](INTERFACES.md#detected-events).-- ## Processing and acceptance-- 1. Decode to a mono, disk-backed f32 cache. The automatic adapter selects 4, 8,- 16 or 32 kHz according to requested global frequency coverage. FFmpeg applies- channel averaging and explicit swresample low-pass filtering (filter_size 64,- cutoff 0.95). Sample zero remains the first decoded sample after codec skips;- resampling can round the final length by a sample. UTC requires separate- recording-clock evidence.- 2. Scan overlapping chunks (120/60 seconds by default). The default spectrum is- a 2-second Hann window, 0.5-second hop, 40–1600 Hz. Temporal whitening and- frequency-wise robust contrast retain the existing measured-peak method.- Peaks carry frequency, contrast, and measured spectral amplitude in dB.- 3. Retain provisional paths of at least four observations **before** duration or- motion rejection. Reconcile duplicate measurements across chunks and then- reciprocal-unique continuations. Distinct peaks in the same chunk are not- deleted as near-unison duplicates. A continuation requires compatible endpoint- slopes in either direction, forward and backward prediction, uncertainty,- observed support and a gap penalty. A turn hidden in a gap is unresolved.- 4. Assess resolved excursion, distributed motion, local prediction residual,- sustained turns, and total variation. Differences and slopes use timestamps- in seconds; missing intervals do not count as observed motion. Rising,- falling and one sustained turning trajectory are eligible. Stationary tones,- isolated tone switches, repeated modulation and wandering fail explicit gates.- 5. Fit constant frequency scales between components with substantial shared- support, resolved motion, high curve correlation and uncertainty-aware- residuals. A bounded integer-family model (orders 1–12, smallest total order)- supplies secondary harmonic evidence, including missing fundamentals.- Noninteger relationships require correlated measured amplitude envelopes.- A ratio match or temporal overlap alone is insufficient.- 6. Reconsider groups jointly. For three or more components each needs two strong- motion witnesses; every supported pair must agree with one joint scale fit,- including short overlaps that cannot establish motion independently. A weak- bridge cannot transitively collect unrelated groups. Sorting observations and- associations makes grouping invariant to input order. Unresolved strong links- are counted and traced separately; separate proposals do not certify separate- physical sources. The model has one scale per child, at most 32 children per- episode, and no free time warps or high-order rational search.- 7. Apply episode acceptance using the union of **observed hop-sized cells**, not- interval span or spectrogram-window footprints. Sustained acceptance needs- at least 12 observed seconds and 65% support. Brief acceptance needs at least- 3 observed seconds, 85% support, and a child with median contrast >=4.5,- excursion >=6 frequency-uncertainty units, distributed motion >=60%, and- prediction-error q95 <=0.75. These are uncalibrated engineering criteria,- not a blanket reduction of the duration/contrast thresholds.-- Gaps are never filled with invented ridge observations. Stitch gaps are at most- 20 seconds and at most 35% of the pair's observed support; aggregate acceptance- also penalizes missing support. The output distinguishes the observed cells- from the wider spectral-window timing uncertainty. Very brief accepted episodes- with fewer than ten total samples are acoustic-review evidence only;- `quality.matching_eligible=0` prevents the matching adapter from failing on them.- The application returns `brief_acoustic_evidence_only` if none are matchable.- Other proposals need not match any flight.-- ## Coverage and resources-- The default coverage remains 40–1600 Hz for compatibility. Higher frequencies- require decoding the original source at a sufficient rate; changing a scanner- setting cannot restore frequencies discarded in an old cache. The automatic- adapter and scanner CLI choose the rate before intake. Direct Python callers- must use `required_sample_rate(settings)` when invoking `intake_recording`.- Requested upper coverage must be <=45% of both source and decoded rates. A- request outside this usable range fails with `unsupported_frequency_coverage`;- it is not reported as an exhaustive negative. The lower limit requires at least- two cycles per window. Longer windows improve low-frequency resolution; shorter- windows improve temporal resolution while increasing frequency uncertainty.-- The `coverage` object records requested and analyzed bin ranges, eligible peak- centers, source/decoded rates, resolution, hop, window, transition guard and edge- policy. Outermost bins support interpolation and cannot be peak centers. Inputs- shorter than a complete window have no spectral observations. The high-rate path- uses a single spectrum per chunk, so there are no overlapping frequency bands- that could duplicate proposals. Chunk grids must align to whole sample hops;- chunk provenance is retained through deduplication and stitching.-- Default explicit limits: 60 peaks/frame, 4,096 provisional paths, 500,000 retained- observations, 200,000 association work units, 8,000,000 full-spectrum cells per- chunk and 100 diagnostic trace entries. Association work includes repeated joint- fit checks, not only unique pairs. Joint fit matrices have at most 32 columns.- Exceeding a processing budget raises a typed failure and records the limit;- it does not silently drop candidates and claim a complete scan. There is no cap- of two, three or four canonical proposals per recording. Increasing a work limit- in the Python settings is an explicit resource choice.-- The decoded cache uses `4 * rate * seconds` bytes: about 55 MiB/hour at 4 kHz,- 220 MiB/hour at 16 kHz. Working spectra stay chunk-bounded; raising rate increases- FFT memory and CPU, and reducing the hop increases frame count. Spectrum cells- are checked before allocation. The [engineering report](ACOUSTIC_EPISODES_REPORT.md)- records measured RSS, time and output volume, including regressions.-- ## Outputs and compatibility-- `discovery.json` contains:-- | Field | Meaning |- | --- | --- |- | `status`, `failure` | `complete` with zero proposals is a valid in-band result; `failed` is an execution, coverage or budget failure |- | `source_sha256`, `code`, `settings`, `runtime_s`, `coverage` | Input identity, git/implementation identity, library versions, effective configuration and runtime |- | `events` | Compatible measured DetectedEvent children; ridge points are stored once here |- | `episodes` | Canonical IDs, child IDs, raw track/chunk membership, fitted frequency scales, joint-fit residual/witness diagnostics, integer orders, observed intervals/gaps, confidence category and limitations |- | `counts` | Separate raw per-chunk paths/observations, provisional/deduplicated/stitched candidates, accepted children and canonical proposals |- | `ridge_count` | Accepted measured child count, retained for older count consumers |- | `rejections` | Counts and measured/threshold ranges per rejection reason; optional bounded candidate traces |- | `reconciliation_counts`, `reconciliation_decisions` | Counted and bounded duplicate, stitch, joint-group and unresolved-relation decisions; truncation is explicit |-- IDs hash source identity and ordered measured content, and do not depend on input- ordering, proposal enumeration or unrelated accepted proposals. They are stable- for the same measurements and effective configuration, not guaranteed invariant- to codecs, alternate chunk whitening, or resampling that changes measurements.- Each child retains original raw-track identifiers and amplitude measurements;- observed frequency scales replace the old ratio dictionary in the matching- adapter. Legacy event groups without these scales still use their old adapter.- Equal aggregate weight per child preserves the existing consumer convention;- additional components do not become additional independent time constraints.-- Confidence is categorical and uncalibrated: `uncalibrated_supported` or- `uncalibrated_brief_limited`. Frequency uncertainty uses the spectral resolution- and robust deviation, not a calibrated interval. `frequency_sigma_hz` and- `frequency_uncertainty_hz` retain the same diagnostic; matching retains its- >=1 Hz loss-scale floor. Every episode says `physical_motion_confirmed=false`- and `physical_source_multiplicity=unresolved`.-- Schema 2 removes the duplicate `harmonic_ridges` array, legacy `fragment_links`- and automatic per-child CSV files. Read measurements from `events` and decisions- from the reconciliation fields. The plot benchmark reads both artifact versions.- Old evidence is preserved; [the starting-version documentation](https://github.com/1337isnot1337/DOPPLERGEIST/blob/451b67f01dcd1dfe44d47c42407f404706a5a9b7/docs/AUDIO_DISCOVERY.md)- contains historical counts and methodology, including cancelled synthetic work.-- ## Commands+ # Automatic audio-event discovery++ `discover_events(recording, output_dir=None, settings=None)` consumes the+ `IntakeRecording` from intake and returns shared-contract `DetectedEvent`+ dictionaries. The normal call supplies no time windows, frequency bands, aircraft+ IDs, search locations or truth. It scans all decoded samples with fixed 120 s+ chunks / 60 s overlap, a 2 s Hann spectrum at 0.5 s hops and 40–1600 Hz coverage+ (clamped below decoded Nyquist). Working memory is bounded by chunk size; a disk+ cache holds the complete recording. Inputs under one spectral window return [].++ Time-whitened spectral contrast suppresses persistent stationary tones. Local+ maxima are linked with bounded motion, short missing spans and local slope+ continuity. Minimum duration/support, resolved downward frequency change,+ distributed motion and jump checks reject noise paths and switching stationary+ tones. Duplicate overlapping chunk ridges merge before grouping harmonics. Both+ integer ratios and rational ratios (e.g. measured 2f and 3f with an absent+ fundamental) count as one independent event. The lowest measured harmonic is the+ representative ridge; no fundamental is invented. Harmonic count denotes distinct+ measured ratios, including fragmented traces of the same harmonic only once.+ Harmonic grouping is optional consolidation: a ridge without a compatible+ partner remains a single-ridge event candidate. The detector does not require a+ second harmonic.++ The output preserves recording-relative ridge samples and weights, measured+ window/band, harmonic-group identity, contrast/support, spectral resolution and+ uncertainty diagnostics. Resolution is not a calibrated error interval; no raw+ quality score is a probability. No compulsory straight-flight speed, slant or+ source-frequency estimate constrains downstream search. These are **acoustic+ moving-tone proposals**, with aircraft identity unconfirmed. Association must+ reject unsupported proposals and count harmonic groups once.++ In the current real one-hour upload, automatic discovery produced 15 independent+ groups: 14 have one observed ridge and one has three. This is a useful reminder+ that harmonic grouping can consolidate evidence when multiple bands are+ recorded, but a single-ridge candidate must remain eligible for downstream+ assessment. The audio-only discovery result does not confirm aircraft identity+ or recording location.++ With output_dir, discovery saves `discovery.json` (all events, settings, chunk+ counts, original harmonic ridges and input hash), `discovery.png` (overview), and+ per-event CSV plus spectrogram PNG. Each spectrogram image is limited to a chunk's+ span; the full measured ridge remains in JSON/CSV. Existing discovery outputs+ are refused. A reproducible whole-file entry point is:```bash- # Default acoustic-only scan. A fresh output directory is required.- PYTHONPATH=src .venv/bin/python scripts/discover_audio.py input.mp3 \- --output results/discovery --plot-summary-- # Global wider coverage; source must actually retain those frequencies.- PYTHONPATH=src .venv/bin/python scripts/discover_audio.py input.wav \- --min-frequency-hz 20 --max-frequency-hz 6000 \- --output results/discovery-wide --plot-summary-- # Optional higher temporal resolution and bounded rejected-candidate traces.- PYTHONPATH=src .venv/bin/python scripts/discover_audio.py input.wav \- --window-s .5 --hop-s .125 --max-frequency-hz 6000 \- --output results/discovery-fast --detailed-candidates --plot-event-details-- # Software properties and existing genuine recorded evidence; no audio synthesis.- PYTHONPATH=src .venv/bin/python -m pytest -q tests/test_episodes.py \- tests/test_real_discovery_normalization.py tests/test_real_upload_verification.py \- tests/test_contracts.py tests/test_job_resume.py+ dopplergeist discover input.mp3 --output results/new-audio-scan```- Summary plots use canonical episodes. Optional detail plots render one bounded- spectrogram per episode, with all its child tracks, once. They do not render the- same group repeatedly for each harmonic. A candidate may fail multiple checks, including both acceptance paths; failed-check- counts are not rejected-candidate counts. Normal operation records aggregated- noise rejection rather than writing a file per rejected fragment. Input/decoder- failures exit unsuccessfully; discovery failures additionally write a failed- artifact. No command above acquires flight data or estimates a location.+ The installed CLI records the source hash, settings, measured events and chunk+ counts in its output. It does not consume evaluation labels. Run post-hoc+ evaluation in a separate process. Use a new output directory for every run.+ Pass `--plot-summary` for the overview or `--plot-event-details` for individual+ spectrograms; plotting is off by default in the CLI.+ The checkout-only `scripts/discover_audio.py` additionally records its Git state,+ code hash, runtime and peak RSS for research comparisons.++ Development evidence before DG-02 controls: full synthetic WAV (1180 s), 2+ proposals spanning both planted passes, 7.24 s / 238044 KiB peak RSS; full public+ reference WAV (3600.1845 s after decode), 8 proposals, 31.05 s / 249528 KiB peak+ RSS. The two prominent known passes are covered, but are fragmented into multiple+ proposals; the documented faint pass is missed. Six proposals do not cover either documented pass center; some appear to be+ fragments of the same pass. Their identities remain unverified. They are not+ labelled aircraft or certified false alarms. No+ complete real event annotation exists to calculate reference precision/recall.+ Earlier v1/v2 diagnostics preserve a missed synthetic event and excess proposals.+ These are development checks, not independent location/nationwide validation.++ Known limits: fixed spectral scale and minimum duration can miss steep/short,+ faint, low-frequency or high-frequency events. A single wide ridge can fragment+ across missing spans, and acoustically similar harmonic sources can be grouped+ ambiguously. No algorithm can establish aircraft identity solely from an arbitrary+ matching synthetic chirp. The existing real recording has no independently+ verified UTC clock. This implementation does not establish 100 m localization.++ Focused tests: `PYTHONPATH=src .venv/bin/python -m pytest -q tests/test_discovery.py`.+ They cover complete-file seams, harmonic grouping including an absent fundamental,+ simultaneous unrelated events, noise/stationary/upward-sweep rejection, short+ unsupported clips, and crossfading stationary tones. Fixed-setting DG-02 corpus+ results are recorded separately in the audio evidence handoff.++ Fixed-code DG-02 control check at discovery commit `4a49646`: all 14 opaque-input+ cases processed, 8 planted events found, 0 misses and 0 false alarms at event+ IoU >= 0.3. Both the development and public deterministic held_out split find+ 4/4 events. Noise, stationary, upward electronic sweep and short clips produce+ no event; harmonic, overlapping and MP3 positives are retained. Detection ran+ through the label-free subprocess runner; a later process read truth for scoring.+ No detector/settings changes followed the control run. These controls have no+ eligible location cases and do not establish real-aircraft identity or accuracy.++ Additional unchanged-code public-audio check: all 40 complete passage WAVs process+ without errors; 28 have at least one proposal, 12 have none, 102 proposals total.+ The run never supplied their frequency annotations. These counts do not establish+ true aircraft-event recall/precision: fragments and incidental sources remain+ unverified. Every prediction is saved under evidence/audio/w1-20261102/public40-4a49646.++ Fragment follow-up: compatible disjoint ridge fragments can join across at most+ 20 s when the gap is at most 35% of the combined observed span, both endpoint+ slopes descend, the observed frequency drop/rate is compatible with those slopes,+ and each endpoint has only one compatible continuation. Competing continuations+ remain separate. No frequency samples are invented across missing intervals;+ harmonic comparison excludes unsupported spans. `fragment_count` and+ `max_observed_gap_s` retain missing-support evidence, and `fragment_links` records+ accepted/ambiguous continuations with reasons. This is a tonal continuity+ hypothesis; it does not prove a flight identity.++ `quality.frequency_sigma_hz` is the integration consumer's canonical robust-loss+ scale, with `frequency_uncertainty_hz` retained for compatibility. Both currently+ carry the same resolution/robust-deviation diagnostic, with no statistical or+ probability calibration implied by the field name. Matching applies its >=1 Hz+ loss-scale floor. Later tests against the already public DG-02 controls are+ regressions, not newly held-out accuracy evidence.++ Sensitivity follow-up lowers the global seed contrast threshold from3.0 to2.5.+ At this setting the full synthetic recording still yields2 groups, with first+ ridge support extended from143–180.5s to119–196s. The reference emits16 proposals,+ including a short1265.5–1282s ridge in the documented faint passage; post-run+ comparison with the archived manual ridge gives median absolute difference+ 0.692Hz over23 points (90th percentile2.139Hz). This is acoustic overlap with an+ existing development measurement, not independently known aircraft or location+ truth. Fourteen known synthetic controls retain8 hits/0 misses/0 false alarms.+ The extra unverified reference proposals remain a matching/search cost. Earlier+ 3.0-threshold evidence and the faint-pass miss stay preserved; no held-out or+ 100m localization claim follows from this development tuning.++ Discovery returns all accepted independent groups; it has no global two- or+ three-event maximum. Four- and six-episode generated audio regressions check that+ later events survive and harmonics count once. These audio-only controls test+ retention, not geographic accuracy. The per-frame peak budget remains an explicit+ bounded-analysis setting, and unsupported or missed tones are not a completeness+ guarantee. The contrast 2.5 settings are frozen for the new public-camera batch.++++## Experimental acoustic episodes++++The installed `discover` command and the checkout script support an explicit++`--experimental-episodes` switch. This switch selects++`dopplergeist.episode_discovery` for acoustic reports. Without the switch, both++commands retain the scanner described above. The automatic analysis and upload++workflow also retain that scanner.++++Run the experimental scanner on a real recording:++++```bash++dopplergeist discover input.mp3 --output results/new-episode-scan \++ --experimental-episodes --plot-summary++```++++Use a new output directory for each run. For a wider frequency range, run:++++```bash++dopplergeist discover input.mp3 --output results/new-wide-episode-scan \++ --experimental-episodes --max-frequency-hz 6000 --plot-summary++```++++The experimental settings default to 40–1600 Hz, a 2-second spectral window,++and a 0.5-second hop. The commands accept `--min-frequency-hz`,++`--max-frequency-hz`, `--window-s`, `--hop-s`, and `--detailed-candidates` only++with `--experimental-episodes`. The checkout script accepts the same switch:++++```bash++PYTHONPATH=src python scripts/discover_audio.py input.mp3 \++ --output results/new-research-episode-scan --experimental-episodes++```++++Experimental intake selects a decoding rate that supports the requested band.++It explicitly uses the FFmpeg resampler with a 64-tap filter and a 0.95 cutoff.++The default scanner retains its existing decoding command. Unsupported source++coverage and analysis limits produce explicit errors.++++### Outputs and compatibility++++Default discovery retains its existing artifact, which has no explicit++`schema_version` field. Experimental discovery writes++`discovery/discovery.json` with `schema_version: 2`, a canonical `episodes`++catalog, and measured `events` children. Episode records reference their measured++children. Gaps remain gaps, and an inferred fundamental does not create measured++ridge samples. Coverage, settings, counts, rejection diagnostics, and code identity++remain available in the artifact.++++The child events retain the shared `DetectedEvent` contract. Numeric quality++fields include `episode_model_version`, `episode_frequency_scale`, and++`matching_eligible`. The matching adapter supports these recorded children and++retains its legacy behavior for version-1 events. Brief episodes without enough++samples remain evidence for acoustic review. The experimental command does not++run a location search or enable these episodes in automatic upload jobs.++++The [frozen real-recording comparison](ACOUSTIC_EPISODES_REPORT.md) retains every++input, including zeros and regressions. Its labels `new` and `default` refer to++the experimental implementation with its original settings. They do not name++the current product default. Six baseline reference groups had no retained++measurement within the report's overlap tolerance, including the documented faint++passage. Runtime also increased on the measured++comparison. The evidence does not establish improved aircraft recall, source++identity, or location accuracy.diff --cc docs/INTERFACES.mdindex 2245316,17671d9..843ad92--- a/docs/INTERFACES.md+++ b/docs/INTERFACES.md@@@ -80,16 -78,6 +80,21 @@@ They are not guaranteed true geometry;(e.g. `ridge_rmse_hz`). A diagnostic score is not a calibrated probability.There is no blanket `confidence` float whose semantics different workers can guess.- Automatic discovery's separate artifact is now `schema_version: 2`; its `episodes`- catalog references compatible `events` children. See [the artifact contract and- migration](AUDIO_DISCOVERY.md#outputs-and-compatibility). Modern children carry- `quality.episode_model_version=2`, positive `episode_frequency_scale`, and numeric- `matching_eligible`. Matching normalizes these measured scales within each- canonical group, with legacy rational-ratio behavior for old records. Accepted- brief episodes with insufficient samples remain acoustic-review evidence. This- additive numeric quality metadata does not change DetectedEvent's strict keys or- the upload/result schema version.++Default discovery retains its existing artifact, which has no explicit++`schema_version` field. The shared event contract remains version 1. Only the explicit++`discover --experimental-episodes` path writes `schema_version: 2` with an++`episodes` catalog that references compatible `events` children. The checkout++scanner also requires this switch. See [outputs and++compatibility](AUDIO_DISCOVERY.md#outputs-and-compatibility).++++Experimental children carry `quality.episode_model_version=2`, positive++`quality.episode_frequency_scale`, and numeric `quality.matching_eligible`.++Matching normalizes these measured scales within each canonical group and retains++legacy rational-ratio behavior for version-1 events. Brief episodes with++insufficient samples remain evidence for acoustic review. These numeric quality++fields preserve DetectedEvent's strict keys and the upload/result schema version.++Automatic analysis and upload jobs do not select the experimental implementation.+## Location candidatesA `LocationCandidate` contains `lat`, `lon`, finite `score`, a descriptivediff --cc scripts/discover_audio.pyindex 1656648,e8e6d85..0ee1e4e--- a/scripts/discover_audio.py+++ b/scripts/discover_audio.py@@@ -11,7 -11,7 +11,6 @@@ from pathlib import Patimport subprocessimport time- from dopplergeist.discovery import DiscoverySettings, discover_events, required_sample_rate-from dopplergeist.discovery import DiscoverySettings, discover_eventsfrom dopplergeist.intake import intake_recordingfrom dopplergeist.resource_usage import process_peak_rss_kib@@@ -24,36 -24,28 +23,53 @@@ def main()help="render the recording-level ridge overview plot")parser.add_argument("--plot-event-details", action="store_true",help="render one spectrogram PNG per discovered event (slower)")- parser.add_argument("--min-frequency-hz", type=float, default=40.0)- parser.add_argument("--max-frequency-hz", type=float, default=1600.0)- parser.add_argument("--window-s", type=float, default=2.0)- parser.add_argument("--hop-s", type=float, default=.5)++ parser.add_argument("--experimental-episodes", action="store_true",++ help="use experimental episode reporting instead of the standard detector")++ parser.add_argument("--min-frequency-hz", type=float)++ parser.add_argument("--max-frequency-hz", type=float)++ parser.add_argument("--window-s", type=float)++ parser.add_argument("--hop-s", type=float)+ parser.add_argument("--detailed-candidates", action="store_true", help="bounded rejected-candidate measurements")args = parser.parse_args()- settings = DiscoverySettings(min_frequency_hz=args.min_frequency_hz, max_frequency_hz=args.max_frequency_hz,- window_s=args.window_s, hop_s=args.hop_s)++ overrides = {name: getattr(args, name) for name in++ ("min_frequency_hz", "max_frequency_hz", "window_s", "hop_s")++ if getattr(args, name) is not None}++ if not args.experimental_episodes and (overrides or args.detailed_candidates):++ parser.error("Frequency, window, hop and detailed-candidate options require --experimental-episodes")++ intake_options, discovery_options = {}, {}++ if args.experimental_episodes:++ from dopplergeist import episode_discovery as discovery++ settings = discovery.DiscoverySettings(**overrides)++ intake_options = dict(sample_rate_hz=discovery.required_sample_rate(settings), resample_filter_size=64)++ discovery_options = dict(settings=settings, detailed_candidates=args.detailed_candidates)++ else:++ from dopplergeist import discovery++ settings = discovery.DiscoverySettings()output = Path(args.output)output.mkdir(parents=True, exist_ok=False)began = time.monotonic()- recording = intake_recording(args.audio, output / "intake", sample_rate_hz=required_sample_rate(settings))- recording = intake_recording(args.audio, output / "intake")-- events = discover_events(recording, output_dir=output / "discovery",++ recording = intake_recording(args.audio, output / "intake", **intake_options)++ events = discovery.discover_events(recording, output_dir=output / "discovery",plot_summary=args.plot_summary,- plot_event_details=args.plot_event_details, settings=settings, detailed_candidates=args.detailed_candidates)- plot_event_details=args.plot_event_details)++ plot_event_details=args.plot_event_details, **discovery_options)root = Path(__file__).resolve().parents[1]sources = sorted((root / "src" / "dopplergeist").glob("*.py"))code_hash = hashlib.sha256()for path in sources:code_hash.update(path.name.encode())code_hash.update(path.read_bytes())- result = {"schema_version": 2, "recording": recording.metadata, "time_status": recording.time_status,- "settings": asdict(settings), "events_found": len({e["harmonic_group_id"] for e in events}),- "canonical_proposals": len({e["harmonic_group_id"] for e in events}), "measured_child_tracks": len(events),+ result = {"recording": recording.metadata, "time_status": recording.time_status,- "settings": asdict(DiscoverySettings()), "events_found": len(events),++ "settings": asdict(settings), "events_found": len(events),"events": [{k: event[k] for k in ("event_id", "start_s", "end_s", "band_hz", "quality")} for event in events],"runtime_s": time.monotonic() - began, "peak_rss_kib": process_peak_rss_kib(),"code_sha256": code_hash.hexdigest(),"git_commit": subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=root, text=True).strip(),"working_tree": subprocess.check_output(["git", "status", "--short"], cwd=root, text=True).strip(),"scope": "Blind acoustic discovery only; no aircraft association or location estimate"}++ if args.experimental_episodes:++ result.update(experimental_episodes=True, discovery_schema_version=2,++ canonical_proposals=len({e["harmonic_group_id"] for e in events}),++ measured_child_tracks=len(events))(output / "summary.json").write_text(json.dumps(result, indent=2, allow_nan=False) + "\n")print(json.dumps(result, indent=2))diff --cc scripts/validate_acoustic_episodes.pyindex ecd0189,0000000..c6e8574mode 100644,000000..100644--- a/scripts/validate_acoustic_episodes.py+++ b/scripts/validate_acoustic_episodes.py@@@ -1,77 -1,0 +1,86 @@@+"""Paired acoustic-only replay of a predeclared real-media manifest.++No downloads, fabricated signals, source identity labels or localization inputs+enter discovery. Each case runs in a fresh process for comparable peak RSS.++Episode discovery requires --experimental-episodes; the default replays the++standard detector, including when --source-root points to a historical checkout.+"""+import argparse+import hashlib+import json+import os+from pathlib import Path+import subprocess+import sys+import time++- def run_case(case, output, upper):- from dopplergeist.discovery import DiscoverySettings, discover_events++def run_case(case, output, upper, experimental=False):++ if experimental:++ from dopplergeist.episode_discovery import DiscoverySettings, discover_events++ else:++ from dopplergeist.discovery import DiscoverySettings, discover_events+ from dopplergeist.intake import intake_recording+ from dopplergeist.resource_usage import process_peak_rss_kib+ began = time.monotonic()+ settings = DiscoverySettings(max_frequency_hz=upper)+ rate = next(rate for rate in (4000, 8000, 16000, 32000) if upper <= rate * .45)- result = dict(case_id=case['id'], source_sha256=case['sha256'])++ result = dict(case_id=case['id'], source_sha256=case['sha256'], experimental_episodes=experimental)+ try:+ with Path(case['path']).open('rb') as stream:+ if hashlib.file_digest(stream, 'sha256').hexdigest() != case['sha256']:+ raise ValueError('Real input checksum differs from frozen manifest')- recording = intake_recording(case['path'], output / 'intake', sample_rate_hz=rate)++ intake_options = dict(resample_filter_size=64) if experimental else {}++ recording = intake_recording(case['path'], output / 'intake', sample_rate_hz=rate, **intake_options)+ events = discover_events(recording, output_dir=output / 'discovery', settings=settings, plot_summary=True)+ groups = sorted({e.get('harmonic_group_id', e['event_id']) for e in events})+ result.update(status='complete', duration_s=recording.metadata['duration_s'],+ proposals=len(groups), child_tracks=len(events),+ intervals=[dict(group=g, intervals_s=[[e['start_s'],e['end_s']] for e in events if e.get('harmonic_group_id',e['event_id'])==g]) for g in groups])+ data = json.loads((output / 'discovery/discovery.json').read_text())+ result['counts'] = data.get('counts', {})+ result['rejections'] = data.get('rejections', {})+ except Exception as exc:+ result.update(status='failed', error_type=type(exc).__name__, error=str(exc))+ result.update(runtime_s=time.monotonic()-began, peak_rss_kib=process_peak_rss_kib(),+ output_bytes=sum(p.stat().st_size for p in (output / 'discovery').glob('*') if p.is_file()))+ return result+++def main():+ parser=argparse.ArgumentParser(description=__doc__)+ parser.add_argument('--manifest',type=Path,required=True)+ parser.add_argument('--source-root',type=Path,required=True)+ parser.add_argument('--output',type=Path,required=True)+ parser.add_argument('--max-frequency-hz',type=float,default=1600)++ parser.add_argument('--experimental-episodes',action='store_true',help='replay the experimental episode detector')+ parser.add_argument('--case',help=argparse.SUPPRESS)+ args=parser.parse_args()+ cases=json.loads(args.manifest.read_text())['cases']+ if args.case:+ case=next(c for c in cases if c['id']==args.case)- print(json.dumps(run_case(case,args.output,args.max_frequency_hz),allow_nan=False))++ print(json.dumps(run_case(case,args.output,args.max_frequency_hz,args.experimental_episodes),allow_nan=False))+ return+ args.output.mkdir(parents=True,exist_ok=False)+ env=dict(os.environ,PYTHONPATH=str(args.source_root.resolve()/'src'),OPENBLAS_NUM_THREADS='1',OMP_NUM_THREADS='1',MPLBACKEND='Agg')+ results=[]+ for case in cases:+ command=[sys.executable,str(Path(__file__).resolve()),'--manifest',str(args.manifest.resolve()),+ '--source-root',str(args.source_root.resolve()),'--output',str(args.output.resolve()/case['id']),+ '--max-frequency-hz',str(args.max_frequency_hz),'--case',case['id']]++ if args.experimental_episodes:++ command.append('--experimental-episodes')+ process=subprocess.run(command,capture_output=True,text=True,env=env,timeout=600)+ if process.returncode:+ result=dict(case_id=case['id'],status='failed',error=process.stderr[-2000:])+ else:+ result=json.loads(process.stdout)+ results.append(result)+ with (args.output/'results.jsonl').open('a') as stream:+ stream.write(json.dumps(result,allow_nan=False)+'\n')+ print(case['id'],result['status'],result.get('proposals'),round(result.get('runtime_s',0),2),flush=True)+ (args.output/'summary.json').write_text(json.dumps(results,indent=2,allow_nan=False)+'\n')+++if __name__=='__main__':+ main()diff --cc src/dopplergeist/cli.pyindex b458b0b,125a4d6..4cb973b--- a/src/dopplergeist/cli.py+++ b/src/dopplergeist/cli.py@@@ -94,6 -102,11 +102,19 @@@ def main()measure.add_argument("--end",type=float,required=True)measure.add_argument("--band",type=float,nargs=2,required=True)measure.add_argument("--output",required=True)+ discover=sub.add_parser("discover",help="Scan a complete recording for acoustic event proposals")+ discover.add_argument("audio")+ discover.add_argument("--output",required=True,help="New directory for the scan and diagnostics")+ discover.add_argument("--plot-summary",action="store_true",help="Render a recording-level ridge overview")+ discover.add_argument("--plot-event-details",action="store_true",help="Render a spectrogram for each proposal")++ discover.add_argument("--experimental-episodes",action="store_true",++ help="Use experimental acoustic episode reporting; not used by automatic location jobs")++ discover.add_argument("--min-frequency-hz",type=float,help="Experimental lower frequency bound (default: 40)")++ discover.add_argument("--max-frequency-hz",type=float,help="Experimental upper frequency bound (default: 1600)")++ discover.add_argument("--window-s",type=float,help="Experimental spectral window in seconds (default: 2)")++ discover.add_argument("--hop-s",type=float,help="Experimental spectral hop in seconds (default: 0.5)")++ discover.add_argument("--detailed-candidates",action="store_true",++ help="Save bounded rejected-candidate measurements; requires --experimental-episodes")analyze=sub.add_parser("analyze",help="Automatically locate aircraft audio, or explain insufficient evidence")analyze.add_argument("audio")analyze.add_argument("--start-utc",help="Earliest UTC recording start, including explicit timezone")@@@ -146,6 -159,23 +167,40 @@@from .audio import measureresult=measure(args.audio,{"start_s":args.start,"end_s":args.end,"band_hz":args.band},args.output)print(json.dumps(result[-1],indent=2))+ elif args.command=="discover":- from .discovery import discover_events+ from .intake import intake_recording++ overrides={name:getattr(args,name) for name in++ ("min_frequency_hz","max_frequency_hz","window_s","hop_s")++ if getattr(args,name) is not None}++ if not args.experimental_episodes and (overrides or args.detailed_candidates):++ parser.error("Frequency, window, hop and detailed-candidate options require --experimental-episodes")+ output=Path(args.output)+ try:++ intake_options={}++ discovery_options={}++ if args.experimental_episodes:++ from .episode_discovery import DiscoverySettings, discover_events, required_sample_rate++ settings=DiscoverySettings(**overrides)++ intake_options={"sample_rate_hz":required_sample_rate(settings),"resample_filter_size":64}++ discovery_options={"settings":settings,"detailed_candidates":args.detailed_candidates}++ else:++ from .discovery import discover_events+ output.mkdir(parents=True,exist_ok=False)- recording=intake_recording(args.audio,output/"intake")++ recording=intake_recording(args.audio,output/"intake",**intake_options)+ events=discover_events(recording,output_dir=output/"discovery",- plot_summary=args.plot_summary,plot_event_details=args.plot_event_details)++ plot_summary=args.plot_summary,plot_event_details=args.plot_event_details,++ **discovery_options)+ summary={"recording":recording.metadata,"time_status":recording.time_status,+ "events_found":len(events),+ "groups_found":len({event.get("harmonic_group_id") or event["event_id"] for event in events}),+ "scope":"Acoustic proposals only; aircraft identity and location are not established"}++ if args.experimental_episodes:++ summary.update(experimental_episodes=True,discovery_schema_version=2,++ canonical_proposals=summary["groups_found"],measured_child_tracks=len(events))+ (output/"summary.json").write_text(json.dumps(summary,indent=2,allow_nan=False)+"\n")+ except (OSError, ValueError) as exc:+ parser.error(f"Could not complete discovery: {exc}")+ print(json.dumps(summary,indent=2))elif args.command=="serve":from .service import servetry:diff --cc src/dopplergeist/episode_discovery.pyindex 0000000,0000000..b4dd3cfnew file mode 100644--- /dev/null+++ b/src/dopplergeist/episode_discovery.py@@@ -1,0 -1,0 +1,497 @@@++"""Experimental whole-recording acoustic episodes, enabled explicitly by callers.++++Only decoded audio is read. Proposals are acoustic evidence, not proof of an++aircraft identity. No straight-pass speed/slant fit is required for acceptance.++The standard detector remains in discovery.py and is used by automatic jobs.++"""++from dataclasses import asdict, dataclass++import json++from pathlib import Path++from statistics import median++import hashlib++from importlib.metadata import version++import subprocess++import time++from collections import Counter++++import numpy as np++from scipy import optimize, signal++++from .audio import Spectrum++from .contracts import validate_event++from .episodes import (Associations, DiscoveryError, Ridge, deduplicate,++ identifier, intervals, motion, reconcile, stitch)++++_HARMONIC_RATIOS = sorted({a / b for a in range(2, 9) for b in range(1, a) if a / b >= 1.2})++_NORMALIZATION_FUNCTIONS = (np.median, np.abs, np.maximum, np.clip, np.isfinite)++++++@dataclass(frozen=True)++class DiscoverySettings:++ chunk_s: float = 120.0++ overlap_s: float = 60.0++ min_frequency_hz: float = 40.0++ max_frequency_hz: float = 1600.0++ window_s: float = 2.0++ hop_s: float = 0.5++ min_contrast: float = 2.5++ min_duration_s: float = 12.0++ min_support: float = 0.65++ min_drop_hz: float = 4.0++ min_fractional_drop: float = 0.03++ max_gap_s: float = 2.0++ max_fragment_gap_s: float = 20.0++ max_peaks_per_frame: int = 60++ provisional_min_points: int = 4++ brief_min_observed_s: float = 3.0++ brief_min_contrast: float = 4.5++ max_candidates: int = 4096++ max_measurements: int = 500000++ max_associations: int = 200000++ max_diagnostic_traces: int = 100++ max_spectral_cells: int = 8000000++ max_episode_components: int = 32++++ def __post_init__(self):++ values = asdict(self)++ if any(not np.isfinite(value) or value <= 0 for value in values.values()):++ raise ValueError("Discovery settings must be finite and positive")++ for name in ("max_peaks_per_frame", "provisional_min_points", "max_candidates", "max_measurements",++ "max_associations", "max_diagnostic_traces", "max_spectral_cells", "max_episode_components"):++ if type(values[name]) is not int:++ raise ValueError(f"{name} must be an integer")++ if self.provisional_min_points < 4 or self.chunk_s > 180 or self.window_s > 8 or self.max_frequency_hz > 14400:++ raise ValueError("Require >=4 provisional points, chunk <=180 s, window <=8 s and upper frequency <=14400 Hz")++ if self.min_frequency_hz < 2 / self.window_s:++ raise ValueError("Lower frequency needs at least two cycles per spectral window")++ if self.overlap_s >= self.chunk_s or self.overlap_s < self.min_duration_s + self.window_s:++ raise ValueError("Overlap must cover an event acceptance window and be shorter than a chunk")++ if not self.hop_s <= self.window_s < self.chunk_s or self.min_support > 1:++ raise ValueError("Invalid spectral window/hop/support")++ if self.min_frequency_hz >= self.max_frequency_hz or type(self.max_peaks_per_frame) is not int:++ raise ValueError("Invalid frequency range or peak limit")++++++def _spectrum(data, sr, start, settings):++ n, hop = round(sr * settings.window_s), round(sr * settings.hop_s)++ if len(data) < n:++ return None++ cells = (n // 2 + 1) * (1 + (len(data) - n) // hop)++ if cells > settings.max_spectral_cells:++ raise DiscoveryError("spectral_budget_exceeded", f"Spectrum needs {cells} cells; limit {settings.max_spectral_cells}")++ f, t, power = signal.spectrogram(data, fs=sr, window="hann", nperseg=n,++ noverlap=n - hop, nfft=n, scaling="density")++ keep = (f >= settings.min_frequency_hz) & (f <= min(settings.max_frequency_hz, sr * 0.48))++ f, power = f[keep], power[keep]++ db = 10 * np.log10(power + np.finfo(np.float32).tiny)++ whitened = db - np.median(db, axis=1, keepdims=True)++ contiguous_columns = (++ type(whitened) is np.ndarray and whitened.dtype == np.float32++ and whitened.ndim == 2 and whitened.size > 0 and whitened.flags.c_contiguous++ and all(current is original for current, original in zip(++ (np.median, np.abs, np.maximum, np.clip, np.isfinite), _NORMALIZATION_FUNCTIONS))++ and np.isfinite(whitened).all()++ )++ axis = 0++ if contiguous_columns:++ # Keep each frequency column contiguous for both partition reductions.++ whitened = whitened.T.copy(order="C")++ axis = 1++ center = np.median(whitened, axis=axis, keepdims=True)++ scale = 1.4826 * np.median(np.abs(whitened - center), axis=axis, keepdims=True)++ contrast = np.clip((whitened - center) / np.maximum(scale, 1.0), -4, 12)++ if contiguous_columns:++ contrast = contrast.T.copy(order="C")++ return Spectrum(t + start, f, db, contrast)++++++def _paths(spec, settings):++ """Link local spectral maxima with bounded motion and short missing spans."""++ active, completed = [], []++ for column, time in enumerate(spec.time):++ peaks, info = signal.find_peaks(spec.contrast[:, column], height=settings.min_contrast,++ prominence=1.5, distance=2)++ order = np.argsort(info["peak_heights"])[-settings.max_peaks_per_frame:]++ peaks = peaks[order]++ frequencies = spec.frequency[peaks]++ weights = spec.contrast[peaks, column]++ # Sub-bin interpolation measures a local maximum without zero-padding.++ if len(peaks):++ a, b, c = (spec.db[peaks + offset, column] for offset in (-1, 0, 1))++ denominator = a - 2 * b + c++ offset = np.divide(0.5 * (a - c), denominator, out=np.zeros_like(a), where=np.abs(denominator) > 1e-9)++ frequencies = frequencies + np.clip(offset, -0.5, 0.5) * np.diff(spec.frequency[:2])[0]++ live = []++ for path in active:++ if time - path[-1][0] <= settings.max_gap_s:++ live.append(path)++ else:++ completed.append(path)++ active = live++ used = set()++ if active and len(peaks):++ last = np.array([path[-1] for path in active])++ dt = time - last[:, 0]++ delta = frequencies[None, :] - last[:, 1, None]++ speed = delta / dt[:, None]++ slopes = []++ for path in active:++ tail = path[-8:]++ if len(tail) >= 2:++ slopes.append(float(median(++ (right[1] - left[1]) / (right[0] - left[0])++ for left, right in zip(tail, tail[1:])++ )))++ else:++ slopes.append(0.0)++ allowed = np.abs(speed) <= np.maximum(8, last[:, 1, None] * 0.08)++ predicted_delta = np.asarray(slopes)[:, None] * dt[:, None]++ tolerance = 3 / settings.window_s + np.maximum(.5, np.abs(slopes)[:, None] * .5) * dt[:, None]++ newborn = np.array([len(path) == 1 for path in active])++ tolerance[newborn] = np.maximum(8, last[newborn, 1, None] * .08) * dt[newborn, None]++ costs = np.abs(delta - predicted_delta) / tolerance++ allowed &= costs <= 1++ costs = np.where(allowed, costs, 1e6)++ rows, cols = optimize.linear_sum_assignment(costs)++ for row, col in zip(rows, cols):++ if costs[row, col] < 1e6:++ active[row].append((float(time), float(frequencies[col]), float(weights[col]), float(spec.db[peaks[col], column])))++ used.add(col)++ active.extend([(float(time), float(frequency), float(weight), float(spec.db[peaks[j], column]))]++ for j, (frequency, weight) in enumerate(zip(frequencies, weights)) if j not in used)++ return completed + active++++++def _usable(path, settings):++ metrics, rejected = motion(np.asarray(path), settings)++ return not rejected and metrics["observed_duration_s"] >= settings.min_duration_s and metrics["support_fraction"] >= settings.min_support++++++def _overlap(a, b):++ """Legacy fixed-grid alignment, retained for existing optional adapters."""++ first, last = max(a[0, 0], b[0, 0]), min(a[-1, 0], b[-1, 0])++ if last <= first:++ return None++ t = np.arange(first, last + 0.001, 0.5)++ supported = np.ones(len(t), dtype=bool)++ for path in (a, b):++ following = np.clip(np.searchsorted(path[:, 0], t), 0, len(path) - 1)++ previous = np.maximum(0, following - 1)++ supported &= np.minimum(np.abs(t - path[following, 0]), np.abs(t - path[previous, 0])) <= 1.0++ t = t[supported]++ if len(t) < 3:++ return None++ return t, np.interp(t, a[:, 0], a[:, 1]), np.interp(t, b[:, 0], b[:, 1])++++++def _merge_duplicates(paths):++ """Legacy adapter compatibility; canonical discovery uses deduplicate()."""++ merged = []++ for path in sorted(paths, key=lambda p: p[0][0]):++ current = np.asarray(path)++ for i, previous in enumerate(merged):++ shared = _overlap(current, previous)++ if shared is None:++ continue++ t, f, g = shared++ if len(t) >= 8 and np.mean(np.abs(f - g) <= max(1.0, np.median(f) * 0.006)) >= 0.85:++ points = np.concatenate((current, previous))++ # A time bin observed in both chunks retains its strongest peak.++ points = points[np.lexsort((-points[:, 2], points[:, 0]))]++ _, unique = np.unique(points[:, 0], return_index=True)++ merged[i] = points[np.sort(unique)]++ break++ else:++ merged.append(current)++ return merged++++++++def _stitch_fragments(paths, settings, diagnostics=None):++ work = Associations(settings)++ ridges = [Ridge(np.asarray(p), (identifier("raw:", np.asarray(p)),)) for p in paths]++ result = stitch(ridges, settings, work)++ if diagnostics is not None:++ diagnostics.extend(work.decisions)++ return [r.points for r in result]++++++def required_sample_rate(settings):++ """Bound decode cost while keeping a 10% Nyquist transition guard."""++ for rate in (4000, 8000, 16000, 32000):++ if settings.max_frequency_hz <= .45 * rate:++ return rate++ raise DiscoveryError("unsupported_frequency_coverage", "Requested upper frequency exceeds bounded decoder coverage")++++++def _coverage(recording, settings):++ sr = recording.metadata["sample_rate_hz"]++ decode = recording.diagnostics.get("decode", {})++ source_sr = decode.get("source_sample_rate_hz", sr)++ upper = .45 * min(sr, source_sr)++ if settings.max_frequency_hz > upper:++ raise DiscoveryError("unsupported_frequency_coverage",++ f"Requested {settings.max_frequency_hz:g} Hz exceeds usable decoded/source coverage {upper:g} Hz; decode at >= {required_sample_rate(settings)} Hz and check source rate")++ if np.floor(settings.max_frequency_hz * settings.window_s) - np.ceil(settings.min_frequency_hz * settings.window_s) < 2:++ raise DiscoveryError("unsupported_frequency_coverage", "Frequency range requires at least three spectral bins for a measured peak")++ # Align frames and chunk boundaries to exactly representable sample hops.++ if any(abs(value * sr - round(value * sr)) > 1e-7 for value in (settings.window_s, settings.hop_s)):++ raise DiscoveryError("unsupported_time_grid", "Window and hop must be integer sample counts")++ step = settings.chunk_s - settings.overlap_s++ if abs(step / settings.hop_s - round(step / settings.hop_s)) > 1e-7:++ raise DiscoveryError("unsupported_time_grid", "Chunk step must be an integer number of spectral hops")++ if round(settings.hop_s * sr) < 1:++ raise DiscoveryError("unsupported_time_grid", "Hop must span at least one sample")++ return dict(requested_hz=[settings.min_frequency_hz, settings.max_frequency_hz],++ analyzed_hz=[float(np.ceil(settings.min_frequency_hz * settings.window_s) / settings.window_s),++ float(np.floor(settings.max_frequency_hz * settings.window_s) / settings.window_s)],++ decoded_sample_rate_hz=sr, source_sample_rate_hz=source_sr, usable_upper_hz=upper,++ frequency_resolution_hz=1 / settings.window_s, time_hop_s=settings.hop_s,++ window_s=settings.window_s, exhaustive_outside_analyzed_range=False,++ ridge_peak_centers_hz=[float((np.ceil(settings.min_frequency_hz * settings.window_s)+1) / settings.window_s),++ float((np.floor(settings.max_frequency_hz * settings.window_s)-1) / settings.window_s)],++ edge_policy="outermost retained bins support interpolation but cannot be peak centers",++ minimum_complete_window_s=settings.window_s,++ method="single higher-rate chunked spectrum; no band boundary", nyquist_guard_fraction=.45)++++++def _code_identity():++ root = Path(__file__).resolve().parents[2]++ try:++ commit = subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=root, text=True, stderr=subprocess.DEVNULL).strip()++ except (OSError, subprocess.CalledProcessError):++ commit = None++ digest = hashlib.sha256()++ for name in ("episode_discovery.py", "episodes.py", "intake.py"):++ digest.update((Path(__file__).parent / name).read_bytes())++ return dict(git_commit=commit, implementation_sha256=digest.hexdigest(),++ numpy=version("numpy"), scipy=version("scipy"))++++++def discover_events(recording, *, output_dir=None, settings=None, plot_summary=True, plot_event_details=False,++ detailed_candidates=False):++ """Return compatible measured child events; discovery.json v2 owns episodes.++++ Grouping is an acoustic hypothesis with unresolved physical multiplicity.++ Budgets/coverage failures raise DiscoveryError and write status=failed;++ status=complete with zero episodes is a valid in-band negative result.++ """++ settings = settings or DiscoverySettings()++ began = time.monotonic()++ output = Path(output_dir) if output_dir is not None else None++ if output:++ output.mkdir(parents=True, exist_ok=True)++ if (output / "discovery.json").exists():++ raise FileExistsError("Discovery output exists; use a new output directory")++ report = dict(schema_version=2, status="running", source_sha256=recording.metadata["source_sha256"],++ settings=asdict(settings), code=_code_identity(), events=[], episodes=[], chunks=[],++ scope="acoustic episodes; physical motion, aircraft identity and single-source interpretation unconfirmed")++ try:++ events, groups = _discover(recording, settings, report, detailed_candidates)++ report["status"] = "complete"++ except DiscoveryError as exc:++ report.update(status="failed", failure=dict(code=exc.code, message=str(exc)))++ raise++ except Exception as exc:++ report.update(status="failed", failure=dict(code="discovery_execution_error", exception_type=type(exc).__name__, message=str(exc)))++ raise++ finally:++ report["runtime_s"] = time.monotonic() - began++ if output:++ (output / "discovery.json").write_text(json.dumps(report, indent=2, allow_nan=False) + "\n")++ if output:++ if plot_summary:++ _plot_groups(groups, output / "discovery.png", recording.metadata["duration_s"], settings.max_gap_s)++ for episode, group in zip(report["episodes"], groups):++ if plot_event_details:++ _plot_event(recording, group, episode, settings, output / f"{episode['proposal_id']}.png")++ return events++++++def _discover(recording, settings, report, detailed):++ report["coverage"] = _coverage(recording, settings)++ sr = recording.metadata["sample_rate_hz"]++ ridges, traces, counts = [], [], Counter()++ report["counts"] = counts++ points_retained = 0++ rejection_ranges = {}++ def reject(reasons, metrics=None, origins=()):++ for reason in reasons:++ counts[reason["reason"]] += 1++ name, value = reason["reason"], float(reason["measured"])++ entry = rejection_ranges.setdefault(name, dict(count=0, measured_min=value, measured_max=value,++ threshold_min=float(reason["threshold"]), threshold_max=float(reason["threshold"]), comparison=reason["comparison"]))++ entry["count"] += 1++ entry["measured_min"] = min(entry["measured_min"], value)++ entry["measured_max"] = max(entry["measured_max"], value)++ entry["threshold_min"] = min(entry["threshold_min"], float(reason["threshold"]))++ entry["threshold_max"] = max(entry["threshold_max"], float(reason["threshold"]))++ if detailed and len(traces) < settings.max_diagnostic_traces:++ traces.append(dict(origins=list(origins), measurements=metrics, rejections=reasons))++ for chunk_index, (start, data) in enumerate(recording.iter_chunks(settings.chunk_s, settings.overlap_s)):++ spec = _spectrum(data, sr, start, settings)++ raw = _paths(spec, settings) if spec is not None else []++ found = 0++ for path in raw:++ counts["raw_paths"] += 1++ counts["raw_observations"] += len(path)++ if len(path) < settings.provisional_min_points:++ reject([dict(reason="provisional_points", measured=len(path), threshold=settings.provisional_min_points, comparison=">=")])++ continue++ points = np.asarray(path)++ origin = f"chunk-{chunk_index:06d}:" + identifier("ridge-", points, recording.metadata["source_sha256"])++ ridges.append(Ridge(points, (origin,)))++ found += 1++ points_retained += len(points)++ if len(ridges) > settings.max_candidates or points_retained > settings.max_measurements:++ raise DiscoveryError("candidate_budget_exceeded", f"Retained {len(ridges)} candidates/{points_retained} observations; limits {settings.max_candidates}/{settings.max_measurements}")++ report["chunks"].append(dict(start_s=start, duration_s=len(data) / sr, raw_paths=len(raw), provisional_paths=found))++ counts["provisional_paths"] = len(ridges)++ counts["provisional_observations"] = points_retained++ work = Associations(settings)++ ridges = deduplicate(ridges, settings, work)++ counts["deduplicated_tracks"] = len(ridges)++ ridges = stitch(ridges, settings, work)++ counts["stitched_tracks"] = len(ridges)++ # Motion before grouping prevents stationary/noisy tracks from licensing++ # group acceptance, but duration rejection only occurs after reconciliation.++ moving = []++ metrics_by_id = {}++ for ridge in ridges:++ metrics, reasons = motion(ridge.points, settings)++ metrics_by_id[identifier("", ridge.points)] = metrics++ if reasons:++ reject(reasons, metrics, ridge.origins)++ else:++ moving.append(ridge)++ reconciled = reconcile(moving, settings, work)++ events, accepted_groups, episodes = [], [], []++ for members, scales, orders, group_model in reconciled:++ metrics = [metrics_by_id[identifier("", r.points)] for r in members]++ cells = intervals(np.concatenate([r.points[:, 0] for r in members]), settings.hop_s)++ observed = sum(b - a for a, b in cells)++ span = cells[-1][1] - cells[0][0]++ support = observed / span++ long = observed >= settings.min_duration_s and support >= settings.min_support++ # Brief observations need stronger contrast, resolution and continuity;++ # harmonic richness alone cannot manufacture a moving event.++ brief = (observed >= settings.brief_min_observed_s and support >= .85 and++ any(m["median_contrast"] >= settings.brief_min_contrast and++ m["frequency_excursion_hz"] >= 6 * m["frequency_uncertainty_hz"] and++ m["moving_fraction"] >= .6 and m["prediction_error_q95"] <= .75 for m in metrics))++ if not long and not brief:++ # Report each failed gate on both alternative paths. A single++ # duration number would obscure support/contrast failures.++ best = max(metrics, key=lambda m: min(m["median_contrast"] / settings.brief_min_contrast,++ m["frequency_excursion_hz"] / (6 * m["frequency_uncertainty_hz"]),++ m["moving_fraction"] / .6, .75 / max(m["prediction_error_q95"], 1e-9)))++ gates = [("sustained_observed_duration_s", observed, settings.min_duration_s, ">="),++ ("sustained_support_fraction", support, settings.min_support, ">="),++ ("brief_observed_duration_s", observed, settings.brief_min_observed_s, ">="),++ ("brief_support_fraction", support, .85, ">="),++ ("brief_contrast", best["median_contrast"], settings.brief_min_contrast, ">="),++ ("brief_excursion_sigma", best["frequency_excursion_hz"] / best["frequency_uncertainty_hz"], 6., ">="),++ ("brief_moving_fraction", best["moving_fraction"], .6, ">="),++ ("brief_prediction_error_q95", best["prediction_error_q95"], .75, "<=")]++ reject([dict(reason=name, measured=float(value), threshold=float(limit), comparison=op)++ for name,value,limit,op in gates if (value < limit if op == ">=" else value > limit)],++ dict(observed_duration_s=observed, support_fraction=support, child_metrics=metrics),++ tuple(x for r in members for x in r.origins))++ continue++ matching_eligible = sum(len(r.points) for r in members) >= 10++ child_ids = [identifier("ridge-", r.points, recording.metadata["source_sha256"]) for r in members]++ proposal_id = "episode-" + hashlib.sha256((recording.metadata["source_sha256"] + "|".join(sorted(child_ids))).encode()).hexdigest()[:20]++ children = []++ for ridge, scale, child_id, m in zip(members, scales, child_ids, metrics):++ points = ridge.points++ t, f, w = points[:, :3].T++ margin = 2 / settings.window_s++ quality = {k: float(v) for k, v in m.items() if isinstance(v, (int, float))}++ quality.update(harmonic_count=float(len(set(orders))) if orders else 0.0,++ frequency_resolution_hz=1 / settings.window_s, time_uncertainty_s=settings.window_s / 2,++ frequency_sigma_hz=m["frequency_uncertainty_hz"],++ fragment_count=float(1 + np.sum(np.diff(t) > settings.max_gap_s)),++ max_observed_gap_s=float(np.max(np.diff(t))),++ frequency_drop_hz=float(np.median(f[:max(3, len(f)//6)]) - np.median(f[-max(3, len(f)//6):])),++ episode_frequency_scale=float(scale), episode_model_version=2.0, matching_eligible=float(matching_eligible))++ event = validate_event(dict(event_id=child_id, harmonic_group_id=proposal_id,++ start_s=max(0., float(t[0] - settings.window_s / 2)),++ end_s=min(recording.metadata["duration_s"], float(t[-1] + settings.window_s / 2)),++ band_hz=[max(.01, float(f.min() - margin)), float(f.max() + margin)],++ ridge=[dict(time_s=float(a), frequency_hz=float(b), weight=float(c)) for a,b,c in points[:, :3]], quality=quality))++ events.append(event)++ children.append(dict(ridge_id=child_id, raw_track_ids=list(ridge.origins), frequency_scale=float(scale),++ amplitude_db=points[:, 3].tolist() if points.shape[1] > 3 else None,++ observed_intervals_s=intervals(t, settings.hop_s), measurements=m))++ episode = dict(proposal_id=proposal_id, event_id=proposal_id, child_ridge_ids=child_ids, children=children,++ start_s=min(e["start_s"] for e in events[-len(members):]), end_s=max(e["end_s"] for e in events[-len(members):]),++ observed_intervals_s=cells, gaps_s=[[cells[i][1], cells[i+1][0]] for i in range(len(cells)-1)],++ observed_duration_s=observed, support_fraction=support,++ band_hz=[float(min(r.points[:,1].min() for r in members)), float(max(r.points[:,1].max() for r in members))],++ matching_eligible=matching_eligible,++ matching_limitation=None if matching_eligible else "Fewer than ten observed samples; retained for acoustic review only",++ acceptance_path="sustained" if long else "brief_strong_evidence",++ confidence="uncalibrated_supported" if long else "uncalibrated_brief_limited",++ physical_source_multiplicity="unresolved", physical_motion_confirmed=False,++ model="constant frequency scales with pairwise supported common motion", group_evidence=group_model, integer_orders=orders,++ limitations=["Common frequency evolution does not establish one physical source or aircraft identity"])++ episodes.append(episode)++ accepted_groups.append([r.points[:, :3] for r in members])++ counts["canonical_proposals"] = len(episodes)++ counts["measured_child_tracks"] = len(events)++ report.update(events=events, episodes=episodes, counts=dict(counts), ridge_count=len(events),++ rejections=dict(measured_ranges=rejection_ranges, counts={k:v for k,v in counts.items() if k not in ("raw_paths", "raw_observations", "provisional_paths", "provisional_observations", "deduplicated_tracks", "stitched_tracks", "canonical_proposals", "measured_child_tracks")},++ traces=traces, traces_enabled=detailed, trace_limit=settings.max_diagnostic_traces),++ association_pairs=work.count, reconciliation_counts=dict(work.decision_counts), reconciliation_decisions=work.decisions,++ decisions_truncated=len(work.decisions) == work.trace_limit)++ return events, accepted_groups++++++def _plot_groups(groups, path, duration, max_gap_s=2.0):++ import matplotlib++ matplotlib.use("Agg")++ from matplotlib import pyplot as plt++ fig, ax = plt.subplots(figsize=(12, 5), layout="constrained")++ for index, group in enumerate(groups):++ for harmonic, points in enumerate(group):++ segments = np.split(points, np.flatnonzero(np.diff(points[:, 0]) > max_gap_s) + 1)++ for segment_index, segment in enumerate(segments):++ ax.plot(segment[:, 0], segment[:, 1], color=f"C{index % 10}", lw=0.8, alpha=0.8,++ label=f"Episode {index + 1}" if harmonic == 0 and segment_index == 0 else None)++ ax.set(xlim=(0, duration), xlabel="Recording-relative time (s)", ylabel="Measured frequency (Hz)",++ title="Canonical acoustic episodes (physical source identity unresolved)")++ if groups:++ ax.legend(loc="upper right", fontsize="small", ncols=2)++ fig.savefig(path, dpi=130)++ plt.close(fig)++++++def _plot_event(recording, group, event, settings, path):++ from matplotlib import pyplot as plt++ # Long merged ridges remain complete in JSON/CSV; image memory is bounded.++ center = (event["start_s"] + event["end_s"]) / 2++ first = max(event["start_s"] - 3, center - settings.chunk_s / 2, 0)++ last = min(event["end_s"] + 3, first + settings.chunk_s, recording.metadata["duration_s"])++ sr = recording.metadata["sample_rate_hz"]++ data = np.memmap(recording.samples_path, dtype="<f4", mode="r")++ spec = _spectrum(np.array(data[round(first * sr):round(last * sr)]), sr, first, settings)++ low = min(points[:, 1].min() for points in group)++ high = max(points[:, 1].max() for points in group)++ limits = (max(settings.min_frequency_hz, low * 0.9), high * 1.1)++ # Only visible cells can affect the image. Keep an extra frequency bin on++ # each side so pcolormesh reconstructs the same boundary-cell coordinates.++ # Whitening still uses the full spectrum and all measured ridges are kept.++ lower = max(0, np.searchsorted(spec.frequency, limits[0]) - 1)++ upper = min(len(spec.frequency), np.searchsorted(spec.frequency, limits[1], side="right") + 1)++ visible = slice(lower, upper)++ fig, ax = plt.subplots(figsize=(10, 4), layout="constrained")++ ax.pcolormesh(spec.time, spec.frequency[visible], spec.contrast[visible], shading="auto", cmap="magma", vmin=0, vmax=6,++ rasterized=True)++ for points in group:++ for segment in np.split(points, np.flatnonzero(np.diff(points[:, 0]) > settings.max_gap_s) + 1):++ ax.plot(segment[:, 0], segment[:, 1], color="cyan", lw=0.9)++ ax.set(xlim=(first, last), ylim=limits,++ xlabel="Recording-relative time (s)", ylabel="Frequency (Hz)",++ title=f"{event['event_id']}: measured ridges; acoustic proposal, identity unconfirmed")++ fig.savefig(path, dpi=130)++ plt.close(fig)diff --cc src/dopplergeist/episodes.pyindex fa76b62,0000000..ff52029mode 100644,000000..100644--- a/src/dopplergeist/episodes.py+++ b/src/dopplergeist/episodes.py@@@ -1,379 -1,0 +1,379 @@@+"""Bounded reconciliation of measured tonal tracks; no physical-source inference.++All time differences below are seconds. Pairwise constant-scale fits have one+parameter; group-wide reconciliation prevents weak transitive bridges.+"""+from collections import Counter+from dataclasses import dataclass+import hashlib++import numpy as np+from scipy import ndimage+++class DiscoveryError(ValueError):+ def __init__(self, code, message):+ self.code = code+ super().__init__(message)+++@dataclass+class Ridge:+ points: np.ndarray+ origins: tuple+++def identifier(prefix, points, source=""):+ # IDs depend on observations, not input enumeration or proposal count.+ values = np.ascontiguousarray(points[:, :3], dtype="<f8")+ return prefix + hashlib.sha256(source.encode() + values.tobytes()).hexdigest()[:20]+++def key(ridge):+ p = ridge.points+ return (float(p[0, 0]), float(np.median(p[:, 1])), identifier("", p))+++def intervals(times, hop):+ """Union of observation cells, not of spectrogram-window footprints."""+ result = []+ for t in sorted(set(float(t) for t in times)):+ left, right = max(0.0, t - hop / 2), t + hop / 2+ if result and left <= result[-1][1] + 1e-8:+ result[-1][1] = max(result[-1][1], right)+ else:+ result.append([left, right])+ return result+++def uncertainty(points, settings):+ f = points[:, 1]+ smooth = ndimage.median_filter(f, size=min(5, len(f) // 2 * 2 + 1), mode="nearest")+ return float(max(1 / settings.window_s, 1.4826 * np.median(np.abs(f - smooth))))+++def aligned(a, b, settings):+ # Use measured times and interpolate only within a supported observation gap.+ first, last = max(a[0, 0], b[0, 0]), min(a[-1, 0], b[-1, 0])+ times = a[(a[:, 0] >= first) & (a[:, 0] <= last), 0]+ if len(times) < 3:+ return None+ following = np.clip(np.searchsorted(b[:, 0], times), 0, len(b) - 1)+ previous = np.maximum(0, following - 1)+ exact = np.abs(b[following, 0] - times) < 1e-7+ supported = exact | ((b[following, 0] - b[previous, 0] <= settings.max_gap_s)+ & (times >= b[previous, 0]))+ times = times[supported]+ if len(times) < 3:+ return None+ return times, np.interp(times, a[:, 0], a[:, 1]), np.interp(times, b[:, 0], b[:, 1])+++def motion(points, settings):+ """Evidence and explicit rejection thresholds, independent of duration gate."""+ t, f, w = points[:, :3].T+ cells = intervals(t, settings.hop_s)+ observed = sum(right - left for left, right in cells)+ span = t[-1] - t[0] + settings.hop_s+ sigma = uncertainty(points, settings)+ smooth = ndimage.median_filter(f, size=5, mode="nearest")+ dt = np.diff(t)+ # Missing intervals do not contribute to moving fraction or smoothness.+ valid = dt <= settings.max_gap_s+ slopes = np.diff(smooth) / dt+ excursion = float(np.quantile(smooth, .95) - np.quantile(smooth, .05))+ required = max(settings.min_drop_hz, float(np.median(f)) * settings.min_fractional_drop, 4 * sigma)+ moving = valid & (np.abs(slopes) > max(.05, excursion / max(span, 1) * .2))+ moving_fraction = float(np.sum(dt[moving]) / max(np.sum(dt[valid]), settings.hop_s))+ # Local prediction on actual timestamps, with uncertainty in Hz and slope.+ errors = []+ for i in range(2, len(t)):+ if dt[i - 1] > settings.max_gap_s:+ continue+ first = max(0, i - 5)+ local_dt = np.diff(t[first:i])+ local_good = local_dt <= settings.max_gap_s+ rates = np.diff(f[first:i]) / local_dt+ if not np.any(local_good):+ continue+ rate = float(np.median(rates[local_good]))+ tolerance = 3 * sigma + max(.5, abs(rate) * .5) * dt[i - 1]+ errors.append(abs(f[i] - f[i - 1] - rate * dt[i - 1]) / tolerance)+ discontinuity = float(np.quantile(errors, .95)) if errors else 0.0+ signs = np.sign(slopes[moving])+ # A turn requires a sustained resolved leg; repeated reversals are modulation+ # or unresolved wandering, not a compulsory descending-flight template.+ runs = []- for sign, duration, observed in zip(np.sign(slopes), dt, valid):- if not observed or abs(sign) == 0:++ for sign, duration, is_observed in zip(np.sign(slopes), dt, valid):++ if not is_observed or abs(sign) == 0:+ continue+ if runs and runs[-1][0] == sign:+ runs[-1][1] += min(duration, settings.hop_s)+ else:+ runs.append([sign, min(duration, settings.hop_s)])+ sustained = [sign for sign, duration in runs if duration >= max(1.5, span * .08)]+ turns = sum(a != b for a, b in zip(sustained, sustained[1:]))+ total_variation = float(np.sum(np.abs(np.diff(smooth))[valid]))+ variation_ratio = total_variation / max(excursion, sigma)+ direction = "stationary"+ if len(signs):+ direction = "turning" if turns else ("rising" if np.median(signs) > 0 else "falling")+ metrics = dict(observed_duration_s=float(observed), span_s=float(span), support_fraction=float(observed / span),+ frequency_excursion_hz=excursion, required_excursion_hz=float(required),+ frequency_uncertainty_hz=sigma, moving_fraction=moving_fraction,+ prediction_error_q95=discontinuity, sustained_turns=int(turns),+ variation_ratio=float(variation_ratio), median_contrast=float(np.median(w)), direction=direction)+ checks = [(excursion >= required, "unresolved_frequency_motion", excursion, required, ">="),+ (moving_fraction >= .35, "insufficient_distributed_motion", moving_fraction, .35, ">="),+ (discontinuity <= 1, "discontinuous_motion", discontinuity, 1, "<="),+ (turns <= 1, "repeated_modulation", turns, 1, "<="),+ (variation_ratio <= 2.8, "wandering_or_modulation", variation_ratio, 2.8, "<=")]+ reasons = [dict(reason=name, measured=float(value), threshold=float(limit), comparison=op)+ for passed, name, value, limit, op in checks if not passed]+ return metrics, reasons+++class Associations:+ def __init__(self, settings):+ self.limit = settings.max_associations+ self.count = 0+ self.decisions = []+ self.decision_counts = Counter()+ self.trace_limit = settings.max_diagnostic_traces++ def charge(self):+ self.count += 1+ if self.count > self.limit:+ raise DiscoveryError("association_budget_exceeded", f"Association work exceeded {self.limit} pairs")++ def record(self, kind, left, right, **evidence):+ self.decision_counts[kind] += 1+ if len(self.decisions) < self.trace_limit:+ self.decisions.append(dict(kind=kind, left=list(left.origins), right=list(right.origins), **evidence))+++def combine(a, b):+ points = np.concatenate((a.points, b.points))+ # Deterministic tie break, strongest contrast per timestamp; no invented data.+ points = points[np.lexsort((points[:, 1], -points[:, 2], points[:, 0]))]+ _, keep = np.unique(points[:, 0], return_index=True)+ return Ridge(points[np.sort(keep)], tuple(sorted(set(a.origins + b.origins))))+++def deduplicate(ridges, settings, work):+ result = []+ for ridge in sorted(ridges, key=key):+ for i, previous in enumerate(result):+ if previous.points[-1, 0] < ridge.points[0, 0]:+ continue+ # Tracks measured in the same chunk can be near-unison components.+ if {x.split(":")[0] for x in ridge.origins} & {x.split(":")[0] for x in previous.origins}:+ continue+ if abs(np.median(ridge.points[:, 1]) - np.median(previous.points[:, 1])) > .2 * np.median(ridge.points[:, 1]):+ continue+ work.charge()+ shared = aligned(ridge.points, previous.points, settings)+ if shared is None or len(shared[0]) < 8:+ continue+ residual = float(np.quantile(np.abs(shared[1] - shared[2]), .95))+ tolerance = .6 / settings.window_s+ # Whole overlap agreement prevents reconciling paths that branch.+ if residual <= tolerance:+ work.record("duplicate_chunk_measurement", ridge, previous, residual_q95_hz=residual, threshold_hz=tolerance)+ result[i] = combine(previous, ridge)+ break+ else:+ result.append(ridge)+ return sorted(result, key=key)+++def stitch(ridges, settings, work):+ ridges = sorted(ridges, key=key)+ incoming, outgoing = [[] for _ in ridges], [[] for _ in ridges]+ for i, left in enumerate(ridges):+ a = left.points+ for j in range(i + 1, len(ridges)):+ right, b = ridges[j], ridges[j].points+ gap = b[0, 0] - a[-1, 0]+ if b[0, 0] > a[-1, 0] + settings.max_fragment_gap_s:+ break+ if gap <= settings.hop_s * 1.1:+ continue+ if abs(b[0, 1] - a[-1, 1]) > .3 * a[-1, 1]:+ continue+ work.charge()+ if len(a) < 4 or len(b) < 4:+ continue+ tail, head = a[a[:, 0] >= a[-1, 0] - 4], b[b[:, 0] <= b[0, 0] + 4]+ if len(tail) < 3 or len(head) < 3:+ continue+ sa = float(np.polyfit(tail[:, 0] - tail[-1, 0], tail[:, 1], 1)[0])+ sb = float(np.polyfit(head[:, 0] - head[0, 0], head[:, 1], 1)[0])+ sigma = uncertainty(a, settings) + uncertainty(b, settings)+ tolerance = 2 * sigma + .25 * min(abs(sa), abs(sb)) * gap+ error = max(abs(b[0, 1] - a[-1, 1] - sa * gap), abs(b[0, 1] - a[-1, 1] - sb * gap))+ # Both observed legs must move in the same direction. A turn in an+ # unobserved gap is deliberately unresolved.+ support = sum(y - x for x, y in intervals(np.r_[a[:, 0], b[:, 0]], settings.hop_s))+ if (sa * sb <= 0 or min(abs(sa), abs(sb)) < .1 or+ max(abs(sa), abs(sb)) > 3 * min(abs(sa), abs(sb)) or+ gap > .35 * support or error > tolerance):+ continue+ outgoing[i].append(j)+ incoming[j].append(i)+ work.record("continuation_candidate", left, right, gap_s=float(gap), prediction_error_hz=float(error), threshold_hz=float(tolerance))+ following = {i: js[0] for i, js in enumerate(outgoing) if len(js) == 1 and len(incoming[js[0]]) == 1}+ for i, js in enumerate(outgoing):+ for j in js:+ work.record("stitch" if following.get(i) == j else "ambiguous_continuation", ridges[i], ridges[j])+ consumed, result = set(), []+ for i, ridge in enumerate(ridges):+ if i in consumed:+ continue+ current, joined = i, ridge+ while current in following:+ current = following[current]+ joined = combine(joined, ridges[current])+ consumed.add(current)+ result.append(joined)+ return result+++def family(scales, tolerance=.006):+ """Minimum-complexity integer family, bounded to orders 1..12.++ Absence of this secondary model does not prohibit coherent nonharmonic+ episodes, which require stronger envelope evidence instead.+ """+ scales = np.asarray(scales) / min(scales)+ fits = []+ for base in range(1, 13):+ orders = np.rint(scales * base).astype(int)+ if max(orders) <= 12 and np.max(np.abs(scales - orders / base) / scales) <= tolerance:+ fits.append(orders.tolist())+ return min(fits, key=lambda orders: (sum(orders), orders)) if fits else None+++def related(a, b, settings):+ shared = aligned(a, b, settings)+ if shared is None or len(shared[0]) < 8:+ return None+ t, f, g = shared+ support = len(t) * settings.hop_s+ if support < .6 * min(len(a), len(b)) * settings.hop_s:+ return None+ scale = float(np.exp(np.median(np.log(g / f))))+ sigma = uncertainty(b, settings) + scale * uncertainty(a, settings)+ error = float(np.quantile(np.abs(g - scale * f), .9))+ # Uncertainty cannot license an arbitrary ratio fit to unresolved motion.+ excursion = min(float(np.ptp(f)) * scale, float(np.ptp(g)))+ if excursion < max(6 * sigma, .03 * np.median(g)) or error > min(2 * sigma, .004 * np.median(g)):+ return None+ corr = float(np.corrcoef(f, g)[0, 1]) if np.std(f) > 0 and np.std(g) > 0 else 0.0+ if not np.isfinite(corr) or corr < .96:+ return None+ harmonic = family([1, scale])+ envelope = None+ if a.shape[1] > 3 and b.shape[1] > 3:+ x, y = np.interp(t, a[:, 0], a[:, 3]), np.interp(t, b[:, 0], b[:, 3])+ if min(np.std(x), np.std(y)) >= 1:+ envelope = float(np.corrcoef(x, y)[0, 1])+ if harmonic is None and (envelope is None or not np.isfinite(envelope) or envelope < .65):+ return None+ # Contradictory measured envelopes block even a convenient integer ratio.+ if envelope is not None and np.isfinite(envelope) and envelope < -.25:+ return None+ return dict(scale=scale, residual_q90_hz=error, threshold_hz=float(min(2 * sigma, .004 * np.median(g))),+ frequency_correlation=corr, envelope_correlation=envelope,+ shared_observations=int(len(t)), integer_orders=harmonic)+++def reconcile(ridges, settings, work):+ """Reconcile strong connections under one group-wide scale model.++ Every member of a group of >=3 needs two resolved-motion witnesses. Every+ overlapping pair is checked against the joint fit, even when its own span+ is too short to establish motion. This permits partial harmonic support+ without permitting a chain of single weak bridges.+ """+ ridges = sorted(ridges, key=key)+ edges = {}+ for i, a in enumerate(ridges):+ for j in range(i + 1, len(ridges)):+ b = ridges[j]+ if b.points[0, 0] > a.points[-1, 0]:+ break+ work.charge()+ evidence = related(a.points, b.points, settings)+ if evidence:+ edges[i, j] = evidence+ def fit(indices):+ work.charge()+ if len(indices) > settings.max_episode_components:+ return None+ positions = {x:i for i,x in enumerate(indices)}+ internal = []+ for ix,x in enumerate(indices):+ for y in indices[ix+1:]:+ work.charge()+ if (x,y) in edges:+ internal.append((x,y,edges[x,y]))+ if len(indices)>2 and any(sum(x==i or y==i for x,y,_ in internal)<2 for i in indices):+ return None+ matrix, values = [], []+ for x,y,e in internal:+ row = np.zeros(len(indices))+ row[positions[y]], row[positions[x]] = 1., -1.+ matrix.append(row[1:]); values.append(np.log(e["scale"]))+ scales = np.exp(np.r_[0., np.linalg.lstsq(np.asarray(matrix),values,rcond=None)[0]])+ checked_pairs, worst_residual = 0, 0.0+ for ix,x in enumerate(indices):+ for iy in range(ix+1,len(indices)):+ y = indices[iy]+ work.charge()+ shared = aligned(ridges[x].points,ridges[y].points,settings)+ if shared is None:+ continue+ ratio = scales[iy]/scales[ix]+ error = float(np.quantile(np.abs(shared[2]-ratio*shared[1]),.9))+ sigma = uncertainty(ridges[y].points,settings)+ratio*uncertainty(ridges[x].points,settings)+ checked_pairs += 1+ worst_residual = max(worst_residual,error/(2*sigma))+ if error > 2*sigma:+ return None+ return dict(scales=scales.tolist(), checked_overlap_pairs=checked_pairs,+ worst_residual_fraction_of_limit=float(worst_residual),+ min_resolved_motion_witnesses=min(sum(x==i or y==i for x,y,_ in internal) for i in indices))+ groups = [{i} for i in range(len(ridges))]+ owners = {i:g for g in groups for i in g}+ fitted = {frozenset(g):dict(scales=[1.],checked_overlap_pairs=0,worst_residual_fraction_of_limit=None,+ min_resolved_motion_witnesses=0) for g in groups}+ ordered = sorted(edges.items(),key=lambda item:(item[1]["residual_q90_hz"]/item[1]["threshold_hz"],item[0]))+ changed = True+ while changed:+ changed = False+ for (i,j),evidence in ordered:+ left, right = owners[i], owners[j]+ if left is right:+ continue+ scales = fit(sorted(left|right))+ if scales is None:+ continue+ work.record("joint_episode",ridges[i],ridges[j],**evidence)+ left.update(right)+ for member in right:+ owners[member] = left+ groups.remove(right)+ fitted[frozenset(left)] = scales+ changed = True+ for (i,j),evidence in ordered:+ if owners[i] is not owners[j]:+ work.record("unresolved_episode_relation",ridges[i],ridges[j],+ reason="insufficient_joint_witnesses_or_inconsistent_group_fit",**evidence)+ result = []+ for group in groups:+ indices = sorted(group)+ model = fitted[frozenset(group)]+ scales = model["scales"]+ result.append(([ridges[x] for x in indices],scales,family(scales),model))+ return resultdiff --cc src/dopplergeist/intake.pyindex 2515b24,83937f6..952c767--- a/src/dopplergeist/intake.py+++ b/src/dopplergeist/intake.py@@@ -94,7 -94,7 +94,8 @@@ class IntakeRecordingbreak--def intake_recording(source, output_dir, *, time_window=None, sample_rate_hz=4000):++def intake_recording(source, output_dir, *, time_window=None, sample_rate_hz=4000,++ resample_filter_size=None):"""Decode mono f32 into a new cache without holding the whole input in RAM.``time_window`` follows the shared RecordingTimeWindow contract and bounds@@@ -102,11 -102,11 +103,15 @@@that explicit window: tags alone do not provide clock error or edit history.A missing window permits acoustic analysis and yields ``needs_input`` forhistorical matching. Existing cache files are never overwritten.++ ``resample_filter_size`` opts into the explicit swresample filter used by++ experimental episode discovery; omission preserves the standard decoder."""from .contracts import validate_recording, validate_requestif type(sample_rate_hz) is not int or not 1000 <= sample_rate_hz <= 192000:raise ValueError("sample_rate_hz must be an integer between 1000 and 192000")++ if resample_filter_size is not None and (type(resample_filter_size) is not int or resample_filter_size <= 0):++ raise ValueError("resample_filter_size must be a positive integer")source = Path(source).resolve()request = validate_request({"schema_version": 1, "audio_path": str(source), "time_window": time_window})probe = probe_media(source)@@@ -120,8 -120,8 +125,10 @@@raise FileExistsError("Intake output already exists; use a new output directory")channels = int(audio["channels"])downmix = "pan=mono|c0=" + "+".join(f"{1 / channels:.17g}*c{i}" for i in range(channels))++ if resample_filter_size is not None:++ downmix += f",aresample=resampler=swr:filter_size={resample_filter_size}:cutoff=0.95"command = ["ffmpeg", "-nostdin", "-v", "error", "-xerror", "-i", str(source),- "-map", "0:a:0", "-vn", "-sn", "-dn", "-af", downmix + ",aresample=resampler=swr:filter_size=64:cutoff=0.95", "-ac", "1", "-ar", str(sample_rate_hz),+ "-map", "0:a:0", "-vn", "-sn", "-dn", "-af", downmix, "-ac", "1", "-ar", str(sample_rate_hz),"-acodec", "pcm_f32le", "-f", "f32le", "pipe:1"]temporary = Nonetry:@@@ -173,10 -173,8 +180,12 @@@"decode": {"decoder": "ffmpeg", "sample_format": "f32le", "channel_policy": "arithmetic channel mean","source_sample_rate_hz": int(audio["sample_rate"]), "source_channels": int(audio["channels"]),"source_codec": audio.get("codec_name", "unknown"), "stream_index": int(audio["index"]),- "audio_time_zero": "first decoded sample after codec skip/discard", "command": command,- "resampling": "ffmpeg swresample, 64-tap low-pass, cutoff 0.95; timestamps start at decoded sample zero",- "usable_frequency_hz": [0.0, .45 * min(sample_rate_hz, int(audio["sample_rate"]))]},+ "audio_time_zero": "first decoded sample after codec skip/discard", "command": command},}++ if resample_filter_size is not None:++ diagnostics["decode"].update(++ resampling=f"ffmpeg swresample, filter_size {resample_filter_size}, cutoff 0.95; timestamps start at decoded sample zero",++ usable_frequency_hz=[0.0, .45 * min(sample_rate_hz, int(audio["sample_rate"]))])# Exclusive creation also prevents accidental replacement on concurrent intake.os.link(temporary, samples_path)with metadata_path.open("x") as target:diff --cc src/dopplergeist/matching.pyindex d64eeff,d2d35a0..057f45e--- a/src/dopplergeist/matching.py+++ b/src/dopplergeist/matching.py@@@ -469,10 -469,8 +469,10 @@@ def prepare_events(detected_events, c=3for event in detected_events:key = event.get("harmonic_group_id") or event["event_id"]groups.setdefault(key, []).append(event)-- settings, measurements = [], []-- for members in groups.values():++ settings, measurements, retained_groups = [], [], []++ for group_id, members in groups.items():+ if any(e.get("quality", {}).get("matching_eligible") == 0 for e in members):+ continuereference = min(members, key=lambda e: np.median([p["frequency_hz"] for p in e["ridge"]]))reference_time = np.array([p["time_s"] for p in reference["ridge"]])reference_frequency = np.array([p["frequency_hz"] for p in reference["ridge"]])@@@ -524,10 -513,10 +524,12 @@@event["event_ids"] = [e["event_id"] for e in members]settings.append(event)measurements.append((RidgeTimes(t), f, w, {}))-- grouped = list(groups.items())-- for index, (first_id, first_members) in enumerate(grouped):-- for following in range(index + 1, len(grouped)):-- second_id, second_members = grouped[following]++ retained_groups.append((group_id, members))++ # Match the prepared settings exactly: ineligible episodes have no setting++ # and must not shift the indices used to attach reused-observation conflicts.++ for index, (first_id, first_members) in enumerate(retained_groups):++ for following in range(index + 1, len(retained_groups)):++ second_id, second_members = retained_groups[following]conflict = next((found for first in first_members for second in second_membersif (found := reused_ridge_observations(first, second)) is not None), None)if conflict is not None:diff --cc tests/test_real_episode_artifact.pyindex 8963788,0000000..1046c73mode 100644,000000..100644--- a/tests/test_real_episode_artifact.py+++ b/tests/test_real_episode_artifact.py@@@ -1,83 -1,0 +1,122 @@@+"""Contract checks on complete observed real-media runs, without audio generation."""+import gzip+import json++from copy import deepcopy+from pathlib import Path++import pytest++from dopplergeist.contracts import validate_event++ROOT=Path(__file__).parents[1]/'benchmarks/acoustic-episodes-349'++[email protected](scope='module')+def observations():+ manifest=json.loads((ROOT/'manifest.json').read_text())+ with gzip.open(ROOT/'observations.jsonl.gz','rt') as stream:+ rows=[json.loads(line) for line in stream]+ assert {r['case_id'] for r in rows}=={c['id'] for c in manifest['cases']}+ return manifest,rows+++def test_complete_real_case_selection_and_input_identity(observations):+ manifest,rows=observations+ assert len(rows)==32+ lookup={c['id']:c for c in manifest['cases']}+ for row in rows:+ for name in ['baseline','new','wide']:+ data=row[name]+ if data is None:+ assert name=='wide' and row['case_id']=='whole-reference'+ continue+ assert data['source_sha256']==lookup[row['case_id']]['sha256']+ assert data.get('status','complete')=='complete'+ assert len({r['new']['code']['implementation_sha256'] for r in rows})==1+++def test_canonical_membership_preserves_all_measured_children(observations):+ for row in observations[1]:+ for data in [row['new'],row['wide']]:+ if data is None:+ continue+ events={e['event_id']:validate_event(e) for e in data['events']}+ assert len(events)==data['counts']['measured_child_tracks']==data['ridge_count']+ assert len(data['episodes'])==data['counts']['canonical_proposals']+ members=[]+ for episode in data['episodes']:+ assert episode['physical_motion_confirmed'] is False+ assert episode['physical_source_multiplicity']=='unresolved'+ assert {c['ridge_id'] for c in episode['children']}==set(episode['child_ridge_ids'])+ for child in episode['children']:+ event=events[child['ridge_id']]+ assert event['harmonic_group_id']==episode['proposal_id']+ assert child['frequency_scale']>0 and child['raw_track_ids']+ assert len(child['amplitude_db'])==len(event['ridge'])+ members.append(child['ridge_id'])+ if sum(len(events[c]['ridge']) for c in episode['child_ridge_ids'])<10:+ assert not episode['matching_eligible']+ assert len(members)==len(set(members))==len(events)+ assert set(members)==set(events)+++def test_observed_gaps_and_resource_limits_are_explicit(observations):+ for row in observations[1]:+ for data in [row['new'],row['wide']]:+ if data is None:+ continue+ settings=data['settings'];counts=data['counts']+ assert counts['provisional_paths']<=settings['max_candidates']+ assert counts['provisional_observations']<=settings['max_measurements']+ assert data['association_pairs']<=settings['max_associations']+ assert len(data['reconciliation_decisions'])<=settings['max_diagnostic_traces']+ assert data['rejections']['traces']==[]+ events={e['event_id']:e for e in data['events']}+ for episode in data['episodes']:+ cells=episode['observed_intervals_s']+ assert sum(b-a for a,b in cells)==pytest.approx(episode['observed_duration_s'])+ assert episode['gaps_s']==[[a[1],b[0]] for a,b in zip(cells,cells[1:])]+ assert len(episode['children'])<=settings['max_episode_components']+ for child in episode['children']:+ for point in events[child['ridge_id']]['ridge']:+ assert not any(a<point['time_s']<b for a,b in episode['gaps_s'])+ assert data['coverage']['analyzed_hz'][1]<=data['coverage']['usable_upper_hz']+ assert not data['coverage']['exhaustive_outside_analyzed_range']++++++def test_skipping_a_group_preserves_conflicts_on_recorded_ridges(observations):++ """Exercise consumer eligibility state without generating ridge samples.++++ The recorded car case contains two proposals sharing measured observations.++ Marking an unrelated earlier group ineligible is a software-state check,++ not a claim that the original detector rejected that recorded group.++ """++ import numpy as np++ from dopplergeist.matching import prepare_events++++ row = next(row for row in observations[1] if row['case_id'] == 'demand-tcar')++ observed = row['wide']['events']++ baseline, baseline_measurements = prepare_events(observed)++ skipped = observed[0]['harmonic_group_id']++ conflicts = [conflict for event in baseline++ for conflict in event.get('shared_ridge_observations', [])]++ assert conflicts++ assert all(skipped not in conflict['group_ids'] for conflict in conflicts)++++ events = deepcopy(observed)++ for event in events:++ if event['harmonic_group_id'] == skipped:++ event['quality']['matching_eligible'] = 0.0++ before = deepcopy(events)++ prepared, measurements = prepare_events(events)++ expected = [(event, measurement)++ for event, measurement in zip(baseline, baseline_measurements)++ if event['harmonic_group_id'] != skipped]++ assert prepared == [event for event, _ in expected]++ assert events == before++ assert [event['ridge'] for event in events] == [event['ridge'] for event in observed]++ assert len(measurements) == len(expected)++ for actual, (_, previous) in zip(measurements, expected):++ np.testing.assert_array_equal(actual[0].time, previous[0].time)++ np.testing.assert_array_equal(actual[1], previous[1])++ np.testing.assert_array_equal(actual[2], previous[2])diff --cc tests/test_real_episode_cli.pyindex 0000000,0000000..bb0b19dnew file mode 100644--- /dev/null+++ b/tests/test_real_episode_cli.py@@@ -1,0 -1,0 +1,81 @@@++"""Exercise CLI routing and coverage failures with unmodified recorded PCM.++++The two four-second excerpts are separate recordings for this software check.++No samples are generated, padded or joined, and proposal recall is not assessed.++"""++import base64++import json++from pathlib import Path++import subprocess++import sys++import tempfile++import unittest++++import numpy as np++from scipy.io import wavfile++++++ROOT = Path(__file__).resolve().parents[1]++++++class RealEpisodeCli(unittest.TestCase):++ def test_explicit_routing_and_source_coverage(self):++ fixture = json.loads((ROOT / "tests/fixtures/real_discovery_normalization.json").read_text())++ self.assertEqual(fixture["sample_format"], "<f4")++ with tempfile.TemporaryDirectory() as temporary:++ root = Path(temporary)++ for index, excerpt in enumerate(fixture["excerpts"]):++ raw = base64.b64decode(excerpt["pcm_f32le_base64"], validate=True)++ self.assertEqual(len(raw), excerpt["sample_count"] * 4)++ audio = root / f"recorded-excerpt-{index}.wav"++ wavfile.write(audio, fixture["sample_rate_hz"], np.frombuffer(raw, dtype="<f4"))++ for experimental in (False, True):++ output = root / f"scan-{index}-{experimental}"++ command = [sys.executable, "-m", "dopplergeist.cli", "discover", str(audio),++ "--output", str(output)]++ if experimental:++ command.append("--experimental-episodes")++ process = subprocess.run(command, cwd=ROOT, capture_output=True, text=True, timeout=60)++ self.assertEqual(process.returncode, 0, process.stderr)++ summary = json.loads(process.stdout)++ artifact = json.loads((output / "discovery/discovery.json").read_text())++ intake = json.loads((output / "intake/intake.json").read_text())++ self.assertEqual(intake["sample_count"], excerpt["sample_count"])++ self.assertEqual(summary["recording"]["duration_s"],++ excerpt["sample_count"] / fixture["sample_rate_hz"])++ self.assertEqual(summary["events_found"], len(artifact["events"]))++ if experimental:++ self.assertTrue(summary["experimental_episodes"])++ self.assertEqual(artifact["schema_version"], 2)++ self.assertEqual(artifact["status"], "complete")++ self.assertEqual(summary["canonical_proposals"], len(artifact["episodes"]))++ self.assertIn("filter_size=64", " ".join(intake["decode"]["command"]))++ else:++ self.assertNotIn("experimental_episodes", summary)++ self.assertNotIn("episodes", artifact)++ self.assertNotIn("aresample", " ".join(intake["decode"]["command"]))++ self.assertEqual((output / "intake/recording.f32").read_bytes(), raw)++++ refused = root / "unrequested-experimental-option"++ process = subprocess.run(++ [sys.executable, "-m", "dopplergeist.cli", "discover", str(audio),++ "--output", str(refused), "--max-frequency-hz", "6000"],++ cwd=ROOT, capture_output=True, text=True, timeout=60)++ self.assertEqual(process.returncode, 2)++ self.assertIn("require --experimental-episodes", process.stderr)++ self.assertFalse(refused.exists())++++ unsupported = root / "unsupported-source-coverage"++ process = subprocess.run(++ [sys.executable, "-m", "dopplergeist.cli", "discover", str(audio),++ "--output", str(unsupported), "--experimental-episodes", "--max-frequency-hz", "6000"],++ cwd=ROOT, capture_output=True, text=True, timeout=60)++ self.assertEqual(process.returncode, 2)++ artifact = json.loads((unsupported / "discovery/discovery.json").read_text())++ self.assertEqual(artifact["status"], "failed")++ self.assertEqual(artifact["failure"]["code"], "unsupported_frequency_coverage")++ self.assertFalse((unsupported / "summary.json").exists())++++++if __name__ == "__main__":++ unittest.main()diff --cc tests/test_real_episode_motion.pyindex 0000000,0000000..27d12a0new file mode 100644--- /dev/null+++ b/tests/test_real_episode_motion.py@@@ -1,0 -1,0 +1,36 @@@++"""Motion metrics on unchanged measured AeroSonicDB child ridges."""++import json++from pathlib import Path++++import numpy as np++++from dopplergeist.episode_discovery import DiscoverySettings++from dopplergeist.episodes import motion++++++def test_recorded_child_duration_and_support():++ fixture = json.loads(++ (Path(__file__).parent / "fixtures/real_episode_children.json").read_text()++ )++ # Durations are the recorded child observation-cell sums in case-0001.++ # Missing intervals remain excluded; these are not continuous-span lengths.++ expected = {++ "ridge-e89a6abd10d83ec9cd4c": (39.0, 45.5),++ "ridge-9834a3c314c9474690ee": (27.5, 33.0),++ "ridge-41f68eae800cafb36acc": (36.5, 36.5),++ "ridge-af2d2e7c0b20d7fec4c2": (12.5, 17.5),++ "ridge-e4492d9b7e99ae1549c9": (17.0, 18.5),++ "ridge-4b9a927849f08dd061ac": (5.0, 8.5),++ }++ events = {event["event_id"]: event for event in fixture["events"]}++ assert set(events) == set(expected)++ settings = DiscoverySettings()++ for event_id, (observed_s, span_s) in expected.items():++ points = np.array([++ [point["time_s"], point["frequency_hz"], point["weight"]]++ for point in events[event_id]["ridge"]++ ])++ metrics, _ = motion(points, settings)++ assert metrics["observed_duration_s"] == observed_s++ assert metrics["span_s"] == span_s++ assert metrics["support_fraction"] == observed_s / span_s