GitHub Action commited on
Commit
41aa0cd
·
1 Parent(s): b41e1b2

Sync from GitHub with Git LFS

Browse files
Files changed (1) hide show
  1. 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