git clone https://github.com/omercagatay/bddk-mcp.git
cd bddk-mcp
uv sync

export BDDK_JWT_ISSUER=https://idp.invalid
export BDDK_JWT_RESOURCE=https://localhost:8000/mcp
export BDDK_JWT_JWKS_URL=https://idp.invalid/jwks
export BDDK_JWT_AUDIENCE=bddk-mcp-local
docker compose up --build -d bddk-bootstrap
docker compose wait bddk-bootstrap
export BDDK_DATABASE_URL=postgresql://bddk_local_public:local-only-public@localhost:5432/bddk

uv run --frozen bddk-mcp verify-corpus

BDDK_INGESTION_DATABASE_URL='postgresql://INGESTION:SECRET@HOST:5432/DATABASE?sslmode=verify-full&sslrootcert=%2FAPPROVED%2Fpostgres-ca.crt' \
  uv run --frozen bddk-mcp bootstrap \
    --seed-dir /APPROVED/CORPUS \
    --reindex-existing \
    --require-quantified-freshness \
    --require-measured-freshness \
    --require-verified-signature \
    --trusted-signing-key /APPROVED/TRUST/corpus-signing-public-key.pem

BDDK_RELEASE_VERIFIER_DATABASE_URL='postgresql://VERIFIER:SECRET@HOST:5432/DATABASE?sslmode=verify-full&sslrootcert=%2FAPPROVED%2Fpostgres-ca.crt' \
BDDK_RELEASE_VERIFIER_REVISION_SHA256='REPLACE_64_LOWERCASE_HEX_REVISION' \
BDDK_RELEASE_VERIFIER_IMAGE_DIGEST='sha256:REPLACE_64_LOWERCASE_HEX_IMAGE_DIGEST' \
BDDK_RELEASE_VERIFICATION_VALIDITY_SECONDS=900 \
  uv run --frozen bddk-mcp verify-and-stage-corpus-release \
    --seed-dir /APPROVED/CORPUS \
    --trusted-signing-key /APPROVED/TRUST/corpus-signing-public-key.pem

BDDK_RELEASE_PUBLISHER_DATABASE_URL='postgresql://PUBLISHER:SECRET@HOST:5432/DATABASE?sslmode=verify-full&sslrootcert=%2FAPPROVED%2Fpostgres-ca.crt' \
  uv run --frozen bddk-mcp activate-corpus-release \
    --request-id corpus_release_request_sha256_REPLACE_64_LOWERCASE_HEX

uv run pytest tests/test_tools_sections.py tests/test_doc_store.py -k section -v
uv run ruff check .

BDDK_DATABASE_URL=postgresql://bddk:bddk@localhost:5432/bddk \
uv run --frozen bddk-mcp serve

BDDK_DATABASE_URL=postgresql://bddk:bddk@localhost:5432/bddk \
MCP_TRANSPORT=streamable-http \
PORT=8000 \
uv run --frozen bddk-mcp serve

Streamable HTTP MCP endpoint — это `http://localhost:8000/mcp`, сервер работает в режиме stateless JSON response. Remote-приложение публикует метаданные RFC 9728 protected-resource по пути `/.well-known/oauth-protected-resource/mcp`; 401 challenge возвращает тот же URL в `resource_metadata`. Это application-level discovery авторизации MCP; это не является доказательством регистрации/приёмки клиента в банковском IdP. Фиксированные, не зависящие от содержимого probe-эндпоинты — это `GET /health/live` и `GET /health/ready`; readiness периодически перепроверяет миграции, критические объекты каталога, публикацию корпуса и workload-ACL. Хотя probe-эндпоинты исключены из проверки authentication/Host, они подчиняются процессным rate- и concurrency-лимитам. Binding вне loopback работает по принципу fail-closed: обязательны точные Host/HTTPS Origin allowlist и полные настройки JWT/JWKS; публичный профиль требует scope `bddk.read`, операторский профиль — scope `bddk.operator`. Удалённый оператор также требует явного opt-in через `BDDK_OPERATOR_REMOTE_ENABLED=true`. `BDDK_HTTP_ALLOW_UNAUTHENTICATED` — это поддерживаемый явный opt-in для публичного read-only bind вне loopback без bearer authentication; по умолчанию он не задан, и пока он не задан, fail-closed default не меняется. При установке его нельзя сочетать ни с какой настройкой с префиксом `BDDK_JWT_` — запуск завершится с ошибкой и перечислит заданные переменные по именам — и он отклоняется для операторского профиля вне loopback независимо от значения `BDDK_OPERATOR_REMOTE_ENABLED`; инструменты оператора остаются authenticated или loopback-only. Неаутентифицированный сервер не публикует OAuth discovery: нет `WWW-Authenticate` challenge, и оба well-known OAuth route возвращают 404. Host/Origin allowlist, а также лимиты body, concurrency и rate продолжают применяться; в этом режиме rate limiter — основной контроль злоупотреблений. Ключ клиента для rate limiter'а определяется настройкой `BDDK_HTTP_TRUSTED_PROXY_HOPS` (default `0`): при значении `0` ключом является ASGI socket peer, а `X-Forwarded-For` полностью игнорируется; за обратным прокси, контролируемым оператором, задаётся реальное количество hop `n`, а ключом становится `n`-я запись объединённого forwarded-списка справа. Недоступные значения не откатываются к socket peer, а попадают в общий bucket `unknown`; неверное значение делает лимитер либо общим, либо спуфингуемым. Лимиты body, concurrency и rate-лимиты на минуту применяются внутри процесса приложения; они не обеспечивают глобального ingress-лимита между репликами. Подробности см. в [документации по развёртыванию](docs/DEPLOYMENT.md).

Старый вспомогательный скрипт импорта/экспорта seed тоже сохранён; для новых развёртываний предпочтителен `bddk-mcp bootstrap` с проверкой:

GXP9

### Конфигурация Claude

[`.mcp.json`](.mcp.json) в корне репозитория — это переносимый stdio-пример для клиентов, совместимых с `.mcp.json`, использующих корень репозитория в качестве рабочей папки:

GXP10

### Конфигурация Codex

Codex CLI и IDE extension используют одну и ту же настройку Codex MCP. Добавьте следующее в `~/.codex/config.toml` или в `.codex/config.toml` внутри доверенного репозитория; измените `cwd` на путь до вашего checkout:

GXP11

Проверьте подключение через `codex mcp list` или `/mcp` в Codex.

Ограничения Docker, Railway и OpenShift AI — в [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).

### Пример запросов

GXP12

### Сценарии использования оператора

Проверка качества:

GXP13

Dry-run для документов с проблемами качества:

GXP14

Повторное извлечение конкретного документа с quality failure:

GXP15

Пересоздание таблицы `document_sections` из существующих документов по идентификатору ingest:

GXP16

Скрипты quality backfill, sync и reindex, выполняющие изменения, также требуют `BDDK_INGESTION_DATABASE_URL` и проверяют точный privilege contract `bddk_ingestion`; их нельзя запускать с public или operator DSN.

Опциональная retrieval-телеметрия:

GXP17

Телеметрия по умолчанию выключена. При включении отдельный LOGIN должен наследовать только роль `bddk_telemetry_writer`; при запуске проверяются column-scoped привилегии INSERT-only и отклоняются чтение/изменение trace или широкое членство. В таблицу `tool_call_traces` записываются latency, result count, doc ID, флаг качества и сводка релевантности; текст query/prompt хранится как hash/length summary. Сырой текст записывается только при явном `BDDK_TELEMETRY_STORE_TEXT=true`.

### Архитектура

GXP18

### Примечания по качеству данных и безопасности

* Полные ответы по документам и retrieval по разделам берётся из локального store; эти два потока не делают live-fetch документов в рантайме.
* Инструменты обновления кэша каталога, поиска по учреждениям/объявлениям и бюллетеням могут обращаться к upstream-сервисам BDDK в зависимости от конфигурации и состояния кэша.
* Live-регуляторные HTTP-пути применяют точные HTTPS-хосты BDDK нормативных положений, повторную проверку redirect/DNS и контентные streaming-лимиты по типу artifact; URL/query/текст исключений не пишутся в retry-логи. Поскольку публичные инструменты для учреждений/объявлений/бюллетней/обновлений тоже могут выполнять live-обращение к BDDK, egress-контракт OpenShift должен давать как публичному, так и операторскому runtime доступ только к одобренным regulatory-source или прокси через TCP 443; lifecycle Job'ам этот доступ выдавать нельзя. Из-за гонок DNS-to-connect обязательна NetworkPolicy или одобренный прокси/firewall.
* Модель эмбеддинга по умолчанию зафиксирована на полном коммите `d13f1b27baf31030b7fd040960d60d909913633f`, опциональный reranker по умолчанию — на `1427fd652930e4ba29e8149678df786c240d8825`; иммутабельная схема принимает только `vector(768)`. Изменение настроек model/chunk требует контролируемого полного re-embedding и retrieval regression.
* Запись о публикации retrieval пишется только после проверки целостности chunk, актуального content hash и активной конфиденциальности retrieval; отсутствующий или устаревший индекс не подмешивается в результаты поиска незаметно.
* Bootstrap связывает проверенный corpus с точными artifact-path'ами из манифеста и отклоняет reserved seed filename bypass. Отдельный прогон `verify-corpus` — только диагностический preflight; production security gate'в нужно закреплять за той же командой `bootstrap` и отдельно подмонтированным trust key. `deploy/openshift-overlays/bank-bootstrap` проверяет в том числе эту команду, read-only PVC approved-corpus и отдельный Secret corpus-trust в repository preflight; реальная подготовка PVC/Secret и запуск Job остаётся внешним gate.
* v0005 добавляет append-only release/activation и mutation epoch для 17 corpus-таблиц; строгие локальные corpus-вызовы сверяют один и тот же active release до и после вызова. v0008 удаляет у издателя прежнее право прямой публикации: `bddk_release_verifier` читает material корпуса/trust, доказывает строгое соответствие и ставит запрос в очередь с TTL 60–3600 секунд, привязанным к verifier/image digest; `bddk_release_publisher` может выполнить activation только по одноразовому request ID. Activation повторно проверяет expiry, повторное использование, readiness публикации, epoch корпуса и state hash атомарно. Если один и тот же principal имеет доступ к обеим ролям или правам schema-owner — разделение нарушено; custody Secret/RBAC банка должна это предотвращать. v7 дополнительно копирует и фиксирует точное active state в 17 типизированных retained relations через `retain-corpus-generation --expected-release-id ...`; retained generation не является serving/reactivation. Ре-миграцией noncanonical-хэша v7 и ранее является строго проверенный publication-only compatibility boundary в неизменной v5/v6-схеме; после перехода на v7 прямой путь v8 не должен использоваться как steady-state. CLI `publish-corpus-release` в текущем бинарнике отключён; не создавать исторических строк и binding'ов; применять approved upgrade remediation и пройти миграцию v8 и grants. Tracked corpus подписан и сообщает о 9 675 chunk'ах, сгенерированных текущим профилем. Release-ledger v0010 принимает ровно две роли fresh policies: `quantified_measured_signature_verified_pass` и weaker `quantified_unmeasured_signature_verified_pass`; обе требуют числовую цель и проверенную подпись. Verifier выводит уровень из манифестного подтверждения; `--accept-unmeasured-freshness` разрешает только слабый уровень и не может пометить его как measured.
* Quat v0004 `11` owner-controlled legal-curation таблиц разделяют content ID `SourceBlob` и acquisition ID `SourceArtifact`. Права на изменение — только у owner; v0008 verifier получает точное read-only исключение для пересчёта proof публикации. v7 в scope.. v0006 public `resolve_regulation_status` function/tool abstained при conflict/недостатcopyующего evidence. Синтетический real-PostgreSQL доказательство не является доказательством реального family/currentness.
* Evaluation-gatter требует четыре подписанных слоя: метрированный corpus, expert dataset, legal-curator attestation для exact Citation pack и legal-release checkpoint, который проверяет цепочку source/acquisition/page/excerpt. Эти роли могут быть раздельными: canonical corpus/dataset/curator/release signer fingerprints должны быть разными. Текущий preflight гарантирует криптографическую согласованность только при operator-provided anchors; banks authorization и model-score authorization всегда false. Tracked 20-case dataset является draft; key rotation, named reviewer policy и expert-case execution пока не completed.
* Supply-chain lane-контейнеры собираются локально с Buildx `--provenance=false --load`; manifest descriptor/digest, config digest, loaded image и Syft SBOM привязаны к одному image fail-closed. Репозиторий также производит неподписанные SLSA и проверяет совместимость model manifest/runtime/Dockerfile pinning. Результаты из pending exception не могут быть promotion-eligible; bank signing, admission и registry promotion всё ещё являются внешними gate.
* Runtime wheel/sdist не включает `<seed_data>`, benchmark данные и deployment assets; предоставленный container включает протаски сверенный seed. При установке из wheel должен быть подключён approved corpus и передан `--seed-dir` либо `BDDK_SEED_DIR` инструменту bootstrap.
* Низкокачественные выходные данные extraction помечаются как `warning` или `fail`.
* Для формул, перегруженных или OCR-испорченных документов может понадобиться проверка исходного PDF.
* В ответах `get_bddk_document` удаляются data URI, raw HTML и некоторые артефакты OCR.
* При ответе модель должна опираться только на результат инструмента; нельзя придумывать решения номер решения, дату или вывод о юридическом результате.
* Настройки качества извлечения, списка failed document'ов и команды backfill см. в [docs/DOCUMENT_QUALITY.md](docs/DOCUMENT_QUALITY.md).
* Кластер OpenShift банка, схема backup/restore и Claude/Codex/GPT/GPT-OSS/LLM Studio/local model client matrix ещё не прошли acceptance test с этим репозиторием.

***

<a id="english"></a>

## Английский языковой раздел

### Что это?

BDDK MCP Server направлен на предоставление безопасного, аудируемого интерфейса Model Context Protocol для данных турецкого банковского регулирования. Он спроектирован так, чтобы закреплять ответы LLM в локальных данных BDDK, а не полагаться на прежние знания модели. Текущие границы production-security указаны в [документации по deployment](docs/DEPLOYMENT.md).

Общие сценарии использования:

* Поиск по каталогу регуляторных документов BDDK.
* Поиск внутри тел документов с помощью семантического и полнотекстового retrieval.
* Получение пагинированных Markdown-документов.
* Получение точных юридических разделов, таких как `Madde`, `Ilke`, `Paragraf` и `Ek`.
* Запрос к еженедельным и ежемесячным банковским бюллетеням.
* Формирование регуляторных отчётов и сводок по трендам.
* Мониторинг качества документов, OCR/formula риска и сбоев извлечения.

### Основные возможности

* **Поверхность инструментов MCP SDK:** примеры для stdio и Streamable HTTP приведены для Claude/Codex; примеры не являются сертификацией совместимости для конкретного релиза.
* **Автономная выдача документов (offline-first):** текст нормативных актов и разделы отдаются из PostgreSQL/pgvector; инструменты поиска учреждений, объявлений и бюллетеней могут требовать доступ к вышестоящим системам.
* **Разделение каталога и тела документов:** `search_bddk_regulations` ищет по метаданным; `search_document_store` ищет по телам документов.
* **Выдача на уровне разделов:** `get_document_section` и `search_document_sections` поддерживают ссылки вида `943 Ilke 5` и `mevzuat_22599 Madde 9`.
* **Точное сохранение юридических ссылок:** лексические совпадения, такие как `Madde 9`, не отсеиваются плотным фильтром релевантности.
* **Метки качества:** выходные данные документов содержат метаданные качества `clean`, `warning` или `fail` и соответствующие флаги.
* **Очистка контекста документов:** `get_bddk_document` удаляет data URI, артефакты необработанного HTML/OCR и патологически длинные строки перед передачей в контекст модели.
* **Скрипты оператора:** включены сценарии проверки качества, обратного заполнения качества и переиндексации `document_sections`.
* **PostgreSQL + pgvector:** документы, разделы, полнотекстовый поиск и векторный поиск используют одну базу данных.

### Поверхность инструментов

Профиль процесса по умолчанию `public` (`BDDK_TOOL_PROFILE=public` или `bddk-mcp serve --profile public`) открывает только 17 публичных инструментов.

| Модуль                    | Инструменты                                                                                                       |
| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Поиск                     | `search_bddk_regulations`, `search_document_store`, `search_bddk_institutions`, `search_bddk_announcements` |
| Документы                 | `get_bddk_document`, `get_document_history`                                                                 |
| Разделы и правовой статус | `get_document_section`, `search_document_sections`, `resolve_regulation_status`                             |
| Граф регулирования        | `get_amendment_chain`, `get_cross_references`                                                               |
| Бюллетень                 | `get_bddk_bulletin`, `get_bddk_bulletin_snapshot`, `get_bddk_monthly`                                       |
| Аналитика                 | `analyze_bulletin_trends`, `get_regulatory_digest`, `compare_bulletin_metrics`                              |

Отдельный профиль процесса `operator` (`BDDK_TOOL_PROFILE=operator` или `bddk-mcp serve --profile operator`) добавляет 14 операторских инструментов к 17 публичным и суммарно открывает 31 инструмент. Для него нужен отдельный `BDDK_OPERATOR_DATABASE_URL` с правами на запись; отката к публичному DSN не происходит.

* `check_bddk_updates`
* `document_store_stats`
* `bddk_cache_status`
* `refresh_bddk_cache`
* `sync_bddk_documents`
* `trigger_startup_sync`
* `get_operator_job`
* `list_operator_jobs`
* `cancel_operator_job`
* `document_health`
* `health_check`
* `bddk_metrics`
* `backfill_degraded_documents`
* `document_quality_report`

Канонический реестр оператора содержит 17 публичных инструментов плюс 14 операторских инструментов — всего 31 MCP-инструмент. Мутирующие операторские инструменты немедленно возвращают квитанции о задании; для наблюдения за ними используйте `get_operator_job`, `list_operator_jobs` и `cancel_operator_job`. Записи заданий, хэшированные ключи идемпотентности, числовой прогресс и ограниченные метрики результата сохраняются в таблице PostgreSQL `bddk_operator.operator_jobs`. Аренда допуска заданий — сеансового уровня — предотвращает одновременную владение одним исполнителем из нескольких процессов; отдельная транзакционная блокировка изменений корпуса сериализует санкционированные пишущие транзакции и выпускающий редактор. Задачи исполнителя по-прежнему живут в процессе оператора, устаревшие работы в статусе `queued` никогда не «угадываются» автоматически, а переключение при отказе на несколько реплик не было принято в банковской среде. Поэтому стартовый шаблон OpenShift использует одну реплику с `Recreate`; это не представлено как очередь заданий банковской надёжности. Схемы бенчмарков экспортируются из того же канонического реестра оператора; прогоны бенчмарков должны содержать точный список инструментов и использованный профиль. См. [benchmark/README.md](benchmark/README.md).

### Быстрый старт

Требования:

* Python 3.12 или 3.13
* `uv`
* PostgreSQL 17 с `pgvector` и `unaccent` (в этом релизе при непроверенных старших версиях происходит закрытие с ошибкой)
* Опционально: Docker Compose

Установка:

GXP19

Одноразовый жизненный цикл локального PostgreSQL:

GXP20

Только для разработки через loopback, Compose выполняет: настройка роли/расширений DBA → миграция `migrate` от владельца схемы → гранты DBA → импорт `bootstrap`. Зарезервированные значения JWT `.invalid` нужны Compose только для разбора неиспользуемого определения HTTP-сервиса; этот жизненный цикл не запускает HTTP-сервер, и эти значения не являются допустимой конфигурацией сервера. Зафиксированные в нём пароли — это публичные тестовые фикстуры, их нельзя распространять на удалённые системы. В production `bddk-mcp migrate` выполняет только изменения схемы. `bddk-mcp bootstrap` требует уже мигрированную схему с выданными правами, после чего импортирует выверенный seed-каталог, разделы и 768-мерные эмбеддинги; он не производит миграцию. Полный порядок учётных субъектов и применения прав см. в [руководстве по развертыванию](docs/DEPLOYMENT.md).

Используйте опциональную предварительную проверку (preflight) только для чтения, чтобы просмотреть объявление корпуса и все три seed-артефакта, не открывая соединение с базой данных:

GXP21

Команда проверяет контрольные суммы, размеры, количества записей и времена актуальности, но не передаёт доверие последующему процессу. Производственный импорт должен заново применять строгие политики непосредственно в мутирующем вызове `bootstrap`:

GXP22

Перед открытием пула базы `bootstrap` проверяет точное содержимое `corpus_scope.yml` и объявленные в манифесте пути, байты и хэши артефактов; он отвергает присутствующие, но не объявление `documents.json`, `chunks.json` или `decision_cache.json`. Передавайте ключ доверия из отдельного Secret/для монтированного раздела вне корпуса. Объявление числовых показателей не является измерением: статус `measured` требует для каждого документа временну́ю линию ««авторитетная публикация → обнаружение источника → загрузка → извлечение → публикация в поисковой выдаче»» и вычисленные задержки в пределах этих нормативов. Текущий выверенный манифест не подписан, не содержит числовых показателей и считается `slo_evidence_status: not_measured`; он намеренно не проходит этот производственный bootstrap. Успешный вывод bootstrap включает не связанный с путём идентификатор манифеста и SHA-256 для регистрации оператором, а также обозначает публикацию как обязательную; сам он не сохраняет кандидата. Производственный жизненный цикл: `migrate` → `bootstrap` → `verify-and-stage-corpus-release` → `activate-corpus-release` (DBA применяет `02_grants.sql` между миграцией и bootstrap). Проверяющий использует отдельную идентичность `bddk_release_verifier` и `BDDK_RELEASE_VERIFIER_DATABASE_URL`; он повторно проверяет корпус и ключ доверия, контролирует точную принадлежность/состояние/epoch базы и возвращает короткоживущий идентификатор запроса. Ключ доверия должен находиться в отдельном монтируемом разделе, причём и переданный, и фактически разрешённый путь обязаны оставаться за пределами корня корпуса. `BDDK_RELEASE_VERIFIER_REVERSION_SHA256` должен содержать 64 шестнадцатеричных символа в нижнем регистре, `BDDK_RELEASE_VERIFIER_IMAGE_DIGEST` — представлять собой дайджест `sha256:`, а `BDDK_RELEASE_VERIFICATION_VALIDITY_SECONDS` ограничен диапазоном 60–3 600 секунд (по умолчанию 900). Издатель получает только этот идентификатор запроса и `BDDK_RELEASE_PUBLISHER_DATABASE_URL` — никакого PVC корпуса, манифеста, подписи или ключа доверия:

GXP23

Активация происходит с закрытием при истечении срока запроса, если он использован или изменилось состояние корпуса, эпоха или готовность. Старый псевдоним `publish-corpus-release` отключён для сохранения изоляции учётных данных.

Обычная миграция закрывается с ошибкой `fail closed` на базе, которая управляется не через журнал миграций. `--adopt-legacy` — это явный флаг только для точно поддерживаемого состояния после проверенной резервной копии и [инструкции по обновлению старой базы](docs/LEGACY_DATABASE_UPGRADE.md); это не флаг чистой установки и не средство общего ремонта. Заполненная база версии 2 также по умолчанию отказывается от миграции 3, потому что обратное заполнение поисковых выдачи (retrieval-publication backfill) берёт блокирующие блокировки и проверяет внешние ключи. Применяйте `--allow-retrieval-publication-backfill` только в плановом окне обслуживания, после остановки рабочих нагрузок, доказанной восстановимости резервной копии и репетиции восстановления сопоставимого размера. `BDDK_EXPECTED_DATABASE_NAME` и целевая база независимого DBA-скрипта должны совпадать с активной базой. За пределами изолированного локального Compose💥 DSN PostgreSQL обязаны использовать `sslmode=verify-full` и абсолютный путь `sslrootcert`.

Проверка:

GXP24

Запуск MCP через stdio:

GXP25

Запуск стримингового HTTP:

GXP26

Конечная точка Streamable HTTP MCP — `http://localhost:8000/mcp`, настроенная на ответы JSON без состояния. Приложение публикует метаданные защищённого ресурса RFC 9728 по адресу `/.well-known/oauth-protected/resource/mcp`, и запрос 401 через `resource_metadata` указывает на тот же URL. Это обнаружение механизма авторизации MCP на уровне приложения, а не подтверждение регистрация и поддержка потока в банковском IdP. Фиксированные «пустые» проверочные эндпоинты — `GET /health/live` и `GET /health/ready`; готовность периодически перепроверяет миграции, критически важные объекты каталога, публикацию корпуса и ACL рабочих нагрузок. Эти проверки обходят аутентификацию и Host-контроль, но подчинены лимитам по процессу и допустимому конкурентному вхождения. Сетевое подключение не через `loopback` без явных списков разрешённых Host/HTTPS Origin и полной конфигурации JWT/JWKS происходит с закрытием `fail closed`; публичный профиль требует `bddk.read`, операторский профиль — `bddk.operator`. Удалённый операторский HTTP также требует явного включения `BDDK_OPERATOR_REMOTE_ENABLED=true`. `BDDK_HTTP_ALLOW_UNAUTHENTICATED` — это поддерживаемый явный opt-in, позволяющий неаутентифицированную публичную read-only привязку вне localhost; он по умолчанию не задан, и до его установки поведение `fail closed` сохраняется. Если установлен, его нельзя комбинировать ни с одной установкой с префиксом `BDDK_JWT_` — при этом запуск отклоняется и называет переменные-нарушители — и он безусловно отклоняется для не-loopback операторского профиля независимо от `BDDK_OPERATOR_REMOTE_ENABLED`; инструменты оператора либо остаются аутентифицированы, либо применяются через local loopback. Сервер без аутентификации не анонсирует OAuth- обнаружение: отсутствует проверка `www-Authenticate`, а оба известных OAuth- route выдают 404. Host/Origin allowlists, лимиты тела, конкурсантность и лимит запросов продолжают действовать; главным средством защиты от злоупотреблений становится rate limiter. Его ключ клиента задаётся через `BDDK_HTTP_TRUSTED_PROXY_HOPS` (default `0`): при `0` лимитер определяет ключ по socket-пиру ASGI и полностью игнорирует `X-Forwarded-For`; за `n` подконтрольных оператору reverse-проектных, укажите реальное число переходов, чтобы ключом был `n`‑й элемент справа в объединяемом forwarded-списке. Любое непригодное значение деградирует до общего bucket `unknown`, а не падает к socket-pier; неверное значение делает rate limiter либо общим, либо обманчивым. Лимиты тела, конкурентности и операций в минуту действуют в пределах одного процесса приложения и не являются единым общим ingress-лимитом между репликами. Полный контракт см. в [руководстве по развертыванию](docs/DEPLOYMENT.md).

Служебная утилита импорта/экспорта seed остаётся доступной; для новых развертываний предпочитайте `bddk-mcp bootstrap`, поскольку он включает валидацию готовности:

GXP27

### Конфигурация Claude

Файл репозитория [`.mcp.json`](.mcp.json) — это переносимый пример stdio для клиентов, совместимых с `.mcp.json`, которые запускают его с корня репозитория как рабочей директории:

GXP28

### Конфигурация Codex

Codex CLI и расширение IDE используют одну конфигурацию MCP Codex. Добавьте в `~/.codex/config.toml` или в `.codex/config.toml` в доверенном репозитории, заменив `cwd` на ваш путь:

GXP29

Проверить подключение можно командой `codex mcp list` или `/mcp`.
Файдосм. в [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md). для границ Docker, Railway, OpenShift AI.

### Примеры запросов

GXP30

### Скрипты оператора

Запуск проверки качества документов:

GXP31

Пробное обратное заполнение (dry-run) при известных сбоях качества:

GXP32

Повторное извлечение одного известного ошибочного документа:

GXP33

Перестроение `document_sections` для существующих документов с идентичностью и загрузки:

GXP34

Исполненные скрипты обратного заполнения, синхронизации и переиндексации качества также требуют `BDDK_INGESTION_DATABASE_URL` и проверяют точный контракт привилегий `bddk_ingestion`. Не запускайте их с публичным или операторским DSN.

Необязательная телеметрия поиска:

GXP35

Телеметрия отключена по умолчанию. При включении её отдельный LOGIN должен наследовать только `bddk_telemetry_writer`; при запуске проверяется точный контракт INSERT-только с ограничением по колонкам, а чтения/изменения трасс или более широкое членство отклоняются. Сервер записывает задержки, количество результатов, идентификаторы документов, метки качества и сводки релевантности в `tool_call_traces`; текст запроса/подсказки хранится в виде хеша и сводки длины. Сырой текст хранится только при явной установке `BDDK_TELEMETRY_STORE_TEXT=true`.

### Архитектура

GXP36

### Примечания по качеству данных и безопасности

* Полные ответы по нормативным документам и разделам обслуживаются из локального хранилища; эти пути не выполняют «живую» загрузку документов во время выполнения.
* Обновление каталога, поиск учреждений/объявлений и инструменты бюллетеней могут обращаться к вышестоящим службам BDDK в зависимости от конфигурации и состояния кэша.
* «Живые» регуляторные HTTP-пути обеспечивают строгую проверку HTTPS-хостов BDDK/mevzuat, перепроверку перенаправлений/DNS и лимиты потоковой передачи, принадлежащие коду, по типу артефактов; логи повторов не содержат URL, строк запроса и текста исключений. Поскольку инструменты публичных учреждений, объявлений, бюллетеней и обновлений также могут вызывать «живые» источники BDDK, контракт исходящего трафика OpenShift должен предоставлять одобренным регуляторным источникам или прокси TCP 443 как для публичных, так и для операторских сред выполнения, но не для заданий жизненного цикла. NetworkPolicy или одобренный прокси/межсетевой экран остаются обязательными, поскольку проверка DNS не может устранить гонку DNS-к-подключению.
* Модель внедрения по умолчанию зафиксирована на полном коммите `d13f1b27baf31030b7fd040960d60d909913633f`, необязательный ранжировщик по умолчанию — на `1427fd652930e4ba29e8149678df786c240d8825`, а неизменяемая схема принимает только `vector(768)`. Изменение модели/настроек фрагментации требует контролируемого полного повторного внедрения и регрессионного тестирования поиска.
* Запись публикации поиска выполняется только после проверки целостности фрагментов, текущего хеша содержимого и активного профиля поиска; неполные или устаревшие индексы не смешиваются молча с результатами поиска.
* Bootstrap привязывает проверенный корпус к точным путям артефактов манифеста и отклоняет обходы зарезервированных имён файлов-начальных данных. Отдельный запуск `verify-corpus` — это только диагностическая предварительная проверка; производственные доверительные шлюзы должны передаваться непосредственно тому же вызову `bootstrap` с отдельно смонтированным доверительным ключом. `deploy/openshift-overlays/bank-bootstrap` проверяет точный инвентарь этой команды, корпус-PVC только для чтения с одобренным корпусом и отдельный Secret доверия корпуса только для чтения в предварительной проверке репозитория; фактическое выделение банка и выполнение Job остаются внешними шлюзами.
* Миграция v0005 добавляет доказательства выпуска/активации только с добавлением и эпоху мутаций по 17 таблицам корпуса; строгие вызовы локального корпуса проверяют тот же активный выпуск до и после выполнения. Миграция v0008 отзывает старое разрешение прямого опубликования издателя: `bddk_release_verifier` читает материал корпуса/доверия, доказывает строгое членство и подготавливает запрос, привязанный к версии верификатора/провенансу образа и TTL 60–3600 секунд; `bddk_release_publisher` может активировать только одноразовый идентификатор запроса. Активация атомарно перепроверяет срок действия, повторное использование, готовность поиска, эпоху корпуса и хеш состояния. Доступ одного принципала к обеим ролям — или к полномочиям владельца схемы — разрушает разделение, поэтому custody Secret/RBAC банка остаётся обязательным. Миграция v0007 отдельно позволяет издателю запускать `retain-corpus-generation --expected-release-id ...` для фиксации точного активного состояния по 17 типизированным удерживаемым отношениям; удержание не является обслуживанием или реактивацией, привязанной к поколению. Исправление неканонических хешей до v7 остаётся точной, проверенной границей совместимости только для публикации на неизменённой схеме v5/v6; после достижения v7 оно не должно становиться обходным путём постоянного режима на пути к v8. Текущий бинарный файл отключает CLI `publish-corpus-release`; никогда не создавайте историческую строку или привязку — следуйте одобренному исправлению обновления, затем завершите миграцию и гранты v8. Отслеживаемый корпус подписан и объявляет 9675 фрагментов, которые регенерирует текущий профиль. Миграция v0010 допускает ровно две политики свежести — `quantified_measured_signature_verified_pass` и явно более слабую `quantified_unmeasured_signature_verified_pass` — обе требуют количественных целей и проверенной подписи. Верификатор выводит уровень из доказательств манифеста; `--accept-unmeasured-freshness` допускает более слабый уровень, но никогда не перемаркирует его как измеренный.
* 11 таблиц юридической курации, управляемых владельцем, из миграции v0004 разделяют исходное содержимое и идентичность приобретения. Мутации остаются только у владельца; v0008 даёт верификатору выпуска точное исключение только для чтения, необходимое для пересчёта доказательств публикации. V0006 добавляет публичный путь `resolve_regulation_status` с приоритетом воздержания. Синтетические доказательства на реальном PostgreSQL не устанавливают актуальность реального семейства регуляций.
* Шлюз оценки требует четыре подписанных уровня: измеренный корпус, экспертный набор данных, аттестацию юридического куратора по точному набору Citation и контрольную точку юридического выпуска по сохранённой истории исходников/приобретения/страниц/выдержек. Канонические отпечатки подписей корпуса/набора данных/куратора/выпуска должны различаться. Текущая предварительная проверка доказывает только криптографическую согласованность при якорях, предоставленных оператором; авторизация банка и авторизация оценки модели остаются ложными. Набор из 20 случаев является черновиком, а ротация ключей, политика именованных рецензентов и выполнение экспертных случаев остаются открытыми.
* Конвейер цепочки поставок собирает контейнеры локально с Buildx `--provenance=false --load`; он с отказом закрытия привязывает дескриптор/дайджест манифеста, дайджест конфигурации, загруженный образ и Syft SBOM к одному и тому же образу. Репозиторий отдельно создаёт неподписанную провенанс SLSA и проверяет согласованность пинов модели-манифеста/среды выполнения/Dockerfile. Любой результат, применяющий ожидающее исключение, никогда не подходит для продвижения; подпись банка, допуск и продвижение в реестр остаются внешними шлюзами.
* Колеса/sdist среды выполнения исключают `seed_data`, код бенчмарков и артефакты развёртывания; предоставленный контейнер явно включает проверенное начальное содержимое. Развёртывание колеса должно монтировать одобренный корпус и передавать `--seed-dir` или `BDDK_SEED_DIR` в bootstrap.
* Извлечения низкого качества помечаются как `warning` или `fail`.
* Документы с обилием формул или повреждённые OCR могут потребовать просмотра исходного PDF.
* `get_bddk_document` удаляет URI данных, необработанный HTML и выбранные артефакты OCR перед подачей в контекст модели.
* Модель должна отвечать только на основе вывода инструментов. Она не должна выдумывать номера решений, даты или юридические заключения.
* См. [docs/DOCUMENT\_QUALITY.md](docs/DOCUMENT_QUALITY.md) для известных проблем извлечения, отслеживаемого списка сбоев и команд обратного заполнения.
* Кластер OpenShift AI целевого банка, процесс резервного копирования/восстановления и матрица клиентов Claude/Codex/GPT/GPT-OSS/LM Studio/локальных моделей ещё не прошли приёмочное тестирование с этим репозиторием.

### Команды разработки

GXP37

Сфокусированные проверки, часто используемые в этом проекте:

GXP38

### Лицензия

Исходный код распространяется под [лицензией MIT](LICENSE). Документы из регуляторных источников и другие сторонние данные могут иметь отдельные условия происхождения или повторного использования; лицензия на код не предоставляет дополнительных прав на эти материалы. Подтверждённая граница, нерешённые решения и шлюз выпуска зафиксированы в разделе [Лицензирование и провенанс](docs/LICENSING_AND_PROVENANCE.md).