Add a portable metadata record so collection and verdict can run apart

`collect_metadata_record` returns a JSON-safe record carrying an image's
provenance metadata regions -- never its pixels -- and the existing
`evidence_from_metadata_record` + `identify_from_evidence` build the verdict
from it without opening the file. The contract is equality with
`identify(path, metadata only)`, verified over the tracked fixtures and over a
local corpus of 3,478 images (every file carrying a rare signal, plus a random
slice): zero differences.

Three placements defeated earlier drafts and each is now a rule with a test:
the `scan_head` buffer is the head CONCATENATED with late metadata, so a
structural walk must read the raw head instead; Samsung splits its evidence
between a post-EOI trailer and the coded scan; and PIL's info keys must be
emitted in the file path's candidate order, since the first token match wins.

Also fix a real detection gap found while establishing that equality: a label
the decoder can read but a raw byte scan cannot -- a compressed PNG `zTXt`
packet, or a WebP XMP chunk past the scan window -- was invisible to
`identify`. Eight corpus files carrying a China TC260 AIGC label or an IPTC
"Made with AI" tag were reported as no signal at all.

`scripts/detection_timing.py` and its report script measure the metadata path
per method; they write outside the repository and are read-only over a dataset.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

scripts/detection_timing.py

@@ -0,0 +1,239 @@
+"""Per-method wall time for metadata extraction and the verdict built on it.
+
+WHY THIS EXISTS
+  The detection path is documented by CAPABILITY -- which signals it reads, in what
+  order, with what confidence -- but not by COST. Batch throughput and the question
+  "which probe dominates, and does it depend on container or on file size" have never
+  been measured.
+
+WHAT IT MEASURES
+  Only the file-backed half: metadata extraction, then the verdict evaluated on the
+  extracted evidence. The pixel-backed detectors are deliberately out of scope.
+
+  COLD pass: one measurement on a file the process has never touched --
+  ``extract_provenance_evidence``. Only the first read of a file is genuinely cold,
+  so it buys exactly one number, and that is the one a single-shot run pays.
+
+  WARM pass, with the filesystem cache now hot:
+    1. ``extract_provenance_evidence`` as a whole.
+    2. Its nine components, timed IN THE ORDER the dataclass constructs them and with
+       the per-file caches cleared once beforehand -- so ``extract_c2pa_info`` carries
+       the Rust manifest reader and the later ``get_ai_metadata`` sees the same warm
+       cache it sees in production. Timing them in any other order moves that cost to
+       a different row and flatters whichever ran second.
+    3. ``identify_from_evidence``: pure verdict logic, the source is never reopened.
+    4. ``identify(check_visible=False, check_invisible=False)`` -- extraction plus
+       verdict as one call, the cross-check that 1 + 3 is the whole metadata path.
+
+  Every ``@lru_cache`` in the metadata and C2PA modules is cleared before each timed
+  unit. Without that the second measurement of a file answers from the memo and
+  reports a cost of zero -- the caches are keyed on (path, mtime, size) and this
+  script reads each file several times.
+
+READING IT
+  Component times do NOT sum to the ``extract_provenance_evidence`` total for free:
+  they come from a separate cache-cleared run, so the sum is a cross-check. A gap
+  means a component is missing from the list. Both numbers are written.
+
+DATA SAFETY
+  Read-only over a local dataset. Writes only to the given output prefix, which
+  belongs outside the repository.
+
+    uv run python scripts/detection_timing.py data/spaces/originals .local-eval/timing/run
+    uv run python scripts/detection_timing.py <dataset> <prefix> --limit 200
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from remove_ai_watermarks import identify as identify_mod
+from remove_ai_watermarks import metadata as metadata_mod
+from remove_ai_watermarks._internal import c2pa as c2pa_mod
+
+log = logging.getLogger(__name__)
+
+SUPPORTED = frozenset({".png", ".jpg", ".jpeg", ".webp", ".heic", ".heif", ".avif"})
+
+# Timed in the order ``ProvenanceEvidence`` is constructed in ``identify.py``. The
+# report script imports this to label its columns, so the order is the contract.
+COMPONENTS: tuple[tuple[str, Callable[[Path], Any]], ...] = (
+    ("c2pa_info", c2pa_mod.extract_c2pa_info),
+    ("ai_metadata", metadata_mod.get_ai_metadata),
+    ("scan_head", lambda p: metadata_mod.scan_head(p, identify_mod._SCAN_BYTES)),
+    ("iptc_ai_system", metadata_mod.iptc_ai_system),
+    ("aigc_label", metadata_mod.aigc_label),
+    ("exif_generator", metadata_mod.exif_generator),
+    ("xai_signature", metadata_mod.xai_signature),
+    ("huggingface_job", metadata_mod.huggingface_job),
+    ("samsung_genai", metadata_mod.samsung_genai),
+)
+
+
+def _cache_clearers() -> tuple[Callable[[], None], ...]:
+    """Every per-file memo in the metadata path, found by attribute, not by name list.
+
+    A hand-written list silently goes stale the next time a probe gains a cache, and a
+    stale entry shows up as a suspiciously fast row rather than as an error.
+    """
+    found: list[Callable[[], None]] = []
+    for module in (metadata_mod, c2pa_mod):
+        for name in dir(module):
+            clear = getattr(getattr(module, name, None), "cache_clear", None)
+            if callable(clear):
+                found.append(clear)
+    return tuple(found)
+
+
+_CLEARERS = _cache_clearers()
+
+
+def _clear() -> None:
+    for clear in _CLEARERS:
+        clear()
+
+
+def _ms(fn: Callable[[], Any]) -> tuple[float, Any]:
+    """Wall time in milliseconds plus the call's result."""
+    start = time.perf_counter_ns()
+    value = fn()
+    return (time.perf_counter_ns() - start) / 1e6, value
+
+
+def _pixel_geometry(path: Path) -> tuple[str | None, int | None, int | None]:
+    """Container format and pixel dimensions from the header alone."""
+    try:
+        from PIL import Image
+
+        with Image.open(path) as img:
+            return img.format, img.width, img.height
+    except Exception:  # unreadable or an unsupported container
+        return None, None, None
+
+
+def _warm_breakdown(path: Path, row: dict[str, Any]) -> None:
+    """Fill ``row`` with the warm-cache per-method breakdown."""
+    _clear()
+    row["extract_evidence_ms"], evidence = _ms(lambda: identify_mod.extract_provenance_evidence(path))
+
+    _clear()
+    component_sum = 0.0
+    for name, fn in COMPONENTS:
+        elapsed, _ = _ms(lambda fn=fn: fn(path))
+        row[f"meta_{name}_ms"] = elapsed
+        component_sum += elapsed
+    row["meta_components_sum_ms"] = component_sum
+
+    row["verdict_from_evidence_ms"], report = _ms(lambda: identify_mod.identify_from_evidence(evidence))
+
+    _clear()
+    row["identify_metadata_only_ms"], full = _ms(
+        lambda: identify_mod.identify(path, check_visible=False, check_invisible=False)
+    )
+
+    row["scan_bytes"] = len(evidence.scan)
+    row["has_c2pa"] = bool(evidence.c2pa_info)
+    row["has_ai_metadata"] = bool(evidence.ai_metadata)
+    row["is_ai_generated"] = full.is_ai_generated
+    row["confidence"] = full.confidence
+    row["platform"] = full.platform
+    row["signals"] = [signal.name for signal in full.signals]
+    # The two verdict paths must agree; a mismatch means the breakdown timed a
+    # different code path than the end-to-end call and the rows are not comparable.
+    row["verdict_agrees"] = (report.confidence, report.platform) == (full.confidence, full.platform)
+
+
+def _measure(path: Path) -> dict[str, Any]:
+    row: dict[str, Any] = {"path": str(path), "ext": path.suffix.lower()}
+    try:
+        row["bytes"] = path.stat().st_size
+    except OSError as exc:
+        return {**row, "error": f"stat: {exc}"}
+
+    # COLD first: this is the only moment the file is untouched by this process.
+    _clear()
+    try:
+        row["cold_extract_evidence_ms"], _ = _ms(lambda: identify_mod.extract_provenance_evidence(path))
+    except Exception as exc:
+        return {**row, "error": f"cold extract: {type(exc).__name__}: {exc}"}
+
+    row["format"], row["width"], row["height"] = _pixel_geometry(path)
+    width, height = row["width"], row["height"]
+    row["megapixels"] = round(width * height / 1e6, 3) if width and height else None
+
+    try:
+        _warm_breakdown(path, row)
+    except Exception as exc:
+        row["error"] = f"warm pass: {type(exc).__name__}: {exc}"
+    return row
+
+
+def _iter_images(root: Path) -> Iterator[Path]:
+    for path in sorted(root.rglob("*")):
+        if path.is_file() and path.suffix.lower() in SUPPORTED:
+            yield path
+
+
+def _done_paths(out_path: Path) -> set[str]:
+    """Paths already recorded, so a long run resumes instead of restarting."""
+    if not out_path.exists():
+        return set()
+    done: set[str] = set()
+    with out_path.open(encoding="utf-8") as handle:
+        for line in handle:
+            try:
+                done.add(json.loads(line)["path"])
+            except (ValueError, KeyError):
+                continue
+    return done
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("dataset", type=Path, help="directory of images, scanned recursively")
+    parser.add_argument("out_prefix", type=Path, help="output prefix; writes <prefix>.jsonl")
+    parser.add_argument("--limit", type=int, default=0, help="stop after N files (0 = all)")
+    parser.add_argument("--progress-every", type=int, default=200)
+    args = parser.parse_args()
+
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(message)s")
+    out_path = args.out_prefix.with_suffix(".jsonl")
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    done = _done_paths(out_path)
+    if done:
+        log.info("resuming: %d files already recorded", len(done))
+
+    processed = 0
+    started = time.monotonic()
+    with out_path.open("a", encoding="utf-8") as handle:
+        for path in _iter_images(args.dataset):
+            if str(path) in done:
+                continue
+            row = _measure(path)
+            handle.write(json.dumps(row, ensure_ascii=False, default=str) + "\n")
+            handle.flush()
+            processed += 1
+            if processed % args.progress_every == 0:
+                log.info("%d files, %.2f files/s", processed, processed / (time.monotonic() - started))
+            if args.limit and processed >= args.limit:
+                break
+
+    elapsed = time.monotonic() - started
+    rate = processed / max(elapsed, 1e-9)
+    log.info("done: %d files in %.1f s (%.2f files/s) -> %s", processed, elapsed, rate, out_path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/detection_timing_report.py

@@ -0,0 +1,232 @@
+"""Aggregate ``detection_timing.py`` records into per-method, per-segment tables.
+
+WHAT IT PRODUCES
+  Reading it back: the per-file JSONL is one row per image with a millisecond field
+  per method. This collapses it into percentiles per method, then repeats that per
+  segment -- container, megapixels, file size, C2PA presence, verdict confidence --
+  because a single median hides a path whose cost is carried entirely by one
+  container or by the files that actually have a manifest.
+
+  Writes ``<prefix>_summary.csv`` (long form: segment_kind, segment, method, n, p50,
+  p90, p99, mean) and prints a markdown report.
+
+  Percentiles are computed by nearest-rank on the sorted sample, not interpolated:
+  every reported number is a time some real file actually took.
+
+DATA SAFETY
+  Reads and writes only the given prefix, which belongs outside the repository.
+
+    uv run python scripts/detection_timing_report.py .local-eval/timing/full
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import math
+import statistics
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from detection_timing import COMPONENTS as _TIMED
+
+# Taken from the script that WROTE the rows, in its order, so a probe added, removed
+# or reordered there cannot silently leave a column missing or mislabelled here.
+COMPONENTS = tuple(name for name, _ in _TIMED)
+METHODS = (
+    ("cold_extract_evidence_ms", "extract_provenance_evidence (cold)"),
+    ("extract_evidence_ms", "extract_provenance_evidence (warm)"),
+    *((f"meta_{name}_ms", f"  {name}") for name in COMPONENTS),
+    ("meta_components_sum_ms", "  (sum of components)"),
+    ("verdict_from_evidence_ms", "identify_from_evidence (verdict)"),
+    ("identify_metadata_only_ms", "identify(metadata only), end to end"),
+)
+# Median-only columns in the per-segment tables; the full percentile set goes to the CSV.
+HEADLINE_LABELS = (
+    ("extract_evidence_ms", "extract p50"),
+    ("verdict_from_evidence_ms", "verdict p50"),
+    ("identify_metadata_only_ms", "end-to-end p50"),
+)
+HEADLINE = tuple(key for key, _ in HEADLINE_LABELS)
+
+
+def _bucket(value: float | None, edges: tuple[float, ...], labels: tuple[str, ...]) -> str:
+    if value is None:
+        return "unknown"
+    for edge, label in zip(edges, labels, strict=False):
+        if value < edge:
+            return label
+    return labels[-1]
+
+
+SEGMENTS: tuple[tuple[str, Callable[[dict[str, Any]], str]], ...] = (
+    ("container", lambda r: str(r.get("format") or "unknown")),
+    (
+        "megapixels",
+        lambda r: _bucket(r.get("megapixels"), (1, 4, 12), ("<1 MP", "1-4 MP", "4-12 MP", ">12 MP")),
+    ),
+    (
+        "file size",
+        lambda r: _bucket(
+            (r["bytes"] / 1e6) if r.get("bytes") is not None else None,
+            (1, 5, 20),
+            ("<1 MB", "1-5 MB", "5-20 MB", ">20 MB"),
+        ),
+    ),
+    ("c2pa", lambda r: "with C2PA" if r.get("has_c2pa") else "no C2PA"),
+    ("verdict", lambda r: f"confidence={r.get('confidence') or 'n/a'}"),
+)
+
+
+def _numeric(records: list[dict[str, Any]], key: str) -> list[float]:
+    """The numeric values of ``key``, skipping rows where it is absent or non-numeric.
+
+    One definition of "counts as a measurement", so the printed table and the CSV can
+    never disagree about which rows a method was measured on.
+    """
+    return [float(r[key]) for r in records if isinstance(r.get(key), (int, float))]
+
+
+def _percentile(sorted_values: list[float], q: float) -> float:
+    """Nearest-rank percentile: the reported value is one a real file produced."""
+    index = max(0, math.ceil(q * len(sorted_values)) - 1)
+    return sorted_values[index]
+
+
+def _stats(values: list[float]) -> dict[str, float | int]:
+    ordered = sorted(values)
+    return {
+        "n": len(ordered),
+        "p50": _percentile(ordered, 0.50),
+        "p90": _percentile(ordered, 0.90),
+        "p99": _percentile(ordered, 0.99),
+        "mean": statistics.fmean(ordered),
+    }
+
+
+def _rows(path: Path) -> Iterator[dict[str, Any]]:
+    with path.open(encoding="utf-8") as handle:
+        for line in handle:
+            try:
+                yield json.loads(line)
+            except ValueError:  # a truncated tail while the run is still writing
+                continue
+
+
+def _table(rows: list[dict[str, Any]], methods: tuple[tuple[str, str], ...]) -> list[str]:
+    out = ["| method | n | p50 | p90 | p99 | mean |", "|---|---:|---:|---:|---:|---:|"]
+    for key, label in methods:
+        values = _numeric(rows, key)
+        if not values:
+            continue
+        s = _stats(values)
+        out.append(f"| {label} | {s['n']} | {s['p50']:.3f} | {s['p90']:.3f} | {s['p99']:.3f} | {s['mean']:.3f} |")
+    return out
+
+
+def _correlation(rows: list[dict[str, Any]], x_key: str, y_key: str) -> float | None:
+    both = [r for r in rows if isinstance(r.get(x_key), (int, float)) and isinstance(r.get(y_key), (int, float))]
+    if len(both) < 3:
+        return None
+    xs = _numeric(both, x_key)
+    ys = _numeric(both, y_key)
+    try:
+        return statistics.correlation(xs, ys)
+    except statistics.StatisticsError:  # a constant column has no correlation
+        return None
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("prefix", type=Path, help="prefix given to detection_timing.py")
+    args = parser.parse_args()
+
+    jsonl = args.prefix.with_suffix(".jsonl")
+    all_rows = list(_rows(jsonl))
+    failed = [r for r in all_rows if "error" in r]
+    rows = [r for r in all_rows if "error" not in r]
+    if not rows:
+        print(f"no usable records in {jsonl}")
+        return 1
+
+    disagreed = [r for r in rows if r.get("verdict_agrees") is False]
+
+    lines = [
+        f"# Detection timing over {len(rows)} images",
+        "",
+        f"Source: `{jsonl}`. Failed rows: {len(failed)}. Verdict-path mismatches: {len(disagreed)}.",
+        "",
+        "All times in milliseconds. Percentiles are nearest-rank.",
+        "",
+        "## Whole corpus",
+        "",
+        *_table(rows, METHODS),
+        "",
+    ]
+
+    csv_rows: list[dict[str, Any]] = []
+    for key, label in METHODS:
+        values = _numeric(rows, key)
+        if values:
+            csv_rows.append({"segment_kind": "all", "segment": "all", "method": label.strip(), **_stats(values)})
+
+    for kind, classify in SEGMENTS:
+        groups: dict[str, list[dict[str, Any]]] = defaultdict(list)
+        for row in rows:
+            groups[classify(row)].append(row)
+        lines += [f"## By {kind}", ""]
+        header = ["| segment | n | " + " | ".join(label for _, label in HEADLINE_LABELS) + " |"]
+        header.append("|---|---:|" + "---:|" * len(HEADLINE))
+        lines += header
+        for segment, group in sorted(groups.items(), key=lambda item: -len(item[1])):
+            cells = []
+            for key in HEADLINE:
+                values = _numeric(group, key)
+                cells.append(f"{_percentile(sorted(values), 0.5):.2f}" if values else "-")
+            lines.append(f"| {segment} | {len(group)} | " + " | ".join(cells) + " |")
+            for key, label in METHODS:
+                values = _numeric(group, key)
+                if values:
+                    csv_rows.append(
+                        {"segment_kind": kind, "segment": segment, "method": label.strip(), **_stats(values)}
+                    )
+        lines.append("")
+
+    corr = _correlation(rows, "scan_bytes", "verdict_from_evidence_ms")
+    corr_size = _correlation(rows, "bytes", "extract_evidence_ms")
+    lines += [
+        "## Scaling",
+        "",
+        f"- verdict time vs scan-buffer size: r = {corr:.3f}" if corr is not None else "- verdict correlation: n/a",
+        (
+            f"- extraction time vs file size: r = {corr_size:.3f}"
+            if corr_size is not None
+            else "- extraction correlation: n/a"
+        ),
+        "",
+    ]
+
+    summary_csv = args.prefix.with_name(args.prefix.name + "_summary.csv")
+    columns = ["segment_kind", "segment", "method", "n", "p50", "p90", "p99", "mean"]
+    with summary_csv.open("w", encoding="utf-8", newline="") as handle:
+        writer = csv.DictWriter(handle, fieldnames=columns)
+        writer.writeheader()
+        writer.writerows(csv_rows)
+
+    report = "\n".join(lines)
+    args.prefix.with_name(args.prefix.name + "_report.md").write_text(report + "\n", encoding="utf-8")
+    print(report)
+    print(f"\nwrote {summary_csv}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())