bobframes 0.1.0__tar.gz

bobframes-0.1.0/.gitignore

@@ -0,0 +1,57 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.Python
+*.egg-info/
+.eggs/
+*.egg
+build/
+dist/
+wheels/
+pip-wheel-metadata/
+
+# Virtual env
+.venv/
+venv/
+env/
+
+# Editor
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Test artifacts
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Project-specific: never commit user data, manifests, or rendered output
+**/_data/
+**/_reports/
+**/_stage/
+**/_tmp/
+**/index.html
+**/*.parquet
+**/*.rdc
+**/*.zip.xml
+**/_manifest.json
+**/done.marker
+
+# Exception: bundled test fixtures (ADR-8: synthetic _data + golden HTML are test code, not user
+# data). Must override the broad _data/_reports/index.html/parquet/manifest ignores above. Git
+# cannot un-ignore a file under an ignored directory, so re-include the directories first, then files.
+!bobframes/tests/data/
+!bobframes/tests/data/**/
+!bobframes/tests/data/**
+
+# Bobframes config
+.bobframes.toml
+
+# Generated docs (docs/plan/ IS tracked — only built output is ignored)
+docs/_build/
+
+# OS
+Thumbs.db

bobframes-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+Changes to this project are documented here, newest first.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-31
+
+First standalone release. v1 is Windows-only (the replay stage drives `qrenderdoc`).
+
+### Added
+- Single `bobframes` binary with subcommands `ingest`, `render`, `ab`, `report`, `catalog`, `lint`,
+  `check`, `serve`, `smoke`, and `version`. Positional `root` (default `.`) across verbs; long-flag
+  only; exit codes `0`/`1`/`2`/`3`/`4`. stdlib `logging` at INFO by default, `--verbose` for DEBUG,
+  `[HH:MM:SS]` line format (G-8).
+- Replay script located via `importlib.resources` (`bobframes.replay.replay_script_path`) so replay
+  works from an installed wheel, not just an in-tree checkout.
+- Reliability hardening: atomic writes for `_manifest.json`, Parquet+CSV pairs, and `done.marker`
+  (`.tmp` + `os.replace`, rollback on failure); process-tree kill (`taskkill /T /F`) when a
+  `qrenderdoc` replay times out; per-capture replay-failure isolation
+  (`capture_status='replay_failed'` instead of aborting the whole drop); subprocess stderr logged on
+  convert-timeout and on every parse; manifest provenance fields `tool_versions` and `host_info`.
+- Test gates: golden-snapshot parity, schema regression, determinism, performance, and a replay
+  column-drift guard against `schemas.py` (H-6); mocked-subprocess tests for the hardening branches
+  the GPU-less runner cannot exercise; a data-driven `smoke` (render-only against a bundled synthetic
+  fixture by default); unit tests for stable keys, schemas, and drop discovery.
+- GitHub Actions CI across a Windows / Python / pyarrow matrix, with a tag-gated PyPI publish job.
+
+### Changed
+- **Stable-key format upgrade:** stable keys now carry a `KEY_VERSION = 1` version byte in the hash
+  input. Keys produced before this release are not comparable with `0.1.0` keys; rebuild affected
+  data with `bobframes ingest --force`. `KEY_VERSION` bumps on any future key-derivation rule change.
+- Timestamps unified to a single UTC `now_iso()` helper (`bobframes.manifest.now_iso`); the
+  local-time variant in `reports/cli` was dropped.
+
+### Removed
+- The project-embedded `_analysis` package. `python -m _analysis.run` and the other
+  `python -m _analysis.*` entry points no longer work; switch to the `bobframes` commands (see the
+  migration table in the README). This is a hard rename with no compatibility shim.
+
+[Unreleased]: https://github.com/altpsyche/bobframes/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/altpsyche/bobframes/releases/tag/v0.1.0

bobframes-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siva Subramanyam, Mayhem Studios
+
+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.

bobframes-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: bobframes
+Version: 0.1.0
+Summary: RenderDoc capture pipeline: ingest, analyze, render.
+Project-URL: Homepage, https://github.com/altpsyche/bobframes
+Project-URL: Issues, https://github.com/altpsyche/bobframes/issues
+Project-URL: Changelog, https://github.com/altpsyche/bobframes/blob/main/CHANGELOG.md
+Author-email: Siva Subramanyam <sivasubramanyam@mayhem-studios.com>
+License: MIT
+License-File: LICENSE
+Keywords: gpu,parquet,profiling,renderdoc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+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 :: Software Development :: Debuggers
+Requires-Python: <3.15,>=3.10
+Requires-Dist: pyarrow<22,>=17
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# BobFrames
+
+RenderDoc capture pipeline: ingest, analyze, render. Point it at a folder of `.rdc` captures and it
+produces `_data/` (Parquet tables) plus `_reports/` (static HTML you can browse). Windows-only in v1.
+
+## Requirements
+
+- Windows 10 or later (the replay stage drives `qrenderdoc`, which is Windows-only in v1).
+- Python 3.10 - 3.13.
+- RenderDoc 1.x, or Arm Performance Studio, providing `renderdoccmd` and `qrenderdoc` on disk.
+
+## Install
+
+```
+pipx install bobframes
+bobframes check
+```
+
+`bobframes check` prints the resolved paths for `renderdoccmd` and `qrenderdoc` and exits non-zero if
+either is missing, so you can confirm the toolchain before a long ingest.
+
+## Quickstart
+
+```
+cd path\to\captures      # a folder of <Area>\<YYYY-MM-DD[_label]>\*.rdc
+bobframes ingest .       # export, parse, replay, parquetize, derive, render
+bobframes serve .        # open a local static preview of the reports
+```
+
+`ingest` writes Parquet under `_data/` and HTML under `_reports/`. Re-run `bobframes render .` any
+time to rebuild the HTML from existing Parquet without re-replaying captures.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `ingest [root] [--area X] [--label Y] [--capture N] [--force] [--pixel-grid 4] [--render-only]` | Full pipeline: export, parse, replay, parquetize, derive, manifest, commit, catalog, render. |
+| `render [root] [--area X] [--label Y]` | Rebuild HTML and catalog from existing Parquet. |
+| `ab [root] --baseline-label X --compare-label Y` | All reports for one drop pair under `_reports/ab/<pair>/`. |
+| `report [root] <name>` | Build one named report (draws-by-class, trend, instancing, pass-gpu, shader, overdraw, dashboard). |
+| `catalog [root]` | Rebuild `_data/_catalog.parquet` only. |
+| `lint <file>...` | Check HTML or markdown against the banlist. |
+| `check` | Print resolved tool paths; non-zero when a tool is missing. |
+| `serve [root] [--port 8000] [--bind 127.0.0.1]` | Static preview via the stdlib HTTP server. |
+| `smoke [--data DIR]` | End-to-end check; render-only against the bundled fixture when `--data` is omitted. |
+| `version` | Print `bobframes`, schema, and pyarrow versions. |
+
+`<root>` is positional and defaults to `.`. Flags are long-form only. Exit codes: `0` success,
+`1` pipeline or build failure, `2` usage error, `3` external tool missing, `4` interrupted.
+
+## External tools
+
+The export stage runs `renderdoccmd convert`; the replay stage runs `qrenderdoc --python`. v1 looks
+for both at a baked Arm Performance Studio install path and on `PATH`. A config file and a
+tool-resolver with version globbing arrive in v0.2; until then, install RenderDoc where v1 expects it
+or put the executables on `PATH`. Run `bobframes check` to see what was resolved.
+
+## Output layout
+
+```
+<root>/
+  index.html                          root catalog view
+  <area>/<drop>/                      raw RDC inputs (left untouched)
+  _data/                              pipeline outputs
+    _catalog.parquet (+ .csv, .json)
+    _global_entities.parquet (+ .csv)
+    _query_examples.md
+    <area>/<drop>/                    per-drop data (29 Parquet tables)
+      *.parquet (+ matching .csv)
+      _manifest.json, _resource_labels.json
+      shader_src/*.glsl, jsonl sidecars
+      done.marker
+  _reports/                           rendered HTML
+    *.html (dashboard + reports)
+    ab/<pair>/*.html
+    drill/<area>/<drop>/index.html    per-drop browser
+    _cache/
+```
+
+The catalog stores each drop's path relative to `<root>` for portability.
+
+## Migrating from `_analysis`
+
+v1 is a hard rename of the older project-embedded `_analysis` package, with no compatibility shim:
+`python -m _analysis.*` stops working once `bobframes` is installed. Map old invocations to new ones:
+
+| Old (`_analysis`) | New (`bobframes`) |
+|---|---|
+| `python -m _analysis.run --root . --area X --label Y` | `bobframes ingest . --area X --label Y` |
+| `python -m _analysis.reports.ab --root . --baseline-label X --compare-label Y` | `bobframes ab . --baseline-label X --compare-label Y` |
+| `python -m _analysis.lint <file>` | `bobframes lint <file>` |
+| `python -m _analysis.tests.smoke` | `bobframes smoke` |
+
+## Troubleshooting
+
+| Symptom | Resolution |
+|---|---|
+| `renderdoccmd not found` (exit 3) | Install RenderDoc or Arm Performance Studio, or put the executable on `PATH`; confirm with `bobframes check`. |
+| `qrenderdoc` replay hangs | v1 kills the replay process tree on timeout and records `capture_status='replay_failed'` for that capture; the rest of the drop still completes. Re-run with `--force` to retry. |
+| Lint failure during render | The emitted HTML contains a banned token. Run `bobframes lint <file>` to see the line and label. |
+| `schema mismatch` (exit 1) | A drop's `_manifest.json` schema version differs from the installed schema. Rebuild it with `bobframes ingest --force` (the v1 schema-migration path; see G-3). |
+| Permission denied on `_data` | Close any viewer holding a Parquet open, then re-run; writes are staged and renamed atomically. |
+
+## Advanced
+
+- A/B reports: `bobframes ab . --baseline-label OLD --compare-label NEW` builds a side-by-side set.
+- Programmatic use: import `bobframes.schemas`, `bobframes.discovery`, and `bobframes.paths` to drive
+  table lookups, drop discovery, and path resolution from your own scripts.
+- `bobframes/probes/whatif.py` is a manual qrenderdoc-side probe and is not wired as a CLI command.
+- A TOML config file, an externalized draw classifier, and design-token theming are planned for v0.2.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

bobframes-0.1.0/README.md

@@ -0,0 +1,114 @@
+# BobFrames
+
+RenderDoc capture pipeline: ingest, analyze, render. Point it at a folder of `.rdc` captures and it
+produces `_data/` (Parquet tables) plus `_reports/` (static HTML you can browse). Windows-only in v1.
+
+## Requirements
+
+- Windows 10 or later (the replay stage drives `qrenderdoc`, which is Windows-only in v1).
+- Python 3.10 - 3.13.
+- RenderDoc 1.x, or Arm Performance Studio, providing `renderdoccmd` and `qrenderdoc` on disk.
+
+## Install
+
+```
+pipx install bobframes
+bobframes check
+```
+
+`bobframes check` prints the resolved paths for `renderdoccmd` and `qrenderdoc` and exits non-zero if
+either is missing, so you can confirm the toolchain before a long ingest.
+
+## Quickstart
+
+```
+cd path\to\captures      # a folder of <Area>\<YYYY-MM-DD[_label]>\*.rdc
+bobframes ingest .       # export, parse, replay, parquetize, derive, render
+bobframes serve .        # open a local static preview of the reports
+```
+
+`ingest` writes Parquet under `_data/` and HTML under `_reports/`. Re-run `bobframes render .` any
+time to rebuild the HTML from existing Parquet without re-replaying captures.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `ingest [root] [--area X] [--label Y] [--capture N] [--force] [--pixel-grid 4] [--render-only]` | Full pipeline: export, parse, replay, parquetize, derive, manifest, commit, catalog, render. |
+| `render [root] [--area X] [--label Y]` | Rebuild HTML and catalog from existing Parquet. |
+| `ab [root] --baseline-label X --compare-label Y` | All reports for one drop pair under `_reports/ab/<pair>/`. |
+| `report [root] <name>` | Build one named report (draws-by-class, trend, instancing, pass-gpu, shader, overdraw, dashboard). |
+| `catalog [root]` | Rebuild `_data/_catalog.parquet` only. |
+| `lint <file>...` | Check HTML or markdown against the banlist. |
+| `check` | Print resolved tool paths; non-zero when a tool is missing. |
+| `serve [root] [--port 8000] [--bind 127.0.0.1]` | Static preview via the stdlib HTTP server. |
+| `smoke [--data DIR]` | End-to-end check; render-only against the bundled fixture when `--data` is omitted. |
+| `version` | Print `bobframes`, schema, and pyarrow versions. |
+
+`<root>` is positional and defaults to `.`. Flags are long-form only. Exit codes: `0` success,
+`1` pipeline or build failure, `2` usage error, `3` external tool missing, `4` interrupted.
+
+## External tools
+
+The export stage runs `renderdoccmd convert`; the replay stage runs `qrenderdoc --python`. v1 looks
+for both at a baked Arm Performance Studio install path and on `PATH`. A config file and a
+tool-resolver with version globbing arrive in v0.2; until then, install RenderDoc where v1 expects it
+or put the executables on `PATH`. Run `bobframes check` to see what was resolved.
+
+## Output layout
+
+```
+<root>/
+  index.html                          root catalog view
+  <area>/<drop>/                      raw RDC inputs (left untouched)
+  _data/                              pipeline outputs
+    _catalog.parquet (+ .csv, .json)
+    _global_entities.parquet (+ .csv)
+    _query_examples.md
+    <area>/<drop>/                    per-drop data (29 Parquet tables)
+      *.parquet (+ matching .csv)
+      _manifest.json, _resource_labels.json
+      shader_src/*.glsl, jsonl sidecars
+      done.marker
+  _reports/                           rendered HTML
+    *.html (dashboard + reports)
+    ab/<pair>/*.html
+    drill/<area>/<drop>/index.html    per-drop browser
+    _cache/
+```
+
+The catalog stores each drop's path relative to `<root>` for portability.
+
+## Migrating from `_analysis`
+
+v1 is a hard rename of the older project-embedded `_analysis` package, with no compatibility shim:
+`python -m _analysis.*` stops working once `bobframes` is installed. Map old invocations to new ones:
+
+| Old (`_analysis`) | New (`bobframes`) |
+|---|---|
+| `python -m _analysis.run --root . --area X --label Y` | `bobframes ingest . --area X --label Y` |
+| `python -m _analysis.reports.ab --root . --baseline-label X --compare-label Y` | `bobframes ab . --baseline-label X --compare-label Y` |
+| `python -m _analysis.lint <file>` | `bobframes lint <file>` |
+| `python -m _analysis.tests.smoke` | `bobframes smoke` |
+
+## Troubleshooting
+
+| Symptom | Resolution |
+|---|---|
+| `renderdoccmd not found` (exit 3) | Install RenderDoc or Arm Performance Studio, or put the executable on `PATH`; confirm with `bobframes check`. |
+| `qrenderdoc` replay hangs | v1 kills the replay process tree on timeout and records `capture_status='replay_failed'` for that capture; the rest of the drop still completes. Re-run with `--force` to retry. |
+| Lint failure during render | The emitted HTML contains a banned token. Run `bobframes lint <file>` to see the line and label. |
+| `schema mismatch` (exit 1) | A drop's `_manifest.json` schema version differs from the installed schema. Rebuild it with `bobframes ingest --force` (the v1 schema-migration path; see G-3). |
+| Permission denied on `_data` | Close any viewer holding a Parquet open, then re-run; writes are staged and renamed atomically. |
+
+## Advanced
+
+- A/B reports: `bobframes ab . --baseline-label OLD --compare-label NEW` builds a side-by-side set.
+- Programmatic use: import `bobframes.schemas`, `bobframes.discovery`, and `bobframes.paths` to drive
+  table lookups, drop discovery, and path resolution from your own scripts.
+- `bobframes/probes/whatif.py` is a manual qrenderdoc-side probe and is not wired as a CLI command.
+- A TOML config file, an externalized draw classifier, and design-token theming are planned for v0.2.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

bobframes-0.1.0/bobframes/__init__.py

@@ -0,0 +1,3 @@
+from ._version import __version__
+
+__all__ = ["__version__"]

bobframes-0.1.0/bobframes/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

bobframes-0.1.0/bobframes/catalog.py

@@ -0,0 +1,154 @@
+"""Build <root>/_data/_catalog.parquet and _catalog.json.
+
+One row per (area, drop_date, drop_label, capture). Per-capture row counts
+are computed by reading each drop's parquets and grouping by the `capture`
+column — that way the catalog reflects what actually landed for each
+capture, not just drop-level totals.
+
+Also tracks schema version, build timestamp, replay status, and the relative
+path to the drop's data dir (`_data/<area>/<drop>`). Path is RELATIVE for
+portability across machines.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import os
+from collections import defaultdict
+
+import pyarrow as pa
+import pyarrow.csv as pacsv
+import pyarrow.parquet as papq
+
+from . import paths as _paths
+
+
+_CATALOG_TABLE_KEYS = [
+    'draws', 'events', 'shaders', 'textures',
+    'render_targets', 'buffers', 'programs',
+    'samplers', 'fbos', 'state_change_events',
+    'counters_per_event', 'descriptor_access',
+    'passes', 'frame_totals',
+    'clears', 'dispatches', 'rt_event_timeline',
+    'vertex_inputs', 'resource_creation',
+    'draw_bindings', 'program_transitions',
+    'pixel_history', 'vbo_samples', 'ibo_samples',
+    'post_vs_samples', 'texture_samples', 'indirect_args',
+    'pass_class_breakdown', 'texture_usage',
+]
+
+
+def _find_manifests(root: str) -> list[tuple[str, str, dict]]:
+    """Walk _data/<area>/<drop>/_manifest.json. Returns [(data_dir, rel_path, manifest)]."""
+    out = []
+    data_root = _paths.data_root(root)
+    if not os.path.isdir(data_root):
+        return out
+    for area_entry in sorted(os.listdir(data_root)):
+        if area_entry.startswith(('_', '.')):
+            continue
+        area_dir = os.path.join(data_root, area_entry)
+        if not os.path.isdir(area_dir):
+            continue
+        for drop_entry in sorted(os.listdir(area_dir)):
+            drop_dir = os.path.join(area_dir, drop_entry)
+            if not os.path.isdir(drop_dir):
+                continue
+            mf = os.path.join(drop_dir, '_manifest.json')
+            if not os.path.exists(mf):
+                continue
+            try:
+                with open(mf, 'r', encoding='utf-8') as f:
+                    m = json.load(f)
+            except Exception:
+                continue
+            rel = _paths.drop_dir_rel(area_entry, drop_entry)
+            out.append((drop_dir, rel, m))
+    return out
+
+
+def _per_capture_row_counts(data_dir: str, captures: list[str]) -> dict[str, dict[str, int]]:
+    """Walk all parquets in data_dir; return {capture: {table: row_count}}."""
+    result: dict[str, dict[str, int]] = {c: defaultdict(int) for c in captures}
+    for table in _CATALOG_TABLE_KEYS:
+        pq = os.path.join(data_dir, f'{table}.parquet')
+        if not os.path.exists(pq):
+            continue
+        try:
+            t = papq.read_table(pq, columns=['capture'])
+            caps = t.column('capture').to_pylist()
+        except Exception:
+            continue
+        for c in caps:
+            if c in result:
+                result[c][table] += 1
+    return {c: dict(d) for c, d in result.items()}
+
+
+def _capture_rows(data_dir: str, rel_path: str, manifest: dict) -> list[dict]:
+    captures = manifest.get('captures') or manifest.get('stems') or []
+    cap_status = manifest.get('capture_status') or manifest.get('stem_status') or {}
+
+    per_cap = _per_capture_row_counts(data_dir, captures) if captures else {}
+
+    rows: list[dict] = []
+    for cap in captures:
+        counts = per_cap.get(cap, {})
+        rows.append({
+            'area': manifest['area'],
+            'drop_date': manifest['drop_date'],
+            'drop_label': manifest.get('drop_label', '') or '',
+            'capture': cap,
+            'schema_version': int(manifest.get('schema_version', 0)),
+            'build_timestamp': manifest.get('build_timestamp', ''),
+            'replay_status': cap_status.get(cap, 'unknown'),
+            **{f'row_count_{k}': int(counts.get(k, 0)) for k in _CATALOG_TABLE_KEYS},
+            'analysis_out_path': rel_path,
+        })
+    return rows
+
+
+def build_catalog(root: str) -> dict:
+    manifests = _find_manifests(root)
+    all_rows: list[dict] = []
+    for data_dir, rel_path, m in manifests:
+        all_rows.extend(_capture_rows(data_dir, rel_path, m))
+
+    cols = [
+        'area', 'drop_date', 'drop_label', 'capture',
+        'schema_version', 'build_timestamp', 'replay_status',
+    ] + [f'row_count_{k}' for k in _CATALOG_TABLE_KEYS] + ['analysis_out_path']
+
+    arrays: dict[str, pa.Array] = {}
+    for c in cols:
+        vs = [r.get(c, '' if not c.startswith('row_count_') and c != 'schema_version' else 0)
+              for r in all_rows]
+        if c.startswith('row_count_') or c == 'schema_version':
+            arrays[c] = pa.array(vs, type=pa.int64())
+        else:
+            arrays[c] = pa.array([str(v) for v in vs], type=pa.string())
+    table = pa.table(arrays)
+
+    os.makedirs(_paths.data_root(root), exist_ok=True)
+    papq.write_table(table, _paths.catalog_parquet(root), compression='snappy')
+    pacsv.write_csv(table, _paths.catalog_csv(root))
+
+    summary = {
+        'schema_version': max((r['schema_version'] for r in all_rows), default=0),
+        'build_timestamp': _dt.datetime.now(_dt.timezone.utc).replace(microsecond=0).isoformat(),
+        'drop_count': len({(r['area'], r['drop_date'], r['drop_label']) for r in all_rows}),
+        'capture_count': len(all_rows),
+        'areas': sorted({r['area'] for r in all_rows}),
+    }
+    with open(_paths.catalog_json(root), 'w', encoding='utf-8') as f:
+        json.dump(summary, f, indent=2)
+
+    return summary
+
+
+if __name__ == '__main__':
+    import sys
+    root = sys.argv[1] if len(sys.argv) > 1 else '.'
+    s = build_catalog(root)
+    print(json.dumps(s, indent=2))