qcoder 0.1.0a0__py3-none-any.whl

qcoder/tools/runners/quantum_rings/v12/harness.py

@@ -0,0 +1,1350 @@
+#!/usr/bin/env python3
+"""
+qcoder.tools.harness
+
+QCoder harness: Adaptive Threshold (2× ladder) + Benchmark + Aggregate Report
+
+Pipeline per (circuit, backend, precision):
+  1) Mirror sweep on threshold ladder using qcoder.tools.mirror until target metric is met (or exhausted)
+     - Optional: runner timing probe at each tested threshold (shots_probe) with JSON immediately deleted
+  2) Select threshold = first meeting target (or fallback)
+  3) (Optional) Verification mirror at selected threshold using counts-based mirror (qasm_counts) to report p_return_zero
+  4) Benchmark original circuit with qcoder.tools.runner at selected threshold:
+       - shots_state (default 1)     : proxy for state/setup time
+       - shots_hist  (default 10000): histogram runtime (JSON kept per policy)
+  5) Write ONE aggregate report JSON for the whole harness run
+  6) Retention policy:
+       - Mirror JSONs: keep bracketing + selected (default)
+       - Runner JSONs: keep hist-only (default: keep shots_hist JSON, delete shots_state JSON)
+       - Probe JSONs: always deleted (metrics stored in report only)
+
+Notes:
+- Harness invokes your scripts via subprocess; it does NOT import QuantumRingsLib.
+- This avoids DLL path issues; qr_dll_bootstrap runs inside each script.
+
+New capabilities:
+- --mirror-mode auto|qasm_counts|sdk_inverse_fidelity
+  auto => sdk_inverse_fidelity when --mirror-metric=sdk_get_fidelity else qasm_counts
+- Timeouts per subprocess call (mirror/runner/probe)
+- Optional verification mirror (--mirror-verify) to report both methods while using sdk_inverse_fidelity for selection
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import datetime as _dt
+import glob
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+
+# -----------------------------
+# Utility
+# -----------------------------
+
+def die(msg: str, code: int = 1) -> None:
+    print(f"[fatal] {msg}", file=sys.stderr, flush=True)
+    sys.exit(code)
+
+def utc_now_iso() -> str:
+    return _dt.datetime.now(_dt.timezone.utc).replace(microsecond=0).isoformat()
+
+def ensure_dir(p: str) -> None:
+    os.makedirs(p, exist_ok=True)
+
+def sha256_file(path: str, chunk_size: int = 1 << 20) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while True:
+            b = f.read(chunk_size)
+            if not b:
+                break
+            h.update(b)
+    return h.hexdigest()
+
+def read_text(path: str) -> str:
+    with open(path, "r", encoding="utf-8", errors="replace") as f:
+        return f.read()
+
+def safe_unlink(path: str) -> None:
+    try:
+        os.remove(path)
+    except FileNotFoundError:
+        return
+    except Exception as e:
+        print(f"[warn] could not delete {path}: {e}", flush=True)
+
+def run_subprocess(cmd: List[str], quiet: bool, timeout_s: Optional[float]) -> Tuple[int, str]:
+    """
+    Run command; return (returncode, combined stdout+stderr).
+    Timeout returns rc=124 and includes a [timeout] line in output.
+    """
+    if not quiet:
+        print("[cmd]", " ".join(cmd), flush=True)
+
+    t = None
+    if timeout_s is not None and float(timeout_s) > 0:
+        t = float(timeout_s)
+
+    try:
+        p = subprocess.run(cmd, capture_output=True, text=True, timeout=t)
+        out = (p.stdout or "") + (p.stderr or "")
+        if not quiet and out.strip():
+            print(out.rstrip(), flush=True)
+        return p.returncode, out
+    except subprocess.TimeoutExpired as e:
+        def _to_text(x: Any) -> str:
+            if x is None:
+                return ""
+            if isinstance(x, bytes):
+                return x.decode("utf-8", errors="replace")
+            return str(x)
+
+        out = ""
+        out += _to_text(getattr(e, "stdout", None))
+        out += _to_text(getattr(e, "stderr", None))
+        out += f"\n[timeout] exceeded {t}s\n"
+        if not quiet:
+            print(out.rstrip(), flush=True)
+        return 124, out
+
+def parse_json(path: str) -> Dict[str, Any]:
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+def to_float(x) -> Optional[float]:
+    try:
+        if x is None:
+            return None
+        return float(x)
+    except Exception:
+        return None
+
+def to_int(x) -> Optional[int]:
+    try:
+        if x is None:
+            return None
+        return int(x)
+    except Exception:
+        return None
+
+
+def _truncate_error_message(out: str, max_len: int = 600) -> Optional[str]:
+    """Compact subprocess output into a bounded error message."""
+    text = (out or "").strip()
+    if not text:
+        return None
+    lines = [ln.strip() for ln in text.replace("\r", "\n").splitlines() if ln.strip()]
+    if not lines:
+        return None
+    msg = " | ".join(lines[-6:])
+    if len(msg) > max_len:
+        msg = "..." + msg[-(max_len - 3):]
+    return msg
+
+
+CANONICAL_STATUSES = {
+    "ok",
+    "non_unitary",
+    "unsupported_gate",
+    "backend_not_found",
+    "parse_error",
+    "runner_error",
+    "timeout",
+}
+
+
+def classify_attempt_status(note: str, returncode: Optional[int], error_message: Optional[str]) -> Tuple[str, str, str]:
+    """
+    Map subprocess outcome to canonical status/error labels.
+    Returns (status, error_code, error_detail).
+    """
+    note_s = (note or "").strip()
+    msg = (error_message or "").strip()
+    msg_l = msg.lower()
+
+    if (returncode == 0) and note_s == "ok":
+        return "ok", "", ""
+    if returncode == 124 or "timeout" in note_s:
+        return "timeout", "timeout", msg or note_s or "timeout"
+    if "could not resolve backend" in msg_l:
+        return "backend_not_found", "backend_not_found", msg or note_s
+    if "mirror eligibility=non_unitary" in msg_l:
+        return "non_unitary", "non_unitary", msg or note_s
+    if "mirror eligibility=parse_error" in msg_l or "unrecognized statement" in msg_l:
+        return "parse_error", "parse_error", msg or note_s
+    if "unsupported gate for mirror" in msg_l or "unsupported include for mirror" in msg_l:
+        return "unsupported_gate", "unsupported_gate", msg or note_s
+
+    # Distinguish structured missing-json cases; otherwise generic runner_error.
+    if note_s in {"mirror_missing_json", "runner_missing_json"}:
+        return "runner_error", note_s, msg or note_s
+    return "runner_error", "runner_error", msg or note_s
+
+
+# -----------------------------
+# Quick QASM2 features (cheap heuristics)
+# -----------------------------
+
+_QREG_DECL_RE = re.compile(r'^\s*qreg\s+([A-Za-z_]\w*)\s*\[(\d+)\]\s*;', re.M)
+_CREG_DECL_RE = re.compile(r'^\s*creg\s+([A-Za-z_]\w*)\s*\[(\d+)\]\s*;', re.M)
+_MEASURE_RE = re.compile(r'^\s*measure\s+', re.I)
+
+_TWOQ_MNEMONICS = ("cx", "cz", "swap", "rzz", "rxx", "ryy", "rzx", "crx", "cry", "crz", "cp", "cu1", "cu3", "ch")
+
+def qasm2_features(text: str) -> Dict[str, Any]:
+    # strip // comments and blank lines for counting
+    lines = []
+    for raw in text.splitlines():
+        s = raw.strip()
+        if not s or s.startswith("//"):
+            continue
+        lines.append(s)
+
+    qregs = [(m.group(1), int(m.group(2))) for m in _QREG_DECL_RE.finditer(text)]
+    cregs = [(m.group(1), int(m.group(2))) for m in _CREG_DECL_RE.finditer(text)]
+    n_qubits = sum(n for _, n in qregs) if qregs else None
+    n_clbits = sum(n for _, n in cregs) if cregs else 0
+
+    n_measure = 0
+    n_barrier = 0
+    n_decl = 0
+    n_ops = 0
+    n_2q = 0
+    n_other = 0
+
+    for s in lines:
+        sl = s.lower()
+        if sl.startswith("openqasm") or sl.startswith("include"):
+            continue
+        if sl.startswith("qreg") or sl.startswith("creg"):
+            n_decl += 1
+            continue
+        if sl.startswith("barrier"):
+            n_barrier += 1
+            continue
+        if _MEASURE_RE.match(s):
+            n_measure += 1
+            continue
+        if s.endswith(";"):
+            n_ops += 1
+            first = s.split(None, 1)[0].strip().lower()
+            if first in _TWOQ_MNEMONICS:
+                n_2q += 1
+            else:
+                n_other += 1
+
+    return {
+        "qasm_n_qubits_decl": n_qubits,
+        "qasm_n_clbits_decl": n_clbits,
+        "qasm_ops_total_approx": n_ops,
+        "qasm_ops_2q_approx": n_2q,
+        "qasm_ops_other": n_other,
+        "qasm_measures": n_measure,
+        "qasm_barriers": n_barrier,
+        "qasm_decls": n_decl,
+        "qasm_nonempty_lines": len(lines),
+    }
+
+
+# -----------------------------
+# Data classes
+# -----------------------------
+
+@dataclass
+class MirrorRun:
+    threshold: int
+    json_path: str
+    metric_value: Optional[float]          # the metric used for selection
+    p_return_zero: Optional[float]         # from mirror_metrics.p_return_zero
+    sdk_get_fidelity: Optional[float]      # from sdk_metrics.get_fidelity
+    sdk_peakmem0: Optional[float]          # from sdk_metrics.get_peakmemorysize_0 (numeric-ish)
+    run_wall_s: Optional[float]
+    peak_rss_mb: Optional[float]
+    returncode: int
+    note: str
+    error_message: Optional[str] = None
+
+@dataclass
+class RunnerRun:
+    threshold: int
+    shots: int
+    json_path: str
+    run_wall_s: Optional[float]
+    peak_rss_mb: Optional[float]
+    unique_outcomes: Optional[int]
+    tail_mass: Optional[float]
+    sdk_get_fidelity: Optional[float]
+    sdk_peakmem0: Optional[float]
+    returncode: int
+    note: str
+    error_message: Optional[str] = None
+
+
+# -----------------------------
+# RunRecord (JSONL) schema
+# -----------------------------
+
+RUN_RECORD_SCHEMA = "qcoder.run_record.v0"
+FIDELITY_NOT_SET_DEFAULTED = "FIDELITY_NOT_SET_DEFAULTED"
+
+
+def build_run_record(
+    *,
+    content_hash: str,
+    features_ref: str,
+    fidelity_metric_source: str,
+    created_utc: str,
+    qasm_file: str,
+    qasm_path: str,
+    backend: str,
+    backend_id: str,
+    precision: str,
+    env_id: str,
+    status: str,
+    selected_threshold: Optional[int],
+    run_kind: str = "job_summary",
+    threshold: Optional[int] = None,
+    shots: Optional[int] = None,
+    runtime_wall_s: Optional[float] = None,
+    fidelity: Optional[float] = None,
+    fidelity_metric: Optional[str] = None,
+    returncode: Optional[int] = None,
+    error_type: Optional[str] = None,
+    error_message: Optional[str] = None,
+    error_code: Optional[str] = None,
+    error_detail: Optional[str] = None,
+    peak_rss_mb: Optional[float] = None,
+    mirror_wall_s: Optional[float] = None,
+    probe_wall_s: Optional[float] = None,
+    runner_wall_s: Optional[float] = None,
+    shots_mirror: Optional[int] = None,
+    shots_runner: Optional[int] = None,
+) -> Dict[str, Any]:
+    """Build a RunRecord dict for JSONL logging. features_ref is relative to out_dir (dataset root)."""
+    warnings: List[str] = []
+    if fidelity_metric_source == "default":
+        warnings.append(FIDELITY_NOT_SET_DEFAULTED)
+    return {
+        "schema": RUN_RECORD_SCHEMA,
+        "content_hash": content_hash,
+        "features_ref": features_ref,
+        "fidelity_metric_source": fidelity_metric_source,
+        "warnings": warnings,
+        "created_utc": created_utc,
+        "qasm_file": qasm_file,
+        "qasm_path": qasm_path,
+        "backend": backend,
+        "backend_id": backend_id,
+        "precision": precision,
+        "env_id": env_id,
+        "run_kind": run_kind,
+        "status": status,
+        "selected_threshold": selected_threshold,
+        "threshold": threshold,
+        "shots": shots,
+        "runtime_wall_s": runtime_wall_s,
+        "fidelity": fidelity,
+        "fidelity_metric": fidelity_metric,
+        "returncode": returncode,
+        "peak_rss_mb": peak_rss_mb,
+        "mirror_wall_s": mirror_wall_s,
+        "probe_wall_s": probe_wall_s,
+        "runner_wall_s": runner_wall_s,
+        "shots_mirror": shots_mirror,
+        "shots_runner": shots_runner,
+        "error_code": error_code,
+        "error_detail": error_detail,
+        # Legacy aliases kept for backward compatibility
+        "error_type": error_type,
+        "error_message": error_message,
+    }
+
+
+# -----------------------------
+# Extract metrics from per-run JSONs
+# -----------------------------
+
+def _extract_sdk_metrics(payload: Dict[str, Any]) -> Tuple[Optional[float], Optional[float]]:
+    sm = payload.get("sdk_metrics", {}) if isinstance(payload.get("sdk_metrics", {}), dict) else {}
+    gf = to_float(sm.get("get_fidelity"))
+
+    # We standardize on get_peakmemorysize_0; fallback to other keys if needed
+    pm = sm.get("get_peakmemorysize_0")
+    if pm is None:
+        pm = sm.get("get_peakmemorysize")
+    pmf = to_float(pm)
+
+    return gf, pmf
+
+def extract_mirror_metrics(
+    payload: Dict[str, Any],
+    mirror_metric: str
+) -> Tuple[Optional[float], Optional[float], Optional[float], Optional[float], Optional[float], Optional[float]]:
+    """
+    Returns:
+      metric_value (used for selection),
+      p_return_zero,
+      sdk_get_fidelity,
+      sdk_peakmem0,
+      run_wall_s,
+      peak_rss_mb
+    """
+    p0 = None
+    try:
+        mm = payload.get("mirror_metrics", {})
+        if isinstance(mm, dict):
+            p0 = to_float(mm.get("p_return_zero"))
+    except Exception:
+        p0 = None
+
+    gf, pm0 = _extract_sdk_metrics(payload)
+
+    t = to_float(payload.get("timing_s", {}).get("run_wall_s")) if isinstance(payload.get("timing_s", {}), dict) else None
+    mem = to_float(payload.get("memory", {}).get("peak_rss_mb")) if isinstance(payload.get("memory", {}), dict) else None
+
+    if mirror_metric == "p_return_zero":
+        mv = p0
+    elif mirror_metric == "sdk_get_fidelity":
+        mv = gf
+    else:
+        mv = None
+
+    return mv, p0, gf, pm0, t, mem
+
+def extract_runner_metrics(payload: Dict[str, Any]) -> Tuple[Optional[float], Optional[float], Optional[int], Optional[float], Optional[float], Optional[float]]:
+    """
+    Returns:
+      run_wall_s, peak_rss_mb, unique_outcomes, tail_mass, sdk_get_fidelity, sdk_peakmem0
+    """
+    t = to_float(payload.get("timing_s", {}).get("run_wall_s")) if isinstance(payload.get("timing_s", {}), dict) else None
+    mem = to_float(payload.get("memory", {}).get("peak_rss_mb")) if isinstance(payload.get("memory", {}), dict) else None
+
+    u = None
+    tail = None
+    try:
+        h = payload.get("hist", {})
+        if isinstance(h, dict):
+            u = to_int(h.get("unique_outcomes"))
+            tail = to_float(h.get("tail_mass"))
+    except Exception:
+        pass
+
+    gf, pm0 = _extract_sdk_metrics(payload)
+    return t, mem, u, tail, gf, pm0
+
+
+# -----------------------------
+# Invocations
+# -----------------------------
+
+_OK_JSON_RE = re.compile(r"\[ok\]\s+wrote JSON:\s*(.+)$", re.M)
+
+def run_mirror_once(
+    qasm_path: str,
+    backend: str,
+    precision: str,
+    threshold: int,
+    shots: int,
+    out_dir: str,
+    quiet: bool,
+    mirror_metric: str,
+    mirror_mode: Optional[str],
+    timeout_s: Optional[float],
+) -> MirrorRun:
+
+    ensure_dir(out_dir)
+
+    cmd = [
+        sys.executable, "-m", "qcoder.tools.mirror",
+        qasm_path,
+        "--backend", backend,
+        "--precision", precision,
+        "--threshold", str(int(threshold)),
+        "--shots", str(int(shots)),
+        "--out-dir", out_dir,
+    ]
+    if mirror_mode:
+        cmd += ["--mirror-mode", mirror_mode]
+
+    rc, out = run_subprocess(cmd, quiet=quiet, timeout_s=timeout_s)
+
+    json_path = ""
+    m = _OK_JSON_RE.search(out)
+    if m:
+        json_path = m.group(1).strip()
+
+    if rc == 124:
+        return MirrorRun(threshold, json_path, None, None, None, None, None, None, rc, "mirror_timeout", _truncate_error_message(out))
+
+    if rc != 0:
+        return MirrorRun(threshold, json_path, None, None, None, None, None, None, rc, "mirror_failed", _truncate_error_message(out))
+
+    if not json_path or not os.path.exists(json_path):
+        return MirrorRun(threshold, json_path, None, None, None, None, None, None, rc, "mirror_missing_json", _truncate_error_message(out))
+
+    payload = parse_json(json_path)
+    mv, p0, gf, pm0, t, mem = extract_mirror_metrics(payload, mirror_metric=mirror_metric)
+    return MirrorRun(threshold, json_path, mv, p0, gf, pm0, t, mem, rc, "ok")
+
+def run_runner_once(
+    qasm_path: str,
+    backend: str,
+    precision: str,
+    threshold: int,
+    shots: int,
+    topk: int,
+    out_dir: str,
+    quiet: bool,
+    timeout_s: Optional[float],
+) -> RunnerRun:
+
+    ensure_dir(out_dir)
+
+    cmd = [
+        sys.executable, "-m", "qcoder.tools.runner",
+        qasm_path,
+        "--backend", backend,
+        "--precision", precision,
+        "--threshold", str(int(threshold)),
+        "--shots", str(int(shots)),
+        "--topk", str(int(topk)),
+        "--out-dir", out_dir,
+    ]
+    rc, out = run_subprocess(cmd, quiet=quiet, timeout_s=timeout_s)
+
+    json_path = ""
+    m = _OK_JSON_RE.search(out)
+    if m:
+        json_path = m.group(1).strip()
+
+    if rc == 124:
+        return RunnerRun(threshold, shots, json_path, None, None, None, None, None, None, rc, "runner_timeout", _truncate_error_message(out))
+
+    if rc != 0:
+        return RunnerRun(threshold, shots, json_path, None, None, None, None, None, None, rc, "runner_failed", _truncate_error_message(out))
+
+    if not json_path or not os.path.exists(json_path):
+        return RunnerRun(threshold, shots, json_path, None, None, None, None, None, None, rc, "runner_missing_json", _truncate_error_message(out))
+
+    payload = parse_json(json_path)
+    t, mem, u, tail, gf, pm0 = extract_runner_metrics(payload)
+    return RunnerRun(threshold, shots, json_path, t, mem, u, tail, gf, pm0, rc, "ok")
+
+
+# -----------------------------
+# Policies / helpers
+# -----------------------------
+
+def build_threshold_ladder(start: int, max_thr: int) -> List[int]:
+    x = max(1, int(start))
+    out: List[int] = []
+    while x <= int(max_thr):
+        out.append(x)
+        x *= 2
+    return out
+
+def _forward_thresholds_from_mirror(
+    mirror_runs: List[MirrorRun],
+    selected_thr: Optional[int],
+    ladder: List[int],
+) -> List[int]:
+    """
+    Build forward_thresholds: thresholds from mirror_runs that returned successfully and have
+    a usable non-null metric_value. Preserves ladder order and deduplicates.
+    If none, fall back to [selected_thr] so report/CSV remain defined.
+    selected_thr is always included so the primary summary pair exists.
+    """
+    out = list(dict.fromkeys(
+        mr.threshold for mr in mirror_runs
+        if mr.returncode == 0 and mr.metric_value is not None
+    ))
+    if not out:
+        return [selected_thr] if selected_thr is not None else []
+    # Ensure selected_thr is included for job_summary/report/CSV primary pair.
+    if selected_thr is not None and selected_thr not in out:
+        out = out + [selected_thr]
+        out.sort(key=lambda t: ladder.index(t) if t in ladder else 999)
+    return out
+
+
+def mirror_keep_set(mirror_runs: List[MirrorRun], selected_thr: Optional[int], keep_policy: str) -> set:
+    """
+    keep_policy: all | bracketing+selected | selected-only | none
+    """
+    if keep_policy == "all":
+        return {mr.json_path for mr in mirror_runs if mr.json_path}
+    if keep_policy == "none":
+        return set()
+    if selected_thr is None:
+        return {mr.json_path for mr in mirror_runs if mr.json_path}
+    if keep_policy == "selected-only":
+        return {mr.json_path for mr in mirror_runs if mr.json_path and mr.threshold == selected_thr}
+
+    keep = set()
+    sel_idx = None
+    for i, mr in enumerate(mirror_runs):
+        if mr.threshold == selected_thr:
+            sel_idx = i
+            break
+    if sel_idx is not None:
+        if mirror_runs[sel_idx].json_path:
+            keep.add(mirror_runs[sel_idx].json_path)
+        if sel_idx - 1 >= 0 and mirror_runs[sel_idx - 1].json_path:
+            keep.add(mirror_runs[sel_idx - 1].json_path)
+    return keep
+
+def fmt_opt(x: Optional[float], digits: int = 3) -> str:
+    if x is None:
+        return "?"
+    return f"{x:.{digits}f}"
+
+def fmt_int(x: Optional[int]) -> str:
+    return "?" if x is None else str(int(x))
+
+
+# -----------------------------
+# Main
+# -----------------------------
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="QCoder harness: mirror threshold selection + shots=1 and shots=hist benchmarks.")
+
+    ap.add_argument("--mirror-metric", choices=["p_return_zero", "sdk_get_fidelity"], default="p_return_zero",
+                    help="Which metric from the mirror run to use for threshold selection.")
+
+    ap.add_argument(
+        "--mirror-mode",
+        choices=["auto", "qasm_counts", "sdk_inverse_fidelity"],
+        default="auto",
+        help="auto => sdk_inverse_fidelity when mirror-metric=sdk_get_fidelity else qasm_counts."
+    )
+
+    ap.add_argument("--mirror-verify", action="store_true",
+                    help="After selecting threshold, run a counts-based mirror (qasm_counts) at selected threshold to report p_return_zero.")
+    ap.add_argument("--mirror-verify-shots", type=int, default=1000,
+                    help="Shots for verification counts-based mirror (only used when --mirror-verify).")
+
+    ap.add_argument("--target-fidelity", dest="target", type=float, default=0.99,
+                    help="Target mirror metric to meet/exceed (default 0.99).")
+    ap.add_argument("--threshold-start", type=int, default=2, help="Start of 2× threshold ladder.")
+    ap.add_argument("--threshold-max", type=int, default=256, help="Max threshold in ladder.")
+    ap.add_argument("--stop-when", choices=["first_cross", "exhaust"], default="first_cross",
+                    help="Stop scanning ladder at first threshold meeting target, or always exhaust ladder.")
+
+    ap.add_argument("--circuits-folder", default="circuits", help="Folder containing QASM files.")
+    ap.add_argument("--circuit-glob", default="*.qasm", help="Glob pattern inside circuits-folder.")
+    ap.add_argument("--include", nargs="*", default=None, help="Optional allowlist (filenames).")
+    ap.add_argument("--exclude", nargs="*", default=None, help="Optional blocklist (filenames).")
+    ap.add_argument("--max-circuits", type=int, default=0, help="Optional cap (0=no cap).")
+    ap.add_argument("--sort-circuits", choices=["size", "name"], default="size",
+                    help="Sort circuits by file size (ascending) or by name.")
+
+    ap.add_argument("--backends", nargs="+", default=["Scarlet"], help="Backends: e.g. Scarlet Amber Serin")
+    ap.add_argument("--precisions", nargs="+", default=["single"], choices=["single", "double"], help="Precisions.")
+
+    ap.add_argument("--shots-mirror", type=int, default=200,
+                    help="Shots for mirror metric. If mirror-mode is sdk_inverse_fidelity, shots can be small (even 1).")
+
+    ap.add_argument("--shots-probe", type=int, default=0,
+                    help="Runner shots for per-threshold timing probe during mirror sweep. Set 0 to disable.")
+
+    ap.add_argument("--shots-state", type=int, default=1, help="Runner shots for state/setup timing proxy (default 1).")
+    ap.add_argument("--shots-hist", type=int, default=10000, help="Runner shots for histogram timing (default 10000).")
+
+    ap.add_argument("--topk", type=int, default=50, help="Top-K bitstrings stored by runner JSON.")
+    ap.add_argument("--out-dir", default="runs", help="Output directory for per-run JSONs.")
+    ap.add_argument("--report-json", default="runs/harness_report.json", help="Aggregate report JSON path.")
+    ap.add_argument("--run-record", default=None, metavar="PATH",
+                    help="If set, append one RunRecord JSON object per line (JSONL) to PATH. Path-driven; no default.")
+    ap.add_argument("--subdir", default=None, help="Optional subdirectory under --out-dir (e.g. exp_harness).")
+
+    ap.add_argument("--keep-mirror", choices=["bracketing+selected", "all", "selected-only", "none"],
+                    default="bracketing+selected", help="Which mirror JSONs to retain on disk.")
+    ap.add_argument("--keep-runner", choices=["hist-only", "all", "none"], default="hist-only",
+                    help="Which runner JSONs to retain (hist-only keeps only shots-hist JSON).")
+
+    ap.add_argument("--dataset-csv", default="runs/harness_dataset.csv", help="Dataset CSV path.")
+    ap.add_argument("--append-csv", action="store_true", help="Append to CSV if it exists.")
+    ap.add_argument("--quiet-cmd", action="store_true", help="Suppress subprocess stdout/stderr (use one-line summaries).")
+
+    ap.add_argument("--timeout-mirror-s", type=int, default=1800, help="Timeout per mirror rung (0 disables).")
+    ap.add_argument("--timeout-runner-s", type=int, default=1800, help="Timeout per runner call (0 disables).")
+    ap.add_argument("--timeout-probe-s", type=int, default=600, help="Timeout per probe runner call (0 disables).")
+
+    args = ap.parse_args()
+    args.mirror_metric_explicit = "--mirror-metric" in sys.argv
+
+    # Resolve mirror mode for the main selection sweep
+    if args.mirror_mode == "auto":
+        mirror_mode_sel = "sdk_inverse_fidelity" if args.mirror_metric == "sdk_get_fidelity" else "qasm_counts"
+    else:
+        mirror_mode_sel = args.mirror_mode
+
+    # Subdir behavior: put outputs into runs/<subdir>/ but preserve explicit custom paths elsewhere
+    if args.subdir:
+        base_out_dir = args.out_dir  # typically "runs"
+        exp_out_dir = os.path.join(base_out_dir, args.subdir)
+
+        base_abs = os.path.abspath(base_out_dir)
+        rep_abs = os.path.abspath(args.report_json)
+        csv_abs = os.path.abspath(args.dataset_csv)
+
+        if rep_abs.startswith(base_abs + os.sep):
+            args.report_json = os.path.join(exp_out_dir, os.path.basename(args.report_json))
+
+        if csv_abs.startswith(base_abs + os.sep):
+            args.dataset_csv = os.path.join(exp_out_dir, os.path.basename(args.dataset_csv))
+
+        args.out_dir = exp_out_dir
+
+    target = float(args.target)
+    if not (0.0 < target <= 1.0):
+        die("--target-fidelity must be in (0,1].")
+
+    ladder = build_threshold_ladder(args.threshold_start, args.threshold_max)
+    if not ladder:
+        die("Empty ladder. Check --threshold-start/--threshold-max.")
+
+    ensure_dir(args.out_dir)
+    ensure_dir(os.path.dirname(args.report_json) or ".")
+    ensure_dir(os.path.dirname(args.dataset_csv) or ".")
+    run_record_path: Optional[str] = (args.run_record or "").strip() or None
+    if run_record_path:
+        ensure_dir(os.path.dirname(os.path.abspath(run_record_path)) or ".")
+    features_dir = os.path.join(args.out_dir, "features")
+
+    # Gather circuits
+    pattern = os.path.join(args.circuits_folder, args.circuit_glob)
+    candidates = glob.glob(pattern)
+    if not candidates:
+        die(f"No circuits found: {pattern}")
+
+    include = set(args.include or [])
+    exclude = set(args.exclude or [])
+    circuits: List[str] = []
+    for p in candidates:
+        base = os.path.basename(p)
+        if include and base not in include:
+            continue
+        if exclude and base in exclude:
+            continue
+        circuits.append(p)
+
+    if args.sort_circuits == "size":
+        circuits.sort(key=lambda p: (os.path.getsize(p), os.path.basename(p)))
+    else:
+        circuits.sort(key=lambda p: os.path.basename(p))
+
+    if args.max_circuits and args.max_circuits > 0:
+        circuits = circuits[: int(args.max_circuits)]
+
+    total_jobs = len(circuits) * len(args.backends) * len(args.precisions)
+    job_idx = 0
+
+    print("===== QCoder harness =====", flush=True)
+    print(f"[config] mirror_metric={args.mirror_metric} mirror_mode={args.mirror_mode} resolved_mode={mirror_mode_sel}", flush=True)
+    print(f"[config] target={target} ladder={ladder} stop_when={args.stop_when}", flush=True)
+    print(f"[config] circuits={len(circuits)} backends={args.backends} precisions={args.precisions}", flush=True)
+    print(f"[config] shots_mirror={args.shots_mirror} shots_probe={args.shots_probe} shots_state={args.shots_state} shots_hist={args.shots_hist}", flush=True)
+    print(f"[config] mirror_verify={args.mirror_verify} mirror_verify_shots={args.mirror_verify_shots}", flush=True)
+    print(f"[config] timeouts: mirror={args.timeout_mirror_s}s runner={args.timeout_runner_s}s probe={args.timeout_probe_s}s", flush=True)
+    print(f"[config] keep_mirror={args.keep_mirror} keep_runner={args.keep_runner} out_dir={args.out_dir}", flush=True)
+
+    report: Dict[str, Any] = {
+        "meta": {
+            "schema_version": "qr12_harness_1.1",
+            "created_utc": utc_now_iso(),
+            "mirror_metric": args.mirror_metric,
+            "mirror_mode": args.mirror_mode,
+            "mirror_mode_resolved": mirror_mode_sel,
+            "mirror_verify": bool(args.mirror_verify),
+            "mirror_verify_shots": int(args.mirror_verify_shots),
+            "target": target,
+            "threshold_ladder": ladder,
+            "stop_when": args.stop_when,
+            "circuits_folder": os.path.abspath(args.circuits_folder),
+            "circuit_glob": args.circuit_glob,
+            "sorted_by": args.sort_circuits,
+            "backends": args.backends,
+            "precisions": args.precisions,
+            "shots_mirror": int(args.shots_mirror),
+            "shots_probe": int(args.shots_probe),
+            "shots_state": int(args.shots_state),
+            "shots_hist": int(args.shots_hist),
+            "topk": int(args.topk),
+            "keep_mirror": args.keep_mirror,
+            "keep_runner": args.keep_runner,
+            "out_dir": os.path.abspath(args.out_dir),
+            "timeouts_s": {
+                "mirror": int(args.timeout_mirror_s),
+                "runner": int(args.timeout_runner_s),
+                "probe": int(args.timeout_probe_s),
+            },
+            "python": sys.version.split()[0],
+        },
+        "runs": []
+    }
+
+    # NOTE: CSV schema unchanged (to avoid churn). Verification results go into report JSON.
+    csv_fields = [
+        "created_utc",
+        "qasm_file",
+        "qasm_path",
+        "qasm_sha256",
+        "qasm_bytes",
+        "backend",
+        "backend_id",
+        "precision",
+        "env_id",
+        "mirror_metric",
+        "target",
+        "selected_threshold",
+        "mirror_metric_selected",
+        "mirror_p_return_zero_selected",
+        "mirror_sdk_get_fidelity_selected",
+        "mirror_sdk_peakmem0_selected",
+        "mirror_run_wall_s_selected",
+        "mirror_peak_rss_mb_selected",
+        "probe_shots",
+        "probe_run_wall_s_selected",
+        "probe_peak_rss_mb_selected",
+        "runner_t_state_s",
+        "runner_t_hist_s",
+        "runner_shots_state",
+        "runner_shots_hist",
+        "runner_per_shot_s_est",
+        "runner_hist_unique_outcomes",
+        "runner_hist_tail_mass",
+        "runner_state_sdk_get_fidelity",
+        "runner_state_sdk_peakmem0",
+        "runner_hist_sdk_get_fidelity",
+        "runner_hist_sdk_peakmem0",
+        "runner_state_json",
+        "runner_hist_json",
+        "status",
+        "error_code",
+        "error_detail",
+        "mirror_wall_s",
+        "probe_wall_s",
+        "runner_wall_s",
+        "shots_mirror",
+        "shots_runner",
+        "peak_rss_mb",
+        "note",
+        # heuristics
+        "qasm_n_qubits_decl",
+        "qasm_n_clbits_decl",
+        "qasm_ops_total_approx",
+        "qasm_ops_2q_approx",
+        "qasm_ops_other",
+        "qasm_measures",
+        "qasm_barriers",
+        "qasm_decls",
+        "qasm_nonempty_lines",
+    ]
+
+    write_header = not (args.append_csv and os.path.exists(args.dataset_csv))
+    csv_mode = "a" if args.append_csv else "w"
+    f_csv = open(args.dataset_csv, csv_mode, newline="", encoding="utf-8")
+    writer = csv.DictWriter(f_csv, fieldnames=csv_fields)
+    if write_header:
+        writer.writeheader()
+
+    f_run_record = open(run_record_path, "a", encoding="utf-8") if run_record_path else None
+    try:
+        for qasm_path in circuits:
+            qasm_abs = os.path.abspath(qasm_path)
+            qasm_file = os.path.basename(qasm_path)
+            qasm_hash = sha256_file(qasm_path)
+            qasm_bytes = os.path.getsize(qasm_path)
+
+            feats: Dict[str, Any] = {}
+            try:
+                feats = qasm2_features(read_text(qasm_path))
+            except Exception as e:
+                print(f"[warn] feature extraction failed for {qasm_file}: {e}", flush=True)
+
+            features_ref_rel = ""
+            if run_record_path:
+                ensure_dir(features_dir)
+                features_path = os.path.join(features_dir, qasm_hash + ".json")
+                with open(features_path, "w", encoding="utf-8") as f:
+                    json.dump(feats, f, sort_keys=True)
+                # Store path relative to out_dir (dataset root) for portability
+                features_ref_rel = os.path.join("features", qasm_hash + ".json")
+
+            for backend in args.backends:
+                for precision in args.precisions:
+                    job_idx += 1
+
+                    mirror_runs: List[MirrorRun] = []
+                    probe_runs: List[Optional[RunnerRun]] = []
+                    selected_thr: Optional[int] = None
+
+                    # 1) Mirror sweep
+                    for thr in ladder:
+                        fidelity_metric_source = "explicit" if args.mirror_metric_explicit else "default"
+                        mr = run_mirror_once(
+                            qasm_path=qasm_path,
+                            backend=backend,
+                            precision=precision,
+                            threshold=int(thr),
+                            shots=int(args.shots_mirror),
+                            out_dir=args.out_dir,
+                            quiet=bool(args.quiet_cmd),
+                            mirror_metric=args.mirror_metric,
+                            mirror_mode=mirror_mode_sel,
+                            timeout_s=args.timeout_mirror_s,
+                        )
+                        mirror_runs.append(mr)
+                        if f_run_record and features_ref_rel:
+                            mr_status, mr_error_code, mr_error_detail = classify_attempt_status(
+                                mr.note, mr.returncode, mr.error_message
+                            )
+                            rec = build_run_record(
+                                content_hash=qasm_hash,
+                                features_ref=features_ref_rel,
+                                fidelity_metric_source=fidelity_metric_source,
+                                created_utc=utc_now_iso(),
+                                qasm_file=qasm_file,
+                                qasm_path=qasm_abs,
+                                backend=backend,
+                                backend_id=backend,
+                                precision=precision,
+                                env_id="",
+                                run_kind="mirror_threshold_attempt",
+                                status=mr_status,
+                                selected_threshold=int(thr),
+                                threshold=int(thr),
+                                runtime_wall_s=mr.run_wall_s,
+                                fidelity=mr.metric_value,
+                                fidelity_metric=args.mirror_metric,
+                                returncode=mr.returncode,
+                                peak_rss_mb=mr.peak_rss_mb,
+                                mirror_wall_s=mr.run_wall_s,
+                                shots_mirror=int(args.shots_mirror),
+                                error_code=mr_error_code,
+                                error_detail=mr_error_detail,
+                                error_type=mr_error_code,
+                                error_message=mr.error_message,
+                            )
+                            f_run_record.write(json.dumps(rec, sort_keys=True) + "\n")
+                            f_run_record.flush()
+
+                        probe_rr: Optional[RunnerRun] = None
+                        if int(args.shots_probe) > 0 and mr.returncode == 0:
+                            probe_rr = run_runner_once(
+                                qasm_path=qasm_path,
+                                backend=backend,
+                                precision=precision,
+                                threshold=int(thr),
+                                shots=int(args.shots_probe),
+                                topk=int(args.topk),
+                                out_dir=args.out_dir,
+                                quiet=bool(args.quiet_cmd),
+                                timeout_s=args.timeout_probe_s,
+                            )
+                            # Probe JSON always deleted (metrics kept in report only)
+                            if probe_rr.json_path and os.path.exists(probe_rr.json_path):
+                                safe_unlink(probe_rr.json_path)
+                                probe_rr.json_path = ""
+                        probe_runs.append(probe_rr)
+
+                        if mr.returncode != 0:
+                            continue
+
+                        if mr.metric_value is not None and mr.metric_value >= target:
+                            selected_thr = int(thr)
+                            if args.stop_when == "first_cross":
+                                break
+
+                    legacy_status = "ok"
+                    note = ""
+
+                    # 2) Select threshold fallback rules
+                    if selected_thr is None:
+                        good = [mr for mr in mirror_runs if mr.returncode == 0 and mr.metric_value is not None]
+                        if good:
+                            selected_thr = int(good[-1].threshold)
+                            legacy_status = "no_threshold_met"
+                            note = f"mirror_never_met_target;fallback_thr={selected_thr}"
+                        else:
+                            selected_thr = int(ladder[-1])
+                            legacy_status = "mirror_failed"
+                            note = f"no_successful_mirror;fallback_thr={selected_thr}"
+
+                    sel_mr = next((mr for mr in mirror_runs if mr.threshold == selected_thr), None)
+
+                    sel_probe: Optional[RunnerRun] = None
+                    for mr, pr in zip(mirror_runs, probe_runs):
+                        if mr.threshold == selected_thr:
+                            sel_probe = pr
+                            break
+
+                    # Mirror retention policy for sweep runs
+                    keep_mirror_paths = mirror_keep_set(mirror_runs, selected_thr, args.keep_mirror)
+                    for mr in mirror_runs:
+                        if mr.json_path and os.path.exists(mr.json_path) and (mr.json_path not in keep_mirror_paths):
+                            safe_unlink(mr.json_path)
+
+                    # 3) Optional verification mirror at selected threshold (counts-based)
+                    verify_mr: Optional[MirrorRun] = None
+                    if args.mirror_verify:
+                        verify_mr = run_mirror_once(
+                            qasm_path=qasm_path,
+                            backend=backend,
+                            precision=precision,
+                            threshold=int(selected_thr),
+                            shots=int(args.mirror_verify_shots),
+                            out_dir=args.out_dir,
+                            quiet=bool(args.quiet_cmd),
+                            mirror_metric="p_return_zero",
+                            mirror_mode="qasm_counts",
+                            timeout_s=args.timeout_mirror_s,
+                        )
+                        # Respect keep_mirror=none by deleting verification json too
+                        if args.keep_mirror == "none" and verify_mr.json_path and os.path.exists(verify_mr.json_path):
+                            safe_unlink(verify_mr.json_path)
+                            verify_mr.json_path = ""
+
+                    # 4) Benchmark forward circuit: run state+hist at every threshold with successful mirror (rc=0, metric_value set).
+                    # Build/setup timing comes from the 1-shot state forward row (shots_state), not from probe_wall_s.
+                    tested_forward_thresholds = _forward_thresholds_from_mirror(mirror_runs, selected_thr, ladder)
+                    forward_runs_by_threshold: Dict[int, Tuple[RunnerRun, RunnerRun]] = {}
+                    for thr in tested_forward_thresholds:
+                        rr_s = run_runner_once(
+                            qasm_path=qasm_path,
+                            backend=backend,
+                            precision=precision,
+                            threshold=int(thr),
+                            shots=int(args.shots_state),
+                            topk=int(args.topk),
+                            out_dir=args.out_dir,
+                            quiet=bool(args.quiet_cmd),
+                            timeout_s=args.timeout_runner_s,
+                        )
+                        rr_h = run_runner_once(
+                            qasm_path=qasm_path,
+                            backend=backend,
+                            precision=precision,
+                            threshold=int(thr),
+                            shots=int(args.shots_hist),
+                            topk=int(args.topk),
+                            out_dir=args.out_dir,
+                            quiet=bool(args.quiet_cmd),
+                            timeout_s=args.timeout_runner_s,
+                        )
+                        forward_runs_by_threshold[thr] = (rr_s, rr_h)
+                        if f_run_record and features_ref_rel:
+                            fidelity_metric_source = "explicit" if args.mirror_metric_explicit else "default"
+                            for rr in (rr_s, rr_h):
+                                rr_status, rr_error_code, rr_error_detail = classify_attempt_status(
+                                    rr.note, rr.returncode, rr.error_message
+                                )
+                                rec = build_run_record(
+                                    content_hash=qasm_hash,
+                                    features_ref=features_ref_rel,
+                                    fidelity_metric_source=fidelity_metric_source,
+                                    created_utc=utc_now_iso(),
+                                    qasm_file=qasm_file,
+                                    qasm_path=qasm_abs,
+                                    backend=backend,
+                                    backend_id=backend,
+                                    precision=precision,
+                                    env_id="",
+                                    run_kind="forward_runner_execution",
+                                    status=rr_status,
+                                    selected_threshold=int(selected_thr),
+                                    threshold=rr.threshold,
+                                    shots=rr.shots,
+                                    runtime_wall_s=rr.run_wall_s,
+                                    fidelity=rr.sdk_get_fidelity,
+                                    fidelity_metric="sdk_get_fidelity",
+                                    returncode=rr.returncode,
+                                    peak_rss_mb=rr.peak_rss_mb,
+                                    runner_wall_s=rr.run_wall_s,
+                                    shots_runner=rr.shots,
+                                    error_code=rr_error_code,
+                                    error_detail=rr_error_detail,
+                                    error_type=rr_error_code,
+                                    error_message=rr.error_message,
+                                )
+                                f_run_record.write(json.dumps(rec, sort_keys=True) + "\n")
+                                f_run_record.flush()
+
+                    # Primary pair for report/CSV/job_summary: selected threshold only (build/setup = 1-shot state row).
+                    rr_state, rr_hist = forward_runs_by_threshold[selected_thr]
+
+                    if rr_state.returncode != 0 or rr_hist.returncode != 0:
+                        if legacy_status == "ok":
+                            legacy_status = "runner_failed"
+                        note = (note + ";" if note else "") + f"runner_rc_state={rr_state.returncode},runner_rc_hist={rr_hist.returncode}"
+
+                    # Runner retention policy: apply to all forward runs (all tested thresholds).
+                    for _thr, (r_s, r_h) in forward_runs_by_threshold.items():
+                        if args.keep_runner == "none":
+                            if r_s.json_path and os.path.exists(r_s.json_path):
+                                safe_unlink(r_s.json_path)
+                            if r_h.json_path and os.path.exists(r_h.json_path):
+                                safe_unlink(r_h.json_path)
+                        elif args.keep_runner == "hist-only":
+                            if r_s.json_path and os.path.exists(r_s.json_path):
+                                safe_unlink(r_s.json_path)
+
+                    per_shot_est = None
+                    if (
+                        rr_state.run_wall_s is not None
+                        and rr_hist.run_wall_s is not None
+                        and int(args.shots_hist) > int(args.shots_state)
+                    ):
+                        denom = float(int(args.shots_hist) - int(args.shots_state))
+                        per_shot_est = (float(rr_hist.run_wall_s) - float(rr_state.run_wall_s)) / denom
+
+                    # Canonical summary status/error mapping for output records/CSV.
+                    status = "ok"
+                    error_code = ""
+                    error_detail = ""
+                    if legacy_status == "mirror_failed":
+                        mr_fail = next((x for x in mirror_runs if x.returncode != 0), None)
+                        if mr_fail is not None:
+                            status, error_code, error_detail = classify_attempt_status(
+                                mr_fail.note, mr_fail.returncode, mr_fail.error_message
+                            )
+                        else:
+                            status, error_code, error_detail = "runner_error", "runner_error", note
+                    elif legacy_status == "runner_failed":
+                        rr_fail = rr_state if rr_state.returncode != 0 else rr_hist
+                        status, error_code, error_detail = classify_attempt_status(
+                            rr_fail.note, rr_fail.returncode, rr_fail.error_message
+                        )
+                    elif legacy_status == "no_threshold_met":
+                        status = "ok"
+                        error_code = "threshold_target_not_met"
+                        error_detail = note
+
+                    entry: Dict[str, Any] = {
+                        "created_utc": utc_now_iso(),
+                        "qasm": {
+                            "file": qasm_file,
+                            "path": qasm_abs,
+                            "sha256": qasm_hash,
+                            "bytes": int(qasm_bytes),
+                            "features": feats,
+                        },
+                        "backend": backend,
+                        "precision": precision,
+                        "selection": {
+                            "mirror_metric": args.mirror_metric,
+                            "mirror_mode_resolved": mirror_mode_sel,
+                            "target": target,
+                            "selected_threshold": int(selected_thr),
+                            "selected_mirror_metric_value": None if sel_mr is None else sel_mr.metric_value,
+                            "stop_when": args.stop_when,
+                        },
+                        "mirror_sweep": [
+                            {
+                                "threshold": mr.threshold,
+                                "metric_value": mr.metric_value,
+                                "p_return_zero": mr.p_return_zero,
+                                "sdk_get_fidelity": mr.sdk_get_fidelity,
+                                "sdk_peakmem0": mr.sdk_peakmem0,
+                                "run_wall_s": mr.run_wall_s,
+                                "peak_rss_mb": mr.peak_rss_mb,
+                                "returncode": mr.returncode,
+                                "note": mr.note,
+                                "json_path": mr.json_path if (mr.json_path in keep_mirror_paths) else "",
+                                "probe": None if pr is None else {
+                                    "shots": pr.shots,
+                                    "run_wall_s": pr.run_wall_s,
+                                    "peak_rss_mb": pr.peak_rss_mb,
+                                    "returncode": pr.returncode,
+                                    "note": pr.note,
+                                },
+                            }
+                            for mr, pr in zip(mirror_runs, probe_runs)
+                        ],
+                        "mirror_verify": None if verify_mr is None else {
+                            "threshold": verify_mr.threshold,
+                            "p_return_zero": verify_mr.p_return_zero,
+                            "sdk_get_fidelity": verify_mr.sdk_get_fidelity,
+                            "sdk_peakmem0": verify_mr.sdk_peakmem0,
+                            "run_wall_s": verify_mr.run_wall_s,
+                            "peak_rss_mb": verify_mr.peak_rss_mb,
+                            "returncode": verify_mr.returncode,
+                            "note": verify_mr.note,
+                            "json_path": verify_mr.json_path,
+                        },
+                        "bench": {
+                            # Build/setup timing: state_run.run_wall_s (1-shot forward row), not probe_wall_s.
+                            "shots_state": int(args.shots_state),
+                            "shots_hist": int(args.shots_hist),
+                            "state_run": {
+                                "threshold": rr_state.threshold,
+                                "shots": rr_state.shots,
+                                "run_wall_s": rr_state.run_wall_s,
+                                "peak_rss_mb": rr_state.peak_rss_mb,
+                                "sdk_get_fidelity": rr_state.sdk_get_fidelity,
+                                "sdk_peakmem0": rr_state.sdk_peakmem0,
+                                "returncode": rr_state.returncode,
+                                "note": rr_state.note,
+                                "json_path": rr_state.json_path,
+                            },
+                            "hist_run": {
+                                "threshold": rr_hist.threshold,
+                                "shots": rr_hist.shots,
+                                "run_wall_s": rr_hist.run_wall_s,
+                                "peak_rss_mb": rr_hist.peak_rss_mb,
+                                "unique_outcomes": rr_hist.unique_outcomes,
+                                "tail_mass": rr_hist.tail_mass,
+                                "sdk_get_fidelity": rr_hist.sdk_get_fidelity,
+                                "sdk_peakmem0": rr_hist.sdk_peakmem0,
+                                "returncode": rr_hist.returncode,
+                                "note": rr_hist.note,
+                                "json_path": rr_hist.json_path,
+                            },
+                            "derived": {
+                                "per_shot_s_est": per_shot_est,
+                            },
+                        },
+                        "status": status,
+                        "legacy_status": legacy_status,
+                        "error_code": error_code,
+                        "error_detail": error_detail,
+                        "note": note,
+                    }
+                    report["runs"].append(entry)
+
+                    if f_run_record and features_ref_rel:
+                        fidelity_metric_source = "explicit" if args.mirror_metric_explicit else "default"
+                        rec = build_run_record(
+                            content_hash=qasm_hash,
+                            features_ref=features_ref_rel,
+                            fidelity_metric_source=fidelity_metric_source,
+                            created_utc=entry["created_utc"],
+                            qasm_file=qasm_file,
+                            qasm_path=qasm_abs,
+                            backend=backend,
+                            backend_id=backend,
+                            precision=precision,
+                            env_id="",
+                            run_kind="job_summary",
+                            status=status,
+                            selected_threshold=selected_thr,
+                            returncode=None,
+                            peak_rss_mb=rr_hist.peak_rss_mb,
+                            mirror_wall_s=None if sel_mr is None else sel_mr.run_wall_s,
+                            probe_wall_s=None if sel_probe is None else sel_probe.run_wall_s,  # optional probe run; build = 1-shot state row
+                            runner_wall_s=rr_hist.run_wall_s,
+                            shots_mirror=int(args.shots_mirror),
+                            shots_runner=int(args.shots_hist),
+                            error_code=error_code,
+                            error_detail=error_detail,
+                            error_type=error_code,
+                            error_message=error_detail,
+                        )
+                        f_run_record.write(json.dumps(rec, sort_keys=True) + "\n")
+                        f_run_record.flush()
+
+                    mv = None if sel_mr is None else sel_mr.metric_value
+                    t_m = None if sel_mr is None else sel_mr.run_wall_s
+                    n_q = feats.get("qasm_n_qubits_decl", None)
+
+                    verify_p0 = None if verify_mr is None else verify_mr.p_return_zero
+                    verify_str = "" if verify_mr is None else f" verify_p0={fmt_opt(verify_p0,6)}"
+
+                    print(
+                        f"[summary {job_idx:03d}/{total_jobs:03d}] "
+                        f"{qasm_file} n={fmt_int(n_q)} "
+                        f"backend={backend} prec={precision} thr={selected_thr} "
+                        f"{args.mirror_metric}={fmt_opt(mv,8)} mirror_wall_s={fmt_opt(t_m,3)}s "
+                        f"probe_wall_s={fmt_opt(rr_state.run_wall_s,3)}s "
+                        f"runner_wall_s={fmt_opt(rr_hist.run_wall_s,3)}s "
+                        f"mem={fmt_opt(rr_hist.peak_rss_mb,1)}MB "
+                        f"status={status}{verify_str}",
+                        flush=True
+                    )
+
+                    # CSV row (legacy + canonical fields)
+                    row = {k: "" for k in csv_fields}
+                    row.update({
+                        "created_utc": entry["created_utc"],
+                        "qasm_file": qasm_file,
+                        "qasm_path": qasm_abs,
+                        "qasm_sha256": qasm_hash,
+                        "qasm_bytes": qasm_bytes,
+                        "backend": backend,
+                        "backend_id": backend,
+                        "precision": precision,
+                        "env_id": "",
+                        "mirror_metric": args.mirror_metric,
+                        "target": target,
+                        "selected_threshold": selected_thr,
+                        "mirror_metric_selected": "" if mv is None else mv,
+                        "mirror_p_return_zero_selected": "" if (sel_mr is None or sel_mr.p_return_zero is None) else sel_mr.p_return_zero,
+                        "mirror_sdk_get_fidelity_selected": "" if (sel_mr is None or sel_mr.sdk_get_fidelity is None) else sel_mr.sdk_get_fidelity,
+                        "mirror_sdk_peakmem0_selected": "" if (sel_mr is None or sel_mr.sdk_peakmem0 is None) else sel_mr.sdk_peakmem0,
+                        "mirror_run_wall_s_selected": "" if t_m is None else t_m,
+                        "mirror_peak_rss_mb_selected": "" if (sel_mr is None or sel_mr.peak_rss_mb is None) else sel_mr.peak_rss_mb,
+                        "probe_shots": int(args.shots_probe) if int(args.shots_probe) > 0 else "",
+                        "probe_run_wall_s_selected": "" if (sel_probe is None or sel_probe.run_wall_s is None) else sel_probe.run_wall_s,
+                        "probe_peak_rss_mb_selected": "" if (sel_probe is None or sel_probe.peak_rss_mb is None) else sel_probe.peak_rss_mb,
+                        "runner_t_state_s": "" if rr_state.run_wall_s is None else rr_state.run_wall_s,
+                        "runner_t_hist_s": "" if rr_hist.run_wall_s is None else rr_hist.run_wall_s,
+                        "runner_shots_state": int(args.shots_state),
+                        "runner_shots_hist": int(args.shots_hist),
+                        "runner_per_shot_s_est": "" if per_shot_est is None else per_shot_est,
+                        "runner_hist_unique_outcomes": "" if rr_hist.unique_outcomes is None else rr_hist.unique_outcomes,
+                        "runner_hist_tail_mass": "" if rr_hist.tail_mass is None else rr_hist.tail_mass,
+                        "runner_state_sdk_get_fidelity": "" if rr_state.sdk_get_fidelity is None else rr_state.sdk_get_fidelity,
+                        "runner_state_sdk_peakmem0": "" if rr_state.sdk_peakmem0 is None else rr_state.sdk_peakmem0,
+                        "runner_hist_sdk_get_fidelity": "" if rr_hist.sdk_get_fidelity is None else rr_hist.sdk_get_fidelity,
+                        "runner_hist_sdk_peakmem0": "" if rr_hist.sdk_peakmem0 is None else rr_hist.sdk_peakmem0,
+                        "runner_state_json": rr_state.json_path,
+                        "runner_hist_json": rr_hist.json_path,
+                        "status": status,
+                        "error_code": error_code,
+                        "error_detail": error_detail,
+                        "mirror_wall_s": "" if t_m is None else t_m,
+                        "probe_wall_s": "" if (sel_probe is None or sel_probe.run_wall_s is None) else sel_probe.run_wall_s,
+                        "runner_wall_s": "" if rr_hist.run_wall_s is None else rr_hist.run_wall_s,
+                        "shots_mirror": int(args.shots_mirror),
+                        "shots_runner": int(args.shots_hist),
+                        "peak_rss_mb": "" if rr_hist.peak_rss_mb is None else rr_hist.peak_rss_mb,
+                        "note": note,
+                    })
+                    row.update(feats)
+                    writer.writerow(row)
+
+    finally:
+        f_csv.close()
+        if f_run_record is not None:
+            f_run_record.close()
+
+    with open(args.report_json, "w", encoding="utf-8") as f_out:
+        json.dump(report, f_out, indent=2, sort_keys=True)
+
+    print("===== done =====", flush=True)
+    print(f"[ok] wrote report:   {args.report_json}", flush=True)
+    print(f"[ok] wrote dataset:  {args.dataset_csv}", flush=True)
+    if run_record_path:
+        print(f"[ok] appended run records: {run_record_path}", flush=True)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except SystemExit:
+        raise
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        die(f"Unhandled exception: {e}")
+