← к элементу · к схеме
Гайд Архитектора ADB
| Продукт | ai_docs_broker |
|---|
| Контур | dev |
|---|
| Тип документа | Гайд Архитектора |
|---|
| Координаты чтения | {"op": "get_document", "env": "dev", "product": "ai_docs_broker", "doc_type": "Гайд Архитектора", "latest": true} |
|---|
| Версия | v0.20 |
|---|
| SHA-256 | 04ad62519b8fe88dddc12a818ef097a03ad32b13b4c2c93cf566b03f2dba858a
сверено
|
|---|
| Размер | 71892 байт |
|---|
Полный текст
# ai_docs_broker: Гайд Архитектора v0.20
## §CHANGELOG v0.20 относительно v0.19 (2026-09-21)
Полная новая редакция по прямому поручению Оператора об очистке битых документных ссылок. Исправлены подтверждённые действующие адреса: Гайд UEPR принадлежит prod/adb_meta, а не prod/ai_docs_broker; в процедуре закрытия дополнительно исправлена среда Онтологии h2_shared на dev и шаблон пользовательского гайда на prod. Для этой редакции заменено 1 JSON-ссылок/шаблонов (1 UEPR, 0 Онтология); изменения не отменяют требований документов.
Разрешимые ссылки заменены проверенными каноническими адресами, а не удалены вместе с нужной зависимостью. Неактивная история и датированные доказательства сохранены без подмены наблюдений. Архив ADB не запрашивался и не изменялся. Исправление документации не означает внедрение нового guard, исправление runtime, повторную валидацию продукта или восстановление недоступных файлов других записей.
## §CHANGELOG v0.19
Полная редакция после независимого холодного старта. Учтён фактический дрейф ЖЦ к v0.5, исправлен порядок wheel_id до установки/LS; живые разрешения не расширены. Исторические приложения сохранены побайтно.
## Сверка изменившегося ЖЦ перед итогом
19.09.2026 в 09:08:18Z получен и прочитан изменившийся норматив:
`{"op":"get_document","env":"prod","product":"adb_meta","doc_type":"Гайд ЖЦ ИТ-продукта H2","latest":true}`.
Evidence этого чтения: version v0.5, SHA
`8dfe5c49ad14836c02f27fa6f46cd9f7d42e5ae49d87970eb9c29dafe4201c9f`,
17497 байт; зарегистрирован владельцем нормы 09:00:00.620Z.
Изменены шаги 5/9/13: первичная регистрация артефакта выполняется до установки
и зачётного Live Scenario; после LS и ai_validation завершается учёт release.
Прежнее противоречие порядка wheel_id больше не является нормативным блокером.
Оно не заменено фиктивным успехом: эта сессия не регистрировала wheel/deploy/run
и не устанавливала a30. TD-2026-09-19-04 остаётся OPEN по фактической цепочке.
Остальные нормы, в том числе конфликт dev/prod Гайда Пользователя, не изменены.
Прежние ссылки на v0.4 внутри датированных наблюдений и истории описывают прошлое,
а не текущую инструкцию.
## Статус публикации
Редакция `v0.19` одобрена Оператором 19.09.2026 для регистрации. Это полный документ, не черновик на согласование. Его регистрация подтверждается ответом ADB и контрольным скачиванием текущей версии с проверкой SHA и размера; собственный будущий ID здесь не предполагается. Разрешение касается только документации и независимой read-only проверки нового ИИ-Арха. Установка a30, изменение runtime, секретов и данных, регистрация wheel/deploy/прогонов не разрешены. Приёмка продукта BLOCKED.
Исторический родитель: version `v0.17`, SHA `6b7da6f6fb5d38406045061c157380bed73181551914844e83876cf947525518`. Координаты latest ниже предназначены для текущей редакции, а не поиска родителя.
## §CHANGELOG v0.18
Документные ссылки заменены полными координатами ADB; текущие утверждения отделены от исторических; редакция одобрена для регистрации. Прежние измерения не объявлены новыми.
## Координаты документов в ADB
Любое упоминание документа ниже разрешается через эту таблицу, а не через имя локального файла, старый ID или прямой Files URL. Запросы показывают business payload; полный actor добавляется по действующему гайду. После ответа сверить env/product/type/node, скачать тело по возвращённому owui_file_id, проверить SHA и размер и прочитать содержание. Сам Files download является транспортом после поиска в ADB, а не постоянной документной ссылкой.
| Документ | Координаты поиска |
|---|---|
| ai_docs_broker: Гайд Пользователя | `{"op":"get_document","env":"prod","product":"ai_docs_broker","doc_type":"Гайд Пользователя","latest":true}` |
| ai_docs_broker: Онтология | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Онтология","latest":true}` |
| ai_docs_broker: Гайд Архитектора | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Гайд Архитектора","latest":true}` |
| ai_docs_broker: Концепт Развития | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Концепт Развития","latest":true}` |
| ai_docs_broker: Live Scenario | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Live Scenario","latest":true}` |
| ai_docs_broker: Отчёт Валидации | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Отчёт Валидации","latest":true}` |
| ai_docs_broker: Аудит UEPR | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Аудит UEPR","latest":true,"node":"heavy02"}` |
| ai_docs_broker: UEPR | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"UEPR","latest":true,"node":"heavy02"}` |
| adb_meta: Закрытие сессии ИИ-Арх | `{"op":"get_document","env":"prod","product":"adb_meta","doc_type":"Закрытие сессии ИИ-Арх","latest":true}` |
| ai_docs_broker: Стандарт (Техдолг) | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Стандарт","version":"tech-debt-log-v48.3"}` |
| ai_docs_broker: Дорожная Карта | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Дорожная Карта","latest":true}` |
| ai_docs_broker: Онбординг | `{"op":"get_document","env":"prod","product":"ai_docs_broker","doc_type":"Онбординг","latest":true}` |
| adb_meta: Гайд UEPR | `{"op":"get_document","env":"prod","product":"adb_meta","doc_type":"Гайд UEPR","latest":true}` |
| ai_docs_broker: Гайд Аудита | `{"op":"get_document","env":"prod","product":"ai_docs_broker","doc_type":"Гайд Аудита","latest":true}` |
| adb_meta: Гайд ЖЦ ИТ-продукта H2 | `{"op":"get_document","env":"prod","product":"adb_meta","doc_type":"Гайд ЖЦ ИТ-продукта H2","latest":true}` |
| adb_meta: Письмо-открытка ии-арх ПерпКомп для онбординга | `{"op":"get_document","env":"prod","product":"adb_meta","doc_type":"Письмо-открытка ии-арх ПерпКомп для онбординга","latest":true}` |
| ai_validation: Гайд Пользователя | `{"op":"get_document","env":"prod","product":"ai_validation","doc_type":"Гайд Пользователя","latest":true}` |
Техдолг: указан точный адрес согласованной серии tech-debt-log-v48.3 этого комплекта; актуальность подтверждается ADB, не именем файла. Для нового current сначала выполнить `{"op":"list_documents","env":"dev","product":"ai_docs_broker","doc_type":"Стандарт","limit":100,"offset":0}`, прочитать все страницы, выбрать именно серию tech-debt-log и затем запросить её точную version. Не подменять её contour-binding и не выбирать по максимальному id. При неоднозначности отметить GAP; не придумывать параметр series или version_prefix.
Версии и SHA в старых измерениях являются provenance этого измерения. Ни координаты latest, ни текст новой редакции не делают старые измерения свежими. Ссылки на сессии, API endpoint-шаблоны, пути исходников и имена первичных JSON/test evidence не являются ссылками на документы ADB. Их доступность проверяется отдельно; локальный путь не считается доказательством доставки новому исполнителю.
Полный LS и встроенная инструкция установки входят в тела соответствующих документов. Перед использованием подтвердить эту версию через ADB и проверить SHA; никаких отдельных локальных .md для продолжения не требуется.
## Рамки этой редакции
Полная редакция принята Оператором для публикации 19.09.2026. Дата среза: 19.09.2026; свежесть отдельных
наблюдений указана в evidence, а не заменена датой сборки документа.
Действующий runtime: a26, dev / heavy02, deploy96 / wheel109.
Кандидат a30 имеет отдельную офлайн-приёмку и НЕ установлен.
Отсутствие prod deploy при dev_only является N/A, а не аварией.
Опубликованный UEPR описывает a26; новые правки этого комплекта одобрены для публикации. products_state отдельно не изменялся; аттестация BLOCKED.
Разрешены чтение, безопасная диагностика, файлы, OWUI Files и agent_work_log. Оператор отдельно разрешил публикацию документов этого комплекта.
Запрещены без отдельного разрешения установка, restart/stop, миграции, изменение
кода или конфигурации узла, регистрация wheel/deploy/прогонов,
deprecate/retire/cleanup и удаление данных. Тест с env=dev не становится безопасным
сам по себе. Примеры WRITE ниже являются описанием, не командой к исполнению.
Фрагменты запросов сокращены: к каждому добавляется actor по полному контракту.
Текущие нормативы получают по (env,product,doc_type,latest=true), SHA проверяют
при скачивании. ID/версии/SHA родителей ниже нужны для provenance, не для вечного
выбора current. Приложенная история никогда не является действующей инструкцией.
Родитель: id=586; версия=v0.16-consolidated; SHA-256 `e48c72ab3c11c97ac14da4655c77a94a79e150b42cac7fd7848156aafdb2abed`.
## Изменения этой полной редакции
Заменены §6, §7.1/7.3/7.5, §8; исправлены actor/READ/bootstrap и состояние runtime. Убран SQL-обход. Полный прежний каталог и история сохранены; старые отчёты не переаттестованы.
**Дата:** 2026-09-19
**Продукт:** ai_docs_broker
**Наблюдаемый runtime:** dev a26 / heavy02 / deploy96 / wheel109; prod отсутствует.
**Непосредственный родитель:** v0.16-consolidated (doc_id=586)
**Кумулятивно к:** v0.7 → v0.12 → v0.13..v0.15 (весь arch-каталог собран заново, не delta).
**Основание пересборки:** Дор Карта v0.41 §NEW-1 (расщепление гайдов), TDL v40 TD-2026-09-16-07 (T-DOCS-DELTA-BAN).
**Правило гайда.** Этот гайд — только про то, что делает **ИИ-Архитектор ADB** или системный оператор. Всё пользовательское (простой минимум, жизненный цикл сборки, работа с документами) — в актуальном Гайде Пользователя; получать его по prod-координатам из таблицы; не закреплять старую версию.
Каталог ниже сохраняет 29 ранее описанных arch-op. Это не заявление о полном числе текущих операций; актуальный перечень сверяется с кодом и фасадом.
---
## §1. Категории
- **§2 arch_audit_history** — 6 op. Аудит: кто, что, когда с сущностями делал.
- **§3 arch_validation** — 5 op. Прогоны LS и валидаторов; смена review_status документа.
- **§4 arch_node_inventory** — 16 op. Инвентарь узлов: регистрация, конфиги, JSON-манифесты, состояние.
- **§5 arch_debug** — 2 op. Отладка транспорта.
Каждая категория — свой §. Общие стандарты (актор, версии, ошибки) — §7.
---
## §2. arch_audit_history — Аудит и история (6 op)
### 2.1 `list_caller_events` — аудит вызовов
Обязательны `env/product`, но это контекст запроса, не WHERE-изоляция событий.
Таблица caller_events не хранит эти две колонки. Для отбора передайте объект
`filters` с `actor_product/actor_node/actor_session_type/actor_session_id/op/`
`result_status/since/until`. Legacy principal/HMAC-поля не задают авторизацию.
Параметры `limit` (до500), `offset`, `cursor`, `order`,
`include_payload_hash` находятся сверху. Cursor имеет приоритет над offset.
Ответ: `data.rows` и алиас `data.events`, `count/total/has_more/next_cursor`.
Без since/until берётся окно последних24часов; это не вся история.
### 2.2 `who_touched` — аудит сущности
Передаётся ровно один из `document_id` или `product_state_id`, опционально
`limit<=100`; actor обязателен. Ответ `data.touches/pre_hmac_count`.
`entity_type/entity_id` не являются текущим контрактом.
### 2.3 `list_audit_snapshots` — снимки автоаудита
`env` обязателен, `limit` и `since` опциональны. Product-фильтра нет.
Ответ `data.snapshots/count/limit`.
### 2.4 `list_document_archive` — архив документов
**Зачем:** все версии документа, включая архивные (deprecated).
**Пример:**
```json
{"op":"list_document_archive","env":"prod","product":"ai_docs_broker","doc_type":"Гайд Пользователя","limit":50}
```
**Ответ:** `archive[]` — каждая запись с `{archive_id, orig_id, version, sha256, uploaded_at, archived_at, archived_by, retired_reason, archive_reason}`.
### 2.5 `get_document_from_archive` — чтение архивной версии
Обязательны `env/archive_id`. Ответ: поля архивной записи непосредственно в
`data`, не `data.row/text`. Тело и owui_file_id этой проекцией не гарантированы:
в read-only ответе archive597 были метаданные и SHA, но не ссылка на тело.
Если owui_file_id отсутствует, найдите его в проверяемом историческом манифесте
или другом доверенном файловом реестре; скачайте тело через Files API и сравните
байтовый SHA с архивом. filename сам по себе не идентификатор файла.
Отсутствующая запись даёт `E_ARCHIVE_NOT_FOUND`.
### 2.6 `full_state_report` — срез состояния
Опциональны `env/product/node/doc_type/include_archives/include_nodes/`
`include_products_state`. Без `include_nodes=true` секция nodes не добавляется;
`products_registry` и `active_deploys` добавляются всегда. Это диагностический
срез, а не UEPR и не доказательство runtime.
## §3. arch_validation — Прогоны и статусы (5 op)
### 3.1 `register_live_scenario_run` — регистрация LS, WRITE
`env/product/scenario_name/scenario_version/status/started_at`; опционально
`wheel_id/passed/failed/total/finished_at/evidence_url/comment`.
Status: green/red/partial/running. Полей `ls_version`, заданного клиентом
`run_id` и `run_by` нет. total должен быть >0 для GREEN.
### 3.2 `list_live_scenario_runs` — история прогонов LS
**Пример:**
```json
{"op":"list_live_scenario_runs","env":"prod","product":"ai_docs_broker","limit":20}
```
### 3.3 `register_validation_run` — регистрация валидатора, WRITE
`env/product/validator/status/started_at`; опционально
`wheel_id/passed/failed/total/finished_at/evidence_url/comment`.
Status: green/red/yellow/running. Не использовать `validator_name` или `run_by`.
### 3.4 `list_validation_runs` — история прогонов валидатора
Фильтры `env/product/validator/status/limit`. Поле называется `validator`, не
`validator_name`. Ответ `data.runs`, `data.counts.runs`.
```json
{
"op": "list_validation_runs",
"env": "dev",
"product": "ai_docs_broker",
"validator": "aval",
"limit": 20
}
```
### 3.5 `set_review_status` — статус review, WRITE
`env/product/doc_id/review_status`, опционально comment. Допустимы
pending/approved/rejected/needs_changes. Значений draft и reviewed_by в
текущем контракте нет.
## §4. arch_node_inventory — Инвентарь узлов (16 op)
### 4.1 `register_node` — регистрация узла, WRITE
`node_id/class/purpose/registered_by`; опционально status/is_test_node/comment,
а `env/product` используются для soft-check. class: heavy/light/laptop.
Это не поля node/kind.
### 4.2 `register_node_config` — профиль узла, WRITE
`env/node`; опционально `node_json/hardware_json/os/os_version/hostname/`
`is_test_node/merge`. Полей config_json и uploaded_by нет.
### 4.3 `get_node_profile` — профиль узла
Обязательны `env/node`. Ответ: `data.node`, `data.products_state`,
`data.active_deploys`, `data.credentials` (после удаления HMAC пустой список).
Обёртки `profile` нет. В frozen a30 products_state и active_deploys здесь
выбираются для узла без env-фильтра: среду каждой записи проверять отдельно.
### 4.4 `retire_node` — вывод узла, WRITE
Обязательны `env/node`, опциональны `reason/archived_by`.
Это не `retired_reason/retired_by`. Ответ: `data.row/archive_id/new_id`.
Узел становится retired с архивным снимком; повтор даёт `E_ALREADY_RETIRED`.
В этом поручении вызов запрещён.
### 4.5 `sync_node_from_node_json` — синхронизация, WRITE
Только `env/node_id` (registered_by опционален). Канонический файл берётся через
сохранённый node_json_ref, скачивается, проверяется и затем обновляет профиль.
Не передавайте сырой node_json в эту операцию.
### 4.6..4.14 `register_*_json` — JSON-поля узла, WRITE
Для access/accounts/autostart/firewall/node_json_ref/registry/
secrets_manifest/watchdogs канонический конверт:
`env/node_id/payload` (объект), опционально `comment/archive_always`.
Это не `node/<name>_json/uploaded_by`. `register_canonical_node_json` имеет
отдельный контракт: `env/node_id/owui_file_id/sha256/filename/uploaded_by`,
опционально comment/allow_overwrite; брокер скачивает и валидирует 7 секций.
Для wire-конверта используйте `{op, params:{env,node_id,payload}, actor}`.
Поле business payload нельзя класть рядом с op: `_split_envelope` считает
такое поле внешней обёрткой. Пример сокращённого конверта (полный actor
добавляется рядом с op и params, НЕ внутрь inventory payload):
```json
{
"op": "register_firewall_json",
"params": {
"env": "dev",
"node_id": "heavy02",
"payload": {
"rules": []
}
}
}
```
### 4.15 `register_product_state` — состояние продукта, WRITE
Обязательны `env/product/node/product_version/state`; опционально
wheel_version/wheel_path/is_development_wheel/comment. Авторство берётся из
actor. state физически кодируется в comment текущей схемы; не обещайте отдельную
колонку state.
### 4.16 `product_readiness_report` — реестровый отчёт готовности
Обязательны `env/product`. Ответ непосредственно в `data`:
`product_meta/active_deploys/last_validation_run/last_live_scenario_run/`
`recent_documents/readiness_score/signals`. Обёртки report нет.
Его green означает наличие active deploy и последних GREEN-записей двух
реестров, но не проверяет всю release-specific цепочку ЖЦ и не заменяет приёмку.
## §5. arch_debug — Отладка транспорта (2 op)
### 5.1 `echo` — smoke-тест
Передайте `{"op":"echo","params":{"payload":{"message":"ping"}}}`,
добавив полный actor на уровень op/params. Не размещайте business payload
на верхнем уровне: `_split_envelope` воспримет его как внешний конверт
и потеряет соседние actor/params. Ответ: `data.echo`, `data.at`, `data.node`;
message в примере читается как `data.echo.message`, не `data.message`.
### 5.2 `rotate_node_credential` — заглушка HMAC-remove
**Статус:** заглушка, всегда возвращает `E_OP_REMOVED` (HMAC удалён в 0.9.0a9, миграция 033). Оставлена для обратной совместимости старых клиентов.
---
## §6. Реестр типов документов
Семейство операций: list_doc_types, register_doc_type, deprecate_doc_type,
update_document_description. Старое утверждение «все четыре всегда E_UNKNOWN_OP»
не является актуальным результатом: source-проверка части фасада дала PARTIAL,
сквозная матрица четырёх операций остаётся в TD-2026-09-16-01.
Прямой SQL не является обходом отказа фасада и в этой работе запрещён.
Канонический doc_type берётся из ADB; имена не переводятся в lowercase при чтении.
## §7. Стандарты и правила
### 7.1 Контракт actor
Actor передаётся JSON-объектом во всех операциях, включая READ и get_document.
Поля: product, node, product_version, session_type, session_id, request_id, emitted_at, source_url.
Только bootstrap get_document допускает отсутствие product_version, но не всего actor.
Версия actor берётся из SHA-проверенного тела UEPR по порядку действующего Онбординга,
а не из metadata.version документа, health или предположения о кандидате.
Если канонический UEPR ещё описывает a25, это отдельно объявленное расхождение с runtime a26.
Для service, roo, owui и perplexity source_url обязателен и содержит действительный
полный URL сессии-инициатора. session_id является каноническим UUID текущего
исполнителя; request_id новый на каждый вызов; emitted_at имеет UTC ISO-8601 milliseconds Z.
Идентичность роли задаётся (product,node). Principal не передаётся, legacy principal
игнорируется; uploaded_by/deprecated_by формируются как product@node.
HMAC снят; hmac_phase и caller_kind не являются обязательными клиентскими полями.
Это контракт идентичности, а не разрешение изменять данные или обходить права операций.
### 7.2 Кумулятивная эволюция документов (норма и механизм)
ИИ-Арх хранит и предлагает к регистрации полный текст нормативного документа,
с честным CHANGELOG; delta не считается полноценным артефактом. Но frozen a30
удаляет прежние механические cumulative/trivial guards, поэтому конкретный
`E_DELTA_NOT_CUMULATIVE` не обещается. Содержательная LLM-проверка, правила
CHANGELOG и некомулятивных типов остаются VERIFY_REQUIRED. Нельзя запускать
WRITE только для выяснения поведения без отдельного разрешения.
### 7.3 Версии
Версия пакета и actor.product_version имеют PEP-440, например 0.9.0a26.
Версия документа может быть иной строкой и не подменяет версию пакета.
Старое обещание «будет исправлено в a13» снято: поведение applies_to_version_range
проверяется отдельно как TD-2026-09-16-04. Не утверждать закрытие по номеру версии.
### 7.4 Ошибки (по фактическому ответу)
Проверяйте `status/error/error_code/errors` фактического конверта. Примеры кодов
frozen a30: `E_OP_REMOVED`, `E_NODE_NOT_FOUND`, `E_ALREADY_RETIRED`,
`E_ARCHIVE_NOT_FOUND`, `E_CANONICAL_SCHEMA_INVALID`. Прежние
`E_NODE_NOT_REGISTERED/E_JSON_MANIFEST_INVALID/E_STATE_INCONSISTENT` не
считать гарантированными кодами этих операций.
### 7.5 Инварианты
Host-level node.json задаёт конфигурацию узла; реальный путь подтверждается на узле.
Имена новых продуктов lower_snake_case. Найденные legacy-case записи не удаляются.
Наличие нескольких «Стандарт» не означает дубликат: tech-debt-log и контурный
стандарт являются разными сериями. current выбирается канонически, не эвристикой.
Нельзя утверждать отсутствие дубликатов без полного inventory: свежая классификация
сохранена в evidence/inventory. Полное тело документа и содержательный changelog
обязательны; наличие простого delta-validator не доказывает LLM-проверку changelog.
HMAC снят; подтверждение auth не заменяет разрешение на бизнес-WRITE.
## §8. Начало работы архитектора
1. Соблюсти действующий обязательный онбординг; отдельный START_HERE не требуется.
2. Bootstrap get_document UEPR по dev/ai_docs_broker/heavy02 с actor без product_version.
3. Скачать тело, сверить SHA, извлечь версию из тела; начать журнал до Онбординга.
4. get_document prod/ai_docs_broker/«Онбординг» latest=true, SHA и реальное чтение.
5. После обязательного журналирования получить health, active deploy dev и prod,
onboard и необходимые документы по координатам; готовность onboard не равна GREEN.
6. list_products_state передавать с обязательными product и node.
7. Получить все страницы list_live_scenario_runs и list_validation_runs нужного env.
8. Прочитать текущие части Дорожной карты и Техдолга: границы, состояние, очередь и первый безопасный шаг. Сверить их с UEPR и манифестом имеющегося пакета; не закрывать задачи по историческим GREEN.
## CHANGELOG v0.17
Исправлены текущие API-контракты, actor/bootstrap и границы a26/a30. Полный прежний changelog сохранён только в неактивном родителе. Прямой SQL не является разрешённым обходом фасада.
## Журнал работы и закрытие
До чтения Онбординга записать start_session/started и start_get_onboarding/started.
После скачивания и SHA: end_get_onboarding/ok; после чтения: end_read_onboarding/ok.
Использовать ту же OWUI Function; entry содержит все известные target_product,
target_node, target_env, task_id, task_url, document_id/type/version/sha256/section
и occurred_at в UTC ISO-8601 milliseconds Z. Неизвестные значения не выдумывать.
Lowercase применяется только к машинным меткам env, actor.product/node/session_type,
verb/status, target_product/node/env и document_type записи журнала.
Регистр UUID, URL, task_id, document_version, SHA, document_section, remarks и
временных меток сохраняется. В get_document doc_type канонический, например «Онбординг».
Перед final прочитать все страницы list_agent_work_log с filters.actor_session_id
текущего канонического UUID; проверить env и отсутствие error. Последняя запись:
verb=final,status=ready. Отказ журнала: одна error при возможности и STOP, без retry.
Записи задним числом запрещены. final/ready означает готовность результата задачи,
а не автоматический GREEN продукта.
## Релиз, установка и критерии GREEN
Цепочка по действующему ЖЦ: frozen source → release manifest и wheel SHA →
разрешённая загрузка и регистрация артефакта с собственным wheel_id →
одобренная установка в существующий единственный runtime → runtime proof →
Guide–Runtime Parity → полный LS с наблюдением → независимый ai_validation →
завершение учёта release/deploy/product state и результатов приёмки → UEPR и аудит.
Первичная регистрация артефакта не означает успешную валидацию или GREEN.
Документ с частичным результатом не отменяет ни одного обязательного шага.
Runtime proof содержит observed_at, product, env, node, release_id, sys_executable,
module_file, package_version, wheel_sha256. Отдельно фиксируются служба, PID,
командная строка, пути и не-editable установка, соответствие файлов wheel RECORD.
Диагностический импорт не выдается за чтение памяти работающего процесса.
Анализ памяти не является дополнительным придуманным обязательным гейтом.
SHA wheel-архива сравнивается с архивом, а файлы пакета с соответствующими членами.
Установка кандидата и перезапуск в этой задаче НЕ выполняются. План установки и
rollback включены в Гайд Пользователя, раздел «Установка и откат a30» (координаты в таблице); перед исполнением
нужны разрешение, актуальный preflight, проверка backup и security.
ЖЦ теперь требует зарегистрировать артефакт после manifest и до установки/LS.
Для кандидата получить его собственный wheel_id и связать с SHA/release manifest;
ID a26 нельзя подставлять a30. Нормативная часть TD-2026-09-19-04 разрешена,
но permission, регистрация кандидата и вся живая цепочка остаются NOT_RUN.
Три независимые оценки:
-_PACKAGE: комплект полон, непротиворечив, SHA/ссылки/хронология проверены.
- OFFLINE_WHEEL: конкретный wheel связан с source и успешными офлайн-тестами.
- INSTALLED_RUNTIME_LIFECYCLE: все обязательные живые гейты пройдены на одном релизе.
Первые две не подменяют третью. Skip/NOT_RUN не считается PASS; total обязан быть >0.
## ИСТОРИЯ: точное полное тело родителя, НЕ АКТИВНО
Ниже сохранена прежняя версия для проверки кумулятивности. Старые actor, principal, HMAC, разрешения, версии, результаты и команды не исполняются.
# ADB Гайд Архитектора v0.16-consolidated
**Дата:** 2026-09-16
**Продукт:** ai_docs_broker
**Prod-версия:** 0.9.0a12 (heavy02, deploy_id=55)
**Родитель:** v0.15 (doc_id=520)
**Кумулятивно к:** v0.7 → v0.12 → v0.13..v0.15 (весь arch-каталог собран заново, не delta).
**Основание пересборки:** Дор Карта v0.41 §NEW-1 (расщепление гайдов), TDL v40 TD-2026-09-16-07 (T-DOCS-DELTA-BAN).
**Правило гайда.** Этот гайд — только про то, что делает **ИИ-Архитектор ADB** или системный оператор. Всё пользовательское (простой минимум, жизненный цикл сборки, работа с документами) — в Гайде Пользователя v0.30.
**Всего arch-op в этом гайде:** 29 из 50 в prod. Остальные 21 — в Гайде Пользователя v0.30.
---
## §1. Категории
- **§2 arch_audit_history** — 6 op. Аудит: кто, что, когда с сущностями делал.
- **§3 arch_validation** — 5 op. Прогоны LS и валидаторов; смена review_status документа.
- **§4 arch_node_inventory** — 16 op. Инвентарь узлов: регистрация, конфиги, JSON-манифесты, состояние.
- **§5 arch_debug** — 2 op. Отладка транспорта.
Каждая категория — свой §. Общие стандарты (актор, версии, ошибки) — §7.
---
## §2. arch_audit_history — Аудит и история (6 op)
### 2.1 `list_caller_events` — аудит вызовов
**Ключевые поля запроса:**
- `env`, `product` (**обязателен**, TDL TD-2026-09-16-02).
- `caller_kind`, `principal`, `op`, `since`, `until` — фильтры.
- `limit`, `offset` — пагинация.
**Пример:**
```json
{"op":"list_caller_events","env":"prod","product":"ai_docs_broker","limit":50}
```
**Ответ:** `rows[]` с `{id, ts, product, node, op, caller_kind, principal, session_type, session_id, source_url, hmac_phase, params_digest, result_status}`.
### 2.2 `who_touched` — кто менял сущность
**Ключевые поля:** `env`, `entity_type` (`document`/`wheel`/`deploy`/`node`/`product`), `entity_id`.
**Пример:**
```json
{"op":"who_touched","env":"prod","entity_type":"document","entity_id":562}
```
**Ответ:** `events[]` — все аудит-события, затронувшие сущность, хронологически.
### 2.3 `list_audit_snapshots` — снапшоты аудита
**Зачем:** периодические слепки состояния для последующего сравнения.
**Пример:**
```json
{"op":"list_audit_snapshots","env":"prod","product":"ai_docs_broker","limit":20}
```
**Ответ:** `rows[]` — метаданные снапшотов.
### 2.4 `list_document_archive` — архив документов
**Зачем:** все версии документа, включая архивные (deprecated).
**Пример:**
```json
{"op":"list_document_archive","env":"prod","product":"ai_docs_broker","doc_type":"Гайд Пользователя","limit":50}
```
**Ответ:** `archive[]` — каждая запись с `{archive_id, orig_id, version, sha256, uploaded_at, archived_at, archived_by, retired_reason, archive_reason}`.
### 2.5 `get_document_from_archive` — чтение архивной версии
**Ключевые поля:** `env`, `archive_id`.
**Пример:**
```json
{"op":"get_document_from_archive","env":"prod","archive_id":801}
```
**Ответ:** `row` + опционально `text` архивного документа.
### 2.6 `full_state_report` — полный отчёт состояния
**Зачем:** снапшот всего состояния ADB на один момент (продукты, wheel'ы, деплои, документы, узлы).
**Пример:**
```json
{"op":"full_state_report","env":"prod"}
```
**Ответ:** `state.{products, wheels, deploys, documents, nodes}` — агрегированный отчёт.
**Используйте:** для еженедельного snapshot'а, для передачи состояния другому ИИ-Арх.
---
## §3. arch_validation — Прогоны и статусы (5 op)
### 3.1 `register_live_scenario_run` — фиксация прогона LS
**Обязательные поля:** `env`, `product`, `ls_version`, `run_id`, `steps_total`, `steps_green`, `steps_red`, `evidence_url`, `run_by`.
**Пример:**
```json
{
"op":"register_live_scenario_run","env":"prod","product":"ai_docs_broker",
"ls_version":"v0.15","run_id":25,"steps_total":110,"steps_green":110,"steps_red":0,
"evidence_url":"owui://file/...","run_by":"andy.krivenko@gmail.com"
}
```
### 3.2 `list_live_scenario_runs` — история прогонов LS
**Пример:**
```json
{"op":"list_live_scenario_runs","env":"prod","product":"ai_docs_broker","limit":20}
```
### 3.3 `register_validation_run` — фиксация прогона валидатора
**Обязательные поля:** `env`, `product`, `validator_name`, `wheel_id`, `passed`, `failed`, `evidence_url`, `run_by`.
**Пример:**
```json
{
"op":"register_validation_run","env":"prod","product":"ai_docs_broker",
"validator_name":"aval","wheel_id":76,"passed":48,"failed":0,
"evidence_url":"owui://file/...","run_by":"andy.krivenko@gmail.com"
}
```
### 3.4 `list_validation_runs` — история прогонов валидатора
**Пример:**
```json
{"op":"list_validation_runs","env":"prod","product":"ai_docs_broker","validator_name":"aval"}
```
### 3.5 `set_review_status` — смена review_status документа
**Ключевые поля:** `env`, `doc_id`, `review_status` (`draft`/`approved`/`rejected`), `reviewed_by`.
**Пример:**
```json
{
"op":"set_review_status","env":"prod","doc_id":562,
"review_status":"approved","reviewed_by":"andy.krivenko@gmail.com"
}
```
---
## §4. arch_node_inventory — Инвентарь узлов (16 op)
### 4.1 `register_node` — регистрация нового узла
**Обязательные поля:** `env`, `node`, `kind` (`vps`/`workstation`/`edge`), `registered_by`.
### 4.2 `register_node_config` — конфиг узла
**Ключевые поля:** `env`, `node`, `config_json` (raw JSON), `uploaded_by`.
### 4.3 `get_node_profile` — профиль узла
**Пример:**
```json
{"op":"get_node_profile","env":"prod","node":"heavy02"}
```
**Ответ:** `profile.{node, kind, active_deploys, last_json_manifests, last_seen_at}`.
### 4.4 `retire_node` — вывод узла
**Ключевые поля:** `env`, `node`, `retired_reason`, `retired_by`.
### 4.5 `sync_node_from_node_json` — синк из node.json
**Зачем:** одним вызовом синхронизировать все 9 JSON-манифестов узла из host-level `node.json` (SSOT по H2_SHARED_ONTOLOGY v1.7.8).
**Ключевые поля:** `env`, `node`, `node_json` (полный содержимое `node.json`), `synced_by`.
### 4.6..4.14 `register_*_json` — 9 JSON-манифестов узла
Все имеют одинаковую сигнатуру `{env, node, <name>_json, uploaded_by}`:
- **`register_access_json`** — `access.json` (входы для СС).
- **`register_accounts_json`** — `accounts.json` (учётки узла).
- **`register_autostart_json`** — `autostart.json` (что стартует автоматически).
- **`register_canonical_node_json`** — canonical `node.json` (SSOT).
- **`register_firewall_json`** — `firewall.json` (правила фаервола).
- **`register_node_json_ref_json`** — ссылки на JSON'ы узла (метамодель).
- **`register_registry_json`** — `registry.json` (реестр).
- **`register_secrets_manifest_json`** — манифест секретов (без самих секретов).
- **`register_watchdogs_json`** — `watchdogs.json` (мониторы).
**Пример:**
```json
{
"op":"register_firewall_json","env":"prod","node":"heavy02",
"firewall_json":{"rules":[...]},"uploaded_by":"andy.krivenko@gmail.com"
}
```
### 4.15 `register_product_state` — состояние продукта на узле
**Ключевые поля:** `env`, `product`, `node`, `state` (`ready`/`degraded`/`down`/`unknown`), `reported_by`.
### 4.16 `product_readiness_report` — отчёт готовности продукта
**Пример:**
```json
{"op":"product_readiness_report","env":"prod","product":"ai_docs_broker"}
```
**Ответ:** `report` со списком узлов, состоянием на каждом, отсутствующими документами / деплоями.
---
## §5. arch_debug — Отладка транспорта (2 op)
### 5.1 `echo` — smoke-тест
**Пример:**
```json
{"op":"echo","message":"ping"}
```
**Ответ:** `data.message='ping'`. Используется, чтобы проверить, что фасад отвечает и актор-подмешивание работает.
### 5.2 `rotate_node_credential` — заглушка HMAC-remove
**Статус:** заглушка, всегда возвращает `E_OP_REMOVED` (HMAC удалён в 0.9.0a9, миграция 033). Оставлена для обратной совместимости старых клиентов.
---
## §6. Doc-types реестр (не через фасад, см. TDL TD-2026-09-16-01)
**Проблема (TD-2026-09-16-01):** OWUI-фасад `_KNOWN_OPS_P3` **не пускает** 4 op из doc_types-реестра:
- `list_doc_types`
- `register_doc_type`
- `deprecate_doc_type`
- `update_document_description`
Все возвращают `E_UNKNOWN_OP`. Пока не поправлен (планируется 0.9.0a13), управление реестром doc_types идёт через прямой SQL в БД `doc_types`. Схема:
```sql
CREATE TABLE doc_types (
id INT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(64) UNIQUE,
description TEXT,
is_cumulative BOOLEAN DEFAULT FALSE,
deprecated_at TIMESTAMP NULL,
...
);
```
**Правило:** новые doc_type вносятся ИИ-Арх через SQL с записью в аудит-снапшот. После 0.9.0a13 — через штатные 4 op.
---
## §7. Стандарты и правила
### 7.1 Актор (обязателен на всех WRITE-op)
9 полей — те же, что в Гайде Пользователя v0.30 §5.1:
- `product`, `node`, `product_version`
- `session_type`, `principal`, `source_url`
- `hmac_phase`, `session_id`, `caller_kind`
### 7.2 Кумулятивная эволюция документов (T-DOCS-14 + T-DOCS-DELTA-BAN)
Правила приёма — см. Гайд Пользователя v0.30 §5.5. ИИ-Арх дополнительно:
1. **Одноразовая консолидация исторических delta-версий** (TDL TD-2026-09-16-07 пункт 3). Скрипт `scripts/consolidate_documents.py` собирает полный кумулятивный текст из delta-цепочки и регистрирует новую версию с постфиксом `-consolidated`.
2. **LLM-проверка changelog** (см. Дор Карта v0.41 §NEW-5 + бриф ИИ-Кодеру от 2026-09-16 «поиск существующего LLM changelog-валидатора»): при регистрации новой кумулятивной версии LLM проверяет, что раздел «§CHANGELOG» реально отражает изменения от предыдущей версии, а не dummy-запись.
3. **Правило владения:** для кумулятивных документов ИИ-Арх обязан хранить полный текст в workspace и регистрировать целиком; delta-запись отклоняется брокером (`E_DELTA_NOT_CUMULATIVE`).
### 7.3 Версии — PEP-440
- `register_wheel.version` — без пре-дефиса: `0.9.0a12`, `0.0.1a1+ls62de9349`.
- `applies_to_version_range` — с дефисом (странность, будет исправлена в 0.9.0a13, TDL TD-2026-09-16-04): `>=0.9.0-a11`, `<1.0.0-0`.
### 7.4 Ошибки
**Arch-специфичные `error_code`:**
- `E_OP_REMOVED` — операция удалена (например, `rotate_node_credential` после HMAC-remove).
- `E_NODE_NOT_REGISTERED` — узел не зарегистрирован через `register_node`.
- `E_JSON_MANIFEST_INVALID` — JSON-манифест не проходит схему.
- `E_STATE_INCONSISTENT` — расхождение между `list_deploys` и `list_products_state`.
### 7.5 Инварианты платформы
Из H2_SHARED_ONTOLOGY v1.7.8 (SSOT — host-level `node.json`):
- **BROKER-14 = 0:** нет дубликатов по `(product, doc_type, version)` в case-insensitive проверке (миграция 014).
- **DEPLOY-HOOK:** каждый деплой продукта через `deploy_registration_hook.py` (h2_shared 0.57.0) автоматически вызывает `register_deploy(status='active')`; `uploaded_by='service:deploy_hook'` — идентификатор автомата.
- **HMAC-REMOVED:** после 0.9.0a9 никакой WRITE-op не требует HMAC-подпись; поле `hmac_phase='removed'` в акторе — маркер.
- **DOCS-DELTA-BAN (после 0.9.0a14):** валидатор `verify_cumulative_evolution_v2` не пропускает delta для 8 кумулятивных типов.
---
## §8. Что делать в первую очередь при принятии роли ИИ-Арх
1. `health(env=prod)` — сервис жив.
2. `full_state_report(env=prod)` — снапшот всего состояния.
3. `list_products_state(env=prod)` — какие продукты в каком состоянии.
4. `list_live_scenario_runs(product='ai_docs_broker', limit=5)` — последние прогоны LS.
5. `list_caller_events(product='ai_docs_broker', limit=50)` — свежий аудит.
6. `get_document(product='ai_docs_broker', doc_type='Дорожная Карта')` + `doc_type='Стандарт'` — открытые задачи и долги.
7. Читать `docs.*` из ответа `onboard(product='ai_docs_broker', include_texts=true)`, если это первый вход в проект.
---
## §CHANGELOG v0.16
**Пересборка целиком, кумулятивно к v0.7 → v0.12 → v0.13..v0.15.**
**Что изменилось vs v0.15:**
1. **Принят 29 arch-op**, вернувшихся из Гайда Пользователя (см. Дор Карта v0.41 §NEW-1). Новые категории §2..§5 полностью описывают все arch-op.
2. **§6 «Doc-types реестр»** — новый раздел про TDL TD-2026-09-16-01 (фасад не пускает doc_types-ops, обход через SQL).
3. **§7.2 «Кумулятивная эволюция»** — обновлено: правило T-DOCS-DELTA-BAN, LLM-проверка changelog, обязанность ИИ-Арх регистрировать целые тексты.
4. **§7.5 «Инварианты платформы»** — добавлен инвариант DOCS-DELTA-BAN.
5. **§8 «Что делать в первую очередь»** — обновлён порядок первых 7 вызовов при принятии роли ИИ-Арх.
**Закрыто внешним ходом:**
- §H-REMOVED из v0.15 (HMAC HARD-режим) — CANCELLED в Дор Карте v0.40, здесь не переносится.
§END v0.16
---
## §CONSOLIDATION
**Версия:** `v0.16-consolidated`. Полный кумулятивный текст для `Гайд Архитектора`. Актуальная версия `565` сохранена первой; ниже сохранены все доступные предыдущие версии этой линии для буквенной непрерывности секций. Это не delta-документ: нормативный актуальный текст находится выше, исторические снимки добавлены только для проверки эволюции.
## §HISTORICAL-PRESERVATION
### Исходная версия v0.13 (doc_id=415)
# ADB Гайд Архитектора v0.13
**Дата:** 2026-09-13
**Продукт:** ai_docs_broker
**Prod:** 0.9.0a6
**Родитель:** v0.12 (doc_id=415)
## Что нового в v0.13 (кумулятивно к v0.12)
- **§32 NEW** — Инвариант «имена продуктов — lower_snake_case».
- **§33 NEW** — Миграция 030: `utf8mb4_bin` для `product`-колонок.
- **§34 NEW** — Гейт `E_INVALID_PRODUCT_NAME` на входе write-op.
- Разделы §0..§31 v0.12 сохранены (кумулятивная эволюция T-DOCS-14).
---
## §32. Инвариант: имена продуктов
Все имена продуктов — `lower_snake_case` (`^[a-z][a-z0-9_]*$`). Валидация на
входе (`register_product` / `register_document` / `bulk_deprecate_documents`),
коллация `utf8mb4_bin` в БД. Регистровая case-sensitive проверка обязательна для
любого нового write-op, работающего с `product`-колонкой. См. Онтологию §2.1.
**Почему это важно для архитектора:** отсутствие явного контракта имён
допустило дефект 2026-09-13 — case-insensitive коллация `utf8mb4_unicode_ci`
привела к тому, что UPDATE/bulk-фильтр по `ai_Docs_broker` заматчил канонический
`ai_docs_broker` (брифы v10 §4, v11 §1). Любой новый bulk/UPDATE-код, работающий
с `product`, ОБЯЗАН либо полагаться на `utf8mb4_bin` (migration 030), либо
форсировать `BINARY` в сравнении.
## §33. Миграция 030 — case-sensitive collation
**Файл:** `ai_docs_broker/migrations/030_products_case_sensitive_collation.sql`.
```sql
-- products.product / documents.product / documents_archive.product → utf8mb4_bin
ALTER TABLE products MODIFY COLUMN product VARCHAR(128)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL;
ALTER TABLE documents MODIFY COLUMN product VARCHAR(128)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL;
ALTER TABLE documents_archive MODIFY COLUMN product VARCHAR(128)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL;
```
**Idempotency:** каждая `ALTER` выполняется динамическим guard-ом через
`INFORMATION_SCHEMA.COLUMNS` (пропуск, если коллация уже `utf8mb4_bin`).
**Порядок (критично):** перед применением обязательна проверка отсутствия
дубликатов по регистру среди активных записей — иначе смена CI→CS может дать
UNIQUE-конфликт. Проверка: группировка по `LOWER(product)` с `HAVING COUNT(*)>1`.
В prod на 2026-09-13 дубликатов нет (`case_variant_dupes=[]`).
**Rollback:** обратный `MODIFY ... COLLATE utf8mb4_unicode_ci` — безопасен, но
возвращает класс дефектов; применять только для аварийного отката.
## §34. Гейт `E_INVALID_PRODUCT_NAME`
Реализован в `ai_docs_broker/validation/product_name.py`:
```python
PRODUCT_NAME_RE = re.compile(r'^[a-z][a-z0-9_]*$')
def validate_product_name(name: str, *, field: str = "product") -> str:
if not isinstance(name, str) or PRODUCT_NAME_RE.match(name) is None:
raise InvalidProductName(name, field=field)
return name
```
**Применение:**
- `register_product` — до записи в БД (также для `parent`).
- `register_document` — валидация `params['product']`.
- `bulk_deprecate_documents` — валидация `filter.products[i]` и
`filter.product_pattern` (для pattern ослаблено: разрешены LIKE-метасимволы
`%` и `_`).
**Ошибка:** `E_INVALID_PRODUCT_NAME`, `class=validation`,
`data.field` = имя нарушившего поля.
**Новая операция `unmark_product`** (WRITE): снимает `deprecated`-маркер с
записи `products`. Фильтр — точное case-sensitive имя (`BINARY product=%s`).
Использована для восстановления §1 (collateral damage v10 §4).
## §35. Наблюдаемость
Число `@observable`-op: 52 → **53** (добавлена `unmark_product` в 0.9.0a6).
§END v0.13
### Исходная версия v0.14 (doc_id=482)
# ADB Гайд Архитектора v0.14
Delta vs v0.13. Остальное — без изменений.
## §35-NEW. Динамический реестр doc_types
### 35.1. Мотивация
До 0.9.0a8 `doc_type` был жёстко зашит в SQL ENUM из 9 значений. Любое расширение требовало миграции + пересборки wheel + деплоя. Задача — открыть реестр для пользовательской регистрации без релиза брокера.
### 35.2. Схема (миграция 031)
```sql
CREATE TABLE doc_types (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
env ENUM('dev','stage','prod') NOT NULL,
name VARCHAR(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL,
description VARCHAR(512) NULL,
added_by VARCHAR(255) NOT NULL,
created_at TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
deprecated TINYINT(1) NOT NULL DEFAULT 0,
UNIQUE KEY uq_env_name (env, name)
) ENGINE=InnoDB;
```
Seed для каждого env (dev/stage/prod): 9 базовых значений через `INSERT ... ON DUPLICATE KEY IGNORE`, `added_by='system:seed-031'`.
Rollback: `031_doc_types_down.sql` — `DROP TABLE doc_types;`. Деструктивный, задокументирован.
### 35.3. Валидация в register_document / bulk_deprecate_documents
Заменить in-enum lookup на:
```sql
SELECT 1 FROM doc_types WHERE env=%s AND name=%s AND deprecated=0
```
Порядок гейтов: `E_INVALID_PRODUCT_NAME` → `E_UNKNOWN_DOC_TYPE`. Ошибка отсутствия: `E_UNKNOWN_DOC_TYPE, class=validation, data={doc_type, available:[топ-32 активных]}`.
### 35.4. Новые op
**`register_doc_type`** (WRITE, HMAC HARD):
- params: `env`, `name`, `description?`.
- Валидация имени: регекс `^[A-ZА-Я][A-ZА-Яa-zа-я0-9_ \-]{1,63}$`, коллация значима.
- Дубликат → `E_DOC_TYPE_EXISTS`.
- Успех: `{status:'ok', data:{new_id, env, name, description}}`.
**`deprecate_doc_type`** (WRITE, HMAC HARD):
- params: `env`, `name`.
- Отказ, если по `(env, name)` есть недеприкейтнутые документы → `E_DOC_TYPE_IN_USE, data.in_use_count=N`.
- Успех: `deprecated=1` в таблице.
**`list_doc_types`** (READ):
- params: `env`, опц. `include_deprecated=false`.
- Ответ: `{status:'ok', data:{doc_types:[{name, description, added_by, created_at, deprecated, in_use_count}]}}`.
### 35.5. Обновление schema_meta и onboard
- `full_state_report.schema_meta.enums.doc_type` — computed: список активных `name` для запрошенного env.
- `onboard.docs_types_available` — новое поле в ответе onboard: список активных doc_type для env (для клиента-Исполнителя).
## §36-NEW. Поле documents.description
### 36.1. Схема (миграция 032)
```sql
ALTER TABLE documents ADD COLUMN description VARCHAR(512) NULL AFTER comment;
ALTER TABLE documents_archive ADD COLUMN description VARCHAR(512) NULL AFTER comment;
```
Rollback: `032_description_down.sql` — DROP COLUMN. Деструктивный.
### 36.2. Расширение register_document
Опциональный параметр `description` (str ≤512, не только пробелы). Валидация: длина → `E_DESCRIPTION_TOO_LONG`; только пробелы → `E_DESCRIPTION_BLANK`.
### 36.3. Новая op update_document_description (WRITE, HMAC HARD)
- params: `env`, `doc_id`, `description`.
- Гейт: `principal == documents.uploaded_by` OR `principal ∈ arch_actors` (см. §34).
- Ошибка: `E_FORBIDDEN, data.uploaded_by=…, data.principal=…`.
- Успех: `{status:'ok', data:{doc_id, description}}`.
- Отдельная op (не расширение `update_document`) — снижение surface атаки.
### 36.4. Расширение read-op
`get_document`, `list_documents`, `full_state_report.documents[*]`, `onboard.docs[*]` — добавить поле `description` в ответ. Old-клиенты игнорируют.
### 36.5. promote_document
Опциональный `override_description?`. По умолчанию — копия из исходной записи. Копирование при deprecate → архив тоже включает description.
## §37-NEW. Публичный контракт onboard.docs_types_available
Пример ответа `onboard(env=prod, product=ai_docs_broker)`:
```json
{
"status": "ok",
"data": {
"ready": true,
"docs_types_available": ["Гайд Пользователя", "Гайд Архитектора", "Онтология", "Live Scenario", "Дорожная Карта", "Стандарт", "Отчёт Валидации", "Концепт Развития", "PMA"],
"docs": [{"doc_type":"Гайд Пользователя", "version":"v0.27", "sha256":"...", "description":"...", ...}],
...
}
}
```
## §34 (напоминание, без изменений)
`arch_actors` — hardcoded whitelist principals с расширенными правами (сейчас: andy.krivenko@gmail.com). Определяется в `ai_docs_broker/config/arch_actors.py`.
### Исходная версия v0.15 (doc_id=520)
# ADB Гайд Архитектора v0.15
Delta vs v0.14. Остальное — без изменений.
## §H-REMOVED. HMAC полностью удалён (миграция 033, wheel 0.9.0a9)
### 38.1. Мотивация
HMAC-подпись клиентских WRITE-запросов (`X-ADB-HMAC-Key-Id`, `X-ADB-HMAC-Sig`, `X-ADB-HMAC-Ts`, `X-ADB-HMAC-Nonce`) вводилась в 0.5.x как второй слой авторизации поверх actor. В 0.8.x + переход на actor-first авторизацию сделал HMAC избыточным:
- Actor обязателен на каждой WRITE-op, содержит полный контекст (product/node/principal/request_id/emitted_at/source_url) и уже проходит все гейты (`arch_actors`, `principal == uploaded_by`, per-node scope).
- HMAC не защищал ни от одного реального сценария, не покрытого actor'ом.
- Bootstrap/rotate требовал keyring, KEK, hmac_secret cache, отдельного протокола ротации — источник ops-долга и постоянных `E_HMAC_*` сбоев у Кодеров.
Оператор одобрил полное удаление 2026-09-15. Реализовано в BRIEF-ADB-099, wheel `0.9.0a9`, deploy_id=46 heavy02.
### 38.2. Схема (миграция 033_hmac_removed)
```sql
-- 033_hmac_removed.up.sql
RENAME TABLE node_credentials TO _deprecated_node_credentials_2026_09_15;
-- audit-колонки в documents / documents_archive остаются (для истории), но новые записи их не заполняют
ALTER TABLE documents_audit_log
DROP COLUMN IF EXISTS hmac_key_id,
DROP COLUMN IF EXISTS hmac_valid;
```
Rollback: `033_hmac_removed.down.sql` — `RENAME TABLE _deprecated_node_credentials_2026_09_15 TO node_credentials;` + восстановление колонок в audit-log из архивной копии. Rollback возможен 30+ дней (до миграции 034).
**Миграция 034** (планируется ≥30 дней после prod-деплоя, т.е. **не раньше 2026-10-15**):
```sql
DROP TABLE _deprecated_node_credentials_2026_09_15;
```
Деструктивная, задокументирована в Дорожной Карте v0.41 (T-MIGRATION-034).
### 38.3. Удалённая поверхность
**Op:**
- `rotate_node_credential` — WRITE-stub, возвращает `E_OP_REMOVED` для любого payload. Полное снятие с whitelist — в 0.9.0b1.
**Middleware (h2_shared):**
- `HmacRequiredMiddleware`, `HmacVerifyMiddleware`, `HmacSignerClient`, `NodeKeyStore` — удалены из `h2_shared.security.hmac.*`. Импорт этих модулей после 0.9.0a9 → `ImportError`.
**Error codes:**
- Удалены: `E_HMAC_REQUIRED`, `E_HMAC_INVALID`, `E_HMAC_MISSING`, `E_HMAC_REPLAY`, `E_NODE_REVOKED`, `E_INSECURE_BOOTSTRAP`, `E_CURRENT_KEY_MISMATCH`.
- Введён один новый: `E_OP_REMOVED` (`class=contract`) — маркер удалённой op на переходный период.
**Ответ `register_node`:**
- Убраны поля `hmac_secret`, `key_id`, `expires_at`. Ответ теперь: `{status:'ok', data:{node, env, created}}`.
- Поля `bootstrap_secret`, `rotate_of` в payload — deprecated no-op (игнорируются, не отклоняются, для совместимости со старыми клиентами).
**Env-переменные:**
- `ADB_KEK`, `ADB_BOOTSTRAP_SECRET`, `ADB_HMAC_REQUIRE_SECRETS` — deprecated no-op. Сервис стартует без них.
### 38.4. Клиент ai_docs_broker_client 0.2.0
**Wheel:** `ai_docs_broker_client-0.2.0-py3-none-any.whl`, sha256 `18fc70a41b43452c84178f2dd5a9eb78000f02dc81b77fefea2c4ac3eb3a0ba1`.
**Изменения:**
- Удалены функции `_maybe_sign()`, `_resolve_secret()`, `_hmac_headers()`.
- Модуль `hmac_sign.py` → no-op shim (возвращает пустой dict).
- Зависимость `keyring` удалена из `pyproject.toml`.
- Секция `[credential]` в `actor.toml` → warning `hmac_removed` в лог, дальше игнорируется.
- HMAC-related тесты (`test_client_hmac_cross.py`) перемещены в `_deprecated_tests/`.
**Совместимость:**
- Клиенты 0.1.x продолжают работать против broker 0.9.0a9+ — сервер игнорирует HMAC-заголовки.
- Клиент 0.2.0 против broker < 0.9.0a9 — работает, если старый broker не требовал HMAC HARD; иначе получает `E_HMAC_REQUIRED` и не может продолжить (запрет обходить старый HMAC).
Публикация 0.2.0 в единый wheelhouse — отдельный тикет T-CLIENT-PUBLISH (см. tech-debt-log v39).
### 38.5. Инварианты (обновлены)
- **INV-AUTH-1 (обновлён):** `all WRITE ops require valid actor{...} in payload` (было: `+ HMAC header`).
- **INV-AUTH-2 (снят):** `HMAC secret must never leak in logs / responses`. Больше не применяется — секретов нет.
- **INV-AUTH-3 (снят):** `rotate_node_credential must issue new secret without invalidating in-flight requests`. Op удалена.
- **INV-AUTH-4 (новый):** `no HMAC-related error code may be returned by broker >= 0.9.0a9`. Проверяется тестом `test_hmac_removed_0_9_0a9.py`.
### 38.6. Backward-compat matrix
| Клиент | Broker < 0.9.0a9 | Broker >= 0.9.0a9 |
|---|---|---|
| client < 0.2.0 (со старой подписью) | работает как раньше | HMAC-заголовки игнорируются, работает по actor |
| client 0.2.0+ (без подписи) | работает, если сервер не требовал HMAC HARD | работает |
### 38.7. Ops runbook (что делать при инциденте)
1. **Клиент шлёт `E_UNKNOWN_OP` на `rotate_node_credential`** — обновить клиент или пропустить операцию: она удалена намеренно.
2. **Клиент шлёт `E_HMAC_INVALID`** — узел или клиент на старом wheel. `health.version` целевого broker'а должен быть ≥ 0.9.0a9. Проверить `list_deploys(node)`.
3. **Broker падает при старте с `KeyError: ADB_KEK`** — старый wheel. Задеплоить 0.9.0a9+; env-переменные больше не читаются.
4. **Обнаружены записи в `_deprecated_node_credentials_2026_09_15`** — это ожидаемо. Данные сохраняются до миграции 034 для аварийного отката. Не трогать.
## §37-UPDATED. onboard.docs_types_available (без изменений)
Публичный контракт `onboard` не меняется (см. §37 v0.14).
## §35..36 (напоминание, без изменений)
Динамический реестр `doc_types` и поле `documents.description` работают как описано в v0.14. Все маркировки WRITE-op в них — `actor обязателен` (без HMAC).
## §CHANGELOG v0.16-consolidated
- Создана полная кумулятивная редакция для TD-2026-09-16-07 (T-DOCS-DELTA-BAN).