Skip to content

Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)

Integrate acoustic episodes as opt-in reports and fix recorded-data regressions

Cinna Davis838cda67cb52
diff --cc .github/workflows/tests.yml
index 505d90c,b74ac21..6ba7f34
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@@ -47,6 -45,6 +45,8 @@@ jobs
run: python scripts/check_country_profiles.py --online --cache-root "$RUNNER_TEMP/dopplergeist-geography"
- name: Check terrain seams against observed Copernicus raster footprints
run: 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 checkpoints
run: |
python - <<'PY'
diff --cc README.md
index 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 application
Start the browser application:
diff --cc benchmarks/acoustic-episodes-349/README.md
index 9326c8a,0000000..2f24643
mode 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.md
index 24cd238,0000000..7ae24ec
mode 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.
+
+![One canonical family with six measured children](../benchmarks/acoustic-episodes-349/family-episodes.png)
+
+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.
+
+![Separate source-ambiguous vehicle-context trajectories](../benchmarks/acoustic-episodes-349/vehicle-episodes.png)
+
+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.md
index 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.md
index 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 candidates
A `LocationCandidate` contains `lat`, `lon`, finite `score`, a descriptive
diff --cc scripts/discover_audio.py
index 1656648,e8e6d85..0ee1e4e
--- a/scripts/discover_audio.py
+++ b/scripts/discover_audio.py
@@@ -11,7 -11,7 +11,6 @@@ from pathlib import Pat
import subprocess
import time
- from dopplergeist.discovery import DiscoverySettings, discover_events, required_sample_rate
-from dopplergeist.discovery import DiscoverySettings, discover_events
from dopplergeist.intake import intake_recording
from 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.py
index ecd0189,0000000..c6e8574
mode 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.py
index 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 measure
result=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 serve
try:
diff --cc src/dopplergeist/episode_discovery.py
index 0000000,0000000..b4dd3cf
new 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.py
index fa76b62,0000000..ff52029
mode 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 result
diff --cc src/dopplergeist/intake.py
index 2515b24,83937f6..952c767
--- a/src/dopplergeist/intake.py
+++ b/src/dopplergeist/intake.py
@@@ -94,7 -94,7 +94,8 @@@ class IntakeRecording
break
--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`` for
historical 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_request
if 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 = None
try:
@@@ -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.py
index 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=3
for 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):
+ continue
reference = 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_members
if (found := reused_ridge_observations(first, second)) is not None), None)
if conflict is not None:
diff --cc tests/test_real_episode_artifact.py
index 8963788,0000000..1046c73
mode 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.py
index 0000000,0000000..bb0b19d
new 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.py
index 0000000,0000000..27d12a0
new 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