feat(visible): white-core rescue for the Gemini false-positive gate

The FP gate demotes a low-gradient match, but a real FAINT sparkle also has soft
edges, so metadata-stripped faint sparkles were dropped. Keep a low-grad match
that is a strong (conf >= 0.52), bright, near-WHITE-core sparkle: a real sparkle
core is white, a clean bright corner that shape-matches (sky/sun) is colored
(_core_saturation). Recovers ~14/20 stripped faint sparkles under the DEFAULT
strict/auto (no metadata, no flag) at ~1.25% clean false-fire (baseline 0.55%);
the ~0.51-scoring bright-background FPs stay demoted (below 0.52).

A learned classifier on the same features measured WORSE than the tuned gate
(tier-1: MLP 86.7% recall vs the gate's 90.8% at equal false-fire), so the
heuristic stays; a patch-CNN with richer features is roadmapped P2 with low
expected value -- the precision/recall wall is fundamental (deep-research +
tier-1 both confirm it).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/module-internals.md

@@ -63,7 +63,7 @@ module.
 
 **Localize -> fill by policy (replaced reverse-alpha):** each mark is localized to a binary full-frame footprint mask (a `Localization`), and one shared, swappable fill inpaints that mask via `fill(image, mask, backend=...)` (delegates to `region_eraser.erase`). This replaced the old reverse-alpha removal (invert a captured alpha map, `original = (wm - a*logo)/(1-a)`, plus a thin residual inpaint) for ALL marks — gemini, doubao, jimeng, samsung, and jimeng_pill. **Why it changed:** reverse-alpha depended on a fixed captured alpha map at a fixed position, so it broke whenever a vendor moved or re-rendered its mark; and it was not color-lossless even with the right map (it amplifies 8-bit quantization and JPEG-chroma error by `1/(1-a)`), which showed up as "the color just changed, not removed" reports. Localize -> fill has a benign failure mode: a slightly-off localization just inpaints a small region near-losslessly instead of leaving a color-shifted smear. The captured alpha maps are still used to DETECT the marks and to shape the mask (gemini's footprint), but NOT for pixel recovery. Fill backends: `cv2` (classical inpaint, no deps, the floor), `migan` (MI-GAN ONNX, light, the memory-tight pick where LaMa will not fit), `lama` (big-LaMa ONNX, best quality, heavier, auto-preferred when a learned backend is available); `auto` = LaMa > MI-GAN > cv2, best available. Each `KnownMark` ties a key to {usual `location`, `in_auto` flag, a `_detect` callable → uniform `MarkDetection`, a `_mask` callable → full-frame footprint mask}; `KnownMark.remove(image, *, backend="auto", provenance=False, force=False)`. Entries today: `gemini` (bottom-right sparkle), `doubao` (bottom-right "豆包AI生成"), `jimeng` (bottom-right "★ 即梦AI"), `samsung` (bottom-**LEFT** "✦ Contenuti generati dall'AI", Samsung Galaxy AI, Italian locale), and the capture-less `jimeng_pill` (top-left "AI生成"). `detect_marks(image, *, provenance=frozenset())` scans all (strict, for the identify verdict); `remove_auto_marks(image, *, sensitivity="auto", provenance=frozenset(), backend="auto")` removes every detected mark in one pass. **Sensitivity (`auto`/`strict`/`assume_ai`)** decides how hard a borderline mark is trusted: the visual detectors are pixel-based (no metadata needed) and the recall gain comes from relaxing the false-positive gate, not from metadata. `resolve_relax` turns the policy + evidence into the per-mark relaxation boolean — `strict` never relaxes, `assume_ai` always relaxes (the caller asserts AI, e.g. a metadata-stripped screenshot; ~46% -> ~92% Gemini recall, at the cost of a small near-lossless fill on some clean corners), `auto` relaxes only on same-product evidence (metadata provenance for that vendor, or a confidently strict-detected sibling of the same `_PRODUCT_OF` — Doubao and Jimeng are both bottom-right ByteDance but distinct products, so they do NOT cross-relax). **Perception / decision / action are separated three ways** (the removal path only; `identify` keeps calling `KnownMark.detect` directly, so its verdict is untouched): `_build_candidates(image)` is PERCEPTION — it runs each detector at both trust levels and packages raw verdicts + the pill's flatness feature into `Candidate`s, no policy; `decide(candidates, Context(sensitivity, provenance)) -> [Decision]` is the pure DECISION arbiter — all keep/drop policy (`resolve_relax` cross-mark corroboration + the pill gate) in one image-free, unit-testable function (`tests/test_watermark_registry.py::TestArbiter`); then `remove_auto_marks` does the ACTION, localizing -> filling each winner. The Gemini FP gate deliberately stays inside `gemini_engine` (not the arbiter) because `identify` reads that same gated confidence — pulling it out would drift the provenance verdict. Behavior is byte-identical to the pre-arbiter two-pass (corpus-verified: strict/auto 46%, assume_ai 92% Gemini recall unchanged).
 
-**Head-to-head validation (v0.12.1 reverse-alpha vs the current localize -> fill):** run over the full labelled visible-mark set, with the cv2 / MI-GAN / LaMa fills each compared against the old reverse-alpha. **doubao and jimeng are identical** across every backend -- 100% coverage and 100% clearance either way. **gemini** strict coverage is a few points below reverse-alpha's (the deliberate false-positive tightening), but every strict-missed mark is recovered under `assume_ai`, clearance is equal (~98% both), and neither version touches pixels outside the mark box (outside-box PSNR ~99). **Clearance is fill-independent** -- cv2, MI-GAN and LaMa all strip the mark's shape equally, so the re-detect metric does not separate them; the difference is purely the *visual fill quality* on the recovered region, and it is background-dependent. reverse-alpha recovered textured and especially regular/structured backgrounds (a lattice, a grid) more cleanly than any inpaint; **LaMa closes most of that gap** (the best learned backend), **MI-GAN can ghost or hallucinate structure**, and **cv2 smears** (the last-resort floor). This is why `auto` resolves `LaMa > MI-GAN > cv2` (`preferred_inpaint_backend`) and warns once on the cv2 fallback; on flat backgrounds every backend is clean.
+**Head-to-head validation (v0.12.1 reverse-alpha vs the current localize -> fill):** run over the full labelled visible-mark set, with the cv2 / MI-GAN / LaMa fills each compared against the old reverse-alpha. **doubao and jimeng are identical** across every backend -- 100% coverage and 100% clearance either way. **gemini** strict coverage is a few points below reverse-alpha's (the deliberate false-positive tightening), but the metadata-stripped faint ones are now mostly recovered by the DEFAULT white-core rescue in the FP gate (`gemini_engine`: a bright near-WHITE core distinguishes a real faint sparkle from a colored bright corner -- ~14/20 recovered at ~1.25% clean false-fire; a learned classifier on the same features measured worse, 2026-07 tier-1), the residual under `assume_ai`; clearance is equal (~98% both), and neither version touches pixels outside the mark box (outside-box PSNR ~99). **Clearance is fill-independent** -- cv2, MI-GAN and LaMa all strip the mark's shape equally, so the re-detect metric does not separate them; the difference is purely the *visual fill quality* on the recovered region, and it is background-dependent. reverse-alpha recovered textured and especially regular/structured backgrounds (a lattice, a grid) more cleanly than any inpaint; **LaMa closes most of that gap** (the best learned backend), **MI-GAN can ghost or hallucinate structure**, and **cv2 smears** (the last-resort floor). This is why `auto` resolves `LaMa > MI-GAN > cv2` (`preferred_inpaint_backend`) and warns once on the cv2 fallback; on flat backgrounds every backend is clean.
 
 **Provenance prior:** when local metadata already confirms the vendor, the mark's detection trust gate is relaxed (a confirmed vendor means the mark is present with high prior, so a mark the conservative detector would demote as a content false positive is trusted). `detect_marks` / `remove_auto_marks` take a `provenance` frozenset and `KnownMark.remove` a `provenance` flag. Mapping: a Google/Gemini C2PA issuer relaxes gemini (skips its false-positive gate and lowers the trust threshold from 0.5 to 0.35); a China-AIGC (TC260) label relaxes doubao/jimeng; `samsung_genai` relaxes samsung. Corpus finding: on Google-C2PA images, Gemini sparkle recall rose from ~46% (plain detector) to ~90% with the provenance prior (recovering marks the vendor moved or re-rendered). The localizer is cheap CPU (cv2/numpy), so a memory-tight caller runs it anywhere; the heavy MI-GAN/LaMa fill is opt-in and chosen by the caller.
 

src/remove_ai_watermarks/gemini_engine.py

@@ -167,6 +167,21 @@ class GeminiEngine:
     # confidence >= 0.65, above the gate).
     _SPARKLE_FP_GRAD = 0.55
 
+    # White-core rescue for the gate above. A real but FAINT sparkle -- a soft white
+    # star on a bright/textured background -- has a high core-ring margin but low
+    # gradient fidelity, the SAME signature the grad gate uses to demote the smooth
+    # colored-corner FP, so faint real sparkles get demoted with it. The separator the
+    # grad gate discards is the CORE COLOR: a real Gemini sparkle core is near-WHITE
+    # (low saturation), while a clean bright corner that shape-matches (sky, sun, a warm
+    # light) is COLORED. So do NOT demote a low-grad match that already clears the trust
+    # confidence (_SPARKLE_KEEP_CONF -- the registry's 0.5 sparkle gate plus a small
+    # margin so the ~0.51 bright-background FPs the grad gate was added for stay demoted)
+    # AND has a bright (margin) near-neutral core (_core_saturation <= _SPARKLE_WHITE_SAT).
+    # Corpus-measured on metadata-stripped faint sparkles: recovers ~14/20 the low-grad
+    # demotion would drop, at ~0.8% clean false-fire vs the ~0.55% baseline.
+    _SPARKLE_KEEP_CONF = 0.52
+    _SPARKLE_WHITE_SAT = 0.20
+
     # Corner promotion (issue #36): the size weight that suppresses tiny-patch
     # false positives also buries a small, near-perfect sparkle when a larger,
     # mediocre match sits elsewhere (e.g. a bright collar in a portrait). A small
@@ -381,18 +396,26 @@ class GeminiEngine:
         # FP (low margin) AND the bright-background smooth-blob FP (high margin but low
         # gradient), which the margin check alone misses. See _SPARKLE_FP_GRAD.
         if confidence < self._SPARKLE_FP_CONF and not trust_provenance:
-            margin = self._core_ring_margin(image, self.get_interpolated_alpha(best_scale), (pos_x, pos_y))
+            alpha = self.get_interpolated_alpha(best_scale)
+            pos = (pos_x, pos_y)
+            margin = self._core_ring_margin(image, alpha, pos)
             low_margin = margin is not None and margin < self._SPARKLE_FP_MARGIN
             low_grad = grad_score < self._SPARKLE_FP_GRAD
             if low_margin or low_grad:
-                logger.debug(
-                    "Sparkle FP gate: conf=%.3f, core-ring margin=%s, grad=%.3f < %.2f; demoting.",
-                    confidence,
-                    f"{margin:.1f}" if margin is not None else "n/a",
-                    grad_score,
-                    self._SPARKLE_FP_GRAD,
-                )
-                confidence = min(confidence, 0.30)
+                # White-core rescue: a real faint sparkle clears the trust confidence,
+                # has a bright core (not low_margin), and a near-WHITE core -- unlike the
+                # colored-corner FP the low-grad demotion targets. See _SPARKLE_WHITE_SAT.
+                core_sat = self._core_saturation(image, alpha, pos)
+                white_core = not low_margin and core_sat is not None and core_sat <= self._SPARKLE_WHITE_SAT
+                if not (confidence >= self._SPARKLE_KEEP_CONF and white_core):
+                    logger.debug(
+                        "Sparkle FP gate: conf=%.3f, margin=%s, grad=%.3f, core_sat=%s; demoting.",
+                        confidence,
+                        f"{margin:.1f}" if margin is not None else "n/a",
+                        grad_score,
+                        f"{core_sat:.2f}" if core_sat is not None else "n/a",
+                    )
+                    confidence = min(confidence, 0.30)
 
         result.confidence = float(max(0.0, min(1.0, confidence)))
         result.detected = result.confidence >= 0.35
@@ -628,6 +651,35 @@ class GeminiEngine:
         cb = self._core_and_bg(image, alpha_map, position)
         return None if cb is None else cb[0] - cb[1]
 
+    def _core_saturation(
+        self,
+        image: NDArray[Any],
+        alpha_map: NDArray[Any],
+        position: tuple[int, int],
+    ) -> float | None:
+        """Median color saturation of the sparkle core (0 = white/neutral, higher =
+        colored). A real Gemini sparkle is a white star, so its core is near-neutral;
+        a clean bright corner that shape-matches (sky, sun, a warm light) is colored,
+        so a high core saturation flags the false positive the brightness/gradient
+        gates miss. Samples the same high-alpha core pixels as :meth:`_core_and_bg`.
+        None when the footprint cannot be placed or the core is empty.
+        """
+        placed = self._footprint_indices(alpha_map, position, image.shape)
+        if placed is None:
+            return None
+        alpha_roi, (y1, y2, x1, x2) = placed
+        a_cap = float(alpha_roi.max())
+        if a_cap < 0.2:
+            return None
+        core = alpha_roi >= a_cap * self._CORE_ALPHA_FRAC
+        box = image[y1:y2, x1:x2]
+        if box.shape[:2] != core.shape or not bool(core.any()):
+            return None
+        px = box[core].astype(np.float32)  # (N, 3) BGR core pixels
+        hi = px.max(axis=1)
+        lo = px.min(axis=1)
+        return float(np.median((hi - lo) / (hi + 1.0)))
+
 
 def detect_sparkle_confidence(image_path: Path, *, image: NDArray[Any] | None = None) -> float | None:
     """Visible-sparkle detection confidence for a file, for provenance use.

tests/test_gemini_engine.py

@@ -292,14 +292,15 @@ class TestSparkleFalsePositiveGate:
         assert det.confidence < 0.5
         assert not det.detected
 
-    def test_bright_background_low_gradient_match_demoted(self):
-        """Bright-background content FP (2026-06-26 landing-page reports: a snow+sky
-        photo and a white product render scored ~0.51). A bright background gives the
-        match a HIGH core-ring margin, so the margin gate cannot demote it -- but the
-        smooth blob lacks the crisp star edges of a real sparkle, so its GRADIENT NCC
-        is low. The gradient gate (``_SPARKLE_FP_GRAD``) demotes it. Reproduces the
-        regime with a heavily-blurred bright sparkle: high margin, low gradient, and a
-        pre-gate fusion above the 0.5 promote bar (so it WOULD have been detected).
+    def test_bright_white_blurred_sparkle_rescued(self):
+        """A strong, bright, WHITE blurred sparkle is now KEPT (white-core rescue). A
+        faint / re-compressed real sparkle has soft edges (low gradient) like a smooth
+        blob, but its core is bright AND near-WHITE and its fused confidence clears the
+        trust gate, so the rescue (``_SPARKLE_WHITE_SAT`` / ``_SPARKLE_KEEP_CONF``) keeps
+        it -- recovering the metadata-stripped faint sparkles the grad gate used to drop.
+        The weaker (~0.51) bright-background FPs the grad gate was added for still get
+        demoted, because they fall below ``_SPARKLE_KEEP_CONF`` (0.52); the colored-blob
+        case below is demoted on core saturation.
         """
         size = 1400
         config = get_watermark_config(size, size)
@@ -311,16 +312,28 @@ class TestSparkleFalsePositiveGate:
         img[y : y + ah, x : x + aw] = a * 255.0 + (1.0 - a) * img[y : y + ah, x : x + aw]
         img = cv2.GaussianBlur(np.clip(img, 0, 255).astype(np.uint8), (39, 39), 0)
         det = self.engine.detect_watermark(img)
-        # Pre-gate fusion clears the 0.5 promote bar (would have been detected)...
-        pre = det.spatial_score * 0.5 + det.gradient_score * 0.3 + det.variance_score * 0.2
-        assert pre > 0.5
-        # ...the OLD margin gate cannot catch it (bright background -> high margin)...
-        margin = self.engine._core_ring_margin(img, self.engine.get_interpolated_alpha(det.region[2]), det.region[:2])
-        assert margin is not None
-        assert margin >= self.engine._SPARKLE_FP_MARGIN
-        # ...but the gradient is low (smooth blob, not a crisp star)...
+        assert det.gradient_score < self.engine._SPARKLE_FP_GRAD  # soft edges, low gradient
+        assert det.confidence >= self.engine._SPARKLE_KEEP_CONF  # strong white-core match, kept
+        assert det.detected
+
+    def test_bright_colored_blob_still_demoted(self):
+        """The white-core rescue must NOT re-admit a COLORED bright-corner FP (sky, sun,
+        a warm light): its core saturation is high, so the rescue does not apply and the
+        gradient gate still demotes it. Same blurred construction as the white sparkle
+        above, but tinted -- proving the discriminator is core color, not just brightness.
+        """
+        size = 1400
+        config = get_watermark_config(size, size)
+        x, y = config.get_position(size, size)
+        alpha = self.engine.get_alpha_map(WatermarkSize.LARGE)
+        ah, aw = alpha.shape[:2]
+        img = np.full((size, size, 3), 110, dtype=np.float32)
+        a = np.clip(alpha * 1.6, 0.0, 1.0)[:, :, None]
+        color = np.array([40.0, 140.0, 235.0])  # BGR warm/orange -> saturated (non-white) core
+        img[y : y + ah, x : x + aw] = a * color + (1.0 - a) * img[y : y + ah, x : x + aw]
+        img = cv2.GaussianBlur(np.clip(img, 0, 255).astype(np.uint8), (39, 39), 0)
+        det = self.engine.detect_watermark(img)
         assert det.gradient_score < self.engine._SPARKLE_FP_GRAD
-        # ...so the gradient gate demotes it below the detection bar.
         assert det.confidence < 0.5
         assert not det.detected