md

History/provenance-columns.md

@@ -0,0 +1,44 @@
+# Provenance Columns — Opus Round 2
+
+Дата: 2026-06-23 | Версия: v1.0.114 | Связано: spec_events, apply_events.cfm, convert_server.py
+
+---
+
+## Что сделано
+
+Добавлены две колонки в `spec_events`, рекомендованные Opus (раунд 2, ответ 6):
+
+| Колонка | Тип | Откуда берётся | Зачем |
+|---------|-----|----------------|-------|
+| `source_document_id` | UUID FK→documents | `convert_server.py` — из JOIN supplements+documents | Прямая ссылка на исходный документ (provenance). Без неё — только через supplement_id, что хрупко. |
+| `raw_llm_response` | JSONB | `convert_server.py` — полный `llm_result` (mode + ops) | Аудит: что модель ВООБЩЕ ответила vs что мы применили. Воспроизводимость. |
+
+Вместе с `prompt_version` (v1.0.113) — полный комплект provenance для каждой операции.
+
+## Почему
+
+Opus: «Добавилась услуга X за 15000» без источника — бесполезно. «Добавилась услуга X ← допник №3, п.2.4, вот абзац» → проверка за 2 секунды.
+
+Три колонки закрывают:
+- **Каким промптом** (`prompt_version`)
+- **Из какого документа** (`source_document_id`)
+- **Что модель ответила** (`raw_llm_response`)
+
+## Что изменилось
+
+### convert_server.py
+- SQL запрос supplements: добавлен `d.id as document_id`
+- apply_events POST: добавлены `document_id` и `raw_llm_response`
+
+### apply_events.cfm
+- 3× ALTER TABLE ADD COLUMN IF NOT EXISTS (prompt_version, source_document_id, raw_llm_response)
+- Все 7 INSERT INTO spec_events: +2 колонки с `<cfif len(...)>`
+
+## Что НЕ изменилось
+- Логика сравнения
+- spec_current
+- UI
+- Старые строки — NULL в новых колонках, ни на что не влияет
+
+## Риски
+- Нулевые. Колонки опциональные (NULL разрешён), чисто аддитивные.