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.mdindex 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.mdindex 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 interpolationquality 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.pyindex 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.pyindex 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_promptfrom sprite_gen.video import align as video_alignfrom sprite_gen.video import follow as video_followfrom 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_sourcefrom sprite_gen.video import rife_installfrom sprite_gen.effects import recolor, shadowfrom sprite_gen.scene import render, inspect_scene@@ -360,6 +362,16 @@ COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callabvideo_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.pyindex 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.pyindex 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.pyindex 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 0diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.pyindex 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 excreport_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"] = Nonetry:diff --git a/sprite_gen/video/playback.py b/sprite_gen/video/playback.pynew file mode 100644index 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, Nonediff --git a/sprite_gen/video/restoration.py b/sprite_gen/video/restoration.pynew file mode 100644index 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 0diff --git a/sprite_gen/video/source.py b/sprite_gen/video/source.pynew file mode 100644index 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 0diff --git a/tests/video/test_source_restoration.py b/tests/video/test_source_restoration.pynew file mode 100644index 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']