fix(i18n): read every refusal from the backend's syntax tree, not by regex

The contract read Python with regexes, and each guard added for a missed shape had shapes of its own
it missed: a reason after another key, a status passed by name, a second `e.reason` handler with the
same text, a pin naming a type nothing checked.

backend/tests/refusal_sites.py (stdlib `ast`, run by the contract on the host's Python) reads every
`{"code": ...}` detail and follows each reason to its values: literals, both arms of a conditional,
module constants, the `Literal` on the parameter or attribute it travels in (on the class an `except`
catches), every call of a `str` helper with its defaults, a map's values with its keys held to the
index's type. What it cannot follow fails the contract, unless no screen shows that code; no pins.

The reason attributes are typed with their Literal, so a subclass or an assignment cannot widen
them; InvalidSetting takes a SettingReason, and the settings map is held to it (a reason the map
lacked was a 500). The per-family reverse checks are one check by prefix (the admin actions
included), and the leaf-key filter applies only to the suffixed sign-in family.

backend/app/downloads/clip.py

@@ -78,7 +78,7 @@ class ClipError(Exception):
     message names (the cap itself, so the client never says a stale one)."""
 
     def __init__(self, reason: ClipReason, **params: float):
-        self.reason = reason
+        self.reason: ClipReason = reason
         self.params = params
         super().__init__(reason)
 

backend/app/downloads/credentials.py

@@ -174,7 +174,7 @@ class InvalidCookies(ValueError):
 
     def __init__(self, reason: CookieReason):
         super().__init__(reason)
-        self.reason = reason
+        self.reason: CookieReason = reason
 
 
 def validate_cookies(raw: str) -> str:

backend/app/downloads/folders.py

@@ -197,7 +197,7 @@ class FolderError(Exception):
 
     def __init__(self, reason: FolderReason) -> None:
         super().__init__(reason)
-        self.reason = reason
+        self.reason: FolderReason = reason
 
 
 def own_folder(db: Session, user_id: int, folder_id: int, *, hold: bool = True) -> FileFolder:

backend/app/downloads/quota.py

@@ -60,7 +60,7 @@ class QuotaExceeded(Exception):
     """Raised by check_enqueue; `reason` names the cap it hit (an i18n key on the client)."""
 
     def __init__(self, reason: QuotaReason, limit: int, current: int):
-        self.reason = reason
+        self.reason: QuotaReason = reason
         self.limit = limit
         self.current = current
         super().__init__(f"download quota exceeded: {reason} ({current}/{limit})")

backend/app/downloads/service.py

@@ -49,7 +49,7 @@ class EditError(Exception):
     """Bad edit request (empty spec / source not ready / not media); `reason` names the sentence."""
 
     def __init__(self, reason: EditReason):
-        self.reason = reason
+        self.reason: EditReason = reason
         super().__init__(reason)
 
 

backend/app/downloads/urlguard.py

@@ -59,7 +59,7 @@ class BlockedUrl(Exception):
 
     def __init__(self, reason: UrlBlockedReason):
         super().__init__(reason)
-        self.reason = reason
+        self.reason: UrlBlockedReason = reason
 
 
 def _is_forbidden(ip: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool:

backend/app/reader/service.py

@@ -311,7 +311,7 @@ class MoveRefused(Exception):
 
     def __init__(self, reason: MoveReason):
         super().__init__(reason)
-        self.reason = reason
+        self.reason: MoveReason = reason
 
 
 def touch(pl: Playlist) -> None:

backend/app/refusal.py

@@ -7,16 +7,19 @@ whatever sentence the route happened to hand-write. `refused` is the generic fam
 (`errors.refused.<reason>`, the params interpolated into the sentence); the older specific codes
 (`not_found`, `youtube`, `playlist`, the admin refusals, …) stay, since each is already translated.
 
-A test (`test_http_details.py`) reads every `HTTPException` in the app and fails on a string detail,
-and the frontend's contract test (`i18n/backendIds.contract.test.ts`) requires every `code` a detail
-carries to be in one record of `lib/api/refusalCodes.ts`, and every reason it can be sent with — a
-literal, or a `Literal` type when it travels in a variable — to have its sentence in both languages.
-A code or reason that scan cannot read fails it until it is listed with what holds it. So the rule is
-enforced, not described.
+A test (`test_http_details.py`) reads every `HTTPException` in the app and fails on a string detail.
+`tests/refusal_sites.py` reads every `{"code": …}` detail from the syntax tree and follows each reason
+to its values: a literal, a `Literal` type on the parameter or attribute it travels in, every call of
+a helper like `refused` below, a map's values. The frontend's contract test
+(`i18n/backendIds.contract.test.ts`) runs it and requires each code in one record of
+`lib/api/refusalCodes.ts`, and each reason's sentence in both languages; a code or reason it cannot
+follow fails it, unless no screen shows that code. So the rule is enforced, not described.
 """
 
 from fastapi import HTTPException
 
+from app.sysconfig import InvalidSetting, SettingReason
+
 
 def refused(status: int, reason: str, **params: object) -> HTTPException:
     """The refusal to raise: `raise refused(409, "view_name_taken", name=name)`. `params` travel in
@@ -24,9 +27,9 @@ def refused(status: int, reason: str, **params: object) -> HTTPException:
     return HTTPException(status_code=status, detail={"code": "refused", "reason": reason, **params})
 
 
-# `sysconfig.InvalidSetting.reason` → the refusal it answers as. A dict of literals, so the frontend's
-# contract test can read every reason this can produce.
-_SETTING_REASONS = {
+# `sysconfig.InvalidSetting.reason` → the refusal it answers as. A dict of literals, so the refusal
+# scan reads every reason this can produce, and holds its keys to `SettingReason`.
+_SETTING_REASONS: dict[SettingReason, str] = {
     "not_a_number": "setting_not_a_number",
     "too_low": "setting_too_low",
     "too_high": "setting_too_high",
@@ -35,6 +38,6 @@ _SETTING_REASONS = {
 }
 
 
-def setting_refused(exc) -> HTTPException:
+def setting_refused(exc: InvalidSetting) -> HTTPException:
     """A value the admin entered that `sysconfig.set_value` refused (`exc`: its `InvalidSetting`)."""
     return refused(400, _SETTING_REASONS[exc.reason], key=exc.key, **exc.params)

backend/app/sysconfig.py

@@ -443,15 +443,20 @@ def _default(s: ConfigSpec):
     return getattr(settings, s.default_attr)
 
 
+# Every reason `set_value` refuses with. `refusal.setting_refused` looks each one up in its map, which
+# the refusal scan holds to exactly these keys: a reason the map lacks would answer a 500.
+SettingReason = Literal["not_a_number", "too_low", "too_high", "not_a_choice", "no_encryption_key"]
+
+
 class InvalidSetting(ValueError):
     """A value `set_value` refuses, as a reason the UI translates (`errors.refused.setting_<reason>`)
     plus what the sentence needs — the English message is for logs only. A ValueError still, so a
     caller that only needs "refused or not" keeps working."""
 
-    def __init__(self, key: str, reason: str, **params: object):
+    def __init__(self, key: str, reason: SettingReason, **params: object):
         super().__init__(f"{key}: {reason} {params}")
         self.key = key
-        self.reason = reason
+        self.reason: SettingReason = reason
         self.params = params