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

Жизненный цикл пакета h2_shared

Полный текст

# Жизненный цикл пакета h2_shared

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

Правка по приказу Оператора от 30.09.2026 (волна 107, heavy01/MARIA107): в маршрут установки на
новый сервер ДОБАВЛЕН обязательный шаг «Локальная MariaDB (аудит-сток)» — ставится СРАЗУ,
ДО установки моста (owui_roo_bridge) и сервисов Ring 3. Основание: heavy01 был подготован и
получил мост БЕЗ MariaDB (29.09) — жнец моста сутки писал `tick FAILED` (1161 отказ), зачётные
пробы UEPR были частично заблокированы; устранено MARIA107 30.09 (MariaDB 11.4.8, h2_audit
14 таблиц, жнец чистый; prod-UEPR heavy01 doc 1722). В «сложности» добавлены уроки MARIA107:
свойство MSI `SERVICENAME` (не SERVICE_NAME — rc=0 без службы), сид db/schema ДО миграций
(0022 требует llm_logs), terminating-error от stderr нативных команд при
`$ErrorActionPreference='Stop'`. Полный канон — Гайд Пользователя v1.7.17 §6e.

Прочие нормы v0.9 не изменены. Патч документальный: runtime, wheel, deploy и прежние результаты
проверок не менялись и заново не аттестованы.

## §CHANGELOG v0.9 относительно v0.8 (2026-09-29)

Дополнение по поручению Оператора от 29.09.2026: добавлен раздел «Установка на новый сервер: сложности и лучшая практика» — фактические затруднения, встреченные при подготовке узлов heavy01, h2-br-srv (H2-BR-SRV, 10.0.120.2) и h2-appsrv (H2-APPSRV, 10.0.120.3), и выработанный маршрут установки. Основание — задачи H01RECON/H01PREP/H01TOOLS/H01BRIDGEPREP/H01PROVRECON/H01PROVISION и NEWSRV-RECON/NEWSRV-PREP (29.09.2026, деплои 205, 208, 209–212).

Прочие нормы v0.8 не изменены. Патч документальный: runtime, wheel, deploy и прежние результаты проверок не менялись и заново не аттестованы.

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

Точечная правка по решению Оператора от 29.09.2026: закреплены зоны ответственности при подготовке нового узла H2 под продукты h2_shared. Роль внешнего provision-процесса узла исполняет ИИ-Архитектор h2_shared: структура каталогов узла, перенос wheel-байтов, offline-установка ядра и prod-инструментов, перенос NSSM-бинаря с SHA-сверкой, создание node.json по канону Онтологии (собственные node_id, config_id и integrity-хэш через публичный API установленного пакета), проверка наличия секретов с фиксацией инструкции по их заведению, регистрация деплоев и UEPR узла. Валидаторы (`ai_validation`, `ai_h2_shared_validation`) в prod-контур узла не ставятся: их контур — валидация dev-релизов. VS Code, его расширения и установку самих мостовых продуктов ведут архитекторы мостов; значения секретов создаёт только Оператор, и они не проходят через агентов.

Прочие нормы v0.7 не изменены. Патч документальный: runtime, wheel, deploy и прежние результаты проверок не менялись и заново не аттестованы. Основание — подготовка узла heavy01 (prod deploy h2_shared 205; коррекция Оператора от 29.09.2026 по составу инструментов на prod-узле).

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

Точечная правка по решению Оператора от 27.09.2026: синхронизация с Гайдом UEPR v0.23 (doc 1429) и Гайдом Аудита v0.2.10 (doc 1430) — узел вынесен в название doc_type UEPR и аудитов. Причины — дефекты реестра документов DEF-UEPR-SLOT-COLLISION-20260926 (doc 1418) и DEF-UEPR-NODE-FILTER-20260927 (doc 1427): поле `node` в реестре отсутствует, чтение узлы не различает.

Изменения: шаблоны адресации Dev-UEPR, Аудита UEPR и Prod-UEPR переведены на узловые doc_type «UEPR <node>»/«Аудит UEPR <node>», нерабочий параметр `node` из шаблонов убран; нормативный адрес Гайда UEPR исправлен на `prod/h2_shared/Гайд UEPR` (фактическое место серии v0.19–v0.23); в «Размещении документов» закреплено хранение UEPR в узловых типах и запрет новых регистраций в общих типах «UEPR»/«Аудит UEPR».

Прочие нормы v0.6 не изменены. Патч документальный: runtime, wheel, deploy и прежние результаты проверок не менялись и заново не аттестованы.

## §CHANGELOG v0.6 относительно v0.5 (2026-09-22)

Точечная правка по поручению Оператора: prod-запись wheel создаётся один раз после зелёного на dev, а не при каждой установке на prod-node. Добавлен п.15а (однократная регистрация тех же байтов принятого dev-wheel в `env=prod` как отметка «готово к выдаче»); в п.16 закреплено, что dev- и prod-записи одного wheel сравниваются только по SHA-256 и Files ID; в п.17 установка на prod-node идёт из этой prod-записи с регистрацией prod deploy на неё; в Критерий готовности добавлен один пункт. Правка согласована с Гайдом Аудита v0.2.6 (CT-5). Прочие нормы v0.5 не изменены. Патч документальный: runtime, wheel, deploy и прежние результаты проверок не менялись и заново не аттестованы.

## §CHANGELOG v0.5 относительно v0.4 (2026-09-21)

Полная новая редакция по прямому поручению Оператора об очистке битых документных ссылок. Исправлены подтверждённые действующие адреса: Гайд UEPR принадлежит prod/adb_meta, а не prod/ai_docs_broker; в процедуре закрытия дополнительно исправлена среда Онтологии h2_shared на dev и шаблон пользовательского гайда на prod. Для этой редакции заменено 1 JSON-ссылок/шаблонов (1 UEPR, 0 Онтология); изменения не отменяют требований документов.

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


## §CHANGELOG v0.4 относительно v0.3 (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":"h2_shared","doc_type":"Гайд Пользователя","latest":true}
```

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

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


**Версия:** v0.4  
**Статус:** ACTIVE  
**Назначение:** применённый к библиотечному Python-пакету `h2_shared` норматив его
сборки, проверки, выпуска и эксплуатации как зависимости внешних агентов.  
**Принцип:** пакет принимается только по фактическим evidence одного release, а не
по декларациям, именам файлов или прежним результатам.

## Что нового

v0.3 подтверждает node-local правило Ring 0: на каждом сервере используется
свой канонический `node.json`; файл одного узла не является конфигурацией или
донором конфигурации другого. Это уточнение добавлено по read-only
аттестации laptop и не меняет release, deploy либо runtime.

v0.2 уточняет единый механизм установки `h2_shared` во внешнее окружение
потребителя и разные роли обязательных внешних проверок. Пакет не является
самостоятельно запускаемым агентом или сервисом: зачётный Live Scenario запускает
внешний агент `test_guide`, а обязательную независимую валидацию exact release
выполняет `ai_h2_shared_validation`. Результат другого продукта, включая
`ai_validation`, не заменяет эти проверки. Гайд Пользователя `h2_shared` является
внешним фасадом для Кодеров и ИИ-Архитекторов, а не описанием самостоятельного
пользовательского runtime пакета. Нормы `Гайд ЖЦ ИТ-продукта H2 v0.6` сохранены
во всём, что не изменено явно этим документом.

Норма устанавливает единые координаты ADB для документов, фактическую карту
пакета из active deploy, доказательную цепочку release и обязательную независимую
валидацию специальным агентом `ai_h2_shared_validation`.

## Область применения

ЖЦ применим только к `h2_shared` как пакетируемому артефакту. Базовые правила
ЖЦ H2 обязательны, а стадии сборки, установки и продвижения относятся к wheel
пакета. Вид пакета, внешние агенты-потребители, транспорт и способ проверки
определяются документацией `h2_shared`.

`ai_h2_shared_validation` является обязательным специальным агентом независимой
валидации принимаемого release `h2_shared`. Он не собирает wheel, не выполняет
deploy и не изменяет пакет.

## Термины

- **Пакет** — библиотечный Python-артефакт с именем `product=h2_shared`, release и evidence.
- **Узел** — сервер продукта с именем `node`.
- **Dev-node** — единственный узел активной разработки продукта.
- **Prod-node** — каждый иной узел активной эксплуатации продукта.
- **Release** — единая принимаемая совокупность source revision, артефактов, manifest, deploy и evidence.
- **Runtime evidence** — фактическое наблюдение запущенного процесса внешнего потребителя: node, interpreter, import path, версия, SHA артефакта и время наблюдения.

Для `h2_shared` на одном узле существует ровно один активный runtime-набор,
который импортирует пакет. Dev-среда разработки и установленный dev-артефакт
являются слоями одного dev-контура, а не двумя одновременно работающими контурами.

Проверки выполняются в существующем назначенном контуре. Отдельные тестовые БД, схемы-дубликаты, второй runtime-набор и неидентифицированные остановки процессов запрещены.

## Node-local топология Ring 0

`h2_shared` — мультисерверный пакет Ring 0. Каждый узел получает уникальные
для него сведения только из собственного канонического
`C:/ProgramData/H2/config/node.json`; переменная `H2_NODE_CONFIG` указывает
именно на этот файл данного узла. В репозитории пакета нет writer этого файла:
его создание, атомарная публикация и назначение переменной относятся к
внешнему процессу provision/deploy узла. На узлах H2 эту роль внешнего
provision-процесса исполняет ИИ-Архитектор h2_shared по команде Оператора:
файл создаётся по канону Онтологии §K.4 с собственными node_id, config_id,
config_revision и integrity-хэшем (канонический payload SHA-256 вычисляется
публичным API установленного пакета), публикуется атомарно в
`C:/ProgramData/H2/config/node.json` и проверяется
`load_node_config`/`validate_node_config`. Запреты, закреплённые ниже
(копирование файла другого узла, шаблоны с готовыми значениями), сохраняются.

`node.json` содержит node-local профильные ссылки, а не переносимый между
узлами набор endpoint, DSN либо секретов. Поэтому запрещено копировать,
подменять или использовать как шаблон с готовыми значениями `node.json`
другого сервера. Laptop с проверенным локальным каноническим файлом
подтверждает ожидаемую топологию Ring 0, но не доказывает наличие,
корректность или доступность NodeConfig на `light02/dev`. Для `light02`
требуется собственный файл с `node_id=light02`, собственный SHA-256 и
отдельное runtime evidence.

### Зоны ответственности при подготовке нового узла (v0.8)

- **ИИ-Архитектор h2_shared** — подготовка узла целиком, кроме перечисленного
  ниже: структура каталогов (`C:\H2`: wheels, deps, venv, bridge_work,
  incoming, nssm, evidence), перенос колёс с узла-донора без двойного хода,
  offline-установка ядра и prod-инструментов, перенос NSSM-бинаря с
  SHA-сверкой, создание node.json, проверка наличия секретов и фиксация
  инструкции по заведению недостающих, регистрация деплоев, prod-UEPR узла.
- **Оператор** — значения секретов (`DEEPSEEK_API_KEY` и другие): создание,
  размещение, ротация. Значения не проходят через агентов и не печатаются
  в evidence.
- **Архитекторы мостов** — VS Code, его расширения (Roo Code, локальные
  bridge-расширения) и установка самих мостовых продуктов
  (`owui_roo_bridge`, `owui_perl_bridge`).

### Установка на новый сервер: сложности и лучшая практика (v0.9)

Фактические затруднения, встреченные при подготовке узлов (heavy01, h2-br-srv,
h2-appsrv):

1. **Состав prod-контура не выводится из реестра деплоев.** У валидаторов
   (`ai_validation`, `ai_h2_shared_validation`) есть активные prod-деплои на
   старых узлах; механическое зеркалирование реестра привело к ошибочной
   установке валидаторов на heavy01 с последующим откатом. Правило: prod-контур
   нового узла — ядро `h2_shared` + `test_guide` (node-port Live Scenario);
   валидаторы не ставятся.
2. **Перенос без двойного хода.** NTLM-аутентификация запрещает вторичный ход:
   все переносы — двумя последовательными PSSession через узел-исполнитель
   (например light01) или через admin-шары `\\<ip>\c$` с DPAPI-кредой.
   `Copy-Item -ToSession` упирается в лимит `MaxEnvelopeSize` WS-Management
   (файл 368 КБ не проходил); обход — чанковая передача, но она медленная.
   Лучшая практика — admin-шары: на h2-br-srv/h2-appsrv перенос 34 файлов
   прошёл одним способом, без чанков.
3. **Python на целевом узле.** Новый сервер может быть без Python. Инсталлятор
   скачивается ТОЛЬКО на узле-исполнителе (единственный с интернетом),
   переносится в `C:\H2\incoming` и ставится тихо:
   `/quiet InstallAllUsers=1 TargetDir=C:\Python\Python313 AssociateFiles=0
   Shortcuts=0`, ожидание — поллингом до 10 минут. Версия — одна на всех узлах
   (3.13.x, cp313-колёса зависимостей).
4. **Зависимости offline.** deps-колёса готовятся заранее на узле-исполнителе
   (`pip download --only-binary=:all: --python-version 3.13 --implementation cp
   --abi cp313 --platform win_amd64`). Добор зависимостей на целевом узле без
   интернета невозможен — состав продуктов определять ДО подбора зависимостей
   (см. п.1).
5. **node.json.** `validate_node_config` принимает path/str/dict, но НЕ объект
   NodeConfig (`E_NODE_CONFIG_IO: expected path or dict`). Правильные формы:
   `validate_node_config(r'C:\ProgramData\H2\config\node.json')` или
   распарсенный dict. Целевой вызов `load_node_config()` без аргументов —
   только проверка загрузки.
6. **Имена и локаль.** Имя узла-исполнителя может не резолвиться (light01 =
   локальный LIGHT-1) — использовать IP. Кириллическая локаль: `net
   localgroup` пусто, состав админов — `Get-LocalGroupMember -SID
   S-1-5-32-544`.
7. **Чужое на узле.** На серверах уже живут чужие службы (`h2-bridge`,
   MSSQL, NATS) и данные (`C:\H2\Bridge_1C`, `1c_h2` и т.п.) — разведка
   `C:\H2` (Recurse -Depth 1) перед любым изменением обязательна, ничего
   не затирать, службы не трогать.
8. **Отчёты исполнителей.** Текст завершения Roo-задачи обрезается (~4000
   символов): полное evidence писать в файл на узле
   (`C:\H2\h2_shared\evidence_install.md`), отчёт держать компактным.
   Автоматические SHA-сводки могут давать ложные «bad» (артефакт маппинга
   путей) — финальная сверка прямым подсчётом по каждому файлу.
9. **RECORD.** Число строк RECORD одного и того же wheel может отличаться на
   1 между узлами (697 vs 698 на heavy01) — не блокер, но расхождение
   фиксировать в evidence и проверять точечно.

10. **MariaDB до моста.** Отсутствие локальной MariaDB на подготовленном узле не
   блокирует установку моста (мост стартует), но жнец моста сразу начинает писать
   `tick FAILED` в stderr (60-секундный тик), а пробы UEPR, зависящие от h2_logs-стока,
   блокируются. MariaDB — прелиминарный компонент узла (Гайд v1.7.17 §6e): ставится
   ДО установки моста. Уроки MARIA107: свойство MSI — `SERVICENAME` (передача
   `SERVICE_NAME` даёт rc=0 без создания службы); канонический сид `db/schema/*.sql`
   обязателен ДО миграций (миграция 0022 требует базовую таблицу `llm_logs`);
   при `$ErrorActionPreference='Stop'` stderr mariadb.exe — terminating error
   (использовать 'Continue' в скриптах установки); elevated-запуск `-Verb RunAs`
   несовместим с `-RedirectStandardOutput/Error` (elevated-скрипт пишет свой лог).

**Лучший маршрут установки на новый сервер** (порядок обязательный):

1. Разведка (READ-ONLY): hostname/whoami/OS/RAM/диск, Python, `Test-Path`
   C:\H2, C:\opt\h2, VS Code, C:\ProgramData\H2, службы h2/nssm/nats,
   NATS `Test-NetConnection 192.168.99.11 -Port 4222`, `C:\Users`, дерево
   `C:\` и `C:\H2`.
2. Регистрация узла в ADB (`register_node`: node_id = hostname в нижнем
   регистре, class, purpose).
3. Перенос с узла-донора: 6 колёс `C:\H2\wheels` + deps + `nssm.exe`
   → admin-шара `\\<ip>\c$` (fallback: два PSSession + чанки);
   SHA-256 каждого файла на источнике и цели.
4. Python: при отсутствии — тихая установка из `C:\H2\incoming` (п.3 выше).
5. venv + offline-установка ядра и `test_guide` (`--no-index --find-links`),
   `pip check`, версии, RECORD → `evidence_install.md` на узле.
6. Каталоги: `C:\H2\bridge_work`, `C:\H2\incoming`, `C:\H2\h2_shared\logs`.
7. `node.json` по канону Онтологии §K.4 (собственные node_id, config_id,
   integrity через публичный API установленного пакета; атомарная публикация;
   валидация формой path/dict).
8. Секреты: проверка наличия (только имена), инструкция по заведению
   недостающих (значения — только Оператор, через агентов не проходят).
9. Регистрация деплоев в ADB (`h2_shared`, `test_guide`) с полным
   комментарием-evidence; компактный отчёт Оператору.

10. **Локальная MariaDB (аудит-сток) — ДО установки моста и сервисов Ring 3**
    (Гайд v1.7.17 §6e): официальный MSI LTS (SERVICENAME=<имя службы>, PORT=3306,
    SERVICESTARTTYPE=Auto, ALLOWNETWORK=0, UTF8=1), учётка и DSN по kv-тиру узла
    (`mariadb_audit_url`), сид `db/schema/*.sql` ДО миграций, канонический раннер
    14 миграций (идемпотентно, эталон h2_audit = 14 таблиц), критерий готовности:
    0 `tick FAILED` за >=5 тиков + прирост h2_logs + `h2-logs recent-errors` rc=0.
    В UEPR узла — раздел «База данных (audit-сток)» со списком таблиц
    (образец: prod-UEPR heavy01 doc 1722).
11. Установка мостовых продуктов и VS Code (зона архитекторов мостов) — только
    ПОСЛЕ шага 10; жнец моста с первого тика обязан находить живой h2_audit-сток.

Ссылочная реализация: heavy01 (деплой 205/208; MariaDB — MARIA107, UEPR doc 1722)
и h2-br-srv / h2-appsrv (деплои 209–212), 29–30.09.2026.


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

Каждая ссылка на документ задаётся координатами поиска ADB. В нормативном тексте не используются ADB ID, version, имя файла, SHA прошлой версии или неформальная ссылка «актуальный документ».

После получения документа исполнитель скачивает бинарное тело через Files API и сверяет SHA-256 с metadata. Полученные ID, version, file ID и SHA фиксируются в evidence конкретного release.

### Платформенные документы

**Онбординг:**

```json
{"op":"get_document","env":"prod","product":"ai_docs_broker","doc_type":"Онбординг","latest":true}
```

**Гайд Пользователя ADB:**

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

**Гайд UEPR:**

```json
{"op":"get_document","env":"prod","product":"h2_shared","doc_type":"Гайд UEPR","latest":true}
```

**ЖЦ ИТ-продукта H2:**

```json
{"op":"get_document","env":"prod","product":"adb_meta","doc_type":"Гайд ЖЦ ИТ-продукта H2","latest":true}
```

### Документы продукта

**Онтология:**

```json
{"op":"get_document","env":"dev","product":"<product>","doc_type":"Онтология","latest":true}
```

**Гайд Архитектора:**

```json
{"op":"get_document","env":"dev","product":"<product>","doc_type":"Гайд Архитектора","latest":true}
```

**Гайд Пользователя:**

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

Для `h2_shared` этот документ является обязательным внешним фасадом для
Кодеров и ИИ-Архитекторов. Он описывает, как потребитель вызывает публичные
контракты пакета, а не самостоятельный runtime пакета.

**Дорожная Карта:**

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

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

```json
{"op":"get_document","env":"dev","product":"<product>","doc_type":"Концепт Развития","latest":true}
```

**Стандарт:**

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

**Live Scenario:**

```json
{"op":"get_document","env":"dev","product":"<product>","node":"<dev_node>","doc_type":"Live Scenario","latest":true}
```

Для `h2_shared` зачётный сценарий исполняет внешний агент `test_guide`, который
устанавливает candidate wheel и проверяет его через публичную границу.

**Отчёт Валидации:**

```json
{"op":"get_document","env":"dev","product":"<product>","node":"<dev_node>","doc_type":"Отчёт Валидации","latest":true}
```

**Dev-UEPR:**

```json
{"op":"get_document","env":"dev","product":"<product>","doc_type":"UEPR <dev_node>","latest":true}
```

**Аудит UEPR:**

```json
{"op":"get_document","env":"dev","product":"<product>","doc_type":"Аудит UEPR <dev_node>","latest":true}
```

**Prod-UEPR:**

```json
{"op":"get_document","env":"prod","product":"<product>","doc_type":"UEPR <prod_node>","latest":true}
```

## Размещение документов

В `dev` находятся Онтология, Гайд Архитектора, Дорожная
Карта, Live Scenario, Отчёт Валидации, dev-UEPR и Аудит UEPR.

Гайд Пользователя любого продукта всегда канонически хранится в `prod`, включая dev-only продукты. Он описывает все доступные пользователю среды; наличие prod-runtime не является условием публикации.

На каждом active prod-node существует отдельный prod-UEPR. Начиная с Гайда UEPR v0.23 (doc 1429) UEPR каждого узла хранится в узловом doc_type «UEPR <node>» (например «UEPR light01»), аудиты продукта — в «Аудит UEPR <node>», инвентаризация узла — в «Аудит узла <node>» (Гайд Аудита v0.2.10, doc 1430). Новые регистрации UEPR и аудитов в общих типах «UEPR»/«Аудит UEPR» запрещены; существующие строки остаются историей. Онтология, Гайд Архитектора, Live Scenario и Аудит UEPR не являются обязательными prod-документами.

Каждая новая версия документа создаётся полным текстом. Исторические версии сохраняются в истории и не удаляются из-за появления новой версии.

## Роли

- **Оператор** — задаёт цель и разрешает опасные либо необратимые действия.
- **ИИ-Архитектор `h2_shared`** — определяет контур пакета, пишет бриф, проверяет evidence и принимает release.
- **ИИ-Кодер `h2_shared`** — выполняет утверждённый бриф на назначенном узле, собирает wheel, выполняет deploy и формирует evidence.
- **`test_guide`** — внешний исполнитель зачётного Live Scenario candidate wheel.
- **`ai_h2_shared_validation`** — независимый обязательный агент валидации release.

Кодер не начинает работу без письменного брифа с TASK_ID. Для одной пары `(product, node)` одновременно открыта не более одной задачи Кодеру.

## Фактическая карта продукта

Перед чтением документов, началом работ или аудитом Архитектор определяет карту
пакета только по active deploy:

1. получает active deploy в `dev`;
2. получает active deploy в `prod`;
3. фиксирует product, node, env, deploy ID, wheel ID, version, SHA-256 и время каждого deploy;
4. ровно один active dev deploy определяет `dev_node`; для планируемого
   восстановления `h2_shared` им должен стать `light02`, но только после
   успешного зарегистрированного dev deploy;
5. отсутствие active prod deploy означает `dev_only`;
6. один или более active prod deploy означает `dev_and_prod`;
7. каждый active prod deploy требует отдельный prod-UEPR той же пары `(product, node, env=prod)`.

Документы подтверждают фактическую карту, но не определяют её. Назначение
`light02` в bootstrap-UEPR не заменяет active dev deploy.

## Нормальный release-цикл

### Подготовка

1. Архитектор создаёт либо обновляет Дорожную Карту `h2_shared` в `dev`.
2. Кодер получает бриф с TASK_ID, назначенным node, ожидаемым release и критериями evidence.
3. До установки candidate wheel Кодер подтверждает единственность назначенного контура, доступность зависимостей внешнего сценария, отсутствие второго runtime-набора и работоспособность launch-lock.

### Сборка и dev-приёмка

4. Кодер фиксирует неизменяемые `source.ref` и `source.revision`, затем собирает артефакт на dev-node.
5. Для каждого компонента фиксируются версия, SHA-256 и Files ID. Создаётся единый release manifest:

```json
{
  "release_id":"<uuid>",
  "product":"<product>",
  "source":{"ref":"<immutable reference>","revision":"<immutable revision>"},
  "components":[
    {"name":"<component>","version":"<version>","sha256":"<64hex>","owui_file_id":"<uuid>"}
  ],
  "built_on":"<dev_node>",
  "built_at":"<UTC ISO-8601>"
}
```

До установки и приёмочного Live Scenario артефакт загружается и регистрируется в ADB. Полученный `wheel_id` связывается с его SHA-256 и release manifest. Регистрация артефакта не означает успешную валидацию или приёмку release.

6. Кодер устанавливает артефакт обычной non-editable установкой в назначенное dev-окружение внешнего потребителя. Сам пакет не запускается как отдельная служба или агент.
7. Кодер фиксирует runtime evidence:

```yaml
observed_at: "<UTC ISO-8601>"
product: "<product>"
env: "dev"
node: "<dev_node>"
release_id: "<uuid>"
sys_executable: "<absolute path>"
module_file: "<absolute import path>"
package_version: "<observed version>"
wheel_sha256: "<64hex>"
```

8. Архитектор выполняет Guide-Runtime Parity: получает внешний Гайд Пользователя
`h2_shared` по координатам ADB, подтверждает SHA-256 бинарного тела, сверяет
операции, обязательные поля и примеры вызовов с публичным контрактом установленного
пакета.
9. Внешний агент `test_guide` выполняет Live Scenario по подтверждённому
пользовательскому гайду. Зачётный Live Scenario выполняется после установки
зарегистрированного артефакта. Проверки исходников до сборки являются
предварительными и не заменяют этот прогон. Зачётный run содержит:

```yaml
run_id: "<unique ID>"
product: "<product>"
env: "dev"
node: "<dev_node>"
release_id: "<uuid>"
product_version: "<version>"
wheel_id: "<ADB wheel ID>"
wheel_sha256: "<64hex>"
source_revision: "<immutable revision>"
total: "<positive integer>"
passed: "<integer>"
failed: 0
verdict: "passed"
evidence_ref: "<immutable evidence>"
```

10. Runtime внешнего потребителя остаётся наблюдаемым во время проверки и
публикует согласованное актуальное состояние установленного пакета.
11. `ai_h2_shared_validation` получает release evidence и выполняет полный
применимый чек-лист. Его Отчёт Валидации связан с тем же release ID, dev-node,
wheel ID, wheel SHA и ненулевым total. Результат другого продукта, включая
`ai_validation`, не заменяет этот отчёт.
12. Архитектор отдельно принимает source, wheel, runtime evidence, Live Scenario
`test_guide`, UEPR и результаты `ai_h2_shared_validation`.
13. После последовательного успешного Live Scenario `test_guide` и
    `ai_h2_shared_validation` Кодер завершает учёт release в ADB: фиксирует
    результаты приёмки, release manifest, dev deploy и product state, связанные
    с ранее зарегистрированным артефактом.
14. Кодер выпускает полный dev-UEPR и Аудит UEPR. Dev-UEPR доказывает цепочку source → dev artifact → dev deploy → dev-окружение внешнего потребителя → Live Scenario `test_guide`.

### Обязательные действия при новом wheel

Новый wheel — это wheel с новым SHA-256, даже если его строка версии не изменилась. Нельзя считать новый wheel обновлением только по имени файла или версии пакета.

При каждом новом wheel Кодер выполняет один связанный набор действий:

1. создаёт новый `release_id`, фиксирует неизменяемые `source.ref` и `source.revision`, SHA-256, размер, Files ID и версию wheel в release manifest;
2. загружает и регистрирует именно эти байты в ADB до установки; идентификатор зарегистрированного wheel и его SHA сохраняются в manifest;
3. устанавливает зарегистрированный wheel в назначенное окружение внешнего потребителя обычной non-editable установкой. Окружение, которое импортирует исходники, editable-install, другой virtualenv или wheel с иным SHA, не принимается;
4. снимает новое runtime evidence из внешнего потребителя: node, env, `sys.executable`, путь импортируемого модуля, версию, `release_id` и SHA установленного wheel;
5. передаёт candidate wheel внешнему агенту `test_guide`, который выполняет
   зачётный Live Scenario на установленном runtime. В run обязательно совпадают
   node, env, `release_id`, версия, wheel ID и wheel SHA, а `total > 0` и
   `failed = 0`;
6. передаёт тот же набор evidence в `ai_h2_shared_validation`; выпускает новый
   Отчёт Валидации, dev-UEPR и Аудит UEPR. Старые успешные отчёты не подтверждают
   новый SHA;
7. только после успешных пунктов 1–6 обновляет active dev deploy и product state. Если изменился пользовательский контракт, одновременно обновляет Гайд Пользователя и повторяет Guide-Runtime Parity; если изменились назначение, состав или границы продукта, одновременно обновляет Онтологию и Гайд Архитектора.

Исторические wheel, deploy и документы не удаляются: они остаются evidence прежних release. В актуальном product state, active deploy, runtime evidence, Live Scenario, Отчёте Валидации, UEPR и Аудите UEPR должен быть указан один и тот же принимаемый `release_id` и SHA wheel.

### Продвижение и prod-приёмка

15. Архитектор разрешает promote только если dev evidence полностью подтверждены, а dev-UEPR и Аудит UEPR не содержат обязательных `FAIL` или `BLOCKED`.
15а. Сразу после разрешения по п.15 Кодер **один раз** регистрирует те же байты принятого dev-wheel в `env=prod` (`register_wheel`: те же `version`, `sha256`, `size`, `filename`, `owui_file_id`; в `comment` указываются dev `wheel_id`, `release_id` и версии dev-UEPR, Live Scenario, Отчёта Валидации и Аудита UEPR). Эта prod-запись является отметкой «готово к выдаче»; для каждого нового prod-node её повторно не создают.
16. В prod передаются только те же байты wheel из принятого dev release manifest: совпадают release ID, Files ID и SHA-256. Пересборка для prod, wheel с другим SHA и установка wheel, не прошедшего dev-приёмку, запрещены. Prod-запись wheel по п.15а — учётная копия тех же байтов, а не новый артефакт; тождество dev- и prod-записи проверяется только по SHA-256 и Files ID, их `wheel_id` различаются и не сравниваются.
17. Для каждого prod-node Кодер устанавливает wheel из prod-записи по п.15а обычной non-editable установкой в назначенное prod-окружение внешнего потребителя, регистрирует prod deploy на эту prod-запись и фиксирует новое runtime evidence. Runtime evidence доказывает node, env, interpreter, module path, версию, `release_id` и SHA wheel; source/editable import запрещён. Путь interpreter, virtualenv и импортируемого модуля не может лежать в dev source root, dev-workspace или dev-virtualenv.
18. После prod deploy Кодер выпускает prod-UEPR. Source и dev Live Scenario в prod-UEPR имеют `not_applicable`; prod deploy, установленный wheel и фактический prod runtime должны совпадать с принятым dev release manifest.
19. Архитектор проверяет соответствие release manifest, active deploy, runtime evidence и prod-UEPR на каждом prod-node: SHA и Files ID active prod-wheel равны компоненту принятого dev release, этот dev-wheel зарегистрирован и принят до prod deploy, а фактические пути prod runtime не принадлежат dev-контуру. При несовпадении prod не получает GREEN.

## Критерий готовности

Release готов к общему GREEN, когда одновременно выполнены условия:

- фактическая карта продукта определена однозначно;
- все обязательные документы получены по координатам ADB и подтверждены SHA-256 бинарного тела;
- source revision, release manifest, SHA артефакта, deploy и runtime evidence относятся к одному release;
- назначенные внешние потребители в dev и prod импортируют продукт из установленного артефакта;
- при наличии prod его active wheel совпадает по Files ID и SHA-256 с принятым dev-wheel того же release;
- Live Scenario имеет `total > 0`, полный binding и успешный verdict;
- `test_guide` завершил зачётный Live Scenario candidate wheel с полным binding;
- `ai_h2_shared_validation` завершил обязательную независимую валидацию;
- dev-UEPR и Аудит UEPR подтверждают dev-цепочку;
- каждый active prod-node имеет отдельный prod-UEPR;
- prod-запись wheel создана после принятия dev release, и её SHA-256 и Files ID равны принятому dev-wheel;
- evidence каждого шага существует и относится к принимаемому release.

## Evidence и обновление

Кодер `h2_shared` хранит своё evidence каждого шага в
`_tasks/<TASK_ID>/evidence/`. `test_guide` и `ai_h2_shared_validation` хранят
собственное evidence в своих задачах, но передают неизменяемые ссылки и полное
binding release. Финальный отчёт Кодера содержит выполненные действия,
фактические результаты, ссылки на evidence и координаты созданных либо
обновлённых документов.

Новая source revision, новый SHA артефакта, новый deploy, изменение runtime, изменение Live Scenario или изменение пользовательского контракта требуют нового релизного цикла и новых документов соответствующей области.

## История редакций

**v0.2:** уточнены установка wheel в назначенное окружение внешнего потребителя,
роль `test_guide` как зачётного Live Scenario и роль
`ai_h2_shared_validation` как независимой валидации release.

**v0.1:** полная специализированная копия `Гайд ЖЦ ИТ-продукта H2 v0.6`.
Заменены только универсальные роли, неприменимые к библиотечному пакету:
`h2_shared` определён как пакет, зачётный Live Scenario закреплён за
`test_guide`, независимая валидация закреплена за
`ai_h2_shared_validation`, а Гайд Пользователя описан как внешний фасад для
Кодеров и ИИ-Архитекторов. Нормы evidence, неизменяемого source, wheel,
не-editable установки, SHA, UEPR и продвижения в prod сохранены.

§END