Merge pull request #338 from spoo-me/fix/embed-future-links

fix(safety): say what a block does to future links, drop blocklist claim

Author: Zingzy

services/safety/analyzer.py

@@ -233,6 +233,9 @@ async def _handle_toxic(
             legacy_count=result.legacy_count,
             sample_url=event.url,
             scope=scope_note,
+            scope_kind={"host": "host", "path_pattern": "pattern", "links": "links"}[
+                scope
+            ],
             follow_up=follow_up,
         )
 
@@ -272,7 +275,7 @@ async def _reenforce(self, event: SafetyAnalyzeEvent, existing: VerdictDoc) -> b
                 reason=reason,
             )
             await self._notify_reenforced(
-                event, result, reason, scope=f"pattern: {pattern}"
+                event, result, reason, scope=f"pattern: {pattern}", scope_kind="pattern"
             )
             return matching_blocked_pattern(event.url, (pattern,)) is not None
         # links scope: already blocked and the create gate refuses the exact URL.
@@ -326,10 +329,16 @@ async def _screen_redirect(self, event: SafetyAnalyzeEvent) -> None:
                 legacy_count=result.legacy_count,
                 sample_url=event.url,
                 scope=f"the judged link only (reached through {event.host})",
+                scope_kind="links",
             )
 
     async def _notify_reenforced(
-        self, event, result, reason: str, scope: str = "host-wide"
+        self,
+        event,
+        result,
+        reason: str,
+        scope: str = "host-wide",
+        scope_kind: str = "host",
     ) -> None:
         """Blocked something: the operator hears about it. Zero blocks stays quiet."""
         if result.blocked_count + result.legacy_count == 0:
@@ -342,6 +351,7 @@ async def _notify_reenforced(
             legacy_count=result.legacy_count,
             sample_url=event.url,
             scope=f"{scope} (re-enforced existing verdict)",
+            scope_kind=scope_kind,
         )
 
     async def _escalate(

services/safety/investigation.py

@@ -388,6 +388,7 @@ async def _enact(
                 legacy_count=result.legacy_count,
                 sample_url=event.url,
                 scope="host-wide",
+                scope_kind="host",
                 screenshot=shot,
             )
         elif decision.action == "block_aliases":
@@ -409,7 +410,7 @@ async def _enact(
                     result.blocked_count,
                     result.legacy_count,
                 )
-                scope_note = f"pattern: {pattern} (proposed for the blocklist)"
+                scope_note, scope_kind = f"pattern: {pattern}", "pattern"
             else:
                 pairs = await self._aliases_to_block(event)
                 if pairs:
@@ -431,7 +432,10 @@ async def _enact(
                         result.blocked_count,
                         result.legacy_count,
                     )
-                scope_note = "specific links only, host left serving"
+                scope_note, scope_kind = (
+                    "specific links only, host left serving",
+                    "links",
+                )
             await self._notifier.safety_action(
                 host=event.host,
                 reason=verdict.reason,
@@ -440,6 +444,7 @@ async def _enact(
                 legacy_count=legacy_count,
                 sample_url=event.url,
                 scope=scope_note,
+                scope_kind=scope_kind,
                 screenshot=shot,
             )
         elif decision.action == "apply_list":

services/safety/notify.py

@@ -8,13 +8,23 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Literal
 
 from infrastructure.ops_notify import OpsNotifier
 
 ACTION_COLOR = 15548997  # red: automatic enforcement happened
 REVIEW_COLOR = 16705372  # yellow: a human decision is needed
 
+ScopeKind = Literal["host", "pattern", "links"]
+
+# What the verdict store, which is the create-time gate, does from now on.
+# Nothing here touches the operator blocklist; saying so is the point.
+_FUTURE: dict[str, str] = {
+    "host": "new links to this host are REFUSED at create (verdict store, not the blocklist)",
+    "pattern": "new links matching the pattern are REFUSED at create; other paths on the host stay open",
+    "links": "this URL (query variants included) is refused at create; the host stays open",
+}
+
 
 def _code(value: object) -> str:
     return f"```{value}```"
@@ -34,21 +44,25 @@ async def safety_action(
         legacy_count: int,
         sample_url: str | None,
         scope: str = "",
+        scope_kind: ScopeKind | None = None,
         screenshot: bytes | None = None,
         follow_up: str = "",
     ) -> bool:
         """Enforcement already happened; this states the action taken.
-        ``scope`` is its own field because "host-wide" and "one link" are
-        read very differently by the person deciding whether to intervene,
-        and ``follow_up`` is separate so a link-scoped block never reads
-        "host-wide decision..." beside a Scope that says otherwise."""
+        ``scope`` says how far the block reached on links that exist;
+        ``scope_kind`` adds what happens to the next link someone creates,
+        because "host-wide" alone does not answer that. ``follow_up`` is
+        separate so a link-scoped block never reads "host-wide decision..."
+        beside a Scope that says otherwise."""
         fields: list[dict[str, Any]] = [
             {"name": "Destination Host", "value": _code(host)},
             {"name": "Scope", "value": _code(scope or "unspecified")},
             {"name": "Reason", "value": _code(reason)},
             {"name": "Trigger", "value": _code(trigger)},
             {"name": "Links Blocked (v2)", "value": _code(blocked_count)},
         ]
+        if scope_kind:
+            fields.append({"name": "Future links", "value": _code(_FUTURE[scope_kind])})
         if legacy_count:
             fields.append(
                 {"name": "Legacy v1/emoji Blocked", "value": _code(legacy_count)}

services/safety/providers.py

@@ -15,7 +15,7 @@
 
 import time
 from dataclasses import dataclass
-from typing import Protocol
+from typing import Literal, Protocol
 
 from infrastructure.logging import get_logger
 from infrastructure.web_risk import WebRiskClient
@@ -28,13 +28,15 @@
 log = get_logger(__name__)
 
 
+VerdictScope = Literal["host", "links", "path_pattern"]
+
+
 @dataclass(frozen=True)
 class ProviderVerdict:
     tier: VerdictTier
     reason: str
-    # "host", "links" (one exact URL) or "path_pattern" (regex in
-    # ``path_pattern``): how far the evidence reaches, not what it enforces.
-    scope: str = "host"
+    # How far the evidence reaches, not what it enforces.
+    scope: VerdictScope = "host"
     path_pattern: str | None = None
 
 

tests/unit/services/safety/test_analyzer.py

@@ -650,6 +650,7 @@ async def test_reenforcement_that_blocks_new_links_notifies(self):
 
         kw = notifier.safety_action.await_args.kwargs
         assert kw["scope"] == "host-wide (re-enforced existing verdict)"
+        assert kw["scope_kind"] == "host"
         assert kw["reason"] == "old verdict"
 
     @pytest.mark.asyncio

tests/unit/services/safety/test_investigation.py

@@ -399,11 +399,12 @@ async def test_pattern_reaches_the_operator_and_the_verdict(self):
         assert prov["scope"] == "path_pattern"
         assert "sites" in prov["path_pattern"]
         assert prov["scope_justification"] == "shared site builder, 210 creators"
-        # The operator is told the pattern to add, since a pattern reaches
-        # every FUTURE link and only a human may apply it.
+        # The verdict store refuses future matches itself; nothing here writes
+        # to the operator blocklist, so the embed must not say it does.
         kw = notifier.safety_action.await_args.kwargs
         assert kw["scope"].startswith("pattern: ")
-        assert "proposed for the blocklist" in kw["scope"]
+        assert kw["scope_kind"] == "pattern"
+        assert "blocklist" not in kw["scope"]
         assert (
             "pattern" not in kw["reason"]
         )  # the reason is the model's reason, nothing else
@@ -785,6 +786,7 @@ async def tool_call():
         enforcer.block_host.assert_awaited_once()
         kw = notifier.safety_action.await_args.kwargs
         assert kw["scope"] == "host-wide"
+        assert kw["scope_kind"] == "host"
         # The judged URL's render, not the root fetched after it.
         assert kw["screenshot"] == b"the-page"
 

tests/unit/services/safety/test_notify.py

@@ -111,3 +111,51 @@ async def test_carries_context_and_image(self):
         f = _fields(ops)
         assert "classification: uncertain" in f["Context"]
         assert f["Sample URL"] == "```https://h/x```"
+
+
+class TestFutureLinks:
+    """Scope says how far the block reached on links that already exist.
+    It says nothing about the next link someone creates, and it must never
+    imply the operator blocklist changed: nothing in the pipeline writes to
+    it, the verdict store is the create-time gate."""
+
+    @pytest.mark.asyncio
+    async def test_host_kind_says_new_links_are_refused(self):
+        n, ops = _notifier()
+        await _action(n, scope="host-wide", scope_kind="host")
+        f = _fields(ops)["Future links"]
+        assert "new links to this host are REFUSED at create" in f
+        assert "not the blocklist" in f
+
+    @pytest.mark.asyncio
+    async def test_pattern_kind_says_matches_refused_host_stays_open(self):
+        n, ops = _notifier()
+        await _action(
+            n, scope="pattern: ^https://evil.example/l.*", scope_kind="pattern"
+        )
+        f = _fields(ops)["Future links"]
+        assert "matching the pattern are REFUSED" in f
+        assert "other paths on the host stay open" in f
+
+    @pytest.mark.asyncio
+    async def test_links_kind_says_host_stays_open(self):
+        n, ops = _notifier()
+        await _action(n, scope="the judged link only", scope_kind="links")
+        f = _fields(ops)["Future links"]
+        assert "query variants included" in f
+        assert "the host stays open" in f
+
+    @pytest.mark.asyncio
+    async def test_no_kind_no_field(self):
+        n, ops = _notifier()
+        await _action(n, scope="host-wide")
+        assert "Future links" not in _fields(ops)
+
+    def test_future_text_never_promises_the_blocklist(self):
+        """A "proposed for the blocklist" claim shipped and survived two
+        review rounds. Pin it out."""
+        from services.safety.notify import _FUTURE
+
+        for text in _FUTURE.values():
+            assert "proposed" not in text
+            assert "blocklist" not in text.replace("not the blocklist", "")