← к элементу · к схеме

Концепт Развития ADB

Полный текст

# ai_docs_broker: Концепт Развития contours-v0.19

## §CHANGELOG contours-v0.19 относительно contours-v0.18 (2026-10-01)

Решение Оператора (01.10 11:04, сессия 7c7f2694): wiki — интерфейс для
просмотра всей документации ADB. У wiki НЕТ своих доков (все доки — в
ADB) и НЕТ своих таблиц — всё лежит в таблицах MariaDB продукта ADB.
Отдельная схема `wiki_h2_web_view` и её сервисный пользователь из v0.17
ОТМЕНЕНЫ: таблицы проекции становятся таблицами продукта ADB и
вносятся миграциями ADB по его ЖЦ. Оформлены: тип «Архитектура»,
док «Архитектура wiki» v0.1 (doc 1880, роль wiki в Архитектуре H2) и
стандарт «Описание документа „Архитектура“» v0_1 (doc 1881, проверка
любого архитектурного дока: полнота + непротиворечивость).

Редакция кумулятивная: полный текст v0.18 (и история внутри) — ниже как
NON-ACTIVE HISTORY.

# MVP wiki: схема + первые доки

## Состав MVP (и только это)

1. **Главная страница** — кликабельная слоёная схема из «Архитектура
   Платформы» v0.2 (5 слоёв + сквозные контуры; каждый элемент — ссылка на
   страницу элемента) и живые счётчики реестра.
2. **Страницы элементов** — по ключам схемы (operator, owui, owui-chat,
   owui-files, owui-functions, aho, aco, bridges, roles, adb, nats, wiki,
   nodes, node-json, h2-shared, ring3, env, monitor, vps, paa): описание
   элемента + список его документов с ADB-координатами; отсутствующие
   помечены «нет в ADB».
3. **Страницы первых документов** — полный текст по координатам, версия и
   контрольная сумма видны.

Всё остальное (все продукты, узлы, деплои, прогоны, журнал, архив, поиск,
карта связей, llms.txt) — НЕ входит в MVP и делается только после его
сдачи (П2+ прежнего плана).

## Первые доки (выбраны из текущего ADB, срез 01.10)

| # | Док | Координаты чтения | Версия / doc | SHA (начало) |
|---|---|---|---|---|
| 1 | Архитектура H2 (схема) | `{"op":"get_document","env":"dev","product":"adb_meta","doc_type":"Архитектура Платформы","latest":true}` | v0.2 / 1877 | 315ea00c… |
| 2 | Онтология ADB | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Онтология","latest":true}` | v0.25 / 1087 | d235d079… |
| 3 | Гайд Архитектора ADB | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Гайд Архитектора","latest":true}` | v0.20 / 1081 | 04ad6251… |
| 4 | Гайд Пользователя ADB | `{"op":"get_document","env":"prod","product":"ai_docs_broker","doc_type":"Гайд Пользователя","latest":true}` | 0.48 / 1391 | c504db77… |
| 5 | UEPR ADB | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"UEPR","latest":true}` | 0.9.0a33-dev12 / 1097 | 45d60515… |
| 6 | Гайд Архитектора h2_shared («как запустить новый ит-продукт») | `{"op":"get_document","env":"dev","product":"h2_shared","doc_type":"Гайд Архитектора","latest":true}` | v1.2 / 1695 | 7beeed52… |
| 7 | Жизненный цикл пакета h2_shared | `{"op":"get_document","env":"dev","product":"h2_shared","doc_type":"Жизненный цикл пакета h2_shared","latest":true}` | v0.10 / 1728 | f289e578… |
| 8 | Гайд ЖЦ ИТ-продукта H2 (ЖЦ ring 3) | `{"op":"get_document","env":"prod","product":"adb_meta","doc_type":"Гайд ЖЦ ИТ-продукта H2","latest":true}` | v0.15 / 1431 | 47204429… |
| 9 | Онтология h2_shared | `{"op":"get_document","env":"dev","product":"h2_shared","doc_type":"Онтология","latest":true}` | v1.7.19 / 1653 | eb20f2d2… |
| 10 | Концепт Развития ADB (этот) | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Концепт Развития","latest":true}` | contours-v0.19 | — |
| 11 | Архитектура wiki | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Архитектура","latest":true}` | v0.1 / 1880 | aa881f79… |

Привязка к элементам схемы: 1, 11 → wiki (и главная); 2, 3, 4, 5, 10 → adb;
6, 7, 9 → h2-shared; 8 → ring3; остальным элементам MVP показывает их
страницы с пометкой «нет в ADB» по инвентаризации v0.16.

## Приёмка MVP

1. wiki.h2platform.ru открывается; схема видна, все слои визуально
   различимы; каждый элемент кликабелен и ведёт на страницу элемента.
2. Все 10 первых доков открываются полным текстом; версия и контрольная
   сумма на странице совпадают с реестром (живая сверка по координатам).
3. Счётчики главной совпадают с живыми вызовами фасада (продукты, доки,
   типы, узлы; 3+ счётчика).
4. Таблицы проекции созданы в MariaDB продукта ADB миграциями его ЖЦ;
   отдельная схема/пользователь не заводятся; таблицы реестра ADB не
   тронуты.
5. Изменений в ADB нет (кроме уже зарегистрированных «Архитектура
   Платформы» v0.2 и этого концепта).
6. Сдача MVP Оператору; П2+ начинаются только после приёмки.

## Таблицы MariaDB

База — готовая MariaDB на dev heavy02 (продукт ADB). У wiki НЕТ своих
tаблиц: всё, что нужно для показа, лежит в таблицах MariaDB продукта
ADB. Таблицы проекции (перечислены ниже) — таблицы продукта ADB:
заводятся и меняются ТОЛЬКО миграциями ADB по его ЖЦ (снимок до,
подготовка, живые пробы, учёт, обратный ход). Отдельная база, отдельная
схема или отдельный сервисный пользователь для wiki не заводятся
(решение Оператора 01.10 11:04; отмена схемы `wiki_h2_web_view` из
v0.17). Кодировка utf8mb4, InnoDB. Данные реестра wiki читает через
фасад; прямой SQL к таблицам реестра ADB из wiki запрещён. Архитектура
wiki целиком — док «Архитектура wiki» v0.1:
`{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Архитектура","latest":true}`.

**Таблицы MVP (создаются на П1-МВП):**

1. `elements` — граф схемы (источник — «Архитектура Платформы»):
   `element_key` (PK), `layer` TINYINT, `layer_title`, `parent_key`,
   `title`, `description`, `order_index`, `page_enabled` BOOL,
   `updated_at`.
2. `element_docs` — привязка элемента к докам:
   `id` PK, `element_key` (FK→elements), `env`, `product`, `doc_type`,
   `version`, `doc_id`, `sha256`, `label`, `kind`
   (primary|related|missing), `order_index`, `updated_at`.
3. `pages` — кеш страниц (свежесть — пересбор после приёма дока):
   `page_key` PK, `kind` (element|doc), `env`, `product`, `doc_type`,
   `version`, `title`, `body_md` MEDIUMTEXT, `source_sha256`, `built_at`.
4. `counters` — срезы счётчиков главной:
   `counter_key` PK, `value` BIGINT, `captured_at`.
5. `sync_log` — журнал синхронизации с фасадом:
   `id` PK, `op`, `params` JSON, `status`, `items` INT, `started_at`,
   `finished_at`.

**Таблицы после MVP (создаются на своих итерациях П5/П6):**

6. `search_index` (П5) — полнотекстовый поиск:
   `id` PK, `doc_id`, `product`, `doc_type`, `version`, `title`,
   `body_text` LONGTEXT, FULLTEXT `ft_search` (title, body_text),
   `updated_at`. MariaDB FULLTEXT по utf8mb4 ищет по словам без
   морфологии; стемминг — вопрос отдельной итерации, не MVP.
7. `links` (П6) — карта связей и разрывы:
   `id` PK, `from_doc_id`, `to_ref` JSON, `resolved_doc_id` (nullable),
   `status` (ok|broken), `checked_at`.

## Проверка непересечения таблиц (wiki vs ADB, срез 01.10)

Источник фактов — фактический DDL ADB: миграции 001–040 сборки 0.9.0a33
(каталог `ai_docs_broker/migrations`).

**Таблицы ADB:** `documents`, `documents_archive`, `doc_types`,
`platform_norm_doc_types`, `products`, `products_state` (+`_archive`),
`nodes`, `nodes_archive`, `node_credentials` (выведена миграцией 033),
`wheels`, `deploys`, `validation_runs`, `live_scenario_runs`,
`agent_work_log`, `audit_snapshots`, `caller_events`, `h2_migration_log`,
`_ops_migrations_log`.

**Сравнение — ни одна wiki-таблица не повторяет таблицу ADB:**

| Wiki-таблица | Ближайшая в ADB | Повтор? | Что добавляет к контуру |
|---|---|---|---|
| elements | нет | нет | слои и ключи схемы — навигационный граф, которого в ADB нет |
| element_docs | documents (метаданные) | нет — хранит только координаты-ссылки | привязка дока к элементу схемы; видимость «нет в ADB» (kind=missing) |
| pages | documents + owui files | нет — кеш рендера, источник всегда ADB | готовая страница с временем среза; скорость |
| counters | нет (вычислимы из ops) | нет — снимки, не факты реестра | мгновенная главная без live-запросов |
| sync_log | caller_events, agent_work_log | нет — другой владелец и другие данные (срезы синхронизатора, не вызовы брокера) | доказательство свежести каждого среза |
| search_index | нет — у фасада нет полнотекстового поиска | нет | поиск по текстам всех доков |
| links | нет — канонический реестр ссылок только планируется (группа В v0.14) | нет — вычисляемая проекция из текстов | карта связей и разрывов уже сейчас |

**Правила непересечения (действуют всегда):**

1. В wiki нет ни одной строки, являющейся фактом реестра. Документы,
   типы, продукты, узлы, сборки, деплои, прогоны, журнал работ агентов —
   только в ADB. Wiki их не копирует: каждая wiki-строка — либо
   производная (кеш, срез, индекс), либо привязка (элемент↔док).
2. Копии координат в `element_docs`/`pages` (version, sha256) —
   ссылки-снимки, не источник истины. При живой сверке расхождение sha
   помечает страницу устаревшей; истина — реестр ADB.
3. У каждого вида данных один владелец: ADB — «что существует», owui
   files — «тела документов», wiki — «как показано, как найдено, насколько
   свежо».

**Полный контур документации (складывается из трёх частей):**

- Слой «Что есть» — таблицы ADB: существование и история всех сущностей
  (документы, типы, продукты, узлы, сборки, деплои, прогоны, журнал,
  аудит).
- Слой «Тела» — owui files: содержимое документов по id.
- Слой «Показ» — таблицы wiki: структура для навигации (elements,
  element_docs), выдача (pages, counters), поиск (search_index), связи
  (links), свежесть (sync_log).

Вместе закрываются все вопросы контура: что существует (ADB), что внутри
(files), где это в схеме платформы (elements), как пройти к доку
(element_docs), что показать (pages), насколько свежо показано
(counters, sync_log), как найти (search_index), как связаны и где
разорвано (links). Отсутствующий док виден (kind=missing), устаревший
кеш виден (sha-сверка), изменение в ADB подтягивается пересбором. Пробел
один и он уже в плане: канонический реестр ссылок в ADB (группа В) —
тогда links из проекции станет сверяемой копией канона.

Правило свежести MVP: после каждого принятого документа в ADB — пересбор
затронутых страниц `pages` и срез `counters`; время среза видно на
страницах.

## Порядок работ (обновлённый)

1. **П1-МВП** — всё, что описано выше (приложение на heavy02, Caddy на VPS,
   MariaDB-схема MVP, схема + элементы + 10 первых доков). Это суженный П1
   из v0.16.
2. Сдача MVP Оператору.
3. Только после приёмки MVP — П2+ по плану v0.16 (страницы всех элементов,
   затем продукты/узлы/документы/… , поиск П5, карта П6, llms.txt П7).

Стандарт итерации v0.14, правило «ноль изменений ADB на этапе П», ссылки
только ADB-маршрутами — действуют без изменений.

## NON-ACTIVE HISTORY: contours-v0.18 (verbatim, 335739 bytes, SHA e7be48c364813de0d901c96cb3c5600c7631bd54d319dbd0c1bb5038519b2111)

Текст ниже — неизменённая предшествующая редакция (включает историю v0.17,
v0.16, v0.15, v0.14, v0.13, v0.12, v0.11, v0.10). Действующий порядок —
разделы этой редакции.
# ai_docs_broker: Концепт Развития contours-v0.18

## §CHANGELOG contours-v0.18 относительно contours-v0.17 (2026-10-01)

Решение Оператора (01.10 10:48, сессия 7c7f2694): проверить, что таблицы wiki
не повторяют, а дополняют таблицы ADB, и вместе составляют полный контур
документации. Проверка сделана по фактическому DDL ADB (миграции 001–040
сборки 0.9.0a33) — новый раздел «Проверка непересечения таблиц» в главе о
MariaDB. Остальное содержание v0.17 не менялось.

Редакция кумулятивная: полный текст v0.17 (и история внутри) — ниже как
NON-ACTIVE HISTORY.

# MVP wiki: схема + первые доки

## Состав MVP (и только это)

1. **Главная страница** — кликабельная слоёная схема из «Архитектура
   Платформы» v0.2 (5 слоёв + сквозные контуры; каждый элемент — ссылка на
   страницу элемента) и живые счётчики реестра.
2. **Страницы элементов** — по ключам схемы (operator, owui, owui-chat,
   owui-files, owui-functions, aho, aco, bridges, roles, adb, nats, wiki,
   nodes, node-json, h2-shared, ring3, env, monitor, vps, paa): описание
   элемента + список его документов с ADB-координатами; отсутствующие
   помечены «нет в ADB».
3. **Страницы первых документов** — полный текст по координатам, версия и
   контрольная сумма видны.

Всё остальное (все продукты, узлы, деплои, прогоны, журнал, архив, поиск,
карта связей, llms.txt) — НЕ входит в MVP и делается только после его
сдачи (П2+ прежнего плана).

## Первые доки (выбраны из текущего ADB, срез 01.10)

| # | Док | Координаты чтения | Версия / doc | SHA (начало) |
|---|---|---|---|---|
| 1 | Архитектура H2 (схема) | `{"op":"get_document","env":"dev","product":"adb_meta","doc_type":"Архитектура Платформы","latest":true}` | v0.2 / 1877 | 315ea00c… |
| 2 | Онтология ADB | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Онтология","latest":true}` | v0.25 / 1087 | d235d079… |
| 3 | Гайд Архитектора ADB | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Гайд Архитектора","latest":true}` | v0.20 / 1081 | 04ad6251… |
| 4 | Гайд Пользователя ADB | `{"op":"get_document","env":"prod","product":"ai_docs_broker","doc_type":"Гайд Пользователя","latest":true}` | 0.48 / 1391 | c504db77… |
| 5 | UEPR ADB | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"UEPR","latest":true}` | 0.9.0a33-dev12 / 1097 | 45d60515… |
| 6 | Гайд Архитектора h2_shared («как запустить новый ит-продукт») | `{"op":"get_document","env":"dev","product":"h2_shared","doc_type":"Гайд Архитектора","latest":true}` | v1.2 / 1695 | 7beeed52… |
| 7 | Жизненный цикл пакета h2_shared | `{"op":"get_document","env":"dev","product":"h2_shared","doc_type":"Жизненный цикл пакета h2_shared","latest":true}` | v0.10 / 1728 | f289e578… |
| 8 | Гайд ЖЦ ИТ-продукта H2 (ЖЦ ring 3) | `{"op":"get_document","env":"prod","product":"adb_meta","doc_type":"Гайд ЖЦ ИТ-продукта H2","latest":true}` | v0.15 / 1431 | 47204429… |
| 9 | Онтология h2_shared | `{"op":"get_document","env":"dev","product":"h2_shared","doc_type":"Онтология","latest":true}` | v1.7.19 / 1653 | eb20f2d2… |
| 10 | Концепт Развития ADB (этот) | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Концепт Развития","latest":true}` | contours-v0.18 | — |

Привязка к элементам схемы: 1 → wiki (и главная); 2, 3, 4, 5, 10 → adb;
6, 7, 9 → h2-shared; 8 → ring3; остальным элементам MVP показывает их
страницы с пометкой «нет в ADB» по инвентаризации v0.16.

## Приёмка MVP

1. wiki.h2platform.ru открывается; схема видна, все слои визуально
   различимы; каждый элемент кликабелен и ведёт на страницу элемента.
2. Все 10 первых доков открываются полным текстом; версия и контрольная
   сумма на странице совпадают с реестром (живая сверка по координатам).
3. Счётчики главной совпадают с живыми вызовами фасада (продукты, доки,
   типы, узлы; 3+ счётчика).
4. Схема и сервисный пользователь в MariaDB на dev heavy02 созданы по
   канону Онтологии (своя схема, свой пользователь, DDL в миграциях
   приложения); ADB-таблицы не тронуты.
5. Изменений в ADB нет (кроме уже зарегистрированных «Архитектура
   Платформы» v0.2 и этого концепта).
6. Сдача MVP Оператору; П2+ начинаются только после приёмки.

## Таблицы MariaDB

База — готовая MariaDB на dev heavy02 (продукт ADB). Схема `wiki_h2_web_view`,
сервисный пользователь `wiki_h2_web_view_svc` — по канону Онтологии v0.25
(своя схема + свой пользователь на продукт). Кодировка utf8mb4, InnoDB.
DDL живёт в миграциях приложения h2_web_view. В схеме — только данные wiki;
данные ADB читаются через фасад, прямой SQL к таблицам ADB запрещён.

**Таблицы MVP (создаются на П1-МВП):**

1. `elements` — граф схемы (источник — «Архитектура Платформы»):
   `element_key` (PK), `layer` TINYINT, `layer_title`, `parent_key`,
   `title`, `description`, `order_index`, `page_enabled` BOOL,
   `updated_at`.
2. `element_docs` — привязка элемента к докам:
   `id` PK, `element_key` (FK→elements), `env`, `product`, `doc_type`,
   `version`, `doc_id`, `sha256`, `label`, `kind`
   (primary|related|missing), `order_index`, `updated_at`.
3. `pages` — кеш страниц (свежесть — пересбор после приёма дока):
   `page_key` PK, `kind` (element|doc), `env`, `product`, `doc_type`,
   `version`, `title`, `body_md` MEDIUMTEXT, `source_sha256`, `built_at`.
4. `counters` — срезы счётчиков главной:
   `counter_key` PK, `value` BIGINT, `captured_at`.
5. `sync_log` — журнал синхронизации с фасадом:
   `id` PK, `op`, `params` JSON, `status`, `items` INT, `started_at`,
   `finished_at`.

**Таблицы после MVP (создаются на своих итерациях П5/П6):**

6. `search_index` (П5) — полнотекстовый поиск:
   `id` PK, `doc_id`, `product`, `doc_type`, `version`, `title`,
   `body_text` LONGTEXT, FULLTEXT `ft_search` (title, body_text),
   `updated_at`. MariaDB FULLTEXT по utf8mb4 ищет по словам без
   морфологии; стемминг — вопрос отдельной итерации, не MVP.
7. `links` (П6) — карта связей и разрывы:
   `id` PK, `from_doc_id`, `to_ref` JSON, `resolved_doc_id` (nullable),
   `status` (ok|broken), `checked_at`.

## Проверка непересечения таблиц (wiki vs ADB, срез 01.10)

Источник фактов — фактический DDL ADB: миграции 001–040 сборки 0.9.0a33
(каталог `ai_docs_broker/migrations`).

**Таблицы ADB:** `documents`, `documents_archive`, `doc_types`,
`platform_norm_doc_types`, `products`, `products_state` (+`_archive`),
`nodes`, `nodes_archive`, `node_credentials` (выведена миграцией 033),
`wheels`, `deploys`, `validation_runs`, `live_scenario_runs`,
`agent_work_log`, `audit_snapshots`, `caller_events`, `h2_migration_log`,
`_ops_migrations_log`.

**Сравнение — ни одна wiki-таблица не повторяет таблицу ADB:**

| Wiki-таблица | Ближайшая в ADB | Повтор? | Что добавляет к контуру |
|---|---|---|---|
| elements | нет | нет | слои и ключи схемы — навигационный граф, которого в ADB нет |
| element_docs | documents (метаданные) | нет — хранит только координаты-ссылки | привязка дока к элементу схемы; видимость «нет в ADB» (kind=missing) |
| pages | documents + owui files | нет — кеш рендера, источник всегда ADB | готовая страница с временем среза; скорость |
| counters | нет (вычислимы из ops) | нет — снимки, не факты реестра | мгновенная главная без live-запросов |
| sync_log | caller_events, agent_work_log | нет — другой владелец и другие данные (срезы синхронизатора, не вызовы брокера) | доказательство свежести каждого среза |
| search_index | нет — у фасада нет полнотекстового поиска | нет | поиск по текстам всех доков |
| links | нет — канонический реестр ссылок только планируется (группа В v0.14) | нет — вычисляемая проекция из текстов | карта связей и разрывов уже сейчас |

**Правила непересечения (действуют всегда):**

1. В wiki нет ни одной строки, являющейся фактом реестра. Документы,
   типы, продукты, узлы, сборки, деплои, прогоны, журнал работ агентов —
   только в ADB. Wiki их не копирует: каждая wiki-строка — либо
   производная (кеш, срез, индекс), либо привязка (элемент↔док).
2. Копии координат в `element_docs`/`pages` (version, sha256) —
   ссылки-снимки, не источник истины. При живой сверке расхождение sha
   помечает страницу устаревшей; истина — реестр ADB.
3. У каждого вида данных один владелец: ADB — «что существует», owui
   files — «тела документов», wiki — «как показано, как найдено, насколько
   свежо».

**Полный контур документации (складывается из трёх частей):**

- Слой «Что есть» — таблицы ADB: существование и история всех сущностей
  (документы, типы, продукты, узлы, сборки, деплои, прогоны, журнал,
  аудит).
- Слой «Тела» — owui files: содержимое документов по id.
- Слой «Показ» — таблицы wiki: структура для навигации (elements,
  element_docs), выдача (pages, counters), поиск (search_index), связи
  (links), свежесть (sync_log).

Вместе закрываются все вопросы контура: что существует (ADB), что внутри
(files), где это в схеме платформы (elements), как пройти к доку
(element_docs), что показать (pages), насколько свежо показано
(counters, sync_log), как найти (search_index), как связаны и где
разорвано (links). Отсутствующий док виден (kind=missing), устаревший
кеш виден (sha-сверка), изменение в ADB подтягивается пересбором. Пробел
один и он уже в плане: канонический реестр ссылок в ADB (группа В) —
тогда links из проекции станет сверяемой копией канона.

Правило свежести MVP: после каждого принятого документа в ADB — пересбор
затронутых страниц `pages` и срез `counters`; время среза видно на
страницах.

## Порядок работ (обновлённый)

1. **П1-МВП** — всё, что описано выше (приложение на heavy02, Caddy на VPS,
   MariaDB-схема MVP, схема + элементы + 10 первых доков). Это суженный П1
   из v0.16.
2. Сдача MVP Оператору.
3. Только после приёмки MVP — П2+ по плану v0.16 (страницы всех элементов,
   затем продукты/узлы/документы/… , поиск П5, карта П6, llms.txt П7).

Стандарт итерации v0.14, правило «ноль изменений ADB на этапе П», ссылки
только ADB-маршрутами — действуют без изменений.

## NON-ACTIVE HISTORY: contours-v0.17 (verbatim, 320960 bytes, SHA 8c8e7f578503766f1f77b51e454a44e5cae50a2cf88638dcbc6bced84f41ea28)

Текст ниже — неизменённая предшествующая редакция (включает историю v0.16,
v0.15, v0.14, v0.13, v0.12, v0.11, v0.10). Действующий порядок — разделы
этой редакции.
# ai_docs_broker: Концепт Развития contours-v0.17

## §CHANGELOG contours-v0.17 относительно contours-v0.16 (2026-10-01)

Решение Оператора (01.10 10:44, сессия 7c7f2694):

1. В «Архитектуре H2» схема сделана кликабельной, все слои видны визуально
   (зарегистрирована «Архитектура Платформы» v0.2 — слоёная схема с ключами
   элементов).
2. В Концепте описано простое MVP-наполнение: сначала «Архитектура H2» и
   связь с первыми документами; первые доки выбраны из текущего ADB и
   внесены в этот концепт (раздел «MVP»).
3. Двигаться далее — только после сдачи этого MVP.
4. Для wiki описаны таблицы MariaDB (раздел «Таблицы MariaDB»).

Редакция кумулятивная: полный текст v0.16 (и история внутри) — ниже как
NON-ACTIVE HISTORY.

# MVP wiki: схема + первые доки

## Состав MVP (и только это)

1. **Главная страница** — кликабельная слоёная схема из «Архитектура
   Платформы» v0.2 (5 слоёв + сквозные контуры; каждый элемент — ссылка на
   страницу элемента) и живые счётчики реестра.
2. **Страницы элементов** — по ключам схемы (operator, owui, owui-chat,
   owui-files, owui-functions, aho, aco, bridges, roles, adb, nats, wiki,
   nodes, node-json, h2-shared, ring3, env, monitor, vps, paa): описание
   элемента + список его документов с ADB-координатами; отсутствующие
   помечены «нет в ADB».
3. **Страницы первых документов** — полный текст по координатам, версия и
   контрольная сумма видны.

Всё остальное (все продукты, узлы, деплои, прогоны, журнал, архив, поиск,
карта связей, llms.txt) — НЕ входит в MVP и делается только после его
сдачи (П2+ прежнего плана).

## Первые доки (выбраны из текущего ADB, срез 01.10)

| # | Док | Координаты чтения | Версия / doc | SHA (начало) |
|---|---|---|---|---|
| 1 | Архитектура H2 (схема) | `{"op":"get_document","env":"dev","product":"adb_meta","doc_type":"Архитектура Платформы","latest":true}` | v0.2 | — |
| 2 | Онтология ADB | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Онтология","latest":true}` | v0.25 / 1087 | d235d079… |
| 3 | Гайд Архитектора ADB | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Гайд Архитектора","latest":true}` | v0.20 / 1081 | 04ad6251… |
| 4 | Гайд Пользователя ADB | `{"op":"get_document","env":"prod","product":"ai_docs_broker","doc_type":"Гайд Пользователя","latest":true}` | 0.48 / 1391 | c504db77… |
| 5 | UEPR ADB | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"UEPR","latest":true}` | 0.9.0a33-dev12 / 1097 | 45d60515… |
| 6 | Гайд Архитектора h2_shared («как запустить новый ит-продукт») | `{"op":"get_document","env":"dev","product":"h2_shared","doc_type":"Гайд Архитектора","latest":true}` | v1.2 / 1695 | 7beeed52… |
| 7 | Жизненный цикл пакета h2_shared | `{"op":"get_document","env":"dev","product":"h2_shared","doc_type":"Жизненный цикл пакета h2_shared","latest":true}` | v0.10 / 1728 | f289e578… |
| 8 | Гайд ЖЦ ИТ-продукта H2 (ЖЦ ring 3) | `{"op":"get_document","env":"prod","product":"adb_meta","doc_type":"Гайд ЖЦ ИТ-продукта H2","latest":true}` | v0.15 / 1431 | 47204429… |
| 9 | Онтология h2_shared | `{"op":"get_document","env":"dev","product":"h2_shared","doc_type":"Онтология","latest":true}` | v1.7.19 / 1653 | eb20f2d2… |
| 10 | Концепт Развития ADB (этот) | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Концепт Развития","latest":true}` | contours-v0.17 | — |

Привязка к элементам схемы: 1 → wiki (и главная); 2, 3, 4, 5, 10 → adb;
6, 7, 9 → h2-shared; 8 → ring3; остальным элементам MVP показывает их
страницы с пометкой «нет в ADB» по инвентаризации v0.16.

## Приёмка MVP

1. wiki.h2platform.ru открывается; схема видна, все слои визуально
   различимы; каждый элемент кликабелен и ведёт на страницу элемента.
2. Все 10 первых доков открываются полным текстом; версия и контрольная
   сумма на странице совпадают с реестром (живая сверка по координатам).
3. Счётчики главной совпадают с живыми вызовами фасада (продукты, доки,
   типы, узлы; 3+ счётчика).
4. Схема и сервисный пользователь в MariaDB на dev heavy02 созданы по
   канону Онтологии (своя схема, свой пользователь, DDL в миграциях
   приложения); ADB-таблицы не тронуты.
5. Изменений в ADB нет (кроме уже зарегистрированных «Архитектура
   Платформы» v0.2 и этого концепта).
6. Сдача MVP Оператору; П2+ начинаются только после приёмки.

## Таблицы MariaDB

База — готовая MariaDB на dev heavy02 (продукт ADB). Схема `wiki_h2_web_view`,
сервисный пользователь `wiki_h2_web_view_svc` — по канону Онтологии v0.25
(своя схема + свой пользователь на продукт). Кодировка utf8mb4, InnoDB.
DDL живёт в миграциях приложения h2_web_view. В схеме — только данные wiki;
данные ADB читаются через фасад, прямой SQL к таблицам ADB запрещён.

**Таблицы MVP (создаются на П1-МВП):**

1. `elements` — граф схемы (источник — «Архитектура Платформы»):
   `element_key` (PK), `layer` TINYINT, `layer_title`, `parent_key`,
   `title`, `description`, `order_index`, `page_enabled` BOOL,
   `updated_at`.
2. `element_docs` — привязка элемента к докам:
   `id` PK, `element_key` (FK→elements), `env`, `product`, `doc_type`,
   `version`, `doc_id`, `sha256`, `label`, `kind`
   (primary|related|missing), `order_index`, `updated_at`.
3. `pages` — кеш страниц (свежесть — пересбор после приёма дока):
   `page_key` PK, `kind` (element|doc), `env`, `product`, `doc_type`,
   `version`, `title`, `body_md` MEDIUMTEXT, `source_sha256`, `built_at`.
4. `counters` — срезы счётчиков главной:
   `counter_key` PK, `value` BIGINT, `captured_at`.
5. `sync_log` — журнал синхронизации с фасадом:
   `id` PK, `op`, `params` JSON, `status`, `items` INT, `started_at`,
   `finished_at`.

**Таблицы после MVP (создаются на своих итерациях П5/П6):**

6. `search_index` (П5) — полнотекстовый поиск:
   `id` PK, `doc_id`, `product`, `doc_type`, `version`, `title`,
   `body_text` LONGTEXT, FULLTEXT `ft_search` (title, body_text),
   `updated_at`. MariaDB FULLTEXT по utf8mb4 ищет по словам без
   морфологии; стемминг — вопрос отдельной итерации, не MVP.
7. `links` (П6) — карта связей и разрывы:
   `id` PK, `from_doc_id`, `to_ref` JSON, `resolved_doc_id` (nullable),
   `status` (ok|broken), `checked_at`.

Правило свежести MVP: после каждого принятого документа в ADB — пересбор
затронутых страниц `pages` и срез `counters`; время среза видно на
страницах.

## Порядок работ (обновлённый)

1. **П1-МВП** — всё, что описано выше (приложение на heavy02, Caddy на VPS,
   MariaDB-схема MVP, схема + элементы + 10 первых доков). Это суженный П1
   из v0.16.
2. Сдача MVP Оператору.
3. Только после приёмки MVP — П2+ по плану v0.16 (страницы всех элементов,
   затем продукты/узлы/документы/… , поиск П5, карта П6, llms.txt П7).

Стандарт итерации v0.14, правило «ноль изменений ADB на этапе П», ссылки
только ADB-маршрутами — действуют без изменений.

## NON-ACTIVE HISTORY: contours-v0.16 (verbatim, 310903 bytes, SHA 32427dea95b0e7f9c67dae0cbd44eaa68fafab3d68789bfe5dbce474e8f006fe)

Текст ниже — неизменённая предшествующая редакция (включает историю v0.15,
v0.14, v0.13, v0.12, v0.11, v0.10). Действующий порядок — разделы этой
редакции.
# ai_docs_broker: Концепт Развития contours-v0.16

## §CHANGELOG contours-v0.16 относительно contours-v0.15 (2026-10-01)

Решение Оператора (01.10, сессия 7c7f2694):

1. Главная страница wiki — схема полной архитектуры H2. Схема занесена в
   ADB как документ и к ней привязывается каждый элемент, чтобы было видно
   наполнение каждого элемента архитектуры.
2. Главная страница — первая; далее по ссылкам все доки вплоть до
   конкретных гайдов.
3. Прочитан конспект Оператора «Архитектура H2»; по нему сделан поиск
   доков, на которые уже есть ссылки, и список доков/страниц wiki, которые
   нужно доделать (инвентаризация ниже).
4. Хранение wiki — в уже готовой MariaDB на dev heavy02 (продукт ADB),
   без новой базы.

Редакция кумулятивная: полный текст v0.15 (и история внутри) — ниже как
NON-ACTIVE HISTORY.

# Wiki: главная страница — схема архитектуры

## Источник схемы

Схема зарегистрирована в ADB (01.10):

`{"op":"get_document","env":"dev","product":"adb_meta","doc_type":"Архитектура Платформы","version":"0.1"}`
— doc 1875, SHA `0e1fb77c9d8acba1d02c32e3fbe3cea9f30475ad2a61410e582b33e69cefbd58`,
7978 bytes. Новый тип «Архитектура Платформы» зарегистрирован штатной
операцией register_doc_type (id 1). Держатель — adb_meta (по рекомендации
v0.15 §4.1 о платформенных документах).

## Элементы схемы (все кликабельны)

Оператор; Платформа H2 (уровни A/B/C/D); OWUI chat; OWUI files; OWUI
functions; Мониторинг (Grafana); VPS Selectel (вход в VPN); ADB + wiki;
NATS; Сервера (node.json); h2_shared (ring 0); AHO; ACO; Мосты (roo, perpl);
Среды env; Роли ии-агентов; Основные документы продукта; Типы доков;
Проверки при внесении; Процессные доки; Промпт как код.

Правило: каждый элемент на схеме — ссылка на страницу элемента. Страница
элемента = описание из схемы + список документов этого элемента с их
координатами чтения ADB (JSON-маршрут, как в правиле ссылок v0.15) + живые
данные (продукты, деплои, прогоны — read-only через фасад). Если дока
элемента в ADB нет — страница честно показывает «нет в ADB» и ведёт в
очередь доделок. Никаких ссылок на файлы OWUI — только ADB-маршруты.

Навигация: главная (схема) → страницы элементов → документы → конкретные
гайды. Документы открываются полным текстом на странице документа (П2+).

## Привязка элементов к докам: инвентаризация

Проверено по живому реестру (list_documents/list_products по всем продуктам,
срез 30.09–01.10; dev 46 продуктов, ~1145+ документов, 63+1 типов).

**Уже есть в ADB (dev, если не сказано иное):**

| Элемент схемы | Наполнение в ADB |
|---|---|
| ADB | ai_docs_broker: Онтология 4, Гайд Архитектора 2, Гайд Пользователя (prod, v0.48, doc 1391), Live Scenario 6, Дорожная Карта 17, Концепт Развития 8 (v0.10–v0.16), UEPR 16, Аудит UEPR 14, Стандарт 37, Отчёт Валидации 57, PMA 12, Бриф 11, Дефект 6 |
| h2_shared (ring 0) | h2_shared: Онтология 11, Гайд Архитектора 3 («как запустить новый ит-продукт»), Жизненный цикл пакета h2_shared 10, Дорожная Карта 32, UEPR 43, Аудит UEPR 14, Стандарт 4, Live Scenario 4 |
| AHO | ai_helper_operator: Концепт Развития 11, Дорожная Карта 2 — НЕТ Онтологии/Гайда/UEPR (частично) |
| ACO | ai_connect_orchestrator: Онтология 3, Гайд Архитектора 4, UEPR heavy02 7, Аудит UEPR heavy02 4, Release Manifest 13, Дорожная Карта 13, Стандарт 8, Live Scenario 3 |
| Мосты | owui_roo_bridge: Онтология 6, Гайд Архитектора 7, UEPR 9, Дорожная Карта 54, Стандарт 16 и др. (132 дока); owui_perl_bridge: Онтология 1, Гайд Архитектора 2, PMA 6, Стандарт 9 и др. (42 дока) |
| Мониторинг | h2_obs_stack: Гайд Архитектора 1, Онтология 1, UEPR h2-edge-test 1, UEPR heavy01 1, Release Manifest 2, Отчёт Валидации 1, Дорожная Карта 1, Аудит UEPR 1 |
| Промпт как код | h2_agent_monitor: Анализ Журнала Агентов 19, Стандарт 4, Дорожная Карта 6, Гайд Архитектора 1, Онтология 1, Концепт Развития 3 |
| Онбординги | Контекст онбординга ИИ-Арх (11 по продуктам), Онбординг ИИ-Кодера 3 (ai_docs_broker) |
| Среды env | Правила env — в Онтологиях и Гайдах продуктов; узлы: heavy01, heavy02, light01(+prod), light02, light03, laptop, h2-appsrv, h2-br-srv, h2-edge-test зарегистрированы |
| Схема архитектуры | adb_meta: Архитектура Платформы v0.1 (doc 1875, новая) |

**Отсутствует — очередь доделок (wiki показывает «нет в ADB»):**

1. **Жизненный Цикл разработки продукта (ring 3)** — «Гайд ЖЦ ИТ-продукта
   H2» есть только в prod (adb_meta, v0.6, doc 830); в dev отсутствует.
   Доделать: актуализировать и внести в dev.
2. **Закрытие сессии ИИ-Арх** — нет ни типа, ни дока.
3. **Открытка онбординга ИИ-Кодера** — нет ни типа, ни дока (для ИИ-Арх
   открытка = «Контекст онбординга ИИ-Арх», есть).
4. **Гайд пользователя у продуктов, кроме ADB** — тип есть только в prod и
   только для ADB; остальным продуктам гайдов пользователя нет.
5. **Доки OWUI как элемента** (chat/files/functions) — продукта OWUI в ADB
   нет; ближайшее — «Исходник OWUI-фасада» (h2_agent_monitor, 1) и гайды
   h2_shared. Нужно нормативное решение о владельце.
6. **4 платформенных документа H2** (каркас, преамбула, функциональная
   поверхность, концепт C) — вне ADB, план В6 v0.14 без изменений.
7. **UEPR/Онтология для ai_helper_operator** — дополнить до полного набора
   основных документов.

Очередь доделок — отдельные задачи по ЖЦ (владелец — соответствующий
продукт); wiki не ждёт их и не блокируется их отсутствием.

# Хранение wiki: готовая MariaDB на dev heavy02

Проверено (01.10):

- Канон Онтологии ADB v0.25 (dev doc 1087): SQL-база ADB — MariaDB; у
  каждого продукта своя схема, свой сервисный пользователь, DDL таблиц;
  миграции SQL в пакете продукта.
- DSN хранится в h2_shared secrets (KV H2_SECRETS): сервисный пользователь —
  ключ `mariadb_ai_docs_broker_url`, admin — `mariadb_root_url`; node.json
  хранит только имя профиля `connection_profiles.sql`, значения резолвит
  h2_shared.
- ADB dev работает на heavy02: UEPR a26 «Работает a26 на heavy02/dev», все
  dev-регистрации идут от ai_docs_broker@heavy02.

Правила размещения:

- Новая база НЕ заводится. Wiki использует готовую MariaDB на heavy02 dev:
  своя схема (например `wiki_h2_web_view`), свой сервисный пользователь —
  по канону Онтологии (схема+пользователь на продукт).
- В схеме wiki — только собственные данные wiki: кеш срезов, граф схемы
  (элемент→страница→координаты дока), полнотекстовый индекс поиска,
  счётчики свежести. Это НЕ данные ADB.
- Данные ADB wiki читает ТОЛЬКО через OWUI-фасад (read-only, закрытый
  список операций — по образцу адаптера наблюдения). Прямой SQL к таблицам
  ADB запрещён (Гайд Архитектора v0.20: прямой SQL не является разрешённым
  обходом фасада).
- Доступ к DSN — h2_shared secrets по образцу ADB; пароли не в коде и не в
  node.json.

# Топология и итерации группы П (обновление)

Топология П1 (обновлена против v0.15):

- Приложение h2_web_view — на heavy02 dev, рядом с ADB и MariaDB. Сборка
  кодером на heavy02. Мост heavy01 заблокирован миграцией замка
  (E_TASK_ID_LOCK_MIGRATION_REQUIRED, 30.09–01.10) — П1 от него не зависит
  и его не ждёт.
- VPS h2-edge-test: Caddy-блок wiki.h2platform.ru проксирует на приложение
  heavy02 через VPN (VPS — вход в VPN H2). DNS A-запись wiki → 161.104.53.48
  добавлена на reg.ru 30.09 (зона h2platform.ru).
- Резервный вариант — по факту живой пробы: если проксирование через VPN не
  взлетит, приложение на VPS, MariaDB — через VPN-туннель. Решение
  фиксируется результатом пробы, не заранее.
- Наружу — только 22/80/443 на VPS; приложение на heavy02 слушает только
  localhost/VPN.

Итерации (стандарт v0.14: снимок до, подготовка с бэкапом, живые пробы,
учёт, обратный ход; одна итерация = одно изменение; сам ADB не меняется):

- **П1 (обновлён).** Каркас: приложение на heavy02, схема wiki в готовой
  MariaDB (свой сервисный пользователь), Caddy-блок на VPS, домен
  wiki.h2platform.ru. Главная страница = схема архитектуры (источник —
  doc 1875) с кликабельными элементами и живыми счётчиками. Приёмка:
  схема открывается по домену; 3+ счётчика совпадают с живыми вызовами
  фасада; схема wiki создана в MariaDB по канону; каждый элемент ведёт на
  страницу с координатами ADB-доков.
- **П2.** Страницы элементов: описание + список доков элемента
  (координаты JSON) + пометка «нет в ADB» для отсутствующих; страницы
  документов с полным текстом. Приёмка: контрольный элемент сверен с
  реестром (версия, сумма, текст).
- **П3.** Продукты, узлы, документы, типы, сборки, деплои, прогоны, журнал,
  архив — как v0.15, приёмка по живой сверке каждого раздела.
- **П4.** Свежесть: пересбор после каждого принятого документа, ≤30 минут;
  время среза на страницах.
- **П5.** Поиск: полнотекстовый индекс в схеме wiki (MariaDB); найдено
  несколько похожих — показываются все кандидаты, сайт не выбирает сам.
- **П6.** Карта связей и разрывы: ссылки извлекаются из текстов на стороне
  wiki; отчёт битых ссылок.
- **П7.** llms.txt: машиночитаемый указатель актуальных документов с
  координатами.

Приёмка каждой итерации — по стандарту v0.14, с поправкой v0.15: ADB не
переустанавливается и не меняется; проверяется wiki и её совпадение с
реестром. Прогон Live Scenario — по гайду продукта проекции с независимым
проверяющим.

## Порядок этапов

1. Группа П (П1–П7, обновлённая П1) — веб-отображение со схемой архитектуры
   как главной страницей.
2. Далее — группы А, Б, В, Д v0.14 без изменения содержания; В6 (внесение
   четырёх платформенных документов) сохраняет рекомендацию adb_meta.

Остальные правила v0.14 (стандарт итерации, критерий «ADB работает», запрет
двух правок в одной итерации) и правила v0.15 (ноль изменений ADB на этапе
П, ссылки только ADB-маршрутами) действуют без изменений. Единственное
изменение ADB этой редакции — уже сделанное и вне этапа П: тип «Архитектура
Платформы» и документ-схема doc 1875 (решение Оператора п.1).

## NON-ACTIVE HISTORY: contours-v0.15 (verbatim, 295205 bytes, SHA cd35d388ca5e70f17dc76f5c3a76a1da62f137d5fff27e9961ccaf53250ef238)

Текст ниже — неизменённая предшествующая редакция (включает историю v0.14,
v0.13, v0.12, v0.11, v0.10). Действующий порядок — разделы этой редакции.
# ai_docs_broker: Концепт Развития contours-v0.15

## §CHANGELOG contours-v0.15 относительно contours-v0.14 (2026-09-30)

Решение Оператора (30.09, сессия 7c7f2694): первым этапом реализуется
веб-отображение. В этапе — НОЛЬ изменений в ADB: ни новых операций, ни правок
схемы, ни правок данных; сайт только показывает то, что в ADB уже есть сейчас.
Состав разделов изучен по живым данным и предложен ниже; порядок итераций
v0.14 меняется — группа «П» (проекция) становится первой, остальные группы
(А/Б/В/Д v0.14) идут после и содержанием не меняются.

Проверено живыми read-only вызовами 30.09.2026 (доступность данных для
разделов): list_deploys, list_wheels, list_validation_runs,
list_live_scenario_runs, list_agent_work_log, list_documents, list_products,
list_nodes, list_doc_types — все возвращают данные; составы и счётчики
приведены в разделе «Разделы сайта».

Редакция кумулятивная: полный текст v0.14 (и история внутри) — ниже как
NON-ACTIVE HISTORY.

# Первый этап: веб-отображение того, что есть

## Жёсткое ограничение этапа

Сайт ничего не пишет в H2 и ничего не меняет в ADB. Единственный источник
данных — существующие read-only операции через OWUI-фасады. Синхронизатор —
по образцу существующего адаптера наблюдения (закрытый список операций,
пагинация без пропусков, секреты только в контейнере). Всё, чего в ADB нет
(например, реестр ссылок), на стороне сайта вычисляется из текстов документов
в собственном кеше проекции — это не изменение ADB.

## Разделы сайта (предложение по живым данным)

1. **Главная.** Сводка платформы одним экраном: счётчики (продуктов, узлов,
   документов, типов, активных деплоев, прогонов за неделю), время последнего
   среза, здоровье ADB (версия, время старта службы).
2. **Продукты.** Список карточек; карточка продукта: имя, тип, описание,
   узлы с активными деплоями (версия сборки, контрольная сумма, время), число
   документов, последние прогоны, журнал по продукту.
3. **Узлы.** Список: имя, класс (тяжёлый/лёгкий/ноутбук), назначение, статус,
   что развёрнуто на узле (активные деплои с версиями). Тестовые узлы
   показываются отдельным сворачиваемым списком, чтобы не мешали.
4. **Документы.** По продуктам и типам: актуальная версия, автор, время,
   контрольная сумма, комментарий, координаты для чтения агентом. Страница
   документа — полный текст. Многосерийные типы (UEPR по узлам) — сгруппированы
   по базовой части имени.
5. **Типы документов.** Справочник: имя, описание, счётчик использования,
   признак выведенного из использования.
6. **Сборки.** По продуктам: версия, контрольная сумма, размер, диапазон
   применимости, когда зарегистрирована.
7. **Деплои.** По узлам: активный деплой и история (заменённые), время,
   кто разворачивал.
8. **Прогоны.** Отчёты валидации и живые сценарии: продукт, статус
   (зелёный/красный/частичный), счётчики прошло/упало/всего, время.
9. **Журнал работ агентов.** Последние записи: кто, что делал, результат,
   время; фильтр по продукту/сессии.
10. **Архив документов.** Ушедшие версии: отдельный раздел, только чтение,
    с временем и причиной ухода.
11. **Карта связей и разрывы** (вычисляется на стороне сайта): кто на кого
    ссылается по текстам документов; отчёт битых ссылок.
12. **Поиск** (на стороне сайта): по названиям, описаниям и текстам; найдено
    несколько похожих — показываются все кандидаты, сайт не выбирает сам.
13. **llms.txt** — машиночитаемый указатель в корне домена для внешних
    инструментов: список актуальных документов с координатами.

## Итерации первого этапа (группа «П», каждая — одна итерация)

- **П1. Каркас приложения.** Контейнер на VPS h2-edge-test, за общим Caddy,
  домен вида wiki.h2platform.ru; главная страница с живым снимком реестра.
  Приёмка: страница открывается, счётчики совпадают с реестром.
- **П2. Продукты, узлы, документы.** Списки, карточки, страница документа с
  полным текстом. Приёмка: контрольный документ на сайте совпадает с реестром
  (версия, сумма, текст).
- **П3. Типы, сборки, деплои, прогоны, журнал, архив.** Приёмка: сверка
  выборочно по каждому разделу с живыми вызовами.
- **П4. Свежесть.** Пересбор после каждого принятого документа, не дольше
  30 минут; на страницах — время среза. Приёмка: внесённый документ виден
  на сайте в срок; время среза честно показано.
- **П5. Поиск.** Приёмка: известные документы находятся по словам из
  названия и описания; несколько кандидатов — показаны все.
- **П6. Карта связей и разрывы.** Ссылки извлекаются из текстов на стороне
  сайта. Приёмка: контрольная выборка связей сверена вручную.
- **П7. llms.txt.** Приёмка: указатель полный, совпадает с реестром.

Приёмка каждой итерации — по стандарту v0.14 (снимок до, подготовка,
живые пробы, учёт, обратный ход), с одной поправкой: сам ADB в этих итерациях
не переустанавливается и не меняется; проверяется сайт и его совпадение с
реестром. Прогон Live Scenario — по гайду продукта проекции с независимым
проверяющим.

## Порядок этапов (обновлённый)

1. Группа П (П1–П7) — веб-отображение, без изменений ADB.
2. Далее — группы А, Б, В, Д v0.14 без изменения содержания (справочник,
   первые документы, серии, описания, реестр ссылок и приёмка, платформенные
   документы, оценки).

Остальные правила v0.14 (стандарт итерации, критерий «ADB работает»,
запрет двух правок в одной итерации) действуют без изменений.

## NON-ACTIVE HISTORY: contours-v0.14 (verbatim, 285792 bytes, SHA da50234ad2cb7d4d8499db8e3cae1cdde6829adc467f60da0adec13a94c0e7dc)

Текст ниже — неизменённая предшествующая редакция (включает историю v0.13,
v0.12, v0.11, v0.10). Действующий порядок — разделы этой редакции.
# ai_docs_broker: Концепт Развития contours-v0.14

## §CHANGELOG contours-v0.14 относительно contours-v0.13 (2026-09-30)

Решение Оператора: план внедрения упрощается и режется на много малых итераций.
Каждая итерация — одно понятное изменение с полной приёмкой, доказывающей, что
ADB работает. Новый раздел «Как будем внедрять» (ниже) описывает единый
стандарт итерации и перечень шагов. Содержание направлений не меняется —
меняется только способ подачи: вместо крупных блоков — короткие шаги, каждый
отдельно принимается и отдельно откатывается. Все статусы — PROPOSED; порядок
шагов — рекомендованный, владельцем очереди остаётся Дорожная Карта.

Редакция кумулятивная: полный текст v0.13 (и история внутри него) — ниже как
NON-ACTIVE HISTORY.

# Как будем внедрять: много малых итераций

## Принцип

Никаких больших замен. Работаем короткими шагами: одна итерация — одно
изменение. После каждого шага ADB проверен целиком и работает; если шаг
неудачен — откатываем только его, ничего больше не трогаем. Между шагами нет
«наполовину сделанного»: реестр после каждой итерации полностью рабочий.

## Стандарт каждой итерации (всегда одинаковый)

1. **Снимок до.** Здоровье службы, счётчики реестра, список актуальных
   документов — сохраняем.
2. **Подготовка с бэкапом.** Правка кода на узле, полный тест-прогон при
   остановленной службе — ноль падений. Бэкап устанавливаемого пакета.
3. **Установка и перезапуск** — по образцу деплоя 0.9.0a34: установка,
   перезапуск службы, чистый лог, новая версия в health.
4. **Живые пробы после:**
   - старое поведение не изменилось: снимок «после» совпадает со снимком «до»
     (кроме намеренного изменения шага);
   - новое поведение работает: позитивная проба;
   - плохое отклоняется: негативная проба с понятной ошибкой.
5. **Учёт:** сборка и деплой регистрируются, результат — в журнал работ.
6. **Обратный ход:** бэкап и прежняя сборка наготове; откат — одна итерация.

Итерация не завершена, пока не выполнены все шесть пунктов. Две правки в одной
итерации не делаются. Если итерация откатилась — она повторяется целиком,
остальной план не сдвигается.

## Шаги (рекомендованный порядок)

Каждый шаг — одна итерация со стандартной приёмкой. Группы идут по
зависимости; внутри группы порядок можно менять.

**Группа А. Порядок в справочнике (без новых правил):**

- **А1. Схемы операций в гайд.** Добавить в Гайд Пользователя полные схемы
  register_validation_run / register_live_scenario_run (текст готов — из
  письма h2_openbrowser). Только документ, без кода.
- **А2. Проверка трёх функций справочника.** Живые пробы register_doc_type /
  deprecate_doc_type / update_document_description; если работают — закрыть
  TD-2026-09-16-01, если нет — мелкая починка и закрытие.
- **А3. Инвентаризация типов.** Только чтение: список всех типов с счётчиком
  использования и происхождением; отчёт в журнал. Ничего не меняем.
- **А4. Чистка типов.** По отчёту А3: вывести из справочника неиспользуемые
  тестовые типы, с причиной; повторная инвентаризация «после» — в журнал.
- **А5. Имена типов с узлом.** Привести «UEPR heavy02» и подобные к виду
  «база [узел]»; проверка: поиск по базовой части находит все серии.

**Группа Б. Первые документы и серии:**

- **Б1. Первый документ для одного типа (пилот).** Выбрать один простой тип,
  вручную внести Первый документ: принцип + пример. Приёмка: документ читается,
  тип помечен готовым.
- **Б2. Свойство «ключ серии» в справочнике.** Поле в справочнике типов
  (база + узел). Приёмка: чтение справочника возвращает ключи, ничего не
  сломалось.
- **Б3. Запрет новых линий (NORM-SERIES).** Включить отказ «новая линия с тем
  же именем» только после Б2. Приёмка: негативная проба — отказ; легальное
  продолжение — принимается; копия dev→prod — работает.
- **Б4. Приёмка по Первому документу — пилот.** Для типа из Б1: сверка
  документов с Первым документом при внесении. Приёмка: плохой по структуре —
  отказ с замечаниями; хороший — принят.
- **Б5. Приёмка — режим наблюдения на всех типах.** Проверки включаются как
  отчёт: пишут «было бы нельзя», ничего не запрещают. Приёмка: агенты работают
  как раньше; отчёты собираются.
- **Б6. Приёмка — включение по одному типу.** По готовности Первых документов:
  полная проверка включается на типе, наблюдаем на живом потоке; далее по
  одному. Правило: не включаем, пока в отчётах есть ложные отказы.

**Группа В. Полнота:**

- **В1. Поле описания.** Описание обязательное при внесении (черновик готовит
  вносящий агент). Приёмка: документ без описания — отказ; с описанием —
  принят, описание видно в списках.
- **В2. Наполнение описаний.** Пакетно, по продуктам, с подтверждением
  владельцев. Одна итерация = один-два продукта.
- **В3. Реестр ссылок — построение.** Схема + первичный проход по актуальным
  документам (только чтение документов, запись в таблицу ссылок). Приёмка:
  контрольная сверка числа ссылок по нескольким документам вручную.
- **В4. Проверка ссылок на входе.** При внесении: неразрешённая ссылка —
  отказ. Приёмка: документ с битой ссылкой — отказ; с рабочими — принят.
- **В5. Приведение старых ссылок к канону.** По списку из В3, пакетами по
  продуктам, отдельное разрешение Оператора на каждый пакет.
- **В6. Внесение четырёх платформенных документов H2.** Каркас, преамбула,
  функциональная поверхность, концепт C — по одному, с описанием и ссылками.

**Группа Г. Обзор для человека:**

- **Г1. Статические страницы + llms.txt.** Генератор страниц из реестра
  (документы, описания, координаты) + машиночитаемый указатель в корне
  домена. Приёмка: страница открывается, совпадает с реестром, свежесть —
  после каждого принятия, ≤30 минут.
- **Г2. Карта связей и разрывы.** Интерактивный слой над реестром ссылок:
  кто на кого ссылается, отчёт битых ссылок. Приёмка: совпадение с В3.
- **Г3. Поиск.** По названиям, описаниям, текстам; нашлось несколько —
  показываем все кандидатов. Приёмка: известные документы находятся по
  словам из описания; правило неоднозначности соблюдено.

**Группа Д. Оценки и остальное (каждая — отдельная итерация):**

- **Д1. Оценка MCP.** PMA: объём, польза, аудитория (включая ИИ-Кодера в
  VS Code). Только документ с оценкой, решение — Оператор.
- **Д2. Указатель по единой базе.** Передать задачу в контур платформы
  (h2_shared): короткая записка в реестре, тело оценки — там.
- **Д3. Типы продуктов.** Закрытый список типов + правило «один prod на H2»
  для выбранного класса. Приёмка: негативная проба — второй активный prod
  отклоняется.
- **Д4. Архивация ушедших версий.** Отчёт-кандидат (что осталось ни на одном
  сервере), архивация по подтверждению. Приёмка: архив не удаляет, читается.
- **Д5. Авто-обновление контекста онбординга.** Пересборка по прямым ссылкам,
  глубина 1, пакет изменений = одно обновление. Приёмка: изменение источника
  → контекст перевыпущен; зацикливания нет.
- **Д6. Валидация документации.** Сверка «Закрытие сессии ↔ Онбординг»;
  отчёт по действующей схеме прогонов.

## Что считается «ADB работает» на каждой итерации

После каждого шага проверяются четыре вещи, и только тогда шаг закрыт:
служба жива и отвечает о здоровье; чтение по координатам возвращает документ
с подтверждённой целостностью; списки возвращают то же, что до шага (снимок
совпадает); запись принимает хорошее и отклоняет плохое — как задумано шагом.
Полный тест-прогон — ноль падений. Всё записано в реестр и журнал.

## NON-ACTIVE HISTORY: contours-v0.13 (verbatim, 272603 bytes, SHA 45df4b44ac30c7768b15a91b0ac9904641addd0dc0e277f1ff01769a6b06bbf3)

Текст ниже — неизменённая предшествующая редакция (включает историю v0.12,
v0.11, v0.10). Не является маршрутом current; действующий порядок — раздел
«Как будем внедрять» этой редакции.
# ai_docs_broker: Концепт Развития contours-v0.13

## §CHANGELOG contours-v0.13 относительно contours-v0.12 (2026-09-30)

Редакция по решениям Оператора от 30.09.2026 (сессия 7c7f2694) после проверки
v0.12. Все новые блоки — PROPOSED; реализация — только через Дорожную Карту.
Прежние статусы и доказательства не переаттестуются. Код и runtime не меняются.

Решения Оператора этой редакцией:

1. **«Первый документ» вместо «слоя концептов типов».** Для каждого типа
   документов заводится Первый документ: в нём описан принцип типа — и он же
   является примером-эталоном этого типа. Все последующие документы типа
   сверяются с Первым документом. Первый документ типа вносится вручную,
   первым, без сверки — этим снимается цикл «для проверки документа нужен
   образец, для образца нужен образец». Терминология упрощена: тип документа —
   Первый документ (принцип + пример) — остальные документы типа.
2. **Промежуточный статус при проверке отменён.** Никаких «черновиков
   ожидания» не вводится. Всё остаётся как сейчас: пока документ не принят —
   его в реестре нет; приняли — появилась новая версия. Если проверка
   недоступна — отказ с явной ошибкой, повторная подача тем же путём.
3. **Спорные случаи решает владелец правил.** Если проверка не может решить,
   хороший документ или плохой, — документ не принимается, а владелец правил
   (Первого документа типа) смотрит и пишет, что не так: правило уточняется,
   документ автором правится. Ошибка ищется сначала в правиле.
4. **Чистка типов документов.** В справочнике накопились лишние типы
   (одноразовые фикстуры Live Scenario и пр.). Вводится чистка (Блок 2A).
5. **Типы с узлом в имени.** Для типов вида «UEPR heavy02», «Аудит UEPR
   light01» вводится правило: поиск и проверка идут по базовой части имени
   без узла; узел — модификатор серии (Блок 2B).
6. **Полное описание и преамбула системы ADB** — новый раздел этой редакции
   (ниже), простым языком.

Также исправлены дефекты текста v0.12, подтверждённые по байтам зарегистрированного
файла: убраны случайные иероглифы в §CHANGELOG п.6 (v0.12) и снята коллизия
нумерации — новые разделы именуются по-ID (без сквозных номеров «Блок N»),
ссылки на разделы прежних редакций всегда с суффиксом версии.

Редакция кумулятивная: полный текст v0.12 (включая историю v0.11/v0.10) —
ниже как NON-ACTIVE HISTORY.

# Система ADB — полное описание и преамбула

## Что такое ADB

ADB (ai_docs_broker) — единый реестр платформы H2. Один сервис, который знает
и доказывает: какие продукты существуют, на каких узлах они установлены, какие
сборки приняты, какие документы написаны и какие версии документов актуальны.
ADB — единственный источник истины: всё остальное (обзорные страницы, отчёты,
копии) — производные отображения, они ничего не решают.

## Зачем ADB нужен

Платформа H2 состоит из многих продуктов, узлов и внешних ИИ-агентов. Без
единого реестра каждый агент видел бы свою картину и верил самоотчётам. ADB
заменяет самоотчёты доказательствами: у каждой записи — кто, когда, что именно
(побайтовая контрольная сумма), и каждое действие оставляет след.

## Как устроен ADB

- **Сервис.** Программа на узле heavy02, работает как служба, подключена к
  общему транспорту платформы (NATS) и своей базе данных.
- **Доступ.** Агенты обращаются к ADB через функции OWUI (именованные вызовы):
  чтение документов, списки, внесение, регистрация сборок и деплоев. Человек
  пользуется теми же данными через обзорную страницу-проекцию (в разработке).
- **Среды.** Данных два контура: dev (разработка) и prod (боевой). Документ
  попадает в prod копированием из dev после приёмки — других путей нет.

## Что ADB хранит

- **Продукты** — кто есть кто: имя, тип, описание.
- **Узлы** — где что работает: машины платформы и их назначение.
- **Типы документов** — справочник: онтология, гайды, дорожные карты, отчёты
  и так далее. У каждого типа — Первый документ (принцип + пример).
- **Документы** — версии с автором, временем и контрольной суммой файла;
  актуальна одна версия на линию, прежние уходят в архив (не удаляются).
- **Сборки (wheel)** — принятое «изделие» продукта: имя, версия, контрольная
  сумма, размер. Деплой — факт установки сборки на узел; при новом деплое
  прежний автоматически становится «заменённым».
- **Прогоны** — результаты проверок: отчёты валидации и живые сценарии
  (зачётный прогон), с счётчиками «прошло/упало/всего» и статусом.
- **Журналы** — единый журнал работы агентов (что делали и с каким результатом)
  и технический журнал вызовов (кто и когда обращался, что ответило).

## Как читают документы

Только по точным координатам: среда, продукт, тип документа, «актуальный»
или конкретная версия. Не «полистать что есть», а «дай именно этот документ».
Функция чтения возвращает сразу полный текст, описание и подтверждение, что
файл цел (контрольная сумма сошлась). Ссылки из документа в документ — это
такие же координаты в общепринятой форме, а не адреса файлов.

## Как вносят документы

Новая версия документа регистрируется через приёмку: проверяется, что автор
представился, файл цел, ссылки рабочие, серия правильная, документ
соответствует принципу своего типа (Первому документу). Пока проверка не
пройдена — документа в реестре нет; принят — появилась новая версия.
Отказ всегда объяснён и не портит ничего: просто подай снова после исправления.

## Правила, которые нельзя обойти

- Каждый вызывающий обязан представиться (актёр): продукт, узел, версия, сессия.
- Контрольная сумма обязательна: то, что записано, должно совпадать с байтами.
- Документы кумулятивны: новая версия содержит полный текст, а не только
 изменения; сравнение версий программное.
- Всё важное пишется в журнал; журнал не редактируется.
- Актуальна одна версия на линию; приёмка продукта — по единым критериям
  готовности (GREEN), включая независимую проверку.

## Чего ADB не делает

- Не редактирует содержание документов — их пишут люди и агенты.
- Не хранит файлы сам — файлы лежат в файловом хранилище, ADB хранит ссылки
  и контрольные суммы и проверяет целостность.
- Не является второй вики: любые страницы-обзоры — только отображение.
- Не принимает продукт «на слово»: без прогона и независимой проверки
  приёмки нет.

## Тип документа — Первый документ — остальные документы

Три простых понятия, на которых строится порядок:

1. **Тип документа** — запись в справочнике: имя (возможно, с узлом),
   описание, свойства, признак готовности.
2. **Первый документ** типа — вручную вносимый эталон: в нём описан принцип
   (зачем этот тип существует, для кого, какая структура обязательна, что
   запрещено, как проверяется) и приведён пример. Он не сверяется ни с чем —
   он первый. Он же служит образцом, с которого копируют структуру.
3. **Остальные документы** типа — сверяются с Первым документом при внесении.
   Спор между документом и правилом решает владелец правила: он смотрит и
   пишет, что не так — уточняется правило или правится документ.

## Правило для типов с узлом в имени

Типы вида «UEPR heavy02», «Аудит UEPR light01» — это базовый тип с модификатором
узла. Канон: имя типа = «базовая часть [узел]». Поиск, проверка и отчёты по
таким типам всегда ведутся по базовой части («UEPR»), узел лишь уточняет серию.
Новые типы с узлом создаются только в этой форме; существующие приводятся к
ней в чистке (ниже).

## Блок 2A: чистка типов документов (NORM-DOCTYPE-CLEAN-01)

Факт: в справочнике dev 63 типа, prod 36; среди dev — одноразовые фикстуры
Live Scenario (LSBA…, LSB… и т.п.) с нулевым использованием, созданные
тестовыми задачами. Чистка:

1. Инвентаризация всех типов с счётчиком использования и последним датированным
   упоминанием.
2. Типы с нулевым использованием и служебно-тестовым происхождением — вывод
   из справочника с указанием причины (не удаление: справочник хранит историю).
3. Типы с узлом в имени — приведение к канону «база [узел]» с сохранением
   базовой части.
4. Правило против нового мусора: новый тип создаётся только вместе с Первым
   документом типа; одноразовые нужды задач (фикстуры) не оформляются типами.
5. Контроль после чистки: повторная инвентаризация, отчёт в журнал.

## Блок 2B: типы с узлом и серии

Базовая часть имени типа — ключ поиска и проверки; узел — ключ серии внутри
типа (см. NORM-SERIES-01 v0.11): для одного базового типа допустимы параллельные
линии по узлам, каждая — своя серия со своей версией. Запрос по базовой части
возвращает все серии; запрос с узлом — конкретную. Это же правило используется
приёмкой при проверке серий и валидацией документации.

## Приёмка документов (уточнение решений Оператора)

Сводно, с учётом решений этой редакции:

- Проверка при внесении — синхронная: документ появится в реестре только
  после полной проверки. Промежуточных статусов нет — как сейчас: не приняли —
  документа нет; приняли — есть версия.
- Если проверка недоступна — отказ с явной ошибкой; повторная подача тем же
  путём. Никаких «внесём, проверим потом».
- Спорный случай — документ не принимается; владелец правил смотрит и пишет,
  что не так. Ошибка ищется сначала в правиле, потом в документе.
- Существующие версии не проверяются задним числом. Полная проверка действует
  на новые версии, и только для типов с включённым признаком готовности
  (Первый документ типа зарегистрирован, владелец включил проверку).
- Пока у типа нет Первого документа — приёмка документов этого типа идёт в
  упрощённом режиме (только структура и ссылки), и обновление старых
  документов не блокируется.
- Результат проверки сохраняется в доказательствах документа: какая версия
  Первого документа применена, контрольная сумма проверенных байтов, вердикт.

## Переход без поломки (обязательный порядок внедрения)

Все новые проверки ставятся за «рубильниками», по умолчанию выключены; пока
выключены — брокер работает как сейчас, работающие агенты ничего не замечают.

1. Установка новой версии брокера — как 0.9.0a34: бэкап, установка,
   перезапуск, проверка живым запросом, откат наготове.
2. Режим наблюдения: новые проверки только записывают, что «было бы нельзя»,
   ничего не запрещают. Смотрим отчёты: сколько было бы отказов, где правила
   ошибаются. Агенты работают без ограничений.
3. Включение на одном типе документов у одного продукта; наблюдение на живом
   потоке — настоящие агенты вносят настоящие документы.
4. Боевой прогон: живой агент шлёт запросы на чтение и внесение до, во время
   и после переключения. Проверяем: чтение не сломалось, плохое отклоняется с
   понятной ошибкой, хорошее принимается, скорость в норме.
5. Обратный ход: любой рубильник выключается одной командой, поведение
   возвращается к прежнему без переустановки.
6. Постепенное расширение: остальные типы — по одному; prod — отдельное
   включение и отдельная проверка.

Правило перехода: следующий шаг не включается, пока не видно из отчётов,
что ложных отказов нет; чтение документов не меняется ни на одном шаге ни
для кого; у каждого шага есть обратный ход.

## Порядок внедрения (обновление v0.13)

1. Патч Гайда Пользователя №8: полные схемы register_validation_run /
   register_live_scenario_run (текст готов — письмо h2_openbrowser).
2. Верификация трёх WRITE-op справочника типов → закрытие TD-2026-09-16-01.
3. Чистка типов (Блок 2A) + канон «база [узел]» (Блок 2B).
4. Первые документы обязательных типов (первичное наполнение, вручную;
   рекурсии нет — Первый документ сверки не проходит).
5. Справочник типов со свойствами (ключ серии = база+узел, признак
   готовности, закладка видимости) → затем NORM-SERIES-01.
6. Поле описания (DESC-FIELD-01) + бэкфилл по продуктам с владельцами.
7. Приёмка (синхронная, без промежуточных статусов, отказ при недоступности)
   — включение по плану перехода.
8. Реестр ссылок → массовый проход по документам (отдельное разрешение).
9. Внесение четырёх платформенных документов H2.
10. Обзорная проекция + поиск (свежесть: после каждого принятия, ≤30 минут;
    поиск по базовой части типа; кандидаты не выбираются автоматически) +
    llms.txt.
11. Оценки (PMA): MCP-EVAL-01 (аудитория включает внутренних исполнителей в
    MCP-совместимых инструментах; правило «агенты ходят через контракты ADB»
    не меняется) и H2-UNIDB-01 (сокращён до указателя: тело — платформенный
    контур h2_shared; входное условие — изменение топологического канона,
    только по полному циклу).
12. NORM-PRODTYPE-01, NORM-ARCHIVE-01, CTX-AUTO-01 (лимиты каскада).
13. Валидация документации (пара «Закрытие сессии ↔ Онбординг»).

Патчи Гайда Пользователя вносятся синхронно с каждым внедрённым пунктом;
патч №8 — немедленно.

## NON-ACTIVE HISTORY: contours-v0.12 (verbatim, 250186 bytes, SHA c940270ceec52c94757e8876ce8b406436841163425ec0b3a361b1cb6b2d584c)

Текст ниже — неизменённая предшествующая редакция (включает историю v0.11
и v0.10). Не является маршрутом current, очередью или сегодняшним вердиктом.
Разделы истории с коллизией нумерации «Блок 6» сохранены как есть (verbatim);
в действующей части ссылки на них всегда с суффиксом редакции.
# ai_docs_broker: Концепт Развития contours-v0.12

## §CHANGELOG contours-v0.12 относительно contours-v0.11 (2026-09-30)

Редакция по итогам внешней мульти-модельной рецензии contours-v0.11 (три
независимых модели: Claude Opus 5.5, GPT 6.1 Sol, Gemini 3.8 Flash) и решений
Оператора от 30.09.2026 (сессия 7c7f2694-8d7a-4f23-b37c-9a3361478ec6). Все
новые блоки — статус PROPOSED CONCEPT / PROPOSED EVALUATION: утверждение не
является внедрением; реализация — только через Дорожную Карту отдельными
поручениями. Прежние статусы и доказательства не переаттестуются. Код, runtime
и контракты API этой редакцией не меняются.

Изменения по решениям Оператора:

1. **Блок 5 переработан.** Wiki — только для человека-Оператора; агенты в wiki
   не ходят и точкой входа её не считают (вход агентов — контракты ADB). CMS
   (Wiki.js/BookStack/MediaWiki) из реализации исключена; проекция — тонкое
   собственное read-only приложение + машиночитаемый указатель llms.txt.
   Память и место НЕ являются ограничением (решение Оператора); исключение
   CMS — следствие анализа ценности, а не экономии ресурсов.
2. **Блок 6 (новый): MCP-EVAL-01** — оценка объёма доработки и пользы MCP-слоя
   как прокси над контрактами ADB. Решение — после оценки.
3. **Блок 7 (новый): H2-UNIDB-01** — единая база данных H2 (Postgres),
   подключённая к NATS, с возможностью записи с любого узла. Ресурсные
   ограничения сняты Оператором; целевая СУБД — Postgres (при существующем
   MS SQL); «сделать сразу нормально». Стадия — оценка/концепт.
4. **ACCEPT-PROC-01 скорректирован решением Оператора:** семантическая
   проверка (соответствие концепту типа) остаётся СИНХРОННОЙ внутри приёмки —
   документ ждёт, пока проверен; лучше не принять ошибочный документ, чем
   отказывать задним числом. Инженерные следствия (fail-closed, двухфазный
   фасад) описаны в Блоке 2.
5. **DOCCONCEPT-01 усилен до полноценного слоя концептов типов документов**
   (требование Оператора): стандарт на каждый тип — гайд, валидация, отчёт и
   т.д. — и синхронная проверка документа по нему при загрузке. См. Блок 2.4a.
6. **ACCESS-RESERVE-01:** модель прав чтения сейчас не делается, но во все
   новые схемы закладывается так, чтобы добавить её后来 одним изменением.
7. **NORM-SERIES-01** исполняется только после введения ключа серии в
   справочнике типов (снятие внутреннего конфликта, отмеченного рецензией).
   **CTX-AUTO-01** получает лимиты каскада. **TD-2026-09-16-01** закрывается
   верификацией трёх WRITE-op до старта работ по справочнику (list_doc_types
   проверен живым вызовом 30.09.2026 через фасад: 63 типа dev / 36 prod —
   рецензия в этой части устарела).

Редакция кумулятивная: полный текст contours-v0.11 (включая NON-ACTIVE
HISTORY v0.10) включён ниже без изменений.

## Область и границы действующей редакции

Работа: документное обновление Концепта Развития ИИ-Архом ai_docs_broker /
heavy02 / dev. Фактическое состояние на момент редакции — как в v0.11:
брокер 0.9.0a34 (deploy_id 202, wheel_id 239); dev: 46 продуктов, 1145
актуальных документов, 63 типа; prod: 36 типов; Гайд Пользователя ADB — v0.48
(prod, doc_id 1391). Дополнительно проверено 30.09.2026 живым вызовом через
OWUI-фасад: `list_doc_types` работает (63/36 записей) — из четырёх операций
справочника типов, перечисленных в TD-2026-09-16-01, недоказанными остаются
три WRITE-op (`register_doc_type`, `deprecate_doc_type`,
`update_document_description`).

Постоянные ссылки на документы имеют ровно пять полей: op=get_document, env,
product, doc_type, latest=true. Actor добавляется при вызове. ID, версии, SHA
и размер — датированный evidence, не замена JSON-ссылки.

## Блок 2 (дополнение v0.12): приёмка и слой концептов типов

### 2.4a DOCCONCEPT-LAYER-01: слой концептов типов документов

Требование Оператора: на КАЖДЫЙ тип документа заводится концепт-стандарт —
полноценный документ-слой, а не справочная карточка. Концепт типа описывает:
назначение типа (зачем этот документ существует, какую задачу платформы
закрывает); целевую аудиторию (кто читатель и с каким уровнем доступа);
обязательную структуру (разделы, которые обязаны присутствовать); допустимое и
недопустимое содержание (что в документе этого типа запрещено); критерии
приёмки (как проверяется соответствие); шаблон документа (заготовка для
создания); примеры (эталонный экземпляр с координатами в реестре).

Хранение: концепт типа — сам документ в реестре, кумулятивный, одна линия на
тип (по правилу серий Блока 1.1), тип справочника — «Концепт Типа». Концепт
типа обязателен: без него документы этого типа не регистрируются (для новых
типов) — существующие типы получают концепты первичным наполнением, до
наполнения приёмка работает в режиме «структурная проверка only».

Первичное наполнение — по убыванию обязательности: Гайд Пользователя, Гайд
Архитектора, Онтология, Гайд ЖЦ ИТ-продукта H2, UEPR, Аудит UEPR, Дорожная
Карта, Концепт Развития, Live Scenario, Отчёт Валидации, Закрытие сессии
ИИ-Арх, Онбординг, Письмо-открытка, Стандарт, Техдолг, PMA, Бриф, Дефект,
Контекст онбординга ИИ-Арх. Каждый концепт типа вносится через обычный ЖЦ
документа; владелец — ИИ-Арх ADB, утверждение концепта типа — Оператор.

### 2.4b Синхронная семантическая проверка (решение Оператора)

Проверка документа на соответствие концепту его типа выполняется СИНХРОННО
внутри процедуры приёмки (ACCEPT-PROC-01): регистрация не завершается, пока
документ не проверен. Решение Оператора: лучше задержать внесение, чем
принять ошибочный документ и откатывать задним числом. Следствия, обязательные
к проектированию:

- **Fail-closed:** если семантическая проверка недоступна (LLM-контур не
  отвечает), приёмка отказывает с явным кодом (E_VALIDATION_PENDING) без
  записи; повторная подача — тем же путём. Никаких «приняли, проверим потом».
- **Двухфазный фасад:** синхронный NATS request-reply фасада может не ждать
  минутного LLM-прогона; поэтому транспорт приёмки — двухфазный на уровне
  фасада (submit → poll статуса приёмки → commit), при этом сама запись в
  реестр остаётся атомарной по результату полной проверки. Частично принятых
  документов не существует.
- **Воспроизводимость:** результат семантической проверки (вердикт, какая
  версия концепта типа применена, SHA проверенных байтов) сохраняется в
  receipt документа — проверка доказуема, а не «на словах».
- **Порог качества:** концепт типа задаёт критерии приёмки; спорные вердикты
  (пограничные случаи) не молча проходят и не молча отвергаются — фиксируются
  как замечания в receipt с пометкой для владельца типа. Апелляция — через
  владельца концепта типа, не через повторную подачу до изменения.

### 2.9 ACCESS-RESERVE-01: закладка модели прав (не реализация)

Решение Оператора: модель прав чтения сейчас не делается, но система
проектируется так, чтобы добавить её одним изменением, без миграций и
переписывания контрактов. Закладки: (a) в справочнике типов — зарезервированное
свойство «класс видимости» (значение по умолчанию — публичный; вводится в
эксплуатацию только нормативным решением); (b) в реестре ссылок — зарезервированное
поле видимости строки (заполняется значением по умолчанию); (c) все read-op
(фасады, проекция, llms.txt) читают через единую точку формирования выдачи, к
которой позже подключается фильтр прав одним местом; (d) llms.txt формируется
из той же точки — при вводе прав публичный указатель сузится автоматически.
Запрещается: строить read-пути в обход этой точки (иначе фильтрацию потом
придётся чинить в каждом месте).

## Блок 5 (переработанный v0.12): веб-проекция для человека

### 5.1 WEB-VIEW-01: принцип — без изменений

Проекция, не второй источник истины: данные — только read-only контракты
(OWUI-фасады ADB), редактирование — только через ЖЦ ADB. ADB остаётся
единственным источником истины; wiki — производное представление.

### 5.2 WEB-VIEW-02: назначение и ценность (уточнение Оператора)

Wiki нужна, чтобы человек увидел всю складную картину системы: правильное
отображение связей между документами, поиск разрывов (битые/висящие ссылки),
отслеживание обновлений документов по изменениям в связях («кто на меня
ссылается и что поменялось»), навигацию по продуктам/типам/узлам/деплоям.
Все эти ценности берутся из РЕЕСТРА ССЫЛОК (Блок 2.2 v0.11) и описаний
(3.1) — собственных данных ADB.

### 5.3 WEB-VIEW-03: реализация — тонкое собственное read-only приложение

CMS (Wiki.js, BookStack, MediaWiki) из v1 исключена. Обоснование (не
экономия ресурсов — память и место не проблема по решению Оператора):
главные ценности из 5.2 (карта связей, разрывы, лента изменений по ссылкам)
CMS не рендерит в принципе — это рендеринг НАШЕГО реестра ссылок, то есть в
любом случае собственный код; хостинг же markdown-страниц CMS даёт дороже и
сложнее, чем генерация статики; Wiki.js 2.x — ветка в сопровождении, 3.0 —
бета с пометкой «not for production» (проверено 30.09.2026), требующая к тому
же PostgreSQL 16+ и Node 26.

Реализация: тонкое read-only веб-приложение по образцу h2_obs_stack
(контейнер в compose-группе на VPS h2-edge-test за общим Caddy,
домен вида wiki.h2platform.ru; адаптер-синхронизатор с whitelist операций и
пагинацией без пропусков; инварианты IC-1..IC-7 Онтологии h2_obs_stack
переиспользуются). Состав: (a) генератор статических страниц документов
(markdown → html, свежесть — по мере синхронизации); (b) интерактивный слой
над реестром ссылок: страница документа с описанием и списком входящих/
исходящих ссылок, карта связей продукта, отчёт разрывов, лента изменений по
ссылкам; (c) инвентарь: продукты (с типами из 1.2), узлы, активные деплои;
(d) раздел «архив» — только чтение. Скрытые ссылки (3.4 v0.11) в проекцию не
попадают. Права — через закладки 2.9 (единая точка выдачи).

### 5.4 WEB-VIEW-04: llms.txt

В корне домена — машиночитаемый указатель llms.txt (и llms-full.txt):
список актуальных документов с координатами ADB, типами, версиями, SHA.
Назначение — внешние инструменты и краулеры; формируется той же точкой
выдачи, что и проекция (см. 2.9c). Указатель — навигация, не источник факта:
любой потребитель обязан подтверждать факт через get_document_full.

### 5.5 WEB-VIEW-05: агенты НЕ ходят через wiki (решение Оператора)

Внутренние ИИ-агенты H2 не используют wiki как точку входа. Их путь —
OWUI-фасады ADB: get_document_full (текст + целостность) и, после реализации
Блока 2.2, реестр ссылок (навигация «что читать дальше»). Wiki — интерфейс
человека. Интеграция с внешними ИИ-экосистемами (Claude, ChatGPT, Cursor,
VS Code) — предмет MCP-оценки (Блок 6), не wiki-API.

## Блок 6 (новый v0.12): MCP-EVAL-01 — оценка MCP-слоя

Решение Оператора: MCP — хорошо; нужны оценка объёма доработки и пользы.

Содержание оценки (стадия PMA/бриф, НЕ код):
- **Что оценивается:** MCP-сервер как прокси над контрактами ADB (над
  OWUI-фасадами), а не над wiki. Инструменты-кандидаты: поиск документов
  (по типу/продукту/тексту через будущую поисковую точку выдачи 2.9c),
  чтение документа (get_document_full с проверкой SHA), реестр ссылок,
  инвентарь продуктов/узлов/деплоев.
- **Кому:** внешние ИИ-экосистемы и IDE; внутренние агенты H2 свой путь не
  меняют (фасады). Фрагментации точек входа нет: MCP транслирует те же
  операции, права — наследуются из ADB через ту же точку выдачи (2.9).
- **Объём доработки:** каркас MCP-сервера (python), маппинг инструментов на
  существующие фасады, аутентификация (токен фасада), развёртывание на VPS
  рядом с проекцией, Live Scenario приёмки. Оценка трудоёмкости — в PMA.
- **Польза:** подключение платформенной базы знаний к стандартным клиентам
  2026 без интеграций под каждый инструмент; ограничение — аудитория внешних
  потребителей должна реально существовать (спрос со стороны Оператора/
  продуктов), иначе польза откладывается.
- **Выход:** PMA с оценкой (объём, риски, польза, аудитория) и решение
  Оператора — делать/отложить.

## Блок 7 (новый v0.12): H2-UNIDB-01 — единая база данных H2 (оценка)

Решение Оператора (30.09.2026): память и место — не проблема; MS SQL уже
есть, но целевая СУБД — точно Postgres; в будущем H2 может понадобиться
единая база данных, подключённая к NATS, куда любой узел пишет; если делать
— сразу нормально.

Содержание оценки (стадия концепт/PMA платформенного контура C, НЕ код):

- **Границы предмета:** блок выходит за рамки самого ADB — это платформенная
  инфраструктура; владелец контура — h2_shared (Ring 0), ADB — первый
  кандидат-потребитель и участник требований. В Концепте ADB зафиксирован,
  потому что реестр ADB и его NATS-контракты — первый объект миграции.
- **Целевая картина:** единый Postgres-кластер платформы; запись с любого
  узла — только через NATS-контракты (по образцу закрытых списков
  R-*-CENTRAL: никакой узел не пишет в СУБД мимо контракта), чтение — через
  сервисы-фасады. Топология размещения (heavy01 рядом с NATS/MinIO или VPS) —
  предмет оценки с учётом топологической дисциплины Онтологии.
- **Отношение к текущим данным:** ADB работает на MariaDB (mysql_pool).
  Миграция реестра ADB MariaDB → Postgres — отдельное нормативное решение с
  полным ЖЦ (схема, мигратор, параллельный прогон, приёмка AVAL), не часть
  этой оценки. Единая БД не поглощает ADB автоматически: ADB — реестр с
  собственной семантикой приёмки; UNIDB — инфраструктура хранения.
  Разграничение фиксируется в оценке явно.
- **Что оценивается:** состав данных-кандидатов (какие продукты платформы
  пишут в UNIDB; какие остаются в собственных СУБД), контур записи через
  NATS, схема версионирования/совместимости, секреты и права, ресурсная
  модель (снятое ограничение подтверждает запас), миграционные пути
  (MariaDB→Postgres, MS SQL→Postgres), риски двойного источника истины
  (UNIDB не становится вторым реестром — ADB остаётся источником истины о
  документах; UNIDB — хранилище, а не реестр).
- **Выход:** платформенная PMA/концепт с оценкой объёма и архитектуры,
  решение Оператора; дальнейшее — через ЖЦ продукта C-контура (усиленная
  приёмка: test_guide + ai_h2_shared_validation).

## Порядок внедрения (обновление v0.12)

Очередь и владельцы — только в Дорожной Карте; здесь — рекомендуемая
последовательность и зависимости:

1. Патч Гайда Пользователя №8 (полные схемы register_validation_run /
   register_live_scenario_run) — самый дешёвый пункт, внешние продукты уже
   спотыкались (письмо h2_openbrowser 28.09).
2. Верификация трёх WRITE-op справочника типов живыми вызовами → закрытие
   TD-2026-09-16-01 (list_doc_types уже проверен 30.09).
3. Слой концептов типов (2.4a): концепты обязательных типов — первичное
   наполнение.
4. Справочник типов со свойствами (включая ключ серии и закладку видимости
   2.9) → затем NORM-SERIES-01.
5. DESC-FIELD-01 (поле описания, автогенерация при внесении; бэкфилл 1145
   документов — пакетная задача с владельцами).
6. ACCEPT-PROC-01: приёмка с СИНХРОННОЙ семантической проверкой (2.4b),
   fail-closed, двухфазный фасад.
7. LINK-REGISTRY-01: реестр ссылок (первичное наполнение — проходом 8).
8. REFS-CANON-01: массовый проход по всем документам с приведением ссылок к
   канону (отдельное разрешение Оператора).
9. PLATFORM-DOCS-01: внесение четырёх платформенных документов H2.
10. WEB-VIEW-01..05: тонкое read-only приложение + llms.txt на VPS; приёмка
    по образцу h2_obs_stack (Live Scenario с независимым проверяющим).
11. Параллельные оценки (PMA, без кода): MCP-EVAL-01 (Блок 6) и H2-UNIDB-01
    (Блок 7) — решения Оператора по итогам.
12. NORM-PRODTYPE-01 + NORM-ARCHIVE-01 + CTX-AUTO-01 (с лимитами каскада:
    глубина 1, дедупликация и пакетирование триггеров).
13. DOCVALID-01: валидация документации (первый случай — пара
    «Закрытие сессии ↔ Онбординг»).

Патчи Гайда Пользователя v0.48→v0.49 (Блок 6 v0.11) вносятся синхронно с
каждым внедрённым пунктом; патч №8 — немедленно (пункт 1).

Приёмочные тесты каждого этапа: программные проверки структуры, живые
негативные пробы (отказ без записи), контрольный обход монитора ссылок
(нуль неразрешённых), для проекции и MCP — зачётный Live Scenario.

## NON-ACTIVE HISTORY: contours-v0.11 (verbatim, 223435 bytes, SHA 70ddbc761202fa960d949f1de657b5071e58435c6a36cd5461442289ef239707)

Текст ниже — неизменённая предшествующая редакция (включает NON-ACTIVE
HISTORY contours-v0.10). Не является маршрутом current, очередью или
сегодняшним вердиктом.
# ai_docs_broker: Концепт Развития contours-v0.11

## §CHANGELOG contours-v0.11 относительно contours-v0.10 (2026-09-30)

Новая редакция по поручению Оператора (сессия 7c7f2694-8d7a-4f23-b37c-9a3361478ec6,
2026-09-30): развитие ADB по четырём направлениям — доработка самого брокера
(чистота реестра, проверка внесения, полнота), внесение платформенной
документации H2, веб-интерфейс-проекция на VPS Selectel и подключение к ней
ИИ-агентов. Все новые блоки этой редакции — статус PROPOSED CONCEPT:
утверждение концепта не является внедрением. Реализация, деплой, миграции и
массовые изменения реестра — только отдельными поручениями через Дорожную Карту.
Прежние статусы (ADB-JSON-REF-GUARD-01, ADB-REF-MON-01, CTX-H2-01,
ADB-BOOTSTRAP-01), результаты проверок и доказательства этой редакцией не
переаттестуются. Код, runtime и контракты API этим патчем не меняются.

Редакция кумулятивная: полный текст contours-v0.10 включён ниже как NON-ACTIVE
HISTORY без изменений.

## Область и границы действующей редакции

Работа: документное обновление Концепта Развития ИИ-Архом ai_docs_broker /
heavy02 / dev. Фактическое состояние на момент редакции (проверено живыми
read-only вызовами 2026-09-30): брокер 0.9.0a34 (deploy_id 202, wheel_id 239);
в dev зарегистрировано 46 продуктов и 1145 актуальных документов; в справочнике
типов 63 записи dev / 36 prod; актуальная редакция Концепта — contours-v0.10
(doc_id 1628, SHA-256 fcb6caf9a2128487d9aab69ba7a1c135d980872aa06d90fd12e60e13598cd7df).
Гайд Пользователя ADB — v0.48, канонический в prod. Четыре платформенных
документа (каркас платформы, преамбула, функциональная поверхность, концепт C)
проверены по всему реестру dev: в ADB НЕ зарегистрированы, существуют только
как файлы OWUI Files (факт зафиксирован в Блоке 4).

Постоянные ссылки на документы имеют ровно пять полей: op=get_document, env,
product, doc_type, latest=true. Actor добавляется при вызове. ID, версии, SHA и
размер ниже — датированный evidence, не замена JSON-ссылки.

## Блок 1. Чистота реестра

Цель блока: в реестре остаётся ровно одна понятная линия каждого логического
документа, типы продуктов управляются платформой, а мёртвые версии уходят в
архив без ручного решения каждый раз.

### 1.1 NORM-SERIES-01: новая линия вместо продолжения

Проблема. Сейчас одноимённый документ с новой версией можно внести как
продолжение старой линии (parent-цепочка), даже если содержательно это новый
документ; серии внутри одного doc_type не различаются надёжно (ограничение уже
зафиксировано в ADB-JSON-REF-GUARD-01: «нет надёжного измерения серии»).

Правило. Регистрация документа с тем же именем/типом, но новой линией — ОТКАЗ
(E_NEW_SERIES), если только это не заявленное продолжение той же линии
(явный parent, честная эволюция версии и CHANGELOG). Единственное разрешённое
«копирование без продолжения»: prod-копия dev-документа через promote_document
(существующий механизм env-pipeline) — она и остаётся способом попадания
документа в prod. Иные пути внесения «той же новой версии» отклоняются.

Реализация: контроль в register_document (точка `_upsert_active_document`) —
проверка, что (env, product, doc_type, серия) уже занята активной линией и
версия заявлена как продолжение; при несоответствии — ошибка без записи.
Мульти-серийность (например, UEPR по узлам) остаётся легальной: серия
различается по явному ключу (node/диапазон), ключ серии фиксируется в
справочнике типов (Блок 2.5).

### 1.2 NORM-PRODTYPE-01: тип продукта и единственный prod

Проблема. Поле product_type существует (unknown/other/service/library/meta/
tool/agent по факту реестра), но не нормативно: тип не управляет поведением,
prod-контур не ограничен.

Правило. (a) Вводится закрытый нормативный список типов продукта (расширение
существующего поля; новый тип — только через нормативное решение). (b) Для
типизированных продуктов действует норма «один prod на всю H2»: единственная
активная prod-запись деплоя платформенно-автоуправляемая (регистрация нового
prod-деплоя автоматически суперсидит прежний — механизм уже есть в
register_deploy; недостаёт запрета параллельных активных prod для этого класса
продуктов). (c) Из OWUI функциональная поверхность для таких продуктов видна
ровно двумя вариантами среды: prod и dev (никаких промежуточных имён сред);
это же ограничение наследуют фасады `h2_*_function`.

Границы: правило не трогает мультинодовые продукты с легальными отдельными
prod-деплоями на каждом prod-узле (Гайд ЖЦ); класс продуктов «один prod на
H2» определяется справочником типов явно.

### 1.3 NORM-ARCHIVE-01: версии, ушедшие со всех серверов

Проблема. Версии документов и wheel с applies_to_version_range, который больше
не соответствует ни одному активному деплою ни на одном узле, остаются
«актуальными» в реестре и мешают чтению.

Правило. Фоновая процедура (расширение ADB-REF-MON-01, тот же сервисный контур)
регулярно вычисляет: версия документа/wheel, чей диапазон применимости не
пересекается ни с одной активной версией runtime на всех узлах, — кандидат в
архив. Автоматически — только отчёт-кандидат и журналирование; перемещение в
архив (deprecate с retired_reason «left all servers, auto-audit <дата>») — по
явному подтверждению владельца или по нормативному правилу, если Оператор его
утвердит. Удаление исключено: только архив.

## Блок 2. Проверка внесения (приёмка документа)

Цель блока: в ADB не попадает документ с непроверенными ссылками, без описания
или с содержанием, не соответствующим концепту своего типа. Это развитие
утверждённого ADB-JSON-REF-GUARD-01 из «ссылки при записи» в полную процедуру
приёмки.

### 2.1 REF-GUARD: все ссылки — по канону get_document_full

Все рабочие ссылки во вносимых документах обязаны быть каноническими
JSON-координатами (op=get_document, env, product, doc_type, latest=true|version)
под функцией get_document_full — правило v0.44 Гайда становится обязательным
гейтом регистрации, а не рекомендацией. Реализация — по утверждённому концепту
ADB-JSON-REF-GUARD-01 (порядок записи уже описан там: поиск и классификация
ссылок → разрешение целей → план замен или ошибка → нормализация → повторная
проверка → атомарная запись). Дополнение этой редакции: помимо документов,
каноническими ссылками становятся типы документов, продукты и узлы (см. 2.5,
4.2).

### 2.2 LINK-REGISTRY-01: реестр ссылок

Новая сущность: таблица ссылок реестра. Для каждого актуального документа
фиксируются все исходящие ссылки (на документы, типы, продукты, узлы) с их
типом, координатами цели и состоянием (resolved/broken/hidden). Отдельная
проекция — все ссылки по архивным документам. Наполнение: первичный проход по
всем актуальным документам (1145 на 2026-09-30) процедурой из 2.3; далее —
автоматически при каждой регистрации. Чтение: list_document_links
(фильтры по документу/цели/состоянию). Реестр ссылок — производная величина,
не второй источник истины: строки строятся из проверенных байтов документов.

### 2.3 ACCEPT-PROC-01: процедура приёмки документа

Единая точка приёмки перед записью: (1) базовые проверки actor/полей/файла
(существующие); (2) проверка серии (1.1); (3) извлечение и проверка всех ссылок
по канону, приведение к канону, разрешение целей только по актуальному
реестру — или отказ без записи; (4) запись строк в реестр ссылок (2.2);
(5) проверка соответствия концепту типа (2.4); (6) проверка обязательности
описания (3.1); (7) атомарная запись с receipt: перечень проверок, замен и
новых строк реестра ссылок. Один прогон, без «частично принятых» документов.

### 2.4 DOCCONCEPT-01: концепты типов и контроль отсебятины

Для каждого типа документа заводится концепт: назначение типа, обязательная
структура, границы (чего в документе этого типа быть не должно), критерии
соответствия. При регистрации документ сверяется с концептом своего типа:
несоответствие структуры — отказ с точным указанием; содержание сверх концепта
допускается, но помечается. Сверка программная (структура) + LLM-проверка
«не отсебятина ли» (развитие существующего smart_intake: сейчас он проверяет
эволюцию версий, не соответствие типу). Концепты типов — кумулятивные
документы самих типов, вносятся в реестр как документы типа «Концепт Типа»
(новый тип справочника).

### 2.5 DOCTYPE-REF-01: справочник типов со свойствами

Справочник типов документов (register_doc_type/list_doc_types уже существует)
расширяется свойствами: концепт-ссылка (2.4), обязательность для класса
продуктов (2.6), признак «только в одном продукте / у каждого продукта»,
признак скрытых ссылок (3.4), ключ серии (1.1), каноническое имя файла.
Продукты и узлы также становятся ссылочными сущностями со свойствами (4.2).

### 2.6 MANDATORY-DOCS-01: обязательные документы

Закрытый список обязательных типов документов на класс продукта (по Гайду ЖЦ:
концепт, гайд, Live Scenario, критерии валидации на dev; UEPR, отчёт валидации
на prod). Список хранится в справочнике типов (2.5) и читается при онбординге
продукта. Правило: обязательные документы создаются по шаблону из концепта
типа — агент не изобретает структуру сам; отклонение от шаблона — через
нормативное решение, а не молча.

### 2.7 TD-DOC-01: Техдолг — отдельный документ

Технический долг продукта ведётся как отдельный документ своего типа
(«Техдолг», тип уже есть в реестре: in_use 1 в prod), а не разделами внутри
других документов. Концепт типа (2.4) фиксирует формат записи: TD-ID, статус
(open/frozen/closed), владелец решения, связь с Дорожной Картой. Нормативная
цель — один актуальный Техдолг на продукт, продолжение линии по правилу 1.1.

### 2.8 DOCVALID-01: валидация документации

Валидация документации продукта как регулярная операция: сверка фактического
набора документов продукта с обязательным списком (2.6), состояния ссылок
(2.2), соответствия концептам (2.4) и перекрёстная сверка пар документов,
которые обязаны согласываться друг с другом. Первый закрепляемый случай:
«Закрытие сессии ИИ-Арх» ↔ «Онбординг» (в онбординге нет ссылок на
несуществующие или заархивированные документы; в закрытии сессии перечислены
те же факты, что зафиксированы в журнале). Формат результата — отчёт валидации
документации (register_validation_run существующей схемы, validator =
продукт-валидатор или ИИ-Арх).

## Блок 3. Полнота и навигация

Цель блока: любой читатель — человек или агент — получает из ADB сразу и
суть документа, и его текст, и карту связей, без ручной сборки.

### 3.1 DESC-FIELD-01: поле описания документа

Каждый документ получает обязательное поле описания: суть, цель, зачем документ
существует (2–5 предложений). Операция update_document_description уже
существует (с wheel 0.9.0a8) — этой редакцией она становится частью нормы:
описание обязательно для актуальных документов, формируется/обновляется
автоматически при внесении новой версии (черновик описания готовит
регистрирующий агент, LLM-проверка осмысленности — в приёмке 2.3), читается во
всех списках и в onboard. Для 1145 существующих документов — первичное
наполнение отдельной задачей с подтверждением владельцев; до наполнения поле
остаётся пустым и помечается как незаполненное, ошибки это не создаёт.

### 3.2 OWUI-TEXT-01: из OWUI — сразу текст документа

Чтение документа через OWUI-функции (get_document_full) возвращает сразу полный
текст документа и его описание, а не ссылку на файл: это уже фактическое
поведение get_document_full (text + integrity_verified). Этой редакцией
нормативно закрепляется: (a) функции чтения обязаны возвращать text и
description в одном ответе; (b) то же свойство получают функции списков —
list_documents/onboard возвращают описание рядом с координатами; (c) ссылка на
документ в теле другого документа — это инструкция для вызова
get_document_full, а не URL; ответ функции и есть «открытие документа».

### 3.3 REFS-CANON-01: переформатирование ссылок в существующих документах

Проектная задача: пройти все актуальные документы, выявить все места, где ADB
упоминается идентификаторами (doc_id, file_id, «см. реестр») или нестандартными
ссылками, и привести их к каноническим JSON-координатам под get_document_full —
со встроенной ссылкой, открывающей документ, а не номером записи. Порядок:
(1) массовое обнаружение (поиск по всем 1145 документам; критерии — числовые
ID, Files UUID, текстовые отсылки); (2) план замен по документам, подтверждение
владельцев; (3) внесение новых версий через приёмку 2.3 (ссылки уже каноничны,
реестр ссылок наполняется автоматически); (4) контрольный обход ADB-REF-MON-01
— ноль неразрешённых ссылок. Массовое изменение реестра — отдельное поручение
Оператора, этой редакцией только планируется.

### 3.4 HIDDEN-LINKS-01: скрытые ссылки для типов документов

Тип документа может иметь признак «скрытые ссылки» (свойство в справочнике
2.5): ссылки такого документа не публикуются в реестре ссылок и не видны в
чтении списков; они проверяются при приёмке (2.3) на разрешимость, но не
раскрываются читателям. Первый случай — «Контекст онбординга ИИ-Арх»:
производный документ, чьи ссылки — служебная информация для платформы, а не
навигация для читателя.

### 3.5 CTX-AUTO-01: автоматическое переформирование контекста онбординга

Развитие CTX-H2-01 (сейчас контекст обновляется вручную, авто-refresh не
заявлен). Правило: контекст онбординга — производный документ, который
переформируется автоматически при изменении любого документа, на который он
ссылается (по реестру ссылок 2.2: цель изменила версию → пересборка контекста
по подтверждённым координатам). Новая версия контекста вносится через обычную
приёмку 2.3 с пометкой производности; ручная правка производного документа
запрещена — только перевыпуск. Механика триггера — сервисный контур
ADB-REF-MON-01 (та же очередь мониторинга).

## Блок 4. Платформенная документация H2 в реестре

### 4.1 PLATFORM-DOCS-01: внесение четырёх документов

Проверено 2026-09-30 по всему реестру dev (46 продуктов, 1145 документов):
четыре платформенных документа существуют только как файлы OWUI Files и в ADB
не зарегистрированы:

| Файл | Суть | OWUI file_id | Байты |
|---|---|---|---|
| H2_platform_skeleton_v1.md | Каркас описания платформы H2 по фактам ADB, без адб-meta | 6802c7eb-68d9-4f27-ad03-2e20c25dad31 | 24 434 |
| 06_preambula_v1.md | Преамбула: разделение H2 на Пользователя и Архитектора | 57ebde18-f68e-4fd3-a817-da95100b4a51 | 14 214 |
| 08_functional_surface_v1.md | Функциональная поверхность H2 для B-продукта | f77a70f9-c152-45ef-800e-88e8519fea9d | 15 924 |
| 10_architect_concept_C_v2.md | H2 для Архитектора — концепт (C), v2 | f3f7c3d2-a1ac-47c4-bd17-12f65571c83e | 12 984 |

Предложение: зарегистрировать их в ADB как платформенные документы (продукт-
владелец — нормативное решение: adb_meta как существующий держатель
мета-документов или новый продукт h2_platform; рекомендуется adb_meta, чтобы
не плодить сущности), с типами по справочнику и обязательным описанием (3.1).
До внесения — приёмка 2.3: в документах есть упоминания координат ADB в
тексте, их нужно привести к канону (3.3). Регистрация — отдельное поручение.

### 4.2 ENTITY-LINKS-01: продукты и узлы как ссылки со свойствами

Продукты и узлы становятся полноценными ссылочными сущностями: каноническая
ссылка на продукт/узел (по аналогии с документной: {op, env, product|node}),
свойства сущности (тип, статус, display_name, описание) читаются в ответе
функции рядом с текстом. Все упоминания продуктов и узлов в документах
приводятся к таким ссылкам в проходе 3.3. Свойства продуктов (включая тип из
1.2) и узлов — источник для проекции Блока 5.

## Блок 5. Веб-интерфейс-проекция (открытый wiki-продукт на VPS Selectel)

### 5.1 WEB-VIEW-01: принцип — проекция, не второй источник истины

Веб-интерфейс «вся складная картина» строится на существующем VPS Selectel
(узел h2-edge-test, 161.104.53.48: контур h2-owui / h2-pipelines /
h2-edge-caddy / h2-edge-nats; бюджет узла ~2–3 ГБ RAM, общий со стеком
наблюдения h2_obs_stack). Архитектурный принцип повторяет h2_obs_stack:
источник данных — только read-only контракты (OWUI-фасады
`h2_ai_docs_broker_function` и др.), продукт проекции ничего не пишет в H2.
ADB остаётся единственным источником истины; wiki — производное представление
(страницы = документы ADB, связи = реестр ссылок 2.2, инвентарь = продукты/
узлы/деплои). Редактирование контента только через ЖЦ ADB; в wiki — чтение и
поиск. Это исключает рассинхронизацию двух источников.

### 5.2 WEB-VIEW-02: выбор открытого продукта

Кандидаты (открытый код, self-hosted, Docker, поддержка API для этапа 5.4):

| Продукт | Движок | БД | Поиск | API | Оценка |
|---|---|---|---|---|---|
| Wiki.js 2.x | Node.js | PostgreSQL / MariaDB / SQLite | встроенный | GraphQL (страницы, поиск) | Рекомендуется: Markdown-native (доки ADB уже .md), лёгкий, API покрывает чтение и поиск |
| BookStack | PHP | MySQL/MariaDB | встроенный | REST (чтение) | Запасной: проще, но слабее API для агентов |
| MediaWiki | PHP | MySQL/MariaDB | полнотекстовый | зрелый API | Если нужен именно «Википедия-стиль»: тяжёлее, страницы не Markdown |

Рекомендация: Wiki.js 2.x, контейнер в compose-группе рядом с h2-obs, за общим
Caddy узла (домен вида wiki.h2platform.ru, как monitor.h2platform.ru у стека
наблюдения), БД SQLite на старте / MariaDB при росте. Синхронизатор —
отдельный лёгкий контейнер по образцу h2_obs_adapter (whitelist операций,
пагинация без пропусков, никаких секретов в конфигах дашбордов; инварианты
IC-1..IC-7 Онтологии h2_obs_stack переиспользуются).

### 5.3 WEB-VIEW-03: содержимое проекции

Страницы: актуальные документы ADB (по продуктам/типам), описание (3.1), карта
связей (2.2), справочник типов со свойствами, реестр продуктов/узлов/деплоев,
обязательные документы (2.6). Скрытые ссылки (3.4) в проекцию не попадают.
Архивные версии — отдельный раздел «архив», только чтение.

### 5.4 WEB-VIEW-04: подключение ИИ-агентов (этап после запуска)

После стабилизации проекции агенты получают доступ через API wiki:
полнотекстовый поиск по всей документации и чтение страниц. Правило
достоверности: wiki — указатель и навигация; факт для исполнения агент
обязан подтвердить чтением первоисточника через get_document_full (в ответе —
SHA/версия/цельность). Ссылки wiki на страницы генерируются из координат ADB
(обратное преобразование канона 2.1), поэтому цепочка «wiki → координаты →
документ» однозначна.

## Блок 6. Патчи Гайда Пользователя ADB (v0.48 → v0.49)

Проверено по актуальному тексту v0.48 (prod). Вносить при реализации
соответствующих блоков (каждый патч — кумулятивной новой версией гайда через
обычный ЖЦ):

1. §1.3/§1.4: ответ get_document_full/list_documents включает description;
   правило «открытие = текст» (3.1, 3.2).
2. §1.5: процедура приёмки документа — новый подраздел: проверка ссылок,
   приведение к канону, реестр ссылок, проверка серии, концепт типа,
   обязательное описание (2.1–2.6).
3. §1.5: правило серий — отказ на новую линию с тем же именем; prod-копия
   только через promote_document (1.1).
4. §2.1: закрытый список типов продукта, норма «один prod на H2» для
   типизированных продуктов, два варианта среды из OWUI (1.2).
5. §3.2/новое: политика архивации версий, ушедших со всех серверов;
   новые операции реестра ссылок (list_document_links) (1.3, 2.2).
6. §5.5: производные документы и контекст онбординга — автопереформирование,
   запрет ручных правок, скрытые ссылки (3.4, 3.5).
7. §5.7: обязательные типы документов по классу продукта; Техдолг как
   отдельный тип (2.6, 2.7).
8. Новое приложение: полные схемы операций register_validation_run /
   register_live_scenario_run (обязательные и опциональные поля, enum статусов)
   — устранение пробела, вскрытого письмом h2_openbrowser 2026-09-28
   (зафиксировано в журнале, записи 12242/12641).
9. §3.1/§3.4: семантика update_document_description в общем списке WRITE-op
   (операция существует с 0.9.0a8, в гайде отдельного раздела нет).

## Порядок внедрения

Очередь, владельцы и разрешения — только в Дорожной Карте; здесь —
рекомендуемая последовательность и зависимости:

1. NORM-SERIES-01 + DESC-FIELD-01 (гейты записи; база для всего остального).
2. LINK-REGISTRY-01 + ACCEPT-PROC-01 (реестр ссылок; первичное наполнение
   проходом 3.3).
3. DOCTYPE-REF-01 + DOCCONCEPT-01 + MANDATORY-DOCS-01 + TD-DOC-01 (справочник
   и концепты типов).
4. REFS-CANON-01 (массовый проход по документам; отдельное разрешение
   Оператора).
5. PLATFORM-DOCS-01 (внесение четырёх платформенных документов).
6. NORM-PRODTYPE-01 + NORM-ARCHIVE-01 + CTX-AUTO-01 + HIDDEN-LINKS-01.
7. DOCVALID-01 (валидация документации, включая пару
   «Закрытие сессии ↔ Онбординг»).
8. WEB-VIEW-01..04 (wiki-проекция на VPS; развёртывание и приёмка по образцу
   h2_obs_stack).
9. Патчи гайда v0.49 — синхронно с каждым внедрённым блоком (Блок 6).

Приёмочные тесты каждого этапа: программные проверки структуры (серия,
ссылки, реестр), живые негативные пробы (отказ без записи), контрольный обход
монитора ссылок (нуль неразрешённых), для wiki — зачётный Live Scenario по
Гайду Пользователя с независимым проверяющим.

## NON-ACTIVE HISTORY: contours-v0.10 (verbatim, 188735 bytes, SHA fcb6caf9a2128487d9aab69ba7a1c135d980872aa06d90fd12e60e13598cd7df)

Текст ниже — неизменённая предшествующая редакция. Не является маршрутом
current, очередью или сегодняшним вердиктом.
# ai_docs_broker: Концепт Развития contours-v0.10

## §CHANGELOG contours-v0.10 относительно contours-v0.9 (2026-09-28)

Точечная документная редакция по поручению Оператора: требования журналирования
согласованы с центральным журналом `agent_work_log`. Его операции:
`append_agent_work_log` и `list_agent_work_log`; для ПерпКомп они доступны через
OWUI Function `h2_ai_docs_broker_function`. Разрешённый транспорт ИИ-Кодера
определён его действующим контрактом и этой редакцией не меняется.
Технический аудит `caller_events` является отдельным
каналом и не подменяет этот журнал.

Редакционная правка охватывает полный текст, включая встроенные приложения.
Реквизиты прежних публикаций остаются датированными данными; отредактированные
приложения не объявляются побайтовыми копиями прежних файлов. Предыдущие записи
реестра и архив не изменены. Остальные требования, результаты проверок и статусы
работ не переаттестованы; код, runtime и контракты API этим патчем не меняются.
Порядок действий при простом документном входе определяется актуальным
Онбордингом; этот патч не добавляет входу журналирование, отчёт или новые гейты.

## Действующий порядок работы с журналом

Когда задача требует журналирования, источником хронологии является
`agent_work_log`. Агент отправляет событие через `append_agent_work_log` с
собственным actor, средой задачи, фактическим временем и безопасным описанием
результата. Для проверки события используется возвращённый числовой ID записи,
а для проверки полноты выполняется `list_agent_work_log` с фильтром собственной
сессии и пагинацией. Итоговый ответ содержит результат задачи и ограничения;
он не воспроизводит хронологию событий. Если подтверждение записи не получено,
успех журналирования не заявляется. Это правило определяет способ ведения
журнала при исполнении, а не вводит обязательное журналирование простого чтения.

Точные границы текстового патча: исправлены относящиеся к журналированию пункты
и ссылки внутри этого документа; сохранены относящиеся к задаче результаты,
проверки, недоказанные состояния и остальные требования. Объём изменения
редакционный и нормативный; наличие новой функции сервера не заявляется.


## §CHANGELOG contours-v0.9 относительно contours-v0.8

Полная редакция по поручению Оператора о закрытии сессии. Составлена 2026-09-21T18:22:18.043942+00:00. Актуализированы результаты документного цикла, незавершённые задачи и границы доказательств; прежний текст включён в историческое приложение с согласованными редакционными изменениями. Эта редакция не является delta или новым отдельным планом.

## Область и границы действующей редакции

Работа: документное закрытие ИИ-Арх ai_docs_broker / heavy02 / dev по поручению Оператора. Сессия 920f3491-21a3-40db-bcee-1f081dc4d0ad. Новая полная редакция не означает новый deploy, приёмку продукта, выполнение Live Scenario или внедрение одобренного кода. Архив ADB не читался и не изменялся. Историческое содержание включено ниже с согласованными редакционными изменениями; NON-ACTIVE HISTORY не является маршрутом current, очередью или сегодняшним вердиктом.

Постоянные ссылки на документы имеют ровно пять полей: op=get_document, env, product, doc_type, latest=true. Actor добавляется при вызове. ID, версии, SHA и размер ниже являются датированным evidence, не заменой JSON-ссылки. Гайд Пользователя любого продукта находится только в prod, независимо от среды его runtime. Для нескольких логических серий одного типа сначала list_documents и проверка серии/узла/диапазона; неоднозначный latest запрещено автоматически считать нужным документом.

Разрешены эта актуализация и read-only сверка. Не разрешены новым поручением: deployment, изменение кода или схемы, массовая миграция, удаление файлов/продуктов/записей, перезапуск исполнителей, закрытие чужих окон, снятие заморозки Техдолга. Все 20 существующих незакрытых TD-ID и их статусы сохраняются. Новые документные наблюдения не являются переоценкой замороженных статусов.
## Фактическое состояние и предел доказательств

Read-only API при закрытии: health сообщает 0.9.0a33, DB reachable, migration040/behind=0, started_at=2026-09-21T08:42:41.258Z. Для dev/ai_docs_broker/heavy02 реестр показывает один active deploy123, wheel150, version0.9.0a33, SHA-256 f667bce4f4e0f90b4a50b70b464e761b59831573b8e1f7b7734d055ba490b8f2, release a82e637c-b2ff-4e37-ad6d-2dde5c529e04; registered_at=2026-09-21T08:41:37.544Z. Prod active deploy для этой пары не найден. Это реестровое состояние, а не повторное доказательство узловых PID/путей/байтов установленного wheel.

Прежнее описание «accepted a26 / installed wheel132 / LS72 RED / validation NOT_RUN» относится к более раннему этапу и не используется как current. При этом наличие нового active deploy не доказывает автоматически соблюдение всех гейтов ЖЦ. В этой сессии новый runtime-кандидат не создавался и продукт заново не принимался.

Live Scenario runs73/74 для wheel150 зарегистрированы green, passed103/failed0/total135, но comments содержат 32 BLOCKED. Validation run85 зарегистрирован green, passed103/failed0/total103, validator=coder-adba33. Требуются сопоставление знаменателей, карточек и доказательство независимости требуемой ai_validation. Старый отчёт не переписывается под ожидаемые цифры; статус реестра не скрывается и не выдаётся за новую приёмку. Связь: TD-2026-09-19-04.

ROO в исследовании guard подтвердил installed0.9.0a33, но отметил более старые source/dist. До реализации надо доказать соответствие исходников wheel150, а не устанавливать найденное дерево. Source revision из прежнего UEPR сохранён как историческое утверждение, не новое подтверждение provenance.
## Результат исследования и граница реализации

Исследование процедуры записи и концепт завершены; документное утверждение не равно внедрению. ROO-задача ADB-JSON-REF-GUARD-CONCEPT-20260921-1954 завершена, экспорт ранее проверен: SHA-256 3a969eeeb456b00af29ae97d7b337f74522430f8da3ce617245dc6ab2c7c2ab4, 225060 bytes. Слова ROO о чтении норм не заменяли авторскую проверку wheel и актуальных нормативов. Это исследование, не независимая приёмка runtime.

Guard и монитор остаются APPROVED / NOT_IMPLEMENTED. До кода требуется разрешить source/wheel provenance и неоднозначность series/node. Нельзя молча нормализовать ссылку на другую серию. Неудачный/неоднозначный lookup должен дать ошибку без записи; архив монитором не сканируется. Автоматическая очистка сломанных ссылок без владельца не включается.

Очередь, владельцы и разрешения находятся только в Дорожной карте; дефекты в существующем Техдолге. Производный контекст обновляется вручную после реальных регистраций, автоматический refresh не заявлен.

## ADB-JSON-REF-GUARD-01: утверждённый концепт

Статус APPROVED CONCEPT / NOT_IMPLEMENTED. Оператор утвердил концепт 21.09.2026 после исследования ИИ-Арха с ROO. Реализация кода, deployment, фоновые задания и live-приёмка в этой документной задаче не выполняются.

## Решение в одном абзаце

Перед записью любого документа брокер проверяет весь фактически загруженный файл. Все рабочие ссылки на документы должны быть каноническими JSON-запросами. Старую ссылку на Files ID или document ID брокер автоматически заменяет, только если цель доказуемо однозначна и JSON выбирает тот же логический документ. Если хотя бы одна ссылка не разрешена или неоднозначна, операция завершается ошибкой без регистрации документа. После нормализации остаётся отдельная проверка честной эволюции/CHANGELOG; одна проверка не заменяет другую.

## Что нашли в текущем коде

Исследован опубликованный wheel `ai_docs_broker-0.9.0a33`, SHA-256 `f667bce4f4e0f90b4a50b70b464e761b59831573b8e1f7b7734d055ba490b8f2`. Пакет скачан через OWUI Files и проверен по байтам. ROO независимо исследовал `C:/h2/ai_Docs_broker`, включая установленный пакет в `.venv`; он подтвердил 0.9.0a33, но обнаружил более старые метаданные source/dist. Это риск происхождения сборки, не разрешение устанавливать найденное дерево.

Пути и строки ниже относятся именно к проверенному wheel. Они нужны как доказательства исследования кода, а не вместо JSON-ссылок на документы.

| Участок | Путь / функция | Фактическое поведение |
|---|---|---|
| Вход записи | `ai_docs_broker/ops/handlers.py:2958`, `register_document` | Проверяет поля, env, продукт, doc_type, файл и метаданные |
| Проверка файла | `ops/handlers.py:573`, `_verify_owui_sha_and_size` | Скачивает байты, сверяет SHA и переданный размер; сейчас не возвращает байты следующему шагу |
| Родитель | `ops/handlers.py:2810`, `_validate_parent_and_range` | Проверяет существование parent; это не доказательство, что сравнивается предшественник того же логического документа |
| Эволюция | `validation/smart_intake.py`, `validate_smart_intake` | Версии сравниваются программно; смысл и CHANGELOG оценивает LLM |
| Запись | `ops/handlers.py:2873`, `_upsert_active_document` | Идемпотентный повтор, конфликт или insert/update; используется также продвижением |
| Другой путь | `ops/handlers.py:3104`, `promote_document` | Может перенести документ без обычной содержательной проверки register_document |
| Канонический JSON узла | `ops/handlers.py:2266`, `register_canonical_node_json` | Также вызывает `_upsert_active_document`; требует общей проверки ссылок с сохранением схемы канонического JSON |
| Изменение метаданных | `ops/handlers.py:3312`, `update_document` | Нужен отдельный учёт изменений типа/контекста; обычный metadata-only update не должен переписывать файл |
| Выбор цели | `ops/handlers.py:2678`, `get_document`; `ops/repository.py` | По умолчанию новейшая активная запись по env/product/doc_type; отдельного надёжного измерения серии нет |

Цепочка записи: OWUI Function → NATS → agent/handler → `register_document` → проверки → `_upsert_active_document` → repository/БД.

### Ограничения нынешней проверки CHANGELOG

- **Проверка смысла не детерминирована:** `changelog_check` запрашивается в LLM-ответе. Это не жёсткая структурная проверка принадлежности текста нужному продукту и документу.
- **Охват ограничен:** `MAX_PROMPT_TEXT_CHARS=24000`; длинный документ целиком модель не видит.
- **Есть пропуски:** первая редакция, некумулятивный тип и отсутствие текста предшественника могут привести к skipped. Поэтому добавление требования ссылок только в LLM-промпт не даёт обязательного контроля.
- **Доверие к inline:** новый и предыдущий тексты могут браться из клиентского payload. Проверка SHA файла отдельно не связывает этот inline с теми байтами, которые прочитает LLM.
- **Нужен надёжный предшественник:** иерархический `parent_doc_id` не следует автоматически считать идентификатором предыдущей редакции. Нельзя сравнить один документ с подставленным клиентом другим.

## Предлагаемый порядок записи

```text
Проверка actor, прав, полей и идентичности документа
  → одно скачивание нового файла, проверка исходных SHA/size
  → получение полного проверенного текста
  → поиск и классификация всех ссылок
  → разрешение целей только по актуальному реестру
  → построение полного плана замен или ошибка
  → нормализация в памяти и повторная проверка всего текста
  → CHANGELOG/evolution по проверенным текстам той же линии документа
  → новый OWUI-файл, только если байты изменились; обратная SHA/size-сверка
  → повторная проверка неизменности контекста и разрешённых целей
  → атомарная запись реестра
  → receipt с фактическими file_id/SHA/size и перечнем замен
```

Предлагаемый модуль: `validation/document_references.py`, сервис подготовки `prepare_document_registration`. Это новые компоненты, не существующие API. Общая точка commit должна требовать внутренний результат проверки, связанный с SHA финального файла и версией политики; клиент не может передать `validated=true`, `skip_refs` или иной обход.

Покрытие обязательно для первой и последующих редакций, всех типов, включая Отчёт Валидации, обычной регистрации, продвижения и `register_canonical_node_json`. Для структурированных документов нормализация должна сохранять валидность их собственной схемы; если схема требует ID как техническое поле, нельзя слепо заменить его строкой JSON: нужно отделить техническую идентичность от рабочей ссылки, а неразрешённый конфликт контракта вернуть ошибкой. Идемпотентный повтор возвращает прежний receipt и явно различает «уже зарегистрировано» и новую проверку. Переклассификация/изменение контекста, способное поменять смысл ссылок, требует повторной проверки; журнал agent_work_log не становится документом и не получает этот guard автоматически.

### Канонический формат

```json
{"op":"get_document","env":"prod","product":"ai_docs_broker","doc_type":"Гайд Пользователя","latest":true}
```

Для обычной рабочей ссылки обязательны эти пять полей; запрещены заменяющие их ID, Files URL и закреплённая версия. Внешний actor остаётся в конверте вызова, не в постоянном адресе. Гайды Пользователя всегда prod; остальные типы не перемещаются автоматически между средами.

Если цель различается по узлу или серии, нельзя удалить эту различимость ради красивого JSON. Текущий общий get_document не доказывает выбор по node, даже если поле принято без ошибки. До подтверждённого канонического разрешения такой цели возвращается `E_DOC_REF_AMBIGUOUS`/`E_DOC_REF_IDENTITY_UNSUPPORTED`; произвольные `series` и `version_prefix` не добавляются. Контракт адресации серий/узлов требуется согласовать отдельно, если эти случаи нужны для включения guard.

## Как работает нормализация

### Найти все ссылки, не полагаясь на LLM

Полный Markdown/JSON/YAML разбирается структурно, дополнительно проводится лексический поиск Files URL, UUID в контексте file_id, doc_id/id и исполняемых get_document-блоков. Проверяются таблицы, reference-style Markdown links, HTML href, code fences, вложенные JSON-строки и приложения. Нельзя исключить все code blocks: там часто находятся настоящие рабочие запросы.

Детерминированный разбор не обещает понять любой намёк естественного языка. Подозрительная неразобранная конструкция в роли документной ссылки считается неуспешной проверкой, а не «ссылок нет». Шаблоны и evidence должны иметь явную проверяемую роль. Просто пометить произвольный блок «history» недостаточно для обхода.

### Разрешить старый адрес

1. Извлечь точный Files UUID или document ID; не выполнять URL как произвольный сетевой запрос.
2. Параметризованно найти соответствия только в текущей таблице документов с проверкой прав вызывающего. Не использовать архив, имя файла или догадку LLM.
3. Сгруппировать версии по доказанной логической идентичности. Несколько версий одной линии не равны нескольким независимым целям; совпадение одного файла у разных продуктов или сред может быть неоднозначным.
4. Проверить продукт/тип/среду по явному контексту ссылки. Межпродуктовая ссылка сама по себе допустима; запрещено незаметно заменить заявленную цель другой.
5. Выполнить каноническое разрешение latest и доказать, что оно остаётся в той же линии. Если привязка есть только у старой записи, которая не является выбранной актуальной целью, без доказанной связи отказ.
6. Проверить доступность и целостность целевого файла, с ограничением размера, времени и числа целей. Не рекурсивно обходить весь граф документов; повторяющиеся цели проверять один раз в рамках операции.
7. Заменить весь рабочий адрес JSON-ссылкой, сохранить видимую подпись и местоположение изменения. Повторно проверить получившийся документ.

API обратного поиска по `owui_file_id` сейчас отсутствует; потребуется внутренний repository-метод и индекс, если план SQL подтвердит необходимость. Нет оснований придумывать колонку `is_current`: актуальность вычисляется по реальному контракту реестра. Даже диагностический поиск «в другом месте» не должен скрыто обращаться к архиву.

### Не искажать доказательства и технические примеры

Датированные ID/версии/SHA как evidence не становятся latest: иначе меняется смысл прежней проверки. Сохранённые исторические приложения и технические шаблоны скачивания Files API не переписываются. Рядом с evidence при необходимости добавляется рабочая JSON-ссылка.

Для автоматического исключения исторического блока нужна проверяемая неизменность относительно авторитетного предшественника либо иная утверждённая схема provenance. Автор не может превратить действующий некорректный переход в «историю» одной меткой. Неустановленная классификация ведёт к отказу с указанием места.

Веб-источники, сессии, пути исходников и бинарные release/test-артефакты не являются ADB-документами только потому, что у них есть URL или UUID. Их не подменяют get_document. Тип файла определяется по фактическому содержимому и MIME; неподдерживаемый формат не принимается с skipped. Для Markdown/JSON/YAML возможна нормализация; PDF/DOCX/ZIP требуют отдельного адаптера или явного отказа, а не притворной текстовой проверки.

## Целостность, ошибки и гонки

- **Единые байты:** проверять inline на точное соответствие декодированным байтам либо игнорировать его как источник истины. Предшественника получать сервером из той же подтверждённой линии; `prev_content` клиента не является доказательством.
- **Автоисправление создаёт новый файл:** исходный OWUI-файл не изменяется. Ответ обязан вернуть реально зарегистрированные file_id, SHA и size, а также original_sha, normalized_sha и список замен. SHA считается по байтам, не по нормализованному верхнеуровневому OWUI hash.
- **Нет частичного успеха:** сначала разрешить все ссылки и пройти содержательные проверки. При одной ошибке не регистрировать документ с остальными исправленными ссылками.
- **Две системы хранения:** OWUI и БД не образуют общую транзакцию. Новую загрузку учитывать как staging, при неуспешном commit оставить явный cleanup receipt и удалить только собственный неиспользуемый staging-файл по безопасной политике. Не обещать невозможную общую атомарность.
- **Конкурентное изменение:** сохранить fingerprint исходной головы и разрешений; непосредственно перед commit проверить их снова. При изменении вернуть retryable `E_DOC_REF_CONCURRENT_CHANGE`, не переключать цель молча. Сетевые вызовы не выполняются под долгой DB-блокировкой.
- **Идемпотентность:** ключ операции привязать к actor/request, исходному SHA, целевой версии и версии политики; повтор не создаёт вторую нормализованную загрузку/запись.
- **Самоссылка и циклы:** каноническая ссылка на публикуемый документ допустима, если точно совпадает с его будущим ключом и проверена в той же транзакции. Несуществующий другой документ даёт ошибку; циклические обычные ссылки сами по себе допустимы, поскольку рекурсивная валидация графа не нужна. Циклы parent-иерархии остаются отдельным запретом.
- **Без обходов:** неполученный текст, тайм-аут, превышение лимита или unsupported format дают явный отказ. Ни `allow_overwrite`, ни dev/test, ни тип документа, ни отсутствие parent не отключают guard.

Предлагаемые коды: `E_DOC_REF_INVALID`, `E_DOC_REF_NOT_FOUND`, `E_DOC_REF_AMBIGUOUS`, `E_DOC_REF_IDENTITY_UNSUPPORTED`, `E_DOC_REF_UNREADABLE`, `E_DOC_REF_UNCLASSIFIED`, `E_DOC_REF_FORMAT_UNSUPPORTED`, `E_DOC_REF_CONCURRENT_CHANGE`, `E_DOC_CONTENT_MISMATCH`. Это проектируемые коды, не уже поддерживаемый API.

Ошибка возвращает для каждого проблемного места: line/column или JSON path, безопасный фрагмент, исходный тип ссылки, причину, список разрешённых кандидатов без утечки чужих данных, действие для исправления. Внешний URL не скачивается произвольно: только разрешённый OWUI origin и UUID через известный Files endpoint.

## Минимальные приёмочные тесты

| Сценарий | Ожидаемый результат |
|---|---|
| Нет документных ссылок, полный текст прочитан | Успех с checked=0 |
| Корректный JSON на доступную актуальную цель | Без изменения файла |
| Один однозначный Files ID; несколько повторений | Все вхождения исправлены, одна проверка цели |
| Doc ID с доказанной актуальной идентичностью | Канонический JSON |
| Гайд Пользователя со старой dev-координатой, однозначная prod-цель | Исправление в prod с проверкой идентичности |
| Разрешённая ссылка на другой продукт | Успех, без ошибочного blanket cross-product запрета |
| Files ID принадлежит разным продуктам/сериям | Отказ без угадывания |
| Файл/запись отсутствуют; 403/404; SHA неверен | Отказ без регистрации |
| Похожее имя файла, но нет подтверждённой связи | Отказ |
| Новая ссылка спрятана после 24 000 символов | Найдена полным сканом |
| Блок кода, HTML href, Markdown reference link, вложенный JSON | Проверены, не пропущены |
| Inline или prev_content не равны доверенным файлам | Отказ, LLM не проверяет подставной текст |
| Evidence с прежним ID/SHA и неизменённая история | Не искажены |
| Рабочий Files URL замаскирован пометкой history | Отказ, а не skip |
| Нет предшественника или тип Отчёт Валидации | Контроль ссылок всё равно выполнен |
| Latest выбирает другую серию; node не учитывается | Явная ошибка идентичности |
| Нормализация меняет байты | Новый file_id, правильные SHA/size, исходник неизменён |
| Ошибка у последней из нескольких ссылок | Ни одной новой записи документа |
| Ошибка commit после загрузки staging | Нет опубликованной записи, staging учтён для cleanup |
| Повтор запроса после потери ответа | Тот же результат, без дублей |
| Цель изменилась между resolve и commit | Конфликт, без тихого переключения |
| Promote/register_canonical_node_json/update-context/allow_overwrite пытаются обойти guard | Проверка не обойдена; схема структурированного документа сохранена |
| Self-reference / будущая чужая цель / A↔B | Самоссылка валидна; будущая цель запрещена; цикл обычных ссылок не запускает рекурсию |
| ZIP/PDF без адаптера, oversized или невалидный текст | Явный unsupported/limit error, не skipped |

## Порядок внедрения

Сначала зафиксировать provenance исходников относительно установленного a33 и согласовать идентичность серий/узлов. Затем реализовать полный скан и dry-run отчёт без изменения реестра, проверить реальные текущие документы и исключения evidence. После этого добавить нормализатор, staging/commit/idempotency и включить обязательный guard на всех путях записи. Финальный gate: положительная и отрицательная матрица, отдельный тест ссылки за пределами 24 000 символов, live-регистрация с нормализацией и доказанный отказ без частичной записи.

Изменение LLM evolution следует отделить от нормализации ссылок, но устранение доверия к непроверенному inline и неверному предшественнику входит в обязательную безопасную границу. Простое добавление строки в существующий LLM-промпт задачу не решает.



## ADB-REF-MON-01: будущий мониторинг целостности документных ссылок

Статус: APPROVED CONCEPT / NOT_IMPLEMENTED. Алгоритм утверждён Оператором 21.09.2026 как часть развития ADB; наличие раздела не означает запуска службы, расписания, исправления runtime или успешной приёмки. Мониторинг использует тот же детерминированный разбор и разрешение ссылок, что и входной контроль регистрации, чтобы два контура не расходились в правилах.

### Область и снимок

1. Получить полный постраничный перечень актуальных документов по всем средам через функции запросов ADB. Не читать `documents_archive`, не включать историю и не считать все строки active одной актуальной редакцией. Для каждого поддерживаемого логического ключа выбрать голову тем же контрактом, которым пользуется `get_document/latest`; отдельные серии и узловые документы нельзя молча объединять.
2. Зафиксировать run_id, время, права/actor, версию политики, количество ожидаемых голов и fingerprint каждого ключа: ID, SHA, размер, file_id, диапазон применимости. Это согласуемый снимок, а не обещание атомарности нескольких сетевых GET.
3. Скачать фактические байты каждой головы, сверить SHA и размер. Кеш допустим только при совпадении fingerprint и ранее доказанной проверке байтов; проверку доступности проводить живым запросом с ограниченным TTL. Отсутствие тела даёт отдельный дефект владельца документа, не «ноль плохих ссылок».

### Поиск и классификация

4. Просканировать полное содержимое поддерживаемого формата, без лимита LLM в 24 000 символов. Учитывать Markdown-ссылки, reference links, HTML, таблицы, code fences, JSON/YAML и строковые вложения; неподдерживаемый формат и превышение лимита дают coverage gap, а не PASS.
5. Отделить рабочую документную ссылку от внешнего веб-источника, артефакта сборки/теста, примера-шаблона и исторического доказательства. Метка history сама по себе не является разрешением пропустить новую ссылку; неизменность исторической части подтверждается provenance. Не обращаться к архиву для её «починки».
6. Для каждой рабочей ссылки проверить канонические поля, допустимость среды/типа, существование актуальной цели, её доступность и идентичность. Гайды Пользователя адресуются только в prod. Для legacy ID построить однозначное соответствие актуальному логическому ключу; отсутствие, несколько кандидатов или потеря серии/узла запрещают автозамену.
7. Различать классы: INVALID_FORMAT, MISSING_CURRENT_TARGET, AMBIGUOUS_TARGET, TARGET_FILE_UNAVAILABLE, OWNER_FILE_UNAVAILABLE, CONTENT_HASH_MISMATCH, UNSUPPORTED_FORMAT, STALE_SNAPSHOT и TRANSIENT_TRANSPORT_ERROR. HTTP 404 означает недоступность в текущем контексте, не доказанное физическое удаление; 401/403, 429, timeout и 5xx не переводятся автоматически в «битую ссылку».

### Подтверждение и выдача

8. Перед окончательной классификацией повторить сомнительный запрос ограниченное число раз с backoff; отдельно сверить метаданные Files и содержимое. Никаких бесконечных retry, смены учётной записи для обхода прав или произвольного скачивания внешних URL.
9. Сопоставить fingerprint голов в конце прохода с начальным. Изменившиеся документы перечитать и перепроверить; при непрерывном изменении пометить STALE, а не закрывать проверку зелёным результатом.
10. Сформировать машиночитаемые findings: run_id, канонический ключ источника, evidence ID/SHA, строка/JSON path, тип и безопасный фрагмент ссылки, ключ цели, ошибка, наблюдения HTTP, уверенность, предложенное действие и владелец. Дедупликация по ключу источника, типу проблемы и нормализованной цели; новое наблюдение обновляет finding, не создаёт поток дублей.
11. Сводка содержит expected/scanned/verified/skipped/unreadable, число проверенных ссылок, открытые/новые/закрытые ошибки и возраст последнего полного прохода. GREEN допустим только при 100% заявленного охвата и отсутствии ошибок; UNKNOWN/BLOCKED не являются GREEN. Отдельно считать качество ссылок и бинарную целостность владельцев, чтобы исправление ссылок не скрыло недоступные документы.

### Исправление и проверка

12. По умолчанию монитор только читает и сообщает. Исполнитель исправлений действует по отдельной политике/разрешению: уникально разрешимый legacy ID заменяется JSON; неразрешённая рабочая ссылка удаляется только при явном разрешении Оператора и без удаления окружающего требования. Если без ссылки теряется обязательное доказательство/зависимость, документ не объявляется годным: сохранить явный GAP/BLOCKED и сообщить владельцу.
13. Не удалять запись реестра, не архивировать документ и не придумывать его отсутствующее тело ради зелёного отчёта. Физически недоступные исходники требуют восстановления подтверждённых байтов либо отдельного решения по жизненному циклу.
14. Любое исправление создаёт полную новую редакцию с честным CHANGELOG, неизменённым историческим evidence, parent/provenance и собственными SHA/size; перед записью выполнить optimistic concurrency check. После записи прочитать latest, скачать файл, проверить bytes/SHA/size и повторно просканировать ссылки. Finding закрывать только подтверждённым readback, а не ответом регистрации.
15. Предусмотреть инкрементальную проверку после публикации, изменения цели или прав доступа плюс периодическую полную сверку. Интервал, бюджет, владельцы и канал уведомления задаются конфигурацией при реализации; этим документом расписание и уведомления не создаются.

### Приёмка мониторинга

Обязательны тесты: битая ссылка после 24 000 символов; legacy ID в таблице/code fence; отсутствующая и неоднозначная цель; dev-ссылка на пользовательский гайд; 404 против 403/timeout; отсутствующий файл источника; неверный SHA; недоступный формат; изменение головы во время обхода; неполная пагинация; дедупликация повторов; отказ без авторизации на запись; полная новая редакция и подтверждённое закрытие finding. Отдельный отрицательный тест должен доказать, что архив не запрашивается и результат с неполным охватом не становится GREEN.



## CTX-H2-01: производный контекст онбординга

Основной владелец: ИИ-Арх ai_docs_broker; общий потребитель: контуры H2/Bridge. Цель: короткий адресный вход без потери источников, истории и зависимостей. Состояние RESEARCHED / PROTOTYPED / PARTIALLY_VERIFIED; автоматическое обновление NOT_IMPLEMENTED. Предыдущий результат от 19 сентября: ready15.593с для ADB и24.995с для Bridge, полная проверка около139с. Это единичные исторические наблюдения, не SLA и не измерение этой сессии.

Принято: структура семантического ядра, маршруты по задаче, dependency manifest, исключение производного контекста из собственной подписи. Отклонено: превращать ready в execution authorization, выдавать последовательные GET за атомарный снимок, автоматически считать контекст свежим после регистрации. Остаток: реализация обновления/инвалидации/атомарного watermark не выполнена; внешние зависимости свежими не объявлены.

В предыдущем цикле был подготовлен context-v0.2: исправлены baseline и адрес Гайда UEPR, сохранён manifest с явными historical/unverified dependencies. Контекст регистрируется после зависимых документов и пересобирается с реальными ID/SHA. Внешние неперепроверенные зависимости остаются явно DIRTY; факт последующей регистрации проверяется через ADB, не обещается этой редакцией. Другой производный контекст Bridge в этой сессии не пересобран и не аттестован; его согласование остаётся в TD-2026-09-19-CTX-01, не предполагает разрешения на запись другому продукту.

## ADB-BOOTSTRAP-01: публичный bootstrap без ослабления actor/ring

Владелец: ИИ-Арх ai_docs_broker, транспортный владелец привлекается только по подтверждённому контрактному разрыву. Цель: получить норму и UEPR через публичный транспорт, затем вести полный actor-журнал в целевом env без чтения секретов в вывод.

Исходная гипотеза о необходимости менять h2_shared для транспорта отвергнута probe: публичный send_request работает в установленном окружении. Частный клиент, чтение HOST_REGISTRY вместо UEPR и снятие ring/actor-гейта отвергнуты. Документная поправка LC06 выполнена и проверена по байтам; функциональный bootstrap доказан вторым probe, но процесс целиком PARTIALLY_VERIFIED из-за journal env mismatch. NOT_IMPLEMENTED здесь относится к отсутствующей полной процедурной коррекции/новому принятому прогону, а не к уже работающему публичному транспорту.

Критерий завершения: чистый воспроизводимый старт по актуальной открытке, полные координаты/SHA/прочитанные разделы, target env без чужой записи, один корректный final, проверяемая история и безопасная доставка evidence. Повторный запуск не разрешается одним наличием этого концепта. Остаток связан с TD-2026-09-17-06 и Дорожной картой.


## Текущие адреса

`{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Дорожная Карта","latest":true}`

`{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Стандарт","latest":true}`

`{"op":"get_document","env":"prod","product":"ai_docs_broker","doc_type":"Гайд Пользователя","latest":true}`


---

## NON-ACTIVE HISTORY: редакционная копия предшествующего текста

Предшественник doc1082, versioncontours-v0.8, SHA-256 b5e79fb373966f7e70cd773054259295c70aa6441b5fd5c9e3c139d4b8d326c4, size136269. Следующий текст сохраняется как датированное свидетельство и прежние подробные критерии. Старые адреса/статусы здесь не являются текущими указаниями. Никакой архивный API для этого приложения не использовался.

# ai_docs_broker: Концепт Развития contours-v0.8

## §CHANGELOG contours-v0.8 относительно contours-v0.7 (2026-09-21)

Полная новая редакция по решению Оператора: утверждён концепт обязательного контроля и нормализации рабочих JSON-ссылок при регистрации документов; добавлен алгоритм будущего мониторинга ошибок ссылок. Предыдущие разделы и историческое evidence сохранены полностью. Это развитие существующего продукта, не отдельный документ-передача и не новая приёмка runtime.

## ADB-JSON-REF-GUARD-01: утверждённый концепт

Статус APPROVED CONCEPT / NOT_IMPLEMENTED. Оператор утвердил концепт 21.09.2026 после исследования ИИ-Арха с ROO. Реализация кода, deployment, фоновые задания и live-приёмка в этой документной задаче не выполняются.

## Решение в одном абзаце

Перед записью любого документа брокер проверяет весь фактически загруженный файл. Все рабочие ссылки на документы должны быть каноническими JSON-запросами. Старую ссылку на Files ID или document ID брокер автоматически заменяет, только если цель доказуемо однозначна и JSON выбирает тот же логический документ. Если хотя бы одна ссылка не разрешена или неоднозначна, операция завершается ошибкой без регистрации документа. После нормализации остаётся отдельная проверка честной эволюции/CHANGELOG; одна проверка не заменяет другую.

## Что нашли в текущем коде

Исследован опубликованный wheel `ai_docs_broker-0.9.0a33`, SHA-256 `f667bce4f4e0f90b4a50b70b464e761b59831573b8e1f7b7734d055ba490b8f2`. Пакет скачан через OWUI Files и проверен по байтам. ROO независимо исследовал `C:/h2/ai_Docs_broker`, включая установленный пакет в `.venv`; он подтвердил 0.9.0a33, но обнаружил более старые метаданные source/dist. Это риск происхождения сборки, не разрешение устанавливать найденное дерево.

Пути и строки ниже относятся именно к проверенному wheel. Они нужны как доказательства исследования кода, а не вместо JSON-ссылок на документы.

| Участок | Путь / функция | Фактическое поведение |
|---|---|---|
| Вход записи | `ai_docs_broker/ops/handlers.py:2958`, `register_document` | Проверяет поля, env, продукт, doc_type, файл и метаданные |
| Проверка файла | `ops/handlers.py:573`, `_verify_owui_sha_and_size` | Скачивает байты, сверяет SHA и переданный размер; сейчас не возвращает байты следующему шагу |
| Родитель | `ops/handlers.py:2810`, `_validate_parent_and_range` | Проверяет существование parent; это не доказательство, что сравнивается предшественник того же логического документа |
| Эволюция | `validation/smart_intake.py`, `validate_smart_intake` | Версии сравниваются программно; смысл и CHANGELOG оценивает LLM |
| Запись | `ops/handlers.py:2873`, `_upsert_active_document` | Идемпотентный повтор, конфликт или insert/update; используется также продвижением |
| Другой путь | `ops/handlers.py:3104`, `promote_document` | Может перенести документ без обычной содержательной проверки register_document |
| Канонический JSON узла | `ops/handlers.py:2266`, `register_canonical_node_json` | Также вызывает `_upsert_active_document`; требует общей проверки ссылок с сохранением схемы канонического JSON |
| Изменение метаданных | `ops/handlers.py:3312`, `update_document` | Нужен отдельный учёт изменений типа/контекста; обычный metadata-only update не должен переписывать файл |
| Выбор цели | `ops/handlers.py:2678`, `get_document`; `ops/repository.py` | По умолчанию новейшая активная запись по env/product/doc_type; отдельного надёжного измерения серии нет |

Цепочка записи: OWUI Function → NATS → agent/handler → `register_document` → проверки → `_upsert_active_document` → repository/БД.

### Ограничения нынешней проверки CHANGELOG

- **Проверка смысла не детерминирована:** `changelog_check` запрашивается в LLM-ответе. Это не жёсткая структурная проверка принадлежности текста нужному продукту и документу.
- **Охват ограничен:** `MAX_PROMPT_TEXT_CHARS=24000`; длинный документ целиком модель не видит.
- **Есть пропуски:** первая редакция, некумулятивный тип и отсутствие текста предшественника могут привести к skipped. Поэтому добавление требования ссылок только в LLM-промпт не даёт обязательного контроля.
- **Доверие к inline:** новый и предыдущий тексты могут браться из клиентского payload. Проверка SHA файла отдельно не связывает этот inline с теми байтами, которые прочитает LLM.
- **Нужен надёжный предшественник:** иерархический `parent_doc_id` не следует автоматически считать идентификатором предыдущей редакции. Нельзя сравнить один документ с подставленным клиентом другим.

## Предлагаемый порядок записи

```text
Проверка actor, прав, полей и идентичности документа
  → одно скачивание нового файла, проверка исходных SHA/size
  → получение полного проверенного текста
  → поиск и классификация всех ссылок
  → разрешение целей только по актуальному реестру
  → построение полного плана замен или ошибка
  → нормализация в памяти и повторная проверка всего текста
  → CHANGELOG/evolution по проверенным текстам той же линии документа
  → новый OWUI-файл, только если байты изменились; обратная SHA/size-сверка
  → повторная проверка неизменности контекста и разрешённых целей
  → атомарная запись реестра
  → receipt с фактическими file_id/SHA/size и перечнем замен
```

Предлагаемый модуль: `validation/document_references.py`, сервис подготовки `prepare_document_registration`. Это новые компоненты, не существующие API. Общая точка commit должна требовать внутренний результат проверки, связанный с SHA финального файла и версией политики; клиент не может передать `validated=true`, `skip_refs` или иной обход.

Покрытие обязательно для первой и последующих редакций, всех типов, включая Отчёт Валидации, обычной регистрации, продвижения и `register_canonical_node_json`. Для структурированных документов нормализация должна сохранять валидность их собственной схемы; если схема требует ID как техническое поле, нельзя слепо заменить его строкой JSON: нужно отделить техническую идентичность от рабочей ссылки, а неразрешённый конфликт контракта вернуть ошибкой. Идемпотентный повтор возвращает прежний receipt и явно различает «уже зарегистрировано» и новую проверку. Переклассификация/изменение контекста, способное поменять смысл ссылок, требует повторной проверки; журнал agent_work_log не становится документом и не получает этот guard автоматически.

### Канонический формат

```json
{"op":"get_document","env":"prod","product":"ai_docs_broker","doc_type":"Гайд Пользователя","latest":true}
```

Для обычной рабочей ссылки обязательны эти пять полей; запрещены заменяющие их ID, Files URL и закреплённая версия. Внешний actor остаётся в конверте вызова, не в постоянном адресе. Гайды Пользователя всегда prod; остальные типы не перемещаются автоматически между средами.

Если цель различается по узлу или серии, нельзя удалить эту различимость ради красивого JSON. Текущий общий get_document не доказывает выбор по node, даже если поле принято без ошибки. До подтверждённого канонического разрешения такой цели возвращается `E_DOC_REF_AMBIGUOUS`/`E_DOC_REF_IDENTITY_UNSUPPORTED`; произвольные `series` и `version_prefix` не добавляются. Контракт адресации серий/узлов требуется согласовать отдельно, если эти случаи нужны для включения guard.

## Как работает нормализация

### Найти все ссылки, не полагаясь на LLM

Полный Markdown/JSON/YAML разбирается структурно, дополнительно проводится лексический поиск Files URL, UUID в контексте file_id, doc_id/id и исполняемых get_document-блоков. Проверяются таблицы, reference-style Markdown links, HTML href, code fences, вложенные JSON-строки и приложения. Нельзя исключить все code blocks: там часто находятся настоящие рабочие запросы.

Детерминированный разбор не обещает понять любой намёк естественного языка. Подозрительная неразобранная конструкция в роли документной ссылки считается неуспешной проверкой, а не «ссылок нет». Шаблоны и evidence должны иметь явную проверяемую роль. Просто пометить произвольный блок «history» недостаточно для обхода.

### Разрешить старый адрес

1. Извлечь точный Files UUID или document ID; не выполнять URL как произвольный сетевой запрос.
2. Параметризованно найти соответствия только в текущей таблице документов с проверкой прав вызывающего. Не использовать архив, имя файла или догадку LLM.
3. Сгруппировать версии по доказанной логической идентичности. Несколько версий одной линии не равны нескольким независимым целям; совпадение одного файла у разных продуктов или сред может быть неоднозначным.
4. Проверить продукт/тип/среду по явному контексту ссылки. Межпродуктовая ссылка сама по себе допустима; запрещено незаметно заменить заявленную цель другой.
5. Выполнить каноническое разрешение latest и доказать, что оно остаётся в той же линии. Если привязка есть только у старой записи, которая не является выбранной актуальной целью, без доказанной связи отказ.
6. Проверить доступность и целостность целевого файла, с ограничением размера, времени и числа целей. Не рекурсивно обходить весь граф документов; повторяющиеся цели проверять один раз в рамках операции.
7. Заменить весь рабочий адрес JSON-ссылкой, сохранить видимую подпись и местоположение изменения. Повторно проверить получившийся документ.

API обратного поиска по `owui_file_id` сейчас отсутствует; потребуется внутренний repository-метод и индекс, если план SQL подтвердит необходимость. Нет оснований придумывать колонку `is_current`: актуальность вычисляется по реальному контракту реестра. Даже диагностический поиск «в другом месте» не должен скрыто обращаться к архиву.

### Не искажать доказательства и технические примеры

Датированные ID/версии/SHA как evidence не становятся latest: иначе меняется смысл прежней проверки. Сохранённые исторические приложения и технические шаблоны скачивания Files API не переписываются. Рядом с evidence при необходимости добавляется рабочая JSON-ссылка.

Для автоматического исключения исторического блока нужна проверяемая неизменность относительно авторитетного предшественника либо иная утверждённая схема provenance. Автор не может превратить действующий некорректный переход в «историю» одной меткой. Неустановленная классификация ведёт к отказу с указанием места.

Веб-источники, сессии, пути исходников и бинарные release/test-артефакты не являются ADB-документами только потому, что у них есть URL или UUID. Их не подменяют get_document. Тип файла определяется по фактическому содержимому и MIME; неподдерживаемый формат не принимается с skipped. Для Markdown/JSON/YAML возможна нормализация; PDF/DOCX/ZIP требуют отдельного адаптера или явного отказа, а не притворной текстовой проверки.

## Целостность, ошибки и гонки

- **Единые байты:** проверять inline на точное соответствие декодированным байтам либо игнорировать его как источник истины. Предшественника получать сервером из той же подтверждённой линии; `prev_content` клиента не является доказательством.
- **Автоисправление создаёт новый файл:** исходный OWUI-файл не изменяется. Ответ обязан вернуть реально зарегистрированные file_id, SHA и size, а также original_sha, normalized_sha и список замен. SHA считается по байтам, не по нормализованному верхнеуровневому OWUI hash.
- **Нет частичного успеха:** сначала разрешить все ссылки и пройти содержательные проверки. При одной ошибке не регистрировать документ с остальными исправленными ссылками.
- **Две системы хранения:** OWUI и БД не образуют общую транзакцию. Новую загрузку учитывать как staging, при неуспешном commit оставить явный cleanup receipt и удалить только собственный неиспользуемый staging-файл по безопасной политике. Не обещать невозможную общую атомарность.
- **Конкурентное изменение:** сохранить fingerprint исходной головы и разрешений; непосредственно перед commit проверить их снова. При изменении вернуть retryable `E_DOC_REF_CONCURRENT_CHANGE`, не переключать цель молча. Сетевые вызовы не выполняются под долгой DB-блокировкой.
- **Идемпотентность:** ключ операции привязать к actor/request, исходному SHA, целевой версии и версии политики; повтор не создаёт вторую нормализованную загрузку/запись.
- **Самоссылка и циклы:** каноническая ссылка на публикуемый документ допустима, если точно совпадает с его будущим ключом и проверена в той же транзакции. Несуществующий другой документ даёт ошибку; циклические обычные ссылки сами по себе допустимы, поскольку рекурсивная валидация графа не нужна. Циклы parent-иерархии остаются отдельным запретом.
- **Без обходов:** неполученный текст, тайм-аут, превышение лимита или unsupported format дают явный отказ. Ни `allow_overwrite`, ни dev/test, ни тип документа, ни отсутствие parent не отключают guard.

Предлагаемые коды: `E_DOC_REF_INVALID`, `E_DOC_REF_NOT_FOUND`, `E_DOC_REF_AMBIGUOUS`, `E_DOC_REF_IDENTITY_UNSUPPORTED`, `E_DOC_REF_UNREADABLE`, `E_DOC_REF_UNCLASSIFIED`, `E_DOC_REF_FORMAT_UNSUPPORTED`, `E_DOC_REF_CONCURRENT_CHANGE`, `E_DOC_CONTENT_MISMATCH`. Это проектируемые коды, не уже поддерживаемый API.

Ошибка возвращает для каждого проблемного места: line/column или JSON path, безопасный фрагмент, исходный тип ссылки, причину, список разрешённых кандидатов без утечки чужих данных, действие для исправления. Внешний URL не скачивается произвольно: только разрешённый OWUI origin и UUID через известный Files endpoint.

## Минимальные приёмочные тесты

| Сценарий | Ожидаемый результат |
|---|---|
| Нет документных ссылок, полный текст прочитан | Успех с checked=0 |
| Корректный JSON на доступную актуальную цель | Без изменения файла |
| Один однозначный Files ID; несколько повторений | Все вхождения исправлены, одна проверка цели |
| Doc ID с доказанной актуальной идентичностью | Канонический JSON |
| Гайд Пользователя со старой dev-координатой, однозначная prod-цель | Исправление в prod с проверкой идентичности |
| Разрешённая ссылка на другой продукт | Успех, без ошибочного blanket cross-product запрета |
| Files ID принадлежит разным продуктам/сериям | Отказ без угадывания |
| Файл/запись отсутствуют; 403/404; SHA неверен | Отказ без регистрации |
| Похожее имя файла, но нет подтверждённой связи | Отказ |
| Новая ссылка спрятана после 24 000 символов | Найдена полным сканом |
| Блок кода, HTML href, Markdown reference link, вложенный JSON | Проверены, не пропущены |
| Inline или prev_content не равны доверенным файлам | Отказ, LLM не проверяет подставной текст |
| Evidence с прежним ID/SHA и неизменённая история | Не искажены |
| Рабочий Files URL замаскирован пометкой history | Отказ, а не skip |
| Нет предшественника или тип Отчёт Валидации | Контроль ссылок всё равно выполнен |
| Latest выбирает другую серию; node не учитывается | Явная ошибка идентичности |
| Нормализация меняет байты | Новый file_id, правильные SHA/size, исходник неизменён |
| Ошибка у последней из нескольких ссылок | Ни одной новой записи документа |
| Ошибка commit после загрузки staging | Нет опубликованной записи, staging учтён для cleanup |
| Повтор запроса после потери ответа | Тот же результат, без дублей |
| Цель изменилась между resolve и commit | Конфликт, без тихого переключения |
| Promote/register_canonical_node_json/update-context/allow_overwrite пытаются обойти guard | Проверка не обойдена; схема структурированного документа сохранена |
| Self-reference / будущая чужая цель / A↔B | Самоссылка валидна; будущая цель запрещена; цикл обычных ссылок не запускает рекурсию |
| ZIP/PDF без адаптера, oversized или невалидный текст | Явный unsupported/limit error, не skipped |

## Порядок внедрения

Сначала зафиксировать provenance исходников относительно установленного a33 и согласовать идентичность серий/узлов. Затем реализовать полный скан и dry-run отчёт без изменения реестра, проверить реальные текущие документы и исключения evidence. После этого добавить нормализатор, staging/commit/idempotency и включить обязательный guard на всех путях записи. Финальный gate: положительная и отрицательная матрица, отдельный тест ссылки за пределами 24 000 символов, live-регистрация с нормализацией и доказанный отказ без частичной записи.

Изменение LLM evolution следует отделить от нормализации ссылок, но устранение доверия к непроверенному inline и неверному предшественнику входит в обязательную безопасную границу. Простое добавление строки в существующий LLM-промпт задачу не решает.



## ADB-REF-MON-01: будущий мониторинг целостности документных ссылок

Статус: APPROVED CONCEPT / NOT_IMPLEMENTED. Алгоритм утверждён Оператором 21.09.2026 как часть развития ADB; наличие раздела не означает запуска службы, расписания, исправления runtime или успешной приёмки. Мониторинг использует тот же детерминированный разбор и разрешение ссылок, что и входной контроль регистрации, чтобы два контура не расходились в правилах.

### Область и снимок

1. Получить полный постраничный перечень актуальных документов по всем средам через функции запросов ADB. Не читать `documents_archive`, не включать историю и не считать все строки active одной актуальной редакцией. Для каждого поддерживаемого логического ключа выбрать голову тем же контрактом, которым пользуется `get_document/latest`; отдельные серии и узловые документы нельзя молча объединять.
2. Зафиксировать run_id, время, права/actor, версию политики, количество ожидаемых голов и fingerprint каждого ключа: ID, SHA, размер, file_id, диапазон применимости. Это согласуемый снимок, а не обещание атомарности нескольких сетевых GET.
3. Скачать фактические байты каждой головы, сверить SHA и размер. Кеш допустим только при совпадении fingerprint и ранее доказанной проверке байтов; проверку доступности проводить живым запросом с ограниченным TTL. Отсутствие тела даёт отдельный дефект владельца документа, не «ноль плохих ссылок».

### Поиск и классификация

4. Просканировать полное содержимое поддерживаемого формата, без лимита LLM в 24 000 символов. Учитывать Markdown-ссылки, reference links, HTML, таблицы, code fences, JSON/YAML и строковые вложения; неподдерживаемый формат и превышение лимита дают coverage gap, а не PASS.
5. Отделить рабочую документную ссылку от внешнего веб-источника, артефакта сборки/теста, примера-шаблона и исторического доказательства. Метка history сама по себе не является разрешением пропустить новую ссылку; неизменность исторической части подтверждается provenance. Не обращаться к архиву для её «починки».
6. Для каждой рабочей ссылки проверить канонические поля, допустимость среды/типа, существование актуальной цели, её доступность и идентичность. Гайды Пользователя адресуются только в prod. Для legacy ID построить однозначное соответствие актуальному логическому ключу; отсутствие, несколько кандидатов или потеря серии/узла запрещают автозамену.
7. Различать классы: INVALID_FORMAT, MISSING_CURRENT_TARGET, AMBIGUOUS_TARGET, TARGET_FILE_UNAVAILABLE, OWNER_FILE_UNAVAILABLE, CONTENT_HASH_MISMATCH, UNSUPPORTED_FORMAT, STALE_SNAPSHOT и TRANSIENT_TRANSPORT_ERROR. HTTP 404 означает недоступность в текущем контексте, не доказанное физическое удаление; 401/403, 429, timeout и 5xx не переводятся автоматически в «битую ссылку».

### Подтверждение и выдача

8. Перед окончательной классификацией повторить сомнительный запрос ограниченное число раз с backoff; отдельно сверить метаданные Files и содержимое. Никаких бесконечных retry, смены учётной записи для обхода прав или произвольного скачивания внешних URL.
9. Сопоставить fingerprint голов в конце прохода с начальным. Изменившиеся документы перечитать и перепроверить; при непрерывном изменении пометить STALE, а не закрывать проверку зелёным результатом.
10. Сформировать машиночитаемые findings: run_id, канонический ключ источника, evidence ID/SHA, строка/JSON path, тип и безопасный фрагмент ссылки, ключ цели, ошибка, наблюдения HTTP, уверенность, предложенное действие и владелец. Дедупликация по ключу источника, типу проблемы и нормализованной цели; новое наблюдение обновляет finding, не создаёт поток дублей.
11. Сводка содержит expected/scanned/verified/skipped/unreadable, число проверенных ссылок, открытые/новые/закрытые ошибки и возраст последнего полного прохода. GREEN допустим только при 100% заявленного охвата и отсутствии ошибок; UNKNOWN/BLOCKED не являются GREEN. Отдельно считать качество ссылок и бинарную целостность владельцев, чтобы исправление ссылок не скрыло недоступные документы.

### Исправление и проверка

12. По умолчанию монитор только читает и сообщает. Исполнитель исправлений действует по отдельной политике/разрешению: уникально разрешимый legacy ID заменяется JSON; неразрешённая рабочая ссылка удаляется только при явном разрешении Оператора и без удаления окружающего требования. Если без ссылки теряется обязательное доказательство/зависимость, документ не объявляется годным: сохранить явный GAP/BLOCKED и сообщить владельцу.
13. Не удалять запись реестра, не архивировать документ и не придумывать его отсутствующее тело ради зелёного отчёта. Физически недоступные исходники требуют восстановления подтверждённых байтов либо отдельного решения по жизненному циклу.
14. Любое исправление создаёт полную новую редакцию с честным CHANGELOG, неизменённым историческим evidence, parent/provenance и собственными SHA/size; перед записью выполнить optimistic concurrency check. После записи прочитать latest, скачать файл, проверить bytes/SHA/size и повторно просканировать ссылки. Finding закрывать только подтверждённым readback, а не ответом регистрации.
15. Предусмотреть инкрементальную проверку после публикации, изменения цели или прав доступа плюс периодическую полную сверку. Интервал, бюджет, владельцы и канал уведомления задаются конфигурацией при реализации; этим документом расписание и уведомления не создаются.

### Приёмка мониторинга

Обязательны тесты: битая ссылка после 24 000 символов; legacy ID в таблице/code fence; отсутствующая и неоднозначная цель; dev-ссылка на пользовательский гайд; 404 против 403/timeout; отсутствующий файл источника; неверный SHA; недоступный формат; изменение головы во время обхода; неполная пагинация; дедупликация повторов; отказ без авторизации на запись; полная новая редакция и подтверждённое закрытие finding. Отдельный отрицательный тест должен доказать, что архив не запрашивается и результат с неполным охватом не становится GREEN.


## Ранее действующее содержание Концепта Развития

Ниже сохранены прежние разделы без утраты требований и исторических фактов. Добавленные выше положения имеют приоритет только в части контроля документных ссылок и будущего мониторинга; остальные направления и ограничения сохраняются.


## §CHANGELOG contours-v0.7 относительно contours-v0.6 (2026-09-21)

Полная новая редакция по решению Оператора: исправлены действующие ссылки и правила размещения Гайда Пользователя. Для любого продукта этот тип хранится только в prod, независимо от dev-only/dev-and-prod runtime. Постоянная ссылка содержит ровно op, env, product, doc_type и latest:true, без версии, ID и Files URL:

```json
{"op":"get_document","env":"prod","product":"ai_docs_broker","doc_type":"Гайд Пользователя","latest":true}
```

Поле actor добавляется вызывающей стороной по контракту ADB; это не часть постоянных координат документа. После lookup проверяются возвращённые метаданные и двоичный SHA-256.

Коррекция относится только к документации: runtime, wheel, deploy, сценарии и прежние результаты проверок не менялись и заново не аттестованы. Датированные снимки, ID/версии/SHA в доказательствах и исторические приложения не являются текущими ссылками; они сохраняются как свидетельства своего времени. Прежние требования искать или публиковать пользовательский гайд в dev больше не действуют. Описания старых guard a26/a30 не доказывают сегодняшнюю реализацию; наличие нормативного правила не объявляется успешным runtime-тестом.


Дата подготовки 2026-09-21T05:18:12.913Z. Сессия `ff8e57e3-196c-4b90-9a9f-430c88fa0ff4`.

**Полная редакция для разрешённой регистрации.** Оператор после просмотра четырёх проектов поручил действовать автономно. Разрешение ограничено этими существующими документами dev/ai_docs_broker; runtime/deploy/product state/prod не изменяются. Факт регистрации и точные байты удостоверяются ADB и отдельным readback/receipt, не предположением собственного ID в тексте. Регистрация не означает приёмку продукта. Предыдущий текст включён в NON-ACTIVE HISTORY с согласованными редакционными изменениями; прежние инструкции там не являются текущими.

## §CHANGELOG и назначение

Обновлена граница installed/accepted, сохранены выполненные этапы CTX-H2-01 и bootstrap без объявления всей концепции реализованной. Назначение продукта прежнее: документы, версии и доказательная цепочка H2. Очередь и владельцы исполнения находятся в Дорожной карте, дефекты в Техдолге; этот документ не третий план.

## CTX-H2-01: производный контекст онбординга

Основной владелец: ИИ-Арх ai_docs_broker; общий потребитель: контуры H2/Bridge. Цель: короткий адресный вход без потери источников, истории и зависимостей. Состояние RESEARCHED / PROTOTYPED / PARTIALLY_VERIFIED; автоматическое обновление NOT_IMPLEMENTED. Предыдущий результат от 19 сентября: ready15.593с для ADB и24.995с для Bridge, полная проверка около139с. Это единичные исторические наблюдения, не SLA и не измерение этой сессии.

Принято: структура семантического ядра, маршруты по задаче, dependency manifest, исключение производного контекста из собственной подписи. Отклонено: превращать ready в execution authorization, выдавать последовательные GET за атомарный снимок, автоматически считать контекст свежим после регистрации. Остаток: реализация обновления/инвалидации/атомарного watermark не выполнена; внешние зависимости свежими не объявлены.

Подготовлен context-v0.2: исправлены baseline и адрес Гайда UEPR, сохранён manifest с явными historical/unverified dependencies. Контекст регистрируется после зависимых документов и пересобирается с реальными ID/SHA. Внешние неперепроверенные зависимости остаются явно DIRTY; факт последующей регистрации проверяется через ADB, не обещается этой редакцией. Другой производный контекст Bridge в этой сессии не пересобран и не аттестован; его согласование остаётся в TD-2026-09-19-CTX-01, не предполагает разрешения на запись другому продукту.

## ADB-BOOTSTRAP-01: публичный bootstrap без ослабления actor/ring

Владелец: ИИ-Арх ai_docs_broker, транспортный владелец привлекается только по подтверждённому контрактному разрыву. Цель: получить норму и UEPR через публичный транспорт, затем вести полный actor-журнал в целевом env без чтения секретов в вывод.

Исходная гипотеза о необходимости менять h2_shared для транспорта отвергнута probe: публичный send_request работает в установленном окружении. Частный клиент, чтение HOST_REGISTRY вместо UEPR и снятие ring/actor-гейта отвергнуты. Документная поправка LC06 выполнена и проверена по байтам; функциональный bootstrap доказан вторым probe, но процесс целиком PARTIALLY_VERIFIED из-за journal env mismatch. NOT_IMPLEMENTED здесь относится к отсутствующей полной процедурной коррекции/новому принятому прогону, а не к уже работающему публичному транспорту.

Критерий завершения: чистый воспроизводимый старт по актуальной открытке, полные координаты/SHA/прочитанные разделы, target env без чужой записи, один корректный final, проверяемая история и безопасная доставка evidence. Повторный запуск не разрешается одним наличием этого концепта. Остаток связан с TD-2026-09-17-06 и Дорожной картой.

## Фактическое состояние и границы вывода

Целевой продукт ai_docs_broker, узел heavy02, runtime и документы продукта dev. Назначение: брокер документов и доказательного реестра H2. Последнее поручение: прочитать и выполнить закрытие сессии, не продолжать установку либо запуск нового release. Ранее разрешённая LC06-публикация двух bootstrap-нормативов в prod не является общим разрешением на правку prod.

Датированный baseline: 2026-09-21 около 05:02 UTC, read-only API health/list_deploys/list_live_scenario_runs/get_document перед отчётом. Это НЕ новое наблюдение узловых путей, PID или wheel при закрытии. Runtime ответил 0.9.0a33, DB/disk OK, migration040 behind=0, started_at 2026-09-20T17:44:07.600Z. Узловые source/import/interpreter evidence относятся к установке 20 сентября. Время составления этого документа не обновляет их observed_at.

- **Установленное:** a33 revision2, wheel132, release `482cd297-cb23-419d-bb33-22f08dbf7cc3`; wheel SHA `0a4c7291c9b0b12832deee018aae344ed3db10c82cf817ed277c2a8f3d6d6831`, 302495 bytes, source revision `a83e15b6d236c113e347a77121b348a0cdefad22bba6a2c2107e856daf878e5a`. Точные байты wheel: [Files](https://chat.h2platform.ru/api/v1/files/91604e6a-9794-4932-b4e7-252acb5ad71b/content). Идентичность обеспечивается SHA, не только строкой a33.
- **Принятое ранее:** active deploy96 / wheel109 / a26, SHA `2763747f218e947d042bf0f77f708a3c885d7050bb9ffbc9dc792c3d86c3a803`. Это не installed a33. products_state=a25 является более ранним наблюдением, при закрытии свежая проверка state не выполнена.
- **Live Scenario:** run72 / wheel132, 103 карточки: 65 PASS, 1 FAIL (LS-117), 33 BLOCKED, 4 N/A. Первичное evidence: [LS](https://chat.h2platform.ru/api/v1/files/7fe60607-da47-48ef-9eec-6cd79d42232f/content), SHA `2b143be51968631115d2760579844e88ac56452a8f10f9ffc68d7e3320d72524`. Точный размер этого файла в данном закрытии не сверялся, GAP переносимости не скрыт.
- **Предварительные тесты:** 945 source и 945 isolated-wheel tests прошли в предыдущем этапе; они не заменяют Live Scenario и независимую приёмку.
- **ai_validation:** для a33 NOT_RUN_GATE_BLOCKED. Исторические проблемы a32 (validator version 4.5 против 4.7 и BOM) не объявлены исправленными.
- **UEPR:** зарегистрированный dev UEPR960/a33dev8 отражает installed candidate отдельно от accepted deploy. Аудит952 не является полным аудитом этого последнего UEPR. Независимый Roo-аудит квалифицирован, полный GREEN отсутствует.

Итог продукта: BLOCKED/NOT_ACCEPTED по ЖЦ. Исправлять LS-117 досрочной регистрацией принятого deploy запрещено: ЖЦ v0.6 требует успешные LS и ai_validation до обновления active deploy/product state. Сначала разрешить конфликт candidate-binding по действующему контракту, а не подгонять реестр либо норму под зелёный результат.

## Выполненное LC05 и LC06, не равное завершению ЖЦ

LC05: read-only API-карта 122 deploy / 147 wheel / 28 active стабильна в двух чтениях, без выявленных env-join конфликтов и дубликатов active-групп. API inner join может скрывать физические сироты: CT9/CT10 доказаны только в API-представлении, live FK и полный физический аудит НЕ доказаны. Для stage wheel19/dev wheel21 обнаружен кандидат исключения unique-index; индекс и разрешение исключения не подтверждены. Документы stage510/515 не удалялись.

LC06: опубликованы и прочитаны обратно coder957/coder-v0.13, postcard958/v0.7 и UEPR960/a33dev8. Bootstrap сохраняет обязательный actor; только product_version временно отсутствует до получения активного UEPR. Приватные обходы и HOST_REGISTRY fallback не приняты. В реальном ADB venv Python3.14.3 с h2_shared0.56.80 публичный NATS send_request работает без изменения h2_shared. Первый probe остановился на недостающих ключах после успешного транспорта; второй прошёл функциональный bootstrap, но строгая проверка журнала QUALIFIED_FAIL: одна запись prod3556 вместо dev, строки dev3555/3558/3559/3560. Итог не назван полным независимым PASS.

Roo task `e6f8703c-32cf-4890-8160-38c296803b50`, session `01a0c080-dd30-7768-85aa-21683c2995cd`; затем task `46ac91d9-da48-451e-af81-07321af4ee0f`, session `01a0c085-30e1-7419-be3a-b055a6ecbf92`. Завершённые результаты подтверждались экспортированной историей прежнего этапа. При закрытии list_instances показывает ready, без active_session_uuid для портов9876/9877, но это не новая проверка полной истории всех задач. Мониторинг этих двух задач остаётся у текущего/следующего ИИ-Архитектора; при расхождении сначала read-only история/артефакты, без повторного dispatch. Окна не закрывались ради уборки, чужие окна не тронуты.

Публичная выдача исходных Roo ZIP запрещена: в них встречались стартовые секреты. Производные очищенные ZIP не равны исходным байтам и не доказывают ротацию раскрытых credentials. Инцидент TD-2026-09-19-07 OPEN; ссылки на сырые экспорты в неизменённой истории не являются маршрутами выдачи преемнику.

## Координаты и проверенный документный снимок

Это действующие адреса поиска, не обещание наличия черновиков в ADB. Для серии Техдолга сначала list_documents в dev/ai_docs_broker, затем точная версия серии; latest общего типа «Стандарт» не выбирать вслепую. Узел heavy02 проверяется в теле применимого документа.

- `{"op":"get_document","env":"prod","product":"adb_meta","doc_type":"Закрытие сессии ИИ-Арх","latest":true}`: v0.6, doc 794, SHA `a4b3fb505cbe072cef1c21b85a46e0944a3be8c965c3cf8e33205f8c78727640`, 51371 bytes; observed_at 2026-09-21T05:09:58.531Z; SHA PASS; размер реестра совпал.
- `{"op":"get_document","env":"prod","product":"ai_docs_broker","doc_type":"Онбординг","latest":true}`: executor-v0.42, doc 956, SHA `375878c292861a37b403bdeffa816eaebf371ab7b516dc5c82c9a350fa9739a7`, 59130 bytes; observed_at 2026-09-21T05:10:20.090Z; SHA PASS; размер реестра совпал.
- `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Дорожная Карта","latest":true}`: 0.46.4, doc 954, SHA `c5753cf066c29cbed5963face2351ea70f47f17d4835637449f2ff2d3da06e45`, 420722 bytes; observed_at 2026-09-21T05:10:19.000Z; SHA PASS; размер реестра совпал.
- `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Стандарт","version":"tech-debt-log-v48.4"}`: tech-debt-log-v48.4, doc 831, SHA `5be7a9d83949c4d3657d16a6d855bd4bad18d31d31fd80b3cc24eb15b2dba563`, 235315 bytes; observed_at 2026-09-21T05:10:53.102Z; SHA PASS; размер реестра совпал.
- `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Концепт Развития","latest":true}`: contours-v0.5, doc 708, SHA `0918dccf7e3841faac95b429ce0adef2b8a0d35646ec37fc10edd2575fb61e00`, 79539 bytes; observed_at 2026-09-21T05:10:20.056Z; SHA PASS; размер реестра совпал.
- `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Контекст онбординга ИИ-Арх","latest":true}`: context-v0.1, doc 833, SHA `5bd1042ef61848c089e3089fa45c23a2f9311aa5ccad119d5bacfa1a1245da71`, 45203 bytes; observed_at 2026-09-21T05:10:53.104Z; SHA PASS; размер реестра совпал.
- `{"op":"get_document","env":"prod","product":"adb_meta","doc_type":"Гайд ЖЦ ИТ-продукта H2","latest":true}`: v0.6, doc 830, SHA `bbf1f52be49288ddfa7ff33d0e38a852c408bca6b04a322d721e43409a99226a`, 21258 bytes; observed_at 2026-09-21T05:14:34.236Z; SHA PASS; размер реестра UNKNOWN (поле отсутствует).
- `{"op":"get_document","env":"prod","product":"adb_meta","doc_type":"Гайд UEPR","latest":true}`: 0.13, doc 955, SHA `7cdc8bc0191babc6464edc3ea8fb561582822fa23607e110f747aba1e37562ae`, 64351 bytes; observed_at 2026-09-21T05:14:34.241Z; SHA PASS; размер реестра совпал.

Профильные документы для адресного продолжения:

- `{"op":"get_document","env":"prod","product":"ai_docs_broker","doc_type":"Гайд Пользователя","latest":true}`.
- `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"UEPR","latest":true}`.
- `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Аудит UEPR","latest":true}`.
- `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Live Scenario","latest":true}`.
- `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Отчёт Валидации","latest":true}`.
- `{"op":"get_document","env":"prod","product":"ai_docs_broker","doc_type":"Гайд Аудита","latest":true}`.
- `{"op":"get_document","env":"prod","product":"ai_docs_broker","doc_type":"Онбординг ИИ-Кодера","latest":true}`.
- `{"op":"get_document","env":"prod","product":"adb_meta","doc_type":"Письмо-открытка ии-кодеру ROO для онбординга","latest":true}`.


---
## NON-ACTIVE HISTORY: contours-v0.5 (verbatim, 79539 bytes, SHA 0918dccf7e3841faac95b429ce0adef2b8a0d35646ec37fc10edd2575fb61e00)

# ai_docs_broker: Концепт Развития contours-v0.5

## §CHANGELOG contours-v0.5

Полная кумулятивная редакция по поручению 19.09.2026 закрыть документный этап и сохранить незавершённые концепции. Предыдущая версия `contours-v0.4`, SHA `a2b566852115c2378677c6bbab3dc33ceb6d1a389514586765f07886777c7cf3` сохранена полностью ниже и в evidence-пакете. Регистрация подтверждается ADB/readback, не этим текстом. Контур работы: `ai_docs_broker/heavy02/dev`; разрешены только документы, тип, Files и журнал, без runtime/dispatch/установок.

## Актуальная основа и направления продукта

ADB учитывает документы, узлы, релизы и evidence H2, не заменяя h2_shared, Roo, ai_validation или Context Broker. Сохраняются направления достоверности выдачи, единых actor/документных контрактов, полной release-цепочки, контуров dev/prod, backup/retention/rollback и передачи состояния. CTX-H2-01 развивает передачу, не заменяет эти направления.

Проверены действующие документные версии: ЖЦ v0.6, Онбординг executor-v0.41, Гайд ADB 0.41, ДорКарта 0.45.4 и Техдолг v48.3 до текущей публикации. В прежнем концепте wheel_id-зависимость оставалась в старом приоритете: это устарело, первичная регистрация собственного артефакта предусмотрена до install/LS. ЖЦ v0.6 требует новый цикл для нового SHA и перенос в prod тех же принятых dev-байтов без пересборки.

a26/deploy96/wheel109 и отставший products_state a25 являются датированным документным baseline; текущий процесс заново не измерялся. a30 остаётся offline-кандидатом, не установленным и не принятым. Security OPEN, backup/restore UNKNOWN, фактическая цепочка и разрешения не закрыты. Непосредственная продуктовая работа остаётся read-only CR-01/CR-03 и TD-2026-09-19-01/04, не повторная полная инвентаризация и не установка кандидата.

## CTX-H2-01: заранее подготовленный контекст продолжения

Статус инициативы: RESEARCHED / PROTOTYPED / PARTIALLY_VERIFIED; автоматическая система сборки, актуализации и выдачи NOT_IMPLEMENTED. Публикация документа и регистрация контекстов не означают принятую реализацию или GREEN продуктов. Инициатива остаётся открытой.

### Цель и архитектурное решение

Новый ИИ-Арх получает один файл для `product × node × env`: короткое смысловое ядро, карту «какой документ открыть под задачу» и машинный манифест координат, версий, SHA, размеров и применимости. Вход должен объяснять назначение продукта, состояние, ограничения и направления развития, а не повторять разведку или заставлять читать все документы. Цель начальной ориентации 20–30 секунд является измеряемой целью, не гарантированным SLA.

Исходники истины остаются прежними. Концепт хранит исследование и проектное решение, ДорКарта управляет очередью и ответственностью, Техдолг хранит дефекты, профильные документы задают контракты. Контекст является производным представлением, не самостоятельной очередью работ. Начальная ориентация не равна полномочию на исполнение, актуальному runtime или приёмке продукта.

Предлагаемый жизненный цикл: изменение источника → определение затронутых контекстов → адресное повторное чтение → пересборка → машинная и содержательная проверка → атомарная публикация согласованной версии. Вход новой сессии не должен выполнять этот конвейер заново. Источники зависимости: точные выбранные тела, текущий выбор серии/области, прежние GAP, применимость и политика/карта сборки. При изменении любого из них затронутый пакет DIRTY; собственные производные контексты не входят в подпись своих источников.

Это проект, а не описание реализованного API: новая операция ADB, серверный atomic watermark, background worker и триггеры обновления не созданы. При текущей ручной публикации нужен контроль дрейфа перед записью и readback после неё. Недоступность источника означает адресный GAP, не выдуманный контракт и не остановку всего продукта.

### Исследование и отвергнутые варианты

Подход опирается на краткую навигационную карту OpenAI, выборку минимального информативного контекста Anthropic и восстановимое сжатие Manus; эти материалы не обещают скорость именно Perplexity Computer ([OpenAI](https://openai.com/index/harness-engineering/), [Anthropic](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents), [Manus](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus)). Исследования context files дают неоднозначные результаты: наличие файла само по себе не доказывает улучшения корректности и может увеличивать действия агента ([ETH/LogicStar](https://arxiv.org/html/2602.11988v2), [Lulla и соавторы](https://arxiv.org/html/2601.20404v2)).

Отвергнуты: энциклопедия всех документов в обязательном вводе, обязательный runtime/test/dispatch во время ориентации, выдача исторического наблюдения за текущий факт и самостоятельный вручную поддерживаемый START_HERE. Полное исследование с девятью группами экспертных/экспериментальных источников, ограничениями, сравнением трёх видов кэша и проектом зависимости сохранено в evidence-пакете. Его более ранние формулировки «не зарегистрировано» описывают время исследования, не состояние после этой публикации.

### Выполненные этапы и хронология

| Этап | Факт и результат | Что этим не доказано |
|---|---|---|
| Исправление штатного онбординга | Онбординг executor-v0.41 и Гайд ADB 0.41 опубликованы; обе обычные независимые сессии 19.09 завершили вход примерно за 5:00 и 5:41. Выданы результаты входа и CONTEXT_SNAPSHOT | Безошибочность и ускорение не получены; это не 20–30 секунд |
| Исследование подходов | Подготовлен источник-цитированный разбор context engineering, latency, памяти, freshness и исследований с противоречивыми выводами | Исследование не является работающим сборщиком |
| Локальный сборщик прототипа | Для каждого продукта собраны 29 ролей, проверены 27 уникальных файлов, 19 маршрутов; каталог собственного продукта содержал 134/37 строк. Семь тестов инвалидирования: body, новая строка, удаление, scope, снятие GAP, applicability, policy/routes | Снимок неатомарен; полный транзитивный H2 не аттестован; триггер в runtime отсутствует |
| Первая независимая проба ADB | Ready за 18,330 с; 3 правильных адреса, но requests отверг proxy TLS, 0/3 чтений | Нельзя засчитать чтение или цитаты |
| Независимая проба Bridge | Ready за 24,995 с; 3/3 GET, HTTP 200, SHA/размер совпали; 18 ситуационных ответов | 8 ответов превысили 1–3 роли, 2/7 цитат не дословны по пунктуации, исправленная локальная JSON-ошибка |
| Исправление транспорта и повтор ADB | Curl с обычной TLS-проверкой, без insecure; ready за 15,593 с; 3/3 GET и совпадение байтов; 18 ситуационных ответов | 7 ответов превысили бюджет ролей, 2/6 цитат не буквально точны; первый tool timestamp не экспортирован |
| Документное закрытие | Результаты, ограничения, история и ссылки перенесены в существующие концепты; контексты подготовлены к регистрации отдельным типом по поручению 19.09 | Не заменяет автоматизацию, повторный benchmark финально опубликованных байтов или приёмку runtime |

Ready измерен от серверного создания сессии до экспортированной отметки readiness, до чтения первоисточников. Полная успешная проверка занимала 139,245/139,649 с; стоимость времени предварительной сборки не включена в ready. Малый размер выборки, отсутствие полного tool trace и серверного Files access log не позволяют обещать SLA или абсолютное отсутствие лишних действий. В ADB-журналах трёх проб по их UUID было 0 caller_events и 0 agent_work_log, что согласуется с Files-only тестом, но не доказывает отсутствие действий вне ADB.

### Первичные доказательства и фактические контексты

- **Обычный вход v0.41:** [ADB](https://www.perplexity.ai/computer/tasks/2e5fe357-6c7d-47e9-a043-3aa328ed3a7c), [Bridge](https://www.perplexity.ai/computer/tasks/9352446f-7ca9-4748-b9b2-b071f2e62e37).
- **Прототип, первая ADB-проба:** [сессия с честно зафиксированной TLS-ошибкой](https://www.perplexity.ai/computer/tasks/d9c4da07-1451-451e-9d73-c7d60e91c571).
- **Прототип, Bridge:** [независимая сессия](https://www.perplexity.ai/computer/tasks/23a574a8-6ec0-4624-95b4-701a92362795).
- **Прототип, повтор ADB:** [независимая сессия после curl-поправки](https://www.perplexity.ai/computer/tasks/b5fb6e93-0d58-4e00-88eb-2246eec3326b).
- **Инициирующая сессия и поручения:** [история работы Архитектора](https://www.perplexity.ai/computer/tasks/0f526b82-4553-43a2-81e8-0648a65abdd4).

В evidence-пакете сохранены неизменённые readiness/evaluation/materialized_context каждой пробы, входные файлы обеих редакций, проверки составителя, исследование и исходники локального сборщика. Materialized context является видимым рабочим состоянием, не скрытыми рассуждениями модели и не автономным входным документом без манифеста.

### Остаток и критерий завершения

1. Согласовать нормативную границу «ориентация / начало работы» без отмены обязательного preflight перед исполнением.
2. Разделить в карте первые 1–3 документа и условные дальнейшие чтения; цитаты извлекать буквально, не пересказывать в кавычках.
3. Разрешить затронутые внешние координаты и конфликты dev/prod; не объявлять все документы H2 охваченными по 29 ролям.
4. Реализовать dependency tracking, обработку появления/отзыва источника и изменения review/applicability; атомарную выдачу, защиту от одновременных авторов и проверяемый отказ от stale.
5. Проверить новые/неизвестные задачи и отсутствие прежнего закрытия, а также дрейф концепта, откат источника, частично недоступный реестр и восстановление после ошибки.
6. Провести повторяемый benchmark на разных продуктах, замеряя отдельно ориентацию, первый правильный источник, лишние действия и корректность последующей работы. Регистрация не обнуляет дефекты прототипа.

Завершение CTX-H2-01 возможно лишь при доказанной корректности обновления и выдачи, отсутствии скрытой очереди в контексте, правильной адресной навигации и согласованной нормативной границе. Для конкретной разработки источники читаются по задаче; конечный файл не может заранее содержать все детали произвольных будущих функций. Очередь продолжения и разрешения находятся в ДорКарте; текущие дефекты связаны с CTX-H2-01 в Техдолге.

## Координаты документов

Документные адреса являются поисковыми координатами ADB. Контур хранения не задаёт runtime; для узлового источника проверить применимость в теле. Техдолг ниже выбран по точной серии, не как произвольный latest типа Стандарт.

| Документ | Запрос |
|---|---|
| Концепт продукта | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Концепт Развития","latest":true}` |
| Общая инициатива CTX-H2-01 | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Концепт Развития","latest":true}` |
| Дорожная карта | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Дорожная Карта","latest":true}` |
| Техдолг | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Стандарт","version":"tech-debt-log-v48.4"}` |
| Контекст | `{"op":"get_document","env":"dev","product":"ai_docs_broker","doc_type":"Контекст онбординга ИИ-Арх","latest":true}` |
| Закрытие | `{"op":"get_document","env":"prod","product":"adb_meta","doc_type":"Закрытие сессии ИИ-Арх","latest":true}` |
| ЖЦ | `{"op":"get_document","env":"prod","product":"adb_meta","doc_type":"Гайд ЖЦ ИТ-продукта H2","latest":true}` |
| Онбординг | `{"op":"get_document","env":"prod","product":"ai_docs_broker","doc_type":"Онбординг","latest":true}` |
| Гайд ADB | `{"op":"get_document","env":"prod","product":"ai_docs_broker","doc_type":"Гайд Пользователя","latest":true}` |

## Переносимые первичные доказательства

[Архив CTX-H2-01 с исследованием, прототипами, результатами и полными родителями](https://chat.h2platform.ru/api/v1/files/1dd64943-2e3e-4846-ac3e-36d0ac2d888d/content). SHA-256 `440f5fdbb93bc4bde444ff310d3a6f3b9259f4baded4384ac0cf0e5c951089a8`, размер 363386 байт. ZIP/CRC и каждый член проверены по SHA256_MANIFEST.json. Это зафиксированное evidence, не адрес current-документа ADB и не скрытая очередь работ. История сохранена без редактирования; прототипные registered=false/DRAFT и неактуальные будущие планы в ней относятся к времени пробы.

## История: полное тело предыдущей редакции, NONACTIVE

Ниже неизменённые исторические байты. Старые текущие статусы, контуры, локальные пути и разрешения не являются инструкцией сейчас. Действующие выводы выше и профильные current-документы имеют приоритет.

# ai_docs_broker: Концепт Развития contours-v0.4

## §CHANGELOG contours-v0.4

Полная редакция после независимого холодного старта. Учтён фактический дрейф ЖЦ к 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 внутри датированных наблюдений и истории описывают прошлое,
а не текущую инструкцию.


## Статус публикации

Редакция `contours-v0.4` одобрена Оператором 19.09.2026 для регистрации. Это полный документ, не черновик на согласование. Его регистрация подтверждается ответом ADB и контрольным скачиванием текущей версии с проверкой SHA и размера; собственный будущий ID здесь не предполагается. Разрешение касается только документации и независимой read-only проверки нового ИИ-Арха. Установка a30, изменение runtime, секретов и данных, регистрация wheel/deploy/прогонов не разрешены. Приёмка продукта BLOCKED.

Исторический родитель: version `contours-v0.2`, SHA `fe55ae2814387e6ef06ae594f34a5dac3f432f1328e81473eb61c3f3dbc88e97`. Координаты latest ниже предназначены для текущей редакции, а не поиска родителя.


## §CHANGELOG contours-v0.3

Документные ссылки заменены полными координатами 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}` |
| ai_docs_broker: Гайд UEPR | `{"op":"get_document","env":"prod","product":"ai_docs_broker","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=708; версия=contours-v0.1; SHA-256 `a3180e6ddb9d48db40ddc40569b2a13998856735e60e946468e107243243fb01`.

## Изменения этой полной редакции

Прежний проект контуров преобразован в актуальный продуктовый концепт: heavy02 по active deploy, dev_only, раздельные a26/a30, наблюдаемая очередь и проверяемые критерии вместо старого назначения LIGHT02.

## Цель

Продукт ADB должен выдавать доказуемо актуальную картину продукта и документов,
а новый ИИ-Арх должен различать наблюдаемый runtime, канонический реестр,
неустановленный кандидат, черновик и историческое доказательство.

## Текущее устройство

Контур ADB определяется active deploy: dev / heavy02, a26, deploy96/wheel109.
Старое указание «разработка на light02» относилось к прежней задаче и не назначает
dev-узел ADB. Кандидат a30 заморожен отдельно, есть offline evidence, но он не
установлен. UEPR актуализирован до a26; products_state отдельно не исправлялся, полная согласованность не принята.

## Направления развития

| Блок | Результат | Приёмка |
|---|---|---|
| Достоверность выдачи | onboard сообщает отсутствующие/устаревшие документы, не создаёт ложный ready | Матрица выдачи со всеми обязательными слотами и негативными примерами |
| Контракты документов | Один actor-контракт, полные тексты и содержательный changelog | Current-body review + offline проверки + разрешённые контрактные тесты |
| Release evidence | source/manifest/wheel/deploy/runtime/LS связаны на один релиз | ЖЦ без пропусков, независимый ai_validation |
| Контуры | Один dev-node, prod определяется фактом, N/A не считается дефектом | CT-1..CT-11 с явной применимостью и evidence |
| Эксплуатация | Backup, bounded-retention, наблюдаемость и rollback | Фактические безопасные проверки, отдельное разрешение на restore/изменения |
| Передача сессии | Текущие Дорожная карта и Техдолг, ссылки на исходные доказательства | После обязательного онбординга новый исполнитель восстанавливает состояние и безопасный следующий шаг без отдельного входного документа |

## Приоритеты

Сначала завершить полный-комплект и безопасную сверку доказательств.
Затем согласовать нормативную wheel_id-зависимость, backup и конкретный install
план. После разрешения пройти live gates и только затем публиковать согласованные
результаты. Публикация не используется для маскировки непройденных проверок.
Полная очередь находится в Дорожной карте v0.45 r2, доказательства проблем и критерии закрытия в tech-debt-log v48 r2. Отдельный список работ не требуется.

## Не входит в разрешение этой сессии

Очистка текущих/архивных документов, удаление базы, принудительный STOP, второй
runtime/NATS, миграции и регистрация новых версий. История и данные сохраняются.
## Релиз, установка и критерии 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, разрешения, версии, результаты и команды не исполняются.

# Контуры dev/prod в H2: правило, патч нормативов, приведение к норме (v0.1)

**Автор:** ИИ-Архитектор сессии `31ce3123-d53d-4356-9f45-295a55d8ffc7`, актор `owui_roo_bridge@light02`
**Дата:** 2026-09-18
**Правило контура работ:** доработка ведётся только в `dev` на узле `light02`; в `prod` не пишется ничего, кроме регистрации документов ADB.
**Основание:** поручение Оператора H2 от 2026-09-18.

---

## §0. Правило Оператора (как задано)

1. **Dev-среда любого продукта — строго один сервер.** На этом сервере должны быть **и среда разработки, и wheel**. Версии среды разработки и wheel могут различаться, если идёт разработка — это фиксируется в аудите.
2. **Prod — все остальные серверы.** На prod только wheel. Версия prod-wheel может отличаться от dev-wheel, если релиз ещё не выложен — это фиксируется в аудите.

Дальше это правило называется **Правило Контура**.

---

## §1. Что нормативы говорят сейчас

Проверены три норматива, каждый прочитан целиком по env=prod:

| Документ | doc_id | product | Что про контуры есть |
|---|---|---|---|
| Гайд Аудита UEPR/Код/Онтология v0.1 | 543 | `ai_docs_broker` | **Ничего.** Три оси — UEPR, Код, Онтология. Слова `dev`/`prod` встречаются один раз, в §9: «`register_deploy` в prod → аудит продукта в течение недели». Оси «Контур» нет, проб по составу узла нет. |
| Гайд UEPR v0.2 | 542 | `ai_docs_broker` | **Почти ничего.** Формат UEPR не содержит поля контура. `env` фигурирует только как аргумент операций реестра. §7 «Как проверить чужой UEPR» сверяет wheel_sha256 и deploy_id, но не проверяет, тот ли это контур и тот ли состав узла. |
| Жизненный Цикл ИТ продукта H2 v0.2 | 648 | `adb_meta` | **Частично.** Есть три близких нормы. |

Что именно есть в Гайде ЖЦ (дословно):

- §1: «**Контур** — окружение продукта: `dev` или `prod`.»
- §1: «**Роль узла** — `(product, node) → role ∈ {dev, prod}`. На узле с `role=dev` не могут стоять активные prod-wheel того же продукта.»
- §6 п.10: «**Один продукт × один узел = один активный deploy.**»
- §6.1: «На dev-узле продукта X не может быть активных prod-deploys продукта X.»
- §5 шаг 2: «Сборка выполняется **один раз, на dev-узле**. Пересборка "для prod" запрещена.»
- §5 шаг 1: `smoke_dev_clean(product, node)` — проверка, что на dev-узле нет активных prod-деплоев.

## §2. Чего в нормативах нет

Правило Контура покрыто нормативами примерно на треть. Отсутствуют пять норм.

| # | Недостающая норма | Почему это дыра |
|---|---|---|
| N-1 | **Dev-узел продукта — ровно один.** | Нигде не сказано, что dev-узел единственный. Запрет односторонний: prod-wheel нельзя на dev-узле, но два dev-узла у одного продукта формально разрешены. |
| N-2 | **Узел не может быть одновременно dev и prod.** | Есть только запрет prod-деплоя на dev-узле. Обратное — dev-деплой на prod-узле — не запрещено ни одной строкой. |
| N-3 | **Обязательный состав dev-узла: среда разработки И wheel.** | Гайд UEPR не делает `source_dir`/`tests_dir`/`wheel_local` обязательными; аудит их наличие не проверяет. Dev-узел без исходников проходит все текущие пробы. |
| N-4 | **Обязательный состав prod-узла: только wheel.** | Прямого запрета исходников, тестов и каталогов сборки на prod-узле нет. Запрет пересборки в §5 шаг 2 говорит про процесс релиза, а не про состав узла, и на эксплуатацию не распространяется. |
| N-5 | **Объявляемые расхождения версий.** | Допустимость «исходники впереди wheel» (dev) и «prod-wheel позади dev-wheel» (до промо) нигде не описана, и нет требования фиксировать такое расхождение в аудите. Сейчас это либо молчаливо игнорируется, либо трактуется как ошибка — оба варианта неверны. |

**Вывод:** патч нужен. Ниже точный текст.

---

## §3. Патч нормативов

### §3.1. Область применения Правила Контура

Патч вводит явную область, иначе аудит будет ложно краснеть на мета-записях:

- Правило Контура применяется к **продуктам H2, имеющим wheel** (`kind ∈ {service, tool, library}`).
- **Не применяется** к документным мета-продуктам без wheel (`adb_meta`, `H2`) — у них нет ни среды разработки, ни артефакта установки.
- **Не применяется** к внешним компонентам (`nssm`, `vscode`, `roo_code`, `python_runtime`) — они учитываются как окружение узла, а не как продукты с контуром.
- Продукты-фикстуры и пробы (см. E-13) до пометки `deprecated` формально попадают в область и будут краснеть. Это корректное поведение: их надо либо задепрекейтить, либо привести в норму.

### §3.2. Патч П-1 → Гайд ЖЦ v0.2 (doc_id=648, `adb_meta`), §1 «Определения»

Заменить абзац «Роль узла» на четыре нормы:

> - **Контур продукта** — окружение `env ∈ {dev, prod}`, в котором ведётся учёт артефактов продукта: `wheels`, `deploys`, `products_state`, документы.
> - **Роль узла** — `(product, node) → role ∈ {dev, prod}`.
> - **Dev-контур продукта — ровно один узел.** Для каждого продукта существует единственный узел с `role=dev`. Двух и более активных dev-деплоев одного продукта на разных узлах быть не может. Один и тот же узел может быть dev-узлом для нескольких разных продуктов — это не нарушение.
> - **Prod-контур продукта — все остальные узлы**, на которых продукт эксплуатируется. Их может быть один или несколько.
> - **Узел не может быть одновременно dev-узлом и prod-узлом одного и того же продукта.** Запрет двусторонний: на dev-узле продукта X не может быть активных prod-деплоев X, и на prod-узле продукта X не может быть активных dev-деплоев X.

### §3.3. Патч П-2 → Гайд ЖЦ v0.2, новый §6.2 «Состав узла по контуру»

> **§6.2. Состав узла по контуру**
>
> **Dev-узел продукта обязан содержать оба слоя:**
> 1. Среду разработки — рабочее дерево исходников (`paths.source_dir`), тесты (`paths.tests_dir`), отдельный venv разработки (`runtime.interpreter`), при наличии миграций — `paths.migrations_dir`.
> 2. Собранный wheel — файл по `paths.wheel_local` и соответствующая ему запись `register_wheel(env=dev, ...)`.
>
> Dev-узел без слоя 1 — не dev-узел, а prod-узел, ошибочно помеченный как dev. Dev-узел без слоя 2 не может быть источником промо: промоутится wheel, а не дерево исходников.
>
> **Версия исходников на dev-узле может опережать версию установленного wheel.** Это нормальное состояние активной разработки, а не дефект. Расхождение обязано быть объявлено в Аудите UEPR записью `dev_source_ahead_of_wheel` с обеими версиями. Необъявленное расхождение — дефект.
>
> **Prod-узел продукта обязан содержать ровно один слой:** пакет, установленный из wheel (`paths.installed_package`).
>
> На prod-узле **запрещены**: рабочее дерево исходников (`paths.source_dir` с исходниками), тесты (`paths.tests_dir`), каталоги сборки (`dist/`, `build/`, `wheelhouse/`, `*.egg-info/`) и сборочный инструментарий продукта. Wheel, установленный на prod-узле, обязан иметь запись `register_wheel(env=prod, ...)` с тем же `sha256`, что у dev-записи того же `release_id`.
>
> **Версия wheel в prod может отставать от версии wheel в dev.** Это нормальное состояние до промо. Отставание обязано быть объявлено в Аудите UEPR записью `prod_wheel_behind_dev` с обеими версиями. Необъявленное отставание — дефект.
>
> Обе объявляемые записи не делают вердикт красным: они переводят ось «Контур» в `yellow` с явной причиной. Красный даёт только нарушение состава или единственности узла.

### §3.4. Патч П-3 → Гайд UEPR v0.2 (doc_id=542, `ai_docs_broker`), §2 «Формат»

Добавить обязательный блок и правила заполнения `paths`:

> ```yaml
> environment_contour:
>   env: dev | prod                  # контур, в котором зарегистрирован этот UEPR
>   node_role: dev | prod            # роль ЭТОГО узла для ЭТОГО продукта
>   dev_node: <имя узла>             # единственный dev-узел продукта; одинаков во всех UEPR продукта
>   source_version: <версия|null>    # версия исходников; обязательна при node_role=dev, иначе null
>   wheel_version: <версия>          # версия установленного wheel
>   declared_divergence:             # список объявленных расхождений; [] если их нет
>     - dev_source_ahead_of_wheel | prod_wheel_behind_dev
> ```
>
> Правила заполнения `paths` по контуру:
> - `node_role=dev`: обязательны `source_dir`, `tests_dir`, `wheel_local`; `migrations_dir` — при наличии миграций.
> - `node_role=prod`: обязателен `installed_package`; `source_dir`, `tests_dir`, `wheel_local` обязаны быть `null`.
>
> Значение `environment_contour.dev_node` во всех UEPR одного продукта обязано совпадать. Расхождение означает, что у продукта более одного dev-узла — нарушение §1 Гайда ЖЦ.
>
> Дополнить §6 «Когда обновлять»: UEPR обновляется также при любой смене роли узла и при появлении или снятии объявленного расхождения версий.

### §3.5. Патч П-4 → Гайд Аудита UEPR v0.1 (doc_id=543, `ai_docs_broker`)

Ввести **четвёртую ось «Контур»** (матрица становится 4×N) и новый §3а с шестью живыми пробами. Пробы выполняются на узле, каждая даёт файл в `evidence/`.

| ID | Проба | Как проверяется | FAIL когда |
|---|---|---|---|
| CT-1 | `dev_single_node` | `list_deploys(env=dev, product)`, отобрать `status=active`, посчитать уникальные узлы | число узлов ≠ 1 |
| CT-2 | `dev_has_source` | В dev-UEPR заполнены `source_dir` и `tests_dir`; оба каталога существуют на узле и непусты | поле пустое или каталога нет |
| CT-3 | `dev_has_wheel` | В dev-UEPR заполнен `wheel_local`; файл существует; его `sha256` равен `sha256` записи `register_wheel(env=dev)` активного dev-деплоя | поле пустое, файла нет или sha разошёлся |
| CT-4 | `prod_wheel_only` | На каждом prod-узле продукта отсутствуют `source_dir` с исходниками, `tests_dir`, `dist/`, `build/`, `wheelhouse/`, `*.egg-info/` | найден любой из них |
| CT-5 | `prod_wheel_registered` | `wheel_id` активного prod-деплоя присутствует в `list_wheels(env=prod, product)`; `sha256` записи равен `sha256` установленного на узле файла и равен `sha256` dev-записи того же `release_id` | запись отсутствует или sha разошёлся |
| CT-6 | `contour_separation` | Пересечение множеств активных dev-узлов и активных prod-узлов продукта пусто | пересечение непусто |

Объявляемые расхождения (не FAIL, но обязательны к записи в отчёт):

| ID | Расхождение | Условие |
|---|---|---|
| CT-D1 | `dev_source_ahead_of_wheel` | `source_version > wheel_version` на dev-узле |
| CT-D2 | `prod_wheel_behind_dev` | активная prod-версия wheel < активной dev-версии wheel |

Вердикт по оси «Контур»:
- `green` — 6/6 PASS и `declared_divergence` в UEPR совпадает с фактически обнаруженными расхождениями;
- `yellow` — 6/6 PASS, но обнаружено расхождение, отсутствующее в `declared_divergence` продукта, при наличии его в отчёте аудита;
- `red` — любой FAIL из CT-1..CT-6.

Дополнить §9 «Периодичность и триггеры»: «Аудит оси «Контур» — при каждом `register_deploy` в любом env, а также при смене роли узла.»
Дополнить §8 «Что регистрировать в ADB»: отчёт аудита содержит блок `contour` с результатами CT-1..CT-6 и списком объявленных расхождений.

### §3.6. Владельцы патчей

| Патч | Документ | product | env | Кто вносит |
|---|---|---|---|---|
| П-1, П-2 | Гайд ЖЦ 648 | `adb_meta` | prod | владелец `adb_meta` |
| П-3 | Гайд UEPR 542 | `ai_docs_broker` | prod | владелец `ai_docs_broker` |
| П-4 | Гайд Аудита 543 | `ai_docs_broker` | prod | владелец `ai_docs_broker` |

Ни один из трёх документов не принадлежит `owui_roo_bridge`. Текст патчей подготовлен полностью; применение — по решению Оператора.

---

## §4. Проверка Правила Контура по всем продуктам

**Метод.** `list_products`, `list_deploys`, `list_wheels` по `env ∈ {dev, prod}`; `list_documents` по каждому живому продукту; все UEPR скачаны по `owui_file_id` и разобраны по полям `paths`. Данные: `_data/env_inventory.json`, `_data/uepr_paths.json`, `_data/env_rule_check.json`, `_data/uepr/*.md`.

**Охват.** 49 имён продуктов в реестре, из них 9 живых (есть активный деплой или UEPR): `ai_docs_broker`, `ai_h2_shared_validation`, `ai_validation`, `h2_openbrowser`, `h2_shared`, `owui_perl_bridge`, `owui_perl_bridge_health_monitor`, `owui_roo_bridge`, `ai_connect_orchestrator`. Остальные — фикстуры и пробы.

### §4.1. Сводная таблица

| Продукт | dev-узел | dev wheel | prod-узлы | prod wheel | Правило Контура |
|---|---|---|---|---|---|
| `ai_validation` | light02 | 4.7.0 (id 79) | heavy02 | **нет записи** | ✗ E-04, E-06, E-11 |
| `owui_roo_bridge` | light02 | 0.7.26 (id 83) | нет активного | 0.7.21 (устар.) | ✗ E-07, E-08 |
| `ai_docs_broker` | **нет** | 0.9.0a1/a2, деплоя нет | heavy02, workspace-cloud | 0.9.0a23 | ✗ E-01, E-02, E-04, E-05, E-10 |
| `h2_shared` | **нет** | нет | heavy02 | 0.56.80 | ✗ E-01, E-04 |
| `ai_h2_shared_validation` | **нет** | нет | heavy02 | 1.2.0 | ✗ E-01, E-04 |
| `h2_openbrowser` | **нет** | нет | heavy02 | 0.4.1 | ✗ E-01, E-04, E-05 |
| `owui_perl_bridge` | **нет** | нет | heavy02 | 0.3.9 | ✗ E-01, E-04, E-05 |
| `owui_perl_bridge_health_monitor` | **нет** | нет | heavy02 | 0.1.0 | ✗ E-01, E-04, E-05 |
| `ai_connect_orchestrator` | **нет** | 0.1.0, деплоя нет | нет активного | нет | ✗ E-01, E-12 |
| `si01_probe_perplexity` (проба) | **heavy02 + light02** | 0.1.0 / 0.2.0 | — | — | ✗ E-09 |

**Ни один из девяти живых продуктов Правилу Контура не соответствует.** Ближе всех `ai_validation`: у него единственный настоящий dev-узел с полной средой разработки.

### §4.2. Дефекты

| ID | Сев. | Дефект | Доказательство |
|---|---|---|---|
| E-01 | HIGH | **Dev-контур отсутствует у 7 из 9 живых продуктов.** Ноль активных dev-деплоев у `ai_docs_broker`, `h2_shared`, `ai_h2_shared_validation`, `h2_openbrowser`, `owui_perl_bridge`, `owui_perl_bridge_health_monitor`, `ai_connect_orchestrator`. У пяти из них ноль dev-wheel и ноль dev-UEPR. | `list_deploys(env=dev)` — активны только `ai_validation@light02` (60), `owui_roo_bridge@light02` (63) и две пробы |
| E-02 | HIGH | **Разработка `ai_docs_broker` идёт в prod-контуре.** 36 деплоев в `env=prod` на heavy02, версии от 0.8.0 до 0.9.0a23, 24 деплоя за 6 дней, активный 92 = альфа `0.9.0a23`. В dev — 2 wheel (0.9.0a1, 0.9.0a2) и ни одного деплоя. Dev-loop выполняется на prod-узле в prod-контуре. | `list_deploys(env=prod, product=ai_docs_broker)`; авторы деплоев `coder-adb111@heavy02`, `coder-adb112@heavy02`, … |
| E-03 | HIGH | **heavy02 совмещает контуры.** 8 активных prod-деплоев и одновременно 2 активных dev-деплоя (`ls_probe_b452c8` id 56, `si01_probe_perplexity` id 85). | сводка по узлам из `list_deploys` |
| E-04 | HIGH | **На prod-узле heavy02 зарегистрированы среды разработки 8 продуктов.** `paths.source_dir` заполнен во **всех** prod-UEPR: `C:\H2\ai_Docs_broker`, `C:\H2\h2_shared`, `C:\H2\ai_h2_shared_validation`, `C:\H2\ai_validation_dev`, `C:\H2\h2_openbrowser`, `C:\h2\owui_perl_bridge\src`, `C:\H2\owui_perl_bridge_health_monitor`, `C:\H2\bridge_work\wavei_bridge_src`, `C:\H2\ai_connect_orchestrator`. У `owui_perl_bridge` заполнен и `tests_dir` (`C:\h2\owui_perl_bridge\tests`). | `_data/uepr/*__prod__*.md`, поля `paths` |
| E-05 | HIGH | **Wheel собирается на prod-узле.** `wheel_local` в prod-UEPR указывает внутрь дерева исходников на heavy02: `C:\H2\ai_Docs_broker\dist\...whl`, `C:\H2\h2_openbrowser\dist\...whl`, `C:\h2\owui_perl_bridge\dist\...whl`, `C:\H2\owui_perl_bridge_health_monitor\dist\...whl`. Нарушает и §5 шаг 2 Гайда ЖЦ: «сборка один раз, на dev-узле; пересборка для prod запрещена». | те же файлы UEPR |
| E-06 | HIGH | **Висячая ссылка в активном prod-деплое.** `ai_validation` prod deploy_id=51 (heavy02, `wheel_version=4.7.0`) ссылается на `wheel_id=18`, которого нет ни в `list_wheels(env=prod)` (id 35..104), ни в `list_wheels(env=dev)` (id 50..99). Единственный wheel `ai_validation` (id 79, 4.7.0) зарегистрирован **только в dev**. Prod-эксплуатация без зарегистрированного prod-wheel. | сверка `deploys.wheel_id` × `wheels.id` в обоих env |
| E-07 | MED | **Dev-узел `owui_roo_bridge` без среды разработки.** В dev-UEPR 608 (v0.7.26) `source_dir`, `tests_dir`, `migrations_dir` не заполнены. Единственный путь — `wheel_local = C:\Temp\owui_roo_bridge-0.7.25-py3-none-any.whl`: версия wheel (0.7.25) не совпадает с версией UEPR (0.7.26), и артефакт лежит в `C:\Temp`. | `_data/uepr/owui_roo_bridge__dev__608.md` |
| E-08 | MED | **Два accepted dev-UEPR одной пары (продукт, узел).** `owui_roo_bridge@light02`: doc 608 (0.7.26) и doc 575 (0.7.24), оба `review_status=accepted`. Какой актуален — из реестра не определяется однозначно. | `list_documents(env=dev, product=owui_roo_bridge)` |
| E-09 | MED | **Продукт с двумя dev-узлами.** `si01_probe_perplexity`: активные dev-деплои 85 (heavy02, 0.1.0) и 86 (light02, 0.2.0) — два узла и две разные версии одновременно. | `list_deploys(env=dev)` |
| E-10 | MED | **Брошенный второй prod-узел.** `ai_docs_broker` активен на heavy02 (92, 0.9.0a23) и на `workspace-cloud` (30, 0.8.0rc3, 2026-09-11, `deployed_by=null`). `workspace-cloud` не является сервером платформы. Ранее зафиксировано как F-23. | `list_deploys(env=prod, product=ai_docs_broker)` |
| E-11 | MED | **Каталог с суффиксом `_dev` на prod-узле.** prod-UEPR `ai_validation` (552) описывает heavy02 с `source_dir = C:\H2\ai_validation_dev`, тогда как настоящий dev-узел продукта — light02 (UEPR 602, `D:\ai_validation_dev\ai_validation_code`). Два разных «dev»-каталога на двух узлах у одного продукта. | UEPR 552 и 602 |
| E-12 | LOW | **Продукт без действующего контура.** `ai_connect_orchestrator`: prod-UEPR 555 есть, prod-деплоя и prod-wheel нет; в dev 1 wheel (0.1.0) без деплоя. | `list_deploys`, `list_wheels` оба env |
| E-13 | LOW | **Реестр продуктов засорён.** Из 49 имён ~35 — фикстуры и пробы (`test_adb111_probe_*` ×8, `brief099_*` ×4, `td_cumul_v2_*` ×3, `ls_probe_*`, `_baseline_probe`, `_range_probe`, `probe_dummy`, `obs_probe`, `stage11_h6_*`, …), ни одна не помечена `deprecated`. Плюс дубль имени: `ai_docs_broker` и `ai_Docs_broker`. Продолжение F-21 (та же болезнь в реестре узлов: 41 узел, большинство однодневки вида `adb_reg_ls013_*`). | `list_products` оба env, `list_nodes` |
| E-14 | LOW | **Контракт: `list_documents` не возвращает `owui_file_id`.** Скачать документы пачкой нельзя — нужен отдельный `get_document` на каждый. Поля ответа: `id, env, product, doc_type, version, sha256, size, filename, review_status, uploaded_at, uploaded_by, comment, parent_doc_id, applies_to_version_range`. | прямой вызов |

### §4.3. Главный вывод проверки

Правило Контура нарушено не точечно, а системно: **heavy02 фактически является единственным сервером разработки платформы, но в реестре описан как prod-узел восьми продуктов.** Отсюда следуют E-01..E-05 сразу: dev-контуров нет потому, что разработка идёт в prod-контуре; исходники на prod-узле есть потому, что это и есть рабочее дерево; wheel собирается там же.

Приведение к норме — это не правка полей UEPR, а решение о том, какой узел становится dev-узлом каждого продукта.

---

## §5. Концепт приведения к норме

### §5.1. Этапы

| Этап | Что делается | Исполнитель | Выход |
|---|---|---|---|
| Э0 | Применить П-1..П-4 к трём нормативам | владельцы `adb_meta` и `ai_docs_broker` | Гайд ЖЦ v0.3, Гайд UEPR v0.3, Гайд Аудита v0.2 в prod |
| Э1 | Решение по dev-узлам: какой узел становится dev-узлом каждого из 7 продуктов без dev-контура | **Оператор** | таблица `продукт → dev-узел` |
| Э2 | Развернуть dev-контуры: на назначенном узле создать дерево исходников, venv, тесты; собрать wheel; `register_wheel(env=dev)` + `register_deploy(env=dev)`; выпустить dev-UEPR с блоком `environment_contour` | ИИ-Кодер на узле | 7 dev-контуров, 7 dev-UEPR |
| Э3 | Очистить prod-узел heavy02: вывести деревья исходников, тесты и каталоги сборки; в prod-UEPR обнулить `source_dir`/`tests_dir`/`wheel_local`, заполнить `installed_package` | ИИ-Кодер на узле | 8 чистых prod-UEPR |
| Э4 | Починить ссылки: зарегистрировать prod-wheel `ai_validation` (E-06); снять брошенный деплой на `workspace-cloud` (E-10); свести dev-UEPR `owui_roo_bridge` к одному (E-08); привести `si01_probe_perplexity` к одному dev-узлу либо задепрекейтить (E-09) | ИИ-Арх + Кодер | ноль висячих ссылок |
| Э5 | Гигиена реестра: `deprecated` всем фикстурам и пробам, снять дубль `ai_Docs_broker`, зачистить однодневные узлы | ИИ-Арх | реестр только из живых сущностей |
| Э6 | Прогнать новый аудит оси «Контур» по всем живым продуктам | ИИ-Кодер, проверяю я | зелёная матрица |

### §5.2. Порядок и зависимости

Э0 — первый: без патча аудит нечего проверять, критериев не существует. Э1 блокирует Э2: назначение dev-узлов — решение Оператора, не моё. Э2 обязан идти раньше Э3: пока dev-контура нет, вывезти исходники с heavy02 некуда — иначе разработка встанет. Э4 и Э5 независимы и идут параллельно. Э6 — последний, только после Э2+Э3+Э4.

### §5.3. Развилка Э1, которую надо решить Оператору

Семь продуктов сейчас разрабатываются на heavy02. Варианты:

- **Вариант А — light02 становится общим dev-узлом.** Уже чистый dev-узел (4 активных dev-деплоя, ноль prod). Сохраняет правило «узел не совмещает контуры» без переездов prod. Минус: одна машина держит разработку всей платформы; `h2_shared` — ядро, и его dev рядом с dev моста.
- **Вариант Б — новый выделенный dev-сервер.** Чисто, но требует железа и переноса семи деревьев исходников.
- **Вариант В — heavy02 переобъявляется dev-узлом, prod-эксплуатация переезжает на другие узлы.** Соответствует фактическому положению дел и не требует переноса исходников, но требует переезда восьми prod-сервисов, включая `ai_docs_broker` — сам реестр.
- **Вариант Г — по группам:** ядро (`h2_shared`, `ai_h2_shared_validation`) на один dev-узел, прикладные — на другой.

Моя оценка: **вариант В самый честный по факту и самый дорогой по риску** (переезд реестра). **Вариант А самый быстрый**, и при нём Правило Контура выполнимо уже на следующем аудите. Рекомендую А, с оговоркой: `ai_docs_broker` вынести отдельно, потому что его dev-контур на том же узле, где dev моста, даст связанные простои.

### §5.4. Четыре продукта работы

1. Этот концепт (документ в ADB).
2. Три патча нормативов — текст готов в §3, применение по решению Оператора.
3. Задача ИИ-Арху на Э2..Э5 через мост Roo.
4. Отчёт нового аудита оси «Контур» по всем живым продуктам.

---

## §6. Как проверяется, что стало чисто

### §6.1. Критерий приёмки

Аудит оси «Контур» прогоняется по 9 живым продуктам. Чисто = **9 × 6 = 54 PASS**, ноль FAIL, и для каждого продукта список фактически найденных расхождений версий совпадает со списком `declared_divergence` в его UEPR.

### §6.2. Что именно я буду смотреть

| # | Проверка | Чем подтверждается | Что считаю провалом |
|---|---|---|---|
| 1 | У каждого живого продукта ровно один активный dev-деплой | `list_deploys(env=dev, product)` по всем 9 | 0 узлов или ≥2 узлов |
| 2 | Ни один узел не является dev и prod для одного продукта | пересечение множеств узлов по каждому продукту | непустое пересечение |
| 3 | В каждом dev-UEPR заполнены `source_dir`, `tests_dir`, `wheel_local`, и все три существуют на узле | dev-UEPR + листинг каталогов с узла в `evidence/` | пустое поле или отсутствующий путь |
| 4 | В каждом prod-UEPR `source_dir`, `tests_dir`, `wheel_local` = `null`, `installed_package` заполнен | 8 prod-UEPR | любое непустое из трёх запрещённых |
| 5 | На prod-узлах физически нет `dist/`, `build/`, `wheelhouse/`, `*.egg-info/`, `tests/` продукта | листинг с узла в `evidence/`, не самоотчёт агента | найден любой каталог |
| 6 | `wheel_id` каждого активного prod-деплоя существует в `list_wheels(env=prod)`, sha сходится с установленным файлом | сверка реестра и файла на узле | висячая ссылка или расхождение sha |
| 7 | Расхождения версий объявлены: `dev_source_ahead_of_wheel` и `prod_wheel_behind_dev` присутствуют в UEPR там, где обнаружены фактически | сверка `declared_divergence` × факт | необъявленное расхождение |
| 8 | `product_readiness_report(env, product)` даёт `drift=[]` в обоих контурах по всем живым продуктам | вывод операции | непустой `drift` |
| 9 | Отчёт аудита содержит блок `contour` и зарегистрирован в ADB | `Аудит UEPR` в реестре с sha и размером | отчёт без блока `contour` |

### §6.3. Чего я не приму за доказательство

- Слов агента «привёл в норму», «проверил», «всё чисто» без файлов в `evidence/`.
- Зелёного аудита с нулём выполненных проб — это уже случалось (F-10: `green` при `total=0`; A-07: три dev-прогона `green` при `p=0 f=0 t=0`).
- Правки полей UEPR без фактического изменения состояния узла: обнулить `source_dir` в документе, оставив дерево исходников на prod-узле, — это подделка, а не приведение к норме. Поэтому проба 5 идёт с узла, а не из документа.
- Отчёта, где расхождение версий скрыто вместо того, чтобы быть объявленным. Правило Оператора допускает расхождение и требует его зафиксировать; сокрытие хуже расхождения.

---

## §7. Риски

| ID | Риск | Митигация |
|---|---|---|
| R-1 | Переезд dev-контура `ai_docs_broker` останавливает сам реестр, через который ведётся вся работа | `ai_docs_broker` идёт последним в Э2; на время переезда — окно, согласованное с Оператором |
| R-2 | Вывоз исходников с heavy02 (Э3) выполнен раньше, чем развёрнут dev-контур (Э2) — разработка встанет | жёсткий порядок Э2 → Э3, проба CT-2 зелёная до начала Э3 |
| R-3 | Агент «выполнит» Э3 правкой полей UEPR, не тронув узел | проба 5 §6.2 выполняется листингом с узла; расхождение документа и узла = red |
| R-4 | Патч нормативов применён, а контуры не приведены — аудит станет красным по всей платформе | это ожидаемое и желаемое поведение: красный аудит фиксирует реальное состояние; порядок Э0 → Э6 не меняется |
| R-5 | `h2_shared` — ядро; создание его dev-контура ломает сборки зависимых продуктов из-за расхождения версий | dev-контур `h2_shared` создаётся с той же версией, что в prod (`0.56.80`); расхождение версий вводится отдельным шагом |
| R-6 | Область применения понята слишком широко, аудит краснеет на `adb_meta`, `nssm`, `vscode` | §3.1 фиксирует область явно; фикстуры депрекейтятся в Э5 |
| R-7 | Э1 затягивается, всё стоит | до решения Оператора выполняются Э4 и Э5 — они от Э1 не зависят |

---

## §8. Что нужно от Оператора

| # | Вопрос | Варианты | Моя рекомендация |
|---|---|---|---|
| 1 | Применять ли П-1..П-4 к трём нормативам сейчас | да / сначала обсудить текст | применять; текст в §3 готов дословно |
| 2 | Развилка Э1: какой узел становится dev-узлом семи продуктов | А light02 / Б новый сервер / В heavy02 как dev / Г по группам | А, с выносом `ai_docs_broker` отдельно |
| 3 | Чем считать `workspace-cloud` (E-10) | снять деплой / оставить как отдельный prod-узел | снять: не сервер платформы, запись от 2026-09-11 брошена |
| 4 | Депрекейтить ли 35 фикстур и пробу `si01_probe_perplexity` (E-09, E-13) | да / оставить | да, иначе аудит будет постоянно красным на мусоре |

---

## §9. Выполнено на момент этой версии

- Прочитаны целиком Гайд Аудита UEPR (543), Гайд UEPR (542), Гайд ЖЦ (648) — по env=prod.
- Установлено: Правило Контура покрыто нормативами частично; отсутствуют пять норм N-1..N-5 (§2).
- Написан патч П-1..П-4 дословным текстом в четыре раздела трёх документов (§3).
- Собрана фактура по обоим контурам: 49 продуктов, 70 деплоев, 70 wheel, 41 узел, 12 UEPR скачаны и разобраны по полям.
- Правило Контура проверено по всем продуктам: **соответствия нет ни у одного из 9 живых** (§4.1).
- Зафиксировано 14 дефектов E-01..E-14, из них 6 HIGH (§4.2).
- Описан концепт приведения Э0..Э6 с зависимостями и развилкой Э1 (§5).
- Заданы критерии чистого аудита: 54 PASS, 9 проверок, 4 запрещённых вида доказательства (§6).

Файлы фактуры: `_data/env_inventory.json`, `_data/env_rule_check.json`, `_data/uepr_map.json`, `_data/uepr_paths.json`, `_data/uepr/*.md` (12 UEPR), `_data/nodes_prod.json`.