nexu-io/open-design · error · SystemExit

job {job_id} decoded output does not match its recorded sour

Error message

job {job_id} decoded output does not match its recorded source image; do not rewrite decoded visual outputs locally

What it means

The decoded output's sha256 differs from the source's recorded hash. Decoded outputs must be byte-identical to their source image, so this fires when someone re-decoded, re-exported, or edited decoded/<state>.png locally instead of using the canonical decode path.

Source

Thrown at skills/hatch-pet/scripts/finalize_pet_run.py:75


def validate_hash(job: dict[str, object], *, source: Path, output: Path, job_id: str) -> None:
    expected_hash = job.get("source_sha256")
    if not isinstance(expected_hash, str) or not expected_hash:
        raise SystemExit(
            f"job {job_id} is missing source_sha256; ingest visual outputs with "
            "record_imagegen_result.py instead of editing imagegen-jobs.json"
        )
    if not source.is_file():
        raise SystemExit(f"job {job_id} source image no longer exists: {source}")
    if not output.is_file():
        raise SystemExit(f"job {job_id} decoded output is missing: {output}")
    source_hash = file_sha256(source)
    output_hash = file_sha256(output)
    if source_hash != expected_hash:
        raise SystemExit(f"job {job_id} source image hash does not match imagegen-jobs.json")
    if output_hash != expected_hash:
        raise SystemExit(
            f"job {job_id} decoded output does not match its recorded source image; "
            "do not rewrite decoded visual outputs locally"
        )


def validate_mirror_hash(job: dict[str, object], *, source: Path, output: Path, job_id: str) -> None:
    if job_id != "running-left":
        raise SystemExit(f"job {job_id} may not use deterministic mirror provenance")
    if job.get("derived_from") != "running-right":
        raise SystemExit("running-left mirror job must derive from running-right")
    decision = job.get("mirror_decision")
    if not isinstance(decision, dict) or decision.get("approved") is not True:
        raise SystemExit(
            "running-left mirror job is missing an approved mirror_decision; "
            "use derive_running_left_from_running_right.py after visual review"
        )

    expected_source_hash = job.get("source_sha256")

View on GitHub (pinned to 5be4028344)

Solutions

Regenerate the decoded output via the canonical decode/ingest (record_imagegen_result.py) from the original source.
Never edit decoded visual outputs by hand — they must equal the source bytes.
Re-run finalize_pet_run.py.

Defensive patterns

Strategy: validation

Validate before calling

import hashlib, json
from pathlib import Path

def sha256(p: Path) -> str:
    h = hashlib.sha256()
    with p.open("rb") as f:
        for chunk in iter(lambda: f.read(1 << 20), b""):
            h.update(chunk)
    return h.hexdigest()

run_dir = Path("<run_dir>")
manifest = json.loads((run_dir / "imagegen-jobs.json").read_text())
for job in manifest["jobs"]:
    if job.get("status") != "complete":
        continue
    out = run_dir / job["output_path"] if not Path(job["output_path"]).is_absolute() else Path(job["output_path"])
    assert sha256(out) == job["source_sha256"], f"decoded output drift for {job.get('id')}; regenerate via record_imagegen_result.py"

Prevention

Treat decoded outputs as read-only; never open and re-save them.
Only the canonical decode path (record_imagegen_result.py) may write decoded/*.png.
If a sync/backup tool re-encodes images, exclude decoded/ from it.

When it happens

Trigger: Manually editing decoded/<state>.png in an image editor; re-exporting through a tool that re-encodes or re-compresses; a decode step that is not byte-preserving.

Common situations: Opening the decoded PNG to tweak it and saving; running a non-canonical decoder that rewrites PNGs lossily; a sync tool that re-encodes images.

Related errors

AI-assisted analysis of nexu-io/open-design@5be4028344 (2026-08-12). Data as JSON: /api/errors/12021b04c5ff8c05. Report an issue: GitHub.