|
|
--- |
|
|
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) > ⚠️ **ВНИМАНИЕ:** Данная версия спецификации является..." |
|
|
} |
|
|
``` |
|
|
|
