Initial project import

docs/runbooks/1c-operational-coding.md

@@ -116,8 +116,11 @@ SQL удобен как быстрый источник данных, но не
   canonical path до процедуры, областью является эта процедура/функция; иначе
   весь текущий saved-модуль.
 
-По умолчанию `code.write` делает `mode=apply`, но это apply в saved-state
-слой (`ConfigSave`/`ConfigCASSave`), а не применение конфигурации в runtime.
+По умолчанию `code.write` делает безопасный `mode=plan` и не пишет в SQL.
+Только явно переданный `mode=apply`, `apply_and_verify` или
+`apply_and_rollback` может записать saved-state слой
+(`ConfigSave`/`ConfigCASSave`); это всё равно не применение конфигурации в
+runtime.
 Адаптер сам выставляет save-first gates и сам выбирает физический маршрут.
 Физические детали возвращаются только при `include_storage=true` для
 диагностики. Ответ `code.write` всегда содержит `write_mode`: target
@@ -134,6 +137,62 @@ source `saved_state`, activation_state `not_activated`.
 добирается отдельным проходом, а `counts.saved_matches` и
 `counts.active_matches` показывают покрытие по слоям.
 
+### Repository lock and first extension edit
+
+Для изменения объекта в расширении, подключенном к хранилищу, агент сначала
+использует только публичные вызовы:
+
+```text
+code.search → repository.lock.plan → repository.lock.request
+→ человек захватывает объект в Конфигураторе → repository.lock.confirm
+→ code.write → code.search (readback)
+```
+
+Если у extension-модуля ещё нет saved-state строки, `code.write(mode=plan)`
+возвращает `needs_prepare` и
+`diagnostics.next_action=confirm_repository_lock_then_apply`. Это нормальный
+первый-edit маршрут: после подтверждённого lock тот же публичный `code.write`
+в apply-режиме сам подготовит saved-state. Агент не передаёт `module_ref`,
+`stream_index`, таблицу или имя технического файла.
+
+Исключение: `extension_saved_state_prepare_protocol_unproven` означает, что
+автоматическая подготовка запрещена. Это не доказательство того, что
+расширение не сохраняли: адаптер ещё не доказал точный prepare-кодек для
+наблюдаемой extension-layout. Агент не создаёт контейнер через SQL и передаёт
+случай разработчикам адаптера без технических координат.
+
+Acceptance extension write считается пройденным только при наличии в
+`upo_test` отдельного extension-owned `Report` с object module и успешном
+публичном `code.write(..., apply_and_rollback)` без storage-координат. Успех
+base-модуля в `ConfigSave` не доказывает ветку `ConfigCAS → ConfigCASSave`.
+
+`upo` не используется для автоматических проверочных записей. Контролируемые
+`apply_and_rollback` проверки разрешены только в `upo_test`.
+
+Для регрессии первого extension-edit используйте публичный smoke (без SQL
+таблиц, key, module_ref или GUID в запросе):
+
+```powershell
+python scripts\smoke_1c_extension_saved_state_prepare.py --apply
+```
+
+Он проверяет `plan → prepare/readback → rollback → immediate plan` на
+`upo_test / фс_ДоработкиОбщее / Catalog.Номенклатура`. После rollback не
+должно остаться saved-state строк, а повторный план должен быть `plan_ready`.
+
+### Safe adapter deployment
+
+Перед Docker-обновлением скрипт развёртывания запрашивает `/health` и ждёт
+`runtime.state=ready` и `runtime.active_rpc_count=0`. При остановке REST
+переходит в `draining`; уже начатые запросы продолжают выполняться до пяти
+минут. Не используйте `-SkipDrainCheck`, кроме аварийного случая, когда
+ответственный подтвердил отсутствие активной записи.
+
+После обновления проверяются REST `/health?base_id=upo_test` и MCP `/health`.
+JSONL-аудит REST хранится в `/data/adapter-audit.jsonl`, MCP — в
+`/data/mcp-audit.jsonl`; оба периодически сворачиваются в
+`/data/adapter-audit-reports/latest.json` на соответствующем хосте.
+
 Если фрагмент повторяется, агент должен передать более узкий контекст
 (`routine_name`) или заменить процедуру целиком. Адаптер в такой ситуации
 возвращает `ambiguous_fragment`, `scope` и `counts.occurrences`, и не