sud-cli 0.1.1__py3-none-any.whl

sud_cli/fssp_semi.py

@@ -0,0 +1,285 @@
+"""S-61 полу-автомат ФССП (решение проекта 25.10, юридическая проверка запрошена отдельно).
+
+Полу-автомат: скрипт делает ВСЁ, кроме капчи — открывает страницу БДИП через
+общий loopback-браузер (Camofox runtime), заполняет форму, нажимает «Найти».
+Если сайт выставил капчу — делает скриншот, отдаёт его человеку; человек
+сообщает код, `fssp assist --resume` вводит его и забирает результат.
+Капчу решает человек, не сервис-Recognizer и не брутфорс.
+
+Ограничения честности:
+- селекторы эвристические (страница недоступна для калибровки из-за лимита
+  подключений ФССП к нашему exit IP); при нераспознанной странице — статус
+  page_changed со снимком, ручной контур (fssp check) остаётся запасным;
+- rate-limit: не более одного start на сессию; 503/429/'лимит подключений'
+  -> breaker_trip(fssp.gov.ru) и честная ошибка limited;
+- runtime обязан быть loopback (SSRF-политика, как в мосте case-search).
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import secrets
+import time
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlsplit
+
+FSSP_URL = "https://fssp.gov.ru/iss/ip/"
+DEFAULT_RUNTIME = "http://127.0.0.1:9377"
+_LOOPBACK = {"127.0.0.1", "localhost", "::1"}
+_TTL_S = 30 * 60
+
+
+class FsspAssistError(Exception):
+    pass
+
+
+def _runtime_url() -> str:
+    raw = os.environ.get("CSE_FSSP_RUNTIME", DEFAULT_RUNTIME).strip()
+    parts = urlsplit(raw)
+    if parts.scheme not in ("http", "https") or parts.hostname not in _LOOPBACK:
+        raise FsspAssistError("CSE_FSSP_RUNTIME must be a loopback http(s) URL")
+    return raw.rstrip("/")
+
+
+def _api(method: str, path: str, *, body: Optional[dict] = None,
+         query: Optional[dict] = None, timeout: int = 60, binary: bool = False):
+    import urllib.error
+    import urllib.request
+
+    base = _runtime_url()
+    qs = ("?" + "&".join(f"{k}={v}" for k, v in (query or {}).items())) if query else ""
+    url = f"{base}{path}{qs}"
+    data = json.dumps(body).encode("utf-8") if body is not None else None
+    req = urllib.request.Request(url, data=data, method=method,
+                                 headers={"Content-Type": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read(12_000_000)
+    except urllib.error.HTTPError as exc:
+        detail = exc.read(300).decode("utf-8", "replace") if binary is False else ""
+        raise FsspAssistError(f"runtime http {exc.code}: {detail[:160]}") from exc
+    except urllib.error.URLError as exc:
+        raise FsspAssistError(f"runtime unreachable: {str(exc.reason)[:80]}") from exc
+    if binary:
+        return raw
+    try:
+        return json.loads(raw.decode("utf-8", "replace") or "{}")
+    except json.JSONDecodeError:
+        return {"raw": raw.decode("utf-8", "replace")[:400]}
+
+
+def _state_dir(state_dir: Path) -> Path:
+    d = Path(state_dir) / "fssp_assist"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _save(sess: dict) -> None:
+    d = _state_dir(Path(sess["state_dir"]))
+    (d / f"{sess['session_id']}.json").write_text(
+        json.dumps(sess, ensure_ascii=False), encoding="utf-8")
+
+
+def _load(session_id: str, state_dir: Path) -> dict:
+    p = _state_dir(state_dir) / f"{session_id}.json"
+    if not p.is_file():
+        raise FsspAssistError(f"session not found: {session_id}")
+    sess = json.loads(p.read_text(encoding="utf-8"))
+    if time.time() - sess.get("created_at", 0) > _TTL_S:
+        raise FsspAssistError("session expired (30 min); start fresh or use manual contour")
+    return sess
+
+
+def _breaker_trip(url: str) -> None:
+    try:
+        from sud_cli.sud_netguard import breaker_trip
+        breaker_trip(url, reason="fssp_assist_limited")
+    except Exception:
+        pass
+
+
+_LIMIT_RE = re.compile(r"превысили лимит|попробуйте позже", re.I)
+_CAPTCHA_RE = re.compile(r"captcha|капч|смарт-?каптча|не робот", re.I)
+_RESULT_WORDS = re.compile(r"найдено|результат|исполнительное производство|отсутству", re.I)
+
+
+_FORM_MARK = re.compile(r"Наименование предприятия-должника|Фамилия", re.I)
+_RESULT_MARK = re.compile(
+    r"исполнительн\w* производств\w* (?:не )?(?:найдено|отсутству)"
+    r"|найдено (?:исполнительных )?производств"
+    r"|^.*\bдолжник\b", re.I | re.M)
+_CAPTCHA_MARK = re.compile(r"captcha|каптч|не робот|robot check|challenge|подтвердите,? что", re.I)
+
+
+def _detect_page(text: str, *, pre: bool = False) -> str:
+    body = text or ""
+    if _LIMIT_RE.search(body):
+        return "limited"
+    if _CAPTCHA_MARK.search(body):
+        return "captcha"
+    if not pre and _RESULT_MARK.search(body):
+        return "result"
+    if _FORM_MARK.search(body):
+        return "form"
+    return "unknown"
+
+
+def _close_tab(user_id: str, tab_id: str) -> None:
+    """Закрыть вкладку (пул не должен копить мёртвые сессии)."""
+    try:
+        _api("DELETE", f"/tabs/{tab_id}", query={"userId": user_id})
+    except Exception:
+        pass
+
+
+def start(state_dir: Path, *, kind: str, name: Optional[str] = None,
+          inn: Optional[str] = None, birth_date: Optional[str] = None) -> dict:
+    """Открыть БДИП и заполнить форму; капчу — не решает."""
+    kind = (kind or "").strip().lower()
+    if kind not in ("fiz", "ur"):
+        raise FsspAssistError("kind must be fiz|ur")
+    if not (name or inn):
+        raise FsspAssistError("provide --name or --inn")
+    sid = secrets.token_hex(6)
+    user_id = f"sud-fssp-{sid}"
+    tab = _api("POST", "/tabs", body={"userId": user_id, "sessionKey": sid, "url": FSSP_URL})
+    tab_id = tab.get("tabId") or (tab.get("tab") or {}).get("tabId")
+    if not tab_id:
+        raise FsspAssistError(f"runtime did not return tabId: {str(tab)[:120]}")
+    _api("POST", f"/tabs/{tab_id}/wait", body={"userId": user_id, "timeout": 15000})
+    snap = _api("GET", f"/tabs/{tab_id}/snapshot", query={"userId": user_id}, timeout=60)
+    text = snap.get("snapshot") or snap.get("text") or snap.get("raw") or json.dumps(snap, ensure_ascii=False)
+    state = _detect_page(text, pre=True)
+    sess = {"session_id": sid, "tab_id": tab_id, "user_id": user_id,
+            "state_dir": str(state_dir), "kind": kind, "name": name, "inn": inn,
+            "birth_date": birth_date, "created_at": time.time(), "page_state": state}
+    if state == "limited":
+        _breaker_trip(FSSP_URL)
+        sess["status"] = "limited"
+        sess["hint"] = ("ФССП ограничила подключения с exit IP; хост уведён в cooldown. "
+                        "Повторите позже или используйте ручной контур: fssp check.")
+        _close_tab(user_id, tab_id)
+        _save(sess)
+        return sess
+    if state in ("form", "unknown"):
+        try:
+            filled = _fill_form(user_id, tab_id, kind=kind, name=name, inn=inn,
+                                birth_date=birth_date)
+            sess["fill"] = filled
+            if filled.get("submitted"):
+                _api("POST", f"/tabs/{tab_id}/wait", body={"userId": user_id, "timeout": 15000})
+                snap2 = _api("GET", f"/tabs/{tab_id}/snapshot", query={"userId": user_id})
+                t2 = snap2.get("snapshot") or snap2.get("text") or ""
+                state = _detect_page(t2, pre=False)
+                sess["page_state"] = state
+                sess["page_text"] = t2[:4000]
+        except FsspAssistError as exc:
+            sess["page_state"] = "page_changed"
+            sess["hint"] = f"автозаполнение не удалось: {exc}; используйте fssp check"
+            _close_tab(user_id, tab_id)
+    if sess["page_state"] == "captcha":
+        png = _state_dir(Path(state_dir)) / f"{sid}.png"
+        raw = _api("GET", f"/tabs/{tab_id}/screenshot", query={"userId": user_id, "fullPage": "true"},
+                   timeout=60, binary=True)
+        png.write_bytes(raw if isinstance(raw, (bytes, bytearray)) else b'')
+        sess["status"] = "waiting_human_captcha"
+        sess["captcha_image"] = str(png)
+        sess["instruction"] = ("Решите капчу на скриншоте, пришлите код: "
+                               f"sud-cli fssp assist --resume {sid} --code <КОД>")
+    elif sess["page_state"] == "result":
+        sess["status"] = "done"
+        sess["results_text"] = sess.get("page_text", "")
+    else:
+        sess["status"] = sess.get("page_state", "unknown")
+    _save(sess)
+    return sess
+
+
+def _fill_form(user_id: str, tab_id: str, *, kind: str, name: Optional[str],
+               inn: Optional[str], birth_date: Optional[str]) -> dict:
+    """Заполнение формы БДИП по калиброванным подписям (a11y-снапшот 25.10)."""
+    script = r"""((kind, name, inn, bd) => {
+      const vis = el => el && el.offsetParent !== null;
+      const labOf = el => {
+        let n = el.previousElementSibling;
+        let txt = '';
+        while (n && !txt) { txt = (n.innerText || n.textContent || '').trim(); n = n.previousElementSibling; }
+        return txt + ' ' + (el.placeholder || '') + ' ' + (el.name || '') + ' ' + (el.id || '');
+      };
+      const setVal = (el, v) => {
+        const desc = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value');
+        if (desc && desc.set) desc.set.call(el, v); else el.value = v;
+        el.dispatchEvent(new Event('input', {bubbles: true}));
+        el.dispatchEvent(new Event('change', {bubbles: true}));
+      };
+      const inputs = [...document.querySelectorAll('input')].filter(e => vis(e) && (e.type === 'text' || !e.type));
+      const byLabel = re => inputs.find(e => re.test(labOf(e)));
+      const steps = [];
+      let done = 0;
+      const put = (re, val, tag) => {
+        if (!val) return;
+        const el = byLabel(re);
+        if (el) { setVal(el, val); steps.push(tag); done++; }
+      };
+      if (kind === 'fiz') {
+        const parts = (name || '').split(/\s+/);
+        put(/Фамилия/i, parts[0], 'last');
+        put(/Имя(?! и отчество)/i, parts[1], 'first');
+        put(/Отчество/i, parts[2], 'middle');
+        if (bd) put(/Дата рождения/i, bd, 'birth');
+      } else {
+        put(/Наименование предприятия-должника/i, name, 'ur-name');
+        put(/ИНН юридического лица/i, inn, 'ur-inn');
+      }
+      const btns = [...document.querySelectorAll('button, input[type=submit]')].filter(vis);
+      const btn = btns.find(b => /найт/i.test((b.innerText || b.value || '').trim()));
+      let submitted = false;
+      if (btn && done) { btn.click(); submitted = true; steps.push('submit'); }
+      return {steps, filled: done, submitted};
+    })"""
+    body = {"userId": user_id,
+            "expression": f"{script}({json.dumps(kind)}, {json.dumps(name)}, {json.dumps(inn)}, {json.dumps(birth_date)})",
+            "timeout": 15000}
+    out = _api("POST", f"/tabs/{tab_id}/evaluate", body=body)
+    res = out.get("result") if isinstance(out, dict) else None
+    if not isinstance(res, dict):
+        raise FsspAssistError(f"evaluate returned {str(out)[:120]}")
+    if not res.get("submitted"):
+        raise FsspAssistError(f"форма не распознана (заполнено полей: {res.get('filled')}); используйте fssp check")
+    return res
+
+
+def resume(state_dir: Path, session_id: str, code: str) -> dict:
+    """Ввести человеческий ответ капчи и забрать результат."""
+    sess = _load(session_id, state_dir)
+    if not code or not str(code).strip():
+        raise FsspAssistError("code required (what the human read from the captcha)")
+    user_id, tab_id = sess["user_id"], sess["tab_id"]
+    _api("POST", f"/tabs/{tab_id}/type", body={
+        "userId": user_id,
+        "selector": "input[name*='captch' i], input[id*='captch' i], input[name*='capcha' i], textarea[name*='captch' i]",
+        "text": str(code).strip(),
+    })
+    _api("POST", f"/tabs/{tab_id}/click", body={
+        "userId": user_id, "selector": "button, input[type=submit]"})
+    _api("POST", f"/tabs/{tab_id}/wait", body={"userId": user_id, "timeout": 20000})
+    snap = _api("GET", f"/tabs/{tab_id}/snapshot", query={"userId": user_id})
+    text = snap.get("text") or snap.get("snapshot") or json.dumps(snap, ensure_ascii=False)
+    state = _detect_page(text)
+    sess["page_state"] = state
+    sess["resumed_at"] = time.time()
+    if state == "result":
+        sess["status"] = "done"
+        sess["results_text"] = text[:4000]
+        sess["verdict"] = ("none" if re.search(r"не найдено|отсутству", text, re.I) else "found")
+        _close_tab(user_id, tab_id)
+    elif state == "limited":
+        _breaker_trip(FSSP_URL)
+        sess["status"] = "limited"
+        _close_tab(user_id, tab_id)
+    else:
+        sess["status"] = f"need_retry ({state})"
+    _save(sess)
+    return sess

sud_cli/fssp_stats.py

@@ -0,0 +1,105 @@
+"""S-61 (В) официальная статистика БДИП ФССП — агрегатный справочник.
+
+Акт legal 2026.10.25: общедоступный CSV статистики исполнительных производств
+(fssp.gov.ru/api/is/statistics/csv) годен как вспомогательный источник по
+ст. 7 8-ФЗ (достоверность оперативной информации). Для индивидуальных досье
+статистика проверку НЕ заменяет — только контекст/справки.
+
+Сетевой слой: тот же netguard-путь, что и остальные live-адаптеры
+(fail-closed egress, DNS-pin, no-redirect, size cap, per-host breaker на
+401/403/429/5xx-лимиты — ФССП ограничивает частые подключения, это штатно
+уводится в cooldown, не брутфорсится).
+"""
+from __future__ import annotations
+
+import csv
+import io
+from typing import Optional
+
+STATS_URL = "https://fssp.gov.ru/api/is/statistics/csv"
+
+_UA = ("Mozilla/5.0 (X11; Linux x86_64) Gecko/20100101 Firefox/126.0")
+
+
+class FsspStatsError(Exception):
+    """Без PII: статистика не содержит персональные данные по построению."""
+
+
+def _http_get(url: str, *, timeout: int = 30) -> bytes:
+    from sud_cli.sud_netguard import (
+        BreakerOpenError,
+        breaker_trip,
+        check_before_fetch,
+    )
+
+    try:
+        check_before_fetch(url)
+    except BreakerOpenError as exc:
+        raise FsspStatsError(f"host in cooldown (anti-ban breaker): {exc}") from exc
+
+    import urllib.error as _ue
+    import urllib.request as _ur
+
+    req = _ur.Request(url, headers={"User-Agent": _UA, "Accept": "text/csv,*/*"})
+
+    class _NoRedirect(_ur.HTTPRedirectHandler):
+        def redirect_request(self, *a, **k):
+            return None
+
+    try:
+        with _ur.build_opener(_NoRedirect()).open(req, timeout=timeout) as resp:
+            raw = resp.read(8_000_000)
+    except _ue.HTTPError as exc:
+        if exc.code in (301, 302, 303, 307, 308, 401, 403, 429) or exc.code >= 500:
+            breaker_trip(url, reason=f"fssp_stats_http_{exc.code}")
+        raise FsspStatsError(f"fssp stats http {exc.code}") from exc
+    except _ue.URLError as exc:
+        raise FsspStatsError("fssp stats unreachable: " + str(exc.reason)[:80]) from exc
+    return raw
+
+
+def _parse(raw: bytes) -> list[dict]:
+    text = raw.decode("utf-8-sig", errors="replace")
+    rows: list[dict] = []
+    try:
+        reader = csv.DictReader(io.StringIO(text), delimiter=";", quotechar='"')
+    except Exception as exc:  # noqa: BLE001
+        raise FsspStatsError("fssp stats: unparseable csv") from exc
+    for row in reader:
+        rid = (row.get("id") or "").strip()
+        title = (row.get("title") or "").strip()
+        count = (row.get("count") or "").strip()
+        if not rid or not title:
+            continue
+        try:
+            n = int(count)
+        except ValueError:
+            continue
+        rows.append({"region_id": rid, "region": title, "active_executions": n})
+    if not rows:
+        raise FsspStatsError("fssp stats: unexpected payload (no rows)")
+    return rows
+
+
+def statistics(region: Optional[str] = None, *, timeout: int = 30) -> dict:
+    """Общедоступная статистика БДИП: число активных ИП по подразделениям/регионам.
+
+    region — опциональный фильтр по id региона (префикс) или названию (подстрока).
+    """
+    raw = _http_get(STATS_URL, timeout=timeout)
+    rows = _parse(raw)
+    total = sum(r["active_executions"] for r in rows if r["region_id"] == "00")
+    if region:
+        needle = region.strip().lower()
+        rows = [r for r in rows
+                if r["region_id"] == needle or needle in r["region"].lower()]
+    return {
+        "source": STATS_URL,
+        "provider_label": "fssp.gov.ru (официальная статистика БДИП, ст. 7 8-ФЗ — оперативные данные)",
+        "region_filter": region,
+        "count": len(rows),
+        "rows": rows,
+        "note": ("Агрегатная статистика; индивидуальные проверки — ручной контур "
+                 "fssp check/record (юридическая проверка 25.10)."),
+        "center_total_hint": total,
+    }

sud_cli/government_transfers.json

@@ -0,0 +1,8 @@
+{
+  "source": "sud_cli/holidays_rf.json",
+  "verified_through": 2027,
+  "years": {
+    "2026": {"decree": "Постановление Правительства РФ от 24.09.2025 № 1466"},
+    "2027": {"decree": "Постановление Правительства РФ от 17.09.2026 № 1187"}
+  }
+}

sud_cli/holidays_rf.json

@@ -0,0 +1,62 @@
+{
+  "_note": "Production calendar for the Russian Federation, federal level only.",
+  "_source": "ст. 112 ТК РФ (fixed federal non-working holidays) + Government transfer decrees",
+  "_scope": "MVP per colleague-legal addendum 1.1.0 п.Б2. Regional holidays are NOT included.",
+  "_transfer_provenance": "Decrees were verified against the official portal scan, not transcribed from memory. Each entry records its own decree; a year without an entry keeps the CALENDAR_WARNING.",
+  "federal_holidays": {
+    "2024": ["01-01", "01-02", "01-03", "01-04", "01-05", "01-06", "01-07", "01-08",
+             "02-23", "03-08", "05-01", "05-09", "06-12", "11-04"],
+    "2025": ["01-01", "01-02", "01-03", "01-04", "01-05", "01-06", "01-07", "01-08",
+             "02-23", "03-08", "05-01", "05-09", "06-12", "11-04"],
+    "2026": ["01-01", "01-02", "01-03", "01-04", "01-05", "01-06", "01-07", "01-08",
+             "02-23", "03-08", "05-01", "05-09", "06-12", "11-04"],
+    "2027": ["01-01", "01-02", "01-03", "01-04", "01-05", "01-06", "01-07", "01-08",
+             "02-23", "03-08", "05-01", "05-09", "06-12", "11-04"]
+  },
+  "_transfer_note": "Days moved in by a Government decree (a weekday declared a day off) or out of a holiday. Both directions matter: a day moved OUT becomes an ordinary working day, and one moved IN becomes non-working.",
+  "transfers": {
+    "2026": {
+      "decree": "Постановление Правительства РФ от 24.09.2025 № 1466 «О переносе выходных дней в 2026 году»",
+      "decree_number": 1466,
+      "decree_date": "2025-09-24",
+      "published": "официальный интернет-портал правовой информации, 24.09.2025, N 0001202509240023; СЗ РФ, 29.09.2025, N 39, ст. 5738",
+      "url": "http://publication.pravo.gov.ru/document/0001202509240023",
+      "amendments_found": false,
+      "extra_days_off": ["01-09", "12-31"],
+      "extra_days_off_reason": "с субботы 3 января на пятницу 9 января; с воскресенья 4 января на четверг 31 декабря (второй абзац ч. 1 ст. 112 ТК РФ — новогодние переносы делает только Правительство)",
+      "days_restored_to_working": []
+    },
+    "2027": {
+      "decree": "Постановление Правительства РФ от 17.09.2026 № 1187 «О переносе выходных дней в 2027 году»",
+      "decree_number": 1187,
+      "decree_date": "2026-09-17",
+      "published": "официальный интернет-портал правовой информации, 18.09.2026, N 0001202609180037",
+      "url": "http://publication.pravo.gov.ru/document/0001202609180037",
+      "amendments_found": false,
+      "extra_days_off": ["02-22", "11-05", "12-31"],
+      "extra_days_off_reason": "с субботы 20 февраля на понедельник 22 февраля (выходной переносится на рабочий понедельник, поскольку 23 февраля — праздник); с субботы 2 января на пятницу 5 ноября; с воскресенья 3 января на пятницу 31 декабря. Первые два новогодних переноса делает только Правительство (абз. 2 ч. 1 ст. 112 ТК РФ), первый — из общего правила ч. 2 ст. 112.",
+      "days_restored_to_working": ["02-20"],
+      "days_restored_to_working_reason": "с субботы 20 февраля на понедельник 22 февраля. Перенос двусторонний: 20 февраля перестаёт быть выходным (иначе появляется лишний нерабочий день), 22 февраля им становится. Без этой строки февраль 2027 даёт 18 рабочих дней вместо 19 по опубликованному календарю.",
+      "verification": "Прочитан со скана официального портала (publication.pravo.gov.ru/file/pdf?eoNumber=0001202609180037), 1 страница. Дни недели в тексте постановления сверены: 02.01.2027 = суббота, 03.01.2027 = воскресенье, 20.02.2027 = суббота, 22.02.2027 = понедельник. Контрольный счёт: 247 рабочих / 118 выходных и праздничных за 2027 год — совпадает с опубликованным производственным календарём."
+    }
+  },
+  "_auto_transfer_note": "ч. 2 ст. 112 ТК РФ: a holiday landing on a weekend moves to the next working day automatically, EXCEPT the holidays named in абз. 2 and 3 of the same article (1–8 января, 23 февраля) — for those only the Government may move the day off. The automatic moves below are therefore derived from ст. 112, not from the decree.",
+  "auto_transfers_st112": {
+    "2026": [
+      {"holiday": "03-08", "weekday": "воскресенье", "moved_to": "03-09"},
+      {"holiday": "05-09", "weekday": "суббота", "moved_to": "05-11"}
+    ],
+    "2027": [
+      {"holiday": "05-01", "weekday": "суббота", "moved_to": "05-03"},
+      {"holiday": "05-09", "weekday": "воскресенье", "moved_to": "05-10"},
+      {"holiday": "06-12", "weekday": "суббота", "moved_to": "06-14"}
+    ]
+  },
+  "transfer_decrees_encoded": true,
+  "years_with_verified_transfers": [2026, 2027],
+  "verified_through": 2027,
+  "known_years": [2024, 2025, 2026, 2027],
+  "warning_template": "CALENDAR_WARNING: расчёт произведён по базовым выходным (сб/вс), ст. 112 ТК РФ и автопереносам, но перенос Правительства РФ за {year} год НЕ зашит (постановление не подтверждено). Фактические нерабочие дни могут отличаться.",
+  "no_warning_template": "Переносы Правительства РФ за {year} год учтены ({decree}). Переносы, введённые позже этой даты, не учтены.",
+  "regional_note": "Региональные нерабочие праздничные дни субъектов РФ не учитываются."
+}

sud_cli/idempotency.py

@@ -0,0 +1,78 @@
+"""W6a §1 (S-80): реестр идемпотентности write-инструментов MCP.
+
+Повтор write-вызова с тем же ``idempotency_key`` в окне 10 минут обязан
+вернуть ПЕРВЫЙ результат, а не устроить вторую запись. Реестр живёт в
+state-dir (``idempotency.json``, права 0600 — в значении могут быть реквизиты
+дела) и чистится по тому же окну: запись старше 600 с больше ничего не
+подавляет.
+
+Границы: модуль не знает про сеть и про MCP-транспорт — только чтение/запись
+одного файла. Повреждённый реестр трактуется как пустой (fail-open для
+легальных записей): потерянное подавление повтора видимо по audit-журналу, а
+заблокировать законный вызов молча — худший из исходов.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+WINDOW_SECONDS = 600  # окно подавления повторов: 10 минут = первый результат
+REGISTRY_NAME = "idempotency.json"
+
+
+def registry_path(state_dir) -> Path:
+    return Path(state_dir) / REGISTRY_NAME
+
+
+def _load(state_dir) -> dict:
+    path = registry_path(state_dir)
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _entry_id(tool: str, key: str) -> str:
+    return f"{tool}|{key}"
+
+
+def lookup(state_dir, tool: str, key: str, now: float | None = None):
+    """Первый результат по (tool, key), если он ещё в окне; иначе None."""
+    now = time.time() if now is None else now
+    entry = _load(state_dir).get(_entry_id(tool, key))
+    if not isinstance(entry, dict):
+        return None
+    try:
+        ts = float(entry.get("ts", 0))
+    except (TypeError, ValueError):
+        return None
+    if now - ts > WINDOW_SECONDS:
+        return None
+    result = entry.get("result")
+    return result if isinstance(result, dict) else None
+
+
+def record(state_dir, tool: str, key: str, result: dict, now: float | None = None) -> None:
+    """Сохранить первый результат; записи вне окна вычищаются заодно."""
+    now = time.time() if now is None else now
+    state_dir = Path(state_dir)
+    state_dir.mkdir(parents=True, exist_ok=True)
+    data = _load(state_dir)
+    data = {
+        k: v for k, v in data.items()
+        if isinstance(v, dict) and (now - float(v.get("ts") or 0)) <= WINDOW_SECONDS
+    }
+    data[_entry_id(tool, key)] = {"ts": now, "result": result}
+    path = registry_path(state_dir)
+    tmp = path.with_name(path.name + ".tmp")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(data, fh, ensure_ascii=False, sort_keys=True)
+        os.replace(tmp, path)
+    finally:
+        tmp.unlink(missing_ok=True)
+    os.chmod(path, 0o600)