Fix SynthID provenance evidence and release 0.26.1

Make the video SynthID operating point measurable and hard to move silently

.claude/rules/development.md

@@ -0,0 +1,130 @@
+---
+globs: ["src/**/*.py", "tests/**/*.py", "scripts/**/*.py", "pyproject.toml", "uv.lock", "maintain.sh", ".github/workflows/*.yml"]
+description: Command contracts, project gate, typing boundaries, model-adjacent test invariants, and the detection-path measurement rule.
+---
+
+# Development invariants
+
+## Command contracts
+
+Every single-image command declares `source` with `dir_okay=False`; `batch` declares its directory with `file_okay=False`. Keep `tests/test_cli_robustness.py::TestDirectoryInputIsRejected` as the regression guard.
+
+Exit-code and no-signal behavior is a public contract. Read the command-line section of [`../../docs/module-internals.md`](../../docs/module-internals.md) before changing it.
+
+Do not add an option whose only outcome is an error. Model id, step count and CFG are fixed by the profile, so none of them is a parameter of the CLI, `InvisibleEngine`, or `WatermarkRemover` -- they were accepted-then-rejected for a while, which moved the failure several frames below the caller and advertised choices the pinned stack cannot honor. If a value cannot vary, delete the knob rather than validating it.
+
+`device` is the deliberate exception and stays a library parameter: `None`/`"auto"` detect, `"cuda"` pins without detecting, and everything else raises at construction. It is not a CLI option, because the only value a user could usefully type is the one auto-detection already finds.
+
+The same rule applies to install hints: name the extra that actually makes the command work (`qwen-zimage`, not `diffusion`), and keep the printed command shell-quoted -- bare `pkg[extra]` is a glob in zsh.
+
+## Local gate
+
+Run `bash maintain.sh` from the repository root. The authoritative type gate is scoped to `src/`; full-project Pyright can exhaust Node memory on the ML dependency graph.
+
+Boundary modules for cv2, Torch, and Diffusers may carry narrow per-file relaxations for unknown third-party types. Keep pure-logic files strict, preserve the local piexif stub, and fix real errors before widening a pragma.
+
+From a worktree, `uv run` imports the package from the MAIN checkout -- that is where the editable install points. A script measuring a worktree's edit must insert that worktree's `src` at `sys.path[0]` and assert `module.__file__` resolves inside it, or it silently compares unmodified code against itself.
+
+## Model-adjacent tests
+
+Do not classify an entire module as untestable because its main path downloads a model. Keep pure behavior covered without downloads, including:
+
+- target-size selection in `test_invisible_engine.py`;
+- unsharp and adaptive-polish helpers in `test_humanizer.py`;
+- tiling geometry and blending in `test_tiling.py`;
+- prompt-embedding cache keying, storage round-trip, and the cross-pipeline reuse
+  that lets a stack load without its text encoder, in `test_qwen_zimage_pipeline.py`;
+- the face stack's dtype, in `test_qwen_zimage_pipeline.py`. A subclass that changes
+  the pipeline dtype for its own global model must not change the inherited face
+  stage's; `sdxl-zimage` shipped doing exactly that and crashed on every image with a
+  face. When one profile inherits another's stage, guard the invariants that stage
+  relies on, not just the code path.
+- the `InvisibleOptions` defaults, in `test_api.py`. When one signature promises to
+  mirror another, compare them field by field rather than pinning the values you happen
+  to know about, so the next field added on one side and not the other fails at the
+  seam. Two of these defaults drifted in practice and neither needed a GPU to catch;
+  the incident is recorded in `docs/module-internals.md`. Keep the comparison free of
+  an exception table: a field that needs one is a field that belongs elsewhere, which
+  is what `force` turned out to be.
+
+A defaults comparison is not a forwarding test, and the two fail differently. Pin the
+VALUE at the seam, not just the name -- `_run_invisible` passed the whole suite with
+`controlnet_conditioning_scale` hardcoded, because nothing asserted the caller's value
+arrived. `test_every_field_arrives_at_the_engine_with_the_caller_s_value` drives the
+real seam with every field set off its default, so one test covers the whole bag
+instead of one assertion per knob.
+
+Count the seams before believing a knob is covered. Each of `force` and
+`controlnet_conditioning_scale` reaches the engine through TWO paths -- `remove_all`
+versus `remove_batch(mode="all")` for the first, `_run_invisible` versus `_batch_engine`
+for the second -- and in both cases guarding one path left the other free to hardcode a
+constant with a green suite. The mode-parametrized guards in
+`TestRemoveBatchLibrary::test_force_reaches_the_scrub_gate_in_every_scrubbing_mode` and
+`TestBatchCommand::test_batch_controlnet_scale_flows_to_the_cached_engine` exist because
+that is what actually happened.
+
+Use availability checks only for paths that actually load large models.
+
+## One measurement, one gate seam
+
+A detector is split into a trust-level-blind scan and a verdict that applies the
+threshold, so `detect` and `detect_both` reach the same numbers by construction. Two
+rules follow, and both were broken in practice before they were written down:
+
+- A per-mark demotion goes in the `_post_gate` hook (or, for a whole-scan precondition
+  like LibLibAI's size floor, in `_scan`) -- never in a `detect` override. An override
+  is invisible to `detect_both`, so the RunningHub and Yuanbao anchor gates silently
+  stopped applying on the arbiter's perception path. `TestSinglePassPerception` is the
+  guard: it asserts `detect_both` equals two `detect` calls field for field.
+- Detection and the removal mask must read ONE sweep. The winning box travels on
+  `TextMarkDetection.match_box` and the registry threads the detection into the mask
+  builder; a mask path that re-runs its own sweep is how the two drift apart.
+
+The C2PA manifest-store JSON is NOT stable across reads: the reader regenerates manifest
+URNs and instance ids. Compare the derived `c2pa_info`, never the raw store.
+
+A third seam reaches the same verdict: `collect_metadata_record` ->
+`evidence_from_metadata_record` -> `identify_from_evidence`, the path a caller uses when
+collection and verdict run on different machines. Its contract is equality with
+`identify(path, check_visible=False, check_invisible=False)` on the same image, and it
+can break from EITHER side -- a region the collector stops walking, or a placement the
+file path learns to read and the record does not. `tests/test_metadata_record.py` pins
+it over the tracked fixtures; a separate local evaluation corpus catches placements the
+fixtures do not cover. Change either side and re-run both.
+
+Before changing anything in the detection path, record the detectors' exact verdicts
+over a local sample first and diff them after. A refactor here is only correct if that
+record is byte-identical, and a green test suite does not establish that on its own. A
+change that is meant to FIX detection is the exception that proves the rule: the diff
+must then be exactly the files you intended to change, named in advance.
+
+## A certified operating point is data, not a constant
+
+The video SynthID default is only meaningful as a row in
+`data/evaluations/video-synthid-oracle.csv`, so
+`test_shipped_defaults_match_a_certified_manifest_row` derives the pin from that
+manifest instead of restating literals. Pinning `noise_std` alone had let `long_side`
+and `fps` -- two thirds of what the oracle was actually shown -- move with a green
+suite.
+
+The certified profile is a perturbation-to-signal ratio, not a bare `noise_std`, so
+the latent scaling factor is gated in `load_video_vae_runtime`, carried on
+`VideoVaeRuntime`, and passed into encode and decode: the validated value and the
+applied value are one measurement. Anything that produces oracle evidence loads
+through that function. `video_synthid_sweep.py` hand-rolled the load and was the one
+path exempt from the gate it exists to feed, which is exactly backwards.
+
+Prove a video-path refactor the same way the detection path is proven, and without
+needing an oracle carrier: build a clip from a tracked fixture with ffmpeg, run the
+engine before and after, and require an identical output sha256. Keep the generated
+media outside the repository.
+
+Frame sampling is compared as `timestamp + 1e-9 >= next_sample_time`, so mutating
+that `>=` to `>` changes nothing and a green suite proves nothing. Mutate the phase
+or the period instead -- starting the accumulator half a period late shifts the
+selection by one frame while keeping the count identical, which is the drift a
+frame-count check cannot see and what
+`test_pairing_follows_the_engine_sampling_rule_not_just_the_frame_count` exists to
+catch.
+
+Environment setup, dependency recovery, CI behavior, and fixture policy: [`../../docs/development.md`](../../docs/development.md).

.env.example

@@ -1,3 +1,3 @@
 # HuggingFace token (optional; only needed for gated/private models)
 # Get yours at: https://huggingface.co/settings/tokens
-HF_TOKEN=
+# HF_TOKEN=

.github/dependabot.yml

@@ -14,6 +14,21 @@ updates:
         update-types:
           - "minor"
           - "patch"
+    # The `all` extra must remain jointly resolvable. These candidates violate
+    # upstream constraints: TrustMark still requires NumPy 1.x, OpenCV 4.12+
+    # requires NumPy 2 on newer Python versions, and this project keeps tokenizers
+    # below 0.23 for the stable Transformers path. Keep Dependabot on the
+    # compatible lines until those constraints move.
+    ignore:
+      - dependency-name: "numpy"
+        versions:
+          - ">=2"
+      - dependency-name: "opencv-python-headless"
+        versions:
+          - ">=4.12"
+      - dependency-name: "tokenizers"
+        versions:
+          - ">=0.23"
 
   - package-ecosystem: "github-actions"
     directory: "/"

.github/workflows/distribute.yml

@@ -1,11 +1,13 @@
 name: Distribute on release
 
 # Fans a published GitHub Release out to the channels that need a nudge.
-# PyPI is handled by publish.yml; conda-forge is handled by its autotick bot.
-# This workflow event-drives the two channels that would otherwise be manual:
+# PyPI is handled by publish.yml; the conda-forge channel is handled by its
+# autotick bot. This workflow updates the repository recipe and event-drives
+# the three channels that would otherwise be manual:
 #   - Homebrew tap: rewrite the formula's url + sha256 to the new sdist.
 #   - HF Space: factory-rebuild so it reinstalls the latest sdist from PyPI.
-# Both wait for the freshly published sdist to appear on PyPI first, since the
+#   - ComfyUI: sync, test, and publish the node against the exact library release.
+# All wait for the freshly published sdist to appear on PyPI first, since the
 # Release event fires in parallel with publish.yml's upload.
 
 on:
@@ -87,6 +89,34 @@ jobs:
           git commit -m "remove-ai-watermarks $VERSION" || { echo "Formula already current"; exit 0; }
           git push
 
+  conda-recipe:
+    needs: resolve
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v7
+        with:
+          ref: main
+      - name: Bump the repository conda recipe
+        env:
+          SHA: ${{ needs.resolve.outputs.sha }}
+          VERSION: ${{ needs.resolve.outputs.version }}
+        run: |
+          set -euo pipefail
+          python scripts/sync_conda_recipe.py --version "$VERSION" --sha256 "$SHA"
+          git diff --check
+          if git diff --quiet -- packaging/conda/recipe.yaml; then
+            echo "Conda recipe already current"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add packaging/conda/recipe.yaml
+          git commit -m "Sync conda recipe with v$VERSION"
+          git push
+
   hf-space:
     needs: resolve
     runs-on: ubuntu-latest
@@ -104,3 +134,75 @@ jobs:
           )
           print("HF Space factory rebuild triggered")
           PY
+
+  comfyui:
+    needs: resolve
+    runs-on: ubuntu-latest
+    steps:
+      - name: Sync and publish the ComfyUI nodes
+        env:
+          GH_TOKEN: ${{ secrets.COMFYUI_RELEASE_TOKEN }}
+        run: |
+          set -euo pipefail
+          repo=wiltodelta/ComfyUI-remove-ai-watermarks
+          workflow=sync-library.yml
+          dispatched_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+          gh workflow run "$workflow" \
+            --repo "$repo" \
+            --ref main \
+            --raw-field library_version="${{ needs.resolve.outputs.version }}"
+
+          run_id=""
+          for attempt in $(seq 1 30); do
+            run_id=$(
+              gh run list \
+                --repo "$repo" \
+                --workflow "$workflow" \
+                --event workflow_dispatch \
+                --limit 10 \
+                --json databaseId,createdAt \
+                | python3 -c '
+          import json
+          import sys
+
+          dispatched_at = sys.argv[1]
+          runs = json.load(sys.stdin)
+          print(next(
+              (run["databaseId"] for run in runs if run["createdAt"] >= dispatched_at),
+              "",
+          ))
+          ' "$dispatched_at"
+            )
+            if [ -n "$run_id" ]; then
+              break
+            fi
+            echo "ComfyUI sync run not visible yet (attempt $attempt), waiting..."
+            sleep 2
+          done
+
+          if [ -z "$run_id" ]; then
+            echo "::error::The dispatched ComfyUI sync run did not appear"
+            exit 1
+          fi
+
+          for attempt in $(seq 1 180); do
+            read -r status conclusion <<< "$(
+              gh run view "$run_id" \
+                --repo "$repo" \
+                --json status,conclusion \
+                --jq '[.status, (.conclusion // "")] | @tsv'
+            )"
+            if [ "$status" = "completed" ]; then
+              if [ "$conclusion" = "success" ]; then
+                echo "ComfyUI sync run $run_id succeeded"
+                exit 0
+              fi
+              echo "::error::ComfyUI sync run $run_id completed with $conclusion"
+              exit 1
+            fi
+            echo "ComfyUI sync run $run_id is $status (attempt $attempt), waiting..."
+            sleep 5
+          done
+          echo "::error::ComfyUI sync run $run_id did not finish in time"
+          exit 1

.github/workflows/test.yml

@@ -44,3 +44,43 @@ jobs:
         run: uv sync --frozen --extra dev
       - name: Run tests
         run: uv run pytest -q
+
+  transport-contract-python-314:
+    name: versioned transport contracts py3.14
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+      - name: Create clean runtime contract environment
+        run: uv venv --python 3.14 .venv-contract
+      - name: Install runtime contract dependencies
+        run: >-
+          uv pip install --python .venv-contract/bin/python
+          ".[pixels,heif]" "numpy>=2,<3" "pytest>=8"
+      - name: Run versioned transport contract tests
+        run: >-
+          .venv-contract/bin/python -m pytest -q
+          tests/test_forensic_metadata.py
+          tests/test_metadata_record.py
+          tests/test_pixel_evidence.py
+
+  video-e2e:
+    name: video full-clip end-to-end
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+      - name: Install ffmpeg
+        run: sudo apt-get update && sudo apt-get install --yes ffmpeg
+      - name: Sync dev environment
+        run: uv sync --frozen --extra dev
+      - name: Run full-clip video test
+        run: >-
+          uv run pytest -vv -o faulthandler_timeout=60
+          tests/test_video.py::TestVideoVisibleFullClip
+          tests/test_video_fidelity_probe.py

.gitignore

@@ -4,6 +4,8 @@ __pycache__/
 *.egg-info/
 dist/
 build/
+tmp/
+.sc/
 
 # Environment secrets
 .env
@@ -18,8 +20,7 @@ Thumbs.db
 *.swp
 *.swo
 
-# SynthID corpus reference fills (synthetic black/white calibration tiles,
-# regenerable; the labeled pos/neg/cleaned images ARE tracked, see README)
+# Generated calibration inputs
 data/synthid_corpus/refs/
 
 # Reference materials
@@ -33,11 +34,7 @@ yolov8n.pt
 .claude/settings.local.json
 .claude/scheduled_tasks.lock
 
-# Visible-watermark alpha calibration. The solid black/gray/white CAPTURES are
-# committed (content-free: a solid colour + the watermark; the source for
-# scripts/visible_alpha_solve.py so the alpha assets are reproducible). The
-# synthetic seeds (regenerable) and any real-content validation download (a real
-# generated scene, kept local for privacy) are NOT committed.
+# Generated calibration inputs and local evaluation artifacts
 data/doubao_capture/seeds/
 data/jimeng_capture/seeds/
 data/jimeng_capture/captures/jimeng_content_*.png
@@ -46,13 +43,8 @@ data/gemini_capture/captures/gemini_content_*.png
 data/samsung_capture/seeds/
 data/samsung_capture/captures/samsung_content_*
 
-# Leftover GFPGAN weights dir from the retired face-restore experiments
-# (GFPGAN wrote RetinaFace/parsing weights to a CWD ./gfpgan/weights/ working
-# dir on first use). Runtime artifact, never committed.
+# Runtime model artifacts
 gfpgan/
 
-# Qwen ControlNet experiment outputs (throwaway eval; never the committed corpus)
-scripts/_qwen_exp_out/
-
-# Local-only working data for analysis (not a committed corpus; never tracked)
+# Local evaluation data
 .local-eval/

CLAUDE.md

@@ -1,104 +1,54 @@
-# Remove-AI-Watermarks
+# Remove AI Watermarks
 
-You are a **principal Python engineer** maintaining a CLI tool and library for removing visible and invisible AI watermarks from images.
+You are a **principal Python engineer** maintaining a CLI tool and library for removing visible and invisible AI provenance watermarks.
 
 ## Scope and non-goals
 
-The mission is removing **AI-provenance watermarks** that a platform stamps onto content the user generated themselves — SynthID, the Gemini / Nano Banana sparkle, the Doubao / Jimeng / Qwen / Kling / Tencent Yuanbao / Samsung visible AI labels, the Chinese TC260 "由…AI生成" label, and C2PA / IPTC / EXIF "Made with AI" metadata. The point is user autonomy over their own generated output.
+The project gives users control over provenance marks on content they generated or edited themselves. It does not automatically remove stock-agency, marketplace, classifieds, tiled-preview, or other marks that protect a third party's paid or copyrighted asset.
 
-It deliberately does **not** remove watermarks that protect someone else's paid or copyrighted content — stock-agency overlays (Shutterstock, Getty, iStock, Adobe Stock), classifieds-site marks, or any tiled / diagonal "preview" watermark whose job is to gate a purchase. Stripping those makes a paid resource free off someone else's work; out of scope **by principle, not by technical difficulty**. The line: a visible mark is in scope when it labels the user's **own** AI generation, and out of scope when it protects a **third party's paid asset**.
+- Add visible templates only for AI-generation labels.
+- Do not add stock, agency, or classifieds marks to `watermark_registry.py`.
+- Keep `erase --region` generic and user-directed; do not build an automatic stock-watermark remover on it.
 
-Consequences for contributors (do not drift back into the stock niche just because it is technically feasible):
-- Do not add stock / agency / classifieds watermark removal to `watermark_registry.py` or the eraser, and do not build tiled-overlay or multi-image watermark-estimation features aimed at them.
-- `erase --region` stays a generic **user-driven** tool (the user points at their own object); do not ship an *automatic* stock-watermark detector/remover on top of it.
-- New visible-mark templates are for **AI-generation labels only**.
-
-(Established 2026-06-13 by user instruction: "Я пытаюсь сделать платные ресурсы бесплатными — это не то, против чего мы боремся.")
+Full boundary and legal context: [`docs/legal-and-safety.md`](docs/legal-and-safety.md).
 
 ## How to run
 
-Per-command exit-code semantics (the no-signal / GPU-missing skip branches), test traps, and regression-guard paths live in `docs/module-internals.md` (section "CLI commands (`cli.py`)") — read it before changing any command's skip/exit behavior. Every single-image command's `source` argument declares `dir_okay=False`: without it `click.Path(exists=True)` accepts a directory, which then reached `open()` and raised `IsADirectoryError` (Tier E, 2026-07-20; `batch`'s `directory` already declared `file_okay=False`). Regression: `tests/test_cli_robustness.py::TestDirectoryInputIsRejected`.
+```bash
+uv run remove-ai-watermarks --help
+bash maintain.sh
+```
 
-- `uv run remove-ai-watermarks all <image.png> -o <output.png>` — full pipeline (visible + invisible + metadata). Same diffusion knobs as `invisible`, plus the visible-pass `--backend auto|cv2|migan|lama` (default `auto`) and `--sensitivity auto|strict` (default `auto`) for the localize -> fill visible removal (see the `visible` bullet). Skips step 2 (invisible/SynthID) when the `[gpu]` extra is absent or no invisible signal is detectable; see the module doc for the distinct exit codes.
-- `uv run remove-ai-watermarks invisible <image.png> -o <out.png>` — diffusion SynthID removal. **Full knob set** (kept identical across `invisible`/`all`/`batch`): `--strength` (vendor-adaptive default except resolution-adaptive `qwen-zimage`), `--steps` (**interacts with `--strength`** on the diffusers profiles; `watermark_profiles.viable_steps` prevents zero effective steps. `qwen-zimage` instead fixes its Lightning stage at 4 steps), `--guidance-scale`, `--pipeline sdxl|controlnet|qwen|qwen-zimage` (default `controlnet`; `qwen` and `qwen-zimage` are manual opt-ins), `--controlnet-scale`, `--model`, `--device`, `--seed`, `--hf-token`, `--max-resolution`/`--min-resolution`, `--upscaler lanczos|esrgan`, `--humanize`, `--unsharp`, `--adaptive-polish/--no-adaptive-polish`, `--tile/--no-tile` + `--tile-size`/`--tile-overlap`, `--cpu-offload/--no-cpu-offload`, `--force/--no-force`. `--cpu-offload` trades speed for lower CUDA VRAM use by moving Diffusers model components between CPU and GPU; on `qwen-zimage` it forces the face stack to offload instead of using automatic residency. It has no effect on CPU/MPS. ControlNet is the compatibility and cost default, not the highest-fidelity mode. Recommend the CUDA-only `qwen-zimage` profile when output quality, especially face identity, matters more than runtime and cost; it needs the separate extra, uses a fixed Qwen-Image-2512 + Z-Image stack, rejects `--model`, defaults to the oracle-candidate seed 0, and supports tiling only for its global Qwen pass. The full-frame face stage runs once after tile blending. Tiled outputs still need separate oracle certification. `--auto` is deprecated and a no-op that only warns. Skips the diffusion when no invisible signal is detectable; see the module doc.
-- `uv run remove-ai-watermarks visible <image.png> -o <out.png>` — known-visible-mark removal by **localize -> fill**: each detected mark is localized to a binary full-frame footprint mask, then one shared, swappable fill inpaints that mask. `--backend auto|cv2|migan|lama` (default `auto`) picks the fill: `cv2` (classical inpaint, no deps, the floor), `migan` (MI-GAN ONNX, light, the memory-tight pick where LaMa will not fit), `lama` (big-LaMa ONNX, best quality, heavier, auto-preferred when a learned backend is available); `auto` = LaMa > MI-GAN > cv2, best available. `--mark auto` (default) removes EVERY detected mark in one pass (a Jimeng-basic image carries the top-left "AI生成" pill AND the bottom-right "★ 即梦AI" wordmark) from: Gemini sparkle, Doubao "豆包AI生成", Jimeng "★ 即梦AI", Qwen "千问AI生成", Kling "可灵AI 3.0", Tencent Yuanbao "元宝 / AI生成", Samsung Galaxy AI "✦ Contenuti generati dall'AI", Baidu "百度 AI生成", LibLibAI wordmark (bottom-center), RunningHub "RunningHub AI生成" (top-left), and the capture-less Jimeng "AI生成" pill (top-left, metadata-gated); `--mark gemini|doubao|jimeng|qwen|kling|yuanbao|samsung|baidu|liblib|runninghub|jimeng_pill` forces one. `--sensitivity auto|strict` (default `auto`) sets how hard a borderline mark is trusted: `auto` relaxes a mark's gate only on same-product evidence (metadata provenance for that vendor, or a confidently detected sibling mark of the same product — clean images stay untouched); `strict` never relaxes. Metadata provenance is read automatically and feeds `auto`. (`assume-ai` was REMOVED in 0.16 — see the registry bullet; a user who can SEE a missed mark should point at it with `erase --region`, or name it with `--mark <text-mark> --no-detect`.) For arbitrary logos/objects use `erase`. When no known mark is detected the command writes no output and exits with the no-visible-mark code instead of re-serving the input; `--no-detect` forces the gemini fallback and proceeds. See the module doc for the routing/exit detail. `--backend` and `--sensitivity` are shared across `visible`/`all`/`batch`.
-- `uv run remove-ai-watermarks erase <image.png> --region x,y,w,h -o <out.png>` — universal region eraser (any logo/object, any position). `--backend cv2` (default, no deps), `--backend migan` (MI-GAN via onnxruntime, extra `migan`; ~28 MB, ~1 GB RAM, near-LaMa), or `--backend lama` (big-LaMa, extra `lama`; best quality but ~4.7 GB RAM); `--region` is repeatable.
-- `uv run remove-ai-watermarks identify <image>` — provenance verdict (platform + watermark inventory + confidence); `--json` for machine output, `--no-visible` to skip both registered visible detectors and the optional open invisible-watermark decoder
-- `uv run remove-ai-watermarks metadata <image.png> --check` — inspect AI metadata (C2PA, EXIF, PNG chunks)
-- `uv run remove-ai-watermarks metadata <image.png> --remove -o <out.png>` — strip all AI metadata
-- `uv run remove-ai-watermarks batch <directory>` — process every supported image in a directory (output defaults to `<directory>_clean/`, set with `-o`). `--mode visible|invisible|metadata|all` (default `visible`); the invisible/all path reuses the full `invisible` knob set above, plus `--backend` and `--sensitivity` for the visible localize -> fill pass. Applies the same no-signal skip per image; see the module doc. **Exit code:** non-zero when any image errored OR (mirroring single `all`) a `--mode invisible`/`all` image carried an invisible signal but the GPU extra was absent, so its SynthID scrub was skipped — it emits a loud warning and copies the input through (invisible mode) so the output dir stays complete; a wrapping service can then detect the incomplete run instead of trusting a silent exit 0.
-
-## Test and lint
-
-- **CI** (`.github/workflows/test.yml`): runs on push to `main` + every PR. A `lint` job (ubuntu: `ruff check` + `ruff format --check`) plus a `test` matrix (ubuntu/macos/windows x py3.10/3.12) that does `uv sync --frozen --extra dev` then `pytest`. The matrix installs only core + dev (no `gpu` extra), so the GPU/model-running tests skip there and it exercises the metadata/identify/visible/cv2-eraser surface on all three OSes. Keep `uv.lock` valid (don't break `--frozen`) when editing `pyproject.toml`.
-- Dependency PR checks run the GitHub merge ref against current `main`, not the contributor branch in isolation. If `main` moves after the dependency branch was opened, merge current `main` locally and rerun the full gate; a new linter can expose stale directives in code that landed later.
-- **Release flow + distribution channels** (PyPI publish via `publish.yml`/`uv publish`, the automated Homebrew-tap + HF-Space bumps in `distribute.yml`, conda-forge, ComfyUI Registry, the sdist `data/` exclusion, hatchling pin history): see `docs/release-and-distribution.md` before cutting a release.
-- `bash maintain.sh` — uv-outdated, uv-secure, ruff check/fix, ruff format, pyright (scoped `src/`, see the OOM note below), pytest -n auto. The helper tools live in the `dev` extra (`pytest-xdist`, plus `uv-outdated`/`uv-secure` marker-gated to py3.12+ so the py3.10 resolution stays solvable) — a bare env without `--extra dev` does not have them.
-- **Strict pyright is clean across `src/` (0 errors).** The cv2/torch/diffusers boundary files (`gemini_engine`, `region_eraser`, `doubao_engine`, `humanizer`, `invisible_engine`, `noai/watermark_remover`) carry a documented per-file `# pyright:` relax pragma that turns off only the unknown-type / untyped-third-party rules — those libs ship no usable types, so strict typing there fights the ecosystem. Pure-logic files stay fully strict; `typings/piexif/__init__.pyi` is a local stub so `metadata.py`/`extractor.py` resolve piexif. Public ndarray-returning signatures on the relaxed engines are still annotated `NDArray[Any]` so strict consumers (`cli.py`) stay clean. When touching a relaxed file, prefer fixing real issues over widening the pragma; keep the pragma scoped to genuinely-untyped boundaries. The `uv-secure` CVE-resolution history (idna/aiohttp bumps, retired basicsr, the dismissed torch `GHSA-rrmf-rvhw-rf47`) lives in `docs/release-and-distribution.md` — read it before re-triaging a dependency alert.
-- **Full-project `uv run pyright` (no path) OOMs/crashes node on this ML-heavy repo** (emits a `libnode` stack frame, no summary) — a known environment limit, not a code error. Gate with `uv run --extra dev --extra gpu pyright src/` (completes, authoritative) or scope to changed files; also run `uv run ruff check` and `uv run pytest` directly.
-- Run `uv run` from the repo root — from another cwd it falls back to a bare env without numpy/cv2/torch.
-- **Stale `trustmark` remnant in site-packages after an extras change:** the `trustmark` package downloads model weights INTO its own package dir, so when a narrower `uv sync` prunes the package, a `trustmark/models/` directory survives as an empty namespace package. Symptom: pyright `"TrustMark" is unknown import symbol` on `trustmark_detector.py` and `find_spec("trustmark")` returning a loader-less spec (so `is_available()` lies True). Fix: `rm -rf .venv/lib/python3.12/site-packages/trustmark` (regenerable weights cache).
-- To add a dev tool (pytest/ruff/pyright) into the env, use `uv sync --frozen --extra dev --extra gpu`, **never `uv pip install`** — `uv pip install` re-resolves and rewrites `uv.lock`, which silently bumped `transformers` to a build incompatible with the pinned `diffusers` (`cannot import name 'Qwen3VLForConditionalGeneration'`) and broke every `identify`/metadata import. Recovery: `git checkout uv.lock && uv sync --frozen --extra gpu --extra dev`. The `gpu` extra holds `diffusers`/`transformers`/`torch`, so a bare `uv sync` (no extras) removes them; `noai/__init__` is now **lazy** (PEP 562 `__getattr__`, so importing `identify`/`metadata` no longer pulls `watermark_remover`/torch), so a bare env breaks only when the removal pipeline is actually invoked, not on import. `maintain.sh`'s `uv sync --all-extras` also pulls the heavy `trustmark`/`lama` wheels (pytorch-lightning, onnxruntime) — fine on a good connection, but on flaky DNS sync only `--extra gpu --extra dev` and run the lint/test steps by hand.
-- Metadata/C2PA tests assert against real committed fixtures in `data/fixtures/provenance/` (`chatgpt-*.png` = OpenAI C2PA, `firefly-1.png` = Adobe, `mj-1.png` = Midjourney IPTC, `doubao-1.png` = ByteDance Doubao with the China TC260 `<TC260:AIGC>` XMP label **and** a visible "豆包AI生成" text mark bottom-right; `grok-1.jpg` = xAI Grok with its EXIF-only `Signature:` blob + UUID `Artist` and no C2PA/SynthID/IPTC; `flux-1.png` / `flux-1.jpg` = real Black Forest Labs FLUX.2 Playground output, signed C2PA (issuer "Black Forest Labs" + `trainedAlgorithmicMedia`) -- `flux-1.jpg` is the first committed **JPEG-with-C2PA** fixture, exercising the c2pa-python non-PNG reader path end to end; whether BFL hosted output also embeds the open DWT-DCT pixel watermark is UNRESOLVED -- our detector returns None on these fox samples, but they are high-texture carriers where even a known-embedded watermark fails the round-trip, see the content-fragility caveat in `docs/watermarking-landscape.md`); synthetic byte blobs cover the remaining JPEG/ISOBMFF format paths. The `clean_photo` conftest fixture generates a deterministic metadata-free PNG; no real negative photo is committed for tests.
-- Repository data follows `data/README.md`: executable provenance fixtures live in `data/fixtures/`, minimal detector rebuild inputs in `data/calibration/`, canonical provider-oracle originals in `data/synthid/`, and evaluation-only ground truth in `data/evaluations/`. Store each binary once and point every consumer at the canonical path.
-- SynthID oracle fixtures: `scripts/synthid_corpus.py` ingests labeled originals into `data/synthid/originals/`. The tracked `manifest.csv` is kept in sync with the files on disk, one row per image. `full-pipeline-quality.csv` is the reusable full-pipeline test set: read its single canonical copy, preserve `source_filename` in outputs, and keep provider groups separate for their respective oracles. Generated or cleaned outputs stay outside the repository; record their reproducible command, hash, and oracle verdict instead.
+Run `uv` from the repository root. Command selection, options, defaults, and examples live in [`docs/cli.md`](docs/cli.md). Before changing command routing, no-signal behavior, or exit codes, read the command-line section of [`docs/module-internals.md`](docs/module-internals.md).
 
 ## Configuration
 
-- GPU/ML modules (invisible_engine, watermark_remover) are optional — guard imports with `is_available()` checks
-- Optional detection extras: `detect` (imwatermark — open SD/SDXL/FLUX watermark) and `trustmark` (Adobe TrustMark decoder; pulls torch + downloads weights). Both are guarded by `is_available()` and skipped by `identify` when absent.
-- Optional `esrgan` extra (spandrel only): Real-ESRGAN pre-diffusion super-resolution for small inputs (`upscaler.py`, CLI `--upscaler esrgan` on `invisible`/`all`/`batch`). Guarded by `upscaler.is_available()`; the default upscaler stays Lanczos (cv2, no deps) and the engine falls back to Lanczos when the extra is absent or the model errors. spandrel is MIT and pulls NO basicsr (only torch/torchvision/safetensors/numpy/einops); Real-ESRGAN weights are BSD-3-Clause and download on first use via `torch.hub` (never bundled). Kept OUT of `all` (heavy + model download).
-- Tests for the *model-running* paths are limited to availability checks (multi-GB downloads). But the **pure helpers inside ML-adjacent modules are unit-tested without any download** and must stay that way: `_target_size` (native-vs-downscale-cap-vs-upscale-floor, `test_invisible_engine.py`), `humanizer.unsharp_mask`/`adaptive_polish` (`test_humanizer.py`), and the MPS->CPU fallback control flow via mocked pipelines (`test_img2img_runner.py`, 100% cover). Don't skip these as "ML, needs a model" — only `remove_watermark`/the diffusion bodies do.
+GPU and ML modules are optional. Guard their imports with `is_available()`.
 
-## Key modules
+Optional features and installation groups are documented in [`docs/installation.md`](docs/installation.md). Model-running paths may use availability tests, while pure helpers in ML-adjacent modules must remain unit-tested without downloads.
 
-Compact map. The full per-module detail (design decisions, tuned thresholds, calibration history, incident records, and the regression-guard map) lives in `docs/module-internals.md` — **read the relevant section there before changing any module below.**
+## Test and lint
 
-- `noai/c2pa.py` — C2PA reading. `extract_c2pa_info(path)` uses the official **c2pa-python `Reader`** first (core dep, any container; `read_manifest_store_json` returns the WHOLE store JSON — active + ingredient manifests — so an AI marker on a parent manifest is seen), and falls back to the hand-rolled caBX/CBOR parser (`has_c2pa_metadata` / `extract_c2pa_chunk` / `_extract_c2pa_info_png`) for synthetic/partial blobs the validator rejects or a broken/absent wheel. The registry scan (issuer / source-type / SynthID / soft-binding) is shared by both paths via `_populate_registry_fields`, so the return-dict shape is identical. Do not reimplement chunk parsing; chunk reads are clamped to the remaining file size by design. `extract_c2pa_chunk`/`inject_c2pa_chunk` stay PNG-only (raw caBX bytes, test/extractor use).
-- `noai/constants.py` — the single `C2PA_AI_VENDORS` registry (+ `C2PA_SOFT_BINDINGS`) from which `C2PA_ISSUERS` / `SYNTHID_C2PA_ISSUERS` / `C2PA_IDENTITY_AI_ORGS` / `identify._ISSUER_PLATFORM` are all derived. Add a new vendor as one registry entry; never edit the derived dicts and never add inline. A vendor's `asserts_ai=True` flag means its mere presence asserts AI generation even without a `trainedAlgorithmicMedia` digital-source-type (a pure-generator brand with a distinctive issuer/generator string, e.g. **Dreamina** — ByteDance's international Jimeng brand, signed as "Bytedance Pte. Ltd." with a "Dreamina/x.y" claim generator and no source-type); NEVER set it for common-word issuers (Adobe/Google/OpenAI/Microsoft) that appear incidentally in unrelated bytes — those stay source-type-gated in `identify._attribute_platform`.
-- `metadata.py` — `scan_head(path)` is the shared (memoized) input for every C2PA/AIGC/IPTC byte scan; use it instead of `open().read(1MB)` for any new marker scan. Also home to `synthid_source`, `xai_signature`, `iptc_ai_system`, `aigc_label`, `huggingface_job`, `samsung_genai`, and `remove_ai_metadata` (fail-safe `strip_c2pa_boxes`). **A caller that REPORTS an outcome must use `strip_and_verify`, not `remove_ai_metadata` directly** -- the stripper is deliberately fail-safe (a file PIL cannot decode is copied through UNCHANGED rather than crashing), so its return value cannot distinguish a no-op from a real strip. `metadata --remove` and `batch --mode metadata|all` both re-scan the OUTPUT through it and fail loudly; verified on Samsung Galaxy S22 C2PA PNGs, where the command printed "stripped" and exited 0 while the output still read as AI (2026-07-19). **`remove_ai_metadata` is the SINGLE metadata stripper** (the legacy PIL-re-encoding `noai/cleaner` was deleted; the diffusion core and the public `noai.remove_ai_metadata` re-export now point here). It strips **losslessly** per container: ISOBMFF (HEIC/AVIF/MP4) blanks tokens / strips boxes in place; **JPEG uses `_strip_jpeg_metadata_lossless`** — a marker-segment walk that drops the AI-bearing APP segments (C2PA APP11; XMP APP1 carrying C2PA, a China-AIGC token, OR an IPTC `digitalSourceType` / 2025.1 AI-disclosure marker; IPTC-IIM APP13) and scrubs AI EXIF tags via piexif, copying the entropy-coded scan verbatim so **the pixels are bit-identical** (no DCT re-encode). **Detection<->removal parity across every marker placement is load-bearing** — anything a scanner flags, the strip must reach, or a re-served file still reads as AI: (a) the APP1-XMP branch of `_jpeg_app_carries_ai` checks the IPTC marker sets too, not only C2PA/AIGC (the Instagram/MidJourney/Meta "Made with AI" `digitalSourceType` lives in XMP, not the APP13 IIM record); (b) a bare `AIGC{...}` / `{"AIGC":{...}}` block in ANY JPEG APP segment — the specific C2PA(APP11)/XMP(APP1)/IPTC(APP13) checks FALL THROUGH to a generic `_is_aigc_exif_value` drop, so a bare AIGC in APP11 (the supported placement, NOT a C2PA manifest) is caught, not swallowed by the C2PA-only 0xEB branch — plus the same AIGC block in a STANDARD **PNG text chunk** value (e.g. `Description`, which `_is_ai_key` keeps) is dropped on the value; (c) the China TC260 `{"AIGC":{...}}` block in EXIF `UserComment`/`ImageDescription` is scrubbed by `_scrub_ai_exif` (Doubao producer + Tencent service-provider schemas); (d) the Samsung Galaxy AI `PhotoEditor_Re_Edit_Data` trailer past the JPEG EOI is truncated by `_strip_samsung_trailer` (and `samsung_genai` reads the file tail so a multi-MB photo's trailer past the 512 KB quick-scan window is still DETECTED). Pixels stay bit-identical throughout, so a `--strip-metadata` on a q100 removal output does NOT crush it back to q75; PNG/WebP re-saves are pixel-lossless (WebP written at cv2 lossless mode, quality 101 — quality 1-100 is lossy). **The PIL-fallback save format is chosen by the source's CONTENT, not its file extension** (`_sniff_image_format`, and the JPEG-lossless gate is content-gated too): inputs can be misnamed (a PNG served as `.jpg` is the common one), and routing on the extension re-encoded a lossless PNG/WebP into a real JPEG — a silent degradation that broke "work with originals". A **misnamed** lossless source (source-extension format != content) is preserved in its true format; a **correctly-named** source still honors a deliberate output-extension conversion (e.g. `source.png -> output.jpg`). Not yet handled: a 16-bit PNG is downconverted to 8-bit on the PIL re-save (rare; would need a byte-level PNG chunk stripper). Regression: `tests/test_metadata.py::TestHasAiMetadata::test_strip_preserves_lossless_content_with_mismatched_extension`. **`remove_ai_metadata` is fail-safe on an undecodable image:** a truncated/corrupt file (PIL raises `OSError` decoding it; some inputs) is copied through UNCHANGED rather than crashing a direct library caller (a web worker would 500 on a partial upload), mirroring `strip_c2pa_boxes` — we cannot strip what we cannot parse, but we never raise. Regression: `tests/test_metadata.py::TestHasAiMetadata::test_remove_ai_metadata_failsafe_on_truncated_png`. Regression: `tests/test_metadata.py::TestHasAiMetadata::{test_jpeg_metadata_strip_is_pixel_lossless, test_jpeg_strip_removes_iptc_marker_in_xmp}`, `TestSamsungGenai::{test_remove_strips_post_eoi_trailer, test_detects_trailer_past_scan_window}`, the AIGC-EXIF/bare-APP removal tests, and `tests/test_noai.py::TestISOBMFF::{test_blank_aigc_block_in_exif, test_blank_xai_signature_pair_in_exif}`. `exif_generator` matches a VALUE against `AI_GENERATOR_TOKENS` across EXIF `Software`/`Make`/`Artist`/`ImageDescription`, XMP `CreatorTool`, AND PNG `tEXt` chunks (`Software`/`Source`/`Title`/`Description` — NovelAI stamps there, not EXIF). **Detection and removal must stay in parity:** a Line truncated
-- `identify.py` — aggregates every locally-readable signal into one `ProvenanceReport`; `is_ai_generated` is True or None, never asserted False. `ProvenanceReport.ai_source_kind` exposes the C2PA digital-source-type split — `"generated"` (trainedAlgorithmicMedia, fully AI) vs `"enhanced"` (compositeWithTrainedAlgorithmicMedia, a real photo with an AI-composited region), else None — so a caller branches full-frame scrub vs region-targeted clean (see `noai/tiling.feather_region_composite` + `WatermarkRemover.remove_watermark(region=...)`). The sparkle provenance threshold is the SHARED `watermark_registry.GEMINI_SPARKLE_TRUST_CONF` (imported, not a private copy) so the provenance "is there a sparkle" verdict and the removal "take the sparkle" decision can never drift. `import identify` is deliberately light (lazy `noai/__init__`, fits a 512 MB host) — keep heavy imports out (the `watermark_registry` constant import stays light: engines are lazy there). Add capture-camera tokens to `_DEVICE_C2PA_PLATFORM` only when verified against a real C2PA file; editing-app/AI-device signer tokens go to `_SIGNER_C2PA_PLATFORM`; generator/issuer platforms to `C2PA_AI_VENDORS` in `constants.py`. The IPTC `digitalSourceType` **`algorithmicMedia`** (bare) is PROCEDURAL (an algorithm not trained on sampled data), NOT AI/ML generation, so it is deliberately absent from `IPTC_AI_MARKERS` — flagging it made `identify` assert AI + `has_invisible_target` True, scrubbing clean procedural content (it is a distinct token from `trainedAlgorithmicMedia`, so real "Made with AI" labels are unaffected; regression `test_metadata.py::...test_bare_algorithmic_media_not_flagged_ai`). Integrity-clash detection is high-precision by design (only hard generator stamps feed it, source-grouped independence). `_vendor_of` normalizes ByteDance/Canva/ElevenLabs/Black Forest Labs (as well as OpenAI/Google/... ) so their C2PA claims participate in the clash check; the generic **China TC260 AIGC label names no specific vendor**, so when a TC260-applying vendor (ByteDance, `_TC260_VENDORS`) is co-attributed the label is attributed to it (a legit Doubao image carrying its own TC260 label must NOT clash), while a NON-TC260 vendor next to a TC260 label still clashes as a laundering tell. The vendor normalization must not introduce clashes on clean compatibility samples.
-- `watermark_registry.py` — the single catalog of known visible watermarks (gemini / doubao / jimeng / qwen / kling / samsung / runninghub / baidu / liblib / jimeng_pill). **Removal is LOCALIZE -> FILL for every mark:** each mark is localized to a binary full-frame footprint mask (a `Localization`), then ONE shared, swappable fill inpaints that mask via `fill(image, mask, backend=...)` (delegates to `region_eraser.erase`). Reverse-alpha (the old `original = (wm - a*logo)/(1-a)` inversion of a captured alpha map + thin residual inpaint) is GONE for ALL marks; why it was dropped is recorded in `docs/module-internals.md`. Backends: `cv2` (classical inpaint, no deps, the floor), `migan` (MI-GAN ONNX, light, the memory-tight pick where LaMa will not fit), `lama` (big-LaMa ONNX, best quality, heavier, auto-preferred when a learned backend is available); `auto` = LaMa > MI-GAN > cv2, best available. The captured alpha maps (`scripts/visible_alpha_solve.py`) are still used to DETECT the marks and to shape the mask, but NOT for pixel recovery. **`--mark auto` removes EVERY detected mark in one pass** via `remove_auto_marks(image, *, sensitivity="auto", provenance=frozenset(), backend="auto")` (marks coexist -- a Jimeng-basic image has the top-left pill AND the bottom-right wordmark; a single-strongest pick would leave one). **Three orthogonal axes:** `backend` (the fill), `sensitivity` (how hard to trust a borderline mark: `auto`/`strict`, see the `Sensitivity` literal), and `provenance` (vendor keys metadata confirms -- the evidence that drives `auto`). **Perception / decision / action are separated:** `_build_candidates(image)` runs every detector at BOTH trust levels (strict + relaxed) and packages raw verdicts + features into `Candidate`s (no policy); the pure arbiter `decide(candidates, Context(sensitivity, provenance)) -> [Decision]` makes every keep/drop call (per-mark `resolve_trust` + the assumed-trust floor + the pill gate) with no image/IO, so it is unit-testable in isolation; then each winner is localized -> filled. Do NOT put policy back into the engines (the one exception, the Gemini FP gate, stays in `gemini_engine` because `identify` shares that confidence). `detect_marks(..., provenance=frozenset())` stays strict (identify verdict, precision over recall); `KnownMark.remove/detect/localize(..., provenance: bool)` take the already-resolved boolean. **How `auto` decides (this is metadata-INDEPENDENT for recall):** the visual detectors are pixel-based and need no metadata; the recall gain comes from RELAXING the false-positive gate, not from metadata. `strict` never relaxes (clean images untouched); `auto` relaxes a mark only on same-product evidence -- metadata provenance for that vendor OR a confidently detected sibling mark of the SAME product (`_PRODUCT_OF`; Doubao and Jimeng are both bottom-right ByteDance but distinct products, so they do NOT cross-relax). **`resolve_trust` resolves TWO levels:** `confirmed` bypasses the engine's false-positive gate, and only `confirmed` has evidence naming THAT vendor, which is exactly what the bypass is contracted to require (`GeminiEngine.detect_watermark`'s `trust_provenance` docstring: "external metadata already proves this is a Google generation"). **Historical, kept as the reason the third level is gone:** a removed `assumed` level let `assume_ai` bypass the gate on the bare assertion an image is AI. It produced unacceptable false positives on clean camera images and was removed. A wrong relaxation only fills a small corner near-losslessly (the localize -> fill benign failure mode), which is what made a SMALL false-fire rate arguable; it was never a licence for a 60% one. Metadata provenance mapping (feeds `auto`, read by `cli._visible_provenance`): Google/Gemini C2PA issuer -> gemini; China-AIGC (TC260) label -> doubao/jimeng; `samsung_genai` -> samsung. **The `jimeng_pill` is capture-less.** It uses a synthetic silhouette and a fixed top-left footprint. `_keep_pill` requires either a confirmed sibling wordmark or Jimeng provenance with a flat footprint. Do not loosen the flatness guard. **`assume_ai` was REMOVED (2026-07-19); `--sensitivity` is now `auto`/`strict` only.** It relaxed every mark's FP gate on the bare assertion an image is AI -- which names no vendor and no location, exactly what the bypass requires -- and had no place in the model (detector finds -> remove; finds nothing -> leave alone; user SEES a mark -> act on that). It took `_ASSUMED_CONF_FLOOR` / `assumed_floor_ok` / the `assumed` trust level with it, collapsing the ladder to `strict`/`confirmed`, and `_keep_pill` lost its `sensitivity` arg. Recall/precision on the unbiased sample are unchanged, so nothing on the default path moved. **Replacement advice is per mark:** `erase --region` is sound by construction; `--mark <text-mark> --no-detect` is reasonable (forced mask = the real glyph blob, non-empty 13/13); **`--mark gemini --no-detect` is NOT** -- it falls back to a fixed slot thLine truncated
-- `gemini_engine.py` — visible Gemini-sparkle detector + localizer (cv2/numpy, no GPU): top-K size-weighted fusion candidate selection (`_SELECT_TOPK`), corner-promote, false-positive gate (the provenance prior relaxes the gate + lowers the trust threshold when a Google/Gemini C2PA issuer confirms the vendor). **White-core rescue:** the FP gate demotes a low-gradient match (soft edges), but a real FAINT sparkle also has soft edges -- so the gate keeps a low-grad match that is a strong (conf ≥ `_SPARKLE_KEEP_CONF` 0.52), bright (margin), near-WHITE-core sparkle (`_core_saturation` ≤ `_SPARKLE_WHITE_SAT` 0.20): a real sparkle core is white, a clean bright corner that shape-matches (sky/sun) is colored. This recovers ~14/20 metadata-stripped faint sparkles under the DEFAULT strict/auto (no flag, no metadata) at ~1.25% clean false-fire (baseline 0.55%); the ~0.51-scoring bright-bg FPs stay demoted (below 0.52). A learned classifier on the SAME features was measured WORSE than the tuned gate (2026-07 tier-1: MLP 86.7% recall vs 90.8% at equal FP), so the heuristic stays; a patch-CNN with richer features is the only lever left (roadmapped P2, low expected value -- the wall is fundamental). Detection scores the top-K size-weighted matches by full fusion (spatial+gradient+variance) and keeps the highest — NOT the raw-NCC argmax, which re-admits the tiny-patch FPs the size weight suppresses (the osachub 2026-06-12 sub-0.85 corner-sparkle regression; see `docs/module-internals.md`). Keep the 0.85 corner-promote NCC gate; a margin/chroma-gated lower promote was measured and REJECTED 2026-06-11 (~33% FP on non-Google content). Removal is localize -> fill: `footprint_mask` returns the sparkle footprint (the captured alpha thresholded LOW so the faint halo is included, then dilated by a sparkle-relative margin), and the shared `watermark_registry.fill` inpaints it. The captured alpha maps are used only to detect and to shape the mask, not for pixel recovery. `detect_sparkle_confidence` reuses a process-wide `_shared_engine()` singleton (lru_cache) — the engine holds only constant assets (captures, alpha maps, a precomputed 16..118 template ladder) and takes the image as an arg, so do NOT reconstruct `GeminiEngine()` per call: that reloaded assets + recomputed alpha maps + rebuilt the template cache on every one of ~34k `identify` calls (−24% on the sparkle path once made a singleton, output byte-identical). `detect_watermark`/`footprint_mask` guard `image.size == 0` before `to_bgr`, and return an empty (detected=False) result when no template scale fits (short side < 16 px), rather than dereferencing an empty candidate list.
-- `_text_mark_engine.py` — shared base for the text-mark engines (extracted 2026-06-09); the per-engine modules are config-only subclasses. Detection still matches the glyph silhouette (NCC, keys on glyph shape). The removal mask is TEMPLATE-FREE: it is the bounding box of the top-hat glyph blob (`extract_mask`), filled solid + dilated, so the shared fill inpaints the whole wordmark rectangle. This drops the fixed alpha-template placement, so a re-rendered or differently-placed mark is still masked; the captured alpha maps are now used only for the detection silhouette, not for removal. New text mark = a `TextMarkConfig` + a thin subclass + one registry row. Gemini stays a separate engine (different model). The corner anchor is `corner` = `br`/`bl`/`tl`/`bc` (tl added 2026-07-22 for runninghub, bc for liblib's centered wordmark); `detect_frontend` is `binary`/`tophat`/`gray` (`gray` = raw-grayscale NCC for the faint mid-gray runninghub mark, added 2026-07-22; contrast-DEPENDENT, so its gates never port). The detection scale ladder is per-mark (`TextMarkConfig.ladder`, default `(0.8, 1.0, 1.25)` -- added 2026-07-21 for qwen's two size modes; the shared default is unchanged for every other mark, and densifying the SHARED ladder was measured and rejected, see `docs/verification-plan.md` B2).
-- `pill_engine.py` — detects the capture-less Jimeng "AI生成" pill with a synthetic silhouette and removes it through the shared fill path. Its weak detector is registry-gated: a sibling wordmark may confirm it, while metadata-only removal also requires a flat footprint. Do not loosen those gates.
-- `doubao_engine.py` / `jimeng_engine.py` / `samsung_engine.py` — thin `TextMarkEngine` subclasses: Doubao "豆包AI生成" (bottom-right), Jimeng "★ 即梦AI" (bottom-right), Samsung Galaxy AI "✦ Contenuti generati dall'AI" (bottom-LEFT, locale-specific — Italian variant calibrated). Detection matches the glyph silhouette (NCC); removal localizes the glyph blob to a solid dilated box (`extract_mask`) and hands it to the shared fill. Calibration confirms that doubao and jimeng localize and remove cleanly, while clean compatibility images remain unchanged. **Samsung detection is calibrated only for the Italian "Contenuti generati dall'AI" string** (a pre-existing limit, unchanged by the localize -> fill refactor but now surfaced because detection gates removal): non-Italian Samsung locales are not detected, and thus not removed, even though the fill mask itself is locale-independent; other locales need their own detection silhouette (the locale string font-rendered + calibrated on real positives), NOT an app capture.
-- `qwen_engine.py` — detects the Qwen "千问AI生成" bottom-right text mark with a synthetic silhouette and per-mark geometry. Keep its calibration independent from similar CJK marks.
-- `kling_engine.py` — detects the Kling "可灵AI 3.0" bottom-right text mark. It uses short-side geometry and a synthetic silhouette.
-- `yuanbao_engine.py` — detects the standard two-line Tencent Yuanbao "元宝 / AI生成" bottom-right mark through polarity-independent local contrast. The one-line overlay variant remains unsupported.
-- `runninghub_engine.py` — detects the faint top-left RunningHub mark through grayscale silhouette matching. The anchor gate and detector-owned match box are part of its false-positive control.
-- `baidu_engine.py` — detects the Baidu "百度 AI生成" bottom-right mark. Rival margins separate it from similar CJK marks, and its custom footprint includes the adjacent tag.
-- `liblib_engine.py` — detects the bottom-center LibLibAI wordmark with a synthetic silhouette, contrast gating, and detector-owned footprint.
-- `region_eraser.py` — universal region eraser (`erase` CLI) and the shared fill backend behind `watermark_registry.fill` for the visible localize -> fill removal. Three backends: `cv2` (default for the user-directed `erase` command, no deps, the floor), `migan` (MI-GAN ONNX, extra `migan`, MIT, ~28 MB / ~0.19 s, the memory-tight learned tier), `lama` (big-LaMa ONNX, extra `lama`, ~200 MB / ~4.7 GB peak, best quality but too heavy for a minimal worker). The visible registry's `auto` resolution is **LaMa > MI-GAN > cv2**; select MI-GAN or OpenCV explicitly when memory matters. Both `migan` and `lama` **crop a padded region around the mask** before inference and paste only masked pixels back, so peak RAM is bounded by the MARK size, not the image (`migan` ~0.6-0.9 GB regardless of upload size — feeding the whole frame scaled it to ~2.4 GB at 25 MP; `migan` feeds the crop at native resolution, `lama` resizes to its fixed 512²). **Measured end to end 2026-07-20** (`scripts/resource_ceilings.py`, fresh process per cell, 1 MP → 25 MP): `migan` 603 → 775 MB and `lama` 4679 → 4779 MB, both **flat in input size** — the crop-around-the-mask design holds and both documented figures reproduce. **`cv2` is the only backend that GROWS with the input** (74 → 440 MB, 5.9x) because it inpaints the full frame rather than a crop; still the cheapest tier, but size it for the largest upload accepted. Cold wall time 0.02-0.12 s (cv2) / ~0.6 s (migan) / ~3.8 s (lama), model load included. (The harness's own no-op check originally allocated a full-frame temp before reading peak RSS and inflated these by up to 17% at 25 MP; it now compares only the mask box. The conclusion survived re-measurement, the digits moved.) **MI-GAN mask polarity is INVERTED** (0=hole/255=known) vs this package's 255-erase convention; `erase_migan` inverts before feeding the model (feeding 255=hole regenerates the whole frame into stripes — verified). Both ONNX models download on first use, never bundled. The `erase` command keeps its own `--backend`/`--inpaint-method` (unchanged).
-- `invisible_watermark.py` — decodes the OPEN DWT-DCT watermarks (SD / SDXL / FLUX) via `imwatermark` (extra `detect`, pulls torch). Fragile two ways: (1) does not survive JPEG re-encode/resize; (2) **carrier-fragile on a broad class of pristine images** -- a clean encode->decode round-trip recovers 48/48 on chatgpt/firefly/random but FAILS (28-39/48, below the `_MATCH_48`=44 gate) on the FLUX fox, doubao, a flat FLUX generation, AND a clean synthetic flat fill with no watermark. The failure does NOT track texture; it goes with a degenerate **all-ones decode that is a CARRIER ARTIFACT, not a watermark** (synthetic clean image reproduces it). So `detect_invisible_watermark` is **positive-only**: trust a hit; a `None` is inconclusive unless a same-carrier positive-control embed first recovers >=44. Verified 2026-06-19; full caveat in `docs/watermarking-landscape.md`.
-- `trustmark_detector.py` — Adobe TrustMark open decoder (extra `trustmark`). Do NOT remove the JPEG re-encode false-positive gate — a lone TrustMark hit without it is almost always content noise.
-- `noai/watermark_remover.py` — `WatermarkRemover` with four diffusion pipelines selected by the explicit `pipeline` ctor arg, never inferred from `model_id`: `sdxl` (plain SDXL img2img), `controlnet` (SDXL + canny ControlNet, **the compatibility and cost DEFAULT since 2026-06-09**), `qwen` (Qwen-Image 20B img2img), and `qwen-zimage` (delegates to the fixed two-stage runtime below). Removal comes from img2img strength. Both SDXL loaders pass `add_watermarker=False`; diffusers otherwise re-stamps an open SDXL DWT-DCT watermark. Qwen's certified floors and fidelity results remain as documented below. The base `qwen` profile stays the manual text lane; `qwen-zimage` is the recommended high-quality manual mode, especially for face identity, while remaining experimental rather than an auto-router.
-- `noai/qwen_zimage_pipeline.py` — CUDA-only Qwen-Image-2512 Lightning + DiffSynth Canny full-frame regeneration, followed by YuNet face boxes, SAM masks, and Z-Image Turbo regeneration from original face crops. Ports both adaptive denoise formulas from Synthid-Bypass v2. The active upstream face path is YOLO + SAM; this port keeps its center-point and box prompts, proposal selection, detector-box intersection, crop factor, and paste feather while replacing YOLO with YuNet to avoid an AGPL runtime. The port is architectural, not bit-identical: it uses full safetensors instead of GGUF, DiffSynth samplers instead of the Comfy sampler pairs, and no latent detailer feather. DiffSynth input pixels, Canny control, and explicit dimensions must share the same /16 grid. SAM pixels follow the model dtype, geometric prompts stay float32, and bfloat16 outputs convert through float32 before NumPy. The YuNet download verifies its SHA-256. Separate `qwen-zimage` extra; fixed four-step global and eight-step face schedules; no custom `--model`; `--tile` applies only to the global stage, followed by one full-frame face stage; CLI adaptive polish defaults off. GPUs with at least 64 GiB VRAM keep the face stack resident, while smaller devices retain CPU offload. Fixed prompt embeddings are cached only when they do not depend on an edit image. The exact seed-0 release candidate passed the corresponding provider-oracle checks; broader seeded text, face, and tiled-output certification remains open.
-- `noai/tiling.py` — sliding-window tiled diffusion for large inputs (CLI `--tile`). The SDXL, ControlNet, and base Qwen paths branch to `run_tiled` when `tile` is set AND the long side exceeds `tile_size`, refactoring the single-pass `_generate` into a per-tile `_generate_one` (the ControlNet edge map is rebuilt per tile inside it). `qwen-zimage` instead calls `run_tiled` only around its global Qwen stage, blends the tiles, then runs one full-frame face stage. Pure helpers `plan_tiles` (uniform-size tiles, last one flush to the edge) and `feather_weights` (strictly-positive separable taper -> partition-of-unity blend) are unit-tested without the model. Also home to `feather_region_composite(base, regenerated, box, *, feather)` — the pure region-targeted compositor for **AI-enhanced composites** (`ai_source_kind == "enhanced"`): blends the regenerated AI box back over the original with a feathered seam, leaving the real photo OUTSIDE the box pixel-exact. It backs `WatermarkRemover.remove_watermark(region=...)` (regenerate ONLY the AI region, not the whole frame); the no-model lossless region path stays `region_eraser.erase`. New tile/region-blend tuning goes in these pure helpers; do not inline blend math into the runner.
-- `auto_config.py` + the content-detection layer were REMOVED 2026-06-09; `--auto` is a deprecated no-op (controlnet is the default pipeline and adaptive polish is ON by default for the original profiles, while `qwen-zimage` leaves it off to preserve the upstream two-stage output).
-- `upscaler.py` — optional Real-ESRGAN pre-diffusion super-resolution for small inputs (extra `esrgan`, spandrel only). Manual opt-in; the default `--upscaler` stays `lanczos` and the engine always falls back to Lanczos on absence/error. ESRGAN can degrade faces and thin text.
-- `image_io.py` — centralizes Unicode-safe image IO, alpha preservation, content-based format sniffing, and HEIC/AVIF fallbacks. Callers must check `imwrite` success. No-op visible removal preserves original bytes when the output format is unchanged.
-- `api.py` — the high-level convenience API, re-exported lazily at the package top level via `__init__.__getattr__` (PEP 562, so `import remove_ai_watermarks` stays cheap): `remove_visible(source, output=None, *, sensitivity="auto", backend="auto", strip_metadata=True, write_noop=True) -> (result_bgr, [labels])` (source = path OR BGR ndarray; a PATH auto-reads metadata provenance and preserves alpha, an ARRAY does neither; `write_noop=True` writes a clean passthrough copy when nothing is removed, `False` leaves `output` untouched so a "no mark = produce nothing" caller like the CLI `visible` command does not clobber a pre-existing file there) and `visible_provenance(path) -> frozenset[str]` (the single metadata→vendor-keys mapper; `cli._visible_provenance` is a thin None-guarded wrapper over it). **`remove_visible` is the ONE path the CLI and library share** — `cli.cmd_visible`'s `--mark auto` branch delegates entirely to it (read → provenance → `remove_auto_marks` → write → `strip_metadata`), so there is no CLI-vs-library drift; `strip_metadata` defaults True to match `visible --strip-metadata`. This is where a library caller should start — NOT the engines directly (`GeminiEngine`/`TextMarkEngine` have no `remove_watermark` any more; removal is registry `remove_auto_marks`/`KnownMark.remove`; the old single-strongest `best_auto_mark` is gone — removal takes EVERY mark). `identify` is NOT top-level re-exported (it collides with the `identify` submodule); use `from remove_ai_watermarks.identify import identify`.
+`maintain.sh` runs dependency freshness and security checks, Ruff, Pyright scoped to `src/`, and the parallel test suite. Full-project Pyright is not the project gate because the ML dependency graph can exhaust Node memory.
 
-For the Doubao alpha-distillation history (why content-image reverse-alpha distillation fails by physics and controlled captures were required), see `docs/research-doubao-distillation.md`.
+Command, gate, typing, and model-test invariants auto-load from [`.claude/rules/development.md`](.claude/rules/development.md). Environment recovery, CI behavior, and fixture policy live in [`docs/development.md`](docs/development.md).
 
-## Watermarking landscape
+Before a release, read [`docs/release-and-distribution.md`](docs/release-and-distribution.md). Keep the source-distribution public allowlist.
 
-Who embeds what (C2PA / IPTC / EXIF / TC260 AIGC / xAI signature / open and proprietary invisible watermarks), whether each is locally detectable, the C2PA 2.4 durable-credentials implications, and the regulatory driver table live in `docs/watermarking-landscape.md` (research 2026-05-24, updated through 2026-06-10). Read it before adding a new `identify` signal, vendor token, or metadata marker. See `identify.py` for what we read today.
+## Module architecture
 
-## Known limitations
+[`docs/module-internals.md`](docs/module-internals.md) is the canonical per-module map, including design decisions, thresholds, calibration history, incident records, and regression guards. Read the relevant section before changing a subsystem.
 
-Compact list. Full measurements, incident history, and oracle-validation runs live in `docs/known-limitations.md` — **read the relevant section there before changing the diffusion pipelines, strength defaults, resolution handling, or metadata coverage.**
+Research and current constraints are routed through [`docs/index.md`](docs/index.md), especially [`docs/known-limitations.md`](docs/known-limitations.md), [`docs/supported-signals.md`](docs/supported-signals.md), [`docs/synthid.md`](docs/synthid.md), and [`docs/watermarking-landscape.md`](docs/watermarking-landscape.md).
 
-- **Visible-mark fill quality is background/backend-dependent.** The fill only touches the mark footprint (no outside-box damage) and whether the mark is removed is fill-independent — cv2/MI-GAN/LaMa all strip the shape; only the recovered region's *quality* differs. Flat backgrounds: all clean (cv2 often crispest). Textured/regular-structured (fabric, grid): cv2 smears, MI-GAN can ghost/hallucinate, LaMa best. The old reverse-alpha recovered true pixels so it was sometimes cleaner on structure, but localize -> fill trades that for robustness (moved/re-rendered marks, no per-mark capture); `auto` = LaMa > MI-GAN > cv2 with a one-time cv2-fallback warning. Head-to-head vs v0.12.1 on the full visible set: doubao/jimeng identical (100%/100%), gemini strict coverage a few points lower (the metadata-stripped faint ones now mostly recovered by the default white-core rescue in the gemini FP gate), clearance ~98% both. Detail in `docs/known-limitations.md`.
-- `invisible` processes at native resolution for inputs >= 1024px long side and auto-upscales smaller inputs to a 1024px floor (`--min-resolution 0` disables; `--max-resolution N` is an opt-in cap to bound GPU/MPS memory). MPS OOM is memory-tier dependent, not a hard limit: ~24 GB unified memory falls back to CPU (slow but weight-identical output), 32 GB runs native on MPS. The native-vs-cap-vs-floor decision lives in the pure helper `invisible_engine._target_size` — keep the logic there, unit-tested without the model. For large inputs that OOM, `--tile` is the **lossless** alternative to `--max-resolution`: sliding-window diffusion at native resolution, each tile near SDXL's 1024 training size, feather-blended over the overlap (`noai/tiling.py`). It only engages when the long side exceeds `--tile-size`; the geometry (`plan_tiles`) and the blend window (`feather_weights`) are pure and unit-tested (`tests/test_tiling.py`). Caveat: each tile is an independent low-strength regeneration, so at the certified removal strengths (0.20-0.30) tile drift is minimal but not zero; tiling is a memory workaround, not a quality upgrade over a single native pass.
-- fp16 VAE black-output (issues #29/#41): the fp16-fixed SDXL VAE (`madebyollin/sdxl-vae-fp16-fix`) is swapped in for the default SDXL checkpoint on cuda/xpu fp16, plus a model-agnostic backstop that detects a degenerate (all-black) fp16 output and re-runs once in fp32. cpu/mps run fp32 and never reproduce the bug.
-- Pyright first run is slow (2-3 min) due to ML deps (torch/diffusers/transformers stubs); full-project `uv run pyright` can stall for many minutes — scope it to changed files.
-- A third-party PIL plugin autoload (e.g. an HEIF/AVIF plugin) can raise a non-OSError (`ModuleNotFoundError`), not `UnidentifiedImageError`, when opening a file. Code that opens user-supplied or unknown-format files should `except Exception`, not just `OSError`/`UnidentifiedImageError`.
-- rich was dropped: the CLI + analysis scripts print plain text (`click.echo` / the `scripts/_plain_console.py` shim). `rich` is NOT a dependency — importing it breaks the core+dev CI sync; new scripts must use the shim. No Unicode glyphs / colors / progress bars in CLI output by design.
-- HEIC/AVIF are decodable on BOTH paths now: the pixel/removal path via the `image_io.imread` Pillow fallback (+ core `pillow-heif`), and metadata detection via a plugin-free binary scan. C2PA removal in those containers (and MP4/MOV/M4V) is `noai/isobmff.py`; JPEG-XL stays metadata/strip-only (Pillow can't decode it without `pillow-jxl`, not a dep). Non-ISOBMFF audio/video (WebM/MP3/WAV/FLAC/OGG) strips losslessly via ffmpeg on PATH. On the ISOBMFF path `remove_ai_metadata` routes to the container branch and never runs the JPEG `_scrub_ai_exif`, so `isobmff.blank_ai_exif_tokens` is the ONLY EXIF scrubber there and must stay in PARITY with it: it blanks **in place** (same-length space overwrite, piexif-validated so a coincidental II/MM run in pixels is ignored — no `iinf`/`iloc` surgery, mirrors `blank_ai_xmp_packets`) an AI-generator token in `Software`/`Make`/`Artist`/`ImageDescription`, the China TC260 `{"AIGC":{...}}` block in `ImageDescription`/`UserComment` (via `_is_aigc_exif_value`), AND the xAI/Grok `Signature:` + UUID-`Artist` pair — leaving camera/editor EXIF intact. Still NOT built: Resemble PerTh audio detection (no presence/confidence flag exists).
-- **SynthID technical reference: `docs/synthid.md`** — primary-source-cited doc covering mechanism (post-hoc encoder/decoder pair, 136-bit payload at 512x512, pixel-space, model weights NOT modified), robustness numbers (arXiv:2510.09263: ~99.98% TPR@0.1%FPR across 30 transforms including JPEG/crop/resize/color/noise), removal attacks and forensic detectability (arXiv:2605.09203: all 6 attacks detectable at >98% TPR@1%FPR), detectability limits (no public decoder, metadata-proxy only), oracle scope, and adoption landscape. Read that doc first before adding notes here.
-- **SynthID detection is metadata-only.** No local pixel detector is possible by design (Google's decoder is proprietary, trusted-testers only); we read the C2PA companion proxy, which goes quiet once metadata is stripped — a quiet proxy is not proof the pixel watermark is gone. Each vendor has its OWN oracle and it detects only that vendor's content: the Gemini app "Verify with SynthID" for Google, `openai.com/verify` for OpenAI. **Validate the OpenAI arm FIRST** — `openai.com/verify` is more accessible (fewer per-check restrictions) and the strongest automation candidate (Playwright / Chrome MCP); the Gemini flow is more manual. Ordering/throughput choice, not a substitution (see `docs/synthid.md`). SynthID survives JPEG re-encode, so GitHub issue attachments remain valid pixel-watermark test subjects. Every spectral/phase detection approach evaluated (reverse-SynthID, our own probes) works only on controlled solid fills, never on real content.
-- **External AI-vs-real classifier models are out of scope** (decided 2026-05-24): per-generator, degrade off-distribution, and our own light SDXL pass would likely defeat them. Detection stays local + signal-based.
-- **Default strength is VENDOR-ADAPTIVE, one ladder for BOTH pipelines** (since 2026-06-09): `resolve_strength(strength, vendor)` picks OpenAI **0.10** / Gemini **0.15** / unknown **0.15** when `--strength` is unset (the 2026-06-14 lowering from the 2026-06-04 cert floors of 0.20/0.30 — the single source of truth is `watermark_profiles.py`, and the full cert/lowering history is in `docs/known-limitations.md`); explicit `--strength` always wins. Removal at low strength is content x pipeline dependent, and near-threshold removal is SEED-NON-DETERMINISTIC — pick a strength with margin and oracle-revalidate per content type.
-- **`controlnet` is the default pipeline**; `--pipeline sdxl` is the lighter opt-down. Neither pipeline clears all content at low strength (photoreal survives controlnet, flat graphics survive sdxl — the lever is higher strength). A removal-priority caller MUST oracle-validate strength across content types; prod recipe: controlnet + per-vendor floor + FIXED seed. Forensic-stealth caveat (arXiv:2605.09203): defeating the SynthID verifier is NOT forensic invisibility — removal-processed images are flaggable at >98% TPR@1%FPR.
+## Data safety
+
+Follow [`data/README.md`](data/README.md) for public fixture, calibration, oracle, and evaluation layout. Store each tracked binary once and keep generated evaluation outputs outside the repository.
+
+## Rules and conventions
+
+Topic-specific rules live in `.claude/rules/*.md` and are auto-loaded when matching files are touched.
+
+| File | Covers |
+|---|---|
+| `development.md` | Command contracts, project gate, typing boundaries, model-adjacent tests, and the detection-path measurement rule |

README.md

@@ -1,11 +1,16 @@
 # Remove AI Watermarks
 
-Remove AI provenance marks from images you generated yourself:
+Remove AI provenance marks from images and video you generated yourself:
 
 - known visible labels such as the Gemini sparkle and vendor text marks;
 - invisible pixel watermarks through diffusion regeneration;
 - C2PA, EXIF, XMP, IPTC, and related AI metadata.
 
+Video support covers provenance identification, complete visible-plus-metadata
+cleaning, directory batches, visible Sora, Veo, Seedance, Dola, Hailuo, and
+Kling mark removal, and oracle-certified VAE regeneration for video SynthID
+removal.
+
 > Try it online at [raiw.cc](https://raiw.cc) if you do not want to install Python
 > or run diffusion models locally.
 
@@ -28,13 +33,36 @@ Remove AI provenance marks from images you generated yourself:
 | Remove known visible AI marks | `visible` | No |
 | Erase a region you select | `erase` | No |
 | Strip AI metadata | `metadata` | No |
-| Regenerate an image to disrupt invisible watermarks | `invisible` | Recommended |
+| Identify supported video provenance | `video identify` | No |
+| Remove visible marks and AI metadata from video | `video all` | No |
+| Strip AI metadata from video | `video metadata` | No |
+| Remove a registered visible AI mark from video | `video visible` | No |
+| Process a directory of videos | `video batch` | Depends on mode |
+| Remove video SynthID with the certified VAE profile | `video invisible` | Recommended |
+| Regenerate an image to disrupt invisible watermarks | `invisible` | Required (CUDA) |
 | Run visible, invisible, and metadata removal | `all` | Recommended |
 | Process a directory | `batch` | Depends on mode |
 
+## Installation modes
+
+| Need | Install |
+| --- | --- |
+| Metadata inspection and stripping | `remove-ai-watermarks` |
+| Visible detection and removal | `remove-ai-watermarks[visible]` |
+| Visible video processing | `remove-ai-watermarks[video]` |
+| Video SynthID removal | `remove-ai-watermarks[video,diffusion]` |
+| Torch-free DWT-DCT detection | `remove-ai-watermarks[detect]` |
+| Invisible image removal (needs CUDA) | `remove-ai-watermarks[qwen-zimage]` |
+| Every production feature | `remove-ai-watermarks[all]` |
+
+Lower-level and specialized extras include `pixels`, `heif`, `trustmark`,
+`migan`, `lama`, and `diffusion`. The
+[installation guide](docs/installation.md#feature-extras) documents their exact
+dependency composition and model requirements.
+
 ## Quick start
 
-Install the core CLI:
+Install the metadata-focused default CLI:
 
 ```bash
 uv tool install remove-ai-watermarks
@@ -46,7 +74,13 @@ Inspect an image:
 remove-ai-watermarks identify image.png
 ```
 
-Remove a known visible mark and AI metadata:
+For visible watermark removal, install the pixel dependencies:
+
+```bash
+uv tool install --force "remove-ai-watermarks[visible]"
+```
+
+Then remove a known visible mark and AI metadata:
 
 ```bash
 remove-ai-watermarks visible image.png -o clean.png
@@ -58,10 +92,102 @@ Strip metadata without running visible inpainting or diffusion:
 remove-ai-watermarks metadata image.png --remove -o clean.png
 ```
 
-For invisible watermark removal, install the diffusion dependencies:
+Without `-o` this command overwrites the source in place.
+
+Inspect or remove AI metadata from an MP4, MOV, M4V, WebM, MKV, AVI, or FLV
+file:
 
 ```bash
-uv tool install --force "remove-ai-watermarks[gpu]"
+remove-ai-watermarks video metadata input.mp4 --check
+remove-ai-watermarks video metadata input.mp4 --remove -o clean.mp4
+```
+
+The `video metadata` command does not transcode video or audio streams. Unlike
+the image command above, when `-o` is omitted it writes `<source>_clean` and
+preserves the original. MP4 and MOV
+inspection includes the native TC260 `AIGC` tag in
+`moov.udta.meta.keys/ilst`, including a `moov` placed after the media payload.
+MKV and WebM inspection reads the normative
+`Segment.Tags.Tag.SimpleTag` placement. AVI uses `LIST/INFO/AIGC`, while FLV
+uses `script.onMetaData.AIGC`. The non-ISOBMFF formats are remuxed with stream
+copy for removal.
+
+Use the product-oriented video path to identify or clean a file:
+
+```bash
+uv tool install --force "remove-ai-watermarks[video]"
+remove-ai-watermarks video identify input.mp4
+remove-ai-watermarks video all input.mp4 -o clean.mp4
+```
+
+`video all` removes a stable registered visible mark when present and always
+strips verified AI metadata. If neither signal is found, it still writes a
+same-container passthrough, so application callers get one predictable output
+contract. Proprietary invisible-video removal is excluded by default.
+`--invisible` opts into the lossy, oracle-certified video SynthID profile.
+
+Process a directory with the same contract:
+
+```bash
+remove-ai-watermarks video batch ./videos --mode all
+```
+
+Remove a supported visible video mark:
+
+```bash
+remove-ai-watermarks video visible input.mp4 -o clean.mp4
+remove-ai-watermarks video visible veo.mp4 --mark veo -o veo_clean.mp4
+remove-ai-watermarks video visible seedance.mp4 --mark seedance -o seedance_clean.mp4
+remove-ai-watermarks video visible dola.mp4 --mark dola -o dola_clean.mp4
+remove-ai-watermarks video visible hailuo.mp4 --mark hailuo -o hailuo_clean.mp4
+remove-ai-watermarks video visible kling.mp4 --mark kling -o kling_clean.mp4
+```
+
+This path scans the complete sequence before changing pixels. It accepts only a
+mark that repeats at a stable position across adjacent frames, then reuses the
+same OpenCV, MI-GAN, or LaMa fill backends as image removal. Audio is copied
+without re-encoding and is allowed to reach its natural end; the video stream
+is transcoded because its pixels change. By default, a guarded optical-flow
+pass motion-aligns the preceding accepted fill and blends it only when the
+nearby source context agrees; use `--no-temporal-consistency` to disable it.
+The encoder preserves supported
+8-bit source chroma sampling, color tags, and MP4/MOV track timescale instead
+of relying on ffmpeg's implicit raw-BGR defaults. Variable frame intervals are
+preserved through a timestamped in-memory NUT bridge instead of being flattened
+to the average frame rate. Non-zero source start timestamps are retained
+together with the copied audio offset. The default `--mark auto`
+scans all providers in one decode pass and selects the first stable match in
+the specificity order shown below. Pass an explicit mark to restrict detection
+to one provider.
+Sora covers the moving Sora 2 mascot and wordmark. Veo covers both the current
+four-point diamond and the legacy `Veo` text. Seedance covers the fixed boxed
+`AI` label, Dola covers the fixed `Dola AI` text, Hailuo covers the composite
+`MINIMAX | hailuo AI` label, and Kling covers the bottom-right `KLING AI`
+label with its version suffix. A completed encode is published atomically. No
+output is written when no stable mark is found.
+HDR, PQ/HLG, and greater-than-8-bit inputs are rejected before encoding rather
+than silently reduced through OpenCV's 8-bit BGR boundary.
+
+Remove video SynthID:
+
+```bash
+uv tool install --force "remove-ai-watermarks[video,diffusion]"
+remove-ai-watermarks video invisible input.mp4 -o clean.mp4
+```
+
+This path regenerates the complete sequence with one latent-noise field shared
+across time, copies complete audio, strips source metadata, and publishes the
+completed encode atomically. The default `noise_std=0.15` profile passed both
+the two-carrier calibration and a complete public eight-second Veo oracle
+check. Google does not publish a local decoder, so a fresh provider check
+remains useful for unusually important files or after provider changes, but it
+is not a product result state.
+
+For invisible watermark removal, install the `qwen-zimage` extra. **An NVIDIA GPU
+is required**: both profiles are CUDA-only, and there is no CPU or MPS fallback.
+
+```bash
+uv tool install --force "remove-ai-watermarks[qwen-zimage]"
 remove-ai-watermarks invisible image.png -o clean.png
 ```
 
@@ -85,14 +211,14 @@ features, and development setup.
 
 ### High quality invisible removal
 
-The `qwen-zimage` profile is the highest fidelity option for face heavy images.
-It is CUDA only and uses a much larger model stack than the default ControlNet
-profile.
+`qwen-zimage` is the default profile: a Qwen-Image-2512 Lightning pass under Canny
+ControlNet, followed by SAM-masked Z-Image repair of any detected face. The
+alternative, `sdxl-zimage`, swaps the global stage for SDXL and keeps the same face
+stage. Both are CUDA only.
 
 ```bash
 uv tool install --force "remove-ai-watermarks[qwen-zimage]"
-remove-ai-watermarks invisible image.png -o clean.png \
-  --pipeline qwen-zimage --force
+remove-ai-watermarks invisible image.png -o clean.png --force
 ```
 
 | OpenAI example before | OpenAI example after |
@@ -129,8 +255,9 @@ remove-ai-watermarks erase image.png \
 
 ### Use a learned fill backend
 
-The core install uses OpenCV inpainting when no learned backend is installed.
-For more difficult backgrounds:
+The `visible` extra uses OpenCV inpainting when no learned backend is installed.
+For more difficult backgrounds, the learned-backend extras include the same
+pixel dependencies automatically:
 
 ```bash
 uv tool install --force "remove-ai-watermarks[migan]"
@@ -150,7 +277,7 @@ remove-ai-watermarks invisible image.png -o clean.png \
 ```
 
 CPU offload lowers CUDA memory pressure by moving model components between CPU
-and GPU. It is slower and has no effect on CPU or MPS.
+and GPU, at the cost of speed.
 
 ### Process a directory
 
@@ -164,7 +291,7 @@ remove-ai-watermarks batch ./images --mode all
 Visible mark support includes:
 
 - Google Gemini and Nano Banana sparkle;
-- Doubao, Jimeng, Qwen, Kling, Baidu, LibLibAI, and RunningHub labels;
+- Doubao, Jimeng, Qwen, Kling, Yuanbao, Baidu, LibLibAI, and RunningHub labels;
 - one calibrated Samsung Galaxy AI label variant.
 
 Metadata and provenance inspection covers C2PA, EXIF, XMP, IPTC, common
@@ -184,8 +311,9 @@ Visible removal follows three steps:
 3. Fill only the masked region with OpenCV, MI-GAN, or LaMa.
 
 Metadata removal uses format aware stripping. JPEG metadata removal preserves
-the encoded image scan instead of recompressing it. Other supported containers
-use their corresponding metadata path.
+the encoded image scan instead of recompressing it. Native MP4/MOV TC260 values
+are blanked without changing box sizes or media offsets. Other supported
+containers use their corresponding metadata path.
 
 Invisible removal is different. It regenerates the image through a diffusion
 pipeline to disrupt pixel and frequency domain watermarks. This changes the
@@ -197,19 +325,38 @@ See [supported signals](docs/supported-signals.md) and
 
 ## Python API
 
+The visible-removal API requires `remove-ai-watermarks[visible]`.
+
 ```python
 import remove_ai_watermarks as raiw
 
 result, removed = raiw.remove_visible("watermarked.png", "clean.png")
 print(removed)
+
+provenance = raiw.identify_video("input.mp4")
+report = raiw.inspect_video_metadata("input.mp4")
+complete = raiw.remove_video_all("input.mp4", "clean.mp4")
+batch = raiw.remove_video_batch("videos", "videos_clean")
+cleaned = raiw.remove_video_metadata("input.mp4")
+synthid_cleaned = raiw.remove_video_invisible("input.mp4", "synthid_clean.mp4")
+visible = raiw.remove_video_visible("input.mp4", "clean.mp4")
+print(visible.mark)
+veo = raiw.remove_video_visible("veo.mp4", "veo_clean.mp4", mark="veo")
+seedance = raiw.remove_video_visible(
+    "seedance.mp4",
+    "seedance_clean.mp4",
+    mark="seedance",
+)
+dola = raiw.remove_video_visible("dola.mp4", "dola_clean.mp4", mark="dola")
 ```
 
 The high level API accepts a file path or a BGR NumPy array. For path inputs it
 also reads provenance metadata, preserves alpha, and can strip AI metadata from
 the written result.
 
-See the [Python API guide](docs/python-api.md) for visible removal, provenance
-inspection, metadata stripping, and diffusion usage.
+See the [Python API guide](docs/python-api.md) for visible removal, the full
+`remove_all` and `remove_batch` pipeline, provenance inspection, metadata
+stripping, and diffusion usage.
 
 ## ComfyUI
 
@@ -226,11 +373,51 @@ invisible removal.
   and selected fill backend.
 - Invisible removal changes the whole image and may alter faces, text, or fine
   detail.
-- `qwen-zimage` requires CUDA. The other diffusion profiles also support the
-  devices listed by `remove-ai-watermarks invisible --help`.
+- Visible video removal recognizes the moving Sora 2 wordmark, the current Veo
+  diamond plus legacy `Veo` text, the Seedance boxed `AI` label, and the fixed
+  Dola, Hailuo, and Kling labels. It does not recognize the older Sora Turbo
+  corner swirl or unregistered layouts from those providers.
+  The classical OpenCV backend can smear structured backgrounds; use MI-GAN or
+  LaMa when recovery quality matters.
+- Video SynthID regeneration changes resolution, frame rate, and image detail.
+  The shipped profile is oracle-certified, but no public local decoder can
+  certify an arbitrary output at runtime. Recheck unusually important outputs
+  after provider changes.
+- Invisible-watermark removal requires CUDA. Both profiles refuse any other
+  device at construction rather than falling back to one that cannot run them.
+  Visible removal, metadata stripping and `identify` still run anywhere.
 - Provider watermark systems can change. Validate important outputs with the
   provider's own verifier when one is available.
 
+The shipped `video invisible` command uses the certified `noise_std=0.15`
+profile. The companion `scripts/video_synthid_sweep.py` research harness builds
+a matched re-encode control plus VAE-regenerated candidates and leaves the
+verifier verdict blank:
+
+```bash
+uv run --extra video --extra diffusion python scripts/video_synthid_sweep.py input.mp4 -o sweep/
+```
+
+To score what an output actually cost, use `scripts/video_fidelity_probe.py`:
+the engine's own PSNR is measured before the resize and the encode, so only the
+probe sees the delivered picture.
+
+```bash
+uv run --extra video python scripts/video_fidelity_probe.py input.mp4 input_clean.mp4
+```
+
+The control must still be SynthID-positive before a negative candidate can
+count as removal evidence. In the 2026-07-29 two-clip calibration, both matched
+controls were positive in Gemini's built-in SynthID verifier; the stronger
+candidate was negative on both carriers, while a weaker candidate was
+negative on one. A later adversarial follow-up that asked ordinary Gemini to
+reinterpret the pixel result returned `UNAVAILABLE`; that follow-up was not a
+verifier rerun and does not invalidate the built-in verdicts. A 2026-07-31
+full-clip check on a public eight-second Veo sample found `0.10` still detected
+and `0.15` not detected, so `0.15` is now the certified default. The
+reproducible hashes and verdicts live in
+`data/evaluations/video-synthid-oracle.csv`.
+
 ## Documentation
 
 Start with the [documentation index](docs/index.md).

data/README.md

@@ -15,6 +15,8 @@ data/
                   Reusable full-pipeline evaluation selection
   evaluations/
     fidelity/     Evaluation instructions and hand-verified ground truth
+    video-synthid-oracle.csv
+                  Reproducible full-clip Gemini SynthID verdicts
 ```
 
 ## Storage rules
@@ -36,3 +38,40 @@ data/
 
 The source distribution excludes `data/`; the wheel contains only package
 runtime assets.
+
+## Video SynthID oracle manifest
+
+`evaluations/video-synthid-oracle.csv` is the only evidence that the shipped
+video removal profile works, so it is also the source of truth for three shipped
+defaults: `tests/test_video_invisible.py` asserts that `noise_std`, `long_side`,
+and `fps` together match a row this manifest records as certified. Changing one
+of those three without adding the row that certifies it fails the suite. `vae` is
+deliberately outside that check because neither tracked row records one; add it
+to the assertion in the same commit as the first row that does.
+
+| Column | Meaning |
+| --- | --- |
+| `date`, `source_url`, `source_sha256` | Identify the carrier. |
+| `source_width`, `source_height`, `source_fps` | Carrier geometry. Without it the actual downscale factor of a row cannot be recovered later. |
+| `duration_seconds`, `source_verdict` | Clip length submitted and the verifier's reading of the untouched carrier. |
+| `vae`, `noise_std`, `long_side`, `fps`, `seed` | The full run configuration. |
+| `output_sha256` | Identifies the exact submitted file. |
+| `output_verdict` | One of `detected`, `not_detected`, `indeterminate`, `refused`. |
+| `output_verdict_text` | The verifier's wording, verbatim. |
+| `output_detected_range` | Time range the verifier reported for the output. |
+| `track` | `visual`, `audio`, `both`, or empty. The verifier scores tracks separately and this path copies source audio unchanged. |
+| `session_id` | Groups rows submitted in one oracle session, so per-session drift stays visible. |
+| `stratum` | Content class of the carrier, for stratified certification. |
+| `psnr_db`, `temporal_residual_ratio` | Fidelity measurements. Neither is a watermark verdict. |
+
+Record `indeterminate` when the verifier answers with its unclear state rather
+than a negative: an unclear reading logged as `not_detected` is exactly the
+silent regression this manifest exists to prevent. Leave a field empty when it
+was not recorded, and never backfill it with a plausible value.
+
+`psnr_db` is measured against the already-resized frame and before the encode,
+so it excludes the downscale, the decimation, and the codec. Rows stay
+comparable to each other only while that definition holds.
+
+The two 2026-07-31 rows predate this schema; their empty fields were never
+recorded and are not recoverable from the row.

data/evaluations/video-synthid-oracle.csv

@@ -0,0 +1,3 @@
+date,source_url,source_sha256,source_width,source_height,source_fps,duration_seconds,source_verdict,vae,noise_std,long_side,fps,seed,output_sha256,output_verdict,output_verdict_text,output_detected_range,track,session_id,stratum,psnr_db,temporal_residual_ratio
+2026-07-31,https://storage.googleapis.com/gdm-deepmind-com-prod-public/media/media/veo__veo-3__off-road.mp4,79a552b9406a079682440c31f14d33a10ba8e1b8b2e96425f5de70f63350299d,,,,8,detected_all_frames,,0.10,512,12,0,079165105d4c56e1612091987c08c2627049423025f74c0d4e245fb47c2ff0e3,detected,,,,,,26.2932,1.0072
+2026-07-31,https://storage.googleapis.com/gdm-deepmind-com-prod-public/media/media/veo__veo-3__off-road.mp4,79a552b9406a079682440c31f14d33a10ba8e1b8b2e96425f5de70f63350299d,,,,8,detected_all_frames,,0.15,512,12,0,1c4046bcfdead138353b4e2a73339ba227bb5e544878d80c5bc6cd8427c7b00e,not_detected,,,,,,25.3911,1.0578

data/synthid/README.md

@@ -56,7 +56,9 @@ Ground-truth quality, strongest first:
 - `gemini-app` — checked via the Gemini app "Verify with SynthID" feature. Gold standard for the pixel watermark (Google models).
 - `openai-verify` — checked via openai.com/verify (gold standard for OpenAI ChatGPT/Codex/API images).
 - `synthid-portal` — checked via Google's SynthID Detector portal.
-- `c2pa-metadata` — issuer-only proxy (Google/OpenAI C2PA manifest present). Weaker: the C2PA can be stripped while the pixel watermark remains.
+- `c2pa-metadata` — supported provenance evidence (Google AI C2PA, or OpenAI
+  C2PA with an explicit `c2pa.watermarked.*` action). Weaker than a provider
+  oracle: C2PA can be stripped while the pixel watermark remains.
 - `third-party` — label asserted by an external dataset, not independently verified.
 - `none` — unverified.
 

docs/cli.md

@@ -9,15 +9,38 @@ remove-ai-watermarks [OPTIONS] COMMAND [ARGS]
 Run `remove-ai-watermarks COMMAND --help` for the complete option list and
 defaults. This page focuses on choosing the right command.
 
+## Command dependency map
+
+| Command or signal | Required installation |
+| --- | --- |
+| `metadata` and metadata-only `identify` | Default package |
+| Visible signals in `identify` | `remove-ai-watermarks[visible]` (`pixels` is the minimal runtime) |
+| Open DWT-DCT signals in `identify` | `remove-ai-watermarks[detect]` |
+| Adobe TrustMark signals in `identify` | `remove-ai-watermarks[trustmark]` |
+| `visible` and `erase` with OpenCV | `remove-ai-watermarks[visible]` (`pixels` is the minimal runtime) |
+| `visible` or `erase` with MI-GAN | `remove-ai-watermarks[migan]` |
+| `visible` or `erase` with big-LaMa | `remove-ai-watermarks[lama]` |
+| `invisible` and `all` (needs CUDA) | `remove-ai-watermarks[qwen-zimage]` |
+| `video metadata` and `video identify --no-visible` | Default package |
+| `video identify` | `remove-ai-watermarks[video]` |
+| `video visible`, `video all`, and visible/all batch modes | `remove-ai-watermarks[video]` plus ffmpeg on PATH |
+| `video invisible` and `video all --invisible` | `remove-ai-watermarks[video,diffusion]` plus ffmpeg on PATH |
+| HEIC/HEIF/AVIF pixel input | Add `remove-ai-watermarks[heif]` |
+| Every production command and backend | `remove-ai-watermarks[all]` |
+
+`batch` requires the same extra as its selected mode. Extras can be combined in
+one installation, for example `remove-ai-watermarks[visible,detect,heif]`.
+
 ## Inspect an image
 
 ```bash
 remove-ai-watermarks identify image.png
 ```
 
-`identify` combines supported metadata and pixel signals into one provenance
-report. When no signal is found, it reports the origin as unknown. It does not
-claim the image is clean.
+`identify` always inspects supported metadata. When pixel extras are installed,
+it also evaluates supported visible and invisible pixel signals. When no signal
+is found, it reports the origin as unknown. It does not claim the image is
+clean.
 
 Machine readable output:
 
@@ -36,6 +59,8 @@ invisible pixel detectors. Metadata inspection still runs.
 
 ## Remove known visible marks
 
+Install `remove-ai-watermarks[visible]` before using `visible` or `erase`.
+
 ```bash
 remove-ai-watermarks visible image.png -o clean.png
 ```
@@ -43,7 +68,8 @@ remove-ai-watermarks visible image.png -o clean.png
 The default behavior:
 
 - checks every registered visible mark;
-- removes every detected match;
+- removes every detected match, except the weakly detected Jimeng label pill,
+  which needs corroboration (see [supported signals](supported-signals.md));
 - selects the best installed fill backend;
 - strips AI metadata from the output.
 
@@ -104,6 +130,13 @@ remove-ai-watermarks erase image.png \
 `erase` accepts `cv2`, `migan`, and `lama`. The corresponding optional extra
 must be installed for a learned backend.
 
+Two more knobs tune the fill. `--dilate N` (default 3) grows every box by `N`
+pixels before inpainting, which helps when a mark has a soft edge or a drop
+shadow just outside the box you measured; it applies to every backend because it
+shapes the mask. `--inpaint-method telea|ns` selects the classical algorithm and
+only affects the `cv2` backend. Like `visible`, `erase` strips AI metadata from
+the output by default; pass `--keep-metadata` to retain it.
+
 ## Strip AI metadata
 
 Inspect metadata:
@@ -125,12 +158,201 @@ The command also supports the audio and video containers listed in
 [supported signals](supported-signals.md). ffmpeg must be available for the
 non-ISOBMFF audio and video path.
 
-## Remove invisible watermarks
+## Identify and clean video
 
-Install the diffusion dependencies first:
+Install the video pixel and timestamp runtime for visible identification,
+removal, and the complete pipeline:
 
 ```bash
-uv tool install --force "remove-ai-watermarks[gpu]"
+uv tool install --force "remove-ai-watermarks[video]"
+```
+
+Inspect every locally supported video signal:
+
+```bash
+remove-ai-watermarks video identify input.mp4
+remove-ai-watermarks video identify input.mp4 --json
+remove-ai-watermarks video identify input.mp4 --no-visible
+```
+
+The default scans the complete clip for stable registered visible marks and
+inspects supported metadata. A result with no signals is reported as unknown,
+not clean, because proprietary pixel watermarks have no public local decoder.
+`--no-visible` performs metadata-only inspection.
+
+Use the complete locally verifiable cleaning path:
+
+```bash
+remove-ai-watermarks video all input.mp4 -o clean.mp4
+```
+
+It removes a stable supported visible mark when found and always strips
+verified AI metadata. When neither signal is found, it writes a same-container
+passthrough instead of returning a missing output. The source is never
+overwritten.
+
+Invisible regeneration is deliberately opt-in:
+
+```bash
+remove-ai-watermarks video all input.mp4 -o clean.mp4 --invisible
+```
+
+That option is supported only for MP4, MOV, and M4V. It is lossy and uses the
+same oracle-certified profile as `video invisible`.
+
+Process all supported files in a top-level directory:
+
+```bash
+remove-ai-watermarks video batch ./videos --mode all
+remove-ai-watermarks video batch ./videos --mode visible
+remove-ai-watermarks video batch ./videos --mode metadata
+```
+
+The batch runs sequentially, preserves successful outputs when another file
+fails, and exits nonzero if any item failed. Visible no-op files are copied
+byte-for-byte so the output directory remains complete. `--invisible` is
+available only with `--mode all`.
+
+## Strip AI metadata from video
+
+Metadata inspection and removal are also available as an isolated operation:
+
+```bash
+remove-ai-watermarks video metadata input.mp4 --check
+remove-ai-watermarks video metadata input.mp4 --remove -o clean.mp4
+```
+
+Supported containers are MP4, MOV, M4V, WebM, MKV, AVI, and FLV. The operation
+delegates to the same verified metadata scanner and stripper as the generic
+`metadata` command, so detection and removal stay in parity. Video and audio
+streams are not transcoded. For MP4 and MOV, this includes the native TC260
+`AIGC` key and JSON value stored in `moov.udta.meta.keys/ilst`. The inspector
+seeks past a large `mdat` to find a tail `moov`. Removal stream-copies the
+container in bounded chunks, converts supported top-level provenance boxes to
+same-size `free` boxes, and blanks the TC260 key/value in place. Box sizes,
+media offsets, and encoded stream bytes do not move; the result is atomically
+published only after the complete copy succeeds.
+
+For MKV and WebM, the inspector reads the native TC260
+`Segment.Tags.Tag.SimpleTag` entry. Removal uses ffmpeg stream copying to
+discard container tags and chapters without transcoding the streams.
+AVI uses the normative `LIST/INFO/AIGC` chunk, while FLV uses the
+`script.onMetaData.AIGC` AMF0 string. Their bounded readers skip media payloads,
+and removal also uses ffmpeg stream copying.
+
+When `-o` is omitted, the command writes `<source>_clean` with the same
+extension. It never overwrites the source, and it rejects an output with a
+different container extension.
+
+Visible video labels and invisible video watermarks are not handled by this
+command.
+
+## Remove video SynthID
+
+```bash
+uv tool install --force "remove-ai-watermarks[video,diffusion]"
+remove-ai-watermarks video invisible input.mp4 -o clean.mp4
+```
+
+The command supports MP4, MOV, and M4V. It samples the complete
+sequence at the configured frame rate, resizes frames to the configured long
+side, regenerates them through a VAE, and applies one deterministic latent-noise
+field to every frame. Reusing one spatial field avoids the unnecessary flicker
+caused by independent per-frame noise. Frames are regenerated in bounded
+batches and streamed directly to ffmpeg, which encodes the result, copies
+audio, and drops source metadata.
+
+The default `noise_std=0.15` profile is oracle-certified. The project has no
+local video SynthID decoder, so an optional per-file recheck is still useful
+for unusually important files or after provider changes. In a new Gemini chat,
+upload the original first, invoke the built-in verifier with `@synthid`, and ask:
+
+> For the video attached to this message, was it created or edited by Google
+> AI? Use the built-in SynthID content verification result.
+
+The source must be positive. Then upload the processed result in a separate new
+chat and repeat the same built-in check. Only a source-positive, output-negative
+pair is a fresh per-file verification. Do not ask an adversarial follow-up that tells the
+chat model to ignore the verifier and reason about raw pixels: that is ordinary
+Gemini reasoning, not a second oracle check.
+
+The default output is `<source>_clean` in the same container. The
+source is never overwritten. Use `--noise-std`, `--long-side`, `--fps`,
+`--batch-size`, `--seed`, and `--device` to control the regeneration. The
+default noise level is `0.15`. It cleared both carriers in the 2026-07-29
+short-clip calibration and the complete public eight-second Veo carrier in the
+2026-07-31 full-clip check; `0.10` remained detected on that complete clip. This
+calibration certifies the shipped operating point; the paired check above is an
+optional runtime audit, not a separate result state.
+
+## Remove a supported visible video mark
+
+```bash
+remove-ai-watermarks video visible input.mp4 -o clean.mp4
+remove-ai-watermarks video visible veo.mp4 --mark veo -o veo_clean.mp4
+remove-ai-watermarks video visible seedance.mp4 --mark seedance -o seedance_clean.mp4
+remove-ai-watermarks video visible dola.mp4 --mark dola -o dola_clean.mp4
+remove-ai-watermarks video visible hailuo.mp4 --mark hailuo -o hailuo_clean.mp4
+remove-ai-watermarks video visible kling.mp4 --mark kling -o kling_clean.mp4
+```
+
+The command supports the moving Sora mascot and wordmark, two Veo
+corner variants, the Seedance boxed `AI` label, the `Dola AI` text label, the
+composite `MINIMAX | hailuo AI` label, and the bottom-right Kling label. Sora
+searches the whole frame at multiple scales. The other detectors search bounded
+lower-frame regions with separate synthetic silhouettes. Kling additionally
+requires its bright low-saturation label near the frame edge. Every mark
+requires a spatially recurring candidate across adjacent frames. Fixed marks
+must also remain anchored instead of drifting with a scene object. Matching
+provider provenance may relax the visual score only for registered
+provenance-aware marks; metadata alone never creates a detection.
+
+`--mark auto` is the default. It evaluates all providers in one decode pass and
+selects the first stable match in specificity order: Sora, Veo, Seedance, Dola,
+Hailuo, then Kling. Their confidence scores are independently calibrated and
+are not compared across providers. Pass an explicit `--mark` to scan only that
+provider.
+
+The video stream is transcoded and the complete original audio stream is
+copied without truncating an audio tail that extends beyond the final video
+frame. The encoder probes the source stream and preserves supported 8-bit
+chroma sampling, color range/matrix/transfer/primaries tags, and MP4/MOV track
+timescale. For a variable-frame-rate source, decoded PTS are carried through a
+timestamped in-memory NUT bridge so the output retains the source frame
+intervals instead of flattening them to a constant rate. A non-zero source
+start PTS and the copied audio start offset are preserved as well.
+Supported input and output containers are MP4, MOV, M4V, WebM, MKV, AVI, and
+FLV; the output extension must match the input. The default `cv2` backend is
+fast but can smear structured backgrounds. Select `--backend migan` or
+`--backend lama` for a learned fill, or `--backend auto` to choose the best
+installed backend.
+
+`--temporal-consistency` is enabled by default. It motion-aligns the preceding
+accepted fill, requires overlapping removal masks and matching source context,
+and blends only the safely covered pixels. Scene cuts, disjoint moving marks,
+or a poor motion match keep the independent current-frame fill. Use
+`--no-temporal-consistency` for an exact frame-local baseline.
+
+The pixel path is intentionally limited to SDR 8-bit video. A high-bit-depth,
+PQ, or HLG source is rejected before ffmpeg starts, preserving any existing
+output instead of silently downconverting it through OpenCV's 8-bit boundary.
+On CPU, MI-GAN is the practical learned tier. LaMa remains an explicit offline
+quality option because full-sequence inference is too slow and memory-heavy
+for an online worker.
+
+AI metadata is stripped from the encoded output by default. Use
+`--keep-metadata` to retain mapped container metadata. When no temporally stable
+mark is found, the command writes no output and exits with the no-visible-mark
+status. The final path is replaced atomically only after ffmpeg completes, so a
+failed encode does not overwrite an existing result.
+
+## Remove invisible watermarks
+
+Install the removal dependencies first. Both profiles are CUDA-only and both
+run the DiffSynth Z-Image face stage, so this is the extra either one needs:
+
+```bash
+uv tool install --force "remove-ai-watermarks[qwen-zimage]"
 ```
 
 Then run:
@@ -150,10 +372,15 @@ remove-ai-watermarks invisible image.png -o clean.png --force
 
 | Pipeline | When to use it |
 | --- | --- |
-| `controlnet` | Default compatibility profile with structural conditioning |
-| `sdxl` | Lighter plain SDXL regeneration |
-| `qwen` | Large CUDA oriented Qwen Image profile |
-| `qwen-zimage` | CUDA only high fidelity profile with a separate face stage |
+| `qwen-zimage` | Default. Qwen-Image-2512 global pass plus a SAM-masked Z-Image face stage |
+| `sdxl-zimage` | The same recipe and face stage on an SDXL global pass, at a higher denoise |
+
+**Both are CUDA-only.** There is no CPU or MPS profile for invisible-watermark
+removal. The former `controlnet`, `sdxl`, `qwen` and `default` profiles were removed
+rather than kept as a CPU path: none of them matched this recipe's face preservation,
+so offering them implied a quality the library no longer delivers. Passing a retired
+name is rejected at parse time rather than remapped. Visible-mark removal and every
+identify path still run anywhere.
 
 Example:
 
@@ -162,8 +389,11 @@ remove-ai-watermarks invisible image.png -o clean.png \
   --pipeline qwen-zimage --force
 ```
 
-The legacy `default` value is an alias for `sdxl`. The `--auto` option is
-deprecated, emits a warning, and changes nothing.
+There is no `--model`, `--steps`, `--guidance-scale` or `--device` option, and the
+deprecated `--auto` is gone. Each profile pins its model stack, its per-stage
+schedule, CFG 1.0 and CUDA, so every one of those flags existed only to be refused
+several layers down. They are not parsed at all now, which fails at the point the
+user can act on rather than after a model load.
 
 ### Work with limited memory
 
@@ -194,6 +424,12 @@ It is a memory strategy, not a guarantee of better quality.
 
 ## Run the full pipeline
 
+The `all` command and the `all` installation extra are separate concepts. The
+command runs every applicable stage. Installing `remove-ai-watermarks[all]`
+makes every production backend available; a smaller installation such as
+`remove-ai-watermarks[visible,qwen-zimage]` can also run the command with fewer
+optional backends.
+
 ```bash
 remove-ai-watermarks all image.png -o clean.png
 ```
@@ -206,10 +442,16 @@ The command runs:
 
 The visible options and diffusion options are also available on `all`.
 
-If diffusion is required but the `gpu` extra is unavailable, `all` still
-writes the result of the visible and metadata stages, prints a prominent
-warning, and exits with code 1. This prevents a partial result from being
-reported as complete.
+When the `qwen-zimage` extra is unavailable, `all` still writes the result of
+the visible and metadata stages, prints a prominent warning, and exits with code
+1. That happens on every run without the extra: the skipped stage is what would
+have decided whether a signal was there. This prevents a partial result from
+being reported as complete.
+
+If the extra is installed but the machine has no CUDA, which is the usual macOS
+case, the run fails at engine construction instead: `all` prints
+`Error: Invisible-watermark removal is CUDA-only ...`, writes no output at all,
+and exits with code 1.
 
 ## Process a directory
 

docs/code-provenance.md

@@ -0,0 +1,9 @@
+# Code provenance
+
+This page records notices required by source dependencies and licensed derivative work.
+
+## Licensed derivative work
+
+- The DWT-DCT implementation derives from ShieldMnt's
+  [`invisible-watermark`](https://github.com/ShieldMnt/invisible-watermark), licensed
+  under MIT. Its notice ships in `src/remove_ai_watermarks/licenses/invisible-watermark-MIT.txt`.

docs/controlnet-removal-pipeline-research.md

@@ -3,7 +3,10 @@
 > Research archive. This document records experiments, superseded defaults, and
 > deployment considerations from the time of the study. It does not define the
 > current CLI or Python API. See `README.md`, `docs/cli.md`, and
-> `docs/known-limitations.md` for current behavior.
+> `docs/known-limitations.md` for current behavior. Everything it names on the
+> face-restoration path was removed after this study: the `--restore-faces` and
+> `--face-id` flags, the `instantid`, `photomaker` and `faceid` extras, and their
+> modules. So were the `controlnet`, `sdxl`, `qwen` and `default` profiles.
 
 Date: 2026-06-02. Source: a manual primary-source pass (WebSearch + WebFetch over the
 watermark-removal-attack and SDXL-ControlNet literature). Prompted by issue #35
@@ -55,8 +58,7 @@ content it protects. Controlnet is the text/structure PRESERVATION pipeline; rem
 is set by STRENGTH, separately calibrated, not by the pipeline choice.
 
 This section is the single consolidated reference for the controlnet pipeline's
-removal behavior. (Mirrored briefly in `docs/synthid.md` §5.5 and the CLAUDE.md
-controlnet / face_restore bullets, which point here.)
+removal behavior. (Mirrored briefly in `docs/synthid.md` §5.5, which points here.)
 
 ### What we measured (real gpt-image + Gemini originals)
 
@@ -211,7 +213,7 @@ regeneration so strokes exceed the VAE's ~8 px latent floor), but ctrlregen runs
 at LOW res, the opposite. CtrlRegen's paper gives no resolution/tiling spec to contradict this.
 
 **Sources.** the former internal
-`src/remove_ai_watermarks/noai/ctrlregen/engine.py` (removed after this study);
+`src/remove_ai_watermarks/_internal/ctrlregen/engine.py` (removed after this study);
 resolution-omission
 confirmed against https://arxiv.org/html/2410.05470v1
 
@@ -288,8 +290,8 @@ text-vs-scrub tension as an empirical question to measure, not assume.
 **Prototype (runs locally on 32 GB MPS — no dedicated GPU required):**
 
 Compute is NOT the bottleneck. On a 32 GB Apple-silicon machine (M5 here) native SDXL already
-runs entirely on MPS with no CPU fallback (~155 s at 1122x1402, verified — see `synthid.md` /
-CLAUDE.md). The prototype runs at **1024** (fewer pixels than that) with SDXL base + an SDXL
+runs entirely on MPS with no CPU fallback (~155 s at 1122x1402, verified 2026-05-31).
+The prototype runs at **1024** (fewer pixels than that) with SDXL base + an SDXL
 ControlNet + activations in **fp32** (MPS fp16 decodes to all-black NaN — issue #29 — confirmed
 on run 1 below; fp32 is the required default on mps/cpu) — fits the 32 GB budget with vae-tiling +
 attention-slicing; ~1-2 min/image, so a coarse sweep is a sub-hour background run. A dedicated GPU
@@ -534,7 +536,8 @@ https://instantid.github.io/ · https://arxiv.org/abs/2308.06721 (IP-Adapter)
 
 ### FaceID prototype run 1 -- 2026-06-03 (NEGATIVE on dense small-face groups)
 
-Built and shipped the masked multi-face FaceID layer (`--face-id`, `face_id.py`, `faceid` extra).
+Built and shipped the masked multi-face FaceID layer (`--face-id`, `face_id.py`, `faceid` extra;
+all three were removed after this run and never reached the tracked tree).
 First real run on the gemini_3 group photo (Google, s015, scale 0.6, native 2816 via cap 1536):
 insightface detected **17 faces**, the masked multi-face pass composed and ran end-to-end (non-black
 output), so the API is correct. **At s015 the result is a clear FAILURE: every face corrupted --

docs/development.md

@@ -0,0 +1,35 @@
+# Development
+
+Read this reference for environment setup, dependency recovery, CI behavior, and fixture policy. The always-loaded invariants remain in [`.claude/rules/development.md`](../.claude/rules/development.md).
+
+## Local environment
+
+- Use `uv sync --frozen --extra dev` and add only the feature extras needed for the task.
+- Do not use `uv pip install` for development tools. It can re-resolve `uv.lock` outside the compatible ML dependency set.
+- A default-only sync removes every pixel and model package by design. Package imports remain light through lazy exports.
+- On an unreliable connection, sync `dev` plus only the required feature extras, such as `diffusion`, and run the checks directly instead of downloading every optional learned backend.
+- Run `uv` from the repository root or it may create a bare environment without the project dependencies.
+
+The optional TrustMark decoder downloads weights into its installed package directory. After pruning that extra, a leftover weights directory can make availability checks see an empty namespace package. If Pyright reports an unknown `TrustMark` import and `find_spec("trustmark")` returns a loader-less spec, remove that regenerable remnant from the active virtual environment and resync.
+
+## CI
+
+`.github/workflows/test.yml` runs Ruff, a cross-platform test matrix over the supported-Python floor and the latest supported minor with default plus development dependencies, and a separate job that installs ffmpeg on Ubuntu to run the full-clip video test. Diffusion and model-running tests skip in that matrix; metadata, identification, visible removal, the DWT-DCT decoder, and the OpenCV eraser remain covered across operating systems.
+
+Keep `uv.lock` compatible with `uv sync --frozen`. Dependency pull-request checks use GitHub's merge result against current `main`; if `main` moves, merge it locally and rerun the full gate because a newer linter can expose stale directives in later code.
+
+Release and distribution behavior is canonical in [`release-and-distribution.md`](release-and-distribution.md).
+
+## Fixture and data policy
+
+[`../data/README.md`](../data/README.md) is the source of truth:
+
+- executable provenance fixtures live under `data/fixtures/`;
+- minimal controlled detector inputs live under `data/calibration/`;
+- canonical provider-oracle originals and their manifests live under `data/synthid/`;
+- evaluation-only ground truth lives under `data/evaluations/`;
+- runtime detector assets live in the package; unregistered research candidates remain outside the shipped wheel.
+
+Store each binary once. Point tests and manifests at its canonical path. Keep generated and cleaned outputs outside the repository and retain only reproducible public records allowed by the data policy.
+
+Use synthetic byte blobs for unsupported format paths and deterministic generated negatives where a real negative fixture is unnecessary. Detection and removal tests must preserve their format-specific invariants.

docs/index.md

@@ -8,7 +8,7 @@ to run the tool. Use the maintainer references only when changing the code.
 | Page | Use it when |
 | --- | --- |
 | [Installation](installation.md) | You need the CLI, an optional model backend, or a development environment. |
-| [CLI guide](cli.md) | You want a command for one image, a directory, or a specific watermark type. |
+| [CLI guide](cli.md) | You want a command for an image, video metadata or visible marks, a directory, or a specific watermark type. |
 | [Python API](python-api.md) | You want to call the package from Python. |
 | [Supported signals](supported-signals.md) | You need to know which visible marks, metadata formats, and invisible signals are covered. |
 | [Known limitations](known-limitations.md) | You need the quality, device, format, or verification boundaries. |
@@ -19,6 +19,8 @@ to run the tool. Use the maintainer references only when changing the code.
 | Page | Purpose |
 | --- | --- |
 | [Module internals](module-internals.md) | Current architecture, invariants, and regression guards by module. |
+| [Development](development.md) | Environment setup, dependency recovery, CI behavior, and fixture policy. |
+| [Code provenance](code-provenance.md) | Required notices for licensed derivative work. |
 | [Verification plan](verification-plan.md) | Verification methods, completed measurements, and remaining validation gaps. |
 | [Release and distribution](release-and-distribution.md) | PyPI, Homebrew, Hugging Face Space, and release workflow. |
 | [Watermarking landscape](watermarking-landscape.md) | Vendor signals and detection approaches. |
@@ -35,4 +37,5 @@ The current behavior is defined by the code, tests, README, and user guides.
 - [Doubao reverse-alpha research](research-doubao-distillation.md)
 - [SynthID identity research](synthid-robust-identity-research.md)
 - [SynthID identity follow-up](synthid-robust-identity-research-2026-06-08.md)
+- [Video SynthID quality research](video-synthid-quality-research.md)
 - [Text protection research](text-protection-research.md)

docs/installation.md

@@ -2,15 +2,17 @@
 
 Python 3.10.1 or newer is required.
 
-## Core install
+## Default metadata mode
 
-The core package provides:
+The default package provides:
 
 - provenance inspection;
-- visible watermark removal with OpenCV;
-- manual region erasing with OpenCV;
 - AI metadata inspection and removal.
 
+It installs Pillow, piexif, and c2pa-python for reading metadata directly from
+files. It does not install NumPy, OpenCV, pillow-heif, Torch, diffusion models,
+or invisible-watermark decoders.
+
 Install it as an isolated command with uv:
 
 ```bash
@@ -29,45 +31,130 @@ You can also install the Homebrew package on macOS or Linux:
 brew install wiltodelta/tap/remove-ai-watermarks
 ```
 
-## Invisible watermark removal
+## Visible watermark removal
 
-Diffusion based removal needs the `gpu` extra:
+Visible mark detection, OpenCV inpainting, and manual region erasing need the
+`visible` extra:
 
 ```bash
-uv tool install --force "remove-ai-watermarks[gpu]"
+uv tool install --force "remove-ai-watermarks[visible]"
 ```
 
-The code supports CUDA, XPU, MPS, and CPU devices. A GPU is recommended because
-CPU inference is slow.
+Add `heif` only when the pixel path must decode HEIC, HEIF, or AVIF:
 
-For the CUDA only Qwen Image plus Z-Image profile:
+```bash
+uv tool install --force "remove-ai-watermarks[visible,heif]"
+```
+
+## Video processing
+
+Video metadata inspection works with the default package, and MP4 and MOV
+stripping uses the in-tree ISOBMFF box walker. Stripping the non-ISOBMFF
+containers (MKV, WebM, AVI, FLV, and the audio formats) and writing any cleaned
+video need ffmpeg on PATH, for example `brew install ffmpeg`. Stable
+visible-mark identification and removal, full video cleaning, and visible/all
+batch modes need the `video` extra:
+
+```bash
+uv tool install --force "remove-ai-watermarks[video]"
+```
+
+The extra includes the visible pixel runtime and PyAV for preserving variable
+frame timestamps. Video SynthID regeneration also needs the diffusion stack:
+
+```bash
+uv tool install --force "remove-ai-watermarks[video,diffusion]"
+```
+
+## Invisible watermark removal
+
+Install the `qwen-zimage` extra:
 
 ```bash
 uv tool install --force "remove-ai-watermarks[qwen-zimage]"
 ```
 
-The `qwen-zimage` extra includes the normal `gpu` dependencies.
+Both remaining profiles run a Z-Image face stage on the DiffSynth runtime, so
+both need this extra. It includes the `diffusion` dependencies; `diffusion` on its
+own covers the torch and diffusers imports but not the face stage, so it is not
+enough to run a removal.
 
-## Optional features
+**An NVIDIA GPU is required.** `qwen-zimage` and `sdxl-zimage` are CUDA-only, and
+construction refuses any other device rather than falling back to a slow or broken
+one. There is no CPU, MPS or XPU path for invisible-watermark removal. Visible-mark
+removal, metadata stripping and every `identify` command still run anywhere.
 
-Install only what you need:
+Video SynthID regeneration is a separate VAE path and does still run on CPU or MPS;
+it needs the `diffusion` extra, not this one.
 
-| Extra | Adds |
-| --- | --- |
-| `migan` | MI-GAN ONNX fill backend |
-| `lama` | big-LaMa ONNX fill backend |
-| `detect` | Open DWT-DCT watermark decoder used by `identify` |
-| `trustmark` | Adobe TrustMark decoder |
-| `esrgan` | Real-ESRGAN upscaling before diffusion |
-| `qwen-zimage` | CUDA only Qwen Image plus Z-Image pipeline |
+## Feature extras
 
-Example:
+Extras are composable. Install only the capabilities and file formats the
+application actually uses:
+
+| Extra | Capability | Automatically includes | Torch or model download |
+| --- | --- | --- | --- |
+| `pixels` | Shared BGR array and image-processing runtime | NumPy, headless OpenCV | No |
+| `heif` | HEIC, HEIF, and AVIF pixel decoding | pillow-heif | No |
+| `visible` | Visible mark detection, OpenCV inpainting, and manual erasing | `pixels` | No |
+| `video` | Visible video identification/removal and timestamp preservation | `visible`, PyAV | No |
+| `detect` | Open DWT-DCT detection for Stable Diffusion, SDXL, and FLUX | `pixels`, PyWavelets | No |
+| `trustmark` | Adobe TrustMark detection | trustmark | Yes |
+| `diffusion` | Torch and Diffusers runtime; video SynthID regeneration | `pixels`, Torch, Diffusers | Yes |
+| `migan` | MI-GAN ONNX fill backend | `visible`, ONNX Runtime | Model download, no Torch |
+| `lama` | big-LaMa ONNX fill backend | `visible`, ONNX Runtime | Model download, no Torch |
+| `qwen-zimage` | Invisible image-watermark removal, both CUDA-only profiles | `diffusion`, DiffSynth | Yes |
+| `all` | Every production feature | All rows above | Yes |
+| `dev` | Tests, linting, typing, and upstream parity checks | `video`, `detect`, upstream invisible-watermark | Yes, for parity tests |
+
+Dependency composition:
+
+```mermaid
+flowchart LR
+    visible --> pixels
+    video --> visible
+    detect --> pixels
+    diffusion --> pixels
+    migan --> visible
+    lama --> visible
+    qwen["qwen-zimage"] --> diffusion
+    heif
+    trustmark
+```
+
+`heif` and `trustmark` are independent branches. Combine them explicitly with
+another feature when required. The `all` bundle contains every production
+branch but never includes `dev`.
+
+Examples:
 
 ```bash
+# Metadata plus torch-free DWT-DCT detection
+uv tool install --force "remove-ai-watermarks[detect]"
+
+# Visible removal with HEIC/AVIF support and MI-GAN
+uv tool install --force "remove-ai-watermarks[migan,heif]"
+
+# Visible video removal with preserved timestamps
+uv tool install --force "remove-ai-watermarks[video]"
+
+# DWT-DCT and TrustMark detection without diffusion removal
+uv tool install --force "remove-ai-watermarks[detect,trustmark]"
+
+# Every production capability
+uv tool install --force "remove-ai-watermarks[all]"
+
+# An arbitrary minimal combination
 uv tool install --force "remove-ai-watermarks[migan,detect]"
 ```
 
-Some optional models download their weights on first use.
+`heif` stays independent so applications that only process PNG, JPEG, or WebP
+do not install libheif. `detect` uses the in-tree torch-free decoder and does
+not install the upstream `invisible-watermark` package. Optional models download
+their weights on first use.
+
+The old `gpu` and `remove` aliases are intentionally not provided. Use
+`diffusion` and `visible` respectively.
 
 ## Install from the repository
 
@@ -81,7 +168,7 @@ Add the feature groups required for your work:
 
 ```bash
 uv sync --frozen --extra dev
-uv sync --frozen --extra dev --extra gpu
+uv sync --frozen --extra dev --extra diffusion
 ```
 
 Run commands from the repository root:
@@ -104,8 +191,10 @@ Run the complete project gate:
 bash maintain.sh
 ```
 
-The script runs dependency checks, linting, formatting checks, type checking,
-and the test suite.
+The script syncs every optional backend on top of the `dev` environment above,
+then runs dependency checks, linting, formatting, type checking, and the test
+suite. It applies Ruff fixes and formatting in place rather than only reporting
+them.
 
 ## Hugging Face authentication
 
@@ -132,5 +221,7 @@ The normal behavior is to skip diffusion when no supported local signal is
 found. A missing signal does not prove that the image is clean. If you know the
 image came from a relevant generator, use `--force`.
 
-If the CLI reports that diffusion dependencies are unavailable, install the
-`gpu` extra.
+If the CLI reports that the removal dependencies are unavailable, install the
+`qwen-zimage` extra. `diffusion` alone covers Torch and Diffusers but not the
+DiffSynth face stage that both profiles run. Video SynthID removal is a separate
+path and needs `video` and `diffusion`.

docs/known-limitations.md

@@ -11,7 +11,8 @@ superseded experiments live in the research archive listed in
 Visible removal changes only the selected mask, but the hidden pixels still
 have to be reconstructed.
 
-- OpenCV is fast and dependency free. It works well on flat backgrounds but
+- OpenCV is fast and requires no model download. It works well on flat
+  backgrounds but
   can smear texture or repeated structure.
 - MI-GAN is a lighter learned backend. It can improve natural texture but may
   ghost or invent structure.
@@ -56,18 +57,19 @@ Invisible removal does not decode and delete a payload. It regenerates the
 image through a diffusion pipeline. Faces, text, colors, and fine detail can
 change even when the watermark is successfully disrupted.
 
-ControlNet is the default compatibility profile. It conditions on edges to
-preserve structure, but edges do not preserve identity or exact texture.
-
-The CUDA only `qwen-zimage` profile adds a separate face stage and is the
-highest fidelity option in the current implementation. It is larger, slower,
-and still may alter small text or difficult faces.
+`qwen-zimage` is the default profile and `sdxl-zimage` the only alternative.
+Both are CUDA only and differ only in the global regeneration model: each
+conditions that stage on a canny edge map, which preserves structure but not
+identity or exact texture, and each then runs the same face stage.
+`qwen-zimage` is the higher fidelity of the two. Both are large, slow, and may
+still alter small text or difficult faces.
 
 ### Removal cannot be verified locally for proprietary SynthID
 
-The project has no public local SynthID pixel decoder. It can infer likely
-presence from supported provenance metadata, but a missing metadata proxy is
-not a negative pixel verdict.
+The project has no public local SynthID pixel decoder. It recognizes presence
+from supported provenance metadata: Google AI C2PA under Google's all-media
+policy, or current OpenAI C2PA with an explicit watermark action. A missing
+provenance signal is not a negative pixel verdict.
 
 For important outputs:
 
@@ -79,45 +81,101 @@ For important outputs:
 Provider systems can change, so a result verified on one file, seed, or version
 is not a permanent certification.
 
+### Video SynthID removal is lossy and content-dependent
+
+The `video invisible` command and `remove_video_invisible` API regenerate video
+pixels through a VAE. The shipped `noise_std=0.15` profile is oracle-certified,
+but Google does not publish a local decoder for arbitrary runtime outputs. A
+quiet metadata scan, paired PSNR, and the temporal-residual metric are fidelity
+measurements, not independent SynthID verdicts.
+
+The control must use the same clip, frame rate, dimensions, and final codec as
+the candidates. The separate `scripts/video_synthid_sweep.py` harness produces
+that matched control. If the control is not detected by the matching provider
+oracle, the experiment cannot attribute a quiet candidate to regeneration.
+
+The 2026-07-29 two-clip calibration used Gemini's built-in content verifier:
+both matched controls were SynthID-positive, the stronger candidate was
+negative on both carriers, and a weaker candidate was negative on one. A
+2026-07-30 adversarial follow-up incorrectly asked the ordinary chat model to
+reinterpret the verifier while excluding every other input; its `UNAVAILABLE`
+answer was not another detector run and does not invalidate the original
+built-in results. The calibrated default remains content-dependent; a fresh
+source-positive, output-negative pair is an optional audit for unusually
+important files or after provider changes.
+
+The 2026-07-31 full-clip check used the public eight-second Veo off-road sample.
+The source was detected across the full clip, the complete product path at
+`noise_std=0.10` remained detected, and `0.15` returned no SynthID detection.
+The default was raised to `0.15`. At 512 px / 12 fps, the accepted candidate
+measured 25.39 dB paired PSNR and a 1.058 motion-compensated temporal-residual
+ratio. This is one carrier, not a universal guarantee; hashes and exact verdicts
+are tracked in `data/evaluations/video-synthid-oracle.csv`.
+
+The shipped engine streams sampled frames in bounded batches, computes its
+fidelity metrics incrementally, and pipes regenerated pixels directly to
+ffmpeg. Its frame and latent memory is therefore bounded by `--batch-size`
+rather than clip duration. Runtime still grows linearly with duration, and the
+separate multi-candidate research sweep deliberately retains its short sampled
+prefix so it can reuse identical latents across candidate strengths.
+
+The reported `psnr_db` is measured against the already-resized frame and before
+the H.264 encode, so it excludes the downscale, the frame decimation, and the
+encoder. It measures the VAE round trip plus latent noise at the working geometry.
+[`video-synthid-quality-research.md`](video-synthid-quality-research.md) records
+what the manifest rows constrain, what a higher-resolution or higher-frame-rate
+profile would need in order to be certified, and the audio-track question this
+path has not yet answered.
+
 ### Strength is content and seed dependent
 
-For SDXL and ControlNet, the CLI resolves an unset strength from the detected
-vendor:
+The two profiles resolve an unset strength differently, because different things
+were measured for each.
 
-- OpenAI: `0.10`;
-- Google: `0.15`;
-- unknown: `0.15`.
+`qwen-zimage` reads it from image area, through the resolution-adaptive denoise
+curve. The vendor is deliberately ignored: the curve, not the issuer, is what was
+calibrated.
 
-An explicit `--strength` overrides these defaults. The defaults are operating
-points, not universal guarantees. Near a removal threshold, different content
-or a different random seed may change the verifier result.
+`sdxl-zimage` reads it from the C2PA issuer, on a flat ladder:
 
-The base Qwen and `qwen-zimage` profiles have profile specific strength
-behavior. Consult `remove-ai-watermarks invisible --help` and the source of
-[`watermark_profiles.py`](../src/remove_ai_watermarks/noai/watermark_profiles.py)
-for the current resolver.
+- OpenAI: `0.15`;
+- Google: `0.25`;
+- unknown: `0.25`, following the stricter of the two.
+
+An SDXL global pass needs more denoise than Qwen at the same fidelity, and the
+values are flat rather than a curve because flat values are what was measured: each
+verdict came from a fixed strength at one size, and no size dependence has been
+established for that stage.
+
+An explicit `--strength` overrides both. The defaults are operating points, not
+universal guarantees. Near a removal threshold, different content or a different
+random seed may change the verifier result, which is why both profiles are
+certified at a fixed seed. The live resolver is
+[`watermark_profiles.py`](../src/remove_ai_watermarks/_internal/watermark_profiles.py).
 
 ### Pipelines have different quality tradeoffs
 
 | Pipeline | Main limit |
 | --- | --- |
-| `controlnet` | Edge conditioning can preserve a watermark carrying region too closely, and faces may drift. |
-| `sdxl` | Flat graphics and precise structure may receive too little or unhelpful change. |
-| `qwen` | Large CUDA oriented model; face smoothing can still be significant. |
 | `qwen-zimage` | CUDA only, large model stack, and limited broad certification across seeds and content. |
+| `sdxl-zimage` | CUDA only. Its strength ladder is flat per vendor, not a resolution curve, because flat values are what was measured. |
 
-The legacy `default` profile name maps to `sdxl`. The `--auto` flag is
-deprecated, emits a warning, and changes nothing.
+The `controlnet`, `sdxl`, `qwen` and `default` profiles were removed, not aliased
+onward: a retired name is rejected at parse time rather than routed into a profile
+the caller never chose. There is no `--model`, `--steps`, `--guidance-scale`,
+`--device` or `--auto` option either; each profile pins its model stack, its
+per-stage schedule, CFG 1.0 and CUDA.
 
 ## Resolution and memory
 
-### Small images are enlarged before SDXL based diffusion
+### Small images are processed at their native size
 
-The SDXL, ControlNet, and base Qwen paths use a default minimum long side of
-`1024`. Smaller inputs are enlarged before diffusion and restored to their
-original dimensions afterward. Set `--min-resolution 0` to disable the floor.
+There is no minimum-resolution floor. It existed to enlarge small inputs toward
+SDXL's ~1024 training resolution and was removed with the SDXL profiles, which
+never applied it anyway. Both surviving profiles run at native geometry, so a
+small input is neither enlarged before diffusion nor restored afterward.
 
-`qwen-zimage` does not apply this SDXL minimum resolution floor.
+`--max-resolution` still caps very large inputs, and only ever scales down.
 
 ### Large images stay at native resolution unless capped
 
@@ -130,23 +188,25 @@ overlapping tiles. It avoids the explicit downscale, but it is not pixel
 lossless: each tile is independently regenerated. With `qwen-zimage`, only the
 global Qwen stage is tiled; the face stage runs after tile blending.
 
-### CPU offload is CUDA only
+### CPU offload trades speed for VRAM
 
-`--cpu-offload` moves Diffusers model components between CPU and CUDA instead of
-keeping the complete standard pipeline in GPU memory. For `qwen-zimage`, it
-forces the face stack to use its offload path.
+`--cpu-offload` forces both stacks of the two-stage profile out of automatic
+device residency, streaming weights instead of pinning them. It reduces CUDA
+memory pressure at the cost of speed.
 
-The option reduces CUDA memory pressure at the cost of speed. It has no effect
-on CPU or MPS and fails loudly when a CUDA Diffusers pipeline does not expose
-the required offload method.
+Residency is otherwise chosen from the card's total VRAM. On a card large enough
+to hold a stack, offloading is pure waste: DiffSynth drops weights to the meta
+device and re-reads every parameter from disk on each stage transition.
 
-### MPS may fall back to CPU
+### There is no CPU or MPS fallback
 
-The SDXL paths include an MPS out-of-memory fallback that reloads on CPU. A run
-that appears much slower after an MPS failure may be continuing on CPU.
+Invisible-watermark removal refuses any device but CUDA at construction. There is
+no MPS out-of-memory fallback that continues on CPU, and no lighter profile to
+drop to: both remaining profiles need an NVIDIA GPU.
 
-Memory needs depend on the pipeline, input size, dtype, and machine. Use tiling,
-a resolution cap, or a lighter pipeline when necessary.
+When a run does not fit, the levers are `--tile` (native geometry, tiled
+diffusion), `--max-resolution` (an explicit downscale), and `--cpu-offload`.
+Memory needs depend on the profile, input size, dtype, and card.
 
 ## Metadata and formats
 
@@ -162,11 +222,13 @@ The metadata path recognizes JPEG XL containers, but the visible and diffusion
 image paths do not list `.jxl` as a supported pixel format because the package
 does not include a JPEG XL pixel decoder.
 
-### HEIC, HEIF, and AVIF use a Pillow fallback
+### HEIC, HEIF, and AVIF pixel decoding uses an optional Pillow fallback
 
 OpenCV does not decode these formats in the project. `image_io.imread` falls
-back to Pillow with `pillow-heif`. A corrupt or truncated file may still fail to
-decode.
+back to Pillow with `pillow-heif` when the `heif` extra is installed alongside
+a pixel feature. The
+default metadata path scans these containers without that plugin. A corrupt or
+truncated file may still fail to decode.
 
 ### Some metadata removal requires ffmpeg
 
@@ -174,11 +236,100 @@ WebM, Matroska, MP3, WAV, FLAC, OGG, Opus, and AAC container metadata is strippe
 through ffmpeg with stream copying. The operation fails if ffmpeg is absent or
 cannot parse the input.
 
+### Video pixel removal is provider-specific
+
+The `video metadata` command and high level video API inspect and strip
+supported AI provenance metadata without transcoding streams.
+
+`video visible` and `remove_video_visible` additionally support the moving
+Sora 2 mascot and wordmark, the current Veo four-point diamond, the legacy
+`Veo` text, the Seedance boxed `AI` label, the fixed `Dola AI` text, the Hailuo
+MINIMAX/Hailuo composite label, and the bottom-right Kling label with its
+version suffix. Detection requires a recurring visual candidate across
+adjacent frames. Fixed-mark candidates must remain anchored rather than
+drifting with a scene object. Kling also requires a bright low-saturation
+candidate near the expected frame edge. Provider provenance can recover
+low-contrast runs only after visual evidence exists for the marks that define a
+provenance prior, so metadata alone does not erase a clean API export.
+The default auto-router evaluates all detectors in one decode pass but does not
+rank their raw confidence values. Those scores are provider-specific and known
+to cross-match in some layouts, so the router applies the independent temporal
+policies and selects the first stable result in specificity order. Use an
+explicit mark when the provider is already known.
+Historical Sora Turbo exports use a small OpenAI swirl in the corner rather
+than the moving mascot-and-wordmark design; that earlier variant is not
+detected by the `sora` video mark. Hailuo and Kling coverage is specific to the
+verified lower-edge layouts; a new provider layout needs a separate calibrated
+silhouette. Other provider video labels are not supported yet. Google video
+SynthID has an oracle-certified VAE removal path, while other proprietary
+invisible video watermarks have no registered attack.
+
+Visible removal transcodes the video stream and copies the complete audio
+stream without shortening an audio tail. Completed visible and invisible
+encodes are published atomically, so an encode failure preserves an existing
+output. Visible removal now applies a guarded motion-compensated blend after
+the per-frame fill. It uses adjacent optical flow only when the warped prior
+mask covers the current mask and a source-context ring agrees; scene cuts and
+disjoint marks keep the independent fill. This reduces measured paired
+temporal error, but it is not a generative video-inpainting model and cannot
+recover structure that no frame exposes. OpenCV can still leave a visible
+smear where the mark overlaps a hard edge or structured texture. MI-GAN
+improves difficult individual frames and is the practical learned CPU tier.
+LaMa remains an offline quality option: a full real sequence confirmed its
+multi-GB memory use and CPU throughput unsuitable for an online worker. The Veo diamond
+uses a shape mask to limit damage outside the symbol. Seedance fills the full
+localized box because a synthetic outline mask left part of the real
+translucent border visible in an end-to-end check. OpenCV may therefore soften
+texture inside that small box; use MI-GAN or LaMa when reconstruction quality
+matters. Relative variable-frame timestamps are preserved through a timestamped
+NUT bridge. A non-zero absolute video start PTS and the corresponding copied
+audio offset are preserved through ffmpeg timestamp passthrough.
+The encoder is source-aware for common 8-bit inputs: it probes and preserves
+supported chroma sampling, recognized color metadata, encoder time base, and
+MP4/MOV track timescale instead of accepting ffmpeg's implicit `yuv444p`
+raw-BGR output. OpenCV still decodes through 8-bit BGR, so HDR/high-bit-depth
+inputs are rejected before encoding rather than silently falling back to
+`yuv420p`. The synthetic
+Sora/OpenCV full-clip CI gate covers complete removal, untouched-region PSNR,
+frame count, frame rate, duration, copied-audio identity, source stream
+properties, paired temporal deltas against an independently encoded
+frame-local baseline inside the filled region, and metadata
+stripping through real ffmpeg. A second synthetic VFR clip verifies all display
+timestamps to the source time-base tick, including a non-zero source start,
+and checks both video and audio stream offsets. A separate constant-rate case
+guards the non-zero-start routing independently of VFR detection. A local
+full-sequence audit over all six providers passed both OpenCV and MI-GAN for
+complete-frame removal, quiet second detection, stream starts, duration, and
+copied audio. A full LaMa sequence passed the same checks but established that
+the backend belongs in the offline tier on CPU. These bounded local checks are
+still not universal evidence for every provider layout or source.
+
+Native TC260 metadata in MP4/MOV is supported at its normative
+`moov.udta.meta.keys/ilst` placement, including non-faststart files whose
+`moov` follows a large media payload. MKV/WebM is supported at the normative
+`Segment.Tags.Tag.SimpleTag` placement and uses ffmpeg for stream-copy removal.
+AVI is supported at `LIST/INFO/AIGC`, and FLV at
+`script.onMetaData.AIGC`; both use ffmpeg stream-copy removal. Stock ffmpeg can
+write and strip the FLV form, but writing the nonstandard AVI child for fixture
+generation requires dedicated muxer support, so the AVI reader is verified
+against an exact synthetic RIFF structure.
+
+MP4/MOV/M4V metadata removal now stream-copies the container in bounded chunks,
+keeps every box size and media offset fixed, and publishes atomically. The
+large-`mdat` regression rejects a full-source `read_bytes()` call and verifies
+that the encoded payload is byte-identical. HEIF/AVIF/JPEG-XL image metadata
+still uses the in-memory path because their XMP/EXIF items may live inside
+`mdat`/`idat` and require bounded format-item parsing before that path can
+stream safely.
+
 ### Metadata transformation is fail safe
 
 `remove_ai_metadata` may copy an undecodable file through unchanged instead of
 raising. User facing callers must use `strip_and_verify` and inspect its
-surviving marker mapping before reporting success. The CLI does this.
+surviving marker mapping before reporting success. `strip_and_verify` recovers
+when `image_io` can still decode the raster by normalizing the container and
+checking again. A truly undecodable file still reports the surviving markers.
+The CLI uses this verified path.
 
 ### Sixteen bit PNG output is not preserved
 

docs/module-internals.md

@@ -53,9 +53,19 @@ The decorators for diffusion options are shared by `invisible`, `all`, and
 `batch`. The runtime help generated by Click is the source of truth for option
 names and defaults.
 
-The deprecated `--auto` option does not select a pipeline or change adaptive
-polishing. [`_resolve_auto_polish`](../src/remove_ai_watermarks/cli.py) emits a
-warning and returns the explicit polish value unchanged.
+`--adaptive-polish` is tri-state: it declares `default=None`, so "the user did not
+choose" is a value the CLI passes through rather than a default it has to invent.
+`resolve_adaptive_polish` in `watermark_profiles.py` turns that `None` into the
+profile's answer (off for `qwen-zimage`, whose output already matches the input's
+detail level; on for `sdxl-zimage`). The same call runs inside
+`InvisibleEngine.remove_watermark`, so a library caller and a CLI caller on one
+profile get the same output.
+
+It used to read Click's parameter source in the CLI instead. That put per-profile
+data in the argument-parsing layer, left the engine declaring the opposite default,
+and silently lost the polish for anything supplying the flag non-interactively (an
+envvar default or a wrapper calling `main()` with a defaulted list is classified
+`DEFAULT`). The seed follows the same rule: the CLI does not pre-resolve it either.
 
 Regression coverage:
 
@@ -65,12 +75,39 @@ Regression coverage:
 
 ## High-level Python API
 
-[`api.py`](../src/remove_ai_watermarks/api.py) provides:
+[`api.py`](../src/remove_ai_watermarks/api.py) provides the visible-mark entry
+points:
 
 - `remove_visible`
 - `visible_provenance`
 
-The package root exposes both lazily through
+and the image pipeline that the `all` and `batch` commands are thin wrappers
+over:
+
+- `remove_all`, returning a `RemoveAllResult` after the visible, invisible, and
+  metadata stages
+- `remove_batch`, returning a `BatchSummary` for one directory and one mode
+- `InvisibleOptions`, the invisible stage's knobs as one immutable value. Engine
+  knobs only, under the engine's own names and defaults, so a bare
+  `InvisibleOptions()` behaves exactly like calling the engine with no arguments.
+  The engine takes them across two callables, `__init__` for what shapes the
+  loaded stack and `remove_watermark` for the per-image ones, so `_run_invisible`
+  forwards each field to the right one rather than splatting the whole bag. Two
+  defaults silently stopped
+  mirroring: `max_resolution=None` reached `_target_size`'s `max_resolution > 0`
+  and raised `TypeError` on every library call, and `cpu_offload=True` made a
+  library run slower than the identical CLI run.
+  `TestInvisibleOptionsMirrorTheEngine` compares the two signatures field by
+  field, and deliberately keeps no exception table: a field needing one is a
+  field that belongs elsewhere. `force` was such a field, and it decides whether
+  the engine runs rather than how, so it is a parameter of `remove_all` and
+  `remove_batch` next to `backend` and `sensitivity`
+- `MetadataStripIncomplete`, raised before any write when AI metadata survives
+
+`remove_all` reports progress as `(stage, detail)` pairs of stable tokens, not
+prose the caller has to parse back.
+
+The package root exposes all of them lazily through
 [`__getattr__`](../src/remove_ai_watermarks/__init__.py), keeping a plain package
 import free of the heavier image and model imports.
 
@@ -86,16 +123,249 @@ Regression coverage:
 - [`test_api.py`](../tests/test_api.py)
 - [`test_image_io.py`](../tests/test_image_io.py)
 
+[`video.py`](../src/remove_ai_watermarks/video.py) provides the high-level
+video entry point:
+
+- `identify_video`
+- `inspect_video_metadata`
+- `remove_video_all`
+- `remove_video_batch`
+- `remove_video_invisible`
+- `remove_video_metadata`
+- `remove_video_visible`
+
+The video API validates both the supported extension and container signature,
+then delegates all metadata detection and stripping to `metadata.py`. It
+requires a separate same-container output, defaulting to `<source>_clean`, so
+the product path does not overwrite an original. The package root exposes all
+functions lazily.
+
+`identify_video` runs the same stable-mark selection helper as
+`remove_video_visible`, so a provenance report cannot authorize a mark that the
+removal path would reject. It reports an empty local result as unknown rather
+than clean. Identification skips the separate per-frame timestamp probe because
+it never encodes frames. `remove_video_all` is the predictable-output
+composition: visible removal plus verified metadata stripping by default, with
+a same-container passthrough when neither signal exists. The lossy invisible
+removal stage is an explicit opt-in through the oracle-certified profile.
+`remove_video_batch` applies those contracts sequentially across a top-level
+directory, returns every per-file failure, and byte-copies visible no-ops so a
+successful output set has no silent holes. An invisible batch loads one VAE
+runtime and reuses it across every compatible file; a failed model load is
+reported per file without retrying the same multi-GB initialization.
+
+Native MP4/MOV TC260 labels follow TC260-PG-20257A:
+`moov.udta.meta.keys` maps an `AIGC` key to a raw JSON value in `ilst`.
+[`_internal/isobmff.py`](../src/remove_ai_watermarks/_internal/isobmff.py) walks those
+nested boxes by seeking, so detection reaches a tail `moov` without reading the
+preceding `mdat`. The MP4/MOV/M4V/M4A removal path first validates the top-level
+box walk, then copies the source to a sibling temporary file in bounded chunks.
+Supported C2PA/JUMBF/AI-label boxes become same-size `free` boxes with blank
+payloads; TC260 removal changes the four-byte key to `free` and blanks only the
+validated JSON value with same-length spaces. This preserves every box size,
+`stco`/`co64` offset, encoded stream byte, and source-sized memory bound.
+Publication is atomic, and a malformed top-level walk is copied unchanged. A
+generic `AIGC` key whose value has no TC260 field is ignored.
+
+[`_internal/ebml.py`](../src/remove_ai_watermarks/_internal/ebml.py) provides the
+corresponding bounded Matroska/WebM reader. It seeks over clusters and accepts
+only a `Segment.Tags.Tag.SimpleTag` pairing `TagName=AIGC` with a JSON
+`TagString` carrying a TC260 field. The existing ffmpeg stream-copy path removes
+those container tags without transcoding the encoded streams.
+
+[`_internal/riff.py`](../src/remove_ai_watermarks/_internal/riff.py) and
+[`_internal/flv.py`](../src/remove_ai_watermarks/_internal/flv.py) implement the remaining
+normative TC260 video placements. The RIFF walker reads only AVI
+`LIST/INFO/AIGC` children. The FLV walker skips media tags and parses the AMF0
+`script.onMetaData.AIGC` string. Both require a recognized TC260 JSON field and
+use the verified ffmpeg stream-copy path for removal.
+
+[`video_encoding.py`](../src/remove_ai_watermarks/video_encoding.py) owns the
+ffmpeg command and pipe lifecycle shared by visible removal and invisible
+regeneration. It centralizes container codecs, optional audio stream copying,
+metadata/chapter policy, encode-failure reporting, and atomic same-directory
+publication. Each mapped stream is allowed to reach its own end, so a copied
+audio tail is not shortened to the frame-input duration.
+Both the raw-BGR and timestamped-NUT stdin modes redirect ffmpeg stderr to a
+temporary file while frames are written. Waiting to read diagnostics until
+after stdin closed allowed stderr backpressure to stop ffmpeg's frame reads,
+which in turn blocked the producer before it could close stdin. The file consumes
+no pipe capacity or RAM while ffmpeg runs; completion reports a bounded head and
+tail when diagnostics are unusually large. Aborts release it even when ffmpeg
+has already exited. A real subprocess regression writes diagnostics beyond pipe
+capacity while streaming frames, checks bounded failure reporting, and the Linux
+full-clip CI job guards the complete path.
+Frame encoding and source-audio copying run as two ffmpeg processes in sequence.
+The streaming encoder has only the frame pipe as input, so input probing or
+demux queues cannot deadlock the producer against a second input. After that
+pipe reaches EOF, a finite stream-copy mux combines the encoded video with the
+source audio and applies the requested metadata/chapter policy. Both stages use
+sibling temporary files, and only the completed mux is published atomically.
+The mux also redirects diagnostics to disk and reports only a bounded head and
+tail. Command regressions assert the single-input encoder and final map targets;
+failure regressions cover bounded mux diagnostics and atomic cleanup.
+`probe_video_encode_profile` reads the first source video stream with ffprobe
+and preserves the supported properties that survive the 8-bit BGR boundary:
+`yuv420p`/`yuv422p`/`yuv444p` chroma sampling, recognized color tags, encoder
+time base, MP4/MOV track timescale, source pixel format, and component depth.
+Both raw-CFR and timestamped-NUT inputs use ffmpeg's passthrough FPS mode. This
+keeps one encoded frame per supplied frame when an older ffmpeg receives a
+fine-grained source encoder time base such as `1/90000`; implicit synchronization
+can otherwise synthesize thousands of duplicate frames between CFR timestamps.
+HDR transfer functions and component depths above 8 bits are rejected before
+encoding so the OpenCV boundary cannot silently reduce them to SDR 8-bit.
+`probe_video_timestamps` reads authoritative per-frame display PTS through
+ffprobe. OpenCV timestamps are only a count-matched fallback when ffprobe is
+unavailable or fails; this avoids decoder anomalies such as one spurious
+negative first-frame timestamp turning a CFR clip into false VFR. A uniform sequence keeps the
+cheap raw-BGR pipe unless the source starts at a non-zero PTS. A variable or
+offset sequence is packetized by the lazy PyAV bridge as rawvideo in an
+in-memory NUT stream with explicit PTS. System ffmpeg reads that stream with
+`-fps_mode passthrough`; `-copyts` additionally retains a non-zero video start
+and the corresponding copied-audio offset. No temporary frame sequence or
+second video encoder is introduced.
+
+[`video_temporal.py`](../src/remove_ai_watermarks/video_temporal.py) owns the
+shared optical-flow maps and temporal residual metric. Visible removal uses
+`stabilize_filled_frame` after the selected image backend: it works on a
+bounded crop around adjacent masks, backward-warps the prior cleaned frame,
+requires high warped-mask coverage, and gates blending on an unmasked
+source-context ring. Only covered current-mask pixels change. Scene cuts,
+disjoint marks, and poor motion matches therefore retain the independent
+current-frame fill. The same module supplies the motion-compensated metric used
+by the invisible-video sweep.
+
+[`video_invisible.py`](../src/remove_ai_watermarks/video_invisible.py)
+implements the oracle-certified video SynthID removal engine. It samples frames
+uniformly, resizes to a VAE-aligned geometry, encodes each frame to latent
+space, applies one seeded spatial-noise field across the entire sequence, and
+decodes fresh pixels. Reusing a single noise field avoids independent
+frame-to-frame noise. The shipped path retains only one configured frame batch,
+updates PSNR and temporal residuals incrementally, and streams BGR frames
+directly to the video-only ffmpeg encoder. A separate stream-copy mux then adds
+optional source audio and drops all source metadata. The result is written
+through same-directory temporary files and atomically replaced only after both
+stages succeed.
+
+The engine returns PSNR and a motion-compensated temporal-residual ratio as
+quality measurements. Neither is a watermark detector. The high-level result
+reports completed removal without a separate verification-status flag. The companion
+`scripts/video_synthid_sweep.py` imports the same engine helpers to build a
+matched control and candidate grid, preventing research and shipped
+regeneration paths from drifting.
+
+The engine's `psnr_db` is measured against the already-resized frame and before
+the encoder, so it scores the VAE round trip plus latent noise and cannot see
+the downscale, the decimation, or the codec. No in-loop metric can: the
+candidate frame is captured before it reaches the encoder pipe.
+`scripts/video_fidelity_probe.py` covers the rest by decoding the delivered file
+after muxing, upscaling it back to the source geometry, and scoring it against
+the untouched source frames. It also reports the delivered file's bitrate, so a
+fixed-crf bitrate rise cannot read as unchanged quality; because the mux copies
+source audio verbatim, that figure is a container bitrate, not a video one. The
+probe streams and accumulates the same way the engine does, so its peak memory
+does not grow with clip length. It drives the source through the engine's own
+`_iter_sampled_frames` at the source geometry rather than repeating the
+selection rule: a frame-count check cannot catch a rule that reorders frames
+without changing how many, so the rule itself has to be shared.
+
+`load_video_vae_runtime` asserts the default model's latent scaling factor
+against `VIDEO_SYNTHID_VAE_SCALING_FACTOR` and warns that no certified profile
+exists for any other model. The published `sd-vae-ft-mse` config carries no
+`scaling_factor` key, so the value is a `diffusers` class default under an
+upper-unbounded pin, and the certified profile is a perturbation-to-signal ratio
+rather than a bare `noise_std`. A library bump that moved that default would
+otherwise rescale every perturbation with a green suite. The validated factor is
+carried on `VideoVaeRuntime` and passed into encode and decode, so the gated
+value and the applied value are one measurement rather than three independent
+reads. `scripts/video_synthid_sweep.py` loads through the same function: the
+harness that produces the certified rows is the last place that should be exempt
+from the gate. The full-clip oracle floor is
+`noise_std=0.15`: on the public eight-second Veo carrier, `0.10` remained
+detected while `0.15` did not.
+
+[`video_visible.py`](../src/remove_ai_watermarks/video_visible.py) implements
+the first pixel stages for Sora, Veo, Seedance, Dola, Hailuo, and Kling. The
+Sora detector searches a normalized frame with a fully synthetic
+mascot-and-text silhouette at several scales. The Veo detector uses separate
+synthetic silhouettes for the current four-point diamond and legacy `Veo`
+text. Seedance uses a synthetic rounded boxed-`AI` silhouette, while Dola uses
+an OpenCV-font `Dola AI` silhouette. Hailuo uses a synthetic waveform,
+MINIMAX/Hailuo text, separator, and ring. Kling combines synthetic font
+variants with a ring approximation of its swirl; the logo path rescues
+wordmarks whose version or font differs, while the edge and white-label gates
+reject recurring scene texture. All fixed-mark searches are bounded to the
+expected lower-frame area and calibrated independently. A strong relocated Veo
+diamond may bypass the known layout anchors, but weak free-corner matches never
+enter the temporal arbiter.
+
+The default `auto` route decodes each frame once, shares its grayscale and
+normalized representations across all detectors, and caches resized synthetic
+template features for the fixed stream geometry. Provider confidence scales
+are not comparable: selection applies each provider's temporal arbiter and
+takes the first stable result in specificity order (`sora`, `veo`, `seedance`,
+`dola`, `hailuo`, `kling`). An explicit mark uses the same scan path with one
+candidate. Removal also collects authoritative per-frame timestamps for the
+encoder, while identification omits that unused ffprobe pass.
+
+Every per-frame result is untrusted. Each provider's floors, minimum-run policy,
+fill padding and mask style are one row in `VISIBLE_MARK_POLICIES`, and every mark
+enters the same `stabilize_localizations` entry point; the recurrence
+implementation underneath knows nothing about providers. That policy row also
+carries `accepts_provenance`, which forces `provenance=False` for Hailuo and Kling
+— they have no metadata that could confirm them, and the guarantee used to be
+structural (their wrappers took no `provenance` parameter at all). Provenance can relax a low-contrast run only
+after recurring visual evidence exists. Sora transition frames follow the
+nearest confirmed moving position only with Sora provenance. Seedance, Dola,
+Hailuo, and Kling additionally require candidates to remain anchored to the
+start of a run. This rejects slowly drifting scene details that still have
+high frame-to-frame overlap. Hailuo and Kling do not infer provenance from
+technical encoder tags; their confirmed public samples carried no provider
+metadata.
+
+Removal runs in a second decode pass. Sora, legacy Veo text, Dola text,
+Seedance, Hailuo, and Kling use box masks. Seedance deliberately fills the
+complete localized box: a synthetic outline mask passed repeat detection but
+left part of the real translucent border visible during visual end-to-end
+review. Hailuo expands beyond the matched core to cover both provider icons.
+Kling expands around the wordmark or swirl to include the version and optional
+`PRO` suffix. The square Veo diamond uses a synthetic shape mask so transparent
+corners do not erase unrelated pixels. Every mask goes through the shared
+`watermark_registry.fill` backends. ffmpeg encodes the changed video stream and
+copies optional audio. The default OpenCV fill is the speed floor; structured
+backgrounds need MI-GAN or LaMa for better reconstruction. Invisible video
+stages must continue to reuse the image and metadata implementations rather
+than copying their logic.
+
+Regression coverage:
+
+- [`test_video.py`](../tests/test_video.py), including a real ffmpeg full-clip
+  Sora/OpenCV path that generates a synthetic marked MP4 with AAC audio and
+  C2PA provenance, runs both `remove_video_visible` and the composed
+  `remove_video_all` API without mocks, and verifies complete removal, frame
+  count, frame rate, duration, untouched-region PSNR, paired temporal deltas
+  inside the filled region, byte-identical copied audio packets, source stream
+  properties, metadata stripping, and a large-`mdat` metadata case that rejects
+  any full-source `read_bytes()` call. CI installs ffmpeg explicitly for this
+  test so the integration gate cannot silently skip.
+- [`test_video_fidelity_probe.py`](../tests/test_video_fidelity_probe.py), which
+  builds its clips from solid-color frames whose index is recoverable from the
+  pixels, so a decimation that keeps the frame count but shifts the phase scores
+  far worse instead of passing unnoticed. It also asserts that the probe binds the
+  engine's sampler rather than a copy of it, and it holds the suite's only
+  constraint on that sampler's phase. Nothing here needs a model, but it does need
+  ffmpeg, so CI runs this file in the same job that installs it.
+
 ## Metadata and provenance
 
 ### C2PA
 
-[`noai/c2pa.py`](../src/remove_ai_watermarks/noai/c2pa.py) reads C2PA with the
+[`_internal/c2pa.py`](../src/remove_ai_watermarks/_internal/c2pa.py) reads C2PA with the
 official `c2pa-python` reader first. Its byte-level PNG parser remains a fallback
 for partial and synthetic fixtures that the official reader rejects.
 
 Vendor attribution comes from the registry in
-[`noai/constants.py`](../src/remove_ai_watermarks/noai/constants.py). Derived
+[`_internal/constants.py`](../src/remove_ai_watermarks/_internal/constants.py). Derived
 issuer and platform maps should not be maintained separately.
 
 ### Metadata scanning and stripping
@@ -105,16 +375,35 @@ metadata scanners and `remove_ai_metadata`.
 
 Key contracts:
 
-- `scan_head` is the shared cached input for bounded byte scans.
+- `scan_head` is the shared cached input for bounded byte scans. It fills the buffer
+  in two layers. Structural readers first, one per container, each seeking past the
+  pixel payload to reach metadata placed beyond the window: `isobmff.scan_c2pa_region`,
+  `_png_late_metadata`, `_riff_late_metadata`. A decoder-backed fallback last,
+  `_decoder_visible_text`, for metadata the raw bytes do not spell at all — a
+  zlib-compressed PNG `zTXt` packet is readable only after inflation. The layers are
+  ordered that way because the structural readers work on files no decoder can open.
+- A C2PA reader failure is logged at warning, not debug. It returns the same `None` as
+  a file with no manifest, so nothing downstream can distinguish "no credentials" from
+  "the credentials could not be read", and the second silently downgrades a verdict.
 - JPEG stripping walks metadata segments and preserves the entropy-coded image
   scan.
 - ISOBMFF containers use
-  [`noai/isobmff.py`](../src/remove_ai_watermarks/noai/isobmff.py).
+  [`_internal/isobmff.py`](../src/remove_ai_watermarks/_internal/isobmff.py).
+- Native MP4/MOV TC260 `AIGC` entries are read from
+  `moov.udta.meta.keys/ilst` and blanked without changing box sizes.
+- Native MKV/WebM TC260 `AIGC` entries are read from
+  `Segment.Tags.Tag.SimpleTag` and removed through the ffmpeg stream-copy path.
+- Native AVI and FLV TC260 entries are read from `LIST/INFO/AIGC` and
+  `script.onMetaData.AIGC`, respectively, then removed through ffmpeg stream
+  copying.
 - Supported non-ISOBMFF audio and video containers use ffmpeg stream copying.
 - The low-level remover is fail-safe and can copy an undecodable file through
   unchanged.
 - A caller that reports success must use `strip_and_verify`, which scans the
-  written output for surviving markers.
+  written output for surviving markers. If the metadata-preserving decoder
+  rejected the container but `image_io` can still decode its raster,
+  `strip_and_verify` normalizes that raster and scans again. A truly undecodable
+  file keeps the surviving-marker result.
 
 Detection and removal must stay in parity. A new marker is incomplete until the
 scanner can find it, the remover can reach every supported placement, and a
@@ -123,14 +412,142 @@ test proves that it no longer appears in the output.
 Regression coverage:
 
 - [`test_metadata.py`](../tests/test_metadata.py)
-- [`test_noai.py`](../tests/test_noai.py)
+- [`test_metadata_internals.py`](../tests/test_metadata_internals.py)
 - [`test_security_clamp.py`](../tests/test_security_clamp.py)
 
 ### Provenance report
 
-[`identify.py`](../src/remove_ai_watermarks/identify.py) combines metadata,
-registered visible marks, and optional open invisible-watermark decoders into a
-`ProvenanceReport`.
+[`identify.py`](../src/remove_ai_watermarks/identify.py) separates file-backed
+metadata extraction from verdict logic:
+
+- `extract_provenance_evidence` reads the supported metadata signals into
+  `ProvenanceEvidence`.
+- `evidence_from_metadata_record` normalizes an externally collected nested
+  metadata record into the same evidence type without file access. Versioned native
+  records accept only source-derived fields; filenames, hashes, timings, errors,
+  prior verdicts, and pixel results cannot become evidence. Unknown native schema
+  versions and other record types are rejected.
+- The vendor registries are matched over `_metadata_region(head)`, not the whole scan
+  buffer: they see the container's metadata and not its coded pixels. The tokens are
+  raw substrings and the shortest are four and five bytes, so over a megabyte of
+  compressed data one turns up by chance, and the entry it hits may assert AI. The
+  trim happens only when the container parses -- a malformed or unknown one is left
+  whole, because dropping real evidence to avoid a chance match is the wrong trade.
+- `identify_from_evidence` evaluates that evidence without reopening the source. Rules
+  that decide a verdict live here, not in extraction: extraction has two
+  implementations, and a rule in only one of them is a rule the other lacks. The
+  SynthID provenance evidence is the worked example — its structured form comes from the manifest,
+  and the byte-scan fallback for containers no parser reaches runs in the verdict, so
+  both extractors reach the same answer. It did not, and the record path silently
+  reported no SynthID for images the file path flagged.
+- `identify` preserves the path-based API and adds the optional registered
+  visible-mark and open invisible-watermark decoders after extraction.
+
+### Portable metadata record
+
+[`metadata_record.py`](../src/remove_ai_watermarks/metadata_record.py) produces the
+record `evidence_from_metadata_record` consumes, so collection and verdict can run
+on different machines. Its contract is equality with the file path, and the three
+defects found while establishing that equality are the reason each rule exists:
+
+- It walks the file's RAW head, never the `scan_head` buffer. That buffer is the
+  head concatenated with late metadata payloads, so a structural walk runs off the
+  end of the real head and parses appended bytes as chunks, inflating the record and
+  creating false signals.
+- Samsung Galaxy AI splits its evidence: the `PhotoEditor_Re_Edit_Data` marker sits
+  in the post-EOI trailer while the `genAIType` value it is gated on can sit inside
+  the entropy-coded scan. A marked file therefore keeps the whole tail window, not
+  just the trailer.
+- PIL's info keys are emitted in the file path's own candidate order
+  (`Software`, `Source`, `Title`, `Description`, then EXIF). `generator_from_metadata`
+  returns the FIRST candidate carrying a known token, so preserving candidate order
+  is part of verdict equivalence.
+
+The transport is independently versioned as `provenance_metadata` schema 1. Native
+records require the exact integer schema version and a `complete` status. Source
+read failures are explicit error records and cannot be judged. WebP walks the full
+declared RIFF container by seeking over `VP8`, `VP8L`, `ALPH`, and `ANMF`, so late
+XMP/C2PA remains visible without shipping coded frames or parsing appended trailer
+bytes as chunks.
+
+Pixel forensics are deliberately absent: the provenance path does not read them.
+Verdict equivalence is checked over tracked fixtures and a separate local evaluation
+corpus.
+
+### Broad forensic metadata
+
+[`forensic_metadata.py`](../src/remove_ai_watermarks/forensic_metadata.py) owns the
+wide metadata-only inspection record: hashes and timestamps, full EXIF/IPTC, C2PA,
+container inventories, bounded binary metadata, and embedded-thumbnail forensics.
+It is a separate `forensic_metadata` record type and is deliberately rejected by the
+provenance normalizer. Integration code publishes the strict
+`ProvenanceReport.to_dict()` alongside it rather than letting operational fields or
+derived results influence detection.
+
+### Pixel forensics
+
+[`pixel_evidence.py`](../src/remove_ai_watermarks/pixel_evidence.py) measures six
+families of scale-robust pixel statistics (block-DCT histograms and Benford
+deviation, FFT band energies and CFA peaks, high-pass residual, error level,
+gradient, color) in a single decode, sharing the intermediate maps between them.
+
+It remains independent of verdict and removal. `PixelEvidence.to_dict()` is the
+versioned service boundary: it omits the local path, exposes complete/partial/error
+status, keeps exception details in logs, and can include opt-in per-stage timings.
+
+The provenance metadata collector, broad forensic collector, provenance report,
+and pixel report all accept an explicit output `schema_version`. Package releases
+may add an output schema while retaining older serializers, so a rolling consumer
+can keep requesting the version it already understands. Within one schema, changes
+are additive; existing fields, types, meanings, signal names, and watermark labels
+remain stable. Unsupported selections raise before a different shape is returned.
+
+`artifacts=True` additionally returns the spatial layer: a perceptual hash, a 128px
+JPEG thumbnail, and coarse ELA, residual and phase maps. Those identify the source
+image rather than describe it, which is why they are opt-in and a separate field: a
+caller storing them is handling image content, not statistics about it.
+
+The DWT-DCT detector and the visible-mark stage share a single decode of the
+source, held by
+a per-call `_SharedDecode`. It exposes two accessors because the two arms need
+opposite failure handling: the visible arm swallows a decode failure (no cv2, no
+visible marks, metadata verdict untouched), while the invisible arm re-raises it
+so `has_invisible_target` reaches its documented fail-safe `True`. Swallowing it
+there would skip a diffusion scrub on a file that used to get one. TrustMark
+deliberately keeps its own Pillow decode: cv2 and Pillow disagree on EXIF
+orientation and on 16-bit PNG, so substituting one for the other is not
+behavior-preserving.
+
+The metadata probes (`aigc_label`, `xai_signature`, `iptc_ai_system`,
+`huggingface_job`, `samsung_genai`) and `extract_c2pa_info` are memoized on
+`(path, mtime_ns, size)`. One `identify` reaches each of them twice, and each
+re-walks the container or re-runs the manifest reader. Size is in the key as well
+as mtime because this package rewrites files in place, and an in-place rewrite
+can land inside one mtime tick. The C2PA key additionally carries the
+reader-availability flag: with the official reader the manifest comes back as a
+store and without it from the PNG chunk parser, so the answer depends on process
+state and not on the file alone.
+
+Native-container TC260 readers (`isobmff`, `ebml`, `riff`, `flv`) all run, in that
+order, on every file. Each self-gates on its own magic bytes after a 4-12 byte
+read, so gating the AVI and FLV ones on the file extension as well was redundant
+and made a correctly formatted container served under the wrong name invisible.
+WebP is the one input class the now-unconditional RIFF reader newly touches; its
+`AVI ` form check is what rejects it.
+
+`api._SourceEvidence` extracts that metadata once per `remove_all` call and serves
+both the visible pass (which vendor is confirmed) and the scrub gate (is there an
+invisible target). It is per-call, never module-level: `batch` may write its
+output over its input, and a holder that outlived one call would answer the scrub
+gate from pre-write evidence. In `batch` each stage builds its own holder after
+any write that precedes it, for the same reason. Every accessor fails safe the way
+the function it replaces does — no provenance means no relaxation, and an unknown
+invisible target means scrub rather than skip.
+
+The `detect` extra composes the shared `pixels` runtime with PyWavelets. Its
+in-tree [`dwt_dct.py`](../src/remove_ai_watermarks/dwt_dct.py) decoder preserves
+the upstream matrix algorithm without installing Torch or non-headless OpenCV.
+The upstream MIT notice ships inside the wheel under `licenses/`.
 
 `is_ai_generated` is `True` or `None`; absence of evidence is not reported as a
 human-made verdict. `ai_source_kind` distinguishes fully generated content from
@@ -169,6 +586,30 @@ The Jimeng pill has an additional decision gate because its visual detector is
 weaker than the other registered marks. Keep that policy in the registry, not
 inside unrelated detector engines.
 
+Everything about a mark is one registry row: its product family, its label regime,
+the platform sentence `identify` reports for it, and the metadata signals that
+confirm its vendor. `identify._VISIBLE_MARK_PLATFORM` and the signal mapping in
+`api.visible_provenance` are derived from those rows rather than hand-maintained
+beside them, so registering a mark is one edit. Two marks carry no platform of
+their own: the Gemini sparkle has its own higher-confidence path, and the
+capture-less pill is too weak to attribute.
+
+The set of marks that veto the pill is DERIVED from the registry rows: every mark
+under the same label regime (`tc260`) belonging to a different product. It used to
+be a hand-written list of keys, and that list drifted -- LibLibAI was registered
+alongside RunningHub and Baidu, both of which were added to it, and LibLibAI was
+not, so a confident LibLibAI detection did not suppress the pill the way its two
+siblings did. Marks outside the TC260 regime (Gemini, Samsung) are deliberately
+not vetoers: neither can put `jimeng` into `provenance`, so neither can enable the
+arm it would be vetoing.
+
+A TC260 label relaxes the vendor its `ContentProducer` names, resolved through
+`KnownMark.tc260_producer_codes`. The label itself is vendor-agnostic, so this used to
+relax ByteDance's two products on every China-AIGC image -- which both risked a
+false fill on an image carrying some other vendor's mark and denied that vendor's
+own mark the relaxed gate its `provenance_ncc_factor` was calibrated for. An
+absent or unmapped producer still falls back to the ByteDance pair.
+
 `remove_auto_marks` removes every selected mark, not only the strongest one.
 This matters for images that carry marks in more than one corner.
 
@@ -212,7 +653,23 @@ be represented by the shared base:
 
 The detector and removal mask must use compatible geometry. A detector that
 fires while producing an empty or misplaced mask is a removal failure even if
-the detection test passes.
+the detection test passes. That parity is now structural rather than a
+convention: the three continuous front ends share one ladder sweep
+(`_ladder_best`), and the winning box travels to the mask on
+`TextMarkDetection.match_box` instead of being swept a second time.
+
+Detection is split into a trust-level-blind `_scan` and a `_verdict` that applies
+the threshold. `detect_both` returns the strict and relaxed verdicts from one
+scan, which is what the arbiter's perception stage calls. A per-mark demotion
+belongs in the `_post_gate` hook, never in a `detect` override: an override is
+invisible to the single-pass path, and the RunningHub and Yuanbao anchor gates
+were briefly skipped there for exactly that reason.
+
+A mark whose removable footprint differs from what the detector localizes
+overrides `_footprint_rect` (which policy) and `_extend_match_box` (how far the
+box grows), not the whole `footprint_mask`. Baidu extends right to the corner tag
+and LibLibAI extends left to the triangle logo; both inherit every guard around
+that arithmetic.
 
 Yuanbao uses the polarity-independent `contrast` front end because its standard
 two-line mark can be light on dark scenes or dark on light scenes. Its detector
@@ -256,48 +713,107 @@ Regression coverage:
 
 ### Profiles and strength
 
-[`noai/watermark_profiles.py`](../src/remove_ai_watermarks/noai/watermark_profiles.py)
+[`_internal/watermark_profiles.py`](../src/remove_ai_watermarks/_internal/watermark_profiles.py)
 is the source of truth for:
 
-- profile aliases;
-- default model identifiers;
-- default steps and seeds;
-- vendor-adaptive strength resolution;
-- the minimum viable step calculation.
+- profile names and their underscore spellings;
+- the fixed seed;
+- the SDXL global-stage checkpoint id (`SDXL_MODEL_ID`) and the Canny ControlNet id;
+- strength resolution for both profiles.
 
-The current profiles are `controlnet`, `sdxl`, `qwen`, and `qwen-zimage`.
-`default` is a legacy alias for `sdxl`. There is no content-dependent automatic
-router.
+The current profiles are `qwen-zimage` (the default) and `sdxl-zimage`, and both
+are CUDA-only. `controlnet`, `sdxl`, `qwen` and `default` were removed rather than
+kept as a CPU path, and are rejected rather than aliased onward. There is no
+content-dependent automatic router.
+
+For serverless cold starts, `InvisibleEngine.preload(global_only=True)` loads the
+mandatory global stage and YuNet while leaving the optional Z-Image and SAM face
+stack lazy until a face is detected. The default `preload()` still loads every
+stage.
+
+**What is deliberately not a parameter.** Model id, step count and CFG are fixed
+by the profile, so none of them appears in `WatermarkRemover.__init__`,
+`remove_watermark`, `InvisibleEngine`, or the CLI. They used to be accepted and
+then rejected several frames down; a signature that refuses the argument outright
+fails where the caller can act on it, and stops a wrapper from threading a value
+that would silently do nothing. The step count and CFG live with the stage that
+runs them (`GLOBAL_STEPS`, `FACE_STEPS`, `GLOBAL_CFG`, `FACE_CFG` in
+`qwen_zimage_pipeline.py`). The dtype is likewise profile-owned: see "Face-stage
+dtype" for what an override cost the last time one existed.
+
+`device` is the exception and remains a library parameter: `None` or `"auto"`
+detect, `"cuda"` pins without detecting (which is what a container that knows its
+hardware wants), and any other value raises at construction. It is not a CLI
+option, because the only useful value a user could type is the one detection
+already returns.
 
 [`invisible_engine.py`](../src/remove_ai_watermarks/invisible_engine.py) handles
-image sizing, optional pre-upscaling, postprocessing, and the public engine
+image sizing, postprocessing, and the public engine
 interface. It delegates model execution to
-[`noai/watermark_remover.py`](../src/remove_ai_watermarks/noai/watermark_remover.py).
+[`_internal/watermark_remover.py`](../src/remove_ai_watermarks/_internal/watermark_remover.py).
 
-The Python engine and CLI do not have identical defaults for every optional
-postprocessing argument. Integrations that require reproducibility should pass
-the relevant values explicitly.
+`get_device` in that module answers only `cuda` or `cpu`. An `mps` or `xpu` answer
+would travel one frame to the same CUDA-only refusal while costing a device probe,
+and reporting it implied an Apple-silicon or Intel-GPU path that does not exist.
+The refusal names the *resolved* device, so `device=None` on a CUDA-less host says
+`'cpu'` rather than `'None'`.
+
+The Python engine and the CLI now resolve the same defaults: the CLI forwards an
+unset `--adaptive-polish` and `--seed` as `None` and the engine applies the
+profile's answer, so a library caller and a CLI caller on one profile produce the
+same pixels. They diverged before, in opposite directions, for exactly this knob.
+
+The global and face prompts are calibrated model inputs, and the Canny edge map
+uses fixed thresholds of `_CANNY_LOW = 13` / `_CANNY_HIGH = 64`
+(`qwen_zimage_pipeline.py`). Treat those values as behavioral compatibility
+contracts: a refactor must preserve them, and any deliberate change requires
+image-quality evaluation rather than only a unit-test pass. The prompt and
+edge-map regression guards are
+`test_qwen_zimage_pipeline.py::test_global_kwargs_use_lightning_and_diffsynth_controlnet_shape`,
+`::test_face_kwargs_use_project_zimage_settings` and
+`::test_canny_control_image_is_three_channel_and_detects_an_edge`.
 
 Regression coverage:
 
-- [`test_watermark_profiles.py`](../tests/test_watermark_profiles.py)
 - [`test_invisible_engine.py`](../tests/test_invisible_engine.py)
-- [`test_img2img_runner.py`](../tests/test_img2img_runner.py)
+- [`test_qwen_zimage_pipeline.py`](../tests/test_qwen_zimage_pipeline.py)
 - [`test_platform.py`](../tests/test_platform.py)
 
 ### CPU offload
 
-CPU offload is enabled only when requested on CUDA. The standard Diffusers
-profiles call `enable_model_cpu_offload`. The `qwen-zimage` profile uses the
-same flag to force its face stack out of automatic device residency.
+CPU offload is enabled only when requested. Nothing calls Diffusers'
+`enable_model_cpu_offload` any more -- that belonged to the deleted single-stage
+profiles. `--cpu-offload` now forces **both** stacks of the two-stage profiles out
+of automatic device residency.
+
+Residency is otherwise chosen from the card's total VRAM, once per stack:
+`resolve_global_model_residency` gates the mandatory Qwen stack at
+`RESIDENT_GLOBAL_MODEL_MIN_VRAM_GIB` and `resolve_face_model_residency` gates the
+optional Z-Image stack at `RESIDENT_FACE_MODEL_MIN_VRAM_GIB`.
+
+Below the global floor, `_qwen_vram_config` streams the stack from disk, which is
+what makes a 20B model runnable on a consumer card. At or above it, streaming is
+pure waste and the weights stay on the GPU. The difference is not marginal:
+DiffSynth offloads by dropping the weights to the meta device and re-reading every
+parameter through its `DiskMap` on the next onload, and the pipeline moves between
+text encoder, transformer and VAE on each pass. Measured on an H100 (80 GiB) in
+August 2026, a warm global pass took 37.3 s at 0.8 GiB resident with the streaming
+config, against 2.2 s at 28.7 GiB with the stack resident; both stacks resident
+peaked at 48.0 GiB. Faster storage cannot close that gap, because the cost is the
+reload itself rather than the read.
+
+The resident config deliberately passes no `"disk"` value anywhere. DiffSynth latches
+`disk_offload` once, from `offload_dtype`, so leaving the sentinel in place while
+pointing every device at CUDA would keep the meta-drop and re-read.
 
 Regression coverage:
 
 - [`test_cpu_offload.py`](../tests/test_cpu_offload.py)
+- [`test_qwen_zimage_pipeline.py`](../tests/test_qwen_zimage_pipeline.py)
 
 ### Qwen plus Z-Image
 
-[`noai/qwen_zimage_pipeline.py`](../src/remove_ai_watermarks/noai/qwen_zimage_pipeline.py)
+[`_internal/qwen_zimage_pipeline.py`](../src/remove_ai_watermarks/_internal/qwen_zimage_pipeline.py)
 implements the fixed CUDA-only two-stage profile:
 
 1. Qwen Image with Canny conditioning regenerates the frame.
@@ -308,6 +824,152 @@ The profile rejects a custom model identifier. Its global and face model stack
 is fixed by the implementation. When tiling is enabled, only the global stage
 is tiled; the face stage runs once after the tiles are blended.
 
+#### How the face stage actually composites
+
+The mechanism is easy to misread from the parameter names, so state it plainly.
+`_run_faces` crops the expanded box from the **original** image, resizes it toward the
+768 px face guide, runs Z-Image over **the entire crop**, resizes back, and only then
+merges through `composite_face`, which cross-fades on a Gaussian-blurred SAM mask with
+`feather=10`. The base it merges into is the global Qwen result.
+
+Two consequences follow, and both matter when tuning:
+
+- **Everything inside the crop is regenerated, including the pixels the mask later
+  discards.** The generation is therefore conditioned on a fully noised neighbourhood,
+  not on an intact one. An alternative design passes the mask into the sampler as a
+  latent noise mask, so only masked pixels are ever denoised and the edge transition
+  happens inside the generation rather than as a post-hoc blend. That approach has
+  never been tried in this runtime and is an open lever, particularly since the face
+  stage is the largest measured quality contributor: removing it costs 3.5 dB inside
+  the face boxes on one fixture and 6.1 dB on another.
+- **`FACE_DENOISE_SCALE = 0.5` is best understood as compensation for the above.**
+  Regenerating a whole crop and blending is a stronger operation than denoising only
+  inside a mask, so the halved strength brings the visible result back into range. Read
+  it as coupled to the compositing design rather than as an independently calibrated
+  constant: changing the compositing without revisiting the scale would change output
+  strength by roughly a factor of two.
+
+The maintained implementation preserves the previously oracle-tested strength,
+conditioning, crop, and sampler parameters as compatibility contracts. Its Python
+orchestration, YuNet integration, SAM selection, masks, sizing helpers, and pixel
+compositing are implemented for this runtime. Changing a calibrated model input
+requires the same provider-oracle and identity evaluation as a model change.
+
+### SDXL plus Z-Image
+
+[`_internal/sdxl_zimage_pipeline.py`](../src/remove_ai_watermarks/_internal/sdxl_zimage_pipeline.py)
+runs the same two-stage recipe on an SDXL global pass. `SdxlZImagePipeline` subclasses
+`QwenZImagePipeline` and overrides only `_run_global` and `preload`, so the face stage
+is inherited rather than copied and cannot drift between the profiles; a test asserts
+the shared methods are the same objects.
+
+Four things are architecture-bound and swap with the model: the ControlNet
+(`xinsir/controlnet-canny-sdxl-1.0`), the four-step distillation LoRA
+(`ByteDance/SDXL-Lightning` at its documented strength 1.0, not the reference graph's
+0.8, which belongs to a different LoRA), the sampler (Euler with trailing spacing, no
+AuraFlow shift), and the latent grid (8 px against Qwen's 16).
+
+**Strength is architecture-bound too, and that is the easy mistake.** An SDXL global
+pass leaves SynthID at the strength Qwen needs: verified through the Gemini app on a
+native 2816x1536 original, 0.154 is FOUND while 0.20, 0.25 and 0.30 are clean. So this
+profile takes a vendor policy (`SDXL_ZIMAGE_OPENAI_STRENGTH` 0.15,
+`SDXL_ZIMAGE_GEMINI_STRENGTH` 0.25, unknown following Gemini) rather than
+`resolution_adaptive_denoise`. Flat values are what was measured; no size dependence
+has been established for this stage, so none is asserted.
+
+`requested_steps` exists because the two runtimes truncate differently. DiffSynth sets
+`sigma_start = denoising_strength` and runs every requested step across the shortened
+sigma range; Diffusers img2img truncates the step *count*
+(`init_timestep = int(steps * strength)`), so asking it for four steps at 0.15 executes
+**zero** and returns a bare VAE round-trip.
+
+**The face stage keeps its own dtype, and 0.23.0 shipped without that.** The remover
+gives this profile `torch.float16`, because SDXL ships fp16 weights and an fp16-safe
+VAE. That dtype reached the inherited `_load_zimage`, while `_zimage_vram_config()`
+hardcodes bfloat16 for its offload, onload and computation dtypes -- so the Z-Image
+modules were built bf16 and handed fp16 latents, and every image containing a face
+died in the VAE with `Input type (c10::Half) and bias type (c10::BFloat16) should be
+the same`. Every face-stage loader now reads `_face_stage_dtype()`, which returns the
+computation dtype of the VRAM config it is paired with, so the two cannot drift again.
+
+Two things hid this. Zero-face inputs never enter `_run_faces`, so the profile looked
+healthy on exactly the images used to time it; and the profile's tests deliberately
+avoid model downloads, so nothing exercised the loader. The lesson is narrower than
+"add a GPU test": inheriting a stage means inheriting its *invariants*, and this one
+was a dtype the subclass silently changed out from under it.
+
+Note what the seam is, because it decides where the fix belongs.
+`SdxlZImagePipeline._load_sdxl` hardcodes fp16 for its own ControlNet, VAE and
+pipeline, so `self.torch_dtype` was never actually the global stage's dtype on this
+profile -- its only remaining readers were face-stage code. SAM was the second one:
+it never crashed, because it casts its own inputs and leaves through `.float()`, but it
+was reading the same wrong field and would have re-landed the bug for the next profile
+with a different global dtype. It is routed through the same accessor, which for
+`qwen-zimage` is the bfloat16 it already used.
+
+The guard is `test_face_stage_loads_in_its_own_dtype_when_the_global_stage_differs`.
+It asserts the dtype the Z-Image and SAM loaders actually receive, not the accessor
+against the config it is derived from -- that comparison would restate the
+implementation and pass for any consistently wrong value. Both assertions were
+mutation-tested against the pre-fix line. For `qwen-zimage` the whole change is a
+strict no-op: the remover already handed it bfloat16, the same value
+`_face_stage_dtype()` returns.
+
+This profile is not deployed. Before it could be, it needs the other three Gemini
+originals, OpenAI re-verified at 0.15, a flat-graphic content class, and a low
+resolution case -- every verdict so far comes from one fixture and one seed.
+
+### Measured provider boundaries for qwen-zimage
+
+Both ends of the shipped curve now have oracle verdicts, and the shipped curve clears
+everything it has been tested at:
+
+| oracle | fixture size | detected at | clean from |
+|---|---|---|---|
+| openai.com/verify | 1.57 MP | 0.06 | 0.08 |
+| Gemini app | 4.33 MP | 0.08 | 0.10 |
+| Gemini app | 0.57 MP | -- | 0.0896 (the curve's own value) |
+| Gemini app | 1.40 MP | -- | 0.1066 (the curve's own value) |
+
+Read the last two rows before concluding the curve's low end is under-driven. Against
+the 4.33 MP Gemini boundary the sub-1 MP rungs of 0.084-0.098 look short, but at those
+sizes the curve's own values verify clean, which is what a resolution-scaled
+requirement would predict. There is no measured size at which the shipped curve fails,
+so it is left alone.
+
+### Static prompt embeddings
+
+Both stages prompt with module constants, and at CFG 1.0 DiffSynth's
+`PipelineUnitRunner` reuses the positive embedding for the negative side instead of
+encoding it. So exactly one embedding per stage is ever computed, from text that
+cannot vary at runtime, which makes it cacheable across containers rather than only
+within one pipeline.
+
+`_cache_static_prompt_embeddings` therefore persists what the text encoder produced
+under `_model_cache_dir()/prompt-embeddings`, keyed by cache version, model id,
+pipeline output params, and the exact prompt string. Once that file exists,
+`_load_qwen` and `_load_zimage` drop the text-encoder `ModelConfig` from the model
+stack entirely and serve the stored tensors instead. Measured on an H100 volume in
+August 2026, that removes **15.45 GiB** (Qwen2.5-VL) and **7.49 GiB** (Z-Image) of a
+**87.6 GiB** per-request read, worth a median **11.76 s** and **4.10 s** of load time
+(paired within five containers). The output is **byte-identical** -- the stored
+tensors are the encoder's own -- so this needs no provider-oracle re-verification.
+
+Three properties are load-bearing:
+
+- **The key self-heals.** A model bump or a prompt edit changes the key, so the next
+  container recomputes rather than reading a stale embedding. `_PROMPT_CACHE_VERSION`
+  covers a change to the stored shape itself.
+- **The write is atomic.** A torn write must never be readable as a cache hit, so the
+  payload lands in a temp file and is renamed into place.
+- **A miss after the encoder was dropped raises.** `require_cache` records that the
+  stack was built without a text encoder on the strength of the file; falling back
+  would call a model that is not loaded, which surfaces as an opaque crash.
+
+`_model_cache_dir()` prefers `HF_HOME` for the same reason: on a scale-to-zero runner
+that is the only persistently mounted path, and anything below it is re-derived per
+request. The YuNet download follows the same root.
+
 Regression coverage:
 
 - [`test_qwen_zimage_pipeline.py`](../tests/test_qwen_zimage_pipeline.py)
@@ -315,32 +977,36 @@ Regression coverage:
 
 ### Tiling
 
-[`noai/tiling.py`](../src/remove_ai_watermarks/noai/tiling.py) contains pure
-tile planning, feather weights, tile orchestration, and region compositing.
+[`_internal/tiling.py`](../src/remove_ai_watermarks/_internal/tiling.py) contains pure
+tile planning, feather weights, and tile orchestration.
 
 Tiling engages only when requested and the long side exceeds the tile size.
 It avoids an explicit full-image downscale but does not make diffusion
 pixel-preserving. Each tile is still regenerated.
 
-`feather_region_composite` changes only the requested box and leaves pixels
-outside it unchanged.
+It also held a `feather_region_composite` for AI-*enhanced* composites, where only
+the edited region should change. Nothing ever reached it: the `erase` command
+inpaints through `region_eraser`, and the remover's `region` argument was only
+reachable from a module-level convenience wrapper with no callers. Both went.
 
 Regression coverage:
 
 - [`test_tiling.py`](../tests/test_tiling.py)
 
-### Upscaling and postprocessing
-
-[`upscaler.py`](../src/remove_ai_watermarks/upscaler.py) is the optional
-Real-ESRGAN path used only when enlarging a small image to the minimum
-resolution floor. Failure or an absent extra falls back to Lanczos.
+### Postprocessing
 
 [`humanizer.py`](../src/remove_ai_watermarks/humanizer.py) contains explicit
 grain, unsharp masking, and adaptive polish helpers.
 
+`upscaler.py` held an optional Real-ESRGAN path, reachable only when enlarging a
+small image to the minimum-resolution floor. That floor existed to lift small
+inputs toward SDXL's ~1024 training size; when the SDXL profiles were removed it
+was forced to 0 on every path, so the module, the `--min-resolution` and
+`--upscaler` options and the `esrgan` extra were all unreachable and went with
+it. Only the `max_resolution` cap can move geometry now, and it only scales down.
+
 Regression coverage:
 
-- [`test_upscaler.py`](../tests/test_upscaler.py)
 - [`test_humanizer.py`](../tests/test_humanizer.py)
 
 ## Image input and output
@@ -355,7 +1021,8 @@ Contracts:
 - `to_bgr` normalizes grayscale and alpha-bearing arrays.
 - `read_bgr_and_alpha` and `write_bgr_with_alpha` preserve the alpha plane.
 - `imwrite` returns a success flag; every caller must check it.
-- HEIC, HEIF, and AVIF fall back to Pillow plus `pillow-heif`.
+- HEIC, HEIF, and AVIF pixel reads fall back to Pillow plus `pillow-heif` from
+  the independent `heif` extra. Metadata scanning does not require that plugin.
 - A visible no-op can preserve the original file bytes.
 
 Regression coverage:

docs/python-api.md

@@ -3,8 +3,19 @@
 Use the high level API for normal application integration. Low level detector
 and pipeline modules are intended for maintainers and specialized workflows.
 
+Dependency groups are identical for the CLI and Python API. The default install
+covers metadata extraction, normalization, verdict logic, and stripping.
+Array/pixel APIs use `pixels`; visible removal uses `visible`; DWT-DCT detection
+uses `detect`; invisible image removal uses `qwen-zimage` and an NVIDIA GPU; and
+visible video processing uses `video`. Video SynthID removal is a separate VAE
+path that still runs on CPU and combines `video` and `diffusion`. Add `heif`
+independently when path-based pixel APIs must decode HEIC, HEIF, or AVIF. See
+the complete [feature-extra matrix](installation.md#feature-extras).
+
 ## Remove visible marks
 
+Install `remove-ai-watermarks[visible]` before using the visible-removal API.
+
 ```python
 import remove_ai_watermarks as raiw
 
@@ -66,8 +77,66 @@ image = cv2.imread("input.png")
 result, removed = raiw.remove_visible(image, backend="cv2")
 ```
 
+## Run the full pipeline
+
+`remove_all` is the library form of the `all` command: visible marks, then the
+invisible watermark, then AI metadata. Stages are chained through a file in the
+system temp directory, so a partial result never appears at the output path.
+
+```python
+import remove_ai_watermarks as raiw
+
+result = raiw.remove_all("input.png", "clean.png")   # -> RemoveAllResult
+print(result.output)          # the path written
+print(result.visible_label)   # the marks removed, or None
+print(result.invisible)       # "removed" | "no-signal" | "unavailable"
+```
+
+`invisible` is the field to check. `"unavailable"` means the GPU extra is not
+installed, so the output *looks* processed but still carries the watermark;
+`"no-signal"` means the scrub was deliberately skipped because nothing was
+locally detectable, which is a successful run.
+
+Pass `InvisibleOptions` to tune the diffusion stage, and `engine` to reuse one
+loaded model across many calls:
+
+```python
+from remove_ai_watermarks import InvisibleOptions
+
+raiw.remove_all(
+    "input.png",
+    "clean.png",
+    invisible=InvisibleOptions(strength=0.35),
+    force=True,
+    progress=print,
+)
+```
+
+`InvisibleOptions` carries only what `InvisibleEngine` itself takes, and uses the
+engine's own parameter names and defaults. `force`, which decides whether the
+engine runs at all, is a parameter of `remove_all` and `remove_batch` alongside
+`backend` and `sensitivity`.
+
+If AI metadata survives the strip, `remove_all` raises `MetadataStripIncomplete`
+**before** writing anything: an AI-readable output is worse than no output.
+
+`remove_batch` runs one mode over a directory and never lets a single bad file
+end the run:
+
+```python
+summary = raiw.remove_batch("in_dir", "out_dir", mode="visible")   # -> BatchSummary
+print(summary.processed, summary.failed, summary.errors)
+print(summary.invisible_unavailable)   # outputs that still carry the watermark
+```
+
+`mode` is `all`, `visible`, `invisible`, or `metadata`. Pass a constructed
+`InvisibleEngine` as `engine` to load the model once for the whole directory.
+
 ## Inspect provenance
 
+The default installation evaluates file metadata. Add `visible`, `detect`, or
+`trustmark` to enable the corresponding optional pixel signals.
+
 Get the vendor keys used by visible removal:
 
 ```python
@@ -88,8 +157,8 @@ print(report.platform)
 print(report.signals)
 ```
 
-Use `check_visible=False` and `check_invisible=False` for metadata only
-inspection:
+Use `check_visible=False` and `check_invisible=False` for metadata-only
+inspection through the compatible path-based API:
 
 ```python
 report = identify(
@@ -99,6 +168,155 @@ report = identify(
 )
 ```
 
+Extraction and detection are also available as separate steps. This is useful
+when a file-reading worker collects the metadata once and another component
+evaluates the resulting evidence:
+
+```python
+from remove_ai_watermarks.identify import (
+    extract_provenance_evidence,
+    identify_from_evidence,
+)
+
+evidence = extract_provenance_evidence(Path("input.png"))
+report = identify_from_evidence(evidence)
+```
+
+### Collect once, judge elsewhere
+
+`collect_metadata_record` splits the two halves apart: it is the only step that
+touches the file, and it returns a JSON-serializable record the verdict can be
+built from on another machine, in another process, or later.
+
+```python
+import json
+
+from remove_ai_watermarks.identify import identify_metadata_record
+from remove_ai_watermarks.metadata_record import collect_metadata_record
+
+record = collect_metadata_record(Path("input.png"), schema_version=1)   # reads the file
+blob = json.dumps(record)                             # ship it anywhere
+
+report = identify_metadata_record(json.loads(blob), path=Path("input.png"))  # reads nothing
+payload = report.to_dict(schema_version=1)            # versioned JSON contract
+```
+
+The collection record has `record_type="provenance_metadata"`,
+`schema_version=1`, and a `status`. A vanished or unreadable source produces an
+`error` record with structured `issues`; `identify_metadata_record` rejects that
+record instead of turning a collection failure into an unknown-image verdict.
+Unknown schema versions, non-integer aliases, and native records without a
+`complete` collection status are rejected explicitly.
+
+The verdict is the same one `identify(path, check_visible=False,
+check_invisible=False)` returns for that file. That equality is the record's whole
+contract and is verified over the tracked provenance fixtures and a separate local
+evaluation corpus. `ProvenanceReport.to_dict()` is the stable service boundary: it
+adds a `schema_version`, contains only JSON-safe values, and deliberately omits the
+local source path.
+
+Package and transport versions evolve independently. Long-lived consumers should
+request the schema they implement, as above, instead of assuming the installed
+package's latest schema. Within schema 1, existing fields, types, meanings,
+`signals[].name` values, and `watermarks[]` labels remain compatible; releases may
+add fields that consumers must ignore. A breaking change requires a new schema while
+the schema 1 serializer remains available for rolling upgrades. Asking a release for
+an unsupported schema raises `ValueError` rather than silently returning another
+shape.
+
+A record carries metadata regions, not the primary coded-pixel stream: marker
+segments before the JPEG scan, every PNG chunk except `IDAT`, RIFF chunks except the
+coded image, the ISOBMFF provenance boxes, the container's trailer, the parsed EXIF tags the
+verdict reads by name, PIL's info mapping, and the C2PA manifest store. Record size
+is bounded by those metadata regions and trailers; images with large embedded
+manifests naturally produce larger records.
+
+The `path` argument is metadata: it labels the report and is never opened by
+either function, so a record collected elsewhere can be judged against a path that
+does not exist locally.
+
+If metadata was collected by another component instead, normalize its nested
+record the same way:
+
+```python
+from remove_ai_watermarks.identify import (
+    evidence_from_metadata_record,
+    identify_from_evidence,
+)
+
+record = {
+    "pil": {"info:parameters": "Steps: 20, Sampler: Euler"},
+    "exif": {"0th": {"Software": "Stable Diffusion"}},
+}
+evidence = evidence_from_metadata_record(record, path=Path("input.png"))
+report = identify_from_evidence(evidence)
+```
+
+Unversioned third-party records are normalized recursively for compatibility. The
+normalizer preserves text and byte values. It also decodes
+strings prefixed with `hex:` and fields named `base64` or ending in
+`_base64`. Diagnostic, transport, timing, hash, provenance-result, and pixel-result
+subtrees are ignored because they describe the collector or a derived result rather
+than the source file. A versioned portable record is stricter still: only
+`metadata_base64`, `tail_base64`, `pil`, `exif`, and `c2pa_store` are accepted as
+source evidence. Other `record_type` values are rejected, so do not pass a broad
+forensic inspection record to this API. Pass a C2PA manifest-store dictionary in
+`record["c2pa_store"]`, or through the explicit
+`c2pa_manifest_store` argument.
+
+### Broad metadata inspection
+
+`collect_forensic_metadata` provides the wide metadata-only record used by forensic
+inspection and migration adapters. It preserves hashes and timestamps, full EXIF and
+IPTC, C2PA, container inventories, bounded raw metadata payloads, and embedded
+thumbnail forensics. It does not calculate a provenance verdict or pixel statistics.
+
+```python
+from remove_ai_watermarks.forensic_metadata import collect_forensic_metadata
+
+record = collect_forensic_metadata(Path("input.png"), schema_version=1)
+assert record["record_type"] == "forensic_metadata"
+```
+
+This record is intentionally not accepted by `identify_metadata_record`. Collect the
+small strict provenance record separately and publish the resulting
+`ProvenanceReport.to_dict()` as the detector contract.
+
+### Pixel evidence
+
+`extract_pixel_evidence` decodes once and calculates the DCT, FFT, residual, ELA,
+gradient, and color families. Its versioned `to_dict()` result has a semantic
+`status`: `complete`, `partial` when an individual family failed, or `error` when the
+source could not be decoded. Transported errors contain only the exception class, so
+local paths stay in the caller's logs rather than crossing the service boundary.
+
+```python
+from remove_ai_watermarks.pixel_evidence import extract_pixel_evidence
+
+pixels = extract_pixel_evidence(Path("input.png"), artifacts=False, timings=True)
+payload = pixels.to_dict(schema_version=1)
+```
+
+Timings and spatial artifacts are opt-in. Artifacts include image-identifying data
+such as a thumbnail and perceptual hash; aggregate feature families do not.
+
+`identify_from_evidence` does not reopen the source file by default: it evaluates
+metadata only, and registered visible marks and pixel-backed invisible watermarks
+remain in the path-based `identify` call.
+
+Pass `image_path` together with `check_visible` or `check_invisible` to add those
+pixel detectors on top of the SAME evidence. That is how a caller asking one file
+two provenance questions — which vendor is confirmed, and is there an invisible
+target — pays for the metadata extraction once:
+
+```python
+from remove_ai_watermarks.identify import extract_provenance_evidence, identify_from_evidence
+
+evidence = extract_provenance_evidence(source)
+metadata_only = identify_from_evidence(evidence)
+with_pixels = identify_from_evidence(evidence, image_path=source, check_invisible=True)
+```
+
 ## Strip metadata
 
 ```python
@@ -119,21 +337,222 @@ if has_ai_metadata(source):
 
 Use `strip_and_verify` when your application reports that stripping succeeded.
 It checks the written output and returns `(output_path, surviving_markers)`.
-Treat a nonempty `surviving_markers` mapping as a failure.
+When the first strip leaves markers in a malformed but raster-decodable image,
+it normalizes the container through `image_io` and checks again. That recovery
+path preserves the pixels but drops standard metadata. Treat a nonempty
+`surviving_markers` mapping as a failure.
 
 `remove_ai_metadata` is the lower level fail-safe transformer. It may copy an
 undecodable input through unchanged, so its return alone must not be presented
 as proof that metadata was removed.
 
+## Identify and clean video
+
+The high level video API supports MP4, MOV, M4V, WebM, MKV, AVI, and FLV:
+metadata-only calls work with the default install, while visible identification,
+removal, and the complete pipeline require `remove-ai-watermarks[video]`.
+
+```python
+import remove_ai_watermarks as raiw
+
+report = raiw.identify_video("input.mp4")
+print(report.is_ai_generated)
+print(report.platform)
+print(report.visible_mark)
+print(report.metadata_markers)
+```
+
+`identify_video` uses the same full-clip temporal arbiter as visible removal.
+It reports a recurring registered mark and supported AI metadata as positive
+signals. When neither is present, `is_ai_generated` is `None`, never `False`.
+The absence of a public local video SynthID decoder is included in `caveats`.
+Pass `check_visible=False` for a bounded metadata-only inspection.
+
+For normal product integration, use the complete locally verifiable pipeline:
+
+```python
+result = raiw.remove_video_all("input.mp4", "clean.mp4")
+if result.remaining_metadata:
+    raise RuntimeError(f"AI metadata remains: {result.remaining_metadata}")
+```
+
+The default removes one stable supported visible provider mark when present,
+always strips verified AI metadata, and writes a same-container output even
+when neither signal is found. This gives callers one predictable output path.
+It does not run lossy invisible regeneration by default.
+
+`include_invisible=True` explicitly adds VAE regeneration for MP4, MOV, or M4V.
+`VideoAllResult.invisible_removed` reports whether the oracle-certified SynthID
+stage ran.
+
+Process a top-level directory sequentially:
+
+```python
+batch = raiw.remove_video_batch("videos", "videos_clean", mode="all")
+if batch.failed:
+    for item in batch.items:
+        if item.error:
+            print(item.source, item.error)
+```
+
+Batch modes are `all`, `visible`, and `metadata`. Successful visible no-ops are
+copied byte-for-byte, keeping the output directory complete. Per-file failures
+are returned in `VideoBatchItem.error`; they do not discard successful outputs.
+The invisible stage is available only as an explicit opt-in in `all` mode and
+reuses one loaded VAE runtime across the batch.
+
+## Inspect and strip video metadata
+
+Metadata inspection and removal use the same supported video containers:
+
+```python
+import remove_ai_watermarks as raiw
+
+report = raiw.inspect_video_metadata("input.mp4")
+if report.has_ai_metadata:
+    result = raiw.remove_video_metadata("input.mp4")
+    if result.remaining:
+        raise RuntimeError(f"AI metadata remains: {result.remaining}")
+```
+
+`remove_video_metadata` does not transcode video or audio streams. Its default
+output is `input_clean.mp4`, leaving the source untouched. An explicit output
+must use the same container extension as the source.
+
+The returned `VideoMetadataResult` records the source, output, metadata detected
+before removal, and any markers remaining after the verified strip. MP4/MOV
+inspection recognizes the native TC260 `AIGC` entry in
+`moov.udta.meta.keys/ilst`; its removal preserves container size and encoded
+stream bytes. MP4/MOV/M4V are copied in bounded chunks, so a large `mdat` is not
+loaded into memory; publication is atomic. MKV/WebM inspection recognizes the corresponding
+`Segment.Tags.Tag.SimpleTag` representation; its removal requires ffmpeg for a
+stream-copy remux. AVI inspection reads `LIST/INFO/AIGC`, and FLV inspection
+reads `script.onMetaData.AIGC`; both use the same verified ffmpeg stream-copy
+removal path.
+
+## Remove video SynthID
+
+Install `remove-ai-watermarks[video,diffusion]` before using the video SynthID
+API.
+
+```python
+import remove_ai_watermarks as raiw
+
+result = raiw.remove_video_invisible(
+    "input.mp4",
+    "clean.mp4",
+    device="auto",
+)
+if result.remaining_metadata:
+    raise RuntimeError(f"AI metadata remains: {result.remaining_metadata}")
+```
+
+`remove_video_invisible` supports MP4, MOV, and M4V. It regenerates the complete
+video through a VAE in bounded batches, shares one seeded latent-noise field
+across all frames, streams pixels to ffmpeg, copies complete audio, strips
+source metadata, and publishes atomically. The default output is
+`input_clean.mp4`; a distinct same-container output is required.
+
+The returned `VideoInvisibleResult` includes output geometry, frame rate, frame
+count, paired PSNR, and the motion-compensated temporal-residual ratio. Those
+fields measure fidelity and flicker only. They are not a SynthID detector.
+The default `noise_std=0.15` is the current full-clip oracle floor; `0.10`
+remained detected on the public eight-second Veo calibration carrier.
+The default profile is oracle-certified. Google does not publish a local
+decoder for this video payload, so a fresh source-positive, output-negative
+pair from Gemini's built-in SynthID verifier remains an optional per-file audit.
+A response inferred from a visible logo or metadata is not such a verdict, and
+an adversarial follow-up asking ordinary Gemini to reinterpret the verifier is
+not a second oracle run.
+
+## Remove a supported visible video mark
+
+```python
+import remove_ai_watermarks as raiw
+
+result = raiw.remove_video_visible(
+    "input.mp4",
+    "clean.mp4",
+    backend="cv2",
+    strip_metadata=True,
+    temporal_consistency=True,
+)
+if result.output is None:
+    print("No temporally stable supported mark was found")
+else:
+    print(result.mark)
+
+veo_result = raiw.remove_video_visible(
+    "veo.mp4",
+    "veo_clean.mp4",
+    mark="veo",
+)
+seedance_result = raiw.remove_video_visible(
+    "seedance.mp4",
+    "seedance_clean.mp4",
+    mark="seedance",
+)
+dola_result = raiw.remove_video_visible(
+    "dola.mp4",
+    "dola_clean.mp4",
+    mark="dola",
+)
+hailuo_result = raiw.remove_video_visible(
+    "hailuo.mp4",
+    "hailuo_clean.mp4",
+    mark="hailuo",
+)
+kling_result = raiw.remove_video_visible(
+    "kling.mp4",
+    "kling_clean.mp4",
+    mark="kling",
+)
+```
+
+`remove_video_visible` scans the complete video before writing output. It
+combines synthetic multi-scale visual matching with temporal consistency, so an
+isolated lookalike in one frame is not enough to authorize inpainting.
+`mark="auto"` is the default: it evaluates all providers in one decode pass and
+selects the first stable match in specificity order (`sora`, `veo`, `seedance`,
+`dola`, `hailuo`, `kling`). Provider confidence values are calibrated
+independently and are not compared across detectors. Pass one of those explicit
+values to restrict the scan to a single provider. The Veo detector recognizes
+the current four-point diamond and the
+legacy `Veo` text. Seedance recognizes the boxed `AI` label, Dola recognizes
+its compact text label, Hailuo recognizes the composite MINIMAX/Hailuo label,
+and Kling recognizes its bottom-right logo, wordmark, and version suffix. Each
+variant has an independent synthetic silhouette and calibrated temporal policy.
+After each accepted frame is filled, `temporal_consistency=True` motion-aligns
+the preceding accepted fill and blends it only when the warped prior mask
+covers the current mask and a surrounding source-context ring agrees. Scene
+cuts and disjoint masks keep the independent current fill. Pass
+`temporal_consistency=False` for the frame-local baseline.
+
+The returned `VideoVisibleResult` records the selected `mark`, the total,
+detected, and removed frame counts, plus any AI metadata that survived the
+output encode. The function returns `output=None` and writes no file when no
+stable mark is selected. Video pixels are transcoded through ffmpeg while the
+complete source audio stream is copied. The encoder preserves supported 8-bit
+source chroma sampling, color tags, MP4/MOV track timescale, and relative
+variable-frame timestamps. It also retains a non-zero source start PTS and the
+copied audio offset. A failed encode preserves any existing output; only a
+completed result is published atomically.
+SDR 8-bit video is the supported pixel contract. High-bit-depth, PQ, and HLG
+sources raise `RuntimeError` before encoding instead of being silently reduced
+to 8-bit SDR.
+
 ## Remove invisible watermarks
 
+Install `remove-ai-watermarks[qwen-zimage]`. Both profiles need it, and both
+need an NVIDIA GPU.
+
 ```python
 from pathlib import Path
 
 from remove_ai_watermarks.invisible_engine import InvisibleEngine
 
 engine = InvisibleEngine(
-    pipeline="controlnet",
+    pipeline="qwen-zimage",  # the default; the only other value is "sdxl-zimage"
     device=None,
     cpu_offload=False,
 )
@@ -144,29 +563,35 @@ engine.remove_watermark(
 )
 ```
 
-`device=None` selects the device automatically. Supported explicit values are
-defined by the CLI and runtime device resolver.
+`device=None` and `device="auto"` both run detection. `"cuda"` pins it without
+detecting. Every other value raises at construction rather than deferring a
+guaranteed failure to model-load time.
 
 For limited CUDA memory:
 
 ```python
 engine = InvisibleEngine(
-    pipeline="controlnet",
+    pipeline="qwen-zimage",
     cpu_offload=True,
 )
 ```
 
-For the CUDA only high fidelity profile:
+Both profiles are CUDA-only, so on a machine without an NVIDIA GPU `device=None`
+resolves to `cpu` and construction raises. For the SDXL global stage instead of
+Qwen:
 
 ```python
-engine = InvisibleEngine(pipeline="qwen-zimage")
+engine = InvisibleEngine(pipeline="sdxl-zimage")
 ```
 
-The `qwen-zimage` extra must be installed for that profile.
+The `qwen-zimage` extra is required for both profiles: each runs the same
+DiffSynth Z-Image face stage.
 
-The full `remove_watermark` signature includes strength, steps, guidance,
-seeding, tiling, resolution, upscaling, and postprocessing controls. Read the
-method signature in
+`remove_watermark` takes strength, seed, tiling, resolution, and postprocessing
+controls. It takes no model id, step count or guidance scale, and neither does the
+constructor: each profile pins its model stack, its per-stage schedule and CFG
+1.0, so passing one raises `TypeError` at the call rather than being accepted and
+refused several layers down. Read the method signature in
 [`invisible_engine.py`](../src/remove_ai_watermarks/invisible_engine.py) or use
 the CLI guide for the concepts.
 Defaults can differ between the Python method and CLI profile resolution, so

docs/qwen-improvement-research.md

@@ -79,13 +79,13 @@ Measured on `gemini_3` (18 faces) at the Gemini scrub floor 0.25 vs base-Qwen 0.
 a Qwen face fix. The next distinct architecture was Z-Image-Turbo on original masked face
 crops, not another Qwen geometry conditioner.
 
-**Implementation follow-up (2026-07-24):** that distinct architecture now exists as the
-manual `qwen-zimage` profile. It ports the upstream Synthid-Bypass v2 graph: Qwen-Image-2512
-Lightning + DiffSynth Canny for the full frame, then SAM-masked Z-Image Turbo regeneration
-from original face crops. The upstream result supplied by the user was Gemini-oracle negative.
-The active upstream face path is YOLO + SAM, not the unconnected MediaPipe node. The port
-matches its center-point + box prompts, IoU-0.93 proposal selection, detector-box intersection,
-crop factor, and paste feather; YuNet is the intentional detector substitution.
+**Implementation follow-up (2026-07-24, revised 2026-07-31):** an early experimental
+`qwen-zimage` prototype reproduced a broad two-stage shape demonstrated by a public
+experiment: structure-guided Qwen regeneration followed by masked Z-Image face
+refinement. The maintained profile was subsequently
+rewritten with project-owned prompts, adaptive strength and sizing policies, YuNet face
+detection, SAM selection, masks, and compositing. It does not include the upstream workflow
+JSON or source code. The upstream result supplied by the user was Gemini-oracle negative.
 
 The first exact-path Modal run completed without SAM fallback or face seams. On one crowded
 18-face `gemini_3` fixture, ArcFace identity improved materially over controlnet
@@ -108,7 +108,7 @@ checked all six current outputs in the provider-separated
 oracles and confirmed that none retained SynthID or the provider generation signal. The
 checked bytes used the complete `visible -> qwen-zimage -> metadata` route, the calibrated
 YuNet 0.5 gate, and the shipped prompt-cache/model-residency optimizations. This supersedes
-the earlier first-port batch check as the release-candidate result, but it is not a
+the earlier prototype batch check as the release-candidate result, but it is not a
 certification across seeds, resolutions, and content classes. YuNet's threshold was
 calibrated independently from upstream YOLO: 0.5 retained the visible faces in the
 comparison fixtures while removing the false and duplicate boxes admitted by the copied

docs/release-and-distribution.md

@@ -43,6 +43,7 @@ PyPI API token from the repository.
 waits for the matching source distribution to appear on PyPI, then:
 
 - updates the Homebrew tap formula URL and SHA-256;
+- updates the repository conda recipe version and source-distribution SHA-256;
 - triggers a factory rebuild of the Hugging Face Space.
 
 The workflow can also be started manually with an optional version input.
@@ -52,14 +53,28 @@ If a distribution job fails because a repository or Hugging Face credential is
 invalid, rotate the corresponding GitHub secret and rerun the failed job. A
 manual Homebrew formula update is the fallback when its automation is blocked.
 
+The conda job uses the published artifact rather than a locally built archive
+as the hash source and commits the resulting recipe change to `main`. Runtime
+dependency mapping remains review-controlled: keep it aligned with the default
+metadata dependencies in `pyproject.toml`, do not copy optional pixel extras
+into the default recipe, and document any conda-forge package that is
+unavailable and must be omitted.
+The optional `video` extra carries PyAV with Python-version-specific bounds; it
+does not belong in the default metadata-focused conda recipe.
+
 ## Source distribution boundary
 
 The wheel includes the package under `src/`.
 
-The source distribution explicitly excludes `/data` through
-`[tool.hatch.build.targets.sdist]` in `pyproject.toml`. Keep that exclusion:
-calibration captures and test corpora do not belong in the published package
-archive.
+The source distribution uses an explicit allowlist for `/src`, `/LICENSE`,
+`/README.md`, and `/pyproject.toml` through
+`[tool.hatch.build.targets.sdist]` in `pyproject.toml`. It also defensively
+excludes `/data`, `/tmp`, and `/.sc`. Keep both controls: calibration captures,
+test corpora, generated research outputs, and local session state do not belong
+in the published package archive. Hatchling always adds the root `.gitignore` to
+the sdist, so keep its comments generic and free of local operational context.
+Ignore rules are not the build boundary: `data/` is deliberately tracked, while
+the sdist configuration keeps it and the other excluded paths out of the archive.
 
 ## Build backend
 
@@ -69,17 +84,35 @@ The package uses hatchling through the unpinned `hatchling` build requirement in
 ## Other channels
 
 The repository includes a conda recipe under `packaging/conda/recipe.yaml`.
-Keep its runtime dependencies aligned with `pyproject.toml`.
 
-The ComfyUI nodes are maintained and versioned separately from this package.
-A library release does not by itself publish a new ComfyUI node version.
+The ComfyUI nodes are maintained and versioned in their own repository. After
+the matching source distribution appears on PyPI, `distribute.yml` dispatches
+that repository's sync workflow with the exact library version and waits for it
+to finish. The sync updates the dependency floor, runs compatibility tests,
+bumps the node patch version, and publishes to the ComfyUI Registry only when
+those tests pass. Its daily schedule remains as a recovery path if a release
+dispatch is interrupted. The `COMFYUI_RELEASE_TOKEN` repository secret is a
+fine-grained token limited to the ComfyUI node repository, with Actions read and
+write access.
 
 ## Release verification
 
+Forensic transports are versioned independently from the package. Before publishing
+a change to provenance metadata, provenance reports, broad forensic metadata, or
+pixel evidence, run their schema 1 contract tests. Additive fields are compatible;
+renaming a field, changing its type or meaning, changing a signal name or watermark
+label, or removing a field requires a new output schema. Add the new serializer
+without removing schema 1 so long-lived consumers can update separately. A package
+release must never silently substitute its latest schema when a caller explicitly
+requests an older supported one.
+
 After publication, verify:
 
 - both wheel and source distribution exist on PyPI;
 - the package version matches the tag;
 - the Homebrew formula points to the new source distribution;
 - the distribution workflow completed successfully;
+- the repository's conda recipe matches the published version and source
+  distribution;
+- the ComfyUI Registry node requires the new library version;
 - a clean install can run `remove-ai-watermarks --version`.

docs/research-doubao-distillation.md

@@ -26,7 +26,7 @@ color still leaves a persistent ghost outline.
 
 Diagnosed why, empirically (cached stacks, `/tmp/doubao_distill`): (1) the mark is a clean white overlay with **no dark halo** -- over glyph pixels ~54% are brighter than the clean bg, only ~4% darker -- so the white-logo model `I=(1-α)O+α·255` is correct; (2) but content backgrounds are almost never dark *under* the mark (median darkest available bg over glyph pixels = **58/255**; only ~13% of mark pixels are ever observed on a bg < 40), so on bright backgrounds the equation is ill-conditioned and `α` is unidentifiable; (3) LaMa's `O` is a plausible **hallucination**, not the true pre-mark background, which compounds the error, and per-pixel regression on ~15 obs overfits into color noise.
 
-**Why Gemini's engine is clean (verified in GeminiWatermarkTool `src/core/watermark_engine.cpp`): its alpha map is the watermark stamped on a PURE-BLACK background**, where `watermarked = α·255 + (1-α)·0 = α·255`, so `alpha = capture/255` exactly -- no estimation. (`gemini_bg_*.png` is literally the sparkle in gray on black.) So the real Doubao unlock is the same controlled capture, **not more content images**. The retained black and gray outputs live in `data/calibration/doubao/`; local solid-color seeds are regenerable and are not committed.
+**Why Gemini's engine is clean: its alpha map is the watermark stamped on a PURE-BLACK background**, where `watermarked = α·255 + (1-α)·0 = α·255`, so `alpha = capture/255` exactly -- no estimation. (`gemini_bg_*.png` is literally the sparkle in gray on black.) So the real Doubao unlock is the same controlled capture, **not more content images**. The retained black and gray outputs live in `data/calibration/doubao/`; local solid-color seeds are regenerable and are not committed.
 
 **Until black captures arrive, the shipped direction is precise canonical glyph mask + inpaint (cv2 default, lama optional), NOT reverse-alpha.**
 

docs/supported-signals.md

@@ -29,13 +29,34 @@ the masked area.
 Marks from other vendors are not detected automatically. Use `erase --region`
 when you can select the affected area yourself.
 
+### Visible video marks
+
+| Key | Mark | Motion | Important limit |
+| --- | --- | --- | --- |
+| `sora` | Sora 2 mascot and wordmark | Moves among frame positions | Requires a temporally recurring visual match; the older Sora Turbo corner swirl is a different unsupported mark. |
+| `veo` | Current four-point diamond and legacy `Veo` text | Fixed bottom-right corner | Uses separate silhouettes and requires a recurring match; learned fill is preferable on structured backgrounds. |
+| `seedance` | Boxed `AI` label | Fixed bottom-right corner | Requires an anchored recurring match; the full localized box is filled because a thinner synthetic shape mask leaves the real translucent rim behind. |
+| `dola` | `Dola AI` text | Fixed bottom-right corner | Requires an anchored recurring match; ByteDance or BytePlus provenance can relax only an existing visual run. |
+| `hailuo` | `MINIMAX \| hailuo AI` composite label | Fixed lower edge | Uses a synthetic waveform, text, separator, and ring silhouette; the complete recurring label box is filled. |
+| `kling` | Kling swirl, `KLING AI`, version, and optional `PRO` suffix | Fixed bottom-right edge | Combines a synthetic logo rescue with font variants, an edge gate, a white-label gate, and anchored temporal recurrence. |
+
+`video identify`, `video visible`, and `video all` share this registry and the
+same temporal arbiter. It is separate from the image registry because selection
+is made over a sequence rather than one raster. The default `auto` mode scans
+all six entries in one decode pass and selects the first temporally stable
+match in table order; an explicit mark restricts the scan to that row.
+Accepted fills are motion-aligned across adjacent frames by default. The prior
+fill contributes only where its warped mask covers the current removal mask and
+nearby source context agrees. Scene cuts or disjoint marks retain the
+independent frame fill.
+
 ## Fill backends
 
 | Backend | Install | Behavior |
 | --- | --- | --- |
-| `cv2` | Core package | Classical OpenCV inpainting |
-| `migan` | `remove-ai-watermarks[migan]` | MI-GAN through ONNX Runtime |
-| `lama` | `remove-ai-watermarks[lama]` | big-LaMa through ONNX Runtime |
+| `cv2` | `remove-ai-watermarks[visible]` | Classical OpenCV inpainting |
+| `migan` | `remove-ai-watermarks[migan]` | MI-GAN through ONNX Runtime; practical learned CPU video tier |
+| `lama` | `remove-ai-watermarks[lama]` | big-LaMa through ONNX Runtime; offline video quality tier |
 | `auto` | Depends on installed extras | Selects LaMa, then MI-GAN, then OpenCV |
 
 The learned backends download model files on first use.
@@ -48,7 +69,10 @@ The inspection and stripping code handles signals in these groups:
 - EXIF and XMP generator fields;
 - IPTC AI disclosure fields;
 - PNG text chunks and embedded generation parameters;
-- China TC260 AIGC labels in supported metadata placements;
+- China TC260 AIGC labels in supported image placements and the normative
+  MP4/MOV `moov.udta.meta.keys/ilst`, MKV/WebM
+  `Segment.Tags.Tag.SimpleTag`, AVI `LIST/INFO/AIGC`, and FLV
+  `script.onMetaData.AIGC` placements;
 - xAI and Grok EXIF signature fields;
 - Samsung AI editing markers;
 - Hugging Face job metadata;
@@ -69,12 +93,15 @@ Pixel based image commands discover these extensions:
 - HEIC and HEIF;
 - AVIF.
 
+HEIC, HEIF, and AVIF pixel decoding requires the independent `heif` extra in
+addition to the selected pixel feature. Metadata scanning does not.
+
 Metadata inspection and removal additionally have container paths for:
 
 - JPEG XL metadata;
 - MP4, MOV, M4V, and M4A;
-- WebM, MKV, MKA, MP3, WAV, FLAC, OGG, OGA, Opus, and AAC when ffmpeg is
-  available.
+- WebM, MKV, MKA, AVI, FLV, MP3, WAV, FLAC, OGG, OGA, Opus, and AAC when
+  ffmpeg is available.
 
 JPEG image metadata stripping removes targeted metadata segments without
 re-encoding the entropy coded image scan. PNG and WebP removal preserves pixel
@@ -87,17 +114,28 @@ The `invisible` command uses diffusion regeneration. It targets watermark
 patterns by changing the image rather than decoding and deleting a known
 payload.
 
-Current pipeline values:
+Current pipeline values, both CUDA-only:
 
-- `controlnet`;
-- `sdxl`;
-- `qwen`;
-- `qwen-zimage`;
-- legacy alias `default`, which resolves to `sdxl`.
+- `qwen-zimage`, the default;
+- `sdxl-zimage`, the same recipe and the same face stage on an SDXL global pass.
 
-SynthID does not have a public local pixel decoder in this project. The tool can
-infer likely presence from supported provenance metadata, but after that
-metadata is removed a local negative result is inconclusive.
+The `controlnet`, `sdxl`, `qwen` and `default` values were removed. A retired name
+is rejected at parse time rather than remapped onto a surviving profile.
+
+SynthID does not have a public local pixel decoder in this project. The tool
+recognizes presence from supported provenance: Google AI C2PA under Google's
+all-media watermark policy, and current OpenAI C2PA carrying an explicit
+`c2pa.watermarked.*` action. Legacy OpenAI C2PA without that action does not
+assert SynthID. After provenance metadata is removed, a local negative result
+is still inconclusive.
+
+For MP4, MOV, and M4V, `video invisible` or the explicit
+`video all --invisible` option can regenerate the video through a VAE and strip
+source metadata. The shipped profile is oracle-certified, but it is not a local
+decoder. A fresh source-positive, output-negative pair from Gemini's built-in
+SynthID verifier is an optional per-file audit. A normal Gemini answer may instead
+infer from a visible logo or metadata; asking it to reinterpret a completed
+verifier result is not a second oracle run.
 
 The optional `detect` extra is different: it provides a local decoder for the
 open DWT-DCT watermark used by some Stable Diffusion, SDXL, and FLUX workflows.
@@ -109,6 +147,7 @@ not a universal clean verdict.
 | Provider or family | Visible | Invisible path | Metadata or provenance |
 | --- | --- | --- | --- |
 | Google Gemini | Sparkle | Diffusion regeneration for SynthID | C2PA and related source signals |
+| Google Veo video | Veo diamond and legacy text | Oracle-certified VAE removal for SynthID | C2PA and related source signals |
 | OpenAI image generators | None registered | Diffusion regeneration for supported invisible signals | C2PA and generator provenance |
 | Stable Diffusion and SDXL | None registered | Diffusion regeneration; optional open decoder | Embedded parameters and text metadata |
 | FLUX | None registered | Diffusion regeneration; optional open decoder | C2PA for supported sources |
@@ -116,7 +155,8 @@ not a universal clean verdict.
 | Midjourney | None registered | No registered pixel decoder | EXIF, XMP, and IPTC signals |
 | ByteDance generators | Doubao and Jimeng marks | No registered pixel decoder | TC260 AIGC and supported C2PA signals |
 | Qwen | Qwen mark | No registered pixel decoder | TC260 AIGC |
-| Kling | Kling mark | No registered pixel decoder | TC260 AIGC |
+| Kling | Kling image and video marks | No registered pixel decoder | TC260 AIGC |
+| Hailuo / MiniMax video | Hailuo composite video label | No registered pixel decoder | TC260 AIGC where present |
 | Baidu | Baidu mark | No registered pixel decoder | TC260 AIGC |
 | LibLibAI | LibLibAI mark | No registered pixel decoder | TC260 AIGC |
 | RunningHub | RunningHub mark | No registered pixel decoder | TC260 AIGC |

docs/synthid-robust-identity-research-2026-06-08.md

@@ -1,7 +1,9 @@
 # Deep research: SynthID-safe face-identity recovery for SDXL (2026-06-08)
 
 > Research archive. This dated follow-up records evidence available during the
-> study. It is not the current command reference.
+> study. It is not the current command reference. The `instantid` and `photomaker`
+> extras it discusses, the `--restore-faces` flag, and their modules were all removed
+> from the library afterwards.
 
 **Stats:** {"angles": 6, "sourcesFetched": 28, "claimsExtracted": 104, "claimsVerified": 25, "confirmed": 19, "killed": 6, "afterSynthesis": 6, "urlDupes": 1, "budgetDropped": 7, "agentCalls": 111}
 
@@ -149,8 +151,9 @@ on Modal A100 in two phases:
    - v3 (tighter ellipse 0.32*bw x 0.42*bh + per-channel mean color match to
      local cleaned canvas + softer feather): patchwork visually softened; faces
      still read as studio portraits inserted into the scene, not as people
-     shot in the scene. Single portrait identity drifted (tatsunari -> "round
-     Asian male" vs original's thin face).
+     shot in the scene. Single portrait identity drifted (the single-portrait
+     fixture regenerated as a generic "round Asian male" vs the original's thin
+     face).
 2. **Phase 2: InstantID img2img on cleaned crop.** Switched to the upstream
    `pipeline_stable_diffusion_xl_instantid_img2img` (downloaded at first use
    from raw.githubusercontent.com; requires `trust_remote_code=True`). Same

docs/synthid-robust-identity-research.md

@@ -3,7 +3,8 @@
 > Research archive. This document evaluates approaches considered during the
 > study. It does not describe the current public interface. The current
 > pipelines and limits are documented in `docs/cli.md` and
-> `docs/known-limitations.md`.
+> `docs/known-limitations.md`. The path it calls shipped -- `photomaker_restore.py`
+> and the `photomaker` extra -- was removed from the library afterwards.
 
 > **Status (2026-06-08): retired.** Every approach described below was empirically
 > tested and rejected -- see `docs/synthid-robust-identity-research-2026-06-08.md`
@@ -224,7 +225,7 @@ from the test set + this doc).
 
 ## 6. Integration cost (rough)
 
-- New deps: `diffusers` already in the gpu extra; PhotoMaker ships as a `.bin`
+- New deps: `diffusers` already in the diffusion extra; PhotoMaker ships as a `.bin`
   loaded via `pipeline.load_photomaker_adapter(...)`. The OpenCLIP encoder is the
   same one diffusers already pulls. No new heavy pip dep.
 - Weight download: PhotoMaker-V1 weights are ~3 GB. Add to the Modal HF volume
@@ -246,7 +247,9 @@ from the test set + this doc).
    - If no -> the assumption is wrong; PhotoMaker would re-introduce the
      watermark. Stop and reconsider.
 2. **PhotoMaker-V1 prototype** in the existing `controlnet` pipeline:
-   - Mirror the `_load_controlnet_pipeline` path: add a PhotoMaker variant that
+   - Mirror the `_load_controlnet_pipeline` path (removed in 0.24.0 with the
+     controlnet profile; the equivalent seam is now `SdxlZImagePipeline._load_sdxl`):
+     add a PhotoMaker variant that
      loads SDXL + canny ControlNet + PhotoMaker adapter on the same engine.
    - Extract the OpenCLIP face embedding from the watermarked face crops (use
      OpenCV YuNet, already bundled for `auto`, to find the face boxes).

docs/synthid.md

@@ -1,4 +1,4 @@
-# SynthID-Image: technical reference
+# SynthID: technical reference
 
 > Technical research reference. Current package behavior is defined by the
 > [supported signals](supported-signals.md), [known limitations](known-limitations.md),
@@ -6,10 +6,10 @@
 > historical evidence and should not be read as current CLI defaults.
 
 This document covers how Google SynthID for images works mechanically, what it
-survives, what removes it, and the current deployment landscape. It is written
-for engineers working on watermark detection and removal -- specifically to
-inform decisions about strength settings, test methodology, and what oracle
-results mean.
+survives, what removes it, the external video-verification workflow, and the
+current deployment landscape. It is written for engineers working on watermark
+detection and removal -- specifically to inform decisions about strength
+settings, test methodology, and what oracle results mean.
 
 Primary sources are cited inline. Marketing-only claims are flagged separately
 from independently-verified results.
@@ -289,14 +289,19 @@ The external variant SynthID-O is available "through partnerships" only. Our
 tool cannot locally detect SynthID presence or absence -- this is by design,
 not a gap we can fill.
 
-### 3.2 How our tool detects SynthID (metadata proxy)
+### 3.2 How our tool recognizes SynthID from provenance
 
-We detect SynthID indirectly: if the image's C2PA manifest is signed by a
-known SynthID-using issuer (Google, OpenAI), we infer SynthID is present. This
-is a **metadata proxy**, not a pixel watermark decode. It works while the C2PA
-manifest is intact, and is silent once the manifest is stripped or the image
-is re-encoded without C2PA (e.g., a screenshot, a social-media re-upload, or
-after `metadata --remove`).
+We recognize SynthID indirectly from supported C2PA evidence; this is not a
+pixel watermark decode. Google states that all media generated by its tools is
+watermarked, so Google AI C2PA establishes SynthID. OpenAI C2PA predates its
+SynthID rollout, but current manifests add the signed
+`c2pa.watermarked.unbound` action; OpenAI provenance establishes SynthID only
+when that action is present. Legacy OpenAI C2PA without it remains valid origin
+evidence but does not assert a pixel watermark.
+
+This works while the C2PA manifest is intact and is silent once the manifest is
+stripped or the image is re-encoded without C2PA (e.g., a screenshot, a
+social-media re-upload, or after `metadata --remove`).
 
 This is why:
 - `identify` on a GitHub-recompressed issue attachment returns Unknown (C2PA is
@@ -326,6 +331,63 @@ A Google-SynthID image reads clean on openai.com/verify. An OpenAI image reads
 clean in the Gemini oracle. They are different payloads within the same
 framework.
 
+### 3.4 Video verification and attack harness
+
+Gemini's built-in verification flow reports whether and where it detects Google
+SynthID in a video. This remains a proprietary oracle: invoke `@synthid`, use
+the supported content-verification question, and keep every file in a separate
+new chat. A normal Gemini answer that discusses visual clues or metadata is not
+an oracle verdict. Nor is an adversarial follow-up that asks the chat model to
+ignore and reinterpret a completed verifier result.
+
+The research harness `scripts/video_synthid_sweep.py` tests a VAE regeneration
+attack without pretending to detect success locally. It emits:
+
+1. a re-encode control using the same sampled frames, dimensions, frame rate,
+   and codec as the candidates;
+2. VAE round-trip candidates with one spatial latent-noise field shared across
+   time;
+3. paired PSNR and motion-compensated temporal-residual metrics;
+4. an empty oracle column for the external verdict.
+
+The control is the first oracle submission. If it is not SynthID-positive, stop:
+the surrounding transcode already changed the verifier result. Only a
+control-positive, candidate-negative pair is evidence about the regeneration
+attack. PSNR and temporal residual measure fidelity and flicker, never watermark
+presence.
+
+The shipped `video invisible` command and `remove_video_invisible` API reuse the
+same VAE regeneration mechanism for a complete input sequence. The shipped
+default is oracle-certified and does not expose a separate verification-status
+flag. In the 2026-07-29
+two-carrier calibration, both matched controls were positive in the built-in
+verifier; the stronger candidate was negative on both, while a weaker
+candidate was negative on one. A 2026-07-30 `UNAVAILABLE` response came from an
+ordinary-model follow-up that asked Gemini to reinterpret the already returned
+verdict and therefore did not invalidate it. The default is a calibrated,
+content-dependent operating point. A per-file provider check remains an
+optional audit after provider changes or for unusually important files.
+
+The 2026-07-31 full-clip calibration used Google's public eight-second Veo
+off-road sample through the complete product command. The original was detected
+across 00:00-00:07, the `noise_std=0.10` output remained detected, and the
+`0.15` output was not detected. The positive `0.10` result proves that the
+surrounding 512 px / 12 fps / H.264 path did not create the negative result by
+itself. `0.15` is therefore the shipped default. The tracked manifest
+`data/evaluations/video-synthid-oracle.csv` records the public source URL,
+hashes, fidelity metrics, and verdicts without committing generated videos.
+
+What that calibration does and does not constrain, the ranked experiment program
+for trading less quality for the same removal, and the change candidates that were
+refuted along the way are recorded in
+[`video-synthid-quality-research.md`](video-synthid-quality-research.md).
+
+The VAE perturbation follows the general regeneration-attack construction from
+Zhao et al. The video-specific control and temporal metric are local additions.
+VideoMarkBench motivates testing frame aggregation and matched perturbations,
+but it does not evaluate Google's proprietary SynthID, so its findings cannot
+stand in for the Gemini oracle.
+
 ---
 
 ## 4. Adoption and current state (as of June 2026)
@@ -352,8 +414,9 @@ OpenAI confirmed SynthID adoption (Help Center, updated 2026-05-21):
 > "ChatGPT images include both C2PA metadata and SynthID watermarks."
 
 This is time-gated: pre-rollout ChatGPT/gpt-image images carry C2PA without
-SynthID. Our C2PA proxy therefore over-reports SynthID presence on old images
-(hence the `_OPENAI_CAVEAT` hedging flag in the codebase).
+SynthID. Current OpenAI manifests distinguish the watermarked output with the
+signed `c2pa.watermarked.unbound` action. The detector requires that action, so
+old OpenAI C2PA remains an origin signal without becoming a SynthID claim.
 
 ### 4.3 Other vendors
 
@@ -396,6 +459,14 @@ the payload, reconstituting SynthID in text. The lesson held and shaped the
 current design: **content is preserved by REGENERATING it under structural
 conditioning, never by copying original pixels.**
 
+> **Superseded in 0.24.0.** The `controlnet`, `sdxl`, `qwen` and `default` profiles
+> were removed, and a retired name is now rejected at parse time rather than routed
+> onward. `--pipeline` accepts only `qwen-zimage` (the default) and `sdxl-zimage`;
+> both are CUDA-only, both condition their global stage on a canny edge map, and both
+> run the same Z-Image face stage. The bullets below are a record of what was measured
+> on the removed profiles, kept because the oracle verdicts are still the evidence the
+> current design rests on.
+
 - **Text + structure:** `--pipeline controlnet` (SDXL img2img + a canny ControlNet) is
   **THE DEFAULT pipeline since 2026-06-09** (`--pipeline default` opts down to plain
   SDXL img2img for inputs without text/faces). It conditions the regeneration on the
@@ -428,21 +499,21 @@ conditioning, never by copying original pixels.**
   measured at. See §5.2.**
 - **Highest-fidelity CUDA option:** `--pipeline qwen-zimage` is the recommended
   quality mode when preserving face identity matters more than latency, model size,
-  and GPU cost. ControlNet remains the default because it is much cheaper and supports
+  and GPU cost. ControlNet was then the default, because it was much cheaper and ran on
   CUDA, XPU, MPS, and CPU, but canny conditioning preserves edges rather than identity.
   On two direct upstream comparisons, `qwen-zimage` retained substantially more
   ArcFace identity than polished ControlNet. On 2026-07-25 the exact six-output
   `visible -> qwen-zimage -> metadata` candidate was negative in the corresponding
   OpenAI and Gemini oracles. This is a quality recommendation for the measured content,
   not broad removal certification; very small text can still degrade.
-  See `docs/known-limitations.md` for the metrics, runtime, and validation scope.
-- **Face identity:** canny holds face *structure* but not *identity*. The standard
-  SDXL and ControlNet profiles do not run a separate face-restoration option.
-  Earlier GFPGAN, PhotoMaker, and FaceID experiments were removed after they
-  degraded identity or risked reintroducing source pixels. The separate
-  `qwen-zimage` profile now provides the only shipped face-specific stage:
-  YuNet and SAM locate faces, then Z-Image regenerates the selected original
-  face crops before a feathered composite. See
+  See `docs/qwen-improvement-research.md` for the identity and text metrics and the
+  validation scope of those comparisons.
+- **Face identity:** canny holds face *structure* but not *identity*. The removed
+  SDXL and ControlNet profiles did not run a separate face-restoration stage, and
+  earlier GFPGAN, PhotoMaker, and FaceID experiments were dropped after they
+  degraded identity or risked reintroducing source pixels. Both shipped profiles
+  now run the same face-specific stage: YuNet and SAM locate faces, then Z-Image
+  regenerates the selected original face crops before a feathered composite. See
   `docs/controlnet-removal-pipeline-research.md` for the historical experiments.
 
 ### 5.2 Strength setting
@@ -459,13 +530,20 @@ study (section 2.2) gives empirical floors:
   measured on; treat it as a lower bound, not a guarantee, and raise + oracle-recheck
   per content type (see §5.1 controlnet bullet).
 - **Google (capped 1536)**: 0.15 (n=4); 0.05 and 0.10 do not clear.
-- **Google native 2816**: not locally measured; likely needs >= 0.30 (vendor +
-  resolution stack). Use a GPU or `--max-resolution 1536`.
+- **Google native 2816**: 0.15 clears (n=2, deployed controlnet worker, 2026-06-14) --
+  the same rung as capped 1536, so no resolution penalty was observed.
 
-The default is **vendor-adaptive** (`watermark_profiles.resolve_strength` +
-`vendor_for_strength`): the tool reads the C2PA issuer on the original input and picks
+> **Superseded in 0.24.0.** The `sdxl`, `controlnet`, `qwen` and `default` profiles
+> were removed, and `OPENAI_STRENGTH` / `GEMINI_STRENGTH` / `UNKNOWN_STRENGTH` went
+> with them. Everything from here to the end of this section is a record of what was
+> measured on those profiles, kept because the oracle verdicts are still the evidence
+> base. For the strength policy in force now see `module-internals.md`: `qwen-zimage`
+> uses `resolution_adaptive_denoise`, `sdxl-zimage` a flat vendor ladder.
+
+The default was **vendor-adaptive** (`watermark_profiles.resolve_strength` +
+`vendor_for_strength`): the tool read the C2PA issuer on the original input and picked
 `OPENAI_STRENGTH` 0.10 / `GEMINI_STRENGTH` 0.15 / `UNKNOWN_STRENGTH` 0.15 **(LOWERED
-2026-06-14 from the 2026-06-04 cert floors 0.20/0.30/0.30)**. **The SAME ladder applies
+2026-06-14 from the 2026-06-04 cert floors 0.20/0.30/0.30)**. **The SAME ladder applied
 to both pipelines** (`sdxl` and `controlnet`). The 2026-06-14 re-test on the deployed
 Modal controlnet worker (v0.10.0) cleared SynthID on the oracle at OpenAI 0.10 (2
 photoreal) and Google 0.15 (2 NATIVE 2816x1536, contradicting the "native >= 0.30" guess
@@ -486,12 +564,56 @@ for `sdxl`, not a separate certification (no local SynthID detector to self-veri
 The higher strength costs little quality where it matters, because `controlnet` is now
 the default pipeline, so `sdxl` is reached only via an explicit `--pipeline sdxl` (a
 deliberate opt-down), where over-regeneration has no faces/text to damage.
-This uses the vendor signal we DO have locally (the C2PA SynthID proxy) to avoid the
+This uses the vendor signal we DO have locally (the C2PA SynthID provenance) to avoid the
 overkill of a single high default on OpenAI images, without needing a local pixel
 detector. An explicit `--strength` always wins. If the watermark still survives (e.g. a
 large native Gemini beyond the capped-1536 validation), raise toward 0.35-0.40 (0.40
 visibly corrupts dense text), using the lowest value that reads clean on the oracle.
 
+**qwen-zimage global denoise, Gemini boundary bracketed (2026-08-02).** The profile does
+not use the vendor ladder above; `resolution_adaptive_denoise` maps megapixels onto
+roughly 0.084 (sub-0.3 MP) to 0.154 (>= 3.7 MP). A ladder on one native 2816x1536 Gemini
+original, seed 0, everything else at profile defaults, verified through the Gemini app:
+
+| global denoise | Gemini app | whole-image PSNR | face-box PSNR | edge IoU |
+|---|---|---|---|---|
+| 0.154 (profile top) | clean | 24.72 | 31.19 | 0.188 |
+| 0.12 | clean | 25.65 | 31.82 | 0.202 |
+| 0.10 | **clean** | 26.26 | 32.17 | 0.212 |
+| 0.08 | **SynthID FOUND** | 26.95 | 32.51 | 0.227 |
+
+So the boundary sits between 0.08 and 0.10 for this image, and the profile's shipped
+0.154 carries roughly half a rung more strength than that content needed. Fidelity rises
+monotonically all the way down - dropping to 0.10 buys **+1.54 dB whole-image and
++0.98 dB inside the face boxes** - which is exactly why the temptation is to move the
+ceiling, and exactly why one fixture is not enough to do it.
+
+Two constraints on reading this:
+
+- **It brackets, it does not calibrate.** One image, one seed. Shipping the lowest clean
+  rung means shipping at the measured cliff edge; another sample, seed, or content class
+  can sit on the other side of it. Note §5.2's flat-graphic hard cases were not in this
+  set at all.
+- **The bottom of the curve was the untested end. It has now been measured, and it
+  holds.** Every Gemini oracle fixture is 2816x1536, so the Google-side certification
+  only ever covered 0.154, while `resolution_adaptive_denoise` sends sub-1 MP images to
+  0.084-0.094 - at or below the rung that failed at 4.33 MP. Downscaling a Gemini
+  original (valid test material: SynthID survives it by design) and running the deployed
+  worker on it gives, through the Gemini app:
+
+  | processing size | profile denoise | Gemini app |
+  |---|---|---|
+  | 1024x559 (0.57 MP) | 0.0896 | clean |
+  | 1600x873 (1.40 MP) | 0.1066 | clean |
+
+  So production's own low end clears Google, and the "small images are under-processed"
+  failure mode is ruled out at these two sizes. **Read this as validation of the shipped
+  curve, not as proof that the boundary moves with resolution.** 0.0896 sits inside the
+  untested gap at 4.33 MP, where only 0.08 (found) and 0.10 (clean) were probed, so it
+  may well clear at both sizes. The direction of any resolution dependence remains
+  unproven (§5.5). Also note these are downscales of a 2816x1536 original rather than
+  natively small Gemini outputs, which have still never been tested.
+
 ### 5.3 Test methodology
 
 - **GitHub-recompressed JPEGs from issue attachments are valid SynthID test
@@ -501,7 +623,7 @@ visibly corrupts dense text), using the lowest value that reads clean on the ora
 - **The correct oracle for OpenAI images is openai.com/verify**, not the Gemini
   app. The two oracles detect different payloads.
 - **A quiet `identify` output after processing is not proof of removal.** It
-  means the metadata proxy is gone. The pixel watermark state is unknown without
+  means the provenance evidence is gone. The pixel watermark state is unknown without
   an oracle check.
 - **After removal, the output may carry forensic artifacts** detectable by an
   independent classifier even if the vendor oracle reads negative. Defeating the
@@ -571,7 +693,7 @@ it; (3) **historical engineering conclusion:** this dated run argued for a
 higher ControlNet strength than the then-current default. That proposal was
 later superseded. The current resolver intentionally shares the 0.10/0.15
 ladder between SDXL and ControlNet and uses a separate Qwen ladder; see
-`noai/watermark_profiles.py`.
+`_internal/watermark_profiles.py`.
 Source images are private (faces / product shots), not committed; reproduce on any
 photoreal + flat-graphic gpt-image pair, varying the seed, and re-checking the
 oracle.
@@ -590,24 +712,32 @@ openai.com/verify):
   weight 0.5 blends ~half its pixels back, re-introducing SynthID into the
   composited face over the diffusion-cleaned result (see §5.1 face-identity bullet).
 - (Side note: reducing the processing resolution does NOT weaken SynthID -- it is
-  robust to downscaling by design, and the study's resolution trend says LOWER
-  processing res needs LESS strength, so 1024 was never the wall.)
+  robust to downscaling by design, so 1024 was never the wall. Whether a lower
+  processing resolution then needs more or less removal strength is NOT established;
+  see the note below.)
 
 **Historical controlnet certification, superseded by the current vendor-adaptive
 defaults (isolated GPU sweep + oracle,
 restore OFF, <= 1536, each vendor on its own oracle):** OpenAI **0.20** (2 photoreal x
 seed {1,2,3} = 6/6 clean; the 0.15-flipper is seed-robust at 0.20) and Gemini **0.30**
-(0.20 detected -> 0.30 clean on 2/2 seeds). OpenAI 0.20 transfers to prod
-(resolution-independent); Gemini 0.30 holds only <= 1536 -- Gemini is
-resolution-sensitive, so a native-resolution deployment should cap Gemini <= 1536 + use 0.30 or
-native-calibrate (~0.35+). See `docs/controlnet-removal-pipeline-research.md` for the
-table.
+(0.20 detected -> 0.30 clean on 2/2 seeds). Both were measured at <= 1536 only. See
+`docs/controlnet-removal-pipeline-research.md` for the table.
+
+**Whether Gemini removal is resolution-sensitive is UNPROVEN, in either direction.**
+This document previously asserted it was, and recommended capping Gemini at 1536 with
+0.30 or "native-calibrating" to ~0.35+. Nothing measured that. The one relevant
+measurement points the other way: the 2026-06-14 deployed-worker re-test cleared Gemini
+at **0.15 on two NATIVE 2816x1536 images**, the same rung as capped 1536. So there is no
+observed native-resolution penalty, and no observed benefit either -- the low-resolution
+end has simply never been through the Gemini oracle on any pipeline. Do not reason from
+a resolution trend here; measure it.
 
 **Current implication:** the old floor table remains evidence about the dated
-test set, not the current resolver. The shipped SDXL and ControlNet defaults are
-defined in `watermark_profiles.py`, and face restoration is available only
-through the separate `qwen-zimage` profile. Removal near a threshold remains
-seed dependent, so reproducible verification requires a fixed seed.
+test set, not the current resolver. The SDXL and ControlNet profiles it measured
+no longer exist; the shipped defaults are defined in `watermark_profiles.py`, and
+both surviving profiles run face repair as a built-in second stage rather than as
+an optional restore. Removal near a threshold remains seed dependent, so
+reproducible verification requires a fixed seed.
 
 ---
 
@@ -628,3 +758,14 @@ seed dependent, so reproducible verification requires a fixed seed.
 
 5. OpenAI. **Verify tool for AI-generated images.** openai.com/research/verify.
    Accessed 2026-05-31.
+
+6. Google. **Verify AI-generated images, videos, and audio.**
+   https://support.google.com/gemini/answer/16722517
+
+7. Zhao et al. (2024). **Invisible Image Watermarks Are Provably Removable
+   Using Generative AI.** NeurIPS 2024, arXiv:2306.01953.
+   https://arxiv.org/abs/2306.01953
+
+8. Jiang et al. (2025). **VideoMarkBench: Benchmarking Robustness of Video
+   Watermarking.** arXiv:2505.21620.
+   https://arxiv.org/abs/2505.21620

docs/text-protection-research.md

@@ -2,6 +2,8 @@
 
 > Research archive. This page records evaluated ideas, including rejected
 > prototypes. Current behavior is documented in the user guides and source.
+> The `text_protector.py` module it describes was removed from the library
+> afterwards.
 
 Date: 2026-05-29. Source: a deep-research run (104 agents, 5 search angles, sources
 fetched and 3-vote adversarially verified). Not committed automatically — saved as a

docs/verification-plan.md

@@ -72,8 +72,10 @@ Run detection, removal, and re-detection over a representative local set. Confir
 
 ### A5. Contract sweep across every parameter choice
 
-`scripts/smoke_matrix.py` (exists, 68 rows, 0 skipped with `--diffusion`) covers every
-choice-valued flag on fixtures. Extend from fixtures to a stratified corpus slice
+`scripts/smoke_matrix.py` covers every choice-valued flag on fixtures. Its knob rows
+were rewritten when the CPU/MPS profiles and the ESRGAN chain were removed: most now
+assert a knob is REJECTED, and the accepted-knob rows skip without a CUDA device, so
+the row count is host-dependent rather than the fixed 68 recorded here before. Extend from fixtures to a stratified corpus slice
 (~500 images spanning format x provenance x aspect ratio), asserting exit-code semantics
 rather than just absence of crash.
 
@@ -84,25 +86,33 @@ sweep asserts on stderr, or the codes get split -- the latter is the better fix.
 #### Coverage method
 
 Compare the flags and values exercised by the matrix against the options declared by
-the CLI. Include optional backends, batch modes, tiling, region-targeted composition,
-the ESRGAN upscaler, and the ffmpeg audio/video strip. The gap to find is not only
+the CLI. Include optional backends, batch modes, tiling, and the ffmpeg audio/video
+strip. (Region-targeted diffusion composition was on this list until the parameter
+was deleted: nothing but a caller-less convenience wrapper ever reached it, and the
+user-facing region path is `erase`, which inpaints instead.) The gap to find is not only
 "logic untested" but
 "never executed on real data", which is precisely what this campaign is for.
 
-#### Bug found by the extension: `--steps` below ~7 crashes inside torch
+#### Bug found by the extension: `--steps` below ~7 crashed inside torch
 
-Effective timesteps are `int(steps * strength)`. At the vendor-adaptive default strength
-(0.15, or 0.10 for OpenAI) any `--steps` under 7 rounds to **zero**, and the pipeline dies
-with a raw traceback:
+**Fixed by deletion.** `--steps` no longer exists, on the CLI or in the Python API,
+so this class of failure is unreachable. Kept as a record of why.
+
+Effective timesteps were `int(steps * strength)`. At the vendor-adaptive default
+strength (0.15, or 0.10 for OpenAI) any `--steps` under 7 rounded to **zero**, and the
+pipeline died with a raw traceback:
 
 ```
-$ remove-ai-watermarks invisible img.png --steps 5
 RuntimeError: cannot reshape tensor of 0 elements into shape [0, -1, 1, 512]
 ```
 
-Fully valid CLI arguments, no special flags, no `--force`. The value is accepted, the
-crash is a torch internal, and nothing tells the user that steps and strength interact.
-Fix is either a clamp to >=1 effective step or an up-front validation naming both values.
+Fully valid CLI arguments, no special flags, no `--force`. The value was accepted, the
+crash was a torch internal, and nothing told the user that steps and strength interact.
+The considered fixes were a clamp to >=1 effective step or an up-front validation
+naming both values; what shipped instead is that each stage owns its own distilled
+schedule and no caller can set it. The general lesson stands: a knob whose valid range
+depends on another knob's value needs the interaction validated where both are known,
+or it needs to not be a knob.
 
 Method note: the first run of the knob rows failed 12 times with this identical error,
 which read like twelve broken features. It was one bad harness parameter (`--steps 4`)
@@ -216,6 +226,43 @@ for the wrong reason reads exactly like success.
 the control passes -- but that is Google's claim about their own decoder, not our
 measurement, so it is a hypothesis to test, not a reason to skip the control.
 
+### D4. Video candidates require a matched transcode control
+
+Video experiments add frame sampling, resizing, frame-rate conversion, and a
+final video codec around the actual attack. `scripts/video_synthid_sweep.py`
+therefore emits `control.mp4` from the same selected frames and encoder settings
+as every VAE candidate.
+
+Verify the control first in a new Gemini chat by invoking `@synthid` and using
+the supported built-in content-verification question. Continue only when the
+provider oracle still detects SynthID in it. Verify each candidate in its own
+new chat. A generic response that discusses visual clues or metadata is not an
+oracle result. Do not ask the chat model to reinterpret or second-guess the
+built-in verdict; that follow-up is ordinary model reasoning. Record only the
+explicit built-in SynthID verification verdict in the generated CSV.
+
+The harness shares one latent-noise field across the sequence to avoid adding
+independent frame noise. Its temporal-residual metric is a fidelity check, not a
+watermark detector.
+
+The 2026-07-29 two-carrier calibration produced genuine built-in verifier
+results: both matched controls were positive, the stronger candidate
+was negative on both carriers, and a weaker candidate was negative on one. On
+2026-07-30, adversarial follow-up prompts returned `UNAVAILABLE` after asking
+ordinary Gemini to ignore and reinterpret the detector result. Those follow-ups
+were mistakenly treated as a stricter oracle; they were not detector reruns.
+The implementation remains exposed as `video invisible` and
+`remove_video_invisible`. Its oracle-certified default is the product operating
+point. A fresh control-positive, candidate-negative pair remains an optional
+per-file audit after provider changes or for unusually important files.
+
+The 2026-07-31 full-clip check added a public eight-second Veo carrier. The
+source and the complete `0.10` product output were both detected, proving the
+surrounding resize / frame-rate / codec path had not silenced the oracle. The
+complete `0.15` product output was not detected, so `0.15` became the default.
+The tracked source and output hashes, fidelity metrics, and verdicts are in
+`data/evaluations/video-synthid-oracle.csv`; generated media remains untracked.
+
 ## Tier E -- robustness and adversarial inputs
 
 Malformed and hostile inputs, including truncated files:
@@ -277,6 +324,43 @@ separately, outside this repo.
 
 Run `scripts/real_examples_e2e.py` against representative local inputs before releases that affect image handling. The script must read from `.local-eval/`, write only untracked temporary output, and report behavior without exposing dataset provenance or aggregate private measurements.
 
+The cheap video seam is covered automatically by
+`TestVideoVisibleFullClip::test_removes_complete_clip_and_preserves_sequence_and_audio`.
+It constructs a full synthetic Sora-like MP4 with AAC audio and C2PA
+provenance, then exercises detection, temporal arbitration, OpenCV fill, real
+ffmpeg encoding, metadata stripping, audio stream copy, and atomic publication
+through the public API. A separately encoded clean control supplies the paired
+frame-to-frame deltas inside the filled region, so the gate detects temporal
+flicker rather than treating all output motion as an error. The default
+motion-compensated fill must score strictly below a separately encoded
+frame-local opt-out on the median paired error, while its high-percentile error
+cannot regress. The dedicated Linux CI job installs ffmpeg explicitly. Keep real-provider and learned-backend
+sequence evaluation local because those inputs or model downloads do not
+belong in the core matrix.
+
+The local real-provider audit runs one complete clip for every registered video
+mark. OpenCV and MI-GAN must remove every accepted frame, leave the second-pass
+detector quiet, preserve source stream starts and duration, and copy AAC
+packets exactly when present. Run one complete LaMa clip to verify wiring and
+resource tier; its CPU throughput makes a six-provider online matrix
+counterproductive. Store generated outputs and the detailed CSV only under
+`.local-eval/`.
+
+The same full-clip gate runs the public metadata-only path against its real MP4
+and verifies unchanged file size, decoded frames, stream properties, and AAC
+packets. A separate synthetic large-`mdat` test rejects full-source
+`read_bytes()`, hashes the copied media payload, and mutation-checks both C2PA
+and TC260 survival.
+
+A companion full-clip VFR case alternates three frame durations, runs the
+public visible-removal API, and compares every output display timestamp to the
+source within one source time-base tick. Its source starts at a non-zero PTS,
+so the test also verifies retained video/audio stream offsets, container
+duration, and copied AAC identity. Mutations that disable the timestamped NUT
+bridge or reset its start PTS must fail this gate.
+A separate constant-rate clip with the same non-zero start guards the
+start-offset routing without relying on the VFR branch.
+
 ## Standing gap
 
 None of this is in `maintain.sh`, and it should not all be -- the sweeps take hours. But

docs/video-synthid-quality-research.md

@@ -0,0 +1,493 @@
+# Video SynthID quality research (2026-08-05)
+
+> Research archive. This page records experiments and decisions from the date
+> above. It may mention prototypes or defaults that were later changed. Use the
+> user guides and current source code for the supported interface.
+
+Cited research behind the question **"can the video SynthID path keep removing the
+mark while giving up far less quality than the shipped 512 px / 12 fps profile?"**
+Produced by a 13-agent workflow: 6 parallel scouts (pipeline ablation, SynthID
+internals, attack literature, autoencoder landscape, perceptual masking, experiment
+design), 11 change proposals from 3 independent design angles, and 3 adversarial
+critics (signal theory, repository engineering, verifiability). No experiment was
+run against the provider oracle for this page; every claim is labeled MEASURED,
+REPORTED, or INFERRED.
+
+Repository claims below were re-verified against source after the workflow
+returned: the PSNR reference frame, the audio stream copy, the missing `_fit_size`
+clamp, the absent `enable_tiling` call, the crf asymmetry, the test pins, and the
+absent `scaling_factor` key in the cached checkpoint config.
+
+## Context
+
+`remove_video_invisible` regenerates video pixels through `sd-vae-ft-mse`: frames
+are decimated to 12 fps, resized to a 512 px long side, encoded to latents with
+`latent_dist.mode()`, perturbed by one seeded spatial noise field shared across
+every frame, decoded, and streamed to an H.264 encoder at crf 18. A separate
+stream-copy mux re-adds source audio and strips metadata. The shipped
+`noise_std=0.15` is certified by one oracle row on one carrier.
+
+The quality complaint is real: a 1080p source is delivered at roughly a quarter of
+its linear resolution and half its frame rate. This page asks what part of that
+cost is buying removal and what part is buying nothing.
+
+## What the two oracle rows do and do not prove
+
+`data/evaluations/video-synthid-oracle.csv`, one carrier (Veo 3 off-road,
+sha256 `79a552b9...`), one seed, one geometry:
+
+| noise_std | long_side | fps | verdict | psnr_db | temporal_residual_ratio |
+| --- | --- | --- | --- | --- | --- |
+| 0.10 | 512 | 12 | detected | 26.2932 | 1.0072 |
+| 0.15 | 512 | 12 | not_detected | 25.3911 | 1.0578 |
+
+They prove exactly one thing: the envelope of 512 px, 12 fps, crf 18, and a full
+VAE round trip does **not** silence the oracle on its own. The verdict flip is
+bought by the last 0.05 of latent noise.
+
+They cannot decompose that conjunction. No row varies `long_side` or `fps`, so the
+contribution of the downscale is unmeasured. The frequent reading "the 512 px
+downscale was probably doing the removal work" is not supported, and neither is its
+opposite.
+
+## Measured facts from the repository
+
+- **The fidelity metric is blind to the expensive steps.** `_iter_sampled_frames`
+  applies `cv2.resize` at [`video_invisible.py:236`](../src/remove_ai_watermarks/video_invisible.py);
+  the same generator feeds the loop at `:401-407`; the accumulator at `:429-435`
+  zips those already-resized frames against `regenerated` captured at `:423`, which
+  is before `frame_pipe.write` at `:430`. `psnr_db` therefore excludes the
+  downscale, the decimation, and the encoder. It measures the VAE round trip plus
+  latent noise at the working geometry, nothing else.
+- **Frame decimation cannot destroy the carrier.** `_iter_sampled_frames`
+  (`:224-238`) is pure subset selection: the only statement inside the threshold
+  test is `yield cv2.resize(...)`, with no arithmetic across frames. The
+  perturbation is equally time-blind: `shared_noise.expand(latents.shape[0], -1, -1, -1)`
+  at `:295` broadcasts one CHW field across the batch and never mixes across time.
+  Any fps effect on the verdict is a detection-probability effect, not carrier
+  destruction.
+- **`_fit_size` has no clamp at 1.0.** `scale = long_side / max(width, height)` at
+  `:88` upscales any source whose long side is below 512, and both axes are floored
+  independently to a multiple of 8 at `:89-96`, which introduces an anamorphic
+  shift at scale 1.0 (1366x768 becomes 1360x768).
+- **`enable_tiling` is never called** anywhere in `src/`, `scripts/`, or `tests/`.
+  `enable_slicing()` at `:135` already splits both encode and decode to single
+  frames, so activation VRAM is set by one frame and does not scale with
+  `--batch-size`.
+- **crf asymmetry:** 18 on the invisible path (`:321`, `:386`) against 14 on the
+  visible path ([`video_visible.py:1343`](../src/remove_ai_watermarks/video_visible.py))
+  through the same encoder.
+- **No HDR guard on the invisible path.** `_HDR_TRANSFERS` (`video_visible.py:97`)
+  and the `component_depth > 8` rejection (`:1322`) exist only for visible removal.
+- **Audio is byte-copied.** `-map 0:v:0`, `-map 1:a?`, `-c copy` at
+  [`video_encoding.py:413`](../src/remove_ai_watermarks/video_encoding.py).
+- **Only `noise_std` is pinned.** `tests/test_video_invisible.py:285` asserts
+  `DEFAULT_VIDEO_SYNTHID_NOISE_STD == 0.15`. Neither `long_side` nor `fps` is
+  pinned anywhere, so changing either breaks no test.
+- **`scaling_factor` 0.18215 is a class default, not a checkpoint fact.** The
+  cached `config.json` for `stabilityai/sd-vae-ft-mse` has no `scaling_factor` key
+  at all (verified locally: `_class_name`, `latent_channels`, `block_out_channels`,
+  `sample_size`, and block types only). The value comes from the `AutoencoderKL`
+  class default under `diffusers>=0.38.0` with no upper bound (`pyproject.toml:94`,
+  `uv.lock` resolves 0.39.0), while `maintain.sh` runs `uv-outdated`. A dependency
+  bump can move the certified operating point with a fully green test suite.
+- **The manifest schema cannot record what a real program needs:** no source
+  geometry, no control row, no track column, no verbatim verdict, no indeterminate
+  state.
+
+## Measured facts from external sources
+
+- Gemini video verification quota: 10 checks per rolling 24 hours, up to 5 minutes
+  of video total, under 90 seconds and 100 MB per file. The verifier reports which
+  parts of the video carry the mark, and it has a **third** state beyond detected
+  and not detected: unclear, with documented causes including "not enough details
+  to watermark".
+- The verifier scores **audio and visual tracks separately**. Google's published
+  example verdict reads as SynthID detected in the audio over a time range with no
+  SynthID detected in the visuals.
+- SynthID-Image (arXiv:2510.09263) is a post-hoc, model-independent pixel-space
+  watermark: a separate encoder network stamps an already-decoded image rather than
+  being injected into the generator's latents. Its published payload figure is 136
+  bits within a 512x512 image, and its product setup runs at 1536x1536.
+
+## Inferred, with the reasoning that makes them weak
+
+- **The noise axis is nearly exhausted.** Fitting `MSE = A + B * noise_std^2` to the
+  two measured rows gives A = 124.5 and B = 2815, so a pure round trip
+  (`noise_std = 0`) lands near 27.2 dB. The entire noise budget is worth at most
+  **+1.79 dB**; everything else is the autoencoder. This is a two-parameter fit to
+  two points with zero degrees of freedom, and the assumptions that MSE is
+  quadratic in `noise_std` and that reconstruction and noise errors are orthogonal
+  are untested. One local run at `noise_std=0` replaces it with a measurement.
+- **Statistical power of the current certification.** With zero failures at n = 1,
+  the exact one-sided Clopper-Pearson bound `1 - 0.05^(1/n)` is 95%: the data are
+  compatible with removal failing almost always. n = 15 gives 18.1%, n = 30 gives
+  9.5%.
+- **Size of the geometry prize.** At a 1280x720 source, `_fit_size(1280, 720, 512)`
+  is `(512, 288)` (pinned in `tests/test_video_synthid_sweep.py:30`), so 6.25x of
+  the pixels are discarded by the downscale and another 2x by decimation from a
+  24 fps source. Ladder rungs: 768 gives 2.25x the current area, 1024 gives 4.0x.
+  The carrier's own geometry is recorded nowhere, so this is conditional.
+- **The direction of the resolution effect is disputed, and both sides are
+  inference.** Against raising it: the absolute frequency ceiling below which an f8
+  VAE reconstructs faithfully is tied to the latent pitch, so 512x288 (a 64x36
+  latent) preserves roughly up to 32 cycles per frame width while 1920 (a 240x135
+  latent) preserves up to about 120. Raising resolution moves the carrier band out
+  of the regime the decoder synthesizes and into the regime it reproduces
+  faithfully, handing the detector more evidence. For raising it: Google's product
+  operating point is 1536x1536, so native is closer to the distribution the
+  watermark encoder targets. Note that the second argument cuts against the
+  proposal rather than for it.
+
+## First local measurements (2026-08-05)
+
+Run without the oracle on a locally built carrier: a 6-second 1280x720 24 fps
+clip panning across `data/fixtures/provenance/doubao-1.png`, processed by the
+shipped path at 512 px / 12 fps on MPS. Generated media stayed outside the
+repository.
+
+| noise_std | engine `psnr_db` | end-to-end PSNR | end-to-end SSIM | bitrate |
+| --- | --- | --- | --- | --- |
+| 0.00 | 27.8049 | 27.6935 | 0.6955 | 2564 kbps |
+| 0.15 | 25.8853 | 25.8541 | 0.6703 | 2716 kbps |
+
+Three readings, all MEASURED, none of them about SynthID:
+
+1. **The two-point fit's shape survives contact with independent content.** The
+   pure round trip lands at 27.80 dB against the 27.2 dB the carrier fit
+   predicted, and the whole noise budget costs 1.92 dB against the predicted
+   1.79 dB. These are not the carrier's numbers, but the decomposition holds:
+   the autoencoder is the floor and the entire `noise_std` axis is worth about
+   2 dB.
+2. **On this content the downscale is nearly free in PSNR terms.** End-to-end
+   PSNR sits within 0.11 dB of the in-loop number, meaning the 512 px geometry
+   cost almost nothing next to the VAE damage. This clip is a pan over a smooth
+   generated image with little high-frequency detail, so it is the friendly
+   case: real camera texture should widen that gap. Run the probe across content
+   types before trusting any estimate of the geometry prize.
+3. **`temporal_residual_ratio` is not meaningful on a near-static shot.** It read
+   1.82 at `noise_std=0` and 2.47 at 0.15, far outside the [1.0072, 1.0578] band
+   ever observed before. A slow pan gives the source almost no motion residual,
+   so the `max(temporal_baseline, 1e-6)` denominator collapses and the ratio
+   inflates. This is the predicted defect, now observed rather than argued.
+
+## The single most important unknown
+
+**How much the 512 px downscale contributes to removal.** Every quality gain routes
+through this question, and the critics moved it from "probably free" to "direction
+unknown", which is exactly what makes it the highest-information experiment
+available.
+
+## Ranked experiment program
+
+Ranked by information per oracle query. The budget is roughly 10 checks per 24
+hours (MEASURED), so the program is paced by calendar, not by money.
+
+### E0. The zero-oracle tier (0 submissions) - do this first
+
+Not an experiment on the oracle; the precondition that makes everything else
+interpretable.
+
+- `ffprobe` the carrier and record `source_width`, `source_height`, `source_fps`.
+  The actual downscale factor of the existing rows is currently unrecoverable.
+- Extend the manifest schema: variant/control, source geometry, `vae`, `track`
+  (audio|visual), verdict state in {DETECTED, NOT_DETECTED, INDETERMINATE,
+  REFUSED}, verbatim verdict text, detected time range for the output,
+  `session_id`, content stratum.
+- **Measure the `noise_std = 0.0` round trip locally** on the same carrier. This
+  converts the inferred 27.2 dB ceiling into a measurement and bounds the whole
+  noise axis for one GPU pass and zero oracle cost.
+- Freeze the current defaults' metrics on a fixed clip set, matching the
+  record-then-diff rule in `.claude/rules/development.md`.
+- Determine whether the carrier has an audio track and whether it carries SynthID.
+
+### E1. Instrument validation: multiplexing and a session anchor (1-2 submissions)
+
+The verifier reports time ranges, so one file can carry several doses. A 24-second
+file of `[control 8 s | certified 0.15 8 s | control 8 s]` should read detected on
+the outer segments and not detected on the middle one, both halves already known
+from the manifest.
+
+`encode_video_frames` requires matching dimensions and one frame rate, so
+multiplexing works **only along the `noise_std` axis**, not across geometries: one
+multiplexed file per geometric envelope.
+
+Separately, submitting the existing detected file first in each session costs 10%
+of the quota, turns "the oracle may have changed" into a per-session gate, and
+measures the flip rate on a byte-identical file, a quantity every plan silently
+assumes is zero.
+
+### E2. Resolution ladder at fixed dose - the decisive axis (2 submissions per rung)
+
+A fixed value, not a ceiling. Rung 1 is `long_side = 768` with fps held at 12 so
+exactly one destruction axis moves. Jumping straight to 1920 is a bad first rung:
+a 3.75x jump makes a detected verdict uninformative about where the boundary lies.
+
+- **Matched control:** 768 / 12 / `noise_std = 0.10`, expected DETECTED. It is
+  strictly stronger than a plain re-encode control because it discharges the
+  envelope, the VAE round trip, and a nonzero dose at once, and it diffs directly
+  against the existing 512 row.
+- **Candidate:** 768 / 12 / 0.15.
+- **Positive:** the resolution axis is open; next rungs 1024 and then native with a
+  clamp, 2 submissions each.
+- **Negative:** the downscale contributes to removal. This is the most valuable
+  available negative: it kills the native-resolution proposals outright and turns
+  the question into how much dose must be spent to buy resolution back, at the
+  known exchange rate B = 2815.
+- Watch for a monotonicity violation: 768 / 0.10 reading NOT_DETECTED would
+  overturn the critics' spectral argument.
+
+### E3. Frame rate at fixed geometry and dose (2 submissions)
+
+Control 512 / 24 / 0.10 expected DETECTED; candidate 512 / 24 / 0.15 expected
+not detected. The mechanism is provable from source, so the prior is high, but the
+only counter-mechanism - per-frame count aggregation - is probabilistic and n = 1
+on an 8-second clip does not measure it. Certify on the longest clip that fits the
+90 s / 100 MB limits, because the risk compounds with frame count.
+
+Ranked below E2 because the outcome is nearly predetermined and the prize (judder)
+is smaller than the geometry prize. It is the safest bet if a guaranteed win is
+wanted.
+
+### E4. `noise_std = 0.0` as an oracle probe (1 submission) - deliberately low rank
+
+The local half of this probe is the cheapest high-information measurement in the
+program and already sits in E0 at zero oracle cost. The **oracle** half ranks low:
+it buys no quality by construction, and its likely DETECTED outcome is nearly
+deducible from the 0.10 row under monotonicity. Its one real value is that
+NOT_DETECTED here would be non-monotone against 0.10 and would refute the
+assumption underneath every ladder and bisection in this program. Worth one query,
+after E2 and E3.
+
+### E5. Stratified certification of the surviving operating point (15-30 submissions)
+
+Only after E2 and E3 produce a winner. Zero detections across at least 15
+stratified carriers (at least 3 per stratum: face closeup, fast motion, flat sky,
+dark night, text overlay) bounds the failure rate at 18.1%; 30 carriers bound it at
+9.5%. Add the project's 1.5x margin convention, at least 2 seeds, at least 2
+sessions, and per-track verdict recording.
+
+For the flat-sky stratum, check the source reads detected first: Google documents a
+"not enough details to watermark" state, so a clean reading there may say nothing
+about removal.
+
+## Surviving change candidates
+
+**S1. Fix the metric's reference frame (0 oracle submissions).** Add
+`source_psnr_db` (candidate upscaled back to native against the untouched source
+frame) **and** a separate post-mux pass that decodes the delivered file. The
+critics killed the original claim that this would expose crf 18: the candidate is
+captured at `:423`, before `frame_pipe.write` at `:430`, so no in-loop metric can
+see the codec. Only the post-mux pass covers resize, decimation, crf, and mux
+together. Use `INTER_AREA` or a fixed analytic size for the upscale so the CPU
+resize does not dominate the loop, and update both other consumers of the
+generator in the same change (`read_sampled_frames` at `:188-209`, and
+`scripts/video_synthid_sweep.py:147` where `np.stack(frames)` must keep receiving
+resized frames). Do not redefine the existing `psnr_db`: the two manifest rows stay
+comparable to each other only while that field keeps its exact current meaning.
+
+**S2. Frame rate as a fixed certified value (after E3).**
+`DEFAULT_VIDEO_SYNTHID_FPS` 12.0 to 24.0, keeping `min(fps, source_fps)`. A
+ceiling of 60.0 was **rejected**: it makes the delivered operating point a function
+of the user's source, so one sample from a family gets certified while the rest
+ship uncertified, and the risk direction is unfavorable. Port the VFR/PTS bridge
+(`probe_video_timestamps`, `timestamped_input`, currently only in
+`video_visible.py`): at native frame rate the output stops reading as a proxy, and
+silent CFR-ification becomes a master-quality defect. Add `fps` and `long_side`
+pins next to `tests/test_video_invisible.py:285`, tied to the certifying manifest
+row.
+
+**S3. Clamp and align `_fit_size` (0 oracle submissions, with a caveat).**
+`scale = min(1.0, long_side / max(width, height))` at `:88`; align the long side
+and derive the short side from the true aspect, rounding to the nearest multiple of
+8. The pinned `_fit_size(1280, 720, 512) == (512, 288)` survives. The caveat: the
+clamp is an **uncertified operator change for a whole class of users**, since a
+320x240 source is upscaled to 512x384 today and would run at 320x240 afterwards,
+and neither has been tested. Ship it as its own documented change, not as a
+drive-by fix.
+
+**S4. Extend the manifest schema and oracle protocol (0 submissions).** A
+precondition for the whole program. Record the verbatim verdict text, because an
+unclear state logged as not detected is exactly the silent regression the protocol
+exists to prevent.
+
+**S5. A sigma normalization contract (0 submissions, applies to the current path).**
+No VAE swap survived, but two elements are real risks today: `vae.config.scaling_factor`
+cannot be trusted, so log `latents.std()` at `:276` and assert the effective
+scaling factor at load; and any cross-model sigma transfer must match on the **RMS
+of the decoded pixel perturbation**, not on latent units.
+
+**S6. Additive texture masking - contingency on an E2 negative only.** Not energy
+preserving: the certified sigma stays as a floor everywhere and the mask only adds
+on top in textured regions. The original energy-preserving form was refuted - the
+mechanism normalizes and then clips, which breaks the claimed invariant by a
+content-dependent amount, and the proposed unit test asserted the invariant before
+the clip and would have stayed green. Energy preservation is also unsafe in
+principle: the detector does not need a full frame, and the verifier reports
+per-segment, so a flat region perturbed only at the floor is a crop carrying nearly
+the full carrier. The salvaged version has **no standalone PSNR win**; its only
+value is freeing distortion budget to spend on resolution if E2 shows the dose must
+rise. It additionally needs motion compensation for the mask (flow is computed at
+`:442`, after the decode at `:423`, so the loop must be restructured) and one
+deliberately bad candidate so `temporal_residual_ratio` acquires a known failing
+value: it has only ever been observed in [1.0072, 1.0578], so "the ratio looks
+fine" is currently an unfalsified claim.
+
+## Refuted proposals - do not resurrect
+
+- **Carrier-scale, resolution-invariant noise field.** "Carrier scale" is set by
+  our VAE's latent pitch, not the carrier's. The motivating arithmetic treats a
+  field on the latent grid as white at pixel resolution and is wrong by exactly the
+  square of the scale factor: white noise on a 240-wide latent already spans
+  0-120 cycles per frame, entirely inside the band the decoder reproduces. The
+  construction actually band-limits the perturbation from 0-120 to 0-32 cycles,
+  making it smoother - the first thing any spread-spectrum extractor's content
+  suppression removes - while moving its energy toward the peak of the contrast
+  sensitivity function, making it more visible. Bilinear upsampling is also
+  heteroscedastic, and global renormalization by `noise.std()` stamps a visible
+  amplitude lattice rather than fixing it.
+- **Native resolution plus tiling plus a carrier-scale field.** Inherits the
+  arithmetic above, concedes that native processing destroys less carrier without
+  proposing a replacement mechanism, and bundles four destruction axes into one
+  candidate on a 4-query budget so a detected verdict is undecomposable. Its cost
+  model was also wrong by roughly 10x. The salvageable parts moved into S1 and S3.
+- **`AutoencoderKLTemporalDecoder`.** Refuted independently by three critics.
+  Removal is a property of the encode-decode composition, so a strictly more
+  faithful decoder preserves more carrier at the same sigma. The class implements
+  neither slicing nor tiling, so `enable_slicing()` at `:135` raises
+  `NotImplementedError` and the documented bounded-memory property dies. Its
+  temporal receptive field needs windows of tens of frames, its license carries a
+  revenue restriction incompatible with an Apache-2.0 default, and its own
+  published table shows a **worse** FID (9.17 against 7.61).
+- **Wan or another temporal video VAE.** Hard refusal in code: `AutoencoderKLWan._encode`
+  uses `iter_ = 1 + (num_frame - 1) // 4`, so at the shipped `batch_size = 4` only
+  frame 0 is encoded and a 4-frame batch decodes back to 1, which makes
+  `zip(..., strict=True)` at `:429` raise. The proposed remedy of carrying the
+  causal feature cache across chunks is impossible through the public API, since
+  `clear_cache()` runs on both entry and exit of `_encode` and `_decode`.
+  `float(vae.config.scaling_factor)` at `:270` and `:292` also raises, because Wan
+  exposes `latents_mean`/`latents_std` instead. Logically, feeding 4:1 temporal
+  compression frames 83 ms apart either reconstructs well (carrier preserved, no
+  removal gain) or hallucinates (no quality prize); the two claims are mutually
+  exclusive.
+- **A 16-channel f8 VAE.** Self-refuted and confirmed by the critics. Quadrupling
+  latent channels roughly doubles L in Zhao's theorem, so sigma must roughly double
+  to hold removal, and the VAE frontier in the UnMarker results is monotone with no
+  published point where a more faithful autoencoder removes **more**. Predicted net
+  loss of 2-7.5 dB by its own arithmetic. Its config also carries
+  `scaling_factor = 0.2614`, so an unchanged `noise_std = 0.15` is about 30% weaker
+  in raw latent units. Only the normalization contract survived, as S5.
+- **A per-channel luma/chroma probe.** The arms match in absolute latent units but
+  not in relative dose per channel, since `scaling_factor` normalizes the aggregate
+  latent, so the very reading the probe exists for is confounded with dose. The
+  chroma arm is additionally subsampled by the yuv420p encode, which no current
+  metric sees. Maximum prize under 1 dB by its own fit.
+- **Post-processing with unsharp plus grain, as a shipped stage.** The
+  carrier-reimport argument is sound and was verified line by line: `unsharp_mask`
+  reads only its own argument ([`humanizer.py:79`](../src/remove_ai_watermarks/humanizer.py)),
+  and `adaptive_polish` touches the source only through one float. But reimport was
+  never the binding risk:
+  `cv2.addWeighted(img_f, 1.0 + amount, blurred, -amount, 0.0)` at
+  `_ADAPTIVE_MAX_UNSHARP = 1.0` multiplies the **surviving carrier residue** by up
+  to 2x as the terminal operation before encoding, and whether that re-arms a given
+  file depends on that file's unobservable margin. With no local decoder and only a
+  sampled oracle the stage is structurally uncertifiable, not merely expensive to
+  certify. The only rescue is moving sharpening **above** the VAE stage so the
+  removal operator stays terminal. Grain, which monotonically lowers detector SNR,
+  is the safe half and can be separated.
+
+## Measuring quality properly
+
+The current `psnr_db` cannot show the improvement this work exists to produce.
+Minimum upgrade:
+
+1. **`source_psnr_db`** - candidate upscaled back to native against the untouched
+   source frame. Good for ranking configurations against a common reference,
+   dominated by unrecoverable high-frequency content, so not a measure of what the
+   VAE costs.
+2. **A post-mux end-to-end pass** - decode the delivered file after
+   `mux_encoded_video` (`:456`) and compare against the source. The only measure
+   covering resize, decimation, crf, and mux together. Keep it out of the streaming
+   loop so `test_stream_batches_consumes_only_one_batch_ahead` stays valid.
+   Implemented as `scripts/video_fidelity_probe.py`, which streams, reports the
+   delivered file's bitrate, and shares the engine's frame-selection rule rather
+   than copying it.
+3. **DISTS** (arXiv:2004.07728), built to tolerate texture resampling - exactly
+   what the VAE does to foliage, skin, and grass, and exactly what PSNR and LPIPS
+   punish even when the result is perceptually equivalent. It separates "the VAE
+   resampled the grass" from "the VAE destroyed an edge".
+4. **VMAF** through `ffmpeg` `libvmaf`, cheapest to add, whose ADM/DLM feature
+   names this exact complaint. Its temporal term is only a mean absolute luma
+   difference between neighboring frames, so it is not a flicker detector: keep the
+   motion-compensated ratio.
+5. **Encoded file size as a third axis.** Every current metric is taken before the
+   pipe, so a bitrate explosion currently reads as "quality did not suffer". This
+   matters most for any perturbation that varies frame to frame: at fixed crf it
+   raises bitrate rather than lowering quality.
+6. **`temporal_residual_ratio` repairs**: add a p95 across frames next to the mean
+   so localized flicker stops being averaged away, add a long-horizon term against
+   the first frame, and replace `max(temporal_baseline, 1e-6)` with an explicit
+   undefined result on static shots.
+7. **A no-reference metric** (DOVER or FAST-VQA) for the case where no
+   full-reference measure can compare a 512/12 output against a 1024/24 output on
+   one scale. Relative ranking within a sweep only; absolute values are
+   uncalibrated for this artifact class.
+
+Nothing local measures removal. `remove_video_invisible` checks `get_ai_metadata`
+on the output, which is metadata, not pixels. Only a manifest row counts.
+
+## Risks
+
+**Error asymmetry is the governing constraint.** Shipping a leak means a user
+receives a watermarked file believing it is clean, with no local pixel decoder to
+catch it and no feedback path that would surface it. Staying conservative means a
+user receives 512 px / 12 fps, a cost that is visible, bounded, and reversible with
+an explicit flag. A symmetric test is therefore inadmissible, and the burden of
+proof sits entirely on the new default.
+
+**n = 1.** The current default is certified by one success on one carrier with one
+seed. Any quality change inherits that weakness and must not deepen it.
+
+**Content and seed dependence** is MEASURED on this project's image branch:
+survivors switch by content type, and near the threshold the same input flipped
+between runs on seed alone.
+
+**Oracle instability.** Three verdict states, not two. Per-segment reporting.
+Separate audio and visual tracks - and the pipeline byte-copies audio, so a Veo 3
+clip with generated sound leaves with its audio SynthID intact, and the manifest
+cannot even record which track the 2026-07-31 negative referred to. That is
+potentially a shipped product hole, not only an experimental confound. Session
+drift is currently unfalsifiable.
+
+**Observability narrows exactly where quality rises.** At fixed crf the bitrate
+grows with pixels per second, so the maximum duration fitting under 100 MB falls as
+fps and resolution rise. The configuration users actually receive becomes **less**
+observable than the one it replaces. That is a permanent property, not an
+inconvenience.
+
+**Ceilings instead of fixed values.** Any ceiling makes the delivered operating
+point a function of the user's source, and with it the perturbation's cycles per
+frame - the quantity carrying the certified margin. Ship fixed values.
+
+**Documentation and test surface.** Only `DEFAULT_VIDEO_SYNTHID_NOISE_STD` is
+pinned. Moving `long_side` or `fps` touches hardcoded numbers in `README.md`,
+`docs/known-limitations.md`, `docs/cli.md`, `docs/python-api.md`,
+`docs/module-internals.md`, `docs/synthid.md`, and `docs/verification-plan.md`.
+Drift-prone operational numbers should not live in seven places of prose; their
+source of truth is the manifest.
+
+**Silent configuration drift.** `sd-vae-ft-mse/config.json` carries no
+`scaling_factor`, so 0.18215 is a class default under an upper-unbounded
+`diffusers>=0.38.0` while `maintain.sh` runs `uv-outdated`. A library bump can move
+the certified operating point with a green suite.
+
+**Missing guards that get worse at native resolution.** There is no HDR or >8-bit
+rejection and no VFR/PTS bridge on the invisible path. A 512 px output plainly
+reads as a proxy; a native-resolution output reads as a master, and the cost of
+silently flattening a 10-bit PQ source to 8-bit SDR rises accordingly.
+
+**Do not bundle axes.** Raising `long_side`, raising `fps`, and lowering crf all
+reduce total destruction and all require recertification. The metric reference-frame
+fix is the only exception, because it changes the measurement rather than the
+pixels. Do not put a crf 18 to 14 change in the same candidate as a resolution
+change.

docs/watermarking-landscape.md

@@ -33,12 +33,24 @@ Grok JPEG downloads (Aurora model) carry **no C2PA, no XMP, no SynthID, no IPTC*
 **Stripped on removal too:** `remove_ai_metadata` calls `_scrub_ai_exif` on
 JPEG EXIF, which deletes the xAI Signature and UUID Artist pair plus supported
 AI generator values while retaining unrelated camera and editor EXIF. The
-shared `_is_xai_signature_pair` helper is the single source of truth for the
+shared `xai_signature_pair` helper is the single source of truth for the
 pair. On the ISOBMFF path, `blank_ai_exif_tokens` provides the corresponding
 in-place scrub for supported EXIF values, TC260 AIGC blocks, and the xAI pair.
-- **China TC260 AIGC label (caught by `AIGC_MARKERS` / `metadata.aigc_label`, surfaced by `identify` as the `aigc` signal):** China-served generators embed an XMP `<TC260:AIGC>{"Label":"1","ContentProducer":...}` block — China's mandatory AI-content labeling (TC260 namespace `tc260.org.cn/ns/AIGC`).
+- **China TC260 AIGC label (caught by `AIGC_MARKERS` / `metadata.aigc_label`, surfaced by `identify` as the `aigc` signal):** China-served generators embed an XMP `<TC260:AIGC>{"Label":"1","ContentProducer":...}` block — China's mandatory AI-content labeling (TC260 namespace `tc260.org.cn/ns/AIGC`). The label says only "this is AI", but its `ContentProducer` names the signing entity — `001` + `1` + an 18-char Unified Social Credit Code + a 5-digit product suffix, normalized by `metadata.uscc_of`, or for a few generators a bare product name. `KnownMark.tc260_producer_codes` maps the codes settled per vendor by `scripts/vendor_cohort_harvest.py` to registry mark keys, so an AIGC image relaxes the detector of the vendor it actually carries rather than a guessed pair; an unmapped or absent producer falls back to ByteDance's two products. A code identifies a legal entity, not necessarily one brand, so a hosting or aggregating platform that signs for several apps is a recall bet rather than a proof.
+
+**Doubao** (ByteDance) uses it (verified on a public issue sample; `ContentProducer` `001191110102MACQD9K64010000`, no C2PA/SynthID/imwatermark — the XMP block is the only signal; GitHub attachment upload did NOT strip it). The same standard is mandatory for Jimeng/Kling/Qwen/Ernie etc., so the one marker covers the whole China-AIGC-labeled ecosystem. `aigc_label` reads **four image serializations** through a shared `_parse` helper: the HTML-entity-encoded XMP `TC260:AIGC` block in **either RDF form** — the nested element `<TC260:AIGC>{...}</TC260:AIGC>` (Doubao) or the attribute `TC260:AIGC="{...}"` (**PicWish**, `ContentProducer="picwish"`, verified on compatible samples) — via a container-agnostic raw-byte scan (any JSON object accepted), a raw-JSON PNG `AIGC` tEXt chunk (Doubao also writes the label this way, no namespaced marker at all — confirmed on compatible samples, `ContentProducer="doubao"`), a bare raw-JSON `{"AIGC":{...}}` object embedded in **JPEG EXIF (UserComment)** by some China-served generators, brace-matched from the scan head with `json.JSONDecoder().raw_decode` (no namespaced marker, no PNG chunk — confirmed on compatible samples, `ContentProducer="001191440300708461136T1308L"`), **and** a bare `AIGC{...}` blob (the label glued straight to its JSON, no `"AIGC":` key wrapper) embedded in a **JPEG APP segment near the JFIF header** — confirmed on compatible samples. The two raw-JSON forms are scanned in one loop (`'"AIGC"'` then `AIGC{`) that **falls through on a non-TC260 / undecodable hit instead of returning** — a quoted `"AIGC"` can appear later in an XMP packet while the real label is a bare `AIGC{...}` earlier in the file, so an unconditional early return on the quoted form would shadow the bare form (the exact bug behind the 06-10 misses). Native MP4/MOV is a fifth serialization: TC260-PG-20257A stores an `AIGC` key in `moov.udta.meta.keys` and the raw JSON in the matching `ilst` item. The seeking parser reaches a tail `moov` without reading `mdat`; removal replaces the key with `free` and blanks the validated value at the same length so every box size and stream offset stays fixed. All generic forms are gated on at least one TC260 field (`TC260_AIGC_FIELDS`) so a generic `AIGC` key cannot false-positive; the namespaced XMP element is unambiguous and needs no gate. `TC260_AIGC_FIELDS` covers **two schemas**: the producer-side one (`Label` / `ContentProducer` / `ProduceID` / `ContentPropagator` / `PropagateID`, Doubao and most China gens) and the **service-provider** one (`ServiceProvider` / `ServiceUser`, plus generic `Time` / `ContentId` which are NOT gated on) — **Tencent Cloud's** AIGC variant (`ServiceProvider` = `腾讯云`), embedded in **EXIF `ImageDescription`**, verified on compatible samples. In `identify`, `aigc` fires on the parsed label **or** the `AIGC_MARKERS` byte scan (the latter preserves the laundering-tell case where the JSON payload is truncated).
+
+Native MKV/WebM is a sixth serialization. TC260-PG-20257A stores
+`TagName=AIGC` and the raw JSON `TagString` in
+`Segment.Tags.Tag.SimpleTag`. The bounded EBML reader skips cluster payloads;
+the existing ffmpeg stream-copy path removes the tags without transcoding.
+
+The same [TC260 video guide](https://www.tc260.org.cn/portal/article/303/4061772dcf684d8a96f395a4298e9e53)
+defines two more native serializations. AVI stores an `AIGC` child in
+`LIST/INFO`; FLV stores an AMF0 `AIGC` string under `script.onMetaData`. The
+bounded RIFF and FLV readers validate the JSON field set and skip media
+payloads. Removal remuxes either container through ffmpeg with stream copy.
 
-**Doubao** (ByteDance) uses it (verified on a public issue sample; `ContentProducer` `001191110102MACQD9K64010000`, no C2PA/SynthID/imwatermark — the XMP block is the only signal; GitHub attachment upload did NOT strip it). The same standard is mandatory for Jimeng/Kling/Qwen/Ernie etc., so the one marker covers the whole China-AIGC-labeled ecosystem. `aigc_label` reads **four serializations** through a shared `_parse` helper: the HTML-entity-encoded XMP `TC260:AIGC` block in **either RDF form** — the nested element `<TC260:AIGC>{...}</TC260:AIGC>` (Doubao) or the attribute `TC260:AIGC="{...}"` (**PicWish**, `ContentProducer="picwish"`, verified on compatible samples) — via a container-agnostic raw-byte scan (any JSON object accepted), a raw-JSON PNG `AIGC` tEXt chunk (Doubao also writes the label this way, no namespaced marker at all — confirmed on compatible samples, `ContentProducer="doubao"`), a bare raw-JSON `{"AIGC":{...}}` object embedded in **JPEG EXIF (UserComment)** by some China-served generators, brace-matched from the scan head with `json.JSONDecoder().raw_decode` (no namespaced marker, no PNG chunk — confirmed on compatible samples, `ContentProducer="001191440300708461136T1308L"`), **and** a bare `AIGC{...}` blob (the label glued straight to its JSON, no `"AIGC":` key wrapper) embedded in a **JPEG APP segment near the JFIF header** — confirmed on compatible samples. The two raw-JSON forms are scanned in one loop (`'"AIGC"'` then `AIGC{`) that **falls through on a non-TC260 / undecodable hit instead of returning** — a quoted `"AIGC"` can appear later in an XMP packet while the real label is a bare `AIGC{...}` earlier in the file, so an unconditional early return on the quoted form would shadow the bare form (the exact bug behind the 06-10 misses). All three generic forms (the PNG chunk, the bare `{"AIGC":...}` object, and the bare `AIGC{...}` blob) are gated on at least one TC260 field (`_TC260_FIELDS`) so a generic `AIGC` key cannot false-positive; the namespaced XMP element is unambiguous and needs no gate. `_TC260_FIELDS` covers **two schemas**: the producer-side one (`Label` / `ContentProducer` / `ProduceID` / `ContentPropagator` / `PropagateID`, Doubao and most China gens) and the **service-provider** one (`ServiceProvider` / `ServiceUser`, plus generic `Time` / `ContentId` which are NOT gated on) — **Tencent Cloud's** AIGC variant (`ServiceProvider` = `腾讯云`), embedded in **EXIF `ImageDescription`**, verified on compatible samples. In `identify`, `aigc` fires on the parsed label **or** the `AIGC_MARKERS` byte scan (the latter preserves the laundering-tell case where the JSON payload is truncated).
 - **HuggingFace-hosted job (caught by `metadata.huggingface_job`, surfaced by `identify` as the `hf_job` signal, MEDIUM confidence):** HuggingFace Jobs / Spaces can stamp generated PNGs with an `hf-job-id` tEXt chunk holding the job UUID. It marks the *hosting job*, not a model, so it lifts an Unknown verdict to a tentative AI via `hf_only` but never overrides a hard metadata signal. `_HF_JOB_CAVEAT` states the limit. Removal drops the chunk through the PNG metadata whitelist.
 - **No detectable signal on some downloads:** Recraft exports and some hosted
   FLUX surfaces can arrive without a supported local signal. Midjourney samples
@@ -49,12 +61,18 @@ in-place scrub for supported EXIF values, TC260 AIGC blocks, and the xAI pair.
 - **C2PA 2.4 "Durable Content Credentials" (April 2026; verified against the spec) raise the bar for metadata stripping.** 2.4 defines soft bindings (an invisible watermark or a content fingerprint) plus a server-side manifest repository and a new `c2pa.repository-receipt` assertion. Per the spec: "if a C2PA manifest is removed from an asset, but a copy of that manifest remains in a provenance store elsewhere, the manifest and asset may be matched using available soft bindings." So our local `metadata --remove` deletes the *embedded* manifest, but a fingerprint/watermark soft binding can still re-link the image to its manifest in a repository server-side. Stripping the file is becoming necessary-but-not-sufficient against durable provenance. (Our parsers target the stable embedded-manifest format documented in C2PA 2.1 §11; that format is unchanged in 2.4 -- the new pieces are repository/soft-binding infra, not the on-file box layout, so no parser change is implied.) Spec: https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html We now READ the soft-binding `alg` (`C2PA_SOFT_BINDINGS` / `soft_binding_vendors_in`) to name the forensic-watermark vendor, and locally DECODE the one open scheme, Adobe TrustMark (`trustmark_detector`); the rest (Digimarc/Imatag/Steg.AI/...) stay name-only (proprietary decoders).
 - **Built in the dated batch:** soft-binding vendor detection, IPTC Photo
   Metadata AI-disclosure fields, C2PA detection and stripping for supported
-  ISOBMFF video, and the optional Adobe TrustMark decoder. Visible video-logo
-  removal and proprietary audio-watermark detection remain outside the package.
+  ISOBMFF video, the optional Adobe TrustMark decoder, and temporally stabilized
+  visible Sora, Veo, Seedance, Dola, Hailuo, and Kling removal. Other visible
+  video logos and proprietary audio-watermark detection remain outside the
+  package.
   Metadata stripping for supported audio containers is a separate implemented
   path.
 
-**Box detection window — now handled (v0.6.8):** detection no longer relies on a fixed first-MB read. `metadata.scan_head(path, size)` reads the first `size` bytes and, for ISOBMFF, appends the payloads of late provenance boxes found by `isobmff.scan_c2pa_region` (a file-seeking top-level box walker that skips past `mdat` by size without reading it), so a C2PA/AIGC/IPTC manifest placed AFTER a large `mdat` in a streaming/non-faststart MP4 is now caught. Every C2PA/marker byte scan (`has_ai_metadata`, `aigc_label`, `iptc_ai_system`, `synthid_source`, `exif_generator` XMP, `get_ai_metadata` soft-binding, and `identify`) goes through `scan_head`; it is behavior-neutral for non-ISOBMFF inputs (exactly `f.read(size)`).
+**Box detection window — now handled (v0.6.8):** detection no longer relies on a fixed first-MB read. `metadata.scan_head(path, size)` reads the first `size` bytes and, for ISOBMFF, appends the payloads of late provenance boxes found by `isobmff.scan_c2pa_region` (a file-seeking top-level box walker that skips past `mdat` by size without reading it), so a C2PA/AIGC/IPTC manifest placed AFTER a large `mdat` in a streaming/non-faststart MP4 is now caught. Every C2PA/marker byte scan (`has_ai_metadata`, `aigc_label`, `iptc_ai_system`, `synthid_source`, `exif_generator` XMP, `get_ai_metadata` soft-binding, and `identify`) goes through `scan_head`; for PNG it likewise appends the payloads of `tEXt` / `iTXt` / `zTXt` / `eXIf` / `iCCP` chunks that start beyond the window (`_png_late_metadata`, seeking past `IDAT`), which is how a TC260 AIGC label appended after the pixel stream is caught; for WebP it appends the `EXIF` / `XMP ` / `ICCP` / `C2PA` chunks past the window (`_riff_late_metadata`, stepping over the coded image), which is how an IPTC "Made with AI" tag stored after the pixels is caught; and for a file at least `size` bytes long it finally appends the metadata text the decoder reaches but a raw read cannot (`_decoder_visible_text`), which covers a compressed PNG `zTXt` packet no byte scan can spell; for any file that fits inside `size`, it is exactly `f.read(size)`.
+
+Native TC260 MP4/MOV tags do not live in those top-level provenance boxes.
+`tc260_aigc_payloads` separately seeks through `moov.udta.meta.keys/ilst`, so
+the normative tag is also found when a large `mdat` precedes `moov`.
 
 **Meta-box XMP and EXIF removal are handled in place:** an AI-label XMP packet
 stored as a meta-box `mime` item is blanked by
@@ -69,6 +87,42 @@ against primary sources before adding jurisdiction-specific claims.
 
 **Google Gemini visible "sparkle" -- tier-dependent, and spec-undocumented by Google.** Google primary sources (the Nano Banana Pro blog and the gemini.google image-generation page, both WebFetch-verified) confirm Gemini images carry BOTH the invisible SynthID (on ALL Google-AI media) AND a visible sparkle, but the visible mark is **tier-gated**: applied for FREE and Google AI **Pro** users, and **REMOVED** for Google AI **Ultra** subscribers, inside **Google AI Studio**, and on **API / dev** output. So a Google-C2PA image with NO visible sparkle is expected (Ultra / API), not evidence it is clean -- this reinforces the `identify` "no visible mark != clean" rule. The ONLY official verifier is the SynthID flow (upload to the Gemini app, ask if it is AI-generated), which reads the INVISIBLE mark; there is **no official visible-sparkle detector**, and Google publishes **no** glyph geometry / size / opacity / color / locale / placement spec. So our capture-based sparkle template is the only source of truth and cannot be validated against a vendor spec -- keep reverse-engineering from real captures (do not expect a published spec).
 
+**Google Veo video marks use two incompatible visible designs.** Public raw
+clips verify the current four-point diamond and the legacy bottom-right `Veo`
+text. The independent
+[VeoWatermarkRemover](https://github.com/allenk/VeoWatermarkRemover) project
+reports the same current-versus-legacy split, multiple output layouts, and the
+need for cross-frame position agreement. Our implementation copies no logo
+pixels or alpha maps from that project: it uses two synthetic silhouettes,
+known-layout searches plus a strong relocated-diamond fallback, and a separate
+temporal arbiter calibrated against raw watermarked clips and clean API exports.
+
+**ByteDance video surfaces use distinct visible labels.** Public Seedance
+showcase clips contain a fixed rounded box with `AI`, while the Dola sample in
+[issue #16](https://github.com/wiltodelta/remove-ai-watermarks/issues/16) uses
+fixed `Dola AI` text. The independent
+[Seedance remover](https://github.com/SamurAIGPT/seedance-2.0-watermark-remover)
+estimates a static corner from a temporal mean frame and edge density. Our
+implementation instead matches provider-specific synthetic silhouettes on
+every frame, then requires an anchored temporal run. This extra anchor check
+was necessary because a moving clean scene detail could retain enough adjacent
+overlap to pass a recurrence-only gate.
+
+**Hailuo and Kling use larger fixed composite labels.** Verified Hailuo exports
+carry a lower-edge waveform, `MINIMAX`, separator, Hailuo ring, and
+`hailuo AI` text. Verified Kling exports carry a bottom-right swirl,
+`KLING AI`, a changing version suffix, and sometimes `PRO`. The detectors use
+only synthetic primitives and fonts. Hailuo expands the matched core to cover
+the complete composite. Kling combines a version-independent text core with a
+synthetic ring rescue, then requires the recurring candidate to reach the
+expected frame edge and contain enough bright low-saturation pixels. Those
+extra gates were added after clean Luma and PixVerse scene details passed shape
+and temporal recurrence alone. The generic
+[WatermarkRemover-AI](https://github.com/D-Ogi/WatermarkRemover-AI) project
+instead uses Florence-2 to identify arbitrary watermarks before LaMa
+inpainting. That is broader, but it carries a much heavier model and a less
+auditable detection boundary than the provider-specific synthetic path here.
+
 **The faint-visible-mark precision/recall wall is fundamental, not a heuristic artifact.** The visible-watermark-detection literature has moved to LEARNED segmentation / object-detection (WDNet WACV'21 arXiv:2012.07616; SLBR ACM MM'21, open code+weights; the PRCV'18 large-scale detector; Su et al. survey 2025), but three verified findings bound what a learned detector actually buys: (1) a claim that a confidence threshold "cleanly separates" true from false matches even with a learned CNN front-end was **REFUTED** in verification (arXiv:1705.08593) -- the precision/recall wall persists even with learned features. (2) Learned detectors need a LARGE, pattern-diverse labeled dataset trained on synthetic composites (PRCV'18: 60k images / 80 watermark classes; CLWD: 60k / 160 marks), and off-distribution degradation is a documented real axis (models trained on limited-pattern LVW transfer worse; diversity of training patterns drives generalization). (3) Inference is cheap (WDNet ~8 ms at 256x256) -- the cost is the data pipeline, not runtime. Net: a learned detector shifts the frontier but does NOT remove the wall; for a SINGLE mark the cheapest next step is a small patch classifier (real-sparkle vs false-positive) on top of the existing NCC localizer, not a full segmentation model. SLBR is a ready baseline. The current NCC + false-positive gate (core-ring brightness margin + gradient-NCC crispness + white-core saturation) is a sound operating point, and the residual miss is the information-theoretic wall the literature confirms.
 
 **Visible-mark landscape beyond the registry.** Meta stamps a visible "Imagined with AI" mark (bottom-LEFT, a small symbol) on its OWN Meta AI / "Imagine" output; for third-party images it relies on C2PA / IPTC, not a visible mark. Samsung Galaxy AI additionally uses a **four-star icon** variant in a corner alongside the localized text wordmark `samsung_engine` calibrates (only the Italian text variant is covered) -- the icon is a distinct, uncovered variant. Every source agrees visible + metadata marks are trivially removable (crop / screenshot, ~2 s), which is the tool's premise.

packaging/conda/recipe.yaml

@@ -1,7 +1,7 @@
 schema_version: 1
 
 context:
-  version: "0.10.1"
+  version: "0.26.0"
   python_min: "3.10"
 
 package:
@@ -10,7 +10,7 @@ package:
 
 source:
   url: https://pypi.org/packages/source/r/remove-ai-watermarks/remove_ai_watermarks-${{ version }}.tar.gz
-  sha256: ec92b450363d947cd897f0b75c18e75c2988ff79314ea247333ba892470b5a77
+  sha256: 0a8c8126d74cd7f818e5595eef2f269db5cefb8d90febd424f991c5850c8025b
 
 build:
   noarch: python
@@ -26,10 +26,11 @@ requirements:
     - python >=${{ python_min }}
     - pillow >=10.0.0
     - piexif >=1.1.3
-    - numpy >=1.24.0
-    - py-opencv >=4.8.0
     - click >=8.0.0
     - python-dotenv >=1.0.0
+    # c2pa-python is a default PyPI dependency but is not packaged on conda-forge.
+    # The guarded import falls back to the built-in C2PA byte scanner when it is
+    # absent. Add it here once a c2pa-python feedstock exists.
 
 tests:
   - python:
@@ -46,14 +47,12 @@ tests:
 
 about:
   homepage: https://github.com/wiltodelta/remove-ai-watermarks
-  summary: Remove visible and invisible AI watermarks from images
+  summary: Inspect and strip AI provenance metadata from media
   description: |
-    Detect and remove visible AI watermarks (Gemini / Nano Banana sparkle,
-    ByteDance Doubao and Jimeng, Samsung Galaxy AI) and strip AI-provenance
-    metadata (C2PA, EXIF, IPTC, PNG text chunks) from images. The core package
-    covers the identify / metadata / visible / erase command surface; optional
-    pip extras add SynthID diffusion removal and additional invisible-watermark
-    detectors.
+    Inspect and strip AI-provenance metadata (C2PA, EXIF, IPTC, and PNG text
+    chunks) from images and supported video containers. Optional pip extras add
+    visible watermark removal, video processing, SynthID diffusion removal, and
+    additional invisible-watermark detectors.
   license: Apache-2.0
   license_file: LICENSE
   repository: https://github.com/wiltodelta/remove-ai-watermarks

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "remove-ai-watermarks"
-version = "0.20.0"
-description = "AI watermark remover: strip visible and invisible AI watermarks (Gemini / Nano Banana sparkle, SynthID) and provenance metadata (C2PA, EXIF) from images"
+version = "0.26.1"
+description = "AI watermark remover for visible, invisible, and provenance marks in images and video"
 readme = "README.md"
 requires-python = ">=3.10.1"
 license = {text = "Apache-2.0"}
@@ -37,6 +37,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Multimedia :: Graphics",
     "Topic :: Multimedia :: Graphics :: Graphics Conversion",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
@@ -46,20 +47,12 @@ classifiers = [
 ]
 dependencies = [
     "pillow>=10.0.0",
-    # HEIC/AVIF pixel decode for the removal path (iPhone photos, modern exports):
-    # OpenCV cannot decode these containers, so image_io.imread falls back to Pillow
-    # and pillow-heif (bundled libheif, prebuilt wheels) registers the HEIF+AVIF
-    # openers. The metadata path already handles them via a plugin-free binary scan;
-    # this closes the same gap for the pixel path so `visible`/`all` work on them.
-    "pillow-heif>=0.13.0",
     "piexif>=1.1.3",
-    "numpy>=1.24.0",
-    "opencv-python-headless>=4.8.0",
     "click>=8.0.0",
     "python-dotenv>=1.0.0",
     # Official C2PA reader (Content Authenticity Initiative, MIT/Apache-2.0). The
     # primary, spec-tracking manifest parser for the identify/metadata path; the
-    # hand-rolled caBX/CBOR scanner in noai/c2pa.py is kept only as a fallback for
+    # hand-rolled caBX/CBOR scanner in _internal/c2pa.py is kept only as a fallback for
     # synthetic/partial blobs the validator rejects. Binary wheel (Rust), but the
     # import is light (no torch/numpy) so it fits the dependency-light identify
     # host. Prebuilt wheels cover the full CI matrix (linux/macos/windows).
@@ -67,17 +60,38 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-gpu = [
+pixels = [
+    "numpy>=1.24.0",
+    "opencv-python-headless>=4.8.0",
+]
+# Optional HEIC/AVIF pixel decode. Metadata scanning handles these containers
+# without this plugin; combine `heif` with any pixel feature only when needed.
+heif = [
+    "pillow-heif>=0.13.0",
+]
+visible = ["remove-ai-watermarks[pixels]"]
+# Video visible removal uses the shared pixel runtime. PyAV packetizes processed
+# VFR frames with explicit PTS before system ffmpeg encodes them. PyAV 18 requires
+# Python 3.11; the 16.x wheel line still covers Python 3.10.
+video = [
+    "remove-ai-watermarks[visible]",
+    "av>=16,<17; python_version < '3.11'",
+    "av>=18,<19; python_version >= '3.11'",
+]
+# Open DWT-DCT watermarks used by Stable Diffusion / SDXL / FLUX. The in-tree
+# decoder avoids the upstream invisible-watermark package's mandatory torch and
+# non-headless OpenCV dependencies.
+detect = [
+    "remove-ai-watermarks[pixels]",
+    "PyWavelets>=1.1.1",
+]
+diffusion = [
+    "remove-ai-watermarks[pixels]",
+    # A CUDA-enabled torch build is required: invisible-watermark removal has no
+    # CPU, MPS or XPU path. The default PyPI wheel carries CUDA on Linux/Windows;
+    # on macOS there is no CUDA build and this extra installs only for the
+    # non-diffusion imports it shares.
     "torch>=2.0.0",
-    # The default PyPI torch wheel is a CPU/CUDA build. To drive an Intel GPU
-    # (Arc / Data Center) via ``--device xpu`` you need an XPU-enabled torch
-    # from PyTorch's XPU wheel index (Linux/Windows only -- there is no macOS
-    # XPU build). Install that build first, then this extra (torch is then
-    # already satisfied and won't be re-pulled):
-    #   pip install torch --index-url https://download.pytorch.org/whl/xpu
-    #   pip install 'remove-ai-watermarks[gpu]'
-    # uv users can target the ``pytorch-xpu`` index declared under [tool.uv]:
-    #   uv pip install torch --index-url https://download.pytorch.org/whl/xpu
     "diffusers>=0.38.0",
     # diffusers 0.38's auto-pipeline registry imports ``Qwen3VLForConditional
     # Generation`` (its ``nucleusmoe_image`` pipeline), which only exists in
@@ -95,23 +109,13 @@ gpu = [
 ]
 # Full two-stage high-fidelity profile: Qwen-Image-2512 Lightning + DiffSynth
 # Canny ControlNet for the frame, then SAM-masked Z-Image Turbo face repair.
-# CUDA-only and intentionally separate from the normal gpu extra because the
+# CUDA-only and intentionally separate from the normal diffusion extra because the
 # additional model stack and DiffSynth runtime are large.
 qwen-zimage = [
-    "remove-ai-watermarks[gpu]",
+    "remove-ai-watermarks[diffusion]",
     "diffsynth>=2.0.17,<3",
     "torchvision>=0.20.0",
 ]
-# Open invisible-watermark (imwatermark) decoder for detecting the DWT-DCT
-# watermarks embedded by Stable Diffusion / SDXL / FLUX. Optional because it
-# pulls non-headless opencv AND torch (invisible-watermark declares torch a hard
-# dependency, and WatermarkDecoder eagerly imports rivaGan -> torch at import
-# time, so the dwtDct-only detect path still needs torch present even though it
-# never runs on GPU). So `detect` alone pulls torch -- no need to add `gpu` for
-# detection. identify() guards the import and skips the signal when absent.
-detect = [
-    "invisible-watermark>=0.2.0",
-]
 # Adobe TrustMark decoder -- the open, keyless watermark behind Adobe Durable
 # Content Credentials (soft-binding alg ``com.adobe.trustmark.P``). Optional
 # because it pulls torch and downloads model weights on first use. identify()
@@ -124,7 +128,11 @@ trustmark = [
 # cached by huggingface_hub; it is never bundled in this repo. The default cv2
 # eraser backend needs none of this.
 lama = [
-    "onnxruntime>=1.16.0",
+    "remove-ai-watermarks[visible]",
+    # ONNX Runtime 1.24 dropped CPython 3.10 wheels; keep the project's
+    # supported 3.10 line on the last compatible release series.
+    "onnxruntime>=1.16.0,<1.24; python_version < '3.11'",
+    "onnxruntime>=1.16.0; python_version >= '3.11'",
     "huggingface-hub>=0.20.0",
 ]
 # Lightweight inpaint backend -- MI-GAN via onnxruntime (andraniksargsyan/migan,
@@ -133,25 +141,18 @@ lama = [
 # memory-tight learned tier (vs big-LaMa's ~4.7 GB). Select it explicitly when
 # LaMa, the quality-first `auto` choice, is too large. Same runtime as `lama`.
 migan = [
-    "onnxruntime>=1.16.0",
+    "remove-ai-watermarks[visible]",
+    "onnxruntime>=1.16.0,<1.24; python_version < '3.11'",
+    "onnxruntime>=1.16.0; python_version >= '3.11'",
     "huggingface-hub>=0.20.0",
 ]
-# Optional pre-diffusion super-resolution for small inputs (Real-ESRGAN). Loaded via
-# spandrel (MIT) -- a pure model-loader with NO basicsr dependency (it pulls only
-# torch / torchvision / safetensors / numpy / einops).
-# The Real-ESRGAN weights (BSD-3-Clause) download on first use and are cached; they
-# are never bundled. CPU works but is slow on large inputs -- it is meant for the
-# pre-diffusion upscale of SMALL inputs (and the GPU worker). Guarded by
-# upscaler.is_available(); the default upscaler stays Lanczos (cv2, no deps). The
-# weights are fetched with torch.hub (bundled with spandrel's torch), so no extra
-# download dependency is needed.
-esrgan = [
-    "spandrel>=0.3.0",
-]
 dev = [
+    "remove-ai-watermarks[video]",
+    "remove-ai-watermarks[detect]",
     "pytest>=8.0.0",
     "pytest-cov>=4.1.0",
     "pytest-xdist>=3.5.0",
+    "packaging>=24.0",
     "ruff>=0.4.0",
     "pyright>=1.1.0",
     "invisible-watermark>=0.2.0",
@@ -160,16 +161,9 @@ dev = [
     "uv-outdated>=0.1.0; python_version >= '3.12'",
     "uv-secure>=0.12.0; python_version >= '3.12'",
 ]
-all = ["remove-ai-watermarks[gpu,detect,trustmark,lama,migan,dev]"]
-
-# PyTorch Intel-GPU (XPU) wheel index. ``explicit = true`` keeps it inert for
-# the default CPU/CUDA install: uv consults it only when a torch install
-# explicitly targets it (see the ``gpu`` extra comment), so it does not alter
-# the locked CPU/CUDA resolution. Linux/Windows only -- no macOS XPU build.
-[[tool.uv.index]]
-name = "pytorch-xpu"
-url = "https://download.pytorch.org/whl/xpu"
-explicit = true
+# ``qwen-zimage`` already pulls ``diffusion``; naming both would suggest diffusion is
+# independently sufficient for a removal, which it is not.
+all = ["remove-ai-watermarks[video,heif,detect,trustmark,qwen-zimage,lama,migan]"]
 
 [project.scripts]
 remove-ai-watermarks = "remove_ai_watermarks.cli:main"
@@ -185,9 +179,20 @@ build-backend = "hatchling.build"
 packages = ["src/remove_ai_watermarks"]
 
 [tool.hatch.build.targets.sdist]
-# Keep the source distribution small: ship the package and metadata, not
-# calibration or evaluation data under data/. The wheel ships only src/.
-exclude = ["/data"]
+# Keep the source distribution small and public-safe: ship tracked source and
+# metadata, not corpora or local research/session artifacts. The wheel ships
+# only src/.
+include = [
+    "/src",
+    "/LICENSE",
+    "/README.md",
+    "/pyproject.toml",
+]
+exclude = [
+    "/data",
+    "/tmp",
+    "/.sc",
+]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
@@ -210,8 +215,8 @@ ignore = [
 [tool.ruff.lint.per-file-ignores]
 "scripts/*.py" = ["G004", "S108", "S310", "T20"]
 "tests/*.py" = ["ANN", "S101", "S105", "S106", "S108"]
-"src/remove_ai_watermarks/noai/watermark_remover.py" = ["S603", "S606", "S607", "T201"]  # subprocess calls for auto-install/CUDA fix
-"src/remove_ai_watermarks/noai/c2pa.py" = ["S110"]  # try-except-pass for corrupt file handling
+"src/remove_ai_watermarks/_internal/watermark_remover.py" = ["S603", "S606", "S607"]  # nvidia-smi capability probe
+"src/remove_ai_watermarks/_internal/c2pa.py" = ["S110"]  # try-except-pass for corrupt file handling
 
 [tool.ruff.format]
 quote-style = "double"

scripts/ai_score.py

@@ -1,436 +0,0 @@
-"""AI-generation scorer for scanned datasets.
-
-Trains a gradient-boosted classifier on the metadata-derived labels of a
-scan_dataset.py output and scores every file, WITHOUT needing the
-metadata to be present at scoring time: the features are pixel and
-container statistics, so a metadata-stripped file still gets a score.
-The model is distribution-specific by design; evaluate it again before
-using it on an unrelated target distribution.
-
-Modes:
-    uv run --with scikit-learn python scripts/ai_score.py train <scan_glob> <model.pkl> [v1|v2]
-    uv run --with scikit-learn python scripts/ai_score.py score <scan_glob> <model.pkl> <out.jsonl>
-
-<scan_glob> is a glob of scan_dataset shards, e.g. 'data/scan/part_*.jsonl'.
-score output: one JSON line per file with file, sha256, ai_score, and the
-label evidence when a metadata label existed (for monitoring drift).
-"""
-
-import glob
-import json
-import math
-import pickle
-import sys
-from collections import defaultdict
-from pathlib import Path
-from typing import Any, Literal
-
-import numpy as np
-
-# AI-generator names in C2PA claim_generator_info (metadata-level truth).
-AI_GENERATORS = (
-    "openai",
-    "adobe firefly",
-    "adobe_firefly",
-    "microsoft responsible ai",
-    "microsoft_designer",
-    "black forest labs",
-    "fal-ai",
-    "bria",
-    "chatgpt",
-    "stability",
-    "dreamina",
-    "canva",
-)
-# Human-origin software (negative evidence, NOT proof by itself).
-HUMAN_SOFTWARE = (
-    "photoshop",
-    "lightroom",
-    "picsart",
-    "snapseed",
-    "paint.net",
-    "gimp",
-    "capture one",
-    "meitu",
-    "xingtu",
-    "snow",
-)
-
-_FEAT_SCALAR = [
-    ("noise", "noise_std"),
-    ("noise", "noise_kurtosis"),
-    ("fft", "cfa_peak"),
-    ("ela", "ela_mean"),
-    ("ela", "ela_p95"),
-    ("gradient", "laplacian_var"),
-    ("color", "saturation_mean"),
-    ("color", "value_mean"),
-    ("dct", "benford_mad"),
-]
-FeatureSchema = Literal["v1", "v2"]
-_FFT_BANDS = 8
-_GRADIENT_BINS = 10
-_COLOR_BINS = 64
-_DCT_AC_POSITIONS = 8
-_DCT_AC_BINS = 21
-_JPEG_QUANT_TABLES = 2
-_JPEG_QUANT_VALUES = 64
-_SCORE_BATCH = 4096
-
-_V1_FEATURE_NAMES = (
-    *(key for _, key in _FEAT_SCALAR),
-    *(f"fft_band_energy_{index}" for index in range(_FFT_BANDS)),
-    *(f"gradient_hist_{index}" for index in range(_GRADIENT_BINS)),
-    *(f"color_hist_4x4x4_{index}" for index in range(_COLOR_BINS)),
-    "jpeg_444",
-    "jpeg_progressive",
-    "megapixels",
-    "aspect_ratio",
-    "format_jpeg",
-    "format_png",
-)
-_V2_EXTRA_FEATURE_NAMES = (
-    "cfa_peak_0",
-    "cfa_peak_1",
-    *(f"dct_ac_{position}_{bin_index}" for position in range(_DCT_AC_POSITIONS) for bin_index in range(_DCT_AC_BINS)),
-    *(f"jpeg_quant_{table}_{index}" for table in range(_JPEG_QUANT_TABLES) for index in range(_JPEG_QUANT_VALUES)),
-    "jpeg_quant_table_count",
-    "jpeg_huffman_table_count",
-    "jpeg_huffman_total_bytes",
-    "jpeg_scan_count",
-    "jpeg_restart_interval",
-    "jpeg_precision_bits",
-    "jpeg_adobe_transform",
-    "jpeg_jfif_present",
-    "format_webp",
-    "format_isobmff",
-    "format_other",
-)
-_SCHEMA_FEATURE_NAMES: dict[str, tuple[str, ...]] = {
-    "v1": _V1_FEATURE_NAMES,
-    "v2": _V1_FEATURE_NAMES + _V2_EXTRA_FEATURE_NAMES,
-}
-
-
-def parse_schema(value: Any) -> FeatureSchema:
-    """Validate a feature-schema token (CLI argument or model-bundle field)."""
-    if value == "v1" or value == "v2":
-        return value
-    raise ValueError(f"Unknown feature schema: {value!r}")
-
-
-def feature_names(schema: FeatureSchema = "v1") -> tuple[str, ...]:
-    """Return the stable ordered feature names for a model schema."""
-    return _SCHEMA_FEATURE_NAMES[parse_schema(schema)]
-
-
-def _fixed_values(values: Any, count: int, *, normalize: bool = False) -> list[float]:
-    """Return a fixed-width float vector, padding absent values with NaN."""
-    if not isinstance(values, (list, tuple)):
-        return [float("nan")] * count
-    result = [float(value) for value in values[:count]]
-    if normalize and result:
-        total = sum(value for value in result if math.isfinite(value))
-        if total > 0:
-            result = [value / total for value in result]
-    return result + [float("nan")] * (count - len(result))
-
-
-def _optional_float(mapping: dict[str, Any], key: str) -> float:
-    value = mapping.get(key)
-    return float(value) if isinstance(value, (int, float)) else float("nan")
-
-
-def label_of(record: dict[str, Any]) -> int | None:
-    """1 = strong metadata AI, 0 = human-origin, None = unlabeled."""
-    store = record.get("c2pa_store") or {}
-    for m in (store.get("manifests") or {}).values():
-        for cgi in m.get("claim_generator_info") or []:
-            if any(g in str(cgi.get("name", "")).lower() for g in AI_GENERATORS):
-                return 1
-        for a in m.get("assertions") or []:
-            d = a.get("data") if isinstance(a.get("data"), dict) else {}
-            if "trainedAlgorithmicMedia" in str(d.get("digitalSourceType", "")):
-                return 1
-    for c in record.get("png_chunks", []):
-        t = c.get("text", "")
-        kw = t.split("\x00")[0]
-        if kw in ("prompt", "workflow", "parameters") or "AIGC" in t[:80]:
-            return 1
-    exif = record.get("exif", {})
-    z = exif.get("0th") or {}
-    e = exif.get("Exif") or {}
-    if z.get("Make") and z.get("Model") and (e.get("MakerNote") or e.get("LensModel") or e.get("LensMake")):
-        return 0
-    for c in record.get("png_chunks", []):
-        if c.get("apple_screenshot_marker"):
-            return 0
-    for v in (record.get("iptc") or {}).values():
-        if str(v).strip() == "Screenshot":
-            return 0
-    if any(t in str(z.get("Software", "")).lower() for t in HUMAN_SOFTWARE):
-        return 0
-    return None
-
-
-def features_of(record: dict[str, Any], *, schema: FeatureSchema = "v1") -> list[float]:
-    """The structural feature vector (pixel + container stats, no metadata)."""
-    v = [float((record.get(s) or {}).get(k, np.nan)) for s, k in _FEAT_SCALAR]
-    fft = record.get("fft") or {}
-    gradient = record.get("gradient") or {}
-    color = record.get("color") or {}
-    v.extend(_fixed_values(fft.get("fft_band_energy"), _FFT_BANDS))
-    v.extend(_fixed_values(gradient.get("gradient_hist"), _GRADIENT_BINS))
-    v.extend(_fixed_values(color.get("color_hist_4x4x4"), _COLOR_BINS))
-    jf = record.get("jpeg_forensics") or {}
-    v.append(1.0 if jf.get("subsampling") == "4:4:4" else 0.0)
-    v.append(1.0 if jf.get("progressive") else 0.0)
-    pil = record.get("pil") or {}
-    w, h = pil.get("width") or 0, pil.get("height") or 0
-    v += [float(w * h) / 1e6, float(w) / max(h, 1)]
-    fmt = record.get("content_format")
-    v += [1.0 if fmt == "jpeg" else 0.0, 1.0 if fmt == "png" else 0.0]
-    if schema == "v2":
-        v.extend(_fixed_values(fft.get("cfa_peaks"), 2))
-        dct_hist = (record.get("dct") or {}).get("dct_ac_hist")
-        for position in range(_DCT_AC_POSITIONS):
-            values = dct_hist[position] if isinstance(dct_hist, list) and position < len(dct_hist) else None
-            v.extend(_fixed_values(values, _DCT_AC_BINS, normalize=True))
-        quant_tables = jf.get("quant_tables")
-        for table in range(_JPEG_QUANT_TABLES):
-            values = quant_tables.get(str(table)) if isinstance(quant_tables, dict) else None
-            v.extend(_fixed_values(values, _JPEG_QUANT_VALUES))
-        is_jpeg = fmt == "jpeg"
-        huffman_tables = jf.get("huffman_tables_hex")
-        huffman_values = huffman_tables if isinstance(huffman_tables, list) else []
-        v.extend(
-            [
-                float(len(quant_tables)) if isinstance(quant_tables, dict) else (0.0 if is_jpeg else float("nan")),
-                float(len(huffman_values)) if is_jpeg else float("nan"),
-                (
-                    float(sum(len(value) // 2 for value in huffman_values if isinstance(value, str)))
-                    if is_jpeg
-                    else float("nan")
-                ),
-                _optional_float(jf, "scan_count"),
-                _optional_float(jf, "restart_interval"),
-                _optional_float(jf, "precision_bits"),
-                _optional_float(jf, "adobe_transform"),
-                1.0 if jf.get("jfif") else (0.0 if is_jpeg else float("nan")),
-                1.0 if fmt == "webp" else 0.0,
-                1.0 if isinstance(fmt, str) and fmt.startswith("isobmff:") else 0.0,
-                (
-                    1.0
-                    if fmt is not None and fmt not in {"jpeg", "png", "webp"} and not str(fmt).startswith("isobmff:")
-                    else 0.0
-                ),
-            ]
-        )
-    elif schema != "v1":
-        raise ValueError(f"Unknown feature schema: {schema}")
-    expected = len(feature_names(schema))
-    if len(v) != expected:
-        raise ValueError(f"Feature schema {schema} produced {len(v)} values; expected {expected}")
-    return v
-
-
-def grouped_stratified_split(
-    labels: np.ndarray,
-    hashes: np.ndarray,
-    *,
-    test_size: float = 0.3,
-    random_state: int = 0,
-) -> tuple[np.ndarray, np.ndarray]:
-    """Split records by hash while preserving label balance across hash groups."""
-    if len(labels) != len(hashes):
-        raise ValueError("labels and hashes must have equal length")
-    if not 0 < test_size < 1:
-        raise ValueError("test_size must be between 0 and 1")
-    groups: dict[str, list[int]] = defaultdict(list)
-    group_labels: dict[str, int] = {}
-    for index, (label, digest) in enumerate(zip(labels, hashes, strict=True)):
-        key = str(digest) if digest else f"__row_{index}"
-        int_label = int(label)
-        if key in group_labels and group_labels[key] != int_label:
-            raise ValueError(f"Hash {key!r} has conflicting labels")
-        group_labels[key] = int_label
-        groups[key].append(index)
-    keys_by_label: dict[int, list[str]] = defaultdict(list)
-    for key, label in group_labels.items():
-        keys_by_label[label].append(key)
-    rng = np.random.default_rng(random_state)
-    test_set: set[str] = set()
-    for class_keys in keys_by_label.values():
-        if len(class_keys) < 2:
-            raise ValueError("Each label needs at least two distinct hash groups")
-        shuffled = np.asarray(class_keys)
-        rng.shuffle(shuffled)
-        test_count = min(max(round(len(shuffled) * test_size), 1), len(shuffled) - 1)
-        test_set.update(shuffled[:test_count].tolist())
-    train_set = set(groups) - test_set
-    train = np.asarray([index for key, indices in groups.items() if key in train_set for index in indices])
-    test = np.asarray([index for key, indices in groups.items() if key in test_set for index in indices])
-    return np.sort(train), np.sort(test)
-
-
-def temporal_holdout_split(
-    dates: np.ndarray,
-    hashes: np.ndarray,
-    *,
-    train_fraction: float = 0.7,
-) -> tuple[np.ndarray, np.ndarray, str]:
-    """Split chronologically and remove later copies of training hashes."""
-    if len(dates) != len(hashes):
-        raise ValueError("dates and hashes must have equal length")
-    if not 0 < train_fraction < 1:
-        raise ValueError("train_fraction must be between 0 and 1")
-    unique_dates = sorted({str(date) for date in dates})
-    if len(unique_dates) < 2:
-        raise ValueError("Temporal holdout needs at least two distinct dates")
-    cutoff_index = min(int(len(unique_dates) * train_fraction), len(unique_dates) - 1)
-    cutoff = unique_dates[cutoff_index]
-    train = np.flatnonzero(dates < cutoff)
-    test = np.flatnonzero((dates >= cutoff) & ~np.isin(hashes, hashes[train]))
-    return train, test, cutoff
-
-
-def model_schema(bundle: dict[str, Any]) -> FeatureSchema:
-    """Read a model's feature schema, defaulting legacy bundles to v1."""
-    return parse_schema(bundle.get("feature_schema", "v1"))
-
-
-def iter_records(pattern: str) -> Any:
-    for path in sorted(glob.glob(pattern)):
-        with open(path) as fh:
-            for line in fh:
-                yield json.loads(line)
-
-
-def cmd_train(pattern: str, model_path: str, schema: FeatureSchema = "v2") -> None:
-    from sklearn.ensemble import HistGradientBoostingClassifier
-    from sklearn.impute import SimpleImputer
-    from sklearn.metrics import average_precision_score, roc_auc_score
-
-    # keep the feature vector, not the record: a parsed scan record is an order of
-    # magnitude larger than the row it collapses to.
-    labeled: dict[str, tuple[list[float], int, str]] = {}
-    missing_hash_index = 0
-    for r in iter_records(pattern):
-        if "noise" not in r:
-            continue
-        lab = label_of(r)
-        if lab is None:
-            continue
-        digest = r.get("sha256")
-        if not digest:
-            digest = f"__missing_{missing_hash_index}"
-            missing_hash_index += 1
-        date = Path(r["file"]).parent.name
-        previous = labeled.get(str(digest))
-        if previous is not None and previous[1] != lab:
-            raise ValueError(f"Hash {digest!r} has conflicting labels")
-        if previous is None or date < previous[2]:
-            labeled[str(digest)] = (features_of(r, schema=schema), lab, date)
-
-    rows, labels, row_dates = zip(*labeled.values(), strict=True)
-    X = np.asarray(rows)
-    y = np.asarray(labels)
-    dates = np.asarray(row_dates)
-    hashes = np.asarray(list(labeled))
-    print(
-        f"unique labeled: {len(y)} "
-        f"(pos {int(y.sum())}, neg {int((1 - y).sum())}, features {X.shape[1]}, schema {schema})"
-    )
-
-    def fit(train: np.ndarray) -> tuple[Any, Any]:
-        rows = X[train]
-        imputer = SimpleImputer(strategy="median")
-        classifier = HistGradientBoostingClassifier(
-            random_state=0,
-            max_iter=300,
-            l2_regularization=5.0,
-            early_stopping=False,
-        )
-        classifier.fit(imputer.fit_transform(rows), y[train])
-        return imputer, classifier
-
-    train, test = grouped_stratified_split(y, hashes, test_size=0.3, random_state=0)
-    imp, clf = fit(train)
-    p = clf.predict_proba(imp.transform(X[test]))[:, 1]
-    print(f"SHA-grouped holdout: AUC {roc_auc_score(y[test], p):.4f} | AP {average_precision_score(y[test], p):.4f}")
-
-    temporal_train, temporal_test, cutoff = temporal_holdout_split(dates, hashes)
-    if len(temporal_train) > 100 and len(temporal_test) > 100:
-        imp_t, clf_t = fit(temporal_train)
-        pt = clf_t.predict_proba(imp_t.transform(X[temporal_test]))[:, 1]
-        auc_t = roc_auc_score(y[temporal_test], pt)
-        ap_t = average_precision_score(y[temporal_test], pt)
-        print(f"temporal (<{cutoff}): AUC {auc_t:.4f} | AP {ap_t:.4f}")
-
-    all_indices = np.arange(len(y))
-    imp, clf = fit(all_indices)
-    bundle = {
-        "imputer": imp,
-        "clf": clf,
-        "feature_schema": schema,
-        "feature_names": feature_names(schema),
-    }
-    with open(model_path, "wb") as f:
-        pickle.dump(bundle, f)
-    print(f"model written: {model_path}")
-
-
-def cmd_score(pattern: str, model_path: str, out_path: str) -> None:
-    # the model file is produced locally by `train`; do not load third-party pickles
-    with open(model_path, "rb") as f:
-        bundle = pickle.load(f)  # noqa: S301
-    imp, clf = bundle["imputer"], bundle["clf"]
-    schema = model_schema(bundle)
-    stored_names = bundle.get("feature_names")
-    if stored_names is not None and tuple(stored_names) != feature_names(schema):
-        raise ValueError(f"Model feature names do not match schema {schema}")
-    n = 0
-    batch_rows: list[list[float]] = []
-    batch_meta: list[dict[str, Any]] = []
-
-    def flush(out: Any) -> None:
-        """Score one batch: per-record predict_proba is dominated by call overhead."""
-        nonlocal n
-        if not batch_rows:
-            return
-        scores = clf.predict_proba(imp.transform(np.asarray(batch_rows)))[:, 1]
-        for meta, score in zip(batch_meta, scores, strict=True):
-            out.write(json.dumps({**meta, "ai_score": round(float(score), 4)}) + "\n")
-        n += len(batch_rows)
-        batch_rows.clear()
-        batch_meta.clear()
-        print(f"  {n}", flush=True)
-
-    with open(out_path, "w") as out:
-        for r in iter_records(pattern):
-            if "noise" not in r:
-                continue
-            batch_rows.append(features_of(r, schema=schema))
-            batch_meta.append({"file": r["file"], "sha256": r.get("sha256"), "metadata_label": label_of(r)})
-            if len(batch_rows) >= _SCORE_BATCH:
-                flush(out)
-        flush(out)
-    print(f"scored {n} -> {out_path}")
-
-
-def main() -> None:
-    if len(sys.argv) < 2 or sys.argv[1] not in ("train", "score"):
-        print(__doc__)
-        sys.exit(2)
-    if sys.argv[1] == "train" and len(sys.argv) in (4, 5):
-        schema = parse_schema(sys.argv[4]) if len(sys.argv) == 5 else "v2"
-        cmd_train(sys.argv[2], sys.argv[3], schema)
-    elif sys.argv[1] == "score" and len(sys.argv) == 5:
-        cmd_score(sys.argv[2], sys.argv[3], sys.argv[4])
-    else:
-        print(__doc__)
-        sys.exit(2)
-
-
-if __name__ == "__main__":
-    main()

scripts/detection_timing.py

@@ -0,0 +1,241 @@
+"""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 <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
+
+# The package's OWN tree, not the repository root: from a worktree, an editable
+# install resolves `remove_ai_watermarks` to the MAIN checkout, so a script measuring
+# this tree would silently import a different one.
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+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())

scripts/ladder_headroom.py

@@ -1,7 +1,7 @@
 """How much recall is the coarse scale ladder costing, and what would a denser one cost?
 
 THE FINDING THIS MEASURES
-  `_tophat_score` sweeps three rungs -- (0.8, 1.0, 1.25) -- and the `binary` front-end
+  `_ladder_best` sweeps three rungs -- (0.8, 1.0, 1.25) -- and the `binary` front-end
   sweeps none at all. Measured on stamped marks over controlled backgrounds
   (`scripts/detector_response.py`), the response is a COMB: doubao scores 0.99 exactly at
   each rung and collapses to 0.37-0.48 between them, against a 0.50 gate. So a mark whose
@@ -93,7 +93,10 @@ def wilson(k: int, n: int, z: float = 1.96) -> tuple[float, float]:
 
 
 def score_at_scales(engine: Any, image: np.ndarray, scales: tuple[float, ...]) -> dict[float, float]:
-    """`_tophat_score`'s inner loop, opened up so the ladder is a parameter.
+    """`_ladder_best`'s inner loop, opened up so the ladder is a parameter.
+
+    A DELIBERATE second copy of the sweep: it exists to measure ladders the shipped
+    engine does not have, so it must not be folded back into `_ladder_best`.
 
     Deliberately reaches into the engine (`tophat_response`, `_glyph_silhouette`): a
     measurement script may, product code may not. Kept a faithful copy of the shipped

scripts/metadata_removal_audit.py

@@ -32,7 +32,7 @@ from pathlib import Path
 import click
 import numpy as np
 
-from remove_ai_watermarks.noai.constants import SUPPORTED_FORMATS
+from remove_ai_watermarks._internal.constants import SUPPORTED_FORMATS
 
 log = logging.getLogger(__name__)
 

scripts/real_examples_e2e.py

@@ -13,20 +13,20 @@ WHAT IT COVERS
   metadata   real AI-metadata files -> --check detects, --remove strip-and-verifies clean
   visible    real marked images per mark -> the mark is gone on re-detect, output written
   erase      a real image, each fill backend (cv2 / migan / lama) -> output written
-  invisible  a real SynthID image on MPS at reduced resolution -> a CHANGED image is written
+  invisible  a real SynthID image at reduced resolution -> a CHANGED image is written
   all        a real marked image through the full pipeline -> output written
   batch      a real directory -> every input produces an output
 
   invisible/all run the diffusion model, so they are gated behind --diffusion and run at a
-  small --max-resolution on MPS (the user's "reduced size on MPS" path). Everything else is
-  cv2/numpy and fast.
+  small --max-resolution. Both profiles are CUDA-only, so that section needs an NVIDIA
+  GPU; everything else is cv2/numpy, fast, and runs anywhere.
 
 DATA SAFETY
   Treat input datasets as sensitive and read-only. Output stays in a gitignored temp
   dir. Records example uids and pass/fail, never image content.
 
     uv run python scripts/real_examples_e2e.py                 # fast surface (no diffusion)
-    uv run python scripts/real_examples_e2e.py --diffusion     # + invisible/all on MPS
+    uv run python scripts/real_examples_e2e.py --diffusion     # + invisible/all (needs CUDA)
 """
 
 from __future__ import annotations
@@ -239,12 +239,16 @@ def check_erase(res: Results, tmp: Path) -> None:
 
 
 def check_diffusion(res: Results, tmp: Path, gemini_src: str, openai_src: str) -> None:
-    """The GPU path: invisible + all on MPS at reduced resolution -> a CHANGED image."""
+    """The GPU path: invisible + all at reduced resolution -> a CHANGED image.
+
+    CUDA-only. On a machine without an NVIDIA GPU every row here fails with the
+    library's clean refusal; run this section on a GPU box.
+    """
     import numpy as np
 
     from remove_ai_watermarks.image_io import imread
 
-    print("\ninvisible / all -- real SynthID image on MPS, reduced resolution")
+    print("\ninvisible / all -- real SynthID image, reduced resolution (CUDA required)")
     for label, src in (("invisible/gemini", gemini_src), ("invisible/openai", openai_src)):
         if not src:
             res.add(label, "-", True, "no real positive found (skipped)")
@@ -252,7 +256,7 @@ def check_diffusion(res: Results, tmp: Path, gemini_src: str, openai_src: str) -
         sp = Path(src)
         outp = tmp / f"inv_{sp.stem}.png"
         code, out = run(
-            ["invisible", src, "-o", str(outp), "--device", "mps", "--max-resolution", "512", "--seed", "0"],
+            ["invisible", src, "-o", str(outp), "--max-resolution", "512", "--seed", "0"],
             timeout=1200,
         )
         if not outp.exists():
@@ -276,7 +280,7 @@ def check_diffusion(res: Results, tmp: Path, gemini_src: str, openai_src: str) -
         sp = Path(gemini_src)
         outp = tmp / f"all_{sp.stem}.png"
         code, out = run(
-            ["all", gemini_src, "-o", str(outp), "--device", "mps", "--max-resolution", "512", "--seed", "0"],
+            ["all", gemini_src, "-o", str(outp), "--max-resolution", "512", "--seed", "0"],
             timeout=1200,
         )
         ok = outp.exists() and outp.stat().st_size > 0
@@ -304,7 +308,7 @@ def check_batch(res: Results, tmp: Path) -> None:
 
 def main() -> None:
     ap = argparse.ArgumentParser()
-    ap.add_argument("--diffusion", action="store_true", help="also run invisible/all on MPS (slow)")
+    ap.add_argument("--diffusion", action="store_true", help="also run invisible/all (slow, needs CUDA)")
     ap.add_argument("--gemini", default="")
     ap.add_argument("--openai", default="")
     a = ap.parse_args()
@@ -320,7 +324,7 @@ def main() -> None:
         if a.diffusion:
             check_diffusion(res, tmp, a.gemini, a.openai)
         else:
-            print("\n(diffusion skipped -- pass --diffusion to run invisible/all on MPS)")
+            print("\n(diffusion skipped -- pass --diffusion to run invisible/all)")
     raise SystemExit(res.report())
 
 

scripts/record_parity_audit.py

@@ -0,0 +1,224 @@
+"""Audit the record path against the file path over a whole dataset.
+
+WHY THIS EXISTS
+
+Two seams reach the same provenance verdict:
+
+    identify(path, check_visible=False, check_invisible=False)
+
+    identify_metadata_record(collect_metadata_record(path), path=path)
+
+Their equality is the record's entire contract, and it can break from either side --
+a region the collector stops walking, or a placement the file path learns to read and
+the record does not. ``tests/test_metadata_record.py`` pins it over the tracked
+fixtures; those cover the signal families we already know about. This covers the ones
+we do not: every real placement in a real corpus, which is where all three defects
+found so far actually came from.
+
+The record is round-tripped through ``json.dumps``/``loads`` before it is judged, so
+a value that only survives in memory fails here rather than at a customer.
+
+WHAT IT REPORTS
+
+One JSONL row per image: both verdicts, whether they agree, the record size, and any
+exception from either side. The summary counts disagreements by field and by signal,
+so "the record lost samsung_genai on 13 files" reads directly off the output instead
+of being reconstructed.
+
+Pass ``--baseline`` with an earlier run to also diff against it. That answers the
+other question a detection change raises: which files changed verdict, and are they
+exactly the ones that were meant to.
+
+DATA SAFETY
+
+Read-only over a local dataset. Writes only the given output path, which belongs
+outside the repository. Resumable: rerunning skips files already recorded.
+
+    uv run python scripts/record_parity_audit.py data/spaces/originals .local-eval/parity.jsonl
+    uv run python scripts/record_parity_audit.py <dataset> <out> --baseline .local-eval/previous.jsonl
+"""
+
+from __future__ import annotations
+
+import argparse
+import collections
+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 Iterator
+
+# The package's OWN tree, not the repository root: from a worktree, an editable
+# install resolves `remove_ai_watermarks` to the MAIN checkout, so a script measuring
+# this tree would silently import a different one.
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from remove_ai_watermarks.identify import identify, identify_metadata_record
+from remove_ai_watermarks.metadata_record import collect_metadata_record
+
+log = logging.getLogger(__name__)
+
+SUPPORTED = frozenset({".png", ".jpg", ".jpeg", ".webp", ".heic", ".heif", ".avif"})
+# Every field of the verdict a caller can act on. `path` is excluded: it is extraction
+# context, and the two paths are handed the same one by construction.
+COMPARED = ("is_ai_generated", "platform", "confidence", "ai_source_kind", "ai_from_metadata")
+
+
+def _verdict(report: Any) -> dict[str, Any]:
+    return {
+        **{field: getattr(report, field) for field in COMPARED},
+        "signals": sorted(signal.name for signal in report.signals),
+        "watermarks": sorted(report.watermarks),
+    }
+
+
+def _audit(path: Path) -> dict[str, Any]:
+    row: dict[str, Any] = {"path": str(path)}
+    try:
+        row["bytes"] = path.stat().st_size
+    except OSError as exc:
+        return {**row, "error": f"stat: {exc}"}
+
+    try:
+        started = time.perf_counter()
+        record = json.loads(json.dumps(collect_metadata_record(path)))
+        row["collect_ms"] = (time.perf_counter() - started) * 1000
+        row["record_bytes"] = len(json.dumps(record))
+        row["container"] = record.get("container")
+        via_record = _verdict(identify_metadata_record(record, path=path))
+    except Exception as exc:
+        return {**row, "error": f"record path: {type(exc).__name__}: {exc}"}
+
+    try:
+        via_file = _verdict(identify(path, check_visible=False, check_invisible=False))
+    except Exception as exc:
+        return {**row, "error": f"file path: {type(exc).__name__}: {exc}"}
+
+    row["record"] = via_record
+    row["file"] = via_file
+    row["agree"] = via_record == via_file
+    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(out_path: Path) -> set[str]:
+    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 _summarize(rows: list[dict[str, Any]], baseline: Path | None) -> None:
+    failed = [r for r in rows if "error" in r]
+    usable = [r for r in rows if "error" not in r]
+    disagreed = [r for r in usable if not r["agree"]]
+
+    print(f"\nimages: {len(rows)}   errors: {len(failed)}   compared: {len(usable)}")
+    print(f"record path disagrees with file path: {len(disagreed)}")
+    for row in failed[:10]:
+        print(f"   ERROR {Path(row['path']).name}: {row['error']}")
+
+    fields: collections.Counter[str] = collections.Counter()
+    for row in disagreed:
+        fields.update(field for field in COMPARED if row["record"][field] != row["file"][field])
+        for name in set(row["file"]["signals"]) - set(row["record"]["signals"]):
+            fields[f"signal missing from record: {name}"] += 1
+        for name in set(row["record"]["signals"]) - set(row["file"]["signals"]):
+            fields[f"signal only in record: {name}"] += 1
+    for label, count in fields.most_common():
+        print(f"   {label}: {count}")
+    for row in disagreed[:10]:
+        print(f"   {Path(row['path']).name}\n      record: {row['record']}\n      file:   {row['file']}")
+
+    if baseline is None:
+        return
+    previous = {}
+    with baseline.open(encoding="utf-8") as handle:
+        for line in handle:
+            try:
+                item = json.loads(line)
+            except ValueError:
+                continue
+            if "error" not in item:
+                previous[Path(item["path"]).name] = item
+
+    changed = []
+    for row in usable:
+        was = previous.get(Path(row["path"]).name)
+        if was is None:
+            continue
+        # The WHOLE verdict, not a chosen subset. A first version compared confidence
+        # and signals only and reported "0 changed" for a run whose single intended
+        # correction was a watermark line -- the change it existed to show.
+        before = was.get("file") or {}
+        if before and before != row["file"]:
+            changed.append((row["path"], before, row["file"]))
+    print(f"\nverdicts changed against the baseline: {len(changed)}")
+    moved: collections.Counter[str] = collections.Counter()
+    for _, before, after in changed:
+        for name in set(after["signals"]) - set(before.get("signals") or []):
+            moved[f"gained signal {name}"] += 1
+        for name in set(before.get("signals") or []) - set(after["signals"]):
+            moved[f"LOST signal {name}"] += 1
+        for field in (*COMPARED, "watermarks"):
+            if before.get(field) != after.get(field):
+                moved[f"{field} changed"] += 1
+    for label, count in moved.most_common():
+        print(f"   {label}: {count}")
+    for path, before, after in changed[:10]:
+        print(f"   {Path(path).name}\n      before: {before}\n      after:  {after}")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("dataset", type=Path)
+    parser.add_argument("out", type=Path)
+    parser.add_argument("--baseline", type=Path, default=None, help="an earlier run to diff verdicts against")
+    parser.add_argument("--limit", type=int, default=0)
+    parser.add_argument("--progress-every", type=int, default=2000)
+    args = parser.parse_args()
+
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(message)s")
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    done = _done(args.out)
+    if done:
+        log.info("resuming: %d images already audited", len(done))
+
+    processed = 0
+    started = time.monotonic()
+    with args.out.open("a", encoding="utf-8") as handle:
+        for path in _iter_images(args.dataset):
+            if str(path) in done:
+                continue
+            handle.write(json.dumps(_audit(path), ensure_ascii=False, default=str) + "\n")
+            handle.flush()
+            processed += 1
+            if processed % args.progress_every == 0:
+                log.info("%d images, %.1f/s", processed, processed / (time.monotonic() - started))
+            if args.limit and processed >= args.limit:
+                break
+
+    log.info("audited %d images in %.1f s", processed, time.monotonic() - started)
+    with args.out.open(encoding="utf-8") as handle:
+        rows = [json.loads(line) for line in handle]
+    _summarize(rows, args.baseline)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/smoke_matrix.py

@@ -17,9 +17,10 @@ WHAT IT COVERS AND WHY THAT SHAPE
     work" report); a no-op must be byte-identical; `metadata --remove` must actually
     strip; a JPEG strip must not touch the pixels. Note the pixel-lossless contract is
     the DEFAULT path's -- `--remove-all` deliberately re-encodes (see metadata.py).
-  * The diffusion bodies under `--diffusion`, at `--max-resolution 512` so they fit MPS
-    (~1 min/image on 32 GB unified memory). Not just exit codes: `invisible` must
-    restore the input resolution and must NOT re-stamp SDXL's own open watermark.
+  * The diffusion bodies under `--diffusion`, at a small `--max-resolution`. Both
+    profiles are CUDA-only, so those rows need an NVIDIA GPU and are reported as
+    skips elsewhere. Not just exit codes: `invisible` must restore the input
+    resolution and must NOT re-stamp SDXL's own open watermark.
 
 WHAT IT DOES NOT COVER, DELIBERATELY AND LOUDLY
   * Without `--diffusion`, the model-running bodies are reported as SKIPPED with a
@@ -34,7 +35,7 @@ WHAT IT DOES NOT COVER, DELIBERATELY AND LOUDLY
 
     uv run python scripts/smoke_matrix.py                 # corpus + fixtures
     uv run python scripts/smoke_matrix.py --quick         # fixtures only, no corpus
-    uv run python scripts/smoke_matrix.py --diffusion     # + the SDXL model paths
+    uv run python scripts/smoke_matrix.py --diffusion     # + the model paths (needs CUDA)
 """
 
 from __future__ import annotations
@@ -113,7 +114,7 @@ def main() -> None:
     ap = argparse.ArgumentParser()
     ap.add_argument("--quick", action="store_true", help="fixtures only; skip the corpus rows")
     ap.add_argument(
-        "--diffusion", action="store_true", help="also run the model-running paths (SDXL weights, ~1 min/image)"
+        "--diffusion", action="store_true", help="also run the model-running paths (needs CUDA, ~1 min/image)"
     )
     a = ap.parse_args()
 
@@ -303,7 +304,7 @@ def main() -> None:
         _diffusion_rows(r, tmp, doubao)
     else:
         for name in ("invisible", "all", "batch --mode invisible"):
-            r.skip(f"{name} (model-running body)", "pass --diffusion to exercise it (needs the SDXL weights)")
+            r.skip(f"{name} (model-running body)", "pass --diffusion to exercise it (needs CUDA and the model weights)")
 
     # ---- real-data formats and shapes ---------------------------------------
     if not a.quick:
@@ -354,18 +355,18 @@ def main() -> None:
 def _knob_rows(r: Runner, tmp: Path, img: Path) -> None:
     """Every diffusion knob the matrix never touched.
 
-    Deliberately cheap (`--steps 4`, `--max-resolution 384`): these rows answer "is the
-    knob accepted and does the run complete", NOT "is the output good". Quality per knob
-    needs a per-knob oracle and most of them have none (`--humanize` has no oracle at
-    all), so claiming more here would be dishonest.
+    Deliberately cheap (`--max-resolution 384`): these rows answer "is the knob accepted
+    and does the run complete", NOT "is the output good". Quality per knob needs a
+    per-knob oracle and most of them have none (`--humanize` has no oracle at all), so
+    claiming more here would be dishonest.
     """
-    from remove_ai_watermarks import upscaler
-
-    # --steps 20 is the floor that WORKS, not an arbitrary choice: effective timesteps
-    # are int(steps * strength), so at the default strength 0.15 anything below
-    # --steps 7 rounds to ZERO and the pipeline dies inside torch. The first version of
-    # these rows used --steps 4 and every single one failed with the same reshape error.
-    fast = ["--max-resolution", "384", "--min-resolution", "0", "--steps", "20", "--force", "--seed", "0"]
+    # Both surviving profiles are CUDA-only, pin a fixed model stack and let each stage
+    # own its schedule and CFG. The knobs that used to contradict that (--model, --steps,
+    # --guidance-scale, --device, --auto) are gone from the parser, so the rows below
+    # assert Click itself refuses them. That is the coverage worth having: an option the
+    # CLI accepts and the library refuses several layers down is what this matrix exists
+    # to catch, and the cheapest way to keep it caught is for the option not to exist.
+    fast = ["--max-resolution", "384", "--force", "--seed", "0"]
 
     def run(name: str, extra: list[str], *, tag: str, expect: int | None = 0) -> None:
         r.run(
@@ -375,65 +376,53 @@ def _knob_rows(r: Runner, tmp: Path, img: Path) -> None:
             timeout=2400,
         )
 
-    run("--pipeline sdxl", ["--pipeline", "sdxl"], tag="sdxl")
-    run("--pipeline controlnet", ["--pipeline", "controlnet"], tag="cnet")
-    run("--strength", ["--strength", "0.2"], tag="strength")
-    run("--guidance-scale", ["--guidance-scale", "5.0"], tag="gs")
-    run("--controlnet-scale", ["--controlnet-scale", "0.5"], tag="cns")
-    run("--humanize", ["--humanize", "0.3"], tag="hum")
-    run("--unsharp", ["--unsharp", "0.5"], tag="uns")
-    run("--no-adaptive-polish", ["--no-adaptive-polish"], tag="nap")
-    run("--tile", ["--tile", "--tile-size", "256", "--tile-overlap", "64"], tag="tile")
-    run("--device mps", ["--device", "mps"], tag="mps")
-    run("--upscaler lanczos", ["--upscaler", "lanczos"], tag="lanczos")
-    run("--auto (deprecated no-op)", ["--auto"], tag="auto")
+    # Click rejects a retired profile at parse time (exit 2) rather than remapping it.
+    for retired in ("sdxl", "controlnet", "qwen", "default"):
+        run(f"--pipeline {retired} is rejected", ["--pipeline", retired], tag=f"retired_{retired}", expect=2)
 
-    if upscaler.is_available():
-        run("--upscaler esrgan", ["--upscaler", "esrgan"], tag="esrgan")
-    else:
-        r.skip("--upscaler esrgan", "the `esrgan` extra is not installed")
+    # Retired options: no longer parsed at all (exit 2, "No such option").
+    for args, tag in (
+        (["--steps", "20"], "steps20"),
+        (["--guidance-scale", "5.0"], "gs5"),
+        (["--model", "org/custom"], "model"),
+        (["--device", "cpu"], "devcpu"),
+        (["--auto"], "auto"),
+    ):
+        run(f"{args[0]} is no longer an option", args, tag=tag, expect=2)
 
-    # CPU is correctness-relevant (it is the documented MPS-OOM fallback) but slow, so
-    # it gets the smallest possible run rather than being skipped.
-    r.run(
-        "--device cpu",
-        [
-            "invisible",
-            str(img),
-            "-o",
-            str(tmp / "k_cpu.png"),
-            "--device",
-            "cpu",
-            "--max-resolution",
-            "256",
-            "--min-resolution",
-            "0",
-            "--steps",
-            "20",
-            "--force",
-            "--seed",
-            "0",
-        ],
-        timeout=3600,
-    )
-
-    # qwen is CUDA-class by design (bf16 MMDiT, no MPS fallback). On this host the
-    # honest outcome is a CLEAN failure, not a crash -- assert it does not hang or
-    # dump a traceback at the user.
     try:
         import torch
 
         cuda = bool(torch.cuda.is_available())
     except Exception:
         cuda = False
-    if cuda:
-        run("--pipeline qwen", ["--pipeline", "qwen"], tag="qwen")
-    else:
-        r.skip("--pipeline qwen", "CUDA-class pipeline; no CUDA device on this host")
 
-    # --model and --hf-token are deliberately not exercised: one would download a second
-    # multi-GB checkpoint, the other needs a real credential. Skipped loudly, not passed.
-    r.skip("--model", "would download a second multi-GB checkpoint")
+    if not cuda:
+        # Without CUDA the honest outcome is a CLEAN refusal naming the reason, not a
+        # traceback from inside a half-built pipeline.
+        run("no CUDA fails cleanly", [], tag="nocuda", expect=1)
+        for label in (
+            "--strength",
+            "--controlnet-scale",
+            "--humanize",
+            "--unsharp",
+            "--no-adaptive-polish",
+            "--tile",
+            "--pipeline sdxl-zimage",
+        ):
+            r.skip(label, "accepted-knob rows need a CUDA device")
+        return
+
+    run("--pipeline sdxl-zimage", ["--pipeline", "sdxl-zimage"], tag="sdxlz")
+    run("--strength", ["--strength", "0.2"], tag="strength")
+    run("--controlnet-scale", ["--controlnet-scale", "0.5"], tag="cns")
+    run("--humanize", ["--humanize", "0.3"], tag="hum")
+    run("--unsharp", ["--unsharp", "0.5"], tag="uns")
+    run("--no-adaptive-polish", ["--no-adaptive-polish"], tag="nap")
+    run("--tile", ["--tile", "--tile-size", "256", "--tile-overlap", "64"], tag="tile")
+
+    # --hf-token needs a real credential, so it cannot be exercised meaningfully here.
+    # Skipped loudly rather than silently passed over.
     r.skip("--hf-token", "needs a real credential; cannot be exercised meaningfully here")
 
     # CONTRACT, not just execution: the same seed must reproduce the same pixels.
@@ -497,7 +486,7 @@ def _sdxl_watermark_bits(img: object) -> float:
 
 
 def _diffusion_rows(r: Runner, tmp: Path, doubao: Path) -> None:
-    """Exercise the model-running bodies at a reduced resolution (MPS-friendly).
+    """Exercise the model-running bodies at a reduced resolution (CUDA required).
 
     Bounded with `--max-resolution 512` and a fixed seed: the point is that the paths
     RUN and keep their contracts, not to certify removal strength (that needs the
@@ -519,7 +508,7 @@ def _diffusion_rows(r: Runner, tmp: Path, doubao: Path) -> None:
     # OUTPUT and the row degrades to a skip rather than a false pass if it goes fragile.
     mj = SAMPLES / "mj-1.png"
     inv = tmp / "inv_mj.png"
-    res = r.run("invisible runs (mps, 512px)", ["invisible", str(mj), "-o", str(inv), "--force", *small], timeout=1800)
+    res = r.run("invisible runs (512px)", ["invisible", str(mj), "-o", str(inv), "--force", *small], timeout=1800)
     if res.status == "pass" and inv.exists():
         src_img, out_img = imread(str(mj)), imread(str(inv))
         r.check(
@@ -547,7 +536,7 @@ def _diffusion_rows(r: Runner, tmp: Path, doubao: Path) -> None:
 
     # `all`: every stage must land -- the visible mark AND the metadata both gone.
     allout = tmp / "all_out.png"
-    res = r.run("all runs (mps, 512px)", ["all", str(doubao), "-o", str(allout), *small], timeout=1800)
+    res = r.run("all runs (512px)", ["all", str(doubao), "-o", str(allout), *small], timeout=1800)
     if res.status == "pass" and allout.exists():
         rep = json.loads(_capture(["identify", str(allout), "--json"]))
         r.check(
@@ -566,7 +555,7 @@ def _diffusion_rows(r: Runner, tmp: Path, doubao: Path) -> None:
         shutil.copy(f, bd / f.name)
     bout = tmp / "batch_inv_out"
     res = r.run(
-        "batch --mode invisible runs (mps, 512px)",
+        "batch --mode invisible runs (512px)",
         ["batch", str(bd), "--mode", "invisible", "-o", str(bout), *small],
         expect_exit=None,
         timeout=3600,
@@ -578,44 +567,12 @@ def _diffusion_rows(r: Runner, tmp: Path, doubao: Path) -> None:
     # `batch --mode all` -- the only --mode value the matrix never ran.
     aout = tmp / "batch_all_out"
     r.run(
-        "batch --mode all runs (mps, 512px)",
+        "batch --mode all runs (512px)",
         ["batch", str(bd), "--mode", "all", "-o", str(aout), *small],
         expect_exit=None,
         timeout=3600,
     )
 
-    # The AI-enhanced composite path: regenerate ONLY a region and feather it back,
-    # leaving everything outside the box pixel-exact. Library-level -- the CLI has no
-    # flag for it, so it would otherwise never be exercised on real data.
-    try:
-        import numpy as np
-
-        from remove_ai_watermarks.image_io import imread
-        from remove_ai_watermarks.noai.watermark_remover import WatermarkRemover
-
-        src = imread(str(mj))
-        h, w = src.shape[:2]
-        box = (w // 4, h // 4, w // 4, h // 4)
-        rem = WatermarkRemover(pipeline="controlnet")
-        rout = tmp / "region_composite.png"
-        rem.remove_watermark(mj, rout, strength=0.15, num_inference_steps=20, seed=0, region=box)
-        got = imread(str(rout))
-        if got is None or got.shape != src.shape:
-            r.check("region composite keeps the frame outside the box", False, "shape changed or unreadable")
-        else:
-            mask = np.ones(src.shape[:2], dtype=bool)
-            x, y, bw, bh = box
-            # Outside the box PLUS the feather margin must be untouched.
-            pad = 96
-            mask[max(0, y - pad) : y + bh + pad, max(0, x - pad) : x + bw + pad] = False
-            r.check(
-                "region composite keeps the frame outside the box",
-                bool(np.array_equal(src[mask], got[mask])),
-                "pixels changed outside the regenerated region",
-            )
-    except Exception as e:
-        r.skip("region composite (remove_watermark(region=...))", f"{type(e).__name__}: {e}"[:120])
-
 
 if __name__ == "__main__":
     main()

scripts/sync_conda_recipe.py

@@ -0,0 +1,53 @@
+"""Update the conda recipe to a published package version and sdist hash."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import re
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+_VERSION_LINE = re.compile(r'^  version: "[^"]+"$', re.MULTILINE)
+_SHA256_LINE = re.compile(r"^  sha256: [0-9a-f]{64}$", re.MULTILINE)
+
+
+def update_recipe(text: str, *, version: str, sha256: str) -> str:
+    """Return recipe text with exactly one context version and source hash updated."""
+    if not version or any(char.isspace() for char in version):
+        raise ValueError("version must be a non-empty value without whitespace")
+    if re.fullmatch(r"[0-9a-f]{64}", sha256) is None:
+        raise ValueError("sha256 must be 64 lowercase hexadecimal characters")
+
+    updated, version_count = _VERSION_LINE.subn(f'  version: "{version}"', text)
+    updated, sha_count = _SHA256_LINE.subn(f"  sha256: {sha256}", updated)
+    if version_count != 1 or sha_count != 1:
+        raise ValueError(
+            "expected exactly one context version and one source sha256 "
+            f"(found version={version_count}, sha256={sha_count})"
+        )
+    return updated
+
+
+def main() -> None:
+    """Update the selected recipe in place."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--version", required=True)
+    parser.add_argument("--sha256", required=True)
+    parser.add_argument(
+        "--recipe",
+        type=Path,
+        default=Path("packaging/conda/recipe.yaml"),
+    )
+    args = parser.parse_args()
+
+    original = args.recipe.read_text()
+    updated = update_recipe(original, version=args.version, sha256=args.sha256)
+    args.recipe.write_text(updated)
+    log.info("Updated %s to version %s", args.recipe, args.version)
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+    main()

scripts/synthid_corpus.py

@@ -29,7 +29,7 @@ import click
 from _plain_console import Console, Table
 from PIL import Image
 
-from remove_ai_watermarks.noai.c2pa import extract_c2pa_info
+from remove_ai_watermarks._internal.c2pa import extract_c2pa_info
 
 log = logging.getLogger(__name__)
 console = Console()

scripts/vendor_cohort_harvest.py

@@ -62,17 +62,10 @@ OUT = REPO / ".local-eval" / "vendor-cohorts.jsonl"
 FIRED = REPO / ".local-eval" / "visible-positives.jsonl"
 SHEET_DIR = REPO / ".local-eval" / "vendor-cohort-sheets"
 
-# A producer code is `001` + `1` + USCC(18) + a 5-digit app/product suffix, so two
-# codes sharing the USCC are the same legal entity registering different products.
-# Slicing is defensive: anything not matching the layout is grouped by its raw value.
-_USCC_START, _USCC_END = 4, 22
-
-
-def uscc_of(code: str) -> str:
-    """The 18-char Unified Social Credit Code embedded in a TC260 producer code."""
-    if len(code) >= _USCC_END and code[:3] == "001":
-        return code[_USCC_START:_USCC_END]
-    return code
+# `uscc_of` moved into the library (`metadata.uscc_of`) when the USCC -> vendor table
+# started driving `api.visible_provenance`; this script must group by the same rule the
+# product uses, so it imports rather than reimplements it.
+from remove_ai_watermarks.metadata import uscc_of  # noqa: E402
 
 
 def _one(path_str: str) -> dict[str, Any] | None:

scripts/vendor_mark_calibrate.py

@@ -97,7 +97,7 @@ def _score(args: ScoreArgs) -> dict[str, Any] | None:
     eng = TextMarkEngine(build_config(asset, name, basis, overrides))
     loc = eng.locate(img)
     try:
-        score, box = eng._tophat_best(img, loc)
+        score, box = eng._ladder_best(img, loc)
     except Exception:
         return None
     return {"path": path_str, "score": round(float(score), 4), "box": box}
@@ -225,7 +225,7 @@ def sheets(pos: list[dict[str, Any]], name: str, per_sheet: int = 24) -> None:
 # genuinely unknown, which is the one case a dense ladder earns its cost -- but it also
 # hands clean corners extra chances to match, so it must never set a gate.
 _FIT_SCALES = tuple(round(0.4 * (1.03**i), 4) for i in range(80))  # 0.40 .. ~4.1
-# The ladder the product actually ships (`_text_mark_engine._tophat_best`).
+# The ladder the product actually ships (`_text_mark_engine._ladder_best`).
 _SHIPPED_LADDER = (0.8, 1.0, 1.25)
 
 
@@ -460,7 +460,7 @@ def _cross_score(args: tuple[str, Any, Any]) -> dict[str, Any] | None:
         eng = TextMarkEngine(cfg)
         loc = eng.locate(img)
         try:
-            score, _ = eng._tophat_best(img, loc)
+            score, _ = eng._ladder_best(img, loc)
         except Exception:
             return None
         out[key] = round(float(score), 4)

scripts/video_fidelity_probe.py

@@ -0,0 +1,216 @@
+"""End-to-end fidelity of a DELIVERED video against its source.
+
+The engine's own ``psnr_db`` is measured against the already-resized frame and
+before the encoder, so it reports the VAE round trip plus latent noise and
+nothing else. The downscale, the frame decimation and the H.264 encode -- the
+three steps that actually cost the user picture -- are invisible to it, and no
+metric computed inside the streaming loop can see them, because the candidate
+frame is captured before it is written to the encoder pipe.
+
+This script measures what the engine cannot: it decodes the delivered file after
+muxing, upscales each frame back to the source geometry, and scores it against
+the untouched source frame it came from. That reference is deliberately harsh -
+detail the downscale destroyed is unrecoverable, so the absolute number is
+dominated by content the pipeline never had a chance to keep. Use it to RANK
+configurations against a shared reference, not to attribute loss to one stage.
+
+It streams, for the same reason the engine does: holding a 1080p clip plus its
+upscaled candidate and flow maps in memory runs to gigabytes and grows with clip
+length. Peak here is a handful of frames regardless of duration.
+
+It is a research tool, not part of the shipped path, and it measures fidelity
+only. Nothing here is a watermark verdict: only a provider-oracle row is.
+
+    uv run python scripts/video_fidelity_probe.py source.mp4 out-512.mp4 out-768.mp4
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import math
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import click
+import cv2
+import numpy as np
+
+from remove_ai_watermarks.video_invisible import _iter_sampled_frames, _probe_video
+from remove_ai_watermarks.video_temporal import _backward_map, _motion_residual
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from invisible_quality_audit import _ssim  # reuse, do not reimplement a fourth SSIM
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from numpy.typing import NDArray
+
+log = logging.getLogger(__name__)
+
+
+def _delivered_geometry(path: Path) -> tuple[int, int, float]:
+    capture = cv2.VideoCapture(str(path))
+    if not capture.isOpened():
+        raise click.ClickException(f"Could not open video: {path}")
+    try:
+        width = round(capture.get(cv2.CAP_PROP_FRAME_WIDTH))
+        height = round(capture.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        fps = float(capture.get(cv2.CAP_PROP_FPS))
+    finally:
+        capture.release()
+    if width <= 0 or height <= 0 or fps <= 0.0:
+        raise click.ClickException(f"Video has no usable geometry or frame rate: {path}")
+    return width, height, fps
+
+
+def _iter_frames(path: Path) -> Iterator[NDArray[Any]]:
+    capture = cv2.VideoCapture(str(path))
+    if not capture.isOpened():
+        raise click.ClickException(f"Could not open video: {path}")
+    try:
+        while True:
+            ok, frame = capture.read()
+            if not ok:
+                return
+            yield frame
+    finally:
+        capture.release()
+
+
+def _measure(
+    source: Path,
+    delivered: Path,
+    *,
+    source_geometry: tuple[int, int, float],
+    duration: float | None,
+) -> dict[str, Any]:
+    source_width, source_height, source_fps = source_geometry
+    width, height, fps = _delivered_geometry(delivered)
+
+    # Drive the source through the engine's own sampler at the source's geometry,
+    # so the frame the probe compares against is the frame the engine regenerated.
+    # Importing the rule is what keeps the pairing correct: a count check cannot
+    # catch a selection rule that reorders frames without changing how many.
+    reference_frames = _iter_sampled_frames(
+        source,
+        source_fps=source_fps,
+        duration=duration,
+        effective_fps=fps,
+        size=(source_width, source_height),
+    )
+
+    squared_error = 0.0
+    pixel_count = 0
+    ssim_scores: list[float] = []
+    temporal_baseline = 0.0
+    temporal_candidate = 0.0
+    previous_gray: NDArray[Any] | None = None
+    previous_reference_f32: NDArray[Any] | None = None
+    previous_candidate_f32: NDArray[Any] | None = None
+    frame_count = 0
+    needs_upscale = (width, height) != (source_width, source_height)
+
+    reference_iter = iter(reference_frames)
+    delivered_iter = _iter_frames(delivered)
+    while True:
+        reference = next(reference_iter, None)
+        delivered_frame = next(delivered_iter, None)
+        if reference is None and delivered_frame is None:
+            break
+        if reference is None or delivered_frame is None:
+            raise click.ClickException(
+                f"{delivered.name} and the sampled source ran out at different points after "
+                f"{frame_count} frames. Pass --duration to match the prefix this output was "
+                f"produced from, or check that it came from {source.name}."
+            )
+        candidate = (
+            cv2.resize(delivered_frame, (source_width, source_height), interpolation=cv2.INTER_LANCZOS4)
+            if needs_upscale
+            else delivered_frame
+        )
+        reference_f32 = reference.astype(np.float32)
+        candidate_f32 = candidate.astype(np.float32)
+        difference = reference_f32 - candidate_f32
+        squared_error += float(np.sum(difference * difference, dtype=np.float64))
+        pixel_count += reference.size
+        ssim_scores.append(
+            _ssim(cv2.cvtColor(reference, cv2.COLOR_BGR2GRAY), cv2.cvtColor(candidate, cv2.COLOR_BGR2GRAY))
+        )
+
+        current_gray = cv2.cvtColor(reference, cv2.COLOR_BGR2GRAY)
+        if previous_gray is not None and previous_reference_f32 is not None and previous_candidate_f32 is not None:
+            frame_maps = _backward_map(current_gray, previous_gray)
+            temporal_baseline += _motion_residual(reference_f32, previous_reference_f32, frame_maps)
+            temporal_candidate += _motion_residual(candidate_f32, previous_candidate_f32, frame_maps)
+        previous_gray = current_gray
+        previous_reference_f32 = reference_f32
+        previous_candidate_f32 = candidate_f32
+        frame_count += 1
+
+    if frame_count < 2:
+        raise click.ClickException(f"{delivered.name} paired fewer than two frames against {source.name}")
+
+    mse = squared_error / pixel_count
+    size_bytes = delivered.stat().st_size
+    return {
+        "file": delivered.name,
+        "source": source.name,
+        "source_width": source_width,
+        "source_height": source_height,
+        "source_fps": round(source_fps, 4),
+        "width": width,
+        "height": height,
+        "fps": round(fps, 4),
+        "frames": frame_count,
+        "pixel_ratio": round((width * height) / (source_width * source_height), 4),
+        "source_psnr_db": math.inf if mse == 0.0 else round(20.0 * math.log10(255.0 / math.sqrt(mse)), 4),
+        "source_ssim": round(float(np.mean(ssim_scores)), 4),
+        "temporal_residual_ratio": round(temporal_candidate / max(temporal_baseline, 1e-6), 4),
+        "size_bytes": size_bytes,
+        # The mux copies the source audio track verbatim, so this is a container
+        # bitrate. It still ranks candidates at fixed crf; it is not a video bitrate.
+        "file_bitrate_kbps": round(size_bytes * 8.0 / (frame_count / fps) / 1000.0, 1),
+    }
+
+
+@click.command()
+@click.argument("source", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.argument("delivered", nargs=-1, required=True, type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option(
+    "--duration",
+    type=click.FloatRange(min=0.1),
+    default=None,
+    help="Score only the first N seconds of the source, matching a trimmed sweep candidate.",
+)
+@click.option("--json-out", type=click.Path(dir_okay=False, path_type=Path), help="Also write the rows as JSON.")
+def main(source: Path, delivered: tuple[Path, ...], duration: float | None, json_out: Path | None) -> None:
+    """Score each DELIVERED file against SOURCE end to end."""
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    source_geometry = _probe_video(source)
+    log.info("Source %s: %dx%d at %.4f fps", source.name, *source_geometry)
+
+    rows = [_measure(source, path, source_geometry=source_geometry, duration=duration) for path in delivered]
+    for row in rows:
+        log.info(
+            "%s: %dx%d at %s fps, %.1f%% of source pixels, PSNR %s dB, SSIM %s, temporal %s, %s kbps",
+            row["file"],
+            row["width"],
+            row["height"],
+            row["fps"],
+            row["pixel_ratio"] * 100.0,
+            row["source_psnr_db"],
+            row["source_ssim"],
+            row["temporal_residual_ratio"],
+            row["file_bitrate_kbps"],
+        )
+    if json_out is not None:
+        json_out.write_text(json.dumps(rows, indent=2), encoding="utf-8")
+        log.info("Wrote %s", json_out)
+
+
+if __name__ == "__main__":
+    main()

scripts/video_synthid_sweep.py

@@ -0,0 +1,243 @@
+"""Build oracle-gated video regeneration candidates for SynthID research.
+
+This is a research harness, not a shipped removal command. Google does not
+publish a local video SynthID decoder, so the script cannot label a candidate as
+clean. It produces:
+
+* a re-encode control with the same duration, frame rate, dimensions, and codec;
+* one VAE-regenerated video per requested latent-noise level;
+* paired fidelity and temporal-residual measurements;
+* a CSV column for the external Gemini SynthID verdict.
+
+The control is load-bearing. If it reads clean, the experiment is invalid:
+resize, frame-rate conversion, or H.264 compression already silenced the oracle,
+so a VAE candidate cannot be credited with removal.
+
+The regeneration attack follows the general encode, perturb, reconstruct family
+from WatermarkAttacker (NeurIPS 2024). A single spatial latent-noise sample is
+shared by every frame. Independent per-frame noise creates avoidable flicker and
+does not test the video-specific question.
+
+Run with the project's GPU extra:
+
+    uv run --extra gpu python scripts/video_synthid_sweep.py input.mp4 -o out/
+
+Then upload ``control.mp4`` and each candidate in separate Gemini chats, invoke
+the built-in SynthID verifier (``@synthid``), and use the question printed by
+the script. Do not follow the verdict with an adversarial prompt asking the chat
+model to reinterpret the detector: that switches back to ordinary reasoning.
+Only a control-positive, candidate-negative pair from the built-in verifier is
+removal evidence.
+"""
+
+from __future__ import annotations
+
+import csv
+import hashlib
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import click
+import numpy as np
+
+from remove_ai_watermarks.video_invisible import (
+    _decode_frame_latents,
+    _encode_frame_latents,
+    _fit_size,
+    _probe_video,
+    _shared_latent_noise,
+    build_temporal_reference,
+    encode_video_frames,
+    load_video_vae_runtime,
+    paired_psnr,
+    read_sampled_frames,
+    temporal_residual_ratio,
+)
+from remove_ai_watermarks.video_synthid import (
+    DEFAULT_VIDEO_SYNTHID_FPS,
+    DEFAULT_VIDEO_SYNTHID_LONG_SIDE,
+    DEFAULT_VIDEO_SYNTHID_VAE,
+    VIDEO_SYNTHID_LATENT_MULTIPLE,
+    VIDEO_SYNTHID_VERIFICATION_PROMPT,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+log = logging.getLogger(__name__)
+
+
+def _parse_noise_levels(values: str) -> tuple[float, ...]:
+    levels = tuple(float(value.strip()) for value in values.split(",") if value.strip())
+    if not levels:
+        raise click.BadParameter("At least one noise level is required")
+    if any(not 0.0 <= value <= 1.0 for value in levels):
+        raise click.BadParameter("Noise levels must be between 0 and 1")
+    return levels
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _write_manifest(output_dir: Path, rows: Sequence[dict[str, str]]) -> Path:
+    path = output_dir / "sweep.csv"
+    # Mirrors the tracked manifest's run-configuration fields (data/README.md) so a
+    # row carries into data/evaluations/video-synthid-oracle.csv without hand
+    # reconstruction. The two 2026-07-31 rows show the cost of not doing this: their
+    # geometry was never recorded and cannot be recovered from the row.
+    fieldnames = [
+        "variant",
+        "source_sha256",
+        "source_width",
+        "source_height",
+        "source_fps",
+        "duration_seconds",
+        "vae",
+        "noise_std",
+        "long_side",
+        "fps",
+        "seed",
+        "psnr_db",
+        "temporal_residual_ratio",
+        "file",
+        "sha256",
+        "synthid_oracle",
+    ]
+    with path.open("w", newline="", encoding="utf-8") as stream:
+        writer = csv.DictWriter(stream, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(rows)
+    return path
+
+
+@click.command()
+@click.argument("source", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option("-o", "--output-dir", required=True, type=click.Path(file_okay=False, path_type=Path))
+@click.option("--noise-levels", default="0,0.05,0.1,0.15", show_default=True)
+@click.option("--duration", type=click.FloatRange(min=0.1), default=2.0, show_default=True)
+@click.option("--fps", type=click.FloatRange(min=1.0), default=DEFAULT_VIDEO_SYNTHID_FPS, show_default=True)
+@click.option(
+    "--long-side",
+    type=click.IntRange(min=VIDEO_SYNTHID_LATENT_MULTIPLE),
+    default=DEFAULT_VIDEO_SYNTHID_LONG_SIDE,
+    show_default=True,
+)
+@click.option("--batch-size", type=click.IntRange(min=1), default=4, show_default=True)
+@click.option("--seed", type=int, default=0, show_default=True)
+@click.option("--model", default=DEFAULT_VIDEO_SYNTHID_VAE, show_default=True)
+@click.option("--device", type=click.Choice(["auto", "cuda", "mps", "cpu"]), default="auto", show_default=True)
+def main(
+    source: Path,
+    output_dir: Path,
+    noise_levels: str,
+    duration: float,
+    fps: float,
+    long_side: int,
+    batch_size: int,
+    seed: int,
+    model: str,
+    device: str,
+) -> None:
+    """Generate VAE video candidates from the prefix of SOURCE."""
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    levels = _parse_noise_levels(noise_levels)
+    width, height, source_fps = _probe_video(source)
+    size = _fit_size(width, height, long_side)
+    frames, effective_fps = read_sampled_frames(source, duration=duration, output_fps=fps, size=size)
+    run = {
+        "source_sha256": _sha256(source),
+        "source_width": str(width),
+        "source_height": str(height),
+        "source_fps": f"{source_fps:.4f}",
+        "duration_seconds": f"{duration:.4f}",
+        "vae": model,
+        "long_side": str(long_side),
+        "fps": f"{effective_fps:.4f}",
+        "seed": str(seed),
+    }
+    output_dir.mkdir(parents=True, exist_ok=True)
+    control_path = output_dir / "control.mp4"
+    encode_video_frames(frames, source, control_path, fps=effective_fps)
+    rows: list[dict[str, str]] = [
+        {
+            **run,
+            "variant": "control",
+            "noise_std": "",
+            "psnr_db": "inf",
+            "temporal_residual_ratio": "1",
+            "file": control_path.name,
+            "sha256": _sha256(control_path),
+            "synthid_oracle": "",
+        }
+    ]
+
+    # Load through the engine's own loader rather than repeating it here: the
+    # scaling-factor gate lives there, and the harness that produces the certified
+    # rows is the last place that should be exempt from it.
+    runtime = load_video_vae_runtime(model=model, device=device)
+    vae, resolved_device = runtime.vae, runtime.resolved_device
+
+    log.info("Encoding source frames")
+    latent_batches = _encode_frame_latents(
+        frames,
+        vae=vae,
+        device=resolved_device,
+        batch_size=batch_size,
+        scaling_factor=runtime.scaling_factor,
+    )
+    first_latents = latent_batches[0]
+    shared_noise = _shared_latent_noise(
+        first_latents.shape[1:],
+        seed=seed,
+        device=resolved_device,
+        dtype=first_latents.dtype,
+    )
+    reference_stack = np.stack(frames)
+    temporal_maps, temporal_baseline = build_temporal_reference(frames)
+    for level in levels:
+        log.info("Decoding latent noise %.4f", level)
+        regenerated = _decode_frame_latents(
+            latent_batches,
+            vae=vae,
+            noise_std=level,
+            shared_noise=shared_noise,
+            scaling_factor=runtime.scaling_factor,
+        )
+        output_path = output_dir / f"vae-noise-{level:.4f}.mp4"
+        encode_video_frames(
+            regenerated,
+            source,
+            output_path,
+            fps=effective_fps,
+        )
+        psnr = paired_psnr(reference_stack, np.stack(regenerated))
+        temporal_ratio = temporal_residual_ratio(regenerated, temporal_maps, temporal_baseline)
+        rows.append(
+            {
+                **run,
+                "variant": "vae",
+                "noise_std": f"{level:.4f}",
+                "psnr_db": f"{psnr:.4f}",
+                "temporal_residual_ratio": f"{temporal_ratio:.4f}",
+                "file": output_path.name,
+                "sha256": _sha256(output_path),
+                "synthid_oracle": "",
+            }
+        )
+
+    manifest = _write_manifest(output_dir, rows)
+    log.info("Wrote %s", manifest)
+    log.info(
+        "Verify control.mp4 first with Gemini's built-in SynthID verifier and this question: %s",
+        VIDEO_SYNTHID_VERIFICATION_PROMPT,
+    )
+
+
+if __name__ == "__main__":
+    main()

scripts/visible_positives.py

@@ -38,7 +38,7 @@ sys.path.insert(0, str(Path(__file__).parent.parent))
 
 # The package's own format set. An inlined copy here silently skipped .heif, which
 # CLAUDE.md documents as supported.
-from remove_ai_watermarks.noai.constants import SUPPORTED_FORMATS as _EXTS
+from remove_ai_watermarks._internal.constants import SUPPORTED_FORMATS as _EXTS
 
 REPO = Path(__file__).resolve().parents[1]
 CORPUS = REPO / ".local-eval" / "originals"

src/remove_ai_watermarks/__init__.py

@@ -6,6 +6,13 @@ High-level API (lazy, so ``import remove_ai_watermarks`` stays cheap)::
     raiw.remove_visible("in.png", "out.png")            # clean a file (provenance auto)
     result, removed = raiw.remove_visible(bgr_array)    # array -> array
     raiw.visible_provenance("in.png")                   # -> frozenset of confirmed vendors
+    raiw.identify_video("in.mp4")                       # -> VideoProvenanceReport
+    raiw.inspect_video_metadata("in.mp4")               # -> VideoMetadataReport
+    raiw.remove_video_all("in.mp4", "out.mp4")          # visible + verified metadata
+    raiw.remove_video_batch("videos", "videos_clean")   # complete per-file results
+    raiw.remove_video_metadata("in.mp4", "out.mp4")     # verified metadata strip
+    raiw.remove_video_invisible("in.mp4", "out.mp4")    # oracle-certified SynthID removal
+    raiw.remove_video_visible("in.mp4", "out.mp4")      # stable visible video-mark removal
 
 For a provenance verdict use the ``identify`` submodule::
 
@@ -25,19 +32,75 @@ _os.environ.setdefault("TRANSFORMERS_VERBOSITY", "error")
 _warnings.filterwarnings("ignore", message=r".*ImageProcessorFast.*")
 
 
-__version__ = "0.20.0"
+__version__ = "0.26.1"
 
-__all__ = ["__version__", "remove_visible", "visible_provenance"]
+__all__ = [
+    "BatchSummary",
+    "InvisibleOptions",
+    "MetadataStripIncomplete",
+    "RemoveAllResult",
+    "__version__",
+    "identify_video",
+    "inspect_video_metadata",
+    "remove_all",
+    "remove_batch",
+    "remove_video_all",
+    "remove_video_batch",
+    "remove_video_invisible",
+    "remove_video_metadata",
+    "remove_video_visible",
+    "remove_visible",
+    "visible_provenance",
+]
 
 if TYPE_CHECKING:
-    from remove_ai_watermarks.api import remove_visible, visible_provenance
+    from remove_ai_watermarks.api import (
+        BatchSummary,
+        InvisibleOptions,
+        MetadataStripIncomplete,
+        RemoveAllResult,
+        remove_all,
+        remove_batch,
+        remove_visible,
+        visible_provenance,
+    )
+    from remove_ai_watermarks.video import (
+        identify_video,
+        inspect_video_metadata,
+        remove_video_all,
+        remove_video_batch,
+        remove_video_invisible,
+        remove_video_metadata,
+        remove_video_visible,
+    )
 
 
 def __getattr__(name: str) -> object:
     """Lazily resolve the high-level API (PEP 562), so the heavy imports (cv2, the
     metadata/identify stack) load only when a caller actually reaches for them."""
-    if name in ("remove_visible", "visible_provenance"):
+    if name in (
+        "BatchSummary",
+        "InvisibleOptions",
+        "MetadataStripIncomplete",
+        "RemoveAllResult",
+        "remove_all",
+        "remove_batch",
+        "remove_visible",
+        "visible_provenance",
+    ):
         from remove_ai_watermarks import api
 
         return getattr(api, name)
+    if name in (
+        "identify_video",
+        "inspect_video_metadata",
+        "remove_video_all",
+        "remove_video_batch",
+        "remove_video_invisible",
+        "remove_video_metadata",
+        "remove_video_visible",
+    ):
+        from remove_ai_watermarks import video
+
+        return getattr(video, name)
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/remove_ai_watermarks/_internal/__init__.py

@@ -0,0 +1,15 @@
+"""Private namespace for metadata parsing and regeneration internals.
+
+Deliberately empty. It carried a PEP 562 ``__getattr__`` re-exporting
+``WatermarkRemover`` and ``remove_ai_metadata`` as a "compatibility namespace",
+but nothing ever reached for either through this package -- every caller imports
+the submodule directly. The laziness it defended is real and still enforced, just
+elsewhere: importing a light submodule (``_internal.c2pa`` / ``_internal.constants``
+from ``identify``) must not pull ``watermark_remover``, which imports torch at
+module top. That property comes from those direct submodule imports, not from a
+shim here; a re-export in this file would be the one thing that could break it.
+
+Keep this module free of imports. ``import remove_ai_watermarks.identify`` stays
+around 36 MB even in a full install where torch is present; routing anything heavy
+through here inflated it to roughly 420 MB and risked OOM on a 512 MB host.
+"""

src/remove_ai_watermarks/_internal/c2pa.py

@@ -0,0 +1,427 @@
+"""C2PA inspection through the official reader with a bounded PNG fallback."""
+
+from __future__ import annotations
+
+import contextlib
+import functools
+import json
+import logging
+import re
+import struct
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+
+from remove_ai_watermarks._internal.constants import (
+    C2PA_ACTIONS,
+    C2PA_AI_TOOLS,
+    C2PA_AI_VENDORS,
+    C2PA_CHUNK_TYPE,
+    C2PA_ISSUERS,
+    C2PA_SIGNATURES,
+    C2PA_SOFT_BINDINGS,
+    PNG_SIGNATURE,
+)
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from typing import BinaryIO
+
+_C2paReader: Any = None
+_C2paError: Any = None
+with contextlib.suppress(Exception):
+    from c2pa import C2paError as _C2paError  # pyright: ignore[reportMissingTypeStubs]
+    from c2pa import Reader as _C2paReader  # pyright: ignore[reportMissingTypeStubs]
+
+_C2PA_READER_AVAILABLE = _C2paReader is not None
+_PNG_HEADER = struct.Struct(">I4s")
+
+
+@dataclass(frozen=True)
+class _PngChunk:
+    payload: bytes
+    serialized: bytes
+
+
+def reader_available() -> bool:
+    """Return whether the official C2PA reader loaded successfully."""
+    return _C2PA_READER_AVAILABLE
+
+
+def _manifest_json_uncached(path: str) -> str | None:
+    """The manifest store as JSON, or None when this file has no readable manifest.
+
+    Two outcomes are routine and stay at debug: a file with no manifest (``try_create``
+    returns None) and a container the reader does not support. ANY other failure is
+    logged at warning, because the caller cannot tell the difference from the return
+    value and the consequence is severe: the verdict silently falls back to the raw
+    byte scan and can lose a high-confidence signal. The log line preserves the
+    diagnostic context needed to investigate an intermittent reader failure.
+    """
+    try:
+        reader = _C2paReader.try_create(path)
+    except _C2paError.NotSupported as error:
+        logger.debug("C2PA reader does not support %s: %s", path, error)
+        return None
+    except Exception as error:
+        logger.warning("C2PA reader failed to open %s: %s: %s", path, type(error).__name__, error)
+        return None
+    if reader is None:
+        return None
+    try:
+        with reader:
+            return cast("str", reader.json())
+    except Exception as error:
+        # The reader opened the file, so a manifest is there; failing to serialize it
+        # is never routine.
+        logger.warning("C2PA reader could not serialize %s: %s: %s", path, type(error).__name__, error)
+        return None
+
+
+@functools.lru_cache(maxsize=8)
+def _manifest_json_cached(path: str, _mtime_ns: int) -> str | None:
+    return _manifest_json_uncached(path)
+
+
+def read_manifest_store_json(image_path: Path) -> str | None:
+    """Read the complete manifest-store JSON, caching it until the file changes."""
+    if not reader_available():
+        return None
+    path = str(image_path)
+    try:
+        return _manifest_json_cached(path, image_path.stat().st_mtime_ns)
+    except OSError:
+        return _manifest_json_uncached(path)
+
+
+def _find_c2pa_chunk(path: Path) -> _PngChunk | None:
+    """Return the first recognizable C2PA chunk without loading the whole PNG."""
+    try:
+        stream = path.open("rb")
+    except OSError:
+        return None
+    with stream:
+        if stream.read(len(PNG_SIGNATURE)) != PNG_SIGNATURE:
+            return None
+        file_size = stream.seek(0, 2)
+        stream.seek(len(PNG_SIGNATURE))
+        while True:
+            header = stream.read(_PNG_HEADER.size)
+            if len(header) != _PNG_HEADER.size:
+                return None
+            length, kind = _PNG_HEADER.unpack(header)
+            if length + 4 > file_size - stream.tell():
+                return None
+            if kind == C2PA_CHUNK_TYPE:
+                payload = stream.read(length)
+                crc = stream.read(4)
+                if _looks_like_c2pa(payload):
+                    return _PngChunk(payload, header + payload + crc)
+            else:
+                stream.seek(length + 4, 1)
+            if kind == b"IEND":
+                return None
+
+
+def _is_well_formed_png(path: Path) -> bool:
+    """Validate PNG chunk bounds with seeks rather than payload allocations."""
+    try:
+        stream = path.open("rb")
+    except OSError:
+        return False
+    with stream:
+        if stream.read(len(PNG_SIGNATURE)) != PNG_SIGNATURE:
+            return False
+        file_size = stream.seek(0, 2)
+        stream.seek(len(PNG_SIGNATURE))
+        while True:
+            header = stream.read(_PNG_HEADER.size)
+            if len(header) != _PNG_HEADER.size:
+                return False
+            length, kind = _PNG_HEADER.unpack(header)
+            if length + 4 > file_size - stream.tell():
+                return False
+            stream.seek(length + 4, 1)
+            if kind == b"IEND":
+                return True
+
+
+def _copy_bytes(source: BinaryIO, target: BinaryIO, byte_count: int) -> None:
+    """Copy exactly one bounded chunk without allocating its complete payload."""
+    remaining = byte_count
+    while remaining:
+        block = source.read(min(remaining, 1024 * 1024))
+        if not block:
+            raise OSError("PNG changed while it was being copied")
+        target.write(block)
+        remaining -= len(block)
+
+
+def _looks_like_c2pa(payload: bytes) -> bool:
+    lowered = payload.lower()
+    return any(signature in payload for signature in C2PA_SIGNATURES) or b"c2pa" in lowered or b"jumb" in lowered
+
+
+def extract_c2pa_chunk(image_path: Path) -> bytes | None:
+    """Return the first complete C2PA PNG chunk, including header and CRC."""
+    if image_path.suffix.casefold() != ".png":
+        return None
+    chunk = _find_c2pa_chunk(image_path)
+    return None if chunk is None else chunk.serialized
+
+
+def has_c2pa_metadata(image_path: Path) -> bool:
+    """Return whether a validly bounded PNG contains a recognizable C2PA chunk."""
+    return extract_c2pa_chunk(Path(image_path)) is not None
+
+
+def _active_manifest(store: dict[str, Any]) -> dict[str, Any]:
+    manifests = store.get("manifests")
+    if not isinstance(manifests, dict):
+        return {}
+    typed_manifests = cast("dict[object, object]", manifests)
+    active = typed_manifests.get(store.get("active_manifest"))
+    return cast("dict[str, Any]", active) if isinstance(active, dict) else {}
+
+
+def _claim_generator_from_store(store: dict[str, Any]) -> str | None:
+    active = _active_manifest(store)
+    direct = active.get("claim_generator")
+    if isinstance(direct, str) and direct.isprintable() and direct:
+        return direct
+    candidates = active.get("claim_generator_info")
+    if isinstance(candidates, list) and candidates and isinstance(candidates[0], dict):
+        candidate = cast("dict[object, object]", candidates[0])
+        name = candidate.get("name")
+        if isinstance(name, str) and name.isprintable() and name:
+            return name
+    return None
+
+
+def synthid_verdict(vendors: str) -> str:
+    """Describe why supported provenance establishes a SynthID watermark."""
+    return f"present according to {vendors} provenance"
+
+
+def _names_present(buffer: bytes, registry: dict[bytes, str]) -> list[str]:
+    return sorted({label for token, label in registry.items() if token in buffer})
+
+
+def synthid_evidence_vendors_in(buffer: bytes, *, has_watermark_action: bool | None = None) -> list[str]:
+    """List issuers whose provenance establishes SynthID for this asset.
+
+    Google applies SynthID to all media generated by its tools, so its AI C2PA
+    provenance is sufficient. OpenAI C2PA predates OpenAI's SynthID rollout;
+    current manifests distinguish the watermarked generation with the explicit
+    ``c2pa.watermarked.*`` action. A legacy OpenAI issuer token alone therefore
+    remains provenance evidence, but not SynthID evidence.
+    """
+    if has_watermark_action is None:
+        has_watermark_action = b"c2pa.watermarked" in buffer
+    return sorted(
+        {
+            vendor.org
+            for vendor in C2PA_AI_VENDORS
+            if vendor.synthid
+            and vendor.issuer in buffer
+            and (has_watermark_action or not vendor.synthid_requires_watermark_action)
+        }
+    )
+
+
+def soft_binding_vendors_in(buffer: bytes) -> list[str]:
+    """List the soft-binding algorithms named in manifest bytes."""
+    return _names_present(buffer, C2PA_SOFT_BINDINGS)
+
+
+def _ordered_matches(buffer: bytes, registry: dict[bytes, str]) -> list[str]:
+    return list(dict.fromkeys(label for token, label in registry.items() if token in buffer))
+
+
+def _populate_registry_fields(buffer: bytes, info: dict[str, Any]) -> bool:
+    issuers = _ordered_matches(buffer, C2PA_ISSUERS)
+    tools = _ordered_matches(buffer, C2PA_AI_TOOLS)
+    actions = _ordered_matches(buffer, C2PA_ACTIONS)
+    if issuers:
+        info["issuer"] = ", ".join(issuers)
+    if tools:
+        info["ai_tool"] = ", ".join(tools)
+    if actions:
+        info["actions"] = ", ".join(actions)
+
+    ai_source = False
+    if b"trainedAlgorithmicMedia" in buffer:
+        info.update(source_type="trainedAlgorithmicMedia (AI-generated)", ai_source_kind="generated")
+        ai_source = True
+    elif b"compositeWithTrainedAlgorithmicMedia" in buffer:
+        info.update(source_type="compositeWithTrainedAlgorithmicMedia (AI-enhanced)", ai_source_kind="enhanced")
+        ai_source = True
+    elif b"algorithmicMedia" in buffer:
+        info["source_type"] = "algorithmicMedia"
+
+    if b"c2pa.watermarked" in buffer:
+        info["watermarked"] = True
+    synthid = synthid_evidence_vendors_in(buffer, has_watermark_action=info.get("watermarked", False))
+    if ai_source and synthid:
+        info["synthid_vendors"] = synthid
+        info["synthid_watermark"] = synthid_verdict(", ".join(synthid))
+
+    soft_bindings = soft_binding_vendors_in(buffer)
+    if soft_bindings:
+        info["soft_binding_vendors"] = soft_bindings
+        info["soft_binding"] = ", ".join(soft_bindings)
+    return ai_source
+
+
+def _base_info(byte_count: int, *, fallback: bool = False) -> dict[str, Any]:
+    container = "C2PA manifest" if fallback else "C2PA manifest store"
+    return {
+        "has_c2pa": True,
+        "type": "C2PA (Coalition for Content Provenance and Authenticity)",
+        "c2pa_manifest": f"{container} ({byte_count} bytes)",
+    }
+
+
+def _info_from_store(store: dict[str, Any], encoded: bytes) -> dict[str, Any]:
+    info = _base_info(len(encoded))
+    _populate_registry_fields(encoded, info)
+    generator = _claim_generator_from_store(store)
+    if generator is not None:
+        info["claim_generator"] = generator
+    signature_value = _active_manifest(store).get("signature_info")
+    if isinstance(signature_value, dict):
+        signature = cast("dict[object, object]", signature_value)
+        timestamp = signature.get("time")
+        if timestamp:
+            info["timestamp"] = str(timestamp)
+    return info
+
+
+def c2pa_info_from_manifest_store(store: str | dict[str, Any]) -> dict[str, Any]:
+    """Normalize a manifest store supplied as JSON text or a decoded object."""
+    try:
+        raw_decoded: object = store if isinstance(store, dict) else json.loads(store)
+        decoded = cast("dict[str, Any]", raw_decoded) if isinstance(raw_decoded, dict) else None
+        if not isinstance(decoded, dict) or not decoded or decoded.get("error"):
+            return {}
+        encoded = json.dumps(decoded, ensure_ascii=False).encode() if isinstance(store, dict) else store.encode()
+    except (TypeError, ValueError):
+        return {}
+    return _info_from_store(decoded, encoded)
+
+
+def cbor_text_after(payload: bytes, key: bytes) -> str | None:
+    """Decode a definite-length CBOR text value immediately following ``key``."""
+    key_end = payload.find(key)
+    if key_end < 0:
+        return None
+    cursor = key_end + len(key)
+    if cursor >= len(payload):
+        return None
+    initial = payload[cursor]
+    if 0x60 <= initial <= 0x77:
+        length, cursor = initial & 0x1F, cursor + 1
+    elif initial == 0x78 and cursor + 1 < len(payload):
+        length, cursor = payload[cursor + 1], cursor + 2
+    elif initial == 0x79 and cursor + 2 < len(payload):
+        length = int.from_bytes(payload[cursor + 1 : cursor + 3], "big")
+        cursor += 3
+    else:
+        return None
+    raw = payload[cursor : cursor + length]
+    if len(raw) != length:
+        return None
+    try:
+        return raw.decode()
+    except UnicodeDecodeError:
+        return raw.decode("latin1", errors="replace")
+
+
+def _parse_c2pa_chunk(payload: bytes, info: dict[str, Any]) -> None:
+    info.update(_base_info(len(payload), fallback=True))
+    _populate_registry_fields(payload, info)
+    for key, output_key in ((b"name", "claim_generator"), (b"specVersion", "c2pa_spec")):
+        value = cbor_text_after(payload, key)
+        if value and value.isprintable():
+            info[output_key] = value
+    timestamps = [item.decode() for item in re.findall(rb"\d{14}Z", payload)]
+    if timestamps:
+        info["timestamp"] = timestamps[0]
+        if len(timestamps) > 1:
+            info["timestamps"] = timestamps[:3]
+
+
+def _extract_c2pa_info_png(image_path: Path) -> dict[str, Any]:
+    if image_path.suffix.casefold() != ".png":
+        return {}
+    chunk = _find_c2pa_chunk(image_path)
+    if chunk is None:
+        return {}
+    info: dict[str, Any] = {}
+    _parse_c2pa_chunk(chunk.payload, info)
+    return info
+
+
+def _extract_c2pa_info_impl(image_path: Path) -> dict[str, Any]:
+    store = read_manifest_store_json(Path(image_path))
+    if store is not None:
+        return c2pa_info_from_manifest_store(store)
+    return _extract_c2pa_info_png(Path(image_path))
+
+
+@functools.lru_cache(maxsize=4)
+def _extract_c2pa_info_cached(path_str: str, _mtime_ns: int, _size: int, _reader: bool) -> dict[str, Any]:
+    """Cache shim: every argument after the path is key-only.
+
+    ``_reader`` is in the key because the answer genuinely depends on it -- with the
+    official reader the manifest comes back as a store, without it from the hand-rolled
+    PNG chunk parser, and the two produce different ``c2pa_manifest`` labels. Keying on
+    the file alone handed a reader-path result to a caller that had disabled the reader.
+    """
+    return _extract_c2pa_info_impl(Path(path_str))
+
+
+def extract_c2pa_info(image_path: Path) -> dict[str, Any]:
+    """Return normalized C2PA evidence from the official reader or PNG fallback.
+
+    Memoized on ``(path, mtime_ns, size)``: one ``identify`` reaches this twice (once
+    directly, once inside ``get_ai_metadata``) and each call re-runs the Rust manifest
+    reader and re-parses its JSON. Size joins mtime in the key because this package
+    rewrites files in place, and an in-place rewrite can land inside one mtime tick.
+    """
+    try:
+        stat = image_path.stat()
+    except OSError:
+        # No stat (a pipe, or a race): read uncached rather than fail.
+        return _extract_c2pa_info_impl(image_path)
+    cached = _extract_c2pa_info_cached(str(image_path), stat.st_mtime_ns, stat.st_size, _C2PA_READER_AVAILABLE)
+    # Deep-ish copy: values are scalars plus a few lists, and a caller mutating one of
+    # those lists would otherwise poison every later reader of the same file.
+    return {key: list(cast("list[Any]", value)) if isinstance(value, list) else value for key, value in cached.items()}
+
+
+def inject_c2pa_chunk(target_path: Path, output_path: Path, c2pa_chunk: bytes) -> None:
+    """Replace any C2PA chunks in a PNG and insert ``c2pa_chunk`` before IDAT."""
+    if target_path.suffix.casefold() != ".png" or output_path.suffix.casefold() != ".png":
+        raise ValueError("C2PA chunk injection is only supported for PNG files")
+    if not _is_well_formed_png(target_path):
+        raise ValueError("Target is not a well-formed PNG file")
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with target_path.open("rb") as source, output_path.open("wb") as target:
+        target.write(source.read(len(PNG_SIGNATURE)))
+        inserted = False
+        while True:
+            header = source.read(_PNG_HEADER.size)
+            length, kind = _PNG_HEADER.unpack(header)
+            if kind == b"IDAT" and not inserted:
+                target.write(c2pa_chunk)
+                inserted = True
+            if kind == C2PA_CHUNK_TYPE:
+                source.seek(length + 4, 1)
+            else:
+                target.write(header)
+                _copy_bytes(source, target, length + 4)
+            if kind == b"IEND":
+                break

src/remove_ai_watermarks/_internal/constants.py

@@ -0,0 +1,180 @@
+"""Registries shared by metadata extraction and provenance classification."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+def _tokens(value: str) -> tuple[str, ...]:
+    return tuple(value.split("|"))
+
+
+SUPPORTED_FORMATS = frozenset(_tokens(".png|.jpg|.jpeg|.webp|.heic|.heif|.avif"))
+AI_METADATA_KEYS = _tokens(
+    "parameters|postprocessing|extras|workflow|prompt|Dream|SD:mode|StableDiffusionVersion|"
+    "generation_time|Model|Model hash|Seed"
+)
+AI_KEYWORDS = _tokens(
+    "prompt|negative_prompt|sampler|cfg_scale|lora|diffusion|comfy|midjourney|dall-e|dalle|imagen|firefly|c2pa|chatgpt|gpt-4|sora|openai|truepic|stable_diffusion|invokeai"
+)
+
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+C2PA_CHUNK_TYPE = b"caBX"
+PNG_METADATA_CHUNKS = frozenset({b"tEXt", b"iTXt", b"zTXt", b"eXIf", b"iCCP"})
+RIFF_METADATA_CHUNKS = frozenset({b"EXIF", b"XMP ", b"ICCP", b"C2PA"})
+RIFF_CODED_IMAGE_CHUNKS = frozenset({b"VP8 ", b"VP8L", b"ALPH", b"ANMF"})
+C2PA_SIGNATURES = tuple(
+    token.encode() for token in _tokens("c2pa|C2PA|jumb|jumd|JUMBF|jumbf|cbor|contentcreds|digid|assertions|manifest")
+)
+
+
+@dataclass(frozen=True, slots=True)
+class C2paAiVendor:
+    """One issuer signature and its normalized product attribution."""
+
+    issuer: bytes
+    org: str
+    platform: str | None
+    needle: str | None
+    synthid: bool = False
+    asserts_ai: bool = False
+    synthid_requires_watermark_action: bool = False
+
+
+def _vendor(
+    issuer: bytes | str,
+    org: str,
+    platform: str | None,
+    needle: str | None,
+    *,
+    synthid: bool = False,
+    asserts_ai: bool = False,
+    synthid_requires_watermark_action: bool = False,
+) -> C2paAiVendor:
+    token = issuer.encode() if isinstance(issuer, str) else issuer
+    return C2paAiVendor(
+        token,
+        org,
+        platform,
+        needle,
+        synthid=synthid,
+        asserts_ai=asserts_ai,
+        synthid_requires_watermark_action=synthid_requires_watermark_action,
+    )
+
+
+# Order is product priority when a manifest mentions more than one organization.
+C2PA_AI_VENDORS: tuple[C2paAiVendor, ...] = (
+    _vendor(b"Microsoft", "Microsoft", "Microsoft (Bing Image Creator / Designer)", "Microsoft"),
+    _vendor(b"Adobe", "Adobe", "Adobe Firefly", "Adobe"),
+    _vendor(
+        b"OpenAI",
+        "OpenAI",
+        "OpenAI (ChatGPT / gpt-image / DALL-E / Sora)",
+        "OpenAI",
+        synthid=True,
+        synthid_requires_watermark_action=True,
+    ),
+    _vendor(b"Google", "Google LLC", "Google (Gemini / Imagen)", "Google", synthid=True),
+    _vendor(b"Stability AI", "Stability AI", "Stability AI (Stable Image / DreamStudio)", "Stability AI"),
+    _vendor(b"Black Forest Labs", "Black Forest Labs", "Black Forest Labs (FLUX)", "Black Forest Labs"),
+    _vendor(b"volcengine", "ByteDance (Volcano Engine)", "ByteDance (Doubao / Jimeng / Volcano Engine)", "ByteDance"),
+    _vendor(
+        "北京火山引擎科技有限公司",
+        "ByteDance (Volcano Engine)",
+        "ByteDance (Doubao / Jimeng / Volcano Engine)",
+        "ByteDance",
+    ),
+    _vendor(b"Byteplus", "BytePlus (ByteDance)", "ByteDance (Doubao / Jimeng / Volcano Engine)", "ByteDance"),
+    _vendor(
+        b"Dreamina",
+        "ByteDance (Dreamina)",
+        "ByteDance (Doubao / Jimeng / Volcano Engine)",
+        "ByteDance",
+        asserts_ai=True,
+    ),
+    _vendor(b"Canva", "Canva", "Canva (Magic Media)", "Canva"),
+    _vendor(b"Eleven Labs", "ElevenLabs", "ElevenLabs", "ElevenLabs"),
+    _vendor(b"fal-ai", "fal.ai", "fal.ai", "fal.ai", asserts_ai=True),
+    _vendor(b"Bria", "Bria Artificial Intelligence", "Bria AI", "Bria", asserts_ai=True),
+    _vendor(b"Truepic", "Truepic", None, None),
+)
+
+C2PA_ISSUERS = {vendor.issuer: vendor.org for vendor in C2PA_AI_VENDORS}
+C2PA_IDENTITY_AI_ORGS = frozenset(vendor.org for vendor in C2PA_AI_VENDORS if vendor.asserts_ai)
+
+C2PA_AI_TOOLS = {
+    token.encode(): label
+    for token, label in (
+        ("GPT-4o", "GPT-4o"),
+        ("ChatGPT", "ChatGPT"),
+        ("Sora", "Sora"),
+        ("DALL-E", "DALL-E"),
+        ("DALL", "DALL-E"),
+        ("Imagen", "Imagen"),
+        ("Firefly", "Firefly"),
+    )
+}
+
+C2PA_SOFT_BINDINGS = {
+    b"com.adobe.trustmark": "Adobe TrustMark",
+    b"com.adobe.icn": "Adobe (content fingerprint)",
+    b"com.digimarc": "Digimarc",
+    b"com.imatag.lamark": "Imatag (Lamark)",
+    b"ai.steg": "Steg.AI",
+    b"com.microsoft.invismark": "Microsoft InvisMark",
+    b"com.microsoft.wavmark": "Microsoft WavMark",
+    b"com.verimatrix": "Verimatrix",
+    b"com.nagra.nexguard": "NAGRA NexGuard",
+    b"com.aiwatermark": "AIWatermark (Meta PixelSeal)",
+    b"ai.trufo": "Trufo",
+    b"app.overlai": "Overlai",
+    b"com.markany": "MarkAny",
+    b"com.mentaport": "Mentaport",
+    b"es.lumatrace": "LumaTrace",
+    b"ai.verda": "VerdaAI",
+    b"ai.contentlens": "ContentLens",
+    b"io.iscc": "ISCC (content code)",
+}
+
+AI_GENERATOR_TOKENS = frozenset(
+    {
+        "firefly",
+        "dall-e",
+        "dalle",
+        "midjourney",
+        "stable diffusion",
+        "stable-diffusion",
+        "stablediffusion",
+        "comfyui",
+        "automatic1111",
+        "invokeai",
+        "imagen",
+        "gpt-image",
+        "nightcafe",
+        "ideogram",
+        "leonardo",
+        "flux",
+        "dreamstudio",
+        "novelai",
+        "reve.com",
+        "aphrodite ai",
+        "apple photos clean up",
+        "fal-ai",
+    }
+)
+
+_C2PA_ACTION_NAMES = _tokens("created|converted|edited|filtered|cropped|resized|opened|placed|watermarked.unbound")
+C2PA_ACTIONS = {f"c2pa.{action}".encode(): action for action in _C2PA_ACTION_NAMES}
+
+
+# TC260 producer identity -> the mark key whose vendor signs with it now lives on the
+# registry rows (``KnownMark.tc260_producer_codes``, read through
+# ``watermark_registry.tc260_producer_vendors``). Keeping the codes beside the mark is
+# what stops a newly registered TC260 vendor from silently falling back to ByteDance.
+#
+# What a TC260 label confirms when its producer is absent or unmapped. Historical
+# behaviour, kept as the fallback so an unrecognized producer never regresses to no
+# relaxation at all: ByteDance's two products are the ones the relaxed band was
+# calibrated on (see _text_mark_engine._DEFAULT_PROVENANCE_NCC_FACTOR).
+TC260_FALLBACK_VENDORS: frozenset[str] = frozenset({"doubao", "jimeng"})

src/remove_ai_watermarks/_internal/ebml.py

@@ -0,0 +1,154 @@
+"""Bounded Matroska/WebM metadata reader for native TC260 AIGC labels.
+
+TC260-PG-20257A stores the label as a Matroska ``SimpleTag`` whose
+``TagName`` is ``AIGC`` and whose ``TagString`` is the normative JSON object.
+The walker seeks over unrelated elements such as clusters instead of reading
+their payloads.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, BinaryIO
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+from remove_ai_watermarks.metadata import MAX_TC260_VALUE_BYTES, parse_tc260_aigc_json
+
+_EBML_MAGIC = b"\x1aE\xdf\xa3"
+_SEGMENT_ID = 0x18538067
+_TAGS_ID = 0x1254C367
+_TAG_ID = 0x7373
+_SIMPLE_TAG_ID = 0x67C8
+_TAG_NAME_ID = 0x45A3
+_TAG_STRING_ID = 0x4487
+_MAX_TAG_NAME_BYTES = 256
+
+
+def _vint_length(first: int, *, maximum: int) -> int | None:
+    """Return an EBML variable-integer length from its first byte."""
+    mask = 0x80
+    for length in range(1, maximum + 1):
+        if first & mask:
+            return length
+        mask >>= 1
+    return None
+
+
+def _read_element_header(
+    stream: BinaryIO,
+    pos: int,
+    limit: int,
+) -> tuple[int, int, int] | None:
+    """Return ``(element_id, payload_start, element_end)`` inside ``limit``."""
+    if pos < 0 or pos >= limit:
+        return None
+    stream.seek(pos)
+    first_raw = stream.read(1)
+    if not first_raw:
+        return None
+    id_length = _vint_length(first_raw[0], maximum=4)
+    if id_length is None or pos + id_length >= limit:
+        return None
+    element_id_raw = first_raw + stream.read(id_length - 1)
+    if len(element_id_raw) != id_length:
+        return None
+    element_id = int.from_bytes(element_id_raw, "big")
+
+    size_first_raw = stream.read(1)
+    if not size_first_raw:
+        return None
+    size_length = _vint_length(size_first_raw[0], maximum=8)
+    if size_length is None:
+        return None
+    size_rest = stream.read(size_length - 1)
+    if len(size_rest) != size_length - 1:
+        return None
+    marker = 1 << (8 - size_length)
+    size_value = int.from_bytes(bytes([size_first_raw[0] & (marker - 1)]) + size_rest, "big")
+    payload_start = pos + id_length + size_length
+    if payload_start > limit:
+        return None
+    unknown_size = size_value == (1 << (7 * size_length)) - 1
+    element_end = limit if unknown_size else payload_start + size_value
+    if element_end > limit:
+        return None
+    return element_id, payload_start, element_end
+
+
+def _iter_elements(
+    stream: BinaryIO,
+    start: int,
+    end: int,
+) -> Iterator[tuple[int, int, int]]:
+    """Yield valid direct children from one bounded EBML region."""
+    pos = start
+    while pos < end:
+        header = _read_element_header(stream, pos, end)
+        if header is None:
+            return
+        element_id, payload_start, element_end = header
+        yield element_id, payload_start, element_end
+        if element_end <= pos:
+            return
+        pos = element_end
+
+
+def _read_bounded(
+    stream: BinaryIO,
+    start: int,
+    end: int,
+    maximum: int,
+) -> bytes | None:
+    size = end - start
+    if size < 0 or size > maximum:
+        return None
+    stream.seek(start)
+    value = stream.read(size)
+    return value if len(value) == size else None
+
+
+def _simple_tag_payloads(
+    stream: BinaryIO,
+    start: int,
+    end: int,
+) -> tuple[bytes, ...]:
+    name: bytes | None = None
+    values: list[bytes] = []
+    for element_id, payload_start, element_end in _iter_elements(stream, start, end):
+        if element_id == _TAG_NAME_ID:
+            name = _read_bounded(stream, payload_start, element_end, _MAX_TAG_NAME_BYTES)
+        elif element_id == _TAG_STRING_ID:
+            value = _read_bounded(stream, payload_start, element_end, MAX_TC260_VALUE_BYTES)
+            if value is not None:
+                values.append(value)
+    if name != b"AIGC":
+        return ()
+    return tuple(value for value in values if parse_tc260_aigc_json(value) is not None)
+
+
+def tc260_aigc_payloads(path: str | Path) -> tuple[bytes, ...]:
+    """Read validated TC260 values from Matroska/WebM ``SimpleTag`` entries."""
+    found: list[bytes] = []
+    try:
+        with open(path, "rb") as stream:
+            if stream.read(4) != _EBML_MAGIC:
+                return ()
+            stream.seek(0, 2)
+            file_size = stream.tell()
+            for element_id, payload_start, element_end in _iter_elements(stream, 0, file_size):
+                if element_id != _SEGMENT_ID:
+                    continue
+                for child_id, child_start, child_end in _iter_elements(stream, payload_start, element_end):
+                    if child_id != _TAGS_ID:
+                        continue
+                    for tag_id, tag_start, tag_end in _iter_elements(stream, child_start, child_end):
+                        if tag_id != _TAG_ID:
+                            continue
+                        for simple_id, simple_start, simple_end in _iter_elements(stream, tag_start, tag_end):
+                            if simple_id == _SIMPLE_TAG_ID:
+                                found.extend(_simple_tag_payloads(stream, simple_start, simple_end))
+    except OSError:
+        return ()
+    return tuple(found)

src/remove_ai_watermarks/_internal/extractor.py

@@ -0,0 +1,98 @@
+"""Read image metadata without changing the source container."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+import piexif
+from PIL import Image
+
+from remove_ai_watermarks._internal.c2pa import extract_c2pa_chunk, extract_c2pa_info, has_c2pa_metadata
+from remove_ai_watermarks._internal.constants import AI_KEYWORDS, AI_METADATA_KEYS
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+_EXIF_KEY = "exif"
+_AI_KEYS_CASEFOLD = frozenset(key.casefold() for key in AI_METADATA_KEYS)
+
+
+def _read_pillow_info(source_path: Path) -> dict[str, Any]:
+    with Image.open(source_path) as image:
+        return {key: value for key, value in image.info.items() if isinstance(key, str)}
+
+
+def _decode_exif(raw: object) -> tuple[str, object]:
+    if not isinstance(raw, bytes):
+        return "exif_raw", raw
+    try:
+        return _EXIF_KEY, piexif.load(raw)
+    except Exception:
+        return "exif_raw", raw
+
+
+def _is_ai_field(key: str) -> bool:
+    folded = key.casefold()
+    return folded in _AI_KEYS_CASEFOLD or any(token in folded for token in AI_KEYWORDS)
+
+
+def _attach_c2pa(source_path: Path, metadata: dict[str, Any]) -> None:
+    if not has_c2pa_metadata(source_path):
+        return
+    metadata["c2pa"] = extract_c2pa_info(source_path)
+    payload = extract_c2pa_chunk(source_path)
+    if payload is not None:
+        metadata["c2pa_chunk"] = payload
+
+
+def extract_metadata(source_path: Path) -> dict[str, Any]:
+    """Return every Pillow-visible field plus decoded EXIF and C2PA data."""
+    raw_info = _read_pillow_info(source_path)
+    metadata = dict(raw_info)
+    if _EXIF_KEY in raw_info:
+        metadata.pop(_EXIF_KEY, None)
+        decoded_key, decoded_value = _decode_exif(raw_info[_EXIF_KEY])
+        metadata[decoded_key] = decoded_value
+
+    _attach_c2pa(source_path, metadata)
+    return metadata
+
+
+def extract_ai_metadata(source_path: Path) -> dict[str, Any]:
+    """Return only metadata keys recognized as AI provenance or generation data."""
+    metadata = {key: value for key, value in _read_pillow_info(source_path).items() if _is_ai_field(key)}
+    _attach_c2pa(source_path, metadata)
+    return metadata
+
+
+def has_ai_metadata(image_path: Path) -> bool:
+    """Return whether a supported metadata signal is present."""
+    if any(_is_ai_field(key) for key in _read_pillow_info(image_path)):
+        return True
+    return has_c2pa_metadata(image_path)
+
+
+def _summary_value(value: object) -> str:
+    if isinstance(value, bytes):
+        return f"<binary data ({len(value)} bytes)>"
+    text = str(value)
+    return text if len(text) <= 100 else f"{text[:100]}..."
+
+
+def get_ai_metadata_summary(source_path: Path) -> str:
+    """Format the AI-only metadata view for the command-line report."""
+    metadata = extract_ai_metadata(source_path)
+    if not metadata:
+        return "No AI metadata found."
+
+    lines = ["AI Image Metadata:", "-" * 40]
+    for key, value in metadata.items():
+        if key == "c2pa_chunk":
+            continue
+        if key == "c2pa" and isinstance(value, dict):
+            lines.append("C2PA Metadata:")
+            c2pa_fields = cast("dict[str, object]", value)
+            lines.extend(f"  {name}: {_summary_value(item)}" for name, item in c2pa_fields.items())
+            continue
+        lines.append(f"{key}: {_summary_value(value)}")
+    return "\n".join(lines)

src/remove_ai_watermarks/_internal/flv.py

@@ -0,0 +1,160 @@
+"""Bounded FLV metadata reader for native TC260 AIGC labels.
+
+TC260-PG-20257A stores the label in the ``onMetaData`` script tag as an AMF0
+property named ``AIGC`` whose string value is the normative JSON object. Media
+tag payloads are skipped without being loaded.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+from remove_ai_watermarks.metadata import MAX_TC260_VALUE_BYTES, parse_tc260_aigc_json
+
+_SCRIPT_TAG = 18
+_MAX_SCRIPT_BYTES = 4 * 1024 * 1024
+
+
+def _u24(value: bytes) -> int:
+    return int.from_bytes(value, "big")
+
+
+def _amf0_string(data: bytes, position: int, *, long: bool = False) -> tuple[bytes, int] | None:
+    length_size = 4 if long else 2
+    if position + length_size > len(data):
+        return None
+    length = int.from_bytes(data[position : position + length_size], "big")
+    start = position + length_size
+    end = start + length
+    if end > len(data):
+        return None
+    return data[start:end], end
+
+
+def _skip_amf0(data: bytes, position: int, depth: int = 0) -> int | None:
+    if position >= len(data) or depth > 8:
+        return None
+    value_type = data[position]
+    position += 1
+    if value_type == 0:
+        return position + 8 if position + 8 <= len(data) else None
+    if value_type == 1:
+        return position + 1 if position + 1 <= len(data) else None
+    if value_type == 2:
+        parsed = _amf0_string(data, position)
+        return parsed[1] if parsed is not None else None
+    if value_type in {5, 6}:
+        return position
+    if value_type == 7:
+        return position + 2 if position + 2 <= len(data) else None
+    if value_type == 11:
+        return position + 10 if position + 10 <= len(data) else None
+    if value_type == 12:
+        parsed = _amf0_string(data, position, long=True)
+        return parsed[1] if parsed is not None else None
+    if value_type == 10:
+        if position + 4 > len(data):
+            return None
+        count = int.from_bytes(data[position : position + 4], "big")
+        position += 4
+        for _ in range(count):
+            next_position = _skip_amf0(data, position, depth + 1)
+            if next_position is None:
+                return None
+            position = next_position
+        return position
+    if value_type in {3, 8}:
+        if value_type == 8:
+            if position + 4 > len(data):
+                return None
+            position += 4
+        while position + 3 <= len(data):
+            name_length = int.from_bytes(data[position : position + 2], "big")
+            position += 2
+            if name_length == 0 and data[position] == 9:
+                return position + 1
+            position += name_length
+            if position > len(data):
+                return None
+            next_position = _skip_amf0(data, position, depth + 1)
+            if next_position is None:
+                return None
+            position = next_position
+        return None
+    return None
+
+
+def _script_payloads(data: bytes) -> tuple[bytes, ...]:
+    first = _amf0_string(data, 1) if data[:1] == b"\x02" else None
+    if first is None or first[0] != b"onMetaData":
+        return ()
+    position = first[1]
+    if position >= len(data) or data[position] not in {3, 8}:
+        return ()
+    if data[position] == 8:
+        position += 5
+    else:
+        position += 1
+    found: list[bytes] = []
+    while position + 3 <= len(data):
+        name_length = int.from_bytes(data[position : position + 2], "big")
+        position += 2
+        if name_length == 0 and data[position] == 9:
+            break
+        name_end = position + name_length
+        if name_end > len(data):
+            break
+        name = data[position:name_end]
+        position = name_end
+        if name == b"AIGC" and position < len(data) and data[position] in {2, 12}:
+            long = data[position] == 12
+            parsed = _amf0_string(data, position + 1, long=long)
+            if parsed is None:
+                break
+            value, position = parsed
+            if len(value) <= MAX_TC260_VALUE_BYTES and parse_tc260_aigc_json(value) is not None:
+                found.append(value)
+            continue
+        next_position = _skip_amf0(data, position)
+        if next_position is None:
+            break
+        position = next_position
+    return tuple(found)
+
+
+def tc260_aigc_payloads(path: str | Path) -> tuple[bytes, ...]:
+    """Read validated TC260 values from FLV ``script.onMetaData.AIGC``."""
+    found: list[bytes] = []
+    try:
+        with open(path, "rb") as stream:
+            header = stream.read(9)
+            if len(header) != 9 or header[:3] != b"FLV":
+                return ()
+            data_offset = int.from_bytes(header[5:9], "big")
+            stream.seek(0, 2)
+            file_size = stream.tell()
+            position = data_offset + 4
+            while position + 11 <= file_size:
+                stream.seek(position)
+                tag_header = stream.read(11)
+                if len(tag_header) != 11:
+                    break
+                tag_type = tag_header[0] & 0x1F
+                data_size = _u24(tag_header[1:4])
+                payload_start = position + 11
+                payload_end = payload_start + data_size
+                if payload_end + 4 > file_size:
+                    break
+                if tag_type == _SCRIPT_TAG and data_size <= _MAX_SCRIPT_BYTES:
+                    payload = stream.read(data_size)
+                    if len(payload) == data_size:
+                        found.extend(_script_payloads(payload))
+                        if found:
+                            return tuple(found)
+                position = payload_end + 4
+    except OSError:
+        return ()
+    return tuple(found)

src/remove_ai_watermarks/_internal/isobmff.py

@@ -0,0 +1,624 @@
+"""Minimal ISOBMFF box walker for AI provenance in AVIF / HEIF / MP4 / JPEG-XL.
+
+The ISO Base Media File Format wraps content in nested ``[size:4][type:4][...]``
+boxes. C2PA stores its manifest in a top-level ``uuid`` box keyed by the
+C2PA UUID; JPEG-XL uses a ``jumb`` box (JUMBF) instead. To strip provenance
+without re-encoding, the image path drops matching boxes and emits the rest
+verbatim. The streaming MP4/MOV/M4A path instead preserves all offsets by
+retyping matching boxes as ``free`` and blanking their payloads in place. The
+codestream (``mdat`` for ISOBMFF, ``jxlc`` / ``jxlp`` for JPEG-XL) is untouched,
+so pixel, video, and audio data is preserved bit-for-bit.
+
+TC260-PG-20257A video metadata is nested instead:
+``moov.udta.meta.keys/ilst``. Its detector seeks through those boxes without
+reading media payloads, and its stripper blanks the validated key/value in
+place so fast-start media offsets remain valid.
+
+This file intentionally avoids dependencies on format-specific libraries
+(pillow-heif, pillow-jxl, pymp4) so it works on systems where they aren't
+installed.
+
+Reference: ISO/IEC 14496-12 (ISOBMFF) and C2PA 2.1 spec §11.
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+import os
+import re
+import shutil
+import struct
+from typing import TYPE_CHECKING, Any, BinaryIO
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+from remove_ai_watermarks.metadata import (
+    AIGC_MARKERS,
+    C2PA_UUID,
+    IPTC_AI_FIELD_MARKERS,
+    IPTC_AI_MARKERS,
+    MAX_TC260_VALUE_BYTES,
+    parse_tc260_aigc_json,
+)
+
+logger = logging.getLogger(__name__)
+
+# Top-level box types that may carry AI provenance. ``uuid`` boxes are checked
+# against ``C2PA_UUID`` / AI-label markers before being stripped; ``jumb`` boxes
+# are always stripped (JPEG-XL uses them exclusively for JUMBF).
+C2PA_BOX_TYPES: frozenset[bytes] = frozenset({b"uuid", b"jumb"})
+
+# AI-label byte markers (TC260 AIGC, IPTC "Made with AI", IPTC 2025.1 AI fields)
+# whose presence inside an XMP ``uuid`` box means the box carries an AI label.
+# Matching the payload rather than a fixed XMP UUID avoids the XMP-box UUID
+# byte-order ambiguity and stays surgical: only AI-bearing XMP is dropped, plain
+# XMP (copyright, camera info) is kept.
+_AI_LABEL_MARKERS: tuple[bytes, ...] = AIGC_MARKERS + IPTC_AI_MARKERS + IPTC_AI_FIELD_MARKERS
+
+# Adobe XMP packet delimiters (XMP spec part 3). In HEIF/AVIF the XMP packet
+# sits inside a ``meta``-box ``mime`` item whose bytes live in ``mdat`` / ``idat``,
+# out of reach of the top-level box stripper, so an AI-label packet there is
+# blanked in place (see ``blank_ai_xmp_packets``).
+_XMP_PACKET_RE = re.compile(rb"<\?xpacket begin=.*?<\?xpacket end=[^>]*?\?>", re.DOTALL)
+_STREAM_COPY_BYTES = 1024 * 1024
+STREAM_SCAN_BYTES = 4 * 1024 * 1024
+
+
+# TC260-PG-20257A stores an MP4/MOV label as an ``AIGC`` key in
+# ``moov.udta.meta.keys`` and its JSON value in the corresponding
+# ``moov.udta.meta.ilst`` item. The value is intentionally bounded before it is
+# read: the normative object is tiny, and a corrupt size must not allocate an
+# arbitrary amount of memory during an inspection.
+def _iter_top_level_boxes(data: bytes) -> Iterator[tuple[int, int, bytes, int]]:
+    """Yield ``(start, end, type, payload_offset)`` for each top-level box.
+
+    Handles all three ISOBMFF box-size encodings:
+    - ``size > 1``: 32-bit size field is the total box length.
+    - ``size == 1``: 64-bit ``largesize`` follows after the type field.
+    - ``size == 0``: box runs to end of file.
+    """
+    pos = 0
+    n = len(data)
+    while pos + 8 <= n:
+        size32 = struct.unpack_from(">I", data, pos)[0]
+        box_type = data[pos + 4 : pos + 8]
+        if size32 == 1:
+            if pos + 16 > n:
+                return
+            size = struct.unpack_from(">Q", data, pos + 8)[0]
+            payload_off = pos + 16
+        elif size32 == 0:
+            size = n - pos
+            payload_off = pos + 8
+        else:
+            size = size32
+            payload_off = pos + 8
+        if size < (payload_off - pos) or pos + size > n:
+            return
+        yield pos, pos + size, box_type, payload_off
+        pos += size
+
+
+def _read_box_header(
+    stream: BinaryIO,
+    pos: int,
+    limit: int,
+) -> tuple[int, bytes, int] | None:
+    """Return ``(end, type, payload_offset)`` for one box inside ``limit``."""
+    if pos < 0 or pos + 8 > limit:
+        return None
+    stream.seek(pos)
+    header = stream.read(8)
+    if len(header) != 8:
+        return None
+    size32 = struct.unpack(">I", header[:4])[0]
+    box_type = header[4:8]
+    payload_off = pos + 8
+    if size32 == 1:
+        extended = stream.read(8)
+        if len(extended) != 8:
+            return None
+        size = struct.unpack(">Q", extended)[0]
+        payload_off = pos + 16
+    elif size32 == 0:
+        size = limit - pos
+    else:
+        size = size32
+    end = pos + size
+    if size < payload_off - pos or end > limit:
+        return None
+    return end, box_type, payload_off
+
+
+def iter_file_boxes(
+    stream: BinaryIO,
+    start: int,
+    end: int,
+) -> Iterator[tuple[int, int, bytes, int]]:
+    """Yield valid boxes from one bounded container region."""
+    pos = start
+    while pos + 8 <= end:
+        header = _read_box_header(stream, pos, end)
+        if header is None:
+            return
+        box_end, box_type, payload_off = header
+        yield pos, box_end, box_type, payload_off
+        pos = box_end
+
+
+def _tc260_key_indices(
+    stream: BinaryIO,
+    payload_off: int,
+    box_end: int,
+) -> dict[int, tuple[int, int]]:
+    """Map every exact ``AIGC`` key index to its byte span."""
+    if payload_off + 8 > box_end:
+        return {}
+    stream.seek(payload_off)
+    prefix = stream.read(8)
+    if len(prefix) != 8:
+        return {}
+    entry_count = struct.unpack(">I", prefix[4:8])[0]
+    pos = payload_off + 8
+    found: dict[int, tuple[int, int]] = {}
+    for index in range(1, entry_count + 1):
+        if pos + 8 > box_end:
+            return {}
+        stream.seek(pos)
+        header = stream.read(8)
+        if len(header) != 8:
+            return {}
+        entry_size = struct.unpack(">I", header[:4])[0]
+        entry_end = pos + entry_size
+        if entry_size < 8 or entry_end > box_end:
+            return {}
+        name_start = pos + 8
+        if entry_end - name_start == 4:
+            stream.seek(name_start)
+            if stream.read(4) == b"AIGC":
+                found[index] = (name_start, entry_end)
+        pos = entry_end
+    return found
+
+
+def _tc260_aigc_regions(
+    stream: BinaryIO,
+    file_size: int,
+) -> list[tuple[int, int, int, int, bytes]]:
+    """Locate validated native TC260 entries without reading media payloads.
+
+    Each tuple is ``(key_start, key_end, value_start, value_end, value)``.
+    """
+    regions: list[tuple[int, int, int, int, bytes]] = []
+    for _moov_start, moov_end, moov_type, moov_payload in iter_file_boxes(stream, 0, file_size):
+        if moov_type != b"moov":
+            continue
+        for _udta_start, udta_end, udta_type, udta_payload in iter_file_boxes(
+            stream,
+            moov_payload,
+            moov_end,
+        ):
+            if udta_type != b"udta":
+                continue
+            for _meta_start, meta_end, meta_type, meta_payload in iter_file_boxes(
+                stream,
+                udta_payload,
+                udta_end,
+            ):
+                if meta_type != b"meta" or meta_payload + 4 > meta_end:
+                    continue
+                keys: dict[int, tuple[int, int]] = {}
+                ilst_boxes: list[tuple[int, int]] = []
+                for _child_start, child_end, child_type, child_payload in iter_file_boxes(
+                    stream,
+                    meta_payload + 4,
+                    meta_end,
+                ):
+                    if child_type == b"keys":
+                        keys.update(_tc260_key_indices(stream, child_payload, child_end))
+                    elif child_type == b"ilst":
+                        ilst_boxes.append((child_payload, child_end))
+                if not keys:
+                    continue
+                for ilst_payload, ilst_end in ilst_boxes:
+                    for _item_start, item_end, item_type, item_payload in iter_file_boxes(
+                        stream,
+                        ilst_payload,
+                        ilst_end,
+                    ):
+                        index = int.from_bytes(item_type, "big")
+                        key_span = keys.get(index)
+                        if key_span is None:
+                            continue
+                        for _data_start, data_end, data_type, data_payload in iter_file_boxes(
+                            stream,
+                            item_payload,
+                            item_end,
+                        ):
+                            value_start = data_payload + 8
+                            value_size = data_end - value_start
+                            if data_type != b"data" or value_size < 0 or value_size > MAX_TC260_VALUE_BYTES:
+                                continue
+                            stream.seek(value_start)
+                            value = stream.read(value_size)
+                            if len(value) == value_size and parse_tc260_aigc_json(value) is not None:
+                                regions.append((*key_span, value_start, data_end, value))
+    return regions
+
+
+def tc260_aigc_payloads(path: str | Path) -> tuple[bytes, ...]:
+    """Read native TC260 ``AIGC`` JSON values from an MP4/MOV container."""
+    try:
+        with open(path, "rb") as stream:
+            if not is_isobmff(stream.read(8)):
+                return ()
+            stream.seek(0, 2)
+            file_size = stream.tell()
+            return tuple(region[4] for region in _tc260_aigc_regions(stream, file_size))
+    except OSError:
+        return ()
+
+
+def blank_tc260_aigc_tags(data: bytes) -> tuple[bytes, int]:
+    """Blank native TC260 values in place while preserving every box offset.
+
+    Removing a nested ``ilst`` item would shift ``mdat`` in a fast-start MP4 and
+    invalidate its chunk offsets. Replacing the four-byte key with ``free`` and
+    the JSON value with spaces keeps every box size and media offset unchanged.
+    """
+    if not is_isobmff(data):
+        return data, 0
+    regions = _tc260_aigc_regions(io.BytesIO(data), len(data))
+    if not regions:
+        return data, 0
+    out = bytearray(data)
+    key_spans: set[tuple[int, int]] = set()
+    for key_start, key_end, value_start, value_end, _value in regions:
+        key_spans.add((key_start, key_end))
+        out[key_start:key_end] = b"free"
+        out[value_start:value_end] = b" " * (value_end - value_start)
+    return bytes(out), len(key_spans)
+
+
+def is_isobmff(data: bytes) -> bool:
+    """Cheap sniff: ISOBMFF files start with an ``ftyp`` box."""
+    return len(data) >= 8 and data[4:8] == b"ftyp"
+
+
+def scan_c2pa_region(path: str | Path, *, max_total: int = 4 * 1024 * 1024) -> bytes:
+    """Concatenated payloads of top-level ``uuid`` / ``jumb`` boxes in an ISOBMFF
+    file, found by seeking past other boxes (``mdat`` etc.) by size.
+
+    C2PA manifests and XMP packets (incl. AI labels) live in top-level ``uuid``
+    boxes; JPEG-XL uses ``jumb``. In a streaming / non-faststart MP4 the manifest
+    sits AFTER a multi-megabyte ``mdat``, so a fixed first-MB read misses it. This
+    walks box headers (8-16 bytes each) and seeks past payloads it does not need,
+    so it never loads ``mdat`` into memory and works on multi-GB files. Returns
+    the relevant box payloads (capped at ``max_total``), or ``b""`` for a
+    non-ISOBMFF file or on any read error.
+    """
+    collected = bytearray()
+    try:
+        with open(path, "rb") as f:
+            sniff = f.read(8)
+            if len(sniff) < 8 or sniff[4:8] != b"ftyp":
+                return b""
+            f.seek(0, 2)
+            file_size = f.tell()
+            pos = 0
+            while pos + 8 <= file_size and len(collected) < max_total:
+                f.seek(pos)
+                header = f.read(8)
+                if len(header) < 8:
+                    break
+                size32 = struct.unpack(">I", header[:4])[0]
+                box_type = header[4:8]
+                payload_off = pos + 8
+                if size32 == 1:
+                    ext = f.read(8)
+                    if len(ext) < 8:
+                        break
+                    size = struct.unpack(">Q", ext)[0]
+                    payload_off = pos + 16
+                elif size32 == 0:
+                    size = file_size - pos
+                else:
+                    size = size32
+                if size < (payload_off - pos) or pos + size > file_size:
+                    # Detection-only: a malformed box halts the walk, so a manifest
+                    # placed after it is missed (best-effort scan; no resync).
+                    break
+                if box_type in C2PA_BOX_TYPES:
+                    f.seek(payload_off)
+                    to_read = min(pos + size - payload_off, max_total - len(collected))
+                    if to_read > 0:
+                        collected += f.read(to_read)
+                pos += size
+    except OSError:
+        return b""
+    return bytes(collected)
+
+
+def _payload_has_ai_label(
+    stream: BinaryIO,
+    start: int,
+    end: int,
+    *,
+    max_scan: int,
+) -> bool:
+    """Scan a bounded prefix of one metadata payload for an AI-label marker."""
+    longest_marker = max(len(marker) for marker in _AI_LABEL_MARKERS)
+    remaining = min(end - start, max_scan)
+    overlap = b""
+    stream.seek(start)
+    while remaining > 0:
+        chunk = stream.read(min(_STREAM_COPY_BYTES, remaining))
+        if not chunk:
+            return False
+        searchable = overlap + chunk
+        if any(marker in searchable for marker in _AI_LABEL_MARKERS):
+            return True
+        overlap = searchable[-(longest_marker - 1) :]
+        remaining -= len(chunk)
+    return False
+
+
+def _streaming_provenance_boxes(
+    stream: BinaryIO,
+    file_size: int,
+    *,
+    max_scan: int,
+) -> list[tuple[int, int, int]] | None:
+    """Return top-level provenance boxes, or ``None`` for a malformed walk.
+
+    Each result is ``(box_start, payload_start, box_end)``. The walk reads only
+    headers and bounded metadata prefixes, seeking over ``mdat`` payloads.
+    """
+    stream.seek(0)
+    if not is_isobmff(stream.read(8)):
+        return None
+    targets: list[tuple[int, int, int]] = []
+    pos = 0
+    while pos < file_size:
+        header = _read_box_header(stream, pos, file_size)
+        if header is None:
+            return None
+        box_end, box_type, payload_off = header
+        if box_type == b"uuid":
+            stream.seek(payload_off)
+            is_c2pa = payload_off + 16 <= box_end and stream.read(16) == C2PA_UUID
+            has_ai_label = not is_c2pa and _payload_has_ai_label(
+                stream,
+                payload_off,
+                box_end,
+                max_scan=max_scan,
+            )
+            if is_c2pa or has_ai_label:
+                targets.append((pos, payload_off, box_end))
+        elif box_type == b"jumb":
+            targets.append((pos, payload_off, box_end))
+        pos = box_end
+    return targets
+
+
+def _overwrite_range(
+    stream: BinaryIO,
+    start: int,
+    end: int,
+    *,
+    byte: bytes,
+) -> None:
+    """Overwrite one byte range with bounded allocations."""
+    stream.seek(start)
+    remaining = end - start
+    block = byte * min(_STREAM_COPY_BYTES, max(remaining, 1))
+    while remaining > 0:
+        size = min(len(block), remaining)
+        stream.write(block[:size])
+        remaining -= size
+
+
+def strip_isobmff_media_file(
+    source: str | Path,
+    output: str | Path,
+    *,
+    max_box_scan: int = STREAM_SCAN_BYTES,
+) -> tuple[int, int]:
+    """Stream-copy an MP4/MOV/M4A while removing supported AI metadata.
+
+    The output retains every box size and byte offset. A top-level C2PA/JUMBF or
+    AI-label box is converted to a ``free`` box and its payload is zeroed; native
+    TC260 key/value spans are blanked in place. Keeping the original lengths is
+    required because removing a pre-``mdat`` box would invalidate absolute media
+    offsets in an existing sample table.
+
+    The source is copied in bounded chunks to a sibling temporary file and
+    atomically published only after all patches succeed. A malformed top-level
+    walk is fail-safe: the input is copied unchanged.
+
+    Returns ``(provenance_boxes_blanked, native_tc260_keys_blanked)``.
+    """
+    from pathlib import Path as _Path
+
+    from remove_ai_watermarks.video_encoding import atomic_video_output
+
+    source_path = _Path(source)
+    output_path = _Path(output)
+    with source_path.open("rb") as stream:
+        stream.seek(0, 2)
+        file_size = stream.tell()
+        targets = _streaming_provenance_boxes(
+            stream,
+            file_size,
+            max_scan=max_box_scan,
+        )
+        tc260_regions = _tc260_aigc_regions(stream, file_size) if targets is not None else []
+        tc260_key_spans = {(region[0], region[1]) for region in tc260_regions}
+
+    with atomic_video_output(output_path) as temporary_path:
+        with source_path.open("rb") as source_stream, temporary_path.open("r+b") as temporary:
+            shutil.copyfileobj(source_stream, temporary, length=_STREAM_COPY_BYTES)
+            if targets is not None:
+                for box_start, payload_start, box_end in targets:
+                    temporary.seek(box_start + 4)
+                    temporary.write(b"free")
+                    _overwrite_range(temporary, payload_start, box_end, byte=b"\x00")
+                for key_start, _key_end, value_start, value_end, _value in tc260_regions:
+                    temporary.seek(key_start)
+                    temporary.write(b"free")
+                    _overwrite_range(temporary, value_start, value_end, byte=b" ")
+            temporary.flush()
+            os.fsync(temporary.fileno())
+        shutil.copymode(source_path, temporary_path)
+
+    if targets is None:
+        logger.warning(
+            "ISOBMFF box walk failed for %s; copied input unchanged to avoid corrupting media offsets",
+            source_path,
+        )
+        return 0, 0
+    return len(targets), len(tc260_key_spans)
+
+
+def strip_c2pa_boxes(data: bytes) -> tuple[bytes, int]:
+    """Return ``(cleaned_bytes, stripped_count)`` with AI-provenance boxes removed.
+
+    Walks top-level boxes and drops:
+    - any ``uuid`` box whose UUID equals ``C2PA_UUID`` (a C2PA manifest);
+    - any ``uuid`` box whose payload carries an AI-label marker (an XMP packet
+      with a TC260 / IPTC / IPTC-2025.1 AI field -- caught by content, not by the
+      XMP UUID, so it works regardless of the UUID's byte order, and leaves plain
+      non-AI XMP intact);
+    - any ``jumb`` box (JPEG-XL JUMBF container).
+
+    All other boxes (incl. ``mdat`` / codestream) are emitted verbatim, so pixel
+    and audio data is preserved bit-for-bit. Non-ISOBMFF input is returned
+    unchanged. Despite the name this also covers MP4/MOV/M4A video and audio
+    (all ISOBMFF). NOTE: this drops only top-level boxes. AI metadata stored as an
+    *item inside the ``meta`` box* (typical for AVIF/HEIF) is handled separately and
+    in place (same length, no offset rewrite): AI-label XMP by
+    :func:`blank_ai_xmp_packets`, and AI-generator tokens in an ``Exif`` item by
+    :func:`blank_ai_exif_tokens`.
+    """
+    if not is_isobmff(data):
+        return data, 0
+
+    out = bytearray()
+    stripped = 0
+    consumed = 0
+    for start, end, box_type, payload_off in _iter_top_level_boxes(data):
+        consumed = end
+        if box_type == b"uuid":
+            # uuid boxes carry the 16-byte UUID immediately after the type.
+            is_c2pa = payload_off + 16 <= end and data[payload_off : payload_off + 16] == C2PA_UUID
+            has_ai_label = any(marker in data[payload_off:end] for marker in _AI_LABEL_MARKERS)
+            if is_c2pa or has_ai_label:
+                stripped += 1
+                continue
+        elif box_type == b"jumb":
+            stripped += 1
+            continue
+        out.extend(data[start:end])
+
+    # Fail-safe: the walker returns early on a malformed box (bad size, or a box
+    # that runs past EOF), so anything after it was never visited. Emitting `out`
+    # would silently truncate the file from the bad box to EOF -- worse than not
+    # stripping. If the walk did not consume the whole input, return it unchanged.
+    if consumed != len(data):
+        logger.warning(
+            "ISOBMFF box walk stopped at offset %d of %d (malformed box); "
+            "returning input unchanged to avoid truncation",
+            consumed,
+            len(data),
+        )
+        return data, 0
+
+    return bytes(out), stripped
+
+
+def blank_ai_xmp_packets(data: bytes) -> tuple[bytes, int]:
+    """Overwrite (with spaces, in place) any XMP packet carrying an AI-label
+    marker; return ``(data, blanked_count)``.
+
+    HEIF/AVIF store XMP as a ``meta``-box ``mime`` item whose bytes live in
+    ``mdat`` / ``idat``, which ``strip_c2pa_boxes`` cannot remove without
+    meta-box surgery (``iinf`` / ``iloc`` rewrite). Instead, the XMP packet is
+    located by its ``<?xpacket begin ... end?>`` delimiters and, when it carries
+    an AI-label marker (TC260 AIGC / IPTC / IPTC-2025.1), overwritten with spaces.
+    Because the replacement is the **same length**, every box size and ``iloc``
+    offset stays valid and the coded image data is untouched -- only the AI label
+    content is destroyed. Packets without an AI marker (plain copyright / camera
+    XMP) are left intact, mirroring the top-level XMP-``uuid`` content match.
+    """
+    blanked = 0
+
+    def _scrub(match: re.Match[bytes]) -> bytes:
+        nonlocal blanked
+        packet = match.group()
+        if any(marker in packet for marker in _AI_LABEL_MARKERS):
+            blanked += 1
+            return b" " * len(packet)
+        return packet
+
+    return _XMP_PACKET_RE.sub(_scrub, data), blanked
+
+
+# EXIF TIFF byte-order headers: little-endian (II 0x2a 0x00) and big-endian
+# (MM 0x00 0x2a). A HEIF/AVIF ``Exif`` meta-box item stores its TIFF block in
+# ``mdat`` / ``idat``, so the block (and these headers) appear in the raw bytes.
+_TIFF_HEADERS: tuple[bytes, ...] = (b"II\x2a\x00", b"MM\x00\x2a")
+# How far past a TIFF header an EXIF block plausibly extends; bounds the slice we
+# hand to piexif and search within (EXIF blocks are small kilobyte-scale).
+_EXIF_WINDOW = 256 * 1024
+
+
+def blank_ai_exif_tokens(data: bytes) -> tuple[bytes, int]:
+    """Overwrite (with spaces, in place) any AI-generator token in an EXIF block
+    stored as an ISOBMFF ``meta``-box ``Exif`` item; return ``(data, blanked_count)``.
+
+    HEIF/AVIF can carry EXIF as a ``meta``-box ``Exif`` item whose TIFF bytes live
+    in ``mdat`` / ``idat`` -- out of reach of the top-level box stripper, and (when
+    no pillow-heif plugin is installed) of the PIL EXIF reader too, so an AI
+    ``Software`` / ``Make`` / ``Artist`` / ``ImageDescription`` tag there survived
+    ``remove_ai_metadata`` (a documented gap). This locates EXIF TIFF blocks by
+    their byte-order header, **validates each with piexif** (so a coincidental
+    II/MM run in pixel data is ignored -- it will not parse as a TIFF IFD), and
+    overwrites any AI value with spaces of the SAME length. Because the replacement
+    is same-length, every box size and ``iloc`` offset stays valid and the coded image
+    is untouched -- only the AI tag content is destroyed; camera/editor EXIF without an
+    AI token is left intact. This mirrors ``metadata._scrub_ai_exif`` in what it removes
+    -- generator tokens (``Software``/``Make``/``Artist``/``ImageDescription``), the
+    China TC260 ``{"AIGC":{...}}`` block (``ImageDescription``/``UserComment``), and the
+    xAI/Grok ``Signature:`` + UUID-``Artist`` pair -- since on the ISOBMFF path this is
+    the ONLY EXIF scrubber (``_scrub_ai_exif`` never runs there), so without parity a
+    HEIC/AVIF AIGC/xAI tag is detected but not removed.
+    """
+    import piexif
+
+    # The AI-EXIF rule set is defined ONCE in metadata._ai_exif_targets and shared by both
+    # EXIF scrubbers (the JPEG _scrub_ai_exif pops the tag; here we blank the value bytes),
+    # so their coverage cannot drift. Imported lazily to avoid import-order coupling with
+    # metadata (which imports this module); a deliberate cross-module use, not an API leak.
+    from remove_ai_watermarks.metadata import _ai_exif_targets  # pyright: ignore[reportPrivateUsage]
+
+    out = bytearray(data)
+    blanked = 0
+    for header in _TIFF_HEADERS:
+        pos = data.find(header)
+        while pos != -1:
+            window = bytes(out[pos : pos + _EXIF_WINDOW])
+            try:
+                loaded: dict[str, Any] = piexif.load(window)
+            except Exception:
+                loaded = {}
+            for _ifd_key, _tag, value, _name in _ai_exif_targets(loaded):
+                # Blank the value bytes in place, within this EXIF block only.
+                vpos = out.find(value, pos, pos + _EXIF_WINDOW)
+                if vpos != -1:
+                    out[vpos : vpos + len(value)] = b" " * len(value)
+                    blanked += 1
+            pos = data.find(header, pos + len(header))
+    return bytes(out), blanked

src/remove_ai_watermarks/_internal/qwen_zimage_pipeline.py

@@ -1,16 +1,9 @@
-"""Qwen 2512 Canny regeneration followed by masked Z-Image face repair.
+"""Project-native Qwen regeneration with an optional masked face refinement pass.
 
-This profile ports the two-stage architecture used by cebeuq/Synthid-Bypass:
-
-1. Qwen-Image-2512 img2img with the 4-step Lightning LoRA and the DiffSynth
-   blockwise Canny ControlNet regenerates the whole image, optionally as
-   overlapping feather-blended tiles for large inputs.
-2. Faces are detected on the original image, refined to masks with SAM, regenerated
-   from the original face crops with Z-Image Turbo, and feathered into stage 1.
-
-The runtime intentionally uses permissively licensed YuNet instead of the reference
-workflow's Ultralytics detector. All diffusion and segmentation models remain the same
-model families and the denoise formulas are direct ports of the reference custom node.
+The profile was inspired by public experiments that combine structure-guided global
+regeneration with a second face-only pass. Its orchestration, sizing rules, adaptive
+strength policy, detector, masks, prompts, and compositing are implemented here for
+this library's Pillow and DiffSynth runtime.
 """
 
 # DiffSynth, torch, transformers, and cv2 expose mostly untyped tensor/array APIs.
@@ -32,7 +25,7 @@ from typing import TYPE_CHECKING, Any
 import numpy as np
 from PIL import Image
 
-from remove_ai_watermarks.noai.watermark_profiles import resolve_seed
+from remove_ai_watermarks._internal.watermark_profiles import resolve_seed
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -52,10 +45,8 @@ YUNET_MODEL_URL = (
 )
 YUNET_MODEL_NAME = "face_detection_yunet_2023mar.onnx"
 YUNET_MODEL_SHA256 = "8f2383e4dd3cfbb4553ea8718107fc0423210dc964f9f4280604804ed2552fa4"
-# The upstream graph's 0.2 threshold belongs to YOLO and does not transfer to
-# YuNet's score calibration. At 0.2 YuNet admitted background and decorative
-# false positives, multiplying the serial Z-Image face-stage cost. A 0.5 gate
-# retained all visible faces in the public and upstream comparison fixtures.
+# This threshold retained the faces in the public validation set without admitting
+# decorative background regions as faces.
 YUNET_SCORE_THRESHOLD = 0.5
 
 GLOBAL_STEPS = 4
@@ -64,14 +55,34 @@ GLOBAL_CFG = 1.0
 FACE_CFG = 1.0
 GLOBAL_CONTROLNET_SCALE = 1.0
 RESIDENT_FACE_MODEL_MIN_VRAM_GIB = 64.0
+# Below this floor the mandatory Qwen stack streams from disk, which is what makes a
+# 20B model runnable on a consumer card at all; at or above it, streaming is pure
+# waste. Set equal to the face floor rather than lower because that is the
+# configuration actually measured with both stacks resident; a tighter gate is
+# plausible but unvalidated. Benchmark in docs/module-internals.md, "CPU offload".
+RESIDENT_GLOBAL_MODEL_MIN_VRAM_GIB = 64.0
+FACE_DENOISE_SCALE = 0.5
+
+# Both stages prompt with compile-time constants, and at CFG 1.0 DiffSynth reuses the
+# positive embedding for the negative side instead of encoding it, so exactly one
+# embedding per stage is ever needed. Persisting it lets the next container load the
+# stack without its text encoder at all: 15.45 GiB for Qwen and 7.49 GiB for Z-Image
+# of a measured 87.6 GiB read per request. The stored tensors are what the encoder
+# itself produced, so the output stays byte-identical. Bump the version when the
+# stored shape changes; the model id and prompt are already part of the key, so a
+# model or prompt change invalidates itself.
+_PROMPT_CACHE_VERSION = 1
+_PROMPT_CACHE_DIRNAME = "prompt-embeddings"
+# DiffSynth identifies a pipeline unit by what it produces, so these tuples are how
+# the prompt stage is located inside each pipeline and how its cache file is keyed.
+_QWEN_PROMPT_OUTPUTS = ("prompt_emb", "prompt_emb_mask")
+_ZIMAGE_PROMPT_OUTPUTS = ("prompt_embeds",)
 
-# The source graph uses normalized Canny thresholds 0.05 and 0.25. OpenCV takes
-# byte thresholds, so round 255*x to the matching integer values.
 _CANNY_LOW = 13
 _CANNY_HIGH = 64
 
-# These strings intentionally preserve the reference workflow spelling. They are
-# model inputs, not user-facing copy, and changing them would change the port.
+# These short model inputs are retained as calibrated compatibility parameters.
+# Changing them requires the same provider-oracle and identity evaluation as a model change.
 _GLOBAL_PROMPT = "ultra clear and smoothe skin, spotless skin"
 _GLOBAL_NEGATIVE = "moles, freckes, high detail skin"
 _FACE_PROMPT = ""
@@ -89,6 +100,17 @@ def resolve_face_model_residency(
     return total_memory_gib >= RESIDENT_FACE_MODEL_MIN_VRAM_GIB
 
 
+def resolve_global_model_residency(
+    requested: bool | None,
+    *,
+    total_memory_gib: float,
+) -> bool:
+    """Keep the mandatory Qwen stack resident when explicitly requested or safely sized."""
+    if requested is not None:
+        return requested
+    return total_memory_gib >= RESIDENT_GLOBAL_MODEL_MIN_VRAM_GIB
+
+
 def _pin_vram_managed_models(pipe: Any) -> None:
     """Move the managed Z-Image stack to CUDA once and make offload a no-op."""
     model_names = ["text_encoder", "dit", "vae_encoder", "vae_decoder"]
@@ -120,7 +142,56 @@ def _pin_vram_managed_models(pipe: Any) -> None:
     pipe.load_models_to_device(model_names)
 
 
-def _cached_prompt_process(original_process: Any) -> Any:
+def _cast_prompt_payload(payload: Any, device: Any, dtype: Any) -> Any:
+    """Move a stored embedding payload onto the runtime device.
+
+    Only floating tensors take the pipeline dtype. The attention masks travel in the
+    same payload and are integer, so casting them would corrupt the prompt.
+    """
+    import torch
+
+    if isinstance(payload, torch.Tensor):
+        if dtype is not None and payload.is_floating_point():
+            return payload.to(device=device, dtype=dtype)
+        return payload.to(device=device)
+    if isinstance(payload, dict):
+        return {key: _cast_prompt_payload(value, device, dtype) for key, value in payload.items()}
+    if isinstance(payload, (list, tuple)):
+        return type(payload)(_cast_prompt_payload(value, device, dtype) for value in payload)
+    return payload
+
+
+def _prompt_cache_path(model_id: str, output_params: tuple[str, ...], prompt: str) -> Path:
+    """Locate the stored embedding for one model and one exact prompt string."""
+    key = "\x1f".join((str(_PROMPT_CACHE_VERSION), model_id, *output_params, prompt))
+    digest = hashlib.sha256(key.encode("utf-8")).hexdigest()[:32]
+    return _model_cache_dir() / _PROMPT_CACHE_DIRNAME / f"{digest}.pt"
+
+
+def _store_prompt_payload(path: Path, payload: Any) -> None:
+    """Write the embedding atomically so a torn write can never read back as a hit."""
+    import torch
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(dir=path.parent, suffix=".pt", delete=False) as handle:
+        torch.save(_cast_prompt_payload(payload, "cpu", None), handle)
+        temporary = Path(handle.name)
+    temporary.replace(path)
+
+
+def _load_prompt_payload(path: Path, device: Any, dtype: Any) -> Any:
+    import torch
+
+    return _cast_prompt_payload(torch.load(path, map_location="cpu", weights_only=True), device, dtype)
+
+
+def _cached_prompt_process(
+    original_process: Any,
+    *,
+    model_id: str | None,
+    output_params: tuple[str, ...],
+    require_cache: bool,
+) -> Any:
     cache: dict[str, dict[str, Any]] = {}
 
     def cached_process(
@@ -130,9 +201,30 @@ def _cached_prompt_process(original_process: Any) -> Any:
     ) -> dict[str, Any]:
         if edit_image is not None:
             return original_process(runtime_pipe, prompt, edit_image=edit_image)
-        if prompt not in cache:
-            cache[prompt] = original_process(runtime_pipe, prompt, edit_image=None)
-        return cache[prompt]
+        if prompt in cache:
+            return cache[prompt]
+        path = None if model_id is None else _prompt_cache_path(model_id, output_params, prompt)
+        if path is not None and path.exists():
+            try:
+                cache[prompt] = _load_prompt_payload(path, runtime_pipe.device, runtime_pipe.torch_dtype)
+            except Exception:
+                log.warning("Discarding unreadable prompt-embedding cache %s", path, exc_info=True)
+            else:
+                return cache[prompt]
+        if require_cache:
+            # The text encoder was left out of the model stack on the strength of
+            # this file, so there is nothing left to fall back to.
+            raise RuntimeError(
+                f"The cached prompt embedding {path} disappeared after the stack was loaded without its text encoder."
+            )
+        produced = original_process(runtime_pipe, prompt, edit_image=None)
+        if path is not None:
+            try:
+                _store_prompt_payload(path, produced)
+            except OSError:
+                log.warning("Could not persist the prompt embedding to %s", path, exc_info=True)
+        cache[prompt] = produced
+        return produced
 
     return cached_process
 
@@ -140,11 +232,25 @@ def _cached_prompt_process(original_process: Any) -> Any:
 def _cache_static_prompt_embeddings(
     pipe: Any,
     output_params: tuple[str, ...],
+    *,
+    model_id: str | None = None,
+    require_cache: bool = False,
 ) -> bool:
-    """Memoize a prompt unit when its embedding depends only on static text."""
+    """Memoize a prompt unit when its embedding depends only on static text.
+
+    With ``model_id`` the memo is also persisted, which is what lets the next
+    container skip the text encoder entirely; without it the memo lives only as long
+    as the pipeline. ``require_cache`` says the stack was already built without a
+    text encoder, so a miss must fail loudly rather than call a model that is absent.
+    """
     for unit in pipe.units:
         if tuple(getattr(unit, "output_params", ())) == output_params:
-            unit.process = _cached_prompt_process(unit.process)
+            unit.process = _cached_prompt_process(
+                unit.process,
+                model_id=model_id,
+                output_params=output_params,
+                require_cache=require_cache,
+            )
             return True
     return False
 
@@ -163,28 +269,18 @@ def resolution_adaptive_denoise(
     denoise_min: float = 0.08,
     denoise_max: float = 0.15,
 ) -> float:
-    """Port the reference resolution-based adaptive denoise calculation.
-
-    At neutral level 5, 0.30 MP maps to ``denoise_min`` and 3.70 MP maps to
-    ``denoise_max``. Levels above or below 5 add the same asymmetric spread as the
-    reference custom node.
-    """
-    image_mp = max(1.0, float(width) * float(height)) / 1_000_000.0
-    normalized = _clamp((image_mp - 0.30) / (3.70 - 0.30), 0.0, 1.0)
-
-    minimum = float(denoise_min)
-    maximum = float(denoise_max)
-    if maximum < minimum:
-        minimum, maximum = maximum, minimum
-    denoise_range = maximum - minimum
-    base = minimum + denoise_range * normalized
-
-    level = int(adaptive_level)
-    if level >= 5:
-        offset = ((float(level) - 5.0) / 5.0) * denoise_range * 0.285714
+    """Choose the calibrated global strength from image area and operator level."""
+    low, high = sorted((float(denoise_min), float(denoise_max)))
+    megapixels = max(1.0, float(width) * float(height)) * 1e-6
+    area_fraction = _clamp((megapixels - 0.30) / 3.40, 0.0, 1.0)
+    strength_range = high - low
+    strength = low + strength_range * area_fraction
+    level_delta = float(int(adaptive_level)) - 5.0
+    if level_delta >= 0.0:
+        strength += level_delta * strength_range * (0.285714 / 5.0)
     else:
-        offset = -((5.0 - float(level)) / 4.0) * denoise_range * 0.257143
-    return _clamp(base + offset, 0.0001, 1.0)
+        strength += level_delta * strength_range * (0.257143 / 4.0)
+    return _clamp(strength, 0.0001, 1.0)
 
 
 def largest_face_denoise(
@@ -196,7 +292,7 @@ def largest_face_denoise(
     denoise_min: float = 0.05,
     denoise_max: float = 0.28,
 ) -> float:
-    """Scale face denoise from the largest face area, matching reference mode."""
+    """Choose the calibrated face strength from the largest detected face area."""
     width, height = image_size
     image_area = max(1.0, float(width) * float(height))
     largest_ratio = 0.0
@@ -205,7 +301,7 @@ def largest_face_denoise(
         largest_ratio = max(largest_ratio, box_area / image_area)
     if largest_ratio <= 0.0:
         return _clamp(base_denoise, denoise_min, denoise_max)
-    scaled = float(base_denoise) * (largest_ratio / max(1e-6, float(adaptive_ratio)))
+    scaled = float(base_denoise) * largest_ratio / max(1e-6, float(adaptive_ratio))
     return _clamp(scaled, denoise_min, denoise_max)
 
 
@@ -223,7 +319,7 @@ def _resize_to_target(image: Image.Image) -> Image.Image:
 
 
 def build_canny_control_image(image: Image.Image) -> Image.Image:
-    """Build the three-channel Canny conditioning image used by stage 1."""
+    """Build the calibrated three-channel Canny conditioning map."""
     import cv2
 
     rgb = np.asarray(image.convert("RGB"))
@@ -253,8 +349,6 @@ def build_global_kwargs(
         "seed": seed,
         "rand_device": "cpu",
         "num_inference_steps": GLOBAL_STEPS,
-        # The source graph applies ModelSamplingAuraFlow with shift=3. DiffSynth
-        # expresses the same rational sigma shift as exp(mu), so mu=log(3).
         "exponential_shift_mu": math.log(3.0),
         "blockwise_controlnet_inputs": [controlnet_input],
     }
@@ -306,7 +400,7 @@ def _expanded_box(
     *,
     factor: float = 2.5,
 ) -> tuple[int, int, int, int]:
-    """Expand a face box around its center, matching the reference crop factor."""
+    """Expand a face box around its center to include local lighting context."""
     x1, y1, x2, y2 = box
     image_width, image_height = image_size
     center_x = (x1 + x2) / 2.0
@@ -322,7 +416,13 @@ def _expanded_box(
 
 
 def _model_cache_dir() -> Path:
-    root = os.environ.get("XDG_CACHE_HOME")
+    """Where this library persists downloaded and derived model assets.
+
+    ``HF_HOME`` comes first because on a scale-to-zero runner it is the one path
+    mounted persistently; anything under a container-local cache is re-derived on
+    every request, which defeats both the YuNet download and the prompt cache.
+    """
+    root = os.environ.get("HF_HOME") or os.environ.get("XDG_CACHE_HOME")
     base = Path(root) if root else Path.home() / ".cache"
     return base / "remove-ai-watermarks"
 
@@ -461,11 +561,18 @@ def _clip_sam_masks_to_boxes(
     image_size: tuple[int, int],
 ) -> list[np.ndarray]:
     """Match Impact Pack by intersecting each SAM mask with its detector box."""
+    # Same rectangle primitive the shared fill uses, rather than a private zeros/fill
+    # copy. `dilate=0` because this box CLIPS a SAM mask -- growing it would admit the
+    # pixels the clip exists to exclude. The function-local import keeps region_eraser's
+    # module-scope cv2 off this module's import path.
+    from remove_ai_watermarks.region_eraser import boxes_to_mask
+
     width, height = image_size
     clipped: list[np.ndarray] = []
     for mask, (x1, y1, x2, y2) in zip(masks, boxes, strict=True):
-        box_mask = np.zeros((height, width), dtype=np.uint8)
-        box_mask[max(0, y1) : min(height, y2), max(0, x1) : min(width, x2)] = 255
+        # (x, y, w, h) with w = x2 - x1 keeps x + w == x2, so a negative origin clamps
+        # to the same span the explicit max/min pair produced.
+        box_mask = boxes_to_mask((height, width), [(x1, y1, x2 - x1, y2 - y1)], dilate=0)
         clipped.append(np.bitwise_and(mask.astype(np.uint8), box_mask))
     return clipped
 
@@ -519,6 +626,7 @@ class QwenZImagePipeline:
     progress_callback: Callable[[str], None] | None = None
     controlnet_conditioning_scale: float = GLOBAL_CONTROLNET_SCALE
     keep_face_models_on_device: bool | None = None
+    keep_global_models_on_device: bool | None = None
     cache_prompt_embeddings: bool = True
 
     def __post_init__(self) -> None:
@@ -535,8 +643,9 @@ class QwenZImagePipeline:
     def _require_cuda(self) -> None:
         if self.device != "cuda":
             raise RuntimeError(
-                "The qwen-zimage pipeline is CUDA-only. Its Qwen-Image-2512 and "
-                "Z-Image models do not fit the supported MPS path."
+                "The qwen-zimage pipeline is CUDA-only; there is no CPU or MPS path "
+                "for it. WatermarkRemover already refuses a non-CUDA device, so "
+                "reaching this guard means the pipeline was constructed directly."
             )
 
     def _vram_limit(self) -> float | None:
@@ -546,21 +655,54 @@ class QwenZImagePipeline:
             return max(1.0, torch.cuda.mem_get_info("cuda")[1] / (1024**3) - 0.5)
         return None
 
-    def _keep_face_models_resident(self) -> bool:
+    def _total_vram_gib(self) -> float:
+        """Card capacity for the residency gates, 0.0 when it cannot be read.
+
+        Separate from ``_vram_limit``, which answers a different question (the budget
+        handed to DiffSynth) and must stay ``None`` rather than 0.0 when unknown, so
+        an unreadable device means "no limit" there and "assume small" here.
+        """
         import torch
 
-        total_memory_gib = 0.0
         with contextlib.suppress(Exception):
-            total_memory_gib = torch.cuda.get_device_properties("cuda").total_memory / (1024**3)
+            return torch.cuda.get_device_properties("cuda").total_memory / (1024**3)
+        return 0.0
+
+    def _keep_face_models_resident(self) -> bool:
         return resolve_face_model_residency(
             self.keep_face_models_on_device,
-            total_memory_gib=total_memory_gib,
+            total_memory_gib=self._total_vram_gib(),
         )
 
-    @staticmethod
-    def _qwen_vram_config() -> dict[str, Any]:
+    def _keep_global_models_resident(self) -> bool:
+        return resolve_global_model_residency(
+            self.keep_global_models_on_device,
+            total_memory_gib=self._total_vram_gib(),
+        )
+
+    def _prompt_is_cached(self, model_id: str, output_params: tuple[str, ...], prompt: str) -> bool:
+        """Whether this stack can be built without its text encoder at all."""
+        return self.cache_prompt_embeddings and _prompt_cache_path(model_id, output_params, prompt).exists()
+
+    def _qwen_vram_config(self) -> dict[str, Any]:
         import torch
 
+        if self._keep_global_models_resident():
+            # Same fp8 storage and bf16 computation as the streaming config, but the
+            # weights never leave the GPU. Passing no "disk" anywhere is what makes
+            # this work: DiffSynth decides `disk_offload` once from `offload_dtype`,
+            # so a card large enough to hold the stack skips both the `to("meta")`
+            # drop and the DiskMap re-read entirely.
+            return {
+                "offload_dtype": torch.float8_e4m3fn,
+                "offload_device": "cuda",
+                "onload_dtype": torch.float8_e4m3fn,
+                "onload_device": "cuda",
+                "preparing_dtype": torch.float8_e4m3fn,
+                "preparing_device": "cuda",
+                "computation_dtype": torch.bfloat16,
+                "computation_device": "cuda",
+            }
         return {
             "offload_dtype": "disk",
             "offload_device": "disk",
@@ -572,6 +714,23 @@ class QwenZImagePipeline:
             "computation_device": "cuda",
         }
 
+    @classmethod
+    def _face_stage_dtype(cls) -> Any:
+        """The dtype every face-stage model loads and computes in.
+
+        Deliberately independent of ``self.torch_dtype``, which belongs to the global
+        stage. ``sdxl-zimage`` runs its global model in fp16, and inheriting that here
+        built the Z-Image modules bf16 (per the VRAM config below) while handing them
+        fp16 latents -- a Half/BFloat16 conv mismatch that crashed every face image
+        while zero-face inputs passed, so no unit test could see it.
+
+        Read by Z-Image and by SAM alike, so the whole stage moves together. SAM never
+        crashed, because it casts its own inputs and leaves through ``.float()``, but it
+        was reading the same wrong field and would re-land the bug for the next profile
+        that changes its global dtype.
+        """
+        return cls._zimage_vram_config()["computation_dtype"]
+
     @staticmethod
     def _zimage_vram_config() -> dict[str, Any]:
         import torch
@@ -604,17 +763,18 @@ class QwenZImagePipeline:
 
         self._progress("Loading Qwen-Image-2512, Lightning LoRA, and Canny ControlNet...")
         config = self._qwen_vram_config()
+        text_encoder_config = ModelConfig(
+            model_id=QWEN_IMAGE_2512_MODEL_ID,
+            origin_file_pattern="text_encoder/model*.safetensors",
+            **config,
+        )
         model_configs = [
             ModelConfig(
                 model_id=QWEN_IMAGE_2512_MODEL_ID,
                 origin_file_pattern="transformer/diffusion_pytorch_model*.safetensors",
                 **config,
             ),
-            ModelConfig(
-                model_id=QWEN_IMAGE_2512_MODEL_ID,
-                origin_file_pattern="text_encoder/model*.safetensors",
-                **config,
-            ),
+            text_encoder_config,
             ModelConfig(
                 model_id=QWEN_IMAGE_2512_MODEL_ID,
                 origin_file_pattern="vae/diffusion_pytorch_model.safetensors",
@@ -626,6 +786,10 @@ class QwenZImagePipeline:
                 **config,
             ),
         ]
+        prompt_cached = self._prompt_is_cached(QWEN_IMAGE_2512_MODEL_ID, _QWEN_PROMPT_OUTPUTS, _GLOBAL_PROMPT)
+        if prompt_cached:
+            model_configs.remove(text_encoder_config)
+            log.info("Qwen prompt embedding is cached; loading the stack without its text encoder")
         pipe = QwenImagePipeline.from_pretrained(
             torch_dtype=self.torch_dtype,
             device=self.device,
@@ -650,7 +814,9 @@ class QwenZImagePipeline:
         if self.cache_prompt_embeddings:
             _cache_static_prompt_embeddings(
                 pipe,
-                ("prompt_emb", "prompt_emb_mask"),
+                _QWEN_PROMPT_OUTPUTS,
+                model_id=QWEN_IMAGE_2512_MODEL_ID,
+                require_cache=prompt_cached,
             )
         self._qwen_pipe = (pipe, ControlNetInput)
         return self._qwen_pipe
@@ -673,26 +839,32 @@ class QwenZImagePipeline:
         self._progress("Loading Z-Image Turbo face-detail model...")
         keep_on_device = self._keep_face_models_resident()
         config = self._zimage_vram_config()
+        text_encoder_config = ModelConfig(
+            model_id=ZIMAGE_TURBO_MODEL_ID,
+            origin_file_pattern="text_encoder/*.safetensors",
+            **config,
+        )
+        model_configs = [
+            ModelConfig(
+                model_id=ZIMAGE_TURBO_MODEL_ID,
+                origin_file_pattern="transformer/*.safetensors",
+                **config,
+            ),
+            text_encoder_config,
+            ModelConfig(
+                model_id=ZIMAGE_TURBO_MODEL_ID,
+                origin_file_pattern="vae/diffusion_pytorch_model.safetensors",
+                **config,
+            ),
+        ]
+        prompt_cached = self._prompt_is_cached(ZIMAGE_TURBO_MODEL_ID, _ZIMAGE_PROMPT_OUTPUTS, _FACE_PROMPT)
+        if prompt_cached:
+            model_configs.remove(text_encoder_config)
+            log.info("Z-Image prompt embedding is cached; loading the stack without its text encoder")
         pipe = ZImagePipeline.from_pretrained(
-            torch_dtype=self.torch_dtype,
+            torch_dtype=self._face_stage_dtype(),
             device=self.device,
-            model_configs=[
-                ModelConfig(
-                    model_id=ZIMAGE_TURBO_MODEL_ID,
-                    origin_file_pattern="transformer/*.safetensors",
-                    **config,
-                ),
-                ModelConfig(
-                    model_id=ZIMAGE_TURBO_MODEL_ID,
-                    origin_file_pattern="text_encoder/*.safetensors",
-                    **config,
-                ),
-                ModelConfig(
-                    model_id=ZIMAGE_TURBO_MODEL_ID,
-                    origin_file_pattern="vae/diffusion_pytorch_model.safetensors",
-                    **config,
-                ),
-            ],
+            model_configs=model_configs,
             tokenizer_config=ModelConfig(
                 model_id=ZIMAGE_TURBO_MODEL_ID,
                 origin_file_pattern="tokenizer/",
@@ -702,7 +874,12 @@ class QwenZImagePipeline:
         if keep_on_device:
             _pin_vram_managed_models(pipe)
         if self.cache_prompt_embeddings:
-            _cache_static_prompt_embeddings(pipe, ("prompt_embeds",))
+            _cache_static_prompt_embeddings(
+                pipe,
+                _ZIMAGE_PROMPT_OUTPUTS,
+                model_id=ZIMAGE_TURBO_MODEL_ID,
+                require_cache=prompt_cached,
+            )
         self._zimage_pipe = pipe
         return pipe
 
@@ -720,7 +897,7 @@ class QwenZImagePipeline:
         processor = AutoProcessor.from_pretrained(SAM_MODEL_ID, **kwargs)
         model = AutoModelForMaskGeneration.from_pretrained(
             SAM_MODEL_ID,
-            torch_dtype=self.torch_dtype,
+            torch_dtype=self._face_stage_dtype(),
             **kwargs,
         ).to(self.device)
         model.eval()
@@ -749,7 +926,7 @@ class QwenZImagePipeline:
             )
             original_sizes = inputs["original_sizes"].clone()
             reshaped_sizes = inputs["reshaped_input_sizes"].clone()
-            inputs = _prepare_sam_inputs(inputs, self.device, self.torch_dtype)
+            inputs = _prepare_sam_inputs(inputs, self.device, self._face_stage_dtype())
             with torch.inference_mode():
                 outputs = model(**inputs, multimask_output=True)
             processed = processor.post_process_masks(
@@ -767,12 +944,13 @@ class QwenZImagePipeline:
             log.warning("SAM face-mask refinement failed (%s); using box-derived ellipse masks", exc)
             return _ellipse_masks(boxes, image.size)
 
-    def preload(self) -> None:
-        """Eagerly load both diffusion stages and the face segmentation model."""
+    def preload(self, *, global_only: bool = False) -> None:
+        """Eagerly load the mandatory stage and, by default, the face stack."""
         self._load_qwen()
-        self._load_zimage()
-        self._load_sam()
         _yunet_model_path()
+        if not global_only:
+            self._load_zimage()
+            self._load_sam()
 
     def _run_global(self, image: Image.Image, strength: float, seed: int | None) -> Image.Image:
         pipe, controlnet_input_cls = self._load_qwen()
@@ -806,7 +984,7 @@ class QwenZImagePipeline:
         scale_for_face = 768.0 / max(1, max(face_width, face_height))
         scale_for_crop = 1024.0 / max(1, max(crop_width, crop_height))
         scale = min(scale_for_face, scale_for_crop)
-        # Never shrink below the crop's current size unless the 1024 cap requires it.
+        # Never shrink below the crop's current size unless the cap requires it.
         if max(crop_width, crop_height) <= 1024:
             scale = max(1.0, scale)
         width = max(16, round(crop_width * scale / 16.0) * 16)
@@ -869,12 +1047,12 @@ class QwenZImagePipeline:
     ) -> Image.Image:
         """Execute global regeneration and masked face repair."""
         self._require_cuda()
-        seed = resolve_seed(seed, "qwen-zimage")
+        seed = resolve_seed(seed)
         global_strength = (
             resolution_adaptive_denoise(image.width, image.height) if strength is None else float(strength)
         )
         if tile and max(image.size) > tile_size:
-            from remove_ai_watermarks.noai.tiling import run_tiled
+            from remove_ai_watermarks._internal.tiling import run_tiled
 
             global_result = run_tiled(
                 lambda tile_image: self._run_global(tile_image, global_strength, seed),
@@ -892,7 +1070,7 @@ class QwenZImagePipeline:
             self._progress("No faces detected; keeping the Qwen global result.")
             return global_result
         masks = self._sam_masks(image, boxes)
-        face_strength = largest_face_denoise(boxes, image.size)
+        face_strength = largest_face_denoise(boxes, image.size) * FACE_DENOISE_SCALE
         return self._run_faces(
             image,
             global_result,

src/remove_ai_watermarks/_internal/riff.py

@@ -0,0 +1,74 @@
+"""Bounded AVI metadata reader for native TC260 AIGC labels.
+
+TC260-PG-20257A stores the label in an AVI ``LIST/INFO`` chunk whose child
+chunk ID is ``AIGC`` and whose value is the normative JSON object. The walker
+seeks over media chunks and reads only bounded metadata values.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, BinaryIO
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+from remove_ai_watermarks.metadata import MAX_TC260_VALUE_BYTES, parse_tc260_aigc_json
+
+
+def _info_payloads(
+    stream: BinaryIO,
+    start: int,
+    end: int,
+) -> tuple[bytes, ...]:
+    found: list[bytes] = []
+    position = start
+    while position + 8 <= end:
+        stream.seek(position)
+        chunk_id = stream.read(4)
+        size_raw = stream.read(4)
+        if len(chunk_id) != 4 or len(size_raw) != 4:
+            break
+        size = int.from_bytes(size_raw, "little")
+        payload_start = position + 8
+        payload_end = payload_start + size
+        if payload_end > end:
+            break
+        if chunk_id == b"AIGC" and size <= MAX_TC260_VALUE_BYTES:
+            value = stream.read(size)
+            if len(value) == size and parse_tc260_aigc_json(value) is not None:
+                found.append(value.rstrip(b"\x00 "))
+        position = payload_end + (size & 1)
+    return tuple(found)
+
+
+def tc260_aigc_payloads(path: str | Path) -> tuple[bytes, ...]:
+    """Read validated TC260 values from an AVI ``LIST/INFO/AIGC`` chunk."""
+    found: list[bytes] = []
+    try:
+        with open(path, "rb") as stream:
+            header = stream.read(12)
+            if len(header) != 12 or header[:4] != b"RIFF" or header[8:12] != b"AVI ":
+                return ()
+            stream.seek(0, 2)
+            file_size = stream.tell()
+            declared_end = min(8 + int.from_bytes(header[4:8], "little"), file_size)
+            position = 12
+            while position + 8 <= declared_end:
+                stream.seek(position)
+                chunk_id = stream.read(4)
+                size_raw = stream.read(4)
+                if len(chunk_id) != 4 or len(size_raw) != 4:
+                    break
+                size = int.from_bytes(size_raw, "little")
+                payload_start = position + 8
+                payload_end = payload_start + size
+                if payload_end > declared_end:
+                    break
+                if chunk_id == b"LIST" and size >= 4:
+                    list_type = stream.read(4)
+                    if list_type == b"INFO":
+                        found.extend(_info_payloads(stream, payload_start + 4, payload_end))
+                position = payload_end + (size & 1)
+    except OSError:
+        return ()
+    return tuple(found)

src/remove_ai_watermarks/_internal/schema.py

@@ -0,0 +1,16 @@
+"""Shared validation for versioned JSON transport contracts."""
+
+from collections.abc import Collection
+
+
+def require_schema_version(
+    value: object,
+    *,
+    contract: str,
+    supported: Collection[int],
+) -> int:
+    """Return an explicitly supported integer schema version or raise."""
+    if type(value) is not int or value not in supported:
+        versions = ", ".join(str(version) for version in sorted(supported))
+        raise ValueError(f"Unsupported {contract} schema: {value!r}; supported versions: {versions}")
+    return value

src/remove_ai_watermarks/_internal/sdxl_zimage_pipeline.py

@@ -0,0 +1,154 @@
+"""The qwen-zimage recipe with an SDXL global stage.
+
+Only the global regeneration model changes. The face stage is inherited verbatim
+from :class:`QwenZImagePipeline` -- same YuNet detection, same SAM masks, same
+Z-Image Turbo repair of the original crops, same feathered compositing -- so a
+change there cannot silently diverge between the two profiles.
+
+Three pieces cannot be shared, because they are bound to the architecture: the
+ControlNet, the four-step distillation LoRA, and the sampler. Strength is bound to
+it too, which is the part that is easy to miss: an SDXL global pass leaves SynthID
+at the strength Qwen needs. See ``watermark_profiles.SDXL_ZIMAGE_OPENAI_STRENGTH``.
+"""
+
+# Diffusers and torch expose mostly untyped tensor APIs. Keep the relaxation local
+# to this optional ML boundary.
+# pyright: reportUnknownMemberType=false, reportUnknownArgumentType=false, reportUnknownVariableType=false, reportUnknownParameterType=false, reportMissingTypeArgument=false, reportMissingTypeStubs=false, reportMissingImports=false, reportArgumentType=false, reportAssignmentType=false, reportReturnType=false, reportCallIssue=false, reportAttributeAccessIssue=false, reportPrivateUsage=false, reportPrivateImportUsage=false
+from __future__ import annotations
+
+import logging
+import math
+from dataclasses import dataclass
+from typing import Any
+
+from PIL import Image
+
+from remove_ai_watermarks._internal.qwen_zimage_pipeline import (
+    GLOBAL_STEPS,
+    QwenZImagePipeline,
+    build_canny_control_image,
+)
+from remove_ai_watermarks._internal.watermark_profiles import (
+    CONTROLNET_CANNY_MODEL,
+    SDXL_LIGHTNING_MODEL_ID,
+    SDXL_LIGHTNING_PATTERN,
+    SDXL_MODEL_ID,
+)
+
+log = logging.getLogger(__name__)
+
+SDXL_VAE_MODEL_ID = "madebyollin/sdxl-vae-fp16-fix"
+# SDXL aligns to an 8-pixel latent grid, against Qwen's 16.
+_LATENT_GRID = 8
+
+
+def sdxl_target_size(width: int, height: int) -> tuple[int, int]:
+    """Floor dimensions to SDXL's latent grid without changing aspect."""
+    return max(_LATENT_GRID, (width // _LATENT_GRID) * _LATENT_GRID), max(
+        _LATENT_GRID, (height // _LATENT_GRID) * _LATENT_GRID
+    )
+
+
+def requested_steps(effective_steps: int, strength: float) -> int:
+    """Translate "spend N denoising steps" into what Diffusers has to be asked for.
+
+    The two runtimes truncate differently and it is easy to port this wrong.
+    DiffSynth sets ``sigma_start = denoising_strength`` and then runs *every*
+    requested step across the shortened sigma range. Diffusers img2img instead
+    truncates the step *count* (``init_timestep = int(steps * strength)``), so
+    asking it for four steps at strength 0.15 runs **zero** and returns nothing but
+    a VAE round-trip. Ask for enough that ``effective_steps`` actually execute.
+    """
+    return max(1, math.ceil(effective_steps / max(float(strength), 1e-6)))
+
+
+@dataclass
+class SdxlZImagePipeline(QwenZImagePipeline):
+    """Lazy runtime for the SDXL global stage plus the inherited face stage."""
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        self._sdxl_pipe: Any = None
+
+    def _load_sdxl(self) -> Any:
+        if self._sdxl_pipe is not None:
+            return self._sdxl_pipe
+        self._require_cuda()
+        import torch
+        from diffusers import (
+            AutoencoderKL,
+            ControlNetModel,
+            EulerDiscreteScheduler,
+            StableDiffusionXLControlNetImg2ImgPipeline,
+        )
+        from huggingface_hub import hf_hub_download
+
+        self._progress("Loading SDXL, Lightning LoRA, and Canny ControlNet...")
+        token = {"token": self.hf_token} if self.hf_token else {}
+        controlnet = ControlNetModel.from_pretrained(CONTROLNET_CANNY_MODEL, torch_dtype=torch.float16, **token)
+        vae = AutoencoderKL.from_pretrained(SDXL_VAE_MODEL_ID, torch_dtype=torch.float16, **token)
+        pipe = StableDiffusionXLControlNetImg2ImgPipeline.from_pretrained(
+            SDXL_MODEL_ID,
+            controlnet=controlnet,
+            vae=vae,
+            torch_dtype=torch.float16,
+            variant="fp16",
+            add_watermarker=False,
+            **token,
+        ).to(self.device)
+        # SDXL's own four-step distillation, at the strength its authors document.
+        # The reference graph loads the Qwen LoRA at 0.8; carrying that number to a
+        # different LoRA on a different architecture would be imitation, not parity.
+        pipe.load_lora_weights(hf_hub_download(SDXL_LIGHTNING_MODEL_ID, SDXL_LIGHTNING_PATTERN, **token))
+        pipe.fuse_lora()
+        # SDXL-Lightning is distilled against trailing timestep spacing.
+        pipe.scheduler = EulerDiscreteScheduler.from_config(pipe.scheduler.config, timestep_spacing="trailing")
+        self._sdxl_pipe = pipe
+        return pipe
+
+    def preload(self, *, global_only: bool = False) -> None:
+        """Eagerly load the mandatory stage and, by default, the face stack."""
+        from remove_ai_watermarks._internal.qwen_zimage_pipeline import _yunet_model_path
+
+        self._load_sdxl()
+        _yunet_model_path()
+        if not global_only:
+            self._load_zimage()
+            self._load_sam()
+
+    def _run_global(self, image: Image.Image, strength: float, seed: int | None) -> Image.Image:
+        import torch
+
+        pipe = self._load_sdxl()
+        target = sdxl_target_size(image.width, image.height)
+        prepared = image if image.size == target else image.resize(target, Image.Resampling.LANCZOS)
+        control = build_canny_control_image(prepared)
+        steps = requested_steps(GLOBAL_STEPS, strength)
+        self._progress(f"Running SDXL Canny pass: strength={strength:.4f}, steps={GLOBAL_STEPS} of {steps}...")
+        generator = torch.Generator(device=self.device).manual_seed(seed) if seed is not None else None
+        result = pipe(
+            prompt=self._global_prompt(),
+            negative_prompt=self._global_negative(),
+            image=prepared,
+            control_image=control,
+            controlnet_conditioning_scale=float(self.controlnet_conditioning_scale),
+            strength=float(strength),
+            num_inference_steps=steps,
+            guidance_scale=1.0,
+            generator=generator,
+        ).images[0]
+        if result.size != image.size:
+            result = result.resize(image.size, Image.Resampling.LANCZOS)
+        return result.convert("RGB")
+
+    @staticmethod
+    def _global_prompt() -> str:
+        from remove_ai_watermarks._internal.qwen_zimage_pipeline import _GLOBAL_PROMPT
+
+        return _GLOBAL_PROMPT
+
+    @staticmethod
+    def _global_negative() -> str:
+        from remove_ai_watermarks._internal.qwen_zimage_pipeline import _GLOBAL_NEGATIVE
+
+        return _GLOBAL_NEGATIVE

src/remove_ai_watermarks/_internal/tiling.py

@@ -1,11 +1,11 @@
 """Sliding-window tiled diffusion for large images.
 
-The img2img / ControlNet pipeline denoises the WHOLE image in one forward pass,
-so it OOMs on MPS/GPU above ~2K (issue #10). Tiling splits the image into
-overlapping tiles -- each kept near SDXL's ~1024 training size -- regenerates
-each tile independently, and feather-blends the overlaps. The result retains the
-input's native dimensions without an explicit ``--max-resolution`` downscale, but
-it is not pixel-lossless because every tile is regenerated.
+The global stage denoises the WHOLE image in one forward pass, so it OOMs on a
+GPU above ~2K (issue #10). Tiling splits the image into overlapping tiles -- each
+kept near the ~1024 training size -- regenerates each tile independently, and
+feather-blends the overlaps. The result retains the input's native dimensions
+without an explicit ``--max-resolution`` downscale, but it is not pixel-lossless
+because every tile is regenerated.
 
 The geometry (``plan_tiles``) and the blend weighting (``feather_weights``) are
 pure functions, unit-tested without the diffusion model. ``run_tiled`` is the
@@ -100,59 +100,6 @@ def feather_weights(width: int, height: int, overlap: int) -> NDArray[Any]:
     return weights
 
 
-def feather_region_composite(
-    base: NDArray[Any],
-    regenerated: NDArray[Any],
-    box: tuple[int, int, int, int],
-    *,
-    feather: int = 64,
-) -> NDArray[Any]:
-    """Composite ``regenerated`` over ``base`` inside ``box`` only, feathering the seam.
-
-    For AI-ENHANCED composites (digitalSourceType ``compositeWithTrainedAlgorithmicMedia``):
-    the diffusion remover regenerates the whole frame, but only the AI-composited
-    REGION should change -- the rest is a real photo that must be preserved. This
-    blends the regenerated pixels in over ``box = (x, y, w, h)`` with a separable
-    linear taper of ``feather`` px at the box edges, so the result equals ``base``
-    EXACTLY outside the box and ramps smoothly (no hard seam) at the boundary.
-
-    Pure and model-free (unit-tested): ``base`` and ``regenerated`` must be the same
-    shape (H x W, or H x W x C). The output preserves ``base``'s dtype. ``feather`` is
-    clamped to half the box on each axis, so a small region still tapers symmetrically;
-    ``feather=0`` is a hard-edged paste.
-    """
-    import numpy as np
-
-    if base.shape != regenerated.shape:
-        raise ValueError(f"shape mismatch: base {base.shape} vs regenerated {regenerated.shape}")
-    h, w = base.shape[:2]
-    x, y, bw, bh = box
-    x0, y0 = max(0, x), max(0, y)
-    x1, y1 = min(w, x + bw), min(h, y + bh)
-    out = base.copy()
-    if x1 <= x0 or y1 <= y0:
-        return out  # empty / off-image box -> nothing regenerated
-
-    def taper(n: int) -> NDArray[Any]:
-        win = np.ones(n, dtype=np.float32)
-        f = min(max(feather, 0), n // 2)
-        if f > 0:
-            ramp = (np.arange(f, dtype=np.float32) + 1.0) / (f + 1.0)  # in (0, 1), 0 at the edge
-            win[:f] = ramp
-            win[n - f :] = ramp[::-1]
-        return win
-
-    rh, rw = y1 - y0, x1 - x0
-    wmap = np.outer(taper(rh), taper(rw))  # ~0 at the box edge, 1 in the interior
-    if base.ndim == 3:
-        wmap = wmap[:, :, None]
-    roi_base = base[y0:y1, x0:x1].astype(np.float32)
-    roi_gen = regenerated[y0:y1, x0:x1].astype(np.float32)
-    blended = roi_base * (1.0 - wmap) + roi_gen * wmap
-    out[y0:y1, x0:x1] = np.clip(blended, 0, 255).astype(base.dtype)
-    return out
-
-
 def run_tiled(
     generate_tile: Callable[[PILImage.Image], PILImage.Image],
     image: PILImage.Image,

src/remove_ai_watermarks/_internal/utils.py

@@ -0,0 +1,30 @@
+"""Small path helpers shared by optional image pipelines."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from remove_ai_watermarks._internal.constants import SUPPORTED_FORMATS
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+_PIL_FORMAT_BY_SUFFIX = {
+    ".jpg": "JPEG",
+    ".jpeg": "JPEG",
+    ".png": "PNG",
+}
+
+
+def is_supported_format(file_path: Path) -> bool:
+    """Return whether ``file_path`` has a supported raster suffix."""
+    return file_path.suffix.casefold() in SUPPORTED_FORMATS
+
+
+def get_image_format(file_path: Path) -> str:
+    """Return the Pillow save format used by the legacy metadata API.
+
+    The metadata writer only has specialized PNG and JPEG paths. Other accepted
+    inputs therefore use its PNG fallback, matching the established API contract.
+    """
+    return _PIL_FORMAT_BY_SUFFIX.get(file_path.suffix.casefold(), "PNG")

src/remove_ai_watermarks/_internal/watermark_profiles.py

@@ -0,0 +1,149 @@
+"""Project-owned configuration for invisible-watermark regeneration profiles.
+
+Two profiles remain, and both are CUDA-only: ``qwen-zimage`` (the default) and
+``sdxl-zimage``. The older ``controlnet``, ``sdxl``, ``qwen`` and ``default`` profiles
+were removed rather than kept as a CPU path, because none of them matched the two-stage
+recipe's face preservation and keeping them implied a quality this library no longer
+offers. Removing invisible watermarks therefore needs a CUDA device; the visible-mark
+registry and every identify path still run anywhere.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+# SDXL base is no longer a profile of its own, but it is still the global stage of
+# sdxl-zimage, so the checkpoint id stays. Named for what it is rather than
+# ``DEFAULT_MODEL_ID``: there is no user-selectable model any more, so "default"
+# implied an override that both profiles reject.
+SDXL_MODEL_ID = "stabilityai/stable-diffusion-xl-base-1.0"
+CONTROLNET_CANNY_MODEL = "xinsir/controlnet-canny-sdxl-1.0"
+
+QWEN_ZIMAGE_PROFILE = "qwen-zimage"
+SDXL_ZIMAGE_PROFILE = "sdxl-zimage"
+DEFAULT_PROFILE = QWEN_ZIMAGE_PROFILE
+PROFILE_CHOICES = (QWEN_ZIMAGE_PROFILE, SDXL_ZIMAGE_PROFILE)
+
+# The modules a real removal run needs, and the extra that installs them. Both live
+# here, in the only profile module that imports nothing heavy, because the CLI's
+# availability gate and the remover's own precondition must agree: when they drifted,
+# the CLI passed on a torch+diffusers environment and the run then died at the
+# DiffSynth face stage, telling the user to install an extra that does not contain it.
+REMOVAL_MODULES = ("torch", "diffusers", "diffsynth")
+# Shell-quoted, because this string is printed as a command the user copy-pastes.
+# Bare brackets are a glob in zsh (the macOS default shell): an unquoted
+# ``pip install remove-ai-watermarks[qwen-zimage]`` dies with "no matches found"
+# before pip ever runs -- another install hint that does not install.
+INVISIBLE_EXTRA = "'remove-ai-watermarks[qwen-zimage]'"
+
+# qwen-zimage's output already matches the input's detail level, so polishing it is a
+# no-op at best. sdxl-zimage's global pass leaves the softer output the polish exists
+# for. This is per-profile data, not a CLI concern: the flag defaults to None so that
+# "the user did not choose" stays a value rather than an inference from Click state.
+PROFILE_ADAPTIVE_POLISH = {QWEN_ZIMAGE_PROFILE: False, SDXL_ZIMAGE_PROFILE: True}
+
+SDXL_LIGHTNING_MODEL_ID = "ByteDance/SDXL-Lightning"
+SDXL_LIGHTNING_PATTERN = "sdxl_lightning_4step_lora.safetensors"
+
+# Both profiles are certified at a fixed seed because SynthID removal near the
+# strength floor is seed-dependent. The step count and CFG are not settable at all --
+# each stage owns them (``GLOBAL_STEPS`` / ``FACE_STEPS`` in qwen_zimage_pipeline).
+PROFILE_SEED = 0
+
+# sdxl-zimage runs the qwen-zimage recipe on an SDXL global stage, and strength is
+# architecture-bound: at Qwen's 0.154 an SDXL global pass leaves SynthID on a native
+# 2816x1536 Gemini original, while 0.20, 0.25 and 0.30 all read clean in the Gemini
+# app. 0.25 keeps a rung of margin over that boundary, which the historical SDXL
+# certification argues for -- it recorded 0.20 as DETECTED against Gemini on an
+# older SDXL pipeline. OpenAI is the easier oracle: the profile already cleared
+# openai.com/verify at 0.1102, so 0.15 sits above what was verified rather than on
+# it. Unknown follows Gemini, the stricter of the two.
+#
+# Unlike qwen-zimage this is a flat vendor policy rather than a resolution curve,
+# because flat values are what was measured. Every verdict above comes from a fixed
+# strength at one size; no size dependence has been established for this stage.
+SDXL_ZIMAGE_OPENAI_STRENGTH = 0.15
+SDXL_ZIMAGE_GEMINI_STRENGTH = 0.25
+SDXL_ZIMAGE_UNKNOWN_STRENGTH = SDXL_ZIMAGE_GEMINI_STRENGTH
+
+
+# sdxl-zimage picks its strength from the VENDOR (unlike qwen-zimage, which derives it
+# from image area). An unlisted or unknown vendor falls back to the Gemini value.
+_SDXL_ZIMAGE_STRENGTH_BY_VENDOR: dict[str, float] = {
+    "openai": SDXL_ZIMAGE_OPENAI_STRENGTH,
+    "google": SDXL_ZIMAGE_GEMINI_STRENGTH,
+}
+_ALIASES = {
+    "qwen_zimage": QWEN_ZIMAGE_PROFILE,
+    "sdxl_zimage": SDXL_ZIMAGE_PROFILE,
+}
+
+
+def normalize_profile(profile: str) -> str:
+    """Normalize spelling and resolve the underscore spellings."""
+    value = profile.strip().casefold()
+    return _ALIASES.get(value, value)
+
+
+def resolve_seed(seed: int | None) -> int:
+    """Keep both profiles reproducible by default."""
+    return PROFILE_SEED if seed is None else seed
+
+
+def resolve_adaptive_polish(adaptive_polish: bool | None, pipeline: str) -> bool:
+    """Return an explicit polish choice, or the profile's calibrated default."""
+    if adaptive_polish is not None:
+        return adaptive_polish
+    return PROFILE_ADAPTIVE_POLISH.get(normalize_profile(pipeline), True)
+
+
+def strength_default_help() -> str:
+    """Describe the live default policy without duplicating its values."""
+    return (
+        "profile-adaptive (qwen-zimage uses resolution-adaptive denoise; sdxl-zimage "
+        f"uses OpenAI {SDXL_ZIMAGE_OPENAI_STRENGTH} / Google {SDXL_ZIMAGE_GEMINI_STRENGTH} / "
+        f"unknown {SDXL_ZIMAGE_UNKNOWN_STRENGTH}, from the C2PA issuer)"
+    )
+
+
+def resolve_strength(
+    strength: float | None,
+    vendor: str | None = None,
+    pipeline: str | None = None,
+    *,
+    size: tuple[int, int] | None = None,
+) -> float:
+    """Resolve a user override or the calibrated policy for a profile and vendor.
+
+    Total by design. qwen-zimage picks its strength from image area rather than from
+    the vendor, so it needs ``size``; returning ``None`` for it instead would push that
+    branch onto every caller and move one of the two strength policies outside this
+    module. ``size`` is required for qwen-zimage without an explicit strength.
+    """
+    if strength is not None:
+        return strength
+    if normalize_profile(pipeline or "") == SDXL_ZIMAGE_PROFILE:
+        return _SDXL_ZIMAGE_STRENGTH_BY_VENDOR.get((vendor or "").casefold(), SDXL_ZIMAGE_UNKNOWN_STRENGTH)
+    if size is None:
+        raise ValueError("qwen-zimage resolves strength from image area, so size is required")
+    from remove_ai_watermarks._internal.qwen_zimage_pipeline import resolution_adaptive_denoise
+
+    return resolution_adaptive_denoise(*size)
+
+
+def vendor_for_strength(image_path: Path) -> Literal["openai", "google"] | None:
+    """Select the strength cohort using the input's SynthID provenance evidence."""
+    try:
+        from remove_ai_watermarks.metadata import synthid_source
+
+        evidence = (synthid_source(image_path) or "").casefold()
+    except Exception:
+        return None
+    if "google" in evidence:
+        return "google"
+    if "openai" in evidence:
+        return "openai"
+    return None

src/remove_ai_watermarks/_internal/watermark_remover.py

@@ -0,0 +1,216 @@
+"""Project-native orchestration for diffusion-based pixel regeneration."""
+
+# pyright: reportUnknownMemberType=false, reportUnknownArgumentType=false, reportUnknownVariableType=false, reportUnknownParameterType=false, reportMissingTypeArgument=false, reportMissingTypeStubs=false, reportMissingImports=false, reportArgumentType=false, reportAssignmentType=false, reportReturnType=false, reportCallIssue=false, reportIndexIssue=false, reportOperatorIssue=false, reportOptionalMemberAccess=false, reportOptionalCall=false, reportOptionalSubscript=false, reportOptionalOperand=false, reportAttributeAccessIssue=false, reportPrivateImportUsage=false, reportPrivateUsage=false, reportInvalidTypeForm=false, reportConstantRedefinition=false, reportUnnecessaryComparison=false
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+from typing import TYPE_CHECKING, Any
+
+from PIL import Image
+
+from remove_ai_watermarks._internal.watermark_profiles import (
+    DEFAULT_PROFILE,
+    INVISIBLE_EXTRA,
+    PROFILE_CHOICES,
+    REMOVAL_MODULES,
+    SDXL_ZIMAGE_PROFILE,
+    normalize_profile,
+    resolve_seed,
+    resolve_strength,
+)
+from remove_ai_watermarks.optional_deps import module_available
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+try:
+    import torch
+
+    _HAS_TORCH = True
+except ImportError:
+    torch = None  # type: ignore[assignment]
+    _HAS_TORCH = False
+
+# Probed once at import. ``torch`` is imported above rather than probed because this
+# module needs the object, not just the answer.
+_HAS_REMOVAL_MODULES = module_available(*(name for name in REMOVAL_MODULES if name != "torch"))
+
+
+def is_watermark_removal_available() -> bool:
+    """Return whether the full removal runtime can be imported."""
+    return _HAS_TORCH and _HAS_REMOVAL_MODULES
+
+
+def _ensure_watermark_deps() -> None:
+    if not is_watermark_removal_available():
+        raise ImportError(
+            f"Invisible watermark regeneration requires the 'qwen-zimage' extra: pip install {INVISIBLE_EXTRA}."
+        )
+
+
+def _has_nvidia_gpu() -> bool:
+    try:
+        subprocess.run(
+            ["nvidia-smi"],
+            check=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        return False
+    return True
+
+
+def _cuda_works() -> bool:
+    try:
+        probe = torch.tensor([1.0], device="cuda")  # type: ignore[union-attr]
+        _ = probe + probe
+    except (AssertionError, RuntimeError):
+        return False
+    return True
+
+
+def get_device() -> str:
+    """Return ``"cuda"`` when a usable CUDA backend is present, else ``"cpu"``.
+
+    Deliberately binary. Both profiles are CUDA-only, so an XPU or MPS answer would
+    only travel one frame further to the same refusal in :class:`WatermarkRemover`,
+    while costing a probe on each. ``"cpu"`` here means "no CUDA", which is exactly
+    what that refusal reports.
+    """
+    if not _HAS_TORCH:
+        return "cpu"
+    if torch.cuda.is_available() and _cuda_works():  # type: ignore[union-attr]
+        return "cuda"
+    if _has_nvidia_gpu():
+        logger.warning("NVIDIA GPU detected, but the installed PyTorch build has no working CUDA backend")
+    return "cpu"
+
+
+class WatermarkRemover:
+    """Load one regeneration profile and write a metadata-clean raster output."""
+
+    def __init__(
+        self,
+        device: str | None = None,
+        progress_callback: Callable[[str], None] | None = None,
+        hf_token: str | None = None,
+        pipeline: str = DEFAULT_PROFILE,
+        controlnet_conditioning_scale: float = 1.0,
+        cpu_offload: bool = False,
+    ) -> None:
+        self.model_profile = normalize_profile(pipeline)
+        if self.model_profile not in PROFILE_CHOICES:
+            raise ValueError(f"Unsupported pipeline '{pipeline}'. Use one of: {', '.join(PROFILE_CHOICES)}.")
+        # There is no ``model_id`` parameter and no ``model_id`` attribute: each
+        # profile pins a fixed model stack, and the dtype below is bound to that
+        # stack's weights. Both used to be constructor overrides that existed only to
+        # be rejected or to break the run, and the attribute only existed to echo the
+        # rejected value back.
+        _ensure_watermark_deps()
+        selected_device = (device or get_device()).casefold()
+        self.device = get_device() if selected_device == "auto" else selected_device
+        # CUDA is a precondition of the object, not of the run. Both profiles raise on
+        # any other device, so accepting one here only defers a guaranteed failure to
+        # model-load time, several layers down and under the wrong profile's name.
+        if self.device != "cuda":
+            raise ValueError(
+                f"Invisible-watermark removal is CUDA-only, so '{self.device}' cannot run it. "
+                "Both remaining profiles need an NVIDIA GPU. Visible-mark removal and "
+                "every identify command still run on CPU."
+            )
+
+        if self.model_profile == SDXL_ZIMAGE_PROFILE:
+            # SDXL ships fp16 weights and an fp16-safe VAE; bf16 would give up the
+            # variant without buying anything on this architecture.
+            self.torch_dtype = torch.float16  # type: ignore[union-attr]
+        else:
+            self.torch_dtype = torch.bfloat16  # type: ignore[union-attr]
+
+        self.cpu_offload = cpu_offload
+        self.controlnet_conditioning_scale = controlnet_conditioning_scale
+        self.hf_token = hf_token or os.environ.get("HF_TOKEN")
+        self._progress_callback = progress_callback
+        self._qwen_zimage_pipeline: Any = None
+
+    def preload(self, *, global_only: bool = False) -> None:
+        """Materialize the selected model stack before the first request."""
+        self._load_qwen_zimage_pipeline().preload(global_only=global_only)
+
+    def _load_qwen_zimage_pipeline(self) -> Any:
+        if self._qwen_zimage_pipeline is None:
+            if self.model_profile == SDXL_ZIMAGE_PROFILE:
+                from remove_ai_watermarks._internal.sdxl_zimage_pipeline import (
+                    SdxlZImagePipeline as _Pipeline,
+                )
+            else:
+                from remove_ai_watermarks._internal.qwen_zimage_pipeline import (
+                    QwenZImagePipeline as _Pipeline,
+                )
+
+            self._qwen_zimage_pipeline = _Pipeline(
+                device=self.device,
+                torch_dtype=self.torch_dtype,
+                hf_token=self.hf_token,
+                progress_callback=self._progress_callback,
+                controlnet_conditioning_scale=self.controlnet_conditioning_scale,
+                keep_face_models_on_device=False if self.cpu_offload else None,
+                keep_global_models_on_device=False if self.cpu_offload else None,
+            )
+        return self._qwen_zimage_pipeline
+
+    def _write_output(self, image: Image.Image, output_path: Path) -> None:
+        import numpy as np
+
+        from remove_ai_watermarks import image_io
+
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        bgr = np.ascontiguousarray(np.asarray(image.convert("RGB"))[:, :, ::-1])
+        if not image_io.imwrite(str(output_path), bgr):
+            image.save(output_path)
+        from remove_ai_watermarks.metadata import remove_ai_metadata
+
+        remove_ai_metadata(output_path, output_path, keep_standard=True)
+
+    def remove_watermark(
+        self,
+        image_path: Path,
+        output_path: Path | None = None,
+        strength: float | None = None,
+        seed: int | None = None,
+        vendor: str | None = None,
+        tile: bool = False,
+        tile_size: int = 1024,
+        tile_overlap: int = 128,
+    ) -> Path:
+        """Regenerate image pixels and write the result without AI metadata.
+
+        Step count and CFG are not parameters. Each stage of both profiles is a
+        distilled schedule that owns its own, so the only thing a caller-supplied
+        value could do is break the run or be rejected.
+        """
+        if not image_path.exists():
+            raise FileNotFoundError(f"Image not found: {image_path}")
+        destination = output_path or image_path
+        with Image.open(image_path) as opened:
+            source = opened.convert("RGB")
+
+        resolved_strength = resolve_strength(strength, vendor, self.model_profile, size=source.size)
+        if not 0.0 <= resolved_strength <= 1.0:
+            raise ValueError(f"Strength must be between 0.0 and 1.0, got {resolved_strength}")
+
+        result = self._load_qwen_zimage_pipeline().run(
+            source,
+            strength=resolved_strength,
+            seed=resolve_seed(seed),
+            tile=tile,
+            tile_size=tile_size,
+            tile_overlap=tile_overlap,
+        )
+        self._write_output(result, destination)
+        return destination

src/remove_ai_watermarks/_text_mark_engine.py

@@ -132,7 +132,7 @@ class TextMarkConfig:
     # Which image dimension the mark's size and margins scale with. VENDOR-SPECIFIC,
     # measured, not assumed -- see TextMarkEngine.scale_base. "short" = min(h, w), "width" = w.
     scale_basis: Literal["short", "width"] = "width"
-    # Scale rungs ``_tophat_best`` sweeps (the detection comb). PER-MARK: a vendor
+    # Scale rungs ``_ladder_best`` sweeps (the detection comb). PER-MARK: a vendor
     # whose stamp sizes do not land on the shared 3-rung comb carries its own ladder
     # (measured for 千问, whose marks sit in two size modes ~1.6x apart -- one fraction
     # on 3 rungs covers only ~75% of them). Densifying the SHARED ladder for everyone
@@ -156,7 +156,6 @@ class TextMarkLocation:
     y: int
     w: int
     h: int
-    is_fallback: bool = True  # geometry anchor (no template match) -> always True for now
 
     @property
     def bbox(self) -> tuple[int, int, int, int]:
@@ -171,6 +170,33 @@ class TextMarkDetection:
     confidence: float = 0.0
     region: tuple[int, int, int, int] = (0, 0, 0, 0)
     coverage: float = 0.0  # fraction of the box occupied by glyph pixels
+    # ROI-local (x0, y0, x1, y1) of the ladder sweep's best match, in the LOCATED BOX's
+    # coordinates. None for the ``binary`` front-end (it runs no sweep) and whenever no
+    # rung matched. ``footprint_mask`` bounds the fill with it, so carrying it here is
+    # what stops the mask path re-running a sweep the detector already ran.
+    match_box: tuple[int, int, int, int] | None = None
+    # The trust level this detection was taken at, mirroring detect()'s ``provenance``.
+    # ``footprint_mask`` reuses a threaded detection only when it matches the STRICT
+    # level its own re-detect would have used -- see TextMarkEngine._strict_detection.
+    provenance: bool = False
+
+
+@dataclass(frozen=True)
+class TextMarkScan:
+    """The trust-level-BLIND half of text-mark detection, reusable across both levels.
+
+    ``loc is None`` means detection stopped before any scan (empty or too-small image).
+    ``score is None`` means the binary front-end fell below its coverage gate, which is
+    a verdict of "not detected, confidence 0.0" without consulting the rival margin.
+    """
+
+    loc: TextMarkLocation | None
+    box: NDArray[Any] | None  # box-sized binary glyph mask
+    base: int  # scale_base(image)
+    frame: tuple[int, int] = (0, 0)  # (h, w) of the scanned image
+    coverage: float = 0.0
+    score: float | None = None
+    match_box: tuple[int, int, int, int] | None = None
 
 
 # Alpha / silhouette templates, cached per asset name. This shared cache lets every
@@ -307,6 +333,28 @@ class TextMarkEngine:
 
     # ── Locate ──────────────────────────────────────────────────────────
 
+    def _roi_fields(
+        self, image: NDArray[Any], loc: TextMarkLocation
+    ) -> tuple[NDArray[Any], NDArray[Any], NDArray[Any]]:
+        """``(luma, saturation, local_background)`` for the located box, all float32.
+
+        The ROI is normalized to 3-channel BGR first (grayscale / BGRA would break
+        ``axis=2``).
+
+        Local background model: a strong Gaussian blur (sigma ~ box height); the white
+        top-hat (``luma - local_bg``) lights up bright thin strokes regardless of the
+        absolute background level.
+
+        The callers each keep their own ``bh < 16 or bw < 16`` guard: they return three
+        different sentinels for a degenerate ROI, so the check cannot move in here.
+        """
+        x, y, bw, bh = loc.bbox
+        roi = image_io.to_bgr(image[y : y + bh, x : x + bw]).astype(np.float32)
+        luma = roi.mean(axis=2)
+        sat = roi.max(axis=2) - roi.min(axis=2)
+        sigma = max(4.0, bh * 0.4)  # 0.4 factor and 4.0 floor are calibrated; do not retune
+        return luma, sat, cv2.GaussianBlur(luma, (0, 0), sigmaX=sigma, sigmaY=sigma)
+
     def tophat_response(self, image: NDArray[Any], loc: TextMarkLocation) -> NDArray[Any] | None:
         """The CONTINUOUS white top-hat in the located box -- the glyph signal, unbinarized.
 
@@ -329,26 +377,48 @@ class TextMarkEngine:
         Kept per-mark (``detect_frontend``) rather than switched globally, because a
         front-end change must be measured per mark before it ships.
         """
+        return self._residual_response(image, loc, absolute=False)
+
+    def _residual_response(self, image: NDArray[Any], loc: TextMarkLocation, *, absolute: bool) -> NDArray[Any] | None:
+        """Max-normalized uint8 local-luma residual in the located box, saturation-weighted.
+
+        ``absolute=False`` keeps only the POSITIVE side -- the white top-hat, for a mark
+        always rendered brighter than its background. ``absolute=True`` takes the
+        magnitude, for a renderer that switches between light-on-dark and dark-on-light
+        while preserving one silhouette; a one-polarity top-hat misses the latter.
+        """
         c = self.config
-        x, y, bw, bh = loc.bbox
+        _x, _y, bw, bh = loc.bbox
         if bh < 16 or bw < 16:
             return None
-        roi = image_io.to_bgr(image[y : y + bh, x : x + bw]).astype(np.float32)
-        luma = roi.mean(axis=2)
-        sat = roi.max(axis=2) - roi.min(axis=2)
-        sigma = max(4.0, bh * 0.4)
-        tophat = luma - cv2.GaussianBlur(luma, (0, 0), sigmaX=sigma, sigmaY=sigma)
-        resp = np.clip(tophat, 0, None) * (sat < c.max_saturation)
+        luma, sat, local_bg = self._roi_fields(image, loc)
+        residual = luma - local_bg
+        resp = (np.abs(residual) if absolute else np.clip(residual, 0, None)) * (sat < c.max_saturation)
         peak = float(resp.max())
         if peak <= 1e-6:
             return None
         return (resp / peak * 255).astype(np.uint8)
 
-    def _tophat_best(
+    def _detect_response(self, image: NDArray[Any], loc: TextMarkLocation) -> NDArray[Any] | None:
+        """The uint8 image the ladder sweep correlates the silhouette against, chosen by
+        ``TextMarkConfig.detect_frontend``. ``binary`` runs no sweep and never reaches here."""
+        frontend = self.config.detect_frontend
+        if frontend == "gray":
+            x, y, bw, bh = loc.bbox
+            if bh < 16 or bw < 16:
+                return None
+            return cv2.cvtColor(image_io.to_bgr(image[y : y + bh, x : x + bw]), cv2.COLOR_BGR2GRAY)
+        if frontend == "contrast":
+            return self._residual_response(image, loc, absolute=True)
+        if frontend == "tophat":
+            return self._residual_response(image, loc, absolute=False)
+        raise ValueError(f"{frontend!r} has no ladder response (binary runs no sweep)")
+
+    def _ladder_best(
         self, image: NDArray[Any], loc: TextMarkLocation
     ) -> tuple[float, tuple[int, int, int, int] | None]:
-        """Best TM_CCOEFF_NORMED of a soft template against the continuous response, and
-        the ROI-local box (x0, y0, x1, y1) where that best match sits.
+        """Best TM_CCOEFF_NORMED of the mark's silhouette against its front-end response,
+        and the ROI-local box (x0, y0, x1, y1) where that best match sits.
 
         Sweeps the mark's scale ladder: the nominal glyph size is derived from the mark's
         geometry, but a vendor re-rasterization shifts it by a few percent and the
@@ -359,10 +429,15 @@ class TextMarkEngine:
         detection, the box bounds the fill. Sharing it is deliberate: the standing rule is
         that detection and the mask use the same front-end, and the way that rule was last
         broken was a drift between two separate implementations. One method makes the drift
-        impossible instead of merely discouraged.
+        impossible instead of merely discouraged -- which is why the three continuous
+        front-ends (tophat / contrast / gray) sweep here rather than in a copy each.
+
+        Tie-breaking is load-bearing: the ``0.0`` seed plus the STRICT ``>`` means the
+        EARLIEST ladder rung wins a tie, and a sweep whose maximum is not above 0.0
+        returns no box at all.
         """
         c = self.config
-        resp = self.tophat_response(image, loc)
+        resp = self._detect_response(image, loc)
         sil = self._glyph_silhouette()
         if resp is None or sil is None:
             return (0.0, None)
@@ -374,90 +449,12 @@ class TextMarkEngine:
             gh = max(4, int(c.alpha_height_frac * base * scale))
             if gw >= resp.shape[1] or gh >= resp.shape[0]:
                 continue
-            tmpl = cv2.resize(sil, (gw, gh), interpolation=cv2.INTER_AREA).astype(np.float32)
-            if c.template_blur > 0:
-                tmpl = cv2.GaussianBlur(tmpl, (0, 0), sigmaX=c.template_blur, sigmaY=c.template_blur)
-            result = cv2.matchTemplate(resp, tmpl.astype(np.uint8), cv2.TM_CCOEFF_NORMED)
-            _, score, _, top_left = cv2.minMaxLoc(result)
-            if score > best_score:
-                tx, ty = int(top_left[0]), int(top_left[1])
-                best_score, best_box = float(score), (tx, ty, tx + gw - 1, ty + gh - 1)
-        return (best_score, best_box)
-
-    def _tophat_score(self, image: NDArray[Any], loc: TextMarkLocation) -> float:
-        """The detection score alone -- the box the removal mask needs is discarded here."""
-        return self._tophat_best(image, loc)[0]
-
-    def _contrast_best(
-        self, image: NDArray[Any], loc: TextMarkLocation
-    ) -> tuple[float, tuple[int, int, int, int] | None]:
-        """Best silhouette match against the absolute local-luma residual.
-
-        Unlike the white top-hat, this response is polarity-independent: the same
-        watermark can be lighter or darker than its local background. Detection and
-        removal share the returned box, preserving the front-end parity contract.
-        """
-        c = self.config
-        x, y, bw, bh = loc.bbox
-        if bh < 16 or bw < 16:
-            return (0.0, None)
-        roi = image_io.to_bgr(image[y : y + bh, x : x + bw]).astype(np.float32)
-        luma = roi.mean(axis=2)
-        sat = roi.max(axis=2) - roi.min(axis=2)
-        sigma = max(4.0, bh * 0.4)
-        response = np.abs(luma - cv2.GaussianBlur(luma, (0, 0), sigmaX=sigma, sigmaY=sigma))
-        response *= sat < c.max_saturation
-        peak = float(response.max())
-        sil = self._glyph_silhouette()
-        if peak <= 1e-6 or sil is None:
-            return (0.0, None)
-        response = (response / peak * 255).astype(np.uint8)
-        base = self.scale_base(image)
-        best_score = 0.0
-        best_box: tuple[int, int, int, int] | None = None
-        for scale in c.ladder:
-            gw = max(c.min_gw, int(c.alpha_width_frac * base * scale))
-            gh = max(4, int(c.alpha_height_frac * base * scale))
-            if gw >= response.shape[1] or gh >= response.shape[0]:
-                continue
-            template = cv2.resize(sil, (gw, gh), interpolation=cv2.INTER_AREA)
-            result = cv2.matchTemplate(response, template, cv2.TM_CCOEFF_NORMED)
-            _, score, _, top_left = cv2.minMaxLoc(result)
-            if score > best_score:
-                tx, ty = int(top_left[0]), int(top_left[1])
-                best_score, best_box = float(score), (tx, ty, tx + gw - 1, ty + gh - 1)
-        return (best_score, best_box)
-
-    def _gray_best(self, image: NDArray[Any], loc: TextMarkLocation) -> tuple[float, tuple[int, int, int, int] | None]:
-        """Best TM_CCOEFF_NORMED of the silhouette against the raw GRAYSCALE ROI, and
-        the ROI-local box (x0, y0, x1, y1) of that best match.
-
-        Mirrors :meth:`_tophat_best` (same ladder sweep, same one-method contract so
-        detection and the removal mask can never drift), but skips the top-hat
-        entirely: the RunningHub mark is a faint mid-gray text the top-hat's
-        background subtraction suppresses to clean-arm levels, while raw gray NCC
-        separates (see ``TextMarkConfig.detect_frontend``). Contrast-DEPENDENT by
-        construction, so the gate must be picked against the clean arm, which is
-        what ``scripts/vendor_mark_calibrate.py`` does.
-        """
-        c = self.config
-        x, y, bw, bh = loc.bbox
-        if bh < 16 or bw < 16:
-            return (0.0, None)
-        roi = cv2.cvtColor(image_io.to_bgr(image[y : y + bh, x : x + bw]), cv2.COLOR_BGR2GRAY)
-        sil = self._glyph_silhouette()
-        if sil is None:
-            return (0.0, None)
-        base = self.scale_base(image)
-        best_score = 0.0
-        best_box: tuple[int, int, int, int] | None = None
-        for scale in c.ladder:
-            gw = max(c.min_gw, int(c.alpha_width_frac * base * scale))
-            gh = max(4, int(c.alpha_height_frac * base * scale))
-            if gw >= roi.shape[1] or gh >= roi.shape[0]:
-                continue
             tmpl = cv2.resize(sil, (gw, gh), interpolation=cv2.INTER_AREA)
-            result = cv2.matchTemplate(roi, tmpl, cv2.TM_CCOEFF_NORMED)
+            if c.detect_frontend == "tophat" and c.template_blur > 0:
+                tmpl = cv2.GaussianBlur(
+                    tmpl.astype(np.float32), (0, 0), sigmaX=c.template_blur, sigmaY=c.template_blur
+                ).astype(np.uint8)
+            result = cv2.matchTemplate(resp, tmpl, cv2.TM_CCOEFF_NORMED)
             _, score, _, top_left = cv2.minMaxLoc(result)
             if score > best_score:
                 tx, ty = int(top_left[0]), int(top_left[1])
@@ -512,7 +509,7 @@ class TextMarkEngine:
         y = min(margin_b, max(0, h - wm_h)) if c.corner == "tl" else max(0, h - margin_b - wm_h)
         wm_w = min(wm_w, w - x)
         wm_h = min(wm_h, h - y)
-        return TextMarkLocation(x=x, y=y, w=wm_w, h=wm_h, is_fallback=True)
+        return TextMarkLocation(x=x, y=y, w=wm_w, h=wm_h)
 
     # ── Mask ────────────────────────────────────────────────────────────
 
@@ -571,10 +568,33 @@ class TextMarkEngine:
         the mark's own ``provenance_ncc_factor`` to recover a faint or slightly
         re-rendered mark (per-mark, not shared -- see _DEFAULT_PROVENANCE_NCC_FACTOR).
         """
+        scan = self._scan(image)
+        return self._verdict(scan, provenance=provenance)
+
+    def detect_both(self, image: NDArray[Any] | None) -> tuple[TextMarkDetection, TextMarkDetection]:
+        """``(strict, relaxed)`` from ONE scan of the image.
+
+        ``provenance`` scales the acceptance THRESHOLD and nothing else -- the locate
+        box, the glyph mask, the coverage and the front-end ladder score are computed
+        identically at either trust level. Two ``detect`` calls therefore ran the same
+        expensive sweep twice to reach two verdicts, which is what the arbiter's
+        perception pass did for every mark on every image.
+
+        Returns two DISTINCT objects: subclasses demote a verdict by mutating it.
+        """
+        scan = self._scan(image)
+        return self._verdict(scan, provenance=False), self._verdict(scan, provenance=True)
+
+    def _scan(self, image: NDArray[Any] | None) -> TextMarkScan:
+        """Everything in detection that does not depend on the trust level.
+
+        Per-CALL only, never memoized on ``self``: ``remove_auto_marks`` re-invokes each
+        engine on a progressively cleaned frame inside one process, so a cached scan
+        would answer for the wrong pixels.
+        """
         c = self.config
-        det = TextMarkDetection()
         if image is None or image.size == 0:
-            return det
+            return TextMarkScan(None, None, 0)
         # Guard against the small-image NCC-noise false positive (see
         # _MIN_DETECT_SHORT_SIDE): an icon/thumbnail is too small to carry a real
         # text label, and the degraded few-pixel template spuriously correlates.
@@ -585,57 +605,57 @@ class TextMarkEngine:
                 min(image.shape[:2]),
                 _MIN_DETECT_SHORT_SIDE,
             )
-            return det
+            return TextMarkScan(None, None, 0)
         loc = self.locate(image)
         box = self.extract_mask(image, loc)  # box-sized mask (== old full-frame cropped to bbox)
         _x, _y, bw, bh = loc.bbox
         coverage = float((box > 0).sum()) / float(max(1, bw * bh))
-        det.region = loc.bbox
-        det.coverage = coverage
-        if c.detect_frontend == "tophat":
-            # The continuous front-end does not depend on the binarized blob, so the
-            # coverage gate (a blob-area heuristic) does not apply to it.
-            score = self._tophat_score(image, loc)
-            threshold = c.detect_ncc_threshold * (c.provenance_ncc_factor if provenance else 1.0)
-            det.confidence = score
-            det.detected = score >= threshold and self._rival_margin_ok(score, box, self.scale_base(image))
-            logger.debug("%s detect (tophat): ncc=%.2f thr=%.2f detected=%s", c.name, score, threshold, det.detected)
+        base = self.scale_base(image)
+        match_box: tuple[int, int, int, int] | None = None
+        if c.detect_frontend == "binary":
+            # The coverage gate is a blob-AREA heuristic, so it applies only to the
+            # front-end that binarizes; the continuous ones never build a blob. Below
+            # the gate the detection stays at confidence 0.0 and the rival margin is
+            # never consulted, so the score stays None here.
+            score = self._template_match_score(box, base) if coverage >= c.detect_min_coverage else None
+        else:
+            score, match_box = self._ladder_best(image, loc)
+        return TextMarkScan(loc, box, base, frame=image.shape[:2], coverage=coverage, score=score, match_box=match_box)
+
+    def _verdict(self, scan: TextMarkScan, *, provenance: bool) -> TextMarkDetection:
+        """Apply the trust-level-dependent tail to a scan, as a fresh result object."""
+        c = self.config
+        det = TextMarkDetection(provenance=provenance)
+        if scan.loc is None or scan.box is None:
             return det
-        if c.detect_frontend == "gray":
-            # Same no-coverage-gate reasoning as tophat: the gray front-end never
-            # binarizes, so a blob-area heuristic does not apply to it either.
-            score = self._gray_best(image, loc)[0]
-            threshold = c.detect_ncc_threshold * (c.provenance_ncc_factor if provenance else 1.0)
-            det.confidence = score
-            det.detected = score >= threshold and self._rival_margin_ok(score, box, self.scale_base(image))
-            logger.debug("%s detect (gray): ncc=%.2f thr=%.2f detected=%s", c.name, score, threshold, det.detected)
+        det.region = scan.loc.bbox
+        det.coverage = scan.coverage
+        det.match_box = scan.match_box
+        if scan.score is None:  # binary front-end below the coverage gate
             return det
-        if c.detect_frontend == "contrast":
-            score = self._contrast_best(image, loc)[0]
-            threshold = c.detect_ncc_threshold * (c.provenance_ncc_factor if provenance else 1.0)
-            det.confidence = score
-            det.detected = score >= threshold and self._rival_margin_ok(score, box, self.scale_base(image))
-            logger.debug(
-                "%s detect (contrast): ncc=%.2f thr=%.2f detected=%s",
-                c.name,
-                score,
-                threshold,
-                det.detected,
-            )
-            return det
-        if coverage >= c.detect_min_coverage:
-            score = self._template_match_score(box, self.scale_base(image))
-            threshold = c.detect_ncc_threshold * (c.provenance_ncc_factor if provenance else 1.0)
-            det.confidence = score
-            det.detected = score >= threshold and self._rival_margin_ok(score, box, self.scale_base(image))
-            logger.debug(
-                "%s detect: coverage=%.3f ncc=%.2f thr=%.2f detected=%s",
-                c.name,
-                coverage,
-                score,
-                threshold,
-                det.detected,
-            )
+        threshold = c.detect_ncc_threshold * (c.provenance_ncc_factor if provenance else 1.0)
+        det.confidence = scan.score
+        # Short-circuit is load-bearing: _rival_margin_ok scores every rival template
+        # and logs its own rejection line, so it must stay unevaluated below threshold.
+        det.detected = scan.score >= threshold and self._rival_margin_ok(scan.score, scan.box, scan.base)
+        logger.debug(
+            "%s detect (%s): coverage=%.3f ncc=%.2f thr=%.2f detected=%s",
+            c.name,
+            c.detect_frontend,
+            scan.coverage,
+            scan.score,
+            threshold,
+            det.detected,
+        )
+        return self._post_gate(det, scan)
+
+    def _post_gate(self, det: TextMarkDetection, scan: TextMarkScan) -> TextMarkDetection:
+        """Per-mark demotion applied after the shared threshold, for both trust levels.
+
+        OVERRIDABLE. It lives here rather than in a ``detect`` override so a mark's gate
+        cannot be silently skipped by the single-pass ``detect_both`` path -- which is
+        exactly what happened while the anchor demotions were ``detect`` overrides.
+        """
         return det
 
     # ── Inpaint footprint (for the inpaint-fallback removal path) ────────
@@ -645,8 +665,132 @@ class TextMarkEngine:
     # to mask. A real strip covers hundreds of pixels.
     _MIN_GLYPH_PIXELS = 20
 
+    def _strict_detection(self, image: NDArray[Any], detection: TextMarkDetection | None) -> TextMarkDetection:
+        """The STRICT detection the footprint is bounded by.
+
+        A threaded detection is reused only when it was taken at the same strict level
+        this method would have used itself. A provenance-RELAXED detection is NOT
+        reused: a strict re-detect can demote a mark the relaxed gate accepted, which
+        for a continuous front-end means no mask at all. That is a MEASURED difference,
+        not a refactor, so the strict semantics stay.
+
+        Reuse is safe against ``remove_auto_marks`` chaining marks on a progressively
+        cleaned frame: the registry re-detects on that same cleaned array before
+        threading (``KnownMark.localize``), so a threaded detection is never stale.
+        """
+        if detection is not None and not detection.provenance:
+            return detection
+        return self.detect(image)  # polymorphic: a subclass gate must still apply
+
+    def _geometry_rect(self, loc: TextMarkLocation, frame: tuple[int, int]) -> tuple[int, int, int, int]:
+        """The whole locate box, clamped to the frame -- the ``force`` footprint."""
+        bx, by, bw, bh = loc.bbox
+        h, w = frame
+        return (bx, by, min(w, bx + bw), min(h, by + bh))
+
+    def _extend_match_box(
+        self, box: tuple[int, int, int, int], loc: TextMarkLocation, frame: tuple[int, int]
+    ) -> tuple[int, int, int, int]:
+        """Grow an ROI-local box into the absolute fill rectangle by a symmetric pad.
+
+        OVERRIDABLE, and the override contract is specifically the DETECTOR'S MATCH BOX:
+        a mark whose removable footprint reaches beyond what the NCC localizes -- Baidu's
+        flat white tag right of the text run, LibLibAI's triangle logo left of the
+        wordmark -- supplies its own extension here and inherits the rest of the
+        footprint path. The blob-bbox branch never routes through an override.
+        """
+        gx0, gy0, gx1, gy1 = box
+        bx, by, _bw, bh = loc.bbox
+        h, w = frame
+        pad = max(4, int(0.10 * bh))
+        return (
+            max(0, bx + gx0 - pad),
+            max(0, by + gy0 - pad),
+            min(w, bx + gx1 + 1 + pad),
+            min(h, by + gy1 + 1 + pad),
+        )
+
+    def _footprint_rect(
+        self,
+        image: NDArray[Any],
+        loc: TextMarkLocation,
+        *,
+        force: bool,
+        detection: TextMarkDetection | None,
+    ) -> tuple[int, int, int, int] | None:
+        """Default footprint policy: the binary glyph blob's bbox, else the detector's
+        own match box for the front-ends that under-segment, else the geometry box
+        under ``force``.
+
+        The gray front-end exists for marks the top-hat under-segments, so the binary
+        blob is NOT authoritative there: trusting it first bounded the fill by a PARTIAL
+        blob (the faint head glyphs dropped out) and left the leftmost "Runni" of
+        "RunningHub AI生成" unremoved (2026-07-22).
+
+        A dark-on-light Yuanbao mark has no WHITE top-hat blob at all, so the contrast
+        front-end is bounded by the polarity-independent detector's match box too.
+
+        A tophat mark found only by the CONTINUOUS front-end has no binary glyph blob to
+        bound, so the mask came back empty and removal was a silent no-op while
+        ``identify`` still reported the mark. Use the DETECTOR'S OWN best-match box: the
+        correlation already located the mark at a position and scale, and thresholding
+        the response was a strictly worse proxy for that. An earlier fix thresholded the
+        max-normalized uint8 response at 0.5 -- which selects every non-zero pixel, not
+        "half the peak" as its comment claimed -- and filled ~120% of the corner box on
+        textured frames (measured: whole corner vs 58.7% for the match box, both
+        detector-clean). Gated on an actual detection: on a clean corner the box would
+        be spurious.
+        """
+        ys, xs = np.where(self.extract_mask(image, loc) > 0)
+        blob = (
+            (int(xs.min()), int(ys.min()), int(xs.max()), int(ys.max())) if xs.size >= self._MIN_GLYPH_PIXELS else None
+        )
+        frontend = self.config.detect_frontend
+        if frontend in ("gray", "contrast"):
+            det = self._strict_detection(image, detection)
+            box = det.match_box if det.detected else blob
+        elif blob is not None:
+            box = blob
+        elif frontend == "tophat":
+            det = self._strict_detection(image, detection)
+            box = det.match_box if det.detected else None
+        else:
+            box = None
+        if box is not None:
+            return self._extend_match_box(box, loc, image.shape[:2])
+        return self._geometry_rect(loc, image.shape[:2]) if force else None
+
+    def _match_box_rect(
+        self,
+        image: NDArray[Any],
+        loc: TextMarkLocation,
+        *,
+        force: bool,
+        detection: TextMarkDetection | None,
+    ) -> tuple[int, int, int, int] | None:
+        """Footprint policy for a mark whose fill must be bounded by the DETECTOR's match
+        box and never by the binary glyph blob.
+
+        Baidu's white tag has a flat interior a top-hat cannot answer, and LibLibAI's
+        blob bleeds up into background structure; in both cases the blob bbox is
+        measurably wrong and the NCC match box is right. ``force`` takes priority here,
+        unlike the default policy: a ``--no-detect`` caller named the mark, so the whole
+        geometry box is the honest footprint.
+        """
+        if force:
+            return self._geometry_rect(loc, image.shape[:2])
+        det = self._strict_detection(image, detection)
+        if not det.detected or det.match_box is None:
+            return None
+        return self._extend_match_box(det.match_box, loc, image.shape[:2])
+
     def footprint_mask(
-        self, image: NDArray[Any], *, force: bool = False, dilate: int | None = None
+        self,
+        image: NDArray[Any] | None,
+        *,
+        force: bool = False,
+        dilate: int | None = None,
+        detection: TextMarkDetection | None = None,
     ) -> NDArray[Any] | None:
         """Full-frame uint8 mask (255 = mark) of the mark footprint, for the shared
         fill removal path (cv2 / MI-GAN / LaMa), or None if no glyph is found.
@@ -663,6 +807,10 @@ class TextMarkEngine:
 
         With ``force`` and no glyph found, falls back to the whole geometry box (the
         ``--no-detect`` path). The caller gates on detection.
+
+        ``detection`` is the caller's already-computed detection, threaded in so the
+        footprint does not re-run a sweep the detector already ran. See
+        :meth:`_strict_detection` for when it is reused.
         """
         if image is None or image.size == 0:
             return None  # guard before to_bgr (cvtColor raises on an empty Mat); mirror detect()
@@ -671,46 +819,10 @@ class TextMarkEngine:
         if h < 32 or w < 64:
             return None
         loc = self.locate(image)
-        bx, by, bw, bh = loc.bbox
-        glyph = self.extract_mask(image, loc)  # box-sized, 255 = glyph
-        ys, xs = np.where(glyph > 0)
-        box: tuple[int, int, int, int] | None = None
-        if self.config.detect_frontend == "gray" and self.detect(image).detected:
-            # The gray front-end exists for marks the top-hat under-segments, so the
-            # binary blob is NOT authoritative here: trusting it first bounded the
-            # fill by a PARTIAL blob (the faint head glyphs dropped out) and left the
-            # leftmost "Runni" of "RunningHub AI生成" unremoved (2026-07-22). Use the
-            # detector's own best-match box, same as the tophat faint path below.
-            _, box = self._gray_best(image, loc)
-        elif self.config.detect_frontend == "contrast" and self.detect(image).detected:
-            # A dark-on-light Yuanbao mark has no WHITE top-hat blob at all. Bound
-            # the fill by the polarity-independent detector's own match box.
-            _, box = self._contrast_best(image, loc)
-        elif xs.size >= self._MIN_GLYPH_PIXELS:
-            box = (int(xs.min()), int(ys.min()), int(xs.max()), int(ys.max()))
-        elif self.config.detect_frontend == "tophat" and self.detect(image).detected:
-            # A mark found only by the CONTINUOUS front-end has no binary glyph blob to
-            # bound, so the mask came back empty and removal was a silent no-op while
-            # `identify` still reported the mark while removal left it untouched.
-            # Use the DETECTOR'S OWN best-match box: the correlation already located the
-            # mark at a position and scale, and thresholding the response was a strictly
-            # worse proxy for that. An earlier fix thresholded the max-normalized uint8
-            # response at 0.5 -- which selects every non-zero pixel, not "half the peak" as
-            # its comment claimed -- and filled ~120% of the corner box on textured frames
-            # (measured: whole corner vs 58.7% for the match box, both detector-clean).
-            # Gated on an actual detection: on a clean corner the box would be spurious.
-            _, box = self._tophat_best(image, loc)
-        if box is not None:
-            gx0, gy0, gx1, gy1 = box
-            pad = max(4, int(0.10 * bh))
-            rx1 = max(0, bx + gx0 - pad)
-            rx2 = min(w, bx + gx1 + 1 + pad)
-            ry1 = max(0, by + gy0 - pad)
-            ry2 = min(h, by + gy1 + 1 + pad)
-        elif force:
-            rx1, ry1, rx2, ry2 = bx, by, min(w, bx + bw), min(h, by + bh)
-        else:
+        rect = self._footprint_rect(image, loc, force=force, detection=detection)
+        if rect is None:
             return None
+        rx1, ry1, rx2, ry2 = rect
         if rx1 >= rx2 or ry1 >= ry2:
             return None
         # Rectangular footprint + dilation is exactly region_eraser.boxes_to_mask (the
@@ -718,5 +830,5 @@ class TextMarkEngine:
         # zeros/fill/MORPH_ELLIPSE-dilate here.
         from remove_ai_watermarks import region_eraser
 
-        d = dilate if dilate is not None else max(3, int(0.02 * bw))
+        d = dilate if dilate is not None else max(3, int(0.02 * loc.w))
         return region_eraser.boxes_to_mask((h, w), [(rx1, ry1, rx2 - rx1, ry2 - ry1)], dilate=d)

src/remove_ai_watermarks/api.py

@@ -16,11 +16,14 @@ Imports stay lazy (inside the functions), so ``import remove_ai_watermarks`` is
 
 from __future__ import annotations
 
+from contextlib import suppress
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     from numpy.typing import NDArray
 
     from remove_ai_watermarks.watermark_registry import Backend, Sensitivity
@@ -40,8 +43,17 @@ def visible_provenance(source: str | Path) -> frozenset[str]:
     """Vendor keys that the file's local metadata confirms, the evidence that drives
     the ``auto`` sensitivity (relaxing a corroborated mark's detection trust gate).
 
-    Mapping: a Google/Gemini C2PA issuer -> ``"gemini"``; a China-AIGC (TC260) label
-    -> ``"doubao"``/``"jimeng"``; a ``samsung_genai`` marker -> ``"samsung"``.
+    Mapping: a Google/Gemini C2PA issuer -> ``"gemini"``; a ``samsung_genai`` marker ->
+    ``"samsung"``; a China-AIGC (TC260) label -> the vendor its ``ContentProducer``
+    names (``KnownMark.tc260_producer_codes``), falling back to ByteDance's two products
+    when the producer is absent or unmapped.
+
+    The TC260 label itself says only "this is AI", so it used to relax Doubao and
+    Jimeng on EVERY China-AIGC image -- including one carrying a Qwen or Kling mark,
+    where relaxing the wrong pair is pure false-positive risk and the mark actually
+    present never reached the relaxed gate its own ``provenance_ncc_factor`` was
+    calibrated for. The producer code identifies the signing entity, so it can.
+
     Best-effort: any read error yields an empty set (no relaxation). Metadata-only, so
     it never loads cv2/torch.
     """
@@ -52,19 +64,33 @@ def visible_provenance(source: str | Path) -> frozenset[str]:
         from remove_ai_watermarks import identify
 
         rep = identify.identify(path, check_visible=False, check_invisible=False)
-        signal_names = {signal.name for signal in rep.signals}
-        keys: set[str] = set()
-        platform = (rep.platform or "").lower()
-        if "google" in platform or "gemini" in platform:
-            keys.add("gemini")
-        if "aigc" in signal_names:
-            keys |= {"doubao", "jimeng"}
-        if "samsung_genai" in signal_names:
-            keys.add("samsung")
-        return frozenset(keys)
+        return _provenance_from_report(rep, path)
     return frozenset()
 
 
+def _tc260_vendors(path: Path) -> frozenset[str]:
+    """Vendor keys a TC260 label confirms, from its ``ContentProducer`` identity.
+
+    An absent, unreadable or unmapped producer falls back to the historical pair rather
+    than to nothing: the caller has already established that the AIGC signal fired, so
+    the image IS China-AIGC labelled, and dropping to no relaxation would lose the
+    detections the fallback recovers today. The re-read is deliberately isolated -- a
+    failure here must narrow the answer, never discard the rest of the provenance.
+    """
+    import contextlib
+
+    from remove_ai_watermarks._internal.constants import TC260_FALLBACK_VENDORS
+
+    with contextlib.suppress(Exception):
+        from remove_ai_watermarks.metadata import aigc_label, uscc_of
+        from remove_ai_watermarks.watermark_registry import tc260_producer_vendors
+
+        producer = (aigc_label(path) or {}).get("ContentProducer", "")
+        if producer and (vendor := tc260_producer_vendors().get(uscc_of(producer))):
+            return frozenset({vendor})
+    return TC260_FALLBACK_VENDORS
+
+
 def _load_visible_input(source: str | Path | NDArray[Any]) -> _VisibleInput:
     """Normalize a path/array source without making the public operation stateful."""
     if not isinstance(source, (str, Path)):
@@ -177,3 +203,477 @@ def remove_visible(
             write_noop=write_noop,
         )
     return result, removed
+
+
+# ── The three-stage image pipeline (visible -> invisible -> metadata) ──
+# This is the `all` / `batch` pipeline. It lived only in cli.py, written twice with
+# divergences, so a library caller could not run the flagship path at all. The CLI is
+# now a thin wrapper: it builds the options, prints the stage lines through
+# `progress`, and turns the outcome into console text and an exit code.
+
+
+@dataclass(frozen=True)
+class InvisibleOptions:
+    """The invisible stage's knobs, as one value instead of a dozen parameters.
+
+    ENGINE KNOBS ONLY, under the engine's own names and defaults, so a bare
+    ``InvisibleOptions()`` behaves exactly like calling the engine with no arguments.
+    The engine takes them across TWO callables -- ``__init__`` for the ones that shape
+    the loaded stack, ``remove_watermark`` for the per-image ones -- so this is not a
+    splat-through bag; ``_run_invisible`` forwards each field to the right one.
+    ``TestInvisibleOptionsMirrorTheEngine`` compares the signatures field by field with
+    no exception table to maintain: a decision made before the engine runs, like
+    ``force``, is a parameter of ``remove_all`` next to ``backend`` and ``sensitivity``,
+    not a knob smuggled in here.
+
+    Immutable so a batch can build it once and reuse it across every image while the
+    engine itself is cached separately.
+    """
+
+    strength: float | None = None
+    pipeline: str = "qwen-zimage"
+    seed: int | None = None
+    hf_token: str | None = None
+    humanize: float = 0.0
+    unsharp: float = 0.0
+    adaptive_polish: bool | None = None
+    max_resolution: int = 0
+    controlnet_conditioning_scale: float = 1.0
+    cpu_offload: bool = False
+    tile: bool = False
+    tile_size: int = 1024
+    tile_overlap: int = 128
+
+
+# What the invisible stage did. "unavailable" is the one outcome the caller must
+# surface loudly: the file looks processed but still carries the watermark.
+InvisibleOutcome = Literal["removed", "no-signal", "unavailable"]
+
+
+@dataclass(frozen=True)
+class RemoveAllResult:
+    """Outcome of :func:`remove_all` -- what each stage actually did."""
+
+    output: Path
+    visible_label: str | None  # the removed mark(s), or None when nothing fired
+    invisible: InvisibleOutcome
+
+
+class MetadataStripIncomplete(RuntimeError):
+    """AI metadata survived the strip, so no output was produced.
+
+    Raised BEFORE the final write, deliberately: the contract is that an incomplete
+    strip leaves nothing on disk rather than an AI-readable file the caller might ship.
+    """
+
+    def __init__(self, surviving: set[str]) -> None:
+        self.surviving = surviving
+        super().__init__(f"AI metadata survived the strip: {', '.join(sorted(surviving))}")
+
+
+class _SourceEvidence:
+    """One metadata extraction per source file, serving every stage of one call.
+
+    ``remove_all`` asks the same file two provenance questions -- which vendor the
+    metadata confirms (for the visible pass) and whether an invisible target exists
+    (for the scrub gate). Both start from the same file-backed extraction, and running
+    them independently paid for it twice.
+
+    Per-CALL only, never module-level: the pipeline REWRITES its input in place on some
+    paths (``batch`` with the output directory equal to the input), so a holder that
+    outlived one call would answer from pre-write evidence. The individual metadata
+    probes are memoized on content, which is what makes that safe -- this holder only
+    removes the remaining assembly work.
+
+    Every accessor fails safe exactly as the function it replaces does: an extraction or
+    verdict error yields no provenance (no relaxation) and an invisible target of True
+    (scrub rather than skip).
+    """
+
+    __slots__ = ("_evidence", "_extracted", "_path")
+
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        self._extracted = False
+        self._evidence: Any | None = None
+
+    def _extract(self) -> Any | None:
+        if not self._extracted:
+            self._extracted = True
+            with suppress(Exception):
+                from remove_ai_watermarks.identify import extract_provenance_evidence
+
+                self._evidence = extract_provenance_evidence(self._path)
+        return self._evidence
+
+    def visible_provenance(self) -> frozenset[str]:
+        """Vendor keys the metadata confirms; empty on any failure (no relaxation)."""
+        evidence = self._extract()
+        if evidence is None:
+            return frozenset()
+        # The suppress spans the VERDICT and the mapping, not just the extraction --
+        # `visible_provenance` fails safe as a whole, and a raise here would escape as a
+        # traceback where the old code returned an empty set.
+        with suppress(Exception):
+            from remove_ai_watermarks.identify import identify_from_evidence
+
+            report = identify_from_evidence(evidence)
+            return _provenance_from_report(report, self._path)
+        return frozenset()
+
+    def has_invisible_target(self) -> bool:
+        """Whether a diffusion target exists. True on any failure -- see the fail-safe
+        note on ``identify.has_invisible_target``: leaving a watermark on a paid removal
+        is worse than over-regenerating a clean image."""
+        evidence = self._extract()
+        if evidence is None:
+            return True
+        try:
+            from remove_ai_watermarks.identify import identify_from_evidence
+
+            report = identify_from_evidence(evidence, image_path=self._path, check_invisible=True)
+        except Exception:
+            return True
+        return bool(report.ai_from_metadata)
+
+
+def _provenance_from_report(report: Any, path: Path) -> frozenset[str]:
+    """Map an already-built report to the vendor keys it confirms.
+
+    Shared by :func:`visible_provenance` and the evidence holder so the two cannot
+    drift; which evidence confirms which mark is data on the registry row.
+    """
+    from remove_ai_watermarks.watermark_registry import known_marks
+
+    signal_names = {signal.name for signal in report.signals}
+    platform = (report.platform or "").lower()
+    keys: set[str] = set()
+    aigc = False
+    for mark in known_marks():
+        if any(token in platform for token in mark.provenance_platform_tokens):
+            keys.add(mark.key)
+        if "aigc" in mark.provenance_signals and "aigc" in signal_names:
+            aigc = True
+        elif any(name in signal_names for name in mark.provenance_signals):
+            keys.add(mark.key)
+    if aigc:
+        # The TC260 label is vendor-agnostic: which of its marks it confirms comes from
+        # the producer identity, not from the signal firing.
+        keys |= _tc260_vendors(path)
+    return frozenset(keys)
+
+
+def remove_all(
+    source: str | Path,
+    output: str | Path,
+    *,
+    backend: Backend = "auto",
+    sensitivity: Sensitivity = "auto",
+    invisible: InvisibleOptions | None = None,
+    force: bool = False,
+    engine: Any | None = None,
+    progress: Callable[[str, str], None] | None = None,
+) -> RemoveAllResult:
+    """Remove visible marks, the invisible watermark, and AI metadata, in that order.
+
+    Stages are chained through a file in the SYSTEM temp dir, not next to ``output``:
+    the point of staging is that the user never sees a partial output file during a long
+    model download, and writing the partial next to the final defeats that.
+
+    ``force`` scrubs even when no invisible watermark is locally detectable. It sits
+    here rather than in ``InvisibleOptions`` because it decides WHETHER the engine runs,
+    which is settled before the engine is built; the options carry only what the engine
+    itself takes.
+
+    ``engine`` accepts an already-constructed ``InvisibleEngine`` so a batch can build
+    the model once; leave it None to construct one per call.
+
+    ``progress`` receives ``(stage, detail)`` per step -- ``stage`` is one of
+    ``visible`` / ``invisible`` / ``metadata`` and ``detail`` is a stable token, not
+    prose: the caller owns the wording. The invisible stage reports its
+    :data:`InvisibleOutcome`, plus a ``strength=<value>`` line before it runs.
+
+    Raises :class:`MetadataStripIncomplete` before writing anything when AI metadata
+    survives, and ``OSError`` when the output cannot be written.
+    """
+    import os
+    import tempfile
+
+    from remove_ai_watermarks import image_io, watermark_registry
+    from remove_ai_watermarks.metadata import strip_and_verify
+
+    def say(stage: str, detail: str) -> None:
+        if progress is not None:
+            progress(stage, detail)
+
+    opts = invisible if invisible is not None else InvisibleOptions()
+    src, out = Path(source), Path(output)
+    watermark_registry.validate_sensitivity(sensitivity)
+
+    image, alpha = image_io.read_bgr_and_alpha(src)
+    if image is None:
+        raise ValueError(f"Could not read image: {src}")
+
+    # One metadata extraction for the whole pipeline: the visible pass asks which
+    # vendor is confirmed and the scrub gate asks whether a target exists, and both
+    # start from the same evidence.
+    evidence = _SourceEvidence(src)
+
+    tmp_fd, tmp_name = tempfile.mkstemp(suffix=src.suffix)
+    os.close(tmp_fd)
+    staged = Path(tmp_name)
+    try:
+        # ── 1. Visible marks ──
+        result, removed = watermark_registry.remove_auto_marks(
+            image,
+            sensitivity=sensitivity,
+            provenance=evidence.visible_provenance(),
+            backend=backend,
+        )
+        visible_label = ", ".join(removed) if removed else None
+        say("visible", visible_label or "")
+        if not image_io.write_bgr_with_alpha(staged, result, alpha):
+            raise OSError(f"failed to write the staged intermediate: {staged}")
+
+        # ── 2. Invisible watermark ──
+        outcome = _run_invisible(src, staged, staged, opts, engine, say, evidence, force)
+
+        # ── 3. AI metadata ──
+        # Read the pristine ORIGINAL for provenance above and the STAGED file here:
+        # the visible pass has already dropped this file's C2PA.
+        _, leftover = strip_and_verify(staged, staged)
+        if leftover:
+            # Before the write, on purpose -- see MetadataStripIncomplete.
+            raise MetadataStripIncomplete(set(leftover))
+        say("metadata", "stripped")
+
+        # The invisible stage (and the cv2.IMREAD_COLOR paths under it) drops alpha, so
+        # re-attach the ORIGINAL alpha plane unchanged for transparent formats.
+        final_bgr, _ = image_io.read_bgr_and_alpha(staged)
+        if final_bgr is None:
+            raise OSError(f"failed to read back the staged intermediate: {staged}")
+        out.parent.mkdir(parents=True, exist_ok=True)
+        if not image_io.write_bgr_with_alpha(out, final_bgr, alpha):
+            raise OSError(f"failed to write output (is the destination writable?): {out}")
+    finally:
+        if staged.exists():
+            staged.unlink()
+    return RemoveAllResult(out, visible_label, outcome)
+
+
+def _run_invisible(
+    vendor_source: Path,
+    in_path: Path,
+    out_path: Path,
+    opts: InvisibleOptions,
+    engine: Any | None,
+    say: Callable[[str, str], None],
+    evidence: _SourceEvidence,
+    force: bool,
+) -> InvisibleOutcome:
+    """Run, or deliberately skip, the diffusion scrub.
+
+    ``vendor_source`` is the PRISTINE original: the staged/output file has already lost
+    its C2PA to the visible pass, so gating or resolving the vendor from it would always
+    read as "no signal" and "unknown vendor". ``in_path``/``out_path`` are what the
+    engine reads and writes (the same staged file for ``remove_all``, input->output for
+    an invisible-only batch).
+    """
+    from remove_ai_watermarks.invisible_engine import is_available
+
+    if not is_available():
+        say("invisible", "unavailable")
+        return "unavailable"
+    if not (force or evidence.has_invisible_target()):
+        say("invisible", "no-signal")
+        return "no-signal"
+
+    from remove_ai_watermarks._internal.watermark_profiles import resolve_strength, vendor_for_strength
+
+    vendor = vendor_for_strength(vendor_source)
+    # Report the strength the engine will actually execute, resolved the same way it
+    # resolves it, so the reported value cannot drift from the executed one.
+    with suppress(Exception):
+        from PIL import Image
+
+        with Image.open(vendor_source) as probe:
+            say("invisible", f"strength={resolve_strength(opts.strength, vendor, opts.pipeline, size=probe.size)}")
+
+    if engine is None:
+        from remove_ai_watermarks.invisible_engine import InvisibleEngine
+
+        engine = InvisibleEngine(
+            pipeline=opts.pipeline,
+            hf_token=opts.hf_token,
+            progress_callback=lambda message: say("invisible", message),
+            controlnet_conditioning_scale=opts.controlnet_conditioning_scale,
+            cpu_offload=opts.cpu_offload,
+        )
+    engine.remove_watermark(
+        image_path=in_path,
+        output_path=out_path,
+        strength=opts.strength,
+        seed=opts.seed,
+        humanize=opts.humanize,
+        unsharp=opts.unsharp,
+        adaptive_polish=opts.adaptive_polish,
+        max_resolution=opts.max_resolution,
+        vendor=vendor,
+        tile=opts.tile,
+        tile_size=opts.tile_size,
+        tile_overlap=opts.tile_overlap,
+    )
+    say("invisible", "removed")
+    return "removed"
+
+
+BatchMode = Literal["all", "visible", "metadata", "invisible"]
+
+
+@dataclass(frozen=True)
+class BatchSummary:
+    """Per-directory outcome of :func:`remove_batch`."""
+
+    processed: int
+    failed: int
+    # Files whose invisible watermark was left in place because the GPU extra is
+    # missing. Non-empty means the outputs LOOK processed but still carry it.
+    invisible_unavailable: list[Path]
+    errors: list[tuple[Path, str]]
+
+
+def remove_batch(
+    directory: str | Path,
+    output_dir: str | Path,
+    *,
+    mode: BatchMode = "all",
+    backend: Backend = "auto",
+    sensitivity: Sensitivity = "auto",
+    invisible: InvisibleOptions | None = None,
+    force: bool = False,
+    engine: Any | None = None,
+    progress: Callable[[Path, str, str], None] | None = None,
+) -> BatchSummary:
+    """Run one removal ``mode`` over every supported image in ``directory``.
+
+    Never raises for a single bad image: a per-file failure is counted and recorded in
+    ``BatchSummary.errors`` so one unreadable file cannot abandon the rest of the
+    directory. ``force`` and ``engine`` are threaded straight through, so a caller that
+    passes a constructed ``InvisibleEngine`` loads the model once for the whole run.
+
+    ``progress`` receives ``(path, stage, detail)``. Every image ends with exactly one
+    terminal stage -- ``done`` or ``failed`` -- whatever the mode does in between, so a
+    caller driving a progress bar can advance on that alone.
+    """
+    from remove_ai_watermarks._internal.utils import is_supported_format
+
+    src_dir, out_dir = Path(directory), Path(output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    def say(path: Path, stage: str, detail: str) -> None:
+        if progress is not None:
+            progress(path, stage, detail)
+
+    processed = failed = 0
+    unavailable: list[Path] = []
+    errors: list[tuple[Path, str]] = []
+    for img_path in sorted(p for p in src_dir.iterdir() if is_supported_format(p)):
+        out_path = out_dir / img_path.name
+        try:
+            outcome = _run_batch_one(img_path, out_path, mode, backend, sensitivity, invisible, force, engine, say)
+        except Exception as exc:
+            failed += 1
+            errors.append((img_path, str(exc)))
+            say(img_path, "failed", str(exc))
+            continue
+        processed += 1
+        if outcome == "unavailable":
+            unavailable.append(img_path)
+        # Exactly one terminal event per image, in every mode: a caller's progress bar
+        # advances on this and nothing else. Keying it off a mode-specific stage line
+        # left `visible` and `metadata` runs sitting at 0% for the whole batch.
+        say(img_path, "done", outcome or "")
+    return BatchSummary(processed, failed, unavailable, errors)
+
+
+def _run_batch_one(
+    img_path: Path,
+    out_path: Path,
+    mode: BatchMode,
+    backend: Backend,
+    sensitivity: Sensitivity,
+    invisible: InvisibleOptions | None,
+    force: bool,
+    engine: Any | None,
+    say: Callable[[Path, str, str], None],
+) -> InvisibleOutcome | None:
+    """One image, one mode. Returns the invisible outcome when that stage ran."""
+    from remove_ai_watermarks import image_io
+    from remove_ai_watermarks.metadata import strip_and_verify
+
+    if mode == "all":
+        result = remove_all(
+            img_path,
+            out_path,
+            backend=backend,
+            sensitivity=sensitivity,
+            invisible=invisible,
+            force=force,
+            engine=engine,
+            progress=lambda stage, detail: say(img_path, stage, detail),
+        )
+        return result.invisible
+
+    # NOTE on holders in batch: `out_path` may EQUAL `img_path` (nothing forbids
+    # `-o <the input directory>`), and the visible stage rewrites it. So each stage that
+    # asks the file a provenance question builds its OWN holder, after any write that
+    # precedes it. One holder spanning the write would answer the invisible gate from
+    # pre-write evidence and scrub a file that today is correctly skipped.
+    if mode == "visible":
+        # Deliberately NOT `remove_visible`: its no-op branch copies the original bytes
+        # through when nothing was removed, which is right for a single lossless call
+        # and wrong here. A batch must produce every output through the one writer, so a
+        # failed write RAISES and the run is counted and exits non-zero -- a read-only
+        # output directory once produced zero files and still exited 0 (Tier E).
+        # Always read the ORIGINAL: a stale out_path from a previous run must not be
+        # re-processed as if it were the input.
+        from remove_ai_watermarks import watermark_registry
+
+        image, alpha = image_io.read_bgr_and_alpha(img_path)
+        if image is None:
+            raise ValueError(f"Could not read image: {img_path}")
+        result, _ = watermark_registry.remove_auto_marks(
+            image,
+            sensitivity=sensitivity,
+            provenance=visible_provenance(img_path),
+            backend=backend,
+        )
+        if not image_io.write_bgr_with_alpha(out_path, result, alpha):
+            raise OSError(f"failed to write output (is the destination writable?): {out_path}")
+        return None
+
+    if mode == "metadata":
+        _, leftover = strip_and_verify(img_path, out_path)
+        if leftover:
+            raise MetadataStripIncomplete(set(leftover))
+        return None
+
+    # invisible-only: no preceding visible pass, so out_path does not exist yet, and
+    # the input IS the pristine original for both the gate and the vendor probe.
+    outcome = _run_invisible(
+        img_path,
+        img_path,
+        out_path,
+        invisible if invisible is not None else InvisibleOptions(),
+        engine,
+        lambda stage, detail: say(img_path, stage, detail),
+        _SourceEvidence(img_path),
+        force,
+    )
+    if not out_path.exists():
+        # Keep the output directory COMPLETE even when the pixels are deliberately
+        # left alone; a hole the caller cannot see is worse than an unchanged copy.
+        src_bgr, src_alpha = image_io.read_bgr_and_alpha(img_path)
+        if src_bgr is None or not image_io.write_bgr_with_alpha(out_path, src_bgr, src_alpha):
+            raise OSError(f"failed to copy input through to output: {out_path}")
+    return outcome

src/remove_ai_watermarks/baidu_engine.py

@@ -30,11 +30,14 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from remove_ai_watermarks import _text_mark_engine
-from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+from remove_ai_watermarks._text_mark_engine import (
+    TextMarkConfig,
+    TextMarkDetection,
+    TextMarkEngine,
+    TextMarkLocation,
+)
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from numpy.typing import NDArray
 
 # Locate geometry as a fraction of the image SHORT side (measured basis). The
@@ -100,79 +103,51 @@ _CONFIG = TextMarkConfig(
     provenance_ncc_factor=1.0,
 )
 
-BaiduDetection = TextMarkDetection
-
 
 def _alpha_template() -> NDArray[Any] | None:
     """The bundled Baidu alpha template (float [0,1]), or None."""
     return _text_mark_engine.load_alpha_template(_CONFIG.asset_name)
 
 
-def _glyph_silhouette() -> NDArray[Any] | None:
-    """Binary "百度" silhouette (255 = glyph) from the alpha map, or None."""
-    return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
-
-
-def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
-    """TM_CCOEFF_NORMED of the Baidu glyph silhouette against ``box_mask``."""
-    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
-
-
 class BaiduEngine(TextMarkEngine):
     """Detect/localize the visible Baidu "百度 AI生成" mark (bottom-right; localize -> fill)."""
 
     def __init__(self) -> None:
         super().__init__(_CONFIG)
 
-    def footprint_mask(
-        self, image: NDArray[Any] | None, *, force: bool = False, dilate: int | None = None
-    ) -> NDArray[Any] | None:
-        """Full-frame mask of the WHOLE mark (text run + the pill tag to its right).
+    def _footprint_rect(
+        self,
+        image: NDArray[Any],
+        loc: TextMarkLocation,
+        *,
+        force: bool,
+        detection: TextMarkDetection | None,
+    ) -> tuple[int, int, int, int] | None:
+        """Bound the fill by the detector's match box, never by the binary glyph blob.
 
         The base class's blob-bbox footprint UNDERCOVERS this mark: the white tag's
         flat interior gives no top-hat response (a top-hat answers edges, not flats),
         so the blob ends at the text run and the fill leaves the tag's right half as
         a ghost (measured 2026-07-22 on the 768x1024 cohort frame: blob bbox x
-        632..746 vs the tag ending ~758). The layout is measured and fixed -- the
-        text run is at the left of the locate box, the tag runs to the corner -- so
-        the footprint is the detector's match box extended RIGHT to the corner.
+        632..746 vs the tag ending ~758).
         """
-        if image is None or image.size == 0:
-            return None
+        return self._match_box_rect(image, loc, force=force, detection=detection)
 
-        from remove_ai_watermarks import image_io, region_eraser
+    def _extend_match_box(
+        self, box: tuple[int, int, int, int], loc: TextMarkLocation, frame: tuple[int, int]
+    ) -> tuple[int, int, int, int]:
+        """Extend the match box RIGHT to the corner end of the locate box.
 
-        image = image_io.to_bgr(image)
-        h, w = image.shape[:2]
-        if h < 32 or w < 64:
-            return None
-        loc = self.locate(image)
+        The layout is measured and fixed: the text run is at the left of the locate
+        box and the tag runs to the corner, so the mark's right edge is the box's.
+        """
+        gx0, gy0, _gx1, gy1 = box
         bx, by, bw, bh = loc.bbox
-        if force:
-            rx1, ry1, rx2, ry2 = bx, by, min(w, bx + bw), min(h, by + bh)
-        else:
-            if not self.detect(image).detected:
-                return None
-            _, box = self._tophat_best(image, loc)
-            if box is None:
-                return None
-            gx0, gy0, _gx1, gy1 = box
-            pad = max(4, int(0.15 * bh))
-            rx1 = max(0, bx + gx0 - pad)
-            ry1 = max(0, by + gy0 - pad)
-            rx2 = min(w, bx + bw)  # the tag runs to the corner end of the box
-            ry2 = min(h, by + gy1 + 1 + pad)
-        if rx1 >= rx2 or ry1 >= ry2:
-            return None
-        d = dilate if dilate is not None else max(3, int(0.02 * bw))
-        return region_eraser.boxes_to_mask((h, w), [(rx1, ry1, rx2 - rx1, ry2 - ry1)], dilate=d)
-
-
-def load_image_bgr(path: str | Path) -> NDArray[Any]:
-    """Read an image as BGR ndarray (helper for scripts/tests)."""
-    from remove_ai_watermarks import image_io
-
-    img = image_io.imread(path)
-    if img is None:
-        raise FileNotFoundError(f"Failed to read image: {path}")
-    return img
+        h, w = frame
+        pad = max(4, int(0.15 * bh))
+        return (
+            max(0, bx + gx0 - pad),
+            max(0, by + gy0 - pad),
+            min(w, bx + bw),  # the tag runs to the corner end of the box
+            min(h, by + gy1 + 1 + pad),
+        )

src/remove_ai_watermarks/doubao_engine.py

@@ -23,11 +23,9 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from remove_ai_watermarks import _text_mark_engine
-from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkEngine
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from numpy.typing import NDArray
 
 # Locate geometry as a fraction of image WIDTH (the mark scales with width, anchored
@@ -96,9 +94,6 @@ _CONFIG = TextMarkConfig(
     min_gw=8,
 )
 
-# Doubao-specific aliases for the shared detection result/engine.
-DoubaoDetection = TextMarkDetection
-
 
 def _alpha_template() -> NDArray[Any] | None:
     """The bundled Doubao alpha template (float [0,1]), or None."""
@@ -120,13 +115,3 @@ class DoubaoEngine(TextMarkEngine):
 
     def __init__(self) -> None:
         super().__init__(_CONFIG)
-
-
-def load_image_bgr(path: str | Path) -> NDArray[Any]:
-    """Read an image as BGR ndarray (helper for scripts/tests)."""
-    from remove_ai_watermarks import image_io
-
-    img = image_io.imread(path)
-    if img is None:
-        raise FileNotFoundError(f"Failed to read image: {path}")
-    return img

src/remove_ai_watermarks/dwt_dct.py

@@ -0,0 +1,97 @@
+"""DWT-DCT decoder compatible with invisible-watermark's ``dwtDct`` path.
+
+Derived from ShieldMnt/invisible-watermark ``imwatermark/maxDct.py`` (MIT),
+trimmed to the matrix path used by Stable Diffusion, SDXL, and FLUX.
+
+Copyright (c) 2021 ShieldMnt
+
+The complete upstream license is distributed in
+``licenses/invisible-watermark-MIT.txt``.
+"""
+
+# pyright: reportUnknownMemberType=false, reportUnknownArgumentType=false, reportUnknownVariableType=false, reportMissingTypeStubs=false
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import cv2
+import numpy as np
+import pywt
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+_DEFAULT_SCALES = (0, 36, 36)
+_DEFAULT_BLOCK = 4
+
+
+class _DecodeMaxDct:
+    """Extract frequency-domain bits using the upstream matrix algorithm."""
+
+    def __init__(
+        self,
+        wm_lengths: tuple[int, ...],
+        scales: tuple[int, int, int] = _DEFAULT_SCALES,
+        block: int = _DEFAULT_BLOCK,
+    ) -> None:
+        self._wm_lengths = wm_lengths
+        self._scales = scales
+        self._block = block
+
+    def decode(self, bgr: NDArray[Any]) -> dict[int, NDArray[Any]]:
+        row, col, _channels = bgr.shape
+        yuv = cv2.cvtColor(bgr, cv2.COLOR_BGR2YUV)
+
+        scores_by_length = {wm_len: ([0] * wm_len, [0] * wm_len) for wm_len in self._wm_lengths}
+        for channel in range(2):
+            if self._scales[channel] <= 0:
+                continue
+            ca1, _detail = pywt.dwt2(yuv[: row // 4 * 4, : col // 4 * 4, channel], "haar")
+            self._decode_frame(ca1, self._scales[channel], scores_by_length)
+
+        return {
+            wm_len: np.asarray(sums) * 255 > np.asarray(counts) * 127
+            for wm_len, (sums, counts) in scores_by_length.items()
+        }
+
+    def _decode_frame(
+        self,
+        frame: NDArray[Any],
+        scale: int,
+        scores_by_length: dict[int, tuple[list[int], list[int]]],
+    ) -> None:
+        row, col = frame.shape
+        bit_index = 0
+        for i in range(row // self._block):
+            for j in range(col // self._block):
+                block = frame[
+                    i * self._block : i * self._block + self._block,
+                    j * self._block : j * self._block + self._block,
+                ]
+                inferred = self._infer_bit(block, scale)
+                for wm_len, (sums, counts) in scores_by_length.items():
+                    bucket = bit_index % wm_len
+                    sums[bucket] += inferred
+                    counts[bucket] += 1
+                bit_index += 1
+
+    def _infer_bit(self, block: NDArray[Any], scale: int) -> int:
+        position = int(np.argmax(np.abs(block.flatten()[1:]))) + 1
+        i, j = position // self._block, position % self._block
+        value = abs(float(block[i][j]))
+        return int((value % scale) > 0.5 * scale)
+
+
+def decode_dwt_dct(bgr: NDArray[Any], wm_len: int) -> NDArray[Any]:
+    """Extract ``wm_len`` watermark bits from a BGR image."""
+    return decode_dwt_dct_lengths(bgr, (wm_len,))[wm_len]
+
+
+def decode_dwt_dct_lengths(bgr: NDArray[Any], wm_lengths: tuple[int, ...]) -> dict[int, NDArray[Any]]:
+    """Extract several watermark lengths with one DWT and block scan."""
+    if bgr.size == 0 or min(bgr.shape[:2]) * max(bgr.shape[:2]) < 256 * 256:
+        raise RuntimeError("image too small, should be larger than 256x256")
+    if not wm_lengths or any(wm_len <= 0 for wm_len in wm_lengths):
+        raise ValueError("watermark lengths must be positive")
+    return _DecodeMaxDct(wm_lengths=tuple(dict.fromkeys(wm_lengths))).decode(bgr)

src/remove_ai_watermarks/humanizer.py

@@ -1,7 +1,7 @@
 """Post-processing filters for the cleaned output.
 
-``apply_analog_humanizer`` injects film grain and chromatic aberration to defeat
-digital AI-perfection classifiers (ported from NeuralBleach); ``unsharp_mask``
+``apply_analog_humanizer`` injects film grain and chromatic aberration to reduce
+overly uniform digital surfaces; ``unsharp_mask``
 counters the soft, over-smoothed look that the diffusion pass leaves behind
 (itself a common "this is AI" tell).
 """
@@ -16,10 +16,7 @@ from numpy.typing import NDArray
 
 def apply_analog_humanizer(image: NDArray, grain_intensity: float = 4.0, chromatic_shift: int = 1) -> NDArray:
     """
-    Apply Analog Humanizer (film grain and chromatic aberration) to an image.
-    This simulates analog film imperfections to defeat digital AI perfection classifiers.
-
-    Ported from NeuralBleach.
+    Apply shared-luminance grain and a small lateral color offset.
 
     Args:
         image: BGR image as numpy array (uint8).
@@ -33,26 +30,22 @@ def apply_analog_humanizer(image: NDArray, grain_intensity: float = 4.0, chromat
     if len(image.shape) != 3 or image.shape[2] != 3:
         return image.copy()
 
-    # Split channels (OpenCV uses BGR)
-    # B = 0, G = 1, R = 2
+    # Translate the outer color channels without circular edge wrapping.
     b, g, r = cv2.split(image)
-
-    # 1. Chromatic Aberration
-    # Shift R channel left, B channel right. np.roll is circular, so it wraps
-    # the opposite edge into a thin colored fringe at the L/R borders; replicate
-    # the original edge columns there to keep the intended offset interior-only.
-    # Clamp so the edge-replication slices below always have a source column: a shift
-    # >= width would leave them empty and crash the broadcast (r[:, -shift:] = (H, 0)).
-    shift = min(chromatic_shift, image.shape[1] - 1)
+    shift = min(max(0, chromatic_shift), max(0, image.shape[1] - 1))
     if shift > 0:
-        r = np.roll(r, -shift, axis=1)
-        r[:, -shift:] = r[:, -shift - 1 : -shift]
-        b = np.roll(b, shift, axis=1)
-        b[:, :shift] = b[:, shift : shift + 1]
+        shifted_b = np.empty_like(b)
+        shifted_b[:, :shift] = b[:, :1]
+        shifted_b[:, shift:] = b[:, :-shift]
+        b = shifted_b
+
+        shifted_r = np.empty_like(r)
+        shifted_r[:, :-shift] = r[:, shift:]
+        shifted_r[:, -shift:] = r[:, -1:]
+        r = shifted_r
 
     merged = cv2.merge((b, g, r))
 
-    # 2. Film Grain (Gaussian Noise)
     if grain_intensity > 0:
         img_f = merged.astype(np.float32)
         noise = np.random.normal(0, grain_intensity, img_f.shape).astype(np.float32)

src/remove_ai_watermarks/image_io.py

@@ -89,6 +89,19 @@ def _pil_read(path: str | Path, flags: int) -> NDArray[Any] | None:
         return None
 
 
+def load_image_bgr(path: str | Path) -> NDArray[Any]:
+    """Read ``path`` as a BGR ndarray, raising instead of returning ``None``.
+
+    :func:`imread` keeps cv2's ``None``-on-failure contract because the removal paths
+    branch on it. Scripts and tests want the opposite -- fail loudly at the read -- so
+    they call this. Each vendor engine used to carry its own verbatim copy.
+    """
+    image = imread(path)
+    if image is None:
+        raise FileNotFoundError(f"Failed to read image: {path}")
+    return image
+
+
 def to_bgr(image: NDArray[Any]) -> NDArray[Any]:
     """Return a 3-channel BGR view of ``image``, promoting grayscale and BGRA.
 

src/remove_ai_watermarks/invisible_engine.py

@@ -1,10 +1,7 @@
-"""Invisible watermark removal engine.
+"""Diffusion engine for regenerating images that carry invisible AI watermarks.
 
-Wraps the vendored noai-watermark code for removing invisible AI watermarks
-(SynthID, StableSignature, TreeRing) via diffusion-based regeneration.
-
-This module requires the 'gpu' extra dependencies:
-    uv pip install 'remove-ai-watermarks[gpu]'
+Requires the 'qwen-zimage' extra and a CUDA device:
+    uv pip install 'remove-ai-watermarks[qwen-zimage]'
 """
 
 # cv2/torch boundary: this engine wraps cv2 (resize/imwrite/cvtColor) and the
@@ -17,12 +14,12 @@ import logging
 import os
 import warnings
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
-from .noai.watermark_profiles import (
-    DEFAULT_MODEL_ID as DEFAULT_SDXL_MODEL_ID,
-)
-from .noai.watermark_profiles import (
+from ._internal.watermark_profiles import (
+    DEFAULT_PROFILE,
+    REMOVAL_MODULES,
+    resolve_adaptive_polish,
     resolve_seed,
 )
 
@@ -43,27 +40,30 @@ logger = logging.getLogger(__name__)
 
 
 def is_available() -> bool:
-    """Check if invisible watermark removal dependencies are installed."""
+    """Whether the dependencies for a real removal run are installed.
+
+    Shares :data:`REMOVAL_MODULES` with the remover's own precondition so the two
+    cannot drift. When they did, a torch+diffusers-only environment passed this gate
+    and then died at the DiffSynth face stage.
+    """
     from .optional_deps import module_available
 
-    return module_available("diffusers", "torch")
+    return module_available(*REMOVAL_MODULES)
 
 
-def _target_size(width: int, height: int, max_resolution: int, min_resolution: int = 0) -> tuple[int, int] | None:
+def _target_size(width: int, height: int, max_resolution: int) -> tuple[int, int] | None:
     """Compute the (width, height) to process at, or None for native.
 
-    Two opposite long-side adjustments, in precedence order:
+    One long-side adjustment: if it exceeds ``max_resolution``, scale DOWN to it
+    (integer-truncated, matching the PIL ``resize`` call site). 0/negative = no cap.
+    Set only to bound GPU/MPS memory on very large inputs (issue #10).
 
-    - ``max_resolution`` (cap): if the long side exceeds it, scale DOWN to it
-      (integer-truncated, matching the PIL ``resize`` call site). 0/negative = no
-      cap. Set only to bound GPU/MPS memory on very large inputs (issue #10).
-    - ``min_resolution`` (floor): else if the long side is below it, scale UP to it
-      (rounded) so SDXL img2img runs near its ~1024 training resolution instead of
-      degrading on a tiny latent (a 381x512 portrait distorts badly at native).
-      The output is restored to the original size by the caller, so the floor is a
-      transparent quality boost. 0 = no floor. Skipped on a ``min > max`` misconfig.
+    There was also a ``min_resolution`` floor that scaled small inputs UP toward
+    SDXL's ~1024 training size. It went with the SDXL profiles: both surviving
+    profiles run at native geometry, so the floor was forced to 0 on every path and
+    could not fire.
 
-    Returns None when neither applies (native resolution). Pure function so the
+    Returns None when the cap does not apply (native resolution). Pure function so the
     resolution decision is unit-testable without loading the diffusion model.
     """
     long_side = max(width, height)
@@ -72,31 +72,20 @@ def _target_size(width: int, height: int, max_resolution: int, min_resolution: i
         # Clamp the short side to >=1: extreme aspect ratios (e.g. 5000x3 capped
         # at 1024) would otherwise truncate it to 0 and crash image.resize().
         return (max(1, int(width * ratio)), max(1, int(height * ratio)))
-    if min_resolution > 0 and long_side < min_resolution and (max_resolution <= 0 or min_resolution <= max_resolution):
-        ratio = min_resolution / long_side
-        return (max(1, round(width * ratio)), max(1, round(height * ratio)))
     return None
 
 
 class InvisibleEngine:
     """Remove invisible AI watermarks using diffusion model regeneration.
 
-    Based on noai-watermark by mertizci:
-    https://github.com/mertizci/noai-watermark
-
     The approach encodes the image into latent space, injects controlled noise
     to break watermark patterns, and reconstructs via reverse diffusion.
     """
 
-    # SDXL base is the default since May 2026; the vendor-adaptive strength
-    # removes the current SynthID (see watermark_profiles + docs/synthid.md).
-    DEFAULT_MODEL_ID = DEFAULT_SDXL_MODEL_ID
-
     def __init__(
         self,
-        model_id: str | None = None,
         device: str | None = None,
-        pipeline: str = "controlnet",
+        pipeline: str = DEFAULT_PROFILE,
         hf_token: str | None = None,
         progress_callback: Callable[[str], None] | None = None,
         controlnet_conditioning_scale: float = 1.0,
@@ -105,31 +94,28 @@ class InvisibleEngine:
         """Initialize the invisible watermark removal engine.
 
         Args:
-            model_id: HuggingFace model ID. None = use the SDXL base default.
-            device: Device for inference (auto/cpu/mps/cuda/xpu). None = auto.
-            pipeline: Pipeline profile. "controlnet" (DEFAULT; SDXL + canny ControlNet
-                that preserves text/face structure via edge conditioning while removing
-                SynthID), "sdxl" (plain SDXL img2img, lighter but leaves SynthID on
-                flat-graphic content), or "qwen" (Qwen-Image 20B img2img, best text/
-                structure preservation but CUDA/cloud-class), or "qwen-zimage"
-                (Qwen-Image-2512 Lightning + Canny, then SAM-masked Z-Image face
-                repair; CUDA-only). "default" aliases "sdxl".
+            device: Device for inference. Both profiles are CUDA-only, so the
+                usable values are "cuda" and None/"auto" (which detects it);
+                anything else raises rather than falling back.
+            pipeline: Pipeline profile, one of "qwen-zimage" (DEFAULT;
+                Qwen-Image-2512 Lightning + Canny, then SAM-masked Z-Image face repair)
+                or "sdxl-zimage" (the same recipe and the same face stage on an SDXL
+                global pass, vendor-adaptive strength because an SDXL global stage
+                needs more of it). BOTH ARE CUDA-ONLY -- there is no CPU or MPS path
+                for invisible-watermark removal.
             hf_token: HuggingFace API token.
             progress_callback: Optional callback for progress messages.
-            controlnet_conditioning_scale: ControlNet structure-preservation
-                strength (controlnet pipeline only).
+            controlnet_conditioning_scale: Canny ControlNet structure-preservation
+                strength on the global stage of both profiles.
             cpu_offload: Offload model components to CPU between CUDA calls instead
                 of keeping the whole pipeline in VRAM, at the cost of speed. For
                 qwen-zimage, force the face stack to offload instead of using automatic
                 residency. CUDA only.
         """
 
-        from remove_ai_watermarks.noai.watermark_remover import WatermarkRemover
-
-        effective_model = model_id or self.DEFAULT_MODEL_ID
+        from remove_ai_watermarks._internal.watermark_remover import WatermarkRemover
 
         self._remover = WatermarkRemover(
-            model_id=effective_model,
             device=device,
             progress_callback=progress_callback,
             hf_token=hf_token,
@@ -139,51 +125,26 @@ class InvisibleEngine:
         )
         self._progress_callback = progress_callback
 
-    def preload(self) -> None:
-        """Eagerly load the pipeline so download progress is visible."""
-        self._remover.preload()
+    def preload(self, *, global_only: bool = False) -> None:
+        """Eagerly load the pipeline so download progress is visible.
 
-    def _esrgan_upscale(self, image: Any, target: tuple[int, int]) -> Any:
-        """Upscale a PIL image to ``target`` with Real-ESRGAN, else Lanczos.
-
-        Runs Real-ESRGAN at its native factor (on the remover's device, CPU fallback),
-        then resizes to the exact ``target`` with Lanczos. Falls back to a plain Lanczos
-        resize when the ``esrgan`` extra is absent or the model errors.
+        For ``qwen-zimage``, ``global_only=True`` loads the mandatory Qwen stage
+        and leaves the optional Z-Image and SAM face stack lazy until a face is
+        detected. Other profiles have no optional stage and ignore the flag.
         """
-        import cv2
-        import numpy as np
-        from PIL import Image
-
-        from remove_ai_watermarks import upscaler
-
-        if not upscaler.is_available():
-            logger.debug("esrgan upscaler requested but the extra is absent; using Lanczos")
-            return image.resize(target, Image.Resampling.LANCZOS)
-        try:
-            bgr = cv2.cvtColor(np.array(image.convert("RGB")), cv2.COLOR_RGB2BGR)
-            big = upscaler.upscale(bgr, device=self._remover.device)
-            if (big.shape[1], big.shape[0]) != target:
-                big = cv2.resize(big, target, interpolation=cv2.INTER_LANCZOS4)
-            return Image.fromarray(cv2.cvtColor(big, cv2.COLOR_BGR2RGB))
-        except Exception as e:  # never let an optional upscaler break removal
-            logger.warning("Real-ESRGAN upscale failed (%s); using Lanczos", e)
-            return image.resize(target, Image.Resampling.LANCZOS)
+        self._remover.preload(global_only=global_only)
 
     def remove_watermark(
         self,
         image_path: Path,
         output_path: Path | None = None,
         strength: float | None = None,
-        num_inference_steps: int | None = None,
-        guidance_scale: float | None = None,
         seed: int | None = None,
         humanize: float = 0.0,
         max_resolution: int = 0,
-        min_resolution: int = 1024,
         vendor: str | None = None,
         unsharp: float = 0.0,
-        adaptive_polish: bool = False,
-        upscaler: str = "lanczos",
+        adaptive_polish: bool | None = None,
         tile: bool = False,
         tile_size: int = 1024,
         tile_overlap: int = 128,
@@ -193,38 +154,26 @@ class InvisibleEngine:
         Args:
             image_path: Path to the watermarked image.
             output_path: Output path (None = overwrite source).
-            strength: Denoising strength (0.0-1.0). None -> the vendor-adaptive
-                default.
-            num_inference_steps: Number of denoising steps. None keeps the existing
-                100-step library default, except qwen-zimage uses its required
-                four-step Lightning schedule.
-            guidance_scale: Classifier-free guidance scale.
-            seed: Random seed for reproducibility. None resolves to 0 for
-                qwen-zimage and stays random for the other profiles.
+            strength: Denoising strength (0.0-1.0). None -> the profile's calibrated
+                default (resolution-adaptive for qwen-zimage, vendor-adaptive for
+                sdxl-zimage).
+            seed: Random seed for reproducibility. None resolves to 0, because both
+                profiles are certified at a fixed seed.
             humanize: Intensity of Analog Humanizer film grain (0 = off).
             unsharp: Final unsharp-mask sharpening strength (0 = off, default).
                 Applied last to counter the soft / over-smoothed look of the
                 diffusion pass; ~0.5-0.8 is a safe range, higher risks edge halos.
-            adaptive_polish: When True (the CLI default), restore the input's detail
-                level in the softened output: a capped unsharp + edge-masked grain
-                targeting the input's Laplacian variance. Self-limiting -- a no-op when
-                the output already meets the input's detail level (text/flat graphics),
-                so it only acts on over-smoothed photo/face texture. Runs LAST.
+            adaptive_polish: Restore the input's detail level in the softened
+                output: a capped unsharp + edge-masked grain targeting the input's
+                Laplacian variance. Self-limiting -- a no-op when the output already
+                meets the input's detail level (text/flat graphics), so it only acts on
+                over-smoothed photo/face texture. Runs LAST. None (the default) follows
+                the profile: off for qwen-zimage, on for sdxl-zimage. This resolves
+                through the same ``resolve_adaptive_polish`` the CLI uses, so a library
+                caller and a CLI caller on one profile get the same output.
             max_resolution: Cap the long side (px) before diffusion. 0 (default)
-                = no cap. Set a positive value only to bound GPU/MPS memory on
-                very large inputs (it reintroduces a lossy downscale->upscale
-                round-trip).
-            min_resolution: Upscale the long side UP to this (px) before diffusion
-                when the input is smaller, so SDXL runs near its ~1024 training
-                resolution (small inputs degrade/distort badly at native). 1024
-                (default) = on; 0 = off. The output is restored to the original
-                input size, so this is a transparent quality boost; it adds time
-                and memory on small inputs. Ignored on a min > max misconfig.
-            upscaler: How to upscale a small input to the ``min_resolution`` floor:
-                ``"lanczos"`` (default, cv2, no deps) or ``"esrgan"`` (Real-ESRGAN
-                via the ``esrgan`` extra). Only applies when UPscaling (the floor
-                case); a ``max_resolution`` downscale always uses Lanczos. Falls back
-                to Lanczos if the extra is absent.
+                = no cap. Set a positive value only to bound GPU memory on very large
+                inputs (it reintroduces a lossy downscale->upscale round-trip).
             tile: Process the diffusion pass in overlapping tiles instead of one
                 forward pass. This retains the input's native dimensions instead
                 of applying ``max_resolution``, but each tile is still regenerated.
@@ -237,19 +186,13 @@ class InvisibleEngine:
         """
         import tempfile
 
-        if num_inference_steps is None:
-            profile = getattr(self._remover, "model_profile", None)
-            num_inference_steps = 4 if profile == "qwen-zimage" else 100
-        profile = getattr(self._remover, "model_profile", "controlnet")
-        seed = resolve_seed(seed, profile)
+        seed = resolve_seed(seed)
+        adaptive_polish = resolve_adaptive_polish(adaptive_polish, self._remover.model_profile)
 
         from PIL import Image, ImageOps
 
         # Resolution policy: a max_resolution cap (0 = none) bounds memory on huge
-        # inputs, and a min_resolution floor (1024 = default) upscales tiny inputs so
-        # SDXL img2img runs near its ~1024 training size instead of distorting on a
-        # tiny latent (a 381x512 portrait wrecks at native -- issue #36 follow-up).
-        # The output is restored to orig_size below, so the floor is transparent.
+        # inputs. See _target_size for why it is the only lever left.
         # Register the HEIF/AVIF opener so a .heic/.avif input (now a SUPPORTED_FORMAT)
         # decodes here too. The --force skip path bypasses image_io.imread, which is
         # what would otherwise register it, so a bare Image.open would fail on HEIC.
@@ -263,34 +206,16 @@ class InvisibleEngine:
         # reassigned to the resized copy below; PIL resize returns a new object).
         reference_pil = image
 
-        # qwen-zimage operates at the input's native geometry in its reference graph.
-        # Keep an explicit max cap available for callers, but do not apply the SDXL
-        # 1024px minimum-resolution floor to this profile.
-        effective_min_resolution = (
-            0 if getattr(self._remover, "model_profile", None) == "qwen-zimage" else min_resolution
-        )
-        target = _target_size(
-            image.width,
-            image.height,
-            max_resolution,
-            effective_min_resolution,
-        )
+        # Both profiles run at the input's native geometry, so only the explicit max
+        # cap can move it, and it can only ever scale down.
+        target = _target_size(image.width, image.height, max_resolution)
         if target is not None:
-            upscaling = max(target) > max(image.width, image.height)
             if self._progress_callback:
-                reason = (
-                    f"min-resolution floor {min_resolution}px"
-                    if upscaling
-                    else f"max-resolution cap {max_resolution}px"
+                self._progress_callback(
+                    f"Downscaling {image.width}x{image.height} to {target[0]}x{target[1]} "
+                    f"(max-resolution cap {max_resolution}px)..."
                 )
-                verb = "Upscaling" if upscaling else "Downscaling"
-                self._progress_callback(f"{verb} {image.width}x{image.height} to {target[0]}x{target[1]} ({reason})...")
-            # Real-ESRGAN only helps when UPscaling (the floor case); a downscale cap
-            # always uses Lanczos. _esrgan_upscale falls back to Lanczos if the extra is absent.
-            if upscaling and upscaler == "esrgan":
-                image = self._esrgan_upscale(image, target)
-            else:
-                image = image.resize(target, Image.Resampling.LANCZOS)
+            image = image.resize(target, Image.Resampling.LANCZOS)
 
         # Always persist to a temp file, even without downscaling: WatermarkRemover
         # reloads by path, so the EXIF-transposed pixels must be saved or rotation
@@ -310,8 +235,6 @@ class InvisibleEngine:
                 image_path=image_path,
                 output_path=output_path,
                 strength=strength,
-                num_inference_steps=num_inference_steps,
-                guidance_scale=guidance_scale,
                 seed=seed,
                 vendor=vendor,
                 tile=tile,
@@ -382,21 +305,3 @@ class InvisibleEngine:
             # _tmp_path is always set above (we persist the image unconditionally).
             if _tmp_path.exists():
                 _tmp_path.unlink()
-
-    def remove_watermark_batch(
-        self,
-        input_dir: Path,
-        output_dir: Path,
-        strength: float | None = None,
-        steps: int | None = None,
-    ) -> list[Path]:
-        """Remove invisible watermarks from all images in a directory."""
-        if steps is None:
-            profile = getattr(self._remover, "model_profile", None)
-            steps = 4 if profile == "qwen-zimage" else 50
-        return self._remover.remove_watermark_batch(
-            input_dir=input_dir,
-            output_dir=output_dir,
-            strength=strength,
-            num_inference_steps=steps,
-        )

src/remove_ai_watermarks/invisible_watermark.py

@@ -14,22 +14,24 @@ source:
 
 The watermark is fragile: it does NOT survive JPEG re-encoding or resizing
 (verified -- gone after JPEG q90), so detection works only on pristine PNG
-originals. Absence is never proof. Requires the optional ``invisible-watermark``
-package (extra: ``detect``); ``detect_invisible_watermark`` returns None when it
-is not installed.
+originals. Absence is never proof. Requires the optional ``detect`` extra;
+``detect_invisible_watermark`` returns None when it is not installed.
 """
 
-# imwatermark ships no type stubs (like cv2); its decoder returns are Unknown.
-# Relax the untyped-library diagnostics for this thin wrapper module only.
+# The optional numeric libraries do not provide complete types for this path.
 # pyright: reportMissingTypeStubs=false, reportUnknownMemberType=false, reportUnknownVariableType=false, reportUnknownArgumentType=false
 
 from __future__ import annotations
 
 import logging
-from typing import TYPE_CHECKING, cast
+from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
+    from collections.abc import Iterable
     from pathlib import Path
+    from typing import Any
+
+    from numpy.typing import NDArray
 
 logger = logging.getLogger(__name__)
 
@@ -49,10 +51,10 @@ _MATCH_SD1_FRAC = 0.92  # fraction of the 136 string bits that must match
 
 
 def is_available() -> bool:
-    """True if the optional imwatermark decoder is installed."""
+    """True when all dependencies for the optional DWT-DCT decoder exist."""
     from .optional_deps import module_available
 
-    return module_available("imwatermark")
+    return module_available("cv2", "numpy", "pywt")
 
 
 def _bits_match(value: int, ref: int, width: int = 48) -> int:
@@ -68,7 +70,21 @@ def _bytes_match_frac(a: bytes, b: bytes) -> float:
     return 1.0 - diff / (8 * len(b))
 
 
-def detect_invisible_watermark(image_path: Path) -> str | None:
+def _bits_to_int(bits: Iterable[object]) -> int:
+    value = 0
+    for bit in bits:
+        value = (value << 1) | int(bool(bit))
+    return value
+
+
+def _bits_to_bytes(bits: Iterable[object], nbytes: int) -> bytes:
+    import numpy as np
+
+    packed = np.packbits([int(bool(bit)) for bit in bits])
+    return bytes(int(value) for value in packed[:nbytes])
+
+
+def detect_invisible_watermark(image_path: Path, *, image: NDArray[Any] | None = None) -> str | None:
     """Return the embedding scheme name if a known open watermark is decoded.
 
     Returns e.g. ``"Stable Diffusion XL"`` / ``"FLUX.2 (Black Forest Labs)"`` /
@@ -78,32 +94,29 @@ def detect_invisible_watermark(image_path: Path) -> str | None:
     """
     if not is_available():
         return None
-    from imwatermark import WatermarkDecoder
-
     from remove_ai_watermarks import image_io
+    from remove_ai_watermarks.dwt_dct import decode_dwt_dct_lengths
 
-    img = image_io.imread(image_path)
+    # ``image`` lets a caller that has already decoded these pixels hand them in
+    # (mirrors gemini_engine.detect_sparkle_confidence). The decoder only reads the
+    # array -- it converts colour spaces into fresh buffers -- so no copy is needed.
+    img = image if image is not None else image_io.imread(image_path)
     if img is None:
         return None
 
-    # 48-bit fixed-message watermarks (SDXL, FLUX.2).
     try:
-        bits = WatermarkDecoder("bits", 48).decode(img, "dwtDct")
-        value = 0
-        for bit in bits:
-            value = (value << 1) | (1 if bit else 0)
-        for name, ref in _BITS_48.items():
-            if _bits_match(value, ref) >= _MATCH_48:
-                return name
+        decoded = decode_dwt_dct_lengths(img, (48, 8 * len(_SD1_STRING)))
     except Exception as exc:  # decode can fail on tiny images
-        logger.debug("48-bit watermark decode failed for %s: %s", image_path, exc)
+        logger.debug("watermark decode failed for %s: %s", image_path, exc)
+        return None
 
-    # 136-bit default string watermark (SD 1.x / 2.x).
-    try:
-        raw = cast("bytes", WatermarkDecoder("bytes", 8 * len(_SD1_STRING)).decode(img, "dwtDct"))
-        if _bytes_match_frac(raw, _SD1_STRING) >= _MATCH_SD1_FRAC:
-            return "Stable Diffusion 1.x / 2.x"
-    except Exception as exc:
-        logger.debug("string watermark decode failed for %s: %s", image_path, exc)
+    value = _bits_to_int(decoded[48])
+    for name, ref in _BITS_48.items():
+        if _bits_match(value, ref) >= _MATCH_48:
+            return name
+
+    raw = _bits_to_bytes(decoded[8 * len(_SD1_STRING)], len(_SD1_STRING))
+    if _bytes_match_frac(raw, _SD1_STRING) >= _MATCH_SD1_FRAC:
+        return "Stable Diffusion 1.x / 2.x"
 
     return None

src/remove_ai_watermarks/jimeng_engine.py

@@ -24,7 +24,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from remove_ai_watermarks import _text_mark_engine
-from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkEngine
 
 if TYPE_CHECKING:
     from numpy.typing import NDArray
@@ -85,8 +85,6 @@ _CONFIG = TextMarkConfig(
     min_gw=8,
 )
 
-JimengDetection = TextMarkDetection
-
 
 def _alpha_template() -> NDArray[Any] | None:
     """The bundled Jimeng alpha template (float [0,1]), or None."""

src/remove_ai_watermarks/kling_engine.py

@@ -52,11 +52,9 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from remove_ai_watermarks import _text_mark_engine
-from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkEngine
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from numpy.typing import NDArray
 
 # Locate geometry as a fraction of the image SHORT side (measured basis -- see
@@ -114,8 +112,6 @@ _CONFIG = TextMarkConfig(
     provenance_ncc_factor=1.0,
 )
 
-KlingDetection = TextMarkDetection
-
 
 def _alpha_template() -> NDArray[Any] | None:
     """The bundled Kling alpha template (float [0,1]), or None."""
@@ -127,23 +123,8 @@ def _glyph_silhouette() -> NDArray[Any] | None:
     return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
 
 
-def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
-    """TM_CCOEFF_NORMED of the Kling glyph silhouette against ``box_mask``."""
-    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
-
-
 class KlingEngine(TextMarkEngine):
     """Detect/localize the visible Kling "可灵AI 3.0" watermark (locate -> mask; mask feeds the fill)."""
 
     def __init__(self) -> None:
         super().__init__(_CONFIG)
-
-
-def load_image_bgr(path: str | Path) -> NDArray[Any]:
-    """Read an image as BGR ndarray (helper for scripts/tests)."""
-    from remove_ai_watermarks import image_io
-
-    img = image_io.imread(path)
-    if img is None:
-        raise FileNotFoundError(f"Failed to read image: {path}")
-    return img

src/remove_ai_watermarks/liblib_engine.py

@@ -25,11 +25,15 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from remove_ai_watermarks import _text_mark_engine
-from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+from remove_ai_watermarks._text_mark_engine import (
+    TextMarkConfig,
+    TextMarkDetection,
+    TextMarkEngine,
+    TextMarkLocation,
+    TextMarkScan,
+)
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from numpy.typing import NDArray
 
 # Locate geometry as a fraction of the image WIDTH (measured basis). The box is
@@ -84,24 +88,12 @@ _CONFIG = TextMarkConfig(
     provenance_ncc_factor=1.0,
 )
 
-LibLibDetection = TextMarkDetection
-
 
 def _alpha_template() -> NDArray[Any] | None:
     """The bundled LibLibAI alpha template (float [0,1]), or None."""
     return _text_mark_engine.load_alpha_template(_CONFIG.asset_name)
 
 
-def _glyph_silhouette() -> NDArray[Any] | None:
-    """Binary "LibLibAI" silhouette (255 = glyph) from the alpha map, or None."""
-    return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
-
-
-def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
-    """TM_CCOEFF_NORMED of the LibLibAI glyph silhouette against ``box_mask``."""
-    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
-
-
 class LibLibEngine(TextMarkEngine):
     """Detect/localize the visible LibLibAI wordmark (bottom-center; localize -> fill)."""
 
@@ -111,60 +103,51 @@ class LibLibEngine(TextMarkEngine):
     def __init__(self) -> None:
         super().__init__(_CONFIG)
 
-    def detect(self, image: NDArray[Any] | None, *, provenance: bool = False) -> TextMarkDetection:
-        if image is None or not image.size or min(image.shape[:2]) < self._MIN_SHORT_SIDE:
-            return TextMarkDetection()
-        return super().detect(image, provenance=provenance)
+    def _scan(self, image: NDArray[Any] | None) -> TextMarkScan:
+        """Skip the scan entirely below the size floor.
 
-    def footprint_mask(
-        self, image: NDArray[Any] | None, *, force: bool = False, dilate: int | None = None
-    ) -> NDArray[Any] | None:
-        """Full-frame mask of the logo + wordmark, bounded by the detector's match box.
+        Gating the SCAN rather than overriding ``detect`` is what keeps the floor on the
+        single-pass perception path too, and it means a small image costs nothing.
+        """
+        if image is None or not image.size or min(image.shape[:2]) < self._MIN_SHORT_SIDE:
+            return TextMarkScan(None, None, 0)
+        return super()._scan(image)
+
+    def _footprint_rect(
+        self,
+        image: NDArray[Any],
+        loc: TextMarkLocation,
+        *,
+        force: bool,
+        detection: TextMarkDetection | None,
+    ) -> tuple[int, int, int, int] | None:
+        """Bound the fill by the detector's match box, never by the binary glyph blob.
 
         The base class's blob-bbox footprint is wrong in both directions here: the
         blob bleeds UP into bright background structure (on the 768x1024 cohort
         frame it reached y 931 and the fill ate the shirt's own print) and it does
-        not own the triangle logo anyway. The match box bounds the wordmark exactly
-        (that is what the NCC localized); the logo sits its own height to the LEFT
-        of the text (measured on the cohort zoom: logo ~1.0x the glyph height, gap
-        ~0.3x), so the footprint is the match box extended left by ~1.3 heights.
+        not own the triangle logo anyway.
         """
-        if image is None or image.size == 0:
-            return None
-        from remove_ai_watermarks import image_io, region_eraser
+        return self._match_box_rect(image, loc, force=force, detection=detection)
 
-        image = image_io.to_bgr(image)
-        h, w = image.shape[:2]
-        if h < 32 or w < 64:
-            return None
-        loc = self.locate(image)
-        bx, by, bw, bh = loc.bbox
-        if force:
-            rx1, ry1, rx2, ry2 = bx, by, min(w, bx + bw), min(h, by + bh)
-        else:
-            if not self.detect(image).detected:
-                return None
-            _, box = self._tophat_best(image, loc)
-            if box is None:
-                return None
-            gx0, gy0, gx1, gy1 = box
-            gh = gy1 - gy0 + 1
-            pad = max(3, int(0.25 * gh))
-            rx1 = max(0, bx + gx0 - int(1.3 * gh))  # the triangle logo, left of the text
-            ry1 = max(0, by + gy0 - pad)
-            rx2 = min(w, bx + gx1 + 1 + pad)
-            ry2 = min(h, by + gy1 + 1 + pad)
-        if rx1 >= rx2 or ry1 >= ry2:
-            return None
-        d = dilate if dilate is not None else max(3, int(0.02 * bw))
-        return region_eraser.boxes_to_mask((h, w), [(rx1, ry1, rx2 - rx1, ry2 - ry1)], dilate=d)
+    def _extend_match_box(
+        self, box: tuple[int, int, int, int], loc: TextMarkLocation, frame: tuple[int, int]
+    ) -> tuple[int, int, int, int]:
+        """Extend the match box LEFT to take in the triangle logo.
 
-
-def load_image_bgr(path: str | Path) -> NDArray[Any]:
-    """Read an image as BGR ndarray (helper for scripts/tests)."""
-    from remove_ai_watermarks import image_io
-
-    img = image_io.imread(path)
-    if img is None:
-        raise FileNotFoundError(f"Failed to read image: {path}")
-    return img
+        The match box bounds the wordmark exactly (that is what the NCC localized);
+        the logo sits its own height to the LEFT of the text (measured on the cohort
+        zoom: logo ~1.0x the glyph height, gap ~0.3x), so the footprint is the match
+        box extended left by ~1.3 heights.
+        """
+        gx0, gy0, gx1, gy1 = box
+        bx, by, _bw, _bh = loc.bbox
+        h, w = frame
+        gh = gy1 - gy0 + 1
+        pad = max(3, int(0.25 * gh))
+        return (
+            max(0, bx + gx0 - int(1.3 * gh)),  # the triangle logo, left of the text
+            max(0, by + gy0 - pad),
+            min(w, bx + gx1 + 1 + pad),
+            min(h, by + gy1 + 1 + pad),
+        )

src/remove_ai_watermarks/licenses/invisible-watermark-MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 ShieldMnt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/remove_ai_watermarks/metadata.py

@@ -1,7 +1,4 @@
-"""AI metadata detection and removal.
-
-Wraps the noai-watermark metadata handling for stripping AI-generation
-metadata (EXIF, PNG text chunks, C2PA provenance) from images.
+"""Detect and remove AI provenance metadata from image containers.
 
 For metadata-only operations, the heavy ML dependencies are NOT required.
 """
@@ -10,14 +7,22 @@ from __future__ import annotations
 
 import contextlib
 import functools
+import itertools
+import json
 import logging
 import re
 import struct
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
 if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
     from pathlib import Path
 
+from remove_ai_watermarks._internal.constants import (
+    PNG_METADATA_CHUNKS,
+    RIFF_METADATA_CHUNKS,
+)
+
 logger = logging.getLogger(__name__)
 
 # Smaller scan_head window for the cheap marker checks (has_ai_metadata,
@@ -101,7 +106,7 @@ IPTC_AI_MARKERS: tuple[bytes, ...] = (
 # (Meta / Instagram / MidJourney) use ``trainedAlgorithmicMedia``. Including the bare
 # token flagged clean procedural images as AI (is_ai=high + has_invisible_target=True ->
 # a diffusion scrub of clean content), contradicting the c2pa layer, which sets
-# source_type without ai_source for it (tests/test_noai.py::test_plain_algorithmic_media_not_flagged_ai).
+# source_type without ai_source for it (tests/test_metadata_internals.py::test_plain_algorithmic_media_not_flagged_ai).
 # It is not a substring of the trained/composite tokens, so its removal does not affect
 # their detection.
 
@@ -120,12 +125,13 @@ IPTC_AI_FIELD_MARKERS: tuple[bytes, ...] = (
 # the container level (image, video, audio -- all ISOBMFF). A content sniff
 # (``ftyp``) is also accepted, so this is a fast-path hint, not the sole gate.
 _ISOBMFF_EXTS: frozenset[str] = frozenset({".avif", ".heif", ".heic", ".jxl", ".mp4", ".mov", ".m4v", ".m4a"})
+_STREAMING_ISOBMFF_EXTS: frozenset[str] = frozenset({".mp4", ".mov", ".m4v", ".m4a"})
 
 # Non-ISOBMFF audio/video the ISOBMFF box walker can't reach (EBML / framed /
 # RIFF / Vorbis). remove_ai_metadata strips their container metadata losslessly
 # via ffmpeg (`-c copy`), so it needs ffmpeg on PATH for these.
 _FFMPEG_STRIP_EXTS: frozenset[str] = frozenset(
-    {".webm", ".mkv", ".mka", ".mp3", ".wav", ".flac", ".ogg", ".oga", ".opus", ".aac"}
+    {".webm", ".mkv", ".mka", ".avi", ".flv", ".mp3", ".wav", ".flac", ".ogg", ".oga", ".opus", ".aac"}
 )
 
 # China's mandatory AI-content labeling (TC260, the national cybersecurity
@@ -143,7 +149,7 @@ AIGC_MARKERS: tuple[bytes, ...] = (
 # the same object as a PNG ``tEXt`` chunk keyed ``AIGC`` (raw JSON, not XMP), so
 # a JSON object carrying at least one of these is accepted as a valid TC260
 # label even when the namespaced XMP element is absent.
-_TC260_FIELDS: frozenset[str] = frozenset(
+TC260_AIGC_FIELDS: frozenset[str] = frozenset(
     {
         # Producer-side schema (Doubao and most China-served generators).
         "Label",
@@ -161,6 +167,37 @@ _TC260_FIELDS: frozenset[str] = frozenset(
         "ServiceUser",
     }
 )
+MAX_TC260_VALUE_BYTES = 1024 * 1024
+
+
+# A TC260 producer code is ``001`` + ``1`` + USCC(18) + a 5-digit app/product suffix,
+# so two codes sharing the USCC are the same legal entity registering different
+# products. Slicing is defensive: anything not matching the layout is returned as-is,
+# which also passes through the bare-name forms some generators write ("doubao",
+# "picwish").
+_USCC_START, _USCC_END = 4, 22
+
+
+def uscc_of(code: str) -> str:
+    """The 18-char Unified Social Credit Code embedded in a TC260 producer code."""
+    if len(code) >= _USCC_END and code[:3] == "001":
+        return code[_USCC_START:_USCC_END]
+    return code
+
+
+def parse_tc260_aigc_json(value: bytes) -> dict[str, str] | None:
+    """Parse a bounded JSON object carrying at least one normative TC260 field."""
+    if len(value) > MAX_TC260_VALUE_BYTES:
+        return None
+    try:
+        parsed = json.loads(value.rstrip(b"\x00 ").decode("utf-8"))
+    except (UnicodeDecodeError, ValueError):
+        return None
+    if not isinstance(parsed, dict):
+        return None
+    fields = {str(key): str(item) for key, item in cast("dict[object, object]", parsed).items()}
+    return fields if TC260_AIGC_FIELDS & fields.keys() else None
+
 
 # HuggingFace-hosted GPU jobs (Jobs / Spaces) stamp generated PNGs with this
 # ``tEXt`` chunk key holding the job UUID. It marks the hosting job, not a
@@ -198,17 +235,12 @@ def _is_ai_value(value: str) -> bool:
     detection: NovelAI stamps a generic ``Title``/``Source`` text chunk (an
     AI-shaped value under a non-AI key) that ``_is_ai_key`` alone would keep.
     """
-    from remove_ai_watermarks.noai.constants import AI_GENERATOR_TOKENS
+    from remove_ai_watermarks._internal.constants import AI_GENERATOR_TOKENS
 
     value_lower = value.lower()
     return any(token in value_lower for token in AI_GENERATOR_TOKENS)
 
 
-# PNG ancillary chunks that can carry provenance metadata (XMP, EXIF, text).
-# Never IDAT -- that is the compressed pixel stream.
-_PNG_META_CHUNKS: frozenset[bytes] = frozenset({b"tEXt", b"iTXt", b"zTXt", b"eXIf", b"iCCP"})
-
-
 def _png_late_metadata(image_path: Path, window: int) -> bytes:
     """Payloads of PNG metadata chunks that start *beyond* the first ``window``
     bytes, found by seeking past the (large) ``IDAT`` pixel stream.
@@ -240,7 +272,7 @@ def _png_late_metadata(image_path: Path, window: int) -> bytes:
                 # Clamp the attacker-controlled 32-bit length to the bytes that
                 # actually remain, so a malformed huge length can't allocate GBs.
                 safe_length = max(0, min(length, file_size - data_start))
-                if chunk_type in _PNG_META_CHUNKS and data_start >= window:
+                if chunk_type in PNG_METADATA_CHUNKS and data_start >= window:
                     f.seek(data_start)
                     out += f.read(safe_length)
                 # Advance by the CLAMPED length: a malformed/inflated `length` that
@@ -253,17 +285,86 @@ def _png_late_metadata(image_path: Path, window: int) -> bytes:
     return bytes(out)
 
 
+def _riff_late_metadata(image_path: Path, window: int, *, max_total: int = 4 * 1024 * 1024) -> bytes:
+    """Payloads of RIFF metadata chunks that start *beyond* the first ``window``
+    bytes, found by stepping over the (large) coded-image chunk.
+
+    The WebP layout puts ``XMP ``/``EXIF`` AFTER the pixels, so a fixed read can stop
+    before an IPTC or C2PA AI label. This is the RIFF analogue of
+    :func:`_png_late_metadata`; it returns only chunks past ``window`` so bytes
+    already in the head are not duplicated, and empty when there are none.
+
+    ``max_total`` caps what a metadata scan can pull into memory, the same ceiling
+    ``isobmff.scan_c2pa_region`` applies. Clamping each chunk to the bytes that remain
+    is not enough on its own: a corrupt or crafted file can declare one ``XMP `` chunk
+    spanning most of itself, and this runs on the memoized verdict path for images from
+    arbitrary sources. A label that needs more than 4 MB of XMP does not exist.
+    """
+    out = bytearray()
+    try:
+        with open(image_path, "rb") as f:
+            if f.read(4) != b"RIFF":
+                return b""
+            f.seek(0, 2)
+            file_size = f.tell()
+            f.seek(4)
+            declared_size = f.read(4)
+            if len(declared_size) < 4:
+                return b""
+            container_end = min(file_size, 8 + struct.unpack("<I", declared_size)[0])
+            position = 12  # 'RIFF' + size + form type
+            while position + 8 <= container_end and len(out) < max_total:
+                f.seek(position)
+                header = f.read(8)
+                if len(header) < 8:
+                    break
+                chunk_type = header[:4]
+                (length,) = struct.unpack("<I", header[4:8])
+                start = position + 8
+                # Clamp to what remains: a malformed 32-bit length must not push the
+                # walk past EOF and abandon a genuine label chunk after it.
+                safe_length = max(0, min(length, container_end - start))
+                if chunk_type in RIFF_METADATA_CHUNKS and start >= window:
+                    f.seek(start)
+                    out += f.read(min(safe_length, max_total - len(out)))
+                position = start + safe_length + (safe_length & 1)  # chunks are word-aligned
+    except OSError as exc:
+        logger.debug("RIFF late-metadata scan failed on %s: %s", image_path, exc)
+        return b""
+    return bytes(out)
+
+
+def _stat_key(image_path: Path) -> tuple[str, int, int] | None:
+    """Cache key identifying this file's exact CONTENT, or None when it cannot stat.
+
+    ``(path, mtime_ns, size)`` -- size as well as mtime because an in-place rewrite
+    can land inside the same mtime tick on a coarse filesystem, and this package does
+    rewrite in place (``remove_ai_metadata(p, p)``, the batch output-equals-input
+    case). A file it cannot stat is read uncached rather than failing.
+    """
+    try:
+        st = image_path.stat()
+    except OSError:
+        return None
+    return (str(image_path), st.st_mtime_ns, st.st_size)
+
+
 def scan_head(image_path: Path, size: int = 1024 * 1024) -> bytes:
     """First ``size`` bytes of the file, plus the payloads of any provenance
     metadata found beyond that window: ISOBMFF ``uuid`` / ``jumb`` boxes (seeking
     past large boxes like ``mdat``) and PNG ``tEXt`` / ``iTXt`` / ``eXIf`` chunks
     (seeking past ``IDAT``).
 
+    A file at least ``size`` bytes long additionally gets the metadata text its
+    decoder can reach but a raw read cannot (:func:`_decoder_visible_text`): a
+    compressed PNG ``zTXt`` packet, or a chunk past the window in a container with no
+    late-chunk reader here. A file that fits inside ``size`` is exactly
+    ``f.read(size)``, since the raw read already holds every byte.
+
     This is the shared input for every C2PA / AIGC / IPTC byte scan. The
     extensions catch a manifest or XMP packet placed AFTER the media data -- a
     non-faststart MP4 manifest, or a PNG XMP packet appended after the pixels --
-    which a fixed first-MB read would miss. For other inputs, and for files that
-    fit within ``size``, it is exactly ``f.read(size)`` -- behavior-neutral.
+    which a fixed first-MB read would miss.
 
     The result is memoized per (path, size, mtime): one ``identify``/``get_ai_metadata``
     call fans out to ~8 byte-scan detectors that each call this on the same file, so
@@ -290,7 +391,7 @@ def _scan_head_impl(image_path: Path, size: int) -> bytes:
     with open(image_path, "rb") as f:
         head = f.read(size)
     # Lazy import: isobmff imports this module's constants at top level.
-    from remove_ai_watermarks.noai import isobmff
+    from remove_ai_watermarks._internal import isobmff
 
     if isobmff.is_isobmff(head):
         region = isobmff.scan_c2pa_region(image_path)
@@ -300,9 +401,63 @@ def _scan_head_impl(image_path: Path, size: int) -> bytes:
         # len(head) == size means the file is at least `size` bytes, so metadata
         # chunks may lie beyond the window; otherwise the whole PNG is in `head`.
         head += _png_late_metadata(image_path, size)
+    elif head[:4] == b"RIFF" and head[8:12] == b"WEBP" and len(head) == size:
+        head += _riff_late_metadata(image_path, size)
+    if len(head) >= size:
+        head += _decoder_visible_text(image_path, head)
     return head
 
 
+# Text values the image decoder can reach that a raw byte read cannot. Bounded: a
+# packet larger than this is not a provenance label.
+_DECODED_TEXT_LIMIT = 512 * 1024
+# Decoder values that are binary payloads with their own readers, not metadata text.
+# An ICC profile is colour data and can run to hundreds of kilobytes; appending it
+# would bloat the buffer every later detector re-scans, for no signal.
+_DECODER_BINARY_KEYS = frozenset({"icc_profile"})
+
+
+def _decoder_visible_text(image_path: Path, head: bytes) -> bytes:
+    """Metadata text PIL can decode but the raw window does not contain.
+
+    This is the last of two layers, not the first. Metadata placed BEYOND the window
+    is the structural readers' job (``_png_late_metadata``, ``_riff_late_metadata``,
+    the ISOBMFF box walk), and they work on a file no decoder can open. What is left
+    for this one is metadata the bytes do not spell at all:
+
+    * COMPRESSED -- a PNG ``zTXt`` chunk is zlib-deflated, so an XMP packet carrying
+      a TC260 AIGC label is unreadable as bytes while PIL inflates it on open.
+
+    It stays container-agnostic on purpose: it is the net under a placement no
+    structural reader here knows about yet.
+
+    Only text ALREADY MISSING from ``head`` is appended, so the common case adds
+    nothing and no detector sees a value twice. Skipped entirely when the file fits
+    inside the window, since then the raw read already holds every byte.
+    """
+    try:
+        from PIL import Image
+
+        with Image.open(image_path) as img:
+            values = [value for key, value in img.info.items() if key not in _DECODER_BINARY_KEYS]
+    except Exception as exc:  # a container PIL cannot open: the raw scan stands alone
+        logger.debug("decoder-visible text unavailable for %s: %s", image_path, exc)
+        return b""
+
+    out = bytearray()
+    for value in values:
+        if isinstance(value, str):
+            encoded = value.encode("utf-8", "replace")
+        elif isinstance(value, bytes):
+            encoded = value
+        else:
+            continue
+        if len(encoded) > _DECODED_TEXT_LIMIT or not encoded or encoded in head:
+            continue
+        out += b"\x00" + encoded
+    return bytes(out)
+
+
 def has_ai_metadata(image_path: Path) -> bool:
     """Check if an image contains AI-generation metadata.
 
@@ -328,7 +483,7 @@ def has_ai_metadata(image_path: Path) -> bool:
     # Check C2PA — via the official c2pa-python reader first (spec-tracking, every
     # container it supports), then a binary scan that also catches AVIF/HEIF/JPEG-XL
     # containers and synthetic/partial blobs the validator rejects.
-    from remove_ai_watermarks.noai.c2pa import read_manifest_store_json
+    from remove_ai_watermarks._internal.c2pa import read_manifest_store_json
 
     if read_manifest_store_json(image_path) is not None:
         return True
@@ -356,13 +511,65 @@ def has_ai_metadata(image_path: Path) -> bool:
     return xai_signature(image_path)
 
 
-def aigc_label(image_path: Path) -> dict[str, str] | None:
+def aigc_label_from_metadata(data: bytes, candidates: tuple[str, ...] = ()) -> dict[str, str] | None:
+    """Parse a China TC260 AI-labeling block from already collected metadata."""
+    import html
+    import json
+    from typing import cast
+
+    def _parse(text: str, *, require_tc260_field: bool) -> dict[str, str] | None:
+        if require_tc260_field:
+            return parse_tc260_aigc_json(text.encode("utf-8"))
+        try:
+            parsed = json.loads(text)
+        except ValueError:
+            return None
+        if not isinstance(parsed, dict):
+            return None
+        return {str(k): str(v) for k, v in cast("dict[object, object]", parsed).items()}
+
+    for candidate in candidates:
+        if result := _parse(candidate, require_tc260_field=True):
+            return result
+
+    match = re.search(
+        rb'<TC260:AIGC>(.*?)</TC260:AIGC>|TC260:AIGC\s*=\s*"(.*?)"',
+        data,
+        re.DOTALL,
+    )
+    if match:
+        body = match.group(1) if match.group(1) is not None else match.group(2)
+        return _parse(html.unescape(body.decode("utf-8", "replace")), require_tc260_field=False)
+
+    text = data.decode("latin-1")
+    for needle in ('"AIGC"', "AIGC{"):
+        start = text.find(needle)
+        if start == -1:
+            continue
+        brace = text.find("{", start)
+        if brace == -1:
+            continue
+        try:
+            _, end = json.JSONDecoder().raw_decode(text, brace)
+        except ValueError:
+            continue
+        if result := _parse(text[brace:end], require_tc260_field=True):
+            return result
+    return None
+
+
+def _aigc_label_impl(image_path: Path) -> dict[str, str] | None:
     """Parse a China TC260 AI-labeling block, if present.
 
-    Three serializations are recognized:
+    Supported serializations are:
 
     - a PNG ``tEXt``/``iTXt`` chunk keyed ``AIGC`` carrying the raw JSON object
       (as written by Doubao / ByteDance), read via PIL;
+    - a native MP4/MOV ``AIGC`` key in ``moov.udta.meta.keys`` whose matching
+      ``ilst`` item carries the raw JSON object;
+    - a native MKV/WebM ``AIGC`` simple tag carrying the raw JSON object;
+    - a native AVI ``LIST/INFO/AIGC`` chunk or FLV
+      ``script.onMetaData.AIGC`` string carrying the raw JSON object;
     - an XMP ``<TC260:AIGC>{...}</TC260:AIGC>`` block (HTML-entity encoded text),
       found by a container-agnostic raw-byte scan (PNG/JPEG/WebP alike); and
     - a raw-JSON ``{"AIGC":{...}}`` block with no namespace, as embedded in JPEG
@@ -375,27 +582,9 @@ def aigc_label(image_path: Path) -> dict[str, str] | None:
     Returns the decoded JSON (e.g. ``{"Label": "1", "ContentProducer": ...}``)
     or None. The generic forms (the PNG-chunk key ``AIGC``, the bare
     ``{"AIGC":...}`` object, and the bare ``AIGC{...}`` blob) are accepted only
-    if they carry at least one known TC260 field (``_TC260_FIELDS``); the
+    if they carry at least one known TC260 field (``TC260_AIGC_FIELDS``); the
     namespaced XMP element is unambiguous, so any JSON object is accepted.
     """
-    import html
-    import json
-    from typing import cast
-
-    def _parse(text: str, *, require_tc260_field: bool) -> dict[str, str] | None:
-        try:
-            parsed = json.loads(text)
-        except ValueError:
-            return None
-        if not isinstance(parsed, dict):
-            return None
-        fields = {str(k): str(v) for k, v in cast("dict[object, object]", parsed).items()}
-        if require_tc260_field and not (_TC260_FIELDS & fields.keys()):
-            return None
-        return fields
-
-    # PNG tEXt chunk keyed "AIGC" with raw JSON (Doubao and other China gens).
-    # The key is generic, so require a TC260 field to avoid a false positive.
     try:
         from PIL import Image
 
@@ -404,50 +593,46 @@ def aigc_label(image_path: Path) -> dict[str, str] | None:
     except Exception as exc:
         logger.debug("PIL could not open %s for AIGC chunk scan: %s", image_path, exc)
         value = None
-    if isinstance(value, str) and (result := _parse(value, require_tc260_field=True)):
+
+    if isinstance(value, str) and (result := aigc_label_from_metadata(b"", (value,))):
         return result
 
-    # XMP TC260:AIGC, namespaced (unambiguous) in either serialization RDF allows:
-    # an element  <TC260:AIGC>{...}</TC260:AIGC>  or an attribute  TC260:AIGC="{...}"
-    # (the attribute form is what PicWish writes). Both are HTML-entity encoded.
-    data = scan_head(image_path)
-    match = re.search(
-        rb'<TC260:AIGC>(.*?)</TC260:AIGC>|TC260:AIGC\s*=\s*"(.*?)"',
-        data,
-        re.DOTALL,
-    )
-    if match:
-        body = match.group(1) if match.group(1) is not None else match.group(2)
-        return _parse(html.unescape(body.decode("utf-8", "replace")), require_tc260_field=False)
-
-    # Generic raw-JSON forms the PNG-chunk and XMP paths above both miss, each
-    # gated on a TC260 field: the ``"AIGC":{...}`` key wrapper (as written into
-    # JPEG EXIF UserComment) and the bare ``AIGC{...}`` blob (the label glued
-    # straight to its JSON, no key wrapper, in a JPEG APP segment near the JFIF
-    # header). `raw_decode` brace-matches the inner object (respecting nested
-    # braces / quoted strings); `_parse` applies the same dict coercion + TC260
-    # gate as the PNG-chunk path. A non-matching hit (no TC260 field, or an
-    # undecodable brace) must FALL THROUGH to the next form, never short-circuit:
-    # a quoted ``"AIGC"`` can appear later in an XMP packet while the real label
-    # is a bare ``AIGC{...}`` blob earlier in the file, so an unconditional return
-    # on the quoted form would shadow the bare form.
-    text = data.decode("latin-1")
-    for needle in ('"AIGC"', "AIGC{"):
-        start = text.find(needle)
-        if start == -1:
-            continue
-        # First brace at/after the needle: the object brace for ``"AIGC":{`` and
-        # the glued brace (at start+4) for the bare ``AIGC{`` -- one search covers both.
-        brace = text.find("{", start)
-        if brace == -1:
-            continue
-        try:
-            _, end = json.JSONDecoder().raw_decode(text, brace)
-        except ValueError:
-            continue
-        if result := _parse(text[brace:end], require_tc260_field=True):
+    # Native container TC260 metadata. Every reader walks its own container structure
+    # and skips media payloads instead of relying on a raw substring that could collide
+    # inside compressed video, and every one of them SELF-GATES on its magic bytes --
+    # returning () after a 4-12 byte read on anything else. So the route is content, not
+    # extension: a correctly formatted AVI or FLV served under the wrong suffix used to
+    # be missed, which contradicts this module's own rule elsewhere ("route on the
+    # actual content format, not the extension").
+    for reader in _tc260_container_readers():
+        candidates = tuple(payload.decode("utf-8", "replace") for payload in reader(image_path))
+        if result := aigc_label_from_metadata(b"", candidates):
             return result
-    return None
+
+    data = scan_head(image_path)
+    return aigc_label_from_metadata(data)
+
+
+def _tc260_container_readers() -> tuple[Callable[[Path], tuple[bytes, ...]], ...]:
+    """The native-container TC260 readers, most common first.
+
+    Static imports rather than ``importlib``: this module carries no pyright pragma, so
+    a dynamically resolved callable would be ``Any`` and fail the strict gate. They stay
+    function-local because ``isobmff`` imports this module's constants at import time.
+
+    * MP4/MOV -- the ``AIGC`` key in ``moov.udta.meta.keys`` points at raw JSON in
+      ``ilst``; the bounded box walker finds a tail ``moov`` after a large ``mdat``
+      without loading the media payload.
+    * MKV/WebM -- ``Segment.Tags.Tag.SimpleTag`` carries ``TagName=AIGC``.
+    * AVI -- a ``LIST/INFO/AIGC`` chunk.
+    * FLV -- ``script.onMetaData.AIGC``.
+    """
+    from remove_ai_watermarks._internal.ebml import tc260_aigc_payloads as ebml_payloads
+    from remove_ai_watermarks._internal.flv import tc260_aigc_payloads as flv_payloads
+    from remove_ai_watermarks._internal.isobmff import tc260_aigc_payloads as isobmff_payloads
+    from remove_ai_watermarks._internal.riff import tc260_aigc_payloads as riff_payloads
+
+    return (isobmff_payloads, ebml_payloads, riff_payloads, flv_payloads)
 
 
 # C2PA "Durable Content Credentials" manifest repositories (C2PA 2.4). When the
@@ -490,7 +675,7 @@ def c2pa_cloud_manifest(image_path: Path) -> str | None:
     return c2pa_cloud_manifest_in(scan_head(image_path, _QUICK_SCAN_BYTES))
 
 
-def huggingface_job(image_path: Path) -> str | None:
+def _huggingface_job_impl(image_path: Path) -> str | None:
     """Return the HuggingFace job id if the image carries an ``hf-job-id`` PNG
     text chunk, else None.
 
@@ -541,7 +726,17 @@ def _read_file_tail(image_path: Path, size: int) -> bytes:
         return b""
 
 
-def samsung_genai(image_path: Path) -> int | None:
+def samsung_genai_in(data: bytes) -> int | None:
+    """Return Samsung's non-zero ``genAIType`` from collected metadata bytes."""
+    if _SAMSUNG_EDITOR_MARKER not in data:
+        return None
+    match = _SAMSUNG_GENAI_RE.search(data)
+    if match is None:
+        return None
+    return int(match.group(1)) or None
+
+
+def _samsung_genai_impl(image_path: Path) -> int | None:
     """Return Samsung's non-zero ``genAIType`` value if the image carries the
     Galaxy AI editing marker, else None.
 
@@ -565,15 +760,20 @@ def samsung_genai(image_path: Path) -> int | None:
             oversize = False
         if oversize:
             data = _read_file_tail(image_path, _QUICK_SCAN_BYTES)
-    if _SAMSUNG_EDITOR_MARKER not in data:
-        return None
-    m = _SAMSUNG_GENAI_RE.search(data)
-    if m is None:
-        return None
-    return int(m.group(1)) or None
+    return samsung_genai_in(data)
 
 
-def iptc_ai_system(image_path: Path) -> str | None:
+def iptc_ai_system_in(data: bytes) -> str | None:
+    """Return an IPTC 2025.1 AI-disclosure note from collected metadata bytes."""
+    if not any(marker in data for marker in IPTC_AI_FIELD_MARKERS):
+        return None
+    match = re.search(rb"AISystemUsed[=:\s]*[\"'>]\s*([^<\"']{1,120})", data)
+    if match and (value := match.group(1).decode("utf-8", "replace").strip()):
+        return value
+    return "fields present"
+
+
+def _iptc_ai_system_impl(image_path: Path) -> str | None:
     """Return an IPTC 2025.1 AI-disclosure note if the file carries those XMP
     properties, else None.
 
@@ -583,28 +783,22 @@ def iptc_ai_system(image_path: Path) -> str | None:
     extractable, otherwise the literal ``"fields present"``. Container-agnostic
     raw-byte scan; handles both XMP element and attribute serializations.
     """
-    data = scan_head(image_path)
-    if not any(marker in data for marker in IPTC_AI_FIELD_MARKERS):
-        return None
-    match = re.search(rb"AISystemUsed[=:\s]*[\"'>]\s*([^<\"']{1,120})", data)
-    if match and (value := match.group(1).decode("utf-8", "replace").strip()):
-        return value
-    return "fields present"
+    return iptc_ai_system_in(scan_head(image_path))
 
 
 def synthid_source(image_path: Path) -> str | None:
-    """Return the vendor name(s) if the image carries a SynthID pixel watermark.
+    """Return the vendor name(s) when provenance establishes SynthID.
 
-    This is a *metadata-based* proxy: Google (Imagen/Gemini) and OpenAI
-    (ChatGPT/DALL-E/gpt-image) embed an invisible SynthID watermark alongside
-    a C2PA manifest, so a C2PA manifest signed by one of them on AI-generated
-    content implies SynthID in the pixels. Adobe Firefly / Microsoft Designer
-    sign C2PA but do not use SynthID, so they return None.
+    This is provenance-based, not a local pixel decode. Google states that all
+    media generated by its tools carries SynthID, so Google AI C2PA establishes
+    the mark. OpenAI C2PA existed before OpenAI adopted SynthID, so OpenAI also
+    requires the explicit ``c2pa.watermarked.*`` action used by current manifests.
+    Adobe Firefly and Microsoft sign C2PA but do not use SynthID, so they return
+    None.
 
-    The verdict is reliable only while the C2PA manifest is intact -- absence
-    is not proof, because C2PA can be stripped while the pixel watermark
-    survives, and the pixel watermark itself is not locally detectable
-    (proprietary decoder).
+    The evidence is readable only while the C2PA manifest is intact. Absence is
+    not proof: C2PA can be stripped while the pixel watermark survives, and the
+    pixel watermark itself is not locally detectable (proprietary decoder).
 
     Args:
         image_path: Path to the image (PNG, JPEG, WebP, or ISOBMFF container).
@@ -612,7 +806,7 @@ def synthid_source(image_path: Path) -> str | None:
     Returns:
         Comma-joined vendor name(s) (e.g. ``"OpenAI"``) or None.
     """
-    from remove_ai_watermarks.noai.c2pa import extract_c2pa_info, synthid_vendors_in
+    from remove_ai_watermarks._internal.c2pa import extract_c2pa_info, synthid_evidence_vendors_in
 
     # PNG: the caBX chunk parser gives a clean, structured issuer.
     vendors = extract_c2pa_info(image_path).get("synthid_vendors")
@@ -628,10 +822,24 @@ def synthid_source(image_path: Path) -> str | None:
     ai_source = b"trainedAlgorithmicMedia" in data or b"TrainedAlgorithmicMedia" in data
     if not (has_c2pa and ai_source):
         return None
-    matched = synthid_vendors_in(data)
+    matched = synthid_evidence_vendors_in(data)
     return ", ".join(matched) if matched else None
 
 
+def generator_from_metadata(candidates: Iterable[str], scan: bytes = b"") -> str | None:
+    """Return a known AI generator from collected EXIF, PNG, or XMP values."""
+    from remove_ai_watermarks._internal.constants import AI_GENERATOR_TOKENS
+
+    creator_tools = (
+        match.group(1).decode("latin1", "replace")
+        for match in re.finditer(rb"CreatorTool[>\"'=\s]{1,4}([^<\"']{1,80})", scan)
+    )
+    for value in itertools.chain(candidates, creator_tools):
+        if any(token in value.lower() for token in AI_GENERATOR_TOKENS):
+            return value.strip()
+    return None
+
+
 def exif_generator(image_path: Path) -> str | None:
     """Return an AI-generator name from the EXIF ``Software`` / XMP ``CreatorTool``
     field (or a PNG text chunk), if it matches a known generator (see
@@ -644,10 +852,6 @@ def exif_generator(image_path: Path) -> str | None:
     chunks rather than EXIF. Only AI tokens match, so ordinary editors (plain
     "Adobe Photoshop", "GIMP") are not flagged.
     """
-    import re
-
-    from remove_ai_watermarks.noai.constants import AI_GENERATOR_TOKENS
-
     candidates: list[str] = []
 
     # EXIF Software / Artist / ImageDescription (0th IFD) via PIL exif bytes,
@@ -682,18 +886,12 @@ def exif_generator(image_path: Path) -> str | None:
     except Exception as exc:  # unopenable format / malformed EXIF
         logger.debug("EXIF generator read failed for %s: %s", image_path, exc)
 
-    # XMP CreatorTool: text, container-agnostic (covers HEIF/JXL via raw scan).
     try:
         head = scan_head(image_path)
-        for match in re.finditer(rb"CreatorTool[>\"'=\s]{1,4}([^<\"']{1,80})", head):
-            candidates.append(match.group(1).decode("latin1", "replace"))
     except Exception as exc:
         logger.debug("XMP CreatorTool scan failed for %s: %s", image_path, exc)
-
-    for value in candidates:
-        if any(token in value.lower() for token in AI_GENERATOR_TOKENS):
-            return value.strip()
-    return None
+        head = b""
+    return generator_from_metadata(candidates, head)
 
 
 # xAI / Grok EXIF signature scheme. A 64+ char base64 blob after "Signature:"
@@ -703,7 +901,7 @@ _XAI_SIGNATURE_RE = re.compile(r"Signature:\s*[A-Za-z0-9+/=]{64,}")
 _UUID_RE = re.compile(r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", re.IGNORECASE)
 
 
-def _is_xai_signature_pair(description: str, artist: str) -> bool:
+def xai_signature_pair(description: str, artist: str) -> bool:
     """True if an EXIF (ImageDescription, Artist) pair is xAI/Grok's scheme."""
     return _XAI_SIGNATURE_RE.match(description) is not None and _UUID_RE.fullmatch(artist) is not None
 
@@ -714,7 +912,7 @@ def _exif_text(ifd: dict[int, Any], tag: int) -> str:
     return value.decode("latin1", "replace").strip() if isinstance(value, bytes) else ""
 
 
-def xai_signature(image_path: Path) -> bool:
+def _xai_signature_impl(image_path: Path) -> bool:
     """Detect xAI / Grok's EXIF provenance signature scheme.
 
     Grok image downloads (Aurora model) carry no C2PA, XMP, SynthID, or IPTC --
@@ -739,7 +937,7 @@ def xai_signature(image_path: Path) -> bool:
         logger.debug("xAI-signature EXIF read failed for %s: %s", image_path, exc)
         return False
 
-    return _is_xai_signature_pair(
+    return xai_signature_pair(
         _exif_text(tags, piexif.ImageIFD.ImageDescription), _exif_text(tags, piexif.ImageIFD.Artist)
     )
 
@@ -750,7 +948,7 @@ def _is_aigc_exif_value(raw: object) -> bool:
     Mirrors ``aigc_label``'s EXIF path: the ``{"AIGC":{...}}`` wrapper embedded in
     ``UserComment`` / ``ImageDescription`` by China-served generators (Doubao's
     producer schema AND Tencent Cloud's service-provider schema, both keyed under
-    ``_TC260_FIELDS``). Gated on both the ``AIGC`` marker and a TC260 field so a
+    ``TC260_AIGC_FIELDS``). Gated on both the ``AIGC`` marker and a TC260 field so a
     coincidental token cannot false-drop a genuine caption/comment. Accepts a ``str``
     too (a PNG ``tEXt``/``iTXt`` value), not only EXIF bytes.
     """
@@ -761,7 +959,7 @@ def _is_aigc_exif_value(raw: object) -> bool:
     if b"AIGC" not in raw:
         return False
     text = bytes(raw).decode("latin-1", "ignore")
-    return any(field in text for field in _TC260_FIELDS)
+    return any(field in text for field in TC260_AIGC_FIELDS)
 
 
 def _ai_exif_targets(loaded: dict[str, Any]) -> list[tuple[str, int, bytes, str]]:
@@ -780,7 +978,7 @@ def _ai_exif_targets(loaded: dict[str, Any]) -> list[tuple[str, int, bytes, str]
     """
     import piexif
 
-    from remove_ai_watermarks.noai.constants import AI_GENERATOR_TOKENS
+    from remove_ai_watermarks._internal.constants import AI_GENERATOR_TOKENS
 
     ifd0: dict[int, Any] = loaded.get("0th") or {}
     ifde: dict[int, Any] = loaded.get("Exif") or {}
@@ -794,9 +992,7 @@ def _ai_exif_targets(loaded: dict[str, Any]) -> list[tuple[str, int, bytes, str]
             targets.append((ifd_key, tag, value, name))
 
     # (a) xAI / Grok: the Signature blob and the UUID Artist go together.
-    if _is_xai_signature_pair(
-        _exif_text(ifd0, piexif.ImageIFD.ImageDescription), _exif_text(ifd0, piexif.ImageIFD.Artist)
-    ):
+    if xai_signature_pair(_exif_text(ifd0, piexif.ImageIFD.ImageDescription), _exif_text(ifd0, piexif.ImageIFD.Artist)):
         add("0th", ifd0, piexif.ImageIFD.ImageDescription, "ImageDescription")
         add("0th", ifd0, piexif.ImageIFD.Artist, "Artist")
     # (b) known AI generator token in a 0th text tag.
@@ -841,7 +1037,7 @@ def get_ai_metadata(image_path: Path) -> dict[str, str]:
     """
     from PIL import Image
 
-    from remove_ai_watermarks.noai.c2pa import extract_c2pa_info, soft_binding_vendors_in, synthid_verdict
+    from remove_ai_watermarks._internal.c2pa import extract_c2pa_info, soft_binding_vendors_in, synthid_verdict
 
     result: dict[str, str] = {}
 
@@ -861,7 +1057,7 @@ def get_ai_metadata(image_path: Path) -> dict[str, str]:
     except Exception as exc:
         logger.debug("PIL could not open %s for AI-metadata scan: %s", image_path, exc)
 
-    # C2PA manifest fields from the single canonical parser (noai/c2pa.py).
+    # C2PA manifest fields from the single canonical parser (_internal/c2pa.py).
     c2pa = extract_c2pa_info(image_path)
     for key in (
         "c2pa_manifest",
@@ -1091,9 +1287,32 @@ def strip_and_verify(
     exposed this when `metadata --remove` reported success while the output still read
     as AI.
 
+    If markers survive but OpenCV can still decode the raster, the verified path
+    normalizes the container through :mod:`image_io` and scans once more. This
+    intentionally drops standard metadata on that recovery path because the original
+    container is too malformed for the metadata-preserving decoder.
+
     Returns ``(output_path, surviving_markers)``; an empty mapping means a real strip.
     """
     out = remove_ai_metadata(source_path, output_path, keep_standard=keep_standard)
+    remaining = get_ai_metadata(out)
+    if not remaining:
+        return out, {}
+
+    import cv2
+
+    from remove_ai_watermarks import image_io
+
+    image = image_io.imread(out, cv2.IMREAD_UNCHANGED)
+    if image is None:
+        return out, remaining
+    logger.warning(
+        "AI metadata survived stripping; normalizing decodable raster: path=%s fields=%s",
+        out,
+        ",".join(sorted(remaining)),
+    )
+    if not image_io.imwrite(out, image):
+        raise OSError(f"Failed to normalize image after incomplete metadata stripping: {out}")
     return out, get_ai_metadata(out)
 
 
@@ -1126,39 +1345,56 @@ def remove_ai_metadata(
     # strip C2PA + AI-label boxes at the container level without re-encoding.
     # Avoids needing PIL plugins (pillow-heif / pillow-jxl) and preserves the
     # codestream bit-for-bit. MP4/MOV/M4A are ISOBMFF too, so the same top-level
-    # uuid/jumb box walker applies. Route by suffix OR by an ``ftyp`` content
-    # sniff, so a correctly-shaped container is handled whatever its extension.
-    from remove_ai_watermarks.noai.isobmff import (
+    # uuid/jumb box walker applies. Known media suffixes take the bounded,
+    # offset-preserving streaming path; images retain the in-memory item scrub
+    # needed for XMP/EXIF inside mdat/idat. Route the remaining formats by suffix
+    # OR by an ``ftyp`` content sniff.
+    from remove_ai_watermarks._internal.isobmff import (
         blank_ai_exif_tokens,
         blank_ai_xmp_packets,
+        blank_tc260_aigc_tags,
         is_isobmff,
         strip_c2pa_boxes,
+        strip_isobmff_media_file,
     )
 
     with open(source_path, "rb") as f:
         head = f.read(12)
+    if source_path.suffix.lower() in _STREAMING_ISOBMFF_EXTS and is_isobmff(head):
+        stripped, tc260_blanked = strip_isobmff_media_file(source_path, output_path)
+        logger.info(
+            "Stream-blanked %d AI-provenance box(es) and %d native TC260 tag(s) → %s",
+            stripped,
+            tc260_blanked,
+            output_path,
+        )
+        return output_path
     if source_path.suffix.lower() in _ISOBMFF_EXTS or is_isobmff(head):
         data = source_path.read_bytes()
         # Top-level uuid/jumb boxes (C2PA + AI-label XMP), then the meta-box items
         # the top-level stripper can't reach (HEIF/AVIF store them in mdat/idat):
-        # AI-label XMP packets and AI-generator tokens in an Exif item -- both
-        # blanked in place (same length) so box sizes and iloc offsets stay valid
-        # and the coded image is untouched.
+        # Native TC260 tags, AI-label XMP packets, and AI-generator tokens in an
+        # Exif item are blanked in place (same length) so box sizes and iloc /
+        # media offsets stay valid and the coded content is untouched.
         cleaned, stripped = strip_c2pa_boxes(data)
+        cleaned, tc260_blanked = blank_tc260_aigc_tags(cleaned)
         cleaned, blanked = blank_ai_xmp_packets(cleaned)
         cleaned, exif_blanked = blank_ai_exif_tokens(cleaned)
         output_path.parent.mkdir(parents=True, exist_ok=True)
         output_path.write_bytes(cleaned)
         logger.info(
-            "Stripped %d AI-provenance box(es), blanked %d meta-box XMP packet(s) + %d EXIF token(s) → %s",
+            "Stripped %d AI-provenance box(es), blanked %d native TC260 tag(s) + "
+            "%d meta-box XMP packet(s) + %d EXIF token(s) → %s",
             stripped,
+            tc260_blanked,
             blanked,
             exif_blanked,
             output_path,
         )
         return output_path
 
-    # Non-ISOBMFF audio/video (WebM/Matroska EBML, MP3 ID3, WAV/FLAC/OGG): the
+    # Non-ISOBMFF audio/video (WebM/Matroska EBML, AVI/FLV, MP3 ID3,
+    # WAV/FLAC/OGG): the
     # box walker can't reach these, so strip container metadata losslessly via
     # ffmpeg (-c copy -- codec data untouched, only tags/chapters dropped).
     if source_path.suffix.lower() in _FFMPEG_STRIP_EXTS:
@@ -1273,3 +1509,100 @@ def remove_ai_metadata(
 
     logger.info("Stripped AI metadata → %s", output_path)
     return output_path
+
+
+# ── Per-file probe memoization ──────────────────────────────────────────────
+# One ``identify`` reaches each of these twice (``get_ai_metadata`` internally, then
+# ``extract_provenance_evidence``), and each call re-walks the container -- the
+# ISOBMFF/EBML walks in ``aigc_label`` and the file-tail read in ``samsung_genai``
+# are the expensive ones. Keyed on (path, mtime_ns, size) so an in-place rewrite
+# invalidates; ``maxsize`` bounds memory to a handful of entries.
+
+
+@functools.lru_cache(maxsize=4)
+def _aigc_label_cached(path_str: str, _mtime_ns: int, _size: int) -> dict[str, str] | None:
+    from pathlib import Path as _Path
+
+    return _aigc_label_impl(_Path(path_str))
+
+
+def aigc_label(image_path: Path) -> dict[str, str] | None:
+    """See :func:`_aigc_label_impl`; memoized per file content."""
+    key = _stat_key(image_path)
+    if key is None:
+        return _aigc_label_impl(image_path)
+    result = _aigc_label_cached(*key)
+    return dict(result) if result is not None else None
+
+
+@functools.lru_cache(maxsize=4)
+def _huggingface_job_cached(path_str: str, _mtime_ns: int, _size: int) -> str | None:
+    from pathlib import Path as _Path
+
+    return _huggingface_job_impl(_Path(path_str))
+
+
+def huggingface_job(image_path: Path) -> str | None:
+    """See :func:`_huggingface_job_impl`; memoized per file content."""
+    key = _stat_key(image_path)
+    if key is None:
+        return _huggingface_job_impl(image_path)
+    return _huggingface_job_cached(*key)
+
+
+@functools.lru_cache(maxsize=4)
+def _samsung_genai_cached(path_str: str, _mtime_ns: int, _size: int) -> int | None:
+    from pathlib import Path as _Path
+
+    return _samsung_genai_impl(_Path(path_str))
+
+
+def samsung_genai(image_path: Path) -> int | None:
+    """See :func:`_samsung_genai_impl`; memoized per file content."""
+    key = _stat_key(image_path)
+    if key is None:
+        return _samsung_genai_impl(image_path)
+    return _samsung_genai_cached(*key)
+
+
+@functools.lru_cache(maxsize=4)
+def _iptc_ai_system_cached(path_str: str, _mtime_ns: int, _size: int) -> str | None:
+    from pathlib import Path as _Path
+
+    return _iptc_ai_system_impl(_Path(path_str))
+
+
+def iptc_ai_system(image_path: Path) -> str | None:
+    """See :func:`_iptc_ai_system_impl`; memoized per file content."""
+    key = _stat_key(image_path)
+    if key is None:
+        return _iptc_ai_system_impl(image_path)
+    return _iptc_ai_system_cached(*key)
+
+
+@functools.lru_cache(maxsize=4)
+def _xai_signature_cached(path_str: str, _mtime_ns: int, _size: int) -> bool:
+    from pathlib import Path as _Path
+
+    return _xai_signature_impl(_Path(path_str))
+
+
+def xai_signature(image_path: Path) -> bool:
+    """See :func:`_xai_signature_impl`; memoized per file content."""
+    key = _stat_key(image_path)
+    if key is None:
+        return _xai_signature_impl(image_path)
+    return _xai_signature_cached(*key)
+
+
+# ── Shared with the portable metadata record ────────────────────────
+# `metadata_record` must read exactly the windows and markers the file path reads: a
+# record built from a different window is a record whose verdict can disagree with
+# `identify` on the same image. Aliased rather than renamed because the private names
+# are load-bearing in this module's own tests and in a corpus script.
+QUICK_SCAN_BYTES = _QUICK_SCAN_BYTES
+SAMSUNG_EDITOR_MARKER = _SAMSUNG_EDITOR_MARKER
+read_file_tail = _read_file_tail
+png_late_metadata = _png_late_metadata
+riff_late_metadata = _riff_late_metadata
+exif_text = _exif_text

src/remove_ai_watermarks/metadata_record.py

@@ -0,0 +1,404 @@
+"""Collect one image's provenance metadata into a portable, JSON-safe record.
+
+WHY THIS EXISTS
+
+``extract_provenance_evidence`` reads a file and hands back evidence in memory, so
+collection and verdict must happen in the same process, on the machine holding the
+image. This module splits them: collect here, judge anywhere, from a record that
+survives JSON.
+
+    record = collect_metadata_record(path)          # touches the file
+    evidence = evidence_from_metadata_record(record, path=path)
+    report = identify_from_evidence(evidence)       # touches nothing
+
+WHAT GOES IN, AND WHY NOT SIMPLY THE FILE HEAD
+
+The verdict reads a scan buffer that ``scan_head`` fills with the first mebibyte of
+the file. Shipping that verbatim would make a record larger than a phone photo's
+worth of metadata by two orders of magnitude, because for a PNG almost all of that
+mebibyte is compressed pixel data in ``IDAT`` -- bytes no provenance token can ever
+live in. A record carries the metadata REGIONS instead, walked per container: the
+JPEG marker segments before the coded scan, every PNG chunk but ``IDAT``, the RIFF
+chunks that are not coded image, the ISOBMFF provenance boxes, and in every case the
+container's trailer.
+
+COMPLETENESS IS A MEASURED PROPERTY, NOT A CLAIM
+
+A region walker is only correct if nothing the verdict reads falls outside the
+regions it keeps, and no test over fixtures can establish that: the failure mode is
+a container placement nobody thought of. The contract is therefore ALSO verified
+against the file path over a real corpus -- same image, both paths, identical
+``ProvenanceReport``.
+
+The placements that defeated an earlier draft of this collector, and the reason each
+rule below exists, are recorded in ``docs/module-internals.md`` under "Portable
+metadata record".
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import struct
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+from remove_ai_watermarks._internal.constants import PNG_SIGNATURE, RIFF_CODED_IMAGE_CHUNKS
+from remove_ai_watermarks._internal.schema import require_schema_version
+from remove_ai_watermarks.metadata import (
+    QUICK_SCAN_BYTES,
+    SAMSUNG_EDITOR_MARKER,
+    exif_text,
+    read_file_tail,
+)
+
+logger = logging.getLogger(__name__)
+
+# The structural walk covers the same window the file path reads raw, so the two
+# cannot disagree about a chunk type inside it. A smaller window would be cheaper but
+# opens a blind spot: past the window only ``png_late_metadata``'s ALLOWLIST is
+# collected, while the file path still sees every chunk type up to its own window --
+# and a C2PA ``caBX`` chunk is in neither that allowlist nor ``IDAT``. Walking here
+# costs little because the payload of the pixel stream is skipped, not copied.
+HEAD_WINDOW = 1024 * 1024
+# The window searched for the container's end marker. Matches the quick-scan window
+# the file path uses when it goes looking for a Samsung trailer, so a trailer visible
+# to one path is visible to the other.
+TAIL_WINDOW = QUICK_SCAN_BYTES
+# Kept from the tail when no end marker is found, so an unrecognized container still
+# contributes its last bytes without carrying half a photo.
+UNKNOWN_TRAILER_WINDOW = 64 * 1024
+
+# PNG text keys the file path reads for a generator tag, in ITS order. NovelAI stamps
+# Software/Source/Title rather than EXIF, and the first match wins, so order matters.
+_GENERATOR_TEXT_KEYS = ("Software", "Source", "Title", "Description")
+# Stable transport contract for records produced by this module. The version is
+# deliberately separate from the verdict version: collection and interpretation can
+# evolve independently as long as old records remain readable.
+METADATA_RECORD_SCHEMA_VERSION = 1
+METADATA_RECORD_TYPE = "provenance_metadata"
+
+
+def _jpeg_regions(data: bytes) -> bytes:
+    """Every marker segment up to the entropy-coded scan, plus the trailer after EOI.
+
+    The scan itself is skipped by walking to SOS and then jumping to the trailing
+    EOI, so a 20 MB photo contributes only its markers.
+
+    TWIN: ``metadata._strip_jpeg_metadata_lossless`` walks the same marker chain. The
+    two were left separate on purpose -- that one couples the walk to "return False and
+    fall back to a PIL re-encode", a decision the lossless strip path owns and this one
+    must not inherit -- so a fix to marker handling belongs in BOTH.
+    """
+    out = bytearray()
+    index, size = 2, len(data)
+    while index + 1 < size:
+        if data[index] != 0xFF:
+            break  # malformed boundary: keep what was collected, the tail still follows
+        marker = data[index + 1]
+        if marker in (0xDA, 0xD9):  # SOS / EOI: the coded scan follows
+            break
+        if 0xD0 <= marker <= 0xD7 or marker == 0x01:  # standalone, no length
+            index += 2
+            continue
+        if index + 4 > size:
+            break
+        segment_length = int.from_bytes(data[index + 2 : index + 4], "big")
+        end = index + 2 + segment_length
+        if segment_length < 2 or end > size:
+            break
+        out += data[index:end]
+        index = end
+    return bytes(out)
+
+
+def _png_regions(data: bytes) -> bytes:
+    """Every chunk except the ``IDAT`` payloads, plus whatever follows IEND.
+
+    TWIN: ``metadata._png_late_metadata`` walks the same chunk chain by SEEKING over
+    the file rather than over a buffer, and keeps an allowlist rather than skipping
+    ``IDAT``. Both filters are deliberate: inside the window the file path sees every
+    chunk type raw, past it only the allowlist survives.
+    """
+    out = bytearray()
+    size = len(data)
+    position = len(PNG_SIGNATURE)
+    while position + 8 <= size:
+        (length,) = struct.unpack(">I", data[position : position + 4])
+        chunk_type = data[position + 4 : position + 8]
+        start = position + 8
+        # Clamp the length to the bytes that remain: a malformed 32-bit length must
+        # not push the walk past EOF and abandon a genuine label chunk after it.
+        safe_length = max(0, min(length, size - start))
+        if chunk_type != b"IDAT":
+            out += chunk_type + data[start : start + safe_length]
+        position = start + safe_length + 4  # payload + CRC
+        if chunk_type == b"IEND":
+            out += data[position:]  # a trailer past IEND is metadata too
+            break
+    return bytes(out)
+
+
+def _riff_regions(data: bytes) -> bytes:
+    """Every RIFF chunk except the coded image payloads.
+
+    TWIN: ``metadata._riff_late_metadata`` (seek-based, past the scan window) and
+    ``_internal.riff`` (AVI ``LIST/INFO``). Same chunk-stepping arithmetic, three
+    input models.
+    """
+    out = bytearray(data[:12])  # 'RIFF' + size + 'WEBP'
+    declared_end = 8 + struct.unpack("<I", data[4:8])[0] if len(data) >= 12 else len(data)
+    size = min(len(data), declared_end)
+    position = 12
+    while position + 8 <= size:
+        chunk_type = data[position : position + 4]
+        (length,) = struct.unpack("<I", data[position + 4 : position + 8])
+        start = position + 8
+        safe_length = max(0, min(length, size - start))
+        if chunk_type not in RIFF_CODED_IMAGE_CHUNKS:
+            out += chunk_type + data[start : start + safe_length]
+        position = start + safe_length + (safe_length & 1)  # chunks are word-aligned
+    return bytes(out)
+
+
+def _isobmff_regions(image_path: Path, head: bytes) -> bytes:
+    """Header window plus the provenance regions the bounded box walkers find.
+
+    ISOBMFF hides a manifest in a ``uuid``/``jumb`` box that can sit after a
+    multi-megabyte ``mdat``, and a TC260 label in ``moov.udta``. Both walkers seek
+    rather than read the media, so neither pulls the payload in.
+    """
+    from remove_ai_watermarks._internal.isobmff import scan_c2pa_region, tc260_aigc_payloads
+
+    out = bytearray(head[:HEAD_WINDOW])
+    try:
+        out += scan_c2pa_region(image_path)
+    except Exception as exc:
+        logger.debug("ISOBMFF C2PA region scan failed on %s: %s", image_path, exc)
+    try:
+        for payload in tc260_aigc_payloads(image_path):
+            out += payload
+    except Exception as exc:
+        logger.debug("ISOBMFF TC260 scan failed on %s: %s", image_path, exc)
+    return bytes(out)
+
+
+def _container_regions(image_path: Path, head: bytes) -> tuple[str, bytes]:
+    """(container label, metadata bytes) for the container ``head`` starts with.
+
+    ``head`` must be the file's raw first bytes. Handing this the ``scan_head``
+    buffer instead is a trap: that buffer is the head CONCATENATED with late metadata
+    payloads, so a structural walk runs off the end of the real head and parses the
+    appended bytes as chunks, inflating the record and creating false signals.
+    """
+    from remove_ai_watermarks._internal.isobmff import is_isobmff
+    from remove_ai_watermarks.metadata import png_late_metadata, riff_late_metadata
+
+    if head.startswith(b"\xff\xd8"):
+        return "jpeg", _jpeg_regions(head)
+    if head.startswith(PNG_SIGNATURE):
+        # Chunks placed after the pixel stream (an XMP packet at 2.7 MB, say) are
+        # past the window; the same seek-past-IDAT reader the file path uses gets them.
+        return "png", _png_regions(head) + png_late_metadata(image_path, HEAD_WINDOW)
+    if head.startswith(b"RIFF") and head[8:12] == b"WEBP":
+        return "webp", _riff_regions(head) + riff_late_metadata(image_path, HEAD_WINDOW)
+    if is_isobmff(head):
+        return "isobmff", _isobmff_regions(image_path, head)
+    return "unknown", head
+
+
+def _raw_head(image_path: Path) -> bytes:
+    """The file's first bytes, unmodified -- the input every structural walk needs."""
+    try:
+        with open(image_path, "rb") as handle:
+            return handle.read(HEAD_WINDOW)
+    except OSError as exc:
+        logger.debug("head read failed for %s: %s", image_path, exc)
+        return b""
+
+
+def _trailer(image_path: Path, container: str) -> bytes:
+    """The bytes that follow the container's end marker, and nothing else.
+
+    A fixed-size tail read would be almost entirely pixels: the trailer of a 20 MB
+    photo is a few kilobytes at most. So the end marker is located in the tail window
+    and only what follows it is kept. When no marker is found (an unknown container,
+    or one whose end lies before the window) the window is kept as-is, bounded --
+    that is what a byte scan of the same file would have seen anyway.
+    """
+    if container == "webp":
+        # RIFF declares its structural end in bytes 4..8. A fixed tail window is
+        # normally the last animation/frame payload, not a trailer, so preserve
+        # only bytes appended after the declared RIFF container.
+        try:
+            with open(image_path, "rb") as handle:
+                header = handle.read(12)
+                if len(header) < 12 or not header.startswith(b"RIFF"):
+                    return b""
+                declared_end = 8 + struct.unpack("<I", header[4:8])[0]
+                handle.seek(0, 2)
+                file_size = handle.tell()
+                if declared_end < 12 or declared_end >= file_size:
+                    return b""
+                handle.seek(declared_end)
+                return handle.read(min(file_size - declared_end, UNKNOWN_TRAILER_WINDOW))
+        except OSError as exc:
+            logger.debug("RIFF trailer read failed for %s: %s", image_path, exc)
+            return b""
+    if container == "isobmff":
+        # ISOBMFF has no out-of-container trailer convention. Its bounded box
+        # walkers already collect late provenance while skipping ``mdat``; keeping
+        # a blind tail here would carry coded media bytes.
+        return b""
+
+    tail = read_file_tail(image_path, TAIL_WINDOW)
+    if SAMSUNG_EDITOR_MARKER in tail:
+        # Galaxy AI splits its evidence: the marker sits in the post-EOI trailer, but
+        # the `genAIType` value it is gated on can sit INSIDE the entropy-coded scan.
+        # Keeping only the trailer therefore carries the marker without the value and the
+        # verdict silently drops the Samsung signal, so a marked file keeps the whole
+        # window. Only Samsung-marked files pay for it.
+        return tail
+    marker = {"jpeg": b"\xff\xd9", "png": b"IEND\xae\x42\x60\x82"}.get(container)
+    if marker is None:
+        return tail[-UNKNOWN_TRAILER_WINDOW:]
+    index = tail.rfind(marker)
+    return tail[index + len(marker) :] if index >= 0 else tail[-UNKNOWN_TRAILER_WINDOW:]
+
+
+def _decoder_info(image_path: Path) -> dict[str, Any]:
+    """PIL's ``info`` mapping, read once.
+
+    One open for both consumers below. They want different parts of the same mapping
+    (the text keys, and the raw EXIF blob), and opening twice repeats the container
+    header parse and, for a PNG carrying ``zTXt``, the zlib inflate with it.
+    """
+    try:
+        from PIL import Image
+
+        with Image.open(image_path) as img:
+            # PIL types this mapping with a non-string key union (a DPI tuple key
+            # exists), so the keys are normalized here rather than assumed.
+            return {str(key): value for key, value in img.info.items()}
+    except Exception as exc:  # a container PIL cannot open
+        logger.debug("PIL info unavailable for %s: %s", image_path, exc)
+        return {}
+
+
+def _exif_pairs(info: dict[str, Any]) -> dict[str, str]:
+    """The 0th-IFD tags the verdict reads, under their tag NAMES.
+
+    Not a convenience: two probes key on names rather than on the raw bytes already
+    in the regions. ``xai_signature_pair`` wants an (ImageDescription, Artist) pair,
+    and ``_external_exif_generator`` looks for Software / Make / Artist /
+    ImageDescription. Ship the bytes alone and both silently return nothing, which
+    is how a collector can silently lose Grok and NovelAI verdicts.
+    """
+    exif_bytes = info.get("exif")
+    if not exif_bytes:
+        return {}
+    try:
+        import piexif
+
+        tags = piexif.load(exif_bytes).get("0th", {})
+    except Exception as exc:  # malformed EXIF
+        logger.debug("EXIF parse failed: %s", exc)
+        return {}
+
+    return {
+        name: text
+        for name, tag in (
+            ("Software", piexif.ImageIFD.Software),
+            ("Make", piexif.ImageIFD.Make),
+            ("Artist", piexif.ImageIFD.Artist),
+            ("ImageDescription", piexif.ImageIFD.ImageDescription),
+        )
+        if (text := exif_text(tags, tag))
+    }
+
+
+def _pil_info(info: dict[str, Any]) -> dict[str, str]:
+    """PIL's ``info`` mapping as strings, the source of PNG text keys and ``hf-job-id``."""
+
+    def text_of(value: Any) -> str:
+        return value.decode("utf-8", "replace") if isinstance(value, bytes) else str(value)
+
+    # Emitted in the file path's own candidate order. ``generator_from_metadata``
+    # returns the FIRST candidate carrying a known token. A record using PIL's natural
+    # dict order can therefore choose a different platform string than the file path,
+    # even though the two paths are supposed to be indistinguishable.
+    out: dict[str, str] = {}
+    for key in _GENERATOR_TEXT_KEYS:
+        value = info.get(key)
+        if value is not None and not isinstance(value, (dict, list, tuple)):
+            out[f"info:{key}"] = text_of(value)
+    for key, value in info.items():
+        if key in _GENERATOR_TEXT_KEYS or isinstance(value, (dict, list, tuple)):
+            continue
+        out[f"info:{key}"] = text_of(value)
+    return out
+
+
+def collect_metadata_record(
+    image_path: Path,
+    *,
+    schema_version: int = METADATA_RECORD_SCHEMA_VERSION,
+) -> dict[str, Any]:
+    """Collect everything the provenance verdict reads, as a JSON-safe record.
+
+    The record is the transport format for
+    :func:`identify.evidence_from_metadata_record`: it carries the metadata regions
+    (base64), the C2PA manifest store, and PIL's info mapping without carrying the
+    primary coded-pixel stream. Schema and collection status are explicit so a
+    consumer cannot mistake a failed read for an unknown provenance verdict.
+
+    Args:
+        image_path: Path to the image.
+        schema_version: Output schema implemented by the consumer.
+
+    Returns:
+        A versioned JSON-serializable dict. ``metadata_base64`` holds the
+        concatenated container regions, ``tail_base64`` the file trailer.
+    """
+    schema_version = require_schema_version(
+        schema_version,
+        contract="provenance metadata",
+        supported=(1,),
+    )
+
+    from remove_ai_watermarks._internal.c2pa import read_manifest_store_json
+
+    try:
+        image_path.stat()
+        status = "complete"
+        issues: list[dict[str, str]] = []
+    except OSError as exc:
+        logger.debug("metadata source unavailable for %s: %s", image_path, exc)
+        status = "error"
+        issues = [{"stage": "source", "code": "unavailable"}]
+
+    container, regions = _container_regions(image_path, _raw_head(image_path))
+
+    info = _decoder_info(image_path)
+    record: dict[str, Any] = {
+        "schema_version": schema_version,
+        "record_type": METADATA_RECORD_TYPE,
+        "status": status,
+        "issues": issues,
+        "container": container,
+        "name": image_path.name,
+        "metadata_base64": base64.b64encode(regions).decode("ascii"),
+        # Always collected: Samsung's Galaxy AI marker is a post-EOI trailer, and a
+        # record without it loses that verdict outright.
+        "tail_base64": base64.b64encode(_trailer(image_path, container)).decode("ascii"),
+        # PIL info BEFORE exif: the file path prefers a PNG text tag over an EXIF
+        # one, and the normalizer walks the record in insertion order.
+        "pil": _pil_info(info),
+        "exif": _exif_pairs(info),
+    }
+    store = read_manifest_store_json(image_path)
+    if store is not None:
+        record["c2pa_store"] = store
+    return record

src/remove_ai_watermarks/noai/__init__.py

@@ -1,38 +0,0 @@
-"""Vendored noai-watermark code for invisible watermark removal.
-
-Original: https://github.com/mertizci/noai-watermark (MIT License)
-
-The public API (``WatermarkRemover`` / ``remove_watermark`` / ``remove_ai_metadata``)
-is exposed **lazily** via PEP 562 ``__getattr__``: importing a light submodule
-(e.g. ``noai.c2pa`` / ``noai.constants`` from ``identify``) must NOT eagerly pull
-``watermark_remover``, which imports torch + diffusers at module top. Keeping this
-lazy is what lets ``import remove_ai_watermarks.identify`` stay cheap (~36 MB, no
-torch) even in a full install where the ``gpu``/``detect`` extras are present --
-otherwise the mere presence of torch in the env inflated identify to ~420 MB and
-risked OOM on a 512 MB host.
-"""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from remove_ai_watermarks.metadata import remove_ai_metadata
-    from remove_ai_watermarks.noai.watermark_remover import WatermarkRemover, remove_watermark
-
-__all__ = ["WatermarkRemover", "remove_ai_metadata", "remove_watermark"]
-
-
-def __getattr__(name: str) -> object:
-    """Resolve the public API on first access (PEP 562), not at package import."""
-    if name == "remove_ai_metadata":
-        # Re-export the single, robust stripper (byte-level, lossless-for-JPEG, all
-        # containers); the old noai.cleaner implementation is retired.
-        from remove_ai_watermarks.metadata import remove_ai_metadata
-
-        return remove_ai_metadata
-    if name in ("WatermarkRemover", "remove_watermark"):
-        from remove_ai_watermarks.noai import watermark_remover
-
-        return getattr(watermark_remover, name)
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/remove_ai_watermarks/noai/c2pa.py

@@ -1,532 +0,0 @@
-"""C2PA (Coalition for Content Provenance and Authenticity) metadata handling.
-
-Reading goes through the official c2pa-python ``Reader`` first (any container it
-supports), via ``extract_c2pa_info`` / ``read_manifest_store_json``. The
-hand-rolled PNG ``caBX`` JUMBF-chunk tools below (``has_c2pa_metadata`` /
-``extract_c2pa_chunk`` / ``inject_c2pa_chunk`` and the ``_extract_c2pa_info_png``
-fallback) cover raw-chunk extraction, re-injection, and the cases the validator
-rejects (synthetic/partial blobs, a broken/absent wheel). Known issuers:
-
-- Google Imagen
-- Adobe Firefly
-- Microsoft Designer
-- OpenAI (ChatGPT, GPT-4o, Sora, DALL-E)
-- Truepic (signing authority)
-
-The fallback parser uses byte-level scanning — it does not validate JUMBF/CBOR
-structure but reliably identifies known signatures, issuers, tools, and actions.
-The vendor / source-type / SynthID / soft-binding registry scan
-(``_populate_registry_fields``) is shared by both the reader and fallback paths.
-"""
-
-from __future__ import annotations
-
-import contextlib
-import functools
-import json
-import logging
-import re
-import struct
-from pathlib import Path
-from typing import Any, cast
-
-from remove_ai_watermarks.noai.constants import (
-    C2PA_ACTIONS,
-    C2PA_AI_TOOLS,
-    C2PA_CHUNK_TYPE,
-    C2PA_ISSUERS,
-    C2PA_SIGNATURES,
-    C2PA_SOFT_BINDINGS,
-    PNG_SIGNATURE,
-    SYNTHID_C2PA_ISSUERS,
-)
-
-logger = logging.getLogger(__name__)
-
-# Official C2PA reader (c2pa-python, a core dependency). It is the primary,
-# spec-tracking manifest parser; the hand-rolled caBX/CBOR scanner below stays as
-# a fallback for synthetic/partial blobs the validator rejects. The import is
-# guarded so a partially-broken install degrades to the byte-scan rather than
-# crashing the dependency-light identify path.
-_C2paReader: Any = None
-with contextlib.suppress(Exception):  # broken/absent wheel -> byte-scan fallback
-    from c2pa import Reader as _C2paReader  # pyright: ignore[reportMissingTypeStubs]
-_C2PA_READER_AVAILABLE = _C2paReader is not None
-
-
-def reader_available() -> bool:
-    """True when the official c2pa-python Reader imported successfully."""
-    return _C2PA_READER_AVAILABLE
-
-
-def read_manifest_store_json(image_path: Path) -> str | None:
-    """Return the full C2PA manifest-store JSON for ``image_path``, or None.
-
-    Uses the official c2pa-python ``Reader`` (any container it supports: PNG,
-    JPEG, WebP, AVIF/HEIF, MP4, ...). Returns None when the reader is unavailable,
-    the file carries no parseable manifest, or parsing fails. The JSON is the
-    WHOLE store (every manifest plus ingredient manifests), matching the
-    whole-chunk semantics of the legacy byte scan -- an AI-source marker in a
-    parent/ingredient manifest (e.g. a ChatGPT edit of a Sora generation) is
-    still seen.
-
-    Memoized per (path, mtime): one identify/get_ai_metadata call invokes the
-    structured parser ~3 times on the same file, so the cache turns the repeated
-    crypto-validating reads into one.
-    """
-    if not _C2PA_READER_AVAILABLE:
-        return None
-    try:
-        mtime = image_path.stat().st_mtime_ns
-    except OSError:
-        return _read_manifest_store_impl(str(image_path))
-    return _read_manifest_store_cached(str(image_path), mtime)
-
-
-@functools.lru_cache(maxsize=8)
-def _read_manifest_store_cached(path_str: str, _mtime_ns: int) -> str | None:
-    """Cache shim: ``_mtime_ns`` is part of the key only (invalidates on change)."""
-    return _read_manifest_store_impl(path_str)
-
-
-def _read_manifest_store_impl(path_str: str) -> str | None:
-    # try_create returns None when there is no manifest; a default Reader does no
-    # trust enforcement, so an untrusted signer still yields the manifest content
-    # (we report what is in the file, we do not gate on certificate trust).
-    try:
-        reader = _C2paReader.try_create(path_str)
-    except Exception as exc:  # malformed manifest, unsupported container, etc.
-        logger.debug("c2pa Reader could not parse %s: %s", path_str, exc)
-        return None
-    if reader is None:
-        return None
-    try:
-        with reader:
-            return reader.json()
-    except Exception as exc:  # pragma: no cover - reader opened but json() failed
-        logger.debug("c2pa Reader.json() failed on %s: %s", path_str, exc)
-        return None
-
-
-def has_c2pa_metadata(image_path: Path) -> bool:
-    """
-    Check if an image contains C2PA metadata.
-
-    Args:
-        image_path: Path to the image file.
-
-    Returns:
-        True if C2PA metadata is detected, False otherwise.
-    """
-    image_path = Path(image_path)
-
-    if image_path.suffix.lower() != ".png":
-        return False
-
-    try:
-        with open(image_path, "rb") as f:
-            signature = f.read(8)
-            if signature != PNG_SIGNATURE:
-                return False
-
-            file_size = f.seek(0, 2)
-            f.seek(8)
-
-            while True:
-                chunk_header = f.read(8)
-                if len(chunk_header) < 8:
-                    break
-
-                length = struct.unpack(">I", chunk_header[:4])[0]
-                chunk_type = chunk_header[4:8]
-                # Clamp the attacker-controlled 32-bit length to the bytes that
-                # actually remain, so a malformed huge length can't allocate GBs.
-                safe_length = max(0, min(length, file_size - f.tell()))
-
-                if chunk_type == C2PA_CHUNK_TYPE:
-                    chunk_data = f.read(safe_length)
-                    # Check for any C2PA signature
-                    for sig in C2PA_SIGNATURES:
-                        if sig in chunk_data:
-                            return True
-                    # Also check if chunk_data itself contains C2PA-like patterns
-                    if b"jumb" in chunk_data.lower() or b"c2pa" in chunk_data.lower():
-                        return True
-                    f.read(4)
-                else:
-                    f.seek(safe_length + 4, 1)
-
-                if chunk_type == b"IEND":
-                    break
-    except Exception:
-        pass
-
-    return False
-
-
-def _claim_generator_from_store(store: dict[str, Any]) -> str | None:
-    """Structured claim-generator name from the active manifest of a store dict.
-
-    Prefers the top-level ``claim_generator`` string (Firefly: "Adobe_Firefly"),
-    falling back to the first ``claim_generator_info[].name`` (ChatGPT keys it
-    only there). isprintable() guards against odd binary-ish values.
-    """
-    active = _active_manifest(store)
-    generator: Any = active.get("claim_generator")
-    if not (isinstance(generator, str) and generator):
-        info_list: list[Any] = active.get("claim_generator_info") or []
-        if info_list and isinstance(first := info_list[0], dict):
-            generator = cast("dict[str, Any]", first).get("name")
-    return generator if isinstance(generator, str) and generator and generator.isprintable() else None
-
-
-def _active_manifest(store: dict[str, Any]) -> dict[str, Any]:
-    """The active manifest dict from a manifest-store dict, or {} when absent."""
-    manifests: Any = store.get("manifests")
-    if not isinstance(manifests, dict):
-        return {}
-    active = cast("dict[str, Any]", manifests).get(store.get("active_manifest", ""))
-    return cast("dict[str, Any]", active) if isinstance(active, dict) else {}
-
-
-def _info_from_store_json(store_json: str) -> dict[str, Any]:
-    """Build the C2PA info dict from a c2pa-python manifest-store JSON string."""
-    store_bytes = store_json.encode("utf-8")
-    c2pa_info: dict[str, Any] = {
-        "has_c2pa": True,
-        "type": "C2PA (Coalition for Content Provenance and Authenticity)",
-        "c2pa_manifest": f"C2PA manifest store ({len(store_bytes)} bytes)",
-    }
-    # The whole-store JSON carries every vendor / source-type / SynthID /
-    # soft-binding signature (across active + ingredient manifests), so the same
-    # registry scan that runs on the raw caBX chunk applies unchanged here.
-    _populate_registry_fields(store_bytes, c2pa_info)
-
-    try:
-        parsed: Any = json.loads(store_json)
-    except (ValueError, TypeError):
-        return c2pa_info
-    if not isinstance(parsed, dict):
-        return c2pa_info
-    store = cast("dict[str, Any]", parsed)
-    if generator := _claim_generator_from_store(store):
-        c2pa_info["claim_generator"] = generator
-    sig: Any = _active_manifest(store).get("signature_info")
-    if isinstance(sig, dict) and (time := cast("dict[str, Any]", sig).get("time")):
-        c2pa_info["timestamp"] = str(time)
-    return c2pa_info
-
-
-def extract_c2pa_info(image_path: Path) -> dict[str, Any]:
-    """
-    Extract C2PA metadata information from an image.
-
-    Uses the official c2pa-python reader first (any supported container), falling
-    back to the hand-rolled PNG caBX parser when the reader is unavailable or the
-    file carries no parseable manifest (synthetic/partial blobs).
-
-    Args:
-        image_path: Path to the image file.
-
-    Returns:
-        Dictionary containing C2PA metadata info, or {} when none is found.
-    """
-    image_path = Path(image_path)
-
-    if (store_json := read_manifest_store_json(image_path)) is not None:
-        return _info_from_store_json(store_json)
-
-    return _extract_c2pa_info_png(image_path)
-
-
-def _extract_c2pa_info_png(image_path: Path) -> dict[str, Any]:
-    """Fallback PNG caBX parser, used when the c2pa-python reader finds nothing."""
-    c2pa_info: dict[str, Any] = {}
-
-    if not has_c2pa_metadata(image_path):
-        return c2pa_info
-
-    c2pa_info["has_c2pa"] = True
-    c2pa_info["type"] = "C2PA (Coalition for Content Provenance and Authenticity)"
-
-    try:
-        with open(image_path, "rb") as f:
-            signature = f.read(8)
-            if signature != PNG_SIGNATURE:
-                return c2pa_info
-
-            file_size = f.seek(0, 2)
-            f.seek(8)
-
-            while True:
-                chunk_header = f.read(8)
-                if len(chunk_header) < 8:
-                    break
-
-                length = struct.unpack(">I", chunk_header[:4])[0]
-                chunk_type = chunk_header[4:8]
-                # Clamp the attacker-controlled 32-bit length to the bytes that
-                # actually remain, so a malformed huge length can't allocate GBs.
-                safe_length = max(0, min(length, file_size - f.tell()))
-
-                if chunk_type == C2PA_CHUNK_TYPE:
-                    chunk_data = f.read(safe_length)
-                    _parse_c2pa_chunk(chunk_data, c2pa_info)
-                    f.read(4)
-                else:
-                    f.seek(safe_length + 4, 1)
-
-                if chunk_type == b"IEND":
-                    break
-    except Exception:
-        pass
-
-    return c2pa_info
-
-
-def cbor_text_after(payload: bytes, key: bytes) -> str | None:
-    """Return the CBOR text-string immediately following ``key`` in ``payload``.
-
-    Handles CBOR major-type 3 length prefixes: direct (0x60-0x77), 1-byte
-    (0x78 NN), and 2-byte (0x79 NN NN). This reads the actual encoded value, so
-    it avoids the byte-grabbing artifacts a loose regex produces (e.g. the
-    leading length byte showing up as ``fGPT-4o``).
-    """
-    idx = payload.find(key)
-    if idx < 0:
-        return None
-    p = idx + len(key)
-    if p >= len(payload):
-        return None
-    head = payload[p]
-    if 0x60 <= head <= 0x77:
-        length, start = head - 0x60, p + 1
-    elif head == 0x78 and p + 1 < len(payload):
-        length, start = payload[p + 1], p + 2
-    elif head == 0x79 and p + 2 < len(payload):
-        length, start = (payload[p + 1] << 8) | payload[p + 2], p + 3
-    else:
-        return None
-    raw_str = payload[start : start + length]
-    try:
-        return raw_str.decode("utf-8")
-    except UnicodeDecodeError:
-        return raw_str.decode("latin1", errors="replace")
-
-
-def synthid_verdict(vendors: str) -> str:
-    """Human-readable SynthID-source verdict, shared by all callers."""
-    return f"likely present ({vendors} embeds SynthID with C2PA)"
-
-
-def synthid_vendors_in(buffer: bytes) -> list[str]:
-    """Return SynthID-using C2PA issuer names whose signature appears in ``buffer``.
-
-    Shared by the PNG caBX parser and the format-agnostic binary scan so both
-    apply the same SYNTHID_C2PA_ISSUERS rule against their respective bytes.
-    """
-    return sorted({name for sig, name in C2PA_ISSUERS.items() if sig in buffer and sig in SYNTHID_C2PA_ISSUERS})
-
-
-def soft_binding_vendors_in(buffer: bytes) -> list[str]:
-    """Return forensic-watermark vendor names whose C2PA soft-binding ``alg``
-    identifier appears in ``buffer``.
-
-    A ``c2pa.soft-binding`` assertion names the watermark scheme that stamped the
-    pixels (Adobe TrustMark, Digimarc, Imatag, Steg.AI, ...). Shared by the PNG
-    caBX parser and the format-agnostic binary scan so both apply the same
-    C2PA_SOFT_BINDINGS rule against their respective bytes.
-    """
-    return sorted({name for sig, name in C2PA_SOFT_BINDINGS.items() if sig in buffer})
-
-
-def _populate_registry_fields(buf: bytes, c2pa_info: dict[str, Any]) -> bool:
-    """Populate the registry-driven C2PA fields by scanning ``buf``.
-
-    Shared by the legacy caBX-chunk parser and the c2pa-python store-JSON path so
-    both produce an identical dict shape. ``buf`` is the raw manifest bytes for
-    the former and the manifest-store JSON (UTF-8) for the latter; the vendor /
-    tool / action / source-type / SynthID / soft-binding signatures appear in
-    both. Sets ``issuer``, ``ai_tool``, ``actions``, ``source_type``,
-    ``synthid_vendors`` / ``synthid_watermark``, ``soft_binding_vendors`` /
-    ``soft_binding`` when present and returns whether the source type is AI.
-    """
-    if issuers := [name for sig, name in C2PA_ISSUERS.items() if sig in buf]:
-        c2pa_info["issuer"] = ", ".join(dict.fromkeys(issuers))
-
-    if ai_tools := [name for sig, name in C2PA_AI_TOOLS.items() if sig in buf]:
-        c2pa_info["ai_tool"] = ", ".join(dict.fromkeys(ai_tools))
-
-    if actions := [name for sig, name in C2PA_ACTIONS.items() if sig in buf]:
-        c2pa_info["actions"] = ", ".join(actions)
-
-    # Digital source type (matched anywhere in the store, including ingredient
-    # manifests -- a ChatGPT edit of a Sora generation carries the AI marker on
-    # the parent, not the active manifest).
-    # ``ai_source_kind`` is the structured generated-vs-enhanced split the caller
-    # branches on (full-frame scrub vs region-targeted clean); ``source_type`` is the
-    # human-readable form. The two byte strings are unambiguous:
-    # "compositeWithTrainedAlgorithmicMedia" capitalizes the inner "Trained", so a
-    # lowercase "trainedAlgorithmicMedia" match is standalone full generation, which
-    # wins when both appear (an edit chain).
-    ai_source = False
-    if b"trainedAlgorithmicMedia" in buf:
-        c2pa_info["source_type"] = "trainedAlgorithmicMedia (AI-generated)"
-        c2pa_info["ai_source_kind"] = "generated"
-        ai_source = True
-    elif b"compositeWithTrainedAlgorithmicMedia" in buf:
-        # Checked BEFORE bare ``algorithmicMedia``: a manifest can carry both tokens
-        # (an AI-enhanced composite with a procedural ingredient), and the bare-token
-        # branch would otherwise fire first and misclassify the AI composite as non-AI.
-        c2pa_info["source_type"] = "compositeWithTrainedAlgorithmicMedia (AI-enhanced)"
-        c2pa_info["ai_source_kind"] = "enhanced"
-        ai_source = True
-    elif b"algorithmicMedia" in buf:
-        c2pa_info["source_type"] = "algorithmicMedia"
-
-    # SynthID pixel-watermark proxy: a C2PA manifest from a SynthID-using
-    # vendor (Google/OpenAI) on AI-generated content implies an invisible
-    # SynthID watermark in the pixels (see SYNTHID_C2PA_ISSUERS).
-    synthid_vendors = synthid_vendors_in(buf)
-    if synthid_vendors and ai_source:
-        c2pa_info["synthid_vendors"] = synthid_vendors
-        c2pa_info["synthid_watermark"] = synthid_verdict(", ".join(synthid_vendors))
-
-    # Soft-binding: a forensic/third-party watermark vendor named in the
-    # manifest (Adobe TrustMark, Digimarc, ...), independent of the issuer.
-    soft_binding_vendors = soft_binding_vendors_in(buf)
-    if soft_binding_vendors:
-        c2pa_info["soft_binding_vendors"] = soft_binding_vendors
-        c2pa_info["soft_binding"] = ", ".join(soft_binding_vendors)
-
-    return ai_source
-
-
-def _parse_c2pa_chunk(chunk_data: bytes, c2pa_info: dict[str, Any]) -> None:
-    """Parse a raw caBX chunk payload and populate the info dictionary.
-
-    The fallback path, used when the official c2pa-python reader is unavailable
-    or rejects the file (synthetic/partial blobs, broken installs).
-    """
-    c2pa_info["c2pa_manifest"] = f"C2PA manifest ({len(chunk_data)} bytes)"
-
-    _populate_registry_fields(chunk_data, c2pa_info)
-
-    # Claim generator and spec version: read the CBOR text-string values
-    # directly (regex byte-grabbing produced artifacts like ``fGPT-4o``).
-    # Guard with isprintable(): on some manifests (e.g. Microsoft Designer) the
-    # first ``name`` key precedes a binary field (a hash), not the generator
-    # string, which would otherwise surface as control-char garbage.
-    if (generator := cbor_text_after(chunk_data, b"name")) and generator.isprintable():
-        c2pa_info["claim_generator"] = generator
-    if (spec := cbor_text_after(chunk_data, b"specVersion")) and spec.isprintable():
-        c2pa_info["c2pa_spec"] = spec
-
-    # Find timestamps
-    timestamp_matches = re.findall(rb"(\d{14}Z)", chunk_data)
-    if timestamp_matches:
-        c2pa_info["timestamp"] = timestamp_matches[0].decode("utf-8")
-        if len(timestamp_matches) > 1:
-            c2pa_info["timestamps"] = [t.decode("utf-8") for t in timestamp_matches[:3]]
-
-
-def extract_c2pa_chunk(image_path: Path) -> bytes | None:
-    """
-    Extract the raw C2PA JUMBF chunk from a PNG file.
-
-    Args:
-        image_path: Path to the source PNG file.
-
-    Returns:
-        Raw bytes of the C2PA chunk or None.
-    """
-    if image_path.suffix.lower() != ".png":
-        return None
-
-    try:
-        with open(image_path, "rb") as f:
-            signature = f.read(8)
-            if signature != PNG_SIGNATURE:
-                return None
-
-            file_size = f.seek(0, 2)
-            f.seek(8)
-
-            while True:
-                chunk_header = f.read(8)
-                if len(chunk_header) < 8:
-                    break
-
-                length = struct.unpack(">I", chunk_header[:4])[0]
-                chunk_type = chunk_header[4:8]
-                # Clamp the attacker-controlled 32-bit length to the bytes that
-                # actually remain, so a malformed huge length can't allocate GBs.
-                safe_length = max(0, min(length, file_size - f.tell()))
-
-                if chunk_type == C2PA_CHUNK_TYPE:
-                    chunk_data = f.read(safe_length)
-                    crc = f.read(4)
-
-                    # Check for any C2PA signature
-                    for sig in C2PA_SIGNATURES:
-                        if sig in chunk_data:
-                            return chunk_header + chunk_data + crc
-
-                    # Also check lowercase variants
-                    if b"jumb" in chunk_data.lower() or b"c2pa" in chunk_data.lower():
-                        return chunk_header + chunk_data + crc
-                else:
-                    f.seek(safe_length + 4, 1)
-
-                if chunk_type == b"IEND":
-                    break
-    except Exception:
-        pass
-
-    return None
-
-
-def inject_c2pa_chunk(target_path: Path, output_path: Path, c2pa_chunk: bytes) -> None:
-    """
-    Inject a C2PA JUMBF chunk into a PNG file.
-
-    Args:
-        target_path: Path to the target PNG file.
-        output_path: Path where the output file will be saved.
-        c2pa_chunk: Raw bytes of the C2PA chunk to inject.
-
-    Raises:
-        ValueError: If not PNG files.
-    """
-    if target_path.suffix.lower() != ".png" or output_path.suffix.lower() != ".png":
-        raise ValueError("C2PA chunk injection is only supported for PNG files")
-
-    output_path.parent.mkdir(parents=True, exist_ok=True)
-
-    with open(target_path, "rb") as f_in, open(output_path, "wb") as f_out:
-        f_out.write(f_in.read(8))
-
-        c2pa_injected = False
-        while True:
-            chunk_header = f_in.read(8)
-            if len(chunk_header) < 8:
-                break
-
-            length = struct.unpack(">I", chunk_header[:4])[0]
-            chunk_type = chunk_header[4:8]
-            chunk_data = f_in.read(length)
-            crc = f_in.read(4)
-
-            if chunk_type == b"IDAT" and not c2pa_injected:
-                f_out.write(c2pa_chunk)
-                c2pa_injected = True
-
-            if chunk_type == C2PA_CHUNK_TYPE:
-                continue
-
-            f_out.write(chunk_header)
-            f_out.write(chunk_data)
-            f_out.write(crc)
-
-            if chunk_type == b"IEND":
-                break

src/remove_ai_watermarks/noai/constants.py

@@ -1,342 +0,0 @@
-"""Shared constants for AI metadata detection, C2PA parsing, and format support.
-
-All modules reference these constants rather than hard-coding values,
-so adding a new AI tool or metadata key requires updating only this file.
-"""
-
-from typing import NamedTuple
-
-# Supported image formats for the pixel/removal path (CLI input validation + batch
-# discovery). PNG/JPEG/WebP decode+encode via cv2; HEIC/HEIF/AVIF via the core
-# pillow-heif dep (image_io.imread Pillow fallback + imwrite _pil_write), so batch
-# now picks them up and the CLI no longer warns on an iPhone HEIC. JPEG-XL is left
-# out on purpose -- it is metadata/strip-only (no pixel decoder without pillow-jxl).
-SUPPORTED_FORMATS = {".png", ".jpg", ".jpeg", ".webp", ".heic", ".heif", ".avif"}
-
-# AI-generated image metadata keys (Stable Diffusion, ComfyUI, Midjourney, etc.)
-AI_METADATA_KEYS = [
-    "parameters",  # Stable Diffusion WebUI (AUTOMATIC1111, Vladmandic)
-    "postprocessing",  # SD WebUI post-processing info
-    "extras",  # SD WebUI extras
-    "workflow",  # ComfyUI workflow JSON
-    "prompt",  # Some AI tools
-    "Dream",  # DreamStudio
-    "SD:mode",  # Stability AI
-    "StableDiffusionVersion",  # SD version info
-    "generation_time",  # Generation time info
-    "Model",  # Model name
-    "Model hash",  # Model hash
-    "Seed",  # Seed value
-]
-
-# Standard PNG metadata keys
-PNG_METADATA_KEYS = [
-    "Author",
-    "Title",
-    "Description",
-    "Copyright",
-    "Creation Time",
-    "Software",
-    "Disclaimer",
-    "Warning",
-    "Source",
-    "Comment",
-]
-
-# AI-related keywords for detection
-AI_KEYWORDS = [
-    "prompt",
-    "negative_prompt",
-    "sampler",
-    "cfg_scale",
-    "lora",
-    "diffusion",
-    "comfy",
-    "midjourney",
-    "dall-e",
-    "dalle",
-    "imagen",
-    "firefly",
-    "c2pa",
-    "chatgpt",
-    "gpt-4",
-    "sora",
-    "openai",
-    "truepic",
-    "stable_diffusion",
-    "invokeai",
-]
-
-# C2PA (Coalition for Content Provenance and Authenticity) constants
-# Used by Google Imagen, Adobe Firefly, Microsoft Designer, OpenAI, etc.
-C2PA_CHUNK_TYPE = b"caBX"  # JUMBF container chunk type for C2PA
-C2PA_SIGNATURES = [
-    b"c2pa",
-    b"C2PA",
-    b"jumb",
-    b"jumd",
-    b"JUMBF",
-    b"jumbf",
-    b"cbor",
-    b"contentcreds",
-    b"digid",
-    b"assertions",
-    b"manifest",
-]
-
-
-# Single source of truth for every C2PA-signing vendor. The three per-vendor
-# facts that used to live in separate tables -- the issuer byte signature
-# (C2PA_ISSUERS), the SynthID pairing (SYNTHID_C2PA_ISSUERS), and the human
-# platform label (identify._ISSUER_PLATFORM) -- are all fields here, so adding a
-# new C2PA vendor is a single append below; the views derive automatically.
-class C2paAiVendor(NamedTuple):
-    issuer: bytes  # distinctive byte signature scanned in the manifest (cert org / signer)
-    org: str  # resolved issuer/cert-org display name (the old C2PA_ISSUERS value)
-    # Human platform label for identify; None marks a signing authority / non-generator
-    # (e.g. Truepic), which never names an AI platform on its own.
-    platform: str | None
-    # Substring matched against the joined issuer-org names for platform attribution
-    # (usually a shorter form of org, e.g. "Google" for "Google LLC"); None when platform is.
-    needle: str | None
-    synthid: bool = False  # vendor pairs an invisible SynthID pixel watermark with its C2PA manifest
-    # The vendor's mere presence in the manifest asserts AI generation even without
-    # a digitalSourceType (``trainedAlgorithmicMedia``) assertion. Set ONLY for a
-    # pure-generator brand whose issuer/generator byte string is unambiguous (e.g.
-    # "Dreamina"). Do NOT set for common-word issuers (Adobe/Google/OpenAI/Microsoft):
-    # those appear incidentally in unrelated XMP/trust-chain bytes, so they stay
-    # source-type-gated in identify._attribute_platform.
-    asserts_ai: bool = False
-
-
-# C2PA known vendors, ORDERED for first-match-wins platform attribution: when a
-# manifest names several issuers (Microsoft Designer signs as "OpenAI, Microsoft"),
-# the earlier entry wins so the product, not the backend engine, is named.
-# Used by Google Imagen, Adobe Firefly, Microsoft Designer, OpenAI, etc.
-C2PA_AI_VENDORS: tuple[C2paAiVendor, ...] = (
-    # Microsoft signs both Designer and Bing Image Creator; Bing now runs its own
-    # MAI-Image model (not DALL-E), so the label stays model-neutral.
-    C2paAiVendor(b"Microsoft", "Microsoft", "Microsoft (Bing Image Creator / Designer)", "Microsoft"),
-    C2paAiVendor(b"Adobe", "Adobe", "Adobe Firefly", "Adobe"),
-    C2paAiVendor(b"OpenAI", "OpenAI", "OpenAI (ChatGPT / gpt-image / DALL-E / Sora)", "OpenAI", synthid=True),
-    C2paAiVendor(b"Google", "Google LLC", "Google (Gemini / Imagen)", "Google", synthid=True),
-    # Stability AI signs C2PA as "Stability AI" (cert org "Stability AI Ltd").
-    # Verified on a live Brand Studio (DreamStudio successor) output, 2026-05-24.
-    C2paAiVendor(b"Stability AI", "Stability AI", "Stability AI (Stable Image / DreamStudio)", "Stability AI"),
-    # Black Forest Labs (FLUX) API output: claim_generator_info "Black Forest
-    # Labs API" + a c2pa.ai_generated_content assertion + trainedAlgorithmicMedia.
-    # Verified on a real signed FLUX JPEG, 2026-05-29.
-    C2paAiVendor(b"Black Forest Labs", "Black Forest Labs", "Black Forest Labs (FLUX)", "Black Forest Labs"),
-    # ByteDance's Volcano Engine (Volcengine) signs its AI image output with a
-    # cert from certificate_center@volcengine.com -- the platform behind Doubao /
-    # Jimeng. Verified on two real signed JPEGs, 2026-05-29.
-    C2paAiVendor(
-        b"volcengine", "ByteDance (Volcano Engine)", "ByteDance (Doubao / Jimeng / Volcano Engine)", "ByteDance"
-    ),
-    # Some Volcano Engine certs name the signer with the Chinese legal entity
-    # "北京火山引擎科技有限公司" (Beijing Volcano Engine Technology Co., Ltd.) rather
-    # than the latin "volcengine" -- the latin needle misses it entirely. The issuer is the
-    # UTF-8 of the Chinese name (it appears UTF-8-encoded in the manifest-store
-    # JSON and the raw caBX bytes alike); it normalizes to the same "ByteDance"
-    # needle and platform as the volcengine row, so the two collapse together for
-    # clash detection. Verified against compatible signed samples.
-    C2paAiVendor(
-        "北京火山引擎科技有限公司".encode(),
-        "ByteDance (Volcano Engine)",
-        "ByteDance (Doubao / Jimeng / Volcano Engine)",
-        "ByteDance",
-    ),
-    # ByteDance's international brand (BytePlus / Seedream / Seededit) signs its
-    # cert as "Byteplus Pte. Ltd." -- the bare ``volcengine`` needle misses it, so
-    # real BytePlus AI output was mis-attributed (an incidental "Adobe XMP" string
-    # in the file's XMP made it read "Adobe Firefly"). Adding the issuer means the
-    # clean manifest issuer matches "BytePlus (ByteDance)" directly. The platform
-    # string mirrors the volcengine row: both share the "ByteDance" needle, so the
-    # earlier row's label wins anyway -- they normalize together for clash
-    # detection. Verified on compatible signed samples.
-    C2paAiVendor(b"Byteplus", "BytePlus (ByteDance)", "ByteDance (Doubao / Jimeng / Volcano Engine)", "ByteDance"),
-    # Dreamina (ByteDance's international Jimeng brand) signs C2PA as "Bytedance
-    # Pte. Ltd." with a "Dreamina/x.y" claim generator and, unlike the Volcano
-    # Engine output, NO digitalSourceType assertion -- so the generator name is the
-    # only AI signal. It is registered by that generator token (which the caBX /
-    # store-JSON byte scan sees across active + ingredient manifests, where the
-    # active manifest is often a plain c2pa-tool transcode). ``asserts_ai`` lets the
-    # issuer alone flag AI without trainedAlgorithmicMedia; "Dreamina" is a
-    # distinctive brand string, so it does not risk the incidental-mention problem
-    # the common-word issuers have. Verified on compatible signed samples.
-    # Normalizes to the same "ByteDance" needle/platform as the
-    # volcengine row (they collapse together for clash detection).
-    C2paAiVendor(
-        b"Dreamina",
-        "ByteDance (Dreamina)",
-        "ByteDance (Doubao / Jimeng / Volcano Engine)",
-        "ByteDance",
-        asserts_ai=True,
-    ),
-    # Canva Magic Media signs AI-generated images as "Canva" with a generic
-    # c2pa-rs claim generator + trainedAlgorithmicMedia; without this entry the
-    # source read AI but no platform was attributed. Verified on compatible signed
-    # samples. Canva does not use SynthID.
-    C2paAiVendor(b"Canva", "Canva", "Canva (Magic Media)", "Canva"),
-    # ElevenLabs is a pure generative-AI company (AI voice / audio, and image /
-    # video via its API); it signs output as "Eleven Labs Inc.", so the C2PA
-    # manifest alone marks AI generation. Verified on compatible signed samples.
-    # ElevenLabs does not use SynthID.
-    C2paAiVendor(b"Eleven Labs", "ElevenLabs", "ElevenLabs", "ElevenLabs"),
-    # fal.ai (generative inference platform, issuer "fal - Features & Labels
-    # Inc." / common name "fal.ai", claim generators like "fal-ai/seedvr",
-    # "fal-ai/gpt-image-2"). The files carry trainedAlgorithmicMedia, so the
-    # verdict already fired, but the platform stayed unattributed. fal.ai is
-    # a pure generative platform, so ``asserts_ai`` also covers its output
-    # that omits the source-type.
-    C2paAiVendor(b"fal-ai", "fal.ai", "fal.ai", "fal.ai", asserts_ai=True),
-    # Bria AI (bria.ai, generative platform) signs as "Bria Artificial
-    # Intelligence" with a "Bria Ai" claim generator and source type
-    # ``empty`` (NOT trainedAlgorithmicMedia), so a real signed file was
-    # completely missed by identify. A pure-AI
-    # vendor with distinctive strings, so ``asserts_ai`` is safe here.
-    C2paAiVendor(b"Bria", "Bria Artificial Intelligence", "Bria AI", "Bria", asserts_ai=True),
-    # Truepic is a C2PA signing authority, not an AI generator: no platform label,
-    # never asserts is_ai (the verdict comes from the digital-source-type).
-    C2paAiVendor(b"Truepic", "Truepic", None, None),
-)
-
-# Deliberately NOT registered as AI-generation vendors:
-#   - TikTok Inc.: signs C2PA as a content-provenance / AI-labeling authority on
-#     uploads, not as an image generator. The is_ai verdict keys off the
-#     digitalSourceType (trainedAlgorithmicMedia), which is already honored; a
-#     bare TikTok signer marks distribution provenance, not generation, so adding
-#     it as a generator needle would mis-label human uploads as AI.
-#   - PixelBin.io (issuer "Fynd"): an image transformation / optimization / CDN
-#     service. Its C2PA stamps a transform/upload step, not a generation event.
-#   Both are excluded to avoid false-positive AI attribution; re-evaluate only
-#   against a real signed file whose manifest carries a trainedAlgorithmicMedia
-#   digital-source type produced by the vendor itself.
-
-# Derived view -- add a vendor to C2PA_AI_VENDORS above, not here.
-# C2PA issuer signature -> resolved org name, for the manifest byte-scan.
-C2PA_ISSUERS: dict[bytes, str] = {v.issuer: v.org for v in C2PA_AI_VENDORS}
-
-# Resolved org names of the vendors whose presence asserts AI generation on its
-# own (no digitalSourceType needed) -- see the ``asserts_ai`` field. identify uses
-# this to lift the AI verdict for an identity-AI issuer (e.g. Dreamina) that ships
-# no trainedAlgorithmicMedia. Derived from the flag -- set it on the vendor, not here.
-C2PA_IDENTITY_AI_ORGS: frozenset[str] = frozenset(v.org for v in C2PA_AI_VENDORS if v.asserts_ai)
-
-# C2PA issuers whose signed outputs also carry an invisible SynthID pixel
-# watermark -- a metadata proxy for "SynthID is in the pixels":
-#   - Google (Imagen/Gemini): embeds SynthID, long-standing (DeepMind docs).
-#   - OpenAI (ChatGPT/Codex/API): pairs SynthID with C2PA since ~2026-05-20.
-#     Confirmed by OpenAI's Help Center ("C2PA and SynthID in OpenAI-generated
-#     images", updated 2026-05-21): "Images generated with ChatGPT, Codex, and
-#     our API include both C2PA metadata and SynthID watermarks." OpenAI also
-#     notes a signal may be absent if "the image was created before these
-#     signals were available" -- so OpenAI images from before the rollout can
-#     carry C2PA without SynthID. For OpenAI the proxy is therefore "likely",
-#     not certain; the verdict string is hedged accordingly. OpenAI's own oracle
-#     is openai.com/verify (Google's is the Gemini app "Verify with SynthID").
-# The issuer byte ("OpenAI"/"Google") is verified locally against data/fixtures/provenance;
-# the SynthID pairing is documented behavior (Google: DeepMind; OpenAI: above).
-# Adobe Firefly and Microsoft Designer sign C2PA but do NOT use SynthID, so a
-# C2PA manifest alone is not a SynthID signal -- the issuer is. The pixel
-# watermark is not locally detectable (proprietary decoder); the C2PA companion
-# is the proxy, and only while the manifest is intact.
-# Derived from the `synthid` flag on C2PA_AI_VENDORS -- set it there, not here.
-SYNTHID_C2PA_ISSUERS: frozenset[bytes] = frozenset(v.issuer for v in C2PA_AI_VENDORS if v.synthid)
-
-# C2PA known AI tools
-C2PA_AI_TOOLS = {
-    b"GPT-4o": "GPT-4o",
-    b"ChatGPT": "ChatGPT",
-    b"Sora": "Sora",
-    b"DALL-E": "DALL-E",
-    b"DALL": "DALL-E",
-    b"Imagen": "Imagen",
-    b"Firefly": "Firefly",
-}
-
-# C2PA ``c2pa.soft-binding`` algorithm identifiers -> the forensic-watermark
-# vendor that stamped the pixels. The manifest's ``alg`` field names the
-# watermark scheme even when the watermark itself cannot be decoded locally, so
-# a byte-scan for these (keyed on a distinctive prefix to catch all variants)
-# tells us a third-party forensic watermark is present and whose. Verified
-# against the official C2PA registry (github.com/c2pa-org/softbinding-algorithm-list).
-# Adobe TrustMark is additionally decodable locally (see ``trustmark_detector``);
-# the rest (Digimarc, Imatag, Steg.AI, etc.) are proprietary oracle-only decoders.
-C2PA_SOFT_BINDINGS = {
-    b"com.adobe.trustmark": "Adobe TrustMark",
-    b"com.adobe.icn": "Adobe (content fingerprint)",
-    b"com.digimarc": "Digimarc",
-    b"com.imatag.lamark": "Imatag (Lamark)",
-    b"ai.steg": "Steg.AI",
-    b"com.microsoft.invismark": "Microsoft InvisMark",
-    b"com.microsoft.wavmark": "Microsoft WavMark",
-    b"com.verimatrix": "Verimatrix",
-    b"com.nagra.nexguard": "NAGRA NexGuard",
-    b"com.aiwatermark": "AIWatermark (Meta PixelSeal)",
-    b"ai.trufo": "Trufo",
-    b"app.overlai": "Overlai",
-    b"com.markany": "MarkAny",
-    b"com.mentaport": "Mentaport",
-    b"es.lumatrace": "LumaTrace",
-    b"ai.verda": "VerdaAI",
-    b"ai.contentlens": "ContentLens",
-    b"io.iscc": "ISCC (content code)",
-}
-
-# Lowercased substrings that mark an AI generator when found in an EXIF
-# ``Software`` / XMP ``CreatorTool`` value. Conservative on purpose: plain
-# editors like "Adobe Photoshop" or "GIMP" must NOT match (no AI token), so only
-# generator names land here. Add new generators here, not inline.
-AI_GENERATOR_TOKENS: frozenset[str] = frozenset(
-    {
-        "firefly",
-        "dall-e",
-        "dalle",
-        "midjourney",
-        "stable diffusion",
-        "stable-diffusion",
-        "stablediffusion",
-        "comfyui",
-        "automatic1111",
-        "invokeai",
-        "imagen",
-        "gpt-image",
-        "nightcafe",
-        "ideogram",
-        "leonardo",
-        "flux",
-        "dreamstudio",
-        # Generator stamps without C2PA:
-        #   - NovelAI (anime SD): PNG tEXt Software="NovelAI", Source="NovelAI
-        #     Diffusion V4.5 <hash>", Title="NovelAI generated image".
-        #   - Reve Image (reve.com): EXIF Software / XMP CreatorTool = "reve.com"
-        #     (the bare token "reve" would false-positive on "forever"/"reverie").
-        #   - Aphrodite AI: EXIF Make / Software = "Aphrodite AI[ v1.0]".
-        "novelai",
-        "reve.com",
-        "aphrodite ai",
-        # Additional verified markers:
-        #   - Apple Photos Clean Up (Apple Intelligence object removal): XMP
-        #     photoshop:Credit / IPTC credit value; composite source-type
-        #     covered detection, this token covers removal parity.
-        #   - fal-ai: generative-platform generator string.
-        "apple photos clean up",
-        "fal-ai",
-    }
-)
-
-# C2PA action types
-C2PA_ACTIONS = {
-    b"c2pa.created": "created",
-    b"c2pa.converted": "converted",
-    b"c2pa.edited": "edited",
-    b"c2pa.filtered": "filtered",
-    b"c2pa.cropped": "cropped",
-    b"c2pa.resized": "resized",
-    b"c2pa.opened": "opened",
-    b"c2pa.placed": "placed",
-}
-
-# PNG signature
-PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"

src/remove_ai_watermarks/noai/extractor.py

@@ -1,155 +0,0 @@
-"""Read-only metadata extraction from PNG and JPEG images.
-
-Provides functions to pull all metadata, AI-only metadata, or a
-human-readable summary without modifying the source file.
-"""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any, cast
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-import piexif
-from PIL import Image
-
-from remove_ai_watermarks.noai.c2pa import extract_c2pa_chunk, extract_c2pa_info, has_c2pa_metadata
-from remove_ai_watermarks.noai.constants import AI_KEYWORDS, AI_METADATA_KEYS, PNG_METADATA_KEYS
-
-
-def extract_metadata(source_path: Path) -> dict[str, Any]:
-    """
-    Extract all metadata from a PNG or JPG file.
-
-    Args:
-        source_path: Path to the source image file.
-
-    Returns:
-        Dictionary containing all extracted metadata.
-    """
-    metadata: dict[str, Any] = {}
-
-    with Image.open(source_path) as img:
-        # Extract EXIF data
-        if "exif" in img.info:
-            try:
-                exif_dict = piexif.load(img.info["exif"])
-                metadata["exif"] = exif_dict
-            except Exception:
-                metadata["exif_raw"] = img.info["exif"]
-
-        # Extract standard PNG metadata
-        for key in PNG_METADATA_KEYS:
-            if key in img.info:
-                metadata[key] = img.info[key]
-
-        # Extract all other metadata including AI-specific
-        for key, value in img.info.items():
-            if not isinstance(key, str):
-                continue
-            if key not in metadata and key not in ["exif"]:
-                metadata[key] = value
-
-        # Extract DPI and gamma if present
-        if "dpi" in img.info:
-            metadata["dpi"] = img.info["dpi"]
-        if "gamma" in img.info:
-            metadata["gamma"] = img.info["gamma"]
-
-    # Check for C2PA metadata
-    if has_c2pa_metadata(source_path):
-        metadata["c2pa"] = extract_c2pa_info(source_path)
-        c2pa_chunk = extract_c2pa_chunk(source_path)
-        if c2pa_chunk:
-            metadata["c2pa_chunk"] = c2pa_chunk
-
-    return metadata
-
-
-def extract_ai_metadata(source_path: Path) -> dict[str, Any]:
-    """
-    Extract only AI-generated metadata from a PNG or JPG file.
-
-    Args:
-        source_path: Path to the source image file.
-
-    Returns:
-        Dictionary containing only AI-related metadata.
-    """
-    ai_metadata: dict[str, Any] = {}
-
-    with Image.open(source_path) as img:
-        for key in AI_METADATA_KEYS:
-            if key in img.info:
-                ai_metadata[key] = img.info[key]
-
-        for key, value in img.info.items():
-            if not isinstance(key, str):
-                continue
-            key_lower = key.lower()
-            if key not in ai_metadata and any(kw in key_lower for kw in AI_KEYWORDS):
-                ai_metadata[key] = value
-
-    # Check for C2PA metadata
-    if has_c2pa_metadata(source_path):
-        ai_metadata["c2pa"] = extract_c2pa_info(source_path)
-        c2pa_chunk = extract_c2pa_chunk(source_path)
-        if c2pa_chunk:
-            ai_metadata["c2pa_chunk"] = c2pa_chunk
-
-    return ai_metadata
-
-
-def has_ai_metadata(image_path: Path) -> bool:
-    """
-    Check if an image contains AI-generated metadata.
-
-    Args:
-        image_path: Path to the image file.
-
-    Returns:
-        True if AI metadata is detected, False otherwise.
-    """
-    with Image.open(image_path) as img:
-        for key in AI_METADATA_KEYS:
-            if key in img.info:
-                return True
-
-    return bool(has_c2pa_metadata(image_path))
-
-
-def get_ai_metadata_summary(source_path: Path) -> str:
-    """
-    Get a human-readable summary of AI metadata.
-
-    Args:
-        source_path: Path to the source image file.
-
-    Returns:
-        Formatted string with AI metadata summary.
-    """
-    ai_meta = extract_ai_metadata(source_path)
-
-    if not ai_meta:
-        return "No AI metadata found."
-
-    lines = ["AI Image Metadata:"]
-    lines.append("-" * 40)
-
-    for key, value in ai_meta.items():
-        if key == "c2pa_chunk":
-            continue
-        if key == "c2pa" and isinstance(value, dict):
-            lines.append("C2PA Metadata:")
-            for ck, cv in cast("dict[str, Any]", value).items():
-                lines.append(f"  {ck}: {cv}")
-        elif isinstance(value, str) and len(value) > 100:
-            value = value[:100] + "..."
-            lines.append(f"{key}: {value}")
-        elif isinstance(value, bytes):
-            lines.append(f"{key}: <binary data ({len(value)} bytes)>")
-        else:
-            lines.append(f"{key}: {value}")
-
-    return "\n".join(lines)

src/remove_ai_watermarks/noai/img2img_runner.py

@@ -1,161 +0,0 @@
-"""Img2img pipeline execution with progress monitoring and MPS fallback.
-
-Extracted from ``watermark_remover.py`` to keep the ``WatermarkRemover``
-class focused on orchestration.
-"""
-
-from __future__ import annotations
-
-import contextlib
-import logging
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from collections.abc import Callable
-
-    from PIL import Image
-
-from remove_ai_watermarks.noai.progress import is_mps_error, make_pipeline_progress
-
-logger = logging.getLogger(__name__)
-
-
-def run_img2img(
-    pipeline: Any,
-    image: Image.Image,
-    strength: float,
-    num_inference_steps: int,
-    guidance_scale: float,
-    generator: Any,
-    device: str,
-    set_progress: Callable[[str], None],
-    extra_kwargs: dict[str, Any] | None = None,
-) -> Image.Image:
-    """Execute img2img with live progress and return the generated image.
-
-    ``extra_kwargs`` overlays additional pipeline arguments (e.g. the ControlNet
-    ``control_image`` / ``controlnet_conditioning_scale`` and a non-empty prompt),
-    so a ControlNet img2img pass reuses the same progress + fallback machinery.
-    """
-    effective_steps = max(1, int(num_inference_steps * strength))
-
-    step_cb, first_step, done_ev, start_updater = make_pipeline_progress(
-        effective_steps,
-        device,
-        set_progress,
-    )
-    start_updater()
-
-    try:
-        result = _call_pipeline(
-            pipeline, image, strength, num_inference_steps, guidance_scale, generator, step_cb, extra_kwargs
-        )
-        done_ev.set()
-        return result.images[0]
-    except TypeError as exc:
-        # The only TypeError we retry is the deprecated-callback case: `_call_pipeline`
-        # passes the legacy `callback`/`callback_steps` kwargs, and a diffusers version
-        # that removed them raises TypeError("... unexpected keyword argument
-        # 'callback'"). We then re-run once WITHOUT the progress callback. Any OTHER
-        # TypeError (e.g. a bad control_image/dtype in the forward pass) is a real error
-        # -- re-raise it instead of silently re-running the whole diffusion pass and
-        # masking the cause.
-        if "callback" not in str(exc):
-            raise
-        first_step.set()
-        result = _call_pipeline(
-            pipeline, image, strength, num_inference_steps, guidance_scale, generator, None, extra_kwargs
-        )
-        done_ev.set()
-        return result.images[0]
-    finally:
-        first_step.set()
-        done_ev.set()
-
-
-def run_img2img_with_mps_fallback(
-    load_pipeline: Callable[[], Any],
-    image: Image.Image,
-    strength: float,
-    num_inference_steps: int,
-    guidance_scale: float,
-    generator: Any,
-    device: str,
-    set_progress: Callable[[str], None],
-    *,
-    reload_on_cpu: Callable[[], Any],
-    extra_kwargs: dict[str, Any] | None = None,
-) -> tuple[Image.Image, str]:
-    """Run img2img; on MPS error, fall back to CPU.
-
-    ``extra_kwargs`` overlays extra pipeline arguments (used by the ControlNet
-    path). Returns ``(result_image, final_device)`` — device may change to
-    ``"cpu"`` on fallback.
-    """
-    pipeline = load_pipeline()
-
-    try:
-        img = run_img2img(
-            pipeline,
-            image,
-            strength,
-            num_inference_steps,
-            guidance_scale,
-            generator,
-            device,
-            set_progress,
-            extra_kwargs,
-        )
-        return img, device
-    except RuntimeError as error:
-        if device == "mps" and is_mps_error(error):
-            logger.warning("MPS error detected: %s. Falling back to CPU.", error)
-            set_progress("MPS error! Clearing cache and retrying on CPU...")
-            try_empty_device_cache("mps")
-            pipeline = reload_on_cpu()
-            img = run_img2img(
-                pipeline, image, strength, num_inference_steps, guidance_scale, None, "cpu", set_progress, extra_kwargs
-            )
-            return img, "cpu"
-        raise
-
-
-def _call_pipeline(
-    pipeline: Any,
-    image: Image.Image,
-    strength: float,
-    num_inference_steps: int,
-    guidance_scale: float,
-    generator: Any,
-    step_callback: Any,
-    extra_kwargs: dict[str, Any] | None = None,
-) -> Any:
-    kwargs: dict[str, Any] = {
-        "prompt": "",
-        "image": image,
-        "strength": strength,
-        "num_inference_steps": num_inference_steps,
-        "guidance_scale": guidance_scale,
-        "generator": generator,
-    }
-    if extra_kwargs:
-        kwargs.update(extra_kwargs)
-    if step_callback is not None:
-        kwargs["callback"] = step_callback
-        kwargs["callback_steps"] = 1
-    return pipeline(**kwargs)
-
-
-def try_empty_device_cache(device: str) -> None:
-    """Best-effort free of cached GPU/MPS/XPU memory for ``device``.
-
-    ``torch.<device>.empty_cache()`` exists for cuda/mps/xpu but not cpu (the
-    hasattr guard skips the cpu no-op). Never raises -- callers use it as cleanup
-    (the MPS->CPU fallback here, and the batch loop in watermark_remover).
-    """
-    with contextlib.suppress(Exception):
-        import torch
-
-        backend = getattr(torch, device, None)
-        if backend is not None and hasattr(backend, "empty_cache"):
-            backend.empty_cache()  # type: ignore[attr-defined]

src/remove_ai_watermarks/noai/isobmff.py

@@ -1,284 +0,0 @@
-"""Minimal ISOBMFF box walker for stripping C2PA from AVIF / HEIF / MP4 / JPEG-XL.
-
-The ISO Base Media File Format wraps content in nested ``[size:4][type:4][...]``
-boxes. C2PA stores its manifest in a top-level ``uuid`` box keyed by the
-C2PA UUID; JPEG-XL uses a ``jumb`` box (JUMBF) instead. To strip provenance
-without re-encoding the image, we walk the top-level box list, drop boxes that
-carry C2PA, and emit the rest verbatim. The codestream (``mdat`` for ISOBMFF,
-``jxlc`` / ``jxlp`` for JPEG-XL) is untouched, so pixel data is preserved
-bit-for-bit.
-
-This file intentionally avoids dependencies on format-specific libraries
-(pillow-heif, pillow-jxl, pymp4) so it works on systems where they aren't
-installed.
-
-Reference: ISO/IEC 14496-12 (ISOBMFF) and C2PA 2.1 spec §11.
-"""
-
-from __future__ import annotations
-
-import logging
-import re
-import struct
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from collections.abc import Iterator
-    from pathlib import Path
-
-from remove_ai_watermarks.metadata import (
-    AIGC_MARKERS,
-    C2PA_UUID,
-    IPTC_AI_FIELD_MARKERS,
-    IPTC_AI_MARKERS,
-)
-
-logger = logging.getLogger(__name__)
-
-# Top-level box types that may carry AI provenance. ``uuid`` boxes are checked
-# against ``C2PA_UUID`` / AI-label markers before being stripped; ``jumb`` boxes
-# are always stripped (JPEG-XL uses them exclusively for JUMBF).
-C2PA_BOX_TYPES: frozenset[bytes] = frozenset({b"uuid", b"jumb"})
-
-# AI-label byte markers (TC260 AIGC, IPTC "Made with AI", IPTC 2025.1 AI fields)
-# whose presence inside an XMP ``uuid`` box means the box carries an AI label.
-# Matching the payload rather than a fixed XMP UUID avoids the XMP-box UUID
-# byte-order ambiguity and stays surgical: only AI-bearing XMP is dropped, plain
-# XMP (copyright, camera info) is kept.
-_AI_LABEL_MARKERS: tuple[bytes, ...] = AIGC_MARKERS + IPTC_AI_MARKERS + IPTC_AI_FIELD_MARKERS
-
-# Adobe XMP packet delimiters (XMP spec part 3). In HEIF/AVIF the XMP packet
-# sits inside a ``meta``-box ``mime`` item whose bytes live in ``mdat`` / ``idat``,
-# out of reach of the top-level box stripper, so an AI-label packet there is
-# blanked in place (see ``blank_ai_xmp_packets``).
-_XMP_PACKET_RE = re.compile(rb"<\?xpacket begin=.*?<\?xpacket end=[^>]*?\?>", re.DOTALL)
-
-
-def _iter_top_level_boxes(data: bytes) -> Iterator[tuple[int, int, bytes, int]]:
-    """Yield ``(start, end, type, payload_offset)`` for each top-level box.
-
-    Handles all three ISOBMFF box-size encodings:
-    - ``size > 1``: 32-bit size field is the total box length.
-    - ``size == 1``: 64-bit ``largesize`` follows after the type field.
-    - ``size == 0``: box runs to end of file.
-    """
-    pos = 0
-    n = len(data)
-    while pos + 8 <= n:
-        size32 = struct.unpack_from(">I", data, pos)[0]
-        box_type = data[pos + 4 : pos + 8]
-        if size32 == 1:
-            if pos + 16 > n:
-                return
-            size = struct.unpack_from(">Q", data, pos + 8)[0]
-            payload_off = pos + 16
-        elif size32 == 0:
-            size = n - pos
-            payload_off = pos + 8
-        else:
-            size = size32
-            payload_off = pos + 8
-        if size < (payload_off - pos) or pos + size > n:
-            return
-        yield pos, pos + size, box_type, payload_off
-        pos += size
-
-
-def is_isobmff(data: bytes) -> bool:
-    """Cheap sniff: ISOBMFF files start with an ``ftyp`` box."""
-    return len(data) >= 8 and data[4:8] == b"ftyp"
-
-
-def scan_c2pa_region(path: str | Path, *, max_total: int = 4 * 1024 * 1024) -> bytes:
-    """Concatenated payloads of top-level ``uuid`` / ``jumb`` boxes in an ISOBMFF
-    file, found by seeking past other boxes (``mdat`` etc.) by size.
-
-    C2PA manifests and XMP packets (incl. AI labels) live in top-level ``uuid``
-    boxes; JPEG-XL uses ``jumb``. In a streaming / non-faststart MP4 the manifest
-    sits AFTER a multi-megabyte ``mdat``, so a fixed first-MB read misses it. This
-    walks box headers (8-16 bytes each) and seeks past payloads it does not need,
-    so it never loads ``mdat`` into memory and works on multi-GB files. Returns
-    the relevant box payloads (capped at ``max_total``), or ``b""`` for a
-    non-ISOBMFF file or on any read error.
-    """
-    collected = bytearray()
-    try:
-        with open(path, "rb") as f:
-            sniff = f.read(8)
-            if len(sniff) < 8 or sniff[4:8] != b"ftyp":
-                return b""
-            f.seek(0, 2)
-            file_size = f.tell()
-            pos = 0
-            while pos + 8 <= file_size and len(collected) < max_total:
-                f.seek(pos)
-                header = f.read(8)
-                if len(header) < 8:
-                    break
-                size32 = struct.unpack(">I", header[:4])[0]
-                box_type = header[4:8]
-                payload_off = pos + 8
-                if size32 == 1:
-                    ext = f.read(8)
-                    if len(ext) < 8:
-                        break
-                    size = struct.unpack(">Q", ext)[0]
-                    payload_off = pos + 16
-                elif size32 == 0:
-                    size = file_size - pos
-                else:
-                    size = size32
-                if size < (payload_off - pos) or pos + size > file_size:
-                    # Detection-only: a malformed box halts the walk, so a manifest
-                    # placed after it is missed (best-effort scan; no resync).
-                    break
-                if box_type in C2PA_BOX_TYPES:
-                    f.seek(payload_off)
-                    to_read = min(pos + size - payload_off, max_total - len(collected))
-                    if to_read > 0:
-                        collected += f.read(to_read)
-                pos += size
-    except OSError:
-        return b""
-    return bytes(collected)
-
-
-def strip_c2pa_boxes(data: bytes) -> tuple[bytes, int]:
-    """Return ``(cleaned_bytes, stripped_count)`` with AI-provenance boxes removed.
-
-    Walks top-level boxes and drops:
-    - any ``uuid`` box whose UUID equals ``C2PA_UUID`` (a C2PA manifest);
-    - any ``uuid`` box whose payload carries an AI-label marker (an XMP packet
-      with a TC260 / IPTC / IPTC-2025.1 AI field -- caught by content, not by the
-      XMP UUID, so it works regardless of the UUID's byte order, and leaves plain
-      non-AI XMP intact);
-    - any ``jumb`` box (JPEG-XL JUMBF container).
-
-    All other boxes (incl. ``mdat`` / codestream) are emitted verbatim, so pixel
-    and audio data is preserved bit-for-bit. Non-ISOBMFF input is returned
-    unchanged. Despite the name this also covers MP4/MOV/M4A video and audio
-    (all ISOBMFF). NOTE: this drops only top-level boxes. AI metadata stored as an
-    *item inside the ``meta`` box* (typical for AVIF/HEIF) is handled separately and
-    in place (same length, no offset rewrite): AI-label XMP by
-    :func:`blank_ai_xmp_packets`, and AI-generator tokens in an ``Exif`` item by
-    :func:`blank_ai_exif_tokens`.
-    """
-    if not is_isobmff(data):
-        return data, 0
-
-    out = bytearray()
-    stripped = 0
-    consumed = 0
-    for start, end, box_type, payload_off in _iter_top_level_boxes(data):
-        consumed = end
-        if box_type == b"uuid":
-            # uuid boxes carry the 16-byte UUID immediately after the type.
-            is_c2pa = payload_off + 16 <= end and data[payload_off : payload_off + 16] == C2PA_UUID
-            has_ai_label = any(marker in data[payload_off:end] for marker in _AI_LABEL_MARKERS)
-            if is_c2pa or has_ai_label:
-                stripped += 1
-                continue
-        elif box_type == b"jumb":
-            stripped += 1
-            continue
-        out.extend(data[start:end])
-
-    # Fail-safe: the walker returns early on a malformed box (bad size, or a box
-    # that runs past EOF), so anything after it was never visited. Emitting `out`
-    # would silently truncate the file from the bad box to EOF -- worse than not
-    # stripping. If the walk did not consume the whole input, return it unchanged.
-    if consumed != len(data):
-        logger.warning(
-            "ISOBMFF box walk stopped at offset %d of %d (malformed box); "
-            "returning input unchanged to avoid truncation",
-            consumed,
-            len(data),
-        )
-        return data, 0
-
-    return bytes(out), stripped
-
-
-def blank_ai_xmp_packets(data: bytes) -> tuple[bytes, int]:
-    """Overwrite (with spaces, in place) any XMP packet carrying an AI-label
-    marker; return ``(data, blanked_count)``.
-
-    HEIF/AVIF store XMP as a ``meta``-box ``mime`` item whose bytes live in
-    ``mdat`` / ``idat``, which ``strip_c2pa_boxes`` cannot remove without
-    meta-box surgery (``iinf`` / ``iloc`` rewrite). Instead, the XMP packet is
-    located by its ``<?xpacket begin ... end?>`` delimiters and, when it carries
-    an AI-label marker (TC260 AIGC / IPTC / IPTC-2025.1), overwritten with spaces.
-    Because the replacement is the **same length**, every box size and ``iloc``
-    offset stays valid and the coded image data is untouched -- only the AI label
-    content is destroyed. Packets without an AI marker (plain copyright / camera
-    XMP) are left intact, mirroring the top-level XMP-``uuid`` content match.
-    """
-    blanked = 0
-
-    def _scrub(match: re.Match[bytes]) -> bytes:
-        nonlocal blanked
-        packet = match.group()
-        if any(marker in packet for marker in _AI_LABEL_MARKERS):
-            blanked += 1
-            return b" " * len(packet)
-        return packet
-
-    return _XMP_PACKET_RE.sub(_scrub, data), blanked
-
-
-# EXIF TIFF byte-order headers: little-endian (II 0x2a 0x00) and big-endian
-# (MM 0x00 0x2a). A HEIF/AVIF ``Exif`` meta-box item stores its TIFF block in
-# ``mdat`` / ``idat``, so the block (and these headers) appear in the raw bytes.
-_TIFF_HEADERS: tuple[bytes, ...] = (b"II\x2a\x00", b"MM\x00\x2a")
-# How far past a TIFF header an EXIF block plausibly extends; bounds the slice we
-# hand to piexif and search within (EXIF blocks are small kilobyte-scale).
-_EXIF_WINDOW = 256 * 1024
-
-
-def blank_ai_exif_tokens(data: bytes) -> tuple[bytes, int]:
-    """Overwrite (with spaces, in place) any AI-generator token in an EXIF block
-    stored as an ISOBMFF ``meta``-box ``Exif`` item; return ``(data, blanked_count)``.
-
-    HEIF/AVIF can carry EXIF as a ``meta``-box ``Exif`` item whose TIFF bytes live
-    in ``mdat`` / ``idat`` -- out of reach of the top-level box stripper, and (when
-    no pillow-heif plugin is installed) of the PIL EXIF reader too, so an AI
-    ``Software`` / ``Make`` / ``Artist`` / ``ImageDescription`` tag there survived
-    ``remove_ai_metadata`` (a documented gap). This locates EXIF TIFF blocks by
-    their byte-order header, **validates each with piexif** (so a coincidental
-    II/MM run in pixel data is ignored -- it will not parse as a TIFF IFD), and
-    overwrites any AI value with spaces of the SAME length. Because the replacement
-    is same-length, every box size and ``iloc`` offset stays valid and the coded image
-    is untouched -- only the AI tag content is destroyed; camera/editor EXIF without an
-    AI token is left intact. This mirrors ``metadata._scrub_ai_exif`` in what it removes
-    -- generator tokens (``Software``/``Make``/``Artist``/``ImageDescription``), the
-    China TC260 ``{"AIGC":{...}}`` block (``ImageDescription``/``UserComment``), and the
-    xAI/Grok ``Signature:`` + UUID-``Artist`` pair -- since on the ISOBMFF path this is
-    the ONLY EXIF scrubber (``_scrub_ai_exif`` never runs there), so without parity a
-    HEIC/AVIF AIGC/xAI tag is detected but not removed.
-    """
-    import piexif
-
-    # The AI-EXIF rule set is defined ONCE in metadata._ai_exif_targets and shared by both
-    # EXIF scrubbers (the JPEG _scrub_ai_exif pops the tag; here we blank the value bytes),
-    # so their coverage cannot drift. Imported lazily to avoid import-order coupling with
-    # metadata (which imports this module); a deliberate cross-module use, not an API leak.
-    from remove_ai_watermarks.metadata import _ai_exif_targets  # pyright: ignore[reportPrivateUsage]
-
-    out = bytearray(data)
-    blanked = 0
-    for header in _TIFF_HEADERS:
-        pos = data.find(header)
-        while pos != -1:
-            window = bytes(out[pos : pos + _EXIF_WINDOW])
-            try:
-                loaded: dict[str, Any] = piexif.load(window)
-            except Exception:
-                loaded = {}
-            for _ifd_key, _tag, value, _name in _ai_exif_targets(loaded):
-                # Blank the value bytes in place, within this EXIF block only.
-                vpos = out.find(value, pos, pos + _EXIF_WINDOW)
-                if vpos != -1:
-                    out[vpos : vpos + len(value)] = b" " * len(value)
-                    blanked += 1
-            pos = data.find(header, pos + len(header))
-    return bytes(out), blanked

src/remove_ai_watermarks/noai/progress.py

@@ -1,332 +0,0 @@
-"""Terminal progress animation and library output suppression.
-
-This module provides two main capabilities for the CLI:
-
-1. ``run_with_progress`` — a styled two-line terminal animation that
-   displays a bouncing highlight bar, a braille spinner, elapsed time,
-   and a live operation message while a background task executes.
-
-2. ``silence_library_output`` — a wrapper that suppresses noisy log
-   output produced by third-party ML libraries (transformers, diffusers,
-   huggingface_hub, tqdm) so the user only sees our own progress messages.
-"""
-
-from __future__ import annotations
-
-import contextlib
-import io
-import os
-import sys
-import threading
-import time
-import warnings
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from collections.abc import Callable
-
-# ── ANSI color constants ────────────────────────────────────────────
-_CYAN = "\033[36m"
-_YELLOW = "\033[33m"
-_GREEN = "\033[32m"
-_DIM = "\033[2m"
-_BOLD = "\033[1m"
-_RESET = "\033[0m"
-
-# Bar geometry
-_BAR_WIDTH = 32
-_HIGHLIGHT_WIDTH = 5
-
-
-def _no_color() -> bool:
-    """Respect the NO_COLOR convention (https://no-color.org/)."""
-    return bool(os.environ.get("NO_COLOR"))
-
-
-def _truncate(text: str, max_len: int = 72) -> str:
-    """Shorten a string with an ellipsis if it exceeds *max_len*."""
-    return text if len(text) <= max_len else text[: max_len - 1] + "…"
-
-
-def _build_bar(step: int) -> str:
-    """Build a flowing highlight bar that bounces across the width.
-
-    The highlight segment (5 chars wide) travels left→right→left
-    continuously, giving the user a visual "working" signal.
-    """
-    cycle = _BAR_WIDTH * 2 - 2
-    pos = step % cycle
-    if pos >= _BAR_WIDTH:
-        pos = cycle - pos
-
-    hl_start = max(0, pos - _HIGHLIGHT_WIDTH // 2)
-    hl_end = min(_BAR_WIDTH, pos + _HIGHLIGHT_WIDTH // 2 + 1)
-    before = "━" * hl_start
-    highlight = "━" * (hl_end - hl_start)
-    after = "━" * (_BAR_WIDTH - hl_end)
-
-    if _no_color():
-        return before + highlight + after
-    return f"{_DIM}{before}{_RESET}{_BOLD}{_YELLOW}{highlight}{_RESET}{_DIM}{after}{_RESET}"
-
-
-def run_with_progress(
-    task: Callable[[], Any],
-    progress_state: dict[str, str] | None = None,
-) -> Any:
-    """Execute *task* in a background thread while showing a progress animation.
-
-    The animation renders two lines to ``sys.__stderr__``:
-
-    - **Line 1**: braille spinner + bouncing bar + elapsed seconds
-    - **Line 2**: current operation message from *progress_state*
-
-    When the task finishes, a green "Completed" line replaces the animation.
-
-    Args:
-        task: A zero-argument callable to run in the background.
-        progress_state: Mutable dict whose ``"message"`` key is read
-            by the animation loop to display the current operation.
-
-    Returns:
-        Whatever *task* returns.
-
-    Raises:
-        Any exception raised by *task* is re-raised after the animation
-        is cleaned up.
-    """
-    done = threading.Event()
-    output_holder: dict[str, Any] = {"result": None, "error": None}
-
-    def worker() -> None:
-        try:
-            output_holder["result"] = task()
-        except Exception as error:  # pragma: no cover - passthrough
-            output_holder["error"] = error
-        finally:
-            done.set()
-
-    thread = threading.Thread(target=worker, daemon=True)
-    thread.start()
-
-    spinner_frames = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
-    idx = 0
-    start_time = time.time()
-    no_color = _no_color()
-
-    def _get_operation() -> str:
-        if isinstance(progress_state, dict):
-            return progress_state.get("message", "Processing...")
-        return "Processing..."
-
-    # ── Animation loop ──────────────────────────────────────────────
-    while not done.is_set():
-        spinner = spinner_frames[idx % len(spinner_frames)]
-        elapsed = int(time.time() - start_time)
-        bar_str = _build_bar(idx)
-        operation = _truncate(_get_operation())
-
-        if no_color:
-            line1 = f"  {spinner}  Processing {bar_str}  {elapsed:>3}s"
-            line2 = f"  ╰─ {operation}"
-        else:
-            line1 = f"  {_CYAN}{spinner}{_RESET}  Processing {bar_str}  {_BOLD}{_YELLOW}{elapsed:>3}s{_RESET}"
-            line2 = f"  {_DIM}╰─ {operation}{_RESET}"
-
-        print(
-            f"\r\033[2K{line1}\n\033[2K{line2}\033[1A\r",
-            end="",
-            flush=True,
-            file=sys.__stderr__,
-        )
-        time.sleep(0.08)
-        idx += 1
-
-    # ── Final "done" frame ──────────────────────────────────────────
-    thread.join()
-    total = int(time.time() - start_time)
-    final_operation = _truncate(_get_operation())
-    done_bar = "━" * _BAR_WIDTH
-
-    if no_color:
-        final_line1 = f"  ✓  Completed {done_bar}  {total:>3}s"
-        final_line2 = f"  ╰─ {final_operation}"
-    else:
-        final_line1 = (
-            f"  {_GREEN}{_BOLD}✓{_RESET}  {_GREEN}Completed{_RESET} "
-            f"{_GREEN}{done_bar}{_RESET}  {_BOLD}{_GREEN}{total:>3}s{_RESET}"
-        )
-        final_line2 = f"  {_DIM}╰─ {final_operation}{_RESET}"
-
-    print(
-        f"\r\033[2K{final_line1}\n\033[2K{final_line2}",
-        file=sys.__stderr__,
-    )
-
-    if output_holder["error"] is not None:
-        raise output_holder["error"]
-
-    return output_holder["result"]
-
-
-def silence_library_output(
-    run_func: Callable[[], Any],
-    set_progress: Callable[[str], None] | None = None,
-) -> Callable[[], Any]:
-    """Return a wrapper that silences noisy ML library output.
-
-    The wrapper:
-
-    1. Disables HuggingFace Hub progress bars via env var.
-    2. Sets ``transformers``, ``diffusers``, and ``huggingface_hub``
-       loggers to *error* level.
-    3. Redirects ``stdout`` and ``stderr`` to ``io.StringIO`` sinks so
-       that stray ``tqdm`` bars and model-loading chatter are invisible.
-    4. Suppresses all Python warnings during the call.
-
-    Args:
-        run_func: The callable to execute silently.
-        set_progress: Optional callback to report phase changes.
-
-    Returns:
-        A zero-argument callable that, when invoked, runs *run_func*
-        inside the silent context.
-    """
-
-    def wrapped() -> Any:
-        if set_progress:
-            set_progress("Configuring runtime and suppressing noisy logs...")
-
-        os.environ.setdefault("HF_HUB_DISABLE_PROGRESS_BARS", "1")
-
-        for _silence in (
-            lambda: __import__("transformers").logging.set_verbosity_error(),
-            lambda: _silence_diffusers(),
-            lambda: __import__("huggingface_hub").logging.set_verbosity_error(),
-        ):
-            with contextlib.suppress(Exception):
-                _silence()
-
-        with warnings.catch_warnings():
-            warnings.simplefilter("ignore")
-            with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
-                if set_progress:
-                    set_progress("Executing watermark removal pipeline...")
-                return run_func()
-
-    return wrapped
-
-
-def _silence_diffusers() -> None:
-    """Silence diffusers logging and progress bars."""
-    from diffusers.utils import logging as diffusers_logging
-
-    diffusers_logging.set_verbosity_error()
-    if hasattr(diffusers_logging, "disable_progress_bar"):
-        diffusers_logging.disable_progress_bar()
-
-
-# ── Shared pipeline progress helpers ─────────────────────────────────
-
-_DEFAULT_PRE_PHASES: list[tuple[int, str]] = [
-    (0, "Encoding image with VAE encoder"),
-    (3, "Mapping pixel data → latent space"),
-    (7, "Injecting noise into latent representation"),
-    (12, "Building denoiser schedule"),
-    (18, "Starting reverse diffusion sampler"),
-    (30, "Running first denoising iteration"),
-    (50, "Still processing — this can take a while"),
-    (90, "Pipeline running — may take a few minutes"),
-]
-
-_DEFAULT_POST_PHASES: list[tuple[int, str]] = [
-    (0, "Denoising complete · Running VAE decoder"),
-    (2, "Decoding latent channels → RGB color space"),
-    (5, "Reconstructing pixel grid from latents"),
-    (10, "Applying color space conversion and normalization"),
-    (18, "Finalizing pixel output"),
-    (30, "Still decoding — large images take longer"),
-    (60, "Almost done — large images take longer to decode"),
-]
-
-
-def make_pipeline_progress(
-    effective_steps: int,
-    device: str,
-    set_progress: Callable[[str], None],
-    *,
-    bar_len: int = 20,
-    label: str = "Denoising",
-    pre_phases: list[tuple[int, str]] | None = None,
-    post_phases: list[tuple[int, str]] | None = None,
-) -> tuple[Callable[..., None], threading.Event, threading.Event, Callable[[], threading.Thread]]:
-    """Create step callback and background updater for a diffusion pipeline.
-
-    Returns:
-        (step_callback, first_step_event, pipeline_done_event, start_updater)
-        where ``start_updater()`` launches and returns the background thread.
-    """
-    pre = pre_phases or [(s, f"{m} on {device}") for s, m in _DEFAULT_PRE_PHASES]
-    post = post_phases or [(s, f"{m} on {device}") for s, m in _DEFAULT_POST_PHASES]
-
-    t0_holder: list[float] = [time.monotonic()]
-    first_step = threading.Event()
-    pipeline_done = threading.Event()
-    last_cb_time: list[float] = [t0_holder[0]]
-
-    def _background_updater() -> None:
-        idx = 0
-        while not first_step.is_set():
-            elapsed = time.monotonic() - t0_holder[0]
-            while idx < len(pre) - 1 and elapsed >= pre[idx + 1][0]:
-                idx += 1
-            set_progress(pre[idx][1])
-            first_step.wait(timeout=0.4)
-
-        idx = 0
-        post_start: float | None = None
-        while not pipeline_done.is_set():
-            since_cb = time.monotonic() - last_cb_time[0]
-            if since_cb >= 1.5:
-                if post_start is None:
-                    post_start = time.monotonic()
-                elapsed = time.monotonic() - post_start
-                while idx < len(post) - 1 and elapsed >= post[idx + 1][0]:
-                    idx += 1
-                set_progress(post[idx][1])
-            else:
-                post_start = None
-                idx = 0
-            pipeline_done.wait(timeout=0.4)
-
-    def step_callback(step: int, timestep: int, latents: Any) -> None:
-        first_step.set()
-        last_cb_time[0] = time.monotonic()
-        elapsed = time.monotonic() - t0_holder[0]
-        current = step + 1
-        per_step = elapsed / max(1, current)
-        remaining = per_step * max(0, effective_steps - current)
-        filled = int(bar_len * current / max(1, effective_steps))
-        bar = "█" * filled + "░" * (bar_len - filled)
-        set_progress(
-            f"{label} [{bar}] {current}/{effective_steps} | {elapsed:.0f}s elapsed, ~{remaining:.0f}s left | {device}"
-        )
-
-    def start_updater() -> threading.Thread:
-        t0_holder[0] = time.monotonic()
-        last_cb_time[0] = t0_holder[0]
-        first_step.clear()
-        pipeline_done.clear()
-        t = threading.Thread(target=_background_updater, daemon=True)
-        t.start()
-        return t
-
-    return step_callback, first_step, pipeline_done, start_updater
-
-
-# ── MPS fallback helper ──────────────────────────────────────────────
-
-
-def is_mps_error(error: Exception) -> bool:
-    """Check whether an exception is an MPS-related runtime error."""
-    return "mps" in str(error).lower()

src/remove_ai_watermarks/noai/utils.py

@@ -1,43 +0,0 @@
-"""Low-level utility helpers used across the metadata pipeline.
-
-Kept deliberately small — only format detection lives here so that
-higher-level modules can import without circular dependencies.
-"""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-from remove_ai_watermarks.noai.constants import SUPPORTED_FORMATS
-
-
-def is_supported_format(file_path: Path) -> bool:
-    """
-    Check if the file format is supported.
-
-    Args:
-        file_path: Path to the image file.
-
-    Returns:
-        True if the format is supported, False otherwise.
-    """
-    return file_path.suffix.lower() in SUPPORTED_FORMATS
-
-
-def get_image_format(file_path: Path) -> str:
-    """
-    Get the image format from file path.
-
-    Args:
-        file_path: Path to the image file.
-
-    Returns:
-        Format string (PNG, JPEG, etc.).
-    """
-    suffix = file_path.suffix.lower()
-    if suffix in {".jpg", ".jpeg"}:
-        return "JPEG"
-    return "PNG"

src/remove_ai_watermarks/noai/watermark_profiles.py

@@ -1,207 +0,0 @@
-"""Watermark removal model profiles and the default strength.
-
-Pure configuration and lookup functions with no ML dependencies.
-"""
-
-from __future__ import annotations
-
-import math
-from typing import TYPE_CHECKING, Literal
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-DEFAULT_MODEL_ID = "stabilityai/stable-diffusion-xl-base-1.0"
-
-# Qwen-Image (20B MMDiT, Apache-2.0 code AND weights) base for the ``qwen`` pipeline:
-# an img2img alternative to SDXL with native text rendering (incl. CJK). Loaded only
-# when ``--pipeline qwen`` is selected; CUDA/cloud-class (does not fit MPS). CERTIFIED
-# oracle floors (2026-06-20): OpenAI **0.10** (seed-robust -- clean on seeds 0-4) and
-# Google/Gemini **0.25** (seed 0 verified on 2 images; pin a seed in prod, the Gemini
-# oracle rate-limits volume seed-repeat). The Gemini floor (0.25) is HIGHER than the
-# certified controlnet Gemini floor (0.15); ``resolve_strength(..., pipeline="qwen")``
-# now carries this via ``_QWEN_VENDOR_STRENGTH`` (below), so ``--pipeline qwen`` gets the
-# right floor automatically -- the old manual "pass --strength 0.25 for Gemini on qwen"
-# workaround is retired.
-# (Dispatch uses the bare "qwen" literal, matching the sdxl/controlnet sites, so there
-# is no QWEN_PROFILE constant -- only the model id is referenced from code.)
-QWEN_MODEL_ID = "Qwen/Qwen-Image"
-
-# Canonical pipeline-profile names + the back-compat alias. The plain SDXL img2img
-# profile is ``sdxl``; ``default`` is kept as an accepted alias (it was the profile's
-# name before ``controlnet`` became the default-selected pipeline, 2026-06-09).
-SDXL_PROFILE = "sdxl"
-QWEN_ZIMAGE_PROFILE = "qwen-zimage"
-_PROFILE_ALIASES = {
-    "default": SDXL_PROFILE,
-    "qwen_zimage": QWEN_ZIMAGE_PROFILE,
-}
-
-
-def normalize_profile(profile: str) -> str:
-    """Canonicalize a pipeline-profile name, resolving the ``default`` -> ``sdxl`` alias."""
-    normalized = profile.strip().lower()
-    return _PROFILE_ALIASES.get(normalized, normalized)
-
-
-def resolve_steps(num_inference_steps: int | None, pipeline: str) -> int:
-    """Resolve a profile-specific step default while preserving explicit values.
-
-    The Lightning LoRA in ``qwen-zimage`` is distilled for four steps. Existing
-    SDXL and Qwen profiles keep the long-standing 50-step CLI default.
-    """
-    if num_inference_steps is not None:
-        return num_inference_steps
-    return 4 if normalize_profile(pipeline) == QWEN_ZIMAGE_PROFILE else 50
-
-
-def resolve_seed(seed: int | None, pipeline: str) -> int | None:
-    """Keep the oracle-verified qwen-zimage profile deterministic by default."""
-    if seed is not None:
-        return seed
-    return 0 if normalize_profile(pipeline) == QWEN_ZIMAGE_PROFILE else None
-
-
-# The SDXL-native canny ControlNet used by the ``controlnet`` pipeline. The
-# ControlNet is an add-on to the SDXL base checkpoint (DEFAULT_MODEL_ID), not a
-# separate base model, so both the ``sdxl`` and ``controlnet`` profiles load the
-# same base weights and share the same vendor-adaptive strength ladder (see below).
-CONTROLNET_CANNY_MODEL = "xinsir/controlnet-canny-sdxl-1.0"
-
-# Vendor-adaptive default denoising strength for the SDXL img2img scrub, overridable
-# from the CLI (`--strength`). The right strength depends on which vendor's SynthID is
-# present (detected from the C2PA issuer, metadata.synthid_source). The SAME ladder
-# applies to BOTH pipelines (`sdxl` plain img2img and `controlnet`) -- see "why one
-# ladder" below.
-#
-# Data basis (see docs/synthid.md sections 2.2 / 5.5): ORACLE-CERTIFIED controlnet floors.
-# Oracle re-testing
-# LOWERED the ladder back to OpenAI 0.10 / Google 0.15: each output verified on its own
-# oracle (openai.com/verify for OpenAI, the Google Gemini app for Google), all clean ->
-#   - OpenAI 0.10: 2 photoreal images (1402 / 1448 px), SynthID not found on either.
-#   - Google 0.15: 2 NATIVE-resolution images (both 2816x1536), SynthID not found on
-#     either -- this directly retires the earlier "native ~2816 likely needs ~0.35+"
-#     guess, which was speculative and never oracle-checked at that resolution.
-# This supersedes the 2026-06-04 cert (OpenAI 0.20 / Google 0.30), whose higher floor a
-# pixel-fidelity sweep showed was ~2x the removal floor and over-regenerated for no
-# efficacy gain (Google MAE -20% at 0.15 vs 0.30, no SynthID returning). Unknown vendor
-# tracks the Google (more robust watermark) value -> 0.15, still safe-by-default and the
-# floor that real (no-vendor) photos hit, so it also minimizes damage when there is in
-# fact nothing to remove. CAVEAT: the re-test is n=2 per vendor on photoreal / landscape
-# content; FLAT-GRAPHIC hard cases (the historical `sdxl` weak spot) were NOT in the
-# sample, so if an oracle still reads SynthID on a flat output, raise `--strength`.
-#
-# Why ONE ladder for both pipelines (2026-06-09): the certification was run on
-# controlnet, and it does NOT transfer to `sdxl` by symmetry -- the two pipelines have
-# OPPOSITE hard cases (controlnet leaves SynthID on photoreal, `sdxl` leaves it on flat
-# graphics; the content-x-pipeline table in docs/synthid.md §5.1). BUT on its OWN hard
-# case (flat fills) `sdxl` is the WEAKER remover -- plain img2img at low strength barely
-# perturbs a flat region -- so it needs AT LEAST as much strength as controlnet, not
-# less. Hence the certified controlnet floor is the right floor for `sdxl` too. The
-# higher strength costs little quality where it matters. `controlnet` is now the default
-# pipeline and `sdxl` is reached only through an explicit `--pipeline sdxl`. NOTE:
-# this is a MARGIN argument for `sdxl`, not a fresh certification -- there is no local
-# SynthID detector, so if an oracle still reads SynthID on a flat `sdxl` output, raise
-# `--strength`.
-OPENAI_STRENGTH = 0.10
-GEMINI_STRENGTH = 0.15
-UNKNOWN_STRENGTH = 0.15
-# Backwards-compatible alias: the vendor-unknown value (what a caller gets without a
-# detected vendor). Kept as DEFAULT_STRENGTH for existing references.
-DEFAULT_STRENGTH = UNKNOWN_STRENGTH
-
-# Detected-vendor -> default strength. Vendor strings come from `vendor_for_strength`.
-_VENDOR_STRENGTH = {"openai": OPENAI_STRENGTH, "google": GEMINI_STRENGTH}
-
-# Qwen has its OWN certified floors (Modal A100-80GB, 2026-06-20), DIFFERENT from the
-# SDXL ladder above: OpenAI 0.10 (seed-robust), Gemini 0.25 (HIGHER than controlnet's
-# 0.15 -- the 20B MMDiT perturbs less per denoising step, so it needs more strength to
-# clear Gemini SynthID). Unknown vendor tracks the higher (Gemini) value, safe-by-default.
-# `resolve_strength(..., pipeline="qwen")` uses this table so `--pipeline qwen` carries the
-# right floor automatically -- retiring the old manual "pass --strength 0.25 for Gemini on
-# qwen" workaround.
-QWEN_OPENAI_STRENGTH = 0.10
-QWEN_GEMINI_STRENGTH = 0.25
-QWEN_UNKNOWN_STRENGTH = 0.25
-_QWEN_VENDOR_STRENGTH = {"openai": QWEN_OPENAI_STRENGTH, "google": QWEN_GEMINI_STRENGTH}
-
-
-def strength_default_help() -> str:
-    """One-line description of the vendor-adaptive default, derived from the constants.
-
-    Single source of truth for the CLI ``--strength`` help so the numbers can never
-    drift from the actual ladder (they did once when the per-pipeline split was unified).
-    """
-    return (
-        f"vendor-adaptive (OpenAI {OPENAI_STRENGTH} / Google {GEMINI_STRENGTH} / "
-        f"unknown {UNKNOWN_STRENGTH}, from the C2PA issuer; qwen-zimage instead uses "
-        "resolution-adaptive denoise)"
-    )
-
-
-def resolve_strength(strength: float | None, vendor: str | None = None, pipeline: str | None = None) -> float:
-    """Resolve the denoising strength, applying the vendor default when unset.
-
-    ``None`` means "the user did not pass ``--strength``", which resolves
-    **vendor-adaptively**: ``vendor`` (``"openai"`` / ``"google"`` / None, from
-    ``vendor_for_strength``) selects the per-vendor floor. The ``sdxl`` and ``controlnet``
-    pipelines share ONE ladder (``OPENAI_STRENGTH`` / ``GEMINI_STRENGTH`` /
-    ``UNKNOWN_STRENGTH`` -- see the module comment for why); ``qwen`` has its OWN higher
-    ladder (``_QWEN_VENDOR_STRENGTH``, Gemini 0.25 vs controlnet 0.15), selected when
-    ``pipeline`` normalizes to ``"qwen"``. An explicit value always wins (including
-    ``0.0`` -- the check is ``is None``, not falsiness). Shared by the CLI (for display)
-    and the engine (for execution) so the two never disagree -- both must pass the SAME
-    ``vendor`` and ``pipeline``.
-    """
-    if strength is not None:
-        return strength
-    if pipeline is not None and normalize_profile(pipeline) == "qwen":
-        return _QWEN_VENDOR_STRENGTH.get(vendor or "", QWEN_UNKNOWN_STRENGTH)
-    return _VENDOR_STRENGTH.get(vendor or "", UNKNOWN_STRENGTH)
-
-
-def viable_steps(num_inference_steps: int, strength: float) -> int:
-    """The smallest step count >= ``num_inference_steps`` that actually denoises.
-
-    diffusers derives its img2img timesteps as ``int(steps * strength)``. When that
-    rounds to ZERO the pipeline builds an empty latent and dies deep inside attention
-    with ``cannot reshape tensor of 0 elements into shape [0, -1, 1, 512]`` -- an opaque
-    torch error for what is really "these two options cannot work together".
-
-    The combination is reachable with entirely valid CLI arguments: at the default
-    strength 0.15 every ``--steps`` below 7 crashed, and nothing told the user that
-    ``--steps`` and ``--strength`` interact (found by the release smoke matrix,
-    2026-07-19). Raising the count to the minimum that denoises keeps the caller's intent
-    -- they asked for "few steps", not "zero" -- and the engine logs the adjustment.
-
-    A non-positive ``strength`` cannot denoise at any step count; return the caller's
-    value unchanged rather than dividing by zero.
-    """
-    if strength <= 0:
-        return num_inference_steps
-    if int(num_inference_steps * strength) >= 1:
-        return num_inference_steps
-    return math.ceil(1 / strength)
-
-
-def vendor_for_strength(image_path: Path) -> Literal["openai", "google"] | None:
-    """Detect the SynthID vendor for strength selection: ``"openai"`` / ``"google"`` / None.
-
-    Reads the C2PA SynthID proxy (``metadata.synthid_source``) on the ORIGINAL input,
-    so it must run before any pass that strips metadata. When both issuers appear (a
-    rare multi-sign anomaly) Google wins -- the more-robust watermark -> safer (higher)
-    strength. Returns None when metadata is stripped or the issuer is neither vendor,
-    which maps to ``UNKNOWN_STRENGTH``. Lazy-imports ``metadata`` to keep this module
-    dependency-light.
-    """
-    try:
-        from remove_ai_watermarks.metadata import synthid_source
-
-        src = (synthid_source(image_path) or "").lower()
-    except Exception:  # metadata unreadable -> treat as unknown vendor
-        return None
-    if "google" in src:
-        return "google"
-    if "openai" in src:
-        return "openai"
-    return None

src/remove_ai_watermarks/pill_engine.py

@@ -61,6 +61,10 @@ _MASK_W, _MASK_H = 0.205, 0.115  # width of W, height of W
 # invisible inpaint. Threshold = median Sobel magnitude over the footprint box at a
 # normalized width. The reliable bottom-right wordmark arm is NOT texture-gated:
 # a wordmark-confirmed pill is removed regardless.
+#
+# Measured through the PRODUCT path (the `_keep_pill` gate), not the raw detector, by
+# ``scripts/pill_gate_audit.py`` -- the raw path bypasses the gate and reads as a
+# disaster that the shipped behaviour does not have. Re-run it when the gate changes.
 _FLAT_TEXTURE_MAX = 6.0
 
 _silhouette: NDArray[Any] | None = None
@@ -163,8 +167,11 @@ class PillEngine:
         box = self._footprint_box(image)
         if box is None:
             return None
+        # Same primitive the shared fill uses, rather than a private zeros/fill copy.
+        # `dilate=0` because this footprint is already generous by construction; the
+        # box is clamped to the frame in _footprint_box and both origins are positive
+        # fractions, so boxes_to_mask's own clamping is a no-op here.
+        from remove_ai_watermarks import region_eraser
+
         x0, y0, x1, y1 = box
-        h, w = image.shape[:2]
-        mask = np.zeros((h, w), np.uint8)
-        mask[y0:y1, x0:x1] = 255
-        return mask
+        return region_eraser.boxes_to_mask(image.shape[:2], [(x0, y0, x1 - x0, y1 - y0)], dilate=0)

src/remove_ai_watermarks/pixel_evidence.py

@@ -0,0 +1,484 @@
+# pyright: reportUnknownMemberType=false, reportUnknownArgumentType=false, reportUnknownVariableType=false, reportMissingTypeStubs=false
+"""The complete pixel-forensics layer for one image.
+
+STATUS
+
+Independent from provenance verdicts, removal, and the CLI. Consumers use the
+versioned :meth:`PixelEvidence.to_dict` boundary; feature extraction failures are
+reported per family without discarding successful measurements.
+
+WHAT IS MEASURED
+
+One decode, then six families of scale-robust statistics over it:
+
+* ``dct`` -- AC coefficient histograms over the 8x8 block DCT, plus the deviation of
+  leading digits from Benford's law.
+* ``fft`` -- radial band energies of the log-magnitude spectrum, plus the
+  color-filter-array periodicity peaks a demosaiced camera capture leaves.
+* ``noise`` -- standard deviation and kurtosis of a high-pass residual.
+* ``ela`` -- error level after a quality-90 JPEG re-save.
+* ``gradient`` -- gradient-magnitude histogram and Laplacian variance.
+* ``color`` -- 4x4x4 RGB histogram, mean saturation, mean value.
+
+and, in ``artifacts``, the spatial layer those statistics are computed from: a
+64-bit perceptual hash, a 128px JPEG thumbnail, and coarse ELA, noise-residual and
+FFT-phase maps.
+
+THE ARTIFACTS ARE NOT AGGREGATES
+
+Everything above ``artifacts`` is a scalar or a fixed-length histogram, and an image
+cannot be reconstructed from those. ``artifacts`` is different in kind: a thumbnail
+is a picture, a perceptual hash identifies one, and the coarse maps carry layout.
+Collecting them makes a record that identifies the source image, so a caller storing
+or forwarding them is handling image content, not statistics about it. That is why
+they are a separate field and not merged into the families.
+
+REQUIREMENTS
+
+Needs the ``pixels`` extra (numpy). Guard a call with :func:`is_available` when the
+caller must not hard-depend on it.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from remove_ai_watermarks._internal.schema import require_schema_version
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Analysis resolution. Every statistic here is scale-robust, and a 2048px cap keeps
+# the FFT and the sliding-window residual bounded on a 100 MP input.
+MAX_SIDE = 2048
+# The eight lowest-frequency AC positions of the 8x8 block DCT, zig-zag order.
+AC_POSITIONS = ((0, 1), (1, 0), (1, 1), (0, 2), (2, 0), (2, 1), (1, 2), (0, 3))
+FFT_BANDS = 8
+# A Bayer CFA shows as symmetric peaks at half the Nyquist on the diagonals.
+BAYER_OFFSETS = ((1, 1), (1, -1))
+INSTALL_HINT = "install the pixel extra: uv add 'remove-ai-watermarks[pixels]'"
+PIXEL_EVIDENCE_SCHEMA_VERSION = 1
+
+
+@dataclass(frozen=True)
+class PixelEvidence:
+    """Pixel statistics for one image, and the spatial artifacts behind them.
+
+    ``decode`` carries the source dimensions, or ``{"error": ...}`` when the image
+    could not be decoded -- in which case every other field is empty. A family is also
+    empty when the image is too small for it (the block DCT needs 8x8, the FFT 32x32,
+    the residual 3x3), so a caller must treat every field as optional rather than
+    assume a fixed feature width.
+    """
+
+    path: Path
+    decode: dict[str, Any]
+    dct: dict[str, Any] = field(default_factory=dict[str, Any])
+    fft: dict[str, Any] = field(default_factory=dict[str, Any])
+    noise: dict[str, Any] = field(default_factory=dict[str, Any])
+    ela: dict[str, Any] = field(default_factory=dict[str, Any])
+    gradient: dict[str, Any] = field(default_factory=dict[str, Any])
+    color: dict[str, Any] = field(default_factory=dict[str, Any])
+    # Identifies the source image; see the module note. Empty unless asked for.
+    artifacts: dict[str, Any] = field(default_factory=dict[str, Any])
+    # Opt-in timings for callers measuring pipeline latency. Empty by default so
+    # repeated evidence collection remains value-deterministic.
+    timing_ms: dict[str, float] = field(default_factory=dict[str, float])
+
+    @property
+    def decoded(self) -> bool:
+        """False when the source could not be decoded at all."""
+        return "error" not in self.decode
+
+    @property
+    def status(self) -> str:
+        """``complete``, ``partial`` for a failed family, or ``error`` on decode."""
+        if not self.decoded:
+            return "error"
+        sections = (self.dct, self.fft, self.noise, self.ela, self.gradient, self.color, self.artifacts)
+        return "partial" if any("error" in section for section in sections) else "complete"
+
+    def to_dict(
+        self,
+        *,
+        schema_version: int = PIXEL_EVIDENCE_SCHEMA_VERSION,
+    ) -> dict[str, Any]:
+        """Return the selected JSON-safe transport schema without a local path."""
+        schema_version = require_schema_version(
+            schema_version,
+            contract="pixel evidence",
+            supported=(1,),
+        )
+        return {
+            "schema_version": schema_version,
+            "status": self.status,
+            "decode": dict(self.decode),
+            "dct": dict(self.dct),
+            "fft": dict(self.fft),
+            "noise": dict(self.noise),
+            "ela": dict(self.ela),
+            "gradient": dict(self.gradient),
+            "color": dict(self.color),
+            "artifacts": dict(self.artifacts),
+            "timing_ms": dict(self.timing_ms),
+        }
+
+
+def is_available() -> bool:
+    """True when the optional pixel dependencies are installed."""
+    from remove_ai_watermarks.optional_deps import module_available
+
+    return module_available("numpy")
+
+
+def _numpy() -> Any:
+    from remove_ai_watermarks.optional_deps import module_available
+
+    if not module_available("numpy"):
+        raise RuntimeError(f"Pixel evidence needs numpy -- {INSTALL_HINT}")
+    import numpy as np
+
+    return np
+
+
+def _dct_matrix(np: Any, n: int = 8) -> Any:
+    """Orthonormal n x n DCT-II basis: M[i, j] = cos(pi (2j + 1) i / 2n)."""
+    i = np.arange(n)[:, None]
+    j = np.arange(n)[None, :]
+    m = np.cos(np.pi * (2 * j + 1) * i / (2 * n))
+    m[0, :] *= 1 / np.sqrt(2)
+    return m * np.sqrt(2 / n)
+
+
+def read_gray(image_path: Path) -> tuple[Any, Any, dict[str, Any]]:
+    """Decode to float32 grayscale (and RGB for color stats), downscaled.
+
+    Pillow, not cv2, and the source dimensions are recorded BEFORE the downscale.
+    """
+    np = _numpy()
+    from PIL import Image
+
+    from remove_ai_watermarks import image_io
+
+    try:
+        image_io._register_heif()  # pyright: ignore[reportPrivateUsage]
+        with Image.open(image_path) as img:
+            info: dict[str, Any] = {"width": img.width, "height": img.height}
+            if max(img.size) > MAX_SIDE:
+                img.thumbnail((MAX_SIDE, MAX_SIDE), Image.Resampling.LANCZOS)
+            rgb = np.asarray(img.convert("RGB"), dtype=np.float32)
+            gray = np.asarray(img.convert("L"), dtype=np.float32)
+    except Exception as exc:
+        logger.debug("pixel decode failed for %s: %s", image_path, exc)
+        # Exception text from Pillow commonly embeds the absolute source path.
+        # Keep that detail in the log, not in the pathless transport contract.
+        return None, None, {"error": type(exc).__name__}
+    return gray, rgb, info
+
+
+def dct_features(gray: Any) -> dict[str, Any]:
+    """AC coefficient histograms over the 8x8 block DCT + Benford deviation."""
+    np = _numpy()
+    height, width = gray.shape
+    h8, w8 = height // 8 * 8, width // 8 * 8
+    if h8 < 8 or w8 < 8:
+        return {}
+    basis = _dct_matrix(np)
+    bins = np.linspace(-20.5, 20.5, 22)
+    blocks = gray[:h8, :w8].reshape(h8 // 8, 8, w8 // 8, 8).swapaxes(1, 2)
+    rows = basis[[row for row, _ in AC_POSITIONS]]
+    columns = basis[[column for _, column in AC_POSITIONS]]
+    coeff = np.einsum("ki,abij,kj->abk", rows, blocks, columns)
+    hists = []
+    lead_vals: list[Any] = []
+    for index in range(len(AC_POSITIONS)):
+        values = coeff[:, :, index].ravel()
+        hists.append(np.histogram(values, bins=bins)[0].tolist())
+        lead_vals.append(np.abs(values))
+    out: dict[str, Any] = {"dct_ac_hist": hists}
+    flat = np.abs(np.concatenate(lead_vals))
+    flat = flat[flat >= 1]
+    if flat.size > 100:
+        leading = (flat / 10 ** np.floor(np.log10(flat))).astype(int)
+        leading = leading[(leading >= 1) & (leading <= 9)]
+        if leading.size > 100:
+            observed = np.bincount(leading, minlength=10)[1:10] / leading.size
+            benford = np.log10(1 + 1 / np.arange(1, 10))
+            out["benford_mad"] = float(np.abs(observed - benford).mean())
+    return out
+
+
+def noise_residual_map(gray: Any) -> Any:
+    """High-pass residual, the map the noise statistics are computed from."""
+    np = _numpy()
+    from numpy.lib.stride_tricks import sliding_window_view
+
+    if gray.shape[0] < 3 or gray.shape[1] < 3:
+        return None
+    kernel = np.array([[-1.0, -1.0, -1.0], [-1.0, 8.0, -1.0], [-1.0, -1.0, -1.0]])
+    height, width = gray.shape
+    # kernel is float64, so the residual is float64 like the unchunked form
+    out = np.empty((height - 2, width - 2), dtype=np.float64)
+    # Row-chunked: the (window * kernel) temporary is ~150 MB at 2048px if
+    # materialized whole. Per-element 9-tap sums are computed in the same order,
+    # so the result is bit-identical to the unchunked form.
+    for y0 in range(0, height - 2, 256):
+        y1 = min(y0 + 256, height - 2)
+        window = sliding_window_view(gray[y0 : y1 + 2], (3, 3))
+        out[y0:y1] = (window * kernel).sum(axis=(-1, -2))
+    return out
+
+
+def noise_features(residual: Any) -> dict[str, Any]:
+    """High-pass residual std and kurtosis."""
+    flat = residual.ravel()
+    std = float(flat.std())
+    if std < 1e-9:
+        return {"noise_std": 0.0, "noise_kurtosis": 0.0}
+    z = (flat - flat.mean()) / std
+    return {"noise_std": std, "noise_kurtosis": float((z**4).mean() - 3.0)}
+
+
+def fft_decompose(gray: Any) -> tuple[Any, Any] | None:
+    """Log-magnitude (fftshifted) and phase of the image spectrum."""
+    np = _numpy()
+    if min(gray.shape) < 32:
+        return None
+    spectrum = np.fft.fftshift(np.fft.fft2(gray - gray.mean()))
+    return np.log1p(np.abs(spectrum)), np.angle(spectrum)
+
+
+def fft_features(mag: Any) -> dict[str, Any]:
+    """Radial magnitude band energies (no phase) + CFA periodicity peaks."""
+    np = _numpy()
+    height, width = mag.shape
+    cy, cx = height // 2, width // 2
+    # 1D broadcast instead of an mgrid: saves ~160 MB of int64 temporaries at
+    # 2048px. The squares are exact in float64 (values < 2^53), so band means
+    # are identical to the mgrid form.
+    r2y = (np.arange(height, dtype=np.float64) - cy) ** 2
+    r2x = (np.arange(width, dtype=np.float64) - cx) ** 2
+    radius = np.sqrt(r2y[:, None] + r2x[None, :])
+    r_max = radius.max()
+    bands = []
+    for index in range(FFT_BANDS):
+        mask = (radius >= r_max * index / FFT_BANDS) & (radius < r_max * (index + 1) / FFT_BANDS)
+        bands.append(float(mag[mask].mean()) if mask.any() else 0.0)
+    peaks = []
+    for dy, dx in BAYER_OFFSETS:
+        y, x = cy + dy * (height // 4), cx + dx * (width // 4)
+        neighborhood = mag[y - 2 : y + 3, x - 2 : x + 3]
+        peaks.append(float(neighborhood.max() - mag.mean()))
+    return {"fft_band_energy": bands, "cfa_peaks": peaks, "cfa_peak": max(peaks)}
+
+
+def ela_map(rgb: Any) -> Any:
+    """Absolute per-pixel error after a quality-90 JPEG re-save."""
+    np = _numpy()
+    from PIL import Image
+
+    try:
+        buffer = io.BytesIO()
+        Image.fromarray(rgb.astype(np.uint8)).save(buffer, "JPEG", quality=90)
+        buffer.seek(0)
+        resaved = np.asarray(Image.open(buffer).convert("RGB"), dtype=np.float32)
+    except Exception as exc:
+        logger.debug("ELA re-save failed: %s", exc)
+        return None
+    if resaved.shape != rgb.shape:
+        return None
+    return np.abs(rgb - resaved).mean(axis=-1)
+
+
+def ela_features(err: Any) -> dict[str, Any]:
+    """Error-level stats after a quality-90 JPEG re-save."""
+    np = _numpy()
+    return {"ela_mean": float(err.mean()), "ela_p95": float(np.percentile(err, 95))}
+
+
+def gradient_features(gray: Any) -> dict[str, Any]:
+    np = _numpy()
+    gy, gx = np.gradient(gray)
+    mag = np.sqrt(gx**2 + gy**2)
+    hist = np.histogram(mag, bins=10, range=(0, 255))[0].tolist()
+    laplacian = np.gradient(gy, axis=0) + np.gradient(gx, axis=1)
+    return {"gradient_hist": hist, "laplacian_var": float(laplacian.var())}
+
+
+def color_features(rgb: Any) -> dict[str, Any]:
+    np = _numpy()
+    small = rgb[::4, ::4]  # decimate; the histogram is position-blind anyway
+    bins = (small / 256 * 4).astype(int).clip(0, 3)
+    index = bins[..., 0] * 16 + bins[..., 1] * 4 + bins[..., 2]
+    hist = np.bincount(index.ravel(), minlength=64).tolist()
+    mx = small.max(axis=-1)
+    mn = small.min(axis=-1)
+    saturation = np.where(mx > 0, (mx - mn) / np.maximum(mx, 1e-6), 0)
+    return {
+        "color_hist_4x4x4": hist,
+        "saturation_mean": float(saturation.mean()),
+        "value_mean": float(mx.mean() / 255),
+    }
+
+
+def perceptual_hash(gray: Any) -> str:
+    """64-bit DCT perceptual hash. Identifies an image; see the module note."""
+    np = _numpy()
+    from PIL import Image
+
+    small = np.asarray(Image.fromarray(gray.astype(np.float32), mode="F").resize((32, 32), Image.Resampling.LANCZOS))
+    basis = _dct_matrix(np, 32)
+    low_basis = basis[:8]
+    low = (low_basis @ small @ low_basis.T).ravel()[1:]  # drop DC
+    bits = low > np.median(low)
+    return f"{int(''.join('1' if bit else '0' for bit in bits), 2):016x}"
+
+
+def _coarse(np: Any, arr: Any, side: int = 64) -> Any:
+    """Downscale a 2D map to at most ``side`` on the long edge."""
+    from PIL import Image
+
+    height, width = arr.shape
+    if max(height, width) <= side:
+        return arr
+    img = Image.fromarray(arr.astype(np.float32), mode="F")
+    img.thumbnail((side, side), Image.Resampling.BILINEAR)
+    return np.asarray(img)
+
+
+def _array_payload(arr: Any) -> dict[str, Any]:
+    return {
+        "shape": list(arr.shape),
+        "dtype": str(arr.dtype),
+        "base64": base64.b64encode(arr.tobytes()).decode("ascii"),
+    }
+
+
+def spatial_artifacts(gray: Any, rgb: Any, *, ela: Any, residual: Any, phase: Any) -> dict[str, Any]:
+    """Perceptual hash, thumbnail, and coarse ELA / residual / phase maps.
+
+    These identify the source image rather than describe it -- see the module note.
+    The maps are the ones the statistics were computed from, passed in rather than
+    recomputed.
+    """
+    np = _numpy()
+    from PIL import Image
+
+    out: dict[str, Any] = {"phash": perceptual_hash(gray)}
+    thumbnail = Image.fromarray(rgb.astype(np.uint8))
+    thumbnail.thumbnail((128, 128), Image.Resampling.LANCZOS)
+    buffer = io.BytesIO()
+    thumbnail.save(buffer, "JPEG", quality=70)
+    out["thumbnail_jpeg_b64"] = base64.b64encode(buffer.getvalue()).decode("ascii")
+
+    if ela is not None:
+        out["ela_map"] = _array_payload(_coarse(np, ela))
+    if residual is not None:
+        clipped = np.clip(residual / 4.0, -1, 1)
+        out["noise_residual"] = _array_payload(_coarse(np, (clipped * 127).astype(np.int8)))
+    if phase is not None:
+        out["fft_phase"] = _array_payload(_coarse(np, phase.astype(np.float32), 32))
+    return out
+
+
+def extract_pixel_evidence(image_path: Path, *, artifacts: bool = False, timings: bool = False) -> PixelEvidence:
+    """Measure every pixel-statistic family for one image in a single decode.
+
+    The image is decoded ONCE and the intermediate maps (high-pass residual, ELA
+    error, FFT magnitude and phase) are computed once and shared, because the
+    residual's sliding window and the ELA re-save are the two expensive steps and
+    each family would otherwise redo them.
+
+    A family that fails or does not apply is left empty rather than raising: an
+    undecodable file, or one too small for the block DCT, still returns a
+    :class:`PixelEvidence` whose ``decoded`` / empty fields say so. Missing numpy is
+    the one hard error, since then nothing can be measured at all.
+
+    Args:
+        image_path: Path to the image. Any container Pillow can open.
+        artifacts: Also return the spatial layer -- perceptual hash, thumbnail and
+            coarse maps. Off by default: those identify the source image, so asking
+            for them is a decision the caller makes explicitly.
+        timings: Measure each stage and include rounded milliseconds in
+            :attr:`PixelEvidence.timing_ms`.
+
+    Returns:
+        A :class:`PixelEvidence`.
+    """
+    started = time.perf_counter()
+    stage_started = started
+    measured: dict[str, float] = {}
+
+    gray, rgb, info = read_gray(image_path)
+    measured["decode"] = time.perf_counter() - stage_started
+    if gray is None or rgb is None:
+        measured["total"] = time.perf_counter() - started
+        timing_ms = {name: round(seconds * 1000, 1) for name, seconds in measured.items()} if timings else {}
+        return PixelEvidence(path=image_path, decode=info, timing_ms=timing_ms)
+
+    families: dict[str, dict[str, Any]] = {}
+
+    residual = None
+    stage_started = time.perf_counter()
+    try:
+        residual = noise_residual_map(gray)
+        families["noise"] = noise_features(residual) if residual is not None else {}
+    except Exception as exc:
+        logger.debug("pixel family noise failed for %s: %s", image_path, exc)
+        families["noise"] = {"error": type(exc).__name__}
+    measured["noise"] = time.perf_counter() - stage_started
+
+    spectrum = None
+    stage_started = time.perf_counter()
+    try:
+        spectrum = fft_decompose(gray)
+        families["fft"] = fft_features(spectrum[0]) if spectrum is not None else {}
+    except Exception as exc:
+        logger.debug("pixel family fft failed for %s: %s", image_path, exc)
+        families["fft"] = {"error": type(exc).__name__}
+    measured["fft"] = time.perf_counter() - stage_started
+
+    error = None
+    stage_started = time.perf_counter()
+    try:
+        error = ela_map(rgb)
+        families["ela"] = ela_features(error) if error is not None else {}
+    except Exception as exc:
+        logger.debug("pixel family ela failed for %s: %s", image_path, exc)
+        families["ela"] = {"error": type(exc).__name__}
+    measured["ela"] = time.perf_counter() - stage_started
+
+    for name, compute in (
+        ("dct", lambda: dct_features(gray)),
+        ("gradient", lambda: gradient_features(gray)),
+        ("color", lambda: color_features(rgb)),
+    ):
+        stage_started = time.perf_counter()
+        try:
+            families[name] = compute()
+        except Exception as exc:  # one bad family must not lose the other five
+            logger.debug("pixel family %s failed for %s: %s", name, image_path, exc)
+            families[name] = {"error": type(exc).__name__}
+        measured[name] = time.perf_counter() - stage_started
+
+    if artifacts:
+        stage_started = time.perf_counter()
+        try:
+            families["artifacts"] = spatial_artifacts(
+                gray, rgb, ela=error, residual=residual, phase=spectrum[1] if spectrum is not None else None
+            )
+        except Exception as exc:
+            logger.debug("pixel artifacts failed for %s: %s", image_path, exc)
+            families["artifacts"] = {"error": type(exc).__name__}
+        measured["full_artifacts"] = time.perf_counter() - stage_started
+
+    measured["total"] = time.perf_counter() - started
+    timing_ms = {name: round(seconds * 1000, 1) for name, seconds in measured.items()} if timings else {}
+    return PixelEvidence(path=image_path, decode=info, timing_ms=timing_ms, **families)

src/remove_ai_watermarks/qwen_engine.py

@@ -52,11 +52,9 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from remove_ai_watermarks import _text_mark_engine
-from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkEngine
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from numpy.typing import NDArray
 
 # Locate geometry as a fraction of the image SHORT side (measured basis -- see
@@ -122,8 +120,6 @@ _CONFIG = TextMarkConfig(
     provenance_ncc_factor=1.0,
 )
 
-QwenDetection = TextMarkDetection
-
 
 def _alpha_template() -> NDArray[Any] | None:
     """The bundled Qwen alpha template (float [0,1]), or None."""
@@ -135,23 +131,8 @@ def _glyph_silhouette() -> NDArray[Any] | None:
     return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
 
 
-def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
-    """TM_CCOEFF_NORMED of the Qwen glyph silhouette against ``box_mask``."""
-    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
-
-
 class QwenEngine(TextMarkEngine):
     """Detect/localize the visible Qwen "千问AI生成" watermark (locate -> mask; mask feeds the fill)."""
 
     def __init__(self) -> None:
         super().__init__(_CONFIG)
-
-
-def load_image_bgr(path: str | Path) -> NDArray[Any]:
-    """Read an image as BGR ndarray (helper for scripts/tests)."""
-    from remove_ai_watermarks import image_io
-
-    img = image_io.imread(path)
-    if img is None:
-        raise FileNotFoundError(f"Failed to read image: {path}")
-    return img

src/remove_ai_watermarks/region_eraser.py

@@ -21,6 +21,10 @@ Backends:
     texture but ~200 MB model and ~4.7 GB peak RAM (too heavy for a small host).
     The model is downloaded on first use and cached by huggingface_hub; it is
     never bundled in this repo.
+
+The per-backend RAM and wall-time figures above are reproduced by
+``scripts/resource_ceilings.py`` (fresh subprocess per measurement, synthetic inputs).
+Re-run it before changing any of them.
 """
 
 # cv2/numpy boundary: cv2 ships no usable type info, so strict pyright cannot know
@@ -30,6 +34,7 @@ Backends:
 from __future__ import annotations
 
 import logging
+from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Literal
 
 import cv2
@@ -48,9 +53,38 @@ _LAMA_FILE = "lama_fp32.onnx"
 _MIGAN_REPO = "andraniksargsyan/migan"
 _MIGAN_FILE = "migan.onnx"
 
-# Cached onnxruntime sessions (loading is expensive; reuse across calls).
-_lama_session: object | None = None
-_migan_session: object | None = None
+# Cached onnxruntime sessions, keyed by backend name (loading is expensive; reuse
+# across calls).
+_sessions: dict[str, object] = {}
+
+
+@dataclass(frozen=True)
+class _LearnedBackend:
+    """One optional model-backed fill: its human label and the module-level names of
+    its availability probe and erase function.
+
+    NAMES, not function objects: the fallback tests monkeypatch these by attribute on
+    the module, and a table holding bound references would not see the patch.
+    """
+
+    label: str
+    available: str
+    erase: str
+
+
+# The learned tier, best-quality first. `resolve_backend`'s preference order and the
+# CLI's choices are separate literals by design (see FILL_BACKENDS below), but the
+# availability probe, install hint and dispatch all read this one table.
+_LEARNED_BACKENDS: dict[str, _LearnedBackend] = {
+    "lama": _LearnedBackend("LaMa", "lama_available", "erase_lama"),
+    "migan": _LearnedBackend("MI-GAN", "migan_available", "erase_migan"),
+}
+
+# Every fill backend this module can execute, plus the caller-facing `auto`. Kept as a
+# literal tuple (not derived through an import) so `watermark_registry` and the CLI can
+# state their choices without importing this cv2-loading module at their import time --
+# a test pins the two in sync.
+FILL_BACKENDS: tuple[str, ...] = ("auto", "cv2", "migan", "lama")
 
 
 def boxes_to_mask(
@@ -119,19 +153,25 @@ def lama_available() -> bool:
     return module_available("onnxruntime")
 
 
-def _get_lama_session() -> object:
-    """Load (once) the big-LaMa ONNX session, downloading the model on first use."""
-    global _lama_session
-    if _lama_session is not None:
-        return _lama_session
+def _get_session(name: str, repo_id: str, filename: str, label: str) -> object:
+    """Load (once) an ONNX session, downloading the model on first use."""
+    cached = _sessions.get(name)
+    if cached is not None:
+        return cached
 
     import onnxruntime as ort
     from huggingface_hub import hf_hub_download
 
-    model_path = hf_hub_download(repo_id=_LAMA_REPO, filename=_LAMA_FILE)
-    logger.info("Loading LaMa-ONNX model: %s", model_path)
-    _lama_session = ort.InferenceSession(model_path, providers=["CPUExecutionProvider"])
-    return _lama_session
+    model_path = hf_hub_download(repo_id=repo_id, filename=filename)
+    logger.info("Loading %s model: %s", label, model_path)
+    session = ort.InferenceSession(model_path, providers=["CPUExecutionProvider"])
+    _sessions[name] = session
+    return session
+
+
+def _get_lama_session() -> object:
+    """The big-LaMa ONNX session (kept as a named seam the tests monkeypatch)."""
+    return _get_session("lama", _LAMA_REPO, _LAMA_FILE, "LaMa-ONNX")
 
 
 def erase_lama(image_bgr: NDArray[Any], mask: NDArray[Any]) -> NDArray[Any]:
@@ -196,25 +236,21 @@ def erase_lama(image_bgr: NDArray[Any], mask: NDArray[Any]) -> NDArray[Any]:
 
 
 def migan_available() -> bool:
-    """True when the optional MI-GAN backend can run (onnxruntime installed)."""
+    """True when the optional MI-GAN backend can run (onnxruntime installed).
+
+    Deliberately a separate function from :func:`lama_available` even though both
+    currently reduce to the same onnxruntime probe: they are independent capability
+    questions and `auto` resolves them separately (see
+    ``watermark_registry.preferred_inpaint_backend``).
+    """
     from .optional_deps import module_available
 
     return module_available("onnxruntime")
 
 
 def _get_migan_session() -> object:
-    """Load (once) the MI-GAN ONNX session, downloading the model on first use."""
-    global _migan_session
-    if _migan_session is not None:
-        return _migan_session
-
-    import onnxruntime as ort
-    from huggingface_hub import hf_hub_download
-
-    model_path = hf_hub_download(repo_id=_MIGAN_REPO, filename=_MIGAN_FILE)
-    logger.info("Loading MI-GAN ONNX model: %s", model_path)
-    _migan_session = ort.InferenceSession(model_path, providers=["CPUExecutionProvider"])
-    return _migan_session
+    """The MI-GAN ONNX session (kept as a named seam the tests monkeypatch)."""
+    return _get_session("migan", _MIGAN_REPO, _MIGAN_FILE, "MI-GAN ONNX")
 
 
 def erase_migan(image_bgr: NDArray[Any], mask: NDArray[Any]) -> NDArray[Any]:
@@ -308,16 +344,17 @@ def erase(
     if not mask.any():
         return image_bgr.copy()
 
-    if backend == "migan":
-        if not migan_available():
+    learned = _LEARNED_BACKENDS.get(backend)
+    if learned is not None:
+        # Probe and erase by MODULE NAME, not by the captured function object: the
+        # availability probes and the erase functions are monkeypatched by name in the
+        # fallback tests, and a table of bound references would not see those patches.
+        if not globals()[learned.available]():
             raise RuntimeError(
-                "MI-GAN backend requires onnxruntime. Install the extra: pip install 'remove-ai-watermarks[migan]'"
+                f"{learned.label} backend requires onnxruntime. "
+                f"Install the extra: pip install 'remove-ai-watermarks[{backend}]'"
             )
-        return erase_migan(image_bgr, mask)
-    if backend == "lama":
-        if not lama_available():
-            raise RuntimeError(
-                "LaMa backend requires onnxruntime. Install the extra: pip install 'remove-ai-watermarks[lama]'"
-            )
-        return erase_lama(image_bgr, mask)
+        return globals()[learned.erase](image_bgr, mask)
+    # cv2 and anything unrecognized (including "auto", which a library caller may pass
+    # straight through) degrade to the classical fill rather than raising.
     return erase_cv2(image_bgr, mask, method=cv2_method, radius=cv2_radius)

src/remove_ai_watermarks/runninghub_engine.py

@@ -48,13 +48,16 @@ import logging
 from typing import TYPE_CHECKING, Any
 
 from remove_ai_watermarks import _text_mark_engine
-from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+from remove_ai_watermarks._text_mark_engine import (
+    TextMarkConfig,
+    TextMarkDetection,
+    TextMarkEngine,
+    TextMarkScan,
+)
 
 logger = logging.getLogger(__name__)
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from numpy.typing import NDArray
 
 # Locate geometry as a fraction of the image WIDTH (the measured basis: every
@@ -111,24 +114,12 @@ _CONFIG = TextMarkConfig(
     provenance_ncc_factor=1.0,
 )
 
-RunningHubDetection = TextMarkDetection
-
 
 def _alpha_template() -> NDArray[Any] | None:
     """The bundled RunningHub alpha template (float [0,1]), or None."""
     return _text_mark_engine.load_alpha_template(_CONFIG.asset_name)
 
 
-def _glyph_silhouette() -> NDArray[Any] | None:
-    """Binary "RunningHub AI生成" silhouette (255 = glyph) from the alpha map, or None."""
-    return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
-
-
-def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
-    """TM_CCOEFF_NORMED of the RunningHub glyph silhouette against ``box_mask``."""
-    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
-
-
 class RunningHubEngine(TextMarkEngine):
     """Detect/localize the visible RunningHub "RunningHub AI生成" mark (top-left; localize -> fill)."""
 
@@ -140,18 +131,21 @@ class RunningHubEngine(TextMarkEngine):
     _ANCHOR_MAX_X = 0.025
     _ANCHOR_MAX_Y = 0.015
 
-    def detect(self, image: NDArray[Any], *, provenance: bool = False) -> TextMarkDetection:
-        det = super().detect(image, provenance=provenance)
-        if not det.detected:
+    def _post_gate(self, det: TextMarkDetection, scan: TextMarkScan) -> TextMarkDetection:
+        """Demote a match that does not hug the top-left corner.
+
+        A shared post-gate rather than a ``detect`` override, so the single-pass
+        perception path (``detect_both``) cannot skip it.
+        """
+        if not det.detected or scan.loc is None:
             return det
-        loc = self.locate(image)
-        _, box = self._gray_best(image, loc)
+        box = det.match_box  # the sweep the scan already ran on this same loc
         if box is None:
             det.detected = False
             return det
-        h, w = image.shape[:2]
-        ax = (loc.x + box[0]) / w
-        ay = (loc.y + box[1]) / h
+        h, w = scan.frame
+        ax = (scan.loc.x + box[0]) / w
+        ay = (scan.loc.y + box[1]) / h
         if ax > self._ANCHOR_MAX_X or ay > self._ANCHOR_MAX_Y:
             logger.debug(
                 "RunningHub detect: score %.3f but match off-anchor (x=%.3f y=%.3f); demoting.",
@@ -161,13 +155,3 @@ class RunningHubEngine(TextMarkEngine):
             )
             det.detected = False
         return det
-
-
-def load_image_bgr(path: str | Path) -> NDArray[Any]:
-    """Read an image as BGR ndarray (helper for scripts/tests)."""
-    from remove_ai_watermarks import image_io
-
-    img = image_io.imread(path)
-    if img is None:
-        raise FileNotFoundError(f"Failed to read image: {path}")
-    return img

src/remove_ai_watermarks/samsung_engine.py

@@ -28,7 +28,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from remove_ai_watermarks import _text_mark_engine
-from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkEngine
 
 if TYPE_CHECKING:
     from numpy.typing import NDArray
@@ -79,8 +79,6 @@ _CONFIG = TextMarkConfig(
     min_gw=16,
 )
 
-SamsungDetection = TextMarkDetection
-
 
 def _alpha_template() -> NDArray[Any] | None:
     """The bundled Samsung alpha template (float [0,1]), or None."""

src/remove_ai_watermarks/upscaler.py

@@ -1,126 +0,0 @@
-"""Optional pre-diffusion super-resolution for small inputs (Real-ESRGAN via spandrel).
-
-Mirrors ``region_eraser``'s optional-backend pattern: ``is_available()`` guards the
-``spandrel`` import, a lazy singleton (double-checked lock) holds the loaded model, and
-the weights download on first use (cached by ``torch.hub``) -- they are never bundled.
-
-The DEFAULT upscaler stays Lanczos (cv2, no deps); this is opt-in via the ``esrgan``
-extra and feeds the ``--upscaler esrgan`` path. ``spandrel`` is a pure model-loader
-(MIT) with NO basicsr dependency -- it pulls only torch/torchvision/safetensors/numpy/
-einops -- so it sidesteps the basicsr / ``torchvision.transforms.functional_tensor``
-breakage that the retired ``restore`` (GFPGAN) extra had to shim. Real-ESRGAN weights
-are BSD-3-Clause.
-
-CPU works but is slow on large inputs, so this is meant for the pre-diffusion upscale of
-SMALL inputs (and the GPU worker). On a memory-constrained host it is a no-op (the extra
-is absent), and the caller falls back to Lanczos.
-"""
-
-# torch/spandrel boundary: these libs ship no usable element types; relax the
-# unknown-type rules for this file only.
-# pyright: reportUnknownMemberType=false, reportUnknownArgumentType=false, reportUnknownVariableType=false, reportUnknownParameterType=false, reportMissingTypeArgument=false, reportMissingTypeStubs=false, reportMissingImports=false, reportArgumentType=false, reportAssignmentType=false, reportReturnType=false, reportCallIssue=false, reportIndexIssue=false, reportOperatorIssue=false, reportAttributeAccessIssue=false, reportPrivateImportUsage=false
-from __future__ import annotations
-
-import logging
-import threading
-from pathlib import Path
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from numpy.typing import NDArray
-
-logger = logging.getLogger(__name__)
-
-# Real-ESRGAN x2plus (BSD-3-Clause), official release. x2 is the right native factor for
-# the pre-diffusion floor upscale (small inputs ~512 -> ~1024); spandrel infers the
-# architecture and scale from the checkpoint, so swapping the URL is enough to change it.
-_MODEL_URL = "https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.1/RealESRGAN_x2plus.pth"
-_MODEL_FILENAME = "RealESRGAN_x2plus.pth"
-
-_model: Any = None  # lazy singleton (spandrel ImageModelDescriptor)
-_model_device: str = "cpu"
-_lock = threading.Lock()
-
-
-def is_available() -> bool:
-    """True if the ``esrgan`` extra (spandrel + torch) is importable."""
-    from .optional_deps import module_available
-
-    return module_available("spandrel", "torch")
-
-
-def _model_cache_path() -> Path:
-    """Path the weights are cached at (the torch.hub checkpoints dir)."""
-    import torch
-
-    cache_dir = Path(torch.hub.get_dir()) / "checkpoints"
-    cache_dir.mkdir(parents=True, exist_ok=True)
-    return cache_dir / _MODEL_FILENAME
-
-
-def _get_model(device: str) -> Any:
-    """Load the Real-ESRGAN model once (downloading the weights on first use)."""
-    global _model, _model_device
-    if _model is not None and _model_device == device:
-        return _model
-    with _lock:
-        if _model is None:
-            import torch
-            from spandrel import ImageModelDescriptor, ModelLoader
-
-            dst = _model_cache_path()
-            if not dst.exists():
-                logger.info("Downloading Real-ESRGAN weights to %s", dst)
-                torch.hub.download_url_to_file(_MODEL_URL, str(dst), progress=False)
-            model = ModelLoader().load_from_file(str(dst))
-            if not isinstance(model, ImageModelDescriptor):
-                raise RuntimeError(f"Unexpected spandrel model type: {type(model).__name__}")
-            _model = model.eval()
-        if _model_device != device:
-            _model.to(device)
-            _model_device = device
-    return _model
-
-
-def scale() -> int:
-    """The model's native upscale factor (e.g. 2 for x2plus). Loads the model if needed."""
-    return int(_get_model("cpu").scale)
-
-
-def upscale(image: NDArray[Any], device: str | None = None) -> NDArray[Any]:
-    """Upscale a BGR uint8 image by the model's native factor with Real-ESRGAN.
-
-    Returns a BGR uint8 array. Falls back to CPU if the requested device errors (an
-    MPS/CUDA OOM or unsupported-op on the small pre-diffusion input), mirroring the
-    diffusion engine's MPS->CPU fallback.
-
-    Raises:
-        RuntimeError: if the ``esrgan`` extra is not installed (guard with
-            ``is_available()`` first).
-    """
-    if not is_available():
-        raise RuntimeError("Real-ESRGAN upscaler needs the 'esrgan' extra (spandrel). Install it or use Lanczos.")
-    import cv2
-    import numpy as np
-    import torch
-
-    target_device = (device or "cpu").lower()
-    if target_device not in {"cpu", "mps", "cuda", "xpu"}:
-        target_device = "cpu"
-    rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
-    tensor = torch.from_numpy(rgb).permute(2, 0, 1).float().div(255.0).unsqueeze(0)
-
-    def _run(dev: str) -> NDArray[Any]:
-        model = _get_model(dev)
-        with torch.no_grad():
-            out = model(tensor.to(dev))
-        arr = out.clamp(0.0, 1.0).squeeze(0).permute(1, 2, 0).cpu().numpy() * 255.0
-        return cv2.cvtColor(arr.round().astype(np.uint8), cv2.COLOR_RGB2BGR)
-
-    try:
-        return _run(target_device)
-    except Exception as e:  # GPU OOM / unsupported op: fall back to CPU
-        if target_device == "cpu":
-            raise
-        logger.warning("Real-ESRGAN on %s failed (%s); retrying on CPU", target_device, e)
-        return _run("cpu")