S162: SV-B1 isteidad filename, SV-B2 keepalive localhost, rm tajalli+itiqan-v5, add safaa-v3

app.py

@@ -35,7 +35,7 @@ BASE = Path(__file__).parent
 ENGINE_SCRIPTS = {
     "v11.0": BASE / "engine_safaa_v3_fixed.py",  # S149
     "v11.1": BASE / "true_engine_itiqan_v2_fixed.py",
-    "v11.2": BASE / "engine_isteidad_v12.py",
+    "v11.2": BASE / "engine_isteidad_v21.py",  # S162-SV-B1
     "v10.0": BASE / "engine_safaa_v3_fixed.py",  # S149
     "v9.0":  BASE / "engine_v90.py",
     "v8.9":  BASE / "engine_v89.py",
@@ -137,7 +137,7 @@ threading.Thread(target=_janitor, daemon=True).start()
 def _keepalive():
     import urllib.request
     time.sleep(120)
-    url = os.environ.get("SPACE_URL", "https://carm5333-tilawa-server.hf.space/ping")
+    url = os.environ.get("SPACE_URL", "http://127.0.0.1:7860/ping")  # S162-SV-B2
     while True:
         try: urllib.request.urlopen(url, timeout=15)
         except Exception: pass

engine_safaa_v3_fixed.py

@@ -0,0 +1,863 @@
+#!/usr/bin/env python3
+"""
+الصفاء v3  —  Dedicated Dereverberation Engine
+إزالة الصدى والريفيرب
+
+FIXES vs v2:
+  B1  _jalaa() late window: 150ms → 450ms (was reading 50-200ms; §3.3 says 50-500ms)
+  B2  _decode() now uses pcm_f32le → float32; soundfile when available (no 16-bit truncation)
+  B3  _band_energy() samples across full file (was FFT of first 1024 samples only)
+  B4  G4 Ra-trill: scans full audio in overlapping 1s windows (was first 1s only)
+  B5  _rt60() fallback slope condition was malformed (med-4 guard logic fixed)
+
+IMPROVEMENTS vs v2:
+  I1  DF3 three passes now run in parallel (ThreadPoolExecutor) — 3× faster
+  I2  _enc() intermediates are mono; only final output is stereo
+  I3  _tailnr() reduces nr by 1 when JALAA already ran (avoid double-attenuation)
+  I4  DF3 speech-pass attenuation capped to §79 per-style limits:
+        Murattal ≤ 18 dB  /  Mujawwad ≤ 6 dB
+  I5  WPE LRA check uses 50% overlapping frames (was non-overlapping → noisy)
+  I6  SafaaState gains guard_pass/guard_warn lists (structured; JSON report improved)
+  I7  LF EQ: LF band RT60 scaled by 1.3× per §3.4 (LF decays slower than broadband)
+  I8  process() tracks all temp paths; single cleanup on exit (no leaks)
+  I9  _decode() try/finally ensures temp file removed on exception
+  I10 DRR-weighted JALAA: skip when DRR already > 6 dB (room is already reasonably dry)
+
+PIPELINE  (unchanged order)
+  S1  RT60 estimation (Schroeder backward integration)
+  S2  Sub-band LF room mode removal (3 bands, LF-scaled depth) [B5/I7]
+  S3  WPE dereverberation RT60 > 1.0s
+  S4  DF3 reverb-adapted (speech/transition/tail, parallel) [I1/I4]
+  S5  JALAA per-frame DRR gate [B1/I10]
+  S6  Tail floor NR (afftdn calibrated) [I3]
+  S7  Arabic phoneme guards [B3/B4]
+
+USAGE
+  python3 engine_safaa_v3.py input.wav output.wav [--tier X] [--mujawwad 0.0] [--rt60 0.0]
+
+KB REFS: §3 §28 §35 §36 §52 §79 §109 §138 §140 §143 §145 §151 §152 §154
+"""
+from __future__ import annotations
+
+__version__ = 'v3'
+
+import os, shutil, subprocess, tempfile, time, warnings  # S156: time for temp uniqueness
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional, Tuple
+warnings.filterwarnings('ignore')
+
+_TMP = tempfile.gettempdir()
+
+try:
+    import numpy as np
+    NUMPY_OK = True
+except ImportError:
+    NUMPY_OK = False
+
+try:
+    import soundfile as SF
+    SF_OK = True
+except ImportError:
+    SF_OK = False
+
+try:
+    from scipy.io import wavfile as _scipy_wavfile
+    SCIPY_WAV_OK = True
+except ImportError:
+    SCIPY_WAV_OK = False
+
+# DF3 binary
+_DF3_CLI_BIN = ''
+for _c in ['deep-filter', 'deepfilter', 'deep_filter', '/usr/local/bin/deep-filter']:
+    if shutil.which(_c):
+        _DF3_CLI_BIN = _c; break
+DF3_OK = bool(_DF3_CLI_BIN)
+
+# nara_wpe
+WPE_OK = False
+try:
+    from nara_wpe.wpe import wpe_v8
+    from nara_wpe.utils import stft as _wpe_stft, istft as _wpe_istft
+    WPE_OK = True
+except ImportError:
+    pass
+
+# ─── Constants ────────────────────────────────────────────────────────────────
+SR             = 48000
+WAV_CODEC      = 'pcm_s24le'
+RT60_MIN       = 0.15    # below: nothing to do
+RT60_WPE_MIN   = 1.00    # §109.6
+RT60_TAILNR    = 0.30
+RT60_AGGR      = 1.50
+MUJ_RT60_FLOOR = 1.20    # §145.3
+
+# §79 per-style DF attenuation hard limits
+_DF3_LIM_MURATTAL  = 18   # dB maximum
+_DF3_LIM_MUJAWWAD  =  6   # dB maximum
+_DF3_SPEECH        = 12
+_DF3_TRANS         = 20
+_DF3_TAIL          = 28
+
+_CHUNK_S       = 0.100
+_XFADE_N       = 960
+
+_RMS_MAX_DELTA = 1.0
+_LRA_MAX_DELTA = 0.5     # §109.4
+
+DRR_ALREADY_DRY = 6.0   # dB — skip JALAA if DRR already above this [I10]
+
+
+# ─── State ────────────────────────────────────────────────────────────────────
+@dataclass
+class SafaaState:
+    input_path:    str   = ''
+    source_tier:   str   = 'TIER_UNKNOWN'
+    mujawwad_conf: float = 0.0
+    rt60_initial:  float = 0.0
+    drr_before:    float = 0.0
+    drr_after:     float = 0.0
+    lf_eq:         bool  = False
+    wpe:           bool  = False
+    df3:           bool  = False
+    jalaa:         bool  = False
+    tail_nr:       bool  = False
+    guard_reverts: int   = 0
+    guard_pass:    List[str] = field(default_factory=list)   # [I6]
+    guard_warn:    List[str] = field(default_factory=list)   # [I6]
+    log:           List[str] = field(default_factory=list)
+    _tmps:         List[str] = field(default_factory=list, repr=False)
+
+def _L(st, msg):
+    st.log.append(msg); print(msg)
+
+def _track(st, path):
+    """Register a temp path for cleanup. Returns path."""
+    if path and path not in (st.input_path,):
+        st._tmps.append(path)
+    return path
+
+def _cleanup_all(st):
+    for p in st._tmps:
+        try:
+            if p and os.path.exists(p): os.unlink(p)
+        except Exception:
+            pass
+    st._tmps.clear()
+
+
+# ─── FFmpeg helpers ───────────────────────────────────────────────────────────
+def _run(cmd, timeout=600):
+    r = subprocess.run(cmd, capture_output=True, timeout=timeout)
+    return r.returncode, r.stdout, r.stderr
+
+def _tmp(tag, st=None):
+    # S156-B2: add nanosecond suffix — avoids collision between concurrent server jobs
+    p = os.path.join(_TMP, f'safaa3_{tag}_{os.getpid()}_{time.time_ns()}.wav')
+    if st is not None:
+        st._tmps.append(p)
+    return p
+
+def _cleanup(*paths):
+    for p in paths:
+        try:
+            if p and os.path.exists(p): os.unlink(p)
+        except Exception:
+            pass
+
+def _decode(path, st=None):
+    """
+    Float32 mono at SR. [B2/I9]
+    Uses soundfile when available (faster, native float32).
+    Falls back to ffmpeg pcm_f32le + wave read.
+    try/finally ensures temp file removed on exception.
+    """
+    if not NUMPY_OK:
+        return None
+    t = None
+    try:
+        if SF_OK:
+            # ffmpeg → pcm_f32le temp, then soundfile reads it natively
+            t = os.path.join(_TMP, f'safaa3_dec_{os.getpid()}_{time.time_ns()}.wav')  # S156-B2
+            rc, _, _ = _run(['ffmpeg', '-y', '-i', path,
+                             '-acodec', 'pcm_f32le',
+                             '-ar', str(SR), '-ac', '1',
+                             '-loglevel', 'error', t])
+            if rc or not os.path.exists(t):
+                return None
+            data, _ = SF.read(t, dtype='float32', always_2d=False)
+            return data
+        elif SCIPY_WAV_OK:
+            # scipy.io.wavfile can read pcm_f32le natively
+            t = os.path.join(_TMP, f'safaa3_dec_{os.getpid()}_{time.time_ns()}.wav')  # S156-B2
+            rc, _, _ = _run(['ffmpeg', '-y', '-i', path,
+                             '-acodec', 'pcm_f32le',
+                             '-ar', str(SR), '-ac', '1',
+                             '-loglevel', 'error', t])
+            if rc or not os.path.exists(t):
+                return None
+            _, data = _scipy_wavfile.read(t)
+            if data.dtype != np.float32:
+                data = data.astype(np.float32) / np.iinfo(data.dtype).max
+            return data.copy()
+        else:
+            # Final fallback: pcm_s16le → int16 → float32 normalised
+            t = os.path.join(_TMP, f'safaa3_dec_{os.getpid()}_{time.time_ns()}.wav')  # S156-B2
+            rc, _, _ = _run(['ffmpeg', '-y', '-i', path,
+                             '-acodec', 'pcm_s16le',
+                             '-ar', str(SR), '-ac', '1',
+                             '-loglevel', 'error', t])
+            if rc or not os.path.exists(t):
+                return None
+            import wave as _w
+            with _w.open(t, 'rb') as f:
+                raw = f.readframes(f.getnframes())
+            return np.frombuffer(raw, dtype=np.int16).astype(np.float32) / 32768.0
+    except Exception:
+        return None
+    finally:
+        if t and os.path.exists(t):
+            try: os.unlink(t)
+            except Exception: pass
+
+def _enc_mono(src, dst):
+    """Intermediate encode: mono 24-bit. [I2]"""
+    rc, _, _ = _run(['ffmpeg', '-y', '-i', src,
+                     '-acodec', WAV_CODEC,
+                     '-ar', str(SR), '-ac', '1',
+                     '-loglevel', 'error', dst])
+    return rc == 0 and os.path.exists(dst)
+
+def _enc_stereo(src, dst):
+    """Final output encode: stereo 24-bit. [I2]"""
+    rc, _, _ = _run(['ffmpeg', '-y', '-i', src,
+                     '-acodec', WAV_CODEC,
+                     '-ar', str(SR), '-ac', '2',
+                     '-loglevel', 'error', dst])
+    return rc == 0 and os.path.exists(dst)
+
+def _rmsdb(s):
+    return float(20 * np.log10(np.sqrt(np.mean(s ** 2)) + 1e-10))
+
+def _band_energy(s, flo, fhi, n_fft=2048, n_samples=8):
+    """
+    Band energy estimate sampled across the full signal. [B3]
+    Averages n_samples evenly-spaced windows rather than only the first n_fft samples.
+    """
+    if len(s) < n_fft:
+        return 0.0
+    step = max(n_fft, len(s) // (n_samples + 1))
+    positions = range(0, len(s) - n_fft, step)
+    energies = []
+    fr = np.fft.rfftfreq(n_fft, 1.0 / SR)
+    mask = (fr >= flo) & (fr <= fhi)
+    for pos in positions:
+        sp = np.abs(np.fft.rfft(s[pos:pos + n_fft], n=n_fft))
+        energies.append(float(np.mean(sp[mask] ** 2) + 1e-20))
+    return float(np.mean(energies)) if energies else 0.0
+
+
+# ─── Stage 1: RT60 (Schroeder backward integration) ──────────────────────────
+def _rt60(samples, sr=SR):
+    """
+    Schroeder backward integration (§3.1).
+    Find -5 dB and -25 dB crossings of backward energy → T20 × 3 = T60.
+    Fallback: linear regression on the decay region. [B5]
+    """
+    if not NUMPY_OK or samples is None or len(samples) < sr * 3:
+        return 0.0
+    fn = int(0.020 * sr)
+    n = len(samples) // fn
+    if n < 30:
+        return 0.0
+
+    energy = np.array([float(np.mean(samples[i * fn:(i + 1) * fn] ** 2)) for i in range(n)])
+    energy = np.maximum(energy, 1e-20)
+    sch = np.cumsum(energy[::-1])[::-1]
+    sch_db = 10 * np.log10(sch / (sch[0] + 1e-20))
+
+    t5 = t25 = None
+    for i, v in enumerate(sch_db):
+        if t5  is None and v <= -5.0:  t5  = i * 0.020
+        if t25 is None and v <= -25.0: t25 = i * 0.020; break
+    if t5 is not None and t25 is not None and t25 > t5:
+        return float(np.clip((t25 - t5) * 3.0, 0.0, 6.0))
+
+    # Fallback: slope estimation on the decay tail [B5]
+    edb = 10 * np.log10(energy)
+    med = float(np.median(edb))
+    # Find the decay region: frames below median but above noise floor
+    decay_mask = (edb > med - 30) & (edb < med - 2)
+    if decay_mask.sum() < 6:
+        return 0.0
+    t_arr = np.where(decay_mask)[0] * 0.020
+    e_arr = edb[decay_mask]
+    slope = float(np.polyfit(t_arr, e_arr, 1)[0])
+    if slope >= -1.0:
+        return 0.0
+    return float(np.clip(60.0 / abs(slope), 0.0, 4.0))
+
+
+def _drr(samples, sr=SR):
+    """
+    DRR: energy ratio early(0-50ms) vs late(50-500ms) (§3.3/§28.6).
+    """
+    if not NUMPY_OK or samples is None:
+        return 0.0
+    en = int(0.050 * sr)
+    ln = int(0.450 * sr)           # late window: 50-500ms
+    step = int(0.200 * sr)
+    vals = []
+    for s in range(0, len(samples) - en - ln, step):
+        er = float(np.sqrt(np.mean(samples[s:s + en] ** 2)) + 1e-10)
+        lr = float(np.sqrt(np.mean(samples[s + en:s + en + ln] ** 2)) + 1e-10)
+        if er > 1e-5 and lr > 1e-5:
+            vals.append(20.0 * np.log10(er / lr))
+    return float(np.median(vals)) if vals else 0.0
+
+
+# ─── Stage 2: Sub-band LF EQ (§3.4) ─────────────────────────────────────────
+def _lf_eq(wav, samples, rt60, st):
+    """
+    Three EQ bands with LF-scaled depth. [I7]
+    §3.4: LF bands have longer RT60 (empirically ~1.3× broadband).
+    Apply the LF multiplier before computing per-band depth.
+    Mujawwad: reduce depth and enforce RT60 floor (§145.3).
+    """
+    if rt60 < RT60_MIN:
+        return wav
+    lf_rt60  = rt60 * 1.30        # §3.4: LF decays ~30% slower [I7]
+    scale    = float(np.clip(lf_rt60 / 0.5, 1.0, 6.0))
+    d_sub    = float(np.clip(scale * 1.0, 1.0, 6.0))
+    d_lo     = float(np.clip(scale * 0.7, 0.7, 4.2))
+    d_room   = float(np.clip(scale * 0.4, 0.4, 2.4))
+
+    if st.mujawwad_conf > 0.6:
+        d_sub *= 0.5; d_lo *= 0.5; d_room *= 0.5
+        if rt60 < MUJ_RT60_FLOOR * 1.5:
+            r = float(np.clip((rt60 - MUJ_RT60_FLOOR) / (MUJ_RT60_FLOOR * 0.5 + 0.001), 0, 1))
+            d_sub *= r; d_lo *= r; d_room *= r
+            _L(st, f'  [S2-LF] Mujawwad floor limiter ratio={r:.2f}')
+
+    flt = []
+    if d_sub  > 0.2: flt.append(f'equalizer=f=150:width_type=o:width=1.4:g=-{d_sub:.1f}')
+    if d_lo   > 0.2: flt.append(f'equalizer=f=300:width_type=o:width=1.2:g=-{d_lo:.1f}')
+    if d_room > 0.2: flt.append(f'equalizer=f=500:width_type=o:width=1.0:g=-{d_room:.1f}')
+    if not flt:
+        return wav
+
+    out = _tmp('s2', st)
+    rc, _, _ = _run(['ffmpeg', '-y', '-i', wav, '-af', ','.join(flt),
+                     '-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',  # mono [I2]
+                     '-loglevel', 'error', out])
+    if rc or not os.path.exists(out):
+        return wav
+
+    post = _decode(out)
+    if post is not None and samples is not None:
+        d = _rmsdb(post) - _rmsdb(samples)
+        if abs(d) > 3.0:   # relaxed: LF EQ at high RT60 can legitimately remove >1dB
+            _cleanup(out); st.guard_reverts += 1
+            _L(st, f'  [S2-LF] RMS Δ={d:+.2f}dB — REVERT'); return wav
+
+    st.lf_eq = True
+    _L(st, f'  [S2-LF] ✓ lf_rt60={lf_rt60:.2f}s sub={d_sub:.1f} lo={d_lo:.1f} room={d_room:.1f} dB')
+    return out
+
+
+# ─── Stage 3: WPE (threshold 1.0s, §109.6) ───────────────────────────────────
+def _lra_overlapping(s, frame_s=0.4, hop_s=0.2, sr=SR):
+    """LRA estimate using 50% overlapping frames. [I5]"""
+    fn = int(frame_s * sr)
+    hn = int(hop_s * sr)
+    if len(s) < fn:
+        return 0.0
+    db = [float(20 * np.log10(np.sqrt(np.mean(s[i:i + fn] ** 2)) + 1e-10))
+          for i in range(0, len(s) - fn, hn)]
+    return float(np.percentile(db, 95) - np.percentile(db, 10)) if len(db) >= 4 else 0.0
+
+def _wpe(wav, rt60, st):
+    if not WPE_OK:
+        _L(st, '  [S3-WPE] nara_wpe not installed → pip install nara_wpe soundfile')
+        return wav
+    if rt60 < RT60_WPE_MIN:
+        _L(st, f'  [S3-WPE] RT60={rt60:.2f}s < {RT60_WPE_MIN}s — skip (§109.6)')
+        return wav
+
+    _L(st, f'  [S3-WPE] RT60={rt60:.2f}s — running WPE')
+    d = tempfile.mkdtemp(prefix='safaa3_wpe_')
+    try:
+        mi = os.path.join(d, 'in.wav')
+        rc, _, _ = _run(['ffmpeg', '-y', '-i', wav,
+                         '-acodec', 'pcm_f32le', '-ar', str(SR), '-ac', '1',
+                         '-loglevel', 'error', mi])
+        if rc or not os.path.exists(mi):
+            return wav
+        if SF_OK:
+            y, _ = SF.read(mi, dtype='float32', always_2d=False)
+        else:
+            import wave as _w
+            with _w.open(mi, 'rb') as f: raw = f.readframes(f.getnframes())
+            y = np.frombuffer(raw, dtype=np.float32).copy()
+
+        if   st.mujawwad_conf > 0.6: taps, iters = 5, 2
+        elif rt60 > 4.0:              taps, iters = 12, 3
+        elif rt60 > 2.0:              taps, iters = 10, 3
+        else:                         taps, iters = 8, 3
+        delay = 3
+
+        Y = _wpe_stft(y, size=512, shift=128)
+        Z = wpe_v8(Y[..., np.newaxis], taps=taps, delay=delay, iterations=iters)
+        z = _wpe_istft(Z[..., 0], size=512, shift=128)
+        z = z[:len(y)] if len(z) > len(y) else np.pad(z, (0, len(y) - len(z)))
+
+        ld = abs(_lra_overlapping(y) - _lra_overlapping(z))   # [I5]
+        if ld > _LRA_MAX_DELTA:
+            _L(st, f'  [S3-WPE] LRA Δ={ld:.2f}LU — retry iters-1')
+            Z2 = wpe_v8(Y[..., np.newaxis], taps=taps, delay=delay, iterations=max(1, iters - 1))
+            z2 = _wpe_istft(Z2[..., 0], size=512, shift=128)
+            z2 = z2[:len(y)] if len(z2) > len(y) else np.pad(z2, (0, len(y) - len(z2)))
+            ld2 = abs(_lra_overlapping(y) - _lra_overlapping(z2))
+            if ld2 > _LRA_MAX_DELTA:
+                st.guard_reverts += 1
+                _L(st, f'  [S3-WPE] LRA {ld2:.2f}LU after retry — REVERT'); return wav
+            z = z2; ld = ld2
+
+        mo = os.path.join(d, 'out.wav')
+        if SF_OK:
+            SF.write(mo, z.astype(np.float32), SR, subtype='FLOAT')
+        else:
+            import wave as _w
+            b16 = (np.clip(z, -1, 1) * 32767).astype(np.int16)
+            with _w.open(mo, 'wb') as f:
+                f.setnchannels(1); f.setsampwidth(2); f.setframerate(SR)
+                f.writeframes(b16.tobytes())
+        out = _tmp('s3', st)
+        if not _enc_mono(mo, out):
+            return wav
+        st.wpe = True
+        _L(st, f'  [S3-WPE] ✓ taps={taps} delay={delay} iters={iters} LRA Δ={ld:.2f}LU')
+        return out
+    except Exception as e:
+        _L(st, f'  [S3-WPE] exception: {e}'); return wav
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+# ─── Stage 4: DF3 reverb-adapted pass (parallel) [I1/I4] ─────────────────────
+def _df3_run_one(args):
+    """Worker: run DF3 at one attenuation level. Returns (name, array|None)."""
+    name, at, cli_bin, fi, od, SR_ = args
+    import wave as _w
+    r = subprocess.run([cli_bin, '--atten-lim-db', str(at), '-o', od, fi],
+                       capture_output=True, timeout=600)
+    wp = os.path.join(od, os.path.basename(fi))
+    if r.returncode or not os.path.exists(wp):
+        return name, None
+    with _w.open(wp, 'rb') as f:
+        raw = f.readframes(f.getnframes())
+    return name, np.frombuffer(raw, dtype=np.int16).astype(np.float32) / 32768.0
+
+def _df3(wav, samples, rt60, st):
+    if not DF3_OK:
+        _L(st, '  [S4-DF3] deep-filter not found — skip'); return wav
+
+    # Attenuation levels
+    ta = _DF3_TAIL   + (4 if rt60 > RT60_AGGR else 0)
+    ra = _DF3_TRANS  + (2 if rt60 > RT60_AGGR else 0)
+    sa = _DF3_SPEECH
+
+    # §79 per-style hard limits [I4]
+    if st.mujawwad_conf > 0.6:
+        lim = _DF3_LIM_MUJAWWAD
+    else:
+        lim = _DF3_LIM_MURATTAL
+    sa = min(sa, lim)
+    ra = min(ra, lim + 8)    # transition/tail may exceed speech limit but respect style spirit
+    ta = min(ta, lim + 16)
+    if st.mujawwad_conf > 0.6:
+        ta = min(ta, int(ta * 0.70)); ra = min(ra, int(ra * 0.70)); sa = min(sa, int(sa * 0.80))
+
+    import wave as _w
+    d = tempfile.mkdtemp(prefix='safaa3_df3_')
+    try:
+        fi = os.path.join(d, 'in.wav')
+        rc, _, _ = _run(['ffmpeg', '-y', '-i', wav,
+                         '-acodec', 'pcm_s16le', '-ar', str(SR), '-ac', '1',
+                         '-loglevel', 'error', fi])
+        if rc or not os.path.exists(fi):
+            return wav
+        with _w.open(fi, 'rb') as f: raw = f.readframes(f.getnframes())
+        s16 = np.frombuffer(raw, dtype=np.int16).astype(np.float32) / 32768.0
+
+        cn = int(_CHUNK_S * SR); nc = len(s16) // cn
+        if nc < 1:
+            return wav
+
+        rms = np.array([float(np.sqrt(np.mean(s16[i*cn:(i+1)*cn]**2)) + 1e-10) for i in range(nc)])
+        zcr = np.array([float(np.mean(np.abs(np.diff(np.sign(s16[i*cn:(i+1)*cn]))))) for i in range(nc)])
+        rp30 = float(np.percentile(rms, 30)); rp70 = float(np.percentile(rms, 70))
+        zm   = float(np.median(zcr))
+        labels = np.where((rms >= rp70) & (zcr >= zm * 0.7), 0,
+                          np.where((rms <= rp30) & (zcr < zm * 0.5), 2, 1))
+
+        # Parallel DF3 passes [I1]
+        jobs = []
+        for nm, at in [('speech', sa), ('transition', ra), ('tail', ta)]:
+            od = os.path.join(d, nm); os.makedirs(od, exist_ok=True)
+            jobs.append((nm, at, _DF3_CLI_BIN, fi, od, SR))
+
+        pas = {}
+        with ThreadPoolExecutor(max_workers=3) as ex:
+            futs = {ex.submit(_df3_run_one, j): j[0] for j in jobs}
+            for fut in as_completed(futs):
+                nm, arr = fut.result()
+                if arr is None:
+                    _L(st, f'  [S4-DF3] {nm} failed — abort'); return wav
+                pas[nm] = arr
+                atten = next(j[1] for j in jobs if j[0] == nm)
+                _L(st, f'  [S4-DF3] {nm:10s} {atten:2d}dB ✓')
+
+        pa = [pas['speech'], pas['transition'], pas['tail']]
+        ml = min(len(s16), min(len(a) for a in pa))
+        out_s = np.empty(ml, dtype=np.float32)
+        t = np.linspace(0, 1, _XFADE_N, dtype=np.float32)
+        ci_ = 0.5 * (1 - np.cos(np.pi * t)).astype(np.float32); co_ = 1 - ci_
+        pl = int(labels[0])
+        for ci in range(nc):
+            s = ci * cn; e = min((ci + 1) * cn, ml)
+            if e > ml: break
+            lb = int(labels[ci])
+            if lb != pl and ci > 0 and s + _XFADE_N <= ml:
+                b = min(_XFADE_N, e - s)
+                out_s[s:s+b] = pa[pl][s:s+b] * co_[:b] + pa[lb][s:s+b] * ci_[:b]
+                if e > s + _XFADE_N: out_s[s+_XFADE_N:e] = pa[lb][s+_XFADE_N:e]
+            else:
+                out_s[s:e] = pa[lb][s:e]
+            pl = lb
+
+        bm = os.path.join(d, 'blend.wav')
+        b16 = (np.clip(out_s, -1, 1) * 32767).astype(np.int16)
+        with _w.open(bm, 'wb') as f:
+            f.setnchannels(1); f.setsampwidth(2); f.setframerate(SR)
+            f.writeframes(b16.tobytes())
+        out = _tmp('s4', st)
+        if not _enc_mono(bm, out):
+            return wav
+
+        delta = _rmsdb(b16.astype(np.float32) / 32768.0) - _rmsdb(s16)
+        if abs(delta) > _RMS_MAX_DELTA * 2:
+            _cleanup(out); st.guard_reverts += 1
+            _L(st, f'  [S4-DF3] RMS Δ={delta:+.2f}dB — REVERT'); return wav
+        st.df3 = True
+        _L(st, f'  [S4-DF3] ✓ sa={sa} ra={ra} ta={ta} RMS Δ={delta:+.2f}dB  '
+              f'speech={int(np.sum(labels==0))} trans={int(np.sum(labels==1))} '
+              f'tail={int(np.sum(labels==2))}')
+        return out
+    except Exception as e:
+        _L(st, f'  [S4-DF3] exception: {e}'); return wav
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+# ─── Stage 5: JALAA per-frame DRR gate (§28.6) ───────────────────────────────
+def _jalaa(wav, samples, rt60, drr_before, st):
+    """
+    Per-frame DRR classification → calibrated afftdn on reverb-dominated frames.
+    [B1] Late window corrected to 450ms (50-500ms per §3.3).
+    [I10] Skip entirely if DRR already > DRR_ALREADY_DRY (room is dry enough).
+    """
+    if not NUMPY_OK or samples is None or rt60 < 0.30:
+        _L(st, f'  [S5-JALAA] RT60={rt60:.2f}s < 0.30 — skip'); return wav
+    if drr_before > DRR_ALREADY_DRY:
+        _L(st, f'  [S5-JALAA] DRR={drr_before:.1f}dB already dry — skip [I10]'); return wav
+
+    fn = int(0.200 * SR)
+    en = int(0.050 * SR)
+    ln = int(0.450 * SR)          # [B1] was 0.150 → 450ms (50-500ms window)
+    n  = len(samples) // fn
+    if n < 5:
+        return wav
+
+    nf_vals = []
+    for i in range(n):
+        s = i * fn; chunk = samples[s:s + fn]
+        if len(chunk) < en + ln:
+            continue
+        er = float(np.sqrt(np.mean(chunk[:en] ** 2)) + 1e-10)
+        lr = float(np.sqrt(np.mean(chunk[en:en + ln] ** 2)) + 1e-10)
+        if er < 1e-5: continue
+        if 20.0 * np.log10(er / lr) < 3.0:   # reverb-dominated
+            nf_vals.append(float(20 * np.log10(lr + 1e-10)))
+
+    if not nf_vals:
+        _L(st, '  [S5-JALAA] no reverb frames — skip'); return wav
+
+    nf = float(np.clip(float(np.median(nf_vals)) + 3, -72, -25))
+    nr = 2 if rt60 > RT60_AGGR else 1
+    if st.mujawwad_conf > 0.6: nr = max(1, nr - 1)
+
+    out = _tmp('s5', st)
+    rc, _, _ = _run(['ffmpeg', '-y', '-i', wav,
+                     '-af', f'afftdn=nr={nr}:nf={nf:.0f}:tn=1',
+                     '-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
+                     '-loglevel', 'error', out])
+    if rc or not os.path.exists(out):
+        return wav
+
+    post = _decode(out)
+    if post is not None:
+        d = _rmsdb(post) - _rmsdb(samples)
+        if abs(d) > _RMS_MAX_DELTA:
+            _cleanup(out); st.guard_reverts += 1
+            _L(st, f'  [S5-JALAA] RMS Δ={d:+.2f}dB — REVERT'); return wav
+
+    st.jalaa = True
+    _L(st, f'  [S5-JALAA] ✓ reverb_frames={len(nf_vals)}/{n} nf={nf:.0f}dB nr={nr}')
+    return out
+
+
+# ─── Stage 6: Tail floor NR ─────────────────────────────────────────────────���─
+def _tailnr(wav, samples, rt60, st):
+    """
+    [I3] If JALAA already ran, reduce nr by 1 to avoid double-attenuation.
+    """
+    if rt60 < RT60_TAILNR or samples is None or not NUMPY_OK:
+        return wav
+    fn = int(0.200 * SR)
+    overall = _rmsdb(samples)
+    fdb = np.array([float(20 * np.log10(np.sqrt(np.mean(samples[i:i + fn] ** 2)) + 1e-10))
+                    for i in range(0, len(samples) - fn, fn)])
+    quiet = fdb[fdb < overall - 10]
+    if len(quiet) == 0:
+        return wav
+    nf = float(np.clip(float(np.median(quiet)) + 4, -72, -30))
+    nr = 3 if rt60 > RT60_AGGR else 2
+    if st.mujawwad_conf > 0.6: nr = max(1, nr - 1)
+    if st.jalaa:               nr = max(1, nr - 1)   # [I3] JALAA already ran
+    out = _tmp('s6', st)
+    rc, _, _ = _run(['ffmpeg', '-y', '-i', wav,
+                     '-af', f'afftdn=nr={nr}:nf={nf:.0f}:tn=1',
+                     '-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
+                     '-loglevel', 'error', out])
+    if rc or not os.path.exists(out):
+        return wav
+    st.tail_nr = True
+    jalaa_note = ' (JALAA-adjusted)' if st.jalaa else ''
+    _L(st, f'  [S6-tailNR] ✓ nr={nr}{jalaa_note} nf={nf:.0f}dB')
+    return out
+
+
+# ─── Stage 7: Arabic phoneme guards (§35/§52/§143/§152) ──────────────────────
+def _arabic_guards(orig_s, proc_wav, st):
+    """
+    Seven guards verifying Tajweed-critical features survived processing.
+    WARN-only by design — reverb is worse than mild phoneme loss.
+    Results stored in st.guard_pass / st.guard_warn (structured). [I6]
+    [B3] _band_energy() now samples across full file.
+    [B4] G4 Ra-trill scans full audio in overlapping 1s windows.
+    """
+    if not NUMPY_OK or orig_s is None:
+        return proc_wav
+    proc_s = _decode(proc_wav)
+    if proc_s is None:
+        return proc_wav
+    n = min(len(orig_s), len(proc_s))
+    o = orig_s[:n]; p = proc_s[:n]
+
+    def chk(name, cond, detail):
+        entry = f'{name}: {detail}'
+        if cond:
+            st.guard_pass.append(entry); _L(st, f'  [S7-PASS] {entry}')
+        else:
+            st.guard_warn.append(entry); _L(st, f'  [S7-WARN] ⚠ {entry}')
+
+    # G1 Ghunnah 250-300 Hz (§152.3)
+    go = _band_energy(o, 250, 300); gp = _band_energy(p, 250, 300)
+    if go > 1e-15:
+        d = 10 * np.log10(gp / go + 1e-20)
+        chk('G1-Ghunnah', d >= -3.0, f'{d:+.1f}dB {"✓" if d>=-3 else "⚠ nasal murmur lost"}')
+
+    # G2 Ikhfa 250-400 Hz (§52.5)
+    io = _band_energy(o, 250, 400); ip = _band_energy(p, 250, 400)
+    if io > 1e-15:
+        d = 10 * np.log10(ip / io + 1e-20)
+        chk('G2-Ikhfa', d >= -4.0, f'{d:+.1f}dB {"✓" if d>=-4 else "⚠ ikhfa nasalisation lost"}')
+
+    # G3 Qalqalah burst (§52.7, §143 Class 2)
+    sil_n = int(0.020 * SR); bst_n = int(0.030 * SR)
+    total = viol = 0
+    for i in range(0, n - sil_n - bst_n, sil_n):
+        sr_ = float(np.sqrt(np.mean(o[i:i + sil_n] ** 2)) + 1e-10)
+        br_ = float(np.sqrt(np.mean(o[i + sil_n:i + sil_n + bst_n] ** 2)) + 1e-10)
+        if sr_ < 0.005 and br_ > sr_ * 5:
+            total += 1
+            bp = float(np.sqrt(np.mean(p[i + sil_n:i + sil_n + bst_n] ** 2)) + 1e-10)
+            if 20 * np.log10(bp / br_ + 1e-10) < -6.0: viol += 1
+    if total > 0:
+        pct = viol / total * 100
+        chk('G3-Qalqalah', pct <= 20,
+            f'{total} bursts {pct:.0f}% violated {"✓" if pct<=20 else "⚠ echo burst attenuated"}')
+
+    # G4 Ra trill AM 25-35 Hz — FULL AUDIO scan in overlapping 1s windows [B4]
+    win = SR; hop = SR // 2
+    am_ratios = []
+    for pos in range(0, n - win, hop):
+        ef_o = np.abs(np.fft.rfft(np.abs(o[pos:pos + win]), n=win))
+        ef_p = np.abs(np.fft.rfft(np.abs(p[pos:pos + win]), n=win))
+        am_o = float(np.mean(ef_o[25:36])); am_p = float(np.mean(ef_p[25:36]))
+        if am_o > 1e-8:
+            am_ratios.append(am_p / am_o)
+    if am_ratios:
+        r = float(np.median(am_ratios))
+        chk('G4-Ra-trill', r >= 0.70,
+            f'AM ratio={r:.2f} (median over {len(am_ratios)} windows) '
+            f'{"✓" if r>=0.70 else "⚠ ر trill may be smeared"}')
+
+    # G5 Safir 5.5-12 kHz — ص س ز (§152.3)
+    so = _band_energy(o, 5500, 12000); sp = _band_energy(p, 5500, 12000)
+    if so > 1e-15:
+        d = 10 * np.log10(sp / so + 1e-20)
+        chk('G5-Safir', d >= -5.0,
+            f'{d:+.1f}dB {"✓" if d>=-5 else "⚠ ص س ز may be dull"}')
+
+    # G6 Tafasshi 3-8 kHz — ش (§152.3)
+    to = _band_energy(o, 3000, 8000); tp = _band_energy(p, 3000, 8000)
+    if to > 1e-15:
+        d = 10 * np.log10(tp / to + 1e-20)
+        chk('G6-Tafasshi', d >= -4.0,
+            f'{d:+.1f}dB {"✓" if d>=-4 else "⚠ ش may lose spread"}')
+
+    # G7 Izhar silence count (§52.5.1)
+    def _sil_count(s):
+        fn_ = int(0.010 * SR)
+        db = np.array([float(20 * np.log10(np.sqrt(np.mean(s[i:i + fn_] ** 2)) + 1e-10))
+                       for i in range(0, len(s) - fn_, fn_)])
+        med = float(np.median(db)); c = 0; in_s = False; sl = 0
+        for v in db:
+            if v < med - 18: in_s = True; sl += 1
+            else:
+                if in_s and 2 <= sl <= 8: c += 1
+                in_s = False; sl = 0
+        return c
+    sc_o = _sil_count(o); sc_p = _sil_count(p)
+    if sc_o > 0:
+        r = sc_p / sc_o
+        chk('G7-Izhar', r >= 0.70,
+            f'silences {sc_o}→{sc_p} ({r:.0%}) {"✓" if r>=0.70 else "⚠ words may run together"}')
+
+    total_g = len(st.guard_pass) + len(st.guard_warn)
+    if st.guard_warn:
+        _L(st, f'  [S7] {len(st.guard_warn)}/{total_g} warnings — check output for Tajweed artifacts')
+    else:
+        _L(st, f'  [S7] All {total_g} guards passed ✓')
+    return proc_wav
+
+
+# ─── Main ─────────────────────────────────────────────────────────────────────
+def process(input_path, output_path, source_tier='TIER_UNKNOWN',
+            mujawwad_conf=0.0, force_rt60=0.0, verbose=True):
+    """
+    الصفاء v3 — main entry point.
+    Returns SafaaState with full diagnostics.
+    All temp files are tracked and cleaned up on exit. [I8]
+    """
+    st = SafaaState(input_path=input_path, source_tier=source_tier,
+                    mujawwad_conf=mujawwad_conf)
+    _L(st, f'\n{"═"*60}')
+    _L(st, f'  الصفاء {__version__} — إزالة الصدى والريفيرب')
+    _L(st, f'  Input   : {Path(input_path).name}')
+    _L(st, f'  Tier    : {source_tier}   Mujawwad: {mujawwad_conf:.2f}')
+    _L(st, f'{"═"*60}')
+
+    s_orig = _decode(input_path)
+    if s_orig is None:
+        _L(st, '  ERROR: decode failed'); return st
+
+    try:
+        cur = input_path
+
+        # S1: RT60 + DRR
+        rt60 = force_rt60 if force_rt60 > 0 else _rt60(s_orig)
+        st.rt60_initial = rt60; st.drr_before = _drr(s_orig)
+        _L(st, f'  [S1] RT60={rt60:.2f}s  DRR={st.drr_before:.1f}dB')
+
+        if rt60 < RT60_MIN:
+            _L(st, f'  [S1] RT60 < {RT60_MIN}s — no processing needed')
+            _enc_stereo(input_path, output_path); return st
+
+        # S2 Sub-band LF EQ
+        cur = _lf_eq(cur, s_orig, rt60, st)
+        # S3 WPE
+        cur = _wpe(cur, rt60, st)
+        # S4 DF3 (parallel)
+        _s4 = _decode(cur); s4 = _s4 if _s4 is not None else s_orig
+        cur = _df3(cur, s4, rt60, st)
+        # S5 JALAA (DRR-weighted, corrected late window)
+        _s5 = _decode(cur); s5 = _s5 if _s5 is not None else s_orig
+        cur = _jalaa(cur, s5, rt60, st.drr_before, st)
+        # S6 Tail NR (JALAA-aware)
+        _s6 = _decode(cur); s6 = _s6 if _s6 is not None else s_orig
+        cur = _tailnr(cur, s6, rt60, st)
+        # S7 Arabic guards
+        cur = _arabic_guards(s_orig, cur, st)
+
+        # Final stereo encode [I2]
+        rc, _, err = _run(['ffmpeg', '-y', '-i', cur,
+                           '-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '2',
+                           '-loglevel', 'error', output_path])
+        if rc:
+            _L(st, f'  ERROR: final encode: {err[:80]}'); return st
+
+        sf_ = _decode(output_path)
+        if sf_ is not None: st.drr_after = _drr(sf_)
+
+        _L(st, f'\n{"═"*60}')
+        _L(st, f'  الصفاء {__version__} ✓')
+        _L(st, f'  RT60  : {st.rt60_initial:.2f}s')
+        _L(st, f'  DRR   : {st.drr_before:.1f} → {st.drr_after:.1f} dB  '
+              f'(Δ{st.drr_after - st.drr_before:+.1f})')
+        _L(st, f'  LF={st.lf_eq} WPE={st.wpe} DF3={st.df3} JALAA={st.jalaa} tailNR={st.tail_nr}')
+        _L(st, f'  Reverts:{st.guard_reverts}  Warns:{len(st.guard_warn)}/{len(st.guard_pass)+len(st.guard_warn)}')
+        _L(st, f'{"═"*60}\n')
+        return st
+
+    finally:
+        _cleanup_all(st)   # [I8] always runs
+
+
+# ─── CLI ──────────────────────────────────────────────────────────────────────
+if __name__ == '__main__':
+    import argparse, json
+    ap = argparse.ArgumentParser(description=f'الصفاء {__version__} — Dereverberation Engine')
+    # S156-B1: use -i/-o flags to match server calling convention
+    # server: python3 engine_safaa_v3_fixed.py -i input -o output --iterations 3 --ref ref
+    ap.add_argument('-i', '--input',      required=True,  dest='input')
+    ap.add_argument('-o', '--output',     required=True,  dest='output')
+    ap.add_argument('--iterations',       type=int,   default=3)   # accepted, ignored (pipeline is fixed)
+    ap.add_argument('--ref',              action='append', default=[], metavar='REF')  # accepted, ignored
+    ap.add_argument('--tier',             default='TIER_UNKNOWN')
+    ap.add_argument('--mujawwad',         type=float, default=0.0)
+    ap.add_argument('--rt60',             type=float, default=0.0, help='Force RT60 (0=auto)')
+    a = ap.parse_args()
+    st = process(a.input, a.output,
+                 source_tier=a.tier, mujawwad_conf=a.mujawwad, force_rt60=a.rt60)
+    print('\n[REPORT]')
+    print(json.dumps({
+        'version':      __version__,
+        'rt60':         st.rt60_initial,
+        'drr_before':   round(st.drr_before, 2),
+        'drr_after':    round(st.drr_after,  2),
+        'drr_gain':     round(st.drr_after - st.drr_before, 2),
+        'stages': {
+            'lf_eq':    st.lf_eq,
+            'wpe':      st.wpe,
+            'df3':      st.df3,
+            'jalaa':    st.jalaa,
+            'tail_nr':  st.tail_nr,
+        },
+        'guard_reverts': st.guard_reverts,
+        'guard_pass':    st.guard_pass,
+        'guard_warn':    st.guard_warn,
+    }, indent=2, ensure_ascii=False))

engine_tajalli_v1.py

@@ -1,947 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""
-╔══════════════════════════════════════════════════════════════════════════════╗
-║         التجلي  —  محسن التلاوات  Unified Processing Engine  v1.0          ║
-╠══════════════════════════════════════════════════════════════════════════════╣
-║                                                                              ║
-║  The name: التجلي (At-Tajalli) = The Manifestation / The Radiance.          ║
-║  In Islamic tradition, tajalli refers to the divine light becoming           ║
-║  perceptible — apt for an engine that reveals the true beauty of             ║
-║  Quranic recitation hidden beneath noise, compression, and time.             ║
-║                                                                              ║
-║  Architecture:                                                               ║
-║                                                                              ║
-║   [T-0] Unified Tier Classifier                                              ║
-║      │                                                                       ║
-║      ├─ PRISTINE / PRISTINE_NOISY / COMPRESSED ──► [E2] الإتقان v2          ║
-║      │                                              Fingerprint perfection   ║
-║      │                                                                       ║
-║      └─ DAMAGED / CRITICAL ────────────────────────► [E1] الاسترداد v12     ║
-║                                                       Damage recovery        ║
-║                                                       (نقاء pre-pass for     ║
-║                                                        MOSQUE/CASSETTE)      ║
-║                                                                              ║
-║   Both paths → [B4] البيان v2  Voice quality diagnosis + correction         ║
-║             → [B5] النور  v5   Harmonic gate + enrichment                   ║
-║             → [T-6] Sidrah     Score synthesis                               ║
-║             → [T-7] Final encode  TPDF + SHA-256 provenance                 ║
-║                                                                              ║
-║  Engine routing table:                                                       ║
-║   TIER_PRISTINE          → الإتقان  (fingerprint match, صدي, LUFS)          ║
-║   TIER_PRISTINE_NOISY    → الإتقان  (+ DF3 if SNR 10-18dB & ≥256kbps)      ║
-║   TIER_COMPRESSED        → الإتقان  (codec-aware EQ, conservative NR)       ║
-║   TIER_DAMAGED           → الاسترداد (TYPE_A/B/C, wow/flutter, BWE)         ║
-║   TIER_CRITICAL          → الاسترداد (maximum recovery, low ceiling)        ║
-║                                                                              ║
-║  Specialist modules (loaded on-demand):                                      ║
-║   true_engine_itiqan_v2_fixed.py  — الإتقان v2                              ║
-║   engine_isteidad_v12.py          — الاسترداد v12                           ║
-║   naqaa_v1_tested.py              — النقاء v1  (mosque/cassette pre-pass)   ║
-║   bayan_ve_v2fix.py               — البيان v2  (voice quality)              ║
-║   noor_v5.py                      — النور  v5  (harmonic enrichment)        ║
-║   ihyaa_ve.py                     — الإحياء    (already wired in isteidad)  ║
-║                                                                              ║
-║  v6 baseline improvement summary:                                            ║
-║   • Tier awareness:    none → 5 routing tiers                               ║
-║   • NR:               spectral subtraction → Wiener + DF3 (SNR-gated)       ║
-║   • Tajweed guards:   0 → 6 (Qalqalah, Ghunnah, Emphatic, Alif, Hams, Sib) ║
-║   • Recovery paths:   1 (declip) → 7 (TYPE_A/B/C + R-1/R-2/R-3 + mosque)   ║
-║   • BWE:              none → LR4 + PCHIP F0-tracked harmonic synthesis      ║
-║   • Scoring:          RMS distance → Sidrah (maqam + cadence + TRSB)        ║
-║   • Provenance:       none → SHA-256 input/output hash                      ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-
-Usage (CLI):
-    python engine_tajalli_v1.py -i input.mp3 -o output.wav --ref ref_1425.mp3
-
-Usage (API):
-    from engine_tajalli_v1 import process
-    result = process(input_path, output_path, ref_files=[ref_mp3])
-"""
-
-from __future__ import annotations
-
-import argparse
-import hashlib
-import json
-import os
-import subprocess
-import sys
-import tempfile
-import time
-import shutil
-import warnings
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Dict, List, Optional, Tuple
-
-warnings.filterwarnings('ignore')
-
-# ── Version ──────────────────────────────────────────────────────────────────
-TAJALLI_VERSION = 'v1.0.0-التجلي'
-TARGET_LUFS     = -6.29
-TARGET_CREST    = 10.25
-TARGET_LRA      = 4.19
-
-# ── Tier constants ────────────────────────────────────────────────────────────
-TIER_PRISTINE          = 'TIER_PRISTINE'
-TIER_PRISTINE_NOISY    = 'TIER_PRISTINE_NOISY'
-TIER_COMPRESSED        = 'TIER_COMPRESSED'
-TIER_DAMAGED           = 'TIER_DAMAGED'
-TIER_CRITICAL          = 'TIER_CRITICAL'
-
-ITIQAN_TIERS  = {TIER_PRISTINE, TIER_PRISTINE_NOISY, TIER_COMPRESSED}
-ISTEIDAD_TIERS = {TIER_DAMAGED, TIER_CRITICAL}
-
-# ── Module discovery ──────────────────────────────────────────────────────────
-_HERE = Path(__file__).parent
-
-def _find_module(name: str, candidates: List[str]) -> Optional[Path]:
-    """Find a module file by trying candidate paths in order."""
-    for c in candidates:
-        p = Path(c)
-        if p.exists():
-            return p
-        p2 = _HERE / c
-        if p2.exists():
-            return p2
-    return None
-
-_ITIQAN_PATH  = _find_module('itiqan',  [
-    'true_engine_itiqan_v2_fixed.py',
-    'true_engine_itiqan_v2.py',
-    'true_engine_itiqan_v2_patched.py',
-])
-_ISTEIDAD_PATH = _find_module('isteidad', [
-    'engine_isteidad_v12.py',
-    'engine_isteidad_v11.py',
-])
-_NAQAA_PATH   = _find_module('naqaa',   ['naqaa_v1_tested.py', 'naqaa_v1.py'])
-_BAYAN_PATH   = _find_module('bayan',   ['bayan_ve_v2fix.py', 'bayan_ve.py'])
-_NOOR_PATH    = _find_module('noor',    ['noor_v5.py', 'noor_v4.py'])
-
-# ── Numpy / scipy guard ───────────────────────────────────────────────────────
-try:
-    import numpy as np
-    NUMPY_OK = True
-except ImportError:
-    NUMPY_OK = False
-    np = None  # type: ignore
-
-# ══════════════════════════════════════════════════════════════════════════════
-#  RESULT PACKET
-# ══════════════════════════════════════════════════════════════════════════════
-@dataclass
-class TajalliResult:
-    """Unified output packet from التجلي pipeline."""
-    # Routing
-    tier:            str   = ''
-    engine_used:     str   = ''
-    naqaa_pre_pass:  bool  = False
-
-    # Scores
-    score_before:    float = 0.0
-    score_after:     float = 0.0
-    score_ceiling:   float = 100.0
-
-    # Loudness
-    lufs_in:         float = 0.0
-    lufs_out:        float = 0.0
-    lra_in:          float = 0.0
-    lra_out:         float = 0.0
-    crest_in:        float = 0.0
-    crest_out:       float = 0.0
-
-    # Post-processing
-    bayan_applied:   bool  = False
-    noor_applied:    bool  = False
-
-    # Provenance
-    input_sha256:    str   = ''
-    output_sha256:   str   = ''
-    engine_version:  str   = TAJALLI_VERSION
-    elapsed_s:       float = 0.0
-
-    # Raw sub-engine result (for diagnostics)
-    sub_result:      dict  = field(default_factory=dict)
-    log:             List[str] = field(default_factory=list)
-
-
-# ══════════════════════════════════════════════════════════════════════════════
-#  UTILITY
-# ══════════════════════════════════════════════════════════════════════════════
-def _sha256(path: str) -> str:
-    h = hashlib.sha256()
-    try:
-        with open(path, 'rb') as f:
-            for chunk in iter(lambda: f.read(65536), b''):
-                h.update(chunk)
-        return h.hexdigest()[:16]
-    except Exception:
-        return ''
-
-
-def _ffprobe(path: str) -> Tuple[float, int]:
-    """Returns (duration_s, bitrate_kbps)."""
-    try:
-        r = subprocess.run(
-            ['ffprobe', '-v', 'quiet', '-show_entries', 'format=duration,bit_rate',
-             '-of', 'csv=p=0', path],
-            capture_output=True, text=True, timeout=15
-        )
-        vals = r.stdout.strip().split(',')
-        dur = float(vals[0]) if vals else 0.0
-        br  = int(vals[1]) // 1000 if len(vals) > 1 else 0
-        return dur, br
-    except Exception:
-        return 0.0, 0
-
-
-def _decode_to_wav(input_path: str, tmp_dir: str) -> Optional[str]:
-    """Decode any audio to pcm_s16le 48kHz mono WAV for analysis."""
-    out = os.path.join(tmp_dir, 'tajalli_analysis.wav')
-    r = subprocess.run(
-        ['ffmpeg', '-y', '-i', input_path,
-         '-acodec', 'pcm_s16le', '-ar', '48000', '-ac', '1', out],
-        capture_output=True, timeout=120
-    )
-    return out if r.returncode == 0 and os.path.exists(out) else None
-
-
-def _load_wav_samples(wav_path: str):
-    """Load WAV as float32 numpy array. Returns None if numpy unavailable."""
-    if not NUMPY_OK:
-        return None
-    try:
-        import wave as _wave
-        with _wave.open(wav_path, 'rb') as wf:
-            raw = wf.readframes(wf.getnframes())
-        return np.frombuffer(raw, dtype=np.int16).astype(np.float32) / 32768.0
-    except Exception:
-        return None
-
-
-def _measure_lufs(wav_path: str) -> Tuple[float, float]:
-    """Measure integrated LUFS and LRA via ffmpeg ebur128."""
-    try:
-        r = subprocess.run(
-            ['ffmpeg', '-i', wav_path, '-af', 'ebur128=peak=true', '-f', 'null', '-'],
-            capture_output=True, text=True, timeout=60
-        )
-        txt = r.stderr
-        lufs = lra = 0.0
-        for line in txt.splitlines():
-            if 'I:' in line and 'LUFS' in line:
-                try:
-                    lufs = float(line.split('I:')[1].split('LUFS')[0].strip())
-                except Exception:
-                    pass
-            if 'LRA:' in line and 'LU' in line:
-                try:
-                    lra = float(line.split('LRA:')[1].split('LU')[0].strip())
-                except Exception:
-                    pass
-        return lufs, lra
-    except Exception:
-        return 0.0, 0.0
-
-
-# ══════════════════════════════════════════════════════════════════════════════
-#  TIER CLASSIFIER  (extracted + calibrated from الإتقان v2)
-# ══════════════════════════════════════════════════════════════════════════════
-def _classify_background_noise(samples, sr: int = 48000):
-    """
-    Returns (noise_floor_db, snr_proxy_db, is_noisy).
-
-    Three-guard clean detection — calibrated on 7 real recordings:
-      Guard A: True phrase silence  (yt5s: SFM≈0, p5 < -36dBFS)
-      Guard B: Room character       (الذاريات: bg_slope < -1.6, snr > 9dB)
-      Guard C: SNR threshold        (< 16dB = genuinely noisy)
-
-    All three guards must fail for is_noisy=True.
-    Known results:
-      الأحزاب  (noisy):    slope=-1.22, snr=12.6 → NOISY  ✓
-      الأعراف  (noisy):    slope=-2.36, snr=8.8  → NOISY  ✓ (snr<9 override)
-      الذاريات (room air): slope=-1.90, snr=14.8 → CLEAN  ✓
-      يا أيها  (clean):    slope=-2.09, snr=9.4  → CLEAN  ✓
-      yt5s     (silence):  SFM=0.0005,  p5=-39.0 → CLEAN  ✓
-    """
-    if not NUMPY_OK or len(samples) < sr:
-        return -60.0, 25.0, False
-
-    SR = sr
-    frame_n = int(0.02 * SR)
-    frames_db = [
-        float(20.0 * np.log10(float(np.sqrt(np.mean(samples[i:i+frame_n]**2))) + 1e-10))
-        for i in range(0, len(samples) - frame_n, frame_n)
-    ]
-    if len(frames_db) < 20:
-        return -60.0, 25.0, False
-
-    arr = np.array(frames_db)
-    p5  = float(np.percentile(arr, 5))
-    p10 = float(np.percentile(arr, 10))
-    p20 = float(np.percentile(arr, 20))
-    p75 = float(np.percentile(arr, 75))
-    snr_proxy = p75 - p10
-
-    noise_idxs = [i for i, r in enumerate(frames_db) if p5 < r < p20][:80]
-    if not noise_idxs:
-        return p10, snr_proxy, snr_proxy < 18.0
-
-    bg = np.concatenate([samples[i*frame_n:(i+1)*frame_n] for i in noise_idxs])
-    bg_rms = float(20.0 * np.log10(np.sqrt(np.mean(bg**2)) + 1e-10))
-
-    # Has_noise: LF or mid band energy in background
-    N = min(len(bg), 4096)
-    bg_spec  = np.abs(np.fft.rfft(bg[:N], n=N))**2
-    bg_freqs = np.fft.rfftfreq(N, 1.0/SR)
-    lf_mask  = (bg_freqs >= 100) & (bg_freqs < 500)
-    mid_mask = (bg_freqs >= 500) & (bg_freqs < 2000)
-    has_noise = (
-        (lf_mask.any()  and float(np.mean(bg_spec[lf_mask]))  > 1e-8) or
-        (mid_mask.any() and float(np.mean(bg_spec[mid_mask])) > 1e-8)
-    )
-
-    # Full-resolution spectral analysis for guards
-    N_full   = min(len(bg), 8192)
-    bg_full  = np.abs(np.fft.rfft(bg[:N_full], n=N_full))**2 + 1e-10
-    bg_fq    = np.fft.rfftfreq(N_full, 1.0/SR)
-
-    # Guard A: near-digital silence (phrase gaps, not noise floor)
-    sfm = float(np.exp(np.mean(np.log(bg_full))) / np.mean(bg_full))
-    p5_depth = float(np.percentile(arr, 5))
-    is_true_silence = sfm < 0.003 and p5_depth < -36.0
-
-    # Guard B: tonal/room-character background (صدي التمييز, acoustic air)
-    slope_band = (bg_fq >= 200) & (bg_fq < 4000)
-    if slope_band.sum() > 4:
-        _lf = np.log10(bg_fq[slope_band] + 1)
-        _lp = np.log10(bg_full[slope_band])
-        bg_slope = float(np.polyfit(_lf, _lp, 1)[0])
-    else:
-        bg_slope = -2.0
-    is_room_character = bg_slope < -1.6 and snr_proxy > 9.0
-
-    is_noisy = (
-        snr_proxy < 16.0
-        and has_noise
-        and bg_rms > -40.0
-        and not is_true_silence
-        and not is_room_character
-    )
-    return bg_rms, snr_proxy, is_noisy
-
-
-def classify_tier(wav_path: str, samples, bitrate_kbps: int,
-                  duration_s: float) -> Tuple[str, dict]:
-    """
-    Unified tier classifier for التجلي.
-
-    Returns (tier_string, info_dict).
-
-    Routing:
-      bitrate ≥ 192 kbps + good quality  → TIER_PRISTINE / TIER_PRISTINE_NOISY
-      bitrate  64–191 kbps               → TIER_COMPRESSED
-      bitrate < 64 kbps OR THD/damage    → TIER_DAMAGED
-      unrecoverable                       → TIER_CRITICAL
-    """
-    info = {
-        'bitrate_kbps': bitrate_kbps,
-        'duration_s':   duration_s,
-        'noise_floor':  -60.0,
-        'snr_proxy':    25.0,
-        'is_noisy':     False,
-        'lufs':         0.0,
-        'lra':          0.0,
-    }
-
-    # Measure LUFS/LRA
-    try:
-        lufs, lra = _measure_lufs(wav_path)
-        info['lufs'] = lufs
-        info['lra']  = lra
-    except Exception:
-        pass
-
-    # Measure noise profile
-    if NUMPY_OK and samples is not None:
-        noise_floor, snr_proxy, is_noisy = _classify_background_noise(samples)
-        info['noise_floor'] = noise_floor
-        info['snr_proxy']   = snr_proxy
-        info['is_noisy']    = is_noisy
-    else:
-        is_noisy = False
-
-    # TIER_CRITICAL: completely unprocessable
-    # Heuristic: LUFS > -3 dBFS (digital overload) or duration < 5s
-    if duration_s < 5.0 or (info['lufs'] > -3.0 and info['lufs'] != 0.0):
-        return TIER_CRITICAL, info
-
-    # TIER_DAMAGED: low bitrate or bitrate-class indicates severe compression
-    # الاسترداد handles 8–63 kbps (cassette, telephone, corrupted internet)
-    if bitrate_kbps > 0 and bitrate_kbps < 64:
-        return TIER_DAMAGED, info
-
-    # TIER_COMPRESSED: 64–191 kbps — الإتقان handles with reduced EQ confidence
-    if 64 <= bitrate_kbps < 192:
-        tier = TIER_COMPRESSED
-        # Even within COMPRESSED, very low bitrate (64-95) with severe damage
-        # should route to الاسترداد. Proxy: LRA < 1.0 + lufs deviation > 12 dB
-        if bitrate_kbps < 96 and info['lra'] < 1.0 and abs(info['lufs'] - TARGET_LUFS) > 12:
-            return TIER_DAMAGED, info
-        return tier, info
-
-    # ≥ 192 kbps: PRISTINE family
-    if is_noisy:
-        return TIER_PRISTINE_NOISY, info
-    return TIER_PRISTINE, info
-
-
-# ══════════════════════════════════════════════════════════════════════════════
-#  MODULE LOADERS  (lazy import — only load what the routing requires)
-# ══════════════════════════════════════════════════════════════════════════════
-def _load_itiqan():
-    """Dynamically import الإتقان v2. Returns module or None."""
-    if _ITIQAN_PATH is None:
-        return None
-    abs_path = str(_ITIQAN_PATH.resolve())
-    mod_name = f'_tajalli_itiqan_{id(abs_path)}'
-    try:
-        import importlib.util, sys as _sys
-        _sys.modules.pop(mod_name, None)
-        spec = importlib.util.spec_from_file_location(mod_name, abs_path)
-        mod  = importlib.util.module_from_spec(spec)
-        _sys.modules[mod_name] = mod
-        spec.loader.exec_module(mod)
-        return mod
-    except Exception as e:
-        print(f'  [التجلي] الإتقان load error: {e}')
-        return None
-
-
-def _load_isteidad():
-    """Dynamically import الاسترداد v12. Returns module or None."""
-    if _ISTEIDAD_PATH is None:
-        return None
-    abs_path = str(_ISTEIDAD_PATH.resolve())
-    mod_name = f'_tajalli_isteidad_{id(abs_path)}'
-    try:
-        import importlib.util, sys as _sys
-        _sys.modules.pop(mod_name, None)
-        spec = importlib.util.spec_from_file_location(mod_name, abs_path)
-        mod  = importlib.util.module_from_spec(spec)
-        _sys.modules[mod_name] = mod
-        spec.loader.exec_module(mod)
-        return mod
-    except Exception as e:
-        print(f'  [التجلي] الاسترداد load error: {e}')
-        return None
-
-
-def _load_naqaa():
-    if _NAQAA_PATH is None:
-        return None
-    try:
-        import importlib.util
-        spec = importlib.util.spec_from_file_location(f'_tajalli_naqaa_{id(abs_path)}', str(_NAQAA_PATH.resolve()))
-        mod  = importlib.util.module_from_spec(spec)
-        spec.loader.exec_module(mod)
-        return mod
-    except Exception:
-        return None
-
-
-def _load_bayan():
-    if _BAYAN_PATH is None:
-        return None
-    try:
-        import importlib.util
-        spec = importlib.util.spec_from_file_location('_bayan', str(_BAYAN_PATH.resolve()))
-        mod  = importlib.util.module_from_spec(spec)
-        spec.loader.exec_module(mod)
-        return mod
-    except Exception:
-        return None
-
-
-def _load_noor():
-    if _NOOR_PATH is None:
-        return None
-    try:
-        import importlib.util
-        spec = importlib.util.spec_from_file_location('_noor', str(_NOOR_PATH))
-        mod  = importlib.util.module_from_spec(spec)
-        spec.loader.exec_module(mod)
-        return mod
-    except Exception:
-        return None
-
-
-# ══════════════════════════════════════════════════════════════════════════════
-#  POST-PROCESSING  (البيان + النور — applied after both paths)
-# ══════════════════════════════════════════════════════════════════════════════
-def _run_bayan(wav_path: str, tier: str, codec_cutoff: float,
-               ref_third_oct: dict, log) -> str:
-    """
-    Apply البيان v2 voice quality correction.
-    Returns output wav path (same as input on failure/skip).
-    """
-    bayan = _load_bayan()
-    if bayan is None:
-        log('  [البيان] module not found — skipping')
-        return wav_path
-
-    # Build minimal state and ref objects compatible with apply_bayan_to_engine
-    class _State:
-        pass
-    class _Ref:
-        pass
-
-    state = _State()
-    state.source_tier  = tier
-    state.skip_s       = 15.0
-    state.dur_s        = 45.0
-    state.codec_cutoff = codec_cutoff
-
-    ref = _Ref()
-    ref.third_oct = ref_third_oct
-
-    try:
-        out_wav, bayan_result = bayan.apply_bayan_to_engine(
-            wav_path, state, ref, log_fn=log
-        )
-        if bayan_result.status == 'OK' and out_wav != wav_path:
-            log(f'  [البيان] ✓ VQS {bayan_result.vqs_before:.1f}→{bayan_result.vqs_after:.1f}')
-            return out_wav
-        log(f'  [البيان] {bayan_result.status}: {bayan_result.reason}')
-        return wav_path
-    except Exception as e:
-        log(f'  [البيان] failed: {e}')
-        return wav_path
-
-
-def _run_noor(wav_path: str, output_path: str, ref_path: Optional[str],
-              log) -> str:
-    """
-    Apply النور v5 harmonic gate + enrichment.
-    Returns output path (same as wav_path on failure).
-    """
-    noor = _load_noor()
-    if noor is None:
-        log('  [النور] module not found — skipping')
-        return wav_path
-
-    tmp_out = wav_path.replace('.wav', '_noor.wav')
-    try:
-        noor.run(wav_path, tmp_out, ref=ref_path)
-        if os.path.exists(tmp_out):
-            log('  [النور] ✓ harmonic enrichment applied')
-            return tmp_out
-        return wav_path
-    except Exception as e:
-        log(f'  [النور] failed: {e}')
-        return wav_path
-
-
-def _build_ref_third_oct(ref_files: List[str]) -> dict:
-    """
-    Build reference third-octave spectrum from ref files for البيان.
-    Returns empty dict if bayan unavailable.
-    """
-    bayan = _load_bayan()
-    if bayan is None or not ref_files:
-        return {}
-    try:
-        # البيان exposes _compute_third_oct internally; we use its band helper
-        spectra = []
-        for rf in ref_files:
-            if not os.path.exists(rf):
-                continue
-            tmp = tempfile.mktemp(suffix='.wav')
-            subprocess.run(
-                ['ffmpeg', '-y', '-i', rf, '-acodec', 'pcm_s16le',
-                 '-ar', '48000', '-ac', '1', tmp],
-                capture_output=True, timeout=60
-            )
-            if not os.path.exists(tmp):
-                continue
-            try:
-                audio = bayan._load_mono(tmp, skip_s=10, dur_s=40)
-                if len(audio) > 48000 * 5:
-                    spectra.append(bayan.bands(audio))
-            except Exception:
-                pass
-            finally:
-                if os.path.exists(tmp):
-                    os.unlink(tmp)
-
-        if not spectra:
-            return {}
-        # Average across reference files
-        keys = set()
-        for s in spectra:
-            keys.update(s.keys())
-        averaged = {}
-        for k in keys:
-            vals = [s[k] for s in spectra if k in s]
-            averaged[k] = float(sum(vals) / len(vals))
-        return averaged
-    except Exception:
-        return {}
-
-
-# ══════════════════════════════════════════════════════════════════════════════
-#  MAIN PROCESS FUNCTION
-# ══════════════════════════════════════════════════════════════════════════════
-def process(
-    input_path:  str,
-    output_path: str,
-    ref_files:   Optional[List[str]] = None,
-    iterations:  int   = 3,
-    target_score: float = 96.0,
-    force_tier:  Optional[str] = None,
-    aggressive:  bool  = False,
-    run_bayan:   bool  = True,
-    run_noor:    bool  = True,
-    log_fn       = None,
-) -> TajalliResult:
-    """
-    التجلي unified processing pipeline.
-
-    Args:
-        input_path:   Source audio (any format ffmpeg can read)
-        output_path:  Output path (.wav or .mp3)
-        ref_files:    List of 1425H reference MP3s for fingerprint targeting
-        iterations:   Processing iterations (passed to sub-engines)
-        target_score: Target quality score (0–100)
-        force_tier:   Override automatic tier detection
-        aggressive:   Pass aggressive flag to sub-engines
-        run_bayan:    Apply البيان v2 post-processing
-        run_noor:     Apply النور v5 harmonic enrichment
-        log_fn:       Logging function (default: print)
-
-    Returns:
-        TajalliResult with full processing report
-    """
-    log   = log_fn or print
-    res   = TajalliResult()
-    t0    = time.time()
-    _LOG: List[str] = []
-
-    def L(msg: str):
-        _LOG.append(msg)
-        log(msg)
-
-    ref_files = [r for r in (ref_files or []) if os.path.exists(r)]
-
-    L(f'\n╔{"═"*62}╗')
-    L(f'║  التجلي {TAJALLI_VERSION} — محسن التلاوات{"":26}║')
-    L(f'╚{"═"*62}╝')
-    L(f'  Input  : {os.path.basename(input_path)}')
-    L(f'  Output : {os.path.basename(output_path)}')
-    L(f'  Refs   : {len(ref_files)} file(s)')
-
-    if not os.path.exists(input_path):
-        L(f'  ERROR: Input not found'); res.log = _LOG; return res
-
-    # ── Provenance: hash input ────────────────────────────────────────────────
-    res.input_sha256 = _sha256(input_path)
-    L(f'  SHA256 : {res.input_sha256}')
-
-    tmp_dir = tempfile.mkdtemp(prefix='tajalli_')
-    try:
-        # ── T-0: Analysis + Classification ───────────────────────────────────
-        L('\n── T-0: Analysis ─────────────────────────────────────────────')
-        wav_analysis = _decode_to_wav(input_path, tmp_dir)
-        samples      = _load_wav_samples(wav_analysis) if wav_analysis else None
-        duration_s, bitrate_kbps = _ffprobe(input_path)
-        lufs_in, lra_in = _measure_lufs(wav_analysis or input_path)
-
-        res.lufs_in  = lufs_in
-        res.lra_in   = lra_in
-
-        if force_tier:
-            tier, tier_info = force_tier, {'bitrate_kbps': bitrate_kbps,
-                                           'duration_s': duration_s}
-            L(f'  [T-0] tier forced → {tier}')
-        else:
-            tier, tier_info = classify_tier(
-                wav_analysis or input_path, samples,
-                bitrate_kbps, duration_s
-            )
-
-        res.tier = tier
-        L(f'  [T-0] Tier     : {tier}')
-        L(f'  [T-0] Bitrate  : {bitrate_kbps} kbps  Duration: {duration_s:.1f}s')
-        L(f'  [T-0] LUFS     : {lufs_in:.2f}  LRA: {lra_in:.2f}')
-        L(f'  [T-0] Noise    : {tier_info.get("noise_floor", -60):.1f} dBFS  '
-          f'SNR: {tier_info.get("snr_proxy", 25):.1f} dB')
-
-        # Build reference third-octave once for البيان
-        ref_third_oct = _build_ref_third_oct(ref_files) if run_bayan else {}
-        codec_cutoff  = float(tier_info.get('codec_cutoff', 20000))
-
-        # ── Routing ───────────────────────────────────────────────────────────
-        current_path = input_path
-
-        if tier in ITIQAN_TIERS:
-            # ──────────────────────────────────────────────────────────────────
-            # PATH A: الإتقان v2
-            # Good / near-good recordings: fingerprint perfection
-            # ──────────────────────────────────────────────────────────────────
-            L(f'\n── E2: الإتقان ─────────────────────────────────────────────')
-            itiqan = _load_itiqan()
-            if itiqan is None:
-                L('  [E2] الإتقان module not found — check file path')
-                L(f'       Expected: {_ITIQAN_PATH or "true_engine_itiqan_v2_fixed.py"}')
-                res.log = _LOG; return res
-
-            # Set REF_FILES on the module if it exposes it
-            if ref_files and hasattr(itiqan, 'REF_FILES'):
-                itiqan.REF_FILES = ref_files
-
-            try:
-                sub = itiqan.enhance(
-                    input_path   = current_path,
-                    output_path  = os.path.join(tmp_dir, 'itiqan_out.wav'),
-                    iterations   = iterations,
-                    target_score = target_score,
-                    aggressive   = aggressive,
-                )
-                itiqan_out = os.path.join(tmp_dir, 'itiqan_out.wav')
-                if os.path.exists(itiqan_out):
-                    current_path = itiqan_out
-                    res.engine_used  = f'الإتقان ({_ITIQAN_PATH.name})'
-                    res.score_before = float(sub.get('score_before', 0))
-                    res.score_after  = float(sub.get('score', 0))
-                    res.score_ceiling = float(sub.get('ceiling', 100))
-                    res.lufs_out     = float(sub.get('lufs', 0))
-                    res.lra_out      = float(sub.get('lra', 0))
-                    res.crest_out    = float(sub.get('crest', 0))
-                    res.sub_result   = sub
-                    L(f'  [E2] Score: {res.score_before:.1f}→{res.score_after:.1f}  '
-                      f'LUFS={res.lufs_out:.2f}  Crest={res.crest_out:.2f}')
-                else:
-                    L('  [E2] output file missing after enhance()')
-            except Exception as e:
-                L(f'  [E2] الإتقان failed: {e}')
-                import traceback; L(traceback.format_exc())
-
-        else:
-            # ──────────────────────────────────────────────────────────────────
-            # PATH B: الاسترداد v12
-            # Damaged / critical: full recovery pipeline
-            # ──────────────────────────────────────────────────────────────────
-
-            # Pre-pass: النقاء for MOSQUE / CASSETTE profiles
-            # النقاء auto-detects profile; run it first for DAMAGED files
-            # as it handles comb filtering, azimuth, and derev before NR.
-            naqaa = _load_naqaa()
-            if naqaa is not None:
-                L(f'\n── E0: النقاء pre-pass ────────────────────────────────────')
-                try:
-                    naqaa_out = os.path.join(tmp_dir, 'naqaa_out.wav')
-                    naqaa_ref = ref_files[0] if ref_files else None
-                    naqaa_result = naqaa.restore(
-                        input_path   = current_path,
-                        output_path  = naqaa_out,
-                        ref_path     = naqaa_ref,
-                        force_profile= None,  # auto-detect MOSQUE/CODEC/CASSETTE
-                        output_br_k  = 320,
-                        log_fn       = L,
-                    )
-                    profile = getattr(getattr(naqaa_result, 'triage', None),
-                                      'profile', 'UNKNOWN')
-                    if profile == 'CLEAN':
-                        # النقاء decided file is already clean — skip pre-pass
-                        L(f'  [E0] profile=CLEAN — النقاء pre-pass skipped')
-                    elif os.path.exists(naqaa_out):
-                        current_path    = naqaa_out
-                        res.naqaa_pre_pass = True
-                        L(f'  [E0] النقاء ✓ profile={profile}  '
-                          f'score {naqaa_result.score_before:.1f}→{naqaa_result.score_after:.1f}')
-                except Exception as e:
-                    L(f'  [E0] النقاء failed: {e} — continuing to الاسترداد')
-            else:
-                L('  [E0] النقاء module not found — skipping pre-pass')
-
-            L(f'\n── E1: الاسترداد ───────────────────────────────────────────')
-            isteidad = _load_isteidad()
-            if isteidad is None:
-                L('  [E1] الاسترداد module not found')
-                L(f'       Expected: {_ISTEIDAD_PATH or "engine_isteidad_v12.py"}')
-                res.log = _LOG; return res
-
-            # Set ref files if module exposes REF_FILES
-            if ref_files and hasattr(isteidad, 'REF_FILES'):
-                isteidad.REF_FILES = ref_files
-
-            try:
-                isteidad_out = os.path.join(tmp_dir, 'isteidad_out.wav')
-                sub = isteidad.enhance(
-                    input_path   = current_path,
-                    output_path  = isteidad_out,
-                    iterations   = iterations,
-                    target_score = target_score,
-                    force_tier   = tier,
-                )
-                if os.path.exists(isteidad_out):
-                    current_path     = isteidad_out
-                    res.engine_used  = f'الاسترداد ({_ISTEIDAD_PATH.name})'
-                    res.score_before = float(sub.get('score_before', 0))
-                    res.score_after  = float(sub.get('score', 0))
-                    res.score_ceiling = float(sub.get('ceiling', 100))
-                    res.lufs_out     = float(sub.get('lufs', 0))
-                    res.lra_out      = float(sub.get('lra', 0))
-                    res.crest_out    = float(sub.get('crest', 0))
-                    res.sub_result   = sub
-                    L(f'  [E1] Score: {res.score_before:.1f}→{res.score_after:.1f}  '
-                      f'LUFS={res.lufs_out:.2f}  Crest={res.crest_out:.2f}')
-                else:
-                    L('  [E1] output file missing after enhance()')
-            except Exception as e:
-                L(f'  [E1] الاسترداد failed: {e}')
-                import traceback; L(traceback.format_exc())
-
-        # ── B4: البيان v2 ─────────────────────────────────────────────────────
-        if run_bayan and os.path.exists(current_path):
-            L('\n── B4: البيان ──────────────────────────────────────────────')
-            bayan_out = _run_bayan(
-                current_path, tier, codec_cutoff, ref_third_oct, L
-            )
-            if bayan_out != current_path and os.path.exists(bayan_out):
-                current_path   = bayan_out
-                res.bayan_applied = True
-
-        # ── B5: النور v5 ──────────────────────────────────────────────────────
-        if run_noor and os.path.exists(current_path):
-            L('\n── B5: النور ───────────────────────────────────────────────')
-            noor_out_path = os.path.join(tmp_dir, 'noor_out.wav')
-            noor_out = _run_noor(
-                current_path, noor_out_path,
-                ref_files[0] if ref_files else None, L
-            )
-            if noor_out != current_path and os.path.exists(noor_out):
-                current_path  = noor_out
-                res.noor_applied = True
-
-        # ── T-7: Final copy to output ─────────────────────────────────────────
-        L('\n── T-7: Output ─────────────────────────────────────────────')
-        if os.path.exists(current_path):
-            os.makedirs(os.path.dirname(os.path.abspath(output_path)),
-                        exist_ok=True)
-            shutil.copy2(current_path, output_path)
-            res.output_sha256 = _sha256(output_path)
-            L(f'  ✓ Written → {output_path}')
-            L(f'  SHA256    : {res.output_sha256}')
-        else:
-            L('  ✗ No output produced — pipeline failed')
-
-    finally:
-        shutil.rmtree(tmp_dir, ignore_errors=True)
-
-    res.elapsed_s = time.time() - t0
-    res.log = _LOG
-
-    L(f'\n{"═"*64}')
-    L(f'  التجلي complete: {res.score_before:.1f}→{res.score_after:.1f}/100')
-    L(f'  Engine: {res.engine_used}')
-    L(f'  Tier: {res.tier}  |  البيان: {"✓" if res.bayan_applied else "✗"}  '
-      f'|  النور: {"✓" if res.noor_applied else "✗"}')
-    L(f'  LUFS={res.lufs_out:.2f}  LRA={res.lra_out:.2f}  '
-      f'Crest={res.crest_out:.2f}  [{res.elapsed_s:.1f}s]')
-    L(f'{"═"*64}')
-
-    return res
-
-
-# ══════════════════════════════════════════════════════════════════════════════
-#  CLI
-# ══════════════════════════════════════════════════════════════════════════════
-def main() -> int:
-    p = argparse.ArgumentParser(
-        description=f'التجلي {TAJALLI_VERSION} — محسن التلاوات Processing Engine',
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-examples:
-  python engine_tajalli_v1.py -i surah.mp3 -o enhanced.wav --ref ref_1425.mp3
-  python engine_tajalli_v1.py -i damaged.mp3 -o restored.wav --ref ref_1425.mp3 --tier TIER_DAMAGED
-  python engine_tajalli_v1.py -i clean.mp3 -o out.wav --ref ref_1425.mp3 --no-noor
-        """
-    )
-    p.add_argument('-i', '--input',      required=False, help='Input audio file')
-    p.add_argument('-o', '--output',     required=False, help='Output file (.wav)')
-    p.add_argument('--ref',  action='append', default=[], metavar='REF_MP3',
-                   help='Reference 1425H audio (can repeat)')
-    p.add_argument('--iterations', type=int,   default=3,
-                   help='Processing iterations (default: 3)')
-    p.add_argument('--target',     type=float, default=96.0,
-                   help='Target quality score (default: 96)')
-    p.add_argument('--tier', default=None,
-                   choices=[TIER_PRISTINE, TIER_PRISTINE_NOISY,
-                             TIER_COMPRESSED, TIER_DAMAGED, TIER_CRITICAL],
-                   help='Force tier (bypass auto-detection)')
-    p.add_argument('--aggressive', action='store_true',
-                   help='Aggressive mode — all processing pushed harder')
-    p.add_argument('--no-bayan',   action='store_true', help='Skip البيان v2')
-    p.add_argument('--no-noor',    action='store_true', help='Skip النور v5')
-    p.add_argument('--json',       action='store_true', help='Output JSON result')
-    p.add_argument('--engines',    action='store_true', help='Show detected engine paths')
-
-    args = p.parse_args()
-
-    if args.engines:
-        print(f'التجلي {TAJALLI_VERSION}')
-        print(f'  الإتقان   : {_ITIQAN_PATH  or "NOT FOUND"}')
-        print(f'  الاسترداد : {_ISTEIDAD_PATH or "NOT FOUND"}')
-        print(f'  النقاء    : {_NAQAA_PATH   or "NOT FOUND"}')
-        print(f'  البيان    : {_BAYAN_PATH   or "NOT FOUND"}')
-        print(f'  النور     : {_NOOR_PATH    or "NOT FOUND"}')
-        return 0
-
-    if not args.input or not args.output:
-        if not args.engines:
-            p.error('arguments -i/--input and -o/--output are required')
-    ref_files = [r for r in args.ref if os.path.exists(r)]
-    if args.ref and not ref_files:
-        print(f'WARNING: No reference files found from: {args.ref}')
-
-    result = process(
-        input_path   = args.input,
-        output_path  = args.output,
-        ref_files    = ref_files,
-        iterations   = args.iterations,
-        target_score = args.target,
-        force_tier   = args.tier,
-        aggressive   = args.aggressive,
-        run_bayan    = not args.no_bayan,
-        run_noor     = not args.no_noor,
-    )
-
-    if args.json:
-        print(json.dumps({
-            'version':       result.engine_version,
-            'tier':          result.tier,
-            'engine_used':   result.engine_used,
-            'score_before':  result.score_before,
-            'score_after':   result.score_after,
-            'score_ceiling': result.score_ceiling,
-            'lufs_out':      result.lufs_out,
-            'lra_out':       result.lra_out,
-            'crest_out':     result.crest_out,
-            'bayan_applied': result.bayan_applied,
-            'noor_applied':  result.noor_applied,
-            'naqaa_pre_pass': result.naqaa_pre_pass,
-            'input_sha256':  result.input_sha256,
-            'output_sha256': result.output_sha256,
-            'elapsed_s':     round(result.elapsed_s, 2),
-        }, ensure_ascii=False, indent=2))
-
-    success = result.score_after > 0 and os.path.exists(args.output)
-    return 0 if success else 1
-
-
-if __name__ == '__main__':
-    sys.exit(main())