ktalk-cli 2.0.0__tar.gz → 2.1.0__tar.gz

{ktalk_cli-2.0.0 → ktalk_cli-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ktalk-cli
-Version: 2.0.0
+Version: 2.1.0
 Summary: CLI for accessing Kontur Talk (KTalk) recordings, transcripts and summaries
 Project-URL: Homepage, https://github.com/mdemyanov/ktalk-cli
 Project-URL: Repository, https://github.com/mdemyanov/ktalk-cli
@@ -26,15 +26,18 @@ Description-Content-Type: text/markdown
 [![PyPI](https://img.shields.io/pypi/v/ktalk-cli)](https://pypi.org/project/ktalk-cli/)
 [![Python](https://img.shields.io/pypi/pyversions/ktalk-cli)](https://pypi.org/project/ktalk-cli/)
 
-CLI `ktalk` для доступа к записям [Контур.Толк](https://ktalk.ru) (KTalk) — чтение
-записей, транскриптов и саммари, работа с расписанием, операционный реестр
-обработки записей на SQLite.
+CLI `ktalk` — интерфейс командной строки для тех, кто работает с записями видеовстреч
+[Контур.Толк](https://ktalk.ru) (KTalk) программно: читает записи, транскрипты и саммари,
+управляет расписанием, ведёт локальный реестр обработки записей на SQLite. Годится и как
+самостоятельный инструмент, и как предусловие плагина Claude Code `ktalk` — подробнее в
+разделе «Пакет и плагин Claude Code» ниже.
 
 > Раньше пакет назывался `ktalk-mcp` и, помимо CLI, поднимал MCP-сервер для
 > Claude Code (инструменты вида `ktalk_list_recordings`). Этот слой снят
 > целиком — MCP в пакете больше нет, единственная точка входа — команда
-> `ktalk`. Нужна интеграция с Claude Code — отдельный плагин `ktalk` вызывает
-> эту же CLI напрямую, без MCP-сервера.
+> `ktalk`. Пришли по старой ссылке или ищете `ktalk-mcp` — это тот же проект
+> под новым именем, старый пакет дальше не развивается (о конфликте имени
+> команды при апгрейде — ниже, в «Установке»).
 
 Умеет:
 - Список записей конференций и детали одной записи.
@@ -73,6 +76,18 @@ uv tool uninstall ktalk-mcp
 uv tool install ktalk-cli
 ```
 
+**Проверка версии** — после установки или обновления:
+
+```bash
+ktalk --version    # печатает, например: ktalk-cli 2.1.0
+```
+
+**Обновление** до последней версии — та же команда `install`, только `upgrade`:
+
+```bash
+uv tool upgrade ktalk-cli
+```
+
 ## Авторизация
 
 CLI поддерживает два способа авторизации: session token (кука браузера) и
@@ -222,11 +237,20 @@ ktalk auth-status
 Все команды поддерживают `--json` (валидный JSON в stdout; ошибки — в stderr с
 ненулевым кодом возврата).
 
+### Коды возврата
+
+| Код | Значение |
+|---|---|
+| `0` | Успех. |
+| `1` | Отказ вызова — сеть, сервер, конфигурация. |
+| `2` | Usage error — неверные аргументы CLI (`argparse`). |
+| `3` | Только `ktalk get-transcript`. Данные получены и напечатаны полностью, но независимая сверка идентичности не сошлась (`identity_check.result == "mismatch"`) — состав участников транскрипта разошёлся с составом записи. Это не сбой команды: код 3 отличает «данные есть, но сверка не сошлась» от `0` (сошлось или не проверялось) и от `1`/`2` (данных нет вовсе). Подробности — в самом теле ответа, поле `identity_check` (ADR-024 §Д1). |
+
 | Команда | Назначение |
 |---|---|
 | `ktalk list-recordings [--query Q] [--start-from ISO] [--start-to ISO] [--top N] [--order O] [--page-token T]` | Список записей. `--top` 1–1000 (по умолчанию 30); `--order`: `byTimeNewFirst` (умолчание), `byTimeOldFirst`, `byTitle`, `bySizeBigFirst`, `bySizeSmallFirst`. |
 | `ktalk get-recording <recording_key>` | Детали записи — автор, дата, длительность, участники (список ограничен 6, полный состав — `get-participants`). |
-| `ktalk get-transcript <recording_key> [--chunk N] [--chunk-size N]` | Транскрипт по спикерам с таймкодами. Длинный транскрипт режется на чанки по границам реплик: `--chunk 0` (умолчание) — целиком или первый чанк; `--chunk-size` — макс. символов в чанке (умолчание 30000, ~7500 токенов). |
+| `ktalk get-transcript <recording_key> [--chunk N] [--chunk-size N]` | Транскрипт по спикерам с таймкодами. Длинный транскрипт режется на чанки по границам реплик: `--chunk 0` (умолчание) — целиком или первый чанк; `--chunk-size` — макс. символов в чанке (умолчание 30000, ~7500 токенов). Независимая сверка идентичности включена по умолчанию (`--no-verify-identity` отключает); `--chunk` вне диапазона сверку по сети не запускает вовсе, `identity_check.result == "not_checked"`/`reason: "chunk_out_of_range"`. |
 | `ktalk get-summary <recording_key>` | Полное саммари (краткое резюме + протокол). |
 | `ktalk get-summary-type <recording_key> --type shortSummary\|protocol` | Саммари одного типа. |
 | `ktalk get-participants <recording_key>` | Полный состав участников, включая анонимных — обходит лимит в 6, который отдают `get-recording`/`list-recordings`. |
@@ -386,6 +410,30 @@ uv run ruff check .
 KTALK_SESSION_TOKEN=... KTALK_BASE_URL=... uv run ktalk auth-status
 ```
 
+## Пакет и плагин Claude Code
+
+`ktalk-cli` работает и сам по себе, и как предусловие плагина Claude Code `ktalk`. Плагин не
+обращается к KTalk напрямую и не поднимает MCP-сервер — он вызывает эту же команду `ktalk`
+как единственную точку входа в контур.
+
+Плагин пинует точную версию пакета (не нижний порог: «ровно эта версия», не «эта или новее») в
+собственном файле совместимости. Если что-то в интеграции с плагином ведёт себя не так, как
+описано в его документации, — первым делом сверьте версию:
+
+```bash
+ktalk --version    # см. «Проверка версии» в разделе «Установка»
+```
+
+Версия не совпадает с той, что требует плагин, — обновите пакет тем же способом, что при
+установке (`uv tool upgrade ktalk-cli`, см. «Установка»); не совпадает в другую сторону
+(пакет новее, чем ожидает плагин) — не откатывайте его самостоятельно, сверьтесь с тем, кто
+настраивал плагин.
+
+## Проблемы и вопросы
+
+Нашли баг, некорректное поведение или неточность в документации — заведите issue в этом
+репозитории: https://github.com/mdemyanov/ktalk-cli/issues.
+
 ## Лицензия
 
 MIT

{ktalk_cli-2.0.0 → ktalk_cli-2.1.0}/README.md

@@ -3,15 +3,18 @@
 [![PyPI](https://img.shields.io/pypi/v/ktalk-cli)](https://pypi.org/project/ktalk-cli/)
 [![Python](https://img.shields.io/pypi/pyversions/ktalk-cli)](https://pypi.org/project/ktalk-cli/)
 
-CLI `ktalk` для доступа к записям [Контур.Толк](https://ktalk.ru) (KTalk) — чтение
-записей, транскриптов и саммари, работа с расписанием, операционный реестр
-обработки записей на SQLite.
+CLI `ktalk` — интерфейс командной строки для тех, кто работает с записями видеовстреч
+[Контур.Толк](https://ktalk.ru) (KTalk) программно: читает записи, транскрипты и саммари,
+управляет расписанием, ведёт локальный реестр обработки записей на SQLite. Годится и как
+самостоятельный инструмент, и как предусловие плагина Claude Code `ktalk` — подробнее в
+разделе «Пакет и плагин Claude Code» ниже.
 
 > Раньше пакет назывался `ktalk-mcp` и, помимо CLI, поднимал MCP-сервер для
 > Claude Code (инструменты вида `ktalk_list_recordings`). Этот слой снят
 > целиком — MCP в пакете больше нет, единственная точка входа — команда
-> `ktalk`. Нужна интеграция с Claude Code — отдельный плагин `ktalk` вызывает
-> эту же CLI напрямую, без MCP-сервера.
+> `ktalk`. Пришли по старой ссылке или ищете `ktalk-mcp` — это тот же проект
+> под новым именем, старый пакет дальше не развивается (о конфликте имени
+> команды при апгрейде — ниже, в «Установке»).
 
 Умеет:
 - Список записей конференций и детали одной записи.
@@ -50,6 +53,18 @@ uv tool uninstall ktalk-mcp
 uv tool install ktalk-cli
 ```
 
+**Проверка версии** — после установки или обновления:
+
+```bash
+ktalk --version    # печатает, например: ktalk-cli 2.1.0
+```
+
+**Обновление** до последней версии — та же команда `install`, только `upgrade`:
+
+```bash
+uv tool upgrade ktalk-cli
+```
+
 ## Авторизация
 
 CLI поддерживает два способа авторизации: session token (кука браузера) и
@@ -199,11 +214,20 @@ ktalk auth-status
 Все команды поддерживают `--json` (валидный JSON в stdout; ошибки — в stderr с
 ненулевым кодом возврата).
 
+### Коды возврата
+
+| Код | Значение |
+|---|---|
+| `0` | Успех. |
+| `1` | Отказ вызова — сеть, сервер, конфигурация. |
+| `2` | Usage error — неверные аргументы CLI (`argparse`). |
+| `3` | Только `ktalk get-transcript`. Данные получены и напечатаны полностью, но независимая сверка идентичности не сошлась (`identity_check.result == "mismatch"`) — состав участников транскрипта разошёлся с составом записи. Это не сбой команды: код 3 отличает «данные есть, но сверка не сошлась» от `0` (сошлось или не проверялось) и от `1`/`2` (данных нет вовсе). Подробности — в самом теле ответа, поле `identity_check` (ADR-024 §Д1). |
+
 | Команда | Назначение |
 |---|---|
 | `ktalk list-recordings [--query Q] [--start-from ISO] [--start-to ISO] [--top N] [--order O] [--page-token T]` | Список записей. `--top` 1–1000 (по умолчанию 30); `--order`: `byTimeNewFirst` (умолчание), `byTimeOldFirst`, `byTitle`, `bySizeBigFirst`, `bySizeSmallFirst`. |
 | `ktalk get-recording <recording_key>` | Детали записи — автор, дата, длительность, участники (список ограничен 6, полный состав — `get-participants`). |
-| `ktalk get-transcript <recording_key> [--chunk N] [--chunk-size N]` | Транскрипт по спикерам с таймкодами. Длинный транскрипт режется на чанки по границам реплик: `--chunk 0` (умолчание) — целиком или первый чанк; `--chunk-size` — макс. символов в чанке (умолчание 30000, ~7500 токенов). |
+| `ktalk get-transcript <recording_key> [--chunk N] [--chunk-size N]` | Транскрипт по спикерам с таймкодами. Длинный транскрипт режется на чанки по границам реплик: `--chunk 0` (умолчание) — целиком или первый чанк; `--chunk-size` — макс. символов в чанке (умолчание 30000, ~7500 токенов). Независимая сверка идентичности включена по умолчанию (`--no-verify-identity` отключает); `--chunk` вне диапазона сверку по сети не запускает вовсе, `identity_check.result == "not_checked"`/`reason: "chunk_out_of_range"`. |
 | `ktalk get-summary <recording_key>` | Полное саммари (краткое резюме + протокол). |
 | `ktalk get-summary-type <recording_key> --type shortSummary\|protocol` | Саммари одного типа. |
 | `ktalk get-participants <recording_key>` | Полный состав участников, включая анонимных — обходит лимит в 6, который отдают `get-recording`/`list-recordings`. |
@@ -363,6 +387,30 @@ uv run ruff check .
 KTALK_SESSION_TOKEN=... KTALK_BASE_URL=... uv run ktalk auth-status
 ```
 
+## Пакет и плагин Claude Code
+
+`ktalk-cli` работает и сам по себе, и как предусловие плагина Claude Code `ktalk`. Плагин не
+обращается к KTalk напрямую и не поднимает MCP-сервер — он вызывает эту же команду `ktalk`
+как единственную точку входа в контур.
+
+Плагин пинует точную версию пакета (не нижний порог: «ровно эта версия», не «эта или новее») в
+собственном файле совместимости. Если что-то в интеграции с плагином ведёт себя не так, как
+описано в его документации, — первым делом сверьте версию:
+
+```bash
+ktalk --version    # см. «Проверка версии» в разделе «Установка»
+```
+
+Версия не совпадает с той, что требует плагин, — обновите пакет тем же способом, что при
+установке (`uv tool upgrade ktalk-cli`, см. «Установка»); не совпадает в другую сторону
+(пакет новее, чем ожидает плагин) — не откатывайте его самостоятельно, сверьтесь с тем, кто
+настраивал плагин.
+
+## Проблемы и вопросы
+
+Нашли баг, некорректное поведение или неточность в документации — заведите issue в этом
+репозитории: https://github.com/mdemyanov/ktalk-cli/issues.
+
 ## Лицензия
 
 MIT

{ktalk_cli-2.0.0 → ktalk_cli-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ktalk-cli"
-version = "2.0.0"
+version = "2.1.0"
 description = "CLI for accessing Kontur Talk (KTalk) recordings, transcripts and summaries"
 readme = "README.md"
 license = "MIT"

{ktalk_cli-2.0.0 → ktalk_cli-2.1.0}/src/ktalk_cli/cli_content.py

@@ -27,6 +27,7 @@ from ktalk_cli.formatters import (
     format_summary_by_type,
     render_tool_output,
     render_transcript_output,
+    resolve_chunk_range,
 )
 from ktalk_cli.transcript_identity import check_identity
 
@@ -132,11 +133,13 @@ async def _verify_transcript_identity(client: KTalkClient, recording_key: str, t
 
 
 def _render_transcript_with_identity(
-    output_text: str, identity_check: dict | None, *, json_flag: bool
+    output_text: str, identity_check: dict | None, *, json_flag: bool, in_range: bool = True
 ) -> str:
-    """Сборка вывода `get-transcript` (companion-спека «Оркестрация», шаг 4).
+    """Сборка вывода `get-transcript` (companion-спека «Оркестрация», шаг 5).
     `identity_check is None` -> сверка отключена (`--no-verify-identity`), выводим
-    как раньше."""
+    как раньше. `in_range` — валидность `--chunk` уже известна вызывающей стороне
+    (`resolve_chunk_range`, ADR-024 §Д3) — на пути вне диапазона JSON-конверт
+    собирается явно (`{"error": …}`), без `try/except JSONDecodeError`."""
     if identity_check is None:
         return output_text
 
@@ -146,37 +149,53 @@ def _render_transcript_with_identity(
             line += f" ({identity_check['reason']})"
         return f"{output_text}\n{line}"
 
-    try:
-        parsed = json.loads(output_text)
-    except (json.JSONDecodeError, ValueError):
-        # `--chunk N` вне диапазона отдаёт нестрого-JSON текст — сверять нечего,
-        # печатаем как есть (companion-спека, edge case чанкинга).
-        return output_text
+    if not in_range:
+        return json.dumps(
+            {"error": output_text, "identity_check": identity_check},
+            ensure_ascii=False,
+            indent=2,
+        )
 
+    parsed = json.loads(output_text)
     return json.dumps(
         {"transcript": parsed, "identity_check": identity_check}, ensure_ascii=False, indent=2
     )
 
 
 def cmd_get_transcript(_reg, args: argparse.Namespace) -> int:
-    async def _fetch() -> tuple[dict, dict | None]:
+    fmt = "raw" if args.json else "markdown"
+
+    async def _fetch() -> tuple[dict, dict | None, bool]:
         async with KTalkClient.from_settings(Settings()) as client:
             data = await client.get_transcript(args.recording_key)
+            in_range, _total_chunks = resolve_chunk_range(data, fmt, args.chunk, args.chunk_size)
             identity_check = None
             if not args.no_verify_identity:
-                identity_check = await _verify_transcript_identity(
-                    client, args.recording_key, data
-                )
-            return data, identity_check
+                if in_range:
+                    identity_check = await _verify_transcript_identity(
+                        client, args.recording_key, data
+                    )
+                else:
+                    # ADR-024 §Д3: чанк заведомо вне диапазона — сверка не
+                    # оплачивается сетевым вызовом, `not_checked` формируется
+                    # локально, переиспользуя словарь исходов ADR-023.
+                    identity_check = {"result": "not_checked", "reason": "chunk_out_of_range"}
+            return data, identity_check, in_range
 
     try:
-        data, identity_check = asyncio.run(_fetch())
+        data, identity_check, in_range = asyncio.run(_fetch())
     except Exception as exc:  # noqa: BLE001 - surface as CLI error, NFR-5 маскирует
         print(f"Ошибка: {redact_secrets(str(exc))}", file=sys.stderr)
         return 1
-    fmt = "raw" if args.json else "markdown"
     output_text = render_transcript_output(data, fmt, args.chunk, args.chunk_size)
-    print(_render_transcript_with_identity(output_text, identity_check, json_flag=args.json))
+    print(
+        _render_transcript_with_identity(
+            output_text, identity_check, json_flag=args.json, in_range=in_range
+        )
+    )
+    if identity_check is not None and identity_check.get("result") == "mismatch":
+        # ADR-024 §Д1: отказ становится громким — код 3, отдельный от 0/1/2.
+        return 3
     return 0
 
 

{ktalk_cli-2.0.0 → ktalk_cli-2.1.0}/src/ktalk_cli/formatters.py

@@ -318,6 +318,37 @@ def chunk_transcript_raw(data: dict, chunk_size: int) -> list[str]:
     return chunks
 
 
+def _chunk_transcript(data: dict, fmt: str, chunk_size: int, full_text: str) -> list[str]:
+    """Общая точка чанкинга для `render_transcript_output`/`resolve_chunk_range` —
+    не дублирует ветвление raw/markdown (ADR-024 companion-спека §3)."""
+    if fmt == "raw":
+        return chunk_transcript_raw(data, chunk_size)
+    return chunk_transcript_markdown(full_text, chunk_size)
+
+
+def resolve_chunk_range(data: dict, fmt: str, chunk: int, chunk_size: int) -> tuple[bool, int]:
+    """Определяет, лежит ли `chunk` в валидном диапазоне для `data`, БЕЗ сети
+    (ADR-024 §Д3, issue #9) — переиспользует чанкинг `render_transcript_output`,
+    не дублирует его. Отрицательный `chunk` — тоже вне диапазона (не Python-
+    отрицательная индексация).
+
+    Возвращает `(in_range, total_chunks)`.
+    """
+    if fmt == "raw":
+        full_text = format_raw(data)
+    else:
+        full_text = format_transcript(data)
+
+    if chunk == 0 and len(full_text) <= chunk_size:
+        return True, 1
+
+    chunks = _chunk_transcript(data, fmt, chunk_size, full_text)
+    total_chunks = len(chunks)
+    chunk_index = 0 if chunk == 0 else chunk - 1
+
+    return 0 <= chunk_index < total_chunks, total_chunks
+
+
 def render_transcript_output(data: dict, fmt: str, chunk: int, chunk_size: int) -> str:
     """Общий слой чтения транскрипта с чанкингом — единственная точка правды для
     `ktalk_get_transcript` (MCP) и `ktalk get-transcript` (CLI, DEV-002 волны 3):
@@ -332,10 +363,7 @@ def render_transcript_output(data: dict, fmt: str, chunk: int, chunk_size: int)
     if chunk == 0 and total_characters <= chunk_size:
         return full_text
 
-    if fmt == "raw":
-        chunks = chunk_transcript_raw(data, chunk_size)
-    else:
-        chunks = chunk_transcript_markdown(full_text, chunk_size)
+    chunks = _chunk_transcript(data, fmt, chunk_size, full_text)
 
     total_chunks = len(chunks)
     chunk_index = 0 if chunk == 0 else chunk - 1

{ktalk_cli-2.0.0 → ktalk_cli-2.1.0}/tests/test_nfr17_identity_verification.py

@@ -1,7 +1,8 @@
 """AT-design: NFR-17 — обнаружимость подмены транскрипта под конкуренцией
-(`content/40-architecture/at-design-adr023-open-issues.md`, раздел «NFR-17»).
+(`content/40-architecture/at-design-adr023-open-issues.md`, раздел «NFR-17»;
+волна 2 (ADR-024, Д1/Д3) — `content/40-architecture/at-design-adr024-open-issues-wave2.md`).
 
-Покрывает 3 AC NFR-17 из `content/30-requirements/transcript-identity-observability.md`
+Покрывает 5 AC NFR-17 из `content/30-requirements/transcript-identity-observability.md`
 (BA-014, вход RES-006) через `#### Scenario:` капабилити-спеки
 `openspec/specs/recording-data-access/spec.md`, раздел «A transcript response's
 recording identity is independently verifiable, not assumed from a successful call»:
@@ -11,6 +12,21 @@ recording identity is independently verifiable, not assumed from a successful ca
 - NFR17-AC3 — недоступность независимого источника отдаёт явный сигнал
   «не сверено» (`not_checked`), не тихое умолчание о совпадении; основной результат
   транскрипта возвращается в любом случае.
+- NFR17-AC4 (ADR-024 Д1, issue #5, новый сценарий капабилити-спеки «A detected
+  mismatch fails loudly, not silently») — `mismatch` обязан завершать `get-transcript`
+  кодом возврата 3, отдельным от 0 (успех), 1 (отказ вызова) и 2 (usage error);
+  тело ответа (`transcript`+`identity_check`) не пустеет. Причина исходной подмены
+  этим НЕ устраняется (ADR-024 §Д1) — тест проверяет только громкость отказа.
+- NFR17-AC5 (ADR-024 Д3, issue #9, новый сценарий «An out-of-range chunk request
+  does not silently drop the verification signal») — `--chunk` вне диапазона
+  обязан (а) не платить сетевым вызовом `get_recording` вовсе, (б) отдавать явный
+  `identity_check.result == "not_checked"`, `reason == "chunk_out_of_range"` в
+  валидном `--json`-конверте, отличимо от «сверка прошла и совпало».
+
+ADR-024 Д2 (issue #8) не меняет код — устойчивость `anonymousId` подтверждена
+измерением на живом контуре (companion-спека §2), не тестом; регрессия ключа
+сравнения анонимов уже покрыта ниже
+(`test_nfr17_boundary_anonymous_participants_identified_by_anonymous_id`).
 
 Решение SA, ПОПРАВЛЕННОЕ владельцем на gate-sa (ADR-023, ред. 2a2f6e3, НЕ 81b379a):
 сверка ВКЛЮЧЕНА ПО УМОЛЧАНИЮ у `get-transcript`; флаг `--no-verify-identity` её
@@ -50,6 +66,26 @@ NFR-17»): `match` (пересечение непусто), `mismatch` (оба
   усиленные тесты ниже проверяют явно: (а) поле `identity_check` не пропущено, (б)
   результат не «match» по умолчанию при отказе, (в) `--no-verify-identity` даёт
   ИМЕННО отсутствие второго вызова, а не тихий always-on второй вызов вопреки флагу.
+- **NFR17-AC4 (Д1), испорченный ввод** — N/A, явно, не по умолчанию: `mismatch` —
+  сигнатура серверной кросс-контаминации (RES-006), не опечатки `recording_key`.
+  Опечатанный ключ, для которого сервер отдаёт СОГЛАСОВАННЫЙ (тот же неверный ключ)
+  ответ и на транскрипт, и на `get_recording`, даёт `match` на СВОЁМ (чужом) составе,
+  не `mismatch` — нет воспроизводимого триггера подмены со стороны клиентского ввода
+  (ADR-024 §Д1: причина не локализована, тест на неё не проектируется).
+- **NFR17-AC4 (Д1), замаскированный отказ** — это и есть самый предмет решения:
+  до ADR-024 код возврата 0 на `mismatch` МАСКИРОВАЛ обнаруженное расхождение от
+  потребителей, читающих только код (не тело ответа). `test_nfr17_ac4_…` проверяет
+  явно, что маска снята: `rc == 3`, отдельно от 0/1/2.
+- **NFR17-AC5 (Д3), испорченный ввод** — отрицательный номер чанка
+  (`--chunk -1`) — не просто «вне диапазона», а структурно бессмысленное значение,
+  которое пользователь мог ввести по опечатке; должно давать тот же исход
+  (`not_checked`/`chunk_out_of_range`, ноль сетевых вызовов), не отдельную ветку.
+- **NFR17-AC5 (Д3), замаскированный отказ** — до ADR-024 результат сверки на этой
+  ветке ВЫЧИСЛЯЛСЯ (сетевой вызов оплачивался), но ТИХО терялся сборкой `--json`
+  (`JSONDecodeError` -> печать как есть, без `identity_check`) — неотличимо от
+  «сверка прошла успешно» на уровне общей формы ответа. Тесты проверяют явно:
+  ноль вызовов `get_recording` (не просто «результат не виден») и присутствие
+  структурированного `identity_check.reason == "chunk_out_of_range"` в JSON.
 """
 
 from __future__ import annotations
@@ -85,6 +121,13 @@ def _recording_url_re(key: str) -> re.Pattern:
     return re.compile(rf"{re.escape(BASE_URL)}/api/recordings/{re.escape(key)}(\?.*)?$")
 
 
+def _count_recording_calls(httpx_mock: HTTPXMock, key: str) -> int:
+    """Число сетевых вызовов ИМЕННО `get_recording` (не транскрипта) — ADR-024 Д3
+    требует ровно 0 на `--chunk` вне диапазона, не «меньше вызовов вообще»."""
+    pattern = _recording_url_re(key)
+    return sum(1 for req in httpx_mock.get_requests() if pattern.search(str(req.url)))
+
+
 # ============================================================================================
 # Unit — transcript_identity.py (чистые функции, входы — фикстуры JSON)
 # ============================================================================================
@@ -326,12 +369,20 @@ def test_nfr17_no_verify_identity_flag_skips_second_call_entirely(
 
 
 @pytest.mark.httpx_mock(assert_all_responses_were_requested=False)
-def test_nfr17_ac1_mismatch_surfaced_in_default_on_json_response(
+def test_nfr17_ac4_mismatch_exits_with_code_3_and_still_carries_full_body(
     httpx_mock: HTTPXMock, monkeypatch, capsys
 ):
-    """NFR17-AC1 буквально: конкурентная подмена (расходящиеся составы) -> потребитель
-    получает наблюдаемый признак ПРЕЖДЕ, чем содержимое использовано дальше — признак
-    доступен уже в самом `--json`-ответе `get-transcript`, не требует отдельного вызова."""
+    """NFR17-AC1+AC4 (ADR-024 Д1, issue #5): конкурентная подмена (расходящиеся
+    составы) -> потребитель получает наблюдаемый признак ПРЕЖДЕ, чем содержимое
+    использовано дальше (признак доступен уже в самом `--json`-ответе, AC1), И код
+    возврата 3 — отдельный от 0/1/2 (AC4, ADR-024 Д1).
+
+    ПРАВКА КОНТРАКТА (не регресс, не находка QA-runner): до ADR-024 этот же тест
+    закреплял `assert rc == 0` на mismatch — ровно то тихое поведение, которое
+    решение Д1 отменяет («отказ становится громким», не «гонка устранена» —
+    ADR-024 §Д1 дословно). Старое утверждение: `assert rc == 0`. Новое: `assert
+    rc == 3`. Причина исходной подмены (issue #5) этим НЕ локализована — тест не
+    проверяет большего, чем громкость отказа."""
     key = "REC-1"
     httpx_mock.add_response(
         json={
@@ -350,11 +401,24 @@ def test_nfr17_ac1_mismatch_surfaced_in_default_on_json_response(
     rc = _run(["get-transcript", key, "--json"], monkeypatch)
     out = json.loads(capsys.readouterr().out)
 
-    assert rc == 0
     assert out["identity_check"]["result"] == "mismatch", (
         f"NFR17-AC1: составы {{'u9'}} vs {{'u1'}} не пересекаются — ожидался mismatch "
         f"в самом --json ответе, получено {out.get('identity_check')}"
     )
+    assert rc == 3, (
+        "NFR17-AC4 (ADR-024 Д1, замаскированный отказ до правки): `mismatch` обязан "
+        f"завершать команду кодом 3, отдельным от 0/1/2 — фактический код {rc}. "
+        "Старый контракт (`rc == 0` даже на mismatch) отменён этим ADR — это НЕ "
+        "регресс покрытия, а сознательная правка теста под новое решение."
+    )
+    assert rc not in (0, 1, 2), (
+        f"NFR17-AC4: код 3 обязан быть отличим от успеха(0)/отказа вызова(1)/usage error(2), "
+        f"получено {rc}"
+    )
+    assert out.get("transcript") is not None, (
+        "NFR17-AC4 (замаскированный отказ): код 3 не должен опустошать тело ответа — "
+        f"`transcript` обязан присутствовать целиком, получено {out}"
+    )
 
 
 # ============================================================================================
@@ -427,26 +491,37 @@ def test_nfr17_malformed_mistyped_recording_key_get_recording_404_yields_not_che
 
 
 # ============================================================================================
-# Регресс — граница `--chunk` вне диапазона + умолчание-включено + `--json`
+# NFR17-AC5 (ADR-024 Д3, issue #9) — `--chunk` вне диапазона: сверка не оплачивается,
+# сигнал `not_checked`/`chunk_out_of_range` не теряется сборкой `--json`
 # ============================================================================================
 
 
 @pytest.mark.httpx_mock(assert_all_responses_were_requested=False)
-def test_nfr17_out_of_range_chunk_with_default_verify_does_not_crash_on_json_parse(
+def test_nfr17_ac5_out_of_range_chunk_with_default_verify_skips_network_call_and_signals_not_checked(
     httpx_mock: HTTPXMock, monkeypatch, capsys
 ):
-    """Companion-спека, «Оркестрация», edge case: `render_transcript_output` при
-    `--chunk N` вне диапазона отдаёт НЕСТРОГО-JSON текст ("Чанк N не существует...")
-    — `json.loads` этого текста бросает исключение; наивная реализация обёртки
-    `{"transcript": parsed, "identity_check": ...}` крашится на этом пути. Ожидание:
-    команда не падает (`rc == 0`), сообщение о несуществующем чанке доходит до
-    пользователя как есть."""
+    """ПРАВКА КОНТРАКТА (не регресс — ADR-024 Д3 отменяет прежнее поведение,
+    называвшееся issue #9 недостаточным): старый тест
+    (`test_nfr17_out_of_range_chunk_with_default_verify_does_not_crash_on_json_parse`)
+    закреплял РОВНО ДВА сетевых вызова (транскрипт + `get_recording`) и печать
+    НЕСТРОГО-JSON текста "Чанк N не существует..." как есть — то самое тихое
+    выбрасывание уже вычисленного `identity_check`, которое Д3 устраняет. Старое
+    утверждение: `len(httpx_mock.get_requests()) == 2` и `rc == 0` без проверки формы
+    JSON. Новое: `get_recording` НЕ вызывается вовсе (0, не 2 вызова на сверку —
+    сетевая цена не оплачивается на заведомо неверном чанке), а `--json`-вывод —
+    валидный JSON с явным `identity_check.result == "not_checked"`,
+    `reason == "chunk_out_of_range"`, отличимым от `match`."""
     key = "REC-1"
     httpx_mock.add_response(
         json={"status": "complete", "tracks": []}, url=_transcript_url_re(key)
     )
+    # get_recording МОК присутствует специально: если реализация (сегодняшняя,
+    # непочиненная) всё же вызовет его — вызов должен УСПЕШНО пройти и быть
+    # засчитан `_count_recording_calls`, а не свалить тест сторонней ошибкой
+    # pytest_httpx «нет зарегистрированного ответа».
     httpx_mock.add_response(
-        json={"id": key, "participants": []}, url=_recording_url_re(key)
+        json={"id": key, "participants": [{"userInfo": {"key": "u1"}}]},
+        url=_recording_url_re(key),
     )
 
     rc = _run(
@@ -454,12 +529,211 @@ def test_nfr17_out_of_range_chunk_with_default_verify_does_not_crash_on_json_par
     )
     raw = capsys.readouterr().out
 
-    assert len(httpx_mock.get_requests()) == 2, (
-        "NFR17 (edge case чанкинга, умолчание-включено): сверка обязана произойти "
-        f"даже на этом пути (два вызова), фактически {len(httpx_mock.get_requests())}"
+    assert rc == 0, (
+        f"NFR17-AC5: чанк вне диапазона — usage error нет, команда не должна "
+        f"падать, stdout: {raw!r}"
+    )
+    assert _count_recording_calls(httpx_mock, key) == 0, (
+        "NFR17-AC5 (ADR-024 Д3): `--chunk` вне диапазона НЕ должен запускать сверку "
+        f"по сети вовсе — фактически вызовов get_recording: "
+        f"{_count_recording_calls(httpx_mock, key)}"
+    )
+
+    try:
+        out = json.loads(raw)
+    except json.JSONDecodeError:
+        pytest.fail(
+            "NFR17-AC5 (замаскированный отказ до правки): `--json`-вывод на чанке "
+            f"вне диапазона обязан быть валидным JSON-конвертом, а не нестрого-JSON "
+            f"текстом сообщения — получено {raw!r}"
+        )
+
+    identity_check = out.get("identity_check")
+    assert identity_check is not None, (
+        f"NFR17-AC5 (замаскированный отказ): `identity_check` не должен тихо "
+        f"пропадать при сборке `--json` на этой ветке, получено {out}"
+    )
+    assert identity_check["result"] == "not_checked", (
+        f"NFR17-AC5: чанк вне диапазона -> `not_checked`, получено {identity_check}"
+    )
+    assert identity_check.get("reason") == "chunk_out_of_range", (
+        "NFR17-AC5: причина обязана называть именно чанк вне диапазона (переиспользуя "
+        f"словарь исходов `not_checked`, ADR-024 §Д3), получено {identity_check}"
+    )
+    assert identity_check["result"] != "match", (
+        "NFR17-AC5 (замаскированный отказ): пропуск сверки не должен путаться с "
+        "успешным совпадением"
+    )
+    assert "error" in out and "99" in out["error"], (
+        f"сообщение о несуществующем чанке обязано дойти до пользователя под ключом "
+        f"`error`, получено {out}"
+    )
+
+
+@pytest.mark.httpx_mock(assert_all_responses_were_requested=False)
+def test_nfr17_malformed_negative_chunk_index_also_skips_network_call_and_signals_not_checked(
+    httpx_mock: HTTPXMock, monkeypatch, capsys
+):
+    """Класс «испорченный/опечатанный ввод» для NFR17-AC5: `--chunk -1` — не просто
+    большое число вне диапазона, а структурно бессмысленное значение (пользователь
+    мог опечататься, введя отрицательный номер) — обязано давать тот же честный
+    исход, что и положительное значение вне диапазона, не отдельную непроверенную
+    ветку (например, не должно случайно попасть в валидный `chunk_index` через
+    Python-семантику отрицательной индексации где-то в реализации)."""
+    key = "REC-1"
+    httpx_mock.add_response(
+        json={"status": "complete", "tracks": []}, url=_transcript_url_re(key)
+    )
+    httpx_mock.add_response(
+        json={"id": key, "participants": [{"userInfo": {"key": "u1"}}]},
+        url=_recording_url_re(key),
+    )
+
+    rc = _run(
+        ["get-transcript", key, "--json", "--chunk", "-1", "--chunk-size", "10"], monkeypatch
+    )
+    raw = capsys.readouterr().out
+
+    assert rc == 0
+    assert _count_recording_calls(httpx_mock, key) == 0, (
+        "NFR17-AC5 (испорченный ввод, отрицательный чанк): сверка не должна "
+        f"запускаться, фактически вызовов get_recording: "
+        f"{_count_recording_calls(httpx_mock, key)}"
+    )
+    out = json.loads(raw)
+    assert out.get("identity_check", {}).get("reason") == "chunk_out_of_range", (
+        f"отрицательный `--chunk` обязан классифицироваться как вне диапазона, "
+        f"получено {out}"
+    )
+
+
+@pytest.mark.httpx_mock(assert_all_responses_were_requested=False)
+def test_nfr17_out_of_range_chunk_with_no_verify_identity_is_unaffected_by_hardening(
+    httpx_mock: HTTPXMock, monkeypatch, capsys
+):
+    """Регресс-guard (companion-спека, «Edge cases»): `--no-verify-identity` +
+    `--chunk` вне диапазона — поведение НЕ меняется ADR-024 Д3 (сверка и без того
+    отключена явным флагом, `identity_check` не появляется вовсе); ожидание — уже
+    верно на сегодняшнем дереве, тест закрепляет это (green guard), не проектирует
+    новое поведение."""
+    key = "REC-1"
+    httpx_mock.add_response(
+        json={"status": "complete", "tracks": []}, url=_transcript_url_re(key)
+    )
+
+    rc = _run(
+        [
+            "get-transcript",
+            key,
+            "--json",
+            "--chunk",
+            "99",
+            "--chunk-size",
+            "10",
+            "--no-verify-identity",
+        ],
+        monkeypatch,
+    )
+    raw = capsys.readouterr().out
+
+    assert rc == 0
+    assert _count_recording_calls(httpx_mock, key) == 0, (
+        "`--no-verify-identity`: сверка не должна запускаться независимо от чанка"
+    )
+    assert "identity_check" not in raw, (
+        f"`--no-verify-identity`: `identity_check` не должен появляться вовсе, "
+        f"получено {raw!r}"
     )
-    assert rc == 0, f"NFR17 (edge case чанкинга): команда не должна падать, stdout: {raw!r}"
     assert "не существует" in raw, (
         f"сообщение о несуществующем чанке должно дойти до пользователя как есть, "
         f"получено: {raw!r}"
     )
+
+
+# ============================================================================================
+# NFR17-AC5, unit — `formatters.resolve_chunk_range` (новая чистая функция, ADR-024 §3)
+# ============================================================================================
+
+
+def _five_entry_raw_transcript() -> dict:
+    """5 треков по одной реплике из 30 символов -> с `chunk_size=80` даёт РОВНО 5
+    raw-чанков (проверено на сегодняшнем `chunk_transcript_raw`, до правки —
+    фикстура объективна, не подогнана под ожидаемый ответ новой функции)."""
+    tracks = []
+    for i in range(5):
+        tracks.append(
+            {
+                "speaker": {"userInfo": {"key": f"u{i}"}, "isAnonymous": False},
+                "chunks": [{"startTimeOffsetInMillis": i * 1000, "text": "x" * 30}],
+            }
+        )
+    return {"status": "complete", "tracks": tracks}
+
+
+def test_nfr17_ac5_resolve_chunk_range_reports_in_range_for_a_middle_chunk():
+    from ktalk_cli.formatters import resolve_chunk_range
+
+    data = _five_entry_raw_transcript()
+
+    in_range, total_chunks = resolve_chunk_range(data, "raw", 3, 80)
+
+    assert total_chunks == 5, f"фикстура даёт 5 raw-чанков, получено {total_chunks}"
+    assert in_range is True, "чанк 3 из 5 — валидный номер, ожидался in_range=True"
+
+
+def test_nfr17_ac5_resolve_chunk_range_boundary_last_valid_chunk_is_in_range():
+    from ktalk_cli.formatters import resolve_chunk_range
+
+    data = _five_entry_raw_transcript()
+
+    in_range, total_chunks = resolve_chunk_range(data, "raw", 5, 80)
+
+    assert total_chunks == 5
+    assert in_range is True, (
+        "граница: последний валидный номер чанка (== total_chunks) обязан быть "
+        "in_range=True"
+    )
+
+
+def test_nfr17_ac5_resolve_chunk_range_one_past_last_chunk_is_out_of_range():
+    from ktalk_cli.formatters import resolve_chunk_range
+
+    data = _five_entry_raw_transcript()
+
+    in_range, total_chunks = resolve_chunk_range(data, "raw", 6, 80)
+
+    assert total_chunks == 5
+    assert in_range is False, (
+        "граница: total_chunks + 1 обязан быть out_of_range — ровно этот случай "
+        "воспроизводит issue #9"
+    )
+
+
+def test_nfr17_ac5_resolve_chunk_range_auto_chunk_zero_maps_to_first_chunk():
+    """`--chunk 0` (умолчание, «авто») -> при тексте длиннее `chunk_size` эквивалентен
+    первому чанку, та же семантика, что `render_transcript_output` сегодня
+    (`chunk_index = 0 if chunk == 0 else chunk - 1`) — новая функция не должна менять
+    этот выбор, только вынести его в переиспользуемую форму."""
+    from ktalk_cli.formatters import resolve_chunk_range
+
+    data = _five_entry_raw_transcript()
+
+    in_range, total_chunks = resolve_chunk_range(data, "raw", 0, 80)
+
+    assert total_chunks == 5
+    assert in_range is True, "`--chunk 0` при длинном тексте обязан маппиться на первый чанк"
+
+
+def test_nfr17_malformed_resolve_chunk_range_negative_chunk_is_out_of_range():
+    """Класс «испорченный/опечатанный ввод» на уровне чистой функции: отрицательный
+    номер чанка — не «просто больше total_chunks», а сам по себе структурно
+    невалидный ввод; не должен случайно стать валидным через Python-семантику
+    отрицательной индексации где-то в реализации `resolve_chunk_range`."""
+    from ktalk_cli.formatters import resolve_chunk_range
+
+    data = _five_entry_raw_transcript()
+
+    in_range, total_chunks = resolve_chunk_range(data, "raw", -1, 80)
+
+    assert total_chunks == 5
+    assert in_range is False, f"отрицательный чанк обязан быть out_of_range, total_chunks={total_chunks}"