Skip to content

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

feat(video): restore 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.md
index 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. New
extractions 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.webp
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.
+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 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.
+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 integer
body 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 not
accepted. 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:
```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 \
+ --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` 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.
+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 unused
proposal 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. 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.
+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.py
index 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 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")
+ # 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.py
index 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 source
bridge 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 annotations
import argparse
-import copy
import json
import shutil
import tempfile
+from dataclasses import dataclass
from pathlib import Path
from typing import Any
@@ -25,12 +31,20 @@ 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"
+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 = 3
MAX_PROPOSALS = 3
ARTIFACTS = ("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_TINT
def 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[di
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)
+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.artifacts
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)
+ 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"] 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 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_webp
from sprite_gen.util.gif_utils import save_clean_gif
if out.exists():
@@ -205,23 +384,15 @@ def _write_candidate(paths: dict[str, Path], out: Path, name: str, baseline: Loo
shutil.copyfile(paths[key], stage / filename)
else:
frames = list(baseline.frames)
- frames[target] = projection.frames[target]
+ frames[target] = frame
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))
+ 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: Loo
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]:
+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 result
def 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.py
index 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 | Non
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]:
diff --git a/tests/video/test_source_restoration.py b/tests/video/test_source_restoration.py
index 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 copy
import json
import shutil
import subprocess
@@ -17,11 +16,14 @@ from sprite_gen.cli import main
from sprite_gen.util.gif_utils import save_clean_gif
from 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.fixture
def 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']=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])
+ 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_pa
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
+ # 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)])==0
r=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)])==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']
+ 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'*64
paths['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)==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']