gainmap-audit 0.1.0__tar.gz

gainmap_audit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest

gainmap_audit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,65 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v[0-9]+.[0-9]+.[0-9]+"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # The version lives in both pyproject.toml and __init__.py, so check the
+      # tag against both rather than letting them drift apart silently.
+      - name: Check the tag matches the package version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME#v}"
+          init=$(python -c "import re;print(re.search(r'__version__ = \"([^\"]+)\"', open('src/gainmap_audit/__init__.py').read()).group(1))")
+          proj=$(python -c "import re;print(re.search(r'^version = \"([^\"]+)\"', open('pyproject.toml').read(), re.M).group(1))")
+          test "${tag}" = "${init}" || { echo "tag ${tag} != __init__ ${init}"; exit 1; }
+          test "${tag}" = "${proj}" || { echo "tag ${tag} != pyproject ${proj}"; exit 1; }
+
+      - run: python -m pip install --disable-pip-version-check build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/gainmap-audit
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      # Uses the PYPI_API_TOKEN secret. To move to Trusted Publishing, register this workflow
+      # and the `pypi` environment on pypi.org, then drop the `password` line; the id-token
+      # permission above is already in place for it.
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip-existing: true

gainmap_audit-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+tests/.cache/

gainmap_audit-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project uses [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-09-22
+
+Initial release.
+
+### Added
+- `gmaudit check` / `scan` / `diff` CLI subcommands with `--json`, `--csv`,
+  `--fail-on`, and `--verify-with-uhdrtool` options.
+- Detection of four HDR gain map flavours: Adobe/Google Ultra HDR
+  (`ultrahdr`), ISO/IEC TS 21496-1 in JPEG (`iso-jpeg`) and in HEIF/AVIF
+  (`iso-heif`), and Apple's auxiliary gain map (`apple-aux`).
+- `orphaned` state for files whose MPF/HEIF plumbing still references a
+  gain map that nothing points a viewer at.
+- Filename-based pairing (`stem` or `relpath`) for auditing a source tree
+  against its exports.
+- Dependency-free, stdlib-only implementation; read-only, never modifies
+  the files it inspects.

gainmap_audit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Bosch
+
+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.

gainmap_audit-0.1.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.5
+Name: gainmap-audit
+Version: 0.1.0
+Summary: Find photos whose HDR gain map was lost in an editing round trip
+Project-URL: Homepage, https://github.com/Booyaka101/gainmap-audit
+Project-URL: Repository, https://github.com/Booyaka101/gainmap-audit
+Project-URL: Changelog, https://github.com/Booyaka101/gainmap-audit/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Booyaka101/gainmap-audit/issues
+Author-email: Chris Bosch <cbosch101@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: avif,gain-map,hdr,heic,jpeg,metadata,photography,ultrahdr
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gainmap-audit
+
+Find photos whose HDR gain map was lost in an editing round trip.
+
+An HDR gain map is the extra metadata that lets a JPEG or HEIC render bright
+highlights on an HDR display while staying a normal SDR image everywhere
+else (Apple's "HDR photo" format, Google's Ultra HDR, and the ISO 21496-1
+standard all work this way). It is exactly the kind of thing an editor,
+resizer, or cloud photo library silently drops: the photo still opens fine,
+it just renders flat everywhere from then on. `gmaudit` finds those photos
+before you notice months later that your library went dark.
+
+**`gmaudit` never writes to your images.** It opens files read-only, parses
+container metadata, and reports what it finds. It does not decode pixels,
+does not repair anything, and does not touch the filesystem except to read.
+If you want to actually rebuild a stripped gain map, that's a job for
+[`uhdrtool`](https://github.com/google/libultrahdr); `gmaudit` can shell out
+to it for cross-verification (`--verify-with-uhdrtool`) but never invokes it
+to modify a file.
+
+## Install
+
+```
+pip install gainmap-audit
+```
+
+Requires Python 3.10+. No dependencies beyond the standard library.
+
+## The problem, in one real run
+
+An iPhone photo with an Apple HDR gain map, exported through an editor that
+doesn't understand gain maps, comes back as a plain JPEG with the same name.
+Nothing in a file browser or thumbnail flags this:
+
+```
+$ gmaudit diff photos/ export/
+VERDICT   PAIR                           STATE
+STRIPPED  IMG_0421.HEIC -> IMG_0421.jpg  apple-aux -> none
+1 pair: 1 stripped
+$ echo $?
+1
+```
+
+`gmaudit` paired the files by name, classified each one, and flagged the
+loss. The same photo can also come back `iso-heif -> none` (Apple began
+shipping ISO 21496-1 gain maps in iOS 18) -- either way, once the source
+carried a gain map and the export doesn't, `gmaudit` calls it `STRIPPED`.
+
+## Usage
+
+### Classify individual files
+
+```
+$ gmaudit check IMG_0421.HEIC
+STATE      PATH             SIZE    RULES      ERROR
+APPLE-AUX  IMG_0421.HEIC    238982  apple-aux
+1 file: 1 apple-aux
+```
+
+Add `--json` for machine-readable output:
+
+```
+$ gmaudit check IMG_0421.HEIC --json
+{
+  "files": [
+    {
+      "path": "IMG_0421.HEIC",
+      "state": "apple-aux",
+      "container": "isobmff",
+      "size": 238982,
+      "rules_fired": ["apple-aux"],
+      "evidence": [
+        {"rule": "ftyp", "detail": "brands heic, mif1, MiHE, miaf, MiHB", "offset": 0},
+        {
+          "rule": "apple-aux",
+          "detail": "ipma links item 10 to auxC aux_type urn:com:apple:photo:2020:aux:hdrgainmap; iref auxl -> base item 7",
+          "offset": 36
+        }
+      ],
+      "gain_map": {"source": "auxc-item", "offset": null, "length": null, "mime": "", "item_id": 10},
+      "error": null
+    }
+  ]
+}
+```
+
+### Scan a whole folder
+
+```
+$ gmaudit scan tests/corpus
+STATE      PATH                                               SIZE    RULES      ERROR
+APPLE-AUX  tests\corpus\apple_gainmap_new.jpg                 50824   apple-aux
+APPLE-AUX  tests\corpus\apple_hdr_sample.heic                 238982  apple-aux
+NONE       tests\corpus\colors_sdr_srgb.avif                  18845   -
+ULTRAHDR   tests\corpus\paris_exif_xmp_gainmap_bigendian.jpg  47579   ultrahdr
+NONE       tests\corpus\sample_srgb.jpg                       154458  -
+ISO-HEIF   tests\corpus\seine_sdr_gainmap_notmapbrand.avif    129769  iso-heif
+ISO-JPEG   tests\corpus\small_uhdr.jpg                        39385   iso-jpeg
+7 files: 2 apple-aux, 2 none, 1 ultrahdr, 1 iso-heif, 1 iso-jpeg
+```
+
+Add `-r` / `--recursive` to descend into subdirectories. Hidden directories,
+`@eaDir`/`@__thumb`/`.thumbnails`/`$RECYCLE.BIN`, and sidecar files
+(`.xmp`, `.aae`) are skipped automatically.
+
+### Diff a source tree against its exports
+
+```
+$ gmaudit diff photos/ export/ -r
+```
+
+Pairs files by filename stem, case-insensitively, so an extension change
+across the round trip (`.HEIC` in, `.jpg` out) still matches. Pass
+`--match relpath` to pair by path relative to each root instead, if your
+export keeps the folder structure but changes every filename.
+
+Each pair gets one of:
+
+| Verdict | Meaning |
+|---|---|
+| `OK` | both sides carry a gain map |
+| `STRIPPED` | source had one, export doesn't |
+| `ORPHANED` | source had one, export has broken/unreachable gain map plumbing |
+| `DEGRADED` | source never had one, export ended up with broken gain map plumbing anyway |
+| `ADDED` | export gained a gain map the source didn't have |
+| `SDR-BOTH` | neither side has one |
+| `UNPAIRED-SOURCE` | no matching export found |
+| `UNPAIRED-EXPORT` | no matching source found |
+| `AMBIGUOUS` | more than one file on either side shares the same pairing key |
+| `ERROR` | one side couldn't be read/parsed |
+
+### Global options
+
+- `--json` -- emit JSON instead of the table (schema shown above; `diff` emits `{"pairs": [...]}`).
+- `--csv PATH` -- also write results as CSV to `PATH`.
+- `--fail-on LIST` -- comma-separated states/verdicts that make the process exit 1.
+  Default: `stripped,orphaned`.
+- `--verify-with-uhdrtool [PATH]` -- run `uhdrtool detect -in FILE` on every JPEG
+  and print a warning to stderr wherever it disagrees with `gmaudit`'s verdict.
+  Looks up `uhdrtool` on `PATH` if no argument is given.
+
+### Exit codes
+
+- `0` -- ran clean, nothing matched `--fail-on`.
+- `1` -- at least one file/pair matched `--fail-on`, or one couldn't be read/parsed at all.
+- `2` -- usage error: bad flags, missing directory, unreadable arguments.
+
+## What it detects
+
+Four independent rules run against every file; each records its own
+evidence, and the highest-precedence rule that fired wins the reported
+state (`ultrahdr` > `iso-jpeg` > `iso-heif` > `apple-aux` > `orphaned`):
+
+1. **`ultrahdr`** -- `hdrgm:Version` in the primary image's XMP (Adobe/Google
+   Ultra HDR), cross-referenced against the `Container:Directory` and any
+   MPF secondary image.
+2. **`iso-jpeg`** -- an APP2 segment identified by the literal
+   `urn:iso:std:iso:ts:21496:-1` (ISO/IEC TS 21496-1).
+3. **`iso-heif`** -- a `tmap` derived item in the HEIF/AVIF `meta` box,
+   normally linked to its base image by an `iref` `dimg` reference.
+4. **`apple-aux`** -- an `auxC` box naming
+   `urn:com:apple:photo:2020:aux:hdrgainmap` (HEIC), or an MPF secondary
+   image whose own XMP carries `apdi:AuxiliaryImageType` or
+   `HDRGainMap:HDRGainMapVersion` (JPEG). If the container can't be parsed
+   at all, a byte-level scan for the same URN literal is used as a fallback
+   (evidence rule `urn-scan`), so a file with an unusual box layout still
+   gets flagged rather than silently reported clean.
+
+A fifth state, **`orphaned`**, is not a gain map flavour but a warning: the
+MPF index still lists a second image that looks like a gain map, but nothing
+in the primary XMP points a viewer at it. That's what a half-completed strip
+or a buggy re-encode looks like from the outside, and it's exactly the case
+`--fail-on orphaned` (the default) is there to catch.
+
+`gmaudit` never crashes on a bad file. Truncated, zero-byte, unreadable, or
+non-image files are reported with `state: error` and a reason, not a
+traceback.
+
+## Testing
+
+```
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+The test suite builds its own JPEG and ISOBMFF byte streams for unit tests
+(`tests/builders.py`, `tests/builders_isobmff.py`), classifies a committed
+corpus of real sample files (`tests/corpus/`, sourced and licensed per
+`tests/corpus/SOURCES.md`), and strips XMP from a real Ultra HDR JPEG inside
+`tests/test_roundtrip.py` to prove the `orphaned` detection actually fires on
+real bytes, not just synthetic ones. `tests/test_download_integration.py`
+pulls two more pinned real files over the network and skips cleanly if it
+can't reach them.
+
+## Limitations
+
+- Detects the four gain map flavours in current use. A future or
+  proprietary flavour with none of these markers reports `none`, correctly
+  meaning "no gain map found," not "verified absent by inspecting pixels."
+- Pairing across a source and export tree is filename-based (stem or
+  relative path). If an export tool renames files unpredictably, pairing
+  won't find the match.
+- `--verify-with-uhdrtool` only checks JPEGs, since that's what `uhdrtool`
+  understands.

gainmap_audit-0.1.0/PROGRESS.md

@@ -0,0 +1,38 @@
+# Build progress
+
+Autonomous build log for `gainmap-audit`. Newest entry last.
+
+## Phase 1 — core parsers and detection
+- `reader.py`: bounded, read-only file windowing (`FileWindow.read_at`/`find`), never opens a file twice.
+- `jpeg.py`: marker-stream walker (SOI/APPn/SOS/EOI), APP1 XMP (standard + extended/GUID-reassembled), APP2 MPF (CIPA DC-007, 16-byte MP Entry, offsets relative to the MP Header).
+- `isobmff.py`: box walker for ftyp/meta/iinf/infe/iref/iprp/ipco/auxC/pitm, HEIF/AVIF item graph traversal.
+- `xmp.py`: namespace-aware textual RDF/XML lookup (no DOM parser), `Xmp.declares`/`get`/`has`/`prefixes_for`/`container_items`/`gain_map_item`.
+- `detect.py`: four precedence-resolved rules (`ultrahdr` > `iso-jpeg` > `iso-heif` > `apple-aux`), plus `orphaned` and `error` states.
+- Status: done.
+
+## Phase 2 — pairing, CLI, reporting
+- `pairing.py`: filename pairing (`stem`/`relpath`), verdict matrix (OK/STRIPPED/ORPHANED/DEGRADED/ADDED/SDR-BOTH/UNPAIRED-*/AMBIGUOUS/ERROR), directory walk skipping sidecars/hidden/junk dirs.
+- `cli.py`: `check`/`scan`/`diff` subcommands, `--json`/`--csv`/`--fail-on`/`--verify-with-uhdrtool`, exit 0/1/2.
+- `report.py`: human table and CSV writers.
+- Status: done.
+
+## Phase 3 — tests
+- Unit tests build real byte streams for every format (`tests/builders.py`, `tests/builders_isobmff.py`) — no mocks.
+- `tests/corpus/` — 7 real sample files (licensed, sourced in `SOURCES.md`), classified against a documented expected-state table.
+- `tests/test_roundtrip.py` — strips real XMP from a real Ultra HDR JPEG, proves the resulting `orphaned` classification on real bytes.
+- `tests/test_download_integration.py` — two more pinned real files fetched over the network with sha256 verification, skips cleanly offline.
+- `tests/test_cli.py` — exit codes, JSON schema, the brief's HEIC->JPG worked example end to end through the CLI.
+- Result: 101 tests, all passing; `ruff check .` clean.
+- Status: done.
+
+## Phase 4 — packaging and docs
+- `pyproject.toml` (hatchling, stdlib-only, console_script `gmaudit`), version 0.1.0.
+- `README.md` with real captured CLI output (not hand-typed), install/usage/detection-rules/limitations sections, explicit "never modifies files" statement.
+- `CHANGELOG.md` starting at 0.1.0, `LICENSE` (MIT), `.gitignore`, `.github/workflows/ci.yml` (ubuntu/macos/windows x py3.10-3.13).
+- Verified: `python -m build --wheel` succeeds, `pip install dist/*.whl && gmaudit --version` works in a clean venv (`gmaudit 0.1.0`).
+- Status: done.
+
+## Phase 5 — final review
+- Clone-detection check (difflib on AST-extracted function line ranges): `jpeg.py` vs `isobmff.py` whole-module similarity 12.2%; `_rule_iso_jpeg` vs `_rule_iso_heif` 0.0%; `_rule_apple_jpeg` vs `_rule_apple_heif` 4.3%. All well under the ~60% extract-shared-mechanism threshold — the four detection rules are genuinely different mechanisms (raw byte/XMP matching vs. parsed ISOBMFF item-graph traversal), not clones.
+- Testing/build/lint bugs found and fixed during review were all in test fixtures (wrong MPF entry byte width, wrong MPF data_offset base, wrong MP type constant, one stale corpus doc note) — zero defects found in shipped production code.
+- Status: done.

gainmap_audit-0.1.0/README.md

@@ -0,0 +1,205 @@
+# gainmap-audit
+
+Find photos whose HDR gain map was lost in an editing round trip.
+
+An HDR gain map is the extra metadata that lets a JPEG or HEIC render bright
+highlights on an HDR display while staying a normal SDR image everywhere
+else (Apple's "HDR photo" format, Google's Ultra HDR, and the ISO 21496-1
+standard all work this way). It is exactly the kind of thing an editor,
+resizer, or cloud photo library silently drops: the photo still opens fine,
+it just renders flat everywhere from then on. `gmaudit` finds those photos
+before you notice months later that your library went dark.
+
+**`gmaudit` never writes to your images.** It opens files read-only, parses
+container metadata, and reports what it finds. It does not decode pixels,
+does not repair anything, and does not touch the filesystem except to read.
+If you want to actually rebuild a stripped gain map, that's a job for
+[`uhdrtool`](https://github.com/google/libultrahdr); `gmaudit` can shell out
+to it for cross-verification (`--verify-with-uhdrtool`) but never invokes it
+to modify a file.
+
+## Install
+
+```
+pip install gainmap-audit
+```
+
+Requires Python 3.10+. No dependencies beyond the standard library.
+
+## The problem, in one real run
+
+An iPhone photo with an Apple HDR gain map, exported through an editor that
+doesn't understand gain maps, comes back as a plain JPEG with the same name.
+Nothing in a file browser or thumbnail flags this:
+
+```
+$ gmaudit diff photos/ export/
+VERDICT   PAIR                           STATE
+STRIPPED  IMG_0421.HEIC -> IMG_0421.jpg  apple-aux -> none
+1 pair: 1 stripped
+$ echo $?
+1
+```
+
+`gmaudit` paired the files by name, classified each one, and flagged the
+loss. The same photo can also come back `iso-heif -> none` (Apple began
+shipping ISO 21496-1 gain maps in iOS 18) -- either way, once the source
+carried a gain map and the export doesn't, `gmaudit` calls it `STRIPPED`.
+
+## Usage
+
+### Classify individual files
+
+```
+$ gmaudit check IMG_0421.HEIC
+STATE      PATH             SIZE    RULES      ERROR
+APPLE-AUX  IMG_0421.HEIC    238982  apple-aux
+1 file: 1 apple-aux
+```
+
+Add `--json` for machine-readable output:
+
+```
+$ gmaudit check IMG_0421.HEIC --json
+{
+  "files": [
+    {
+      "path": "IMG_0421.HEIC",
+      "state": "apple-aux",
+      "container": "isobmff",
+      "size": 238982,
+      "rules_fired": ["apple-aux"],
+      "evidence": [
+        {"rule": "ftyp", "detail": "brands heic, mif1, MiHE, miaf, MiHB", "offset": 0},
+        {
+          "rule": "apple-aux",
+          "detail": "ipma links item 10 to auxC aux_type urn:com:apple:photo:2020:aux:hdrgainmap; iref auxl -> base item 7",
+          "offset": 36
+        }
+      ],
+      "gain_map": {"source": "auxc-item", "offset": null, "length": null, "mime": "", "item_id": 10},
+      "error": null
+    }
+  ]
+}
+```
+
+### Scan a whole folder
+
+```
+$ gmaudit scan tests/corpus
+STATE      PATH                                               SIZE    RULES      ERROR
+APPLE-AUX  tests\corpus\apple_gainmap_new.jpg                 50824   apple-aux
+APPLE-AUX  tests\corpus\apple_hdr_sample.heic                 238982  apple-aux
+NONE       tests\corpus\colors_sdr_srgb.avif                  18845   -
+ULTRAHDR   tests\corpus\paris_exif_xmp_gainmap_bigendian.jpg  47579   ultrahdr
+NONE       tests\corpus\sample_srgb.jpg                       154458  -
+ISO-HEIF   tests\corpus\seine_sdr_gainmap_notmapbrand.avif    129769  iso-heif
+ISO-JPEG   tests\corpus\small_uhdr.jpg                        39385   iso-jpeg
+7 files: 2 apple-aux, 2 none, 1 ultrahdr, 1 iso-heif, 1 iso-jpeg
+```
+
+Add `-r` / `--recursive` to descend into subdirectories. Hidden directories,
+`@eaDir`/`@__thumb`/`.thumbnails`/`$RECYCLE.BIN`, and sidecar files
+(`.xmp`, `.aae`) are skipped automatically.
+
+### Diff a source tree against its exports
+
+```
+$ gmaudit diff photos/ export/ -r
+```
+
+Pairs files by filename stem, case-insensitively, so an extension change
+across the round trip (`.HEIC` in, `.jpg` out) still matches. Pass
+`--match relpath` to pair by path relative to each root instead, if your
+export keeps the folder structure but changes every filename.
+
+Each pair gets one of:
+
+| Verdict | Meaning |
+|---|---|
+| `OK` | both sides carry a gain map |
+| `STRIPPED` | source had one, export doesn't |
+| `ORPHANED` | source had one, export has broken/unreachable gain map plumbing |
+| `DEGRADED` | source never had one, export ended up with broken gain map plumbing anyway |
+| `ADDED` | export gained a gain map the source didn't have |
+| `SDR-BOTH` | neither side has one |
+| `UNPAIRED-SOURCE` | no matching export found |
+| `UNPAIRED-EXPORT` | no matching source found |
+| `AMBIGUOUS` | more than one file on either side shares the same pairing key |
+| `ERROR` | one side couldn't be read/parsed |
+
+### Global options
+
+- `--json` -- emit JSON instead of the table (schema shown above; `diff` emits `{"pairs": [...]}`).
+- `--csv PATH` -- also write results as CSV to `PATH`.
+- `--fail-on LIST` -- comma-separated states/verdicts that make the process exit 1.
+  Default: `stripped,orphaned`.
+- `--verify-with-uhdrtool [PATH]` -- run `uhdrtool detect -in FILE` on every JPEG
+  and print a warning to stderr wherever it disagrees with `gmaudit`'s verdict.
+  Looks up `uhdrtool` on `PATH` if no argument is given.
+
+### Exit codes
+
+- `0` -- ran clean, nothing matched `--fail-on`.
+- `1` -- at least one file/pair matched `--fail-on`, or one couldn't be read/parsed at all.
+- `2` -- usage error: bad flags, missing directory, unreadable arguments.
+
+## What it detects
+
+Four independent rules run against every file; each records its own
+evidence, and the highest-precedence rule that fired wins the reported
+state (`ultrahdr` > `iso-jpeg` > `iso-heif` > `apple-aux` > `orphaned`):
+
+1. **`ultrahdr`** -- `hdrgm:Version` in the primary image's XMP (Adobe/Google
+   Ultra HDR), cross-referenced against the `Container:Directory` and any
+   MPF secondary image.
+2. **`iso-jpeg`** -- an APP2 segment identified by the literal
+   `urn:iso:std:iso:ts:21496:-1` (ISO/IEC TS 21496-1).
+3. **`iso-heif`** -- a `tmap` derived item in the HEIF/AVIF `meta` box,
+   normally linked to its base image by an `iref` `dimg` reference.
+4. **`apple-aux`** -- an `auxC` box naming
+   `urn:com:apple:photo:2020:aux:hdrgainmap` (HEIC), or an MPF secondary
+   image whose own XMP carries `apdi:AuxiliaryImageType` or
+   `HDRGainMap:HDRGainMapVersion` (JPEG). If the container can't be parsed
+   at all, a byte-level scan for the same URN literal is used as a fallback
+   (evidence rule `urn-scan`), so a file with an unusual box layout still
+   gets flagged rather than silently reported clean.
+
+A fifth state, **`orphaned`**, is not a gain map flavour but a warning: the
+MPF index still lists a second image that looks like a gain map, but nothing
+in the primary XMP points a viewer at it. That's what a half-completed strip
+or a buggy re-encode looks like from the outside, and it's exactly the case
+`--fail-on orphaned` (the default) is there to catch.
+
+`gmaudit` never crashes on a bad file. Truncated, zero-byte, unreadable, or
+non-image files are reported with `state: error` and a reason, not a
+traceback.
+
+## Testing
+
+```
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+The test suite builds its own JPEG and ISOBMFF byte streams for unit tests
+(`tests/builders.py`, `tests/builders_isobmff.py`), classifies a committed
+corpus of real sample files (`tests/corpus/`, sourced and licensed per
+`tests/corpus/SOURCES.md`), and strips XMP from a real Ultra HDR JPEG inside
+`tests/test_roundtrip.py` to prove the `orphaned` detection actually fires on
+real bytes, not just synthetic ones. `tests/test_download_integration.py`
+pulls two more pinned real files over the network and skips cleanly if it
+can't reach them.
+
+## Limitations
+
+- Detects the four gain map flavours in current use. A future or
+  proprietary flavour with none of these markers reports `none`, correctly
+  meaning "no gain map found," not "verified absent by inspecting pixels."
+- Pairing across a source and export tree is filename-based (stem or
+  relative path). If an export tool renames files unpredictably, pairing
+  won't find the match.
+- `--verify-with-uhdrtool` only checks JPEGs, since that's what `uhdrtool`
+  understands.