structured_md/docs/HMP-container-spec.md

---
title: 🧩 HMP Container Specification (v1.2-draft)
description: '> ⚠️ **ВНИМАНИЕ:** Данная версия спецификации является черновиком для
  [HMP-0005.md](HMP-0005.md). > > После утверждения пятой версии протокола будет зафиксирована
  как стабильная `v1.2`.  ## 1. Назначе...'
type: Article
tags:
- REPL
- Ethics
- Mesh
- JSON
- HMP
- Agent
---

# 🧩 HMP Container Specification (v1.2-draft)

> ⚠️ **ВНИМАНИЕ:** Данная версия спецификации является черновиком для [HMP-0005.md](HMP-0005.md).
>
> После утверждения пятой версии протокола будет зафиксирована как стабильная `v1.2`.

## 1. Назначение

Документ описывает универсальный формат **контейнера HMP**, применяемый для передачи и хранения всех типов данных внутри сети **HyperCortex Mesh Protocol (HMP)**.  
Контейнеры служат стандартной оболочкой для сообщений, целей, репутационных профилей, консенсусных голосований, писем и других сущностей.

Единая структура контейнера обеспечивает:

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


---

## 2. Общая структура контейнера

```json
{
  "hmp_container": {
    "version": "1.2",
    "class": "goal" | "reputation" | "knowledge_node" | "ethics_case" | "protocol_goal" | ...,
    "class_version": "1.0",
    "class_id": "goal-v1.0",
    "container_did": "did:hmp:container:abc123",
    "schema": "https://mesh.hypercortex.ai/schemas/container-v1.json",
    "sender_did": "did:hmp:agent123",
    "public_key": "BASE58(...)",
    "recipient": ["did:hmp:agent456", "did:hmp:agent789"],
    "broadcast": false,
    "network": "",
    "tags": ["research", "collaboration"],
    "timestamp": "2025-10-10T15:32:00Z",
    "ttl": "2025-11-10T00:00:00Z",
    "sig_algo": "ed25519",
    "signature": "BASE64URL(...)",
    "compression": "zstd",
    "payload_type": "json",
    "payload_hash": "sha256:abcd...",
    "payload": {
      /* Содержимое зависит от class */
    },
    "related": {
      "previous_version": "did:hmp:container:abc122",
      "in_reply_to": "did:hmp:container:msg-77",
      "see_also": ["did:hmp:container:ctx-31", "did:hmp:container:goal-953"]
    },
    "relations": [
      { "type": "depends_on", "target": "did:hmp:container:goal-953" }
    ],
    "magnet_uri": "magnet:?xt=urn:sha256:abcd1234..."
  },
  "referenced-by": ["did:hmp:container:ctx-34", "did:hmp:container:goal-945"]
}
```

---

## 3. Обязательные поля

| Поле            | Тип      | Назначение                                                                                        |
| --------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `version`       | string   | Версия спецификации контейнера                                                                    |
| `class`         | string   | Тип содержимого (`goal`, `reputation`, `knowledge_node`, `ethics_case`, `protocol_goal` и т.п.)   |
| `class_version` | string   | Версия конкретного класса                                                                         |
| `class_id`      | string   | Уникальный идентификатор класса (обычно формируется как `<class>_v<class_version>`)               |
| `container_did` | string   | DID самого контейнера (например, `did:hmp:container:abc123`)                                      |
| `schema`        | string   | Ссылка на JSON Schema, по которой валидируется контейнер                                          |
| `sender_did`    | string   | DID-идентификатор отправителя                                                                     |
| `timestamp`     | datetime | Время создания контейнера                                                                         |
| `payload_hash`  | string   | Хэш распакованной полезной нагрузки                                                               |
| `sig_algo`      | string   | Алгоритм цифровой подписи (по умолчанию `ed25519`)                                                |
| `signature`     | string   | Цифровая подпись контейнера                                                                       |
| `payload_type`  | string   | Тип данных полезной нагрузки (`json`, `binary`, `mixed`)                                          |
| `payload`       | object   | Основное содержимое контейнера                                                                    |

---

## 4. Опциональные поля

| Поле                       | Тип           | Описание                                                                     |
| -------------------------- | ------------- | ---------------------------------------------------------------------------- |
| `recipient`                | array(string) | Один или несколько DID-адресатов                                             |
| `broadcast`                | bool          | Флаг широковещательной рассылки (если `true`, поле `recipient` игнорируется) |
| `tags`                     | array(string) | Тематические теги контейнера                                                 |
| `ttl`                      | datetime      | Срок актуальности (контейнер не передаётся после истечения)                  |
| `public_key`               | string        | Публичный ключ отправителя, если нет глобальной привязки к DID               |
| `compression`              | string        | Алгоритм сжатия полезной нагрузки (`zstd`, `gzip`)                           |
| `magnet_uri`               | string        | Magnet-ссылка на оригинал или зеркала контейнера                             |
| `related.previous_version` | string        | Ссылка на предыдущую версию контейнера                                       |
| `related.in_reply_to`      | string        | Контейнер, на который дан ответ                                              |
| `related.see_also`         | array(string) | Список связанных контейнеров для дополнительного контекста                   |
| `relations`                | array(object) | Семантические связи в виде пар `{ "type": "...", "target": "..." }`          |
| `encryption_algo`          | string        | Алгоритм шифрования полезной нагрузки                                        |
| `key_recipient`            | string        | DID получателя, для которого зашифрованы данные                              |
| `payload_type`             | string        | Может содержать сложные типы, например `encrypted+zstd+json`                 |
| `referenced-by`            | array(string) | Неподписываемое поле, формируемое агентом на основе полученных ссылок. Содержит список DID-контейнеров, которые ссылаются на данный. Может дополняться, поэтому требует проверки; используется для локальной навигации |
| `network`       | `string`        | Указывает локальную область распространения контейнера: `"localhost"`, `"lan:<subnet>"`. Пустая строка (`""`) означает интернет/глобальное распространение. Если задано, `broadcast` автоматически считается `false`. |

---

## 5. Структура полезной нагрузки (`payload`)

Полезная нагрузка содержит содержательные данные контейнера.
Тип и структура зависят от поля `class`.

Рекомендуемый формат описания полей:

```
- key: имя поля
  type: тип значения (JSON | TXT | BOOL | INT | FLOAT | ARRAY)
  description: краткое назначение
  required: true/false
  value: пример значения
```

**Пример:**

```
- key: "title"
  type: "TXT"
  required: true
  description: "Название цели"
  value: "Improve local agent discovery"

- key: "priority"
  type: "FLOAT"
  required: false
  description: "Важность задачи"
  value: 0.82

- key: "dependencies"
  type: "JSON"
  required: false
  description: "Список зависимостей других целей"
  value: ["goal-953", "goal-960"]
```

---

## 6. Подпись контейнера

1. Подписывается **весь JSON-объект `hmp_container`**, кроме поля `signature`.
2. По умолчанию используется алгоритм Ed25519.
3. При наличии поля `public_key` проверка подписи может выполняться без обращения к глобальной базе DID.
4. Агент, получивший контейнер, обязан сверить открытый ключ с известными данными DID-узлов, чтобы исключить подмену ключа.

   * Если агент не знает отправителя — он инициирует опрос соседних узлов о соответствии `sender_did → public_key`.

---

## 7. Сжатие (`compression`)

1. Поле `compression` указывает алгоритм сжатия полезной нагрузки.
2. Сжатие выполняется **до вычисления `payload_hash` и подписи**.
3. Для верификации контейнера полезная нагрузка должна быть распакована, затем вычисляется хэш и сверяется с `payload_hash`.

---

## 8. Шифрование (`encryption_algo`)

1. Если контейнер предназначен для конкретных получателей (`recipient`), допускается **гибридное шифрование** полезной нагрузки.
2. Алгоритм указывается в поле `encryption_algo`. Рекомендуемые значения:
   - `x25519-chacha20poly1305`
   - `rsa-oaep-sha256`
3. Порядок операций при создании зашифрованного контейнера:
   1. Сформировать `payload` (JSON, бинарные данные и т.д.)
   2. Сжать (`compression`)
   3. Зашифровать открытым ключом получателя (`public_key`)
   4. Вычислить `payload_hash` по зашифрованным данным
   5. Подписать контейнер (`signature`)
4. Для верификации структуры контейнера не требуется расшифровка,  
   но для проверки `payload_hash` и подписи — используется зашифрованная форма полезной нагрузки.
5. Поля:
   | Поле | Тип | Назначение |
   |------|-----|------------|
   | `encryption_algo` | string | Алгоритм шифрования |
   | `key_recipient` | string | DID получателя, для которого зашифрованы данные |
   | `payload_type` | string | Рекомендуется использовать префикс `encrypted+`, например `encrypted+zstd+json` |

---

## 9. Верификация контейнера

1. Проверить наличие обязательных полей.
2. Проверить корректность `timestamp` (не в будущем).
3. Если указано `ttl` — контейнер считается неактуальным по истечении этого времени.
4. Проверить хэш: вычислить `sha256(payload)` и сравнить с `payload_hash`.
5. Проверить цифровую подпись по алгоритму Ed25519 (если иное не указано в `sig_algo`).
6. Проверить допустимость схемы (`class` должен быть известным типом).
   * Для совместимости: если агент не распознаёт указанный `class`, но контейнер валиден по [базовой схеме](https://github.com/kagvi13/HMP/tree/main/docs/schemas/container-v1.2.json), он обязан сохранить и ретранслировать контейнер (режим **store & forward**). 
7. Рекомендуется периодически попытаться найти контейнеры, где текущий указан как `previous_version` — для обнаружения возможных обновлений.
8. При конфликте нескольких версий — действительной считается та, что получила подтверждение большинства доверенных узлов (консенсус на уровне DHT).

---

## 10. Контейнер как универсальное сообщение

Любой контейнер может выступать контекстом (`in_reply_to`) для другого контейнера.
Это позволяет использовать единую структуру для **обсуждений**, **голосований**, **писем**, **гипотез**, **аргументов** и других форм коммуникации.

Цепочки `in_reply_to` образуют **диалектическое дерево рассуждений**, в котором каждая ветвь отражает развитие мысли, уточнение позиции или контраргумент.
Таким образом, обсуждения и консенсусы в HMP имеют не линейную, а **многоуровневую и саморазвивающуюся структуру**.

> Таким образом, **все взаимодействия между агентами в HMP** представляют собой взаимосвязанную сеть контейнеров, формирующую **когнитивный граф рассуждений**.

---

## 11. Версионирование и преемственность

Контейнеры поддерживают эволюцию данных через поле `related.previous_version`.
Это позволяет отслеживать происхождение, обновления и смысловую преемственность.

* Потомок признаётся действительным, если его подпись совпадает с DID автора предыдущей версии.
* При расхождении подписи допустимо признание потомка легитимным при подтверждении не менее **⅔ доверенных узлов сети**.
  В этом случае право на дальнейшее развитие идеи фактически переходит сообществу — как форма коллективного владения смыслом.
* Агенты обязаны хранить как минимум одну предыдущую версию контейнера для совместимости и проверки целостной цепочки.
* Один контейнер может иметь несколько потомков (альтернативных ветвей), различающихся по дате или авторству; при необходимости приоритет определяется по консенсусу сети.
  Такие ветви рассматриваются как **смысловые форки** — параллельные линии развития одной идеи, существующие в рамках общего когнитивного графа.

---

## 12. TTL и актуальность

Поле `ttl` задаёт срок актуальности контейнера (например, для сообщений `DISCOVERY`).
Если `ttl` отсутствует — контейнер считается действительным **до появления новой версии**, в которой данный контейнер указан как `previous_version`.

По истечении срока действия контейнер сохраняется в архиве, но **не подлежит ретрансляции** в активной сети.

---

## 13. Расширяемость

* Разрешается добавление новых полей, не конфликтующих с существующими именами.
* Контейнеры старших версий должны оставаться читаемыми узлами, поддерживающими младшие версии.
* При появлении новых классов (`class`) они регистрируются в публичном реестре схем (`/schemas/container-types/`).
* Для контейнеров, описывающих **спецификации протоколов**, рекомендуется использовать префикс `protocol_`, за которым следует область применения (например, `protocol_goal`, `protocol_reputation`, `protocol_mesh_handshake` и т.п.).

---

## 14. Виртуальные обратные ссылки (`referenced-by`)

Каждый контейнер может иметь **дополнительный блок** `referenced-by`, указывающий, **какие другие контейнеры ссылаются на него**.  
Этот блок не является частью оригинального контейнера и передаётся как "прилепленный" (обособленный) атрибут.

### 14.1 Общие принципы

* **Не подписывается** — `referenced-by` не включён в подпись контейнера и не влияет на его целостность.
* **Формируется и обновляется локально агентом** при анализе ссылок (`in_reply_to`, `see_also`, `relations`) в других контейнерах.
* **Может передаваться вместе с контейнером** в качестве дополнительного блока данных, который другие агенты вправе проверить и при необходимости скорректировать.
* **Подлежит проверке** — агент должен сверить, действительно ли каждый контейнер из `referenced-by` содержит ссылку на данный контейнер.
* **Тип данных:** массив идентификаторов контейнеров (`array<string>`), где каждый элемент представляет собой UUID (`container_id`).  
  Пример:

  ```json
  "referenced-by": ["C2", "C3", "C4"]
  ```

> Контейнер [C1] остаётся неизменным.
> Блок referenced-by не является частью контейнера, а представляет собой **вспомогательный вычисляемый атрибут**, формируемый и поддерживаемый агентом на основании анализа входящих ссылок.

### 14.2 Принцип работы

1. Агент получает контейнер `[C1]` и сопоставляет его с уже известными контейнерами `[C2..Cn]`, которые ссылаются на `[C1]`.
2. Формируется или обновляется локальный блок:

```text
referenced-by = [C2, C3, ..., Cn]
```

3. При получении `[C1]` от других узлов с другим набором ссылок, либо новых контейнеров, которые ссылаются на `[C1]`, список обновляется:
   * новые ссылки добавляются после проверки;
   * недействительные ссылки удаляются.

4. Если обнаружено несоответствие (например, контейнер заявляет ссылку, которой нет), агент может:
   * удалить ссылку локально;
   * **по желанию** отправить уведомление узлу-источнику: `"проверь и поправь"` (такое сообщение также подлежит проверке).

### 14.3 Пример

| Агент | received `[C1]` references |
| ----- | -------------------------- |
| A     | [C2], [C3]                 |
| B     | [C4], [C5]                 |
| C     | [C6], [C7]                 |

Агент D агрегирует все ссылки:

```text
referenced-by = [C2, C3, C4, C5, C6, C7]
```

После проверки выясняется, что `[C7]` не ссылается на `[C1]`, поэтому итоговый локальный блок:

```text
referenced-by = [C2, C3, C4, C5, C6]
```

### 14.4 Применение

* Позволяет строить локальные графы обсуждений, голосований и обновлений.
* Ускоряет поиск связанных контейнеров без постоянного запроса всей истории.
* Полезно для анализа **ConsensusResult**, ветвлений обновлений и любых ссылочных цепочек.
* Может использоваться для визуализации сетевых связей между контейнерами.
* Агент периодически пересчитывает `referenced-by`, используя локальные данные или запрашивая новые контейнеры у соседей.

---

## 15. Применение полей `network` и `broadcast`

Для управления распространением контейнеров в локальной и глобальной среде введено поле `network`. Оно позволяет ограничивать область доставки контейнера и определяет, какие методы передачи должны использоваться агентом.

### 15.1 Общие правила

* Если `network` не пустое, контейнер предназначен для локальной среды и **не должен передаваться в глобальный Mesh**.  
  В этом случае поле `broadcast` автоматически считается `false`, а `recipient` — пустым массивом (`[]`).
* Если `network` пустое (`""`), контейнер разрешено транслировать в Mesh, используя стандартные DID-адреса и механизмы доставки.

### 15.2 Возможные значения `network`

| Значение                  | Описание                                                                                 |
| ------------------------- | --------------------------------------------------------------------------------------- |
| `""`                       | Контейнер разрешено транслировать в глобальный Mesh.                                     |
| `"localhost"`              | Контейнер предназначен для доставки только другим агентам на том же хосте.             |
| `"lan:192.168.0.0/24"`    | Контейнер предназначен для доставки агентам в указанной локальной подсети.             |

> ⚠️ Примечание: Когда контейнер ограничен `network` (например, `localhost` или `lan:*`), агенты распространяют его с использованием **локальных механизмов обнаружения** — IPC, UDP broadcast, multicast или прямых TCP-соединений.  
> Это необходимо, потому что DID-адреса других агентов в локальной сети могут быть ещё неизвестны.  

### 15.3 Примеры

1. **Глобальная Mesh-доставка:**

```json
{
  "broadcast": true,
  "network": "",
  "recipient": []
}
```

Контейнер может распространяться по всему Mesh без ограничений.

2. **Локальный хост:**

```json
{
  "broadcast": false,
  "network": "localhost",
  "recipient": []
}
```

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

3. **Подсеть LAN:**

```json
{
  "broadcast": false,
  "network": "lan:192.168.0.0/24",
  "recipient": []
}
```

Контейнер предназначен для агентов в подсети `192.168.0.0/24`. Доставка осуществляется через локальные сетевые механизмы (UDP discovery, broadcast/multicast).

### 15.4 Особенности

* Поле `network` определяет **область действия контейнера**, тогда как `broadcast` указывает, разрешена ли широковещательная рассылка в рамках выбранной сети.
* При необходимости агент может создавать **несколько контейнеров** для разных подсетей, если у него несколько LAN-интерфейсов или он работает в изолированных сегментах сети.
* Контейнеры, предназначенные для локальных сетей, остаются **совместимыми с общей Mesh-инфраструктурой**, но доставка ограничена локальными каналами.
* Хотя механизм был разработан прежде всего для **поиска и синхронизации локальных узлов**, он также может использоваться для **обмена сообщениями внутри домашней или корпоративной среды**, где важно, чтобы контейнеры **не покидали локальную сеть** и не передавались в Интернет.


---
> ⚡ [AI friendly version docs (structured_md)](../index.md)


```json
{
  "@context": "https://schema.org",
  "@type": "Article",
  "name": "🧩 HMP Container Specification (v1.2-draft)",
  "description": "# 🧩 HMP Container Specification (v1.2-draft)  > ⚠️ **ВНИМАНИЕ:** Данная версия спецификации является..."
}
```