Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

gen-set: the report is the last-written commit marker; any failed attempt leaves no reusable row

Soohong Kim719b177aeafa
diff --git a/sprite_gen/gen/gen_set.py b/sprite_gen/gen/gen_set.py
index 8e96cdd..3b26437 100644
--- a/sprite_gen/gen/gen_set.py
+++ b/sprite_gen/gen/gen_set.py
@@ -72,6 +72,20 @@ def _stages(request: dict[str, Any], states: list[str]) -> list[list[str]]:
return [stage for stage in (first, second) if stage]
+def _row_image_ok(out: Path) -> str | None:
+ """None when `out` is a complete, decodable image; otherwise why not."""
+ if not out.is_file():
+ return "row image missing"
+ try:
+ from PIL import Image
+
+ with Image.open(out) as im:
+ im.verify()
+ except Exception as exc: # noqa: BLE001 — any decode failure is the same verdict
+ return f"row image unreadable ({exc.__class__.__name__})"
+ return None
+
+
def read_report(report: Path) -> tuple[dict[str, Any] | None, str | None]:
"""Parse a row's gen report. Returns (report, None) or (None, why) — a missing,
unreadable or provider-less report is never treated as a finished row."""
@@ -127,27 +141,33 @@ def run_item(
raise SystemExit(f"layout guide missing: {guide} — run `sprite-gen prepare` first")
if out.is_file() and not force:
prior, why = read_report(report)
- if prior is not None:
+ bad_image = _row_image_ok(out)
+ if prior is not None and bad_image is None:
result["reused"] = True
result["provider"] = prior.get("provider")
result["provider_resolved_from"] = prior.get("provider_resolved_from")
result["ok"] = True
return result
- result["regenerated_because"] = why # the row image exists but its report does not prove it — generate again, say why
+ result["regenerated_because"] = why or bad_image # the files exist but do not prove a finished row — generate again, say why
identity = anchor_mod.identity_ref(run_dir, state, request, quiet=True)
refs = [identity, guide]
result["refs"] = [str(r) for r in refs]
out.parent.mkdir(parents=True, exist_ok=True)
+ # The report is the commit marker of a finished row. Drop the previous one BEFORE the
+ # provider runs: a provider that half-overwrites the image and exits non-zero must not
+ # leave a valid-looking report next to a broken image (validator finding 2026-09-09).
+ report.unlink(missing_ok=True)
rc = gen_runner(prompt_file, out, refs, report, provider=provider, model=model, log=log)
- if rc != 0 or not out.is_file():
- tail = log.read_text(encoding="utf-8", errors="replace").strip().splitlines()[-3:] if log.exists() else []
- raise SystemExit(f"gen exited {rc}; " + (" | ".join(tail) if tail else f"see {log}"))
- gen_report, why = read_report(report)
- if gen_report is None:
- for partial in (out, report):
+ gen_report, why = read_report(report) if rc == 0 else (None, None)
+ bad_image = _row_image_ok(out) if rc == 0 else None
+ if rc != 0 or gen_report is None or bad_image is not None:
+ for partial in (out, report): # no half state: an unproven row is removed so the next run regenerates
if partial.exists():
partial.unlink()
- raise SystemExit(f"gen exited 0 but its {why}; the row and the report were removed so the next run regenerates")
+ if rc != 0:
+ tail = log.read_text(encoding="utf-8", errors="replace").strip().splitlines()[-3:] if log.exists() else []
+ raise SystemExit(f"gen exited {rc}; " + (" | ".join(tail) if tail else f"see {log}") + " — the row and its report were removed")
+ raise SystemExit(f"gen exited 0 but its {why or bad_image}; the row and the report were removed so the next run regenerates")
result["provider"] = gen_report.get("provider")
result["provider_resolved_from"] = gen_report.get("provider_resolved_from")
if gen_report.get("provider_fallback"):
diff --git a/tests/gen/test_gen_set.py b/tests/gen/test_gen_set.py
index e51201c..242ebf8 100644
--- a/tests/gen/test_gen_set.py
+++ b/tests/gen/test_gen_set.py
@@ -176,3 +176,34 @@ def test_gen_set_row_without_a_real_report_is_regenerated_with_a_reason(tmp_path
payload = gen_set.run_set(run_dir=run_dir, states=["walk"], provider="codex", model=None, concurrency=1, force=False, gen_runner=_fake_runner(record=calls))
item = payload["items"][0]
assert len(calls) == 1 and item["ok"] and item.get("reused") is None and item["regenerated_because"] == "report missing"
+
+
+def test_gen_set_failed_force_regeneration_leaves_no_reusable_row(tmp_path: Path) -> None:
+ """Validator finding 2026-09-09 (round 2): valid row → --force run whose provider half-
+ overwrites the image and exits 3 → a plain rerun must regenerate, never reuse the stale
+ report over the broken image."""
+ run_dir = _prepare(tmp_path)
+ ok = gen_set.run_set(run_dir=run_dir, states=["idle"], provider="codex", model=None, concurrency=1, force=False, gen_runner=_fake_runner())
+ assert ok["ok"] == 1
+
+ def half_writer(prompt_file: Path, out: Path, refs: list[Path], report: Path, *, provider, model, log) -> int:
+ out.write_bytes(b"\x89PNG\r\n\x1a\n incomplete image") # truncated overwrite
+ log.write_text("provider died mid-write\n", encoding="utf-8")
+ return 3
+
+ forced = gen_set.run_set(run_dir=run_dir, states=["idle"], provider="codex", model=None, concurrency=1, force=True, gen_runner=half_writer)
+ assert forced["failed"] == ["idle"] and "gen exited 3" in forced["items"][0]["error"]
+ assert not (run_dir / "raw" / "idle.png").exists() and not (run_dir / "reports" / "gen-set" / "idle.json").exists()
+
+ calls: list = []
+ retry = gen_set.run_set(run_dir=run_dir, states=["idle"], provider="codex", model=None, concurrency=1, force=False, gen_runner=_fake_runner(record=calls))
+ assert len(calls) == 1 and retry["ok"] == 1 and retry["items"][0].get("reused") is None
+
+
+def test_gen_set_unreadable_row_image_is_not_reused(tmp_path: Path) -> None:
+ run_dir = _prepare(tmp_path)
+ gen_set.run_set(run_dir=run_dir, states=["idle"], provider="codex", model=None, concurrency=1, force=False, gen_runner=_fake_runner())
+ (run_dir / "raw" / "idle.png").write_bytes(b"\x89PNG\r\n\x1a\n incomplete image") # a valid report next to a broken image
+ calls: list = []
+ again = gen_set.run_set(run_dir=run_dir, states=["idle"], provider="codex", model=None, concurrency=1, force=False, gen_runner=_fake_runner(record=calls))
+ assert len(calls) == 1 and again["items"][0]["regenerated_because"].startswith("row image unreadable")