Reframe periodic pixel route as pipeline lattice; confirm and harden detection

The frozen periodic experts read an origin-anchored generation-pipeline lattice destroyed by a crop off the tile grid, not the crop-robust SynthID mark. Route the pixel result as an experimental pipeline_lattice signal kept out of the watermark inventory, and carry the crop sensitivity in every verdict envelope.

Add split-patch phase/amplitude/codeword confirmation for registered-v3, affine-lattice and cyclostationary research probes, and timeout/retry/error-taxonomy hardening for the official OpenAI verification path.

src/remove_ai_watermarks/__init__.py

@@ -40,6 +40,7 @@ __all__ = [
     "BatchSummary",
     "InvisibleOptions",
     "MetadataStripIncomplete",
+    "OpenAIProvenanceError",
     "OpenAISynthIDDetection",
     "RemoveAllResult",
     "SynthIDDetection",
@@ -70,7 +71,11 @@ if TYPE_CHECKING:
         remove_visible,
         visible_provenance,
     )
-    from remove_ai_watermarks.openai_provenance import OpenAISynthIDDetection, verify_openai_synthid
+    from remove_ai_watermarks.openai_provenance import (
+        OpenAIProvenanceError,
+        OpenAISynthIDDetection,
+        verify_openai_synthid,
+    )
     from remove_ai_watermarks.synthid_detector import SynthIDDetection, detect_synthid
     from remove_ai_watermarks.video import (
         identify_video,
@@ -115,7 +120,7 @@ def __getattr__(name: str) -> object:
         from remove_ai_watermarks import synthid_detector
 
         return getattr(synthid_detector, name)
-    if name in ("OpenAISynthIDDetection", "verify_openai_synthid"):
+    if name in ("OpenAIProvenanceError", "OpenAISynthIDDetection", "verify_openai_synthid"):
         from remove_ai_watermarks import openai_provenance
 
         return getattr(openai_provenance, name)

src/remove_ai_watermarks/_synthid_confirmation.py

@@ -0,0 +1,288 @@
+"""Independent split-patch confirmation for the registered SynthID carrier."""
+
+# The optional numeric libraries do not provide complete types for this path.
+# pyright: reportMissingTypeStubs=false, reportUnknownMemberType=false, reportUnknownVariableType=false, reportUnknownArgumentType=false
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+import cv2
+import numpy as np
+
+from remove_ai_watermarks.synthid_detector import fold_residual_template, unit_tile
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+MIN_PERIOD = 10.0
+MIN_COHERENCE = 0.30
+MIN_AMPLITUDE = 0.0
+H5_PERIOD = (18.0, 18.6)
+H5_MIN = 0.13
+STRONG_COHERENCE_PERIOD = (18.6, 20.0)
+STRONG_COHERENCE_MIN = 0.40
+WEAK_H5_PERIOD = (20.0, 22.0)
+WEAK_H5_MIN = 0.02
+PATCH_SIZE = 256
+GRID_SIZE = 4
+HARMONIC_COUNT = 16
+
+
+@dataclass(frozen=True)
+class RegisteredConfirmationComponents:
+    """Auditable split-patch confirmation components for one fixed period."""
+
+    period: float
+    joint_coherence: float
+    joint_amplitude: float
+    unknown_codeword_fixed_confirmation: float
+    selection_patches: int
+    confirmation_patches: int
+
+    @property
+    def passes(self) -> bool:
+        """Whether every frozen period-aware confirmation gate passes."""
+        return registered_confirmation_passes(
+            self.period,
+            self.joint_coherence,
+            self.joint_amplitude,
+            self.unknown_codeword_fixed_confirmation,
+        )
+
+
+def registered_confirmation_passes(
+    period: float,
+    joint_coherence: float,
+    joint_amplitude: float,
+    unknown_codeword_fixed_confirmation: float,
+) -> bool:
+    """Apply the single frozen registered-carrier confirmation rule."""
+    if period < MIN_PERIOD:
+        return False
+    if joint_coherence < MIN_COHERENCE or joint_amplitude < MIN_AMPLITUDE:
+        return False
+    if H5_PERIOD[0] <= period < H5_PERIOD[1]:
+        return unknown_codeword_fixed_confirmation >= H5_MIN
+    if STRONG_COHERENCE_PERIOD[0] <= period < STRONG_COHERENCE_PERIOD[1]:
+        return joint_coherence >= STRONG_COHERENCE_MIN
+    if WEAK_H5_PERIOD[0] <= period < WEAK_H5_PERIOD[1]:
+        return unknown_codeword_fixed_confirmation >= WEAK_H5_MIN
+    return True
+
+
+def _opponent_channels(values: NDArray[Any]) -> NDArray[Any]:
+    red = values[:, :, 0]
+    green = values[:, :, 1]
+    blue = values[:, :, 2]
+    return np.stack((green, red - green, blue - 0.5 * (red + green)), axis=2)
+
+
+def _template_harmonics(template: NDArray[Any]) -> tuple[NDArray[Any], NDArray[Any]]:
+    opponent = _opponent_channels(np.asarray(template, dtype=np.float64))
+    spectrum = np.fft.fft2(opponent, axes=(0, 1))
+    height, width = template.shape[:2]
+    candidates: list[tuple[float, int, int]] = []
+    for row in range(height):
+        signed_row = row if row <= height // 2 else row - height
+        for column in range(width):
+            signed_column = column if column <= width // 2 else column - width
+            if signed_row < 0 or (signed_row == 0 and signed_column <= 0):
+                continue
+            power = float(np.sum(np.abs(spectrum[row, column]) ** 2))
+            candidates.append((power, signed_row, signed_column))
+    candidates.sort(reverse=True)
+    selected = candidates[:HARMONIC_COUNT]
+    harmonics = np.asarray([(row, column) for _power, row, column in selected], dtype=np.float64)
+    coefficients = np.asarray([spectrum[int(row) % height, int(column) % width] for row, column in harmonics])
+    weights = np.abs(coefficients)
+    weight_sum = float(np.sum(weights))
+    if weight_sum <= 0.0:
+        raise ValueError("template has no nonzero periodic harmonics")
+    return harmonics, weights / weight_sum
+
+
+def _patch_origins(height: int, width: int) -> list[tuple[int, int, int]]:
+    if height < PATCH_SIZE or width < PATCH_SIZE:
+        raise ValueError("registered confirmation needs both image sides to be at least 256 pixels")
+    y_values = np.linspace(0, height - PATCH_SIZE, min(GRID_SIZE, height // PATCH_SIZE), dtype=np.int64)
+    x_values = np.linspace(0, width - PATCH_SIZE, min(GRID_SIZE, width // PATCH_SIZE), dtype=np.int64)
+    origins = [
+        (int(y), int(x), (y_index + x_index) % 2)
+        for y_index, y in enumerate(np.unique(y_values))
+        for x_index, x in enumerate(np.unique(x_values))
+    ]
+    if {group for _y, _x, group in origins} != {0, 1}:
+        raise ValueError("registered confirmation needs two independent patch groups")
+    return origins
+
+
+def _bilinear_sample(spectrum: NDArray[Any], y: NDArray[Any], x: NDArray[Any]) -> NDArray[Any]:
+    height, width = spectrum.shape
+    y_floor = np.floor(y)
+    x_floor = np.floor(x)
+    y0 = y_floor.astype(np.int64) % height
+    x0 = x_floor.astype(np.int64) % width
+    y1 = (y0 + 1) % height
+    x1 = (x0 + 1) % width
+    dy = y - y_floor
+    dx = x - x_floor
+    return (
+        spectrum[y0, x0] * (1.0 - dy) * (1.0 - dx)
+        + spectrum[y1, x0] * dy * (1.0 - dx)
+        + spectrum[y0, x1] * (1.0 - dy) * dx
+        + spectrum[y1, x1] * dy * dx
+    )
+
+
+def _patch_unit_values(
+    pixels: NDArray[Any],
+    origin_y: int,
+    origin_x: int,
+    period: float,
+    harmonics: NDArray[Any],
+    denoise_sigma: float,
+) -> NDArray[Any]:
+    patch = np.asarray(
+        pixels[origin_y : origin_y + PATCH_SIZE, origin_x : origin_x + PATCH_SIZE],
+        dtype=np.float32,
+    )
+    channels = _opponent_channels(patch)
+    window_1d = np.hanning(PATCH_SIZE).astype(np.float32)
+    window = window_1d[:, None] * window_1d[None, :]
+    frequencies_y = harmonics[:, 0] / period
+    frequencies_x = harmonics[:, 1] / period
+    sample_y = frequencies_y * PATCH_SIZE
+    sample_x = frequencies_x * PATCH_SIZE
+    sampled = np.empty((len(harmonics), 3), dtype=np.complex128)
+    for channel in range(3):
+        residual = channels[:, :, channel]
+        residual -= cv2.GaussianBlur(
+            residual,
+            (0, 0),
+            sigmaX=denoise_sigma,
+            sigmaY=denoise_sigma,
+            borderType=cv2.BORDER_REFLECT_101,
+        )
+        sampled[:, channel] = _bilinear_sample(np.fft.fft2(residual * window), sample_y, sample_x)
+    sampled *= np.exp(-2j * math.pi * (frequencies_y * origin_y + frequencies_x * origin_x))[:, None]
+    magnitudes = np.abs(sampled)
+    return np.divide(sampled, magnitudes, out=np.zeros_like(sampled), where=magnitudes > 1e-12)
+
+
+def _coherence(values: list[NDArray[Any]], weights: NDArray[Any]) -> float:
+    coherence = np.abs(np.mean(np.stack(values), axis=0))
+    return float(np.sum(coherence * weights))
+
+
+def _unknown_codeword_fixed_confirmation(
+    selection_values: list[NDArray[Any]],
+    confirmation_values: list[NDArray[Any]],
+    weights: NDArray[Any],
+) -> float:
+    cross_codeword = np.mean(np.stack(confirmation_values), axis=0) * np.conj(
+        np.mean(np.stack(selection_values), axis=0)
+    )
+    confirmation_mask = np.arange(len(weights)) % 2 == 1
+    masked_weights = weights[confirmation_mask]
+    return float(np.abs(np.sum(cross_codeword[confirmation_mask] * masked_weights)) / np.sum(masked_weights))
+
+
+def _canonical_pixels(pixels: NDArray[Any], template: NDArray[Any], period: float) -> NDArray[Any]:
+    width = max(template.shape[1], round(pixels.shape[1] * template.shape[1] / period))
+    height = max(template.shape[0], round(pixels.shape[0] * template.shape[0] / period))
+    if (height, width) == pixels.shape[:2]:
+        return pixels
+    interpolation = cv2.INTER_AREA if width < pixels.shape[1] else cv2.INTER_CUBIC
+    return np.asarray(cv2.resize(pixels, (width, height), interpolation=interpolation))
+
+
+def _cyclic_correlations(template: NDArray[Any], tile: NDArray[Any]) -> NDArray[Any]:
+    template_spectrum = np.fft.fft2(template, axes=(0, 1))
+    tile_spectrum = np.fft.fft2(tile, axes=(0, 1))
+    return np.fft.ifft2(np.sum(template_spectrum * np.conj(tile_spectrum), axis=2)).real
+
+
+def _joint_amplitude(
+    pixels: NDArray[Any],
+    template: NDArray[Any],
+    period: float,
+    denoise_sigma: float,
+) -> tuple[float, int, int]:
+    canonical = _canonical_pixels(pixels, template, period)
+    tile_height, tile_width = template.shape[:2]
+    grouped_units: dict[int, list[NDArray[Any]]] = {0: [], 1: []}
+    origins = _patch_origins(*canonical.shape[:2])
+    for origin_y, origin_x, group in origins:
+        aligned_y = (origin_y // tile_height) * tile_height
+        aligned_x = (origin_x // tile_width) * tile_width
+        folded = fold_residual_template(
+            canonical[aligned_y : aligned_y + PATCH_SIZE, aligned_x : aligned_x + PATCH_SIZE],
+            tile_height=tile_height,
+            tile_width=tile_width,
+            denoise_sigma=denoise_sigma,
+        )
+        unit, _norm = unit_tile(folded)
+        grouped_units[group].append(unit)
+    selection_tile, _selection_norm = unit_tile(np.mean(grouped_units[0], axis=0))
+    confirmation_tile, _confirmation_norm = unit_tile(np.mean(grouped_units[1], axis=0))
+    selection_correlations = _cyclic_correlations(template, selection_tile)
+    confirmation_correlations = _cyclic_correlations(template, confirmation_tile)
+    shift_y, shift_x = np.unravel_index(int(np.argmax(selection_correlations)), selection_correlations.shape)
+    return (
+        min(
+            float(selection_correlations[shift_y, shift_x]),
+            float(confirmation_correlations[shift_y, shift_x]),
+        ),
+        len(grouped_units[0]),
+        len(grouped_units[1]),
+    )
+
+
+def registered_confirmation_components(
+    pixels: NDArray[Any],
+    template: NDArray[Any],
+    period: float,
+    denoise_sigma: float,
+) -> RegisteredConfirmationComponents:
+    """Measure the frozen split-patch gates at one registered carrier period."""
+    if pixels.ndim != 3 or pixels.shape[2] != 3:
+        raise ValueError("pixels must have shape (height, width, 3)")
+    if not math.isfinite(period) or period <= 0.0:
+        raise ValueError("registered period must be finite and positive")
+    harmonics, weights = _template_harmonics(template)
+    grouped_values: dict[int, list[NDArray[Any]]] = {0: [], 1: []}
+    for origin_y, origin_x, group in _patch_origins(*pixels.shape[:2]):
+        grouped_values[group].append(
+            _patch_unit_values(
+                pixels,
+                origin_y,
+                origin_x,
+                period,
+                harmonics,
+                denoise_sigma,
+            )
+        )
+    amplitude, selection_patches, confirmation_patches = _joint_amplitude(
+        pixels,
+        template,
+        period,
+        denoise_sigma,
+    )
+    return RegisteredConfirmationComponents(
+        period=period,
+        joint_coherence=min(
+            _coherence(grouped_values[0], weights),
+            _coherence(grouped_values[1], weights),
+        ),
+        joint_amplitude=amplitude,
+        unknown_codeword_fixed_confirmation=_unknown_codeword_fixed_confirmation(
+            grouped_values[0],
+            grouped_values[1],
+            weights,
+        ),
+        selection_patches=selection_patches,
+        confirmation_patches=confirmation_patches,
+    )

src/remove_ai_watermarks/_synthid_registered.py

@@ -13,6 +13,10 @@ from typing import TYPE_CHECKING, Any
 import cv2
 import numpy as np
 
+from remove_ai_watermarks._synthid_confirmation import (
+    RegisteredConfirmationComponents,
+    registered_confirmation_components,
+)
 from remove_ai_watermarks.synthid_detector import folded_template_score
 
 if TYPE_CHECKING:
@@ -21,6 +25,9 @@ if TYPE_CHECKING:
 _PYRAMID_SCALES = (0.75, 1.0, 1.25)
 _SEARCH_PERIODS = np.linspace(5.0, 32.0, 541, dtype=np.float64)
 _CANONICAL_PERIODS = np.linspace(7.5, 24.5, 1701, dtype=np.float64)
+_OPPONENT_SEARCH_PERIODS = np.linspace(7.5, 14.5, 141, dtype=np.float64)
+_FINE_OPPONENT_COARSE_PERIODS = np.linspace(7.5, 9.0, 31, dtype=np.float64)
+_FINE_OPPONENT_PROBE_SIZE = 384
 _PERIOD_THRESHOLDS = (
     (7.5, 8.5, 0.3770629524888979),
     (8.5, 10.0, 0.25174716660523494),
@@ -33,6 +40,15 @@ _PERIOD_THRESHOLDS = (
     (22.0, 24.5, 0.3142958338390489),
 )
 REGISTERED_HIGH_BAND_THRESHOLD = 0.075
+OPPONENT_REGISTERED_MIN_PERIOD = 7.9
+OPPONENT_REGISTERED_MAX_PERIOD = 12.0
+OPPONENT_REGISTERED_CODEC_VETO_MAX_PERIOD = 8.1
+OPPONENT_REGISTERED_MAX_P8_EDGE_RATIO = 1.05
+FINE_OPPONENT_REGISTERED_MIN_PERIOD = 7.5
+FINE_OPPONENT_REGISTERED_MAX_PERIOD = 9.0
+OPPONENT_REGISTERED_FIXED_MIN = 0.16
+OPPONENT_REGISTERED_RED_GREEN_MIN = 0.60
+OPPONENT_REGISTERED_BLUE_YELLOW_MIN = 0.55
 
 
 @dataclass(frozen=True)
@@ -44,10 +60,11 @@ class RegisteredComponents:
     selected_period: float
     spectral_period: float
     high_band_score: float
+    confirmation: RegisteredConfirmationComponents | None = None
 
     @property
-    def decision_score(self) -> float:
-        """Return a statistic that reaches one only when every gate passes."""
+    def base_decision_score(self) -> float:
+        """Return the unchanged registered-v2 decision statistic."""
         if self.selected_period != self.spectral_period:
             return 0.0
         return min(
@@ -55,6 +72,62 @@ class RegisteredComponents:
             self.high_band_score / REGISTERED_HIGH_BAND_THRESHOLD,
         )
 
+    @property
+    def decision_score(self) -> float:
+        """Return the base score only after split confirmation passes."""
+        base_score = self.base_decision_score
+        if base_score < 1.0:
+            return base_score
+        if self.confirmation is None or not self.confirmation.passes:
+            return 0.0
+        return base_score
+
+
+@dataclass(frozen=True)
+class OpponentRegisteredComponents:
+    """Auditable margins for the bounded opponent-color fallback."""
+
+    selected_period: float
+    spectral_period: float
+    spectral_score: float
+    fixed_score: float
+    red_green_spatial: float
+    blue_yellow_spatial: float
+    candidate_count: int
+    red_green_p8_edge_ratio: float | None
+    blue_yellow_p8_edge_ratio: float | None
+
+    @property
+    def base_decision_score(self) -> float:
+        """Return the minimum normalized color-carrier margin."""
+        return min(
+            self.fixed_score / OPPONENT_REGISTERED_FIXED_MIN,
+            self.red_green_spatial / OPPONENT_REGISTERED_RED_GREEN_MIN,
+            self.blue_yellow_spatial / OPPONENT_REGISTERED_BLUE_YELLOW_MIN,
+        )
+
+    @property
+    def decision_score(self) -> float:
+        """Return the margin only inside the independently challenged period band."""
+        if not OPPONENT_REGISTERED_MIN_PERIOD <= self.selected_period <= OPPONENT_REGISTERED_MAX_PERIOD:
+            return 0.0
+        if self.selected_period <= OPPONENT_REGISTERED_CODEC_VETO_MAX_PERIOD:
+            ratios = (self.red_green_p8_edge_ratio, self.blue_yellow_p8_edge_ratio)
+            if any(value is None or value > OPPONENT_REGISTERED_MAX_P8_EDGE_RATIO for value in ratios):
+                return 0.0
+        return self.base_decision_score
+
+    @property
+    def fine_decision_score(self) -> float:
+        """Return the margin for the separately calibrated fine-period expert."""
+        if not FINE_OPPONENT_REGISTERED_MIN_PERIOD <= self.selected_period <= FINE_OPPONENT_REGISTERED_MAX_PERIOD:
+            return 0.0
+        if self.selected_period <= OPPONENT_REGISTERED_CODEC_VETO_MAX_PERIOD:
+            ratios = (self.red_green_p8_edge_ratio, self.blue_yellow_p8_edge_ratio)
+            if any(value is None or value > OPPONENT_REGISTERED_MAX_P8_EDGE_RATIO for value in ratios):
+                return 0.0
+        return self.base_decision_score
+
 
 def _resize(pixels: NDArray[Any], width: int, height: int) -> NDArray[Any]:
     interpolation = cv2.INTER_AREA if width < pixels.shape[1] else cv2.INTER_CUBIC
@@ -265,6 +338,256 @@ def _pyramid_locked_mean(
     return float(np.mean(locked))
 
 
+def _opponent_pair(values: NDArray[Any]) -> NDArray[Any]:
+    """Return Red-minus-Green and Blue-minus-Yellow color planes."""
+    red = values[:, :, 0]
+    green = values[:, :, 1]
+    blue = values[:, :, 2]
+    return np.stack((red - green, blue - 0.5 * (red + green)), axis=2)
+
+
+def _opponent_period_curve(
+    pixels: NDArray[Any],
+    template: NDArray[Any],
+    periods: NDArray[Any] = _OPPONENT_SEARCH_PERIODS,
+) -> NDArray[Any]:
+    """Return signed opponent-color coherence across the frozen search grid."""
+    template_opponent = _opponent_pair(np.asarray(template, dtype=np.float64))
+    template_spectrum = np.fft.fft2(template_opponent, axes=(0, 1))
+    power = np.sum(np.abs(template_spectrum) ** 2, axis=2)
+    power[0, 0] = 0.0
+    indices = np.argsort(power.ravel())[::-1][:30]
+    rows, columns = np.unravel_index(indices, power.shape)
+    height, width = template.shape[:2]
+    signed_rows = np.where(rows <= height // 2, rows, rows - height)
+    signed_columns = np.where(columns <= width // 2, columns, columns - width)
+    harmonics = np.column_stack((signed_rows, signed_columns)).astype(np.float64)
+    coefficients = template_spectrum[rows, columns]
+
+    image_height, image_width = pixels.shape[:2]
+    sample_y = periods[:, None] ** -1 * harmonics[None, :, 0] * image_height
+    sample_x = periods[:, None] ** -1 * harmonics[None, :, 1] * image_width
+    sampled = np.empty((len(periods), len(harmonics), 2), dtype=np.complex128)
+    image_opponent = _opponent_pair(np.asarray(pixels, dtype=np.float32))
+    for channel in range(2):
+        residual = image_opponent[:, :, channel]
+        residual -= cv2.GaussianBlur(
+            residual,
+            (0, 0),
+            sigmaX=1.0,
+            sigmaY=1.0,
+            borderType=cv2.BORDER_REFLECT_101,
+        )
+        sampled[:, :, channel] = _bilinear_sample(
+            np.fft.fft2(residual),
+            sample_y % image_height,
+            sample_x % image_width,
+        )
+    numerator = np.real(np.sum(np.conj(coefficients)[None, :, :] * sampled, axis=(1, 2)))
+    denominator = np.linalg.norm(coefficients) * np.linalg.norm(sampled, axis=(1, 2))
+    return np.divide(numerator, denominator, out=np.zeros_like(numerator), where=denominator > 0.0)
+
+
+def _opponent_period_candidates(scores: NDArray[Any], count: int = 3) -> list[int]:
+    """Return separated period indices in descending spectral-score order."""
+    candidates: list[int] = []
+    for index in np.argsort(scores)[::-1]:
+        period = float(_OPPONENT_SEARCH_PERIODS[index])
+        if any(abs(period - float(_OPPONENT_SEARCH_PERIODS[prior])) < 0.5 for prior in candidates):
+            continue
+        candidates.append(int(index))
+        if len(candidates) == count:
+            break
+    return candidates
+
+
+def _canonical_at_period(
+    pixels: NDArray[Any],
+    template: NDArray[Any],
+    period: float,
+) -> NDArray[Any]:
+    """Resample PIXELS so PERIOD maps to the frozen template period."""
+    width = max(template.shape[1], round(pixels.shape[1] * template.shape[1] / period))
+    height = max(template.shape[0], round(pixels.shape[0] * template.shape[0] / period))
+    if (height, width) == pixels.shape[:2]:
+        return pixels
+    return _resize(pixels, width, height)
+
+
+def _correlation(left: NDArray[Any], right: NDArray[Any]) -> float:
+    """Return the signed real cosine between equal-shaped arrays."""
+    denominator = float(np.linalg.norm(left) * np.linalg.norm(right))
+    return float(np.real(np.vdot(right, left)) / denominator) if denominator > 0.0 else 0.0
+
+
+def _period8_edge_ratio(values: NDArray[Any]) -> float:
+    """Measure native 8-pixel block edges relative to non-block phases."""
+    phase_values = np.zeros(8, dtype=np.float64)
+    for axis in (0, 1):
+        differences = np.abs(np.diff(values, axis=axis))
+        indices = np.arange(differences.shape[axis])
+        for phase in range(8):
+            selected = indices[(indices + 1) % 8 == phase]
+            phase_values[phase] += 0.5 * float(np.take(differences, selected, axis=axis).mean())
+    baseline = float(np.median(phase_values[[1, 2, 3, 5, 6, 7]]))
+    return float(phase_values[0] / baseline) if baseline > 1e-9 else math.inf
+
+
+def _period8_opponent_edge_ratios(pixels: NDArray[Any]) -> tuple[float, float]:
+    """Return codec-grid ratios for the two opponent-color planes."""
+    opponent = _opponent_pair(np.asarray(pixels, dtype=np.float32))
+    return _period8_edge_ratio(opponent[:, :, 0]), _period8_edge_ratio(opponent[:, :, 1])
+
+
+def _opponent_components_at_period(
+    pixels: NDArray[Any],
+    template: NDArray[Any],
+    sigma: float,
+    period: float,
+    *,
+    spectral_period: float,
+    spectral_score: float,
+    candidate_count: int,
+    period8_edge_ratios: tuple[float, float] | None = None,
+) -> OpponentRegisteredComponents:
+    """Measure one period without selecting it from the image being scored."""
+    canonical = _canonical_at_period(pixels, template, period)
+    fixed_score, folded = folded_template_score(canonical, template, sigma)
+    folded_opponent = _opponent_pair(folded)
+    template_opponent = _opponent_pair(template)
+    red_green_p8_edge_ratio, blue_yellow_p8_edge_ratio = period8_edge_ratios or (None, None)
+    return OpponentRegisteredComponents(
+        selected_period=period,
+        spectral_period=spectral_period,
+        spectral_score=spectral_score,
+        fixed_score=fixed_score,
+        red_green_spatial=_correlation(folded_opponent[:, :, 0], template_opponent[:, :, 0]),
+        blue_yellow_spatial=_correlation(folded_opponent[:, :, 1], template_opponent[:, :, 1]),
+        candidate_count=candidate_count,
+        red_green_p8_edge_ratio=red_green_p8_edge_ratio,
+        blue_yellow_p8_edge_ratio=blue_yellow_p8_edge_ratio,
+    )
+
+
+def opponent_registered_components(
+    pixels: NDArray[Any],
+    template: NDArray[Any],
+    sigma: float,
+) -> OpponentRegisteredComponents:
+    """Measure the bounded lossless-resize carrier in opponent-color space."""
+    curve = _opponent_period_curve(pixels, template)
+    candidate_indices = _opponent_period_candidates(curve)
+    observations: list[OpponentRegisteredComponents] = []
+    period8_edge_ratios: tuple[float, float] | None = None
+    for index in candidate_indices:
+        period = float(_OPPONENT_SEARCH_PERIODS[index])
+        if period <= OPPONENT_REGISTERED_CODEC_VETO_MAX_PERIOD and period8_edge_ratios is None:
+            period8_edge_ratios = _period8_opponent_edge_ratios(pixels)
+        observations.append(
+            _opponent_components_at_period(
+                pixels,
+                template,
+                sigma,
+                period,
+                spectral_period=float(_OPPONENT_SEARCH_PERIODS[int(np.argmax(curve))]),
+                spectral_score=float(curve[index]),
+                candidate_count=len(candidate_indices),
+                period8_edge_ratios=period8_edge_ratios,
+            )
+        )
+    if not observations:
+        raise RuntimeError("opponent-color registration produced no candidates")
+    return max(observations, key=lambda observation: observation.base_decision_score)
+
+
+def _fine_opponent_period_groups(curve: NDArray[Any]) -> list[list[float]]:
+    """Return fine period grids around separated absolute spectral peaks."""
+    centers: list[float] = []
+    for index in np.argsort(np.abs(curve))[::-1]:
+        period = float(_FINE_OPPONENT_COARSE_PERIODS[index])
+        if any(abs(period - existing) < 0.2 for existing in centers):
+            continue
+        centers.append(period)
+        if len(centers) == 3:
+            break
+    return [
+        sorted(
+            {
+                round(float(period), 2)
+                for period in np.arange(center - 0.36, center + 0.361, 0.01)
+                if FINE_OPPONENT_REGISTERED_MIN_PERIOD <= period <= FINE_OPPONENT_REGISTERED_MAX_PERIOD
+            }
+        )
+        for center in centers
+    ]
+
+
+def fine_opponent_registered_components(
+    pixels: NDArray[Any],
+    template: NDArray[Any],
+    sigma: float,
+) -> OpponentRegisteredComponents:
+    """Select and score the calibrated fine-period lossless-resize expert."""
+    curve = _opponent_period_curve(pixels, template, _FINE_OPPONENT_COARSE_PERIODS)
+    spectral_index = int(np.argmax(np.abs(curve)))
+    spectral_period = float(_FINE_OPPONENT_COARSE_PERIODS[spectral_index])
+    period_groups = _fine_opponent_period_groups(curve)
+    probe = pixels[
+        : min(_FINE_OPPONENT_PROBE_SIZE, pixels.shape[0]),
+        : min(_FINE_OPPONENT_PROBE_SIZE, pixels.shape[1]),
+    ]
+    candidate_count = sum(len(group) for group in period_groups)
+    unique_periods = sorted({period for group in period_groups for period in group})
+    probe_by_period = {
+        period: _opponent_components_at_period(
+            probe,
+            template,
+            sigma,
+            period,
+            spectral_period=spectral_period,
+            spectral_score=float(np.interp(period, _FINE_OPPONENT_COARSE_PERIODS, curve)),
+            candidate_count=candidate_count,
+        )
+        for period in unique_periods
+    }
+    probe_groups = [[probe_by_period[period] for period in group] for group in period_groups]
+    probe_observations = [observation for group in probe_groups for observation in group]
+    finalist_periods = {
+        observation.selected_period
+        for group in probe_groups
+        for observation in sorted(group, key=lambda value: value.base_decision_score, reverse=True)[:2]
+    }
+    finalist_periods.update(
+        observation.selected_period
+        for observation in sorted(
+            probe_observations,
+            key=lambda value: value.base_decision_score,
+            reverse=True,
+        )[:5]
+    )
+    period8_edge_ratios = (
+        _period8_opponent_edge_ratios(pixels)
+        if any(period <= OPPONENT_REGISTERED_CODEC_VETO_MAX_PERIOD for period in finalist_periods)
+        else None
+    )
+    observations = [
+        _opponent_components_at_period(
+            pixels,
+            template,
+            sigma,
+            period,
+            spectral_period=spectral_period,
+            spectral_score=float(np.interp(period, _FINE_OPPONENT_COARSE_PERIODS, curve)),
+            candidate_count=len(probe_observations),
+            period8_edge_ratios=period8_edge_ratios,
+        )
+        for period in sorted(finalist_periods)
+    ]
+    if not observations:
+        raise RuntimeError("fine opponent-color registration produced no candidates")
+    return max(observations, key=lambda observation: observation.base_decision_score)
+
+
 def registered_components(
     pixels: NDArray[Any],
     template: NDArray[Any],
@@ -286,13 +609,32 @@ def registered_components(
         base_curve,
     )
     raw_score = float((baseline + quadrant + pyramid) / 3.0)
-    return RegisteredComponents(
+    components = RegisteredComponents(
         raw_score=raw_score,
         amplitude_threshold=_period_threshold(selected_period),
         selected_period=selected_period,
         spectral_period=candidates[0],
         high_band_score=_high_band_score(folded, template_spectrum),
     )
+    if components.base_decision_score < 1.0:
+        return components
+    try:
+        confirmation = registered_confirmation_components(
+            pixels,
+            template,
+            selected_period,
+            sigma,
+        )
+    except ValueError:
+        return components
+    return RegisteredComponents(
+        raw_score=components.raw_score,
+        amplitude_threshold=components.amplitude_threshold,
+        selected_period=components.selected_period,
+        spectral_period=components.spectral_period,
+        high_band_score=components.high_band_score,
+        confirmation=confirmation,
+    )
 
 
 def registered_score(
@@ -302,3 +644,21 @@ def registered_score(
 ) -> float:
     """Return the calibrated registered decision statistic."""
     return registered_components(pixels, template, sigma).decision_score
+
+
+def opponent_registered_score(
+    pixels: NDArray[Any],
+    template: NDArray[Any],
+    sigma: float,
+) -> float:
+    """Return the bounded opponent-color fallback decision statistic."""
+    return opponent_registered_components(pixels, template, sigma).decision_score
+
+
+def fine_opponent_registered_score(
+    pixels: NDArray[Any],
+    template: NDArray[Any],
+    sigma: float,
+) -> float:
+    """Return the separately calibrated fine-period decision statistic."""
+    return fine_opponent_registered_components(pixels, template, sigma).fine_decision_score

src/remove_ai_watermarks/cli.py

@@ -1323,15 +1323,22 @@ def cmd_video_batch(
 @click.argument("source", type=click.Path(exists=True, dir_okay=False, path_type=Path))
 @click.option("--json", "as_json", is_flag=True, help="Emit the detector result as JSON.")
 @click.option(
-    "--register-scale",
-    is_flag=True,
-    help="Search the slower calibrated range of spatial carrier scales.",
+    "--register-scale/--fixed-period",
+    default=None,
+    help="Force registered production search or the legacy fixed-period diagnostic.",
 )
-def cmd_detect_synthid(source: Path, as_json: bool, register_scale: bool) -> None:
-    """Detect the SynthID periodic pixel carrier at calibrated image sizes.
+def cmd_detect_synthid(source: Path, as_json: bool, register_scale: bool | None) -> None:
+    """Detect a generation-pipeline pixel lattice at calibrated image sizes.
 
-    A negative result means this detector did not find its supported carrier; it
-    is not proof that the image contains no SynthID watermark.
+    EXPERIMENTAL. The supported route for SynthID is signed provenance, which
+    `identify` reads and `verify-openai-synthid` confirms against the provider.
+    This command does NOT detect the SynthID watermark. The statistic it reports is
+    destroyed by a seven-pixel crop, while SynthID's published evaluation keeps
+    99.97% of its detection rate under aggressive crop and resize, so what
+    crosses the threshold identifies the generation pipeline rather than the
+    mark. Read a positive as "these pixels came from a pipeline that leaves this
+    lattice", never as "this image is watermarked", and read an indeterminate
+    result as neither.
     """
     from remove_ai_watermarks.synthid_detector import detect_synthid
 
@@ -1346,18 +1353,28 @@ def cmd_detect_synthid(source: Path, as_json: bool, register_scale: bool) -> Non
         return
 
     _banner()
-    console.print(f"\n  SynthID pixel carrier: {result.status}")
+    console.print(f"\n  Generation-pipeline lattice (experimental): {result.status}")
     console.print(f"  Geometry: {result.width}x{result.height}")
     if result.score is not None:
         console.print(f"  Score: {result.score:.6f}  (threshold: {result.threshold:.6f})")
     console.print(f"  Detector: {result.detector}")
-    scale_scope = (
-        "  Bounded spatial-scale registration was enabled. A negative or\n"
-        if register_scale
-        else "  Arbitrary spatial resampling was not registered. A negative or\n"
-    )
+    if result.reason is not None:
+        console.print(f"  Reason: {result.reason}")
+    if register_scale is True:
+        scale_scope = "  Bounded spatial-scale registration was explicitly enabled. An indeterminate or\n"
+    elif register_scale is False:
+        scale_scope = "  The legacy fixed-period diagnostic was explicitly enabled. An indeterminate or\n"
+    else:
+        scale_scope = (
+            "  The production router selected the calibrated registered or large-image expert. An indeterminate or\n"
+        )
     console.print(
-        "  Scope: one confirmed periodic carrier family in a calibrated image-size range.\n"
+        "  Scope: experimental. One periodic lattice family in a calibrated image-size range,\n"
+        "  secondary to signed provenance, which remains the supported SynthID route. This is a\n"
+        "  generation-pipeline signature, not the SynthID watermark: it disappears when the\n"
+        "  image is cropped off the tile grid, and it changes when the generator's pipeline\n"
+        "  changes. A positive says the pixels came from such a pipeline. It does not say the\n"
+        "  image carries a watermark, and it does not say it lacks one.\n"
         + scale_scope
         + "  unsupported result is not proof that SynthID is absent."
     )

src/remove_ai_watermarks/identify.py

@@ -114,10 +114,12 @@ _SYNTHID_CAVEAT = (
     "covers one measured carrier family in a calibrated image-size range; confirm other cases with "
     "the provider oracle."
 )
-_SYNTHID_PIXEL_CAVEAT = (
-    "The local SynthID pixel result is a positive-only match to one measured periodic carrier family "
-    "in a calibrated image-size range, not a proprietary payload decode. A negative or unsupported "
-    "result is not proof of absence."
+_PIPELINE_LATTICE_CAVEAT = (
+    "EXPERIMENTAL. Signed provenance is the primary route for SynthID; this pixel result is not a "
+    "watermark at all but a generation-pipeline lattice: it is destroyed by a "
+    "crop of seven pixels, while the published SynthID evaluation survives aggressive crop and resize. "
+    "It accepted 29 of 223 images from other generators, 24% of Adobe Firefly, so it does not identify "
+    "the provider. A negative or unsupported result is not proof of absence."
 )
 _IPTC_ONLY_CAVEAT = "The IPTC 'Made with AI' tag flags AI provenance but does not identify the specific platform."
 _INVISIBLE_WM_CAVEAT = (
@@ -956,8 +958,14 @@ def _trustmark(image_path: Path) -> str | None:
     return detect_trustmark(image_path)
 
 
-def _synthid_pixel_watermark(image_path: Path, decode: _SharedDecode) -> bool:
-    """Whether the supported positive-only SynthID carrier is detected."""
+def _pipeline_lattice(image_path: Path, decode: _SharedDecode) -> bool:
+    """Whether the supported generation-pipeline lattice is detected.
+
+    Named for what it measures. The underlying expert is still called a SynthID
+    detector in its own module, but its statistic is a lattice anchored at the
+    image origin that a seven-pixel crop removes, so nothing here may present it
+    as a watermark.
+    """
     from remove_ai_watermarks.synthid_detector import detect_synthid, is_available
 
     if not is_available() or (image := decode.get()) is None:
@@ -1309,16 +1317,17 @@ def _identify_from_evidence(
         if platform is None:
             platform = f"{scheme} (open DWT-DCT watermark)"
 
-    # ── Positive-only SynthID periodic carrier ──────────────────────
-    # This is deliberately separate from C2PA provenance. It survives lossless
-    # metadata stripping, but covers only one carrier family and a calibrated
-    # image-size range.
-    if check_invisible and pixel_path is not None and _synthid_pixel_watermark(pixel_path, decode):
-        signals.append(Signal("synthid_pixel", "calibrated periodic carrier", "high"))
-        watermarks.append("SynthID periodic pixel carrier (calibrated image size)")
-        caveats.append(_SYNTHID_PIXEL_CAVEAT)
+    # ── Generation-pipeline lattice, experimental ───────────────────
+    # Signed provenance above is the primary SynthID route; this is a secondary
+    # pixel observation and is kept out of the watermark inventory on purpose. This reads a periodic
+    # lattice anchored at the image origin, which identifies the pipeline that
+    # produced the pixels; it is not SynthID and not any watermark, so listing
+    # it beside C2PA watermark assertions would misrepresent both.
+    if check_invisible and pixel_path is not None and _pipeline_lattice(pixel_path, decode):
+        signals.append(Signal("pipeline_lattice", "generation-pipeline lattice (experimental)", "medium"))
+        caveats.append(_PIPELINE_LATTICE_CAVEAT)
         if platform is None:
-            platform = "SynthID carrier detected (provider not attributed locally)"
+            platform = "generation-pipeline lattice detected (provider not attributed locally)"
 
     # ── Adobe TrustMark invisible watermark (open decoder, no key) ───
     # The watermark behind Adobe Durable Content Credentials. Decoded locally,
@@ -1331,7 +1340,8 @@ def _identify_from_evidence(
             platform = "Adobe (TrustMark / Content Credentials)"
 
     # ── Verdict so far (metadata + embedded watermark) ──────────────
-    invisible_wm = any(s.name in {"invisible_watermark", "synthid_pixel"} for s in signals)
+    invisible_wm = any(s.name == "invisible_watermark" for s in signals)
+    pipeline_lattice = any(s.name == "pipeline_lattice" for s in signals)
     exif_gen = any(s.name == "exif_generator" for s in signals)
     xai_sig = any(s.name == "xai_signature" for s in signals)
     ai_from_metadata = bool(
@@ -1341,6 +1351,7 @@ def _identify_from_evidence(
         or aigc
         or local_keys
         or invisible_wm
+        or pipeline_lattice
         or exif_gen
         or xai_sig
     )

src/remove_ai_watermarks/openai_provenance.py

@@ -18,6 +18,7 @@ import importlib
 import json
 import logging
 import tempfile
+import time
 from collections.abc import Callable, Mapping
 from dataclasses import dataclass
 from pathlib import Path
@@ -30,6 +31,10 @@ OpenAISynthIDStatus = Literal["detected", "not_detected"]
 DETECTOR_ID = "openai-content-provenance-synthid-v1"
 INSTALL_HINT = "install the verification extra: uv add 'remove-ai-watermarks[verify]'"
 MAX_UPLOAD_BYTES = 50 * 1024 * 1024
+REQUEST_TIMEOUT_SECONDS = 120.0
+# One acknowledgement authorizes one upload. The SDK otherwise retries some
+# failures by default, which can transmit the same media more than once.
+MAX_AUTOMATIC_RETRIES = 0
 _FORMAT_DETAILS = {
     "JPEG": ("image/jpeg", ".jpg"),
     "PNG": ("image/png", ".png"),
@@ -48,6 +53,10 @@ class OpenAISynthIDDetection:
     detector: str = DETECTOR_ID
     ai_metadata_stripped: bool = True
     pixels_preserved: bool = True
+    signal_family: str = "synthid"
+    provider_scope: str = "openai"
+    backend: str = "official-openai-api"
+    metadata_used_for_verdict: bool = False
 
     @property
     def detected(self) -> bool:
@@ -64,9 +73,34 @@ class OpenAISynthIDDetection:
             "detector": self.detector,
             "ai_metadata_stripped": self.ai_metadata_stripped,
             "pixels_preserved": self.pixels_preserved,
+            "signal_family": self.signal_family,
+            "provider_scope": self.provider_scope,
+            "backend": self.backend,
+            "metadata_used_for_verdict": self.metadata_used_for_verdict,
         }
 
 
+class OpenAIProvenanceError(RuntimeError):
+    """An official verification failure, with retry and support context."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        error_code: str | None = None,
+        request_id: str | None = None,
+        retry_after: str | None = None,
+        retryable: bool = False,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.request_id = request_id
+        self.retry_after = retry_after
+        self.retryable = retryable
+
+
 def is_available() -> bool:
     """True when the optional OpenAI SDK is installed."""
     from remove_ai_watermarks.optional_deps import module_available
@@ -116,16 +150,22 @@ def _optional_string(entry: Mapping[str, Any], field: str) -> str | None:
 
 def _parse_synthid_result(payload: Mapping[str, Any]) -> OpenAISynthIDDetection:
     """Read exactly one SynthID entry and deliberately ignore C2PA entries."""
+    if payload.get("object") != "content_provenance_check":
+        raise RuntimeError("OpenAI Content Provenance response has an unexpected 'object' field")
     raw_results = payload.get("results")
     if not isinstance(raw_results, list):
         raise RuntimeError("OpenAI Content Provenance response has no results list")
     results = cast("list[Any]", raw_results)
     synthid_entries: list[Mapping[str, Any]] = []
     for raw_entry in results:
-        if isinstance(raw_entry, Mapping):
-            entry = cast("Mapping[str, Any]", raw_entry)
-            if entry.get("type") == "synthid":
-                synthid_entries.append(entry)
+        if not isinstance(raw_entry, Mapping):
+            raise RuntimeError("OpenAI Content Provenance response has an invalid result entry")
+        entry = cast("Mapping[str, Any]", raw_entry)
+        result_type = entry.get("type")
+        if not isinstance(result_type, str):
+            raise RuntimeError("OpenAI Content Provenance response has a result without a valid type")
+        if result_type == "synthid":
+            synthid_entries.append(entry)
     if len(synthid_entries) != 1:
         raise RuntimeError(f"OpenAI Content Provenance returned {len(synthid_entries)} SynthID results; expected one")
 
@@ -148,9 +188,12 @@ def _default_client() -> Any:
     if not is_available():
         raise RuntimeError(f"OpenAI SynthID verification needs the OpenAI SDK; {INSTALL_HINT}")
     openai_module = importlib.import_module("openai")
-    client_factory = cast("Callable[[], Any]", openai_module.OpenAI)
+    client_factory = cast("Callable[..., Any]", openai_module.OpenAI)
     try:
-        client = client_factory()
+        client = client_factory(
+            timeout=REQUEST_TIMEOUT_SECONDS,
+            max_retries=MAX_AUTOMATIC_RETRIES,
+        )
     except Exception as exc:
         raise RuntimeError(f"could not initialize the OpenAI client: {exc}") from exc
     if not hasattr(client, "content_provenance_checks"):
@@ -158,17 +201,74 @@ def _default_client() -> Any:
     return client
 
 
-def _request_error(exc: Exception) -> RuntimeError:
-    status_code = getattr(exc, "status_code", None)
-    if status_code == 400:
+def _string_attribute(value: Any) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+def _response_header(exc: Exception, name: str) -> str | None:
+    response = getattr(exc, "response", None)
+    headers = getattr(response, "headers", None)
+    if headers is None:
+        return None
+    try:
+        return _string_attribute(headers.get(name))
+    except (AttributeError, TypeError):
+        return None
+
+
+def _request_error(exc: Exception) -> OpenAIProvenanceError:
+    raw_status_code = getattr(exc, "status_code", None)
+    status_code = (
+        raw_status_code if isinstance(raw_status_code, int) and not isinstance(raw_status_code, bool) else None
+    )
+    error_code = _string_attribute(getattr(exc, "code", None))
+    if error_code is None:
+        body = getattr(exc, "body", None)
+        # The SDK types the exception body as Any, so narrowing it leaves a
+        # Mapping with unknown parameters. The same cast the module already uses
+        # for response payloads keeps the gate clean here.
+        if isinstance(body, Mapping):
+            error_code = _string_attribute(cast("Mapping[str, Any]", body).get("code"))
+    request_id = _string_attribute(getattr(exc, "request_id", None)) or _response_header(exc, "x-request-id")
+    retry_after = _response_header(exc, "retry-after")
+    error_name = type(exc).__name__
+    if error_name == "APITimeoutError":
+        detail = "the OpenAI Content Provenance request timed out"
+    elif error_name == "APIConnectionError":
+        detail = "the OpenAI Content Provenance API could not be reached"
+    elif status_code == 400:
         detail = "OpenAI rejected the image as malformed, unsupported, or blocked"
+    elif status_code == 401:
+        detail = "OpenAI Content Provenance authentication failed"
+    elif status_code == 403:
+        detail = "the OpenAI project is not permitted to use Content Provenance"
     elif status_code == 404:
         detail = "the OpenAI organization does not have Content Provenance API access"
     elif status_code == 429:
         detail = "the OpenAI Content Provenance API rate limit was exceeded"
+    elif status_code is not None and status_code >= 500:
+        detail = "the OpenAI Content Provenance API returned a temporary server error"
     else:
         detail = f"OpenAI Content Provenance request failed: {exc}"
-    return RuntimeError(detail)
+    if retry_after is not None:
+        detail += f"; Retry-After: {retry_after}"
+    if error_code is not None:
+        detail += f"; error code: {error_code}"
+    if request_id is not None:
+        detail += f"; request id: {request_id}"
+    retryable = (
+        error_name in ("APITimeoutError", "APIConnectionError")
+        or status_code == 429
+        or (status_code is not None and status_code >= 500)
+    )
+    return OpenAIProvenanceError(
+        detail,
+        status_code=status_code,
+        error_code=error_code,
+        request_id=request_id,
+        retry_after=retry_after,
+        retryable=retryable,
+    )
 
 
 def verify_openai_synthid(
@@ -215,18 +315,37 @@ def verify_openai_synthid(
             "filename": sanitized.name,
             "media_type": media_type,
             "bytes": upload_bytes,
-            "pixel_sha256": source_fingerprint,
+            "automatic_retries": MAX_AUTOMATIC_RETRIES,
+            "timeout_seconds": REQUEST_TIMEOUT_SECONDS,
         }
         log.info("OpenAI Content Provenance request: %s", json.dumps(request_context, sort_keys=True))
+        started_at = time.monotonic()
         try:
             with stripped.open("rb") as upload:
                 response = api_client.content_provenance_checks.create(
                     file=(sanitized.name, upload, media_type),
+                    timeout=REQUEST_TIMEOUT_SECONDS,
                 )
         except Exception as exc:
-            log.exception("OpenAI Content Provenance request failed: %s", json.dumps(request_context, sort_keys=True))
+            failure_context = {
+                **request_context,
+                "duration_ms": round((time.monotonic() - started_at) * 1000),
+                "error_code": _string_attribute(getattr(exc, "code", None)),
+                "request_id": _string_attribute(getattr(exc, "request_id", None))
+                or _response_header(exc, "x-request-id"),
+                "status_code": getattr(exc, "status_code", None),
+            }
+            log.exception(
+                "OpenAI Content Provenance request failed: %s",
+                json.dumps(failure_context, default=str, sort_keys=True),
+            )
             raise _request_error(exc) from exc
 
         payload = _response_mapping(response)
-        log.info("OpenAI Content Provenance response: %s", json.dumps(payload, default=str, sort_keys=True))
+        response_context = {
+            "duration_ms": round((time.monotonic() - started_at) * 1000),
+            "payload": payload,
+            "request_id": _string_attribute(getattr(response, "_request_id", None)),
+        }
+        log.info("OpenAI Content Provenance response: %s", json.dumps(response_context, default=str, sort_keys=True))
         return _parse_synthid_result(payload)

src/remove_ai_watermarks/synthid_detector.py

@@ -2,8 +2,8 @@
 
 This is a positive-only detector for one measured carrier epoch, not Google's
 private payload decoder. A positive result is strong local evidence for the
-carrier. A negative result means only that the selected detector did not find
-it; image sizes outside that mode's calibrated range are reported separately.
+carrier. An indeterminate result means only that the selected detector did not
+find it; image sizes outside that mode's calibrated range are reported separately.
 
 The numeric runtime requires the ``pixels`` extra. Imports remain lazy so the
 package's metadata-only paths stay dependency-light.
@@ -22,10 +22,12 @@ from typing import TYPE_CHECKING, Any, Literal
 if TYPE_CHECKING:
     from numpy.typing import NDArray
 
-SynthIDDetectionStatus = Literal["detected", "not_detected", "unsupported"]
+SynthIDDetectionStatus = Literal["detected", "indeterminate", "unsupported"]
 
 DETECTOR_ID = "synthid-periodic-tile-v2"
-REGISTERED_DETECTOR_ID = "synthid-periodic-tile-registered-v2"
+REGISTERED_DETECTOR_ID = "synthid-periodic-tile-registered-v3"
+OPPONENT_REGISTERED_DETECTOR_ID = "synthid-periodic-tile-opponent-registered-v1"
+FINE_OPPONENT_REGISTERED_DETECTOR_ID = "synthid-periodic-tile-opponent-fine-registered-v1"
 LARGE_DETECTOR_ID = "synthid-periodic-tile-large-v1"
 MODEL_FILENAME = "synthid_periodic_tile_2048_v1.npz"
 # The template remains frozen at this model geometry. Runtime images are never
@@ -39,10 +41,25 @@ MAX_SUPPORTED_PIXELS = 18_000_000
 TILE_THRESHOLD = 0.17357069773071196
 REGISTERED_MIN_SUPPORTED_PIXELS = 250_000
 REGISTERED_MAX_SUPPORTED_PIXELS = 10_000_000
-REGISTERED_MIN_SIDE = 64
-# The registered score is the minimum normalized margin across its amplitude,
-# spectral-candidate, and high-frequency agreement gates.
+# Registered-v3 can confirm a positive only when both disjoint checkerboard
+# groups contain a complete frozen 256-pixel patch. Narrower geometries need a
+# separately calibrated adaptive-patch expert and must not masquerade as misses.
+REGISTERED_MIN_SIDE = 256
+# The registered score preserves the minimum normalized v2 margin only after
+# independent split-patch phase, amplitude, and held-out codeword confirmation.
 REGISTERED_THRESHOLD = 1.0
+# The opponent-color fallback is a narrower precision-first route for lossless
+# scale changes. Smaller rasters retained a natural period-10 false positive.
+OPPONENT_REGISTERED_THRESHOLD = 1.0
+OPPONENT_REGISTERED_MIN_PIXELS = 1_000_000
+OPPONENT_REGISTERED_MIN_SIDE = 768
+# Fine-period registration is separately frozen for the dense 0.47-0.55
+# lossless-resize challenge. Its more expensive selector is bounded to the
+# geometry range covered by the locked and reserve negative sets.
+FINE_OPPONENT_REGISTERED_THRESHOLD = 1.05
+FINE_OPPONENT_REGISTERED_MIN_PIXELS = 1_000_000
+FINE_OPPONENT_REGISTERED_MAX_PIXELS = 5_000_000
+FINE_OPPONENT_REGISTERED_MIN_SIDE = 768
 # The large-image score combines all-window fixed and spatial opponent gates
 # with an any-window signed opponent mid-band gate. The one vulnerable portrait
 # geometry has an additional Green mid-band upper gate.
@@ -62,7 +79,15 @@ INSTALL_HINT = "install the pixel extra: uv add 'remove-ai-watermarks[pixels]'"
 
 @dataclass(frozen=True)
 class SynthIDDetection:
-    """One local periodic-carrier verdict."""
+    """One local periodic-lattice verdict.
+
+    The family this reports is NOT the watermark, and the field names say so. The
+    statistic is destroyed by a crop of seven pixels, while SynthID's published
+    evaluation retains 99.97% TPR under aggressive crop and resize, so what
+    crosses the threshold is a generation-pipeline lattice anchored at the image
+    origin. It identifies the pipeline, not the mark, and `docs/synthid.md`
+    carries the measurement.
+    """
 
     status: SynthIDDetectionStatus
     width: int
@@ -70,13 +95,23 @@ class SynthIDDetection:
     score: float | None
     threshold: float
     detector: str = DETECTOR_ID
+    reason: str | None = None
+    signal_family: str = "generation-pipeline-lattice"
+    provider_scope: str = "provider-neutral"
+    backend: str = "local-pixel"
+    metadata_used_for_verdict: bool = False
+    pixels_preserved: bool = True
+    # Consumers cannot be expected to read a caveat in prose, so the two measured
+    # failure modes travel with every verdict.
+    tile_aligned_crop_required: bool = True
+    identifies_watermark: bool = False
 
     @property
     def detected(self) -> bool:
         """Whether the supported carrier crossed its frozen threshold."""
         return self.status == "detected"
 
-    def to_dict(self) -> dict[str, str | int | float | None]:
+    def to_dict(self) -> dict[str, str | int | float | bool | None]:
         """Return a JSON-safe result without a local file path."""
         return {
             "status": self.status,
@@ -85,6 +120,14 @@ class SynthIDDetection:
             "score": self.score,
             "threshold": self.threshold,
             "detector": self.detector,
+            "reason": self.reason,
+            "signal_family": self.signal_family,
+            "provider_scope": self.provider_scope,
+            "backend": self.backend,
+            "metadata_used_for_verdict": self.metadata_used_for_verdict,
+            "pixels_preserved": self.pixels_preserved,
+            "tile_aligned_crop_required": self.tile_aligned_crop_required,
+            "identifies_watermark": self.identifies_watermark,
         }
 
 
@@ -269,6 +312,24 @@ def _large_geometry_supported(width: int, height: int) -> bool:
     return min(width, height) >= LARGE_WINDOW and LARGE_MIN_PIXELS < pixels <= LARGE_MAX_PIXELS
 
 
+def _opponent_registered_geometry_supported(width: int, height: int) -> bool:
+    """Whether the opponent-color fallback passed its frozen geometry challenge."""
+    pixels = width * height
+    return (
+        min(width, height) >= OPPONENT_REGISTERED_MIN_SIDE
+        and OPPONENT_REGISTERED_MIN_PIXELS <= pixels <= REGISTERED_MAX_SUPPORTED_PIXELS
+    )
+
+
+def _fine_opponent_registered_geometry_supported(width: int, height: int) -> bool:
+    """Whether the fine-period selector passed its frozen geometry challenge."""
+    pixels = width * height
+    return (
+        min(width, height) >= FINE_OPPONENT_REGISTERED_MIN_SIDE
+        and FINE_OPPONENT_REGISTERED_MIN_PIXELS <= pixels <= FINE_OPPONENT_REGISTERED_MAX_PIXELS
+    )
+
+
 def folded_template_score(
     pixels: NDArray[Any],
     template: NDArray[Any],
@@ -382,13 +443,16 @@ def detect_synthid(
     image_path: str | Path,
     *,
     image: NDArray[Any] | None = None,
-    register_scale: bool = False,
+    register_scale: bool | None = None,
 ) -> SynthIDDetection:
     """Detect the supported periodic carrier in IMAGE_PATH.
 
-    ``not_detected`` is not a clean-image guarantee. It means only that the
-    frozen periodic carrier did not cross its calibrated threshold. Set
-    ``register_scale`` for the slower, separately calibrated resize search.
+    ``indeterminate`` means that the frozen periodic carrier did not cross its
+    calibrated threshold; it is not a clean-image guarantee. The default
+    production router uses scale registration through 10 megapixels and the
+    native large-image expert above that boundary. Set ``register_scale`` to
+    ``True`` to force registration or ``False`` to run the legacy fixed-period
+    diagnostic below the large-image boundary.
     """
     path = Path(image_path)
     if image is None:
@@ -397,19 +461,28 @@ def detect_synthid(
         if image.ndim != 3 or image.shape[2] != 3:
             raise ValueError("image must be a three-channel BGR array")
         height, width = image.shape[:2]
-    large_mode = not register_scale and width * height > LARGE_MIN_PIXELS
-    if register_scale:
+    large_mode = register_scale is not True and width * height > LARGE_MIN_PIXELS
+    registered_mode = register_scale is True or (register_scale is None and not large_mode)
+    if registered_mode:
         geometry_supported = _registered_geometry_supported(width, height)
         threshold = REGISTERED_THRESHOLD
         detector_id = REGISTERED_DETECTOR_ID
+        unsupported_reason = (
+            "registered-v3 requires 250,000-10,000,000 decoded pixels and both dimensions to be at least 256 pixels"
+        )
     elif large_mode:
         geometry_supported = _large_geometry_supported(width, height)
         threshold = LARGE_THRESHOLD
         detector_id = LARGE_DETECTOR_ID
+        unsupported_reason = (
+            "large-v1 requires more than 10,000,000 through 18,000,000 decoded pixels "
+            "and at least two phase-aligned 2048-pixel windows"
+        )
     else:
         geometry_supported = _geometry_supported(width, height)
         threshold = TILE_THRESHOLD
         detector_id = DETECTOR_ID
+        unsupported_reason = "fixed-v2 requires 1,000,000-18,000,000 decoded pixels"
     if not geometry_supported:
         return SynthIDDetection(
             status="unsupported",
@@ -418,6 +491,7 @@ def detect_synthid(
             score=None,
             threshold=threshold,
             detector=detector_id,
+            reason=unsupported_reason,
         )
     if not is_available():
         raise RuntimeError(f"SynthID pixel detection needs numpy and OpenCV; {INSTALL_HINT}")
@@ -433,19 +507,37 @@ def detect_synthid(
         pixels = np.asarray(image[:, :, ::-1], dtype=np.uint8)
     if pixels.shape != (height, width, 3):
         raise RuntimeError("decoded image geometry does not match its header")
-    if register_scale:
-        from remove_ai_watermarks._synthid_registered import registered_score
+    if registered_mode:
+        from remove_ai_watermarks._synthid_registered import (
+            fine_opponent_registered_score,
+            opponent_registered_score,
+            registered_score,
+        )
 
         score = registered_score(pixels, template, sigma)
+        if score < REGISTERED_THRESHOLD and _opponent_registered_geometry_supported(width, height):
+            opponent_score = opponent_registered_score(pixels, template, sigma)
+            if opponent_score >= OPPONENT_REGISTERED_THRESHOLD:
+                score = opponent_score
+                threshold = OPPONENT_REGISTERED_THRESHOLD
+                detector_id = OPPONENT_REGISTERED_DETECTOR_ID
+        if score < threshold and _fine_opponent_registered_geometry_supported(width, height):
+            fine_score = fine_opponent_registered_score(pixels, template, sigma)
+            if fine_score >= FINE_OPPONENT_REGISTERED_THRESHOLD:
+                score = fine_score
+                threshold = FINE_OPPONENT_REGISTERED_THRESHOLD
+                detector_id = FINE_OPPONENT_REGISTERED_DETECTOR_ID
     elif large_mode:
         score = large_image_components(pixels, template, sigma).decision_score
     else:
         score, _folded = folded_template_score(pixels, template, sigma)
+    detected = score >= threshold
     return SynthIDDetection(
-        status="detected" if score >= threshold else "not_detected",
+        status="detected" if detected else "indeterminate",
         width=width,
         height=height,
         score=score,
         threshold=threshold,
         detector=detector_id,
+        reason=None if detected else "the selected carrier expert did not cross every calibrated gate",
     )