feat: --deep mode + WARNING floor for AAC/Vorbis transcodes (v1.2.0)

[Guillain-RDCDE]

What & why

The README's documented blind spot — high-bitrate AAC / Opus / Vorbis transcodes — turned out to be smaller than we'd written. A measurement campaign showed the bundled v4 CNN (Rule 12) does separate these codecs from genuine FLAC on full-range audio (ROC-AUC 0.94–0.99, AAC-256 0.945), confound-controlled (a lossless ffmpeg round-trip scores AUC 0.500 — the model ignores the pipeline, it sees the codec).

Two things stopped that ability from ever reaching a verdict:

1. Off by one point. Rule 12 is capped at +30, and a full-range AAC/Vorbis transcode earns ~0 from the heuristics — so +30 lands exactly on 30, the top of AUTHENTIC (WARNING starts at 31). A maximally-confident detection couldn't even reach WARNING.
2. The fast path skips Rule 12. To keep big scans fast, the calculator short-circuits on files the heuristics clear (score < 10, no MP3) and returns before Rule 12 — exactly the silent-heuristic profile of these fakes.

Both are fixed here, opt-in, so the default scan stays as fast as before.

Changes

• --deep flag — runs Rule 12 on every file, bypassing the authentic fast path. Slower (a decode + CNN pass per file); the only way to surface silent AAC/Vorbis fakes.
• High-confidence WARNING floor (ml_classifier._WARNING_FLOOR_P = 0.90) — when the CNN is confident on a full-range file the heuristics left silent, lift the verdict to WARNING (never SUSPICIOUS — the model says “look here”, it does not call the file a fake).
• Threaded deep through main → FLACAnalyzer → new_calculate_score → _apply_scoring_rules.
• Docs (newbies + pros): corrected the “near-undetectable” claim (README FAQ, technical-details), documented --deep (README, user-guide), and added the full R&D narrative + the fast-path lesson to ml/README.md.
• Tests: tests/test_rule12_warning_floor.py (4) + a deep-mode fast-path bypass test.
• ml/ probe + measurement scripts committed (regenerable CSV/npz outputs gitignored).

Calibration & proof

Operating point (ml/calibrate_r12_threshold.py, n=240, full-range):

p ≥	authentic FP	aac_256 recall	vorbis recall
0.90	3.8 %	71.7 %	94.6 %
0.95	2.9 %	60.0 %	84.6 %

Proven on the real pipeline (R12_DEEP=1, full-range, 36 sources/codec, WARNING before → after):

codec	WARNING before	WARNING after
aac_256	1	22
vorbis_q5	1	29
opus_128	1	21

Authentic cost: +2 WARNING, 0 SUSPICIOUS.

Limits (kept honest)

• Full-range only. Band-limited material (baroque, 1920s, solo acoustic) remains a fundamental signal limit --deep does not solve.
• The WARNING floor is a real specificity↔recall trade (the authentic FP floor is ~3 % even at p ≥ 0.95) — which is why it stops at WARNING, and why it's opt-in.

Checks

black / isort / flake8 src tests / mypy src all clean; rule-12, deep-mode, scoring and verdict tests pass. Backward compatible — without --deep, behaviour and speed are unchanged.

🤖 Generated with Claude Code