GitHub Action commited on
Commit ·
41aa0cd
1
Parent(s): b41e1b2
Sync from GitHub with Git LFS
Browse files- docs/HMP-0005.md +138 -0
docs/HMP-0005.md
CHANGED
|
@@ -6397,6 +6397,144 @@ This extension is optional and not required for HMP v5.0 compliance.
|
|
| 6397 |
|
| 6398 |
---
|
| 6399 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6400 |
## Appendix A — JSON Examples
|
| 6401 |
|
| 6402 |
### Appendix A.1 — Minimal Valid HMP v5.0 Container
|
|
|
|
| 6397 |
|
| 6398 |
---
|
| 6399 |
|
| 6400 |
+
### 12.7 Versions Index (optional)
|
| 6401 |
+
|
| 6402 |
+
To optimize navigation across container versions, future versions of HMP may introduce an optional `versions` block.
|
| 6403 |
+
|
| 6404 |
+
The `versions` block acts as a *non-authoritative version index*, providing a compact, signed list of known versions of a given container, including both earlier and later revisions.
|
| 6405 |
+
|
| 6406 |
+
It is intended as a navigation and synchronization accelerator and does not replace the canonical version relationships defined via `related.previous_version`.
|
| 6407 |
+
|
| 6408 |
+
---
|
| 6409 |
+
|
| 6410 |
+
#### 12.7.1 Purpose and Scope
|
| 6411 |
+
|
| 6412 |
+
The primary goals of the `versions` block are:
|
| 6413 |
+
|
| 6414 |
+
- fast discovery of the latest known version of a container;
|
| 6415 |
+
- efficient traversal of version history without full DAG exploration;
|
| 6416 |
+
- reduction of synchronization overhead for lightweight agents and UI clients.
|
| 6417 |
+
|
| 6418 |
+
The block is optional and external to the immutable signed container core.
|
| 6419 |
+
Its presence or absence does not affect container validity.
|
| 6420 |
+
|
| 6421 |
+
---
|
| 6422 |
+
|
| 6423 |
+
#### 12.7.2 Trust Model and Semantics
|
| 6424 |
+
|
| 6425 |
+
The `versions` block follows the same trust and update model as `referenced-by` and `evaluations`:
|
| 6426 |
+
|
| 6427 |
+
- it may be published and updated by any agent;
|
| 6428 |
+
- it is signed by the publishing agent;
|
| 6429 |
+
- it may be incomplete, truncated, or partially outdated;
|
| 6430 |
+
- multiple conflicting `versions` blocks may coexist for the same container.
|
| 6431 |
+
|
| 6432 |
+
The block is non-authoritative and MUST NOT be treated as a source of truth for version ordering or existence.
|
| 6433 |
+
|
| 6434 |
+
---
|
| 6435 |
+
|
| 6436 |
+
#### 12.7.3 Block Structure
|
| 6437 |
+
|
| 6438 |
+
```json
|
| 6439 |
+
"versions": {
|
| 6440 |
+
"links": {
|
| 6441 |
+
"2025-10-28T09:20:00Z": "did:hmp:container:abc175",
|
| 6442 |
+
"2025-10-28T09:12:00Z": "did:hmp:container:abc144",
|
| 6443 |
+
"2025-10-28T09:10:00Z": "did:hmp:container:abc121",
|
| 6444 |
+
"2025-10-28T09:00:00Z": "did:hmp:container:abc101"
|
| 6445 |
+
},
|
| 6446 |
+
"sort": "default",
|
| 6447 |
+
"peer_did": "did:hmp:agent456",
|
| 6448 |
+
"public_key": "BASE58(...)",
|
| 6449 |
+
"sig_algo": "ed25519",
|
| 6450 |
+
"signature": "BASE64URL(...)",
|
| 6451 |
+
"versions_hash": "sha256:abcd..."
|
| 6452 |
+
}
|
| 6453 |
+
```
|
| 6454 |
+
|
| 6455 |
+
The `links` map associates timestamps with container identifiers.
|
| 6456 |
+
By convention, entries are ordered in descending order (most recent first).
|
| 6457 |
+
|
| 6458 |
+
Implementations MAY support alternative ordering or filtering strategies, but any deviation from the default convention SHOULD be explicitly declared in the `sort` entry.
|
| 6459 |
+
|
| 6460 |
+
The `sort` field is informational and does not affect block validity.
|
| 6461 |
+
|
| 6462 |
+
---
|
| 6463 |
+
|
| 6464 |
+
#### 12.7.4 Construction and Maintenance
|
| 6465 |
+
|
| 6466 |
+
Agents may construct or update a `versions` block by:
|
| 6467 |
+
|
| 6468 |
+
- traversing the canonical `related.previous_version` chain;
|
| 6469 |
+
- observing newer versions published after the current container;
|
| 6470 |
+
- merging `versions` blocks received from other agents.
|
| 6471 |
+
|
| 6472 |
+
Agents may:
|
| 6473 |
+
- add newly discovered versions;
|
| 6474 |
+
- prune older entries to limit block size;
|
| 6475 |
+
- re-sign the updated block using their own key.
|
| 6476 |
+
|
| 6477 |
+
No global coordination is required.
|
| 6478 |
+
|
| 6479 |
+
---
|
| 6480 |
+
|
| 6481 |
+
#### 12.7.5 Verification and Consistency
|
| 6482 |
+
|
| 6483 |
+
Verification of a `versions` block consists of:
|
| 6484 |
+
|
| 6485 |
+
- validating the cryptographic signature of the publishing agent;
|
| 6486 |
+
- optionally cross-checking listed entries against canonical version relations when available.
|
| 6487 |
+
|
| 6488 |
+
Inconsistencies or omissions are expected and do not invalidate the block.
|
| 6489 |
+
|
| 6490 |
+
---
|
| 6491 |
+
|
| 6492 |
+
#### 12.7.6 Integration with `container_index`
|
| 6493 |
+
|
| 6494 |
+
To support efficient discovery and synchronization, future extensions to `container_index` MAY include:
|
| 6495 |
+
|
| 6496 |
+
- `versions_hash` — a hash referencing the latest `versions` block published or adopted by the indexing agent for this container, analogous to `referenced-by_hash` and `evaluations_hash`.
|
| 6497 |
+
|
| 6498 |
+
---
|
| 6499 |
+
|
| 6500 |
+
#### 12.7.7 Versions Exchange Container
|
| 6501 |
+
|
| 6502 |
+
To exchange version metadata without transferring the containers themselves, a dedicated `versions_exchange` container MAY be introduced.
|
| 6503 |
+
|
| 6504 |
+
The `versions_exchange` container:
|
| 6505 |
+
- references one or more target containers;
|
| 6506 |
+
- carries a `versions` block;
|
| 6507 |
+
- is used for synchronization, reconciliation, and fast discovery of newer or missing versions.
|
| 6508 |
+
|
| 6509 |
+
```json
|
| 6510 |
+
"payload": {
|
| 6511 |
+
"did:hmp:container:abc123": {
|
| 6512 |
+
"links": {
|
| 6513 |
+
"2025-10-28T09:20:00Z": "did:hmp:container:abc175",
|
| 6514 |
+
"2025-10-28T09:12:00Z": "did:hmp:container:abc144",
|
| 6515 |
+
"2025-10-28T09:10:00Z": "did:hmp:container:abc121",
|
| 6516 |
+
"2025-10-28T09:00:00Z": "did:hmp:container:abc101"
|
| 6517 |
+
},
|
| 6518 |
+
"sort": "default"
|
| 6519 |
+
}
|
| 6520 |
+
}
|
| 6521 |
+
```
|
| 6522 |
+
|
| 6523 |
+
The payload MAY contain version metadata for multiple containers, allowing batch synchronization and reducing protocol overhead.
|
| 6524 |
+
|
| 6525 |
+
---
|
| 6526 |
+
|
| 6527 |
+
#### 12.7.8 Design Notes
|
| 6528 |
+
|
| 6529 |
+
The `versions` block is intentionally non-canonical.
|
| 6530 |
+
|
| 6531 |
+
It improves performance and usability while preserving HMP’s core principles:
|
| 6532 |
+
- immutability of signed containers;
|
| 6533 |
+
- absence of a globally authoritative state;
|
| 6534 |
+
- tolerance for partial and divergent knowledge.
|
| 6535 |
+
|
| 6536 |
+
---
|
| 6537 |
+
|
| 6538 |
## Appendix A — JSON Examples
|
| 6539 |
|
| 6540 |
### Appendix A.1 — Minimal Valid HMP v5.0 Container
|