Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
feat(video): restore a damaged cell with the source pixels that keep the key guard, rebuilt from an immutable origin
Soohong Kimf2a93e69dd40
diff --git a/docs/loop-comparison.md b/docs/loop-comparison.mdindex e324443..aae3862 100644--- a/docs/loop-comparison.md+++ b/docs/loop-comparison.md@@ -116,10 +116,64 @@ quality bounds, and [video pipeline](video-pipeline.md) for processing stages.`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.+schedule. No interpolation is called. This operation has its own contract:+repair report `schema_version: 2`, comparison `schema_version: 3`,+`metric_version: source-restoration-v2`, `policy_version:+key-protected-source-copy-v1`, `scope: processing-defect-restoration`,+`operation: restore_active_cut`. The v1 comparison above is unchanged.+`source-restoration-v1`, an unreleased draft that copied the whole source cell,+is not this contract: its evidence and receipts are refused, never read as v2.++### What a restored cell is++In the target cell, a pixel that differs from the source at the same place and+the same source time becomes the source's pixel, **unless the source's pixel+would raise the key-colour guard there**. At those places the delivered pixel+stays. Every pixel of the output is the whole RGBA of one of the two at that+place: nothing is blended, moved, borrowed from another frame or recoloured,+and a colour hidden under zero coverage never gains coverage.++```text+K(p) = alpha(p) x max(0, key hue excess(p) - 8) whole numbers+differing = places where the origin's cell and the source's differ in RGBA+protected = differing places where K(source) > K(origin)+copied = differing places that are not protected+output(p) = source(p) where copied, origin(p) everywhere else+```++`K` is 255 times the alpha-weighted excess of `axes.key_colour`, with the same+full-spill bar and the same hue test (green: `G - max(R, B)`; magenta:+`min(R, B) - G`), so yellow, cyan, red and blue are not the key's hue. The mask+is made by the engine from the actual files and has no manual input: no+dilation, blur, key cleanup or tuning. When nothing is protected the output is+the whole source cell.++**The output's coverage must be the source's at every pixel.** Where a protected+place has another alpha in the origin than in the source, keeping the delivered+pixel would keep a silhouette the source does not have, so that proposal ends+with `status: unknown`, `common_failure: false`, reason+`protected-pixel-alpha-conflict` and empty `outputs`. Nothing is written. It+used that proposal's attempt; the next independent proposal may be tried. A+target whose every differing place is protected ends the same way with+`no-unprotected-source-pixel`. No protected pixel is given up to make a+candidate pass, however few they are.++### The origin++Restoration needs three sets of files, all read and hashed again on every call:++| Input | What it is |+|---|---|+| source | the clip, canvas, ordered keyed PNGs, extraction report and their manifest |+| origin | the five loop files the **first** restoration of this loop started from |+| baseline | the five loop files active now |++On a first request the origin is the baseline: pass the same five files twice.+After a candidate is adopted, the next request passes the adopted five files as+the baseline and **the same origin as before**. The origin is required and is+never guessed from the baseline. An application records the origin's object keys+and digests at the first request and supplies those bytes from then on; the+origin is evidence for recomputation, not a second copy of the active result.First retain the actual clip, canvas, keyed PNGs, and extraction report. Newextractions can use `video-frames --source-manifest source.json --reference@@ -143,6 +197,8 @@ hashes are read and checked again, not trusted from a `verified` flag.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 \+ --origin-strip O.strip.png --origin-meta O.strip.json \+ --origin-report O.loop.json --origin-gif O.gif --origin-webp O.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@@ -155,10 +211,13 @@ to `loop.strip.png`, `loop.strip.json`, `loop.loop.json`, `loop.gif`, `loop.webpreplace 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.+source-relative damage. `--proposal-index` is one-based, limited to 1–3. A cell+already restored, a strip or playback boundary cell and a cell that is not+played are never proposed. The stable `proposal_id` binds the baseline's five+digests, the origin's five digests, the source inputs and sequence, the+projection, the policy version, the target and the digests of its two masks.+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 ||---|---|@@ -167,16 +226,23 @@ The application owns its deadline, attempted IDs and adoption transaction.| `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 |+| `applied_cells` | Cells earlier requests restored, in order, as rebuilt from the origin |+| `origin_artifacts`, `baseline_artifacts`, `candidate_artifacts` | Exact five-file byte receipts (`sha256`, `bytes` per file) || `source_artifacts`, `projection` | Source inputs, fixed transform, sample PTS and exact correspondence |+| `partial.copied`, `partial.protected` | The two masks of the target: `size`, `count`, row-major run lengths `rle` (the first run is clear) and `sha256` of the packed bits |+| `partial.alpha_equals_source` | Whether the output's coverage is the source's; `false` only with `protected-pixel-alpha-conflict` |+| `partial.protected_pixels` | `count`, `alpha_conflicts`, and for the first 256 in row order (`listed`) `x`, `y`, `origin_rgba`, `source_rgba`, `origin_key_weight`, `source_key_weight`, `alpha_equal` || `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 comparesas `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.+unmodified cell of the origin, 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. A request whose proposals exist but are each refused stays+`unknown` or `regressed` per proposal and keeps the active result; it is not+reported as `no_change`.The supported projection is scrub, small-component cleanup, optional integerbody ramp, one shared integer crop and the standard resampler. New loop reports@@ -186,12 +252,66 @@ matches remain unknown. Frame-specific alignment, different cuts, subsampling,size hold, motion anchoring, cycle alignment, or unproven follow warps are notaccepted. Do not rerun follow on a restoration output.-Compare the final artifacts using the **same** source inputs:+### The receipt and what a later request rebuilds++A candidate's metadata is the baseline's, byte for byte. Its loop report is the+origin's own report with one key added, `restoration`; the historical+`jump_repair`, `producer` and animation records stay as the origin wrote them+and are not a new quality verdict. The five final digests are in the repair and+comparison reports, not in the loop report, which cannot hold its own digest.++| `restoration` field | Contract |+|---|---|+| `operation`, `metric_version`, `policy_version` | This contract |+| `origin_artifacts` | The origin's five byte receipts |+| `source_artifacts`, `source` | Source input receipts and the ordered keyed sequence identity |+| `projection` | Recipe, crop, cell, scale, wrap, samples, PTS, reference pixel hashes |+| `applied` | One entry per restored cell, in the order they were adopted; a cell appears once |+| `applied[].target`, `source_index` | The cell and its source frame |+| `applied[].copied`, `protected` | The two masks, as in the repair report |+| `applied[].origin_rgba_sha256`, `source_rgba_sha256`, `output_rgba_sha256` | The cell in the origin, in the source projection and as restored |+| `applied[].alpha_equals_source` | Always `true` for an applied cell |+| `applied[].proposal_id`, `baseline_artifacts`, `baseline_pixels_sha256` | The proposal, the five files it was proposed on and their decoded cells |+| `applied[].measurement_engine` | The implementation that wrote the entry; a later one recomputes everything else |++Nothing in a receipt is trusted. Every request reads the origin, the source and+the baseline, proves the projection on **the origin's** normal cells, then+makes each applied cell again from the origin and the source in the recorded+order. Each must have been a proposal of the loop as it stood before it, must+give the recorded masks and digests, and must pass the protections on that+loop. The cells read from the baseline must then equal the rebuilt ones: an+applied cell its partial copy, every other cell the origin's. The rebuilt+pixels are an expectation to compare with; they never replace the baseline's+files. A restored cell therefore stays verified although it is no longer the+source's whole cell.++These are errors, with nonzero exit: an origin that already carries a receipt;+a baseline that differs from the origin without a receipt; a receipt naming+another origin or source; an applied entry that is repeated, out of range, not+a proposal of its prefix, or whose mask, digests or protections the inputs do+not reproduce; an emptied or extended receipt; changed metadata bytes or a+changed report outside the receipt; and baseline pixels that differ from the+rebuilt ones in any cell. A receipt of another metric or policy version is+shared `unknown` with `restoration-receipt-policy-unsupported`.++An earlier file digest in `applied[].baseline_artifacts` is a label bound into+that entry's proposal ID: the first must be the origin's, and the pixels each+stands for are recomputed (`baseline_pixels_sha256`). Digests are not a+signature. A caller that replaces the origin, the source and their manifest+together presents a different history, which the engine cannot tell from the+first; the application's stored origin digests and its revision check own that+boundary.++### Comparing the final artifacts++Compare the final artifacts using the **same** source inputs and origin:```bashsprite-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 \+ --origin-strip O.strip.png --origin-meta O.strip.json \+ --origin-report O.loop.json --origin-gif O.gif --origin-webp O.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 \@@ -200,31 +320,52 @@ sprite-gen video-loop-compare \--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.+The comparator rebuilds the baseline from the origin and the source, makes the+target's masks and partial copy again, 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/origin/evidence files and encoder/decoder+failures return nonzero. An unsupported mapping is `unknown`, not an execution+error disguised as a normal result.++The report carries `origin`, `baseline` and `candidate` (each with its five+`artifacts`), `source.artifacts` and `source.sequence`, `provenance.applied`+(the earlier cells as rebuilt), `restoration` (the changed cell's `target`,+`proposal_id`, masks and protected pixels, as in the repair report),+`preservation`, `playback`, `axes`, `cleared_faults` and `gait`.++`improved` requires that the one changed cell is byte-exact the partial copy+made from the origin and the source, its coverage the source's, the candidate's+receipt the recomputed one, at least one cleared actual fault, unchanged normal+cells and metadata bytes, and no worsening protected axis. Changed pixels+outside the copied mask return `regressed` with+`changed-cell-is-not-the-verified-source-copy`; a receipt that differs returns+`unknown` with `candidate-report-differs-from-verified-receipt`; changed+metadata bytes `candidate-metadata-bytes-changed`; equal pixels with any other+changed file `unchanged-pixels-with-changed-artifacts`.++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.+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.++Key-colour protection is read again from the final strip, whatever the mask+promised. `axes.key_colour.introduced_excess` sums only the positive per-pixel+increases of the alpha-weighted excess on the fixed canvas, per cell, and+`introduced_pixels` counts the pixels that increased. The sum is not a pixel+count. A reduction elsewhere cannot offset newly introduced spill, even when+the cell's total tint decreases.For an outline-specific UI success message, require `verdict == improved` andan `outline` entry in `cleared_faults[].faults`. `axes` contains raw baseline,reference and candidate values for outline/smear, source-relative partialcoverage 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.+order only; `gait.absolute == unverified` remains explicit. A restored cell is+the source's pixel or the delivered one at each place; these measurements do+not claim the source's whole drawing, nor to repair mistakes already in it.A candidate-specific unknown or regression may be followed by the next unusedproposal within budget. Shared unknown stops the request. Upload and activate@@ -233,15 +374,7 @@ initial repair report is not authority to replace the active revision.Every proposal in one request starts from the same immutable baseline. Proposal2 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.+the adopted five files as its new baseline with the unchanged origin, so its+proposal IDs and baseline digests change. 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.diff --git a/sprite_gen/video/compare.py b/sprite_gen/video/compare.pyindex 567f693..5a50688 100644--- a/sprite_gen/video/compare.py+++ b/sprite_gen/video/compare.py@@ -266,7 +266,9 @@ def add_arguments(parser: argparse.ArgumentParser) -> None: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+ from sprite_gen.video import restoration, source+ for artifact in restoration.ARTIFACTS:+ parser.add_argument(f"--origin-{artifact}", type=Path)source.add_inputs(parser, required=False)parser.add_argument("--repair-evidence", type=Path)parser.add_argument("--report", required=True, type=Path)@@ -276,16 +278,19 @@ 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:- from sprite_gen.video import source- restoration_mode = any(kwargs.get(k) is not None for k in (*source.INPUTS, "repair_evidence"))+ from sprite_gen.video import restoration, source+ origin = {k: kwargs.get(f"origin_{k}") for k in restoration.ARTIFACTS}+ restoration_mode = any(kwargs.get(k) is not None for k in (*source.INPUTS, "repair_evidence")) or any(origin.values())protected = [p for row in paths.values() for p in row.values()]if restoration_mode:- from sprite_gen.video import restorationinputs = 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")+ # The origin is never guessed from the current baseline, not even on a first request.+ if (any(kwargs.get(f"{s}_{k}") is None for s in paths for k in ("gif", "webp"))+ or None in origin.values() or not kwargs.get("repair_evidence")):+ raise ValueError("source comparison requires the origin's five files, baseline/candidate GIF and WebP, and repair evidence")for side in paths:paths[side].update({k: Path(kwargs[f"{side}_{k}"]) for k in ("gif", "webp")})+ paths["origin"] = {k: Path(p) for k, p in origin.items()}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()]@@ -296,7 +301,8 @@ def run(**kwargs: Any) -> int: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,+ payload = restoration.compare(restoration.read_loop(paths["origin"])[0], 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"]))diff --git a/sprite_gen/video/restoration.py b/sprite_gen/video/restoration.pyindex f7e6f1e..640007d 100644--- a/sprite_gen/video/restoration.py+++ b/sprite_gen/video/restoration.py@@ -1,6 +1,12 @@# SPDX-License-Identifier: Apache-2.0"""Restore one damaged delivered cell from its verified source time, without RIFE.+A source pixel is copied only where it does not raise the key guard over the+origin's pixel; the origin's pixel stays everywhere else, and the cell's whole+coverage must still be the source's. The origin is the five files the first+restoration started from: every request rebuilds the current baseline from it+and the source, so a receipt is recomputed, never trusted.+Source correspondence, proposal generation and final acceptance are separate.A failed independent proposal never hides the next one; a missing shared sourcebridge stops the operation. All quality measurements consume final pixels.@@ -8,10 +14,10 @@ bridge stops the operation. All quality measurements consume final pixels.from __future__ import annotationsimport argparse-import copyimport jsonimport shutilimport tempfile+from dataclasses import dataclassfrom pathlib import Pathfrom typing import Any@@ -25,12 +31,20 @@ from sprite_gen.video import evidence, playback, rife, sourcefrom sprite_gen.video.compare import KIND as COMPARISON_KIND, Loopfrom sprite_gen.video.interpolation_quality import SMEAR_WARN, OUTLINE_WARN, faults-METRIC = "source-restoration-v1"+METRIC = "source-restoration-v2"+POLICY = "key-protected-source-copy-v1"SCOPE = "processing-defect-restoration"OPERATION = "restore_active_cut"KIND = "sprite-gen-video-loop-restoration"+REPAIR_SCHEMA = 2+COMPARISON_SCHEMA = 3MAX_PROPOSALS = 3ARTIFACTS = ("strip", "meta", "report", "gif", "webp")+PROTECTED_LISTED = 256 # protected pixels a report spells out; the mask always holds all of them++# The guard in whole numbers is the same formula only while the bar is a whole number.+_BAR = int(_SPILL_FULL_MIN_TINT)+assert _BAR == _SPILL_FULL_MIN_TINTdef read_loop(paths: dict[str, Path]) -> tuple[Loop, dict[str, playback.Playback]]:@@ -44,13 +58,15 @@ def measure(frames: list[Image.Image], neighbours: list[Image.Image]) -> list[direturn [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)+def key_weight(rgba: Any, key: str) -> Any:+ """Alpha times the key hue's excess over the full-spill bar, per pixel, in whole numbers.++ 255 times the alpha-weighted excess the comparison reports. Includes newly+ restored coverage: returning to a source pixel does not excuse its key spill.+ """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+ hue = _key_excess_field(rgba[..., :3].astype(np.int64), channels, others)+ return rgba[..., 3].astype(np.int64) * np.maximum(0, hue - _BAR)def _source_key(src: source.Source) -> str | None:@@ -60,59 +76,252 @@ def _source_key(src: source.Source) -> str | None:return key if key in ("green", "magenta") else None-def proposals(baseline: Loop, projection: source.Projection) -> list[int]:+@dataclass+class Partial:+ frame: Image.Image # the source where it is copied, the origin where it is protected+ copied: Any+ protected: Any+ alpha_conflict: bool # a protected pixel whose coverage is not the source's+++def partial(origin: Image.Image, reference: Image.Image, key: str) -> Partial:+ """Where the two differ, the source's pixel unless it would raise the key guard there.++ Every pixel is the origin's or the source's whole RGBA at the same place: no+ colour is mixed, moved or made, and a hidden colour never gains coverage.+ """+ b, s = (np.asarray(f, dtype=np.uint8) for f in (origin, reference))+ differs = (b != s).any(axis=-1)+ protected = differs & (key_weight(s, key) > key_weight(b, key))+ copied = differs & ~protected+ frame = Image.fromarray(np.where(copied[..., None], s, b))+ return Partial(frame, copied, protected, bool((b[..., 3] != s[..., 3])[protected].any()))+++def _mask(mask: Any) -> dict[str, Any]:+ """A mask as row-major run lengths, the first run clear, and the digest of its packed bits."""+ flat = np.asarray(mask, dtype=bool).ravel()+ bounds = np.concatenate(([0], np.flatnonzero(flat[1:] != flat[:-1]) + 1, [flat.size]))+ runs = np.diff(bounds).tolist()+ h, w = mask.shape+ return {"size": [w, h], "count": int(flat.sum()), "rle": [0, *runs] if flat[0] else runs,+ "sha256": evidence.digest(f"{w}x{h}:".encode() + np.packbits(flat).tobytes())}+++def _protected_pixels(part: Partial, origin: Image.Image, reference: Image.Image, key: str) -> dict[str, Any]:+ b, s = (np.asarray(f, dtype=np.uint8) for f in (origin, reference))+ kb, ks = key_weight(b, key), key_weight(s, key)+ places = np.argwhere(part.protected)+ return {"count": len(places), "alpha_conflicts": int((b[..., 3] != s[..., 3])[part.protected].sum()),+ "listed": min(len(places), PROTECTED_LISTED),+ "pixels": [{"x": int(x), "y": int(y), "origin_rgba": b[y, x].tolist(), "source_rgba": s[y, x].tolist(),+ "origin_key_weight": int(kb[y, x]), "source_key_weight": int(ks[y, x]),+ "alpha_equal": bool(b[y, x, 3] == s[y, x, 3])} for y, x in places[:PROTECTED_LISTED]]}+++def _describe(part: Partial, origin: Image.Image, reference: Image.Image, key: str) -> dict[str, Any]:+ return {"copied": _mask(part.copied), "protected": _mask(part.protected),+ "alpha_equals_source": not part.alpha_conflict,+ "protected_pixels": _protected_pixels(part, origin, reference, key)}+++def proposals(frames: list[Image.Image], projection: source.Projection, shown: list[int],+ applied: list[int]) -> 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]+ actual, fixed, original = measure(frames, frames), measure(frames, ref), measure(ref, ref)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()+ eligible = [k for k in projection.record["repair_hints"] if k in shown and k not in boundary and k not in applied+ and 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}+def _portable(value: Any) -> Any:+ """A record without the identity of the engine that wrote it; a later engine recomputes the rest."""+ if isinstance(value, dict):+ return {k: _portable(v) for k, v in value.items() if k != "measurement_engine"}+ return [_portable(v) for v in value] if isinstance(value, list) else value+++def proposal_id(current: dict[str, Any], origin: dict[str, Any], src: source.Source,+ projection: source.Projection, target: int, part: Partial) -> str:+ identity = {"current": current, "origin": origin,+ "source": {"artifacts": src.artifacts, "sequence": src.record["source"]},+ "projection": _portable(projection.record), "operation": OPERATION, "metric": METRIC,+ "policy": POLICY, "target": target,+ "mask": {k: _mask(m)["sha256"] for k, m in (("copied", part.copied), ("protected", part.protected))}}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(),+def _entry(target: int, part: Partial, origin: Loop, current: dict[str, Any], before: list[Image.Image],+ src: source.Source, projection: source.Projection) -> dict[str, Any]:+ """One applied cell. `current` is the five-file receipt of the baseline it was proposed on."""+ return {"target": target, "source_index": projection.record["samples"][target],+ "proposal_id": proposal_id(current, origin.artifacts, src, projection, target, part),+ "baseline_artifacts": current,+ "baseline_pixels_sha256": evidence.digest(b"".join(f.tobytes() for f in before)),+ "copied": _mask(part.copied), "protected": _mask(part.protected),+ "origin_rgba_sha256": evidence.digest(origin.frames[target].tobytes()),+ "source_rgba_sha256": evidence.digest(projection.frames[target].tobytes()),+ "output_rgba_sha256": evidence.digest(part.frame.tobytes()),+ "alpha_equals_source": not part.alpha_conflict, "measurement_engine": evidence.engine_identity()}+++def _receipt(origin: Loop, src: source.Source, projection: source.Projection,+ applied: list[dict[str, Any]]) -> dict[str, Any]:+ return {"operation": OPERATION, "metric_version": METRIC, "policy_version": POLICY,+ "origin_artifacts": origin.artifacts, "source_artifacts": src.artifacts,+ "source": src.record["source"], "projection": projection.record, "applied": applied,+ "upstream_quality": "historical; final pixels require source-restoration comparison"}+++def judge(before: list[Image.Image], after: list[Image.Image], ref: list[Image.Image], key: str) -> dict[str, Any]:+ """The protections over final pixels, from one loop's cells to the next's."""+ changed = [k for k, (a, b) in enumerate(zip(before, after)) if a.tobytes() != b.tobytes()]+ a_final, b_final, reference = measure(before, before), measure(after, after), measure(ref, ref)+ a_fixed, b_fixed = measure(before, ref), measure(after, 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_weight(np.asarray(f, dtype=np.uint8), key) for f in row] for row in (before, after))+ raised = [np.maximum(0, b - a) for a, b in zip(a_fields, b_fields)]+ axes["key_colour"] = {"baseline": [int(f.sum()) / 255 for f in a_fields],+ "candidate": [int(f.sum()) / 255 for f in b_fields], "key": key,+ "introduced_excess": [int(r.sum()) / 255 for r in raised],+ "introduced_pixels": [int((r > 0).sum()) for r in raised], "tint_threshold": _BAR,+ "status": "regressed" if any(r.any() for r in raised) else "non_regressing"}+ cleared = [{"cell": k, "faults": sorted(set(faults(a_final[k])) - set(faults(b_final[k])))} for k in changed]+ regressed = [k + ":regressed" for k, v in axes.items() if v["status"] == "regressed"]+ if regressed:+ verdict, reasons = "regressed", regressed+ elif not changed:+ verdict, reasons = "non_regressing", ["identical-pixels-and-timing"]+ elif any(faults(b_final[k]) or faults(b_fixed[k]) for k in changed) or not all(c["faults"] for c in cleared):+ verdict, reasons = "unknown", ["interpolation-fault-not-cleared"]+ else:+ verdict, reasons = "improved", ["verified-source-defect-restored"]+ return {"verdict": verdict, "reasons": reasons, "axes": axes, "cleared_faults": cleared}+++@dataclass+class Chain:+ projection: source.Projection+ key: str+ shown: list[int]+ applied: list[dict[str, Any]]++ def targets(self, frames: list[Image.Image]) -> list[int]:+ return proposals(frames, self.projection, self.shown, [e["target"] for e in self.applied])+++def chain(origin: Loop, current: Loop, src: source.Source) -> tuple[Chain | None, str | None]:+ """Rebuild the current baseline from the origin and the source.++ The origin's own normal cells prove the projection. Each applied cell is made+ again from the origin and the source, in order, as a proposal of its prefix+ that passes the protections there; the pixels read from the current baseline+ must then be the rebuilt ones. A receipt the inputs do not reproduce is an error.+ """+ if "restoration" in origin.source_report:+ raise ValueError("origin carries a restoration receipt: supply the five files the first restoration started from")+ receipt = current.source_report.get("restoration")+ if receipt is None and current.artifacts != origin.artifacts:+ raise ValueError("current baseline differs from the origin and carries no restoration receipt")+ if receipt is not None:+ if not isinstance(receipt, dict):+ raise ValueError("malformed restoration receipt")+ if (receipt.get("metric_version"), receipt.get("policy_version")) != (METRIC, POLICY):+ return None, "restoration-receipt-policy-unsupported"+ if receipt.get("origin_artifacts") != origin.artifacts or receipt.get("source_artifacts") != src.artifacts:+ raise ValueError("restoration receipt names another origin or source")+ projection, issue = source.project(origin, src)+ if issue:+ return None, issue+ assert projection is not None+ key = _source_key(src)+ if key is None:+ return None, "source-key-colour-unverified"+ schedule = playback.mapping(origin)+ if schedule is None:+ return None, "playback-schedule-unverified"+ state = Chain(projection, key, schedule[0], [])+ if receipt is None:+ return state, None+ applied = receipt.get("applied")+ if not isinstance(applied, list) or not applied or any(not isinstance(e, dict) for e in applied):+ raise ValueError("restoration receipt lists no applied cell")+ if (current.artifacts["meta"] != origin.artifacts["meta"]+ or {k: v for k, v in current.source_report.items() if k != "restoration"} != origin.source_report):+ raise ValueError("current baseline metadata or report differs from the origin outside its restoration receipt")+ frames = list(origin.frames)+ for step, entry in enumerate(applied):+ target = entry.get("target")+ if type(target) is not int or target not in state.targets(frames):+ raise ValueError("an applied restoration was not a proposal of its prefix")+ previous = entry.get("baseline_artifacts")+ if not isinstance(previous, dict) or (step == 0 and previous != origin.artifacts):+ raise ValueError("an applied restoration names another baseline than its prefix")+ part = partial(origin.frames[target], projection.frames[target], key)+ after = [part.frame if k == target else f for k, f in enumerate(frames)]+ if (part.alpha_conflict or _portable(entry) != _portable(_entry(target, part, origin, previous, frames, src, projection))+ or judge(frames, after, projection.frames, key)["verdict"] != "improved"):+ raise ValueError("an applied restoration is not reproduced by the origin, the source and the protections")+ state.applied.append(entry)+ frames = after+ if _portable(receipt) != _portable(_receipt(origin, src, projection, state.applied)):+ raise ValueError("restoration receipt differs from the one the origin and the source reproduce")+ if any(a.tobytes() != b.tobytes() for a, b in zip(frames, current.frames)):+ raise ValueError("current baseline pixels differ from the origin rebuilt with its restoration receipt")+ return state, None+++def _base(origin: Loop, baseline: Loop, candidate: Loop, src: source.Source) -> dict[str, Any]:+ return {"kind": COMPARISON_KIND, "schema_version": COMPARISON_SCHEMA, "metric_version": METRIC,+ "policy_version": POLICY, "scope": SCOPE, "operation": OPERATION,+ "measurement_engine": evidence.engine_identity(), "origin": origin.describe(),"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"]}+ "a restored cell is the source's pixel or the origin's at each place, never the whole source drawing",+ "source and origin receipts bind supplied bytes; they are not signatures of the original producer"]}-def compare(baseline: Loop, candidate: Loop, src: source.Source, *,+def compare(origin: Loop, 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)+ result = _base(origin, 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+ if ((repair_evidence.get("kind"), repair_evidence.get("schema_version"), repair_evidence.get("metric_version"),+ repair_evidence.get("policy_version")) != (KIND, REPAIR_SCHEMA, METRIC, POLICY)+ or repair_evidence.get("origin_artifacts") != origin.artifactsor repair_evidence.get("baseline_artifacts") != baseline.artifactsor repair_evidence.get("source_artifacts") != src.artifactsor repair_evidence.get("candidate_artifacts") != candidate.artifacts):raise ValueError("repair evidence does not bind these exact input artifacts")- projection, issue = source.project(baseline, src)+ state, issue = chain(origin, baseline, src)if issue:return finish("unknown", [issue], True)- assert projection is not None+ assert state is not None+ projection, ref = state.projection, state.projection.frames# 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"}:+ if _portable(repair_evidence.get("projection")) != _portable(projection.record):raise ValueError("repair projection evidence differs from actual source projection")+ result["provenance"] = {"applied": state.applied}a_play, issue = playback.verify(baseline, baseline_playback)if issue:return finish("unknown", ["baseline:" + issue], True)@@ -120,75 +329,45 @@ def compare(baseline: Loop, candidate: Loop, src: source.Source, *,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"])+ # The writer copies the metadata byte for byte: no cut, crop, schedule, follow or rendering change.+ if candidate.artifacts["meta"] != baseline.artifacts["meta"]:+ return finish("unknown", ["candidate-metadata-bytes-changed"])if any(a_play[k]["durations_ms"] != b_play[k]["durations_ms"] ora_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.frameschanged = [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 not changed and candidate.artifacts != baseline.artifacts:+ return finish("unknown", ["unchanged-pixels-with-changed-artifacts"])if changed:- if len(changed) != 1 or changed[0] not in allowed:+ if len(changed) != 1 or changed[0] not in state.targets(baseline.frames):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):+ part = partial(origin.frames[target], ref[target], state.key)+ entry = _entry(target, part, origin, baseline.artifacts, baseline.frames, src, projection)+ if repair_evidence.get("proposal_id") != entry["proposal_id"] 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["restoration"] = {"target": target, "proposal_id": entry["proposal_id"],+ **_describe(part, origin.frames[target], ref[target], state.key)}+ if part.alpha_conflict:+ return finish("unknown", ["protected-pixel-alpha-conflict"])+ if candidate.frames[target].tobytes() != part.frame.tobytes():+ return finish("regressed", ["changed-cell-is-not-the-verified-source-copy"])+ receipt = _receipt(origin, src, projection, [*state.applied, entry])+ if _portable(candidate.source_report) != _portable({**baseline.source_report, "restoration": receipt}):+ return finish("unknown", ["candidate-report-differs-from-verified-receipt"])+ measured = judge(baseline.frames, candidate.frames, ref, state.key)+ result["axes"] = {**measured["axes"], "seam": {+ "status": "non_regressing", "reason": "strip-and-playback-boundary-cells-and-durations-exact"}}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"])+ result["cleared_faults"] = measured["cleared_faults"]+ return finish(measured["verdict"], measured["reasons"])-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]:+def _write_candidate(paths: dict[str, Path], out: Path, name: str, baseline: Loop, target: int | None,+ frame: Image.Image | None, receipt: dict[str, Any] | None) -> dict[str, Path]:from sprite_gen.video.loop import write_webpfrom sprite_gen.util.gif_utils import save_clean_gifif out.exists():@@ -205,23 +384,15 @@ def _write_candidate(paths: dict[str, Path], out: Path, name: str, baseline: Looshutil.copyfile(paths[key], stage / filename)else:frames = list(baseline.frames)- frames[target] = projection.frames[target]+ frames[target] = framew, h = frames[0].sizestrip = Image.new("RGBA", (w * len(frames), h))- for k, frame in enumerate(frames):- strip.paste(frame, (k * w, 0))+ for k, cell in enumerate(frames):+ strip.paste(cell, (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]+ # The loop report stays the origin's own record; only the receipt is added.+ report = {**baseline.source_report, "restoration": receipt}(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]@@ -235,43 +406,55 @@ def _write_candidate(paths: dict[str, Path], out: Path, name: str, baseline: Looreturn {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]:+def restore(paths: dict[str, Path], origin_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,+ origin, _ = read_loop(origin_paths)+ result = {"kind": KIND, "schema_version": REPAIR_SCHEMA, "metric_version": METRIC, "policy_version": POLICY,+ "scope": SCOPE, "operation": OPERATION, "measurement_engine": evidence.engine_identity(),+ "origin_artifacts": origin.artifacts, "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)+ state, issue = chain(origin, 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))+ assert state is not None+ projection = state.projection+ targets = state.targets(baseline.frames)+ result.update(projection=projection.record, proposals_available=len(targets),+ applied_cells=[e["target"] for e in state.applied])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)+ result.update(target=target, proposal_id=None, common_failure=False, reasons=[], status="no_change")+ frame = receipt = None+ if target is not None:+ part = partial(origin.frames[target], projection.frames[target], state.key)+ entry = _entry(target, part, origin, baseline.artifacts, baseline.frames, src, projection)+ result.update(proposal_id=entry["proposal_id"], status="candidate",+ partial=_describe(part, origin.frames[target], projection.frames[target], state.key))+ if part.alpha_conflict or not part.copied.any():+ return {**result, "status": "unknown", "reasons": [+ "protected-pixel-alpha-conflict" if part.alpha_conflict else "no-unprotected-source-pixel"]}+ frame, receipt = part.frame, _receipt(origin, src, projection, [*state.applied, entry])+ outputs = _write_candidate(paths, out_dir, name, baseline, target, frame, receipt)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,+ result["comparison"] = compare(origin, baseline, candidate, src, baseline_playback=animations,candidate_playback=candidate_animations, repair_evidence=result)return resultdef add_arguments(parser: argparse.ArgumentParser) -> None:- for key in ARTIFACTS:- parser.add_argument("--baseline-" + key, type=Path, required=True)+ for side in ("baseline", "origin"):+ for key in ARTIFACTS:+ parser.add_argument(f"--{side}-{key}", type=Path, required=True)source.add_inputs(parser)parser.add_argument("--out-dir", type=Path, required=True)parser.add_argument("--name", default="loop")@@ -282,15 +465,15 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:def run(**kwargs: Any) -> int:try:inputs = source.input_paths(kwargs)- paths = {k: Path(kwargs["baseline_" + k]) for k in ARTIFACTS}+ paths, origin = ({k: Path(kwargs[f"{side}_{k}"]) for k in ARTIFACTS} for side in ("baseline", "origin"))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 = [*paths.values(), *origin.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,+ payload = restore(paths, origin, 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"diff --git a/sprite_gen/video/source.py b/sprite_gen/video/source.pyindex 565ece8..3d7953e 100644--- a/sprite_gen/video/source.py+++ b/sprite_gen/video/source.py@@ -140,11 +140,6 @@ class Projection: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@@ -193,13 +188,6 @@ def project(baseline: Any, source: Source) -> tuple[Projection | None, str | Nonif (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]:diff --git a/tests/video/test_source_restoration.py b/tests/video/test_source_restoration.pyindex c317dde..21c993a 100644--- a/tests/video/test_source_restoration.py+++ b/tests/video/test_source_restoration.py@@ -1,9 +1,8 @@# SPDX-License-Identifier: Apache-2.0-"""Source-backed acceptance: actual bytes, fixed source time, and final exports.+"""Source-backed acceptance: actual bytes, an immutable origin, fixed source time, final exports.These are synthetic contract fixtures, not a production repair success claim."""-import copyimport jsonimport shutilimport subprocess@@ -17,11 +16,14 @@ from sprite_gen.cli import mainfrom sprite_gen.util.gif_utils import save_clean_giffrom sprite_gen.video.compare import Loop+W, H, N = 64, 80, 12+FILL = (210, 160, 110, 255)+def frames():result = []- for k in range(12):- im = Image.new('RGBA', (64, 80))+ for k in range(N):+ im = Image.new('RGBA', (W, H))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)@@ -39,7 +41,7 @@ def damage(im):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))+ made.putpixel((x,y),FILL)return made@@ -48,6 +50,23 @@ def exports(paths, fs, delay=42):loop.write_webp(fs, paths['webp'], delay_ms=delay, workdir=paths['webp'].parent/'webp-temp')+def cleaned(frame):+ # The loop cleanup is part of the recorded recipe.+ from sprite_gen.video.frames import drop_specks+ c=frame.copy(); loop._scrub(c)+ return drop_specks(c,alpha_over=16,diagonal=False,apart=0)[0]+++def write_strip(paths, fs):+ sheet=Image.new('RGBA',(N*W,H))+ for k,f in enumerate(fs): sheet.paste(f,(W*k,0))+ sheet.save(paths['strip']); exports(paths,fs)+++def cells(paths):+ return restoration.read_loop(paths)[0].frames++@pytest.fixturedef case(tmp_path):if not shutil.which('ffmpeg') or not loop.img2webp_supports_exact():@@ -65,12 +84,7 @@ def case(tmp_path):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']=mp4manifest.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])+ clean=[cleaned(f) for f in fs]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'}@@ -78,34 +92,55 @@ def case(tmp_path):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)+ write_strip(paths,bad)return paths, inputs, clean-def repair(case,tmp_path,index=1):+def repair(case,tmp_path,index=1,*,baseline=None,origin=None,out=None):paths,inputs,_=case- return restoration.restore(paths,source.Source.read(**inputs),out_dir=tmp_path/f'candidate-{index}',name='loop',proposal_index=index)+ return restoration.restore(baseline or paths,origin or paths,source.Source.read(**inputs),+ out_dir=tmp_path/(out or f'candidate-{index}'),name='loop',proposal_index=index)+++def outputs(result):+ return {k:Path(p) for k,p in result['outputs'].items()}-def compare_result(case,result):+def compare_result(case,result,*,baseline=None,origin=None,candidate=None):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)+ o,_=restoration.read_loop(origin or paths)+ a,ap=restoration.read_loop(baseline or paths)+ b,bp=restoration.read_loop(candidate or outputs(result))+ return restoration.compare(o,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):+def repaint_source(case, index, paint):+ """Change one keyed source frame and receipt the new bytes; the baseline's normal cells are untouched."""+ paths,inputs,_=case+ p=inputs['source_frames_dir']/f'frame-{index:04}.png'+ with Image.open(p) as image: frame=image.convert('RGBA')+ paint(frame); frame.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))+ return frame+++def test_source_restoration_preserves_normal_motion_and_timing(case,tmp_path):result=repair(case,tmp_path)- assert result['status']=='candidate'+ assert result['status']=='candidate' and result['schema_version']==2+ assert result['origin_artifacts']==result['baseline_artifacts']comparison=compare_result(case,result)assert comparison['verdict']=='improved', comparison['reasons']- assert comparison['metric_version']=='source-restoration-v1'+ assert (comparison['metric_version'],comparison['schema_version'])==('source-restoration-v2',3)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()+ a,b=cells(case[0]),cells(outputs(result))+ assert all(x.tobytes()==y.tobytes() for k,(x,y) in enumerate(zip(a,b)) if k!=target)+ # Nothing is protected here, so the copy is the whole source cell.+ assert result['partial']['protected']['count']==0+ assert b[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@@ -113,12 +148,22 @@ def test_exact_source_restoration_preserves_normal_motion_and_timing(case,tmp_paassert comparison['gait']=={'absolute':'unverified','source_order':'preserved'}assert comparison['playback']['baseline']['gif']['durations_ms']==[40]*12assert comparison['playback']['candidate']['webp']['durations_ms']==[42]*12+ # The loop report stays the origin's record; only the receipt is added.+ report=json.loads(outputs(result)['report'].read_bytes())+ receipt=report.pop('restoration')+ assert report==json.loads(case[0]['report'].read_bytes())+ assert outputs(result)['meta'].read_bytes()==case[0]['meta'].read_bytes()+ assert receipt['origin_artifacts']==result['origin_artifacts'] and receipt['source_artifacts']==result['source_artifacts']+ assert [e['target'] for e in receipt['applied']]==[target]+ assert receipt['applied'][0]['proposal_id']==result['proposal_id']==comparison['restoration']['proposal_id']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'+ # Proposal 2 starts from the same baseline: it does not hold proposal 1.+ assert cells(outputs(second))[first['target']].tobytes()==cells(case[0])[first['target']].tobytes()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)@@ -126,12 +171,11 @@ def test_next_independent_proposal_and_budget(case,tmp_path):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)+ write_strip(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']+ assert all(outputs(result)[k].read_bytes()==paths[k].read_bytes() for k in paths)@pytest.mark.parametrize('field',['clip','canvas','frames_report','frame','manifest','pts'])@@ -159,26 +203,25 @@ def test_missing_source_is_error_and_follow_is_shared_unknown(case,tmp_path):with pytest.raises(FileNotFoundError): source.Source.read(**inputs)[email protected]('mutation',['freeze','wrong_time','colour','alpha','duration','crop','report'])[email protected]('mutation',['freeze','wrong_time','colour','alpha','duration','crop','report','receipt'])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()}+ paths=outputs(r)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')+ elif mutation=='receipt':+ report=json.loads(paths['report'].read_bytes()); report['restoration']['applied'][0]['copied']['rle'][0]+=1+ paths['report'].write_text(json.dumps(report))else:- c,_=restoration.read_loop(paths)- fs=c.frames+ fs=cells(paths)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)+ write_strip(paths,fs)# An unchanged evidence JSON cannot authorize different final bytes.with pytest.raises(ValueError): compare_result(case,r)if mutation=='freeze':@@ -193,8 +236,7 @@ def test_tampered_final_artifacts_are_not_accepted(case,tmp_path,mutation):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()}+ paths=outputs(r)# 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')@@ -203,38 +245,182 @@ def test_actual_playback_mismatch_and_byte_hashes(case,tmp_path):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):+def cli_args(case):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))]+ baseline=[a for k,p in paths.items() for a in ('--baseline-'+k,str(p))]+ origin=[a for k,p in paths.items() for a in ('--origin-'+k,str(p))]+ return baseline,origin,[a for k,p in inputs.items() for a in ('--'+k.replace('_','-'),str(p))]+++def test_cli_real_json_needs_the_origin(case,tmp_path,capsys):+ baseline,origin,src=cli_args(case)report=tmp_path/'repair.json'- assert main(['video-loop-repair',*args,'--out-dir',str(tmp_path/'cli'),'--report',str(report)])==0+ # A request without the origin is refused: the current baseline is never taken for it.+ with pytest.raises(SystemExit):+ main(['video-loop-repair',*baseline,*src,'--out-dir',str(tmp_path/'guessed'),'--report',str(report)])+ assert not (tmp_path/'guessed').exists() and not report.exists()+ assert main(['video-loop-repair',*baseline,*origin,*src,'--out-dir',str(tmp_path/'cli'),'--report',str(report)])==0r=json.loads(report.read_bytes())+ assert (r['schema_version'],r['metric_version'])==(2,'source-restoration-v2')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+ with pytest.raises(SystemExit,match='origin'):+ main(['video-loop-compare',*baseline,*candidate,*src,'--repair-evidence',str(report),'--report',str(comparison)])+ assert not comparison.exists()+ assert main(['video-loop-compare',*baseline,*origin,*candidate,*src,'--repair-evidence',str(report),'--report',str(comparison)])==0c=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']+ assert c['verdict']=='improved' and c['schema_version']==3 and c['metric_version']=='source-restoration-v2'+ assert set(c['candidate']['artifacts'])==set(c['origin']['artifacts'])=={'strip','meta','report','gif','webp'}+ assert c['origin']['artifacts']==r['origin_artifacts']+++def test_key_spill_stays_out_and_the_rest_of_the_cell_is_restored(case,tmp_path):+ # A real source pixel can still be bad: copying it would bring key tint the delivered cell lacks.+ # Those places keep the delivered pixel; every other differing place is the source's.+ tinted=repaint_source(case,2,lambda f: ImageDraw.Draw(f).rectangle((25,25,28,28),fill=(180,205,120)))+ outcomes={r['target']:r for r in (repair(case,tmp_path,k) for k in (1,2))}+ assert {r['comparison']['verdict'] for r in outcomes.values()}=={'improved'}+ r=outcomes[2]+ assert r['partial']['protected']['count']==16 and r['partial']['alpha_equals_source']+ assert r['partial']['protected_pixels']['alpha_conflicts']==0+ assert r['partial']['protected_pixels']['pixels'][0]=={+ 'x':25,'y':25,'origin_rgba':list(FILL),'source_rgba':[180,205,120,255],+ 'origin_key_weight':0,'source_key_weight':255*(205-180-8),'alpha_equal':True}+ made,before,tinted=cells(outputs(r))[2],cells(case[0])[2],cleaned(tinted)+ for y in range(H):+ for x in range(W):+ kept=25<=x<=28 and 25<=y<=28+ assert made.getpixel((x,y))==(before if kept else tinted).getpixel((x,y))+ key=r['comparison']['axes']['key_colour']+ assert key['introduced_excess'][2]==0 and key['introduced_pixels'][2]==0 and key['tint_threshold']==8+ assert r['comparison']['cleared_faults']==[{'cell':2,'faults':['outline']}]+++def test_protected_pixel_with_other_coverage_ends_that_proposal_only(case,tmp_path):+ # The delivered cell lost its part-covered line (solid fill there); the source's line is key tinted.+ # Keeping the delivered pixel would keep coverage the source does not have, so nothing is written.+ y=14+[0,1,2,1,0,-1][2]+ repaint_source(case,2,lambda f: f.putpixel((15,y),(30,60,30,170)))+ outcomes={r['target']:r for r in (repair(case,tmp_path,k) for k in (1,2))}+ r=outcomes[2]+ assert (r['status'],r['common_failure'],r['reasons'],r['outputs'])==('unknown',False,['protected-pixel-alpha-conflict'],{})+ assert r['proposal_id'] and 'comparison' not in r and 'candidate_artifacts' not in r+ assert r['partial']['protected_pixels']=={'count':1,'alpha_conflicts':1,'listed':1,'pixels':[{+ 'x':15,'y':y,'origin_rgba':list(FILL),'source_rgba':[30,60,30,170],+ 'origin_key_weight':0,'source_key_weight':170*(60-30-8),'alpha_equal':False}]}+ assert not (tmp_path/f"candidate-{r['proposal_index']}").exists()+ # The other proposal is independent of it.+ assert outcomes[8]['comparison']['verdict']=='improved'+ assert repair(case,tmp_path,3)['status']=='exhausted'+++def test_colours_beside_the_key_hue_are_copied_and_a_key_accent_is_left(case,tmp_path):+ # Yellow, cyan, red and blue are not the green key's hue; a green accent is.+ colours={(20,20):(255,255,0),(22,20):(0,255,255),(24,20):(255,0,0),(26,20):(80,80,255),(28,20):(60,200,60)}+ def paint(f):+ for place,colour in colours.items(): f.putpixel(place,colour+(255,))+ repaint_source(case,2,paint)+ r=next(r for r in (repair(case,tmp_path,k) for k in (1,2)) if r['target']==2)+ assert r['comparison']['verdict']=='improved'+ made=cells(outputs(r))[2]+ for place,colour in colours.items():+ assert made.getpixel(place)==(FILL if colour==(60,200,60) else colour+(255,))+ assert r['partial']['protected']['count']==1+++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 the source would bring at a different one.+ # A summed colour score would allow the whole source cell.+ 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))+ fs=[strip.crop((k*64,0,(k+1)*64,80)) for k in range(12)];write_strip(paths,fs)+ for k in (2,8): repaint_source(case,k,lambda f: ImageDraw.Draw(f).rectangle((35,35,36,36),fill=(180,210,110)))+ r=repair(case,tmp_path)+ outcome=r['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 and outcome['verdict']=='improved'+ assert r['partial']['protected']['count']==4+ # The whole source cell at that time is still refused by the guard on final pixels.+ o,_=restoration.read_loop(paths)+ src=source.Source.read(**inputs)+ state,_=restoration.chain(o,o,src)+ whole=[state.projection.frames[k] if k==target else f for k,f in enumerate(o.frames)]+ judged=restoration.judge(o.frames,whole,state.projection.frames,state.key)+ assert sum(f for f in judged['axes']['key_colour']['candidate'])<sum(judged['axes']['key_colour']['baseline'])+ assert judged['axes']['key_colour']['introduced_pixels'][target]==4+ assert judged['verdict']=='regressed' and 'key_colour:regressed' in judged['reasons']+ # Written out as a candidate, it is not the verified copy either.+ forged=outputs(r)+ write_strip(forged,whole)+ c,_=restoration.read_loop(forged); r['candidate_artifacts']=c.artifacts+ assert compare_result(case,r)['reasons']==['changed-cell-is-not-the-verified-source-copy']+++def test_partial_copy_formula():+ def image(pixels):+ im=Image.new('RGBA',(len(pixels),1))+ for x,pixel in enumerate(pixels): im.putpixel((x,0),pixel)+ return im+ def made(origin,reference,key='green'):+ part=restoration.partial(image(origin),image(reference),key)+ return part,[part.frame.getpixel((x,0)) for x in range(len(origin))]+ # A larger drop at one place does not pay for a rise at another.+ part,pixels=made([(100,110,100,255),(100,108,100,255)],[(100,108,100,255),(100,109,100,255)])+ assert pixels==[(100,108,100,255),(100,108,100,255)]+ assert part.copied.tolist()==[[True,False]] and part.protected.tolist()==[[False,True]] and not part.alpha_conflict+ # The same rise where the coverage also differs cannot keep the delivered pixel.+ assert made([(100,108,100,128)],[(100,109,100,255)])[0].alpha_conflict+ # The excess is weighted by coverage: more hue under less coverage can be less of it.+ origin,thin,thick=(100,120,100,255),(100,140,100,90),(100,140,100,100)+ assert made([origin],[thin])[1]==[thin]+ assert made([origin],[thick])[0].alpha_conflict+ # A colour under zero coverage has no excess on either side; the pixel is copied whole.+ hidden=(0,255,0,0)+ assert made([hidden],[(90,80,70,255)])[1]==[(90,80,70,255)]+ assert made([(90,80,70,255)],[hidden])[1]==[hidden]+ # Magenta's hue is min(R, B) - G; green's is G - max(R, B).+ accent=(200,60,200,255)+ assert made([FILL],[accent],'magenta')[1]==[FILL]+ assert made([FILL],[accent],'green')[1]==[accent]+++def recolour_outline(colour):+ def paint(f):+ for y in range(8,58):+ for x in range(W):+ if f.getpixel((x,y))[:3]==(20,20,20): f.putpixel((x,y),colour)+ return paint+++def test_protected_outline_leaves_the_fault_and_is_not_adopted(case,tmp_path):+ # The source's outline is dark and key tinted: every outline pixel is protected, with the same coverage.+ # The copy then restores too little to clear the fault, and nothing else makes it an improvement.+ repaint_source(case,2,recolour_outline((20,40,20,255)))+ outcomes={r['target']:r for r in (repair(case,tmp_path,k) for k in (1,2))}+ r=outcomes[2]+ assert r['status']=='candidate' and r['partial']['alpha_equals_source'] and r['partial']['protected']['count']>100+ assert (r['comparison']['verdict'],r['comparison']['reasons'])==('unknown',['interpolation-fault-not-cleared'])+ assert r['comparison']['axes']['key_colour']['introduced_pixels'][2]==0+ assert outcomes[8]['comparison']['verdict']=='improved'+++def test_source_cell_with_its_own_fault_is_not_proposed(case,tmp_path):+ repaint_source(case,2,recolour_outline(FILL))+ first=repair(case,tmp_path,1)+ assert (first['target'],first['proposals_available'])==(8,1)+ assert repair(case,tmp_path,2)['status']=='exhausted'+++def test_source_that_does_not_reproduce_the_normal_cells_is_shared_unknown(case,tmp_path):+ # Another extraction of the same clip is another source unless every normal cell is reproduced exactly.+ repaint_source(case,5,lambda f: f.putpixel((30,40),(200,150,100,255)))+ r=repair(case,tmp_path)+ assert (r['status'],r['common_failure'],r['reasons'],r['outputs'])==(+ 'unknown',True,['legacy-source-correspondence-unverified'],{})+ assert not (tmp_path/'candidate-1').exists()def test_missing_legacy_recipe_is_shared_unknown(case,tmp_path):@@ -255,17 +441,16 @@ def test_native_before_repair_receipt_is_checked(case,tmp_path):assert repair(case,tmp_path)['comparison']['verdict']=='improved'r['source_projection']['before_repair_pixels_sha256'][2]='a'*64paths['report'].write_text(json.dumps(r))- result=restoration.restore(paths,source.Source.read(**case[1]),out_dir=tmp_path/'rejected',name='loop')+ result=repair(case,tmp_path,out='rejected')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))]+ paths,_,_=case+ baseline,origin,src=cli_args(case)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'])])+ main(['video-loop-repair',*baseline,*origin,*src,'--out-dir',str(tmp_path/'unsafe'),'--report',str(paths['meta'])])assert paths['meta'].read_bytes()==old and not (tmp_path/'unsafe').exists()@@ -286,20 +471,140 @@ def test_legacy_ambiguous_projection_cannot_choose_one_crop():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']+def adopted(case,tmp_path):+ """A first request whose restored cell keeps protected pixels, adopted as the next baseline."""+ repaint_source(case,2,lambda f: ImageDraw.Draw(f).rectangle((25,25,28,28),fill=(180,205,120)))+ origin=case[0]+ first=next(r for r in (repair(case,tmp_path,k) for k in (1,2)) if r['target']==2)+ assert first['comparison']['verdict']=='improved' and first['partial']['protected']['count']==16+ return origin,first,outputs(first)+++def test_later_request_rebuilds_the_new_baseline_from_the_origin(case,tmp_path,adopted):+ origin,first,current=adopted+ # The restored cell is not the source's whole cell, and is still verified: it is rebuilt from the origin.+ second=repair(case,tmp_path,baseline=current,origin=origin,out='next-request')+ assert second['comparison']['verdict']=='improved', second['comparison']['reasons']+ assert (second['target'],second['applied_cells'])==(8,[2])assert second['baseline_artifacts']==first['candidate_artifacts']+ assert second['origin_artifacts']==first['origin_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 second['comparison']['preservation']['changed_cells']==[8]+ assert [e['target'] for e in second['comparison']['provenance']['applied']]==[2]+ receipt=json.loads(outputs(second)['report'].read_bytes())['restoration']+ assert [e['target'] for e in receipt['applied']]==[2,8]+ assert receipt['applied'][0]==json.loads(current['report'].read_bytes())['restoration']['applied'][0]+ assert receipt['applied'][1]['baseline_artifacts']==first['candidate_artifacts']+ # A separate comparison of the final files agrees with the preview.+ assert compare_result(case,second,baseline=current,origin=origin)['verdict']=='improved'+ # Once all supported damage has been restored, the next request copies its baseline.+ final=outputs(second)+ third=repair(case,tmp_path,baseline=final,origin=origin,out='all-restored')assert third['status']=='no_change' and third['comparison']['verdict']=='non_regressing'+ assert third['applied_cells']==[2,8] and third['target'] is None+ assert all(outputs(third)[k].read_bytes()==final[k].read_bytes() for k in final)+++def rewrite_receipt(current, change):+ report=json.loads(current['report'].read_bytes()); change(report); current['report'].write_text(json.dumps(report))+++def repaint_cell(current, index, place, colour):+ fs=cells(current); fs[index].putpixel(place,colour); write_strip(current,fs)+++REBUILT='not reproduced by the origin'; PIXELS='pixels differ from the origin rebuilt'; PREFIX='not a proposal of its prefix'+OUTSIDE='differs from the origin outside its restoration receipt'++[email protected]('tamper,refusal',[+ ('mask_run',REBUILT),('mask_digest',REBUILT),('output_digest',REBUILT),+ ('restored_pixel',PIXELS),('protected_pixel',PIXELS),('normal_pixel',PIXELS),+ ('list_emptied','lists no applied cell'),('receipt_removed','carries no restoration receipt'),+ ('duplicate',PREFIX),('out_of_range',PREFIX),('first_baseline','another baseline than its prefix'),+ ('extra_field','differs from the one the origin and the source reproduce'),+ ('meta_bytes',OUTSIDE),('report_field',OUTSIDE)])+def test_changed_current_baseline_or_receipt_is_error(case,tmp_path,adopted,tamper,refusal):+ origin,first,current=adopted+ entry=lambda report: report['restoration']['applied'][0]+ if tamper=='mask_run': rewrite_receipt(current,lambda r: entry(r)['copied']['rle'].__setitem__(0,entry(r)['copied']['rle'][0]+1))+ elif tamper=='mask_digest': rewrite_receipt(current,lambda r: entry(r)['protected'].update(sha256='0'*64))+ elif tamper=='output_digest': rewrite_receipt(current,lambda r: entry(r).update(output_rgba_sha256='0'*64))+ elif tamper=='restored_pixel': repaint_cell(current,2,(30,40),(200,150,100,255))+ # One protected place quietly given the source's pixel: fewer protected pixels than the origin allows.+ elif tamper=='protected_pixel': repaint_cell(current,2,(25,25),(180,205,120,255))+ elif tamper=='normal_pixel': repaint_cell(current,5,(30,40),(200,150,100,255))+ elif tamper=='list_emptied': rewrite_receipt(current,lambda r: r['restoration'].update(applied=[]))+ elif tamper=='receipt_removed': rewrite_receipt(current,lambda r: r.pop('restoration'))+ elif tamper=='duplicate': rewrite_receipt(current,lambda r: r['restoration']['applied'].append(entry(r)))+ elif tamper=='out_of_range': rewrite_receipt(current,lambda r: entry(r).update(target=99))+ elif tamper=='first_baseline': rewrite_receipt(current,lambda r: entry(r)['baseline_artifacts']['strip'].update(sha256='0'*64))+ elif tamper=='extra_field': rewrite_receipt(current,lambda r: r['restoration'].update(verified=True))+ elif tamper=='meta_bytes': current['meta'].write_text(current['meta'].read_text()+'\n')+ else: rewrite_receipt(current,lambda r: r.update(producer={'implementation_sha256':'0'*64}))+ with pytest.raises(ValueError,match=refusal):+ repair(case,tmp_path,baseline=current,origin=origin,out='next-request')+ assert not (tmp_path/'next-request').exists()+++def test_replaced_origin_or_source_is_error(case,tmp_path,adopted):+ origin,first,current=adopted+ paths,inputs,_=case+ # The current baseline offered as its own origin.+ with pytest.raises(ValueError,match='origin carries a restoration receipt'):+ repair(case,tmp_path,baseline=current,origin=current,out='own-origin')+ # One origin file changed: not the origin the receipt names.+ other={k:tmp_path/('other'+p.suffix if k!='report' else 'other.loop.json') for k,p in origin.items()}+ for k,p in origin.items(): shutil.copyfile(p,other[k])+ other['meta'].write_text(other['meta'].read_text()+'\n')+ with pytest.raises(ValueError,match='another origin or source'):+ repair(case,tmp_path,baseline=current,origin=other,out='other-origin')+ # A first request must start at its origin.+ with pytest.raises(ValueError,match='carries no restoration receipt'):+ repair(case,tmp_path,baseline=other,origin=origin,out='unrelated-first')+ # Another source: one keyed frame changed and receipted again.+ p=inputs['source_frames_dir']/'frame-0005.png'+ with Image.open(p) as image: frame=image.convert('RGBA')+ frame.putpixel((30,40),(200,150,100,255)); frame.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))+ with pytest.raises(ValueError,match='another origin or source'):+ repair(case,tmp_path,baseline=current,origin=origin,out='other-source')+ assert not any((tmp_path/d).exists() for d in ('own-origin','other-origin','unrelated-first','other-source'))+++def test_other_policy_receipt_is_not_read_as_this_one(case,tmp_path,adopted):+ origin,first,current=adopted+ for change in (lambda r: r['restoration'].update(policy_version='another-policy'),+ lambda r: r.update(restoration={'operation':'restore_active_cut','metric_version':'source-restoration-v1',+ 'target':2,'restored_cells':[2]})):+ rewrite_receipt(current,change)+ result=repair(case,tmp_path,baseline=current,origin=origin,out='other-policy')+ assert (result['status'],result['common_failure'],result['reasons'],result['outputs'])==(+ 'unknown',True,['restoration-receipt-policy-unsupported'],{})+ assert not (tmp_path/'other-policy').exists()+++def test_old_proposal_cannot_be_compared_on_the_new_baseline(case,tmp_path,adopted):+ origin,first,current=adopted+ second=repair(case,tmp_path,baseline=current,origin=origin,out='next-request')+ # The first request's evidence, or its candidate, against the adopted baseline.+ with pytest.raises(ValueError,match='does not bind'):+ compare_result(case,first,baseline=current,origin=origin,candidate=outputs(second))+ with pytest.raises(ValueError,match='does not bind'):+ compare_result(case,second,baseline=case[0],origin=origin)+ # Evidence of another schema or metric is not this contract's.+ for field,value in (('schema_version',1),('metric_version','source-restoration-v1'),('policy_version','another-policy')):+ with pytest.raises(ValueError,match='does not bind'):+ compare_result(case,{**second,field:value},baseline=current,origin=origin)+ # A candidate whose receipt drops the earlier cell is not the verified one.+ forged=outputs(second)+ rewrite_receipt(forged,lambda r: r['restoration']['applied'].pop(0))+ c,_=restoration.read_loop(forged)+ outcome=compare_result(case,{**second,'candidate_artifacts':c.artifacts},baseline=current,origin=origin)+ assert (outcome['verdict'],outcome['reasons'])==('unknown',['candidate-report-differs-from-verified-receipt'])def test_low_scale_legacy_search_is_bounded():@@ -332,27 +637,3 @@ def test_video_frames_writes_a_receipt_of_the_actual_extraction(tmp_path):assert len(src.frames)==12assert 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']