ktalk-cli 1.0.0__py3-none-any.whl

ktalk_cli/host_config.py

@@ -0,0 +1,136 @@
+"""Discovery, парсинг и валидация `.ktalk.toml` — конфигурации проекта-хозяина.
+
+SA-003 (`content/40-architecture/ktalk-plugin-spec.md`), FR-20. Отдельный модуль
+от `registry.py` (грандфазер заморожен на 562 строках). Не пишет файлы и не
+создаёт каталоги — только читает и валидирует (границы спеки).
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_KNOWN_TOP_LEVEL_KEYS = {"registry", "directories", "routing", "integrations"}
+_CONFIG_FILE_NAME = ".ktalk.toml"
+
+
+class HostConfigError(Exception):
+    """`.ktalk.toml` не парсится TOML-синтаксисом или проваливает валидацию схемы.
+
+    Именует конкретный файл и причину — процесс останавливается на этом шаге, не
+    продолжает работу на дефолте молча (ktalk-plugin-spec.md, «Поведение при
+    малформенном файле»).
+    """
+
+
+@dataclass
+class HostConfig:
+    """Распарсенный и провалидированный `.ktalk.toml`.
+
+    Каждая секция — `dict`-подобная с `.get(...)`; отсутствующий ключ означает
+    «не объявлен», не «объявлен пустым» (FR-20 AC-2/AC-3, FR-24 деградация).
+    """
+
+    registry: dict = field(default_factory=dict)
+    directories: dict = field(default_factory=dict)
+    routing: dict = field(default_factory=dict)
+    integrations: dict = field(default_factory=dict)
+
+
+def _validate_string_map(section_name: str, section: dict, path: Path) -> None:
+    for key, value in section.items():
+        if not isinstance(value, str):
+            raise HostConfigError(
+                f"{path}: {section_name}.{key} должен быть строкой, получено {type(value).__name__}"
+            )
+
+
+def load_host_config(path: str | Path) -> HostConfig:
+    """Парсит и валидирует `.ktalk.toml` по указанному пути.
+
+    Пустой/отсутствующий-по-ключам файл — валиден (FR-20 AC-2, boundary): каждая
+    секция трактуется как отсутствующая по отдельности, не как ошибка.
+    """
+    path = Path(path)
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise HostConfigError(f"{path}: не удалось прочитать файл: {exc}") from exc
+
+    try:
+        data = tomllib.loads(raw)
+    except tomllib.TOMLDecodeError as exc:
+        raise HostConfigError(f"{path}: некорректный TOML-синтаксис: {exc}") from exc
+
+    unknown = set(data.keys()) - _KNOWN_TOP_LEVEL_KEYS
+    if unknown:
+        raise HostConfigError(
+            f"{path}: неизвестные секции {sorted(unknown)} "
+            f"(ожидаются только {sorted(_KNOWN_TOP_LEVEL_KEYS)})"
+        )
+
+    registry = data.get("registry", {})
+    directories = data.get("directories", {})
+    routing = data.get("routing", {})
+    integrations = data.get("integrations", {})
+
+    for name, section in (
+        ("registry", registry),
+        ("directories", directories),
+        ("routing", routing),
+        ("integrations", integrations),
+    ):
+        if not isinstance(section, dict):
+            raise HostConfigError(f"{path}: секция [{name}] должна быть таблицей")
+
+    if "db_path" in registry and not isinstance(registry["db_path"], str):
+        raise HostConfigError(f"{path}: registry.db_path должен быть строкой")
+    _validate_string_map("directories", directories, path)
+    _validate_string_map("routing", routing, path)
+    if "qmd" in integrations and not isinstance(integrations["qmd"], bool):
+        raise HostConfigError(f"{path}: integrations.qmd должен быть булевым")
+
+    return HostConfig(
+        registry=registry,
+        directories=directories,
+        routing=routing,
+        integrations=integrations,
+    )
+
+
+def discover_host_config(project_dir: str | Path | None = None) -> HostConfig | None:
+    """Ищет и загружает `.ktalk.toml` (ktalk-plugin-spec.md, «Discovery»).
+
+    1. `project_dir` (явный оверрайд, тот же контракт, что и `${CLAUDE_PROJECT_DIR}`)
+       или `${CLAUDE_PROJECT_DIR}`, если задан, — конфиг ищется РОВНО по этому
+       корню, обхода вверх нет.
+    2. Иначе (голый CLI) — обход вверх от `cwd` до первого найденного
+       `.ktalk.toml`, либо до первого каталога с `.git` (граница проекта), либо
+       до корня файловой системы.
+    3. Ничего не найдено -> `None`, не ошибка (FR-20 AC-2). Малформенный
+       найденный файл -> `HostConfigError` доходит до вызывающей стороны, не
+       гасится тихим откатом (FR-20 AC-3).
+    """
+    if project_dir is not None:
+        root = Path(project_dir)
+        candidate = root / _CONFIG_FILE_NAME
+        return load_host_config(candidate) if candidate.is_file() else None
+
+    claude_project_dir = os.environ.get("CLAUDE_PROJECT_DIR")
+    if claude_project_dir:
+        candidate = Path(claude_project_dir) / _CONFIG_FILE_NAME
+        return load_host_config(candidate) if candidate.is_file() else None
+
+    current = Path.cwd()
+    while True:
+        candidate = current / _CONFIG_FILE_NAME
+        if candidate.is_file():
+            return load_host_config(candidate)
+        if (current / ".git").exists():
+            return None
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent

ktalk_cli/meeting_body.py

@@ -0,0 +1,178 @@
+"""FR-13/NFR-9: allow-list компоновщик тела встречи + канонический хеш (ADR-005
+«Решение», ADR-009 §1-4 — состав тела приведён к живому снимку DevTools).
+
+Единая функция принимает только согласованный постановкой набор полей — без
+`**kwargs` и без прохода через произвольный словарь вызывающего. `isRecurring`/
+`recurrence` и поля вне этого состава физически не имеют параметра, через который
+могли бы попасть в тело — структурная невозможность, не рантайм-фильтр. ADR-009
+расширяет тот же приём на `autoRunDeepFakeDetection`/`maskingSettings` и убирает
+`enableSip` тем же способом (параметра больше нет).
+
+ГИПОТЕЗА (ADR-009): состав тела и конвертация времени в UTC не проверены
+собственным боевым POST — построены по одному живому снимку DevTools, ревизуются
+следующей санкционированной попыткой.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from datetime import UTC, datetime
+
+from ktalk_cli.client import KTalkError
+
+_TIMEZONE_RE = re.compile(r"^GMT[+-](?:[0-9]|1[0-4])$")
+
+# ADR-009 §1-2: 12 полей от вызывающего/архитектуры + `description` с тихим
+# дефолтом = 13 ключей тела. `pinCode`/`anonymousAccessExpirationDate` не входят
+# в этот общий None-цикл — у них своя развилка (условная обязательность), не
+# плоское «передано/не передано».
+_REQUIRED = (
+    "subject",
+    "start",
+    "end",
+    "timezone",
+    "roomName",
+    "requiredAttendees",
+    "allowAnonymous",
+    "enableAutoRecording",
+)
+
+# ADR-009 §2: архитектурные константы — не параметры `build_meeting_body`, не
+# решения вызывающего, поэтому вне периметра NFR-9 (запрет тихих дефолтов
+# относится к полям, которые вызывающий мог бы решить, но не решил).
+_FIXED = {
+    "isRecurring": False,
+    "autoRunDeepFakeDetection": None,
+    "maskingSettings": {
+        "nameMaskingMode": "none",
+        "postMaskingMode": "none",
+        "showAdditionalInfo": True,
+    },
+}
+
+
+class MissingFieldError(KTalkError):
+    """Поле не передано явно (`None`) — отказ до сетевого вызова (NFR-9)."""
+
+    def __init__(self, field: str) -> None:
+        super().__init__(
+            f'Поле «{field}» не передано явно вызывающим — запрос на создание встречи '
+            "отклонён до сетевого вызова (NFR-9)."
+        )
+        self.field = field
+
+
+class TimezoneFormatError(KTalkError):
+    """Форма `timezone` не распознана — отказ до сетевого вызова (FR-40).
+
+    ГИПОТЕЗА: диапазон `GMT-14..GMT+14` не измерен целиком, подтверждено
+    замером только `GMT+3` (rooms-calendar-scheduling.md:357-368,
+    ADR-020 §3). Границы взяты по общемировому диапазону смещений UTC, не по
+    факту API — ревизуются следующим боевым замером с иным значением.
+    """
+
+    def __init__(self, value: str) -> None:
+        super().__init__(
+            f'Часовой пояс «{value}» не распознан. Требуемый формат: `GMT±N` '
+            "(пример: `GMT+3`). Другие нотации (IANA, Windows ID, ISO-смещение, "
+            "аббревиатуры) сервер не принимает — см. FR-40."
+        )
+        self.value = value
+
+
+def build_required_attendees(keys: list[str]) -> list[dict]:
+    """ADR-009 §4: `requiredUserKeys` (список логинов) заменён на список объектов
+    `{"type": "user", "key": str}` — `key` числовой id строкой (снимок сериализует
+    id как `"668"`, не `668`). Формат `key` не валидируется (`.isdigit()`) —
+    компоновщик не знает формат id других типов участников за пределами снимка."""
+    return [{"type": "user", "key": key} for key in keys]
+
+
+def _to_utc_z(value: str) -> str:
+    """ADR-009 §1: `start`/`end` — UTC с суффиксом `Z` и миллисекундами, не
+    локальное смещение. Вызывающий передаёт локальное ISO с оффсетом,
+    конвертация — деталь этого модуля (единственная точка правки, не
+    компоновщика вызывающего кода)."""
+    dt = datetime.fromisoformat(value)
+    dt_utc = dt.astimezone(UTC)
+    millis = dt_utc.microsecond // 1000
+    return f"{dt_utc.strftime('%Y-%m-%dT%H:%M:%S')}.{millis:03d}Z"
+
+
+def build_meeting_body(
+    *,
+    subject: str | None = None,
+    start: str | None = None,
+    end: str | None = None,
+    timezone: str | None = None,
+    room_name: str | None = None,
+    required_attendee_keys: list[str] | None = None,
+    description: str | None = None,
+    enable_auto_recording: bool | None = None,
+    pin_code: str | None = None,
+    pin_code_explicit_none: bool = False,
+    allow_anonymous: bool | None = None,
+    anonymous_access_expiration: str | None = None,
+) -> dict:
+    """Каждое поле `_REQUIRED` проверяется через `is None` (не truthiness) — явный
+    пустой список участников/`False` — валидные явные решения, отсутствие
+    значения — нет. `description` — единственное поле с разрешённым тихим
+    дефолтом (пустая строка, NFR-9). `pinCode`/`anonymousAccessExpirationDate`
+    решаются отдельными условными правилами (ADR-009 §2-3), не общим циклом.
+
+    `timezone` принимает единственную форму `GMT±N` (пример `GMT+3`, диапазон
+    `GMT-14..GMT+14`, ГИПОТЕЗА — измерен только `GMT+3`). Другая нотация
+    отклоняется `TimezoneFormatError` до сборки тела.
+    """
+    body = {
+        "subject": subject,
+        "start": _to_utc_z(start) if start is not None else None,
+        "end": _to_utc_z(end) if end is not None else None,
+        "timezone": timezone,
+        "roomName": room_name,
+        "requiredAttendees": (
+            build_required_attendees(required_attendee_keys)
+            if required_attendee_keys is not None
+            else None
+        ),
+        "description": description if description is not None else "",
+        "enableAutoRecording": enable_auto_recording,
+        "allowAnonymous": allow_anonymous,
+    }
+    for field in _REQUIRED:
+        if body[field] is None:
+            raise MissingFieldError(field)
+    if not _TIMEZONE_RE.match(body["timezone"]):
+        raise TimezoneFormatError(body["timezone"])
+
+    # ADR-009 §2: `pin_code_explicit_none=True` побеждает при одновременной
+    # передаче обоих сигналов — «решено: нет PIN» перекрывает конкретное
+    # значение `pin_code` (порядок не специфицирован спекой, зафиксирован здесь).
+    if pin_code_explicit_none:
+        body["pinCode"] = None
+    elif pin_code is not None:
+        body["pinCode"] = pin_code
+    else:
+        raise MissingFieldError("pinCode")
+
+    # ADR-009 §3: `anonymousAccessExpirationDate` условно обязателен — вне
+    # общего `_REQUIRED`-цикла. `allow_anonymous=False` + значение передано —
+    # значение отбрасывается (поле неприменимо, доступ выключен), не ошибка:
+    # решение Dev по edge case, не специфицированному спекой дословно.
+    if allow_anonymous is True and anonymous_access_expiration is None:
+        raise MissingFieldError("anonymousAccessExpirationDate")
+    body["anonymousAccessExpirationDate"] = (
+        anonymous_access_expiration if allow_anonymous else None
+    )
+
+    body.update(_FIXED)
+    return body
+
+
+def canonical_body_hash(body: dict) -> str:
+    """sha256 канонической (стабильной по порядку ключей) сериализации тела —
+    основа привязки подтверждения к содержимому (ADR-005)."""
+    canonical = json.dumps(body, sort_keys=True, ensure_ascii=False)
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()

ktalk_cli/meeting_cancel.py

@@ -0,0 +1,33 @@
+"""ADR-011 §2: компоновка данных отмены встречи (без сети).
+
+Параллель `meeting_scheduling.PreviewService` — чистые функции, без `KTalkClient`,
+физическая невозможность сетевого вызова из этого модуля.
+"""
+
+from __future__ import annotations
+
+from ktalk_cli.confirmation import ConfirmationStore
+from ktalk_cli.meeting_body import canonical_body_hash
+
+
+def build_cancel_confirmation_payload(*, id: str, reason: str = "") -> dict:
+    """Не тело запроса (то — `{"reason": reason}`), а предмет хеширования
+    подтверждения (ADR-011 п.2): `id` — часть пути, не тела, но обязан входить
+    в хеш, иначе подтверждение для одной встречи матчится для любой другой.
+    `operation` — дискриминатор против путаницы с будущим подтверждением
+    `update_meeting` на том же `id`."""
+    return {"operation": "cancel_meeting", "id": id, "reason": reason}
+
+
+class CancelPreviewService:
+    """Параллель `PreviewService` (`meeting_scheduling.py`) — тот же
+    `ConfirmationStore`, та же `canonical_body_hash`."""
+
+    def __init__(self, store: ConfirmationStore) -> None:
+        self._store = store
+
+    def preview(self, *, id: str, reason: str = "") -> tuple[dict, str]:
+        payload = build_cancel_confirmation_payload(id=id, reason=reason)
+        payload_hash = canonical_body_hash(payload)
+        confirmation_id = self._store.issue(payload_hash)
+        return payload, confirmation_id

ktalk_cli/meeting_scheduling.py

@@ -0,0 +1,120 @@
+"""FR-13 §6.6: предпросмотр (без сети) + создание (ровно одна сетевая попытка).
+
+`create_meeting` — свободная функция вне `client.py` (гейт C13), тем же приёмом,
+что `rooms.get_room`/`calendar_reader._fetch_segment`.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from ktalk_cli.auth import quote_path_param
+from ktalk_cli.client import KTalkClient
+from ktalk_cli.confirmation import ConfirmationStore
+from ktalk_cli.contour_diagnostics import TRANSIENT_ERRORS, diagnose_undocumented_failure
+from ktalk_cli.meeting_body import build_meeting_body, canonical_body_hash
+
+logger = logging.getLogger(__name__)
+
+
+class PreviewService:
+    def __init__(self, store: ConfirmationStore) -> None:
+        self._store = store
+
+    def preview(self, **fields: object) -> tuple[dict, str]:
+        """`build_meeting_body` -> `canonical_body_hash` -> `store.issue`. Без сети
+        физически — не получает `KTalkClient` (структурная невозможность, не
+        поведенческая)."""
+        body = build_meeting_body(**fields)
+        body_hash = canonical_body_hash(body)
+        confirmation_id = self._store.issue(body_hash)
+        return body, confirmation_id
+
+
+async def create_meeting(client: KTalkClient, body: dict) -> dict:
+    """Ровно одна сетевая попытка `POST /api/calendar`, без retry. ADR-007 п.3:
+    оборачивается корреляционной диагностикой ADR-004, тем же приёмом, что
+    `calendar_reader._fetch_segment` — сбой недокументированного пути неотличим
+    от обычного auth/сетевого сбоя без контрольного вызова.
+
+    ADR-009 §6 (пересматривает ADR-008 §1): на `profile.mutating` (сегодня только
+    session-режим этой операции) заголовки `Authorization: Session <token>` +
+    `X-Platform: web` отправляются ВМЕСТО query-параметра `sessionToken`, не
+    поверх него — единственная известная рабочая конфигурация (снимок DevTools).
+    Query вырезается точечно из уже построенного `httpx.Request`
+    (`copy_remove_param`) — конструктор клиента (`client._client.params`,
+    ADR-003) не трогается, следующий read-путь того же клиента снова несёт
+    `sessionToken` в query как обычно. ГИПОТЕЗА до следующего боевого POST. Тело
+    ответа 4xx/5xx читается до классификации и прикрепляется к перехваченному
+    исключению атрибутом `response_body` (обрезано до 500 символов) — переживает
+    прогон независимо от конфигурации `logging`, которой в проекте нет."""
+    profile = client._profile_for("create_meeting")  # noqa: SLF001
+    headers = (
+        {"Authorization": f"Session {client._auth.credential}", "X-Platform": "web"}  # noqa: SLF001
+        if profile.mutating
+        else None
+    )
+    request = client._client.build_request(  # noqa: SLF001
+        "POST", profile.path_template, json=body, headers=headers
+    )
+    if profile.mutating:
+        request.url = request.url.copy_remove_param("sessionToken")
+    try:
+        response = await client._client.send(request)  # noqa: SLF001
+    except TRANSIENT_ERRORS as exc:
+        await diagnose_undocumented_failure(client, "create_meeting", exc)
+        raise  # недостижимо
+
+    body_text = response.text[:500] if response.status_code >= 400 else None
+    if body_text:
+        logger.warning("create_meeting: HTTP %s, тело: %s", response.status_code, body_text)
+
+    try:
+        client._classify(response, profile.required_scope)  # noqa: SLF001
+    except TRANSIENT_ERRORS as exc:
+        # DEV-008: тело пустое ("") — это факт контура, отличный от "тело не
+        # прикреплено вовсе" (той ветки, где ответа не было — сетевой сбой выше).
+        # `if body_text:` терял этот факт при пустой строке.
+        if body_text is not None:
+            exc.response_body = body_text  # атрибут читает CLI/MCP на границе вывода
+        await diagnose_undocumented_failure(client, "create_meeting", exc)
+        raise  # недостижимо
+    return response.json()
+
+
+async def cancel_meeting(client: KTalkClient, *, id: str, reason: str = "") -> dict:
+    """Ровно одна сетевая попытка `POST /api/calendar/{id}/cancel`, без retry —
+    тот же контракт, что `create_meeting` (ADR-005 п.2). Транспорт (заголовки,
+    отсутствие query) — тот же код, что `create_meeting`: `profile.mutating`
+    общий признак, не специфичный для операции. `{id}` — обязательный
+    `quote_path_param` (Ф-56): `+`/`/`/`=` меняют путь без квотирования."""
+    profile = client._profile_for("cancel_meeting")  # noqa: SLF001
+    path = profile.path_template.format(id=quote_path_param(id))
+    headers = (
+        {"Authorization": f"Session {client._auth.credential}", "X-Platform": "web"}  # noqa: SLF001
+        if profile.mutating
+        else None
+    )
+    request = client._client.build_request(  # noqa: SLF001
+        "POST", path, json={"reason": reason}, headers=headers
+    )
+    if profile.mutating:
+        request.url = request.url.copy_remove_param("sessionToken")
+    try:
+        response = await client._client.send(request)  # noqa: SLF001
+    except TRANSIENT_ERRORS as exc:
+        await diagnose_undocumented_failure(client, "cancel_meeting", exc)
+        raise  # недостижимо
+
+    body_text = response.text[:500] if response.status_code >= 400 else None
+    try:
+        client._classify(response, profile.required_scope)  # noqa: SLF001
+    except TRANSIENT_ERRORS as exc:
+        if body_text is not None:
+            exc.response_body = body_text
+        await diagnose_undocumented_failure(client, "cancel_meeting", exc)
+        raise  # недостижимо
+    # Ф-57: успешная отмена отвечает 200 с ПУСТЫМ телом — `response.json()` на нём
+    # падает, и необратимая выполненная операция докладывалась как «исход неизвестен».
+    # Отличие от `create_meeting`, чей ответ несёт объект встречи.
+    return response.json() if response.content else {}

ktalk_cli/pagination.py

@@ -0,0 +1,108 @@
+"""Единый асинхронный итератор постраничного чтения (FR-9, FR-14).
+
+`paginate_pages` — форма-независимый движок термination-логики: продолжает, пока
+очередная страница непустая И следующий курсор истинный; останавливается на первом
+же из двух отрицательных сигналов. Не полагается на конкретное имя поля пагинации
+в ответе API — это и закрывает Ф-3 (`/api/recordings` не отдаёт `nextPageToken`).
+
+`skip_pages` — offset-адаптер (session-список записей, архив, FR-9/FR-14): жёстко
+клэмпит размер страницы в [1, 100] (закрывает регрессию `top=1000`, зонд Ф-2) и
+продолжает по `skip`, пока очередной запрос не вернёт пустую страницу — намеренно
+НЕ останавливается на «короткой», но непустой странице: домен ни разу не подтвердил,
+что API отдаёт заведомо неполные непоследние страницы, а недоверие отсутствующему
+полю (Ф-3) распространяется и на предположение «короткая = последняя».
+
+`token_pages` — курсорный адаптер (api-key список записей): `nextPageToken`.
+
+`clip_to_window` — клиентское окно дат (Ф-15). API игнорирует `startFrom`/`startTo`:
+зонд показал побитово одинаковую выдачу с фильтром и без него, а описания этих
+параметров у v1 и v2 в спеке вдобавок зеркальны. Поэтому окно `--days` обеспечивает
+клиент, а не сервер. Ранняя остановка опирается на `orderMode=byTimeNewFirst`
+и проверена на пяти страницах подряд (Ф-16): порядок строго убывающий внутри
+страницы и монотонный между страницами.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import Any
+
+Cursor = Any
+FetchPage = Callable[[Cursor | None], Awaitable[tuple[list[dict], Cursor | None]]]
+
+
+def clip_to_window(
+    items: list[dict],
+    start_from: str | None,
+    *,
+    date_key: str = "createdDate",
+) -> tuple[list[dict], bool]:
+    """Оставляет записи не старше `start_from`, сообщая, исчерпано ли окно.
+
+    Возвращает `(kept, exhausted)`. `exhausted=True` означает, что страница
+    содержала запись старше порога — при сортировке от новых к старым все
+    последующие страницы заведомо вне окна и запрашивать их не нужно.
+
+    Записи без разбираемой даты не отбрасываются: пустой `createdDate` — это
+    неизвестность, а не «старая запись», и терять её молча нельзя.
+    """
+    if not start_from:
+        return items, False
+    kept: list[dict] = []
+    exhausted = False
+    for item in items:
+        raw = (item.get(date_key) or "")[:10]
+        if not raw:
+            kept.append(item)
+            continue
+        if raw < start_from[:10]:
+            exhausted = True
+            continue
+        kept.append(item)
+    return kept, exhausted
+
+
+async def paginate_pages(fetch_page: FetchPage) -> AsyncIterator[list[dict]]:
+    """Обходит страницы через `fetch_page(cursor) -> (items, next_cursor)`."""
+    cursor: Cursor | None = None
+    while True:
+        items, next_cursor = await fetch_page(cursor)
+        if not items:
+            return
+        yield items
+        if not next_cursor:
+            return
+        cursor = next_cursor
+
+
+def skip_pages(
+    fetch: Callable[[int, int], Awaitable[dict]],
+    page_size: int = 100,
+    items_key: str = "recordings",
+) -> FetchPage:
+    """Строит `fetch_page` для offset-пагинации поверх `fetch(skip, top) -> raw_dict`."""
+    page_size = max(1, min(int(page_size), 100))
+
+    async def fetch_page(cursor: int | None) -> tuple[list[dict], int | None]:
+        skip = cursor or 0
+        raw = await fetch(skip, page_size)
+        items = raw.get(items_key) or []
+        next_cursor = skip + len(items) if items else None
+        return items, next_cursor
+
+    return fetch_page
+
+
+def token_pages(
+    fetch: Callable[[str | None], Awaitable[dict]],
+    items_key: str = "entities",
+    token_key: str = "nextPageToken",
+) -> FetchPage:
+    """Строит `fetch_page` для курсорной пагинации поверх `fetch(token) -> raw_dict`."""
+
+    async def fetch_page(cursor: str | None) -> tuple[list[dict], str | None]:
+        raw = await fetch(cursor)
+        items = raw.get(items_key) or []
+        return items, raw.get(token_key) or None
+
+    return fetch_page

ktalk_cli/reconciliation.py

@@ -0,0 +1,59 @@
+"""Сверка идентификаторов перед первым api-key sync (FR-15).
+
+Внутренний контур отдаёт только `id`, интеграторский — `id` и `key`; совпадают ли
+значения между контурами не проверено эмпирически (ключ выдан без нужных scope,
+зонд Ф-11/Ф-14). Если разойдутся, первый `ktalk sync` под ключом задвоит реестр
+(~1316 записей) — обязателен `ktalk sync --dry-run` до первого боевого прогона.
+"""
+
+from __future__ import annotations
+
+
+def recording_ids(recordings: list[dict]) -> list[str]:
+    """Извлекает id (fallback на key, как `registry.recording_fields_from_api`)."""
+    return [rid for r in recordings if (rid := r.get("id") or r.get("key"))]
+
+
+def compare_id_sets(fetched: list[str], existing: list[str]) -> dict:
+    """Сравнивает множество id из API-ответа с уже существующими строками реестра."""
+    fetched_set = set(fetched)
+    existing_set = set(existing)
+    return {
+        "only_in_fetched": fetched_set - existing_set,
+        "only_in_existing": existing_set - fetched_set,
+        "common": fetched_set & existing_set,
+    }
+
+
+def dry_run_report(fetched_ids: list[str], existing_ids: list[str]) -> dict:
+    """Отчёт для `ktalk sync --dry-run` (FR-15 AC-2/AC-3).
+
+    `ok=True` — можно продолжать обычную синхронизацию (полное совпадение либо
+    реестр ещё пуст, сверивать не с чем). `ok=False` — расхождение идентификаторов,
+    боевой sync заблокирован до осознанного решения оператора (используется как
+    exit-код CLI, по аналогии с уже принятым в проекте `migrate --dry-run`).
+    """
+    if not existing_ids:
+        return {
+            "ok": True,
+            "message": (
+                "Реестр пуст — нет данных для сравнения. Сверка id будет возможна "
+                "после первого сохранённого sync."
+            ),
+            "only_in_fetched": sorted(set(fetched_ids)),
+            "only_in_existing": [],
+        }
+    comparison = compare_id_sets(fetched_ids, existing_ids)
+    mismatch = bool(comparison["only_in_fetched"] or comparison["only_in_existing"])
+    message = (
+        "Обнаружено расхождение идентификаторов — боевой sync заблокирован до "
+        "осознанного решения оператора."
+        if mismatch
+        else "Идентификаторы полностью совпадают — можно продолжать обычную синхронизацию."
+    )
+    return {
+        "ok": not mismatch,
+        "message": message,
+        "only_in_fetched": sorted(comparison["only_in_fetched"]),
+        "only_in_existing": sorted(comparison["only_in_existing"]),
+    }