feat(allowlist): coverage projection + applied-count + post-accept projection (#7a/#7b)

Cluster B, milestone #99. Backend for the allowlist tuning dashboard.

#7a: AllowlistService.coverage(tag_id, threshold) counts distinct images with
a prediction resolving to the tag (raw_name==tag.name OR (raw_name,category) in
the tag's aliases) scoring >= threshold — the gross candidate pool, mirroring
tasks.ml._confidence_for_tag resolution. list_all now carries applied_count
(grouped image_tag count) + coverage_count (at the row's threshold). New
GET /api/tags/<id>/allowlist/coverage?threshold= for the live what-if number.

#7b: /suggestions/accept + /alias return {allowlisted, tag_id, tag_name,
projected_count} (projection at the tag's threshold) instead of 204, so the UI
can show a non-blocking 'auto-applying to ~N images' toast. Apply still runs
async via apply_allowlist_tags — projected_count is an estimate.

Tests: coverage by threshold (direct + alias-with-category), list applied vs
coverage, coverage route (explicit/default/bad threshold), accept/alias payload
(newly-allowlisted vs already-on-list).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XCUHUGQLrBrkgyk1t49kpX

tests/test_api_allowlist.py

@@ -1,6 +1,6 @@
 import pytest
 
-from backend.app.models import TagAllowlist, TagKind
+from backend.app.models import ImagePrediction, ImageRecord, TagAllowlist, TagKind
 from backend.app.services.tag_service import TagService
 
 pytestmark = pytest.mark.integration
@@ -39,3 +39,50 @@ async def test_patch_rejects_out_of_range(client, db):
         f"/api/tags/{tag.id}/allowlist", json={"min_confidence": 1.5}
     )
     assert resp.status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_coverage_endpoint(client, db):
+    tag = await TagService(db).find_or_create("Cover", TagKind.general)
+    db.add(TagAllowlist(tag_id=tag.id, min_confidence=0.90))
+    for i, score in enumerate((0.95, 0.60)):
+        img = ImageRecord(
+            path=f"/images/cov{i}.jpg", sha256=f"cv{i:062d}", size_bytes=1,
+            mime="image/jpeg", width=1, height=1,
+            origin="imported_filesystem", integrity_status="unknown",
+        )
+        db.add(img)
+        await db.flush()
+        db.add(ImagePrediction(
+            image_record_id=img.id, raw_name="Cover",
+            category="general", score=score,
+        ))
+    await db.commit()
+
+    # Explicit threshold.
+    resp = await client.get(
+        f"/api/tags/{tag.id}/allowlist/coverage?threshold=0.90"
+    )
+    assert resp.status_code == 200
+    assert (await resp.get_json())["count"] == 1
+    # Lower what-if threshold widens coverage.
+    resp = await client.get(
+        f"/api/tags/{tag.id}/allowlist/coverage?threshold=0.50"
+    )
+    assert (await resp.get_json())["count"] == 2
+    # No threshold → uses the stored min_confidence (0.90).
+    resp = await client.get(f"/api/tags/{tag.id}/allowlist/coverage")
+    body = await resp.get_json()
+    assert body["count"] == 1
+    assert body["threshold"] == pytest.approx(0.90)
+
+
+@pytest.mark.asyncio
+async def test_coverage_rejects_bad_threshold(client, db):
+    tag = await TagService(db).find_or_create("Cover2", TagKind.general)
+    db.add(TagAllowlist(tag_id=tag.id))
+    await db.commit()
+    resp = await client.get(
+        f"/api/tags/{tag.id}/allowlist/coverage?threshold=2.0"
+    )
+    assert resp.status_code == 400

tests/test_api_suggestions.py

@@ -14,11 +14,11 @@ def eager():
     celery.conf.task_always_eager = False
 
 
-async def _img(db, preds):
+async def _img(db, preds, sha="s" * 64):
     from tests._prediction_helpers import seed_predictions
 
     img = ImageRecord(
-        path="/images/s.jpg", sha256="s" * 64, size_bytes=1,
+        path=f"/images/{sha[:8]}.jpg", sha256=sha, size_bytes=1,
         mime="image/jpeg", width=1, height=1,
         origin="imported_filesystem", integrity_status="unknown",
     )
@@ -57,7 +57,31 @@ async def test_accept_then_applied(client, db):
     resp = await client.post(
         f"/api/images/{img.id}/suggestions/accept", json={"tag_id": tag.id}
     )
-    assert resp.status_code == 204
+    assert resp.status_code == 200
+    body = await resp.get_json()
+    # #7b: a fresh accept newly-allowlists → projection payload for the toast.
+    assert body["allowlisted"] is True
+    assert body["tag_id"] == tag.id
+    assert body["tag_name"] == "AcceptMe"
+    assert "projected_count" in body
+
+
+@pytest.mark.asyncio
+async def test_accept_already_allowlisted_reports_not_new(client, db):
+    img1 = await _img(db, {}, sha="c" * 64)
+    img2 = await _img(db, {}, sha="d" * 64)
+    tag = await TagService(db).find_or_create("Twice", TagKind.character)
+    await db.commit()
+    first = await client.post(
+        f"/api/images/{img1.id}/suggestions/accept", json={"tag_id": tag.id}
+    )
+    assert (await first.get_json())["allowlisted"] is True
+    second = await client.post(
+        f"/api/images/{img2.id}/suggestions/accept", json={"tag_id": tag.id}
+    )
+    body = await second.get_json()
+    assert body["allowlisted"] is False   # already on the allowlist
+    assert "projected_count" not in body
 
 
 @pytest.mark.asyncio
@@ -127,7 +151,8 @@ async def test_alias_roundtrip_resolves_by_raw_key(client, db):
             "canonical_tag_id": canonical.id,
         },
     )
-    assert resp.status_code == 204
+    assert resp.status_code == 200
+    assert (await resp.get_json())["allowlisted"] is True
 
     # (b) A DIFFERENT image with the same prediction now resolves via the alias
     # (image A's tag is applied, so it's filtered there). Had the alias been

tests/test_ml_allowlist.py

@@ -1,7 +1,13 @@
 import pytest
 from sqlalchemy import select
 
-from backend.app.models import TagAllowlist, TagKind, TagSuggestionRejection
+from backend.app.models import (
+    ImagePrediction,
+    TagAlias,
+    TagAllowlist,
+    TagKind,
+    TagSuggestionRejection,
+)
 from backend.app.models.tag import image_tag
 from backend.app.services.ml.allowlist import AllowlistService
 from backend.app.services.tag_service import TagService
@@ -9,10 +15,10 @@ from backend.app.services.tag_service import TagService
 pytestmark = pytest.mark.integration
 
 
-async def _make_image(db):
+async def _make_image(db, sha: str = "x" * 64):
     from backend.app.models import ImageRecord
     img = ImageRecord(
-        path="/images/x.jpg", sha256="x" * 64, size_bytes=1,
+        path=f"/images/{sha[:8]}.jpg", sha256=sha, size_bytes=1,
         mime="image/jpeg", width=1, height=1,
         origin="imported_filesystem", integrity_status="unknown",
     )
@@ -21,6 +27,14 @@ async def _make_image(db):
     return img
 
 
+async def _add_pred(db, image_id, raw_name, score, category="general"):
+    db.add(ImagePrediction(
+        image_record_id=image_id, raw_name=raw_name,
+        category=category, score=score,
+    ))
+    await db.flush()
+
+
 @pytest.mark.asyncio
 async def test_accept_applies_and_allowlists(db):
     img = await _make_image(db)
@@ -106,6 +120,52 @@ async def test_update_threshold_and_remove(db):
     assert await db.get(TagAllowlist, tag.id) is None
 
 
+@pytest.mark.asyncio
+async def test_coverage_by_threshold_direct_name(db):
+    tag = await TagService(db).find_or_create("Cov", TagKind.general)
+    svc = AllowlistService(db)
+    for i, score in enumerate((0.95, 0.80, 0.60)):
+        img = await _make_image(db, sha=f"c{i:063d}")
+        await _add_pred(db, img.id, "Cov", score)
+    assert await svc.coverage(tag.id, 0.90) == 1
+    assert await svc.coverage(tag.id, 0.70) == 2
+    assert await svc.coverage(tag.id, 0.50) == 3
+
+
+@pytest.mark.asyncio
+async def test_coverage_via_alias_respects_category(db):
+    tag = await TagService(db).find_or_create("Aliased", TagKind.character)
+    db.add(TagAlias(
+        alias_string="model_key", alias_category="character",
+        canonical_tag_id=tag.id,
+    ))
+    await db.flush()
+    svc = AllowlistService(db)
+    hit = await _make_image(db, sha=f"a{0:063d}")
+    await _add_pred(db, hit.id, "model_key", 0.92, category="character")
+    # Same alias string but wrong category must NOT resolve to the tag.
+    miss = await _make_image(db, sha=f"a{1:063d}")
+    await _add_pred(db, miss.id, "model_key", 0.99, category="general")
+    assert await svc.coverage(tag.id, 0.90) == 1
+
+
+@pytest.mark.asyncio
+async def test_list_all_reports_applied_and_coverage(db):
+    tag = await TagService(db).find_or_create("Both", TagKind.general)
+    svc = AllowlistService(db)
+    applied_img = await _make_image(db, sha=f"b{0:063d}")
+    await svc.accept(applied_img.id, tag.id)  # applies + allowlists
+    await _add_pred(db, applied_img.id, "Both", 0.95)
+    # A second image only has a qualifying prediction (covered, not applied).
+    cov_img = await _make_image(db, sha=f"b{1:063d}")
+    await _add_pred(db, cov_img.id, "Both", 0.95)
+
+    rows = await svc.list_all()
+    row = next(r for r in rows if r.tag_id == tag.id)
+    assert row.applied_count == 1                 # only the accepted image
+    assert row.coverage_count == 2                # both have a ≥threshold pred
+
+
 @pytest.mark.asyncio
 async def test_update_threshold_clamped_to_store_floor(db):
     # A min_confidence below the store floor (default 0.70) is clamped up —