Skip to content

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

feat(video): restore active-cut damage from exact source and playback evidence

Soohong Kimf5206443ba14
diff --git a/SKILL.md b/SKILL.md
index 5130157..d7cfd93 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -103,6 +103,7 @@ hold the arms still, and check the loop with `handed-check --state walk`.
| Grok video sprites | `video-set` | [video-pipeline](docs/video-pipeline.md) |
| A soft part of a walk loop follows the body (a chest, a belly): an ellipse in the first cell, after `video-cycle-align` | `video-follow` | [video-pipeline](docs/video-pipeline.md#6-follow-through--video-follow) |
| Compare the currently displayed loop with a final candidate, including after follow-through | `video-loop-compare` | [loop-comparison](docs/loop-comparison.md) |
+| Restore post-processing damage in the current cut from its exact source times, preserving normal cells and playback | `video-source-manifest` → `video-loop-repair` → `video-loop-compare` | [source restoration](docs/loop-comparison.md#restoring-the-active-cut-from-source) |
| Video sprites from a clip your agent makes with a connected video MCP (ZCRE, 지크) | `video-canvas`, `video-prompt --no-last-frame`, the agent's own MCP tools (quote, user approval, generate, save the mp4), then `video-frames` and `video-loop` (a walk or run with `--anchor motion-auto`, which holds its size), and for a walk or run cut in two or more directions `video-cycle-align --view …` over their loop directories (a set it stops on a loop that may hold two cycles: look at that loop, count its strides, and pass `--cycles <loop>=<k>`; a loop the report lists under `unnamed_feet` — its view could not tell the feet apart, or only by too small a margin (`low-margin`): look at its first candidate frame, say which own foot lands there, and align again with `--foot <loop>=left|right`). `video-set` is not run on this route, so the set stage it runs by default (`--align-cycles auto`) is yours to run. sprite-gen never calls the MCP. Walk, run and jump only: ZCRE's `grok-imagine-video-1.5` has no end frame, so idle, attack and diagonal walks are refused unless `--unpinned` | [video-pipeline](docs/video-pipeline.md#a-clip-from-a-video-mcp-on-your-agent--zcre) |
| Ordinary image or edit | `gen --provider codex` or `gen --provider grok` (subscription routes) | [gen](docs/gen.md) |
| Image generation with no login available (server, container, SaaS) | `gen --provider openai` — server/SaaS route on `OPENAI_API_KEY`, **billed per call**, never a default or a fallback | [gen](docs/gen.md#subscription-first--openai-is-named-or-it-does-not-run) |
diff --git a/docs/loop-comparison.md b/docs/loop-comparison.md
index aaa98ac..e324443 100644
--- a/docs/loop-comparison.md
+++ b/docs/loop-comparison.md
@@ -30,7 +30,7 @@ and `metric_version: "same-sample-defects-v1"`.
| `baseline`, `candidate` | The actual artifacts, decoded pixels, frame count, cell size, timing, source cut, producer and follow presence |
| `<side>.artifacts.{strip,meta,report}.{sha256,bytes}` | SHA-256 and size of each **original file's bytes**; JSON whitespace is significant |
| `<side>.pixels_sha256` | SHA-256 of the ordered decoded RGBA cell bytes |
-| `measurement_engine.implementation_sha256` | Fingerprint of the video implementation and CLI that performed the measurement |
+| `measurement_engine.implementation_sha256` | Fingerprint of the video, keying, resampling, GIF and CLI code that performed the measurement |
| `axes.<axis>` | `baseline`, `candidate`, `comparable`, `reason`, `status` for that axis |
| `limits` | What the comparison does not establish |
@@ -111,3 +111,137 @@ Common reason codes include `identical-pixels-and-timing`,
See [loop repair](loop-repair.md) for proposal rejection and the interpolation
quality bounds, and [video pipeline](video-pipeline.md) for processing stages.
+
+## Restoring the active cut from source
+
+`video-loop-repair` proposes a separate output for one damaged interior cell.
+It preserves the cut, metadata, normal cells, boundary cells, and actual GIF/WebP
+schedule. No interpolation is called. This operation has its own comparison
+contract: `schema_version: 2`, `metric_version: source-restoration-v1`,
+`scope: processing-defect-restoration`, `operation: restore_active_cut`.
+The v1 comparison above is unchanged.
+
+First retain the actual clip, canvas, keyed PNGs, and extraction report. New
+extractions can use `video-frames --source-manifest source.json --reference
+canvas.png` alongside their normal extraction flags. To inventory an existing
+extraction without extracting it again:
+
+```bash
+sprite-gen video-source-manifest \
+ --clip clip.mp4 --canvas canvas.png --frames-report frames.json \
+ --frames-dir frames/keyed --out source.json
+```
+
+The receipt binds input bytes, ordered keyed PNG bytes, actual video PTS,
+extraction report recipe and measurement implementation/environment. It is an
+inventory of supplied evidence, not a signature or an assertion of a historical
+producer's identity. Preserve the extraction environment log with the manifest.
+Consumers must retain immutable source files. The source sequence and input
+hashes are read and checked again, not trusted from a `verified` flag.
+
+```bash
+sprite-gen video-loop-repair \
+ --baseline-strip B.strip.png --baseline-meta B.strip.json \
+ --baseline-report B.loop.json --baseline-gif B.gif --baseline-webp B.webp \
+ --source-frames-dir frames/keyed --source-manifest source.json \
+ --source-clip clip.mp4 --source-canvas canvas.png --source-frames-report frames.json \
+ --out-dir candidate-1 --name loop --proposal-index 1 --report repair-1.json
+```
+
+`--out-dir` must not exist. Artifacts are built in a sibling staging directory
+and published together. `outputs` maps `strip`, `meta`, `report`, `gif`, `webp`
+to `loop.strip.png`, `loop.strip.json`, `loop.loop.json`, `loop.gif`, `loop.webp`.
+`--name` sets their common stem. The repair report is separate and must not
+replace any input or candidate artifact.
+
+The engine enumerates up to three independent single-cell proposals, ranked by
+source-relative damage. `--proposal-index` is one-based, limited to 1–3. The
+stable `proposal_id` binds baseline file digests, source sequence, policy and
+target. Repeating the same index is the same proposal, not a retry strategy.
+The application owns its deadline, attempted IDs and adoption transaction.
+
+| Repair field | Contract |
+|---|---|
+| `status` | `candidate`, `no_change`, `unknown`, or `exhausted` |
+| `common_failure` | A shared evidence failure; do not try the other proposals |
+| `reasons` | Machine-readable explanation |
+| `proposals_available`, `proposal_limit`, `proposal_index` | Available independent candidates and request budget |
+| `proposal_id`, `target` | Selected identity and zero-based cell; null for a no-op |
+| `baseline_artifacts`, `candidate_artifacts` | Exact five-file byte receipts |
+| `source_artifacts`, `projection` | Source inputs, fixed transform, sample PTS and exact correspondence |
+| `comparison` | Initial measurement of written files; compare again after finalization |
+| `interpolation_calls` | Always zero in this operation |
+
+For a normal input, `no_change` copies all five files byte-for-byte and compares
+as `non_regressing`. If the legacy recipe cannot uniquely explain every
+unmodified cell, the result is shared `unknown` without a candidate. Historical
+repair indices are hints only: a target must have a final and source-relative
+interpolation fault, and its source reference must pass the common policy.
+
+The supported projection is scrub, small-component cleanup, optional integer
+body ramp, one shared integer crop and the standard resampler. New loop reports
+also record hashes before repair. Legacy crops are bounded by the recorded
+scale recipe and canvas, with a search limit of 4096 hypotheses; multiple exact
+matches remain unknown. Frame-specific alignment, different cuts, subsampling,
+size hold, motion anchoring, cycle alignment, or unproven follow warps are not
+accepted. Do not rerun follow on a restoration output.
+
+Compare the final artifacts using the **same** source inputs:
+
+```bash
+sprite-gen video-loop-compare \
+ --baseline-strip B.strip.png --baseline-meta B.strip.json \
+ --baseline-report B.loop.json --baseline-gif B.gif --baseline-webp B.webp \
+ --candidate-strip candidate-1/loop.strip.png --candidate-meta candidate-1/loop.strip.json \
+ --candidate-report candidate-1/loop.loop.json \
+ --candidate-gif candidate-1/loop.gif --candidate-webp candidate-1/loop.webp \
+ --source-frames-dir frames/keyed --source-manifest source.json \
+ --source-clip clip.mp4 --source-canvas canvas.png --source-frames-report frames.json \
+ --repair-evidence repair-1.json --report comparison-1.json
+```
+
+The comparator rebuilds the reference from actual source files and reads all
+five final artifacts. Changed JSON whitespace changes its byte receipt. A
+changed file no longer bound by the repair evidence is an input error. All
+verdicts return exit 0; malformed, missing or changed source/evidence files and
+encoder/decoder failures return nonzero. An unsupported mapping is `unknown`,
+not an execution error disguised as a normal result.
+
+`improved` requires an exact source-time replacement, at least one cleared
+actual fault, unchanged normal cells and no worsening protected axis. The
+common outline/smear thresholds apply to every final frame, including neighbours
+of the restored one. Raw partial coverage is reported; the protected quantity
+is excess over the fixed source reference with common source neighbours.
+Restoring natural antialiasing may increase raw partial coverage. Alpha-weighted
+key-colour excess must not increase. Other colour changes cannot be accepted:
+the changed cell must exactly equal its source projection. Boundary pixels and
+actual playback intervals stay identical. GIF quantization and WebP decoding
+are checked against the strip export mapping, with their actual integer delays
+recorded separately from fractional strip timing.
+
+For an outline-specific UI success message, require `verdict == improved` and
+an `outline` entry in `cleared_faults[].faults`. `axes` contains raw baseline,
+reference and candidate values for outline/smear, source-relative partial
+coverage and key colour. `gait.source_order == preserved` proves source motion
+order only; `gait.absolute == unverified` remains explicit. These measurements
+do not claim to repair mistakes already present in the source drawing.
+
+A candidate-specific unknown or regression may be followed by the next unused
+proposal within budget. Shared unknown stops the request. Upload and activate
+only the final five digests returned by comparison; a file's existence or the
+initial repair report is not authority to replace the active revision.
+
+Every proposal in one request starts from the same immutable baseline. Proposal
+2 does not include proposal 1. After adoption, a subsequent request must supply
+the adopted five files as its new baseline, so its proposal IDs and baseline
+digests change. The candidate loop report records cumulative `restored_cells`;
+those cells join the next bridge's exact normal-cell checks and cannot be
+silently replaced again. Its historical `jump_repair.replaced` remains intact.
+Once all supported damage has been restored, the next request is a byte-exact
+no-op. A client must never apply an old proposal or compare receipt to the new
+baseline revision.
+
+Key-colour protection uses the existing full-spill tint threshold and the key
+hue channels. `axes.key_colour.introduced_excess` sums only positive per-pixel
+increases on the fixed canvas. A reduction elsewhere cannot offset newly
+introduced spill, even when the cell's total tint decreases.
diff --git a/sprite_gen/_modules.py b/sprite_gen/_modules.py
index 62deb66..e0ad04c 100644
--- a/sprite_gen/_modules.py
+++ b/sprite_gen/_modules.py
@@ -29,6 +29,8 @@ MODULE_DOMAIN = {
'align': 'video',
'follow': 'video',
'compare': 'video',
+ 'restoration': 'video',
+ 'source': 'video',
'rife_install': 'video',
'clip_prompt': 'video',
'prepare': 'gen',
diff --git a/sprite_gen/cli.py b/sprite_gen/cli.py
index 365b8f1..830425c 100644
--- a/sprite_gen/cli.py
+++ b/sprite_gen/cli.py
@@ -23,6 +23,8 @@ from sprite_gen.video import clip_prompt as video_prompt
from sprite_gen.video import align as video_align
from sprite_gen.video import follow as video_follow
from sprite_gen.video import compare as video_compare
+from sprite_gen.video import restoration as video_restoration
+from sprite_gen.video import source as video_source
from sprite_gen.video import rife_install
from sprite_gen.effects import recolor, shadow
from sprite_gen.scene import render, inspect_scene
@@ -360,6 +362,16 @@ COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callab
video_compare.add_arguments,
video_compare.run,
),
+ "video-source-manifest": (
+ "Record actual clip, canvas and ordered keyed bytes from an existing extraction for source verification.",
+ video_source.add_arguments,
+ video_source.run,
+ ),
+ "video-loop-repair": (
+ "Restore one damaged cell of the current cut from verified source pixels; preserve timing and normal cells.",
+ video_restoration.add_arguments,
+ video_restoration.run,
+ ),
"video-set": (
"Directions x states end to end (canvas -> video -> frames -> loop), rate-limit aware, one report per item.",
video_batch.add_arguments,
diff --git a/sprite_gen/video/compare.py b/sprite_gen/video/compare.py
index 1a9ce06..567f693 100644
--- a/sprite_gen/video/compare.py
+++ b/sprite_gen/video/compare.py
@@ -264,6 +264,11 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
for side in ("baseline", "candidate"):
for artifact in ("strip", "meta", "report"):
parser.add_argument(f"--{side}-{artifact}", required=True, type=Path)
+ for artifact in ("gif", "webp"):
+ parser.add_argument(f"--{side}-{artifact}", type=Path)
+ from sprite_gen.video import source
+ source.add_inputs(parser, required=False)
+ parser.add_argument("--repair-evidence", type=Path)
parser.add_argument("--report", required=True, type=Path)
@@ -271,9 +276,30 @@ def run(**kwargs: Any) -> int:
output = Path(kwargs["report"])
paths = {s: {k: Path(kwargs[f"{s}_{k}"]) for k in ("strip", "meta", "report")} for s in ("baseline", "candidate")}
try:
- if any(output.resolve() == p.resolve() for row in paths.values() for p in row.values()):
+ from sprite_gen.video import source
+ restoration_mode = any(kwargs.get(k) is not None for k in (*source.INPUTS, "repair_evidence"))
+ protected = [p for row in paths.values() for p in row.values()]
+ if restoration_mode:
+ from sprite_gen.video import restoration
+ inputs = source.input_paths(kwargs)
+ if any(kwargs.get(f"{s}_{k}") is None for s in paths for k in ("gif", "webp")) or not kwargs.get("repair_evidence"):
+ raise ValueError("source comparison requires baseline/candidate GIF, WebP and repair evidence")
+ for side in paths:
+ paths[side].update({k: Path(kwargs[f"{side}_{k}"]) for k in ("gif", "webp")})
+ evidence_path = Path(kwargs["repair_evidence"])
+ protected += [*inputs.values(), evidence_path, *inputs["source_frames_dir"].glob("*.png")]
+ protected += [p for row in paths.values() for p in row.values()]
+ elif any(kwargs.get(f"{s}_{k}") for s in paths for k in ("gif", "webp")):
+ raise ValueError("playback comparison requires source inputs and repair evidence")
+ if any(output.resolve() == p.resolve() for p in protected):
raise ValueError("comparison report cannot overwrite an input artifact")
- payload = compare(Loop.read(**paths["baseline"]), Loop.read(**paths["candidate"]))
+ if restoration_mode:
+ a, ap = restoration.read_loop(paths["baseline"])
+ b, bp = restoration.read_loop(paths["candidate"])
+ payload = restoration.compare(a, b, source.Source.read(**inputs), baseline_playback=ap, candidate_playback=bp,
+ repair_evidence=_json(evidence_path.read_bytes(), "repair evidence"))
+ else:
+ payload = compare(Loop.read(**paths["baseline"]), Loop.read(**paths["candidate"]))
text = json.dumps(payload, indent=2, allow_nan=False) + "\n"
output.parent.mkdir(parents=True, exist_ok=True)
atomic_write_text(output, text)
diff --git a/sprite_gen/video/evidence.py b/sprite_gen/video/evidence.py
index 7f69546..40fef08 100644
--- a/sprite_gen/video/evidence.py
+++ b/sprite_gen/video/evidence.py
@@ -19,8 +19,9 @@ def digest(data: bytes) -> str:
def engine_identity() -> dict[str, str]:
"""Fingerprint the measured video implementation, including an unreleased checkout."""
root = Path(__file__).parent
- files = [*sorted(root.glob("*.py")), root.parent / "cli.py"]
- return {"implementation_sha256": digest(b"".join(p.name.encode() + b"\0" + p.read_bytes() for p in files))}
+ files = [*sorted(root.glob("*.py")), *sorted((root.parent / "frames").glob("*.py")),
+ root.parent / "cli.py", root.parent / "util/resample.py", root.parent / "util/gif_utils.py"]
+ return {"implementation_sha256": digest(b"".join(str(p.relative_to(root.parent)).encode() + b"\0" + p.read_bytes() for p in files))}
def source_identity(files: list[Path], fps: float) -> dict[str, Any]:
diff --git a/sprite_gen/video/frames.py b/sprite_gen/video/frames.py
index f7c0777..cbdc745 100644
--- a/sprite_gen/video/frames.py
+++ b/sprite_gen/video/frames.py
@@ -460,7 +460,16 @@ def _edge_contact_message(contacts: list[dict[str, Any]]) -> str:
return message
-def run_frames(clip: Path, out_dir: Path, *, key: str, allow_edge_contact: bool, report_path: Path | None, spill: str = "small", reference: Path | None = None, allow_subject_edge_contact: bool = False, decontam: str = "off") -> dict[str, Any]:
+def run_frames(clip: Path, out_dir: Path, *, key: str, allow_edge_contact: bool, report_path: Path | None, spill: str = "small", reference: Path | None = None, allow_subject_edge_contact: bool = False, decontam: str = "off", source_manifest: Path | None = None) -> dict[str, Any]:
+ if source_manifest is not None and reference is None:
+ raise SystemExit("video-frames: --source-manifest needs --reference (the source canvas)")
+ if source_manifest is not None:
+ target = (report_path or out_dir / "frames.report.json").expanduser().resolve()
+ receipt = Path(source_manifest).expanduser().resolve()
+ if (receipt in (target, clip.expanduser().resolve(), Path(reference).expanduser().resolve())
+ or receipt.is_relative_to((out_dir / "keyed").expanduser().resolve())
+ or receipt.is_relative_to((out_dir / "raw").expanduser().resolve())):
+ raise SystemExit("video-frames: source manifest cannot overwrite source files or report")
if spill not in SPILL_MODES:
raise SystemExit(f"video-frames: unknown --spill {spill!r}; expected one of {', '.join(SPILL_MODES)}")
if spill == "auto" and reference is None:
@@ -479,7 +488,17 @@ def run_frames(clip: Path, out_dir: Path, *, key: str, allow_edge_contact: bool,
report = key_frames(files, keyed_dir, key=key, check_edges=not allow_edge_contact, spill=decision["mode"], allow_subject=allow_subject_edge_contact, decontam=decontam)
payload = {"kind": "sprite-gen-video-frames-report", "clip": str(clip), "out_dir": str(out_dir), "raw_dir": str(raw_dir), "keyed_dir": str(keyed_dir), "key": key, "spill": decision, **meta, **report}
target = (report_path or (out_dir / "frames.report.json")).expanduser().resolve()
+ if source_manifest is not None:
+ from sprite_gen.video.evidence import engine_identity
+ payload["producer"] = engine_identity()
atomic_write_text(target, json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+ if source_manifest is not None:
+ from sprite_gen.video import source
+ Path(source_manifest).parent.mkdir(parents=True, exist_ok=True)
+ record = source.manifest(clip=clip, canvas=Path(reference), frames_report=target,
+ files=sorted(keyed_dir.glob("*.png")),
+ timestamps=source.timestamps(clip, meta["stream_index"]))
+ atomic_write_text(Path(source_manifest), json.dumps(record, indent=2, allow_nan=False) + "\n")
payload["report"] = str(target)
return payload
@@ -491,6 +510,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
parser.add_argument("--allow-edge-contact", action="store_true", help="accept any opaque pixel at the top/left/right edge (subject and leftover key background alike)")
parser.add_argument("--allow-subject-edge-contact", action="store_true", help="accept the subject touching the top/left/right edge (a `video-canvas --fit tight` clip) but still refuse leftover key background there")
parser.add_argument("--report", type=Path, help="report JSON (default <out-dir>/frames.report.json)")
+ parser.add_argument("--source-manifest", type=Path, help="write exact clip/canvas/keyed-file digests and source timestamps (requires --reference)")
parser.add_argument("--spill", choices=SPILL_MODES, default="small", help="small: correct only small key-tinted clusters (default); full: every key tint in the subject is spill; auto: decide from --reference")
parser.add_argument("--reference", type=Path, help="the still the clip was made from (required by --spill auto)")
parser.add_argument("--decontam", choices=DECONTAM_MODES, default="off", help="off: the matte as is (default); palette: re-explain key-tinted edges with the subject's own colours (one palette per clip, video fit); auto: the same where it applies, reasons recorded where not")
@@ -501,7 +521,7 @@ def run(**kwargs: object) -> int:
allow_edge_contact=bool(kwargs.get("allow_edge_contact")), report_path=kwargs.get("report"), # type: ignore[arg-type]
spill=str(kwargs.get("spill") or "small"), reference=kwargs.get("reference"), # type: ignore[arg-type]
allow_subject_edge_contact=bool(kwargs.get("allow_subject_edge_contact")),
- decontam=str(kwargs.get("decontam") or "off"))
+ decontam=str(kwargs.get("decontam") or "off"), source_manifest=kwargs.get("source_manifest")) # type: ignore[arg-type]
summary = {k: payload[k] for k in ("clip", "keyed_dir", "width", "height", "fps", "frames", "codec", "pix_fmt", "audio_streams", "alpha_zero_pct_min", "alpha_zero_pct_max", "edge_contacts", "edge_policy", "spill", "report")}
print(json.dumps(summary, ensure_ascii=False, indent=2))
return 0
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index 94ac82b..af7cbdd 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -1291,6 +1291,12 @@ def run_loop(
write_loop_report(target, {**report_base, "status": "failed", "error": error, "cycle": cycle})
raise SystemExit(error) from exc
report_base["motion_anchor"] = motion
+ if anchor in ("none", "body"):
+ from sprite_gen.video.source import RECIPE
+ report_base["source_projection"] = {
+ "recipe": RECIPE, "wrap_dx_px": wrap_dx,
+ "before_repair_pixels_sha256": [evidence_mod.digest(f.tobytes()) for f in frames],
+ }
if repair != "off" and prof.gait:
report_base["jump_repair"] = None
try:
diff --git a/sprite_gen/video/playback.py b/sprite_gen/video/playback.py
new file mode 100644
index 0000000..04c9836
--- /dev/null
+++ b/sprite_gen/video/playback.py
@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Read delivered animation bytes and prove the strip-to-playback mapping."""
+
+from __future__ import annotations
+
+import io
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from PIL import Image
+
+from sprite_gen.video import evidence
+from sprite_gen.util.gif_utils import _prepare_transparent_frame
+
+
+def visible_bytes(frame: Image.Image) -> bytes:
+ """GIF has no RGB under transparency; compare its displayed RGBA instead."""
+ out = Image.new("RGBA", frame.size)
+ out.paste(frame, mask=frame.getchannel("A").point(lambda a: 255 if a else 0))
+ return out.tobytes()
+
+
+@dataclass
+class Playback:
+ frames: list[Image.Image]
+ durations: list[int]
+ loop: int | None
+ format: str
+ artifact: dict[str, Any]
+
+ @classmethod
+ def read(cls, path: Path, format: str) -> Playback:
+ blob = path.read_bytes()
+ with Image.open(io.BytesIO(blob)) as im:
+ if im.format != format:
+ raise ValueError(f"playback must be {format}")
+ repeat = im.info.get("loop")
+ frames, durations = [], []
+ for k in range(getattr(im, "n_frames", 1)):
+ im.seek(k)
+ frame = im.convert("RGBA") # WebP publishes duration when loaded.
+ duration = im.info.get("duration")
+ if not isinstance(duration, int) or duration <= 0:
+ raise ValueError("playback has no positive integer duration")
+ frames.append(frame)
+ durations.append(duration)
+ return cls(frames, durations, repeat, format,
+ {"sha256": evidence.digest(blob), "bytes": len(blob)})
+
+ def describe(self) -> dict[str, Any]:
+ return {"frames": len(self.frames), "durations_ms": self.durations, "loop": self.loop,
+ "format": self.format, "pixels_sha256": [evidence.digest(visible_bytes(f)) for f in self.frames]}
+
+
+def mapping(loop: Any) -> tuple[list[int], int] | None:
+ """The recorded uniform export recipe, also used by legacy video-loop."""
+ n = len(loop.frames)
+ count, delay = (loop.source_report.get(k) for k in ("n_out", "delay_ms"))
+ if (type(count) is not int or not 2 <= count <= n or type(delay) is not int or delay < 20
+ or loop.delay is None or loop.timing_issue()):
+ return None
+ if delay != max(20, round(1000 * loop.meta["cycle_seconds"] / count)):
+ return None
+ return [min(n - 1, round(k * n / count)) for k in range(count)], delay
+
+
+def verify(loop: Any, animations: dict[str, Playback]) -> tuple[dict[str, Any], str | None]:
+ recipe = mapping(loop)
+ if recipe is None:
+ return {}, "playback-schedule-unverified"
+ indices, delay = recipe
+ records = {}
+ for key, fmt in (("gif", "GIF"), ("webp", "WEBP")):
+ if key not in animations:
+ return records, "playback-missing"
+ animation = animations[key]
+ expected_delay = delay // 10 * 10 if fmt == "GIF" else delay
+ if (animation.format != fmt or animation.loop != 0 or len(animation.frames) != len(indices)
+ or animation.durations != [expected_delay] * len(indices)):
+ return records, f"{key}:playback-schedule-mismatch"
+ for frame, index in zip(animation.frames, indices):
+ cell = loop.frames[index]
+ expected = _prepare_transparent_frame(cell, 128).convert("RGBA") if fmt == "GIF" else cell
+ if frame.size != cell.size or visible_bytes(frame) != visible_bytes(expected):
+ return records, f"{key}:playback-pixels-mismatch"
+ records[key] = {**animation.describe(), "strip_indices": indices, "exact_export": True}
+ return records, None
diff --git a/sprite_gen/video/restoration.py b/sprite_gen/video/restoration.py
new file mode 100644
index 0000000..f7e6f1e
--- /dev/null
+++ b/sprite_gen/video/restoration.py
@@ -0,0 +1,301 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Restore one damaged delivered cell from its verified source time, without RIFE.
+
+Source correspondence, proposal generation and final acceptance are separate.
+A failed independent proposal never hides the next one; a missing shared source
+bridge stops the operation. All quality measurements consume final pixels.
+"""
+from __future__ import annotations
+
+import argparse
+import copy
+import json
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from PIL import Image
+
+from sprite_gen._deps import np
+from sprite_gen.frames.cutout import KEY_TARGETS
+from sprite_gen.frames.extract import _key_channel_split, _key_excess_field, _SPILL_FULL_MIN_TINT
+from sprite_gen.spec.runio import atomic_write_text
+from sprite_gen.video import evidence, playback, rife, source
+from sprite_gen.video.compare import KIND as COMPARISON_KIND, Loop
+from sprite_gen.video.interpolation_quality import SMEAR_WARN, OUTLINE_WARN, faults
+
+METRIC = "source-restoration-v1"
+SCOPE = "processing-defect-restoration"
+OPERATION = "restore_active_cut"
+KIND = "sprite-gen-video-loop-restoration"
+MAX_PROPOSALS = 3
+ARTIFACTS = ("strip", "meta", "report", "gif", "webp")
+
+
+def read_loop(paths: dict[str, Path]) -> tuple[Loop, dict[str, playback.Playback]]:
+ loop = Loop.read(**{k: paths[k] for k in ("strip", "meta", "report")})
+ animations = {k: playback.Playback.read(paths[k], k.upper()) for k in ("gif", "webp")}
+ loop.artifacts.update({k: a.artifact for k, a in animations.items()})
+ return loop, animations
+
+
+def measure(frames: list[Image.Image], neighbours: list[Image.Image]) -> list[dict[str, float]]:
+ return [rife.smear(f, neighbours[k - 1], neighbours[(k + 1) % len(frames)]) for k, f in enumerate(frames)]
+
+
+def _key_field(frame: Image.Image, key: str) -> Any:
+ # Alpha-weighted excess of the key channels. Includes newly restored coverage:
+ # returning to a source pixel does not excuse reintroducing its key spill.
+ a = np.asarray(frame, dtype=np.float64)
+ channels, others = _key_channel_split(KEY_TARGETS[key])
+ tint = _key_excess_field(a[..., :3], channels, others)
+ return np.maximum(0, tint - _SPILL_FULL_MIN_TINT) * a[..., 3] / 255
+
+
+def _source_key(src: source.Source) -> str | None:
+ key = src.record["recipe"].get("key")
+ if key == "auto":
+ key = (src.record["recipe"].get("spill") or {}).get("key")
+ return key if key in ("green", "magenta") else None
+
+
+def proposals(baseline: Loop, projection: source.Projection) -> list[int]:
+ ref = projection.frames
+ actual, fixed, original = measure(baseline.frames, baseline.frames), measure(baseline.frames, ref), measure(ref, ref)
+ schedule = playback.mapping(baseline)
+ if schedule is None:
+ return []
+ shown = schedule[0]
+ boundary = {0, len(ref) - 1, shown[0], shown[-1]}
+ eligible = [k for k in projection.record["repair_hints"] if k in shown and k not in boundary
+ and baseline.frames[k].tobytes() != ref[k].tobytes()
+ and faults(actual[k]) and faults(fixed[k]) and not faults(original[k])]
+ return sorted(eligible, key=lambda k: (-max(fixed[k]["outline_loss"], fixed[k]["dark_excess"]), k))[:MAX_PROPOSALS]
+
+
+def proposal_id(baseline: Loop, src: source.Source, target: int) -> str:
+ identity = {"baseline": baseline.artifacts, "source": src.record["source"],
+ "operation": OPERATION, "metric": METRIC, "target": target}
+ return evidence.digest(json.dumps(identity, sort_keys=True, separators=(",", ":")).encode())
+
+
+def _base(baseline: Loop, candidate: Loop, src: source.Source) -> dict[str, Any]:
+ return {"kind": COMPARISON_KIND, "schema_version": 2, "metric_version": METRIC, "scope": SCOPE,
+ "operation": OPERATION, "measurement_engine": evidence.engine_identity(),
+ "baseline": baseline.describe(), "candidate": candidate.describe(),
+ "source": {"artifacts": src.artifacts, "sequence": src.record["source"]},
+ "axes": {}, "gait": {"absolute": "unverified", "source_order": "unverified"},
+ "limits": ["same-time processing damage only; no absolute gait or drawing-quality certification",
+ "source receipts bind supplied bytes; they are not signatures of the original producer"]}
+
+
+def compare(baseline: Loop, candidate: Loop, src: source.Source, *,
+ baseline_playback: dict[str, playback.Playback], candidate_playback: dict[str, playback.Playback],
+ repair_evidence: dict[str, Any]) -> dict[str, Any]:
+ result = _base(baseline, candidate, src)
+ def finish(verdict: str, reasons: list[str], common: bool = False) -> dict[str, Any]:
+ return {**result, "verdict": verdict, "reasons": reasons, "common_failure": common}
+ if (repair_evidence.get("kind") != KIND or repair_evidence.get("metric_version") != METRIC
+ or repair_evidence.get("baseline_artifacts") != baseline.artifacts
+ or repair_evidence.get("source_artifacts") != src.artifacts
+ or repair_evidence.get("candidate_artifacts") != candidate.artifacts):
+ raise ValueError("repair evidence does not bind these exact input artifacts")
+ projection, issue = source.project(baseline, src)
+ if issue:
+ return finish("unknown", [issue], True)
+ assert projection is not None
+ # The verifier may be a newer implementation. Require the same measured
+ # projection and reference bytes, not equality of the old measuring engine's
+ # identity; both engine receipts remain available for the caller to audit.
+ previous_projection = repair_evidence.get("projection")
+ if not isinstance(previous_projection, dict) or {
+ k: v for k, v in previous_projection.items() if k != "measurement_engine"
+ } != {k: v for k, v in projection.record.items() if k != "measurement_engine"}:
+ raise ValueError("repair projection evidence differs from actual source projection")
+ a_play, issue = playback.verify(baseline, baseline_playback)
+ if issue:
+ return finish("unknown", ["baseline:" + issue], True)
+ b_play, issue = playback.verify(candidate, candidate_playback)
+ if issue:
+ return finish("unknown", ["candidate:" + issue])
+ result["playback"] = {"baseline": a_play, "candidate": b_play}
+ # Metadata is copied byte-for-byte by the writer. Accept whitespace differences,
+ # but no other cut, crop, schedule, follow or rendering change.
+ if candidate.meta != baseline.meta or candidate.source_report.get("cycle") != baseline.source_report.get("cycle"):
+ return finish("unknown", ["candidate-schedule-or-geometry-changed"])
+ if any(a_play[k]["durations_ms"] != b_play[k]["durations_ms"] or
+ a_play[k]["strip_indices"] != b_play[k]["strip_indices"] for k in a_play):
+ return finish("unknown", ["playback-schedule-changed"])
+ candidate_projection, issue = source.project(candidate, src)
+ if issue:
+ return finish("unknown", ["candidate:" + issue])
+ if candidate_projection is None or candidate_projection.record["crop"] != projection.record["crop"]:
+ return finish("unknown", ["candidate-projection-changed"])
+ ref = projection.frames
+ changed = [k for k, (a, b) in enumerate(zip(baseline.frames, candidate.frames)) if a.tobytes() != b.tobytes()]
+ result["preservation"] = {"changed_cells": changed, "unchanged_cells": [k for k in range(len(ref)) if k not in changed],
+ "samples": projection.record["samples"], "pts_seconds": projection.record["pts_seconds"],
+ "crop": projection.record["crop"], "boundaries_exact": not ({0, len(ref) - 1} & set(changed))}
+ allowed = proposals(baseline, projection)
+ if changed:
+ if len(changed) != 1 or changed[0] not in allowed:
+ return finish("unknown", ["changed-cells-outside-verified-proposal"])
+ target = changed[0]
+ if (repair_evidence.get("proposal_id") != proposal_id(baseline, src, target)
+ or repair_evidence.get("target") != target):
+ raise ValueError("repair proposal identity differs from actual changed cells")
+ if candidate.frames[target].tobytes() != ref[target].tobytes():
+ return finish("regressed", ["changed-cell-is-not-exact-source-time"])
+ key = _source_key(src)
+ if key is None:
+ return finish("unknown", ["source-key-colour-unverified"], True)
+ a_final, b_final, reference = measure(baseline.frames, baseline.frames), measure(candidate.frames, candidate.frames), measure(ref, ref)
+ a_fixed, b_fixed = measure(baseline.frames, ref), measure(candidate.frames, ref)
+ axes: dict[str, Any] = {}
+ for metric, threshold in (("outline_loss", OUTLINE_WARN), ("dark_excess", SMEAR_WARN)):
+ a, b = ([max(0, q[metric] - threshold) for q in row] for row in (a_final, b_final))
+ axes[metric] = {"baseline": [q[metric] for q in a_final], "candidate": [q[metric] for q in b_final],
+ "reference": [q[metric] for q in reference], "threshold": threshold,
+ "status": "regressed" if any(y > x + 1e-9 for x, y in zip(a, b)) else
+ "improved" if any(y < x - 1e-9 for x, y in zip(a, b)) else "non_regressing"}
+ a_partial, b_partial = ([max(0, q["partial_excess"] - r["partial_excess"]) for q, r in zip(row, reference)]
+ for row in (a_fixed, b_fixed))
+ axes["introduced_partial"] = {"baseline": a_partial, "candidate": b_partial,
+ "raw_baseline": [q["partial_excess"] for q in a_fixed],
+ "raw_candidate": [q["partial_excess"] for q in b_fixed],
+ "raw_reference": [q["partial_excess"] for q in reference],
+ "status": "regressed" if any(b > a + 1e-9 for a, b in zip(a_partial, b_partial)) else "non_regressing"}
+ a_fields, b_fields = ([_key_field(f, key) for f in row] for row in (baseline.frames, candidate.frames))
+ a_key, b_key = ([float(f.sum()) for f in fields] for fields in (a_fields, b_fields))
+ introduced_key = [float(np.maximum(0, b - a).sum()) for a, b in zip(a_fields, b_fields)]
+ axes["key_colour"] = {"baseline": a_key, "candidate": b_key, "key": key,
+ "introduced_excess": introduced_key, "tint_threshold": _SPILL_FULL_MIN_TINT,
+ "status": "regressed" if any(v > 1e-9 for v in introduced_key) else "non_regressing"}
+ axes["seam"] = {"status": "non_regressing", "reason": "strip-and-playback-boundary-cells-and-durations-exact"}
+ result["axes"] = axes
+ result["gait"]["source_order"] = "preserved"
+ cleared = [{"cell": k, "faults": sorted(set(faults(a_final[k])) - set(faults(b_final[k])))} for k in changed]
+ result["cleared_faults"] = cleared
+ regressed = [k + ":regressed" for k, v in axes.items() if v["status"] == "regressed"]
+ if regressed:
+ return finish("regressed", regressed)
+ if not changed:
+ return finish("non_regressing", ["identical-pixels-and-timing"])
+ if any(faults(b_final[k]) or faults(b_fixed[k]) for k in changed) or not all(c["faults"] for c in cleared):
+ return finish("unknown", ["interpolation-fault-not-cleared"])
+ return finish("improved", ["verified-source-defect-restored"])
+
+
+def _write_candidate(paths: dict[str, Path], out: Path, name: str, baseline: Loop, src: source.Source,
+ projection: source.Projection, target: int | None, identity: str | None) -> dict[str, Path]:
+ from sprite_gen.video.loop import write_webp
+ from sprite_gen.util.gif_utils import save_clean_gif
+ if out.exists():
+ raise ValueError("candidate directory must be new (never overwrite or repeat a proposal)")
+ if not name or Path(name).name != name or name in (".", ".."):
+ raise ValueError("name must be a filename stem")
+ out.parent.mkdir(parents=True, exist_ok=True)
+ stage = Path(tempfile.mkdtemp(prefix=".restoration-", dir=out.parent))
+ names = {k: name + suffix for k, suffix in (("strip", ".strip.png"), ("meta", ".strip.json"),
+ ("report", ".loop.json"), ("gif", ".gif"), ("webp", ".webp"))}
+ try:
+ if target is None:
+ for key, filename in names.items():
+ shutil.copyfile(paths[key], stage / filename)
+ else:
+ frames = list(baseline.frames)
+ frames[target] = projection.frames[target]
+ w, h = frames[0].size
+ strip = Image.new("RGBA", (w * len(frames), h))
+ for k, frame in enumerate(frames):
+ strip.paste(frame, (k * w, 0))
+ strip.save(stage / names["strip"])
+ shutil.copyfile(paths["meta"], stage / names["meta"])
+ report = copy.deepcopy(baseline.source_report)
+ report.update(producer=evidence.engine_identity(), source=src.record["source"])
+ report["restoration"] = {"operation": OPERATION, "metric_version": METRIC, "target": target,
+ "restored_cells": sorted(set(source.restored_cells(baseline.source_report)) | {target}),
+ "proposal_id": identity, "baseline_artifacts": baseline.artifacts,
+ "projection": projection.record,
+ "upstream_quality": "historical; final pixels require source-restoration comparison"}
+ for fmt in ("gif", "webp"):
+ if isinstance(report.get(fmt), dict):
+ report[fmt]["file"] = names[fmt]
+ (stage / names["report"]).write_text(json.dumps(report, indent=2, allow_nan=False) + "\n")
+ indices, delay = playback.mapping(baseline)
+ selected = [frames[k] for k in indices]
+ save_clean_gif(selected, stage / names["gif"], duration_ms=delay, alpha_threshold=128)
+ write_webp(selected, stage / names["webp"], delay_ms=delay, workdir=stage / ".webp")
+ shutil.rmtree(stage / ".webp")
+ stage.rename(out)
+ finally:
+ if stage.exists():
+ shutil.rmtree(stage)
+ return {k: out / filename for k, filename in names.items()}
+
+
+def restore(paths: dict[str, Path], src: source.Source, *, out_dir: Path, name: str, proposal_index: int = 1) -> dict[str, Any]:
+ if type(proposal_index) is not int or not 1 <= proposal_index <= MAX_PROPOSALS:
+ raise ValueError("proposal-index must be between 1 and 3")
+ baseline, animations = read_loop(paths)
+ result = {"kind": KIND, "schema_version": 1, "metric_version": METRIC, "scope": SCOPE, "operation": OPERATION,
+ "measurement_engine": evidence.engine_identity(), "baseline_artifacts": baseline.artifacts,
+ "source_artifacts": src.artifacts, "proposal_index": proposal_index,
+ "proposal_limit": MAX_PROPOSALS, "interpolation_calls": 0, "outputs": {}}
+ projection, issue = source.project(baseline, src)
+ if not issue:
+ _, issue = playback.verify(baseline, animations)
+ if not issue and _source_key(src) is None:
+ issue = "source-key-colour-unverified"
+ if issue:
+ return {**result, "status": "unknown", "common_failure": True, "reasons": [issue]}
+ assert projection is not None
+ targets = proposals(baseline, projection)
+ result.update(projection=projection.record, proposals_available=len(targets))
+ if proposal_index > max(1, len(targets)):
+ return {**result, "status": "exhausted", "common_failure": False, "reasons": ["proposal-budget-exhausted"]}
+ target = targets[proposal_index - 1] if targets else None
+ identity = proposal_id(baseline, src, target) if target is not None else None
+ result.update(target=target, proposal_id=identity, common_failure=False, reasons=[],
+ status="candidate" if target is not None else "no_change")
+ outputs = _write_candidate(paths, out_dir, name, baseline, src, projection, target, identity)
+ candidate, candidate_animations = read_loop(outputs)
+ result.update(outputs={k: str(p) for k, p in outputs.items()}, candidate_artifacts=candidate.artifacts)
+ # This is a preview, not authority for later bytes. The compare verb rereads and
+ # measures every final input (including a caller's subsequent modifications).
+ result["comparison"] = compare(baseline, candidate, src, baseline_playback=animations,
+ candidate_playback=candidate_animations, repair_evidence=result)
+ return result
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+ for key in ARTIFACTS:
+ parser.add_argument("--baseline-" + key, type=Path, required=True)
+ source.add_inputs(parser)
+ parser.add_argument("--out-dir", type=Path, required=True)
+ parser.add_argument("--name", default="loop")
+ parser.add_argument("--proposal-index", type=int, choices=range(1, MAX_PROPOSALS + 1), default=1)
+ parser.add_argument("--report", type=Path, required=True)
+
+
+def run(**kwargs: Any) -> int:
+ try:
+ inputs = source.input_paths(kwargs)
+ paths = {k: Path(kwargs["baseline_" + k]) for k in ARTIFACTS}
+ output = Path(kwargs["report"])
+ out = Path(kwargs["out_dir"])
+ name = kwargs.get("name", "loop")
+ protected = [*paths.values(), *inputs.values(), *inputs["source_frames_dir"].glob("*.png")]
+ protected += [out / (name + ext) for ext in (".strip.png", ".strip.json", ".loop.json", ".gif", ".webp")]
+ if output.resolve() in {p.resolve() for p in protected}:
+ raise ValueError("repair report cannot overwrite an input")
+ payload = restore(paths, source.Source.read(**inputs), out_dir=out,
+ name=name, proposal_index=kwargs.get("proposal_index", 1))
+ output.parent.mkdir(parents=True, exist_ok=True)
+ text = json.dumps(payload, indent=2, allow_nan=False) + "\n"
+ atomic_write_text(output, text)
+ except (OSError, ValueError, TypeError, KeyError) as exc:
+ raise SystemExit(f"video-loop-repair: {exc}") from exc
+ print(text, end="")
+ return 0
diff --git a/sprite_gen/video/source.py b/sprite_gen/video/source.py
new file mode 100644
index 0000000..565ece8
--- /dev/null
+++ b/sprite_gen/video/source.py
@@ -0,0 +1,291 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Byte receipts for extracted source files and a deliberately exact loop projection.
+
+A receipt is not a declaration that a loop matches its source. ``project`` must
+also reproduce every unmodified delivered cell before any source pixel is used.
+Unsupported processing stays unknown; malformed or changed inputs are errors.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import math
+import platform
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from PIL import Image, __version__ as pillow_version
+
+from sprite_gen._deps import np
+from sprite_gen.video import evidence
+from sprite_gen.util.resample import resize_cell
+
+KIND = "sprite-gen-video-source-manifest"
+RECIPE = "scrub-specks-body-ramp-union-v1"
+
+
+def timestamps(clip: Path, stream_index: int) -> list[float]:
+ """Presentation timestamps from the actual picture stream, not index / fps."""
+ from sprite_gen.video.frames import _require
+ proc = subprocess.run([_require("ffprobe"), "-v", "error", "-select_streams", str(stream_index),
+ "-show_entries", "frame=best_effort_timestamp_time", "-of", "json", str(clip)],
+ capture_output=True, text=True, timeout=60)
+ if proc.returncode:
+ raise ValueError(f"cannot read source timestamps: {proc.stderr[:300]}")
+ return [float(row["best_effort_timestamp_time"]) for row in json.loads(proc.stdout)["frames"]]
+
+
+def artifact(data: bytes) -> dict[str, Any]:
+ return {"sha256": evidence.digest(data), "bytes": len(data)}
+
+
+INPUTS = ("source_manifest", "source_frames_dir", "source_clip", "source_canvas", "source_frames_report")
+
+
+def add_inputs(parser: Any, *, required: bool = True) -> None:
+ for name in INPUTS:
+ parser.add_argument("--" + name.replace("_", "-"), type=Path, required=required)
+
+
+def input_paths(kwargs: dict[str, Any]) -> dict[str, Path]:
+ if any(kwargs.get(k) is None for k in INPUTS):
+ raise ValueError("source comparison needs manifest, keyed directory, clip, canvas and frames report")
+ return {k: Path(kwargs[k]) for k in INPUTS}
+
+
+def manifest(*, clip: Path, canvas: Path, frames_report: Path,
+ files: list[Path], timestamps: list[float]) -> dict[str, Any]:
+ """Record existing extraction output; the caller obtains PTS from the clip."""
+ report = json.loads(frames_report.read_bytes())
+ if len(files) != len(timestamps) or not files:
+ raise ValueError("source timestamp count differs from keyed frame count")
+ fps = report["fps"]
+ return {"kind": KIND, "schema_version": 1, "receipt_engine": evidence.engine_identity(),
+ "receipt_environment": {"python": platform.python_version(), "platform": platform.platform(),
+ "pillow": pillow_version, "numpy": np.__version__},
+ "extraction_engine": report.get("producer"),
+ "inputs": {k: artifact(p.read_bytes()) for k, p in
+ (("clip", clip), ("canvas", canvas), ("frames_report", frames_report))},
+ "recipe": {k: report.get(k) for k in ("key", "spill", "decontam", "edge_policy", "stream_index")},
+ "fps": fps, "source": evidence.source_identity(files, fps),
+ "frames": [{"file": p.name, "pts_seconds": t, **artifact(p.read_bytes())}
+ for p, t in zip(files, timestamps)]}
+
+
+@dataclass
+class Source:
+ frames: list[Image.Image]
+ record: dict[str, Any]
+ artifacts: dict[str, Any]
+
+ @classmethod
+ def read(cls, *, source_manifest: Path, source_frames_dir: Path, source_clip: Path,
+ source_canvas: Path, source_frames_report: Path) -> Source:
+ paths = {"manifest": source_manifest, "clip": source_clip, "canvas": source_canvas,
+ "frames_report": source_frames_report}
+ data = {k: p.read_bytes() for k, p in paths.items()}
+ m = json.loads(data["manifest"])
+ report = json.loads(data["frames_report"])
+ if not isinstance(m, dict) or m.get("kind") != KIND or m.get("schema_version") != 1:
+ raise ValueError("unsupported source manifest")
+ if any(m.get("inputs", {}).get(k) != artifact(data[k]) for k in ("clip", "canvas", "frames_report")):
+ raise ValueError("source input bytes do not match manifest")
+ fps = m.get("fps")
+ if (isinstance(fps, bool) or not isinstance(fps, (int, float)) or not math.isfinite(fps)
+ or fps <= 0 or fps != report.get("fps")):
+ raise ValueError("invalid source fps")
+ rows = m.get("frames")
+ files = sorted(source_frames_dir.glob("*.png"))
+ if (not isinstance(rows, list) or not files or len(files) != len(rows)
+ or any(not isinstance(r, dict) for r in rows)
+ or [p.name for p in files] != [r.get("file") for r in rows]):
+ raise ValueError("source ordered file list differs from manifest")
+ images, hashes = [], []
+ previous = -math.inf
+ for p, r in zip(files, rows):
+ blob = p.read_bytes()
+ if any(r.get(k) != v for k, v in artifact(blob).items()):
+ raise ValueError(f"source frame bytes differ: {p.name}")
+ t = r.get("pts_seconds")
+ if isinstance(t, bool) or not isinstance(t, (int, float)) or not math.isfinite(t) or t <= previous:
+ raise ValueError("source timestamps must be finite and strictly increasing")
+ previous = t
+ with Image.open(io.BytesIO(blob)) as im:
+ if im.format != "PNG":
+ raise ValueError("source must contain PNG frames")
+ images.append(im.convert("RGBA"))
+ hashes.append(bytes.fromhex(evidence.digest(blob)))
+ identity = {"kind": "keyed-frame-sequence", "sha256": evidence.digest(b"".join(hashes)),
+ "frames": len(images), "fps": fps}
+ if m.get("source") != identity or report.get("frames") != len(images):
+ raise ValueError("source sequence identity differs from actual files")
+ if any(im.size != images[0].size for im in images):
+ raise ValueError("source frame sizes differ")
+ if images[0].size != (report.get("width"), report.get("height")):
+ raise ValueError("source dimensions differ from extraction report")
+ actual_pts = timestamps(source_clip, report["stream_index"])
+ if actual_pts != [r["pts_seconds"] for r in rows]:
+ raise ValueError("source timestamps differ from actual clip")
+ if m.get("recipe") != {k: report.get(k) for k in ("key", "spill", "decontam", "edge_policy", "stream_index")}:
+ raise ValueError("source recipe differs from extraction report")
+ return cls(images, m, {k: artifact(b) for k, b in data.items()})
+
+
+@dataclass
+class Projection:
+ frames: list[Image.Image]
+ record: dict[str, Any]
+
+
+def restored_cells(report: dict[str, Any]) -> list[int]:
+ receipt = report.get("restoration", {})
+ return receipt.get("restored_cells", [receipt["target"]] if "target" in receipt else [])
+
+
+def project(baseline: Any, source: Source) -> tuple[Projection | None, str | None]:
+ """Prove one shared crop against all cells outside the recorded repair hints."""
+ from sprite_gen.video import loop
+ from sprite_gen.video.frames import drop_specks
+
+ m, report = baseline.meta, baseline.source_report
+ if report.get("kind") != "sprite-gen-video-loop-report" or report.get("status") != "passed":
+ return None, "source-report-unverified"
+ if "follow" in m:
+ return None, "follow-source-warp-unverified"
+ n = len(baseline.frames)
+ cycle = report.get("cycle", {})
+ start, length = cycle.get("start"), cycle.get("length")
+ if (type(start) is not int or type(length) is not int or start < 0 or length != n
+ or n < 3 or start + n > len(source.frames) or m.get("subsampled") is not False
+ or m.get("cycle_frames") != n or m.get("loop") is not True):
+ return None, "source-schedule-unsupported"
+ if m.get("sample_indices", list(range(n))) != list(range(n)):
+ return None, "source-samples-mismatch"
+ for drawings in (m.get("cycle_drawings"), report.get("cycle_drawings")):
+ if drawings is not None and (drawings.get("start") != start or drawings.get("length") != n):
+ return None, "source-drawings-mismatch"
+ reported = report.get("strip")
+ if not isinstance(reported, dict) or any(m.get(k) != reported.get(k) for k in
+ ("frames", "w", "h", "delay_ms", "cycle_seconds", "scale", "source_rect", "foot_anchor", "wrap_dx_px")):
+ return None, "source-geometry-inconsistent"
+ fps = source.record["fps"]
+ if (report.get("fps") != fps or report.get("frames_total") != len(source.frames)
+ or baseline.timing_issue() or abs(m["cycle_seconds"] - n / fps) > .00005 + 1e-9):
+ return None, "source-timing-unverified"
+ pts = [row["pts_seconds"] for row in source.record["frames"]]
+ if any(abs((b - a) - 1 / fps) > 1e-5 for a, b in zip(pts, pts[1:])):
+ return None, "nonuniform-source-timing-unsupported"
+ if report.get("source") is not None and report["source"] != source.record["source"]:
+ return None, "source-sequence-mismatch"
+ if "source_cut" in m and m["source_cut"] != {
+ "source": source.record["source"], "start": start, "length": n,
+ "samples": list(range(start, start + n))}:
+ return None, "source-samples-mismatch"
+ anchor = m.get("foot_anchor")
+ if anchor not in ("none", "body") or report.get("anchor") != anchor:
+ return None, "source-anchor-unsupported"
+ if any(k in m for k in ("cycle_align", "motion_anchor")) or report.get("size_hold", {}).get("applied"):
+ return None, "source-processing-unsupported"
+ hints = (report.get("jump_repair") or {}).get("replaced", [])
+ if (not isinstance(hints, list) or any(type(k) is not int or not 0 <= k < n for k in hints)
+ or len(set(hints)) != len(hints) or len(hints) > n // 2):
+ return None, "repair-locations-unverified"
+ restored = restored_cells(report)
+ if (not isinstance(restored, list) or any(type(k) is not int or k not in hints for k in restored)
+ or len(set(restored)) != len(restored)):
+ return None, "restoration-locations-unverified"
+ # On a later request, already restored cells are part of the normal cells
+ # whose pixels must exactly match the same projection, not fresh targets.
+ hints = [k for k in hints if k not in restored]
+ keep = [k for k in range(n) if k not in hints]
+ frames = []
+ for frame in source.frames[start:start + n]:
+ frame = frame.copy()
+ loop._scrub(frame)
+ frames.append(drop_specks(frame, alpha_over=16, diagonal=False, apart=0)[0])
+ dx = loop.body_wrap_offset(frames) if anchor == "body" else 0
+ if anchor == "body" and m.get("wrap_dx_px") != dx:
+ return None, "source-anchor-mismatch"
+ frames = loop.ramp_frames(frames, dx)
+ native = report.get("source_projection")
+ if native is not None and (native.get("recipe") != RECIPE or native.get("wrap_dx_px") != dx
+ or native.get("before_repair_pixels_sha256") != [evidence.digest(f.tobytes()) for f in frames]):
+ return None, "source-processing-receipt-mismatch"
+ boxes = [frames[k].getchannel("A").point(lambda v: 255 if v >= 8 else 0).getbbox() for k in keep]
+ if any(b is None for b in boxes):
+ return None, "empty-source-subject"
+ w, h = m["w"], m["h"]
+ rect = m.get("source_rect")
+ if rect is not None:
+ if (not isinstance(rect, list) or len(rect) != 4 or any(type(v) is not int for v in rect)
+ or rect[2] <= rect[0] or rect[3] <= rect[1]):
+ raise ValueError("invalid source_rect")
+ candidates = [rect]
+ else:
+ # A legacy strip omits the crop. Bounds come only from its recorded scale
+ # recipe, frame canvas and the union of the known unmodified subjects.
+ target, standing, cap, top = (m.get(k) for k in
+ ("body_height_target", "body_src_h", "cell_height_cap", "top_margin_px"))
+ if any(type(v) is not int or v <= 0 for v in (target, standing, cap)) or type(top) is not int or top < 0:
+ return None, "legacy-projection-recipe-missing"
+ left_max, right_min = min(b[0] for b in boxes) - 8, max(b[2] for b in boxes) + 8
+ candidates = []
+ for bottom in range(max(b[3] for b in boxes), frames[0].height + 1):
+ if bottom <= top:
+ continue
+ scale = min(cap / (bottom - top), target / standing)
+ if round(scale, 4) != m.get("scale") or round((bottom - top) * scale) != h:
+ continue
+ for width in range(max(1, math.floor((w - .5) / scale)), math.ceil((w + .5) / scale) + 1):
+ if round(width * scale) != w:
+ continue
+ for left in range(max(-8, right_min - width), left_max + 1):
+ if left + width <= frames[0].width + 8:
+ candidates.append([left, top, left + width, bottom])
+ if len(candidates) > 4096:
+ return None, "legacy-projection-search-budget"
+ hits = []
+ for crop in candidates:
+ if all(resize_cell(frames[k].crop(crop), (w, h)).tobytes() == baseline.frames[k].tobytes() for k in keep):
+ hits.append(crop)
+ if len(hits) > 1:
+ return None, "legacy-projection-ambiguous"
+ if not hits:
+ return None, "legacy-source-correspondence-unverified"
+ crop = hits[0]
+ projected = [resize_cell(frame.crop(crop), (w, h)) for frame in frames]
+ receipt = {"recipe": RECIPE, "crop": crop, "cell": [w, h], "wrap_dx_px": dx,
+ "source": source.record["source"], "inputs": source.artifacts,
+ "measurement_engine": evidence.engine_identity(),
+ "scale_xy": [w / (crop[2] - crop[0]), h / (crop[3] - crop[1])],
+ "samples": list(range(start, start + n)), "pts_seconds": pts[start:start + n],
+ "unmodified_cells": keep, "repair_hints": hints, "exact_projections": 1,
+ "reference_pixels_sha256": [evidence.digest(f.tobytes()) for f in projected]}
+ return Projection(projected, receipt), None
+
+
+def add_arguments(parser: Any) -> None:
+ for name in ("clip", "canvas", "frames_report", "frames_dir", "out"):
+ parser.add_argument("--" + name.replace("_", "-"), type=Path, required=True)
+
+
+def run(**kwargs: Any) -> int:
+ """Receipt existing keyed output without repeating extraction; not a source attestation."""
+ from sprite_gen.spec.runio import atomic_write_text
+ clip, canvas, report, directory, out = (Path(kwargs[k]) for k in
+ ("clip", "canvas", "frames_report", "frames_dir", "out"))
+ files = sorted(directory.glob("*.png"))
+ try:
+ if out.resolve() in {p.resolve() for p in (clip, canvas, report, *files)}:
+ raise ValueError("manifest cannot overwrite a source input")
+ record = manifest(clip=clip, canvas=canvas, frames_report=report, files=files,
+ timestamps=timestamps(clip, json.loads(report.read_bytes())["stream_index"]))
+ out.parent.mkdir(parents=True, exist_ok=True)
+ atomic_write_text(out, json.dumps(record, indent=2, allow_nan=False) + "\n")
+ except (OSError, ValueError, KeyError, TypeError, subprocess.SubprocessError) as exc:
+ raise SystemExit(f"video-source-manifest: {exc}") from exc
+ print(json.dumps({"manifest": str(out), "source": record["source"]}))
+ return 0
diff --git a/tests/video/test_source_restoration.py b/tests/video/test_source_restoration.py
new file mode 100644
index 0000000..c317dde
--- /dev/null
+++ b/tests/video/test_source_restoration.py
@@ -0,0 +1,358 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Source-backed acceptance: actual bytes, fixed source time, and final exports.
+
+These are synthetic contract fixtures, not a production repair success claim.
+"""
+import copy
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+from PIL import Image, ImageDraw
+
+from sprite_gen.video import evidence, source, restoration, playback, loop
+from sprite_gen.cli import main
+from sprite_gen.util.gif_utils import save_clean_gif
+from sprite_gen.video.compare import Loop
+
+
+def frames():
+ result = []
+ for k in range(12):
+ im = Image.new('RGBA', (64, 80))
+ d = ImageDraw.Draw(im)
+ y = [0, 1, 2, 1, 0, -1][k % 6]
+ d.rectangle((16, 10+y, 46, 57+y), fill=(210, 160, 110), outline=(20, 20, 20), width=3)
+ # Different feet alternate independently; body bob is intentional.
+ d.rectangle((15+k%6, 58, 26+k%6, 74), fill=(45, 35, 25))
+ d.rectangle((39-k%6, 58, 48-k%6, 74), fill=(65, 45, 25))
+ # Natural partial coverage, absent from the damaged frame below.
+ d.line((15, 14+y, 15, 52+y), fill=(30, 30, 30, 170))
+ result.append(im)
+ return result
+
+
+def damage(im):
+ made = im.copy()
+ for y in range(8, 58):
+ for x in range(made.width):
+ if made.getpixel((x,y))[:3] in ((20,20,20),(30,30,30)):
+ made.putpixel((x,y),(210,160,110,255))
+ return made
+
+
+def exports(paths, fs, delay=42):
+ save_clean_gif(fs, paths['gif'], duration_ms=delay, alpha_threshold=128)
+ loop.write_webp(fs, paths['webp'], delay_ms=delay, workdir=paths['webp'].parent/'webp-temp')
+
+
+def case(tmp_path):
+ if not shutil.which('ffmpeg') or not loop.img2webp_supports_exact():
+ pytest.skip('ffmpeg and img2webp >=1.5 required')
+ fs = frames()
+ src_dir=tmp_path/'keyed'
+ src_dir.mkdir()
+ for k,f in enumerate(fs): f.save(src_dir/f'frame-{k:04}.png')
+ canvas=src_dir/'frame-0000.png'
+ freport=tmp_path/'frames.json'
+ freport.write_text(json.dumps({'kind':'sprite-gen-video-frames-report','fps':24.,'frames':12,'width':64,'height':80,'stream_index':0,'key':'green'}))
+ manifest=tmp_path/'source.json'
+ inputs=dict(source_manifest=manifest,source_frames_dir=src_dir,source_canvas=canvas,source_frames_report=freport)
+ mp4=tmp_path/'clip.mp4'
+ subprocess.run(['ffmpeg','-v','error','-framerate','24','-i',str(src_dir/'frame-%04d.png'),'-c:v','libx264','-pix_fmt','yuv420p',str(mp4)],check=True)
+ inputs['source_clip']=mp4
+ manifest.write_text(json.dumps(source.manifest(clip=mp4,canvas=canvas,frames_report=freport,files=sorted(src_dir.glob('*.png')),timestamps=source.timestamps(mp4,0))))
+ # The loop cleanup is part of the recorded recipe.
+ from sprite_gen.video.frames import drop_specks
+ clean=[]
+ for f in fs:
+ c=f.copy(); loop._scrub(c)
+ clean.append(drop_specks(c,alpha_over=16,diagonal=False,apart=0)[0])
+ bad=list(clean); bad[2]=damage(clean[2]); bad[8]=damage(clean[8])
+ paths={k:tmp_path/('b'+ext) for k,ext in [('strip','.png'),('meta','.json'),('report','.loop.json'),('gif','.gif'),('webp','.webp')]}
+ m={'frames':12,'w':64,'h':80,'delay_ms':41.67,'cycle_seconds':.5,'cycle_frames':12,'subsampled':False,'loop':True,'scale':1.,'source_rect':[0,0,64,80],'sample_indices':list(range(12)),'foot_anchor':'none'}
+ src=source.Source.read(**inputs)
+ m['source_cut']={'source':src.record['source'],'start':0,'length':12,'samples':list(range(12))}
+ report={'kind':'sprite-gen-video-loop-report','status':'passed','fps':24.,'frames_total':12,'source':src.record['source'],'cycle':{'start':0,'length':12},'anchor':'none','jump_repair':{'replaced':[2,8]},'strip':m,'n_out':12,'delay_ms':42}
+ paths['meta'].write_text(json.dumps(m)); paths['report'].write_text(json.dumps(report))
+ sheet=Image.new('RGBA',(12*64,80))
+ for k,f in enumerate(bad): sheet.paste(f,(64*k,0))
+ sheet.save(paths['strip']); exports(paths,bad)
+ return paths, inputs, clean
+
+
+def repair(case,tmp_path,index=1):
+ paths,inputs,_=case
+ return restoration.restore(paths,source.Source.read(**inputs),out_dir=tmp_path/f'candidate-{index}',name='loop',proposal_index=index)
+
+
+def compare_result(case,result):
+ paths,inputs,_=case
+ a,ap=restoration.read_loop(paths)
+ b,bp=restoration.read_loop({k:Path(p) for k,p in result['outputs'].items()})
+ return restoration.compare(a,b,source.Source.read(**inputs),baseline_playback=ap,candidate_playback=bp,repair_evidence=result)
+
+
+def test_exact_source_restoration_preserves_normal_motion_and_timing(case,tmp_path):
+ result=repair(case,tmp_path)
+ assert result['status']=='candidate'
+ comparison=compare_result(case,result)
+ assert comparison['verdict']=='improved', comparison['reasons']
+ assert comparison['metric_version']=='source-restoration-v1'
+ target=result['target']
+ a,_=restoration.read_loop(case[0]); b,_=restoration.read_loop({k:Path(v) for k,v in result['outputs'].items()})
+ assert all(x.tobytes()==y.tobytes() for k,(x,y) in enumerate(zip(a.frames,b.frames)) if k!=target)
+ assert b.frames[target].tobytes()==case[2][target].tobytes()
+ axis=comparison['axes']['introduced_partial']
+ assert axis['raw_candidate'][target]>axis['raw_baseline'][target]
+ assert axis['candidate'][target]==0
+ assert comparison['cleared_faults']==[{'cell':target,'faults':['outline']}]
+ assert comparison['gait']=={'absolute':'unverified','source_order':'preserved'}
+ assert comparison['playback']['baseline']['gif']['durations_ms']==[40]*12
+ assert comparison['playback']['candidate']['webp']['durations_ms']==[42]*12
+
+
+def test_next_independent_proposal_and_budget(case,tmp_path):
+ first,second=repair(case,tmp_path,1),repair(case,tmp_path,2)
+ assert first['target']!=second['target'] and first['proposal_id']!=second['proposal_id']
+ assert second['comparison']['verdict']=='improved'
+ assert repair(case,tmp_path,3)['status']=='exhausted'
+ with pytest.raises(ValueError,match='between 1 and 3'): repair(case,tmp_path,4)
+ with pytest.raises(ValueError,match='directory must be new'): repair(case,tmp_path,1)
+
+
+def test_normal_source_is_noop(case,tmp_path):
+ paths,_,clean=case
+ sheet=Image.new('RGBA',(12*64,80))
+ for k,f in enumerate(clean): sheet.paste(f,(k*64,0))
+ sheet.save(paths['strip']); exports(paths,clean)
+ result=repair(case,tmp_path)
+ assert result['status']=='no_change' and result['comparison']['verdict']=='non_regressing'
+ assert result['baseline_artifacts']==result['candidate_artifacts']
+
+
[email protected]('field',['clip','canvas','frames_report','frame','manifest','pts'])
+def test_changed_or_forged_source_receipt_is_error(case,field):
+ _,inputs,_=case
+ if field=='manifest':
+ m=json.loads(inputs['source_manifest'].read_bytes()); m['source']['sha256']='f'*64
+ inputs['source_manifest'].write_text(json.dumps(m))
+ elif field=='pts':
+ m=json.loads(inputs['source_manifest'].read_bytes()); m['frames'][3]['pts_seconds']+=.0001
+ inputs['source_manifest'].write_text(json.dumps(m))
+ else:
+ p=next(inputs['source_frames_dir'].glob('*.png')) if field=='frame' else inputs['source_'+field]
+ p.write_bytes(p.read_bytes()+b'changed')
+ with pytest.raises(ValueError): source.Source.read(**inputs)
+
+
+def test_missing_source_is_error_and_follow_is_shared_unknown(case,tmp_path):
+ paths,inputs,_=case
+ meta=json.loads(paths['meta'].read_bytes()); meta['follow']={'gain':1}; paths['meta'].write_text(json.dumps(meta))
+ r=repair(case,tmp_path)
+ assert r['status']=='unknown' and r['common_failure'] and not r['outputs']
+ assert r['reasons']==['follow-source-warp-unverified']
+ inputs['source_clip'].unlink()
+ with pytest.raises(FileNotFoundError): source.Source.read(**inputs)
+
+
[email protected]('mutation',['freeze','wrong_time','colour','alpha','duration','crop','report'])
+def test_tampered_final_artifacts_are_not_accepted(case,tmp_path,mutation):
+ r=repair(case,tmp_path)
+ from pathlib import Path
+ paths={k:Path(p) for k,p in r['outputs'].items()}
+ if mutation in ('duration','crop'):
+ m=json.loads(paths['meta'].read_bytes()); m['delay_ms' if mutation=='duration' else 'source_rect']=80 if mutation=='duration' else [1,0,65,80]
+ paths['meta'].write_text(json.dumps(m))
+ elif mutation=='report':
+ paths['report'].write_text(paths['report'].read_text()+'\n')
+ else:
+ c,_=restoration.read_loop(paths)
+ fs=c.frames
+ if mutation=='freeze': fs=[fs[0]]*len(fs)
+ elif mutation=='wrong_time': fs[r['target']]=fs[r['target']-1]
+ elif mutation=='colour': ImageDraw.Draw(fs[r['target']]).rectangle((22,25,36,35),fill=(0,255,0))
+ else: fs[r['target']].putpixel((32,32),(255,0,0,0))
+ sheet=Image.new('RGBA',(12*64,80))
+ for k,f in enumerate(fs): sheet.paste(f,(64*k,0))
+ sheet.save(paths['strip']); exports(paths,fs)
+ # An unchanged evidence JSON cannot authorize different final bytes.
+ with pytest.raises(ValueError): compare_result(case,r)
+ if mutation=='freeze':
+ # The WebP encoder collapses a frozen sequence to a still with no duration.
+ with pytest.raises(ValueError,match='duration'): restoration.read_loop(paths)
+ return
+ # Even rewritten receipts cannot conceal actual final pixels/schedule.
+ c,_=restoration.read_loop(paths); r['candidate_artifacts']=c.artifacts
+ verdict=compare_result(case,r)['verdict']
+ assert verdict == 'improved' if mutation=='report' else verdict in ('unknown','regressed')
+
+
+def test_actual_playback_mismatch_and_byte_hashes(case,tmp_path):
+ r=repair(case,tmp_path)
+ from pathlib import Path
+ paths={k:Path(p) for k,p in r['outputs'].items()}
+ # Same strip, differently timed WebP: even a rewritten receipt is rejected.
+ c,_=restoration.read_loop(paths)
+ loop.write_webp(c.frames,paths['webp'],delay_ms=60,workdir=tmp_path/'bad-webp')
+ c,_=restoration.read_loop(paths); r['candidate_artifacts']=c.artifacts
+ assert compare_result(case,r)['verdict']=='unknown'
+ for key,p in paths.items(): assert c.artifacts[key]['sha256']==evidence.digest(p.read_bytes())
+
+
+def test_cli_real_json_and_v1_remains_separate(case,tmp_path,capsys):
+ paths,inputs,_=case
+ args=[a for k,p in paths.items() for a in ('--baseline-'+k,str(p))]
+ args += [a for k,p in inputs.items() for a in ('--'+k.replace('_','-'),str(p))]
+ report=tmp_path/'repair.json'
+ assert main(['video-loop-repair',*args,'--out-dir',str(tmp_path/'cli'),'--report',str(report)])==0
+ r=json.loads(report.read_bytes())
+ candidate=[a for k,p in r['outputs'].items() for a in ('--candidate-'+k,p)]
+ comparison=tmp_path/'comparison.json'
+ assert main(['video-loop-compare',*args,*candidate,'--repair-evidence',str(report),'--report',str(comparison)])==0
+ c=json.loads(comparison.read_bytes())
+ assert c['verdict']=='improved' and c['schema_version']==2
+ assert set(c['candidate']['artifacts'])=={'strip','meta','report','gif','webp'}
+
+
+def test_colour_tradeoff_does_not_stop_next_independent_target(case,tmp_path):
+ paths,inputs,clean=case
+ # A real source pixel can still be bad: restoring it may reintroduce key tint.
+ # Colour at one target differs from its delivered frame but the other target is independent.
+ p=inputs['source_frames_dir']/'frame-0002.png'
+ with Image.open(p) as image: tinted=image.convert('RGBA')
+ ImageDraw.Draw(tinted).rectangle((25,25,28,28),fill=(180,205,120))
+ tinted.save(p)
+ record=source.manifest(clip=inputs['source_clip'],canvas=inputs['source_canvas'],frames_report=inputs['source_frames_report'],
+ files=sorted(inputs['source_frames_dir'].glob('*.png')),timestamps=source.timestamps(inputs['source_clip'],0))
+ inputs['source_manifest'].write_text(json.dumps(record))
+ m=json.loads(paths['meta'].read_bytes()); m['source_cut']['source']=record['source']; paths['meta'].write_text(json.dumps(m))
+ r=json.loads(paths['report'].read_bytes()); r.update(source=record['source'],strip=m); paths['report'].write_text(json.dumps(r))
+ outcomes=[repair(case,tmp_path,k)['comparison'] for k in (1,2)]
+ assert {o['verdict'] for o in outcomes}=={'regressed','improved'}
+ bad=next(o for o in outcomes if o['verdict']=='regressed')
+ assert 'key_colour:regressed' in bad['reasons']
+
+
+def test_missing_legacy_recipe_is_shared_unknown(case,tmp_path):
+ paths,_,_=case
+ m=json.loads(paths['meta'].read_bytes()); m.pop('source_rect'); paths['meta'].write_text(json.dumps(m))
+ r=json.loads(paths['report'].read_bytes()); r['strip']=m; paths['report'].write_text(json.dumps(r))
+ result=repair(case,tmp_path)
+ assert result['status']=='unknown' and result['common_failure']
+ assert result['reasons']==['legacy-projection-recipe-missing']
+ assert not (tmp_path/'candidate-1').exists()
+
+
+def test_native_before_repair_receipt_is_checked(case,tmp_path):
+ paths,_,clean=case
+ r=json.loads(paths['report'].read_bytes())
+ r['source_projection']={'recipe':source.RECIPE,'wrap_dx_px':0,'before_repair_pixels_sha256':[evidence.digest(f.tobytes()) for f in clean]}
+ paths['report'].write_text(json.dumps(r))
+ assert repair(case,tmp_path)['comparison']['verdict']=='improved'
+ r['source_projection']['before_repair_pixels_sha256'][2]='a'*64
+ paths['report'].write_text(json.dumps(r))
+ result=restoration.restore(paths,source.Source.read(**case[1]),out_dir=tmp_path/'rejected',name='loop')
+ assert result['reasons']==['source-processing-receipt-mismatch'] and result['common_failure']
+
+
+def test_overwriting_any_input_is_refused(case,tmp_path):
+ paths,inputs,_=case
+ args=[a for k,p in paths.items() for a in ('--baseline-'+k,str(p))]
+ args += [a for k,p in inputs.items() for a in ('--'+k.replace('_','-'),str(p))]
+ old=paths['meta'].read_bytes()
+ with pytest.raises(SystemExit,match='cannot overwrite'):
+ main(['video-loop-repair',*args,'--out-dir',str(tmp_path/'unsafe'),'--report',str(paths['meta'])])
+ assert paths['meta'].read_bytes()==old and not (tmp_path/'unsafe').exists()
+
+
+def test_legacy_ambiguous_projection_cannot_choose_one_crop():
+ # Severe downscaling erases differences between several integer crops.
+ # A single best-looking crop is insufficient evidence.
+ from sprite_gen.util.resample import resize_cell
+ im=Image.new('RGBA',(64,64))
+ ImageDraw.Draw(im).rectangle((16,16,47,63),fill=(180,120,60,8))
+ src=source.Source([im.copy() for _ in range(6)],
+ {'fps':24.,'source':{},'frames':[{'pts_seconds':k/24} for k in range(6)]},{})
+ m={'frames':6,'w':2,'h':2,'delay_ms':41.67,'cycle_seconds':.25,'cycle_frames':6,'subsampled':False,'loop':True,
+ 'scale':round(2/64,4),'foot_anchor':'none','body_height_target':2,'body_src_h':64,'cell_height_cap':10,'top_margin_px':8}
+ r={'kind':'sprite-gen-video-loop-report','status':'passed','anchor':'none','fps':24.,'frames_total':6,'cycle':{'start':0,'length':6},'strip':m}
+ cell=resize_cell(im.crop((8,8,56,64)),(2,2))
+ b=Loop([cell.copy() for _ in range(6)],m,r,{},41.67)
+ p,reason=source.project(b,src)
+ assert p is None and reason=='legacy-projection-ambiguous'
+
+
+def test_later_request_uses_new_baseline_and_preserves_previous_restoration(case,tmp_path):
+ first=repair(case,tmp_path,1)
+ first_paths={k:Path(p) for k,p in first['outputs'].items()}
+ second=restoration.restore(first_paths,source.Source.read(**case[1]),out_dir=tmp_path/'next-request',name='loop')
+ assert second['comparison']['verdict']=='improved'
+ assert second['target']!=first['target']
+ assert second['baseline_artifacts']==first['candidate_artifacts']
+ assert second['proposal_id']!=first['proposal_id']
+ assert first['target'] in second['projection']['unmodified_cells']
+ assert second['comparison']['preservation']['changed_cells']==[second['target']]
+ assert first['target'] in second['comparison']['preservation']['unchanged_cells']
+ final_paths={k:Path(p) for k,p in second['outputs'].items()}
+ third=restoration.restore(final_paths,source.Source.read(**case[1]),out_dir=tmp_path/'all-restored',name='loop')
+ assert third['status']=='no_change' and third['comparison']['verdict']=='non_regressing'
+
+
+def test_low_scale_legacy_search_is_bounded():
+ from sprite_gen.util.resample import resize_cell
+ im=Image.new('RGBA',(64,80))
+ ImageDraw.Draw(im).rectangle((16,16,47,63),fill=(180,120,60))
+ src=source.Source([im.copy() for _ in range(6)],{'fps':24.,'source':{},'frames':[{'pts_seconds':k/24} for k in range(6)]},{})
+ m={'frames':6,'w':2,'h':2,'delay_ms':41.67,'cycle_seconds':.25,'cycle_frames':6,'subsampled':False,'loop':True,
+ 'scale':round(2/64,4),'foot_anchor':'none','body_height_target':2,'body_src_h':64,'cell_height_cap':10,'top_margin_px':8}
+ r={'kind':'sprite-gen-video-loop-report','status':'passed','anchor':'none','fps':24.,'frames_total':6,'cycle':{'start':0,'length':6},'strip':m}
+ b=Loop([resize_cell(im.crop((8,8,56,64)),(2,2)) for _ in range(6)],m,r,{},41.67)
+ assert source.project(b,src)[1]=='legacy-projection-search-budget'
+
+
+def test_video_frames_writes_a_receipt_of_the_actual_extraction(tmp_path):
+ from sprite_gen.video.frames import run_frames
+ if not shutil.which('ffmpeg'):
+ pytest.skip('ffmpeg required')
+ inputs=tmp_path/'input'; inputs.mkdir()
+ for k,f in enumerate(frames()):
+ canvas=Image.new('RGB',f.size,(0,255,0));canvas.paste(f,mask=f.getchannel('A'))
+ canvas.save(inputs/f'frame-{k:04}.png')
+ clip=tmp_path/'clip.mp4'
+ subprocess.run(['ffmpeg','-v','error','-framerate','24','-i',str(inputs/'frame-%04d.png'),'-c:v','libx264','-pix_fmt','yuv420p',str(clip)],check=True)
+ report=tmp_path/'frames.json'; manifest=tmp_path/'receipts/source.json'
+ run_frames(clip,tmp_path/'output',key='green',allow_edge_contact=False,report_path=report,
+ reference=inputs/'frame-0000.png',source_manifest=manifest)
+ src=source.Source.read(source_clip=clip,source_canvas=inputs/'frame-0000.png',source_frames_report=report,
+ source_manifest=manifest,source_frames_dir=tmp_path/'output/keyed')
+ assert len(src.frames)==12
+ assert src.record['extraction_engine']==evidence.engine_identity()
+ assert src.record['inputs']['frames_report']['sha256']==evidence.digest(report.read_bytes())
+
+
+def test_less_total_key_spill_cannot_hide_new_local_key_spill(case,tmp_path):
+ paths,inputs,_=case
+ # More green is removed at one location than introduced at a different one.
+ # A summed colour score would incorrectly allow the tradeoff.
+ with Image.open(paths['strip']) as im: strip=im.convert('RGBA')
+ d=ImageDraw.Draw(strip)
+ for k in (2,8): d.rectangle((k*64+20,22,k*64+28,28),fill=(80,240,60))
+ strip.save(paths['strip'])
+ fs=[strip.crop((k*64,0,(k+1)*64,80)) for k in range(12)];exports(paths,fs)
+ for k in (2,8):
+ p=inputs['source_frames_dir']/f'frame-{k:04}.png'
+ with Image.open(p) as im: f=im.convert('RGBA')
+ ImageDraw.Draw(f).rectangle((35,35,36,36),fill=(180,210,110));f.save(p)
+ record=source.manifest(clip=inputs['source_clip'],canvas=inputs['source_canvas'],frames_report=inputs['source_frames_report'],files=sorted(inputs['source_frames_dir'].glob('*.png')),timestamps=source.timestamps(inputs['source_clip'],0))
+ inputs['source_manifest'].write_text(json.dumps(record))
+ m=json.loads(paths['meta'].read_bytes());m['source_cut']['source']=record['source'];paths['meta'].write_text(json.dumps(m))
+ r=json.loads(paths['report'].read_bytes());r.update(source=record['source'],strip=m);paths['report'].write_text(json.dumps(r))
+ outcome=repair(case,tmp_path)['comparison']
+ key=outcome['axes']['key_colour'];target=outcome['preservation']['changed_cells'][0]
+ assert key['candidate'][target]<key['baseline'][target]
+ assert key['introduced_excess'][target]>0
+ assert outcome['verdict']=='regressed' and 'key_colour:regressed' in outcome['reasons']