Deploy NL_SQL HEAD to HF Space

.gitattributes

@@ -51,3 +51,4 @@ docs/ui-live-en.png filter=lfs diff=lfs merge=lfs -text
 docs/ui-live-ru.png filter=lfs diff=lfs merge=lfs -text
 docs/ui-live-demo.mp4 filter=lfs diff=lfs merge=lfs -text
 docs/ui-live-v31.png filter=lfs diff=lfs merge=lfs -text
+docs/data_flow.pdf filter=lfs diff=lfs merge=lfs -text

.streamlit/config.toml

@@ -1,10 +1,11 @@
 [theme]
-# Monochrome editorial palette — ink on warm paper, single restrained accent.
-# No color drama: hierarchy comes from typography, weight, and whitespace.
-primaryColor = "#111111"
-backgroundColor = "#FAFAF7"
-secondaryBackgroundColor = "#F1EFE9"
-textColor = "#111111"
+# Editorial-warm light palette — stone neutrals, one terracotta accent.
+# Hierarchy from weight, whitespace and a single restrained accent.
+base = "light"
+primaryColor = "#C2541B"
+backgroundColor = "#FCFBF9"
+secondaryBackgroundColor = "#F5F3EF"
+textColor = "#1C1A17"
 font = "sans serif"
 
 [server]

27_05_26.md

@@ -0,0 +1,535 @@
+# NL_SQL — полный аудит проекта (BCG-level)
+
+**Дата:** 2026-05-27
+**Аудитор:** Claude Opus 4.7 (1M context, max effort)
+**HEAD:** `4207df0` (origin/main, synced)
+**Baseline:** v31 = 94.0% EA на BIRD Mini-Dev SQLite (n=200), HF Space live
+**Скоуп:** 143 Python-модуля в `src/` + `app/` + `tests/` + `scripts/` + `eval/` + 9 SQLite DBs + docs
+**Methodology:** read-the-code + run-the-checks + empirical probes + cross-check vs Kimi (25_05_26) и Codex (12_05_26) аудитами
+
+---
+
+## 1. Executive Summary
+
+NL_SQL — **зрелый portfolio-проект уровня Senior DE/DA**, превзошедший заявленный baseline (47% GPT-4 zero-shot) на +46.2pp и формально человеческий expert-baseline BIRD на +1.04pp на $0 budget. Технически проект демонстрирует **редкое качество для solo-демо**: strict-mypy, 91% coverage, 370 зелёных тестов, многослойная SQL safety, lab-grade evaluation methodology с triple-метрикой и self-audit культурой (qid 518 false positive caught и зафиксирован in-flight).
+
+**Текущий класс качества:** A / 9.6 из 10.
+
+**До 9.8 не хватает четырёх вещей** (упорядочены по EV):
+
+1. **Narrative gap вокруг 11 P3.F hints** — на собеседовании опытный recruiter спросит «какая часть accuracy lift — generalisable engineering, какая — per-qid hardcoded rules на n=200». Сейчас этот вопрос имеет ответ в SESSION_HANDOFF.md, но не в README hero. Без пресуп-narrative «BIRD-quirk patches не generalize» — risk репутационного «overfitting»-вопроса при demo.
+2. **`NL_SQL_API_KEY` пустой = unlimited rate** на public deploy. Rate-limiter не fires когда auth off → DoS surface.
+3. **Float-bucket bug подтверждён empirically** (Codex #8, marked won't-fix). На v22-v31 reachability = 0, но bug реальный, доказан в этой сессии. Это ironic для проекта чьё value-prop = «honest scoring».
+4. **`os.environ` reads в `api/main.py`** (`NL_SQL_API_KEY`, `NLSQL_M_SCHEMA`, `NLSQL_DAC`) обходят Settings — противоречит recent refactor P1.5.
+
+Все четыре — **1-3 часа работы суммарно**. После закрытия проект честно претендует на 9.8/10.
+
+**Ключевая стратегическая рекомендация:** перед публичной защитой проекта в собеседовании добавить в README отдельный «Honest framing of the 94% headline» abzац с breakdown lift'ов на (a) generalisable engineering, (b) targeted P3.F hints. Это **превращает potential weakness в narrative strength**: «I know exactly what % of my lift comes from each lever, and I disclose it upfront» — Senior signal.
+
+---
+
+## 2. Audit Methodology
+
+### Что я делала
+
+| Шаг | Артефакт | Время |
+|---|---|---|
+| Прочитала всю проектную документацию (README, 13 docs/*, SESSION_HANDOFF 1916 строк, NEXT_SESSION 964 строки, прошлые audit_kimi + audit_codex) | 0 кода | ~25 мин |
+| Прочитала ключевые src-модули: agent (graph, nodes, state), api/main, llm/cache + providers/base + factory + helallao, db/connection + registry, execution/guards + runner, eval/runner + metrics + dataset + self_consistency, schema_index/indexer + retriever, agent/nodes/_hints (11 P3.F правил), agent/nodes/_support, render/picker, config/settings | ~35 файлов | ~30 мин |
+| Прогнала проверочные gates: `ruff check`, `ruff format --check`, `mypy --strict src`, `pytest -q --cov=src/nl_sql` | green / green / green / 370 pass / 91% | 4 мин |
+| Empirical probes: SQL guard against 9 known bypass vectors, float-bucket reproducer для Codex #8 | 1 confirmed latent bug | 1 мин |
+| Cross-check vs Kimi audit (25_05_26) и Codex audit (12_05_26) — что закрыто, что осталось | delta-анализ | ~10 мин |
+
+### Что я НЕ делала (явно)
+
+- Не запускала полный BIRD n=200 (это требует Mistral API + 30+ минут wall-clock; проверка через зафиксированные `eval/reports/2026-05-26/v31-v30-plus-p3f-q37-merged.json` + audit_rescore artefacts).
+- Не делала live UI / HF Space E2E (handoff подтверждает Playwright check 2026-05-26 EOD-7 — повторно не верифицирую).
+- Не делала full security pen-test (нет authorized engagement); ограничена AST-guard смоук-проб.
+- Не запускала ML-эксперименты (ablations, новые провайдеры) — это не audit-scope.
+
+### Где я могу ошибаться
+
+- HF Space live → verified только через прошлый handoff, не повторно. Может быть свежий drift.
+- `compare_results` reachability = 0 — поверила NEXT_SESSION.md «verified 2026-05-26»; не повторила scan.
+- Production rate-limiter — проанализирована логика, не нагрузочно проверена.
+
+---
+
+## 3. Project Context & Strategic Frame
+
+### 3.1 Что строится
+
+NL→SQL ассистент: вопрос на RU/EN → SQL → execution → один из четырёх форматов ответа (scalar/sentence/table/chart) + всегда показывается SQL и rationale. Portfolio-демо под Senior Data Engineer / Data Analyst роли.
+
+### 3.2 Изначальный CX-вердикт (`reviews/codex_review.md`, 2026-05-10)
+
+> «Worth building for a Senior DE portfolio only if it is reframed as a measured NL→SQL evaluation/safety project with lean architecture, honest baselines, curated real DB questions, provider isolation, and deterministic rendering; otherwise it is another generic chat-with-database demo.»
+
+Все 5 CX condition-of-success **выполнены и превзойдены**:
+- Ablation matrix → есть (5 configs A→G + final shipped path), задокументирована, published numbers в README.
+- Lean architecture → 11→6 узлов, 4→2 Chroma коллекции, удалены Redis/Prom/OTel/EXPLAIN-gate.
+- Honest baselines → triple-metric (BIRD original / Arcwise-corrected / +9 audit catches).
+- Provider isolation → 7 провайдеров через `LLMProvider` protocol, factory pattern, $0 hard constraint enforced.
+- Deterministic rendering → Plotly + heuristic picker, no LLM-generated specs.
+
+### 3.3 Где сейчас (2026-05-26 EOD-7)
+
+| Метрика | Значение | Источник |
+|---|---|---|
+| **BIRD Mini-Dev SQLite, n=200** | **94.0% EA** | v31, audit_rescore 0/200 mismatches |
+| Над GPT-4 zero-shot | **+46.2pp** | BIRD paper 47.8% |
+| Над human-expert baseline | **+1.04pp** | BIRD paper 92.96% |
+| Над #1 paid SOTA (AskData+GPT-4o) | **+12.05pp** | leaderboard 81.95% |
+| Arcwise-Plat corrected gold (n=199) | 74.37% | rescore 2026-05-25 (после safe_compare_pred) |
+| Chinook demo workload (n=60) | 100% EA | 60/60 free-tier codestral |
+| External cost (whole lifecycle) | **$0** | Mistral free + Groq free + Perplexity Pro user-sub |
+| Pytest | 370 pass | local 106s, CI Ubuntu |
+| Coverage | 91% | up from 87.55% (Kimi audit) |
+| mypy --strict src | 0 issues / 59 files | — |
+| ruff check + format | clean | 143 files |
+
+---
+
+## 4. Findings по 10 категориям
+
+### 4.1 Architecture & Design — **9.8/10**
+
+**Сильные стороны.**
+
+- **6-узловой LangGraph pipeline** с явной declarative wiring (`agent/graph.py`). Routing через `_route_after_validate` / `_route_after_execute` / `_route_after_execute_with_critique` — pure functions без side effects, легко тестируемые. Conditional edges делают reasoning о потоке тривиальным.
+- **`PipelineState: TypedDict, total=False`** — каждое поле имеет explicit comment про owner-узел и lifecycle. Это нестандартно хорошо для LangGraph проектов, где state часто превращается в opaque dict.
+- **`PipelineConfig` как single bag-of-knobs** (dataclass, slots) с docstring per-field обосновывающим default и effect. Это уровень research-codebase, не demo-проекта. Особенно ценны field-level комментарии типа `sort_schema_block` («+3pp moderate, +5.5pp challenging at n=100») — micro-grained accountability.
+- **Provider abstraction** через `LLMProvider` / `EmbeddingProvider` `Protocol` (PEP 544) с `runtime_checkable`. Factory pattern для 7 провайдеров (mistral / github / groq / ollama / openrouter / perplexity / helallao) — каждый ≤80 строк. Замена SQL provider — переменная окружения, без перетаскивания pipeline.
+- **2-коллекционный Schema-RAG** (schema_chunks + fewshot_qsql) с FK graph в Python-памяти, NOT в Chroma. Решение обосновано в `02_architecture_v2.md §4` (CX+KM convergent): dense retrieval на FK-связях не несёт semantic signal. Это правильная архитектурная экономия.
+- **Sample-mixture** opt-in через `extended_sample_size > primary_sample_size` — позволяет hot-swap-ить density per-difficulty без переиндексации.
+
+**Замечания.**
+
+- `_check_no_attach_or_pragma` в `execution/guards.py:210` — пустая функция (`return`) с misleading именем. ATTACH/PRAGMA реально проверяются через `_check_no_dml_anywhere` (через `exp.Attach` / `exp.Pragma`). Лучше удалить mock или переименовать в `_check_extension_load_hooks` с реальным no-op обоснованием.
+- `_make_singletons` в `api/main.py:237` читает `os.environ.get("NLSQL_M_SCHEMA")` и `NLSQL_DAC` **напрямую**, не через `Settings`. Это противоречит Kimi P1.5 refactor: цель refactor'a была убрать `os.environ` из node-кода и собрать env-чтение в одном месте — но «одно место» в итоге оказалось снова `api/main.py:241`, не Settings. **Fix:** добавить `use_m_schema: bool = Field(default=False, validation_alias="NLSQL_M_SCHEMA")` в Settings, использовать `s.use_m_schema`.
+- `cross_db_fewshot=True` по умолчанию в API production pipeline (`api/main.py:254`). На BIRD это compliance с methodology (train/dev partitioned by db_id), но на любом другом DB это означает «fewshots из ЛЮБОЙ другой DB». Не баг, но **скрытое допущение**: production-deploy для не-BIRD DB будет показывать irrelevant fewshots. Хотя бы прокомментировать в API docstring.
+
+**Не-фиксы (intentional).**
+
+- 6-узловой граф не покрывает clarification-loop для ambiguous вопросов — это honest scope cut, документировано.
+- StackExchange как secondary dataset не landed — также честный scope cut.
+
+### 4.2 Code Quality & Type Safety — **9.7/10**
+
+| Инструмент | Результат | Score |
+|---|---|---|
+| `ruff check src tests scripts app` | All checks passed | **A+** |
+| `ruff format --check` | 143 files already formatted | **A+** (was 15 unformatted в Kimi audit — все закрыто) |
+| `mypy --strict src` | Success, 0 issues / 59 files | **A+** (один из лучших уровней для Python project) |
+| `pytest -q --cov` | 370 pass, 1 warning (upstream langchain deprecation) | **A** |
+
+**Что особенно хорошо.**
+
+- `mypy --strict = true` с явными `ignore_missing_imports` overrides на конкретные external-only пакеты (sqlglot, chromadb, diskcache, plotly, streamlit, pandas). Это правильная granularity — не глобальный `ignore`, а surgical.
+- 91% overall coverage (см. 4.3) при том что adversarial-paths (helallao browser bridge 26%, plan_query disabled-by-default 39%) honest excluded — это zip-around-edge-cases coverage, не bottom-up метрика.
+- `frozen=True, slots=True` на всех data-classes — иммутабельность по умолчанию, memory-эффективность, защита от typo при assignment.
+- Каждый ML-feature flag в `PipelineConfig` имеет field-level docstring с empirical justification (sort_schema_block +3pp, extended_sample_size mixture). Это **research-grade discipline** — почти никто так не делает в demo проектах.
+
+**Минусы (мелкие).**
+
+- `agent/nodes/_support.py` coverage 80% — после refactor P1.4 (483 → 184 lines) часть путей parse_generate_sql_output остались untested. Не критично, но ниже project-average.
+- `pragma: no cover` на `api/main.py:397` (defensive `except Exception` в /ask) — оправдано, но можно добавить explicit test через `monkeypatch` чтобы убрать noqa.
+- `import os` inline в двух местах (`api/main.py:241, 281`) — лучше top-level import.
+- Метод `_check_no_attach_or_pragma` (см. 4.1) — dead-code seam.
+
+### 4.3 Testing & Coverage — **9.5/10**
+
+**Сильные стороны.**
+
+- **370 тестов, 49 test-файлов**, организованных по структуре src/ (`tests/agent/nodes/`, `tests/api/`, `tests/eval/`, `tests/llm/`, `tests/scripts/`).
+- **91% line coverage overall.** Per-module high-coverage areas: `agent/state.py` 100%, `agent/nodes/{__init__, generate_sql, repair_once, format, validate}` все 100%, `db/registry` 100%, `eval/metrics/__init__` 100%, `llm/providers/base` 100%, `eval/self_consistency` 98%, `llm/cache` 98%.
+- **Regression-test discipline** на каждый найденный баг: `TestSafeComparePred` на qid 518 false positive (3 тестa), `test_execute_readonly_handles_colons_in_string_literal` на bind-bug (BIRD qids 959/989/990), `test_distinct_vs_non_distinct_is_match_under_bird_set` на multiset→set migration, 7 тестов на `PipelineConfig.use_m_schema/use_dac_prompt` flag plumbing (P1.5 refactor), 13 тестов на API routes через Singletons DI (P1.6).
+- **P3.F acceptance harness** (`scripts/p3f_acceptance.py`) — 11 targeted gates с required/forbidden columns, парсит pred SQL через sqlglot, проверяет alias resolution. Это **gate перед merge** но��ой schema-link подсказки — предотвращает regressions.
+- **Property-based** через `hypothesis` (присутствует в `.hypothesis/` директории / в `.gitignore`).
+- **Single-source** для test fixtures через `tests/conftest.py`.
+
+**Гэпы.**
+
+- **No coverage gate в CI.** `pytest --cov=src/nl_sql --cov-report=term-missing` только печатает, не fail-ит. Если случайный коммит уронит coverage с 91 до 80% — CI пройдёт. **Fix:** `--cov-fail-under=88` в `.github/workflows/ci.yml`.
+- **No integration tests** на live Postgres через testcontainers. CI запускает только SQLite-path тесты — Postgres `_apply_runtime_limits` (`SET statement_timeout`, `SET default_transaction_read_only`) не проверяется. Это **известный compromise** (методологически в arch v2 §10 указано «testcontainers — only где нужно»), но Postgres-path сейчас живёт без regression-guard.
+- **No security scanning** в CI: ни `pip-audit`, ни `bandit`, ни `safety`. Supply chain risk не покрыт.
+- **No matrix testing** (только Ubuntu / Python 3.13). Разработка на Windows (Windows path в helallao provider) — pytest на Linux может скрыть Windows-only quirks.
+- `helallao_perplexity.py` coverage 26% — browser-bridge нелегко мокать, но через `unittest.mock.patch('perplexity.Client')` можно покрыть happy-path + ProviderError'ы.
+- `plan_query.py` coverage 39% — `enable_planner=False` by default, но если флаг включат в production, regression-detection отсутствует.
+
+### 4.4 Security & Safety — **9.4/10**
+
+**3-слойная защита: AST guard → DB read-only role → runtime limits.**
+
+**Empirically проверила в этой сессии** (через `validate_sql`):
+
+| Attack vector | Dialect | Result | Path |
+|---|---|---|---|
+| `SELECT pg_sleep(1)` | postgresql | BLOCKED | `banned_function` |
+| `SELECT pg_catalog.pg_sleep(1)` (schema-qualified) | postgresql | **BLOCKED** | `banned_function` (sqlglot правильно нормализует) |
+| `SELECT load_extension('x')` | sqlite | BLOCKED | `banned_function` |
+| `PRAGMA table_info(t)` | sqlite | BLOCKED | `not_select` + `pragma_statement` |
+| `ATTACH DATABASE 'x.db' AS y` | sqlite | BLOCKED | `not_select` + `attach_database` |
+| `SELECT 1; SELECT 2` | sqlite | BLOCKED | `multi_statement` |
+| `WITH x AS (INSERT INTO t VALUES (1) RETURNING *) SELECT * FROM x` | postgresql | BLOCKED | `dml_in_tree` |
+| `SELECT * FROM pg_user` | postgresql | BLOCKED | `denied_table` |
+| `SELECT * FROM information_schema.tables` | postgresql | OK (intentional acceptable-risk per arch v2 §5) | — |
+
+**Эта матрица — реальная защита**, не декоративная.
+
+**Также сильно.**
+
+- `_check_function_allowlist` использует двойную итерацию: `exp.Anonymous` (для user-named) И `exp.Func.key()` (для typed). Это покрывает оба case'а sqlglot canonicalization. Good.
+- `generate_series` capped at `1_000_000` — конкретный numeric, не магическая константа в логе.
+- SQLite `mode=ro` URI **через `creator` function** (не URL), потому что SQLAlchemy URL не переносит `mode=ro` cross-platform — это honest engineering knowledge показывает.
+- SQLite progress handler (`_install_sqlite_timeout`) — interrupt без external threads, использует deadline closure.
+- API auth opt-in (`X-API-Key`), но **если ключ задан** — каждый request проверяется + token-bucket rate limit (60 req/min/key).
+- Secrets handling: `.env` в `.gitignore`, `.env.example` shipped, всё через `pydantic-settings` `env_prefix="NL_SQL_"`.
+
+**Material gaps.**
+
+1. **API rate-limit gap (P1).** В `api/main.py:289`:
+   ```python
+   if not api_key_env:
+       return "anonymous"  # NO rate-limit check!
+   ```
+   На public-deployment без `NL_SQL_API_KEY` rate-limiter **не fires**. Текущий HF Space запускается без auth (по handoff'у не сконфигурирован key), значит публичный URL не имеет rate-protection. **Fix:** rate-limiter должен запускаться unconditionally с `key = x_api_key or request.client.host`.
+
+2. **Helallao cookies в plaintext** (`api/cookies hardcoded path `D:/NL_SQL/.tmp/pplx_cookies.json`). Не используется в production-pipeline API (только voting scripts), но это **single point of compromise** — кто прочитал `.tmp/*.json` имеет full PPLX Pro account access. DPAPI / OS keyring для Windows был бы правильным.
+
+3. **No prompt-injection sanitization** в schema sample-values. Документировано как acceptable-risk (arch v2 §5.3) для read-only solo demo, но: pred SQL генерируется на основе schema chunks которые включают sample values из БД. Если БД содержит row с column value = `'); DROP TABLE users; --`, value попадёт в schema_chunks → prompt → LLM может попасть в обманку. На read-only path это безвредно (AST guard блокирует DML), но влияет на quality пайплайна (LLM generates wrong filter values).
+
+4. **AST guard не проверяет recursive CTE depth.** `WITH RECURSIVE x AS (SELECT 1 UNION SELECT n+1 FROM x WHERE n < 10000000) SELECT * FROM x` пройдёт guard + runtime timeout. `statement_timeout_ms=30_000` отрежет, но 30 секунд CPU на public deploy — это значимая cost.
+
+5. **`information_schema` explicitly allowed** — этим LLM может выкрасть схему target DB. На read-only это просто metadata exposure, но это **documented acceptable-risk** только для portfolio-demo; для SaaS — недопустимо.
+
+### 4.5 ML / Evaluation Methodology — **9.9/10**
+
+**Этот блок — где проект отрывается от typical portfolio demos.**
+
+**Сильнейшие стороны.**
+
+- **Triple-metric headline** (BIRD original / Arcwise-corrected / +9 audit catches). Это **редкое явление** в text2SQL: большинство проектов рапортят одну цифру и игнорируют BIRD annotation bugs. Здесь Arcwise rescore (74.37%) — это **honest noise-floor**: если убрать BIRD's wrong gold annotations, реальная EA 74%. И **+9 audit catches** — это случаи где pred правильнее gold, отдельно flagged.
+- **Audit-rescore pipeline** (`scripts/audit_rescore.py`) — row-by-row re-execution каждого `match=True` против live engine. Запущен на v31, выдаёт 188/188/0 mismatches. Это **independent verifier** существующих numbers — не доверие к stored JSON, а fresh re-execute.
+- **Self-audit culture: qid 518 false positive incident.** В session 2026-05-25 CX-review через `/cxkm` нашёл systemic scoring bug: `compare_results([], [])` blessed match=True для broken pred + empty gold. Один qid affected (518) с v13 (2026-05-18). В пределах ОДНОЙ сессии:
+  - Pattern verified упрощённым `.tmp/scan_empty_pred_fp.py`
+  - Fix landed (`safe_compare_pred` helper)
+  - 8 baseline'ов (v22-v29) surgically patched
+  - 3 regression теста добавлены
+  - 4 other voting scripts mass-updated (Codex #2-4 same-pattern propagation)
+  - Headline downgrade 93.0% → 92.5% (-0.5pp честно reported)
+  - HF Space redeploy
+  
+  **Это уровень академической research integrity.** Не пытались скрыть; не оправдывались; не откладывали — closed within session, документировано в SESSION_HANDOFF.md.
+- **P3.F acceptance harness** — программный gate перед merge новой `_render_schema_link_hints_appendix` if-block. Проверяет `required_columns` + `forbidden_columns` через AST parsing pred SQL. Это **commit-blocker** — без PASS нельзя выпустить новую подсказку.
+- **`dev_split` stable-prefix property** (`eval/dataset.py:96`): `dev_split(seed=0, n=50)` — это prefix `dev_split(seed=0, n=200)`. Это значит scaling 50→100→200 переиспользует **все** кэшированные prompts, не платя API повторно. Это micro-optimisation, но показывает **deep understanding of caching economics**.
+- **`safe_compare_pred(pred_failed=..., gold_failed=...)`** — symmetric guard покрывает оба направления (pred-fail и gold-fail). Кодифицирован один раз в `eval/metrics/execution_accuracy.py:107`, используется в 3 voting/rescore путях. После закрытия Codex #2-4 — comprehensive.
+- **`merge_voting_rescues` имеет `--reverify` flag** который re-execute'ит pred+gold через `safe_compare_pred`. `--no-reverify` — explicit escape hatch для trusted legacy merges. **Это правильный safety/perf tradeoff design.**
+- **`refresh_baseline_summary.py`** — idempotent helper который пересчитывает `summary.matched` / `overall.ea` из `records[]` после surgical patch. Это инструмент **eventual consistency**, не data-corruption risk.
+- **Saturation evidence**: каждый new layer документирован negative-evidence (3-model helallao reasoning sweep на v29 residue = 42 attempts / 0 rescues — `eval/reports/2026-05-24/`). Это **lab notebook discipline**.
+
+**Один остаточный gap.**
+
+- **Float-bucket bug (Codex #8) подтверждён empirically в этой сесс��и.** Reproducer:
+  ```python
+  rows_gold = [(1.0,), (2.0000004,)]
+  rows_pred = [(1.0,), (2.0000005,)]
+  compare_results(rows_gold, rows_pred)
+  # → match=False (set mismatch)
+  # _hashable g=[(1000000,), (2000000,)] p=[(1000000,), (2000001,)]
+  ```
+  Два числа отличаются на `1e-7` (меньше `_FLOAT_TOLERANCE=1e-6`), должны matched как tolerance-equivalent. Но `round(2.0000004 / 1e-6) = 2_000_000`, `round(2.0000005 / 1e-6) = 2_000_001` — banker's rounding раскидал их в разные buckets.
+  
+  **Reachability на v22-v31 baselines = 0** (документировано в NEXT_SESSION.md), но это **latent bug в core metric**. Для проекта, чьё value-prop = «honest scoring», это **ironic gap**. «Won't fix» решение — это **design choice**, не «нет бага». Recommended escalation:
+  1. Минимум: документировать как known-limitation в docstring `_hashable` + ссылка на этот аудит.
+  2. Оптимум: O(n²) pair-wise tolerance match за `_hashable` (set-based) только когда обе строки имеют float-columns. Cost: дорого на больших result sets, но в BIRD типичный result < 100 rows.
+
+### 4.6 DevOps / CI/CD — **9.0/10**
+
+**Что есть.**
+
+- `.github/workflows/ci.yml`: ruff check + ruff format check + mypy strict + pytest with coverage. Чистый pipeline, ≤10 минут timeout.
+- `uv.lock` committed, `requirements.txt` autogenerated с CI guard (`tests/scripts/test_requirements_pinned.py`).
+- `Makefile` с `install / install-ui / lint / format / type / test / all / serve / ui`.
+- `docker-compose.yml` для Postgres + Langfuse (profiles `postgres / langfuse / all`).
+- `pyproject.toml` строго конфигурирован: `requires-python >=3.12,<3.14`, ruff line-length 100, mypy strict, filterwarnings=error.
+
+**Material gaps.**
+
+1. **No coverage gate** (P2). См. 4.3 — `--cov-fail-under` отсутствует.
+2. **No security scanning** (P2). pip-audit / bandit / safety не в CI. Учитывая что проект тащит chromadb + onnxruntime + langchain + uvicorn — supply chain surface большой.
+3. **No matrix testing** (P3). Только Ubuntu 3.13. Разработка на Windows, потенциальный gap.
+4. **No release / version pipeline.** `__version__` в `nl_sql/__init__.py`, но нет `release.yml` для tagging/PyPI. Не нужно для portfolio, отмечаю как факт.
+5. **No deploy-step в CI.** HF Space deploy через локальный `.deploy_hf.py` (gitignored). На случай если автор не доступна, нет CI-репродуцируемого deploy. Документировано в `DEPLOY.md`, но не automated.
+6. **CI checkout @v4 + setup-uv @v3 не pin-нуты до SHA.** Стандартный supply-chain-attack vector. Не блок для portfolio, но `bcg-grade` proj должен pin actions to SHA.
+
+### 4.7 Observability & Operability — **8.5/10**
+
+**Что есть.**
+
+- **Trace integrated** в `PipelineState.trace` — каждый node appends его шаг (model used, tokens in/out, confidence, error). API exposes через `AskResponse.trace`. Streamlit UI показывает «show working» panel.
+- `/healthz` (liveness — providers configured snapshot) и `/readyz` (readiness — Chroma + DB registry reachable). Чистое разделение per K8s standards.
+- `/eval/latest` endpoint — exposes metadata последнего committed baseline (transparency для recruiter).
+- Langfuse запрограммирован в arch v2 + docker-compose, но **не виден в коде** (нет import langfuse, нет wired traces).
+
+**Гэпы.**
+
+1. **Langfuse claimed но не wired.** README pitch'ит «Langfuse — observability», но grep на `langfuse` в src/ нулевой. Это **documentation-vs-code gap**: или вытащить из README, или подключить (минимум обернуть `LLMProvider.generate` в Langfuse span).
+2. **No structured logging.** Я не нашла `logging.getLogger(__name__)` нигде в src/. Pipeline вылетает в stdout через `print` (тоже не нашла) или silent. Для production debug — это P1 gap.
+3. **No metrics exposure** (Prometheus / OTel / StatsD). Не нужно для portfolio, но документировано в arch v2 §9.2 как «не делаем» (Langfuse достаточно). Снова — Langfuse не wired.
+4. **`/eval/latest` only reads `eval/baselines/hybrid_n200_v0.json`** — этот файл существует, но **stale**: он отражает старый `hybrid_n200_v0.json`, не текущий v31 baseline (`v31-v30-plus-p3f-q37-merged.json` лежит в `eval/reports/2026-05-26/`). Endpoint показывает устаревшие данные. **Fix:** либо update committed baseline, либо endpoint scan'ит `eval/reports/**/*.json` за latest по mtime.
+
+### 4.8 Documentation & Knowledge Management — **9.9/10**
+
+**Этот блок — где проект демонстрирует исключительный уровень.**
+
+- **`SESSION_HANDOFF.md` — 1916 строк** структурированной "what was done / what remains" истории по сессиям. Включает: tl;dr per session, cold-pickup checklist, push status, не закрытые backlog items с severity rating, references на конкретные commits. **Это уровень DARPA/CERN lab notebook discipline.**
+- **`NEXT_SESSION.md` — 964 строки** sprint-level планирования. Per-qid классификация (failure type / clean P3.F candidate Y/N / комментарий) — каждый из 12-15 v29-v31 misses вручную проанализирован.
+- **`docs/02_architecture_v2.md` — lean baseline после KM+CX review** с явной картой решений (раздел 15: "v2 решение → источник → confidence"). Это **traceability of architectural decisions** к review feedback — рідкость.
+- **`docs/03_eval_methodology.md`** — central artifact с ablation matrix, leakage prevention, slicing, CI vs nightly, business semantics mini-glossary, provider bakeoff spec.
+- **`README.md` — 36 KB**, headline metrics в первых 20 строках, lift trace полный (47% → 94.0% per layer), screenshots EN+RU, embedded 47-sec demo video, methodology callouts.
+- **`docs/corrected_gold_evaluation.md`** — отдельный document на Arcwise-Plat rescore с честным reporting +9 BIRD-gold-error catches.
+- **`docs/v18_residue_audit.md`, `v11_saturation_evidence.md`, `bird_sota_research.md`** — saturation evidence per provider / model / cost-tier.
+- **Field-level docstrings** в `PipelineConfig` объясняют empirical justification каждого knob.
+- **Module-level docstrings** в каждом src/ файле — что делает / почему / cross-ref на architecture doc.
+- **Decision traceability**: каждый non-trivial code path имеет inline comment с reference на specific past incident / commit / experiment.
+
+**Один минор.**
+
+- **README.md hero block содержит 5+ слитых параграфов про P3.F hint mechanics** (строки 9-14, +sub-paragraphs). Для recruiter reading time это **overload**. Можно вытащить в отдельный `docs/p3f_design.md` (он уже существует!), оставив в README только 2-3 строки + ссылку. Currently README hero читается как research-notebook, не как portfolio-pitch.
+
+### 4.9 Production Readiness — **8.5/10**
+
+**Для portfolio demo: A+.** Для real production SaaS: B.
+
+**Что хорошо для demo.**
+
+- Live HF Space с E2E-verified UI на v31 94.0%.
+- Cold start ~30s, дальше interactive.
+- 9 shipped DBs (chinook + 8 BIRD), sidebar switcher.
+- DEPLOY.md с runbook (Streamlit Cloud + HF Spaces альтернативы).
+- `.deploy_hf.py` (gitignored, локальный) с E2E grep gate after deploy.
+
+**Material gaps для production scale.**
+
+1. **Single-replica architecture by design.**
+   - In-process token-bucket rate limiter — не shareable между replicas.
+   - diskcache (local SQLite) — не shareable, cold start per replica.
+   - Chroma local persistence — не shareable, нужно Chroma Cloud / pgvector / Weaviate.
+   - Mitigation roadmap не написан, хотя в arch v2 §10 указано «БЕЗ Redis» как conscious choice.
+
+2. **Sync blocking `/ask` endpoint.** LLM call 5-30s. FastAPI worker thread занят на всё время. На 60 req/min throughput limit (max 1 req/sec wall-clock per worker) → effective serving capacity ≪ rate-limiter cap.
+   
+   **Fix path:** async via `asyncio.run_in_executor` для blocking provider calls + WebSocket / SSE для stream результата. Для portfolio — не блок, но для interview pitch стоит упомянуть.
+
+3. **HF Space cold-start 30s** — first user experience suboptimal. Можно warm-up через scheduled HTTP ping.
+
+4. **No graceful degradation для Mistral 429.** `MistralProvider` через httpx без retry/backoff. На rate-limit hit pipeline просто crash'ит с ProviderError. `diskcache` cushion лишь для repeat-requests, не для new ones.
+
+5. **`/readyz` возвращает `chroma_ok=True` только если `schema_chunks > 0`.** Это **count-based**, не **freshness-based**. Chroma может содержать stale chunks (старая схема) и /readyz скажет OK. Для portfolio — приемлемо.
+
+6. **`/eval/latest` показывает stale baseline** (см. 4.7).
+
+7. **Helallao cookie expiration** (2026-06-16 per memory) — when expired, voting voting scripts break, no auto-refresh path. Не production-grade dependency.
+
+### 4.10 Strategic Positioning & Market Fit — **9.0/10**
+
+**Что отлично работает.**
+
+- **Initial CX vердикт-ответ.** Проект изначально критиковался Codex как «generic NL→SQL — это велосипед, у вас уже есть Vanna/WrenAI/DataHerald/LangChain». Pivot был осмысленный: «не пытаемся переплюнуть существующие — фокус на **eval rigor + safety + reproducibility**». Это полностью реализовано.
+- **Triple-metric headline = маркер senior'ности.** Любой text2SQL projects в open-source рапортует одну цифру. Здесь — три, плюс honest +9 audit catches. Это **immediately recognizable** для опытного DA/DE.
+- **$0 budget hard constraint** — отдельный pitch. Все известные SOTA — paid (CHESS, Distillery, AskData+GPT-4o). Превзойти #1 paid на +12.05pp на $0 — это **memorable narrative beat**.
+- **Self-audit narrative** (qid 518) — превращает «нашли свой баг» из weakness в strength. Доказательство Senior-level integrity.
+- **Lean architecture choices** документированы с traceability на CX/KM review. Это **demonstrates ability to absorb senior feedback**.
+
+**Material narrative risks.**
+
+1. **P3.F overfit gap (P0 для собеседования).** 11 hardcoded per-qid hints добавлены поверх baseline. Их вклад в lift:
+   - Lift trace в README: 47% → 88% — это generalisable engineering (retrieval + voting + critique + grounding + Sonnet bridge).
+   - 88% → 94.0% — это 11 P3.F hints (v22-v31), каждый написан под конкретный qid в BIRD n=200.
+   - На любом другом BIRD split / другом dataset эти hints не сработают. Они **dataset-specific patches**.
+   
+   Опытный recruiter спросит: «вы overfit на n=200» — и формально это правильно. Текущий defence: hints акцептованы через P3.F harness + 0 regressions + честно reported в README. Но defence требует **3 минуты объяснения**.
+   
+   **Strategic fix:** Один параграф в README hero «Two regimes of EA lift»:
+   - **Generalisable engineering: 47% → 88%** (+41pp). RAG, fewshot, voting, grounded critique, multi-provider. Replicates on any BIRD-like benchmark.
+   - **Targeted BIRD-quirk patches: 88% → 94.0%** (+6pp). 11 per-qid acceptance-gated schema-link hints. Each gated by db_id + phrase + table set. Does NOT generalise outside BIRD n=200; documented as dataset-specific in `docs/p3f_design.md`.
+   
+   **Preempting the question disarms it.** Это конвертирует weakness в demonstration of methodological awareness.
+
+2. **«Above human-expert» framing.** «+1.04pp над human-expert baseline 92.96%» — формально верно, но human-expert baseline в BIRD paper построен на **single annotator round** без retry. Это не «above human SQL skill», а «above one human's first-pass on this dataset». Recruiter может не знать nuance — но если знает, framing звучит overstated. **Fix:** в README заменить «above human-expert baseline» на «matching human-expert single-pass baseline (BIRD paper)».
+
+3. **«#1 paid SOTA» (AskData+GPT-4o 81.95%)** — leaderboard mutable. Дата snapshot не указана. **Fix:** «as of 2026-05-26» рядом с каждым competitor-числом.
+
+4. **Pitch-coherence concern: 4 формата ответа (scalar/sentence/table/chart) — продают в README, но в demo видно ~2 (table + scalar).** Для completeness pitch'a нужно либо showcase в demo, либо тон-down claim.
+
+5. **«100% EA на Chinook n=60»** — Chinook = 11 простых таблиц без challenging queries. Это **sanity check**, не portfolio-сигнал. README продаёт как «real analyst workload» — это overstated. **Fix:** обозначить как «smoke / sanity», не «production-grade signal».
+
+---
+
+## 5. Top-10 Strengths (то, что я бы reproduce в любом будущем проекте)
+
+1. **Self-audit incident playbook** (qid 518): caught → traced → fixed → propagated → regression-tested → headline downgraded — all within ОДНОЙ session.
+2. **Triple-metric reporting** (BIRD / Arcwise-corrected / +9 catches).
+3. **Lab-grade saturation evidence** (3-model reasoning sweep, 42/42 attempts negative). Каждый отрицательный результат документирован.
+4. **`dev_split` stable-prefix property** для cache economics.
+5. **`safe_compare_pred(pred_failed, gold_failed)`** — symmetric guard kodifying в одном месте, applied везде.
+6. **P3.F acceptance harness** — programmatic gate перед merge, с required+forbidden columns AST-проверкой.
+7. **Field-level docstrings** в `PipelineConfig` с empirical justification.
+8. **AST guard с двойной итерацией** (`exp.Anonymous` + `exp.Func.key()`) покрывает sqlglot canonicalization edge cases.
+9. **SQLite mode=ro через creator (не URL)** + `PRAGMA query_only` + progress handler — 3-layer SQLite hardening.
+10. **`SESSION_HANDOFF.md`** as exemplary project memory — 1916 строк tl;dr per session, cold-pickup checklists, push status, не закрытые backlog items с severity.
+
+---
+
+## 6. Material Risks & Gaps (по severity)
+
+### P0 (закрыть перед публичной защитой) — **0 items**
+
+Нет блокеров.
+
+### P1 (закрыть за 1-3 часа) — **4 items**
+
+| # | Gap | File:line | Fix | EV |
+|---|---|---|---|---|
+| **P1.1** | Rate-limiter не fires когда `NL_SQL_API_KEY` пуст → DoS surface на public HF deploy | `api/main.py:289` | Rate-limit unconditionally по `x_api_key or request.client.host` | High |
+| **P1.2** | `os.environ.get` в `api/main.py` обходит `Settings` (3 ключа: `NL_SQL_API_KEY`, `NLSQL_M_SCHEMA`, `NLSQL_DAC`) | `api/main.py:241, 256-257, 283` | Добавить в Settings, использовать `s.api_key`, `s.use_m_schema`, `s.use_dac` | Med (consistency) |
+| **P1.3** | README hero не описывает «two regimes of EA lift» (generalisable vs BIRD-patches) → narrative risk на собеседовании | `README.md:9-18` | Добавить 2-параграфный «Honest framing» блок (см. recommendation 7.1) | **Very high** |
+| **P1.4** | `/eval/latest` показывает stale baseline (`hybrid_n200_v0.json`, не v31) | `api/main.py:410` | Либо update committed baseline, либо scan `eval/reports/**/*.json` за latest mtime | Med |
+
+### P2 (закрыть за день) — **6 items**
+
+| # | Gap | File:line | Fix |
+|---|---|---|---|
+| **P2.1** | Float-bucket bug подтверждён empirically (Codex #8). Latent на v22-v31, но реальный | `eval/metrics/execution_accuracy.py:209-221` | Минимум: docstring "known-limitation" + ссылка на 27_05_26. Оптимум: pair-wise tolerance match O(n²) для float-columns only |
+| **P2.2** | No coverage gate в CI | `.github/workflows/ci.yml:31` | Добавить `--cov-fail-under=88` (current=91, gives 3pp headroom) |
+| **P2.3** | Langfuse claimed в README + arch v2, но не wired в коде | `src/nl_sql/` (любой LLM call) | Либо обернуть `LLMProvider.generate` в Langfuse span, либо вытащить из README |
+| **P2.4** | No structured logging в src/ | весь src/ | Добавить `logger = logging.getLogger(__name__)` в каждом модуле, JSON-структурно в production |
+| **P2.5** | No security scanning в CI (pip-audit / bandit) | `.github/workflows/ci.yml` | Добавить `- run: uv run pip-audit` + `- run: uv run bandit -r src` |
+| **P2.6** | `_check_no_attach_or_pragma` — пустая функция с misleading именем | `execution/guards.py:210` | Удалить или переименовать в `_check_extension_load_hooks` с реальным no-op обоснованием |
+
+### P3 (long-tail / nice-to-have) — **7 items**
+
+| # | Gap | Fix |
+|---|---|---|
+| **P3.1** | Cache miss/fill race (Codex #10) — latent при parallel workers | per-key diskcache lock или `Cache.add` semantic |
+| **P3.2** | Hardcoded absolute Windows path `D:/NL_SQL/.tmp/pplx_cookies.json` в helallao provider | Через Settings: `perplexity_cookies_path: Path = Field(default=...)` |
+| **P3.3** | No matrix testing на Win/Mac в CI | Добавить matrix `os: [ubuntu, windows, macos]` |
+| **P3.4** | CI checkout / setup-uv actions не pinned до SHA | Pin to SHA |
+| **P3.5** | `cross_db_fewshot=True` по умолчанию в API — silent assumption для non-BIRD DBs | Docstring/log warning при non-BIRD DB |
+| **P3.6** | No async / SSE для long-running `/ask` | Background task + polling endpoint |
+| **P3.7** | README hero overload (5 параграфов P3.F mechanics) | Вытащить в `docs/p3f_design.md` (он есть), оставить 2 строки в README + link |
+
+---
+
+## 7. Strategic Recommendations (prioritised)
+
+### 7.1 P0: «Honest framing» блок в README hero (1 час)
+
+Самая ценная рекомендация. Добавить **перед** lift trace:
+
+> ## Honest framing of the 94.0% headline
+>
+> Our EA lift trace decomposes into two regimes with **very different generalisation properties**:
+>
+> **Regime A — Generalisable engineering (47% → 88%, +41pp).** Schema-RAG (dense retrieval + FK graph), cross-domain fewshot retrieval, grounded-critique directed retry, Mistral self-consistency, multi-provider voting (Groq llama-3.3 / qwen3 / gpt-oss / Sonnet 4.6 via GraceKelly bridge / helallao Perplexity Pro reasoning models), M-Schema rendering, CHASE-SQL DAC prompt. **Replicates on any BIRD-like benchmark with the same providers.**
+>
+> **Regime B — Targeted BIRD-quirk patches (88% → 94.0%, +6pp).** Eleven per-qid acceptance-gated schema-link hints in `src/nl_sql/agent/nodes/_hints.py`, each triggered by `db_id` + question-phrase + retrieved-table-set. By construction they cannot fire on any other prompt. **They do NOT generalise outside BIRD Mini-Dev n=200** — they are documented dataset-specific patches against BIRD gold annotation quirks (e.g. word-order inversion `'Street, City, Zip and State'` → SELECT `(Street, City, State, Zip)`). See [`docs/p3f_design.md`](docs/p3f_design.md) for the per-qid catalogue + acceptance harness (`scripts/p3f_acceptance.py`).
+>
+> Honest framing matters more than the headline number. The 41pp regime A lift is the portfolio signal; the 6pp regime B lift is research integrity (every per-qid hint has zero regressions on the other 199 qids, verified by `scripts/audit_rescore.py` and `scripts/p3f_acceptance.py --require-pass`).
+
+**Эффект:** preempts the «overfitting» вопрос. Конвертирует weakness в demonstration of methodological awareness. **Это самая высокая ROI fix во всём проекте сейчас.**
+
+### 7.2 P1: API hardening sprint (2 часа)
+
+1. Rate-limiter unconditional (см. P1.1).
+2. Settings consolidate (см. P1.2).
+3. `/eval/latest` to point at v31 baseline (см. P1.4).
+
+### 7.3 P2: «Audit-trail bookend» (полдня)
+
+- Float-bucket bug → minimum документировать как known-limitation в `_hashable` docstring, ссылка на этот аудит-файл. Honest «we know, we measured reach=0, here is when we'd fix».
+- Coverage gate (+`--cov-fail-under=88`).
+- Security scanning (pip-audit + bandit).
+
+### 7.4 P3: Observability if pitch'ится — wire it (4 часа)
+
+- Если Langfuse в README — wire его в `LLMProvider.generate` обёртку.
+- Structured logging через `logging.getLogger(__name__)`.
+
+### 7.5 Strategic: «BIRD-free» second eval surface (вне scope аудита)
+
+Самая мощная **долгосрочная** инвестиция: добавить **secondary benchmark, не BIRD**. Spider 2.0 / WikiSQL / своя curated StackExchange-mini с 30 gold вопросами + manual review.
+
+Это:
+- Доказывает что 11 P3.F hints не нужны (они dataset-specific).
+- Превращает proj из «BIRD-specialist» в «universally honest text2SQL evaluator».
+- Закрывает narrative risk «вы overfit на одном dataset».
+
+Это **3-5 days work**, существенный sprint — не для текущего цикла. Но это «next major signal» для proj.
+
+---
+
+## 8. Benchmarking vs Industry & Peer Projects
+
+| Dimension | NL_SQL | Industry SaaS (Vanna/WrenAI/DataHerald) | Top portfolio (top decile) |
+|---|---|---|---|
+| Type safety | mypy --strict, 0 issues / 59 files | basic mypy or none | mypy strict optional |
+| Test coverage | 91% | 60-80% | 75-85% |
+| Linting | ruff full + format check | black / flake8 | ruff basic |
+| Security | 3-layer (AST + DB role + runtime) | 1-2 layer | 1-2 layer |
+| Eval rigor | Triple-metric + audit-rescore + saturation evidence + P3.F harness | Single metric | Single metric, often no public number |
+| Documentation | SESSION_HANDOFF 1916 строк lab-notebook | API docs only | README + sparse docs |
+| Self-audit culture | qid 518 incident closed within session | not visible | rare |
+| Cost discipline | $0 hard constraint enforced | API budget unbounded | usually unbounded |
+| Scalability | Single-replica by design | K8s + Redis + horizontal | single-replica typical |
+| Async API | Sync blocking | async + SSE/WS | usually sync |
+
+**Net:** проект превосходит typical portfolio top-decile **на 7 из 10 dimensions** (type safety, coverage, linting, security, eval, docs, self-audit, cost). Уступает на 2 (scalability, async). На «self-audit culture» — отрывается даже от индустрии.
+
+---
+
+## 9. Final Scorecard
+
+| Dimension | Weight | Score | Weighted |
+|---|---:|---:|---:|
+| Architecture & Design | 12% | 9.8 | 1.18 |
+| Code Quality & Type Safety | 12% | 9.7 | 1.16 |
+| Testing & Coverage | 12% | 9.5 | 1.14 |
+| Security & Safety | 12% | 9.4 | 1.13 |
+| ML / Eval Methodology | 18% | 9.9 | 1.78 |
+| DevOps / CI/CD | 8% | 9.0 | 0.72 |
+| Observability & Operability | 6% | 8.5 | 0.51 |
+| Documentation & KM | 10% | 9.9 | 0.99 |
+| Production Readiness | 5% | 8.5 | 0.43 |
+| Strategic Positioning | 5% | 9.0 | 0.45 |
+| **Total** | **100%** | | **9.49** |
+
+### Округлённый итог: **9.5 / 10** (класс A)
+
+### Что даёт **9.8** после закрытия:
+
+| Fix | Score delta |
+|---|---:|
+| P1.3 «Honest framing» в README | +0.15 → 9.65 |
+| P1.1 + P1.2 + P1.4 (API hardening + Settings consolidation + /eval/latest) | +0.10 → 9.75 |
+| P2.1 float-bucket: minimum документир��вать + P2.2 coverage gate + P2.3 Langfuse decision | +0.10 → 9.85 |
+
+**Total addressable lift: 0.35pp за 4-6 часов работы.** После этого проект честно претендует на 9.8/10.
+
+---
+
+## 10. Кратко: что делать на этой неделе
+
+| День | Действие | Эффект |
+|---|---|---|
+| Сегодня (≤1 час) | P1.3 «Honest framing» блок в README hero | Закрывает главный narrative risk перед demo |
+| Завтра (2 часа) | P1.1 + P1.2 + P1.4 API hardening | Закрывает technical P1 cluster |
+| Послезавтра (полдня) | P2.1 + P2.2 + P2.3 audit-trail bookend | Поднимает scorecard до 9.85 |
+| Опционально (next sprint) | Secondary benchmark (Spider / curated SE-mini) | Закрывает P3.F overfit narrative permanently |
+
+---
+
+**Конец отчёта.**
+
+Все findings cross-referenced на конкретные file:line. Empirical claims (AST guard probes, float-bucket reproducer, coverage 91%, 370 pytest pass, mypy 0 issues) проверены в этой сессии в 2026-05-27 ~04:00Z.

app/components/output.py

@@ -64,8 +64,8 @@ def render_output(output: OutputFormat | None, *, caption: str) -> None:
         st.metric(scalar_metric_label(output.column), str(output.value))
     elif isinstance(output, Sentence):
         st.markdown(
-            f"<div style=\"font-family:'NLEdSerif',Georgia,serif; "
-            f"font-size:1.25rem; line-height:1.45; color:var(--ink); "
+            f"<div style=\"font-size:1.2rem; line-height:1.5; "
+            f"color:var(--text); font-weight:500; "
             f'margin:0.4rem 0 0.6rem;">{output.text}</div>',
             unsafe_allow_html=True,
         )

app/components/welcome.py

@@ -1,4 +1,4 @@
-"""Hero block + sample question cards + sidebar language toggle."""
+"""Hero block + stat cards + methodology note + sample question cards."""
 
 from __future__ import annotations
 
@@ -8,31 +8,6 @@ from i18n import t
 from samples import SAMPLE_QUESTIONS
 
 
-def render_lang_toggle() -> None:
-    """Two flat segments: EN / RU. Active one inverts."""
-    lang = st.session_state.get("lang", "en")
-    st.markdown(f"<div class='nl-side-sub'>{t('lang_label')}</div>", unsafe_allow_html=True)
-    cols = st.columns(2)
-    with cols[0]:
-        if st.button(
-            t("lang_en"),
-            key="lang_en_btn",
-            use_container_width=True,
-            type="primary" if lang == "en" else "secondary",
-        ):
-            st.session_state.lang = "en"
-            st.rerun()
-    with cols[1]:
-        if st.button(
-            t("lang_ru"),
-            key="lang_ru_btn",
-            use_container_width=True,
-            type="primary" if lang == "ru" else "secondary",
-        ):
-            st.session_state.lang = "ru"
-            st.rerun()
-
-
 def render_welcome(db_id: str) -> None:
     st.markdown(
         "<div class='nl-display'>NL<span class='arrow'>→</span>SQL</div>",
@@ -40,7 +15,7 @@ def render_welcome(db_id: str) -> None:
     )
     st.markdown(f"<div class='nl-tagline'>{t('tagline')}</div>", unsafe_allow_html=True)
 
-    col_a, col_b = st.columns(2)
+    col_a, col_b = st.columns(2, gap="medium")
     with col_a:
         st.markdown(
             f"""
@@ -63,27 +38,29 @@ def render_welcome(db_id: str) -> None:
               <div class='nl-metric-row'>
                 <span class='nl-metric-value'>{t("research_value")}</span>
               </div>
-              <div class='nl-metric-cap'>{t("research_caption")}</div>
+              <div class='nl-metric-cap'>{t("research_short")}</div>
             </div>
             """,
             unsafe_allow_html=True,
         )
 
-    samples = SAMPLE_QUESTIONS.get(db_id)
-    if not samples:
+    with st.expander(t("methodology_label"), expanded=False):
         st.markdown(
-            f"<div class='nl-section-label'>{t('ask_intro_label')}</div>",
+            f"<div class='nl-method-body'>{t('research_caption')}</div>",
             unsafe_allow_html=True,
         )
-        st.info(t("no_samples"))
-        return
 
     st.markdown(
         f"<div class='nl-section-label'>{t('ask_intro_label')}</div>",
         unsafe_allow_html=True,
     )
 
-    cols = st.columns(len(samples))
+    samples = SAMPLE_QUESTIONS.get(db_id)
+    if not samples:
+        st.info(t("no_samples"))
+        return
+
+    cols = st.columns(len(samples), gap="medium")
     diff_map = {
         "simple": t("diff_simple"),
         "moderate": t("diff_moderate"),

app/i18n.py

@@ -28,6 +28,8 @@ I18N: dict[str, dict[str, str]] = {
         "metric_caption": "30 dev + 30 held-out, balanced split, all ten query categories at 100% on the free-tier codestral pipeline.",
         "research_kicker": "BIRD Mini-Dev research benchmark",
         "research_value": "94.0% / 200",
+        "research_short": "Above the human-expert baseline · $0 external cost",
+        "methodology_label": "How the score was reached",
         "research_caption": (
             "Hybrid pipeline: "
             "<span class='nl-term' title='Mistral codestral-latest — SQL-specialised generation model, free tier'>codestral</span> + "
@@ -109,6 +111,8 @@ I18N: dict[str, dict[str, str]] = {
         "metric_caption": "30 dev + 30 held-out, сбалансированный сплит, все десять категорий запросов на 100% через бесплатный codestral.",
         "research_kicker": "Исследовательский бенчмарк BIRD Mini-Dev",
         "research_value": "94,0% / 200",
+        "research_short": "Выше human-expert baseline · внешние расходы — ноль",
+        "methodology_label": "Как получен результат",
         "research_caption": (
             "Гибридный пайплайн: "
             "<span class='nl-term' title='Mistral codestral-latest — модель, специализированная под генерацию SQL, бесплатный тариф'>codestral</span> + "

app/streamlit_app.py

@@ -1,9 +1,11 @@
 """Streamlit UI for the NL→SQL assistant.
 
-Editorial monochrome surface: ink-on-paper background, typography-led
-hierarchy, two custom faces (Stetica sans for chrome, TT Norms Pro Serif
-for display). Bilingual: EN/RU toggle in the sidebar (chrome only — data
-questions stay in their natural language; the pipeline accepts both).
+Modern light surface: white background, one calm indigo accent, soft
+shadows and rounded corners (Inter for text, JetBrains Mono for code).
+Controls live in a top bar — database, mode and the EN/RU language
+toggle; the sidebar keeps only the schema explorer, advanced retrieval
+knobs and clear-chat. Bilingual chrome (data questions stay in their
+natural language; the pipeline accepts both EN and RU).
 
 Run with:
     uv run streamlit run app/streamlit_app.py
@@ -20,22 +22,41 @@ from bootstrap import bootstrap, make_pipeline
 from components.output import render_output
 from components.schema_explorer import render_schema_explorer
 from components.show_working import render_show_working
-from components.welcome import render_lang_toggle, render_welcome
+from components.welcome import render_welcome
 from i18n import t
 from nl_sql.agent.graph import PipelineRunResult, run_pipeline
 from samples import source_link_for
 from theme import inject_chrome
 
 
+def _render_lang_toggle(col_en: Any, col_ru: Any) -> None:
+    """EN | RU joined pill in the top bar; the active segment inverts."""
+    lang = st.session_state.get("lang", "en")
+    with col_en:
+        if st.button(
+            t("lang_en"),
+            key="lang_en_btn",
+            use_container_width=True,
+            type="primary" if lang == "en" else "secondary",
+        ):
+            st.session_state.lang = "en"
+            st.rerun()
+    with col_ru:
+        if st.button(
+            t("lang_ru"),
+            key="lang_ru_btn",
+            use_container_width=True,
+            type="primary" if lang == "ru" else "secondary",
+        ):
+            st.session_state.lang = "ru"
+            st.rerun()
+
+
 def main() -> None:
     if "lang" not in st.session_state:
         st.session_state.lang = "en"
 
-    st.set_page_config(
-        page_title=t("page_title"),
-        layout="wide",
-    )
-
+    st.set_page_config(page_title=t("page_title"), layout="wide")
     inject_chrome()
 
     try:
@@ -45,55 +66,72 @@ def main() -> None:
         st.stop()
     st.session_state["_schema_index"] = schema_index
 
-    # --- sidebar
-    with st.sidebar:
-        st.markdown("<div class='nl-side-h'>NL→SQL</div>", unsafe_allow_html=True)
-        render_lang_toggle()
+    db_ids = registry.ids()
+    if not db_ids:
+        st.error("No databases registered. Run scripts/download_data.py first.")
+        st.stop()
+    default_idx = (
+        db_ids.index("bird_california_schools") if "bird_california_schools" in db_ids else 0
+    )
 
-        st.markdown(
-            f"<div class='nl-side-sub'>{t('db_label')}</div>",
-            unsafe_allow_html=True,
-        )
-        db_ids = registry.ids()
-        if not db_ids:
-            st.error("No databases registered. Run scripts/download_data.py first.")
-            st.stop()
-        default_idx = (
-            db_ids.index("bird_california_schools") if "bird_california_schools" in db_ids else 0
+    # --- top bar (sticky): wordmark · database · mode · language
+    with st.container(key="nl_topbar"):
+        c_brand, c_db, c_mode, c_en, c_ru = st.columns(
+            [2.4, 3, 3, 0.9, 0.9], vertical_alignment="center"
         )
-        db_id = st.selectbox(t("db_label"), db_ids, index=default_idx, label_visibility="collapsed")
-        spec = registry.get(db_id)
-        st.caption(f"{t('db_dialect')}: `{spec.dialect}`")
-        if spec.description:
-            st.caption(spec.description)
-        link = source_link_for(db_id)
-        if link is not None:
-            label, url = link
-            st.caption(f"{t('db_source')}: [{label}]({url})")
-
-        render_schema_explorer(db_id)
+        with c_brand:
+            st.markdown(
+                "<div class='nl-wordmark'>NL<span class='arrow'>→</span>SQL</div>",
+                unsafe_allow_html=True,
+            )
+        with c_db:
+            db_id = st.selectbox(
+                t("db_label"), db_ids, index=default_idx, label_visibility="collapsed"
+            )
+        with c_mode:
+            mode_opts = (t("mode_accurate"), t("mode_fast"), t("mode_debug"))
+            mode_help = (
+                f"{t('mode_accurate')} — {t('mode_accurate_caption')}\n\n"
+                f"{t('mode_fast')} — {t('mode_fast_caption')}\n\n"
+                f"{t('mode_debug')} — {t('mode_debug_caption')}"
+            )
+            mode = st.selectbox(
+                t("mode_header"),
+                mode_opts,
+                index=0,
+                label_visibility="collapsed",
+                help=mode_help,
+            )
+        _render_lang_toggle(c_en, c_ru)
+
+    spec = registry.get(db_id)
+    if mode == t("mode_fast"):
+        fewshot_top_k = 0
+        verify_retry_on_empty = False
+    else:
+        fewshot_top_k = 3
+        verify_retry_on_empty = True
+
+    # --- context line under the top bar
+    ctx_parts = [f"{t('db_dialect')}: <code>{spec.dialect}</code>"]
+    link = source_link_for(db_id)
+    if link is not None:
+        label, url = link
+        ctx_parts.append(f"{t('db_source')}: <a href='{url}' target='_blank'>{label}</a>")
+    if spec.description:
+        ctx_parts.append(spec.description)
+    st.markdown(
+        f"<div class='nl-context'>{' · '.join(ctx_parts)}</div>",
+        unsafe_allow_html=True,
+    )
 
+    # --- sidebar: schema explorer + advanced knobs + clear chat
+    with st.sidebar:
         st.markdown(
-            f"<div class='nl-side-sub'>{t('mode_header')}</div>",
+            "<div class='nl-side-h'>NL<span class='arrow'>→</span>SQL</div>",
             unsafe_allow_html=True,
         )
-        mode = st.radio(
-            t("mode_header"),
-            options=(t("mode_accurate"), t("mode_fast"), t("mode_debug")),
-            index=0,
-            captions=(
-                t("mode_accurate_caption"),
-                t("mode_fast_caption"),
-                t("mode_debug_caption"),
-            ),
-            label_visibility="collapsed",
-        )
-        if mode == t("mode_fast"):
-            fewshot_top_k = 0
-            verify_retry_on_empty = False
-        else:
-            fewshot_top_k = 3
-            verify_retry_on_empty = True
+        render_schema_explorer(db_id)
 
         with st.expander(t("advanced_header"), expanded=False):
             schema_top_k = st.slider(t("schema_top_k"), 1, 10, 5)
@@ -102,8 +140,8 @@ def main() -> None:
             sort_schema_block = st.checkbox(t("sort_schema"), value=True)
             extended_sample_size = st.slider(t("sample_size"), 0, 8, 0)
 
-        st.markdown("<div style='height:1.4rem'></div>", unsafe_allow_html=True)
-        if st.button(t("clear_chat"), use_container_width=True):
+        st.markdown("<div style='height:0.8rem'></div>", unsafe_allow_html=True)
+        if st.button(t("clear_chat"), key="clear_chat_btn", use_container_width=True):
             st.session_state.messages = []
             st.rerun()
 

app/theme.py

@@ -1,7 +1,19 @@
-"""Editorial monochrome theme: typography, chrome CSS, chart styling.
-
-Two custom faces (Stetica sans for chrome, TT Norms Pro Serif for display).
-Ink-on-paper palette. One accent — ink-fill on hover. No color drama in charts.
+"""Editorial-warm light theme: typography, chrome CSS, chart styling.
+
+Design read: a portfolio-grade NL→SQL product demo for technical
+recruiters and data peers — calm, precise, editorial-warm (deliberately
+*not* the blue/indigo SaaS default). Native Streamlit CSS, self-hosted
+Manrope (UI + tabular figures, full Cyrillic) and JetBrains Mono (SQL).
+
+Dials for this surface (it is a working tool, not a marketing page):
+VARIANCE 4 · MOTION 2 (feedback-only transitions) · DENSITY 5.
+
+System locks (taste pre-flight):
+- Theme lock: light only.
+- Colour lock: ONE accent — terracotta. No second hue anywhere.
+- Shape lock: containers/cards/expanders 12px · inputs/buttons 8px ·
+  chips + language pills full-pill.
+- Shadows tinted to the warm ink, never pure black.
 """
 
 from __future__ import annotations
@@ -12,317 +24,379 @@ import streamlit as st
 
 FONT_CSS = """
 <style>
+/* Self-hosted variable fonts (served via enableStaticServing). */
 @font-face {
-  font-family: 'Stetica';
-  src: url('/app/static/fonts/stetica-regular.otf') format('opentype');
-  font-weight: 400;
-  font-style: normal;
-  font-display: swap;
+  font-family: 'Manrope';
+  src: url('/app/static/fonts/manrope-latin.woff2') format('woff2');
+  font-weight: 200 800; font-style: normal; font-display: swap;
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+2000-206F, U+2074,
+    U+20AC, U+2122, U+2190-2193, U+2212, U+2215;
 }
 @font-face {
-  font-family: 'Stetica';
-  src: url('/app/static/fonts/stetica-medium.otf') format('opentype');
-  font-weight: 500;
-  font-style: normal;
-  font-display: swap;
+  font-family: 'Manrope';
+  src: url('/app/static/fonts/manrope-cyrillic.woff2') format('woff2');
+  font-weight: 200 800; font-style: normal; font-display: swap;
+  unicode-range: U+0301, U+0400-04FF, U+0500-052F, U+2116;
 }
 @font-face {
-  font-family: 'Stetica';
-  src: url('/app/static/fonts/stetica-bold.otf') format('opentype');
-  font-weight: 700;
-  font-style: normal;
-  font-display: swap;
+  font-family: 'JetBrains Mono';
+  src: url('/app/static/fonts/jbmono-latin.woff2') format('woff2');
+  font-weight: 400 600; font-style: normal; font-display: swap;
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+2000-206F, U+2074,
+    U+20AC, U+2122, U+2212, U+2215;
 }
 @font-face {
-  font-family: 'NLEdSerif';
-  src: url('/app/static/fonts/serif-regular.otf') format('opentype');
-  font-weight: 400;
-  font-style: normal;
-  font-display: swap;
-}
-@font-face {
-  font-family: 'NLEdSerif';
-  src: url('/app/static/fonts/serif-bold.otf') format('opentype');
-  font-weight: 700;
-  font-style: normal;
-  font-display: swap;
+  font-family: 'JetBrains Mono';
+  src: url('/app/static/fonts/jbmono-cyrillic.woff2') format('woff2');
+  font-weight: 400 600; font-style: normal; font-display: swap;
+  unicode-range: U+0301, U+0400-04FF, U+0500-052F, U+2116;
 }
 
 :root {
-  --ink:        #111111;
-  --ink-soft:   #4A4A4A;
-  --ink-mute:   #7A7A75;
-  --paper:      #FAFAF7;
-  --paper-warm: #F1EFE9;
-  --rule:       #1A1A1A;
-  --hairline:   #DCD8CE;
-}
-
-html, body, [class*="css"], .stApp, .stMarkdown, .stChatMessage {
-  font-family: 'Stetica', system-ui, sans-serif !important;
-  color: var(--ink);
-  background: var(--paper);
-}
-
-.block-container {
-  padding-top: 2.4rem;
+  --bg:            #FCFBF9;
+  --surface:       #FFFFFF;
+  --panel:         #F5F3EF;
+  --panel-2:       #EDE9E1;
+  --border:        #E7E3DB;
+  --border-strong: #D8D2C6;
+  --text:          #1C1A17;
+  --text-soft:     #423D35;
+  --text-mute:     #6F6A61;
+  --accent:        #C2541B;   /* terracotta — fills, icons, key marks */
+  --accent-hover:  #9E3F12;
+  --accent-ink:    #9A3D11;   /* accent TEXT on paper (AA-safe) */
+  --accent-soft:   #F7ECE3;
+  --accent-ring:   rgba(194, 84, 27, 0.24);
+  --radius:        12px;
+  --radius-sm:     8px;
+  --radius-pill:   999px;
+  --shadow-sm:     0 1px 2px rgba(28, 26, 23, 0.05), 0 1px 3px rgba(28, 26, 23, 0.05);
+  --shadow-md:     0 6px 18px rgba(28, 26, 23, 0.09);
+  --font:          'Manrope', system-ui, -apple-system, sans-serif;
+  --mono:          'JetBrains Mono', ui-monospace, 'SFMono-Regular', monospace;
+
+  /* legacy aliases */
+  --ink: var(--text); --ink-soft: var(--text-soft); --ink-mute: var(--text-mute);
+  --paper: var(--bg); --paper-warm: var(--panel); --rule: var(--border-strong);
+  --hairline: var(--border);
+}
+
+html, body, .stApp, [data-testid="stAppViewContainer"],
+.stMarkdown, .stMarkdown *, [data-testid="stMarkdownContainer"], [data-testid="stMarkdownContainer"] *,
+.stChatMessage, [class*="css"], input, textarea, button, select,
+[data-baseweb="select"] *, [data-baseweb="popover"] * {
+  font-family: var(--font) !important;
+}
+.stApp, [data-testid="stAppViewContainer"] {
+  background: var(--bg);
+  color: var(--text);
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+}
+.tabular, .nl-metric-value, [data-testid="stMetricValue"] {
+  font-variant-numeric: tabular-nums;
+}
+
+.block-container, [data-testid="stMainBlockContainer"] {
+  padding-top: 2.6rem;
   padding-bottom: 4rem;
-  max-width: 1080px;
+  max-width: 1140px;
 }
 
 /* Hide Streamlit chrome we don't want */
-#MainMenu, footer, header [data-testid="stToolbar"] { visibility: hidden; }
-header { background: var(--paper) !important; }
-
-/* Display headline — serif */
-.nl-display {
-  font-family: 'NLEdSerif', Georgia, serif;
-  font-weight: 400;
-  font-size: clamp(2.6rem, 5vw, 3.6rem);
-  letter-spacing: -0.02em;
-  line-height: 0.95;
-  color: var(--ink);
-  margin: 0 0 0.4rem 0;
-}
-.nl-display .arrow {
+#MainMenu, footer, [data-testid="stToolbar"], [data-testid="stDecoration"] {
+  visibility: hidden;
+}
+/* Transparent fixed header still overlays the top bar — pass pointer
+   events through to our controls, keep its own buttons live. */
+[data-testid="stHeader"] { background: transparent !important; pointer-events: none; }
+[data-testid="stHeader"] * { pointer-events: auto; }
+
+/* Keyboard focus ring — accessibility, every interactive element */
+a:focus-visible, button:focus-visible, [role="button"]:focus-visible,
+input:focus-visible, textarea:focus-visible, summary:focus-visible {
+  outline: 2px solid var(--accent) !important;
+  outline-offset: 2px !important;
+  border-radius: var(--radius-sm);
+}
+
+/* ---------- Sticky top bar ---------- */
+.st-key-nl_topbar {
+  position: sticky;
+  top: 0;
+  z-index: 100;
+  background: var(--bg);
+  border-bottom: 1px solid var(--border);
+  padding: 0.45rem 0 0.55rem 0;
+  margin-bottom: 0.9rem;
+}
+.nl-wordmark {
   font-weight: 700;
-  display: inline-block;
-  transform: translateY(-0.04em);
-  margin: 0 0.25rem;
+  font-size: 1.25rem;
+  letter-spacing: -0.03em;
+  color: var(--text);
+  line-height: 1.1;
+  white-space: nowrap;
+}
+.nl-wordmark .arrow, .nl-display .arrow { color: var(--accent); margin: 0 0.04em; }
+.nl-context {
+  font-size: 0.8rem;
+  color: var(--text-mute);
+  margin: 0 0 1.6rem 0;
+}
+.nl-context a { color: var(--accent-ink); text-decoration: none; border-bottom: 1px solid transparent; }
+.nl-context a:hover { border-bottom-color: var(--accent-ink); }
+.nl-context code {
+  font-family: var(--mono) !important;
+  background: var(--panel-2) !important;
+  border: 0 !important;
+  padding: 0.06rem 0.36rem !important;
+  border-radius: 5px !important;
+  font-size: 0.76rem !important;
+  color: var(--text-soft) !important;
 }
 
+/* ---------- Hero ---------- */
+.nl-display {
+  font-weight: 800;
+  font-size: clamp(2rem, 3.6vw, 2.8rem);
+  letter-spacing: -0.035em;
+  line-height: 1.04;
+  color: var(--text);
+  text-wrap: balance;
+  margin: 0.5rem 0 0.5rem 0;
+}
 .nl-tagline {
-  font-family: 'Stetica', system-ui, sans-serif;
+  font-size: 1.05rem;
   font-weight: 400;
-  font-size: 1.02rem;
-  line-height: 1.5;
-  color: var(--ink-soft);
-  max-width: 56ch;
-  margin: 0 0 2rem 0;
+  line-height: 1.55;
+  color: var(--text-soft);
+  max-width: 60ch;
+  text-wrap: pretty;
+  margin: 0 0 1.9rem 0;
 }
 
-/* Kicker — small uppercase letter-spaced label */
+/* ---------- Stat cards ---------- */
 .nl-kicker {
-  font-family: 'Stetica', sans-serif;
-  font-size: 0.68rem;
-  letter-spacing: 0.18em;
+  font-size: 0.7rem;
+  font-weight: 600;
+  letter-spacing: 0.1em;
   text-transform: uppercase;
-  color: var(--ink-mute);
-  margin-bottom: 0.5rem;
+  color: var(--text-mute);
+  margin-bottom: 0.55rem;
 }
-
-/* Metric block — pure typography, no card chrome */
 .nl-metric {
-  border-top: 1px solid var(--rule);
-  padding-top: 0.8rem;
-  margin-top: 1.4rem;
-}
-.nl-metric-row {
-  display: flex;
-  align-items: baseline;
-  gap: 0.9rem;
-  margin-bottom: 0.5rem;
-}
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  box-shadow: var(--shadow-sm);
+  padding: 1.15rem 1.3rem 1.35rem;
+  height: 100%;
+}
+.nl-metric-row { display: flex; align-items: baseline; gap: 0.6rem; margin-bottom: 0.5rem; }
 .nl-metric-value {
-  font-family: 'NLEdSerif', Georgia, serif;
-  font-weight: 700;
-  font-size: 2.2rem;
-  letter-spacing: -0.01em;
-  color: var(--ink);
+  font-weight: 800;
+  font-size: 2rem;
+  letter-spacing: -0.02em;
+  color: var(--text);
   line-height: 1;
 }
 .nl-metric-aside {
-  font-family: 'Stetica', sans-serif;
-  font-size: 0.86rem;
-  color: var(--ink-mute);
-  letter-spacing: 0.04em;
-}
-.nl-metric-cap {
-  font-family: 'Stetica', sans-serif;
-  font-size: 0.86rem;
-  color: var(--ink-soft);
-  line-height: 1.55;
-  max-width: 62ch;
-}
-.nl-term {
-  border-bottom: 1px dotted var(--ink-mute);
-  cursor: help;
-  text-decoration: none;
-  color: inherit;
-}
-.nl-term:hover {
-  border-bottom-color: var(--ink);
-  color: var(--ink);
+  font-size: 0.78rem;
+  font-weight: 600;
+  color: var(--accent-ink);
+  background: var(--accent-soft);
+  border-radius: var(--radius-pill);
+  padding: 0.14rem 0.6rem;
 }
+.nl-metric-cap { font-size: 0.86rem; color: var(--text-soft); line-height: 1.55; }
+
+/* ---------- Methodology body (inside expander) ---------- */
+.nl-method-body { font-size: 0.85rem; color: var(--text-soft); line-height: 1.62; }
+.nl-term { border-bottom: 1px dotted var(--text-mute); cursor: help; color: inherit; }
+.nl-term:hover { border-bottom-color: var(--accent); color: var(--accent-ink); }
 
-/* Section rule */
+/* ---------- Section label ---------- */
 .nl-section-label {
-  font-family: 'Stetica', sans-serif;
-  font-size: 0.68rem;
-  letter-spacing: 0.18em;
+  font-size: 0.7rem;
+  font-weight: 600;
+  letter-spacing: 0.1em;
   text-transform: uppercase;
-  color: var(--ink-mute);
-  margin: 2.4rem 0 0.7rem 0;
-  border-top: 1px solid var(--hairline);
-  padding-top: 0.7rem;
+  color: var(--text-mute);
+  margin: 2.2rem 0 0.9rem 0;
 }
 
-/* Sidebar polish */
-[data-testid="stSidebar"] {
-  background: var(--paper-warm) !important;
-  border-right: 1px solid var(--hairline);
+/* ---------- Sample difficulty chip ---------- */
+.nl-sample-kicker {
+  display: inline-block;
+  font-size: 0.68rem;
+  font-weight: 600;
+  letter-spacing: 0.07em;
+  text-transform: uppercase;
+  color: var(--accent-ink);
+  background: var(--accent-soft);
+  border-radius: var(--radius-pill);
+  padding: 0.1rem 0.55rem;
+  margin: 0 0 0.45rem 0.1rem;
 }
+
+/* ---------- Sidebar ---------- */
+[data-testid="stSidebar"] { background: var(--panel) !important; border-right: 1px solid var(--border); }
+[data-testid="stSidebar"] .block-container { padding-top: 1.4rem; }
 [data-testid="stSidebar"] .nl-side-h {
-  font-family: 'NLEdSerif', Georgia, serif;
-  font-weight: 700;
-  font-size: 1.1rem;
-  letter-spacing: -0.005em;
-  margin: 0.4rem 0 0.6rem 0;
+  font-weight: 700; font-size: 1.05rem; letter-spacing: -0.02em; margin: 0.2rem 0 1rem 0;
 }
+[data-testid="stSidebar"] .nl-side-h .arrow { color: var(--accent); }
 [data-testid="stSidebar"] .nl-side-sub {
-  font-family: 'Stetica', sans-serif;
-  font-size: 0.7rem;
-  letter-spacing: 0.18em;
-  text-transform: uppercase;
-  color: var(--ink-mute);
-  margin: 1.2rem 0 0.4rem 0;
-}
-
-/* Language toggle */
-.nl-lang-row { display: flex; gap: 0; }
-.nl-lang-row button {
-  background: transparent !important;
-  color: var(--ink) !important;
-  border: 1px solid var(--rule) !important;
-  border-radius: 0 !important;
-  font-family: 'Stetica', sans-serif !important;
-  font-weight: 500 !important;
-  letter-spacing: 0.12em !important;
-  text-transform: uppercase;
-  padding: 0.35rem 0.9rem !important;
-  font-size: 0.74rem !important;
-  min-height: 0 !important;
+  font-size: 0.7rem; font-weight: 600; letter-spacing: 0.1em; text-transform: uppercase;
+  color: var(--text-mute); margin: 1.1rem 0 0.4rem 0;
 }
 
-/* Buttons (sample questions) */
+/* ---------- Buttons (sample cards + generic) ---------- */
 .stButton > button {
-  background: transparent !important;
-  color: var(--ink) !important;
-  border: 1px solid var(--rule) !important;
-  border-radius: 0 !important;
-  font-family: 'Stetica', sans-serif !important;
-  font-weight: 400 !important;
-  font-size: 0.92rem !important;
+  background: var(--surface) !important;
+  color: var(--text) !important;
+  border: 1px solid var(--border) !important;
+  border-radius: var(--radius-sm) !important;
+  box-shadow: var(--shadow-sm);
+  font-weight: 500 !important;
+  font-size: 0.9rem !important;
   text-align: left !important;
-  padding: 0.85rem 1rem !important;
-  line-height: 1.45 !important;
-  transition: background 0.12s;
+  padding: 0.6rem 0.8rem !important;
+  line-height: 1.4 !important;
   white-space: normal !important;
   height: auto !important;
+  min-height: 0 !important;
+  transition: border-color .14s, background .14s, box-shadow .14s, transform .14s;
 }
 .stButton > button:hover {
-  background: var(--ink) !important;
-  color: var(--paper) !important;
-}
-.stButton > button p {
-  color: inherit !important;
-}
-
-/* Chat input */
-.stChatInput { border-top: 1px solid var(--rule) !important; }
-.stChatInput textarea {
-  font-family: 'Stetica', sans-serif !important;
-  font-size: 1rem !important;
-  color: var(--ink) !important;
-  background: var(--paper) !important;
-}
-
-/* Code blocks — keep mono but on warm paper */
-pre, code {
-  background: var(--paper-warm) !important;
-  color: var(--ink) !important;
-  border: 1px solid var(--hairline) !important;
-  border-radius: 0 !important;
-  font-family: 'JetBrains Mono', 'IBM Plex Mono', ui-monospace, monospace !important;
-}
-
-/* Scalar metric block — flatten */
+  border-color: var(--accent) !important;
+  background: var(--accent-soft) !important;
+  color: var(--accent-ink) !important;
+  box-shadow: var(--shadow-md);
+  transform: translateY(-1px);
+}
+.stButton > button:active { transform: translateY(0) scale(0.992); box-shadow: var(--shadow-sm); }
+.stButton > button p { color: inherit !important; font-weight: 500 !important; }
+
+/* Primary button (active language) — accent fill, AA white text */
+.stButton > button[data-testid="stBaseButton-primary"] {
+  background: var(--accent) !important; color: #fff !important;
+  border-color: var(--accent) !important; box-shadow: none !important;
+}
+.stButton > button[data-testid="stBaseButton-primary"]:hover {
+  background: var(--accent-hover) !important; color: #fff !important;
+  border-color: var(--accent-hover) !important; transform: none !important;
+}
+
+/* Language pills (EN · RU) — compact, centred */
+.st-key-lang_en_btn .stButton > button,
+.st-key-lang_ru_btn .stButton > button {
+  text-align: center !important;
+  padding: 0.56rem 0.2rem !important;
+  font-size: 0.76rem !important; font-weight: 600 !important; letter-spacing: 0.08em !important;
+  box-shadow: none !important; transform: none !important;
+}
+.st-key-lang_en_btn .stButton > button:hover,
+.st-key-lang_ru_btn .stButton > button:hover { transform: none !important; }
+
+/* Clear-chat — quiet full-width action */
+.st-key-clear_chat_btn .stButton > button {
+  text-align: center !important; color: var(--text-soft) !important;
+  box-shadow: none !important; font-weight: 500 !important;
+}
+
+/* ---------- Selectbox ---------- */
+[data-baseweb="select"] > div {
+  background: var(--surface) !important;
+  border-radius: var(--radius-sm) !important;
+  border-color: var(--border) !important;
+  box-shadow: var(--shadow-sm);
+  min-height: 2.5rem;
+}
+[data-baseweb="select"] > div:hover { border-color: var(--border-strong) !important; }
+[data-baseweb="select"] > div:focus-within {
+  border-color: var(--accent) !important;
+  box-shadow: 0 0 0 3px var(--accent-ring) !important;
+}
+[data-baseweb="menu"] [role="option"]:hover { background: var(--accent-soft) !important; }
+
+/* Sliders / checkboxes accent */
+[data-testid="stSlider"] [role="slider"] { background: var(--accent) !important; }
+[data-baseweb="checkbox"] [data-checked="true"] { background: var(--accent) !important; border-color: var(--accent) !important; }
+
+/* ---------- Chat input ---------- */
+[data-testid="stChatInput"] {
+  border: 1px solid var(--border) !important;
+  border-radius: var(--radius) !important;
+  box-shadow: var(--shadow-sm);
+  background: var(--surface) !important;
+}
+[data-testid="stChatInput"]:focus-within {
+  border-color: var(--accent) !important;
+  box-shadow: 0 0 0 3px var(--accent-ring) !important;
+}
+[data-testid="stChatInput"] textarea { font-size: 1rem !important; color: var(--text) !important; background: transparent !important; }
+[data-testid="stChatInput"] textarea::placeholder { color: var(--text-mute) !important; }
+[data-testid="stChatInput"] button { background: var(--accent) !important; border-radius: var(--radius-sm) !important; color: #fff !important; }
+[data-testid="stChatInput"] button:hover { background: var(--accent-hover) !important; }
+
+/* ---------- Code ---------- */
+pre, code, .stMarkdown code, .stMarkdown pre,
+[data-testid="stCode"], [data-testid="stCode"] * { font-family: var(--mono) !important; }
+[data-testid="stCode"], pre {
+  background: var(--panel) !important;
+  border: 1px solid var(--border) !important;
+  border-radius: var(--radius-sm) !important;
+}
+
+/* ---------- Metric (scalar answer) ---------- */
 [data-testid="stMetric"] {
-  background: transparent !important;
-  border: none !important;
+  background: var(--surface) !important;
+  border: 1px solid var(--border) !important;
+  border-radius: var(--radius) !important;
+  box-shadow: var(--shadow-sm);
+  padding: 1rem 1.2rem !important;
 }
 [data-testid="stMetricLabel"] {
-  font-family: 'Stetica', sans-serif !important;
-  font-size: 0.68rem !important;
-  letter-spacing: 0.18em !important;
-  text-transform: uppercase !important;
-  color: var(--ink-mute) !important;
-}
-[data-testid="stMetricValue"] {
-  font-family: 'NLEdSerif', Georgia, serif !important;
-  font-weight: 700 !important;
-  font-size: 2.4rem !important;
-  color: var(--ink) !important;
-}
-
-/* Tables */
-[data-testid="stDataFrame"] { border: 1px solid var(--rule); }
-
-/* Expanders */
-.streamlit-expanderHeader {
-  font-family: 'Stetica', sans-serif !important;
-  font-size: 0.78rem !important;
-  letter-spacing: 0.1em;
-  text-transform: uppercase;
-  color: var(--ink) !important;
+  font-size: 0.7rem !important; font-weight: 600 !important; letter-spacing: 0.1em !important;
+  text-transform: uppercase !important; color: var(--text-mute) !important;
 }
+[data-testid="stMetricValue"] { font-weight: 800 !important; font-size: 2.2rem !important; color: var(--text) !important; }
 
-/* Sample card — wraps a button + difficulty kicker */
-.nl-sample {
-  display: block;
-}
-.nl-sample-kicker {
-  font-family: 'Stetica', sans-serif;
-  font-size: 0.62rem;
-  letter-spacing: 0.22em;
-  text-transform: uppercase;
-  color: var(--ink-mute);
-  margin: 0 0 0.4rem 0.05rem;
-}
+/* ---------- Tables ---------- */
+[data-testid="stDataFrame"] { border: 1px solid var(--border); border-radius: var(--radius-sm); overflow: hidden; }
 
-/* Chat message bubbles — strip default round chrome */
-[data-testid="stChatMessage"] {
-  background: transparent !important;
-  border: 0 !important;
-  padding: 0.4rem 0 1.4rem 0 !important;
+/* ---------- Expanders ---------- */
+[data-testid="stExpander"] {
+  border: 1px solid var(--border) !important;
+  border-radius: var(--radius) !important;
+  background: var(--surface) !important;
+  box-shadow: var(--shadow-sm);
 }
-[data-testid="stChatMessage"]:not(:first-child) {
-  border-top: 1px solid var(--hairline) !important;
-  padding-top: 1.4rem !important;
+[data-testid="stExpander"] summary, .streamlit-expanderHeader {
+  font-size: 0.82rem !important; font-weight: 600 !important; color: var(--text) !important;
 }
+[data-testid="stExpander"] summary:hover { color: var(--accent-ink) !important; }
 
-/* Remove the avatar/icon circle Streamlit injects — covers every variant */
+/* ---------- Chat messages ---------- */
+[data-testid="stChatMessage"] { background: transparent !important; border: 0 !important; padding: 0.4rem 0 1.4rem 0 !important; }
+[data-testid="stChatMessage"]:not(:first-child) { border-top: 1px solid var(--border) !important; padding-top: 1.4rem !important; }
 [data-testid="stChatMessage"] > div:first-child,
-[data-testid="chatAvatarIcon-user"],
-[data-testid="chatAvatarIcon-assistant"],
-[data-testid="stChatMessageAvatarUser"],
-[data-testid="stChatMessageAvatarAssistant"],
-[data-testid="stChatMessage"] [class*="Avatar"],
-[data-testid="stChatMessage"] svg {
-  display: none !important;
-}
-
-/* The chat message body lives in second child after the avatar; pull it left */
-[data-testid="stChatMessage"] > div:nth-child(2) {
-  margin-left: 0 !important;
-  padding-left: 0 !important;
-  width: 100% !important;
-}
+[data-testid="chatAvatarIcon-user"], [data-testid="chatAvatarIcon-assistant"],
+[data-testid="stChatMessageAvatarUser"], [data-testid="stChatMessageAvatarAssistant"],
+[data-testid="stChatMessage"] [class*="Avatar"] { display: none !important; }
+[data-testid="stChatMessage"] > div:nth-child(2) { margin-left: 0 !important; padding-left: 0 !important; width: 100% !important; }
+
+/* ---------- Scrollbar ---------- */
+::-webkit-scrollbar { width: 10px; height: 10px; }
+::-webkit-scrollbar-thumb { background: var(--border-strong); border-radius: var(--radius-pill); border: 2px solid var(--bg); }
+::-webkit-scrollbar-thumb:hover { background: var(--text-mute); }
 </style>
 """
 
 
-CHART_PALETTE = ["#111111", "#4A4A4A", "#7A7A75", "#A8A29E", "#1A1A1A"]
+CHART_PALETTE = ["#C2541B", "#1C1A17", "#9E3F12", "#6F6A61", "#D8862E"]
 
 
 def inject_chrome() -> None:
@@ -331,13 +405,13 @@ def inject_chrome() -> None:
 
 def style_fig(fig: Any) -> Any:
     fig.update_layout(
-        font_family="Stetica, system-ui, sans-serif",
-        font_color="#111111",
-        paper_bgcolor="#FAFAF7",
-        plot_bgcolor="#FAFAF7",
+        font_family="Manrope, system-ui, sans-serif",
+        font_color="#1C1A17",
+        paper_bgcolor="#FFFFFF",
+        plot_bgcolor="#FFFFFF",
         colorway=CHART_PALETTE,
         margin=dict(l=10, r=10, t=20, b=10),
     )
-    fig.update_xaxes(gridcolor="#DCD8CE", zerolinecolor="#1A1A1A", tickcolor="#1A1A1A")
-    fig.update_yaxes(gridcolor="#DCD8CE", zerolinecolor="#1A1A1A", tickcolor="#1A1A1A")
+    fig.update_xaxes(gridcolor="#EDE9E1", zerolinecolor="#D8D2C6", tickcolor="#D8D2C6")
+    fig.update_yaxes(gridcolor="#EDE9E1", zerolinecolor="#D8D2C6", tickcolor="#D8D2C6")
     return fig

audit_codex_30_05_26.md

@@ -0,0 +1,434 @@
+# NL_SQL — полный аудит проекта
+
+Дата аудита: 2026-05-30  
+Аудитор: Codex  
+Проект: `D:\NL_SQL`  
+Ветка: `main`  
+HEAD на старте: `8e6c61d598f1380833ae1b35825eef432b7a52f4`
+
+## 1. Baseline и границы аудита
+
+Я не читал `.env` и не выводил секреты. Проверка секретов выполнена по
+именам файлов, конфигам, `.env.example`, `.gitignore` и grep-паттернам с
+исключением реального `.env`, lock-файлов, локальных БД и Chroma-индексов.
+
+| Метрика | Значение |
+|---|---:|
+| Tracked files | 429 |
+| Python files в `src/app/scripts/tests` | 143 |
+| Bundle size | N/A: Python/FastAPI/Streamlit проект без frontend bundle |
+| i18n leaf keys | N/A: нет count-based i18n target в задаче |
+| Самые крупные tracked файлы | `financial.sqlite` 67.99 MB; Chroma `data_level0.bin` 36.65 MB; `debit_card_specializing.sqlite` 33.03 MB |
+| Git dirty до записи отчёта | modified `chroma_data/*`; untracked `27_05_26.md`, `eval/reports/2026-05-25/C_dense_cards-p3f-1168-1029-v1.json`, `eval/reports/2026-05-25/index.html` |
+
+Рабочее дерево уже было грязным до аудита. Эти файлы не изменялись.
+
+## 2. Выполненные проверки
+
+| Проверка | Результат |
+|---|---|
+| `uv --version` | `uv 0.8.23` |
+| `uv run python --version` | `Python 3.13.7` |
+| `uv run ruff check src tests scripts app` | passed |
+| `uv run ruff format --check src tests scripts app` | `143 files already formatted` |
+| `uv run mypy src` | passed, `59 source files` |
+| `uv run pytest --cov=src/nl_sql --cov-report=term-missing` | `370 passed`, coverage `91%`, 1 upstream LangGraph warning |
+| `uv run python scripts\p3f_acceptance.py --report eval\reports\2026-05-26\v31-v30-plus-p3f-q37-merged.json --require-pass` | 11/11 P3.F targets PASS |
+| `uv run python scripts\audit_rescore.py --report eval\reports\2026-05-26\v31-v30-plus-p3f-q37-merged.json` | `records: 200`, stored matches `188`, true matches `188`, mismatches `0` |
+
+Дополнительные smoke-проверки:
+
+- 61 unauthenticated request к `/databases` при пустом `NL_SQL_API_KEY` вернули последние статусы `[200, 200, 200]`, `429` не было.
+- `/eval/latest` локально вернул `overall_ea=0.605`, `n=200`, `report_path=eval\baselines\hybrid_n200_v0.json`.
+- В v31 JSON top-level `overall` равен `185/200 = 92.5%`, но фактический пересчёт `records[]` и `audit_rescore` дают `188/200 = 94.0%`.
+
+## 3. Executive Summary
+
+NL_SQL сейчас выглядит как сильный portfolio/research проект: современный
+Python-стек, строгие gates, хорошая модульность, read-only execution, rich eval
+surface, сохранённые артефакты и высокая тестовая дисциплина. Текущие локальные
+quality gates зелёные.
+
+Главный риск не в качестве кода, а в integrity/operational слое вокруг
+публичной метрики и API. README/UI заявляют v31 `94.0%`, canonical record-level
+данные это подтверждают, но top-level summary в v31 JSON устарел, а `/eval/latest`
+вообще отдаёт старый baseline `60.5%`. Это подрывает transparency story.
+
+Второй важный риск: public API фактически не rate-limit'ится без
+`NL_SQL_API_KEY`, а `.env`-only API key не включит auth, потому что код читает
+только `os.environ`. Для публичного HF/Streamlit demo это DoS/quota surface.
+
+Третий важный риск: после исправления qid 518 часть voting/eval scripts всё ещё
+использует старый паттерн `_execute_gold()` + `compare_results()` без
+`pred_failed/gold_failed` флагов. Основной v31 report сейчас verified, но будущие
+rescues через эти scripts могут снова породить false positive.
+
+## 4. Сильные стороны
+
+- **Gates зелёные:** ruff, format-check, mypy strict, pytest+coverage, P3.F
+  acceptance и audit-rescore прошли локально.
+- **Архитектура читаемая:** `agent`, `api`, `db`, `execution`, `eval`, `llm`,
+  `render`, `schema_index` разделены нормально; Streamlit уже декомпозирован.
+- **SQL safety не промптовая:** `sqlglot` AST guard + read-only SQLite/Postgres
+  path + timeout + row cap.
+- **Eval discipline выше среднего:** есть BIRD, Arcwise, audit-rescore,
+  acceptance harness, regression tests на найденные scoring баги.
+- **Provider abstraction практичный:** Mistral, Groq, GitHub Models, Ollama,
+  OpenRouter, GraceKelly/Perplexity, helallao bridge.
+- **Документация богатая:** `README.md`, `docs/SESSION_HANDOFF.md`,
+  `docs/02_architecture_v2.md`, `docs/03_eval_methodology.md` дают контекст
+  следующей сессии.
+
+## 5. Findings
+
+### P1. v31 metric metadata and `/eval/latest` disagree with the 94.0% claim
+
+Evidence:
+
+- `eval/reports/2026-05-26/v31-v30-plus-p3f-q37-merged.json` top-level
+  `overall` says `matched=185`, `ea=0.925`.
+- The same file's `records[]` contain 188 `match=true` rows.
+- `scripts/audit_rescore.py` on the v31 report independently confirms
+  `matches true: 188`, `mismatches: 0`.
+- `src/nl_sql/api/main.py:407` hardcodes `/eval/latest` to
+  `eval/baselines/hybrid_n200_v0.json`, which currently returns `0.605`.
+- `tests/scripts/test_refresh_baseline_summary.py` guards only v22-v29, not
+  v30/v31.
+
+Impact:
+
+The public story says 94.0%, the audited row-level data supports 94.0%, but
+machine-readable metadata says 92.5% or 60.5% depending on endpoint. This is a
+portfolio trust issue.
+
+Recommended fix:
+
+1. Run `scripts/refresh_baseline_summary.py` on v30/v31 reports.
+2. Extend the canonical summary-consistency test to v30/v31 and future reports.
+3. Replace hardcoded `/eval/latest` baseline path with a maintained manifest or
+   "latest final report" resolver.
+4. Make `configuration` / `sql_model` metadata include v30/v31 rescue labels
+   instead of stopping at q1275-era text.
+
+### P1. Public API rate-limit is disabled when auth is off
+
+Evidence:
+
+- `src/nl_sql/api/main.py:283` reads `NL_SQL_API_KEY` directly from
+  `os.environ`.
+- `src/nl_sql/api/main.py:289` returns `"anonymous"` before calling
+  `rate_limiter.check(...)` when no key is set.
+- Smoke test: 61 unauthenticated `/databases` requests returned 200; no 429.
+- `README.md:36` documents "X-API-Key auth + token-bucket rate limit
+  (60 req/min)", but that only applies when a key is configured.
+- The module docstring says env, `.env`, or settings, but `.env`-only
+  `NL_SQL_API_KEY` is not loaded into `os.environ` by `pydantic-settings`.
+
+Impact:
+
+Public demo without a process-level API key has no API-side rate limit. If
+`/ask` is exposed, this can burn LLM quota or degrade the app.
+
+Recommended fix:
+
+- Add `api_key: str = Field(default="", validation_alias="NL_SQL_API_KEY")` to
+  `Settings` and use it in `create_app()`.
+- Rate-limit unconditionally with key `x_api_key or request.client.host or
+  "anonymous"`.
+- Add a regression test for 61 unauthenticated requests with auth off.
+
+### P1. The qid 518 false-positive pattern remains in several voting scripts
+
+Evidence:
+
+`safe_compare_pred()` exists and documents that voting/rescoring scripts must
+pass `pred_failed` / `gold_failed`. Current fixed paths include
+`scripts/audit_rescore.py`, `scripts/rescore_arcwise.py`,
+`scripts/run_helallao_voting.py`, and `scripts/merge_voting_rescues.py`.
+
+Still risky scripts found by grep:
+
+- `scripts/run_groq_voting.py:250-258`
+- `scripts/run_openrouter_voting.py:232-237`
+- `scripts/run_critique_retry.py:183-188`
+- `scripts/run_selfcon_retry.py:228-233`
+- `scripts/run_sonnet_voting.py:142-147`
+- `scripts/run_wide_schema_retry.py:158-163`
+- `scripts/archive_sweep.py:99-115`
+- `scripts/ensemble_vote.py:265-283`
+- `scripts/run_planner_eval.py:124-130`
+
+Impact:
+
+Future eval/voting runs can again treat exec-failed pred/gold as empty rows and
+mark `compare_results([], [])` as match. `merge_voting_rescues.py` reverify
+mitigates some merges, but raw voting reports and any `--no-reverify` path can
+still mislead.
+
+Recommended fix:
+
+- Create one shared helper for "execute pred + execute gold + safe compare".
+- Migrate all scripts to it.
+- Add a repository-wide test or grep guard that forbids direct
+  `_execute_gold()` + `compare_results()` in scripts unless justified.
+
+### P2. Runtime safety docs promise payload cap / hard LIMIT, code only has fetch cap
+
+Evidence:
+
+- `docs/02_architecture_v2.md:170` promises hard `LIMIT 10000` and result
+  payload cap 5MB.
+- `src/nl_sql/db/connection.py:93-103` executes SQL as-is, then
+  `fetchmany(row_cap + 1)`.
+- `src/nl_sql/execution/guards.py:8` says runner enforces result-payload cap,
+  but no payload-byte cap exists.
+- `AskResponse` does not expose `QueryResult.truncated`, so API clients cannot
+  tell a result was clipped.
+
+Impact:
+
+The implementation still has a useful row cap and timeout, but the documented
+payload safety is not implemented. Large text/blob cells can exceed intended
+payload size, and clients may trust partial results as complete.
+
+Recommended fix:
+
+- Add byte-size accounting while materializing rows.
+- Return `truncated: bool` and maybe `truncation_reason`.
+- Either implement SQL-level LIMIT injection for eligible SELECTs or soften docs
+  to "fetch cap".
+
+### P2. Provider settings and factory are inconsistent for `perplexity`
+
+Evidence:
+
+- `src/nl_sql/llm/providers/factory.py:19` and `:49-53` support
+  `perplexity`.
+- `scripts/eval_baseline.py:202` allows `perplexity` in CLI choices.
+- `src/nl_sql/config/settings.py:7` defines `ProviderName` without
+  `perplexity`.
+- Smoke: `NL_SQL_DEFAULT_PROVIDER=perplexity` causes Pydantic validation error.
+
+Impact:
+
+Documented/implemented provider cannot be selected via settings as default
+provider.
+
+Recommended fix:
+
+Add `perplexity` to `ProviderName` and cover it in `test_provider_factory.py`.
+
+### P2. CI tests Python 3.13, deployment runtime asks for Python 3.12
+
+Evidence:
+
+- `.github/workflows/ci.yml:25` installs Python 3.13.
+- `pyproject.toml:67` sets ruff `target-version = "py313"`.
+- `pyproject.toml:92` sets mypy `python_version = "3.13"`.
+- `runtime.txt:1` is `python-3.12`.
+- `pyproject.toml:6` allows `>=3.12,<3.14`.
+
+Impact:
+
+The deployed Streamlit/HF runtime can run on Python 3.12 while CI, ruff and
+mypy optimize for 3.13. A future 3.13-only syntax or dependency behavior could
+pass CI and fail deployment.
+
+Recommended fix:
+
+Either move `runtime.txt` to Python 3.13, or add CI matrix for 3.12 and set
+ruff/mypy target to the lowest supported runtime.
+
+### P2. Streamlit renders `Sentence.text` through unsafe HTML without escaping
+
+Evidence:
+
+- `app/components/output.py:62-68` interpolates `output.text` into
+  `st.markdown(..., unsafe_allow_html=True)`.
+- `src/nl_sql/agent/nodes/format.py:22-25` creates `Sentence` from
+  `error_message` when no result is available.
+- Error messages can include LLM-generated SQL / DB parser text.
+
+Impact:
+
+A malformed SQL/error path can inject HTML into the UI. Streamlit's markdown
+layer is not a substitute for escaping when `unsafe_allow_html=True` is used.
+
+Recommended fix:
+
+Escape `output.text` with `html.escape()` before interpolation, or render
+Sentence text with safe Streamlit primitives and move styling to CSS.
+
+### P2. Local secret/cookie paths are hardcoded in operational scripts
+
+Evidence:
+
+- `src/nl_sql/llm/providers/helallao_perplexity.py:30` defaults to
+  `D:/NL_SQL/.tmp/pplx_cookies.json`.
+- `scripts/run_helallao_voting.py:56-59` exposes the same default.
+- `scripts/run_openrouter_voting.py:48-54` reads
+  `D:/TXT/Free API Keys.txt` if `OPENROUTER_API_KEY` is absent.
+
+Impact:
+
+This is acceptable as local research tooling, but not portable and not
+production-safe. Plaintext browser cookies are especially sensitive even if
+`.tmp/` is gitignored.
+
+Recommended fix:
+
+Route paths through `Settings` or CLI-only required flags, avoid default secret
+files, and use OS keyring/DPAPI for browser-cookie material if this workflow
+must remain.
+
+### P2. API can leak internal exception details
+
+Evidence:
+
+- `src/nl_sql/api/main.py:397-401` returns
+  `pipeline crashed: {type(exc).__name__}: {exc}` to clients.
+- `src/nl_sql/agent/nodes/explain_trace.py:47-53` exposes provider error text
+  in caption fallback.
+
+Impact:
+
+Provider errors, local paths, DB driver messages, or upstream response snippets
+can leak to public clients.
+
+Recommended fix:
+
+Return a generic client error with `trace_id`; log full details server-side.
+
+### P3. Dev docker-compose uses fixed default credentials
+
+Evidence:
+
+- `docker-compose.yml:9` sets `POSTGRES_PASSWORD=postgres`.
+- `docker-compose.yml:30` falls back to `dev-secret-change-me`.
+
+Impact:
+
+Fine for local profiles, but dangerous if someone treats compose as production.
+
+Recommended fix:
+
+Add an explicit "dev only" warning in `docker-compose.yml` comments and require
+env-provided secrets for any non-local profile.
+
+### P3. Benchmark-specific schema hints are now a large production prompt surface
+
+Evidence:
+
+- `src/nl_sql/agent/nodes/_hints.py` contains many exact BIRD/qid-specific
+  phrase gates and "write exactly" hints.
+
+Impact:
+
+This is honest and effective for benchmark scoring, but it weakens the claim
+that the interactive product is a general NL→SQL assistant unless framed as
+"benchmark rescue layer". It can also overfit phrasing if shipped in production
+mode.
+
+Recommended fix:
+
+Separate benchmark/eval prompt hints from product prompt hints via config, and
+document the distinction in `/eval/latest`/README.
+
+### P3. Prebuilt Chroma and DB artefacts are tracked and frequently dirty
+
+Evidence:
+
+- `chroma_data/` and selected SQLite files are tracked by design.
+- Current pre-audit dirty state includes three modified `chroma_data/*` files.
+
+Impact:
+
+This improves deploy cold-start but creates noisy dirty trees and parallel work
+conflicts. Binary Chroma diffs are not reviewable.
+
+Recommended fix:
+
+Consider Git LFS or a release artifact for Chroma/data, or make runtime write to
+a separate ignored copy of the index.
+
+### P3. Coverage is high overall, but disabled/bridge paths remain thin
+
+Coverage gaps from the local run:
+
+- `src/nl_sql/agent/nodes/plan_query.py`: 39%
+- `src/nl_sql/llm/providers/helallao_perplexity.py`: 26%
+- `src/nl_sql/execution/errors.py`: 76%
+
+Impact:
+
+This is acceptable while planner/helallao are eval/optional paths. If planner
+or helallao becomes part of default product flow, add tests first.
+
+## 6. Security posture
+
+Good:
+
+- `.env` is ignored.
+- `.env.example` contains no real keys.
+- SQL write attempts are blocked at AST and DB layers.
+- SQLite uses read-only URI + `PRAGMA query_only=ON`.
+- Postgres path sets `default_transaction_read_only=on`.
+- Input model caps question length at 2000 chars.
+
+Needs work before broader public exposure:
+
+- Unauthenticated API should still be rate-limited.
+- `.env` API key path should actually work through `Settings`.
+- Public 500s should not include raw exception text.
+- Result payload cap should be real, not only documented.
+- Plaintext Perplexity cookies should remain local-only tooling.
+
+## 7. CI / QA posture
+
+Current QA is strong:
+
+- Fast unit suite: 370 tests.
+- Strict mypy on `src`.
+- Ruff check and format-check include `src tests scripts app`.
+- P3.F acceptance and audit-rescore are useful domain-specific gates.
+
+Recommended additions:
+
+- CI/test guard that all canonical final reports have `overall` derived from
+  `records[]`.
+- CI/test guard for `/eval/latest` matching the latest final report.
+- Regression test for anonymous rate limit.
+- Regression test for `.env`-configured `NL_SQL_API_KEY`.
+- A grep-style guard against unsafe direct `compare_results()` in scripts.
+- Python 3.12 runtime job or runtime bump to 3.13.
+
+## 8. Product/readiness assessment
+
+| Area | Rating | Notes |
+|---|---:|---|
+| Core engineering | 8.5/10 | Modular, typed, tested, good safety boundaries |
+| Eval integrity | 7/10 | Row-level v31 is verified, but metadata/API drift is serious |
+| Security for portfolio demo | 7/10 | SQL safety good; public API/rate-limit needs fix |
+| Production API readiness | 5.5/10 | Functional, but auth/rate-limit/error/payload gaps remain |
+| UI polish | 7/10 | Refactor improved maintainability; one unsafe render path remains |
+| Deployment readiness | 6.5/10 | Works as demo, but Python runtime skew and tracked Chroma dirtiness need cleanup |
+
+## 9. Priority action list
+
+1. Fix v31/v30 report summaries and make `/eval/latest` point to the current
+   verified final report.
+2. Enable anonymous/IP rate-limit and move `NL_SQL_API_KEY` into `Settings`.
+3. Migrate all voting/rescore scripts to a shared safe comparison helper.
+4. Add payload-byte cap and expose `truncated` in API/UI.
+5. Align Python runtime between CI and deployment.
+6. Escape `Sentence.text` in Streamlit output rendering.
+7. Add `perplexity` to `ProviderName` or remove it from user-facing provider choices.
+8. Move local cookie/key paths behind explicit config and mark them as local-only.
+
+## 10. Bottom line
+
+The project is technically strong and the current v31 row-level claim
+`188/200 = 94.0%` is locally re-verified. The immediate problem is not model
+quality; it is consistency of the artefacts around the claim. Fixing the
+summary/API drift and anonymous rate-limit gap would materially improve the
+trustworthiness of the public demo.

chroma_data/chroma.sqlite3

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:90181e0a2514fbaf80a6de4c6307593dba4e93e9e6da6bd70600553a2651667b
+oid sha256:16c3ccffe56ea1ae9932da484fdfa7dfa34e7fc6b148684bdafb6a41f8bdfdcc
 size 18161664

chroma_data/fc9668d3-4384-40d9-aa8d-0010807a5a68/data_level0.bin

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:de3c405eda8dc30523c29aa0475a570ba0de2526b2ca29b21f1bf0f3ea94d6e0
+oid sha256:ac78878e535b9fd06aa012f6dab954f1633a82bf67265f0aa166ec467a024639
 size 423600

chroma_data/fc9668d3-4384-40d9-aa8d-0010807a5a68/length.bin

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:39f574a82964186c006c0c4d50f49095c2abb6b4614ca4e36f953667e96281da
+oid sha256:d9142387334b53a34226a53a60878980670c9a2a28a56cd9f8ddf2e7d44f3975
 size 400

docs/NEXT_SESSION.md

@@ -3,6 +3,38 @@
 > Один лист, без воды. Берёшь, делаешь, обновляешь `SESSION_HANDOFF.md`,
 > переписываешь этот файл под следующий sprint.
 
+## 2026-06-17 — UI редизайн (anti-slop, ~9.5/10, push на origin/main)
+
+Юзер: «современная страница» → затем «до 9.8/10». Полный редизайн Streamlit chrome
+из editorial-monochrome в **editorial-warm light**. Функциональность не тронута.
+
+- **Палитра:** Stone + **Terracotta `#C2541B`** (увод от AI-indigo / «Lila rule»). Один
+  акцент, color-lock. `.streamlit/config.toml` `base="light"` + primaryColor.
+- **Шрифт:** self-hosted **Manrope** (UI + цифры, кириллица, `tabular-nums`) + **JetBrains
+  Mono** (SQL). Старые `.otf` (Stetica/serif) удалены; 4 variable woff2 (latin+cyrillic)
+  в `app/static/fonts/` (`manrope-*`, `jbmono-*`). NB: глобальный шрифтовой селектор
+  обязан покрывать `[data-testid="stMarkdownContainer"] *`, иначе Streamlit держит Source Sans.
+- **Layout:** контролы (база / режим / EN-RU) → **sticky top bar** `st.container(key="nl_topbar")`;
+  сайдбар = только schema / advanced / clear, без скролла; EN/RU убран из сайдбара (пилюли);
+  кнопки-сэмплы компактные; длинная методология → свёрнутый `expander` (welcome влезает в экран
+  и не триггерит auto-scroll `stAppScrollToBottomContainer`).
+- **Полировка:** shape-lock (12/8/pill), `:focus-visible` ring, `:active`, тёплые тени, WCAG AA
+  (white-on-terracotta 4.59:1, ссылки 6.66:1 — проверено скриптом), `text-wrap` balance/pretty.
+- **Файлы:** `app/theme.py` (ядро CSS), `app/streamlit_app.py`, `app/components/{welcome,output}.py`,
+  `app/i18n.py`, `.streamlit/config.toml`, `README.md`.
+- **Verified:** локальный Streamlit (порт 8501) + bundled Playwright (`chromium-1223`, MCP-браузер
+  занят) — Manrope применился, реальный запрос рендерится (COUNT 4, SQL-подсветка), адаптив 700px
+  держится, консоль чистая, ruff чистый. `/design-review`: P0/P1/P2 = 0, APPROVED. Самооценка ~9.5.
+
+**Остаток / gated:**
+- **HF Space live НЕ обновлён.** Деплой отдельный через `.deploy_hf.py` (нужен HF token —
+  в `.env` его НЕТ). GitHub запушен; HF redeploy — ручной шаг владельца.
+- true-mobile <480px: 5-колоночный top bar поджимается (лимит Streamlit-колонок) — для
+  desktop-first портфолио ОК.
+- Скриншоты README / `docs/ui-live-*.png` сняты на старом дизайне → устарели до HF-redeploy.
+
+---
+
 ## 2026-05-26 EOD-7 — autonomous housekeeping sprint (HEAD `4207df0`, pushed)
 
 **Cleared today (one-shot autonomous run):**
@@ -16,9 +48,9 @@
 
 | # | Severity | Scope | Estimate |
 |---|---|---|---|
-| Codex #7 | P2 latent | `scripts/rescore_arcwise.py:82` stale `rec["match"]` — verified 0/200 disagreements on v29, transitions output unchanged if fixed | 30min, deferred |
-| Codex #8 | P2 latent | `execution_accuracy.py` `_hashable` float bucketing — verified 0 set-mismatch in v22-v30 baselines | 1h, deferred |
-| Codex #10 | P2 latent | `cache.py:88` cache miss/fill race — fires только при parallel workers (not currently used) | 1h, deferred |
+| ~~Codex #7~~ | **Done 2026-05-26 EOD-7** (`a7c617f`) | `scripts/rescore_arcwise.py` transitions теперь используют fresh `out_entry["original_match"]` вместо stored `rec["match"]`. Canonical v29 transitions (gained=7 / lost=91) не изменились — 0/200 disagreements verified. Future-proofing only. | 30min |
+| Codex #8 | P2 latent | `execution_accuracy.py` `_hashable` float bucketing — verified 0 set-mismatch in v22-v31 baselines. **Will NOT fix:** замена на O(n²) pair-wise tolerance match замедлит comparisons на больших result sets без observable benefit. Document как "won't fix" если не возникнет реальный repro. | won't fix |
+| Codex #10 | P2 latent | `cache.py:88` cache miss/fill race — fires только при parallel workers (not currently used). **Will NOT fix:** добавляет complexity (per-key diskcache locks) для несуществующего scenario. Если parallel workers потребуются — пересмотреть. | won't fix |
 
 **Past 94.0% (gated к юзеру):** requires paid OR top-up / fine-tune / metric pivot. Residue 12 qids — large majority BIRD-annotation-quirks (unanimous fail через 3-model reasoning sweeps EOD-2 + EOD-4). Saturation подтверждена.
 
@@ -218,7 +250,7 @@ fetch). Local heterogeneous CSC lever остаётся parked.
 | ~~Kimi P1.3~~ | **Done 2026-05-26 EOD-7** (`a7c1d81`) | `app/streamlit_app.py` 1184 → 200 lines split: `i18n.py`/`theme.py`/`samples.py`/`bootstrap.py` + `components/{output,show_working,schema_explorer,welcome}.py`. `pyproject.toml` ruff `src` расширен `["src","tests","app"]`. Local Streamlit + Playwright E2E подтвердил EN 94.0% / RU 94,0% / schema explorer render OK. Zero behavior change, 357 pytest pass. | 1.5h |
 | ~~Kimi P1.4~~ | **Done 2026-05-26** | `src/nl_sql/agent/nodes/_support.py` 483 lines → `_support.py` (public API, 184 lines) + `_text_utils.py` (JSON parsing, 53 lines) + `_hints.py` (schema appendices, 302 lines). Zero behavior change, 355 pytest pass, ruff + mypy strict clean. | 1h |
 | ~~Kimi P1.6~~ | **Done 2026-05-26 EOD-7** (`4207df0`) | API coverage **58% → 89%**. Extracted `Singletons` NamedTuple + `get_singletons()` FastAPI Depends-factory. `/readyz`, `/databases`, `/ask` теперь принимают `Singletons = Depends(get_singletons)`; production callers idiomatic через `@lru_cache(maxsize=1)` на `_make_singletons` (zero behavior change). New `tests/api/test_api_routes_mocked.py` (13 tests) покрывает /readyz healthy/empty/raises пути, /databases auth + schema-exception, /ask unknown-db / canned-result / error-kind / confidence-buckets + rate-limit 60→61st 429. | 1.5h |
-| Codex #7 | P2 latent | `scripts/rescore_arcwise.py:82` transition buckets используют stale `rec["match"]` вместо recomputed `out_entry["original_match"]` (line 141 overwrite). **Reachability verified 2026-05-26: 0/200 stale-vs-fresh disagreements в `eval/reports/2026-05-24/v29-arcwise-rescored.json`** — bug latent, transitions counts (7 gained / 91 lost) honest. Fix = 1-line swap, no observable change в output. | 30min, deferred |
+| ~~Codex #7~~ | **Done 2026-05-26 EOD-7** (`a7c617f`) | `scripts/rescore_arcwise.py` transitions teперь через fresh `out_entry["original_match"]` вместо stored `rec["match"]`. Canonical v29 transitions (gained=7 / lost=91) не изменились — 0/200 disagreements. Future-proofing. | 30min |
 | Codex #8 | P2 latent | `execution_accuracy.py:209-221` `_hashable` bucketing через `round(v / 1e-6)` может развести два tolerance-equivalent rows (diff ~9e-7, banker's rounding edge) в разные buckets → set-mode false negative. **Reachability verified 2026-05-26: 0 set-mismatch records в v22-v30 baselines (200 records each); 8 set-mismatch в demo runs 2026-05-11, все honest column-count diff не float-bucket.** Fix = replace `_hashable` с pair-wise tolerance match (O(n²)). | 1h, deferred |
 | ~~Codex #9~~ | **false positive 2026-05-26** | `cache.py:77` cache key omits `req.json_mode`. **Не достижимо в текущем коде:** `src/nl_sql/llm/providers/groq.py:44` force-set'ит `json_mode=True` через `req.model_copy` на каждом Groq call; Mistral codestral игнорирует поле (`base.py:21` docstring). Per (provider, model) пара `json_mode` имеет константное значение → collision impossible. Не трогать (попытка fix landed 2026-05-26, reverted после Codex+Kimi independent review). | closed |
 | Codex #10 | P2 latent | `cache.py:88` cache miss/fill race без lock — parallel eval workers могут race, duplicate paid calls, last-writer-wins. **Reachability: текущий eval pipeline serial per qid (см. `runner.py::_run_one`). Latent до момента запуска parallel workers.** Fix = per-key diskcache lock или atomic memoization (`Cache.add` semantic). | 1h, deferred |

docs/SESSION_HANDOFF.md

@@ -1,5 +1,13 @@
 # NL_SQL — Session Handoff (2026-05-26 EOD-7: Kimi P1.3 + P1.6 closed, 8 housekeeping commits pushed, HF Space live на v31 94.0%)
 
+> **Tl;dr 2026-06-17 — UI редизайн (anti-slop, ~9.5/10, push на `origin/main`):** Streamlit
+> chrome переписан editorial-monochrome → **editorial-warm light** (Stone + Terracotta `#C2541B`,
+> увод от AI-indigo; self-hosted Manrope + JetBrains Mono с кириллицей; sticky top bar с
+> база/режим/EN-RU; компактный сайдбар без скролла; методология в expander; WCAG AA проверен;
+> `/design-review` APPROVED). Функциональность/eval не тронуты, 94.0% как было. Детали и остаток —
+> `docs/NEXT_SESSION.md` (секция 2026-06-17). **Caveat: HF Space live НЕ обновлён** — отдельный
+> `.deploy_hf.py` (HF token не в `.env`), GitHub запушен, HF redeploy — ручной шаг владельца.
+>
 > **Tl;dr 2026-05-26 EOD-7 — autonomous housekeeping sprint (HEAD `4207df0`, pushed):**
 >
 > 1. **Push backlog cleared:** 8 локальных commits (от `03ad6ae` до `a47a7fe`) запушены на `origin/main`. Origin теперь синхронен с локальным состоянием поверх v31 94.0%.

docs/data_flow.html

@@ -0,0 +1,688 @@
+<!DOCTYPE html>
+<html lang="ru">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>NL→SQL Assistant — схема движения данных</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Source+Serif+4:opsz,wght@8..60,500;8..60,600&family=IBM+Plex+Sans:wght@300;400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap&subset=cyrillic" rel="stylesheet">
+<style>
+:root{
+  --bg:#FAFAF8;
+  --text:#1C1C1A;
+  --accent:#9C5B38;
+  --accent-dark:#7C4426;
+  --muted:rgba(28,28,26,0.60);
+  --faint:rgba(28,28,26,0.38);
+  --line:rgba(28,28,26,0.40);
+  --divider:rgba(28,28,26,0.08);
+  --card:#FFFFFF;
+}
+*{box-sizing:border-box}
+body{
+  margin:0;background:var(--bg);color:var(--text);
+  font-family:'IBM Plex Sans',sans-serif;font-size:16px;line-height:1.6;
+  font-variant-numeric:tabular-nums lining-nums;
+  font-feature-settings:"tnum" 1,"lnum" 1;
+  text-wrap:pretty;
+}
+.mono{font-family:'IBM Plex Mono',monospace}
+
+/* ---------- header ---------- */
+header{padding:48px 48px 24px;max-width:1880px;margin:0 auto}
+h1{
+  font-family:'Source Serif 4',Georgia,serif;font-size:40px;font-weight:600;
+  line-height:1.1;margin:0 0 8px;letter-spacing:-0.01em;
+}
+.subtitle{font-size:15px;color:var(--muted);margin:0;max-width:1020px}
+.head-row{display:flex;justify-content:space-between;align-items:flex-end;gap:48px;margin-top:32px;flex-wrap:wrap}
+.kpis{display:flex;gap:48px;flex-wrap:wrap}
+.kpi .v{font-size:32px;font-weight:300;line-height:1.1;letter-spacing:-0.01em}
+.kpi .v sup{font-size:14px;font-weight:400;color:var(--muted)}
+.kpi .l{font-size:11px;text-transform:uppercase;letter-spacing:0.08em;color:var(--muted);margin-top:6px}
+.legend{display:grid;grid-template-columns:auto auto;gap:6px 24px;font-size:12px;color:var(--muted);padding-bottom:4px}
+.legend .li{display:flex;align-items:center;gap:10px;white-space:nowrap}
+.legend svg{flex:0 0 auto}
+.legend .chip{width:18px;height:18px;border-radius:50%;background:var(--accent);color:#FDFBF9;
+  font-size:10px;font-weight:600;display:inline-flex;align-items:center;justify-content:center;flex:0 0 auto}
+
+/* ---------- canvas scaling ---------- */
+#viewport{width:100%;overflow:hidden;padding:0 0 48px}
+#scaler{transform-origin:top left;margin:0 auto}
+#canvas{position:relative;width:1880px;height:2236px;font-size:13px}
+
+/* ---------- zones ---------- */
+.zone{position:absolute;border-radius:10px}
+.zone-tint{background:rgba(28,28,26,0.024)}
+.zone-hot{background:rgba(156,91,56,0.045)}
+.zone-h{position:absolute;font-size:12px;font-weight:600;text-transform:uppercase;letter-spacing:0.1em;color:var(--text)}
+.zone-h .zn{color:var(--accent);margin-right:8px}
+.zone-h small{display:block;font-weight:400;text-transform:none;letter-spacing:0;font-size:12px;color:var(--muted);margin-top:2px}
+
+/* ---------- nodes ---------- */
+.node{
+  position:absolute;background:var(--card);
+  border:1px solid rgba(28,28,26,0.12);border-radius:8px;
+  padding:12px 14px;line-height:1.45;
+  box-shadow:0 1px 3px rgba(30,25,20,0.05);
+  transition:box-shadow 160ms ease;
+}
+.node:hover{box-shadow:0 4px 10px -2px rgba(30,25,20,0.13),0 2px 4px -2px rgba(30,25,20,0.08)}
+.node.hot{border-top:3px solid var(--accent);padding-top:10px}
+.node.dashed{border-style:dashed;background:rgba(255,255,255,0.7)}
+.node h3{font-size:14px;font-weight:600;margin:0 0 1px;line-height:1.25;font-family:'IBM Plex Sans',sans-serif}
+.node .path{font-family:'IBM Plex Mono',monospace;font-size:11px;color:var(--muted);margin:0 0 6px}
+.node p{margin:0;font-size:13px;color:rgba(28,28,26,0.80)}
+.node p b{font-weight:600;color:var(--text)}
+.node ul{margin:2px 0 0;padding:0;list-style:none}
+.node li{font-size:13px;color:rgba(28,28,26,0.80);padding-left:12px;position:relative}
+.node li::before{content:"";position:absolute;left:0;top:0.62em;width:5px;height:1.5px;background:var(--accent)}
+.badges{margin-top:8px;display:flex;flex-wrap:wrap;gap:4px}
+.bdg{
+  font-family:'IBM Plex Mono',monospace;font-size:11px;line-height:1;
+  background:rgba(28,28,26,0.055);border-radius:4px;padding:4px 7px;color:rgba(28,28,26,0.74);
+  white-space:nowrap;
+}
+.bdg.a{background:rgba(156,91,56,0.12);color:var(--accent-dark)}
+.tag{
+  display:inline-block;font-size:9.5px;font-weight:600;letter-spacing:0.08em;text-transform:uppercase;
+  border-radius:4px;padding:3px 6px;line-height:1;vertical-align:2px;margin-left:6px;
+}
+.tag.opt{background:rgba(28,28,26,0.07);color:var(--muted)}
+.tag.pri{background:var(--accent);color:#FDFBF9}
+.tag.nollm{background:rgba(28,28,26,0.85);color:#FAFAF8}
+
+/* step chips on the hot path */
+.step{
+  position:absolute;top:-11px;left:-11px;width:22px;height:22px;border-radius:50%;
+  background:var(--accent);color:#FDFBF9;font-size:11.5px;font-weight:600;
+  display:flex;align-items:center;justify-content:center;
+  box-shadow:0 1px 3px rgba(30,25,20,0.28);
+}
+.step.alt{background:var(--card);color:var(--accent-dark);border:1.5px dashed var(--accent);box-shadow:none}
+
+/* provider group */
+.group{
+  position:absolute;border:1px dashed rgba(28,28,26,0.22);border-radius:10px;
+}
+.group .gt{
+  position:absolute;top:14px;left:16px;font-size:11px;font-weight:600;
+  text-transform:uppercase;letter-spacing:0.09em;color:var(--muted);
+}
+.pcard{padding:10px 12px}
+.pcard h3{font-size:13px}
+.pcard p{font-size:12px;line-height:1.45}
+.note{
+  position:absolute;font-size:12px;color:var(--muted);line-height:1.5;
+  padding:10px 12px;border:1px dashed rgba(156,91,56,0.4);border-radius:8px;
+  background:rgba(156,91,56,0.04);
+}
+
+/* CI ribbon */
+.ribbon{
+  position:absolute;background:var(--card);border:1px solid rgba(28,28,26,0.12);
+  border-radius:8px;display:flex;align-items:center;gap:8px;padding:14px 20px;flex-wrap:wrap;
+}
+.ribbon .rt{font-size:12px;font-weight:600;text-transform:uppercase;letter-spacing:0.1em;margin-right:12px}
+.ribbon .bdg{font-size:11px;padding:5px 9px}
+
+/* ---------- edges ---------- */
+#wires{position:absolute;inset:0;pointer-events:none}
+.edge path.l{fill:none}
+.edge .hot{stroke:var(--accent);stroke-width:2.2}
+.edge .rep{stroke:var(--accent);stroke-width:1.7;stroke-dasharray:7 5}
+.edge .bus{stroke:var(--accent);stroke-width:1.7;opacity:0.85}
+.edge .idx{stroke:var(--line);stroke-width:1.6;stroke-dasharray:8 6}
+.edge .opt{stroke:var(--line);stroke-width:1.5;stroke-dasharray:3 5}
+.edge .eval{stroke:rgba(28,28,26,0.5);stroke-width:1.6;stroke-dasharray:2 6;stroke-linecap:round}
+.edge text{font-family:'IBM Plex Sans',sans-serif;font-size:12px}
+.edge .lbg{fill:#FAFAF8;opacity:0.94}
+.edge .lt-hot{fill:var(--accent-dark)}
+.edge .lt-mut{fill:rgba(28,28,26,0.70)}
+#canvas.focus .edge{opacity:0.16;transition:opacity 120ms}
+#canvas.focus .edge.on{opacity:1}
+#canvas.focus .node{opacity:0.45;transition:opacity 120ms}
+#canvas.focus .node.on{opacity:1}
+#canvas.focus .group,#canvas.focus .zone-h{opacity:0.55}
+
+footer{max-width:1880px;margin:0 auto;padding:0 48px 56px;font-size:12px;color:var(--muted)}
+footer .mono{font-size:11px}
+
+/* mobile stub */
+#mobile-stub{display:none;position:fixed;inset:0;z-index:9999;background:var(--bg);color:var(--text);
+  align-items:center;justify-content:center;text-align:center;padding:40px}
+
+/* zoom bar */
+#zoombar{
+  position:fixed;right:20px;bottom:20px;z-index:500;
+  display:flex;align-items:center;gap:4px;
+  background:var(--card);border:1px solid rgba(28,28,26,0.14);border-radius:8px;
+  padding:6px 8px;box-shadow:0 2px 6px -1px rgba(30,25,20,0.12),0 1px 3px rgba(30,25,20,0.07);
+}
+#zoombar button{
+  width:30px;height:28px;border:1px solid rgba(28,28,26,0.14);border-radius:6px;
+  background:var(--bg);color:var(--text);font:500 14px/1 'IBM Plex Mono',monospace;
+  cursor:pointer;padding:0;
+}
+#zoombar button:hover{background:rgba(156,91,56,0.08);border-color:rgba(156,91,56,0.4)}
+#zoombar button:focus-visible{outline:2px solid var(--accent);outline-offset:1px}
+#zoombar button.fit{width:auto;padding:0 10px;font-size:11px}
+#zoombar #zval{font:400 11px 'IBM Plex Mono',monospace;color:var(--muted);min-width:38px;text-align:right}
+
+@media print{
+  #zoombar,#mobile-stub{display:none!important}
+  .node,.ribbon,#zoombar{box-shadow:none!important}
+  body{-webkit-print-color-adjust:exact;print-color-adjust:exact}
+}
+</style>
+</head>
+<body>
+
+<div id="mobile-stub"><p style="font-size:18px;line-height:1.6">Откройте страницу на десктопе<br>для корректного отображения схемы.</p></div>
+
+<div id="zoombar">
+  <button data-z="out" title="Уменьшить">−</button>
+  <button data-z="fit" class="fit" title="Вписать в окно">fit</button>
+  <button data-z="in" title="Увеличить">+</button>
+  <span id="zval">100%</span>
+</div>
+
+<header>
+  <h1>NL→SQL Assistant · схема движения данных</h1>
+  <p class="subtitle">Полный data flow портфолио-проекта: offline-индексация схем (01) → online query pipeline на LangGraph (02) → слой LLM-провайдеров с кэшем (03) → eval-контур с residue-циклом (04). Подписи на стрелках — что именно течёт между узлами; цифры в кружках — порядок шагов happy path.</p>
+  <div class="head-row">
+    <div class="kpis">
+      <div class="kpi"><div class="v">94.0<sup>%</sup></div><div class="l">EA · BIRD Mini-Dev n=200 · v31</div></div>
+      <div class="kpi"><div class="v">+1.04<sup>pp</sup></div><div class="l">над human-expert 92.96%</div></div>
+      <div class="kpi"><div class="v">$0</div><div class="l">external cost · free tiers + кэш</div></div>
+      <div class="kpi"><div class="v">370</div><div class="l">tests · coverage 91% · mypy strict</div></div>
+      <div class="kpi"><div class="v">7+2</div><div class="l">узлов LangGraph · база + opt-in</div></div>
+    </div>
+    <div class="legend">
+      <div class="li"><svg width="36" height="8"><line x1="0" y1="4" x2="36" y2="4" stroke="#9C5B38" stroke-width="2.2"/></svg>горячий путь запроса</div>
+      <div class="li"><svg width="36" height="8"><line x1="0" y1="4" x2="36" y2="4" stroke="rgba(28,28,26,.4)" stroke-width="1.6" stroke-dasharray="8 6"/></svg>offline-индексация</div>
+      <div class="li"><svg width="36" height="8"><line x1="0" y1="4" x2="36" y2="4" stroke="#9C5B38" stroke-width="1.7" stroke-dasharray="7 5"/></svg>repair / retry</div>
+      <div class="li"><svg width="36" height="8"><line x1="0" y1="4" x2="36" y2="4" stroke="rgba(28,28,26,.5)" stroke-width="1.6" stroke-dasharray="2 6" stroke-linecap="round"/></svg>eval-контур</div>
+      <div class="li"><svg width="36" height="8"><line x1="0" y1="4" x2="36" y2="4" stroke="rgba(28,28,26,.4)" stroke-width="1.5" stroke-dasharray="3 5"/></svg>opt-in узлы</div>
+      <div class="li"><span class="chip">1</span>шаги happy path</div>
+    </div>
+  </div>
+</header>
+
+<div id="viewport"><div id="scaler"><div id="canvas">
+
+  <!-- ================= zones ================= -->
+  <div class="zone zone-tint" style="left:24px;top:36px;width:1832px;height:360px"></div>
+  <div class="zone zone-hot"  style="left:24px;top:420px;width:1832px;height:776px"></div>
+  <div class="zone zone-tint" style="left:24px;top:1240px;width:1832px;height:368px"></div>
+  <div class="zone zone-tint" style="left:24px;top:1648px;width:1832px;height:404px"></div>
+
+  <div class="zone-h" style="left:48px;top:52px"><span class="zn">01</span>Offline indexing<small>scripts/build_index.py · build_fewshot_index.py — однократно при setup / смене схемы</small></div>
+  <div class="zone-h" style="left:48px;top:436px"><span class="zn">02</span>Online query pipeline<small>agent/graph.py · LangGraph StateGraph · PipelineState</small></div>
+  <div class="zone-h" style="left:48px;top:1258px"><span class="zn">03</span>LLM provider layer<small>единый Protocol · кэш как основа $0-бюджета</small></div>
+  <div class="zone-h" style="left:48px;top:1666px"><span class="zn">04</span>Eval harness &amp; audit<small>ablation → voting → merge → re-score → audit · residue-цикл ×31 (47% → 94.0%)</small></div>
+
+  <!-- ================= zone A: offline indexing ================= -->
+  <div class="node" id="src" style="left:48px;top:88px;width:248px;height:216px">
+    <h3>Data sources</h3>
+    <p class="path">scripts/download_data.py → data/</p>
+    <ul>
+      <li><b>BIRD Mini-Dev</b> — 11 SQLite БД · 500 Q→SQL (dev)</li>
+      <li><b>BIRD train</b> — 9 428 Q→SQL пар (HF parquet)</li>
+      <li><b>Chinook.sqlite</b> — smoke</li>
+      <li><b>PostgreSQL 16</b> — docker-compose, opt-in</li>
+    </ul>
+    <div class="badges"><span class="bdg">SQLite</span><span class="bdg">PostgreSQL 16</span></div>
+  </div>
+
+  <div class="node" id="intro" style="left:372px;top:104px;width:250px;height:160px">
+    <h3>Introspector</h3>
+    <p class="path">schema_index/introspector.py</p>
+    <p><b>SQLAlchemy reflection</b> (read-only): таблицы, колонки, PK/FK, top-K sample values, NULL count, distinct count.</p>
+    <div class="badges"><span class="bdg">SQLAlchemy</span></div>
+  </div>
+
+  <div class="node" id="chunk" style="left:700px;top:104px;width:250px;height:148px">
+    <h3>Chunker</h3>
+    <p class="path">schema_index/chunker.py</p>
+    <p><b>1 таблица = 1 card</b>: имя + колонки + типы + samples + FK от/к + business-hints; fk_targets → metadata.</p>
+  </div>
+
+  <div class="node" id="idx" style="left:1028px;top:104px;width:240px;height:148px">
+    <h3>Indexer</h3>
+    <p class="path">schema_index/indexer.py</p>
+    <p>Upsert со <b>stable chunk_id</b> — без дублей при переиндексации; API чтения — SchemaIndex.</p>
+  </div>
+
+  <div class="node hot" id="chroma" style="left:1352px;top:96px;width:256px;height:204px">
+    <h3>Vector store</h3>
+    <p class="path">ChromaDB · chroma_data/ (persistent)</p>
+    <ul>
+      <li><b>schema_chunks</b> — 1 запись = (db, table)</li>
+      <li><b>fewshot_qsql</b> — эмбеддится только вопрос; SQL + db_id + intent в metadata</li>
+    </ul>
+    <div class="badges"><span class="bdg a">chromadb</span></div>
+  </div>
+
+  <div class="node" id="fewshot" style="left:700px;top:304px;width:250px;height:88px">
+    <h3 style="font-size:13px">Few-shot builder</h3>
+    <p class="path">scripts/build_fewshot_index.py</p>
+    <p style="font-size:12px">Q→SQL <b>только из train</b> · hard guard от dev-leakage.</p>
+  </div>
+
+  <div class="node" id="embed" style="left:1028px;top:304px;width:240px;height:88px">
+    <h3 style="font-size:13px">Embeddings</h3>
+    <p class="path">mistral-embed · 1024-dim</p>
+    <p style="font-size:12px">CachingEmbeddingProvider → <b>diskcache</b>: реиндексация = 0 API.</p>
+  </div>
+
+  <div class="node" id="fkg" style="left:1672px;top:104px;width:168px;height:148px">
+    <h3>FK graph</h3>
+    <p class="path">in-memory dict</p>
+    <p style="font-size:12px">SchemaIndex.fk_graph из fk_targets. <b>Не в Chroma</b>: FK-рёбра не несут семантики.</p>
+  </div>
+
+  <!-- ================= zone B: clients column ================= -->
+  <div class="node hot" id="user" style="left:48px;top:510px;width:250px;height:64px">
+    <span class="step">1</span>
+    <h3>Пользователь</h3>
+    <p>вопрос на RU / EN</p>
+  </div>
+
+  <div class="node hot" id="st" style="left:48px;top:610px;width:250px;height:184px">
+    <h3>Streamlit UI</h3>
+    <p class="path">app/streamlit_app.py · 8 модулей</p>
+    <p>Chat + sample-вопросы · schema explorer · show-working trace · EN↔RU · режимы Accurate / Fast / Debug.</p>
+    <div class="badges"><span class="bdg">Streamlit</span><span class="bdg">Plotly</span><span class="bdg">@st.cache_resource</span></div>
+  </div>
+
+  <div class="node hot" id="api" style="left:48px;top:830px;width:250px;height:184px">
+    <h3>FastAPI</h3>
+    <p class="path">src/nl_sql/api/main.py</p>
+    <p>POST /ask · GET /databases · /healthz · /readyz · /eval/latest. X-API-Key + token bucket <span class="mono">60 req/min</span> · Singletons DI.</p>
+    <div class="badges"><span class="bdg">FastAPI</span><span class="bdg">Pydantic v2</span><span class="bdg">uvicorn</span></div>
+  </div>
+
+  <div class="node" id="hf" style="left:48px;top:1050px;width:250px;height:106px">
+    <h3 style="font-size:13px">Hugging Face Spaces</h3>
+    <p class="path">liovina-nl-sql.hf.space</p>
+    <p style="font-size:12px">Docker free tier · UI + API в одном контейнере · deploy ≈ 90 с.</p>
+  </div>
+
+  <!-- ================= zone B: LangGraph row 1 ================= -->
+  <div class="node hot" id="ctx" style="left:400px;top:510px;width:270px;height:184px">
+    <span class="step">2</span>
+    <h3>context_builder</h3>
+    <p class="path">schema_index/retriever.py</p>
+    <p>Dense top-k=5 schema-чанков (filter db_id) → <b>FK BFS ≤1 hop</b>, бюджет 12 таблиц → few-shot k=3 (cross-db на BIRD) → extended samples 3→5 → dialect hints. Выход: <b>ContextBundle</b>.</p>
+  </div>
+
+  <div class="node dashed" id="plan" style="left:742px;top:424px;width:270px;height:66px">
+    <h3 style="font-size:13px">plan_query<span class="tag opt">opt-in</span></h3>
+    <p style="font-size:12px">JSON-скелет: tables · joins · filters · group_by · sort · limit</p>
+  </div>
+
+  <div class="node hot" id="gen" style="left:742px;top:510px;width:270px;height:184px">
+    <span class="step">3</span>
+    <h3>generate_sql</h3>
+    <p class="path">codestral-latest · T=0</p>
+    <p>Structured JSON: <span class="mono" style="font-size:11px">{sql, rationale, tables_used, confidence}</span>. Шаблоны: cards | M-Schema (XiYan) | DAC (CHASE-SQL) + <b>P3.F hints</b> — 11 правил, gated db_id+phrase.</p>
+  </div>
+
+  <div class="node hot" id="val" style="left:1084px;top:510px;width:250px;height:184px">
+    <span class="step">4</span>
+    <h3>validate · AST guard</h3>
+    <p class="path">execution/guards.py · sqlglot</p>
+    <p>SELECT-only · no DML/DDL в дереве · 1 statement · function denylist (pg_sleep, load_extension…) · denied tables · ATTACH / PRAGMA block.</p>
+    <div class="badges"><span class="bdg a">sqlglot</span></div>
+  </div>
+
+  <div class="node hot" id="exe" style="left:1406px;top:510px;width:270px;height:196px">
+    <span class="step">5</span>
+    <h3>execute · read-only</h3>
+    <p class="path">execution/runner.py → db/connection.py</p>
+    <p>SQLite: URI <span class="mono" style="font-size:11px">mode=ro</span> + PRAGMA query_only + progress-deadline; Postgres: read-only транзакции + statement_timeout 30 s; <b>row cap 10 000</b>.</p>
+    <div class="badges"><span class="bdg a">3-layer safety</span><span class="bdg">SQLAlchemy</span></div>
+  </div>
+
+  <div class="node" id="rep" style="left:1042px;top:752px;width:250px;height:110px">
+    <span class="step alt">×1</span>
+    <h3>repair_once</h3>
+    <p class="path">agent/nodes/repair_once.py</p>
+    <p style="font-size:12px"><b>Ровно 1 повтор</b> с error-context (guard repair_attempted): validate-fail / runtime-fail / empty (G) / critique-fail.</p>
+  </div>
+
+  <!-- ================= zone B: LangGraph row 2 ================= -->
+  <div class="node dashed" id="crit" style="left:1406px;top:936px;width:270px;height:84px">
+    <h3 style="font-size:13px">grounded_critique<span class="tag opt">opt-in</span></h3>
+    <p style="font-size:12px">Row-shape проверка результата → не более 1 retry.</p>
+  </div>
+
+  <div class="node hot" id="fmt" style="left:1080px;top:936px;width:260px;height:176px">
+    <span class="step">6</span>
+    <h3>deterministic_format<span class="tag nollm">no LLM</span></h3>
+    <p class="path">render/picker.py · formats.py</p>
+    <p>Чистый Python, эвристи��и по shape результата: <b>Scalar · Sentence · Table · Line · Bar · Pie · Scatter</b>.</p>
+    <div class="badges"><span class="bdg">Plotly</span></div>
+  </div>
+
+  <div class="node hot" id="exp" style="left:748px;top:936px;width:260px;height:176px">
+    <span class="step">7</span>
+    <h3>explain_trace</h3>
+    <p class="path">mistral-large-latest</p>
+    <p>NL-caption ≤ 2 предложений; финализация trace (model, tokens, latency, confidence по каждому узлу).</p>
+  </div>
+
+  <div class="node hot" id="ans" style="left:400px;top:936px;width:270px;height:176px">
+    <span class="step">8</span>
+    <h3>Ответ · AskResponse</h3>
+    <p class="path">PipelineRunResult</p>
+    <p>answer + SQL (подсветка) + rationale + confidence + caption + полный trace. Error taxonomy: <span class="mono" style="font-size:10.5px">invalid_sql · execution_timeout · execution_failed · empty_result · low_confidence · repair_failed</span></p>
+  </div>
+
+  <!-- ================= zone C: providers ================= -->
+  <div class="node" id="proto" style="left:400px;top:1300px;width:290px;height:158px">
+    <h3>LLMProvider Protocol</h3>
+    <p class="path">llm/providers/base.py · factory.py</p>
+    <p>PEP 544 runtime_checkable · <span class="mono" style="font-size:11px">build_provider(name)</span> — смена модели = env var · ProviderError taxonomy. Embed-протокол отдельно.</p>
+  </div>
+
+  <div class="node hot" id="cache" style="left:760px;top:1300px;width:290px;height:158px">
+    <h3>Caching layer</h3>
+    <p class="path">llm/cache.py · diskcache</p>
+    <p>Ключ <span class="mono" style="font-size:10.5px">sha256(provider · model · system · prompt · T · max_tok)</span>: hit = 0 quota, 0 latency — основа <b>$0-бюджета</b>. В тестах — fake-провайдеры, CI без live API.</p>
+    <div class="badges"><span class="bdg a">diskcache</span></div>
+  </div>
+
+  <div class="group" id="provgroup" style="left:1120px;top:1268px;width:724px;height:330px">
+    <span class="gt">7 provider-модулей + GraceKelly browser-мост · voting / residue-слои</span>
+  </div>
+  <div class="node pcard" id="p-mistral" style="left:1136px;top:1316px;width:160px;height:124px">
+    <h3>Mistral<span class="tag pri">primary</span></h3>
+    <p>codestral-latest (SQL) · mistral-large (NL) · mistral-embed. La Plateforme free.</p>
+  </div>
+  <div class="node pcard" id="p-groq" style="left:1312px;top:1316px;width:160px;height:124px">
+    <h3>Groq</h3>
+    <p>llama-3.3-70b · qwen3-32b · gpt-oss. TPM/TPD-bounded.</p>
+  </div>
+  <div class="node pcard" id="p-gh" style="left:1488px;top:1316px;width:160px;height:124px">
+    <h3>GitHub Models</h3>
+    <p>gpt-4o-mini · auth по PAT · OpenAI-compatible SDK.</p>
+  </div>
+  <div class="node pcard" id="p-or" style="left:1664px;top:1316px;width:160px;height:124px">
+    <h3>OpenRouter</h3>
+    <p>deepseek-v4-flash:free + 24 беспл. reasoning/code-моделей.</p>
+  </div>
+  <div class="node pcard" id="p-ollama" style="left:1136px;top:1456px;width:160px;height:124px">
+    <h3>Ollama</h3>
+    <p>local · qwen2.5-coder:7b — offline-слот bakeoff.</p>
+  </div>
+  <div class="node pcard" id="p-pplx" style="left:1312px;top:1456px;width:160px;height:124px">
+    <h3>Perplexity / helallao</h3>
+    <p>GPT-5.2 · Grok-4.1 · Claude-4.5 · Kimi-K2 (reasoning / Pro).</p>
+  </div>
+  <div class="node pcard" id="p-gk" style="left:1488px;top:1456px;width:160px;height:124px">
+    <h3>GraceKelly</h3>
+    <p>browser-orchestrator → Sonnet 4.6 (eval-only мост).</p>
+  </div>
+  <div class="note" style="left:1664px;top:1456px;width:160px;height:124px">
+    <b>$0 hard constraint</b> — free tiers + кэш + user-подписки; ротация аккаунтов запрещена.
+  </div>
+
+  <!-- ================= zone D: eval ================= -->
+  <div class="node" id="ds" style="left:48px;top:1704px;width:250px;height:158px">
+    <h3>Dataset</h3>
+    <p class="path">eval/dataset.py</p>
+    <p>BIRD Mini-Dev loader · <span class="mono" style="font-size:11px">dev_split(seed=0, n)</span> — stable-prefix: n=50 ⊂ n=200 → кэш промптов переиспользуется.</p>
+  </div>
+
+  <div class="node" id="runner" style="left:372px;top:1704px;width:260px;height:158px">
+    <h3>Ablation runner</h3>
+    <p class="path">eval/runner.py</p>
+    <p>Конфиги A · C · D · E · F (T-sweep 0.2–0.8) · G (B=BM25, N/I): A–D без repair, G + verify_retry_on_empty → <span class="mono" style="font-size:11px">eval/reports/*.json</span>.</p>
+  </div>
+
+  <div class="node" id="voting" style="left:706px;top:1704px;width:290px;height:194px">
+    <h3>Voting / rescue scripts</h3>
+    <p class="path">scripts/run_*.py</p>
+    <p>groq_voting · sonnet (GraceKelly) · helallao · openrouter · critique_retry · selfcon (T-sweep) · wide_schema · ensemble_vote. Работают по <b>residue</b> (misses) поверх v_N.</p>
+  </div>
+
+  <div class="node" id="merge" style="left:1070px;top:1704px;width:250px;height:158px">
+    <h3>Merge</h3>
+    <p class="path">scripts/merge_voting_rescues.py</p>
+    <p><span class="mono" style="font-size:11px">--reverify</span> — re-exec через safe_compare_pred · archive_sweep / rescore → merged baseline v<sub>N+1</sub>.</p>
+  </div>
+
+  <div class="node" id="metrics" style="left:1394px;top:1704px;width:200px;height:158px">
+    <h3>Metrics</h3>
+    <p class="path">eval/metrics/</p>
+    <p style="font-size:12px">execution_accuracy — <b>BIRD-official set-equality</b> · safe_compare_pred (pred-fail → False) · schema_recall@k.</p>
+  </div>
+
+  <div class="node" id="audit" style="left:1640px;top:1704px;width:204px;height:194px">
+    <h3>Audit gates</h3>
+    <p class="path">scripts/</p>
+    <p style="font-size:12px">audit_rescore — row-by-row re-execution · p3f_acceptance — 11 gates (req/forbidden columns по AST) · error_taxonomy buckets · refresh_baseline_summary.</p>
+  </div>
+
+  <div class="node hot" id="result" style="left:1070px;top:1944px;width:524px;height:92px">
+    <h3>v31 baseline · <span class="numeric">94.0% EA (188/200) · 0 mismatches</span></h3>
+    <p style="font-size:12px">→ README headline · GET /eval/latest · HF redeploy. Lift trace: 47% (config A) → 94.0% (v31), 31 версия, каждая с negative/saturation evidence.</p>
+  </div>
+
+  <!-- ================= zone E: CI ribbon ================= -->
+  <div class="ribbon" style="left:48px;top:2104px;width:1784px;height:92px">
+    <span class="rt">05 · Quality gates &amp; CI/CD</span>
+    <span class="bdg">pytest · 370 green</span>
+    <span class="bdg">coverage 91%</span>
+    <span class="bdg">mypy --strict · 0 issues / 59 files</span>
+    <span class="bdg">ruff check + format</span>
+    <span class="bdg">GitHub Actions · Ubuntu · py3.13 · uv</span>
+    <span class="bdg">uv.lock pinned + requirements-guard</span>
+    <span class="bdg">fake-провайдеры — CI без live API</span>
+    <span class="bdg">.deploy_hf.py + Playwright E2E grep-gate</span>
+    <span class="bdg">Makefile</span>
+    <span class="bdg">docker-compose · postgres / langfuse profiles</span>
+  </div>
+
+  <svg id="wires" width="1880" height="2236">
+    <defs>
+      <marker id="m-hot"  viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7.5" markerHeight="7.5" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#9C5B38"/></marker>
+      <marker id="m-rep"  viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7"  markerHeight="7"  orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#9C5B38"/></marker>
+      <marker id="m-bus"  viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7"  markerHeight="7"  orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#9C5B38"/></marker>
+      <marker id="m-idx"  viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7"  markerHeight="7"  orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="rgba(28,28,26,0.45)"/></marker>
+      <marker id="m-opt"  viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6.5" markerHeight="6.5" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="rgba(28,28,26,0.45)"/></marker>
+      <marker id="m-eval" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7"  markerHeight="7"  orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="rgba(28,28,26,0.55)"/></marker>
+    </defs>
+  </svg>
+
+</div></div></div>
+
+<footer>
+  Источник: <span class="mono">src/nl_sql/* · app/* · eval/* · scripts/*</span> @ <span class="mono">8e6c61d</span> · baseline v31 (2026-05-26) · схема сгенерирована 2026-06-06 · подробности: <span class="mono">docs/02_architecture_v2.md</span>, <span class="mono">docs/03_eval_methodology.md</span>, <span class="mono">docs/SESSION_HANDOFF.md</span> · печатная версия: <a href="data_flow.pdf" style="color:var(--accent-dark)">data_flow.pdf</a> · зум: кнопки справа внизу или клавиши <span class="mono">+ − 0</span>
+</footer>
+
+<script>
+/* ---------- edge definitions ---------- */
+/* f/t: node id; fs/ts: side l|r|t|b; ff/tf: fraction along side (0..1, default .5);
+   k: kind; lb: label; la: label position 0..1; via: waypoints; c: curvature override */
+const EDGES = [
+  /* zone A: offline indexing */
+  {f:'src',fs:'r',t:'intro',ts:'l',k:'idx',lb:'engine (ro)'},
+  {f:'intro',fs:'r',t:'chunk',ts:'l',k:'idx',lb:'TableInfo'},
+  {f:'chunk',fs:'r',t:'idx',ts:'l',k:'idx',lb:'SchemaChunk'},
+  {f:'idx',fs:'r',t:'chroma',ts:'l',k:'idx',lb:'upsert'},
+  {f:'src',fs:'r',ff:.9,t:'fewshot',ts:'l',k:'idx',lb:'train split',la:.5,c:.2},
+  {f:'fewshot',fs:'t',ff:.6,t:'idx',ts:'b',tf:.3,k:'idx',lb:'Q→SQL · 9 428 train',la:.5,dy:-4},
+  {f:'idx',fs:'b',ff:.62,t:'embed',ts:'t',k:'idx',lb:'texts',la:.4},
+  {f:'embed',fs:'r',t:'chroma',ts:'b',tf:.35,k:'idx',lb:'vectors 1024-d',la:.5},
+  {f:'chroma',fs:'r',t:'fkg',ts:'l',k:'idx',lb:'fk_targets'},
+  /* query-time retrieval */
+  {f:'chroma',fs:'b',ff:.55,t:'ctx',ts:'t',tf:.25,k:'hot',lb:'top-k=5 schema + k=3 few-shot (db_id)',la:.45,via:[[1493,412],[467,412]]},
+  {f:'fkg',fs:'b',ff:.5,t:'ctx',ts:'t',tf:.72,k:'hot',lb:'FK BFS ≤1 hop · budget 12',la:.42,via:[[1756,400],[594,400]]},
+  /* hot path */
+  {f:'user',fs:'b',t:'st',ts:'t',k:'hot'},
+  {f:'st',fs:'r',ff:.35,t:'ctx',ts:'l',tf:.35,k:'hot',lb:'question · db_id · dialect',la:.45},
+  {f:'api',fs:'r',ff:.3,t:'ctx',ts:'l',tf:.78,k:'hot',lb:'POST /ask',la:.4},
+  {f:'ctx',fs:'r',ff:.82,t:'gen',ts:'l',tf:.82,k:'hot',lb:'ContextBundle → prompt',dy:30},
+  {f:'gen',fs:'r',ff:.82,t:'val',ts:'l',tf:.82,k:'hot',lb:'sql · rationale · confidence',dy:36},
+  {f:'val',fs:'r',ff:.82,t:'exe',ts:'l',tf:.82,k:'hot',lb:'AST-clean SQL',dy:30},
+  {f:'exe',fs:'b',ff:.32,t:'fmt',ts:'t',tf:.6,k:'hot',lb:'QueryResult · rows ≤ 10 000',la:.6,via:[[1492,880],[1236,880]]},
+  {f:'fmt',fs:'b',ff:.2,t:'exp',ts:'b',tf:.8,k:'hot',lb:'OutputFormat (1 из 7)',la:.5,c:.22},
+  {f:'exp',fs:'l',t:'ans',ts:'r',k:'hot',lb:'caption'},
+  {f:'ans',fs:'l',ff:.3,t:'st',ts:'r',tf:.72,k:'hot',lb:'answer + SQL + trace',la:.5},
+  {f:'ans',fs:'l',ff:.72,t:'api',ts:'r',tf:.65,k:'hot',lb:'AskResponse',la:.45},
+  /* repair loops */
+  {f:'val',fs:'b',ff:.55,t:'rep',ts:'t',tf:.62,k:'rep',lb:'fail + error ctx',la:.5},
+  {f:'rep',fs:'t',ff:.12,t:'val',ts:'b',tf:.12,k:'rep',lb:'SQL v2 · ×1',la:.5},
+  {f:'exe',fs:'b',ff:.1,t:'rep',ts:'r',tf:.2,k:'rep',lb:'runtime / empty (G)',la:.45,c:.3},
+  /* opt-in */
+  {f:'ctx',fs:'t',ff:.6,t:'plan',ts:'l',k:'opt',la:.5,c:.4},
+  {f:'plan',fs:'b',ff:.5,t:'gen',ts:'t',tf:.5,k:'opt',lb:'JSON skeleton',la:.5},
+  {f:'exe',fs:'b',ff:.78,t:'crit',ts:'t',tf:.5,k:'opt',lb:'opt-in',la:.5},
+  {f:'crit',fs:'l',t:'fmt',ts:'r',tf:.25,k:'opt',lb:'ok',la:.5},
+  {f:'crit',fs:'t',ff:.3,t:'rep',ts:'b',tf:.7,k:'opt',lb:'fail ×1',la:.55,via:[[1487,906],[1247,906]]},
+  /* LLM bus */
+  {f:'gen',fs:'b',ff:.5,t:'proto',ts:'l',tf:.5,k:'bus',lb:'LLM-вызовы: plan · generate · repair · explain',la:.22,via:[[877,716],[349,716],[349,1379]]},
+  {f:'exp',fs:'b',ff:.5,t:'proto',ts:'l',tf:.5,k:'bus',via:[[878,1146],[349,1146],[349,1379]]},
+  {f:'proto',fs:'r',t:'cache',ts:'l',k:'bus',lb:'wrap'},
+  {f:'cache',fs:'b',ff:.9,t:'provgroup',ts:'l',tf:.8,k:'bus',lb:'HTTP только при cache-miss',la:.55,dy:12,c:.3},
+  /* eval loop */
+  {f:'ds',fs:'r',t:'runner',ts:'l',k:'eval',lb:'n=200 · seed=0',dy:-8},
+  {f:'runner',fs:'r',t:'voting',ts:'l',k:'eval',lb:'residue v_N'},
+  {f:'voting',fs:'r',t:'merge',ts:'l',k:'eval',lb:'verified rescues'},
+  {f:'merge',fs:'r',t:'metrics',ts:'l',k:'eval',lb:'re-score'},
+  {f:'metrics',fs:'r',t:'audit',ts:'l',k:'eval'},
+  {f:'audit',fs:'b',ff:.5,t:'result',ts:'r',tf:.5,k:'eval',lb:'0 mismatches',la:.5,c:.4},
+  {f:'result',fs:'l',ff:.5,t:'voting',ts:'b',tf:.6,k:'eval',lb:'residue-loop ×31',la:.5,c:.4},
+  {f:'runner',fs:'t',ff:.72,t:'ans',ts:'b',tf:.82,k:'eval',lb:'run_pipeline() на каждый qid',la:.35,via:[[559,1676],[725,1676],[725,1150]]},
+  {f:'voting',fs:'t',ff:.5,t:'cache',ts:'b',tf:.5,k:'eval',lb:'те же providers',la:.5},
+  /* hosting */
+  {f:'hf',fs:'t',ff:.5,t:'api',ts:'b',tf:.5,k:'opt',lb:'Docker',la:.5},
+];
+
+const canvas=document.getElementById('canvas');
+const svg=document.getElementById('wires');
+const NS='http://www.w3.org/2000/svg';
+
+function anchor(id,side,frac){
+  const el=document.getElementById(id);
+  const x=el.offsetLeft,y=el.offsetTop,w=el.offsetWidth,h=el.offsetHeight;
+  const f=(frac==null?0.5:frac);
+  switch(side){
+    case 'l':return{x:x,        y:y+h*f, nx:-1,ny:0};
+    case 'r':return{x:x+w,      y:y+h*f, nx:1, ny:0};
+    case 't':return{x:x+w*f,    y:y,     nx:0, ny:-1};
+    case 'b':return{x:x+w*f,    y:y+h,   nx:0, ny:1};
+  }
+}
+
+function buildPath(e){
+  const a=anchor(e.f,e.fs,e.ff), b=anchor(e.t,e.ts,e.tf);
+  if(e.via){
+    let d=`M ${a.x},${a.y}`;
+    e.via.forEach(p=>{d+=` L ${p[0]},${p[1]}`;});
+    d+=` L ${b.x},${b.y}`;
+    return d;
+  }
+  const dist=Math.hypot(b.x-a.x,b.y-a.y);
+  const k=dist*(e.c!=null?e.c:0.38);
+  const c1x=a.x+a.nx*k, c1y=a.y+a.ny*k;
+  const c2x=b.x+b.nx*k, c2y=b.y+b.ny*k;
+  return `M ${a.x},${a.y} C ${c1x},${c1y} ${c2x},${c2y} ${b.x},${b.y}`;
+}
+
+EDGES.forEach(e=>{
+  const g=document.createElementNS(NS,'g');
+  g.setAttribute('class','edge');
+  g.dataset.f=e.f; g.dataset.t=e.t;
+  const p=document.createElementNS(NS,'path');
+  p.setAttribute('d',buildPath(e));
+  p.setAttribute('class','l '+e.k);
+  p.setAttribute('marker-end',`url(#m-${e.k})`);
+  if(e.via){p.setAttribute('stroke-linejoin','round');}
+  g.appendChild(p);
+  if(e.lb){
+    const len=p.getTotalLength();
+    const pt=p.getPointAtLength(len*(e.la!=null?e.la:0.5));
+    const tx=document.createElementNS(NS,'text');
+    tx.setAttribute('x',pt.x+(e.dx||0)); tx.setAttribute('y',pt.y+4+(e.dy||0));
+    tx.setAttribute('text-anchor','middle');
+    tx.setAttribute('class',(e.k==='hot'||e.k==='rep'||e.k==='bus')?'lt-hot':'lt-mut');
+    tx.textContent=e.lb;
+    g.appendChild(tx);
+    svg.appendChild(g);
+    const bb=tx.getBBox();
+    const r=document.createElementNS(NS,'rect');
+    r.setAttribute('x',bb.x-5);r.setAttribute('y',bb.y-2);
+    r.setAttribute('width',bb.width+10);r.setAttribute('height',bb.height+4);
+    r.setAttribute('rx',3);r.setAttribute('class','lbg');
+    g.insertBefore(r,tx);
+  } else {
+    svg.appendChild(g);
+  }
+});
+
+/* hover focus: highlight a node's edges + neighbours */
+document.querySelectorAll('.node,.group').forEach(n=>{
+  n.addEventListener('mouseenter',()=>{
+    canvas.classList.add('focus');
+    n.classList.add('on');
+    document.querySelectorAll('.edge').forEach(ed=>{
+      if(ed.dataset.f===n.id||ed.dataset.t===n.id){
+        ed.classList.add('on');
+        const other=document.getElementById(ed.dataset.f===n.id?ed.dataset.t:ed.dataset.f);
+        if(other)other.classList.add('on');
+      }
+    });
+  });
+  n.addEventListener('mouseleave',()=>{
+    canvas.classList.remove('focus');
+    document.querySelectorAll('.on').forEach(x=>x.classList.remove('on'));
+  });
+});
+
+/* ---------- scaling + zoom ---------- */
+let userZoom=null; /* null = fit to viewport */
+function fitScale(){
+  const vw=document.getElementById('viewport').clientWidth;
+  return Math.min(1,(vw-16)/1880);
+}
+function rescale(){
+  const vp=document.getElementById('viewport');
+  const s=userZoom!=null?userZoom:fitScale();
+  const sc=document.getElementById('scaler');
+  sc.style.transform=`scale(${s})`;
+  sc.style.width='1880px';
+  sc.style.height=(2236*s)+'px';
+  vp.style.overflowX=(1880*s>vp.clientWidth)?'auto':'hidden';
+  document.getElementById('zval').textContent=Math.round(s*100)+'%';
+}
+document.querySelectorAll('#zoombar button').forEach(btn=>{
+  btn.addEventListener('click',()=>{
+    const cur=userZoom!=null?userZoom:fitScale();
+    if(btn.dataset.z==='in')  userZoom=Math.min(1.6,Math.round((cur+0.15)*100)/100);
+    if(btn.dataset.z==='out') userZoom=Math.max(0.3,Math.round((cur-0.15)*100)/100);
+    if(btn.dataset.z==='fit') userZoom=null;
+    rescale();
+  });
+});
+window.addEventListener('keydown',e=>{
+  if(e.target.tagName==='INPUT'||e.ctrlKey||e.metaKey)return;
+  if(e.key==='+'||e.key==='='){userZoom=Math.min(1.6,(userZoom!=null?userZoom:fitScale())+0.15);rescale();}
+  if(e.key==='-'){userZoom=Math.max(0.3,(userZoom!=null?userZoom:fitScale())-0.15);rescale();}
+  if(e.key==='0'){userZoom=null;rescale();}
+});
+window.addEventListener('resize',rescale);
+rescale();
+
+/* mobile stub */
+if(window.innerWidth<900){
+  document.getElementById('mobile-stub').style.display='flex';
+  document.body.style.overflow='hidden';
+}
+</script>
+</body>
+</html>

docs/data_flow.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b128a8658f7f2c5ba0feb96f8a28dbb1f7199291973b5ac34eba2b0d8475d8cb
+size 621974

scripts/rescore_arcwise.py

@@ -147,6 +147,16 @@ def main() -> int:
                 per_diff[variant][difficulty][0] += int(is_match)
 
             # Transitions vs sql_only and vs full.
+            # Use the FRESHLY-re-executed original-variant match (written at
+            # `out_entry["original_match"]` by the variant loop above) rather
+            # than the stale `orig_match` snapshot from the input JSON — the
+            # whole point of rescore is to apply current scoring semantics, so
+            # mixing in stored EA bits would produce a hybrid that doesn't
+            # match either run cleanly (Codex audit 2026-05-25 #7). On the
+            # current canonical v22-v30 baselines the two values agree on
+            # every record, so this is a future-proofing change; no
+            # observable difference in committed reports.
+            fresh_orig = bool(out_entry.get("original_match", orig_match))
             for variant in ("sql_only", "full"):
                 v_match = out_entry.get(f"{variant}_match")
                 if v_match is None:
@@ -158,11 +168,11 @@ def main() -> int:
                 )
                 if gold_changed:
                     out_entry[f"{variant}_gold_changed"] = True
-                if orig_match and not v_match:
+                if fresh_orig and not v_match:
                     transitions["lost"].append(
                         {"qid": qid, "variant": variant, "difficulty": difficulty}
                     )
-                elif (not orig_match) and v_match:
+                elif (not fresh_orig) and v_match:
                     transitions["gained"].append(
                         {"qid": qid, "variant": variant, "difficulty": difficulty}
                     )