Fail closed when wizard freshness sees corrupt timing.json

The asset graph treated garbage timing.json as a missing timestamps
entry. Reuse load_bundle_timing so list/assets APIs return 500 instead
of a fake "run timestamps" gap.

Co-authored-by: jmjava <jmjava@gmail.com>

Author: cursoragent

milestones/README.md

@@ -5,11 +5,13 @@ repositories that install `docgen` and maintain their own demo bundle. The
 library no longer ships an in-repo dogfood; consumers are the integration test
 of record.
 
-**Active:** **[yaml-generate-mappings.md](yaml-generate-mappings.md)** —
-`yaml-generate` merge/discover must not replace a list/scalar `visual_map` or
-narration/manim block with `{}`.
+**Active:** **[asset-graph-timing.md](asset-graph-timing.md)** — wizard
+freshness must not treat corrupt `timing.json` as a missing timestamps entry.
 
 **Shipped:**
+- **[yaml-generate-mappings.md](yaml-generate-mappings.md)** — `yaml-generate`
+  merge/discover must not replace a list/scalar `visual_map` or narration/manim
+  block with `{}` (#91).
 - **[context-path-lists.md](context-path-lists.md)** — `pages.segments` and
   narration/manim context path lists must be typed (#90).
 - **[timing-json-parse.md](timing-json-parse.md)** — corrupt `timing.json`

milestones/asset-graph-timing.md

@@ -0,0 +1,40 @@
+# Milestone: wizard freshness must not treat corrupt `timing.json` as missing
+
+**Status:** Active  
+**PR:** pending  
+**Depends on:** `milestones/timing-json-parse.md` (PR #89),
+`milestones/wizard-narration-paths.md` (PR #81)
+
+## Problem
+
+Compile, validate, scene-asset preflight, and wizard **timestamps write** already
+fail closed on garbage `timing.json` (`load_bundle_timing` → `TimestampError`).
+
+The wizard **asset freshness** graph still caught `JSONDecodeError` / a list root
+and returned “no timing.json entry — run timestamps”. Maintainers saw a missing
+step instead of a corrupt file, and `/api/segments` returned 200.
+
+## Goal
+
+Reuse `load_bundle_timing` in the freshness graph. Missing file stays “no entry”.
+Corrupt JSON / non-object root raises; wizard list/assets endpoints return 500
+and do not rewrite the file.
+
+## Done when
+
+- [x] `_timing_entry_exists` uses `load_bundle_timing` (no silent `False` on
+      garbage JSON).
+- [x] `GET /api/segments` and `GET /api/segments/<id>/assets` map
+      `TimestampError` to HTTP 500 with the parse message.
+- [x] Tests for corrupt JSON and a list root.
+- [ ] `ruff check src/ tests/`
+- [ ] `pytest tests/`
+- [ ] `docgen benchmark` (no clock change)
+
+## Out of scope
+
+- Missing `timing.json` still shows timestamps as missing.
+- CLI `timestamps extract_all` still rewrites the whole file for `segments.all`
+  (recovery path; does not merge extra stems).
+- Wizard `.docgen-state.json` corrupt still resets to empty (UI session, not
+  pipeline timing).

milestones/yaml-generate-mappings.md

@@ -1,7 +1,7 @@
 # Milestone: yaml-generate must not wipe non-mapping blocks
 
-**Status:** Active  
-**PR:** pending  
+**Status:** Shipped  
+**PR:** #91  
 **Depends on:** `milestones/context-path-lists.md` (PR #90),
 `milestones/config-mapping-keys.md` (PR #83)
 

src/docgen/asset_graph.py

@@ -8,7 +8,6 @@
 
 from __future__ import annotations
 
-import json
 from dataclasses import asdict, dataclass
 from pathlib import Path
 from typing import Any, TYPE_CHECKING
@@ -120,15 +119,15 @@ def _find_asset(directory: Path, seg_name: str, seg_id: str, ext: str) -> Path |
 
 
 def _timing_entry_exists(cfg: "Config", seg_name: str, audio: Path | None) -> bool:
-    timing_path = cfg.animations_dir / "timing.json"
-    if not timing_path.is_file():
-        return False
-    try:
-        data = json.loads(timing_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return False
-    if not isinstance(data, dict):
-        return False
+    """True when ``timing.json`` has a stem for this segment.
+
+    A missing file is ``False`` (timestamps not run yet). Corrupt JSON or a
+    non-object root raises :class:`~docgen.timestamps.TimestampError` so the
+    wizard cannot treat garbage as “no entry”.
+    """
+    from docgen.timestamps import load_bundle_timing
+
+    data = load_bundle_timing(cfg)
     if seg_name in data:
         return True
     if audio is not None and audio.stem in data:

src/docgen/wizard.py

@@ -685,8 +685,12 @@ def api_segments():
                     merged_narration_from_source_settings(cfg, seg_id).context_paths
                 )
             from docgen.asset_graph import segment_asset_report
+            from docgen.timestamps import TimestampError
 
-            assets = segment_asset_report(cfg, seg_id)
+            try:
+                assets = segment_asset_report(cfg, seg_id)
+            except TimestampError as exc:
+                return jsonify({"error": str(exc)}), 500
             result.append({
                 "id": seg_id,
                 "name": seg_name,
@@ -711,8 +715,12 @@ def api_segment_assets(segment_id: str):
         if not cfg:
             return jsonify({"error": "no config"}), 400
         from docgen.asset_graph import segment_asset_report
+        from docgen.timestamps import TimestampError
 
-        return jsonify(segment_asset_report(cfg, segment_id))
+        try:
+            return jsonify(segment_asset_report(cfg, segment_id))
+        except TimestampError as exc:
+            return jsonify({"error": str(exc)}), 500
 
     @app.route("/api/segments/<segment_id>/focus")
     def api_get_focus(segment_id: str):

tests/test_asset_graph.py

@@ -133,6 +133,48 @@ def test_api_segments_includes_assets(tmp_path: Path) -> None:
     assert assets.get_json()["segment_id"] == "01"
 
 
+def test_segment_statuses_corrupt_timing_json_raises(tmp_path: Path) -> None:
+    from docgen.timestamps import TimestampError
+
+    cfg = _bundle(tmp_path)
+    (cfg.audio_dir / "01-demo.mp3").write_bytes(b"fake")
+    (cfg.animations_dir / "timing.json").write_text("{not-json", encoding="utf-8")
+    with pytest.raises(TimestampError, match="not valid JSON"):
+        segment_step_statuses(cfg, "01")
+
+
+def test_segment_statuses_non_object_timing_json_raises(tmp_path: Path) -> None:
+    from docgen.timestamps import TimestampError
+
+    cfg = _bundle(tmp_path)
+    (cfg.animations_dir / "timing.json").write_text("[1, 2]", encoding="utf-8")
+    with pytest.raises(TimestampError, match="JSON object"):
+        segment_step_statuses(cfg, "01")
+
+
+def test_api_segments_rejects_corrupt_timing_json(tmp_path: Path) -> None:
+    cfg = _bundle(tmp_path)
+    (cfg.animations_dir / "timing.json").write_text("{not-json", encoding="utf-8")
+    app = create_app(cfg)
+    client = app.test_client()
+    res = client.get("/api/segments")
+    assert res.status_code == 500
+    err = res.get_json()["error"]
+    assert "not valid JSON" in err
+
+
+def test_api_segment_assets_rejects_corrupt_timing_json(tmp_path: Path) -> None:
+    cfg = _bundle(tmp_path)
+    (cfg.animations_dir / "timing.json").write_text("{not-json", encoding="utf-8")
+    app = create_app(cfg)
+    client = app.test_client()
+    res = client.get("/api/segments/01/assets")
+    assert res.status_code == 500
+    assert "not valid JSON" in res.get_json()["error"]
+    assert (cfg.animations_dir / "timing.json").read_text(encoding="utf-8") == "{not-json"
+
+
+
 def test_api_run_from_cascades_mocked(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
     cfg = _bundle(tmp_path)
     app = create_app(cfg)