bobframes 0.1.0__py3-none-any.whl

bobframes/paths.py

@@ -0,0 +1,111 @@
+"""Single source of truth for output paths.
+
+Layout (Option A — outputs separated from RDC inputs):
+
+  <root>/
+    index.html                          # root catalog VIEW
+    <area>/<drop>/                      # raw RDC inputs (untouched)
+    _data/                              # pipeline outputs
+      _catalog.parquet (+.csv, .json)
+      _global_entities.parquet (+.csv)
+      _query_examples.md
+      <area>/<drop>/                    # per-drop data
+        *.parquet (29 tables)
+        _manifest.json, _resource_labels.json
+        shader_src/*.glsl, histogram/, jsonl sidecars
+        done.marker
+    _reports/                           # rendered HTML
+      *.html (dashboard + 6 reports)
+      ab/<pair>/*.html
+      drill/<area>/<drop>/index.html    # per-drop browser
+      _cache/
+
+Catalog `analysis_out_path` column stores RELATIVE path (e.g. `_data/Police station/2026-05-27_r110565`)
+for portability. Reports resolve via resolve_drop_dir(root, analysis_out_path).
+"""
+
+from __future__ import annotations
+
+import os
+
+
+def data_root(root: str) -> str:
+    return os.path.join(root, '_data')
+
+
+def drop_data_dir(root: str, area: str, drop_label_dated: str) -> str:
+    """<root>/_data/<area>/<drop>/"""
+    return os.path.join(data_root(root), area, drop_label_dated)
+
+
+def drop_data_dir_tmp(root: str, area: str, drop_label_dated: str) -> str:
+    """Staging dir for atomic commit. Renamed to drop_data_dir on success."""
+    return drop_data_dir(root, area, drop_label_dated) + '.tmp'
+
+
+def drop_drill_dir(root: str, area: str, drop_label_dated: str) -> str:
+    """<root>/_reports/drill/<area>/<drop>/  (per-drop browser HTML)"""
+    return os.path.join(root, '_reports', 'drill', area, drop_label_dated)
+
+
+def reports_dir(root: str) -> str:
+    return os.path.join(root, '_reports')
+
+
+def reports_cache_dir(root: str) -> str:
+    return os.path.join(reports_dir(root), '_cache')
+
+
+def catalog_parquet(root: str) -> str:
+    return os.path.join(data_root(root), '_catalog.parquet')
+
+
+def catalog_csv(root: str) -> str:
+    return os.path.join(data_root(root), '_catalog.csv')
+
+
+def catalog_json(root: str) -> str:
+    return os.path.join(data_root(root), '_catalog.json')
+
+
+def global_entities_parquet(root: str) -> str:
+    return os.path.join(data_root(root), '_global_entities.parquet')
+
+
+def global_entities_csv(root: str) -> str:
+    return os.path.join(data_root(root), '_global_entities.csv')
+
+
+def query_examples_md(root: str) -> str:
+    return os.path.join(data_root(root), '_query_examples.md')
+
+
+def root_index_html(root: str) -> str:
+    return os.path.join(root, 'index.html')
+
+
+def drop_dir_rel(area: str, drop_label_dated: str) -> str:
+    """Relative path stored in catalog.analysis_out_path column.
+    Combine with root via resolve_drop_dir() at read time."""
+    return os.path.join('_data', area, drop_label_dated).replace('\\', '/')
+
+
+def resolve_drop_dir(root: str, analysis_out_path: str) -> str:
+    """Convert catalog's stored path to an absolute drop data dir.
+    Tolerates legacy absolute paths for back-compat during migration."""
+    if not analysis_out_path:
+        return ''
+    if os.path.isabs(analysis_out_path):
+        return analysis_out_path
+    return os.path.join(root, analysis_out_path)
+
+
+def drop_dir_to_drill_dir(drop_dir: str) -> str:
+    """Given absolute <root>/_data/<area>/<drop>, return <root>/_reports/drill/<area>/<drop>.
+    Used by report drill-link helpers."""
+    parts = os.path.normpath(drop_dir).split(os.sep)
+    try:
+        i = parts.index('_data')
+    except ValueError:
+        return drop_dir
+    return os.sep.join(parts[:i] + ['_reports', 'drill'] + parts[i + 1:])

bobframes/probes/whatif.py

@@ -0,0 +1,165 @@
+"""WHATIF shader-override probe. NOT WIRED INTO run.py.
+
+Stub holding the BuildTargetShader + ReplaceResource pattern from
+Appendix A.10 for ad-hoc use. Run separately when a human has identified
+shader IDs they want to stub-test for GPU-time savings.
+
+Usage (from inside qrenderdoc.exe --python):
+    set RDC_INSIDE_ARGS=<rdc_path>\x1f<shader_id>[\x1f<shader_id>...]\x1f<N_samples>
+    qrenderdoc.exe --python probes/whatif.py
+
+Writes results to <rdc_dir>/_whatif_<shader_id>.csv.
+
+Pattern documentation (verbatim from Appendix A.10):
+
+  - GetResources() returns a list with .resourceId fields; str(rid) is
+    'ResourceId::N'. Parse N to map int handles to ResourceId objects.
+  - BuildTargetShader returns a tuple of (ResourceId, str) OR (str, ResourceId)
+    depending on RD version. Find the ResourceId via isinstance walk.
+  - ReplaceResource requires both arguments to be real ResourceId objects;
+    rd.ResourceId(int) is rejected.
+  - FetchCounters([rd.GPUCounter.EventGPUDuration]) returns one CounterResult
+    per event with value.d in seconds.
+  - Median 3-5 baseline + 3-5 replaced samples per shader for reliable deltas;
+    single-sample variance is +/- 10%.
+  - Always FreeTargetResource() and RemoveReplacement() after each test.
+
+The actual implementation is left as an exercise for the downstream report
+layer that drives this probe with specific shader IDs and sample counts.
+"""
+
+from __future__ import annotations
+
+import csv
+import os
+import statistics
+import sys
+import time
+
+
+FS_GRAY_STUB = """\
+#version 310 es
+precision mediump float;
+out vec4 out_FragColor;
+void main() { out_FragColor = vec4(0.5, 0.5, 0.5, 1.0); }
+"""
+
+
+def run_whatif_for_shader(ctrl, shader_handle: int, samples: int = 3) -> dict:
+    """Run baseline + replaced timing for one shader. Returns dict of medians."""
+    import renderdoc as rd  # type: ignore
+
+    resources = ctrl.GetResources()
+    handle_to_rid: dict[int, object] = {}
+    for r in resources:
+        s = str(r.resourceId)
+        if '::' in s:
+            try:
+                handle_to_rid[int(s.split('::', 1)[1])] = r.resourceId
+            except Exception:
+                continue
+
+    if shader_handle not in handle_to_rid:
+        raise KeyError(f'shader {shader_handle} not found in capture resources')
+    orig_rid = handle_to_rid[shader_handle]
+
+    def measure_total() -> float:
+        rs = ctrl.FetchCounters([rd.GPUCounter.EventGPUDuration])
+        return float(sum(float(r.value.d) for r in rs))
+
+    baseline_samples = [measure_total() for _ in range(samples)]
+
+    result = ctrl.BuildTargetShader(
+        'main', rd.ShaderEncoding.GLSL,
+        bytes(FS_GRAY_STUB, 'utf-8'),
+        rd.ShaderCompileFlags(),
+        rd.ShaderStage.Pixel,
+    )
+    new_id = None
+    err_str = ''
+    if isinstance(result, tuple) and len(result) >= 2:
+        for x in result:
+            if isinstance(x, rd.ResourceId):
+                new_id = x
+            else:
+                err_str = str(x)
+    if new_id is None or new_id == rd.ResourceId.Null():
+        raise RuntimeError(f'compile failed: {err_str}')
+
+    ctrl.ReplaceResource(orig_rid, new_id)
+    try:
+        replaced_samples = [measure_total() for _ in range(samples)]
+    finally:
+        ctrl.RemoveReplacement(orig_rid)
+        ctrl.FreeTargetResource(new_id)
+
+    bm = statistics.median(baseline_samples)
+    rm = statistics.median(replaced_samples)
+    return {
+        'shader_id': shader_handle,
+        'baseline_median_s': bm,
+        'baseline_samples': baseline_samples,
+        'replaced_median_s': rm,
+        'replaced_samples': replaced_samples,
+        'delta_s_median': bm - rm,
+        'delta_pct_median': (bm - rm) / bm * 100.0 if bm else 0.0,
+    }
+
+
+def main() -> int:
+    env = os.environ.get('RDC_INSIDE_ARGS', '')
+    parts = env.split('\x1f') if env else []
+    if len(parts) < 2:
+        print('usage: set RDC_INSIDE_ARGS=<rdc>\\x1f<shader_id>[\\x1f<shader_id>...][\\x1f<samples>]')
+        os._exit(2)
+
+    rdc_path = parts[0]
+    samples = 3
+    shader_ids = []
+    for p in parts[1:]:
+        try:
+            sh = int(p)
+            if sh < 100:  # treat small ints as samples count
+                samples = sh
+            else:
+                shader_ids.append(sh)
+        except ValueError:
+            continue
+
+    if not shader_ids:
+        print('no shader ids supplied')
+        os._exit(2)
+
+    import renderdoc as rd  # type: ignore
+    cap = rd.OpenCaptureFile()
+    cap.OpenFile(rdc_path, '', None)
+    res = cap.OpenCapture(rd.ReplayOptions(), None)
+    rc, ctrl = (res if isinstance(res, tuple) else (res.result, res.controller))
+    if rc != rd.ResultCode.Succeeded:
+        print(f'open failed: {rc}')
+        os._exit(1)
+
+    out_path = os.path.join(os.path.dirname(rdc_path),
+                            f'_whatif_{os.path.basename(rdc_path).replace(".rdc","")}.csv')
+    fields = ['shader_id', 'baseline_median_s', 'baseline_samples',
+              'replaced_median_s', 'replaced_samples',
+              'delta_s_median', 'delta_pct_median']
+    with open(out_path, 'w', encoding='utf-8', newline='') as f:
+        w = csv.DictWriter(f, fieldnames=fields)
+        w.writeheader()
+        for sh in shader_ids:
+            r = run_whatif_for_shader(ctrl, sh, samples=samples)
+            r['baseline_samples'] = ';'.join(f'{x:.6f}' for x in r['baseline_samples'])
+            r['replaced_samples'] = ';'.join(f'{x:.6f}' for x in r['replaced_samples'])
+            w.writerow(r)
+            print(f'  shader {sh}: baseline={r["baseline_median_s"]*1000:.2f}ms '
+                  f'replaced={r["replaced_median_s"]*1000:.2f}ms '
+                  f'delta={r["delta_s_median"]*1000:.2f}ms ({r["delta_pct_median"]:.1f}%)')
+
+    ctrl.Shutdown(); cap.Shutdown()
+    print(f'wrote {out_path}')
+    os._exit(0)
+
+
+if __name__ == '__main__':
+    main()

bobframes/qrd_harness.py

@@ -0,0 +1,119 @@
+"""Launch qrenderdoc.exe --python <script> with payload args via env.
+
+qrenderdoc swallows positional argv after the script path (treats them as
+captures to open) so we pass arguments via the RDC_INSIDE_ARGS env var,
+joined by \\x1f (unit separator).
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import time
+
+_DEFAULT_QRD = (
+    r'c:/Program Files/Arm/Arm Performance Studio 2026.2'
+    r'/renderdoc_for_arm_gpus/qrenderdoc.exe'
+)
+
+_SEP = '\x1f'
+
+
+def _kill_tree(pid: int) -> None:
+    """Kill a process AND its descendants. qrenderdoc spawns GPU/replay
+    grandchildren that survive a bare child kill and keep file locks held for
+    the next run (R-4, ADR-4); `subprocess` only reaps the direct child. Uses
+    Windows `taskkill /T /F`. Best-effort — never raises."""
+    try:
+        subprocess.run(
+            ['taskkill', '/T', '/F', '/PID', str(pid)],
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=30,
+        )
+    except Exception:
+        pass
+
+
+def find_qrenderdoc() -> str:
+    env = os.environ.get('RENDERDOC_QRENDERDOC', '').strip()
+    if env and os.path.exists(env):
+        return env
+    if os.path.exists(_DEFAULT_QRD):
+        return _DEFAULT_QRD
+    raise FileNotFoundError(
+        'qrenderdoc.exe not found. Set RENDERDOC_QRENDERDOC env var or install '
+        'Arm Performance Studio 2026.2.'
+    )
+
+
+def run(
+    script_path: str,
+    payload_args: list[str],
+    log_path: str | None = None,
+    timeout_s: float = 600.0,
+) -> tuple[int, float]:
+    """Launch qrenderdoc --python script_path with payload via env.
+
+    Returns (returncode, elapsed_seconds). The replay script is responsible
+    for writing its own output files; we only forward the exit code.
+
+    Output is redirected directly to log_path (NOT captured through PIPE) to
+    avoid Windows hang: capture_output=True keeps pipes open until ALL inherited
+    handles close, including any grandchild qrenderdoc helpers that may inherit
+    them; the pipes can stay open indefinitely past the main process exit.
+    """
+    qrd = find_qrenderdoc()
+    env = dict(os.environ)
+    env['RDC_INSIDE_ARGS'] = _SEP.join(payload_args)
+
+    if log_path:
+        os.makedirs(os.path.dirname(log_path), exist_ok=True)
+
+    t0 = time.monotonic()
+    logf = None
+    if log_path:
+        logf = open(log_path, 'a', encoding='utf-8', buffering=1)
+    try:
+        if logf:
+            logf.write(f'\n--- qrd_harness launching {os.path.basename(script_path)} ---\n')
+            logf.flush()
+            stdout = logf
+            stderr = subprocess.STDOUT
+        else:
+            stdout = subprocess.DEVNULL
+            stderr = subprocess.DEVNULL
+
+        # Popen (not subprocess.run) so we hold the pid for a process-tree kill on timeout.
+        proc = subprocess.Popen([qrd, '--python', script_path], env=env,
+                                stdout=stdout, stderr=stderr)
+        try:
+            proc.communicate(timeout=timeout_s)
+            rc = proc.returncode
+            if logf:
+                logf.write(f'\n--- rc={rc}, elapsed={time.monotonic()-t0:.2f}s ---\n')
+        except subprocess.TimeoutExpired:
+            _kill_tree(proc.pid)
+            try:
+                proc.wait(timeout=30)
+            except Exception:
+                pass
+            rc = -1
+            if logf:
+                logf.write(f'\n--- TIMEOUT after {timeout_s}s; killed process tree pid={proc.pid} ---\n')
+    finally:
+        if logf:
+            logf.close()
+    elapsed = time.monotonic() - t0
+    return rc, elapsed
+
+
+def parse_inside_args(argv: list[str]) -> list[str]:
+    """Called from inside qrenderdoc to retrieve payload args.
+
+    qrenderdoc passes script path as argv[0] (approximately) and may swallow
+    later positionals; the canonical source is RDC_INSIDE_ARGS.
+    """
+    env = os.environ.get('RDC_INSIDE_ARGS', '')
+    if env:
+        return env.split(_SEP)
+    return argv[1:] if len(argv) > 1 else []

bobframes/query_examples.py

@@ -0,0 +1,222 @@
+"""Emit <root>/_query_examples.md.
+
+Canonical DuckDB / polars query patterns for Layer 2 reports.
+"""
+
+from __future__ import annotations
+
+import os
+
+
+_CONTENT = r"""# Canonical query patterns
+
+All snippets target DuckDB. Replace `**/` with the root path or a specific
+drop folder when needed. Reports may also use polars / pyarrow on the same
+Parquet files.
+
+## Read the catalog
+
+```sql
+SELECT * FROM read_parquet('_catalog.parquet') ORDER BY drop_date, area, capture;
+```
+
+Each row = one capture. Has `row_count_*` per table, schema_version, build
+timestamp, replay_status, and `analysis_out_path` pointing at the drop folder.
+
+## Total GPU duration per area per drop
+
+```sql
+SELECT area, drop_date, drop_label, sum(total_gpu_duration_s) AS gpu_s
+FROM read_parquet('**/frame_totals.parquet')
+GROUP BY area, drop_date, drop_label
+ORDER BY drop_date, area;
+```
+
+## Top shaders by total draw count, across all drops
+
+```sql
+SELECT stable_key, count(*) AS draw_uses,
+       any_value(shader_type) AS type,
+       any_value(src_len) AS src_len
+FROM read_parquet('**/shaders.parquet') s
+JOIN read_parquet('**/draws.parquet') d
+  ON s.area = d.area
+ AND s.drop_date = d.drop_date
+ AND s.drop_label = d.drop_label
+ AND s.capture = d.capture
+ AND (s.shader_id = d.fs_shader_id OR s.shader_id = d.vs_shader_id)
+WHERE s.stable_key != ''
+GROUP BY stable_key
+ORDER BY draw_uses DESC
+LIMIT 20;
+```
+
+## Use _global_entities for single-key joins
+
+```sql
+-- All draws whose fragment shader matches a given stable_key
+WITH g AS (
+  SELECT area, drop_date, drop_label, capture, local_id
+  FROM read_parquet('_global_entities.parquet')
+  WHERE kind = 'shader' AND stable_key = '390139100b660402...'
+)
+SELECT d.* FROM read_parquet('**/draws.parquet') d
+JOIN g USING (area, drop_date, drop_label, capture)
+WHERE d.fs_shader_id = g.local_id;
+```
+
+## Pass-level GPU time across drops
+
+```sql
+SELECT marker_path_norm, drop_date, sum(gpu_duration_s) AS gpu_s,
+       sum(num_draws) AS draws
+FROM read_parquet('**/passes.parquet')
+WHERE marker_path_norm != ''
+GROUP BY marker_path_norm, drop_date
+ORDER BY marker_path_norm, drop_date;
+```
+
+`marker_path_norm` has the `Frame N/` prefix stripped so passes match across
+captures and drops.
+
+## Draws-by-class per area
+
+```sql
+SELECT area, draw_class, count(*) AS n,
+       sum(num_indices * num_instances) AS pre_vs_verts
+FROM read_parquet('**/draws.parquet')
+GROUP BY area, draw_class
+ORDER BY area, n DESC;
+```
+
+## Find non-instanced repeated draws (potential merge targets)
+
+```sql
+SELECT area, capture, parent_pass_path_norm, fs_shader_id,
+       count(*) AS occurrences
+FROM read_parquet('**/draws.parquet')
+WHERE num_instances <= 1 AND draw_class IN ('opaque', 'prepass')
+GROUP BY area, capture, parent_pass_path_norm, fs_shader_id
+HAVING count(*) >= 4
+ORDER BY occurrences DESC
+LIMIT 50;
+```
+
+## Largest render targets per area
+
+```sql
+SELECT area, format, width, height, count(*) AS rt_count,
+       any_value(label) AS sample_label
+FROM read_parquet('**/render_targets.parquet')
+WHERE width > 0
+GROUP BY area, format, width, height
+ORDER BY width * height DESC
+LIMIT 50;
+```
+
+## Texture inventory across drops (deduped via stable_key)
+
+```sql
+SELECT stable_key, any_value(label) AS label,
+       any_value(format) AS format,
+       any_value(width) AS w, any_value(height) AS h,
+       count(DISTINCT area || drop_date || drop_label || capture) AS in_captures
+FROM read_parquet('**/textures.parquet')
+WHERE stable_key != ''
+GROUP BY stable_key
+ORDER BY in_captures DESC, label
+LIMIT 100;
+```
+
+## Pixel-history rejection summary per RT
+
+```sql
+SELECT rt_id, count(*) AS samples,
+       sum(passed) AS passed,
+       sum(depth_test_failed) AS depth_failed,
+       sum(shader_discarded) AS discarded,
+       sum(scissor_clipped) AS scissored
+FROM read_parquet('**/pixel_history.parquet')
+GROUP BY rt_id
+ORDER BY samples DESC;
+```
+
+## Cross-drop entity stability check
+
+```sql
+-- How many unique shader stable_keys exist across all drops?
+SELECT count(DISTINCT stable_key) FROM read_parquet('_global_entities.parquet')
+WHERE kind = 'shader';
+
+-- Which shaders appear in every drop?
+WITH per_drop AS (
+  SELECT stable_key, drop_date, count(*) AS n
+  FROM read_parquet('_global_entities.parquet')
+  WHERE kind = 'shader'
+  GROUP BY stable_key, drop_date
+)
+SELECT stable_key, count(DISTINCT drop_date) AS in_drops
+FROM per_drop
+GROUP BY stable_key
+HAVING count(DISTINCT drop_date) = (SELECT count(DISTINCT drop_date) FROM per_drop)
+ORDER BY stable_key;
+```
+
+## Per-capture totals from catalog (no joins needed)
+
+```sql
+SELECT area, capture, row_count_draws, row_count_state_change_events,
+       row_count_pixel_history
+FROM read_parquet('_catalog.parquet')
+ORDER BY area, capture;
+```
+
+## Reading shader source on demand
+
+```python
+import json, glob, os
+shader_id = 16844
+# Find captures that have this shader id
+import pyarrow.parquet as pq
+for p in glob.glob('*/2026-05-27_*/_analysis_out/shaders.parquet'):
+    t = pq.read_table(p, columns=['area','capture','shader_id','src_file_path'])
+    df = t.to_pandas()
+    hit = df[df['shader_id'] == shader_id]
+    for _, r in hit.iterrows():
+        src = os.path.join(os.path.dirname(p), r['src_file_path'])
+        with open(src) as f:
+            print(f.read())
+```
+
+## Uniform values per pass
+
+`uniforms_per_pass.jsonl` (per drop) carries one JSON object per pass-first-draw
+with the bound constant-block layouts and raw UBO bytes. Read line-by-line:
+
+```python
+import json
+for p in glob.glob('*/2026-05-27_*/_analysis_out/uniforms_per_pass.jsonl'):
+    with open(p) as f:
+        for line in f:
+            o = json.loads(line)
+            if 'MobileBasePass' in o['marker_path']:
+                # o['constant_blocks'] -> list of {stage, block_name, members, ...}
+                # o['raw_by_binding'][slot] -> {buffer_id, offset, size, raw_hex}
+                ...
+```
+"""
+
+
+def write_query_examples(root: str) -> str:
+    from . import paths as _paths
+    os.makedirs(_paths.data_root(root), exist_ok=True)
+    path = _paths.query_examples_md(root)
+    with open(path, 'w', encoding='utf-8') as f:
+        f.write(_CONTENT)
+    return path
+
+
+if __name__ == '__main__':
+    import sys
+    p = write_query_examples(sys.argv[1] if len(sys.argv) > 1 else '.')
+    print(f'wrote {p}')

bobframes/rdcmd.py

@@ -0,0 +1,72 @@
+"""renderdoccmd wrapper.
+
+Locates renderdoccmd.exe via env or the known Arm Performance Studio path
+and exposes a convert() helper that produces .xml / .zip.xml from .rdc.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import time
+
+_DEFAULT_PATHS = [
+    r'c:/Program Files/Arm/Arm Performance Studio 2026.2/renderdoc_for_arm_gpus/renderdoccmd.exe',
+]
+
+
+def find_renderdoccmd() -> str:
+    env = os.environ.get('RENDERDOCCMD', '').strip()
+    if env and os.path.exists(env):
+        return env
+    for p in _DEFAULT_PATHS:
+        if os.path.exists(p):
+            return p
+    raise FileNotFoundError(
+        'renderdoccmd not found. Set RENDERDOCCMD env var or install '
+        'Arm Performance Studio 2026.2 at the default path.'
+    )
+
+
+def convert(rdc_path: str, out_path: str, fmt: str = 'xml', timeout_s: float = 120.0) -> float:
+    """Convert .rdc to xml or zip.xml. Returns elapsed seconds.
+
+    fmt is 'xml' or 'zip.xml'. Raises RuntimeError on failure.
+    """
+    if fmt not in ('xml', 'zip.xml'):
+        raise ValueError(f'unknown fmt: {fmt!r}')
+    cmd = [
+        find_renderdoccmd(), 'convert',
+        '-f', rdc_path,
+        '-o', out_path,
+        '-i', 'rdc',
+        '-c', fmt,
+    ]
+    t0 = time.monotonic()
+    try:
+        rc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout_s)
+    except subprocess.TimeoutExpired as e:
+        # capture_output swallows stderr on timeout; surface the tail before re-raising (R-8).
+        out = e.stderr or e.output or ''
+        if isinstance(out, bytes):
+            out = out.decode('utf-8', 'replace')
+        print(f'renderdoccmd convert timed out after {timeout_s}s (fmt={fmt}): {out[-400:]}',
+              file=sys.stderr)
+        raise
+    elapsed = time.monotonic() - t0
+    if rc.returncode != 0:
+        tail = (rc.stderr or rc.stdout or '')[-400:]
+        raise RuntimeError(
+            f'renderdoccmd convert failed (rc={rc.returncode}, fmt={fmt}): {tail}'
+        )
+    if not os.path.exists(out_path):
+        raise RuntimeError(f'renderdoccmd convert reported success but {out_path} is missing')
+    return elapsed
+
+
+def needs_export(rdc_path: str, out_path: str) -> bool:
+    """True if out_path is missing or older than rdc_path."""
+    if not os.path.exists(out_path):
+        return True
+    return os.path.getmtime(out_path) < os.path.getmtime(rdc_path)