Prefer provider APIs before web oracles

scripts/README.md

@@ -18,7 +18,7 @@ explicitly names a tracked canonical result.
 | `pill_gate_audit.py` | Measure the Jimeng pill detector on the product path. |
 | `provider_oracle_web.py` | Implement isolated Playwright submissions for the unified provider-oracle runner. |
 | `provider_oracle_microsoft.py` | Call Microsoft's Content Provenance API with hash-bound public media and Azure CLI authentication. |
-| `provider_oracles.py` | Drive and validate hash-bound Google, OpenAI, Microsoft, and Meta oracle checks. |
+| `provider_oracles.py` | Plan API-first and drive hash-bound Google, OpenAI, Microsoft, and Meta oracle checks. |
 | `real_examples_e2e.py` | Run end-to-end confidence checks over local examples. |
 | `record_parity_audit.py` | Compare record-based and file-based identification. |
 | `resource_ceilings.py` | Measure peak RSS and runtime for fill backends. |

scripts/provider_oracles.py

@@ -257,6 +257,24 @@ SURFACES: dict[str, OracleSurface] = {
 PROVIDER_KEYS = frozenset(surface.provider_key for surface in SURFACES.values())
 
 
+def _surface_order(surface: OracleSurface) -> tuple[bool, str]:
+    """Sort API surfaces before Web surfaces, then stabilize by key."""
+    return surface.automation != "api", surface.key
+
+
+def provider_plan(provider_key: str) -> list[OracleSurface]:
+    """Return one provider's surfaces in the API-first operator order."""
+    if provider_key not in PROVIDER_KEYS:
+        raise ValueError(f"unknown provider oracle: {provider_key}")
+    surfaces = [surface for surface in SURFACES.values() if surface.provider_key == provider_key]
+    return sorted(surfaces, key=_surface_order)
+
+
+def ordered_surfaces() -> list[OracleSurface]:
+    """Return the catalog with every API surface before every Web surface."""
+    return sorted(SURFACES.values(), key=_surface_order)
+
+
 def _inside(path: Path, parent: Path) -> bool:
     """Return whether resolved PATH is inside resolved PARENT."""
     try:
@@ -820,7 +838,7 @@ def cli() -> None:
 @click.option("--json", "as_json", is_flag=True, help="Emit machine-readable JSON.")
 def list_oracles(as_json: bool) -> None:
     """List provider scope, supported media, and verification surfaces."""
-    definitions = [SURFACES[key] for key in sorted(SURFACES)]
+    definitions = ordered_surfaces()
     if as_json:
         click.echo(json.dumps([definition.to_dict() for definition in definitions], indent=2, sort_keys=True))
         return
@@ -829,6 +847,26 @@ def list_oracles(as_json: bool) -> None:
         click.echo(f"{definition.key}\t{definition.automation}\t{media}\t{definition.surface}\t{definition.url}")
 
 
+@cli.command()
+@click.argument("provider", type=click.Choice(sorted(PROVIDER_KEYS)))
+@click.option("--json", "as_json", is_flag=True, help="Emit machine-readable JSON.")
+def plan(provider: str, as_json: bool) -> None:
+    """Show the API-first surface order for one provider."""
+    definitions = provider_plan(provider)
+    rows = []
+    for index, definition in enumerate(definitions):
+        row = definition.to_dict()
+        row["preference"] = "primary" if index == 0 else "fallback"
+        rows.append(row)
+    if as_json:
+        click.echo(json.dumps(rows, indent=2, sort_keys=True))
+        return
+    for row in rows:
+        click.echo(f"{row['preference']}\t{row['key']}\t{row['automation']}\t{row['surface']}")
+    if len(rows) > 1:
+        click.echo("Web fallback requires a separate operator decision; failures do not trigger it automatically.")
+
+
 @cli.command()
 @click.argument("surface", type=click.Choice(sorted(SURFACES)))
 @click.option("--slots", "slots_path", type=click.Path(exists=True, dir_okay=False, path_type=Path))

scripts/qwen_scrub_prototype.py

@@ -23,7 +23,8 @@ invisible pipeline onto Qwen-Image-Edit). It is DELIBERATELY standalone:
   * Qwen-Image is ~20B, so it needs a real GPU (CUDA) -- it will not fit on MPS.
 
 Run (on a GPU box / Modal), then eyeball the outputs AND submit them to the
-matching oracle (openai.com/verify for OpenAI, the Gemini app for Google):
+matching oracle (the Content Provenance API first for OpenAI, the Gemini app for
+Google; inspect the current order with ``provider_oracles.py plan PROVIDER``):
 
     uv run scripts/qwen_scrub_prototype.py INPUT.png -o out/ --strengths 0.1,0.2,0.3,0.4
 
@@ -119,8 +120,9 @@ def main(
 
     log.info(
         "\nDone. Eyeball text/face fidelity, then submit each output to the matching oracle "
-        "(openai.com/verify / Gemini app). The smallest strength that clears the oracle while "
-        "keeping fidelity is the number to compare against the SDXL floors (OpenAI 0.10 / Google 0.15)."
+        "(OpenAI Content Provenance API first / Gemini app). The smallest strength that clears "
+        "the oracle while keeping fidelity is the number to compare against the SDXL floors "
+        "(OpenAI 0.10 / Google 0.15)."
     )