sud-cli 0.1.1__py3-none-any.whl

sud_cli/metrics.py

@@ -0,0 +1,142 @@
+"""история §5 (S-86): метрики state-dir — счётчики из таблиц, без выдуманных KPI.
+
+Границы:
+- ни одного «индекса здоровья», «риска» или «прогресса»: поле за полем это
+  COUNT(*)/GROUP BY по реальным таблицам sud-cli;
+- письма/журнал не трогаем — это шина a2a, не данные sud (bus-free);
+- last backup берётся из ``meta``: путь пишет сам ``backup create``, и ничего
+  не вынюхивается по диску;
+- пустая таблица даёт 0, а отсутствующая секция — []/{}: числа выводятся
+  только из запросов, «среднего» не выдумываем.
+"""
+from __future__ import annotations
+
+from datetime import date as _date
+from typing import Any, Dict, Optional
+
+from .db import (
+    LEGAL_CASE_STATUSES,
+    get_connection,
+    init_db,
+    list_all_deadline_states,
+    list_cases,
+)
+
+#: Окна совпадают с agenda/reminders: своё «среднее» окно здесь не изобретается.
+NEAR_DAYS = 30
+REMINDERS_DAYS = 7
+
+METRICS_DISCLAIMER = (
+    "Метрики — счётчики строк локального реестра (state tables). Это не KPI "
+    "и не оценка качества работы: sud-cli наблюдает только внесённые данные."
+)
+
+_TABLES_WITH_CASE = (
+    "events",
+    "case_amounts",
+    "case_documents",
+    "case_notes",
+    "deadline_states",
+    "evidence_items",
+    "case_representatives",
+)
+
+
+def _counts_by_status(cases) -> Dict[str, int]:
+    """Все статусы enum'а всегда на месте: пустой портфель даёт нули, не {}."""
+    out = {s: 0 for s in LEGAL_CASE_STATUSES}
+    for c in cases:
+        key = c.get("status") if c.get("status") is not None else "unknown"
+        out[key] = out.get(key, 0) + 1
+    return out
+
+
+def metrics_payload(state_dir: Any, today: Optional[_date] = None,
+                    near_days: int = NEAR_DAYS) -> Dict[str, Any]:
+    init_db(state_dir)
+    conn = get_connection(state_dir)
+    try:
+        today = today or _date.today()
+        cases = list_cases(conn)
+        states = list_all_deadline_states(conn)
+
+        states_by_state: Dict[str, int] = {}
+        for s in states:
+            key = str(s.get("state"))
+            states_by_state[key] = states_by_state.get(key, 0) + 1
+
+        from .reminders import due_items
+        from .reports import _near_overdue
+
+        reminders_pending = len(due_items(states, today, REMINDERS_DAYS))
+        near, over, _agenda = _near_overdue(state_dir, today, near_days)
+
+        rows_per_table: Dict[str, int] = {}
+        for table in _TABLES_WITH_CASE:
+            rows_per_table[table] = int(
+                conn.execute(f"SELECT COUNT(*) AS n FROM {table}").fetchone()["n"]
+            )
+
+        docs_revisions = int(conn.execute(
+            "SELECT COUNT(*) AS n FROM case_documents WHERE supersedes IS NOT NULL"
+        ).fetchone()["n"])
+        evidence_without_hash = int(conn.execute(
+            "SELECT COUNT(*) AS n FROM evidence_items WHERE sha256 IS NULL"
+        ).fetchone()["n"])
+        reps_by_side = {
+            str(row["side"]): int(row["n"])
+            for row in conn.execute(
+                "SELECT side, COUNT(*) AS n FROM case_representatives "
+                "GROUP BY side ORDER BY side ASC"
+            ).fetchall()
+        }
+
+        from .backup import last_backup
+
+        last = last_backup(state_dir)
+    finally:
+        conn.close()
+
+    return {
+        "as_of": today.isoformat(),
+        "cases": {"total": len(cases), "by_status": _counts_by_status(cases)},
+        "events": rows_per_table["events"],
+        "deadline_states": {"total": len(states), "by_state": states_by_state},
+        "deadlines_window": {
+            "near_days": near_days,
+            "near": len(near),
+            "overdue": len(over),
+        },
+        "documents": {"total": rows_per_table["case_documents"],
+                      "revisions": docs_revisions},
+        "evidence": {"total": rows_per_table["evidence_items"],
+                     "without_hash": evidence_without_hash},
+        "representatives": {"total": rows_per_table["case_representatives"],
+                            "by_side": reps_by_side},
+        "notes": rows_per_table["case_notes"],
+        "amounts": rows_per_table["case_amounts"],
+        "reminders": {"pending_days": REMINDERS_DAYS, "pending": reminders_pending},
+        "rows_per_table": rows_per_table,
+        "backup": {
+            "last": last,
+            "recorded_in": "meta",
+        },
+        "disclaimer": METRICS_DISCLAIMER,
+    }
+
+
+def doctor_metrics(state_dir: Any) -> Dict[str, Any]:
+    """Сжатая секция для doctor: те же счётчики, без вложенных окон."""
+    payload = metrics_payload(state_dir)
+    return {
+        "cases": payload["cases"],
+        "events": payload["events"],
+        "deadline_states": payload["deadline_states"],
+        "deadlines_window": payload["deadlines_window"],
+        "documents": payload["documents"],
+        "evidence": payload["evidence"],
+        "representatives": payload["representatives"],
+        "reminders": payload["reminders"],
+        "backup": payload["backup"],
+        "disclaimer": payload["disclaimer"],
+    }

sud_cli/npa_as_of.py

@@ -0,0 +1,21 @@
+"""Lookup of bundled historical editions of selected Russian codes."""
+
+import json
+from datetime import date
+from pathlib import Path
+
+DATA_PATH = Path(__file__).with_name("data") / "npa_historical_editions.json"
+
+
+def lookup_as_of(act, article, on_date, path=None):
+    try:
+        target = date.fromisoformat(on_date) if isinstance(on_date, str) else on_date
+        records = json.loads(Path(path or DATA_PATH).read_text(encoding="utf-8"))
+        rows = records.get(act, {}).get(str(article), [])
+        eligible = [row for row in rows if date.fromisoformat(row["effective_date"]) <= target]
+        if not eligible:
+            return {"status": "error", "detail": "historical edition not found for requested date"}
+        row = max(eligible, key=lambda item: item["effective_date"])
+        return {"status": "ok", "act": act, "article": str(article), **row}
+    except (OSError, json.JSONDecodeError, ValueError, TypeError) as exc:
+        return {"status": "error", "detail": str(exc)}

sud_cli/output.py

@@ -0,0 +1,89 @@
+"""Stable output formatting for sud-cli."""
+
+import json
+import sys
+
+
+HUMAN = "human"
+JSON = "json"
+
+
+def emit(data, json_mode=False, stream=None):
+    """Emit a stable result document to *stream*.
+
+    In JSON mode the document is always a single JSON object with at least:
+      - status: "ok" | "error" | "blocked"
+      - data:   the payload (None for errors/blocks without payload)
+      - meta:   runtime metadata (command, state_dir, version)
+    In human mode a concise plain-text rendering is printed.
+    """
+    if stream is None:
+        stream = sys.stdout
+    if json_mode:
+        stream.write(json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True))
+        stream.write("\n")
+    else:
+        _render_human(data, stream)
+
+
+def _render_human(data, stream):
+    status = data.get("status")
+    payload = data.get("data")
+    meta = data.get("meta", {})
+
+    if status == "ok":
+        if isinstance(payload, list):
+            stream.write(f"{len(payload)} result(s)\n")
+            for item in payload:
+                stream.write(_format_item(item) + "\n")
+        elif isinstance(payload, dict):
+            for key, value in sorted(payload.items()):
+                stream.write(f"{key}: {value}\n")
+        else:
+            stream.write(str(payload) + "\n")
+    elif status == "blocked":
+        stream.write(f"BLOCKED / NOT_IMPLEMENTED: {payload}\n")
+    elif status == "error":
+        stream.write(f"ERROR: {payload}\n")
+    else:
+        stream.write(str(payload) + "\n")
+
+    if meta.get("truncated"):
+        stream.write("(results truncated)\n")
+    if "limit" in meta:
+        stream.write(f"limit: {meta['limit']}\n")
+    if "total" in meta:
+        stream.write(f"total: {meta['total']}\n")
+
+
+def _format_item(item):
+    if isinstance(item, dict):
+        return " | ".join(f"{k}={v}" for k, v in sorted(item.items()))
+    return str(item)
+
+
+def result(payload, meta=None, json_mode=False, stream=None):
+    meta = meta or {}
+    emit({"status": "ok", "data": payload, "meta": meta}, json_mode=json_mode, stream=stream)
+
+
+def error(message, meta=None, json_mode=False, stream=None, code=1):
+    meta = meta or {}
+    if stream is None:
+        stream = sys.stderr
+    emit({"status": "error", "data": message, "meta": meta}, json_mode=json_mode, stream=stream)
+    return code
+
+
+def blocked(message, meta=None, json_mode=False, stream=None):
+    """Report a command that was not attempted (gate closed, capability absent).
+
+    Writes to stderr like ``error``: the project convention is that stdout
+    carries only successful payloads, so an agent parsing stdout must not meet
+    a refusal there.
+    """
+    meta = meta or {}
+    if stream is None:
+        stream = sys.stderr
+    emit({"status": "blocked", "data": message, "meta": meta}, json_mode=json_mode, stream=stream)
+    return 1

sud_cli/payment.py

@@ -0,0 +1,24 @@
+"""Payment details and purpose text for state fees."""
+
+KBK = {
+    "eks": "182 1 08 01000 01 1050 110",
+    "arbitration": "182 1 08 01000 01 1050 110",
+    "general_jurisdiction": "182 1 08 03010 01 1050 110",
+    "soyu": "182 1 08 03010 01 1050 110",
+    "supreme_court": "182 1 08 03000 01 1050 110",
+}
+
+
+def payment_details(jurisdiction, amount, court, defendant):
+    key = "general_jurisdiction" if jurisdiction in {"soyu", "general_jurisdiction", "kas"} else jurisdiction
+    if key not in KBK:
+        raise ValueError(f"unknown jurisdiction: {jurisdiction}")
+    amount = int(amount)
+    return {
+        "status": "ok",
+        "kbk": KBK[key],
+        "eks": "Единый казначейский счет",
+        "jurisdiction": jurisdiction,
+        "amount_rub": amount,
+        "purpose": f"Государственная пошлина за рассмотрение искового заявления в {court} к {defendant}. Сумма: {amount} руб. Без НДС.",
+    }

sud_cli/pdn.py

@@ -0,0 +1,259 @@
+"""история §5 (S-07): права субъекта — маш-читаемый экспорт дела и полное уничтожение.
+
+Границы:
+- НИКАКИХ нормативных текстов от себя: основания, срок хранения и перечень
+  прав берутся дословно из блока ``pdn_policy`` правил (legal_rules.json,
+  v1.4.0 финальная) — строки не печатаются по памяти и не хардкодятся;
+- экспорт = данные для субъекта/юриста: полные, без выдуманных сокращений и
+  без «маскирования на глаз»; audit-записи по делу включаются как есть,
+  потому что вырезание части данных — это и есть сокращение;
+- purge = уничтожение: каскад строк всех таблиц дела + физические файлы из
+  case_documents/evidence, а в audit — только ФАКТ (id/дата/actor/счётчики).
+  ПДн в audit не попадает: ни имён сторон, ни текстов, ни путей файлов.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .db import (
+    PURGE_TABLES,
+    case_file_paths,
+    case_row_counts,
+    get_case,
+    get_case_card,
+    get_connection,
+    init_db,
+    list_case_documents,
+    purge_case,
+    read_deadline_audit,
+    verify_case_evidence,
+    evidence_summary,
+)
+
+EXPORT_FORMATS = ("json", "md")
+
+#: Что именно выгружается — список секций печатается в конверте, чтобы
+#: приёмщик видел покрытие, а не догадывался о нём.
+EXPORT_SECTIONS = (
+    "case",
+    "events",
+    "amounts",
+    "documents",
+    "evidence",
+    "representatives",
+    "deadline_states",
+    "notes",
+    "audit",
+)
+
+
+def pdn_policy(rules: Optional[dict] = None) -> Dict[str, Any]:
+    """Блок pdn_policy из правил (дословно, без правок и без дописываний)."""
+    if rules is None:
+        from .legal_engine import load_rules
+
+        rules = load_rules()
+    return rules.get("pdn_policy", {}) or {}
+
+
+def pdn_reference_block(policy: Dict[str, Any]) -> Dict[str, Any]:
+    """Ссылочный блок для конвертов: только поля pdn_policy из правил."""
+    return {
+        "source": "legal_rules.json:pdn_policy",
+        "legal_status": policy.get("legal_status"),
+        "grounds": list(policy.get("grounds") or []),
+        "retention": policy.get("retention"),
+        "subject_rights": list(policy.get("subject_rights") or []),
+    }
+
+
+def export_case(state_dir: Any, case_id: str, fmt: str = "json",
+                rules: Optional[dict] = None) -> Optional[Dict[str, Any]]:
+    """Полный дамп дела + ссылочный блок pdn_policy (дословно из правил)."""
+    if fmt not in EXPORT_FORMATS:
+        raise ValueError(f"unknown format: {fmt} (допустимо: {', '.join(EXPORT_FORMATS)})")
+    if rules is None:
+        from .legal_engine import load_rules
+
+        rules = load_rules()
+    init_db(state_dir)
+    conn = get_connection(state_dir)
+    try:
+        if get_case(conn, case_id) is None:
+            return None
+        card = get_case_card(conn, case_id)
+        docs = list_case_documents(conn, case_id)
+        evidence_items = verify_case_evidence(conn, case_id)
+        summary = evidence_summary(evidence_items)
+        rows = case_row_counts(conn, case_id)
+        audit = read_deadline_audit(state_dir, case_id)
+    finally:
+        conn.close()
+
+    policy = pdn_policy(rules)
+    payload: Dict[str, Any] = {
+        "case_id": case_id,
+        "format": fmt,
+        "sections": list(EXPORT_SECTIONS),
+        "row_counts": {t: rows.get(t, 0) for t in PURGE_TABLES},
+        "case": card.get("case"),
+        "parties": card.get("parties"),
+        "events": card.get("events"),
+        "amounts": card.get("amounts"),
+        "documents": docs,
+        "evidence": {
+            "items": evidence_items,
+            "summary": {k: v for k, v in summary.items() if k != "problem_items"},
+        },
+        "representatives": card.get("representatives"),
+        "deadline_states": card.get("deadlines"),
+        "notes": card.get("notes"),
+        # audit включается целиком: вырезание записей = сокращение данных,
+        # а экспорт для субъекта/юриста по определению без сокращений.
+        "audit": audit,
+        "pdn": pdn_reference_block(policy),
+        "completeness_note": (
+            "Дамп содержит все строки реестра по этому делу: ни одна секция не "
+            "сокрощена, не «обезличена на лету» и не усечена лимитом. Числа "
+            "row_counts — фактическое количество удалённых/выгруженных строк, "
+            "а не оценка."
+        ),
+    }
+    return payload
+
+
+def render_export_md(payload: Dict[str, Any]) -> str:
+    """md-рендер дампа: заголовки секций + таблицы/списки из фактических строк."""
+    case = payload.get("case") or {}
+    lines: List[str] = [
+        f"# Экспорт дела {payload['case_id']}",
+        "",
+        f"- номер: {case.get('case_number')}",
+        f"- суд: {case.get('court')}",
+        f"- статус: {case.get('status')}",
+        f"- instance: {case.get('instance')}",
+        f"- owner: {case.get('owner')}",
+        f"- истец: {(payload.get('parties') or {}).get('plaintiff')}",
+        f"- ответчик: {(payload.get('parties') or {}).get('defendant')}",
+        "",
+        "## Покрытие (row_counts)",
+        "",
+        "| таблица | строк |",
+        "| --- | --- |",
+    ]
+    for table in PURGE_TABLES:
+        lines.append(f"| {table} | {payload['row_counts'].get(table, 0)} |")
+
+    def _block(title: str, items: Any) -> None:
+        lines.append("")
+        lines.append(f"## {title}")
+        lines.append("")
+        if not items:
+            lines.append("_пусто_")
+            return
+        if isinstance(items, dict):
+            items = [items]
+        for item in items:
+            if isinstance(item, dict):
+                for key in sorted(item):
+                    value = item[key]
+                    if value is None or value == "" or value == []:
+                        continue
+                    lines.append(f"- **{key}**: {value}")
+                lines.append("")
+            else:
+                lines.append(f"- {item}")
+
+    _block("События", payload.get("events"))
+    _block("Суммы", payload.get("amounts"))
+    _block("Документы (с хэшами)", payload.get("documents"))
+    _block("Доказательства", (payload.get("evidence") or {}).get("items"))
+    _block("Представители", (payload.get("representatives") or {}).get("items"))
+    _block("Состояния сроков", payload.get("deadline_states"))
+    _block("Заметки", payload.get("notes"))
+    _block("Журнал правок сроков (audit)", payload.get("audit"))
+
+    pdn = payload.get("pdn") or {}
+    lines += [
+        "",
+        "## ПДн: основания и срок (дословно из pdn_policy правил)",
+        "",
+        f"Источник: {pdn.get('source')}",
+        f"Статус блока: {pdn.get('legal_status')}",
+        "",
+        "Основания обработки:",
+    ]
+    lines += [f"- {g}" for g in (pdn.get("grounds") or [])] or ["- (в правилах нет)"]
+    lines += ["", "Срок хранения:", f"- {pdn.get('retention')}", "",
+              "Права субъекта:"]
+    lines += [f"- {r}" for r in (pdn.get("subject_rights") or [])] or ["- (в правилах нет)"]
+    lines += ["", payload.get("completeness_note", "")]
+    return "\n".join(lines) + "\n"
+
+
+def purge_preview(state_dir: Any, case_id: str,
+                  rules: Optional[dict] = None) -> Optional[Dict[str, Any]]:
+    """Превью уничтожения: счётчики строк + файлы + retention-hint из правил."""
+    if rules is None:
+        from .legal_engine import load_rules
+
+        rules = load_rules()
+    init_db(state_dir)
+    conn = get_connection(state_dir)
+    try:
+        if get_case(conn, case_id) is None:
+            return None
+        counts = case_row_counts(conn, case_id)
+        files = case_file_paths(conn, case_id)
+    finally:
+        conn.close()
+    policy = pdn_policy(rules)
+    return {
+        "case_id": case_id,
+        "will_delete_rows": {t: counts.get(t, 0) for t in PURGE_TABLES},
+        "will_delete_files": files,
+        "file_count": len(files),
+        "audit_after_purge": (
+            "в audit попадёт только запись о факте: case id, дата, actor, "
+            "счётчики; содержимое дела в журнал не пишется"
+        ),
+        "retention_hint": policy.get("retention"),
+        "pdn": pdn_reference_block(policy),
+        "requires": "--yes (деструктив без подтверждения не исполняется)",
+    }
+
+
+def purge_apply(state_dir: Any, case_id: str, confirmed: bool = False,
+                actor: str = "cli", rules: Optional[dict] = None,
+                remove_files: bool = True) -> Dict[str, Any]:
+    """Уничтожение дела. Без confirmed — только превью, ноль изменений.
+
+    remove_files=False (--keep-files) оставляет строки case_documents нетронутыми
+    по отношению к диску: файлы чужие (общий каталог сканов), а строк дела это
+    не меняет — каскад таблиц всё равно полный.
+    """
+    if rules is None:
+        from .legal_engine import load_rules
+
+        rules = load_rules()
+    preview = purge_preview(state_dir, case_id, rules=rules)
+    if preview is None:
+        return {"status": "not_found", "case_id": case_id}
+    if not confirmed:
+        return {
+            "status": "needs_confirmation",
+            "detail": "purge уничтожает данные дела безвозвратно: нужен --yes",
+            "preview": preview,
+        }
+    init_db(state_dir)
+    conn = get_connection(state_dir)
+    try:
+        result = purge_case(conn, state_dir, case_id, actor=actor,
+                            remove_files=remove_files)
+    finally:
+        conn.close()
+    result["status"] = "purged"
+    result["files_kept"] = not remove_files
+    result["retention_hint"] = preview["retention_hint"]
+    result["pdn"] = preview["pdn"]
+    return result

sud_cli/plenum_corpus.py

@@ -0,0 +1,134 @@
+"""Корпус разъяснений высших судов (S-55, акт 25.10 §3).
+
+Карточка судебного акта жёстко структурирована, цитаты несут sha256 фрагмента.
+Наполнение — только нормативно-выверенными цитатами официальных публикаций
+ВС РФ / ВАС РФ (источники: vsrf.ru/documents/, pravo.gov.ru, «Бюллетень ВС РФ»,
+ФКЗ № 8-ФКЗ о сохраняющей силе актов ВАС РФ).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from pathlib import Path
+from typing import Optional
+
+SEED_FILE = Path(__file__).with_name("plenums_seed.json")
+CARD_KEYS = ("doc_id", "court", "instance", "doc_type", "number", "date", "title",
+             "official_sources", "status", "paragraphs")
+_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+_ID_RE = re.compile(r"^[A-Z0-9_]+$")
+
+
+class PlenumError(ValueError):
+    pass
+
+
+def sha256_text(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def validate_card(card: dict) -> list[str]:
+    """Вернуть список нарушений (пусто = карточка валидна)."""
+    errs: list[str] = []
+    for k in CARD_KEYS:
+        if k not in card:
+            errs.append(f"нет поля {k}")
+    if not errs:
+        if not _ID_RE.match(str(card["doc_id"])):
+            errs.append("doc_id должен быть CAPS_UNDERSCORE")
+        if not _DATE_RE.match(str(card["date"])):
+            errs.append("date в формате YYYY-MM-DD")
+        if not isinstance(card["official_sources"], list) or not card["official_sources"]:
+            errs.append("official_sources: непустой список")
+        if not isinstance(card["paragraphs"], list) or not card["paragraphs"]:
+            errs.append("paragraphs: непустой список")
+    for p in card.get("paragraphs", []):
+        if "verbatim_text" not in p or "sha256" not in p:
+            errs.append("в параграфе нужны verbatim_text+sha256")
+        elif sha256_text(p["verbatim_text"]) != p["sha256"]:
+            errs.append(f"параграф {p.get('paragraph_no')}: sha256 не сходится")
+    return errs
+
+
+def import_card(card: dict, *, rehash: bool = False) -> dict:
+    """Импортировать карточку. rehash=True — пересчитать sha256 (при расхождении
+    с источником-актом; исходный хэш сохраняется как act_recorded_sha256)."""
+    errs = validate_card(card)
+    if errs and rehash:
+        only_hash_mismatch = all("sha256" in e for e in errs)
+        if only_hash_mismatch:
+            for p in card["paragraphs"]:
+                p["act_recorded_sha256"] = p["sha256"]
+                p["sha256"] = sha256_text(p["verbatim_text"])
+                p["hash_note"] = "пересчитано при импорте 25.10; хэш акта сохранён"
+            errs = validate_card(card)
+    if errs:
+        raise PlenumError("; ".join(errs))
+    return card
+
+
+def store_path(state_dir: Path) -> Path:
+    return Path(state_dir) / "plenums.json"
+
+
+def _load(state_dir: Path) -> list[dict]:
+    sp = store_path(state_dir)
+    if sp.exists():
+        return json.loads(sp.read_text(encoding="utf-8")).get("cards", [])
+    seed = json.loads(SEED_FILE.read_text(encoding="utf-8")).get("cards", [])
+    sp.parent.mkdir(parents=True, exist_ok=True)
+    sp.write_text(json.dumps({"cards": seed}, ensure_ascii=False, indent=2), encoding="utf-8")
+    return json.loads(sp.read_text(encoding="utf-8")).get("cards", [])
+
+
+def list_cards(state_dir: Path) -> list[dict]:
+    out = []
+    for c in _load(state_dir):
+        out.append({"doc_id": c["doc_id"], "date": c["date"], "number": c["number"],
+                    "title": c["title"], "status": c["status"],
+                    "instance": c.get("instance", ""), "doc_type": c.get("doc_type", "")})
+    return out
+
+
+def get_card(state_dir: Path, doc_id: str) -> dict:
+    for c in _load(state_dir):
+        if c["doc_id"] == doc_id:
+            return c
+    raise PlenumError(f"карточка {doc_id} не найдена")
+
+
+def search(state_dir: Path, text: str) -> list[dict]:
+    needle = (text or "").lower()
+    hits = []
+    for c in _load(state_dir):
+        for p in c.get("paragraphs", []):
+            blob = " ".join([str(p.get("key_topic", "")), p.get("verbatim_text", ""),
+                             c.get("title", "")]).lower()
+            if needle and needle in blob:
+                hits.append({"doc_id": c["doc_id"], "paragraph_no": p.get("paragraph_no"),
+                             "key_topic": p.get("key_topic", ""),
+                             "norm_links": p.get("norm_links", []),
+                             "excerpt": p["verbatim_text"][:240]})
+    return hits
+
+
+def verify(state_dir: Path) -> dict:
+    cards = _load(state_dir)
+    bad = []
+    for c in cards:
+        for p in c.get("paragraphs", []):
+            if sha256_text(p.get("verbatim_text", "")) != p.get("sha256"):
+                bad.append(f"{c['doc_id']}#{p.get('paragraph_no')}")
+    return {"cards": len(cards), "ok": not bad, "broken": bad}
+
+
+def add_card(state_dir: Path, card: dict, *, rehash: bool = True) -> dict:
+    card = import_card(card, rehash=rehash)
+    sp = store_path(state_dir)
+    cards = _load(state_dir)
+    if any(c["doc_id"] == card["doc_id"] for c in cards):
+        raise PlenumError(f"карточка {card['doc_id']} уже в корпусе")
+    cards.append(card)
+    sp.write_text(json.dumps({"cards": cards}, ensure_ascii=False, indent=2), encoding="utf-8")
+    return {"doc_id": card["doc_id"], "paragraphs": len(card["paragraphs"])}