sud-cli 0.1.1__py3-none-any.whl

sud_cli/explain.py

@@ -0,0 +1,190 @@
+"""W6a §2 (S-81): --explain — человекочитаемая цепочка расчёта.
+
+Конверт команды с флагом получает блок ``explain`` из четырёх секций:
+какие НОРМЫ применялись (norm_ref из rules; verbatim legal_text там, где он
+есть в правилах), какие ДАННЫЕ (тарифная редакция, ставки, штампы
+производственного календаря), какие ФОРМУЛЫ (шаги breakdown/trace движка) и
+что осталось РУЧНЫМ (manual_review причины).
+
+Zero-граница: explain не печатает тексты норм вне правил — для
+reference_only-записей отдаётся fetch_hint="npa_as_of" (тот же контракт, что
+W2b в jurisdiction/fees_extra). Байт-стабильность старых конвертов: без
+флага --explain этот модуль к конверту не прикасается.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+EXPLAIN_POLICY = ("explain собран только из rules-данных движка; тексты норм вне правил "
+                  "не выводятся — reference_only даёт fetch_hint=npa_as_of")
+
+
+def envelope(command: str, norms: Optional[List[dict]] = None,
+             data: Optional[List[dict]] = None, formulas: Optional[List[str]] = None,
+             manual_review: Optional[List[Any]] = None) -> dict:
+    return {
+        "command": command,
+        "norms": norms or [],
+        "data": data or [],
+        "formulas": formulas or [],
+        "manual_review": manual_review or [],
+        "policy": EXPLAIN_POLICY,
+    }
+
+
+def _norm_from_formula(formula: str) -> Optional[str]:
+    if not formula:
+        return None
+    head = formula.split(":", 1)[0].strip()
+    return head or None
+
+
+def fees_explain(*, fee_doc: dict, rules: dict, as_of_iso: Optional[str]) -> dict:
+    basis = rules.get("tariff_basis") or {}
+    norms = []
+    art = _norm_from_formula(fee_doc.get("formula") or "")
+    if art:
+        norms.append({"norm_ref": art, "source": "legal_rules.json"})
+    norms.append({"norm_ref": "ст. 333.19, 333.21 НК РФ",
+                  "source": "legal_rules.json (tariff_basis)"})
+    data = [
+        {"item": "rules", "version": rules.get("version"),
+         "tariff_version": rules.get("tariff_version"),
+         "legal_status": rules.get("legal_status")},
+        {"item": "tariff_basis", "federal_law": basis.get("federal_law"),
+         "effective_from": basis.get("effective_from")},
+        {"item": "rounding", **{k: (rules.get("rounding") or {}).get(k)
+                                for k in ("article", "mode")}},
+    ]
+    meta = fee_doc.get("meta") or {}
+    if as_of_iso:
+        data.append({"item": "tariff_edition", "as_of": as_of_iso,
+                     "edition_id": meta.get("edition_id"),
+                     "window": meta.get("tariff_effective_window") or meta.get("window"),
+                     "warnings": meta.get("warnings") or []})
+    formulas = []
+    if fee_doc.get("formula"):
+        formulas.append(fee_doc["formula"])
+    for step in fee_doc.get("breakdown") or []:
+        if isinstance(step, dict) and step.get("step"):
+            formulas.append(step["step"])
+    manual = []
+    if fee_doc.get("status") != "ok":
+        manual.append({"reason": "status != ok", "detail": fee_doc.get("detail")})
+    if meta.get("manual_reason"):
+        manual.append({"reason": meta["manual_reason"]})
+    return envelope("fees", norms=norms, data=data, formulas=formulas, manual_review=manual)
+
+
+def deadlines_explain(*, payload: dict, rules: dict, event_date: Optional[str],
+                      region: Optional[str], tz: Optional[str]) -> dict:
+    cal = rules.get("production_calendar") or {}
+    entry = (rules.get("deadline_matrix") or {})
+    norms = []
+    if payload.get("legal_basis"):
+        norms.append({"norm_ref": payload["legal_basis"], "source": "legal_rules.json (deadline_matrix)"})
+    data = [
+        {"item": "spec", "spec_version": rules.get("spec_version"),
+         "legal_status": rules.get("legal_status")},
+        {"item": "calendar", "status": cal.get("status"), "as_of": cal.get("as_of"),
+         "shift_enabled": cal.get("shift_enabled"),
+         "transfers_encoded_through": cal.get("government_transfers_encoded_through")},
+        {"item": "inputs", "event_date": event_date, "region": region, "tz": tz},
+    ]
+    formulas = [t.get("step") for t in payload.get("trace") or [] if isinstance(t, dict) and t.get("step")]
+    manual = []
+    if payload.get("status") != "ok":
+        manual.append({"reason": "status != ok", "detail": payload.get("detail")})
+    for w in payload.get("warnings") or []:
+        manual.append({"reason": "warning", "detail": w})
+    return envelope("deadlines", norms=norms, data=data, formulas=[str(f) for f in formulas], manual_review=manual)
+
+
+def limitation_explain(*, payload: dict, period_type: str, start: str,
+                       check_date: Optional[str]) -> dict:
+    norms = [{"norm_ref": n, "source": "limitation.PERIODS (ст.-ссылки движка)"}
+             for n in payload.get("legal_basis") or []]
+    data = [{"item": "inputs", "period_type": period_type, "start": start,
+             "check_date": check_date}]
+    formulas = [t.get("step") for t in payload.get("trace") or [] if isinstance(t, dict) and t.get("step")]
+    manual = []
+    if payload.get("status") != "ok":
+        manual.append({"reason": "status != ok", "detail": payload.get("detail")})
+    return envelope("limitation", norms=norms, data=data, formulas=[str(f) for f in formulas], manual_review=manual)
+
+
+def interest_explain(*, payload: dict, article: str, amount, start: str, end: str) -> dict:
+    norms = [{"norm_ref": f"ст. {article} ГК РФ", "source": "движок interest.py (ст.-ссылка)"}]
+    data = [
+        {"item": "inputs", "amount": amount, "start": start, "end": end},
+        {"item": "key_rates", **(payload.get("rates_meta") or {})},
+    ]
+    formulas = []
+    for p in payload.get("periods") or []:
+        if isinstance(p, dict):
+            formulas.append(
+                f"{p.get('from')}..{p.get('to')}: {p.get('principal_rub')} × {p.get('days')}/{p.get('year_days', '—')} × {p.get('rate')}% = {p.get('amount_rub')}")
+    manual = [{"reason": "rates warning", "detail": w} for w in payload.get("rates_warnings") or []]
+    return envelope("interest", norms=norms, data=data, formulas=formulas, manual_review=manual)
+
+
+def pretrial_explain(*, payload: dict, code: str, sent: Optional[str]) -> dict:
+    norms = []
+    if payload.get("norm"):
+        norms.append({"norm_ref": payload["norm"], "source": "jurisdiction_rules.json (pretrial)"})
+    data = [{"item": "rule", "code": code, "rule": payload.get("rule"),
+             "days": payload.get("days"), "calendar": payload.get("calendar"),
+             "exclude_nonworking_holidays": payload.get("exclude_nonworking_holidays")}]
+    formulas = []
+    if payload.get("sent") and payload.get("deadline"):
+        formulas.append(f"{payload['sent']} + {payload.get('days')} кал.дн -> {payload['deadline']}"
+                        + (" (с переносом на рабочий день)" if payload.get("exclude_nonworking_holidays") else ""))
+    manual = [{"reason": m.get("reason"), "norm": m.get("norm"), "scope": m.get("scope")}
+              for m in payload.get("manual_review") or [] if isinstance(m, dict)]
+    if payload.get("error"):
+        manual.append({"reason": payload["error"], "detail": str(payload.get("warnings") or "")})
+    return envelope("pretrial", norms=norms, data=data, formulas=formulas, manual_review=manual)
+
+
+def pretrial_consequences_explain(*, payload: dict, code: str, stage: str) -> dict:
+    norms = []
+    if payload.get("norm"):
+        norms.append({"norm_ref": payload["norm"], "source": "jurisdiction_rules.json (consequences)"})
+    data = [{"item": "selection", "code": code, "stage": stage,
+             "consequence": payload.get("consequence"), "confidence": payload.get("confidence")}]
+    manual = []
+    if payload.get("confidence") not in (None, "hard"):
+        manual.append({"reason": "confidence != hard", "detail": payload.get("confidence")})
+    return envelope("pretrial consequences", norms=norms, data=data, formulas=[], manual_review=manual)
+
+
+def jurisdiction_explain(*, payload: dict, code: str, claim: Optional[str]) -> dict:
+    norms = []
+    for cand in payload.get("candidates") or []:
+        if not isinstance(cand, dict):
+            continue
+        entry = {"norm_ref": cand.get("venue_basis"), "confidence": cand.get("confidence")}
+        if cand.get("legal_text"):
+            entry["verbatim"] = cand["legal_text"]  # verbatim берётся из правил
+        if cand.get("fetch_hint"):
+            entry["fetch_hint"] = cand["fetch_hint"]
+        norms.append(entry)
+    data = [{"item": "inputs", "code": code, "claim": claim,
+             "rules_version_key": "jurisdiction_rules.json"}]
+    formulas = [f"кандидат #{i + 1}: {c.get('venue_basis')} ({c.get('confidence')})"
+                for i, c in enumerate(payload.get("candidates") or []) if isinstance(c, dict)]
+    manual = [{"reason": m.get("reason"), "norm": m.get("norm")}
+              for m in payload.get("manual_review") or [] if isinstance(m, dict)]
+    return envelope("jurisdiction check", norms=norms, data=data, formulas=formulas, manual_review=manual)
+
+
+def verify_explain(*, payload: dict, text_len: int) -> dict:
+    data = [{"item": "source", "source": payload.get("source"),
+             "location": payload.get("location"),
+             "path": payload.get("path"), "case_id": payload.get("case_id"),
+             "max_fuzzy": payload.get("max_fuzzy"), "requested_len": text_len}]
+    formulas = [f"verdict={payload.get('status')} offset={payload.get('offset')} ratio={payload.get('ratio')}"]
+    manual = []
+    if payload.get("status") in ("not_found", "edition_unavailable"):
+        manual.append({"reason": payload.get("status"), "detail": payload.get("detail")})
+    return envelope("verify quote", norms=[], data=data, formulas=formulas, manual_review=manual)

sud_cli/fees_extra.py

@@ -0,0 +1,104 @@
+"""W4c: льготы 333.35-37, возврат 333.40, рамка индексации 183/208/189.1.
+
+Основания — ТОЛЬКО fee_exemptions_and_refunds из legal_rules.json
+(VERIFIED pack colleague-legal, акт 2026.10.24). Список категорий в акте —
+выборка, а не полный перечень статьи: совпадения нет => manual_review с
+fetch_hint, права додумывать категории движок не имеет.
+Индексация считается ТОЛЬКО по ИПЦ, явно переданному оператором (данных
+Росстата в репозитории нет; выдумывать коэффициент запрещено).
+"""
+from __future__ import annotations
+
+from decimal import Decimal, ROUND_HALF_UP
+from typing import Optional
+
+DISCLAIMER = ("Расчёт справочный: льготы применяются судом по представленным "
+              "документам; категории — VERIFIED-выборка legal, не полный перечень статьи.")
+
+_JURIS_TO_EXEMPT_KEY = {
+    "apk": "exemptions_333_37",
+    "gpk": "exemptions_333_36",
+    "sayu": "exemptions_333_36",
+    "kas": "exemptions_333_36",
+}
+
+
+def _pack(rules: dict) -> dict:
+    return rules.get("fee_exemptions_and_refunds", {})
+
+
+def fee_exemption_check(rules: dict, *, jurisdiction: str, category_code: str) -> dict:
+    pack = _pack(rules)
+    keys = [_JURIS_TO_EXEMPT_KEY.get(str(jurisdiction).lower()), "exemptions_333_35"]
+    hits = []
+    for k in keys:
+        if not k:
+            continue
+        for cat in pack.get(k, {}).get("categories", []):
+            if cat.get("code") == category_code:
+                hits.append({**cat, "statute": pack[k]["statute"]})
+    if hits:
+        full = [h for h in hits if h.get("exempt_level") == "full"] or hits
+        h = full[0]
+        return {"status": "exempt", "exempt_level": h.get("exempt_level"),
+                "basis": h.get("basis"), "description": h.get("description"),
+                "statute": h.get("statute"), "warnings": [DISCLAIMER]}
+    return {"status": "manual_review",
+            "detail": f"категория '{category_code}' не в VERIFIED-выборке; полный текст "
+                      f"ст.333.35-37 — npa_as_of, не догадка движка",
+            "fetch_hint": "npa_as_of", "warnings": [DISCLAIMER]}
+
+
+def fee_refund(rules: dict, *, paid: Decimal, ground: str,
+               claim_admitted: bool = False, plaintiff_default: bool = False,
+               transferred_to_arbitration: bool = False) -> dict:
+    pack = _pack(rules)
+    grounds = {g["code"]: g for g in pack.get("refund_333_40", {}).get("grounds", [])}
+    if ground not in grounds:
+        return {"status": "manual_review", "detail": f"основание '{ground}' не из VERIFIED списка",
+                "known": sorted(grounds), "warnings": [DISCLAIMER]}
+    g = grounds[ground]
+    share = Decimal(str(g.get("refund_share", 1)))
+    notes = [g.get("condition", "")]
+    if ground == "dismissed_no_consideration" and (plaintiff_default or transferred_to_arbitration):
+        share = Decimal("0")
+        notes.append("исключение VERIFIED-условия: неявка истца / передача в третейский суд — возврат не положен")
+    if ground.startswith("settlement") and claim_admitted:
+        share = Decimal("0")
+        notes.append("исключение VERIFIED-условия: признание иска ответчиком — 70/50/30% не применяются")
+    amount = (paid * share).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+    return {"status": "ok", "ground": ground, "basis": g["basis"], "share": str(share),
+            "paid": str(paid), "refund_amount": str(amount), "conditions": [n for n in notes if n],
+            "statute": pack.get("refund_333_40", {}).get("statute", "ст. 333.40 НК РФ"),
+            "warnings": [DISCLAIMER]}
+
+
+def indexation_frame(rules: dict, *, code: str) -> dict:
+    idx = _pack(rules).get("interest_and_indexation", {}).get("indexation_procedural", {})
+    frame = idx.get(str(code).lower())
+    if not frame:
+        return {"status": "manual_review", "detail": f"нет VERIFIED рамки для '{code}'",
+                "known": sorted(idx)}
+    return {"status": "frame_only", "index": frame.get("index"),
+            "period_start": frame.get("period_start"), "period_end": frame.get("period_end"),
+            "statute": frame.get("statute"),
+            "calc_hint": "sud-cli fees indexation --code X --amount S --cpi-start A --cpi-end B "
+                         "(ИПЦ явно оператором; данных Росстата в пакете нет)",
+            "warnings": ["ИПЦ Росстата в репозитории нет: расчёт только по явно переданному "
+                         "официальному значению; выдуманный коэффициент = фальсификация (правило «тексты только из реестра»)."]}
+
+
+def indexation_compute(rules: dict, *, code: str, amount: Decimal,
+                       cpi_start: Optional[Decimal], cpi_end: Optional[Decimal]) -> dict:
+    f = indexation_frame(rules, code=code)
+    if f["status"] != "frame_only":
+        return f
+    if cpi_start is None or cpi_end is None or cpi_start <= 0:
+        return {**f, "status": "data_unavailable",
+                "detail": "нужны --cpi-start/--cpi-end (официальные значения ИПЦ Росстата)"}
+    indexed = (amount * (cpi_end / cpi_start)).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+    return {"status": "ok", "basis": f["statute"], "amount": str(amount),
+            "cpi_start": str(cpi_start), "cpi_end": str(cpi_end),
+            "indexed_amount": str(indexed), "provenance": "user-supplied CPI, unverified against Росстат",
+            "period": {"start": f["period_start"], "end": f["period_end"]},
+            "warnings": [DISCLAIMER]}

sud_cli/forms.py

@@ -0,0 +1,204 @@
+"""the wave §4 (S-70): структурные скелеты процессуальных форм + bus-free docx-команда.
+
+Границы:
+- только структурные скелеты с плейсхолдерами [ФИО]/[дело]/[дата] и данными
+  дела из реестра (обезличенно: case_number/court/plaintiff/defendant);
+- НИКАКИХ нормативных цитат: в модуле нет ни одной ссылки «ст.» с номером,
+  и тесты гейтят это regex'ом и по исходнику, и по выводу;
+- sud никогда не запускает docx-конвертер: docx_command собирает готовую
+  shlex-экранированную строку (паттерн reminders/alerts) и пишет spec-файл;
+  модуль не импортирует ничего, что умеет поднимать внешние процессы;
+- deferral-шаблон госпошлины НЕ дублируется: вид otsrochka даёт структуру и
+  ссылку-команду на существующий генератор `sud-cli deferral`.
+
+SYNC ТОЧКА §3<->§4: заголовки markdown-секций ниже = маркеры
+data/completeness_rules.json (hodat: Шапка/Просьба/Подпись/Дата;
+appeal: +Обжалуется/Основания/Приложения). Меняешь маркер — меняй заголовок,
+тесты test_v2120_3 расходятся первыми.
+"""
+import json
+import shlex
+import tempfile
+from pathlib import Path
+
+FORM_KINDS = ("vosstanovlenie_sroka", "otsrochka", "appeal_structure")
+
+#: вид формы -> checklist-kind из completeness_rules.json (единый набор маркеров)
+CHECKLIST_KIND_FOR_FORM = {
+    "vosstanovlenie_sroka": "hodat",
+    "otsrochka": "hodat",
+    "appeal_structure": "appeal_apk",
+}
+
+BUS_FREE_NOTE = (
+    "bus-free: sud-cli не запускает docx-конвертер; ниже готовая экранированная "
+    "строка команды — исполнение остаётся за оператором"
+)
+
+VERIFY_CMD_TEMPLATE = '/usr/bin/sud-cli form new {kind} --case {case_id} --format md'
+
+
+def _case_fields(case):
+    case = case or {}
+    return {
+        "case_id": case.get("case_id"),
+        "case_number": case.get("case_number") or "[дело]",
+        "court": case.get("court") or "[суд]",
+        "plaintiff": case.get("plaintiff") or "[истец]",
+        "defendant": case.get("defendant") or "[ответчик]",
+    }
+
+
+def _header(c):
+    return (
+        "## Шапка\n"
+        f"В [суд]: {c['court']}\n"
+        f"Дело [дело] N {c['case_number']}\n"
+        f"[истец]: {c['plaintiff']}\n"
+        f"[ответчик]: {c['defendant']}\n"
+    )
+
+
+def _skeleton_vosstanovlenie(c):
+    return (
+        "# Ходатайство о восстановлении процессуального срока (структурный скелет)\n\n"
+        + _header(c)
+        + "\n## Просьба\n"
+        "Прошу восстановить пропущенный срок для [действие].\n"
+        "[причина пропуска]: ...; [момент, с которым связан срок]: ...\n"
+        "[доказательства уважительности]: ...\n\n"
+        "## Подпись\n"
+        "[ФИО] ________________________\n\n"
+        "## Дата\n"
+        "[ДД.ММ.ГГГГ]\n"
+    )
+
+
+def _skeleton_otsrochka(c):
+    return (
+        "# Ходатайство об отсрочке (рассрочке) уплаты государственной пошлины (структурный скелет)\n\n"
+        + _header(c)
+        + "\n## Просьба\n"
+        "Прошу предоставить отсрочку (рассрочку) уплаты пошлины в размере [сумма] до [ДД.ММ.ГГГГ].\n"
+        "[обстоятельства имущественного положения]: ...\n\n"
+        "## Приложения\n"
+        "[справка банка об остатках]\n[иные документы]\n\n"
+        "## Подпись\n"
+        "[ФИО] ________________________\n\n"
+        "## Дата\n"
+        "[ДД.ММ.ГГГГ]\n\n"
+        "---\n"
+        "Существующий шаблон ходатайства об отсрочке пошлины НЕ дублируется: "
+        "полный текст даёт команда `sud-cli deferral --applicant ... --court ... "
+        "--amount ... --reason ...`.\n"
+    )
+
+
+def _skeleton_appeal(c):
+    return (
+        "# Апелляционная жалоба (структурный скелет)\n\n"
+        + _header(c)
+        + "\n## Обжалуется\n"
+        "Судебный акт от [ДД.ММ.ГГГГ] по делу N " + str(c["case_number"]) + ".\n\n"
+        "## Основания\n"
+        "[довод 1]: ...\n[довод 2]: ...\n\n"
+        "## Просьба\n"
+        "Прошу [решение по результату рассмотрения].\n\n"
+        "## Приложения\n"
+        "[копия судебного акта]\n[документы, подтверждающие доводы]\n\n"
+        "## Подпись\n"
+        "[ФИО] ________________________\n\n"
+        "## Дата\n"
+        "[ДД.ММ.ГГГГ]\n"
+    )
+
+
+_BUILDERS = {
+    "vosstanovlenie_sroka": _skeleton_vosstanovlenie,
+    "otsrochka": _skeleton_otsrochka,
+    "appeal_structure": _skeleton_appeal,
+}
+
+
+def render_skeleton(kind, case):
+    if kind not in _BUILDERS:
+        raise ValueError(f"unknown form kind: {kind}")
+    return _BUILDERS[kind](_case_fields(case))
+
+
+def _as_sections(kind, case):
+    """json-представление: список {heading, body} без потери структуры md."""
+    text = render_skeleton(kind, case)
+    sections = []
+    current = None
+    for line in text.splitlines():
+        if line.startswith("#"):
+            if current:
+                sections.append(current)
+            current = {"heading": line.lstrip("# ").strip(), "body": ""}
+        elif current is not None:
+            current["body"] = (current["body"] + "\n" + line).strip("\n")
+    if current:
+        sections.append(current)
+    return sections
+
+
+def render_form(kind, case, fmt="md"):
+    """Формы: markdown|json. Только чтение данных дела, без сайд-эффектов."""
+    if fmt not in ("md", "json"):
+        raise ValueError(f"unknown format: {fmt}")
+    skeleton = render_skeleton(kind, case)
+    if fmt == "md":
+        return {
+            "status": "ok",
+            "kind": kind,
+            "format": "md",
+            "checklist_kind": CHECKLIST_KIND_FOR_FORM[kind],
+            "case": _case_fields(case),
+            "text": skeleton,
+        }
+    return {
+        "status": "ok",
+        "kind": kind,
+        "format": "json",
+        "checklist_kind": CHECKLIST_KIND_FOR_FORM[kind],
+        "case": _case_fields(case),
+        "sections": _as_sections(kind, case),
+    }
+
+
+def build_docx_spec(kind, case):
+    return {
+        "generator": "sud-cli form docx-command",
+        "kind": kind,
+        "case": _case_fields(case),
+        "content_md": render_skeleton(kind, case),
+    }
+
+
+def docx_command(kind, case, spec_dir=None):
+    """Готовая shlex-строка docx-cli build; sud НИКОГДА не вызывает её сам.
+
+    Паттерн reminders/alerts: сборка строки + запись spec-файла. Никаких
+    внешних процессов: исполнение — осознанный шаг оператора.
+    """
+    case_id = _case_fields(case)["case_id"] or "[case]"
+    spec = build_docx_spec(kind, case)
+    if spec_dir is None:
+        spec_dir = Path(tempfile.mkdtemp(prefix="sud-form-"))
+    else:
+        spec_dir = Path(spec_dir)
+        spec_dir.mkdir(parents=True, exist_ok=True)
+    spec_path = spec_dir / f"{kind}-{case_id}-spec.json"
+    spec_path.write_text(json.dumps(spec, ensure_ascii=False, indent=2), encoding="utf-8")
+    verify = VERIFY_CMD_TEMPLATE.format(kind=kind, case_id=case_id)
+    parts = ["docx-cli", "build", "--spec", str(spec_path), "--verify", verify, "--verify-run"]
+    command = " ".join(shlex.quote(p) for p in parts)
+    return {
+        "status": "ok",
+        "kind": kind,
+        "command": command,
+        "spec_path": str(spec_path),
+        "verify_command": verify,
+        "bus_free": BUS_FREE_NOTE,
+    }

sud_cli/fssp_manual.py

@@ -0,0 +1,91 @@
+"""S-61 (Б) ручной контур ФССП — human-in-the-loop проверка БДИП.
+
+Акт legal 2026.10.25 (проверено): официальный публичный API
+ФССП отключён с 10.03.2022; обход капчи/лимитов запрещён. Утверждён базовый путь:
+sud-cli готовит ссылку и чек-лист, капчу проходит человек с личного устройства,
+результат фиксируется в досье как доказательство с provenance (кто/когда/чем
+подтверждено). Внешние действия — за человеком (канон S-62).
+
+Этот модуль НЕ выполняет сетевых запросов: только план проверки и оформление
+результата. Данные ФССП носит ориентирующий характер (ст. 7 8-ФЗ о достоверности
+оперативной информации): при споре подтверждать первоисточником/запросом.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+FSSP_BASE_URL = "https://fssp.gov.ru/iss/ip/"
+
+_KINDS = {"fiz", "ur"}
+
+CHECKLIST = [
+    "Откройте ссылку на личном устройстве (не с серверного IP: ФССП лимитирует частые подключения).",
+    "Выберите раздел: поиск по физическим лицам / юридических лицах.",
+    "Введите параметры из плана ниже; при возможности сузьте регионом.",
+    "Дождитесь ответа капчи/проверки; сделайте скриншот результата (или сохраните PDF).",
+    "Вернитесь в sud-cli: fssp record — результат попадёт в реестр доказательств дела с отметкой provenance.",
+    "Для процессуального использования: данные БДИП ориентирующие; при споре подтвердите запросом в ОСП/первоисточником.",
+]
+
+
+def _require(condition: bool, message: str) -> None:
+    if not condition:
+        raise ValueError(message)
+
+
+def check_plan(kind: str, *, name: Optional[str] = None, inn: Optional[str] = None,
+               ogrn: Optional[str] = None, birth_date: Optional[str] = None,
+               region: Optional[str] = None) -> dict:
+    """Собрать план ручной проверки БДИП ФССП (без сетевых запросов)."""
+    kind = (kind or "").strip().lower()
+    _require(kind in _KINDS, f"kind must be one of {sorted(_KINDS)}")
+    params: dict[str, str] = {}
+    if kind == "fiz":
+        _require(bool(name), "for kind=fiz provide --name (ФИО)")
+        params["ФИО"] = str(name).strip()
+        if birth_date:
+            params["дата рождения"] = birth_date.strip()
+    else:
+        _require(bool(name or inn or ogrn),
+                 "for kind=ur provide --name or --inn/--ogrn")
+        if name:
+            params["наименование"] = name.strip()
+        if inn:
+            params["ИНН"] = inn.strip()
+        if ogrn:
+            params["ОГРН"] = ogrn.strip()
+    if region:
+        params["регион"] = region.strip()
+    return {
+        "url": FSSP_BASE_URL,
+        "kind": kind,
+        "params": params,
+        "checklist": list(CHECKLIST),
+        "disclaimer": ("Данные Банка данных исполнительных производств носят ориентирующий характер; "
+                       "проверку выполняет человек с личного устройства; результат фиксируется "
+                       "в досье с provenance. Автоматический обход капчи/лимитов запрещён (юридическая проверка 25.10)."),
+    }
+
+
+def record_payload(*, subject: str, result: str, checked_by: str,
+                   notes: Optional[str] = None,
+                   evidence_file: Optional[str] = None) -> dict:
+    """Оформить результат ручной проверки для реестра доказательств.
+
+    title/note — без чужих ПДн pass-through сверх введённых самим оператором;
+    файл доказательства (скрин/PDF) хранится отдельно, здесь только путь.
+    """
+    result = (result or "").strip().lower()
+    _require(bool(subject and subject.strip()), "subject required")
+    _require(bool(checked_by and checked_by.strip()), "checked_by required")
+    _require(result in {"none", "found", "inconclusive"},
+             "result must be none|found|inconclusive")
+    verdict = {"none": "производств не найдено",
+               "found": "производства найдены",
+               "inconclusive": "проверка не завершена/неоднозначно"}[result]
+    title = f"Ручная проверка ФССП БДИП: {subject.strip()}"
+    note = f"Результат: {verdict}. Проверил(а): {checked_by.strip()}. Источник: {FSSP_BASE_URL} (ориентирующие данные)."
+    if notes:
+        note += f" Примечание: {notes.strip()}"
+    return {"title": title, "note": note, "result": result,
+            "evidence_file": evidence_file}